aegis-desktop 0.8.12 → 0.8.13

package/vendor/authorship-key.js

@@ -0,0 +1,366 @@
+'use strict';
+
+/**
+ * authorship-key.js — the key half of φ(α): keygen, and where `--secret` comes
+ * from.
+ *
+ * `client/fingerprint.js` is the vendored engine module and answers "is this
+ * record intact?". With the *public* covenant hash as key, that answer is
+ * "intact, and by the way anyone holding the covenant can also forge it" —
+ * integrity, not authorship. This file is the other half of that sentence: a
+ * private key under the user's own directory, at mode 600, that no one else
+ * has, so a valid record means "minted by whoever holds this key".
+ *
+ * ## The ladder (`resolveKey`)
+ *
+ *   1. `--secret <file>` (alias `--secret-file`, the engine's name)
+ *   2. `AEGIS_FINGERPRINT_SECRET` in the environment
+ *   3. `$AEGIS_HOME/keys/authorship.key` — the same path `keygen` writes
+ *   4. nothing: refuse, and say which command mints one.
+ *
+ * Step 4 is where this deliberately *diverges* from the engine. The engine's
+ * last rung is the published covenant hash, which keeps its tools runnable with
+ * no setup at all. Here an unconfigured host gets an error instead, because the
+ * plugin's records are meant to travel — a plugin record that silently keyed
+ * itself to a public constant would verify on every covenant holder's machine,
+ * which reads as authorship to everyone who did not look up how it was keyed.
+ * A caller who genuinely wants the engine's public mode says so explicitly:
+ * `--public --covenant <file>`, and that mode is labelled on every record it
+ * mints (`keySource` in the tool output, never inside the HMAC body — see
+ * below).
+ *
+ * ## What never happens
+ *
+ * The raw secret is never printed, never returned in a plain-object field that
+ * a `console.log` would surface, and never written anywhere but the key file.
+ * `keygen` returns a *derived* fingerprint — `keyFingerprint(secret)` from the
+ * vendored module, i.e. `sha256('aegiscode-agent-v1\n' + secret)[0:12]`, the
+ * same 12 hex the avatar registry indexes by — so a human can confirm two
+ * machines hold the same key without either machine revealing it. The
+ * derivation is spelled out here because the engine's own comment calls it a
+ * bare `sha256(secret)`, which it is not; the code is the contract, and both
+ * host tests re-derive the formula rather than trusting either description.
+ *
+ * Mode 600 is enforced twice on purpose: `fs.writeFileSync`'s `mode` is masked
+ * by the process umask, so passing it is not the same as getting it. The write
+ * is followed by an explicit `chmodSync` and a re-`stat` that throws if the
+ * result is not 0600 — a key that lands 644 must fail the operation, not warn
+ * about it. Both `resolveKey` and `backup` refuse a file that is group- or
+ * other-readable (any bit of 0o077); a secret the filesystem will hand to
+ * another user is not a secret. On Windows there is no POSIX mode to check, so
+ * the guarantee there is the directory (0700 under the user's profile) rather
+ * than the file — stated here because the tests can only assert the POSIX half.
+ *
+ * No privilege is involved anywhere: `node:fs`/`node:crypto` under `$HOME`, and
+ * one `git check-ignore` spawn in `backup` that is bounded and failure-tolerant.
+ */
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const fp = require('./fingerprint.js');
+
+/** 0600 — owner read/write only. Enforced after the write, and re-checked. */
+const KEY_FILE_MODE = 0o600;
+const DIR_MODE = 0o700;
+
+/** Any of these bits set means the file is readable by someone else. */
+const GROUP_OTHER_BITS = 0o077;
+
+/** 32 random bytes, base64url: 256 bits, matching the engine's keygen exactly. */
+const KEY_BYTES = 32;
+
+const SECRET_ENV = 'AEGIS_FINGERPRINT_SECRET';
+const HOME_ENV = 'AEGIS_HOME';
+const KEY_FILENAME = 'authorship.key';
+
+const isWin = process.platform === 'win32';
+
+// ---------------------------------------------------------------------------
+// paths
+// ---------------------------------------------------------------------------
+
+/** `$AEGIS_HOME`, else `~/.aegiscode` — the plugin's private store. */
+function dataDir(env = process.env) {
+  const home = env[HOME_ENV];
+  if (home && String(home).trim()) return path.resolve(String(home).trim());
+  return path.join(os.homedir(), '.aegiscode');
+}
+
+/** Where `keygen` writes with no `--out`, and the ladder's third rung. */
+function defaultKeyPath(env = process.env) {
+  return path.join(dataDir(env), 'keys', KEY_FILENAME);
+}
+
+function modeOf(file) {
+  return fs.statSync(file).mode & 0o777;
+}
+
+function modeString(mode) {
+  return mode.toString(8).padStart(3, '0');
+}
+
+/**
+ * Refuse a secret file that other users can read.
+ *
+ * Not a warning: `resolveKey` has already chosen this file, so continuing means
+ * minting records under a key the filesystem publishes. The message names the
+ * one-line fix, because the alternative fix a user reaches for first — deleting
+ * the key and starting over — orphans every record already minted under it.
+ */
+function assertPrivate(file) {
+  if (isWin) return; // no POSIX mode; the directory is the boundary (see header)
+  const mode = modeOf(file);
+  if (mode & GROUP_OTHER_BITS) {
+    throw new Error(
+      `authorship-key: ${file} is mode ${modeString(mode)} — a secret file must not be ` +
+        `group/other readable. chmod 600 ${file}`,
+    );
+  }
+}
+
+/** A key file is one line of base64url. Anything else is not one. */
+function readSecretFile(file) {
+  const raw = fs.readFileSync(file, 'utf8');
+  const secret = raw.replace(/\r?\n$/, '');
+  if (!secret.trim()) throw new Error(`authorship-key: ${file} is empty`);
+  if (/\s/.test(secret.trim())) {
+    throw new Error(`authorship-key: ${file} holds more than one line — not a key file`);
+  }
+  return secret.trim();
+}
+
+// ---------------------------------------------------------------------------
+// argv
+// ---------------------------------------------------------------------------
+
+/**
+ * `--secret` and `--secret-file` are the same flag. The engine spells it
+ * `--secret-file`; the plugin's docs and the request that produced this module
+ * both say `--secret`. Accepting one name and rejecting the other would be a
+ * parse error where a user means the same thing, so both are read here — once,
+ * in the shared module, so the CLI and the desktop cannot disagree about it.
+ */
+function flag(argv, name, fallback = null) {
+  const names = name === '--secret' ? ['--secret', '--secret-file'] : [name];
+  for (const n of names) {
+    const i = argv.indexOf(n);
+    if (i !== -1 && argv[i + 1] !== undefined && !argv[i + 1].startsWith('--')) return argv[i + 1];
+  }
+  return fallback;
+}
+
+function hasFlag(argv, name) {
+  const names = name === '--secret' ? ['--secret', '--secret-file'] : [name];
+  return names.some((n) => argv.includes(n));
+}
+
+// ---------------------------------------------------------------------------
+// the ladder
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the key to mint/verify with.
+ *
+ * @returns {{secret: string|null, source: string, public: boolean, path: string|null}}
+ *          `secret: null` means "no key configured" — the caller decides whether
+ *          that is a refusal (mint/verify) or an ordinary unconfigured state
+ *          (status), exactly as presence does with a missing API key.
+ */
+function resolveKey(o = {}) {
+  const argv = o.argv || [];
+  const env = o.env || process.env;
+
+  const file = flag(argv, '--secret');
+  if (file) {
+    if (!fs.existsSync(file)) throw new Error(`authorship-key: no such secret file: ${file}`);
+    assertPrivate(file);
+    return { secret: readSecretFile(file), source: file, public: false, path: file };
+  }
+
+  if (hasFlag(argv, '--public')) {
+    // Explicit public mode, and only with the document that defines the key.
+    const covenant = flag(argv, '--covenant');
+    if (!covenant) {
+      throw new Error(
+        'authorship-key: --public requires --covenant <file> — the public key IS the ' +
+          "covenant document's hash, so it cannot be assumed",
+      );
+    }
+    if (!fs.existsSync(covenant)) {
+      throw new Error(`authorship-key: no such covenant file: ${covenant}`);
+    }
+    const secret = crypto.createHash('sha256').update(fs.readFileSync(covenant)).digest('hex');
+    return { secret, source: `covenant (public): ${covenant}`, public: true, path: null };
+  }
+
+  const envSecret = env[SECRET_ENV];
+  if (envSecret && String(envSecret).trim()) {
+    return { secret: String(envSecret).trim(), source: SECRET_ENV, public: false, path: null };
+  }
+
+  const def = defaultKeyPath(env);
+  if (fs.existsSync(def)) {
+    assertPrivate(def);
+    return { secret: readSecretFile(def), source: def, public: false, path: def };
+  }
+
+  return { secret: null, source: null, public: false, path: null };
+}
+
+// ---------------------------------------------------------------------------
+// keygen
+// ---------------------------------------------------------------------------
+
+/**
+ * Mint a private key.
+ *
+ * `--out F` chooses the path (default `$AEGIS_HOME/keys/authorship.key`);
+ * `--force` overwrites an existing one. Without `--force` an existing key is an
+ * error, never a silent replacement: overwriting the key orphans every record
+ * ever minted under it, and the loss is invisible until someone verifies an old
+ * record. Replacing a key is a deliberate act, so it is a flag.
+ *
+ * @returns {{out: string, created: boolean, replaced: boolean,
+ *            keyFingerprint: string, bytes: number, secretPrinted: false, mode: string}}
+ */
+function keygen(o = {}) {
+  const argv = o.argv || [];
+  const env = o.env || process.env;
+  const out = path.resolve(flag(argv, '--out') || defaultKeyPath(env));
+  const force = hasFlag(argv, '--force') || o.force === true;
+
+  const exists = fs.existsSync(out);
+  if (exists && !force) {
+    throw new Error(`authorship-key: ${out} already exists — pass --force to replace it`);
+  }
+  if (exists && !isWin) {
+    // Replacing a key that is itself world-readable is how a *second* party
+    // ends up holding the old one; refuse rather than rotate on top of it.
+    assertPrivate(out);
+  }
+
+  const secret = crypto.randomBytes(KEY_BYTES).toString('base64url');
+  fs.mkdirSync(path.dirname(out), { recursive: true, mode: DIR_MODE });
+  fs.writeFileSync(out, secret + '\n', { mode: KEY_FILE_MODE });
+  // writeFileSync's mode is ANDed with the complement of the umask, so a 0022
+  // umask turns 0600 into 0644 and the call still "succeeds". Set it outright.
+  fs.chmodSync(out, KEY_FILE_MODE);
+  if (!isWin) {
+    const mode = modeOf(out);
+    if (mode !== KEY_FILE_MODE) {
+      throw new Error(
+        `authorship-key: ${out} landed mode ${modeString(mode)}, expected 600 — refusing to ` +
+          'report success for a key another user may be able to read',
+      );
+    }
+  }
+
+  // Read it back: a key that does not survive the round trip is worse than no
+  // key, because the fingerprint below would name something unrecoverable.
+  const readBack = readSecretFile(out);
+  if (readBack !== secret) throw new Error(`authorship-key: ${out} does not read back as written`);
+
+  return {
+    out,
+    created: !exists,
+    replaced: exists,
+    keyFingerprint: fp.keyFingerprint(secret),
+    bytes: KEY_BYTES,
+    secretPrinted: false,
+    mode: isWin ? 'n/a' : modeString(modeOf(out)),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// backup
+// ---------------------------------------------------------------------------
+
+function git(args, cwd) {
+  try {
+    return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  } catch {
+    return null;
+  }
+}
+
+function insideGitTree(dir) {
+  return git(['rev-parse', '--is-inside-work-tree'], dir) === 'true\n';
+}
+
+/**
+ * Copy the key to a destination that is not inside a git working tree, unless
+ * the destination is covered by that repo's `.gitignore`.
+ *
+ * The check exists because the failure it prevents is unrecoverable in the
+ * wrong direction: a key committed once is public forever, and rotating it does
+ * not un-publish it. `--allow-git` is the escape hatch for a user who has
+ * deliberately encrypted or otherwise protected the destination.
+ */
+function backup(o = {}) {
+  const argv = o.argv || [];
+  const env = o.env || process.env;
+  const to = flag(argv, '--to');
+  if (!to) throw new Error('authorship-key: backup requires --to DIR');
+
+  const from = flag(argv, '--secret') || defaultKeyPath(env);
+  if (!fs.existsSync(from)) throw new Error(`authorship-key: no key at ${from} — run keygen first`);
+  assertPrivate(from);
+
+  const destDir = path.resolve(to);
+  fs.mkdirSync(destDir, { recursive: true });
+  const name = flag(argv, '--name') || path.basename(from);
+  const dest = path.join(destDir, name);
+
+  if (insideGitTree(destDir) && !hasFlag(argv, '--allow-git') && !o.allowGit) {
+    const ignored = git(['check-ignore', '-q', dest], destDir);
+    if (ignored === null) {
+      throw new Error(
+        `authorship-key: ${dest} is inside a git working tree and is not gitignored — ` +
+          'a committed key cannot be un-published. Add it to .gitignore, choose another ' +
+          '--to, or pass --allow-git if you know the destination is protected',
+      );
+    }
+  }
+
+  const secret = readSecretFile(from);
+  fs.writeFileSync(dest, secret + '\n', { mode: KEY_FILE_MODE });
+  fs.chmodSync(dest, KEY_FILE_MODE);
+  if (!isWin && modeOf(dest) !== KEY_FILE_MODE) {
+    throw new Error(`authorship-key: ${dest} landed mode ${modeString(modeOf(dest))}, expected 600`);
+  }
+  if (readSecretFile(dest) !== secret) {
+    throw new Error(`authorship-key: ${dest} does not read back as the same key`);
+  }
+
+  return {
+    from,
+    to: dest,
+    keyFingerprint: fp.keyFingerprint(secret),
+    matchesSource: true,
+    secretPrinted: false,
+  };
+}
+
+module.exports = {
+  KEY_FILE_MODE,
+  DIR_MODE,
+  GROUP_OTHER_BITS,
+  KEY_BYTES,
+  SECRET_ENV,
+  HOME_ENV,
+  KEY_FILENAME,
+  dataDir,
+  defaultKeyPath,
+  assertPrivate,
+  readSecretFile,
+  flag,
+  hasFlag,
+  resolveKey,
+  keygen,
+  backup,
+  modeString,
+};

package/vendor/device-fingerprint.js

@@ -14,6 +14,21 @@
  */
 const crypto = require('node:crypto');
 const os = require('node:os');
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Where a per-install random id is persisted when the OS exposes no machine
+ * identity at all. Deliberately inside the same private store as the
+ * credentials, so `readMachineId()`-less hosts (minimal Linux containers
+ * without /etc/machine-id, hardened images, some CI runners) still get a
+ * collision-resistant fingerprint instead of a guessable one — while the
+ * credential store as a whole remains the single thing a wipe destroys.
+ */
+function installIdPath() {
+  const home = process.env.AEGISCODEX_HOME || path.join(os.homedir(), '.aegiscode');
+  return path.join(home, 'install-id');
+}
 
 /** Best-effort OS machine identity. Empty string, never throws, if none is reachable. */
 function readMachineId() {
@@ -50,14 +65,81 @@ function readMachineId() {
   return '';
 }
 
+/**
+ * A random 128-bit id persisted 0600 in the private store, minted on first
+ * need. Distinct from the machine identity: it survives a credential wipe
+ * only if the store itself survives, which is exactly the guarantee we can
+ * honestly make on a host that reports no machine id at all.
+ *
+ * @returns {string} hex id, or '' if the store is not writable.
+ */
+function persistedInstallId() {
+  const file = installIdPath();
+  const read = () => {
+    try {
+      const v = fs.readFileSync(file, 'utf8').trim();
+      return /^[0-9a-f]{32}$/.test(v) ? v : '';
+    } catch {
+      return '';
+    }
+  };
+  const existing = read();
+  if (existing) return existing;
+  try {
+    const fresh = crypto.randomBytes(16).toString('hex');
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(file, fresh, { mode: 0o600, flag: 'wx' });
+    return fresh;
+  } catch {
+    // Lost a race with a concurrent host process, or the store is read-only.
+    return read();
+  }
+}
+
 /**
  * sha256("aegiscode-plugin-device-v1:" + machine identity), hex.
  *
+ * Identity precedence, strongest first:
+ *   1. an explicit override (test-only),
+ *   2. the OS machine identity (`readMachineId()`),
+ *   3. a persisted random install id,
+ *   4. `hostname:platform:arch` — last resort, kept only so this never throws.
+ *
+ * Only step 4 is guessable by a third party; steps 2 and 3 are both per-host
+ * unique. `machineIdentityKind()` reports which one was used, so aegis1-side
+ * abuse review can tell a genuine re-registration from a forged one.
+ *
  * @param {string} [overrideId] - test-only override for the raw machine identity.
  */
 function machineFingerprint(overrideId) {
-  const id = overrideId || readMachineId() || `${os.hostname()}:${os.platform()}:${os.arch()}`;
-  return crypto.createHash('sha256').update(`aegiscode-plugin-device-v1:${id}`).digest('hex');
+  return crypto
+    .createHash('sha256')
+    .update(`aegiscode-plugin-device-v1:${machineIdentity(overrideId).id}`)
+    .digest('hex');
+}
+
+/** @returns {{kind: 'override'|'machine-id'|'install-id'|'hostname', id: string}} */
+function machineIdentity(overrideId) {
+  if (overrideId) return { kind: 'override', id: String(overrideId) };
+  const machine = readMachineId();
+  if (machine) return { kind: 'machine-id', id: machine };
+  const install = persistedInstallId();
+  if (install) return { kind: 'install-id', id: install };
+  return {
+    kind: 'hostname',
+    id: `${os.hostname()}:${os.platform()}:${os.arch()}`,
+  };
+}
+
+/** Which identity class the fingerprint on THIS host is derived from. */
+function machineIdentityKind() {
+  return machineIdentity().kind;
 }
 
-module.exports = { machineFingerprint, readMachineId };
+module.exports = {
+  machineFingerprint,
+  machineIdentity,
+  machineIdentityKind,
+  readMachineId,
+  persistedInstallId,
+};