@docstack/client 0.1.4 → 0.1.6

package/LICENSE

@@ -0,0 +1,10 @@
+Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)
+
+Copyright (c) Onyx <hello@onyx.ac> (https://onyx.ac)
+
+This work is licensed under the Creative Commons Attribution-ShareAlike 4.0
+International License. You are free to share and adapt this work, including
+commercially, provided you give appropriate attribution and distribute any
+derivative works under the same license.
+
+Full legal text: https://creativecommons.org/licenses/by-sa/4.0/legalcode

package/README.md

@@ -3,7 +3,7 @@
 
 # @docstack/client
 
-**The Intelligent, Offline-First Database Engine for Modern Web Apps.**
+**One does not simply stack documents.**
 
 DocStack Client is a standalone, browser-based datastore built on PouchDB. It bridges the gap between simple client-side storage and full-fledged backend databases by bringing schemas, relationships, SQL-like querying, and background processing directly to the browser.
 

package/lib/core/attribute.d.ts

@@ -1,4 +1,4 @@
-import { SafeParseReturnType } from "zod";
+import { ZodSafeParseResult } from "zod";
 import Class from "./class.js";
 import { Attribute as Attribute_, AttributeModel, AttributeType, AttributeTypeConfig } from "@docstack/shared";
 /**
@@ -57,6 +57,15 @@ declare class Attribute extends Attribute_ {
      * @throws Error if the reference configuration is invalid
      */
     ensureReferenceConfigIsValid: () => Promise<void>;
+    /**
+     * Built Zod fields, shared across attributes with the same type and config.
+     *
+     * An attribute's validator is a pure function of `(type, config)`, and the same
+     * handful of shapes recur across every class build - which happens per snapshot,
+     * per schema propagation, and per cold class fetch. `foreign_key` is the one type
+     * excluded: its refinement closes over the owning instance's class and stack.
+     */
+    private static fieldCache;
     /**
      * Builds the Zod validation schema based on attribute type and configuration.
      * Called automatically during construction.
@@ -120,7 +129,7 @@ declare class Attribute extends Attribute_ {
      * }
      * ```
      */
-    validate: (data: any) => Promise<SafeParseReturnType<any, any>>;
+    validate: (data: any) => Promise<ZodSafeParseResult<any>>;
     /**
      * Adds an attribute to its parent class and persists to the database.
      * Used internally by {@link Attribute.create}.

package/lib/core/class.d.ts

@@ -1,9 +1,30 @@
 import { Class as Class_, TriggerModel } from "@docstack/shared";
 import { Stack, ClassModel, Attribute as Attribute_, AttributeModel, Document } from "@docstack/shared";
 import Attribute from "./attribute.js";
-import { Logger } from 'winston';
+import type { Logger } from '../utils/logger/index.js';
 import { Trigger } from "./trigger/index.js";
 import { z } from "zod";
+/**
+ * How a Class instance should be built.
+ *
+ * @example
+ * ```typescript
+ * // Just the schema, for validating one write - no live subscription to release.
+ * const schemaOnly = await Class.fetch(stack, 'Task', { subscribe: false });
+ * ```
+ */
+export type ClassBuildOptions = {
+    /**
+     * Whether the instance watches its documents and emits `doc` events. Defaults to
+     * `true`.
+     *
+     * Set it to `false` for an instance that is only being read for its schema.
+     * Subscribing is not free - the handle lives until it is closed - so a caller that
+     * builds a Class per write or per read row must not subscribe, or the database
+     * accumulates live feeds and PouchDB warns about its `destroyed` listeners.
+     */
+    subscribe?: boolean;
+};
 /**
  * Represents a data class (schema definition) in the DocStack database.
  *
@@ -44,7 +65,7 @@ declare class Class extends Class_ {
     /** The raw schema definition from the ClassModel. */
     schema: ClassModel["schema"];
     /** Zod schema for runtime validation of document data. */
-    schemaZOD: z.ZodObject<any, any, any>;
+    schemaZOD: z.ZodObject<any>;
     /** The unique identifier for this class (e.g., 'Task', 'Class-123'). */
     id?: string;
     /** The underlying ClassModel document. */
@@ -71,7 +92,7 @@ declare class Class extends Class_ {
      * @param schema - Initial schema definition
      * @returns A new Class instance (not persisted)
      */
-    static get: (stack: Stack, id: string, name: string, type: ClassModel["~class"], description?: string, schema?: ClassModel["schema"]) => Class;
+    static get: (stack: Stack, id: string, name: string, type: ClassModel["~class"], description?: string, schema?: ClassModel["schema"], options?: ClassBuildOptions) => Class;
     /**
      * Creates a new class and persists it to the database.
      * This is the primary factory method for creating new classes.
@@ -97,7 +118,7 @@ declare class Class extends Class_ {
      * @param classModel - The ClassModel document from the database
      * @returns The hydrated Class instance
      */
-    static buildFromModel: (stack: Stack, classModel: ClassModel) => Promise<Class>;
+    static buildFromModel: (stack: Stack, classModel: ClassModel, options?: ClassBuildOptions) => Promise<Class>;
     /**
      * Fetches a class by its document ID.
      *
@@ -123,7 +144,7 @@ declare class Class extends Class_ {
      * }
      * ```
      */
-    static fetch: (stack: Stack, className: string) => Promise<Class>;
+    static fetch: (stack: Stack, className: string, options?: ClassBuildOptions) => Promise<Class>;
     uniqueCheck: (doc: Document) => Promise<boolean>;
     bulkUniqueCheck: (pKs: string[]) => Promise<boolean>;
     /**
@@ -256,6 +277,17 @@ declare class Class extends Class_ {
     addOrUpdateCard: (params: {
         [key: string]: any;
     }, cardId?: string) => Promise<Document | null>;
+    /**
+     * Pushes a document to the database.
+     * This is an alias for {@alias addOrUpdateCard}.
+     *
+     * @param params - The document data
+     * @param docId - Optional document ID. If provided, performs an update.
+     * @returns The created or updated document
+     */
+    push: (params: {
+        [key: string]: any;
+    }, docId?: string) => Promise<Document | null>;
     /**
      * Updates an existing document (card) of this class.
      *
@@ -293,7 +325,9 @@ declare class Class extends Class_ {
      */
     getCards: (selector?: {
         [key: string]: any;
-    }, fields?: string[], skip?: number, limit?: number) => Promise<Document[]>;
+    }, fields?: string[], skip?: number, limit?: number, sort?: {
+        [field: string]: "asc" | "desc";
+    }[]) => Promise<Document[]>;
     /**
      * Retrieves one or more documents by their IDs.
      *

package/lib/core/content-transfer.d.ts

@@ -0,0 +1,178 @@
+import { Document, RelationDocument } from "@docstack/shared";
+/**
+ * Moving a stack's *content* between databases, without its datamodel.
+ *
+ * `stack.dump()` is the other kind of export: every document exactly as stored, which
+ * means class models, patches, users, sessions, policies, design documents - and
+ * encrypted attributes as unreadable {@link EncryptedPayload} blobs. That is a debugging
+ * tool and a backup of one database.
+ *
+ * This is the portable one. It carries the documents an application put in, in the clear,
+ * so that {@link ClientStack.importContent} can place them into a *different* stack -
+ * different device, different key, schema built by that stack's own patches.
+ *
+ * @module
+ */
+/** The envelope format identifier, so an importer can refuse what it does not understand. */
+export declare const CONTENT_EXPORT_FORMAT = "docstack/content-export@1";
+/**
+ * `~class` values that describe the stack rather than hold its content.
+ *
+ * `~self` is the bootstrap class-of-classes; `class` and `superclass` are class models;
+ * `domain` is a relation definition; `patch` is the local ledger of applied patches.
+ */
+export declare const META_CLASSES: readonly string[];
+/**
+ * Reports whether a class name belongs to application content.
+ *
+ * DocStack names everything it owns with a leading `~` - `~User`, `~Group`, `~Policy`,
+ * `~Job`, `~JobRun`, `~UserSession`, `~AuthModule`, `~lock` - and reserves the handful of
+ * unprefixed names in {@link META_CLASSES} for the datamodel itself. Everything else was
+ * created by an application.
+ *
+ * @param className - A `~class` value or class-model id.
+ *
+ * @example
+ * ```typescript
+ * isContentClassName("Task");   // true
+ * isContentClassName("~User");  // false - DocStack's own
+ * isContentClassName("class");  // false - a class model
+ * ```
+ */
+export declare const isContentClassName: (className: unknown) => className is string;
+/** The shape the predicates need. */
+type MaybeDoc = {
+    _id?: unknown;
+    "~class"?: unknown;
+    "~domain"?: unknown;
+    active?: unknown;
+};
+/**
+ * Reports whether a document is application content rather than part of the stack.
+ *
+ * @param doc - Any stored document.
+ */
+export declare const isContentDocument: (doc: MaybeDoc | null | undefined) => boolean;
+/**
+ * Reports whether a document is an application relation.
+ *
+ * Relations carry `~domain` and no `~class` (see `isRelation` in `@docstack/shared`), so
+ * they need their own test rather than falling out of {@link isContentDocument}.
+ *
+ * @param doc - Any stored document.
+ */
+export declare const isContentRelation: (doc: MaybeDoc | null | undefined) => boolean;
+/**
+ * Strips the fields that belong to the source database rather than to the document.
+ *
+ * `_rev` above all: a revision from one database means nothing in another, and carrying
+ * it into an import turns every write into a conflict.
+ *
+ * @param doc - The document to clean.
+ * @returns A copy without the transient fields.
+ */
+export declare const stripTransientFields: <T extends object>(doc: T) => T;
+/**
+ * A stack's content, portable to another stack.
+ *
+ * **The documents are plaintext.** Encrypted attributes are decrypted on the way out so
+ * that a stack holding a different document key can read them; the file is therefore as
+ * sensitive as the data it holds, and protecting it is the caller's job.
+ */
+export interface ContentExport {
+    /** Always {@link CONTENT_EXPORT_FORMAT}. */
+    format: string;
+    /** ISO-8601, when the export was taken. */
+    exportedAt: string;
+    /** Where it came from. Advisory - an import does not require a match. */
+    source: {
+        stack: string;
+        appVersion: string;
+        schemaVersion?: string;
+    };
+    /** Class names present in {@link documents}, so an import can report gaps up front. */
+    classes: string[];
+    /** Domain names present in {@link relations}. */
+    domains: string[];
+    /** Content documents, decrypted, without `_rev`. */
+    documents: Document[];
+    /** Relation documents, ordered after the documents they connect. */
+    relations: RelationDocument[];
+}
+/** Controls what {@link ClientStack.exportContent} collects. */
+export interface ContentExportOptions {
+    /** Restrict to these class names. Defaults to every content class in the stack. */
+    classes?: string[];
+    /** Restrict to these domain names. Defaults to every content domain. */
+    domains?: string[];
+    /** Include relation documents. Defaults to `true`. */
+    includeRelations?: boolean;
+    /**
+     * Include soft-deleted documents (`active: false`). Defaults to `false` - an export
+     * is the live content, not the tombstones.
+     */
+    includeInactive?: boolean;
+    /**
+     * Export encrypted attributes as `null` instead of refusing when the stack is locked.
+     * Defaults to `false`.
+     *
+     * A locked stack cannot decrypt, so those attributes read back as `null` and an export
+     * taken that way is lossy in a way nothing downstream can detect. Refusing is the safe
+     * default; this is the escape hatch for a caller that genuinely wants the rest.
+     */
+    allowLossyWhenLocked?: boolean;
+}
+/** What an import did, per category. */
+export interface ContentImportReport {
+    documents: {
+        written: number;
+        skipped: number;
+    };
+    relations: {
+        written: number;
+        skipped: number;
+    };
+    /** Everything that did not go in cleanly, with the reason. */
+    issues: ContentImportIssue[];
+}
+/** One document that could not be imported, or that was changed on the way in. */
+export interface ContentImportIssue {
+    docId: string;
+    kind: "missing-class" | "missing-domain" | "unknown-attribute" | "conflict" | "rejected";
+    detail: string;
+}
+/** Controls how {@link ClientStack.importContent} reconciles against the datamodel. */
+export interface ContentImportOptions {
+    /**
+     * What to do with a document whose class this stack does not have.
+     * `"skip"` (default) records an issue and carries on; `"fail"` throws.
+     *
+     * Creating the class is deliberately not offered: the export carries no schema, so
+     * DocStack would have to infer one from the data and would get it wrong. Apply the
+     * patch that defines the class first.
+     */
+    onMissingClass?: "skip" | "fail";
+    /**
+     * What to do with an attribute the target class does not define.
+     * `"strip"` (default) drops it and records an issue; `"fail"` throws; `"keep"` passes
+     * it through to schema validation, which will reject it.
+     */
+    onUnknownAttribute?: "strip" | "fail" | "keep";
+    /**
+     * Replace a document that already exists. Defaults to `false`, which records a
+     * conflict and leaves the stored document alone.
+     */
+    overwrite?: boolean;
+}
+/**
+ * Validates an import payload's envelope before anything is written.
+ *
+ * A plain validator rather than an `asserts` signature: the caller already types its
+ * parameter, so there is nothing to narrow, and an assertion function reached through an
+ * import needs a declaration TypeScript can see (TS2775).
+ *
+ * @param payload - The value handed to {@link ClientStack.importContent}.
+ * @throws Error when it is not a content export this version understands.
+ */
+export declare const assertContentExport: (payload: unknown) => void;
+export {};

