@noy-db/hub 0.3.0-pre.1 → 0.3.0-pre.11

package/dist/with-pod/pod-store.d.ts

@@ -0,0 +1,54 @@
+import type { NoydbStore, NoydbPodStore } from '../kernel/types.js';
+export interface WrapPodStoreOptions {
+    /**
+     * When `true` (default), every `put()` and `delete()` flushes the full
+     * vault snapshot to the bundle backend. Set to `false` for bulk operations
+     * and call `store.flush(vaultId)` manually.
+     */
+    autoFlush?: boolean;
+}
+export interface WrappedPodNoydbStore extends NoydbStore {
+    /** Manually flush the in-memory snapshot to the bundle backend. */
+    flush(vaultId: string): Promise<void>;
+    /**
+     * Run a batch of mutations without flushing until the callback completes.
+     * A single flush is performed at the end.
+     */
+    batch(vaultId: string, fn: () => Promise<void>): Promise<void>;
+}
+/**
+ * Convert a `NoydbPodStore` (blob-oriented read/write with OCC) into the
+ * standard six-method `NoydbStore` interface expected by `createNoydb({ store })`.
+ *
+ * Bundle stores operate on the entire vault as a single serialised unit —
+ * ideal for backends like Google Drive, WebDAV, or iCloud Drive that work
+ * best with whole-file I/O rather than per-record KV operations.
+ *
+ * ## Optimistic concurrency
+ *
+ * The wrapper tracks the `version` token from the last `readBundle` and
+ * passes it as `expectedVersion` on every flush. On
+ * `PodVersionConflictError`, it re-reads, merges the remote snapshot
+ * (last-write-wins per record key), and retries (max 3 attempts).
+ *
+ * ## Flush modes
+ *
+ * By default, flushes on every mutation (O(vault size) per write). Options:
+ * - `autoFlush: false` + explicit `store.flush(vaultId)` calls
+ * - `store.batch(vaultId, async () => { ... })` — defers flush until end
+ * - Pair with `syncPolicy: { push: { mode: 'debounce' } }` from
+ */
+export declare function wrapPodStore(bundle: NoydbPodStore, options?: WrapPodStoreOptions): WrappedPodNoydbStore;
+/**
+ * Type-safe factory helper for `NoydbPodStore` implementations,
+ * analogous to `createStore` for KV stores.
+ */
+export declare function createPodStore<TOptions>(factory: (options: TOptions) => NoydbPodStore): (options: TOptions) => NoydbPodStore;
+/** @deprecated Use wrapPodStore. */
+export declare const wrapBundleStore: typeof wrapPodStore;
+/** @deprecated Use createPodStore. */
+export declare const createBundleStore: typeof createPodStore;
+/** @deprecated Use WrappedPodNoydbStore. */
+export type WrappedBundleNoydbStore = WrappedPodNoydbStore;
+/** @deprecated Use WrapPodStoreOptions. */
+export type WrapBundleStoreOptions = WrapPodStoreOptions;

