approval-md 0.3.0 → 0.4.0

package/dist/src/core/run-payload.d.ts

@@ -0,0 +1,160 @@
+/**
+ * The `approval run` payload: the argv, the cwd, and the bytes of the script
+ * the argv names (SPEC.md §6.2, §10.4; APRV-401).
+ *
+ * ## The hazard this closes
+ *
+ * §6.2 defined this payload as "the argv array and cwd", and `approval run`
+ * recomputes it from the argv and cwd it is about to spawn. For a command that
+ * IS its own bytes (`npm update @types/node`) that is the whole action. For a
+ * command that names a script it is not: the payload binds a NAME, and the
+ * bytes behind that name are whatever the path holds at execution time. The
+ * requester controls the file between the request and the grant, so a human
+ * approved a path and the runtime executed a file. Found on a live grant during
+ * APRV-398, exploited by nobody, filed as APRV-401.
+ *
+ * The payload hash is supposed to BE the binding (§10.4: "A grant therefore
+ * approves specific bytes"), so the repair is to put the bytes inside it. A
+ * script edited between the declaration and the execution hashes differently,
+ * and the difference refuses `payload-mismatch` before the child is spawned and
+ * before anything is appended, exactly as a changed argv already did.
+ *
+ * ## The shape, as the operator ruled it (APRV-401 notes, 2026-09-21)
+ *
+ * > the script digest is PART OF THE BINDING, never advisory. Shape: when argv
+ * > names an interpreter (bash, sh, zsh, node, python3 and kin) followed by a
+ * > path that resolves to a regular file at request time, the runtime reads and
+ * > hashes the file into the bound payload, the card shows the digest, byte
+ * > count and path, and approval run re-reads the file and refuses
+ * > payload-mismatch if the bytes changed. No interpretation of the script and
+ * > no second pass for files it sources; the limit is documented. Out of scope:
+ * > piped installers (already opaque), sourced files, interpreters the
+ * > classifier does not name.
+ *
+ * So this is an INTERPRETER-KEYED rule and not "every argv word that happens to
+ * name a file". One script per invocation: the first word after the interpreter
+ * that resolves to a readable regular file, which is the interpreter's operand
+ * whether or not a subcommand comes first (`deno run job.ts`).
+ * {@link SCRIPT_INTERPRETERS} is the list, and every member of it is a name
+ * `core/command-class.ts` already knows: the six shells of its unwrappable set,
+ * `node` from its own branch, and `python`, `python3`, `perl`, `ruby` and
+ * `deno` from its inline-source table. A launcher neither file names binds
+ * nothing, which is the documented limit rather than an oversight.
+ *
+ * The one thing here that the ruling does not spell out is the DEGENERATE case:
+ * `./install.sh` with no interpreter word at all, where the kernel reads the
+ * shebang and the script is `argv[0]` itself. It is bound, because it is the
+ * same fact with the interpreter implied rather than typed, and leaving it out
+ * would be a hole in the rule shaped exactly like the rule.
+ *
+ * ## What is NOT bound, stated plainly
+ *
+ * - **An inline program.** `bash -c '…'`, `node -e '…'`, `python3 -c '…'`: the
+ *   program is a word of the argv, so it was always bound, and there is no file
+ *   to read. The inline flags per interpreter are in {@link SCRIPT_INTERPRETERS}.
+ * - **Nothing resolved through PATH.** The interpreter itself is not hashed. Its
+ *   bytes are the host's rather than the requester's, and resolving a program
+ *   name through `PATH` would make the payload a function of the environment the
+ *   process happens to hold, which §11 says is never read implicitly.
+ * - **Nothing transitive.** A bound script that sources another file, curls a
+ *   second one, or execs a third binds only its own bytes. The digest is a
+ *   binding, not a sandbox.
+ * - **A piped installer.** `curl … | sh` has no file operand and is opaque to
+ *   the classifier for the same reason it is unbindable here.
+ * - **The instant between hashing and spawning.** The digest is taken, then
+ *   `execution.started` is appended, then the child is spawned. A file rewritten
+ *   inside that window runs unbound. Closing it needs the executor to hold the
+ *   bytes rather than the path, which is the adapter contract of §10.4.
+ *
+ * ## Absence is not a claim
+ *
+ * `script` is omitted when nothing is bound, and that omission is deliberate: an
+ * invocation naming no readable script hashes to exactly the value it hashed
+ * before this module existed, so every record already in the log, and every
+ * declaration already written into a task file, verifies unchanged. What the
+ * absence does NOT say is "this runtime checked and there was nothing" — it is
+ * the ordinary shape of a payload with no script to bind, and a reader wanting
+ * to know whether a digest was possible reads the argv, which is right there.
+ *
+ * Every skip is safe for one reason, and it is the same reason in each case: the
+ * value is recomputed at execution by this same rule. A file that was
+ * unreadable at declaration time and readable at execution time gains an entry
+ * and refuses; one that existed and was deleted loses one and refuses. The rule
+ * does not have to decide correctly what a command will do, because both ends
+ * apply it to the same tree and any disagreement is a refusal.
+ *
+ * Reads the filesystem, by design and by necessity: at most one file per call,
+ * and only the one the argv names. Writes nothing, appends nothing, reads no
+ * log, no policy, no environment and no clock.
+ */
+/** The payload key carrying the bound script. Omitted when there is none. */
+export declare const BOUND_SCRIPT_KEY = "script";
+/**
+ * How much of a file is read at once while digesting it.
+ *
+ * Chunked rather than `readFileSync`, because a script may be of any size and
+ * the executor must not be the thing that runs out of memory: a refusal to
+ * compute the binding is a refusal to execute.
+ */
+export declare const DIGEST_CHUNK_BYTES: number;
+/**
+ * The interpreters whose script operand is bound, and the flags that mean
+ * "the program is inline, there is no file".
+ *
+ * Every name here is one `core/command-class.ts` already knows, which is the
+ * ruling's "interpreters the classifier does not name" read as a positive list:
+ * the six shells of its unwrappable set, `node` from its own classification
+ * branch, and `python`, `python3`, `perl`, `ruby`, `deno` from its
+ * inline-source table. The list is duplicated rather than imported because
+ * those tables are private to that module and a public export of them would be
+ * a second consumer of a decision that belongs to classification; the comment
+ * is the seam, and a name added there without being added here binds nothing,
+ * which fails toward the old behaviour rather than toward a wrong digest.
+ *
+ * The shell inline flag is `-c` with any run of `l` and `i` before it, which is
+ * `INLINE_SCRIPT_FLAG` in that module, spelled here as the same regular
+ * expression for the same reason.
+ */
+export declare const SCRIPT_INTERPRETERS: ReadonlyMap<string, readonly (string | RegExp)[]>;
+/** One script the argv names, bound by its bytes. */
+export interface BoundScript {
+    /** Which argv word named it. */
+    argv_index: number;
+    /** The path as resolved against the payload's `cwd`: absolute, always. */
+    path: string;
+    /** The file's size in bytes, which the approver's card shows beside the digest. */
+    bytes: number;
+    /** SHA-256 (lowercase hex) of the file's bytes. */
+    sha256: string;
+}
+/** The `approval run` payload value, canonicalized and hashed by the caller. */
+export interface RunPayload {
+    argv: string[];
+    cwd: string;
+    /** Present only when the argv named a readable script. */
+    script?: BoundScript;
+}
+/**
+ * The script this argv runs, bound by its bytes, or `null` (APRV-401).
+ *
+ * Two shapes, and only two: an interpreter this module names followed by a path
+ * operand, and a path at `argv[0]` that the kernel will read a shebang from.
+ * Anything else binds nothing and the payload is what it always was.
+ */
+export declare function boundScript(argv: readonly string[], cwd: string): BoundScript | null;
+/**
+ * The value `approval run`'s `payload_hash` is taken over (SPEC.md §6.2).
+ *
+ * `{argv, cwd}` when the argv names no readable script, byte for byte what it
+ * has always been; `{argv, cwd, script}` when it does. The caller canonicalizes
+ * and hashes it — this function decides WHAT is bound and never how it is
+ * digested into an approval.
+ */
+export declare function runPayloadValue(argv: readonly string[], cwd: string): RunPayload;
+/**
+ * One line naming the bound script, for a refusal message or a terminal.
+ *
+ * Not a rendering an approver signs: the canonical renderer owns that, and this
+ * is the executor explaining to an agent WHICH file moved.
+ */
+export declare function describeBoundScript(script: BoundScript | null): string;

