euredact 0.5.1 → 0.7.0

package/dist/esm/cloud/client.js

@@ -1,11 +1,15 @@
 /**
  * [CLOUD EXTENSION] The cloud client.
  *
- * Speaks to the euRedact inference service: a deterministic rules engine
- * followed by a fine-tuned model asked only *what did the rules miss?* The
- * service returns both the redacted document and located spans, so this
+ * Speaks to the euRedact inference service: a fine-tuned model asked only
+ * *what did the rules miss?* The service returns located spans, so this
  * module's job is transport and translation, not detection.
  *
+ * It sends the text it is given, as given. `redactAsync(text, { mode: "cloud" })`
+ * is what runs the rules engine first and hands this client only the masked
+ * text; call the client directly and whatever you pass is what leaves the
+ * machine. The spans that come back index the text that was sent.
+ *
  * Three things it hides from the caller:
  *
  * - **Whether the document finished inside the service's sync window.** A short
@@ -20,12 +24,14 @@
  * Zero dependencies, like the rest of the package: this uses the platform's
  * own `fetch`.
  */
-import { getConfig, } from "./config.js";
-import { CloudError, NotConfiguredError, QuotaExceededError, TooLargeError, } from "./errors.js";
+import { getConfig, requireSecureBaseUrl, } from "./config.js";
+import { CloudError, NotConfiguredError, NotFoundError, QuotaExceededError, RateLimitedError, ResultExpiredError, TooLargeError, } from "./errors.js";
 import { canonicalType, DetectionSource, EntityType, } from "../types.js";
-const RETRY_STATUS = new Set([429, 500, 502, 503, 504]);
+/** @internal Shared with cloud/account.ts. */
+export const RETRY_STATUS = new Set([429, 500, 502, 503, 504]);
 const MAX_BACKOFF_MS = 30_000;
