project-tiny-context-harness 0.8.17 → 0.11.0

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

@@ -0,0 +1,387 @@
+import { array, key, literal, nullable, object, repositoryFile, semanticRef, string, text, } from "./long-task-shape-primitives.js";
+import { canonicalValueJson, sha256Hex } from "./strict-codec.js";
+const HASH = /^[a-f0-9]{64}$/u;
+const GIT_OBJECT = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/u;
+const RELEVANT_INPUT = /^(?:bounded|whole):[a-f0-9]{64}$/u;
+const CHALLENGE = /^[A-Za-z0-9_-]{43}$/u;
+export function parseExternalConfirmationRecord(value) {
+    if (value &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        value.schema_version ===
+            "long-task-external-confirmation-record-v2")
+        return parseExternalConfirmationRecordV2(value);
+    return parseExternalConfirmationRecordV1(value);
+}
+export function parseExternalConfirmationRecordV1(value) {
+    const label = "external_confirmation_record";
+    const root = object(value, label, [
+        "schema_version",
+        "confirmation_ref",
+        "compiled_identity",
+        "authority_revision",
+        "candidate",
+        "actor",
+        "session",
+        "results",
+        "artifact_hashes",
+        "relevant_input_identity",
+        "record_sha256",
+    ]);
+    const schemaVersion = literal(root.schema_version, ["long-task-external-confirmation-record-v1"], `${label}.schema_version`);
+    const candidate = object(root.candidate, `${label}.candidate`, [
+        "git_head",
+        "git_tree",
+        "snapshot_sha256",
+    ]);
+    const actor = object(root.actor, `${label}.actor`, [
+        "id",
+        "role",
+        "authority_kind",
+    ]);
+    const session = object(root.session, `${label}.session`, [
+        "id",
+        "target_ref",
+        "environment_identity",
+        "started_at",
+        "completed_at",
+    ]);
+    const startedAt = timestamp(session.started_at, `${label}.session.started_at`);
+    const completedAt = timestamp(session.completed_at, `${label}.session.completed_at`);
+    if (Date.parse(completedAt) < Date.parse(startedAt))
+        invalid(`${label}.session`, "completed_at precedes started_at");
+    const results = array(root.results, `${label}.results`).map((item, index) => parseResult(item, `${label}.results[${index}]`));
+    if (!results.length)
+        invalid(`${label}.results`, "must not be empty");
+    unique(results.map((result) => result.obligation_ref), `${label}.results.obligation_ref`);
+    const artifactHashes = hashMap(root.artifact_hashes, `${label}.artifact_hashes`);
+    const record = {
+        schema_version: schemaVersion,
+        confirmation_ref: key(root.confirmation_ref, `${label}.confirmation_ref`),
+        compiled_identity: hash(root.compiled_identity, `${label}.compiled_identity`),
+        authority_revision: nonnegativeInteger(root.authority_revision, `${label}.authority_revision`),
+        candidate: {
+            git_head: gitObject(candidate.git_head, `${label}.candidate.git_head`),
+            git_tree: gitObject(candidate.git_tree, `${label}.candidate.git_tree`),
+            snapshot_sha256: hash(candidate.snapshot_sha256, `${label}.candidate.snapshot_sha256`),
+        },
+        actor: {
+            id: string(actor.id, `${label}.actor.id`),
+            role: string(actor.role, `${label}.actor.role`),
+            authority_kind: literal(actor.authority_kind, ["human", "expert", "external_system"], `${label}.actor.authority_kind`),
+        },
+        session: {
+            id: string(session.id, `${label}.session.id`),
+            target_ref: semanticRef(session.target_ref, `${label}.session.target_ref`),
+            environment_identity: string(session.environment_identity, `${label}.session.environment_identity`),
+            started_at: startedAt,
+            completed_at: completedAt,
+        },
+        results,
+        artifact_hashes: artifactHashes,
+        relevant_input_identity: relevantInputIdentity(root.relevant_input_identity, `${label}.relevant_input_identity`),
+        record_sha256: hash(root.record_sha256, `${label}.record_sha256`),
+    };
+    assertJsonValue(record, label, 0);
+    const expectedHash = externalConfirmationRecordHash(record);
+    if (record.record_sha256 !== expectedHash)
+        invalid(`${label}.record_sha256`, "integrity mismatch");
+    return record;
+}
+export function parseExternalConfirmationRecordV2(value) {
+    const label = "external_confirmation_record";
+    const root = object(value, label, [
+        "schema_version",
+        "confirmation_ref",
+        "compiled_identity",
+        "authority_revision",
+        "candidate",
+        "challenge",
+        "actor",
+        "session",
+        "results",
+        "artifact_snapshots",
+        "relevant_input_identity",
+        "attestation",
+        "record_sha256",
+    ]);
+    const candidate = parseCandidate(root.candidate, `${label}.candidate`);
+    const actor = parseActor(root.actor, `${label}.actor`);
+    const session = parseSession(root.session, `${label}.session`);
+    const results = array(root.results, `${label}.results`).map((item, index) => parseResultV2(item, `${label}.results[${index}]`));
+    if (!results.length)
+        invalid(`${label}.results`, "must not be empty");
+    unique(results.map((result) => result.obligation_ref), `${label}.results.obligation_ref`);
+    const attestation = object(root.attestation, `${label}.attestation`, [
+        "scheme",
+        "key_id",
+        "signature_base64",
+    ]);
+    const record = {
+        schema_version: literal(root.schema_version, ["long-task-external-confirmation-record-v2"], `${label}.schema_version`),
+        confirmation_ref: key(root.confirmation_ref, `${label}.confirmation_ref`),
+        compiled_identity: hash(root.compiled_identity, `${label}.compiled_identity`),
+        authority_revision: nonnegativeInteger(root.authority_revision, `${label}.authority_revision`),
+        candidate,
+        challenge: challenge(root.challenge, `${label}.challenge`),
+        actor,
+        session,
+        results,
+        artifact_snapshots: parseArtifactSnapshots(root.artifact_snapshots, `${label}.artifact_snapshots`),
+        relevant_input_identity: relevantInputIdentity(root.relevant_input_identity, `${label}.relevant_input_identity`),
+        attestation: {
+            scheme: literal(attestation.scheme, ["ed25519"], `${label}.attestation.scheme`),
+            key_id: key(attestation.key_id, `${label}.attestation.key_id`),
+            signature_base64: ed25519Signature(attestation.signature_base64, `${label}.attestation.signature_base64`),
+        },
+        record_sha256: hash(root.record_sha256, `${label}.record_sha256`),
+    };
+    assertJsonValue(record, label, 0);
+    if (record.record_sha256 !== externalConfirmationRecordV2Hash(record))
+        invalid(`${label}.record_sha256`, "integrity mismatch");
+    return record;
+}
+export function externalConfirmationRecordHash(record) {
+    const { record_sha256: _recordHash, ...unsigned } = record;
+    return sha256Hex(canonicalValueJson(unsigned));
+}
+export function signExternalConfirmationRecordV1(unsigned) {
+    const record = {
+        ...unsigned,
+        record_sha256: externalConfirmationRecordHash(unsigned),
+    };
+    return parseExternalConfirmationRecordV1(record);
+}
+export function externalConfirmationRecordV2Hash(record) {
+    return sha256Hex(canonicalValueJson(externalConfirmationV2IntegrityPayload(record)));
+}
+export function externalConfirmationV2SignablePayload(record) {
+    const { signature_base64: _signature, ...attestation } = record.attestation;
+    return canonicalValueJson({ ...record, attestation });
+}
+function externalConfirmationV2IntegrityPayload(record) {
+    const { record_sha256: _recordHash, ...withoutHash } = record;
+    const { signature_base64: _signature, ...attestation } = withoutHash.attestation;
+    return { ...withoutHash, attestation };
+}
+function parseCandidate(value, label) {
+    const row = object(value, label, ["git_head", "git_tree", "snapshot_sha256"]);
+    return {
+        git_head: gitObject(row.git_head, `${label}.git_head`),
+        git_tree: gitObject(row.git_tree, `${label}.git_tree`),
+        snapshot_sha256: hash(row.snapshot_sha256, `${label}.snapshot_sha256`),
+    };
+}
+function parseActor(value, label) {
+    const row = object(value, label, ["id", "role", "authority_kind"]);
+    return {
+        id: string(row.id, `${label}.id`),
+        role: string(row.role, `${label}.role`),
+        authority_kind: literal(row.authority_kind, ["human", "expert", "external_system"], `${label}.authority_kind`),
+    };
+}
+function parseSession(value, label) {
+    const row = object(value, label, [
+        "id",
+        "target_ref",
+        "environment_identity",
+        "started_at",
+        "completed_at",
+    ]);
+    const startedAt = timestamp(row.started_at, `${label}.started_at`);
+    const completedAt = timestamp(row.completed_at, `${label}.completed_at`);
+    if (Date.parse(completedAt) < Date.parse(startedAt))
+        invalid(label, "completed_at precedes started_at");
+    return {
+        id: string(row.id, `${label}.id`),
+        target_ref: semanticRef(row.target_ref, `${label}.target_ref`),
+        environment_identity: string(row.environment_identity, `${label}.environment_identity`),
+        started_at: startedAt,
+        completed_at: completedAt,
+    };
+}
+function parseResultV2(value, label) {
+    const row = object(value, label, [
+        "obligation_ref",
+        "fact_ref",
+        "claim_ref",
+        "applicability_ref",
+        "result_kind",
+        "verdict",
+        "evidence_refs",
+    ], ["actual", "rationale"]);
+    const resultKind = literal(row.result_kind, ["actual", "judgment"], `${label}.result_kind`);
+    const verdict = literal(row.verdict, ["passed", "failed", "unable"], `${label}.verdict`);
+    const evidenceRefs = array(row.evidence_refs, `${label}.evidence_refs`).map((item, index) => repositoryFile(item, `${label}.evidence_refs[${index}]`));
+    unique(evidenceRefs, `${label}.evidence_refs`);
+    if (!evidenceRefs.length)
+        invalid(`${label}.evidence_refs`, "must not be empty");
+    const rationale = Object.hasOwn(row, "rationale")
+        ? text(row.rationale, `${label}.rationale`)
+        : undefined;
+    if (resultKind === "judgment") {
+        if (Object.hasOwn(row, "actual"))
+            invalid(`${label}.actual`, "is not allowed for judgment");
+        if (!rationale)
+            invalid(`${label}.rationale`, "is required for judgment");
+    }
+    else if (verdict !== "unable" && !Object.hasOwn(row, "actual"))
+        invalid(`${label}.actual`, "is required for an objective result");
+    else if (verdict === "unable" && !rationale)
+        invalid(`${label}.rationale`, "is required when unable");
+    const result = {
+        obligation_ref: semanticRef(row.obligation_ref, `${label}.obligation_ref`),
+        fact_ref: nullable(row.fact_ref, (item) => semanticRef(item, `${label}.fact_ref`)),
+        claim_ref: semanticRef(row.claim_ref, `${label}.claim_ref`),
+        applicability_ref: semanticRef(row.applicability_ref, `${label}.applicability_ref`),
+        result_kind: resultKind,
+        ...(Object.hasOwn(row, "actual") ? { actual: row.actual } : {}),
+        verdict,
+        evidence_refs: evidenceRefs,
+        ...(rationale ? { rationale } : {}),
+    };
+    if (Object.hasOwn(result, "actual"))
+        assertJsonValue(result.actual, `${label}.actual`, 0);
+    return result;
+}
+function parseArtifactSnapshots(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        invalid(label, "must be an object");
+    const rows = [];
+    for (const [rawRef, rawSnapshot] of Object.entries(value)) {
+        const evidenceRef = repositoryFile(rawRef, `${label}.${rawRef}`);
+        const snapshot = object(rawSnapshot, `${label}.${rawRef}`, [
+            "sha256",
+            "size_bytes",
+            "media_type",
+            "store_ref",
+        ]);
+        rows.push([
+            evidenceRef,
+            {
+                sha256: hash(snapshot.sha256, `${label}.${rawRef}.sha256`),
+                size_bytes: nonnegativeInteger(snapshot.size_bytes, `${label}.${rawRef}.size_bytes`),
+                media_type: nullable(snapshot.media_type, (item) => string(item, `${label}.${rawRef}.media_type`)),
+                store_ref: repositoryFile(snapshot.store_ref, `${label}.${rawRef}.store_ref`),
+            },
+        ]);
+    }
+    if (!rows.length)
+        invalid(label, "must not be empty");
+    unique(rows.map(([evidenceRef]) => evidenceRef), label);
+    return Object.fromEntries(rows.sort(([left], [right]) => left.localeCompare(right)));
+}
+function parseResult(value, label) {
+    const row = object(value, label, [
+        "obligation_ref",
+        "fact_ref",
+        "claim_ref",
+        "applicability_ref",
+        "verdict",
+        "evidence_refs",
+    ], ["actual", "rationale"]);
+    const evidenceRefs = array(row.evidence_refs, `${label}.evidence_refs`).map((item, index) => repositoryFile(item, `${label}.evidence_refs[${index}]`));
+    unique(evidenceRefs, `${label}.evidence_refs`);
+    if (!evidenceRefs.length)
+        invalid(`${label}.evidence_refs`, "must not be empty");
+    const result = {
+        obligation_ref: semanticRef(row.obligation_ref, `${label}.obligation_ref`),
+        fact_ref: nullable(row.fact_ref, (item) => semanticRef(item, `${label}.fact_ref`)),
+        claim_ref: semanticRef(row.claim_ref, `${label}.claim_ref`),
+        applicability_ref: semanticRef(row.applicability_ref, `${label}.applicability_ref`),
+        ...(Object.hasOwn(row, "actual") ? { actual: row.actual } : {}),
+        verdict: literal(row.verdict, ["passed", "failed", "unable"], `${label}.verdict`),
+        evidence_refs: evidenceRefs,
+        ...(Object.hasOwn(row, "rationale")
+            ? { rationale: text(row.rationale, `${label}.rationale`) }
+            : {}),
+    };
+    if (Object.hasOwn(result, "actual"))
+        assertJsonValue(result.actual, `${label}.actual`, 0);
+    return result;
+}
+function hashMap(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        invalid(label, "must be an object");
+    const rows = [];
+    for (const [rawPath, rawHash] of Object.entries(value))
+        rows.push([
+            repositoryFile(rawPath, `${label}.${rawPath}`),
+            hash(rawHash, `${label}.${rawPath}`),
+        ]);
+    if (!rows.length)
+        invalid(label, "must not be empty");
+    unique(rows.map(([file]) => file), label);
+    return Object.fromEntries(rows.sort(([left], [right]) => left.localeCompare(right)));
+}
+function hash(value, label) {
+    const result = string(value, label);
+    if (!HASH.test(result))
+        invalid(label, "must be a lowercase SHA-256 digest");
+    return result;
+}
+function gitObject(value, label) {
+    const result = string(value, label);
+    if (!GIT_OBJECT.test(result))
+        invalid(label, "must be a Git object id");
+    return result;
+}
+function relevantInputIdentity(value, label) {
+    const result = string(value, label);
+    if (!RELEVANT_INPUT.test(result))
+        invalid(label, "must be bounded:<sha256> or whole:<sha256>");
+    return result;
+}
+function challenge(value, label) {
+    const result = string(value, label);
+    if (!CHALLENGE.test(result))
+        invalid(label, "must be a canonical 256-bit base64url challenge");
+    return result;
+}
+function ed25519Signature(value, label) {
+    const result = string(value, label);
+    const decoded = Buffer.from(result, "base64");
+    if (decoded.length !== 64 || decoded.toString("base64") !== result)
+        invalid(label, "must be a canonical 64-byte Ed25519 signature");
+    return result;
+}
+function timestamp(value, label) {
+    const result = string(value, label);
+    const epoch = Date.parse(result);
+    if (!Number.isFinite(epoch) || new Date(epoch).toISOString() !== result)
+        invalid(label, "must be a canonical ISO-8601 timestamp");
+    return result;
+}
+function nonnegativeInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        invalid(label, "must be a non-negative safe integer");
+    return value;
+}
+function unique(values, label) {
+    if (new Set(values).size !== values.length)
+        invalid(label, "must not contain duplicates");
+}
+function assertJsonValue(value, label, depth) {
+    if (depth > 64)
+        invalid(label, "JSON nesting exceeds 64 levels");
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            invalid(label, "number must be finite");
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => assertJsonValue(item, `${label}[${index}]`, depth + 1));
+        return;
+    }
+    if (value && typeof value === "object") {
+        for (const [name, item] of Object.entries(value))
+            assertJsonValue(item, `${label}.${name}`, depth + 1);
+        return;
+    }
+    invalid(label, "must be JSON-serializable");
+}
+function invalid(label, message) {
+    throw new Error(`external_confirmation_record_invalid:${label}:${message}`);
+}

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