package/dist/src/core/run-payload.js

@@ -0,0 +1,304 @@
+/**
+ * The `approval run` payload: the argv, the cwd, and the bytes of the script
+ * the argv names (SPEC.md §6.2, §10.4; APRV-401).
+ *
+ * ## The hazard this closes
+ *
+ * §6.2 defined this payload as "the argv array and cwd", and `approval run`
+ * recomputes it from the argv and cwd it is about to spawn. For a command that
+ * IS its own bytes (`npm update @types/node`) that is the whole action. For a
+ * command that names a script it is not: the payload binds a NAME, and the
+ * bytes behind that name are whatever the path holds at execution time. The
+ * requester controls the file between the request and the grant, so a human
+ * approved a path and the runtime executed a file. Found on a live grant during
+ * APRV-398, exploited by nobody, filed as APRV-401.
+ *
+ * The payload hash is supposed to BE the binding (§10.4: "A grant therefore
+ * approves specific bytes"), so the repair is to put the bytes inside it. A
+ * script edited between the declaration and the execution hashes differently,
+ * and the difference refuses `payload-mismatch` before the child is spawned and
+ * before anything is appended, exactly as a changed argv already did.
+ *
+ * ## The shape, as the operator ruled it (APRV-401 notes, 2026-09-21)
+ *
+ * > the script digest is PART OF THE BINDING, never advisory. Shape: when argv
+ * > names an interpreter (bash, sh, zsh, node, python3 and kin) followed by a
+ * > path that resolves to a regular file at request time, the runtime reads and
+ * > hashes the file into the bound payload, the card shows the digest, byte
+ * > count and path, and approval run re-reads the file and refuses
+ * > payload-mismatch if the bytes changed. No interpretation of the script and
+ * > no second pass for files it sources; the limit is documented. Out of scope:
+ * > piped installers (already opaque), sourced files, interpreters the
+ * > classifier does not name.
+ *
+ * So this is an INTERPRETER-KEYED rule and not "every argv word that happens to
+ * name a file". One script per invocation: the first word after the interpreter
+ * that resolves to a readable regular file, which is the interpreter's operand
+ * whether or not a subcommand comes first (`deno run job.ts`).
+ * {@link SCRIPT_INTERPRETERS} is the list, and every member of it is a name
+ * `core/command-class.ts` already knows: the six shells of its unwrappable set,
+ * `node` from its own branch, and `python`, `python3`, `perl`, `ruby` and
+ * `deno` from its inline-source table. A launcher neither file names binds
+ * nothing, which is the documented limit rather than an oversight.
+ *
+ * The one thing here that the ruling does not spell out is the DEGENERATE case:
+ * `./install.sh` with no interpreter word at all, where the kernel reads the
+ * shebang and the script is `argv[0]` itself. It is bound, because it is the
+ * same fact with the interpreter implied rather than typed, and leaving it out
+ * would be a hole in the rule shaped exactly like the rule.
+ *
+ * ## What is NOT bound, stated plainly
+ *
+ * - **An inline program.** `bash -c '…'`, `node -e '…'`, `python3 -c '…'`: the
+ *   program is a word of the argv, so it was always bound, and there is no file
+ *   to read. The inline flags per interpreter are in {@link SCRIPT_INTERPRETERS}.
+ * - **Nothing resolved through PATH.** The interpreter itself is not hashed. Its
+ *   bytes are the host's rather than the requester's, and resolving a program
+ *   name through `PATH` would make the payload a function of the environment the
+ *   process happens to hold, which §11 says is never read implicitly.
+ * - **Nothing transitive.** A bound script that sources another file, curls a
+ *   second one, or execs a third binds only its own bytes. The digest is a
+ *   binding, not a sandbox.
+ * - **A piped installer.** `curl … | sh` has no file operand and is opaque to
+ *   the classifier for the same reason it is unbindable here.
+ * - **The instant between hashing and spawning.** The digest is taken, then
+ *   `execution.started` is appended, then the child is spawned. A file rewritten
+ *   inside that window runs unbound. Closing it needs the executor to hold the
+ *   bytes rather than the path, which is the adapter contract of §10.4.
+ *
+ * ## Absence is not a claim
+ *
+ * `script` is omitted when nothing is bound, and that omission is deliberate: an
+ * invocation naming no readable script hashes to exactly the value it hashed
+ * before this module existed, so every record already in the log, and every
+ * declaration already written into a task file, verifies unchanged. What the
+ * absence does NOT say is "this runtime checked and there was nothing" — it is
+ * the ordinary shape of a payload with no script to bind, and a reader wanting
+ * to know whether a digest was possible reads the argv, which is right there.
+ *
+ * Every skip is safe for one reason, and it is the same reason in each case: the
+ * value is recomputed at execution by this same rule. A file that was
+ * unreadable at declaration time and readable at execution time gains an entry
+ * and refuses; one that existed and was deleted loses one and refuses. The rule
+ * does not have to decide correctly what a command will do, because both ends
+ * apply it to the same tree and any disagreement is a refusal.
+ *
+ * Reads the filesystem, by design and by necessity: at most one file per call,
+ * and only the one the argv names. Writes nothing, appends nothing, reads no
+ * log, no policy, no environment and no clock.
+ */
+import { createHash } from "node:crypto";
+import { closeSync, openSync, readSync, statSync } from "node:fs";
+import { isAbsolute, resolve as resolvePath } from "node:path";
+/** The payload key carrying the bound script. Omitted when there is none. */
+export const BOUND_SCRIPT_KEY = "script";
+/**
+ * How much of a file is read at once while digesting it.
+ *
+ * Chunked rather than `readFileSync`, because a script may be of any size and
+ * the executor must not be the thing that runs out of memory: a refusal to
+ * compute the binding is a refusal to execute.
+ */
+export const DIGEST_CHUNK_BYTES = 64 * 1024;
+/**
+ * The interpreters whose script operand is bound, and the flags that mean
+ * "the program is inline, there is no file".
+ *
+ * Every name here is one `core/command-class.ts` already knows, which is the
+ * ruling's "interpreters the classifier does not name" read as a positive list:
+ * the six shells of its unwrappable set, `node` from its own classification
+ * branch, and `python`, `python3`, `perl`, `ruby`, `deno` from its
+ * inline-source table. The list is duplicated rather than imported because
+ * those tables are private to that module and a public export of them would be
+ * a second consumer of a decision that belongs to classification; the comment
+ * is the seam, and a name added there without being added here binds nothing,
+ * which fails toward the old behaviour rather than toward a wrong digest.
+ *
+ * The shell inline flag is `-c` with any run of `l` and `i` before it, which is
+ * `INLINE_SCRIPT_FLAG` in that module, spelled here as the same regular
+ * expression for the same reason.
+ */
+export const SCRIPT_INTERPRETERS = new Map([
+    ["bash", [/^-[li]*c$/u]],
+    ["sh", [/^-[li]*c$/u]],
+    ["zsh", [/^-[li]*c$/u]],
+    ["dash", [/^-[li]*c$/u]],
+    ["ksh", [/^-[li]*c$/u]],
+    ["fish", [/^-[li]*c$/u, "--command"]],
+    ["node", ["-e", "--eval", "-p", "--print", "--input-type=module"]],
+    ["nodejs", ["-e", "--eval", "-p", "--print"]],
+    ["python", ["-c"]],
+    ["python3", ["-c"]],
+    ["perl", ["-e", "-E"]],
+    ["ruby", ["-e"]],
+    ["deno", ["eval"]],
+]);
+/**
+ * The digest and size of one file, read in bounded chunks, or `null` when it
+ * cannot be read at all.
+ *
+ * `null` for every failure — gone, a directory, a device, permission denied, a
+ * disappearing file, a read error partway — and the reason is not recorded
+ * anywhere. Recording it would put a local errno inside hashed material, so two
+ * machines that agree about the bytes could disagree about the payload; and the
+ * only thing a reader could do with it is treat "unreadable" as a state, which
+ * the recomputation already handles better than any field could.
+ */
+function fileDigest(path) {
+    let fd;
+    try {
+        const stats = statSync(path);
+        if (!stats.isFile())
+            return null;
+        fd = openSync(path, "r");
+    }
+    catch {
+        return null;
+    }
+    const hash = createHash("sha256");
+    const buffer = Buffer.allocUnsafe(DIGEST_CHUNK_BYTES);
+    let bytes = 0;
+    try {
+        let read = readSync(fd, buffer, 0, DIGEST_CHUNK_BYTES, null);
+        while (read > 0) {
+            hash.update(buffer.subarray(0, read));
+            bytes += read;
+            read = readSync(fd, buffer, 0, DIGEST_CHUNK_BYTES, null);
+        }
+    }
+    catch {
+        return null;
+    }
+    finally {
+        try {
+            closeSync(fd);
+        }
+        catch {
+            // A close that fails has nothing to do with the bytes already hashed.
+        }
+    }
+    return { bytes, sha256: hash.digest("hex") };
+}
+/** The last path segment of an argv word: `/usr/bin/bash` reads as `bash`. */
+function basenameOf(word) {
+    const segments = word.split("/");
+    return segments[segments.length - 1] ?? word;
+}
+/** Does `word` mean "the program is inline" for this interpreter? */
+function isInlineProgramFlag(word, markers) {
+    return markers.some((marker) => typeof marker === "string" ? word === marker : marker.test(word));
+}
+/**
+ * The words of an interpreter invocation that could be its script, in order,
+ * or `null` when the program is inline and there is no file at all.
+ *
+ * An inline-program marker anywhere in the options answers `null` rather than
+ * "keep looking": the program is a word of the argv and already bound, and a
+ * file that happens to share its spelling is a file the command never opens.
+ *
+ * Otherwise every non-option word is a candidate, in argv order, and the caller
+ * binds the first that resolves to a readable regular file. Not just the first
+ * non-option word, because interpreters take SUBCOMMANDS: `deno run job.ts`
+ * would otherwise offer `run` and stop, and `python3 -m pkg job.py` would offer
+ * `pkg`. Walking on cannot bind anything the argv does not name, and the worst
+ * case is the harmless direction — a command whose script is missing and whose
+ * later argument happens to be a file binds that file, which is one more thing
+ * bound rather than one fewer.
+ *
+ * An option that takes a separate path value is the one place this can pick the
+ * wrong file (`node --require ./a.js job.js` binds `./a.js`), and both are
+ * files that invocation executes.
+ */
+function scriptCandidateIndexes(argv, markers) {
+    const candidates = [];
+    for (let index = 1; index < argv.length; index += 1) {
+        const word = argv[index];
+        if (isInlineProgramFlag(word, markers))
+            return null;
+        if (word === "--")
+            continue;
+        if (word.startsWith("-") && word.length > 1)
+            continue;
+        candidates.push(index);
+    }
+    return candidates;
+}
+/**
+ * Where an argv word points, resolved against the payload's own `cwd`.
+ *
+ * The cwd is the payload's, never `process.cwd()`: the payload already carries
+ * the directory the child will run in, and resolving against anything else
+ * would make the binding a function of where the hashing process happened to
+ * stand.
+ */
+function resolveArgvPath(word, cwd) {
+    if (word === "" || word === "-" || word === "--")
+        return null;
+    if (word.includes("\0"))
+        return null;
+    return isAbsolute(word) ? word : resolvePath(cwd, word);
+}
+/**
+ * The script this argv runs, bound by its bytes, or `null` (APRV-401).
+ *
+ * Two shapes, and only two: an interpreter this module names followed by a path
+ * operand, and a path at `argv[0]` that the kernel will read a shebang from.
+ * Anything else binds nothing and the payload is what it always was.
+ */
+export function boundScript(argv, cwd) {
+    const program = argv[0];
+    if (program === undefined || program === "")
+        return null;
+    const markers = SCRIPT_INTERPRETERS.get(basenameOf(program));
+    if (markers !== undefined) {
+        const candidates = scriptCandidateIndexes(argv, markers);
+        if (candidates === null)
+            return null;
+        for (const index of candidates) {
+            const path = resolveArgvPath(argv[index], cwd);
+            if (path === null)
+                continue;
+            const digest = fileDigest(path);
+            if (digest !== null)
+                return { argv_index: index, path, ...digest };
+        }
+        return null;
+    }
+    // The degenerate case: no interpreter word, so the script IS argv[0] and the
+    // interpreter is whatever its shebang names. A program with no separator in
+    // it is a PATH lookup and is not this (see the module header).
+    if (!isAbsolute(program) && !program.includes("/"))
+        return null;
+    const path = resolveArgvPath(program, cwd);
+    if (path === null)
+        return null;
+    const digest = fileDigest(path);
+    return digest === null ? null : { argv_index: 0, path, ...digest };
+}
+/**
+ * The value `approval run`'s `payload_hash` is taken over (SPEC.md §6.2).
+ *
+ * `{argv, cwd}` when the argv names no readable script, byte for byte what it
+ * has always been; `{argv, cwd, script}` when it does. The caller canonicalizes
+ * and hashes it — this function decides WHAT is bound and never how it is
+ * digested into an approval.
+ */
+export function runPayloadValue(argv, cwd) {
+    const script = boundScript(argv, cwd);
+    const payload = { argv: [...argv], cwd };
+    if (script !== null)
+        payload.script = script;
+    return payload;
+}
+/**
+ * One line naming the bound script, for a refusal message or a terminal.
+ *
+ * Not a rendering an approver signs: the canonical renderer owns that, and this
+ * is the executor explaining to an agent WHICH file moved.
+ */
+export function describeBoundScript(script) {
+    if (script === null)
+        return "no script";
+    return `argv[${String(script.argv_index)}] ${script.path}, ${String(script.bytes)} bytes, sha256 ${script.sha256}`;
+}
+//# sourceMappingURL=run-payload.js.map