-function requireFetch(supplied) {
+/** @internal */
+export function requireFetch(supplied) {
     const impl = supplied ?? globalThis.fetch;
     if (typeof impl !== "function") {
         throw new NotConfiguredError("the cloud tier needs a global fetch. Node 18+ provides one; on Node 16 " +
@@ -33,10 +39,12 @@ function requireFetch(supplied) {
     }
     return impl;
 }
-function sleep(ms) {
+/** @internal */
+export function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
-function retryAfterMs(headers) {
+/** @internal */
+export function retryAfterMs(headers) {
     const raw = headers?.get("Retry-After");
     if (!raw)
         return null;
@@ -48,12 +56,14 @@ function retryAfterMs(headers) {
  * Full jitter. A synchronised retry storm from many clients is how a
  * recovering service is knocked back over.
  */
-function backoffMs(attempt, retryAfter) {
+/** @internal */
+export function backoffMs(attempt, retryAfter) {
     if (retryAfter !== null)
         return Math.min(retryAfter, MAX_BACKOFF_MS);
     return Math.min(MAX_BACKOFF_MS, Math.random() * 2 ** attempt * 1000);
 }
-function uuid() {
+/** @internal */
+export function uuid() {
     const c = globalThis.crypto;
     if (c && typeof c.randomUUID === "function")
         return c.randomUUID();
@@ -80,7 +90,8 @@ function toEntityType(raw) {
  * Returns the identity when the text has none, which is the common case and
  * costs one regex test.
  */
-function codePointOffsets(text) {
+/** @internal Shared with cloud/batches.ts. */
+export function codePointOffsets(text) {
     if (!/[\uD800-\uDBFF]/.test(text))
         return cp => cp;
     const units = [];
@@ -92,7 +103,98 @@ function codePointOffsets(text) {
     units.push(i);
     return cp => units[Math.min(cp, units.length - 1)];
 }
-function toResult(payload, text) {
+/** @internal */
+export function isInteger(value) {
+    return typeof value === "number" && Number.isInteger(value);
+}
+/**
+ * The `usage` block, or undefined when absent or malformed. Shared rules with
+ * the Python SDK (`conformance/cloud_usage.json`): `tokens` and `credits` are
+ * integers, `billing_rate` a number, `factors` a list whose entries carry a
+ * string `code`. Anything else there drops the whole block rather than
+ * reporting a cost nobody can trust; unknown keys are ignored.
+ * @internal Exported for the conformance test.
+ */
+export function toUsage(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const u = raw;
+    if (!isInteger(u.tokens) || !isInteger(u.credits) || typeof u.billing_rate !== "number"
+        || !Array.isArray(u.factors))
+        return undefined;
+    const factors = [];
+    for (const f of u.factors) {
+        if (f === null || typeof f !== "object" || Array.isArray(f))
+            return undefined;
+        const r = f;
+        if (typeof r.code !== "string")
+            return undefined;
+        const factor = { code: r.code, detail: typeof r.detail === "string" ? r.detail : "" };
+        if (Array.isArray(r.types))
+            factor.types = r.types.filter((t) => typeof t === "string");
+        factors.push(factor);
+    }
+    return { tokens: u.tokens, billingRate: u.billing_rate, credits: u.credits, factors };
+}
+function str(value) {
+    return typeof value === "string" ? value : null;
+}
+/**
+ * The service's account of a request beside its spans. Shared rules with the
+ * Python SDK (`conformance/cloud_result.json`): a field of the wrong type reads
+ * as absent, and an unlocated entry without string `text` is skipped.
+ * @internal
+ */
+export function toCloudInfo(payload) {
+    const unlocated = [];
+    for (const item of Array.isArray(payload.unlocated) ? payload.unlocated : []) {
+        if (item && typeof item === "object" && typeof item.text === "string") {
+            const t = item.type;
+            unlocated.push({
+                text: item.text,
+                entityType: toEntityType(typeof t === "string" ? t : "OTHER"),
+            });
+        }
+    }
+    const usage = toUsage(payload.usage);
+    return {
+        jobId: str(payload.job_id),
+        modelVersion: str(payload.model_version),
+        ...(usage ? { usage } : {}),
+        unlocated,
+    };
+}
+/**
+ * A 429 from the gateway's daily quota rather than the edge's rate limit: the
+ * gateway answers in JSON with `detail.used` and `detail.limit`; nginx in HTML.
+ * @internal
+ */
+export function isQuota(payload) {
+    const detail = payload.detail;
+    return !!detail && typeof detail === "object" && "limit" in detail && "used" in detail;
+}
+/** The error for a non-success answer. @internal Shared with batches and account. */
+export function cloudErrorFor(status, payload) {
+    const message = typeof payload.error === "string" ? payload.error : `HTTP ${status}`;
+    const detail = (payload.detail && typeof payload.detail === "object"
+        ? payload.detail : {});
+    if (status === 401)
+        return new CloudError(`authentication failed: ${message}`, status);
+    if (status === 404)
+        return new NotFoundError(message, status, detail);
+    if (status === 410)
+        return new ResultExpiredError(message, status, detail);
+    if (status === 413)
+        return new TooLargeError(message, status, detail);
+    if (status === 429) {
+        return isQuota(payload)
+            ? new QuotaExceededError(message, status, detail)
+            : new RateLimitedError("rate limited by the service (HTTP 429); try again shortly", status, detail);
+    }
+    return new CloudError(message, status, detail);
+}
+/** @internal Shared with cloud/batches.ts. */
+export function toResult(payload, text) {
     const offset = codePointOffsets(text);
     const detections = (payload.entities ?? []).map(span => ({
         entityType: toEntityType(span.type),
@@ -101,7 +203,9 @@ function toResult(payload, text) {
         text: span.text,
         source: span.source === "model" ? DetectionSource.CLOUD : DetectionSource.RULES,
         country: null,
-        confidence: span.confidence ?? "high",
+        // A model span carries no evidence of its own: the service's confidence
+        // when it sends one, never an invented "high" (rules-engine#108).
+        confidence: span.source === "model" ? (span.confidence ?? null) : (span.confidence ?? "high"),
     }));
     detections.sort((a, b) => a.start - b.start || b.end - a.end);
     return {
@@ -114,6 +218,7 @@ function toResult(payload, text) {
         detectionMode: "declared",
         tokens: {},
         exempted: [],
+        cloud: toCloudInfo(payload),
     };
 }
 export class CloudClient {
@@ -122,6 +227,8 @@ export class CloudClient {
         const resolved = config ?? getConfig();
         if (resolved === null)
             throw new NotConfiguredError();
+        // A config built by hand bypasses configure(), so check it here too.
+        requireSecureBaseUrl(resolved.baseUrl);
         this.config = resolved;
     }
     headers(idempotencyKey) {
@@ -135,15 +242,7 @@ export class CloudClient {
         };
     }
     raiseFor(status, payload) {
-        const message = payload.error ?? `HTTP ${status}`;
-        const detail = payload.detail ?? {};
-        if (status === 401)
-            throw new CloudError(`authentication failed: ${message}`, status);
-        if (status === 413)
-            throw new TooLargeError(message, status, detail);
-        if (status === 429)
-            throw new QuotaExceededError(message, status, detail);
-        throw new CloudError(message, status, detail);
+        throw cloudErrorFor(status, payload);
     }
     async redact(text, options) {
         const doFetch = requireFetch(options.fetchImpl);
@@ -153,7 +252,6 @@ export class CloudClient {
             country: options.country.toUpperCase(),
             language: options.language ?? "",
             priority: options.priority ?? "interactive",
-            rules_only: options.rulesOnly ?? false,
         });
         let attempt = 0;
         for (;;) {
@@ -183,7 +281,8 @@ export class CloudClient {
                 }
                 if (response.status === 200)
                     return toResult(payload, text);
-                if (!RETRY_STATUS.has(response.status) || attempt >= this.config.maxRetries) {
+                if (!RETRY_STATUS.has(response.status) || attempt >= this.config.maxRetries
+                    || (response.status === 429 && isQuota(payload))) {
                     this.raiseFor(response.status, payload);
                 }
             }
@@ -228,7 +327,8 @@ export class CloudClient {
         }
     }
 }
-async function readJson(response) {
+/** @internal */
+export async function readJson(response) {
     try {
         const data = await response.json();
         return data && typeof data === "object" ? data : {};

package/dist/esm/cloud/config.d.ts

@@ -30,6 +30,12 @@ export interface ConfigureOptions {
     maxRetries?: number;
     headers?: Record<string, string>;
 }
+/**
+ * Refuse a cloud address that would not use TLS. The API key and the text sent
+ * must travel encrypted; plain `http` is allowed only to a loopback host, for a
+ * local gateway or a TLS-terminating proxy on the same machine (rules-engine#86).
+ */
+export declare function requireSecureBaseUrl(baseUrl: string): void;
 /**
  * Configure the cloud tier.
  *

package/dist/esm/cloud/config.js

@@ -13,6 +13,29 @@ export const DEFAULT_TIMEOUT_MS = 90_000;
  */
 export const DEFAULT_POLL_TIMEOUT_MS = 900_000;
 export const DEFAULT_MAX_RETRIES = 3;
+/** Hosts a plain-HTTP base URL may name: a gateway or TLS proxy on this machine. */
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
+/**
+ * Refuse a cloud address that would not use TLS. The API key and the text sent
+ * must travel encrypted; plain `http` is allowed only to a loopback host, for a
+ * local gateway or a TLS-terminating proxy on the same machine (rules-engine#86).
+ */
+export function requireSecureBaseUrl(baseUrl) {
+    // Parsed by hand rather than with `URL`: a runtime without that global would
+    // otherwise refuse every address, https included, with a misleading message.
+    const m = /^([a-z][a-z0-9+.-]*):\/\/(?:[^@/?#]*@)?(\[[^\]]*\]|[^:/?#]*)/i.exec(baseUrl);
+    if (m !== null) {
+        const scheme = m[1].toLowerCase();
+        const host = m[2].toLowerCase();
+        if (scheme === "https" && host)
+            return;
+        if (scheme === "http" && LOOPBACK_HOSTS.has(host))
+            return;
+    }
+    throw new Error(`refusing cloud base URL ${JSON.stringify(baseUrl)}: it must start with https:// ` +
+        "(plain http:// is allowed only to localhost, 127.0.0.1 or ::1), because the " +
+        "API key and document text would otherwise travel unencrypted");
+}
 let config = null;
 /** Read an env var where there is an environment to read. Browsers have none. */
 function env(name) {
@@ -30,10 +53,12 @@ export function configure(options = {}) {
     if (!apiKey) {
         throw new Error("no API key: pass configure({ apiKey }) or set EUREDACT_API_KEY");
     }
+    const baseUrl = (options.baseUrl ?? env("EUREDACT_BASE_URL") ?? DEFAULT_BASE_URL)
+        .replace(/\/+$/, "");
+    requireSecureBaseUrl(baseUrl);
     config = {
         apiKey,
-        baseUrl: (options.baseUrl ?? env("EUREDACT_BASE_URL") ?? DEFAULT_BASE_URL)
-            .replace(/\/+$/, ""),
+        baseUrl,
         timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
         pollTimeoutMs: options.pollTimeoutMs ?? DEFAULT_POLL_TIMEOUT_MS,
         maxRetries: options.maxRetries ?? DEFAULT_MAX_RETRIES,

package/dist/esm/cloud/errors.d.ts

@@ -16,10 +16,35 @@ export declare class CloudError extends Error {
 export declare class NotConfiguredError extends CloudError {
     constructor(message?: string);
 }
-/** 429 after retries were exhausted. */
+/**
+ * 429: the account's daily document quota is used up. Thrown at once, not
+ * after retries: the gateway's quota answer (JSON with `detail.used` and
+ * `detail.limit`) will not change before the day does (rules-engine#89).
+ */
 export declare class QuotaExceededError extends CloudError {
     constructor(message: string, status?: number, detail?: Record<string, unknown>);
 }
+/**
+ * 429 from the edge's rate limit, still there after every retry. It clears
+ * within seconds, so it is retried with backoff first. A subclass of
+ * `QuotaExceededError`, which is what every 429 threw before the two were told apart.
+ */
+export declare class RateLimitedError extends QuotaExceededError {
+    constructor(message: string, status?: number, detail?: Record<string, unknown>);
+}
+/** 404: no such job, batch or key -- or another account's, which the service
+ *  deliberately does not distinguish. */
+export declare class NotFoundError extends CloudError {
+    constructor(message: string, status?: number, detail?: Record<string, unknown>);
+}
+/**
+ * 410: the job succeeded, but its result is no longer retained -- swept by the
+ * account's retention period, or discarded on delivery under no-retention. An
+ * empty result here would read like a document with no personal data in it.
+ */
+export declare class ResultExpiredError extends CloudError {
+    constructor(message: string, status?: number, detail?: Record<string, unknown>);
+}
 /**
  * 413. The document is over the service's input cap.
  *

package/dist/esm/cloud/errors.js

@@ -26,13 +26,47 @@ export class NotConfiguredError extends CloudError {
         this.name = "NotConfiguredError";
     }
 }
-/** 429 after retries were exhausted. */
+/**
+ * 429: the account's daily document quota is used up. Thrown at once, not
+ * after retries: the gateway's quota answer (JSON with `detail.used` and
+ * `detail.limit`) will not change before the day does (rules-engine#89).
+ */
 export class QuotaExceededError extends CloudError {
     constructor(message, status, detail) {
         super(message, status, detail);
         this.name = "QuotaExceededError";
     }
 }
+/**
+ * 429 from the edge's rate limit, still there after every retry. It clears
+ * within seconds, so it is retried with backoff first. A subclass of
+ * `QuotaExceededError`, which is what every 429 threw before the two were told apart.
+ */
+export class RateLimitedError extends QuotaExceededError {
+    constructor(message, status, detail) {
+        super(message, status, detail);
+        this.name = "RateLimitedError";
+    }
+}
+/** 404: no such job, batch or key -- or another account's, which the service
+ *  deliberately does not distinguish. */
+export class NotFoundError extends CloudError {
+    constructor(message, status, detail) {
+        super(message, status, detail);
+        this.name = "NotFoundError";
+    }
+}
+/**
+ * 410: the job succeeded, but its result is no longer retained -- swept by the
+ * account's retention period, or discarded on delivery under no-retention. An
+ * empty result here would read like a document with no personal data in it.
+ */
+export class ResultExpiredError extends CloudError {
+    constructor(message, status, detail) {
+        super(message, status, detail);
+        this.name = "ResultExpiredError";
+    }
+}
 /**
  * 413. The document is over the service's input cap.
  *

package/dist/esm/cloud/index.d.ts

@@ -15,5 +15,7 @@
  * ```
  */
 export { CloudClient, type CloudRedactOptions } from "./client.js";
-export { configure, getConfig, reset, DEFAULT_BASE_URL, type CloudConfig, type ConfigureOptions, } from "./config.js";
-export { CloudError, NotConfiguredError, QuotaExceededError, TooLargeError, } from "./errors.js";
+export { Account, Jobs, type AccountSummary, type ApiClientOptions, type ApiKey, type CreditEntry, type Credits, type Job, type KeyRevocation, type KeyUsage, type UsageDay, } from "./account.js";
+export { Batches, BatchError, MAX_DOCUMENTS, MAX_CUSTOM_ID, CUSTOM_ID, MAX_BODY_BYTES, MAX_DOCUMENT_TOKENS, type Batch, type BatchDocument, type BatchResults, type BatchStore, type BatchesOptions, type Cipher, type DocumentOutcome, } from "./batches.js";
+export { configure, getConfig, reset, requireSecureBaseUrl, DEFAULT_BASE_URL, type CloudConfig, type ConfigureOptions, } from "./config.js";
+export { CloudError, NotConfiguredError, NotFoundError, QuotaExceededError, RateLimitedError, ResultExpiredError, TooLargeError, } from "./errors.js";

package/dist/esm/cloud/index.js

@@ -15,5 +15,7 @@
  * ```
  */
 export { CloudClient } from "./client.js";
-export { configure, getConfig, reset, DEFAULT_BASE_URL, } from "./config.js";
-export { CloudError, NotConfiguredError, QuotaExceededError, TooLargeError, } from "./errors.js";
+export { Account, Jobs, } from "./account.js";
+export { Batches, BatchError, MAX_DOCUMENTS, MAX_CUSTOM_ID, CUSTOM_ID, MAX_BODY_BYTES, MAX_DOCUMENT_TOKENS, } from "./batches.js";
+export { configure, getConfig, reset, requireSecureBaseUrl, DEFAULT_BASE_URL, } from "./config.js";
+export { CloudError, NotConfiguredError, NotFoundError, QuotaExceededError, RateLimitedError, ResultExpiredError, TooLargeError, } from "./errors.js";

package/dist/esm/index.d.ts

@@ -1,10 +1,10 @@
 export { EntityType, DetectionSource, LEGACY_TYPE_ALIASES, canonicalType } from "./types.js";
-export type { Detection, Exemption, RedactResult, PatternDef, CountryConfig, CountryEvidence } from "./types.js";
+export type { CloudInfo, Detection, Exemption, RedactResult, Unlocated, Usage, UsageFactor, PatternDef, CountryConfig, CountryEvidence } from "./types.js";
 export { DocumentContext } from "./rules/context.js";
 export { EuRedact, restore, type RedactOptions } from "./sdk.js";
 export { COUNTRY_CONFIGS } from "./rules/countries/index.js";
 export { setBicRegistry, getBicRegistry, SEED_BIC6_PREFIXES, type BicRegistryProvider } from "./rules/bicRegistry.js";
-export { configure, getConfig, CloudClient, CloudError, NotConfiguredError, QuotaExceededError, TooLargeError, type CloudConfig, type ConfigureOptions, type CloudRedactOptions, } from "./cloud/index.js";
+export { configure, getConfig, Account, CloudClient, CloudError, Batches, BatchError, CUSTOM_ID, Jobs, NotConfiguredError, NotFoundError, QuotaExceededError, RateLimitedError, ResultExpiredError, TooLargeError, type AccountSummary, type ApiKey, type CreditEntry, type Credits, type Job, type KeyRevocation, type KeyUsage, type UsageDay, type CloudConfig, type ConfigureOptions, type CloudRedactOptions, type Batch, type BatchDocument, type BatchResults, type BatchStore, type BatchesOptions, type Cipher, type DocumentOutcome, } from "./cloud/index.js";
 import { type RedactOptions } from "./sdk.js";
 import type { RedactResult } from "./types.js";
 export declare function availableCountries(): string[];

package/dist/esm/index.js

@@ -3,7 +3,7 @@ export { DocumentContext } from "./rules/context.js";
 export { EuRedact, restore } from "./sdk.js";
 export { COUNTRY_CONFIGS } from "./rules/countries/index.js";
 export { setBicRegistry, getBicRegistry, SEED_BIC6_PREFIXES } from "./rules/bicRegistry.js";
-export { configure, getConfig, CloudClient, CloudError, NotConfiguredError, QuotaExceededError, TooLargeError, } from "./cloud/index.js";
+export { configure, getConfig, Account, CloudClient, CloudError, Batches, BatchError, CUSTOM_ID, Jobs, NotConfiguredError, NotFoundError, QuotaExceededError, RateLimitedError, ResultExpiredError, TooLargeError, } from "./cloud/index.js";
 import { EuRedact } from "./sdk.js";
 import { COUNTRY_CONFIGS } from "./rules/countries/index.js";
 let _instance = null;

package/dist/esm/platform.browser.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `platform.ts` for browsers: no `node:` imports, so the package bundles for a
+ * page. Selected by the `browser` field in package.json (rules-engine#56).
+ *
+ * The cache key is computed synchronously and must stay collision-resistant
+ * (see `ResultCache.key`), and Web Crypto's `subtle.digest` is asynchronous, so
+ * SHA-256 is implemented here. A test checks it against `node:crypto` byte for
+ * byte, astral characters and lone surrogates included.
+ */
+/** Hex SHA-256 of the UTF-8 encoding of `parts`, joined with nothing between. */
+export declare function sha256Hex(parts: string[]): string;
+/**
+ * A uniformly random integer in `[0, n)`, from `crypto.getRandomValues`.
+ * Rejection sampling: a plain modulo would favour the low residues.
+ */
+export declare function randomIndex(n: number): number;
+/** Mirrors `PlatformBatchStore` in platform.ts (rules-engine#84). */
+export interface PlatformBatchStore {
+    read(batchId: string): Promise<Uint8Array | null>;
+    write(batchId: string, data: Uint8Array): Promise<void>;
+    delete(batchId: string): Promise<void>;
+    list(): Promise<string[]>;
+}
+/** A page has no filesystem: the caller passes `store` to `Batches`. */
+export declare function defaultBatchStore(_directory?: string): PlatformBatchStore | null;
+/** No synchronous gzip in a page; the batch is uploaded uncompressed. */
+export declare function gzip(_data: Uint8Array): Uint8Array | null;

package/dist/esm/platform.browser.js

@@ -0,0 +1,92 @@
+/**
+ * `platform.ts` for browsers: no `node:` imports, so the package bundles for a
+ * page. Selected by the `browser` field in package.json (rules-engine#56).
+ *
+ * The cache key is computed synchronously and must stay collision-resistant
+ * (see `ResultCache.key`), and Web Crypto's `subtle.digest` is asynchronous, so
+ * SHA-256 is implemented here. A test checks it against `node:crypto` byte for
+ * byte, astral characters and lone surrogates included.
+ */
+const K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+/** Hex SHA-256 of the UTF-8 encoding of `parts`, joined with nothing between. */
+export function sha256Hex(parts) {
+    // TextEncoder replaces a lone surrogate with U+FFFD, as Node's hash.update does.
+    const bytes = new TextEncoder().encode(parts.join(""));
+    const bitLength = bytes.length * 8;
+    const padded = new Uint8Array(((bytes.length + 9 + 63) >> 6) << 6);
+    padded.set(bytes);
+    padded[bytes.length] = 0x80;
+    const view = new DataView(padded.buffer);
+    view.setUint32(padded.length - 8, Math.floor(bitLength / 0x100000000));
+    view.setUint32(padded.length - 4, bitLength >>> 0);
+    const h = new Uint32Array([
+        0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+    ]);
+    const w = new Uint32Array(64);
+    for (let offset = 0; offset < padded.length; offset += 64) {
+        for (let i = 0; i < 16; i++)
+            w[i] = view.getUint32(offset + i * 4);
+        for (let i = 16; i < 64; i++) {
+            const a = w[i - 15], b = w[i - 2];
+            const s0 = ((a >>> 7) | (a << 25)) ^ ((a >>> 18) | (a << 14)) ^ (a >>> 3);
+            const s1 = ((b >>> 17) | (b << 15)) ^ ((b >>> 19) | (b << 13)) ^ (b >>> 10);
+            w[i] = (w[i - 16] + s0 + w[i - 7] + s1) >>> 0;
+        }
+        let [a, b, c, d, e, f, g, hh] = h;
+        for (let i = 0; i < 64; i++) {
+            const S1 = ((e >>> 6) | (e << 26)) ^ ((e >>> 11) | (e << 21)) ^ ((e >>> 25) | (e << 7));
+            const ch = (e & f) ^ (~e & g);
+            const t1 = (hh + S1 + ch + K[i] + w[i]) >>> 0;
+            const S0 = ((a >>> 2) | (a << 30)) ^ ((a >>> 13) | (a << 19)) ^ ((a >>> 22) | (a << 10));
+            const maj = (a & b) ^ (a & c) ^ (b & c);
+            const t2 = (S0 + maj) >>> 0;
+            hh = g;
+            g = f;
+            f = e;
+            e = (d + t1) >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) >>> 0;
+        }
+        h[0] = (h[0] + a) >>> 0;
+        h[1] = (h[1] + b) >>> 0;
+        h[2] = (h[2] + c) >>> 0;
+        h[3] = (h[3] + d) >>> 0;
+        h[4] = (h[4] + e) >>> 0;
+        h[5] = (h[5] + f) >>> 0;
+        h[6] = (h[6] + g) >>> 0;
+        h[7] = (h[7] + hh) >>> 0;
+    }
+    return Array.from(h, x => x.toString(16).padStart(8, "0")).join("");
+}
+/**
+ * A uniformly random integer in `[0, n)`, from `crypto.getRandomValues`.
+ * Rejection sampling: a plain modulo would favour the low residues.
+ */
+export function randomIndex(n) {
+    const limit = Math.floor(0x100000000 / n) * n;
+    const buf = new Uint32Array(1);
+    for (;;) {
+        globalThis.crypto.getRandomValues(buf);
+        if (buf[0] < limit)
+            return buf[0] % n;
+    }
+}
+/** A page has no filesystem: the caller passes `store` to `Batches`. */
+export function defaultBatchStore(_directory) {
+    return null;
+}
+/** No synchronous gzip in a page; the batch is uploaded uncompressed. */
+export function gzip(_data) {
+    return null;
+}

package/dist/esm/platform.d.ts

@@ -0,0 +1,20 @@
+/** Hex SHA-256 of the UTF-8 encoding of `parts`, joined with nothing between. */
+export declare function sha256Hex(parts: string[]): string;
+/** A uniformly random integer in `[0, n)`. */
+export declare function randomIndex(n: number): number;
+/** Where a local batch file lives (rules-engine#84). Mirrors `BatchStore` in
+ *  cloud/batches.ts; declared here so this module imports nothing from there. */
+export interface PlatformBatchStore {
+    read(batchId: string): Promise<Uint8Array | null>;
+    write(batchId: string, data: Uint8Array): Promise<void>;
+    delete(batchId: string): Promise<void>;
+    list(): Promise<string[]>;
+}
+/**
+ * `<dir>/<batchId>.json`, directory `0700`, files `0600`, the default local
+ * batch store. Writes go to a temporary file in the same directory, created
+ * `0600` before any byte is written, then renamed over the old one.
+ */
+export declare function defaultBatchStore(directory?: string): PlatformBatchStore | null;
+/** Gzip, for the batch upload. */
+export declare function gzip(data: Uint8Array): Uint8Array | null;