@lannguyensi/harness 0.63.0 → 1.0.0

package/dist/policy-packs/builtin/understanding-before-execution/delegation-markers.d.ts

@@ -1,304 +0,0 @@
-/** Directory holding delegation markers, a sibling of `.approvals/` under `generatedDir`. */
-export declare const DELEGATION_MARKER_DIRNAME = ".delegations";
-/**
- * Directory holding the per-child ADOPTED-ENTRY ledgers (once-per-session
- * transcript-capture bookkeeping written by the PreToolUse hook,
- * `hook-pre-tool-use.ts`), a SIBLING of `.delegations/` itself rather than
- * a subdirectory of it: `<generatedDir>/.delegation-adoptions/<sid>`.
- *
- * Defined here (not in `hook-pre-tool-use.ts`, the only writer) so that a
- * reader that never writes a ledger, such as `harness gc`'s delegation
- * sweep, can name the directory without importing a `cli/` module: this
- * file already owns `DELEGATION_MARKER_DIRNAME`, the sibling constant an
- * adoption-ledger reader also needs, and both dirnames traveling together
- * keeps `.delegations/` and its ledger sibling from drifting apart.
- */
-export declare const ADOPTION_LEDGER_DIRNAME = ".delegation-adoptions";
-/**
- * Directory holding the CONVENTIONAL launcher-report copies for the
- * `--report` fallback shape, a SIBLING of `.delegations/` and
- * `.delegation-adoptions/` (same reasoning: a reader that only needs the
- * path convention, such as a future gc sweep, has no business importing
- * the CLI module that writes into it). `harness delegate --report` copies
- * the operator's file here, at `<childSessionId>.md`, and the child's own
- * PreToolUse hook reads back from exactly this path (never the operator's
- * original `--report` argument, which the hook has no way to learn): the
- * conventional path is what lets both sides derive the SAME location from
- * nothing but the child session id, closing the gap that used to leave a
- * report-bound delegation issued and signature-verifiable but never
- * actually checked against a file (agent-tasks 49d1ee41, follow-up to
- * slice 3, agent-tasks 37ad0b05).
- */
-export declare const DELEGATION_REPORT_DIRNAME = ".delegation-reports";
-/**
- * The signed markerId for a child session: `delegation-<child-sid>`.
- * Binding it into the signed payload is what stops a validly signed
- * delegation from being copied onto another child id, or onto a session
- * marker's id, and still verifying (`task-markers.ts` precedent).
- */
-export declare function delegationMarkerIdFor(childSessionId: string): string;
-/**
- * Filesystem path of a child session's delegation marker. Rejects a
- * malformed session id the same way `approvalMarkerPathFor` does (the
- * value lands in a `path.join` verbatim).
- */
-export declare function delegationMarkerPathFor(generatedDir: string, childSessionId: string): string;
-/**
- * Filesystem path of a child session's CONVENTIONAL launcher-report copy:
- * `<generatedDir>/.delegation-reports/<childSessionId>.md`. Always `.md`,
- * regardless of the extension the operator's original `--report` file
- * carried: the point of the convention is that both `harness delegate`
- * (the writer) and the child's PreToolUse hook (the reader) derive the
- * SAME path from nothing but the child session id, so a preserved
- * extension would only reintroduce a value the hook has no way to learn.
- * Rejects a malformed session id the same way {@link delegationMarkerPathFor}
- * does (the value lands in a `path.join` verbatim).
- */
-export declare function delegationReportPathFor(generatedDir: string, childSessionId: string): string;
-/**
- * sha256 hex of a filesystem path, canonicalized through `realpathSync`
- * when the path exists and through `path.resolve` when it does not.
- *
- * The canonicalization is the point, not an optimization: the parent
- * writing the delegation and the child reporting its cwd routinely spell
- * the same directory differently (on macOS `os.tmpdir()` hands out
- * `/var/folders/...` while the process reports `/private/var/folders/...`,
- * because `/var` is a symlink), and an uncanonicalized comparison would
- * refuse a perfectly legitimate delegation. Falling back to `resolve` for
- * a non-existent path keeps the function total: a path that cannot be
- * canonicalized still hashes deterministically, and a delegation bound to
- * it simply will not match a cwd that resolves elsewhere.
- *
- * Named for its primary use; the fallback shape hashes the launcher-
- * supplied report file's PATH with the same function, so that WHERE the
- * parent put the report is part of what was signed.
- */
-export declare function hashDelegationCwd(targetPath: string): string;
-/** The bindings packed into a delegation's `approvedBy` string. */
-export interface DelegationApprovedByFields {
-    parentSessionId: string;
-    /** sha256 of the child's expected cwd, or `null` for a task-only delegation. */
-    cwdHash: string | null;
-    /** The task id the child is delegated for, or `null` for a cwd-only delegation. */
-    taskId: string | null;
-    /** ISO-8601 instant at which the delegation stops being valid. */
-    expiresAt: string;
-    /** sha256 of the launcher-supplied report file's PATH; present only in the fallback shape. */
-    reportPathHash?: string;
-}
-/**
- * Build the `approvedBy` string a delegation signs:
- * `delegated:<parent>;cwd=<sha256|->;task=<id|->;expires=<iso>` plus
- * `;report=<sha256>` in the fallback shape.
- *
- * Throws on any input that would corrupt the encoding (an empty value, a
- * value carrying a `;` or `=` delimiter or a control character, a
- * malformed parent session id (`rejectMalformedSessionId`), a cwd/report
- * hash that is not a sha256 digest, a non-ISO expiry, or the literal `-`
- * as a task id, which would round-trip as "no task bound"). A silently
- * mis-encoded delegation would be signed and then read back with
- * different bindings than the caller intended, so this fails loudly at
- * the only place that can still tell the difference.
- */
-export declare function buildDelegationApprovedBy(fields: DelegationApprovedByFields): string;
-/** Bindings read back out of a delegation's `approvedBy` string. */
-export interface ParsedDelegationApprovedBy {
-    parentSessionId: string;
-    /** `null` when the delegation binds no cwd (`cwd=-`). */
-    cwdHash: string | null;
-    /** `null` when the delegation binds no task (`task=-`). */
-    taskId: string | null;
-    expiresAt: string;
-    /** Present only in the fallback shape. */
-    reportPathHash?: string;
-}
-export type DelegationApprovedByParse = {
-    ok: true;
-    value: ParsedDelegationApprovedBy;
-} | {
-    ok: false;
-    reason: string;
-};
-/**
- * Strict inverse of {@link buildDelegationApprovedBy}. All four of
- * `delegated`, `cwd`, `task` and `expires` are required and `report` is
- * optional; a missing, duplicated, unknown, empty or malformed segment is
- * an error RESULT, never a default. Segment order is not enforced (the
- * signature already pins the exact bytes), but every other deviation is
- * refused: this string is the only place a delegation's bindings live, so
- * "read it partially and assume the rest" is the one failure mode that
- * would quietly widen a delegation past what the parent signed.
- */
-export declare function parseDelegationApprovedBy(approvedBy: unknown): DelegationApprovedByParse;
-export interface WriteDelegationMarkerOptions {
-    generatedDir: string;
-    /** Session id of the `claude -p` child this delegation authorizes. Becomes the file name. */
-    childSessionId: string;
-    /** Session id of the already-approved parent issuing the delegation. */
-    parentSessionId: string;
-    /** {@link hashDelegationCwd} of the child's expected cwd, or `null` for a task-only delegation. */
-    cwdHash: string | null;
-    /** Task id the child is delegated for, or `null` for a cwd-only delegation. */
-    taskId: string | null;
-    /** ISO-8601 instant the delegation expires at. */
-    expiresAt: string;
-    /** Fallback shape: {@link hashDelegationCwd} of the launcher-supplied report file's path. */
-    reportPathHash?: string;
-    /** Fallback shape: sha256 of that file's CONTENT. Omitted (written as `null`) in the base shape. */
-    reportContentHash?: string;
-    /** Override the issue timestamp for deterministic tests. */
-    now?: Date;
-}
-export type WriteDelegationMarkerResult = {
-    ok: true;
-    filePath: string;
-    markerId: string;
-    approvedAt: string;
-    approvedBy: string;
-} | {
-    ok: false;
-    reason: "signing-key-absent" | "invalid-input" | "write-failed";
-    detail: string;
-};
-/**
- * Write a signed delegation marker through the shared `signMarker` path,
- * under markerId `delegation-<child-sid>`, at
- * `<generatedDir>/.delegations/<child-sid>`. Atomic and mode 0600, like
- * every other marker write.
- *
- * NEVER CREATES THE SIGNING KEY. `signMarker` -> `getOrCreateSigningKey`
- * treats a missing key as a case to REPAIR, generating one and signing
- * with it; key creation is an operator-side act (`harness init`,
- * `harness approve`), and a delegation minted on a machine that never had
- * a key would be a marker signed by whoever asked for it. So this
- * prechecks `signingKeyExists` and returns `signing-key-absent` without
- * reaching the write path at all (ADR threat model (b) item 5, the same
- * rule slice 1's auto path follows).
- *
- * Returns a result rather than throwing, for every failure mode: the
- * callers are a CLI verb and, later, a hook, and both must fail closed
- * with a diagnostic instead of unwinding.
- *
- * Deliberately does NOT refuse a delegation that binds neither cwd nor
- * task. That refusal belongs to the issuing verb (ADR slice 3 acceptance
- * criterion 1) and to `verifyDelegation`, which reports `no_binding`;
- * keeping the writer able to produce one is what lets the test suite
- * exercise that verifier branch against a genuinely signed artifact
- * rather than a hand-rolled fake.
- */
-export declare function writeDelegationMarker(opts: WriteDelegationMarkerOptions): WriteDelegationMarkerResult;
-/**
- * Why a delegation was refused. Every value is reachable and distinct;
- * there is no "unknown" bucket and no branch that falls through to
- * allow.
- */
-export type DelegationRefusalReason = 
-/** No delegation file for this child session (also: a child session id that cannot name a file). */
-"missing"
-/** The file exists but its integrity cannot be established right now: symlink, non-regular, I/O error, or an unavailable signing key. Not a claim of tampering. */
- | "unreadable"
-/** A file was there and its signature does not verify against `delegation-<child-sid>`: unsigned, wrong alg, tampered, or copied from another child's delegation. */
- | "forged"
-/** Validly signed, but its `approvedBy` bindings cannot be read in full. */
- | "unparseable" | "expired" | "cwd_mismatch" | "task_mismatch"
-/** Binds neither a cwd nor a task, so it would authorize the child anywhere, for anything. */
- | "no_binding"
-/**
- * Fallback shape: a stat-only existence probe (`probePathPresence`,
- * `lstat` under the hood) found nothing at the launcher-supplied path.
- * Covers both a genuinely absent path and one lstat cannot reach for any
- * other reason (e.g. EACCES, ENOTDIR): lstat cannot distinguish "nothing
- * is there" from "something is there but unreachable to us", so this
- * reason does not claim to either. A symlink or a directory sitting there
- * IS something lstat can see, so it is not this reason: verification
- * continues past the existence probe. From there a RESOLVABLE symlink is
- * normally caught one step later, at the path-hash comparison
- * (`hashDelegationCwd` resolves it through `realpathSync`, which disagrees
- * with the bind-time hash taken before anything existed at that path), and
- * lands on `report_path_mismatch`; only a DANGLING or looping symlink (or
- * a directory) reaches the full read and lands on `report_content_mismatch`
- * once it cannot produce matching bytes. Checked BEFORE the path hash, so
- * a symlinked temp root (where the missing-path fallback of
- * `hashDelegationCwd` can disagree with the write-time realpath) never
- * turns a plain "the file is gone" into a `report_path_mismatch`. This
- * existence-first order also decides the case where a delegation binds a
- * report path but no `reportContentHash` (a malformed half-binding
- * `writeDelegationMarker` itself refuses to produce, but a hand-signed
- * marker can still carry): an absent file at that path is still
- * `report_missing`, not `report_content_mismatch`, because existence is
- * checked first regardless of what the rest of the binding contains. The
- * mirror case (no report path offered at all) has nothing to lstat and
- * stays `report_path_mismatch`.
- */
- | "report_missing"
-/** Fallback shape: the launcher report is not at the path the parent signed (including when no report path was offered at all). */
- | "report_path_mismatch"
-/** Fallback shape: the launcher report's content is not what the parent signed (including a report that exists but is a symlink, a directory, or otherwise cannot be read as regular file bytes). */
- | "report_content_mismatch";
-export type DelegationVerification = {
-    ok: true;
-    parentSessionId: string;
-    expiresAt: string;
-    boundCwdHash: string | null;
-    boundTaskId: string | null;
-    reportPathHash?: string;
-    /**
-     * Set exactly when `reportPathHash` is set: the launcher report's
-     * bytes as read and content-hash-checked by THIS call, verbatim.
-     * The caller (the hook) persists these bytes directly instead of
-     * re-reading the file itself; a second read would reopen the race
-     * this field exists to close (the file could be rewritten between
-     * verification and a later read).
-     */
-    reportContent?: string;
-} | {
-    ok: false;
-    reason: DelegationRefusalReason;
-    detail: string;
-};
-export interface VerifyDelegationOptions {
-    generatedDir: string;
-    /** The child session whose delegation is being checked. */
-    childSessionId: string;
-    /** The child's actual cwd, or `null` when the caller has none to offer. */
-    cwd: string | null;
-    /** The child's actual task id, or `null` when the caller has none to offer. */
-    taskId: string | null;
-    /** Fallback shape: the launcher-supplied report file the parent bound. */
-    launcherReportPath?: string;
-    /** Override "now" for deterministic tests. */
-    now?: Date;
-}
-/**
- * Gate-side: is there a valid, unexpired, matching delegation for this
- * child session? Checks, in order (ADR slice 3 acceptance criterion 2):
- *
- *   1. the file is present and JSON-readable,
- *   2. its signature verifies against markerId `delegation-<child-sid>`,
- *   3. its `approvedBy` segments parse in full,
- *   4. it binds at least one of cwd / task,
- *   5. it has not expired,
- *   6. the bound cwd hash-matches the caller's cwd,
- *   7. the bound task equals the caller's task,
- *   8. in the fallback shape, the launcher report EXISTS at the offered
- *      path, sits at the bound path, AND hashes to the bound content
- *      (in that order: existence before the path hash, so a missing
- *      file is always `report_missing`, never `report_path_mismatch`).
- *
- * Reads only `.delegations/`; an artifact in `.approvals/` is `missing`
- * here, whatever it contains.
- *
- * NEVER CREATES THE SIGNING KEY, on the READ path either.
- * `verifyMarkerSignature` obtains the key through
- * `getOrCreateSigningKey`, which treats a missing key as a case to
- * REPAIR and generates one; on a machine the operator never initialized
- * that would make a mere gate-time read perform the operator-side act of
- * minting the key. It cannot make a foreign-signed delegation verify, but
- * it does leave a key behind that every LATER write path would then
- * happily sign with, so the never-create rule applies here exactly as it
- * does to `writeDelegationMarker` and to slice 1's auto path. An absent
- * key is reported as `unreadable` (we could not check, not "we checked
- * and it is a forgery"), the same class `verifyMarkerSignature`'s own
- * `key-unavailable` lands in below.
- */
-export declare function verifyDelegation(opts: VerifyDelegationOptions): DelegationVerification;