@chipmobilesdk/rn-local-db 0.1.0

package/src/adapter/index.ts

@@ -0,0 +1,68 @@
+/**
+ * The public lifecycle functions.
+ *
+ * Scope deletion and reset are module-level rather than handle methods: they
+ * must work whether or not a handle is open on the target (FR-059), and
+ * `resetScope` in particular must never be reachable as a fallback from
+ * `openDatabase` (FR-057a).
+ *
+ * The active adapter is resolved lazily so a consuming app that only ever
+ * uses the in-memory adapter in tests never loads the native peers.
+ */
+
+import type { DatabaseHandle, StorageAdapter } from '../contract/adapter';
+import type {
+	DatabaseConfig,
+	DatabaseTargetConfig,
+	ScopeTargetConfig,
+} from '../contract/config';
+import type { DeletionOutcome } from '../contract/attachment';
+
+let override: StorageAdapter | null = null;
+let cached: StorageAdapter | null = null;
+
+/**
+ * Swap the adapter. Intended for tests and for the demo app's in-memory
+ * mode; production code never calls this.
+ */
+export function setStorageAdapter(adapter: StorageAdapter | null): void {
+	override = adapter;
+}
+
+function activeAdapter(): StorageAdapter {
+	if (override) {
+		return override;
+	}
+	if (!cached) {
+		// Lazy require, matching how rn-auth and rn-camera reach their native
+		// peers: importing at module scope would pull op-sqlite into every
+		// consumer, including ones that only run the in-memory adapter.
+		const { createSqliteAdapter } = require('../sqlite/adapter') as {
+			createSqliteAdapter: () => StorageAdapter;
+		};
+		cached = createSqliteAdapter();
+	}
+	return cached;
+}
+
+export function openDatabase(config: DatabaseConfig): Promise<DatabaseHandle> {
+	return activeAdapter().open(config);
+}
+
+export function deleteScopeData(config: ScopeTargetConfig): Promise<DeletionOutcome> {
+	return activeAdapter().deleteScopeData(config);
+}
+
+export function deleteDatabase(config: DatabaseTargetConfig): Promise<DeletionOutcome> {
+	return activeAdapter().deleteDatabase(config);
+}
+
+/**
+ * Destructive. Discards one scope's data and leaves it ready for a clean
+ * first-run migration. Named apart from `deleteScopeData` deliberately: one
+ * is a lifecycle operation, the other is an admission that a database is
+ * broken.
+ */
+export function resetScope(config: ScopeTargetConfig): Promise<DeletionOutcome> {
+	return activeAdapter().resetScope(config);
+}

package/src/adapter/lifecycle.ts

