@chipmobilesdk/rn-local-db 0.2.0 → 0.3.0

package/src/testing/conformance/encryption.ts

@@ -1,150 +1,151 @@
-import { DiagnosticCodes } from '../../contract/errors';
-import type { KeyProvider } from '../../contract/encryption';
-import { isCode } from '../../diagnostics/errors';
-import type { ConformanceContext } from './index';
-
-/** US10: opt-in encryption, and failures that stay apart from each other. */
-export function registerEncryptionConformance(context: ConformanceContext): void {
-	describe('conformance: encryption', () => {
-		beforeEach(() => context.reset());
-
-		const scope = { kind: 'identity', id: 'encrypted' } as const;
-		const keyProvider: KeyProvider = { getKey: async () => 'a-correct-key-32-bytes-long-value' };
-
-		const encrypted = { enabled: true as const, keyProvider };
-
-		it('reports its own posture', async () => {
-			const handle = await context.adapter.open(
-				context.configFor(scope, { encryption: encrypted }),
-			);
-			expect(handle.isEncrypted).toBe(true);
-			await handle.close();
-
-			const plain = await context.adapter.open(
-				context.configFor({ kind: 'identity', id: 'plain' }, { encryption: undefined }),
-			);
-			expect(plain.isEncrypted).toBe(false);
-			await plain.close();
-		});
-
-		it('stores and returns records unchanged under encryption', async () => {
-			const handle = await context.adapter.open(
-				context.configFor(scope, { encryption: encrypted }),
-			);
-			const data = { title: 'secret', score: 1, nested: { deep: [1, null, true] } };
-			await handle.collection('notes').insert({ id: 'a', data });
-			expect((await handle.collection('notes').get('a')).data).toEqual(data);
-			await handle.close();
-
-			const reopened = await context.adapter.open(
-				context.configFor(scope, { encryption: encrypted }),
-			);
-			expect((await reopened.collection('notes').get('a')).data).toEqual(data);
-			await reopened.close();
-		});
-
-		it('round-trips an artifact under encryption, including a byte range', async () => {
-			const handle = await context.adapter.open(
-				context.configFor(scope, { encryption: encrypted }),
-			);
-			const content = Buffer.from('hello encrypted attachment', 'utf8').toString('base64');
-			await handle.attachments().write({ id: 'a1', contentType: 'text/plain', content });
-
-			expect(await handle.attachments().read('a1')).toBe(content);
-			const slice = await handle.attachments().read('a1', { offset: 6, length: 9 });
-			expect(Buffer.from(slice, 'base64').toString('utf8')).toBe('encrypted');
-			expect((await handle.attachments().availability('a1')).state).toBe('available');
-			await handle.close();
-		});
-
-		it('reports a key-provider failure separately from an invalid key', async () => {
-			let thrown: unknown;
-			try {
-				await context.adapter.open(
-					context.configFor(scope, {
-						encryption: {
-							enabled: true,
-							keyProvider: {
-								getKey: async () => {
-									throw new Error('device is locked');
-								},
-							},
-						},
-					}),
-				);
-			} catch (error) {
-				thrown = error;
-			}
-			expect(isCode(thrown, DiagnosticCodes.KEY_PROVIDER_FAILED)).toBe(true);
-
-			let empty: unknown;
-			try {
-				await context.adapter.open(
-					context.configFor(scope, {
-						encryption: { enabled: true, keyProvider: { getKey: async () => '' } },
-					}),
-				);
-			} catch (error) {
-				empty = error;
-			}
-			expect(isCode(empty, DiagnosticCodes.KEY_INVALID)).toBe(true);
-		});
-
-		it('reports a posture mismatch rather than opening or converting', async () => {
-			const plain = await context.adapter.open(context.configFor(scope));
-			await plain.collection('notes').insert({ id: 'a', data: { title: 'plaintext' } });
-			await plain.close();
-
-			let thrown: unknown;
-			try {
-				await context.adapter.open(context.configFor(scope, { encryption: encrypted }));
-			} catch (error) {
-				thrown = error;
-			}
-			expect(isCode(thrown, DiagnosticCodes.ENCRYPTION_MISMATCH)).toBe(true);
-
-			// Nothing was converted, truncated, or discarded.
-			const reopened = await context.adapter.open(context.configFor(scope));
-			expect((await reopened.collection('notes').get('a')).data.title).toBe('plaintext');
-			await reopened.close();
-		});
-
-		it('gives the key provider the scope, so an app can key per identity', async () => {
-			const seen: string[] = [];
-			const recording: KeyProvider = {
-				getKey: async resolved => {
-					seen.push(resolved.key);
-					return `key-for-${resolved.key}`;
-				},
-			};
-
-			for (const id of ['alice', 'bob']) {
-				const handle = await context.adapter.open(
-					context.configFor(
-						{ kind: 'identity', id },
-						{ encryption: { enabled: true, keyProvider: recording } },
-					),
-				);
-				await handle.close();
-			}
-
-			expect(seen).toHaveLength(2);
-			expect(new Set(seen).size).toBe(2);
-			for (const key of seen) {
-				expect(key).toMatch(/^[0-9a-f]{64}$/);
-			}
-		});
-
-		it('keeps an encrypted scope isolated from an unencrypted sibling', async () => {
-			const secure = await context.adapter.open(
-				context.configFor({ kind: 'identity', id: 'secure' }, { encryption: encrypted }),
-			);
-			await secure.collection('notes').insert({ id: 'shared', data: { title: 'secure' } });
-			await secure.close();
-
-			const open = await context.adapter.open(context.configFor({ kind: 'identity', id: 'open' }));
-			expect(await open.collection('notes').find('shared')).toBeNull();
-			await open.close();
-		});
-	});
-}
+import { DiagnosticCodes } from '../../contract/errors';
+import type { KeyProvider } from '../../contract/encryption';
+import { isCode } from '../../diagnostics/errors';
+import { base64ToBytes, bytesToBase64, utf8Bytes, utf8String } from '../../platform/bytes';
+import type { ConformanceContext } from './index';
+
+/** US10: opt-in encryption, and failures that stay apart from each other. */
+export function registerEncryptionConformance(context: ConformanceContext): void {
+	describe('conformance: encryption', () => {
+		beforeEach(() => context.reset());
+
+		const scope = { kind: 'identity', id: 'encrypted' } as const;
+		const keyProvider: KeyProvider = { getKey: async () => 'a-correct-key-32-bytes-long-value' };
+
+		const encrypted = { enabled: true as const, keyProvider };
+
+		it('reports its own posture', async () => {
+			const handle = await context.adapter.open(
+				context.configFor(scope, { encryption: encrypted }),
+			);
+			expect(handle.isEncrypted).toBe(true);
+			await handle.close();
+
+			const plain = await context.adapter.open(
+				context.configFor({ kind: 'identity', id: 'plain' }, { encryption: undefined }),
+			);
+			expect(plain.isEncrypted).toBe(false);
+			await plain.close();
+		});
+
+		it('stores and returns records unchanged under encryption', async () => {
+			const handle = await context.adapter.open(
+				context.configFor(scope, { encryption: encrypted }),
+			);
+			const data = { title: 'secret', score: 1, nested: { deep: [1, null, true] } };
+			await handle.collection('notes').insert({ id: 'a', data });
+			expect((await handle.collection('notes').get('a')).data).toEqual(data);
+			await handle.close();
+
+			const reopened = await context.adapter.open(
+				context.configFor(scope, { encryption: encrypted }),
+			);
+			expect((await reopened.collection('notes').get('a')).data).toEqual(data);
+			await reopened.close();
+		});
+
+		it('round-trips an artifact under encryption, including a byte range', async () => {
+			const handle = await context.adapter.open(
+				context.configFor(scope, { encryption: encrypted }),
+			);
+			const content = bytesToBase64(utf8Bytes('hello encrypted attachment'));
+			await handle.attachments().write({ id: 'a1', contentType: 'text/plain', content });
+
+			expect(await handle.attachments().read('a1')).toBe(content);
+			const slice = await handle.attachments().read('a1', { offset: 6, length: 9 });
+			expect(utf8String(base64ToBytes(slice))).toBe('encrypted');
+			expect((await handle.attachments().availability('a1')).state).toBe('available');
+			await handle.close();
+		});
+
+		it('reports a key-provider failure separately from an invalid key', async () => {
+			let thrown: unknown;
+			try {
+				await context.adapter.open(
+					context.configFor(scope, {
+						encryption: {
+							enabled: true,
+							keyProvider: {
+								getKey: async () => {
+									throw new Error('device is locked');
+								},
+							},
+						},
+					}),
+				);
+			} catch (error) {
+				thrown = error;
+			}
+			expect(isCode(thrown, DiagnosticCodes.KEY_PROVIDER_FAILED)).toBe(true);
+
+			let empty: unknown;
+			try {
+				await context.adapter.open(
+					context.configFor(scope, {
+						encryption: { enabled: true, keyProvider: { getKey: async () => '' } },
+					}),
+				);
+			} catch (error) {
+				empty = error;
+			}
+			expect(isCode(empty, DiagnosticCodes.KEY_INVALID)).toBe(true);
+		});
+
+		it('reports a posture mismatch rather than opening or converting', async () => {
+			const plain = await context.adapter.open(context.configFor(scope));
+			await plain.collection('notes').insert({ id: 'a', data: { title: 'plaintext' } });
+			await plain.close();
+
+			let thrown: unknown;
+			try {
+				await context.adapter.open(context.configFor(scope, { encryption: encrypted }));
+			} catch (error) {
+				thrown = error;
+			}
+			expect(isCode(thrown, DiagnosticCodes.ENCRYPTION_MISMATCH)).toBe(true);
+
+			// Nothing was converted, truncated, or discarded.
+			const reopened = await context.adapter.open(context.configFor(scope));
+			expect((await reopened.collection('notes').get('a')).data.title).toBe('plaintext');
+			await reopened.close();
+		});
+
+		it('gives the key provider the scope, so an app can key per identity', async () => {
+			const seen: string[] = [];
+			const recording: KeyProvider = {
+				getKey: async resolved => {
+					seen.push(resolved.key);
+					return `key-for-${resolved.key}`;
+				},
+			};
+
+			for (const id of ['alice', 'bob']) {
+				const handle = await context.adapter.open(
+					context.configFor(
+						{ kind: 'identity', id },
+						{ encryption: { enabled: true, keyProvider: recording } },
+					),
+				);
+				await handle.close();
+			}
+
+			expect(seen).toHaveLength(2);
+			expect(new Set(seen).size).toBe(2);
+			for (const key of seen) {
+				expect(key).toMatch(/^[0-9a-f]{64}$/);
+			}
+		});
+
+		it('keeps an encrypted scope isolated from an unencrypted sibling', async () => {
+			const secure = await context.adapter.open(
+				context.configFor({ kind: 'identity', id: 'secure' }, { encryption: encrypted }),
+			);
+			await secure.collection('notes').insert({ id: 'shared', data: { title: 'secure' } });
+			await secure.close();
+
+			const open = await context.adapter.open(context.configFor({ kind: 'identity', id: 'open' }));
+			expect(await open.collection('notes').find('shared')).toBeNull();
+			await open.close();
+		});
+	});
+}

