@frontmcp/sdk 0.2.3 → 0.3.0

package/src/auth/session/session.types.d.ts

@@ -0,0 +1,65 @@
+import { SessionUser } from './record/session.base';
+/** How provider tokens are managed in a session. */
+export type SessionMode = 'transparent' | 'stateful' | 'stateless';
+/**
+ * How a single provider’s access token is represented inside the session payload.
+ */
+export type ProviderEmbedMode = 'store-only' | 'encrypted' | 'plain' | 'ref';
+/** AES-256-GCM encrypted blob, base64url fields. */
+export type EncBlob = {
+    alg: 'A256GCM';
+    iv: string;
+    tag: string;
+    data: string;
+};
+export type ProviderSnapshot = {
+    id: string;
+    exp?: number;
+    payload?: Record<string, unknown>;
+    apps?: Array<{
+        id: string;
+        toolIds?: string[];
+    }>;
+    embedMode: ProviderEmbedMode;
+    token?: string;
+    tokenEnc?: {
+        alg: 'A256GCM';
+        iv: string;
+        tag: string;
+        data: string;
+    };
+    refreshTokenEnc?: {
+        alg: 'A256GCM';
+        iv: string;
+        tag: string;
+        data: string;
+    };
+    secretRefId?: string;
+    refreshRefId?: string;
+};
+/** Arguments required to create a session from verified auth data. */
+export type CreateSessionArgs = {
+    token: string;
+    sessionId?: string;
+    claims: Record<string, any>;
+    user: SessionUser;
+    authorizedProviders?: Record<string, import('./session.types').ProviderSnapshot>;
+    authorizedProviderIds?: string[];
+    authorizedApps?: Record<string, {
+        id: string;
+        toolIds: string[];
+    }>;
+    authorizedAppIds?: string[];
+    authorizedResources?: string[];
+    scopes?: string[];
+    authorizedTools?: Record<string, {
+        executionPath: [string, string];
+        details?: Record<string, any>;
+    }>;
+    authorizedToolIds?: string[];
+    authorizedPrompts?: Record<string, {
+        executionPath: [string, string];
+        details?: Record<string, any>;
+    }>;
+    authorizedPromptIds?: string[];
+};

package/src/auth/session/session.types.js

@@ -0,0 +1,4 @@
+"use strict";
+// auth/session/session.types.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=session.types.js.map

package/src/auth/session/session.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.types.js","sourceRoot":"","sources":["../../../../src/auth/session/session.types.ts"],"names":[],"mappings":";AAAA,gCAAgC","sourcesContent":["// auth/session/session.types.ts\n\nimport { SessionUser } from './record/session.base';\n\n/** How provider tokens are managed in a session. */\nexport type SessionMode = 'transparent' | 'stateful' | 'stateless';\n\n/**\n * How a single provider’s access token is represented inside the session payload.\n */\nexport type ProviderEmbedMode =\n  | 'store-only' // stateful, encrypted in memory store\n  | 'encrypted' // stateless, encrypted in JWT/session-secret\n  | 'plain' // stateless, plaintext (in-memory only)\n  | 'ref'; // NEW: external vault/store by reference\n\n/** AES-256-GCM encrypted blob, base64url fields. */\nexport type EncBlob = { alg: 'A256GCM'; iv: string; tag: string; data: string };\n\nexport type ProviderSnapshot = {\n  id: string;\n  exp?: number;\n  payload?: Record<string, unknown>;\n  apps?: Array<{ id: string; toolIds?: string[] }>;\n  embedMode: ProviderEmbedMode;\n\n  // legacy fields (keep for back-compat)\n  token?: string; // in-memory only, for 'plain'\n  tokenEnc?: { alg: 'A256GCM'; iv: string; tag: string; data: string }; // for 'encrypted' or 'store-only'\n  refreshTokenEnc?: { alg: 'A256GCM'; iv: string; tag: string; data: string };\n\n  // NEW: externalized refs\n  secretRefId?: string; // access token reference\n  refreshRefId?: string; // refresh token reference\n};\n\n/** Arguments required to create a session from verified auth data. */\nexport type CreateSessionArgs = {\n  token: string;\n  sessionId?: string;\n  claims: Record<string, any>;\n  user: SessionUser;\n  // Optional precomputed authorization projections (preferred when provided)\n  authorizedProviders?: Record<string, import('./session.types').ProviderSnapshot>;\n  authorizedProviderIds?: string[];\n  authorizedApps?: Record<string, { id: string; toolIds: string[] }>;\n  authorizedAppIds?: string[];\n  authorizedResources?: string[];\n  scopes?: string[];\n  // Scoped tool/prompt projections for fast lookup\n  authorizedTools?: Record<string, { executionPath: [string, string]; details?: Record<string, any> }>;\n  authorizedToolIds?: string[];\n  authorizedPrompts?: Record<string, { executionPath: [string, string]; details?: Record<string, any> }>;\n  authorizedPromptIds?: string[];\n};\n\n"]}

package/src/auth/session/token.refresh.d.ts

