@connectum/auth 1.0.0-rc.3

package/src/session-auth-interceptor.ts

@@ -0,0 +1,120 @@
+/**
+ * Session-based authentication interceptor
+ *
+ * Convenience wrapper for session-based auth systems (e.g., better-auth).
+ * Implements interceptor directly (not via createAuthInterceptor) to pass
+ * full request headers to verifySession for cookie-based auth support.
+ *
+ * @module session-auth-interceptor
+ */
+
+import type { Interceptor, StreamRequest, UnaryRequest } from "@connectrpc/connect";
+import { Code, ConnectError } from "@connectrpc/connect";
+import { LruCache } from "./cache.ts";
+import { authContextStorage } from "./context.ts";
+import { setAuthHeaders } from "./headers.ts";
+import { matchesMethodPattern } from "./method-match.ts";
+import type { AuthContext, SessionAuthInterceptorOptions } from "./types.ts";
+import { AUTH_HEADERS } from "./types.ts";
+
+/**
+ * Default token extractor.
+ * Extracts Bearer token from Authorization header.
+ */
+function defaultExtractToken(req: { header: Headers }): string | null {
+    const authHeader = req.header.get("authorization");
+    if (!authHeader) return null;
+    const match = /^Bearer\s+(.+)$/i.exec(authHeader);
+    return match?.[1] ?? null;
+}
+
+/**
+ * Create a session-based authentication interceptor.
+ *
+ * Two-step authentication:
+ * 1. Extract token from request
+ * 2. Verify session via user-provided callback (receives full headers for cookie support)
+ * 3. Map session data to AuthContext via user-provided mapper
+ *
+ * @param options - Session auth configuration
+ * @returns ConnectRPC interceptor
+ *
+ * @example better-auth integration
+ * ```typescript
+ * import { createSessionAuthInterceptor } from '@connectum/auth';
+ *
+ * const sessionAuth = createSessionAuthInterceptor({
+ *   verifySession: (token, headers) => auth.api.getSession({ headers }),
+ *   mapSession: (s) => ({
+ *     subject: s.user.id,
+ *     name: s.user.name,
+ *     roles: [],
+ *     scopes: [],
+ *     claims: s.user,
+ *     type: 'session',
+ *   }),
+ *   cache: { ttl: 60_000 },
+ * });
+ * ```
+ */
+export function createSessionAuthInterceptor(options: SessionAuthInterceptorOptions): Interceptor {
+    const { verifySession, mapSession, extractToken = defaultExtractToken, cache: cacheOptions, skipMethods = [], propagateHeaders = false, propagatedClaims } = options;
+
+    const cache = cacheOptions ? new LruCache<AuthContext>(cacheOptions) : undefined;
+
+    return (next) => async (req: UnaryRequest | StreamRequest) => {
+        const serviceName: string = req.service.typeName;
+        const methodName: string = req.method.name;
+
+        // Strip auth headers to prevent spoofing
+        for (const headerName of Object.values(AUTH_HEADERS)) {
+            req.header.delete(headerName);
+        }
+
+        if (matchesMethodPattern(serviceName, methodName, skipMethods)) {
+            return await next(req);
+        }
+
+        // Extract token
+        const token = await extractToken(req);
+        if (!token) {
+            throw new ConnectError("Missing credentials", Code.Unauthenticated);
+        }
+
+        // Check cache
+        const cached = cache?.get(token);
+        if (cached && (!cached.expiresAt || cached.expiresAt.getTime() > Date.now())) {
+            if (propagateHeaders) {
+                setAuthHeaders(req.header, cached, propagatedClaims);
+            }
+            return await authContextStorage.run(cached, () => next(req));
+        }
+
+        // Verify session — pass full headers for cookie-based auth
+        let session: unknown;
+        try {
+            session = await verifySession(token, req.header);
+        } catch (err) {
+            if (err instanceof ConnectError) throw err;
+            throw new ConnectError("Session verification failed", Code.Unauthenticated);
+        }
+
+        // Map session to AuthContext
+        let authContext: AuthContext;
+        try {
+            authContext = await mapSession(session);
+        } catch (err) {
+            if (err instanceof ConnectError) throw err;
+            throw new ConnectError("Session mapping failed", Code.Unauthenticated);
+        }
+
+        // Cache result
+        cache?.set(token, authContext);
+
+        if (propagateHeaders) {
+            setAuthHeaders(req.header, authContext, propagatedClaims);
+        }
+
+        return await authContextStorage.run(authContext, () => next(req));
+    };
+}

