@3sln/trove 0.0.12 → 0.0.13

package/README.md

@@ -503,8 +503,11 @@ the same values as config fields instead.
 | `TROVE_JWT_ISSUER` / `_AUDIENCE` / `_ALGS` | — | claim checks after the signature passes |
 | `TROVE_AUTH_SERVER` | the JWT issuer | where refused clients are sent to sign in |
 | `TROVE_ADMINS` | — | comma-separated ids with whole-drive rights |
+| **rate limits** | | |
+| `TROVE_RATE_LIMIT` | on | `off` to meter nothing |
+| `TROVE_RATE_LIMIT_STORE` | `memory` | `kv` for one budget across instances (needed on Workers) |
+| `TROVE_RATE_LIMITS` | — | JSON per class, e.g. `{"search":{"limit":20,"windowMs":60000}}` |
 | **collections** | | |
-| `TROVE_COLLECTIONS` | on | `false` for one open store with no ACLs |
 | `TROVE_DEFAULT_OPEN` | `true` | **set `false`** before exposing it |
 | `TROVE_COLLECTION_CREATOR_ROLES` | — | roles allowed to create collections |
 | **agents** | | |
@@ -1193,8 +1196,17 @@ packages/
   plugin-sdk/   @3sln/trove/plugin-sdk — the iframe-side plugin API + RPC
   create-trove/ @3sln/create-trove — the scaffolder; the one directory that is
                 its own published package rather than part of @3sln/trove
+plugins/
+  audiobook/    a plugin we ship, built into a signed zip
 ```
 
+`plugins/` is a BUILD location rather than a workspace, and the difference is the point: a
+plugin's artifact is a zip the server independently re-parses and installs, never an npm
+dependency and never imported from `packages/`. `bun run build:plugins` produces the same
+bytes a user would drag into the install dialog — there is no privileged path for our own.
+Nothing there is preinstalled: a drive with a plugin its owner did not choose is a drive
+with a capability grant its owner did not make. See `plugins/README.md`.
+
 ## Releasing
 
 Two packages, one version:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@3sln/trove",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "type": "module",
   "description": "Trove — a self-hostable, plugin-extensible Google Drive. Semantic search, pluggable storage (S3 / filesystem / NAS), and a VS Code-style contribution system with sandboxed plugins.",
   "repository": {
@@ -41,6 +41,7 @@
   "scripts": {
     "dev": "web-dev-server --config packages/web/web-dev-server.config.mjs",
     "build:web": "cd packages/web && bun build.mjs",
+    "build:plugins": "bun plugins/build.mjs",
     "serve": "bun packages/server/src/adapters/bun.js",
     "serve:node": "node packages/server/src/adapters/node.js",
     "test": "bun test",

package/packages/core/src/collections/index.js

@@ -80,12 +80,59 @@ export class CollectionService {
       .sort((a, b) => (a.name || '').localeCompare(b.name || ''));
   }
 
+  // --- the same questions, asked of an API key ---------------------------------
+  //
+  // A key is authority that ARRIVED WITH THE REQUEST. There is nobody to look up in the
+  // ACL, and `principal` is null on a key request — so asking the principal side answers
+  // for the ANONYMOUS caller, which is wrong in both directions. On a locked drive a
+  // correctly-scoped key is told it can read nothing; on a `defaultOpen` drive the
+  // `anyone` grant lets a key scoped to one collection read and write every one of them.
+  //
+  // Decided from the key ALONE, never unioned with whatever session happens to be
+  // attached — the same rule engine/providers/access.js states for node and collection
+  // handles, and the reason a weak key cannot borrow a strong session.
+
+  /** The collections an API key may read. `list`'s twin. */
+  async listForGrant(grant) {
+    const rows = await this.kv.list(NS);
+    return rows
+      .map((r) => r.value)
+      .filter((c) => c && grant.can(c.id, 'read'))
+      .map((c) => this.describeForGrant(c, grant))
+      .sort((a, b) => (a.name || '').localeCompare(b.name || ''));
+  }
+
+  /** `assert`'s twin. Refuses with what the KEY lacks, not with what a user lacks. */
+  async assertForGrant(grant, collectionId, capability) {
+    const c = await this.get(collectionId);
+    if (!grant.can(collectionId, capability)) {
+      throw TroveError.forbidden(`This API key does not hold "${capability}" on collection "${c.name}"`);
+    }
+    return c;
+  }
+
+  /**
+   * `hasWholeDrive`'s twin: a key that can read and write every collection that exists.
+   *
+   * Same definition, so the answer does not depend on which credential asked — and it
+   * shrinks the moment a collection the key does not name is created, which is the safe
+   * direction. A `*`-scoped key satisfies it by construction. There is no admin-list
+   * shortcut, because a key is never a named admin: the drive-wide verbs that grant new
+   * power (minting keys, installing a server indexer) are gated by `requireHumanAdmin`
+   * and `isAdmin` and stay out of a key's reach entirely.
+   */
+  async grantHasWholeDrive(grant) {
+    const all = (await this.kv.list(NS)).map((r) => r.value).filter(Boolean);
+    if (!all.length) return false;
+    return all.every((c) => grant.can(c.id, 'read') && grant.can(c.id, 'write'));
+  }
+
   /**
    * The encryption settings for a collection, generating a key the first time.
    *
    * The key is generated, not derived from anything a user types. A passphrase would buy
-   * nothing: the server knows the key regardless — it hands it to clients and decrypts for
-   * indexers — so there is no protection to gain from the user holding it, and every cost
+   * nothing: the server knows the key regardless — it seals what arrives and decrypts what
+   * is read — so there is no protection to gain from the user holding it, and every cost
    * would still apply. A random 256-bit key cannot be forgotten, guessed, or shoulder-read,
    * and needs no prompt in front of the collection.
    *
@@ -117,9 +164,14 @@ export class CollectionService {
    * whole reason every object carries a fingerprint. Retiring a key is only safe once
    * nothing names it any more.
    *
-   * Server-side only. Callers are the transfer plans, which hand the right key to a client
-   * that may read the collection, and indexing, which decrypts to read content. Never
-   * reachable through `describe`.
+   * SERVER-SIDE ONLY, AND ITS RESULT MUST NEVER REACH A RESPONSE. That is the actual
+   * invariant and it was previously unstated — worse, contradicted, by comments describing
+   * a transfer plan that handed the key to a client. That trade came off (see
+   * `#planEncryption`, which answers `sealedBy: 'server'`): encrypted collections pass
+   * through the drive in both directions, and every call site of this is inside the server.
+   *
+   * Callers are sealing on the way in, decryption on the way out, indexing, and rotation.
+   * Not reachable through `describe`, which returns a fingerprint.
    *
    * @param {string} collectionId
    * @param {string} [fingerprint] which key; omitted means the current one
