@chipmobilesdk/rn-local-db 0.1.0

package/src/index.ts

@@ -0,0 +1,110 @@
+/**
+ * `@chipmobilesdk/rn-local-db`
+ *
+ * Offline-first, scope-isolated local storage for ChipMobileSdk apps.
+ *
+ * What is deliberately absent is part of the contract: there is no
+ * `switchScope`, and no read, write, or query operation accepts a scope
+ * argument. Scope is bound to a handle at open time and immutable, so a
+ * cross-scope leak is not expressible rather than merely prevented.
+ *
+ * The underlying engine, the physical layout, key material, and the query
+ * translation are private and unreachable by deep import.
+ */
+
+// Lifecycle
+export {
+	deleteDatabase,
+	deleteScopeData,
+	openDatabase,
+	resetScope,
+} from './adapter';
+
+// Diagnostics
+export {
+	DiagnosticCodes,
+	StorageError,
+	isCode,
+	isStorageError,
+} from './diagnostics/errors';
+export { setDiagnosticLogger, type DiagnosticLogger } from './diagnostics/dev-log';
+
+// Budgets, so a consumer can check before it writes rather than after
+export { Budgets } from './contract/config';
+
+// Contract types
+export type {
+	DatabaseConfig,
+	DatabaseTargetConfig,
+	ScopeTargetConfig,
+} from './contract/config';
+export type {
+	ResolvedScope,
+	ScopeDescriptor,
+	ScopeKind,
+} from './contract/scope';
+export type {
+	CollectionSchema,
+	FieldDeclaration,
+	FieldType,
+	IndexDeclaration,
+} from './contract/schema';
+export type {
+	RecordInput,
+	StorableRecordData,
+	StorableValue,
+	StoredRecord,
+	WriteOperation,
+	WriteOutcome,
+} from './contract/record';
+export type {
+	ComparisonNode,
+	FilterNode,
+	FilterValue,
+	IndexCoverageReport,
+	LogicalNode,
+	PageRequest,
+	Query,
+	ResultPage,
+	SortDirection,
+	SortKey,
+} from './contract/query';
+export type {
+	BatchOperation,
+	BatchOutcome,
+	CollectionOps,
+	Transaction,
+} from './contract/transaction';
+export type {
+	Migration,
+	MigrationContext,
+	MigrationFailureDetail,
+	MigrationLedgerEntry,
+	MigrationOutcome,
+} from './contract/migration';
+export type {
+	AttachmentAvailability,
+	AttachmentAvailabilityState,
+	AttachmentInput,
+	AttachmentOwner,
+	AttachmentReference,
+	ByteRange,
+	DeletionOutcome,
+	ReconciliationReport,
+} from './contract/attachment';
+export type {
+	EncryptionConfig,
+	EncryptionPosture,
+	KeyProvider,
+} from './contract/encryption';
+export type {
+	BackupConfig,
+	BackupPostureValue,
+	EffectivePosture,
+} from './contract/backup';
+export type { DiagnosticCode } from './contract/errors';
+export type {
+	Attachments,
+	DatabaseHandle,
+	StorageAdapter,
+} from './contract/adapter';

package/src/migration/executor.ts

