@blokjs/runner 0.2.0

package/dist/security/EncryptionAtRest.js

@@ -0,0 +1,236 @@
+/**
+ * Encryption at Rest for Blok Framework
+ *
+ * Provides AES-256-GCM encryption and decryption for data at rest:
+ * - Symmetric encryption using AES-256-GCM (authenticated encryption)
+ * - Key derivation via PBKDF2 with configurable iterations and salt length
+ * - JSON object encryption/decryption with type safety
+ * - Key rotation support for seamless secret re-keying
+ *
+ * @example
+ * ```typescript
+ * import { EncryptionAtRest } from "@blokjs/runner";
+ *
+ * const encryption = new EncryptionAtRest({
+ *   algorithm: "aes-256-gcm",
+ *   keyDerivation: { iterations: 100_000, saltLength: 16, digest: "sha512" },
+ *   encoding: "base64",
+ * });
+ *
+ * // Encrypt a string
+ * const payload = encryption.encrypt("sensitive data", "my-secret-key");
+ *
+ * // Decrypt it back
+ * const plaintext = encryption.decrypt(payload, "my-secret-key");
+ *
+ * // Encrypt/decrypt JSON objects
+ * const encrypted = encryption.encryptObject({ userId: 42, email: "a@b.com" }, "key");
+ * const obj = encryption.decryptObject<{ userId: number; email: string }>(encrypted, "key");
+ *
+ * // Rotate encryption key
+ * const reEncrypted = encryption.rotateKey(encrypted, "old-key", "new-key");
+ * ```
+ */
+import { createCipheriv, createDecipheriv, pbkdf2Sync, randomBytes, } from "node:crypto";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** AES-256-GCM requires a 256-bit (32 byte) key */
+const KEY_LENGTH_BYTES = 32;
+/** GCM recommended IV length is 12 bytes (96 bits) */
+const IV_LENGTH_BYTES = 12;
+/** GCM authentication tag length in bytes */
+const AUTH_TAG_LENGTH_BYTES = 16;
+const DEFAULT_KEY_DERIVATION = {
+    iterations: 100_000,
+    saltLength: 16,
+    digest: "sha512",
+};
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+/**
+ * Provides AES-256-GCM encryption and decryption for data at rest.
+ *
+ * All encrypted payloads are self-describing: they embed the IV, auth tag,
+ * and algorithm so that decryption does not require out-of-band metadata.
+ *
+ * Keys are derived from a passphrase via PBKDF2 with a per-encryption random
+ * salt.  The salt is prepended to the ciphertext so it can be recovered
+ * during decryption.
+ *
+ * @example
+ * ```typescript
+ * const enc = new EncryptionAtRest();
+ * const payload = enc.encrypt("hello", "passphrase");
+ * const plain = enc.decrypt(payload, "passphrase");
+ * console.log(plain); // "hello"
+ * ```
+ */
+export class EncryptionAtRest {
+    algorithm;
+    keyDerivation;
+    encoding;
+    /**
+     * Create a new EncryptionAtRest instance.
+     *
+     * @param config - Optional configuration overrides
+     */
+    constructor(config) {
+        this.algorithm = config?.algorithm ?? "aes-256-gcm";
+        this.keyDerivation = {
+            ...DEFAULT_KEY_DERIVATION,
+            ...config?.keyDerivation,
+        };
+        this.encoding = config?.encoding ?? "base64";
+    }
+    // -----------------------------------------------------------------------
+    // Public API
+    // -----------------------------------------------------------------------
+    /**
+     * Encrypt a plaintext string using AES-256-GCM.
+     *
+     * A fresh random IV and PBKDF2 salt are generated for every call, meaning
+     * encrypting the same plaintext twice with the same key will produce
+     * different ciphertexts.
+     *
+     * @param plaintext - The string to encrypt
+     * @param key - Passphrase from which the encryption key is derived
+     * @returns An {@link EncryptedPayload} containing everything needed for decryption
+     *
+     * @example
+     * ```typescript
+     * const payload = encryption.encrypt("my secret", "passphrase");
+     * // payload.ciphertext, payload.iv, payload.tag are all present
+     * ```
+     */
+    encrypt(plaintext, key) {
+        const salt = randomBytes(this.keyDerivation.saltLength);
+        const derivedKey = this.deriveKey(key, salt);
+        const iv = randomBytes(IV_LENGTH_BYTES);
+        const cipher = createCipheriv(this.algorithm, derivedKey, iv, {
+            authTagLength: AUTH_TAG_LENGTH_BYTES,
+        });
+        const encrypted = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+        const tag = cipher.getAuthTag();
+        // Prepend the salt to the ciphertext so it can be recovered on decrypt
+        const ciphertextWithSalt = Buffer.concat([salt, encrypted]);
+        return {
+            iv: iv.toString(this.encoding),
+            ciphertext: ciphertextWithSalt.toString(this.encoding),
+            tag: tag.toString(this.encoding),
+            algorithm: this.algorithm,
+        };
+    }
+    /**
+     * Decrypt an {@link EncryptedPayload} back to the original plaintext.
+     *
+     * @param payload - The encrypted payload produced by {@link encrypt}
+     * @param key - The same passphrase that was used for encryption
+     * @returns The original plaintext string
+     * @throws {Error} If the key is wrong or the payload has been tampered with
+     *
+     * @example
+     * ```typescript
+     * const plaintext = encryption.decrypt(payload, "passphrase");
+     * ```
+     */
+    decrypt(payload, key) {
+        const iv = Buffer.from(payload.iv, this.encoding);
+        const tag = Buffer.from(payload.tag, this.encoding);
+        const ciphertextWithSalt = Buffer.from(payload.ciphertext, this.encoding);
+        // Extract the salt from the beginning of the ciphertext
+        const salt = ciphertextWithSalt.subarray(0, this.keyDerivation.saltLength);
+        const ciphertext = ciphertextWithSalt.subarray(this.keyDerivation.saltLength);
+        const derivedKey = this.deriveKey(key, salt);
+        const decipher = createDecipheriv(this.algorithm, derivedKey, iv, {
+            authTagLength: AUTH_TAG_LENGTH_BYTES,
+        });
+        decipher.setAuthTag(tag);
+        const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+        return decrypted.toString("utf8");
+    }
+    /**
+     * Encrypt a JSON-serializable object.
+     *
+     * The object is serialized to JSON and then encrypted.  The result is a
+     * single Base64/hex string that encodes the full {@link EncryptedPayload}
+     * as JSON.
+     *
+     * @typeParam T - Type of the object being encrypted
+     * @param obj - The object to encrypt
+     * @param key - Passphrase from which the encryption key is derived
+     * @returns A single encoded string representing the encrypted object
+     *
+     * @example
+     * ```typescript
+     * const token = encryption.encryptObject({ userId: 1 }, "key");
+     * ```
+     */
+    encryptObject(obj, key) {
+        const json = JSON.stringify(obj);
+        const payload = this.encrypt(json, key);
+        return Buffer.from(JSON.stringify(payload)).toString(this.encoding);
+    }
+    /**
+     * Decrypt a string produced by {@link encryptObject} back to the original
+     * typed object.
+     *
+     * @typeParam T - Expected type of the decrypted object
+     * @param ciphertext - The encoded string produced by {@link encryptObject}
+     * @param key - The same passphrase that was used for encryption
+     * @returns The original object
+     * @throws {Error} If decryption or JSON parsing fails
+     *
+     * @example
+     * ```typescript
+     * const obj = encryption.decryptObject<{ userId: number }>(token, "key");
+     * console.log(obj.userId); // 1
+     * ```
+     */
+    decryptObject(ciphertext, key) {
+        const payloadJson = Buffer.from(ciphertext, this.encoding).toString("utf8");
+        const payload = JSON.parse(payloadJson);
+        const json = this.decrypt(payload, key);
+        return JSON.parse(json);
+    }
+    /**
+     * Re-encrypt data with a new key (key rotation).
+     *
+     * This is a convenience method that decrypts with the old key and
+     * re-encrypts with the new key in a single call.  It works with the
+     * encoded strings produced by {@link encryptObject}.
+     *
+     * @param data - The encoded ciphertext string to re-encrypt
+     * @param oldKey - The current passphrase
+     * @param newKey - The new passphrase to encrypt with
+     * @returns A new encoded ciphertext string encrypted under the new key
+     *
+     * @example
+     * ```typescript
+     * const rotated = encryption.rotateKey(existingCiphertext, "old-pass", "new-pass");
+     * ```
+     */
+    rotateKey(data, oldKey, newKey) {
+        const payloadJson = Buffer.from(data, this.encoding).toString("utf8");
+        const payload = JSON.parse(payloadJson);
+        const plaintext = this.decrypt(payload, oldKey);
+        const newPayload = this.encrypt(plaintext, newKey);
+        return Buffer.from(JSON.stringify(newPayload)).toString(this.encoding);
+    }
+    // -----------------------------------------------------------------------
+    // Private helpers
+    // -----------------------------------------------------------------------
+    /**
+     * Derive a fixed-length encryption key from a passphrase and salt using
+     * PBKDF2.
+     *
+     * @param passphrase - The user-supplied passphrase
+     * @param salt - Random salt bytes
+     * @returns A Buffer of {@link KEY_LENGTH_BYTES} bytes
+     */
+    deriveKey(passphrase, salt) {
+        return pbkdf2Sync(passphrase, salt, this.keyDerivation.iterations, KEY_LENGTH_BYTES, this.keyDerivation.digest);
+    }
+}
+//# sourceMappingURL=EncryptionAtRest.js.map

