@connectum/auth 1.0.0-rc.3

package/src/gateway-auth-interceptor.ts

@@ -0,0 +1,203 @@
+/**
+ * Gateway authentication interceptor
+ *
+ * For services behind an API gateway that has already performed authentication.
+ * Extracts auth context from gateway-injected headers after verifying trust.
+ *
+ * Trust is established via a header (e.g., x-gateway-secret) rather than
+ * peerAddress, since ConnectRPC interceptors don't have access to peer info.
+ *
+ * @module gateway-auth-interceptor
+ */
+
+import type { Interceptor, StreamRequest, UnaryRequest } from "@connectrpc/connect";
+import { Code, ConnectError } from "@connectrpc/connect";
+import { authContextStorage } from "./context.ts";
+import { setAuthHeaders } from "./headers.ts";
+import { matchesMethodPattern } from "./method-match.ts";
+import type { AuthContext, GatewayAuthInterceptorOptions } from "./types.ts";
+
+/**
+ * Match an IP address against a pattern (exact or CIDR notation).
+ *
+ * Supports:
+ * - Exact match: "10.0.0.1"
+ * - CIDR range: "10.0.0.0/8"
+ */
+function isValidOctet(value: number): boolean {
+    return Number.isInteger(value) && value >= 0 && value <= 255;
+}
+
+function matchesIp(address: string, pattern: string): boolean {
+    if (address === pattern) return true;
+
+    if (pattern.includes("/")) {
+        const [network, prefixStr] = pattern.split("/");
+        if (!network || !prefixStr) return false;
+        const prefix = Number.parseInt(prefixStr, 10);
+        if (Number.isNaN(prefix) || prefix < 0 || prefix > 32) return false;
+        const peerParts = address.split(".").map(Number);
+        const networkParts = network.split(".").map(Number);
+        if (peerParts.length !== 4 || networkParts.length !== 4) return false;
+        if (!peerParts.every(isValidOctet) || !networkParts.every(isValidOctet)) return false;
+        const [p0 = 0, p1 = 0, p2 = 0, p3 = 0] = peerParts;
+        const [n0 = 0, n1 = 0, n2 = 0, n3 = 0] = networkParts;
+        const peerInt = ((p0 << 24) | (p1 << 16) | (p2 << 8) | p3) >>> 0;
+        const networkInt = ((n0 << 24) | (n1 << 16) | (n2 << 8) | n3) >>> 0;
+        const mask = prefix === 0 ? 0 : (~0 << (32 - prefix)) >>> 0;
+        return (peerInt & mask) === (networkInt & mask);
+    }
+
+    return false;
+}
+
+/**
+ * Check if a trust header value matches any of the expected values.
+ *
+ * For each expected value, tries exact match first, then CIDR match.
+ */
+function isTrusted(headerValue: string, expectedValues: readonly string[]): boolean {
+    for (const expected of expectedValues) {
+        if (headerValue === expected) return true;
+        if (expected.includes("/") && matchesIp(headerValue, expected)) return true;
+    }
+    return false;
+}
+
+/**
+ * Create a gateway authentication interceptor.
+ *
+ * Reads pre-authenticated identity from gateway-injected headers.
+ * Trust is established by checking a designated header value against
+ * a list of expected values (shared secrets or trusted IP ranges).
+ *
+ * @param options - Gateway auth configuration
+ * @returns ConnectRPC interceptor
+ *
+ * @example Kong/Envoy gateway with shared secret
+ * ```typescript
+ * const gatewayAuth = createGatewayAuthInterceptor({
+ *   headerMapping: {
+ *     subject: 'x-user-id',
+ *     name: 'x-user-name',
+ *     roles: 'x-user-roles',
+ *   },
+ *   trustSource: {
+ *     header: 'x-gateway-secret',
+ *     expectedValues: [process.env.GATEWAY_SECRET],
+ *   },
+ * });
+ * ```
+ */
+export function createGatewayAuthInterceptor(options: GatewayAuthInterceptorOptions): Interceptor {
+    const { headerMapping, trustSource, stripHeaders = [], skipMethods = [], propagateHeaders = false, defaultType = "gateway" } = options;
+
+    // Fail-closed: require subject mapping and non-empty expectedValues
+    if (!headerMapping.subject) {
+        throw new Error("@connectum/auth: Gateway auth requires headerMapping.subject");
+    }
+    if (trustSource.expectedValues.length === 0) {
+        throw new Error("@connectum/auth: Gateway auth requires non-empty trustSource.expectedValues");
+    }
+
+    // Pre-compute headers to strip (prevents downstream spoofing on all routes)
+    const headersToStrip = [
+        headerMapping.subject,
+        headerMapping.name,
+        headerMapping.roles,
+        headerMapping.scopes,
+        headerMapping.type,
+        headerMapping.claims,
+        trustSource.header,
+        ...stripHeaders,
+    ];
+
+    function stripGatewayHeaders(headers: Headers): void {
+        for (const header of headersToStrip) {
+            if (header) headers.delete(header);
+        }
+    }
+
+    return (next) => async (req: UnaryRequest | StreamRequest) => {
+        const serviceName: string = req.service.typeName;
+        const methodName: string = req.method.name;
+
+        if (matchesMethodPattern(serviceName, methodName, skipMethods)) {
+            // Strip gateway headers even for skipped methods to prevent spoofing
+            stripGatewayHeaders(req.header);
+            return await next(req);
+        }
+
+        // Verify trust
+        const trustHeaderValue = req.header.get(trustSource.header);
+        if (!trustHeaderValue || !isTrusted(trustHeaderValue, trustSource.expectedValues)) {
+            throw new ConnectError("Untrusted request source", Code.Unauthenticated);
+        }
+
+        // Extract subject (required)
+        const subject = req.header.get(headerMapping.subject);
+        if (!subject) {
+            throw new ConnectError("Missing subject header from gateway", Code.Unauthenticated);
+        }
+
+        // Extract optional fields
+        const name = headerMapping.name ? (req.header.get(headerMapping.name) ?? undefined) : undefined;
+        const type = headerMapping.type ? (req.header.get(headerMapping.type) ?? defaultType) : defaultType;
+
+        // Parse roles: JSON array or comma-separated
+        let roles: string[] = [];
+        if (headerMapping.roles) {
+            const rolesRaw = req.header.get(headerMapping.roles);
+            if (rolesRaw) {
+                try {
+                    const parsed: unknown = JSON.parse(rolesRaw);
+                    if (Array.isArray(parsed)) {
+                        roles = parsed.filter((r): r is string => typeof r === "string");
+                    }
+                } catch {
+                    // Not JSON — try comma-separated
+                    roles = rolesRaw
+                        .split(",")
+                        .map((r) => r.trim())
+                        .filter(Boolean);
+                }
+            }
+        }
+
+        // Parse scopes: space-separated
+        let scopes: string[] = [];
+        if (headerMapping.scopes) {
+            const scopesRaw = req.header.get(headerMapping.scopes);
+            if (scopesRaw) {
+                scopes = scopesRaw.split(" ").filter(Boolean);
+            }
+        }
+
+        // Parse claims: JSON object
+        let claims: Record<string, unknown> = {};
+        if (headerMapping.claims) {
+            const claimsRaw = req.header.get(headerMapping.claims);
+            if (claimsRaw && claimsRaw.length <= 8192) {
+                try {
+                    const parsed: unknown = JSON.parse(claimsRaw);
+                    if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+                        claims = parsed as Record<string, unknown>;
+                    }
+                } catch {
+                    // Invalid JSON — ignore
+                }
+            }
+        }
+
+        const authContext: AuthContext = { subject, name, roles, scopes, claims, type };
+
+        // Strip mapped headers to prevent downstream spoofing
+        stripGatewayHeaders(req.header);
+
+        if (propagateHeaders) {
+            setAuthHeaders(req.header, authContext);
+        }
+
+        return await authContextStorage.run(authContext, () => next(req));
+    };
+}

