@plantops/auth-kit 0.1.0

package/dist/core/jwks-verifier.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Local token verification against a published JWKS (Doc 03 §1, Doc 06 §11).
+ *
+ * This is the class that keeps the IAM off every module's request path. A
+ * module fetches `/iam/.well-known/jwks.json` once, caches it for the `max-age`
+ * the IAM publishes, and verifies signatures itself — so an IAM restart, a
+ * network partition, or a slow IAM does not stop a gate terminal from
+ * authenticating a request it has already been handed a token for.
+ *
+ * ## Rotation, from the verifier's side
+ *
+ * Doc 03 §1 puts the obligations on the *signer*: publish the new public key
+ * first, wait a cache TTL, then switch. This class holds up the other end.
+ *
+ * - **Selection is by `kid`, never by trial.** Verifying against each published
+ *   key in turn would turn key retention into a signature oracle, and would
+ *   make a retired key indistinguishable from the live one in the logs.
+ * - **An unknown `kid` refetches once, then rejects.** A rotation may have
+ *   published that key seconds ago and this process may be holding a cache from
+ *   just before it. Rejecting without looking would turn every rotation into a
+ *   burst of spurious 401s lasting one cache TTL.
+ * - **The refetch is rate-limited** ({@link JwksVerifierOptions.minRefetchIntervalSeconds}).
+ *   Without that, a stream of tokens carrying a forged `kid` is a free way to
+ *   make every module hammer the IAM — the unknown-`kid` path is reachable by
+ *   anyone who can send a request.
+ *
+ * ## What is not here
+ *
+ * Revocation. `sid` is verified as present and well-formed; whether that
+ * session is still live is {@link RevocationCache}'s question, asked by the
+ * guard. Keeping the two apart is precisely what lets this class answer without
+ * talking to anyone.
+ */
+import { type JwtClaims } from '@plantops/contracts';
+/**
+ * Anything that can turn a bearer token into claims.
+ *
+ * The IAM implements this over its own local key material — it *is* the signer,
+ * so fetching its own JWKS over HTTP would be a pointless round-trip — and
+ * every other process implements it with {@link JwksVerifier}. The guard
+ * depends on this interface and not on either one.
+ */
+export interface TokenVerifier {
+    /** @throws {TokenVerificationError} */
+    verify(token: string, now?: Date): JwtClaims | Promise<JwtClaims>;
+}
+export interface JwksVerifierOptions {
+    /** Absolute URL of the IAM's `/iam/.well-known/jwks.json`. */
+    jwksUri: string;
+    /** Expected `iss`. A token from another deployment must not verify here. */
+    issuer: string;
+    /** How long a fetched key set stays fresh. Defaults to the published max-age. */
+    cacheMaxAgeSeconds?: number;
+    /**
+     * Floor between JWKS fetches triggered by an unknown `kid`. Defaults to 30 s.
+     * This is a DoS control, not a tuning knob — see the class comment.
+     */
+    minRefetchIntervalSeconds?: number;
+    /** Injectable for tests and for callers with their own HTTP stack. */
+    fetch?: typeof globalThis.fetch;
+}
+export declare class JwksVerifier implements TokenVerifier {
+    private readonly options;
+    private cache?;
+    /** In-flight fetch, so a burst of misses makes one request, not N. */
+    private inFlight?;
+    private readonly maxAgeMs;
+    private readonly minRefetchMs;
+    private readonly http;
+    constructor(options: JwksVerifierOptions);
+    /** @throws {TokenVerificationError} */
+    verify(token: string, now?: Date): Promise<JwtClaims>;
+    private keyFor;
+    /** Fetches the key set, collapsing concurrent callers onto one request. */
+    private refresh;
+    private fetchKeys;
+}
+//# sourceMappingURL=jwks-verifier.d.ts.map

