@intentius/chant-lexicon-terraform 0.124.54 → 0.124.56

package/src/registry/targets/zip.ts

@@ -0,0 +1,287 @@
+/**
+ * The zip of an attested module archive (chant#4605, terragucci#1299 ruling
+ * A). Artifactory takes a module only as a zip and Nexus recommends one, so
+ * their targets upload the same files the bucket registry's `.tar.gz`
+ * carries, at the same paths with the same modes, repacked as a zip. Nothing
+ * is added to or dropped from the module.
+ *
+ * The repack is deterministic: entries keep the tarball's order and mtimes,
+ * so one archive always gives the same zip bytes. The zip's archive comment
+ * carries the attested content digest and the revision
+ * (`chant-module content=sha256:<hex> revision=<sha>`), which is how a
+ * target's `held` tells, from the zip a host gives back, which attested
+ * archive it was made from. A zip with no such comment (one uploaded by
+ * hand) is judged by its own digest, so it never passes for the release's.
+ *
+ * No zip64: an archive past 4 GiB or 65535 entries is refused, far above
+ * either host's limit (Nexus takes 100 MB per module).
+ */
+import { deflateRawSync, gunzipSync, inflateRawSync } from "node:zlib";
+import { PublishTargetError } from "@intentius/chant/lifecycle/release-publish";
+
+/** One entry of a module tarball. */
+export interface ModuleArchiveEntry {
+  path: string;
+  type: "file" | "dir";
+  mode: number;
+  /** Seconds since the epoch. */
+  mtime: number;
+  data: Buffer;
+}
+
+const field = (b: Buffer, at: number, len: number): string => {
+  const raw = b.subarray(at, at + len);
+  const end = raw.indexOf(0);
+  return raw.subarray(0, end < 0 ? raw.length : end).toString("utf-8");
+};
+const octal = (b: Buffer, at: number, len: number): number => parseInt(field(b, at, len).trim() || "0", 8);
+
+function paxRecords(data: Buffer): Record<string, string> {
+  const out: Record<string, string> = {};
+  let at = 0;
+  while (at < data.length) {
+    const space = data.indexOf(0x20, at);
+    if (space < 0) break;
+    const len = parseInt(data.subarray(at, space).toString("utf-8"), 10);
+    if (!Number.isFinite(len) || len <= 0) break;
+    const record = data.subarray(space + 1, at + len - 1).toString("utf-8");
+    const eq = record.indexOf("=");
+    if (eq > 0) out[record.slice(0, eq)] = record.slice(eq + 1);
+    at += len;
+  }
+  return out;
+}
+
+const invalid = (message: string) => new PublishTargetError("publish-archive-invalid", message, "Publish the .tar.gz the bucket registry serves, with the module's files at its root.");
+
+/**
+ * The entries of a module's gzip tarball (ustar, pax and GNU long names), with
+ * `./` cut from each path. A link or a device in the archive is refused: a
+ * zip of the module could not carry it as the tarball does.
+ */
+export function moduleArchiveEntries(archive: Uint8Array): ModuleArchiveEntry[] {
+  let tar: Buffer;
+  try {
+    tar = gunzipSync(archive);
+  } catch {
+    throw invalid("the module archive is not a gzip tarball");
+  }
+  const out: ModuleArchiveEntry[] = [];
+  let at = 0;
+  let pax: Record<string, string> = {};
+  let longName: string | undefined;
+  while (at + 512 <= tar.length) {
+    const header = tar.subarray(at, at + 512);
+    if (header.every((b) => b === 0)) break;
+    const size = octal(header, 124, 12);
+    const flag = String.fromCharCode(header[156] || 0x30);
+    const data = tar.subarray(at + 512, at + 512 + size);
+    at += 512 + Math.ceil(size / 512) * 512;
+    if (flag === "x") {
+      pax = paxRecords(data);
+      continue;
+    }
+    if (flag === "L") {
+      longName = field(data, 0, data.length);
+      continue;
+    }
+    if (flag === "g") continue;
+    const prefix = field(header, 345, 155);
+    const raw = pax.path ?? longName ?? (prefix ? `${prefix}/${field(header, 0, 100)}` : field(header, 0, 100));
+    const mtime = pax.mtime ? Math.floor(Number(pax.mtime)) : octal(header, 136, 12);
+    pax = {};
+    longName = undefined;
+    const path = raw.replace(/^(\.\/)+/, "").replace(/\/+$/, "");
+    if (!path || path === ".") continue;
+    if (path.startsWith("/") || path.split("/").includes("..")) throw invalid(`the module archive holds ${raw}, outside its root`);
+    const type = flag === "0" || flag === "\0" || flag === "7" ? "file" : flag === "5" ? "dir" : undefined;
+    if (!type) throw invalid(`the module archive holds ${path}, which is not a regular file or a directory; a zip of the module cannot carry it`);
+    out.push({ path, type, mode: octal(header, 100, 8) & 0o7777, mtime, data: type === "file" ? Buffer.from(data) : Buffer.alloc(0) });
+  }
+  return out;
+}
+
+const CRC_TABLE = (() => {
+  const t = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    t[n] = c >>> 0;
+  }
+  return t;
+})();
+
+/** The CRC-32 a zip entry carries. */
+export function crc32(data: Uint8Array): number {
+  let c = 0xffffffff;
+  for (let i = 0; i < data.length; i++) c = CRC_TABLE[(c ^ data[i]!) & 0xff]! ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+/** MS-DOS date and time, as a zip entry keeps them, in UTC and clamped to 1980. */
+function dosTime(seconds: number): { time: number; date: number } {
+  const d = new Date(Math.max(seconds * 1000, Date.UTC(1980, 0, 1)));
+  return {
+    time: (d.getUTCHours() << 11) | (d.getUTCMinutes() << 5) | Math.floor(d.getUTCSeconds() / 2),
+    date: ((d.getUTCFullYear() - 1980) << 9) | ((d.getUTCMonth() + 1) << 5) | d.getUTCDate(),
+  };
+}
+
+/** The archive comment that names the attested archive a zip was made from. */
+export const ZIP_COMMENT_PREFIX = "chant-module";
+
+export const moduleZipComment = (content: string, revision?: string): string => `${ZIP_COMMENT_PREFIX} content=${content}${revision ? ` revision=${revision}` : ""}`;
+
+/** The content and revision a zip's archive comment names, when it is one {@link moduleZipComment} wrote. */
+export function readModuleZipComment(comment: string): { content: string; revision?: string } | undefined {
+  if (!comment.startsWith(`${ZIP_COMMENT_PREFIX} `)) return undefined;
+  const content = /(?:^| )content=(sha256:[0-9a-f]{64})(?: |$)/.exec(comment)?.[1];
+  if (!content) return undefined;
+  const revision = /(?:^| )revision=([^ ]+)(?: |$)/.exec(comment)?.[1];
+  return { content, ...(revision ? { revision } : {}) };
+}
+
+/** A zip of the given entries, with `comment` as its archive comment. Files are deflated. */
+export function zipOf(entries: readonly ModuleArchiveEntry[], comment = ""): Buffer {
+  if (entries.length > 0xffff) throw invalid(`the module archive holds ${entries.length} entries; a zip without zip64 holds 65535`);
+  const locals: Buffer[] = [];
+  const centrals: Buffer[] = [];
+  let offset = 0;
+  for (const e of entries) {
+    const name = Buffer.from(e.type === "dir" ? `${e.path}/` : e.path, "utf-8");
+    const data = e.type === "file" ? e.data : Buffer.alloc(0);
+    const packed = e.type === "file" ? deflateRawSync(data, { level: 9 }) : Buffer.alloc(0);
+    const method = e.type === "file" ? 8 : 0;
+    const crc = crc32(data);
+    const { time, date } = dosTime(e.mtime);
+    if (packed.length > 0xfffffffe || data.length > 0xfffffffe || offset > 0xfffffffe) throw invalid("the module archive is past 4 GiB; a zip without zip64 holds less");
+
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(0x04034b50, 0);
+    local.writeUInt16LE(20, 4);
+    local.writeUInt16LE(0x0800, 6);
+    local.writeUInt16LE(method, 8);
+    local.writeUInt16LE(time, 10);
+    local.writeUInt16LE(date, 12);
+    local.writeUInt32LE(crc, 14);
+    local.writeUInt32LE(packed.length, 18);
+    local.writeUInt32LE(data.length, 22);
+    local.writeUInt16LE(name.length, 26);
+    local.writeUInt16LE(0, 28);
+    locals.push(local, name, packed);
+
+    const unixMode = (e.type === "dir" ? 0o040000 : 0o100000) | (e.mode & 0o7777 || (e.type === "dir" ? 0o755 : 0o644));
+    const central = Buffer.alloc(46);
+    central.writeUInt32LE(0x02014b50, 0);
+    central.writeUInt16LE((3 << 8) | 20, 4);
+    central.writeUInt16LE(20, 6);
+    central.writeUInt16LE(0x0800, 8);
+    central.writeUInt16LE(method, 10);
+    central.writeUInt16LE(time, 12);
+    central.writeUInt16LE(date, 14);
+    central.writeUInt32LE(crc, 16);
+    central.writeUInt32LE(packed.length, 20);
+    central.writeUInt32LE(data.length, 24);
+    central.writeUInt16LE(name.length, 28);
+    central.writeUInt16LE(0, 30);
+    central.writeUInt16LE(0, 32);
+    central.writeUInt16LE(0, 34);
+    central.writeUInt16LE(0, 36);
+    central.writeUInt32LE(((unixMode << 16) | (e.type === "dir" ? 0x10 : 0)) >>> 0, 38);
+    central.writeUInt32LE(offset, 42);
+    centrals.push(central, name);
+    offset += local.length + name.length + packed.length;
+  }
+  const cd = Buffer.concat(centrals);
+  const note = Buffer.from(comment, "utf-8");
+  if (note.length > 0xffff) throw invalid("the zip comment is longer than a zip carries");
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(0x06054b50, 0);
+  end.writeUInt16LE(0, 4);
+  end.writeUInt16LE(0, 6);
+  end.writeUInt16LE(entries.length, 8);
+  end.writeUInt16LE(entries.length, 10);
+  end.writeUInt32LE(cd.length, 12);
+  end.writeUInt32LE(offset, 16);
+  end.writeUInt16LE(note.length, 20);
+  return Buffer.concat([...locals, cd, end, note]);
+}
+
+/**
+ * The zip a hosted target uploads for an attested archive: its entries,
+ * repacked, with the content digest and revision in the archive comment.
+ */
+export function moduleZip(archive: Uint8Array, content: string, revision?: string): Buffer {
+  return zipOf(moduleArchiveEntries(archive), moduleZipComment(content, revision));
+}
+
+/** A zip read back: its archive comment and its entries' paths, modes and bytes. */
+export interface ReadZip {
+  comment: string;
+  entries: { path: string; dir: boolean; mode: number; data: Buffer }[];
+}
+
+/** Reads a zip's central directory and entries. Throws on bytes that are not a zip. */
+export function readZip(bytes: Uint8Array): ReadZip {
+  const b = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  let end = -1;
+  for (let i = b.length - 22; i >= Math.max(0, b.length - 22 - 0xffff); i--) {
+    if (b.readUInt32LE(i) === 0x06054b50) {
+      end = i;
+      break;
+    }
+  }
+  if (end < 0) throw new Error("not a zip archive: no end of central directory");
+  const count = b.readUInt16LE(end + 10);
+  const cdOffset = b.readUInt32LE(end + 16);
+  const comment = b.subarray(end + 22, end + 22 + b.readUInt16LE(end + 20)).toString("utf-8");
+  const entries: ReadZip["entries"] = [];
+  let at = cdOffset;
+  for (let n = 0; n < count; n++) {
+    if (b.readUInt32LE(at) !== 0x02014b50) throw new Error("not a zip archive: a bad central directory entry");
+    const method = b.readUInt16LE(at + 10);
+    const csize = b.readUInt32LE(at + 20);
+    const nameLen = b.readUInt16LE(at + 28);
+    const extraLen = b.readUInt16LE(at + 30);
+    const commentLen = b.readUInt16LE(at + 32);
+    const external = b.readUInt32LE(at + 38);
+    const local = b.readUInt32LE(at + 42);
+    const name = b.subarray(at + 46, at + 46 + nameLen).toString("utf-8");
+    at += 46 + nameLen + extraLen + commentLen;
+    if (b.readUInt32LE(local) !== 0x04034b50) throw new Error(`not a zip archive: no local header for ${name}`);
+    const start = local + 30 + b.readUInt16LE(local + 26) + b.readUInt16LE(local + 28);
+    const packed = b.subarray(start, start + csize);
+    const data = method === 0 ? Buffer.from(packed) : method === 8 ? inflateRawSync(packed) : undefined;
+    if (!data) throw new Error(`${name}: zip method ${method} is not read here`);
+    const dir = name.endsWith("/");
+    entries.push({ path: dir ? name.slice(0, -1) : name, dir, mode: (external >>> 16) & 0o7777, data });
+  }
+  return { comment, entries };
+}
+
+const isGzip = (b: Uint8Array) => b.length >= 2 && b[0] === 0x1f && b[1] === 0x8b;
+const isZip = (b: Uint8Array) => b.length >= 4 && b[0] === 0x50 && b[1] === 0x4b;
+
+/**
+ * The content a module archive a host gave back carries, as `held` reports
+ * it: the attested digest a chant zip's comment names; for a gzip tarball,
+ * the digest of its uncompressed bytes, as the bucket registry keeps it; for
+ * any other bytes, their own digest.
+ */
+export function heldContentOf(bytes: Uint8Array, digest: (b: Uint8Array) => string): { content: string; revision?: string } {
+  if (isZip(bytes)) {
+    try {
+      const named = readModuleZipComment(readZip(bytes).comment);
+      if (named) return named;
+    } catch {
+      // Not a zip after all: judged by its own digest below.
+    }
+  } else if (isGzip(bytes)) {
+    try {
+      return { content: digest(gunzipSync(bytes)) };
+    } catch {
+      // A broken gzip: judged by its own digest below.
+    }
+  }
+  return { content: digest(bytes) };
+}

package/src/registry/writer.ts

@@ -0,0 +1,155 @@
+/**
+ * The module registry protocol, written as files a bucket, a directory or a
+ * Pages site holds (https://opentofu.org/docs/internals/module-registry-protocol/):
+ *
+ *   .well-known/terraform.json                  {"modules.v1": "/v1/modules/"}
+ *   v1/modules/<ns>/<name>/<system>/versions     every version, oldest first
+ *   v1/modules/<ns>/<name>/<system>/<v>/download {"location": ...}
+ *   v1/modules/<ns>/<name>/<system>/<v>/<name>-<v>.tar.gz   a tarball download
+ *   v1/modules/<ns>/<name>/<system>/<v>/release.json        the commit and content digest
+ *
+ * The download answer the two CLIs need is a 200 with the JSON body and an
+ * `X-Terraform-Get` header naming the same location (terragucci#1287).
+ * Terraform reads only the header (hashicorp/terraform
+ * internal/registry/client.go:237-250 at v1.14.9 and v1.15.8). OpenTofu reads
+ * the body's `location` first and the header when it is empty
+ * (opentofu/opentofu internal/registry/client.go:205-237 at v1.12.5 and
+ * v1.13.1). A stored file carries no header, so the stored `download` file is
+ * the body, and whatever serves it (`downloadAnswer`, the loopback handler in
+ * ./serve, an edge function) adds the header from that body.
+ *
+ * The writer takes the store it writes to, so the bucket clients stay with
+ * whoever owns them (chant#4554 moves terragucci's into core).
+ */
+// The errors module alone, never the object-store index: its clients import Node built-ins, and the
+// edge function (./edge) reaches this file for the download answer (chant#4589).
+import { isStoreConflict, type StoreCondition } from "@intentius/chant/object-store/errors";
+import { DISCOVERY, MODULES_V1, keyFor, type RegistryAddress } from "./address";
+import { compareSemver, formatSemver, parseSemver, type Semver } from "./semver";
+
+/** The header Terraform takes a module's location from. */
+export const DOWNLOAD_HEADER = "X-Terraform-Get";
+
+/** The files a registry is written to: a bucket client, a directory, or a test's map. */
+export interface RegistryWriteStore {
+  /** Writes one object. With `when`, the write must fail with a conflict when the condition no longer holds. */
+  put(key: string, body: string | Buffer, contentType?: string, when?: StoreCondition): Promise<unknown>;
+  /** One object's body and version tag, or `{}` when there is none. */
+  read(key: string): Promise<{ body?: string; etag?: string }>;
+}
+
+/** The service discovery document. */
+export const discoveryDoc = (): string => `${JSON.stringify({ "modules.v1": MODULES_V1 })}\n`;
+
+/** The protocol's versions answer, oldest first, duplicates and non-versions dropped. */
+export function versionsDoc(versions: string[]): string {
+  // Dedupe after formatting, so "v1.0.0" and "1.0.0" are one version.
+  const parsed = versions.map((v) => parseSemver(v)).filter((v): v is Semver => !!v);
+  const sorted = [...new Set(parsed.sort(compareSemver).map(formatSemver))];
+  return `${JSON.stringify({ modules: [{ versions: sorted.map((version) => ({ version })) }] }, null, 2)}\n`;
+}
+
+/** The versions a versions answer lists, or none when it is missing or not the protocol's JSON. */
+export function readVersions(text: string | undefined): string[] {
+  if (!text) return [];
+  try {
+    const doc = JSON.parse(text) as { modules?: { versions?: { version?: unknown }[] }[] };
+    return (doc.modules?.[0]?.versions ?? []).map((v) => v.version).filter((v): v is string => typeof v === "string");
+  } catch {
+    return [];
+  }
+}
+
+/** A version's download answer body: the JSON OpenTofu reads. */
+export function downloadDoc(location: string): string {
+  return `${JSON.stringify({ location })}\n`;
+}
+
+/** The location a download body names, or undefined when it names none. */
+export function downloadLocation(body: string | undefined): string | undefined {
+  if (!body) return undefined;
+  try {
+    const location = (JSON.parse(body) as { location?: unknown }).location;
+    return typeof location === "string" && location ? location : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** A download answer as a server sends it. */
+export interface DownloadAnswer {
+  status: 200;
+  headers: Record<string, string>;
+  body: string;
+}
+
+/**
+ * The download answer both CLIs install from: status 200, the JSON body with
+ * `location`, and `X-Terraform-Get` naming the same location.
+ */
+export function downloadAnswer(location: string): DownloadAnswer {
+  return { status: 200, headers: { "content-type": "application/json", [DOWNLOAD_HEADER]: location }, body: downloadDoc(location) };
+}
+
+/** The headers a stored download body is served with, or undefined when the body names no location. */
+export function downloadHeaders(body: string | undefined): Record<string, string> | undefined {
+  const location = downloadLocation(body);
+  return location ? downloadAnswer(location).headers : undefined;
+}
+
+/** True for a `.../v1/modules/<ns>/<name>/<system>/<version>/download` path, with or without a leading prefix. */
+export const isDownloadPath = (path: string): boolean => /(^|\/)v1\/modules\/[^/]+\/[^/]+\/[^/]+\/[^/]+\/download$/.test(path.split("?")[0]!);
+
+/** What the registry keeps beside a version, so the next publish knows what it holds. */
+export interface ReleaseMeta {
+  module: string;
+  version: string;
+  revision: string;
+  content: string;
+  location: string;
+}
+
+/** The registry's files for one version, written in this order: the version is listed last, once all it points at is there. */
+export interface VersionFiles {
+  tarball?: { key: string; body: Buffer };
+  download: { key: string; body: string };
+  meta: { key: string; body: string };
+}
+
+export interface WriteVersionOptions {
+  /** The registry's prefix in its store. */
+  prefix?: string;
+  /**
+   * Whether an error from `put` is a lost conditional write, to be retried.
+   * By default chant's `StoreConflict`, or any error named `StoreConflict`
+   * (a store from another package with a class of its own).
+   */
+  isConflict?: (e: unknown) => boolean;
+  /** Conditional retries on the versions file before the conflict is thrown. Default 3. */
+  retries?: number;
+}
+
+/** Writes one version: discovery when it differs, the tarball, the download answer, release.json, then the versions list. */
+export async function writeVersion(store: RegistryWriteStore, addr: RegistryAddress, version: Semver, files: VersionFiles, options: WriteVersionOptions = {}): Promise<void> {
+  const discovery = discoveryDoc();
+  const discoKey = keyFor(options.prefix, DISCOVERY);
+  const disco = await store.read(discoKey);
+  if (disco.body !== discovery) await store.put(discoKey, discovery, "application/json");
+  if (files.tarball) await store.put(files.tarball.key, files.tarball.body, "application/gzip");
+  await store.put(files.download.key, files.download.body, "application/json");
+  await store.put(files.meta.key, files.meta.body, "application/json");
+  const key = keyFor(options.prefix, `${addr.path}/versions`);
+  const isConflict = options.isConflict ?? isStoreConflict;
+  const retries = options.retries ?? 3;
+  // Read, add, write only over the copy read: two publishes at once cannot drop each other's version.
+  for (let attempt = 0; ; attempt++) {
+    const held = await store.read(key);
+    const when: StoreCondition | undefined = held.body === undefined ? { ifNoneMatch: "*" } : held.etag ? { ifMatch: held.etag } : undefined;
+    try {
+      await store.put(key, versionsDoc([...readVersions(held.body), formatSemver(version)]), "application/json", when);
+      return;
+    } catch (e) {
+      if (!isConflict(e) || attempt >= retries) throw e;
+    }
+  }
+}

package/src/state/azure-blob.ts

@@ -1,223 +1,8 @@
 /**
- * Azure Blob Storage for an azurerm backend's state, over its REST API with
- * `fetch` and `node:crypto`: a blob's properties and metadata, its text, a
- * write (under a lease when one holds it), a snapshot, a delete, and the
- * blob lease the backend locks a state with.
- *
- * Requests are signed with Shared Key for an account key, carry a SAS as it
- * is, or carry a storage token the job's OIDC identity is traded for at Entra
- * ID (a client assertion, the way the azurerm backend does it).
- *
- * Lifted from terragucci's `report/azure-blob.ts` (c493e0e), without SAS
- * links, version reads and version listing.
+ * The Azure Blob Storage client an azurerm backend's state uses: chant
+ * core's (#4554, `@intentius/chant/object-store`): a blob's properties and
+ * metadata, a snapshot, a block blob put, and the blob lease the backend
+ * locks a state with, signed with Shared Key, a SAS, or an Entra token for
+ * the job's OIDC identity.
  */
-import { createHmac } from "node:crypto";
-import { readFileSync } from "node:fs";
-import { defaultFetch, encodePath, StoreError, xmlText, type StoreFetch } from "./object-store";
-
-/** The REST version every request names. */
-export const AZURE_VERSION = "2021-08-06";
-
-/** Entra ID's public cloud. */
-export const AZURE_AUTHORITY = "https://login.microsoftonline.com";
-
-const STORAGE_SCOPE = "https://storage.azure.com/.default";
-
-export interface AzureLocation {
-  account: string;
-  container: string;
-  /** The account's blob endpoint, no trailing slash: https://<account>.blob.core.windows.net, or an emulator's http://host:10000/<account>. */
-  endpoint: string;
-}
-
-/** The job's federated identity: an Entra app or managed identity that trusts the forge's token. */
-export interface AzureOidc {
-  tenantId: string;
-  clientId: string;
-  tokenFile: string;
-  /** Entra ID's address, https://host, no path. */
-  authority: string;
-}
-
-export type AzureTarget = AzureLocation & ({ accountKey: string } | { oidc: AzureOidc } | { sas: string });
-
-/** A blob's properties, as a HEAD answers them: never its body. */
-export interface BlobHead {
-  exists: boolean;
-  etag?: string;
-  /** x-ms-lease-state: `leased` while a lease holds it. */
-  leaseState?: string;
-  /** Its metadata, by name without the x-ms-meta- prefix. */
-  metadata: Record<string, string>;
-}
-
-const hmac64 = (key: string, s: string): string => createHmac("sha256", Buffer.from(key, "base64")).update(s, "utf8").digest("base64");
-
-/** The headers whose values Shared Key signs by position, in order. */
-const SIGNED = ["content-encoding", "content-language", "content-length", "content-md5", "content-type", "date", "if-modified-since", "if-match", "if-none-match", "if-unmodified-since", "range"];
-
-/** The Shared Key Authorization header for a request. */
-export function sharedKey(account: string, accountKey: string, method: string, rawUrl: string, headers: Record<string, string>): string {
-  const url = new URL(rawUrl);
-  const h = Object.fromEntries(Object.entries(headers).map(([k, v]) => [k.toLowerCase(), v]));
-  const fixed = SIGNED.map((n) => (n === "content-length" && h[n] === "0" ? "" : (h[n] ?? "")));
-  const ms = Object.keys(h).filter((n) => n.startsWith("x-ms-")).sort().map((n) => `${n}:${h[n]!.trim()}\n`).join("");
-  const params = new Map<string, string[]>();
-  for (const [k, v] of url.searchParams) params.set(k.toLowerCase(), [...(params.get(k.toLowerCase()) ?? []), v]);
-  const query = [...params.keys()].sort().map((k) => `\n${k}:${params.get(k)!.sort().join(",")}`).join("");
-  const toSign = [method, ...fixed].join("\n") + "\n" + ms + `/${account}${url.pathname}` + query;
-  return `SharedKey ${account}:${hmac64(accountKey, toSign)}`;
-}
-
-/** Entra ID's error, or the start of the body. */
-const why = (text: string): string => {
-  try {
-    const j = JSON.parse(text) as { error?: string; error_description?: string };
-    if (j.error) return [j.error, j.error_description?.split("\r\n")[0]].filter(Boolean).join(": ");
-  } catch {
-    // Not JSON: Blob Storage answers in XML.
-  }
-  return [xmlText(text, "Code"), xmlText(text, "Message")?.split("\n")[0]].filter(Boolean).join(": ") || text.slice(0, 300);
-};
-
-export class AzureBlobClient {
-  private token?: Promise<{ token: string; expires: number }>;
-
-  constructor(readonly target: AzureTarget, private readonly fetchFn: StoreFetch = defaultFetch, private readonly readToken: (file: string) => string = (f) => readFileSync(f, "utf-8")) {}
-
-  private where(key: string): string {
-    return `az://${this.target.account}/${this.target.container}/${key}`;
-  }
-
-  private blobUrl(key: string, query = ""): string {
-    const t = this.target;
-    const q = [query, "sas" in t ? t.sas.replace(/^\?/, "") : ""].filter(Boolean).join("&");
-    return `${t.endpoint}/${t.container}/${encodePath(key)}${q ? `?${q}` : ""}`;
-  }
-
-  /** The storage token for the OIDC identity: once per client, again a minute before it expires. */
-  private async bearer(o: AzureOidc): Promise<string> {
-    const fetchToken = async (): Promise<{ token: string; expires: number }> => {
-      let assertion: string;
-      try {
-        assertion = this.readToken(o.tokenFile).trim();
-      } catch (e) {
-        throw new StoreError(`cannot read the OIDC token in ${o.tokenFile}: ${(e as Error).message}`);
-      }
-      if (!assertion) throw new StoreError(`the OIDC token file ${o.tokenFile} is empty`);
-      const body = new URLSearchParams({
-        client_id: o.clientId,
-        scope: STORAGE_SCOPE,
-        grant_type: "client_credentials",
-        client_assertion_type: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
-        client_assertion: assertion,
-      }).toString();
-      const res = await this.fetchFn(`${o.authority}/${o.tenantId}/oauth2/v2.0/token`, { method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" }, body });
-      const text = await res.text();
-      if (!res.ok) throw new StoreError(`Entra ID refused the OIDC token for client ${o.clientId}: ${res.status} ${why(text)}`);
-      let j: { access_token?: string; expires_in?: number | string } = {};
-      try {
-        j = JSON.parse(text) as typeof j;
-      } catch {
-        // Reported below as no token.
-      }
-      if (!j.access_token) throw new StoreError(`Entra ID answered client ${o.clientId} without a token`);
-      return { token: j.access_token, expires: Date.now() + Number(j.expires_in ?? 3600) * 1000 };
-    };
-    const again = (): Promise<{ token: string; expires: number }> =>
-      (this.token = fetchToken().catch((e: unknown) => {
-        this.token = undefined;
-        throw e;
-      }));
-    let held = await (this.token ?? again());
-    if (held.expires - Date.now() < 60_000) held = await again();
-    return held.token;
-  }
-
-  /** The headers for one request, signed or with the bearer token. */
-  private async headers(method: string, url: string, extra: Record<string, string>): Promise<Record<string, string>> {
-    const h: Record<string, string> = { "x-ms-date": new Date().toUTCString(), "x-ms-version": AZURE_VERSION, ...extra };
-    const t = this.target;
-    if ("accountKey" in t) return { ...h, authorization: sharedKey(t.account, t.accountKey, method, url, h) };
-    if ("sas" in t) return h;
-    return { ...h, authorization: `Bearer ${await this.bearer(t.oidc)}` };
-  }
-
-  async get(key: string): Promise<string | undefined> {
-    const url = this.blobUrl(key);
-    const res = await this.fetchFn(url, { method: "GET", headers: await this.headers("GET", url, {}) });
-    if (res.status === 404) return undefined;
-    if (!res.ok) throw new StoreError(`GET ${this.where(key)}: ${res.status} ${why(await res.text())}`);
-    return res.text();
-  }
-
-  /** A blob's properties and metadata, from a HEAD. */
-  async head(key: string): Promise<BlobHead> {
-    const url = this.blobUrl(key);
-    const res = await this.fetchFn(url, { method: "HEAD", headers: await this.headers("HEAD", url, {}) });
-    if (res.status === 404) return { exists: false, metadata: {} };
-    if (!res.ok) throw new StoreError(`HEAD ${this.where(key)}: ${res.status}`);
-    const get = (n: string): string | undefined => res.headers?.get(n) ?? undefined;
-    const metadata: Record<string, string> = {};
-    const all = res.headers as unknown as { forEach?: (fn: (v: string, k: string) => void) => void } | undefined;
-    all?.forEach?.((v, k) => {
-      if (k.toLowerCase().startsWith("x-ms-meta-")) metadata[k.toLowerCase().slice("x-ms-meta-".length)] = v;
-    });
-    const etag = get("etag");
-    const leaseState = get("x-ms-lease-state");
-    return { exists: true, ...(etag ? { etag } : {}), ...(leaseState ? { leaseState } : {}), metadata };
-  }
-
-  /** Take a snapshot of a blob: its id, the time Azure gives it. */
-  async snapshot(key: string): Promise<string> {
-    const url = this.blobUrl(key, "comp=snapshot");
-    const res = await this.fetchFn(url, { method: "PUT", headers: await this.headers("PUT", url, { "content-length": "0" }) });
-    if (!res.ok) throw new StoreError(`snapshot of ${this.where(key)}: ${res.status} ${why(await res.text())}`);
-    const id = res.headers?.get("x-ms-snapshot");
-    if (!id) throw new StoreError(`snapshot of ${this.where(key)}: Azure answered without x-ms-snapshot`);
-    return id;
-  }
-
-  /** Write a block blob with metadata, under a lease when one holds it; with `ifNoneMatch`, only when there is none (false when one was there). */
-  async putBlob(key: string, body: string, contentType: string, options: { leaseId?: string; metadata?: Record<string, string>; ifNoneMatch?: boolean } = {}): Promise<boolean> {
-    const url = this.blobUrl(key);
-    const meta = Object.fromEntries(Object.entries(options.metadata ?? {}).map(([k, v]) => [`x-ms-meta-${k}`, v]));
-    const extra: Record<string, string> = {
-      "x-ms-blob-type": "BlockBlob",
-      "content-type": contentType,
-      "content-length": String(Buffer.byteLength(body)),
-      ...meta,
-      ...(options.leaseId ? { "x-ms-lease-id": options.leaseId } : {}),
-      ...(options.ifNoneMatch ? { "if-none-match": "*" } : {}),
-    };
-    const res = await this.fetchFn(url, { method: "PUT", headers: await this.headers("PUT", url, extra), body });
-    if (options.ifNoneMatch && (res.status === 409 || res.status === 412)) return false;
-    if (!res.ok) throw new StoreError(`PUT ${this.where(key)}: ${res.status} ${why(await res.text())}`);
-    return true;
-  }
-
-  /** Delete a blob. One that is not there is deleted already. */
-  async remove(key: string): Promise<void> {
-    const url = this.blobUrl(key);
-    const res = await this.fetchFn(url, { method: "DELETE", headers: await this.headers("DELETE", url, {}) });
-    if (!res.ok && res.status !== 404) throw new StoreError(`DELETE ${this.where(key)}: ${res.status} ${why(await res.text())}`);
-  }
-
-  /** A blob lease: acquire one that never expires with the id given (false when one holds it), or release it. */
-  async lease(key: string, action: "acquire" | "release", id: string): Promise<boolean> {
-    const url = this.blobUrl(key, "comp=lease");
-    const extra: Record<string, string> = { "x-ms-lease-action": action, "content-length": "0", ...(action === "acquire" ? { "x-ms-lease-duration": "-1", "x-ms-proposed-lease-id": id } : { "x-ms-lease-id": id }) };
-    const res = await this.fetchFn(url, { method: "PUT", headers: await this.headers("PUT", url, extra) });
-    if (action === "acquire" && res.status === 409) return false;
-    if (!res.ok) throw new StoreError(`${action} the lease of ${this.where(key)}: ${res.status} ${why(await res.text())}`);
-    return true;
-  }
-
-  /** Set a blob's metadata, all of it, under its lease when one holds it. */
-  async setMetadata(key: string, metadata: Record<string, string>, leaseId?: string): Promise<void> {
-    const url = this.blobUrl(key, "comp=metadata");
-    const extra = { "content-length": "0", ...Object.fromEntries(Object.entries(metadata).map(([k, v]) => [`x-ms-meta-${k}`, v])), ...(leaseId ? { "x-ms-lease-id": leaseId } : {}) };
-    const res = await this.fetchFn(url, { method: "PUT", headers: await this.headers("PUT", url, extra) });
-    if (!res.ok) throw new StoreError(`set the metadata of ${this.where(key)}: ${res.status} ${why(await res.text())}`);
-  }
-}
+export { AZURE_AUTHORITY, AZURE_VERSION, AzureBlobClient, sharedKey, type AzureLocation, type AzureOidc, type AzureTarget, type BlobHead } from "@intentius/chant/object-store";