aegis-desktop 0.8.12 → 0.8.13

package/vendor/fingerprint.js

@@ -0,0 +1,1061 @@
+'use strict';
+
+/**
+ * VENDORED — do not edit. Generated by tools/vendor-fingerprint.mjs.
+ *
+ * source:   aegiscodex 046ba6f — src/fingerprint.js
+ * rewrite:  ESM -> CJS, module syntax only. No constant, purpose string,
+ *           attested field list or digest differs from the engine's.
+ * verify:   node --test test/fingerprint-interop.test.mjs
+ * refresh:  node tools/vendor-fingerprint.mjs
+ */
+/**
+ * fingerprint.js — φ(α), the agent fingerprint.
+ *
+ * The covenant defines the thing this file mints:
+ *
+ *   Fingerprint  φ(α)  cryptographically verifiable identity
+ *                      carries reputation + track record + behavioural signature
+ *
+ * and then states the structural claim that makes it worth having: *identity and
+ * reputation are properties of the agent, not of the platform hosting it.* φ(α)
+ * travels. It is not a session token.
+ *
+ * So this module answers three separate questions, and keeps them separate:
+ *
+ *   1. "same credential?"      `keyFingerprint(secret)` — one-way, truncated.
+ *   2. "same behaviour?"       `behaviouralSignature(observations)` — a digest
+ *                              over what the agent actually did, order-independent
+ *                              so a re-ordered transcript is still the same agent.
+ *   3. "is this record intact?" `verify(record, secret)` — an HMAC attestation,
+ *                              compared in constant time.
+ *
+ * Four rules, and each is an assertion in `tests/fingerprint.test.mjs` rather
+ * than a sentence in a doc:
+ *
+ *  1. **A fingerprint is not an identity.** `keyFingerprint` says "same
+ *     credential", never "same person" — two agents on one box can legitimately
+ *     share a key. The record therefore keeps credential identity and behavioural
+ *     signature in separate fields and `same()` requires the caller to say which
+ *     one they mean.
+ *  2. **No key material escapes.** The raw secret is never a field, never a
+ *     substring of one, and `assertNoLeak` re-checks that on every minted record:
+ *     no field other than `attestation` may carry a long hex run. `keyFingerprint`
+ *     is truncated to the same 12 hex the avatar registry already uses, so a
+ *     fingerprint minted here indexes the same way a registry row does.
+ *  3. **A signature over nothing is not evidence.** `behaviouralSignature([])`
+ *     returns `null`, and the record records `behaviourSamples: 0`. Absence of
+ *     track record reads as absence, never as a zero-valued hash. The thumb axis
+ *     follows the same rule: fewer than `touch.MIN_STROKES` strokes gives
+ *     `touch: null`, `touchSamples: 0`.
+ *  4. **Verification is recomputation.** `verify` re-derives the attestation
+ *     from the attested fields only (`ATTESTED_FIELDS`), so appending fields to
+ *     a record cannot invalidate it and editing any attested field must.
+ *
+ * The fourth axis — `touch`, the thumb's gesture dynamics — is described in
+ * `src/touch.js`, including the part that matters most: it is **not** a
+ * fingerprint, because this hardware has no fingerprint sensor and the trackpad
+ * exposes no contact geometry through X. It is a behavioural biometric. Two
+ * consequences are structural here rather than documented:
+ *
+ *  - The thumb signature is **not keyed by the secret**. A credential says "same
+ *    key"; a habit says "same thumb". Keying one with the other would make every
+ *    agent sharing a credential look like the same hand.
+ *  - `mint` **recomputes** `touch` from the profile's medians via
+ *    `touch.signatureFromMedians`, so a `signature` field sitting in a captured
+ *    profile file is never trusted.
+ *
+ * The fifth axis is the **AI's own**: `aiKey` / `ai` / `aiSamples` / `aiModel`.
+ *
+ * Every axis above describes the *human* half of a turn — their credential, their
+ * demands, their thumb, their tree. Until v4 the mind on the other side of the
+ * turn was present only as `model`, a free-text label nobody attested, which is
+ * the one thing this module refuses elsewhere: a fabricated field is not
+ * evidence. So the record now carries both halves of a session, and they stay
+ * separate for the same reason credential identity and behaviour stay separate:
+ *
+ *  - `aiKey` is `keyFingerprint` of the credential the session *ran on* — the
+ *    model provider key, not the authorship key. Same derivation, same namespace,
+ *    so `same(a, b, 'ai-credential')` answers "same mind?" and `same(a, b,
+ *    'credential')` still answers "same author?" without one reading as the
+ *    other. It is `null` when the minter nominated no AI credential: an
+ *    un-nominated key must not hash to a shared value, and the record says
+ *    "nobody said which mind this was" rather than inventing one.
+ *  - `ai` is a digest over the assistant's turns (which tools, which targets,
+ *    which outcomes, which model), under its own frozen purpose string so an AI
+ *    digest and a human-turn digest over identical text can never collide. It is
+ *    **unkeyed**, exactly like `touch`: a habit says "same mind", not "same key".
+ *  - `aiSamples` counts the AI turns that carried signal, and `ai` is `null` when
+ *    none did — rule 3 again: absence of track record reads as absence.
+ *
+ * `aiModel` is the attested spelling of what `model` was only claiming: the model
+ * the session actually ran on, bounded and normalised like every other field.
+ *
+ * Record versions 1–3 have different attested bodies and are all kept, selected
+ * by `record.v`: an older record still verifies under its own field list rather
+ * than being silently unreadable.
+ *
+ * Pure: node:crypto only (plus the equally pure `src/touch.js`). No network, no
+ * spawn, no Electron — testable in plain Node, and safe to call in the
+ * autonomous queue where nothing is interactive.
+ */
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+
+const { signatureFromMedians, MIN_STROKES: TOUCH_MIN_STROKES } = require('./touch.js');
+
+/** Bump when the record shape changes; `verify` refuses versions it cannot read. */
+const FP_VERSION = 4;
+
+const FP_ALGO = 'sha256';
+const FP_PREFIX = 'φ_';
+
+/**
+ * `sha256(secret).slice(0, 12)` — deliberately identical in shape and length to
+ * `desktop/lib/avatar/identity.js`'s FINGERPRINT_LENGTH, because this value is
+ * what that module's `keyFingerprint` rung resolves against. Short on purpose:
+ * it is an index for a registry row, not an authenticator.
+ */
+const KEY_FP_LENGTH = 12;
+
+/** Behavioural signatures are truncated too — they are labels for comparison. */
+const SIG_LENGTH = 16;
+
+/** 128-bit HMAC tag. Not the key, so the long-hex rule below exempts it. */
+const ATTEST_LENGTH = 32;
+
+/** Longest hex run tolerated in a non-attestation field before we call it a leak. */
+const LEAK_HEX_RUN = 24;
+
+const MAX_LABEL = 40;
+const MAX_FIELD = 64;
+const MAX_TOOLS = 64;
+const MAX_OBSERVATIONS = 4096;
+const MAX_DEPTH = 8;
+
+/**
+ * The code axis. `CODE_LEN` is deliberately SIG_LENGTH: a 16-hex digest is
+ * shorter than `LEAK_HEX_RUN`, so the aggregate can never be mistaken for key
+ * material by `assertNoLeak`, and it is the same length as the behavioural
+ * signature, which is the same kind of claim.
+ */
+const CODE_LEN = SIG_LENGTH;
+const MAX_CODE_FILES = 4096;
+const MAX_PATH = 200;
+
+/** v1 attested body — no thumb axis. Kept so v1 records still verify. */
+const ATTESTED_FIELDS_V1 = Object.freeze([
+  'v',
+  'algo',
+  'keyFingerprint',
+  'label',
+  'account',
+  'model',
+  'tools',
+  'behaviour',
+  'behaviourSamples',
+  'createdAt',
+]);
+
+/**
+ * The purpose prefix of the behavioural digest is FROZEN and must not track
+ * `FP_VERSION`.
+ *
+ * It used to be `aegiscode-behaviour-v${FP_VERSION}`, which quietly coupled two
+ * unrelated things: bumping the *record shape* changed the *behavioural axis*.
+ * Same observations, new version, different signature — so a v2 record's
+ * `behaviour` could no longer be reproduced by re-running the tool that minted
+ * it, which is precisely what makes the axis comparable across time. The
+ * algorithm has not changed since v2, so the string is pinned there.
+ */
+const BEHAVIOUR_PURPOSE = 'aegiscode-behaviour-v2';
+
+/**
+ * The AI axis's purpose prefix, frozen for the same reason and separately from
+ * `BEHAVIOUR_PURPOSE`.
+ *
+ * Domain separation is the whole point of the string here: the human's turns and
+ * the assistant's turns are hashed from the same observation primer, so without a
+ * distinct prefix a record whose two axes happened to see the same text would
+ * carry one digest under two names — and "same author" would silently read as
+ * "same mind". Pinned to v1 and not to `FP_VERSION`: the algorithm must not
+ * change because the record shape did.
+ */
+const AI_PURPOSE = 'aegiscode-ai-v1';
+
+/** v2 attested body — adds the thumb axis. Field order is load-bearing and frozen. */
+const ATTESTED_FIELDS_V2 = Object.freeze([
+  'v',
+  'algo',
+  'keyFingerprint',
+  'label',
+  'account',
+  'model',
+  'tools',
+  'behaviour',
+  'behaviourSamples',
+  'touch',
+  'touchSamples',
+  'createdAt',
+]);
+
+/**
+ * v3 attested body — adds the code axis: *which revision of which files produced
+ * this turn*. Rule 4 still holds — appending a field to a record must not
+ * invalidate it — so a v1 or v2 record keeps verifying under its own list.
+ */
+const ATTESTED_FIELDS_V3 = Object.freeze([
+  'v',
+  'algo',
+  'keyFingerprint',
+  'label',
+  'account',
+  'model',
+  'tools',
+  'behaviour',
+  'behaviourSamples',
+  'touch',
+  'touchSamples',
+  'code',
+  'codeFiles',
+  'codeDirty',
+  'createdAt',
+]);
+
+/**
+ * v4 attested body — adds the AI axis: *which mind answered, and what it did*,
+ * beside the human half the earlier versions already carried.
+ *
+ * The AI fields sit before `createdAt` and after the human's, so the two halves
+ * read in the order a session happens (the demand, then the answer). Field order
+ * is load-bearing and frozen: this list is the attestation preimage, so
+ * reordering it would invalidate every v4 record ever minted.
+ */
+const ATTESTED_FIELDS_V4 = Object.freeze([
+  'v',
+  'algo',
+  'keyFingerprint',
+  'label',
+  'account',
+  'model',
+  'tools',
+  'behaviour',
+  'behaviourSamples',
+  'touch',
+  'touchSamples',
+  'code',
+  'codeFiles',
+  'codeDirty',
+  'aiKey',
+  'aiModel',
+  'ai',
+  'aiSamples',
+  'createdAt',
+]);
+
+/** The fields the current version attests. Exported for callers that print them. */
+const ATTESTED_FIELDS = ATTESTED_FIELDS_V4;
+
+const ATTESTED_FIELDS_BY_VERSION = Object.freeze({
+  1: ATTESTED_FIELDS_V1,
+  2: ATTESTED_FIELDS_V2,
+  3: ATTESTED_FIELDS_V3,
+  4: ATTESTED_FIELDS_V4,
+});
+
+/** null for a version this build cannot read — verification refuses rather than guesses. */
+function attestedFieldsFor(version) {
+  // `v` comes from untrusted JSON on the verify path. Two coercions make a
+  // bare property read wrong here: numeric keys are stored as strings, so
+  // ATTESTED_FIELDS_BY_VERSION['2'] resolves and a record carrying the *string*
+  // "2" would pin its own field list; and an inherited key ('constructor',
+  // '__proto__') resolves to a function or object rather than a field list.
+  // Require a real integer and an own property.
+  if (typeof version !== 'number' || !Number.isInteger(version)) return null;
+  return Object.prototype.hasOwnProperty.call(ATTESTED_FIELDS_BY_VERSION, version)
+    ? ATTESTED_FIELDS_BY_VERSION[version]
+    : null;
+}
+
+// ---------------------------------------------------------------------------
+// canonicalisation
+// ---------------------------------------------------------------------------
+
+/**
+ * Collapse a value to its comparable form: trimmed, whitespace-collapsed,
+ * lowercased. Hashing is the only consumer, so display casing is preserved only
+ * in `label`.
+ */
+function normalise(value) {
+  if (value === null || value === undefined) return '';
+  return String(value).trim().replace(/\s+/g, ' ').toLowerCase();
+}
+
+/**
+ * Deterministic JSON: keys sorted, undefined/function/symbol dropped, numbers
+ * non-finite -> null, strings normalised, recursion bounded. Two structurally
+ * equal records always produce byte-identical output, which is what lets
+ * `verify` be a recomputation rather than a stored comparison.
+ */
+function canonical(value, depth = 0) {
+  if (depth > MAX_DEPTH) return '"[depth]"';
+  if (value === null || value === undefined) return 'null';
+
+  const t = typeof value;
+  if (t === 'number') return Number.isFinite(value) ? String(value) : 'null';
+  if (t === 'boolean') return value ? 'true' : 'false';
+  if (t === 'string') return JSON.stringify(normalise(value));
+  if (t === 'function' || t === 'symbol' || t === 'bigint') return 'null';
+
+  if (Array.isArray(value)) {
+    return '[' + value.map((v) => canonical(v, depth + 1)).join(',') + ']';
+  }
+
+  if (t === 'object') {
+    const keys = Object.keys(value)
+      .filter((k) => value[k] !== undefined && typeof value[k] !== 'function')
+      .sort();
+    return (
+      '{' +
+      keys.map((k) => JSON.stringify(k) + ':' + canonical(value[k], depth + 1)).join(',') +
+      '}'
+    );
+  }
+
+  return 'null';
+}
+
+/** Purpose-prefixed digest, hex. The prefix keeps one purpose's digest from ever
+ * colliding with another's over the same input. */
+function digest(purpose, body) {
+  return crypto.createHash(FP_ALGO).update(purpose + '\n' + body, 'utf8').digest('hex');
+}
+
+// ---------------------------------------------------------------------------
+// redaction helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * A label safe to store and display: bounded length, and control characters /
+ * newlines stripped so a value can never forge a second record line. Mirrors
+ * `avatar/identity.js`'s `safeLabel`, including its rule that a rejected value
+ * is never echoed back.
+ */
+function safeLabel(value, max = MAX_LABEL) {
+  if (value === null || value === undefined) return '';
+  const cleaned = String(value)
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\u0000-\u001f\u007f]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (!cleaned) return '';
+  return cleaned.length > max ? cleaned.slice(0, max) : cleaned;
+}
+
+/** Any run of >= `n` hex characters. Keys, digests and seeds all look like this. */
+function longHexRun(value, n = LEAK_HEX_RUN) {
+  return new RegExp(`[0-9a-fA-F]{${n},}`).test(String(value));
+}
+
+const HEX_ATTESTATION = new RegExp(`^[0-9a-f]{${ATTEST_LENGTH}}$`);
+
+function isFingerprintShape(value) {
+  return new RegExp(`^[0-9a-f]{${KEY_FP_LENGTH}}$`).test(String(value || ''));
+}
+
+/**
+ * Refuse to return a record that carries the secret or anything that looks like
+ * a key. Throws rather than redacting: a caller that reached this point has a
+ * bug in the shape of what it passes in, and silently dropping the field would
+ * hide it.
+ */
+function assertNoLeak(record, secret, alsoSecret) {
+  const secrets = [secret, alsoSecret]
+    .map((v) => (v === null || v === undefined ? '' : String(v)))
+    .filter(Boolean);
+  for (const [key, value] of Object.entries(record)) {
+    if (value === null || value === undefined) continue;
+    const text = Array.isArray(value) ? value.join('\u0000') : String(value);
+
+    for (const s of secrets) {
+      if (text.includes(s)) {
+        throw new Error(`fingerprint: field "${key}" would carry the secret verbatim`);
+      }
+    }
+    if (key === 'attestation') {
+      if (!HEX_ATTESTATION.test(text)) {
+        throw new Error('fingerprint: attestation must be 32 lowercase hex characters');
+      }
+      continue;
+    }
+    if (longHexRun(text)) {
+      throw new Error(`fingerprint: field "${key}" carries a long hex run (possible key leak)`);
+    }
+  }
+  return true;
+}
+
+/**
+ * The same rule, applied to the *raw* inputs before any bounding.
+ *
+ * Without this, truncation is a laundering route: `label: 'x'.repeat(12) + secret`
+ * gets cut to MAX_LABEL, the secret no longer appears whole, and twenty hex
+ * characters of a live key land in the record unremarked. A caller that hands a
+ * credential to a display field has a bug, and rule 2 says a caller bug in this
+ * shape becomes loud rather than quiet — which is exactly what `assertNoLeak`
+ * cannot do once the value has already been trimmed to fit.
+ */
+function assertInputsClean(inputs, secret, alsoSecret) {
+  const secrets = [secret, alsoSecret]
+    .map((v) => (v === null || v === undefined ? '' : String(v)))
+    .filter(Boolean);
+  if (!secrets.length) return true;
+  for (const field of ['label', 'account', 'model', 'tools', 'aiModel']) {
+    const value = inputs[field];
+    if (value === null || value === undefined) continue;
+    const text = Array.isArray(value) ? value.join('\u0000') : String(value);
+    if (secrets.some((s) => text.includes(s))) {
+      throw new Error(`fingerprint: input "${field}" would carry the secret verbatim`);
+    }
+    if (longHexRun(text)) {
+      throw new Error(`fingerprint: input "${field}" carries a long hex run (possible key leak)`);
+    }
+  }
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// 1. credential identity
+// ---------------------------------------------------------------------------
+
+/**
+ * `sha256('aegiscode-agent-v1:' + secret).slice(0, 12)`, hex — or `null` when no
+ * secret is available, because "no credential" must not hash to a shared value
+ * that would make every keyless agent look like the same agent.
+ *
+ * @param {string} secret - API key, device fingerprint seed, or any stable credential.
+ * @returns {string|null}
+ */
+function keyFingerprint(secret) {
+  if (secret === null || secret === undefined) return null;
+  const s = String(secret).trim();
+  if (!s) return null;
+  return digest('aegiscode-agent-v1', s).slice(0, KEY_FP_LENGTH);
+}
+
+// ---------------------------------------------------------------------------
+// 2. behavioural signature
+// ---------------------------------------------------------------------------
+
+/** One observation rendered canonically, or '' if it carries nothing usable. */
+function observationKey(observation) {
+  if (typeof observation === 'string' || typeof observation === 'number') {
+    return normalise(observation);
+  }
+  if (!observation || typeof observation !== 'object') return '';
+  const parts = [observation.tool, observation.target, observation.outcome, observation.model]
+    .map((p) => normalise(p))
+    .join('|');
+  return parts.replace(/^\|+|\|+$/g, '') ? parts : '';
+}
+
+/** How many observations actually carried signal. */
+function countObservations(observations) {
+  if (!Array.isArray(observations)) return 0;
+  return observations.slice(0, MAX_OBSERVATIONS).filter((o) => observationKey(o) !== '').length;
+}
+
+/**
+ * A digest over a set of observations — deduplicated and sorted, so the same set
+ * of actions fingerprints identically however the transcript was ordered, and a
+ * replayed action adds nothing. This is the "behavioural signature" of the
+ * covenant, not a transcript hash: two agents that used the same tools the same
+ * way match, and a padded log does not inflate the match.
+ *
+ * The purpose string is a parameter because this primer serves two axes that must
+ * not be able to agree by accident — the human's turns and the assistant's (see
+ * `AI_PURPOSE`). Callers outside this file get `behaviouralSignature` and
+ * `aiSignature`, each with its purpose bound.
+ *
+ * @returns {string|null} null when there is no observable behaviour — see rule 3.
+ */
+function signatureFromObservations(observations, purpose) {
+  if (!Array.isArray(observations)) return null;
+  const keys = observations
+    .slice(0, MAX_OBSERVATIONS)
+    .map(observationKey)
+    .filter(Boolean);
+  if (!keys.length) return null;
+  const unique = Array.from(new Set(keys)).sort();
+  return digest(purpose, unique.join('\n')).slice(0, SIG_LENGTH);
+}
+
+function behaviouralSignature(observations) {
+  return signatureFromObservations(observations, BEHAVIOUR_PURPOSE);
+}
+
+/**
+ * The AI axis's behavioural signature: the same primer over the assistant's own
+ * turns, under `AI_PURPOSE`.
+ *
+ * `null` for no observations, for the same reason `behaviouralSignature` is: a
+ * mind with no recorded track record has no track record, and rendering that as a
+ * zero-valued hash would be a claim the evidence does not support.
+ */
+function aiSignature(observations) {
+  return signatureFromObservations(observations, AI_PURPOSE);
+}
+
+/** Bounded, deduplicated tool list in canonical order. */
+function normaliseTools(tools) {
+  if (!Array.isArray(tools)) return Object.freeze([]);
+  const seen = new Set();
+  for (const t of tools.slice(0, MAX_TOOLS)) {
+    const n = normalise(typeof t === 'string' ? t : (t && (t.name || t.id)) || '');
+    if (n) seen.add(n);
+  }
+  return Object.freeze(Array.from(seen).sort());
+}
+
+// ---------------------------------------------------------------------------
+// 2b. the code axis — which revision of which files produced this turn
+// ---------------------------------------------------------------------------
+
+/**
+ * A repo-relative path in comparable form, or `null` if unusable.
+ *
+ * Separators are normalised to `/` and a leading `./` is dropped so the same
+ * file reached two ways hashes once. Absolute paths and any path containing a
+ * `..` segment are refused rather than "cleaned": a record whose paths could
+ * escape its own root would name files outside the tree it claims to describe,
+ * and the whole point of the axis is that the claim is recomputable.
+ */
+function normaliseCodePath(value) {
+  if (value === null || value === undefined) return null;
+  const raw = String(value).replace(/\\/g, '/').trim();
+  if (!raw) return null;
+  if (raw.startsWith('/') || /^[a-zA-Z]:\//.test(raw)) return null;
+  const parts = [];
+  for (const seg of raw.split('/')) {
+    if (seg === '' || seg === '.') continue;
+    if (seg === '..') return null;
+    parts.push(seg);
+  }
+  const rel = parts.join('/');
+  if (!rel) return null;
+  return rel.length > MAX_PATH ? null : rel;
+}
+
+/**
+ * One file's contribution: `sha256('aegiscode-code-v3' + '\0' + relpath + '\0' +
+ * content)`.
+ *
+ * The path is inside the hash on purpose. Hashing contents alone would make a
+ * rename invisible, and a tree where `auth.js` and `handler.js` swap names is
+ * not the same tree. Length-prefixing nothing and delimiting with NUL keeps
+ * path and content from bleeding into each other: `('ab', 'c')` and `('a',
+ * 'bc')` cannot collide.
+ */
+function codeFileDigest(relpath, content) {
+  const rel = normaliseCodePath(relpath);
+  if (!rel) throw new Error(`fingerprint: unusable code path ${JSON.stringify(String(relpath))}`);
+  const buf = Buffer.isBuffer(content)
+    ? content
+    : Buffer.from(content === null || content === undefined ? '' : String(content), 'utf8');
+  return crypto
+    .createHash(FP_ALGO)
+    .update(`aegiscode-code-v3\u0000${rel}\u0000`, 'utf8')
+    .update(buf)
+    .digest('hex');
+}
+
+/**
+ * Fold per-file digests, in sorted path order, into one 16-hex aggregate.
+ *
+ * Order-independence comes from the sort, not from the caller: a directory walk
+ * returns files in whatever order the filesystem feels like, and two walks of
+ * one tree must agree. The fold chains each file's digest into the running
+ * accumulator, so moving a byte from one file to another changes the result —
+ * unlike summing or XOR-ing per-file digests, which would not.
+ *
+ * @param {Array<{path: string, content: string|Buffer}>} files
+ * @returns {{code: string|null, codeFiles: number}} `null`/`0` for no files —
+ *          absence of code evidence reads as absence (rule 3), never as a
+ *          zero-valued hash that a caller might mistake for a real revision.
+ */
+function codeDigest(files) {
+  if (!Array.isArray(files)) return { code: null, codeFiles: 0 };
+
+  // Sorted input, duplicates resolved last-wins: a path listed twice is the same
+  // file twice, and folding both would make the aggregate depend on how many
+  // times the caller mentioned it.
+  const byPath = new Map();
+  for (const f of files) {
+    if (!f || typeof f !== 'object') continue;
+    const rel = normaliseCodePath(f.path);
+    if (!rel) continue;
+    byPath.set(rel, { path: rel, content: f.content });
+  }
+  const entries = Array.from(byPath.keys()).sort();
+  if (!entries.length) return { code: null, codeFiles: 0 };
+  if (entries.length > MAX_CODE_FILES) {
+    throw new Error(
+      `fingerprint: ${entries.length} code files exceeds MAX_CODE_FILES (${MAX_CODE_FILES}); ` +
+        'hash a subtree rather than silently attesting a prefix of one',
+    );
+  }
+
+  let acc = digest('aegiscode-code-v3-root', String(entries.length));
+  for (const rel of entries) {
+    const d = codeFileDigest(rel, byPath.get(rel).content);
+    acc = digest('aegiscode-code-v3-fold', `${acc}\n${rel}\n${d}`);
+  }
+  return { code: acc.slice(0, CODE_LEN), codeFiles: entries.length };
+}
+
+/**
+ * The code axis of a record, with dirtiness passed through honestly.
+ *
+ * `codeDirty` is `true`/`false` only when the caller actually knew; anything
+ * else is `null`. The CLI cannot tell clean from dirty without spawning `git`,
+ * and this module's callers are promised a module that spawns nothing — so
+ * "unknown" is a state the record is allowed to be in, and it is stored as
+ * unknown rather than being rendered as `false`, which would be a claim the
+ * evidence does not support.
+ */
+function codeAxisFrom(files, codeDirty) {
+  const { code, codeFiles } = codeDigest(files);
+  const dirty = typeof codeDirty === 'boolean' ? codeDirty : null;
+  return { code, codeFiles, codeDirty: code ? dirty : null };
+}
+
+// ---------------------------------------------------------------------------
+// 2c. the AI axis — which mind answered, and what it did
+// ---------------------------------------------------------------------------
+
+/**
+ * Fold the AI half of a record out of the caller's inputs.
+ *
+ * Every field degrades to `null`/`0` rather than to a stand-in value, and for the
+ * same reason the other axes do: a record may carry only what was observed.
+ *
+ *  - no nominated credential      ⇒ `aiKey: null`. NOT a hash of the authorship
+ *    key: the authorship key says who *sealed* the record, and reusing it here
+ *    would make every record look like it ran under its author's own key, which
+ *    is a claim about the session that nobody made.
+ *  - no AI observations           ⇒ `ai: null, aiSamples: 0` (rule 3).
+ *  - no model named               ⇒ `aiModel: null`, never the empty string.
+ *
+ * @param {object} [axis]
+ * @param {string} [axis.secret]      - the credential the session ran on. Never stored.
+ * @param {string} [axis.model]       - the model that answered.
+ * @param {Array}  [axis.observations]- the assistant's turns: `{tool, target, outcome, model}`.
+ * @returns {{aiKey: string|null, aiModel: string|null, ai: string|null, aiSamples: number}}
+ */
+function aiAxisFrom(axis = {}) {
+  const { secret, model, observations } = axis || {};
+  const aiKey = keyFingerprint(secret);
+  const ai = aiSignature(observations);
+  return {
+    aiKey,
+    aiModel: safeLabel(model, MAX_FIELD) || null,
+    ai,
+    aiSamples: ai ? countObservations(observations) : 0,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// 3. mint / attest / verify
+// ---------------------------------------------------------------------------
+
+/**
+ * The exact bytes the attestation covers. The field list is chosen by the
+ * record's own `v`, so a v1 record is attested over v1's fields and keeps
+ * verifying after the shape moved on. Unknown fields are ignored either way.
+ */
+function attestationBody(record) {
+  const fields = attestedFieldsFor(record && record.v);
+  if (!fields) {
+    throw new Error(`fingerprint: cannot attest version ${record && record.v}`);
+  }
+  const body = {};
+  for (const field of fields) {
+    const v = record[field];
+    body[field] = v === undefined ? null : v;
+  }
+  return canonical(body);
+}
+
+/** HMAC-SHA256(secret, attested fields), truncated to 128 bits. */
+function attest(record, secret) {
+  if (!secret) throw new Error('fingerprint: a secret is required to attest a record');
+  return crypto
+    .createHmac(FP_ALGO, String(secret))
+    .update(attestationBody(record), 'utf8')
+    .digest('hex')
+    .slice(0, ATTEST_LENGTH);
+}
+
+function isoTs(value) {
+  if (value === null || value === undefined) return new Date().toISOString();
+  const d = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(d.getTime())) throw new Error('fingerprint: createdAt is not a valid date');
+  return d.toISOString();
+}
+
+/**
+ * The thumb axis of a record, recomputed from a captured profile's medians.
+ *
+ * Deliberately ignores any `signature` field the profile carries: recomputation
+ * is what makes the record's thumb axis trustworthy, and trusting the file's own
+ * hash would make it the one field in φ(α) that was taken on faith. Unusable
+ * input degrades to "no thumb axis" (`null`/`0`), never to a zero-valued hash and
+ * never to a leaked string.
+ *
+ * @param {object} profile - shape as produced by `src/touch.js`'s `profile()`.
+ * @returns {{signature: string|null, samples: number}}
+ */
+function touchSignatureFrom(profile) {
+  if (!profile || typeof profile !== 'object') return { signature: null, samples: 0 };
+  const samples = Number(profile.samples) || 0;
+  const signature = signatureFromMedians(profile.medians, samples);
+  return { signature, samples: signature ? samples : 0 };
+}
+
+/**
+ * Mint φ(α).
+ *
+ * @param {object} input
+ * @param {string} input.secret      - credential; required. Never stored.
+ * @param {string} [input.label]     - human display name.
+ * @param {string} [input.account]   - cloud account id (survives key rotation).
+ * @param {string} [input.model]     - model the agent runs on.
+ * @param {string[]} [input.tools]   - tools it can reach.
+ * @param {Array} [input.observations] - what it did; feeds the behavioural signature.
+ * @param {object} [input.touch]     - thumb profile from `src/touch.js`; feeds the
+ *                                     gesture-dynamics signature. NOT keyed by the
+ *                                     secret: a credential is not a hand.
+ * @param {Array<{path: string, content: string|Buffer}>} [input.code]
+ *                                   - the revision this turn ran against, as
+ *                                     repo-relative path + content pairs. The
+ *                                     walk that produces them lives in the caller
+ *                                     (a tool), so this module stays I/O-free
+ *                                     apart from test vectors.
+ * @param {boolean} [input.codeDirty] - whether that tree had uncommitted changes,
+ *                                     when the caller could actually tell.
+ * @param {string|Date} [input.createdAt]
+ * @returns {object} frozen, attested record.
+ */
+function mint(input = {}) {
+  const {
+    secret,
+    label,
+    account,
+    model,
+    tools,
+    observations,
+    touch,
+    code,
+    codeDirty,
+    aiSecret,
+    aiModel,
+    aiObservations,
+    createdAt,
+  } = input;
+  const kf = keyFingerprint(secret);
+  if (!kf) {
+    throw new Error('fingerprint: a secret (API key or device seed) is required to mint φ(α)');
+  }
+
+  // Before bounding: a key in a display field must refuse, not get truncated.
+  // Both credentials are checked — the AI's key is a live provider key, and a
+  // record carrying it in `aiModel` would be exactly the leak this guard exists
+  // to catch.
+  assertInputsClean({ label, account, model, tools, aiModel }, secret, aiSecret);
+
+  const thumb = touchSignatureFrom(touch);
+  const codeAxis = codeAxisFrom(code, codeDirty);
+  const ai = aiAxisFrom({ secret: aiSecret, model: aiModel, observations: aiObservations });
+
+  const record = {
+    v: FP_VERSION,
+    algo: FP_ALGO,
+    keyFingerprint: kf,
+    label: safeLabel(label, MAX_LABEL),
+    account: safeLabel(account, MAX_FIELD) || null,
+    model: safeLabel(model, MAX_FIELD) || null,
+    tools: normaliseTools(tools),
+    behaviour: behaviouralSignature(observations),
+    behaviourSamples: countObservations(observations),
+    touch: thumb.signature,
+    touchSamples: thumb.samples,
+    code: codeAxis.code,
+    codeFiles: codeAxis.codeFiles,
+    codeDirty: codeAxis.codeDirty,
+    aiKey: ai.aiKey,
+    aiModel: ai.aiModel,
+    ai: ai.ai,
+    aiSamples: ai.aiSamples,
+    createdAt: isoTs(createdAt),
+  };
+
+  const sealed = { ...record, attestation: attest(record, secret) };
+  assertNoLeak(sealed, secret, aiSecret);
+  return Object.freeze(sealed);
+}
+
+/** `φ_<keyFingerprint><behaviour|——>`: short, stable, safe to log. */
+function id(record) {
+  if (!record || !isFingerprintShape(record.keyFingerprint)) {
+    throw new Error('fingerprint: not a fingerprinted record');
+  }
+  return `${FP_PREFIX}${record.keyFingerprint}-${record.behaviour || 'unobserved'}`;
+}
+
+function sameReason(record) {
+  if (!record || typeof record !== 'object') return 'not a record';
+  if (!attestedFieldsFor(record.v)) return `unsupported version ${record.v}`;
+  if (record.algo !== FP_ALGO) return `unsupported algo ${record.algo}`;
+  if (!isFingerprintShape(record.keyFingerprint)) return 'keyFingerprint is malformed';
+  return null;
+}
+
+/**
+ * Verify a record by recomputation, not by trusting its stored tag.
+ *
+ * @returns {{ok: boolean, reason: string|null, id: string|null, credentialMatch: boolean|null}}
+ */
+function verify(record, secret) {
+  const bad = sameReason(record);
+  if (bad) return { ok: false, reason: bad, id: null, credentialMatch: null };
+
+  const credentialMatch = secret ? keyFingerprint(secret) === record.keyFingerprint : null;
+
+  if (!secret) {
+    return {
+      ok: false,
+      reason: 'no secret supplied — attestation cannot be recomputed',
+      id: id(record),
+      credentialMatch: null,
+    };
+  }
+
+  const expected = attest(record, secret);
+  const got = String(record.attestation || '');
+  const a = Buffer.from(expected, 'utf8');
+  const b = Buffer.from(got.padEnd(expected.length, ' ').slice(0, expected.length), 'utf8');
+  const tagOk = a.length === b.length && crypto.timingSafeEqual(a, b);
+
+  if (!tagOk) {
+    return { ok: false, reason: 'attestation mismatch', id: id(record), credentialMatch };
+  }
+  if (!credentialMatch) {
+    return {
+      ok: false,
+      reason: 'attestation valid but secret does not match keyFingerprint',
+      id: id(record),
+      credentialMatch: false,
+    };
+  }
+  return { ok: true, reason: null, id: id(record), credentialMatch: true };
+}
+
+/**
+ * Compare two records on one axis. Explicit on purpose: "same credential" and
+ * "same behaviour" are different claims (rule 1), and a caller that does not say
+ * which one it wants gets an error rather than an answer.
+ *
+ * @param {'credential'|'behaviour'|'full'} axis
+ */
+function same(a, b, axis = 'full') {
+  if (!a || !b) return false;
+  if (axis === 'credential') return a.keyFingerprint === b.keyFingerprint;
+  if (axis === 'behaviour') {
+    return Boolean(a.behaviour) && a.behaviour === b.behaviour;
+  }
+  if (axis === 'full') {
+    return a.keyFingerprint === b.keyFingerprint && a.behaviour === b.behaviour;
+  }
+  if (axis === 'ai-credential') {
+    return Boolean(a.aiKey) && a.aiKey === b.aiKey;
+  }
+  if (axis === 'ai') {
+    return Boolean(a.ai) && a.ai === b.ai;
+  }
+  if (axis === 'mind') {
+    return (
+      Boolean(a.aiKey) && a.aiKey === b.aiKey && Boolean(a.ai) && a.ai === b.ai
+    );
+  }
+  throw new Error(`fingerprint: unknown comparison axis "${axis}"`);
+}
+
+/** Display form. Carries no field a key could hide in. */
+function describe(record) {
+  const bad = sameReason(record);
+  if (bad) return `φ(?) ${bad}`;
+  const bits = [
+    `key ${record.keyFingerprint}`,
+    record.behaviour ? `behaviour ${record.behaviour}` : 'behaviour unobserved',
+    record.behaviourSamples ? `${record.behaviourSamples} samples` : null,
+    record.touch ? `touch ${record.touch}` : 'touch unobserved',
+    record.touchSamples ? `${record.touchSamples} strokes` : null,
+    record.code
+      ? `code ${record.code}${record.codeDirty === null ? '' : record.codeDirty ? ' (dirty)' : ' (clean)'}`
+      : 'code unobserved',
+    record.codeFiles ? `${record.codeFiles} files` : null,
+    record.ai && record.aiKey
+      ? `ai ${record.ai} on ${record.aiKey}`
+      : record.ai
+        ? `ai ${record.ai} (no key nominated)`
+        : record.aiKey
+          ? `ai key ${record.aiKey}, behaviour unobserved`
+          : 'ai unobserved',
+    record.aiSamples ? `${record.aiSamples} ai turn(s)` : null,
+    record.aiModel ? `ran on ${record.aiModel}` : null,
+    record.model ? `model ${record.model}` : null,
+    record.tools && record.tools.length ? `tools ${record.tools.length}` : null,
+  ].filter(Boolean);
+  return `${record.label || 'agent'} · ${bits.join(' · ')}`;
+}
+
+// ---------------------------------------------------------------------------
+// CLI — `node src/fingerprint.js --label x --observations file.json`
+//      `node src/fingerprint.js --ai-observations ai.json --ai-model gpt-5`
+//      `node src/fingerprint.js --verify record.json`
+//
+// The secret comes from AEGIS_FINGERPRINT_SECRET or --secret-file, never from
+// argv: argv is visible in `ps` to every process on the box.
+// ---------------------------------------------------------------------------
+
+/**
+ * The AI half's credential, from the same two rungs as the authorship secret and
+ * never from argv (a key in `ps` is a published key).
+ *
+ * It is read from `AEGIS_AI_SECRET`, then `--ai-secret-file`. Deliberately a
+ * separate variable from `AEGIS_FINGERPRINT_SECRET`: the authorship key seals the
+ * record, the AI key names the mind that answered, and a single variable would
+ * make "sealed by" and "ran on" the same value by default — the conflation the two
+ * fields exist to prevent.
+ */
+function readAiSecret(argv, env) {
+  if (env.AEGIS_AI_SECRET) return String(env.AEGIS_AI_SECRET).trim();
+  const i = argv.indexOf('--ai-secret-file');
+  if (i !== -1 && argv[i + 1]) {
+    return fs.readFileSync(argv[i + 1], 'utf8').trim();
+  }
+  return '';
+}
+
+function readSecret(argv, env) {
+  if (env.AEGIS_FINGERPRINT_SECRET) return String(env.AEGIS_FINGERPRINT_SECRET).trim();
+  const i = argv.indexOf('--secret-file');
+  if (i !== -1 && argv[i + 1]) {
+    return fs.readFileSync(argv[i + 1], 'utf8').trim();
+  }
+  return '';
+}
+
+function flag(argv, name, fallback = null) {
+  const i = argv.indexOf(name);
+  return i !== -1 && argv[i + 1] !== undefined ? argv[i + 1] : fallback;
+}
+
+function main(argv, env = process.env) {
+  const secret = readSecret(argv, env);
+
+  if (argv.includes('--verify')) {
+    const file = flag(argv, '--verify');
+    if (!file) throw new Error('fingerprint: --verify needs a record file');
+    const record = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const result = verify(record, secret);
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    return result.ok ? 0 : 1;
+  }
+
+  const obsFile = flag(argv, '--observations');
+  const observations = obsFile ? JSON.parse(fs.readFileSync(obsFile, 'utf8')) : [];
+
+  // The thumb profile comes from `tools/aegis-touchpad.mjs capture`. Only its
+  // medians are used; its own `signature` field is recomputed, not believed.
+  const touchFile = flag(argv, '--touch');
+  const touch = touchFile ? JSON.parse(fs.readFileSync(touchFile, 'utf8')) : null;
+
+  // The AI half: which mind answered, and what it did. The observations file is a
+  // separate one because the two axes are separate claims — a session log's
+  // `reply` text is not an AI observation, and `--ai-observations` is the caller
+  // saying it actually has some.
+  const aiObsFile = flag(argv, '--ai-observations');
+  const aiObservations = aiObsFile ? JSON.parse(fs.readFileSync(aiObsFile, 'utf8')) : null;
+
+  const record = mint({
+    secret,
+    label: flag(argv, '--label', ''),
+    account: flag(argv, '--account', ''),
+    model: flag(argv, '--model', ''),
+    tools: (flag(argv, '--tools', '') || '').split(',').filter(Boolean),
+    observations,
+    touch,
+    aiSecret: readAiSecret(argv, env),
+    aiModel: flag(argv, '--ai-model', ''),
+    aiObservations,
+  });
+  process.stdout.write(JSON.stringify(record, null, 2) + '\n');
+  return 0;
+}
+
+const API = {
+  // identity
+  mint,
+  verify,
+  attest,
+  attestationBody,
+  id,
+  same,
+  describe,
+  // pieces
+  keyFingerprint,
+  behaviouralSignature,
+  aiSignature,
+  aiAxisFrom,
+  observationKey,
+  countObservations,
+  normaliseTools,
+  safeLabel,
+  touchSignatureFrom,
+  normaliseCodePath,
+  codeFileDigest,
+  codeDigest,
+  codeAxisFrom,
+  // guards & constants
+  canonical,
+  assertNoLeak,
+  assertInputsClean,
+  longHexRun,
+  isFingerprintShape,
+  attestedFieldsFor,
+  FP_VERSION,
+  FP_ALGO,
+  FP_PREFIX,
+  KEY_FP_LENGTH,
+  SIG_LENGTH,
+  ATTEST_LENGTH,
+  LEAK_HEX_RUN,
+  CODE_LEN,
+  MAX_CODE_FILES,
+  MAX_PATH,
+  BEHAVIOUR_PURPOSE,
+  AI_PURPOSE,
+  ATTESTED_FIELDS,
+  ATTESTED_FIELDS_V1,
+  ATTESTED_FIELDS_V2,
+  ATTESTED_FIELDS_V3,
+  ATTESTED_FIELDS_V4,
+  ATTESTED_FIELDS_BY_VERSION,
+  main,
+};
+
+
+
+module.exports = API;