@noy-db/core 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,526 @@
+/** Format version for encrypted record envelopes. */
+declare const NOYDB_FORMAT_VERSION: 1;
+/** Format version for keyring files. */
+declare const NOYDB_KEYRING_VERSION: 1;
+/** Format version for backup files. */
+declare const NOYDB_BACKUP_VERSION: 1;
+/** Format version for sync metadata. */
+declare const NOYDB_SYNC_VERSION: 1;
+type Role = 'owner' | 'admin' | 'operator' | 'viewer' | 'client';
+type Permission = 'rw' | 'ro';
+type Permissions = Record<string, Permission>;
+/** The encrypted wrapper stored by adapters. Adapters only ever see this. */
+interface EncryptedEnvelope {
+    readonly _noydb: typeof NOYDB_FORMAT_VERSION;
+    readonly _v: number;
+    readonly _ts: string;
+    readonly _iv: string;
+    readonly _data: string;
+    /** User who created this version (unencrypted metadata). */
+    readonly _by?: string;
+}
+/** All records across all collections for a compartment. */
+type CompartmentSnapshot = Record<string, Record<string, EncryptedEnvelope>>;
+interface NoydbAdapter {
+    /** Get a single record. Returns null if not found. */
+    get(compartment: string, collection: string, id: string): Promise<EncryptedEnvelope | null>;
+    /** Put a record. Throws ConflictError if expectedVersion doesn't match. */
+    put(compartment: string, collection: string, id: string, envelope: EncryptedEnvelope, expectedVersion?: number): Promise<void>;
+    /** Delete a record. */
+    delete(compartment: string, collection: string, id: string): Promise<void>;
+    /** List all record IDs in a collection. */
+    list(compartment: string, collection: string): Promise<string[]>;
+    /** Load all records for a compartment (initial hydration). */
+    loadAll(compartment: string): Promise<CompartmentSnapshot>;
+    /** Save all records for a compartment (bulk write / restore). */
+    saveAll(compartment: string, data: CompartmentSnapshot): Promise<void>;
+    /** Optional connectivity check for sync engine. */
+    ping?(): Promise<boolean>;
+}
+/** Type-safe helper for creating adapter factories. */
+declare function defineAdapter<TOptions>(factory: (options: TOptions) => NoydbAdapter): (options: TOptions) => NoydbAdapter;
+interface KeyringFile {
+    readonly _noydb_keyring: typeof NOYDB_KEYRING_VERSION;
+    readonly user_id: string;
+    readonly display_name: string;
+    readonly role: Role;
+    readonly permissions: Permissions;
+    readonly deks: Record<string, string>;
+    readonly salt: string;
+    readonly created_at: string;
+    readonly granted_by: string;
+}
+interface CompartmentBackup {
+    readonly _noydb_backup: typeof NOYDB_BACKUP_VERSION;
+    readonly _compartment: string;
+    readonly _exported_at: string;
+    readonly _exported_by: string;
+    readonly keyrings: Record<string, KeyringFile>;
+    readonly collections: CompartmentSnapshot;
+}
+interface DirtyEntry {
+    readonly compartment: string;
+    readonly collection: string;
+    readonly id: string;
+    readonly action: 'put' | 'delete';
+    readonly version: number;
+    readonly timestamp: string;
+}
+interface SyncMetadata {
+    readonly _noydb_sync: typeof NOYDB_SYNC_VERSION;
+    readonly last_push: string | null;
+    readonly last_pull: string | null;
+    readonly dirty: DirtyEntry[];
+}
+interface Conflict {
+    readonly compartment: string;
+    readonly collection: string;
+    readonly id: string;
+    readonly local: EncryptedEnvelope;
+    readonly remote: EncryptedEnvelope;
+    readonly localVersion: number;
+    readonly remoteVersion: number;
+}
+type ConflictStrategy = 'local-wins' | 'remote-wins' | 'version' | ((conflict: Conflict) => 'local' | 'remote');
+interface PushResult {
+    readonly pushed: number;
+    readonly conflicts: Conflict[];
+    readonly errors: Error[];
+}
+interface PullResult {
+    readonly pulled: number;
+    readonly conflicts: Conflict[];
+    readonly errors: Error[];
+}
+interface SyncStatus {
+    readonly dirty: number;
+    readonly lastPush: string | null;
+    readonly lastPull: string | null;
+    readonly online: boolean;
+}
+interface ChangeEvent {
+    readonly compartment: string;
+    readonly collection: string;
+    readonly id: string;
+    readonly action: 'put' | 'delete';
+}
+interface NoydbEventMap {
+    'change': ChangeEvent;
+    'error': Error;
+    'sync:push': PushResult;
+    'sync:pull': PullResult;
+    'sync:conflict': Conflict;
+    'sync:online': void;
+    'sync:offline': void;
+    'history:save': {
+        compartment: string;
+        collection: string;
+        id: string;
+        version: number;
+    };
+    'history:prune': {
+        compartment: string;
+        collection: string;
+        id: string;
+        pruned: number;
+    };
+}
+interface GrantOptions {
+    readonly userId: string;
+    readonly displayName: string;
+    readonly role: Role;
+    readonly passphrase: string;
+    readonly permissions?: Permissions;
+}
+interface RevokeOptions {
+    readonly userId: string;
+    readonly rotateKeys?: boolean;
+}
+interface UserInfo {
+    readonly userId: string;
+    readonly displayName: string;
+    readonly role: Role;
+    readonly permissions: Permissions;
+    readonly createdAt: string;
+    readonly grantedBy: string;
+}
+interface NoydbOptions {
+    /** Primary adapter (local storage). */
+    readonly adapter: NoydbAdapter;
+    /** Optional remote adapter for sync. */
+    readonly sync?: NoydbAdapter;
+    /** User identifier. */
+    readonly user: string;
+    /** Passphrase for key derivation. Required unless encrypt is false. */
+    readonly secret?: string;
+    /** Auth method. Default: 'passphrase'. */
+    readonly auth?: 'passphrase' | 'biometric';
+    /** Enable encryption. Default: true. */
+    readonly encrypt?: boolean;
+    /** Conflict resolution strategy. Default: 'version'. */
+    readonly conflict?: ConflictStrategy;
+    /** Auto-sync on online/offline events. Default: false. */
+    readonly autoSync?: boolean;
+    /** Periodic sync interval in ms. Default: 30000. */
+    readonly syncInterval?: number;
+    /** Session timeout in ms. Clears keys after inactivity. Default: none. */
+    readonly sessionTimeout?: number;
+    /** Validate passphrase strength on creation. Default: true. */
+    readonly validatePassphrase?: boolean;
+    /** Audit history configuration. */
+    readonly history?: HistoryConfig;
+}
+/** History configuration. */
+interface HistoryConfig {
+    /** Enable history tracking. Default: true. */
+    readonly enabled?: boolean;
+    /** Maximum history entries per record. Oldest pruned on overflow. Default: unlimited. */
+    readonly maxVersions?: number;
+}
+/** Options for querying history. */
+interface HistoryOptions {
+    /** Start date (inclusive), ISO 8601. */
+    readonly from?: string;
+    /** End date (inclusive), ISO 8601. */
+    readonly to?: string;
+    /** Maximum entries to return. */
+    readonly limit?: number;
+}
+/** Options for pruning history. */
+interface PruneOptions {
+    /** Keep only the N most recent versions. */
+    readonly keepVersions?: number;
+    /** Delete versions older than this date, ISO 8601. */
+    readonly beforeDate?: string;
+}
+/** A decrypted history entry. */
+interface HistoryEntry<T> {
+    readonly version: number;
+    readonly timestamp: string;
+    readonly userId: string;
+    readonly record: T;
+}
+
+declare class NoydbError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+declare class DecryptionError extends NoydbError {
+    constructor(message?: string);
+}
+declare class TamperedError extends NoydbError {
+    constructor(message?: string);
+}
+declare class InvalidKeyError extends NoydbError {
+    constructor(message?: string);
+}
+declare class NoAccessError extends NoydbError {
+    constructor(message?: string);
+}
+declare class ReadOnlyError extends NoydbError {
+    constructor(message?: string);
+}
+declare class PermissionDeniedError extends NoydbError {
+    constructor(message?: string);
+}
+declare class ConflictError extends NoydbError {
+    readonly version: number;
+    constructor(version: number, message?: string);
+}
+declare class NetworkError extends NoydbError {
+    constructor(message?: string);
+}
+declare class NotFoundError extends NoydbError {
+    constructor(message?: string);
+}
+declare class ValidationError extends NoydbError {
+    constructor(message?: string);
+}
+
+/** In-memory representation of an unlocked keyring. */
+interface UnlockedKeyring {
+    readonly userId: string;
+    readonly displayName: string;
+    readonly role: Role;
+    readonly permissions: Permissions;
+    readonly deks: Map<string, CryptoKey>;
+    readonly kek: CryptoKey;
+    readonly salt: Uint8Array;
+}
+
+type EventHandler<T> = (data: T) => void;
+/** Typed event emitter for NOYDB events. */
+declare class NoydbEventEmitter {
+    private readonly listeners;
+    on<K extends keyof NoydbEventMap>(event: K, handler: EventHandler<NoydbEventMap[K]>): void;
+    off<K extends keyof NoydbEventMap>(event: K, handler: EventHandler<NoydbEventMap[K]>): void;
+    emit<K extends keyof NoydbEventMap>(event: K, data: NoydbEventMap[K]): void;
+    removeAllListeners(): void;
+}
+
+/**
+ * Zero-dependency JSON diff.
+ * Produces a flat list of changes between two plain objects.
+ */
+type ChangeType = 'added' | 'removed' | 'changed';
+interface DiffEntry {
+    /** Dot-separated path to the changed field (e.g. "address.city"). */
+    readonly path: string;
+    /** Type of change. */
+    readonly type: ChangeType;
+    /** Previous value (undefined for 'added'). */
+    readonly from?: unknown;
+    /** New value (undefined for 'removed'). */
+    readonly to?: unknown;
+}
+/**
+ * Compute differences between two objects.
+ * Returns an array of DiffEntry describing each changed field.
+ * Returns empty array if objects are identical.
+ */
+declare function diff(oldObj: unknown, newObj: unknown, basePath?: string): DiffEntry[];
+/** Format a diff as a human-readable string. */
+declare function formatDiff(changes: DiffEntry[]): string;
+
+/** Callback for dirty tracking (sync engine integration). */
+type OnDirtyCallback = (collection: string, id: string, action: 'put' | 'delete', version: number) => Promise<void>;
+/** A typed collection of records within a compartment. */
+declare class Collection<T> {
+    private readonly adapter;
+    private readonly compartment;
+    private readonly name;
+    private readonly keyring;
+    private readonly encrypted;
+    private readonly emitter;
+    private readonly getDEK;
+    private readonly onDirty;
+    private readonly historyConfig;
+    private readonly cache;
+    private hydrated;
+    constructor(opts: {
+        adapter: NoydbAdapter;
+        compartment: string;
+        name: string;
+        keyring: UnlockedKeyring;
+        encrypted: boolean;
+        emitter: NoydbEventEmitter;
+        getDEK: (collectionName: string) => Promise<CryptoKey>;
+        historyConfig?: HistoryConfig | undefined;
+        onDirty?: OnDirtyCallback | undefined;
+    });
+    /** Get a single record by ID. Returns null if not found. */
+    get(id: string): Promise<T | null>;
+    /** Create or update a record. */
+    put(id: string, record: T): Promise<void>;
+    /** Delete a record by ID. */
+    delete(id: string): Promise<void>;
+    /** List all records in the collection. */
+    list(): Promise<T[]>;
+    /** Filter records by a predicate. */
+    query(predicate: (record: T) => boolean): T[];
+    /** Get version history for a record, newest first. */
+    history(id: string, options?: HistoryOptions): Promise<HistoryEntry<T>[]>;
+    /** Get a specific past version of a record. */
+    getVersion(id: string, version: number): Promise<T | null>;
+    /** Revert a record to a past version. Creates a new version with the old content. */
+    revert(id: string, version: number): Promise<void>;
+    /**
+     * Compare two versions of a record and return the differences.
+     * Use version 0 to represent "before creation" (empty).
+     * Omit versionB to compare against the current version.
+     */
+    diff(id: string, versionA: number, versionB?: number): Promise<DiffEntry[]>;
+    /** Resolve a version: try history first, then check if it's the current version. */
+    private resolveVersion;
+    private resolveCurrentOrVersion;
+    /** Prune history entries for a record (or all records if id is undefined). */
+    pruneRecordHistory(id: string | undefined, options: PruneOptions): Promise<number>;
+    /** Clear all history for this collection (or a specific record). */
+    clearHistory(id?: string): Promise<number>;
+    /** Count records in the collection. */
+    count(): Promise<number>;
+    /** Load all records from adapter into memory cache. */
+    private ensureHydrated;
+    /** Hydrate from a pre-loaded snapshot (used by Compartment). */
+    hydrateFromSnapshot(records: Record<string, EncryptedEnvelope>): Promise<void>;
+    /** Get all records as encrypted envelopes (for dump). */
+    dumpEnvelopes(): Promise<Record<string, EncryptedEnvelope>>;
+    private encryptRecord;
+    private decryptRecord;
+}
+
+/** A compartment (tenant namespace) containing collections. */
+declare class Compartment {
+    private readonly adapter;
+    private readonly name;
+    private readonly keyring;
+    private readonly encrypted;
+    private readonly emitter;
+    private readonly onDirty;
+    private readonly historyConfig;
+    private readonly getDEK;
+    private readonly collectionCache;
+    constructor(opts: {
+        adapter: NoydbAdapter;
+        name: string;
+        keyring: UnlockedKeyring;
+        encrypted: boolean;
+        emitter: NoydbEventEmitter;
+        onDirty?: OnDirtyCallback | undefined;
+        historyConfig?: HistoryConfig | undefined;
+    });
+    /** Open a typed collection within this compartment. */
+    collection<T>(collectionName: string): Collection<T>;
+    /** List all collection names in this compartment. */
+    collections(): Promise<string[]>;
+    /** Dump compartment as encrypted JSON backup string. */
+    dump(): Promise<string>;
+    /** Restore compartment from an encrypted JSON backup string. */
+    load(backupJson: string): Promise<void>;
+    /** Export compartment as decrypted JSON (owner only). */
+    export(): Promise<string>;
+}
+
+/** The top-level NOYDB instance. */
+declare class Noydb {
+    private readonly options;
+    private readonly emitter;
+    private readonly compartmentCache;
+    private readonly keyringCache;
+    private readonly syncEngines;
+    private closed;
+    private sessionTimer;
+    constructor(options: NoydbOptions);
+    private resetSessionTimer;
+    /** Open a compartment by name. */
+    openCompartment(name: string): Promise<Compartment>;
+    /** Synchronous compartment access (must call openCompartment first, or auto-opens). */
+    compartment(name: string): Compartment;
+    /** Grant access to a user for a compartment. */
+    grant(compartment: string, options: GrantOptions): Promise<void>;
+    /** Revoke a user's access to a compartment. */
+    revoke(compartment: string, options: RevokeOptions): Promise<void>;
+    /** List all users with access to a compartment. */
+    listUsers(compartment: string): Promise<UserInfo[]>;
+    /** Change the current user's passphrase for a compartment. */
+    changeSecret(compartment: string, newPassphrase: string): Promise<void>;
+    /** Push local changes to remote for a compartment. */
+    push(compartment: string): Promise<PushResult>;
+    /** Pull remote changes to local for a compartment. */
+    pull(compartment: string): Promise<PullResult>;
+    /** Bidirectional sync: pull then push. */
+    sync(compartment: string): Promise<{
+        pull: PullResult;
+        push: PushResult;
+    }>;
+    /** Get sync status for a compartment. */
+    syncStatus(compartment: string): SyncStatus;
+    private getSyncEngine;
+    on<K extends keyof NoydbEventMap>(event: K, handler: (data: NoydbEventMap[K]) => void): void;
+    off<K extends keyof NoydbEventMap>(event: K, handler: (data: NoydbEventMap[K]) => void): void;
+    close(): void;
+    /** Get or load the keyring for a compartment. */
+    private getKeyring;
+}
+/** Create a new NOYDB instance. */
+declare function createNoydb(options: NoydbOptions): Promise<Noydb>;
+
+/** Sync engine: dirty tracking, push, pull, conflict resolution. */
+declare class SyncEngine {
+    private readonly local;
+    private readonly remote;
+    private readonly strategy;
+    private readonly emitter;
+    private readonly compartment;
+    private dirty;
+    private lastPush;
+    private lastPull;
+    private loaded;
+    private autoSyncInterval;
+    private isOnline;
+    constructor(opts: {
+        local: NoydbAdapter;
+        remote: NoydbAdapter;
+        compartment: string;
+        strategy: ConflictStrategy;
+        emitter: NoydbEventEmitter;
+    });
+    /** Record a local change for later push. */
+    trackChange(collection: string, id: string, action: 'put' | 'delete', version: number): Promise<void>;
+    /** Push dirty records to remote adapter. */
+    push(): Promise<PushResult>;
+    /** Pull remote records to local adapter. */
+    pull(): Promise<PullResult>;
+    /** Bidirectional sync: pull then push. */
+    sync(): Promise<{
+        pull: PullResult;
+        push: PushResult;
+    }>;
+    /** Get current sync status. */
+    status(): SyncStatus;
+    /** Start auto-sync: listen for online/offline events, optional periodic sync. */
+    startAutoSync(intervalMs?: number): void;
+    /** Stop auto-sync. */
+    stopAutoSync(): void;
+    private handleOnline;
+    private handleOffline;
+    /** Resolve a conflict using the configured strategy. */
+    private resolveConflict;
+    private ensureLoaded;
+    private persistMeta;
+}
+
+/**
+ * WebAuthn biometric enrollment and unlock.
+ *
+ * Enrollment: User enters passphrase → derive KEK → create WebAuthn credential
+ *   → wrap KEK with credential-derived key → store { credentialId, wrappedKek }
+ *
+ * Unlock: Retrieve { credentialId, wrappedKek } → WebAuthn assertion
+ *   → unwrap KEK → proceed as passphrase auth
+ *
+ * This module requires a browser environment with WebAuthn support.
+ */
+interface BiometricCredential {
+    credentialId: string;
+    wrappedKek: string;
+    salt: string;
+}
+/** Check if WebAuthn is available in the current environment. */
+declare function isBiometricAvailable(): boolean;
+/**
+ * Enroll a biometric credential for the current user.
+ * Must be called after passphrase authentication (KEK is in memory).
+ *
+ * @param userId - User identifier for WebAuthn
+ * @param kek - The KEK derived from the user's passphrase (in memory)
+ * @returns BiometricCredential to persist in browser storage
+ */
+declare function enrollBiometric(userId: string, kek: CryptoKey): Promise<BiometricCredential>;
+/**
+ * Unlock using a previously enrolled biometric credential.
+ *
+ * @param storedCredential - The stored BiometricCredential from enrollment
+ * @returns The unwrapped KEK as a CryptoKey
+ */
+declare function unlockBiometric(storedCredential: BiometricCredential): Promise<CryptoKey>;
+/** Remove biometric enrollment from browser storage. */
+declare function removeBiometric(storage: Storage, userId: string): void;
+/** Save biometric credential to browser storage. */
+declare function saveBiometric(storage: Storage, userId: string, credential: BiometricCredential): void;
+/** Load biometric credential from browser storage. */
+declare function loadBiometric(storage: Storage, userId: string): BiometricCredential | null;
+
+/**
+ * Validate passphrase strength.
+ * Checks length and basic entropy heuristics.
+ * Throws ValidationError if too weak.
+ */
+declare function validatePassphrase(passphrase: string): void;
+/**
+ * Estimate passphrase entropy in bits.
+ * Uses character class analysis (not dictionary-based).
+ */
+declare function estimateEntropy(passphrase: string): number;
+
+export { type BiometricCredential, type ChangeEvent, type ChangeType, Collection, Compartment, type CompartmentBackup, type CompartmentSnapshot, type Conflict, ConflictError, type ConflictStrategy, DecryptionError, type DiffEntry, type DirtyEntry, type EncryptedEnvelope, type GrantOptions, type HistoryConfig, type HistoryEntry, type HistoryOptions, InvalidKeyError, type KeyringFile, NOYDB_BACKUP_VERSION, NOYDB_FORMAT_VERSION, NOYDB_KEYRING_VERSION, NOYDB_SYNC_VERSION, NetworkError, NoAccessError, NotFoundError, Noydb, type NoydbAdapter, NoydbError, type NoydbEventMap, type NoydbOptions, type Permission, PermissionDeniedError, type Permissions, type PruneOptions, type PullResult, type PushResult, ReadOnlyError, type RevokeOptions, type Role, SyncEngine, type SyncMetadata, type SyncStatus, TamperedError, type UserInfo, ValidationError, createNoydb, defineAdapter, diff, enrollBiometric, estimateEntropy, formatDiff, isBiometricAvailable, loadBiometric, removeBiometric, saveBiometric, unlockBiometric, validatePassphrase };