@chipmobilesdk/rn-local-db 0.1.2 → 0.2.1

package/src/migration/validate-chain.ts

@@ -1,65 +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);
-}
+/**
+ * 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

@@ -1,88 +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);
-}
+/**
+ * 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

@@ -1,48 +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',
-	};
-}
+/**
+ * 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/bytes.ts

@@ -0,0 +1,144 @@
+/**
+ * Byte handling without Node's `Buffer`.
+ *
+ * Hermes has no global `Buffer`, and `react-native-quick-crypto` installs one
+ * only when the app calls its `install()` — which nothing in this package or its
+ * documentation asked for. Until 0.2.0 attachment writes and reads used the
+ * global anyway, so on a device every attachment operation threw. Everything
+ * here is plain `Uint8Array` and a self-contained base64 codec, identical on
+ * Hermes and in Node.
+ */
+
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+const LOOKUP = (() => {
+	const table = new Int16Array(128).fill(-1);
+	for (let index = 0; index < ALPHABET.length; index += 1) {
+		table[ALPHABET.charCodeAt(index)] = index;
+	}
+	// The URL-safe variants decode too, since some file APIs return them.
+	table['-'.charCodeAt(0)] = 62;
+	table['_'.charCodeAt(0)] = 63;
+	return table;
+})();
+
+/* eslint-disable no-bitwise -- base64 is bit packing; there is no clearer way to write it. */
+
+/** Characters per `String.fromCharCode` call; large spreads overflow the stack. */
+const CHUNK = 0x8000;
+
+export function base64ToBytes(base64: string): Uint8Array {
+	if (typeof globalThis.atob === 'function') {
+		let binary: string | undefined;
+		try {
+			binary = globalThis.atob(base64.replace(/-/g, '+').replace(/_/g, '/'));
+		} catch {
+			// atob is strict where Buffer was lenient; fall through to the
+			// tolerant decoder rather than turn stray characters into a crash.
+		}
+		if (binary !== undefined) {
+			const bytes = new Uint8Array(binary.length);
+			for (let index = 0; index < binary.length; index += 1) {
+				bytes[index] = binary.charCodeAt(index);
+			}
+			return bytes;
+		}
+	}
+	// Decode directly, skipping padding and anything outside the alphabet.
+	const bytes = new Uint8Array(Math.ceil((base64.length * 3) / 4));
+	let out = 0;
+	let buffer = 0;
+	let bits = 0;
+	for (let index = 0; index < base64.length; index += 1) {
+		const code = base64.charCodeAt(index);
+		const value = code < 128 ? LOOKUP[code]! : -1;
+		if (value < 0) continue;
+		buffer = (buffer << 6) | value;
+		bits += 6;
+		if (bits >= 8) {
+			bits -= 8;
+			bytes[out++] = (buffer >> bits) & 0xff;
+		}
+	}
+	return bytes.subarray(0, out);
+}
+
+export function bytesToBase64(bytes: Uint8Array): string {
+	if (typeof globalThis.btoa === 'function') {
+		const parts: string[] = [];
+		for (let index = 0; index < bytes.length; index += CHUNK) {
+			parts.push(String.fromCharCode(...bytes.subarray(index, index + CHUNK)));
+		}
+		return globalThis.btoa(parts.join(''));
+	}
+	const parts: string[] = [];
+	for (let start = 0; start < bytes.length; start += CHUNK * 3) {
+		let piece = '';
+		const end = Math.min(bytes.length, start + CHUNK * 3);
+		let index = start;
+		for (; index + 2 < end; index += 3) {
+			const triple = (bytes[index]! << 16) | (bytes[index + 1]! << 8) | bytes[index + 2]!;
+			piece +=
+				ALPHABET[triple >> 18]! +
+				ALPHABET[(triple >> 12) & 63]! +
+				ALPHABET[(triple >> 6) & 63]! +
+				ALPHABET[triple & 63]!;
+		}
+		const remaining = end - index;
+		if (remaining === 1) {
+			const value = bytes[index]!;
+			piece += `${ALPHABET[value >> 2]}${ALPHABET[(value & 3) << 4]}==`;
+		} else if (remaining === 2) {
+			const value = (bytes[index]! << 8) | bytes[index + 1]!;
+			piece += `${ALPHABET[value >> 10]}${ALPHABET[(value >> 4) & 63]}${ALPHABET[(value & 15) << 2]}=`;
+		}
+		parts.push(piece);
+	}
+	return parts.join('');
+}
+
+/** UTF-8 encoding. `TextEncoder` is in Hermes and Node; the loop is the fallback. */
+export function utf8Bytes(value: string): Uint8Array {
+	if (typeof TextEncoder !== 'undefined') {
+		return new TextEncoder().encode(value);
+	}
+	const encoded = unescape(encodeURIComponent(value));
+	const bytes = new Uint8Array(encoded.length);
+	for (let index = 0; index < encoded.length; index += 1) {
+		bytes[index] = encoded.charCodeAt(index);
+	}
+	return bytes;
+}
+
+/** UTF-8 decoding, the inverse of `utf8Bytes`. */
+export function utf8String(bytes: Uint8Array): string {
+	if (typeof TextDecoder !== 'undefined') {
+		return new TextDecoder().decode(bytes);
+	}
+	let binary = '';
+	for (const byte of bytes) {
+		binary += String.fromCharCode(byte);
+	}
+	return decodeURIComponent(escape(binary));
+}
+
+/* eslint-enable no-bitwise */
+
+export function concatBytes(parts: readonly Uint8Array[]): Uint8Array {
+	const total = parts.reduce((sum, part) => sum + part.length, 0);
+	const joined = new Uint8Array(total);
+	let offset = 0;
+	for (const part of parts) {
+		joined.set(part, offset);
+		offset += part.length;
+	}
+	return joined;
+}
+
+/** The ASCII text of `length` bytes from `start`, for magic numbers. */
+export function asciiAt(bytes: Uint8Array, start: number, length: number): string {
+	let text = '';
+	for (let index = start; index < start + length && index < bytes.length; index += 1) {
+		text += String.fromCharCode(bytes[index]!);
+	}
+	return text;
+}