@frontmcp/auth 0.0.1 → 0.8.0

package/jwks/dev-key-persistence.d.ts

@@ -0,0 +1,70 @@
+import { JSONWebKeySet } from 'jose';
+/**
+ * Data structure for persisted development keys
+ * @deprecated Use `AsymmetricKeyData` from `@frontmcp/utils` instead.
+ */
+export interface DevKeyData {
+    /** Key ID (kid) */
+    kid: string;
+    /** Private key in JWK format (portable) */
+    privateKey: JsonWebKey;
+    /** Public JWKS for verification */
+    publicJwk: JSONWebKeySet;
+    /** Key creation timestamp (ms) */
+    createdAt: number;
+    /** Algorithm used */
+    alg: 'RS256' | 'ES256';
+}
+/**
+ * Options for dev key persistence
+ */
+export interface DevKeyPersistenceOptions {
+    /**
+     * Path to store dev keys
+     * @default '.frontmcp/dev-keys.json'
+     */
+    keyPath?: string;
+    /**
+     * Enable persistence in production (NOT RECOMMENDED)
+     * @default false
+     */
+    forceEnable?: boolean;
+}
+/**
+ * Check if dev key persistence is enabled based on environment and options
+ * @deprecated Use `createKeyPersistence` from `@frontmcp/utils` instead.
+ */
+export declare function isDevKeyPersistenceEnabled(options?: DevKeyPersistenceOptions): boolean;
+/**
+ * Resolve the key file path
+ * @deprecated Use `createKeyPersistence` from `@frontmcp/utils` instead.
+ */
+export declare function resolveKeyPath(options?: DevKeyPersistenceOptions): string;
+/**
+ * Load persisted dev key from file
+ *
+ * @param options - Persistence options
+ * @returns The loaded key data or null if not found/invalid
+ * @deprecated Use `createKeyPersistence` from `@frontmcp/utils` and call `getAsymmetric(kid)` instead.
+ */
+export declare function loadDevKey(options?: DevKeyPersistenceOptions): Promise<DevKeyData | null>;
+/**
+ * Save dev key to file
+ *
+ * Uses atomic write (temp file + rename) to prevent corruption.
+ * Sets file permissions to 0o600 (owner read/write only) for security.
+ *
+ * @param keyData - Key data to persist
+ * @param options - Persistence options
+ * @returns true if save succeeded, false otherwise
+ * @deprecated Use `createKeyPersistence` from `@frontmcp/utils` and call `set(asymmetricKeyData)` instead.
+ */
+export declare function saveDevKey(keyData: DevKeyData, options?: DevKeyPersistenceOptions): Promise<boolean>;
+/**
+ * Delete persisted dev key
+ *
+ * @param options - Persistence options
+ * @deprecated Use `createKeyPersistence` from `@frontmcp/utils` and call `delete(kid)` instead.
+ */
+export declare function deleteDevKey(options?: DevKeyPersistenceOptions): Promise<void>;
+//# sourceMappingURL=dev-key-persistence.d.ts.map

package/jwks/dev-key-persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-key-persistence.d.ts","sourceRoot":"","sources":["../../src/jwks/dev-key-persistence.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,aAAa,EAAE,MAAM,MAAM,CAAC;AAIrC;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,mBAAmB;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,2CAA2C;IAC3C,UAAU,EAAE,UAAU,CAAC;IACvB,mCAAmC;IACnC,SAAS,EAAE,aAAa,CAAC;IACzB,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,qBAAqB;IACrB,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AA2GD;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,CAAC,EAAE,wBAAwB,GAAG,OAAO,CAUtF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE,wBAAwB,GAAG,MAAM,CAUzE;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,OAAO,CAAC,EAAE,wBAAwB,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CA6B/F;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,wBAAwB,GAAG,OAAO,CAAC,OAAO,CAAC,CAgC1G;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,OAAO,CAAC,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAWpF"}

package/jwks/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * JWKS Module
+ *
+ * JSON Web Key Set management for JWT signing and verification.
+ */
+export type { JwksServiceOptions, ProviderVerifyRef, VerifyResult, DevKeyPersistenceOptions } from './jwks.types';
+export { JwksService } from './jwks.service';
+export { trimSlash, normalizeIssuer, decodeJwtPayloadSafe } from './jwks.utils';
+/**
+ * Dev Key Persistence (DEPRECATED)
+ *
+ * These exports are deprecated. Use `createKeyPersistence` from `@frontmcp/utils` instead.
+ * They are kept for backwards compatibility and will be removed in a future major version.
+ *
+ * @deprecated Use `createKeyPersistence` from `@frontmcp/utils` instead.
+ */
+export { isDevKeyPersistenceEnabled, resolveKeyPath, loadDevKey, saveDevKey, deleteDevKey, } from './dev-key-persistence';
+/** @deprecated Use `AsymmetricKeyData` from `@frontmcp/utils` instead. */
+export type { DevKeyData } from './dev-key-persistence';
+//# sourceMappingURL=index.d.ts.map

