@muthuishere/vsync 0.3.0

package/src/backup.ts

@@ -0,0 +1,74 @@
+// Local rolling backup at ~/.config/vsync/backups/<name>-<ts>.zip.enc.
+// Keeps only the 2 most recent backups per name; older ones are pruned.
+//
+// Backups are encrypted with the same key+salt as the S3 bundle so a
+// stolen laptop / cloud-sync leak / Time Machine snapshot does not
+// expose decrypted secrets sitting on disk.
+
+import { existsSync, mkdirSync, readdirSync, statSync, unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { zipPaths } from "./archive";
+import { encrypt } from "./crypto";
+import { vsyncBaseDir } from "./defaults";
+
+export const BACKUP_EXT = ".zip.enc";
+const KEEP = 2;
+
+export function backupDir(): string {
+  const dir = process.env.VSYNC_BACKUP_DIR ?? join(vsyncBaseDir(), "backups");
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+export function timestamp(): string {
+  // YYYYMMDD-HHmmss UTC, e.g. 20260427-104530
+  return new Date().toISOString().slice(0, 19).replace(/[-:]/g, "").replace("T", "-");
+}
+
+// Zip the supplied paths (relative to baseDir), encrypt the zip with the
+// given key+salt, and write the encrypted blob to backupDir() as
+// <name>-<ts>.zip.enc. Returns the path to the encrypted backup, or null
+// if none of the paths existed (nothing to back up).
+export async function makeBackup(
+  name: string,
+  baseDir: string,
+  paths: string[],
+  encryption: { key: string; salt: string },
+): Promise<string | null> {
+  const existing = paths.filter((p) => existsSync(join(baseDir, p)));
+  if (existing.length === 0) return null;
+
+  const dir = backupDir();
+  const ts = timestamp();
+  const tmpZip = join(
+    tmpdir(),
+    `bk-${ts}-${Math.random().toString(36).slice(2)}.zip`,
+  );
+  const outPath = join(dir, `${name.toLowerCase()}-${ts}${BACKUP_EXT}`);
+
+  try {
+    await zipPaths(baseDir, existing, tmpZip);
+    const zipBytes = await Bun.file(tmpZip).bytes();
+    const encrypted = await encrypt(zipBytes, encryption.key, encryption.salt);
+    await Bun.write(outPath, encrypted);
+  } finally {
+    if (existsSync(tmpZip)) unlinkSync(tmpZip);
+  }
+
+  pruneBackups(name);
+  return outPath;
+}
+
+// Delete all but the KEEP most-recent <name>-*.zip.enc files in the backup dir.
+export function pruneBackups(name: string): void {
+  const dir = backupDir();
+  const prefix = `${name.toLowerCase()}-`;
+  const matches = readdirSync(dir)
+    .filter((f) => f.startsWith(prefix) && f.endsWith(BACKUP_EXT))
+    .map((f) => ({ f, mtime: statSync(join(dir, f)).mtimeMs }))
+    .sort((a, b) => b.mtime - a.mtime);
+  for (const { f } of matches.slice(KEEP)) {
+    unlinkSync(join(dir, f));
+  }
+}

package/src/codec.ts

@@ -0,0 +1,21 @@
+// JSON ⇄ gzip+base64 codec.
+// Pure functions, easily unit-testable. CLIs in bin/ are thin wrappers.
+
+export function encodeGzipBase64(json: string): string {
+  // Validate input is JSON before bothering to compress.
+  JSON.parse(json);
+  const gz = Bun.gzipSync(new TextEncoder().encode(json));
+  return Buffer.from(gz).toString("base64");
+}
+
+export function decodeGzipBase64(b64: string): string {
+  const gz = Buffer.from(b64.trim(), "base64");
+  if (gz.byteLength === 0) {
+    throw new Error("decoded base64 is empty");
+  }
+  const raw = Bun.gunzipSync(gz);
+  const json = new TextDecoder().decode(raw);
+  // Validate output is JSON before returning.
+  JSON.parse(json);
+  return json;
+}

package/src/crypto.ts

@@ -0,0 +1,71 @@
+// AES-256-GCM with PBKDF2-SHA256 key derivation from password+salt.
+//
+// Envelope format on disk:
+//   bytes 0..3   — magic "RQE1"
+//   bytes 4..15  — 12-byte IV (random per encryption)
+//   bytes 16..N  — ciphertext (Web Crypto AES-GCM appends a 16-byte auth tag)
+
+const MAGIC = new Uint8Array([0x52, 0x51, 0x45, 0x31]); // "RQE1"
+const IV_LEN = 12;
+const HEADER_LEN = MAGIC.length + IV_LEN; // 16
+const PBKDF2_ITERATIONS = 600_000;
+
+async function deriveKey(password: string, salt: string): Promise<CryptoKey> {
+  const enc = new TextEncoder();
+  const baseKey = await crypto.subtle.importKey(
+    "raw",
+    enc.encode(password),
+    { name: "PBKDF2" },
+    false,
+    ["deriveKey"],
+  );
+  return crypto.subtle.deriveKey(
+    {
+      name: "PBKDF2",
+      salt: enc.encode(salt),
+      iterations: PBKDF2_ITERATIONS,
+      hash: "SHA-256",
+    },
+    baseKey,
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt", "decrypt"],
+  );
+}
+
+export async function encrypt(
+  data: Uint8Array,
+  password: string,
+  salt: string,
+): Promise<Uint8Array> {
+  const key = await deriveKey(password, salt);
+  const iv = crypto.getRandomValues(new Uint8Array(IV_LEN));
+  const ct = new Uint8Array(
+    await crypto.subtle.encrypt({ name: "AES-GCM", iv }, key, data),
+  );
+  const out = new Uint8Array(HEADER_LEN + ct.byteLength);
+  out.set(MAGIC, 0);
+  out.set(iv, MAGIC.length);
+  out.set(ct, HEADER_LEN);
+  return out;
+}
+
+export async function decrypt(
+  blob: Uint8Array,
+  password: string,
+  salt: string,
+): Promise<Uint8Array> {
+  if (blob.byteLength < HEADER_LEN) {
+    throw new Error("envelope too short");
+  }
+  for (let i = 0; i < MAGIC.length; i++) {
+    if (blob[i] !== MAGIC[i]) {
+      throw new Error("invalid magic — not an RQE1 envelope");
+    }
+  }
+  const iv = blob.slice(MAGIC.length, HEADER_LEN);
+  const ct = blob.slice(HEADER_LEN);
+  const key = await deriveKey(password, salt);
+  const pt = await crypto.subtle.decrypt({ name: "AES-GCM", iv }, key, ct);
+  return new Uint8Array(pt);
+}

package/src/defaults.ts

@@ -0,0 +1,91 @@
+// defaults.ts — optional defaults template at ~/.config/vsync/defaults.
+//
+// Read by `vsync init` only — pre-fills prompts on subsequent setups
+// after the first-ever init writes it. Never consulted by push / pull /
+// sync — those resolve everything from the per-repo file (see
+// repoconfig.ts) plus the keychain.
+//
+// Conventions: gzip(JSON), file 0600, parent dir 0700, honours
+// XDG_CONFIG_HOME. Same security envelope as the per-repo file.
+
+import { gunzipSync, gzipSync } from "node:zlib";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as os from "node:os";
+
+export type Defaults = {
+  version: 1;
+  s3?: {
+    endpoint?: string;
+    region?: string;
+    bucket?: string;
+    accessKeyId?: string;
+    secretAccessKey?: string;
+    useSsl?: boolean;
+  };
+};
+
+const ROOT_DIRNAME = "vsync";
+const FILE_NAME = "defaults";
+
+/** Base directory for vsync state. Honours XDG_CONFIG_HOME. */
+export function vsyncBaseDir(): string {
+  const xdg = process.env.XDG_CONFIG_HOME;
+  const base = xdg && xdg.trim() ? xdg : path.join(os.homedir(), ".config");
+  return path.join(base, ROOT_DIRNAME);
+}
+
+/** Path to the defaults template. */
+export function defaultsFilePath(): string {
+  return path.join(vsyncBaseDir(), FILE_NAME);
+}
+
+/** Persist the defaults template (creates the dir tree if needed). */
+export async function saveDefaults(d: Defaults): Promise<string> {
+  validateDefaults(d);
+  const file = defaultsFilePath();
+  const dir = path.dirname(file);
+  await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+  try {
+    await fs.chmod(dir, 0o700);
+  } catch {
+    // Non-fatal; some filesystems don't honour chmod.
+  }
+  const json = JSON.stringify(d);
+  const gz = gzipSync(Buffer.from(json, "utf8"));
+  await fs.writeFile(file, gz, { mode: 0o600 });
+  try {
+    await fs.chmod(file, 0o600);
+  } catch {
+    // Same caveat as above.
+  }
+  return file;
+}
+
+/** Read the defaults template; returns null if absent. Throws on corruption. */
+export async function loadDefaults(): Promise<Defaults | null> {
+  const file = defaultsFilePath();
+  let buf: Buffer;
+  try {
+    buf = await fs.readFile(file);
+  } catch (err: any) {
+    if (err && (err.code === "ENOENT" || err.code === "ENOTDIR")) return null;
+    throw err;
+  }
+  const json = gunzipSync(buf).toString("utf8");
+  const parsed = JSON.parse(json);
+  validateDefaults(parsed);
+  return parsed;
+}
+
+/** Defensive shape check. */
+export function validateDefaults(d: unknown): asserts d is Defaults {
+  const x = d as Partial<Defaults> | null;
+  if (!x || typeof x !== "object") throw new Error("defaults: not an object");
+  if (x.version !== 1) {
+    throw new Error(`defaults: unsupported version ${x.version} (expected 1)`);
+  }
+  if (x.s3 !== undefined && (typeof x.s3 !== "object" || x.s3 === null)) {
+    throw new Error("defaults: s3 field must be an object if present");
+  }
+}

package/src/envconfig.ts

@@ -0,0 +1,179 @@
+// envconfig.ts — the in-memory composite used by push / pull / sync.
+// Glues two on-disk sources together:
+//
+//   1. `~/.config/vsync/<repo>/env_<env>` — self-contained per-(repo, env)
+//      config (S3 creds + salt + paths + sync routing). gzipped JSON,
+//      chmod 0600. See repoconfig.ts.
+//   2. OS keychain (macOS Keychain / Linux libsecret / Windows Credential
+//      Manager) — the AES encryption key. See keychain.ts.
+//
+// `loadEnvConfig(repo, env)` reads both and returns the combined config.
+// Missing file → returns null. Missing key → throws a "key not found"
+// error so push/pull can surface it cleanly.
+//
+// Export/import blob:
+//   `buildExportBlob` zips config+key+metadata into a single string the
+//   user can share with teammates. `parseExportBlob` is the inverse.
+//   Both go through codec.ts for gzip+base64 framing.
+
+import type { S3Credentials } from "./s3";
+import { encodeGzipBase64, decodeGzipBase64 } from "./codec";
+import type { ConfigFile } from "./repoconfig";
+import { loadConfigFile, validateConfigFile } from "./repoconfig";
+import { getKey } from "./keychain";
+
+export const MIN_KEY_LEN = 20;
+export const MIN_SALT_LEN = 16;
+export const EXPORT_BLOB_VERSION = 2;
+
+/**
+ * Runtime composite used by every push / pull / sync code path. Same
+ * shape as ConfigFile, with the keychain key spliced in.
+ */
+export type EnvConfig = {
+  s3: S3Credentials;
+  encryption: { key: string; salt: string };
+  files?: { vaultFolder?: string };
+  sync?: ConfigFile["sync"];
+};
+
+/**
+ * Resolve the effective vault folder for a (repo, env). Defaults to
+ * `infra/vault/<env>` when the per-repo file doesn't override.
+ */
+export function resolveVaultFolder(cfg: EnvConfig | ConfigFile, env: string): string {
+  return cfg.files?.vaultFolder ?? `infra/vault/${env.toLowerCase()}`;
+}
+
+/** Wire shape of the share blob exchanged between teammates. */
+export type ExportPayload = {
+  version: number;
+  repo: string;
+  env: string;
+  config: ConfigFile; // file contents (no key)
+  key: string; // base64-encoded AES key
+};
+
+export class ConfigFileMissingError extends Error {
+  constructor(repo: string, env: string, filePath: string) {
+    super(
+      `no config file for ${repo}/${env} at ${filePath}.\n` +
+        `Run 'vsync init ${env} --repo=${repo}' to create one, or 'vsync import ${env} <share-file>' if a teammate sent you one.`,
+    );
+    this.name = "ConfigFileMissingError";
+  }
+}
+
+export class KeyMissingError extends Error {
+  constructor(repo: string, env: string) {
+    super(
+      `encryption key for ${repo}/${env} not found in OS keychain.\n` +
+        `Run 'vsync import ${env} <share-file>' if a teammate sent you the share file (it carries the key),\n` +
+        `or 'vsync init ${env} --repo=${repo}' to generate a fresh one.`,
+    );
+    this.name = "KeyMissingError";
+  }
+}
+
+/**
+ * Load and assemble the full EnvConfig for a (repo, env). Throws
+ * ConfigFileMissingError if the on-disk file is absent, KeyMissingError
+ * if the file exists but the keychain entry is gone.
+ */
+export async function loadEnvConfig(
+  repo: string,
+  env: string,
+): Promise<EnvConfig> {
+  const { configFilePath } = await import("./repoconfig");
+  const cfg = await loadConfigFile(repo, env);
+  if (!cfg) {
+    throw new ConfigFileMissingError(repo, env, configFilePath(repo, env));
+  }
+  const key = await getKey(repo, env);
+  if (!key) {
+    throw new KeyMissingError(repo, env);
+  }
+  const composite: EnvConfig = {
+    s3: cfg.s3,
+    encryption: { key, salt: cfg.encryption.salt },
+    ...(cfg.files !== undefined ? { files: cfg.files } : {}),
+    ...(cfg.sync !== undefined ? { sync: cfg.sync } : {}),
+  };
+  validate(composite);
+  return composite;
+}
+
+/** Build a share-blob string (the inverse of parseExportBlob). */
+export function buildExportBlob(payload: ExportPayload): string {
+  validateExportPayload(payload);
+  return encodeGzipBase64(JSON.stringify(payload));
+}
+
+/** Parse a share-blob string. Throws on bad gzip / JSON / shape. */
+export function parseExportBlob(blob: string): ExportPayload {
+  const json = decodeGzipBase64(blob.trim());
+  const parsed = JSON.parse(json);
+  validateExportPayload(parsed);
+  return parsed;
+}
+
+/** Validate a runtime composite EnvConfig (key included). */
+export function validate(cfg: unknown): asserts cfg is EnvConfig {
+  const c = cfg as Partial<EnvConfig> | null;
+  const s3 = c?.s3;
+  for (const k of [
+    "endpoint",
+    "region",
+    "accessKeyId",
+    "secretAccessKey",
+    "bucket",
+  ] as const) {
+    if (!s3?.[k]) throw new Error(`s3.${k} missing`);
+  }
+  if (typeof s3?.useSsl !== "boolean") {
+    throw new Error("s3.useSsl missing or not a boolean");
+  }
+  const enc = c?.encryption;
+  for (const k of ["key", "salt"] as const) {
+    if (!enc?.[k]) throw new Error(`encryption.${k} missing`);
+  }
+  if (typeof enc.key !== "string" || enc.key.length < MIN_KEY_LEN) {
+    throw new Error(
+      `encryption.key must be at least ${MIN_KEY_LEN} characters (got ${enc.key?.length ?? 0}).`,
+    );
+  }
+  if (typeof enc.salt !== "string" || enc.salt.length < MIN_SALT_LEN) {
+    throw new Error(
+      `encryption.salt must be at least ${MIN_SALT_LEN} characters (got ${enc.salt?.length ?? 0}).`,
+    );
+  }
+  if (c.files !== undefined) {
+    if (typeof c.files !== "object" || c.files === null) {
+      throw new Error("files must be an object if present");
+    }
+    if (
+      c.files.vaultFolder !== undefined &&
+      typeof c.files.vaultFolder !== "string"
+    ) {
+      throw new Error("files.vaultFolder must be a string if present");
+    }
+  }
+}
+
+function validateExportPayload(p: unknown): asserts p is ExportPayload {
+  const x = p as Partial<ExportPayload> | null;
+  if (!x || typeof x !== "object") throw new Error("export blob is not an object");
+  if (x.version !== EXPORT_BLOB_VERSION) {
+    throw new Error(
+      `unsupported export blob version: ${x.version} (this CLI handles ${EXPORT_BLOB_VERSION})`,
+    );
+  }
+  if (!x.repo || typeof x.repo !== "string") throw new Error("export blob: repo missing");
+  if (!x.env || typeof x.env !== "string") throw new Error("export blob: env missing");
+  if (!x.key || typeof x.key !== "string" || x.key.length < MIN_KEY_LEN) {
+    throw new Error(
+      `export blob: key missing or shorter than ${MIN_KEY_LEN} chars`,
+    );
+  }
+  validateConfigFile(x.config);
+}

package/src/envfile.ts

@@ -0,0 +1,95 @@
+// Parse a `.env.<ENV>` file into push-ready secret tasks.
+//
+// Mirrors the parsing behavior of reqsume/secrets.go:
+//   - skip blank lines + `#` comments
+//   - first `=` splits key/value, both trimmed
+//   - strip a single pair of surrounding `"` or `'` from the value
+//   - skip GITHUB_TOKEN / GOOGLE_APPLICATION_CREDENTIALS (local-only)
+//   - GCP_SA_KEY_FILE_PATH=<path>  → reads file, pushes as GCP_SA_KEY (must look like JSON)
+//   - SSH_KEY_PATH=<path>          → reads file, pushes as SSH_PRIVATE_KEY
+//
+// GITHUB_REPO and GCP_PROJECT_ID are pulled out into `meta` and never pushed
+// as secrets — they're routing config consumed by sync-secrets itself.
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export type SecretTask = { key: string; value: string };
+
+export type ParsedEnv = {
+  tasks: SecretTask[];
+  meta: { GITHUB_REPO?: string; GCP_PROJECT_ID?: string };
+};
+
+const LOCAL_ONLY = new Set(["GITHUB_TOKEN", "GOOGLE_APPLICATION_CREDENTIALS"]);
+const ROUTING = new Set(["GITHUB_REPO", "GCP_PROJECT_ID"]);
+
+export function parseEnvFile(path: string): ParsedEnv {
+  if (!existsSync(path)) {
+    throw new Error(`.env file not found: ${path}`);
+  }
+  const raw = readFileSync(path, "utf8");
+  const tasks: SecretTask[] = [];
+  const meta: ParsedEnv["meta"] = {};
+
+  for (const rawLine of raw.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+
+    const eq = line.indexOf("=");
+    if (eq === -1) continue;
+
+    const key = line.slice(0, eq).trim();
+    let value = stripQuotes(line.slice(eq + 1).trim());
+
+    if (LOCAL_ONLY.has(key)) {
+      console.log(`Skipping ${key} (local use only)`);
+      continue;
+    }
+
+    if (ROUTING.has(key)) {
+      meta[key as keyof ParsedEnv["meta"]] = value;
+      continue;
+    }
+
+    if (key === "GCP_SA_KEY_FILE_PATH") {
+      const content = readFileExpandTilde(value).trim();
+      if (!content.startsWith("{")) {
+        throw new Error(`GCP key file does not look like JSON: ${value}`);
+      }
+      tasks.push({ key: "GCP_SA_KEY", value: content });
+      continue;
+    }
+
+    if (key === "SSH_KEY_PATH") {
+      try {
+        tasks.push({ key: "SSH_PRIVATE_KEY", value: readFileExpandTilde(value) });
+      } catch (e) {
+        console.warn(
+          `Warning: error reading SSH private key from ${value}: ${(e as Error).message}`,
+        );
+      }
+      continue;
+    }
+
+    tasks.push({ key, value });
+  }
+
+  return { tasks, meta };
+}
+
+function stripQuotes(value: string): string {
+  if (value.length < 2) return value;
+  const first = value[0];
+  const last = value[value.length - 1];
+  if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+function readFileExpandTilde(path: string): string {
+  if (path.startsWith("~/")) path = join(homedir(), path.slice(2));
+  return readFileSync(path, "utf8");
+}

package/src/keychain.ts

@@ -0,0 +1,65 @@
+// keychain.ts — thin wrapper over Bun.secrets so the rest of the codebase
+// doesn't have to know whether we're talking to macOS Keychain, Linux
+// libsecret, or Windows Credential Manager. All three are abstracted away
+// by Bun's API; we just pick a consistent service+name pair.
+//
+// Service name follows the UTI convention Bun recommends (`com.org.tool`).
+// Account name is `<repo>/<env>` so a single Keychain entry per repo+env.
+
+import { secrets } from "bun";
+
+export const KEYCHAIN_SERVICE = "tools.vsync";
+
+function accountName(repo: string, env: string): string {
+  if (!repo) throw new Error("repo is required for keychain operations");
+  if (!env) throw new Error("env is required for keychain operations");
+  return `${repo}/${env}`;
+}
+
+/** Save (or overwrite) the encryption key for a (repo, env) pair. */
+export async function setKey(
+  repo: string,
+  env: string,
+  key: string,
+): Promise<void> {
+  if (!key) throw new Error("key value cannot be empty");
+  await secrets.set({
+    service: KEYCHAIN_SERVICE,
+    name: accountName(repo, env),
+    value: key,
+  });
+}
+
+/**
+ * Look up the encryption key. Returns null if not set (rather than throwing)
+ * so callers can produce friendly "key not found, run import" errors.
+ */
+export async function getKey(
+  repo: string,
+  env: string,
+): Promise<string | null> {
+  return await secrets.get({
+    service: KEYCHAIN_SERVICE,
+    name: accountName(repo, env),
+  });
+}
+
+/** Remove the encryption key. Idempotent — no-op if it didn't exist. */
+export async function deleteKey(repo: string, env: string): Promise<void> {
+  try {
+    await secrets.delete({
+      service: KEYCHAIN_SERVICE,
+      name: accountName(repo, env),
+    });
+  } catch {
+    // Bun.secrets.delete throws on macOS for missing entries; swallow so
+    // delete-key is idempotent across platforms.
+  }
+}
+
+/** Generate a fresh 32-byte AES key, base64-encoded (~44 chars). */
+export function generateKey(): string {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return Buffer.from(bytes).toString("base64");
+}

package/src/manifest.ts

@@ -0,0 +1,38 @@
+// Plaintext manifest bound into the encrypted bundle. Lets the pull side
+// verify that the bundle was actually sealed at the timestamp `latest`
+// claims, so an attacker with bucket-write but no encryption key can't
+// repoint `latest` at a renamed copy of an older version.
+//
+// Layout (before encryption):
+//   bytes 0..7   — magic "RQEM0001"
+//   bytes 8..22  — 15-byte timestamp string "YYYYMMDD-HHmmss"
+//   bytes 23..N  — original payload (the zip bytes)
+
+const MAGIC = new TextEncoder().encode("RQEM0001");
+const TS_LEN = 15;
+const HEADER_LEN = MAGIC.length + TS_LEN; // 23
+
+export function wrap(ts: string, payload: Uint8Array): Uint8Array {
+  if (ts.length !== TS_LEN) {
+    throw new Error(`manifest ts must be ${TS_LEN} chars (got ${ts.length})`);
+  }
+  const out = new Uint8Array(HEADER_LEN + payload.byteLength);
+  out.set(MAGIC, 0);
+  out.set(new TextEncoder().encode(ts), MAGIC.length);
+  out.set(payload, HEADER_LEN);
+  return out;
+}
+
+export function unwrap(blob: Uint8Array): { ts: string; payload: Uint8Array } {
+  if (blob.byteLength < HEADER_LEN) {
+    throw new Error("manifest too short");
+  }
+  for (let i = 0; i < MAGIC.length; i++) {
+    if (blob[i] !== MAGIC[i]) {
+      throw new Error("invalid manifest magic — not an RQEM0001 bundle");
+    }
+  }
+  const ts = new TextDecoder().decode(blob.slice(MAGIC.length, HEADER_LEN));
+  const payload = blob.slice(HEADER_LEN);
+  return { ts, payload };
+}

package/src/passphrase.ts

@@ -0,0 +1,39 @@
+// passphrase.ts — generate short, readable passphrases for the share file
+// wrapper. Goals: easy to type, easy to copy, no visually-confusable
+// characters (no 0/O/1/l/I), three hyphen-separated groups so eyes can
+// pair them with confidence on a Slack DM.
+//
+// Default shape: XXXX-XXXX-XXXX (12 chars + 2 hyphens = 14 total).
+
+const ALPHABET = "23456789abcdefghjkmnpqrstuvwxyzABCDEFGHJKMNPQRSTUVWXYZ";
+
+export const PASSPHRASE_MIN_LEN = 8;
+
+export function generatePassphrase(groups = 3, perGroup = 4): string {
+  if (groups < 1 || perGroup < 2) {
+    throw new Error("generatePassphrase: at least 1 group of 2 chars");
+  }
+  const total = groups * perGroup;
+  const bytes = new Uint8Array(total);
+  crypto.getRandomValues(bytes);
+  const chars: string[] = [];
+  for (let i = 0; i < total; i++) {
+    chars.push(ALPHABET[bytes[i]! % ALPHABET.length]);
+  }
+  const out: string[] = [];
+  for (let g = 0; g < groups; g++) {
+    out.push(chars.slice(g * perGroup, (g + 1) * perGroup).join(""));
+  }
+  return out.join("-");
+}
+
+/** Strip surrounding whitespace + reject obvious typos before decrypting. */
+export function normalizePassphrase(input: string): string {
+  const trimmed = (input ?? "").trim();
+  if (trimmed.length < PASSPHRASE_MIN_LEN) {
+    throw new Error(
+      `passphrase must be at least ${PASSPHRASE_MIN_LEN} characters (got ${trimmed.length})`,
+    );
+  }
+  return trimmed;
+}