package/dist/security/EncryptionAtRest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EncryptionAtRest.js","sourceRoot":"","sources":["../../src/security/EncryptionAtRest.ts"],"names":[],"mappings":"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"}

package/dist/security/OAuthProvider.d.ts

@@ -0,0 +1,334 @@
+/**
+ * OAuth 2.0 / OpenID Connect Authentication Provider for Blok
+ *
+ * Provides standards-compliant OIDC authentication with:
+ * - OIDC Discovery (/.well-known/openid-configuration)
+ * - JWKS-based public key retrieval and caching
+ * - JWT verification using RS256 (RSA) and ES256 (ECDSA) via Node.js crypto
+ * - Token claims validation (exp, nbf, iss, aud)
+ * - Token introspection for opaque tokens (RFC 7662)
+ * - LRU token cache with TTL-based expiry
+ *
+ * Uses only Node.js built-in modules (node:crypto, node:buffer).
+ * No external JWT libraries required.
+ *
+ * @example
+ * ```typescript
+ * const oidcProvider = new OAuthOIDCProvider({
+ *   issuerUrl: "https://auth.example.com",
+ *   clientId: "my-app",
+ *   audience: "https://api.example.com",
+ * });
+ *
+ * const auth = new AuthMiddleware({
+ *   providers: [oidcProvider],
+ * });
+ * ```
+ */
+import type { AuthIdentity, AuthProvider, AuthRequest, AuthResult } from "./AuthMiddleware";
+/**
+ * Configuration for the OAuth 2.0 / OIDC authentication provider
+ */
+export interface OAuthOIDCConfig {
+    /** OIDC issuer URL (e.g. "https://auth.example.com") */
+    issuerUrl: string;
+    /** OAuth 2.0 client ID */
+    clientId: string;
+    /** OAuth 2.0 client secret (required for token introspection) */
+    clientSecret?: string;
+    /** Expected audience claim value */
+    audience?: string;
+    /** Allowed JWT signing algorithms (default: ["RS256", "ES256"]) */
+    allowedAlgorithms?: string[];
+    /** JWKS URI override (auto-discovered from OIDC metadata when omitted) */
+    jwksUri?: string;
+    /** JWT claim that contains user roles (default: "roles") */
+    rolesClaim?: string;
+    /** JWT claim that contains scopes (default: "scope") */
+    scopesClaim?: string;
+    /** Clock skew tolerance in seconds for exp/nbf checks (default: 30) */
+    clockToleranceSec?: number;
+    /** Whether to cache the JWKS key set (default: true) */
+    cacheJWKS?: boolean;
+    /** Whether to cache the OIDC discovery document (default: true) */
+    cacheDiscovery?: boolean;
+    /** Token introspection endpoint override (auto-discovered when omitted) */
+    introspectionEndpoint?: string;
+}
+/**
+ * OpenID Connect Discovery document as defined in the OIDC specification
+ *
+ * @see https://openid.net/specs/openid-connect-discovery-1_0.html
+ */
+export interface OIDCDiscoveryDocument {
+    /** Issuer identifier */
+    issuer: string;
+    /** URL of the authorization endpoint */
+    authorization_endpoint: string;
+    /** URL of the token endpoint */
+    token_endpoint: string;
+    /** URL of the userinfo endpoint */
+    userinfo_endpoint: string;
+    /** URL of the JWKS endpoint */
+    jwks_uri: string;
+    /** Supported OAuth 2.0 scopes */
+    scopes_supported: string[];
+    /** Supported OAuth 2.0 response types */
+    response_types_supported: string[];
+    /** Supported OpenID Connect claims */
+    claims_supported: string[];
+    /** Token introspection endpoint (optional, RFC 7662) */
+    introspection_endpoint?: string;
+    /** Additional fields that may appear in the discovery document */
+    [key: string]: unknown;
+}
+/**
+ * JSON Web Key as defined in RFC 7517
+ */
+export interface JWK {
+    /** Key type (e.g. "RSA", "EC") */
+    kty: string;
+    /** Key ID */
+    kid: string;
+    /** Key usage (e.g. "sig") */
+    use?: string;
+    /** Algorithm (e.g. "RS256", "ES256") */
+    alg?: string;
+    /** RSA modulus (base64url-encoded) */
+    n?: string;
+    /** RSA exponent (base64url-encoded) */
+    e?: string;
+    /** EC x-coordinate (base64url-encoded) */
+    x?: string;
+    /** EC y-coordinate (base64url-encoded) */
+    y?: string;
+    /** EC curve name (e.g. "P-256") */
+    crv?: string;
+}
+/**
+ * JSON Web Key Set as defined in RFC 7517
+ */
+export interface JWKS {
+    /** Array of JSON Web Keys */
+    keys: JWK[];
+}
+/** Statistics returned by TokenCache.getStats() */
+export interface TokenCacheStats {
+    /** Number of entries currently in the cache */
+    size: number;
+    /** Maximum number of entries allowed */
+    maxSize: number;
+    /** Total number of cache hits */
+    hits: number;
+    /** Total number of cache misses */
+    misses: number;
+    /** Total number of entries evicted due to TTL or capacity */
+    evictions: number;
+}
+/**
+ * LRU-style token cache with TTL-based expiry.
+ *
+ * Caches validated token identities keyed by a SHA-256 hash of the raw token.
+ * When the cache exceeds its maximum size the least-recently-used entry is
+ * evicted.
+ *
+ * @example
+ * ```typescript
+ * const cache = new TokenCache(500);
+ * const hash = cache.hashToken(rawJwt);
+ *
+ * // Store after validation
+ * cache.set(hash, identity, 3600_000);
+ *
+ * // Retrieve on subsequent requests
+ * const cached = cache.get(hash);
+ * ```
+ */
+export declare class TokenCache {
+    private cache;
+    private readonly maxSize;
+    private hits;
+    private misses;
+    private evictions;
+    constructor(maxSize?: number);
+    /**
+     * Retrieve a cached identity by token hash.
+     * Returns `undefined` if the entry is missing or has expired.
+     * Moves the entry to the end of the map (most-recently-used).
+     */
+    get(tokenHash: string): AuthIdentity | undefined;
+    /**
+     * Store an identity in the cache.
+     *
+     * @param tokenHash - SHA-256 hex hash of the raw token
+     * @param identity  - Validated identity to cache
+     * @param ttlMs     - Time-to-live in milliseconds
+     */
+    set(tokenHash: string, identity: AuthIdentity, ttlMs: number): void;
+    /**
+     * Invalidate (remove) a specific entry by token hash
+     */
+    invalidate(tokenHash: string): boolean;
+    /**
+     * Remove all entries from the cache and reset statistics
+     */
+    clear(): void;
+    /**
+     * Return cache performance statistics
+     */
+    getStats(): TokenCacheStats;
+    /**
+     * Compute a SHA-256 hex digest suitable for use as a cache key
+     */
+    static hashToken(token: string): string;
+}
+/**
+ * OAuth 2.0 / OpenID Connect Authentication Provider
+ *
+ * Validates JWT access tokens issued by an OIDC-compliant identity provider.
+ * Automatically discovers OIDC metadata and JWKS endpoints, verifies token
+ * signatures using RS256 or ES256, and validates standard claims.
+ *
+ * For opaque (non-JWT) tokens, falls back to RFC 7662 token introspection
+ * when an introspection endpoint is configured or discovered.
+ *
+ * @example
+ * ```typescript
+ * const provider = new OAuthOIDCProvider({
+ *   issuerUrl: "https://accounts.google.com",
+ *   clientId: "my-client-id",
+ *   audience: "https://api.example.com",
+ * });
+ *
+ * const result = await provider.authenticate({
+ *   headers: { authorization: "Bearer eyJhbGciOi..." },
+ * });
+ *
+ * if (result.authenticated) {
+ *   console.log("Authenticated:", result.identity?.sub);
+ * }
+ * ```
+ */
+export declare class OAuthOIDCProvider implements AuthProvider {
+    readonly name = "oauth-oidc";
+    private config;
+    /** Cached OIDC discovery document */
+    private discoveryCache;
+    /** Cached JWKS keyset */
+    private jwksCache;
+    /** Pre-imported Node.js KeyObjects keyed by kid */
+    private keyObjectCache;
+    /** Token result cache */
+    private tokenCache;
+    constructor(config: OAuthOIDCConfig);
+    /**
+     * Authenticate an incoming request by extracting and verifying the
+     * Bearer token from the Authorization header.
+     */
+    authenticate(request: AuthRequest): Promise<AuthResult>;
+    /**
+     * Fetch and parse the OIDC discovery document from the issuer's
+     * `/.well-known/openid-configuration` endpoint.
+     *
+     * The result is cached when `cacheDiscovery` is enabled (default).
+     *
+     * @param issuerUrl - The OIDC issuer URL
+     * @returns Parsed OIDC discovery document
+     */
+    discoverConfiguration(issuerUrl: string): Promise<OIDCDiscoveryDocument>;
+    /**
+     * Fetch the JSON Web Key Set from the specified URI.
+     *
+     * The result is cached when `cacheJWKS` is enabled (default).
+     *
+     * @param jwksUri - URL of the JWKS endpoint
+     * @returns The parsed JWKS
+     */
+    fetchJWKS(jwksUri: string): Promise<JWKS>;
+    /**
+     * Introspect an opaque token via the RFC 7662 token introspection endpoint.
+     *
+     * Requires `clientId` and `clientSecret` for Basic authentication.
+     *
+     * @param token                - The raw token string
+     * @param introspectionEndpoint - URL of the introspection endpoint
+     * @returns Resolved AuthIdentity when the token is active, otherwise `null`
+     */
+    introspectToken(token: string, introspectionEndpoint: string): Promise<AuthIdentity | null>;
+    /**
+     * Verify a JWT access token using the issuer's public keys.
+     *
+     * 1. Decodes the JWT header to determine `alg` and `kid`.
+     * 2. Resolves the JWKS (via discovery or explicit config).
+     * 3. Selects the matching JWK by `kid`.
+     * 4. Verifies the signature using RS256 or ES256.
+     * 5. Validates standard claims (exp, nbf, iss, aud).
+     *
+     * @param token - Raw JWT string
+     * @returns Resolved AuthIdentity on success, `null` on failure
+     */
+    private verifyJWT;
+    /**
+     * Verify a JWT signature using the given algorithm and public key.
+     *
+     * @param alg          - JWT algorithm (RS256 or ES256)
+     * @param key          - Node.js KeyObject containing the public key
+     * @param signingInput - The `header.payload` string that was signed
+     * @param signature    - Raw signature bytes
+     * @returns `true` if the signature is valid
+     */
+    private verifySignature;
+    /**
+     * Convert a raw ECDSA signature (r || s, 64 bytes for P-256) to
+     * DER-encoded format expected by Node.js crypto.
+     *
+     * @param raw - Raw ECDSA signature bytes
+     * @returns DER-encoded signature buffer
+     */
+    private rawEcdsaToDer;
+    /**
+     * Resolve a Node.js KeyObject for the given algorithm and key ID.
+     *
+     * Performs OIDC discovery and JWKS fetch as needed, then selects the
+     * appropriate JWK and imports it into a native KeyObject.
+     */
+    private resolvePublicKey;
+    /**
+     * Select a JWK from the key set that matches the algorithm and key ID.
+     */
+    private selectKey;
+    /**
+     * Import a JWK into a Node.js KeyObject using `crypto.createPublicKey`.
+     */
+    private importJWK;
+    /**
+     * Validate standard JWT claims: exp, nbf, iss, aud.
+     *
+     * @returns An error message string if validation fails, `null` otherwise
+     */
+    private validateClaims;
+    /**
+     * Extract roles from token claims using the configured claim names.
+     *
+     * Checks the `rolesClaim` first (e.g. "roles"), then falls back
+     * to parsing space-delimited scopes from `scopesClaim` (e.g. "scope").
+     */
+    private extractRoles;
+    /**
+     * Resolve the JWKS URI, either from explicit config or via OIDC discovery
+     */
+    private resolveJwksUri;
+    /**
+     * Resolve the token introspection endpoint from OIDC discovery
+     */
+    private resolveIntrospectionEndpoint;
+    /**
+     * Clear all internal caches (discovery, JWKS, token cache).
+     * Useful during key rotation or configuration changes.
+     */
+    clearCaches(): void;
+    /**
+     * Return statistics from the token cache
+     */
+    getTokenCacheStats(): TokenCacheStats;
+}