package/jwks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/jwks/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,YAAY,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,YAAY,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAGlH,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAG7C,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEhF;;;;;;;GAOG;AACH,OAAO,EACL,0BAA0B,EAC1B,cAAc,EACd,UAAU,EACV,UAAU,EACV,YAAY,GACb,MAAM,uBAAuB,CAAC;AAC/B,0EAA0E;AAC1E,YAAY,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC"}

package/jwks/jwks.service.d.ts

@@ -0,0 +1,69 @@
+import { JSONWebKeySet } from 'jose';
+import { JwksServiceOptions, ProviderVerifyRef, VerifyResult } from './jwks.types';
+export declare class JwksService {
+    private readonly opts;
+    private warnedProviders;
+    private orchestratorKey;
+    private providerJwks;
+    private keyInitialized;
+    private keyInitPromise;
+    private keyPersistence?;
+    constructor(opts?: JwksServiceOptions);
+    /**
+     * Check if key persistence should be enabled.
+     * Enabled in development by default, disabled in production unless forceEnable.
+     */
+    private shouldEnablePersistence;
+    /**
+     * Get or create the KeyPersistence instance.
+     * Returns null if persistence is disabled.
+     */
+    private getKeyPersistence;
+    /** Gateway's public JWKS (publish at /.well-known/jwks.json when orchestrated). */
+    getPublicJwks(): Promise<JSONWebKeySet>;
+    /** Verify a token issued by the gateway itself (orchestrated mode). */
+    verifyGatewayToken(token: string, expectedIssuer: string): Promise<VerifyResult>;
+    /**
+     * Verify a token against candidate transparent providers.
+     * Ensures JWKS are available (cached/TTL/AS discovery) per provider.
+     */
+    verifyTransparentToken(token: string, candidates: ProviderVerifyRef[]): Promise<VerifyResult>;
+    /**
+     * Check if the error is due to weak RSA key (< 2048 bits)
+     */
+    private isWeakKeyError;
+    /**
+     * Fallback verification for providers using RSA keys smaller than 2048 bits.
+     * Logs a security warning but allows verification to proceed.
+     */
+    private verifyWithWeakKey;
+    /**
+     * Find a matching key from JWKS based on token header
+     */
+    private findMatchingKey;
+    /** Directly set provider JWKS (e.g., inline keys from config). */
+    setProviderJwks(providerId: string, jwks: JSONWebKeySet): void;
+    /**
+     * Ensure JWKS for a provider:
+     *   1) inline jwks (if provided) → cache & return
+     *   2) cached & fresh (TTL)      → return
+     *   3) explicit jwksUri          → fetch, cache, return
+     *   4) discover jwks_uri via AS  → fetch AS metadata, then jwks_uri, cache, return
+     */
+    getJwksForProvider(ref: ProviderVerifyRef): Promise<JSONWebKeySet | undefined>;
+    /** Return the orchestrator public JWKS (generates/rotates as needed). */
+    getOrchestratorJwks(): Promise<JSONWebKeySet>;
+    /** Return private signing key + kid for issuing orchestrator tokens. */
+    getOrchestratorSigningKey(): Promise<{
+        kid: string;
+        key: import('node:crypto').KeyObject;
+        alg: string;
+    }>;
+    private tryFetchJwks;
+    private tryFetchAsMeta;
+    private fetchJson;
+    private ensureOrchestratorKey;
+    private initializeOrchestratorKey;
+    private generateKey;
+}
+//# sourceMappingURL=jwks.service.d.ts.map

