@yuva-devlab/auth-server 0.2.0 → 1.0.0

package/dist/index.d.cts

@@ -11,6 +11,8 @@ declare const DEFAULT_API_KEY_HEADER = "x-api-key";
 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 */
@@ -105,6 +107,44 @@ interface JwksConfig {
 /**
  * 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;
@@ -113,32 +153,26 @@ interface JwtPayload {
     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 In-memory cached RS256 JWKS validator for authenticating JWT session tokens.
+ * @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.
- *
- * @example
- * ```typescript
- * import { JwksValidator } from "@yuva-devlab/auth-server";
- *
- * const validator = new JwksValidator({
- *   jwksUri: "https://auth.devlab.io/.well-known/jwks.json",
- *   issuer: "https://auth.devlab.io",
- *   audience: "api.devlab.io",
- * });
- *
- * const claims = await validator.verifyToken(token);
- * ```
  */
 declare class JwksValidator {
     private readonly jwksUri;
@@ -146,35 +180,42 @@ declare class JwksValidator {
     private readonly issuer?;
     private readonly cacheTtlMs;
     private keyCache;
-    /**
-     * Initializes the JWKS validator.
-     *
-     * @param config - JWKS configuration parameters
-     */
-    constructor(config: JwksConfig);
-    /**
-     * Decodes a JWT token without verifying cryptographic signature.
-     *
-     * @param token - Base64Url encoded JWT string
-     * @returns Header and payload objects
-     */
+    private jwksSetCache;
+    constructor(config?: Partial<JwksConfig>);
     parseUnverified(token: string): {
         header: Record<string, unknown>;
         payload: JwtPayload;
+        rawHeader: string;
+        rawPayload: string;
+        signature: string;
     };
-    /**
-     * Verifies standard claims (exp, nbf, iss, aud) on a JWT token.
-     *
-     * @param token - Bearer access token
-     * @returns Validated JwtPayload claims
-     */
+    private fetchJwks;
+    private resolveKeyObject;
     verifyToken(token: string): Promise<JwtPayload>;
-    /**
-     * Clears cached public keys from memory.
-     */
     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.
@@ -266,4 +307,4 @@ interface CreateAuthMiddlewareOptions {
  */
 declare function createAuthMiddleware(options: CreateAuthMiddlewareOptions): (req: GenericHttpRequest, res: GenericHttpResponse) => Promise<boolean>;
 
-export { type ApiKey, AppStatus, type AuthContext, type AuthUser, type CreateAuthMiddlewareOptions, 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, createAppKillSwitchMiddleware, createAuthMiddleware, requireApiKey, requireScope, requireUser };
+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

@@ -11,6 +11,8 @@ declare const DEFAULT_API_KEY_HEADER = "x-api-key";
 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 */
@@ -105,6 +107,44 @@ interface JwksConfig {
 /**
  * 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;
@@ -113,32 +153,26 @@ interface JwtPayload {
     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 In-memory cached RS256 JWKS validator for authenticating JWT session tokens.
+ * @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.
- *
- * @example
- * ```typescript
- * import { JwksValidator } from "@yuva-devlab/auth-server";
- *
- * const validator = new JwksValidator({
- *   jwksUri: "https://auth.devlab.io/.well-known/jwks.json",
- *   issuer: "https://auth.devlab.io",
- *   audience: "api.devlab.io",
- * });
- *
- * const claims = await validator.verifyToken(token);
- * ```
  */
 declare class JwksValidator {
     private readonly jwksUri;
@@ -146,35 +180,42 @@ declare class JwksValidator {
     private readonly issuer?;
     private readonly cacheTtlMs;
     private keyCache;
-    /**
-     * Initializes the JWKS validator.
-     *
-     * @param config - JWKS configuration parameters
-     */
-    constructor(config: JwksConfig);
-    /**
-     * Decodes a JWT token without verifying cryptographic signature.
-     *
-     * @param token - Base64Url encoded JWT string
-     * @returns Header and payload objects
-     */
+    private jwksSetCache;
+    constructor(config?: Partial<JwksConfig>);
     parseUnverified(token: string): {
         header: Record<string, unknown>;
         payload: JwtPayload;
+        rawHeader: string;
+        rawPayload: string;
+        signature: string;
     };
-    /**
-     * Verifies standard claims (exp, nbf, iss, aud) on a JWT token.
-     *
-     * @param token - Bearer access token
-     * @returns Validated JwtPayload claims
-     */
+    private fetchJwks;
+    private resolveKeyObject;
     verifyToken(token: string): Promise<JwtPayload>;
-    /**
-     * Clears cached public keys from memory.
-     */
     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.
@@ -266,4 +307,4 @@ interface CreateAuthMiddlewareOptions {
  */
 declare function createAuthMiddleware(options: CreateAuthMiddlewareOptions): (req: GenericHttpRequest, res: GenericHttpResponse) => Promise<boolean>;
 
-export { type ApiKey, AppStatus, type AuthContext, type AuthUser, type CreateAuthMiddlewareOptions, 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, createAppKillSwitchMiddleware, createAuthMiddleware, requireApiKey, requireScope, requireUser };
+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 };