@chipmobilesdk/rn-local-db 0.2.0 → 0.2.1

package/src/schema/validate-config.ts

@@ -1,158 +1,158 @@
-/**
- * Configuration validation.
- *
- * Runs to completion before any write and before any migration executes
- * (FR-006, FR-053). Order matters: scope first, then collections, then the
- * migration chain — so a consumer fixes the outermost problem first rather
- * than chasing a downstream symptom.
- */
-
-import { Budgets, type DatabaseConfig } from '../contract/config';
-import { DiagnosticCodes } from '../contract/errors';
-import type { CollectionSchema } from '../contract/schema';
-import { raise } from '../diagnostics/errors';
-import { validateDescriptor } from '../scope/validate';
-
-const IDENTIFIER = /^[A-Za-z][A-Za-z0-9_]{0,62}$/;
-
-function configInvalid(message: string, detail?: Record<string, unknown>): never {
-	raise(DiagnosticCodes.CONFIG_INVALID, { message, detail });
-}
-
-function validateCollection(collection: CollectionSchema, seen: Set<string>): void {
-	if (!IDENTIFIER.test(collection.name)) {
-		configInvalid('collection name is not a valid identifier', {
-			collection: collection.name,
-		});
-	}
-	if (seen.has(collection.name)) {
-		configInvalid('duplicate collection name', { collection: collection.name });
-	}
-	seen.add(collection.name);
-
-	const fieldNames = new Set<string>();
-	for (const field of collection.fields ?? []) {
-		if (!IDENTIFIER.test(field.name)) {
-			configInvalid('field name is not a valid identifier', {
-				collection: collection.name,
-			});
-		}
-		if (fieldNames.has(field.name)) {
-			configInvalid('duplicate field name', { collection: collection.name });
-		}
-		fieldNames.add(field.name);
-	}
-
-	const indexNames = new Set<string>();
-	for (const index of collection.indexes ?? []) {
-		if (!IDENTIFIER.test(index.name)) {
-			configInvalid('index name is not a valid identifier', {
-				collection: collection.name,
-			});
-		}
-		if (indexNames.has(index.name)) {
-			configInvalid('duplicate index name', { collection: collection.name });
-		}
-		indexNames.add(index.name);
-		if (!Array.isArray(index.fields) || index.fields.length === 0) {
-			configInvalid('index declares no fields', { collection: collection.name });
-		}
-		for (const field of index.fields) {
-			if (!fieldNames.has(field)) {
-				// The whole point of declaring fields is that the package can
-				// tell a typo from a deliberate choice. Silently creating an
-				// index over a column that will never exist would turn a config
-				// bug into a mysterious full scan at runtime.
-				configInvalid('index references an undeclared field', {
-					collection: collection.name,
-				});
-			}
-		}
-	}
-}
-
-function validateMigrations(config: DatabaseConfig): void {
-	const migrations = config.migrations ?? [];
-	if (!Number.isInteger(config.schemaVersion) || config.schemaVersion < 1) {
-		raise(DiagnosticCodes.MIGRATION_CONFIG_INVALID, {
-			message: 'schemaVersion must be a positive integer',
-		});
-	}
-
-	const versions = new Set<number>();
-	for (const migration of migrations) {
-		if (!Number.isInteger(migration.version) || migration.version < 1) {
-			raise(DiagnosticCodes.MIGRATION_CONFIG_INVALID, {
-				message: 'migration version must be a positive integer',
-			});
-		}
-		if (versions.has(migration.version)) {
-			raise(DiagnosticCodes.MIGRATION_CONFIG_INVALID, {
-				message: 'duplicate migration version',
-				detail: { version: migration.version },
-			});
-		}
-		versions.add(migration.version);
-		if (typeof migration.migrate !== 'function') {
-			raise(DiagnosticCodes.MIGRATION_CONFIG_INVALID, {
-				message: 'migration has no migrate function',
-				detail: { version: migration.version },
-			});
-		}
-	}
-
-	// A chain must be able to carry a database from 1 to schemaVersion. A gap
-	// means some upgrading user has no path across it, which is worse than
-	// refusing to open.
-	for (let version = 1; version <= config.schemaVersion; version += 1) {
-		if (!versions.has(version)) {
-			raise(DiagnosticCodes.MIGRATION_CONFIG_INVALID, {
-				message: 'migration chain has a gap',
-				detail: { version },
-			});
-		}
-	}
-
-	for (const version of versions) {
-		if (version > config.schemaVersion) {
-			raise(DiagnosticCodes.MIGRATION_CONFIG_INVALID, {
-				message: 'migration version exceeds the declared schemaVersion',
-				detail: { version },
-			});
-		}
-	}
-}
-
-export function validateConfig(config: DatabaseConfig): void {
-	if (!config || typeof config !== 'object') {
-		configInvalid('database config is required');
-	}
-	if (typeof config.name !== 'string' || !IDENTIFIER.test(config.name)) {
-		configInvalid('database name is not a valid identifier');
-	}
-
-	validateDescriptor(config.scope);
-
-	if (!Array.isArray(config.collections) || config.collections.length === 0) {
-		configInvalid('at least one collection must be declared');
-	}
-	if (config.collections.length > Budgets.MAX_COLLECTIONS_PER_DATABASE) {
-		configInvalid('collection count exceeds the budget', {
-			count: config.collections.length,
-			limit: Budgets.MAX_COLLECTIONS_PER_DATABASE,
-		});
-	}
-
-	const seen = new Set<string>();
-	for (const collection of config.collections) {
-		validateCollection(collection, seen);
-	}
-
-	validateMigrations(config);
-
-	if (config.encryption && config.encryption.enabled) {
-		if (typeof config.encryption.keyProvider?.getKey !== 'function') {
-			configInvalid('encryption is enabled but no key provider was supplied');
-		}
-	}
-}
+/**
+ * Configuration validation.
+ *
+ * Runs to completion before any write and before any migration executes
+ * (FR-006, FR-053). Order matters: scope first, then collections, then the
+ * migration chain — so a consumer fixes the outermost problem first rather
+ * than chasing a downstream symptom.
+ */
+
+import { Budgets, type DatabaseConfig } from '../contract/config';
+import { DiagnosticCodes } from '../contract/errors';
+import type { CollectionSchema } from '../contract/schema';
+import { raise } from '../diagnostics/errors';
+import { validateDescriptor } from '../scope/validate';
+
+const IDENTIFIER = /^[A-Za-z][A-Za-z0-9_]{0,62}$/;
+
+function configInvalid(message: string, detail?: Record<string, unknown>): never {
+	raise(DiagnosticCodes.CONFIG_INVALID, { message, detail });
+}
+
+function validateCollection(collection: CollectionSchema, seen: Set<string>): void {
+	if (!IDENTIFIER.test(collection.name)) {
+		configInvalid('collection name is not a valid identifier', {
+			collection: collection.name,
+		});
+	}
+	if (seen.has(collection.name)) {
+		configInvalid('duplicate collection name', { collection: collection.name });
+	}
+	seen.add(collection.name);
+
+	const fieldNames = new Set<string>();
+	for (const field of collection.fields ?? []) {
+		if (!IDENTIFIER.test(field.name)) {
+			configInvalid('field name is not a valid identifier', {
+				collection: collection.name,
+			});
+		}
+		if (fieldNames.has(field.name)) {
+			configInvalid('duplicate field name', { collection: collection.name });
+		}
+		fieldNames.add(field.name);
+	}
+
+	const indexNames = new Set<string>();
+	for (const index of collection.indexes ?? []) {
+		if (!IDENTIFIER.test(index.name)) {
+			configInvalid('index name is not a valid identifier', {
+				collection: collection.name,
+			});
+		}
+		if (indexNames.has(index.name)) {
+			configInvalid('duplicate index name', { collection: collection.name });
+		}
+		indexNames.add(index.name);
+		if (!Array.isArray(index.fields) || index.fields.length === 0) {
+			configInvalid('index declares no fields', { collection: collection.name });
+		}
+		for (const field of index.fields) {
+			if (!fieldNames.has(field)) {
+				// The whole point of declaring fields is that the package can
+				// tell a typo from a deliberate choice. Silently creating an
+				// index over a column that will never exist would turn a config
+				// bug into a mysterious full scan at runtime.
+				configInvalid('index references an undeclared field', {
+					collection: collection.name,
+				});
+			}
+		}
+	}
+}
+
+function validateMigrations(config: DatabaseConfig): void {
+	const migrations = config.migrations ?? [];
+	if (!Number.isInteger(config.schemaVersion) || config.schemaVersion < 1) {
+		raise(DiagnosticCodes.MIGRATION_CONFIG_INVALID, {
+			message: 'schemaVersion must be a positive integer',
+		});
+	}
+
+	const versions = new Set<number>();
+	for (const migration of migrations) {
+		if (!Number.isInteger(migration.version) || migration.version < 1) {
+			raise(DiagnosticCodes.MIGRATION_CONFIG_INVALID, {
+				message: 'migration version must be a positive integer',
+			});
+		}
+		if (versions.has(migration.version)) {
+			raise(DiagnosticCodes.MIGRATION_CONFIG_INVALID, {
+				message: 'duplicate migration version',
+				detail: { version: migration.version },
+			});
+		}
+		versions.add(migration.version);
+		if (typeof migration.migrate !== 'function') {
+			raise(DiagnosticCodes.MIGRATION_CONFIG_INVALID, {
+				message: 'migration has no migrate function',
+				detail: { version: migration.version },
+			});
+		}
+	}
+
+	// A chain must be able to carry a database from 1 to schemaVersion. A gap
+	// means some upgrading user has no path across it, which is worse than
+	// refusing to open.
+	for (let version = 1; version <= config.schemaVersion; version += 1) {
+		if (!versions.has(version)) {
+			raise(DiagnosticCodes.MIGRATION_CONFIG_INVALID, {
+				message: 'migration chain has a gap',
+				detail: { version },
+			});
+		}
+	}
+
+	for (const version of versions) {
+		if (version > config.schemaVersion) {
+			raise(DiagnosticCodes.MIGRATION_CONFIG_INVALID, {
+				message: 'migration version exceeds the declared schemaVersion',
+				detail: { version },
+			});
+		}
+	}
+}
+
+export function validateConfig(config: DatabaseConfig): void {
+	if (!config || typeof config !== 'object') {
+		configInvalid('database config is required');
+	}
+	if (typeof config.name !== 'string' || !IDENTIFIER.test(config.name)) {
+		configInvalid('database name is not a valid identifier');
+	}
+
+	validateDescriptor(config.scope);
+
+	if (!Array.isArray(config.collections) || config.collections.length === 0) {
+		configInvalid('at least one collection must be declared');
+	}
+	if (config.collections.length > Budgets.MAX_COLLECTIONS_PER_DATABASE) {
+		configInvalid('collection count exceeds the budget', {
+			count: config.collections.length,
+			limit: Budgets.MAX_COLLECTIONS_PER_DATABASE,
+		});
+	}
+
+	const seen = new Set<string>();
+	for (const collection of config.collections) {
+		validateCollection(collection, seen);
+	}
+
+	validateMigrations(config);
+
+	if (config.encryption && config.encryption.enabled) {
+		if (typeof config.encryption.keyProvider?.getKey !== 'function') {
+			configInvalid('encryption is enabled but no key provider was supplied');
+		}
+	}
+}

