@intentius/chant-lexicon-terraform 0.124.54 → 0.124.56

package/src/registry/edge/token-source.test.ts

@@ -0,0 +1,258 @@
+// Lambda@Edge tokens from SSM Parameter Store or Secrets Manager (chant#4590), tested as a handler in
+// process with a fake fetch standing in for both AWS APIs: no AWS call, real or emulated, and no deploy.
+import { describe, expect, it, vi } from "vitest";
+import { signV4 } from "@intentius/chant/cloud-lister/sigv4";
+import { downloadDoc } from "../index";
+import {
+  FAILED_READ_BACKOFF_MS,
+  lambdaEdgeHandler,
+  parseStoredTokens,
+  signV4Web,
+  type CloudFrontRequestEvent,
+  type EdgeAwsFetch,
+  type RegistryEdgeOptions,
+} from "./index";
+
+const HOST = "modules.test";
+const DIR = "v1/modules/acme/net/generic";
+const TARBALL = `https://${HOST}/${DIR}/0.1.0/net-0.1.0.tar.gz`;
+const credentials = { accessKeyId: "AKIDEXAMPLE", secretAccessKey: "wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEY", sessionToken: "session" };
+const T0 = 1_800_000_000_000;
+
+const objects = new Map<string, string>([[`${DIR}/0.1.0/download`, downloadDoc(TARBALL)]]);
+const files: RegistryEdgeOptions["files"] = async (key) => ({ body: objects.get(key) });
+
+const event = (uri: string, token?: string): CloudFrontRequestEvent => ({
+  Records: [{ cf: { request: { uri, querystring: "", method: "GET", headers: { host: [{ key: "Host", value: HOST }], ...(token ? { authorization: [{ key: "Authorization", value: `Bearer ${token}` }] } : {}) } } } }],
+});
+
+const status = (answer: unknown): string | undefined => (answer && typeof answer === "object" && "status" in answer ? String((answer as { status: string }).status) : undefined);
+const passedOn = (answer: unknown): boolean => !!answer && typeof answer === "object" && "uri" in answer;
+
+/**
+ * Waits for the read the handler starts when it is made. It signs with WebCrypto before it calls
+ * fetch, and that digest settles off the microtask queue, so the call lands a moment after.
+ */
+const firstRead = (calls: Call[]): Promise<void> => vi.waitFor(() => expect(calls.length).toBeGreaterThan(0), { timeout: 2_000, interval: 5 });
+
+interface Call {
+  url: string;
+  headers: Record<string, string>;
+  body: string;
+}
+
+/** A fake SSM and Secrets Manager: answers from `values`, records each call, fails while `down` is set. */
+function fakeAws(values: { ssm?: Record<string, string>; secrets?: Record<string, string> }) {
+  const calls: Call[] = [];
+  const state = { down: false as false | "network" | number };
+  const fetch: EdgeAwsFetch = async (url, init) => {
+    calls.push({ url, headers: init.headers, body: init.body });
+    if (state.down === "network") throw new Error("connect ETIMEDOUT");
+    const reply = (code: number, doc: unknown) => ({ ok: code < 300, status: code, text: async () => JSON.stringify(doc) });
+    if (typeof state.down === "number") return reply(state.down, { __type: "com.amazonaws#ThrottlingException" });
+    const target = init.headers["x-amz-target"];
+    const req = JSON.parse(init.body) as { Name?: string; SecretId?: string; WithDecryption?: boolean };
+    if (target === "AmazonSSM.GetParameter") {
+      const value = values.ssm?.[req.Name!];
+      return value === undefined ? reply(400, { __type: "ParameterNotFound" }) : reply(200, { Parameter: { Name: req.Name, Type: "SecureString", Value: value } });
+    }
+    if (target === "secretsmanager.GetSecretValue") {
+      const value = values.secrets?.[req.SecretId!];
+      return value === undefined ? reply(400, { __type: "ResourceNotFoundException" }) : reply(200, { Name: req.SecretId, SecretString: value });
+    }
+    return reply(400, { __type: "UnknownOperationException" });
+  };
+  return { fetch, calls, state, values };
+}
+
+describe("tokens in the zip (the default source)", () => {
+  it("keeps auth.tokens working with no store read", async () => {
+    const aws = fakeAws({});
+    const handler = lambdaEdgeHandler({ files, auth: { tokens: ["zip-token"] }, now: () => T0 });
+    expect(status(await handler(event(`/${DIR}/versions`)))).toBe("401");
+    expect(passedOn(await handler(event(`/${DIR}/versions`, "zip-token")))).toBe(true);
+    const explicit = lambdaEdgeHandler({ files, auth: { tokens: ["zip-token"], source: { kind: "zip" } }, now: () => T0 });
+    expect(passedOn(await explicit(event(`/${DIR}/versions`, "zip-token")))).toBe(true);
+    expect(aws.calls).toEqual([]);
+  });
+});
+
+describe("tokens from SSM Parameter Store", () => {
+  it("reads the parameter at cold start with a signed GetParameter call, and checks requests against it", async () => {
+    const aws = fakeAws({ ssm: { "/registry/tokens": "old-token,new-token" } });
+    const handler = lambdaEdgeHandler({ files, auth: { source: { kind: "ssm", name: "/registry/tokens", region: "us-east-1", credentials, fetch: aws.fetch } }, now: () => T0 });
+    // The read starts when the handler is made, before any request.
+    await firstRead(aws.calls);
+    expect(aws.calls).toHaveLength(1);
+    const call = aws.calls[0]!;
+    expect(call.url).toBe("https://ssm.us-east-1.amazonaws.com/");
+    expect(JSON.parse(call.body)).toEqual({ Name: "/registry/tokens", WithDecryption: true });
+    expect(call.headers["x-amz-target"]).toBe("AmazonSSM.GetParameter");
+    expect(call.headers["x-amz-security-token"]).toBe("session");
+    expect(call.headers.authorization).toMatch(/^AWS4-HMAC-SHA256 Credential=AKIDEXAMPLE\/\d{8}\/us-east-1\/ssm\/aws4_request, SignedHeaders=content-type;host;x-amz-date;x-amz-security-token;x-amz-target, Signature=[0-9a-f]{64}$/);
+
+    expect(status(await handler(event(`/${DIR}/versions`)))).toBe("401");
+    expect(status(await handler(event(`/${DIR}/versions`, "wrong")))).toBe("401");
+    expect(passedOn(await handler(event(`/${DIR}/versions`, "old-token")))).toBe(true);
+    expect(passedOn(await handler(event(`/${DIR}/versions`, "new-token")))).toBe(true);
+    // Within the cache time the parameter is not read again.
+    expect(aws.calls).toHaveLength(1);
+  });
+
+  it("picks up a rotated parameter after cacheSeconds, with no redeploy", async () => {
+    let now = T0;
+    const aws = fakeAws({ ssm: { "/registry/tokens": "old-token" } });
+    const handler = lambdaEdgeHandler({ files, auth: { source: { kind: "ssm", name: "/registry/tokens", cacheSeconds: 60, credentials, fetch: aws.fetch } }, now: () => now });
+    expect(passedOn(await handler(event(`/${DIR}/versions`, "old-token")))).toBe(true);
+
+    aws.values.ssm!["/registry/tokens"] = "new-token";
+    now += 30_000;
+    // Still the cached read: the old token holds until the cache runs out, and never longer.
+    expect(passedOn(await handler(event(`/${DIR}/versions`, "old-token")))).toBe(true);
+    now += 31_000;
+    expect(status(await handler(event(`/${DIR}/versions`, "old-token")))).toBe("401");
+    expect(passedOn(await handler(event(`/${DIR}/versions`, "new-token")))).toBe(true);
+    expect(aws.calls).toHaveLength(2);
+  });
+
+  it("caps the cache time at an hour", async () => {
+    let now = T0;
+    const aws = fakeAws({ ssm: { p: "t" } });
+    const handler = lambdaEdgeHandler({ files, auth: { source: { kind: "ssm", name: "p", cacheSeconds: 86_400, credentials, fetch: aws.fetch } }, now: () => now });
+    await handler(event(`/${DIR}/versions`, "t"));
+    now += 3_600_001;
+    await handler(event(`/${DIR}/versions`, "t"));
+    expect(aws.calls).toHaveLength(2);
+  });
+
+  it("shares one read between requests that arrive while it is in flight", async () => {
+    const aws = fakeAws({ ssm: { p: "t" } });
+    const handler = lambdaEdgeHandler({ files, auth: { source: { kind: "ssm", name: "p", credentials, fetch: aws.fetch } }, now: () => T0 });
+    const answers = await Promise.all([1, 2, 3].map(() => handler(event(`/${DIR}/versions`, "t"))));
+    expect(answers.every(passedOn)).toBe(true);
+    expect(aws.calls).toHaveLength(1);
+  });
+
+  it("reads the region it is given, never the replica's", async () => {
+    const aws = fakeAws({ ssm: { p: "t" } });
+    lambdaEdgeHandler({ files, auth: { source: { kind: "ssm", name: "p", region: "eu-west-1", credentials, fetch: aws.fetch } } });
+    await firstRead(aws.calls);
+    expect(aws.calls[0]!.url).toBe("https://ssm.eu-west-1.amazonaws.com/");
+    expect(aws.calls[0]!.headers.authorization).toContain("/eu-west-1/ssm/aws4_request");
+  });
+});
+
+describe("tokens from Secrets Manager", () => {
+  it("reads SecretString with a signed GetSecretValue call, JSON form with a signing key", async () => {
+    const aws = fakeAws({ secrets: { "registry/tokens": JSON.stringify({ tokens: ["s3cret"], signingKey: "sign-key" }) } });
+    const handler = lambdaEdgeHandler({ files, auth: { source: { kind: "secrets-manager", secretId: "registry/tokens", credentials, fetch: aws.fetch } }, now: () => T0 });
+    await firstRead(aws.calls);
+    const call = aws.calls[0]!;
+    expect(call.url).toBe("https://secretsmanager.us-east-1.amazonaws.com/");
+    expect(call.headers["x-amz-target"]).toBe("secretsmanager.GetSecretValue");
+    expect(JSON.parse(call.body)).toEqual({ SecretId: "registry/tokens" });
+    expect(call.headers.authorization).toContain("/us-east-1/secretsmanager/aws4_request");
+
+    expect(status(await handler(event(`/${DIR}/versions`)))).toBe("401");
+    const download = await handler(event(`/${DIR}/0.1.0/download`, "s3cret"));
+    expect(status(download)).toBe("200");
+    const location = new URL((download as { headers: Record<string, { value: string }[]> }).headers["x-terraform-get"]![0]!.value);
+    expect(location.searchParams.get("signature")).toBeTruthy();
+  });
+
+  it("takes a plain-text secret, one token per line", async () => {
+    const aws = fakeAws({ secrets: { s: "a-token\nb-token\n" } });
+    const handler = lambdaEdgeHandler({ files, auth: { source: { kind: "secrets-manager", secretId: "s", credentials, fetch: aws.fetch } }, now: () => T0 });
+    expect(passedOn(await handler(event(`/${DIR}/versions`, "b-token")))).toBe(true);
+  });
+
+  it("takes credentials from a function, such as a role the caller assumes", async () => {
+    const aws = fakeAws({ secrets: { s: "t" } });
+    const handler = lambdaEdgeHandler({ files, auth: { source: { kind: "secrets-manager", secretId: "s", credentials: async () => ({ accessKeyId: "AKIDFN", secretAccessKey: "x" }), fetch: aws.fetch } }, now: () => T0 });
+    expect(passedOn(await handler(event(`/${DIR}/versions`, "t")))).toBe(true);
+    expect(aws.calls[0]!.headers.authorization).toContain("Credential=AKIDFN/");
+    expect(aws.calls[0]!.headers["x-amz-security-token"]).toBeUndefined();
+  });
+});
+
+describe("fails closed", () => {
+  it("answers 503 and never passes a request on while the store cannot be reached", async () => {
+    const aws = fakeAws({ ssm: { p: "t" } });
+    aws.state.down = "network";
+    const log: string[] = [];
+    const handler = lambdaEdgeHandler({ files, auth: { source: { kind: "ssm", name: "p", credentials, fetch: aws.fetch } }, now: () => T0, log: (l) => log.push(l) });
+    const answer = await handler(event(`/${DIR}/versions`, "t"));
+    expect(status(answer)).toBe("503");
+    expect((answer as { headers: Record<string, { value: string }[]> }).headers["cache-control"]![0]!.value).toBe("no-store");
+    expect(status(await handler(event(`/${DIR}/0.1.0/download`, "t")))).toBe("503");
+    expect(log.join("\n")).toContain("token store:");
+    expect(log.join("\n")).not.toContain("Bearer");
+  });
+
+  it("refuses on an AWS error answer, a missing parameter, or a value with no token", async () => {
+    for (const [values, down] of [[{ ssm: { p: "t" } }, 400], [{ ssm: {} }, false], [{ ssm: { p: " ,\n " } }, false], [{ ssm: { p: "{not json" } }, false]] as const) {
+      const aws = fakeAws(values as { ssm: Record<string, string> });
+      aws.state.down = down;
+      const handler = lambdaEdgeHandler({ files, auth: { source: { kind: "ssm", name: "p", credentials, fetch: aws.fetch } }, now: () => T0 });
+      expect(status(await handler(event(`/${DIR}/versions`, "t")))).toBe("503");
+    }
+  });
+
+  it("drops the cached tokens when a refresh fails, then recovers after the backoff", async () => {
+    let now = T0;
+    const aws = fakeAws({ ssm: { p: "t" } });
+    const handler = lambdaEdgeHandler({ files, auth: { source: { kind: "ssm", name: "p", cacheSeconds: 60, credentials, fetch: aws.fetch } }, now: () => now });
+    expect(passedOn(await handler(event(`/${DIR}/versions`, "t")))).toBe(true);
+    aws.state.down = 500;
+    now += 61_000;
+    expect(status(await handler(event(`/${DIR}/versions`, "t")))).toBe("503");
+    // Within the backoff the store is not read again on every request.
+    expect(status(await handler(event(`/${DIR}/versions`, "t")))).toBe("503");
+    expect(aws.calls).toHaveLength(2);
+    aws.state.down = false;
+    now += FAILED_READ_BACKOFF_MS + 1;
+    expect(passedOn(await handler(event(`/${DIR}/versions`, "t")))).toBe(true);
+    expect(aws.calls).toHaveLength(3);
+  });
+
+  it("refuses when there are no credentials in the runtime", async () => {
+    const aws = fakeAws({ ssm: { p: "t" } });
+    const env = (globalThis as { process?: { env: Record<string, string | undefined> } }).process!.env;
+    const saved = { id: env.AWS_ACCESS_KEY_ID, secret: env.AWS_SECRET_ACCESS_KEY };
+    delete env.AWS_ACCESS_KEY_ID;
+    delete env.AWS_SECRET_ACCESS_KEY;
+    try {
+      const handler = lambdaEdgeHandler({ files, auth: { source: { kind: "ssm", name: "p", fetch: aws.fetch } }, now: () => T0 });
+      expect(status(await handler(event(`/${DIR}/versions`, "t")))).toBe("503");
+      expect(aws.calls).toEqual([]);
+    } finally {
+      if (saved.id !== undefined) env.AWS_ACCESS_KEY_ID = saved.id;
+      if (saved.secret !== undefined) env.AWS_SECRET_ACCESS_KEY = saved.secret;
+    }
+  });
+});
+
+describe("parseStoredTokens", () => {
+  it("reads the line and comma form and the JSON form", () => {
+    expect(parseStoredTokens("a, b\nc")).toEqual({ tokens: ["a", "b", "c"] });
+    expect(parseStoredTokens('{"tokens":"a,b"}')).toEqual({ tokens: ["a", "b"] });
+    expect(parseStoredTokens('{"tokens":["a"," b "],"signingKey":"k"}')).toEqual({ tokens: ["a", "b"], signingKey: "k" });
+    expect(() => parseStoredTokens("{oops")).toThrow("do not parse");
+  });
+});
+
+describe("signV4Web", () => {
+  it("signs exactly as chant core's signer does", async () => {
+    const input = {
+      method: "POST",
+      url: "https://ssm.us-east-1.amazonaws.com/",
+      headers: { "content-type": "application/x-amz-json-1.1", "x-amz-target": "AmazonSSM.GetParameter" },
+      body: JSON.stringify({ Name: "/registry/tokens", WithDecryption: true }),
+      region: "us-east-1",
+      service: "ssm",
+      credentials,
+      now: new Date(T0),
+    };
+    expect(await signV4Web(input)).toEqual(signV4(input));
+  });
+});

