@chipmobilesdk/rn-local-db 0.1.2 → 0.2.1

package/src/contract/transaction.ts

@@ -1,46 +1,52 @@
-/**
- * Transactions and batches.
- *
- * A transaction never spans two scopes (FR-038): with one database file per
- * scope, a cross-scope transaction is not expressible rather than merely
- * discouraged.
- */
-
-import type { FilterNode, Query, ResultPage } from './query';
-import type { RecordInput, StorableRecordData, StoredRecord, WriteOutcome } from './record';
-
-/** Collection operations, available on a handle and inside a transaction. */
-export type CollectionOps<T extends StorableRecordData = StorableRecordData> = {
-	insert(record: RecordInput<T>): Promise<WriteOutcome>;
-	update(id: string, record: Partial<RecordInput<T>> & { data: T }): Promise<WriteOutcome>;
-	upsert(record: RecordInput<T>): Promise<WriteOutcome>;
-	/** Rejects with RECORD_NOT_FOUND when absent (FR-027). */
-	get(id: string): Promise<StoredRecord<T>>;
-	/** Null-returning variant, so absence stays distinguishable at the call site. */
-	find(id: string): Promise<StoredRecord<T> | null>;
-	delete(id: string): Promise<WriteOutcome>;
-	softDelete(id: string): Promise<WriteOutcome>;
-	restore(id: string): Promise<WriteOutcome>;
-	list(query?: Query): Promise<ResultPage<T>>;
-	count(filter?: FilterNode): Promise<number>;
-};
-
-export type Transaction = {
-	collection<T extends StorableRecordData = StorableRecordData>(
-		name: string,
-	): CollectionOps<T>;
-	/** Discards every write in this transaction (FR-041). */
-	abort(): Promise<void>;
-};
-
-export type BatchOperation =
-	| { type: 'insert'; collection: string; record: RecordInput }
-	| { type: 'update'; collection: string; id: string; data: StorableRecordData }
-	| { type: 'upsert'; collection: string; record: RecordInput }
-	| { type: 'delete'; collection: string; id: string }
-	| { type: 'softDelete'; collection: string; id: string };
-
-export type BatchOutcome = {
-	applied: number;
-	outcomes: WriteOutcome[];
-};
+/**
+ * Transactions and batches.
+ *
+ * A transaction never spans two scopes (FR-038): with one database file per
+ * scope, a cross-scope transaction is not expressible rather than merely
+ * discouraged.
+ */
+
+import type { FilterNode, Query, ResultPage } from './query';
+import type { RecordInput, StorableRecordData, StoredRecord, WriteOutcome } from './record';
+import type { Attachments } from './adapter';
+
+/** Collection operations, available on a handle and inside a transaction. */
+export type CollectionOps<T extends StorableRecordData = StorableRecordData> = {
+	insert(record: RecordInput<T>): Promise<WriteOutcome>;
+	update(id: string, record: Partial<RecordInput<T>> & { data: T }): Promise<WriteOutcome>;
+	upsert(record: RecordInput<T>): Promise<WriteOutcome>;
+	/** Rejects with RECORD_NOT_FOUND when absent (FR-027). */
+	get(id: string): Promise<StoredRecord<T>>;
+	/** Null-returning variant, so absence stays distinguishable at the call site. */
+	find(id: string): Promise<StoredRecord<T> | null>;
+	delete(id: string): Promise<WriteOutcome>;
+	softDelete(id: string): Promise<WriteOutcome>;
+	restore(id: string): Promise<WriteOutcome>;
+	list(query?: Query): Promise<ResultPage<T>>;
+	count(filter?: FilterNode): Promise<number>;
+};
+
+export type Transaction = {
+	collection<T extends StorableRecordData = StorableRecordData>(name: string): CollectionOps<T>;
+	/**
+	 * Attachments whose references join this transaction (FR-072): they roll
+	 * back with it, and cascaded files are removed only once it commits. Added
+	 * in 0.2.0 — the handle's own `attachments()` no longer reaches into an
+	 * in-flight transaction.
+	 */
+	attachments(): Attachments;
+	/** Discards every write in this transaction (FR-041). */
+	abort(): Promise<void>;
+};
+
+export type BatchOperation =
+	| { type: 'insert'; collection: string; record: RecordInput }
+	| { type: 'update'; collection: string; id: string; data: StorableRecordData }
+	| { type: 'upsert'; collection: string; record: RecordInput }
+	| { type: 'delete'; collection: string; id: string }
+	| { type: 'softDelete'; collection: string; id: string };
+
+export type BatchOutcome = {
+	applied: number;
+	outcomes: WriteOutcome[];
+};

