release(v4.0.0): Shade GA — V3.x consolidation + audit prep

V3.1 → V3.12 consolidated and tagged for the first GA release. Wire
format unchanged from 0.4.x — 4.0 peers interoperate with 0.4.x peers
byte-for-byte. The version bump is semantic: audit-cycle complete,
opt-in surface fully exposed, threat model refreshed for every new
surface.

Highlights:
- All 24 @shade/* packages bumped to 4.0.0 in lockstep.
- CHANGELOG 4.0.0 section is the canonical manifest of what landed.
- THREAT-MODEL extended (§10 fingerprint gates, §11 WebRTC P2P, §12
  Web-Worker boundary) + residual-risks table refreshed.
- OpenAPI now covers all 27 routes: prekey, transfer, KT, inbox,
  bridge, observer, /metrics, /healthz, /ready.
- MIGRATION 0.3.x → 4.0 documented + smoke-tested against
  shade migrate-storage on a real SQLite DB.
- docs/audit/REVIEW-BUNDLE.md + SCOPE.md ready for external reviewer.
- scripts/soak.ts harness for the GA-stable 2-week soak window.
- All V*.md plans archived under docs/archive/ with Status: Done.
- Voice/Video carved out into V5.0; 4.0 audit focuses on the frozen
  non-realtime stack.

Tests: TS 1000/1000 + Kotlin 11/11 cross-platform vectors green.
Docker: gt.zyon.no/stian/shade-prekey:4.0.0 builds and reports
  version 4.0.0 on /health.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

packages/shade-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/cli",
-  "version": "0.3.0",
+  "version": "4.0.0",
   "type": "module",
   "main": "src/cli.ts",
   "bin": {
@@ -9,7 +9,9 @@
   "dependencies": {
     "@shade/core": "workspace:*",
     "@shade/crypto-web": "workspace:*",
+    "@shade/keychain": "workspace:*",
     "@shade/sdk": "workspace:*",
+    "@shade/storage-encrypted": "workspace:*",
     "@shade/storage-sqlite": "workspace:*",
     "@shade/transport": "workspace:*"
   },

packages/shade-cli/src/cli.ts

@@ -12,6 +12,11 @@ import {
 import { dashboardCommand } from './commands/dashboard.js';
 import { doctorCommand } from './commands/doctor.js';
 import { backupExportCommand, backupRestoreCommand } from './commands/backup.js';
+import {
+  migrateStorageCommand,
+  rotateStorageKeyCommand,
+  parseStorageArgs,
+} from './commands/storage.js';
 
 const VERSION = '0.1.0';
 
@@ -24,6 +29,7 @@ Commands:
   init [name]              Scaffold a new Shade project
     --template <name>        Template to use (default: bun-server)
     --prekey-server <url>    Override prekey server URL
+    --doctor                 Run shade doctor against the new project
   fingerprint [address]    Print your own or a peer's fingerprint
   publish                  Re-upload your bundle to the prekey server
   rotate                   Rotate the signed prekey
@@ -37,6 +43,19 @@ Commands:
   doctor                   Diagnose setup issues
   backup export <file>     Export an encrypted backup (prompts for passphrase)
   backup restore <file>    Restore from a backup file
+  migrate-storage          Encrypt the local SQLite store at-rest (V3.2)
+    --key-source <kind>      passphrase | keychain | injected
+    --passphrase <s>         passphrase for KDF (or env SHADE_STORAGE_PASSPHRASE)
+    --keychain-service <s>   keychain service name (default: shade.storage)
+    --keychain-account <s>   keychain account name (default: default)
+    --key-hex <hex>          inject a raw 32-byte key as hex
+    --salt-file <path>       passphrase salt file (default: <db>.salt)
+    --dry-run                validate + report without writing
+    --keep-original          keep unencrypted tables after migration
+    --no-backup              skip the .bak snapshot
+  rotate-storage-key       Re-key the encrypted SQLite store (V3.2)
+    --key-source / --passphrase / …  (current key — same flags as migrate)
+    --new-key-source / --new-passphrase / …  (target key)
   help                     Show this message
 
 Config:
@@ -98,6 +117,16 @@ async function main(): Promise<void> {
         }
         break;
       }
+      case 'migrate-storage': {
+        const opts = parseStorageArgs(args.slice(1));
+        await migrateStorageCommand(opts);
+        break;
+      }
+      case 'rotate-storage-key': {
+        const opts = parseStorageArgs(args.slice(1));
+        await rotateStorageKeyCommand(opts);
+        break;
+      }
       case 'help':
       case '--help':
       case '-h':
@@ -125,11 +154,13 @@ function parseInitArgs(args: string[]): {
   name?: string;
   template?: string;
   prekeyServer?: string;
+  runDoctor?: boolean;
 } {
   const options: ReturnType<typeof parseInitArgs> = {};
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '--template') options.template = args[++i];
     else if (args[i] === '--prekey-server') options.prekeyServer = args[++i];
+    else if (args[i] === '--doctor') options.runDoctor = true;
     else if (!args[i]!.startsWith('--')) options.name = args[i];
   }
   return options;

packages/shade-cli/src/commands/doctor.ts

@@ -1,15 +1,19 @@
 import { tryLoadConfig } from '../config.js';
 import { existsSync } from 'fs';
 
+export interface DoctorOptions {
+  cwd?: string;
+}
+
 /**
  * Diagnose common setup issues.
  */
