@chipmobilesdk/rn-local-db 0.2.0 → 0.3.0

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,75 @@
-/**
- * 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 { lazyPeer } from '@chipmobilesdk/rn-core';
+
+import { DiagnosticCodes } from '../contract/errors';
+import { StorageError } 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 };
+	};
+};
+
+/** Loaded on first use (rn-core's lazy peer); optional, so absence is a normal answer. */
+const cipher = lazyPeer('react-native-quick-crypto', () => {
+	// Inside `try`, so Metro bundles an app that leaves this optional peer out.
+	try {
+		return require('react-native-quick-crypto') as CipherModule;
+	} catch (cause) {
+		throw cause;
+	}
+});
+
+/** Swap the module. Tests only; `null` goes back to the real one. */
+export function setCipherModule(module: CipherModule | null): void {
+	cipher.override(module ?? undefined);
+}
+
+export function isCipherAvailable(): boolean {
+	return cipher.isAvailable();
+}
+
+export function cipherModule(): CipherModule {
+	return cipher.require(
+		(_peer, cause) =>
+			new StorageError(DiagnosticCodes.ENCRYPTION_UNAVAILABLE, {
+				message: 'cipher peer is not installed',
+				cause,
+			}),
+	);
+}

package/src/diagnostics/dev-log.ts

@@ -1,108 +1,132 @@
-/**
- * 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.
+ */
+
+import { createDiagnosticChannel, hasSdkSinks } from '@chipmobilesdk/rn-core';
+
+export type DiagnosticEvent = {
+	operation: string;
+	durationMs?: number;
+	count?: number | undefined;
+	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.
+	if (typeof __DEV__ !== 'undefined') return __DEV__ === true;
+	const { process } = globalThis as { process?: { env?: Record<string, string | undefined> } };
+	return process?.env?.NODE_ENV !== 'production';
+}
+
+/**
+ * A failed operation also reaches the app's SDK sinks (`installSdkSink` from
+ * rn-core, CORE-08), in any build: its code, the operation and the collection,
+ * which are identifiers this package defines. Successes stay with the
+ * development logger.
+ */
+const channel = createDiagnosticChannel('rn-local-db');
+
+export function logDiagnostic(event: DiagnosticEvent): void {
+	if (event.outcome !== undefined) {
+		channel.emit(event.outcome, 'warn', {
+			operation: event.operation,
+			...(event.collection === undefined ? {} : { collection: event.collection }),
+			...(event.adapter === undefined ? {} : { adapter: event.adapter }),
+		});
+	}
+	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 {
+	// Unwrapped unless someone is listening: production pays nothing by default.
+	if (!isLogging() && !hasSdkSinks()) {
+		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;