package/src/registry/edge/token-source.ts

@@ -0,0 +1,169 @@
+/**
+ * Where the Lambda@Edge function gets its accepted tokens (chant#4590).
+ * Lambda@Edge has no environment of its own, so by default the tokens are
+ * built into the zip (`source: { kind: "zip" }`, terragucci#1287's
+ * registry-edge.json). The function can instead read them from SSM Parameter
+ * Store or Secrets Manager: the read starts when the handler is made (the
+ * cold start), its answer is kept for `cacheSeconds`, and a rotation in the
+ * store reaches every replica within that time with no redeploy.
+ *
+ * The read fails closed: while the store cannot be read, or holds no token,
+ * every request gets a 503 and none reaches the bucket.
+ *
+ * The reads are plain fetch calls signed with ./sigv4-web.ts (Web Crypto),
+ * so registry/edge stays free of Node built-ins (chant#4589). Credentials
+ * default to the execution role's, which the Lambda runtime puts in
+ * AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_SESSION_TOKEN; the role
+ * needs ssm:GetParameter (and kms:Decrypt for a SecureString under a key of
+ * your own) or secretsmanager:GetSecretValue on that one name.
+ */
+import { tokensFromSecret } from "./edge";
+import { signV4Web, type EdgeAwsCredentials } from "./sigv4-web";
+
+/** The fetch the reads call; a test passes a fake, so no AWS call is made. */
+export type EdgeAwsFetch = (url: string, init: { method: string; headers: Record<string, string>; body: string }) => Promise<{ ok: boolean; status: number; text(): Promise<string> }>;
+
+/** What a store read shares. */
+interface StoreSourceBase {
+  /**
+   * The region the parameter or secret is in. Default us-east-1, where a
+   * Lambda@Edge function is created; the replicas run in other regions, so
+   * the function's own AWS_REGION is never used.
+   */
+  region?: string;
+  /** Seconds a read is kept before the next request reads again. Default 300, at most 3600. */
+  cacheSeconds?: number;
+  /** The credentials to sign with. Default: the execution role's, from the runtime's environment. */
+  credentials?: EdgeAwsCredentials | (() => Promise<EdgeAwsCredentials>);
+  /** The fetch to call. Default the global fetch. */
+  fetch?: EdgeAwsFetch;
+}
+
+/** An SSM parameter (String or SecureString) holding the tokens. */
+export interface SsmTokenSource extends StoreSourceBase {
+  kind: "ssm";
+  /** The parameter's name, such as /registry/tokens. */
+  name: string;
+}
+
+/** A Secrets Manager secret whose SecretString holds the tokens. */
+export interface SecretsManagerTokenSource extends StoreSourceBase {
+  kind: "secrets-manager";
+  /** The secret's name or ARN. */
+  secretId: string;
+}
+
+/** The tokens built into the function: `auth.tokens`. */
+export interface ZipTokenSource {
+  kind: "zip";
+}
+
+export type EdgeTokenSource = ZipTokenSource | SsmTokenSource | SecretsManagerTokenSource;
+
+/** The tokens a store holds, and the signing key when the store names one. */
+export interface StoredTokens {
+  tokens: string[];
+  signingKey?: string;
+}
+
+export const DEFAULT_TOKEN_CACHE_SECONDS = 300;
+export const MAX_TOKEN_CACHE_SECONDS = 3600;
+/** After a failed read, requests are refused for this long before the next read, so a broken store is not read once per request. */
+export const FAILED_READ_BACKOFF_MS = 5_000;
+
+/**
+ * A stored value as tokens. Either the worker's REGISTRY_TOKENS form (one per
+ * line or comma separated) or JSON: `{ "tokens": [...] | "a,b", "signingKey": "..." }`.
+ */
+export function parseStoredTokens(text: string): StoredTokens {
+  const trimmed = text.trim();
+  if (trimmed.startsWith("{")) {
+    let doc: { tokens?: unknown; signingKey?: unknown };
+    try {
+      doc = JSON.parse(trimmed);
+    } catch {
+      throw new Error("the stored tokens look like JSON but do not parse");
+    }
+    const tokens = Array.isArray(doc.tokens) ? doc.tokens.filter((t): t is string => typeof t === "string").map((t) => t.trim()).filter((t) => !!t) : typeof doc.tokens === "string" ? tokensFromSecret(doc.tokens) : [];
+    return { tokens, ...(typeof doc.signingKey === "string" && doc.signingKey ? { signingKey: doc.signingKey } : {}) };
+  }
+  return { tokens: tokensFromSecret(trimmed) };
+}
+
+/** The execution role's credentials, read from the runtime's environment without importing node:process. */
+function runtimeCredentials(): EdgeAwsCredentials {
+  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env ?? {};
+  const accessKeyId = env.AWS_ACCESS_KEY_ID;
+  const secretAccessKey = env.AWS_SECRET_ACCESS_KEY;
+  if (!accessKeyId || !secretAccessKey) throw new Error("no AWS credentials in the function's runtime (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)");
+  return { accessKeyId, secretAccessKey, ...(env.AWS_SESSION_TOKEN ? { sessionToken: env.AWS_SESSION_TOKEN } : {}) };
+}
+
+const defaultFetch: EdgeAwsFetch = (url, init) => fetch(url, init);
+
+/** One read of the store: the signed JSON call, and the value it answers. */
+export async function readStoredTokens(source: SsmTokenSource | SecretsManagerTokenSource, now: Date = new Date()): Promise<StoredTokens> {
+  const region = source.region ?? "us-east-1";
+  const service = source.kind === "ssm" ? "ssm" : "secretsmanager";
+  const url = `https://${service}.${region}.amazonaws.com/`;
+  const target = source.kind === "ssm" ? "AmazonSSM.GetParameter" : "secretsmanager.GetSecretValue";
+  const body = JSON.stringify(source.kind === "ssm" ? { Name: source.name, WithDecryption: true } : { SecretId: source.secretId });
+  const credentials = typeof source.credentials === "function" ? await source.credentials() : (source.credentials ?? runtimeCredentials());
+  const headers = await signV4Web({ method: "POST", url, headers: { "content-type": "application/x-amz-json-1.1", "x-amz-target": target }, body, region, service, credentials, now });
+  const res = await (source.fetch ?? defaultFetch)(url, { method: "POST", headers, body });
+  const text = await res.text();
+  const what = source.kind === "ssm" ? `SSM parameter ${source.name}` : `secret ${source.secretId}`;
+  if (!res.ok) {
+    let type = "";
+    try {
+      type = String((JSON.parse(text) as { __type?: unknown }).__type ?? "").split("#").pop() ?? "";
+    } catch {}
+    throw new Error(`reading ${what} in ${region} answered ${res.status}${type ? ` ${type}` : ""}`);
+  }
+  let value: unknown;
+  try {
+    const doc = JSON.parse(text) as { Parameter?: { Value?: unknown }; SecretString?: unknown };
+    value = source.kind === "ssm" ? doc.Parameter?.Value : doc.SecretString;
+  } catch {
+    throw new Error(`reading ${what} answered something other than JSON`);
+  }
+  if (typeof value !== "string") throw new Error(`${what} has no text value${source.kind === "secrets-manager" ? " (a binary secret is not read)" : ""}`);
+  const stored = parseStoredTokens(value);
+  if (stored.tokens.length === 0) throw new Error(`${what} holds no token`);
+  return stored;
+}
+
+/** Tokens read from a store and kept for a bounded time. `get` throws while the store cannot be read. */
+export interface TokenCache {
+  get(): Promise<StoredTokens>;
+}
+
+/**
+ * A cache over `readStoredTokens`. The first read starts at once (cold
+ * start). Requests that arrive during a read wait on that one read. A good
+ * read is kept for `cacheSeconds`; a failed one is kept for
+ * FAILED_READ_BACKOFF_MS, and every `get` in that time throws. The last good
+ * tokens are never served past their time, so the function fails closed.
+ */
+export function storedTokenCache(source: SsmTokenSource | SecretsManagerTokenSource, now: () => number = Date.now): TokenCache {
+  const cacheMs = Math.min(Math.max(source.cacheSeconds ?? DEFAULT_TOKEN_CACHE_SECONDS, 0), MAX_TOKEN_CACHE_SECONDS) * 1000;
+  let held: { until: number; result: Promise<StoredTokens> } | undefined;
+  const read = (): Promise<StoredTokens> => {
+    const result = readStoredTokens(source, new Date(now()));
+    const entry = { until: Number.POSITIVE_INFINITY, result };
+    held = entry;
+    result.then(
+      () => {
+        entry.until = now() + cacheMs;
+      },
+      () => {
+        entry.until = now() + FAILED_READ_BACKOFF_MS;
+      },
+    );
+    return result;
+  };
+  read().catch(() => {});
+  return {
+    get: () => (held && now() < held.until ? held.result : read()),
+  };
+}

