approval-md 0.0.1 → 0.2.0

package/dist/src/core/policy-proposal.d.ts

@@ -0,0 +1,265 @@
+/**
+ * The attestation ceremony, collected through a channel (APRV-109, amended
+ * SPEC.md §10.1/§10.3/§11).
+ *
+ * ## The problem
+ *
+ * Attestation is human-only (`core/attest.ts`), and identity is
+ * config-declared, so the two policy ceremonies — `policy attest` and `policy
+ * amend` — required the human to be at a terminal. Every other decision in this
+ * system had already been reduced to a tap on a phone; the one act that decides
+ * which rules are in force had not. This module is the missing half: an agent
+ * prepares the policy edit and appends a *proposal*, a channel puts it in front
+ * of the approver like any other manual prompt, and the tap appends the
+ * `policy.updated` attestation under the human identity the listener holds,
+ * exactly as a grant lands today.
+ *
+ * ## What is computed, and why it has to be
+ *
+ * A proposal carries three things a channel renders: the SHA-256 of the policy
+ * file's exact bytes, the semantic diff of what those bytes change about class
+ * resolution, and the load advisory. **All three are derived here from the
+ * bytes** — none is accepted from the proposing agent. {@link ProposeInput}
+ * has no field for a hash, a diff or a verdict, so the refusal of a
+ * caller-authored value is structural in the same way the refusal of a
+ * caller-supplied `ts` is (amended SPEC.md §8, A2). An agent that could author
+ * the diff summary could show an approver one story and attest another file.
+ *
+ * The BASELINE the diff is taken against is the one place a caller supplies
+ * material, and it is checked rather than trusted: bytes whose own SHA-256 is
+ * not the latest attested hash are refused as a baseline and the proposal falls
+ * to hash-only mode. That is `cli/amend.ts`'s rule ("a baseline nobody can
+ * verify is not a baseline"), enforced here so every caller inherits it.
+ *
+ * ## Fail closed, in this order
+ *
+ * - A policy file that cannot be read proposes nothing.
+ * - A live file that already matches its attestation proposes nothing: there is
+ *   no amendment to sign, and a prompt for one would ask a human to re-attest
+ *   bytes already in force.
+ * - A rendered diff larger than {@link ATTESTATION_DIFF_MAX_CHARS} REFUSES
+ *   (`diff-too-large`) rather than truncating. A phone that shows two thirds of
+ *   a policy change collects a signature for the third it did not show, and the
+ *   repair — read it at a terminal and run `approval policy amend` there — is a
+ *   real repair rather than a smaller lie.
+ * - A tap whose proposal's bytes are no longer the bytes on disk refuses
+ *   `proposal-stale` and attests nothing. The hash the human was shown is the
+ *   hash that gets attested, or nothing does.
+ * - A decline, a supersession and a lapsed deadline all attest nothing. Only
+ *   {@link decideAttestation}`(…, "attest", …)` ever appends a `policy.updated`.
+ *
+ * Everything that writes here goes through `core/log.ts`'s `appendEvent` with a
+ * compare-and-append precondition and a runtime-assigned timestamp, so the new
+ * records inherit the same write-boundary discipline as the rest of the gate.
+ */
+import { type ClockOptions } from "./clock.js";
+import { type AppendOptions, type EventRecord } from "./log.js";
+import type { GateRefusal } from "./gate.js";
+/**
+ * The event an agent appends to ask for an attestation.
+ *
+ * Named `proposed` rather than `requested` deliberately: `approval.requested`
+ * is the approval lifecycle, with its own TTL, its own budgets and its own
+ * grant. This is a different question with a different answer event, and giving
+ * it the same word would invite a reader — or a projection — to treat a policy
+ * attestation as an ordinary authorization.
+ */
+export declare const PROPOSAL_EVENT = "policy.proposed";
+/** The event a decline appends. An attestation appends `policy.updated`. */
+export declare const DECLINE_EVENT = "policy.declined";
+/**
+ * The idempotency key an attestation prompt is rendered under.
+ *
+ * `policy.attest:<sha256>` — derived from the proposed bytes and from nothing
+ * else, so two proposals of the same policy text carry the same key and a tap
+ * on either answers the same question. It is also what
+ * `channels/contract.ts` routes on: a gesture whose key starts with this prefix
+ * becomes an attestation, never a grant.
+ */
+export declare const ATTESTATION_KEY_PREFIX = "policy.attest:";
+/** The action class an attestation prompt is resolved and rendered under. */
+export declare const ATTESTATION_CLASS = "policy.edit";
+/** `policy.attest:<sha256>` for the given policy bytes. */
+export declare function attestationActionKey(sha256: string): string;
+/** Is this an attestation prompt's key rather than an ordinary action's? */
+export declare function isAttestationActionKey(actionKey: string): boolean;
+/** The proposed policy hash named by an attestation key, or `null`. */
+export declare function attestationKeySha256(actionKey: string): string | null;
+/**
+ * The largest rendered diff a channel prompt may carry, in characters.
+ *
+ * Telegram's hard limit is 4096 characters for one message and the prompt
+ * carries a dozen other lines besides the diff, so this is the budget the
+ * *smallest* supported channel can show whole. It is a refusal threshold and
+ * never a truncation point: see the module header.
+ */
+export declare const ATTESTATION_DIFF_MAX_CHARS = 2400;
+/** The same bound, in lines: a diff nobody will scroll is a diff nobody reads. */
+export declare const ATTESTATION_DIFF_MAX_LINES = 60;
+/** The load advisory a channel renders beside the diff. */
+export interface LoadAdvisory {
+    ok: boolean;
+    /** The load failure's machine-readable code, or `null` on a clean load. */
+    code: string | null;
+    message: string | null;
+}
+/** The semantic diff summary a channel renders, as the log records it. */
+export interface DiffSummary {
+    /** False in hash-only mode: no verifiable baseline, so no semantic diff. */
+    available: boolean;
+    /** Why the diff is unavailable; `null` when it is available. */
+    reason: string | null;
+    /** The rendered diff, line by line, exactly as a channel prints it. */
+    lines: string[];
+    /** The one-line headline (`3 class resolution(s), 1 default(s)`). */
+    headline: string;
+    /** The SHA-256 of the baseline the diff was taken against, when there was one. */
+    baseline_sha256: string | null;
+}
+/** What {@link proposeAttestation} was asked to propose. */
+export interface ProposeInput {
+    /** The policy file whose bytes are being proposed. */
+    policyPath: string;
+    /**
+     * The previously-attested policy TEXT, for the semantic diff.
+     *
+     * Checked, never trusted: bytes whose SHA-256 is not the latest attestation's
+     * are refused as a baseline and the proposal falls to hash-only mode with the
+     * reason recorded. Callers recover them from `HEAD:<path>` (`cli/amend.ts`);
+     * a caller with nothing to offer passes nothing.
+     */
+    baseline?: Uint8Array | null;
+    /**
+     * The proposer's own words about the amendment. CLAIMED, and rendered as
+     * such: it is the one field on the prompt the runtime does not stand behind.
+     */
+    note?: string;
+    /**
+     * When the proposing process stops waiting (RFC 3339). Display only, and it
+     * can only raise urgency: see `ChannelRequest.waiting`.
+     */
+    waitUntil?: string;
+}
+/** Options for both verbs: the append's, plus the clock and the schema dir. */
+export interface ProposalOptions extends ClockOptions {
+    schemaDir?: string;
+    append?: AppendOptions;
+    /** Where the full policy text is stored for the channel to display. */
+    payloadStoreDir?: string;
+}
+export type ProposeResult = {
+    ok: true;
+    record: EventRecord;
+    sha256: string;
+    diff: DiffSummary;
+    load: LoadAdvisory;
+} | GateRefusal;
+export type AttestationDecision = "attest" | "decline";
+export type DecideAttestationResult = {
+    ok: true;
+    decision: AttestationDecision;
+    record: EventRecord;
+    sha256: string;
+} | GateRefusal;
+/**
+ * The policy file a proposal concerns, discovered the way `loadPolicy` does so
+ * the proposed file and the enforced file are never two different files.
+ */
+export declare function proposalPolicyPath(dir: string): string;
+/** The load advisory for policy text, as a channel renders it. */
+export declare function adviseLoad(policyPath: string, text: string, schemaDir?: string): LoadAdvisory;
+/** The rendered size of a diff summary, as the channel budget counts it. */
+export declare function diffSize(summary: DiffSummary): {
+    chars: number;
+    lines: number;
+};
+/**
+ * The semantic diff between the attested baseline and the proposed bytes.
+ *
+ * Hash-only mode (`available: false`) whenever the baseline cannot be *proved*
+ * to be the attested text: no baseline was offered, none was ever attested, or
+ * the offered bytes hash to something other than the attestation. The reason is
+ * recorded so a channel can print it instead of a diff, which is the honest
+ * rendering of "we cannot show you what this changes".
+ */
+export declare function summarizeDiff(policyPath: string, baseline: Uint8Array | null | undefined, live: Uint8Array, attestedSha256: string | null, schemaDir?: string): DiffSummary;
+/** The stored value a channel displays as the prompt's full payload. */
+export declare function proposalPayloadValue(policyPath: string, text: string): Record<string, unknown>;
+/**
+ * Append a `policy.proposed` asking a human to attest `policyPath`'s bytes.
+ *
+ * The record's payload is the prompt: `sha256`, `diff` and `load` are all
+ * derived here, `note` and `wait_until` are the proposer's and are labelled
+ * claimed by every channel. `payload_hash` binds the full policy text stored
+ * beside the log, so the approver can read the whole file rather than only the
+ * summary (SPEC.md §10.4).
+ *
+ * No attestation is required to append one. That is the point of the verb: the
+ * live policy is mid-amendment and therefore unattested, which is exactly the
+ * state in which every other gate operation refuses. This one asks a human to
+ * end that state.
+ */
+export declare function proposeAttestation(logPath: string, input: ProposeInput, actor: string, options?: ProposalOptions): ProposeResult;
+/** What became of a proposal, derived from the log and from nothing else. */
+export type ProposalState = 
+/** Nobody has answered, nothing supersedes it, and its deadline has not passed. */
+"open"
+/** A human attested these bytes: a `policy.updated` carries the same hash. */
+ | "attested"
+/** A human declined: a `policy.declined` names this proposal. */
+ | "declined"
+/** A newer proposal for the same policy path replaced it. */
+ | "superseded"
+/** Its `wait_until` passed with no answer. Nothing was attested. */
+ | "expired";
+export interface ProposalDerivation {
+    seq: number;
+    actionKey: string;
+    sha256: string;
+    state: ProposalState;
+    record: EventRecord;
+}
+/** Every `policy.proposed` record in the log, in append order. */
+export declare function proposalRecords(records: readonly EventRecord[]): EventRecord[];
+/**
+ * Derive one proposal's state at `now`.
+ *
+ * Terminal states are read off the log; `expired` is arithmetic on the
+ * proposer's own `wait_until` and materialises no event, because a lapsed
+ * attestation prompt has nothing to record: nothing was attested, and the
+ * proposal record already says everything a reader needs. That is the
+ * fail-closed reading — a prompt nobody answered leaves the policy exactly as
+ * unattested as it was.
+ */
+export declare function proposalState(records: readonly EventRecord[], seq: number, now: string): ProposalDerivation | null;
+/** Every proposal still awaiting a human answer at `now`, in log order. */
+export declare function openProposals(records: readonly EventRecord[], now: string): ProposalDerivation[];
+/** The open proposal whose bytes hash to `sha256`, or `null`. */
+export declare function openProposalFor(records: readonly EventRecord[], sha256: string, now: string): ProposalDerivation | null;
+/** Options for {@link decideAttestation}. */
+export interface DecideAttestationOptions extends ProposalOptions {
+    /** The approver's free-text note, recorded on the answer. */
+    note?: string;
+    /** Where `APPROVAL.md` lives, when it is not the proposal's own directory. */
+    policyPath?: string;
+    /** The channel delivery id this gesture answered, for audit. */
+    batchDeliveryId?: string;
+}
+/**
+ * Answer a proposal: attest the bytes the prompt displayed, or decline them.
+ *
+ * Human-only, in code — the same rule `core/attest.ts` enforces, restated here
+ * because this is a second door onto the same act and the rule must hold for
+ * every caller and not only for the CLI's.
+ *
+ * **The attested hash is the hash the prompt displayed.** Before anything is
+ * appended the live file is re-read and re-hashed, and any difference refuses
+ * `proposal-stale`: the human signed for bytes they were shown, and bytes that
+ * changed underneath the prompt are a different policy that has to be proposed
+ * again. This is the one check that makes "the phone shows the diff and the
+ * hash" mean anything.
+ *
+ * A decline appends `policy.declined` and attests nothing. So does a lapsed
+ * deadline, by appending nothing at all.
+ */
+export declare function decideAttestation(logPath: string, seq: number, decision: AttestationDecision, actor: string, options?: DecideAttestationOptions): DecideAttestationResult;