@zereight/mcp-gitlab 2.1.5 → 2.1.7

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";

package/build/stateless/pending-auth.js

@@ -0,0 +1,65 @@
+/**
+ * S2 — sealed OAuth `state` for callback-proxy mode.
+ *
+ * `authorize()` normally stores a PendingAuthTransaction in an in-memory
+ * BoundedLRUMap keyed by a random `state` parameter. The `/callback` handler
+ * looks it up when GitLab redirects the user back. Under HPA this breaks if
+ * /authorize lands on pod A and /callback on pod B.
+ *
+ * Stateless mode replaces the random `state` with a sealed token that itself
+ * carries the PendingAuthTransaction. No server-side storage; any pod that
+ * holds the shared secret can open it.
+ *
+ * Uses AEAD (AES-256-GCM) because the payload contains `proxyCodeVerifier`,
+ * which is a PKCE secret until the token exchange completes.
+ */
+import { open, seal } from "./codec.js";
+import { StatelessCodecError } from "./errors.js";
+import { STATELESS_PURPOSES, } from "./types.js";
+/**
+ * Mint a sealed state parameter. The returned string is safe to place in a
+ * URL query string; it uses only base64url characters plus dots.
+ */
+export function mintPendingAuthState(material, input) {
+    const iat = input.now ? input.now() : Math.floor(Date.now() / 1000);
+    const payload = {
+        v: 1,
+        iat,
+        cid: input.clientId,
+        cru: input.clientRedirectUri,
+        ccc: input.clientCodeChallenge,
+        pcv: input.proxyCodeVerifier,
+    };
+    if (input.clientState !== undefined)
+        payload.cs = input.clientState;
+    return seal(material, STATELESS_PURPOSES.PENDING_AUTH, payload);
+}
+/**
+ * Open a sealed state parameter. Returns null on any failure.
+ *
+ * NOTE on replay: stateless mode cannot enforce one-time-use without a shared
+ * store. Replaying a `state` value is useless on its own because GitLab's
+ * authorization code is single-use; an attacker who replays just `state`
+ * without a matching unredeemed GitLab code cannot extract tokens.
+ */
+export function openPendingAuthState(material, state, ttlSeconds, now) {
+    try {
+        const { payload } = open(material, STATELESS_PURPOSES.PENDING_AUTH, state, { ttlSeconds, now });
+        if (typeof payload.cid !== "string" ||
+            typeof payload.cru !== "string" ||
+            typeof payload.ccc !== "string" ||
+            typeof payload.pcv !== "string") {
+            return null;
+        }
+        return payload;
+    }
+    catch (err) {
+        if (err instanceof StatelessCodecError)
+            return null;
+        throw err;
+    }
+}
+/** Heuristic for distinguishing stateless state from legacy UUIDs. */
+export function looksLikeStatelessState(value) {
+    return value.startsWith("v1.ps.");
+}

package/build/stateless/secret.js

