@serfab/cadre-core 0.9.0 → 0.10.0

package/dist/formation-approval.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Everything ONE approval is bound to — the five fields inside the approver's signed digest
+ * (see `formationVouchMessage`), plus the hook to ask.
+ *
+ * Every field is fixed BEFORE the hook is contacted: the JOINER mints the nonce (and signs its
+ * own consent over it) before its contact message is sent, and the redeeming node knows the
+ * strand, the joiner's key, and the disclosure text it is about to write. That ordering is
+ * what makes the resulting signature usable — an approval signed over a nonce the node did not
+ * insert fails `FormationUsage.Authorized` at commit.
+ */
+export interface FormationApprovalRequest {
+    /** Invitation token being redeemed. */
+    token: string;
+    /** Single-use nonce for THIS redemption, already minted by the JOINING peer. */
+    usageStampId: string;
+    /** The strand (network) being joined. */
+    strandId: string;
+    /** The joining peer's own ed25519 public key (written to `FormationUsage.PeerKey`). */
+    peerKey: string;
+    /**
+     * The EXACT text that will be written to `FormationUsage.Disclosure`. The approver signs
+     * these bytes verbatim and MUST NOT re-serialize them — the redeeming node computes this
+     * string once and uses the identical string for both the signature and the insert.
+     */
+    disclosure: string;
+    /**
+     * The invite's `ValidationUrl` (the hook to contact). NOT part of the signed digest: it says
+     * where to ask, not what is being approved.
+     */
+    validationUrl: string;
+}
+/**
+ * The five signed fields on their own — what `formationVouchMessage` consumes, and the exact
+ * JSON body posted to the hook. Derived from {@link FormationApprovalRequest} by subtraction so
+ * a field added to the request must be consciously routed here (or the build breaks) rather
+ * than silently dropping out of the digest.
+ *
+ * This is what an APPROVER receives: a hook is posted these five fields and nothing else, so it
+ * has no `validationUrl` to supply and should type its request body as this, not as the full
+ * {@link FormationApprovalRequest}.
+ */
+export type FormationVouchFields = Omit<FormationApprovalRequest, 'validationUrl'>;
+/** An approver's answer: which key vouched, and its signature over the request's digest. */
+export interface FormationApproval {
+    /** Public key the approval claims; must match an enrolled `ValidationKey` row. */
+    validationKey: string;
+    /** base64url ed25519 signature over `formationVouchMessage(request)`. */
+    validationSignature: string;
+}
+/**
+ * Something that can obtain an approval for a redemption. The HTTP hook
+ * ({@link createHttpFormationApprover}) is the production implementation; tests and embedded
+ * deployments can supply their own.
+ *
+ * Rejects with a {@link FormationApprovalError} — never resolves to a "no". A caller that
+ * receives a resolved {@link FormationApproval} may still find it does not verify; use
+ * {@link verifyFormationApproval} before writing.
+ */
+export interface FormationApprover {
+    /**
+     * `signal` is the caller's cancellation (the formation responder's work budget expiring):
+     * a pre-aborted or mid-flight abort rejects with an `unavailable`
+     * {@link FormationApprovalError} without (further) contacting the hook. Optional so
+     * signal-unaware implementations stay assignable.
+     */
+    requestApproval(request: FormationApprovalRequest, signal?: AbortSignal): Promise<FormationApproval>;
+}
+/**
+ * Why an approval could not be obtained. The cases route differently: `refused` is a
+ * final answer, `unavailable` may succeed on a later attempt, and `malformed` /
+ * `unenrolled` / `misconfigured` are operator errors that retrying never fixes.
+ *
+ * `unenrolled` is thrown by the redeeming node's LOCAL enrollment pre-check (the recorder
+ * asking its control database whether the approval's key is an enrolled `ValidationKey`
+ * row), never by the HTTP client — a hook cannot know or report it.
+ */
+export type FormationApprovalFailure = 
+/** The hook answered, and the answer is no. */
+'refused'
+/** Could not get an answer (network error, timeout, non-2xx status, redirect). */
+ | 'unavailable'
+/** Got an answer that is not a usable approval (not JSON, missing/blank fields, oversized). */
+ | 'malformed'
+/** The approval's `validationKey` is not an enrolled `ValidationKey` row (local pre-check). */
+ | 'unenrolled'
+/** The `ValidationUrl` or the runtime is unusable (bad scheme, no `fetch`). */
+ | 'misconfigured';
+/**
+ * Failure to obtain an approval, carrying the {@link FormationApprovalFailure} category the
+ * caller switches on to pick the rejection reason a would-be joiner is told.
+ */
+export declare class FormationApprovalError extends Error {
+    readonly failure: FormationApprovalFailure;
+    constructor(failure: FormationApprovalFailure, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Approver side: produce the approval for a request. Used by tests, and by anyone writing a
+ * hook in TypeScript.
+ *
+ * `privateKeyB64`'s public half must be the key enrolled as the `ValidationKey` row the
+ * redeeming node's control database will verify against — pass that same public key as
+ * `validationKey` (derive it with `ed25519PublicKeyFromPrivate` if you only hold the seed).
+ * Signing with a key that is not enrolled produces a perfectly valid signature that the
+ * database still rejects.
+ *
+ * Takes the five signed fields, not a full {@link FormationApprovalRequest}: an approver is
+ * posted only those five and has no `validationUrl` to hand back. A redeeming node holding a
+ * whole request can still pass it straight in.
+ *
+ * @param fields - The redemption being approved (the five signed fields).
+ * @param validationKey - base64url ed25519 public key that this approval claims.
+ * @param privateKeyB64 - base64url 32-byte ed25519 seed to sign with.
+ */
+export declare function signFormationApproval(fields: FormationVouchFields, validationKey: string, privateKeyB64: string): FormationApproval;
+/**
+ * Redeeming side: does this approval actually verify against the bytes we are about to write?
+ *
+ * A LOCAL PRE-CHECK, not the authority. It turns a bad approval into a legible rejection
+ * instead of an opaque `CHECK constraint failed: Authorized` at commit, and it catches the
+ * ordinary drift case (the hook signed a different nonce/strand/peer than the one we hold).
+ * It cannot substitute for the database check: this verifies against the key the approval
+ * itself names, whereas `FormationUsage.Authorized` verifies against the STORED
+ * `ValidationKey` row — which is what stops a redeemer approving itself with a key of its own
+ * choosing.
+ *
+ * Returns a boolean and never throws (same contract as `verifyPeerAuthorization`): malformed
+ * base64url, a garbage key, or any crypto failure resolves to `false`, logged at debug.
+ */
+export declare function verifyFormationApproval(fields: FormationVouchFields, approval: FormationApproval): boolean;
+/**
+ * Ask an outside approval service, over HTTP, whether a would-be joiner may redeem an
+ * invitation. Contacted by the INVITING party's node (the formation responder) during
+ * redemption — never by the joiner, which neither mints the nonce nor performs the write.
+ *
+ * Wire contract (documented for hook operators in `docs/api.md`):
+ *
+ * - `POST <ValidationUrl>`, `content-type: application/json`, `accept: application/json`.
+ * - Body is exactly the five signed fields — `{ token, usageStampId, strandId, peerKey,
+ *   disclosure }` — and nothing else. No owner keys, no bootstrap addresses, no membership
+ *   keys ever reach the hook.
+ * - `200` with `{ "validationKey": "...", "validationSignature": "..." }` is an approval.
+ * - `401` / `403` is a refusal; any other non-2xx, a network error, a timeout, or a redirect
+ *   is `unavailable`; a 2xx that is not a usable approval is `malformed`.
+ *
+ * Cross-platform by construction: global `fetch` + `AbortController` only, no `node:` imports.
+ */
+export declare function createHttpFormationApprover(options?: {
+    /**
+     * Abort the request after this long, INCLUDING the body read. Default 10s. Must stay under
+     * the responder's provisioning budget — a hook that stalls must not stall formation.
+     */
+    timeoutMs?: number;
+    /** Injectable for tests / non-standard runtimes. Defaults to `globalThis.fetch`. */
+    fetchImpl?: typeof fetch;
+}): FormationApprover;

package/dist/formation-approval.js

@@ -0,0 +1,375 @@
+import debug from 'debug';
+import { concat as uint8ArrayConcat, fromString as uint8ArrayFromString, toString as uint8ArrayToString } from 'uint8arrays';
+import { sign, verify } from '@optimystic/quereus-plugin-crypto';
+import { formationVouchMessage } from './control-database.js';
+const log = debug('sereus:cadre:formation-approval');
+/** Abort an unanswered approval request after this long when no `timeoutMs` is supplied. */
+const DEFAULT_TIMEOUT_MS = 10000;
+/**
+ * Largest approval response body this client will read (64 KiB). An approval is two short
+ * base64url strings; anything approaching this is a broken or hostile hook, and reading it
+ * unbounded would let that hook stream a redeeming node out of memory mid-formation.
+ */
+const MAX_RESPONSE_BYTES = 64 * 1024;
+/**
+ * Failure to obtain an approval, carrying the {@link FormationApprovalFailure} category the
+ * caller switches on to pick the rejection reason a would-be joiner is told.
+ */
+export class FormationApprovalError extends Error {
+    constructor(failure, message, options) {
+        super(message, options);
+        this.failure = failure;
+        this.name = 'FormationApprovalError';
+    }
+}
+/**
+ * The five fields the approver signs, lifted out of the request. Written as an explicit
+ * destructure (not a spread-and-delete) so the object posted to the hook can never pick up a
+ * field the digest does not cover — in particular the `validationUrl`.
+ */
+function vouchFields(request) {
+    const { token, usageStampId, strandId, peerKey, disclosure } = request;
+    return { token, usageStampId, strandId, peerKey, disclosure };
+}
+/**
+ * Approver side: produce the approval for a request. Used by tests, and by anyone writing a
+ * hook in TypeScript.
+ *
+ * `privateKeyB64`'s public half must be the key enrolled as the `ValidationKey` row the
+ * redeeming node's control database will verify against — pass that same public key as
+ * `validationKey` (derive it with `ed25519PublicKeyFromPrivate` if you only hold the seed).
+ * Signing with a key that is not enrolled produces a perfectly valid signature that the
+ * database still rejects.
+ *
+ * Takes the five signed fields, not a full {@link FormationApprovalRequest}: an approver is
+ * posted only those five and has no `validationUrl` to hand back. A redeeming node holding a
+ * whole request can still pass it straight in.
+ *
+ * @param fields - The redemption being approved (the five signed fields).
+ * @param validationKey - base64url ed25519 public key that this approval claims.
+ * @param privateKeyB64 - base64url 32-byte ed25519 seed to sign with.
+ */
+export function signFormationApproval(fields, validationKey, privateKeyB64) {
+    const validationSignature = sign(formationVouchMessage(fields), privateKeyB64, 'ed25519', 'bytes', 'base64url', 'base64url');
+    return { validationKey, validationSignature };
+}
+/**
+ * Redeeming side: does this approval actually verify against the bytes we are about to write?
+ *
+ * A LOCAL PRE-CHECK, not the authority. It turns a bad approval into a legible rejection
+ * instead of an opaque `CHECK constraint failed: Authorized` at commit, and it catches the
+ * ordinary drift case (the hook signed a different nonce/strand/peer than the one we hold).
+ * It cannot substitute for the database check: this verifies against the key the approval
+ * itself names, whereas `FormationUsage.Authorized` verifies against the STORED
+ * `ValidationKey` row — which is what stops a redeemer approving itself with a key of its own
+ * choosing.
+ *
+ * Returns a boolean and never throws (same contract as `verifyPeerAuthorization`): malformed
+ * base64url, a garbage key, or any crypto failure resolves to `false`, logged at debug.
+ */
+export function verifyFormationApproval(fields, approval) {
+    try {
+        return verify(formationVouchMessage(fields), approval.validationSignature, approval.validationKey, 'ed25519', 'bytes', 'base64url', 'base64url');
+    }
+    catch (error) {
+        log('verifyFormationApproval failed: %o', error);
+        return false;
+    }
+}
+/**
+ * Resolve and validate the hook URL before anything is sent.
+ *
+ * `http:` stays permitted — a self-hosted hook on a LAN is a real deployment — but note that
+ * it puts the disclosure text on the wire in clear, and lets anyone on the path see who is
+ * joining which strand. Prefer `https:` for a hook reachable off-link.
+ */
+function parseHookUrl(validationUrl) {
+    let url;
+    try {
+        url = new URL(validationUrl);
+    }
+    catch (error) {
+        throw new FormationApprovalError('misconfigured', `ValidationUrl is not a valid URL: ${validationUrl}`, { cause: error });
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new FormationApprovalError('misconfigured', `ValidationUrl scheme "${url.protocol}" is not supported; use http: or https:`);
+    }
+    return url;
+}
+/**
+ * The `fetch` this approver will call: the injected one, else the global.
+ *
+ * Bound to `globalThis` because an unbound global `fetch` is an illegal invocation in browsers
+ * (and in any runtime whose `fetch` is a branded method rather than a plain function).
+ */
+function resolveFetch(fetchImpl) {
+    if (fetchImpl) {
+        return fetchImpl;
+    }
+    if (typeof globalThis.fetch !== 'function') {
+        throw new FormationApprovalError('misconfigured', 'No fetch implementation: globalThis.fetch is missing and no fetchImpl was supplied');
+    }
+    return globalThis.fetch.bind(globalThis);
+}
+/**
+ * Read the response body as text, refusing anything over {@link MAX_RESPONSE_BYTES}.
+ *
+ * Two paths, because `Response.body` is not universally a stream (React Native's fetch has no
+ * `body` reader): stream and stop at the cap where possible, otherwise read to completion and
+ * measure. The declared `content-length` is checked first so an honest oversized response is
+ * rejected without reading it at all — but it is only a hint, so the actual bytes are counted
+ * either way.
+ *
+ * NOTE: on the no-reader path the cap is enforced only AFTER the runtime has buffered the whole
+ * body, so a hook that under-declares its `content-length` can still make that runtime hold an
+ * arbitrary amount. Harmless where it applies today (React Native clients are not formation
+ * responders); if a responder ever runs on a platform without a body reader, that path needs a
+ * real streaming read rather than a post-hoc measurement.
+ */
+async function readCappedText(response, budget) {
+    const declared = Number(response.headers.get('content-length'));
+    if (Number.isFinite(declared) && declared > MAX_RESPONSE_BYTES) {
+        throw new FormationApprovalError('malformed', `Approval response declares ${declared} bytes, over the ${MAX_RESPONSE_BYTES}-byte cap`);
+    }
+    const body = response.body;
+    if (!body || typeof body.getReader !== 'function') {
+        // NOTE: nothing releases this body when the budget wins — `text()` has already locked it and
+        // the runtime owns the buffering. It only applies to readerless-fetch runtimes (React
+        // Native), which are not formation responders; a responder on such a platform would need a
+        // real streaming read here, as the cap note above already says.
+        const text = await budget.race(response.text());
+        assertUnderCap(uint8ArrayFromString(text, 'utf8').byteLength);
+        return text;
+    }
+    return readCappedStream(body.getReader(), budget);
+}
+/** Drain a body stream, aborting the read the moment the accumulated bytes pass the cap. */
+async function readCappedStream(reader, budget) {
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            // Raced, not just aborted: a `fetch` that drops the abort leaves this read pending
+            // forever, and the budget is the only thing that ends it. The `finally` below cancels
+            // the reader, which is what actually gives the connection back.
+            const { done, value } = await budget.race(reader.read());
+            if (done) {
+                break;
+            }
+            total += value.byteLength;
+            assertUnderCap(total);
+            chunks.push(value);
+        }
+    }
+    finally {
+        // Releases the connection when we bailed early; a no-op on a fully-drained stream.
+        void reader.cancel().catch((error) => log('response cancel failed: %o', error));
+    }
+    return uint8ArrayToString(uint8ArrayConcat(chunks, total), 'utf8');
+}
+/**
+ * Release a body we are never going to read, so the runtime can put the connection back in its
+ * pool. Every failure decided from the status line (a refusal, a 5xx, a redirect) and the
+ * declared-oversize rejection throw before touching the body, and an undrained body keeps a
+ * socket checked out until GC — a node that asks a flapping hook once per redemption would
+ * accumulate them. Skips a body already locked by {@link readCappedStream}, which cancels its
+ * own reader.
+ *
+ * NOTE: awaited by `readApproval`, so it sits OUTSIDE the budget — a runtime whose `cancel()`
+ * never settles would hold the caller past `timeoutMs` even though the deadline already fired.
+ * Every runtime this ships on settles it promptly. If a request is ever seen outliving its budget
+ * despite the budget firing, stop awaiting this; the two tests that assert the body is released
+ * by the time the rejection surfaces would then have to poll instead.
+ */
+async function discardBody(response) {
+    const body = response.body;
+    if (!body || body.locked) {
+        return;
+    }
+    try {
+        await body.cancel();
+    }
+    catch (error) {
+        log('discarding unread response body failed: %o', error);
+    }
+}
+function assertUnderCap(bytes) {
+    if (bytes > MAX_RESPONSE_BYTES) {
+        throw new FormationApprovalError('malformed', `Approval response exceeds the ${MAX_RESPONSE_BYTES}-byte cap`);
+    }
+}
+/** A blank (or whitespace-only) field is as unusable as a missing one — both are `malformed`. */
+function requireField(body, field) {
+    const value = body[field];
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new FormationApprovalError('malformed', `Approval response is missing a usable "${field}"`);
+    }
+    return value;
+}
+/** Parse a 2xx body into an approval, rejecting anything that is not the documented shape. */
+function parseApproval(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        throw new FormationApprovalError('malformed', 'Approval response is not JSON', { cause: error });
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new FormationApprovalError('malformed', 'Approval response is not a JSON object');
+    }
+    const body = parsed;
+    return {
+        validationKey: requireField(body, 'validationKey'),
+        validationSignature: requireField(body, 'validationSignature')
+    };
+}
+/**
+ * Map a response's STATUS — never its body shape — onto a failure. A `403` carrying a
+ * well-formed approval is still a refusal: the hook said no, and a redeeming node that read
+ * the body anyway would let a hook accidentally approve by echoing.
+ */
+function assertApprovingStatus(response, origin) {
+    if (response.status === 401 || response.status === 403) {
+        throw new FormationApprovalError('refused', `Approval hook ${origin} refused this redemption (HTTP ${response.status})`);
+    }
+    if (!response.ok) {
+        throw new FormationApprovalError('unavailable', `Approval hook ${origin} answered HTTP ${response.status}`);
+    }
+    // Belt and braces for runtimes that ignore `redirect: 'error'` rather than rejecting.
+    if (response.redirected) {
+        throw new FormationApprovalError('unavailable', `Approval hook ${origin} redirected; re-publish the ValidationUrl instead of chasing it`);
+    }
+}
+/**
+ * Turn a response into an approval, releasing the body on every path that rejects it.
+ */
+async function readApproval(response, origin, budget) {
+    try {
+        assertApprovingStatus(response, origin);
+        return parseApproval(await readCappedText(response, budget));
+    }
+    catch (error) {
+        await discardBody(response);
+        throw error;
+    }
+}
+/**
+ * Arm the budget for one request. The caller's `signal` is relayed by hand rather than with
+ * `AbortSignal.any` (not reliably present on React Native/Hermes; this client commits to
+ * `fetch` + `AbortController` only).
+ */
+function startBudget(timeoutMs, origin, controller, signal) {
+    let expired = false;
+    let expire;
+    const deadline = new Promise((_resolve, reject) => { expire = reject; });
+    // The deadline can fire between two raced awaits, with nothing attached to it; a bare handler
+    // keeps that from surfacing as an unhandled rejection without hiding it from `race`.
+    void deadline.catch(() => { });
+    const fire = (reason) => {
+        if (expired) {
+            return;
+        }
+        expired = true;
+        // Rejected BEFORE the abort, so this reason — not whatever a fetch that DOES honour the
+        // abort rejects with — is what the race settles on. Both are queued in the same turn, and
+        // the first one queued wins.
+        expire(new FormationApprovalError('unavailable', reason));
+        // Best-effort, and no longer load-bearing: where the runtime honours it, this hands the
+        // socket back instead of leaving it checked out until GC.
+        controller.abort();
+    };
+    const timer = setTimeout(() => fire(`Approval hook ${origin} did not answer within ${timeoutMs}ms`), timeoutMs);
+    const onCallerAbort = () => fire(`Formation was cancelled while approval hook ${origin} was being asked`);
+    signal?.addEventListener('abort', onCallerAbort, { once: true });
+    return {
+        race: (work) => Promise.race([work, deadline]),
+        expired: () => expired,
+        dispose: () => {
+            // A leaked abort timer keeps a node's event loop alive.
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onCallerAbort);
+        }
+    };
+}
+/**
+ * Await the response, giving up when the budget expires — and cleaning up after ourselves if it
+ * does: a `fetch` that ignored the abort still delivers its response eventually, and an unread
+ * body keeps a connection checked out. A late rejection is logged rather than left unhandled.
+ */
+async function fetchWithinBudget(pending, budget) {
+    void pending.then((response) => {
+        if (budget.expired()) {
+            void discardBody(response);
+        }
+    }, (error) => {
+        if (budget.expired()) {
+            log('abandoned approval request rejected after its budget expired: %o', error);
+        }
+    });
+    return budget.race(pending);
+}
+/**
+ * Ask an outside approval service, over HTTP, whether a would-be joiner may redeem an
+ * invitation. Contacted by the INVITING party's node (the formation responder) during
+ * redemption — never by the joiner, which neither mints the nonce nor performs the write.
+ *
+ * Wire contract (documented for hook operators in `docs/api.md`):
+ *
+ * - `POST <ValidationUrl>`, `content-type: application/json`, `accept: application/json`.
+ * - Body is exactly the five signed fields — `{ token, usageStampId, strandId, peerKey,
+ *   disclosure }` — and nothing else. No owner keys, no bootstrap addresses, no membership
+ *   keys ever reach the hook.
+ * - `200` with `{ "validationKey": "...", "validationSignature": "..." }` is an approval.
+ * - `401` / `403` is a refusal; any other non-2xx, a network error, a timeout, or a redirect
+ *   is `unavailable`; a 2xx that is not a usable approval is `malformed`.
+ *
+ * Cross-platform by construction: global `fetch` + `AbortController` only, no `node:` imports.
+ */
+export function createHttpFormationApprover(options) {
+    const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    // A non-positive or non-finite budget would abort every request before it left, turning a
+    // config typo into a hook that appears permanently down. Fail where the mistake was made.
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        throw new FormationApprovalError('misconfigured', `timeoutMs must be a positive number of milliseconds, got ${timeoutMs}`);
+    }
+    const fetchImpl = options?.fetchImpl;
+    return {
+        async requestApproval(request, signal) {
+            const doFetch = resolveFetch(fetchImpl);
+            const url = parseHookUrl(request.validationUrl);
+            // Origin only in messages: a ValidationUrl's path/query may carry a hook secret, and
+            // these strings reach logs and the joiner's rejection reason.
+            const origin = url.origin;
+            if (signal?.aborted) {
+                throw new FormationApprovalError('unavailable', `Formation was cancelled before approval hook ${origin} was asked`);
+            }
+            const controller = new AbortController();
+            const budget = startBudget(timeoutMs, origin, controller, signal);
+            try {
+                const response = await fetchWithinBudget(doFetch(url.toString(), {
+                    method: 'POST',
+                    headers: { 'content-type': 'application/json', accept: 'application/json' },
+                    body: JSON.stringify(vouchFields(request)),
+                    redirect: 'error',
+                    signal: controller.signal
+                }), budget);
+                const approval = await readApproval(response, origin, budget);
+                log('approval obtained from %s for token %s', origin, request.token);
+                return approval;
+            }
+            catch (error) {
+                // Includes the budget's own rejection, which already carries the timeout/cancellation
+                // wording; anything else got here without the budget firing, so the hook is unreachable.
+                if (error instanceof FormationApprovalError) {
+                    throw error;
+                }
+                throw new FormationApprovalError('unavailable', `Approval hook ${origin} could not be reached`, { cause: error });
+            }
+            finally {
+                budget.dispose();
+            }
+        }
+    };
+}
+//# sourceMappingURL=formation-approval.js.map