package/dist/with-pod/ulid.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Minimal ULID generator — zero dependencies, Web Crypto API only.
+ *
+ *. Used by the bundle writer to generate stable opaque
+ * handles for `.noydb` containers.
+ *
+ * **What's a ULID?** A 128-bit identifier encoded as 26 Crockford
+ * base32 characters. Layout:
+ *
+ * ```
+ *   01HYABCDEFGHJKMNPQRSTVWXYZ
+ *   |--------||---------------|
+ *    48-bit     80-bit
+ *    timestamp  randomness
+ * ```
+ *
+ * The first 10 chars encode a millisecond Unix timestamp (so ULIDs
+ * sort lexicographically by creation time), and the remaining 16
+ * chars are random. Crockford base32 omits I/L/O/U to avoid
+ * ambiguity in handwriting and URLs.
+ *
+ * **Why hand-roll instead of pulling in `ulid`?** The package adds
+ * a dep, the implementation is ~30 lines, and the bundle module
+ * is the only consumer. Adding `ulid` would also drag in its own
+ * crypto polyfill that we don't need on Node 18+ or modern
+ * browsers.
+ *
+ * **Privacy consideration:** the timestamp prefix is observable in
+ * the bundle header. This is a deliberate trade-off:
+ *   - Pro: lexicographic sortability lets bundle adapters list
+ *     newest-first without an extra index.
+ *   - Con: a casual observer can read the bundle's creation time
+ *     from the handle. They cannot read it from any OTHER field
+ *     (the header explicitly forbids `_exported_at`), and a
+ *     creation timestamp is the same kind of metadata that
+ *     filesystem mtime would already expose for a downloaded
+ *     bundle. The leak is therefore equivalent to what's already
+ *     visible from the file's mtime — not a new exposure.
+ *
+ * If a future use case needs timestamp-free handles, a v2 of the
+ * format could specify "use the random portion only" without a
+ * format break — `validateBundleHeader` only checks the regex
+ * shape, not the encoded timestamp.
+ */
+/**
+ * Generate a fresh ULID. Uses `crypto.getRandomValues` for the
+ * randomness portion — same Web Crypto API the rest of the
+ * codebase uses for IVs and salt.
+ *
+ * Returns a 26-character string. Calling twice in the same
+ * millisecond produces two distinct ULIDs (the random portion
+ * differs); ULIDs from the same millisecond are NOT guaranteed
+ * to be monotonically ordered relative to each other, only
+ * relative to ULIDs from a different millisecond. The bundle
+ * format never relies on intra-millisecond ordering.
+ */
+export declare function generateULID(): string;
+/**
+ * Validate that a string is a syntactically well-formed ULID. Used
+ * by the bundle header validator. Does NOT verify that the
+ * timestamp portion decodes to a sensible date — the format only
+ * cares about the encoding shape.
+ */
+export declare function isULID(value: string): boolean;