@@ -0,0 +1,444 @@
+/**
+ * Opening and closing a database.
+ *
+ * The order of operations here is the design, not an implementation detail:
+ *
+ * 1. **Validate everything first.** Configuration, scope, and the migration
+ *    chain are checked before a file is touched, so a developer error is
+ *    reported against an untouched database (FR-006, FR-053).
+ * 2. **Consult the catalog before opening the scope file.** A posture
+ *    mismatch is detectable there; discovering it from SQLCipher's "file is
+ *    not a database" would report corruption for what is actually an app
+ *    configuration change (FR-101).
+ * 3. **Migrate before returning.** Nothing observes a half-migrated schema,
+ *    because there is no handle to observe it with until the chain completes
+ *    (FR-055). A failure returns no handle at all (FR-050).
+ *
+ * Scope is bound here and nowhere else. The handle carries its scope key and
+ * no operation on it accepts a scope argument, so there is no `switchScope`
+ * to misuse and no read that could address another scope (FR-008a, FR-015).
+ * SC-002a's "a leak is not expressible" is this shape plus one file per
+ * scope — not a check somewhere that could be forgotten.
+ */
+
+import type { Attachments, DatabaseHandle } from '../contract/adapter';
+import type {
+	AttachmentInput,
+	AttachmentOwner,
+	ByteRange,
+	DeletionOutcome,
+	ReconciliationReport,
+} from '../contract/attachment';
+import type { EffectivePosture } from '../contract/backup';
+import type { DatabaseConfig } from '../contract/config';
+import { DiagnosticCodes } from '../contract/errors';
+import type { IndexCoverageReport, Query } from '../contract/query';
+import type { StorableRecordData } from '../contract/record';
+import type { CollectionSchema } from '../contract/schema';
+import type { ResolvedScope } from '../contract/scope';
+import type {
+	BatchOperation,
+	BatchOutcome,
+	CollectionOps,
+	Transaction,
+} from '../contract/transaction';
+import { artifactAvailability } from '../artifacts/availability';
+import { cascadeForOwner } from '../artifacts/cascade';
+import { reconcileArtifacts } from '../artifacts/reconcile';
+import {
+	ensureAttachmentTable,
+	listReferencesFor,
+	readArtifact,
+	removeArtifact,
+	writeArtifact,
+	type ArtifactContext,
+} from '../artifacts/store';
+import { deriveArtifactKey } from '../crypto/derive';
+import { acquireKey, type KeyHandle } from '../crypto/key-provider';
+import { isCipherAvailable } from '../crypto/provider';
+import { raise } from '../diagnostics/errors';
+import { instrument } from '../diagnostics/dev-log';
+import { throwIfFaulted } from '../diagnostics/faults';
+import { runMigrations } from '../migration/executor';
+import { effectivePostureFor } from '../platform/backup-android-verify';
+import { ensureManagedRoot, iosPosture } from '../platform/backup-ios';
+import { layoutFor, type StorageLayout } from '../platform/location';
+import { withStableTiebreaker } from '../query/sort';
+import { indexSchemas } from '../schema/declare';
+import { validateConfig } from '../schema/validate-config';
+import { resolveScope } from '../scope/validate';
+import { runBatch } from '../sqlite/batch';
+import { ensureCatalog, readEntry, registerScope } from '../sqlite/catalog';
+import { assertReadable, openConnection, type Connection } from '../sqlite/connection';
+import { explainQuery } from '../sqlite/index-coverage';
+import { isEncryptionAvailable } from '../sqlite/native';
+import { addColumnSql, createIndexSql, createTableSql } from '../sqlite/row-codec';
+import { runInTransaction } from '../sqlite/transactions';
+import { text } from '../sqlite/values';
+import { acquireHandleSlot, releaseHandleSlot } from './budgets';
+import { createSqlCollection } from './collection';
+import { clearScopeInvalidation, isScopeInvalidated } from './deletion';
+import { createTransaction } from './transaction';
+
+export type OpenOptions = {
+	now?: () => number;
+};
+
+/**
+ * Bring the physical tables in line with the declared schema.
+ *
+ * Adding a column rather than recreating the table is what makes declaring a
+ * new queryable field non-destructive: the payload already holds the value,
+ * so the new column is backfilled from it and no record is rewritten by hand
+ * (research.md R6).
+ */
+async function ensureCollection(
+	connection: Connection,
+	schema: CollectionSchema,
+): Promise<void> {
+	await connection.execute(createTableSql(schema));
+
+	const info = await connection.execute(
+		`PRAGMA table_info("c_${schema.name}")`,
+	);
+	const present = new Set(info.rows.map(row => text(row.name)));
+
+	for (const field of schema.fields ?? []) {
+		const column = `f_${field.name}`;
+		if (present.has(column)) {
+			continue;
+		}
+		await connection.execute(addColumnSql(schema, field));
+		await connection.execute(
+			`UPDATE "c_${schema.name}" SET "${column}" = json_extract(payload, '$.${field.name}')`,
+		);
+	}
+
+	for (const statement of createIndexSql(schema)) {
+		await connection.execute(statement);
+	}
+}
+
+function resolveEncryption(config: DatabaseConfig): boolean {
+	if (config.encryption?.enabled !== true) {
+		return false;
+	}
+	// Writing plaintext to a file the app believes is encrypted is the one
+	// outcome worse than refusing to open (research.md R1a).
+	if (!isEncryptionAvailable()) {
+		raise(DiagnosticCodes.ENCRYPTION_UNAVAILABLE, {
+			message: 'encryption was requested but SQLCipher is not compiled into this build',
+		});
+	}
+	if (!isCipherAvailable()) {
+		raise(DiagnosticCodes.ENCRYPTION_UNAVAILABLE, {
+			message: 'encryption was requested but the cipher peer is not installed',
+		});
+	}
+	return true;
+}
+
+async function assertPostureMatches(
+	catalog: Connection,
+	scope: ResolvedScope,
+	encrypted: boolean,
+): Promise<void> {
+	const entry = await readEntry(catalog, scope.key);
+	if (!entry) {
+		return;
+	}
+	if (entry.deletionState === 'deleting') {
+		// An interrupted deletion is reported rather than opened over: the
+		// scope is neither present nor gone, and presenting it as healthy is
+		// the one answer FR-063 forbids. `deleteScopeData` finishes the job.
+		raise(DiagnosticCodes.SCOPE_DELETED, {
+			message: 'a previous deletion of this scope was interrupted',
+			detail: { scopeKey: scope.key },
+		});
+	}
+	if (entry.encrypted !== encrypted) {
+		// In-place conversion is not supported this phase (FR-103). Reporting
+		// the mismatch lets an app migrate deliberately; opening would either
+		// fail obscurely or write the wrong posture.
+		raise(DiagnosticCodes.ENCRYPTION_MISMATCH, {
+			message: 'encryption posture does not match the stored database',
+			detail: { scopeKey: scope.key },
+		});
+	}
+}
+
+export async function openSqliteDatabase(
+	config: DatabaseConfig,
+	options: OpenOptions = {},
+): Promise<DatabaseHandle> {
+	const now = options.now ?? (() => Date.now());
+
+	validateConfig(config);
+	throwIfFaulted('open');
+	const scope = resolveScope(config.scope);
+	const encrypted = resolveEncryption(config);
+	const includeInBackup = config.backup?.includeInPlatformBackup === true;
+
+	const layout: StorageLayout = layoutFor(config.name);
+	await ensureManagedRoot(layout, includeInBackup);
+
+	const catalog = await openConnection({ path: layout.catalogPath });
+	let key: KeyHandle | null = null;
+	let connection: Connection | null = null;
+	let released = false;
+
+	const releaseConnection = async (): Promise<void> => {
+		if (released || !connection) {
+			return;
+		}
+		released = true;
+		await connection.close();
+		releaseHandleSlot();
+	};
+
+	try {
+		await ensureCatalog(catalog);
+		await assertPostureMatches(catalog, scope, encrypted);
+
+		if (encrypted) {
+			key = await acquireKey(config.encryption!, scope);
+		}
+
+		acquireHandleSlot();
+		try {
+			connection = await openConnection({
+				path: layout.scopeDataPath(scope.key),
+				...(key ? { encryptionKey: key.value() } : {}),
+			});
+		} catch (error) {
+			releaseHandleSlot();
+			throw error;
+		}
+		await assertReadable(connection);
+
+		const schemas = indexSchemas(config.collections);
+		for (const schema of config.collections) {
+			await ensureCollection(connection, schema);
+		}
+		await ensureAttachmentTable(connection);
+
+		const scopeConnection = connection;
+		const schemaVersion = await runMigrations({
+			connection: scopeConnection,
+			config,
+			schemaFor: name => schemaFor(schemas, name),
+			now,
+			closeOnFailure: releaseConnection,
+		});
+
+		await registerScope(catalog, {
+			scopeKey: scope.key,
+			createdAt: now(),
+			deletionState: 'active',
+			backupPosture: includeInBackup ? 'included' : 'excluded',
+			encrypted,
+		});
+		await catalog.close();
+		clearScopeInvalidation(config.name, scope.key);
+
+		return buildHandle({
+			config,
+			connection: scopeConnection,
+			key,
+			layout,
+			now,
+			schemaVersion,
+			schemas,
+			scope,
+			posture: effectivePostureFor(layout, includeInBackup, iosPosture),
+		});
+	} catch (error) {
+		// No usable handle after a failed open (FR-002). Anything already
+		// acquired is released here rather than left for a caller who is about
+		// to be handed an exception instead of a handle.
+		key?.release();
+		await releaseConnection();
+		await catalog.close();
+		throw error;
+	}
+}
+
+function schemaFor(
+	schemas: ReadonlyMap<string, CollectionSchema>,
+	name: string,
+): CollectionSchema {
+	const schema = schemas.get(name);
+	if (!schema) {
+		raise(DiagnosticCodes.CONFIG_INVALID, {
+			message: 'collection is not declared',
+			detail: { collection: name },
+		});
+	}
+	return schema;
+}
+
+type HandleContext = {
+	config: DatabaseConfig;
+	connection: Connection;
+	key: KeyHandle | null;
+	layout: StorageLayout;
+	now(): number;
+	schemaVersion: number;
+	schemas: ReadonlyMap<string, CollectionSchema>;
+	scope: ResolvedScope;
+	posture: EffectivePosture;
+};
+
+function buildHandle(context: HandleContext): DatabaseHandle {
+	const { config, connection, layout, scope, schemas } = context;
+	let closed = false;
+
+	const assertUsable = (): void => {
+		if (closed) {
+			raise(DiagnosticCodes.CLOSED_HANDLE, { message: 'handle is closed' });
+		}
+		if (isScopeInvalidated(config.name, scope.key)) {
+			// The deletion did not wait for this handle, and this handle does
+			// not get to keep answering from data that is gone (FR-059a).
+			raise(DiagnosticCodes.SCOPE_DELETED, {
+				message: 'scope was deleted beneath this handle',
+				detail: { scopeKey: scope.key },
+			});
+		}
+	};
+
+	const artifacts: ArtifactContext = {
+		executor: () => connection,
+		layout,
+		scopeKey: scope.key,
+		artifactKey: attachmentId =>
+			context.key ? deriveArtifactKey(context.key.value(), scope.key, attachmentId) : null,
+		now: context.now,
+	};
+
+	const rawCollection = <T extends StorableRecordData>(name: string): CollectionOps<T> => {
+		assertUsable();
+		return instrument(
+			name,
+			'sqlite',
+			createSqlCollection<T>({
+				executor: () => connection,
+				schema: schemaFor(schemas, name),
+				now: context.now,
+				assertUsable,
+			}) as unknown as Record<string, (...args: never[]) => unknown>,
+		) as unknown as CollectionOps<T>;
+	};
+
+	/**
+	 * Record deletion optionally takes its artifacts with it (FR-070).
+	 *
+	 * Off unless the app asks: a package that deleted a user's files as a side
+	 * effect of a record delete would be making a decision that is not its to
+	 * make.
+	 */
+	const collectionFor = <T extends StorableRecordData>(name: string): CollectionOps<T> => {
+		const ops = rawCollection<T>(name);
+		if (config.cascadeAttachments !== true) {
+			return ops;
+		}
+		return {
+			...ops,
+			async delete(id: string) {
+				const outcome = await ops.delete(id);
+				await cascadeForOwner(artifacts, connection, { collection: name, id });
+				return outcome;
+			},
+		};
+	};
+
+	const attachments: Attachments = {
+		write(input: AttachmentInput) {
+			assertUsable();
+			return writeArtifact(artifacts, input);
+		},
+		read(id: string, range?: ByteRange) {
+			assertUsable();
+			return readArtifact(artifacts, id, range);
+		},
+		availability(id: string) {
+			assertUsable();
+			return artifactAvailability(artifacts, connection, id);
+		},
+		remove(id: string): Promise<DeletionOutcome> {
+			assertUsable();
+			return removeArtifact(artifacts, id);
+		},
+		listFor(owner: AttachmentOwner) {
+			assertUsable();
+			return listReferencesFor(connection, owner);
+		},
+		reconcile(options): Promise<ReconciliationReport> {
+			assertUsable();
+			return reconcileArtifacts(artifacts, connection, options);
+		},
+	};
+
+	const handle: DatabaseHandle = {
+		scopeKey: scope.key,
+		schemaVersion: context.schemaVersion,
+		backupPosture: context.posture,
+		isEncrypted: context.key !== null,
+
+		collection: collectionFor,
+
+		async transaction<R>(fn: (tx: Transaction) => Promise<R>): Promise<R> {
+			assertUsable();
+			return runInTransaction(connection, async tx => {
+				const managed = createTransaction({
+					collection: collectionFor,
+					rollback: () => tx.rollback(),
+				});
+				const result = await fn(managed.transaction);
+				if (!managed.isSettled()) {
+					throwIfFaulted('commit');
+				}
+				managed.settle();
+				return result;
+			});
+		},
+
+		batch(operations: BatchOperation[]): Promise<BatchOutcome> {
+			assertUsable();
+			return runBatch(
+				{
+					connection,
+					schemaFor: name => schemaFor(schemas, name),
+					now: context.now,
+				},
+				operations,
+			);
+		},
+
+		attachments: () => attachments,
+
+		explain(collection: string, query?: Query): Promise<IndexCoverageReport> {
+			assertUsable();
+			return explainQuery(
+				connection,
+				schemaFor(schemas, collection),
+				query,
+				withStableTiebreaker(query?.sort),
+			);
+		},
+
+		async close(): Promise<void> {
+			if (closed) {
+				return;
+			}
+			closed = true;
+			// The key goes first: a close that fails at the filesystem must not
+			// leave key material alive in a handle nobody can use (FR-098).
+			context.key?.release();
+			await connection.close();
+			releaseHandleSlot();
+		},
+	};
+
+	return handle;
+}

