Enforce `starintel-biz` entitlements and quotas in StarIntel authorization #125

New issue

Open

opened 2026-08-25 10:55:06 +00:00 by lost-rob0t · 1 comment

lost-rob0t commented

2026-08-25 10:55:06 +00:00

(Migrated from github.com)

Goal

Integrate the entitlement projection from starintel-labs/starintel-biz #4 into starintel-server so paid/trial/grace/suspended access is enforced through one narrow authorization boundary without coupling server code to Stripe or crypto providers.

Dependencies

starintel-labs/starintel-biz #1 — canonical billing state
starintel-labs/starintel-biz #4 — entitlement/quota projection
server #124 — external-service integration registry/capability discovery

Requirements

Treat starintel-biz entitlements as an input to authorization, not as a replacement for identity/scopes/tenant checks.
Resolve effective entitlements by authenticated account/tenant identity through a narrowly-scoped server-side adapter registered via #124.
Never expose Stripe/crypto provider IDs, payment details, billing secrets, or private billing service endpoints through public capabilities/OpenAPI/client manifests.
Define precedence explicitly: authentication + authorization scope + tenant/dataset policy + entitlement/plan checks must all pass where applicable.
Add capability/feature gates for paid features without hard-coding commercial plan names into unrelated request handlers.
Enforce quantitative quotas with deterministic error semantics and machine-readable remaining/limit metadata only where safe to reveal to the caller.
Cache entitlement data only with bounded TTL/revision invalidation; stale cache must not resurrect revoked access beyond the documented maximum window.
Fail closed for privileged/paid operations when entitlement state cannot be validated, while preserving explicitly public/free features.
Distinguish upstream billing unavailable, account not entitled, quota exceeded, suspended/revoked, and malformed integration state.
Emit structured authz/billing-integration events through #121 without logging customer payment data.

Capability discovery

Public /api/v1/capabilities may advertise that a feature exists and whether authentication/paid entitlement is generally required, but must not disclose an individual account's private billing state. Authenticated account-specific entitlement/status endpoints, if needed, require an explicit protected contract.

Tests / acceptance

entitled account succeeds; non-entitled account gets stable denial
OAuth/API scope alone cannot bypass missing entitlement
entitlement alone cannot bypass missing auth scope/tenant authority
stale/revoked revision cannot restore access
billing adapter timeout/unavailable behavior follows fail-closed policy for paid operations
quota boundary and concurrent-use fixtures behave deterministically
public/free endpoints remain available when billing is unavailable
no provider/payment/private endpoint leakage in public capability contracts
exact-head server unit/integration/contract suites pass

Execution mode — AUTO-RAGE

Run the full ADARD/ADADR loop autonomously: inspect current authorization/capability/integration architecture plus biz #4 and server #124; design and record entitlement precedence/cache/failure semantics; adversarial review + privilege-bypass/stale-cache/account-isolation threat model; autonomous decision gate; TDD-first implementation; exact-head service-backed verification; push a focused branch and open/update a PR targeting master. Stop only for a genuinely unresolved requirement/security blocker, inaccessible dependency, or failed verification gate. Do not ask for approval between phases.

## Goal Integrate the entitlement projection from `starintel-labs/starintel-biz` #4 into `starintel-server` so paid/trial/grace/suspended access is enforced through one narrow authorization boundary without coupling server code to Stripe or crypto providers. ## Dependencies - `starintel-labs/starintel-biz` #1 — canonical billing state - `starintel-labs/starintel-biz` #4 — entitlement/quota projection - server #124 — external-service integration registry/capability discovery ## Requirements - Treat `starintel-biz` entitlements as an input to authorization, not as a replacement for identity/scopes/tenant checks. - Resolve effective entitlements by authenticated account/tenant identity through a narrowly-scoped server-side adapter registered via #124. - Never expose Stripe/crypto provider IDs, payment details, billing secrets, or private billing service endpoints through public capabilities/OpenAPI/client manifests. - Define precedence explicitly: authentication + authorization scope + tenant/dataset policy + entitlement/plan checks must all pass where applicable. - Add capability/feature gates for paid features without hard-coding commercial plan names into unrelated request handlers. - Enforce quantitative quotas with deterministic error semantics and machine-readable remaining/limit metadata only where safe to reveal to the caller. - Cache entitlement data only with bounded TTL/revision invalidation; stale cache must not resurrect revoked access beyond the documented maximum window. - Fail closed for privileged/paid operations when entitlement state cannot be validated, while preserving explicitly public/free features. - Distinguish upstream billing unavailable, account not entitled, quota exceeded, suspended/revoked, and malformed integration state. - Emit structured authz/billing-integration events through #121 without logging customer payment data. ## Capability discovery Public `/api/v1/capabilities` may advertise that a feature exists and whether authentication/paid entitlement is generally required, but must not disclose an individual account's private billing state. Authenticated account-specific entitlement/status endpoints, if needed, require an explicit protected contract. ## Tests / acceptance - entitled account succeeds; non-entitled account gets stable denial - OAuth/API scope alone cannot bypass missing entitlement - entitlement alone cannot bypass missing auth scope/tenant authority - stale/revoked revision cannot restore access - billing adapter timeout/unavailable behavior follows fail-closed policy for paid operations - quota boundary and concurrent-use fixtures behave deterministically - public/free endpoints remain available when billing is unavailable - no provider/payment/private endpoint leakage in public capability contracts - exact-head server unit/integration/contract suites pass ## Execution mode — AUTO-RAGE Run the full ADARD/ADADR loop autonomously: inspect current authorization/capability/integration architecture plus biz #4 and server #124; design and record entitlement precedence/cache/failure semantics; adversarial review + privilege-bypass/stale-cache/account-isolation threat model; autonomous decision gate; TDD-first implementation; exact-head service-backed verification; push a focused branch and open/update a PR targeting `master`. Stop only for a genuinely unresolved requirement/security blocker, inaccessible dependency, or failed verification gate. Do not ask for approval between phases.

lost-rob0t commented

2026-08-25 10:59:05 +00:00

(Migrated from github.com)

The billing/entitlement architecture and operator documentation is tracked in starintel-labs/starintel-biz#5, including the billing-state -> entitlement -> StarIntel authorization boundary. Keep server-side behavior and public/private capability documentation synchronized with that contract.

The billing/entitlement architecture and operator documentation is tracked in `starintel-labs/starintel-biz#5`, including the billing-state -> entitlement -> StarIntel authorization boundary. Keep server-side behavior and public/private capability documentation synchronized with that contract.