@@ -0,0 +1,136 @@
+/**
+ * The migration executor.
+ *
+ * Four rules, each of which exists because the alternative loses data:
+ *
+ * - **Ascending, and pending only.** A migration whose version is at or below
+ *   the recorded one has already run against this scope (FR-047, FR-049).
+ * - **One transaction per migration.** A failure unwinds that migration and
+ *   nothing else, so the recorded version and the data always agree.
+ * - **The recorded version moves only on success**, inside the same
+ *   transaction as the migration's own writes. Writing it separately would
+ *   leave a window where a crash records a migration that did not happen.
+ * - **A failure returns no handle** (FR-050). Half-migrated data behind a
+ *   working handle is the failure this whole design exists to prevent, and it
+ *   is worse than being unable to open at all: the app writes to it.
+ *
+ * A retry starts from the same version rather than skipping ahead (FR-051),
+ * which is what makes a transient failure — a locked keychain, a full disk
+ * mid-migration — recoverable on the next launch instead of permanent.
+ */
+
+import type { DatabaseConfig } from '../contract/config';
+import { DiagnosticCodes } from '../contract/errors';
+import type { MigrationContext } from '../contract/migration';
+import type { StorableRecordData } from '../contract/record';
+import type { CollectionSchema } from '../contract/schema';
+import type { CollectionOps } from '../contract/transaction';
+import { raise } from '../diagnostics/errors';
+import { throwIfFaulted } from '../diagnostics/faults';
+import { createSqlCollection } from '../adapter/collection';
+import type { Connection, Executor } from '../sqlite/connection';
+import { ensureLedger, readSchemaVersion, recordAttempt, writeSchemaVersion } from './ledger';
+import { pendingMigrations, validateMigrationChain } from './validate-chain';
+
+export type MigrationRunContext = {
+	connection: Connection;
+	config: DatabaseConfig;
+	schemaFor(name: string): CollectionSchema;
+	now(): number;
+	/**
+	 * Called before a migration failure is raised. The executor does not own
+	 * the connection, so it asks rather than closing directly — but the close
+	 * has to happen before the error escapes, or a caller catching it could
+	 * still be holding something usable (FR-050).
+	 */
+	closeOnFailure(): Promise<void>;
+};
+
+function migrationContextFor(
+	context: MigrationRunContext,
+	executor: Executor,
+): MigrationContext {
+	return {
+		collection<T extends StorableRecordData>(name: string): CollectionOps<T> {
+			return createSqlCollection<T>({
+				executor: () => executor,
+				schema: context.schemaFor(name),
+				now: context.now,
+				// Inside a migration the handle does not exist yet, so there is
+				// no closed-handle or deleted-scope state to guard against.
+				assertUsable: () => {},
+			});
+		},
+		async abort(): Promise<void> {
+			// A migration that wants to give up should throw; aborting the
+			// transaction from inside while the executor still believes it is
+			// running would record an outcome that never happened.
+			raise(DiagnosticCodes.TRANSACTION_STATE, {
+				message: 'a migration cannot abort its own transaction',
+			});
+		},
+		async execute(sql: string, params?: unknown[]): Promise<void> {
+			await executor.execute(sql, params as never);
+		},
+	};
+}
+
+export async function runMigrations(context: MigrationRunContext): Promise<number> {
+	const { config, connection } = context;
+	validateMigrationChain(config);
+	await ensureLedger(connection);
+
+	const recorded = await readSchemaVersion(connection);
+
+	if (recorded > config.schemaVersion) {
+		// Opening anyway would mean newer data read by older code, which drops
+		// whatever the newer schema added — silently, and on write (FR-052).
+		await context.closeOnFailure();
+		raise(DiagnosticCodes.SCHEMA_DOWNGRADE, {
+			message: 'recorded schema version is newer than the declared one',
+			detail: { recordedVersion: recorded, version: config.schemaVersion },
+		});
+	}
+
+	let current = recorded;
+
+	for (const migration of pendingMigrations(config, recorded)) {
+		try {
+			await connection.transaction(async tx => {
+				throwIfFaulted('migration');
+				await migration.migrate(migrationContextFor(context, tx));
+				await writeSchemaVersion(tx, migration.version);
+				await recordAttempt(tx, {
+					version: migration.version,
+					attemptedAt: context.now(),
+					outcome: 'applied',
+				});
+			});
+			current = migration.version;
+		} catch (error) {
+			// Recorded outside the rolled-back transaction, or it would vanish
+			// with the migration it describes.
+			await recordAttempt(connection, {
+				version: migration.version,
+				attemptedAt: context.now(),
+				outcome: 'failed',
+				failureCode:
+					(error as { code?: string }).code ?? DiagnosticCodes.MIGRATION_FAILED,
+			});
+			await context.closeOnFailure();
+			raise(DiagnosticCodes.MIGRATION_FAILED, {
+				message: 'migration failed',
+				migration: {
+					// Unchanged: the next open retries from here rather than
+					// skipping the migration that failed.
+					recordedVersion: current,
+					failingVersion: migration.version,
+					outcome: 'failed',
+				},
+				cause: error,
+			});
+		}
+	}
+
+	return current;
+}

package/src/migration/ledger.ts