package/src/testing/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @connectum/auth/testing
+ *
+ * Test utilities for authentication and authorization.
+ *
+ * @module @connectum/auth/testing
+ */
+
+export { createMockAuthContext } from "./mock-context.ts";
+export { createTestJwt, TEST_JWT_SECRET } from "./test-jwt.ts";
+export { withAuthContext } from "./with-context.ts";

package/src/testing/mock-context.ts

@@ -0,0 +1,44 @@
+/**
+ * Mock auth context for testing
+ *
+ * @module testing/mock-context
+ */
+
+import type { AuthContext } from "../types.ts";
+
+/**
+ * Default mock auth context values.
+ */
+const DEFAULT_MOCK_CONTEXT: AuthContext = {
+    subject: "test-user",
+    name: "Test User",
+    roles: ["user"],
+    scopes: ["read"],
+    claims: {},
+    type: "test",
+};
+
+/**
+ * Create a mock AuthContext for testing.
+ *
+ * Merges provided overrides with sensible test defaults.
+ *
+ * @param overrides - Partial AuthContext to override defaults
+ * @returns Complete AuthContext
+ *
+ * @example
+ * ```typescript
+ * import { createMockAuthContext } from '@connectum/auth/testing';
+ *
+ * const ctx = createMockAuthContext({ subject: 'admin-1', roles: ['admin'] });
+ * assert.strictEqual(ctx.subject, 'admin-1');
+ * assert.deepStrictEqual(ctx.roles, ['admin']);
+ * assert.strictEqual(ctx.type, 'test'); // default preserved
+ * ```
+ */
+export function createMockAuthContext(overrides?: Partial<AuthContext>): AuthContext {
+    return {
+        ...DEFAULT_MOCK_CONTEXT,
+        ...overrides,
+    };
+}

package/src/testing/test-jwt.ts

@@ -0,0 +1,75 @@
+/**
+ * Test JWT utilities
+ *
+ * Provides deterministic JWT creation for testing.
+ * NOT for production use.
+ *
+ * @module testing/test-jwt
+ */
+
+import * as jose from "jose";
+
+/**
+ * Deterministic test secret for HS256 JWTs.
+ *
+ * WARNING: This is a well-known secret for testing only.
+ * NEVER use in production.
+ */
+export const TEST_JWT_SECRET = "connectum-test-secret-do-not-use-in-production";
+
+/**
+ * Encoded test secret for jose.
+ */
+const encodedSecret = new TextEncoder().encode(TEST_JWT_SECRET);
+
+/**
+ * Create a signed test JWT for integration testing.
+ *
+ * Uses HS256 algorithm with a deterministic test key.
+ * NOT for production use.
+ *
+ * @param payload - JWT claims
+ * @param options - Signing options
+ * @returns Signed JWT string
+ *
+ * @example Create a test token
+ * ```typescript
+ * import { createTestJwt, TEST_JWT_SECRET } from '@connectum/auth/testing';
+ *
+ * const token = await createTestJwt({
+ *   sub: 'user-123',
+ *   roles: ['admin'],
+ *   scope: 'read write',
+ * });
+ *
+ * // Use with createJwtAuthInterceptor in tests
+ * const auth = createJwtAuthInterceptor({ secret: TEST_JWT_SECRET });
+ * ```
+ */
+export async function createTestJwt(
+    payload: Record<string, unknown>,
+    options?: {
+        expiresIn?: string;
+        issuer?: string;
+        audience?: string;
+    },
+): Promise<string> {
+    let builder = new jose.SignJWT(payload).setProtectedHeader({ alg: "HS256" }).setIssuedAt();
+
+    if (options?.expiresIn) {
+        builder = builder.setExpirationTime(options.expiresIn);
+    } else {
+        // Default: 1 hour expiry
+        builder = builder.setExpirationTime("1h");
+    }
+
+    if (options?.issuer) {
+        builder = builder.setIssuer(options.issuer);
+    }
+
+    if (options?.audience) {
+        builder = builder.setAudience(options.audience);
+    }
+
+    return await builder.sign(encodedSecret);
+}

