@yuva-devlab/auth-server 0.0.0-stage → 0.3.0

package/dist/index.d.cts

@@ -0,0 +1,310 @@
+/**
+ * @file packages/auth-server/src/constants/auth.constants.ts
+ * @description Centralized constants and header keys for server-side authentication.
+ * @module @yuva-devlab/auth-server
+ */
+/** Standard Authorization HTTP header name (lowercase for case-insensitive lookup) */
+declare const DEFAULT_AUTH_HEADER = "authorization";
+/** Standard machine-to-machine API key HTTP header name */
+declare const DEFAULT_API_KEY_HEADER = "x-api-key";
+/** Standard Bearer token prefix */
+declare const DEFAULT_BEARER_PREFIX = "Bearer ";
+/** Default cache time-to-live for fetched RS256 JWKS public keys (1 hour) */
+declare const DEFAULT_JWKS_CACHE_TTL_MS = 3600000;
+/** Default cache time-to-live for validated M2M API keys (5 minutes) */
+declare const DEFAULT_API_KEY_CACHE_TTL_MS = 300000;
+/** Default public endpoints bypassing mandatory authentication */
+declare const DEFAULT_PUBLIC_PATHS: readonly string[];
+/** HTTP Status Code for unauthenticated requests */
+declare const HTTP_STATUS_UNAUTHORIZED = 401;
+/** HTTP Status Code for unauthorized / forbidden role requests */
+declare const HTTP_STATUS_FORBIDDEN = 403;
+/** HTTP Status Code returned when an application is deactivated or killed */
+declare const HTTP_STATUS_SERVICE_UNAVAILABLE = 503;
+
+/**
+ * @file packages/auth-server/src/types/auth.types.ts
+ * @description Type definitions and contracts for server authentication, JWKS, and app lifecycle.
+ * @module @yuva-devlab/auth-server
+ */
+/**
+ * Operational state of an application on the DevLab platform.
+ */
+declare enum AppStatus {
+    /** Application is fully operational and serving traffic */
+    ACTIVE = "ACTIVE",
+    /** Application has been administratively disabled / deactivated (Kill-Switch triggered) */
+    INACTIVE = "INACTIVE",
+    /** Application is undergoing scheduled maintenance */
+    MAINTENANCE = "MAINTENANCE"
+}
+/**
+ * Authenticated user profile representation.
+ */
+interface AuthUser {
+    /** Canonical user UUID */
+    readonly id: string;
+    /** Primary user email address */
+    readonly email?: string;
+    /** Granted role slugs */
+    readonly roles: readonly string[];
+    /** Tenant isolation partition ID */
+    readonly tenantId?: string;
+    /** Arbitrary profile metadata */
+    readonly metadata?: Record<string, unknown>;
+}
+/**
+ * Machine-to-machine API key credential.
+ */
+interface ApiKey {
+    /** Primary API key UUID */
+    readonly id: string;
+    /** Secure key string */
+    readonly key: string;
+    /** Human-readable key name or description */
+    readonly name: string;
+    /** Scoped roles granted to this key */
+    readonly roles: readonly string[];
+    /** Tenant ID partition */
+    readonly tenantId?: string;
+    /** Active status flag */
+    readonly isEnabled: boolean;
+}
+/**
+ * Evaluated authentication context attached to inbound requests.
+ */
+interface AuthContext {
+    /** Whether the request carries valid credentials */
+    readonly authenticated: boolean;
+    /** Authenticated user if authenticated via session/JWT */
+    readonly user?: AuthUser;
+    /** Authenticated API key if authenticated via machine credential */
+    readonly apiKey?: ApiKey;
+    /** Consolidated roles granted across user or API key */
+    readonly roles: readonly string[];
+    /** Whether the host application is currently active on the platform */
+    readonly isAppActive: boolean;
+    /** Detailed app status */
+    readonly appStatus?: AppStatus;
+    /** Tenant partition ID */
+    readonly tenantId?: string;
+    /** Distributed trace request identifier */
+    readonly requestId?: string;
+}
+/**
+ * Configuration for verifying RS256 JWTs against a remote JWKS endpoint.
+ */
+interface JwksConfig {
+    /** JWKS endpoint URI exposing JSON Web Keys */
+    readonly jwksUri: string;
+    /** Expected audience claim */
+    readonly audience?: string;
+    /** Expected issuer claim */
+    readonly issuer?: string;
+    /** In-memory cache duration for public keys in milliseconds */
+    readonly cacheTtlMs?: number;
+}
+/**
+ * Decoded JWT claims payload.
+ */
+/**
+ * Result of validating a Machine-to-Machine API key against the DevLab Portal.
+ */
+interface ApiKeyValidationResult {
+    /** Whether the API key is active, valid, and unexpired */
+    readonly valid: boolean;
+    /** Primary API key UUID */
+    readonly keyId?: string;
+    /** Name assigned to this machine key */
+    readonly name?: string;
+    /** Target application slug this key belongs to */
+    readonly appId?: string;
+    /** Target application display name */
+    readonly appName?: string;
+    /** Scopes and permissions granted to this key */
+    readonly scopes?: readonly string[];
+    /** Allowed requests per minute limit */
+    readonly rateLimitRpm?: number;
+    /** Human-readable rejection reason if invalid */
+    readonly reason?: string;
+}
+/**
+ * Configuration options for Machine-to-Machine API key validation.
+ */
+interface M2mConfig {
+    /** Base URL of the authentication server / identity provider */
+    readonly authUrl?: string;
+    /** Legacy alias for authUrl */
+    readonly portalUrl?: string;
+    /** In-memory cache duration for validated API keys in milliseconds */
+    readonly cacheTtlMs?: number;
+    /** Expected client or application identifier */
+    readonly requiredClientId?: string;
+    /** Legacy alias for requiredClientId */
+    readonly requiredAppId?: string;
+    /** Required operational scopes that must be granted to the API key */
+    readonly requiredScopes?: readonly string[];
+}
+interface JwtPayload {
+    readonly sub: string;
+    readonly iss?: string;
+    readonly aud?: string | readonly string[];
+    readonly exp?: number;
+    readonly nbf?: number;
+    readonly iat?: number;
+    readonly email?: string;
+    readonly name?: string;
+    readonly role?: string;
+    readonly roles?: readonly string[];
+    readonly tenantId?: string;
+    readonly tenant_id?: string;
+    readonly tenant_slug?: string;
+    readonly tenant_name?: string;
+    readonly apps?: readonly string[];
+    readonly appId?: string;
+    readonly [key: string]: unknown;
+}
+
+/**
+ * @file packages/auth-server/src/token/jwt-validator.ts
+ * @description RS256 JWKS validator providing cryptographic signature verification and claims checking.
+ * @module @yuva-devlab/auth-server
+ */
+
+/**
+ * Validates JWT access tokens against an in-memory cached JWKS public key set.
+ */
+declare class JwksValidator {
+    private readonly jwksUri;
+    private readonly audience?;
+    private readonly issuer?;
+    private readonly cacheTtlMs;
+    private keyCache;
+    private jwksSetCache;
+    constructor(config?: Partial<JwksConfig>);
+    parseUnverified(token: string): {
+        header: Record<string, unknown>;
+        payload: JwtPayload;
+        rawHeader: string;
+        rawPayload: string;
+        signature: string;
+    };
+    private fetchJwks;
+    private resolveKeyObject;
+    verifyToken(token: string): Promise<JwtPayload>;
+    clearKeyCache(): void;
+}
+
+/**
+ * @file packages/auth-server/src/token/m2m-validator.ts
+ * @description In-memory cached Machine-to-Machine API key validator introspecting the auth provider.
+ * @module @yuva-devlab/auth-server
+ */
+
+/**
+ * Validates machine-to-machine API keys against central authentication server with in-memory caching.
+ */
+declare class M2mApiKeyValidator {
+    private readonly authUrl?;
+    private readonly cacheTtlMs;
+    private readonly requiredClientId?;
+    private readonly requiredScopes?;
+    private readonly keyCache;
+    constructor(config?: Partial<M2mConfig>);
+    validateKey(rawKey: string): Promise<ApiKeyValidationResult>;
+    private enforceKeyConstraints;
+    clearCache(): void;
+}
+
+/**
+ * @file packages/auth-server/src/guards/auth-guards.ts
+ * @description Authorization assertions and scope/role enforcement guards.
+ * @module @yuva-devlab/auth-server
+ */
+
+/**
+ * Asserts that the request is authenticated with an active user session and optional role requirements.
+ *
+ * @param ctx - Inbound request auth context
+ * @param requiredRoles - Optional list of required roles (user must possess at least one)
+ * @returns Authenticated AuthUser
+ * @throws UnauthorizedError if not authenticated as a user
+ * @throws ForbiddenError if user lacks the required roles
+ *
+ * @example
+ * ```typescript
+ * const user = requireUser(ctx, ["admin", "operator"]);
+ * ```
+ */
+declare function requireUser(ctx: AuthContext, requiredRoles?: readonly string[]): AuthUser;
+/**
+ * Asserts that the request is authenticated via a machine-to-machine API key.
+ *
+ * @param ctx - Inbound request auth context
+ * @returns Authenticated ApiKey
+ * @throws UnauthorizedError if not authenticated via an API key
+ */
+declare function requireApiKey(ctx: AuthContext): ApiKey;
+/**
+ * Asserts that the authenticated context (user or API key) possesses a specific operational scope.
+ *
+ * @param ctx - Inbound request auth context
+ * @param scope - Required scope or permission string
+ * @throws ForbiddenError if scope is missing
+ */
+declare function requireScope(ctx: AuthContext, scope: string): void;
+
+/**
+ * @file packages/auth-server/src/middleware/auth-middleware.ts
+ * @description Universal HTTP middleware providing platform kill-switch enforcement and credential validation.
+ * @module @yuva-devlab/auth-server
+ */
+
+/**
+ * Minimal HTTP request and response interfaces for framework neutrality (Express, Fastify, Node http).
+ */
+interface GenericHttpRequest {
+    url?: string;
+    method?: string;
+    headers: Record<string, string | string[] | undefined>;
+    authContext?: AuthContext;
+}
+interface GenericHttpResponse {
+    statusCode?: number;
+    setHeader(name: string, value: string): void;
+    end(body?: string): void;
+}
+/**
+ * Creates a kill-switch middleware that intercepts all traffic if an application is deactivated.
+ *
+ * @param getAppStatus - Callback returning current platform status of the application
+ * @returns Middleware function returning true if allowed to proceed, false if blocked (503)
+ *
+ * @example
+ * ```typescript
+ * const killSwitch = createAppKillSwitchMiddleware(() => appState.status);
+ * const allowed = await killSwitch(req, res);
+ * if (!allowed) return;
+ * ```
+ */
+declare function createAppKillSwitchMiddleware(getAppStatus: () => Promise<AppStatus> | AppStatus): (req: GenericHttpRequest, res: GenericHttpResponse) => Promise<boolean>;
+/**
+ * Options configuring request authentication middleware.
+ */
+interface CreateAuthMiddlewareOptions {
+    /** Whitelisted public endpoints bypassing authentication */
+    publicPaths?: readonly string[];
+    /** Function resolving an API key against store */
+    validateApiKey?: (key: string) => Promise<AuthContext | null>;
+    /** Function resolving a Bearer session token against JWKS or session store */
+    validateToken?: (token: string) => Promise<AuthContext | null>;
+}
+/**
+ * Universal authentication middleware verifying API keys and Bearer tokens.
+ *
+ * @param options - Configuration options
+ * @returns Middleware handler
+ */
+declare function createAuthMiddleware(options: CreateAuthMiddlewareOptions): (req: GenericHttpRequest, res: GenericHttpResponse) => Promise<boolean>;
+
+export { type ApiKey, type ApiKeyValidationResult, AppStatus, type AuthContext, type AuthUser, type CreateAuthMiddlewareOptions, DEFAULT_API_KEY_CACHE_TTL_MS, DEFAULT_API_KEY_HEADER, DEFAULT_AUTH_HEADER, DEFAULT_BEARER_PREFIX, DEFAULT_JWKS_CACHE_TTL_MS, DEFAULT_PUBLIC_PATHS, type GenericHttpRequest, type GenericHttpResponse, HTTP_STATUS_FORBIDDEN, HTTP_STATUS_SERVICE_UNAVAILABLE, HTTP_STATUS_UNAUTHORIZED, type JwksConfig, JwksValidator, type JwtPayload, M2mApiKeyValidator, type M2mConfig, createAppKillSwitchMiddleware, createAuthMiddleware, requireApiKey, requireScope, requireUser };

