project-tiny-context-harness 0.8.16 → 0.11.0

package/dist/lib/long-task-expected-authority.js

@@ -0,0 +1,126 @@
+import { controlFieldFacts } from "./long-task-control-fields.js";
+export function resolveExpectedAuthority(contract, outcomeKey, assertion, manifest, expectations) {
+    const expectation = expectations.find((item) => item.assertion_ref === assertion.key);
+    if (expectation)
+        return resolveSemanticFactExpectedAuthority(assertion, expectation);
+    const fullClaim = outcomeKey
+        ? `${outcomeKey}.${assertion.claims[0]}`
+        : assertion.claims[0];
+    const canonical = `contract-claim:${fullClaim}`;
+    const sourceAuthorities = contract.source_claims.filter((source) => sourceClaimRefs(source).includes(fullClaim));
+    const declared = assertion.expected_authority_ref;
+    let authorityStatement = claimAuthorityStatement(contract, outcomeKey, assertion.claims[0]);
+    let resolved = canonical;
+    if (declared) {
+        const source = sourceAuthorities.find((item) => [item.key, `source:${item.key}`].includes(declared));
+        const factRef = declared.startsWith("semantic-fact:")
+            ? declared.slice("semantic-fact:".length)
+            : declared;
+        const fact = manifest.facts.find((item) => item.key === factRef);
+        if (declared === canonical)
+            resolved = canonical;
+        else if (source) {
+            resolved = `source:${source.key}`;
+            authorityStatement = source.statement;
+        }
+        else if (fact)
+            return resolveBoundFactAuthority(contract, outcomeKey, assertion, fact);
+        else
+            fail("expected_authority_ref_unknown", `${outcomeKey ?? "GLOBAL"}:${assertion.key}:${declared}`);
+    }
+    if ("expected" in assertion &&
+        assertion.expected !== true &&
+        assertion.expected !== false &&
+        !authorityContainsExpected(authorityStatement, assertion.expected))
+        fail("expected_value_not_projected_from_authority", `${outcomeKey ?? "GLOBAL"}:${assertion.key}:${resolved}`);
+    return resolved;
+}
+function resolveSemanticFactExpectedAuthority(assertion, expectation) {
+    const canonical = `semantic-proof:${expectation.proof_ref}`;
+    if (assertion.expected_authority_ref &&
+        ![
+            canonical,
+            `semantic-fact:${expectation.fact_ref}`,
+            expectation.fact_ref,
+            expectation.proof_ref,
+        ].includes(assertion.expected_authority_ref))
+        fail("expected_authority_ref_mismatch", `${assertion.key}:${assertion.expected_authority_ref}:${canonical}`);
+    return canonical;
+}
+function resolveBoundFactAuthority(contract, outcomeKey, assertion, fact) {
+    if (!semanticFactBoundToAssertion(contract, outcomeKey, assertion, fact.key))
+        fail("expected_authority_fact_not_bound_to_claim", `${outcomeKey ?? "GLOBAL"}:${assertion.key}:${fact.key}`);
+    if ("expected" in assertion &&
+        fact.expected.representation === "inline" &&
+        JSON.stringify(assertion.expected) !== JSON.stringify(fact.expected.value))
+        fail("expected_authority_value_mismatch", `${assertion.key}:${fact.key}`);
+    return `semantic-fact:${fact.key}`;
+}
+function semanticFactBoundToAssertion(contract, outcomeKey, assertion, factRef) {
+    if (!outcomeKey || !assertion.applicability_ref)
+        return false;
+    const outcome = contract.outcomes.find((item) => item.key === outcomeKey);
+    return Boolean(outcome?.semantic_fact_bindings.facts.some((binding) => binding.fact_ref === factRef &&
+        binding.claim_ref === assertion.claims[0] &&
+        binding.applicability_ref === assertion.applicability_ref));
+}
+export function claimAuthorityStatement(contract, outcomeKey, localClaim) {
+    return outcomeKey
+        ? outcomeClaimAuthorityStatement(contract, outcomeKey, localClaim)
+        : globalClaimAuthorityStatement(contract, localClaim);
+}
+function globalClaimAuthorityStatement(contract, localClaim) {
+    if (localClaim.startsWith("non_goal."))
+        return (contract.global.product.non_goals.find((item) => `non_goal.${item.key}` === localClaim)?.statement ?? "");
+    if (localClaim.startsWith("constraint."))
+        return (contract.global.technical.constraints.find((item) => `constraint.${item.key}` === localClaim)?.statement ?? "");
+    return (contract.global.technical.forbidden_shortcuts.find((item) => `forbidden_shortcut.${item.key}` === localClaim)?.statement ?? "");
+}
+function outcomeClaimAuthorityStatement(contract, outcomeKey, localClaim) {
+    const outcome = contract.outcomes.find((item) => item.key === outcomeKey);
+    if (localClaim === "result")
+        return outcome.product.observable_result;
+    if (localClaim.startsWith("requirement."))
+        return keyedStatement(outcome.product.requirements, "requirement", localClaim);
+    if (localClaim.startsWith("control."))
+        return controlAuthorityStatement(outcome, localClaim);
+    if (localClaim === "control_relation_closure")
+        return outcome.product.control_relation_closure.statement;
+    if (localClaim.startsWith("control_relation."))
+        return keyedStatement(outcome.product.control_relations, "control_relation", localClaim);
+    if (localClaim.startsWith("non_completing."))
+        return keyedStatement(outcome.product.non_completing_outcomes, "non_completing", localClaim);
+    if (localClaim.startsWith("obligation."))
+        return keyedStatement(outcome.technical.obligations, "obligation", localClaim);
+    if (localClaim.startsWith("forbidden_shortcut."))
+        return keyedStatement(outcome.technical.forbidden_shortcuts, "forbidden_shortcut", localClaim);
+    return (outcome.semantic_fact_bindings.facts.find((item) => item.claim_ref === localClaim)?.fact_ref ?? "");
+}
+function controlAuthorityStatement(outcome, localClaim) {
+    const [, controlKey, field] = localClaim.split(".");
+    const control = outcome.product.controls.find((item) => item.key === controlKey);
+    return control
+        ? (controlFieldFacts(control).find((item) => item.claim_field === field)
+            ?.statement ?? "")
+        : "";
+}
+function keyedStatement(rows, prefix, localClaim) {
+    return (rows.find((item) => `${prefix}.${item.key}` === localClaim)?.statement ?? "");
+}
+function sourceClaimRefs(source) {
+    if (source.disposition.type === "decision_required")
+        return [];
+    if (source.disposition.type === "outcome_result")
+        return [source.disposition.ref];
+    return source.disposition.refs;
+}
+function authorityContainsExpected(statement, expected) {
+    if (typeof expected === "string")
+        return statement.includes(expected);
+    if (typeof expected === "number")
+        return statement.includes(String(expected));
+    return statement.includes(JSON.stringify(expected));
+}
+function fail(code, detail) {
+    throw new Error(`delivery_contract_invalid:${code}:${detail}`);
+}

