@consiliency/agent-board-cli 1.24.0 → 1.26.0

package/keyslot/agent-board-keyslot-load@.service

@@ -0,0 +1,20 @@
+# Installed to ~/.config/systemd/user/ by scripts/keyslot/provision.sh (IF-0-KEYSEAL-2).
+# Loads the slot key into agent-board-keyslot@%i whenever that agent starts or restarts: a
+# sealed key by decrypting it into a pipe, or an opted-in unsealed key from its 0600 file (A1).
+# slot-%i is a per-slot symlink to the immutable loader version that slot runs (A1).
+[Unit]
+Description=Message Board key slot loader for %i (sealed key via a pipe, or opted-in unsealed key)
+Documentation=https://github.com/Consiliency/message-board
+BindsTo=agent-board-keyslot@%i.service
+After=agent-board-keyslot@%i.service
+
+[Service]
+Type=oneshot
+RemainAfterExit=yes
+# Informational only: keyslot-load.sh sets its own socket from XDG_RUNTIME_DIR and %i,
+# because the manager exports an ambient SSH_AUTH_SOCK (M7).
+Environment=SSH_AUTH_SOCK=%t/agent-board/%i.sock
+ExecStart=%h/.local/libexec/agent-board/slot-%i/keyslot-load.sh %i
+
+[Install]
+WantedBy=agent-board-keyslot@%i.service

package/keyslot/agent-board-keyslot@.service

@@ -0,0 +1,20 @@
+# Installed to ~/.config/systemd/user/ by scripts/keyslot/provision.sh (IF-0-KEYSEAL-2).
+# Its directive set is dev0's hand-installed unit (M7), so an existing hand install is
+# adopted by directive-set equality rather than rewritten.
+[Unit]
+Description=Message Board key slot for %i (dedicated, non-forwarded ssh-agent; starts empty)
+Documentation=https://github.com/Consiliency/message-board
+
+[Service]
+Type=simple
+UMask=0077
+# Shared parent dir is created, never removed: RuntimeDirectory= would be deleted
+# when ANY instance stops, pulling the sockets out from under the other instances.
+ExecStartPre=/bin/mkdir -p -m 0700 %t/agent-board
+ExecStartPre=/bin/rm -f %t/agent-board/%i.sock
+ExecStart=/usr/bin/ssh-agent -D -a %t/agent-board/%i.sock
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=default.target

package/keyslot/constants.sh

