Authorization and billing subjects¶

Authorization in Sandloom is one composable algebra. A policy is a requirement built from atoms with &, | and ~; Depends(require(policy)) turns it into a route dependency. The same policy runs in HTTP routes, in services, in tasks and in consumers. Billing atoms always name whose account they check (of=), because the tenant a request is bound to does not tell you which billing account pays.

What you get by default, and what you declare¶

from fastapi import Depends

from sandloom.sdk import OrgRole, Subscribed, require
from sandloom.sdk.authz import Account  # sandloom: advanced billing subject

ORG = Account.org(param="org_id")


@router.get(
    "/orgs/{org_id}/reports/export",
    dependencies=[Depends(require(OrgRole("member") & Subscribed(of=ORG)))],
)
async def export(org_id: UUID) -> ExportOut: ...

The algebra¶

A requirement is a predicate. & is and, | is or, ~ is not. Atoms evaluate cheapest tier first, then in declaration order, with short circuit, so a cheap claim check decides before any resource load or live call.

Live atoms resolve their contract through the service registry (a local provider, else the RPC binding) and never pass the request's session. The contract an atom talks to is a pluggable adapter (register_live_adapter(ENTITLEMENTS | MEMBERSHIP, adapter)), defaulting to billing's entitlements and tenancy's membership contracts. Cross-cutting atoms reference other modules by string, never by import; a module's own domain-specific atoms live in its package.

Three-valued decisions¶

A decision is allow, deny or indeterminate (the policy could not be evaluated: a fact is unregistered, a contract is absent from the deployment, the tenant context is missing). Indeterminate always denies with its own status: ~ never inverts it, and | allows only when some operand genuinely allows.

Subscription and credit gates answer 402. AccessDenied is an HTTPException, so the response carries the decision's status and a {"detail", "code"} body. require(..., status_code=...) overrides only a definite deny.

One chokepoint: enforce and authorize¶

HTTP guards, use-case calls inside a service and background work evaluate the same policy:

from sandloom.sdk.authz import enforce, system_subject  # sandloom: advanced non-HTTP authorization

await enforce(Role("admin"), subject=user, source="internal")
await enforce(policy, subject=system_subject(), source="task")

enforce builds the context, decides, and on denial records a structured deny log and the access_denied_* metric, then raises AccessDenied. require, authorize and authorize_resource are thin wrappers over it. A denial is logged, not audited: the request rolls back, and its audit rows with it (Audit).

Billing subjects: of= is required¶

Three notions are separate:

Subscribed, SubscriptionActive, Credits, Feature and WithinLimit take a keyword-only, required of=. Without it the atom refuses to construct and startup fails (SANDLOOM-B017).

• A route under /orgs/{org_id} with of=Account.user() is refused statically unless the atom says why: Account.user(reason="the export is billed to the requester") (SANDLOOM-C027). Account.org(param="x") without x in the path or query is an error too.
• Non-HTTP use (authorize(policy, subject=...) in tasks and consumers, service and system subjects) resolves from the authorization context and the bound tenant, not from a request.
• Custom live adapters (adapter=) are kept.

Account selection in billing itself¶

The same rule applies where billing chooses an account:

• The billing API (/subscription, /credits, checkout, portal): without org_id the account is the caller's personal account; an organization account needs org_id. There is no inference from "member of exactly one organization". See Billing.
• billing.credits.v1.spend / get_balance: when the call carries a user subject, a personal tenant_id must equal that subject, else BillingTenantMismatchError (403). System and service callers are unchanged.
• Operation intents (checkout, portal) pass the resolved account to release_check, which requires the authority re-read for an organization (Lifecycle).

Access facts and resolution modes¶

Entitled(fact_name) resolves a named AccessFact, published by its owner as part of its public contract (<owner>.facts.v1; a process without the owner binds it in SERVICE_BINDINGS and gets the same decision). The mode is set per fact with the ACCESS setting: claim (from the token), projection (a local read model), live (an authoritative call) or auto. A configured mode never weakens the fact's min_freshness floor. A claim is trusted only when its owning module is in the token's claims_sources and not in claims_sources_failed; otherwise claim mode escalates to live. Claim interpretation is declared with AccessFact(claim_rule=ClaimRule.one_of(...)) and travels over RPC.

Billing registers subscription.active (default auto) and organization.subscription.active (live only, membership-checked); a false fact denies 402, a non-member is refused 403. In tests, fake_access_fact(name, value) answers a fact without loading its owner; the two subscription facts also answer the live SubscriptionActive / Subscribed(of=Account.org(...)) atoms.

A route's gate names the contracts it calls, and they join the module's derived consumes as optional requirements: SubscriptionActive / Credits add billing.entitlements.v1, Entitled(fact) adds the fact owner's <owner>.facts.v1, Subscribed adds billing.facts.v1, OrgRole adds tenancy.membership.v1. The startup preflight warns when one is unbound, and sandloom add deploy binds them in the microservices profile.

What breaks it¶

Design rationale¶

• ADR-0010: Public API 1.0, "Explicit authorization subjects"
• ADR-0003: fewer sync RPC membership reads
• ADR-0009: route policy (admin risk on gates)