@tinyrack/tinyauth-server 0.0.7

package/dist/services/jwt.service.d.ts

@@ -0,0 +1,321 @@
+import { type JWTPayload } from 'jose';
+import { type JwtKeyEntity } from '../entities/jwt-key.entity.ts';
+import type { TinyAuthRuntimeConfig } from '../lib/config/index.ts';
+import type { MikroService } from './mikro.service.ts';
+/**
+ * Key pair with PEM-encoded keys
+ * Used for JWT signing key generation
+ */
+export interface KeyPair {
+    /** Key ID for identifying the key in JWKS */
+    kid: string;
+    /** PEM-encoded private key (PKCS#8 format) */
+    privateKey: string;
+    /** PEM-encoded public key (SPKI format) */
+    publicKey: string;
+    /** Algorithm (e.g., "RS256") */
+    algorithm: string;
+}
+/**
+ * Public JWK for JWKS endpoint (RFC 7517)
+ * All required fields are guaranteed to be present.
+ * @see https://datatracker.ietf.org/doc/html/rfc7517
+ */
+export interface PublicJWK {
+    /** Key Type (e.g., "RSA") */
+    kty: string;
+    /** Public Key Use ("sig" for signature) */
+    use: string;
+    /** Key ID */
+    kid: string;
+    /** Algorithm (e.g., "RS256") */
+    alg: string;
+    /** RSA modulus (base64url encoded) */
+    n?: string | undefined;
+    /** RSA exponent (base64url encoded) */
+    e?: string | undefined;
+    /** EC x coordinate (base64url encoded) */
+    x?: string | undefined;
+    /** EC y coordinate (base64url encoded) */
+    y?: string | undefined;
+    /** EC curve name */
+    crv?: string | undefined;
+}
+/**
+ * Base JWT payload with standard claims (RFC 7519)
+ * @see https://datatracker.ietf.org/doc/html/rfc7519#section-4.1
+ */
+interface BaseJWTPayload {
+    /** Subject - identifies the principal that is the subject of the JWT */
+    sub: string;
+    /** JWT ID - unique identifier for the JWT */
+    jti?: string | undefined;
+    /** Issued At - time at which the JWT was issued (seconds since epoch) */
+    iat?: number | undefined;
+    /** Expiration Time - time after which the JWT must not be accepted (seconds since epoch) */
+    exp?: number | undefined;
+    /** Issuer - identifies the principal that issued the JWT */
+    iss?: string | undefined;
+}
+/**
+ * Access token payload structure (RFC 6749)
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-1.4
+ */
+export interface AccessTokenPayload extends BaseJWTPayload {
+    /** Token type discriminator */
+    typ: 'access_token';
+    /** Client identifier */
+    client_id: string;
+    /** Space-separated list of scopes */
+    scope: string;
+    /** Audience - intended recipient of the token */
+    aud?: string | undefined;
+}
+/**
+ * Refresh token payload structure (RFC 6749)
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-1.5
+ */
+export interface RefreshTokenPayload extends BaseJWTPayload {
+    /** Token type discriminator */
+    typ: 'refresh_token';
+    /** Client identifier */
+    client_id: string;
+    /** Space-separated list of scopes */
+    scope: string;
+    /** Audience - intended recipient of the token */
+    aud?: string | undefined;
+}
+/**
+ * ID token payload structure (OpenID Connect Core 1.0 §2)
+ * @see https://openid.net/specs/openid-connect-core-1_0.html#IDToken
+ */
+export interface IdTokenPayload extends BaseJWTPayload {
+    /** Audience - client_id of the Relying Party */
+    aud: string;
+    /** Nonce - value used to associate a Client session with an ID Token */
+    nonce?: string | undefined;
+    /**
+     * Time when the End-User authentication occurred (OIDC Core 1.0 §2)
+     * Unix timestamp in seconds
+     */
+    auth_time?: number | undefined;
+    /**
+     * Access Token hash value (OIDC Core 1.0 §3.1.3.6)
+     * Left-most half of the hash of the access token using the hash algorithm
+     * from the alg Header Parameter of the ID Token's JOSE Header
+     */
+    at_hash?: string | undefined;
+    /** Email address */
+    email?: string | undefined;
+    /** Whether the email address has been verified */
+    email_verified?: boolean | undefined;
+    /** Full name */
+    name?: string | undefined;
+    /** Profile picture URL */
+    picture?: string | undefined;
+}
+/**
+ * JWT Service
+ *
+ * Handles JWT signing and verification using RS256 asymmetric keys.
+ * Manages RSA key pairs for signing with automatic rotation support.
+ * Supports token revocation via RevokedToken repository.
+ *
+ * Key Lifecycle:
+ * 1. next: Generated, waiting to be activated
+ * 2. active: Currently used for signing tokens
+ * 3. previous: Recently rotated, still valid for verification
+ * 4. retired: No longer valid for any operation
+ */
+export declare class JwtService {
+    /** Cache for active signing key */
+    private activeKeyCache;
+    private activeKeyCacheTime;
+    private readonly CACHE_TTL_MS;
+    /** Deduplication lock for concurrent ensureActiveKey calls */
+    private ensureActiveKeyPromise;
+    private readonly config;
+    private readonly mikro;
+    constructor(config: TinyAuthRuntimeConfig, mikro: MikroService);
+    /**
+     * Generate a new RSA key pair
+     *
+     * @returns Generated key pair with PEM-encoded keys
+     */
+    generateKeyPair(): Promise<KeyPair>;
+    /**
+     * Generate a unique Key ID
+     *
+     * Format: key-{timestamp}-{random}
+     */
+    private generateKid;
+    /**
+     * Ensure at least one active key exists
+     *
+     * Called on server startup to guarantee signing capability.
+     * Generates a new key if none exists.
+     */
+    ensureActiveKey(): Promise<JwtKeyEntity>;
+    /**
+     * Create a new key and immediately activate it
+     */
+    createAndActivateKey(): Promise<JwtKeyEntity>;
+    /**
+     * Create a new key in 'next' status (pre-rotation)
+     */
+    createNextKey(): Promise<JwtKeyEntity>;
+    /**
+     * Activate a key (change status to 'active')
+     */
+    activateKey(key: JwtKeyEntity): Promise<JwtKeyEntity>;
+    /**
+     * Deactivate current active key and promote next key
+     *
+     * This is the main rotation operation:
+     * 1. Current active -> previous
+     * 2. Next -> active (or create new if no next)
+     */
+    rotateKeys(): Promise<JwtKeyEntity>;
+    /**
+     * Retire old keys past the overlap period
+     *
+     * @param overlapDays - Days to keep previous keys valid
+     */
+    retireOldKeys(overlapDays?: number): Promise<number>;
+    /**
+     * Get the active signing key (with caching)
+     *
+     * @returns Active key with private_key loaded
+     * @throws Error if no active key exists
+     */
+    getActiveKey(): Promise<JwtKeyEntity>;
+    /**
+     * Get key by kid for verification
+     *
+     * @param kid - Key ID from JWT header
+     * @returns Key entity or null
+     */
+    getKeyByKid(kid: string): Promise<JwtKeyEntity | null>;
+    /**
+     * Get all keys valid for verification
+     *
+     * @returns Array of active and previous keys
+     */
+    getVerificationKeys(): Promise<JwtKeyEntity[]>;
+    /**
+     * Convert PEM public key to JWK format for JWKS endpoint
+     *
+     * @param key - JWT Key entity
+     * @returns JWK object
+     */
+    convertToJWK(key: JwtKeyEntity): Promise<PublicJWK>;
+    /**
+     * Get JWKS (JSON Web Key Set) for public endpoint
+     *
+     * Returns all active and previous keys in JWK format.
+     *
+     * @returns JWKS object with keys array
+     */
+    getJWKS(): Promise<{
+        keys: PublicJWK[];
+    }>;
+    /**
+     * Clear the active key cache
+     *
+     * Used after bootstrap or key rotation to ensure fresh key lookup.
+     */
+    clearActiveKeyCache(): void;
+    /**
+     * Sign an access token using RS256
+     */
+    signAccessToken(payload: AccessTokenPayload): Promise<string>;
+    /**
+     * Sign a refresh token using RS256
+     */
+    signRefreshToken(payload: RefreshTokenPayload): Promise<string>;
+    /**
+     * Sign an ID token using RS256 (for OIDC)
+     *
+     * Includes standard OIDC claims:
+     * - auth_time: Time when End-User authentication occurred
+     * - at_hash: Access Token hash (when provided)
+     */
+    signIdToken(payload: IdTokenPayload): Promise<string>;
+    /**
+     * Verify and decode an access token
+     *
+     * @throws {InvalidAccessToken} When token is invalid, expired, or revoked
+     */
+    verifyAccessToken(token: string): Promise<AccessTokenPayload>;
+    /**
+     * Verify and decode a refresh token
+     *
+     * @throws {InvalidRefreshToken} When token is invalid, expired, or revoked
+     */
+    verifyRefreshToken(token: string): Promise<RefreshTokenPayload>;
+    /**
+     * Internal: Verify token with appropriate key based on kid
+     */
+    private verifyToken;
+    /**
+     * Type guard to validate access token payload structure
+     */
+    private isAccessTokenPayload;
+    /**
+     * Type guard to validate refresh token payload structure
+     */
+    private isRefreshTokenPayload;
+    /**
+     * Decode a JWT without verification (for introspection)
+     */
+    decodeToken(token: string): JWTPayload | null;
+    /**
+     * Extract Bearer token from Authorization header
+     *
+     * @param req - Fastify request object
+     * @returns Extracted Bearer token
+     * @throws {MissingAuthorizationHeader} When Authorization header is missing
+     * @throws {InvalidAuthorizationHeaderFormat} When header format is invalid
+     * @throws {MissingBearerToken} When token is missing in header
+     *
+     * @example
+     * ```typescript
+     * const token = jwtService.extractBearerToken(req);
+     * // Returns: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+     * ```
+     */
+    extractBearerToken(req: {
+        headers: {
+            authorization?: string;
+        };
+    }): string;
+    /**
+     * Validate Bearer token and return decoded payload
+     *
+     * Extracts Bearer token from Authorization header and verifies it.
+     * This is the main authentication handler for protected API endpoints.
+     *
+     * @param req - Fastify request object
+     * @returns Decoded access token payload with user and client info
+     * @throws {MissingAuthorizationHeader} When Authorization header is missing
+     * @throws {InvalidAuthorizationHeaderFormat} When header format is invalid
+     * @throws {MissingBearerToken} When token is missing in header
+     * @throws {InvalidAccessToken} When token is invalid or expired
+     *
+     * @example
+     * ```typescript
+     * // In a route handler
+     * const payload = await fastify.jwtService.validateBearerToken(req);
+     * console.log(payload.sub);       // User ID
+     * console.log(payload.client_id); // OAuth client ID
+     * console.log(payload.scope);     // Granted scopes
+     * ```
+     */
+    validateBearerToken(req: {
+        headers: {
+            authorization?: string;
+        };
+    }): Promise<AccessTokenPayload>;
+}
+export {};
+//# sourceMappingURL=jwt.service.d.ts.map