@@ -0,0 +1,97 @@
+/**
+ * The per-scope migration ledger.
+ *
+ * Per scope, not per database, and that is the whole reason FR-054 works: a
+ * scope created after a migration shipped starts at version 0 and is migrated
+ * on first open, rather than being assumed current because some other scope
+ * already ran the chain.
+ *
+ * The ledger records a **code**, never a message (FR-079). A migration that
+ * failed because a domain constraint was violated could otherwise write the
+ * offending value into a table that outlives the failure — a payload leak
+ * with a long half-life, sitting in a file the next crash report might carry.
+ */
+
+import type { MigrationLedgerEntry, MigrationOutcome } from '../contract/migration';
+import type { Executor } from '../sqlite/connection';
+import { maybeText, num, text } from '../sqlite/values';
+
+/** Physical layout version, independent of the app's schema version. */
+export const FORMAT_VERSION = 1;
+
+const CREATE_META = `CREATE TABLE IF NOT EXISTS _meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+)`;
+
+const CREATE_MIGRATIONS = `CREATE TABLE IF NOT EXISTS _migrations (
+  version      INTEGER PRIMARY KEY,
+  attempted_at INTEGER NOT NULL,
+  outcome      TEXT NOT NULL,
+  failure_code TEXT
+)`;
+
+export async function ensureLedger(executor: Executor): Promise<void> {
+	await executor.execute(CREATE_META);
+	await executor.execute(CREATE_MIGRATIONS);
+	await executor.execute(
+		'INSERT INTO _meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO NOTHING',
+		['format_version', String(FORMAT_VERSION)],
+	);
+	await executor.execute(
+		'INSERT INTO _meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO NOTHING',
+		['schema_version', '0'],
+	);
+}
+
+async function readMeta(executor: Executor, key: string): Promise<string | null> {
+	const result = await executor.execute('SELECT value FROM _meta WHERE key = ?', [key]);
+	const row = result.rows[0];
+	return row ? text(row.value) : null;
+}
+
+export async function readSchemaVersion(executor: Executor): Promise<number> {
+	const raw = await readMeta(executor, 'schema_version');
+	return raw === null ? 0 : Number(raw);
+}
+
+export async function readFormatVersion(executor: Executor): Promise<number> {
+	const raw = await readMeta(executor, 'format_version');
+	return raw === null ? FORMAT_VERSION : Number(raw);
+}
+
+export async function writeSchemaVersion(executor: Executor, version: number): Promise<void> {
+	await executor.execute(
+		'INSERT INTO _meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value',
+		['schema_version', String(version)],
+	);
+}
+
+export async function recordAttempt(
+	executor: Executor,
+	entry: { version: number; attemptedAt: number; outcome: MigrationOutcome; failureCode?: string },
+): Promise<void> {
+	await executor.execute(
+		`INSERT INTO _migrations (version, attempted_at, outcome, failure_code)
+		 VALUES (?, ?, ?, ?)
+		 ON CONFLICT(version) DO UPDATE SET
+		   attempted_at = excluded.attempted_at,
+		   outcome = excluded.outcome,
+		   failure_code = excluded.failure_code`,
+		[entry.version, entry.attemptedAt, entry.outcome, entry.failureCode ?? null],
+	);
+}
+
+export async function readLedger(executor: Executor): Promise<MigrationLedgerEntry[]> {
+	const result = await executor.execute(
+		'SELECT version, attempted_at, outcome, failure_code FROM _migrations ORDER BY version ASC',
+	);
+	return result.rows.map(row => ({
+		version: num(row.version),
+		attemptedAt: num(row.attempted_at),
+		outcome: text(row.outcome) as MigrationOutcome,
+		...(maybeText(row.failure_code) === null
+			? {}
+			: { failureCode: text(row.failure_code) }),
+	}));
+}

package/src/migration/validate-chain.ts

@@ -0,0 +1,65 @@
+/**
+ * Migration chain validation, run before any migration executes (FR-053).
+ *
+ * Validating first is what stops a half-run chain from being the thing that
+ * discovers the problem. A duplicate version, a gap, or a chain that does not
+ * reach the declared `schemaVersion` are all configuration errors the
+ * developer can fix; discovering them after migration 3 of 5 has already
+ * rewritten a user's data is not.
+ *
+ * A gap is refused rather than skipped over deliberately. A user upgrading
+ * from the version inside the gap has no path across it, and opening anyway
+ * would hand them a database the code believes is current and is not.
+ */
+
+import type { DatabaseConfig } from '../contract/config';
+import { DiagnosticCodes } from '../contract/errors';
+import type { Migration } from '../contract/migration';
+import { raise } from '../diagnostics/errors';
+
+function invalid(message: string, detail?: Record<string, unknown>): never {
+	raise(DiagnosticCodes.MIGRATION_CONFIG_INVALID, { message, detail });
+}
+
+export function validateMigrationChain(config: DatabaseConfig): void {
+	const migrations = config.migrations ?? [];
+
+	if (!Number.isInteger(config.schemaVersion) || config.schemaVersion < 1) {
+		invalid('schemaVersion must be a positive integer');
+	}
+
+	const versions = new Set<number>();
+	for (const migration of migrations) {
+		if (!Number.isInteger(migration.version) || migration.version < 1) {
+			invalid('migration version must be a positive integer');
+		}
+		if (versions.has(migration.version)) {
+			invalid('duplicate migration version', { version: migration.version });
+		}
+		versions.add(migration.version);
+		if (typeof migration.migrate !== 'function') {
+			invalid('migration has no migrate function', { version: migration.version });
+		}
+	}
+
+	for (let version = 1; version <= config.schemaVersion; version += 1) {
+		if (!versions.has(version)) {
+			invalid('migration chain has a gap', { version });
+		}
+	}
+
+	for (const version of versions) {
+		if (version > config.schemaVersion) {
+			invalid('migration version exceeds the declared schemaVersion', { version });
+		}
+	}
+}
+
+/** Ascending, because the order a consumer declared them in is not a contract. */
+export function orderedMigrations(config: DatabaseConfig): Migration[] {
+	return [...(config.migrations ?? [])].sort((a, b) => a.version - b.version);
+}
+
+export function pendingMigrations(config: DatabaseConfig, recordedVersion: number): Migration[] {
+	return orderedMigrations(config).filter(migration => migration.version > recordedVersion);
+}