@@ -0,0 +1,73 @@
+# shellcheck shell=bash
+# KEYSEAL constants (IF-0-KEYSEAL-1/-2). Sourced by keyslot-load.sh and by every
+# scripts/keyslot tool; a value here is never restated anywhere else.
+
+# The slot name: IF-0-KEYSEAL-1.
+# shellcheck disable=SC2034
+KEYSEAL_SLOT_RE='^[a-z][a-z0-9-]{0,31}$'
+
+# Unit template names, without "@.service".
+# shellcheck disable=SC2034
+KEYSEAL_BASE_UNIT=agent-board-keyslot
+# shellcheck disable=SC2034
+KEYSEAL_LOAD_UNIT=agent-board-keyslot-load
+
+# The installed copies of the loader and its siblings, relative to $HOME, at 0755 (A1). Each
+# version lives in an immutable directory v-<first 16 hex of the set sha256>; slot <s> runs
+# the version its symlink slot-<s> points at, recorded in <s>.loader-sha256 beside the slot.
+# shellcheck disable=SC2034
+KEYSEAL_LIBEXEC_REL=.local/libexec/agent-board
+# Sorted by name: a version's sha is over its files in name order (keyseal_files_sha).
+# shellcheck disable=SC2034
+KEYSEAL_INSTALL_SET=(constants.sh keyslot-load.sh optin.sh seam.sh)
+# shellcheck disable=SC2034
+KEYSEAL_VERSION_PREFIX=v-
+# shellcheck disable=SC2034
+KEYSEAL_SLOT_LINK_PREFIX=slot-
+# shellcheck disable=SC2034
+KEYSEAL_VERSION_HEX=16
+
+# The loader's binaries, by absolute path: no PATH assumption. Each has a seam override
+# named KEYSEAL_TEST_<NAME> (seam.sh), honoured only under KEYSEAL_TEST_ROOT.
+# shellcheck disable=SC2034
+KEYSEAL_BIN_SYSTEMD_CREDS=/usr/bin/systemd-creds
+# shellcheck disable=SC2034
+KEYSEAL_BIN_SSH_ADD=/usr/bin/ssh-add
+# shellcheck disable=SC2034
+KEYSEAL_BIN_SLEEP=/usr/bin/sleep
+# shellcheck disable=SC2034
+KEYSEAL_LOADER_BINS=("$KEYSEAL_BIN_SYSTEMD_CREDS" "$KEYSEAL_BIN_SSH_ADD" "$KEYSEAL_BIN_SLEEP")
+# The unsealed branch's checks (optin.sh), by absolute path too: coreutils and ssh-keygen.
+# shellcheck disable=SC2034
+KEYSEAL_BIN_STAT=/usr/bin/stat
+# shellcheck disable=SC2034
+KEYSEAL_BIN_SHA256SUM=/usr/bin/sha256sum
+# shellcheck disable=SC2034
+KEYSEAL_BIN_ID=/usr/bin/id
+# shellcheck disable=SC2034
+KEYSEAL_BIN_BASE64=/usr/bin/base64
+# shellcheck disable=SC2034
+KEYSEAL_BIN_TAIL=/usr/bin/tail
+# shellcheck disable=SC2034
+KEYSEAL_BIN_SSH_KEYGEN=/usr/bin/ssh-keygen
+# The host identity an opt-in binds to (sha256 of it, first 16 hex). Seam override
+# KEYSEAL_TEST_MACHINE_ID_FILE, under KEYSEAL_TEST_ROOT only.
+# shellcheck disable=SC2034
+KEYSEAL_MACHINE_ID_FILE=/etc/machine-id
+
+# How long the loader waits for the slot socket: 50 x 0.1 s = 5 s.
+# shellcheck disable=SC2034
+KEYSEAL_SOCK_WAIT_STEPS=50
+
+# The sealed credential's name for slot $1.
+keyseal_cred_name() { printf 'agent-board-key-%s' "$1"; }
+
+# The slot agent's socket for slot $1.
+keyseal_sock_path() { printf '%s/agent-board/%s.sock' "$XDG_RUNTIME_DIR" "$1"; }
+
+# K: the slot directory. XDG_CONFIG_HOME if set, else $HOME/.config, which is what the user
+# manager resolves when (as on dev0) it exports HOME but no XDG_CONFIG_HOME.
+keyseal_key_dir() { printf '%s/agent-board/keyslot' "${XDG_CONFIG_HOME:-$HOME/.config}"; }
+
+# The unsealed key of slot $1 (A1): a 0600 file, written only on the opt-in path.
+keyseal_unsealed_key_path() { printf '%s/%s.key' "$(keyseal_key_dir)" "$1"; }