package/src/headers.ts

@@ -0,0 +1,149 @@
+/**
+ * Auth header propagation utilities
+ *
+ * Handles serialization/deserialization of AuthContext to/from
+ * HTTP headers for cross-service context propagation.
+ *
+ * @module headers
+ */
+
+import type { AuthContext } from "./types.ts";
+import { AUTH_HEADERS } from "./types.ts";
+
+const MAX_HEADER_BYTES = 8192;
+
+/**
+ * Sanitize a header value by removing control characters and enforcing length limits.
+ */
+function sanitizeHeaderValue(value: string, maxLength: number): string {
+    // Remove control characters (except tab/LF/CR which are valid in headers)
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional control char removal for header sanitization
+    const cleaned = value.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, "");
+    return cleaned.slice(0, maxLength);
+}
+
+/**
+ * Serialize AuthContext to request headers.
+ *
+ * Sets standard auth headers on the provided Headers object.
+ * Used by auth interceptors when propagateHeaders is enabled.
+ *
+ * @param headers - Headers object to set auth headers on
+ * @param context - Auth context to serialize
+ * @param propagatedClaims - Optional list of claim keys to propagate (all if undefined)
+ */
+export function setAuthHeaders(headers: Headers, context: AuthContext, propagatedClaims?: string[]): void {
+    headers.set(AUTH_HEADERS.SUBJECT, sanitizeHeaderValue(context.subject, 512));
+    headers.set(AUTH_HEADERS.TYPE, sanitizeHeaderValue(context.type, 128));
+
+    if (context.name) {
+        headers.set(AUTH_HEADERS.NAME, sanitizeHeaderValue(context.name, 256));
+    }
+
+    if (context.roles.length > 0) {
+        const rolesValue = JSON.stringify(context.roles);
+        if (rolesValue.length <= MAX_HEADER_BYTES) {
+            headers.set(AUTH_HEADERS.ROLES, rolesValue);
+        }
+    }
+
+    if (context.scopes.length > 0) {
+        const scopesValue = context.scopes.join(" ");
+        if (scopesValue.length <= MAX_HEADER_BYTES) {
+            headers.set(AUTH_HEADERS.SCOPES, scopesValue);
+        }
+    }
+
+    const claimKeys = Object.keys(context.claims);
+    if (claimKeys.length > 0) {
+        const filteredClaims = propagatedClaims ? Object.fromEntries(Object.entries(context.claims).filter(([key]) => propagatedClaims.includes(key))) : context.claims;
+        if (Object.keys(filteredClaims).length > 0) {
+            const claimsValue = JSON.stringify(filteredClaims);
+            if (claimsValue.length <= MAX_HEADER_BYTES) {
+                headers.set(AUTH_HEADERS.CLAIMS, claimsValue);
+            }
+        }
+    }
+}
+
+/**
+ * Parse AuthContext from request headers.
+ *
+ * Deserializes auth context from standard headers set by an upstream
+ * service or gateway. Returns undefined if required headers are missing.
+ *
+ * WARNING: Only use this in trusted environments (behind mTLS, mesh, etc.).
+ * For untrusted environments, use createTrustedHeadersReader() instead.
+ *
+ * @param headers - Request headers to parse
+ * @returns Parsed AuthContext or undefined if headers are missing
+ *
+ * @example Trust upstream auth headers
+ * ```typescript
+ * import { parseAuthHeaders } from '@connectum/auth';
+ *
+ * const context = parseAuthHeaders(req.header);
+ * if (context) {
+ *   console.log(`Authenticated as ${context.subject}`);
+ * }
+ * ```
+ */
+export function parseAuthHeaders(headers: Headers): AuthContext | undefined {
+    const subjectHeader = headers.get(AUTH_HEADERS.SUBJECT);
+    if (!subjectHeader) {
+        return undefined;
+    }
+
+    const subject = sanitizeHeaderValue(subjectHeader, 512);
+    const typeHeader = headers.get(AUTH_HEADERS.TYPE);
+    const type = typeHeader ? sanitizeHeaderValue(typeHeader, 128) : "unknown";
+    const rolesRaw = headers.get(AUTH_HEADERS.ROLES);
+    const scopesRaw = headers.get(AUTH_HEADERS.SCOPES);
+    const claimsRaw = headers.get(AUTH_HEADERS.CLAIMS);
+
+    let roles: string[] = [];
+    if (rolesRaw && rolesRaw.length <= MAX_HEADER_BYTES) {
+        try {
+            const parsed: unknown = JSON.parse(rolesRaw);
+            if (Array.isArray(parsed)) {
+                roles = parsed.filter((r): r is string => typeof r === "string");
+            }
+        } catch {
+            // Invalid JSON — ignore malformed header
+        }
+    }
+
+    let scopes: string[] = [];
+    if (scopesRaw && scopesRaw.length <= MAX_HEADER_BYTES) {
+        scopes = scopesRaw.split(" ").filter(Boolean);
+    }
+
+    const nameRaw = headers.get(AUTH_HEADERS.NAME);
+    const name = nameRaw ? sanitizeHeaderValue(nameRaw, 256) : undefined;
+
+    let claims: Record<string, unknown> = {};
+    if (claimsRaw) {
+        if (claimsRaw.length > MAX_HEADER_BYTES) {
+            // Claims too large — ignore to prevent abuse
+            claims = {};
+        } else {
+            try {
+                const parsed: unknown = JSON.parse(claimsRaw);
+                if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+                    claims = parsed as Record<string, unknown>;
+                }
+            } catch {
+                // Invalid JSON — ignore malformed header
+            }
+        }
+    }
+
+    return {
+        subject,
+        name,
+        type,
+        roles,
+        scopes,
+        claims,
+    };
+}