package/src/platform/backup-android-verify.ts

@@ -0,0 +1,88 @@
+/**
+ * Android backup posture: verified and reported, never enforced.
+ *
+ * Android decides backup participation from `android:dataExtractionRules` in
+ * the app's manifest. That is build-time and app-owned, and this package
+ * authors no native code, so it cannot contribute an entry and cannot change
+ * the answer at runtime (research.md R5).
+ *
+ * What it can do is check the one thing that silently breaks the documented
+ * fix: the rule the README tells an app to ship addresses the `file` domain,
+ * which is the app's `files/` directory. If the managed root did not land
+ * under that directory, the app can ship the XML exactly as documented and
+ * still have an unprotected database. That mismatch is detectable here, and
+ * an app learning it from this report is the whole point of FR-111 — the
+ * alternative is learning it from an incident.
+ */
+
+import { Platform } from 'react-native';
+
+import type { EffectivePosture } from '../contract/backup';
+import { MANAGED_ROOT_NAME, normalizePath, type StorageLayout } from './location';
+
+export function isAndroid(): boolean {
+	return Platform.OS === 'android';
+}
+
+/** The `path` an app's exclusion rule must name for the root it actually got. */
+export function coveragePathFor(layout: StorageLayout): string | null {
+	const root = normalizePath(layout.root);
+	const marker = `/files/`;
+	const index = root.indexOf(marker);
+	if (index === -1) {
+		return null;
+	}
+	return root.slice(index + marker.length);
+}
+
+export function androidPosture(
+	layout: StorageLayout,
+	includeInPlatformBackup: boolean,
+): EffectivePosture {
+	const requested = includeInPlatformBackup ? 'included' : 'excluded';
+	const coverage = coveragePathFor(layout);
+
+	if (coverage === null) {
+		return {
+			requested,
+			// Not "excluded" and not "included": the package genuinely does not
+			// know, and saying either would be a claim it cannot support.
+			observed: 'unknown',
+			enforcedBy: 'app-manifest',
+			warning:
+				'The managed storage area is not under the Android file domain, so the ' +
+				'documented data_extraction_rules.xml entry will not cover it. Backup ' +
+				'posture cannot be honoured on this platform until the app supplies a ' +
+				'rule matching the actual storage location.',
+		};
+	}
+
+	return {
+		requested,
+		observed: 'unknown',
+		enforcedBy: 'app-manifest',
+		warning:
+			`Android backup participation is declared by the app, not this package. ` +
+			`Confirm android/app/src/main/res/xml/data_extraction_rules.xml contains an ` +
+			`entry for domain="file" path="${MANAGED_ROOT_NAME}/" and that ` +
+			`AndroidManifest.xml references it; the observed posture cannot be verified ` +
+			`from JavaScript.`,
+	};
+}
+
+/**
+ * The posture the handle reports (FR-111).
+ *
+ * Split by platform rather than smoothed over, because a consumer writing a
+ * privacy disclosure needs to know which of the two answers it is holding.
+ */
+export function effectivePostureFor(
+	layout: StorageLayout,
+	includeInPlatformBackup: boolean,
+	iosPostureFor: (include: boolean) => EffectivePosture,
+): EffectivePosture {
+	if (isAndroid()) {
+		return androidPosture(layout, includeInPlatformBackup);
+	}
+	return iosPostureFor(includeInPlatformBackup);
+}

package/src/platform/backup-ios.ts

