approval-md 0.3.0 → 0.4.0

package/dist/src/core/daemon-host.js

@@ -0,0 +1,228 @@
+/**
+ * How a daemon process learns its own id, and which ids its policy admits
+ * (APRV-383).
+ *
+ * The other half of `core/daemon-identity.ts`, which holds the grammar, the
+ * process state and the one question the write boundary asks. This half does the
+ * reading: the launch environment, the instance the log belongs to, and the
+ * `daemons` list in an attested policy. It is deliberately NOT imported by
+ * `core/log.ts` — see that module's header for the import cycle this separation
+ * avoids and for why the seam is the right one anyway.
+ *
+ * ## The id
+ *
+ * Two sources, in this order:
+ *
+ * 1. `APPROVAL_DAEMON_ID` in the launch environment. An operator hosting several
+ *    tenants names their processes, and a name a person chose is the one a person
+ *    can recognise on a card, in a log and in an allowlist. It is in the
+ *    environment rather than in a file for the reason every other launch fact is
+ *    (SPEC.md §11.1 invariant 7): the process's operator establishes it, and no
+ *    verb reads it out of the working tree.
+ * 2. Otherwise DERIVED from the instance: `daemon-` plus the eight hex digits
+ *    `core/instance.ts` already computes from the absolute path of the instance's
+ *    `.approval` directory, which `approval doctor` prints as its `keychain-scope`
+ *    suffix and `.approval/env` carries in the open.
+ *
+ * The derived form is what makes AC1's "stable across restarts on the same
+ * machine and keystore" true without storing anything: the input is a directory
+ * path, so a restart, a rebuild of the process and a second daemon started in the
+ * same checkout all derive one id, while a different checkout on the same machine
+ * derives a different one. It is the same identity the keystore items are scoped
+ * by, which is the point — an operator reading `daemon-3f2a9c11` in a record and
+ * `approval-tg-token-3f2a9c11` in `.approval/env` is looking at one gate.
+ *
+ * A random id written to a file was rejected for the reason `core/instance.ts`
+ * rejects it: a file an operator can copy is an identity that travels, and an id
+ * that changed on every restart would make the `daemons` allowlist unwritable.
+ *
+ * ## The allowlist
+ *
+ * Read from the ATTESTED policy and from nothing else, which is invariant 1 doing
+ * its ordinary work: the bytes a human signed are the only bytes a refusal may be
+ * derived from, and a policy file edited since is inoperative. The daemon resolves
+ * it against its own verified read and its own attestation check, never against a
+ * claim from a caller.
+ */
+import { checkAttestation } from "./attest.js";
+import { DAEMON_ID_ENV, declareDaemonIdentity, isDaemonId, setDaemonAllowlist, } from "./daemon-identity.js";
+import { instanceIdFor } from "./instance.js";
+import { loadPolicy } from "./policy-load.js";
+import { readVerifiedRecords } from "./state.js";
+/** The prefix a derived id wears, so the string says what kind of id it is. */
+export const DERIVED_DAEMON_ID_PREFIX = "daemon-";
+/** The id this instance derives when the launch environment declares none. */
+export function derivedDaemonId(logPath) {
+    return `${DERIVED_DAEMON_ID_PREFIX}${instanceIdFor(logPath)}`;
+}
+/**
+ * Resolve the id, preferring an explicit declaration and otherwise deriving one.
+ *
+ * A declared id that fails the grammar is a REFUSAL rather than a fall back to
+ * the derived form: the operator meant the value they set, and a runtime that
+ * quietly substituted another would write records under a name nobody chose and
+ * check them against an allowlist nobody wrote for it. A blank or
+ * whitespace-only value is treated as unset, because an empty variable is how a
+ * shell spells "I did not set this".
+ */
+export function resolveDaemonId(logPath, env = process.env) {
+    const raw = env[DAEMON_ID_ENV];
+    if (raw === undefined || raw.trim().length === 0) {
+        return { ok: true, id: derivedDaemonId(logPath), source: "derived" };
+    }
+    if (!isDaemonId(raw)) {
+        return {
+            ok: false,
+            code: "daemon-id-invalid",
+            declared: raw,
+            message: `${DAEMON_ID_ENV}=${JSON.stringify(raw)} is not a usable daemon id: lowercase letters, digits, \`.\`, \`-\` and \`_\`, starting with a letter or digit, at most 64 characters. Unset it to derive ${derivedDaemonId(logPath)} from this instance`,
+        };
+    }
+    return { ok: true, id: raw, source: "environment" };
+}
+/**
+ * Declare this process's identity into `core/daemon-identity.ts`, and hand back
+ * what was resolved.
+ *
+ * Called by the daemon runtime at construction, beside `markDaemonProcess()`. An
+ * UNUSABLE declared id is still declared — as an identity with no id — because a
+ * daemon that cannot name itself must be refused at the write boundary rather
+ * than left unmarked and writing: the CLI verbs refuse to start on the same
+ * resolution, and this is what closes the gap for a `Daemon` constructed
+ * directly.
+ */
+export function declareDaemonIdentityFor(logPath, env = process.env) {
+    const resolved = resolveDaemonId(logPath, env);
+    declareResolvedDaemonIdentity(resolved);
+    return resolved;
+}
+/**
+ * Declare an identity that was already resolved by {@link resolveDaemonId}
+ * (APRV-448).
+ *
+ * The same declaration {@link declareDaemonIdentityFor} makes, for a process
+ * that resolved its id once at startup and must declare it again somewhere the
+ * environment and the log path are not at hand: `approval serve`'s hook worker
+ * threads, which hold their own copy of this module's state, and the Telegram
+ * webhook listener, whose preparation resolved the id before anything ran. One
+ * resolution, declared in every thread that appends, is what makes the id on a
+ * hook's records the id on a verb's.
+ *
+ * An unusable declared id is declared as an identity with no id, for the reason
+ * {@link declareDaemonIdentityFor} gives: refused at the write boundary rather
+ * than left unmarked and writing.
+ */
+export function declareResolvedDaemonIdentity(resolved) {
+    if (resolved.ok) {
+        declareDaemonIdentity({ id: resolved.id, source: resolved.source });
+    }
+    else {
+        declareDaemonIdentity({ id: null, declared: resolved.declared, source: null });
+    }
+}
+/**
+ * The `daemons` list a LOADED policy declares, or `null` for no restriction.
+ *
+ * `null` for a policy that does not load at all, which looks like a widening and
+ * is not: this function answers "what does this document say", and every caller
+ * that could refuse on the answer requires an ATTESTED policy first
+ * ({@link resolveDaemonAllowlist}). A policy that fails to load restricts
+ * nothing here and makes every class `manual` everywhere else, which is where the
+ * fail-closed behaviour of an unreadable policy lives.
+ */
+export function daemonAllowlistOf(load) {
+    if (!load.ok)
+        return null;
+    const declared = load.policy.daemons;
+    return declared === undefined ? null : declared;
+}
+/**
+ * The allowlist in force, from the attested policy and the verified log.
+ *
+ * `records` are the caller's own VERIFIED records (invariant 1) and `load` its
+ * own policy load; both are passed in rather than read here so that the daemon's
+ * tick does one verified read and one policy load, and so that this function is
+ * pure and exhaustively testable.
+ *
+ * A failure is reported and is NOT a restriction of its own: the caller leaves
+ * whatever was last resolved in force (`core/daemon-identity.ts`'s
+ * `setDaemonAllowlist` is simply not called), so a policy that becomes unreadable
+ * cannot be a way out of the list it carried a moment ago, and a deployment whose
+ * policy was never attested is unrestricted exactly as it was before this key
+ * existed.
+ */
+export function resolveDaemonAllowlist(records, load) {
+    if (!load.ok) {
+        return {
+            ok: false,
+            reason: "policy-unloadable",
+            detail: `the policy could not be loaded (${load.code}), so no \`daemons\` list could be read from it`,
+        };
+    }
+    const attestation = checkAttestation([...records], load.source.path);
+    if (attestation.status !== "attested") {
+        return {
+            ok: false,
+            reason: "policy-not-attested",
+            detail: `the policy at ${load.source.path} is not attested (${attestation.status}), so its \`daemons\` list is not a list a human signed`,
+        };
+    }
+    return { ok: true, allowed: daemonAllowlistOf(load) };
+}
+/**
+ * Resolve the allowlist and put it in force, or leave the previous one standing.
+ *
+ * The one call the daemon's tick makes. It returns the resolution so the caller
+ * can say what happened, and it never widens: on a failure nothing is set.
+ */
+export function refreshDaemonAllowlist(records, load) {
+    const resolution = resolveDaemonAllowlist(records, load);
+    if (resolution.ok)
+        setDaemonAllowlist(resolution.allowed);
+    return resolution;
+}
+/**
+ * The stricter of two allowlists, which never admits an id either of them
+ * refuses (APRV-448 review): `null` (no restriction) yields to a list, and two
+ * lists intersect.
+ *
+ * A thread that has never made a successful resolution of its own (a hook
+ * worker spawned after the policy lost its attestation) starts from the
+ * restriction its listener holds, combined this way with whatever it held
+ * before, so a fresh thread is never a way out of the list in force.
+ */
+export function narrowerAllowlist(a, b) {
+    if (a === null)
+        return b === null ? null : [...b];
+    if (b === null)
+        return [...a];
+    return a.filter((id) => b.includes(id));
+}
+/**
+ * {@link refreshDaemonAllowlist} for a process that has no verified read of its
+ * own in hand (APRV-448): read the store's log through the verified path, load
+ * the policy from `where`, and refresh.
+ *
+ * `approval serve` calls it before every verb call and every hook call, inside
+ * the store lock, and the Telegram webhook listener calls it at startup and on
+ * every dispatch cycle, which is that process's tick. The read is the cached
+ * verified read every other caller in the process shares, so it costs a walk of
+ * what was appended since, never a second walk of the chain.
+ *
+ * A log that does not verify resolves nothing and sets nothing, exactly as an
+ * unattested policy does: the restriction last resolved stays in force, and the
+ * append that follows meets the same unverifiable log on its own path and is
+ * refused there in its own words.
+ */
+export function refreshDaemonAllowlistFrom(logPath, where) {
+    const read = readVerifiedRecords(logPath);
+    if (!read.ok) {
+        return {
+            ok: false,
+            reason: "log-unverified",
+            detail: `the log at ${logPath} did not verify (${read.code}), so no attestation could be checked against it`,
+        };
+    }
+    return refreshDaemonAllowlist(read.records, loadPolicy(where));
+}
+//# sourceMappingURL=daemon-host.js.map

