Abilities / scopes

[stsepelin]

Coarse, stateless authorization in the access token's scope claim (RFC 6749 §3.3 / RFC 9068 §2.2.3), so an API gateway or a non-lukk verifier can read it without knowing about lukk.

Lukk::abilitiesUsing(fn ($userId, $context) => $user->permissionNames());

Route::middleware(['auth:api', 'lukk.ability:orders.read,orders.write'])   // ANY
Route::middleware(['auth:api', 'lukk.abilities:orders.read,orders.write']) // ALL

Inert until configured — without a callback no claim is minted and tokens stay byte-identical to 0.5.0 — and deny by default once it is.

Derived vs pinned

By default abilities are re-derived on every mint, so revoking one takes effect within access_ttl rather than lasting the life of the refresh token. A session can instead own a fixed grant, stored on refresh_tokens.scope and replayed verbatim through every rotation — what a personal access token or a capped impersonation session needs. NULL means derive, '' means pinned-to-nothing.

lukk's own routes

A token pinned to one ability is refused by every gated route in the application but could still log the account out everywhere, or step up and enrol a passkey. RequirePinnedAbility gates DELETE /auth/sessions* on lukk.sessions, and both step-up routes plus POST /auth/password and the passkey/recovery-code reads on lukk.account.

Only pinned tokens are gated, so upgrading breaks no working install. logout and refresh are never gated — a machine token must be able to end and renew itself.

Design decisions worth reviewing

• Policy lives in the Actions, never the issuer. Resolving abilitiesUsing inside a documented swap seam meant rebinding TokenIssuer silently dropped scope, and with deny-by-default every gated route then 403'd with nothing to explain it.
• Both consumer callbacks resolve before the rotate transaction opens, behind one reject short-circuit — no application code runs under the row lock. A slow lookup can't extend it, reverse lock order can't deadlock against it, and on PostgreSQL a swallowed SQL error can't leave the transaction aborted (where COMMIT degrades to a silent ROLLBACK and the client is logged out one refresh later).
• Request-scoped, not model state. Sanctum's withAccessToken equivalent silently denies on a model the guard never touched, and answers from the previous token on one that outlives its request.
• The grace window and reuse detection are untouched — a throwing permission store must never suppress a family revoke.

Notable fixes found in review

Eight review rounds; every finding is pinned by a regression test and mutation-verified.

• Rows are written with forceFill — a useRefreshTokenModel subclass declaring $fillable dropped scope, turning a token pinned to one ability into the subject's full derived grant on first refresh, session management included, because familyIsPinned() reads the same unwritten column and collapsed alongside it.
• assertGuardsIsolated() refuses to boot a lukk-jwt guard with no lukk.guards block — it inherited the default guard's secret and audience, so one guard's token authenticated as a different user under another's provider. Pre-existing since 0.4.0.
• scope and pin are reserved claims in both directions; an empty grant can erase a hook's value.
• features.abilities / features.gate_auth_routes resolve through the active guard's config — both fail open, so a dropped per-guard override was exploitable.
• Lukk::actingAs with abilities throws outside tests: forgetScopedInstances() drops the resolved instance but not the binding, so the token would authorize the next visitor on the worker.

Verification

469 tests · 100% coverage · Pint clean · 5/5 concurrency against real PostgreSQL (two new tests pin that no application callback runs under the row lock) · 12 conformance flows against a live fixture built from this branch.

See UPGRADE.md for the migration, the two contract changes, and the HasAbilities → HasTokenAbilities rename.

Client half: stsepelin/lukk-js#50 · Docs: stsepelin/lukk-docs#10