-export async function doctorCommand(): Promise<void> {
+export async function doctorCommand(opts: DoctorOptions = {}): Promise<void> {
   let ok = true;
   console.log('\x1b[33mShade doctor\x1b[0m\n');
 
   // 1. Config loadable?
-  const configResult = tryLoadConfig();
+  const configResult = tryLoadConfig(opts.cwd);
   if (configResult.ok) {
     console.log('  \x1b[32m✓\x1b[0m Config loaded from .shaderc.json or env vars');
     const config = configResult.config;

packages/shade-cli/src/commands/init.ts

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, writeFileSync, readdirSync, statSync, readFileSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
+import { doctorCommand } from './doctor.js';
 
 const here = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = join(here, '..', '..', 'templates');
@@ -10,6 +11,7 @@ export interface InitOptions {
   template?: string;
   prekeyServer?: string;
   cwd?: string;
+  runDoctor?: boolean;
 }
 
 export async function initCommand(opts: InitOptions = {}): Promise<void> {
@@ -42,6 +44,11 @@ export async function initCommand(opts: InitOptions = {}): Promise<void> {
   console.log(`  cd ${name}`);
   console.log('  bun install');
   console.log('  bun run start');
+
+  if (opts.runDoctor) {
+    console.log('');
+    await doctorCommand({ cwd: target });
+  }
 }
 
 export function listTemplates(): string[] {

packages/shade-cli/src/commands/storage.ts

@@ -0,0 +1,208 @@
+/**
+ * `shade migrate-storage` and `shade rotate-storage-key` — at-rest encryption
+ * lifecycle commands (V3.2).
+ *
+ * Both rely on @shade/storage-encrypted; key sources mirror what KeyManager
+ * accepts: passphrase | keychain | injected (env-injected).
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { mkdirSync } from 'node:fs';
+import { KeyManager, type KeySource, migrateSqliteToEncrypted, rotateSqliteEncryptionKey } from '@shade/storage-encrypted';
+
+interface CommonStorageOptions {
+  dbPath?: string;
+  keySource: 'passphrase' | 'keychain' | 'injected';
+  passphrase?: string;
+  keychainService?: string;
+  keychainAccount?: string;
+  injectedKeyHex?: string;
+  saltFile?: string;
+}
+
+export interface MigrateCliOptions extends CommonStorageOptions {
+  dryRun?: boolean;
+  keepOriginal?: boolean;
+  noBackup?: boolean;
+}
+
+export interface RotateCliOptions extends CommonStorageOptions {
+  newKeySource: 'passphrase' | 'keychain' | 'injected';
+  newPassphrase?: string;
+  newKeychainService?: string;
+  newKeychainAccount?: string;
+  newInjectedKeyHex?: string;
+  newSaltFile?: string;
+}
+
+export async function migrateStorageCommand(opts: MigrateCliOptions): Promise<void> {
+  const dbPath = opts.dbPath ?? process.env.SHADE_DB_PATH ?? '/data/shade-client.db';
+  const km = await openKeyManager({ ...opts, dbPath, role: 'open-or-create' });
+
+  const log = (m: string) => console.log(`  • ${m}`);
+  console.log(`Migrating ${dbPath} → encrypted at-rest schema…`);
+  if (opts.dryRun) console.log('  (dry-run: no writes will be made)');
+
+  const dryRun = opts.dryRun ?? false;
+  // Respect explicit --no-backup; otherwise inherit migrate's default
+  // (which is "no backup during dry-run, backup otherwise").
+  const backup = opts.noBackup ? false : !dryRun;
+  const report = await migrateSqliteToEncrypted({
+    dbPath,
+    keyManager: km,
+    log,
+    dryRun,
+    keepOriginal: opts.keepOriginal ?? false,
+    backup,
+  });
+
+  console.log('\nResult:');
+  console.log(`  identity            ${report.identity}`);
+  console.log(`  config              ${report.config}`);
+  console.log(`  signed_prekeys      ${report.signedPrekeys}`);
+  console.log(`  one_time_prekeys    ${report.oneTimePrekeys}`);
+  console.log(`  sessions            ${report.sessions}`);
+  console.log(`  trusted_identities  ${report.trustedIdentities}`);
+  console.log(`  retired_identities  ${report.retiredIdentities}`);
+  console.log(`  stream_state        ${report.streamStates}`);
+  console.log(`  duration            ${report.durationMs}ms`);
+  if (report.backupPath) console.log(`  backup              ${report.backupPath}`);
+  if (report.dryRun) console.log('\nDry-run complete; no data was modified.');
+  else if (!report.keptOriginal) console.log('\nUnencrypted tables dropped.');
+}
+
+export async function rotateStorageKeyCommand(opts: RotateCliOptions): Promise<void> {
+  const dbPath = opts.dbPath ?? process.env.SHADE_DB_PATH ?? '/data/shade-client.db';
+  if (!existsSync(dbPath)) throw new Error(`rotate-storage-key: DB not found at ${dbPath}`);
+
+  console.log(`Rotating storage key for ${dbPath}…`);
+
+  const oldKm = await openKeyManager({
+    dbPath,
+    role: 'open-existing',
+    keySource: opts.keySource,
+    ...(opts.passphrase !== undefined ? { passphrase: opts.passphrase } : {}),
+    ...(opts.keychainService !== undefined ? { keychainService: opts.keychainService } : {}),
+    ...(opts.keychainAccount !== undefined ? { keychainAccount: opts.keychainAccount } : {}),
+    ...(opts.injectedKeyHex !== undefined ? { injectedKeyHex: opts.injectedKeyHex } : {}),
+    ...(opts.saltFile !== undefined ? { saltFile: opts.saltFile } : {}),
+  });
+  const newKm = await openKeyManager({
+    dbPath,
+    role: 'open-or-create',
+    keySource: opts.newKeySource,
+    ...(opts.newPassphrase !== undefined ? { passphrase: opts.newPassphrase } : {}),
+    ...(opts.newKeychainService !== undefined ? { keychainService: opts.newKeychainService } : {}),
+    ...(opts.newKeychainAccount !== undefined ? { keychainAccount: opts.newKeychainAccount } : {}),
+    ...(opts.newInjectedKeyHex !== undefined ? { injectedKeyHex: opts.newInjectedKeyHex } : {}),
+    ...(opts.newSaltFile !== undefined ? { saltFile: opts.newSaltFile } : {}),
+  });
+
+  const log = (m: string) => console.log(`  • ${m}`);
+  const result = await rotateSqliteEncryptionKey({ dbPath, oldKeyManager: oldKm, newKeyManager: newKm, log });
+  console.log(`\nRotation complete: ${result.rowsRotated} rows re-keyed.`);
+}
+
+// ─── helpers ──────────────────────────────────────────────────────
+
+interface OpenKmArgs extends CommonStorageOptions {
+  /** open-existing: salt file MUST already exist for passphrase mode. open-or-create: generate salt if missing. */
+  role: 'open-existing' | 'open-or-create';
+}
+
+async function openKeyManager(args: OpenKmArgs): Promise<KeyManager> {
+  const source = await buildKeySource(args);
+  if (source.kind === 'keychain') {
+    const { getDefaultKeychain } = await import('@shade/keychain');
+    return KeyManager.open(source, { keychain: getDefaultKeychain() });
+  }
+  return KeyManager.open(source);
+}
+
+async function buildKeySource(args: OpenKmArgs): Promise<KeySource> {
+  switch (args.keySource) {
+    case 'passphrase': {
+      const passphrase = args.passphrase ?? process.env.SHADE_STORAGE_PASSPHRASE;
+      if (!passphrase) throw new Error('passphrase required: pass --passphrase or set SHADE_STORAGE_PASSPHRASE');
+      const dbPath = args.dbPath ?? process.env.SHADE_DB_PATH ?? '/data/shade-client.db';
+      const saltPath = args.saltFile ?? `${dbPath}.salt`;
+      const salt = await loadOrCreateSalt(saltPath, args.role);
+      return { kind: 'passphrase', passphrase, salt };
+    }
+    case 'keychain': {
+      const service = args.keychainService ?? process.env.SHADE_KEYCHAIN_SERVICE ?? 'shade.storage';
+      const account = args.keychainAccount ?? process.env.SHADE_KEYCHAIN_ACCOUNT ?? 'default';
+      return {
+        kind: 'keychain', service, account,
+        createIfMissing: args.role === 'open-or-create',
+      };
+    }
+    case 'injected': {
+      const hex = args.injectedKeyHex ?? process.env.SHADE_STORAGE_KEY_HEX;
+      if (!hex) throw new Error('injected key required: pass --key-hex or set SHADE_STORAGE_KEY_HEX');
+      const key = hexToBytes(hex);
+      if (key.length !== 32) throw new Error(`injected key must be 32 bytes (got ${key.length})`);
+      return { kind: 'injected', key };
+    }
+  }
+}
+
+async function loadOrCreateSalt(saltPath: string, role: OpenKmArgs['role']): Promise<Uint8Array> {
+  if (existsSync(saltPath)) {
+    const buf = readFileSync(saltPath);
+    if (buf.length < 16) throw new Error(`salt file ${saltPath} is too short (need ≥ 16 bytes)`);
+    return new Uint8Array(buf);
+  }
+  if (role === 'open-existing') {
+    throw new Error(`salt file not found at ${saltPath} — re-run with the original salt or create new with migrate-storage`);
+  }
+  const fresh = new Uint8Array(16);
+  globalThis.crypto.getRandomValues(fresh);
+  mkdirSync(dirname(resolve(saltPath)), { recursive: true });
+  writeFileSync(saltPath, fresh, { mode: 0o600 });
+  console.log(`  • generated new salt at ${saltPath}`);
+  return fresh;
+}
+
+function hexToBytes(hex: string): Uint8Array {
+  const clean = hex.startsWith('0x') ? hex.slice(2) : hex;
+  if (clean.length % 2 !== 0) throw new Error('hex string must have even length');
+  const out = new Uint8Array(clean.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+
+export function parseStorageArgs(args: string[]): MigrateCliOptions & RotateCliOptions {
+  const out: MigrateCliOptions & RotateCliOptions = {
+    keySource: 'passphrase',
+    newKeySource: 'passphrase',
+  };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    switch (a) {
+      case '--db-path':         out.dbPath = args[++i]; break;
+      case '--key-source':      out.keySource = args[++i] as MigrateCliOptions['keySource']; break;
+      case '--passphrase':      out.passphrase = args[++i]; break;
+      case '--keychain-service': out.keychainService = args[++i]; break;
+      case '--keychain-account': out.keychainAccount = args[++i]; break;
+      case '--key-hex':         out.injectedKeyHex = args[++i]; break;
+      case '--salt-file':       out.saltFile = args[++i]; break;
+      case '--dry-run':         out.dryRun = true; break;
+      case '--keep-original':   out.keepOriginal = true; break;
+      case '--no-backup':       out.noBackup = true; break;
+      // rotation
+      case '--new-key-source':  out.newKeySource = args[++i] as RotateCliOptions['newKeySource']; break;
+      case '--new-passphrase':  out.newPassphrase = args[++i]; break;
+      case '--new-keychain-service': out.newKeychainService = args[++i]; break;
+      case '--new-keychain-account': out.newKeychainAccount = args[++i]; break;
+      case '--new-key-hex':     out.newInjectedKeyHex = args[++i]; break;
+      case '--new-salt-file':   out.newSaltFile = args[++i]; break;
+      default:
+        if (a?.startsWith('--')) throw new Error(`unknown flag: ${a}`);
+    }
+  }
+  return out;
+}

packages/shade-cli/templates/bun-server/README.md

@@ -39,8 +39,23 @@ curl -X POST http://localhost:3000/receive \
 
 Returns the decrypted plaintext.
 
+## Stream-state retention
+
+Resumable file transfers persist a per-stream record. The template runs
+a daily cron that drops anything idle for more than
+`SHADE_STREAM_RETENTION_DAYS` days (default **14**). Override at
+deploy:
+
+```bash
+SHADE_STREAM_RETENTION_DAYS=7 bun run start
+```
+
+See [`docs/streams.md`](../../../../docs/streams.md) § Retention for the
+full guidance and tuning per use case.
+
 ## Next steps
 
 - Wire a real delivery layer (WebSocket, HTTP push, etc.)
 - Run `shade dashboard` to watch live activity
 - Compare fingerprints with peers out-of-band before trusting sessions
+- Walk through [`docs/PRODUCTION-CHECKLIST.md`](../../../../docs/PRODUCTION-CHECKLIST.md) before going live

packages/shade-cli/templates/bun-server/src/index.ts

@@ -22,6 +22,28 @@ shade.onMessage((from, msg) => {
   console.log(`[${from}] ${msg}`);
 });
 
+// ─── Resumable-stream retention ──────────────────────────────────
+//
+// Drop stream-state records older than SHADE_STREAM_RETENTION_DAYS
+// (default 14d). See docs/streams.md § Retention. Override the
+// horizon with the env var; cron interval is fixed at 24h.
+const STREAM_RETENTION_DAYS = Number(process.env.SHADE_STREAM_RETENTION_DAYS ?? 14);
+const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+const HORIZON_MS = STREAM_RETENTION_DAYS * ONE_DAY_MS;
+
+async function pruneStreamStatesOnce(): Promise<void> {
+  try {
+    await shade.pruneStreamStates(Date.now() - HORIZON_MS);
+  } catch (err) {
+    console.error('[shade] pruneStreamStates failed:', err);
+  }
+}
+
+await pruneStreamStatesOnce();
+const streamPruneTimer = setInterval(pruneStreamStatesOnce, ONE_DAY_MS);
+// Don't keep the process alive for the timer alone.
+if (typeof streamPruneTimer.unref === 'function') streamPruneTimer.unref();
+
 const app = new Hono();
 
 app.get('/', (c) => c.text(`__PROJECT_NAME__ — Shade-enabled backend`));

packages/shade-cli/tests/cli.test.ts

@@ -71,6 +71,37 @@ describe('CLI: init command', () => {
     );
   });
 
+  test('init with --doctor runs diagnostics against the new project', async () => {
+    const port = 19500 + Math.floor(Math.random() * 200);
+    const app = createPrekeyServer({
+      crypto,
+      store: new MemoryPrekeyStore(),
+      disableRateLimit: true,
+    });
+    const server = Bun.serve({ port, fetch: app.fetch });
+
+    const logs: string[] = [];
+    const originalLog = console.log;
+    console.log = (...args) => logs.push(args.join(' '));
+
+    try {
+      await initCommand({
+        name: 'doc-app',
+        template: 'bun-server',
+        cwd: tmpDir,
+        prekeyServer: `http://localhost:${port}`,
+        runDoctor: true,
+      });
+    } finally {
+      console.log = originalLog;
+      server.stop();
+    }
+
+    const out = logs.join('\n');
+    expect(out).toContain('Shade doctor');
+    expect(out).toContain('Prekey server is reachable');
+  });
+
   test('chat-demo template scaffolds correctly', async () => {
     await initCommand({ name: 'chat', template: 'chat-demo', cwd: tmpDir });
 
@@ -81,6 +112,26 @@ describe('CLI: init command', () => {
     const alice = readFileSync(join(target, 'src/alice.ts'), 'utf-8');
     expect(alice).not.toContain('__PROJECT_NAME__');
   });
+
+  test('bun-server template wires the resumable-stream prune cron by default', async () => {
+    // V3.1 acceptance: a freshly-scaffolded bun-server must call
+    // shade.pruneStreamStates on startup + on a daily interval, with
+    // the SHADE_STREAM_RETENTION_DAYS env var as the override knob.
+    await initCommand({ name: 'cron-app', template: 'bun-server', cwd: tmpDir });
+
+    const indexSrc = readFileSync(
+      join(tmpDir, 'cron-app', 'src/index.ts'),
+      'utf-8',
+    );
+
+    expect(indexSrc).toContain('shade.pruneStreamStates(');
+    expect(indexSrc).toContain('SHADE_STREAM_RETENTION_DAYS');
+    expect(indexSrc).toContain('setInterval');
+    // Default horizon stays 14 days unless overridden.
+    expect(indexSrc).toMatch(/\?\?\s*14/);
+    // Cron timer must not keep the process alive on its own.
+    expect(indexSrc).toContain('.unref');
+  });
 });
 
 describe('CLI: config loading', () => {