approval-md 0.2.0 → 0.4.0

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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"}

package/dist/src/core/dark-session.d.ts

@@ -59,6 +59,35 @@
  * cost of the alternative (no branch key at all) is an alarm on every worktree
  * whose session worked entirely outside the payload store's reach.
  *
+ * ## What unit arm A judges, merges included (APRV-374)
+ *
+ * One commit, base to commit, which is the unit a grant binds and the unit the
+ * CI guard judges since APRV-375. The inputs are built by
+ * `core/commit-guard.ts`, so the two sides cannot drift apart.
+ *
+ * A MERGE commit is judged on what it invented and on nothing else. `git log
+ * --name-only` reports no path at all for a merge, so until APRV-374 every
+ * merge dropped out of arm A, which is right for an ordinary merge and wrong
+ * for the evil one: a conflict resolution, or a hand edit made while resolving,
+ * is the merge commit's own work, made in the checkout that made the merge, and
+ * no other commit carries those bytes. So a merge is judged for the paths whose
+ * DENSE COMBINED PATCH (`git log --cc`, {@link denseCombinedPaths}) is
+ * non-empty, against its FIRST PARENT, which is the state the checkout was in
+ * before the merge and therefore the before-state a grant for the resolution
+ * would have bound.
+ *
+ * The dense patch and not `--cc --name-only`, which over-reports: a merge blob
+ * differs from every parent blob whenever both sides edited one file, so
+ * `--name-only` lists a file two lanes happened to edit concurrently and git
+ * merged without a human in the room. Replaying that as the merge's own change
+ * would report dark for work every side of it had evidence for, which is the
+ * class of false alarm APRV-369 and APRV-375 exist to remove. The dense patch
+ * is empty for exactly those merges and non-empty for the resolutions.
+ *
+ * Scope is the guard's scope: guarded paths. A merge that resolved a conflict
+ * in a file no policy protects is not this detector's business, so the dense
+ * question is only ever asked about paths {@link isGuardedPath} accepts.
+ *
  * ## Fail closed in the report
  *
  * Uncertainty is never "fine". A log that does not verify, a payload whose
@@ -90,9 +119,13 @@
  *
  * ## Layout
  *
- * The evaluator ({@link evaluateDarkSessions}) is PURE: no IO, no clock, no
- * git, so a fixture is enough to test it and a repository is never required.
- * The observing half below the fold does run git and read the payload store,
+ * The evaluator ({@link evaluateDarkSessions}) takes no clock and reads no
+ * file, so a fixture drives everything but arm A's replay: the ONE thing it
+ * runs git for is reading the blobs of a commit it is judging, which cannot be
+ * carried in the observation because which blobs are wanted is not known until
+ * the verdict is being computed. A fixture whose commits change no guarded path
+ * needs no repository at all. The observing half below the fold runs the rest
+ * of the git and reads the payload store,
  * and it lives here rather than under `daemon/` because `approval doctor`
  * reports the same findings and `src/cli/` may not import `src/daemon/`
  * (APRV-59). The one thing that stays in `daemon/dark-session.ts` is the
