@chipmobilesdk/rn-local-db 0.1.0

package/src/contract/config.ts

@@ -0,0 +1,54 @@
+/**
+ * Database configuration: everything an app supplies at open time.
+ *
+ * Immutable for the handle's lifetime. Scope in particular is bound here and
+ * never changes (FR-008a) — there is no switchScope, and no operation takes a
+ * scope argument, which is what makes cross-scope leakage inexpressible
+ * rather than merely prevented.
+ */
+
+import type { BackupConfig } from './backup';
+import type { EncryptionConfig } from './encryption';
+import type { Migration } from './migration';
+import type { CollectionSchema } from './schema';
+import type { ScopeDescriptor } from './scope';
+
+/** Phase-one budgets (FR-088). Confirmed against the harness during validation. */
+export const Budgets = {
+	MAX_RECORDS_PER_COLLECTION: 100_000,
+	MAX_RECORD_BYTES: 256 * 1024,
+	MAX_BATCH_OPERATIONS: 1_000,
+	MAX_PAGE_SIZE: 500,
+	MAX_COLLECTIONS_PER_DATABASE: 50,
+	MAX_ATTACHMENT_REFERENCES_PER_SCOPE: 50_000,
+	MAX_ARTIFACT_BYTES: 100 * 1024 * 1024,
+	MAX_OPEN_HANDLES: 8,
+	/** Plaintext chunk size for encrypted artifacts (research.md R4). */
+	ARTIFACT_CHUNK_BYTES: 256 * 1024,
+} as const;
+
+export type DatabaseConfig = {
+	name: string;
+	scope: ScopeDescriptor;
+	/** Must equal the highest version in `migrations` (FR-053). */
+	schemaVersion: number;
+	collections: CollectionSchema[];
+	migrations?: Migration[];
+	/** Absent means unencrypted (FR-097). */
+	encryption?: EncryptionConfig;
+	/** Absent means excluded from platform backup (FR-109). */
+	backup?: BackupConfig;
+	/** Governs whether deleting a record removes its artifacts (FR-070). */
+	cascadeAttachments?: boolean;
+};
+
+/** Names a scope for the operations that legitimately need to (FR-059). */
+export type ScopeTargetConfig = {
+	name: string;
+	scope: ScopeDescriptor;
+	encryption?: EncryptionConfig;
+};
+
+export type DatabaseTargetConfig = {
+	name: string;
+};

package/src/contract/encryption.ts

@@ -0,0 +1,34 @@
+/**
+ * Opt-in encryption at rest under an app-supplied key.
+ *
+ * The package never generates, derives from its own material, persists,
+ * caches beyond the handle's lifetime, transmits, or returns a key (FR-098).
+ * Keeping key acquisition on the app side is also what keeps a keychain
+ * dependency out of this package entirely (LIB-004).
+ */
+
+import type { ResolvedScope } from './scope';
+
+/**
+ * Implemented by the consuming app. Receives the scope so an app can key per
+ * identity — which is what makes destroying one identity's key meaningful
+ * (FR-104).
+ */
+export type KeyProvider = {
+	getKey(scope: ResolvedScope): Promise<string>;
+};
+
+export type EncryptionConfig = {
+	enabled: true;
+	keyProvider: KeyProvider;
+};
+
+/**
+ * What the package will say about its own at-rest posture. Reported so a
+ * consumer can make an accurate privacy disclosure rather than assume one.
+ */
+export type EncryptionPosture = {
+	enabled: boolean;
+	/** Whether SQLCipher is actually compiled into the app (research.md R1a). */
+	available: boolean;
+};

package/src/contract/errors.ts

