@happyvertical/sql 0.89.3 → 0.89.5

package/dist/secure-sqlite-client.d.ts

@@ -0,0 +1,81 @@
+import { lstat, open } from 'node:fs/promises';
+export interface SecureSqliteStatement {
+    sql: string;
+    args?: unknown[];
+}
+export interface SecureSqliteResult {
+    rows: Record<string, unknown>[];
+    rowsAffected: number;
+    lastInsertRowid?: bigint;
+}
+export interface SecureSqliteTransactionClient {
+    readonly closed: boolean;
+    execute(statement: string | SecureSqliteStatement): Promise<SecureSqliteResult>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+    close(): void;
+}
+export interface SecureSqliteClient {
+    readonly transactionReservation: 'exclusive';
+    execute(statement: string | SecureSqliteStatement): Promise<SecureSqliteResult>;
+    transaction(mode?: string): Promise<SecureSqliteTransactionClient>;
+    close(): Promise<void>;
+}
+export interface SecureSqliteCustodyOptions {
+    custody: 'trusted-parent';
+    root?: string;
+}
+interface NodeSqliteStatement {
+    all(...args: unknown[]): Record<string, unknown>[];
+    columns(): Array<{
+        name: string;
+    }>;
+    run(...args: unknown[]): {
+        changes: number | bigint;
+        lastInsertRowid: number | bigint;
+    };
+    setReadBigInts(enabled: boolean): void;
+}
+interface NodeSqliteDatabase {
+    readonly isTransaction: boolean;
+    prepare(sql: string): NodeSqliteStatement;
+    close(): void;
+}
+interface NodeSqliteModule {
+    DatabaseSync: new (filename: string, options?: {
+        enableForeignKeyConstraints?: boolean;
+        enableDoubleQuotedStringLiterals?: boolean;
+    }) => NodeSqliteDatabase;
+}
+/** @internal Deterministic acquisition seam used by the integration tests. */
+export interface SecureSqliteRuntime {
+    platform: NodeJS.Platform;
+    nodeVersion?: string;
+    currentUid?: () => number;
+    pathOwnerUid?: (filePath: string, actualUid: number) => number;
+    inspectDarwinAcl?: (filePath: string) => Promise<boolean>;
+    openLeaf?: typeof open;
+    lstatLeaf?: typeof lstat;
+    loadDriver: () => Promise<NodeSqliteModule>;
+}
+/**
+ * @internal Parses the stable ACL section emitted by macOS `/bin/ls`.
+ * Returns true only when the ACL grants authority; deny-only ACLs are
+ * restrictive and do not weaken trusted-parent custody.
+ */
+export declare function parseDarwinAclListing(listing: string): boolean;
+/** @internal Exact public-contract range guard used by deterministic tests. */
+export declare function toPublicRowCount(value: number | bigint): number;
+/**
+ * Opens a local SQLite file under an explicit trusted-parent custody contract.
+ *
+ * Static path components and their ownership/mode are checked before the
+ * built-in `node:sqlite` driver opens the file. Other principals cannot replace
+ * a path beneath the caller-custodied parent. Hostile processes running as the
+ * same account are explicitly outside this boundary.
+ *
+ * @internal Call through `getDatabase()` with typed `secureFile` custody.
+ */
+export declare function createSecureSqliteClient(url: string, options: SecureSqliteCustodyOptions, runtime?: SecureSqliteRuntime): Promise<SecureSqliteClient>;
+export {};
+//# sourceMappingURL=secure-sqlite-client.d.ts.map

package/dist/secure-sqlite-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secure-sqlite-client.d.ts","sourceRoot":"","sources":["../src/secure-sqlite-client.ts"],"names":[],"mappings":"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"}

package/dist/shared/sqlite-connection-cache.d.ts

@@ -1,4 +1,4 @@
 import { DatabaseInterface, DatabaseOptions } from './types';
-export type SqliteAdapterPath = 'libsql' | 'native';
+export type SqliteAdapterPath = 'libsql' | 'native' | 'secure';
 export declare function getCachedSqliteDatabase(path: SqliteAdapterPath, options: DatabaseOptions, create: () => Promise<DatabaseInterface>): Promise<DatabaseInterface>;
 //# sourceMappingURL=sqlite-connection-cache.d.ts.map