package/dist/lib/long-task-external-confirmation-artifacts.d.ts

@@ -0,0 +1,9 @@
+import type { ExternalConfirmationRecordV2 } from "./long-task-external-confirmation-types.js";
+export declare const MAX_TOTAL_EXTERNAL_CONFIRMATION_ARTIFACT_BYTES: number;
+export declare function externalConfirmationArtifactStoreRef(sha256: string): string;
+export declare function captureAndStoreExternalConfirmationArtifacts(repository: string, workdir: string, snapshots: ExternalConfirmationRecordV2["artifact_snapshots"], options?: {
+    max_total_bytes?: number;
+}): Promise<void>;
+export declare function externalArtifactSnapshotIntegrityIssues(repository: string, workdir: string, snapshots: ExternalConfirmationRecordV2["artifact_snapshots"]): Promise<string[]>;
+export declare function captureStoredExternalConfirmationArtifactIdentities(repository: string, workdir: string, snapshots: ExternalConfirmationRecordV2["artifact_snapshots"]): Promise<Record<string, string>>;
+export declare function externalArtifactIntegrityIssues(repository: string, artifacts: Record<string, string>): Promise<string[]>;

package/dist/lib/long-task-external-confirmation-artifacts.js

@@ -0,0 +1,138 @@
+import { lstat, open, readFile, rename, rm } from "node:fs/promises";
+import path from "node:path";
+import { assertProtectedRepositoryFile, assertSafeRepositoryFilePath, ensureSafeRepositoryDirectory, } from "./repository-path-safety.js";
+import { runtimePath } from "./long-task-state.js";
+import { sha256Hex } from "./strict-codec.js";
+const ARTIFACT_STORE_FOLDER = "external-confirmations/artifacts";
+const MAX_ARTIFACT_BYTES = 16 * 1024 * 1024;
+export const MAX_TOTAL_EXTERNAL_CONFIRMATION_ARTIFACT_BYTES = 64 * 1024 * 1024;
+export function externalConfirmationArtifactStoreRef(sha256) {
+    if (!/^[a-f0-9]{64}$/u.test(sha256))
+        throw new Error(`external_confirmation_artifact_hash_invalid:${sha256}`);
+    return `${ARTIFACT_STORE_FOLDER}/${sha256}`;
+}
+export async function captureAndStoreExternalConfirmationArtifacts(repository, workdir, snapshots, options = {}) {
+    const captured = [];
+    let totalBytes = 0;
+    for (const [evidenceRef, snapshot] of Object.entries(snapshots).sort(([left], [right]) => left.localeCompare(right))) {
+        const expectedStoreRef = externalConfirmationArtifactStoreRef(snapshot.sha256);
+        if (snapshot.store_ref !== expectedStoreRef)
+            throw new Error(`external_confirmation_artifact_store_ref_mismatch:${evidenceRef}`);
+        if (evidenceRef.startsWith(`${ARTIFACT_STORE_FOLDER}/`))
+            throw new Error(`external_confirmation_artifact_source_store_ref_not_allowed:${evidenceRef}`);
+        const file = await assertProtectedRepositoryFile(repository, path.resolve(repository, ...evidenceRef.split("/")), `external_confirmation_artifact:${evidenceRef}`);
+        const info = await lstat(file);
+        if (info.size > MAX_ARTIFACT_BYTES)
+            throw new Error(`external_confirmation_artifact_too_large:${evidenceRef}:${info.size}`);
+        totalBytes += info.size;
+        if (totalBytes >
+            (options.max_total_bytes ??
+                MAX_TOTAL_EXTERNAL_CONFIRMATION_ARTIFACT_BYTES))
+            throw new Error(`external_confirmation_artifacts_total_too_large:${totalBytes}`);
+        const bytes = await readFile(file);
+        if (bytes.length !== info.size || bytes.length !== snapshot.size_bytes)
+            throw new Error(`external_confirmation_artifact_size_mismatch:${evidenceRef}`);
+        if (sha256Hex(bytes) !== snapshot.sha256)
+            throw new Error(`external_confirmation_artifact_content_mismatch:${evidenceRef}`);
+        captured.push({ sha256: snapshot.sha256, bytes });
+    }
+    const unique = new Map(captured.map((row) => [row.sha256, row.bytes]));
+    for (const [sha256, bytes] of unique)
+        await storeArtifact(repository, workdir, sha256, bytes);
+}
+export async function externalArtifactSnapshotIntegrityIssues(repository, workdir, snapshots) {
+    const issues = [];
+    for (const [evidenceRef, snapshot] of Object.entries(snapshots).sort(([left], [right]) => left.localeCompare(right))) {
+        const expectedStoreRef = externalConfirmationArtifactStoreRef(snapshot.sha256);
+        if (snapshot.store_ref !== expectedStoreRef) {
+            issues.push(`artifact_store_ref_mismatch:${evidenceRef}`);
+            continue;
+        }
+        try {
+            const file = await assertProtectedRepositoryFile(repository, runtimePath(workdir, snapshot.store_ref), `external_confirmation_artifact_snapshot:${evidenceRef}`);
+            const info = await lstat(file);
+            const bytes = await readFile(file);
+            if (info.size !== snapshot.size_bytes ||
+                bytes.length !== snapshot.size_bytes)
+                issues.push(`artifact_snapshot_size_changed:${evidenceRef}`);
+            if (sha256Hex(bytes) !== snapshot.sha256)
+                issues.push(`artifact_snapshot_content_changed:${evidenceRef}`);
+        }
+        catch (error) {
+            issues.push(`artifact_snapshot_invalid:${evidenceRef}:${message(error)}`);
+        }
+    }
+    return issues;
+}
+export async function captureStoredExternalConfirmationArtifactIdentities(repository, workdir, snapshots) {
+    const result = {};
+    for (const snapshot of Object.values(snapshots).sort((left, right) => left.store_ref.localeCompare(right.store_ref)))
+        try {
+            const file = await assertProtectedRepositoryFile(repository, runtimePath(workdir, snapshot.store_ref), `external_confirmation_artifact_snapshot:${snapshot.store_ref}`);
+            result[snapshot.store_ref] = `sha256:${sha256Hex(await readFile(file))}`;
+        }
+        catch (error) {
+            result[snapshot.store_ref] = `unavailable:${sha256Hex(`${snapshot.sha256}\0${message(error)}`)}`;
+        }
+    return result;
+}
+// Legacy v1 audit helper. It never establishes fulfillment.
+export async function externalArtifactIntegrityIssues(repository, artifacts) {
+    const issues = [];
+    for (const [relative, expectedHash] of Object.entries(artifacts)) {
+        try {
+            const file = await assertProtectedRepositoryFile(repository, path.resolve(repository, ...relative.split("/")), `external_confirmation_artifact:${relative}`);
+            const actualHash = sha256Hex(await readFile(file));
+            if (actualHash !== expectedHash)
+                issues.push(`artifact_content_changed:${relative}`);
+        }
+        catch (error) {
+            issues.push(`artifact_invalid:${relative}:${message(error)}`);
+        }
+    }
+    return issues;
+}
+async function storeArtifact(repository, workdir, sha256, bytes) {
+    const storeRef = externalConfirmationArtifactStoreRef(sha256);
+    const folder = runtimePath(workdir, ARTIFACT_STORE_FOLDER);
+    await ensureSafeRepositoryDirectory(repository, repositoryRelative(repository, folder), "external_confirmation_artifact_store");
+    const target = runtimePath(workdir, storeRef);
+    const safe = await assertSafeRepositoryFilePath(repository, repositoryRelative(repository, target), `external_confirmation_artifact_store:${sha256}`, { destinationMayBeAbsent: true });
+    if (safe.status) {
+        const existing = await readFile(safe.absolute);
+        if (sha256Hex(existing) !== sha256 || existing.length !== bytes.length)
+            throw new Error(`external_confirmation_artifact_store_collision:${sha256}`);
+        return;
+    }
+    const temporary = `${target}.tmp-${process.pid}-${Date.now()}`;
+    const handle = await open(temporary, "wx");
+    try {
+        await handle.writeFile(bytes);
+        await handle.sync();
+    }
+    catch (error) {
+        await handle.close().catch(() => undefined);
+        await rm(temporary, { force: true });
+        throw error;
+    }
+    await handle.close();
+    try {
+        await rename(temporary, target);
+    }
+    catch (error) {
+        await rm(temporary, { force: true });
+        throw error;
+    }
+}
+function repositoryRelative(repository, candidate) {
+    const relative = path.relative(path.resolve(repository), path.resolve(candidate));
+    if (!relative ||
+        relative === ".." ||
+        relative.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relative))
+        throw new Error("external_confirmation_artifact_outside_repository");
+    return relative.replace(/\\/gu, "/");
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/lib/long-task-external-confirmation-attestation.d.ts