@@ -0,0 +1,76 @@
+/**
+ * Diagnostic codes.
+ *
+ * Stable identifiers so an app can choose a response without parsing a
+ * message (FR-074, FR-082). Disk-full, filesystem-access, and corruption stay
+ * distinct rather than collapsing into a generic write failure (FR-076) —
+ * an app frees space for one, retries after unlock for another, and offers a
+ * reset for the third.
+ *
+ * Full table with recommended recovery per code:
+ * specs/008-rn-local-db-package/contracts/errors.md
+ */
+
+export const DiagnosticCodes = {
+	// Configuration and scope
+	CONFIG_INVALID: 'CONFIG_INVALID',
+	INVALID_SCOPE: 'INVALID_SCOPE',
+	MIGRATION_CONFIG_INVALID: 'MIGRATION_CONFIG_INVALID',
+
+	// Open and lifecycle
+	OPEN_FAILED: 'OPEN_FAILED',
+	CLOSED_HANDLE: 'CLOSED_HANDLE',
+	SCOPE_DELETED: 'SCOPE_DELETED',
+	CORRUPTION: 'CORRUPTION',
+	STORAGE_ACCESS: 'STORAGE_ACCESS',
+
+	// Migration
+	MIGRATION_FAILED: 'MIGRATION_FAILED',
+	SCHEMA_DOWNGRADE: 'SCHEMA_DOWNGRADE',
+
+	// Records and writes
+	RECORD_NOT_FOUND: 'RECORD_NOT_FOUND',
+	RECORD_CONFLICT: 'RECORD_CONFLICT',
+	RECORD_TOO_LARGE: 'RECORD_TOO_LARGE',
+	BATCH_TOO_LARGE: 'BATCH_TOO_LARGE',
+	DISK_FULL: 'DISK_FULL',
+	WRITE_FAILED: 'WRITE_FAILED',
+
+	// Query
+	QUERY_INVALID: 'QUERY_INVALID',
+	PAGE_SIZE_INVALID: 'PAGE_SIZE_INVALID',
+	CURSOR_INVALID: 'CURSOR_INVALID',
+
+	// Transaction
+	TRANSACTION_FAILED: 'TRANSACTION_FAILED',
+	TRANSACTION_STATE: 'TRANSACTION_STATE',
+
+	// Attachments
+	ATTACHMENT_MISSING: 'ATTACHMENT_MISSING',
+	ATTACHMENT_OUT_OF_BOUNDS: 'ATTACHMENT_OUT_OF_BOUNDS',
+	ATTACHMENT_WRITE_FAILED: 'ATTACHMENT_WRITE_FAILED',
+	ATTACHMENT_UNDECRYPTABLE: 'ATTACHMENT_UNDECRYPTABLE',
+
+	// Encryption
+	KEY_INVALID: 'KEY_INVALID',
+	KEY_PROVIDER_FAILED: 'KEY_PROVIDER_FAILED',
+	ENCRYPTION_MISMATCH: 'ENCRYPTION_MISMATCH',
+	ENCRYPTION_UNAVAILABLE: 'ENCRYPTION_UNAVAILABLE',
+} as const;
+
+export type DiagnosticCode = (typeof DiagnosticCodes)[keyof typeof DiagnosticCodes];
+
+/**
+ * Codes worth retrying. `KEY_PROVIDER_FAILED` is here because a locked device
+ * is an expected condition, not a bug (FR-102).
+ */
+export const RETRYABLE_CODES: ReadonlySet<DiagnosticCode> = new Set<DiagnosticCode>([
+	DiagnosticCodes.OPEN_FAILED,
+	DiagnosticCodes.DISK_FULL,
+	DiagnosticCodes.WRITE_FAILED,
+	DiagnosticCodes.STORAGE_ACCESS,
+	DiagnosticCodes.TRANSACTION_FAILED,
+	DiagnosticCodes.MIGRATION_FAILED,
+	DiagnosticCodes.ATTACHMENT_WRITE_FAILED,
+	DiagnosticCodes.KEY_PROVIDER_FAILED,
+]);

package/src/contract/migration.ts