@@ -0,0 +1,98 @@
+/**
+ * Secret / keyring loader for stateless mode.
+ *
+ * Loads the master secret(s) from env vars and derives per-purpose subkeys via
+ * HKDF-SHA256. The caller (the codec) supplies a purpose tag when computing
+ * or verifying a token; that tag is used both as HKDF info and as AEAD
+ * associated data, which gives us domain separation by construction.
+ */
+import { createHmac, hkdfSync } from "node:crypto";
+import { StatelessConfigError } from "./errors.js";
+const MIN_SECRET_BYTES = 32;
+const HKDF_SALT = Buffer.from("gitlab-mcp-stateless-v1");
+const HKDF_HASH = "sha256";
+const KEY_BYTES = 32;
+/**
+ * Decode a base64url-encoded secret string into a Buffer of at least
+ * MIN_SECRET_BYTES. Also accepts standard base64 for operator convenience.
+ */
+export function decodeSecret(value, label) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        throw new StatelessConfigError(`${label} is empty`);
+    }
+    let buf;
+    try {
+        // Node's base64url decoder is forgiving of padding and accepts base64 too,
+        // but we still validate the length explicitly below.
+        buf = Buffer.from(trimmed, "base64url");
+    }
+    catch {
+        throw new StatelessConfigError(`${label} is not valid base64url`);
+    }
+    if (buf.length < MIN_SECRET_BYTES) {
+        throw new StatelessConfigError(`${label} must decode to at least ${MIN_SECRET_BYTES} bytes (got ${buf.length})`);
+    }
+    return buf;
+}
+/**
+ * Load the keyring from the environment. Returns null when stateless mode is
+ * disabled. Throws StatelessConfigError when enabled but misconfigured.
+ *
+ * `enabled` is an explicit input so the caller can drive enablement from the
+ * already-resolved config flag (which honors both env var and CLI flag
+ * precedence), rather than re-reading raw env state here. Re-parsing
+ * `OAUTH_STATELESS_MODE` from `env` would silently ignore the CLI flag
+ * `--oauth-stateless-mode`, leaving `STATELESS_MATERIAL` null and falling back
+ * to per-pod state in multi-pod deployments.
+ */
+export function loadKeyMaterialFromEnv(enabled, env = process.env) {
+    if (!enabled)
+        return null;
+    const current = env.OAUTH_STATELESS_SECRET;
+    if (!current) {
+        throw new StatelessConfigError("OAUTH_STATELESS_MODE=true requires OAUTH_STATELESS_SECRET (base64url, ≥32 bytes)");
+    }
+    const material = {
+        current: decodeSecret(current, "OAUTH_STATELESS_SECRET"),
+    };
+    const previous = env.OAUTH_STATELESS_SECRET_PREVIOUS;
+    if (previous) {
+        material.previous = decodeSecret(previous, "OAUTH_STATELESS_SECRET_PREVIOUS");
+    }
+    return material;
+}
+/**
+ * Derive a 32-byte subkey for a given purpose and slot.
+ */
+export function deriveSubkey(material, slot, purpose) {
+    const master = slot === "current" ? material.current : material.previous;
+    if (!master) {
+        // Callers are expected to check available() before asking for previous.
+        throw new StatelessConfigError(`no ${slot} secret configured`);
+    }
+    const info = Buffer.from(`gitlab-mcp/${purpose}`);
+    const derived = hkdfSync(HKDF_HASH, master, HKDF_SALT, info, KEY_BYTES);
+    // hkdfSync returns ArrayBuffer; wrap for Buffer ergonomics.
+    return Buffer.from(derived);
+}
+/**
+ * Convenience wrapper that returns both available slots' subkeys for a
+ * purpose, in order: current first, then previous (if configured).
+ */
+export function deriveSubkeys(material, purpose) {
+    const out = [
+        { slot: "current", key: deriveSubkey(material, "current", purpose) },
+    ];
+    if (material.previous) {
+        out.push({ slot: "previous", key: deriveSubkey(material, "previous", purpose) });
+    }
+    return out;
+}
+/**
+ * Constant-time HMAC-SHA256. Exposed so the codec module can avoid reimporting
+ * createHmac and so rotation-aware verification uses a single helper.
+ */
+export function hmacSha256(key, data) {
+    return createHmac("sha256", key).update(data).digest();
+}

package/build/stateless/session-id.js

@@ -0,0 +1,68 @@
+/**
+ * S4 — sealed `Mcp-Session-Id` for the Streamable HTTP transport.
+ *
+ * The MCP Streamable HTTP transport identifies sessions by the
+ * `Mcp-Session-Id` header, which the server mints on the initialization
+ * response and the client echoes back on every subsequent request.
+ *
+ * Today's code stores `{header, token, apiUrl, lastUsed}` in a
+ * `Record<sid, AuthData>` on the pod that created the session, which breaks
+ * when a subsequent request is routed to a different pod.
+ *
+ * Stateless mode replaces the server-minted UUID with an AEAD-sealed value
+ * that carries the auth data directly. Any pod sharing
+ * OAUTH_STATELESS_SECRET can open the sid and rebuild the auth context
+ * on the fly, without consulting any shared store.
+ *
+ * Uses AEAD (AES-256-GCM) because the payload contains the bearer token /
+ * PAT / job token. Because the sid is presented on every request, an
+ * attacker who captures one session_id effectively captures the bearer
+ * token behind it — the same security boundary as a stolen Authorization
+ * header. TLS is mandatory; log redaction is recommended (phase 6).
+ */
+import { open, seal } from "./codec.js";
+import { StatelessCodecError } from "./errors.js";
+import { STATELESS_PURPOSES, } from "./types.js";
+/**
+ * Mint a sealed session id. The resulting string is returned via the
+ * `Mcp-Session-Id` response header on the initialization response.
+ */
+export function mintSessionId(material, input) {
+    const iat = input.now ? input.now() : Math.floor(Date.now() / 1000);
+    const payload = {
+        v: 1,
+        iat,
+        h: input.header,
+        t: input.token,
+        u: input.apiUrl,
+    };
+    return seal(material, STATELESS_PURPOSES.SESSION_ID, payload);
+}
+/**
+ * Open a sealed session id and return the embedded auth context.
+ *
+ * Returns null on any failure (malformed, tampered, expired, wrong secret).
+ */
+export function openSessionId(material, sid, ttlSeconds, now) {
+    try {
+        const { payload } = open(material, STATELESS_PURPOSES.SESSION_ID, sid, { ttlSeconds, now });
+        if ((payload.h !== "Authorization" &&
+            payload.h !== "Private-Token" &&
+            payload.h !== "JOB-TOKEN") ||
+            typeof payload.t !== "string" ||
+            payload.t.length === 0 ||
+            typeof payload.u !== "string") {
+            return null;
+        }
+        return payload;
+    }
+    catch (err) {
+        if (err instanceof StatelessCodecError)
+            return null;
+        throw err;
+    }
+}
+/** Heuristic check: does the header value look like a stateless sid? */
+export function looksLikeStatelessSessionId(value) {
+    return value.startsWith("v1.sid.");
+}