package/src/scope/hash.ts

@@ -1,134 +1,131 @@
-/**
- * Scope key derivation.
- *
- * The directory a scope lives in is named by the SHA-256 digest of its
- * canonical descriptor, never by the components themselves. FR-014 requires
- * scope components be treated as sensitive, and a directory named after an
- * email address puts that address in plaintext on disk — visible even when
- * the database itself is encrypted, and carried into any crash report that
- * includes a file path.
- *
- * Hashing also removes filesystem charset and length limits from the problem,
- * which is what lets validation reject rather than sanitize (research.md R2).
- *
- * Implemented in pure TypeScript rather than over a native crypto peer so the
- * scope layer stays importable from anywhere in the package, including the
- * in-memory adapter running under Jest.
- *
- * Verified against Node's own SHA-256 in scope-resolution.test.ts — a wrong
- * digest would silently merge or split scopes, so it is checked against a
- * reference implementation rather than against a snapshot of this one.
- */
-
-/* eslint-disable no-bitwise -- SHA-256 is defined in terms of bitwise operations. */
-
-const K = new Uint32Array([
-	0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4,
-	0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe,
-	0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f,
-	0x4a7484aa, 0x5cb0a9dc, 0x76f988da, 0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7,
-	0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc,
-	0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b,
-	0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070, 0x19a4c116,
-	0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
-	0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7,
-	0xc67178f2,
-]);
-
-function rotr(value: number, bits: number): number {
-	return (value >>> bits) | (value << (32 - bits));
-}
-
-function utf8Bytes(input: string): Uint8Array {
-	const out: number[] = [];
-	for (let i = 0; i < input.length; i += 1) {
-		let codePoint = input.codePointAt(i)!;
-		if (codePoint > 0xffff) {
-			i += 1;
-		}
-		if (codePoint < 0x80) {
-			out.push(codePoint);
-		} else if (codePoint < 0x800) {
-			out.push(0xc0 | (codePoint >> 6), 0x80 | (codePoint & 0x3f));
-		} else if (codePoint < 0x10000) {
-			out.push(
-				0xe0 | (codePoint >> 12),
-				0x80 | ((codePoint >> 6) & 0x3f),
-				0x80 | (codePoint & 0x3f),
-			);
-		} else {
-			out.push(
-				0xf0 | (codePoint >> 18),
-				0x80 | ((codePoint >> 12) & 0x3f),
-				0x80 | ((codePoint >> 6) & 0x3f),
-				0x80 | (codePoint & 0x3f),
-			);
-		}
-	}
-	return Uint8Array.from(out);
-}
-
-export function utf8ByteLength(input: string): number {
-	return utf8Bytes(input).length;
-}
-
-export function sha256Hex(input: string): string {
-	const bytes = utf8Bytes(input);
-	const bitLength = bytes.length * 8;
-	const paddedLength = (((bytes.length + 9) >> 6) + 1) << 6;
-	const padded = new Uint8Array(paddedLength);
-	padded.set(bytes);
-	padded[bytes.length] = 0x80;
-
-	const view = new DataView(padded.buffer);
-	view.setUint32(paddedLength - 8, Math.floor(bitLength / 0x100000000), false);
-	view.setUint32(paddedLength - 4, bitLength >>> 0, false);
-
-	const h = new Uint32Array([
-		0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab,
-		0x5be0cd19,
-	]);
-	const w = new Uint32Array(64);
-
-	for (let offset = 0; offset < paddedLength; offset += 64) {
-		for (let i = 0; i < 16; i += 1) {
-			w[i] = view.getUint32(offset + i * 4, false);
-		}
-		for (let i = 16; i < 64; i += 1) {
-			const s0 = rotr(w[i - 15]!, 7) ^ rotr(w[i - 15]!, 18) ^ (w[i - 15]! >>> 3);
-			const s1 = rotr(w[i - 2]!, 17) ^ rotr(w[i - 2]!, 19) ^ (w[i - 2]! >>> 10);
-			w[i] = (w[i - 16]! + s0 + w[i - 7]! + s1) >>> 0;
-		}
-
-		let [a, b, c, d, e, f, g, hh] = [h[0]!, h[1]!, h[2]!, h[3]!, h[4]!, h[5]!, h[6]!, h[7]!];
-
-		for (let i = 0; i < 64; i += 1) {
-			const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
-			const ch = (e & f) ^ (~e & g);
-			const temp1 = (hh + S1 + ch + K[i]! + w[i]!) >>> 0;
-			const S0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
-			const maj = (a & b) ^ (a & c) ^ (b & c);
-			const temp2 = (S0 + maj) >>> 0;
-
-			hh = g;
-			g = f;
-			f = e;
-			e = (d + temp1) >>> 0;
-			d = c;
-			c = b;
-			b = a;
-			a = (temp1 + temp2) >>> 0;
-		}
-
-		h[0] = (h[0]! + a) >>> 0;
-		h[1] = (h[1]! + b) >>> 0;
-		h[2] = (h[2]! + c) >>> 0;
-		h[3] = (h[3]! + d) >>> 0;
-		h[4] = (h[4]! + e) >>> 0;
-		h[5] = (h[5]! + f) >>> 0;
-		h[6] = (h[6]! + g) >>> 0;
-		h[7] = (h[7]! + hh) >>> 0;
-	}
-
-	return Array.from(h, value => value.toString(16).padStart(8, '0')).join('');
-}
+/**
+ * Scope key derivation.
+ *
+ * The directory a scope lives in is named by the SHA-256 digest of its
+ * canonical descriptor, never by the components themselves. FR-014 requires
+ * scope components be treated as sensitive, and a directory named after an
+ * email address puts that address in plaintext on disk — visible even when
+ * the database itself is encrypted, and carried into any crash report that
+ * includes a file path.
+ *
+ * Hashing also removes filesystem charset and length limits from the problem,
+ * which is what lets validation reject rather than sanitize (research.md R2).
+ *
+ * Implemented in pure TypeScript rather than over a native crypto peer so the
+ * scope layer stays importable from anywhere in the package, including the
+ * in-memory adapter running under Jest.
+ *
+ * Verified against Node's own SHA-256 in scope-resolution.test.ts — a wrong
+ * digest would silently merge or split scopes, so it is checked against a
+ * reference implementation rather than against a snapshot of this one.
+ */
+
+/* eslint-disable no-bitwise -- SHA-256 is defined in terms of bitwise operations. */
+
+const K = new Uint32Array([
+	0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+	0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+	0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+	0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+	0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+	0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+	0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+	0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+
+function rotr(value: number, bits: number): number {
+	return (value >>> bits) | (value << (32 - bits));
+}
+
+function utf8Bytes(input: string): Uint8Array {
+	const out: number[] = [];
+	for (let i = 0; i < input.length; i += 1) {
+		let codePoint = input.codePointAt(i)!;
+		if (codePoint > 0xffff) {
+			i += 1;
+		}
+		if (codePoint < 0x80) {
+			out.push(codePoint);
+		} else if (codePoint < 0x800) {
+			out.push(0xc0 | (codePoint >> 6), 0x80 | (codePoint & 0x3f));
+		} else if (codePoint < 0x10000) {
+			out.push(
+				0xe0 | (codePoint >> 12),
+				0x80 | ((codePoint >> 6) & 0x3f),
+				0x80 | (codePoint & 0x3f),
+			);
+		} else {
+			out.push(
+				0xf0 | (codePoint >> 18),
+				0x80 | ((codePoint >> 12) & 0x3f),
+				0x80 | ((codePoint >> 6) & 0x3f),
+				0x80 | (codePoint & 0x3f),
+			);
+		}
+	}
+	return Uint8Array.from(out);
+}
+
+export function utf8ByteLength(input: string): number {
+	return utf8Bytes(input).length;
+}
+
+export function sha256Hex(input: string): string {
+	const bytes = utf8Bytes(input);
+	const bitLength = bytes.length * 8;
+	const paddedLength = (((bytes.length + 9) >> 6) + 1) << 6;
+	const padded = new Uint8Array(paddedLength);
+	padded.set(bytes);
+	padded[bytes.length] = 0x80;
+
+	const view = new DataView(padded.buffer);
+	view.setUint32(paddedLength - 8, Math.floor(bitLength / 0x100000000), false);
+	view.setUint32(paddedLength - 4, bitLength >>> 0, false);
+
+	const h = new Uint32Array([
+		0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+	]);
+	const w = new Uint32Array(64);
+
+	for (let offset = 0; offset < paddedLength; offset += 64) {
+		for (let i = 0; i < 16; i += 1) {
+			w[i] = view.getUint32(offset + i * 4, false);
+		}
+		for (let i = 16; i < 64; i += 1) {
+			const s0 = rotr(w[i - 15]!, 7) ^ rotr(w[i - 15]!, 18) ^ (w[i - 15]! >>> 3);
+			const s1 = rotr(w[i - 2]!, 17) ^ rotr(w[i - 2]!, 19) ^ (w[i - 2]! >>> 10);
+			w[i] = (w[i - 16]! + s0 + w[i - 7]! + s1) >>> 0;
+		}
+
+		let [a, b, c, d, e, f, g, hh] = [h[0]!, h[1]!, h[2]!, h[3]!, h[4]!, h[5]!, h[6]!, h[7]!];
+
+		for (let i = 0; i < 64; i += 1) {
+			const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+			const ch = (e & f) ^ (~e & g);
+			const temp1 = (hh + S1 + ch + K[i]! + w[i]!) >>> 0;
+			const S0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+			const maj = (a & b) ^ (a & c) ^ (b & c);
+			const temp2 = (S0 + maj) >>> 0;
+
+			hh = g;
+			g = f;
+			f = e;
+			e = (d + temp1) >>> 0;
+			d = c;
+			c = b;
+			b = a;
+			a = (temp1 + temp2) >>> 0;
+		}
+
+		h[0] = (h[0]! + a) >>> 0;
+		h[1] = (h[1]! + b) >>> 0;
+		h[2] = (h[2]! + c) >>> 0;
+		h[3] = (h[3]! + d) >>> 0;
+		h[4] = (h[4]! + e) >>> 0;
+		h[5] = (h[5]! + f) >>> 0;
+		h[6] = (h[6]! + g) >>> 0;
+		h[7] = (h[7]! + hh) >>> 0;
+	}
+
+	return Array.from(h, value => value.toString(16).padStart(8, '0')).join('');
+}