package/dist/formation-approval.js.map

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

package/dist/fs-atomic.d.ts

@@ -0,0 +1,38 @@
+/** Best-effort POSIX permissions (ignored on Windows / unsupported FSes). */
+export declare const DIR_MODE = 448;
+export declare const FILE_MODE = 384;
+/**
+ * Percent-encode a string into a filesystem-safe filename component. Beyond
+ * `encodeURIComponent` (which already escapes `/`, spaces, and unicode), this
+ * also escapes the unreserved characters `encodeURIComponent` leaves intact but
+ * that are unsafe in filenames on some platforms (notably `*` on Windows) — and
+ * `.`, so a file suffix appended by the caller is the only literal dot, making
+ * suffix-stripping unambiguous. Reversed by `decodeURIComponent`. The result
+ * contains only `A-Za-z0-9-_` and `%XX`.
+ */
+export declare function encodeFileSafeComponent(component: string): string;
+/** Whether an unknown error is a Node "file/dir not found" (ENOENT). */
+export declare function isNotFound(error: unknown): boolean;
+/**
+ * Crash-atomic file write: a concurrent reader sees either the complete
+ * previous bytes or the complete new bytes, never a torn file. `dir` is created
+ * (0700) if absent; the data is written to `tmpPath` (created exclusively,
+ * 0600), fsync'd, then atomically renamed onto `finalPath`. A failure at any
+ * point removes the temp file and leaves the previous file untouched.
+ *
+ * `tmpPath` must be a sibling of `finalPath` (same directory) so the rename
+ * stays within one filesystem and is therefore atomic, and should carry a
+ * random component so concurrent writers (and crash-orphaned leftovers) are
+ * collide-free.
+ *
+ * Durability bar: the temp file is fsync'd before the rename so a power loss
+ * cannot surface a file whose bytes never reached the platter, and `dir` is
+ * fsync'd afterwards (best-effort — see {@link syncDirBestEffort}) so the
+ * rename itself survives a crash. On POSIX `rename(2)` replaces atomically;
+ * Node maps to `MoveFileEx(MOVEFILE_REPLACE_EXISTING)` on Windows, which is
+ * also atomic — though it can fail with `EPERM`/`EBUSY` if another process
+ * holds the destination open. That cross-process case is out of scope for the
+ * single-flight in-process callers here; such a failure surfaces to the caller
+ * with the previous file left intact.
+ */
+export declare function writeFileAtomically(dir: string, tmpPath: string, finalPath: string, data: Uint8Array): Promise<void>;