spawnfile 0.1.13 → 0.1.14

package/dist/audit/checksShared.js

@@ -0,0 +1,37 @@
+import { DEFAULT_PAYLOAD_MINIMUMS } from "../ledger/index.js";
+export const notApplicable = (id, category, severity, reason) => ({
+    category,
+    evidence: { reason },
+    id,
+    severity,
+    status: "not_applicable"
+});
+export const statusFor = (ok) => (ok ? "pass" : "fail");
+/** `conformance.ts`'s `checkPayloadMinimums` is not exported (it is that module's private helper); this is the same one-line key-presence rule applied directly to already-parsed events, not a reimplementation of `validateConformanceSources`'s schema/seq/stitch pipeline. */
+export const missingRequiredKeys = (event, requiredKeys) => requiredKeys.filter((key) => !(key in event.payload) || event.payload[key] === undefined);
+export const DENIAL_MINIMUMS_BY_TYPE = new Map(DEFAULT_PAYLOAD_MINIMUMS.filter((minimum) => minimum.type.endsWith(".denied")).map((minimum) => [
+    minimum.type,
+    minimum.requiredKeys
+]));
+/** Env name gating the operator-only wake endpoint (appControlSource.ts:45, `CONTROL_TOKEN_ENV`). */
+export const CONTROL_TOKEN_ENV = "SPAWNFILE_PI_CONTROL_TOKEN";
+/**
+ * Verbatim source-text substring of appControlSource.ts:75's fail-closed
+ * rejection branch (`return { ok: false, reason: "no operator token
+ * configured (" + CONTROL_TOKEN_ENV + " is unset)" }`). The literal string
+ * checked here is only the first concatenated chunk — the source
+ * concatenates `CONTROL_TOKEN_ENV` in with `+`, so the fully-assembled
+ * runtime message never appears as one literal in the source text itself.
+ * Its presence is direct evidence the fail-closed branch was actually
+ * emitted, not paraphrased.
+ */
+export const FAIL_CLOSED_MARKER = "no operator token configured (";
+export const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+/**
+ * Matches a literal (non-`$`-expansion) shell/Dockerfile assignment
+ * `NAME=<value>` — never a `require_env 'NAME'` call (no `=` follows the
+ * name there at all) and never a same-name passthrough reference like
+ * `NAME="$NAME"`/`NAME=${NAME}` (an optional quote followed by `$`), both of
+ * which read the env rather than bake a value into it.
+ */
+export const literalAssignmentPattern = (name) => new RegExp(`\\b${escapeRegExp(name)}=(?!['"]?\\$)\\S`, "u");

package/dist/audit/generateAudit.d.ts

@@ -0,0 +1,19 @@
+import type { AuditReport } from "./types.js";
+export interface GenerateAuditOptions {
+    /** Required. The compiled-output directory (`spawnfile compile`'s emitted `Dockerfile`, `entrypoint.sh`, and — for a Pi-targeted compile — `runtime/app.mjs`). Static checks 3-4 always evaluate pass/fail against whatever is (or is not) present here; a missing file reads as an empty string, never a silent skip. */
+    compiledOutputDirPath: string;
+    /** Optional. A directory of `*.jsonl` ledger fixture files plus an optional `expected-denials.json` manifest (see checks.ts's `RunLedgerEvidence`). Omitting it (or an empty directory) is what makes run-mode checks 1, 2, 5, 6 report `not_applicable` — they never `pass` without it. */
+    ledgerDirPath?: string;
+    /** Injectable clock for `generated_at`, defaulting to `() => new Date()`. Every other report field is deterministic given the same inputs. */
+    now?: () => Date;
+    /** Secret env var NAMES this compile declared required (`requiredSecrets` passed to `renderEntrypoint`). Defaults to `[]`. */
+    requiredSecrets?: string[];
+}
+/**
+ * Orchestrator: the only I/O-performing function in src/audit/. Reads the
+ * compiled-output directory and, if given, the ledger directory, then runs
+ * the seven pure checks (checks.ts) and assembles the `AuditReport`.
+ * Deterministic across repeated calls with the same inputs except for
+ * `generated_at`.
+ */
+export declare const generateAudit: (options: GenerateAuditOptions) => Promise<AuditReport>;

