@vzn/vx-devtools 0.0.650 → 0.0.651

package/README.md

@@ -51,7 +51,7 @@ export type Authorize = (req: Request) => Promise<Access>
 export interface OidcOptions {
   readonly allow: readonly Allowed[]
   readonly audience?: string
-  readonly fetchJson?: (url: string) => Promise<unknown>
+  readonly fetchJson?: (url: string, fresh: boolean) => Promise<unknown>
   readonly now?: () => number
   readonly readAccess?: string
 }
@@ -64,8 +64,22 @@ export interface Repo {
 export function oidcTokenAuth(
   opts: OidcOptions,
 ): (req: Request, named?: Repo) => Promise<Access | undefined>
+export interface KeysCache {
+  match(url: string): Promise<Response | undefined>
+  put(url: string, res: Response): Promise<void>
+}
+export function cachedFetchJson(
+  cache: KeysCache,
+  fetchImpl?: typeof fetch,
+): (url: string, fresh: boolean) => Promise<unknown>
 ```
 
+- `fetchJson`'s `fresh` is true for a reload of keys already read. A reload
+  must reach the issuer. The first read of a URL may come from a cache.
+- `cachedFetchJson(caches.default)` (any `KeysCache`) is how a Worker reads the keys: a fresh
+  isolate takes them from the cache its data center shares (10 minutes),
+  not from the issuer.
+
 ## How it decides
 
 - jose checks the JWT: `RS256`, the signature against the issuer's keys
@@ -92,5 +106,6 @@ export function oidcTokenAuth(
   `refs/heads/gh-readonly-queue/<base>/pr-<n>-<sha>` ref. A
   `pull_request_target`, `issue_comment` or `workflow_run` run writes
   nothing: its `ref` is the base while it may run a pull request's code.
-  Nor does a GitLab merge request pipeline unless `source_project_path` (GitLab
-  19.5+) names its own project: a fork's runs in the parent project.
+  Nor does a GitLab run whose `source_project_path` or `job_project_path`
+  names another project (a fork's merge request, a child pipeline of one),
+  or a merge request pipeline naming no source project (GitLab before 19.5).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx-devtools",
-  "version": "0.0.650",
+  "version": "0.0.651",
   "license": "MIT",
   "description": "Code vx's servers and plugins share, never core: first, the CI OIDC token check.",
   "keywords": [

package/src/index.ts

@@ -6,6 +6,8 @@ export {
   type Access,
   type Allowed,
   type Authorize,
+  cachedFetchJson,
+  type KeysCache,
   oidcAuth,
   oidcTokenAuth,
   type OidcOptions,

package/src/oidc.ts

@@ -126,22 +126,23 @@ const ON_BEHALF = new Set(['pull_request_target', 'issue_comment', 'workflow_run
  * queue's (`merge_group`) run writes its base branch, which its code is
  * about to become (2026-10-25: "just strip it"); only its ref is renamed:
  * anyone can push a branch named like a queue ref. A run of an event in
- * `ON_BEHALF` writes nothing. A GitLab merge request pipeline writes its source branch
- * only when `source_project_path` names its own project: a fork's runs in
- * the parent project with the fork's branch as its `ref_path`, and a
- * GitLab before 19.5 names no source project.
+ * `ON_BEHALF` writes nothing. A GitLab run writes only when the code and
+ * the job are its project's own (`source_project_path`, `job_project_path`):
+ * a fork's merge request runs in the parent project with the fork's branch
+ * as its `ref_path`, and so may a child pipeline of one or a mirrored pull
+ * request, which were not checked. A merge request pipeline must name its
+ * source project: a GitLab before 19.5 names none.
  */
 function branchOf(iss: string, claims: JWTPayload): string | undefined {
-  if (iss !== GITHUB && claims['pipeline_source'] === 'merge_request_event') {
-    const own = (claim: string) => {
+  if (iss !== GITHUB) {
+    // Absent is its own, but where it must be named: a merge request's.
+    const own = (claim: string, required: boolean) => {
       const p = claims[claim]
+      if (p === undefined) return !required
       return typeof p === 'string' && same(p, String(claims['project_path']))
     }
-    if (
-      !own('source_project_path') ||
-      (claims['job_project_path'] !== undefined && !own('job_project_path'))
-    )
-      return undefined
+    const mr = claims['pipeline_source'] === 'merge_request_event'
+    if (!own('source_project_path', mr) || !own('job_project_path', false)) return undefined
   }
   const event = claims['event_name']
   if (ON_BEHALF.has(event as string)) return undefined
@@ -156,8 +157,12 @@ export interface OidcOptions {
   readonly allow: readonly Allowed[]
   /** The `aud` a token must name; unset, the origin the server is reached at. */
   readonly audience?: string
-  /** Reads a URL as JSON; tests serve keys without a network. */
-  readonly fetchJson?: (url: string) => Promise<unknown>
+  /**
+   * Reads a URL as JSON (`cachedFetchJson` on a Worker); tests serve keys
+   * without a network. `fresh`: a reload of keys already read, which must
+   * reach the issuer; the first read of a URL may come from a cache.
+   */
+  readonly fetchJson?: (url: string, fresh: boolean) => Promise<unknown>
   /** Seconds since the epoch; tests move the clock. */
   readonly now?: () => number
   /** `READ_ACCESS`: `public` lets a request with no token read a repository ALLOW names. */
@@ -303,7 +308,7 @@ function tokenVerifier(opts: OidcOptions): (token: string, req: Request) => Prom
   const stale = new Set<string>()
   const keySet = async (iss: string, url: string): Promise<unknown> => {
     try {
-      const json = await fetchJson(url)
+      const json = await fetchJson(url, lastRead.has(url))
       lastRead.set(url, json)
       stale.delete(iss)
       return json
@@ -316,13 +321,15 @@ function tokenVerifier(opts: OidcOptions): (token: string, req: Request) => Prom
   const keysOf = (iss: string) => {
     let set = keys.get(iss)
     if (set === undefined) {
-      set = fetchJson(`${iss.replace(/\/$/, '')}/.well-known/openid-configuration`).then((c) => {
-        const uri = (c as { jwks_uri?: unknown }).jwks_uri
-        if (typeof uri !== 'string') throw new Error('no jwks_uri')
-        return createRemoteJWKSet(new URL(uri), {
-          [customFetch]: async (url: string) => Response.json(await keySet(iss, url)),
-        })
-      })
+      set = fetchJson(`${iss.replace(/\/$/, '')}/.well-known/openid-configuration`, false).then(
+        (c) => {
+          const uri = (c as { jwks_uri?: unknown }).jwks_uri
+          if (typeof uri !== 'string') throw new Error('no jwks_uri')
+          return createRemoteJWKSet(new URL(uri), {
+            [customFetch]: async (url: string) => Response.json(await keySet(iss, url)),
+          })
+        },
+      )
       keys.set(iss, set)
       // A failed discovery is not kept: the next token tries again.
       // quiet: the awaited set rethrows it; this only forgets it
@@ -435,6 +442,41 @@ const keysUnread = (iss: string, err: unknown): Refusal =>
     `could not read ${iss}'s keys: ${err instanceof Error ? err.message : String(err)}`,
   )
 
