@graphorin/store-sqlite-encrypted 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @graphorin/store-sqlite-encrypted
 
+## 0.7.0
+
+### Minor Changes
+
+- [#154](https://github.com/o-stepper/graphorin/pull/154) [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04) Thanks [@o-stepper](https://github.com/o-stepper)! - W-012: `encryptDatabase({ swap: true })` now probes for a live writer BEFORE touching the source and refuses with the new typed `EncryptSwapLiveWriterError` when another connection holds the database. The swap path renames the source file; a running server would keep writing into the renamed `.bak.<ts>` inode, silently diverging from the encrypted copy until `storage cleanup-backups` deletes those writes. The probe (a journal-mode switch, which sqlite3mc refuses with "database is locked" under any other open connection) restores WAL in `finally`; the probe-to-rename window remains a documented best-effort residual. CLI `--swap` help and the storage guide now state the stopped-server requirement.
+
+- [#154](https://github.com/o-stepper/graphorin/pull/154) [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04) Thanks [@o-stepper](https://github.com/o-stepper)! - W-072: every export map's `import` condition becomes `default`, and the Node floor rises to `>=22.12.0`.
+
+  CJS consumers previously hit a bewildering `ERR_PACKAGE_PATH_NOT_EXPORTED` instead of a clear ESM-only signal. With the `default` condition, plain `require('@graphorin/core')` works via Node's stable `require(esm)` - which shipped in 22.12, hence the engines bump across every workspace manifest (packages, examples, benchmarks, docs; enforced by the widened mvp-readiness sweep). No dual-instance hazard: there is no CJS build, `require()` returns the same ESM module instance. ESM consumers are unaffected (`default` serves both paths; `types` stays first). The pack gate now runs attw under the full `node16` profile (was `esm-only`) and adds a runtime `require(esm)` smoke against the packed tarballs. Installs on Node 22.0-22.11 with `engine-strict` will refuse - upgrade Node (see the migration guide).
+
+### Patch Changes
+
+- [#162](https://github.com/o-stepper/graphorin/pull/162) [`73b19ca`](https://github.com/o-stepper/graphorin/commit/73b19caeda388bda628a48138cb7d70b1db839a3) Thanks [@o-stepper](https://github.com/o-stepper)! - Remove phantom workspace dependencies that no source file imports: agent no longer depends on provider and observability, mcp/workflow/server no longer depend on observability, sessions no longer depends on security (and its memory edge moves to devDependencies where the single test import lives), skills no longer depends on tools. Dead tsdown `external` entries for the removed edges are gone too, so a future import can no longer build as external without a declared dependency. Consumer install graphs shrink accordingly; a new repo-wide `check-phantom-deps` CI gate keeps the manifest graph honest from here on.
+
+- [#164](https://github.com/o-stepper/graphorin/pull/164) [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00) Thanks [@o-stepper](https://github.com/o-stepper)! - Tarballs now ship `src/` so the published `dist/**/*.d.ts.map` files actually work (W-136): the maps referenced `../src/*.ts` that the `files` whitelist excluded, so go-to-definition fell back into `.d.ts` and the shipped maps were dead weight. The pack gate gains a `map-integrity` leg: every source referenced by a shipped map must resolve inside the tarball (or be embedded via `sourcesContent`), with an anti-vacuous guard - a package whose tsdown config emits declaration maps must contain a non-zero number of `.d.ts.map` files, so a cache-restored dist that silently dropped maps fails the gate instead of passing vacuously. `mvp-readiness` now requires `src` in every publishable `files` array.
+
+- Updated dependencies [[`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`832f22e`](https://github.com/o-stepper/graphorin/commit/832f22e570b8c3175c1adeb4c150070cbd131534), [`832f22e`](https://github.com/o-stepper/graphorin/commit/832f22e570b8c3175c1adeb4c150070cbd131534), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`832f22e`](https://github.com/o-stepper/graphorin/commit/832f22e570b8c3175c1adeb4c150070cbd131534), [`32bbd03`](https://github.com/o-stepper/graphorin/commit/32bbd03b588136a355e4b5ad6ac5e19b36b4d8ab), [`32bbd03`](https://github.com/o-stepper/graphorin/commit/32bbd03b588136a355e4b5ad6ac5e19b36b4d8ab), [`4ee256e`](https://github.com/o-stepper/graphorin/commit/4ee256e30fe9190cef6c48dc6785464757707156), [`73b19ca`](https://github.com/o-stepper/graphorin/commit/73b19caeda388bda628a48138cb7d70b1db839a3), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00)]:
+  - @graphorin/store-sqlite@0.7.0
+
+## 0.6.1
+
+### Patch Changes
+
+- [#142](https://github.com/o-stepper/graphorin/pull/142) [`436d6ca`](https://github.com/o-stepper/graphorin/commit/436d6ca5ebbd16df094e915682d3915c279a8430) Thanks [@o-stepper](https://github.com/o-stepper)! - Version constants and version-bearing strings now derive from each package's manifest at build time (`VERSION = pkg.version`; writer ids, client/server info, OTLP framework attributes, build-info metrics interpolate it). No behavioral change at the current version: the rendered strings are byte-identical. A release bump no longer edits source; the new `check-version-consistency` gate fails any reintroduced hardcoded framework version.
+
+- Updated dependencies [[`436d6ca`](https://github.com/o-stepper/graphorin/commit/436d6ca5ebbd16df094e915682d3915c279a8430)]:
+  - @graphorin/store-sqlite@0.6.1
+
 ## 0.6.0
 
 ### Patch Changes

package/README.md

@@ -7,14 +7,14 @@
 > encrypt / rekey / integrity-check runners that back the `graphorin storage`
 > CLI subcommand group.
 >
-> Project Graphorin · v0.6.0 · MIT License · © 2026 Oleksiy Stepurenko ·
+> Project Graphorin · v0.7.0 · MIT License · © 2026 Oleksiy Stepurenko ·
 > <https://github.com/o-stepper/graphorin>
 
 ---
 
 ## Status
 
-- **Published:** v0.6.0 (optional sub-pack)
+- **Published:** v0.7.0 (optional sub-pack)
 - **Default cipher:** `sqlcipher` (SQLCipher v4 compatible, `legacy=4`)
 - **Defaults:** encryption-at-rest is **OFF by default**. Opt in through
   `graphorin init --encrypted`.
@@ -159,4 +159,4 @@ MIT © 2026 Oleksiy Stepurenko
 
 ---
 
-**Project Graphorin** · v0.6.0 · MIT License · © 2026 Oleksiy Stepurenko · <https://github.com/o-stepper/graphorin>
+**Project Graphorin** · v0.7.0 · MIT License · © 2026 Oleksiy Stepurenko · <https://github.com/o-stepper/graphorin>

package/dist/encrypt.d.ts

@@ -21,6 +21,14 @@ interface EncryptDatabaseOptions {
    * integrity check passes. The original `sourcePath` is renamed to
    * `${sourcePath}.bak.${timestamp}` so an operator can recover.
    * Default `false` - the CLI does the swap explicitly.
+   *
+   * REQUIRES A STOPPED SERVER (W-012): a live writer keeps its file
+   * descriptor on the renamed `.bak` inode and every post-snapshot
+   * commit silently diverges from the new encrypted file (and is later
+   * deleted by `storage cleanup-backups`). A best-effort live-writer
+   * probe refuses the swap with {@link EncryptSwapLiveWriterError}
+   * when another connection holds the database; the probe-to-rename
+   * window remains a documented residual race.
    */
   readonly swap?: boolean;
   /**
@@ -54,7 +62,19 @@ interface EncryptDatabaseResult {
  *
  * @stable
  */
+/**
+ * Thrown when `encryptDatabase({ swap: true })` detects another live
+ * connection on the source database (W-012). The swap path renames the
+ * source file; a live writer would keep writing into the renamed
+ * `.bak.<ts>` inode and silently diverge from the encrypted copy.
+ *
+ * @stable
+ */
+declare class EncryptSwapLiveWriterError extends Error {
+  readonly sourcePath: string;
+  constructor(sourcePath: string, cause: unknown);
+}
 declare function encryptDatabase(options: EncryptDatabaseOptions): Promise<EncryptDatabaseResult>;
 //#endregion
-export { EncryptDatabaseOptions, EncryptDatabaseResult, encryptDatabase };
+export { EncryptDatabaseOptions, EncryptDatabaseResult, EncryptSwapLiveWriterError, encryptDatabase };
 //# sourceMappingURL=encrypt.d.ts.map

package/dist/encrypt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"encrypt.d.ts","names":[],"sources":["../src/encrypt.ts"],"sourcesContent":[],"mappings":";;;;;;;;;UAuCiB,sBAAA;;;;;;gCAMe;;oBAEZ;;;;;;;;;;;;;;;;;;;UAoBH,qBAAA;;;mBAGE;;;mBAC+C;;;;;;;;;;;;;;iBAY5C,eAAA,UACX,yBACR,QAAQ"}
+{"version":3,"file":"encrypt.d.ts","names":[],"sources":["../src/encrypt.ts"],"sourcesContent":[],"mappings":";;;;;;;;;UAuCiB,sBAAA;;;;;;gCAMe;;oBAEZ;;;;;;;;;;;;;;;;;;;;;;;;;;;UA4BH,qBAAA;;;mBAGE;;;mBAC+C;;;;;;;;;;;;;;;;;;;;;;cAoBrD,0BAAA,SAAmC,KAAA;;;;iBAc1B,eAAA,UACX,yBACR,QAAQ"}

package/dist/encrypt.js

@@ -34,6 +34,22 @@ import { isAbsolute, resolve } from "node:path";
 *
 * @stable
 */
+/**
+* Thrown when `encryptDatabase({ swap: true })` detects another live
+* connection on the source database (W-012). The swap path renames the
+* source file; a live writer would keep writing into the renamed
+* `.bak.<ts>` inode and silently diverge from the encrypted copy.
+*
+* @stable
+*/
+var EncryptSwapLiveWriterError = class extends Error {
+	sourcePath;
+	constructor(sourcePath, cause) {
+		super(`[graphorin/store-sqlite-encrypted] ${sourcePath} appears to be open by another process; stop the server before running storage encrypt with --swap (writes committed after the snapshot would land in the renamed .bak file and be lost).`, { cause });
+		this.name = "EncryptSwapLiveWriterError";
+		this.sourcePath = sourcePath;
+	}
+};
 async function encryptDatabase(options) {
 	const sourcePath = absolute(options.sourcePath);
 	const targetPath = absolute(options.targetPath);
@@ -45,6 +61,24 @@ async function encryptDatabase(options) {
 		unlinkSync(targetPath);
 	}
 	const Ctor = await loadCipherPeer();
+	if (options.swap === true) {
+		const probe = new Ctor(sourcePath);
+		let switched = false;
+		try {
+			try {
+				probe.pragma("journal_mode = DELETE");
+				switched = true;
+			} catch (err) {
+				if (isBusyError(err)) throw new EncryptSwapLiveWriterError(sourcePath, err);
+				throw err;
+			}
+		} finally {
+			if (switched) try {
+				probe.pragma("journal_mode = WAL");
+			} catch {}
+			if (probe.open) probe.close();
+		}
+	}
 	try {
 		const source = new Ctor(sourcePath, { readonly: true });
 		try {
@@ -112,7 +146,14 @@ async function encryptDatabase(options) {
 function absolute(p) {
 	return isAbsolute(p) ? p : resolve(p);
 }
+function isBusyError(err) {
+	if (typeof err !== "object" || err === null) return false;
+	const code = err.code;
+	if (typeof code === "string" && code.includes("SQLITE_BUSY")) return true;
+	const message = err.message;
+	return typeof message === "string" && /database is locked|busy/i.test(message);
+}
 
 //#endregion
-export { encryptDatabase };
+export { EncryptSwapLiveWriterError, encryptDatabase };
 //# sourceMappingURL=encrypt.js.map

package/dist/encrypt.js.map

@@ -1 +1 @@
-{"version":3,"file":"encrypt.js","names":["integrityCheck: { readonly ok: boolean; readonly rows: ReadonlyArray<string> }","swap: { readonly originalRenamedTo: string } | undefined"],"sources":["../src/encrypt.ts"],"sourcesContent":["/**\n * `encryptDatabase` - converts an unencrypted SQLite database file\n * into an encrypted one. Backs `graphorin storage encrypt` per\n * ADR-030 § 8.\n *\n * Strategy (CS-7): sqlite3mc ships **no** `sqlcipher_export` function\n * (verified against the real peer - the old ATTACH+export path threw\n * \"no such function\" on every real run), so the export is a\n * **checkpoint → file copy → in-place `PRAGMA rekey`** sequence:\n *\n *  1. open the plaintext source, `wal_checkpoint(TRUNCATE)`, close;\n *  2. byte-copy the file to the target (this trivially preserves every\n *     rowid, so FTS5 external-content mappings stay intact - CS-10);\n *  3. open the copy through the cipher peer with NO key, apply the\n *     cipher-selection pragmas, then `PRAGMA rekey = <key>` - sqlite3mc\n *     encrypts a plaintext database in place;\n *  4. re-open with the key and verify via `PRAGMA integrity_check`.\n *\n * @packageDocumentation\n */\n\nimport { existsSync, renameSync, unlinkSync } from 'node:fs';\nimport { isAbsolute, resolve } from 'node:path';\n\nimport {\n  DEFAULT_CIPHER,\n  type EncryptionCipher,\n  encodePassphraseForPragma,\n  pragmaSequenceForCipher,\n} from './cipher-config.js';\nimport { loadCipherPeer } from './cipher-peer.js';\nimport { createEncryptedConnection } from './connection.js';\nimport { cipherIntegrityCheck } from './integrity-check.js';\n\n/**\n * Options for {@link encryptDatabase}.\n *\n * @stable\n */\nexport interface EncryptDatabaseOptions {\n  /** Path to the existing unencrypted source DB. */\n  readonly sourcePath: string;\n  /** Path the encrypted output is written to. Must not exist. */\n  readonly targetPath: string;\n  /** Passphrase for the new encrypted DB. */\n  readonly passphrase: string | Buffer;\n  /** Cipher selection. Default `'sqlcipher'` (SQLCipher v4 compatible). */\n  readonly cipher?: EncryptionCipher;\n  /**\n   * If `true`, atomically rename `targetPath` -> `sourcePath` after the\n   * integrity check passes. The original `sourcePath` is renamed to\n   * `${sourcePath}.bak.${timestamp}` so an operator can recover.\n   * Default `false` - the CLI does the swap explicitly.\n   */\n  readonly swap?: boolean;\n  /**\n   * If `true`, overwrite an existing `targetPath` instead of failing.\n   * Default `false`.\n   */\n  readonly overwriteTarget?: boolean;\n}\n\n/**\n * Result of a successful {@link encryptDatabase} run.\n *\n * @stable\n */\nexport interface EncryptDatabaseResult {\n  readonly sourcePath: string;\n  readonly targetPath: string;\n  readonly cipher: EncryptionCipher;\n  readonly integrityCheck: { readonly ok: boolean; readonly rows: ReadonlyArray<string> };\n  readonly swap?: { readonly originalRenamedTo: string };\n}\n\n/**\n * Encrypts an unencrypted SQLite database. Returns once the target\n * file has been written and verified. Throws if the source is missing,\n * the target already exists (and `overwriteTarget` is unset), the\n * cipher peer is missing, or the integrity check fails.\n *\n * @stable\n */\nexport async function encryptDatabase(\n  options: EncryptDatabaseOptions,\n): Promise<EncryptDatabaseResult> {\n  const sourcePath = absolute(options.sourcePath);\n  const targetPath = absolute(options.targetPath);\n  const cipher = options.cipher ?? DEFAULT_CIPHER;\n\n  if (!existsSync(sourcePath)) {\n    throw new Error(`[graphorin/store-sqlite-encrypted] source DB not found: ${sourcePath}`);\n  }\n  if (sourcePath === targetPath) {\n    throw new Error(\n      '[graphorin/store-sqlite-encrypted] sourcePath and targetPath must differ. ' +\n        'Pass a temporary targetPath then enable `swap: true` to atomically replace the source.',\n    );\n  }\n  if (existsSync(targetPath)) {\n    if (options.overwriteTarget !== true) {\n      throw new Error(\n        `[graphorin/store-sqlite-encrypted] target DB already exists: ${targetPath}. ` +\n          'Pass `overwriteTarget: true` to replace it.',\n      );\n    }\n    unlinkSync(targetPath);\n  }\n\n  const Ctor = await loadCipherPeer();\n  try {\n    // 1+2. Online page-level copy via the driver's backup API\n    //    (store-05). The old checkpoint-close-then-copyFileSync left a\n    //    window in which a concurrent writer (a running daemon) could\n    //    commit WAL frames the byte-copy silently missed; `backup()`\n    //    is consistent under live writers, preserves rowids (FTS5\n    //    mappings survive), and includes WAL content.\n    const source = new Ctor(sourcePath, { readonly: true });\n    try {\n      await source.backup(targetPath);\n    } finally {\n      if (source.open) source.close();\n    }\n\n    // 3. In-place conversion: cipher pragmas first, then `rekey` -\n    //    sqlite3mc encrypts a plaintext database in place.\n    const target = new Ctor(targetPath);\n    try {\n      for (const pragma of pragmaSequenceForCipher(cipher)) {\n        target.pragma(pragma);\n      }\n      // sqlite3mc refuses `rekey` in WAL journal mode (real-peer\n      // verified) - drop to DELETE for the conversion, restore after.\n      target.pragma('journal_mode = DELETE');\n      const encodedKey = encodePassphraseForPragma(options.passphrase);\n      target.pragma(`rekey = ${encodedKey}`);\n      target.pragma('journal_mode = WAL');\n    } finally {\n      if (target.open) target.close();\n    }\n  } catch (err) {\n    if (existsSync(targetPath)) {\n      try {\n        unlinkSync(targetPath);\n      } catch {\n        // best-effort cleanup\n      }\n    }\n    throw new Error(\n      `[graphorin/store-sqlite-encrypted] encryption failed: ${(err as Error).message}`,\n      { cause: err },\n    );\n  }\n\n  const verify = await createEncryptedConnection({\n    path: targetPath,\n    skipSqliteVec: true,\n    disableWalHardening: true,\n    encryption: {\n      enabled: true,\n      cipher,\n      passphraseResolver: async () => options.passphrase,\n    },\n  });\n  let integrityCheck: { readonly ok: boolean; readonly rows: ReadonlyArray<string> };\n  try {\n    const result = cipherIntegrityCheck(verify);\n    integrityCheck = { ok: result.ok, rows: result.rows };\n  } finally {\n    verify.close();\n  }\n\n  if (!integrityCheck.ok) {\n    if (existsSync(targetPath)) {\n      try {\n        unlinkSync(targetPath);\n      } catch {\n        // best-effort cleanup\n      }\n    }\n    throw new Error(\n      '[graphorin/store-sqlite-encrypted] post-encrypt integrity check failed: ' +\n        integrityCheck.rows.join('; '),\n    );\n  }\n\n  let swap: { readonly originalRenamedTo: string } | undefined;\n  if (options.swap === true) {\n    const ts = Date.now();\n    const renamedTo = `${sourcePath}.bak.${ts}`;\n    renameSync(sourcePath, renamedTo);\n    renameSync(targetPath, sourcePath);\n    swap = Object.freeze({ originalRenamedTo: renamedTo });\n  }\n\n  const out: EncryptDatabaseResult = Object.freeze({\n    sourcePath,\n    targetPath: swap !== undefined ? sourcePath : targetPath,\n    cipher,\n    integrityCheck: Object.freeze(integrityCheck),\n    ...(swap !== undefined ? { swap } : {}),\n  });\n  return out;\n}\n\nfunction absolute(p: string): string {\n  return isAbsolute(p) ? p : resolve(p);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmFA,eAAsB,gBACpB,SACgC;CAChC,MAAM,aAAa,SAAS,QAAQ,WAAW;CAC/C,MAAM,aAAa,SAAS,QAAQ,WAAW;CAC/C,MAAM,SAAS,QAAQ,UAAU;AAEjC,KAAI,CAAC,WAAW,WAAW,CACzB,OAAM,IAAI,MAAM,2DAA2D,aAAa;AAE1F,KAAI,eAAe,WACjB,OAAM,IAAI,MACR,mKAED;AAEH,KAAI,WAAW,WAAW,EAAE;AAC1B,MAAI,QAAQ,oBAAoB,KAC9B,OAAM,IAAI,MACR,gEAAgE,WAAW,iDAE5E;AAEH,aAAW,WAAW;;CAGxB,MAAM,OAAO,MAAM,gBAAgB;AACnC,KAAI;EAOF,MAAM,SAAS,IAAI,KAAK,YAAY,EAAE,UAAU,MAAM,CAAC;AACvD,MAAI;AACF,SAAM,OAAO,OAAO,WAAW;YACvB;AACR,OAAI,OAAO,KAAM,QAAO,OAAO;;EAKjC,MAAM,SAAS,IAAI,KAAK,WAAW;AACnC,MAAI;AACF,QAAK,MAAM,UAAU,wBAAwB,OAAO,CAClD,QAAO,OAAO,OAAO;AAIvB,UAAO,OAAO,wBAAwB;GACtC,MAAM,aAAa,0BAA0B,QAAQ,WAAW;AAChE,UAAO,OAAO,WAAW,aAAa;AACtC,UAAO,OAAO,qBAAqB;YAC3B;AACR,OAAI,OAAO,KAAM,QAAO,OAAO;;UAE1B,KAAK;AACZ,MAAI,WAAW,WAAW,CACxB,KAAI;AACF,cAAW,WAAW;UAChB;AAIV,QAAM,IAAI,MACR,yDAA0D,IAAc,WACxE,EAAE,OAAO,KAAK,CACf;;CAGH,MAAM,SAAS,MAAM,0BAA0B;EAC7C,MAAM;EACN,eAAe;EACf,qBAAqB;EACrB,YAAY;GACV,SAAS;GACT;GACA,oBAAoB,YAAY,QAAQ;GACzC;EACF,CAAC;CACF,IAAIA;AACJ,KAAI;EACF,MAAM,SAAS,qBAAqB,OAAO;AAC3C,mBAAiB;GAAE,IAAI,OAAO;GAAI,MAAM,OAAO;GAAM;WAC7C;AACR,SAAO,OAAO;;AAGhB,KAAI,CAAC,eAAe,IAAI;AACtB,MAAI,WAAW,WAAW,CACxB,KAAI;AACF,cAAW,WAAW;UAChB;AAIV,QAAM,IAAI,MACR,6EACE,eAAe,KAAK,KAAK,KAAK,CACjC;;CAGH,IAAIC;AACJ,KAAI,QAAQ,SAAS,MAAM;EAEzB,MAAM,YAAY,GAAG,WAAW,OADrB,KAAK,KAAK;AAErB,aAAW,YAAY,UAAU;AACjC,aAAW,YAAY,WAAW;AAClC,SAAO,OAAO,OAAO,EAAE,mBAAmB,WAAW,CAAC;;AAUxD,QAPmC,OAAO,OAAO;EAC/C;EACA,YAAY,SAAS,SAAY,aAAa;EAC9C;EACA,gBAAgB,OAAO,OAAO,eAAe;EAC7C,GAAI,SAAS,SAAY,EAAE,MAAM,GAAG,EAAE;EACvC,CAAC;;AAIJ,SAAS,SAAS,GAAmB;AACnC,QAAO,WAAW,EAAE,GAAG,IAAI,QAAQ,EAAE"}
+{"version":3,"file":"encrypt.js","names":["integrityCheck: { readonly ok: boolean; readonly rows: ReadonlyArray<string> }","swap: { readonly originalRenamedTo: string } | undefined"],"sources":["../src/encrypt.ts"],"sourcesContent":["/**\n * `encryptDatabase` - converts an unencrypted SQLite database file\n * into an encrypted one. Backs `graphorin storage encrypt` per\n * ADR-030 § 8.\n *\n * Strategy (CS-7): sqlite3mc ships **no** `sqlcipher_export` function\n * (verified against the real peer - the old ATTACH+export path threw\n * \"no such function\" on every real run), so the export is a\n * **checkpoint → file copy → in-place `PRAGMA rekey`** sequence:\n *\n *  1. open the plaintext source, `wal_checkpoint(TRUNCATE)`, close;\n *  2. byte-copy the file to the target (this trivially preserves every\n *     rowid, so FTS5 external-content mappings stay intact - CS-10);\n *  3. open the copy through the cipher peer with NO key, apply the\n *     cipher-selection pragmas, then `PRAGMA rekey = <key>` - sqlite3mc\n *     encrypts a plaintext database in place;\n *  4. re-open with the key and verify via `PRAGMA integrity_check`.\n *\n * @packageDocumentation\n */\n\nimport { existsSync, renameSync, unlinkSync } from 'node:fs';\nimport { isAbsolute, resolve } from 'node:path';\n\nimport {\n  DEFAULT_CIPHER,\n  type EncryptionCipher,\n  encodePassphraseForPragma,\n  pragmaSequenceForCipher,\n} from './cipher-config.js';\nimport { loadCipherPeer } from './cipher-peer.js';\nimport { createEncryptedConnection } from './connection.js';\nimport { cipherIntegrityCheck } from './integrity-check.js';\n\n/**\n * Options for {@link encryptDatabase}.\n *\n * @stable\n */\nexport interface EncryptDatabaseOptions {\n  /** Path to the existing unencrypted source DB. */\n  readonly sourcePath: string;\n  /** Path the encrypted output is written to. Must not exist. */\n  readonly targetPath: string;\n  /** Passphrase for the new encrypted DB. */\n  readonly passphrase: string | Buffer;\n  /** Cipher selection. Default `'sqlcipher'` (SQLCipher v4 compatible). */\n  readonly cipher?: EncryptionCipher;\n  /**\n   * If `true`, atomically rename `targetPath` -> `sourcePath` after the\n   * integrity check passes. The original `sourcePath` is renamed to\n   * `${sourcePath}.bak.${timestamp}` so an operator can recover.\n   * Default `false` - the CLI does the swap explicitly.\n   *\n   * REQUIRES A STOPPED SERVER (W-012): a live writer keeps its file\n   * descriptor on the renamed `.bak` inode and every post-snapshot\n   * commit silently diverges from the new encrypted file (and is later\n   * deleted by `storage cleanup-backups`). A best-effort live-writer\n   * probe refuses the swap with {@link EncryptSwapLiveWriterError}\n   * when another connection holds the database; the probe-to-rename\n   * window remains a documented residual race.\n   */\n  readonly swap?: boolean;\n  /**\n   * If `true`, overwrite an existing `targetPath` instead of failing.\n   * Default `false`.\n   */\n  readonly overwriteTarget?: boolean;\n}\n\n/**\n * Result of a successful {@link encryptDatabase} run.\n *\n * @stable\n */\nexport interface EncryptDatabaseResult {\n  readonly sourcePath: string;\n  readonly targetPath: string;\n  readonly cipher: EncryptionCipher;\n  readonly integrityCheck: { readonly ok: boolean; readonly rows: ReadonlyArray<string> };\n  readonly swap?: { readonly originalRenamedTo: string };\n}\n\n/**\n * Encrypts an unencrypted SQLite database. Returns once the target\n * file has been written and verified. Throws if the source is missing,\n * the target already exists (and `overwriteTarget` is unset), the\n * cipher peer is missing, or the integrity check fails.\n *\n * @stable\n */\n/**\n * Thrown when `encryptDatabase({ swap: true })` detects another live\n * connection on the source database (W-012). The swap path renames the\n * source file; a live writer would keep writing into the renamed\n * `.bak.<ts>` inode and silently diverge from the encrypted copy.\n *\n * @stable\n */\nexport class EncryptSwapLiveWriterError extends Error {\n  readonly sourcePath: string;\n  constructor(sourcePath: string, cause: unknown) {\n    super(\n      `[graphorin/store-sqlite-encrypted] ${sourcePath} appears to be open by another process; ` +\n        'stop the server before running storage encrypt with --swap (writes committed after the ' +\n        'snapshot would land in the renamed .bak file and be lost).',\n      { cause },\n    );\n    this.name = 'EncryptSwapLiveWriterError';\n    this.sourcePath = sourcePath;\n  }\n}\n\nexport async function encryptDatabase(\n  options: EncryptDatabaseOptions,\n): Promise<EncryptDatabaseResult> {\n  const sourcePath = absolute(options.sourcePath);\n  const targetPath = absolute(options.targetPath);\n  const cipher = options.cipher ?? DEFAULT_CIPHER;\n\n  if (!existsSync(sourcePath)) {\n    throw new Error(`[graphorin/store-sqlite-encrypted] source DB not found: ${sourcePath}`);\n  }\n  if (sourcePath === targetPath) {\n    throw new Error(\n      '[graphorin/store-sqlite-encrypted] sourcePath and targetPath must differ. ' +\n        'Pass a temporary targetPath then enable `swap: true` to atomically replace the source.',\n    );\n  }\n  if (existsSync(targetPath)) {\n    if (options.overwriteTarget !== true) {\n      throw new Error(\n        `[graphorin/store-sqlite-encrypted] target DB already exists: ${targetPath}. ` +\n          'Pass `overwriteTarget: true` to replace it.',\n      );\n    }\n    unlinkSync(targetPath);\n  }\n\n  const Ctor = await loadCipherPeer();\n\n  // W-012: --swap renames the source out from under any live writer,\n  // so probe for one FIRST. Empirically (real sqlite3mc peer): a\n  // journal-mode switch is refused with \"database is locked\" while any\n  // other connection is open, making it a cheap liveness probe. The\n  // mode is restored in `finally` so a crash mid-probe cannot leave the\n  // file in DELETE mode. Best-effort: the probe-to-rename window stays.\n  if (options.swap === true) {\n    const probe = new Ctor(sourcePath);\n    let switched = false;\n    try {\n      try {\n        probe.pragma('journal_mode = DELETE');\n        switched = true;\n      } catch (err) {\n        if (isBusyError(err)) throw new EncryptSwapLiveWriterError(sourcePath, err);\n        throw err;\n      }\n    } finally {\n      if (switched) {\n        try {\n          probe.pragma('journal_mode = WAL');\n        } catch {\n          // The WAL restore is best-effort; the conversion below sets\n          // journal modes explicitly anyway.\n        }\n      }\n      if (probe.open) probe.close();\n    }\n  }\n\n  try {\n    // 1+2. Online page-level copy via the driver's backup API\n    //    (store-05). The old checkpoint-close-then-copyFileSync left a\n    //    window in which a concurrent writer (a running daemon) could\n    //    commit WAL frames the byte-copy silently missed; `backup()`\n    //    is consistent under live writers, preserves rowids (FTS5\n    //    mappings survive), and includes WAL content.\n    const source = new Ctor(sourcePath, { readonly: true });\n    try {\n      await source.backup(targetPath);\n    } finally {\n      if (source.open) source.close();\n    }\n\n    // 3. In-place conversion: cipher pragmas first, then `rekey` -\n    //    sqlite3mc encrypts a plaintext database in place.\n    const target = new Ctor(targetPath);\n    try {\n      for (const pragma of pragmaSequenceForCipher(cipher)) {\n        target.pragma(pragma);\n      }\n      // sqlite3mc refuses `rekey` in WAL journal mode (real-peer\n      // verified) - drop to DELETE for the conversion, restore after.\n      target.pragma('journal_mode = DELETE');\n      const encodedKey = encodePassphraseForPragma(options.passphrase);\n      target.pragma(`rekey = ${encodedKey}`);\n      target.pragma('journal_mode = WAL');\n    } finally {\n      if (target.open) target.close();\n    }\n  } catch (err) {\n    if (existsSync(targetPath)) {\n      try {\n        unlinkSync(targetPath);\n      } catch {\n        // best-effort cleanup\n      }\n    }\n    throw new Error(\n      `[graphorin/store-sqlite-encrypted] encryption failed: ${(err as Error).message}`,\n      { cause: err },\n    );\n  }\n\n  const verify = await createEncryptedConnection({\n    path: targetPath,\n    skipSqliteVec: true,\n    disableWalHardening: true,\n    encryption: {\n      enabled: true,\n      cipher,\n      passphraseResolver: async () => options.passphrase,\n    },\n  });\n  let integrityCheck: { readonly ok: boolean; readonly rows: ReadonlyArray<string> };\n  try {\n    const result = cipherIntegrityCheck(verify);\n    integrityCheck = { ok: result.ok, rows: result.rows };\n  } finally {\n    verify.close();\n  }\n\n  if (!integrityCheck.ok) {\n    if (existsSync(targetPath)) {\n      try {\n        unlinkSync(targetPath);\n      } catch {\n        // best-effort cleanup\n      }\n    }\n    throw new Error(\n      '[graphorin/store-sqlite-encrypted] post-encrypt integrity check failed: ' +\n        integrityCheck.rows.join('; '),\n    );\n  }\n\n  let swap: { readonly originalRenamedTo: string } | undefined;\n  if (options.swap === true) {\n    const ts = Date.now();\n    const renamedTo = `${sourcePath}.bak.${ts}`;\n    renameSync(sourcePath, renamedTo);\n    renameSync(targetPath, sourcePath);\n    swap = Object.freeze({ originalRenamedTo: renamedTo });\n  }\n\n  const out: EncryptDatabaseResult = Object.freeze({\n    sourcePath,\n    targetPath: swap !== undefined ? sourcePath : targetPath,\n    cipher,\n    integrityCheck: Object.freeze(integrityCheck),\n    ...(swap !== undefined ? { swap } : {}),\n  });\n  return out;\n}\n\nfunction absolute(p: string): string {\n  return isAbsolute(p) ? p : resolve(p);\n}\n\nfunction isBusyError(err: unknown): boolean {\n  if (typeof err !== 'object' || err === null) return false;\n  const code = (err as { code?: unknown }).code;\n  if (typeof code === 'string' && code.includes('SQLITE_BUSY')) return true;\n  const message = (err as { message?: unknown }).message;\n  return typeof message === 'string' && /database is locked|busy/i.test(message);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmGA,IAAa,6BAAb,cAAgD,MAAM;CACpD,AAAS;CACT,YAAY,YAAoB,OAAgB;AAC9C,QACE,sCAAsC,WAAW,4LAGjD,EAAE,OAAO,CACV;AACD,OAAK,OAAO;AACZ,OAAK,aAAa;;;AAItB,eAAsB,gBACpB,SACgC;CAChC,MAAM,aAAa,SAAS,QAAQ,WAAW;CAC/C,MAAM,aAAa,SAAS,QAAQ,WAAW;CAC/C,MAAM,SAAS,QAAQ,UAAU;AAEjC,KAAI,CAAC,WAAW,WAAW,CACzB,OAAM,IAAI,MAAM,2DAA2D,aAAa;AAE1F,KAAI,eAAe,WACjB,OAAM,IAAI,MACR,mKAED;AAEH,KAAI,WAAW,WAAW,EAAE;AAC1B,MAAI,QAAQ,oBAAoB,KAC9B,OAAM,IAAI,MACR,gEAAgE,WAAW,iDAE5E;AAEH,aAAW,WAAW;;CAGxB,MAAM,OAAO,MAAM,gBAAgB;AAQnC,KAAI,QAAQ,SAAS,MAAM;EACzB,MAAM,QAAQ,IAAI,KAAK,WAAW;EAClC,IAAI,WAAW;AACf,MAAI;AACF,OAAI;AACF,UAAM,OAAO,wBAAwB;AACrC,eAAW;YACJ,KAAK;AACZ,QAAI,YAAY,IAAI,CAAE,OAAM,IAAI,2BAA2B,YAAY,IAAI;AAC3E,UAAM;;YAEA;AACR,OAAI,SACF,KAAI;AACF,UAAM,OAAO,qBAAqB;WAC5B;AAKV,OAAI,MAAM,KAAM,OAAM,OAAO;;;AAIjC,KAAI;EAOF,MAAM,SAAS,IAAI,KAAK,YAAY,EAAE,UAAU,MAAM,CAAC;AACvD,MAAI;AACF,SAAM,OAAO,OAAO,WAAW;YACvB;AACR,OAAI,OAAO,KAAM,QAAO,OAAO;;EAKjC,MAAM,SAAS,IAAI,KAAK,WAAW;AACnC,MAAI;AACF,QAAK,MAAM,UAAU,wBAAwB,OAAO,CAClD,QAAO,OAAO,OAAO;AAIvB,UAAO,OAAO,wBAAwB;GACtC,MAAM,aAAa,0BAA0B,QAAQ,WAAW;AAChE,UAAO,OAAO,WAAW,aAAa;AACtC,UAAO,OAAO,qBAAqB;YAC3B;AACR,OAAI,OAAO,KAAM,QAAO,OAAO;;UAE1B,KAAK;AACZ,MAAI,WAAW,WAAW,CACxB,KAAI;AACF,cAAW,WAAW;UAChB;AAIV,QAAM,IAAI,MACR,yDAA0D,IAAc,WACxE,EAAE,OAAO,KAAK,CACf;;CAGH,MAAM,SAAS,MAAM,0BAA0B;EAC7C,MAAM;EACN,eAAe;EACf,qBAAqB;EACrB,YAAY;GACV,SAAS;GACT;GACA,oBAAoB,YAAY,QAAQ;GACzC;EACF,CAAC;CACF,IAAIA;AACJ,KAAI;EACF,MAAM,SAAS,qBAAqB,OAAO;AAC3C,mBAAiB;GAAE,IAAI,OAAO;GAAI,MAAM,OAAO;GAAM;WAC7C;AACR,SAAO,OAAO;;AAGhB,KAAI,CAAC,eAAe,IAAI;AACtB,MAAI,WAAW,WAAW,CACxB,KAAI;AACF,cAAW,WAAW;UAChB;AAIV,QAAM,IAAI,MACR,6EACE,eAAe,KAAK,KAAK,KAAK,CACjC;;CAGH,IAAIC;AACJ,KAAI,QAAQ,SAAS,MAAM;EAEzB,MAAM,YAAY,GAAG,WAAW,OADrB,KAAK,KAAK;AAErB,aAAW,YAAY,UAAU;AACjC,aAAW,YAAY,WAAW;AAClC,SAAO,OAAO,OAAO,EAAE,mBAAmB,WAAW,CAAC;;AAUxD,QAPmC,OAAO,OAAO;EAC/C;EACA,YAAY,SAAS,SAAY,aAAa;EAC9C;EACA,gBAAgB,OAAO,OAAO,eAAe;EAC7C,GAAI,SAAS,SAAY,EAAE,MAAM,GAAG,EAAE;EACvC,CAAC;;AAIJ,SAAS,SAAS,GAAmB;AACnC,QAAO,WAAW,EAAE,GAAG,IAAI,QAAQ,EAAE;;AAGvC,SAAS,YAAY,KAAuB;AAC1C,KAAI,OAAO,QAAQ,YAAY,QAAQ,KAAM,QAAO;CACpD,MAAM,OAAQ,IAA2B;AACzC,KAAI,OAAO,SAAS,YAAY,KAAK,SAAS,cAAc,CAAE,QAAO;CACrE,MAAM,UAAW,IAA8B;AAC/C,QAAO,OAAO,YAAY,YAAY,2BAA2B,KAAK,QAAQ"}

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { DEFAULT_CIPHER, EncryptionCipher, encodePassphraseForPragma, pragmaSequenceForCipher } from "./cipher-config.js";
 import { EncryptedStorePeerMissingError, _resetCipherPeerCacheForTesting, _setCipherPeerForTesting, loadCipherPeer } from "./cipher-peer.js";
 import { createEncryptedConnection } from "./connection.js";
-import { EncryptDatabaseOptions, EncryptDatabaseResult, encryptDatabase } from "./encrypt.js";
+import { EncryptDatabaseOptions, EncryptDatabaseResult, EncryptSwapLiveWriterError, encryptDatabase } from "./encrypt.js";
 import { CipherIntegrityCheckResult, cipherIntegrityCheck } from "./integrity-check.js";
 import { RekeyDatabaseOptions, RekeyDatabaseResult, rekeyDatabase } from "./rekey.js";
 
@@ -44,8 +44,7 @@ import { RekeyDatabaseOptions, RekeyDatabaseResult, rekeyDatabase } from "./reke
  *
  * @packageDocumentation
  */
-/** Canonical version constant. Mirrors the `package.json` version. */
-declare const VERSION = "0.6.0";
+declare const VERSION: string;
 //#endregion
-export { type CipherIntegrityCheckResult, DEFAULT_CIPHER, type EncryptDatabaseOptions, type EncryptDatabaseResult, EncryptedStorePeerMissingError, type EncryptionCipher, type RekeyDatabaseOptions, type RekeyDatabaseResult, VERSION, _resetCipherPeerCacheForTesting, _setCipherPeerForTesting, cipherIntegrityCheck, createEncryptedConnection, encodePassphraseForPragma, encryptDatabase, loadCipherPeer, pragmaSequenceForCipher, rekeyDatabase };
+export { type CipherIntegrityCheckResult, DEFAULT_CIPHER, type EncryptDatabaseOptions, type EncryptDatabaseResult, EncryptSwapLiveWriterError, EncryptedStorePeerMissingError, type EncryptionCipher, type RekeyDatabaseOptions, type RekeyDatabaseResult, VERSION, _resetCipherPeerCacheForTesting, _setCipherPeerForTesting, cipherIntegrityCheck, createEncryptedConnection, encodePassphraseForPragma, encryptDatabase, loadCipherPeer, pragmaSequenceForCipher, rekeyDatabase };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;AAuCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAAa,OAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;AAyCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAAa"}

package/dist/index.js

@@ -1,8 +1,9 @@
+import { version } from "./package.js";
 import { DEFAULT_CIPHER, encodePassphraseForPragma, pragmaSequenceForCipher } from "./cipher-config.js";
 import { EncryptedStorePeerMissingError, _resetCipherPeerCacheForTesting, _setCipherPeerForTesting, loadCipherPeer } from "./cipher-peer.js";
 import { createEncryptedConnection } from "./connection.js";
 import { cipherIntegrityCheck } from "./integrity-check.js";
-import { encryptDatabase } from "./encrypt.js";
+import { EncryptSwapLiveWriterError, encryptDatabase } from "./encrypt.js";
 import { rekeyDatabase } from "./rekey.js";
 
 //#region src/index.ts
@@ -43,9 +44,9 @@ import { rekeyDatabase } from "./rekey.js";
 *
 * @packageDocumentation
 */
-/** Canonical version constant. Mirrors the `package.json` version. */
-const VERSION = "0.6.0";
+/** Canonical version constant, derived from `package.json` at build time. */
+const VERSION = version;
 
 //#endregion
-export { DEFAULT_CIPHER, EncryptedStorePeerMissingError, VERSION, _resetCipherPeerCacheForTesting, _setCipherPeerForTesting, cipherIntegrityCheck, createEncryptedConnection, encodePassphraseForPragma, encryptDatabase, loadCipherPeer, pragmaSequenceForCipher, rekeyDatabase };
+export { DEFAULT_CIPHER, EncryptSwapLiveWriterError, EncryptedStorePeerMissingError, VERSION, _resetCipherPeerCacheForTesting, _setCipherPeerForTesting, cipherIntegrityCheck, createEncryptedConnection, encodePassphraseForPragma, encryptDatabase, loadCipherPeer, pragmaSequenceForCipher, rekeyDatabase };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @graphorin/store-sqlite-encrypted - optional encryption-at-rest\n * sub-pack for the Graphorin framework's default SQLite store.\n *\n * Installing this package pulls in the cipher peer driver\n * (`better-sqlite3-multiple-ciphers@^12.9.0`), which is a drop-in fork\n * of `better-sqlite3` that bundles the SQLite3MultipleCiphers\n * extension (SQLCipher v4 / wxSQLite3 / AES-256-CBC / AES-128-CBC /\n * RC4 cipher modes).\n *\n * The package exposes:\n *\n *  - {@link createEncryptedConnection} - convenience wrapper around\n *    `openConnection` from `@graphorin/store-sqlite/connection` that\n *    pre-loads the cipher peer.\n *  - {@link encryptDatabase} - converts an unencrypted SQLite file\n *    into an encrypted one. Backs `graphorin storage encrypt`.\n *  - {@link rekeyDatabase} - re-keys an already encrypted file. Backs\n *    `graphorin storage rekey`.\n *  - {@link cipherIntegrityCheck} - runs `PRAGMA cipher_integrity_\n *    check`. Used by the triggers daemon's daily verification cron\n *    and the `/v1/health/storage` endpoint.\n *  - {@link DEFAULT_CIPHER}, {@link pragmaSequenceForCipher},\n *    {@link encodePassphraseForPragma} - cipher-config helpers shared\n *    by the runners and consumable for advanced setups.\n *  - {@link loadCipherPeer} / {@link EncryptedStorePeerMissingError} -\n *    explicit peer-loader surface for callers that want to fail-fast\n *    at startup before opening the DB.\n *\n * Defaults follow ADR-030 / DEC-129:\n *  - Cipher: `'sqlcipher'` (SQLCipher v4 compatible, `legacy=4`).\n *  - Default OFF; opt-in through `graphorin init --encrypted`.\n *  - audit.db is ALWAYS encrypted regardless of this opt-in\n *    (DEC-124); this package satisfies that requirement too.\n *\n * @packageDocumentation\n */\n\n/** Canonical version constant. Mirrors the `package.json` version. */\nexport const VERSION = '0.6.0';\n\nexport {\n  DEFAULT_CIPHER,\n  type EncryptionCipher,\n  encodePassphraseForPragma,\n  pragmaSequenceForCipher,\n} from './cipher-config.js';\nexport {\n  _resetCipherPeerCacheForTesting,\n  _setCipherPeerForTesting,\n  EncryptedStorePeerMissingError,\n  loadCipherPeer,\n} from './cipher-peer.js';\nexport { createEncryptedConnection } from './connection.js';\nexport {\n  type EncryptDatabaseOptions,\n  type EncryptDatabaseResult,\n  encryptDatabase,\n} from './encrypt.js';\nexport { type CipherIntegrityCheckResult, cipherIntegrityCheck } from './integrity-check.js';\nexport {\n  type RekeyDatabaseOptions,\n  type RekeyDatabaseResult,\n  rekeyDatabase,\n} from './rekey.js';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,MAAa,UAAU"}
+{"version":3,"file":"index.js","names":["VERSION: string","pkg.version"],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @graphorin/store-sqlite-encrypted - optional encryption-at-rest\n * sub-pack for the Graphorin framework's default SQLite store.\n *\n * Installing this package pulls in the cipher peer driver\n * (`better-sqlite3-multiple-ciphers@^12.9.0`), which is a drop-in fork\n * of `better-sqlite3` that bundles the SQLite3MultipleCiphers\n * extension (SQLCipher v4 / wxSQLite3 / AES-256-CBC / AES-128-CBC /\n * RC4 cipher modes).\n *\n * The package exposes:\n *\n *  - {@link createEncryptedConnection} - convenience wrapper around\n *    `openConnection` from `@graphorin/store-sqlite/connection` that\n *    pre-loads the cipher peer.\n *  - {@link encryptDatabase} - converts an unencrypted SQLite file\n *    into an encrypted one. Backs `graphorin storage encrypt`.\n *  - {@link rekeyDatabase} - re-keys an already encrypted file. Backs\n *    `graphorin storage rekey`.\n *  - {@link cipherIntegrityCheck} - runs `PRAGMA cipher_integrity_\n *    check`. Used by the triggers daemon's daily verification cron\n *    and the `/v1/health/storage` endpoint.\n *  - {@link DEFAULT_CIPHER}, {@link pragmaSequenceForCipher},\n *    {@link encodePassphraseForPragma} - cipher-config helpers shared\n *    by the runners and consumable for advanced setups.\n *  - {@link loadCipherPeer} / {@link EncryptedStorePeerMissingError} -\n *    explicit peer-loader surface for callers that want to fail-fast\n *    at startup before opening the DB.\n *\n * Defaults follow ADR-030 / DEC-129:\n *  - Cipher: `'sqlcipher'` (SQLCipher v4 compatible, `legacy=4`).\n *  - Default OFF; opt-in through `graphorin init --encrypted`.\n *  - audit.db is ALWAYS encrypted regardless of this opt-in\n *    (DEC-124); this package satisfies that requirement too.\n *\n * @packageDocumentation\n */\n\n/** Canonical version constant, derived from `package.json` at build time. */\nimport pkg from '../package.json' with { type: 'json' };\n\nexport const VERSION: string = pkg.version;\n\nexport {\n  DEFAULT_CIPHER,\n  type EncryptionCipher,\n  encodePassphraseForPragma,\n  pragmaSequenceForCipher,\n} from './cipher-config.js';\nexport {\n  _resetCipherPeerCacheForTesting,\n  _setCipherPeerForTesting,\n  EncryptedStorePeerMissingError,\n  loadCipherPeer,\n} from './cipher-peer.js';\nexport { createEncryptedConnection } from './connection.js';\nexport {\n  type EncryptDatabaseOptions,\n  type EncryptDatabaseResult,\n  EncryptSwapLiveWriterError,\n  encryptDatabase,\n} from './encrypt.js';\nexport { type CipherIntegrityCheckResult, cipherIntegrityCheck } from './integrity-check.js';\nexport {\n  type RekeyDatabaseOptions,\n  type RekeyDatabaseResult,\n  rekeyDatabase,\n} from './rekey.js';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,MAAaA,UAAkBC"}

package/dist/package.js

@@ -0,0 +1,6 @@
+//#region package.json
+var version = "0.7.0";
+
+//#endregion
+export { version };
+//# sourceMappingURL=package.js.map

package/dist/package.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.js","names":[],"sources":["../package.json"],"sourcesContent":["{\n  \"name\": \"@graphorin/store-sqlite-encrypted\",\n  \"version\": \"0.7.0\",\n  \"description\": \"Optional encryption-at-rest sub-pack for the Graphorin framework's default SQLite store. Pulls in `better-sqlite3-multiple-ciphers@^12.9.0` (a drop-in fork of `better-sqlite3` that bundles SQLite3MultipleCiphers / SQLCipher v4), exposes the `encryptDatabase` / `rekeyDatabase` / `cipherIntegrityCheck` runners that back `graphorin storage encrypt` / `graphorin storage rekey` / `graphorin storage status`, and provides a `createEncryptedConnection` convenience wrapper around `@graphorin/store-sqlite/connection` for callers that bypass the CLI. Default cipher: `sqlcipher` (SQLCipher v4 compatible). Opt-in alternatives: `chacha20` (the peer default), `aes256cbc`, `aes128cbc`, `rc4`. Default OFF; opt-in through `graphorin init --encrypted` per ADR-030 / DEC-129. Created and maintained by Oleksiy Stepurenko.\",\n  \"license\": \"MIT\",\n  \"author\": \"Oleksiy Stepurenko\",\n  \"homepage\": \"https://github.com/o-stepper/graphorin/tree/main/packages/store-sqlite-encrypted\",\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/o-stepper/graphorin.git\",\n    \"directory\": \"packages/store-sqlite-encrypted\"\n  },\n  \"bugs\": {\n    \"url\": \"https://github.com/o-stepper/graphorin/issues\"\n  },\n  \"keywords\": [\n    \"graphorin\",\n    \"ai\",\n    \"agents\",\n    \"framework\",\n    \"sqlite\",\n    \"sqlcipher\",\n    \"encryption\",\n    \"encryption-at-rest\",\n    \"better-sqlite3-multiple-ciphers\",\n    \"rekey\",\n    \"vacuum-into\"\n  ],\n  \"type\": \"module\",\n  \"engines\": {\n    \"node\": \">=22.12.0\"\n  },\n  \"main\": \"./dist/index.js\",\n  \"module\": \"./dist/index.js\",\n  \"types\": \"./dist/index.d.ts\",\n  \"sideEffects\": false,\n  \"exports\": {\n    \".\": {\n      \"types\": \"./dist/index.d.ts\",\n      \"default\": \"./dist/index.js\"\n    },\n    \"./package.json\": \"./package.json\"\n  },\n  \"files\": [\n    \"dist\",\n    \"src\",\n    \"README.md\",\n    \"CHANGELOG.md\",\n    \"LICENSE\"\n  ],\n  \"scripts\": {\n    \"build\": \"tsdown\",\n    \"typecheck\": \"tsc --noEmit && tsc -p tsconfig.tests.json\",\n    \"test\": \"vitest run\",\n    \"lint\": \"biome check .\",\n    \"clean\": \"rimraf dist .turbo *.tsbuildinfo\"\n  },\n  \"dependencies\": {\n    \"@graphorin/store-sqlite\": \"workspace:*\"\n  },\n  \"peerDependencies\": {\n    \"better-sqlite3-multiple-ciphers\": \"^12.9.0\"\n  },\n  \"peerDependenciesMeta\": {\n    \"better-sqlite3-multiple-ciphers\": {\n      \"optional\": false\n    }\n  },\n  \"publishConfig\": {\n    \"access\": \"public\",\n    \"provenance\": true\n  },\n  \"devDependencies\": {\n    \"@types/better-sqlite3\": \"^7.6.13\"\n  }\n}\n"],"mappings":";cAEa"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphorin/store-sqlite-encrypted",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Optional encryption-at-rest sub-pack for the Graphorin framework's default SQLite store. Pulls in `better-sqlite3-multiple-ciphers@^12.9.0` (a drop-in fork of `better-sqlite3` that bundles SQLite3MultipleCiphers / SQLCipher v4), exposes the `encryptDatabase` / `rekeyDatabase` / `cipherIntegrityCheck` runners that back `graphorin storage encrypt` / `graphorin storage rekey` / `graphorin storage status`, and provides a `createEncryptedConnection` convenience wrapper around `@graphorin/store-sqlite/connection` for callers that bypass the CLI. Default cipher: `sqlcipher` (SQLCipher v4 compatible). Opt-in alternatives: `chacha20` (the peer default), `aes256cbc`, `aes128cbc`, `rc4`. Default OFF; opt-in through `graphorin init --encrypted` per ADR-030 / DEC-129. Created and maintained by Oleksiy Stepurenko.",
   "license": "MIT",
   "author": "Oleksiy Stepurenko",
@@ -28,7 +28,7 @@
   ],
   "type": "module",
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.12.0"
   },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -37,18 +37,19 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "default": "./dist/index.js"
     },
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
+    "src",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
   ],
   "dependencies": {
-    "@graphorin/store-sqlite": "0.6.0"
+    "@graphorin/store-sqlite": "0.7.0"
   },
   "peerDependencies": {
     "better-sqlite3-multiple-ciphers": "^12.9.0"
@@ -63,8 +64,7 @@
     "provenance": true
   },
   "devDependencies": {
-    "@types/better-sqlite3": "^7.6.13",
-    "@graphorin/security": "0.6.0"
+    "@types/better-sqlite3": "^7.6.13"
   },
   "scripts": {
     "build": "tsdown",

package/src/cipher-config.ts

@@ -0,0 +1,80 @@
+/**
+ * Cipher selection + passphrase encoding helpers shared by the
+ * `createEncryptedConnection`, `encryptDatabase`, and `rekeyDatabase`
+ * runners. The cipher peer reads the passphrase via `PRAGMA key`; this
+ * module owns the SQL-literal escaping path so all three runners agree.
+ *
+ * @packageDocumentation
+ */
+
+import type { EncryptionCipher } from '@graphorin/store-sqlite/encryption';
+
+export type { EncryptionCipher };
+
+/**
+ * Default cipher. Matches ADR-030 § 2 - SQLCipher v4 compatible
+ * (AES-256-CBC + HMAC-SHA1, `legacy=4` parameter set).
+ *
+ * @stable
+ */
+export const DEFAULT_CIPHER: EncryptionCipher = 'sqlcipher';
+
+/**
+ * Cipher-specific PRAGMAs that must be applied **before**
+ * `PRAGMA key = ...` for SQLite3MultipleCiphers to interpret the key
+ * correctly. The list mirrors the upstream documentation.
+ *
+ * @internal
+ */
+const CIPHER_PRAGMAS: Readonly<Record<EncryptionCipher, ReadonlyArray<string>>> = Object.freeze({
+  sqlcipher: Object.freeze(["cipher = 'sqlcipher'", 'legacy = 4']),
+  chacha20: Object.freeze(["cipher = 'chacha20'"]),
+  aes256cbc: Object.freeze(["cipher = 'aes256cbc'"]),
+  aes128cbc: Object.freeze(["cipher = 'aes128cbc'"]),
+  rc4: Object.freeze(["cipher = 'rc4'"]),
+});
+
+/**
+ * Returns the PRAGMA statements that select a cipher. The list is
+ * applied **before** `PRAGMA key = ...` so the cipher peer knows which
+ * KDF / mode to use when interpreting the key bytes.
+ *
+ * @stable
+ */
+export function pragmaSequenceForCipher(cipher: EncryptionCipher): ReadonlyArray<string> {
+  const seq = CIPHER_PRAGMAS[cipher];
+  if (seq === undefined) {
+    throw new TypeError(
+      `[graphorin/store-sqlite-encrypted] unknown cipher '${String(cipher)}'. ` +
+        `Supported: ${Object.keys(CIPHER_PRAGMAS).join(', ')}.`,
+    );
+  }
+  return seq;
+}
+
+/**
+ * SQL-literal-encodes a passphrase for use as the right-hand side of
+ * `PRAGMA key = ...`.
+ *
+ * - String input is wrapped in single quotes with internal `'` doubled
+ *   per the SQL specification.
+ * - Buffer input is encoded as the cipher peer's `x'<hex>'` blob form
+ *   so binary keys round-trip exactly.
+ *
+ * Empty inputs are rejected at this layer so callers cannot
+ * accidentally open an unencrypted DB with an empty key.
+ *
+ * @stable
+ */
+export function encodePassphraseForPragma(value: string | Buffer): string {
+  if (typeof value === 'string') {
+    if (value.length === 0) {
+      throw new Error('[graphorin/store-sqlite-encrypted] passphrase is empty');
+    }
+    return `'${value.replace(/'/g, "''")}'`;
+  }
+  if (value.length === 0) {
+    throw new Error('[graphorin/store-sqlite-encrypted] passphrase buffer is empty');
+  }
+  return `x'${value.toString('hex')}'`;
+}

package/src/cipher-peer.ts

@@ -0,0 +1,77 @@
+/**
+ * Loads the `better-sqlite3-multiple-ciphers` cipher peer driver. The
+ * peer is declared `optional: false` in this package's `package.json`
+ * (the whole point of installing this sub-pack is to opt in to
+ * encryption-at-rest), but we still wrap the import in a friendly
+ * fail-fast helper so consumers see an actionable error rather than a
+ * raw `ERR_MODULE_NOT_FOUND`.
+ *
+ * The peer is loaded lazily - importing this package on its own does
+ * NOT load the native addon, so callers that only inspect the public
+ * helpers (e.g. for documentation generation) pay no native-load cost.
+ *
+ * @packageDocumentation
+ */
+
+import type { BetterSqlite3Constructor } from '@graphorin/store-sqlite/connection';
+
+/**
+ * Raised when the cipher peer driver cannot be loaded. Distinct from
+ * the matching `CipherPeerMissingError` in `@graphorin/store-sqlite/
+ * encryption` so consumers can catch the two layers independently.
+ *
+ * @stable
+ */
+export class EncryptedStorePeerMissingError extends Error {
+  override readonly name = 'EncryptedStorePeerMissingError';
+}
+
+/** @internal */
+let CACHED_CTOR: BetterSqlite3Constructor | null = null;
+
+/**
+ * Loads `better-sqlite3-multiple-ciphers`. The result is cached for
+ * the lifetime of the process so repeat callers (encrypt + rekey +
+ * connection-open in the same process) share one native handle.
+ *
+ * @stable
+ */
+export async function loadCipherPeer(): Promise<BetterSqlite3Constructor> {
+  if (CACHED_CTOR !== null) return CACHED_CTOR;
+  try {
+    const mod = (await import('better-sqlite3-multiple-ciphers')) as unknown as {
+      default: BetterSqlite3Constructor;
+    };
+    CACHED_CTOR = mod.default;
+    return CACHED_CTOR;
+  } catch (err) {
+    throw new EncryptedStorePeerMissingError(
+      "the cipher peer 'better-sqlite3-multiple-ciphers' could not be loaded. " +
+        'This sub-pack declares it as a required peer dependency; install it via ' +
+        '`pnpm add better-sqlite3-multiple-ciphers@^12.9.0` (or rerun `pnpm install` ' +
+        'after adding @graphorin/store-sqlite-encrypted).',
+      { cause: err },
+    );
+  }
+}
+
+/**
+ * Test-only escape hatch. Drops the cached constructor so the next
+ * {@link loadCipherPeer} call re-imports the peer.
+ *
+ * @internal
+ */
+export function _resetCipherPeerCacheForTesting(): void {
+  CACHED_CTOR = null;
+}
+
+/**
+ * Test-only escape hatch. Pre-populates the cache with a stub driver
+ * so unit tests can exercise the encrypt / rekey runners without
+ * touching the native cipher addon.
+ *
+ * @internal
+ */
+export function _setCipherPeerForTesting(ctor: BetterSqlite3Constructor): void {
+  CACHED_CTOR = ctor;
+}

package/src/connection.ts

@@ -0,0 +1,49 @@
+/**
+ * Convenience wrapper around `openConnection` from `@graphorin/store-
+ * sqlite/connection` that pre-loads the cipher peer driver and applies
+ * the cipher PRAGMAs in the right order.
+ *
+ * Most callers never reach this directly - the standard path is to
+ * pass `{ encryption: { enabled: true, passphraseResolver } }` to the
+ * store-sqlite facade and let it consult the canonical
+ * `loadCipherDriver`. This helper exists for the encrypt / rekey
+ * runners (which need a "raw" handle on a freshly created cipher DB
+ * before the standard schema migrations run) and for advanced
+ * consumers that want to build a custom store on top of an encrypted
+ * connection.
+ *
+ * @packageDocumentation
+ */
+
+import {
+  type OpenConnectionOptions,
+  openConnection,
+  type SqliteConnection,
+} from '@graphorin/store-sqlite/connection';
+
+import { loadCipherPeer } from './cipher-peer.js';
+
+/**
+ * Opens an encrypted SQLite connection. Differs from `openConnection`
+ * only in that the cipher peer driver is preloaded - callers that
+ * supply an `encryption.passphraseResolver` get the same behaviour as
+ * `openConnection({ encryption })` plus an explicit fail-fast on a
+ * missing cipher peer.
+ *
+ * @stable
+ */
+export async function createEncryptedConnection(
+  options: OpenConnectionOptions,
+): Promise<SqliteConnection> {
+  if (options.encryption?.enabled !== true) {
+    throw new Error(
+      '[graphorin/store-sqlite-encrypted] createEncryptedConnection requires ' +
+        '`encryption.enabled: true`. Use `openConnection` directly for unencrypted DBs.',
+    );
+  }
+  const ctor = await loadCipherPeer();
+  return openConnection({
+    ...options,
+    cipherLoader: async () => ctor,
+  });
+}

package/src/encrypt.ts

@@ -0,0 +1,277 @@
+/**
+ * `encryptDatabase` - converts an unencrypted SQLite database file
+ * into an encrypted one. Backs `graphorin storage encrypt` per
+ * ADR-030 § 8.
+ *
+ * Strategy (CS-7): sqlite3mc ships **no** `sqlcipher_export` function
+ * (verified against the real peer - the old ATTACH+export path threw
+ * "no such function" on every real run), so the export is a
+ * **checkpoint → file copy → in-place `PRAGMA rekey`** sequence:
+ *
+ *  1. open the plaintext source, `wal_checkpoint(TRUNCATE)`, close;
+ *  2. byte-copy the file to the target (this trivially preserves every
+ *     rowid, so FTS5 external-content mappings stay intact - CS-10);
+ *  3. open the copy through the cipher peer with NO key, apply the
+ *     cipher-selection pragmas, then `PRAGMA rekey = <key>` - sqlite3mc
+ *     encrypts a plaintext database in place;
+ *  4. re-open with the key and verify via `PRAGMA integrity_check`.
+ *
+ * @packageDocumentation
+ */
+
+import { existsSync, renameSync, unlinkSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+
+import {
+  DEFAULT_CIPHER,
+  type EncryptionCipher,
+  encodePassphraseForPragma,
+  pragmaSequenceForCipher,
+} from './cipher-config.js';
+import { loadCipherPeer } from './cipher-peer.js';
+import { createEncryptedConnection } from './connection.js';
+import { cipherIntegrityCheck } from './integrity-check.js';
+
+/**
+ * Options for {@link encryptDatabase}.
+ *
+ * @stable
+ */
+export interface EncryptDatabaseOptions {
+  /** Path to the existing unencrypted source DB. */
+  readonly sourcePath: string;
+  /** Path the encrypted output is written to. Must not exist. */
+  readonly targetPath: string;
+  /** Passphrase for the new encrypted DB. */
+  readonly passphrase: string | Buffer;
+  /** Cipher selection. Default `'sqlcipher'` (SQLCipher v4 compatible). */
+  readonly cipher?: EncryptionCipher;
+  /**
+   * If `true`, atomically rename `targetPath` -> `sourcePath` after the
+   * integrity check passes. The original `sourcePath` is renamed to
+   * `${sourcePath}.bak.${timestamp}` so an operator can recover.
+   * Default `false` - the CLI does the swap explicitly.
+   *
+   * REQUIRES A STOPPED SERVER (W-012): a live writer keeps its file
+   * descriptor on the renamed `.bak` inode and every post-snapshot
+   * commit silently diverges from the new encrypted file (and is later
+   * deleted by `storage cleanup-backups`). A best-effort live-writer
+   * probe refuses the swap with {@link EncryptSwapLiveWriterError}
+   * when another connection holds the database; the probe-to-rename
+   * window remains a documented residual race.
+   */
+  readonly swap?: boolean;
+  /**
+   * If `true`, overwrite an existing `targetPath` instead of failing.
+   * Default `false`.
+   */
+  readonly overwriteTarget?: boolean;
+}
+
+/**
+ * Result of a successful {@link encryptDatabase} run.
+ *
+ * @stable
+ */
+export interface EncryptDatabaseResult {
+  readonly sourcePath: string;
+  readonly targetPath: string;
+  readonly cipher: EncryptionCipher;
+  readonly integrityCheck: { readonly ok: boolean; readonly rows: ReadonlyArray<string> };
+  readonly swap?: { readonly originalRenamedTo: string };
+}
+
+/**
+ * Encrypts an unencrypted SQLite database. Returns once the target
+ * file has been written and verified. Throws if the source is missing,
+ * the target already exists (and `overwriteTarget` is unset), the
+ * cipher peer is missing, or the integrity check fails.
+ *
+ * @stable
+ */
+/**
+ * Thrown when `encryptDatabase({ swap: true })` detects another live
+ * connection on the source database (W-012). The swap path renames the
+ * source file; a live writer would keep writing into the renamed
+ * `.bak.<ts>` inode and silently diverge from the encrypted copy.
+ *
+ * @stable
+ */
+export class EncryptSwapLiveWriterError extends Error {
+  readonly sourcePath: string;
+  constructor(sourcePath: string, cause: unknown) {
+    super(
+      `[graphorin/store-sqlite-encrypted] ${sourcePath} appears to be open by another process; ` +
+        'stop the server before running storage encrypt with --swap (writes committed after the ' +
+        'snapshot would land in the renamed .bak file and be lost).',
+      { cause },
+    );
+    this.name = 'EncryptSwapLiveWriterError';
+    this.sourcePath = sourcePath;
+  }
+}
+
+export async function encryptDatabase(
+  options: EncryptDatabaseOptions,
+): Promise<EncryptDatabaseResult> {
+  const sourcePath = absolute(options.sourcePath);
+  const targetPath = absolute(options.targetPath);
+  const cipher = options.cipher ?? DEFAULT_CIPHER;
+
+  if (!existsSync(sourcePath)) {
+    throw new Error(`[graphorin/store-sqlite-encrypted] source DB not found: ${sourcePath}`);
+  }
+  if (sourcePath === targetPath) {
+    throw new Error(
+      '[graphorin/store-sqlite-encrypted] sourcePath and targetPath must differ. ' +
+        'Pass a temporary targetPath then enable `swap: true` to atomically replace the source.',
+    );
+  }
+  if (existsSync(targetPath)) {
+    if (options.overwriteTarget !== true) {
+      throw new Error(
+        `[graphorin/store-sqlite-encrypted] target DB already exists: ${targetPath}. ` +
+          'Pass `overwriteTarget: true` to replace it.',
+      );
+    }
+    unlinkSync(targetPath);
+  }
+
+  const Ctor = await loadCipherPeer();
+
+  // W-012: --swap renames the source out from under any live writer,
+  // so probe for one FIRST. Empirically (real sqlite3mc peer): a
+  // journal-mode switch is refused with "database is locked" while any
+  // other connection is open, making it a cheap liveness probe. The
+  // mode is restored in `finally` so a crash mid-probe cannot leave the
+  // file in DELETE mode. Best-effort: the probe-to-rename window stays.
+  if (options.swap === true) {
+    const probe = new Ctor(sourcePath);
+    let switched = false;
+    try {
+      try {
+        probe.pragma('journal_mode = DELETE');
+        switched = true;
+      } catch (err) {
+        if (isBusyError(err)) throw new EncryptSwapLiveWriterError(sourcePath, err);
+        throw err;
+      }
+    } finally {
+      if (switched) {
+        try {
+          probe.pragma('journal_mode = WAL');
+        } catch {
+          // The WAL restore is best-effort; the conversion below sets
+          // journal modes explicitly anyway.
+        }
+      }
+      if (probe.open) probe.close();
+    }
+  }
+
+  try {
+    // 1+2. Online page-level copy via the driver's backup API
+    //    (store-05). The old checkpoint-close-then-copyFileSync left a
+    //    window in which a concurrent writer (a running daemon) could
+    //    commit WAL frames the byte-copy silently missed; `backup()`
+    //    is consistent under live writers, preserves rowids (FTS5
+    //    mappings survive), and includes WAL content.
+    const source = new Ctor(sourcePath, { readonly: true });
+    try {
+      await source.backup(targetPath);
+    } finally {
+      if (source.open) source.close();
+    }
+
+    // 3. In-place conversion: cipher pragmas first, then `rekey` -
+    //    sqlite3mc encrypts a plaintext database in place.
+    const target = new Ctor(targetPath);
+    try {
+      for (const pragma of pragmaSequenceForCipher(cipher)) {
+        target.pragma(pragma);
+      }
+      // sqlite3mc refuses `rekey` in WAL journal mode (real-peer
+      // verified) - drop to DELETE for the conversion, restore after.
+      target.pragma('journal_mode = DELETE');
+      const encodedKey = encodePassphraseForPragma(options.passphrase);
+      target.pragma(`rekey = ${encodedKey}`);
+      target.pragma('journal_mode = WAL');
+    } finally {
+      if (target.open) target.close();
+    }
+  } catch (err) {
+    if (existsSync(targetPath)) {
+      try {
+        unlinkSync(targetPath);
+      } catch {
+        // best-effort cleanup
+      }
+    }
+    throw new Error(
+      `[graphorin/store-sqlite-encrypted] encryption failed: ${(err as Error).message}`,
+      { cause: err },
+    );
+  }
+
+  const verify = await createEncryptedConnection({
+    path: targetPath,
+    skipSqliteVec: true,
+    disableWalHardening: true,
+    encryption: {
+      enabled: true,
+      cipher,
+      passphraseResolver: async () => options.passphrase,
+    },
+  });
+  let integrityCheck: { readonly ok: boolean; readonly rows: ReadonlyArray<string> };
+  try {
+    const result = cipherIntegrityCheck(verify);
+    integrityCheck = { ok: result.ok, rows: result.rows };
+  } finally {
+    verify.close();
+  }
+
+  if (!integrityCheck.ok) {
+    if (existsSync(targetPath)) {
+      try {
+        unlinkSync(targetPath);
+      } catch {
+        // best-effort cleanup
+      }
+    }
+    throw new Error(
+      '[graphorin/store-sqlite-encrypted] post-encrypt integrity check failed: ' +
+        integrityCheck.rows.join('; '),
+    );
+  }
+
+  let swap: { readonly originalRenamedTo: string } | undefined;
+  if (options.swap === true) {
+    const ts = Date.now();
+    const renamedTo = `${sourcePath}.bak.${ts}`;
+    renameSync(sourcePath, renamedTo);
+    renameSync(targetPath, sourcePath);
+    swap = Object.freeze({ originalRenamedTo: renamedTo });
+  }
+
+  const out: EncryptDatabaseResult = Object.freeze({
+    sourcePath,
+    targetPath: swap !== undefined ? sourcePath : targetPath,
+    cipher,
+    integrityCheck: Object.freeze(integrityCheck),
+    ...(swap !== undefined ? { swap } : {}),
+  });
+  return out;
+}
+
+function absolute(p: string): string {
+  return isAbsolute(p) ? p : resolve(p);
+}
+
+function isBusyError(err: unknown): boolean {
+  if (typeof err !== 'object' || err === null) return false;
+  const code = (err as { code?: unknown }).code;
+  if (typeof code === 'string' && code.includes('SQLITE_BUSY')) return true;
+  const message = (err as { message?: unknown }).message;
+  return typeof message === 'string' && /database is locked|busy/i.test(message);
+}

package/src/index.ts

@@ -0,0 +1,68 @@
+/**
+ * @graphorin/store-sqlite-encrypted - optional encryption-at-rest
+ * sub-pack for the Graphorin framework's default SQLite store.
+ *
+ * Installing this package pulls in the cipher peer driver
+ * (`better-sqlite3-multiple-ciphers@^12.9.0`), which is a drop-in fork
+ * of `better-sqlite3` that bundles the SQLite3MultipleCiphers
+ * extension (SQLCipher v4 / wxSQLite3 / AES-256-CBC / AES-128-CBC /
+ * RC4 cipher modes).
+ *
+ * The package exposes:
+ *
+ *  - {@link createEncryptedConnection} - convenience wrapper around
+ *    `openConnection` from `@graphorin/store-sqlite/connection` that
+ *    pre-loads the cipher peer.
+ *  - {@link encryptDatabase} - converts an unencrypted SQLite file
+ *    into an encrypted one. Backs `graphorin storage encrypt`.
+ *  - {@link rekeyDatabase} - re-keys an already encrypted file. Backs
+ *    `graphorin storage rekey`.
+ *  - {@link cipherIntegrityCheck} - runs `PRAGMA cipher_integrity_
+ *    check`. Used by the triggers daemon's daily verification cron
+ *    and the `/v1/health/storage` endpoint.
+ *  - {@link DEFAULT_CIPHER}, {@link pragmaSequenceForCipher},
+ *    {@link encodePassphraseForPragma} - cipher-config helpers shared
+ *    by the runners and consumable for advanced setups.
+ *  - {@link loadCipherPeer} / {@link EncryptedStorePeerMissingError} -
+ *    explicit peer-loader surface for callers that want to fail-fast
+ *    at startup before opening the DB.
+ *
+ * Defaults follow ADR-030 / DEC-129:
+ *  - Cipher: `'sqlcipher'` (SQLCipher v4 compatible, `legacy=4`).
+ *  - Default OFF; opt-in through `graphorin init --encrypted`.
+ *  - audit.db is ALWAYS encrypted regardless of this opt-in
+ *    (DEC-124); this package satisfies that requirement too.
+ *
+ * @packageDocumentation
+ */
+
+/** Canonical version constant, derived from `package.json` at build time. */
+import pkg from '../package.json' with { type: 'json' };
+
+export const VERSION: string = pkg.version;
+
+export {
+  DEFAULT_CIPHER,
+  type EncryptionCipher,
+  encodePassphraseForPragma,
+  pragmaSequenceForCipher,
+} from './cipher-config.js';
+export {
+  _resetCipherPeerCacheForTesting,
+  _setCipherPeerForTesting,
+  EncryptedStorePeerMissingError,
+  loadCipherPeer,
+} from './cipher-peer.js';
+export { createEncryptedConnection } from './connection.js';
+export {
+  type EncryptDatabaseOptions,
+  type EncryptDatabaseResult,
+  EncryptSwapLiveWriterError,
+  encryptDatabase,
+} from './encrypt.js';
+export { type CipherIntegrityCheckResult, cipherIntegrityCheck } from './integrity-check.js';
+export {
+  type RekeyDatabaseOptions,
+  type RekeyDatabaseResult,
+  rekeyDatabase,
+} from './rekey.js';

package/src/integrity-check.ts

@@ -0,0 +1,62 @@
+/**
+ * Integrity-check runner for encrypted databases. sqlite3mc ships no
+ * `PRAGMA cipher_integrity_check` (CS-7 - the old call returned an
+ * empty row-set on every real run, so `ok` was always false); the
+ * standard `PRAGMA integrity_check` works through the cipher layer
+ * once the connection is keyed, which is exactly the property the
+ * CLI / health endpoint needs ("can this DB be read with this key,
+ * and is it internally consistent").
+ *
+ * @packageDocumentation
+ */
+
+import type { SqliteConnection } from '@graphorin/store-sqlite/connection';
+
+/**
+ * Result of {@link cipherIntegrityCheck}.
+ *
+ * @stable
+ */
+export interface CipherIntegrityCheckResult {
+  /** `true` when SQLite reported a single `'ok'` row. */
+  readonly ok: boolean;
+  /** Raw rows returned by `PRAGMA integrity_check`. */
+  readonly rows: ReadonlyArray<string>;
+  /** Wall-clock duration of the pragma call in milliseconds. */
+  readonly durationMs: number;
+}
+
+/**
+ * Runs `PRAGMA integrity_check` against the provided connection. The
+ * connection MUST already be open with the cipher key applied
+ * (typically via {@link createEncryptedConnection}) - a wrong key
+ * surfaces as an open/read error before the pragma runs.
+ *
+ * The pragma is read-only so it is safe to run from a triggers daemon
+ * cron without taking a write lock.
+ *
+ * @stable
+ */
+export function cipherIntegrityCheck(conn: SqliteConnection): CipherIntegrityCheckResult {
+  const started = performance.now();
+  const raw = conn.pragma('integrity_check');
+  const durationMs = performance.now() - started;
+  const rows = normalizeRows(raw);
+  const ok = rows.length === 1 && rows[0] === 'ok';
+  return Object.freeze({ ok, rows: Object.freeze(rows), durationMs });
+}
+
+function normalizeRows(raw: unknown): string[] {
+  if (!Array.isArray(raw)) return [];
+  const out: string[] = [];
+  for (const row of raw as ReadonlyArray<unknown>) {
+    if (typeof row === 'string') {
+      out.push(row);
+    } else if (row !== null && typeof row === 'object') {
+      const obj = row as Record<string, unknown>;
+      const value = obj.cipher_integrity_check ?? obj.integrity_check ?? Object.values(obj)[0];
+      if (typeof value === 'string') out.push(value);
+    }
+  }
+  return out;
+}

package/src/rekey.ts

@@ -0,0 +1,130 @@
+/**
+ * `rekeyDatabase` - re-keys an already encrypted SQLite database. The
+ * runner backs `graphorin storage rekey`.
+ *
+ * Strategy: open the DB through the cipher peer with the **old** key,
+ * then issue `PRAGMA rekey = <new>;`. The cipher peer rewrites every
+ * page transactionally. After the pragma we re-open the DB with the
+ * new key and run `PRAGMA cipher_integrity_check` to confirm the
+ * rotation succeeded.
+ *
+ * @packageDocumentation
+ */
+
+import { existsSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+
+import {
+  DEFAULT_CIPHER,
+  type EncryptionCipher,
+  encodePassphraseForPragma,
+} from './cipher-config.js';
+import { loadCipherPeer } from './cipher-peer.js';
+import { createEncryptedConnection } from './connection.js';
+import { cipherIntegrityCheck } from './integrity-check.js';
+
+/**
+ * Options for {@link rekeyDatabase}.
+ *
+ * @stable
+ */
+export interface RekeyDatabaseOptions {
+  /** Path to the encrypted DB. */
+  readonly path: string;
+  /** Existing passphrase the DB is currently encrypted with. */
+  readonly oldPassphrase: string | Buffer;
+  /** New passphrase to apply. */
+  readonly newPassphrase: string | Buffer;
+  /** Cipher selection. Default `'sqlcipher'`. */
+  readonly cipher?: EncryptionCipher;
+}
+
+/**
+ * Result of a successful {@link rekeyDatabase} run.
+ *
+ * @stable
+ */
+export interface RekeyDatabaseResult {
+  readonly path: string;
+  readonly cipher: EncryptionCipher;
+  readonly integrityCheck: { readonly ok: boolean; readonly rows: ReadonlyArray<string> };
+}
+
+/**
+ * Re-keys an encrypted SQLite database. Throws if the file is missing,
+ * the cipher peer cannot be loaded, the old passphrase is wrong (the
+ * cipher peer raises `SQLITE_NOTADB` on the first read), or the
+ * post-rekey integrity check fails.
+ *
+ * @stable
+ */
+export async function rekeyDatabase(options: RekeyDatabaseOptions): Promise<RekeyDatabaseResult> {
+  const path = absolute(options.path);
+  const cipher = options.cipher ?? DEFAULT_CIPHER;
+
+  if (!existsSync(path)) {
+    throw new Error(`[graphorin/store-sqlite-encrypted] DB not found: ${path}`);
+  }
+
+  await loadCipherPeer();
+
+  const conn = await createEncryptedConnection({
+    path,
+    skipSqliteVec: true,
+    disableWalHardening: true,
+    encryption: {
+      enabled: true,
+      cipher,
+      passphraseResolver: async () => options.oldPassphrase,
+    },
+  });
+  try {
+    // Sanity-read forces the cipher peer to verify the old key before
+    // we rewrite pages with the new one.
+    conn.pragma('user_version');
+    // sqlite3mc refuses `rekey` in WAL journal mode (real-peer
+    // verified) - drop to DELETE for the rotation, restore after.
+    conn.pragma('journal_mode = DELETE');
+    const newEncoded = encodePassphraseForPragma(options.newPassphrase);
+    conn.pragma(`rekey = ${newEncoded}`);
+    conn.pragma('journal_mode = WAL');
+  } catch (err) {
+    if (conn.raw().open) conn.close();
+    throw new Error(`[graphorin/store-sqlite-encrypted] rekey failed: ${(err as Error).message}`, {
+      cause: err,
+    });
+  } finally {
+    if (conn.raw().open) conn.close();
+  }
+
+  const verify = await createEncryptedConnection({
+    path,
+    skipSqliteVec: true,
+    disableWalHardening: true,
+    encryption: {
+      enabled: true,
+      cipher,
+      passphraseResolver: async () => options.newPassphrase,
+    },
+  });
+  let integrityCheck: { readonly ok: boolean; readonly rows: ReadonlyArray<string> };
+  try {
+    const result = cipherIntegrityCheck(verify);
+    integrityCheck = { ok: result.ok, rows: result.rows };
+  } finally {
+    verify.close();
+  }
+
+  if (!integrityCheck.ok) {
+    throw new Error(
+      '[graphorin/store-sqlite-encrypted] post-rekey integrity check failed: ' +
+        integrityCheck.rows.join('; '),
+    );
+  }
+
+  return Object.freeze({ path, cipher, integrityCheck: Object.freeze(integrityCheck) });
+}
+
+function absolute(p: string): string {
+  return isAbsolute(p) ? p : resolve(p);
+}