@frontmcp/auth 0.0.1 → 0.8.0

package/README.md

@@ -0,0 +1,11 @@
+# auth
+
+This library was generated with [Nx](https://nx.dev).
+
+## Building
+
+Run `nx build auth` to build the library.
+
+## Running unit tests
+
+Run `nx test auth` to execute the unit tests via [Jest](https://jestjs.io).

package/authorization/authorization.types.d.ts

@@ -0,0 +1,236 @@
+/**
+ * Authorization Types
+ *
+ * Core types for authorization, user identity, and progressive auth.
+ * These types are portable and can be used across different implementations.
+ */
+import { z } from 'zod';
+/**
+ * Authentication mode determining how tokens are handled
+ */
+export type AuthMode = 'public' | 'transparent' | 'orchestrated';
+/**
+ * Zod schema for AuthMode
+ */
+export declare const authModeSchema: z.ZodEnum<{
+    public: "public";
+    transparent: "transparent";
+    orchestrated: "orchestrated";
+}>;
+/**
+ * User identity from authentication
+ */
+export interface AuthUser {
+    /** Subject identifier */
+    sub: string;
+    /** Display name */
+    name?: string;
+    /** Email address */
+    email?: string;
+    /** Profile picture URL */
+    picture?: string;
+    /** Whether this is an anonymous user */
+    anonymous?: boolean;
+}
+/**
+ * Zod schema for AuthUser
+ */
+export declare const authUserSchema: z.ZodObject<{
+    sub: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    email: z.ZodOptional<z.ZodString>;
+    picture: z.ZodOptional<z.ZodString>;
+    anonymous: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * Authorized tool entry
+ */
+export interface AuthorizedTool {
+    /** Execution path: [appId, toolId] */
+    executionPath: [appId: string, toolId: string];
+    /** Required scopes for this tool */
+    scopes?: string[];
+    /** Additional tool metadata */
+    details?: Record<string, unknown>;
+}
+/**
+ * Zod schema for AuthorizedTool
+ */
+export declare const authorizedToolSchema: z.ZodObject<{
+    executionPath: z.ZodTuple<[z.ZodString, z.ZodString], null>;
+    scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+/**
+ * Authorized prompt entry
+ */
+export interface AuthorizedPrompt {
+    /** Execution path: [appId, promptId] */
+    executionPath: [appId: string, promptId: string];
+    /** Required scopes for this prompt */
+    scopes?: string[];
+    /** Additional prompt metadata */
+    details?: Record<string, unknown>;
+}
+/**
+ * Zod schema for AuthorizedPrompt
+ */
+export declare const authorizedPromptSchema: z.ZodObject<{
+    executionPath: z.ZodTuple<[z.ZodString, z.ZodString], null>;
+    scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+/**
+ * LLM-safe session context (no tokens exposed)
+ */
+export interface LLMSafeAuthContext {
+    /** Authorization ID */
+    authorizationId: string;
+    /** Session ID */
+    sessionId: string;
+    /** Auth mode */
+    mode: AuthMode;
+    /** Whether anonymous */
+    isAnonymous: boolean;
+    /** User (sub and name only) */
+    user: {
+        sub: string;
+        name?: string;
+    };
+    /** Granted scopes */
+    scopes: string[];
+    /** Authorized tool IDs */
+    authorizedToolIds: string[];
+    /** Authorized prompt IDs */
+    authorizedPromptIds: string[];
+}
+/**
+ * Zod schema for LLMSafeAuthContext
+ */
+export declare const llmSafeAuthContextSchema: z.ZodObject<{
+    authorizationId: z.ZodString;
+    sessionId: z.ZodString;
+    mode: z.ZodEnum<{
+        public: "public";
+        transparent: "transparent";
+        orchestrated: "orchestrated";
+    }>;
+    isAnonymous: z.ZodBoolean;
+    user: z.ZodObject<{
+        sub: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    scopes: z.ZodArray<z.ZodString>;
+    authorizedToolIds: z.ZodArray<z.ZodString>;
+    authorizedPromptIds: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * State of app authorization within a session.
+ * Used for progressive authorization flow.
+ */
+export declare enum AppAuthState {
+    /** App has been fully authorized with tokens stored */
+    AUTHORIZED = "authorized",
+    /** User explicitly skipped this app during initial auth */
+    SKIPPED = "skipped",
+    /** App authorization is pending (not yet presented to user) */
+    PENDING = "pending"
+}
+/**
+ * Zod schema for AppAuthState enum
+ */
+export declare const appAuthStateSchema: z.ZodEnum<typeof AppAuthState>;
+/**
+ * App authorization record with state tracking.
+ * Stored server-side, NOT in JWT.
+ */
+export interface AppAuthorizationRecord {
+    /** App ID */
+    appId: string;
+    /** Current authorization state */
+    state: AppAuthState;
+    /** When the state was last changed (epoch ms) */
+    stateChangedAt: number;
+    /** Scopes granted for this app */
+    grantedScopes?: string[];
+    /** Auth provider ID used for this app */
+    authProviderId?: string;
+    /** Tool IDs accessible through this app authorization */
+    toolIds: string[];
+}
+/**
+ * Zod schema for AppAuthorizationRecord
+ */
+export declare const appAuthorizationRecordSchema: z.ZodObject<{
+    appId: z.ZodString;
+    state: z.ZodEnum<typeof AppAuthState>;
+    stateChangedAt: z.ZodNumber;
+    grantedScopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    authProviderId: z.ZodOptional<z.ZodString>;
+    toolIds: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Progressive auth session state.
+ * Tracks which apps are authorized, skipped, or pending.
+ * Stored server-side for security.
+ */
+export interface ProgressiveAuthState {
+    /** App authorization records by app ID */
+    apps: Record<string, AppAuthorizationRecord>;
+    /** Apps authorized during initial auth */
+    initiallyAuthorized: string[];
+    /** Apps skipped during initial auth */
+    initiallySkipped: string[];
+}
+/**
+ * Zod schema for ProgressiveAuthState
+ */
+export declare const progressiveAuthStateSchema: z.ZodObject<{
+    apps: z.ZodRecord<z.ZodString, z.ZodObject<{
+        appId: z.ZodString;
+        state: z.ZodEnum<typeof AppAuthState>;
+        stateChangedAt: z.ZodNumber;
+        grantedScopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        authProviderId: z.ZodOptional<z.ZodString>;
+        toolIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    initiallyAuthorized: z.ZodArray<z.ZodString>;
+    initiallySkipped: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Context for creating an authorization (portable version)
+ */
+export interface AuthorizationCreateCtx {
+    /** Unique ID (typically token signature fingerprint) */
+    id: string;
+    /** Whether this is anonymous */
+    isAnonymous: boolean;
+    /** User identity */
+    user: AuthUser;
+    /** JWT claims */
+    claims?: Record<string, unknown>;
+    /** Token expiration (epoch ms) */
+    expiresAt?: number;
+    /** Granted scopes */
+    scopes?: string[];
+    /** The original token (for transparent mode) */
+    token?: string;
+    /** Authorized apps */
+    authorizedApps?: Record<string, {
+        id: string;
+        toolIds: string[];
+    }>;
+    /** Authorized app IDs */
+    authorizedAppIds?: string[];
+    /** Authorized tools */
+    authorizedTools?: Record<string, AuthorizedTool>;
+    /** Authorized tool IDs */
+    authorizedToolIds?: string[];
+    /** Authorized prompts */
+    authorizedPrompts?: Record<string, AuthorizedPrompt>;
+    /** Authorized prompt IDs */
+    authorizedPromptIds?: string[];
+    /** Authorized resources */
+    authorizedResources?: string[];
+}
+//# sourceMappingURL=authorization.types.d.ts.map

package/authorization/authorization.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorization.types.d.ts","sourceRoot":"","sources":["../../src/authorization/authorization.types.ts"],"names":[],"mappings":"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"}

package/authorization/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Authorization Module
+ *
+ * Core types for authorization, user identity, and progressive auth.
+ */
+export type { AuthMode, AuthUser, AuthorizedTool, AuthorizedPrompt, LLMSafeAuthContext, AppAuthorizationRecord, ProgressiveAuthState, AuthorizationCreateCtx, } from './authorization.types';
+export { AppAuthState } from './authorization.types';
+export { authModeSchema, authUserSchema, authorizedToolSchema, authorizedPromptSchema, llmSafeAuthContextSchema, appAuthStateSchema, appAuthorizationRecordSchema, progressiveAuthStateSchema, } from './authorization.types';
+//# sourceMappingURL=index.d.ts.map

package/authorization/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/authorization/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,YAAY,EACV,QAAQ,EACR,QAAQ,EACR,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,EACtB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAGrD,OAAO,EACL,cAAc,EACd,cAAc,EACd,oBAAoB,EACpB,sBAAsB,EACtB,wBAAwB,EACxB,kBAAkB,EAClB,4BAA4B,EAC5B,0BAA0B,GAC3B,MAAM,uBAAuB,CAAC"}

package/cimd/cimd-redis.cache.d.ts

@@ -0,0 +1,111 @@
+import type { CimdCacheBackend, CimdCacheEntry, CimdCacheTtlConfig } from './cimd.cache';
+import type { ClientMetadataDocument, CimdCacheConfig } from './cimd.types';
+/**
+ * Redis-backed CIMD document cache.
+ *
+ * Stores cached CIMD documents in Redis with HTTP cache-aware TTLs.
+ * Suitable for production and distributed deployments.
+ *
+ * Key format: {keyPrefix}{sha256(clientId)}
+ * Value format: JSON-serialized CimdCacheEntry
+ *
+ * @example
+ * ```typescript
+ * const cache = new RedisCimdCache({
+ *   redis: { url: 'redis://localhost:6379' },
+ *   defaultTtlMs: 3600_000,
+ * });
+ * await cache.connect();
+ *
+ * // Cache will be usable after connect()
+ * await cache.set(clientId, document, headers);
+ * const entry = await cache.get(clientId);
+ *
+ * // Close when done
+ * await cache.close();
+ * ```
+ */
+export declare class RedisCimdCache implements CimdCacheBackend {
+    private readonly redis;
+    private readonly keyPrefix;
+    protected readonly config: CimdCacheTtlConfig;
+    constructor(config: CimdCacheConfig);
+    /**
+     * Connect to Redis.
+     * Must be called before using any cache operations.
+     */
+    connect(): Promise<void>;
+    /**
+     * Generate a Redis key for a client ID.
+     * Uses SHA-256 hash to handle URLs with special characters.
+     */
+    private cacheKey;
+    /**
+     * Get a cached entry by client_id.
+     *
+     * @param clientId - The client_id URL
+     * @returns The cached entry if valid, or undefined
+     */
+    get(clientId: string): Promise<CimdCacheEntry | undefined>;
+    /**
+     * Get a stale entry for conditional revalidation.
+     *
+     * @param clientId - The client_id URL
+     * @returns The stale entry (even if expired), or undefined if not cached
+     */
+    getStale(clientId: string): Promise<CimdCacheEntry | undefined>;
+    /**
+     * Store a document in the cache.
+     *
+     * @param clientId - The client_id URL
+     * @param document - The metadata document
+     * @param headers - HTTP response headers
+     */
+    set(clientId: string, document: ClientMetadataDocument, headers: Headers): Promise<void>;
+    /**
+     * Update an existing cache entry (after 304 Not Modified).
+     *
+     * @param clientId - The client_id URL
+     * @param headers - New HTTP headers with updated cache directives
+     */
+    revalidate(clientId: string, headers: Headers): Promise<boolean>;
+    /**
+     * Delete a cache entry.
+     *
+     * @param clientId - The client_id URL
+     * @returns true if an entry was deleted
+     */
+    delete(clientId: string): Promise<boolean>;
+    /**
+     * Get conditional request headers for a cached entry.
+     *
+     * @param clientId - The client_id URL
+     * @returns Headers for conditional request, or undefined if not cached
+     */
+    getConditionalHeaders(clientId: string): Promise<Record<string, string> | undefined>;
+    /**
+     * Clear all cached entries.
+     * Uses Redis SCAN to find and delete all keys with our prefix.
+     */
+    clear(): Promise<void>;
+    /**
+     * Get the number of cached entries.
+     * Uses Redis SCAN to count keys with our prefix.
+     */
+    size(): Promise<number>;
+    /**
+     * Remove expired entries.
+     *
+     * Note: Redis handles expiration automatically via TTL.
+     * This method is primarily for explicit cleanup of entries that are
+     * well past their HTTP cache expiration but still within Redis TTL.
+     *
+     * @returns Number of entries removed
+     */
+    cleanup(): Promise<number>;
+    /**
+     * Close the Redis connection.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=cimd-redis.cache.d.ts.map

package/cimd/cimd-redis.cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cimd-redis.cache.d.ts","sourceRoot":"","sources":["../../src/cimd/cimd-redis.cache.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEzF,OAAO,KAAK,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAa5E;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,cAAe,YAAW,gBAAgB;IACrD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsB;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;gBAElC,MAAM,EAAE,eAAe;IA+BnC;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAI9B;;;OAGG;IACH,OAAO,CAAC,QAAQ;IAKhB;;;;;OAKG;IACG,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IA0BhE;;;;;OAKG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAerE;;;;;;OAMG;IACG,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,sBAAsB,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAsB9F;;;;;OAKG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IA4BtE;;;;;OAKG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKhD;;;;;OAKG;IACG,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IA0B1F;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAO5B;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;IAK7B;;;;;;;;OAQG;IACG,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;IA2BhC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/cimd/cimd.cache.d.ts

@@ -0,0 +1,200 @@
+/**
+ * CIMD HTTP Cache-Aware Caching
+ *
+ * Implements caching for CIMD documents that respects HTTP cache headers
+ * like Cache-Control, Expires, ETag, and Last-Modified.
+ *
+ * Supports both in-memory and Redis backends.
+ */
+import type { ClientMetadataDocument, CimdCacheConfig } from './cimd.types';
+/**
+ * Cache entry for a CIMD document.
+ */
+export interface CimdCacheEntry {
+    /**
+     * The cached metadata document.
+     */
+    document: ClientMetadataDocument;
+    /**
+     * When the entry expires (Unix timestamp in ms).
+     */
+    expiresAt: number;
+    /**
+     * HTTP ETag for conditional requests.
+     */
+    etag?: string;
+    /**
+     * HTTP Last-Modified header value.
+     */
+    lastModified?: string;
+    /**
+     * When the entry was cached (Unix timestamp in ms).
+     */
+    cachedAt: number;
+}
+/**
+ * Headers relevant to caching.
+ */
+export interface CacheableHeaders {
+    'cache-control'?: string;
+    expires?: string;
+    etag?: string;
+    'last-modified'?: string;
+    age?: string;
+}
+/**
+ * TTL configuration for cache operations.
+ * This is the minimal config needed for cache TTL calculations.
+ */
+export interface CimdCacheTtlConfig {
+    defaultTtlMs: number;
+    maxTtlMs: number;
+    minTtlMs: number;
+}
+/**
+ * CIMD Cache Backend Interface.
+ *
+ * All cache operations are async to support both in-memory and Redis backends.
+ */
+export interface CimdCacheBackend {
+    /**
+     * Get a cached entry by client_id.
+     * Returns undefined if not cached or expired.
+     */
+    get(clientId: string): Promise<CimdCacheEntry | undefined>;
+    /**
+     * Get a stale entry for conditional revalidation.
+     * Returns the entry even if expired.
+     */
+    getStale(clientId: string): Promise<CimdCacheEntry | undefined>;
+    /**
+     * Store a document in the cache with headers for TTL computation.
+     */
+    set(clientId: string, document: ClientMetadataDocument, headers: Headers): Promise<void>;
+    /**
+     * Update an existing cache entry after 304 Not Modified.
+     */
+    revalidate(clientId: string, headers: Headers): Promise<boolean>;
+    /**
+     * Delete a cache entry.
+     */
+    delete(clientId: string): Promise<boolean>;
+    /**
+     * Get conditional request headers for a cached entry.
+     */
+    getConditionalHeaders(clientId: string): Promise<Record<string, string> | undefined>;
+    /**
+     * Clear all cached entries.
+     */
+    clear(): Promise<void>;
+    /**
+     * Get the number of cached entries.
+     */
+    size(): Promise<number>;
+    /**
+     * Remove expired entries.
+     * Returns the number of entries removed.
+     */
+    cleanup(): Promise<number>;
+    /**
+     * Close the cache backend (for Redis connections).
+     */
+    close?(): Promise<void>;
+}
+/**
+ * Parse cache-relevant headers from a Response or Headers object.
+ */
+export declare function extractCacheHeaders(headers: Headers): CacheableHeaders;
+/**
+ * Parse cache headers and compute TTL.
+ *
+ * @param headers - Cache-relevant headers
+ * @param config - Cache configuration with min/max/default TTL
+ * @returns Object with computed TTL and conditional request headers
+ */
+export declare function parseCacheHeaders(headers: CacheableHeaders, config: CimdCacheTtlConfig): {
+    ttlMs: number;
+    etag?: string;
+    lastModified?: string;
+};
+/**
+ * In-Memory CIMD document cache.
+ *
+ * Stores cached CIMD documents with HTTP cache-aware TTLs.
+ * Suitable for development and single-instance deployments.
+ */
+export declare class InMemoryCimdCache implements CimdCacheBackend {
+    private cache;
+    protected readonly config: CimdCacheTtlConfig;
+    constructor(config?: Partial<CimdCacheConfig>);
+    /**
+     * Get a cached entry by client_id.
+     *
+     * @param clientId - The client_id URL
+     * @returns The cached entry if valid, or undefined
+     */
+    get(clientId: string): Promise<CimdCacheEntry | undefined>;
+    /**
+     * Get a stale entry for conditional revalidation.
+     *
+     * @param clientId - The client_id URL
+     * @returns The stale entry (even if expired), or undefined if not cached
+     */
+    getStale(clientId: string): Promise<CimdCacheEntry | undefined>;
+    /**
+     * Store a document in the cache.
+     *
+     * @param clientId - The client_id URL
+     * @param document - The metadata document
+     * @param headers - HTTP response headers
+     */
+    set(clientId: string, document: ClientMetadataDocument, headers: Headers): Promise<void>;
+    /**
+     * Update an existing cache entry (after 304 Not Modified).
+     *
+     * @param clientId - The client_id URL
+     * @param headers - New HTTP headers with updated cache directives
+     */
+    revalidate(clientId: string, headers: Headers): Promise<boolean>;
+    /**
+     * Delete a cache entry.
+     *
+     * @param clientId - The client_id URL
+     * @returns true if an entry was deleted
+     */
+    delete(clientId: string): Promise<boolean>;
+    /**
+     * Get conditional request headers for a cached entry.
+     *
+     * @param clientId - The client_id URL
+     * @returns Headers for conditional request, or undefined if not cached
+     */
+    getConditionalHeaders(clientId: string): Promise<Record<string, string> | undefined>;
+    /**
+     * Clear all cached entries.
+     */
+    clear(): Promise<void>;
+    /**
+     * Get the number of cached entries.
+     */
+    size(): Promise<number>;
+    /**
+     * Remove expired entries.
+     *
+     * @returns Number of entries removed
+     */
+    cleanup(): Promise<number>;
+}
+/**
+ * Backwards compatibility alias for CimdCache.
+ * @deprecated Use InMemoryCimdCache directly or createCimdCache factory.
+ */
+export declare const CimdCache: typeof InMemoryCimdCache;
+/**
+ * Factory function to create a CIMD cache backend.
+ *
+ * @param config - Cache configuration
+ * @returns A cache backend instance (InMemoryCimdCache or RedisCimdCache)
+ */
+export declare function createCimdCache(config?: CimdCacheConfig): Promise<CimdCacheBackend>;
+//# sourceMappingURL=cimd.cache.d.ts.map

package/cimd/cimd.cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cimd.cache.d.ts","sourceRoot":"","sources":["../../src/cimd/cimd.cache.ts"],"names":[],"mappings":"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"}