@astram/guard 0.19.0 → 0.20.0

package/dist/session/mfa-requirement-service.js

@@ -0,0 +1,461 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MfaRequirementService = exports.MfaRequirementUnavailableError = void 0;
+exports.currentVersionReader = currentVersionReader;
+/**
+ * MfaRequirementService — mandatory 2FA in the guard (auth capabilities R2.3–R2.5, R2.7, D-2, D-11).
+ * One evaluation (core `evaluateMfaRequirement`, B-2) over the guard's `MfaRequirementSource` (B-1),
+ * used at four points:
+ *
+ *  1. SIGN-IN ({@link atLogin}, a lifecycle event: DB reads allowed). The result is bound on the
+ *     session: `'required'` ⇒ `restriction: 'mfa_enrollment'` (the controller also marks the durable
+ *     column), `'grace'` ⇒ `mfaEnrollmentDeadlineMs`; always the version stamp the grants were read
+ *     at. Any failure throws; the controller revokes the session and answers 503 (fail closed).
+ *  2. THE REQUEST PATH ({@link refresh}), on gated AND self-authenticating routes. It re-evaluates
+ *     ONLY when the tenant's current permission version is newer than the session's stamp (or there
+ *     is no stamp yet); otherwise it returns at once with NO DB query (N1, Shield #12, ADR-0035).
+ *     Gated routes pass the version (and the reloaded grants) gate 5 already has; self-authenticating
+ *     routes read the version from Redis ({@link currentVersionReader}: a hit is Redis only, a miss is
+ *     the one DB fill gate 5 also does, a Redis error denies). A transition writes the durable column
+ *     (a lifecycle write), then the session-claims entry by compare-and-set
+ *     (`SessionTokenBinder.updateMfaRequirement`). Any failure throws
+ *     {@link MfaRequirementUnavailableError} (503) and advances nothing, so the next request retries.
+ *  3. DEVICE CONFIRM ({@link onFactorConfirmed}): lifts the restriction on the current session (Redis
+ *     claims and the durable column) and deletes the grace clock (AC-7, AC-10).
+ *  4. LAST-DEVICE REMOVAL ({@link requiresFactor}, R2.7): whether any policy applies (no clock write).
+ *
+ * The subject (decision (2) of slice D): the node chain comes from the session's ACTIVE node (scope
+ * closure); roles and permission keys from the grants (gate 5's reload, or the session-facts
+ * projector, the same `loadCoarseGrants` the decision authority uses). Root accounts are subject
+ * only to platform-floor policies (D-11, in the core rule).
+ *
+ * Constructed only when the policy feature is wired (`SHIELD_MFA_POLICY_FEATURE`); without it the
+ * guard behaves exactly as before.
+ */
+const common_1 = require("@nestjs/common");
+const core_1 = require("@astram/core");
+const session_token_binder_js_1 = require("../request-auth/session-token-binder.js");
+/** The fail-closed answer when the requirement cannot be evaluated or recorded (503). */
+class MfaRequirementUnavailableError extends common_1.HttpException {
+    constructor() {
+        super({ error: 'authentication_unavailable' }, common_1.HttpStatus.SERVICE_UNAVAILABLE);
+    }
+}
+exports.MfaRequirementUnavailableError = MfaRequirementUnavailableError;
+const STATUS_RANK = {
+    required: 3,
+    grace: 2,
+    not_required: 1,
+};
+/**
+ * The tenant's current permission version for the self-authenticating routes, read like gate 5
+ * reads it (ADR-0035): a Redis hit answers alone; a miss is filled once from the source of truth and
+ * written back (best-effort); a Redis ERROR throws {@link MfaRequirementUnavailableError} (deny,
+ * never served from the DB).
+ */
+function currentVersionReader(cache, fill) {
+    return async (tenantId) => {
+        let cached;
+        try {
+            cached = await cache.get(tenantId);
+        }
+        catch {
+            throw new MfaRequirementUnavailableError();
+        }
+        if (cached !== null)
+            return cached;
+        let version;
+        try {
+            version = await fill(tenantId);
+        }
+        catch {
+            throw new MfaRequirementUnavailableError();
+        }
+        try {
+            await cache.raise(tenantId, version);
+        }
+        catch {
+            // Best-effort: the answer already came from the source of truth.
+        }
+        return version;
+    };
+}
+/** The session state an evaluation asks for, at `version`. */
+function stateFrom(req, version) {
+    if (req.status === 'required') {
+        return { restriction: 'mfa_enrollment', mfaRequirementVersion: version };
+    }
+    if (req.status === 'grace') {
+        return { mfaEnrollmentDeadlineMs: req.deadlineMs, mfaRequirementVersion: version };
+    }
+    return { mfaRequirementVersion: version };
+}
+/** A valid version: a non-negative safe integer. */
+function isVersion(v) {
+    return typeof v === 'number' && Number.isSafeInteger(v) && v >= 0;
+}
+class MfaRequirementService {
+    deps;
+    now;
+    constructor(deps) {
+        this.deps = deps;
+        this.now = deps.now ?? Date.now;
+    }
+    /**
+     * Evaluate the requirement and persist the clock the rule asks for (`start` keeps the EARLIER
+     * stored value, R2.4; `clear` deletes it). Throws on any store error (the caller fails closed).
+     */
+    async evaluateFor(subject) {
+        const { source } = this.deps;
+        const nodeIds = await source.scopeChainOf(subject.tenantId);
+        const [policies, hasConfirmedFactor, requiredSinceMs] = await Promise.all([
+            source.loadPolicies(nodeIds),
+            source.hasConfirmedFactor(subject.principalId),
+            source.getRequiredSince(subject.principalId),
+        ]);
+        const nowMs = this.now();
+        const input = {
+            policies,
+            subject: {
+                isRoot: subject.isRoot === true,
+                nodeIds,
+                roleIds: subject.roleIds,
+                permissionKeys: subject.permissionKeys,
+            },
+            hasConfirmedFactor,
+            requiredSinceMs,
+            nowMs,
+        };
+        let req = (0, core_1.evaluateMfaRequirement)(input);
+        if (req.clock === 'start' && (req.status === 'grace' || req.status === 'required')) {
+            const stored = await source.setRequiredSince(subject.principalId, req.requiredSinceMs);
+            // A concurrent first write kept an earlier clock: judge by that one.
+            if (stored !== req.requiredSinceMs) {
+                req = (0, core_1.evaluateMfaRequirement)({ ...input, requiredSinceMs: stored });
+            }
+        }
+        else if (req.clock === 'clear') {
+            await source.clearRequiredSince(subject.principalId);
+        }
+        return req;
+    }
+    /**
+     * The admin users list's `mfaStatus` for a page (auth capabilities R11.3, AC-17). READ ONLY: no
+     * clock is started or cleared (that stays a sign-in / request-path lifecycle write). Batched:
+     * one confirmed-factor read for the page; for the rest one scope-chain read, one policy read, and
+     * (only when a policy exists) one clock read. Grants are loaded per (user, node) ONLY where a
+     * `role` or `permission` policy could apply at that node (the documented per-row cost); `tenant`
+     * and platform policies need none. A confirmed device ⇒ `enrolled` whatever the policies; else the
+     * strictest answer over the user's active memberships (no membership ⇒ the platform floor only).
+     * Throws on any store error (the caller fails closed).
+     */
+    async statusesFor(subjects) {
+        const { source } = this.deps;
+        const batch = this.deps.batch;
+        if (!batch)
+            throw new MfaRequirementUnavailableError();
+        const out = new Map();
+        const ids = [...new Set(subjects.map((s) => s.principalId).filter(isNonEmpty))];
+        if (ids.length === 0)
+            return out;
+        const enrolled = await batch.confirmedFactorsOf(ids);
+        const pending = subjects.filter((s) => isNonEmpty(s.principalId) && !enrolled.has(s.principalId));
+        for (const id of ids)
+            if (enrolled.has(id))
+                out.set(id, 'enrolled');
+        if (pending.length === 0)
+            return out;
+        const nodes = [...new Set(pending.flatMap((s) => [...(s.nodeIds ?? [])]).filter(isNonEmpty))];
+        const chains = nodes.length > 0 ? await batch.scopeChainsOf(nodes) : new Map();
+        const chainOf = (node) => chains.get(node) ?? [node];
+        const allChainNodes = [...new Set(nodes.flatMap((n) => [...chainOf(n)]))];
+        const policies = await source.loadPolicies(allChainNodes);
+        if (policies.length === 0) {
+            for (const s of pending)
+                out.set(s.principalId, 'not_required');
+            return out;
+        }
+        const pendingIds = [...new Set(pending.map((s) => s.principalId))];
+        const clocks = await batch.requiredSinceOf(pendingIds);
+        const nowMs = this.now();
+        for (const s of pending) {
+            const contexts = s.nodeIds.length > 0
+                ? [...new Set(s.nodeIds.filter(isNonEmpty))].map((n) => ({ node: n, chain: chainOf(n) }))
+                : [{ node: null, chain: [] }];
+            let worst = 'not_required';
+            for (const ctx of contexts) {
+                const inChain = new Set(ctx.chain);
+                const candidates = policies.filter((p) => p.platform === true ||
+                    (s.isRoot !== true && p.scopeNodeId !== null && inChain.has(p.scopeNodeId)));
+                if (candidates.length === 0)
+                    continue;
+                const needsGrants = ctx.node !== null && candidates.some((p) => p.kind !== 'tenant');
+                const grants = needsGrants ? await this.grantsOf(s.principalId, ctx.node) : null;
+                const req = (0, core_1.evaluateMfaRequirement)({
+                    policies: candidates,
+                    subject: {
+                        isRoot: s.isRoot === true,
+                        nodeIds: ctx.chain,
+                        roleIds: grants ? ((0, session_token_binder_js_1.liveRoleIds)(grants) ?? []) : [],
+                        permissionKeys: grants ? grants.grantedPermissionKeys : [],
+                    },
+                    hasConfirmedFactor: false,
+                    requiredSinceMs: clocks.get(s.principalId) ?? null,
+                    nowMs,
+                });
+                const status = req.status === 'enrolled' ? 'not_required' : req.status;
+                if (STATUS_RANK[status] > STATUS_RANK[worst])
+                    worst = status;
+                if (worst === 'required')
+                    break;
+            }
+            out.set(s.principalId, worst);
+        }
+        return out;
+    }
+    /**
+     * The state to bind at sign-in. `projected` is the login's own projection (reused: no second
+     * grants read); absent or `null` ⇒ the grants are loaded here. Throws on any failure.
+     */
+    async atLogin(principal, projected) {
+        const grants = projected ?? (await this.grantsOf(principal.id, principal.tenantId));
+        if (!isVersion(grants.permissionsVersion))
+            throw new MfaRequirementUnavailableError();
+        const req = await this.evaluateFor({
+            principalId: principal.id,
+            isRoot: principal.isRoot === true,
+            tenantId: principal.tenantId,
+            roleIds: (0, session_token_binder_js_1.liveRoleIds)(grants) ?? [...principal.roleIds],
+            permissionKeys: grants.grantedPermissionKeys,
+        });
+        if (req.status === 'not_required' && req.clock === 'keep') {
+            await this.clearClockIfRequiredNowhere(principal);
+        }
+        return stateFrom(req, grants.permissionsVersion);
+    }
+    /**
+     * Review item E2: sign-in is a lifecycle event, so a stored clock that the CURRENT node does not
+     * need is checked against every active membership of the user (the users-page evaluation,
+     * {@link statusesFor}, plus the platform floor). Required nowhere ⇒ the clock is cleared, so a
+     * policy added later gives the full grace from that moment. Required (or in grace) anywhere ⇒
+     * kept, so switching nodes cannot dodge a deadline. Not wired, or a read error ⇒ kept (the safe
+     * direction; the sign-in itself already evaluated its own node).
+     */
+    async clearClockIfRequiredNowhere(principal) {
+        const batch = this.deps.batch;
+        if (!batch || typeof batch.activeNodesOf !== 'function')
+            return;
+        try {
+            const nodeIds = await batch.activeNodesOf(principal.id);
+            const statuses = await this.statusesFor([
+                { principalId: principal.id, isRoot: principal.isRoot === true, nodeIds },
+            ]);
+            if (statuses.get(principal.id) === 'not_required') {
+                await this.deps.source.clearRequiredSince(principal.id);
+            }
+        }
+        catch {
+            // Keep the clock.
+        }
+    }
+    /**
+     * The request-path recompute (R2.5). Returns the claims to enforce for THIS request: unchanged
+     * when nothing is due (NO DB query), else re-evaluated and recorded. `known.version` /
+     * `known.grants`: what gate 5 already has on a gated route. Throws
+     * {@link MfaRequirementUnavailableError} on any failure (the caller denies).
+     */
+    async refresh(accessToken, claims, known) {
+        // Sessions only: a service-account key has no session state and no interactive enrolment.
+        if (claims.sessionId === '' || claims.kind === 'service_account')
+            return claims;
+        void accessToken; // keyed by session id: the session-claims entry is authoritative.
+        let version;
+        try {
+            const knownVersion = known?.version;
+            version = isVersion(knownVersion)
+                ? knownVersion
+                : await this.deps.currentVersion(claims.tenantId);
+        }
+        catch {
+            throw new MfaRequirementUnavailableError(); // Redis down ⇒ deny (ADR-0035)
+        }
+        if (!isVersion(version))
+            throw new MfaRequirementUnavailableError();
+        const stamp = claims.mfaRequirementVersion;
+        if (isVersion(stamp) && version <= stamp)
+            return claims; // unchanged: no DB query
+        try {
+            const grants = known?.grants ?? (await this.grantsOf(claims.id, claims.tenantId));
+            const req = await this.evaluateFor({
+                principalId: claims.id,
+                isRoot: claims.isRoot === true,
+                tenantId: claims.tenantId,
+                roleIds: (0, session_token_binder_js_1.liveRoleIds)(grants) ?? [...claims.roleIds],
+                permissionKeys: grants.grantedPermissionKeys,
+            });
+            const state = stateFrom(req, version);
+            // A transition of the mandatory-2FA reason writes the durable column first (lifecycle).
+            const wasRestricted = claims.restriction === 'mfa_enrollment';
+            const restrictions = this.deps.restrictions;
+            if (state.restriction === 'mfa_enrollment' &&
+                !wasRestricted &&
+                claims.mustReenroll !== true) {
+                if (typeof restrictions?.markRestriction === 'function') {
+                    await restrictions.markRestriction(claims.sessionId, 'mfa_enrollment');
+                }
+            }
+            else if (state.restriction === undefined && wasRestricted) {
+                if (typeof restrictions?.clearMfaRestriction === 'function') {
+                    await restrictions.clearMfaRestriction(claims.sessionId);
+                }
+            }
+            const binder = this.deps.binder;
+            const epoch = isVersion(claims.mfaStateEpoch) ? claims.mfaStateEpoch : 0;
+            if (binder === undefined || binder === null)
+                throw new MfaRequirementUnavailableError();
+            if (await binder.updateMfaRequirement(claims.sessionId, claims.tenantId, epoch, state)) {
+                return applyState(claims, state, epoch + 1);
+            }
+            // Refused (review round 1, item A): another recompute or a device confirm got there first.
+            // Enforce what the entry now holds when it is at least as new as this evaluation; never the
+            // state computed here. Older or gone ⇒ deny (the next request retries).
+            const stored = typeof binder.mfaRequirementOf === 'function'
+                ? await binder.mfaRequirementOf(claims.sessionId, claims.tenantId)
+                : null;
+            if (stored === null ||
+                !isVersion(stored.mfaRequirementVersion) ||
+                stored.mfaRequirementVersion < version) {
+                throw new MfaRequirementUnavailableError();
+            }
+            await this.reconcileDurable(claims.sessionId, state, stored);
+            return applyStored(claims, stored);
+        }
+        catch (err) {
+            if (err instanceof MfaRequirementUnavailableError)
+                throw err;
+            throw new MfaRequirementUnavailableError();
+        }
+    }
+    /**
+     * After a refused write, bring the durable mandatory-2FA column back in line with the stored
+     * (authoritative) state when this recompute moved it the other way. Best-effort: the column is
+     * only read by a refresh rebuild, which is unstamped and so re-evaluated on its next request.
+     */
+    async reconcileDurable(sessionId, attempted, stored) {
+        const restrictions = this.deps.restrictions;
+        const storedRestricted = stored.restriction === 'mfa_enrollment';
+        const attemptedRestricted = attempted.restriction === 'mfa_enrollment';
+        if (attemptedRestricted === storedRestricted || stored.restriction === 'reenroll')
+            return;
+        if (storedRestricted) {
+            await restrictions?.markRestriction?.(sessionId, 'mfa_enrollment').catch(() => undefined);
+        }
+        else {
+            await restrictions?.clearMfaRestriction?.(sessionId).catch(() => undefined);
+        }
+    }
+    /**
+     * A factor was just confirmed on this session (R2.3, AC-7): lift the restriction (Redis claims
+     * and the durable mandatory-2FA reason) and delete the grace clock (R2.4). Best-effort, like the
+     * re-enrol clear: a failure leaves the session restricted (the safe direction).
+     */
+    async onFactorConfirmed(claims) {
+        await this.deps.binder?.clearRestriction(claims.sessionId).catch(() => undefined);
+        if (claims.restriction === 'mfa_enrollment') {
+            await this.deps.restrictions?.clearMfaRestriction?.(claims.sessionId).catch(() => undefined);
+        }
+        await this.deps.source.clearRequiredSince(claims.id).catch(() => undefined);
+    }
+    /**
+     * R2.7 defence in depth: a removal left no confirmed factor while a policy applies — restrict this
+     * session now (durable column, then the session-claims entry; see
+     * `SessionTokenBinder.restrictMfaEnrollment`) instead of waiting for the next sign-in. Throws when
+     * the restriction could not be recorded (the caller answers 503; the removal already happened, so
+     * the user retries into a restricted session or signs in again into one).
+     */
+    async restrictNow(claims) {
+        if (claims.sessionId === '' || claims.kind === 'service_account')
+            return;
+        try {
+            if (claims.mustReenroll !== true) {
+                await this.deps.restrictions?.markRestriction?.(claims.sessionId, 'mfa_enrollment');
+            }
+            const binder = this.deps.binder;
+            if (binder === undefined ||
+                binder === null ||
+                typeof binder.restrictMfaEnrollment !== 'function' ||
+                !(await binder.restrictMfaEnrollment(claims.sessionId))) {
+                throw new MfaRequirementUnavailableError();
+            }
+        }
+        catch {
+            throw new MfaRequirementUnavailableError();
+        }
+    }
+    /**
+     * Whether a policy applies to the session's principal at its active node (R2.7): true for
+     * `enrolled` / `grace` / `required`. Reads only, never the clock. Throws on failure.
+     */
+    async requiresFactor(claims) {
+        const { source } = this.deps;
+        const grants = await this.grantsOf(claims.id, claims.tenantId);
+        const nodeIds = await source.scopeChainOf(claims.tenantId);
+        const policies = await source.loadPolicies(nodeIds);
+        const req = (0, core_1.evaluateMfaRequirement)({
+            policies,
+            subject: {
+                isRoot: claims.isRoot === true,
+                nodeIds,
+                roleIds: (0, session_token_binder_js_1.liveRoleIds)(grants) ?? [...claims.roleIds],
+                permissionKeys: grants.grantedPermissionKeys,
+            },
+            hasConfirmedFactor: true,
+            requiredSinceMs: null,
+            nowMs: this.now(),
+        });
+        return req.status !== 'not_required';
+    }
+    /** The grants for (principal, node), or throw: an evaluation never runs on guessed grants. */
+    async grantsOf(principalId, tenantId) {
+        const grants = await this.deps.loadGrants(principalId, tenantId);
+        if (grants === null || grants === undefined || !Array.isArray(grants.grantedPermissionKeys)) {
+            throw new MfaRequirementUnavailableError();
+        }
+        return grants;
+    }
+}
+exports.MfaRequirementService = MfaRequirementService;
+function isNonEmpty(v) {
+    return typeof v === 'string' && v.length > 0;
+}
+/** The claims with a recorded state applied (what this request enforces). */
+function applyState(claims, state, epoch) {
+    const { restriction: _r, mfaEnrollmentDeadlineMs: _d, mfaRequirementVersion: _v, mfaStateEpoch: _e, ...rest } = claims;
+    return {
+        ...rest,
+        ...(claims.restriction === 'reenroll' ? { restriction: 'reenroll' } : {}),
+        ...(state.restriction === 'mfa_enrollment' && claims.restriction !== 'reenroll'
+            ? { restriction: 'mfa_enrollment' }
+            : {}),
+        ...(typeof state.mfaEnrollmentDeadlineMs === 'number'
+            ? { mfaEnrollmentDeadlineMs: state.mfaEnrollmentDeadlineMs }
+            : {}),
+        mfaRequirementVersion: state.mfaRequirementVersion,
+        mfaStateEpoch: epoch,
+    };
+}
+/** The claims with the STORED state applied (a refused write: the entry is authoritative). */
+function applyStored(claims, stored) {
+    const { restriction: _r, mfaEnrollmentDeadlineMs: _d, mfaRequirementVersion: _v, mfaStateEpoch: _e, ...rest } = claims;
+    return {
+        ...rest,
+        ...(stored.restriction !== undefined ? { restriction: stored.restriction } : {}),
+        ...(stored.mfaEnrollmentDeadlineMs !== undefined
+            ? { mfaEnrollmentDeadlineMs: stored.mfaEnrollmentDeadlineMs }
+            : {}),
+        ...(stored.mfaRequirementVersion !== undefined
+            ? { mfaRequirementVersion: stored.mfaRequirementVersion }
+            : {}),
+        mfaStateEpoch: stored.mfaStateEpoch ?? 0,
+    };
+}