package/src/index.ts

@@ -0,0 +1,49 @@
+/**
+ * @connectum/auth
+ *
+ * Authentication and authorization interceptors for Connectum.
+ *
+ * Provides five interceptor factories:
+ * - createAuthInterceptor() — generic, pluggable authentication
+ * - createJwtAuthInterceptor() — JWT convenience with jose
+ * - createGatewayAuthInterceptor() — gateway-injected headers
+ * - createSessionAuthInterceptor() — session-based auth (better-auth, etc.)
+ * - createAuthzInterceptor() — declarative rules-based authorization
+ *
+ * Plus context propagation via AsyncLocalStorage and request headers.
+ *
+ * @module @connectum/auth
+ */
+
+// Interceptor factories
+export { createAuthInterceptor } from "./auth-interceptor.ts";
+export { createAuthzInterceptor } from "./authz-interceptor.ts";
+// Cache
+export { LruCache } from "./cache.ts";
+// Context management
+export { authContextStorage, getAuthContext, requireAuthContext } from "./context.ts";
+export type { AuthzDeniedDetails } from "./errors.ts";
+export { AuthzDeniedError } from "./errors.ts";
+export { createGatewayAuthInterceptor } from "./gateway-auth-interceptor.ts";
+// Header utilities
+export { parseAuthHeaders, setAuthHeaders } from "./headers.ts";
+export { createJwtAuthInterceptor } from "./jwt-auth-interceptor.ts";
+// Method pattern matching
+export { matchesMethodPattern } from "./method-match.ts";
+export { createSessionAuthInterceptor } from "./session-auth-interceptor.ts";
+
+// Types and constants
+export type {
+    AuthContext,
+    AuthInterceptorOptions,
+    AuthzInterceptorOptions,
+    AuthzRule,
+    CacheOptions,
+    GatewayAuthInterceptorOptions,
+    GatewayHeaderMapping,
+    InterceptorFactory,
+    JwtAuthInterceptorOptions,
+    SessionAuthInterceptorOptions,
+} from "./types.ts";
+
+export { AUTH_HEADERS, AuthzEffect } from "./types.ts";

