Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
3d427ee
feat(auth): add opt-in SAML federation through a trusted broker
ALikesToCode Oct 9, 2026
5953994
feat(billing): add opt-in Stripe top-ups credited only from verified …
ALikesToCode Oct 9, 2026
248addd
feat(provisioning): add opt-in SCIM 2.0 user and group provisioning
ALikesToCode Oct 9, 2026
4d362a7
feat(credits): add an opt-in gateway credits ledger
ALikesToCode Oct 9, 2026
649f8f9
feat(governance): add opt-in hierarchical grants, budgets and attribu…
ALikesToCode Oct 9, 2026
048e2ff
feat(tenants): add opt-in organisations, teams and verified workspaces
ALikesToCode Oct 9, 2026
389f1c6
Merge branch 'feat/tenant-hierarchy' into feat/tenant-governance
ALikesToCode Oct 9, 2026
5083e2f
Merge branch 'feat/tenant-governance' into feat/saml-federation
ALikesToCode Oct 9, 2026
20f68a1
Merge branch 'feat/saml-federation' into feat/scim-provisioning
ALikesToCode Oct 9, 2026
7538aec
Merge branch 'feat/scim-provisioning' into feat/credits-ledger
ALikesToCode Oct 9, 2026
81629b4
Merge branch 'feat/credits-ledger' into feat/payment-billing
ALikesToCode Oct 9, 2026
0cfdf92
test(d1): start the integration Worker with the production nodejs_com…
ALikesToCode Oct 9, 2026
764de2a
Merge branch 'feat/payment-billing' into integrate/gateway-waves-1-7
ALikesToCode Oct 9, 2026
7559c87
Merge branch 'feat/tenant-hierarchy' into integrate/gateway-waves-1-7
ALikesToCode Oct 9, 2026
de9a471
Merge branch 'feat/tenant-hierarchy' into feat/tenant-governance
ALikesToCode Oct 9, 2026
0c9d36f
Merge branch 'feat/tenant-governance' into feat/saml-federation
ALikesToCode Oct 9, 2026
606bba8
Merge branch 'feat/saml-federation' into feat/scim-provisioning
ALikesToCode Oct 9, 2026
3a2a109
Merge branch 'feat/scim-provisioning' into feat/credits-ledger
ALikesToCode Oct 9, 2026
cc933b4
Merge branch 'feat/credits-ledger' into feat/payment-billing
ALikesToCode Oct 9, 2026
cee6ade
Merge branch 'feat/payment-billing' into integrate/gateway-waves-1-7
ALikesToCode Oct 9, 2026
83e9193
feat(gateway): wire the Wave 7 enterprise features together
ALikesToCode Oct 9, 2026
df64359
Merge branch 'integrate/gateway-waves-1-6' into integrate/gateway-wav…
ALikesToCode Oct 9, 2026
e83bec4
Merge branch 'integrate/gateway-waves-1-6' into integrate/gateway-wav…
ALikesToCode Oct 9, 2026
4510992
fix(ci): run the credits parity check with the CI interpreter
ALikesToCode Oct 9, 2026
27c5f1d
Merge branch 'integrate/gateway-waves-1-6' into integrate/gateway-wav…
ALikesToCode Oct 9, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,12 @@ store data name the D1 migration to apply before enabling them.
- [Context-leak canary tokens](docs/context-canary.md): `CONTEXT_CANARY_MODE=log` or `block` with `CONTEXT_CANARY_POLICY_JSON` detects opted-in disclosure of a request-specific marker. It does not claim complete leak detection.
- [Signed usage receipts](docs/usage-receipts.md): `USAGE_RECEIPTS_ENABLED` with a reviewed Ed25519 key writes a hash-chained receipt per settled usage event that its owner can fetch and verify, keeping unknown cost explicit (migration 0032).
- [Enterprise integration contracts](docs/enterprise-contracts.md): typed identity, tenancy, quota and credit boundaries for later organisation, SSO and payment modules. `ENTERPRISE_PREVIEW_ENABLED` shows a read-only administrator preview; nothing else activates.
- [Organisations and teams](docs/tenant-hierarchy.md): `ORGANISATIONS_ENABLED` adds optional organisation and team membership with a workspace identity the server verifies, and keeps each workspace's caches, idempotency, hosted state and usage separate (migration 0033).
- [Tenant governance](docs/tenant-governance.md): `TENANT_GOVERNANCE_ENABLED` intersects organisation, team and key grants, reserves organisation and team budgets together with the key's, and attributes usage to the verified workspace (migration 0034).
- [SAML federation](docs/saml-federation.md): `SAML_ENABLED` with `SAML_BROKER_URL`, `SAML_TRUST_CONFIG_JSON` and `SAML_CALLBACK_URL` signs gateway accounts in to the dashboard through an explicitly trusted SAML broker, only for subjects an administrator has linked to an account (migration 0035).
- [SCIM provisioning](docs/scim-provisioning.md): `SCIM_ENABLED` with `SCIM_TRUST_CONFIG_JSON` provisions scoped users and organisation teams through SCIM 2.0; it needs D1 storage and security revision sync (migration 0036).
- [Gateway credits](docs/credits-ledger.md): `CREDITS_ENABLED` keeps an append-only ledger of credits, holds and settlements, separate from usage estimates. `CREDITS_ENFORCEMENT=funded` or `all` makes requests reserve and settle credits (migration 0037).
- [Top-ups](docs/payment-billing.md): `PAYMENTS_ENABLED` with `PAYMENT_PROCESSOR_CONFIG_JSON` and `PAYMENT_WEBHOOK_KEY_REF` creates Stripe Checkout top-ups and credits explicit USD payments only from verified, idempotent webhooks (migration 0038).