@@ -0,0 +1,48 @@
+/**
+ * iOS backup exclusion.
+ *
+ * `NSURLIsExcludedFromBackupKey` is set on the managed root at creation, and
+ * the attribute is inherited by everything beneath it — so one call covers
+ * the catalog, every scope database, and every artifact, including ones
+ * created years later. Setting it per file would leave a window in which a
+ * freshly written artifact is backed up before the attribute lands.
+ *
+ * This is the half of FR-109 the package can actually enforce. Android is
+ * manifest-owned; see backup-android-verify.ts and research.md R5.
+ */
+
+import { Platform } from 'react-native';
+
+import type { EffectivePosture } from '../contract/backup';
+import { fileSystem } from './fs';
+import type { StorageLayout } from './location';
+
+export function isIos(): boolean {
+	return Platform.OS === 'ios';
+}
+
+/**
+ * Create the managed root with the exclusion attribute already on it.
+ *
+ * Idempotent: `mkdir` on an existing directory re-applies the attribute,
+ * which matters because an app that flips the posture between launches must
+ * get the new one without a reinstall.
+ */
+export async function ensureManagedRoot(
+	layout: StorageLayout,
+	includeInPlatformBackup: boolean,
+): Promise<void> {
+	await fileSystem().mkdir(layout.root, {
+		NSURLIsExcludedFromBackupKey: isIos() ? !includeInPlatformBackup : undefined,
+	});
+}
+
+/** What the package can state about iOS, where it enforces rather than reports. */
+export function iosPosture(includeInPlatformBackup: boolean): EffectivePosture {
+	const requested = includeInPlatformBackup ? 'included' : 'excluded';
+	return {
+		requested,
+		observed: requested,
+		enforcedBy: 'package',
+	};
+}

package/src/platform/fs.ts

@@ -0,0 +1,89 @@
+/**
+ * The filesystem peer, behind one lazy accessor.
+ *
+ * Required lazily for the same reason the engine is: a consuming app that
+ * only ever runs the in-memory adapter in tests must not have to install a
+ * native module to import this package. Confining the require to `platform/`
+ * also keeps the native surface four directories wide, which is the layering
+ * rule the ESLint config enforces.
+ */
+
+import { DiagnosticCodes } from '../contract/errors';
+import { raise } from '../diagnostics/errors';
+
+export type FileStat = {
+	path: string;
+	size: number;
+	mtime: number;
+	isFile(): boolean;
+	isDirectory(): boolean;
+};
+
+export type MkdirOptions = {
+	/** iOS only. Set at creation so nothing beneath it is ever backed up. */
+	NSURLIsExcludedFromBackupKey?: boolean;
+};
+
+/**
+ * Only what the package actually uses. The peer's upload and download
+ * helpers are deliberately absent from this type: the package must never
+ * make a network request (FR-084, SC-016), and a surface that cannot express
+ * one is a stronger guarantee than a rule that says not to.
+ */
+export type FileSystem = {
+	DocumentDirectoryPath: string;
+	mkdir(path: string, options?: MkdirOptions): Promise<void>;
+	writeFile(path: string, contents: string, encoding?: string): Promise<void>;
+	appendFile(path: string, contents: string, encoding?: string): Promise<void>;
+	readFile(path: string, encoding?: string): Promise<string>;
+	/** Chunked read at an offset — what FR-107a's flat memory bound rests on. */
+	read(path: string, length: number, position: number, encoding?: string): Promise<string>;
+	stat(path: string): Promise<FileStat>;
+	readdir(path: string): Promise<string[]>;
+	unlink(path: string): Promise<void>;
+	exists(path: string): Promise<boolean>;
+};
+
+let override: FileSystem | null = null;
+let cached: FileSystem | null = null;
+
+/** Swap the peer. Tests and the demo app's in-memory mode only. */
+export function setFileSystem(module: FileSystem | null): void {
+	override = module;
+	cached = null;
+}
+
+export function fileSystem(): FileSystem {
+	if (override) {
+		return override;
+	}
+	if (!cached) {
+		try {
+			cached = require('@dr.pogodin/react-native-fs') as FileSystem;
+		} catch (error) {
+			raise(DiagnosticCodes.STORAGE_ACCESS, {
+				message: 'filesystem peer is not installed',
+				cause: error,
+			});
+		}
+	}
+	return cached!;
+}
+
+export async function pathExists(path: string): Promise<boolean> {
+	try {
+		return await fileSystem().exists(path);
+	} catch {
+		return false;
+	}
+}
+
+/** Remove a path, treating "already gone" as success (FR-062). */
+export async function removeIfPresent(path: string): Promise<boolean> {
+	try {
+		await fileSystem().unlink(path);
+		return true;
+	} catch {
+		return false;
+	}
+}