package/dist/src/core/run-payload.js.map

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

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

@@ -13,10 +13,12 @@
  *
  * ## What is evidence here, and what is not
  *
- * Exactly one field in the whole system is a sender fact worth mapping:
- * Telegram's `callback_query.from.id`, the stable numeric account id the Bot
- * API attributes the tap to. {@link SENDER_CHANNELS} is closed to that one
- * channel for that reason. A web form post authenticates nobody and a CLI
+ * Two fields in the whole system are sender facts worth mapping. Telegram's
+ * `callback_query.from.id`, the stable numeric account id the Bot API
+ * attributes the tap to, and (APRV-455) the EdgeOS `/humans/me` id that an
+ * operator's control plane attributes a gesture to when it carries it over
+ * `approval channel relay`. {@link SENDER_CHANNELS} is closed to those two
+ * channels for that reason. A web form post authenticates nobody and a CLI
  * process authenticates local machine control, so neither may be given an
  * identity key it cannot support: a `senders` entry for either is a schema
  * violation rather than a mapping nothing backs.
@@ -144,16 +146,39 @@ export declare function senderKeyFrom(env?: NodeJS.ProcessEnv): string | null;
  *
  * Closed, and short on purpose. `telegram` is here because the Bot API reports
  * `callback_query.from.id`, a stable numeric account id the sender cannot