@@ -0,0 +1,60 @@
+import type { ProviderSnapshot } from './session.types';
+import type { TokenStore } from './token.store';
+import type { TokenVault } from './token.vault';
+export type TokenRefreshCtx = {
+    /** The provider we’re refreshing for. */
+    providerId: string;
+    /** Caller-provided session facade (only what a refresher may need). */
+    session: {
+        id: string;
+        scopeId: string;
+        /** Current snapshot (mutable by the session after refresh). */
+        authorizedProviders: Record<string, ProviderSnapshot>;
+        /** Optional helper if the refresher wants to call other providers. */
+        getToken?: (pid: string, opts?: {
+            refreshSkewSec?: number;
+            forceRefresh?: boolean;
+        }) => Promise<string | undefined>;
+    };
+    /** Current access token (if known); may be undefined/expired. */
+    accessToken?: string;
+    /**
+     * Refresh token (if accessible by the embedding mode).
+     * For `ref` mode this is usually `undefined`; the refresher should use `store`/`vault`.
+     */
+    refreshToken?: string;
+    /** The snapshot we’re refreshing (same as authorizedProviders[providerId]). */
+    snapshot: ProviderSnapshot;
+    /**
+     * External storage interfaces, present for `ref` mode to avoid revealing plaintext tokens.
+     * - `store` holds opaque encrypted blobs
+     * - `vault` handles AEAD encryption/decryption of secrets
+     */
+    store?: TokenStore;
+    vault?: TokenVault;
+};
+export type TokenRefreshResult = {
+    /** New access token (if rotated). */
+    accessToken?: string;
+    /** New refresh token (optional). */
+    refreshToken?: string;
+    /** New absolute expiry (seconds since epoch preferred; ms also accepted). */
+    exp: number;
+    /** Optional opaque payload returned by the AS (id_token claims, etc.). */
+    payload?: Record<string, unknown>;
+};
+export type TokenRefresher = (ctx: TokenRefreshCtx) => Promise<TokenRefreshResult>;
+/** Convert seconds/ms epoch or Date to epoch seconds. */
+export declare function toEpochSeconds(exp?: number | Date): number | undefined;
+/** Returns true if `exp` will occur within `skewSec` from now (or already past). */
+export declare function isSoonExpiring(exp?: number | Date, skewSec?: number): boolean;
+/**
+ * Synchronous check against a provider snapshot’s `exp` field.
+ * Note: In `ref` mode the exact expiry may live in the store; this helper
+ * intentionally remains synchronous and only uses the snapshot’s `exp`.
+ */
+export declare function isSoonExpiringProvider(sessionLike: {
+    authorizedProviders: Record<string, ProviderSnapshot>;
+}, providerId: string, skewSec?: number): boolean;
+/** Best-effort extraction of `exp` from a JWT without verification. */
+export declare function tryJwtExp(token?: string): number | undefined;

