@zereight/mcp-gitlab 2.1.5 → 2.1.6

package/build/oauth-proxy.js

@@ -48,6 +48,9 @@ import { InvalidTokenError, ServerError } from "@modelcontextprotocol/sdk/server
 import { OAuthTokensSchema } from "@modelcontextprotocol/sdk/shared/auth.js";
 import { randomUUID, randomBytes, createHash } from "node:crypto";
 import { pino } from "pino";
+import { looksLikeStatelessClientId, mintClientId, openClientId, } from "./stateless/client-id.js";
+import { looksLikeStatelessState, mintPendingAuthState, openPendingAuthState, } from "./stateless/pending-auth.js";
+import { looksLikeStatelessStoredTokensCode, mintStoredTokensCode, openStoredTokensCode, } from "./stateless/stored-tokens.js";
 const logger = pino({ name: "gitlab-mcp-oauth-proxy" });
 // ---------------------------------------------------------------------------
 // GitLab OAuth Server Provider
@@ -120,7 +123,11 @@ class GitLabOAuthServerProvider {
     _callbackUrl;
     _pendingAuth = new BoundedLRUMap(PENDING_AUTH_MAX_SIZE);
     _storedTokens = new BoundedLRUMap(PENDING_AUTH_MAX_SIZE);
-    constructor(gitlabBaseUrl, gitlabAppId, resourceName, readOnly, customScopes, callbackProxyEnabled = false, callbackUrl = "") {
+    // Stateless mode (optional). When set, DCR and callback-proxy state are
+    // serialised into opaque OAuth values and the in-memory caches above are
+    // bypassed. Enabled independently of callback-proxy mode.
+    _stateless;
+    constructor(gitlabBaseUrl, gitlabAppId, resourceName, readOnly, customScopes, callbackProxyEnabled = false, callbackUrl = "", stateless = null) {
         this._gitlabBaseUrl = gitlabBaseUrl;
         this._gitlabAppId = gitlabAppId;
         this._resourceName = resourceName;
@@ -132,19 +139,46 @@ class GitLabOAuthServerProvider {
                     : REQUIRED_GITLAB_SCOPES_RW;
         this._callbackProxyEnabled = callbackProxyEnabled;
         this._callbackUrl = callbackUrl;
+        this._stateless = stateless;
         if (callbackProxyEnabled && !callbackUrl) {
             throw new Error("callbackUrl is required when callbackProxyEnabled is true");
         }
         if (callbackProxyEnabled) {
             logger.info(`Callback proxy mode enabled — fixed callback URL: ${callbackUrl}`);
         }
+        if (stateless) {
+            logger.info(`Stateless mode enabled (client_id TTL: ${stateless.clientTtlSeconds}s, ` +
+                `pending TTL: ${stateless.pendingTtlSeconds}s, ` +
+                `stored TTL: ${stateless.storedTtlSeconds}s)`);
+        }
     }
     // ---- Client store (local DCR) ------------------------------------------
     get clientsStore() {
         const cache = this._clientCache;
         const resourceName = this._resourceName;
+        const stateless = this._stateless;
         return {
             getClient: async (clientId) => {
+                // Stateless path: a signed client_id carries the registration.
+                // If verification succeeds, reconstruct the OAuthClientInformationFull.
+                if (stateless && looksLikeStatelessClientId(clientId)) {
+                    const payload = openClientId(stateless.material, clientId, stateless.clientTtlSeconds);
+                    if (!payload) {
+                        logger.warn(`DCR: stateless client_id rejected (bad signature or expired)`);
+                        // Mimic legacy behaviour: return a stub so the SDK surfaces the
+                        // standard InvalidClientError path. We return null to let the SDK
+                        // handler emit a proper OAuth error.
+                        return undefined;
+                    }
+                    return {
+                        client_id: clientId,
+                        client_id_issued_at: payload.iat,
+                        redirect_uris: payload.ruris,
+                        token_endpoint_auth_method: "none",
+                        grant_types: payload.gt ?? ["authorization_code"],
+                        client_name: payload.cn ?? resourceName,
+                    };
+                }
                 const cached = cache.get(clientId);
                 if (cached)
                     return cached;
@@ -157,17 +191,40 @@ class GitLabOAuthServerProvider {
                 };
             },
             registerClient: async (client) => {
+                const grantTypes = client.grant_types ?? ["authorization_code"];
+                const redirectUris = client.redirect_uris ?? [];
+                const clientName = client.client_name
+                    ? `${client.client_name} via ${resourceName}`
+                    : resourceName;
+                // Stateless path: mint a signed client_id and return the registration
+                // without touching the in-memory cache.
+                if (stateless) {
+                    const issuedAt = Math.floor(Date.now() / 1000);
+                    const clientId = mintClientId(stateless.material, {
+                        redirectUris,
+                        grantTypes,
+                        clientName,
+                    });
+                    const registered = {
+                        client_id: clientId,
+                        client_id_issued_at: issuedAt,
+                        redirect_uris: redirectUris,
+                        token_endpoint_auth_method: "none",
+                        grant_types: grantTypes,
+                        client_name: clientName,
+                    };
+                    logger.info(`DCR (stateless): issued signed client_id (name: ${clientName}, ruris: ${redirectUris.length})`);
+                    return registered;
+                }
                 // Generate a virtual client_id; all real OAuth operations use _gitlabAppId.
                 const virtualClientId = randomUUID();
                 const registered = {
                     client_id: virtualClientId,
                     client_id_issued_at: Math.floor(Date.now() / 1000),
-                    redirect_uris: client.redirect_uris ?? [],
+                    redirect_uris: redirectUris,
                     token_endpoint_auth_method: "none",
-                    grant_types: client.grant_types ?? ["authorization_code"],
-                    client_name: client.client_name
-                        ? `${client.client_name} via ${resourceName}`
-                        : resourceName,
+                    grant_types: grantTypes,
+                    client_name: clientName,
                 };
                 cache.set(virtualClientId, registered);
                 logger.info(`DCR: registered virtual client ${virtualClientId} (name: ${registered.client_name})`);
@@ -191,17 +248,30 @@ class GitLabOAuthServerProvider {
             const proxyCodeChallenge = createHash("sha256")
                 .update(proxyCodeVerifier)
                 .digest("base64url");
-            // Use a unique state to correlate the callback
-            const proxyState = randomUUID();
-            // Store the client's original params so /callback can redirect back
-            this._pendingAuth.set(proxyState, {
-                clientId: client.client_id,
-                clientRedirectUri: params.redirectUri,
-                clientState: params.state,
-                clientCodeChallenge: params.codeChallenge,
-                proxyCodeVerifier,
-                createdAt: Date.now(),
-            });
+            // Correlate the callback via either a sealed state (stateless mode) or
+            // a random UUID stored in the pendingAuth LRU (legacy mode).
+            const stateless = this._stateless;
+            const proxyState = stateless
+                ? mintPendingAuthState(stateless.material, {
+                    clientId: client.client_id,
+                    clientRedirectUri: params.redirectUri,
+                    clientState: params.state,
+                    clientCodeChallenge: params.codeChallenge,
+                    proxyCodeVerifier,
+                })
+                : randomUUID();
+            if (!stateless) {
+                // Store the client's original params so /callback can redirect back.
+                // Stateless mode carries these inside proxyState itself.
+                this._pendingAuth.set(proxyState, {
+                    clientId: client.client_id,
+                    clientRedirectUri: params.redirectUri,
+                    clientState: params.state,
+                    clientCodeChallenge: params.codeChallenge,
+                    proxyCodeVerifier,
+                    createdAt: Date.now(),
+                });
+            }
             const searchParams = new URLSearchParams({
                 client_id: this._gitlabAppId,
                 response_type: "code",
@@ -246,19 +316,44 @@ class GitLabOAuthServerProvider {
         if (this._callbackProxyEnabled) {
             // --- Callback proxy mode ---
             // The authorizationCode is a proxy code we generated in handleCallback().
-            // Look up the stored tokens by proxy code.
-            const entry = this._storedTokens.get(authorizationCode);
-            if (!entry) {
-                throw new ServerError("Invalid or expired authorization code");
+            // It is either a sealed token (stateless mode) or a random UUID that
+            // keys into the _storedTokens LRU (legacy mode).
+            const stateless = this._stateless;
+            let entry = null;
+            if (stateless && looksLikeStatelessStoredTokensCode(authorizationCode)) {
+                const payload = openStoredTokensCode(stateless.material, authorizationCode, stateless.storedTtlSeconds);
+                if (!payload) {
+                    throw new ServerError("Invalid or expired authorization code");
+                }
+                entry = {
+                    tokens: payload.t,
+                    clientId: payload.cid,
+                    clientCodeChallenge: payload.ccc,
+                    clientRedirectUri: payload.cru,
+                };
+                // NOTE: Stateless mode cannot enforce one-time use without a shared
+                // store. Replay is mitigated by short TTL + client PKCE verification
+                // below (attacker needs the code_verifier). Documented in
+                // stateless/stored-tokens.ts.
             }
-            // Check TTL before consuming — expired entries can't be retried anyway,
-            // but we give a specific error so the client knows to restart the flow.
-            if (Date.now() - entry.createdAt > PENDING_AUTH_TTL_MS) {
+            else {
+                const lru = this._storedTokens.get(authorizationCode);
+                if (!lru) {
+                    throw new ServerError("Invalid or expired authorization code");
+                }
+                if (Date.now() - lru.createdAt > PENDING_AUTH_TTL_MS) {
+                    this._storedTokens.delete(authorizationCode);
+                    throw new ServerError("Authorization code expired — please restart the OAuth flow");
+                }
+                // One-time use: delete after validation
                 this._storedTokens.delete(authorizationCode);
-                throw new ServerError("Authorization code expired — please restart the OAuth flow");
+                entry = {
+                    tokens: lru.tokens,
+                    clientId: lru.clientId,
+                    clientCodeChallenge: lru.clientCodeChallenge,
+                    clientRedirectUri: lru.clientRedirectUri,
+                };
             }
-            // One-time use: delete after validation
-            this._storedTokens.delete(authorizationCode);
             // Bind the proxy code to the client and redirect_uri that initiated
             // /authorize, preserving the normal OAuth authorization-code invariant.
             if (client.client_id !== entry.clientId) {
@@ -372,16 +467,42 @@ class GitLabOAuthServerProvider {
             res.status(400).send("Missing code or state parameter");
             return;
         }
-        // Look up the pending auth transaction
-        const pending = this._pendingAuth.getAndDelete(state);
-        if (!pending) {
-            res.status(400).send("Unknown or expired state parameter");
-            return;
+        // Look up the pending auth transaction. The sealed-state path carries
+        // the transaction inline; the legacy path fetches it from the LRU.
+        // Both produce the same normalized shape below.
+        const stateless = this._stateless;
+        let pending = null;
+        if (stateless && looksLikeStatelessState(state)) {
+            const payload = openPendingAuthState(stateless.material, state, stateless.pendingTtlSeconds);
+            if (!payload) {
+                res.status(400).send("Unknown or expired state parameter");
+                return;
+            }
+            pending = {
+                clientId: payload.cid,
+                clientRedirectUri: payload.cru,
+                clientState: payload.cs,
+                clientCodeChallenge: payload.ccc,
+                proxyCodeVerifier: payload.pcv,
+            };
         }
-        // Check TTL
-        if (Date.now() - pending.createdAt > PENDING_AUTH_TTL_MS) {
-            res.status(400).send("Authorization request expired");
-            return;
+        else {
+            const lru = this._pendingAuth.getAndDelete(state);
+            if (!lru) {
+                res.status(400).send("Unknown or expired state parameter");
+                return;
+            }
+            if (Date.now() - lru.createdAt > PENDING_AUTH_TTL_MS) {
+                res.status(400).send("Authorization request expired");
+                return;
+            }
+            pending = {
+                clientId: lru.clientId,
+                clientRedirectUri: lru.clientRedirectUri,
+                clientState: lru.clientState,
+                clientCodeChallenge: lru.clientCodeChallenge,
+                proxyCodeVerifier: lru.proxyCodeVerifier,
+            };
         }
         // Exchange the GitLab auth code for tokens using the proxy's PKCE verifier
         try {
@@ -404,15 +525,26 @@ class GitLabOAuthServerProvider {
                 return;
             }
             const tokens = OAuthTokensSchema.parse(await tokenResponse.json());
-            // Generate a proxy auth code for the MCP client
-            const proxyCode = randomUUID();
-            this._storedTokens.set(proxyCode, {
-                tokens,
-                clientId: pending.clientId,
-                clientCodeChallenge: pending.clientCodeChallenge,
-                clientRedirectUri: pending.clientRedirectUri,
-                createdAt: Date.now(),
-            });
+            // Generate a proxy auth code for the MCP client. Sealed in stateless
+            // mode; random UUID + LRU entry in legacy mode.
+            const proxyCode = stateless
+                ? mintStoredTokensCode(stateless.material, {
+                    tokens,
+                    clientId: pending.clientId,
+                    clientRedirectUri: pending.clientRedirectUri,
+                    clientCodeChallenge: pending.clientCodeChallenge,
+                })
+                : (() => {
+                    const id = randomUUID();
+                    this._storedTokens.set(id, {
+                        tokens,
+                        clientId: pending.clientId,
+                        clientCodeChallenge: pending.clientCodeChallenge,
+                        clientRedirectUri: pending.clientRedirectUri,
+                        createdAt: Date.now(),
+                    });
+                    return id;
+                })();
             // Redirect to the MCP client's original callback URL
             const clientCallback = new URL(pending.clientRedirectUri);
             clientCallback.searchParams.set("code", proxyCode);
@@ -462,7 +594,10 @@ class GitLabOAuthServerProvider {
  *                              Only ONE fixed callback URL needs to be registered with GitLab.
  * @param callbackUrl    The fixed callback URL (e.g. https://mcp.example.com/callback).
  *                        Required when callbackProxyEnabled is true.
+ * @param stateless      Optional stateless-mode options. When set, DCR and later
+ *                        callback-proxy state is encoded into opaque OAuth values
+ *                        instead of an in-memory cache, enabling multi-pod deploys.
  */
-export function createGitLabOAuthProvider(gitlabBaseUrl, gitlabAppId, resourceName = "GitLab MCP Server", readOnly = false, customScopes, callbackProxyEnabled = false, callbackUrl = "") {
-    return new GitLabOAuthServerProvider(gitlabBaseUrl, gitlabAppId, resourceName, readOnly, customScopes, callbackProxyEnabled, callbackUrl);
+export function createGitLabOAuthProvider(gitlabBaseUrl, gitlabAppId, resourceName = "GitLab MCP Server", readOnly = false, customScopes, callbackProxyEnabled = false, callbackUrl = "", stateless = null) {
+    return new GitLabOAuthServerProvider(gitlabBaseUrl, gitlabAppId, resourceName, readOnly, customScopes, callbackProxyEnabled, callbackUrl, stateless);
 }

package/build/stateless/client-id.js

@@ -0,0 +1,68 @@
+/**
+ * S1 — signed `client_id` for Dynamic Client Registration.
+ *
+ * The DCR entry is serialised into the `client_id` itself so that any pod
+ * holding the same OAUTH_STATELESS_SECRET can reconstruct the registered
+ * client record without a shared cache.
+ *
+ * Uses the signed (HMAC) format. The payload is public (redirect URIs,
+ * grant types, client name) and does not require encryption.
+ */
+import { randomBytes } from "node:crypto";
+import { sign, verify } from "./codec.js";
+import { StatelessCodecError } from "./errors.js";
+import { STATELESS_PURPOSES, } from "./types.js";
+/**
+ * Mint a signed client_id that carries the DCR registration.
+ *
+ * The returned string is opaque to the MCP client and can be of any length
+ * within standard OAuth bounds. In practice ≤ 2 KB for typical inputs.
+ */
+export function mintClientId(material, input) {
+    const iat = input.now ? input.now() : Math.floor(Date.now() / 1000);
+    // 16 bytes of entropy ⇒ negligible collision probability even across
+    // arbitrarily many DCR registrations. Kept at 16 to keep the client_id
+    // short on the wire.
+    const payload = {
+        v: 1,
+        iat,
+        n: randomBytes(16).toString("base64url"),
+        ruris: input.redirectUris,
+    };
+    if (input.grantTypes && input.grantTypes.length > 0)
+        payload.gt = input.grantTypes;
+    if (input.clientName)
+        payload.cn = input.clientName;
+    return sign(material, STATELESS_PURPOSES.CLIENT_ID, payload);
+}
+/**
+ * Verify a signed client_id and return the decoded payload.
+ *
+ * Returns null on any verification failure (malformed, bad sig, expired, …).
+ * Callers translate `null` to the SDK's InvalidClientError.
+ */
+export function openClientId(material, clientId, ttlSeconds, now) {
+    try {
+        const { payload } = verify(material, STATELESS_PURPOSES.CLIENT_ID, clientId, { ttlSeconds, now });
+        if (!Array.isArray(payload.ruris) ||
+            payload.ruris.some((u) => typeof u !== "string") ||
+            typeof payload.n !== "string" ||
+            payload.n.length === 0) {
+            return null;
+        }
+        return payload;
+    }
+    catch (err) {
+        if (err instanceof StatelessCodecError)
+            return null;
+        throw err;
+    }
+}
+/**
+ * Utility for callers: heuristically detect whether a string looks like a
+ * stateless client_id. Used to skip stateless decoding for legacy client_ids
+ * that might still be in circulation (e.g. the GitLab app UID).
+ */
+export function looksLikeStatelessClientId(value) {
+    return value.startsWith("v1.cid.");
+}

package/build/stateless/codec.js

@@ -0,0 +1,205 @@
+/**
+ * Wire-format codec for stateless tokens.
+ *
+ * Two formats:
+ *   signed:  v1.<purpose>.<b64url(payload)>.<b64url(hmac)>
+ *   sealed:  v1.<purpose>.<b64url(nonce || ciphertext || tag)>
+ *
+ * The "signed" form is used when the payload is not confidential (DCR
+ * client_id). The "sealed" form is used whenever the payload contains secrets
+ * (proxy code verifier, GitLab access token, etc.).
+ *
+ * Verification is rotation-aware: a value minted under the previous secret
+ * still opens/verifies until the operator removes OAUTH_STATELESS_SECRET_PREVIOUS.
+ */
+import { createCipheriv, createDecipheriv, randomBytes, timingSafeEqual } from "node:crypto";
+import { StatelessCodecError } from "./errors.js";
+import { deriveSubkeys, hmacSha256 } from "./secret.js";
+import { STATELESS_PURPOSES, STATELESS_VERSION, } from "./types.js";
+const AES_ALG = "aes-256-gcm";
+const NONCE_LEN = 12;
+const TAG_LEN = 16;
+// Hard cap on accepted token length — prevents pathological inputs. 64 KiB is
+// far larger than any legitimate payload we mint (session tokens are ≤2 KiB).
+const MAX_INPUT_LEN = 64 * 1024;
+// Allowance for clock skew when checking `iat` against "now". If a minter's
+// clock is a few seconds ahead of the verifier's, refuse only when the skew
+// is meaningful.
+const IAT_FUTURE_SKEW_SEC = 60;
+// ──────────────────────────────────────────────────────────────────────────
+// Base64url helpers — Node's Buffer handles base64url natively, but we add a
+// tiny wrapper so the call sites read cleanly and errors are captured.
+// ──────────────────────────────────────────────────────────────────────────
+function b64urlEncode(buf) {
+    return buf.toString("base64url");
+}
+function b64urlDecode(s, purpose) {
+    try {
+        // base64url accepts unpadded input; reject anything outside [A-Za-z0-9_-]
+        // to keep the surface tight.
+        if (!/^[A-Za-z0-9_-]*$/.test(s)) {
+            throw new StatelessCodecError("bad_base64", purpose);
+        }
+        return Buffer.from(s, "base64url");
+    }
+    catch (err) {
+        if (err instanceof StatelessCodecError)
+            throw err;
+        throw new StatelessCodecError("bad_base64", purpose);
+    }
+}
+function canonicalJson(value) {
+    // JSON.stringify is stable for the narrow payload shapes we use (fixed keys,
+    // no Maps/Sets). Keeping it simple is safer than introducing a canonicaliser
+    // dependency; all sign/verify happens within this process family.
+    return Buffer.from(JSON.stringify(value));
+}
+function parseJson(buf, purpose) {
+    try {
+        return JSON.parse(buf.toString("utf8"));
+    }
+    catch {
+        throw new StatelessCodecError("bad_json", purpose);
+    }
+}
+// ──────────────────────────────────────────────────────────────────────────
+// Versioning & purpose tags
+// ──────────────────────────────────────────────────────────────────────────
+function splitToken(token, purpose) {
+    if (!token || token.length > MAX_INPUT_LEN) {
+        throw new StatelessCodecError("malformed", purpose);
+    }
+    const parts = token.split(".");
+    if (parts.length < 3) {
+        throw new StatelessCodecError("malformed", purpose);
+    }
+    if (parts[0] !== STATELESS_VERSION) {
+        throw new StatelessCodecError("unknown_version", purpose);
+    }
+    if (parts[1] !== purpose) {
+        throw new StatelessCodecError("purpose_mismatch", purpose);
+    }
+    return parts;
+}
+function nowSec(override) {
+    return override ? override() : Math.floor(Date.now() / 1000);
+}
+/**
+ * Mint a signed token. Payload must carry `iat` (the mint helper sets it).
+ */
+export function sign(material, purpose, payload) {
+    const [{ key }] = deriveSubkeys(material, purpose).filter(k => k.slot === "current");
+    const payloadBuf = canonicalJson(payload);
+    const mac = hmacSha256(key, Buffer.concat([Buffer.from(purpose), Buffer.from([0]), payloadBuf]));
+    return `${STATELESS_VERSION}.${purpose}.${b64urlEncode(payloadBuf)}.${b64urlEncode(mac)}`;
+}
+/**
+ * Verify a signed token and return the decoded payload.
+ *
+ * Result is augmented with the key slot that accepted the MAC, for metrics.
+ */
+export function verify(material, purpose, token, opts) {
+    const parts = splitToken(token, purpose);
+    if (parts.length !== 4) {
+        throw new StatelessCodecError("malformed", purpose);
+    }
+    const payloadBuf = b64urlDecode(parts[2], purpose);
+    const macBuf = b64urlDecode(parts[3], purpose);
+    const keys = deriveSubkeys(material, purpose);
+    if (keys.length === 0) {
+        throw new StatelessCodecError("no_key", purpose);
+    }
+    let acceptedSlot = null;
+    const toSign = Buffer.concat([Buffer.from(purpose), Buffer.from([0]), payloadBuf]);
+    for (const { slot, key } of keys) {
+        const expected = hmacSha256(key, toSign);
+        if (expected.length === macBuf.length && timingSafeEqual(expected, macBuf)) {
+            acceptedSlot = slot;
+            break;
+        }
+    }
+    if (!acceptedSlot) {
+        throw new StatelessCodecError("bad_signature", purpose);
+    }
+    const payload = parseJson(payloadBuf, purpose);
+    checkIat(payload, opts.ttlSeconds, opts.now, purpose);
+    return { payload, slot: acceptedSlot };
+}
+/**
+ * Mint a sealed (AES-256-GCM) token. The purpose tag becomes the AEAD AAD so
+ * that a sealed value minted for one purpose cannot be "opened" as another.
+ */
+export function seal(material, purpose, payload) {
+    const [{ key }] = deriveSubkeys(material, purpose).filter(k => k.slot === "current");
+    const nonce = randomBytes(NONCE_LEN);
+    const cipher = createCipheriv(AES_ALG, key, nonce);
+    cipher.setAAD(Buffer.from(purpose));
+    const payloadBuf = canonicalJson(payload);
+    const ciphertext = Buffer.concat([cipher.update(payloadBuf), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    const blob = Buffer.concat([nonce, ciphertext, tag]);
+    return `${STATELESS_VERSION}.${purpose}.${b64urlEncode(blob)}`;
+}
+/**
+ * Open a sealed token and return the decoded payload.
+ */
+export function open(material, purpose, token, opts) {
+    const parts = splitToken(token, purpose);
+    if (parts.length !== 3) {
+        throw new StatelessCodecError("malformed", purpose);
+    }
+    const blob = b64urlDecode(parts[2], purpose);
+    if (blob.length < NONCE_LEN + TAG_LEN) {
+        throw new StatelessCodecError("malformed", purpose);
+    }
+    const nonce = blob.subarray(0, NONCE_LEN);
+    const tag = blob.subarray(blob.length - TAG_LEN);
+    const ciphertext = blob.subarray(NONCE_LEN, blob.length - TAG_LEN);
+    const keys = deriveSubkeys(material, purpose);
+    if (keys.length === 0) {
+        throw new StatelessCodecError("no_key", purpose);
+    }
+    let acceptedSlot = null;
+    let plaintext = null;
+    for (const { slot, key } of keys) {
+        try {
+            const decipher = createDecipheriv(AES_ALG, key, nonce);
+            decipher.setAAD(Buffer.from(purpose));
+            decipher.setAuthTag(tag);
+            const p = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+            plaintext = p;
+            acceptedSlot = slot;
+            break;
+        }
+        catch {
+            // Try the next slot; only throw bad_ciphertext after all slots fail.
+        }
+    }
+    if (!acceptedSlot || !plaintext) {
+        throw new StatelessCodecError("bad_ciphertext", purpose);
+    }
+    const payload = parseJson(plaintext, purpose);
+    checkIat(payload, opts.ttlSeconds, opts.now, purpose);
+    return { payload, slot: acceptedSlot };
+}
+// ──────────────────────────────────────────────────────────────────────────
+// Shared TTL check
+// ──────────────────────────────────────────────────────────────────────────
+function checkIat(payload, ttlSec, now, purpose) {
+    if (typeof payload !== "object" ||
+        payload === null ||
+        typeof payload.iat !== "number" ||
+        typeof payload.v !== "number") {
+        throw new StatelessCodecError("bad_schema", purpose);
+    }
+    const iat = payload.iat;
+    const t = nowSec(now);
+    if (iat > t + IAT_FUTURE_SKEW_SEC) {
+        throw new StatelessCodecError("future_iat", purpose);
+    }
+    if (ttlSec > 0 && t - iat > ttlSec) {
+        throw new StatelessCodecError("expired", purpose);
+    }
+}
+// Re-export purposes so callers have one import point.
+export { STATELESS_PURPOSES };

package/build/stateless/errors.js

@@ -0,0 +1,24 @@
+/**
+ * Typed errors for the stateless token codec.
+ *
+ * Callers should translate these to appropriate OAuth / HTTP errors in their
+ * local context. The codec itself never logs token values; it returns errors
+ * that carry only the reason and the purpose tag.
+ */
+export class StatelessCodecError extends Error {
+    reason;
+    purpose;
+    constructor(reason, purpose, message) {
+        super(message ?? `stateless codec error: ${reason} (purpose=${purpose})`);
+        this.name = "StatelessCodecError";
+        this.reason = reason;
+        this.purpose = purpose;
+    }
+}
+/** Thrown at module init when the configuration is missing or malformed. */
+export class StatelessConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "StatelessConfigError";
+    }
+}

package/build/stateless/index.js

@@ -0,0 +1,14 @@
+/**
+ * Public surface of the stateless token codec.
+ *
+ * Higher-level callers (oauth-proxy, streamable HTTP) should import from this
+ * module only, so future refactors inside `stateless/` remain non-breaking.
+ */
+export { StatelessCodecError, StatelessConfigError } from "./errors.js";
+export { STATELESS_PURPOSES, STATELESS_VERSION, } from "./types.js";
+export { decodeSecret, deriveSubkey, deriveSubkeys, hmacSha256, loadKeyMaterialFromEnv, } from "./secret.js";
+export { open, seal, sign, verify, } from "./codec.js";
+export { looksLikeStatelessClientId, mintClientId, openClientId, } from "./client-id.js";
+export { looksLikeStatelessState, mintPendingAuthState, openPendingAuthState, } from "./pending-auth.js";
+export { looksLikeStatelessStoredTokensCode, mintStoredTokensCode, openStoredTokensCode, } from "./stored-tokens.js";
+export { looksLikeStatelessSessionId, mintSessionId, openSessionId, } from "./session-id.js";