@chipmobilesdk/rn-local-db 0.2.0 → 0.2.1

package/src/crypto/key-provider.ts

@@ -1,78 +1,78 @@
-/**
- * Key acquisition, scoped to one handle's lifetime.
- *
- * The package never generates, derives from its own material, persists,
- * caches beyond the handle, transmits, or returns a key (FR-098). What it
- * does is ask the app for one at open and hold it exactly as long as the
- * connection that needs it — which is also why no keychain library appears in
- * this package's dependencies (LIB-004).
- *
- * The provider receives the resolved scope, so an app can key per identity.
- * That is not a convenience: it is what makes destroying one identity's key a
- * meaningful answer to a deletion request, rather than a gesture that leaves
- * the data readable under a shared key (FR-104).
- */
-
-import type { EncryptionConfig } from '../contract/encryption';
-import { DiagnosticCodes } from '../contract/errors';
-import type { ResolvedScope } from '../contract/scope';
-import { raise } from '../diagnostics/errors';
-import { throwIfFaulted } from '../diagnostics/faults';
-
-/**
- * A key with an explicit end of life.
- *
- * Handing the string around directly would leave copies wherever it was
- * passed. A handle that can be released gives the connection one place to
- * drop it, and gives `key-hygiene.test.ts` something to assert against.
- */
-export type KeyHandle = {
-	value(): string;
-	release(): void;
-	readonly released: boolean;
-};
-
-export async function acquireKey(
-	encryption: EncryptionConfig,
-	scope: ResolvedScope,
-): Promise<KeyHandle> {
-	let key: string | null;
-
-	throwIfFaulted('keyProvider');
-
-	try {
-		key = await encryption.keyProvider.getKey(scope);
-	} catch (error) {
-		// A locked device is an expected condition, not a bug (FR-102), which
-		// is why this code is retryable and distinct from an invalid key.
-		raise(DiagnosticCodes.KEY_PROVIDER_FAILED, {
-			message: 'key provider failed',
-			cause: error,
-		});
-	}
-
-	if (typeof key !== 'string' || key.length === 0) {
-		raise(DiagnosticCodes.KEY_INVALID, {
-			message: 'key provider returned no usable key',
-		});
-	}
-
-	let released = false;
-	return {
-		value(): string {
-			if (released || key === null) {
-				raise(DiagnosticCodes.KEY_INVALID, {
-					message: 'key material has already been released',
-				});
-			}
-			return key;
-		},
-		release(): void {
-			released = true;
-			key = null;
-		},
-		get released(): boolean {
-			return released;
-		},
-	};
-}
+/**
+ * Key acquisition, scoped to one handle's lifetime.
+ *
+ * The package never generates, derives from its own material, persists,
+ * caches beyond the handle, transmits, or returns a key (FR-098). What it
+ * does is ask the app for one at open and hold it exactly as long as the
+ * connection that needs it — which is also why no keychain library appears in
+ * this package's dependencies (LIB-004).
+ *
+ * The provider receives the resolved scope, so an app can key per identity.
+ * That is not a convenience: it is what makes destroying one identity's key a
+ * meaningful answer to a deletion request, rather than a gesture that leaves
+ * the data readable under a shared key (FR-104).
+ */
+
+import type { EncryptionConfig } from '../contract/encryption';
+import { DiagnosticCodes } from '../contract/errors';
+import type { ResolvedScope } from '../contract/scope';
+import { raise } from '../diagnostics/errors';
+import { throwIfFaulted } from '../diagnostics/faults';
+
+/**
+ * A key with an explicit end of life.
+ *
+ * Handing the string around directly would leave copies wherever it was
+ * passed. A handle that can be released gives the connection one place to
+ * drop it, and gives `key-hygiene.test.ts` something to assert against.
+ */
+export type KeyHandle = {
+	value(): string;
+	release(): void;
+	readonly released: boolean;
+};
+
+export async function acquireKey(
+	encryption: EncryptionConfig,
+	scope: ResolvedScope,
+): Promise<KeyHandle> {
+	let key: string | null;
+
+	throwIfFaulted('keyProvider');
+
+	try {
+		key = await encryption.keyProvider.getKey(scope);
+	} catch (error) {
+		// A locked device is an expected condition, not a bug (FR-102), which
+		// is why this code is retryable and distinct from an invalid key.
+		raise(DiagnosticCodes.KEY_PROVIDER_FAILED, {
+			message: 'key provider failed',
+			cause: error,
+		});
+	}
+
+	if (typeof key !== 'string' || key.length === 0) {
+		raise(DiagnosticCodes.KEY_INVALID, {
+			message: 'key provider returned no usable key',
+		});
+	}
+
+	let released = false;
+	return {
+		value(): string {
+			if (released || key === null) {
+				raise(DiagnosticCodes.KEY_INVALID, {
+					message: 'key material has already been released',
+				});
+			}
+			return key;
+		},
+		release(): void {
+			released = true;
+			key = null;
+		},
+		get released(): boolean {
+			return released;
+		},
+	};
+}

