@blokjs/runner 0.2.0

package/dist/security/AuthMiddleware.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Authentication Middleware for Blok Triggers
+ *
+ * Provides pluggable authentication for all trigger types:
+ * - JWT Bearer token verification (RS256, HS256)
+ * - API Key verification (header, query param)
+ * - Custom auth provider support
+ *
+ * Integrates with TriggerBase via composition.
+ *
+ * @example
+ * ```typescript
+ * const auth = new AuthMiddleware({
+ *   providers: [
+ *     new JWTAuthProvider({ secret: process.env.JWT_SECRET! }),
+ *     new APIKeyAuthProvider({
+ *       keys: new Map([["my-api-key", { name: "service-a", roles: ["admin"] }]]),
+ *     }),
+ *   ],
+ * });
+ *
+ * // In Express middleware
+ * app.use(auth.expressMiddleware());
+ *
+ * // Or manually
+ * const identity = await auth.authenticate(request);
+ * ```
+ */
+export interface AuthIdentity {
+    /** Unique identifier for the authenticated entity */
+    sub: string;
+    /** Display name */
+    name?: string;
+    /** Email address */
+    email?: string;
+    /** Assigned roles */
+    roles: string[];
+    /** Additional claims/metadata */
+    claims: Record<string, unknown>;
+    /** Authentication provider that verified this identity */
+    provider: string;
+    /** When the token/key was issued */
+    issuedAt?: number;
+    /** When the token/key expires */
+    expiresAt?: number;
+}
+export interface AuthRequest {
+    headers: Record<string, string | string[] | undefined>;
+    query?: Record<string, string | string[] | undefined>;
+    path?: string;
+    method?: string;
+}
+export interface AuthResult {
+    authenticated: boolean;
+    identity?: AuthIdentity;
+    error?: string;
+    statusCode?: number;
+}
+/**
+ * Base interface for authentication providers
+ */
+export interface AuthProvider {
+    /** Unique name for this provider */
+    readonly name: string;
+    /** Try to authenticate the request */
+    authenticate(request: AuthRequest): Promise<AuthResult>;
+}
+export interface AuthMiddlewareConfig {
+    /** Authentication providers to use (tried in order) */
+    providers: AuthProvider[];
+    /** Paths to exclude from authentication (e.g., ["/health-check", "/metrics"]) */
+    excludePaths?: string[];
+    /** Whether authentication is required (default: true) */
+    required?: boolean;
+    /** Custom error handler */
+    onAuthFailure?: (result: AuthResult, request: AuthRequest) => void;
+}
+export declare class AuthMiddleware {
+    private config;
+    constructor(config: AuthMiddlewareConfig);
+    /**
+     * Authenticate a request against all registered providers.
+     * Returns the first successful authentication result.
+     */
+    authenticate(request: AuthRequest): Promise<AuthResult>;
+    /**
+     * Express-compatible middleware function
+     */
+    expressMiddleware(): (req: {
+        headers: Record<string, string>;
+        query: Record<string, string>;
+        path: string;
+        method: string;
+        auth?: AuthIdentity;
+    }, res: {
+        status: (code: number) => {
+            json: (body: unknown) => void;
+        };
+    }, next: () => void) => Promise<void>;
+    private isExcludedPath;
+}
+/**
+ * JWT Authentication Provider
+ *
+ * Verifies JWT tokens from the Authorization: Bearer header.
+ * Supports HS256 (shared secret) out of the box.
+ */
+export interface JWTAuthProviderConfig {
+    /** Secret key for HS256 verification */
+    secret: string;
+    /** Expected issuer (iss claim) */
+    issuer?: string;
+    /** Expected audience (aud claim) */
+    audience?: string;
+    /** Header name to read token from (default: "authorization") */
+    headerName?: string;
+    /** Clock tolerance in seconds for exp/nbf validation (default: 30) */
+    clockToleranceSec?: number;
+    /** Map JWT claims to roles (claim name → role mapping function) */
+    rolesClaim?: string;
+}
+export declare class JWTAuthProvider implements AuthProvider {
+    readonly name = "jwt";
+    private config;
+    constructor(config: JWTAuthProviderConfig);
+    authenticate(request: AuthRequest): Promise<AuthResult>;
+    /**
+     * Verify JWT token using HS256
+     */
+    private verifyToken;
+}
+/**
+ * API Key Authentication Provider
+ *
+ * Verifies API keys from headers or query parameters.
+ */
+export interface APIKeyInfo {
+    /** Name/label for this API key */
+    name: string;
+    /** Roles assigned to this key */
+    roles: string[];
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+    /** Expiration timestamp (Unix seconds) */
+    expiresAt?: number;
+}
+export interface APIKeyAuthProviderConfig {
+    /** Map of API key → key info */
+    keys: Map<string, APIKeyInfo>;
+    /** Header name to read key from (default: "x-api-key") */
+    headerName?: string;
+    /** Query parameter name to read key from (default: "api_key") */
+    queryParam?: string;
+    /** Custom key validation function (e.g., for database lookups) */
+    validate?: (key: string) => Promise<APIKeyInfo | null>;
+}
+export declare class APIKeyAuthProvider implements AuthProvider {
+    readonly name = "api-key";
+    private config;
+    constructor(config: APIKeyAuthProviderConfig);
+    authenticate(request: AuthRequest): Promise<AuthResult>;
+    private buildResult;
+}