package/src/adapter/transaction.ts

@@ -0,0 +1,65 @@
+/**
+ * The `Transaction` a consumer actually holds.
+ *
+ * Two rules live here rather than in either adapter, so both are held to the
+ * same standard:
+ *
+ * **Read-your-own-writes** (FR-043). Every collection reached through `tx`
+ * runs against the transaction's executor, so a read inside sees the writes
+ * made inside. A collection reached through the handle during a transaction
+ * would not, and handing one out would be a quiet correctness trap.
+ *
+ * **Terminal state is terminal** (FR-044). After a commit or an abort, using
+ * the transaction raises rather than silently writing outside it — the
+ * failure mode where a caller's cleanup code lands in the database after the
+ * rollback it was supposed to be part of.
+ */
+
+import { DiagnosticCodes } from '../contract/errors';
+import type { StorableRecordData } from '../contract/record';
+import type { CollectionOps, Transaction } from '../contract/transaction';
+import { raise } from '../diagnostics/errors';
+
+export type TransactionHost = {
+	collection<T extends StorableRecordData>(name: string): CollectionOps<T>;
+	rollback(): Promise<void>;
+};
+
+export type ManagedTransaction = {
+	transaction: Transaction;
+	/** True once the body committed or aborted. */
+	isSettled(): boolean;
+	settle(): void;
+};
+
+export function createTransaction(host: TransactionHost): ManagedTransaction {
+	let settled = false;
+
+	const assertLive = (): void => {
+		if (settled) {
+			raise(DiagnosticCodes.TRANSACTION_STATE, {
+				message: 'transaction already settled',
+			});
+		}
+	};
+
+	const transaction: Transaction = {
+		collection<T extends StorableRecordData>(name: string): CollectionOps<T> {
+			assertLive();
+			return host.collection<T>(name);
+		},
+		async abort(): Promise<void> {
+			assertLive();
+			settled = true;
+			await host.rollback();
+		},
+	};
+
+	return {
+		transaction,
+		isSettled: () => settled,
+		settle: () => {
+			settled = true;
+		},
+	};
+}

