@connectum/auth 1.0.0-rc.3

package/dist/index.d.ts

@@ -0,0 +1,388 @@
+import { Interceptor, ConnectError } from '@connectrpc/connect';
+import { A as AuthInterceptorOptions, a as AuthzInterceptorOptions, b as AuthContext, G as GatewayAuthInterceptorOptions, J as JwtAuthInterceptorOptions, S as SessionAuthInterceptorOptions } from './types-IH8aZeWZ.js';
+export { c as AUTH_HEADERS, d as AuthzEffect, e as AuthzRule, C as CacheOptions, f as GatewayHeaderMapping, I as InterceptorFactory } from './types-IH8aZeWZ.js';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { SanitizableError } from '@connectum/core';
+
+/**
+ * Generic authentication interceptor
+ *
+ * Provides pluggable authentication for any credential type.
+ * Extracts credentials, verifies them, and stores AuthContext
+ * in AsyncLocalStorage for downstream access.
+ *
+ * @module auth-interceptor
+ */
+
+/**
+ * Create a generic authentication interceptor.
+ *
+ * Extracts credentials from request headers, verifies them using
+ * a user-provided callback, and stores the resulting AuthContext
+ * in AsyncLocalStorage for downstream access.
+ *
+ * @param options - Authentication options
+ * @returns ConnectRPC interceptor
+ *
+ * @example API key authentication
+ * ```typescript
+ * import { createAuthInterceptor } from '@connectum/auth';
+ *
+ * const auth = createAuthInterceptor({
+ *   extractCredentials: (req) => req.header.get('x-api-key'),
+ *   verifyCredentials: async (apiKey) => {
+ *     const user = await db.findByApiKey(apiKey);
+ *     if (!user) throw new Error('Invalid API key');
+ *     return {
+ *       subject: user.id,
+ *       roles: user.roles,
+ *       scopes: [],
+ *       claims: {},
+ *       type: 'api-key',
+ *     };
+ *   },
+ * });
+ * ```
+ *
+ * @example Bearer token with default extractor
+ * ```typescript
+ * const auth = createAuthInterceptor({
+ *   verifyCredentials: async (token) => {
+ *     const payload = await verifyToken(token);
+ *     return {
+ *       subject: payload.sub,
+ *       roles: payload.roles ?? [],
+ *       scopes: payload.scope?.split(' ') ?? [],
+ *       claims: payload,
+ *       type: 'jwt',
+ *     };
+ *   },
+ * });
+ * ```
+ */
+declare function createAuthInterceptor(options: AuthInterceptorOptions): Interceptor;
+
+/**
+ * Authorization interceptor
+ *
+ * Declarative rules-based authorization with RBAC support.
+ * Evaluates rules against AuthContext from the auth interceptor.
+ *
+ * @module authz-interceptor
+ */
+
+/**
+ * Create an authorization interceptor.
+ *
+ * Evaluates declarative rules and/or a programmatic callback against
+ * the AuthContext established by the authentication interceptor.
+ *
+ * IMPORTANT: This interceptor MUST run AFTER an authentication interceptor
+ * in the chain.
+ *
+ * @param options - Authorization options
+ * @returns ConnectRPC interceptor
+ *
+ * @example RBAC with declarative rules
+ * ```typescript
+ * import { createAuthzInterceptor } from '@connectum/auth';
+ *
+ * const authz = createAuthzInterceptor({
+ *   defaultPolicy: 'deny',
+ *   rules: [
+ *     { name: 'public', methods: ['public.v1.PublicService/*'], effect: 'allow' },
+ *     { name: 'admin', methods: ['admin.v1.AdminService/*'], requires: { roles: ['admin'] }, effect: 'allow' },
+ *   ],
+ * });
+ * ```
+ */
+declare function createAuthzInterceptor(options?: AuthzInterceptorOptions): Interceptor;
+
+/**
+ * Minimal in-memory LRU cache with TTL expiration.
+ *
+ * Uses Map insertion order for LRU eviction.
+ * No external dependencies.
+ */
+declare class LruCache<T> {
+    #private;
+    constructor(options: {
+        ttl: number;
+        maxSize?: number | undefined;
+    });
+    get(key: string): T | undefined;
+    set(key: string, value: T): void;
+    clear(): void;
+    get size(): number;
+}
+
+/**
+ * Authentication context storage
+ *
+ * Uses AsyncLocalStorage to make auth context available to handlers
+ * without passing it through function parameters.
+ *
+ * @module context
+ */
+
+/**
+ * Module-level AsyncLocalStorage for auth context.
+ *
+ * Set by auth interceptors, read by handlers via getAuthContext().
+ * Automatically isolated per async context (request).
+ */
+declare const authContextStorage: AsyncLocalStorage<AuthContext>;
+/**
+ * Get the current auth context.
+ *
+ * Returns the AuthContext set by the auth interceptor in the current
+ * async context. Returns undefined if no auth interceptor is active
+ * or the current method was skipped.
+ *
+ * @returns Current auth context or undefined
+ *
+ * @example Usage in a service handler
+ * ```typescript
+ * import { getAuthContext } from '@connectum/auth';
+ *
+ * const handler = {
+ *   async getUser(req) {
+ *     const auth = getAuthContext();
+ *     if (!auth) throw new ConnectError('Not authenticated', Code.Unauthenticated);
+ *     return { user: await db.getUser(auth.subject) };
+ *   },
+ * };
+ * ```
+ */
+declare function getAuthContext(): AuthContext | undefined;
+/**
+ * Get the current auth context or throw.
+ *
+ * Like getAuthContext() but throws ConnectError(Code.Unauthenticated)
+ * if no auth context is available. Use when auth is mandatory.
+ *
+ * @returns Current auth context (never undefined)
+ * @throws ConnectError with Code.Unauthenticated if no context
+ */
+declare function requireAuthContext(): AuthContext;
+
+/**
+ * Auth-specific error types
+ *
+ * @module errors
+ */
+
+/**
+ * Details for authorization denied errors.
+ */
+interface AuthzDeniedDetails {
+    readonly ruleName: string;
+    readonly requiredRoles?: readonly string[];
+    readonly requiredScopes?: readonly string[];
+}
+/**
+ * Authorization denied error.
+ *
+ * Carries server-side details (rule name, required roles/scopes) while
+ * exposing only "Access denied" to the client via SanitizableError protocol.
+ */
+declare class AuthzDeniedError extends ConnectError implements SanitizableError {
+    readonly clientMessage = "Access denied";
+    readonly ruleName: string;
+    readonly authzDetails: AuthzDeniedDetails;
+    get serverDetails(): Readonly<Record<string, unknown>>;
+    constructor(details: AuthzDeniedDetails);
+}
+
+/**
+ * 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
+ */
+
+/**
+ * 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],
+ *   },
+ * });
+ * ```
+ */
+declare function createGatewayAuthInterceptor(options: GatewayAuthInterceptorOptions): Interceptor;
+
+/**
+ * Auth header propagation utilities
+ *
+ * Handles serialization/deserialization of AuthContext to/from
+ * HTTP headers for cross-service context propagation.
+ *
+ * @module headers
+ */
+
+/**
+ * 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)
+ */
+declare function setAuthHeaders(headers: Headers, context: AuthContext, propagatedClaims?: string[]): void;
+/**
+ * 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}`);
+ * }
+ * ```
+ */
+declare function parseAuthHeaders(headers: Headers): AuthContext | undefined;
+
+/**
+ * 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
+ */
+
+/**
+ * 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',
+ * });
+ * ```
+ */
+declare function createJwtAuthInterceptor(options: JwtAuthInterceptorOptions): Interceptor;
+
+/**
+ * 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
+ */
+declare function matchesMethodPattern(serviceName: string, methodName: string, patterns: readonly string[]): boolean;
+
+/**
+ * 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
+ */
+
+/**
+ * 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 },
+ * });
+ * ```
+ */
+declare function createSessionAuthInterceptor(options: SessionAuthInterceptorOptions): Interceptor;
+
+export { AuthContext, AuthInterceptorOptions, type AuthzDeniedDetails, AuthzDeniedError, AuthzInterceptorOptions, GatewayAuthInterceptorOptions, JwtAuthInterceptorOptions, LruCache, SessionAuthInterceptorOptions, authContextStorage, createAuthInterceptor, createAuthzInterceptor, createGatewayAuthInterceptor, createJwtAuthInterceptor, createSessionAuthInterceptor, getAuthContext, matchesMethodPattern, parseAuthHeaders, requireAuthContext, setAuthHeaders };