@@ -0,0 +1,10 @@
+import type { ExternalConfirmationRecord, ExternalConfirmationRecordV2 } from "./long-task-external-confirmation-types.js";
+export interface StoredExternalConfirmationRecordV1 {
+    record: ExternalConfirmationRecord | null;
+    error: string | null;
+}
+export declare function externalConfirmationRecordPath(workdir: string, confirmationRef: string): string;
+export declare function captureStoredExternalConfirmationRecordIdentities(repository: string, workdir: string, confirmationRefs: readonly string[]): Promise<Record<string, string>>;
+export declare function readStoredExternalConfirmationRecord(repository: string, workdir: string, confirmationRef: string): Promise<StoredExternalConfirmationRecordV1>;
+export declare function writeStoredExternalConfirmationRecord(repository: string, workdir: string, record: ExternalConfirmationRecordV2): Promise<string>;
+export declare function revokeStoredExternalConfirmationRecord(repository: string, workdir: string, confirmationRef: string): Promise<boolean>;

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

@@ -0,0 +1,109 @@
+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 { parseExternalConfirmationRecord, parseExternalConfirmationRecordV2, } from "./long-task-external-confirmation-shape.js";
+import { canonicalJson, sha256Hex } from "./strict-codec.js";
+const EXTERNAL_CONFIRMATIONS_FOLDER = "external-confirmations";
+const MAX_RECORD_BYTES = 16 * 1024 * 1024;
+export function externalConfirmationRecordPath(workdir, confirmationRef) {
+    assertConfirmationKey(confirmationRef);
+    return runtimePath(workdir, `${EXTERNAL_CONFIRMATIONS_FOLDER}/${confirmationRef}.json`);
+}
+export async function captureStoredExternalConfirmationRecordIdentities(repository, workdir, confirmationRefs) {
+    const result = {};
+    for (const confirmationRef of [...new Set(confirmationRefs)].sort()) {
+        const file = externalConfirmationRecordPath(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_record:${confirmationRef}`);
+        result[confirmationRef] =
+            `sha256:${sha256Hex(await readFile(protectedFile))}`;
+    }
+    return result;
+}
+export async function readStoredExternalConfirmationRecord(repository, workdir, confirmationRef) {
+    const file = externalConfirmationRecordPath(workdir, confirmationRef);
+    const status = await lstat(file).catch((error) => {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    });
+    if (!status)
+        return { record: null, error: null };
+    try {
+        const protectedFile = await assertProtectedRepositoryFile(repository, file, `external_confirmation_record:${confirmationRef}`);
+        if (status.size > MAX_RECORD_BYTES)
+            throw new Error(`external_confirmation_record_too_large:${confirmationRef}:${status.size}`);
+        return {
+            record: parseExternalConfirmationRecord(JSON.parse(await readFile(protectedFile, "utf8"))),
+            error: null,
+        };
+    }
+    catch (error) {
+        return { record: null, error: message(error) };
+    }
+}
+export async function writeStoredExternalConfirmationRecord(repository, workdir, record) {
+    const parsed = parseExternalConfirmationRecordV2(record);
+    const folder = path.dirname(externalConfirmationRecordPath(workdir, parsed.confirmation_ref));
+    await ensureSafeRepositoryDirectory(repository, repositoryRelative(repository, folder), `external_confirmation_folder:${parsed.confirmation_ref}`);
+    const file = externalConfirmationRecordPath(workdir, parsed.confirmation_ref);
+    await assertSafeRepositoryFilePath(repository, repositoryRelative(repository, file), `external_confirmation_record:${parsed.confirmation_ref}`, { destinationMayBeAbsent: true });
+    const temporary = `${file}.tmp-${process.pid}-${Date.now()}`;
+    const handle = await open(temporary, "wx");
+    try {
+        await handle.writeFile(canonicalJson(parsed), "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;
+    }
+    return file;
+}
+export async function revokeStoredExternalConfirmationRecord(repository, workdir, confirmationRef) {
+    const file = externalConfirmationRecordPath(workdir, confirmationRef);
+    const status = await lstat(file).catch((error) => {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    });
+    if (!status)
+        return false;
+    const safe = await assertSafeRepositoryFilePath(repository, repositoryRelative(repository, file), `external_confirmation_record:${confirmationRef}`, { destinationMayBeAbsent: true });
+    await rm(safe.absolute, { force: true });
+    return true;
+}
+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_state_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);
+}