@connectum/auth 1.0.0-rc.3

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@connectum/auth",
+  "version": "1.0.0-rc.3",
+  "description": "Authentication and authorization interceptors for Connectum",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Connectum-Framework/connectum.git",
+    "directory": "packages/auth"
+  },
+  "scripts": {
+    "dev": "node --watch src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test tests/unit/**/*.test.ts tests/integration/**/*.test.ts",
+    "test:unit": "node --test tests/unit/**/*.test.ts",
+    "test:integration": "node --test tests/integration/**/*.test.ts",
+    "test:bun": "exodus-test --engine bun:pure tests/unit/**/*.test.ts tests/integration/**/*.test.ts",
+    "test:esbuild": "exodus-test --esbuild tests/unit/**/*.test.ts tests/integration/**/*.test.ts",
+    "lint": "biome check src",
+    "format": "biome check --write src",
+    "build": "tsup",
+    "clean": "rm -rf coverage dist"
+  },
+  "keywords": [
+    "auth",
+    "authentication",
+    "authorization",
+    "jwt",
+    "connectrpc",
+    "grpc",
+    "connectum",
+    "interceptor"
+  ],
+  "author": "Highload.Zone",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@connectrpc/connect": "catalog:",
+    "@connectum/core": "workspace:^",
+    "jose": "^6.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "catalog:",
+    "c8": "catalog:",
+    "tsup": "catalog:",
+    "typescript": "catalog:"
+  }
+}

package/src/auth-interceptor.ts

@@ -0,0 +1,137 @@
+/**
+ * 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
+ */
+
+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, AuthInterceptorOptions } from "./types.ts";
+import { AUTH_HEADERS } from "./types.ts";
+
+/**
+ * Default credential extractor.
+ * Extracts Bearer token from Authorization header.
+ */
+function defaultExtractCredentials(req: { header: Headers }): string | null {
+    const authHeader = req.header.get("authorization");
+    if (!authHeader) {
+        return null;
+    }
+
+    // Support "Bearer <token>" format
+    const match = /^Bearer\s+(.+)$/i.exec(authHeader);
+    return match?.[1] ?? null;
+}
+
+/**
+ * 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',
+ *     };
+ *   },
+ * });
+ * ```
+ */
+export function createAuthInterceptor(options: AuthInterceptorOptions): Interceptor {
+    const { extractCredentials = defaultExtractCredentials, verifyCredentials, skipMethods = [], propagateHeaders = false, cache: cacheOptions, 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 from external clients
+        for (const headerName of Object.values(AUTH_HEADERS)) {
+            req.header.delete(headerName);
+        }
+
+        // Skip specified methods
+        if (matchesMethodPattern(serviceName, methodName, skipMethods)) {
+            return await next(req);
+        }
+
+        // Extract credentials
+        const credentials = await extractCredentials(req);
+        if (!credentials) {
+            throw new ConnectError("Missing credentials", Code.Unauthenticated);
+        }
+
+        // Check cache before verification
+        const cached = cache?.get(credentials);
+        if (cached && (!cached.expiresAt || cached.expiresAt.getTime() > Date.now())) {
+            if (propagateHeaders) {
+                setAuthHeaders(req.header, cached, propagatedClaims);
+            }
+            return await authContextStorage.run(cached, () => next(req));
+        }
+
+        // Verify credentials
+        let authContext: AuthContext;
+        try {
+            authContext = await verifyCredentials(credentials);
+        } catch (err) {
+            if (err instanceof ConnectError) {
+                throw err;
+            }
+            throw new ConnectError("Authentication failed", Code.Unauthenticated);
+        }
+
+        // Cache the verification result
+        cache?.set(credentials, authContext);
+
+        // Propagate auth context as headers if enabled
+        if (propagateHeaders) {
+            setAuthHeaders(req.header, authContext, propagatedClaims);
+        }
+
+        // Run downstream with auth context in AsyncLocalStorage
+        return await authContextStorage.run(authContext, () => next(req));
+    };
+}

package/src/authz-interceptor.ts