## Setup

Expand Down
5 changes: 4 additions & 1 deletion app.py
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@
)
from routes.config_snapshots import register_config_snapshot_routes
from routes.enterprise_preview import register_enterprise_preview_routes
from routes.tenants import register_tenant_routes
from routes.core import register_core_routes
from routes.dashboard_security import register_dashboard_security_routes
from routes.intelligence_media import register_intelligence_media_routes
Expand All @@ -42,7 +43,7 @@
from services.cache_service import CacheService
from services.image_relay_catalog import ImageRelayCatalogRefresh
from services.provider_catalog_refresh import ProviderCatalogAutoRefresh
from services.gateway_extensions import gateway_callbacks, register_gateway_extensions
from services.gateway_extensions import gateway_callbacks, register_gateway_extensions, register_enterprise_features
from services.metrics_service import MetricsService
from services.proxy_service import ProxyService
from services import usage_ledger
Expand Down Expand Up @@ -147,6 +148,8 @@ def create_app() -> Flask:
register_workbench_routes(app)
register_config_snapshot_routes(app)
register_enterprise_preview_routes(app)
register_tenant_routes(app, csrf=csrf)
register_enterprise_features(app, csrf)
register_shadow_eval_routes(app, csrf, AuthService, MetricsService, ProxyService)
register_knowledge_routes(app, csrf)
register_gateway_mcp_routes(app, csrf)
Expand Down
211 changes: 211 additions & 0 deletions docs/credits-ledger.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,211 @@
# Gateway credits

Credits are disabled unless `CREDITS_ENABLED=true`. Empty values use the defaults.
`CREDITS_CURRENCY` defaults to USD; other currencies disable credits. Invalid
settings log one warning without their values. Disabled routes return 404.

Apply the additive credits migration to the chosen database before enabling the
feature. It creates `credits_balances`, `credits_entries` and `credits_audit`.
Existing usage records are retained. The runtime does not apply migrations.
Missing tables or required columns return JSON 503 with `credits_unavailable`;
credit admission then stops before provider dispatch. Storage outages have the
same result, without retrying writes or switching to another balance authority.
The local store uses the existing `USAGE_DB_PATH`; the Container uses the private
D1 transport when `INTELLIGENCE_STORAGE_BACKEND=d1`.

Amounts are integer micro-USD, bounded to ±1,000,000,000,000,000. One USD is
1,000,000 micro-USD. Fractional amounts, booleans and overflow are rejected,
without rounding or conversion from usage estimates. Revisions have the same
nonnegative bound. No account receives automatic credit, bonus or top-up.

