@fabrika/jwks 0.8.1 → 0.9.0-dev.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/jwks",
-	"version": "0.8.1",
+	"version": "0.9.0-dev.2",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -12,12 +12,13 @@
 	},
 	"files": [
 		"src",
-		"!src/**/__tests__/**"
+		"!src/**/__tests__/**",
+		"types"
 	],
 	"exports": {
 		".": {
 			"bun": "./src/index.ts",
-			"types": "./src/index.ts",
+			"types": "./types/src/index.d.ts",
 			"default": "./src/index.ts"
 		}
 	},
@@ -27,7 +28,7 @@
 	},
 	"dependencies": {
 		"zod": "^3.25.76",
-		"@fabrika/auth-core": "0.8.1",
+		"@fabrika/auth-core": "0.9.0-dev.2",
 		"jose": "^5.9.0"
 	}
 }

package/types/src/index.d.ts

@@ -0,0 +1,3 @@
+export { parseJwks } from './parse';
+export { createJwksCache, JWKS_REFETCH_COOLDOWN_SECONDS, JWKS_TTL_SECONDS, TokenVerifier } from './verifier';
+export type { JwksCache, TokenVerifierOptions, VerifyResult } from './verifier';

package/types/src/parse.d.ts

@@ -0,0 +1,3 @@
+import type { Jwks } from '@fabrika/auth-core';
+/** Reject the whole set when a member cannot be represented; dropping one would misreport an outage as an invalid token. */
+export declare function parseJwks(body: unknown): Jwks | null;

package/types/src/verifier.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The ONE JWKS-backed access-token verifier: fetch IAM's key set, cache it, verify every token
+ * locally with no network call on the warm path.
+ *
+ * `verify` is THREE-STATE, and the distinction is load-bearing: "this token is bad" is the caller's
+ * fault (401) and "we could not check" is ours (503). Both deny; only the second is an incident.
+ * Collapsing them would let a JWKS outage read as a forged token.
+ */
+import { type AccessTokenClaims, type Jwks, type TokenAudienceProfile } from '@fabrika/auth-core';
+import { createLocalJWKSet } from 'jose';
+export type VerifyResult = {
+    ok: true;
+    claims: AccessTokenClaims;
+}
+/** Signature, issuer, audience, expiry or claim-shape failure — the token is not trustworthy. */
+ | {
+    ok: false;
+    reason: 'invalid';
+}
+/** The key set could not be obtained, so nothing could be checked. Deny, but say why. */
+ | {
+    ok: false;
+    reason: 'unavailable';
+};
+/** How long a fetched JWKS is reused before a refetch (a kid rotation also forces one on demand). */
+export declare const JWKS_TTL_SECONDS = 600;
+/**
+ * Minimum gap between two unknown-`kid` refetches. Bounds how often a token nobody can verify may
+ * cost an IAM round trip — the token is denied either way, and a real rotation is picked up within it.
+ */
+export declare const JWKS_REFETCH_COOLDOWN_SECONDS = 30;
+/** jose's local key-set resolver — what `jwtVerify` is handed once the JWKS is in hand. */
+type LocalJwks = ReturnType<typeof createLocalJWKSet>;
+/**
+ * The mutable state verification carries between calls: the cached key set and when an unknown `kid`
+ * last forced a refetch. Injectable because the app SDK keys it by the IAM BINDING — `@fabrika/app`
+ * builds a new SDK object per request, so per-instance state would refetch, and reset the cooldown,
+ * on every request.
+ */
+export interface JwksCache {
+    entry: {
+        keys: LocalJwks;
+        expiresAt: number;
+    } | null;
+    lastForcedAt: number | null;
+}
+export declare function createJwksCache(): JwksCache;
+export interface TokenVerifierOptions {
+    getJwks: () => Promise<Jwks>;
+    /** Byte-exact: it is the token's `iss` and jose compares it verbatim. */
+    issuer: string;
+    /** Unix seconds; injectable for tests. Defaults to the wall clock. */
+    now?: () => number;
+    ttlSeconds?: number;
+    refetchCooldownSeconds?: number;
+    /** Where the key set and the cooldown live. Defaults to state private to this verifier. */
+    cache?: JwksCache;
+}
+export declare class TokenVerifier {
+    private readonly getJwks;
+    private readonly issuer;
+    private readonly now;
+    private readonly ttlSeconds;
+    private readonly refetchCooldownSeconds;
+    private readonly cache;
+    constructor(options: TokenVerifierOptions);
+    /**
+     * Verify `token` for `audience` and narrow it to access claims. A bare string is an app id
+     * (`{ kind: 'app', app }`). An unknown `kid` forces one JWKS refetch (a key rotated in), then a
+     * retry — but at most once per cooldown, because otherwise any caller can turn every request into
+     * an IAM round trip just by inventing a `kid`.
+     */
+    verify(token: string, audience: string | TokenAudienceProfile): Promise<VerifyResult>;
+    /**
+     * May an unknown `kid` force a refetch right now? A rotation is rare and the token is denied either
+     * way, so rate-limiting this costs a few seconds of rotation lag and removes an amplification
+     * primitive: without it, N requests with N invented kids are N IAM fetches.
+     */
+    private mayForceRefetch;
+    /** Returns the payload, `null` on a genuine verification failure, or `NO_KEY` on a kid miss. */
+    private verifyWith;
+    private keySet;
+}
+export {};