@@ -218,15 +270,24 @@ export class CollectionService {
 
   /** A safe, principal-scoped view (no secrets). */
   describe(c, principal) {
-    const caps = [...this.capabilities(principal, c)];
+    return this.#describe(c, this.capabilities(principal, c));
+  }
+
+  /** The same record, with the capabilities an API KEY holds rather than a principal's. */
+  describeForGrant(c, grant) {
+    return this.#describe(c, grant.capabilitiesFor(c.id));
+  }
+
+  #describe(c, held) {
+    const caps = [...held];
     return {
       id: c.id, name: c.name, description: c.description || '',
       driver: c.store?.driver, system: !!c.system,
       capabilities: caps, createdAt: c.createdAt,
-      // Safe to hand to anyone who can see the collection: the salt, the KDF parameters
-      // and the fingerprint are what turn a passphrase into the key, and are useless
-      // without the passphrase. Null when the collection is not encrypted, so a client
-      // never has to ask a second question to find out.
+      // `{ enabled, fingerprint, rules }` and nothing more — see describeEncryption. Safe
+      // to hand to anyone who can see the collection, because a fingerprint names a key
+      // without being it. Null when the collection is not encrypted, so a client never has
+      // to ask a second question to find out.
       encryption: describeEncryption(c.encryption),
     };
   }

package/packages/core/src/encryption/keys.js

@@ -3,8 +3,9 @@
 // The threat model is the STORAGE HOST, and only that: the bucket holds ciphertext, so a
 // leaked bucket credential, a public-bucket misconfiguration, or a storage vendor who is
 // not the compute vendor learns sizes and timestamps and no content. The server holds the
