ashlr-plugin 1.36.4

package/servers/_genome-commits.ts

@@ -0,0 +1,172 @@
+/**
+ * _genome-commits.ts — surface commit sections in ashlr__grep retrieval.
+ *
+ * Loads commit sections from the v2 manifest, scores them against a query
+ * with the same lightweight keyword scorer the static-section retriever
+ * uses (tags > title > summary, IDF-ish boost), and returns a small
+ * sorted slice for the grep handler to prepend to its output.
+ *
+ * Commit sections are ADDITIVE — they extend the corpus, never replace it.
+ * The grep handler formats them with a distinct `[commit <sha> - <date>]`
+ * prefix so users can tell history from static code.
+ */
+
+import { readFile } from "fs/promises";
+import { existsSync } from "fs";
+import { join } from "path";
+import {
+  type CommitSection,
+  type GenomeManifestV2,
+  type SectionMetaV2,
+  loadManifestV2,
+  commitSectionAbsPath,
+} from "./_manifest-v2";
+import { formatFreshness } from "./_genome-freshness";
+
+// ---------------------------------------------------------------------------
+// Tokenization + scoring (mirrors core-efficiency/genome/retriever.ts)
+// ---------------------------------------------------------------------------
+
+export function tokenize(text: string): string[] {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, " ")
+    .split(/\s+/)
+    .filter((t) => t.length > 2);
+}
+
+export function scoreSectionMeta(meta: SectionMetaV2, queryTerms: Set<string>): number {
+  let score = 0;
+  const tagSet = new Set(meta.tags.map((t) => t.toLowerCase()));
+  const titleTerms = new Set(tokenize(meta.title));
+  const summaryTerms = new Set(tokenize(meta.summary));
+  for (const term of queryTerms) {
+    if (tagSet.has(term)) score += 3;
+    if (titleTerms.has(term)) score += 2;
+    if (summaryTerms.has(term)) score += 1;
+  }
+  return score;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface RetrievedCommit {
+  sha: string;
+  shortSha: string;
+  date: string;
+  message: string;
+  summary: string;
+  filesChanged: string[];
+  score: number;
+  /**
+   * v2 freshness — ISO timestamp of the manifest section's last refresh.
+   * Optional so legacy callers (and v1 manifests not yet re-saved) keep
+   * working without rendering a badge.
+   */
+  lastUpdatedAt?: string;
+}
+
+/**
+ * Retrieve up to `limit` commit sections matching `query`.
+ *
+ * Returns an empty array when:
+ *   - no genome exists,
+ *   - the manifest is v1-only (no commit sections recorded),
+ *   - no commit section's keywords overlap the query.
+ *
+ * Never throws — best-effort retrieval, callers should fall through to
+ * static-section results when this returns [].
+ */
+export async function retrieveCommitSections(
+  cwd: string,
+  query: string,
+  limit = 3,
+): Promise<RetrievedCommit[]> {
+  try {
+    const manifest = await loadManifestV2(cwd);
+    if (!manifest) return [];
+
+    const commitMetas = manifest.sections.filter((s) => s.kind === "commit");
+    if (commitMetas.length === 0) return [];
+
+    const queryTerms = new Set(tokenize(query));
+    let scored: Array<{ meta: SectionMetaV2; score: number }>;
+
+    if (queryTerms.size === 0) {
+      // No meaningful query — surface the most recent commits.
+      scored = commitMetas.map((m) => ({ meta: m, score: 1 }));
+    } else {
+      scored = commitMetas
+        .map((m) => ({ meta: m, score: scoreSectionMeta(m, queryTerms) }))
+        .filter((s) => s.score > 0);
+    }
+
+    if (scored.length === 0) return [];
+
+    // Sort by score desc, then date desc (most recent wins ties).
+    scored.sort((a, b) => {
+      if (b.score !== a.score) return b.score - a.score;
+      const ad = a.meta.lastUpdatedAt ?? a.meta.updatedAt;
+      const bd = b.meta.lastUpdatedAt ?? b.meta.updatedAt;
+      return bd > ad ? 1 : bd < ad ? -1 : 0;
+    });
+
+    const out: RetrievedCommit[] = [];
+    for (const { meta, score } of scored.slice(0, limit)) {
+      const sha = meta.path.replace(/^commits\//, "").replace(/\.json$/, "");
+      const abs = commitSectionAbsPath(cwd, sha);
+      if (!existsSync(abs)) continue;
+      let payload: CommitSection;
+      try {
+        payload = JSON.parse(await readFile(abs, "utf-8")) as CommitSection;
+      } catch {
+        continue;
+      }
+      out.push({
+        sha: payload.sha,
+        shortSha: payload.sha.slice(0, 7),
+        date: payload.date,
+        message: payload.message,
+        summary: payload.summary,
+        filesChanged: payload.filesChanged,
+        score,
+        // Surface the section's manifest-level freshness so callers can
+        // render a [fresh|stale: Xd] badge on the commit header.
+        lastUpdatedAt: meta.lastUpdatedAt ?? meta.updatedAt,
+      });
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Format a list of retrieved commit sections as a markdown block suitable for
+ * prepending to grep output. Each commit is clearly labeled with
+ * `[commit <sha> - <date>]` so the user knows it's history, not static code.
+ */
+export function formatCommitsForPrompt(
+  commits: RetrievedCommit[],
+  now: Date = new Date(),
+): string {
+  if (commits.length === 0) return "";
+  const parts = commits.map((c) => {
+    const dateShort = c.date ? c.date.slice(0, 10) : "unknown";
+    const files =
+      c.filesChanged.length === 0
+        ? ""
+        : `\n_files: ${c.filesChanged.slice(0, 6).join(", ")}${c.filesChanged.length > 6 ? ` (+${c.filesChanged.length - 6})` : ""}_\n`;
+    const subject = c.message.split("\n")[0] ?? c.shortSha;
+    // Q2 prep — emit a freshness badge inside the bracketed header so the
+    // model + user can see at a glance whether the retrieved commit is
+    // current. Falls back to no badge when lastUpdatedAt is absent (legacy).
+    const badge = formatFreshness(c.lastUpdatedAt, now);
+    const badgeFragment = badge ? ` \u00b7 ${badge.slice(1, -1)}` : "";
+    return `### [commit ${c.shortSha} - ${dateShort}${badgeFragment}] ${subject}${files}
+${c.summary}`;
+  });
+  return `## Commit History\n\n${parts.join("\n\n---\n\n")}`;
+}

package/servers/_genome-crypto-v2.ts

@@ -0,0 +1,242 @@
+/**
+ * _genome-crypto-v2.ts — client-side v2 envelope encryption for team genomes.
+ *
+ * The server (Phase T1) stores opaque wrapped-DEK envelopes keyed by
+ * `(genome_id, member_user_id)`. This module implements the crypto that
+ * the CLIENT does on either side of that store:
+ *
+ *   - Admin: wraps the team DEK for each recipient's X25519 pubkey once,
+ *            then uploads the envelope via POST /genome/:id/key-envelope.
+ *   - Member: fetches their envelope via GET /genome/:id/key-envelope,
+ *             unwraps with their own X25519 privkey, uses the DEK to
+ *             decrypt genome section content via the existing v1 AES-GCM
+ *             content-encryption path.
+ *
+ * Construction:
+ *   1. Generate ephemeral X25519 keypair.
+ *   2. ECDH with recipient pubkey → shared secret (32 bytes).
+ *   3. HKDF-SHA256(secret, salt=empty, info="ashlr.genome.v2") → 32-byte AES key.
+ *   4. AES-256-GCM(key, nonce=12B random, aad="ashlr.genome.v2") wraps the DEK.
+ *   5. Envelope layout (base64url, concatenated):
+ *        [ 1 byte version=0x01 ]
+ *        [ 32 byte ephemeral-public ]
+ *        [ 12 byte nonce ]
+ *        [ N byte ciphertext ]
+ *        [ 16 byte auth tag ]
+ *
+ * Why ephemeral: forward secrecy per envelope (compromising the recipient's
+ * private key later does not let an attacker decrypt a captured envelope
+ * unless they also captured the ephemeral private at wrap time, which we
+ * discard).
+ *
+ * Why HKDF(info="ashlr.genome.v2"): domain separation from any future v3.
+ */
+
+import {
+  createCipheriv,
+  createDecipheriv,
+  createPrivateKey,
+  createPublicKey,
+  diffieHellman,
+  generateKeyPairSync,
+  hkdfSync,
+  randomBytes,
+} from "crypto";
+
+const VERSION = 0x01;
+const HKDF_INFO = Buffer.from("ashlr.genome.v2", "utf-8");
+const AEAD_AAD = Buffer.from("ashlr.genome.v2", "utf-8");
+const AEAD_NONCE_LEN = 12;
+const AEAD_TAG_LEN = 16;
+
+// ---------------------------------------------------------------------------
+// base64url helpers — Node 20+ has native support via Buffer.toString("base64url").
+// ---------------------------------------------------------------------------
+
+function b64url(b: Buffer): string { return b.toString("base64url"); }
+function fromB64url(s: string): Buffer { return Buffer.from(s, "base64url"); }
+
+// ---------------------------------------------------------------------------
+// X25519 keypair generation
+// ---------------------------------------------------------------------------
+
+export interface KeyPair {
+  /** Raw 32-byte X25519 public key, base64url-encoded. */
+  publicKey: string;
+  /** Raw 32-byte X25519 private key, base64url-encoded. Keep offline. */
+  privateKey: string;
+}
+
+/**
+ * Generate an X25519 keypair. Keys are returned as 32-byte raw values in
+ * base64url. Both sides of the wire use the same encoding.
+ */
+export function generateKeyPair(): KeyPair {
+  const { publicKey, privateKey } = generateKeyPairSync("x25519");
+  // Node's key objects are DER-wrapped by default; we want raw 32-byte values.
+  const pubDer = publicKey.export({ format: "der", type: "spki" });
+  const privDer = privateKey.export({ format: "der", type: "pkcs8" });
+  return {
+    // The last 32 bytes of an X25519 SPKI DER blob are the raw public key.
+    publicKey:  b64url(pubDer.subarray(pubDer.length - 32)),
+    // The last 32 bytes of an X25519 PKCS8 DER blob are the raw private key.
+    privateKey: b64url(privDer.subarray(privDer.length - 32)),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Raw-key → Node KeyObject helpers
+// ---------------------------------------------------------------------------
+
+// RFC 8410 DER prefix for an X25519 public key SPKI: 12 bytes, followed by the
+// 32-byte raw public key. Hand-rolled because Node's API wants the full SPKI.
+const X25519_PUB_SPKI_PREFIX = Buffer.from([
+  0x30, 0x2a, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x6e, 0x03, 0x21, 0x00,
+]);
+
+// RFC 8410 DER prefix for an X25519 private key PKCS8: 16 bytes, followed by
+// a 2-byte OCTET STRING header + 32-byte raw private key.
+const X25519_PRIV_PKCS8_PREFIX = Buffer.from([
+  0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x6e,
+  0x04, 0x22, 0x04, 0x20,
+]);
+
+function rawToPubKeyObject(raw32: Buffer) {
+  if (raw32.length !== 32) throw new Error("X25519 pubkey must be 32 bytes");
+  return createPublicKey({
+    key: Buffer.concat([X25519_PUB_SPKI_PREFIX, raw32]),
+    format: "der",
+    type: "spki",
+  });
+}
+
+function rawToPrivKeyObject(raw32: Buffer) {
+  if (raw32.length !== 32) throw new Error("X25519 privkey must be 32 bytes");
+  return createPrivateKey({
+    key: Buffer.concat([X25519_PRIV_PKCS8_PREFIX, raw32]),
+    format: "der",
+    type: "pkcs8",
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Wrap / Unwrap
+// ---------------------------------------------------------------------------
+
+export const ENVELOPE_ALG = "x25519-hkdf-sha256-aes256gcm-v1";
+
+/**
+ * Wrap a 32-byte DEK for a recipient whose raw X25519 pubkey we have.
+ * Returns a base64url-encoded envelope string.
+ */
+export function wrapDek(dek: Buffer, recipientPubB64url: string): string {
+  if (dek.length !== 32) throw new Error("DEK must be 32 bytes");
+
+  const recipientPubRaw = fromB64url(recipientPubB64url);
+  if (recipientPubRaw.length !== 32) {
+    throw new Error("recipient pubkey must decode to 32 bytes");
+  }
+  const recipientPub = rawToPubKeyObject(recipientPubRaw);
+
+  // Ephemeral keypair → ECDH → HKDF → AES key.
+  const eph = generateKeyPairSync("x25519");
+  const ephPubRaw = eph.publicKey
+    .export({ format: "der", type: "spki" })
+    .subarray(-32);
+
+  const shared = diffieHellman({ privateKey: eph.privateKey, publicKey: recipientPub });
+  const aesKey = Buffer.from(hkdfSync("sha256", shared, Buffer.alloc(0), HKDF_INFO, 32));
+
+  const nonce = randomBytes(AEAD_NONCE_LEN);
+  const cipher = createCipheriv("aes-256-gcm", aesKey, nonce);
+  cipher.setAAD(AEAD_AAD);
+  const ct = Buffer.concat([cipher.update(dek), cipher.final()]);
+  const tag = cipher.getAuthTag();
+
+  const envelope = Buffer.concat([
+    Buffer.from([VERSION]),
+    ephPubRaw,
+    nonce,
+    ct,
+    tag,
+  ]);
+  return b64url(envelope);
+}
+
+/**
+ * Unwrap an envelope produced by wrapDek. Throws on version mismatch, length
+ * mismatch, or AEAD tag mismatch (including wrong recipient privkey).
+ */
+export function unwrapDek(envelopeB64url: string, recipientPrivB64url: string): Buffer {
+  const envelope = fromB64url(envelopeB64url);
+  // 1 version + 32 eph-pub + 12 nonce + 16 tag = 61 min; plus ciphertext (= DEK size).
+  if (envelope.length < 1 + 32 + AEAD_NONCE_LEN + AEAD_TAG_LEN) {
+    throw new Error("envelope too short");
+  }
+  if (envelope[0] !== VERSION) {
+    throw new Error(`unsupported envelope version ${envelope[0]}`);
+  }
+  const ephPubRaw  = envelope.subarray(1, 33);
+  const nonce      = envelope.subarray(33, 33 + AEAD_NONCE_LEN);
+  const ct         = envelope.subarray(33 + AEAD_NONCE_LEN, envelope.length - AEAD_TAG_LEN);
+  const tag        = envelope.subarray(envelope.length - AEAD_TAG_LEN);
+
+  const recipientPrivRaw = fromB64url(recipientPrivB64url);
+  if (recipientPrivRaw.length !== 32) {
+    throw new Error("recipient privkey must decode to 32 bytes");
+  }
+  const recipientPriv = rawToPrivKeyObject(recipientPrivRaw);
+  const ephPub = rawToPubKeyObject(ephPubRaw);
+
+  const shared = diffieHellman({ privateKey: recipientPriv, publicKey: ephPub });
+  const aesKey = Buffer.from(hkdfSync("sha256", shared, Buffer.alloc(0), HKDF_INFO, 32));
+
+  const decipher = createDecipheriv("aes-256-gcm", aesKey, nonce);
+  decipher.setAAD(AEAD_AAD);
+  decipher.setAuthTag(tag);
+  const pt = Buffer.concat([decipher.update(ct), decipher.final()]);
+  if (pt.length !== 32) throw new Error("unwrapped DEK has wrong length");
+  return pt;
+}
+
+// ---------------------------------------------------------------------------
+// Local key storage — ~/.ashlr/member-keys/<userId>.json
+// ---------------------------------------------------------------------------
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+
+export function memberKeyPath(userId: string): string {
+  return join(process.env.HOME ?? homedir(), ".ashlr", "member-keys", `${userId}.json`);
+}
+
+export interface StoredKeypair {
+  userId:     string;
+  publicKey:  string;
+  privateKey: string;
+  alg:        string;  // "x25519-v1"
+  createdAt:  string;  // ISO
+}
+
+/**
+ * Persist a keypair to disk. File mode 0600 because it contains the private
+ * key. Directory created lazily with mode 0700.
+ */
+export function saveKeypair(kp: StoredKeypair): string {
+  const path = memberKeyPath(kp.userId);
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  writeFileSync(path, JSON.stringify(kp, null, 2), { encoding: "utf-8", mode: 0o600 });
+  try { chmodSync(path, 0o600); } catch { /* best-effort on fs that doesn't support it */ }
+  return path;
+}
+
+export function loadKeypair(userId: string): StoredKeypair | null {
+  const path = memberKeyPath(userId);
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as StoredKeypair;
+  } catch {
+    return null;
+  }
+}

package/servers/_genome-crypto.ts

@@ -0,0 +1,259 @@
+/**
+ * _genome-crypto.ts — Client-side AES-256-GCM encryption for team genome sections.
+ *
+ * Threat model:
+ *   - Server operator cannot read section content without the team key.
+ *   - Compromised Redis / S3 / Postgres exposes only ciphertext + nonce + auth tag.
+ *   - TLS protects the transport layer; encryption here provides defence-in-depth.
+ *   - A user who leaves the team loses access to new content after a key rotation.
+ *
+ * v1 model: one symmetric AES-256-GCM key per genome, stored at
+ *   ~/.ashlr/team-keys/<genomeId>.key  (mode 0600, 32 raw bytes)
+ *
+ * Wire format (serializeBlob):
+ *   base64url(<version_byte> : <12-byte nonce> : <16-byte authTag> : <ciphertext>)
+ *   The version prefix allows future algorithm migration without breaking parsers.
+ *
+ * Multi-user model (v2, not shipped):
+ *   Each member holds an X25519 keypair. The team key is wrapped per member:
+ *     envelope[memberId] = encrypt(memberPublicKey, teamKey)
+ *   Admin manages envelopes. Member rotation = re-wrap envelope (no re-encrypt needed).
+ *   Full protocol documented in docs/team-genome.md.
+ *
+ * SECURITY: This module NEVER logs key material, plaintext content, or nonces.
+ */
+
+import { createCipheriv, createDecipheriv, randomBytes } from "crypto";
+import { readFile, writeFile, mkdir, chmod } from "fs/promises";
+import { existsSync } from "fs";
+import { join, dirname } from "path";
+import { homedir } from "os";
+
+// Emit a per-file warning on Windows since POSIX chmod has no effect on NTFS.
+// Note: Node/Bun's `writeFile(..., { mode: 0o600 })` silently ignores `mode`
+// on Windows, so the file lands with whatever ACLs NTFS inherits from the
+// parent directory. For `~/.ashlr/team-keys/` under the user profile, default
+// ACLs typically restrict to the user + Administrators + SYSTEM — but that
+// depends on parent-directory state (roaming profiles, domain policies, or
+// user-created dirs may have broader ACLs). We warn per-key-file so a user
+// rotating keys sees the reminder each time; don't throw because the file
+// is written and functional.
+//
+// The user should protect `~/.ashlr/team-keys/` via BitLocker, Windows EFS,
+// or explicit `icacls` ACLs. Document this in docs/platform-support.md.
+function warnWindowsChmod(p: string): void {
+  process.stderr.write(
+    `[ashlr-genome-crypto] WARNING: Windows — chmod 0600 is a no-op on NTFS. ` +
+    `Key file at ${p} inherits parent-directory ACLs (typically user-only in ` +
+    `~/.ashlr/ but not guaranteed). Protect with BitLocker or EFS.\n`,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const KEY_BYTES    = 32;          // AES-256
+const NONCE_BYTES  = 12;          // GCM recommended nonce size
+const AUTH_TAG_BYTES = 16;        // GCM authentication tag (128-bit)
+const BLOB_VERSION = 1;
+
+// Regex that matches our serialized blob format (base64url)
+// Used by the server to detect encrypted vs plaintext content.
+export const ENCRYPTED_BLOB_RE = /^[A-Za-z0-9_-]{20,}$/;
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface EncryptedBlob {
+  version:    number;
+  nonce:      Buffer;
+  authTag:    Buffer;
+  ciphertext: Buffer;
+}
+
+// ---------------------------------------------------------------------------
+// Key generation
+// ---------------------------------------------------------------------------
+
+/** Generate a new 32-byte AES-256 team key. */
+export function generateKey(): Buffer {
+  return randomBytes(KEY_BYTES);
+}
+
+// ---------------------------------------------------------------------------
+// Encrypt / Decrypt
+// ---------------------------------------------------------------------------
+
+/**
+ * Encrypt a plaintext section with AES-256-GCM.
+ * Each call uses a fresh random nonce — never reuse a nonce with the same key.
+ */
+export function encryptSection(plaintext: string, key: Buffer): EncryptedBlob {
+  if (key.length !== KEY_BYTES) {
+    throw new Error(`[ashlr-genome-crypto] Key must be ${KEY_BYTES} bytes`);
+  }
+  const nonce  = randomBytes(NONCE_BYTES);
+  const cipher = createCipheriv("aes-256-gcm", key, nonce);
+  const ct     = Buffer.concat([cipher.update(plaintext, "utf-8"), cipher.final()]);
+  const authTag = cipher.getAuthTag();
+  return { version: BLOB_VERSION, nonce, authTag, ciphertext: ct };
+}
+
+/**
+ * Decrypt a section blob.
+ * Throws if the auth tag does not match (tampered data or wrong key).
+ * Throws on version mismatch.
+ */
+export function decryptSection(blob: EncryptedBlob, key: Buffer): string {
+  if (key.length !== KEY_BYTES) {
+    throw new Error(`[ashlr-genome-crypto] Key must be ${KEY_BYTES} bytes`);
+  }
+  if (blob.version !== BLOB_VERSION) {
+    throw new Error(`[ashlr-genome-crypto] Unknown blob version: ${blob.version}`);
+  }
+  const decipher = createDecipheriv("aes-256-gcm", key, blob.nonce);
+  decipher.setAuthTag(blob.authTag);
+  try {
+    const plain = Buffer.concat([decipher.update(blob.ciphertext), decipher.final()]);
+    return plain.toString("utf-8");
+  } catch {
+    // Node throws "Unsupported state or unable to authenticate data" on auth tag failure.
+    throw new Error("[ashlr-genome-crypto] Decryption failed — wrong key or corrupt data");
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Serialization
+// ---------------------------------------------------------------------------
+
+/**
+ * Serialize an EncryptedBlob to a compact base64url string.
+ * Layout: [ version(1) | nonce(12) | authTag(16) | ciphertext(variable) ]
+ */
+export function serializeBlob(blob: EncryptedBlob): string {
+  const header = Buffer.alloc(1 + NONCE_BYTES + AUTH_TAG_BYTES);
+  header.writeUInt8(blob.version, 0);
+  blob.nonce.copy(header, 1);
+  blob.authTag.copy(header, 1 + NONCE_BYTES);
+  const full = Buffer.concat([header, blob.ciphertext]);
+  // base64url (no padding, URL-safe)
+  return full.toString("base64url");
+}
+
+/**
+ * Parse a base64url blob string back into an EncryptedBlob.
+ * Throws on malformed input.
+ */
+export function parseBlob(str: string): EncryptedBlob {
+  let buf: Buffer;
+  try {
+    buf = Buffer.from(str, "base64url");
+  } catch {
+    throw new Error("[ashlr-genome-crypto] Invalid blob: base64url decode failed");
+  }
+  const minLen = 1 + NONCE_BYTES + AUTH_TAG_BYTES;
+  if (buf.length < minLen) {
+    throw new Error(`[ashlr-genome-crypto] Invalid blob: too short (${buf.length} bytes)`);
+  }
+  const version  = buf.readUInt8(0);
+  const nonce    = buf.subarray(1, 1 + NONCE_BYTES);
+  const authTag  = buf.subarray(1 + NONCE_BYTES, 1 + NONCE_BYTES + AUTH_TAG_BYTES);
+  const ciphertext = buf.subarray(1 + NONCE_BYTES + AUTH_TAG_BYTES);
+  return {
+    version,
+    nonce:      Buffer.from(nonce),
+    authTag:    Buffer.from(authTag),
+    ciphertext: Buffer.from(ciphertext),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Key file helpers
+// ---------------------------------------------------------------------------
+
+function keyFilePath(genomeId: string): string {
+  return join(homedir(), ".ashlr", "team-keys", `${genomeId}.key`);
+}
+
+/**
+ * Load a team key from ~/.ashlr/team-keys/<genomeId>.key.
+ * Returns null if the file does not exist.
+ * Throws if the file exists but is malformed.
+ */
+export async function loadKey(genomeId: string): Promise<Buffer | null> {
+  const p = keyFilePath(genomeId);
+  if (!existsSync(p)) return null;
+  const raw = await readFile(p);
+  if (raw.length !== KEY_BYTES) {
+    throw new Error(
+      `[ashlr-genome-crypto] Key file at ${p} has wrong length (${raw.length} bytes, expected ${KEY_BYTES})`,
+    );
+  }
+  return Buffer.from(raw);
+}
+
+/**
+ * Save a team key to ~/.ashlr/team-keys/<genomeId>.key with mode 0600.
+ * Creates parent directories as needed.
+ */
+export async function saveKey(genomeId: string, key: Buffer): Promise<void> {
+  if (key.length !== KEY_BYTES) {
+    throw new Error(`[ashlr-genome-crypto] Key must be ${KEY_BYTES} bytes`);
+  }
+  const p = keyFilePath(genomeId);
+  await mkdir(dirname(p), { recursive: true });
+  await writeFile(p, key, { mode: 0o600 });
+  if (process.platform === "win32") {
+    warnWindowsChmod(p);
+  } else {
+    // chmod explicitly in case writeFile mode is masked by umask
+    await chmod(p, 0o600);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Base32 helpers (for human-friendly key export/import)
+// ---------------------------------------------------------------------------
+
+// RFC 4648 base32 alphabet (uppercase, no padding issues with 32-byte keys)
+const BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+
+/** Encode a Buffer as base32 (no padding). */
+export function encodeBase32(buf: Buffer): string {
+  let bits = 0;
+  let value = 0;
+  let output = "";
+  for (const byte of buf) {
+    value = (value << 8) | byte;
+    bits += 8;
+    while (bits >= 5) {
+      output += BASE32_ALPHABET[(value >>> (bits - 5)) & 31];
+      bits -= 5;
+    }
+  }
+  if (bits > 0) {
+    output += BASE32_ALPHABET[(value << (5 - bits)) & 31];
+  }
+  return output;
+}
+
+/** Decode a base32 string to a Buffer. Throws on invalid characters. */
+export function decodeBase32(str: string): Buffer {
+  const s = str.toUpperCase().replace(/\s/g, "");
+  const bytes: number[] = [];
+  let bits = 0;
+  let value = 0;
+  for (const ch of s) {
+    const idx = BASE32_ALPHABET.indexOf(ch);
+    if (idx < 0) throw new Error(`[ashlr-genome-crypto] Invalid base32 character: ${ch}`);
+    value = (value << 5) | idx;
+    bits += 5;
+    if (bits >= 8) {
+      bytes.push((value >>> (bits - 8)) & 255);
+      bits -= 8;
+    }
+  }
+  return Buffer.from(bytes);
+}