+/** A cache a Worker's isolates share (`caches.default`), as `cachedFetchJson` uses it. */
+export interface KeysCache {
+  match(url: string): Promise<Response | undefined>
+  put(url: string, res: Response): Promise<void>
+}
+
+/** How long a shared cache holds an issuer's answer for the next isolate. */
+const KEYS_TTL_S = 600
+
+/**
+ * `fetchJson` through a cache isolates share: a Worker's fresh isolate read
+ * the issuer on its first token, and one slow answer from GitHub failed it
+ * 502 (2026-10-29), as the DTE relay found (2026-10-22). A fresh read (a
+ * reload, maybe for a rotated key) asks the issuer, and refills the cache.
+ */
+export function cachedFetchJson(
+  cache: KeysCache,
+  fetchImpl?: typeof fetch,
+): (url: string, fresh: boolean) => Promise<unknown> {
+  return async (url, fresh) => {
+    const hit = fresh ? undefined : await cache.match(url)
+    if (hit !== undefined) return hit.json()
+    // The global read at each call: one taken when the module loaded missed
+    // a fetch set after it (a test's issuer reached the network).
+    const res = await (fetchImpl ?? fetch)(url, { signal: AbortSignal.timeout(10_000) })
+    if (!res.ok) throw new Error(`${url}: ${res.status}`)
+    const body = await res.text()
+    await cache.put(
+      url,
+      new Response(body, { headers: { 'cache-control': `max-age=${KEYS_TTL_S}` } }),
+    )
+    return JSON.parse(body)
+  }
+}
+
 async function defaultFetchJson(url: string): Promise<unknown> {
   const res = await fetch(url, { signal: AbortSignal.timeout(10_000) })
   if (!res.ok) throw new Error(`${url}: ${res.status}`)