was-teaching-server 0.9.1

package/dist/backends/filesystem.d.ts

@@ -0,0 +1,1179 @@
+import { Transform, type Readable } from 'node:stream';
+import type { FastifyBaseLogger } from 'fastify';
+import type { BlindedIndexQuery, BlindedIndexQueryPage } from '../lib/blindedIndex.js';
+import type { SpaceDescription, CollectionDescription, CollectionSummary, CollectionResourcesList, ResourceResult, ResourceMetadata, ResourceMetadataCustom, ResourceInput, ImportStats, PolicyDocument, BackendDescriptor, BackendUsage, CollectionUsage, StorageBackend, StoredBackendRecord, KeystoreConfig, KmsKeyRecord, RevocationRecord, RevocationScope, CapabilitySummary, IDID } from '../types.js';
+/**
+ * The on-disk shape of a Resource's metadata sidecar (`.meta.<resourceId>.json`,
+ * see `metaSidecarFileName`). Only the server-managed timestamps, the monotonic
+ * `version`, and the user-writable `custom` object are persisted; `contentType`
+ * / `size` are always derived from the stored representation, never duplicated
+ * here.
+ *
+ * `createdBy` is the DID of whoever created the Resource (spec "Resource
+ * Metadata Data Model"): an OPTIONAL server-managed property, absent when no
+ * creator was recorded.
+ *
+ * `version` is the per-Resource monotonic counter that backs the HTTP `ETag`
+ * strong validator (see `formatEtag`): it starts at 1 on first content write and
+ * increments on each subsequent content write. It is `undefined` only for a
+ * Resource written before versioning existed (a legacy sidecar), in which case
+ * the backend treats the current version as 0.
+ *
+ * `metaVersion` is the independent monotonic counter for the `/meta`
+ * sub-resource (spec V2 metadata versioning): it starts at 1 on first metadata
+ * write and increments on each subsequent one, backing the `/meta` ETag. It is
+ * kept separate from `version` so a metadata-only edit does not bump the content
+ * ETag (preserving the content-ETag contract), and is `undefined` until the
+ * first metadata write. A content write preserves it unchanged.
+ *
+ * `deleted` marks a **tombstone**: a soft delete that drops the content
+ * representation but keeps the sidecar so the change feed (replication) still
+ * surfaces it. A
+ * tombstone has no `r.<id>...` content file, so it is invisible to every normal
+ * read path (which gates on the content file via `_findFile`); only the
+ * (future) change feed reads it. `contentType` records the representation's
+ * last-known content-type, which the content filename no longer carries once it
+ * is gone -- present only on a tombstone (a live Resource derives its
+ * content-type from the filename).
+ */
+interface MetaSidecar {
+    createdAt: string;
+    updatedAt: string;
+    createdBy?: IDID;
+    version?: number;
+    metaVersion?: number;
+    custom?: ResourceMetadataCustom | Record<string, unknown>;
+    epoch?: string;
+    deleted?: boolean;
+    contentType?: string;
+}
+/**
+ * Builds the on-disk filename for a Resource's metadata sidecar:
+ * `.meta.<resourceId>.json`. A dot-file kept alongside the resource
+ * representation in the Collection dir (the same convention as `.policy.` /
+ * `.collection.`), holding the timestamps and user-writable `custom` object.
+ * @param resourceId {string}
+ * @returns {string}
+ */
+export declare function metaSidecarFileName(resourceId: string): string;
+export declare class FileSystemBackend implements StorageBackend {
+    spacesDir: string;
+    /**
+     * Root of the WebKMS keystore tree (`data/keystores/<localId>/`), a sibling
+     * of `spacesDir` -- the `/kms` facet is deliberately separable from Spaces
+     * (own route family, own storage tree).
+     */
+    keystoresDir: string;
+    /**
+     * Root of the Space zcap revocation tree (`data/space-revocations/<spaceId>/`),
+     * a sibling of `spacesDir` rather than a subdirectory of each Space. Space
+     * revocations deliberately live OUTSIDE the Space's own directory because
+     * `listCollections` and `_countLiveResources` treat every subdirectory of a
+     * Space dir as a Collection -- a `revocations/` dir nested inside a Space would
+     * surface as a phantom Collection (and could collide with a real one), so it
+     * gets its own root.
+     */
+    spaceRevocationsDir: string;
+    logger: FastifyBaseLogger;
+    /**
+     * Per-Space storage capacity, in bytes (spec "Quotas"). `undefined` means no
+     * configured limit -- the backend reports an unlimited quota (state always
+     * `ok`) and skips write-path enforcement. A finite value drives the
+     * `near-limit` / `over-quota` state thresholds (see `reportUsage`) and is
+     * enforced on the write path: `writeResource` and `importSpace` reject writes
+     * that would push a Space over capacity with `QuotaExceededError` (507). The
+     * constructor normalizes a non-finite ctor option (`Infinity`) to `undefined`.
+     */
+    capacityBytes?: number;
+    /**
+     * Largest single upload the backend accepts, in bytes (spec "Quotas", the
+     * `maxUploadBytes` constraint). `undefined` means no per-upload cap. Distinct
+     * from `capacityBytes` (the cumulative per-Space quota): a write larger than
+     * this cap is rejected with `PayloadTooLargeError` (413) even when the Space
+     * has ample headroom, while smaller writes still succeed. Advertised in quota
+     * reports under `constraints.maxUploadBytes` and enforced on `writeResource`.
+     * The constructor normalizes an unset ctor option to
+     * {@link DEFAULT_MAX_UPLOAD_BYTES} (a default-on cap) and a non-finite option
+     * (`Infinity`) to `undefined` (explicitly no cap).
+     */
+    maxUploadBytes?: number;
+    /**
+     * Max Spaces a single controller may create (spec "Quotas", a default-on
+     * count quota). `undefined` means no cap. Enforced on the Space create path
+     * (`writeSpace`): a new Space whose `controller` already owns this many
+     * Spaces is rejected with `CountQuotaExceededError` (507); overwriting an
+     * existing Space never trips it. The constructor normalizes an unset ctor
+     * option to {@link DEFAULT_MAX_SPACES_PER_CONTROLLER} and a non-finite option
+     * (`Infinity`) to `undefined` (explicitly no cap). Soft under concurrency,
+     * like the byte quota.
+     */
+    maxSpacesPerController?: number;
+    /**
+     * Max Collections a single Space may hold (spec "Quotas", a default-on count
+     * quota). `undefined` means no cap. Enforced on the Collection create path
+     * (`writeCollection`); overwriting an existing Collection description never
+     * trips it. Normalized like {@link maxSpacesPerController}.
+     */
+    maxCollectionsPerSpace?: number;
+    /**
+     * Max live Resources a single Space may hold across all its Collections (spec
+     * "Quotas", a default-on count quota). `undefined` means no cap. Enforced on
+     * the Resource create path (`writeResource`); a tombstone does not count, and
+     * a write over an existing live Resource never trips it. Normalized like
+     * {@link maxSpacesPerController}.
+     */
+    maxResourcesPerSpace?: number;
+    /**
+     * Per-Resource write serialization (the `conditional-writes` feature). A
+     * content write or delete that carries a precondition reads the current
+     * `version`, evaluates `If-Match` / `If-None-Match`, and writes -- all under
+     * this lock, keyed per Resource -- so two concurrent writers cannot both
+     * observe the same prior version and both succeed. Single-instance only.
+     */
+    private _writeMutex;
+    /**
+     * Per-Space usage totals for the write-path quota pre-flight, so
+     * `_assertSpaceHeadroom` does not spawn `du` (a whole-Space tree walk) on
+     * every resource write. Entries live `QUOTA_USAGE_CACHE_TTL` ms; each
+     * accepted write adds its incoming bytes to the cached total, and deletes
+     * invalidate the Space's entry. Quota reports (`reportUsage`) always
+     * re-measure. Single-instance only, like `_writeMutex`.
+     */
+    private _usageCache;
+    constructor({ dataDir, logger, capacityBytes, maxUploadBytes, maxSpacesPerController, maxCollectionsPerSpace, maxResourcesPerSpace }: {
+        dataDir: string;
+        logger?: FastifyBaseLogger;
+        capacityBytes?: number;
+        maxUploadBytes?: number;
+        maxSpacesPerController?: number;
+        maxCollectionsPerSpace?: number;
+        maxResourcesPerSpace?: number;
+    });
+    /**
+     * Self-description advertised at `GET /space/:spaceId/backends`. The
+     * filesystem backend is the single server-configured default: it stores both
+     * JSON documents and binary blobs on disk, so its data survives restarts.
+     *
+     * It advertises the `conditional-writes` affordance: it exposes a per-Resource
+     * `version` as an HTTP `ETag` validator and honors `If-Match` / `If-None-Match`
+     * write preconditions atomically (returning `412 precondition-failed` on a
+     * mismatch). The remaining `features` vocabulary token (`chunked-streams`)
+     * is not implemented yet and is added when it lands.
+     * (Client-side encryption is deliberately not a backend feature: encrypted
+     * documents are opaque client-encrypted JSON this backend already stores
+     * faithfully, with no server cooperation.)
+     * @returns {Required<Omit<BackendDescriptor, 'provider' | 'connection'>>}
+     */
+    describe(): Required<Omit<BackendDescriptor, 'provider' | 'connection'>>;
+    /**
+     * Measures disk usage under the Space dir with `du`, returning the grand total
+     * and a per-Collection breakdown in one pass. `du -d 1 -B 1` (GNU coreutils)
+     * reports each immediate subdirectory (one per Collection) plus the Space dir
+     * itself (the total, which also covers top-level Space files such as the
+     * `.space.` / `.policy.` documents), all in bytes. An absent Space dir (ENOENT
+     * before the dir is provisioned) reports zero usage rather than throwing.
+     * @param spaceDir {string}
+     * @returns {Promise<{ total: number, byCollection: CollectionUsage[] }>}
+     */
+    _diskUsage(spaceDir: string): Promise<{
+        total: number;
+        byCollection: CollectionUsage[];
+    }>;
+    /**
+     * Measures the bytes this Space consumes on disk for the Space Quota report
+     * (spec "Quotas"). `usageBytes` is the `du` total under the Space dir
+     * (Collection dirs plus top-level Space files); `usageByCollection` breaks the
+     * per-Collection totals out (they sum to slightly less than `usageBytes`,
+     * since the Space-level files belong to no Collection).
+     *
+     * The per-Collection `usageByCollection` breakdown is included only when
+     * `includeCollections` is set -- the spec's `?include=collections` opt-in (see
+     * the `quotas` handler, which now tolerates the query string via the
+     * `allowTargetQuery` ZCap path). On the filesystem the breakdown is free (the
+     * one `du -d 1` pass yields it alongside the total), but it is still omitted by
+     * default to keep the hot-path payload lean and match the wire contract.
+     *
+     * `state` / `restrictedActions` derive from usage vs `capacityBytes`: an
+     * unlimited backend is always `ok`; a finite capacity yields `near-limit` at
+     * `QUOTA_NEAR_LIMIT_FRACTION` of capacity and `over-quota` (with reads/deletes
+     * still allowed, but `POST`/`PUT` restricted) at or above full.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param [options.includeCollections] {boolean}   include the per-Collection
+     *   breakdown (spec `?include=collections`)
+     * @returns {Promise<BackendUsage>}
+     */
+    reportUsage({ spaceId, includeCollections }: {
+        spaceId: string;
+        includeCollections?: boolean;
+    }): Promise<BackendUsage>;
+    /**
+     * Measures the bytes a single Collection consumes on disk for the
+     * per-Collection Quota report (spec "Quotas", `GET /space/{id}/{cid}/quota`).
+     * `usageBytes` is scoped to the Collection (its slice of the one-pass
+     * `_diskUsage` breakdown; zero if the Collection dir is empty or absent),
+     * while `state` / `limit` / `restrictedActions` describe the backend's overall
+     * condition (derived from the Space total -- the quota is a per-backend limit,
+     * not per-Collection). The per-Collection `usageByCollection` breakdown is
+     * omitted (a single Collection is the whole report).
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @returns {Promise<BackendUsage>}
+     */
+    reportCollectionUsage({ spaceId, collectionId }: {
+        spaceId: string;
+        collectionId: string;
+    }): Promise<BackendUsage>;
+    /**
+     * Builds the backend-identity and condition fields shared by the Space and
+     * per-Collection quota reports. `usageBytes` is what the report shows (the
+     * Space total or a single Collection's slice); `spaceTotalBytes` drives the
+     * `state` / `restrictedActions`, which are backend-wide (the quota is a
+     * per-Space limit) and so always measured against the Space total. The
+     * `constraints.maxUploadBytes` cap is advertised when configured.
+     * @param options {object}
+     * @param options.usageBytes {number}   the usage figure to report
+     * @param options.spaceTotalBytes {number}   the Space total, for state
+     * @returns {Omit<BackendUsage, 'measuredAt' | 'usageByCollection'>}
+     */
+    _backendUsageFields({ usageBytes, spaceTotalBytes }: {
+        usageBytes: number;
+        spaceTotalBytes: number;
+    }): Omit<BackendUsage, 'measuredAt' | 'usageByCollection'>;
+    /**
+     * Quota pre-flight for the write path (spec "Quotas"): measures the Space's
+     * current on-disk usage and returns the remaining headroom in bytes against
+     * `capacityBytes`. Throws `QuotaExceededError` (507) when the Space is already
+     * at or over capacity, or when a known `incomingBytes` would not fit. Callers
+     * pass the configured `capacityBytes` explicitly (an unlimited backend skips
+     * enforcement entirely and never calls this).
+     *
+     * This is a soft limit under concurrency: two simultaneous writes can each pass
+     * against the same usage snapshot and jointly overshoot. The per-write
+     * streaming guard (`_quotaGuard`) still bounds each individual write.
+     *
+     * The `du` measurement (a whole-Space tree walk) is cached per Space for
+     * `QUOTA_USAGE_CACHE_TTL` ms (see `_usageCache`): between re-measurements
+     * each accepted write's `incomingBytes` is added to the cached total, so a
+     * burst of writes costs one tree walk, not one per write.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.capacityBytes {number}   the configured per-Space limit
+     * @param [options.incomingBytes] {number}   known size of the pending write
+     * @returns {Promise<number>}   remaining headroom in bytes
+     */
+    _assertSpaceHeadroom({ spaceId, capacityBytes, incomingBytes }: {
+        spaceId: string;
+        capacityBytes: number;
+        incomingBytes?: number;
+    }): Promise<number>;
+    /**
+     * A pass-through `Transform` that counts the bytes flowing through it and
+     * aborts the pipeline with `QuotaExceededError` (507) once the cumulative total
+     * would exceed `headroomBytes`. Hard-caps a streamed blob write whose size is
+     * not known up front (so the pre-flight check alone cannot catch it), e.g. a
+     * multipart upload or a body without `Content-Length`.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.capacityBytes {number}   the configured per-Space limit
+     * @param options.headroomBytes {number}   max bytes this write may add
+     * @returns {Transform}
+     */
+    _quotaGuard({ spaceId, capacityBytes, headroomBytes }: {
+        spaceId: string;
+        capacityBytes: number;
+        headroomBytes: number;
+    }): Transform;
+    /**
+     * A pass-through `Transform` that counts the bytes flowing through it and
+     * aborts the pipeline with `PayloadTooLargeError` (413) once the cumulative
+     * total exceeds `maxUploadBytes`. Caps a single streamed upload whose size is
+     * not known up front (e.g. a multipart part or a body without
+     * `Content-Length`), independently of the cumulative Space quota.
+     * @param options {object}
+     * @param options.maxUploadBytes {number}   the per-upload cap in bytes
+     * @returns {Transform}
+     */
+    _uploadCapGuard({ maxUploadBytes }: {
+        maxUploadBytes: number;
+    }): Transform;
+    /**
+     * Defense in depth: asserts that a built path stays within the given storage
+     * root (`spacesDir` by default; `keystoresDir` for the keystore tree), so a
+     * malformed id that somehow slips past request-layer validation can never
+     * escape it (path traversal). The request and tar-import layers reject such
+     * ids first; this is the last line of defense.
+     * @param targetPath {string}
+     * @param [rootDir] {string}   the containing root; defaults to `spacesDir`
+     * @returns {void}
+     */
+    _assertContained(targetPath: string, rootDir?: string): void;
+    _spaceDir(spaceId: string): string;
+    /**
+     * The directory holding one Space's zcap revocation records, under the
+     * sibling `spaceRevocationsDir` root (see that property's doc for why it is
+     * not inside the Space dir), guarded against escaping it.
+     * @param spaceId {string}
+     * @returns {string}
+     */
+    _spaceRevocationDir(spaceId: string): string;
+    _collectionDir({ spaceId, collectionId }: {
+        spaceId: string;
+        collectionId: string;
+    }): string;
+    /**
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @returns {Promise<string>} Created space storage directory path.
+     */
+    _ensureSpaceDir({ spaceId }: {
+        spaceId: string;
+    }): Promise<string>;
+    /**
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @returns {Promise<string>} Created collection storage directory path.
+     */
+    _ensureCollectionDir({ spaceId, collectionId }: {
+        spaceId: string;
+        collectionId: string;
+    }): Promise<string>;
+    /**
+     * Lists every on-disk file belonging to a single Resource: the
+     * representation(s) whose name starts with `r.<encodedResourceId>.` in the
+     * Collection dir. The trailing `.` anchors to the filename's segment boundary
+     * (`r.<encodedResourceId>.<encodedType>.<ext>`) so a resourceId that is a
+     * prefix of another (e.g. `note` vs `notebook`) does not match the longer one;
+     * the id is dot-escaped to match the stored name (see `fileNameFor`). A Resource
+     * normally has a single current representation, so this usually returns one
+     * path; it returns more only transiently while a prior representation under a
+     * different content-type is being pruned. An absent Collection dir resolves an
+     * empty list (it holds no such files).
+     * @param options {object}
+     * @param options.collectionDir {string}
+     * @param options.resourceId {string}
+     * @returns {Promise<string[]>}   full paths, in directory order
+     */
+    _resourceFilesFor({ collectionDir, resourceId }: {
+        collectionDir: string;
+        resourceId: string;
+    }): Promise<string[]>;
+    /**
+     * @param options {object}
+     * @param options.collectionDir {string}
+     * @param options.resourceId {string}
+     * @returns {Promise<string|undefined>} First matching resource file path.
+     */
+    _findFile({ collectionDir, resourceId }: {
+        collectionDir: string;
+        resourceId: string;
+    }): Promise<string | undefined>;
+    /**
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.spaceDescription {SpaceDescription}
+     * @param [options.createdBy] {string}   DID of the invoker, recorded as the
+     *   Space's `createdBy` on first write only
+     * @returns {Promise<void>} Resolved value is implementation-defined and ignored.
+     */
+    writeSpace({ spaceId, spaceDescription, createdBy }: {
+        spaceId: string;
+        spaceDescription: SpaceDescription;
+        createdBy?: IDID;
+    }): Promise<void>;
+    /**
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @returns {Promise<SpaceDescription|undefined>}
+     *   Resolves falsy when the Space does not exist (must not throw).
+     */
+    getSpaceDescription({ spaceId }: {
+        spaceId: string;
+    }): Promise<SpaceDescription | undefined>;
+    /**
+     * Removes a Space and everything scoped to it. The Space's zcap revocations
+     * live in a sibling root (`spaceRevocationsDir`), not under the Space dir, so
+     * they are removed explicitly here rather than falling out of the Space dir
+     * rm.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @returns {Promise<void>}
+     */
+    deleteSpace({ spaceId }: {
+        spaceId: string;
+    }): Promise<void>;
+    /**
+     * Enumerates every Space stored on this backend (each immediate subdirectory
+     * of the spaces root), sorted by Space id. An absent spaces root (nothing
+     * stored yet) resolves an empty list, not an error; a directory without a
+     * readable description file (e.g. a partially deleted Space) is skipped.
+     * @returns {Promise<SpaceDescription[]>}
+     */
+    listSpaces(): Promise<SpaceDescription[]>;
+    /**
+     * Counts the live Resources across every Collection of a Space, for the
+     * Resource count quota (`maxResourcesPerSpace`). Enumerates each Collection
+     * dir and counts distinct Resource ids that have a live representation file
+     * (`r.<id>...`); a tombstone (a `.meta.` sidecar with no `r.` file) does not
+     * count. An absent Space dir counts zero (not yet provisioned). Soft under
+     * concurrency, like the byte quota -- measured at check time by enumeration.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @returns {Promise<number>}   the number of live Resources
+     */
+    _countLiveResources({ spaceId }: {
+        spaceId: string;
+    }): Promise<number>;
+    /**
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @returns {Promise<CollectionSummary[]>}
+     */
+    listCollections({ spaceId }: {
+        spaceId: string;
+    }): Promise<CollectionSummary[]>;
+    /**
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @returns {Promise<Readable>} tar-stream pack
+     */
+    exportSpace({ spaceId }: {
+        spaceId: string;
+    }): Promise<Readable>;
+    /**
+     * Merges a WAS space-export tarball into an existing Space (collections and
+     * resources that already exist are skipped, not overwritten).
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.tarStream {Readable}
+     * @returns {Promise<ImportStats>}
+     */
+    importSpace({ spaceId, tarStream }: {
+        spaceId: string;
+        tarStream: Readable;
+    }): Promise<ImportStats>;
+    /**
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @param options.collectionDescription {CollectionDescription}
+     * @param [options.createdBy] {string}   DID of the invoker, recorded as the
+     *   Collection's `createdBy` on first write only
+     * @param [options.ifMatch] {string}   an `If-Match` compare-and-swap on the
+     *   current description version (the `key-epochs` feature); a stale validator
+     *   throws `PreconditionFailedError` (412)
+     * @returns {Promise<{ version: number }>}   the Collection's new description
+     *   version (the `ETag` validator)
+     */
+    writeCollection({ spaceId, collectionId, collectionDescription, createdBy, ifMatch, assertTransition }: {
+        spaceId: string;
+        collectionId: string;
+        collectionDescription: CollectionDescription;
+        createdBy?: IDID;
+        ifMatch?: string;
+        assertTransition?: (prior?: CollectionDescription & {
+            descriptionVersion?: number;
+        }) => void;
+    }): Promise<{
+        version: number;
+    }>;
+    /**
+     * Builds the per-Collection-description serialization key for `_writeMutex`
+     * (`desc:<spaceId>/<collectionId>`), so a Collection Description compare-and-
+     * swap serializes with itself while staying disjoint from the per-Resource and
+     * unique-scan lock namespaces.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @returns {string}
+     */
+    _collectionDescLockKey({ spaceId, collectionId }: {
+        spaceId: string;
+        collectionId: string;
+    }): string;
+    /**
+     * Writes a Collection's description file (creating the Collection dir if
+     * needed), with NO count-quota check. The count guard lives in the public
+     * `writeCollection`; `importSpace` tracks the Space's Collection count itself
+     * (measured once up front) and calls this directly, so it does not
+     * re-enumerate the Space per created Collection.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @param options.collectionDescription {CollectionDescription}
+     * @param [options.descriptionVersion] {number}   the monotonic description
+     *   version to persist (the `ETag` validator; the `key-epochs` feature). Kept
+     *   OUT of the wire body -- stored under a reserved `_version` member that
+     *   `getCollectionDescription` strips and re-surfaces as `descriptionVersion`.
+     *   When omitted (the import path), a `_version` already on the incoming
+     *   description is preserved, else it defaults to `1`.
+     * @returns {Promise<void>}
+     */
+    _persistCollection({ spaceId, collectionId, collectionDescription, descriptionVersion }: {
+        spaceId: string;
+        collectionId: string;
+        collectionDescription: CollectionDescription;
+        descriptionVersion?: number;
+    }): Promise<void>;
+    /**
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @returns {Promise<CollectionDescription|undefined>}
+     *   Resolves falsy when the Collection does not exist (must not throw).
+     */
+    getCollectionDescription({ spaceId, collectionId }: {
+        spaceId: string;
+        collectionId: string;
+    }): Promise<(CollectionDescription & {
+        descriptionVersion?: number;
+    }) | undefined>;
+    /**
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @returns {Promise<void>}
+     */
+    deleteCollection({ spaceId, collectionId }: {
+        spaceId: string;
+        collectionId: string;
+    }): Promise<void>;
+    /**
+     * Lists a Collection's Resources, OPTIONALLY cursor-paginated (spec
+     * "Pagination"). Items are returned in a stable total order -- ascending by
+     * `resourceId`, read straight from the `r.<resourceId>.<type>.<ext>` filename
+     * (the keyset). A `cursor` resumes the scan at the first id strictly greater
+     * than the cursor's anchor, so paging stays correct even if the anchor id was
+     * deleted between pages; `limit` bounds the page (clamped to
+     * `[1, MAX_PAGE_SIZE]`, default `DEFAULT_PAGE_SIZE`). `next` is built (and
+     * present) only when a further page may follow.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @param [options.limit] {number}   requested page size
+     * @param [options.cursor] {string}   opaque cursor from a prior page's `next`
+     * @returns {Promise<CollectionResourcesList>}
+     */
+    listCollectionItems({ spaceId, collectionId, limit, cursor, collectionDescription: providedDescription }: {
+        spaceId: string;
+        collectionId: string;
+        limit?: number;
+        cursor?: string;
+        collectionDescription?: CollectionDescription;
+    }): Promise<CollectionResourcesList>;
+    /**
+     * Writes a resource representation (JSON value or byte stream) to disk, under
+     * the per-Resource write lock (the `conditional-writes` feature), and bumps
+     * the Resource's monotonic `version`. The new version is returned so the
+     * request layer can surface it as the response `ETag`.
+     *
+     * When a conditional-write precondition is supplied it is evaluated against
+     * the Resource's current state atomically with the write (under the lock),
+     * throwing `PreconditionFailedError` (412) on a mismatch:
+     * - `ifNoneMatch` (a create-if-absent `If-None-Match: *`) fails if the
+     *   Resource already exists.
+     * - `ifMatch` (an update-if-unchanged `If-Match: "<etag>"`) fails if the
+     *   Resource is absent or its current `ETag` does not equal `ifMatch`.
+     * `ifNoneMatch` takes precedence when both are supplied (RFC9110).
+     *
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @param options.resourceId {string}
+     * @param options.input {ResourceInput}
+     * @param [options.createdBy] {string}   DID of the invoker, recorded as the
+     *   Resource's `createdBy` on first write only
+     * @param [options.ifMatch] {string}   `If-Match` precondition (a quoted ETag)
+     * @param [options.ifNoneMatch] {boolean}   `If-None-Match: *` (create-if-absent)
+     * @returns {Promise<{ version: number }>}   the Resource's new version
+     */
+    writeResource({ spaceId, collectionId, resourceId, input, createdBy, epoch, ifMatch, ifNoneMatch }: {
+        spaceId: string;
+        collectionId: string;
+        resourceId: string;
+        input: ResourceInput;
+        createdBy?: IDID;
+        epoch?: string;
+        ifMatch?: string;
+        ifNoneMatch?: boolean;
+    }): Promise<{
+        version: number;
+    }>;
+    /**
+     * The critical section of `writeResource`, run under the per-Resource lock:
+     * evaluates any precondition, writes the representation, prunes a stale
+     * representation under a different content-type, and persists the bumped
+     * `version` in the sidecar. See `writeResource` for the parameters.
+     * @returns {Promise<{ version: number }>}
+     */
+    private _writeResourceLocked;
+    /**
+     * Builds the per-Resource serialization key for `_writeMutex`
+     * (`<spaceId>/<collectionId>/<resourceId>`), so conditional writes to distinct
+     * Resources run concurrently while writes to the same Resource are ordered.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @param options.resourceId {string}
+     * @returns {string}
+     */
+    _resourceLockKey({ spaceId, collectionId, resourceId }: {
+        spaceId: string;
+        collectionId: string;
+        resourceId: string;
+    }): string;
+    /**
+     * The Collection-level mutex key, held by unique-blinded-attribute writes to
+     * serialize their conflict scans. Namespaced (`unique:` prefix) so it can
+     * never collide with a per-Resource key.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @returns {string}
+     */
+    _collectionLockKey({ spaceId, collectionId }: {
+        spaceId: string;
+        collectionId: string;
+    }): string;
+    /**
+     * Evaluates a conditional-write precondition against a Resource's current
+     * on-disk state. MUST be called inside the per-Resource write lock so the
+     * check is atomic with the write that follows. Throws
+     * `PreconditionFailedError` (412) when the precondition is not met.
+     * @param options {object}
+     * @param options.collectionDir {string}
+     * @param options.resourceId {string}
+     * @param [options.ifMatch] {string}   a quoted ETag (`If-Match`)
+     * @param [options.ifNoneMatch] {boolean}   `If-None-Match: *` (create-if-absent)
+     * @returns {Promise<void>}
+     */
+    _assertWritePrecondition({ collectionDir, resourceId, ifMatch, ifNoneMatch }: {
+        collectionDir: string;
+        resourceId: string;
+        ifMatch?: string;
+        ifNoneMatch?: boolean;
+    }): Promise<void>;
+    /**
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @param options.resourceId {string}
+     * @param [options.contentType] {string}
+     * @returns {Promise<ResourceResult>}   includes the Resource's current
+     *   `version` (the ETag validator) when one is recorded in its sidecar.
+     */
+    getResource({ spaceId, collectionId, resourceId }: {
+        spaceId: string;
+        collectionId: string;
+        resourceId: string;
+        /**
+         * `contentType` is advisory and ignored for lookup: a Resource has a
+         * single current representation, resolved by `resourceId` alone.
+         */
+        contentType?: string;
+    }): Promise<ResourceResult>;
+    /**
+     * Builds the on-disk path for a Resource's metadata sidecar
+     * (`.meta.<resourceId>.json`) in its Collection dir.
+     * @param options {object}
+     * @param options.collectionDir {string}
+     * @param options.resourceId {string}
+     * @returns {string}
+     */
+    _metaSidecarPath({ collectionDir, resourceId }: {
+        collectionDir: string;
+        resourceId: string;
+    }): string;
+    /**
+     * Reads a Resource's metadata sidecar. Resolves `undefined` when none has been
+     * written yet (e.g. a Resource created before sidecars existed).
+     * @param options {object}
+     * @param options.collectionDir {string}
+     * @param options.resourceId {string}
+     * @returns {Promise<MetaSidecar|undefined>}
+     */
+    _readMetaSidecar({ collectionDir, resourceId }: {
+        collectionDir: string;
+        resourceId: string;
+    }): Promise<MetaSidecar | undefined>;
+    /**
+     * Writes a Resource's metadata sidecar (full replacement).
+     * @param options {object}
+     * @param options.collectionDir {string}
+     * @param options.resourceId {string}
+     * @param options.sidecar {MetaSidecar}
+     * @returns {Promise<void>}
+     */
+    _writeMetaSidecar({ collectionDir, resourceId, sidecar }: {
+        collectionDir: string;
+        resourceId: string;
+        sidecar: MetaSidecar;
+    }): Promise<void>;
+    /**
+     * Reads the metadata of a Resource's current representation: the REQUIRED
+     * server-managed fields (`contentType`, `size`, both derived from the stored
+     * file), plus the OPTIONAL `createdAt` / `updatedAt` timestamps and the
+     * user-writable `custom` object read from the sidecar. For a Resource written
+     * before sidecars existed, the timestamps fall back to the file's birth/modify
+     * times and `custom` is omitted. Resolves `undefined` when the Resource is
+     * absent (including a delete race on `stat`).
+     *
+     * Also surfaces the Resource's content `version` and its `metaVersion` (the
+     * two ETag validators) when recorded in the sidecar, so the request layer can
+     * set the `ETag` header: HEAD / the resource itself use the content `version`,
+     * while `GET /meta` uses `metaVersion`. Both are out-of-band fields the request
+     * layer reads for the header; neither is part of the Resource Metadata wire
+     * body.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @param options.resourceId {string}
+     * @returns {Promise<(ResourceMetadata & { version?: number; metaVersion?:
+     *   number }) | undefined>}
+     */
+    getResourceMetadata({ spaceId, collectionId, resourceId }: {
+        spaceId: string;
+        collectionId: string;
+        resourceId: string;
+    }): Promise<(ResourceMetadata & {
+        version?: number;
+        metaVersion?: number;
+    }) | undefined>;
+    /**
+     * Replaces the user-writable `custom` object of a Resource's metadata sidecar
+     * (full replacement; `{}` clears it), bumping `updatedAt` and the independent
+     * `metaVersion` (the `/meta` ETag). Does not create a Resource: resolves
+     * `undefined` when the Resource is absent so the handler can 404. The content
+     * `version` and the two REQUIRED server-managed fields are untouched (a
+     * metadata write does not change the stored representation, preserving the
+     * content ETag contract). On an encrypted Collection `custom` is the opaque
+     * encryption envelope, stored verbatim.
+     *
+     * Runs under the per-Resource write lock -- the same lock content writes take
+     * -- so an `If-Match` / `If-None-Match` precondition (evaluated on
+     * `metaVersion`) is atomic with the write and serializes with concurrent
+     * content/metadata writes to the same Resource. A precondition mismatch throws
+     * `PreconditionFailedError` (412).
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @param options.resourceId {string}
+     * @param options.custom {ResourceMetadataCustom | Record<string, unknown>}
+     * @param [options.ifMatch] {string}   `If-Match` on the current `metaVersion`
+     * @param [options.ifNoneMatch] {boolean}   `If-None-Match: *` -- write only if
+     *   no metadata has been written yet (`metaVersion` unset)
+     * @returns {Promise<{ metaVersion: number } | undefined>}   the new
+     *   `metaVersion`, or `undefined` when the Resource does not exist
+     */
+    writeResourceMetadata({ spaceId, collectionId, resourceId, custom, epoch, ifMatch, ifNoneMatch }: {
+        spaceId: string;
+        collectionId: string;
+        resourceId: string;
+        custom: ResourceMetadataCustom | Record<string, unknown>;
+        epoch?: string;
+        ifMatch?: string;
+        ifNoneMatch?: boolean;
+    }): Promise<{
+        metaVersion: number;
+    } | undefined>;
+    /**
+     * Soft-deletes a Resource: drops its content representation but keeps the
+     * sidecar as a **tombstone** (`deleted: true`, a bumped `version` and
+     * `updatedAt`, the last-known `contentType` retained) so the change feed
+     * (replication) still surfaces it until clients catch up (GC of tombstones is
+     * future work). With no content file left, the tombstone is invisible to
+     * every normal read path
+     * (`getResource` / `getResourceMetadata` / `listCollectionItems` all gate on
+     * the content file via `_findFile`, so they 404 / skip it), making soft delete
+     * transparent to the existing API.
+     *
+     * When `ifMatch` is supplied (the `conditional-writes` feature), the delete
+     * proceeds only if the Resource exists and its current `ETag` matches, else
+     * `PreconditionFailedError` (412). The whole read-modify-write runs under the
+     * per-Resource write lock so it serializes with concurrent writes. The delete
+     * is idempotent: an already-absent Resource (never created, or an existing
+     * tombstone) is a no-op, leaving any tombstone's change-feed entry stable.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @param options.resourceId {string}
+     * @param [options.ifMatch] {string}   `If-Match` precondition (a quoted ETag)
+     * @returns {Promise<void>}
+     */
+    deleteResource({ spaceId, collectionId, resourceId, ifMatch }: {
+        spaceId: string;
+        collectionId: string;
+        resourceId: string;
+        ifMatch?: string;
+    }): Promise<void>;
+    /**
+     * Replication change feed (the `changes` query profile; see the
+     * `StorageBackend.changesSince` contract.
+     * Enumerates the Collection once, builds a lightweight descriptor for every
+     * JSON-document Resource (live) and JSON tombstone, orders them by
+     * `(updatedAt, resourceId)`, seeks strictly past `checkpoint`, takes a page of
+     * `limit`, and reads JSON bodies ONLY for that page. O(n) over the Collection
+     * per call (it must read every sidecar to order by `updatedAt`) -- acceptable
+     * for this teaching backend; an indexed backend would answer it from an
+     * `updatedAt` index.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @param [options.checkpoint] {{ id: string, updatedAt: string }}   resume position
+     * @param options.limit {number}   page cap (clamped to the backend maximum)
+     * @returns {Promise<{ documents: Array<object>, checkpoint: object | null }>}
+     */
+    changesSince({ spaceId, collectionId, checkpoint, limit }: {
+        spaceId: string;
+        collectionId: string;
+        checkpoint?: {
+            id: string;
+            updatedAt: string;
+        };
+        limit: number;
+    }): Promise<{
+        documents: Array<{
+            resourceId: string;
+            version: number;
+            metaVersion?: number;
+            createdBy?: IDID;
+            updatedAt: string;
+            deleted: boolean;
+            data?: unknown;
+            custom?: ResourceMetadataCustom | Record<string, unknown>;
+            epoch?: string;
+        }>;
+        checkpoint: {
+            id: string;
+            updatedAt: string;
+        } | null;
+    }>;
+    /**
+     * Blinded-index query (the `blinded-index` query profile; see the
+     * `StorageBackend.queryByBlindedIndex` contract). Enumerates the Collection
+     * dir, reads and parses every live JSON Resource, and hands the candidates
+     * to the shared evaluator (`lib/blindedIndex.ts`) for matching, ordering,
+     * and cursor pagination. O(n) over the Collection per call, with every JSON
+     * body read -- acceptable for this teaching backend; an indexed backend
+     * would answer from flattened attribute tokens. Tombstones are excluded
+     * naturally (no live content file); binary Resources and unparsable JSON
+     * are skipped.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @param options.query {BlindedIndexQuery}
+     * @param [options.count] {boolean}   return only the match count
+     * @param [options.limit] {number}   requested page size
+     * @param [options.cursor] {string}   opaque cursor from a prior page
+     * @returns {Promise<{ count: number } | BlindedIndexQueryPage>}
+     */
+    queryByBlindedIndex({ spaceId, collectionId, query, count, limit, cursor }: {
+        spaceId: string;
+        collectionId: string;
+        query: BlindedIndexQuery;
+        count?: boolean;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        count: number;
+    } | BlindedIndexQueryPage>;
+    /**
+     * Reads and parses every live JSON Resource of a Collection -- the candidate
+     * set for both the blinded-index query and the unique-attribute conflict
+     * scan. Tombstones are excluded naturally (no live content file); binary
+     * Resources, unparsable JSON, and (optionally) one excluded Resource are
+     * skipped. An absent Collection dir resolves empty.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @param [options.excludeResourceId] {string}   omit this Resource (the
+     *   conflict scan excludes the document being written)
+     * @returns {Promise<Array<{ resourceId: string, document: unknown }>>}
+     */
+    private _readJsonCandidates;
+    /**
+     * Builds the on-disk path for a policy document. Stored as a dot-file keyed by
+     * the entity id, alongside the matching `.space.` / `.collection.` description:
+     * Space policy in the space dir, Collection and Resource policy in the
+     * collection dir (the keying id differs, so they never collide).
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param [options.collectionId] {string}
+     * @param [options.resourceId] {string}
+     * @returns {string}
+     */
+    _policyFile({ spaceId, collectionId, resourceId }: {
+        spaceId: string;
+        collectionId?: string;
+        resourceId?: string;
+    }): string;
+    /**
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param [options.collectionId] {string}
+     * @param [options.resourceId] {string}
+     * @returns {Promise<PolicyDocument|undefined>}
+     *   Resolves falsy when no policy is set at that level (must not throw).
+     */
+    getPolicy({ spaceId, collectionId, resourceId }: {
+        spaceId: string;
+        collectionId?: string;
+        resourceId?: string;
+    }): Promise<PolicyDocument | undefined>;
+    /**
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param [options.collectionId] {string}
+     * @param [options.resourceId] {string}
+     * @param options.policy {PolicyDocument}
+     * @returns {Promise<void>}
+     */
+    writePolicy({ spaceId, collectionId, resourceId, policy }: {
+        spaceId: string;
+        collectionId?: string;
+        resourceId?: string;
+        policy: PolicyDocument;
+    }): Promise<void>;
+    /**
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param [options.collectionId] {string}
+     * @param [options.resourceId] {string}
+     * @returns {Promise<void>}   idempotent (no error if absent)
+     */
+    deletePolicy({ spaceId, collectionId, resourceId }: {
+        spaceId: string;
+        collectionId?: string;
+        resourceId?: string;
+    }): Promise<void>;
+    /**
+     * Builds the on-disk path for a registered backend record: a
+     * `.backend.<backendId>.json` dot-file in the Space dir (the same per-file
+     * convention as `.policy.` / `.space.`). One file per backend id.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.backendId {string}
+     * @returns {string}
+     */
+    _backendFile({ spaceId, backendId }: {
+        spaceId: string;
+        backendId: string;
+    }): string;
+    /**
+     * Persists a full (secret-bearing) backend-registration record. Upsert.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.backendId {string}
+     * @param options.record {StoredBackendRecord}
+     * @returns {Promise<void>}
+     */
+    writeBackend({ spaceId, backendId, record }: {
+        spaceId: string;
+        backendId: string;
+        record: StoredBackendRecord;
+    }): Promise<void>;
+    /**
+     * Reads the full (secret-bearing) record for one backend, for internal use
+     * (existence checks, the future provider adapter). Resolves `undefined` when
+     * absent. The only method that exposes secret connection material.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.backendId {string}
+     * @returns {Promise<StoredBackendRecord|undefined>}
+     */
+    getBackend({ spaceId, backendId }: {
+        spaceId: string;
+        backendId: string;
+    }): Promise<StoredBackendRecord | undefined>;
+    /**
+     * Enumerates the Space's registered backends and returns them **sanitized**
+     * (each mapped through `sanitizeBackendRecord`, so the secret connection
+     * material never reaches the listing), sorted by id. An absent Space dir
+     * reports no registered backends rather than throwing.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @returns {Promise<BackendDescriptor[]>}
+     */
+    listBackends({ spaceId }: {
+        spaceId: string;
+    }): Promise<BackendDescriptor[]>;
+    /**
+     * Removes a registered backend record. Idempotent (no error if absent).
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.backendId {string}
+     * @returns {Promise<void>}
+     */
+    deleteBackend({ spaceId, backendId }: {
+        spaceId: string;
+        backendId: string;
+    }): Promise<void>;
+    /**
+     * WebKMS keystores (the `/kms` facet). A sibling tree to Spaces:
+     * `keystores/<localId>/` holds a keystore's `config.json` now, and its key
+     * records / revocations in later tracks -- hence a directory per keystore
+     * rather than a flat file.
+     *
+     * The directory holding one keystore's records, contained in `keystoresDir`.
+     * @param keystoreId {string}   the keystore's server-generated local id
+     * @returns {string}
+     */
+    _keystoreDir(keystoreId: string): string;
+    _keystoreConfigFile(keystoreId: string): string;
+    /**
+     * Persists a keystore config unconditionally (the create path -- local ids
+     * are server-generated random values, so create never collides). The
+     * sequence-gated update path is `updateKeystore`.
+     * @param options {object}
+     * @param options.keystoreId {string}   the keystore's local id
+     * @param options.config {KeystoreConfig}
+     * @returns {Promise<void>}
+     */
+    writeKeystore({ keystoreId, config }: {
+        keystoreId: string;
+        config: KeystoreConfig;
+    }): Promise<void>;
+    /**
+     * @param options {object}
+     * @param options.keystoreId {string}   the keystore's local id
+     * @returns {Promise<KeystoreConfig|undefined>}
+     *   Resolves falsy when the keystore does not exist (must not throw).
+     */
+    getKeystore({ keystoreId }: {
+        keystoreId: string;
+    }): Promise<KeystoreConfig | undefined>;
+    /**
+     * Replaces a keystore config, gated atomically (under the per-keystore write
+     * mutex) on: the keystore existing, `config.sequence` being exactly the
+     * stored sequence + 1, and `config.kmsModule` matching the stored one (the
+     * module is immutable). Any other state rejects with the protocol's single
+     * merged 409 conflict.
+     * @param options {object}
+     * @param options.keystoreId {string}   the keystore's local id
+     * @param options.config {KeystoreConfig}
+     * @returns {Promise<void>}
+     */
+    updateKeystore({ keystoreId, config }: {
+        keystoreId: string;
+        config: KeystoreConfig;
+    }): Promise<void>;
+    /**
+     * Every stored keystore config whose `controller` matches, sorted by local
+     * id (the request layer caps the wire result). An absent keystores root
+     * (nothing stored yet) resolves an empty list; a directory without a
+     * readable config file is skipped.
+     * @param options {object}
+     * @param options.controller {IDID}
+     * @returns {Promise<KeystoreConfig[]>}
+     */
+    listKeystoresByController({ controller }: {
+        controller: IDID;
+    }): Promise<KeystoreConfig[]>;
+    /**
+     * The file holding one key record, contained in its keystore's `keys/`
+     * subdirectory. The record is a plain JSON file (not a metadata store):
+     * records are immutable once inserted, so there is no read-modify-write to
+     * protect.
+     * @param options {object}
+     * @param options.keystoreId {string}   the owning keystore's local id
+     * @param options.localId {string}   the key's local id
+     * @returns {string}
+     */
+    _keyFile({ keystoreId, localId }: {
+        keystoreId: string;
+        localId: string;
+    }): string;
+    /**
+     * Inserts a key record, create-only: the exclusive-create write (`wx`)
+     * enforces the `(keystoreId, localId)` uniqueness atomically, rejecting a
+     * duplicate with the protocol's 409 (`KeyIdConflictError`).
+     * @param options {object}
+     * @param options.keystoreId {string}   the owning keystore's local id
+     * @param options.localId {string}   the key's local id
+     * @param options.record {KmsKeyRecord}   the full (secret-bearing) record
+     * @returns {Promise<void>}
+     */
+    insertKey({ keystoreId, localId, record }: {
+        keystoreId: string;
+        localId: string;
+        record: KmsKeyRecord;
+    }): Promise<void>;
+    /**
+     * @param options {object}
+     * @param options.keystoreId {string}   the owning keystore's local id
+     * @param options.localId {string}   the key's local id
+     * @returns {Promise<KmsKeyRecord|undefined>}
+     *   Resolves falsy when the key does not exist (must not throw).
+     */
+    getKey({ keystoreId, localId }: {
+        keystoreId: string;
+        localId: string;
+    }): Promise<KmsKeyRecord | undefined>;
+    /**
+     * Every stored key record under the keystore (`keys/*.json`), sorted by local
+     * id (the file name's stem). An absent keystore or `keys/` directory (no keys
+     * yet) resolves an empty list; a non-`.json` entry is skipped. The record is
+     * returned verbatim -- the at-rest cipher applies above the backend.
+     * @param options {object}
+     * @param options.keystoreId {string}   the owning keystore's local id
+     * @returns {Promise<Array<{ localId: string, record: KmsKeyRecord }>>}
+     */
+    listKeys({ keystoreId }: {
+        keystoreId: string;
+    }): Promise<Array<{
+        localId: string;
+        record: KmsKeyRecord;
+    }>>;
+    /**
+     * The file holding one zcap revocation record. For a keystore scope it lives
+     * in that keystore's `revocations/` subdirectory; for a Space scope it lives
+     * under the sibling `spaceRevocationsDir` root (NOT inside the Space dir --
+     * see the `spaceRevocationsDir` property doc). The file name folds the
+     * `(delegator, capabilityId)` unique key into a SHA-256 digest (the shared
+     * `revocationFileName` codec).
+     * @param options {object}
+     * @param options.scope {RevocationScope}   the owning keystore or Space
+     * @param options.delegator {string}   the revoked capability's delegator
+     * @param options.capabilityId {string}   the revoked capability's id
+     * @returns {string}
+     */
+    _revocationFile({ scope, delegator, capabilityId }: {
+        scope: RevocationScope;
+        delegator: string;
+        capabilityId: string;
+    }): string;
+    /**
+     * Inserts a revocation record, create-only: the exclusive-create write
+     * (`wx`) enforces the `(delegator, capability.id)` uniqueness atomically,
+     * rejecting a duplicate with the protocol's 409
+     * (`DuplicateRevocationError`).
+     * @param options {object}
+     * @param options.scope {RevocationScope}   the owning keystore or Space
+     * @param options.record {RevocationRecord}   the revocation to store
+     * @returns {Promise<void>}
+     */
+    insertRevocation({ scope, record }: {
+        scope: RevocationScope;
+        record: RevocationRecord;
+    }): Promise<void>;
+    /**
+     * True when any of the given capabilities has a stored, unexpired
+     * revocation under the scope (keystore or Space). A record past its
+     * `meta.expires` GC horizon is pruned on the way through and counts as not
+     * revoked -- the capability itself has expired, so verification already
+     * rejects it on expiry (this is the filesystem analogue of a TTL index).
+     * @param options {object}
+     * @param options.scope {RevocationScope}   the owning keystore or Space
+     * @param options.capabilities {CapabilitySummary[]}   the
+     *   `(capabilityId, delegator)` pairs to check
+     * @returns {Promise<boolean>}
+     */
+    isRevoked({ scope, capabilities }: {
+        scope: RevocationScope;
+        capabilities: CapabilitySummary[];
+    }): Promise<boolean>;
+}
+export {};
+//# sourceMappingURL=filesystem.d.ts.map