package/src/crypto/chunked-cipher.ts

@@ -1,144 +1,153 @@
-/**
- * The chunked AES-256-GCM artifact format.
- *
- * Whole-file encryption was rejected because a 100 MB artifact would have to
- * be held in memory twice — plaintext and ciphertext — which breaks FR-107a's
- * flat memory bound and every PERF-001 budget along with it (research.md R4).
- * Chunking keeps exactly one 256 KB chunk in flight regardless of artifact
- * size.
- *
- * ```text
- * [ header 22 bytes ] magic | format version | chunk size | chunk count | plaintext size
- * [ chunk 0 ] ciphertext(≤ chunkSize) | auth tag (16)
- * [ chunk 1 ] …
- * ```
- *
- * The auth tag follows each chunk rather than sitting in the header, which is
- * a deliberate departure from the sketch in storage-layout.md. A tag is only
- * known after its chunk has been encrypted, and the filesystem peer appends —
- * it cannot seek back to patch a header. Collecting every tag before writing
- * anything would mean buffering the whole ciphertext, which is the thing this
- * format exists to avoid. Inline tags keep the write append-only and leave
- * every chunk at a computable offset.
- *
- * A failing tag on read is `ATTACHMENT_UNDECRYPTABLE`, deliberately distinct
- * from `ATTACHMENT_MISSING` (FR-107c): one is a wrong key or a tampered file
- * and may be recoverable, the other is data that is simply gone.
- */
-
-import { Budgets } from '../contract/config';
-import { DiagnosticCodes } from '../contract/errors';
-import { raise } from '../diagnostics/errors';
-import { nonceForChunk } from './derive';
-import { cipherModule } from './provider';
-
-export const MAGIC = 'LDB1';
-export const FORMAT_VERSION = 1;
-export const HEADER_BYTES = 22;
-export const TAG_BYTES = 16;
-export const ALGORITHM = 'aes-256-gcm';
-
-export type ArtifactHeader = {
-	formatVersion: number;
-	chunkSize: number;
-	chunkCount: number;
-	plaintextSize: number;
-};
-
-export function chunkCountFor(plaintextSize: number, chunkSize: number): number {
-	return plaintextSize === 0 ? 0 : Math.ceil(plaintextSize / chunkSize);
-}
-
-export function encodeHeader(header: ArtifactHeader): Buffer {
-	const buffer = Buffer.alloc(HEADER_BYTES);
-	buffer.write(MAGIC, 0, 4, 'ascii');
-	buffer.writeUInt16BE(header.formatVersion, 4);
-	buffer.writeUInt32BE(header.chunkSize, 6);
-	buffer.writeUInt32BE(header.chunkCount, 10);
-	// Split across two 32-bit writes: artifact sizes stay well inside the safe
-	// integer range, and this avoids depending on BigInt in Hermes.
-	buffer.writeUInt32BE(Math.floor(header.plaintextSize / 0x100000000), 14);
-	buffer.writeUInt32BE(header.plaintextSize % 0x100000000, 18);
-	return buffer;
-}
-
-export function decodeHeader(buffer: Buffer): ArtifactHeader {
-	if (buffer.length < HEADER_BYTES || buffer.toString('ascii', 0, 4) !== MAGIC) {
-		raise(DiagnosticCodes.ATTACHMENT_UNDECRYPTABLE, {
-			message: 'artifact header is not a recognised encrypted artifact',
-		});
-	}
-	return {
-		formatVersion: buffer.readUInt16BE(4),
-		chunkSize: buffer.readUInt32BE(6),
-		chunkCount: buffer.readUInt32BE(10),
-		plaintextSize: buffer.readUInt32BE(14) * 0x100000000 + buffer.readUInt32BE(18),
-	};
-}
-
-/** Plaintext length of chunk `index`; the last one is usually short. */
-export function chunkPlaintextLength(header: ArtifactHeader, index: number): number {
-	const start = index * header.chunkSize;
-	return Math.max(0, Math.min(header.chunkSize, header.plaintextSize - start));
-}
-
-/**
- * Byte offset of chunk `index` in the file.
- *
- * Every chunk but the last is full, so the offset is arithmetic rather than a
- * table lookup — which is what lets a range read seek straight to the chunk
- * it needs instead of walking the file.
- */
-export function chunkOffset(header: ArtifactHeader, index: number): number {
-	return HEADER_BYTES + index * (header.chunkSize + TAG_BYTES);
-}
-
-export function encryptedLength(header: ArtifactHeader): number {
-	if (header.chunkCount === 0) {
-		return HEADER_BYTES;
-	}
-	const lastIndex = header.chunkCount - 1;
-	return chunkOffset(header, lastIndex) + chunkPlaintextLength(header, lastIndex) + TAG_BYTES;
-}
-
-/** One chunk in, ciphertext with its tag appended out. */
-export function encryptChunk(key: Uint8Array, index: number, plaintext: Buffer): Buffer {
-	const cipher = cipherModule().createCipheriv(ALGORITHM, key, nonceForChunk(index));
-	const body = Buffer.concat([
-		Buffer.from(cipher.update(plaintext)),
-		Buffer.from(cipher.final()),
-	]);
-	return Buffer.concat([body, Buffer.from(cipher.getAuthTag())]);
-}
-
-export function decryptChunk(key: Uint8Array, index: number, stored: Buffer): Buffer {
-	if (stored.length < TAG_BYTES) {
-		raise(DiagnosticCodes.ATTACHMENT_UNDECRYPTABLE, {
-			message: 'artifact chunk is truncated',
-		});
-	}
-	const body = stored.subarray(0, stored.length - TAG_BYTES);
-	const tag = stored.subarray(stored.length - TAG_BYTES);
-
-	const decipher = cipherModule().createDecipheriv(ALGORITHM, key, nonceForChunk(index));
-	decipher.setAuthTag(tag);
-	try {
-		return Buffer.concat([Buffer.from(decipher.update(body)), Buffer.from(decipher.final())]);
-	} catch (error) {
-		// A failing tag is the only signal that separates "exists but will not
-		// decrypt" from "missing", and an app responds to them differently.
-		raise(DiagnosticCodes.ATTACHMENT_UNDECRYPTABLE, {
-			message: 'artifact chunk failed authentication',
-			cause: error,
-		});
-	}
-}
-
-export function headerFor(plaintextSize: number, chunkSize = Budgets.ARTIFACT_CHUNK_BYTES): ArtifactHeader {
-	return {
-		formatVersion: FORMAT_VERSION,
-		chunkSize,
-		chunkCount: chunkCountFor(plaintextSize, chunkSize),
-		plaintextSize,
-	};
-}
+/**
+ * The chunked AES-256-GCM artifact format.
+ *
+ * Whole-file encryption was rejected because a 100 MB artifact would have to
+ * be held in memory twice — plaintext and ciphertext — which breaks FR-107a's
+ * flat memory bound and every PERF-001 budget along with it (research.md R4).
+ * Chunking keeps exactly one 256 KB chunk in flight regardless of artifact
+ * size.
+ *
+ * ```text
+ * [ header 22 bytes ] magic | format version | chunk size | chunk count | plaintext size
+ * [ chunk 0 ] ciphertext(≤ chunkSize) | auth tag (16)
+ * [ chunk 1 ] …
+ * ```
+ *
+ * The auth tag follows each chunk rather than sitting in the header, which is
+ * a deliberate departure from the sketch in storage-layout.md. A tag is only
+ * known after its chunk has been encrypted, and the filesystem peer appends —
+ * it cannot seek back to patch a header. Collecting every tag before writing
+ * anything would mean buffering the whole ciphertext, which is the thing this
+ * format exists to avoid. Inline tags keep the write append-only and leave
+ * every chunk at a computable offset.
+ *
+ * A failing tag on read is `ATTACHMENT_UNDECRYPTABLE`, deliberately distinct
+ * from `ATTACHMENT_MISSING` (FR-107c): one is a wrong key or a tampered file
+ * and may be recoverable, the other is data that is simply gone.
+ */
+
+import { Budgets } from '../contract/config';
+import { DiagnosticCodes } from '../contract/errors';
+import { raise } from '../diagnostics/errors';
+import { nonceForChunk } from './derive';
+import { cipherModule } from './provider';
+import { asciiAt, concatBytes } from '../platform/bytes';
+
+export const MAGIC = 'LDB1';
+export const FORMAT_VERSION = 1;
+export const HEADER_BYTES = 22;
+export const TAG_BYTES = 16;
+export const ALGORITHM = 'aes-256-gcm';
+
+export type ArtifactHeader = {
+	formatVersion: number;
+	chunkSize: number;
+	chunkCount: number;
+	plaintextSize: number;
+};
+
+export function chunkCountFor(plaintextSize: number, chunkSize: number): number {
+	return plaintextSize === 0 ? 0 : Math.ceil(plaintextSize / chunkSize);
+}
+
+export function encodeHeader(header: ArtifactHeader): Uint8Array {
+	const bytes = new Uint8Array(HEADER_BYTES);
+	for (let index = 0; index < 4; index += 1) {
+		bytes[index] = MAGIC.charCodeAt(index);
+	}
+	// Big-endian, as DataView writes by default; the on-disk format is unchanged.
+	const view = new DataView(bytes.buffer);
+	view.setUint16(4, header.formatVersion);
+	view.setUint32(6, header.chunkSize);
+	view.setUint32(10, header.chunkCount);
+	// Split across two 32-bit writes: artifact sizes stay well inside the safe
+	// integer range, and this avoids depending on BigInt in Hermes.
+	view.setUint32(14, Math.floor(header.plaintextSize / 0x100000000));
+	view.setUint32(18, header.plaintextSize % 0x100000000);
+	return bytes;
+}
+
+export function decodeHeader(bytes: Uint8Array): ArtifactHeader {
+	if (bytes.length < HEADER_BYTES || asciiAt(bytes, 0, 4) !== MAGIC) {
+		raise(DiagnosticCodes.ATTACHMENT_UNDECRYPTABLE, {
+			message: 'artifact header is not a recognised encrypted artifact',
+		});
+	}
+	const view = new DataView(bytes.buffer, bytes.byteOffset, HEADER_BYTES);
+	return {
+		formatVersion: view.getUint16(4),
+		chunkSize: view.getUint32(6),
+		chunkCount: view.getUint32(10),
+		plaintextSize: view.getUint32(14) * 0x100000000 + view.getUint32(18),
+	};
+}
+
+/** Plaintext length of chunk `index`; the last one is usually short. */
+export function chunkPlaintextLength(header: ArtifactHeader, index: number): number {
+	const start = index * header.chunkSize;
+	return Math.max(0, Math.min(header.chunkSize, header.plaintextSize - start));
+}
+
+/**
+ * Byte offset of chunk `index` in the file.
+ *
+ * Every chunk but the last is full, so the offset is arithmetic rather than a
+ * table lookup — which is what lets a range read seek straight to the chunk
+ * it needs instead of walking the file.
+ */
+export function chunkOffset(header: ArtifactHeader, index: number): number {
+	return HEADER_BYTES + index * (header.chunkSize + TAG_BYTES);
+}
+
+export function encryptedLength(header: ArtifactHeader): number {
+	if (header.chunkCount === 0) {
+		return HEADER_BYTES;
+	}
+	const lastIndex = header.chunkCount - 1;
+	return chunkOffset(header, lastIndex) + chunkPlaintextLength(header, lastIndex) + TAG_BYTES;
+}
+
+/** One chunk in, ciphertext with its tag appended out. */
+export function encryptChunk(key: Uint8Array, index: number, plaintext: Uint8Array): Uint8Array {
+	const cipher = cipherModule().createCipheriv(ALGORITHM, key, nonceForChunk(index));
+	return concatBytes([
+		new Uint8Array(cipher.update(plaintext)),
+		new Uint8Array(cipher.final()),
+		new Uint8Array(cipher.getAuthTag()),
+	]);
+}
+
+export function decryptChunk(key: Uint8Array, index: number, stored: Uint8Array): Uint8Array {
+	if (stored.length < TAG_BYTES) {
+		raise(DiagnosticCodes.ATTACHMENT_UNDECRYPTABLE, {
+			message: 'artifact chunk is truncated',
+		});
+	}
+	const body = stored.subarray(0, stored.length - TAG_BYTES);
+	const tag = stored.subarray(stored.length - TAG_BYTES);
+
+	const decipher = cipherModule().createDecipheriv(ALGORITHM, key, nonceForChunk(index));
+	decipher.setAuthTag(tag);
+	try {
+		return concatBytes([new Uint8Array(decipher.update(body)), new Uint8Array(decipher.final())]);
+	} catch (error) {
+		// A failing tag is the only signal that separates "exists but will not
+		// decrypt" from "missing", and an app responds to them differently.
+		raise(DiagnosticCodes.ATTACHMENT_UNDECRYPTABLE, {
+			message: 'artifact chunk failed authentication',
+			cause: error,
+		});
+	}
+}
+
+export function headerFor(
+	plaintextSize: number,
+	chunkSize = Budgets.ARTIFACT_CHUNK_BYTES,
+): ArtifactHeader {
+	return {
+		formatVersion: FORMAT_VERSION,
+		chunkSize,
+		chunkCount: chunkCountFor(plaintextSize, chunkSize),
+		plaintextSize,
+	};
+}