@@ -0,0 +1,40 @@
+/**
+ * Versioned migrations.
+ *
+ * The package never writes a migration and never alters domain data except
+ * through one the domain supplied (FR-056).
+ */
+
+import type { Transaction } from './transaction';
+
+/** Low-level escape hatch for schema work a migration needs. */
+export type MigrationContext = Transaction & {
+	/** Execute a raw statement against the scope's database. */
+	execute(sql: string, params?: unknown[]): Promise<void>;
+};
+
+export type Migration = {
+	/** Unique, contiguous, and reaching the declared schemaVersion (FR-053). */
+	version: number;
+	migrate(context: MigrationContext): Promise<void>;
+};
+
+export type MigrationOutcome = 'applied' | 'failed';
+
+export type MigrationLedgerEntry = {
+	version: number;
+	attemptedAt: number;
+	outcome: MigrationOutcome;
+	/** A diagnostic code only — never a message, which could carry payload. */
+	failureCode?: string;
+};
+
+/**
+ * Attached to a MIGRATION_FAILED error so an app can tell a transient failure
+ * from a permanent one and choose retry, reset, or asking the user (FR-057c).
+ */
+export type MigrationFailureDetail = {
+	recordedVersion: number;
+	failingVersion: number;
+	outcome: MigrationOutcome;
+};

package/src/contract/query.ts

@@ -0,0 +1,81 @@
+/**
+ * Query contract.
+ *
+ * A query carries no scope, because it cannot address one — scope is bound to
+ * the handle and immutable (FR-008a). That absence is the isolation
+ * guarantee, not a convention.
+ */
+
+import type { StorableRecordData, StoredRecord } from './record';
+
+/** Values a filter may compare against. */
+export type FilterValue = string | number | boolean | null;
+
+export type ComparisonOperator =
+	| 'eq'
+	| 'ne'
+	| 'lt'
+	| 'lte'
+	| 'gt'
+	| 'gte'
+	| 'in'
+	| 'nin'
+	| 'between'
+	| 'isNull'
+	| 'isNotNull'
+	| 'exists';
+
+export type ComparisonNode =
+	| { op: 'eq' | 'ne' | 'lt' | 'lte' | 'gt' | 'gte'; field: string; value: FilterValue }
+	| { op: 'in' | 'nin'; field: string; value: FilterValue[] }
+	| { op: 'between'; field: string; value: [FilterValue, FilterValue] }
+	| { op: 'isNull' | 'isNotNull'; field: string }
+	/** Distinguishes an absent field from one holding null (FR-019). */
+	| { op: 'exists'; field: string; value: boolean };
+
+export type LogicalNode =
+	| { op: 'and'; nodes: FilterNode[] }
+	| { op: 'or'; nodes: FilterNode[] }
+	| { op: 'not'; node: FilterNode };
+
+export type FilterNode = ComparisonNode | LogicalNode;
+
+export type SortDirection = 'asc' | 'desc';
+
+export type SortKey = {
+	field: string;
+	direction?: SortDirection;
+};
+
+export type PageRequest = {
+	/** 1..500 (FR-036, FR-088). */
+	size: number;
+	/** Opaque keyset cursor from a previous page. */
+	cursor?: string;
+};
+
+export type Query = {
+	filter?: FilterNode;
+	sort?: SortKey[];
+	page?: PageRequest;
+	/** Soft-deleted records are excluded unless this is true (FR-021). */
+	includeSoftDeleted?: boolean;
+};
+
+export type ResultPage<T extends StorableRecordData = StorableRecordData> = {
+	records: StoredRecord<T>[];
+	/** Absent when there is no further page. */
+	cursor?: string;
+	hasMore: boolean;
+};
+
+/**
+ * Development-only answer to "is this query covered by an index?" (FR-037).
+ * Backed by EXPLAIN QUERY PLAN on the SQLite adapter.
+ */
+export type IndexCoverageReport = {
+	collection: string;
+	usesIndex: boolean;
+	indexName?: string;
+	detail: string;
+};

package/src/contract/record.ts