package/src/crypto/provider.ts

@@ -1,81 +1,81 @@
-/**
- * The cipher peer, behind one lazy accessor.
- *
- * Marked optional in `peerDependenciesMeta`: an app that never enables
- * encryption should not have to install a native crypto module. That makes
- * "the peer is absent" a supported state rather than a broken install, so it
- * reports `ENCRYPTION_UNAVAILABLE` — the same code as a missing SQLCipher
- * build flag, because from the app's side it is the same problem: encryption
- * was asked for and cannot be delivered (research.md R1a).
- */
-
-import { DiagnosticCodes } from '../contract/errors';
-import { raise } from '../diagnostics/errors';
-
-export type CipherModule = {
-	createCipheriv(
-		algorithm: string,
-		key: Uint8Array,
-		iv: Uint8Array,
-	): {
-		update(data: Uint8Array): Uint8Array;
-		final(): Uint8Array;
-		getAuthTag(): Uint8Array;
-	};
-	createDecipheriv(
-		algorithm: string,
-		key: Uint8Array,
-		iv: Uint8Array,
-	): {
-		update(data: Uint8Array): Uint8Array;
-		final(): Uint8Array;
-		setAuthTag(tag: Uint8Array): void;
-	};
-	hkdfSync(
-		digest: string,
-		key: Uint8Array,
-		salt: Uint8Array,
-		info: Uint8Array,
-		length: number,
-	): ArrayBuffer;
-	createHash(algorithm: string): {
-		update(data: Uint8Array | string): { digest(encoding: string): string };
-	};
-};
-
-let override: CipherModule | null = null;
-let cached: CipherModule | null = null;
-
-export function setCipherModule(module: CipherModule | null): void {
-	override = module;
-	cached = null;
-}
-
-export function isCipherAvailable(): boolean {
-	if (override) {
-		return true;
-	}
-	try {
-		require('react-native-quick-crypto');
-		return true;
-	} catch {
-		return false;
-	}
-}
-
-export function cipherModule(): CipherModule {
-	if (override) {
-		return override;
-	}
-	if (!cached) {
-		try {
-			cached = require('react-native-quick-crypto') as CipherModule;
-		} catch (error) {
-			raise(DiagnosticCodes.ENCRYPTION_UNAVAILABLE, {
-				message: 'cipher peer is not installed',
-				cause: error,
-			});
-		}
-	}
-	return cached!;
-}
+/**
+ * The cipher peer, behind one lazy accessor.
+ *
+ * Marked optional in `peerDependenciesMeta`: an app that never enables
+ * encryption should not have to install a native crypto module. That makes
+ * "the peer is absent" a supported state rather than a broken install, so it
+ * reports `ENCRYPTION_UNAVAILABLE` — the same code as a missing SQLCipher
+ * build flag, because from the app's side it is the same problem: encryption
+ * was asked for and cannot be delivered (research.md R1a).
+ */
+
+import { DiagnosticCodes } from '../contract/errors';
+import { raise } from '../diagnostics/errors';
+
+export type CipherModule = {
+	createCipheriv(
+		algorithm: string,
+		key: Uint8Array,
+		iv: Uint8Array,
+	): {
+		update(data: Uint8Array): Uint8Array;
+		final(): Uint8Array;
+		getAuthTag(): Uint8Array;
+	};
+	createDecipheriv(
+		algorithm: string,
+		key: Uint8Array,
+		iv: Uint8Array,
+	): {
+		update(data: Uint8Array): Uint8Array;
+		final(): Uint8Array;
+		setAuthTag(tag: Uint8Array): void;
+	};
+	hkdfSync(
+		digest: string,
+		key: Uint8Array,
+		salt: Uint8Array,
+		info: Uint8Array,
+		length: number,
+	): ArrayBuffer;
+	createHash(algorithm: string): {
+		update(data: Uint8Array | string): { digest(encoding: string): string };
+	};
+};
+
+let override: CipherModule | null = null;
+let cached: CipherModule | null = null;
+
+export function setCipherModule(module: CipherModule | null): void {
+	override = module;
+	cached = null;
+}
+
+export function isCipherAvailable(): boolean {
+	if (override) {
+		return true;
+	}
+	try {
+		require('react-native-quick-crypto');
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export function cipherModule(): CipherModule {
+	if (override) {
+		return override;
+	}
+	if (!cached) {
+		try {
+			cached = require('react-native-quick-crypto') as CipherModule;
+		} catch (error) {
+			raise(DiagnosticCodes.ENCRYPTION_UNAVAILABLE, {
+				message: 'cipher peer is not installed',
+				cause: error,
+			});
+		}
+	}
+	return cached!;
+}

package/src/diagnostics/dev-log.ts

@@ -1,108 +1,112 @@
-/**
- * Development-only diagnostics.
- *
- * Operation names, durations, and counts are safe to report. Record payloads,
- * field values, and query parameters are not — in any build, including this
- * one (FR-080, FR-081). There is deliberately no path here that accepts a
- * payload, so a future caller cannot pass one by accident.
- */
-
-export type DiagnosticEvent = {
-	operation: string;
-	durationMs?: number;
-	count?: number;
-	collection?: string;
-	adapter?: 'sqlite' | 'memory';
-	/** A diagnostic code when the operation failed. Never a message. */
-	outcome?: string;
-};
-
-export type DiagnosticLogger = (event: DiagnosticEvent) => void;
-
-let logger: DiagnosticLogger | null = null;
-
-/** Passing null removes the logger. */
-export function setDiagnosticLogger(next: DiagnosticLogger | null): void {
-	logger = next;
-}
-
-function isDevelopmentBuild(): boolean {
-	// __DEV__ is a React Native global; the typeof guard keeps this usable
-	// under plain Node when the package is exercised from Jest.
-	return typeof __DEV__ !== 'undefined' ? __DEV__ === true : process.env.NODE_ENV !== 'production';
-}
-
-export function logDiagnostic(event: DiagnosticEvent): void {
-	if (!logger || !isDevelopmentBuild()) {
-		return;
-	}
-	logger(event);
-}
-
-export function isLogging(): boolean {
-	return logger !== null && isDevelopmentBuild();
-}
-
-/**
- * Wrap a collection so every operation reports its name, duration, and result
- * count — and nothing else.
- *
- * Wrapping once here rather than instrumenting each operation in the adapters
- * is what keeps the guarantee checkable: there is one place that decides what
- * a log line may contain, and it has no access to a payload to leak even if a
- * future change wanted one. The wrapper is applied only when a logger is
- * installed and the build is a development build, so a production bundle pays
- * nothing and emits nothing (FR-081).
- */
-export function instrument<T extends Record<string, (...args: never[]) => unknown>>(
-	collection: string,
-	adapter: 'sqlite' | 'memory',
-	operations: T,
-): T {
-	if (!isLogging()) {
-		return operations;
-	}
-
-	const wrapped: Record<string, unknown> = {};
-	for (const [name, operation] of Object.entries(operations)) {
-		wrapped[name] = async (...args: never[]): Promise<unknown> => {
-			const started = Date.now();
-			try {
-				const result = await (operation as (...inner: never[]) => Promise<unknown>)(...args);
-				logDiagnostic({
-					operation: `${collection}.${name}`,
-					durationMs: Date.now() - started,
-					collection,
-					adapter,
-					...(countOf(result) === undefined ? {} : { count: countOf(result) }),
-				});
-				return result;
-			} catch (error) {
-				// The code, never the message: a failure log is exactly where a
-				// payload-bearing native message would otherwise end up.
-				logDiagnostic({
-					operation: `${collection}.${name}`,
-					durationMs: Date.now() - started,
-					collection,
-					adapter,
-					outcome: (error as { code?: string }).code ?? 'failed',
-				});
-				throw error;
-			}
-		};
-	}
-	return wrapped as T;
-}
-
-/** How many records an operation produced, when that is a meaningful answer. */
-function countOf(result: unknown): number | undefined {
-	if (typeof result === 'number') {
-		return result;
-	}
-	if (result && typeof result === 'object' && Array.isArray((result as { records?: unknown }).records)) {
-		return (result as { records: unknown[] }).records.length;
-	}
-	return undefined;
-}
-
-declare const __DEV__: boolean | undefined;
+/**
+ * Development-only diagnostics.
+ *
+ * Operation names, durations, and counts are safe to report. Record payloads,
+ * field values, and query parameters are not — in any build, including this
+ * one (FR-080, FR-081). There is deliberately no path here that accepts a
+ * payload, so a future caller cannot pass one by accident.
+ */
+
+export type DiagnosticEvent = {
+	operation: string;
+	durationMs?: number;
+	count?: number;
+	collection?: string;
+	adapter?: 'sqlite' | 'memory';
+	/** A diagnostic code when the operation failed. Never a message. */
+	outcome?: string;
+};
+
+export type DiagnosticLogger = (event: DiagnosticEvent) => void;
+
+let logger: DiagnosticLogger | null = null;
+
+/** Passing null removes the logger. */
+export function setDiagnosticLogger(next: DiagnosticLogger | null): void {
+	logger = next;
+}
+
+function isDevelopmentBuild(): boolean {
+	// __DEV__ is a React Native global; the typeof guard keeps this usable
+	// under plain Node when the package is exercised from Jest.
+	return typeof __DEV__ !== 'undefined' ? __DEV__ === true : process.env.NODE_ENV !== 'production';
+}
+
+export function logDiagnostic(event: DiagnosticEvent): void {
+	if (!logger || !isDevelopmentBuild()) {
+		return;
+	}
+	logger(event);
+}
+
+export function isLogging(): boolean {
+	return logger !== null && isDevelopmentBuild();
+}
+
+/**
+ * Wrap a collection so every operation reports its name, duration, and result
+ * count — and nothing else.
+ *
+ * Wrapping once here rather than instrumenting each operation in the adapters
+ * is what keeps the guarantee checkable: there is one place that decides what
+ * a log line may contain, and it has no access to a payload to leak even if a
+ * future change wanted one. The wrapper is applied only when a logger is
+ * installed and the build is a development build, so a production bundle pays
+ * nothing and emits nothing (FR-081).
+ */
+export function instrument<T extends Record<string, (...args: never[]) => unknown>>(
+	collection: string,
+	adapter: 'sqlite' | 'memory',
+	operations: T,
+): T {
+	if (!isLogging()) {
+		return operations;
+	}
+
+	const wrapped: Record<string, unknown> = {};
+	for (const [name, operation] of Object.entries(operations)) {
+		wrapped[name] = async (...args: never[]): Promise<unknown> => {
+			const started = Date.now();
+			try {
+				const result = await (operation as (...inner: never[]) => Promise<unknown>)(...args);
+				logDiagnostic({
+					operation: `${collection}.${name}`,
+					durationMs: Date.now() - started,
+					collection,
+					adapter,
+					...(countOf(result) === undefined ? {} : { count: countOf(result) }),
+				});
+				return result;
+			} catch (error) {
+				// The code, never the message: a failure log is exactly where a
+				// payload-bearing native message would otherwise end up.
+				logDiagnostic({
+					operation: `${collection}.${name}`,
+					durationMs: Date.now() - started,
+					collection,
+					adapter,
+					outcome: (error as { code?: string }).code ?? 'failed',
+				});
+				throw error;
+			}
+		};
+	}
+	return wrapped as T;
+}
+
+/** How many records an operation produced, when that is a meaningful answer. */
+function countOf(result: unknown): number | undefined {
+	if (typeof result === 'number') {
+		return result;
+	}
+	if (
+		result &&
+		typeof result === 'object' &&
+		Array.isArray((result as { records?: unknown }).records)
+	) {
+		return (result as { records: unknown[] }).records.length;
+	}
+	return undefined;
+}
+
+declare const __DEV__: boolean | undefined;

package/src/diagnostics/errors.ts

@@ -1,66 +1,62 @@
-/**
- * The single error type the package raises.
- *
- * Everything is redacted on the way in (see redact.ts), so there is no path
- * by which a field value, query parameter, scope component, or key reaches an
- * error object at all.
- */
-
-import {
-	DiagnosticCodes,
-	RETRYABLE_CODES,
-	type DiagnosticCode,
-} from '../contract/errors';
-import type { MigrationFailureDetail } from '../contract/migration';
-import { redactCause, redactDetail, sanitizeAuthoredMessage } from './redact';
-
-export type StorageErrorInit = {
-	/**
-	 * A message this package authored. Never foreign text — a native or
-	 * consumer-thrown message goes in `cause`, which reduces it to an
-	 * identifier. `authored-messages.test.ts` checks every call site.
-	 */
-	message?: string;
-	detail?: Record<string, unknown>;
-	migration?: MigrationFailureDetail;
-	cause?: unknown;
-};
-
-export class StorageError extends Error {
-	readonly code: DiagnosticCode;
-	readonly retryable: boolean;
-	readonly detail?: Record<string, string | number | boolean>;
-	readonly migration?: MigrationFailureDetail;
-	readonly redactedCause?: string;
-
-	constructor(code: DiagnosticCode, init: StorageErrorInit = {}) {
-		super(init.message ? sanitizeAuthoredMessage(init.message) : code);
-		this.name = 'StorageError';
-		this.code = code;
-		this.retryable = RETRYABLE_CODES.has(code);
-		this.detail = redactDetail(init.detail);
-		// Version numbers and an outcome enum — no payload can hide in these.
-		this.migration = init.migration;
-		this.redactedCause = redactCause(init.cause);
-		// `cause` is deliberately NOT assigned: the native error it came from
-		// may quote the offending value, and assigning it would reintroduce
-		// exactly the leak redaction exists to prevent.
-		Object.setPrototypeOf(this, StorageError.prototype);
-	}
-}
-
-export function isStorageError(value: unknown): value is StorageError {
-	return value instanceof StorageError;
-}
-
-/** So no consumer ever has to parse a message string (FR-082). */
-export function isCode(value: unknown, code: DiagnosticCode): boolean {
-	return isStorageError(value) && value.code === code;
-}
-
-export function raise(code: DiagnosticCode, init?: StorageErrorInit): never {
-	throw new StorageError(code, init);
-}
-
-export { DiagnosticCodes };
-export type { DiagnosticCode };
+/**
+ * The single error type the package raises.
+ *
+ * Everything is redacted on the way in (see redact.ts), so there is no path
+ * by which a field value, query parameter, scope component, or key reaches an
+ * error object at all.
+ */
+
+import { DiagnosticCodes, RETRYABLE_CODES, type DiagnosticCode } from '../contract/errors';
+import type { MigrationFailureDetail } from '../contract/migration';
+import { redactCause, redactDetail, sanitizeAuthoredMessage } from './redact';
+
+export type StorageErrorInit = {
+	/**
+	 * A message this package authored. Never foreign text — a native or
+	 * consumer-thrown message goes in `cause`, which reduces it to an
+	 * identifier. `authored-messages.test.ts` checks every call site.
+	 */
+	message?: string;
+	detail?: Record<string, unknown>;
+	migration?: MigrationFailureDetail;
+	cause?: unknown;
+};
+
+export class StorageError extends Error {
+	readonly code: DiagnosticCode;
+	readonly retryable: boolean;
+	readonly detail?: Record<string, string | number | boolean>;
+	readonly migration?: MigrationFailureDetail;
+	readonly redactedCause?: string;
+
+	constructor(code: DiagnosticCode, init: StorageErrorInit = {}) {
+		super(init.message ? sanitizeAuthoredMessage(init.message) : code);
+		this.name = 'StorageError';
+		this.code = code;
+		this.retryable = RETRYABLE_CODES.has(code);
+		this.detail = redactDetail(init.detail);
+		// Version numbers and an outcome enum — no payload can hide in these.
+		this.migration = init.migration;
+		this.redactedCause = redactCause(init.cause);
+		// `cause` is deliberately NOT assigned: the native error it came from
+		// may quote the offending value, and assigning it would reintroduce
+		// exactly the leak redaction exists to prevent.
+		Object.setPrototypeOf(this, StorageError.prototype);
+	}
+}
+
+export function isStorageError(value: unknown): value is StorageError {
+	return value instanceof StorageError;
+}
+
+/** So no consumer ever has to parse a message string (FR-082). */
+export function isCode(value: unknown, code: DiagnosticCode): boolean {
+	return isStorageError(value) && value.code === code;
+}
+
+export function raise(code: DiagnosticCode, init?: StorageErrorInit): never {
+	throw new StorageError(code, init);
+}
+
+export { DiagnosticCodes };
+export type { DiagnosticCode };