@homeflare/cloudflare 0.1.0 → 0.1.2

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/version.ts
-var VERSION = "0.1.0";
+var VERSION = "0.1.2";
 // src/access.ts
 import { createRemoteJWKSet, jwtVerify } from "jose";
 var ACCESS_HEADER = "cf-access-jwt-assertion";
@@ -52,5 +52,5 @@ export {
   verifyAccessJwt
 };
 
-//# debugId=75B5DF3D0BF305CF64756E2164756E21
+//# debugId=DEF7AC9FDEC3F4B864756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -2,11 +2,11 @@
   "version": 3,
   "sources": ["../src/version.ts", "../src/access.ts", "../src/log.ts"],
   "sourcesContent": [
-    "// ⛔ GENERATED by scripts/sync-versions.ts — do not edit. Source: package.json.\nexport const VERSION: string = '0.1.0';\n",
-    "/**\n * Cloudflare Access JWT verification.\n *\n * ★ WHY jose AND NOT A HAND-ROLLED VERIFY. Signature verification is the one place where\n *   a subtle bug is silent and total: a check that never fails looks identical to a\n *   check that always passes. jose handles JWKS fetching, `kid` matching and key\n *   rotation, and it is already in 8 estate packages. This file is the Access-specific\n *   wiring around it, nothing more.\n *\n * ⚠️ THE TRAP THIS CLOSES. Cloudflare's own example does `jwtVerify(...)` inline in the\n *   handler, which builds a NEW remote JWKS on every request — an outbound fetch per\n *   request, and a thundering herd on the certs endpoint under load. The cache below is\n *   keyed by team domain and lives for the isolate's lifetime.\n *\n * ⛔ NEVER SKIP `audience`. Any Access app in your account produces a JWT this team\n *   domain will happily verify; the AUD tag is the only thing that says the token was\n *   minted for THIS app. Verifying issuer alone accepts tokens from a neighbouring app.\n *\n * Docs: developers.cloudflare.com/cloudflare-one/identity/authorization-cookie/validating-json/\n */\nimport { createRemoteJWKSet, jwtVerify } from 'jose';\n\n/** The header Access puts the token in. Lowercase — Headers.get is case-insensitive. */\nconst ACCESS_HEADER = 'cf-access-jwt-assertion';\n\nexport interface AccessOptions {\n  /** `https://<team>.cloudflareaccess.com` — the issuer, and the JWKS host. */\n  readonly teamDomain: string;\n  /** The application's AUD tag, from Zero Trust → Access → Applications. */\n  readonly audience: string;\n}\n\n/** The subset of Access claims worth depending on. */\nexport interface AccessIdentity {\n  readonly email: string | undefined;\n  readonly sub: string | undefined;\n  /** Everything else, for callers that need a claim this interface does not name. */\n  readonly claims: Readonly<Record<string, unknown>>;\n}\n\n/**\n * One JWKS per team domain, reused for the isolate's life.\n * ⚠️ Module scope is per-isolate on workerd, not per-request and not global. That is\n *   exactly the right lifetime here: long enough to amortise the fetch, short enough\n *   that a rotated key is picked up when the isolate recycles. jose also refreshes on\n *   an unknown `kid`.\n */\nconst jwks = new Map<string, ReturnType<typeof createRemoteJWKSet>>();\n\nfunction keysFor(teamDomain: string): ReturnType<typeof createRemoteJWKSet> {\n  const existing = jwks.get(teamDomain);\n  if (existing !== undefined) return existing;\n\n  const created = createRemoteJWKSet(new URL(`${teamDomain}/cdn-cgi/access/certs`));\n  jwks.set(teamDomain, created);\n  return created;\n}\n\n/**\n * Verify the Access JWT on `request`, returning the identity it asserts.\n *\n * ⛔ THROWS ON EVERY FAILURE — missing header, bad signature, wrong audience, expired.\n *   ★ Deliberately not a boolean or a null: an `if (!ok)` that a caller forgets to write\n *     is an open door, whereas an unhandled throw is a 500 and a log line. Callers that\n *     want a soft path catch it explicitly.\n */\nexport async function verifyAccessJwt(\n  request: Request,\n  options: AccessOptions,\n): Promise<AccessIdentity> {\n  const token = request.headers.get(ACCESS_HEADER);\n  if (token === null) throw new Error('access: no Cf-Access-Jwt-Assertion header');\n\n  const { payload } = await jwtVerify(token, keysFor(options.teamDomain), {\n    issuer: options.teamDomain,\n    audience: options.audience,\n  });\n\n  return {\n    email: typeof payload['email'] === 'string' ? payload['email'] : undefined,\n    sub: payload.sub,\n    claims: payload,\n  };\n}\n",
+    "// ⛔ GENERATED by scripts/sync-versions.ts — do not edit. Source: package.json.\nexport const VERSION: string = '0.1.2';\n",
+    "/**\n * Cloudflare Access JWT verification.\n *\n * ★ WHY jose AND NOT A HAND-ROLLED VERIFY. Signature verification is the one place where\n *   a subtle bug is silent and total: a check that never fails looks identical to a\n *   check that always passes. jose handles JWKS fetching, `kid` matching and key\n *   rotation, and it is widely deployed. This file is the Access-specific\n *   wiring around it, nothing more.\n *\n * ⚠️ THE TRAP THIS CLOSES. Cloudflare's own example does `jwtVerify(...)` inline in the\n *   handler, which builds a NEW remote JWKS on every request — an outbound fetch per\n *   request, and a thundering herd on the certs endpoint under load. The cache below is\n *   keyed by team domain and lives for the isolate's lifetime.\n *\n * ⛔ NEVER SKIP `audience`. Any Access app in your account produces a JWT this team\n *   domain will happily verify; the AUD tag is the only thing that says the token was\n *   minted for THIS app. Verifying issuer alone accepts tokens from a neighbouring app.\n *\n * Docs: developers.cloudflare.com/cloudflare-one/identity/authorization-cookie/validating-json/\n */\nimport { createRemoteJWKSet, jwtVerify } from 'jose';\n\n/** The header Access puts the token in. Lowercase — Headers.get is case-insensitive. */\nconst ACCESS_HEADER = 'cf-access-jwt-assertion';\n\nexport interface AccessOptions {\n  /** `https://<team>.cloudflareaccess.com` — the issuer, and the JWKS host. */\n  readonly teamDomain: string;\n  /** The application's AUD tag, from Zero Trust → Access → Applications. */\n  readonly audience: string;\n}\n\n/** The subset of Access claims worth depending on. */\nexport interface AccessIdentity {\n  readonly email: string | undefined;\n  readonly sub: string | undefined;\n  /** Everything else, for callers that need a claim this interface does not name. */\n  readonly claims: Readonly<Record<string, unknown>>;\n}\n\n/**\n * One JWKS per team domain, reused for the isolate's life.\n * ⚠️ Module scope is per-isolate on workerd, not per-request and not global. That is\n *   exactly the right lifetime here: long enough to amortise the fetch, short enough\n *   that a rotated key is picked up when the isolate recycles. jose also refreshes on\n *   an unknown `kid`.\n */\nconst jwks = new Map<string, ReturnType<typeof createRemoteJWKSet>>();\n\nfunction keysFor(teamDomain: string): ReturnType<typeof createRemoteJWKSet> {\n  const existing = jwks.get(teamDomain);\n  if (existing !== undefined) return existing;\n\n  const created = createRemoteJWKSet(new URL(`${teamDomain}/cdn-cgi/access/certs`));\n  jwks.set(teamDomain, created);\n  return created;\n}\n\n/**\n * Verify the Access JWT on `request`, returning the identity it asserts.\n *\n * ⛔ THROWS ON EVERY FAILURE — missing header, bad signature, wrong audience, expired.\n *   ★ Deliberately not a boolean or a null: an `if (!ok)` that a caller forgets to write\n *     is an open door, whereas an unhandled throw is a 500 and a log line. Callers that\n *     want a soft path catch it explicitly.\n */\nexport async function verifyAccessJwt(\n  request: Request,\n  options: AccessOptions,\n): Promise<AccessIdentity> {\n  const token = request.headers.get(ACCESS_HEADER);\n  if (token === null) throw new Error('access: no Cf-Access-Jwt-Assertion header');\n\n  const { payload } = await jwtVerify(token, keysFor(options.teamDomain), {\n    issuer: options.teamDomain,\n    audience: options.audience,\n  });\n\n  return {\n    email: typeof payload['email'] === 'string' ? payload['email'] : undefined,\n    sub: payload.sub,\n    claims: payload,\n  };\n}\n",
     "/**\n * Structured logging for Workers.\n *\n * ★ WHY NO LOGGING LIBRARY. Cloudflare Workers Logs parses `console.log` output as JSON\n *   natively and indexes every field, with unlimited cardinality — so a JSON object on\n *   console IS the structured logging integration. pino is Node-shaped (streams, worker\n *   threads) and needs a wrapper on workerd; `pino-pretty` does not work with wrangler\n *   at all (workers-sdk#6841). Adding a dependency here would buy formatting we do not\n *   want and cost bundle size on a hot path.\n *   Docs: developers.cloudflare.com/workers/observability/logs/workers-logs/\n *\n * ⛔ NEVER LOG A CREDENTIAL. There is no redaction layer here and deliberately so — a\n *   redactor implies it is safe to pass secrets in, and then quietly misses one.\n */\n\n/** Anything JSON-serialisable. Workers Logs indexes each key as its own field. */\nexport type LogFields = Readonly<Record<string, unknown>>;\n\nexport interface Logger {\n  readonly debug: (message: string, fields?: LogFields) => void;\n  readonly info: (message: string, fields?: LogFields) => void;\n  readonly warn: (message: string, fields?: LogFields) => void;\n  readonly error: (message: string, fields?: LogFields) => void;\n  /** Returns a logger that merges `bound` into every subsequent line. */\n  readonly with: (bound: LogFields) => Logger;\n}\n\ntype Level = 'debug' | 'info' | 'warn' | 'error';\n\nfunction emit(level: Level, message: string, fields: LogFields): void {\n  // ⚠️ ONE OBJECT, NOT (message, fields). console.log with several arguments is\n  //   stringified and concatenated by the runtime, which destroys the structure Workers\n  //   Logs would otherwise index — the symptom is a `message` field containing your\n  //   whole payload as text, unqueryable.\n  const line = { level, message, ...fields };\n\n  if (level === 'error') console.error(line);\n  else if (level === 'warn') console.warn(line);\n  else console.log(line);\n}\n\nfunction make(bound: LogFields): Logger {\n  return {\n    debug: (message, fields) => emit('debug', message, { ...bound, ...fields }),\n    info: (message, fields) => emit('info', message, { ...bound, ...fields }),\n    warn: (message, fields) => emit('warn', message, { ...bound, ...fields }),\n    error: (message, fields) => emit('error', message, { ...bound, ...fields }),\n    with: (extra) => make({ ...bound, ...extra }),\n  };\n}\n\n/**\n * The root logger. Bind request-scoped context rather than passing it every call:\n *\n *     const requestLog = log.with({ requestId, path: url.pathname });\n *     requestLog.info('handled', { status, ms });\n */\nexport const log: Logger = make({});\n"
   ],
   "mappings": ";AACO,IAAM,UAAkB;;ACmB/B;AAGA,IAAM,gBAAgB;AAwBtB,IAAM,OAAO,IAAI;AAEjB,SAAS,OAAO,CAAC,YAA2D;AAAA,EAC1E,MAAM,WAAW,KAAK,IAAI,UAAU;AAAA,EACpC,IAAI,aAAa;AAAA,IAAW,OAAO;AAAA,EAEnC,MAAM,UAAU,mBAAmB,IAAI,IAAI,GAAG,iCAAiC,CAAC;AAAA,EAChF,KAAK,IAAI,YAAY,OAAO;AAAA,EAC5B,OAAO;AAAA;AAWT,eAAsB,eAAe,CACnC,SACA,SACyB;AAAA,EACzB,MAAM,QAAQ,QAAQ,QAAQ,IAAI,aAAa;AAAA,EAC/C,IAAI,UAAU;AAAA,IAAM,MAAM,IAAI,MAAM,2CAA2C;AAAA,EAE/E,QAAQ,YAAY,MAAM,UAAU,OAAO,QAAQ,QAAQ,UAAU,GAAG;AAAA,IACtE,QAAQ,QAAQ;AAAA,IAChB,UAAU,QAAQ;AAAA,EACpB,CAAC;AAAA,EAED,OAAO;AAAA,IACL,OAAO,OAAO,QAAQ,aAAa,WAAW,QAAQ,WAAW;AAAA,IACjE,KAAK,QAAQ;AAAA,IACb,QAAQ;AAAA,EACV;AAAA;;ACrDF,SAAS,IAAI,CAAC,OAAc,SAAiB,QAAyB;AAAA,EAKpE,MAAM,OAAO,EAAE,OAAO,YAAY,OAAO;AAAA,EAEzC,IAAI,UAAU;AAAA,IAAS,QAAQ,MAAM,IAAI;AAAA,EACpC,SAAI,UAAU;AAAA,IAAQ,QAAQ,KAAK,IAAI;AAAA,EACvC;AAAA,YAAQ,IAAI,IAAI;AAAA;AAGvB,SAAS,IAAI,CAAC,OAA0B;AAAA,EACtC,OAAO;AAAA,IACL,OAAO,CAAC,SAAS,WAAW,KAAK,SAAS,SAAS,KAAK,UAAU,OAAO,CAAC;AAAA,IAC1E,MAAM,CAAC,SAAS,WAAW,KAAK,QAAQ,SAAS,KAAK,UAAU,OAAO,CAAC;AAAA,IACxE,MAAM,CAAC,SAAS,WAAW,KAAK,QAAQ,SAAS,KAAK,UAAU,OAAO,CAAC;AAAA,IACxE,OAAO,CAAC,SAAS,WAAW,KAAK,SAAS,SAAS,KAAK,UAAU,OAAO,CAAC;AAAA,IAC1E,MAAM,CAAC,UAAU,KAAK,KAAK,UAAU,MAAM,CAAC;AAAA,EAC9C;AAAA;AASK,IAAM,MAAc,KAAK,CAAC,CAAC;",