@@ -0,0 +1,158 @@
+/**
+ * Authorization interceptor
+ *
+ * Declarative rules-based authorization with RBAC support.
+ * Evaluates rules against AuthContext from the auth interceptor.
+ *
+ * @module authz-interceptor
+ */
+
+import type { Interceptor, StreamRequest, UnaryRequest } from "@connectrpc/connect";
+import { Code, ConnectError } from "@connectrpc/connect";
+import { getAuthContext } from "./context.ts";
+import type { AuthzDeniedDetails } from "./errors.ts";
+import { AuthzDeniedError } from "./errors.ts";
+import { matchesMethodPattern } from "./method-match.ts";
+import type { AuthzInterceptorOptions, AuthzRule } from "./types.ts";
+import { AuthzEffect } from "./types.ts";
+
+/**
+ * Check if the auth context satisfies a rule's requirements.
+ */
+function satisfiesRequirements(context: { roles: ReadonlyArray<string>; scopes: ReadonlyArray<string> }, requires: NonNullable<AuthzRule["requires"]>): boolean {
+    // Check roles: user must have at least one of the required roles
+    if (requires.roles && requires.roles.length > 0) {
+        const hasRole = requires.roles.some((role) => context.roles.includes(role));
+        if (!hasRole) {
+            return false;
+        }
+    }
+
+    // Check scopes: user must have ALL required scopes
+    if (requires.scopes && requires.scopes.length > 0) {
+        const hasAllScopes = requires.scopes.every((scope) => context.scopes.includes(scope));
+        if (!hasAllScopes) {
+            return false;
+        }
+    }
+
+    return true;
+}
+
+/**
+ * Evaluate authorization rules against auth context for a specific method.
+ *
+ * Returns the effect of the first matching rule, or undefined if no rule matches.
+ */
+function evaluateRules(
+    rules: AuthzRule[],
+    context: { roles: ReadonlyArray<string>; scopes: ReadonlyArray<string> },
+    serviceName: string,
+    methodName: string,
+): { effect: string; ruleName: string; requiredRoles?: readonly string[]; requiredScopes?: readonly string[] } | undefined {
+    for (const rule of rules) {
+        // Check if any of the rule's method patterns match
+        const matches = matchesMethodPattern(serviceName, methodName, rule.methods);
+        if (!matches) {
+            continue;
+        }
+
+        // If rule has requirements, check them
+        if (rule.requires) {
+            if (satisfiesRequirements(context, rule.requires)) {
+                const result: { effect: string; ruleName: string; requiredRoles?: readonly string[]; requiredScopes?: readonly string[] } = {
+                    effect: rule.effect,
+                    ruleName: rule.name,
+                };
+                if (rule.requires.roles) result.requiredRoles = rule.requires.roles;
+                if (rule.requires.scopes) result.requiredScopes = rule.requires.scopes;
+                return result;
+            }
+            // Requirements not met — this rule doesn't match, continue to next
+            continue;
+        }
+
+        // No requirements — rule matches unconditionally
+        return { effect: rule.effect, ruleName: rule.name };
+    }
+
+    return undefined;
+}
+
+/**
+ * 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' },
+ *   ],
+ * });
+ * ```
+ */
+export function createAuthzInterceptor(options: AuthzInterceptorOptions = {}): Interceptor {
+    const { defaultPolicy = AuthzEffect.DENY, rules = [], authorize, skipMethods = [] } = options;
+
+    return (next) => async (req: UnaryRequest | StreamRequest) => {
+        const serviceName: string = req.service.typeName;
+        const methodName: string = req.method.name;
+
+        // Skip specified methods
+        if (matchesMethodPattern(serviceName, methodName, skipMethods)) {
+            return await next(req);
+        }
+
+        // Get auth context from AsyncLocalStorage
+        const authContext = getAuthContext();
+        if (!authContext) {
+            throw new ConnectError("Authentication required for authorization", Code.Unauthenticated);
+        }
+
+        // Evaluate declarative rules first
+        if (rules.length > 0) {
+            const ruleResult = evaluateRules(rules, authContext, serviceName, methodName);
+            if (ruleResult) {
+                if (ruleResult.effect === AuthzEffect.DENY) {
+                    const details: AuthzDeniedDetails = {
+                        ruleName: ruleResult.ruleName,
+                        ...(ruleResult.requiredRoles && { requiredRoles: [...ruleResult.requiredRoles] }),
+                        ...(ruleResult.requiredScopes && { requiredScopes: [...ruleResult.requiredScopes] }),
+                    };
+                    throw new AuthzDeniedError(details);
+                }
+                // ALLOW — continue
+                return await next(req);
+            }
+        }
+
+        // If no rules matched, try programmatic callback
+        if (authorize) {
+            const allowed = await authorize(authContext, { service: serviceName, method: methodName });
+            if (!allowed) {
+                throw new ConnectError("Access denied", Code.PermissionDenied);
+            }
+            return await next(req);
+        }
+
+        // No rules matched, no callback — apply default policy
+        if (defaultPolicy === AuthzEffect.DENY) {
+            throw new ConnectError("Access denied by default policy", Code.PermissionDenied);
+        }
+
+        return await next(req);
+    };
+}

