@chipmobilesdk/rn-local-db 0.2.0 → 0.3.0

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,49 @@
-/**
- * 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,
+		isIos() ? { NSURLIsExcludedFromBackupKey: !includeInPlatformBackup } : {},
+	);
+}
+
+/** 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

@@ -1,144 +1,157 @@
-/**
- * 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;
-}
+/**
+ * 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;
+})();
+
+/**
+ * Codecs Hermes and Node provide but React Native's type declarations omit.
+ * Read through this view so the package type-checks without DOM or Node types.
+ */
+interface HostCodecs {
+	atob?: (data: string) => string;
+	btoa?: (data: string) => string;
+	TextEncoder?: new () => { encode(input: string): Uint8Array };
+	TextDecoder?: new () => { decode(input: Uint8Array): string };
+}
+
+export const host = globalThis as unknown as HostCodecs;
+
+/* 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 (host.atob) {
+		let binary: string | undefined;
+		try {
+			binary = host.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 (host.btoa) {
+		const parts: string[] = [];
+		for (let index = 0; index < bytes.length; index += CHUNK) {
+			parts.push(String.fromCharCode(...bytes.subarray(index, index + CHUNK)));
+		}
+		return host.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 (host.TextEncoder) {
+		return new host.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 (host.TextDecoder) {
+		return new host.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;
+}