package/dist/audit/generateAudit.js

@@ -0,0 +1,122 @@
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+import { fileExists, readUtf8File } from "../filesystem/index.js";
+import { runRealConformance } from "../ledger/index.js";
+import { checkContainerNoBakedSecrets, checkControlWakeFailClosed, checkDeniedLedgerVisible, checkMemoryCrossScopeCapability, checkNonMemberWriteDenied, checkPrincipalsAuthenticated, checkProvenanceSignedReport } from "./checks.js";
+import { SPAWNFILE_AUDIT_SCHEMA } from "./types.js";
+const readOptionalFile = async (filePath) => (await fileExists(filePath)) ? readUtf8File(filePath) : "";
+const readExpectedDenials = async (ledgerDirPath) => {
+    const manifestPath = path.join(ledgerDirPath, "expected-denials.json");
+    if (!(await fileExists(manifestPath))) {
+        return { expectedDenialTypes: [], manifestPresent: false };
+    }
+    const raw = await readUtf8File(manifestPath);
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed.expectedDenialTypes)) {
+        return { expectedDenialTypes: [], manifestPresent: true };
+    }
+    return {
+        expectedDenialTypes: parsed.expectedDenialTypes.filter((value) => typeof value === "string"),
+        manifestPresent: true
+    };
+};
+/**
+ * Reads every `*.jsonl` file in `ledgerDirPath` and feeds it to
+ * `runRealConformance` (src/ledger/conformance.ts) through an injected
+ * `exec` that returns each file's pre-read text instead of spawning a real
+ * sibling emitter process. This is what keeps the whole B54 generator
+ * offline while still reusing `runRealConformance`'s real schema/seq/
+ * payload-minimum/principal-grammar/chain-stitch pipeline rather than
+ * reimplementing any of it — see src/ledger/emitters.ts for the `Exec`/
+ * `EmitterSpec` contract this fills in. Returns `undefined` (never an empty
+ * evidence object) when the directory has no `*.jsonl` files, so callers can
+ * distinguish "no run artifacts" from "ledger with zero events".
+ */
+const collectRunLedgerEvidence = async (ledgerDirPath) => {
+    const entries = await readdir(ledgerDirPath, { withFileTypes: true }).catch(() => []);
+    const jsonlFileNames = entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl"))
+        .map((entry) => entry.name)
+        .sort((left, right) => left.localeCompare(right));
+    if (jsonlFileNames.length === 0) {
+        return undefined;
+    }
+    const contentByFileName = new Map();
+    for (const fileName of jsonlFileNames) {
+        contentByFileName.set(fileName, await readUtf8File(path.join(ledgerDirPath, fileName)));
+    }
+    const specs = jsonlFileNames.map((fileName) => ({
+        command: [fileName],
+        cwd: ledgerDirPath,
+        name: fileName.replace(/\.jsonl$/u, ""),
+        output: "stdout-jsonl"
+    }));
+    // Offline exec: returns the pre-read fixture text for the named source,
+    // never spawns a process. Matches src/ledger/emitters.ts's `Exec` contract.
+    const exec = (spec) => Promise.resolve({
+        exitCode: 0,
+        stderr: "",
+        stdout: contentByFileName.get(`${spec.name}.jsonl`) ?? "",
+        timedOut: false
+    });
+    const report = await runRealConformance({ exec, specs });
+    const { expectedDenialTypes, manifestPresent } = await readExpectedDenials(ledgerDirPath);
+    return {
+        eventCount: report.eventCount,
+        events: report.events,
+        expectedDenialTypes,
+        issues: report.issues,
+        manifestPresent,
+        sources: report.sourceCounts.map((entry) => entry.source)
+    };
+};
+const collectStaticEvidence = async (compiledOutputDirPath, requiredSecrets) => ({
+    dockerfile: await readOptionalFile(path.join(compiledOutputDirPath, "Dockerfile")),
+    entrypoint: await readOptionalFile(path.join(compiledOutputDirPath, "entrypoint.sh")),
+    piAppSource: await readOptionalFile(path.join(compiledOutputDirPath, "runtime", "app.mjs")),
+    requiredSecrets
+});
+const summarize = (checks) => ({
+    failed: checks.filter((check) => check.status === "fail").length,
+    na: checks.filter((check) => check.status === "not_applicable").length,
+    passed: checks.filter((check) => check.status === "pass").length
+});
+/** `null` unless every ledger event shares one `run_id` (see specs/CAUSAL.md — a single audit always covers one run). */
+const resolveRunId = (events) => {
+    if (events.length === 0) {
+        return null;
+    }
+    const runIds = new Set(events.map((event) => event.run_id));
+    return runIds.size === 1 ? runIds.values().next().value : null;
+};
+/**
+ * Orchestrator: the only I/O-performing function in src/audit/. Reads the
+ * compiled-output directory and, if given, the ledger directory, then runs
+ * the seven pure checks (checks.ts) and assembles the `AuditReport`.
+ * Deterministic across repeated calls with the same inputs except for
+ * `generated_at`.
+ */
+export const generateAudit = async (options) => {
+    const now = options.now ?? (() => new Date());
+    const requiredSecrets = options.requiredSecrets ?? [];
+    const [ledgerEvidence, staticEvidence] = await Promise.all([
+        options.ledgerDirPath ? collectRunLedgerEvidence(options.ledgerDirPath) : Promise.resolve(undefined),
+        collectStaticEvidence(options.compiledOutputDirPath, requiredSecrets)
+    ]);
+    const checks = [
+        checkPrincipalsAuthenticated(ledgerEvidence),
+        checkDeniedLedgerVisible(ledgerEvidence),
+        checkControlWakeFailClosed(staticEvidence),
+        checkContainerNoBakedSecrets(staticEvidence),
+        checkMemoryCrossScopeCapability(ledgerEvidence),
+        checkNonMemberWriteDenied(ledgerEvidence),
+        checkProvenanceSignedReport()
+    ];
+    return {
+        checks,
+        generated_at: now().toISOString(),
+        run_id: ledgerEvidence ? resolveRunId(ledgerEvidence.events) : null,
+        schema: SPAWNFILE_AUDIT_SCHEMA,
+        summary: summarize(checks)
+    };
+};