The ledger stores `credit`, `reserve`, `commit`, `release`, `adjust` and
`compensate` events. Only the materialized balance row changes. Balance is the
sum of credits and adjustments, minus committed costs, plus compensations.
Held credit is the sum of open estimates; available credit is balance minus
held. Every write checks the balance revision. New reservations and negative
adjustments must not make available credit negative. Each owner has its own
operation ID namespace. Repeating an identical
operation, including its original revision, returns its original entry. Reusing
the ID with different content returns 409 `credits_conflict`.

Use a distinct `scoped_id` for each provider attempt, including hedges, shadows
and batch items, and a distinct operation ID for each transition. Reserving an
estimate holds credit. Committing the actual integer cost removes that attempt's
whole hold and debits only the actual cost. The commit entry's `held_delta`
records the released hold atomically. An explicit release removes a hold without
a charge; its amount must match the original estimate. Terminal attempts cannot
reopen.

A commit records the actual cost even when it exceeds the hold and available
credit, and closes only its own hold. Balance and available credit can become
negative within the integer bounds. New reservations are refused while available
credit is zero or negative, until credits or positive adjustments cover the
shortfall and leave available credit for admission.

Unknown reconciliation appends a linked reserve marker with zero balance and
hold deltas. Its zero amount is a marker, not a zero-cost settlement. The original
hold remains indefinitely; there is no automatic expiry. A later known cost can
settle it. A compensation references an original credit, adjustment or commit
operation and applies the exact inverse balance delta once. It never edits the
original entry, reopens a hold or modifies a usage receipt.

Gateway prices are an explicit operator tariff, separate from provider usage
estimates and invoices. `register_credit_authority(store, tariff=...)` and
`registerCreditAuthority(db, {tariff, env})` implement the enterprise
`CreditAuthority` contract. The tariff callback receives `(operation, phase)`;
it must verify the operation's integer amount against the reviewed tariff and
return that tariff's integer revision. Return `None`/`null` for unpriced admission
or unknown reconciliation. Unpriced reserve or commit raises `AuthorityDenied`
with `credits_unpriced`; insufficient funds raise `credits_insufficient`.
Registration performs no storage writes. The authority also checks the feature
flag before evaluating prices or touching storage.

For every authority transition, `AuthorityOperation.revision` must be the owner's
current balance revision. On 412 `credits_revision_mismatch`, re-read that revision
and retry with the same operation ID and unchanged cost and attempt fields, using
a bounded retry limit. A rejected revision writes nothing, and operation IDs make
retries idempotent. After a successful write, replay the original revision to
retrieve its entry; reusing the ID with changed content is a conflict.

`GET /v1/credits` requires a gateway key with `models` scope. It reads only the
authenticated owner; query parameters cannot choose another owner. Verified
tenant context produces a stable organisation/team/principal namespace;
legacy principals keep their existing namespace. The response is:

```text
{currency: "USD", balance_microusd: 100, held_microusd: 60,
available_microusd: 40, entries: [...], next_cursor: null}
```

Use `?limit=20&cursor=0` for pagination. The limit is 1–100 (default 100); cursors
are nonnegative revision strings. Follow `next_cursor` until it is null. Pages
are ordered by increasing ledger revision. All responses use `Cache-Control:
no-store`. Reads and writes include an `ETag` containing the balance revision.
Entries contain operation IDs, integer deltas, attempt/reference IDs and tariff
revisions. They omit actor and adjustment reason. No prompts, completions,
provider credentials or payment details are collected.

`GET /admin/credits/<owner>` requires an administrator dashboard session and
includes the current revision. URL-encode tenant owner IDs.
`POST /admin/credits/adjust` requires the same session, a CSRF token and an
`If-Match` header copied from the owner's current ETag. For example:

```text
If-Match: "0"
X-CSRFToken: <dashboard CSRF token>
{"owner":"alice","amount_microusd":1000000,
"operation_id":"allocation-1","reason":"Reviewed allocation"}
```

Missing `If-Match` returns 428 `credits_revision_required`; a stale revision
returns 412 `credits_revision_mismatch`. Negative adjustments are allowed only
within available credit. Reasons must be 1–512 printable ASCII characters.
Audit rows atomically record owner, operation ID, revision, actor and kind, with
no reason or request content. Treat reason text as administrative metadata and
keep user content out of it. Ledger and audit history are retained; this feature
provides no deletion, automatic payment, currency conversion or invoice service.