package/dist/security/AuthMiddleware.js

@@ -0,0 +1,274 @@
+/**
+ * Authentication Middleware for Blok Triggers
+ *
+ * Provides pluggable authentication for all trigger types:
+ * - JWT Bearer token verification (RS256, HS256)
+ * - API Key verification (header, query param)
+ * - Custom auth provider support
+ *
+ * Integrates with TriggerBase via composition.
+ *
+ * @example
+ * ```typescript
+ * const auth = new AuthMiddleware({
+ *   providers: [
+ *     new JWTAuthProvider({ secret: process.env.JWT_SECRET! }),
+ *     new APIKeyAuthProvider({
+ *       keys: new Map([["my-api-key", { name: "service-a", roles: ["admin"] }]]),
+ *     }),
+ *   ],
+ * });
+ *
+ * // In Express middleware
+ * app.use(auth.expressMiddleware());
+ *
+ * // Or manually
+ * const identity = await auth.authenticate(request);
+ * ```
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+export class AuthMiddleware {
+    config;
+    constructor(config) {
+        this.config = {
+            excludePaths: ["/health-check", "/metrics", "/health", "/liveness", "/readiness"],
+            required: true,
+            ...config,
+        };
+    }
+    /**
+     * Authenticate a request against all registered providers.
+     * Returns the first successful authentication result.
+     */
+    async authenticate(request) {
+        // Check excluded paths
+        if (request.path && this.isExcludedPath(request.path)) {
+            return {
+                authenticated: true,
+                identity: {
+                    sub: "anonymous",
+                    roles: ["public"],
+                    claims: {},
+                    provider: "excluded-path",
+                },
+            };
+        }
+        // Try each provider in order
+        for (const provider of this.config.providers) {
+            const result = await provider.authenticate(request);
+            if (result.authenticated) {
+                return result;
+            }
+        }
+        // No provider authenticated the request
+        if (!this.config.required) {
+            return {
+                authenticated: true,
+                identity: {
+                    sub: "anonymous",
+                    roles: ["public"],
+                    claims: {},
+                    provider: "anonymous",
+                },
+            };
+        }
+        const result = {
+            authenticated: false,
+            error: "Authentication required",
+            statusCode: 401,
+        };
+        if (this.config.onAuthFailure) {
+            this.config.onAuthFailure(result, request);
+        }
+        return result;
+    }
+    /**
+     * Express-compatible middleware function
+     */
+    expressMiddleware() {
+        return async (req, res, next) => {
+            const result = await this.authenticate({
+                headers: req.headers,
+                query: req.query,
+                path: req.path,
+                method: req.method,
+            });
+            if (!result.authenticated) {
+                res.status(result.statusCode || 401).json({
+                    error: result.error || "Unauthorized",
+                });
+                return;
+            }
+            // Attach identity to request
+            req.auth = result.identity;
+            next();
+        };
+    }
+    isExcludedPath(path) {
+        return (this.config.excludePaths || []).some((excluded) => path === excluded || path.startsWith(`${excluded}/`));
+    }
+}
+export class JWTAuthProvider {
+    name = "jwt";
+    config;
+    constructor(config) {
+        this.config = {
+            headerName: "authorization",
+            clockToleranceSec: 30,
+            rolesClaim: "roles",
+            ...config,
+        };
+    }
+    async authenticate(request) {
+        const headerValue = request.headers[this.config.headerName || "authorization"];
+        if (!headerValue) {
+            return { authenticated: false, error: "No authorization header" };
+        }
+        const token = String(headerValue).replace(/^Bearer\s+/i, "");
+        if (!token || token === String(headerValue)) {
+            return { authenticated: false, error: "Invalid Bearer token format" };
+        }
+        try {
+            const payload = this.verifyToken(token);
+            if (!payload) {
+                return { authenticated: false, error: "Invalid token signature", statusCode: 401 };
+            }
+            // Validate expiry
+            const now = Math.floor(Date.now() / 1000);
+            const tolerance = this.config.clockToleranceSec || 30;
+            const exp = typeof payload.exp === "number" ? payload.exp : undefined;
+            const nbf = typeof payload.nbf === "number" ? payload.nbf : undefined;
+            if (exp && exp + tolerance < now) {
+                return { authenticated: false, error: "Token expired", statusCode: 401 };
+            }
+            if (nbf && nbf - tolerance > now) {
+                return { authenticated: false, error: "Token not yet valid", statusCode: 401 };
+            }
+            // Validate issuer
+            if (this.config.issuer && payload.iss !== this.config.issuer) {
+                return { authenticated: false, error: "Invalid token issuer", statusCode: 401 };
+            }
+            // Validate audience
+            if (this.config.audience) {
+                const aud = Array.isArray(payload.aud) ? payload.aud : [payload.aud];
+                if (!aud.includes(this.config.audience)) {
+                    return { authenticated: false, error: "Invalid token audience", statusCode: 401 };
+                }
+            }
+            // Extract roles
+            const rolesClaim = this.config.rolesClaim || "roles";
+            const roles = Array.isArray(payload[rolesClaim])
+                ? payload[rolesClaim]
+                : typeof payload[rolesClaim] === "string"
+                    ? [payload[rolesClaim]]
+                    : [];
+            const iat = typeof payload.iat === "number" ? payload.iat : undefined;
+            return {
+                authenticated: true,
+                identity: {
+                    sub: typeof payload.sub === "string" ? payload.sub : "unknown",
+                    name: payload.name,
+                    email: payload.email,
+                    roles,
+                    claims: payload,
+                    provider: "jwt",
+                    issuedAt: iat,
+                    expiresAt: exp,
+                },
+            };
+        }
+        catch (err) {
+            return {
+                authenticated: false,
+                error: `Token verification failed: ${err instanceof Error ? err.message : String(err)}`,
+                statusCode: 401,
+            };
+        }
+    }
+    /**
+     * Verify JWT token using HS256
+     */
+    verifyToken(token) {
+        const parts = token.split(".");
+        if (parts.length !== 3)
+            return null;
+        const [headerB64, payloadB64, signatureB64] = parts;
+        // Verify signature (HS256)
+        const expectedSignature = createHmac("sha256", this.config.secret)
+            .update(`${headerB64}.${payloadB64}`)
+            .digest("base64url");
+        const signatureBuffer = Buffer.from(signatureB64, "base64url");
+        const expectedBuffer = Buffer.from(expectedSignature, "base64url");
+        if (signatureBuffer.length !== expectedBuffer.length)
+            return null;
+        if (!timingSafeEqual(signatureBuffer, expectedBuffer))
+            return null;
+        // Decode payload
+        try {
+            const payload = JSON.parse(Buffer.from(payloadB64, "base64url").toString("utf-8"));
+            return payload;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+export class APIKeyAuthProvider {
+    name = "api-key";
+    config;
+    constructor(config) {
+        this.config = {
+            headerName: "x-api-key",
+            queryParam: "api_key",
+            ...config,
+        };
+    }
+    async authenticate(request) {
+        // Try header first
+        let apiKey = request.headers[this.config.headerName || "x-api-key"];
+        if (Array.isArray(apiKey))
+            apiKey = apiKey[0];
+        // Then try query param
+        if (!apiKey && request.query) {
+            let queryKey = request.query[this.config.queryParam || "api_key"];
+            if (Array.isArray(queryKey))
+                queryKey = queryKey[0];
+            apiKey = queryKey;
+        }
+        if (!apiKey) {
+            return { authenticated: false, error: "No API key provided" };
+        }
+        // Try custom validator first
+        if (this.config.validate) {
+            const info = await this.config.validate(apiKey);
+            if (info) {
+                return this.buildResult(apiKey, info);
+            }
+            return { authenticated: false, error: "Invalid API key", statusCode: 401 };
+        }
+        // Check static keys
+        const info = this.config.keys.get(apiKey);
+        if (!info) {
+            return { authenticated: false, error: "Invalid API key", statusCode: 401 };
+        }
+        return this.buildResult(apiKey, info);
+    }
+    buildResult(key, info) {
+        // Check expiry
+        if (info.expiresAt && info.expiresAt < Math.floor(Date.now() / 1000)) {
+            return { authenticated: false, error: "API key expired", statusCode: 401 };
+        }
+        return {
+            authenticated: true,
+            identity: {
+                sub: info.name,
+                name: info.name,
+                roles: info.roles,
+                claims: info.metadata || {},
+                provider: "api-key",
+                expiresAt: info.expiresAt,
+            },
+        };
+    }
+}
+//# sourceMappingURL=AuthMiddleware.js.map

package/dist/security/AuthMiddleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AuthMiddleware.js","sourceRoot":"","sources":["../../src/security/AuthMiddleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAwD1D,MAAM,OAAO,cAAc;IAClB,MAAM,CAAuB;IAErC,YAAY,MAA4B;QACvC,IAAI,CAAC,MAAM,GAAG;YACb,YAAY,EAAE,CAAC,eAAe,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,CAAC;YACjF,QAAQ,EAAE,IAAI;YACd,GAAG,MAAM;SACT,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,YAAY,CAAC,OAAoB;QACtC,uBAAuB;QACvB,IAAI,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YACvD,OAAO;gBACN,aAAa,EAAE,IAAI;gBACnB,QAAQ,EAAE;oBACT,GAAG,EAAE,WAAW;oBAChB,KAAK,EAAE,CAAC,QAAQ,CAAC;oBACjB,MAAM,EAAE,EAAE;oBACV,QAAQ,EAAE,eAAe;iBACzB;aACD,CAAC;QACH,CAAC;QAED,6BAA6B;QAC7B,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;YAC9C,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;YACpD,IAAI,MAAM,CAAC,aAAa,EAAE,CAAC;gBAC1B,OAAO,MAAM,CAAC;YACf,CAAC;QACF,CAAC;QAED,wCAAwC;QACxC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YAC3B,OAAO;gBACN,aAAa,EAAE,IAAI;gBACnB,QAAQ,EAAE;oBACT,GAAG,EAAE,WAAW;oBAChB,KAAK,EAAE,CAAC,QAAQ,CAAC;oBACjB,MAAM,EAAE,EAAE;oBACV,QAAQ,EAAE,WAAW;iBACrB;aACD,CAAC;QACH,CAAC;QAED,MAAM,MAAM,GAAe;YAC1B,aAAa,EAAE,KAAK;YACpB,KAAK,EAAE,yBAAyB;YAChC,UAAU,EAAE,GAAG;SACf,CAAC;QAEF,IAAI,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC;YAC/B,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC5C,CAAC;QAED,OAAO,MAAM,CAAC;IACf,CAAC;IAED;;OAEG;IACH,iBAAiB;QAChB,OAAO,KAAK,EACX,GAMC,EACD,GAAoE,EACpE,IAAgB,EACf,EAAE;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC;gBACtC,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,KAAK,EAAE,GAAG,CAAC,KAAK;gBAChB,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,MAAM,EAAE,GAAG,CAAC,MAAM;aAClB,CAAC,CAAC;YAEH,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC;gBAC3B,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC;oBACzC,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,cAAc;iBACrC,CAAC,CAAC;gBACH,OAAO;YACR,CAAC;YAED,6BAA6B;YAC7B,GAAG,CAAC,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC;YAC3B,IAAI,EAAE,CAAC;QACR,CAAC,CAAC;IACH,CAAC;IAEO,cAAc,CAAC,IAAY;QAClC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,QAAQ,GAAG,CAAC,CAAC,CAAC;IAClH,CAAC;CACD;AAuBD,MAAM,OAAO,eAAe;IAClB,IAAI,GAAG,KAAK,CAAC;IACd,MAAM,CAAwB;IAEtC,YAAY,MAA6B;QACxC,IAAI,CAAC,MAAM,GAAG;YACb,UAAU,EAAE,eAAe;YAC3B,iBAAiB,EAAE,EAAE;YACrB,UAAU,EAAE,OAAO;YACnB,GAAG,MAAM;SACT,CAAC;IACH,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,OAAoB;QACtC,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,IAAI,eAAe,CAAC,CAAC;QAC/E,IAAI,CAAC,WAAW,EAAE,CAAC;YAClB,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,yBAAyB,EAAE,CAAC;QACnE,CAAC;QAED,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;QAC7D,IAAI,CAAC,KAAK,IAAI,KAAK,KAAK,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC;YAC7C,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,6BAA6B,EAAE,CAAC;QACvE,CAAC;QAED,IAAI,CAAC;YACJ,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;YACxC,IAAI,CAAC,OAAO,EAAE,CAAC;gBACd,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,yBAAyB,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC;YACpF,CAAC;YAED,kBAAkB;YAClB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;YAC1C,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,iBAAiB,IAAI,EAAE,CAAC;YAEtD,MAAM,GAAG,GAAG,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;YACtE,MAAM,GAAG,GAAG,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;YAEtE,IAAI,GAAG,IAAI,GAAG,GAAG,SAAS,GAAG,GAAG,EAAE,CAAC;gBAClC,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC;YAC1E,CAAC;YAED,IAAI,GAAG,IAAI,GAAG,GAAG,SAAS,GAAG,GAAG,EAAE,CAAC;gBAClC,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,qBAAqB,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC;YAChF,CAAC;YAED,kBAAkB;YAClB,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,KAAK,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;gBAC9D,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,sBAAsB,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC;YACjF,CAAC;YAED,oBAAoB;YACpB,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;gBAC1B,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;gBACrE,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;oBACzC,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,wBAAwB,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC;gBACnF,CAAC;YACF,CAAC;YAED,gBAAgB;YAChB,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU,IAAI,OAAO,CAAC;YACrD,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;gBAC/C,CAAC,CAAE,OAAO,CAAC,UAAU,CAAc;gBACnC,CAAC,CAAC,OAAO,OAAO,CAAC,UAAU,CAAC,KAAK,QAAQ;oBACxC,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAW,CAAC;oBACjC,CAAC,CAAC,EAAE,CAAC;YAEP,MAAM,GAAG,GAAG,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;YAEtE,OAAO;gBACN,aAAa,EAAE,IAAI;gBACnB,QAAQ,EAAE;oBACT,GAAG,EAAE,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS;oBAC9D,IAAI,EAAE,OAAO,CAAC,IAA0B;oBACxC,KAAK,EAAE,OAAO,CAAC,KAA2B;oBAC1C,KAAK;oBACL,MAAM,EAAE,OAAO;oBACf,QAAQ,EAAE,KAAK;oBACf,QAAQ,EAAE,GAAG;oBACb,SAAS,EAAE,GAAG;iBACd;aACD,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACd,OAAO;gBACN,aAAa,EAAE,KAAK;gBACpB,KAAK,EAAE,8BAA8B,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE;gBACvF,UAAU,EAAE,GAAG;aACf,CAAC;QACH,CAAC;IACF,CAAC;IAED;;OAEG;IACK,WAAW,CAAC,KAAa;QAChC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAEpC,MAAM,CAAC,SAAS,EAAE,UAAU,EAAE,YAAY,CAAC,GAAG,KAAK,CAAC;QAEpD,2BAA2B;QAC3B,MAAM,iBAAiB,GAAG,UAAU,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;aAChE,MAAM,CAAC,GAAG,SAAS,IAAI,UAAU,EAAE,CAAC;aACpC,MAAM,CAAC,WAAW,CAAC,CAAC;QAEtB,MAAM,eAAe,GAAG,MAAM,CAAC,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC;QAC/D,MAAM,cAAc,GAAG,MAAM,CAAC,IAAI,CAAC,iBAAiB,EAAE,WAAW,CAAC,CAAC;QAEnE,IAAI,eAAe,CAAC,MAAM,KAAK,cAAc,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC;QAClE,IAAI,CAAC,eAAe,CAAC,eAAe,EAAE,cAAc,CAAC;YAAE,OAAO,IAAI,CAAC;QAEnE,iBAAiB;QACjB,IAAI,CAAC;YACJ,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;YACnF,OAAO,OAAO,CAAC;QAChB,CAAC;QAAC,MAAM,CAAC;YACR,OAAO,IAAI,CAAC;QACb,CAAC;IACF,CAAC;CACD;AA6BD,MAAM,OAAO,kBAAkB;IACrB,IAAI,GAAG,SAAS,CAAC;IAClB,MAAM,CAA2B;IAEzC,YAAY,MAAgC;QAC3C,IAAI,CAAC,MAAM,GAAG;YACb,UAAU,EAAE,WAAW;YACvB,UAAU,EAAE,SAAS;YACrB,GAAG,MAAM;SACT,CAAC;IACH,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,OAAoB;QACtC,mBAAmB;QACnB,IAAI,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,IAAI,WAAW,CAAC,CAAC;QACpE,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;YAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QAE9C,uBAAuB;QACvB,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YAC9B,IAAI,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,IAAI,SAAS,CAAC,CAAC;YAClE,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC;gBAAE,QAAQ,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;YACpD,MAAM,GAAG,QAAQ,CAAC;QACnB,CAAC;QAED,IAAI,CAAC,MAAM,EAAE,CAAC;YACb,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,qBAAqB,EAAE,CAAC;QAC/D,CAAC;QAED,6BAA6B;QAC7B,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YAC1B,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YAChD,IAAI,IAAI,EAAE,CAAC;gBACV,OAAO,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;YACvC,CAAC;YACD,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC;QAC5E,CAAC;QAED,oBAAoB;QACpB,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC1C,IAAI,CAAC,IAAI,EAAE,CAAC;YACX,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC;QAC5E,CAAC;QAED,OAAO,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACvC,CAAC;IAEO,WAAW,CAAC,GAAW,EAAE,IAAgB;QAChD,eAAe;QACf,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;YACtE,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC;QAC5E,CAAC;QAED,OAAO;YACN,aAAa,EAAE,IAAI;YACnB,QAAQ,EAAE;gBACT,GAAG,EAAE,IAAI,CAAC,IAAI;gBACd,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,MAAM,EAAE,IAAI,CAAC,QAAQ,IAAI,EAAE;gBAC3B,QAAQ,EAAE,SAAS;gBACnB,SAAS,EAAE,IAAI,CAAC,SAAS;aACzB;SACD,CAAC;IACH,CAAC;CACD"}

package/dist/security/EncryptionAtRest.d.ts

@@ -0,0 +1,206 @@
+/**
+ * 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");
+ * ```
+ */
+/**
+ * Encrypted payload containing all data needed for decryption.
+ *
+ * This is a self-describing structure: it includes the algorithm and
+ * initialization vector so that the correct decryption parameters can be
+ * reconstructed without external metadata.
+ */
+export interface EncryptedPayload {
+    /** Base64- or hex-encoded initialization vector */
+    iv: string;
+    /** Base64- or hex-encoded ciphertext */
+    ciphertext: string;
+    /** Base64- or hex-encoded GCM authentication tag */
+    tag: string;
+    /** Algorithm used for encryption (e.g. "aes-256-gcm") */
+    algorithm: string;
+    /** Optional identifier for the key that was used */
+    keyId?: string;
+}
+/**
+ * PBKDF2 key derivation settings.
+ */
+export interface KeyDerivationConfig {
+    /** Number of PBKDF2 iterations (recommended >= 100 000) */
+    iterations: number;
+    /** Length of the random salt in bytes (default 16) */
+    saltLength: number;
+    /** Hash digest algorithm (default "sha512") */
+    digest: string;
+}
+/**
+ * Configuration for the {@link EncryptionAtRest} class.
+ */
+export interface EncryptionConfig {
+    /**
+     * Cipher algorithm to use.
+     * @default "aes-256-gcm"
+     */
+    algorithm?: string;
+    /**
+     * PBKDF2 key derivation settings.
+     * @default { iterations: 100_000, saltLength: 16, digest: "sha512" }
+     */
+    keyDerivation?: Partial<KeyDerivationConfig>;
+    /**
+     * Output encoding for binary values in {@link EncryptedPayload}.
+     * @default "base64"
+     */
+    encoding?: BufferEncoding;
+}
+/**
+ * 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 declare class EncryptionAtRest {
+    private readonly algorithm;
+    private readonly keyDerivation;
+    private readonly encoding;
+    /**
+     * Create a new EncryptionAtRest instance.
+     *
+     * @param config - Optional configuration overrides
+     */
+    constructor(config?: EncryptionConfig);
+    /**
+     * 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: string, key: string): EncryptedPayload;
+    /**
+     * 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: EncryptedPayload, key: string): string;
+    /**
+     * 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<T>(obj: T, key: string): string;
+    /**
+     * 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<T>(ciphertext: string, key: string): T;
+    /**
+     * 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: string, oldKey: string, newKey: string): string;
+    /**
+     * 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
+     */
+    private deriveKey;
+}