Software entitlement
A software entitlement is the record of exactly which purchased ids (bundles, individual modules) an account is currently allowed to use. Caisson resolves entitlements from a signed license token at the registry edge, cross-checked against a live revocation deny-set, so a lapsed or revoked purchase reverts to the free base view immediately.
In code
export function makeLicenseEntitlementResolver(
getDenied: () => ReadonlySet<string>,
verify: (token: string) => VerifiedLicense = verifyLicense,
): (request: Request) => ResolvedLicense | null {
return (request: Request): ResolvedLicense | null => {
const header = request.headers.get("authorization");
if (header === null) return null;
const match = BEARER_RE.exec(header.trim());
const token = match?.[1];
if (token === undefined) return null;
const verified = verify(token);
if (!verified.valid || verified.claims === null) return null;
// Edge revocation gate: an operator-revoked license id resolves to community, base-only.
if (getDenied().has(verified.claims.licenseId)) return null;
// The signed per-entitlement updates windows + entitledSince snapshots ride along; an
// absent/null claim normalizes to the empty map (every entitlement unbounded / grandfathered).
return {
entitlements: verified.entitlements,
updatesWindows: verified.claims.updatesWindows ?? {},
entitledSince: verified.claims.entitledSince ?? {},
};
};
}How it holds
Signed claims decide, never the wire tier
The resolver never trusts the token's cosmetic TIER string. verifyLicense checks the cryptographically signed claims.entitlements field alone, so editing the wire tier without a matching signature grants nothing.
Fail-safe to the base view, never throws
verifyLicense never throws: an absent, malformed, forged, or expired token all resolve to null, and the caller then serves the free base-only view. A verification bug degrades a paid account to community rather than crashing the request.
Refcounted grants survive losing one source
The entitlement_grant junction stores one row per account, entitlement, and source. An account holds an entitlement while at least one active grant backs it, so a subscription and a one-time purchase of the same bundle each have to be revoked before access is lost.
Revoked, never deleted
A revoke flips status to 'revoked' and stamps revoked_at rather than deleting the row, preserving the audit trail. The edge resolver also checks a live revocation deny-set keyed on the license id, so an operator-revoked license reverts to the base view immediately, without waiting for the token to expire.