package/dist/with-shape/blobs/blob-compaction.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Blob retention + compaction.
+ *
+ * Declarative per-collection / per-slot eviction policy. Two
+ * triggers:
+ *
+ *   - **`retainDays`** — age-based TTL. A slot uploaded more than N
+ *     days ago is evicted.
+ *   - **`evictWhen(record)`** — predicate over the **decrypted**
+ *     record. Lets consumers express "the image is safe to drop once
+ *     the structured invoice has been reviewed and confirmed."
+ *
+ * Either trigger (or both) causes the slot to evict. Eviction removes
+ * the slot entry from `_blob_slots_{collection}`, decrements the
+ * blob's refCount (so unreferenced chunks can be GC'd by the next
+ * sweep), and writes one entry to the `_blob_eviction_audit`
+ * collection for tamper-evident record-keeping.
+ *
+ * The audit entry carries the eTag of the evicted blob (opaque HMAC
+ * of plaintext under the vault's `_blob` DEK) — no plaintext leakage,
+ * per the SPEC non-correlation invariant. Consumers reconstructing
+ * "what used to be attached" can look up the audit entry by record
+ * id.
+ *
+ * Compaction is **consumer-scheduled** — noy-db never runs a
+ * background daemon. Call `vault.compact()` whenever your workflow
+ * allows (cron, manual "tidy" button, cold-storage export prep, …).
+ *
+ * @module
+ */
+import type { NoydbStore, SlotInfo } from '../../kernel/types.js';
+import { type EnclaveKey } from '../../kernel/enclave/index.js';
+export interface BlobFieldPolicy<T = unknown> {
+    /**
+     * Via port brand marker — lets a `BlobFieldPolicy` satisfy the kernel's
+     * opaque `ViaDescriptor` (#629 Task 7). Optional (the
+     * `ClassifiedFieldSpec._viaBrand` precedent): `blobFields` policies are
+     * plain object literals with no declaration factory to stamp it, so a
+     * mandatory field would break every existing declaration.
+     */
+    readonly _viaBrand?: 'blob';
+    /**
+     * Age-based TTL in days. A slot whose `uploadedAt` is older than
+     * `now - retainDays × 86400s` evicts on the next `vault.compact()`.
+     * Omit to disable age-based eviction.
+     */
+    readonly retainDays?: number;
+    /**
+     * Predicate evaluated against the decrypted record. When it returns
+     * `true`, every matching slot on that record evicts. Omit to
+     * disable predicate-based eviction.
+     */
+    readonly evictWhen?: (record: T) => boolean;
+    /**
+     * **Legal hold.** When this predicate returns `true`, the slot is
+     * never evicted — `retainDays`/`evictWhen` are overridden. Use for a
+     * litigation / audit hold on a fiscal document: the blob stays until
+     * the predicate returns `false` (the hold is released). Fail-closed:
+     * if the predicate throws, the slot is treated as held.
+     */
+    readonly legalHold?: (record: T) => boolean;
+    /**
+     * **Period-bound retention.** Returns the date (Date / ISO string /
+     * epoch ms) until which the slot must be retained — typically derived
+     * from the record's fiscal period (e.g. period end + 10 years). While
+     * `now < retainUntil`, the slot is never evicted, regardless of
+     * `retainDays`. Return `null`/`undefined` to impose no floor.
+     * Fail-closed: a throwing function holds the slot.
+     */
+    readonly retainUntil?: (record: T) => Date | string | number | null | undefined;
+    /**
+     * **External projection.** When `true`, this field's bytes are stored in the
+     * vault's `ObjectProjection` (`createNoydb({ objectStore })`) as a single raw,
+     * **unencrypted** object — servable directly from S3/CDN and processable by
+     * native tooling — instead of the encrypted-chunk path. The encrypted slot
+     * record remains the catalog (anchoring invariant). Requires an `objectStore`;
+     * **outside the zero-knowledge guarantee** — use only for assets meant to
+     * leave the vault. See the as-aws-s3 design spec.
+     */
+    readonly external?: boolean;
+    /**
+     * For an `external` field: make the object world-readable (CDN origin) rather
+     * than presigned-only. Default `false` (presigned). Ignored unless `external`.
+     */
+    readonly public?: boolean;
+    /**
+     * For an `external` field: how to stamp a **backlink** (this record's
+     * vault/collection/id/field) onto the object's metadata — the self-describing
+     * "secondary store" that powers reconcile / DR / import re-pairing.
+     * - `'opaque-token'` (default): a random id; preserves the opaque-bucket
+     *   property (no names leak); the token is also recorded on the slot.
+     * - `'encrypted'`: the reference encrypted under the blob DEK (ZK-preserving;
+     *   falls back to `'opaque-token'` on a plaintext vault).
+     * - `'plain'`: the reference in cleartext metadata — **leaks structure** to
+     *   bucket readers; only for non-sensitive deployments.
+     * - `'none'`: no backlink.
+     */
+    readonly backlink?: 'opaque-token' | 'encrypted' | 'plain' | 'none';
+}
+export type BlobFieldsConfig<T = unknown> = Record<string, BlobFieldPolicy<T>>;
+export declare const BLOB_EVICTION_AUDIT_COLLECTION = "_blob_eviction_audit";
+export interface BlobEvictionEntry {
+    readonly id: string;
+    readonly collection: string;
+    readonly recordId: string;
+    readonly slotName: string;
+    readonly blobHash: string;
+    readonly reason: 'ttl' | 'predicate' | 'both';
+    readonly evictedAt: string;
+    readonly actor: string;
+}
+export interface CompactionResult {
+    /** Number of blob slots evicted across all collections. */
+    readonly evicted: number;
+    /** Number of records touched (iterated + policy checked). */
+    readonly records: number;
+    /** Number of collections with `blobFields` configured. */
+    readonly collections: number;
+    /** Number of audit entries written. Equal to `evicted`. */
+    readonly auditEntries: number;
+    /**
+     * Number of slots that would have evicted (TTL/predicate triggered)
+     * but were retained by a `legalHold` or `retainUntil` floor.
+     */
+    readonly held: number;
+    /** Per-collection breakdown for diagnostics. */
+    readonly byCollection: Record<string, {
+        records: number;
+        evicted: number;
+    }>;
+}
+export interface CompactRunOptions {
+    /** Override "now" for deterministic testing. */
+    readonly now?: Date;
+    /**
+     * Stop after this many evictions. Useful for capped batches / cron
+     * jobs that need to fit in a time window. `undefined` = unbounded.
+     */
+    readonly maxEvictions?: number;
+    /**
+     * Dry-run — evaluate policies and return the counts, but do NOT
+     * delete slots or write audit entries. Lets a consumer preview
+     * what would happen.
+     */
+    readonly dryRun?: boolean;
+}
+export interface CompactionContext {
+    readonly adapter: NoydbStore;
+    readonly vault: string;
+    readonly actor: string;
+    readonly encrypted: boolean;
+    readonly getDEK: (collection: string) => Promise<EnclaveKey>;
+    /**
+     * Resolve a collection's declared `blobFields` config. Returns an
+     * empty map for collections without the config — the walk skips
+     * those.
+     */
+    readonly getBlobFields: <T>(collection: string) => BlobFieldsConfig<T> | null;
+    /** List collection names in the vault. */
+    readonly listCollections: () => Promise<string[]>;
+    /** List record ids in a collection. */
+    readonly listRecords: (collection: string) => Promise<string[]>;
+    /** Decrypt and return the record. Null when absent. */
+    readonly getRecord: <T>(collection: string, id: string) => Promise<T | null>;
+    /** Return the BlobSet-like handle for a record's slots. */
+    readonly listSlots: (collection: string, id: string) => Promise<SlotInfo[]>;
+    /** Delete a slot and decrement its blob's refCount. */
+    readonly deleteSlot: (collection: string, id: string, slotName: string) => Promise<void>;
+}
+export declare function runCompaction(ctx: CompactionContext, options?: CompactRunOptions): Promise<CompactionResult>;

package/dist/with-shape/blobs/blob-set.d.ts

@@ -0,0 +1,342 @@
+import type { NoydbStore, BlobObject, SlotInfo, VersionRecord, BlobPutOptions, BlobResponseOptions } from '../../kernel/types.js';
+import type { ObjectProjection } from './object-projection.js';
+import type { BlobFieldsConfig } from './blob-compaction.js';
+import { type EnclaveKey } from '../../kernel/enclave/index.js';
+/**
+ * DEK slot name for vault-shared blob data. Calling `getDEK('_blob')`
+ * auto-creates a blob DEK the first time — same lazy-creation mechanism
+ * used for any user-defined collection.
+ */
+export declare const BLOB_COLLECTION = "_blob";
+/** Stores `BlobObject` metadata envelopes, keyed by eTag. */
+export declare const BLOB_INDEX_COLLECTION = "_blob_index";
+/**
+ * Stores encrypted chunk envelopes, keyed by `{eTag}/{chunkIndex}`.
+ * NOT loaded into the in-memory query layer. Fetched on demand by
+ * `BlobSet.get()` / `BlobSet.response()`.
+ */
+export declare const BLOB_CHUNKS_COLLECTION = "_blob_chunks";
+/** Prefix for per-collection slot metadata collections. */
+export declare const BLOB_SLOTS_PREFIX = "_blob_slots_";
+/** Prefix for per-collection version records. */
+export declare const BLOB_VERSIONS_PREFIX = "_blob_versions_";
+/**
+ * Default chunk size: 256 KB raw bytes.
+ * After AES-GCM (same size) + base64 (~33% inflation) → ~342 KB per
+ * envelope, safely within DynamoDB's 400 KB item limit.
+ */
+export declare const DEFAULT_CHUNK_SIZE: number;
+/**
+ * Handle for reading, writing, versioning, and deleting binary blobs
+ * on a specific record.
+ *
+ * Obtained via `collection.blob(id)`. No I/O is performed until you
+ * call a method.
+ *
+ * ## Storage layout
+ *
+ * ```
+ * _blob_index/{eTag}                            BlobObject metadata (vault-shared DEK)
+ * _blob_chunks/{eTag}/{chunkIndex}              Encrypted chunk data (vault-shared DEK + AAD)
+ * _blob_slots_{collection}/{recordId}           Slot map (parent collection DEK)
+ * _blob_versions_{collection}/{recordId}/{slot}/{label}  Published versions (parent collection DEK)
+ * ```
+ *
+ * ## Deduplication
+ *
+ * `put()` computes `eTag = HMAC-SHA-256(blobDEK, plaintext)` — keyed so the
+ * store cannot predict eTags for known content. If another record already
+ * uploaded the same bytes, the chunks are reused and `refCount` is incremented.
+ *
+ * ## Chunk integrity
+ *
+ * Each chunk is encrypted with AES-256-GCM using AAD = `{eTag}:{index}:{count}`,
+ * preventing chunk reorder, substitution, and truncation attacks.
+ */
+export declare class BlobSet {
+    private readonly store;
+    private readonly vault;
+    private readonly collection;
+    private readonly recordId;
+    private readonly getDEK;
+    private readonly encrypted;
+    private readonly userId;
+    private readonly maxBlobBytes;
+    private readonly erasableBlobs;
+    private readonly debugPlaintext;
+    private readonly objectStore;
+    private readonly blobFields;
+    constructor(opts: {
+        store: NoydbStore;
+        vault: string;
+        collection: string;
+        recordId: string;
+        getDEK: (name: string) => Promise<EnclaveKey>;
+        encrypted: boolean;
+        userId?: string;
+        maxBlobBytes?: number;
+        erasableBlobs?: boolean;
+        debugPlaintext?: boolean;
+        objectStore?: ObjectProjection;
+        blobFields?: BlobFieldsConfig;
+    });
+    /**
+     * Resolve the key the blob's CHUNKS are encrypted under.
+     *
+     * - `_cek` present (erasable blob) → unwrap the per-blob content CEK under
+     *   the `_blob` DEK. Deleting the BlobObject (at `refCount → 0`) makes this
+     *   key unrecoverable → the chunks are crypto-shredded.
+     * - `_cek` absent (legacy) → the `_blob` DEK encrypts chunks directly.
+     * - unencrypted vault → `null` (chunks stored as plaintext base64).
+     */
+    private resolveChunkKey;
+    /** The internal collection that holds slot metadata for this collection's blobs. */
+    private get slotsCollection();
+    /** The internal collection that holds published versions for this collection's blobs. */
+    private get versionsCollection();
+    private loadSlots;
+    private saveSlots;
+    /**
+     * CAS retry loop for slot metadata updates. Re-reads slots on conflict
+     * and re-applies the mutation function.
+     */
+    private casUpdateSlots;
+    private loadBlobObject;
+    private writeBlobObject;
+    /**
+     * CAS retry loop for refCount changes on a BlobObject.
+     */
+    private casUpdateRefCount;
+    /**
+     * Release `n` references to a blob and reclaim it at refCount 0.
+     *
+     * The single reclaim choke point for every reference-drop path — slot
+     * delete/overwrite, published-version delete, and `forget()` shred — so the
+     * refCount-0 policy is uniform:
+     *  - **erasable blob** (`_cek` present) → delete the `BlobObject` (the SOLE
+     *    copy of the wrapped content CEK → chunks permanently undecryptable) and
+     *    reclaim the chunks. The crypto-shred is EAGER on every path: GDPR erasure
+     *    must not wait on orphan retention.
+     *  - **legacy blob** (no `_cek`) → reclaimed only when `reclaimLegacy` (the
+     *    `forget()` erasure path); otherwise left for deferred GC so the existing
+     *    `BlobLifecyclePolicy.orphanRetentionDays` semantics are preserved.
+     *
+     * @returns `'shredded'` (erasable, refCount 0, chunks dead) · `'retainedShared'`
+     *   (erasable, still referenced) · `'residue'` (legacy — not a crypto-shred).
+     */
+    private releaseRef;
+    /**
+     * Crypto-shred this record's blob attachments — called by
+     * `vault.forget()`.
+     *
+     * For each distinct eTag the record references (a record may attach the same
+     * content under several slot names → several refCount holds): decrement the
+     * blob's refCount by that many. When it reaches 0:
+     *  - **erasable blob** (`_cek` present) → delete the `BlobObject` (the SOLE
+     *    recoverable copy of the wrapped content CEK → chunks permanently
+     *    undecryptable) and reclaim the chunk bytes. This is the crypto-shred.
+     *  - **legacy blob** (no `_cek`) → chunks are under the shared `_blob` DEK and
+     *    stay decryptable until byte-deleted; we delete the orphaned chunks +
+     *    index but report it as residue, not a cryptographic erasure.
+     * When refCount stays > 0 the content legitimately persists for its other
+     * owner — reported as `retainedShared` (or `residue` if legacy).
+     *
+     * Finally drops the record's slot map, severing the subject's link.
+     */
+    shredAllForRecord(): Promise<{
+        shredded: string[];
+        retainedShared: string[];
+        residue: string[];
+    }>;
+    /** CAS retry loop for an arbitrary BlobObject mutation. */
+    private casUpdateBlobObject;
+    /**
+     * Migrate this record's LEGACY blobs (no `_cek`, chunks under the shared
+     * `_blob` DEK) to per-blob content CEKs so they become crypto-shreddable.
+     * Returns the eTags migrated vs. already-erasable.
+     *
+     * **Explicit maintenance pass** (mirrors the record-CEK migration posture):
+     * re-encrypts the existing compressed chunks IN PLACE under a fresh content
+     * CEK — preserving the eTag, chunkCount, chunkSize, and compression — then
+     * flips the `_cek` discriminant. Crash-safe + idempotent via `_cekPending`:
+     *   1. persist the wrapped content CEK in `_cekPending` (readers ignore it →
+     *      the blob stays readable under the `_blob` DEK; the key survives a crash);
+     *   2. re-encrypt each chunk under the content CEK (a resume reads an
+     *      already-migrated chunk under the content CEK, else under the `_blob` DEK);
+     *   3. promote `_cekPending` → `_cek` (atomic flip). Reads now use the CEK.
+     * A re-run after a crash resumes from whichever phase was reached.
+     *
+     * Dedup-safe: migrating a shared blob (refCount > 1) re-keys it for every
+     * referencer at once; a non-erasable collection still reads it (it unwraps
+     * `_cek` under the `_blob` DEK it holds).
+     */
+    migrate(): Promise<{
+        migrated: string[];
+        alreadyErasable: string[];
+    }>;
+    private writeChunk;
+    private readChunk;
+    private versionKey;
+    private loadVersionRecord;
+    private writeVersionRecord;
+    private deleteVersionRecord;
+    private effectiveChunkSize;
+    private fetchAllChunks;
+    /**
+     * Upload bytes and attach them to this record under `slotName`.
+     *
+     * 1. Computes `eTag = HMAC-SHA-256(blobDEK, plaintext)` for keyed content-addressing.
+     * 2. Auto-detects MIME type from magic bytes if not provided.
+     * 3. If a blob with this eTag already exists, skips chunk upload (deduplication)
+     *    and CAS-increments refCount.
+     * 4. Otherwise: compresses → splits into chunks → encrypts each chunk with
+     *    AAD binding → writes `_blob_chunks` → writes `BlobObject` to `_blob_index`.
+     * 5. CAS-updates the slot metadata in `_blob_slots_{collection}`.
+     *    If overwriting an existing slot, decrements the old eTag's refCount.
+     */
+    put(slotName: string, data: Uint8Array, opts?: BlobPutOptions): Promise<void>;
+    private _deferredRefDecrement;
+    /**
+     * Fetch all bytes for the named slot.
+     * Returns `null` if the slot does not exist.
+     * Throws `NotFoundError` if the index entry exists but a chunk is missing.
+     */
+    get(slotName: string): Promise<Uint8Array | null>;
+    /**
+     * A URL to fetch an `external` slot's object directly — presigned
+     * (time-limited) or public, per the projection. Returns `null` if the slot
+     * does not exist. Throws for a non-external slot (use `get()`/`response()`).
+     */
+    url(slotName: string, opts?: {
+        expiresInSeconds?: number;
+    }): Promise<string | null>;
+    /**
+     * Build the backlink stamped onto an external object's metadata — the
+     * self-describing "secondary store" reference back to this record. See
+     * {@link BlobFieldPolicy.backlink}. Returns the `userMeta` to attach and, for
+     * `opaque-token`, the `token` to record on the slot.
+     */
+    private buildBacklink;
+    /**
+     * Adopt an EXISTING object in the projection into this slot **without
+     * re-uploading** — used by import/bootstrap to anchor objects already in the
+     * bucket. Writes the external slot record (the catalog entry).
+     */
+    adoptExternal(slotName: string, ref: {
+        key: string;
+        size?: number;
+        contentType?: string;
+        public?: boolean;
+        backlink?: string;
+        meta?: Record<string, unknown>;
+    }): Promise<void>;
+    /**
+     * Merge derived metadata (video `duration`, image `width`/`height`, arbitrary
+     * metatags) into an external slot's secondary metadata store. Typically called
+     * from an AWS-side processing callback (MediaConvert / ffprobe / Rekognition)
+     * once it has probed the object. No-op for a missing or non-external slot.
+     */
+    setExternalMeta(slotName: string, meta: Record<string, unknown>): Promise<void>;
+    /**
+     * Read an external slot's synced derived metadata (the secondary store).
+     * Returns `null` for a missing or non-external slot, `{}` if none synced yet.
+     */
+    externalMeta(slotName: string): Promise<Record<string, unknown> | null>;
+    /**
+     * List all slot entries for this record.
+     * Returns metadata only — no chunk data is loaded.
+     */
+    list(): Promise<SlotInfo[]>;
+    /**
+     * Delete the named slot from this record.
+     * Decrements refCount on the blob. Chunks are GC'd by `vault.blobGC()`.
+     */
+    delete(slotName: string): Promise<void>;
+    /**
+     * Return a native `Response` whose body streams the decrypted,
+     * decompressed blob bytes with full HTTP metadata headers.
+     *
+     * Note: implementation is buffered — all chunks are loaded into
+     * memory before being enqueued. True streaming deferred to.
+     *
+     * Returns `null` if the slot does not exist.
+     */
+    response(slotName: string, opts?: BlobResponseOptions): Promise<Response | null>;
+    /**
+     * Decrypt the slot and wrap the bytes in a browser ObjectURL ready
+     * to feed into `<img src>`, `<a href>`, etc. The caller MUST call
+     * `revoke()` when the URL is no longer needed — otherwise the URL
+     * (and the underlying decrypted Blob) are pinned for the lifetime
+     * of the document, which leaks memory in long-lived pages.
+     *
+     * Returns `null` when the slot does not exist.
+     *
+     * Throws when `URL.createObjectURL` is unavailable in the host
+     * environment (Node without DOM, restricted workers). Framework
+     * adapters — `useBlobURL` in `@noy-db/in-vue`, etc. — guard against
+     * this for SSR contexts and stay at `null` instead of propagating.
+     */
+    objectURL(slotName: string, opts?: {
+        mimeType?: string;
+    }): Promise<{
+        url: string;
+        revoke: () => void;
+    } | null>;
+    /**
+     * Publish the current slot content as a named version snapshot.
+     *
+     * The published version holds an independent refCount reference to
+     * the blob. Even if the slot is later overwritten or deleted, the
+     * published version keeps the blob data alive.
+     *
+     * Publishing with an existing label overwrites it — if the eTags differ,
+     * refCounts are adjusted accordingly.
+     */
+    publish(slotName: string, label: string): Promise<void>;
+    /**
+     * Fetch bytes for a published version.
+     * Returns `null` if the version does not exist.
+     */
+    getVersion(slotName: string, label: string): Promise<Uint8Array | null>;
+    /**
+     * List all published versions for a slot.
+     */
+    listVersions(slotName: string): Promise<VersionRecord[]>;
+    /**
+     * Delete a published version. Decrements refCount on its blob.
+     */
+    deleteVersion(slotName: string, label: string): Promise<void>;
+    /**
+     * Return a `Response` for a published version — same as `response()`
+     * but reads from the version record's eTag instead of the current slot.
+     */
+    responseVersion(slotName: string, label: string, opts?: BlobResponseOptions): Promise<Response | null>;
+    /**
+     * Return the `BlobObject` metadata for the named slot.
+     * Returns `null` if the slot or blob does not exist.
+     */
+    blobInfo(slotName: string): Promise<BlobObject | null>;
+    /**
+     * Generate a presigned URL for direct client download of the blob's
+     * ciphertext. Only works when the blob store supports `presignUrl`.
+     *
+     * **Important:** The URL returns encrypted data. The caller must
+     * decrypt client-side using `decryptResponse()` or a service worker.
+     *
+     * Returns `null` if the slot doesn't exist or the store doesn't support presigning.
+     */
+    presignedUrl(slotName: string, expiresInSeconds?: number): Promise<string | null>;
+    /**
+     * Decrypt a ciphertext Response (e.g. from a presigned URL fetch)
+     * back into a plaintext Response with correct headers.
+     *
+     * Usage with service worker or client-side fetch:
+     * ```ts
+     * const url = await blobs.presignedUrl('invoice.pdf')
+     * const cipherResponse = await fetch(url)
+     * const plainResponse = await blobs.decryptResponse('invoice.pdf', cipherResponse)
+     * ```
+     */
+    decryptResponse(slotName: string, cipherResponse: Response): Promise<Response | null>;
+    private buildResponse;
+}