@graphorin/store-sqlite-encrypted 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# @graphorin/store-sqlite-encrypted
+
+## 0.1.0
+
+### Minor Changes
+
+- Initial release of the optional encryption-at-rest sub-pack for the Graphorin
+  framework's default SQLite store. Pulls in
+  `better-sqlite3-multiple-ciphers@^12.9.0` and exposes the `encryptDatabase`,
+  `rekeyDatabase`, `cipherIntegrityCheck`, and `createEncryptedConnection`
+  helpers consumed by the `graphorin storage` CLI.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleksiy Stepurenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,162 @@
+# @graphorin/store-sqlite-encrypted
+
+> Optional encryption-at-rest sub-pack for the [Graphorin](https://github.com/o-stepper/graphorin)
+> framework's default SQLite store. Pulls in
+> `better-sqlite3-multiple-ciphers@^12.9.0` (a drop-in fork of `better-sqlite3`
+> that bundles the SQLite3MultipleCiphers extension) and exposes the
+> encrypt / rekey / integrity-check runners that back the `graphorin storage`
+> CLI subcommand group.
+>
+> Project Graphorin · v0.5.0 · MIT License · © 2026 Oleksiy Stepurenko ·
+> <https://github.com/o-stepper/graphorin>
+
+---
+
+## Status
+
+- **Published:** v0.5.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`.
+- **`audit.db`:** ALWAYS encrypted regardless of this opt-in. Installing
+  this sub-pack is the only supported way to satisfy that requirement on
+  fresh installations.
+
+---
+
+## Install
+
+```bash
+pnpm add @graphorin/store-sqlite-encrypted
+# Pulls in better-sqlite3-multiple-ciphers@^12.9.0 as a peer dep.
+```
+
+The cipher peer ships prebuilt binaries for every Node 22+ target
+(macOS arm64/x64, Linux x64/arm/arm64 with both glibc and musl, Windows
+x86/x64/arm64) so there is no compile step on `pnpm install` for the
+default platforms.
+
+If you are on a platform without a prebuilt binary you will need a C++
+toolchain and Python 3 available; consult the upstream
+[`better-sqlite3-multiple-ciphers`](https://www.npmjs.com/package/better-sqlite3-multiple-ciphers)
+README for details.
+
+---
+
+## Usage
+
+### One-shot encryption migration (CLI flow)
+
+```bash
+# 1. Stop any running graphorin server / writers.
+graphorin stop
+
+# 2. Back up the unencrypted DB.
+cp ~/.graphorin/data.db ~/.graphorin/data.db.backup-$(date +%Y%m%d-%H%M)
+
+# 3. Encrypt + verify (passphrase resolved from a SecretRef chain).
+graphorin storage encrypt --passphrase-from keyring:graphorin_db_passphrase
+
+# 4. Update the config and restart.
+graphorin config set storage.encryption.enabled true
+graphorin config set storage.encryption.passphraseRef keyring:graphorin_db_passphrase
+graphorin start
+
+# 5. After a verification window (default 7 days) drop the backup.
+graphorin storage cleanup-backups --older-than 7d
+```
+
+### Programmatic use
+
+```ts
+import {
+  createEncryptedConnection,
+  encryptDatabase,
+  rekeyDatabase,
+  cipherIntegrityCheck,
+} from '@graphorin/store-sqlite-encrypted';
+
+// Open an existing encrypted DB.
+const conn = await createEncryptedConnection({
+  path: '/var/lib/graphorin/data.db',
+  encryption: {
+    enabled: true,
+    passphraseResolver: async () => process.env.GRAPHORIN_DB_PASSPHRASE!,
+  },
+});
+
+// Verify the cipher header on startup or via a triggers cron.
+const integrity = cipherIntegrityCheck(conn);
+if (!integrity.ok) {
+  throw new Error(`cipher_integrity_check failed: ${integrity.rows.join('; ')}`);
+}
+
+// One-shot migration of an unencrypted file into a new encrypted one.
+await encryptDatabase({
+  sourcePath: '/var/lib/graphorin/data.db',
+  targetPath: '/var/lib/graphorin/data.db.encrypted',
+  passphrase: process.env.GRAPHORIN_DB_PASSPHRASE!,
+  swap: true, // atomic rename + .bak.<timestamp> kept for recovery
+});
+
+// Rotate the passphrase in place (PRAGMA rekey under the hood).
+await rekeyDatabase({
+  path: '/var/lib/graphorin/data.db',
+  oldPassphrase: process.env.OLD_PASSPHRASE!,
+  newPassphrase: process.env.NEW_PASSPHRASE!,
+});
+```
+
+---
+
+## Cipher selection
+
+The default cipher is `'sqlcipher'` with the `legacy=4` parameter set —
+SQLCipher v4 compatible — chosen for ecosystem tooling compatibility
+(DB Browser for SQLCipher, `sqlcipher` CLI, GUI inspectors). Other
+cipher modes shipped by the cipher peer are accepted; pass them via the
+`cipher` option:
+
+| Cipher        | Notes                                                                       |
+|---------------|-----------------------------------------------------------------------------|
+| `'sqlcipher'` | Default. AES-256-CBC + HMAC-SHA1 + Argon2id KDF. SQLCipher v4 compatible.   |
+| `'chacha20'`  | The cipher peer's own default (ChaCha20-Poly1305).                          |
+| `'aes256cbc'` | Raw AES-256-CBC without the SQLCipher HMAC envelope.                        |
+| `'aes128cbc'` | AES-128-CBC variant.                                                        |
+| `'rc4'`       | Legacy interop only. Do **not** use for new deployments.                    |
+
+---
+
+## Operational notes
+
+- **Passphrase loss = total data loss.** The cipher peer cannot
+  recover an encrypted DB without the passphrase. Store the passphrase
+  in a keyring or vault (the `graphorin storage encrypt` CLI prompts
+  for this).
+- **WAL housekeeping bytes** are visible to an attacker on file leak
+  (page numbers, lengths). Row contents are not. See ADR-030 § 5
+  for the threat-model nuance.
+- **Performance overhead** is typically 5–15 % on OLTP workloads (read
+  / write of small rows). The triggers cron that runs the daily
+  `cipher_integrity_check` is a read-only pragma so it does not
+  block writers.
+- **Edge runtimes** (Cloudflare Workers, Vercel Edge) are **not
+  supported**. The cipher peer is a native addon. For edge deployments
+  use `@graphorin/store-libsql` (Turso encryption is a separate story).
+
+---
+
+## Related decisions
+
+- ADR-030 — SQLite encryption at rest (SQLCipher v4 baseline + KDF parameters).
+- ADR-008 — Storage default `better-sqlite3` (synchronous embedded SQLite + WAL hardening).
+
+---
+
+## License
+
+MIT © 2026 Oleksiy Stepurenko
+
+---
+
+**Project Graphorin** · v0.5.0 · MIT License · © 2026 Oleksiy Stepurenko · <https://github.com/o-stepper/graphorin>

package/dist/cipher-config.d.ts

@@ -0,0 +1,37 @@
+import { EncryptionCipher } from "@graphorin/store-sqlite/encryption";
+
+//#region src/cipher-config.d.ts
+
+/**
+ * Default cipher. Matches ADR-030 § 2 — SQLCipher v4 compatible
+ * (AES-256-CBC + HMAC-SHA1, `legacy=4` parameter set).
+ *
+ * @stable
+ */
+declare const DEFAULT_CIPHER: EncryptionCipher;
+/**
+ * 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
+ */
+declare function pragmaSequenceForCipher(cipher: EncryptionCipher): ReadonlyArray<string>;
+/**
+ * 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
+ */
+declare function encodePassphraseForPragma(value: string | Buffer): string;
+//#endregion
+export { DEFAULT_CIPHER, type EncryptionCipher, encodePassphraseForPragma, pragmaSequenceForCipher };
+//# sourceMappingURL=cipher-config.d.ts.map

package/dist/cipher-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cipher-config.d.ts","names":[],"sources":["../src/cipher-config.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;cAmBa,gBAAgB;;;;;;;;iBAwBb,uBAAA,SAAgC,mBAAmB;;;;;;;;;;;;;;;iBAyBnD,yBAAA,iBAA0C"}

package/dist/cipher-config.js

@@ -0,0 +1,60 @@
+//#region src/cipher-config.ts
+/**
+* Default cipher. Matches ADR-030 § 2 — SQLCipher v4 compatible
+* (AES-256-CBC + HMAC-SHA1, `legacy=4` parameter set).
+*
+* @stable
+*/
+const DEFAULT_CIPHER = "sqlcipher";
+/**
+* Cipher-specific PRAGMAs that must be applied **immediately after**
+* `PRAGMA key = ...` for SQLite3MultipleCiphers to interpret the key
+* correctly. The list mirrors the upstream documentation.
+*
+* @internal
+*/
+const CIPHER_PRAGMAS = 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
+*/
+function pragmaSequenceForCipher(cipher) {
+	const seq = CIPHER_PRAGMAS[cipher];
+	if (seq === void 0) 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
+*/
+function encodePassphraseForPragma(value) {
+	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")}'`;
+}
+
+//#endregion
+export { DEFAULT_CIPHER, encodePassphraseForPragma, pragmaSequenceForCipher };
+//# sourceMappingURL=cipher-config.js.map