package/src/jwt-auth-interceptor.ts

@@ -0,0 +1,208 @@
+/**
+ * JWT authentication interceptor
+ *
+ * Convenience wrapper for JWT-based authentication using the jose library.
+ * Supports JWKS remote key sets, HMAC secrets, and asymmetric public keys.
+ *
+ * @module jwt-auth-interceptor
+ */
+
+import type { Interceptor } from "@connectrpc/connect";
+import { Code, ConnectError } from "@connectrpc/connect";
+import * as jose from "jose";
+import { createAuthInterceptor } from "./auth-interceptor.ts";
+import type { AuthContext, JwtAuthInterceptorOptions } from "./types.ts";
+
+/**
+ * Resolve a value at a dot-notation path in an object.
+ *
+ * @example getNestedValue({ a: { b: [1, 2] } }, "a.b") // [1, 2]
+ */
+function getNestedValue(obj: Record<string, unknown>, path: string): unknown {
+    let current: unknown = obj;
+    for (const key of path.split(".")) {
+        if (current === null || current === undefined || typeof current !== "object") {
+            return undefined;
+        }
+        current = (current as Record<string, unknown>)[key];
+    }
+    return current;
+}
+
+/**
+ * Get minimum HMAC key size in bytes per RFC 7518.
+ * HS256 requires 32 bytes, HS384 requires 48, HS512 requires 64.
+ */
+function getMinHmacKeyBytes(algorithms?: string[]): number {
+    if (!algorithms) return 32;
+    if (algorithms.includes("HS512")) return 64;
+    if (algorithms.includes("HS384")) return 48;
+    return 32;
+}
+
+/**
+ * Build a JWT verification function from options.
+ *
+ * Separates JWKS (dynamic key resolution) from static keys (HMAC / asymmetric)
+ * to satisfy jose's overloaded jwtVerify signatures.
+ *
+ * Priority: jwksUri > secret > publicKey
+ */
+function buildVerifier(options: JwtAuthInterceptorOptions, verifyOptions: jose.JWTVerifyOptions): (token: string) => Promise<jose.JWTVerifyResult> {
+    if (options.jwksUri) {
+        const jwks = jose.createRemoteJWKSet(new URL(options.jwksUri));
+        return (token) => jose.jwtVerify(token, jwks, verifyOptions);
+    }
+    if (options.secret) {
+        const key = new TextEncoder().encode(options.secret);
+        const minBytes = getMinHmacKeyBytes(options.algorithms);
+        if (key.byteLength < minBytes) {
+            throw new Error(
+                `@connectum/auth: HMAC secret must be at least ${minBytes} bytes (${minBytes * 8} bits) per RFC 7518. ` +
+                    `Got ${key.byteLength} bytes. Generate with: openssl rand -base64 ${minBytes}`,
+            );
+        }
+        return (token) => jose.jwtVerify(token, key, verifyOptions);
+    }
+    if (options.publicKey) {
+        const key = options.publicKey;
+        return (token) => jose.jwtVerify(token, key, verifyOptions);
+    }
+    throw new Error("@connectum/auth: JWT interceptor requires one of: jwksUri, secret, or publicKey");
+}
+
+/**
+ * Mutable intermediate type for claim mapping results.
+ */
+interface MappedClaims {
+    subject?: string;
+    name?: string;
+    roles?: string[];
+    scopes?: string[];
+}
+
+/**
+ * Map JWT claims to AuthContext using configurable claim paths.
+ */
+function mapClaimsToContext(payload: jose.JWTPayload, mapping: NonNullable<JwtAuthInterceptorOptions["claimsMapping"]>): MappedClaims {
+    const result: MappedClaims = {};
+    const claims = payload as Record<string, unknown>;
+
+    // Subject
+    if (mapping.subject) {
+        const val = getNestedValue(claims, mapping.subject);
+        if (typeof val === "string") {
+            result.subject = val;
+        }
+    }
+
+    // Name
+    if (mapping.name) {
+        const val = getNestedValue(claims, mapping.name);
+        if (typeof val === "string") {
+            result.name = val;
+        }
+    }
+
+    // Roles
+    if (mapping.roles) {
+        const val = getNestedValue(claims, mapping.roles);
+        if (Array.isArray(val)) {
+            result.roles = val.filter((r): r is string => typeof r === "string");
+        }
+    }
+
+    // Scopes (can be space-separated string or array)
+    if (mapping.scopes) {
+        const val = getNestedValue(claims, mapping.scopes);
+        if (typeof val === "string") {
+            result.scopes = val.split(" ").filter(Boolean);
+        } else if (Array.isArray(val)) {
+            result.scopes = val.filter((s): s is string => typeof s === "string");
+        }
+    }
+
+    return result;
+}
+
+/**
+ * Throw an Unauthenticated error for a missing JWT subject claim.
+ */
+function throwMissingSubject(): never {
+    throw new ConnectError("JWT missing subject claim", Code.Unauthenticated);
+}
+
+/**
+ * Create a JWT authentication interceptor.
+ *
+ * Convenience wrapper around createAuthInterceptor() that handles
+ * JWT extraction from Authorization header, verification via jose,
+ * and standard claim mapping to AuthContext.
+ *
+ * @param options - JWT authentication options
+ * @returns ConnectRPC interceptor
+ *
+ * @example JWKS-based JWT auth (Auth0, Keycloak, etc.)
+ * ```typescript
+ * import { createJwtAuthInterceptor } from '@connectum/auth';
+ *
+ * const jwtAuth = createJwtAuthInterceptor({
+ *   jwksUri: 'https://auth.example.com/.well-known/jwks.json',
+ *   issuer: 'https://auth.example.com/',
+ *   audience: 'my-api',
+ *   claimsMapping: {
+ *     roles: 'realm_access.roles',
+ *     scopes: 'scope',
+ *   },
+ * });
+ * ```
+ *
+ * @example HMAC secret (testing / simple setups)
+ * ```typescript
+ * const jwtAuth = createJwtAuthInterceptor({
+ *   secret: process.env.JWT_SECRET,
+ *   issuer: 'my-service',
+ * });
+ * ```
+ */
+export function createJwtAuthInterceptor(options: JwtAuthInterceptorOptions): Interceptor {
+    const { claimsMapping = {}, skipMethods, propagateHeaders } = options;
+
+    const verifyOptions: jose.JWTVerifyOptions = {};
+    if (options.issuer) {
+        verifyOptions.issuer = options.issuer;
+    }
+    if (options.audience) {
+        verifyOptions.audience = options.audience;
+    }
+    if (options.algorithms) {
+        verifyOptions.algorithms = options.algorithms;
+    }
+    if (options.maxTokenAge) {
+        verifyOptions.maxTokenAge = options.maxTokenAge;
+    }
+
+    const verify = buildVerifier(options, verifyOptions);
+
+    return createAuthInterceptor({
+        skipMethods,
+        propagateHeaders,
+        verifyCredentials: async (token: string): Promise<AuthContext> => {
+            const { payload } = await verify(token);
+
+            // Map standard + custom claims
+            const mapped = mapClaimsToContext(payload, claimsMapping);
+            const claims = payload as Record<string, unknown>;
+
+            return {
+                subject: mapped.subject ?? payload.sub ?? throwMissingSubject(),
+                name: mapped.name ?? (typeof claims.name === "string" ? claims.name : undefined),
+                roles: mapped.roles ?? [],
+                scopes: mapped.scopes ?? (typeof payload.scope === "string" ? payload.scope.split(" ").filter(Boolean) : []),
+                claims,
+                type: "jwt",
+                expiresAt: payload.exp ? new Date(payload.exp * 1000) : undefined,
+            };
+        },
+    });
+}