@@ -0,0 +1,42 @@
+/**
+ * Records and the four value conditions.
+ *
+ * The distinction FR-019 requires — record absent, field explicitly null,
+ * field absent, record soft-deleted — is preserved because reads reconstruct
+ * from the stored payload alone and never from projected columns. See
+ * research.md R6.
+ */
+
+/** Anything the package will store and hand back unchanged. */
+export type StorableValue =
+	| string
+	| number
+	| boolean
+	| null
+	| StorableValue[]
+	| { [key: string]: StorableValue };
+
+export type StorableRecordData = { [key: string]: StorableValue };
+
+export type RecordInput<T extends StorableRecordData = StorableRecordData> = {
+	id: string;
+	data: T;
+};
+
+export type StoredRecord<T extends StorableRecordData = StorableRecordData> = {
+	id: string;
+	data: T;
+	/** Present only when the collection declares timestamps (FR-020). */
+	createdAt?: number;
+	updatedAt?: number;
+	/** Present only when soft-deleted (FR-021). */
+	deletedAt?: number | null;
+};
+
+export type WriteOperation = 'created' | 'updated' | 'deleted' | 'restored';
+
+/** An upsert reports which it actually was (FR-026). */
+export type WriteOutcome = {
+	operation: WriteOperation;
+	id: string;
+};

package/src/contract/schema.ts

@@ -0,0 +1,36 @@
+/**
+ * Collection schema: structure only.
+ *
+ * Declaring a field makes it queryable and projectable. It does NOT restrict
+ * what a record may contain — undeclared fields are stored and returned
+ * faithfully, they are simply not filterable or sortable (FR-017, FR-034).
+ */
+
+export type FieldType = 'string' | 'number' | 'boolean' | 'timestamp';
+
+export type FieldDeclaration = {
+	name: string;
+	type: FieldType;
+	/** Whether the projected column tolerates SQL NULL. Purely a query concern. */
+	nullable?: boolean;
+};
+
+export type IndexDeclaration = {
+	name: string;
+	/** Must all reference declared fields (FR-006). */
+	fields: string[];
+	unique?: boolean;
+};
+
+export type CollectionSchema = {
+	name: string;
+	fields: FieldDeclaration[];
+	indexes?: IndexDeclaration[];
+	/**
+	 * Opt-in per collection, off by default. When on, deleted rows are
+	 * excluded from queries unless explicitly requested (FR-021).
+	 */
+	softDelete?: boolean;
+	/** When on, the package maintains createdAt / updatedAt (FR-020). */
+	timestamps?: boolean;
+};

package/src/contract/scope.ts

@@ -0,0 +1,36 @@
+/**
+ * Storage scope: the isolation boundary for all data.
+ *
+ * Components are opaque values the consuming app supplies. The package
+ * composes, normalizes, and validates them but never interprets them, and
+ * never invents one of its own (FR-008, FR-009).
+ */
+
+export type ScopeKind = 'guest' | 'identity' | 'tenant' | 'workspace' | 'custom';
+
+/**
+ * What an app supplies to name a scope.
+ *
+ * Every component is treated as sensitive (FR-014): none of these values
+ * reaches disk, a log, or an error. Only the SHA-256 digest of the canonical
+ * form does.
+ */
+export type ScopeDescriptor = {
+	kind: ScopeKind;
+	/** Required for every kind except `guest`. */
+	id?: string;
+	tenant?: string;
+	app?: string;
+	environment?: string;
+	namespace?: string;
+};
+
+/** The resolved scope: a hex digest, plus the kind it came from. */
+export type ResolvedScope = {
+	/** SHA-256 hex of the canonical descriptor. Names the scope's directory. */
+	key: string;
+	kind: ScopeKind;
+};
+
+/** Where a scope sits in its lifecycle. Persisted in the catalog (FR-063). */
+export type ScopeDeletionState = 'active' | 'deleting';

package/src/contract/transaction.ts

@@ -0,0 +1,46 @@
+/**
+ * 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[];
+};

package/src/crypto/chunked-cipher.ts

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

package/src/crypto/derive.ts

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