package/dist/core/jwks-verifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwks-verifier.d.ts","sourceRoot":"","sources":["../../src/core/jwks-verifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAKL,KAAK,SAAS,EACf,MAAM,qBAAqB,CAAC;AAU7B;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,uCAAuC;IACvC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CACnE;AAED,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,sEAAsE;IACtE,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AASD,qBAAa,YAAa,YAAW,aAAa;IASpC,OAAO,CAAC,QAAQ,CAAC,OAAO;IARpC,OAAO,CAAC,KAAK,CAAC,CAAW;IACzB,sEAAsE;IACtE,OAAO,CAAC,QAAQ,CAAC,CAAoB;IAErC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA0B;gBAElB,OAAO,EAAE,mBAAmB;IASzD,uCAAuC;IACjC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,GAAE,IAAiB,GAAG,OAAO,CAAC,SAAS,CAAC;YAoCzD,MAAM;IAkBpB,2EAA2E;IAC3E,OAAO,CAAC,OAAO;YAYD,SAAS;CA6BxB"}

package/dist/core/jwks-verifier.js

@@ -0,0 +1,183 @@
+"use strict";
+/**
+ * Local token verification against a published JWKS (Doc 03 §1, Doc 06 §11).
+ *
+ * This is the class that keeps the IAM off every module's request path. A
+ * module fetches `/iam/.well-known/jwks.json` once, caches it for the `max-age`
+ * the IAM publishes, and verifies signatures itself — so an IAM restart, a
+ * network partition, or a slow IAM does not stop a gate terminal from
+ * authenticating a request it has already been handed a token for.
+ *
+ * ## Rotation, from the verifier's side
+ *
+ * Doc 03 §1 puts the obligations on the *signer*: publish the new public key
+ * first, wait a cache TTL, then switch. This class holds up the other end.
+ *
+ * - **Selection is by `kid`, never by trial.** Verifying against each published
+ *   key in turn would turn key retention into a signature oracle, and would
+ *   make a retired key indistinguishable from the live one in the logs.
+ * - **An unknown `kid` refetches once, then rejects.** A rotation may have
+ *   published that key seconds ago and this process may be holding a cache from
+ *   just before it. Rejecting without looking would turn every rotation into a
+ *   burst of spurious 401s lasting one cache TTL.
+ * - **The refetch is rate-limited** ({@link JwksVerifierOptions.minRefetchIntervalSeconds}).
+ *   Without that, a stream of tokens carrying a forged `kid` is a free way to
+ *   make every module hammer the IAM — the unknown-`kid` path is reachable by
+ *   anyone who can send a request.
+ *
+ * ## What is not here
+ *
+ * Revocation. `sid` is verified as present and well-formed; whether that
+ * session is still live is {@link RevocationCache}'s question, asked by the
+ * guard. Keeping the two apart is precisely what lets this class answer without
+ * talking to anyone.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JwksVerifier = void 0;
+const contracts_1 = require("@plantops/contracts");
+const node_crypto_1 = require("node:crypto");
+const claims_1 = require("./claims");
+const jws_1 = require("./jws");
+const DEFAULT_MIN_REFETCH_INTERVAL_SECONDS = 30;
+class JwksVerifier {
+    constructor(options) {
+        this.options = options;
+        this.maxAgeMs =
+            (options.cacheMaxAgeSeconds ?? contracts_1.JWKS_CACHE_MAX_AGE_SECONDS) * 1000;
+        this.minRefetchMs =
+            (options.minRefetchIntervalSeconds ?? DEFAULT_MIN_REFETCH_INTERVAL_SECONDS) *
+                1000;
+        this.http = options.fetch ?? globalThis.fetch;
+    }
+    /** @throws {TokenVerificationError} */
+    async verify(token, now = new Date()) {
+        const parsed = parse(token);
+        let key = await this.keyFor(parsed.header.kid, now);
+        if (key === undefined) {
+            // The unknown-`kid` path: one refetch, then the rejection stands.
+            key = await this.keyFor(parsed.header.kid, now, { forceRefetch: true });
+        }
+        if (key === undefined) {
+            throw new claims_1.TokenVerificationError(claims_1.TokenRejection.UNKNOWN_KEY, 'Token was signed with a key that is not published');
+        }
+        let signatureValid;
+        try {
+            signatureValid = (0, jws_1.verifyCompactJws)(parsed, key);
+        }
+        catch (error) {
+            throw new claims_1.TokenVerificationError(claims_1.TokenRejection.UNSUPPORTED_ALGORITHM, error instanceof Error ? error.message : 'Unsupported token algorithm');
+        }
+        if (!signatureValid) {
+            throw new claims_1.TokenVerificationError(claims_1.TokenRejection.BAD_SIGNATURE, 'Token signature does not verify');
+        }
+        const claims = (0, claims_1.readAccessTokenClaims)(parsed.payload);
+        (0, claims_1.assertClaimsAcceptable)(claims, this.options.issuer, now);
+        return claims;
+    }
+    async keyFor(kid, now, { forceRefetch = false } = {}) {
+        const ageMs = this.cache ? now.getTime() - this.cache.fetchedAtMs : Infinity;
+        const stale = ageMs >= this.maxAgeMs;
+        // A forced refetch still respects the floor: the trigger is attacker-
+        // reachable, so "an unknown kid arrived" must not mean "fetch now".
+        const mayRefetch = forceRefetch ? ageMs >= this.minRefetchMs : stale;
+        if (this.cache === undefined || mayRefetch) {
+            const cache = await this.refresh(now);
+            return cache.keys.get(kid);
+        }
+        return this.cache.keys.get(kid);
+    }
+    /** Fetches the key set, collapsing concurrent callers onto one request. */
+    refresh(now) {
+        this.inFlight ??= this.fetchKeys(now)
+            .then((cache) => {
+            this.cache = cache;
+            return cache;
+        })
+            .finally(() => {
+            this.inFlight = undefined;
+        });
+        return this.inFlight;
+    }
+    async fetchKeys(now) {
+        let payload;
+        try {
+            const response = await this.http(this.options.jwksUri, {
+                headers: { accept: 'application/jwk-set+json, application/json' },
+            });
+            if (!response.ok) {
+                throw new Error(`JWKS endpoint answered ${response.status}`);
+            }
+            payload = await response.json();
+        }
+        catch (error) {
+            // A fetch failure is not "no keys": clearing the cache here would turn a
+            // brief IAM outage into a fleet-wide auth outage, when the keys already
+            // held are almost certainly still correct. Keep what we have and let the
+            // caller's `kid` lookup decide.
+            if (this.cache !== undefined)
+                return this.cache;
+            throw new claims_1.TokenVerificationError(claims_1.TokenRejection.UNKNOWN_KEY, `Could not fetch JWKS: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const keys = new Map();
+        for (const jwk of readJwks(payload)) {
+            const imported = importJwk(jwk);
+            if (imported !== undefined)
+                keys.set(jwk.kid, imported);
+        }
+        return { keys, fetchedAtMs: now.getTime() };
+    }
+}
+exports.JwksVerifier = JwksVerifier;
+function parse(token) {
+    try {
+        return (0, jws_1.parseCompactJws)(token);
+    }
+    catch (error) {
+        if (error instanceof jws_1.JwsFormatError) {
+            throw new claims_1.TokenVerificationError(claims_1.TokenRejection.MALFORMED, error.message);
+        }
+        throw error;
+    }
+}
+function readJwks(payload) {
+    const keys = payload?.keys;
+    if (!Array.isArray(keys))
+        return [];
+    return keys.filter((jwk) => typeof jwk === 'object' &&
+        jwk !== null &&
+        typeof jwk.kid === 'string' &&
+        jwk.kid !== '');
+}
+/**
+ * Turns one JWKS entry into a usable key, or drops it.
+ *
+ * Dropping rather than throwing: one unusable entry — a future EC key, an
+ * encryption key, a malformed member — must not make the whole key set
+ * unavailable and take every token down with it.
+ *
+ * The size floor is not ceremony. RS256 is only as strong as the modulus, and a
+ * verifier that accepts whatever the endpoint serves would accept a 512-bit key
+ * that can be factored, at which point anyone can mint tokens this process
+ * trusts. A key too small to be safe is not a key.
+ */
+function importJwk(jwk) {
+    if (jwk.kty !== 'RSA')
+        return undefined;
+    if (jwk.use !== undefined && jwk.use !== 'sig')
+        return undefined;
+    if (jwk.alg !== undefined && jwk.alg !== contracts_1.JWT_SIGNING_ALGORITHM)
+        return undefined;
+    // A published JWKS carries public parameters only. A member that looks like a
+    // private key is a misconfigured (or hostile) endpoint, and importing it
+    // would hand this process signing capability it must never have.
+    if ('d' in jwk)
+        return undefined;
+    try {
+        const key = (0, node_crypto_1.createPublicKey)({ key: jwk, format: 'jwk' });
+        const bits = key.asymmetricKeyDetails?.modulusLength ?? 0;
+        return bits >= contracts_1.JWT_MIN_RSA_KEY_BITS ? key : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/core/jws.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Compact JWS serialisation for RS256 (Doc 03 §1).
+ *
+ * Hand-written, for the same reason the RLS policies are: the failure modes
+ * here are silent. A JWT library that accepts one more algorithm than we meant
+ * it to, or that helpfully adds a claim, does not error — it succeeds, and the
+ * mistake is only visible to someone who goes looking. The surface is small
+ * enough (three base64url segments and one `crypto.verify` call) that owning it
+ * outright is cheaper than auditing a dependency's option matrix on every
+ * upgrade.
+ *
+ * It lives in `auth-kit` rather than in the IAM because the IAM signs and every
+ * consuming module verifies, and those two must agree byte for byte. Two
+ * implementations of "the same" JWS handling is how a signer and a verifier
+ * drift into disagreeing about a padded segment — which is a token that works
+ * in one process and fails in the next.
+ *
+ * ## The invariants that make this safe
+ *
+ * 1. **The algorithm is never read from the token.** {@link verifyCompactJws}
+ *    verifies with RS256 and rejects any header whose `alg` is not exactly
+ *    `RS256`. This is the whole of the `alg: "none"` and
+ *    HS256-signed-with-the-public-key attack class, and it is closed by
+ *    construction: there is no HMAC code path in this file for a forged header
+ *    to select.
+ * 2. **The key is never taken from the token.** The header's `kid` selects from
+ *    a closed, locally-held set (`keys.service.ts` in the IAM, the fetched JWKS
+ *    in a module); it is a lookup key, never key material. `jwk`/`jku`/`x5u`
+ *    headers are ignored entirely.
+ * 3. **Segments are validated before decoding.** Node's base64url decoder is
+ *    lenient — it will quietly accept standard-base64 `+`/`/`, padding, and
+ *    trailing junk — so two different strings can decode to the same bytes.
+ *    That is a signature-stripping foothold on any system that compares tokens
+ *    or caches by string. {@link parseCompactJws} rejects anything outside the
+ *    canonical base64url alphabet.
+ * 4. **Verification is over the exact received bytes.** The signing input is
+ *    sliced from the original token string, never re-serialised from the parsed
+ *    header and payload — re-encoding would verify a signature over a
+ *    *different* document than the caller was handed.
+ */
+import { type KeyObject } from 'node:crypto';
+/** The JOSE header the IAM writes, and the only shape it accepts back. */
+export interface JwsHeader {
+    alg: string;
+    typ?: string;
+    /** Identifies the verification key within the published JWKS (Doc 03 §1). */
+    kid: string;
+}
+/** A compact JWS taken apart, with the bytes the signature actually covers. */
+export interface ParsedJws {
+    header: JwsHeader;
+    payload: Record<string, unknown>;
+    /** `<header>.<payload>` exactly as received — the signed document. */
+    signingInput: string;
+    signature: Buffer;
+}
+/** Raised for any token this module refuses. Carries no token material. */
+export declare class JwsFormatError extends Error {
+    constructor(message: string);
+}
+/**
+ * Signs `payload` into a compact JWS.
+ *
+ * The header is built here and cannot be influenced by the caller: `alg` is
+ * always {@link JWT_SIGNING_ALGORITHM}, so nothing upstream can ask for a
+ * weaker one.
+ */
+export declare function signCompactJws(payload: Record<string, unknown>, key: KeyObject, kid: string): string;
+/**
+ * Splits a compact JWS without verifying it.
+ *
+ * Exposed separately because reading `kid` is what *selects* the verification
+ * key — the one thing a verifier legitimately needs from an unverified token.
+ * Nothing else in this codebase may act on the result: a parsed-but-unverified
+ * payload is attacker-controlled JSON.
+ */
+export declare function parseCompactJws(token: string): ParsedJws;
+/**
+ * Verifies a parsed JWS against one public key.
+ *
+ * Returns a boolean rather than throwing so the caller decides what a bad
+ * signature means; it throws only for a header that is not RS256, because that
+ * is a refusal to *attempt* verification rather than a failed one.
+ */
+export declare function verifyCompactJws(parsed: ParsedJws, key: KeyObject): boolean;
+/**
+ * Parses a PEM private key, raising a message that names the variable.
+ *
+ * The underlying OpenSSL error is deliberately *not* attached as `cause`: its
+ * message can echo fragments of the input, and this input is a signing key
+ * (Doc 10 §8). The variable name is what the operator needs anyway.
+ */
+export declare function privateKeyFromPem(pem: string, label: string): KeyObject;
+/** Parses a PEM public key, raising a message that names the variable. */
+export declare function publicKeyFromPem(pem: string, label: string): KeyObject;
+//# sourceMappingURL=jws.d.ts.map

package/dist/core/jws.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jws.d.ts","sourceRoot":"","sources":["../../src/core/jws.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAGH,OAAO,EAKL,KAAK,SAAS,EACf,MAAM,aAAa,CAAC;AAWrB,0EAA0E;AAC1E,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,GAAG,EAAE,MAAM,CAAC;CACb;AAED,+EAA+E;AAC/E,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,SAAS,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,sEAAsE;IACtE,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,2EAA2E;AAC3E,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AA8BD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,GAAG,EAAE,SAAS,EACd,GAAG,EAAE,MAAM,GACV,MAAM,CAKR;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAsCxD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAe3E;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,CAMvE;AAED,0EAA0E;AAC1E,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,CAMtE"}

package/dist/core/jws.js

@@ -0,0 +1,183 @@
+"use strict";
+/**
+ * Compact JWS serialisation for RS256 (Doc 03 §1).
+ *
+ * Hand-written, for the same reason the RLS policies are: the failure modes
+ * here are silent. A JWT library that accepts one more algorithm than we meant
+ * it to, or that helpfully adds a claim, does not error — it succeeds, and the
+ * mistake is only visible to someone who goes looking. The surface is small
+ * enough (three base64url segments and one `crypto.verify` call) that owning it
+ * outright is cheaper than auditing a dependency's option matrix on every
+ * upgrade.
+ *
+ * It lives in `auth-kit` rather than in the IAM because the IAM signs and every
+ * consuming module verifies, and those two must agree byte for byte. Two
+ * implementations of "the same" JWS handling is how a signer and a verifier
+ * drift into disagreeing about a padded segment — which is a token that works
+ * in one process and fails in the next.
+ *
+ * ## The invariants that make this safe
+ *
+ * 1. **The algorithm is never read from the token.** {@link verifyCompactJws}
+ *    verifies with RS256 and rejects any header whose `alg` is not exactly
+ *    `RS256`. This is the whole of the `alg: "none"` and
+ *    HS256-signed-with-the-public-key attack class, and it is closed by
+ *    construction: there is no HMAC code path in this file for a forged header
+ *    to select.
+ * 2. **The key is never taken from the token.** The header's `kid` selects from
+ *    a closed, locally-held set (`keys.service.ts` in the IAM, the fetched JWKS
+ *    in a module); it is a lookup key, never key material. `jwk`/`jku`/`x5u`
+ *    headers are ignored entirely.
+ * 3. **Segments are validated before decoding.** Node's base64url decoder is
+ *    lenient — it will quietly accept standard-base64 `+`/`/`, padding, and
+ *    trailing junk — so two different strings can decode to the same bytes.
+ *    That is a signature-stripping foothold on any system that compares tokens
+ *    or caches by string. {@link parseCompactJws} rejects anything outside the
+ *    canonical base64url alphabet.
+ * 4. **Verification is over the exact received bytes.** The signing input is
+ *    sliced from the original token string, never re-serialised from the parsed
+ *    header and payload — re-encoding would verify a signature over a
+ *    *different* document than the caller was handed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JwsFormatError = void 0;
+exports.signCompactJws = signCompactJws;
+exports.parseCompactJws = parseCompactJws;
+exports.verifyCompactJws = verifyCompactJws;
+exports.privateKeyFromPem = privateKeyFromPem;
+exports.publicKeyFromPem = publicKeyFromPem;
+const contracts_1 = require("@plantops/contracts");
+const node_crypto_1 = require("node:crypto");
+/** Node's digest name for the RS256 (RSASSA-PKCS1-v1_5 + SHA-256) suite. */
+const DIGEST = 'sha256';
+/** `typ` on every header the IAM writes. */
+const JWT_TYPE = 'JWT';
+/** Canonical base64url: no padding, no `+`, no `/`, nothing else. */
+const BASE64URL_SEGMENT = /^[A-Za-z0-9_-]+$/;
+/** Raised for any token this module refuses. Carries no token material. */
+class JwsFormatError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'JwsFormatError';
+    }
+}
+exports.JwsFormatError = JwsFormatError;
+function encodeSegment(value) {
+    return Buffer.from(JSON.stringify(value), 'utf8').toString('base64url');
+}
+/**
+ * Decodes one segment to JSON.
+ *
+ * The alphabet check happens here rather than at the caller because every
+ * segment needs it and a missed one is invisible: the token still verifies.
+ */
+function decodeSegment(segment, what) {
+    if (!BASE64URL_SEGMENT.test(segment)) {
+        throw new JwsFormatError(`Token ${what} is not canonical base64url`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.from(segment, 'base64url').toString('utf8'));
+    }
+    catch {
+        throw new JwsFormatError(`Token ${what} is not valid JSON`);
+    }
+    // `typeof null === 'object'`, and an array would pass a naive object check
+    // and then silently produce `undefined` for every claim lookup.
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new JwsFormatError(`Token ${what} is not a JSON object`);
+    }
+    return parsed;
+}
+/**
+ * Signs `payload` into a compact JWS.
+ *
+ * The header is built here and cannot be influenced by the caller: `alg` is
+ * always {@link JWT_SIGNING_ALGORITHM}, so nothing upstream can ask for a
+ * weaker one.
+ */
+function signCompactJws(payload, key, kid) {
+    const header = { alg: contracts_1.JWT_SIGNING_ALGORITHM, typ: JWT_TYPE, kid };
+    const signingInput = `${encodeSegment(header)}.${encodeSegment(payload)}`;
+    const signature = (0, node_crypto_1.sign)(DIGEST, Buffer.from(signingInput, 'ascii'), key);
+    return `${signingInput}.${signature.toString('base64url')}`;
+}
+/**
+ * Splits a compact JWS without verifying it.
+ *
+ * Exposed separately because reading `kid` is what *selects* the verification
+ * key — the one thing a verifier legitimately needs from an unverified token.
+ * Nothing else in this codebase may act on the result: a parsed-but-unverified
+ * payload is attacker-controlled JSON.
+ */
+function parseCompactJws(token) {
+    const segments = token.split('.');
+    if (segments.length !== 3) {
+        throw new JwsFormatError('Token is not a compact JWS (expected 3 segments)');
+    }
+    const [headerSegment, payloadSegment, signatureSegment] = segments;
+    if (!BASE64URL_SEGMENT.test(signatureSegment)) {
+        throw new JwsFormatError('Token signature is not canonical base64url');
+    }
+    const header = decodeSegment(headerSegment, 'header');
+    const payload = decodeSegment(payloadSegment, 'payload');
+    if (typeof header['alg'] !== 'string') {
+        throw new JwsFormatError('Token header is missing "alg"');
+    }
+    if (typeof header['kid'] !== 'string' || header['kid'] === '') {
+        // Without a `kid` there is no way to choose a key, and guessing by trying
+        // every published key turns key retention during a rotation into a
+        // signature oracle. Doc 03 §1 requires the header.
+        throw new JwsFormatError('Token header is missing "kid"');
+    }
+    return {
+        header: {
+            alg: header['alg'],
+            typ: typeof header['typ'] === 'string' ? header['typ'] : undefined,
+            kid: header['kid'],
+        },
+        payload,
+        signingInput: `${headerSegment}.${payloadSegment}`,
+        signature: Buffer.from(signatureSegment, 'base64url'),
+    };
+}
+/**
+ * Verifies a parsed JWS against one public key.
+ *
+ * Returns a boolean rather than throwing so the caller decides what a bad
+ * signature means; it throws only for a header that is not RS256, because that
+ * is a refusal to *attempt* verification rather than a failed one.
+ */
+function verifyCompactJws(parsed, key) {
+    if (parsed.header.alg !== contracts_1.JWT_SIGNING_ALGORITHM) {
+        throw new JwsFormatError(`Unsupported token algorithm "${parsed.header.alg}" (only ${contracts_1.JWT_SIGNING_ALGORITHM} is accepted)`);
+    }
+    // A public KeyObject, never a raw secret: `crypto.verify` will not perform an
+    // HMAC with one, so a forged `alg: HS256` header has nothing to select even
+    // if the check above were ever removed.
+    return (0, node_crypto_1.verify)(DIGEST, Buffer.from(parsed.signingInput, 'ascii'), key, parsed.signature);
+}
+/**
+ * Parses a PEM private key, raising a message that names the variable.
+ *
+ * The underlying OpenSSL error is deliberately *not* attached as `cause`: its
+ * message can echo fragments of the input, and this input is a signing key
+ * (Doc 10 §8). The variable name is what the operator needs anyway.
+ */
+function privateKeyFromPem(pem, label) {
+    try {
+        return (0, node_crypto_1.createPrivateKey)(pem);
+    }
+    catch {
+        throw new JwsFormatError(`${label} is not a readable PEM private key`);
+    }
+}
+/** Parses a PEM public key, raising a message that names the variable. */
+function publicKeyFromPem(pem, label) {
+    try {
+        return (0, node_crypto_1.createPublicKey)(pem);
+    }
+    catch {
+        throw new JwsFormatError(`${label} is not a readable PEM public key`);
+    }
+}

package/dist/core/revocation-cache.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The revoked-`sid` cache (Doc 03 §6).
+ *
+ * Access tokens are verified by signature, which means a revoked session's
+ * token keeps verifying until it expires. That is unacceptable for the case the
+ * spec singles out — a shared gate terminal logged out at shift end — so every
+ * request also asks whether its `sid` has been killed. The answer has to be
+ * cheap enough to ask on every request, which rules out the database.
+ *
+ * ## One key per revocation, not one set
+ *
+ * Doc 03 §6 says "a Redis set / short-TTL cache". A set is the wrong half of
+ * that: it grows forever and has no per-member expiry, so it must be pruned by
+ * something, and the day that something stops running is the day the set is
+ * either unbounded or silently emptied. One key per revoked `sid`, with a TTL,
+ * prunes itself.
+ *
+ * The TTL is the **remaining exposure**, not the session lifetime. Once every
+ * token bearing a `sid` has expired, the revocation entry protects nothing:
+ * such a token is already refused for `exp`. So the entry lives for one access
+ * token lifetime plus the clock-skew leeway, and then disappears. This is what
+ * keeps the cache proportional to *recent* revocations rather than to all of
+ * them.
+ *
+ * ## What a cache miss means, and what an outage means
+ *
+ * A miss means "not revoked" — that is the happy path and it is DB-free, which
+ * is the whole design. An *error* means something different and must not be
+ * confused with it: a Redis outage that reads as "not revoked" silently
+ * un-revokes every session in the system for the duration. So this class throws
+ * on failure rather than returning `false`, and {@link AuthGuard} decides —
+ * with the database as the authority where one is reachable.
+ *
+ * There remains one honest gap: if Redis is *up* but has lost the key (an
+ * eviction, a flush, a restart without persistence), a revoked session works
+ * until its access token expires. Doc 03 §6 accepts exactly that bound —
+ * "because access tokens are short-lived, the revocation window is bounded even
+ * without a per-request DB hit". The database row stays authoritative, and the
+ * next refresh (Session 9) consults it.
+ */
+/**
+ * The two commands this needs, and nothing else.
+ *
+ * Structural rather than an `ioredis` import on purpose: `auth-kit` is consumed
+ * by every future module, and making it drag a Redis client in would force that
+ * choice on all of them. `ioredis`'s `Redis` satisfies this as-is.
+ */
+export interface RevocationStore {
+    set(key: string, value: string, mode: 'EX', ttlSeconds: number): Promise<unknown>;
+    exists(key: string): Promise<number>;
+}
+/** Whatever can answer "is this session dead?" — see {@link RevocationCache}. */
+export interface RevocationChecker {
+    /** @throws when the answer is unknown. Never returns `false` on failure. */
+    isRevoked(sessionId: string): Promise<boolean>;
+}
+export interface RevocationCacheOptions {
+    /**
+     * How long a revocation entry is kept: one access-token lifetime plus the
+     * skew leeway. Longer wastes memory; shorter re-opens the session.
+     */
+    ttlSeconds: number;
+}
+export declare class RevocationCache implements RevocationChecker {
+    private readonly store;
+    private readonly options;
+    constructor(store: RevocationStore, options: RevocationCacheOptions);
+    /**
+     * Marks a session dead for every verifier sharing this cache.
+     *
+     * Call **after** the database write commits. Publishing first would let a
+     * concurrent reader see a revoked session that a rollback then restores — the
+     * same post-commit ordering the scope-move invalidation requires (Doc 07 §7).
+     */
+    revoke(sessionId: string): Promise<void>;
+    /** @throws when the store cannot answer — see the class comment. */
+    isRevoked(sessionId: string): Promise<boolean>;
+}
+//# sourceMappingURL=revocation-cache.d.ts.map

package/dist/core/revocation-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"revocation-cache.d.ts","sourceRoot":"","sources":["../../src/core/revocation-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAIH;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,CACD,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,IAAI,EACV,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACtC;AAED,iFAAiF;AACjF,MAAM,WAAW,iBAAiB;IAChC,4EAA4E;IAC5E,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,eAAgB,YAAW,iBAAiB;IAErD,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE,sBAAsB;IAGlD;;;;;;OAMG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO9C,oEAAoE;IAC9D,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAGrD"}