-// key — it has to, in order to hand it to a client and to decrypt for an indexer — so this
-// is explicitly not end-to-end and does not pretend to be.
+// key — it has to, in order to seal what arrives, decrypt what is read, and decrypt for an
+// indexer — so this is explicitly not end-to-end and does not pretend to be. The key does
+// not leave the server: a client sends and receives plaintext through the drive.
 //
 // Which is why the key is GENERATED rather than derived from something a user types.
 // A passphrase would buy nothing here: the server knows the key either way, so there is no
@@ -15,7 +16,7 @@
 // passphrase a person would choose.
 //
 // Access to the key is therefore an ACCESS-CONTROL question, not a knowledge one: whoever
-// may read the collection may have the key, because they may already read its contents.
+// may read the collection may read its contents, and the drive decrypts on their behalf.
 //
 // If this ever becomes end-to-end, the change is confined to where the key comes from and
 // who is allowed it. The envelope, the fingerprint, and every stored object are unchanged.

package/packages/core/src/encryption/policy.js

@@ -18,8 +18,8 @@ import { TroveError } from '../errors.js';
  * What a collection stores about its encryption.
  *
  * The fingerprint is safe to show anyone who may see the collection: it names the key
- * without being it. The key itself is never part of this — it reaches a client through a
- * transfer plan, which is authorized per operation.
+ * without being it. The key itself is never part of this, and never reaches a client at
+ * all — see `#planEncryption`, which answers `sealedBy: 'server'`.
  *
  * @typedef {object} EncryptionConfig
  * @property {boolean} enabled