- * choose. `web` and `cli` are absent because neither authenticates a person:
- * the web page takes an unauthenticated form post and the CLI takes whoever
- * controls the process. A policy that named either would be asserting a binding
- * the runtime cannot check, so the schema refuses the key rather than carrying
- * a mapping that reads like identity.
+ * choose. `edgeos` is here (APRV-455) on the same ground: a gesture on it
+ * arrives through `approval channel relay`, authenticated by a shared secret
+ * from the daemon's launch environment, and the control plane holding that
+ * secret attributes it to the EdgeOS `/humans/me` id of the session the person
+ * signed in with, which the person cannot choose. In both cases the daemon
+ * trusts a relay's report of who acted; that is operator trust, and it is the
+ * same trust whichever relay carries the report.
+ *
+ * `web` and `cli` are absent because neither authenticates a person: the web
+ * page takes an unauthenticated form post and the CLI takes whoever controls
+ * the process. A policy that named either would be asserting a binding the
+ * runtime cannot check, so the schema refuses the key rather than carrying a
+ * mapping that reads like identity.
  */
-export declare const SENDER_CHANNELS: readonly ["telegram"];
+export declare const SENDER_CHANNELS: readonly ["telegram", "edgeos"];
 export type SenderChannel = (typeof SENDER_CHANNELS)[number];
 /** Is `name` a channel whose transport can attribute a gesture (§2)? */
 export declare function isSenderChannel(name: string): name is SenderChannel;
