@peac/jwks-cache 0.9.18

package/README.md

@@ -0,0 +1,23 @@
+# @peac/jwks-cache
+
+Edge-safe JWKS fetch and cache with SSRF protection
+
+## Installation
+
+```bash
+pnpm add @peac/jwks-cache
+```
+
+## Documentation
+
+See [peacprotocol.org](https://peacprotocol.org) for full documentation.
+
+## License
+
+Apache-2.0
+
+---
+
+PEAC Protocol is an open source project stewarded by Originary and community contributors.
+
+[Originary](https://www.originary.xyz) | [Docs](https://peacprotocol.org) | [GitHub](https://github.com/peacprotocol/peac)

package/dist/cache.d.ts

@@ -0,0 +1,37 @@
+/**
+ * In-memory cache implementation.
+ */
+import type { CacheBackend, CacheEntry } from './types.js';
+/**
+ * Simple in-memory cache with TTL support.
+ */
+export declare class InMemoryCache implements CacheBackend {
+    private readonly cache;
+    get(key: string): Promise<CacheEntry | null>;
+    set(key: string, value: CacheEntry): Promise<void>;
+    delete(key: string): Promise<void>;
+    /**
+     * Clear all entries.
+     */
+    clear(): void;
+    /**
+     * Get current cache size.
+     */
+    get size(): number;
+}
+/**
+ * Build cache key for a specific key ID.
+ */
+export declare function buildCacheKey(issuerOrigin: string, kid: string): string;
+/**
+ * Build cache key for JWKS set.
+ */
+export declare function buildJwksCacheKey(issuerOrigin: string): string;
+/**
+ * Parse Cache-Control header for max-age.
+ *
+ * @param cacheControl - Cache-Control header value
+ * @returns max-age in seconds or null if not found
+ */
+export declare function parseCacheControlMaxAge(cacheControl: string | null): number | null;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE3D;;GAEG;AACH,qBAAa,aAAc,YAAW,YAAY;IAChD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;IAEjD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAiB5C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxC;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAWlF"}

package/dist/cache.js

@@ -0,0 +1,69 @@
+/**
+ * In-memory cache implementation.
+ */
+/**
+ * Simple in-memory cache with TTL support.
+ */
+export class InMemoryCache {
+    cache = new Map();
+    async get(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return null;
+        }
+        // Check expiration
+        const now = Math.floor(Date.now() / 1000);
+        if (now >= entry.expiresAt) {
+            this.cache.delete(key);
+            return null;
+        }
+        return entry;
+    }
+    async set(key, value) {
+        this.cache.set(key, value);
+    }
+    async delete(key) {
+        this.cache.delete(key);
+    }
+    /**
+     * Clear all entries.
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * Get current cache size.
+     */
+    get size() {
+        return this.cache.size;
+    }
+}
+/**
+ * Build cache key for a specific key ID.
+ */
+export function buildCacheKey(issuerOrigin, kid) {
+    return `${issuerOrigin}:${kid}`;
+}
+/**
+ * Build cache key for JWKS set.
+ */
+export function buildJwksCacheKey(issuerOrigin) {
+    return `${issuerOrigin}:__jwks__`;
+}
+/**
+ * Parse Cache-Control header for max-age.
+ *
+ * @param cacheControl - Cache-Control header value
+ * @returns max-age in seconds or null if not found
+ */
+export function parseCacheControlMaxAge(cacheControl) {
+    if (!cacheControl) {
+        return null;
+    }
+    const match = cacheControl.match(/max-age=(\d+)/);
+    if (!match) {
+        return null;
+    }
+    return parseInt(match[1], 10);
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;GAEG;AACH,MAAM,OAAO,aAAa;IACP,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;IAEvD,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAElC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,IAAI,CAAC;QACd,CAAC;QAED,mBAAmB;QACnB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;QAC1C,IAAI,GAAG,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;YAC3B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,KAAiB;QACtC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,YAAoB,EAAE,GAAW;IAC7D,OAAO,GAAG,YAAY,IAAI,GAAG,EAAE,CAAC;AAClC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,YAAoB;IACpD,OAAO,GAAG,YAAY,WAAW,CAAC;AACpC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,YAA2B;IACjE,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;IAClD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAChC,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,35 @@
+/**
+ * JWKS Cache error codes per execution pack specification.
+ */
+export declare const ErrorCodes: {
+    /** Network error fetching JWKS */
+    readonly JWKS_FETCH_FAILED: "E_JWKS_FETCH_FAILED";
+    /** Fetch timeout */
+    readonly JWKS_TIMEOUT: "E_JWKS_TIMEOUT";
+    /** Invalid JSON or structure */
+    readonly JWKS_INVALID: "E_JWKS_INVALID";
+    /** Response > 1MB */
+    readonly JWKS_TOO_LARGE: "E_JWKS_TOO_LARGE";
+    /** keys.length > 100 */
+    readonly JWKS_TOO_MANY_KEYS: "E_JWKS_TOO_MANY_KEYS";
+    /** Private IP or metadata URL blocked */
+    readonly SSRF_BLOCKED: "E_SSRF_BLOCKED";
+    /** Requested kid not in JWKS */
+    readonly KEY_NOT_FOUND: "E_KEY_NOT_FOUND";
+    /** All discovery paths failed */
+    readonly ALL_PATHS_FAILED: "E_ALL_PATHS_FAILED";
+};
+export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+/**
+ * HTTP status codes for each error.
+ */
+export declare const ErrorHttpStatus: Record<ErrorCode, number>;
+/**
+ * JWKS error with code and HTTP status.
+ */
+export declare class JwksError extends Error {
+    readonly code: ErrorCode;
+    readonly httpStatus: number;
+    constructor(code: ErrorCode, message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,UAAU;IACrB,kCAAkC;;IAElC,oBAAoB;;IAEpB,gCAAgC;;IAEhC,qBAAqB;;IAErB,wBAAwB;;IAExB,yCAAyC;;IAEzC,gCAAgC;;IAEhC,iCAAiC;;CAEzB,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,OAAO,UAAU,CAAC,CAAC;AAErE;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CASrD,CAAC;AAEF;;GAEG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM;CAM7C"}

package/dist/errors.js

@@ -0,0 +1,48 @@
+/**
+ * JWKS Cache error codes per execution pack specification.
+ */
+export const ErrorCodes = {
+    /** Network error fetching JWKS */
+    JWKS_FETCH_FAILED: 'E_JWKS_FETCH_FAILED',
+    /** Fetch timeout */
+    JWKS_TIMEOUT: 'E_JWKS_TIMEOUT',
+    /** Invalid JSON or structure */
+    JWKS_INVALID: 'E_JWKS_INVALID',
+    /** Response > 1MB */
+    JWKS_TOO_LARGE: 'E_JWKS_TOO_LARGE',
+    /** keys.length > 100 */
+    JWKS_TOO_MANY_KEYS: 'E_JWKS_TOO_MANY_KEYS',
+    /** Private IP or metadata URL blocked */
+    SSRF_BLOCKED: 'E_SSRF_BLOCKED',
+    /** Requested kid not in JWKS */
+    KEY_NOT_FOUND: 'E_KEY_NOT_FOUND',
+    /** All discovery paths failed */
+    ALL_PATHS_FAILED: 'E_ALL_PATHS_FAILED',
+};
+/**
+ * HTTP status codes for each error.
+ */
+export const ErrorHttpStatus = {
+    [ErrorCodes.JWKS_FETCH_FAILED]: 502,
+    [ErrorCodes.JWKS_TIMEOUT]: 504,
+    [ErrorCodes.JWKS_INVALID]: 502,
+    [ErrorCodes.JWKS_TOO_LARGE]: 502,
+    [ErrorCodes.JWKS_TOO_MANY_KEYS]: 502,
+    [ErrorCodes.SSRF_BLOCKED]: 403,
+    [ErrorCodes.KEY_NOT_FOUND]: 401,
+    [ErrorCodes.ALL_PATHS_FAILED]: 502,
+};
+/**
+ * JWKS error with code and HTTP status.
+ */
+export class JwksError extends Error {
+    code;
+    httpStatus;
+    constructor(code, message) {
+        super(message);
+        this.name = 'JwksError';
+        this.code = code;
+        this.httpStatus = ErrorHttpStatus[code];
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,kCAAkC;IAClC,iBAAiB,EAAE,qBAAqB;IACxC,oBAAoB;IACpB,YAAY,EAAE,gBAAgB;IAC9B,gCAAgC;IAChC,YAAY,EAAE,gBAAgB;IAC9B,qBAAqB;IACrB,cAAc,EAAE,kBAAkB;IAClC,wBAAwB;IACxB,kBAAkB,EAAE,sBAAsB;IAC1C,yCAAyC;IACzC,YAAY,EAAE,gBAAgB;IAC9B,gCAAgC;IAChC,aAAa,EAAE,iBAAiB;IAChC,iCAAiC;IACjC,gBAAgB,EAAE,oBAAoB;CAC9B,CAAC;AAIX;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAA8B;IACxD,CAAC,UAAU,CAAC,iBAAiB,CAAC,EAAE,GAAG;IACnC,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,GAAG;IAC9B,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,GAAG;IAC9B,CAAC,UAAU,CAAC,cAAc,CAAC,EAAE,GAAG;IAChC,CAAC,UAAU,CAAC,kBAAkB,CAAC,EAAE,GAAG;IACpC,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,GAAG;IAC9B,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,GAAG;IAC/B,CAAC,UAAU,CAAC,gBAAgB,CAAC,EAAE,GAAG;CACnC,CAAC;AAEF;;GAEG;AACH,MAAM,OAAO,SAAU,SAAQ,KAAK;IACzB,IAAI,CAAY;IAChB,UAAU,CAAS;IAE5B,YAAY,IAAe,EAAE,OAAe;QAC1C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,UAAU,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IAC1C,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @peac/jwks-cache
+ *
+ * Edge-safe JWKS fetch and cache with SSRF protection.
+ */
+export type { JWK, JWKS, CacheBackend, CacheEntry, ResolverOptions, ResolvedKey, JwksKeyResolver, } from './types.js';
+export { InMemoryCache, buildCacheKey, buildJwksCacheKey, parseCacheControlMaxAge, } from './cache.js';
+export { validateUrl, isMetadataIp } from './security.js';
+export { createResolver, resolveKey, importJwkAsEd25519, createJwkVerifier } from './resolver.js';
+export { ErrorCodes, ErrorHttpStatus, JwksError } from './errors.js';
+export type { ErrorCode } from './errors.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,YAAY,EACV,GAAG,EACH,IAAI,EACJ,YAAY,EACZ,UAAU,EACV,eAAe,EACf,WAAW,EACX,eAAe,GAChB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAG1D,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAGlG,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACrE,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * @peac/jwks-cache
+ *
+ * Edge-safe JWKS fetch and cache with SSRF protection.
+ */
+// Cache
+export { InMemoryCache, buildCacheKey, buildJwksCacheKey, parseCacheControlMaxAge, } from './cache.js';
+// Security
+export { validateUrl, isMetadataIp } from './security.js';
+// Resolver
+export { createResolver, resolveKey, importJwkAsEd25519, createJwkVerifier } from './resolver.js';
+// Errors
+export { ErrorCodes, ErrorHttpStatus, JwksError } from './errors.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAaH,QAAQ;AACR,OAAO,EACL,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,YAAY,CAAC;AAEpB,WAAW;AACX,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE1D,WAAW;AACX,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAElG,SAAS;AACT,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/dist/resolver.d.ts

@@ -0,0 +1,38 @@
+/**
+ * JWKS resolver with multi-path discovery and caching.
+ */
+import type { SignatureVerifier } from '@peac/http-signatures';
+import type { JWK, ResolverOptions, ResolvedKey, JwksKeyResolver } from './types.js';
+/**
+ * Create a JWKS key resolver.
+ *
+ * @param options - Resolver options
+ * @returns Key resolver function
+ */
+export declare function createResolver(options?: ResolverOptions): JwksKeyResolver;
+/**
+ * Resolve a key by issuer and key ID.
+ *
+ * Discovery order (per TAP spec):
+ * 1. /.well-known/jwks
+ * 2. /keys?keyID=<kid>
+ * 3. /.well-known/jwks.json (fallback)
+ */
+export declare function resolveKey(issuer: string, keyid: string, options: Required<Pick<ResolverOptions, 'cache' | 'defaultTtlSeconds' | 'maxTtlSeconds' | 'minTtlSeconds' | 'timeoutMs' | 'maxResponseBytes' | 'maxKeys' | 'allowLocalhost'>> & Pick<ResolverOptions, 'isAllowedHost'>): Promise<ResolvedKey | null>;
+/**
+ * Import a JWK as Ed25519 public key.
+ *
+ * Returns an opaque key object (runtime-neutral).
+ * Use createJwkVerifier() for a complete SignatureVerifier.
+ */
+export declare function importJwkAsEd25519(jwk: JWK): Promise<unknown>;
+/**
+ * Create a SignatureVerifier from a JWK.
+ *
+ * Convenience function for TAP integration.
+ *
+ * @param jwk - Ed25519 JWK
+ * @returns SignatureVerifier function
+ */
+export declare function createJwkVerifier(jwk: JWK): Promise<SignatureVerifier>;
+//# sourceMappingURL=resolver.d.ts.map

package/dist/resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../src/resolver.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,KAAK,EACV,GAAG,EAGH,eAAe,EACf,WAAW,EACX,eAAe,EAChB,MAAM,YAAY,CAAC;AAYpB;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE,eAAoB,GAAG,eAAe,CAgC7E;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,QAAQ,CACf,IAAI,CACF,eAAe,EACb,OAAO,GACP,mBAAmB,GACnB,eAAe,GACf,eAAe,GACf,WAAW,GACX,kBAAkB,GAClB,SAAS,GACT,gBAAgB,CACnB,CACF,GACC,IAAI,CAAC,eAAe,EAAE,eAAe,CAAC,GACvC,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAgI7B;AAkHD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,CAYnE;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAa5E"}

package/dist/resolver.js

@@ -0,0 +1,266 @@
+/**
+ * JWKS resolver with multi-path discovery and caching.
+ */
+import { ErrorCodes, JwksError } from './errors.js';
+import { validateUrl } from './security.js';
+import { InMemoryCache, buildCacheKey, parseCacheControlMaxAge } from './cache.js';
+const DEFAULT_TTL_SECONDS = 3600; // 1 hour
+const MAX_TTL_SECONDS = 86400; // 24 hours
+const MIN_TTL_SECONDS = 60;
+const DEFAULT_TIMEOUT_MS = 5000;
+const DEFAULT_MAX_RESPONSE_BYTES = 1024 * 1024; // 1MB
+const DEFAULT_MAX_KEYS = 100;
+/**
+ * Create a JWKS key resolver.
+ *
+ * @param options - Resolver options
+ * @returns Key resolver function
+ */
+export function createResolver(options = {}) {
+    const cache = options.cache ?? new InMemoryCache();
+    const { defaultTtlSeconds = DEFAULT_TTL_SECONDS, maxTtlSeconds = MAX_TTL_SECONDS, minTtlSeconds = MIN_TTL_SECONDS, timeoutMs = DEFAULT_TIMEOUT_MS, maxResponseBytes = DEFAULT_MAX_RESPONSE_BYTES, maxKeys = DEFAULT_MAX_KEYS, isAllowedHost, allowLocalhost = false, } = options;
+    return async (issuer, keyid) => {
+        const resolvedKey = await resolveKey(issuer, keyid, {
+            cache,
+            defaultTtlSeconds,
+            maxTtlSeconds,
+            minTtlSeconds,
+            timeoutMs,
+            maxResponseBytes,
+            maxKeys,
+            isAllowedHost,
+            allowLocalhost,
+        });
+        if (!resolvedKey) {
+            return null;
+        }
+        return createJwkVerifier(resolvedKey.jwk);
+    };
+}
+/**
+ * Resolve a key by issuer and key ID.
+ *
+ * Discovery order (per TAP spec):
+ * 1. /.well-known/jwks
+ * 2. /keys?keyID=<kid>
+ * 3. /.well-known/jwks.json (fallback)
+ */
+export async function resolveKey(issuer, keyid, options) {
+    const { cache, isAllowedHost, allowLocalhost } = options;
+    // Normalize issuer to origin
+    const issuerOrigin = new URL(issuer).origin;
+    const cacheKey = buildCacheKey(issuerOrigin, keyid);
+    // Check cache first
+    const cached = await cache.get(cacheKey);
+    if (cached) {
+        return {
+            jwk: cached.jwk,
+            source: '/.well-known/jwks',
+            cached: true,
+        };
+    }
+    // Discovery paths in order
+    const paths = [
+        {
+            url: `${issuerOrigin}/.well-known/jwks`,
+            source: '/.well-known/jwks',
+            isSingleKey: false,
+        },
+        {
+            url: `${issuerOrigin}/keys?keyID=${encodeURIComponent(keyid)}`,
+            source: '/keys',
+            isSingleKey: true,
+        },
+        {
+            url: `${issuerOrigin}/.well-known/jwks.json`,
+            source: '/.well-known/jwks.json',
+            isSingleKey: false,
+        },
+    ];
+    const errors = [];
+    for (const path of paths) {
+        try {
+            // Validate URL for SSRF
+            validateUrl(path.url, { isAllowedHost, allowLocalhost });
+            const result = await fetchWithTimeout(path.url, options.timeoutMs);
+            // Check response size
+            const contentLength = result.headers.get('content-length');
+            if (contentLength && parseInt(contentLength, 10) > options.maxResponseBytes) {
+                throw new JwksError(ErrorCodes.JWKS_TOO_LARGE, `Response too large: ${contentLength} bytes`);
+            }
+            // Parse response
+            const text = await result.text();
+            if (text.length > options.maxResponseBytes) {
+                throw new JwksError(ErrorCodes.JWKS_TOO_LARGE, `Response too large: ${text.length} bytes`);
+            }
+            let data;
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                throw new JwksError(ErrorCodes.JWKS_INVALID, 'Invalid JSON response');
+            }
+            // Extract JWK
+            let jwk = null;
+            if (path.isSingleKey) {
+                // Single key endpoint returns JWK directly
+                jwk = validateJwk(data);
+            }
+            else {
+                // JWKS endpoint returns key set
+                const jwks = validateJwks(data, options.maxKeys);
+                jwk = findKey(jwks, keyid);
+            }
+            if (!jwk) {
+                continue; // Try next path
+            }
+            // Calculate TTL
+            const cacheControlMaxAge = parseCacheControlMaxAge(result.headers.get('cache-control'));
+            const ttl = calculateTtl(cacheControlMaxAge, options.defaultTtlSeconds, options.minTtlSeconds, options.maxTtlSeconds);
+            // Cache the key
+            const now = Math.floor(Date.now() / 1000);
+            await cache.set(cacheKey, {
+                jwk,
+                expiresAt: now + ttl,
+                etag: result.headers.get('etag') ?? undefined,
+            });
+            return {
+                jwk,
+                source: path.source,
+                cached: false,
+            };
+        }
+        catch (error) {
+            errors.push(error);
+            // Continue to next path
+        }
+    }
+    // All paths failed
+    if (errors.length > 0) {
+        const lastError = errors[errors.length - 1];
+        if (lastError instanceof JwksError) {
+            throw lastError;
+        }
+        throw new JwksError(ErrorCodes.ALL_PATHS_FAILED, `All discovery paths failed for ${issuerOrigin}`);
+    }
+    return null;
+}
+/**
+ * Fetch with timeout.
+ */
+async function fetchWithTimeout(url, timeoutMs) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, {
+            signal: controller.signal,
+            redirect: 'error', // No redirect following (fail-closed)
+            headers: {
+                Accept: 'application/json',
+            },
+        });
+        if (!response.ok) {
+            throw new JwksError(ErrorCodes.JWKS_FETCH_FAILED, `HTTP ${response.status}: ${response.statusText}`);
+        }
+        return response;
+    }
+    catch (error) {
+        if (error.name === 'AbortError') {
+            throw new JwksError(ErrorCodes.JWKS_TIMEOUT, `Fetch timeout after ${timeoutMs}ms`);
+        }
+        if (error instanceof JwksError) {
+            throw error;
+        }
+        throw new JwksError(ErrorCodes.JWKS_FETCH_FAILED, `Fetch failed: ${error.message}`);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/**
+ * Validate and extract JWK from response data.
+ */
+function validateJwk(data) {
+    if (!data || typeof data !== 'object') {
+        return null;
+    }
+    const jwk = data;
+    if (jwk.kty !== 'OKP' || jwk.crv !== 'Ed25519' || typeof jwk.x !== 'string') {
+        return null;
+    }
+    return {
+        kty: jwk.kty,
+        crv: jwk.crv,
+        x: jwk.x,
+        kid: typeof jwk.kid === 'string' ? jwk.kid : undefined,
+        use: typeof jwk.use === 'string' ? jwk.use : undefined,
+        alg: typeof jwk.alg === 'string' ? jwk.alg : undefined,
+    };
+}
+/**
+ * Validate JWKS structure.
+ */
+function validateJwks(data, maxKeys) {
+    if (!data || typeof data !== 'object') {
+        throw new JwksError(ErrorCodes.JWKS_INVALID, 'Invalid JWKS structure');
+    }
+    const jwks = data;
+    if (!Array.isArray(jwks.keys)) {
+        throw new JwksError(ErrorCodes.JWKS_INVALID, 'JWKS must have keys array');
+    }
+    if (jwks.keys.length > maxKeys) {
+        throw new JwksError(ErrorCodes.JWKS_TOO_MANY_KEYS, `Too many keys: ${jwks.keys.length} > ${maxKeys}`);
+    }
+    return { keys: jwks.keys };
+}
+/**
+ * Find key by ID in JWKS.
+ */
+function findKey(jwks, keyid) {
+    for (const key of jwks.keys) {
+        if (key.kid === keyid) {
+            return validateJwk(key);
+        }
+    }
+    return null;
+}
+/**
+ * Calculate TTL from Cache-Control and options.
+ */
+function calculateTtl(cacheControlMaxAge, defaultTtl, minTtl, maxTtl) {
+    let ttl = cacheControlMaxAge ?? defaultTtl;
+    ttl = Math.max(minTtl, ttl);
+    ttl = Math.min(maxTtl, ttl);
+    return ttl;
+}
+/**
+ * Import a JWK as Ed25519 public key.
+ *
+ * Returns an opaque key object (runtime-neutral).
+ * Use createJwkVerifier() for a complete SignatureVerifier.
+ */
+export async function importJwkAsEd25519(jwk) {
+    return globalThis.crypto.subtle.importKey('jwk', {
+        kty: jwk.kty,
+        crv: jwk.crv,
+        x: jwk.x,
+    }, { name: 'Ed25519' }, false, ['verify']);
+}
+/**
+ * Create a SignatureVerifier from a JWK.
+ *
+ * Convenience function for TAP integration.
+ *
+ * @param jwk - Ed25519 JWK
+ * @returns SignatureVerifier function
+ */
+export async function createJwkVerifier(jwk) {
+    const key = await importJwkAsEd25519(jwk);
+    return async (data, signature) => {
+        // Create proper ArrayBuffer views to satisfy TypeScript
+        const sigBuffer = new Uint8Array(signature).buffer;
+        const dataBuffer = new Uint8Array(data).buffer;
+        return globalThis.crypto.subtle.verify('Ed25519', key, sigBuffer, dataBuffer);
+    };
+}
+//# sourceMappingURL=resolver.js.map

package/dist/resolver.js.map

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

package/dist/security.d.ts

@@ -0,0 +1,22 @@
+/**
+ * SSRF protection for JWKS fetching.
+ *
+ * Edge runtimes cannot reliably block private IPs via DNS resolution.
+ * This module implements what IS possible at the edge.
+ */
+/**
+ * Validate URL for SSRF protection.
+ *
+ * @param url - URL to validate
+ * @param options - Validation options
+ * @throws JwksError if URL is blocked
+ */
+export declare function validateUrl(url: string, options?: {
+    allowLocalhost?: boolean;
+    isAllowedHost?: (host: string) => boolean;
+}): void;
+/**
+ * Check if hostname is a metadata IP.
+ */
+export declare function isMetadataIp(hostname: string): boolean;
+//# sourceMappingURL=security.d.ts.map

package/dist/security.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../src/security.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,MAAM,EACX,OAAO,GAAE;IACP,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CACtC,GACL,IAAI,CAmCN;AAsCD;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAYtD"}

package/dist/security.js

@@ -0,0 +1,88 @@
+/**
+ * SSRF protection for JWKS fetching.
+ *
+ * Edge runtimes cannot reliably block private IPs via DNS resolution.
+ * This module implements what IS possible at the edge.
+ */
+import { ErrorCodes, JwksError } from './errors.js';
+/**
+ * Validate URL for SSRF protection.
+ *
+ * @param url - URL to validate
+ * @param options - Validation options
+ * @throws JwksError if URL is blocked
+ */
+export function validateUrl(url, options = {}) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new JwksError(ErrorCodes.SSRF_BLOCKED, `Invalid URL: ${url}`);
+    }
+    // HTTPS required (except localhost in dev)
+    if (parsed.protocol !== 'https:') {
+        if (parsed.protocol === 'http:' && options.allowLocalhost && isLocalhostHost(parsed.hostname)) {
+            // Allow http://localhost in dev mode
+        }
+        else {
+            throw new JwksError(ErrorCodes.SSRF_BLOCKED, `HTTPS required, got ${parsed.protocol}`);
+        }
+    }
+    // Block localhost variants (unless explicitly allowed)
+    if (isLocalhostHost(parsed.hostname) && !options.allowLocalhost) {
+        throw new JwksError(ErrorCodes.SSRF_BLOCKED, `Localhost blocked: ${parsed.hostname}`);
+    }
+    // Block literal IP addresses in URL
+    if (isLiteralIp(parsed.hostname)) {
+        throw new JwksError(ErrorCodes.SSRF_BLOCKED, `Literal IP addresses blocked: ${parsed.hostname}`);
+    }
+    // Check enterprise allowlist if provided
+    if (options.isAllowedHost && !options.isAllowedHost(parsed.hostname)) {
+        throw new JwksError(ErrorCodes.SSRF_BLOCKED, `Host not in allowlist: ${parsed.hostname}`);
+    }
+}
+/**
+ * Check if hostname is localhost variant.
+ */
+function isLocalhostHost(hostname) {
+    const lower = hostname.toLowerCase();
+    return (lower === 'localhost' ||
+        lower === '127.0.0.1' ||
+        lower === '::1' ||
+        lower === '[::1]' ||
+        lower.endsWith('.localhost'));
+}
+/**
+ * Check if hostname is a literal IP address.
+ */
+function isLiteralIp(hostname) {
+    // IPv4 pattern
+    if (/^(\d{1,3}\.){3}\d{1,3}$/.test(hostname)) {
+        return true;
+    }
+    // IPv6 pattern (with or without brackets)
+    if (hostname.startsWith('[') && hostname.endsWith(']')) {
+        return true;
+    }
+    // Colon indicates IPv6 (no brackets)
+    if (hostname.includes(':')) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Check if hostname is a metadata IP.
+ */
+export function isMetadataIp(hostname) {
+    // AWS/GCP/Azure metadata service
+    if (hostname === '169.254.169.254') {
+        return true;
+    }
+    // Link-local range (169.254.x.x)
+    if (hostname.startsWith('169.254.')) {
+        return true;
+    }
+    return false;
+}
+//# sourceMappingURL=security.js.map

package/dist/security.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,100 @@
+/**
+ * @peac/jwks-cache - Edge-safe JWKS types
+ */
+import type { SignatureVerifier } from '@peac/http-signatures';
+/**
+ * JSON Web Key (JWK) structure for Ed25519 public keys.
+ */
+export interface JWK {
+    /** Key type - must be "OKP" for Ed25519 */
+    kty: string;
+    /** Curve - must be "Ed25519" */
+    crv: string;
+    /** Public key (base64url) */
+    x: string;
+    /** Key ID (optional) */
+    kid?: string;
+    /** Key use (optional, e.g., "sig") */
+    use?: string;
+    /** Algorithm (optional, e.g., "EdDSA") */
+    alg?: string;
+}
+/**
+ * JSON Web Key Set (JWKS) structure.
+ */
+export interface JWKS {
+    keys: JWK[];
+}
+/**
+ * Cache backend interface for pluggable storage.
+ */
+export interface CacheBackend {
+    /**
+     * Get cached value.
+     * @param key - Cache key
+     * @returns Cached value or null if not found/expired
+     */
+    get(key: string): Promise<CacheEntry | null>;
+    /**
+     * Set cached value with TTL.
+     * @param key - Cache key
+     * @param value - Value to cache
+     */
+    set(key: string, value: CacheEntry): Promise<void>;
+    /**
+     * Delete cached value.
+     * @param key - Cache key
+     */
+    delete(key: string): Promise<void>;
+}
+/**
+ * Cache entry with metadata.
+ */
+export interface CacheEntry {
+    /** Cached JWK */
+    jwk: JWK;
+    /** Cache expiration timestamp (Unix seconds) */
+    expiresAt: number;
+    /** ETag for conditional refresh (optional) */
+    etag?: string;
+}
+/**
+ * JWKS resolver options.
+ */
+export interface ResolverOptions {
+    /** Cache backend (defaults to in-memory) */
+    cache?: CacheBackend;
+    /** Default TTL in seconds (defaults to 3600) */
+    defaultTtlSeconds?: number;
+    /** Max TTL in seconds (defaults to 86400) */
+    maxTtlSeconds?: number;
+    /** Min TTL in seconds (defaults to 60) */
+    minTtlSeconds?: number;
+    /** Fetch timeout in ms (defaults to 5000) */
+    timeoutMs?: number;
+    /** Max response size in bytes (defaults to 1MB) */
+    maxResponseBytes?: number;
+    /** Max keys in JWKS (defaults to 100) */
+    maxKeys?: number;
+    /** Optional allowlist callback for enterprise deployments */
+    isAllowedHost?: (host: string) => boolean;
+    /** Allow localhost in dev mode (defaults to false) */
+    allowLocalhost?: boolean;
+}
+/**
+ * Resolved key result.
+ */
+export interface ResolvedKey {
+    /** The JWK */
+    jwk: JWK;
+    /** Which path resolved the key */
+    source: '/.well-known/jwks' | '/.well-known/jwks.json' | '/keys';
+    /** Whether result was from cache */
+    cached: boolean;
+}
+/**
+ * Key resolver function type for TAP integration.
+ * Returns a SignatureVerifier or null if key not found.
+ */
+export type JwksKeyResolver = (issuer: string, keyid: string) => Promise<SignatureVerifier | null>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE/D;;GAEG;AACH,MAAM,WAAW,GAAG;IAClB,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,6BAA6B;IAC7B,CAAC,EAAE,MAAM,CAAC;IACV,wBAAwB;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,IAAI;IACnB,IAAI,EAAE,GAAG,EAAE,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAE7C;;;;OAIG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnD;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,iBAAiB;IACjB,GAAG,EAAE,GAAG,CAAC;IACT,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,gDAAgD;IAChD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,6CAA6C;IAC7C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0CAA0C;IAC1C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IAC1C,sDAAsD;IACtD,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,cAAc;IACd,GAAG,EAAE,GAAG,CAAC;IACT,kCAAkC;IAClC,MAAM,EAAE,mBAAmB,GAAG,wBAAwB,GAAG,OAAO,CAAC;IACjE,oCAAoC;IACpC,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC"}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * @peac/jwks-cache - Edge-safe JWKS types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@peac/jwks-cache",
+  "version": "0.9.18",
+  "description": "Edge-safe JWKS fetch and cache with SSRF protection",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "jwks",
+    "cache",
+    "ed25519",
+    "ssrf",
+    "edge",
+    "peac"
+  ],
+  "author": "PEAC Protocol Contributors",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/peacprotocol/peac/issues"
+  },
+  "homepage": "https://peacprotocol.org",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/peacprotocol/peac.git",
+    "directory": "packages/jwks-cache"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@peac/http-signatures": "workspace:*"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "vitest": "^2.0.0"
+  }
+}