approval-md 0.3.0 → 0.4.1

package/dist/src/channels/relay.d.ts

@@ -0,0 +1,273 @@
+/**
+ * The authenticated relay channel: its protocol (SPEC.md §10.3, APRV-455).
+ *
+ * Agent Village residents review their approval.md settings in the Edge City
+ * onboarding app, and that review is meant to be the attestation of the policy
+ * in force. The app signs the resident in through EdgeOS, and the operator's
+ * control plane is what holds that session. This module is the daemon's side
+ * of the hop from there: a gesture the control plane carries, attributed to the
+ * EdgeOS `/humans/me` id of the session that made it, arriving over an
+ * authenticated HTTP post (`channels/relay-server.ts`) and turned into a log
+ * event by the SAME function a Telegram tap goes through.
+ *
+ * ## What the relay is trusted for, and what it is not
+ *
+ * The daemon trusts the relay's report of WHO acted, exactly as it trusts the
+ * Telegram Bot API's report of `callback_query.from.id`. That is operator
+ * trust (APRV-422: no hosted service has authority over decisions), and it is
+ * the whole of what the shared secret buys: a post that carries it is a report
+ * from the operator's relay, and a post that does not is nothing. Every
+ * question of AUTHORITY is answered here, by the runtime, from the verified log
+ * and the attested policy:
+ *
+ * - which approver the account is, by `core/sender-identity.ts` against the
+ *   attested mapping, exactly as a tap is resolved;
+ * - whether that approver may decide this request, attest this policy, or
+ *   neither, by `core/gate.ts` and `core/policy-proposal.ts`, unchanged;
+ * - whether the request is still answerable (expiry, policy drift, an earlier
+ *   answer), by the same gate, with the same codes.
+ *
+ * The relay holds NO human identity of its own. A Telegram listener launched
+ * `--as human:carter` falls back to that identity for a channel the policy maps
+ * no sender for; this surface does not, ever (`requireSenderMapping`). A post
+ * naming an account the attested policy does not map is refused
+ * `sender-unmapped` with one `audit.decision_refused`, and a policy that maps
+ * nobody on `edgeos` refuses every gesture the same way.
+ *
+ * ## The body, closed
+ *
+ * ```json
+ * { "gesture": "attest" | "decline", "policy_sha256": "<64 hex>",
+ *   "sender": { "channel": "edgeos", "id": "<EdgeOS /humans/me id>" },
+ *   "nonce": "<16..128 of A-Z a-z 0-9 _ ->", "issued_at": "<RFC 3339 UTC>" }
+ * { "gesture": "grant" | "reject", "action_key": "<the request's key>",
+ *   "sender": { ... }, "nonce": "...", "issued_at": "..." }
+ * { "gesture": "propose", "policy_sha256": "<64 hex>",
+ *   "nonce": "...", "issued_at": "..." }
+ * ```
+ *
+ * Unknown keys are refused rather than ignored, so a field that looks like it
+ * carries authority (an `actor`, a second sender, a `ts`) cannot ride along on
+ * a valid post and be read by something later. `issued_at` is used for one
+ * thing only, the freshness window that bounds how long a nonce must be
+ * remembered; it is never recorded, and every record's `ts` is still the
+ * runtime's own (SPEC.md §11.1 invariant 2).
+ *
+ * ## Why `propose` exists here
+ *
+ * The control plane renders the resident's policy and writes it into the
+ * store; somebody then has to append the `policy.proposed` an acceptance
+ * answers. The existing route for that is `approval policy amend`, which is a
+ * git-aware terminal ceremony that blocks for its own `--wait`. `propose` is the
+ * same `core/policy-proposal.ts` call, under the same secret, recorded under the
+ * actor the operator started the relay with (`--proposer`), and it returns at
+ * once. It binds the hash the control plane rendered: bytes on disk that are not
+ * the bytes it names are refused, so the prompt the resident answers is the file
+ * the control plane showed them.
+ *
+ * It also admits the one proposal `policy amend` refuses: bytes that are
+ * ALREADY the policy in force (`ProposeInput.reaffirm`). The onboarding review
+ * most residents make is "accept, unchanged", and the operator attested those
+ * bytes at provisioning (APRV-449). The reaffirmation changes the attester of
+ * record and nothing else: same hash, a diff that reads "no semantic change",
+ * and an acceptance resolved against the policy in force like any other.
+ *
+ * ## No token leaves this surface
+ *
+ * A grant may mint a single-use execution token for the deciding surface
+ * (manual delivery). A relay is not a place a token can go: the control plane
+ * is not the requester and the HTTP response is not a secrets channel. The
+ * token `recordChannelDecision` returns is dropped here, unread, and the
+ * response says only whether one was minted. The deployments this exists for
+ * mint none (a harness-executed request) or seal it to the requester's own
+ * key, so nothing is lost in practice, and the residual is stated rather than
+ * hidden: a manual-delivery request granted through the relay has a token
+ * nobody holds, and its requester asks again.
+ */
+import type { DecideOptions } from "../core/gate.js";
+import { type ChannelSender } from "../core/sender-identity.js";
+/** The channel name every relay gesture is recorded under, and its senders' namespace. */
+export declare const RELAY_CHANNEL = "edgeos";
+/** The header the shared secret travels in, lowercased as Node presents it. */
+export declare const RELAY_SECRET_HEADER = "x-approval-relay-secret";
+/** The one path this transport answers. */
+export declare const RELAY_PATH = "/relay/gesture";
+/** The interface it binds when the operator names none. Loopback, always. */
+export declare const RELAY_DEFAULT_HOST = "127.0.0.1";
+/** The port it binds when the operator names none: `serve` is 4682, the webhook 4683. */
+export declare const RELAY_DEFAULT_PORT = 4684;
+/** Largest body accepted. A gesture is a handful of short strings. */
+export declare const RELAY_MAX_BODY_BYTES: number;
+/** How much of an oversized body is drained before the socket is dropped. */
+export declare const RELAY_DRAIN_LIMIT_BYTES: number;
+/**
+ * How far `issued_at` may sit from this process's clock, either side.
+ *
+ * Five minutes: a control plane and a sandbox on the same platform agree to
+ * well under a second, and a gesture older than this was not made by a person
+ * who is still looking at the screen that made it.
+ */
+export declare const RELAY_GESTURE_WINDOW_MS: number;
+/**
+ * How long a claimed nonce is remembered.
+ *
+ * Longer than the whole window a fresh gesture can occupy (issued up to one
+ * window in the future, accepted up to one window late), with a minute of
+ * margin, so a replay is refused by the nonce while it is still fresh and by
+ * the window once the nonce is forgotten. There is no instant at which neither
+ * holds.
+ */
+export declare const RELAY_NONCE_RETENTION_MS: number;
+/**
+ * How long a relay proposal stays open (APRV-455 refuter L2).
+ *
+ * The onboarding review is answered in the screen that rendered it, so an hour
+ * is generous; past it the prompt retires from every channel queue by
+ * derivation, and a control plane whose resident came back later proposes
+ * again. Until a proposal is attested the bytes on disk are not the policy in
+ * force, so the control plane restores the in-force bytes when a proposal is
+ * declined or lapses.
+ */
+export declare const RELAY_PROPOSAL_TTL_MS: number;
+/** The actor a proposal is recorded under when the operator names none. */
+export declare const RELAY_DEFAULT_PROPOSER = "agent:edgeos-relay";
+/** The gestures, closed. */
+export declare const RELAY_GESTURES: readonly ["propose", "attest", "decline", "grant", "reject"];
+export type RelayGestureName = (typeof RELAY_GESTURES)[number];
+/**
+ * Every refusal THIS transport makes, and nothing else. Frozen, per SPEC.md
+ * §11.1 invariant 6, and pinned by `conformance/vectors/refusal-unions.v1.json`
+ * because the control plane on the other side of the hop is a second
+ * implementation that branches on these strings.
+ *
+ * Refusals the GATE or the decision surface makes (`sender-unmapped`,
+ * `expired`, `policy-drift`, `already-decided`, `proposal-stale`,
+ * `proposal-not-found`, ...) are not here: they arrive verbatim under
+ * `refusal` in the response body, from their own unions, exactly as a Telegram
+ * tap would surface them.
+ *
+ * None of these appends to the log. A post the relay refuses is a fact about
+ * the transport and is counted and reported on stderr, because an endpoint
+ * that wrote its refusals into the approval log would let anyone who can reach
+ * it grow the record a human is asked to trust.
+ */
+export declare const RELAY_REFUSAL_CODES: readonly [
+/** No secret header, or one that is not the launch environment's secret. */
+"relay-secret-mismatch", 
+/** More than one secret header. Malformed, and not resolvable by choosing. */
+"relay-duplicate-secret-header", 
+/** The request line and the Host header do not form a URL. */
+"relay-malformed-request", 
+/** A path this transport does not serve. */
+"relay-unknown-path", 
+/** The right path, a method other than POST. */
+"relay-method-not-allowed", 
+/** Larger than {@link RELAY_MAX_BODY_BYTES}. */
+"relay-body-too-large", 
+/** The body could not be read off the socket, or is not JSON. */
+"relay-body-unreadable", 
+/** JSON that is not a gesture of the closed shape. */
+"relay-body-invalid", 
+/**
+ * The sender is not an EdgeOS account this transport can report: a channel
+ * other than `edgeos`, or an id outside the grammar `senders.edgeos` pins.
+ */
+"relay-sender-invalid", 
+/** `issued_at` is further than {@link RELAY_GESTURE_WINDOW_MS} from now. */
+"relay-gesture-stale", 
+/** This nonce was already used within {@link RELAY_NONCE_RETENTION_MS}. */
+"relay-nonce-replayed", 
+/**
+ * The nonce ledger could not be written, so a replay could not be refused.
+ * Fails closed: nothing is decided without it.
+ */
+"relay-nonce-unavailable", 
+/**
+ * `propose` named a hash that is not the hash of the policy file on disk.
+ * Distinct from the gate's `proposal-stale`, which is the same fact found at
+ * ACCEPTANCE: this one is found before anything is proposed.
+ */
+"relay-policy-mismatch", 
+/** The gesture threw while being applied. Nothing is claimed about the log. */
+"relay-handler-failed"];
+export type RelayRefusalCode = (typeof RELAY_REFUSAL_CODES)[number];
+/** A parsed, shape-checked gesture. */
+export type RelayGesture = {
+    gesture: "attest" | "decline";
+    policySha256: string;
+    sender: ChannelSender;
+    nonce: string;
+    issuedAtMs: number;
+} | {
+    gesture: "grant" | "reject";
+    actionKey: string;
+    sender: ChannelSender;
+    nonce: string;
+    issuedAtMs: number;
+} | {
+    gesture: "propose";
+    policySha256: string;
+    nonce: string;
+    issuedAtMs: number;
+};
+export type RelayParse = {
+    ok: true;
+    gesture: RelayGesture;
+} | {
+    ok: false;
+    code: RelayRefusalCode;
+    message: string;
+};
+/**
+ * Check one decoded body against the closed shape.
+ *
+ * Pure: no clock, no file, no log. Freshness and the nonce are the server's,
+ * because both need state this function deliberately does not hold.
+ */
+export declare function parseRelayGesture(value: unknown): RelayParse;
+/** Is `issuedAtMs` within the window of `nowMs`? */
+export declare function relayGestureFresh(issuedAtMs: number, nowMs: number): boolean;
+/** What claiming one nonce came to. */
+export type NonceClaim = "claimed" | "replayed" | {
+    error: string;
+};
+/**
+ * Where used nonces are remembered.
+ *
+ * One file per nonce, named by its SHA-256, written whole to a private temp and
+ * then hard-linked into place, under the gate's own `daemon/` directory. The
+ * file system settles the race: `link` fails with EEXIST exactly as `O_EXCL`
+ * does, so of any number of processes claiming one nonce at once exactly one
+ * wins, and a claim file never exists without the time it was claimed.
+ * That is why two relays on one gate need no lease between them for replay
+ * protection, and why a restart forgets nothing it was still obliged to
+ * remember. Files older than {@link RELAY_NONCE_RETENTION_MS} are pruned.
+ */
+export interface NonceLedger {
+    claim(nonce: string, nowMs: number): NonceClaim;
+}
+/** The file ledger described at {@link NonceLedger}. */
+export declare function fileNonceLedger(dir: string): NonceLedger;
+/** What applying a gesture produced: an HTTP status and the JSON body. */
+export interface RelayResponse {
+    status: number;
+    body: Record<string, unknown>;
+}
+export interface ApplyRelayOptions {
+    /** The gate options a decision runs under: the policy location, the clock. */
+    gateOptions: DecideOptions;
+    /** The actor a `propose` is recorded under. */
+    proposer: string;
+}
+/** A transport refusal as a response. Never appended. */
+export declare function relayRefusal(status: number, code: RelayRefusalCode, message: string): RelayResponse;
+/**
+ * Turn one checked gesture into a log event, or into the refusal that replaces
+ * one.
+ *
+ * Decisions and attestations go through {@link recordChannelDecision}, the one
+ * place a reported gesture becomes a log event, with `requireSenderMapping` set
+ * and the channel named `edgeos`. A proposal goes through `proposeAttestation`.
+ * Nothing here decides anything those two do not already decide.
+ */
+export declare function applyRelayGesture(logPath: string, gesture: RelayGesture, options: ApplyRelayOptions): RelayResponse;