package/dist/src/core/daemon-host.js.map

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

package/dist/src/core/daemon-identity.d.ts

@@ -0,0 +1,238 @@
+/**
+ * WHICH daemon wrote this record, and the check the write boundary runs on it
+ * (APRV-383).
+ *
+ * ## The fact this module is about
+ *
+ * `core/daemon-actor.ts` answers "is this process the daemon". Every record the
+ * daemon appends carried that and nothing more: a generic `system:daemon` actor,
+ * one string, identical on every machine that ever ran one. That is enough while
+ * a gate's daemon is the operator's own process in the operator's own checkout,
+ * and it stops being enough the moment one party HOSTS a daemon for another.
+ * Three properties of that arrangement already hold: authority comes from the
+ * tenant's attested policy and never from the host (§5.2, APRV-324 and 356),
+ * credentials come from the launch environment so one process holds one tenant's
+ * token, and a decision arrives only through the tenant's own sender mapping so
+ * the host cannot mint one. What was missing is the smallest of the four and the
+ * one a tenant reads first: opening their own log and seeing which daemon acted
+ * on their behalf.
+ *
+ * So a daemon-written record carries a `daemon` field naming the instance that
+ * wrote it, and an attested policy MAY list the ids permitted to write
+ * (`daemons`, read by `core/daemon-host.ts`). An id the list does not name is
+ * refused at the write boundary.
+ *
+ * ## What the id is NOT, and this is the important half
+ *
+ * It is a SELF-REPORTED field, so SPEC.md §11.1 invariant 4 governs it
+ * completely: it may raise scrutiny and may never lower it. Concretely, in this
+ * runtime:
+ *
+ * - a listed id gains NOTHING. No verdict, no autonomy, no budget, no floor, no
+ *   sampling draw, no token and no TTL reads this field or the list. Being named
+ *   in `daemons` buys a daemon exactly the ability it had before the key existed;
+ * - an unlisted id is REFUSED, which is the only direction the field moves
+ *   anything, and it moves it strictly towards writing less;
+ * - the id never enters a payload hash and never enters a token. It is a
+ *   top-level record field, so the record's own chain hash covers it the way it
+ *   covers `actor` (a record's provenance has to be part of what the chain
+ *   protects, or it could be edited without breaking the chain), and no bound
+ *   payload, no `payload_hash` and no `token_sha256` is computed over it.
+ *
+ * And it is ATTRIBUTION rather than authorization. A hostile host process holds
+ * the tenant's log handle and can call anything in this module the daemon calls,
+ * exactly as it can call {@link markDaemonProcess}; `core/daemon-actor.ts` states
+ * that boundary and this module inherits it word for word. What the allowlist
+ * catches is the likelier failure and the one nothing caught before: a daemon
+ * started against the wrong tenant's log, a second daemon nobody meant to leave
+ * running, a container rebuilt with a new id, each of which used to write records
+ * indistinguishable from the intended daemon's.
+ *
+ * ## Why the state is module state and not an argument
+ *
+ * For the reason `core/daemon-actor.ts` gives for taking no arguments: a field a
+ * caller passes is a field a caller chooses, and an `appendEvent` option naming
+ * the writing daemon would let any process in this runtime claim to be one. The
+ * daemon runtime declares its own identity once, at construction, through
+ * `core/daemon-host.ts`, and `core/log.ts` READS it. `EventInput` deliberately
+ * has no `daemon` member, and `buildRecord` composes a record field by field, so
+ * a caller that puts the property on its input object anyway is ignored rather
+ * than obeyed.
+ *
+ * ## Which processes declare, and why the stamp does not ask for the mark
+ *
+ * Three processes append on a gate's behalf without being a session, and since
+ * APRV-448 all three declare the same identity through the same two calls in
+ * `core/daemon-host.ts` (`declareDaemonIdentityFor` or
+ * `declareResolvedDaemonIdentity`, then `refreshDaemonAllowlist*`): the daemon
+ * loop (`daemon/daemon.ts`, at construction), `approval serve` (its verbs on the
+ * listener's thread and its hook calls on their worker threads), and `approval
+ * channel telegram webhook`. In a co-located deployment, where a facade, a
+ * daemon and a channel run in one process per tenant, a tenant reading their
+ * own log therefore sees one id on the sweeps and on the actions.
+ *
+ * The stamp is keyed on the DECLARATION, not on `core/daemon-actor.ts`'s mark.
+ * The two answer different questions: the mark says "this process is the daemon
+ * loop" and is what routes an advance under the autonomous
+ * `log.advance.daemon` class (APRV-382), while the declaration says "records
+ * this process writes name this instance". `approval serve` dispatches verbs an
+ * agent asked for, so marking it the daemon to get the stamp would hand its
+ * process the daemon's advance route, a widening nothing here needs. Declaring
+ * without marking stamps and restricts, and widens nothing.
+ *
+ * ## Why this module imports almost nothing
+ *
+ * `core/log.ts` imports it, and `core/log.ts` is the bottom of this codebase's
+ * import graph: `core/instance.ts` (where the derived id comes from) reaches
+ * `core/attest.ts` through `core/env-file.ts`, and `core/attest.ts` spreads
+ * `APPEND_ERROR_CODES` at module scope, so importing the
+ * derivation here would close a cycle whose evaluation order throws before any
+ * test ran. The split is also the right seam on its own terms: what the write
+ * boundary needs is a grammar, a state and one question, and everything that
+ * reads a policy or a filesystem to ANSWER that question lives in
+ * `core/daemon-host.ts`.
+ */
+/**
+ * The environment variable a launch may declare the daemon's id in.
+ *
+ * Beside `APPROVAL_HUMAN` and the credential variables, and in the launch
+ * environment for the same reason they are: SPEC.md §11.1 invariant 7 keeps this
+ * runtime from reading configuration out of the working tree, and a hosted
+ * daemon's id is configuration its OPERATOR sets, never something the tenant's
+ * repository tells the host about itself.
+ */
+export declare const DAEMON_ID_ENV = "APPROVAL_DAEMON_ID";
+/** The longest id this runtime writes or admits. */
+export declare const DAEMON_ID_MAX_LENGTH = 64;
+/** Is `value` a well-formed daemon id? */
+export declare function isDaemonId(value: string): boolean;
+/**
+ * The two ways an append can be refused for the identity of the daemon making
+ * it, spread into `APPEND_ERROR_CODES` by `core/log.ts`.
+ *
+ * Two codes rather than one, because the repairs have nothing in common and
+ * SPEC.md §11.1 invariant 6 is about a caller being able to act on the answer:
+ * one is a line to add to an attested policy, the other is a variable to fix in
+ * the launch environment of a process that should not have started.
+ *
+ * Declared here rather than in `core/log.ts`'s literal list so that the codes and
+ * the logic that emits them cannot drift apart; the union there spreads this one,
+ * exactly as `ATTEST_ERROR_CODES` spreads it.
+ */
+export declare const DAEMON_APPEND_REFUSAL_CODES: readonly [
+/**
+ * The daemon declared an id through {@link DAEMON_ID_ENV} that is not a
+ * well-formed id at all, so no record it wrote could be attributed to anything.
+ *
+ * Refused rather than silently falling back to the derived id, which is the
+ * fail-closed direction twice over: an operator who set the variable meant the
+ * value they set, and a runtime that quietly used a different one would write
+ * records under a name nobody chose, against an allowlist nobody wrote for it.
+ */
+"daemon-id-invalid", 
+/**
+ * The attested policy lists the daemon ids that may write to this log, and this
+ * daemon's id is not among them.
+ *
+ * An ABSENT list is no restriction, not an empty one: a policy that never
+ * declares the key behaves exactly as every policy written before it existed.
+ */
+"daemon-not-allowed"];
+export type DaemonAppendRefusalCode = (typeof DAEMON_APPEND_REFUSAL_CODES)[number];
+/** Where this process's id came from. */
+export type DaemonIdSource = "environment" | "derived";
+/**
+ * What a daemon process has declared about itself, or `null` in a process that
+ * has declared nothing.
+ *
+ * `id` is `null` exactly when {@link DAEMON_ID_ENV} held something unusable: the
+ * state is still declared, because a daemon that cannot name itself must be
+ * REFUSED rather than left unmarked and writing.
+ */
+export interface DaemonIdentity {
+    /** The resolved id, or `null` when the declared one is unusable. */
+    id: string | null;
+    /** The raw value {@link DAEMON_ID_ENV} held, when it held one. */
+    declared: string | null;
+    /** Where {@link id} came from; `null` when there is no id. */
+    source: DaemonIdSource | null;
+    /**
+     * The ids the attested policy admits, or `null` for no restriction.
+     *
+     * `null` is the state a process starts in and the state an attested policy
+     * declaring no `daemons` key resolves to. The difference between them matters
+     * to nothing here, deliberately: neither is a restriction, and a runtime that
+     * refused because it had not looked yet would refuse every deployment that
+     * never adopts the key.
+     */
+    allowed: readonly string[] | null;
+}
+/**
+ * Declare the id this process's records carry. Called through
+ * `core/daemon-host.ts` by the processes the header names (the daemon loop,
+ * `approval serve` and its hook threads, the Telegram webhook listener), and by
+ * nothing else.
+ *
+ * Takes the RESOLVED values rather than resolving them, because resolution reads
+ * the environment and the filesystem and this module is the one `core/log.ts`
+ * imports (see the header). Idempotent, and a second call replaces the first: a
+ * runtime that re-resolves its identity is reporting a fact about itself, and the
+ * newest reading is the one in force.
+ */
+export declare function declareDaemonIdentity(state: {
+    id: string | null;
+    declared?: string | null;
+    source: DaemonIdSource | null;
+}): void;
+/**
+ * Record which daemon ids this log's ATTESTED policy admits.
+ *
+ * Called only after a successful resolution: the daemon loaded its policy, read
+ * the verified log, and the attestation matched (`core/daemon-host.ts`). A
+ * resolution that FAILED calls nothing, so the restriction last resolved stays in
+ * force rather than lapsing — a policy that becomes unreadable must not be a way
+ * to escape the list it carried a moment ago.
+ *
+ * `null` means the attested policy declares none, which is no restriction.
+ */
+export declare function setDaemonAllowlist(allowed: readonly string[] | null): void;
+/** Forget the declaration. For tests, and for a runtime that stops being one. */
+export declare function clearDaemonIdentity(): void;
+/** What this process has declared about itself, or `null`. */
+export declare function daemonIdentity(): DaemonIdentity | null;
+/** What {@link daemonStampForAppend} answers. */
+export type DaemonStamp = 
+/** Not a declaring daemon process: the record is written as it always was. */
+{
+    kind: "absent";
+}
+/** Stamp this id onto the record. */
+ | {
+    kind: "stamp";
+    id: string;
+}
+/** Refuse the append; nothing is written. */
+ | {
+    kind: "refuse";
+    code: DaemonAppendRefusalCode;
+    message: string;
+};
+/**
+ * The write boundary's question, answered from this process's own state
+ * (APRV-383).
+ *
+ * Both halves of the answer are here rather than in two functions, because they
+ * are one decision made in one order: a process that cannot name itself is
+ * refused before anything asks whether its name is allowed.
+ *
+ * A process that declared NO identity gets `absent`, whether or not it marked
+ * itself the daemon. That is every session, every hook process and the
+ * pre-APRV-383 daemon, and the records they write are the records they always
+ * wrote; turning an undeclared mark into a dead log would make an unrelated
+ * module's `markDaemonProcess` call a stop-the-world bug. The answer is keyed on
+ * the declaration alone (APRV-448, see the header): the daemon loop marks and
+ * declares together, while `approval serve` and the webhook listener declare
+ * without marking, because the mark carries the daemon's advance route and the
+ * declaration carries nothing but a name and a restriction.
+ */
+export declare function daemonStampForAppend(): DaemonStamp;