@intentius/chant-lexicon-terraform 0.124.54 → 0.124.56

package/dist/registry/edge/token-source.js

@@ -0,0 +1,115 @@
+/**
+ * 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.js";
+import { signV4Web } from "./sigv4-web.js";
+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 = 5000;
+/**
+ * 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) {
+    const trimmed = text.trim();
+    if (trimmed.startsWith("{")) {
+        let doc;
+        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) => 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() {
+    const env = globalThis.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 = (url, init) => fetch(url, init);
+/** One read of the store: the signed JSON call, and the value it answers. */
+export async function readStoredTokens(source, now = new Date()) {
+    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).__type ?? "").split("#").pop() ?? "";
+        }
+        catch { }
+        throw new Error(`reading ${what} in ${region} answered ${res.status}${type ? ` ${type}` : ""}`);
+    }
+    let value;
+    try {
+        const doc = JSON.parse(text);
+        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;
+}
+/**
+ * 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, now = Date.now) {
+    const cacheMs = Math.min(Math.max(source.cacheSeconds ?? DEFAULT_TOKEN_CACHE_SECONDS, 0), MAX_TOKEN_CACHE_SECONDS) * 1000;
+    let held;
+    const read = () => {
+        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/dist/registry/edge/worker.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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.js";
+import { type EdgeAuth } from "./edge.js";
+/** 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 declare const r2Files: (bucket: R2BucketLike) => RegistryFiles;
+/** Read auth from the worker's bindings, or undefined when it is off. */
+export declare function workerAuth(env: RegistryWorkerEnv): EdgeAuth | undefined;
+/** Answers one request with the worker's bindings. */
+export declare function registryWorkerFetch(request: Request, env: RegistryWorkerEnv): Promise<Response>;
+/** The module a worker's entry file re-exports as its default. */
+export declare const registryWorker: {
+    fetch: typeof registryWorkerFetch;
+};
+//# sourceMappingURL=worker.d.ts.map

package/dist/registry/edge/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../../src/registry/edge/worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAmE,KAAK,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAExG,wDAAwD;AACxD,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;CAC3E;AAED,MAAM,WAAW,iBAAiB;IAChC,eAAe,CAAC,EAAE,YAAY,CAAC;IAC/B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,qCAAqC;AACrC,eAAO,MAAM,OAAO,WAAY,YAAY,KAAG,aAG9C,CAAC;AAEF,yEAAyE;AACzE,wBAAgB,UAAU,CAAC,GAAG,EAAE,iBAAiB,GAAG,QAAQ,GAAG,SAAS,CAQvE;AAED,sDAAsD;AACtD,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAIrG;AAED,kEAAkE;AAClE,eAAO,MAAM,cAAc;IAAK,KAAK;CAAuB,CAAC"}

package/dist/registry/edge/worker.js

