@muthuishere/vsync 0.3.1 → 0.5.1

package/README.md

@@ -1,34 +1,91 @@
 # vsync
 
-Encrypted secret-sync CLI for small teams.
+**One encrypted vault for your environment secrets, shared across your team, mirrored to GitHub & GCP, audited every time someone touches it.**
 
-- **One canonical store on S3** — your `infra/vault/<env>/` folder, sealed with AES-256-GCM and a manifest pointer that prevents silent rollback.
-- **Per-machine encryption key** in the OS keychain (`Bun.secrets` — macOS Keychain, Linux libsecret, Windows Credential Manager).
-- **Fanout** to GitHub Repo Secrets and GCP Secret Manager from the same source of truth.
-- **Share file** for onboarding teammates with one passphrase-protected `.share` and one passphrase, sent on different channels.
+![vsync flow](https://raw.githubusercontent.com/muthuishere/vsync/main/docs/public/vsync-flow.png)
+
+A `.env` file is the friendliest thing in your repo: one line per secret, edited by hand, loaded by every framework. It's also the worst thing in your repo — passed around on Slack, copy-pasted into the wrong window, never the same on any two laptops, **never encrypted, never versioned, never auditable**. The moment one teammate's secrets drift from another's, you stop trusting `.env` and start emailing JSON files.
+
+vsync keeps the `.env` you already write, and turns it into a real vault:
+
+- **One folder per environment.** Anything secret — `.env.dev`, `gcp-sa.json`, TLS certs, regression fixtures, signing keys — lives under `infra/vault/<env>/`. No naming convention to learn; whatever is in there gets sealed.
+- **Encrypted bucket as the canonical store.** `vsync push <env>` zips the folder, seals it with AES-256-GCM + manifest-anti-rollback, uploads to any S3-compatible bucket: **AWS S3, Hetzner Object Storage, self-hosted MinIO, Cloudflare R2, Backblaze B2**. The bucket holds the only blessed copy.
+- **One-passphrase onboarding.** New teammate runs `vsync import dev <file>.share`, types the passphrase you sent on a separate channel, runs `vsync pull dev`. Done. No shell-rc edits, no env-var blobs, no key sharing in Slack DMs.
+- **Fanout to where prod actually runs.** `vsync sync dev gh` and `vsync sync dev gcp` push the same `.env.<env>` keys to GitHub Actions secrets / GCP Secret Manager. One edit in the vault; both stay in step.
+- **Append-only audit log.** Every push/pull/import/export records `who, where, when, version, free-form note` to a CSV on the bucket. `vsync audit dev` prints it. CI passes `--note="run #1234"` and it shows up.
+- **Per-machine key in the OS keychain.** `Bun.secrets` — macOS Keychain, Linux libsecret, Windows Credential Manager. The S3 bucket alone is useless; the key alone is useless. Both halves required to decrypt.
 
 ```bash
-bunx @muthuishere/vsync --help
+bun  install -g @muthuishere/vsync     # or:  npm install -g @muthuishere/vsync
+vsync --help
 ```
 
-No shell-rc edits. No giant base64 blob in `~/.zshrc`. Run via `bunx`; nothing to install.
+One global install, then `vsync` is on PATH. No shell-rc edits, no giant base64 blob in `~/.zshrc`. (Allergic to global installs? `bunx @muthuishere/vsync <subcommand>` works too — same code path, slower invocation.)
+
+---
+
+## What lives in the vault
+
+Whatever your app needs at runtime that you'd otherwise scatter across Slack DMs, a password manager, or `~/Downloads/`:
+
+```
+infra/vault/
+  dev/
+    .env.dev                  # KV secrets — vsync sync ships these to gh/gcp
+    gcp-sa.json               # JSON service account key
+    regression-fixture.json   # test data that mirrors prod shape
+    tls/cert.pem
+    tls/key.pem
+  production/
+    .env.production
+    gcp-sa.json
+```
+
+vsync doesn't care what's in there — it zips and seals the whole folder. The `.env.<env>` file is special only in that `vsync sync` reads it for KV fanout to GitHub / GCP. Everything else (JSON keys, certs, regression fixtures, anything binary) just rides along in the encrypted bundle and lands back on every teammate's disk after `pull`.
+
+So regression tests, scripts, or any tool that needs real-shape inputs read directly from `infra/vault/<env>/whatever.json` — no separate test-data dance.
+
+For monorepos, override per-(repo, env): `vsync init dev --vault-folder=apps/foo/infra/vault/dev`. The path is stored in the per-repo config and carried in the `.share` file so teammates inherit it automatically.
+
+---
+
+## Switching environments — `vsync use`
+
+So apps don't need to know vault paths, `vsync use <env>` creates a symlink that points the conventional `.env` location at the vault's env file:
+
+```bash
+vsync use dev                          # ./.env → infra/vault/dev/.env.dev
+vsync use production                   # repoint to infra/vault/production/.env.production
+vsync use                              # print current target
+```
+
+Any framework reading `.env` (Vite, Next.js, Bun, dotenv, every Python lib) just works — no path argument, no custom loader. Switch environments with one command; restart your dev server and you're running against the new env.
+
+**Pick a different link name or location** with `--link=<path>` — useful when you already have a `.env`, want the conventional `.env.<env>` name, or work in a monorepo:
+
+```bash
+vsync use dev  --link=.env.dev          # ./.env.dev → infra/vault/dev/.env.dev
+vsync use prod --link=apps/web/.env     # apps/web/.env → … (monorepo)
+```
+
+**Safety:** if the link path already exists as a *regular file*, vsync refuses to touch it — no `--force`, by design. Move or delete it first (`mv .env .env.local.bak`) and re-run. An existing *symlink* at that path is replaced silently (symlinks are cheap to recreate). vsync also warns if the link's basename isn't covered by `.gitignore`.
+
+**Platform support:** POSIX symlinks on macOS / Linux / WSL out of the box. On Windows it uses the same call with `type: "file"` — requires Developer Mode (Settings → Privacy & security → For developers) or an elevated terminal. vsync prints actionable guidance if the privilege is missing.
 
 ---
 
 ## Mental model
 
-Two persistent halves per (repo, env). Both required to push or pull:
+Every (repo, env) is held by **two persistent halves**. Both required to push or pull; either one alone is useless.
 
 ```
 ┌──────────────────────────────────────────────────────────────────┐
 │ Disk (chmod 0600)                                                │
 │  ~/.config/vsync/<repo>/env_<env>        self-contained config   │
-│    ├── s3.{endpoint, region, bucket, …}    required              │
-│    ├── encryption.salt                     random per init       │
+│    ├── s3.{endpoint, region, bucket, …}    where to find bytes   │
+│    ├── encryption.salt                     PBKDF2 input          │
 │    ├── files.vaultFolder                   optional override     │
-│    │                                       (default infra/vault/<env>)│
 │    └── sync.{gh.repo, gcp.project}         set by `vsync sync`   │
-│  ~/.config/vsync/defaults                  pre-fills `init` only │
 └──────────────────────────────────────────────────────────────────┘
 
 ┌──────────────────────────────────────────────────────────────────┐
@@ -39,43 +96,24 @@ Two persistent halves per (repo, env). Both required to push or pull:
 └──────────────────────────────────────────────────────────────────┘
 ```
 
-Anyone with **(S3 read access to the bucket)** AND **(the encryption key in their keychain)** can pull. Either alone is useless: the disk file gets you bucket access but no decrypt; the key gets you decrypt but no bucket location.
-
-The per-repo file is self-contained — `push`/`pull`/`sync` never read a second config. `~/.config/vsync/defaults` is consulted *only* by `init` to pre-fill prompts on subsequent setups.
-
-In your repo, all secret content lives in one place. Default layout:
-
-```
-infra/vault/
-  dev/
-    .env.dev
-    some-secret.json
-    ...
-  production/
-    .env.production
-```
-
-Apps point dotenv (or equivalent) at the path:
+The disk file gets you bucket access — no decrypt. The keychain key gets you decrypt — no bucket location. Stealing one is a non-event; you need both to read a single secret. Offboarding cuts the bucket side (the cloud provider's IAM), then `vsync init` mints a fresh key for the team that stays.
 
-```js
-dotenv.config({ path: `infra/vault/${env}/.env.${env}` });
-```
-
-`vsync init` prints the dotenv snippet so you copy it once.
-
-**Monorepos:** override the vault folder per (repo, env) at init time — `vsync init dev --vault-folder=apps/foo/infra/vault/dev`. The override is stored per-repo, used by every subsequent `push`/`pull`/`sync`, and carried in the `.share` file so teammates inherit it.
+A `.share` file bundles **both halves** under one passphrase. Sent on a different channel than the passphrase itself, it's the smallest possible onboarding step.
 
 ---
 
 ## Install
 
-You don't. Run via `bunx`:
-
 ```bash
-bunx @muthuishere/vsync <subcommand>
+bun install -g @muthuishere/vsync     # or:  npm install -g @muthuishere/vsync
+vsync --help
 ```
 
-Requires Bun ≥ 1.2.21 (for `Bun.secrets`). For local development of vsync itself:
+Requires Bun ≥ 1.2.21 on PATH (for `Bun.secrets`) — the shebang is `#!/usr/bin/env bun`, so `bun` must be installed even if you used `npm install -g` for the package itself. Most users have Bun anyway; if not, see [bun.sh](https://bun.sh).
+
+Don't want to install? `bunx @muthuishere/vsync <subcommand>` runs the same code from npm cache each time — fine for trying it out, slower for daily use.
+
+For local development of vsync itself:
 
 ```bash
 git clone git@github.com:muthuishere/vsync.git
@@ -91,14 +129,14 @@ bun test
 ```bash
 # 1. Generate the per-(repo, env) key + config. First-ever invocation prompts
 #    for S3 creds; subsequent inits pre-fill from ~/.config/vsync/defaults.
-bunx @muthuishere/vsync init dev
+vsync init dev
 
 # 2. Put your secrets under infra/vault/dev/ and push.
 echo "DATABASE_URL=postgres://..." > infra/vault/dev/.env.dev
-bunx @muthuishere/vsync push dev
+vsync push dev
 
 # 3. Hand the team a share file + passphrase (different channels).
-bunx @muthuishere/vsync export dev
+vsync export dev
 ```
 
 For an onboarding cheat sheet to drop into your repo (so teammates and AI agents know vsync exists), run `vsync docs > infra/AGENTS.md`. Plain stdout — pipe it wherever you want.
@@ -110,11 +148,11 @@ cd <cloned-repo>
 
 # 1. Import the share file your teammate sent (carries S3 creds + key).
 #    No prior `init` required on this machine.
-bunx @muthuishere/vsync import dev ./reqsume-dev.share
+vsync import dev ./reqsume-dev.share
 # Passphrase: <paste>
 
 # 2. Pull the encrypted bundle.
-bunx @muthuishere/vsync pull dev
+vsync pull dev
 ```
 
 After step 2, `infra/vault/dev/` is populated and the encryption key is in your keychain.
@@ -123,18 +161,18 @@ After step 2, `infra/vault/dev/` is populated and the encryption key is in your
 
 ```bash
 # I edited infra/vault/dev/.env.dev locally:
-bunx @muthuishere/vsync push dev
+vsync push dev
 
 # Get the latest from S3:
-bunx @muthuishere/vsync pull dev
+vsync pull dev
 
 # See what versions exist on S3:
-bunx @muthuishere/vsync versions dev
+vsync versions dev
 
 # Push secrets out to GitHub / GCP:
-bunx @muthuishere/vsync sync dev gh
-bunx @muthuishere/vsync sync dev gcp
-bunx @muthuishere/vsync sync dev all
+vsync sync dev gh
+vsync sync dev gcp
+vsync sync dev all
 ```
 
 `pull` makes a local backup at `~/.config/vsync/backups/<env>-<ts>.zip.enc` before overwriting (two-deep rolling buffer). See "Recovering a local backup" below if you ever need one.
@@ -149,13 +187,15 @@ Every command works fully via flags or fully via prompts.
 
 | Cmd | Purpose |
 |---|---|
-| `init <env>` | Generate AES key (→ keychain), write self-contained per-repo config, create the resolved vault folder, relocate an existing root `.env.<env>` if found (with a prompt). First-ever run on a machine also writes `~/.config/vsync/defaults` from the supplied values; subsequent runs pre-fill from defaults. Flags: `--bucket --endpoint --region --access-key --secret-key --use-ssl --vault-folder=<path> --migrate-from=<path> --no-migrate`. |
-| `export <env>` | Write a passphrase-encrypted `.share` file containing the full per-repo config + key. Flags: `--out=<path>` (default `./<repo>-<env>.share`), `--passphrase=<p>` (default: auto-generated readable passphrase). |
-| `import <env> <file>` | Decrypt a `.share` file with its passphrase; write the per-repo config + save key to keychain. Idempotent — re-importing overwrites. Flags: `--passphrase=<p>`, `--file=<path>` (alt to positional). |
-| `push <env>` | Zip the resolved vault folder → manifest-seal → AES-256-GCM encrypt → upload to `s3://<bucket>/<repo>/<env>/versions/<ts>.enc`, then update `s3://<bucket>/<repo>/<env>/latest`. |
-| `pull <env>` | Read `latest` pointer → download version → verify embedded manifest timestamp matches pointer (anti-rollback) → decrypt → unzip into the resolved vault folder. Auto-backs up existing contents first. |
+| `init <env>` | Generate AES key (→ keychain), write self-contained per-repo config, create the resolved vault folder, relocate an existing root `.env.<env>` if found (with a prompt). First-ever run on a machine also writes `~/.config/vsync/defaults` from the supplied values; subsequent runs pre-fill from defaults. Flags: `--bucket --endpoint --region --access-key --secret-key --use-ssl --vault-folder=<path> --migrate-from=<path> --no-migrate --audit=on\|off`. |
+| `export <env>` | Write a passphrase-encrypted `.share` file containing the full per-repo config + key. Flags: `--out=<path>` (default `./<repo>-<env>.share`), `--passphrase=<p>` (default: auto-generated readable passphrase), `--no-audit`, `--note=<text>`, `--meta key=value` (repeatable). |
+| `import <env> <file>` | Decrypt a `.share` file with its passphrase; write the per-repo config + save key to keychain. Idempotent — re-importing overwrites. Flags: `--passphrase=<p>`, `--file=<path>` (alt to positional), `--no-audit`, `--note=<text>`, `--meta key=value` (repeatable). |
+| `use <env>` | Symlink the chosen path → `<vaultFolder>/.env.<env>` so plain `dotenv.config()` works without a path arg. Default link path is `./.env`; override with `--link=<path>` (e.g. `--link=.env.dev` or `--link=apps/web/.env`). `vsync use` with no env prints the current target. **Refuses to touch an existing regular file at the link path — no `--force`, by design.** Replaces an existing symlink silently. Warns if the link's basename isn't `.gitignore`d. POSIX symlinks everywhere; Windows requires Developer Mode or an elevated terminal. |
+| `push <env>` | Zip the resolved vault folder → manifest-seal → AES-256-GCM encrypt → upload to `s3://<bucket>/<repo>/<env>/versions/<ts>.enc`, then update `s3://<bucket>/<repo>/<env>/latest`. Flags: `--no-audit`, `--note=<text>`, `--meta key=value` (repeatable). |
+| `pull <env>` | Read `latest` pointer → download version → verify embedded manifest timestamp matches pointer (anti-rollback) → decrypt → unzip into the resolved vault folder. Auto-backs up existing contents first. Flags: `--no-audit`, `--note=<text>`, `--meta key=value` (repeatable). |
 | `versions <env>` | List `s3://<bucket>/<repo>/<env>/versions/`. One line per version with size + age, `* latest` marker on the active one. Read-only; no decrypt. |
 | `sync <env> <gh\|gcp\|all>` | Read `<vaultFolder>/.env.<env>` → push each KV to the named target. Parallel (6 workers, 10-min timeout). First run prompts for routing config (gh repo / gcp project) and saves it; subsequent runs zero-prompt. Flags: `--gh-repo=<owner/name>`, `--gcp-project=<id>`. |
+| `audit <env>` | Print the S3-side audit log: who/where/when of every pull/push/import/export. Flags: `--limit=N`, `--all`, `--csv`. |
 | `docs` | Print a short onboarding reference (commands, vault layout, backup recovery procedure) to stdout. Pipe wherever you want — e.g. `vsync docs > infra/AGENTS.md`. |
 
 ### `sync` env-file parsing
@@ -172,6 +212,28 @@ Two local-only keys (skipped — used by `gh` / `gcloud` on the local machine, n
 
 Everything else is pushed verbatim.
 
+### Audit log
+
+Every `pull`, `push`, `import`, and `export` appends a row to `s3://<bucket>/<repo>/<env>/audit.csv` so the team can see who did what, from where, and when. Columns:
+
+- `ts, action, version_ts, hostname, local_ip, os_user, git_email, vsync_version, bun_version, meta`
+
+On by default. Skip a single invocation with `--no-audit`. Disable per (repo, env) with `vsync init <env> --audit=off` (or pick "off" at the first-time prompt).
+
+Tag any row with free-form context via `--note=<text>` (sugar for `--meta note=<text>`) or `--meta key=value` (repeatable). The matching env vars `VSYNC_AUDIT_NOTE` and `VSYNC_AUDIT_META` (a JSON object) merge in for CI ergonomics. Example one-liner:
+
+```bash
+VSYNC_AUDIT_META='{"run_id":"7891234","commit":"abc123"}' \
+  vsync pull production --note="prod deploy" --meta ticket=BUG-42
+```
+
+View the log with `vsync audit <env>` (`--limit=N`, `--all`, `--csv`).
+
+Two honesty bullets:
+
+- This is a transparency aid, not tamper-proof. Anyone with bucket write can rewrite the CSV; vsync just makes honest activity legible.
+- The log does not let you reclaim already-pulled secrets. Once a teammate has pulled, they hold a local copy — rotate the key to invalidate future pulls.
+
 ---
 
 ## How sync works (gh + gcp)
@@ -241,17 +303,13 @@ In practice, just don't lose the keychain entry. `pull` itself is the recovery p
 
 ## Versioning
 
-This is **0.3.0** — a clean break from `@muthuishere/secret-lib` 0.2.x. New package name, new bin (`vsync`), new keychain service (`tools.vsync`), new config root (`~/.config/vsync/`), new vault layout (`infra/vault/<env>/.env.<env>`). The crypto envelope (`RQE1`) is unchanged.
-
-0.3.x does not auto-migrate from 0.2.x. The supported upgrade path is to re-`init` from scratch:
-
-```bash
-vsync init dev          # auto-relocates root .env.dev if it exists
-vsync push dev
-vsync export dev        # re-share with team
-```
+| Release | What's in it |
+|---|---|
+| **0.5.0** | `vsync use <env>` — symlinks `./.env` (or `--link=<path>`) at the vault's env file so `dotenv.config()` just works; switch envs with one command. README rewrite + flow diagram. |
+| 0.4.0 | Append-only audit log at `s3://<bucket>/<repo>/<env>/audit.csv` + `vsync audit` viewer. Expandable `meta` JSON cell via `--note` / `--meta` + matching env vars. |
+| 0.3.0 | Opinionated layout: vault folder at `infra/vault/<env>/` with `--vault-folder` override; self-contained per-(repo, env) config; `vsync sync` for GitHub / GCP fanout. |
 
-Any leftover 0.2.x on-disk config tree and keychain entries can be deleted; nothing in 0.3.x reads them. `@muthuishere/secret-lib` 0.2.x stays on npm for users who can't migrate.
+All 0.x releases are wire-compatible with each other on the S3 bundle envelope (`RQE1`) and manifest seal (`RQEM0001`). New clients tolerate the absence of features added in later versions; old clients ignore new objects (like `audit.csv`) on the bucket.
 
 ---
 

package/bin/audit.ts

@@ -0,0 +1,73 @@
+#!/usr/bin/env bun
+// Usage: vsync audit <env> [--limit=N] [--all] [--csv] [--repo=<name>]
+//
+// Fetches s3://<bucket>/<repo>/<env>/audit.csv and prints it. Default is a
+// pretty table of the last 50 rows (newest first); --all shows everything;
+// --limit=N picks a custom cap; --csv passes the raw CSV through for piping
+// into shell tools or spreadsheets.
+//
+// Read-only: per spec §6, observing the log must not perturb it — this
+// command does NOT append an audit row of its own.
+
+import { parseArgs } from "../src/argv";
+import { getRepoName } from "../src/repo";
+import { loadConfigFile, configFilePath } from "../src/repoconfig";
+import {
+  makeAuditClient,
+  readAuditLog,
+  formatAuditTable,
+  formatAuditCsv,
+} from "../src/audit";
+
+export async function main(argv: string[]): Promise<void> {
+  const { positional, flags } = parseArgs(argv);
+  const env = positional[0];
+  if (!env) {
+    console.error("usage: vsync audit <env> [--limit=N] [--all] [--csv] [--repo=<name>]");
+    process.exit(1);
+  }
+  const repo = await getRepoName({ override: flags.repo });
+
+  const cfg = await loadConfigFile(repo, env);
+  if (!cfg) {
+    console.error(
+      `no config file for ${repo}/${env} at ${configFilePath(repo, env)}.\n` +
+        `Run 'vsync init ${env}' first, or 'vsync import ${env} <share-file>' if a teammate sent you one.`,
+    );
+    process.exit(1);
+  }
+
+  const client = makeAuditClient(cfg.s3);
+
+  let rows;
+  try {
+    rows = await readAuditLog(client, repo, env);
+  } catch (e) {
+    console.error(
+      `failed to read audit log for ${repo}/${env}: ${(e as Error).message}`,
+    );
+    process.exit(1);
+  }
+
+  if (rows.length === 0) {
+    console.log(`(no audit log yet for ${repo}/${env})`);
+    return;
+  }
+
+  if (flags.csv === "true") {
+    process.stdout.write(formatAuditCsv(rows));
+    return;
+  }
+
+  const all = flags.all === "true";
+  const limit = flags.limit !== undefined ? parseInt(flags.limit, 10) : undefined;
+  if (limit !== undefined && (!Number.isFinite(limit) || limit <= 0)) {
+    console.error(`--limit must be a positive integer (got "${flags.limit}")`);
+    process.exit(1);
+  }
+  console.log(formatAuditTable(rows, { limit, all }));
+}
+
+if (import.meta.main) {
+  await main(process.argv.slice(2));
+}

package/bin/export.ts

@@ -11,17 +11,23 @@
 
 import { parseArgs } from "../src/argv";
 import { getRepoName } from "../src/repo";
-import { loadConfigFile, configFilePath } from "../src/repoconfig";
+import { loadConfigFile, configFilePath, DEFAULT_AUDIT_ENABLED } from "../src/repoconfig";
 import { getKey } from "../src/keychain";
 import { EXPORT_BLOB_VERSION, type ExportPayload } from "../src/envconfig";
 import { buildShareFile } from "../src/sharefile";
 import { generatePassphrase } from "../src/passphrase";
 import { askText, isTty } from "../src/prompt";
+import {
+  appendAuditRow,
+  buildMeta,
+  gatherRowMetadata,
+  makeAuditClient,
+} from "../src/audit";
 import { writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 
 export async function main(argv: string[]): Promise<void> {
-  const { positional, flags } = parseArgs(argv);
+  const { positional, flags, lists } = parseArgs(argv);
   const env = positional[0];
   if (!env) {
     console.error("usage: vsync export <env> [--repo=<name>] [--out=<path>] [--passphrase=<pp>]");
@@ -85,6 +91,50 @@ export async function main(argv: string[]): Promise<void> {
   console.log("(e.g. file via Slack DM, passphrase via SMS).\n");
   console.log("They will run:");
   console.log(`  vsync import ${env} ${out.split("/").pop()}`);
+
+  await tryAppendAudit(cfg.s3, cfg.audit?.enabled, flags, lists, repo, env);
+}
+
+/**
+ * Best-effort audit append. Honours both the per-(repo, env) opt-out
+ * (`cfg.audit.enabled === false`) and the per-invocation `--no-audit`
+ * flag. Any throw from the append path is downgraded to a stderr warning
+ * so the parent command's exit code is unaffected.
+ */
+async function tryAppendAudit(
+  s3: Parameters<typeof makeAuditClient>[0],
+  enabled: boolean | undefined,
+  flags: Record<string, string>,
+  lists: Record<string, string[]>,
+  repo: string,
+  env: string,
+): Promise<void> {
+  if (flags["no-audit"] === "true") return;
+  const on = enabled ?? DEFAULT_AUDIT_ENABLED;
+  if (!on) return;
+
+  let meta;
+  try {
+    meta = buildMeta({
+      envMeta: process.env.VSYNC_AUDIT_META,
+      envNote: process.env.VSYNC_AUDIT_NOTE,
+      flagMetaList: lists.meta,
+      flagNote: flags.note,
+    });
+  } catch (e) {
+    console.error((e as Error).message);
+    process.exit(1);
+  }
+  for (const w of meta.warnings) console.error(w);
+
+  try {
+    const row = await gatherRowMetadata("export", "");
+    row.meta = meta.json;
+    const client = makeAuditClient(s3);
+    await appendAuditRow(client, repo, env, row);
+  } catch (e) {
+    console.error(`warning: failed to record audit entry: ${(e as Error).message}`);
+  }
 }
 
 if (import.meta.main) {

package/bin/import.ts

@@ -10,15 +10,21 @@
 
 import { parseArgs } from "../src/argv";
 import { getRepoName } from "../src/repo";
-import { saveConfigFile, configFilePath } from "../src/repoconfig";
+import { saveConfigFile, configFilePath, DEFAULT_AUDIT_ENABLED } from "../src/repoconfig";
 import { setKey } from "../src/keychain";
 import { parseShareFile } from "../src/sharefile";
 import { askText, askSecret, isTty } from "../src/prompt";
+import {
+  appendAuditRow,
+  buildMeta,
+  gatherRowMetadata,
+  makeAuditClient,
+} from "../src/audit";
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 
 export async function main(argv: string[]): Promise<void> {
-  const { positional, flags } = parseArgs(argv);
+  const { positional, flags, lists } = parseArgs(argv);
   const env = positional[0];
   let filePath = positional[1] ?? flags.file;
   if (!env) {
@@ -96,6 +102,50 @@ export async function main(argv: string[]): Promise<void> {
   console.log("You can safely delete the .share file now — its contents are installed.");
   // Silence "unused var" linters from finalEnv assignment kept for clarity.
   void finalEnv;
+
+  await tryAppendAudit(payload.config.s3, payload.config.audit?.enabled, flags, lists, repo, env);
+}
+
+/**
+ * Best-effort audit append. Honours both the per-(repo, env) opt-out
+ * (`cfg.audit.enabled === false`) and the per-invocation `--no-audit`
+ * flag. Any throw from the append path is downgraded to a stderr warning
+ * so the parent command's exit code is unaffected.
+ */
+async function tryAppendAudit(
+  s3: Parameters<typeof makeAuditClient>[0],
+  enabled: boolean | undefined,
+  flags: Record<string, string>,
+  lists: Record<string, string[]>,
+  repo: string,
+  env: string,
+): Promise<void> {
+  if (flags["no-audit"] === "true") return;
+  const on = enabled ?? DEFAULT_AUDIT_ENABLED;
+  if (!on) return;
+
+  let meta;
+  try {
+    meta = buildMeta({
+      envMeta: process.env.VSYNC_AUDIT_META,
+      envNote: process.env.VSYNC_AUDIT_NOTE,
+      flagMetaList: lists.meta,
+      flagNote: flags.note,
+    });
+  } catch (e) {
+    console.error((e as Error).message);
+    process.exit(1);
+  }
+  for (const w of meta.warnings) console.error(w);
+
+  try {
+    const row = await gatherRowMetadata("import", "");
+    row.meta = meta.json;
+    const client = makeAuditClient(s3);
+    await appendAuditRow(client, repo, env, row);
+  } catch (e) {
+    console.error(`warning: failed to record audit entry: ${(e as Error).message}`);
+  }
 }
 
 if (import.meta.main) {

package/bin/init.ts

@@ -30,6 +30,8 @@
 //   --vault-folder=<path>    Override default infra/vault/<env> for monorepos
 //   --migrate-from=<path>    Use a non-default source for the .env relocation
 //   --no-migrate             Skip the root .env.<env> migration prompt entirely
+//   --audit=on|off           Enable/disable the per-(repo, env) audit log
+//                            (default on; prompted interactively when unset)
 //   --interactive            Prompt even for fields already provided via flags
 
 import { existsSync, mkdirSync, renameSync, readFileSync } from "node:fs";
@@ -39,6 +41,7 @@ import { getRepoName, getRepoRoot } from "../src/repo";
 import {
   saveConfigFile,
   configFilePath,
+  DEFAULT_AUDIT_ENABLED,
   type ConfigFile,
 } from "../src/repoconfig";
 import { setKey, generateKey } from "../src/keychain";
@@ -73,6 +76,14 @@ function randomSalt(): string {
   return Buffer.from(bytes).toString("base64").replace(/=+$/, "");
 }
 
+function parseOnOff(raw: string, label: string): boolean {
+  const v = raw.toLowerCase();
+  if (v === "on" || v === "true" || v === "yes" || v === "1") return true;
+  if (v === "off" || v === "false" || v === "no" || v === "0") return false;
+  console.error(`${label} must be "on" or "off" (got "${raw}")`);
+  process.exit(1);
+}
+
 export async function main(argv: string[]): Promise<void> {
   const { positional, flags } = parseArgs(argv);
   const env = envFromArg(positional[0]);
@@ -133,11 +144,26 @@ export async function main(argv: string[]): Promise<void> {
   const vaultFolder = vaultFolderOverride ?? defaultVaultFolder;
   const hasVaultOverride = !!vaultFolderOverride && vaultFolderOverride !== defaultVaultFolder;
 
+  // --audit=on|off — explicit flag wins; otherwise prompt when interactive
+  // (or no flag and TTY); otherwise default to enabled.
+  const auditFlag = flags.audit;
+  let auditEnabled: boolean;
+  if (auditFlag !== undefined && !interactive) {
+    auditEnabled = parseOnOff(auditFlag, "--audit");
+  } else if (isTty() && (interactive || auditFlag === undefined)) {
+    const prefilled =
+      auditFlag !== undefined ? parseOnOff(auditFlag, "--audit") : DEFAULT_AUDIT_ENABLED;
+    auditEnabled = askBool("Enable audit log?", prefilled);
+  } else {
+    auditEnabled = auditFlag !== undefined ? parseOnOff(auditFlag, "--audit") : DEFAULT_AUDIT_ENABLED;
+  }
+
   const cfg: ConfigFile = {
     version: 1,
     s3: { endpoint, region, bucket, accessKeyId, secretAccessKey, useSsl },
     encryption: { salt: randomSalt() },
     ...(hasVaultOverride ? { files: { vaultFolder } } : {}),
+    audit: { enabled: auditEnabled },
   };
 
   const filePath = await saveConfigFile(repo, env, cfg);

package/bin/pull.ts

@@ -12,14 +12,21 @@ import { join } from "node:path";
 import { parseArgs } from "../src/argv";
 import { getRepoName, getRepoRoot } from "../src/repo";
 import { loadEnvConfig, resolveVaultFolder } from "../src/envconfig";
+import { loadConfigFile, DEFAULT_AUDIT_ENABLED } from "../src/repoconfig";
 import { unzipTo } from "../src/archive";
 import { decrypt } from "../src/crypto";
 import { unwrap } from "../src/manifest";
 import { makeClient } from "../src/s3";
 import { makeBackup } from "../src/backup";
+import {
+  appendAuditRow,
+  buildMeta,
+  gatherRowMetadata,
+  makeAuditClient,
+} from "../src/audit";
 
 export async function main(argv: string[]): Promise<void> {
-  const { positional, flags } = parseArgs(argv);
+  const { positional, flags, lists } = parseArgs(argv);
   const env = positional[0];
   if (!env) {
     console.error("usage: vsync pull <env> [--repo=<name>]");
@@ -34,6 +41,9 @@ export async function main(argv: string[]): Promise<void> {
     console.error((e as Error).message);
     process.exit(1);
   }
+  // Reload the on-disk ConfigFile to pick up `audit.enabled` (EnvConfig
+  // doesn't carry it through).
+  const cfgFile = await loadConfigFile(repo, env);
   const root = await getRepoRoot();
   const vaultFolder = resolveVaultFolder(cfg, env);
 
@@ -96,6 +106,51 @@ export async function main(argv: string[]): Promise<void> {
   } finally {
     if (existsSync(tmpZip)) unlinkSync(tmpZip);
   }
+
+  await tryAppendAudit(cfg.s3, cfgFile?.audit?.enabled, flags, lists, repo, env, remoteTs);
+}
+
+/**
+ * Best-effort audit append. Honours both the per-(repo, env) opt-out
+ * (`cfg.audit.enabled === false`) and the per-invocation `--no-audit`
+ * flag. Any throw from the append path is downgraded to a stderr warning
+ * so the parent command's exit code is unaffected.
+ */
+async function tryAppendAudit(
+  s3: Parameters<typeof makeAuditClient>[0],
+  enabled: boolean | undefined,
+  flags: Record<string, string>,
+  lists: Record<string, string[]>,
+  repo: string,
+  env: string,
+  versionTs: string,
+): Promise<void> {
+  if (flags["no-audit"] === "true") return;
+  const on = enabled ?? DEFAULT_AUDIT_ENABLED;
+  if (!on) return;
+
+  let meta;
+  try {
+    meta = buildMeta({
+      envMeta: process.env.VSYNC_AUDIT_META,
+      envNote: process.env.VSYNC_AUDIT_NOTE,
+      flagMetaList: lists.meta,
+      flagNote: flags.note,
+    });
+  } catch (e) {
+    console.error((e as Error).message);
+    process.exit(1);
+  }
+  for (const w of meta.warnings) console.error(w);
+
+  try {
+    const row = await gatherRowMetadata("pull", versionTs);
+    row.meta = meta.json;
+    const client = makeAuditClient(s3);
+    await appendAuditRow(client, repo, env, row);
+  } catch (e) {
+    console.error(`warning: failed to record audit entry: ${(e as Error).message}`);
+  }
 }
 
 if (import.meta.main) {