package/dist/session/session-restriction-store.d.ts

@@ -7,6 +7,11 @@
  *  - the session's RE-ENROLL restriction (`shield_identity.session.s_must_reenroll`, identity
  *    migration 1710000000019): set at a recovery-code login, cleared when a fresh MFA device is
  *    confirmed. A restricted session rebuilds `mustReenroll: true` and never root;
+ *  - the restriction REASON (`session.s_restriction`, identity migration 1710000000104, auth
+ *    capabilities D-2): `'reenroll'` (written with `s_must_reenroll`, decision (1)) or
+ *    `'mfa_enrollment'` (mandatory 2FA, R2.3). Read as `s_restriction ?? (s_must_reenroll ?
+ *    'reenroll' : null)`. Without migration 104 the re-enrol statements fall back to
+ *    `s_must_reenroll` alone (errno 1054), so older databases keep working;
  *  - the ACCOUNT STATUS (`shield_app.users.u_status`, the identity org table the default profile
  *    resolver already reads): disabling a user does not revoke its sessions, so a disabled user
  *    gets no rebuild.
@@ -20,6 +25,11 @@ import { type FrameworkSchemaNames } from '../config/framework-schema-names.js';
 export interface SessionRebuildFacts {
     /** The session was opened by a recovery-code login and is not yet re-secured. */
     readonly mustReenroll: boolean;
+    /**
+     * The durable restriction reason (auth capabilities D-2, decision (1)):
+     * `s_restriction ?? (s_must_reenroll ? 'reenroll' : null)`. Absent on stores that predate it.
+     */
+    readonly restriction?: 'reenroll' | 'mfa_enrollment' | null;
     /**
      * `false` when the principal's account row exists and is not `active`. `true` when it is active
      * or when no `shield_app.users` table exists (a guard-only app that keeps users elsewhere).
@@ -31,6 +41,13 @@ export interface SessionRestrictionStore {
     markMustReenroll(sessionId: string): Promise<void>;
     /** Lift it (a fresh device was confirmed). Throws on error. */
     clearMustReenroll(sessionId: string): Promise<void>;
+    /**
+     * Persist the mandatory-2FA restriction (R2.3) on the durable session; never over a re-enrol
+     * restriction. Throws on error. Optional so older test doubles still type-check.
+     */
+    markRestriction?(sessionId: string, reason: 'mfa_enrollment'): Promise<void>;
+    /** Lift the mandatory-2FA restriction only (the re-enrol one stays). Throws on error. */
+    clearMfaRestriction?(sessionId: string): Promise<void>;
     /** Read the restriction + account status for a rebuild. Throws on error (→ no rebuild). */
     rebuildFacts(sessionId: string, principalId: string): Promise<SessionRebuildFacts>;
 }