package/src/testing/conformance/index.ts

@@ -1,161 +1,161 @@
-/**
- * The conformance suite: the executable definition of what the package
- * guarantees (FR-092).
- *
- * Exported rather than kept internal so a consuming team can run it against
- * their own adapter if one ever exists, and so both of ours are held to
- * exactly the same standard rather than to two similar-looking test files.
- */
-
-import type { StorageAdapter } from '../../contract/adapter';
-import type { DatabaseConfig, ScopeTargetConfig } from '../../contract/config';
-import type { EncryptionConfig } from '../../contract/encryption';
-import type { ScopeDescriptor } from '../../contract/scope';
-import { registerRecordConformance } from './records';
-import { registerScopeConformance } from './scopes';
-import { registerQueryConformance } from './queries';
-import { registerTransactionConformance } from './transactions';
-import { registerMigrationConformance } from './migrations';
-import { registerLifecycleConformance } from './lifecycle';
-import { registerAttachmentConformance } from './attachments';
-import { registerEncryptionConformance } from './encryption';
-
-export type ConformanceContext = {
-	adapter: StorageAdapter;
-	/** A fresh config for the given scope, using the standard test schema. */
-	configFor(scope: ScopeDescriptor, overrides?: Partial<DatabaseConfig>): DatabaseConfig;
-	/**
-	 * How an app names a scope for deletion.
-	 *
-	 * Carries the encryption config when the run is encrypted, because that is
-	 * how a real consumer calls it: `ScopeTargetConfig.encryption` exists so
-	 * deletion can report what it removed rather than guessing at it.
-	 */
-	scopeTargetFor(scope: ScopeDescriptor): ScopeTargetConfig;
-	reset(): Promise<void>;
-	/**
-	 * Reach past the package and delete an artifact the way the operating
-	 * system does when it reclaims storage. Each adapter supplies its own,
-	 * because the suite cannot simulate this through the public API without
-	 * asking the package to break its own guarantee.
-	 */
-	removeArtifactBehindTheScenes(scopeKey: string, attachmentId: string): Promise<void>;
-	/** The other direction: a reference whose artifact survives. */
-	removeReferenceBehindTheScenes(scopeKey: string, attachmentId: string): Promise<void>;
-};
-
-export type ConformanceHooks = Pick<
-	ConformanceContext,
-	'removeArtifactBehindTheScenes' | 'removeReferenceBehindTheScenes'
->;
-
-export type ConformanceOptions = {
-	/** Sections the adapter knowingly cannot satisfy, with a documented reason. */
-	skip?: ConformanceSection[];
-	/**
-	 * Run every section against an encrypted database (FR-105).
-	 *
-	 * The suite is the contract, so the contract has to hold in both postures
-	 * — an encrypted database that quietly behaved differently would be a
-	 * second implementation nobody tested.
-	 */
-	encryption?: EncryptionConfig;
-};
-
-export type ConformanceSection =
-	| 'records'
-	| 'scopes'
-	| 'queries'
-	| 'transactions'
-	| 'migrations'
-	| 'lifecycle'
-	| 'attachments'
-	| 'encryption';
-
-export const TEST_COLLECTIONS: DatabaseConfig['collections'] = [
-	{
-		name: 'notes',
-		fields: [
-			{ name: 'title', type: 'string' },
-			{ name: 'score', type: 'number' },
-			{ name: 'done', type: 'boolean' },
-			{ name: 'updated', type: 'timestamp' },
-		],
-		indexes: [{ name: 'notes_by_score', fields: ['score'] }],
-		softDelete: true,
-		timestamps: true,
-	},
-	{
-		name: 'plain',
-		fields: [{ name: 'label', type: 'string' }],
-	},
-];
-
-export function makeConformanceContext(
-	adapter: StorageAdapter,
-	reset: () => Promise<void>,
-	hooks: ConformanceHooks,
-	defaults: Partial<DatabaseConfig> = {},
-): ConformanceContext {
-	return {
-		adapter,
-		reset,
-		...hooks,
-		configFor(scope, overrides = {}) {
-			return {
-				name: 'conformance',
-				scope,
-				schemaVersion: 1,
-				collections: TEST_COLLECTIONS,
-				migrations: [{ version: 1, migrate: async () => {} }],
-				...defaults,
-				...overrides,
-			};
-		},
-		scopeTargetFor(scope) {
-			return {
-				name: 'conformance',
-				scope,
-				...(defaults.encryption ? { encryption: defaults.encryption } : {}),
-			};
-		},
-	};
-}
-
-/**
- * Registers the whole suite against one adapter. Both adapters call this with
- * the same arguments; any difference in outcome is a divergence that must be
- * documented under FR-096 or fixed.
- */
-export function runConformanceSuite(
-	factory: () => StorageAdapter,
-	reset: () => Promise<void>,
-	hooks: ConformanceHooks,
-	options: ConformanceOptions = {},
-): void {
-	const skip = new Set(options.skip ?? []);
-	const context = makeConformanceContext(
-		factory(),
-		reset,
-		hooks,
-		options.encryption ? { encryption: options.encryption } : {},
-	);
-
-	const sections: [ConformanceSection, (c: ConformanceContext) => void][] = [
-		['records', registerRecordConformance],
-		['scopes', registerScopeConformance],
-		['queries', registerQueryConformance],
-		['transactions', registerTransactionConformance],
-		['migrations', registerMigrationConformance],
-		['lifecycle', registerLifecycleConformance],
-		['attachments', registerAttachmentConformance],
-		['encryption', registerEncryptionConformance],
-	];
-
-	for (const [name, register] of sections) {
-		if (skip.has(name)) {
-			continue;
-		}
-		register(context);
-	}
-}
+/**
+ * The conformance suite: the executable definition of what the package
+ * guarantees (FR-092).
+ *
+ * Exported rather than kept internal so a consuming team can run it against
+ * their own adapter if one ever exists, and so both of ours are held to
+ * exactly the same standard rather than to two similar-looking test files.
+ */
+
+import type { StorageAdapter } from '../../contract/adapter';
+import type { DatabaseConfig, ScopeTargetConfig } from '../../contract/config';
+import type { EncryptionConfig } from '../../contract/encryption';
+import type { ScopeDescriptor } from '../../contract/scope';
+import { registerRecordConformance } from './records';
+import { registerScopeConformance } from './scopes';
+import { registerQueryConformance } from './queries';
+import { registerTransactionConformance } from './transactions';
+import { registerMigrationConformance } from './migrations';
+import { registerLifecycleConformance } from './lifecycle';
+import { registerAttachmentConformance } from './attachments';
+import { registerEncryptionConformance } from './encryption';
+
+export type ConformanceContext = {
+	adapter: StorageAdapter;
+	/** A fresh config for the given scope, using the standard test schema. */
+	configFor(scope: ScopeDescriptor, overrides?: Partial<DatabaseConfig>): DatabaseConfig;
+	/**
+	 * How an app names a scope for deletion.
+	 *
+	 * Carries the encryption config when the run is encrypted, because that is
+	 * how a real consumer calls it: `ScopeTargetConfig.encryption` exists so
+	 * deletion can report what it removed rather than guessing at it.
+	 */
+	scopeTargetFor(scope: ScopeDescriptor): ScopeTargetConfig;
+	reset(): Promise<void>;
+	/**
+	 * Reach past the package and delete an artifact the way the operating
+	 * system does when it reclaims storage. Each adapter supplies its own,
+	 * because the suite cannot simulate this through the public API without
+	 * asking the package to break its own guarantee.
+	 */
+	removeArtifactBehindTheScenes(scopeKey: string, attachmentId: string): Promise<void>;
+	/** The other direction: a reference whose artifact survives. */
+	removeReferenceBehindTheScenes(scopeKey: string, attachmentId: string): Promise<void>;
+};
+
+export type ConformanceHooks = Pick<
+	ConformanceContext,
+	'removeArtifactBehindTheScenes' | 'removeReferenceBehindTheScenes'
+>;
+
+export type ConformanceOptions = {
+	/** Sections the adapter knowingly cannot satisfy, with a documented reason. */
+	skip?: ConformanceSection[];
+	/**
+	 * Run every section against an encrypted database (FR-105).
+	 *
+	 * The suite is the contract, so the contract has to hold in both postures
+	 * — an encrypted database that quietly behaved differently would be a
+	 * second implementation nobody tested.
+	 */
+	encryption?: EncryptionConfig | undefined;
+};
+
+export type ConformanceSection =
+	| 'records'
+	| 'scopes'
+	| 'queries'
+	| 'transactions'
+	| 'migrations'
+	| 'lifecycle'
+	| 'attachments'
+	| 'encryption';
+
+export const TEST_COLLECTIONS: DatabaseConfig['collections'] = [
+	{
+		name: 'notes',
+		fields: [
+			{ name: 'title', type: 'string' },
+			{ name: 'score', type: 'number' },
+			{ name: 'done', type: 'boolean' },
+			{ name: 'updated', type: 'timestamp' },
+		],
+		indexes: [{ name: 'notes_by_score', fields: ['score'] }],
+		softDelete: true,
+		timestamps: true,
+	},
+	{
+		name: 'plain',
+		fields: [{ name: 'label', type: 'string' }],
+	},
+];
+
+export function makeConformanceContext(
+	adapter: StorageAdapter,
+	reset: () => Promise<void>,
+	hooks: ConformanceHooks,
+	defaults: Partial<DatabaseConfig> = {},
+): ConformanceContext {
+	return {
+		adapter,
+		reset,
+		...hooks,
+		configFor(scope, overrides = {}) {
+			return {
+				name: 'conformance',
+				scope,
+				schemaVersion: 1,
+				collections: TEST_COLLECTIONS,
+				migrations: [{ version: 1, migrate: async () => {} }],
+				...defaults,
+				...overrides,
+			};
+		},
+		scopeTargetFor(scope) {
+			return {
+				name: 'conformance',
+				scope,
+				...(defaults.encryption ? { encryption: defaults.encryption } : {}),
+			};
+		},
+	};
+}
+
+/**
+ * Registers the whole suite against one adapter. Both adapters call this with
+ * the same arguments; any difference in outcome is a divergence that must be
+ * documented under FR-096 or fixed.
+ */
+export function runConformanceSuite(
+	factory: () => StorageAdapter,
+	reset: () => Promise<void>,
+	hooks: ConformanceHooks,
+	options: ConformanceOptions = {},
+): void {
+	const skip = new Set(options.skip ?? []);
+	const context = makeConformanceContext(
+		factory(),
+		reset,
+		hooks,
+		options.encryption ? { encryption: options.encryption } : {},
+	);
+
+	const sections: [ConformanceSection, (c: ConformanceContext) => void][] = [
+		['records', registerRecordConformance],
+		['scopes', registerScopeConformance],
+		['queries', registerQueryConformance],
+		['transactions', registerTransactionConformance],
+		['migrations', registerMigrationConformance],
+		['lifecycle', registerLifecycleConformance],
+		['attachments', registerAttachmentConformance],
+		['encryption', registerEncryptionConformance],
+	];
+
+	for (const [name, register] of sections) {
+		if (skip.has(name)) {
+			continue;
+		}
+		register(context);
+	}
+}