@@ -0,0 +1,20 @@
+import type { CompiledExternalConfirmationIdentityAssuranceV2, DeliveryContractV2, ExternalConfirmationV2 } from "./long-task-contract-types.js";
+import type { CompiledDeliveryContractV2, ContextAuthoritySnapshotV2 } from "./long-task-delivery-types.js";
+import type { ExternalConfirmationActorV1, ExternalConfirmationRecordV2 } from "./long-task-external-confirmation-types.js";
+export declare function compileExternalConfirmationIdentityAssurances(input: {
+    contract: DeliveryContractV2;
+    repository: string;
+    source_hashes: Record<string, string>;
+    context_snapshot: ContextAuthoritySnapshotV2;
+}): Promise<Record<string, CompiledExternalConfirmationIdentityAssuranceV2>>;
+export declare function externalConfirmationActor(confirmation: ExternalConfirmationV2): ExternalConfirmationActorV1 | null;
+export declare function compiledExternalConfirmationIdentityAssurance(compiled: CompiledDeliveryContractV2, confirmationRef: string): CompiledExternalConfirmationIdentityAssuranceV2 | null;
+export declare function verifyExternalConfirmationAttestation(input: {
+    repository: string;
+    confirmation_ref: string;
+    assurance: CompiledExternalConfirmationIdentityAssuranceV2 | null;
+    record: ExternalConfirmationRecordV2;
+}): Promise<{
+    verified: boolean;
+    issues: string[];
+}>;