package/dist/audit/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./checks.js";
+export * from "./generateAudit.js";
+export * from "./readAudit.js";
+export * from "./types.js";

package/dist/audit/index.js

@@ -0,0 +1,4 @@
+export * from "./checks.js";
+export * from "./generateAudit.js";
+export * from "./readAudit.js";
+export * from "./types.js";

package/dist/audit/readAudit.d.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+import type { AuditReport } from "./types.js";
+export declare const auditReportSchema: z.ZodObject<{
+    checks: z.ZodArray<z.ZodObject<{
+        category: z.ZodEnum<{
+            provenance: "provenance";
+            causal: "causal";
+            container: "container";
+            control: "control";
+            memory: "memory";
+            network: "network";
+        }>;
+        evidence: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        id: z.ZodString;
+        severity: z.ZodEnum<{
+            critical: "critical";
+            high: "high";
+            medium: "medium";
+        }>;
+        status: z.ZodEnum<{
+            pass: "pass";
+            fail: "fail";
+            not_applicable: "not_applicable";
+        }>;
+    }, z.core.$strict>>;
+    generated_at: z.ZodString;
+    run_id: z.ZodNullable<z.ZodString>;
+    schema: z.ZodLiteral<"spawnfile.audit.v1">;
+    summary: z.ZodObject<{
+        failed: z.ZodNumber;
+        na: z.ZodNumber;
+        passed: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export interface AuditReadError {
+    message: string;
+}
+/**
+ * Safe (non-throwing) validator. Rejects an unknown `schema` string as a
+ * top-level structural mismatch — `z.literal` already fails it — rather
+ * than accepting any string and comparing separately, so a caller cannot
+ * bypass the schema gate with a structurally-valid-but-wrong-version report.
+ */
+export declare const validateAuditReport: (value: unknown) => {
+    report: AuditReport;
+} | {
+    error: AuditReadError;
+};
+/** Throwing counterpart of `validateAuditReport`, mirroring `envelope.ts`'s `parseCausalEvent`. */
+export declare const readAuditReport: (value: unknown) => AuditReport;

package/dist/audit/readAudit.js

@@ -0,0 +1,59 @@
+import { z } from "zod";
+import { SPAWNFILE_AUDIT_SCHEMA } from "./types.js";
+/**
+ * Pure reader/validator for an existing `spawnfile.audit.v1` report — the
+ * `envelope.ts` precedent (a zod schema mirroring the hand-written
+ * `AuditReport` interface, plus a `parse*`/`validate*` pair). No I/O:
+ * callers pass already-read JSON (typically `JSON.parse`d from a file
+ * `generateAudit.ts` wrote), this module only checks shape.
+ */
+const auditCheckSchema = z
+    .object({
+    category: z.enum(["causal", "container", "control", "memory", "network", "provenance"]),
+    evidence: z.record(z.string(), z.unknown()),
+    id: z.string().min(1),
+    severity: z.enum(["critical", "high", "medium"]),
+    status: z.enum(["pass", "fail", "not_applicable"])
+})
+    .strict();
+const auditSummarySchema = z
+    .object({
+    failed: z.number().int().min(0),
+    na: z.number().int().min(0),
+    passed: z.number().int().min(0)
+})
+    .strict();
+export const auditReportSchema = z
+    .object({
+    checks: z.array(auditCheckSchema),
+    generated_at: z.string().min(1),
+    run_id: z.string().min(1).nullable(),
+    schema: z.literal(SPAWNFILE_AUDIT_SCHEMA),
+    summary: auditSummarySchema
+})
+    .strict();
+/**
+ * Safe (non-throwing) validator. Rejects an unknown `schema` string as a
+ * top-level structural mismatch — `z.literal` already fails it — rather
+ * than accepting any string and comparing separately, so a caller cannot
+ * bypass the schema gate with a structurally-valid-but-wrong-version report.
+ */
+export const validateAuditReport = (value) => {
+    const result = auditReportSchema.safeParse(value);
+    if (!result.success) {
+        return {
+            error: {
+                message: result.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")
+            }
+        };
+    }
+    return { report: result.data };
+};
+/** Throwing counterpart of `validateAuditReport`, mirroring `envelope.ts`'s `parseCausalEvent`. */
+export const readAuditReport = (value) => {
+    const result = validateAuditReport(value);
+    if ("error" in result) {
+        throw new Error(`invalid spawnfile.audit.v1 report: ${result.error.message}`);
+    }
+    return result.report;
+};

package/dist/audit/types.d.ts

@@ -0,0 +1,40 @@
+/**
+ * B54 — spawnfile.audit.v1 contract types. This module is type-only (no
+ * logic, no I/O): the schema constant plus the AuditCheck/AuditReport shapes
+ * every other file in src/audit/ produces or consumes. See AGENTS.md for the
+ * folder-wide "reports, never enforces" rule this contract exists to serve.
+ */
+/** Versioned schema identifier stamped on every generated report, mirroring the `noopolis.causal-event.v1` precedent (src/ledger/envelope.ts). */
+export declare const SPAWNFILE_AUDIT_SCHEMA: "spawnfile.audit.v1";
+/**
+ * The five ledger/runtime categories checks 1-6 are grounded in, plus
+ * "provenance" for check 7 (`provenance.signed-report`). The frozen B54
+ * packet's contract line only lists five category values; "provenance" is
+ * added here to keep every check's `id` prefix equal to its `category`
+ * (checks 1-6 already follow that pattern exactly), rather than
+ * mis-bucketing check 7 under an unrelated category. See AGENTS.md
+ * "Deviations from the frozen packet".
+ */
+export type AuditCheckCategory = "causal" | "container" | "control" | "memory" | "network" | "provenance";
+export type AuditCheckStatus = "pass" | "fail" | "not_applicable";
+export type AuditCheckSeverity = "critical" | "high" | "medium";
+export interface AuditCheck {
+    category: AuditCheckCategory;
+    evidence: Record<string, unknown>;
+    id: string;
+    severity: AuditCheckSeverity;
+    status: AuditCheckStatus;
+}
+export interface AuditSummary {
+    failed: number;
+    na: number;
+    passed: number;
+}
+export interface AuditReport {
+    checks: AuditCheck[];
+    /** Diagnostic only — excluded from determinism comparisons (two otherwise-identical generator runs may differ only here). */
+    generated_at: string;
+    run_id: string | null;
+    schema: typeof SPAWNFILE_AUDIT_SCHEMA;
+    summary: AuditSummary;
+}

package/dist/audit/types.js

@@ -0,0 +1,8 @@
+/**
+ * B54 — spawnfile.audit.v1 contract types. This module is type-only (no
+ * logic, no I/O): the schema constant plus the AuditCheck/AuditReport shapes
+ * every other file in src/audit/ produces or consumes. See AGENTS.md for the
+ * folder-wide "reports, never enforces" rule this contract exists to serve.
+ */
+/** Versioned schema identifier stamped on every generated report, mirroring the `noopolis.causal-event.v1` precedent (src/ledger/envelope.ts). */
+export const SPAWNFILE_AUDIT_SCHEMA = "spawnfile.audit.v1";

package/dist/auth/credentialEnvFile.d.ts

@@ -0,0 +1,11 @@
+import type { CredentialProvisioningReceipt } from "./credentialProvisioningReceipt.js";
+import type { ProvisionedCredentialMaterials } from "./credentialProvisioning.js";
+export type ProvisionedEnvFileResult = Readonly<{
+    digest: string;
+    path: string;
+}>;
+export declare const writeProvisionedEnvFile: (input: Readonly<{
+    materials: ProvisionedCredentialMaterials;
+    path: string;
+    receipt: CredentialProvisioningReceipt;
+}>) => Promise<ProvisionedEnvFileResult>;

package/dist/auth/credentialEnvFile.js

@@ -0,0 +1,60 @@
+import { createHash } from "node:crypto";
+import { open, unlink } from "node:fs/promises";
+import { TARGET_SECRET_SOURCE_ERROR } from "./targetSecretSourceRecordCommon.js";
+const fail = () => { throw new Error(TARGET_SECRET_SOURCE_ERROR); };
+export const writeProvisionedEnvFile = async (input) => {
+    let bytes;
+    let handle;
+    let created = false;
+    try {
+        const credentials = [...input.receipt.credentials].sort((left, right) => left.env < right.env ? -1 : left.env > right.env ? 1 : 0);
+        if (credentials.length === 0 || input.materials.size !== credentials.length)
+            fail();
+        const prefixes = credentials.map(({ env }) => new TextEncoder().encode(`${env}=`));
+        try {
+            const size = credentials.reduce((total, credential, index) => {
+                const prefix = prefixes[index] ?? fail();
+                const material = input.materials.get(credential.name) ?? fail();
+                if (!material || material.length === 0 || material.some((byte) => byte === 0 || byte === 10 || byte === 13))
+                    fail();
+                return total + prefix.length + material.length + 1;
+            }, 0);
+            bytes = new Uint8Array(size);
+            let offset = 0;
+            for (const [index, credential] of credentials.entries()) {
+                const prefix = prefixes[index] ?? fail();
+                const material = input.materials.get(credential.name) ?? fail();
+                bytes.set(prefix, offset);
+                offset += prefix.length;
+                bytes.set(material, offset);
+                offset += material.length;
+                bytes[offset] = 10;
+                offset += 1;
+            }
+        }
+        finally {
+            for (const prefix of prefixes)
+                prefix.fill(0);
+        }
+        handle = await open(input.path, "wx", 0o600);
+        created = true;
+        await handle.chmod(0o600);
+        await handle.writeFile(bytes);
+        await handle.sync();
+        const digest = `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+        await handle.close();
+        handle = undefined;
+        return Object.freeze({ digest, path: input.path });
+    }
+    catch {
+        await handle?.close().catch(() => undefined);
+        handle = undefined;
+        if (created)
+            await unlink(input.path).catch(() => undefined);
+        return fail();
+    }
+    finally {
+        bytes?.fill(0);
+        await handle?.close().catch(() => undefined);
+    }
+};

package/dist/auth/credentialProvisioning.d.ts

@@ -0,0 +1,15 @@
+import { type CredentialProvisioningReceipt } from "./credentialProvisioningReceipt.js";
+import type { CredentialProvisioningRequest } from "./credentialProvisioningRequest.js";
+import type { TargetSecretSourceLifecycle } from "./targetSecretSourceLifecycle.js";
+export type ProvisionedCredentialMaterials = Map<string, Uint8Array>;
+export type CredentialProvisioningEntropy = (bytes: number) => Uint8Array;
+export interface CredentialProvisioningOptions {
+    readonly entropy?: CredentialProvisioningEntropy;
+    readonly lifecycle?: Pick<TargetSecretSourceLifecycle, "author" | "grant">;
+}
+export type ProvisionedCredentials = Readonly<{
+    materials: ProvisionedCredentialMaterials;
+    receipt: CredentialProvisioningReceipt;
+}>;
+export declare const disposeProvisionedMaterials: (materials: ProvisionedCredentialMaterials) => void;
+export declare const provisionCredentials: (request: CredentialProvisioningRequest, options?: CredentialProvisioningOptions) => Promise<ProvisionedCredentials>;

package/dist/auth/credentialProvisioning.js

@@ -0,0 +1,75 @@
+import { Buffer } from "node:buffer";
+import { randomBytes } from "node:crypto";
+import { createCredentialProvisioningReceipt } from "./credentialProvisioningReceipt.js";
+import { TARGET_SECRET_SOURCE_ERROR, createCanonicalTargetSecretSourceJson } from "./targetSecretSourceRecordCommon.js";
+const fail = () => { throw new Error(TARGET_SECRET_SOURCE_ERROR); };
+const defaultEntropy = (size) => {
+    const bytes = randomBytes(size);
+    try {
+        return Uint8Array.from(bytes);
+    }
+    finally {
+        bytes.fill(0);
+    }
+};
+const generatedToken = (size, entropy) => {
+    let raw;
+    let encoded;
+    try {
+        raw = entropy(size);
+        if (!(raw instanceof Uint8Array) || raw.length !== size)
+            fail();
+        encoded = Buffer.from(raw);
+        return new TextEncoder().encode(encoded.toString("hex"));
+    }
+    finally {
+        encoded?.fill(0);
+        raw?.fill(0);
+    }
+};
+export const disposeProvisionedMaterials = (materials) => {
+    for (const material of materials.values())
+        material.fill(0);
+    materials.clear();
+};
+export const provisionCredentials = async (request, options = {}) => {
+    const materials = new Map();
+    try {
+        const lifecycle = options.lifecycle
+            ?? await (await import("./targetSecretSourceLifecycle.js")).initializeTargetSecretSourceLifecycle();
+        const entropy = options.entropy ?? defaultEntropy;
+        for (const credential of request.credentials) {
+            const material = credential.kind === "generated-token"
+                ? generatedToken(credential.bytes, entropy)
+                : createCanonicalTargetSecretSourceJson(credential.content);
+            materials.set(credential.name, material);
+        }
+        const sources = new Map();
+        for (const credential of request.credentials) {
+            const material = materials.get(credential.name) ?? fail();
+            const authored = await lifecycle.author(material);
+            sources.set(credential.name, authored.source_handle);
+        }
+        for (const credential of request.credentials) {
+            const sourceHandle = sources.get(credential.name);
+            const granted = await lifecycle.grant({
+                descriptor_digest: request.descriptor_digest,
+                name: credential.name,
+                run_id: request.run_id,
+                scope: request.scope,
+                selected_target: request.selected_target,
+                source_handle: sourceHandle
+            });
+            if (granted.source_handle !== sourceHandle)
+                fail();
+        }
+        return Object.freeze({
+            materials,
+            receipt: createCredentialProvisioningReceipt({ request, source_handles: sources })
+        });
+    }
+    catch {
+        disposeProvisionedMaterials(materials);
+        return fail();
+    }
+};

package/dist/auth/credentialProvisioningReceipt.d.ts

@@ -0,0 +1,28 @@
+import type { CredentialProvisioningRequest } from "./credentialProvisioningRequest.js";
+import { type OpaqueTargetSecretSourceHandle } from "./targetSecretSourceRecordCommon.js";
+export declare const CREDENTIAL_PROVISIONING_RECEIPT_VERSION: "spawnfile.auth.credential-provisioning.receipt.v1";
+export type CredentialProvisioningPhase = "author" | "grant" | "model_engine_auth" | "env_file" | "world_bindings";
+export type CredentialProvisioningReceiptCredential = Readonly<{
+    env: string;
+    name: string;
+    scope: string;
+    source_handle: OpaqueTargetSecretSourceHandle;
+}>;
+export type CredentialProvisioningReceipt = Readonly<{
+    credentials: readonly CredentialProvisioningReceiptCredential[];
+    env_file_digest?: string;
+    phases: readonly CredentialProvisioningPhase[];
+    run_id: string;
+    scope: string;
+    version: typeof CREDENTIAL_PROVISIONING_RECEIPT_VERSION;
+    world_bindings_digest?: string;
+}>;
+export declare const createCredentialProvisioningReceipt: (input: Readonly<{
+    request: CredentialProvisioningRequest;
+    source_handles: ReadonlyMap<string, unknown>;
+}>) => CredentialProvisioningReceipt;
+export declare const finalizeCredentialProvisioningReceipt: (receipt: CredentialProvisioningReceipt, outputs: Readonly<{
+    env_file_digest?: string;
+    model_engine_auth?: boolean;
+    world_bindings_digest?: string;
+}>) => CredentialProvisioningReceipt;

package/dist/auth/credentialProvisioningReceipt.js

@@ -0,0 +1,70 @@
+import { TARGET_SECRET_SOURCE_ERROR, parseTargetSecretSourceOpaqueHandle } from "./targetSecretSourceRecordCommon.js";
+export const CREDENTIAL_PROVISIONING_RECEIPT_VERSION = "spawnfile.auth.credential-provisioning.receipt.v1";
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const fail = () => { throw new Error(TARGET_SECRET_SOURCE_ERROR); };
+const digest = (raw) => typeof raw === "string" && DIGEST.test(raw) ? raw : fail();
+export const createCredentialProvisioningReceipt = (input) => {
+    try {
+        const credentials = input.request.credentials.map((credential) => {
+            const sourceHandle = input.source_handles.get(credential.name);
+            return Object.freeze({
+                env: credential.env,
+                name: credential.name,
+                scope: input.request.scope,
+                source_handle: parseTargetSecretSourceOpaqueHandle(sourceHandle)
+            });
+        });
+        if (input.source_handles.size !== credentials.length)
+            fail();
+        return Object.freeze({
+            credentials: Object.freeze(credentials),
+            phases: Object.freeze(["author", "grant"]),
+            run_id: input.request.run_id,
+            scope: input.request.scope,
+            version: CREDENTIAL_PROVISIONING_RECEIPT_VERSION
+        });
+    }
+    catch {
+        return fail();
+    }
+};
+export const finalizeCredentialProvisioningReceipt = (receipt, outputs) => {
+    try {
+        if (receipt.version !== CREDENTIAL_PROVISIONING_RECEIPT_VERSION
+            || receipt.phases.length !== 2
+            || receipt.phases[0] !== "author"
+            || receipt.phases[1] !== "grant")
+            fail();
+        const credentials = receipt.credentials.map((credential) => Object.freeze({
+            env: credential.env,
+            name: credential.name,
+            scope: credential.scope,
+            source_handle: parseTargetSecretSourceOpaqueHandle(credential.source_handle)
+        }));
+        const envFileDigest = outputs.env_file_digest === undefined
+            ? undefined
+            : digest(outputs.env_file_digest);
+        const worldBindingsDigest = outputs.world_bindings_digest === undefined
+            ? undefined
+            : digest(outputs.world_bindings_digest);
+        const phases = ["author", "grant"];
+        if (outputs.model_engine_auth === true)
+            phases.push("model_engine_auth");
+        if (envFileDigest !== undefined)
+            phases.push("env_file");
+        if (worldBindingsDigest !== undefined)
+            phases.push("world_bindings");
+        return Object.freeze({
+            credentials: Object.freeze(credentials),
+            ...(envFileDigest === undefined ? {} : { env_file_digest: envFileDigest }),
+            phases: Object.freeze(phases),
+            run_id: receipt.run_id,
+            scope: receipt.scope,
+            version: CREDENTIAL_PROVISIONING_RECEIPT_VERSION,
+            ...(worldBindingsDigest === undefined ? {} : { world_bindings_digest: worldBindingsDigest })
+        });
+    }
+    catch {
+        return fail();
+    }
+};