approval-md 0.3.0 → 0.4.1

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

@@ -0,0 +1,252 @@
+/**
+ * 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 const DAEMON_ID_ENV = "APPROVAL_DAEMON_ID";
+/** The longest id this runtime writes or admits. */
+export const DAEMON_ID_MAX_LENGTH = 64;
+/**
+ * The shape an id takes: lowercase alphanumerics, dots, dashes and underscores,
+ * starting with an alphanumeric.
+ *
+ * Narrow on purpose, and for the reason `payload.harness_version` is narrow
+ * (APRV-227): the value is a string from a launch environment being written into
+ * an append-only log, so a banner, a path, a newline or a shell fragment must not
+ * be able to arrive through it. It is also a value an operator COMPARES by eye
+ * against `approval doctor` and against the `daemons` list in their policy, and
+ * two ids differing only in case are two ids nobody can tell apart on a phone.
+ */
+const DAEMON_ID_PATTERN = /^[a-z0-9][a-z0-9._-]*$/u;
+/** Is `value` a well-formed daemon id? */
+export function isDaemonId(value) {
+    return value.length <= DAEMON_ID_MAX_LENGTH && DAEMON_ID_PATTERN.test(value);
+}
+/**
+ * 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 const DAEMON_APPEND_REFUSAL_CODES = [
+    /**
+     * 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",
+];
+/** The declaring process's own state. Never set on another process's behalf. */
+let identity = null;
+/**
+ * The pid that made the declaration, for the reason `core/daemon-actor.ts` keeps
+ * one: the stamp answers only while it is still this process's own. Kept beside
+ * {@link identity} rather than inside it, so the reported state is unchanged.
+ */
+let declaredPid = 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 function declareDaemonIdentity(state) {
+    identity = {
+        id: state.id,
+        declared: state.declared ?? null,
+        source: state.source,
+        // A fresh declaration carries no allowlist. The daemon resolves one from its
+        // attested policy and sets it separately, so an identity re-declared mid-run
+        // cannot silently drop a restriction that was in force.
+        allowed: identity === null ? null : identity.allowed,
+    };
+    declaredPid = process.pid;
+}
+/**
+ * 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 function setDaemonAllowlist(allowed) {
+    if (identity === null)
+        return;
+    identity = { ...identity, allowed: allowed === null ? null : [...allowed] };
+}
+/** Forget the declaration. For tests, and for a runtime that stops being one. */
+export function clearDaemonIdentity() {
+    identity = null;
+    declaredPid = null;
+}
+/** What this process has declared about itself, or `null`. */
+export function daemonIdentity() {
+    return identity;
+}
+/**
+ * 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 function daemonStampForAppend() {
+    const state = identity;
+    if (state === null || declaredPid !== process.pid)
+        return { kind: "absent" };
+    if (state.id === null) {
+        return {
+            kind: "refuse",
+            code: "daemon-id-invalid",
+            message: `this daemon declared ${DAEMON_ID_ENV}=${JSON.stringify(state.declared ?? "")}, which is not a usable daemon id (lowercase letters, digits, \`.\`, \`-\` and \`_\`, starting with a letter or digit, at most ${String(DAEMON_ID_MAX_LENGTH)} characters), so no record it wrote could name which daemon wrote it. Nothing was written: fix ${DAEMON_ID_ENV} in this process's launch environment, or unset it and let the id derive from this instance`,
+        };
+    }
+    const allowed = state.allowed;
+    if (allowed !== null && !allowed.includes(state.id)) {
+        return {
+            kind: "refuse",
+            code: "daemon-not-allowed",
+            message: `this daemon's id is ${state.id} and the attested policy's \`daemons\` list admits ${allowed.length === 0 ? "no daemon at all" : allowed.join(", ")}, so it may not write to this log. Nothing was written: add ${state.id} to \`daemons\` and re-attest the policy, or run the daemon whose id the list already names`,
+        };
+    }
+    return { kind: "stamp", id: state.id };
+}
+//# sourceMappingURL=daemon-identity.js.map

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

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