@@ -40,11 +57,30 @@ export declare class MariaDbSessionRestrictionStore implements SessionRestrictio
     private readonly sessionTable;
     /** `<app>`.`users`. */
     private readonly usersTable;
+    /**
+     * Set once a statement found no `s_restriction` column (migration 104 not applied): the re-enrol
+     * statements then use `s_must_reenroll` alone, exactly as before 104.
+     */
+    private legacyColumns;
     constructor(pool: Pool, 
     /** Framework database names; absent ⇒ resolved from `SHIELD_DB_NAMESPACE` here, once. */
     schemas?: FrameworkSchemaNames);
+    /**
+     * Run `current` (it names `s_restriction`), or `legacy` once the column is known to be absent
+     * (errno 1054 on the first try). Any other error propagates.
+     */
+    private withLegacyFallback;
+    /** Decision (1): re-enrol writes both columns (`s_restriction` and the kept `s_must_reenroll`). */
     markMustReenroll(sessionId: string): Promise<void>;
+    /** A fresh device was confirmed: lift BOTH reasons (R2.3: confirm lifts either restriction). */
     clearMustReenroll(sessionId: string): Promise<void>;
+    /**
+     * The mandatory-2FA restriction (R2.3), never over a re-enrol one (that row keeps its reason).
+     * Needs migration 104 (only written when the policy feature is on); errors propagate.
+     */
+    markRestriction(sessionId: string, reason: 'mfa_enrollment'): Promise<void>;
+    /** Lift only the mandatory-2FA reason (the requirement no longer applies). */
+    clearMfaRestriction(sessionId: string): Promise<void>;
     rebuildFacts(sessionId: string, principalId: string): Promise<SessionRebuildFacts>;
 }
 //# sourceMappingURL=session-restriction-store.d.ts.map