package/src/registry/edge/worker.ts

@@ -0,0 +1,61 @@
+/**
+ * The registry edge function as a Cloudflare Worker (chant#4566). Bindings:
+ *
+ *   REGISTRY_BUCKET        an R2 bucket binding holding the registry's files, or
+ *   REGISTRY_ORIGIN        the bucket's HTTP endpoint, when the files are elsewhere
+ *   REGISTRY_PREFIX        the registry's prefix in the bucket (optional)
+ *   REGISTRY_AUTH          "token" turns read auth on; anything else, or unset, leaves it off
+ *   REGISTRY_TOKENS        a secret: the accepted tokens, one per line or comma separated
+ *   REGISTRY_SIGNING_KEY   a secret: the key tarball URLs are signed with (default: the first token)
+ *   REGISTRY_URL_TTL       seconds a signed tarball URL works (default 300)
+ *
+ * Rotating a token: add the new one to REGISTRY_TOKENS beside the old, move
+ * the CLIs to it, then drop the old one. Rotating the signing key breaks only
+ * signed URLs already handed out, which live for REGISTRY_URL_TTL seconds.
+ *
+ * No Node APIs, so it runs without the nodejs_compat flag.
+ */
+import type { RegistryFiles } from "../handler";
+import { DEFAULT_SIGNED_TTL, originFiles, registryEdge, tokensFromSecret, type EdgeAuth } from "./edge";
+
+/** The part of an R2 bucket binding the worker uses. */
+export interface R2BucketLike {
+  get(key: string): Promise<{ arrayBuffer(): Promise<ArrayBuffer> } | null>;
+}
+
+export interface RegistryWorkerEnv {
+  REGISTRY_BUCKET?: R2BucketLike;
+  REGISTRY_ORIGIN?: string;
+  REGISTRY_PREFIX?: string;
+  REGISTRY_AUTH?: string;
+  REGISTRY_TOKENS?: string;
+  REGISTRY_SIGNING_KEY?: string;
+  REGISTRY_URL_TTL?: string;
+}
+
+/** Files read from an R2 binding. */
+export const r2Files = (bucket: R2BucketLike): RegistryFiles => async (key) => {
+  const o = await bucket.get(key);
+  return o ? { body: new Uint8Array(await o.arrayBuffer()) } : {};
+};
+
+/** Read auth from the worker's bindings, or undefined when it is off. */
+export function workerAuth(env: RegistryWorkerEnv): EdgeAuth | undefined {
+  if ((env.REGISTRY_AUTH ?? "").trim().toLowerCase() !== "token") return undefined;
+  const ttl = Number(env.REGISTRY_URL_TTL);
+  return {
+    tokens: tokensFromSecret(env.REGISTRY_TOKENS),
+    ...(env.REGISTRY_SIGNING_KEY ? { signingKey: env.REGISTRY_SIGNING_KEY } : {}),
+    ttl: Number.isInteger(ttl) && ttl > 0 ? ttl : DEFAULT_SIGNED_TTL,
+  };
+}
+
+/** Answers one request with the worker's bindings. */
+export async function registryWorkerFetch(request: Request, env: RegistryWorkerEnv): Promise<Response> {
+  const files = env.REGISTRY_BUCKET ? r2Files(env.REGISTRY_BUCKET) : env.REGISTRY_ORIGIN ? originFiles(env.REGISTRY_ORIGIN) : undefined;
+  if (!files) return new Response("the registry worker needs a REGISTRY_BUCKET binding or REGISTRY_ORIGIN\n", { status: 500 });
+  return registryEdge({ files, prefix: env.REGISTRY_PREFIX, auth: workerAuth(env) })(request);
+}
+
+/** The module a worker's entry file re-exports as its default. */
+export const registryWorker = { fetch: registryWorkerFetch };