package/lib/core/crypto-engine/index.d.ts

@@ -30,6 +30,18 @@ export declare class CryptoEngine {
     private documentKey?;
     /** The imported CryptoKey for Web Crypto API operations. */
     private cryptoKey?;
+    /** Identifier of {@link documentKey}, stamped onto everything it encrypts. */
+    private documentKeyId?;
+    /**
+     * Keys this engine can still read but will never write with, by identifier.
+     *
+     * Re-keying a database is not instantaneous: between the moment a new key becomes the
+     * one that encrypts and the moment the last field has been rewritten, both keys are
+     * needed at once. Retiring a key rather than discarding it is what lets that interval
+     * be arbitrarily long - and therefore what lets a re-key be done in the background,
+     * interrupted, and resumed.
+     */
+    private retiredKeys;
     private readonly logger;
     /** Reference to the parent stack. */
     private readonly stack;
@@ -53,6 +65,47 @@ export declare class CryptoEngine {
      * @returns The hex-encoded document key, or undefined if not set
      */
     getDocumentKey(): string;
+    /**
+     * Returns the identifier of the key this engine currently encrypts with.
+     *
+     * Every payload it writes carries this value, so comparing it against a stored
+     * payload's `kid` says whether that field is current or still under an older key -
+     * which is what makes an incremental re-key possible.
+     *
+     * @returns The key identifier, or `undefined` when no key is held.
+     *
+     * @example
+     * ```typescript
+     * const current = stack.cryptoEngine.getKeyId();
+     * const stale = doc.ssn.kid !== current;   // needs rewriting
+     * ```
+     */
+    getKeyId(): string;
+    /**
+     * Keeps an old document key available for reading after it has stopped being used.
+     *
+     * Call this with the previous key before installing a replacement, and fields written
+     * under either will open while the database is rewritten a piece at a time. Without
+     * it, swapping the key makes every not-yet-rewritten field unreadable, which is what
+     * forces a re-key to be a single offline pass that cannot be resumed if it stops
+     * halfway.
+     *
+     * @param documentKey - The hex-encoded key to retire.
+     * @returns The retired key's identifier.
+     *
+     * @example
+     * ```typescript
+     * await stack.cryptoEngine.retireDocumentKey(oldKey);  // still readable
+     * await stack.unlock(newKey);                          // now writes under newKey
+     * ```
+     */
+    retireDocumentKey(documentKey: string): Promise<string>;
+    /**
+     * Identifiers of every key this engine can read with, current one first.
+     *
+     * @returns Key identifiers; empty when no key is held.
+     */
+    getReadableKeyIds(): string[];
     /**
      * Generates a cryptographically secure random string.
      * Useful for generating salts or nonces.
@@ -62,6 +115,25 @@ export declare class CryptoEngine {
      */
     generateRandomString(length?: number): string;
     encryptValueForMarker(value: unknown): Promise<EncryptedPayload>;
+    /**
+     * Tests whether the current document key is the one a stack was written with.
+     *
+     * AES-GCM authenticates its ciphertext, so a wrong key fails to decrypt rather than
+     * yielding plausible garbage - which makes the stored marker a reliable canary. This
+     * is deliberately separate from {@link decryptValue}, which swallows failures to keep
+     * reads non-fatal: here the failure *is* the answer.
+     *
+     * @param marker - The stored `encryptedMarker` payload.
+     * @returns `true` if the held key decrypts the marker.
+     *
+     * @example
+     * ```typescript
+     * if (!await stack.cryptoEngine.verifyMarker(config.encryptedMarker)) {
+     *     throw new Error("wrong document key");
+     * }
+     * ```
+     */
+    verifyMarker(marker: unknown): Promise<boolean>;
     /**
      * Checks if the crypto engine is enabled.
      * @returns `true` if encryption is enabled
@@ -87,6 +159,15 @@ export declare class CryptoEngine {
      */
     unwrapAndStoreDocumentKey(wrappedDocumentKey?: string | null, derivedKey?: string | null): Promise<string>;
     private getCryptoKey;
+    /**
+     * Chooses the key that can open a payload.
+     *
+     * A payload names its key, so an old field found mid-re-key is decrypted with the key
+     * it was actually written under instead of failing against the current one. Payloads
+     * from before identifiers existed name nothing, and are tried against the current key
+     * - which is what they meant when only one key could exist.
+     */
+    private resolveKeyFor;
     private encryptValue;
     private decryptValue;
     /**
@@ -118,4 +199,4 @@ export declare class CryptoEngine {
     decryptDocument(document: Document, classObj?: Class, encryptedKeys?: string[]): Promise<void>;
 }
 export type { EncryptedPayload } from "./utils.js";
-export { wrapDocumentKey, unwrapDocumentKey } from "./utils.js";
+export { wrapDocumentKey, unwrapDocumentKey, deriveKeyId, isEncryptedPayload } from "./utils.js";

package/lib/core/crypto-engine/utils.d.ts

@@ -3,13 +3,48 @@ export type EncryptedPayload = {
     iv: string;
     data: string;
     alg: "AES-GCM";
+    /**
+     * Identifies the document key this value was encrypted under.
+     *
+     * Without it a database that holds two keys is illegible: a field either opens or it
+     * does not, and nothing says which key it wanted, so re-keying has to be
+     * all-or-nothing and cannot be resumed after an interruption. With it, the fields
+     * still under an old key can be found, so re-keying becomes incremental and
+     * restartable.
+     *
+     * Optional because payloads written before it existed do not carry one. A payload
+     * without a `kid` is assumed to belong to the primary key - which is what it meant
+     * when there could only be one.
+     *
+     * @see deriveKeyId
+     */
+    kid?: string;
 };
 export declare const hexToBytes: (hex: string) => Uint8Array;
 export declare const toBase64: (data: ArrayBuffer | Uint8Array) => string;
 export declare const fromBase64: (value: string) => Uint8Array;
 export declare const importAesKeyFromHex: (hexKey: string, usages?: KeyUsage[]) => Promise<CryptoKey>;
 export declare const isEncryptedPayload: (value: unknown) => value is EncryptedPayload;
-export declare const encryptWithAesGcm: (plaintext: string, key: CryptoKey) => Promise<EncryptedPayload>;
+/**
+ * Derives the stable identifier of a document key.
+ *
+ * A truncated SHA-256 of the key's bytes: deterministic, so two devices handed the same
+ * key arrive at the same identifier without talking to each other, and one-way, so
+ * publishing it in every stored payload discloses nothing about the key itself. Eight
+ * bytes is far more than needed to tell apart the handful of keys a database sees across
+ * its re-keyings, and short enough to sit on every encrypted field without weighing it
+ * down.
+ *
+ * @param hexKey - The hex-encoded document key.
+ * @returns A 16-character hex identifier.
+ *
+ * @example
+ * ```typescript
+ * const kid = await deriveKeyId(documentKey); // e.g. "9f2c1ab30e77d541"
+ * ```
+ */
+export declare const deriveKeyId: (hexKey: string) => Promise<string>;
+export declare const encryptWithAesGcm: (plaintext: string, key: CryptoKey, kid?: string) => Promise<EncryptedPayload>;
 export declare const decryptWithAesGcm: (payload: EncryptedPayload, key: CryptoKey) => Promise<string>;
 export declare const wrapDocumentKey: (documentKey: string, derivedKeyHex: string) => Promise<string>;
 export declare const unwrapDocumentKey: (wrappedDocumentKey: string, cryptoKey: CryptoKey, derivedKeyHex: string) => Promise<string>;

package/lib/core/datamodel/index.d.ts

@@ -1,3 +1,19 @@
 import { Patch } from "@docstack/shared";
+/**
+ * Every document id the system patches seed.
+ *
+ * Derived from the patches rather than hand-listed, so it cannot drift as the datamodel
+ * grows. Load-bearing for replication: each client applies these patches for itself, so
+ * every one of these documents already exists on every client. Sending them costs quota
+ * and invites conflicts - two devices writing `Policy-Admin` independently - while
+ * telling a peer nothing it did not already know. See ADR-0023.
+ *
+ * @example
+ * ```typescript
+ * SYSTEM_SEEDED_DOC_IDS.includes("Group-Admin"); // true - patch-seeded everywhere
+ * SYSTEM_SEEDED_DOC_IDS.includes("user-alice");  // false - created by an application
+ * ```
+ */
+export declare const SYSTEM_SEEDED_DOC_IDS: readonly string[];
 export declare function getSystemPatches(currentVersion: string): Promise<Patch[]>;
 export declare function getAllSystemPatches(): Promise<Patch[]>;

package/lib/core/domain.d.ts

@@ -1,5 +1,5 @@
 import { Document, Domain as Domain_, DomainModel, Stack, DomainRelationValidation, DomainRelationParams, Class, RelationDocument } from "@docstack/shared";
-import { Logger } from "winston";
+import type { Logger } from "../utils/logger/index.js";
 /**
  * Represents a relationship definition between two Classes in the DocStack database.
  *

package/lib/core/guarded-db.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Raised when application code tries to write around a stack's authoring path.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *     await stack.db.bulkDocs({ docs: incoming, new_edits: false });
+ * } catch (error) {
+ *     error instanceof StackWriteGuardError; // true
+ * }
+ * ```
+ */
+export declare class StackWriteGuardError extends Error {
+    name: string;
+    /** The method the caller reached for. */
+    readonly method: string;
+    constructor(method: string, reason: string);
+}
+/**
+ * Wraps a PouchDB instance so the validation-skipping paths are unreachable.
+ *
+ * @param db - The stack's PouchDB instance, already carrying {@link StackPlugin}'s
+ * replaced `bulkDocs`/`bulkGet`.
+ * @returns A handle with the same surface, minus the escape hatches.
+ *
+ * @example
+ * ```typescript
+ * const guarded = createGuardedDb(rawDb);
+ * await guarded.put({ _id: "Task-1", "~class": "Task" });   // validated as usual
+ * await guarded.bulkDocs({ docs, new_edits: false });       // rejects with StackWriteGuardError
+ * ```
+ */
+export declare const createGuardedDb: <T extends {}>(db: PouchDB.Database<T>) => PouchDB.Database<T>;
+/**
+ * Restores the pristine PouchDB methods on a stack's database.
+ *
+ * Replication has to write documents verbatim (`new_edits: false`) and has to read them
+ * exactly as they are stored - {@link StackPlugin}'s `bulkGet` decrypts on read, which
+ * would push plaintext to a remote that is supposed to hold ciphertext. This handle
+ * skips the plugin on both methods while leaving every other method, and the database's
+ * own identity, untouched.
+ *
+ * @param db - The stack's PouchDB instance.
+ * @param pristine - The `bulkDocs`/`bulkGet` captured before the plugin replaced them.
+ * @returns A handle suitable for `PouchDB.replicate`/`PouchDB.sync`.
+ *
+ * @internal
+ */
+export declare const createReplicationDb: <T extends {}>(db: PouchDB.Database<T>, pristine: {
+    bulkDocs: Function;
+    bulkGet: Function;
+}) => PouchDB.Database<T>;