@tinycloud/replica 0.1.0-beta.0

package/dist/index.d.ts

@@ -0,0 +1,325 @@
+import { C as Coverage, A as AuthorityState, R as ReplicaStore, a as ReplicaTransport, G as GrantRecord, L as ListOpts, b as ReplicaStatus, c as AuthorityWindow, d as LocalReadPolicy, e as Change } from './types-BNu2RYwE.js';
+export { F as FetchedContent, f as LeaseToken, g as LocalEntry, h as ReplicaConfig, i as ReplicaLastError, j as ReplicaState, S as SyncPage, k as SyncSource, V as VerifiedChange, l as VerifiedPage } from './types-BNu2RYwE.js';
+
+/** Metadata every local read carries: the replica reports observed state, never finality. */
+type ReadMeta = {
+    consistency: "observed";
+    source: {
+        host: string;
+        nodeDid: string | null;
+        space: string;
+        prefix: string;
+    };
+    asOf: string | null;
+    coverage: Coverage;
+    /** `expired` while reads continue under a node-attested retention. */
+    authority: AuthorityState;
+};
+type ReplicaReadResult = {
+    status: "present";
+    key: string;
+    value: Uint8Array;
+    etag: string;
+    metadata: Record<string, string>;
+    meta: ReadMeta;
+} | {
+    status: "content_missing";
+    key: string;
+    etag: string;
+    metadata: Record<string, string>;
+    meta: ReadMeta;
+} | {
+    status: "deleted" | "absent";
+    key: string;
+    meta: ReadMeta;
+} | {
+    status: "coverage_incomplete" | "not_covered";
+    key: string;
+    meta: ReadMeta;
+};
+type ReplicaListEntry = {
+    key: string;
+    etag: string;
+    metadata: Record<string, string>;
+    content: boolean;
+};
+type ReplicaListResult = {
+    entries: ReplicaListEntry[];
+    meta: ReadMeta;
+};
+type SyncReport = {
+    pages: number;
+    changes: number;
+    deleted: number;
+    fetched: number;
+    contentMissing: number;
+    repaired: number;
+    resets: number;
+    coverage: Coverage;
+    cursorAdvanced: boolean;
+    promotedGrant: boolean;
+    blobsCollected: number;
+};
+type ReplicaOptions = {
+    store: ReplicaStore;
+    /** One transport for whichever grant the replica syncs under (tests, single-grant hosts). */
+    transport?: ReplicaTransport;
+    /**
+     * A transport that invokes with exactly `grant`. Lets the engine try a
+     * pending grant and fall back to the active one if the node refuses it.
+     */
+    transportFor?: (grant: GrantRecord) => ReplicaTransport;
+    now?: () => number;
+    leaseTtlMs?: number;
+};
+/** `"blake3-" + hex(blake3(bytes))`, the strong ETag the node attests for content. */
+declare function contentHash(bytes: Uint8Array): string;
+/**
+ * A durable, read-only local replica of one KV prefix. Reads never touch the
+ * network; `sync` pulls `tinycloud.kv/sync` pages, verifies every byte
+ * against the node-attested ETag, and commits each page with its cursor.
+ */
+declare class Replica {
+    #private;
+    constructor(options: ReplicaOptions);
+    get(key: string, options?: {
+        verify?: boolean;
+    }): Promise<ReplicaReadResult>;
+    /** Live keys under `prefix` (a plain string prefix within the replica's scope). */
+    list(options?: ListOpts): Promise<ReplicaListResult>;
+    status(): Promise<ReplicaStatus>;
+    /** Clear entries, blobs, cursor and the source pin; keep the configuration and grant. */
+    reset(reason: string): Promise<void>;
+    /**
+     * Sync under the pending grant if there is one, else the active grant. If
+     * the node refuses a pending grant before anything committed under it, the
+     * active grant serves: a revoked pending grant is discarded, any other
+     * refusal is recorded on it. A revocation of the grant serving the replica,
+     * learned anywhere in the sync, purges the replica before this returns.
+     */
+    sync(options?: {
+        limit?: number;
+        signal?: AbortSignal;
+    }): Promise<SyncReport>;
+}
+
+/**
+ * Typed replica errors. Every failure a caller can act on has its own code;
+ * hosts (CLI, worker) map codes to their own exit codes or UI states.
+ */
+declare const ReplicaErrorCode: {
+    /** Another process holds the sync lease. */
+    readonly BUSY: "REPLICA_BUSY";
+    /** No replica with this name exists. */
+    readonly NOT_FOUND: "REPLICA_NOT_FOUND";
+    /** The replica exists but its stored configuration differs from the request. */
+    readonly CONFIG_MISMATCH: "REPLICA_CONFIG_MISMATCH";
+    /** The runtime has no supported durable store (e.g. Node < 22.13). */
+    readonly RUNTIME_UNSUPPORTED: "RUNTIME_UNSUPPORTED";
+    /** The local store failed (I/O, corruption, schema). */
+    readonly STORAGE_ERROR: "STORAGE_ERROR";
+    /** The local disk is full. */
+    readonly STORAGE_FULL: "STORAGE_FULL";
+    /** The key is outside the replica's prefix. */
+    readonly NOT_COVERED: "NOT_COVERED";
+    /** Syncing the secrets space or the vault namespace needs an explicit opt-in. */
+    readonly SECRETS_OPT_IN_REQUIRED: "SECRETS_OPT_IN_REQUIRED";
+    /** No grant is installed, or none covers the requested scope. */
+    readonly GRANT_MISSING: "GRANT_MISSING";
+    /** The grant bytes are not a verifiable UCAN, or its signature is wrong. */
+    readonly GRANT_INVALID: "GRANT_INVALID";
+    /** SIWE/CACAO and other non-UCAN grants cannot be used for a replica. */
+    readonly GRANT_FORMAT_UNSUPPORTED: "GRANT_FORMAT_UNSUPPORTED";
+    /** The grant was issued to a different device. */
+    readonly GRANT_AUDIENCE_MISMATCH: "GRANT_AUDIENCE_MISMATCH";
+    /** The grant lacks `tinycloud.kv/sync` or `tinycloud.kv/get` on the prefix. */
+    readonly GRANT_NOT_COVERING: "GRANT_NOT_COVERING";
+    readonly GRANT_NOT_YET_VALID: "GRANT_NOT_YET_VALID";
+    readonly GRANT_EXPIRED: "GRANT_EXPIRED";
+    readonly GRANT_REVOKED: "GRANT_REVOKED";
+    /** The node refused the invocation for a reason other than revocation. */
+    readonly GRANT_UNAUTHORIZED: "GRANT_UNAUTHORIZED";
+    /** The node refused the retention grant. */
+    readonly RETENTION_GRANT_REFUSED: "RETENTION_GRANT_REFUSED";
+    /** The node could not be reached. */
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    /** The node answered with an unexpected status. */
+    readonly NODE_ERROR: "NODE_ERROR";
+    /** The node's answer violates the wire contract. */
+    readonly PROTOCOL_ERROR: "PROTOCOL_ERROR";
+    /** The node asked for a fresh bootstrap (410). Handled inside sync. */
+    readonly RESET_REQUIRED: "RESET_REQUIRED";
+    /** The feed now comes from a different node than the one pinned. */
+    readonly SOURCE_CHANGED: "SOURCE_CHANGED";
+    /** The feed delivered a key outside the replica's prefix. */
+    readonly SCOPE_VIOLATION: "SCOPE_VIOLATION";
+    /** Fetched bytes do not hash to the ETag the node attested for them. */
+    readonly CONTENT_MISMATCH: "CONTENT_MISMATCH";
+    /** A stored blob no longer hashes to its name. */
+    readonly INTEGRITY_ERROR: "INTEGRITY_ERROR";
+};
+type ReplicaErrorCode = (typeof ReplicaErrorCode)[keyof typeof ReplicaErrorCode];
+/**
+ * The package ships separate entry bundles (`.`, `./sqlite`), each with its own
+ * copy of this class, so identity is a registered symbol, not `instanceof`.
+ */
+declare const REPLICA_ERROR: unique symbol;
+declare class ReplicaError extends Error {
+    readonly [REPLICA_ERROR] = true;
+    readonly code: ReplicaErrorCode;
+    readonly detail?: Record<string, unknown>;
+    constructor(code: ReplicaErrorCode, message: string, detail?: Record<string, unknown>, options?: {
+        cause?: unknown;
+    });
+}
+declare function isReplicaError(error: unknown, code?: ReplicaErrorCode): error is ReplicaError;
+
+/** A compact UCAN grant whose Ed25519 signature checked out against its issuer. */
+type ParsedUcanGrant = GrantRecord & {
+    /** The signed attenuation: resource → ability → caveats. */
+    att: Record<string, Record<string, unknown>>;
+    /** Signed proof CIDs. */
+    prf: string[];
+    /** The compact JWT, without any `Bearer ` prefix. */
+    jwt: string;
+};
+/**
+ * The canonical TinyCloud delegation CID of a compact UCAN: CIDv1, raw codec
+ * (0x55), blake3-256 multihash over the JWT's UTF-8 bytes, base32 multibase.
+ * Matches `computeCid(bytes, 0x55)` in the SDK's WASM bindings.
+ */
+declare function ucanCid(jwt: string): string;
+/**
+ * Parse and verify a compact UCAN grant. Worker-safe (no Node APIs).
+ * Everything returned — audience, window, attenuation, proofs — comes from
+ * the signed payload, never from wrapper fields around it. Verifying the
+ * signature proves the issuer signed exactly these claims; whether the chain
+ * holds is the node's call on every sync.
+ */
+declare function parseUcanGrant(input: Uint8Array | string): ParsedUcanGrant;
+/** True when the signed attenuation grants `ability` on a KV path covering `prefix`. */
+declare function grantCovers(grant: Pick<ParsedUcanGrant, "att">, space: string, prefix: string, ability: string): boolean;
+/** The space ids (native form) for which the grant carries `tinycloud.kv/sync`. */
+declare function syncGrantSpaces(grant: Pick<ParsedUcanGrant, "att">): string[];
+/**
+ * Install-time checks: the grant must name this device, cover both
+ * `tinycloud.kv/sync` and `tinycloud.kv/get` on the prefix, and be inside its
+ * own signed window. The node re-checks the whole chain on every sync.
+ */
+declare function assertGrantInstallable(grant: ParsedUcanGrant, input: {
+    deviceDid: string;
+    space: string;
+    prefix: string;
+    now: number;
+}): void;
+
+/**
+ * The node's `kv_prefix_covers`: whole path segments, byte-exact. `notes/`
+ * covers everything under `notes/` but not `notes`; `notes` covers `notes`
+ * and `notes/…` but not `notes-secret/x`.
+ */
+declare function kvPrefixCovers(prefix: string, key: string): boolean;
+/**
+ * Syncing the owner's secrets space, or any prefix overlapping the vault
+ * namespace (including bare `vault`), copies encrypted secret material to
+ * disk and needs an explicit opt-in (TC-733).
+ */
+declare function requiresSecretsOptIn(space: string, prefix: string): boolean;
+/** `"blake3-<hex>"` (quoted or not) → the 64-hex hash, or undefined. */
+declare function hashFromEtag(etag: string): string | undefined;
+type EffectiveAuthority = {
+    state: AuthorityState;
+    notBefore: string | null;
+    expiresAt: string | null;
+    retainUntil: string | null;
+    /** The retention grant was revoked: after expiry, reads are revoked rather than expired. */
+    retentionRevoked: boolean;
+};
+/**
+ * The window local reads are enforced against: the node-attested window from
+ * the last successful sync, bounded by the installed leaf grant (an upper
+ * bound only — a multi-parent ancestor can end the chain earlier, which only
+ * the node can see).
+ */
+declare function effectiveAuthority(input: {
+    window: AuthorityWindow | null;
+    grant: GrantRecord | null;
+    revoked: string | null;
+    retentionRevoked?: string | null;
+    policy: LocalReadPolicy;
+    now: number;
+}): EffectiveAuthority;
+/**
+ * Throws unless local reads are allowed now. Returns the reported authority
+ * state: `valid`, or `expired` while a node-attested retention holds.
+ */
+declare function assertReadable(authority: EffectiveAuthority, now: number): AuthorityState;
+
+/** The sdk-services `ServiceError` fields the transport reads. */
+type ServiceError = {
+    code: string;
+    message: string;
+    meta?: Record<string, unknown>;
+};
+type Result<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: ServiceError;
+};
+type KVChangesResponse = {
+    changes: Change[];
+    more: boolean;
+    cursor: string;
+    source: {
+        nodeDid: string;
+        space: string;
+        prefix: string;
+    };
+    authority: AuthorityWindow;
+};
+type KVValue = {
+    data: unknown;
+    headers: {
+        etag?: string;
+    };
+};
+/**
+ * The slice of sdk-services `KVService` a replica needs: the `tinycloud.kv/sync`
+ * feed (`changes`, TC-736) and binary reads. Typed structurally so this
+ * package never imports an SDK entry point (web-sdk defines custom elements
+ * on load; node-sdk pulls in Node-only code).
+ */
+interface KVSyncClient {
+    changes(options: {
+        prefix: string;
+        cursor?: string;
+        limit?: number;
+        retentionGrant?: string;
+        signal?: AbortSignal;
+    }): Promise<Result<KVChangesResponse>>;
+    get(key: string, options: {
+        binary: true;
+        signal?: AbortSignal;
+    }): Promise<Result<KVValue>>;
+    batchGet(keys: string[], options: {
+        binary: true;
+        signal?: AbortSignal;
+    }): Promise<Result<{
+        results: Array<{
+            key: string;
+            result: Result<KVValue>;
+        }>;
+    }>>;
+}
+/**
+ * Map an SDK failure to the replica's typed errors. `request` is the SDK's
+ * own description of the call (`Failed to get key "k"`), which lets a read's
+ * 401 body be told apart from the key it names.
+ */
+declare function replicaErrorFromService(error: ServiceError, context: string, request?: string): ReplicaError;
+/** A `ReplicaTransport` over a KV service bound to the replica's space and grant. */
+declare function kvSyncTransport(kv: KVSyncClient): ReplicaTransport;
+
+export { AuthorityState, AuthorityWindow, Change, Coverage, type EffectiveAuthority, GrantRecord, type KVSyncClient, ListOpts, LocalReadPolicy, type ParsedUcanGrant, type ReadMeta, Replica, ReplicaError, ReplicaErrorCode, type ReplicaListEntry, type ReplicaListResult, type ReplicaOptions, type ReplicaReadResult, ReplicaStatus, ReplicaStore, ReplicaTransport, type SyncReport, assertGrantInstallable, assertReadable, contentHash, effectiveAuthority, grantCovers, hashFromEtag, isReplicaError, kvPrefixCovers, kvSyncTransport, parseUcanGrant, replicaErrorFromService, requiresSecretsOptIn, syncGrantSpaces, ucanCid };