package/src/auth/session/token.refresh.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toEpochSeconds = toEpochSeconds;
+exports.isSoonExpiring = isSoonExpiring;
+exports.isSoonExpiringProvider = isSoonExpiringProvider;
+exports.tryJwtExp = tryJwtExp;
+// -----------------------------------------------------------------------------
+// Expiry helpers
+// -----------------------------------------------------------------------------
+/** Convert seconds/ms epoch or Date to epoch seconds. */
+function toEpochSeconds(exp) {
+    if (exp == null)
+        return undefined;
+    if (exp instanceof Date)
+        return Math.floor(exp.getTime() / 1000);
+    // Heuristic: treat large numbers as ms
+    return exp > 1e12 ? Math.floor(exp / 1000) : Math.floor(exp);
+}
+/** Returns true if `exp` will occur within `skewSec` from now (or already past). */
+function isSoonExpiring(exp, skewSec = 60) {
+    const expSec = toEpochSeconds(exp);
+    if (expSec == null)
+        return false;
+    const now = Math.floor(Date.now() / 1000);
+    return expSec <= now + Math.max(0, skewSec);
+}
+/**
+ * Synchronous check against a provider snapshot’s `exp` field.
+ * Note: In `ref` mode the exact expiry may live in the store; this helper
+ * intentionally remains synchronous and only uses the snapshot’s `exp`.
+ */
+function isSoonExpiringProvider(sessionLike, providerId, skewSec = 60) {
+    const snap = sessionLike.authorizedProviders[providerId];
+    if (!snap)
+        return false;
+    return isSoonExpiring(snap.exp, skewSec);
+}
+// -----------------------------------------------------------------------------
+// Optional utility: derive exp from JWT (unsigned decode)
+// -----------------------------------------------------------------------------
+/** Best-effort extraction of `exp` from a JWT without verification. */
+function tryJwtExp(token) {
+    if (!token)
+        return undefined;
+    const parts = token.split('.');
+    if (parts.length < 2)
+        return undefined;
+    try {
+        const json = JSON.parse(base64urlDecode(parts[1]));
+        const e = json?.exp;
+        return typeof e === 'number' ? toEpochSeconds(e) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function base64urlDecode(input) {
+    // pad
+    const pad = input.length % 4 === 2 ? '==' : input.length % 4 === 3 ? '=' : '';
+    const s = input.replace(/-/g, '+').replace(/_/g, '/') + pad;
+    return Buffer.from(s, 'base64').toString('utf8');
+}
+//# sourceMappingURL=token.refresh.js.map

package/src/auth/session/token.refresh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.refresh.js","sourceRoot":"","sources":["../../../../src/auth/session/token.refresh.ts"],"names":[],"mappings":";;AA8DA,wCAKC;AAGD,wCAKC;AAOD,wDAQC;AAOD,8BAWC;AAnDD,gFAAgF;AAChF,iBAAiB;AACjB,gFAAgF;AAEhF,yDAAyD;AACzD,SAAgB,cAAc,CAAC,GAAmB;IAChD,IAAI,GAAG,IAAI,IAAI;QAAE,OAAO,SAAS,CAAC;IAClC,IAAI,GAAG,YAAY,IAAI;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC;IACjE,uCAAuC;IACvC,OAAO,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AAC/D,CAAC;AAED,oFAAoF;AACpF,SAAgB,cAAc,CAAC,GAAmB,EAAE,OAAO,GAAG,EAAE;IAC9D,MAAM,MAAM,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,MAAM,IAAI,IAAI;QAAE,OAAO,KAAK,CAAC;IACjC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;IAC1C,OAAO,MAAM,IAAI,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;AAC9C,CAAC;AAED;;;;GAIG;AACH,SAAgB,sBAAsB,CACpC,WAAsE,EACtE,UAAkB,EAClB,OAAO,GAAG,EAAE;IAEZ,MAAM,IAAI,GAAG,WAAW,CAAC,mBAAmB,CAAC,UAAU,CAAC,CAAC;IACzD,IAAI,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IACxB,OAAO,cAAc,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;AAC3C,CAAC;AAED,gFAAgF;AAChF,0DAA0D;AAC1D,gFAAgF;AAEhF,uEAAuE;AACvE,SAAgB,SAAS,CAAC,KAAc;IACtC,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IACvC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACnD,MAAM,CAAC,GAAG,IAAI,EAAE,GAAG,CAAC;QACpB,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC/D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,SAAS,eAAe,CAAC,KAAa;IACpC,MAAM;IACN,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9E,MAAM,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,GAAG,CAAC;IAC5D,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AACnD,CAAC","sourcesContent":["// auth/session/token.refresh.ts\nimport type { ProviderSnapshot } from './session.types';\nimport type { TokenStore } from './token.store';\nimport type { TokenVault } from './token.vault';\n\n// -----------------------------------------------------------------------------\n// Types\n// -----------------------------------------------------------------------------\n\nexport type TokenRefreshCtx = {\n  /** The provider we’re refreshing for. */\n  providerId: string;\n\n  /** Caller-provided session facade (only what a refresher may need). */\n  session: {\n    id: string;\n    scopeId: string;\n    /** Current snapshot (mutable by the session after refresh). */\n    authorizedProviders: Record<string, ProviderSnapshot>;\n    /** Optional helper if the refresher wants to call other providers. */\n    getToken?: (pid: string, opts?: { refreshSkewSec?: number; forceRefresh?: boolean }) => Promise<string | undefined>;\n  };\n\n  /** Current access token (if known); may be undefined/expired. */\n  accessToken?: string;\n\n  /**\n   * Refresh token (if accessible by the embedding mode).\n   * For `ref` mode this is usually `undefined`; the refresher should use `store`/`vault`.\n   */\n  refreshToken?: string;\n\n  /** The snapshot we’re refreshing (same as authorizedProviders[providerId]). */\n  snapshot: ProviderSnapshot;\n\n  /**\n   * External storage interfaces, present for `ref` mode to avoid revealing plaintext tokens.\n   * - `store` holds opaque encrypted blobs\n   * - `vault` handles AEAD encryption/decryption of secrets\n   */\n  store?: TokenStore;\n  vault?: TokenVault;\n};\n\nexport type TokenRefreshResult = {\n  /** New access token (if rotated). */\n  accessToken?: string;\n  /** New refresh token (optional). */\n  refreshToken?: string;\n  /** New absolute expiry (seconds since epoch preferred; ms also accepted). */\n  exp: number;\n  /** Optional opaque payload returned by the AS (id_token claims, etc.). */\n  payload?: Record<string, unknown>;\n};\n\nexport type TokenRefresher = (ctx: TokenRefreshCtx) => Promise<TokenRefreshResult>;\n\n// -----------------------------------------------------------------------------\n// Expiry helpers\n// -----------------------------------------------------------------------------\n\n/** Convert seconds/ms epoch or Date to epoch seconds. */\nexport function toEpochSeconds(exp?: number | Date): number | undefined {\n  if (exp == null) return undefined;\n  if (exp instanceof Date) return Math.floor(exp.getTime() / 1000);\n  // Heuristic: treat large numbers as ms\n  return exp > 1e12 ? Math.floor(exp / 1000) : Math.floor(exp);\n}\n\n/** Returns true if `exp` will occur within `skewSec` from now (or already past). */\nexport function isSoonExpiring(exp?: number | Date, skewSec = 60): boolean {\n  const expSec = toEpochSeconds(exp);\n  if (expSec == null) return false;\n  const now = Math.floor(Date.now() / 1000);\n  return expSec <= now + Math.max(0, skewSec);\n}\n\n/**\n * Synchronous check against a provider snapshot’s `exp` field.\n * Note: In `ref` mode the exact expiry may live in the store; this helper\n * intentionally remains synchronous and only uses the snapshot’s `exp`.\n */\nexport function isSoonExpiringProvider(\n  sessionLike: { authorizedProviders: Record<string, ProviderSnapshot> },\n  providerId: string,\n  skewSec = 60,\n): boolean {\n  const snap = sessionLike.authorizedProviders[providerId];\n  if (!snap) return false;\n  return isSoonExpiring(snap.exp, skewSec);\n}\n\n// -----------------------------------------------------------------------------\n// Optional utility: derive exp from JWT (unsigned decode)\n// -----------------------------------------------------------------------------\n\n/** Best-effort extraction of `exp` from a JWT without verification. */\nexport function tryJwtExp(token?: string): number | undefined {\n  if (!token) return undefined;\n  const parts = token.split('.');\n  if (parts.length < 2) return undefined;\n  try {\n    const json = JSON.parse(base64urlDecode(parts[1]));\n    const e = json?.exp;\n    return typeof e === 'number' ? toEpochSeconds(e) : undefined;\n  } catch {\n    return undefined;\n  }\n}\n\nfunction base64urlDecode(input: string): string {\n  // pad\n  const pad = input.length % 4 === 2 ? '==' : input.length % 4 === 3 ? '=' : '';\n  const s = input.replace(/-/g, '+').replace(/_/g, '/') + pad;\n  return Buffer.from(s, 'base64').toString('utf8');\n}\n"]}

package/src/auth/session/token.store.d.ts

@@ -0,0 +1,35 @@
+import type { EncBlob } from './token.vault';
+export type SecretRecord = {
+    id: string;
+    blob: EncBlob;
+    updatedAt: number;
+};
+export interface TokenStore {
+    /** Create or overwrite a blob under a stable id. */
+    put(id: string, blob: EncBlob): Promise<void>;
+    /** Fetch encrypted blob by id. */
+    get(id: string): Promise<SecretRecord | undefined>;
+    /** Delete a reference. */
+    del(id: string): Promise<void>;
+    /** Allocate a new id (opaque). */
+    allocId(): string;
+}
+/** In-memory reference store (dev/test). */
+export declare class MemoryTokenStore implements TokenStore {
+    private m;
+    allocId(): `${string}-${string}-${string}-${string}-${string}`;
+    put(id: string, blob: EncBlob): Promise<void>;
+    get(id: string): Promise<SecretRecord | undefined>;
+    del(id: string): Promise<void>;
+}
+/** Redis (sketch) — replace `any` with your redis client type. */
+export declare class RedisTokenStore implements TokenStore {
+    private readonly redis;
+    private readonly ns;
+    constructor(redis: any, ns?: string);
+    allocId(): `${string}-${string}-${string}-${string}-${string}`;
+    key(id: string): string;
+    put(id: string, blob: EncBlob): Promise<void>;
+    get(id: string): Promise<SecretRecord | undefined>;
+    del(id: string): Promise<void>;
+}

package/src/auth/session/token.store.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisTokenStore = exports.MemoryTokenStore = void 0;
+// auth/session/token.store.ts
+const node_crypto_1 = require("node:crypto");
+/** In-memory reference store (dev/test). */
+class MemoryTokenStore {
+    m = new Map();
+    allocId() {
+        return (0, node_crypto_1.randomUUID)();
+    }
+    async put(id, blob) {
+        this.m.set(id, { id, blob, updatedAt: Date.now() });
+    }
+    async get(id) {
+        return this.m.get(id);
+    }
+    async del(id) {
+        this.m.delete(id);
+    }
+}
+exports.MemoryTokenStore = MemoryTokenStore;
+/** Redis (sketch) — replace `any` with your redis client type. */
+class RedisTokenStore {
+    redis;
+    ns;
+    constructor(redis, ns = 'tok:') {
+        this.redis = redis;
+        this.ns = ns;
+    }
+    allocId() {
+        return (0, node_crypto_1.randomUUID)();
+    }
+    key(id) {
+        return `${this.ns}${id}`;
+    }
+    async put(id, blob) {
+        const rec = JSON.stringify({ id, blob, updatedAt: Date.now() });
+        // Optional: set EX by blob.exp if you want Redis eviction at token expiry
+        await this.redis.set(this.key(id), rec);
+    }
+    async get(id) {
+        const raw = await this.redis.get(this.key(id));
+        if (!raw)
+            return undefined;
+        return JSON.parse(raw);
+    }
+    async del(id) {
+        await this.redis.del(this.key(id));
+    }
+}
+exports.RedisTokenStore = RedisTokenStore;
+//# sourceMappingURL=token.store.js.map

package/src/auth/session/token.store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.store.js","sourceRoot":"","sources":["../../../../src/auth/session/token.store.ts"],"names":[],"mappings":";;;AAAA,8BAA8B;AAC9B,6CAAyC;AAoBzC,4CAA4C;AAC5C,MAAa,gBAAgB;IACnB,CAAC,GAAG,IAAI,GAAG,EAAwB,CAAC;IAC5C,OAAO;QACL,OAAO,IAAA,wBAAU,GAAE,CAAC;IACtB,CAAC;IACD,KAAK,CAAC,GAAG,CAAC,EAAU,EAAE,IAAa;QACjC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACtD,CAAC;IACD,KAAK,CAAC,GAAG,CAAC,EAAU;QAClB,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC;IACD,KAAK,CAAC,GAAG,CAAC,EAAU;QAClB,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACpB,CAAC;CACF;AAdD,4CAcC;AAED,kEAAkE;AAClE,MAAa,eAAe;IACG;IAA6B;IAA1D,YAA6B,KAAU,EAAmB,KAAK,MAAM;QAAxC,UAAK,GAAL,KAAK,CAAK;QAAmB,OAAE,GAAF,EAAE,CAAS;IAAG,CAAC;IACzE,OAAO;QACL,OAAO,IAAA,wBAAU,GAAE,CAAC;IACtB,CAAC;IACD,GAAG,CAAC,EAAU;QACZ,OAAO,GAAG,IAAI,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC;IAC3B,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,EAAU,EAAE,IAAa;QACjC,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QAChE,0EAA0E;QAC1E,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;IAC1C,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,EAAU;QAClB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;QAC/C,IAAI,CAAC,GAAG;YAAE,OAAO,SAAS,CAAC;QAC3B,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAiB,CAAC;IACzC,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,EAAU;QAClB,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IACrC,CAAC;CACF;AAxBD,0CAwBC","sourcesContent":["// auth/session/token.store.ts\nimport { randomUUID } from 'node:crypto';\nimport type { EncBlob } from './token.vault';\n\nexport type SecretRecord = {\n  id: string; // opaque reference id\n  blob: EncBlob; // encrypted token\n  updatedAt: number; // ms\n};\n\nexport interface TokenStore {\n  /** Create or overwrite a blob under a stable id. */\n  put(id: string, blob: EncBlob): Promise<void>;\n  /** Fetch encrypted blob by id. */\n  get(id: string): Promise<SecretRecord | undefined>;\n  /** Delete a reference. */\n  del(id: string): Promise<void>;\n  /** Allocate a new id (opaque). */\n  allocId(): string;\n}\n\n/** In-memory reference store (dev/test). */\nexport class MemoryTokenStore implements TokenStore {\n  private m = new Map<string, SecretRecord>();\n  allocId() {\n    return randomUUID();\n  }\n  async put(id: string, blob: EncBlob) {\n    this.m.set(id, { id, blob, updatedAt: Date.now() });\n  }\n  async get(id: string) {\n    return this.m.get(id);\n  }\n  async del(id: string) {\n    this.m.delete(id);\n  }\n}\n\n/** Redis (sketch) — replace `any` with your redis client type. */\nexport class RedisTokenStore implements TokenStore {\n  constructor(private readonly redis: any, private readonly ns = 'tok:') {}\n  allocId() {\n    return randomUUID();\n  }\n  key(id: string) {\n    return `${this.ns}${id}`;\n  }\n\n  async put(id: string, blob: EncBlob) {\n    const rec = JSON.stringify({ id, blob, updatedAt: Date.now() });\n    // Optional: set EX by blob.exp if you want Redis eviction at token expiry\n    await this.redis.set(this.key(id), rec);\n  }\n\n  async get(id: string) {\n    const raw = await this.redis.get(this.key(id));\n    if (!raw) return undefined;\n    return JSON.parse(raw) as SecretRecord;\n  }\n\n  async del(id: string) {\n    await this.redis.del(this.key(id));\n  }\n}\n"]}

package/src/auth/session/token.vault.d.ts

@@ -0,0 +1,26 @@
+export type EncBlob = {
+    alg: 'A256GCM';
+    kid: string;
+    iv: string;
+    tag: string;
+    data: string;
+    exp?: number;
+    meta?: Record<string, unknown>;
+};
+export type VaultKey = {
+    kid: string;
+    key: Buffer;
+};
+export declare class TokenVault {
+    /** Active key used for new encryptions */
+    private active;
+    /** All known keys by kid for decryption (includes active) */
+    private keys;
+    constructor(keys: VaultKey[]);
+    rotateTo(k: VaultKey): void;
+    encrypt(plaintext: string, opts?: {
+        exp?: number;
+        meta?: Record<string, unknown>;
+    }): EncBlob;
+    decrypt(blob: EncBlob): string;
+}

package/src/auth/session/token.vault.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenVault = void 0;
+const tslib_1 = require("tslib");
+// auth/session/token.vault.ts
+const node_crypto_1 = tslib_1.__importDefault(require("node:crypto"));
+class TokenVault {
+    /** Active key used for new encryptions */
+    active;
+    /** All known keys by kid for decryption (includes active) */
+    keys = new Map();
+    constructor(keys) {
+        if (!Array.isArray(keys) || keys.length === 0) {
+            throw new Error('TokenVault requires at least one key');
+        }
+        // first is active by convention
+        this.active = keys[0];
+        for (const k of keys)
+            this.keys.set(k.kid, k.key);
+    }
+    rotateTo(k) {
+        this.active = k;
+        this.keys.set(k.kid, k.key);
+    }
+    encrypt(plaintext, opts) {
+        const iv = node_crypto_1.default.randomBytes(12);
+        const cipher = node_crypto_1.default.createCipheriv('aes-256-gcm', this.active.key, iv);
+        const data = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+        const tag = cipher.getAuthTag();
+        return {
+            alg: 'A256GCM',
+            kid: this.active.kid,
+            iv: iv.toString('base64url'),
+            tag: tag.toString('base64url'),
+            data: data.toString('base64url'),
+            exp: opts?.exp,
+            meta: opts?.meta,
+        };
+    }
+    decrypt(blob) {
+        const key = this.keys.get(blob.kid);
+        if (!key)
+            throw new Error(`vault_unknown_kid:${blob.kid}`);
+        const iv = Buffer.from(blob.iv, 'base64url');
+        const tag = Buffer.from(blob.tag, 'base64url');
+        const data = Buffer.from(blob.data, 'base64url');
+        const decipher = node_crypto_1.default.createDecipheriv('aes-256-gcm', key, iv);
+        decipher.setAuthTag(tag);
+        const out = Buffer.concat([decipher.update(data), decipher.final()]);
+        return out.toString('utf8');
+    }
+}
+exports.TokenVault = TokenVault;
+//# sourceMappingURL=token.vault.js.map

package/src/auth/session/token.vault.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.vault.js","sourceRoot":"","sources":["../../../../src/auth/session/token.vault.ts"],"names":[],"mappings":";;;;AAAA,8BAA8B;AAC9B,sEAAiC;AAcjC,MAAa,UAAU;IACrB,0CAA0C;IAClC,MAAM,CAAW;IACzB,6DAA6D;IACrD,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAC;IAEzC,YAAY,IAAgB;QAC1B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC9C,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;QAC1D,CAAC;QACD,gCAAgC;QAChC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACtB,KAAK,MAAM,CAAC,IAAI,IAAI;YAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;IACpD,CAAC;IAED,QAAQ,CAAC,CAAW;QAClB,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;QAChB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IAED,OAAO,CAAC,SAAiB,EAAE,IAAuD;QAChF,MAAM,EAAE,GAAG,qBAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;QAClC,MAAM,MAAM,GAAG,qBAAM,CAAC,cAAc,CAAC,aAAa,EAAE,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACzE,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAC/E,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC;QAChC,OAAO;YACL,GAAG,EAAE,SAAS;YACd,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,GAAG;YACpB,EAAE,EAAE,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC;YAC5B,GAAG,EAAE,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC;YAC9B,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC;YAChC,GAAG,EAAE,IAAI,EAAE,GAAG;YACd,IAAI,EAAE,IAAI,EAAE,IAAI;SACjB,CAAC;IACJ,CAAC;IAED,OAAO,CAAC,IAAa;QACnB,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACpC,IAAI,CAAC,GAAG;YAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QAC3D,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,WAAW,CAAC,CAAC;QAC7C,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;QAC/C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;QACjD,MAAM,QAAQ,GAAG,qBAAM,CAAC,gBAAgB,CAAC,aAAa,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;QACjE,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;QACzB,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QACrE,OAAO,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;CACF;AA/CD,gCA+CC","sourcesContent":["// auth/session/token.vault.ts\nimport crypto from 'node:crypto';\n\nexport type EncBlob = {\n  alg: 'A256GCM';\n  kid: string; // master key id\n  iv: string; // base64url\n  tag: string; // base64url\n  data: string; // base64url\n  exp?: number; // optional epoch seconds\n  meta?: Record<string, unknown>;\n};\n\nexport type VaultKey = { kid: string; key: Buffer };\n\nexport class TokenVault {\n  /** Active key used for new encryptions */\n  private active: VaultKey;\n  /** All known keys by kid for decryption (includes active) */\n  private keys = new Map<string, Buffer>();\n\n  constructor(keys: VaultKey[]) {\n    if (!Array.isArray(keys) || keys.length === 0) {\n      throw new Error('TokenVault requires at least one key');\n    }\n    // first is active by convention\n    this.active = keys[0];\n    for (const k of keys) this.keys.set(k.kid, k.key);\n  }\n\n  rotateTo(k: VaultKey) {\n    this.active = k;\n    this.keys.set(k.kid, k.key);\n  }\n\n  encrypt(plaintext: string, opts?: { exp?: number; meta?: Record<string, unknown> }): EncBlob {\n    const iv = crypto.randomBytes(12);\n    const cipher = crypto.createCipheriv('aes-256-gcm', this.active.key, iv);\n    const data = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);\n    const tag = cipher.getAuthTag();\n    return {\n      alg: 'A256GCM',\n      kid: this.active.kid,\n      iv: iv.toString('base64url'),\n      tag: tag.toString('base64url'),\n      data: data.toString('base64url'),\n      exp: opts?.exp,\n      meta: opts?.meta,\n    };\n  }\n\n  decrypt(blob: EncBlob): string {\n    const key = this.keys.get(blob.kid);\n    if (!key) throw new Error(`vault_unknown_kid:${blob.kid}`);\n    const iv = Buffer.from(blob.iv, 'base64url');\n    const tag = Buffer.from(blob.tag, 'base64url');\n    const data = Buffer.from(blob.data, 'base64url');\n    const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);\n    decipher.setAuthTag(tag);\n    const out = Buffer.concat([decipher.update(data), decipher.final()]);\n    return out.toString('utf8');\n  }\n}\n"]}

package/src/auth/session/utils/auth-token.utils.d.ts

@@ -0,0 +1,11 @@
+import { UserClaim } from '../../../common';
+export declare function isJwt(token: string | undefined): boolean;
+/**
+ * If the token is a JWT, returns the raw signature segment (3rd part) as base64url.
+ * Otherwise, returns a stable SHA-256(base64url) fingerprint of the whole token,
+ * so we can still bind a session id to "this Authorization" deterministically.
+ */
+export declare function getTokenSignatureFingerprint(token: string): string;
+/** Best-effort typed user derivation from claims */
+export declare function deriveTypedUser(claims: Record<string, any>): UserClaim;
+export declare function extractBearerToken(header?: string): string | undefined;

package/src/auth/session/utils/auth-token.utils.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isJwt = isJwt;
+exports.getTokenSignatureFingerprint = getTokenSignatureFingerprint;
+exports.deriveTypedUser = deriveTypedUser;
+exports.extractBearerToken = extractBearerToken;
+function isJwt(token) {
+    if (!token)
+        return false;
+    return token.split('.').length === 3;
+}
+/**
+ * If the token is a JWT, returns the raw signature segment (3rd part) as base64url.
+ * Otherwise, returns a stable SHA-256(base64url) fingerprint of the whole token,
+ * so we can still bind a session id to "this Authorization" deterministically.
+ */
+function getTokenSignatureFingerprint(token) {
+    if (isJwt(token)) {
+        return token.split('.')[2];
+    }
+    const crypto = require('crypto');
+    const digest = crypto.createHash('sha256').update(token).digest('base64');
+    return digest.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
+}
+/** Safely extracts a claim value if it matches the expected type */
+function extractClaimValue(claims, key, validator) {
+    const value = claims[key];
+    return validator(value) ? value : undefined;
+}
+/** Type guards for claim validation */
+const isString = (value) => typeof value === 'string';
+const isNumber = (value) => typeof value === 'number';
+const isStringOrStringArray = (value) => typeof value === 'string' || Array.isArray(value);
+/** Best-effort typed user derivation from claims */
+function deriveTypedUser(claims) {
+    return {
+        ...claims,
+        iss: extractClaimValue(claims, 'iss', isString),
+        sid: extractClaimValue(claims, 'sid', isString),
+        sub: extractClaimValue(claims, 'sub', isString),
+        exp: extractClaimValue(claims, 'exp', isNumber),
+        iat: extractClaimValue(claims, 'iat', isNumber),
+        aud: extractClaimValue(claims, 'aud', isStringOrStringArray),
+        email: extractClaimValue(claims, 'email', isString),
+        preferred_username: extractClaimValue(claims, 'preferred_username', isString),
+        username: extractClaimValue(claims, 'username', isString),
+        name: extractClaimValue(claims, 'name', isString),
+        picture: extractClaimValue(claims, 'picture', isString),
+    };
+}
+function extractBearerToken(header) {
+    if (!header)
+        return undefined;
+    const m = header.match(/^\s*Bearer\s+(.+)\s*$/i);
+    return m ? m[1].trim() : undefined;
+}
+//# sourceMappingURL=auth-token.utils.js.map

package/src/auth/session/utils/auth-token.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-token.utils.js","sourceRoot":"","sources":["../../../../../src/auth/session/utils/auth-token.utils.ts"],"names":[],"mappings":"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","sourcesContent":["// auth/session/utils/auth-token.utils.ts\nimport { UserClaim } from '../../../common';\n\nexport function isJwt(token: string | undefined): boolean {\n  if (!token) return false;\n  return token.split('.').length === 3;\n}\n\n/**\n * If the token is a JWT, returns the raw signature segment (3rd part) as base64url.\n * Otherwise, returns a stable SHA-256(base64url) fingerprint of the whole token,\n * so we can still bind a session id to \"this Authorization\" deterministically.\n */\nexport function getTokenSignatureFingerprint(token: string): string {\n  if (isJwt(token)) {\n    return token.split('.')[2]!;\n  }\n  const crypto = require('crypto') as typeof import('crypto');\n  const digest = crypto.createHash('sha256').update(token).digest('base64');\n  return digest.replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/g, '');\n}\n\n/** Safely extracts a claim value if it matches the expected type */\nfunction extractClaimValue<T>(\n  claims: Record<string, any>,\n  key: string,\n  validator: (value: any) => value is T,\n): T | undefined {\n  const value = claims[key];\n  return validator(value) ? value : undefined;\n}\n\n/** Type guards for claim validation */\nconst isString = (value: any): value is string => typeof value === 'string';\nconst isNumber = (value: any): value is number => typeof value === 'number';\nconst isStringOrStringArray = (value: any): value is string | string[] =>\n  typeof value === 'string' || Array.isArray(value);\n\n/** Best-effort typed user derivation from claims */\nexport function deriveTypedUser(claims: Record<string, any>): UserClaim {\n  return {\n    ...claims,\n    iss: extractClaimValue(claims, 'iss', isString)!,\n    sid: extractClaimValue(claims, 'sid', isString),\n    sub: extractClaimValue(claims, 'sub', isString)!,\n    exp: extractClaimValue(claims, 'exp', isNumber),\n    iat: extractClaimValue(claims, 'iat', isNumber),\n    aud: extractClaimValue(claims, 'aud', isStringOrStringArray),\n    email: extractClaimValue(claims, 'email', isString),\n    preferred_username: extractClaimValue(claims, 'preferred_username', isString),\n    username: extractClaimValue(claims, 'username', isString),\n    name: extractClaimValue(claims, 'name', isString),\n    picture: extractClaimValue(claims, 'picture', isString),\n  };\n}\n\nexport function extractBearerToken(header?: string): string | undefined {\n  if (!header) return undefined;\n  const m = header.match(/^\\s*Bearer\\s+(.+)\\s*$/i);\n  return m ? m[1].trim() : undefined;\n}\n"]}

package/src/auth/session/utils/session-id.utils.d.ts

@@ -0,0 +1,17 @@
+import { HttpRequestIntent, SessionIdPayload } from '../../../common';
+export declare function encryptJson(obj: unknown): string;
+/**
+ * Validates an existing session header OR creates a fresh one.
+ * - Valid: nodeId matches local, authSig matches current Authorization
+ * - On any mismatch/decrypt error → generate new
+ */
+export declare function parseSessionHeader(sessionHeader: string | undefined, token: string): {
+    id: string;
+    payload: SessionIdPayload;
+} | undefined;
+export declare function createSessionId(protocol: HttpRequestIntent, token: string): {
+    id: string;
+    payload: SessionIdPayload;
+};
+export declare function generateSessionCookie(sessionId: string, ttlInMinutes?: number): string;
+export declare function extractSessionFromCookie(cookie?: string): string | undefined;

package/src/auth/session/utils/session-id.utils.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encryptJson = encryptJson;
+exports.parseSessionHeader = parseSessionHeader;
+exports.createSessionId = createSessionId;
+exports.generateSessionCookie = generateSessionCookie;
+exports.extractSessionFromCookie = extractSessionFromCookie;
+// auth/session/utils/session-id.utils.ts
+const crypto_1 = require("crypto");
+const tiny_ttl_cache_1 = require("./tiny-ttl-cache");
+const auth_token_utils_1 = require("./auth-token.utils");
+// 5s TTL cache for decrypted headers
+const cache = new tiny_ttl_cache_1.TinyTtlCache(5000);
+// Single-process machine id generated at server launch
+const MACHINE_ID = (() => {
+    // Prefer an injected env (stable across restarts) if you have one; else random per launch:
+    return process.env['MACHINE_ID'] || (0, crypto_1.randomUUID)(); // TODO: move to gateway config module
+})();
+// Symmetric key derived from secret or machine id (stable for the process)
+function getKey() {
+    const base = process.env['MCP_SESSION_SECRET'] || MACHINE_ID; // TODO: move to gateway config module
+    return (0, crypto_1.createHash)('sha256').update(base).digest(); // 32 bytes
+}
+function b64urlEncode(buf) {
+    return buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
+}
+function b64urlDecode(s) {
+    const pad = 4 - (s.length % 4);
+    const base64 = s.replace(/-/g, '+').replace(/_/g, '/') + (pad < 4 ? '='.repeat(pad) : '');
+    return Buffer.from(base64, 'base64');
+}
+function encryptJson(obj) {
+    const key = getKey();
+    const iv = (0, crypto_1.randomBytes)(12); // AES-GCM 96-bit IV
+    const cipher = (0, crypto_1.createCipheriv)('aes-256-gcm', key, iv);
+    const pt = Buffer.from(JSON.stringify(obj), 'utf8');
+    const ct = Buffer.concat([cipher.update(pt), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    // Pack iv.tag.ct as base64url(iv.tag.ct)
+    return `${b64urlEncode(iv)}.${b64urlEncode(tag)}.${b64urlEncode(ct)}`;
+}
+function decryptSessionId(sessionId, sig) {
+    const key = getKey();
+    const [ivB64, tagB64, ctB64] = sessionId.split('.');
+    if (!ivB64 || !tagB64 || !ctB64)
+        return null;
+    try {
+        const iv = b64urlDecode(ivB64);
+        const tag = b64urlDecode(tagB64);
+        const ct = b64urlDecode(ctB64);
+        const decipher = (0, crypto_1.createDecipheriv)('aes-256-gcm', key, iv);
+        decipher.setAuthTag(tag);
+        const pt = Buffer.concat([decipher.update(ct), decipher.final()]);
+        const dec = JSON.parse(pt.toString('utf8'));
+        if (typeof dec.nodeId === 'string' &&
+            typeof dec.authSig === 'string' &&
+            typeof dec.uuid === 'string' &&
+            typeof dec.iat === 'number' &&
+            dec.authSig === sig) {
+            return dec;
+        }
+        throw new Error('Invalid session id');
+    }
+    catch {
+        return null;
+    }
+}
+function nowSec() {
+    return Math.floor(Date.now() / 1000);
+}
+/**
+ * Validates an existing session header OR creates a fresh one.
+ * - Valid: nodeId matches local, authSig matches current Authorization
+ * - On any mismatch/decrypt error → generate new
+ */
+function parseSessionHeader(sessionHeader, token) {
+    const currentAuthSig = (0, auth_token_utils_1.getTokenSignatureFingerprint)(token);
+    if (sessionHeader) {
+        const cached = cache.get(sessionHeader);
+        if (cached) {
+            if (cached.authSig === currentAuthSig) {
+                return { id: sessionHeader, payload: cached };
+            }
+            // fallthrough to regenerate if mismatch
+        }
+        const dec = decryptSessionId(sessionHeader, currentAuthSig);
+        if (dec) {
+            cache.set(sessionHeader, dec);
+            return { id: sessionHeader, payload: dec };
+        }
+    }
+    return undefined;
+    // // Create fresh
+    // const decodedSse: SessionIdPayload = {
+    //   nodeId: MACHINE_ID,
+    //   authSig: currentAuthSig,
+    //   uuid: randomUUID(),
+    //   iat: nowSec(),
+    // };
+    // const header = encryptJson(decoded);
+    // const headerSse = encryptJson(decodedSse);
+    // cache.set(header, decoded);
+    // cache.set(headerSse, decodedSse);
+    // return { header, decoded, headerSse, isNew: true };
+}
+function createSessionId(protocol, token) {
+    const authSig = (0, auth_token_utils_1.getTokenSignatureFingerprint)(token);
+    const payload = {
+        nodeId: MACHINE_ID,
+        authSig,
+        uuid: (0, crypto_1.randomUUID)(),
+        iat: nowSec(),
+        protocol,
+    };
+    const id = encryptJson(payload);
+    cache.set(id, payload);
+    return { id, payload };
+}
+function generateSessionCookie(sessionId, ttlInMinutes = 60 * 24) {
+    const expires = new Date(Date.now() + ttlInMinutes * 60 * 1000).toUTCString();
+    return `mcp_session_id=${sessionId}; Path=/; Expires=${expires}; HttpOnly; SameSite=Lax`;
+}
+function extractSessionFromCookie(cookie) {
+    if (!cookie)
+        return undefined;
+    const m = cookie.match(/(^|;)\s*mcp_session_id\s*=\s*([^;]*)/);
+    return m ? m[2] : undefined;
+}
+//# sourceMappingURL=session-id.utils.js.map