package/build/stateless/stored-tokens.js

@@ -0,0 +1,66 @@
+/**
+ * S3 — sealed proxy authorization code for callback-proxy mode.
+ *
+ * After `/callback` exchanges the GitLab auth code for tokens, the SDK-style
+ * flow requires the MCP server to return a fresh auth code to the MCP client
+ * via redirect, and to accept that code on the subsequent POST /token.
+ *
+ * The legacy implementation stored the GitLab tokens in a per-pod
+ * BoundedLRUMap keyed by a random UUID proxy code. Under HPA this breaks when
+ * /callback and /token land on different pods.
+ *
+ * Stateless mode replaces the random UUID proxy code with an AEAD-sealed
+ * token that carries the stored tokens and the client PKCE binding directly.
+ *
+ * Uses AEAD (AES-256-GCM) because the payload contains the GitLab access
+ * token and refresh token.
+ *
+ * Replay: proxyCode replay is defeated by two mitigations:
+ *   - short TTL (OAUTH_STATELESS_STORED_TTL_SECONDS, default 600s)
+ *   - PKCE binding (the client must still present a matching code_verifier)
+ */
+import { open, seal } from "./codec.js";
+import { StatelessCodecError } from "./errors.js";
+import { STATELESS_PURPOSES, } from "./types.js";
+/**
+ * Mint a sealed proxy authorization code. The resulting string is used as the
+ * `code` query parameter in the redirect to the MCP client's redirect_uri.
+ */
+export function mintStoredTokensCode(material, input) {
+    const iat = input.now ? input.now() : Math.floor(Date.now() / 1000);
+    const payload = {
+        v: 1,
+        iat,
+        t: input.tokens,
+        cid: input.clientId,
+        cru: input.clientRedirectUri,
+        ccc: input.clientCodeChallenge,
+    };
+    return seal(material, STATELESS_PURPOSES.STORED_TOKENS, payload);
+}
+/**
+ * Open a sealed proxy authorization code. Returns null on any failure.
+ */
+export function openStoredTokensCode(material, code, ttlSeconds, now) {
+    try {
+        const { payload } = open(material, STATELESS_PURPOSES.STORED_TOKENS, code, { ttlSeconds, now });
+        if (typeof payload.cid !== "string" ||
+            typeof payload.cru !== "string" ||
+            typeof payload.ccc !== "string" ||
+            typeof payload.t !== "object" ||
+            payload.t === null ||
+            typeof payload.t.access_token !== "string") {
+            return null;
+        }
+        return payload;
+    }
+    catch (err) {
+        if (err instanceof StatelessCodecError)
+            return null;
+        throw err;
+    }
+}
+/** Heuristic for distinguishing stateless proxy codes from legacy UUIDs. */
+export function looksLikeStatelessStoredTokensCode(value) {
+    return value.startsWith("v1.pc.");
+}

package/build/stateless/types.js

@@ -0,0 +1,18 @@
+/**
+ * Shared types for the stateless token codec.
+ *
+ * Purposes are string constants, each mapping one-to-one to a derived subkey.
+ * They appear in the wire format and in HKDF info to guarantee that a token
+ * minted for one purpose cannot be successfully verified as another.
+ */
+export const STATELESS_VERSION = "v1";
+export const STATELESS_PURPOSES = {
+    /** Signed client_id issued at DCR. */
+    CLIENT_ID: "cid",
+    /** Sealed OAuth state, carried through the GitLab consent screen. */
+    PENDING_AUTH: "ps",
+    /** Sealed proxy authorization code, returned to the MCP client. */
+    STORED_TOKENS: "pc",
+    /** Sealed Mcp-Session-Id, carries session auth across pod hops. */
+    SESSION_ID: "sid",
+};