+/**
+ * The grammar of a RAW EdgeOS sender id (APRV-455), the same one
+ * `schema/policy.schema.json` pins on `senders.edgeos`.
+ *
+ * The id is the one EdgeOS returns from `/humans/me`, and this runtime treats
+ * it as opaque: it is compared byte for byte and never parsed. The grammar is a
+ * bound on what may be compared, not a reading of what the id means. An ASCII
+ * letter or digit, then up to 127 letters, digits, `.`, `_` or `-`: enough
+ * for a UUID or a decimal id, and deliberately without `:` or whitespace, so a
+ * raw id can never be mistaken for the {@link SENDER_HASH_PREFIX} form and can
+ * never contain the separator {@link senderIndex} joins its keys with.
+ */
+export declare const EDGEOS_SENDER_ID_PATTERN: RegExp;
+/** Is `id` a raw EdgeOS sender id this runtime will compare (APRV-455)? */
+export declare function isEdgeosSenderId(id: string): boolean;
 /**
  * One observed sender: the channel that saw it, and the id that channel's
  * transport attributed the gesture to.

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

@@ -13,10 +13,12 @@
  *
  * ## What is evidence here, and what is not
  *
- * Exactly one field in the whole system is a sender fact worth mapping:
- * Telegram's `callback_query.from.id`, the stable numeric account id the Bot
- * API attributes the tap to. {@link SENDER_CHANNELS} is closed to that one
- * channel for that reason. A web form post authenticates nobody and a CLI
+ * Two fields in the whole system are sender facts worth mapping. Telegram's
+ * `callback_query.from.id`, the stable numeric account id the Bot API
+ * attributes the tap to, and (APRV-455) the EdgeOS `/humans/me` id that an
+ * operator's control plane attributes a gesture to when it carries it over
+ * `approval channel relay`. {@link SENDER_CHANNELS} is closed to those two
+ * channels for that reason. A web form post authenticates nobody and a CLI
  * process authenticates local machine control, so neither may be given an
  * identity key it cannot support: a `senders` entry for either is a schema
  * violation rather than a mapping nothing backs.
@@ -153,17 +155,42 @@ export function senderKeyFrom(env = process.env) {
  *
  * Closed, and short on purpose. `telegram` is here because the Bot API reports
  * `callback_query.from.id`, a stable numeric account id the sender cannot
- * choose. `web` and `cli` are absent because neither authenticates a person:
- * the web page takes an unauthenticated form post and the CLI takes whoever
- * controls the process. A policy that named either would be asserting a binding
- * the runtime cannot check, so the schema refuses the key rather than carrying
- * a mapping that reads like identity.
+ * choose. `edgeos` is here (APRV-455) on the same ground: a gesture on it
+ * arrives through `approval channel relay`, authenticated by a shared secret
+ * from the daemon's launch environment, and the control plane holding that
+ * secret attributes it to the EdgeOS `/humans/me` id of the session the person
+ * signed in with, which the person cannot choose. In both cases the daemon
+ * trusts a relay's report of who acted; that is operator trust, and it is the
+ * same trust whichever relay carries the report.
+ *
+ * `web` and `cli` are absent because neither authenticates a person: the web
+ * page takes an unauthenticated form post and the CLI takes whoever controls
+ * the process. A policy that named either would be asserting a binding the
+ * runtime cannot check, so the schema refuses the key rather than carrying a
+ * mapping that reads like identity.
  */