Application integration uses `register_credits_routes(app, csrf)` in
`app.py:create_app`. Bind verified context as `g.tenant_context`. Supply the
registered credit authority to `services/enterprise_contract.py:
register_enterprise_adapters`, preserving the other authority collaborators.
Reservation integration calls reserve from `services/budget_service.py:
BudgetService._reserve_durable` / `services/request_accounting.py:begin`, commit
from `BudgetService.complete` / `services/request_accounting.py:_record_budget`,
and reconcile from `services/reservation_store.py:reconcile`. Use independent
attempt identities and the current balance revision. The private dispatcher call site is
`worker/managed-state-dispatch.mjs:handleManagedStateRequest`, mapped to
`handleCreditsRequest` for `/v1/managed-state/credits`. The Container transport
uses the `credits` domain, allowlisted as `/v1/managed-state/credits` in
`services/intelligence_d1_store.py:_ENDPOINTS` on the private internal origin.
For native requests, bind the authority at the reserve/settle/reconcile call
sites in `worker/reservations-d1.mjs:createReservationLifecycle` through the
fixed registration in `worker/gateway-extensions.mjs`. These call sites must
classify unknown costs rather than translating them to zero. `CreditDenied`
extends `AuthorityDenied` with bounded `code` and `status`; Flask route
registration installs its JSON error handler. Native request integration uses
the denial's `response()` method through `generationErrorResponse` so schema
failures remain JSON 503 denials.

Usage receipts may include an optional ledger operation ID and revision as
provenance. Credit admission and settlement do not require receipt storage,
and receipt errors must never trigger a second charge. Local tests exercise
SQLite and a SQLite-backed D1 contract fake; they do not validate deployed D1,
live provider metering or an operator's tariff.

A billing member's top-up funds that member's own usage within the verified
workspace; it does not fund the whole organisation.

Verified Stripe payments use the dedicated private `payment_append` operation.
The callback records a credit for a top-up, or a negative `adjust` for a refund or
dispute, with the reserved `processor:stripe` actor. Processor adjustments can
make balance negative after spending; new reservations remain denied. Ordinary
admin writes cannot use any `processor:` actor. The immutable payment identity
is replay-safe even after re-reading the current ledger revision. The callback
retries only 412 revision conflicts, with at most three attempts, preserving the payment
operation ID and amount. Its result advances the payment event revision, which
is separate from the ledger revision. A failed callback leaves pending payment
evidence for retry and never grants a second credit.

Shared integer and idempotency vectors:

```json
[
{"invalid_amount": true},
{"invalid_amount": 0.5},
{"invalid_amount": 1000000000000001},
{"invalid_amount": -1000000000000001},
{"request": {"owner":"alice","kind":"credit","amount_microusd":100,"operation_id":"fund","revision":0},"revision":1},
{"request": {"owner":"alice","kind":"credit","amount_microusd":100,"operation_id":"fund","revision":0},"revision":1},
{"request": {"owner":"alice","kind":"credit","amount_microusd":101,"operation_id":"fund","revision":0},"error":"credits_conflict"},
{"request": {"owner":"alice","kind":"reserve","amount_microusd":60,"operation_id":"hold","revision":1,"scoped_id":"attempt","tariff_revision":1},"revision":2},
{"request": {"owner":"alice","kind":"reserve","amount_microusd":50,"operation_id":"second","revision":2,"scoped_id":"other","tariff_revision":1},"error":"credits_insufficient"},
{"request": {"owner":"alice","kind":"commit","amount_microusd":25,"operation_id":"charge","revision":2,"scoped_id":"attempt","tariff_revision":1},"revision":3},
{"request":{"owner":"overrun","kind":"credit","amount_microusd":100,"operation_id":"fund","revision":0},"revision":1},
{"request":{"owner":"overrun","kind":"reserve","amount_microusd":60,"operation_id":"hold","revision":1,"scoped_id":"attempt","tariff_revision":1},"revision":2},
{"request":{"owner":"overrun","kind":"commit","amount_microusd":150,"operation_id":"charge","revision":2,"scoped_id":"attempt","tariff_revision":1},"revision":3,"summary":{"balance_microusd":-50,"held_microusd":0,"available_microusd":-50}},
{"request":{"owner":"overrun","kind":"reserve","amount_microusd":1,"operation_id":"denied","revision":3,"scoped_id":"next","tariff_revision":1},"error":"credits_insufficient"},
{"request":{"owner":"overrun","kind":"credit","amount_microusd":100,"operation_id":"refill","revision":3},"revision":4,"summary":{"balance_microusd":50,"held_microusd":0,"available_microusd":50}},
{"request":{"owner":"overrun","kind":"reserve","amount_microusd":1,"operation_id":"next","revision":4,"scoped_id":"next","tariff_revision":1},"revision":5,"summary":{"balance_microusd":50,"held_microusd":1,"available_microusd":49}},
{"request":{"owner":"processor-tests","kind":"credit","amount_microusd":100,"operation_id":"fund","revision":0},"revision":1},
{"request":{"owner":"processor-tests","kind":"reserve","amount_microusd":100,"operation_id":"hold","revision":1,"scoped_id":"attempt","tariff_revision":1},"revision":2},
{"request":{"owner":"processor-tests","kind":"commit","amount_microusd":100,"operation_id":"spend","revision":2,"scoped_id":"attempt","tariff_revision":1},"revision":3},
{"request":{"owner":"processor-tests","kind":"adjust","amount_microusd":-100,"operation_id":"admin-spoof","revision":3,"actor":"processor:stripe","reason":"refund"},"error":"invalid_credits_request"},
{"operation":"payment_append","request":{"owner":"processor-tests","event_kind":"refund","amount_microusd":100,"operation_id":"refund:checkout","revision":2,"scoped_id":"checkout","processor_id":"stripe"},"error":"credits_revision_mismatch"},
{"operation":"payment_append","request":{"owner":"processor-tests","event_kind":"refund","amount_microusd":100,"operation_id":"refund:checkout","revision":3,"scoped_id":"checkout","processor_id":"stripe"},"revision":4,"summary":{"balance_microusd":-100,"held_microusd":0,"available_microusd":-100}},
{"operation":"payment_append","request":{"owner":"processor-tests","event_kind":"refund","amount_microusd":100,"operation_id":"refund:checkout","revision":4,"scoped_id":"checkout","processor_id":"stripe"},"revision":4,"summary":{"balance_microusd":-100,"revision":4}}
]
```

## Request admission

`CREDITS_ENABLED=true` enables the ledger without charging requests.
`CREDITS_ENFORCEMENT` defaults to `off`; `funded` charges owners whose ledger
revision is above zero, and `all` charges every authenticated owner, including
administrators. Credit owners before selecting `all`. Empty or invalid settings
are off, and enforcement has effect only while the ledger is enabled.

The owner is the verified principal within the selected organisation and team.
A member's payment funds that member's usage in that workspace. Legacy owners
keep their existing format. Key and workspace budgets reserve first; credits
reserve last against the same priced estimate, rounded up to integer micro-USD.
The price revision is the first 12 hexadecimal digits of SHA-256 of the exact
`MODEL_PRICING_USD_PER_MILLION` configuration, interpreted as an integer.

Flask managed requests and native Worker generations use this admission policy.
Insufficient credit returns JSON 402 `credits_insufficient`; an unpriced charged
request returns 503 `credits_unpriced`. Authority failures return 503
`credits_unavailable`. Revision conflicts allow at most three total attempts,
rereading the revision with the same operation ID, scope and amount. An uncertain write is never retried.
Measured usage commits its actual cost. Unknown usage records a reconciliation
marker and retains its hold until an evidenced operator reconciliation.
Pre-dispatch cancellation releases the original estimate once. Each hedged or
batch attempt has a separate reservation; a cancelled hedge's credit estimate
is released. Gateway estimates and measured costs are not provider invoices.

Native generations and semantic embeddings use separate per-attempt credit reservations; cache hits release the generation estimate.

Credit and governance admission runs after the idempotency claim and admission,
at the same point as key-budget admission. A refusal dispatches no provider and
leaves no open hold; its claim settles like a key-budget refusal. A caller who
retries after a top-up must use a new `Idempotency-Key`.
Loading
Loading