package/dist/session/session-restriction-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-restriction-store.d.ts","sourceRoot":"","sources":["../../src/session/session-restriction-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,qCAAqC,CAAC;AAE7C,gFAAgF;AAChF,MAAM,WAAW,mBAAmB;IAClC,iFAAiF;IACjF,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC;AAED,MAAM,WAAW,uBAAuB;IACtC,uGAAuG;IACvG,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,+DAA+D;IAC/D,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,2FAA2F;IAC3F,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACpF;AAKD,qBAAa,8BAA+B,YAAW,uBAAuB;IAO1E,OAAO,CAAC,QAAQ,CAAC,IAAI;IANvB,8BAA8B;IAC9B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,uBAAuB;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAGjB,IAAI,EAAE,IAAI;IAC3B,yFAAyF;IACzF,OAAO,CAAC,EAAE,oBAAoB;IAO1B,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOlD,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOnD,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;CAqBzF"}
+{"version":3,"file":"session-restriction-store.d.ts","sourceRoot":"","sources":["../../src/session/session-restriction-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,qCAAqC,CAAC;AAE7C,gFAAgF;AAChF,MAAM,WAAW,mBAAmB;IAClC,iFAAiF;IACjF,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,UAAU,GAAG,gBAAgB,GAAG,IAAI,CAAC;IAC5D;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC;AAED,MAAM,WAAW,uBAAuB;IACtC,uGAAuG;IACvG,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,+DAA+D;IAC/D,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD;;;OAGG;IACH,eAAe,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7E,yFAAyF;IACzF,mBAAmB,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,2FAA2F;IAC3F,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACpF;AAWD,qBAAa,8BAA+B,YAAW,uBAAuB;IAY1E,OAAO,CAAC,QAAQ,CAAC,IAAI;IAXvB,8BAA8B;IAC9B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,uBAAuB;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC;;;OAGG;IACH,OAAO,CAAC,aAAa,CAAS;gBAGX,IAAI,EAAE,IAAI;IAC3B,yFAAyF;IACzF,OAAO,CAAC,EAAE,oBAAoB;IAOhC;;;OAGG;YACW,kBAAkB;IAWhC,mGAAmG;IAC7F,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAexD,gGAAgG;IAC1F,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAezD;;;OAGG;IACG,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAOjF,8EAA8E;IACxE,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOrD,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;CA0CzF"}

package/dist/session/session-restriction-store.js

@@ -4,12 +4,22 @@ exports.MariaDbSessionRestrictionStore = void 0;
 const framework_schema_names_js_1 = require("../config/framework-schema-names.js");
 /** MariaDB `ER_NO_SUCH_TABLE`. */
 const ER_NO_SUCH_TABLE = 1146;
+/** MariaDB `ER_BAD_FIELD_ERROR`: `s_restriction` absent (an app without identity migration 104). */
+const ER_BAD_FIELD_ERROR = 1054;
+function errnoOf(err) {
+    return err?.errno;
+}
 class MariaDbSessionRestrictionStore {
     pool;
     /** `<identity>`.`session`. */
     sessionTable;
     /** `<app>`.`users`. */
     usersTable;
+    /**
+     * Set once a statement found no `s_restriction` column (migration 104 not applied): the re-enrol
+     * statements then use `s_must_reenroll` alone, exactly as before 104.
+     */
+    legacyColumns = false;
     constructor(pool, 
     /** Framework database names; absent ⇒ resolved from `SHIELD_DB_NAMESPACE` here, once. */
     schemas) {
@@ -18,16 +28,55 @@ class MariaDbSessionRestrictionStore {
         this.sessionTable = (0, framework_schema_names_js_1.qualifiedTableName)(s.identity, 'session');
         this.usersTable = (0, framework_schema_names_js_1.qualifiedTableName)(s.app, 'users');
     }
+    /**
+     * Run `current` (it names `s_restriction`), or `legacy` once the column is known to be absent
+     * (errno 1054 on the first try). Any other error propagates.
+     */
+    async withLegacyFallback(current, legacy) {
+        if (this.legacyColumns)
+            return legacy();
+        try {
+            return await current();
+        }
+        catch (err) {
+            if (errnoOf(err) !== ER_BAD_FIELD_ERROR)
+                throw err;
+            this.legacyColumns = true;
+            return legacy();
+        }
+    }
+    /** Decision (1): re-enrol writes both columns (`s_restriction` and the kept `s_must_reenroll`). */
     async markMustReenroll(sessionId) {
-        await this.pool.query(`UPDATE ${this.sessionTable} SET s_must_reenroll = 1 WHERE s_session_id = ?`, [sessionId]);
+        await this.withLegacyFallback(() => this.pool.query(`UPDATE ${this.sessionTable} SET s_must_reenroll = 1, s_restriction = 'reenroll' WHERE s_session_id = ?`, [sessionId]), () => this.pool.query(`UPDATE ${this.sessionTable} SET s_must_reenroll = 1 WHERE s_session_id = ?`, [sessionId]));
     }
+    /** A fresh device was confirmed: lift BOTH reasons (R2.3: confirm lifts either restriction). */
     async clearMustReenroll(sessionId) {
-        await this.pool.query(`UPDATE ${this.sessionTable} SET s_must_reenroll = 0 WHERE s_session_id = ?`, [sessionId]);
+        await this.withLegacyFallback(() => this.pool.query(`UPDATE ${this.sessionTable} SET s_must_reenroll = 0, s_restriction = NULL WHERE s_session_id = ?`, [sessionId]), () => this.pool.query(`UPDATE ${this.sessionTable} SET s_must_reenroll = 0 WHERE s_session_id = ?`, [sessionId]));
+    }
+    /**
+     * The mandatory-2FA restriction (R2.3), never over a re-enrol one (that row keeps its reason).
+     * Needs migration 104 (only written when the policy feature is on); errors propagate.
+     */
+    async markRestriction(sessionId, reason) {
+        await this.pool.query(`UPDATE ${this.sessionTable} SET s_restriction = ? WHERE s_session_id = ? AND s_must_reenroll = 0 AND (s_restriction IS NULL OR s_restriction <> 'reenroll')`, [reason, sessionId]);
+    }
+    /** Lift only the mandatory-2FA reason (the requirement no longer applies). */
+    async clearMfaRestriction(sessionId) {
+        await this.pool.query(`UPDATE ${this.sessionTable} SET s_restriction = NULL WHERE s_session_id = ? AND s_restriction = 'mfa_enrollment'`, [sessionId]);
     }
     async rebuildFacts(sessionId, principalId) {
-        const rows = (await this.pool.query(`SELECT s_must_reenroll FROM ${this.sessionTable} WHERE s_session_id = ? LIMIT 1`, [sessionId]));
+        const rows = await this.withLegacyFallback(async () => (await this.pool.query(`SELECT s_must_reenroll, s_restriction FROM ${this.sessionTable} WHERE s_session_id = ? LIMIT 1`, [sessionId])), async () => (await this.pool.query(`SELECT s_must_reenroll FROM ${this.sessionTable} WHERE s_session_id = ? LIMIT 1`, [sessionId])));
         // No row → treat as restricted (the caller also re-reads the session and refuses a missing one).
-        const mustReenroll = rows[0] === undefined || Number(rows[0].s_must_reenroll) !== 0;
+        const row = rows[0];
+        const stored = row?.s_restriction;
+        // Decision (1): `s_restriction ?? (s_must_reenroll ? 'reenroll' : null)`. An unknown stored
+        // value is still a restriction (fail closed).
+        const restriction = stored === undefined || stored === null
+            ? null
+            : stored === 'reenroll'
+                ? 'reenroll'
+                : 'mfa_enrollment';
+        const mustReenroll = row === undefined || Number(row.s_must_reenroll) !== 0 || restriction === 'reenroll';
         let accountActive = true;
         try {
             const users = (await this.pool.query(`SELECT u_status FROM ${this.usersTable} WHERE u_uuid = ? LIMIT 1`, [principalId]));
@@ -36,10 +85,12 @@ class MariaDbSessionRestrictionStore {
         }
         catch (err) {
             // Only an absent org table means "this app keeps no users here"; any other error fails closed.
-            if (err.errno !== ER_NO_SUCH_TABLE)
+            if (errnoOf(err) !== ER_NO_SUCH_TABLE)
                 throw err;
         }
-        return { mustReenroll, accountActive };
+        return restriction === null
+            ? { mustReenroll, accountActive }
+            : { mustReenroll, restriction, accountActive };
     }
 }
 exports.MariaDbSessionRestrictionStore = MariaDbSessionRestrictionStore;

package/dist/session/session-restriction.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The restricted-session reason (auth capabilities D-2, R2.3, R2.4) — one reading, used by every
+ * check: the global guard (gated routes) and the self-authenticating `@Public` routes
+ * (`/account/*`, `/auth/scope-switch`, `/identity/auth-facts`).
+ *
+ *  - `'reenroll'`: a recovery-code login (`mustReenroll: true`, the old form, still written so old
+ *    bindings and readers keep working). Checked first: its step-up exemptions differ.
+ *  - `'mfa_enrollment'`: a mandatory-2FA policy applies and the user has no confirmed factor
+ *    (`restriction`), or the grace deadline has passed (`mfaEnrollmentDeadlineMs <= now`, compared
+ *    here on every request, no DB read).
+ *
+ * Both reasons limit the session to `REENROLL_ALLOWED`; each has its own 403 code.
+ */
+import type { BoundPrincipalClaims } from '../request-auth/session-token-binder.js';
+export type SessionRestrictionReason = 'reenroll' | 'mfa_enrollment';
+type RestrictionClaims = Pick<BoundPrincipalClaims, 'mustReenroll'> & Partial<Pick<BoundPrincipalClaims, 'restriction' | 'mfaEnrollmentDeadlineMs'>>;
+/** The session's effective restriction at `nowMs`, or `null` when unrestricted. */
+export declare function restrictionOf(claims: RestrictionClaims, nowMs: number): SessionRestrictionReason | null;
+/** The 403 body code for a reason (`{ error: <code> }`). */
+export declare function restrictionErrorCode(reason: SessionRestrictionReason): 'reenrollment_required' | 'mfa_enrollment_required';
+export {};
+//# sourceMappingURL=session-restriction.d.ts.map

package/dist/session/session-restriction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-restriction.d.ts","sourceRoot":"","sources":["../../src/session/session-restriction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yCAAyC,CAAC;AAEpF,MAAM,MAAM,wBAAwB,GAAG,UAAU,GAAG,gBAAgB,CAAC;AAErE,KAAK,iBAAiB,GAAG,IAAI,CAAC,oBAAoB,EAAE,cAAc,CAAC,GACjE,OAAO,CAAC,IAAI,CAAC,oBAAoB,EAAE,aAAa,GAAG,yBAAyB,CAAC,CAAC,CAAC;AAEjF,mFAAmF;AACnF,wBAAgB,aAAa,CAC3B,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,MAAM,GACZ,wBAAwB,GAAG,IAAI,CAWjC;AAED,4DAA4D;AAC5D,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,wBAAwB,GAC/B,uBAAuB,GAAG,yBAAyB,CAErD"}