approval-md 0.3.0 → 0.4.0

package/dist/src/channels/relay-server.js

@@ -0,0 +1,295 @@
+/**
+ * The authenticated relay channel: its HTTP receiver (SPEC.md §10.3, APRV-455).
+ *
+ * The sibling of `channels/telegram-webhook.ts`, and deliberately the same
+ * shape: one header, one path, one method, one bounded body, a loopback bind by
+ * default with the operator's proxy terminating TLS, a refusal carried as a
+ * body with a frozen code, and no refusal ever written to the log. What differs
+ * is what arrives. A Telegram delivery is an Update the channel parses; a relay
+ * post is a gesture whose shape `channels/relay.ts` closes, whose freshness and
+ * nonce this file checks, and which `applyRelayGesture` turns into a log event
+ * through `recordChannelDecision`, the one place a reported gesture becomes one.
+ *
+ * ## The secret first
+ *
+ * `x-approval-relay-secret` is compared before the URL is parsed, the method is
+ * read or a byte of the body is consumed. A caller without it learns only that
+ * something refused. The comparison is over SHA-256 digests under
+ * `timingSafeEqual`, constant-time and length-independent, and a request
+ * carrying the header twice is refused rather than resolved, because Node joins
+ * repeats and the value compared would not be the value a reader names. These
+ * are the webhook's three rules, for the webhook's reasons.
+ *
+ * ## Why this is its own port and its own secret
+ *
+ * `approval serve` answers two bearer credentials, the agent's and the
+ * tenant's, and NEITHER may reach a decision: grant, reject and attest are
+ * human-only verbs that serve does not publish. This receiver answers a third
+ * credential held by a third party (the operator's control plane), and it is
+ * reachable only from the process `approval channel relay` starts. Nothing in
+ * `src/serve/` or `src/mcp/` imports this module, the verb registry marks the
+ * verb `human_only` so no wrapper publishes it, and `tests/channel-relay.test.ts`
+ * pins both.
+ *
+ * ## Replay
+ *
+ * Every gesture carries a nonce and an `issued_at`. The nonce is claimed in a
+ * ledger of exclusively linked files under the gate's `daemon/` directory before the
+ * gesture is applied, so a replayed post is refused `relay-nonce-replayed`
+ * whether it arrives at this process, after its restart, or at a second relay
+ * on the same gate; a post older than the window is refused
+ * `relay-gesture-stale` after the ledger has forgotten it. The gate is the
+ * belt: a decision a replay did reach would be refused `already-decided`.
+ */
+import { createHash, timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+import { RELAY_DEFAULT_HOST, RELAY_DEFAULT_PORT, RELAY_DRAIN_LIMIT_BYTES, RELAY_MAX_BODY_BYTES, RELAY_PATH, RELAY_REFUSAL_CODES, RELAY_SECRET_HEADER, applyRelayGesture, parseRelayGesture, relayGestureFresh, relayRefusal, } from "./relay.js";
+/** How long {@link RelayHandle.close} waits for requests in flight. */
+export const RELAY_CLOSE_TIMEOUT_MS = 10_000;
+function digest(value) {
+    return createHash("sha256").update(value, "utf8").digest();
+}
+/** Is `offered` the secret? Constant-time over equal-length digests. */
+export function relaySecretMatches(expected, offered) {
+    if (offered === null)
+        return false;
+    return timingSafeEqual(digest(expected), digest(offered));
+}
+/** The one secret header offered, `null` for none, `"duplicate"` for more than one. */
+export function relaySecretHeaderOf(rawHeaders) {
+    const values = [];
+    for (let index = 0; index + 1 < rawHeaders.length; index += 2) {
+        const name = rawHeaders[index];
+        if (name !== undefined && name.toLowerCase() === RELAY_SECRET_HEADER) {
+            values.push(rawHeaders[index + 1] ?? "");
+        }
+    }
+    if (values.length === 0)
+        return null;
+    if (values.length > 1)
+        return "duplicate";
+    return values[0] ?? "";
+}
+async function readBody(req) {
+    const chunks = [];
+    let size = 0;
+    let oversized = false;
+    const tooLarge = {
+        ok: false,
+        code: "relay-body-too-large",
+        message: `request body exceeds ${String(RELAY_MAX_BODY_BYTES)} bytes`,
+    };
+    try {
+        for await (const chunk of req) {
+            const buffer = chunk;
+            size += buffer.length;
+            if (size > RELAY_MAX_BODY_BYTES) {
+                // Drained rather than answered mid-upload, for the webhook's reason: a
+                // response written while the client is still writing closes the socket
+                // under it, and the caller sees a transport error instead of a code.
+                oversized = true;
+                chunks.length = 0;
+                if (size > RELAY_DRAIN_LIMIT_BYTES) {
+                    req.destroy();
+                    break;
+                }
+                continue;
+            }
+            chunks.push(buffer);
+        }
+        if (oversized)
+            return tooLarge;
+    }
+    catch (cause) {
+        if (oversized)
+            return tooLarge;
+        return {
+            ok: false,
+            code: "relay-body-unreadable",
+            message: cause instanceof Error ? cause.message : String(cause),
+        };
+    }
+    return { ok: true, text: Buffer.concat(chunks).toString("utf8") };
+}
+function emptyRefusals() {
+    const counts = {};
+    for (const code of RELAY_REFUSAL_CODES)
+        counts[code] = 0;
+    return counts;
+}
+/** Start the receiver. Resolves once bound; rejects when the bind fails. */
+export async function serveRelay(options) {
+    const host = options.host ?? RELAY_DEFAULT_HOST;
+    const now = options.now ?? (() => Date.now());
+    const complain = options.log ??
+        ((message) => {
+            process.stderr.write(`${message}\n`);
+        });
+    const stats = { requests: 0, gestures: 0, refusals: emptyRefusals() };
+    const sockets = new Set();
+    let inFlight = 0;
+    let closed = null;
+    function send(res, response) {
+        const bytes = Buffer.from(JSON.stringify(response.body), "utf8");
+        res.writeHead(response.status, {
+            "content-type": "application/json",
+            "content-length": bytes.length,
+            "cache-control": "no-store",
+        });
+        res.end(bytes);
+    }
+    /** Counted, said on stderr, answered with its code. Never an event. */
+    function refuse(res, status, code, message) {
+        stats.refusals[code] += 1;
+        complain(`approval: relay refused a post (${code}): ${message}`);
+        send(res, relayRefusal(status, code, message));
+    }
+    const http = createServer((req, res) => {
+        void (async () => {
+            stats.requests += 1;
+            inFlight += 1;
+            try {
+                const offered = relaySecretHeaderOf(req.rawHeaders);
+                if (offered === "duplicate") {
+                    refuse(res, 401, "relay-duplicate-secret-header", `this request carries more than one ${RELAY_SECRET_HEADER} header; exactly one is accepted`);
+                    return;
+                }
+                if (!relaySecretMatches(options.secret, offered)) {
+                    refuse(res, 401, "relay-secret-mismatch", offered === null
+                        ? `no ${RELAY_SECRET_HEADER} header. A post without the relay's secret decides nothing and is not written to the log`
+                        : `the ${RELAY_SECRET_HEADER} header is not this relay's secret. Nothing reached the gate and nothing was appended`);
+                    return;
+                }
+                let url;
+                try {
+                    url = new URL(req.url ?? "/", `http://${req.headers.host ?? host}`);
+                }
+                catch {
+                    refuse(res, 400, "relay-malformed-request", "the request line and Host header do not form a URL");
+                    return;
+                }
+                if (url.pathname !== RELAY_PATH) {
+                    refuse(res, 404, "relay-unknown-path", `no endpoint at ${url.pathname}; the relay answers ${RELAY_PATH}`);
+                    return;
+                }
+                const method = req.method ?? "GET";
+                if (method !== "POST") {
+                    refuse(res, 405, "relay-method-not-allowed", `${RELAY_PATH} answers POST, not ${method}`);
+                    return;
+                }
+                const body = await readBody(req);
+                if (!body.ok) {
+                    refuse(res, body.code === "relay-body-too-large" ? 413 : 400, body.code, body.message);
+                    return;
+                }
+                let decoded;
+                try {
+                    decoded = JSON.parse(body.text);
+                }
+                catch (cause) {
+                    refuse(res, 400, "relay-body-unreadable", `request body is not JSON: ${cause instanceof Error ? cause.message : String(cause)}`);
+                    return;
+                }
+                const parsed = parseRelayGesture(decoded);
+                if (!parsed.ok) {
+                    refuse(res, 400, parsed.code, parsed.message);
+                    return;
+                }
+                const gesture = parsed.gesture;
+                const nowMs = now();
+                if (!relayGestureFresh(gesture.issuedAtMs, nowMs)) {
+                    refuse(res, 400, "relay-gesture-stale", `issued_at ${new Date(gesture.issuedAtMs).toISOString()} is more than five minutes from this relay's clock (${new Date(nowMs).toISOString()}); a gesture is carried while the person who made it is still there, and an old one is refused rather than honoured`);
+                    return;
+                }
+                // Claimed BEFORE the gesture is applied, so a replay racing the
+                // original loses at the file system rather than at the gate. A claim
+                // that cannot be recorded fails closed: replay protection that could
+                // not be promised is not offered as though it were.
+                const claim = options.ledger.claim(gesture.nonce, nowMs);
+                if (claim === "replayed") {
+                    refuse(res, 409, "relay-nonce-replayed", "this nonce was already used. Each gesture carries its own; a retry is a new post with a new nonce, and the gate answers a repeated decision already-decided");
+                    return;
+                }
+                if (claim !== "claimed") {
+                    refuse(res, 503, "relay-nonce-unavailable", `the nonce ledger could not record this gesture (${claim.error}), so a replay of it could not be refused later; nothing was decided`);
+                    return;
+                }
+                let response;
+                try {
+                    response = applyRelayGesture(options.logPath, gesture, options);
+                }
+                catch (cause) {
+                    refuse(res, 500, "relay-handler-failed", `applying the gesture failed (${cause instanceof Error ? cause.message : String(cause)}); read the log for what, if anything, was appended`);
+                    return;
+                }
+                stats.gestures += 1;
+                if (options.afterGesture !== undefined) {
+                    try {
+                        options.afterGesture(response);
+                    }
+                    catch {
+                        // A reporting hook that throws must not turn an answered gesture
+                        // into a failed request.
+                    }
+                }
+                send(res, response);
+            }
+            catch (cause) {
+                if (!res.headersSent) {
+                    refuse(res, 500, "relay-handler-failed", `the request failed: ${cause instanceof Error ? cause.message : String(cause)}`);
+                }
+                else {
+                    res.end();
+                }
+            }
+            finally {
+                inFlight -= 1;
+            }
+        })();
+    });
+    http.on("connection", (socket) => {
+        sockets.add(socket);
+        socket.on("close", () => sockets.delete(socket));
+    });
+    await new Promise((settle, fail) => {
+        const onError = (cause) => fail(cause);
+        http.once("error", onError);
+        http.listen(options.port ?? RELAY_DEFAULT_PORT, host, () => {
+            http.off("error", onError);
+            settle();
+        });
+    });
+    const address = http.address();
+    const boundPort = typeof address === "object" && address !== null ? address.port : (options.port ?? RELAY_DEFAULT_PORT);
+    const boundHost = typeof address === "object" && address !== null ? address.address : host;
+    async function stop() {
+        const accepted = new Promise((settle) => {
+            http.close(() => settle());
+        });
+        const deadline = Date.now() + (options.closeTimeoutMs ?? RELAY_CLOSE_TIMEOUT_MS);
+        while (inFlight > 0 && Date.now() < deadline) {
+            await new Promise((settle) => {
+                setTimeout(settle, 5).unref?.();
+            });
+        }
+        if (inFlight > 0) {
+            complain(`approval: relay: ${String(inFlight)} request(s) still in flight at the close deadline; closing anyway`);
+        }
+        for (const socket of sockets)
+            socket.destroy();
+        sockets.clear();
+        await accepted;
+    }
+    return {
+        host: boundHost,
+        port: boundPort,
+        path: RELAY_PATH,
+        stats: () => ({ ...stats, refusals: { ...stats.refusals } }),
+        inFlight: () => inFlight,
+        close: () => {
+            closed ??= stop();
+            return closed;
+        },
+    };
+}
+//# sourceMappingURL=relay-server.js.map

package/dist/src/channels/relay-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-server.js","sourceRoot":"","sources":["../../../src/channels/relay-server.ts"],"names":[],"mappings":"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"}

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;