package/src/cache.ts

@@ -0,0 +1,66 @@
+/**
+ * Minimal in-memory LRU cache with TTL expiration.
+ *
+ * Uses Map insertion order for LRU eviction.
+ * No external dependencies.
+ */
+
+interface CacheEntry<T> {
+    value: T;
+    expiresAt: number;
+}
+
+export class LruCache<T> {
+    readonly #maxSize: number;
+    readonly #ttl: number;
+    readonly #entries = new Map<string, CacheEntry<T>>();
+
+    constructor(options: { ttl: number; maxSize?: number | undefined }) {
+        if (typeof options.ttl !== "number" || options.ttl <= 0) {
+            throw new RangeError("ttl must be a positive number");
+        }
+        this.#ttl = options.ttl;
+        this.#maxSize = options.maxSize ?? 1000;
+    }
+
+    get(key: string): T | undefined {
+        const entry = this.#entries.get(key);
+        if (!entry) return undefined;
+
+        if (Date.now() >= entry.expiresAt) {
+            this.#entries.delete(key);
+            return undefined;
+        }
+
+        // Move to end (most recently used)
+        this.#entries.delete(key);
+        this.#entries.set(key, entry);
+        return entry.value;
+    }
+
+    set(key: string, value: T): void {
+        // Delete first to update insertion order
+        this.#entries.delete(key);
+
+        // Evict LRU (first entry) if at capacity
+        if (this.#entries.size >= this.#maxSize) {
+            const firstKey = this.#entries.keys().next().value;
+            if (firstKey !== undefined) {
+                this.#entries.delete(firstKey);
+            }
+        }
+
+        this.#entries.set(key, {
+            value,
+            expiresAt: Date.now() + this.#ttl,
+        });
+    }
+
+    clear(): void {
+        this.#entries.clear();
+    }
+
+    get size(): number {
+        return this.#entries.size;
+    }
+}

package/src/context.ts

@@ -0,0 +1,63 @@
+/**
+ * Authentication context storage
+ *
+ * Uses AsyncLocalStorage to make auth context available to handlers
+ * without passing it through function parameters.
+ *
+ * @module context
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import { Code, ConnectError } from "@connectrpc/connect";
+import type { AuthContext } from "./types.ts";
+
+/**
+ * Module-level AsyncLocalStorage for auth context.
+ *
+ * Set by auth interceptors, read by handlers via getAuthContext().
+ * Automatically isolated per async context (request).
+ */
+export const authContextStorage = new 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) };
+ *   },
+ * };
+ * ```
+ */
+export function getAuthContext(): AuthContext | undefined {
+    return authContextStorage.getStore();
+}
+
+/**
+ * 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
+ */
+export function requireAuthContext(): AuthContext {
+    const context = authContextStorage.getStore();
+    if (!context) {
+        throw new ConnectError("Authentication required", Code.Unauthenticated);
+    }
+    return context;
+}

package/src/errors.ts

@@ -0,0 +1,45 @@
+/**
+ * Auth-specific error types
+ *
+ * @module errors
+ */
+
+import { Code, ConnectError } from "@connectrpc/connect";
+// biome-ignore lint/correctness/useImportExtensions: workspace package import
+import type { SanitizableError } from "@connectum/core";
+
+/**
+ * Details for authorization denied errors.
+ */
+export 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.
+ */
+export class AuthzDeniedError extends ConnectError implements SanitizableError {
+    readonly clientMessage = "Access denied";
+    readonly ruleName: string;
+    readonly authzDetails: AuthzDeniedDetails;
+
+    get serverDetails(): Readonly<Record<string, unknown>> {
+        return {
+            ruleName: this.authzDetails.ruleName,
+            requiredRoles: this.authzDetails.requiredRoles,
+            requiredScopes: this.authzDetails.requiredScopes,
+        };
+    }
+
+    constructor(details: AuthzDeniedDetails) {
+        super(`Access denied by rule: ${details.ruleName}`, Code.PermissionDenied);
+        this.name = "AuthzDeniedError";
+        this.ruleName = details.ruleName;
+        this.authzDetails = details;
+    }
+}