package/dist/index.d.ts

@@ -0,0 +1,310 @@
+/**
+ * @file packages/auth-server/src/constants/auth.constants.ts
+ * @description Centralized constants and header keys for server-side authentication.
+ * @module @yuva-devlab/auth-server
+ */
+/** Standard Authorization HTTP header name (lowercase for case-insensitive lookup) */
+declare const DEFAULT_AUTH_HEADER = "authorization";
+/** Standard machine-to-machine API key HTTP header name */
+declare const DEFAULT_API_KEY_HEADER = "x-api-key";
+/** Standard Bearer token prefix */
+declare const DEFAULT_BEARER_PREFIX = "Bearer ";
+/** Default cache time-to-live for fetched RS256 JWKS public keys (1 hour) */
+declare const DEFAULT_JWKS_CACHE_TTL_MS = 3600000;
+/** Default cache time-to-live for validated M2M API keys (5 minutes) */
+declare const DEFAULT_API_KEY_CACHE_TTL_MS = 300000;
+/** Default public endpoints bypassing mandatory authentication */
+declare const DEFAULT_PUBLIC_PATHS: readonly string[];
+/** HTTP Status Code for unauthenticated requests */
+declare const HTTP_STATUS_UNAUTHORIZED = 401;
+/** HTTP Status Code for unauthorized / forbidden role requests */
+declare const HTTP_STATUS_FORBIDDEN = 403;
+/** HTTP Status Code returned when an application is deactivated or killed */
+declare const HTTP_STATUS_SERVICE_UNAVAILABLE = 503;
+
+/**
+ * @file packages/auth-server/src/types/auth.types.ts
+ * @description Type definitions and contracts for server authentication, JWKS, and app lifecycle.
+ * @module @yuva-devlab/auth-server
+ */
+/**
+ * Operational state of an application on the DevLab platform.
+ */
+declare enum AppStatus {
+    /** Application is fully operational and serving traffic */
+    ACTIVE = "ACTIVE",
+    /** Application has been administratively disabled / deactivated (Kill-Switch triggered) */
+    INACTIVE = "INACTIVE",
+    /** Application is undergoing scheduled maintenance */
+    MAINTENANCE = "MAINTENANCE"
+}
+/**
+ * Authenticated user profile representation.
+ */
+interface AuthUser {
+    /** Canonical user UUID */
+    readonly id: string;
+    /** Primary user email address */
+    readonly email?: string;
+    /** Granted role slugs */
+    readonly roles: readonly string[];
+    /** Tenant isolation partition ID */
+    readonly tenantId?: string;
+    /** Arbitrary profile metadata */
+    readonly metadata?: Record<string, unknown>;
+}
+/**
+ * Machine-to-machine API key credential.
+ */
+interface ApiKey {
+    /** Primary API key UUID */
+    readonly id: string;
+    /** Secure key string */
+    readonly key: string;
+    /** Human-readable key name or description */
+    readonly name: string;
+    /** Scoped roles granted to this key */
+    readonly roles: readonly string[];
+    /** Tenant ID partition */
+    readonly tenantId?: string;
+    /** Active status flag */
+    readonly isEnabled: boolean;
+}
+/**
+ * Evaluated authentication context attached to inbound requests.
+ */
+interface AuthContext {
+    /** Whether the request carries valid credentials */
+    readonly authenticated: boolean;
+    /** Authenticated user if authenticated via session/JWT */
+    readonly user?: AuthUser;
+    /** Authenticated API key if authenticated via machine credential */
+    readonly apiKey?: ApiKey;
+    /** Consolidated roles granted across user or API key */
+    readonly roles: readonly string[];
+    /** Whether the host application is currently active on the platform */
+    readonly isAppActive: boolean;
+    /** Detailed app status */
+    readonly appStatus?: AppStatus;
+    /** Tenant partition ID */
+    readonly tenantId?: string;
+    /** Distributed trace request identifier */
+    readonly requestId?: string;
+}
+/**
+ * Configuration for verifying RS256 JWTs against a remote JWKS endpoint.
+ */
+interface JwksConfig {
+    /** JWKS endpoint URI exposing JSON Web Keys */
+    readonly jwksUri: string;
+    /** Expected audience claim */
+    readonly audience?: string;
+    /** Expected issuer claim */
+    readonly issuer?: string;
+    /** In-memory cache duration for public keys in milliseconds */
+    readonly cacheTtlMs?: number;
+}
+/**
+ * Decoded JWT claims payload.
+ */
+/**
+ * Result of validating a Machine-to-Machine API key against the DevLab Portal.
+ */
+interface ApiKeyValidationResult {
+    /** Whether the API key is active, valid, and unexpired */
+    readonly valid: boolean;
+    /** Primary API key UUID */
+    readonly keyId?: string;
+    /** Name assigned to this machine key */
+    readonly name?: string;
+    /** Target application slug this key belongs to */
+    readonly appId?: string;
+    /** Target application display name */
+    readonly appName?: string;
+    /** Scopes and permissions granted to this key */
+    readonly scopes?: readonly string[];
+    /** Allowed requests per minute limit */
+    readonly rateLimitRpm?: number;
+    /** Human-readable rejection reason if invalid */
+    readonly reason?: string;
+}
+/**
+ * Configuration options for Machine-to-Machine API key validation.
+ */
+interface M2mConfig {
+    /** Base URL of the authentication server / identity provider */
+    readonly authUrl?: string;
+    /** Legacy alias for authUrl */
+    readonly portalUrl?: string;
+    /** In-memory cache duration for validated API keys in milliseconds */
+    readonly cacheTtlMs?: number;
+    /** Expected client or application identifier */
+    readonly requiredClientId?: string;
+    /** Legacy alias for requiredClientId */
+    readonly requiredAppId?: string;
+    /** Required operational scopes that must be granted to the API key */
+    readonly requiredScopes?: readonly string[];
+}
+interface JwtPayload {
+    readonly sub: string;
+    readonly iss?: string;
+    readonly aud?: string | readonly string[];
+    readonly exp?: number;
+    readonly nbf?: number;
+    readonly iat?: number;
+    readonly email?: string;
+    readonly name?: string;
+    readonly role?: string;
+    readonly roles?: readonly string[];
+    readonly tenantId?: string;
+    readonly tenant_id?: string;
+    readonly tenant_slug?: string;
+    readonly tenant_name?: string;
+    readonly apps?: readonly string[];
+    readonly appId?: string;
+    readonly [key: string]: unknown;
+}
+
+/**
+ * @file packages/auth-server/src/token/jwt-validator.ts
+ * @description RS256 JWKS validator providing cryptographic signature verification and claims checking.
+ * @module @yuva-devlab/auth-server
+ */
+
+/**
+ * Validates JWT access tokens against an in-memory cached JWKS public key set.
+ */
+declare class JwksValidator {
+    private readonly jwksUri;
+    private readonly audience?;
+    private readonly issuer?;
+    private readonly cacheTtlMs;
+    private keyCache;
+    private jwksSetCache;
+    constructor(config?: Partial<JwksConfig>);
+    parseUnverified(token: string): {
+        header: Record<string, unknown>;
+        payload: JwtPayload;
+        rawHeader: string;
+        rawPayload: string;
+        signature: string;
+    };
+    private fetchJwks;
+    private resolveKeyObject;
+    verifyToken(token: string): Promise<JwtPayload>;
+    clearKeyCache(): void;
+}
+
+/**
+ * @file packages/auth-server/src/token/m2m-validator.ts
+ * @description In-memory cached Machine-to-Machine API key validator introspecting the auth provider.
+ * @module @yuva-devlab/auth-server
+ */
+
+/**
+ * Validates machine-to-machine API keys against central authentication server with in-memory caching.
+ */
+declare class M2mApiKeyValidator {
+    private readonly authUrl?;
+    private readonly cacheTtlMs;
+    private readonly requiredClientId?;
+    private readonly requiredScopes?;
+    private readonly keyCache;
+    constructor(config?: Partial<M2mConfig>);
+    validateKey(rawKey: string): Promise<ApiKeyValidationResult>;
+    private enforceKeyConstraints;
+    clearCache(): void;
+}
+
+/**
+ * @file packages/auth-server/src/guards/auth-guards.ts
+ * @description Authorization assertions and scope/role enforcement guards.
+ * @module @yuva-devlab/auth-server
+ */
+
+/**
+ * Asserts that the request is authenticated with an active user session and optional role requirements.
+ *
+ * @param ctx - Inbound request auth context
+ * @param requiredRoles - Optional list of required roles (user must possess at least one)
+ * @returns Authenticated AuthUser
+ * @throws UnauthorizedError if not authenticated as a user
+ * @throws ForbiddenError if user lacks the required roles
+ *
+ * @example
+ * ```typescript
+ * const user = requireUser(ctx, ["admin", "operator"]);
+ * ```
+ */
+declare function requireUser(ctx: AuthContext, requiredRoles?: readonly string[]): AuthUser;
+/**
+ * Asserts that the request is authenticated via a machine-to-machine API key.
+ *
+ * @param ctx - Inbound request auth context
+ * @returns Authenticated ApiKey
+ * @throws UnauthorizedError if not authenticated via an API key
+ */
+declare function requireApiKey(ctx: AuthContext): ApiKey;
+/**
+ * Asserts that the authenticated context (user or API key) possesses a specific operational scope.
+ *
+ * @param ctx - Inbound request auth context
+ * @param scope - Required scope or permission string
+ * @throws ForbiddenError if scope is missing
+ */
+declare function requireScope(ctx: AuthContext, scope: string): void;
+
+/**
+ * @file packages/auth-server/src/middleware/auth-middleware.ts
+ * @description Universal HTTP middleware providing platform kill-switch enforcement and credential validation.
+ * @module @yuva-devlab/auth-server
+ */
+
+/**
+ * Minimal HTTP request and response interfaces for framework neutrality (Express, Fastify, Node http).
+ */
+interface GenericHttpRequest {
+    url?: string;
+    method?: string;
+    headers: Record<string, string | string[] | undefined>;
+    authContext?: AuthContext;
+}
+interface GenericHttpResponse {
+    statusCode?: number;
+    setHeader(name: string, value: string): void;
+    end(body?: string): void;
+}
+/**
+ * Creates a kill-switch middleware that intercepts all traffic if an application is deactivated.
+ *
+ * @param getAppStatus - Callback returning current platform status of the application
+ * @returns Middleware function returning true if allowed to proceed, false if blocked (503)
+ *
+ * @example
+ * ```typescript
+ * const killSwitch = createAppKillSwitchMiddleware(() => appState.status);
+ * const allowed = await killSwitch(req, res);
+ * if (!allowed) return;
+ * ```
+ */
+declare function createAppKillSwitchMiddleware(getAppStatus: () => Promise<AppStatus> | AppStatus): (req: GenericHttpRequest, res: GenericHttpResponse) => Promise<boolean>;
+/**
+ * Options configuring request authentication middleware.
+ */
+interface CreateAuthMiddlewareOptions {
+    /** Whitelisted public endpoints bypassing authentication */
+    publicPaths?: readonly string[];
+    /** Function resolving an API key against store */
+    validateApiKey?: (key: string) => Promise<AuthContext | null>;
+    /** Function resolving a Bearer session token against JWKS or session store */
+    validateToken?: (token: string) => Promise<AuthContext | null>;
+}
+/**
+ * Universal authentication middleware verifying API keys and Bearer tokens.
+ *
+ * @param options - Configuration options
+ * @returns Middleware handler
+ */
+declare function createAuthMiddleware(options: CreateAuthMiddlewareOptions): (req: GenericHttpRequest, res: GenericHttpResponse) => Promise<boolean>;
+
+export { type ApiKey, type ApiKeyValidationResult, AppStatus, type AuthContext, type AuthUser, type CreateAuthMiddlewareOptions, DEFAULT_API_KEY_CACHE_TTL_MS, DEFAULT_API_KEY_HEADER, DEFAULT_AUTH_HEADER, DEFAULT_BEARER_PREFIX, DEFAULT_JWKS_CACHE_TTL_MS, DEFAULT_PUBLIC_PATHS, type GenericHttpRequest, type GenericHttpResponse, HTTP_STATUS_FORBIDDEN, HTTP_STATUS_SERVICE_UNAVAILABLE, HTTP_STATUS_UNAUTHORIZED, type JwksConfig, JwksValidator, type JwtPayload, M2mApiKeyValidator, type M2mConfig, createAppKillSwitchMiddleware, createAuthMiddleware, requireApiKey, requireScope, requireUser };