package/src/method-match.ts

@@ -0,0 +1,46 @@
+/**
+ * Method pattern matching utility
+ *
+ * Shared logic for matching gRPC methods against patterns.
+ * Used by both auth and authz interceptors.
+ *
+ * @module method-match
+ */
+
+/**
+ * Check if a method matches any of the given patterns.
+ *
+ * Patterns:
+ * - "*" — matches all methods
+ * - "Service/*" — matches all methods of a service
+ * - "Service/Method" — matches exact method
+ *
+ * @param serviceName - Fully-qualified service name (e.g., "user.v1.UserService")
+ * @param methodName - Method name (e.g., "GetUser")
+ * @param patterns - Readonly array of match patterns
+ * @returns true if the method matches any pattern
+ */
+export function matchesMethodPattern(serviceName: string, methodName: string, patterns: readonly string[]): boolean {
+    if (patterns.length === 0) {
+        return false;
+    }
+
+    const fullMethod = `${serviceName}/${methodName}`;
+
+    for (const pattern of patterns) {
+        if (pattern === "*") {
+            return true;
+        }
+        if (pattern === fullMethod) {
+            return true;
+        }
+        if (pattern.endsWith("/*")) {
+            const servicePattern = pattern.slice(0, -2);
+            if (serviceName === servicePattern) {
+                return true;
+            }
+        }
+    }
+
+    return false;
+}