@@ -0,0 +1,26 @@
+import { DEFAULT_SIGNED_TTL, originFiles, registryEdge, tokensFromSecret } from "./edge.js";
+/** Files read from an R2 binding. */
+export const r2Files = (bucket) => 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) {
+    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, env) {
+    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/dist/registry/handler.d.ts

@@ -0,0 +1,25 @@
+import type { RegistryFetch } from "./reader.js";
+/** 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 declare const storeFiles: (store: {
+    read(key: string): Promise<{
+        body?: string | Uint8Array;
+    }>;
+}) => RegistryFiles;
+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 `content-type` a registry file is served with. */
+export declare const registryContentType: (key: string) => string;
+/** Answers GET and HEAD for a registry's files, adding `X-Terraform-Get` to each download answer. */
+export declare function registryHandler(files: RegistryFiles, options?: RegistryHandlerOptions): RegistryHandler;
+/** A fetch that answers from a handler in process, for tests that need no socket. */
+export declare const handlerFetch: (handler: RegistryHandler) => RegistryFetch;
+//# sourceMappingURL=handler.d.ts.map

package/dist/registry/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/registry/handler.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAG9C,uFAAuF;AACvF,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IAAE,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,CAAA;CAAE,CAAC,CAAC;AAErF,6HAA6H;AAC7H,eAAO,MAAM,UAAU,UAAW;IAAE,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,CAAA;KAAE,CAAC,CAAA;CAAE,KAAG,aAAyC,CAAC;AAE7I,MAAM,WAAW,sBAAsB;IACrC,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mFAAmF;IACnF,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AActE,yDAAyD;AACzD,eAAO,MAAM,mBAAmB,QAAS,MAAM,KAAG,MAKjD,CAAC;AAKF,qGAAqG;AACrG,wBAAgB,eAAe,CAAC,KAAK,EAAE,aAAa,EAAE,OAAO,GAAE,sBAA2B,GAAG,eAAe,CA8B3G;AAED,qFAAqF;AACrF,eAAO,MAAM,YAAY,YAAa,eAAe,KAAG,aAAiJ,CAAC"}

package/dist/registry/handler.js

@@ -0,0 +1,75 @@
+/**
+ * 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.js";
+import { downloadAnswer, downloadLocation, isDownloadPath } from "./writer.js";
+/** 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) => (key) => store.read(key);
+/**
+ * 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 = {
+    ".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) => {
+    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) => (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, options = {}) {
+    return async (request) => {
+        const url = new URL(request.url);
+        const method = request.method.toUpperCase();
+        const done = (res) => {
+            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;
+        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) => (url, init) => handler(new Request(url, { method: init?.method ?? "GET", ...(init?.headers ? { headers: init.headers } : {}) }));

package/dist/registry/headers-file.d.ts

@@ -0,0 +1,21 @@
+/** The file's name at the site's root. */
+export declare const HEADERS_FILE = "_headers";
+/** Rules Cloudflare Pages reads from `_headers`. */
+export declare 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;
+}
+/** The download rules an existing `_headers` file holds; other rules are kept by `headersFile` as they are. */
+export declare function readHeadersFile(text: string | undefined): {
+    downloads: DownloadHeaderRule[];
+    other: string[];
+};
+/**
+ * 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 declare function headersFile(rules: DownloadHeaderRule[], existing?: string): string;
+//# sourceMappingURL=headers-file.d.ts.map

package/dist/registry/headers-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headers-file.d.ts","sourceRoot":"","sources":["../../src/registry/headers-file.ts"],"names":[],"mappings":"AAYA,0CAA0C;AAC1C,eAAO,MAAM,YAAY,aAAa,CAAC;AACvC,oDAAoD;AACpD,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAEtC,6FAA6F;AAC7F,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAID,+GAA+G;AAC/G,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG;IAAE,SAAS,EAAE,kBAAkB,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAqB9G;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,kBAAkB,EAAE,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAMlF"}

package/dist/registry/headers-file.js

@@ -0,0 +1,57 @@
+/**
+ * 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.js";
+/** 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;
+const rulePath = (path) => `/${path.replace(/^\/+/, "")}`;
+/** The download rules an existing `_headers` file holds; other rules are kept by `headersFile` as they are. */
+export function readHeadersFile(text) {
+    const downloads = [];
+    const other = [];
+    let current;
+    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, existing) {
+    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`;
+}

package/dist/registry/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The Terraform module registry protocol (chant#4565): addresses, the writer
+ * of the protocol's files, the reader as Terraform and OpenTofu read them,
+ * and a handler that serves the files with the download header both CLIs
+ * install from. Moved from terragucci's `publish/registry.ts`; products keep
+ * their config keys and presets and call this. The module targets that
+ * publish a version to a hosted registry (GitLab first) are under ./targets
+ * (chant#4603). ./docs reads a module's README, inputs, outputs and
+ * examples for its release catalog page (chant#4598). ./source-forms puts
+ * module sources and provider addresses in one normal form, and
+ * ../used-sources lists the ones a root uses (chant#3924); ./proxies
+ * reads them through Artifactory and Nexus proxies (chant#4606).
+ */
+export * from "./address.js";
+export * from "./semver.js";
+export * from "./writer.js";
+export * from "./reader.js";
+export * from "./handler.js";
+export * from "./serve.js";
+export * from "./headers-file.js";
+export * from "./mirror.js";
+export * from "./edge/index.js";
+export * from "./targets/index.js";
+export * from "./docs.js";
+export * from "./catalog-read.js";
+export * from "./deprecated.js";
+export * from "./source-forms.js";
+export * from "./proxies.js";
+export { moduleConsumers, isLocalSource, type ModuleConsumer } from "../pin/consumers.js";
+export { usedSources, type UsedSource, type UnreadSource, type UsedSourcesOptions } from "../used-sources.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/registry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/registry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,cAAc,QAAQ,CAAC;AACvB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvF,OAAO,EAAE,WAAW,EAAE,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/registry/index.js

@@ -0,0 +1,30 @@
+/**
+ * The Terraform module registry protocol (chant#4565): addresses, the writer
+ * of the protocol's files, the reader as Terraform and OpenTofu read them,
+ * and a handler that serves the files with the download header both CLIs
+ * install from. Moved from terragucci's `publish/registry.ts`; products keep
+ * their config keys and presets and call this. The module targets that
+ * publish a version to a hosted registry (GitLab first) are under ./targets
+ * (chant#4603). ./docs reads a module's README, inputs, outputs and
+ * examples for its release catalog page (chant#4598). ./source-forms puts
+ * module sources and provider addresses in one normal form, and
+ * ../used-sources lists the ones a root uses (chant#3924); ./proxies
+ * reads them through Artifactory and Nexus proxies (chant#4606).
+ */
+export * from "./address.js";
+export * from "./semver.js";
+export * from "./writer.js";
+export * from "./reader.js";
+export * from "./handler.js";
+export * from "./serve.js";
+export * from "./headers-file.js";
+export * from "./mirror.js";
+export * from "./edge/index.js";
+export * from "./targets/index.js";
+export * from "./docs.js";
+export * from "./catalog-read.js";
+export * from "./deprecated.js";
+export * from "./source-forms.js";
+export * from "./proxies.js";
+export { moduleConsumers, isLocalSource } from "../pin/consumers.js";
+export { usedSources } from "../used-sources.js";

package/dist/registry/mirror-paths.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Paths of the provider network mirror under a registry (chant#4564), with no
+ * Node imports, so the edge function can tell a mirror's version file apart.
+ */
+/** The mirror's place under the registry's prefix. */
+export declare const PROVIDER_MIRROR_PREFIX = "providers";
+/** True for a mirror's `providers/<host>/<ns>/<type>/<version>.json` path, with or without a prefix in front. */
+export declare const isMirrorVersionPath: (path: string) => boolean;
+//# sourceMappingURL=mirror-paths.d.ts.map

package/dist/registry/mirror-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mirror-paths.d.ts","sourceRoot":"","sources":["../../src/registry/mirror-paths.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,sDAAsD;AACtD,eAAO,MAAM,sBAAsB,cAAc,CAAC;AAElD,iHAAiH;AACjH,eAAO,MAAM,mBAAmB,SAAU,MAAM,KAAG,OAAkI,CAAC"}

package/dist/registry/mirror-paths.js

@@ -0,0 +1,8 @@
+/**
+ * Paths of the provider network mirror under a registry (chant#4564), with no
+ * Node imports, so the edge function can tell a mirror's version file apart.
+ */
+/** The mirror's place under the registry's prefix. */
+export const PROVIDER_MIRROR_PREFIX = "providers";
+/** True for a mirror's `providers/<host>/<ns>/<type>/<version>.json` path, with or without a prefix in front. */
+export const isMirrorVersionPath = (path) => new RegExp(`(^|/)${PROVIDER_MIRROR_PREFIX}/[^/]+/[^/]+/[^/]+/(?!index\\.json$)[^/]+\\.json$`).test(path.split("?")[0]);

package/dist/registry/mirror.d.ts

@@ -0,0 +1,130 @@
+import type { RegistryWriteStore } from "./writer.js";
+export { PROVIDER_MIRROR_PREFIX, isMirrorVersionPath } from "./mirror-paths.js";
+export declare const LOCK_FILE = ".terraform.lock.hcl";
+/** The two hosts a hostless provider source resolves to. */
+export declare const TERRAFORM_REGISTRY = "registry.terraform.io";
+export declare const OPENTOFU_REGISTRY = "registry.opentofu.org";
+/** Every provider in a lock file, by its full address, with its version. */
+export declare function readLock(text: string): Map<string, string>;
+/** The repo's lock files, as `/`-separated paths relative to the repo, sorted. */
+export declare function lockFiles(repo: string): string[];
+/** One provider one lock file pins. */
+export interface LockEntry {
+    /** The lock file, relative to the repo. */
+    lock: string;
+    address: string;
+    version: string;
+}
+/** Every provider every lock file pins. */
+export declare function lockEntries(repo: string, files?: string[]): LockEntry[];
+/** Lock files that pin the same providers at the same versions, mirrored once. */
+export interface MirrorGroup {
+    /** The lock files, relative to the repo. */
+    locks: string[];
+    /** The first lock file's text, which `providers mirror` checks downloads against. */
+    text: string;
+    /** Address to version. */
+    providers: Map<string, string>;
+}
+/** The repo's lock files grouped by what they pin; a lock file that pins nothing is left out. */
+export declare function mirrorGroups(repo: string, locks?: string[]): MirrorGroup[];
+/** A file a mirror build writes, relative to its directory. */
+export interface MirrorModuleFile {
+    path: string;
+    content: string;
+}
+export interface MirrorModuleOptions {
+    /** Directory the modules go under. Default `mirror`. */
+    dir?: string;
+    /** Also require each provider locked on registry.terraform.io or registry.opentofu.org under the other host. Default false. */
+    bothHosts?: boolean;
+}
+/** The other default host's address for a provider locked on one of them, or undefined. */
+export declare function otherHostAddress(address: string): string | undefined;
+/**
+ * One module per group: `versions.tf` holding each provider at exactly its
+ * locked version, and the lock file beside it so `providers mirror` checks the
+ * hashes. With `bothHosts`, the other default host's address is required too;
+ * the lock file does not name it, so its download is checked by that
+ * registry's signature alone.
+ */
+export declare function mirrorModules(groups: MirrorGroup[], options?: MirrorModuleOptions): MirrorModuleFile[];
+/** A platform as the binaries name it, `linux_amd64`, from that form or Docker's `linux/amd64`. */
+export declare function binaryPlatform(platform: string): string;
+/** The platform this process runs on, as the binaries name it. */
+export declare function hostPlatform(platform?: string, arch?: string): string;
+/**
+ * Whether a mirror directory holds the provider at the version for the
+ * platform, in either layout a `filesystem_mirror` reads: packed (what
+ * `providers mirror` writes, a zip per platform) or unpacked (a directory per
+ * platform).
+ */
+export declare function mirrorHas(mirror: string, address: string, version: string, platform: string): boolean;
+/** Runs the binary; a test passes its own. */
+export type MirrorRun = (bin: string, args: string[], cwd: string) => {
+    status: number | null;
+    output: string;
+};
+export interface BuildMirrorOptions {
+    /** The binary that runs `providers mirror`. Default tofu. */
+    binary?: string;
+    /** Platforms to mirror, `linux_amd64` or `linux/amd64`. Default linux_amd64. */
+    platforms?: string[];
+    /** Mirror each provider under both default hosts. Default true. */
+    bothHosts?: boolean;
+    /** The lock files to cover. Default every lock file in the repo. */
+    locks?: string[];
+    /** Where the modules are written while the binary runs. Default a new temporary directory. */
+    workDir?: string;
+    run?: MirrorRun;
+}
+export interface BuiltMirror {
+    /** The directory the mirror was written to. */
+    out: string;
+    /** The lock files covered. */
+    locks: string[];
+    /** Every provider mirrored, as `address version`, sorted. */
+    providers: string[];
+    platforms: string[];
+}
+export declare class MirrorBuildError extends Error {
+    constructor(message: string);
+}
+/**
+ * Runs `providers mirror` over every lock file's group into `out`, then
+ * rewrites each `index.json` from the version files present, so groups that
+ * mirror different versions of one provider all show.
+ */
+export declare function buildMirror(repo: string, out: string, options?: BuildMirrorOptions): BuiltMirror;
+/** The store a mirror is uploaded to: a registry's write store, with an optional existence check so archives already there are skipped. */
+export type MirrorUploadStore = Pick<RegistryWriteStore, "put" | "read"> & {
+    has?(key: string): Promise<boolean>;
+};
+export interface UploadMirrorOptions {
+    /** The registry's prefix in its store; the mirror goes under `<prefix>/providers/`. */
+    prefix?: string;
+}
+export interface UploadedMirror {
+    /** Keys written. */
+    put: string[];
+    /** Archive keys left as they were, already in the store. */
+    kept: string[];
+}
+/** The key a mirror file goes to. */
+export declare const mirrorKey: (prefix: string | undefined, path: string) => string;
+/**
+ * Uploads a built mirror: archives, then each `<version>.json`, then each
+ * `index.json` merged with the versions the store's copy already lists, so a
+ * reader never sees an index naming a version whose files are not there yet.
+ */
+export declare function uploadMirror(store: MirrorUploadStore, dir: string, options?: UploadMirrorOptions): Promise<UploadedMirror>;
+/** The mirror's URL under a registry's base URL, ending in `/`. */
+export declare const mirrorUrl: (registryUrl: string, prefix?: string) => string;
+/**
+ * The CLI config block users add: the mirrored providers come only from the
+ * mirror, and everything else directly from its registry. `include` keeps
+ * the mirror from being asked for a provider it lacks, and `exclude` keeps a
+ * mirrored provider from going direct.
+ */
+export declare function mirrorCliConfig(url: string, addresses: string[]): string;
+//# sourceMappingURL=mirror.d.ts.map

package/dist/registry/mirror.d.ts.map

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