package/keyslot/keygen.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// keygen.mjs --pub-out <path>: generate one Ed25519 key in memory (IF-0-KEYSEAL-1 step 4).
+//
+// The private key goes to STDOUT ONLY, which provision.sh pipes straight into
+// `systemd-creds --user encrypt`. It is an OpenSSH `openssh-key-v1` container with cipher
+// none, not PKCS#8: OpenSSH 9.6p1 (Ubuntu 24.04) rejects an Ed25519 PKCS#8 PEM with
+// `invalid format`, in `ssh-add -` and `ssh-keygen -y` alike, while every OpenSSH since 6.5
+// reads this container. Node exports no OpenSSH private format, so it is written here, per
+// PROTOCOL.key. The one filesystem write is the raw public key, as 43-char
+// base64url, to --pub-out (created 0600, never overwritten). A static test pins that this is
+// the only write and that nothing but node:crypto and node:fs is imported (KS-S1).
+//
+// KEYSEAL_TEST_FAIL_AT=keygen, honoured only under KEYSEAL_TEST_ROOT and only in the `fail`
+// mode, exits 1 AFTER the full PEM and the pub are written (KS-4): the pipefail pin.
+
+import { generateKeyPairSync, randomBytes } from "node:crypto";
+import { writeFileSync } from "node:fs";
+
+const at = process.argv.indexOf("--pub-out");
+const pubOut = at > 0 ? process.argv[at + 1] : undefined;
+if (!pubOut || process.argv.length !== 4) {
+  process.stderr.write("usage: keygen.mjs --pub-out <path>\n");
+  process.exit(1);
+}
+
+const { privateKey } = generateKeyPairSync("ed25519");
+const jwk = privateKey.export({ format: "jwk" });
+writeFileSync(pubOut, `${jwk.x}\n`, { mode: 0o600, flag: "wx" });
+
+function sshString(b) {
+  const buf = Buffer.isBuffer(b) ? b : Buffer.from(b);
+  const len = Buffer.alloc(4);
+  len.writeUInt32BE(buf.length);
+  return Buffer.concat([len, buf]);
+}
+
+function opensshPem() {
+  const pub = Buffer.from(jwk.x, "base64url");
+  const seed = Buffer.from(jwk.d, "base64url");
+  const nkeys = Buffer.alloc(4);
+  nkeys.writeUInt32BE(1);
+  const check = randomBytes(4);
+  const wire = Buffer.concat([sshString("ssh-ed25519"), sshString(pub)]);
+  let priv = Buffer.concat([check, check, wire, sshString(Buffer.concat([seed, pub])), sshString("")]);
+  const pad = [];
+  for (let i = 1; (priv.length + pad.length) % 8 !== 0; i++) pad.push(i);
+  priv = Buffer.concat([priv, Buffer.from(pad)]);
+  const body = Buffer.concat([
+    Buffer.from("openssh-key-v1\0"),
+    sshString("none"),
+    sshString("none"),
+    sshString(""),
+    nkeys,
+    sshString(wire),
+    sshString(priv),
+  ]);
+  const b64 = body.toString("base64").match(/.{1,70}/g).join("\n");
+  return `-----BEGIN OPENSSH PRIVATE KEY-----\n${b64}\n-----END OPENSSH PRIVATE KEY-----\n`;
+}
+
+const failHere =
+  Boolean(process.env.KEYSEAL_TEST_ROOT) &&
+  process.env.KEYSEAL_TEST_FAIL_AT === "keygen" &&
+  (process.env.KEYSEAL_TEST_FAIL_MODE ?? "fail") === "fail";
+process.stdout.write(opensshPem(), () => {
+  process.exit(failHere ? 1 : 0);
+});

package/keyslot/keyslot-load.sh