package/dist/lib/long-task-external-confirmation-attestation.js

@@ -0,0 +1,115 @@
+import { createPublicKey, verify } from "node:crypto";
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { externalConfirmationV2SignablePayload } from "./long-task-external-confirmation-shape.js";
+import { normalizeContextAuthoritySnapshot } from "./long-task-context-authority.js";
+import { assertProtectedRepositoryFile } from "./repository-path-safety.js";
+import { sha256Hex } from "./strict-codec.js";
+const MAX_PUBLIC_KEY_BYTES = 64 * 1024;
+export async function compileExternalConfirmationIdentityAssurances(input) {
+    const result = {};
+    const context = normalizeContextAuthoritySnapshot(input.context_snapshot);
+    const controllingContext = new Set(context.controlling_files);
+    for (const confirmation of input.contract.global.acceptance
+        .external_confirmations) {
+        const assurance = confirmation.actor?.identity_assurance;
+        if (!assurance)
+            continue;
+        if (assurance.scheme === "declared_only") {
+            result[confirmation.key] = assurance;
+            continue;
+        }
+        const expectedHash = input.source_hashes[assurance.public_key_ref] ??
+            (controllingContext.has(assurance.public_key_ref)
+                ? context.sha256[assurance.public_key_ref]
+                : undefined);
+        if (!expectedHash)
+            throw new Error(`external_confirmation_public_key_not_controlling_source:${confirmation.key}:${assurance.public_key_ref}`);
+        const file = await assertProtectedRepositoryFile(input.repository, path.resolve(input.repository, ...assurance.public_key_ref.split("/")), `external_confirmation_public_key:${confirmation.key}`);
+        const info = await stat(file);
+        if (info.size > MAX_PUBLIC_KEY_BYTES)
+            throw new Error(`external_confirmation_public_key_too_large:${confirmation.key}:${info.size}`);
+        const bytes = await readFile(file);
+        const actualHash = sha256Hex(bytes);
+        if (actualHash !== expectedHash)
+            throw new Error(`external_confirmation_public_key_identity_mismatch:${confirmation.key}`);
+        assertEd25519PublicKey(bytes, confirmation.key);
+        result[confirmation.key] = {
+            ...assurance,
+            public_key_sha256: actualHash,
+        };
+    }
+    return Object.fromEntries(Object.entries(result).sort(([left], [right]) => left.localeCompare(right)));
+}
+export function externalConfirmationActor(confirmation) {
+    if (!confirmation.actor)
+        return null;
+    return {
+        id: confirmation.actor.id,
+        role: confirmation.actor.role,
+        authority_kind: confirmation.actor.authority_kind,
+    };
+}
+export function compiledExternalConfirmationIdentityAssurance(compiled, confirmationRef) {
+    return (compiled.external_confirmation_identity_assurances?.[confirmationRef] ??
+        null);
+}
+export async function verifyExternalConfirmationAttestation(input) {
+    const issues = [];
+    const assurance = input.assurance;
+    if (!assurance || assurance.scheme !== "ed25519")
+        return {
+            verified: false,
+            issues: ["blocking_actor_identity_not_ed25519"],
+        };
+    if (input.record.attestation.scheme !== assurance.scheme)
+        issues.push("attestation_scheme_mismatch");
+    if (input.record.attestation.key_id !== assurance.key_id)
+        issues.push("attestation_key_id_mismatch");
+    let publicKeyBytes;
+    try {
+        const file = await assertProtectedRepositoryFile(input.repository, path.resolve(input.repository, ...assurance.public_key_ref.split("/")), `external_confirmation_public_key:${input.confirmation_ref}`);
+        const info = await stat(file);
+        if (info.size > MAX_PUBLIC_KEY_BYTES)
+            throw new Error(`public_key_too_large:${info.size}`);
+        publicKeyBytes = await readFile(file);
+        if (sha256Hex(publicKeyBytes) !== assurance.public_key_sha256)
+            issues.push("public_key_identity_stale");
+    }
+    catch (error) {
+        issues.push(`public_key_invalid:${message(error)}`);
+        return { verified: false, issues };
+    }
+    if (issues.length)
+        return { verified: false, issues };
+    try {
+        const key = assertEd25519PublicKey(publicKeyBytes, input.confirmation_ref);
+        const signature = Buffer.from(input.record.attestation.signature_base64, "base64");
+        const verified = verify(null, Buffer.from(externalConfirmationV2SignablePayload(input.record), "utf8"), key, signature);
+        return {
+            verified,
+            issues: verified ? [] : ["attestation_signature_invalid"],
+        };
+    }
+    catch (error) {
+        return {
+            verified: false,
+            issues: [`attestation_verification_failed:${message(error)}`],
+        };
+    }
+}
+function assertEd25519PublicKey(bytes, confirmationRef) {
+    let key;
+    try {
+        key = createPublicKey(bytes);
+    }
+    catch (error) {
+        throw new Error(`external_confirmation_public_key_invalid:${confirmationRef}:${message(error)}`);
+    }
+    if (key.type !== "public" || key.asymmetricKeyType !== "ed25519")
+        throw new Error(`external_confirmation_public_key_not_ed25519:${confirmationRef}`);
+    return key;
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/lib/long-task-external-confirmation-challenge.d.ts

@@ -0,0 +1,23 @@
+import type { CompiledDeliveryContractV2 } from "./long-task-delivery-types.js";
+export interface ExternalConfirmationChallengeV1 {
+    schema_version: "long-task-external-confirmation-challenge-v1";
+    confirmation_ref: string;
+    compiled_identity: string;
+    authority_revision: number;
+    challenge: string;
+    rotated_at: string;
+    challenge_state_sha256: string;
+}
+export interface ExternalConfirmationChallengeContext {
+    repository: string;
+    workdir: string;
+    compiled: Pick<CompiledDeliveryContractV2, "compiled_identity" | "authority_revision">;
+}
+export declare function externalConfirmationChallengePath(workdir: string, confirmationRef: string): string;
+export declare function readOrCreateExternalConfirmationChallenge(context: ExternalConfirmationChallengeContext, confirmationRef: string): Promise<ExternalConfirmationChallengeV1>;
+export declare function rotateExternalConfirmationChallenge(context: ExternalConfirmationChallengeContext, confirmationRef: string): Promise<ExternalConfirmationChallengeV1>;
+export declare function readExternalConfirmationChallenge(repository: string, workdir: string, confirmationRef: string): Promise<{
+    challenge: ExternalConfirmationChallengeV1 | null;
+    error: string | null;
+}>;
+export declare function captureStoredExternalConfirmationChallengeIdentities(repository: string, workdir: string, confirmationRefs: readonly string[]): Promise<Record<string, string>>;

package/dist/lib/long-task-external-confirmation-challenge.js

@@ -0,0 +1,164 @@
+import { randomBytes } from "node:crypto";
+import { lstat, open, readFile, rename, rm } from "node:fs/promises";
+import path from "node:path";
+import { assertProtectedRepositoryFile, assertSafeRepositoryFilePath, ensureSafeRepositoryDirectory, } from "./repository-path-safety.js";
+import { runtimePath } from "./long-task-state.js";
+import { canonicalJson, canonicalValueJson, sha256Hex, } from "./strict-codec.js";
+const CHALLENGE_FOLDER = "external-confirmations/challenges";
+const MAX_CHALLENGE_RECORD_BYTES = 16 * 1024;
+const HASH = /^[a-f0-9]{64}$/u;
+const CHALLENGE = /^[A-Za-z0-9_-]{43}$/u;
+export function externalConfirmationChallengePath(workdir, confirmationRef) {
+    assertConfirmationKey(confirmationRef);
+    return runtimePath(workdir, `${CHALLENGE_FOLDER}/${confirmationRef}.json`);
+}
+export async function readOrCreateExternalConfirmationChallenge(context, confirmationRef) {
+    const current = await readExternalConfirmationChallenge(context.repository, context.workdir, confirmationRef);
+    if (current.error)
+        throw new Error(`external_confirmation_challenge_invalid:${confirmationRef}:${current.error}`);
+    if (current.challenge &&
+        current.challenge.compiled_identity ===
+            context.compiled.compiled_identity &&
+        current.challenge.authority_revision === context.compiled.authority_revision)
+        return current.challenge;
+    return rotateExternalConfirmationChallenge(context, confirmationRef);
+}
+export async function rotateExternalConfirmationChallenge(context, confirmationRef) {
+    const unsigned = {
+        schema_version: "long-task-external-confirmation-challenge-v1",
+        confirmation_ref: confirmationRef,
+        compiled_identity: context.compiled.compiled_identity,
+        authority_revision: context.compiled.authority_revision,
+        challenge: randomBytes(32).toString("base64url"),
+        rotated_at: new Date().toISOString(),
+    };
+    const record = parseChallenge({
+        ...unsigned,
+        challenge_state_sha256: sha256Hex(canonicalValueJson(unsigned)),
+    });
+    await writeChallenge(context.repository, context.workdir, record);
+    return record;
+}
+export async function readExternalConfirmationChallenge(repository, workdir, confirmationRef) {
+    const file = externalConfirmationChallengePath(workdir, confirmationRef);
+    const status = await lstat(file).catch((error) => {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    });
+    if (!status)
+        return { challenge: null, error: null };
+    try {
+        const protectedFile = await assertProtectedRepositoryFile(repository, file, `external_confirmation_challenge:${confirmationRef}`);
+        if (status.size > MAX_CHALLENGE_RECORD_BYTES)
+            throw new Error(`challenge_record_too_large:${status.size}`);
+        return {
+            challenge: parseChallenge(JSON.parse(await readFile(protectedFile, "utf8"))),
+            error: null,
+        };
+    }
+    catch (error) {
+        return { challenge: null, error: message(error) };
+    }
+}
+export async function captureStoredExternalConfirmationChallengeIdentities(repository, workdir, confirmationRefs) {
+    const result = {};
+    for (const confirmationRef of [...new Set(confirmationRefs)].sort()) {
+        const file = externalConfirmationChallengePath(workdir, confirmationRef);
+        const status = await lstat(file).catch((error) => {
+            if (error.code === "ENOENT")
+                return null;
+            throw error;
+        });
+        if (!status) {
+            result[confirmationRef] = "absent";
+            continue;
+        }
+        const protectedFile = await assertProtectedRepositoryFile(repository, file, `external_confirmation_challenge:${confirmationRef}`);
+        result[confirmationRef] =
+            `sha256:${sha256Hex(await readFile(protectedFile))}`;
+    }
+    return result;
+}
+async function writeChallenge(repository, workdir, record) {
+    const file = externalConfirmationChallengePath(workdir, record.confirmation_ref);
+    await ensureSafeRepositoryDirectory(repository, repositoryRelative(repository, path.dirname(file)), `external_confirmation_challenge_folder:${record.confirmation_ref}`);
+    await assertSafeRepositoryFilePath(repository, repositoryRelative(repository, file), `external_confirmation_challenge:${record.confirmation_ref}`, { destinationMayBeAbsent: true });
+    const temporary = `${file}.tmp-${process.pid}-${Date.now()}`;
+    const handle = await open(temporary, "wx");
+    try {
+        await handle.writeFile(canonicalJson(record), "utf8");
+        await handle.sync();
+    }
+    catch (error) {
+        await handle.close().catch(() => undefined);
+        await rm(temporary, { force: true });
+        throw error;
+    }
+    await handle.close();
+    try {
+        await rename(temporary, file);
+    }
+    catch (error) {
+        await rm(temporary, { force: true });
+        throw error;
+    }
+}
+function parseChallenge(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("challenge_record_not_object");
+    const row = value;
+    const expectedKeys = [
+        "schema_version",
+        "confirmation_ref",
+        "compiled_identity",
+        "authority_revision",
+        "challenge",
+        "rotated_at",
+        "challenge_state_sha256",
+    ];
+    const actualKeys = Object.keys(row).sort();
+    if (actualKeys.join("\0") !== [...expectedKeys].sort().join("\0"))
+        throw new Error("challenge_record_keys_invalid");
+    if (row.schema_version !== "long-task-external-confirmation-challenge-v1")
+        throw new Error("challenge_record_schema_invalid");
+    if (typeof row.confirmation_ref !== "string" ||
+        !/^[a-z0-9][a-z0-9-]*$/u.test(row.confirmation_ref))
+        throw new Error("challenge_confirmation_ref_invalid");
+    if (typeof row.compiled_identity !== "string" ||
+        !HASH.test(row.compiled_identity))
+        throw new Error("challenge_compiled_identity_invalid");
+    if (!Number.isSafeInteger(row.authority_revision) ||
+        row.authority_revision < 0)
+        throw new Error("challenge_authority_revision_invalid");
+    if (typeof row.challenge !== "string" || !CHALLENGE.test(row.challenge))
+        throw new Error("challenge_value_invalid");
+    if (typeof row.rotated_at !== "string" ||
+        !Number.isFinite(Date.parse(row.rotated_at)) ||
+        new Date(Date.parse(row.rotated_at)).toISOString() !== row.rotated_at)
+        throw new Error("challenge_timestamp_invalid");
+    if (typeof row.challenge_state_sha256 !== "string" ||
+        !HASH.test(row.challenge_state_sha256))
+        throw new Error("challenge_state_hash_invalid");
+    const record = row;
+    const { challenge_state_sha256: _hash, ...unsigned } = record;
+    if (sha256Hex(canonicalValueJson(unsigned)) !== record.challenge_state_sha256)
+        throw new Error("challenge_state_integrity_mismatch");
+    return record;
+}
+function repositoryRelative(repository, candidate) {
+    const relative = path.relative(path.resolve(repository), path.resolve(candidate));
+    if (!relative ||
+        relative === ".." ||
+        relative.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relative))
+        throw new Error("external_confirmation_challenge_outside_repository");
+    return relative.replace(/\\/gu, "/");
+}
+function assertConfirmationKey(value) {
+    if (!/^[a-z0-9][a-z0-9-]*$/u.test(value))
+        throw new Error(`external_confirmation_key_invalid:${value}`);
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/lib/long-task-external-confirmation-context.d.ts

@@ -0,0 +1,14 @@
+import type { CompiledDeliveryContractV2, WorkspaceManifestV2 } from "./long-task-delivery-types.js";
+import type { ExternalConfirmationCandidateV1, ExternalConfirmationRecord } from "./long-task-external-confirmation-types.js";
+import type { SemanticFactManifestV1 } from "./semantic-fact-types.js";
+export interface ExternalAuthorityContextV1 {
+    repository: string;
+    workdir: string;
+    compiled: CompiledDeliveryContractV2;
+    manifest: WorkspaceManifestV2;
+    candidate: ExternalConfirmationCandidateV1;
+    candidate_dirty: string[];
+    semantic_manifest: SemanticFactManifestV1;
+}
+export declare function loadExternalAuthorityContext(workdirInput: string, requireCleanCandidate: boolean): Promise<ExternalAuthorityContextV1>;
+export declare function readSubmittedExternalConfirmationRecord(recordPathInput: string): Promise<ExternalConfirmationRecord>;