@astram/guard 0.7.0 → 0.8.0

package/dist/request-auth/session-token-binder.d.ts

@@ -11,7 +11,10 @@
  * establish/rotate time and reads it per request. Zero Core changes.
  *
  * The binding: `shield:at:<accessToken>` → JSON {@link BoundPrincipalClaims}
- * ({ id, tenantId, roleIds, kind }), TTL = the access-token lifetime. The token
+ * ({ id, tenantId, roleIds, kind }), TTL ≤ the access-token lifetime (security hardening
+ * #8). Alongside it: `shield:sessclaims:<sessionId>` (the liveness entry, TTL = the refresh
+ * idle window when configured) and `shield:sessat:<sessionId>` (the session's current
+ * access token, so a rotation can grace-expire the old one and a revoke can drop it). The token
  * stays fully opaque (carries no data itself); the mapping is server-side, so the
  * session is server-REVOCABLE (drop the key) and the read is FAIL-CLOSED (absent or
  * Redis-unavailable → no principal → the guard denies).
@@ -79,26 +82,74 @@ export interface BoundPrincipalClaims {
      * never silently widen or empty a principal's reach.
      */
     readonly scopeSubtreeNodeIds?: readonly string[];
+    /**
+     * OPTIONAL: the permission version of `tenantId` read just BEFORE `scopeSubtreeNodeIds` was
+     * resolved (security hardening Phase 1C). When gate 5 reloads facts at a NEWER version (identity
+     * bumps it on a company create/move/delete), the enforcement guard re-derives the subtree once
+     * and advances this stamp. Read before the resolve, so a bump racing the resolve leaves the stamp
+     * too OLD (one extra re-derive), never too new (a missed one).
+     *
+     * Only meaningful beside a subtree: `resolve()` drops it when the subtree is absent or the value
+     * is not a non-negative integer. ABSENT with a subtree (a legacy binding, or a version read that
+     * failed) → the next gate-5 reload re-derives once and stamps.
+     */
+    readonly scopeSubtreeVersion?: number;
+}
+/**
+ * The `cachedFacts` slot a binding stores (ADR-0035): the version, the keys and the optional time
+ * bound. The projection's `roleIds` are NOT kept here — they are the claims' own `roleIds`, written
+ * in the same payload, so there is one copy of the roles.
+ */
+export declare function factsSlot(grants: CoarseGrants): CoarseGrants;
+/** The projection's live roles when it reported them (a string array), else `undefined`. */
+export declare function liveRoleIds(grants: CoarseGrants | null | undefined): string[] | undefined;
+/** Lifetimes the binder applies (security hardening #8). Both optional for back-compat. */
+export interface SessionTokenBinderOptions {
+    /**
+     * TTL of the session-claims (liveness) entry and the current-token pointer. The auth
+     * module passes the refresh idle window (`refreshIdleMs`): the entry must outlive every
+     * access token of a live session, and no longer. Absent → the legacy `4 × access TTL`.
+     */
+    readonly sessionClaimsTtlMs?: number;
+    /**
+     * How long the PREVIOUS access token stays bound after `rebindOnRotate` (plan D7,
+     * default 30 s). It is then expired (`PEXPIRE`), so a rotated-away token never keeps
+     * its full access TTL.
+     */
+    readonly rotateGraceMs?: number;
 }
 export declare class SessionTokenBinder {
     private readonly redis;
-    constructor(redis: Redis);
+    private readonly options;
+    constructor(redis: Redis, options?: SessionTokenBinderOptions);
+    /** TTL for the session-claims entry + current-token pointer. */
+    private sessionTtl;
     /**
      * Bind an access token to its principal claims for `ttlMs` (the access-token
      * lifetime). Called right after `SessionAuthority.establish` in the auth
      * controller (it holds both the freshly-minted access token and the Principal).
      * ALSO writes a session-id → claims entry so a later `rebindOnRotate` can carry the
      * full claims (roles/kind/root) forward across a token rotation, where the
-     * durable session row alone lacks them.
+     * durable session row alone lacks them, and records the session's CURRENT access
+     * token so a rotation can grace-expire it and a revoke can drop it.
      */
     bind(accessToken: string, claims: BoundPrincipalClaims, ttlMs: number): Promise<void>;
+    /**
+     * Grace-expire the session's previous access token after a rotation (plan D7): it stays
+     * usable for at most `rotateGraceMs` (never longer than it already had), then expires.
+     * Best-effort — a failure leaves the old binding to its own (≤ access TTL) expiry.
+     */
+    private graceExpire;
     /**
      * On refresh/rotate the controller has the NEW access token + the session, but not
      * the full Principal (roles/kind/root live only in the binding, not the
      * durable session row). Re-bind by reading the session-claims entry and writing the
      * new access-token binding with the SAME claims. Returns true if it carried claims
-     * forward, false if the session-claims entry was gone (then the caller has nothing
-     * to bind — a later request will 401 and the user re-logs in; fail-closed).
+     * forward, false if the session-claims entry was gone or unreadable — the caller MUST
+     * then refuse the refresh (the auth controller answers 401: an unbound token is never
+     * handed out). A Redis error on the writes propagates (the caller fails closed too).
+     * The new binding's TTL is `ttlMs` (≤ the access TTL); the session's previous access
+     * token is grace-expired (≤ 30 s by default, plan D7).
      *
      * `freshFacts` (ADR-0011 eager projection at REFRESH):
      *   - `undefined` (omitted, the default) → carry whatever `cachedFacts` the session
@@ -110,7 +161,70 @@ export declare class SessionTokenBinder {
      *   - `null` → STRIP `cachedFacts` (a projection that yielded nothing → the next
      *     request DB-reloads; fail-closed).
      */
-    rebindOnRotate(newAccessToken: string, sessionId: string, ttlMs: number, freshFacts?: CoarseGrants | null, freshSubtree?: readonly string[]): Promise<boolean>;
+    rebindOnRotate(newAccessToken: string, sessionId: string, ttlMs: number, freshFacts?: CoarseGrants | null, freshSubtree?: readonly string[], 
+    /**
+     * The permission version read just before `freshSubtree` was resolved (Phase 1C). Stamped
+     * when the fresh subtree is applied; absent → the stamp is dropped (unknown → re-derive once
+     * at the next reload). Ignored when no fresh subtree is applied (the carried subtree keeps its
+     * own stamp).
+     */
+    freshSubtreeVersion?: number, 
+    /**
+     * The principal's LIVE role ids from the same projection as `freshFacts` (ADR-0035, GAPS #4).
+     * Given → they REPLACE the carried roles (roles and facts are written together). Absent → the
+     * carried roles stay (a projector that does not report roles, or no projection at all).
+     */
+    freshRoleIds?: readonly string[], 
+    /**
+     * The node the fresh facts/roles/subtree were projected for (review follow-up: a scope-switch
+     * moves the claims off the login tenant). Given and the claims are now on a DIFFERENT node (a
+     * switch raced the refresh) → nothing fresh is applied and the cached facts are stripped (the
+     * next request reloads for the right node). Absent → applied as before.
+     */
+    freshForTenantId?: string): Promise<boolean>;
+    /**
+     * SILENT RECOVERY (ADR-0013 / ADR-0035, GAPS #5): write a session binding REBUILT from durable
+     * state after the session-claims entry was lost (Redis restart/flush). The caller (refresh) has
+     * already rotated the durable refresh token and assembled `claims` from the durable session
+     * record + live roles + the root allowlist + the subtree resolver.
+     *
+     * The claims entry is written with `NX`: if one appeared meanwhile, nothing is overwritten and
+     * the rebuild is refused (`false`). The caller MUST then re-read the durable session and call
+     * {@link unbindSession} if it is no longer active (a logout racing the rebuild). A Redis error
+     * propagates (the caller fails closed).
+     */
+    bindRecovered(accessToken: string, claims: BoundPrincipalClaims, ttlMs: number): Promise<boolean>;
+    /**
+     * The node a live session currently acts under (its claims' `tenantId` — the scope-switch target
+     * when it switched), or `null` when the claims are gone, unreadable, or Redis errors. Refresh uses
+     * it to project for the ACTIVE node; `null` → the durable login tenant.
+     */
+    sessionTenant(sessionId: string): Promise<string | null>;
+    /**
+     * Whether Redis answers right now (Phase 2 review F1). Refresh asks BEFORE the durable rotate
+     * spends the refresh token, so a Redis outage answers a retryable 503 instead of burning the
+     * token on a binding that cannot be written. A client without `ping` (a test double) counts as
+     * reachable.
+     *
+     * Bounded by `timeoutMs` (default 1 s): the framework's client queues commands while
+     * disconnected (`maxRetriesPerRequest: null`), so an unbounded PING would wait for Redis to come
+     * back and the refresh would then spend the token for a client that already gave up.
+     */
+    isAvailable(timeoutMs?: number): Promise<boolean>;
+    /**
+     * LIVE GRANTS re-bind (ADR-0035, GAPS #4/#6). Gate 5 reloaded this session's coarse grants (a
+     * version bump, an expired time bound, or no cache yet); write them, and the live roles from the
+     * same projection, onto the access-token entry AND the session-claims entry, so the next requests
+     * are served from the cache and every role-keyed path sees the new roles. Nothing else changes.
+     *
+     * Each entry is rewritten only when it still belongs to `sessionId` + `tenantId` (a concurrent
+     * scope-switch moved it → left alone) and `facts` is fresher than what it holds (a slower request
+     * never overwrites newer facts). Each keeps its remaining TTL and is written with `XX` (a logout
+     * that deleted it wins). Best-effort: any Redis error or miss → that entry is skipped; the caller
+     * still uses the reloaded roles for the current request. Returns `true` when the access-token
+     * entry was rewritten.
+     */
+    refreshGrants(accessToken: string, sessionId: string, tenantId: string, facts: CoarseGrants, roleIds?: readonly string[]): Promise<boolean>;
     /**
      * SCOPE-SWITCH re-bind (Task 5.2, ADR-0027 / ADR-0024). A principal is switching which
      * active node it acts under; re-bind its CURRENT session (the same access token — no
@@ -130,7 +244,39 @@ export declare class SessionTokenBinder {
      * Returns `true` on a successful re-bind, `false` when the binding is gone (logged out /
      * expired) or Redis is unavailable (the caller then denies the switch — fail-closed).
      */
-    rebindActiveScope(accessToken: string, sessionId: string, targetNodeId: string, subtree: readonly string[]): Promise<boolean>;
+    rebindActiveScope(accessToken: string, sessionId: string, targetNodeId: string, subtree: readonly string[], 
+    /**
+     * The TARGET node's permission version read just before `subtree` was resolved (Phase 1C).
+     * The old node's stamp is always dropped (versions are per tenant); this one is stamped when
+     * given, else the stamp stays absent (→ one re-derive at the next reload).
+     */
+    subtreeVersion?: number, 
+    /**
+     * The coarse grants projected for the TARGET node (ADR-0035). Given → cached on the re-scoped
+     * binding instead of stripped (the first request under the new scope is served from cache).
+     * Absent/null → stripped (the next request reloads).
+     */
+    targetFacts?: CoarseGrants | null, 
+    /**
+     * The principal's LIVE roles at the TARGET node (ADR-0035, GAPS #4), from the same projection
+     * as `targetFacts`. Given → they replace the old node's roles (roles are per node). Absent →
+     * the carried roles stay until the first request's reload replaces them.
+     */
+    targetRoleIds?: readonly string[]): Promise<boolean>;
+    /**
+     * RE-DERIVED SUBTREE re-bind (security hardening Phase 1C). The enforcement guard saw gate 5
+     * reload the facts at a permission version NEWER than the bound subtree's stamp and resolved
+     * the subtree again; write it (and its stamp) onto the access-token entry AND the session-claims
+     * entry, so this token and any later rotation carry it. Nothing else in the claims changes.
+     *
+     * Each entry is rewritten only when it still belongs to `sessionId` + `tenantId` (a concurrent
+     * scope-switch moved it elsewhere → left alone) and its stamp is absent or OLDER than `version`
+     * (a concurrent refresh already wrote something at least as fresh → left alone). Each keeps its
+     * remaining TTL (a re-derive never extends a session). Best-effort: any Redis error or miss →
+     * `false`; the caller still uses the fresh subtree for the current request and a later reload
+     * retries. Returns `true` when the access-token entry was rewritten.
+     */
+    rederiveScopeSubtree(accessToken: string, sessionId: string, tenantId: string, subtree: readonly string[], version: number): Promise<boolean>;
     /**
      * Resolve an access token to its bound claims, or `null` if the binding is
      * absent/expired. Fail-closed: any Redis error → `null` (the caller denies), never
@@ -155,9 +301,19 @@ export declare class SessionTokenBinder {
     /** Drop an access-token binding. Idempotent. */
     unbind(accessToken: string): Promise<void>;
     /**
-     * Drop the session-claims entry on logout/revoke, so a rotate after logout cannot
-     * re-mint a binding (defense-in-depth: the session is already revoked, but this
-     * removes the claims cushion too). The per-access-token bindings expire by TTL.
+     * The THROWING variant of {@link unbindSession} (Phase 3 review P1): the same keys, but a
+     * Redis error PROPAGATES. An administrative revoke (an account disable through the session
+     * sweeper) must report a failed unbind so the admin can retry, instead of leaving the
+     * session's live access tokens valid until their TTL. Idempotent (absent keys are fine).
+     */
+    unbindSessionStrict(sessionId: string): Promise<void>;
+    /**
+     * Revoke a session in Redis (logout, password reset, refresh reuse-kill, admin revoke):
+     * drop the session-claims entry — which the {@link resolve} liveness gate requires, so
+     * EVERY access token of the session is denied on its next request — and also the
+     * session's current access-token binding and pointer. A grace-period token from an
+     * earlier rotation is covered by the liveness gate and expires within the grace.
+     * Best-effort per key; TTLs clean up regardless ({@link unbindSessionStrict} throws instead).
      */
     unbindSession(sessionId: string): Promise<void>;
 }

package/dist/request-auth/session-token-binder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-token-binder.d.ts","sourceRoot":"","sources":["../../src/request-auth/session-token-binder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AAKjC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,oFAAoF;AACpF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,YAAY,CAAC;IACpC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClD;AAmED,qBAAa,kBAAkB;IACjB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,KAAK;IAEzC;;;;;;;OAOG;IACG,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,oBAAoB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ3F;;;;;;;;;;;;;;;;;OAiBG;IACG,cAAc,CAClB,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,YAAY,GAAG,IAAI,EAChC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,GAC/B,OAAO,CAAC,OAAO,CAAC;IA2CnB;;;;;;;;;;;;;;;;;;OAkBG;IACG,iBAAiB,CACrB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB,OAAO,CAAC,OAAO,CAAC;IAmDnB;;;;;OAKG;IACG,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAwExE;;;;;;;;;;;;OAYG;IACG,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BrD,gDAAgD;IAC1C,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQhD;;;;OAIG;IACG,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAOtD"}
+{"version":3,"file":"session-token-binder.d.ts","sourceRoot":"","sources":["../../src/request-auth/session-token-binder.ts"],"names":[],"mappings":"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"}