The entitlements pane

Backed by: @pithy-sh/payments. Scopes: payments:entitlements:read · payments:catalog:read · payments:entitlements:grant · payments:entitlements:revoke.

What it shows

A product is not an entitlement is the distinction the pane is built on, resolving one is what your Worker does per request, purchases is what granted it, and roles and permissions is who may grant one by hand.

What subjects are entitled to, and the per-subject read is addressed by both halves of the pair — (subjectType, subjectId).

Always both. Nothing keeps an organization id from equaling some user’s id, so a pane keyed on the id alone would show one holder’s plan under another’s name.

The index lists the keys: those the grants read hold, then any your catalog declares that nobody holds yet. The grants are read a page at a time, and More reads the next. Once the catalog has been read, Product keeps the keys a product grants, or those no product grants, over the keys read. The overview is how the filter panel works.

Comping, and taking it back

Grant comps an entitlement, or repairs a purchase that verified but never projected.

A comp names the key being granted, and the two pickers are never the same list. The comp offers every entitlement your catalog declares — the keys your products grant, plus the ones declared and sold by no product — which is exactly the set your Worker accepts, so a refusal at press time is impossible rather than a 400 to interpret. The revoke offers what that person actually holds, read per record. A catalog-sourced revoke picker would offer keys they never had and would miss the one that matters: a key you dropped from the catalog is still granting access until somebody takes it away.

Revoke takes one back, effective immediately.

A grant is checked against the catalog

A key your project’s entitlements map does not declare is refused, naming the key. A key declared there and sold by no product is comp-only, and grantable.

Which is what turns a typed pr into a 400 rather than a row that grants nothing and that nobody notices for a month.

payments:catalog:read is its own scope because reading what a project sells is not reading what anybody bought — it names no account and no transaction, and answers identically against an empty database.

So a tool that needs a list of comp-able entitlements can hold that and nothing else.

A revoke of a key the catalog has since dropped stays legal, or a catalog edit would be irreversible for everyone still holding it.

A grant is a control-plane call, not a click by a staff member

Comping somebody a year of Pro leaves a row signed by an issued credential with a scope on it — which is a different kind of record from a session that happened to belong to staff.

Lapsed is shown, not filtered

With the date, because your Pro ended on the 4th is the sentence a support conversation needs.

Expiry is applied on read. A row saying active with a date in the past does not grant.

Under organization billing

A colleague who joined this morning is entitled and one who left this afternoon is not — with no row rewritten either time, because membership is resolved at read time rather than stamped into the grant.

A key’s record says where its holders are. A person is on the Users record, where the comp and the revoke are. An organization is on the Organizations record, which changes no entitlement.

Every action here is audited

Grants and revokes especially. Denials too.

The per-record read behind the revoke picker is bounded four ways: only when the record is opened, only for the kind of subject the project bills, only for an id already in the pane’s own listing, and only within the same minute. The assembled path is re-checked against its own template before a token is minted, so a substituted id cannot walk out of the route it was declared for.

ESC