package/src/crypto/derive.ts

@@ -1,63 +1,64 @@
-/**
- * Per-artifact key derivation.
- *
- * The database key is handed straight to SQLCipher. Using that same material
- * as the AES-GCM key for artifacts would mean the two keystreams share a
- * secret, so a weakness in either one — a nonce collision in the artifact
- * format, a padding oracle in the database format — becomes a weakness in
- * both. HKDF costs one hash and removes the coupling entirely (research.md
- * R4).
- *
- * The artifact id is the HKDF `info`, so two artifacts under the same
- * database key derive different subkeys. That is what makes the deterministic
- * nonce scheme safe: a nonce is only ever reused with a different key.
- */
-
-import { cipherModule } from './provider';
-
-const HKDF_DIGEST = 'sha256';
-const KEY_BYTES = 32;
-const NONCE_BYTES = 12;
-
-function bytesOf(value: string): Uint8Array {
-	return Uint8Array.from(Buffer.from(value, 'utf8'));
-}
-
-/** 32 bytes, one artifact, one database key. */
-export function deriveArtifactKey(
-	databaseKey: string,
-	scopeKey: string,
-	attachmentId: string,
-): Uint8Array {
-	const derived = cipherModule().hkdfSync(
-		HKDF_DIGEST,
-		bytesOf(databaseKey),
-		// The scope digest as salt keeps two scopes holding an artifact under
-		// the same id from deriving the same subkey.
-		bytesOf(scopeKey),
-		bytesOf(`chipmobilesdk-localdb/artifact/${attachmentId}`),
-		KEY_BYTES,
-	);
-	return new Uint8Array(derived);
-}
-
-/**
- * Deterministic 12-byte nonce from the chunk index.
- *
- * Deterministic rather than random because a random nonce would have to be
- * stored per chunk, and because uniqueness is already guaranteed one level
- * up: the key is unique per artifact, so an index that is unique within the
- * artifact is unique under that key. The remaining four bytes are a fixed
- * domain tag rather than padding, so a nonce from this scheme can never
- * collide with one from a future scheme that uses the same counter space.
- */
-export function nonceForChunk(index: number): Uint8Array {
-	const nonce = new Uint8Array(NONCE_BYTES);
-	const view = new DataView(nonce.buffer);
-	view.setUint32(0, 0x4c444231, false); // "LDB1"
-	// Split across two 32-bit writes rather than a BigInt: chunk indexes stay
-	// far inside the safe integer range, and Hermes is happier without one.
-	view.setUint32(4, Math.floor(index / 0x100000000), false);
-	view.setUint32(8, index % 0x100000000, false);
-	return nonce;
-}
+/**
+ * Per-artifact key derivation.
+ *
+ * The database key is handed straight to SQLCipher. Using that same material
+ * as the AES-GCM key for artifacts would mean the two keystreams share a
+ * secret, so a weakness in either one — a nonce collision in the artifact
+ * format, a padding oracle in the database format — becomes a weakness in
+ * both. HKDF costs one hash and removes the coupling entirely (research.md
+ * R4).
+ *
+ * The artifact id is the HKDF `info`, so two artifacts under the same
+ * database key derive different subkeys. That is what makes the deterministic
+ * nonce scheme safe: a nonce is only ever reused with a different key.
+ */
+
+import { cipherModule } from './provider';
+import { utf8Bytes } from '../platform/bytes';
+
+const HKDF_DIGEST = 'sha256';
+const KEY_BYTES = 32;
+const NONCE_BYTES = 12;
+
+function bytesOf(value: string): Uint8Array {
+	return utf8Bytes(value);
+}
+
+/** 32 bytes, one artifact, one database key. */
+export function deriveArtifactKey(
+	databaseKey: string,
+	scopeKey: string,
+	attachmentId: string,
+): Uint8Array {
+	const derived = cipherModule().hkdfSync(
+		HKDF_DIGEST,
+		bytesOf(databaseKey),
+		// The scope digest as salt keeps two scopes holding an artifact under
+		// the same id from deriving the same subkey.
+		bytesOf(scopeKey),
+		bytesOf(`chipmobilesdk-localdb/artifact/${attachmentId}`),
+		KEY_BYTES,
+	);
+	return new Uint8Array(derived);
+}
+
+/**
+ * Deterministic 12-byte nonce from the chunk index.
+ *
+ * Deterministic rather than random because a random nonce would have to be
+ * stored per chunk, and because uniqueness is already guaranteed one level
+ * up: the key is unique per artifact, so an index that is unique within the
+ * artifact is unique under that key. The remaining four bytes are a fixed
+ * domain tag rather than padding, so a nonce from this scheme can never
+ * collide with one from a future scheme that uses the same counter space.
+ */
+export function nonceForChunk(index: number): Uint8Array {
+	const nonce = new Uint8Array(NONCE_BYTES);
+	const view = new DataView(nonce.buffer);
+	view.setUint32(0, 0x4c444231, false); // "LDB1"
+	// Split across two 32-bit writes rather than a BigInt: chunk indexes stay
+	// far inside the safe integer range, and Hermes is happier without one.
+	view.setUint32(4, Math.floor(index / 0x100000000), false);
+	view.setUint32(8, index % 0x100000000, false);
+	return nonce;
+}