@@ -127,6 +160,16 @@ export declare const DARK_SESSION_CODES: readonly [
 "no-records", 
 /** Arm A: a guarded path changed and the log carries no evidence for it. */
 "no-evidence", 
+/**
+ * Arm A, and EVERY failing commit arrived here through a merge (APRV-369).
+ *
+ * The same failure as `no-evidence` and the same `dark` verdict — nothing is
+ * excused by it — reported under its own code because the checkout it names
+ * is the one that SYNCED the change rather than the one that made it. The
+ * repair is in whatever branch or worktree authored the commit, which the
+ * detail names.
+ */
+"no-evidence-merged", 
 /** Exempt: the commits touch only the daemon's own append surface. */
 "evidence-surface", 
 /** Exempt: authored by the daemon's own git identity. */
@@ -142,6 +185,18 @@ export declare const DARK_SESSION_CODES: readonly [
 /** Undetermined: git named no usable date for the activity. */
 "activity-undated"];
 export type DarkSessionCode = (typeof DARK_SESSION_CODES)[number];
+/**
+ * The codes a `dark` verdict can carry, and therefore the ones that reach the
+ * log on an `audit.dark_session` record (APRV-369).
+ *
+ * A separate, smaller list than {@link DARK_SESSION_CODES} because it is the
+ * one the event schema constrains: an exempt or undetermined subject is never
+ * recorded, so its code has no business in a write-boundary enum. Pinned equal
+ * to that enum by a test, for the reason APRV-358 gave: a code the sweep can
+ * produce and the schema refuses is an observation that never reaches a human,
+ * and nothing fails loudly when it happens.
+ */
+export declare const DARK_VERDICT_CODES: readonly ["no-records", "no-evidence", "no-evidence-merged"];
 /** One commit the observer saw, as git reported it. */
 export interface ObservedCommit {
     /** The full sha. */
@@ -152,10 +207,42 @@ export interface ObservedCommit {
     author: string;
     /** The author's email alone, lowercased, or `""` when git named none. */
     authorEmail: string;
-    /** Repository-relative, `/`-separated paths this commit changed. */
+    /**
+     * Repository-relative, `/`-separated paths this commit changed.
+     *
+     * For a MERGE commit these are the guarded paths whose result differs from
+     * every parent hunk by hunk — the merge's own resolution work, and nothing
+     * its parents did (APRV-374). An ordinary merge has none.
+     */
     changedPaths: readonly string[];
+    /**
+     * The commit's parents in git's own order, when the observer asked.
+     *
+     * OPTIONAL, and absence means "unknown", which the per-commit input builder
+     * reads as "assume it has a parent": the modest direction, since the base it
+     * then judges against is the first parent rather than nothing at all.
+     * Two or more parents is what makes a commit a merge here.
+     */
+    parents?: readonly string[];
     /** The branch or worktree this commit was observed on, for the message. */
     ref: string;
+    /**
+     * Did this commit reach the checkout through a merge rather than being made
+     * on it? (APRV-369.)
+     *
+     * True when the commit is reachable from the observed HEAD but is NOT on its
+     * first-parent history, which is what "somebody else's branch was merged in"
+     * looks like in git: a lane's commits, a contributor's, or anything that
+     * arrived by fast-forward from the trunk. A commit made in this checkout and
+     * committed on the branch it is standing on is on the first-parent path and
+     * is `false`.
+     *
+     * OPTIONAL, and absence means `false` — attributed to this checkout. That is
+     * the direction that keeps a caller written before this field existed
+     * honest: an observer that cannot say where a commit came from must not be
+     * read as saying it came from somewhere else.
+     */
+    arrivedByMerge?: boolean;
 }
 /** One checkout the observer saw: the primary, or a linked worktree. */
 export interface ObservedCheckout {
@@ -298,8 +385,16 @@ export interface DarkSessionWatch {
     /** How often a sweep runs. The tick interval is the floor. */
     intervalMs: number;
 }
-/** Everything git could tell the sweep about a repository in one window. */
-export declare function observeGitActivity(root: string, from: string, to: string): GitActivity;
+/**
+ * Everything git could tell the sweep about a repository in one window.
+ *
+ * `protectedPaths` is the policy's `protected_paths`, and omitting it asks the
+ * merge question about the BUILT-IN guarded set only. That is the fail-closed
+ * direction for a caller that has no policy to hand: it narrows which merges
+ * are examined and never which evidence is required, and
+ * {@link reportDarkSessions} always passes the loaded list.
+ */
+export declare function observeGitActivity(root: string, from: string, to: string, protectedPaths?: readonly ProtectedPathEntry[]): GitActivity;
 export interface DarkSessionSweepOptions {
     logPath: string;
     /** The checkout to observe. The daemon's own `cwd`; never an agent worktree. */
@@ -316,8 +411,14 @@ export interface DarkSessionSweepOptions {
     /** Verified records. The caller has already read them; nothing re-reads. */
     records: readonly EventRecord[] | null;
     logDetail?: string;
-    /** Test seam: an observer that answers without running git. */
-    observe?: (root: string, from: string, to: string) => GitActivity;
+    /**
+     * Test seam: an observer that answers without running git.
+     *
+     * It is offered the policy's protected paths as a fourth argument, which the
+     * real observer needs to know which merges to ask git about (APRV-374); a
+     * seam that ignores it answers exactly as it did before.
+     */
+    observe?: (root: string, from: string, to: string, protectedPaths: readonly ProtectedPathEntry[]) => GitActivity;
 }
 /**
  * Observe and judge, appending nothing.