package/src/registry/handler.ts

@@ -0,0 +1,89 @@
+/**
+ * Answering registry requests as the CLIs need them: each file as stored,
+ * except a version's `download`, which goes out as `downloadAnswer` (200, the
+ * JSON body, and `X-Terraform-Get` from the body's location; terragucci#1287).
+ *
+ * `registryHandler` is a web-standard `(Request) => Response` with no Node
+ * imports, so the same code answers in an edge function (chant#4566), in a
+ * test as a fetch (`handlerFetch`), and on a loopback socket through
+ * `serveRegistry` in ./serve, which real `terraform init` and `tofu init`
+ * runs point at.
+ */
+import { keyFor } from "./address";
+import type { RegistryFetch } from "./reader";
+import { downloadAnswer, downloadLocation, isDownloadPath } from "./writer";
+
+/** Where the handler reads the registry's files: a key in, the bytes out (or none). */
+export type RegistryFiles = (key: string) => Promise<{ body?: string | Uint8Array }>;
+
+/** A registry held by a store with a text `read` (a bucket client, a test's map). Tarballs need a store that reads bytes. */
+export const storeFiles = (store: { read(key: string): Promise<{ body?: string | Uint8Array }> }): RegistryFiles => (key) => store.read(key);
+
+export interface RegistryHandlerOptions {
+  /** The registry's prefix in its store: URL path `p` reads key `<prefix>/p`. */
+  prefix?: string;
+  /** Called once per request, for a test's log: method, path and the status sent. */
+  log?: (line: string) => void;
+}
+
+export type RegistryHandler = (request: Request) => Promise<Response>;
+
+/**
+ * The pages a release catalog writes beside the registry (chant#4599,
+ * `<prefix>/catalog/`), by extension, so a browser renders them instead of
+ * downloading them.
+ */
+const PAGE_TYPES: Record<string, string> = {
+  ".html": "text/html; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".svg": "image/svg+xml",
+};
+
+/** The `content-type` a registry file is served with. */
+export const registryContentType = (key: string): string => {
+  if (key.endsWith(".tar.gz") || key.endsWith(".tgz")) return "application/gzip";
+  if (key.endsWith(".json") || /(^|\/)(versions|download)$/.test(key)) return "application/json";
+  const dot = key.lastIndexOf(".");
+  return (dot > key.lastIndexOf("/") && PAGE_TYPES[key.slice(dot).toLowerCase()]) || "application/octet-stream";
+};
+
+// TextEncoder and TextDecoder, not Buffer: an edge runtime (a Cloudflare Worker without nodejs_compat) has no Buffer.
+const asText = (body: string | Uint8Array): string => (typeof body === "string" ? body : new TextDecoder().decode(body));
+
+/** Answers GET and HEAD for a registry's files, adding `X-Terraform-Get` to each download answer. */
+export function registryHandler(files: RegistryFiles, options: RegistryHandlerOptions = {}): RegistryHandler {
+  return async (request) => {
+    const url = new URL(request.url);
+    const method = request.method.toUpperCase();
+    const done = (res: Response): Response => {
+      options.log?.(`${method} ${url.pathname} -> ${res.status}`);
+      return res;
+    };
+    if (method !== "GET" && method !== "HEAD") return done(new Response(null, { status: 405, headers: { allow: "GET, HEAD" } }));
+    let path: string;
+    try {
+      path = decodeURIComponent(url.pathname).replace(/^\/+/, "");
+    } catch {
+      return done(new Response(null, { status: 400 }));
+    }
+    if (!path || path.split("/").includes("..")) return done(new Response(null, { status: 404 }));
+    const key = keyFor(options.prefix, path);
+    const { body } = await files(key);
+    if (body === undefined) return done(new Response(null, { status: 404 }));
+    if (isDownloadPath(path)) {
+      const location = downloadLocation(asText(body));
+      if (location) {
+        const answer = downloadAnswer(location);
+        return done(new Response(method === "HEAD" ? null : answer.body, { status: answer.status, headers: answer.headers }));
+      }
+    }
+    const bytes = typeof body === "string" ? new TextEncoder().encode(body) : body;
+    const headers = { "content-type": registryContentType(key), "content-length": String(bytes.byteLength) };
+    return done(new Response(method === "HEAD" ? null : new Uint8Array(bytes), { status: 200, headers }));
+  };
+}
+
+/** A fetch that answers from a handler in process, for tests that need no socket. */
+export const handlerFetch = (handler: RegistryHandler): RegistryFetch => (url, init) => handler(new Request(url, { method: init?.method ?? "GET", ...(init?.headers ? { headers: init.headers } : {}) }));
+