-  "debugId": "75B5DF3D0BF305CF64756E2164756E21",
+  "debugId": "DEF7AC9FDEC3F4B864756E2164756E21",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/cloudflare",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Cloudflare Workers helpers: Access JWT verification, typed bindings, structured logging.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/cloudflare#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",
@@ -39,7 +39,7 @@
     "types": "tsc --noEmit"
   },
   "dependencies": {
-    "@homeflare/kit": "0.1.0",
+    "@homeflare/kit": "0.2.0",
     "jose": "6.2.12"
   },
   "devDependencies": {

package/src/access.ts

@@ -4,7 +4,7 @@
  * ★ WHY jose AND NOT A HAND-ROLLED VERIFY. Signature verification is the one place where
  *   a subtle bug is silent and total: a check that never fails looks identical to a
  *   check that always passes. jose handles JWKS fetching, `kid` matching and key
- *   rotation, and it is already in 8 estate packages. This file is the Access-specific
+ *   rotation, and it is widely deployed. This file is the Access-specific
  *   wiring around it, nothing more.
  *
  * ⚠️ THE TRAP THIS CLOSES. Cloudflare's own example does `jwtVerify(...)` inline in the

package/src/version.ts

@@ -1,2 +1,2 @@
 // ⛔ GENERATED by scripts/sync-versions.ts — do not edit. Source: package.json.
-export const VERSION: string = '0.1.0';
+export const VERSION: string = '0.1.2';