package/src/artifacts/availability.ts

@@ -0,0 +1,69 @@
+/**
+ * "Is this artifact still there?", answered without opening it.
+ *
+ * `stat()` and, for an encrypted artifact, the 22-byte header. Never a
+ * content byte and never a decryption (FR-073e, FR-107b). An availability
+ * check that decrypted would make a gallery screen showing fifty thumbnails
+ * decrypt fifty artifacts to answer a question none of them asked, and would
+ * put key material in play for an operation that does not need it.
+ *
+ * The four states are deliberately four rather than two. `missing` is data
+ * that is gone; `undecryptable` is data that exists under a key that does not
+ * open it, which is often recoverable and always a different conversation to
+ * have with the user (FR-107c).
+ */
+
+import type { AttachmentAvailability } from '../contract/attachment';
+import { fileSystem } from '../platform/fs';
+import { HEADER_BYTES, MAGIC } from '../crypto/chunked-cipher';
+import type { Executor } from '../sqlite/connection';
+import { artifactPath } from './paths';
+import { readReference, type ArtifactContext } from './store';
+
+export async function artifactAvailability(
+	context: ArtifactContext,
+	executor: Executor,
+	id: string,
+): Promise<AttachmentAvailability> {
+	const reference = await readReference(executor, id);
+	if (!reference) {
+		// No reference is "missing" rather than an error: the caller asked
+		// about an artifact this scope does not claim to have.
+		return { id, state: 'missing' };
+	}
+
+	const path = artifactPath(context.layout, context.scopeKey, id);
+
+	let size: number;
+	try {
+		const stat = await fileSystem().stat(path);
+		if (!stat.isFile()) {
+			return { id, state: 'inaccessible' };
+		}
+		size = stat.size;
+	} catch {
+		return { id, state: 'missing' };
+	}
+
+	if (context.artifactKey(id) === null) {
+		return { id, state: 'available', size: reference.size };
+	}
+
+	if (size < HEADER_BYTES) {
+		return { id, state: 'undecryptable', size: reference.size };
+	}
+
+	try {
+		const header = Buffer.from(
+			await fileSystem().read(path, HEADER_BYTES, 0, 'base64'),
+			'base64',
+		);
+		if (header.toString('ascii', 0, 4) !== MAGIC) {
+			return { id, state: 'undecryptable', size: reference.size };
+		}
+	} catch {
+		return { id, state: 'inaccessible', size: reference.size };
+	}
+
+	return { id, state: 'available', size: reference.size };
+}