@@ -95,12 +95,19 @@ export function shouldEncrypt(encryption, { name = '', contentType = '' } = {})
 }
 
 /**
- * What a client is told about a collection's encryption.
+ * What a client is told about a collection's encryption: `{ enabled, fingerprint, rules }`.
  *
- * Enough to know that objects here are sealed and which key seals them; never the key.
- * There is no "locked" state and nothing to prompt for — a client that may read the
- * collection is handed the key with the transfer plan, because being allowed to read the
- * contents and being allowed to decrypt them are the same permission.
+ * Enough to know that objects here are sealed and which key seals them. There is no salt
+ * and no KDF material, because there is no passphrase — the key is generated, and this
+ * comment used to explain why handing out the KDF parameters was safe, describing a design
+ * that no longer exists in the subsystem where being wrong is most expensive.
+ *
+ * A fingerprint names a key without being it, which is the whole reason it is safe to
+ * publish: it is what lets a stored object say which key opens it, and a client say which
+ * key a collection is currently on, without either of them holding one.
+ *
+ * There is no "locked" state and nothing to prompt for. The drive seals and unseals; a
+ * client never decrypts, so there is nothing it needs beyond knowing that it happens.
  */
 export function describeEncryption(encryption) {
   if (!encryption?.enabled) return null;

package/packages/core/src/encryption/rotation.js

@@ -23,9 +23,15 @@
 // on it — not when a counter says the job is done. A count can be wrong; a pass that finds
 // nothing cannot be. That also handles the awkward case of an object uploaded onto the old
 // key by a request that was in flight when the rotation started.
+//
+// WHICH IS ONLY SOUND IF THE PASS SEES EVERYTHING THE KEY OPENS. The trash keeps its
+// bytes, so a soft-deleted object is still sealed and still needs its key on the day
+// someone restores it. The walk therefore sources from `listSealed`, which spans live and
+// trashed, and not from `listItems`, which is live-only by design. Retiring on a pass over
+// a subset is not observation, it is a guess — and the guess destroys data silently.
 
 import { TroveError } from '../errors.js';
-import { encryptStream, decodeHeader } from './envelope.js';
+import { encryptStream, decodeHeader, HEADER_BYTES } from './envelope.js';
 import { fromHex, fingerprint, toHex } from './keys.js';
 
 const NS = 'rotations';
@@ -197,12 +203,16 @@ export class RotationService {
     }
 
     for (;;) {
-      const page = await this.vfs.metadata.listItems(collectionId, { cursor, limit: 50 });
+      // `listSealed`, NOT `listItems`: the trash keeps its bytes, so a trashed object is
+      // still sealed with the old key, and a walk that cannot see it would retire that key
+      // out from under every future restore. The store applies the sealed predicate too,
+      // so a mostly-plaintext collection is one page rather than hundreds to skip.
+      const page = await this.vfs.metadata.listSealed(collectionId, { cursor, limit: 50 });
       const items = page.items || [];
       for (const node of items) {
-        // Only encrypted items, and only ones not already on the current key. This is what
-        // makes re-running a slice free rather than destructive.
-        if (!node.encryption || node.encryption.fingerprint === state.to) continue;
+        // Only items not already on the current key. This is what makes re-running a slice
+        // free rather than destructive.
+        if (node.encryption.fingerprint === state.to) continue;
         sawStragglers = true;
         try {
           const r = await this.#moveSlice(node, key, fp, null, { deadline, now });
@@ -275,14 +285,13 @@ export class RotationService {
    */
   async #moveSlice(node, newKey, newFingerprint, inflight, { deadline, now }) {
     const storage = await this.vfs.storageFor(node.collectionId);
-    const chunkSize = node.encryption.chunkSize;
-    const plaintextSize = node.size;
+    const { plaintextSize, chunkSize } = await this.#geometryOf(node, storage);
 
     // A store without multipart is a local one — filesystem, memory — where the whole
     // object is already within reach. There is nothing to check point against, and nothing
     // that needs it: the budget that makes this necessary is a network one.
     if (!storage.capabilities?.multipart) {
-      await this.#moveWhole(node, newKey, newFingerprint, storage, chunkSize);
+      await this.#moveWhole(node, newKey, newFingerprint, storage, { plaintextSize, chunkSize });
       return { done: true, inflight: null };
     }
 
@@ -307,7 +316,7 @@ export class RotationService {
         const end = Math.min(start + chunksPerPart * chunkSize, plaintextSize) - 1;
         const last = end + 1 >= plaintextSize;
 
-        const read = await this.vfs.readStream(node.id, { range: { start, end } });
+        const read = await this.vfs.readNode(node, { range: { start, end } });
         const sealed = await encryptStream(newKey, read.stream, {
           fingerprint: newFingerprint,
           plaintextSize,
@@ -368,13 +377,38 @@ export class RotationService {
     return { done: true, inflight: null };
   }
 
+  /**
+   * The geometry of the object as the OBJECT states it.
+   *
+   * The Vfs already answers the authority question and answers it this way: the item's
+   * record says which key sealed it and at what chunk size, and that is what makes a
+   * listing cheap — but it is a copy, and a copy can be stale (restored from a backup,
+   * adopted by a scan, written by another version).
+   *
+   * The two arms here disagreed. The multipart arm took `node.size`; the whole-object arm
+   * took the envelope's, so which answer a drive got depended on whether its store supports
+   * multipart. A stale-LARGE `node.size` makes every slice raise "Expected N bytes…
+   * received M", so the rotation can never reach `done` and the old key is never retired; a
+   * stale-SMALL one seals a header that decrypts to the wrong length forever.
+   *
+   * One 44-byte read against a multi-megabyte transfer.
+   */
+  async #geometryOf(node, storage) {
+    const head = await storage.get(node.storageKey, { range: { start: 0, end: HEADER_BYTES - 1 } });
+    const header = decodeHeader(new Uint8Array(await new Response(head.stream).arrayBuffer()));
+    return {
+      plaintextSize: header.plaintextSize ?? node.size,
+      chunkSize: header.chunkSize ?? node.encryption.chunkSize,
+    };
+  }
+
   /** The whole object in one put, for a store that cannot do multipart. */
-  async #moveWhole(node, newKey, newFingerprint, storage, chunkSize) {
+  async #moveWhole(node, newKey, newFingerprint, storage, { plaintextSize, chunkSize }) {
     const nextKey = rotatedKey(node.storageKey);
-    const read = await this.vfs.readStream(node.id);
+    const read = await this.vfs.readNode(node);
     const sealed = await encryptStream(newKey, read.stream, {
       fingerprint: newFingerprint,
-      plaintextSize: read.size ?? node.size,
+      plaintextSize,
       chunkSize,
     });
     await storage.put(nextKey, new Uint8Array(await new Response(sealed).arrayBuffer()), {

package/packages/core/src/errors.js

@@ -118,6 +118,14 @@ export class TroveError extends Error {
   static forbidden(message = 'Forbidden', opts) {
     return new TroveError(ErrorCode.FORBIDDEN, message, opts);
   }
+  /**
+   * Rate limited — 429, and retryable, which is what tells it apart from being out of
+   * disk. See the constructor: QUOTA is 507 when it is NOT retryable, because telling a
+   * client to retry against a full volume sends it into a loop only a human can end.
+   */
+  static rateLimited(message, opts) {
+    return new TroveError(ErrorCode.QUOTA, message, { retryable: true, ...opts });
+  }
   static internal(message = 'Internal error', opts) {
     return new TroveError(ErrorCode.INTERNAL, message, opts);
   }

package/packages/core/src/index.js

@@ -60,7 +60,7 @@ export { TaskRegistry } from './tasks.js';
 export { IssueRegistry, issueId } from './issues.js';
 // Reconcile a collection against what its store actually holds (changes made outside Trove).
 export { CollectionScanner } from './scan.js';
-export { normalizeContribution, clampContribution, clampTagValue, DEFAULT_CAPS } from './indexers/contribution.js';
+export { clampContribution, clampTagValue, DEFAULT_CAPS } from './indexers/contribution.js';
 
 // Cloudflare Vectorize — first-class pluggable vector DB.
 export { VectorizeVectorStore } from './search/vectorize.js';
@@ -68,6 +68,12 @@ export { VectorizeVectorStore } from './search/vectorize.js';
 // Server-side key/value store (subscriptions, inboxes, profiles).
 export { KeyValueStore, MemoryKV, SqliteKV } from './kv.js';
 export { SignedUrls, resolveUrlSecret, URL_PURPOSES } from './signedUrls.js';
+// What one caller may cost, per class of work — see rateLimit.js for why classes rather
+// than one number, and for which runtimes can enforce a limit at all.
+export {
+  RateLimiter, MemoryRateStore, KvRateStore, rateSubject, describeRateLimits,
+  DEFAULT_RATE_LIMITS, RATE_CLASSES,
+} from './rateLimit.js';
 // API keys: capability without identity. CapabilityProvider is the injection point —
 // the counterpart to IdentityProvider, for credentials that say what rather than who.
 export {
@@ -91,7 +97,7 @@ export {
   normalizeServers, resolveAuthDiscovery, usableAuthServer, headerSafe,
 } from './identity/discovery.js';
 
-// Sidecar documents: conversations, tags, indexer facets (CRDT, cold-in-S3).
+// Sidecar documents: conversations, tags, subscriptions (CRDT, cold-in-S3).
 export { SidecarService, SidecarStore, SidecarManager } from './sidecar/index.js';
 export * as sidecarOps from './sidecar/document.js';
 

package/packages/core/src/indexers/contribution.js

@@ -8,11 +8,24 @@
 //   tags           filterable key/values, merged into the item's queryable tags
 //   metadata       arbitrary structured data (an audiobook's chapter index, …)
 //
-// Both halves of the contract live here because they must not drift: `normalize`
-// decides what the shape IS, and `clamp` decides how large it may be. They used to sit
-// in different modules — normalize in the indexing coordinator, clamp inside the plugin
-// isolate runtime — which meant the size limits only applied to one of the three
-// producers. The caps are a property of the contribution, not of whoever made it.
+// TWO SENSES OF "CONTRIBUTION", and this is the other one. Here it is per-node ENRICHMENT
+// produced at runtime and addressed by `contributorId`. The first sense lives in
+// core/src/plugins/contributions.js: an EXTENSION POINT declared in a manifest and
+// addressed by URI. A plugin declares an `indexer` contribution (that sense) which at
+// runtime produces contributions (this one).
+//
+// The rule: that sense is DECLARED, static, and named by URI; this one is PRODUCED, per
+// node, and named by contributor.
+//
+// `clampContribution` does the whole contract in one pass: it accepts the legacy
+// `{ documents, facet }` spelling, decides the canonical shape, and applies the caps. It
+// was two functions, and the second — `normalizeContribution` — had grown its own copy of
+// the legacy mapping, so both halves of a contract that exists here BECAUSE it must not
+// drift had drifted into both. At its only call site it could never see a legacy key,
+// because clamp had already mapped it; all it contributed was three defaults.
+//
+// The caps used to live in the plugin isolate runtime, which meant they applied to one of
+// the three producers. They are a property of the contribution, not of whoever made it.
 
 /** Output caps applied to every contribution, whatever produced it. */
 export const DEFAULT_CAPS = {
@@ -25,18 +38,6 @@ export const DEFAULT_CAPS = {
   maxMetadataBytes: 256 * 1024, // JSON-serialized metadata
 };
 
-/**
- * Normalize to the three canonical scopes, accepting the legacy `{ documents, facet }`
- * shape (documents→semanticTexts, facet→metadata).
- */
-export function normalizeContribution(c = {}) {
-  return {
-    semanticTexts: c.semanticTexts || c.documents || [],
-    tags: c.tags || null,
-    metadata: c.metadata || c.facet || null,
-  };
-}
-
 /**
  * Clamp a contribution to `caps`, dropping (not erroring on) whatever exceeds them.
  *

package/packages/core/src/indexing.js

@@ -11,7 +11,7 @@
 
 import { TroveError } from './errors.js';
 import { readAll } from './util.js';
-import { normalizeContribution, clampContribution, DEFAULT_CAPS } from './indexers/contribution.js';
+import { clampContribution, DEFAULT_CAPS } from './indexers/contribution.js';
 
 export class IndexingCoordinator {
   /**
@@ -61,7 +61,11 @@ export class IndexingCoordinator {
    * the one most exposed to untrusted code.
    */
   async #applyContribution(nodeId, contributorId, contribution) {
-    const { semanticTexts, tags, metadata } = normalizeContribution(clampContribution(contribution, this.caps));
+    // `clamp` alone. It already maps the legacy `documents`/`facet` keys itself, so
+    // `normalize` at this call site can never see one — all it contributed was three
+    // defaults, while contribution.js's header says both halves live there because they
+    // must not drift. They had already drifted into both functions.
+    const { semanticTexts = [], tags = null, metadata = null } = clampContribution(contribution, this.caps);
     // ALWAYS write the search half, including when it is empty. `indexDocuments` clears
     // this (node, contributor)'s prior docs before it writes, so passing [] is how you
     // say "this contributor has nothing to say about this node any more". Skipping the
@@ -75,7 +79,7 @@ export class IndexingCoordinator {
     // with no scopes at all is that contributor withdrawing, so its facets go too,
     // rather than leaving an excerpt describing content that no longer exists.
     if (tags || metadata) await this.metadata.setContribution(nodeId, contributorId, { tags, metadata });
-    else if (!semanticTexts.length) await this.metadata.clearContribution?.(nodeId, contributorId);
+    else if (!semanticTexts.length) await this.metadata.clearContribution(nodeId, contributorId);
   }
 
   /** Clear this contributor's search entries for a node (an empty re-index). */
@@ -257,7 +261,7 @@ export class IndexingCoordinator {
     // can't count leaves this null, and the caller shows an indeterminate indicator —
     // which is the right answer. Inventing a total would produce a progress bar that
     // lies, and that is worse than a spinner.
-    const total = await this.metadata.countItems?.().catch(() => null) ?? null;
+    const total = await this.metadata.countItems().catch(() => null) ?? null;
     let indexed = 0;
     let failed = 0;
     let afterId = null;

package/packages/core/src/issues.js

@@ -76,6 +76,14 @@ export class IssueRegistry {
    */
   async raise(spec) {
     if (!spec?.kind || !spec?.title) throw TroveError.invalid('An issue needs a kind and a title');
+    // A `retry` that is not `{ op }` is silently un-retryable: `canRetry` reads
+    // `issue.retry.op`, so a bare string answers false, the route reports
+    // `retryable: false`, and no button ever renders. That happened — the sidecar-flush
+    // issue passed `retry: 'sidecar-flush'` and its own comment two lines above asserted a
+    // handler was registered for it. Caught at the raise, where the mistake is.
+    if (spec.retry != null && typeof spec.retry?.op !== 'string') {
+      throw TroveError.invalid('An issue\u2019s `retry` must be { op } — a bare string is not retryable');
+    }
     const id = issueId(spec.kind, spec.subject);
     const existing = await this.kv.get(NS, id);
     const at = this.now();

package/packages/core/src/links.js

@@ -32,8 +32,10 @@ export const TROVE_SCHEME = 'trove:';
 // rather than storing kilobytes that will never match.
 const MAX_SELECTOR = 255;
 // How many distinct links one item may record. A document is a grouping, not a database
-// dump; past this the value is in the search index, not the link graph.
-export const MAX_LINKS_PER_ITEM = 500;
+// dump; past this the value is in the search index, not the link graph. Not exported: it
+// is the default for `extractTroveLinks`'s `limit`, and nothing outside chose a different
+// one — an exported cap nobody passes reads as a knob when it is a constant.
+const MAX_LINKS_PER_ITEM = 500;
 
 // Collection ids are slugs (see CollectionService); a name is anything but a slash,
 // since the pathname shorthand has to stop somewhere.
@@ -81,6 +83,18 @@ export function isTroveUri(uri) {
   return parseTroveUri(uri) != null;
 }
 
+/**
+ * The canonical string for one address. The ONE place the template lives.
+ *
+ * There were five hand-written copies of it, which is five chances to get the encoding or
+ * the separator subtly different — and `canonicalTroveUri`, whose whole docstring is
+ * "two links that address the same item by the same selector must produce the same
+ * string", was one of the copies rather than the source.
+ */
+export function formatTroveUri({ collection, by, value }) {
+  return `${TROVE_SCHEME}${collection}?${by}=${encodeURIComponent(value)}`;
+}
+
 /**
  * Build a `trove:` URI. `by` defaults to 'name' — the legible form, which is what
  * gets written into documents; pass 'id' for a link that must survive a rename.
@@ -89,10 +103,10 @@ export function troveUri(node, by = 'name') {
   const collection = node?.collectionId || 'default';
   if (by === 'id') {
     if (!node?.id) throw TroveError.invalid('trove: link by id needs a node id');
-    return `${TROVE_SCHEME}${collection}?id=${encodeURIComponent(node.id)}`;
+    return formatTroveUri({ collection, by: 'id', value: node.id });
   }
   if (!node?.name) throw TroveError.invalid('trove: link by name needs a node name');
-  return `${TROVE_SCHEME}${collection}?name=${encodeURIComponent(node.name)}`;
+  return formatTroveUri({ collection, by: 'name', value: node.name });
 }
 
 /**
@@ -114,7 +128,7 @@ export function extractTroveLinks(text, { limit = MAX_LINKS_PER_ITEM } = {}) {
     const raw = m[0].replace(/[.,;:!?]+$/, '');
     const parsed = parseTroveUri(raw);
     if (!parsed) continue;
-    const canonical = `${TROVE_SCHEME}${parsed.collection}?${parsed.by}=${encodeURIComponent(parsed.value)}`;
+    const canonical = formatTroveUri(parsed);
     if (seen.has(canonical)) continue;
     seen.add(canonical);
     out.push({ uri: canonical, raw, ...parsed });
@@ -129,7 +143,7 @@ export function extractTroveLinks(text, { limit = MAX_LINKS_PER_ITEM } = {}) {
  */
 export function canonicalTroveUri(uri) {
   const p = parseTroveUri(uri);
-  return p ? `${TROVE_SCHEME}${p.collection}?${p.by}=${encodeURIComponent(p.value)}` : null;
+  return p ? formatTroveUri(p) : null;
 }
 
 /** Both canonical forms an item can be addressed by — what a backlink query looks for. */
@@ -220,7 +234,5 @@ export function parseShareUrl(url) {
 export function troveUriFromShareUrl(url) {
   const parsed = parseShareUrl(url);
   if (!parsed) return null;
-  return parsed.by === 'id'
-    ? `${TROVE_SCHEME}${parsed.collection}?id=${encodeURIComponent(parsed.value)}`
-    : `${TROVE_SCHEME}${parsed.collection}?name=${encodeURIComponent(parsed.value)}`;
+  return formatTroveUri(parsed);
 }

package/packages/core/src/metadata/interface.js

@@ -165,6 +165,28 @@ export class MetadataStore {
   async trashedStorageKeys(collectionId) {
     throw TroveError.unsupported('trashedStorageKeys not implemented');
   }
+  /**
+   * Every SEALED item in a collection, live AND trashed, paged by (name, id).
+   *
+   * Key rotation is the caller, and it cannot use `listItems` for the same reason the
+   * scanner cannot: that is live-only by design, while the Vfs deliberately keeps the
+   * BYTES of a soft-deleted item so a restore can bring it back. A rotation that walks
+   * only live items completes a pass having never looked at the trash, retires the old
+   * key on the strength of it, and every trashed object still sealed with that key
+   * becomes permanently unopenable — the restore fails, forever. Retiring by observation
+   * is only sound if the observation covers everything the key still opens.
+   *
+   * Sealed-only because that is the entire set a rotation can act on, and applying the
+   * predicate in the store means a mostly-plaintext collection is one page rather than
+   * hundreds of pages of items to skip.
+   *
+   * @param {string} collectionId
+   * @param {{limit?: number, cursor?: string}} [opts]
+   * @returns {Promise<{items: object[], nextCursor: string|null}>}
+   */
+  async listSealed(collectionId, opts) {
+    throw TroveError.unsupported('listSealed not implemented');
+  }
   /** Rename an item. Rejects ALREADY_EXISTS if the name is taken in its collection. */
   async rename(id, newName) {
     throw TroveError.unsupported('rename not implemented');

package/packages/core/src/metadata/memory.js

@@ -153,6 +153,21 @@ export class MemoryStore extends MetadataStore {
     return keys;
   }
 
+  async listSealed(collectionId = 'default', opts = {}) {
+    // `this.nodes` rather than `#live()`, deliberately — see the interface docblock. The
+    // trash is the half of the key's working set that `listItems` cannot see.
+    const items = [...this.nodes.values()].filter((n) => n.collectionId === collectionId && n.encryption);
+    items.sort((a, b) => compareForSort(a, b, 'name', 1));
+    const limit = opts.limit ?? 500;
+    const at = decodeCursor('name', opts.cursor);
+    const rest = at ? items.filter((n) => afterCursor(n, 'name', at, false)) : items;
+    const page = rest.slice(0, limit);
+    return {
+      items: page.map(clone),
+      nextCursor: rest.length > limit ? encodeCursor('name', page[page.length - 1]) : null,
+    };
+  }
+
   async trashedBefore(cutoff, limit = 500) {
     return [...this.nodes.values()]
       .filter((n) => n.deletedAt && n.deletedAt < cutoff)

package/packages/core/src/metadata/sqlite.js

@@ -208,7 +208,6 @@ export class SqliteStore extends MetadataStore {
     );
     return rows.map(row);
   }
-  /** Items trashed before `cutoff` — what the purge sweep collects. */
   async trashedStorageKeys(collectionId) {
     const rows = await this.db.all(
       'SELECT storageKey FROM nodes WHERE collectionId = ? AND deletedAt IS NOT NULL AND storageKey IS NOT NULL',
@@ -217,6 +216,29 @@ export class SqliteStore extends MetadataStore {
     return new Set(rows.map((r) => r.storageKey));
   }
 
+  async listSealed(collectionId = 'default', opts = {}) {
+    // No `deletedAt IS NULL`, deliberately — see the interface docblock. The trash is the
+    // half of the key's working set that `listItems` cannot see.
+    const limit = opts.limit ?? 500;
+    const at = decodeCursor('name', opts.cursor);
+    // The same keyset shape and the same NOCASE expression `listItems` uses, so a cursor
+    // means the same thing here and the page boundary lines up with the ordering.
+    const where = at ? 'AND (name COLLATE NOCASE > ? OR (name COLLATE NOCASE = ? AND id > ?))' : '';
+    const args = at ? [at.value, at.value, at.id] : [];
+    const rows = await this.db.all(
+      `SELECT * FROM nodes WHERE collectionId = ? AND encryption IS NOT NULL ${where}
+       ORDER BY name COLLATE NOCASE ASC, id ASC
+       LIMIT ?`,
+      collectionId, ...args, limit + 1,
+    );
+    const hasMore = rows.length > limit;
+    const page = rows.slice(0, limit).map(row);
+    return {
+      items: page,
+      nextCursor: hasMore ? encodeCursor('name', page[page.length - 1]) : null,
+    };
+  }
+
   async trashedBefore(cutoff, limit = 500) {
     const rows = await this.db.all(
       'SELECT * FROM nodes WHERE deletedAt IS NOT NULL AND deletedAt < ? ORDER BY deletedAt ASC LIMIT ?',