-export const SENDER_CHANNELS = ["telegram"];
+export const SENDER_CHANNELS = ["telegram", "edgeos"];
 /** Is `name` a channel whose transport can attribute a gesture (§2)? */
 export function isSenderChannel(name) {
     return SENDER_CHANNELS.includes(name);
 }
+/**
+ * The grammar of a RAW EdgeOS sender id (APRV-455), the same one
+ * `schema/policy.schema.json` pins on `senders.edgeos`.
+ *
+ * The id is the one EdgeOS returns from `/humans/me`, and this runtime treats
+ * it as opaque: it is compared byte for byte and never parsed. The grammar is a
+ * bound on what may be compared, not a reading of what the id means. An ASCII
+ * letter or digit, then up to 127 letters, digits, `.`, `_` or `-`: enough
+ * for a UUID or a decimal id, and deliberately without `:` or whitespace, so a
+ * raw id can never be mistaken for the {@link SENDER_HASH_PREFIX} form and can
+ * never contain the separator {@link senderIndex} joins its keys with.
+ */
+export const EDGEOS_SENDER_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
+/** Is `id` a raw EdgeOS sender id this runtime will compare (APRV-455)? */
+export function isEdgeosSenderId(id) {
+    return EDGEOS_SENDER_ID_PATTERN.test(id);
+}
 /** Where a decision's actor came from, recorded on the decision (design §4). */
 export const SENDER_SOURCES = ["policy"];
 /**
@@ -377,7 +404,17 @@ export function resolveSender(load, sender, key = null) {
     // digits — so asking both questions widens nothing and lets one policy carry
     // a migration in progress. They are kept apart rather than concatenated
     // because WHICH one matched decides the form the record takes.
-    const rawClaimed = index.get(indexKey(sender.channel, sender.id)) ?? [];
+    //
+    // APRV-455: an OBSERVED id that already wears the keyed prefix is never
+    // compared raw. A Telegram id is digits and cannot wear it, so this changes
+    // nothing there; on a channel whose ids a relay reports, a caller that copied
+    // a digest out of the published policy and reported it as the account would
+    // otherwise match the keyed entry by string equality, without the key and
+    // without being the account. The keyed comparison below still runs, over the
+    // digest OF that string, which no approver's entry is.
+    const rawClaimed = isHashedSenderId(sender.id)
+        ? []
+        : (index.get(indexKey(sender.channel, sender.id)) ?? []);
     const keyedClaimed = key === null ? [] : (index.get(indexKey(sender.channel, hashedSenderId(key, sender.id))) ?? []);
     const claimed = [...rawClaimed, ...keyedClaimed];
     // THE FORM FOLLOWS THE ENTRY THAT MATCHED, so the id in the record is the