package/jwks/jwks.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwks.service.d.ts","sourceRoot":"","sources":["../../src/jwks/jwks.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAuD,aAAa,EAAO,MAAM,MAAM,CAAC;AAE/F,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAWnF,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAEnB;IAEF,OAAO,CAAC,eAAe,CAAqB;IAG5C,OAAO,CAAC,eAAe,CAKrB;IAGF,OAAO,CAAC,YAAY,CAAiE;IAGrF,OAAO,CAAC,cAAc,CAAS;IAE/B,OAAO,CAAC,cAAc,CAA4B;IAElD,OAAO,CAAC,cAAc,CAAC,CAAiB;gBAE5B,IAAI,CAAC,EAAE,kBAAkB;IAcrC;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAM/B;;;OAGG;YACW,iBAAiB;IAc/B,mFAAmF;IAC7E,aAAa,IAAI,OAAO,CAAC,aAAa,CAAC;IAQ7C,uEAAuE;IACjE,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAsCtF;;;OAGG;IACG,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,iBAAiB,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC;IAqDnG;;OAEG;IACH,OAAO,CAAC,cAAc;IAatB;;;OAGG;YACW,iBAAiB;IA4E/B;;OAEG;IACH,OAAO,CAAC,eAAe;IAqBvB,kEAAkE;IAClE,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa;IAIvD;;;;;;OAMG;IACG,kBAAkB,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC;IAmCpF,yEAAyE;IACnE,mBAAmB,IAAI,OAAO,CAAC,aAAa,CAAC;IAKnD,wEAAwE;IAClE,yBAAyB,IAAI,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,OAAO,aAAa,EAAE,SAAS,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;YAShG,YAAY;YAaZ,cAAc;YAQd,SAAS;YAgBT,qBAAqB;YAyBrB,yBAAyB;IA0DvC,OAAO,CAAC,WAAW;CAgBpB"}

package/jwks/jwks.types.d.ts

@@ -0,0 +1,33 @@
+import { JSONWebKeySet } from 'jose';
+import { DevKeyPersistenceOptions } from './dev-key-persistence';
+export type JwksServiceOptions = {
+    orchestratorAlg?: 'RS256' | 'ES256';
+    rotateDays?: number;
+    /** TTL (ms) for cached provider JWKS before attempting refresh. Default: 6h */
+    providerJwksTtlMs?: number;
+    /** Timeout (ms) for network metadata/JWKS fetches. Default: 5s */
+    networkTimeoutMs?: number;
+    /**
+     * Options for dev key persistence (development mode only by default).
+     * When enabled, keys are saved to a file and reloaded on server restart.
+     */
+    devKeyPersistence?: DevKeyPersistenceOptions;
+};
+export type { DevKeyPersistenceOptions };
+/** Rich descriptor used by verification & fetching */
+export type ProviderVerifyRef = {
+    id: string;
+    issuerUrl: string;
+    jwksUri?: string;
+    jwks?: JSONWebKeySet;
+};
+export type VerifyResult = {
+    ok: boolean;
+    issuer?: string;
+    sub?: string;
+    providerId?: string;
+    header?: Record<string, unknown>;
+    payload?: Record<string, unknown>;
+    error?: string;
+};
+//# sourceMappingURL=jwks.types.d.ts.map

package/jwks/jwks.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwks.types.d.ts","sourceRoot":"","sources":["../../src/jwks/jwks.types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,MAAM,CAAC;AACrC,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAEjE,MAAM,MAAM,kBAAkB,GAAG;IAC/B,eAAe,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+EAA+E;IAC/E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kEAAkE;IAClE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,wBAAwB,CAAC;CAC9C,CAAC;AAEF,YAAY,EAAE,wBAAwB,EAAE,CAAC;AAEzC,sDAAsD;AACtD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,aAAa,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC"}

package/jwks/jwks.utils.d.ts

@@ -0,0 +1,5 @@
+export declare function trimSlash(s: string): string;
+export declare function normalizeIssuer(u?: string): string;
+/** Safe, no-verify JWT payload decode (returns undefined on error). */
+export declare function decodeJwtPayloadSafe(token?: string): Record<string, unknown> | undefined;
+//# sourceMappingURL=jwks.utils.d.ts.map

package/jwks/jwks.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwks.utils.d.ts","sourceRoot":"","sources":["../../src/jwks/jwks.utils.ts"],"names":[],"mappings":"AAAA,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,UAElC;AACD,wBAAgB,eAAe,CAAC,CAAC,CAAC,EAAE,MAAM,UAEzC;AAED,uEAAuE;AACvE,wBAAgB,oBAAoB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAgBxF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/auth",
-  "version": "0.0.1",
+  "version": "0.8.0",
   "description": "FrontMCP Auth - Authentication, session management, and credential vault",
   "author": "AgentFront <info@agentfront.dev>",
   "homepage": "https://docs.agentfront.dev",
@@ -50,7 +50,7 @@
     "zod": "^4.0.0"
   },
   "dependencies": {
-    "@frontmcp/utils": "0.7.2",
+    "@frontmcp/utils": "0.8.0",
     "jose": "^6.0.0"
   },
   "devDependencies": {