package/src/testing/with-context.ts

@@ -0,0 +1,33 @@
+/**
+ * Auth context test helper
+ *
+ * @module testing/with-context
+ */
+
+import { authContextStorage } from "../context.ts";
+import type { AuthContext } from "../types.ts";
+
+/**
+ * Run a function with a pre-set AuthContext.
+ *
+ * Sets the provided AuthContext in AsyncLocalStorage for the duration
+ * of the callback. Useful for testing handlers that call getAuthContext().
+ *
+ * @param context - Auth context to set
+ * @param fn - Function to execute within the context
+ * @returns Return value of fn
+ *
+ * @example Test a handler that reads auth context
+ * ```typescript
+ * import { withAuthContext, createMockAuthContext } from '@connectum/auth/testing';
+ * import { getAuthContext } from '@connectum/auth';
+ *
+ * await withAuthContext(createMockAuthContext({ subject: 'test-user' }), async () => {
+ *   const ctx = getAuthContext();
+ *   assert.strictEqual(ctx?.subject, 'test-user');
+ * });
+ * ```
+ */
+export async function withAuthContext<T>(context: AuthContext, fn: () => T | Promise<T>): Promise<T> {
+    return await authContextStorage.run(context, fn);
+}

package/src/types.ts

@@ -0,0 +1,326 @@
+/**
+ * Shared types for @connectum/auth
+ *
+ * @module types
+ */
+
+import type { Interceptor } from "@connectrpc/connect";
+
+/**
+ * Interceptor factory function type
+ *
+ * @template TOptions - Options type for the interceptor
+ */
+export type InterceptorFactory<TOptions = void> = TOptions extends void ? () => Interceptor : (options: TOptions) => Interceptor;
+
+/**
+ * Authenticated user context
+ *
+ * Represents the result of authentication. Set by auth interceptor,
+ * accessible via getAuthContext() in handlers and downstream interceptors.
+ */
+export interface AuthContext {
+    /** Authenticated subject identifier (user ID, service account, etc.) */
+    readonly subject: string;
+    /** Human-readable display name */
+    readonly name?: string | undefined;
+    /** Assigned roles (e.g., ["admin", "user"]) */
+    readonly roles: ReadonlyArray<string>;
+    /** Granted scopes (e.g., ["read", "write"]) */
+    readonly scopes: ReadonlyArray<string>;
+    /** Raw claims from the credential (JWT claims, API key metadata, etc.) */
+    readonly claims: Readonly<Record<string, unknown>>;
+    /** Credential type identifier (e.g., "jwt", "api-key", "mtls") */
+    readonly type: string;
+    /** Credential expiration time */
+    readonly expiresAt?: Date | undefined;
+}
+
+/**
+ * Standard header names for auth context propagation.
+ *
+ * Used for cross-service context propagation (similar to Envoy credential injection).
+ * The auth interceptor sets these headers when propagateHeaders is true.
+ *
+ * WARNING: These headers are trusted ONLY in service-to-service communication
+ * where transport security (mTLS) is established. Never trust these headers
+ * from external clients without using createGatewayAuthInterceptor().
+ */
+export const AUTH_HEADERS = {
+    /** Authenticated subject identifier */
+    SUBJECT: "x-auth-subject",
+    /** JSON-encoded roles array */
+    ROLES: "x-auth-roles",
+    /** Space-separated scopes */
+    SCOPES: "x-auth-scopes",
+    /** JSON-encoded claims object */
+    CLAIMS: "x-auth-claims",
+    /** Human-readable display name */
+    NAME: "x-auth-name",
+    /** Credential type (jwt, api-key, mtls, etc.) */
+    TYPE: "x-auth-type",
+} as const;
+
+/**
+ * Authorization rule effect
+ */
+export const AuthzEffect = {
+    ALLOW: "allow",
+    DENY: "deny",
+} as const;
+
+export type AuthzEffect = (typeof AuthzEffect)[keyof typeof AuthzEffect];
+
+/**
+ * Authorization rule definition.
+ *
+ * When a rule has `requires`, the match semantics are:
+ * - **roles**: "any-of" -- the user must have **at least one** of the listed roles.
+ * - **scopes**: "all-of" -- the user must have **every** listed scope.
+ */
+export interface AuthzRule {
+    /** Rule name for logging/debugging */
+    readonly name: string;
+    /** Method patterns to match (e.g., "admin.v1.AdminService/*", "user.v1.UserService/DeleteUser") */
+    readonly methods: ReadonlyArray<string>;
+    /** Effect when rule matches */
+    readonly effect: AuthzEffect;
+    /**
+     * Required roles/scopes for this rule.
+     *
+     * - `roles` uses "any-of" semantics: user needs at least one of the listed roles.
+     * - `scopes` uses "all-of" semantics: user needs every listed scope.
+     */
+    readonly requires?:
+        | {
+              readonly roles?: ReadonlyArray<string>;
+              readonly scopes?: ReadonlyArray<string>;
+          }
+        | undefined;
+}
+
+/**
+ * LRU cache configuration for credentials verification
+ */
+export interface CacheOptions {
+    /** Cache entry time-to-live in milliseconds */
+    readonly ttl: number;
+    /** Maximum number of cached entries */
+    readonly maxSize?: number | undefined;
+}
+
+/**
+ * Generic auth interceptor options
+ */
+export interface AuthInterceptorOptions {
+    /**
+     * Extract credentials from request.
+     * Default: extracts Bearer token from Authorization header.
+     *
+     * @param req - Request with headers
+     * @returns Credential string or null if no credentials found
+     */
+    extractCredentials?: (req: { header: Headers }) => string | null | Promise<string | null>;
+
+    /**
+     * Verify credentials and return auth context.
+     * REQUIRED. Must throw on invalid credentials.
+     *
+     * @param credentials - Extracted credential string
+     * @returns AuthContext for valid credentials
+     */
+    verifyCredentials: (credentials: string) => AuthContext | Promise<AuthContext>;
+
+    /**
+     * Methods to skip authentication for.
+     * Patterns: "Service/Method" or "Service/*"
+     * @default [] (health and reflection methods are NOT auto-skipped)
+     */
+    skipMethods?: string[] | undefined;
+
+    /**
+     * Propagate auth context as headers for downstream services.
+     * @default false
+     */
+    propagateHeaders?: boolean | undefined;
+
+    /**
+     * LRU cache for credentials verification results.
+     * Caches AuthContext by credential string to reduce verification overhead.
+     */
+    cache?: CacheOptions | undefined;
+
+    /**
+     * Filter which claims are propagated in headers (SEC-001).
+     * When set, only listed claim keys are included in x-auth-claims header.
+     * When not set, all claims are propagated.
+     */
+    propagatedClaims?: string[] | undefined;
+}
+
+/**
+ * JWT auth interceptor options
+ */
+export interface JwtAuthInterceptorOptions {
+    /** JWKS endpoint URL for remote key set */
+    jwksUri?: string | undefined;
+    /** HMAC symmetric secret (for HS256/HS384/HS512) */
+    secret?: string | undefined;
+    /** Asymmetric public key */
+    publicKey?: CryptoKey | undefined;
+    /** Expected issuer(s) */
+    issuer?: string | string[] | undefined;
+    /** Expected audience(s) */
+    audience?: string | string[] | undefined;
+    /** Allowed algorithms */
+    algorithms?: string[] | undefined;
+    /**
+     * Mapping from JWT claims to AuthContext fields.
+     * Supports dot-notation paths (e.g., "realm_access.roles").
+     */
+    claimsMapping?:
+        | {
+              subject?: string | undefined;
+              name?: string | undefined;
+              roles?: string | undefined;
+              scopes?: string | undefined;
+          }
+        | undefined;
+    /**
+     * Maximum token age.
+     * Passed to jose jwtVerify options.
+     * Number (seconds) or string (e.g., "2h", "7d").
+     */
+    maxTokenAge?: number | string | undefined;
+    /**
+     * Methods to skip authentication for.
+     * @default []
+     */
+    skipMethods?: string[] | undefined;
+    /**
+     * Propagate auth context as headers for downstream services.
+     * @default false
+     */
+    propagateHeaders?: boolean | undefined;
+}
+
+/**
+ * Authorization interceptor options
+ */
+export interface AuthzInterceptorOptions {
+    /**
+     * Default policy when no rule matches.
+     * @default "deny"
+     */
+    defaultPolicy?: AuthzEffect | undefined;
+
+    /**
+     * Declarative authorization rules.
+     * Evaluated in order; first matching rule wins.
+     */
+    rules?: AuthzRule[] | undefined;
+
+    /**
+     * Programmatic authorization callback.
+     * Called after rule evaluation if no rule matched,
+     * or always if no rules are defined.
+     *
+     * @param context - Authenticated user context
+     * @param req - Request info (service and method names)
+     * @returns true if authorized, false otherwise
+     */
+    authorize?: (context: AuthContext, req: { service: string; method: string }) => boolean | Promise<boolean>;
+
+    /**
+     * Methods to skip authorization for.
+     * @default []
+     */
+    skipMethods?: string[] | undefined;
+}
+
+/**
+ * Header name mapping for gateway auth context extraction.
+ *
+ * Maps AuthContext fields to custom header names used by the API gateway.
+ */
+export interface GatewayHeaderMapping {
+    /** Header containing the authenticated subject */
+    readonly subject: string;
+    /** Header containing the display name */
+    readonly name?: string | undefined;
+    /** Header containing JSON-encoded roles array */
+    readonly roles?: string | undefined;
+    /** Header containing space-separated scopes */
+    readonly scopes?: string | undefined;
+    /** Header containing credential type */
+    readonly type?: string | undefined;
+    /** Header containing JSON-encoded claims */
+    readonly claims?: string | undefined;
+}
+
+/**
+ * Gateway auth interceptor options.
+ *
+ * For services behind an API gateway that has already performed authentication.
+ * Extracts auth context from gateway-injected headers.
+ */
+export interface GatewayAuthInterceptorOptions {
+    /** Mapping from AuthContext fields to gateway header names */
+    readonly headerMapping: GatewayHeaderMapping;
+    /** Trust verification: check that request came from a trusted gateway */
+    readonly trustSource: {
+        /** Header set by the gateway to prove trust */
+        readonly header: string;
+        /** Accepted values for the trust header */
+        readonly expectedValues: string[];
+    };
+    /** Headers to strip from the request after extraction (prevent spoofing) */
+    readonly stripHeaders?: string[] | undefined;
+    /** Methods to skip authentication for */
+    readonly skipMethods?: string[] | undefined;
+    /** Propagate auth context as headers for downstream services */
+    readonly propagateHeaders?: boolean | undefined;
+    /** Default credential type when not provided by gateway */
+    readonly defaultType?: string | undefined;
+}
+
+/**
+ * Session-based auth interceptor options.
+ *
+ * Two-step authentication: verify session token, then map session data to AuthContext.
+ */
+export interface SessionAuthInterceptorOptions {
+    /**
+     * Verify session token and return raw session data.
+     * Must throw on invalid/expired sessions.
+     *
+     * @param token - Session token string
+     * @param headers - Request headers (for additional context)
+     * @returns Raw session data
+     */
+    readonly verifySession: (token: string, headers: Headers) => unknown | Promise<unknown>;
+    /**
+     * Map raw session data to AuthContext.
+     *
+     * @param session - Raw session data from verifySession
+     * @returns Normalized auth context
+     */
+    readonly mapSession: (session: unknown) => AuthContext | Promise<AuthContext>;
+    /**
+     * Custom token extraction.
+     * Default: extracts Bearer token from Authorization header.
+     */
+    readonly extractToken?: ((req: { header: Headers }) => string | null | Promise<string | null>) | undefined;
+    /** LRU cache for session verification results */
+    readonly cache?: CacheOptions | undefined;
+    /** Methods to skip authentication for */
+    readonly skipMethods?: string[] | undefined;
+    /** Propagate auth context as headers for downstream services */
+    readonly propagateHeaders?: boolean | undefined;
+    /**
+     * Filter which claims are propagated in headers.
+     * When set, only listed claim keys are included in x-auth-claims header.
+     * When not set, all claims are propagated.
+     */
+    readonly propagatedClaims?: string[] | undefined;
+}