package/dist/services/jwt.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwt.service.d.ts","sourceRoot":"","sources":["../../src/services/jwt.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAQL,KAAK,UAAU,EAGhB,MAAM,MAAM,CAAC;AACd,OAAO,EAAE,KAAK,YAAY,EAAgB,MAAM,+BAA+B,CAAC;AAEhF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAEpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAMvD;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB,6CAA6C;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,6BAA6B;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,sCAAsC;IACtC,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvB,uCAAuC;IACvC,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvB,0CAA0C;IAC1C,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvB,0CAA0C;IAC1C,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvB,oBAAoB;IACpB,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1B;AAMD;;;GAGG;AACH,UAAU,cAAc;IACtB,wEAAwE;IACxE,GAAG,EAAE,MAAM,CAAC;IACZ,6CAA6C;IAC7C,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,4FAA4F;IAC5F,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,4DAA4D;IAC5D,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAmB,SAAQ,cAAc;IACxD,+BAA+B;IAC/B,GAAG,EAAE,cAAc,CAAC;IACpB,wBAAwB;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAoB,SAAQ,cAAc;IACzD,+BAA+B;IAC/B,GAAG,EAAE,eAAe,CAAC;IACrB,wBAAwB;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,cAAe,SAAQ,cAAc;IACpD,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,oBAAoB;IACpB,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,kDAAkD;IAClD,cAAc,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACrC,gBAAgB;IAChB,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,0BAA0B;IAC1B,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9B;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,UAAU;IACrB,mCAAmC;IACnC,OAAO,CAAC,cAAc,CAA6B;IACnD,OAAO,CAAC,kBAAkB,CAAa;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAa;IAE1C,8DAA8D;IAC9D,OAAO,CAAC,sBAAsB,CAAsC;IAEpE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwB;IAC/C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;gBACzB,MAAM,EAAE,qBAAqB,EAAE,KAAK,EAAE,YAAY;IAS9D;;;;OAIG;IACG,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC;IAsBzC;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAMnB;;;;;OAKG;IACG,eAAe,IAAI,OAAO,CAAC,YAAY,CAAC;IAkB9C;;OAEG;IACG,oBAAoB,IAAI,OAAO,CAAC,YAAY,CAAC;IAyBnD;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,YAAY,CAAC;IAqB5C;;OAEG;IACG,WAAW,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAY3D;;;;;;OAMG;IACG,UAAU,IAAI,OAAO,CAAC,YAAY,CAAC;IA4BzC;;;;OAIG;IACG,aAAa,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAgB1D;;;;;OAKG;IACG,YAAY,IAAI,OAAO,CAAC,YAAY,CAAC;IAgC3C;;;;;OAKG;IACG,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAI5D;;;;OAIG;IACG,mBAAmB,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IAIpD;;;;;OAKG;IACG,YAAY,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,CAAC;IAkBzD;;;;;;OAMG;IACG,OAAO,IAAI,OAAO,CAAC;QACvB,IAAI,EAAE,SAAS,EAAE,CAAC;KACnB,CAAC;IAWF;;;;OAIG;IACH,mBAAmB,IAAI,IAAI;IAQ3B;;OAEG;IACG,eAAe,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC;IAsBnE;;OAEG;IACG,gBAAgB,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC;IAsBrE;;;;;;OAMG;IACG,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IA+B3D;;;;OAIG;IACG,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAsBnE;;;;OAIG;IACG,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAsBrE;;OAEG;YACW,WAAW;IAoCzB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAW5B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAW7B;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAY7C;;;;;;;;;;;;;;OAcG;IACH,kBAAkB,CAAC,GAAG,EAAE;QAAE,OAAO,EAAE;YAAE,aAAa,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GAAG,MAAM;IAqBxE;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,mBAAmB,CAAC,GAAG,EAAE;QAC7B,OAAO,EAAE;YAAE,aAAa,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;KACrC,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAOhC"}