package/dist/cipher-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cipher-config.js","names":["DEFAULT_CIPHER: EncryptionCipher","CIPHER_PRAGMAS: Readonly<Record<EncryptionCipher, ReadonlyArray<string>>>"],"sources":["../src/cipher-config.ts"],"sourcesContent":["/**\n * Cipher selection + passphrase encoding helpers shared by the\n * `createEncryptedConnection`, `encryptDatabase`, and `rekeyDatabase`\n * runners. The cipher peer reads the passphrase via `PRAGMA key`; this\n * module owns the SQL-literal escaping path so all three runners agree.\n *\n * @packageDocumentation\n */\n\nimport type { EncryptionCipher } from '@graphorin/store-sqlite/encryption';\n\nexport type { EncryptionCipher };\n\n/**\n * Default cipher. Matches ADR-030 § 2 — SQLCipher v4 compatible\n * (AES-256-CBC + HMAC-SHA1, `legacy=4` parameter set).\n *\n * @stable\n */\nexport const DEFAULT_CIPHER: EncryptionCipher = 'sqlcipher';\n\n/**\n * Cipher-specific PRAGMAs that must be applied **immediately after**\n * `PRAGMA key = ...` for SQLite3MultipleCiphers to interpret the key\n * correctly. The list mirrors the upstream documentation.\n *\n * @internal\n */\nconst CIPHER_PRAGMAS: Readonly<Record<EncryptionCipher, ReadonlyArray<string>>> = Object.freeze({\n  sqlcipher: Object.freeze([\"cipher = 'sqlcipher'\", 'legacy = 4']),\n  chacha20: Object.freeze([\"cipher = 'chacha20'\"]),\n  aes256cbc: Object.freeze([\"cipher = 'aes256cbc'\"]),\n  aes128cbc: Object.freeze([\"cipher = 'aes128cbc'\"]),\n  rc4: Object.freeze([\"cipher = 'rc4'\"]),\n});\n\n/**\n * Returns the PRAGMA statements that select a cipher. The list is\n * applied **before** `PRAGMA key = ...` so the cipher peer knows which\n * KDF / mode to use when interpreting the key bytes.\n *\n * @stable\n */\nexport function pragmaSequenceForCipher(cipher: EncryptionCipher): ReadonlyArray<string> {\n  const seq = CIPHER_PRAGMAS[cipher];\n  if (seq === undefined) {\n    throw new TypeError(\n      `[graphorin/store-sqlite-encrypted] unknown cipher '${String(cipher)}'. ` +\n        `Supported: ${Object.keys(CIPHER_PRAGMAS).join(', ')}.`,\n    );\n  }\n  return seq;\n}\n\n/**\n * SQL-literal-encodes a passphrase for use as the right-hand side of\n * `PRAGMA key = ...`.\n *\n * - String input is wrapped in single quotes with internal `'` doubled\n *   per the SQL specification.\n * - Buffer input is encoded as the cipher peer's `x'<hex>'` blob form\n *   so binary keys round-trip exactly.\n *\n * Empty inputs are rejected at this layer so callers cannot\n * accidentally open an unencrypted DB with an empty key.\n *\n * @stable\n */\nexport function encodePassphraseForPragma(value: string | Buffer): string {\n  if (typeof value === 'string') {\n    if (value.length === 0) {\n      throw new Error('[graphorin/store-sqlite-encrypted] passphrase is empty');\n    }\n    return `'${value.replace(/'/g, \"''\")}'`;\n  }\n  if (value.length === 0) {\n    throw new Error('[graphorin/store-sqlite-encrypted] passphrase buffer is empty');\n  }\n  return `x'${value.toString('hex')}'`;\n}\n"],"mappings":";;;;;;;AAmBA,MAAaA,iBAAmC;;;;;;;;AAShD,MAAMC,iBAA4E,OAAO,OAAO;CAC9F,WAAW,OAAO,OAAO,CAAC,wBAAwB,aAAa,CAAC;CAChE,UAAU,OAAO,OAAO,CAAC,sBAAsB,CAAC;CAChD,WAAW,OAAO,OAAO,CAAC,uBAAuB,CAAC;CAClD,WAAW,OAAO,OAAO,CAAC,uBAAuB,CAAC;CAClD,KAAK,OAAO,OAAO,CAAC,iBAAiB,CAAC;CACvC,CAAC;;;;;;;;AASF,SAAgB,wBAAwB,QAAiD;CACvF,MAAM,MAAM,eAAe;AAC3B,KAAI,QAAQ,OACV,OAAM,IAAI,UACR,sDAAsD,OAAO,OAAO,CAAC,gBACrD,OAAO,KAAK,eAAe,CAAC,KAAK,KAAK,CAAC,GACxD;AAEH,QAAO;;;;;;;;;;;;;;;;AAiBT,SAAgB,0BAA0B,OAAgC;AACxE,KAAI,OAAO,UAAU,UAAU;AAC7B,MAAI,MAAM,WAAW,EACnB,OAAM,IAAI,MAAM,yDAAyD;AAE3E,SAAO,IAAI,MAAM,QAAQ,MAAM,KAAK,CAAC;;AAEvC,KAAI,MAAM,WAAW,EACnB,OAAM,IAAI,MAAM,gEAAgE;AAElF,QAAO,KAAK,MAAM,SAAS,MAAM,CAAC"}

package/dist/cipher-peer.d.ts

@@ -0,0 +1,40 @@
+import { BetterSqlite3Constructor } from "@graphorin/store-sqlite/connection";
+
+//#region src/cipher-peer.d.ts
+
+/**
+ * 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
+ */
+declare class EncryptedStorePeerMissingError extends Error {
+  readonly name = "EncryptedStorePeerMissingError";
+}
+/**
+ * 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
+ */
+declare function loadCipherPeer(): Promise<BetterSqlite3Constructor>;
+/**
+ * Test-only escape hatch. Drops the cached constructor so the next
+ * {@link loadCipherPeer} call re-imports the peer.
+ *
+ * @internal
+ */
+declare function _resetCipherPeerCacheForTesting(): void;
+/**
+ * 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
+ */
+declare function _setCipherPeerForTesting(ctor: BetterSqlite3Constructor): void;
+//#endregion
+export { EncryptedStorePeerMissingError, _resetCipherPeerCacheForTesting, _setCipherPeerForTesting, loadCipherPeer };
+//# sourceMappingURL=cipher-peer.d.ts.map

package/dist/cipher-peer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cipher-peer.d.ts","names":[],"sources":["../src/cipher-peer.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;cAwBa,8BAAA,SAAuC,KAAA;;;;;;;;;;iBAc9B,cAAA,CAAA,GAAkB,QAAQ;;;;;;;iBAyBhC,+BAAA,CAAA;;;;;;;;iBAWA,wBAAA,OAA+B"}

package/dist/cipher-peer.js

@@ -0,0 +1,52 @@
+//#region src/cipher-peer.ts
+/**
+* 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
+*/
+var EncryptedStorePeerMissingError = class extends Error {
+	name = "EncryptedStorePeerMissingError";
+};
+/** @internal */
+let CACHED_CTOR = 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
+*/
+async function loadCipherPeer() {
+	if (CACHED_CTOR !== null) return CACHED_CTOR;
+	try {
+		CACHED_CTOR = (await import("better-sqlite3-multiple-ciphers")).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
+*/
+function _resetCipherPeerCacheForTesting() {
+	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
+*/
+function _setCipherPeerForTesting(ctor) {
+	CACHED_CTOR = ctor;
+}
+
+//#endregion
+export { EncryptedStorePeerMissingError, _resetCipherPeerCacheForTesting, _setCipherPeerForTesting, loadCipherPeer };
+//# sourceMappingURL=cipher-peer.js.map

package/dist/cipher-peer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cipher-peer.js","names":["CACHED_CTOR: BetterSqlite3Constructor | null"],"sources":["../src/cipher-peer.ts"],"sourcesContent":["/**\n * Loads the `better-sqlite3-multiple-ciphers` cipher peer driver. The\n * peer is declared `optional: false` in this package's `package.json`\n * (the whole point of installing this sub-pack is to opt in to\n * encryption-at-rest), but we still wrap the import in a friendly\n * fail-fast helper so consumers see an actionable error rather than a\n * raw `ERR_MODULE_NOT_FOUND`.\n *\n * The peer is loaded lazily — importing this package on its own does\n * NOT load the native addon, so callers that only inspect the public\n * helpers (e.g. for documentation generation) pay no native-load cost.\n *\n * @packageDocumentation\n */\n\nimport type { BetterSqlite3Constructor } from '@graphorin/store-sqlite/connection';\n\n/**\n * Raised when the cipher peer driver cannot be loaded. Distinct from\n * the matching `CipherPeerMissingError` in `@graphorin/store-sqlite/\n * encryption` so consumers can catch the two layers independently.\n *\n * @stable\n */\nexport class EncryptedStorePeerMissingError extends Error {\n  override readonly name = 'EncryptedStorePeerMissingError';\n}\n\n/** @internal */\nlet CACHED_CTOR: BetterSqlite3Constructor | null = null;\n\n/**\n * Loads `better-sqlite3-multiple-ciphers`. The result is cached for\n * the lifetime of the process so repeat callers (encrypt + rekey +\n * connection-open in the same process) share one native handle.\n *\n * @stable\n */\nexport async function loadCipherPeer(): Promise<BetterSqlite3Constructor> {\n  if (CACHED_CTOR !== null) return CACHED_CTOR;\n  try {\n    const mod = (await import('better-sqlite3-multiple-ciphers')) as unknown as {\n      default: BetterSqlite3Constructor;\n    };\n    CACHED_CTOR = mod.default;\n    return CACHED_CTOR;\n  } catch (err) {\n    throw new EncryptedStorePeerMissingError(\n      \"the cipher peer 'better-sqlite3-multiple-ciphers' could not be loaded. \" +\n        'This sub-pack declares it as a required peer dependency; install it via ' +\n        '`pnpm add better-sqlite3-multiple-ciphers@^12.9.0` (or rerun `pnpm install` ' +\n        'after adding @graphorin/store-sqlite-encrypted).',\n      { cause: err },\n    );\n  }\n}\n\n/**\n * Test-only escape hatch. Drops the cached constructor so the next\n * {@link loadCipherPeer} call re-imports the peer.\n *\n * @internal\n */\nexport function _resetCipherPeerCacheForTesting(): void {\n  CACHED_CTOR = null;\n}\n\n/**\n * Test-only escape hatch. Pre-populates the cache with a stub driver\n * so unit tests can exercise the encrypt / rekey runners without\n * touching the native cipher addon.\n *\n * @internal\n */\nexport function _setCipherPeerForTesting(ctor: BetterSqlite3Constructor): void {\n  CACHED_CTOR = ctor;\n}\n"],"mappings":";;;;;;;;AAwBA,IAAa,iCAAb,cAAoD,MAAM;CACxD,AAAkB,OAAO;;;AAI3B,IAAIA,cAA+C;;;;;;;;AASnD,eAAsB,iBAAoD;AACxE,KAAI,gBAAgB,KAAM,QAAO;AACjC,KAAI;AAIF,iBAHa,MAAM,OAAO,oCAGR;AAClB,SAAO;UACA,KAAK;AACZ,QAAM,IAAI,+BACR,+QAIA,EAAE,OAAO,KAAK,CACf;;;;;;;;;AAUL,SAAgB,kCAAwC;AACtD,eAAc;;;;;;;;;AAUhB,SAAgB,yBAAyB,MAAsC;AAC7E,eAAc"}

package/dist/connection.d.ts

@@ -0,0 +1,17 @@
+import { OpenConnectionOptions, SqliteConnection } from "@graphorin/store-sqlite/connection";
+
+//#region src/connection.d.ts
+
+/**
+ * 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
+ */
+declare function createEncryptedConnection(options: OpenConnectionOptions): Promise<SqliteConnection>;
+//#endregion
+export { createEncryptedConnection };
+//# sourceMappingURL=connection.d.ts.map

package/dist/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","names":[],"sources":["../src/connection.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;iBAkCsB,yBAAA,UACX,wBACR,QAAQ"}

package/dist/connection.js

@@ -0,0 +1,41 @@
+import { loadCipherPeer } from "./cipher-peer.js";
+import { openConnection } from "@graphorin/store-sqlite/connection";
+
+//#region src/connection.ts
+/**
+* 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
+*/
+/**
+* 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
+*/
+async function createEncryptedConnection(options) {
+	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
+	});
+}
+
+//#endregion
+export { createEncryptedConnection };
+//# sourceMappingURL=connection.js.map

package/dist/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.js","names":[],"sources":["../src/connection.ts"],"sourcesContent":["/**\n * Convenience wrapper around `openConnection` from `@graphorin/store-\n * sqlite/connection` that pre-loads the cipher peer driver and applies\n * the cipher PRAGMAs in the right order.\n *\n * Most callers never reach this directly — the standard path is to\n * pass `{ encryption: { enabled: true, passphraseResolver } }` to the\n * store-sqlite facade and let it consult the canonical\n * `loadCipherDriver`. This helper exists for the encrypt / rekey\n * runners (which need a \"raw\" handle on a freshly created cipher DB\n * before the standard schema migrations run) and for advanced\n * consumers that want to build a custom store on top of an encrypted\n * connection.\n *\n * @packageDocumentation\n */\n\nimport {\n  type OpenConnectionOptions,\n  openConnection,\n  type SqliteConnection,\n} from '@graphorin/store-sqlite/connection';\n\nimport { loadCipherPeer } from './cipher-peer.js';\n\n/**\n * Opens an encrypted SQLite connection. Differs from `openConnection`\n * only in that the cipher peer driver is preloaded — callers that\n * supply an `encryption.passphraseResolver` get the same behaviour as\n * `openConnection({ encryption })` plus an explicit fail-fast on a\n * missing cipher peer.\n *\n * @stable\n */\nexport async function createEncryptedConnection(\n  options: OpenConnectionOptions,\n): Promise<SqliteConnection> {\n  if (options.encryption?.enabled !== true) {\n    throw new Error(\n      '[graphorin/store-sqlite-encrypted] createEncryptedConnection requires ' +\n        '`encryption.enabled: true`. Use `openConnection` directly for unencrypted DBs.',\n    );\n  }\n  const ctor = await loadCipherPeer();\n  return openConnection({\n    ...options,\n    cipherLoader: async () => ctor,\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCA,eAAsB,0BACpB,SAC2B;AAC3B,KAAI,QAAQ,YAAY,YAAY,KAClC,OAAM,IAAI,MACR,uJAED;CAEH,MAAM,OAAO,MAAM,gBAAgB;AACnC,QAAO,eAAe;EACpB,GAAG;EACH,cAAc,YAAY;EAC3B,CAAC"}

package/dist/encrypt.d.ts

@@ -0,0 +1,60 @@
+import { EncryptionCipher } from "./cipher-config.js";
+
+//#region src/encrypt.d.ts
+
+/**
+ * Options for {@link encryptDatabase}.
+ *
+ * @stable
+ */
+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.
+   */
+  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
+ */
+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
+ */
+declare function encryptDatabase(options: EncryptDatabaseOptions): Promise<EncryptDatabaseResult>;
+//#endregion
+export { EncryptDatabaseOptions, EncryptDatabaseResult, encryptDatabase };
+//# sourceMappingURL=encrypt.d.ts.map

package/dist/encrypt.d.ts.map

@@ -0,0 +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"}

package/dist/encrypt.js

@@ -0,0 +1,119 @@
+import { DEFAULT_CIPHER, encodePassphraseForPragma, pragmaSequenceForCipher } from "./cipher-config.js";
+import { loadCipherPeer } from "./cipher-peer.js";
+import { createEncryptedConnection } from "./connection.js";
+import { cipherIntegrityCheck } from "./integrity-check.js";
+import { copyFileSync, existsSync, renameSync, unlinkSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+
+//#region src/encrypt.ts
+/**
+* `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
+*/
+/**
+* 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
+*/
+async function encryptDatabase(options) {
+	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();
+	try {
+		const source = new Ctor(sourcePath);
+		try {
+			source.pragma("wal_checkpoint(TRUNCATE)");
+		} finally {
+			if (source.open) source.close();
+		}
+		copyFileSync(sourcePath, targetPath);
+		const target = new Ctor(targetPath);
+		try {
+			for (const pragma of pragmaSequenceForCipher(cipher)) target.pragma(pragma);
+			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 {}
+		throw new Error(`[graphorin/store-sqlite-encrypted] encryption failed: ${err.message}`, { cause: err });
+	}
+	const verify = await createEncryptedConnection({
+		path: targetPath,
+		skipSqliteVec: true,
+		disableWalHardening: true,
+		encryption: {
+			enabled: true,
+			cipher,
+			passphraseResolver: async () => options.passphrase
+		}
+	});
+	let integrityCheck;
+	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 {}
+		throw new Error("[graphorin/store-sqlite-encrypted] post-encrypt integrity check failed: " + integrityCheck.rows.join("; "));
+	}
+	let swap;
+	if (options.swap === true) {
+		const renamedTo = `${sourcePath}.bak.${Date.now()}`;
+		renameSync(sourcePath, renamedTo);
+		renameSync(targetPath, sourcePath);
+		swap = Object.freeze({ originalRenamedTo: renamedTo });
+	}
+	return Object.freeze({
+		sourcePath,
+		targetPath: swap !== void 0 ? sourcePath : targetPath,
+		cipher,
+		integrityCheck: Object.freeze(integrityCheck),
+		...swap !== void 0 ? { swap } : {}
+	});
+}
+function absolute(p) {
+	return isAbsolute(p) ? p : resolve(p);
+}
+
+//#endregion
+export { encryptDatabase };
+//# sourceMappingURL=encrypt.js.map

package/dist/encrypt.js.map

@@ -0,0 +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 { copyFileSync, 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. Checkpoint the plaintext source so a byte-copy captures the\n    //    full state even when the DB ran in WAL mode.\n    const source = new Ctor(sourcePath);\n    try {\n      source.pragma('wal_checkpoint(TRUNCATE)');\n    } finally {\n      if (source.open) source.close();\n    }\n\n    // 2. Byte-copy — rowids (and therefore FTS5 mappings) are preserved.\n    copyFileSync(sourcePath, targetPath);\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;EAGF,MAAM,SAAS,IAAI,KAAK,WAAW;AACnC,MAAI;AACF,UAAO,OAAO,2BAA2B;YACjC;AACR,OAAI,OAAO,KAAM,QAAO,OAAO;;AAIjC,eAAa,YAAY,WAAW;EAIpC,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"}

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+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 { CipherIntegrityCheckResult, cipherIntegrityCheck } from "./integrity-check.js";
+import { RekeyDatabaseOptions, RekeyDatabaseResult, rekeyDatabase } from "./rekey.js";
+
+//#region src/index.d.ts
+
+/**
+ * @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. Mirrors the `package.json` version. */
+declare const VERSION = "0.5.0";
+//#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 };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,51 @@
+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 { rekeyDatabase } from "./rekey.js";
+
+//#region src/index.ts
+/**
+* @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. Mirrors the `package.json` version. */
+const VERSION = "0.5.0";
+
+//#endregion
+export { DEFAULT_CIPHER, EncryptedStorePeerMissingError, VERSION, _resetCipherPeerCacheForTesting, _setCipherPeerForTesting, cipherIntegrityCheck, createEncryptedConnection, encodePassphraseForPragma, encryptDatabase, loadCipherPeer, pragmaSequenceForCipher, rekeyDatabase };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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.5.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"}

package/dist/integrity-check.d.ts

@@ -0,0 +1,32 @@
+import { SqliteConnection } from "@graphorin/store-sqlite/connection";
+
+//#region src/integrity-check.d.ts
+
+/**
+ * Result of {@link cipherIntegrityCheck}.
+ *
+ * @stable
+ */
+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
+ */
+declare function cipherIntegrityCheck(conn: SqliteConnection): CipherIntegrityCheckResult;
+//#endregion
+export { CipherIntegrityCheckResult, cipherIntegrityCheck };
+//# sourceMappingURL=integrity-check.d.ts.map

package/dist/integrity-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integrity-check.d.ts","names":[],"sources":["../src/integrity-check.ts"],"sourcesContent":[],"mappings":";;;;;;;;;UAmBiB,0BAAA;;;;iBAIA;;;;;;;;;;;;;;;iBAgBD,oBAAA,OAA2B,mBAAmB"}

package/dist/integrity-check.js

@@ -0,0 +1,39 @@
+//#region src/integrity-check.ts
+/**
+* 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
+*/
+function cipherIntegrityCheck(conn) {
+	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) {
+	if (!Array.isArray(raw)) return [];
+	const out = [];
+	for (const row of raw) if (typeof row === "string") out.push(row);
+	else if (row !== null && typeof row === "object") {
+		const obj = row;
+		const value = obj.cipher_integrity_check ?? obj.integrity_check ?? Object.values(obj)[0];
+		if (typeof value === "string") out.push(value);
+	}
+	return out;
+}
+
+//#endregion
+export { cipherIntegrityCheck };
+//# sourceMappingURL=integrity-check.js.map

package/dist/integrity-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"integrity-check.js","names":["out: string[]"],"sources":["../src/integrity-check.ts"],"sourcesContent":["/**\n * Integrity-check runner for encrypted databases. sqlite3mc ships no\n * `PRAGMA cipher_integrity_check` (CS-7 — the old call returned an\n * empty row-set on every real run, so `ok` was always false); the\n * standard `PRAGMA integrity_check` works through the cipher layer\n * once the connection is keyed, which is exactly the property the\n * CLI / health endpoint needs (\"can this DB be read with this key,\n * and is it internally consistent\").\n *\n * @packageDocumentation\n */\n\nimport type { SqliteConnection } from '@graphorin/store-sqlite/connection';\n\n/**\n * Result of {@link cipherIntegrityCheck}.\n *\n * @stable\n */\nexport interface CipherIntegrityCheckResult {\n  /** `true` when SQLite reported a single `'ok'` row. */\n  readonly ok: boolean;\n  /** Raw rows returned by `PRAGMA integrity_check`. */\n  readonly rows: ReadonlyArray<string>;\n  /** Wall-clock duration of the pragma call in milliseconds. */\n  readonly durationMs: number;\n}\n\n/**\n * Runs `PRAGMA integrity_check` against the provided connection. The\n * connection MUST already be open with the cipher key applied\n * (typically via {@link createEncryptedConnection}) — a wrong key\n * surfaces as an open/read error before the pragma runs.\n *\n * The pragma is read-only so it is safe to run from a triggers daemon\n * cron without taking a write lock.\n *\n * @stable\n */\nexport function cipherIntegrityCheck(conn: SqliteConnection): CipherIntegrityCheckResult {\n  const started = performance.now();\n  const raw = conn.pragma('integrity_check');\n  const durationMs = performance.now() - started;\n  const rows = normalizeRows(raw);\n  const ok = rows.length === 1 && rows[0] === 'ok';\n  return Object.freeze({ ok, rows: Object.freeze(rows), durationMs });\n}\n\nfunction normalizeRows(raw: unknown): string[] {\n  if (!Array.isArray(raw)) return [];\n  const out: string[] = [];\n  for (const row of raw as ReadonlyArray<unknown>) {\n    if (typeof row === 'string') {\n      out.push(row);\n    } else if (row !== null && typeof row === 'object') {\n      const obj = row as Record<string, unknown>;\n      const value = obj.cipher_integrity_check ?? obj.integrity_check ?? Object.values(obj)[0];\n      if (typeof value === 'string') out.push(value);\n    }\n  }\n  return out;\n}\n"],"mappings":";;;;;;;;;;;;AAuCA,SAAgB,qBAAqB,MAAoD;CACvF,MAAM,UAAU,YAAY,KAAK;CACjC,MAAM,MAAM,KAAK,OAAO,kBAAkB;CAC1C,MAAM,aAAa,YAAY,KAAK,GAAG;CACvC,MAAM,OAAO,cAAc,IAAI;CAC/B,MAAM,KAAK,KAAK,WAAW,KAAK,KAAK,OAAO;AAC5C,QAAO,OAAO,OAAO;EAAE;EAAI,MAAM,OAAO,OAAO,KAAK;EAAE;EAAY,CAAC;;AAGrE,SAAS,cAAc,KAAwB;AAC7C,KAAI,CAAC,MAAM,QAAQ,IAAI,CAAE,QAAO,EAAE;CAClC,MAAMA,MAAgB,EAAE;AACxB,MAAK,MAAM,OAAO,IAChB,KAAI,OAAO,QAAQ,SACjB,KAAI,KAAK,IAAI;UACJ,QAAQ,QAAQ,OAAO,QAAQ,UAAU;EAClD,MAAM,MAAM;EACZ,MAAM,QAAQ,IAAI,0BAA0B,IAAI,mBAAmB,OAAO,OAAO,IAAI,CAAC;AACtF,MAAI,OAAO,UAAU,SAAU,KAAI,KAAK,MAAM;;AAGlD,QAAO"}

package/dist/rekey.d.ts

@@ -0,0 +1,44 @@
+import { EncryptionCipher } from "./cipher-config.js";
+
+//#region src/rekey.d.ts
+
+/**
+ * Options for {@link rekeyDatabase}.
+ *
+ * @stable
+ */
+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
+ */
+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
+ */
+declare function rekeyDatabase(options: RekeyDatabaseOptions): Promise<RekeyDatabaseResult>;
+//#endregion
+export { RekeyDatabaseOptions, RekeyDatabaseResult, rekeyDatabase };
+//# sourceMappingURL=rekey.d.ts.map

package/dist/rekey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rekey.d.ts","names":[],"sources":["../src/rekey.ts"],"sourcesContent":[],"mappings":";;;;;;;;;UA8BiB,oBAAA;;;;mCAIkB;;mCAEA;;oBAEf;;;;;;;UAQH,mBAAA;;mBAEE;;;mBAC+C;;;;;;;;;;;iBAW5C,aAAA,UAAuB,uBAAuB,QAAQ"}

package/dist/rekey.js

@@ -0,0 +1,89 @@
+import { DEFAULT_CIPHER, encodePassphraseForPragma } from "./cipher-config.js";
+import { loadCipherPeer } from "./cipher-peer.js";
+import { createEncryptedConnection } from "./connection.js";
+import { cipherIntegrityCheck } from "./integrity-check.js";
+import { existsSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+
+//#region src/rekey.ts
+/**
+* `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
+*/
+/**
+* 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
+*/
+async function rekeyDatabase(options) {
+	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 {
+		conn.pragma("user_version");
+		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.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;
+	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) {
+	return isAbsolute(p) ? p : resolve(p);
+}
+
+//#endregion
+export { rekeyDatabase };
+//# sourceMappingURL=rekey.js.map

package/dist/rekey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rekey.js","names":["integrityCheck: { readonly ok: boolean; readonly rows: ReadonlyArray<string> }"],"sources":["../src/rekey.ts"],"sourcesContent":["/**\n * `rekeyDatabase` — re-keys an already encrypted SQLite database. The\n * runner backs `graphorin storage rekey`.\n *\n * Strategy: open the DB through the cipher peer with the **old** key,\n * then issue `PRAGMA rekey = <new>;`. The cipher peer rewrites every\n * page transactionally. After the pragma we re-open the DB with the\n * new key and run `PRAGMA cipher_integrity_check` to confirm the\n * rotation succeeded.\n *\n * @packageDocumentation\n */\n\nimport { existsSync } from 'node:fs';\nimport { isAbsolute, resolve } from 'node:path';\n\nimport {\n  DEFAULT_CIPHER,\n  type EncryptionCipher,\n  encodePassphraseForPragma,\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 rekeyDatabase}.\n *\n * @stable\n */\nexport interface RekeyDatabaseOptions {\n  /** Path to the encrypted DB. */\n  readonly path: string;\n  /** Existing passphrase the DB is currently encrypted with. */\n  readonly oldPassphrase: string | Buffer;\n  /** New passphrase to apply. */\n  readonly newPassphrase: string | Buffer;\n  /** Cipher selection. Default `'sqlcipher'`. */\n  readonly cipher?: EncryptionCipher;\n}\n\n/**\n * Result of a successful {@link rekeyDatabase} run.\n *\n * @stable\n */\nexport interface RekeyDatabaseResult {\n  readonly path: string;\n  readonly cipher: EncryptionCipher;\n  readonly integrityCheck: { readonly ok: boolean; readonly rows: ReadonlyArray<string> };\n}\n\n/**\n * Re-keys an encrypted SQLite database. Throws if the file is missing,\n * the cipher peer cannot be loaded, the old passphrase is wrong (the\n * cipher peer raises `SQLITE_NOTADB` on the first read), or the\n * post-rekey integrity check fails.\n *\n * @stable\n */\nexport async function rekeyDatabase(options: RekeyDatabaseOptions): Promise<RekeyDatabaseResult> {\n  const path = absolute(options.path);\n  const cipher = options.cipher ?? DEFAULT_CIPHER;\n\n  if (!existsSync(path)) {\n    throw new Error(`[graphorin/store-sqlite-encrypted] DB not found: ${path}`);\n  }\n\n  await loadCipherPeer();\n\n  const conn = await createEncryptedConnection({\n    path,\n    skipSqliteVec: true,\n    disableWalHardening: true,\n    encryption: {\n      enabled: true,\n      cipher,\n      passphraseResolver: async () => options.oldPassphrase,\n    },\n  });\n  try {\n    // Sanity-read forces the cipher peer to verify the old key before\n    // we rewrite pages with the new one.\n    conn.pragma('user_version');\n    // sqlite3mc refuses `rekey` in WAL journal mode (real-peer\n    // verified) — drop to DELETE for the rotation, restore after.\n    conn.pragma('journal_mode = DELETE');\n    const newEncoded = encodePassphraseForPragma(options.newPassphrase);\n    conn.pragma(`rekey = ${newEncoded}`);\n    conn.pragma('journal_mode = WAL');\n  } catch (err) {\n    if (conn.raw().open) conn.close();\n    throw new Error(`[graphorin/store-sqlite-encrypted] rekey failed: ${(err as Error).message}`, {\n      cause: err,\n    });\n  } finally {\n    if (conn.raw().open) conn.close();\n  }\n\n  const verify = await createEncryptedConnection({\n    path,\n    skipSqliteVec: true,\n    disableWalHardening: true,\n    encryption: {\n      enabled: true,\n      cipher,\n      passphraseResolver: async () => options.newPassphrase,\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    throw new Error(\n      '[graphorin/store-sqlite-encrypted] post-rekey integrity check failed: ' +\n        integrityCheck.rows.join('; '),\n    );\n  }\n\n  return Object.freeze({ path, cipher, integrityCheck: Object.freeze(integrityCheck) });\n}\n\nfunction absolute(p: string): string {\n  return isAbsolute(p) ? p : resolve(p);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4DA,eAAsB,cAAc,SAA6D;CAC/F,MAAM,OAAO,SAAS,QAAQ,KAAK;CACnC,MAAM,SAAS,QAAQ,UAAU;AAEjC,KAAI,CAAC,WAAW,KAAK,CACnB,OAAM,IAAI,MAAM,oDAAoD,OAAO;AAG7E,OAAM,gBAAgB;CAEtB,MAAM,OAAO,MAAM,0BAA0B;EAC3C;EACA,eAAe;EACf,qBAAqB;EACrB,YAAY;GACV,SAAS;GACT;GACA,oBAAoB,YAAY,QAAQ;GACzC;EACF,CAAC;AACF,KAAI;AAGF,OAAK,OAAO,eAAe;AAG3B,OAAK,OAAO,wBAAwB;EACpC,MAAM,aAAa,0BAA0B,QAAQ,cAAc;AACnE,OAAK,OAAO,WAAW,aAAa;AACpC,OAAK,OAAO,qBAAqB;UAC1B,KAAK;AACZ,MAAI,KAAK,KAAK,CAAC,KAAM,MAAK,OAAO;AACjC,QAAM,IAAI,MAAM,oDAAqD,IAAc,WAAW,EAC5F,OAAO,KACR,CAAC;WACM;AACR,MAAI,KAAK,KAAK,CAAC,KAAM,MAAK,OAAO;;CAGnC,MAAM,SAAS,MAAM,0BAA0B;EAC7C;EACA,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,GAClB,OAAM,IAAI,MACR,2EACE,eAAe,KAAK,KAAK,KAAK,CACjC;AAGH,QAAO,OAAO,OAAO;EAAE;EAAM;EAAQ,gBAAgB,OAAO,OAAO,eAAe;EAAE,CAAC;;AAGvF,SAAS,SAAS,GAAmB;AACnC,QAAO,WAAW,EAAE,GAAG,IAAI,QAAQ,EAAE"}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@graphorin/store-sqlite-encrypted",
+  "version": "0.5.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",
+  "homepage": "https://github.com/o-stepper/graphorin/tree/main/packages/store-sqlite-encrypted",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/o-stepper/graphorin.git",
+    "directory": "packages/store-sqlite-encrypted"
+  },
+  "bugs": {
+    "url": "https://github.com/o-stepper/graphorin/issues"
+  },
+  "keywords": [
+    "graphorin",
+    "ai",
+    "agents",
+    "framework",
+    "sqlite",
+    "sqlcipher",
+    "encryption",
+    "encryption-at-rest",
+    "better-sqlite3-multiple-ciphers",
+    "rekey",
+    "vacuum-into"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@graphorin/store-sqlite": "0.5.0"
+  },
+  "peerDependencies": {
+    "better-sqlite3-multiple-ciphers": "^12.9.0"
+  },
+  "peerDependenciesMeta": {
+    "better-sqlite3-multiple-ciphers": {
+      "optional": false
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@graphorin/security": "0.5.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.tests.json",
+    "test": "vitest run",
+    "lint": "biome check .",
+    "clean": "rimraf dist .turbo *.tsbuildinfo"
+  }
+}