package/dist/shared/sqlite-connection-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sqlite-connection-cache.d.ts","sourceRoot":"","sources":["../../src/shared/sqlite-connection-cache.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAElE,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAsEpD,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,iBAAiB,EACvB,OAAO,EAAE,eAAe,EACxB,MAAM,EAAE,MAAM,OAAO,CAAC,iBAAiB,CAAC,GACvC,OAAO,CAAC,iBAAiB,CAAC,CA+B5B"}
+{"version":3,"file":"sqlite-connection-cache.d.ts","sourceRoot":"","sources":["../../src/shared/sqlite-connection-cache.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAElE,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AA0E/D,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,iBAAiB,EACvB,OAAO,EAAE,eAAe,EACxB,MAAM,EAAE,MAAM,OAAO,CAAC,iBAAiB,CAAC,GACvC,OAAO,CAAC,iBAAiB,CAAC,CAqC5B"}

package/dist/shared/transaction-lock.d.ts

@@ -10,6 +10,8 @@ export declare const DEFAULT_TRANSACTION_QUEUE_TIMEOUT_MS = 30000;
  * Serializes transactions on a connection that cannot hold more than one.
  */
 export interface TransactionLock {
+    /** Whether one caller currently owns the connection. */
+    readonly held: boolean;
     /**
      * Takes the connection and returns the function that gives it back.
      *

package/dist/shared/transaction-lock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transaction-lock.d.ts","sourceRoot":"","sources":["../../src/shared/transaction-lock.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,eAAO,MAAM,oCAAoC,QAAS,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,OAAO,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC;IAE/B;;;OAGG;IACH,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,MAA6C,GACvD,eAAe,CAoEjB"}
+{"version":3,"file":"transaction-lock.d.ts","sourceRoot":"","sources":["../../src/shared/transaction-lock.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,eAAO,MAAM,oCAAoC,QAAS,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAEvB;;;;;OAKG;IACH,OAAO,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC;IAE/B;;;OAGG;IACH,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,MAA6C,GACvD,eAAe,CA6EjB"}

package/dist/sqlite.d.ts

@@ -1,4 +1,26 @@
 import { DatabaseInterface, DatabaseOptions, SqliteCapabilitiesOptions } from './shared/types';
+export declare function toSafeSqliteCount(value: unknown): number;
+/** Options for the trusted-parent SQLite file acquisition boundary. */
+export interface SecureSqliteFileOptions {
+    /**
+     * Built-in driver that owns the secure acquisition and exact integer path.
+     *
+     * @default 'node:sqlite'
+     */
+    driver: 'node:sqlite';
+    /**
+     * Assert that the application controls the database parent directory.
+     * The adapter verifies current-user ownership, non-writable group/other
+     * permissions, current-user/root ancestor ownership, static symlink absence,
+     * and no macOS ACL before acquisition.
+     */
+    custody: 'trusted-parent';
+    /**
+     * Optional application data root. Defaults to the database's direct parent.
+     * Every database parent at or below this root must satisfy the custody check.
+     */
+    root?: string;
+}
 /**
  * Configuration options for SQLite database connections
  */
@@ -35,6 +57,19 @@ export interface SqliteOptions extends DatabaseOptions {
      * capabilities are only supported for local SQLite databases.
      */
     capabilities?: SqliteCapabilitiesOptions;
+    /**
+     * Require trusted-parent acquisition for a local file-backed database.
+     *
+     * This requires an explicit `trusted-parent` custody assertion, verifies the
+     * application data root/parent chain and rejects static symlinks before the
+     * built-in `node:sqlite` driver opens the file. Other principals cannot
+     * replace a path under the custodied parent. It does not claim protection
+     * from a hostile same-account process, which can directly replace or rewrite
+     * an unencrypted user-owned database.
+     *
+     * Existing pathname behavior is unchanged when omitted or false.
+     */
+    secureFile?: boolean | SecureSqliteFileOptions;
     /**
      * How long a queued transaction waits for the connection, in milliseconds.
      *

package/dist/sqlite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sqlite.d.ts","sourceRoot":"","sources":["../src/sqlite.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAGV,iBAAiB,EACjB,eAAe,EAIf,yBAAyB,EAK1B,MAAM,gBAAgB,CAAC;AAoIxB;;GAEG;AACH,MAAM,WAAW,aAAc,SAAQ,eAAe;IACpD;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,yBAAyB,CAAC;IAEzC;;;;;;;;;;;;;;;;;;OAkBG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC;IAEjC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,OAAO,gBAAgB,EAAE,aAAa,CAAC;CAClD;AA+ED;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,iBAAiB,CAAC,CAkB5B"}
+{"version":3,"file":"sqlite.d.ts","sourceRoot":"","sources":["../src/sqlite.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAGV,iBAAiB,EACjB,eAAe,EAIf,yBAAyB,EAK1B,MAAM,gBAAgB,CAAC;AAsKxB,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CASxD;AAixBD,uEAAuE;AACvE,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,MAAM,EAAE,aAAa,CAAC;IAEtB;;;;;OAKG;IACH,OAAO,EAAE,gBAAgB,CAAC;IAE1B;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,aAAc,SAAQ,eAAe;IACpD;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,yBAAyB,CAAC;IAEzC;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,EAAE,OAAO,GAAG,uBAAuB,CAAC;IAE/C;;;;;;;;;;;;;;;;;;OAkBG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC;IAEjC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,OAAO,gBAAgB,EAAE,aAAa,CAAC;CAClD;AA+ED;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,iBAAiB,CAAC,CAuE5B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/sql",
-  "version": "0.89.3",
+  "version": "0.89.5",
   "description": "Database interface with support for SQLite, PostgreSQL, and DuckDB",
   "type": "module",
   "main": "./dist/index.js",
@@ -46,7 +46,7 @@
     "@libsql/client": "0.17.2",
     "pg": "^8.20.0",
     "sqlite-vss": "^0.1.2",
-    "@happyvertical/utils": "0.89.3"
+    "@happyvertical/utils": "0.89.5"
   },
   "peerDependencies": {
     "@russellthehippo/honker-node": "^0.3.3",
@@ -71,10 +71,11 @@
   "scripts": {
     "test": "vitest --config ../../vitest.package.config.ts run",
     "test:watch": "vitest --config ../../vitest.package.config.ts",
-    "test:sqlite": "vitest --config ../../vitest.package.config.ts run src/sqlite.spec.ts src/count.spec.ts",
+    "test:sqlite": "vitest --config ../../vitest.package.config.ts run src/sqlite.spec.ts src/secure-sqlite.spec.ts src/count.spec.ts",
     "test:postgres": "node ../../scripts/run-with-ci-postgres.mjs -- vitest --config ../../vitest.package.config.ts run src/postgres.spec.ts src/postgres-vector.spec.ts src/postgres-connection-lifecycle.spec.ts src/postgres-nested-transaction.spec.ts src/postgres-transaction-errors.spec.ts src/transaction-schema-scope.spec.ts src/identifier-injection.spec.ts src/postgres-insert-column-binding.spec.ts src/postgres-count.spec.ts src/contains.spec.ts",
     "test:duckdb": "vitest --config ../../vitest.package.config.ts run src/duckdb.spec.ts src/count.spec.ts",
     "build": "vite build",
+    "typecheck": "tsc --noEmit",
     "build:watch": "vite build --watch",
     "docs": "typedoc --plugin typedoc-plugin-markdown --out docs --entryPoints ./src/index.ts --tsconfig ./tsconfig.json --excludePrivate --excludeInternal --hideGenerator --fileExtension .md --readme none --categorizeByGroup false --includeVersion false --hidePageHeader --hidePageTitle false --outputFileStrategy modules",
     "docs:watch": "typedoc --plugin typedoc-plugin-markdown --out docs --entryPoints ./src/index.ts --tsconfig ./tsconfig.json --excludePrivate --excludeInternal --hideGenerator --fileExtension .md --readme none --categorizeByGroup false --includeVersion false --hidePageHeader --hidePageTitle false --outputFileStrategy modules --watch",