package/src/registry/headers-file.ts

@@ -0,0 +1,61 @@
+/**
+ * The `_headers` file Cloudflare Pages and Netlify read beside a static site
+ * (terragucci#1287): one rule per version's download path, sending
+ * `X-Terraform-Get` with the location the stored body names. A host that
+ * reads `_headers` needs no edge function for Terraform to install; a plain
+ * bucket, GitHub Pages and GitLab Pages can't set a header per object and do.
+ *
+ * Cloudflare Pages reads at most 100 rules from `_headers`; a registry with
+ * more versions than that needs the edge function there.
+ */
+import { DOWNLOAD_HEADER } from "./writer";
+
+/** The file's name at the site's root. */
+export const HEADERS_FILE = "_headers";
+/** Rules Cloudflare Pages reads from `_headers`. */
+export const PAGES_HEADER_RULES = 100;
+
+/** One download path (from the site root, leading `/`) and the location its header names. */
+export interface DownloadHeaderRule {
+  path: string;
+  location: string;
+}
+
+const rulePath = (path: string): string => `/${path.replace(/^\/+/, "")}`;
+
+/** The download rules an existing `_headers` file holds; other rules are kept by `headersFile` as they are. */
+export function readHeadersFile(text: string | undefined): { downloads: DownloadHeaderRule[]; other: string[] } {
+  const downloads: DownloadHeaderRule[] = [];
+  const other: string[] = [];
+  let current: { path: string; lines: string[] } | undefined;
+  const flush = () => {
+    if (!current) return;
+    const header = current.lines.map((l) => /^\s+([^:]+):\s*(.*)$/.exec(l)).find((m) => m && m[1]!.trim().toLowerCase() === DOWNLOAD_HEADER.toLowerCase());
+    if (header && current.lines.length === 1) downloads.push({ path: current.path, location: header[2]!.trim() });
+    else other.push([current.path, ...current.lines].join("\n"));
+    current = undefined;
+  };
+  for (const line of (text ?? "").split(/\r?\n/)) {
+    if (!line.trim() || line.trim().startsWith("#")) continue;
+    if (/^\s/.test(line)) current?.lines.push(line);
+    else {
+      flush();
+      current = { path: line.trim(), lines: [] };
+    }
+  }
+  flush();
+  return { downloads, other };
+}
+
+/**
+ * A `_headers` file with a rule per download, merged into `existing`: rules
+ * for other paths stay as written, a download rule for the same path is
+ * replaced, and download rules are sorted by path.
+ */
+export function headersFile(rules: DownloadHeaderRule[], existing?: string): string {
+  const held = readHeadersFile(existing);
+  const byPath = new Map(held.downloads.map((r) => [r.path, r.location]));
+  for (const r of rules) byPath.set(rulePath(r.path), r.location);
+  const downloads = [...byPath.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([path, location]) => `${path}\n  ${DOWNLOAD_HEADER}: ${location}`);
+  return `${[...held.other, ...downloads].join("\n\n")}\n`;
+}