@@ -0,0 +1,78 @@
+#!/bin/bash
+# keyslot-load.sh <slot>: load the key of <slot> into its slot agent.
+#
+# Run by agent-board-keyslot-load@<slot>.service from ~/.local/libexec/agent-board/slot-<slot>/,
+# a symlink to the immutable version directory that slot runs (A1), so it sources its siblings
+# by its own directory and works with the checkout gone. One loader, two modes:
+#   sealed    <slot>.cred: decrypted into a pipe to ssh-add; it never exists as a file
+#             (IF-0-KEYSEAL-2).
+#   unsealed  <slot>.key (A1, opt-in only): streamed into ssh-add ONLY when optin.sh's
+#             predicate holds, the same one status.sh uses: a valid opt-in for this machine,
+#             user, slot and pin; the key 0600 and this user's; its public key the pin. The
+#             loader runs at every boot and status does not, so the refusal lives here. This
+#             branch never resolves systemd-creds, so it runs on a host that has none.
+# Both present is a contradiction, refused.
+set -euo pipefail
+
+if [[ ${BASH_SOURCE[0]} == */* ]]; then here=${BASH_SOURCE[0]%/*}; else here=.; fi
+. "$here/constants.sh"
+. "$here/seam.sh"
+. "$here/optin.sh"
+
+slot=${1-}
+if [[ ! $slot =~ $KEYSEAL_SLOT_RE ]]; then
+  echo "keyslot-load: bad_slot" >&2
+  exit 1
+fi
+: "${XDG_RUNTIME_DIR:?keyslot-load: XDG_RUNTIME_DIR unset}"
+: "${HOME:?keyslot-load: HOME unset}"
+
+ssh_add=$(seam_resolve KEYSEAL_TEST_SSH_ADD "$KEYSEAL_BIN_SSH_ADD")
+sleep=$(seam_resolve KEYSEAL_TEST_SLEEP "$KEYSEAL_BIN_SLEEP")
+
+# Set, never inherited: the manager exports an ambient SSH_AUTH_SOCK (M7), and the unit's
+# Environment= is only as good as the unit file.
+SSH_AUTH_SOCK=$(keyseal_sock_path "$slot")
+export SSH_AUTH_SOCK
+
+for ((i = 0; i < KEYSEAL_SOCK_WAIT_STEPS; i++)); do
+  [[ -S $SSH_AUTH_SOCK ]] && break
+  "$sleep" 0.1
+done
+if [[ ! -S $SSH_AUTH_SOCK ]]; then
+  echo "keyslot-load: socket_absent" >&2
+  exit 1
+fi
+
+cred=$(keyseal_key_dir)/$slot.cred
+key=$(keyseal_unsealed_key_path "$slot")
+if [[ -e $key || -L $key ]]; then
+  if [[ -e $cred || -L $cred ]]; then
+    echo "keyslot-load: slot_contradiction (both $slot.cred and $slot.key)" >&2
+    exit 1
+  fi
+  mid_file=$(seam_resolve KEYSEAL_TEST_MACHINE_ID_FILE "$KEYSEAL_MACHINE_ID_FILE")
+  mid=$(keyseal_machine_id_of "$mid_file") || mid=unreadable
+  # On success the predicate prints the pin it verified: that is the value compared below.
+  if ! pin=$(keyseal_unsealed_verify "$slot" "$("$KEYSEAL_BIN_ID" -u)" "$mid"); then
+    printf 'keyslot-load: unsealed_key_refused: %s\n' "${pin//$'\n'/; }" >&2
+    exit 1
+  fi
+  seam_pause verified "$sleep" || exit 1
+  # ssh-add is fed the descriptor that is checked here, never a re-open of the path: open it
+  # under principle 4, derive its public key through it, compare with the pin, load from it.
+  keyseal_trusted_open "$key" 65536 >&2 || { echo "keyslot-load: unsealed_key_refused" >&2; exit 1; }
+  kp=$(keyseal_fd_pub "$KEYSEAL_FD" "$slot.key") || kp=
+  if [[ -z $pin || $kp != "$pin" ]]; then
+    echo "keyslot-load: unsealed_key_refused: the opened key is not the pin" >&2
+    exit 1
+  fi
+  seam_pause opened "$sleep" || exit 1
+  SSH_AUTH_SOCK=$SSH_AUTH_SOCK "$ssh_add" - <&"$KEYSEAL_FD"
+  exit
+fi
+
+creds=$(seam_resolve KEYSEAL_TEST_SYSTEMD_CREDS "$KEYSEAL_BIN_SYSTEMD_CREDS")
+# pipefail: a decrypt that fails after printing still fails the load.
+"$creds" --user decrypt --name="$(keyseal_cred_name "$slot")" "$cred" - \
+  | "$ssh_add" -