@3sln/trove 0.0.2

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

@@ -0,0 +1,225 @@
+// PluginService — server-side install lifecycle for account-scoped plugins. Holds the
+// pluggable PackageStore (blobs) + PluginInstallStore (records), re-parses uploaded
+// packages, enforces the scope/authz gate (admin required for server indexers or
+// shared resources), and is the authority for capability checks on plugin API calls.
+//
+// Device-scoped plugins (pure client capabilities) never reach here — they live only
+// in the browser. Anything with a server footprint installs through this.
+
+import { TroveError } from '../errors.js';
+import { parsePluginPackage } from './package.js';
+
+export { PackageStore, StoragePackageStore } from './packageStore.js';
+export { PluginInstallStore, SqlitePluginInstallStore, MemoryPluginInstallStore } from './installStore.js';
+export { parsePluginPackage, capabilityList, ALL_CAPABILITIES, serverIndexers, declaredOpeners, declaredContributions } from './package.js';
+export * from './identity.js';
+export { CONTRIBUTION_TYPES, contributionsOfType } from './contributions.js';
+export { IndexerRuntime, InProcessIndexerRuntime } from './runtime.js';
+export { clampContribution, DEFAULT_CAPS } from '../indexers/contribution.js';
+export { PluginIndexers, matchFromSelector } from './indexers.js';
+
+// The account a principal installs into. Per-user for now; a workspace/org model can
+// override this later without touching call sites.
+function accountOf(principal) {
+  if (!principal) throw TroveError.unauthorized('Authentication required');
+  return principal.id;
+}
+
+export class PluginService {
+  /**
+   * @param {object} deps
+   * @param {import('./packageStore.js').PackageStore} deps.packages
+   * @param {import('./installStore.js').PluginInstallStore} deps.installs
+   * @param {(principal:object)=>boolean} [deps.isAdmin]
+   * @param {number} [deps.maxPackageBytes]
+   * @param {import('./indexers.js').PluginIndexers} [deps.indexers] activate/deactivate server indexers
+   */
+  constructor({ packages, installs, isAdmin, indexers = null, maxPackageBytes = 32 * 1024 * 1024, strict = false } = {}) {
+    this.packages = packages;
+    this.installs = installs;
+    this._isAdmin = isAdmin || (() => false);
+    this.indexers = indexers; // PluginIndexers coordinator, or null when indexers are disabled
+    this.maxPackageBytes = maxPackageBytes;
+    // strict = deny a plugin API call when there's no server install record. Off by
+    // default so plugins installed before server-installs existed keep working; a
+    // deployment flips it on (once its clients have re-uploaded) to fully close the
+    // "any client can name any pluginId" gap.
+    this.strict = strict;
+  }
+  async init() {
+    await this.installs?.init?.();
+    // Re-register every installed server indexer into the pipeline (no backfill — the
+    // files were indexed when installed; this just restores the live-upload hooks).
+    if (this.indexers && this.installs?.all) {
+      const records = (await this.installs.all()).filter((r) => r.indexers?.length);
+      if (records.length) await this.indexers.activateAll(records);
+    }
+  }
+
+  /** Whether a package needs admin approval: ships server code, or touches shared state. */
+  requiresAdmin(pkg) {
+    return (pkg.indexers && pkg.indexers.length > 0) || !!pkg.sharedStorage;
+  }
+
+  /**
+   * Install (account scope). `bytes` is the raw package zip. `grants` is the caps the
+   * user approved (defaults to all declared). Re-validates server-side, gates on scope,
+   * stores the blob (deduped by digest) + the install record.
+   */
+  async install({ principal, bytes, grants }) {
+    const account = accountOf(principal);
+    if (bytes.byteLength > this.maxPackageBytes) throw TroveError.invalid('Package exceeds the maximum size');
+    const pkg = await parsePluginPackage(bytes);
+    const granted = (grants || pkg.capabilities).filter((c) => pkg.capabilities.includes(c));
+
+    if (this.requiresAdmin(pkg) && !this._isAdmin(principal)) {
+      throw TroveError.forbidden('This plugin ships server components or uses shared resources and needs an administrator to install it');
+    }
+    // Refuse server-indexer plugins when this deployment has no indexer runtime.
+    if (pkg.indexers.length && !this.indexers) {
+      throw TroveError.unsupported('Server indexers are disabled on this deployment');
+    }
+
+    const version = pkg.manifest.version || '0';
+    // CONTENT-addressed. The ref used to be `<account>/<pluginId>/<version>.zip`, written
+    // only when absent — so re-installing at the same version (the ordinary way to
+    // iterate on a plugin) stored the new digest, the new grants and the new indexer
+    // specs against the OLD bytes, and every device that synced the package got the old
+    // code forever. Worse for a server indexer, whose entry modules are loaded from the
+    // ref while the record advertises the new manifest's. Bumping the version instead
+    // just leaked the previous blob.
+    const prev = await this.installs.get(account, pkg.pluginId);
+    const digestPart = String(pkg.digest).replace(/^sha256:/, '').slice(0, 32);
+    const ref = `${encodeURIComponent(account)}/${encodeURIComponent(pkg.pluginId)}/${digestPart}.zip`;
+    if (!(await this.packages.has(ref))) await this.packages.put(ref, bytes);
+
+    const record = {
+      account, pluginId: pkg.pluginId, version,
+      scope: 'account', grants: granted, indexers: pkg.indexers, // full specs (id/match/entry/dir)
+      config: {}, secrets: {},
+      installedBy: principal.id, adminApprovedBy: this.requiresAdmin(pkg) ? principal.id : null,
+      // Whether the SHARED domain store was actually approved. Computed at install
+      // (it is what makes the package admin-only) and never written down, so the
+      // runtime check in /api/plugins/:id/sql had nothing to consult: a plugin that
+      // declared plain `storage: true`, needing no admin at all, could then open
+      // `scope: "domain"` and reach its vendor's shared database.
+      sharedStorage: !!pkg.sharedStorage,
+      packageRef: ref, digest: pkg.digest, createdAt: Date.now(), updatedAt: Date.now(),
+    };
+    await this.installs.put(record);
+    // The bytes the previous install pointed at are now unreferenced — unless another
+    // account installed the identical package, which is what countByDigest answers.
+    if (prev?.packageRef && prev.packageRef !== ref && !(await this.#refIsShared(prev.packageRef, account))) {
+      await this.packages.delete(prev.packageRef).catch(() => {});
+    }
+    // Register + backfill any server indexers this package ships.
+    if (this.indexers && pkg.indexers.length) {
+      try { await this.indexers.activate(record); }
+      catch (err) { console.error(`activating indexers for ${record.pluginId} failed:`, err.message); }
+    }
+    return this.#publicRecord(record);
+  }
+
+  /** An account's installed plugins (secrets stripped). */
+  async list(principal) {
+    return (await this.installs.list(accountOf(principal))).map((r) => this.#publicRecord(r));
+  }
+  async get(principal, pluginId) {
+    const r = await this.installs.get(accountOf(principal), pluginId);
+    return r ? this.#publicRecord(r) : null;
+  }
+
+  /** Download the package blob (for a device to sync + enable). */
+  async getPackage(principal, pluginId) {
+    const r = await this.installs.get(accountOf(principal), pluginId);
+    if (!r) throw TroveError.notFound('Plugin');
+    return this.packages.get(r.packageRef);
+  }
+
+  /** Remove: drop the record, then the blob if no other install shares its digest. */
+  async remove(principal, pluginId) {
+    const account = accountOf(principal);
+    const r = await this.installs.get(account, pluginId);
+    if (!r) return { ok: true, removed: null };
+    // Unregister + purge server indexers before dropping the record/blob they load from.
+    if (this.indexers && r.indexers?.length) {
+      try { await this.indexers.deactivate(r); }
+      catch (err) { console.error(`deactivating indexers for ${pluginId} failed:`, err.message); }
+    }
+    await this.installs.delete(account, pluginId);
+    // Refs embed the ACCOUNT, so two accounts holding the same digest hold two distinct
+    // blobs — a global digest count said "someone still has it" and left this one behind
+    // with nothing that would ever reference it again. Ask about the blob we actually
+    // hold, not about its contents.
+    if (r.packageRef && !(await this.#refIsShared(r.packageRef, account))) {
+      await this.packages.delete(r.packageRef).catch(() => {});
+    }
+    return { ok: true, removed: pluginId, indexers: (r.indexers || []).map((i) => i.id || i) };
+  }
+
+  /**
+   * Authoritative capability check for a plugin API call. If the plugin is
+   * server-installed, its granted caps are enforced. Transitional: with no server
+   * install record we allow (device-installed plugins predate this and haven't
+   * migrated); once the client account-install flow lands this becomes deny-by-default.
+   */
+  /**
+   * Is this plugin installed on this account at all?
+   *
+   * Deliberately separate from `assertCapability`, because the two questions are not
+   * the same and only one of them is transitional. Whether a plugin holds a GRANT can
+   * fall back to allow while device-installed plugins migrate. Whether a caller may act
+   * AS a plugin cannot: writing under `trove+contrib:vendor.com/plugin/…`, or opening a
+   * vendor's shared domain store, is a claim on somebody else's identity, and index
+   * contributions carry into search results and tag mirrors that other people in the
+   * collection see. No record, no identity — in strict mode and out of it.
+   */
+  async assertInstalled(principal, pluginId) {
+    const r = await this.installs.get(accountOf(principal), pluginId);
+    if (!r) throw TroveError.forbidden(`Plugin "${pluginId}" is not installed on this account`);
+    return r;
+  }
+
+  /**
+   * May this plugin open its vendor's SHARED domain store?
+   *
+   * Only if it declared that scope, which is what made the package admin-gated in the
+   * first place. Declaring plain `storage: true` installs without an admin — and used
+   * to reach the domain scope anyway, because nothing recorded which of the two had
+   * been approved.
+   */
+  async assertSharedStorage(principal, pluginId) {
+    const r = await this.assertInstalled(principal, pluginId);
+    if (!r.sharedStorage) {
+      throw TroveError.forbidden(
+        `Plugin "${pluginId}" did not declare shared (domain) storage, so it cannot open it`,
+      );
+    }
+    return r;
+  }
+
+  async assertCapability(principal, pluginId, cap) {
+    const r = await this.installs.get(accountOf(principal), pluginId);
+    if (!r) {
+      if (this.strict) throw TroveError.forbidden(`Plugin "${pluginId}" is not installed on this account`);
+      return; // transitional allow
+    }
+    // `|| []` denies rather than throws on a record with no grants field. A record that
+    // cannot say what it was granted was granted nothing.
+    if (!(r.grants || []).includes(cap)) {
+      throw TroveError.forbidden(`Plugin "${pluginId}" was not granted the "${cap}" capability`);
+    }
+  }
+
+  /** Does any remaining install still point at this exact blob? */
+  async #refIsShared(packageRef, exceptAccount) {
+    if (!this.installs.all) return false;
+    const all = await this.installs.all();
+    return all.some((r) => r.packageRef === packageRef && r.account !== exceptAccount);
+  }
+
+  #publicRecord(r) {
+    const { secrets, ...rest } = r; // never expose secrets over the API
+    return rest;
+  }
+}

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

@@ -0,0 +1,142 @@
+// PluginIndexers — bridges installed plugin *indexer sub-packages* into the Vfs
+// indexing pipeline. When an account installs (or, at startup, re-activates) a plugin
+// that ships server indexers, this:
+//   1. resolves each indexer's bundle from the PackageStore blob,
+//   2. registers it into the Vfs IndexerRegistry (so it auto-runs on every upload),
+//   3. backfills it over existing files.
+// On uninstall it unregisters and purges the indexer's contributions.
+//
+// Execution goes through the injected IndexerRuntime, which is the isolation seam:
+// tests/first-party use the in-process runtime; a deployment can swap an isolate one.
+
+import { unzipSync } from 'fflate';
+import { readAll, selectorMatches } from '../util.js';
+
+export class PluginIndexers {
+  /**
+   * @param {object} deps
+   * @param {import('../vfs.js').Vfs} deps.vfs
+   * @param {import('./runtime.js').IndexerRuntime} deps.runtime
+   * @param {import('./packageStore.js').PackageStore} deps.packages
+   */
+  constructor({ vfs, runtime, packages }) {
+    this.vfs = vfs;
+    this.runtime = runtime;
+    this.packages = packages;
+    this._bundles = new Map(); // packageRef -> Promise<Record<path, Uint8Array>>
+    this._active = new Map(); // `${account}\0${indexerId}` -> unregister fn
+  }
+
+  /**
+   * Register + backfill every indexer a record declares. Idempotent per (account,
+   * indexer id): a re-activate replaces the prior registration. Records without server
+   * indexers are a no-op.
+   */
+  async activate(record, { backfill = true } = {}) {
+    const specs = record.indexers || [];
+    // Retire anything this plugin used to declare and no longer does. Both this and
+    // deactivate() iterated only the record in hand, so an indexer dropped by an
+    // upgrade stayed registered — running code the user upgraded away from on every
+    // upload, served from the in-memory bundle cache even after the blob was deleted —
+    // and its contributions were orphaned in the index for good.
+    const keep = new Set(specs.map((s) => s?.id).filter(Boolean));
+    for (const id of this.#idsFor(record.account, record.pluginId)) {
+      if (keep.has(id)) continue;
+      this._active.get(this.#key(record.account, id))?.();
+      this._active.delete(this.#key(record.account, id));
+      try { await this.vfs.purgeIndexer(id); }
+      catch (err) { console.error(`purge for retired indexer ${id} failed:`, err.message); }
+    }
+    for (const spec of specs) {
+      if (!spec?.id) continue;
+      const key = this.#key(record.account, spec.id);
+      // Build BEFORE dropping the previous registration. Dropping first meant a
+      // transient package-read failure left a previously-working indexer unregistered
+      // while the install still reported success — and #loadPackage caches the rejected
+      // promise, so it never recovered without a restart.
+      const indexer = await this.#buildIndexer(record, spec);
+      this._active.get(key)?.();
+      const unregister = this.vfs.indexers.register(indexer);
+      this._active.set(key, unregister);
+      if (backfill) {
+        try { await this.vfs.backfillIndexer(indexer); }
+        catch (err) { console.error(`backfill for indexer ${spec.id} failed:`, err.message); }
+      }
+    }
+    return specs.length;
+  }
+
+  /** Unregister + purge every indexer a record declared. */
+  async deactivate(record) {
+    for (const spec of record.indexers || []) {
+      if (!spec?.id) continue;
+      const key = this.#key(record.account, spec.id);
+      this._active.get(key)?.();
+      this._active.delete(key);
+      try { await this.vfs.purgeIndexer(spec.id); }
+      catch (err) { console.error(`purge for indexer ${spec.id} failed:`, err.message); }
+    }
+  }
+
+  /** Which indexer ids this account currently has registered for one plugin. */
+  #idsFor(account, pluginId) {
+    const prefix = `${account}\0`;
+    const out = [];
+    for (const key of this._active.keys()) {
+      if (!key.startsWith(prefix)) continue;
+      const id = key.slice(prefix.length);
+      // Contribution URIs are `trove+contrib:<domain>/<name>/<contribution>`.
+      if (pluginId && !id.includes(`:${pluginId}/`)) continue;
+      out.push(id);
+    }
+    return out;
+  }
+
+  /** Re-activate all installed indexers across accounts at startup (no backfill). */
+  async activateAll(records, opts = {}) {
+    let n = 0;
+    for (const record of records) n += await this.activate(record, { backfill: false, ...opts });
+    return n;
+  }
+
+  #key(account, id) { return `${account}\0${id}`; }
+
+  /**
+   * An indexer is an ENTRY MODULE inside the plugin's one package — not a nested
+   * sub-package — so it shares code with the rest of the plugin. The bundle handed to
+   * the runtime is therefore the whole package, and `spec.entry` names which module to
+   * run (e.g. "src/indexers/pdf.js").
+   */
+  async #buildIndexer(record, spec) {
+    const files = await this.#loadPackage(record.packageRef);
+    const entry = spec.entry;
+    const match = matchFromSelector(spec.match);
+    const runtime = this.runtime;
+    const runSpec = { id: spec.id, entry, files, cacheKey: `${record.digest || record.packageRef}\0${spec.id}` };
+    return {
+      id: spec.id,
+      displayName: spec.title || spec.name || spec.id,
+      match,
+      index: (node, ctx) => runtime.run(runSpec, node, { ...ctx, config: record.config || {}, secrets: record.secrets || {} }),
+    };
+  }
+
+  #loadPackage(ref) {
+    let p = this._bundles.get(ref);
+    if (!p) {
+      p = this.packages.get(ref).then(async ({ stream }) => unzipSync(await readAll(stream)));
+      // Never cache a REJECTION. A transient read failure otherwise poisoned this ref
+      // for the life of the process: every later activate got the same rejected promise
+      // back and the indexer could not be brought up again without a restart.
+      p.catch(() => this._bundles.delete(ref));
+      this._bundles.set(ref, p);
+    }
+    return p;
+  }
+}
+
+/** Turn an indexer `match` selector into a node predicate (shared matcher). */
+export function matchFromSelector(sel = {}) {
+  return (node) => selectorMatches(sel, node);
+}
+

package/packages/core/src/plugins/installStore.js

@@ -0,0 +1,134 @@
+// PluginInstallStore — the bookkeeping half of server plugin installs: which
+// packages an account has installed, at what version, with which capabilities
+// granted, plus config/secrets and the PackageStore ref. Small and queryable, so it
+// lives in the shared SQLite provider (a `plugin_installs` table) rather than the
+// bulk blob store. A memory impl backs tests / provider-less use.
+
+import { TroveError } from '../errors.js';
+
+const COLS = ['account', 'pluginId', 'version', 'scope', 'grants', 'indexers', 'config', 'secrets', 'installedBy', 'adminApprovedBy', 'packageRef', 'digest', 'createdAt', 'updatedAt'];
+
+export class PluginInstallStore {
+  async init() {}
+  /** Upsert a record by (account, pluginId). */
+  async put(record) { throw TroveError.unsupported('PluginInstallStore.put'); }
+  /** @returns {Promise<object|null>} */
+  async get(account, pluginId) { throw TroveError.unsupported('PluginInstallStore.get'); }
+  /** @returns {Promise<object[]>} an account's installs. */
+  async list(account) { throw TroveError.unsupported('PluginInstallStore.list'); }
+  /** @returns {Promise<object[]>} every install across all accounts (startup sweep). */
+  async all() { throw TroveError.unsupported('PluginInstallStore.all'); }
+  async delete(account, pluginId) { throw TroveError.unsupported('PluginInstallStore.delete'); }
+  /** How many installs reference a blob digest (for dedupe on blob delete). */
+  async countByDigest(digest) { throw TroveError.unsupported('PluginInstallStore.countByDigest'); }
+}
+
+// --- SQLite (shared provider) ------------------------------------------------
+
+const JSON_FIELDS = new Set(['grants', 'indexers', 'config', 'secrets']);
+
+export class SqlitePluginInstallStore extends PluginInstallStore {
+  constructor({ provider, key = 'plugins' } = {}) {
+    super();
+    this._opts = { provider, key };
+    this.db = null;
+  }
+  async init() {
+    if (this.db) return;
+    if (!this._opts.provider) throw TroveError.invalid('SqlitePluginInstallStore needs a provider');
+    this.db = await this._opts.provider.obtain({ key: this._opts.key });
+    await this.db.exec(`
+      CREATE TABLE IF NOT EXISTS plugin_installs (
+        account TEXT NOT NULL,
+        pluginId TEXT NOT NULL,
+        version TEXT,
+        scope TEXT,
+        grants TEXT NOT NULL DEFAULT '[]',
+        indexers TEXT NOT NULL DEFAULT '[]',
+        config TEXT NOT NULL DEFAULT '{}',
+        secrets TEXT NOT NULL DEFAULT '{}',
+        installedBy TEXT,
+        adminApprovedBy TEXT,
+        packageRef TEXT,
+        digest TEXT,
+        createdAt INTEGER NOT NULL,
+        updatedAt INTEGER NOT NULL,
+        PRIMARY KEY (account, pluginId)
+      );
+      CREATE INDEX IF NOT EXISTS idx_plugin_installs_digest ON plugin_installs(digest);
+    `);
+  }
+  async put(record) {
+    const r = normalize(record);
+    await this.db.run(
+      `INSERT INTO plugin_installs (${COLS.join(',')}) VALUES (${COLS.map(() => '?').join(',')})
+       ON CONFLICT(account, pluginId) DO UPDATE SET
+         version=excluded.version, scope=excluded.scope, grants=excluded.grants, indexers=excluded.indexers,
+         config=excluded.config, secrets=excluded.secrets, installedBy=excluded.installedBy,
+         adminApprovedBy=excluded.adminApprovedBy, packageRef=excluded.packageRef, digest=excluded.digest,
+         updatedAt=excluded.updatedAt`,
+      ...COLS.map((c) => (JSON_FIELDS.has(c) ? JSON.stringify(r[c] ?? (c === 'config' || c === 'secrets' ? {} : [])) : r[c] ?? null)),
+    );
+    return r;
+  }
+  async get(account, pluginId) {
+    return hydrate(await this.db.get('SELECT * FROM plugin_installs WHERE account=? AND pluginId=?', account, pluginId));
+  }
+  async list(account) {
+    const rows = await this.db.all('SELECT * FROM plugin_installs WHERE account=? ORDER BY updatedAt DESC', account);
+    return rows.map(hydrate);
+  }
+  async all() {
+    const rows = await this.db.all('SELECT * FROM plugin_installs ORDER BY account ASC, pluginId ASC');
+    return rows.map(hydrate);
+  }
+  async delete(account, pluginId) {
+    await this.db.run('DELETE FROM plugin_installs WHERE account=? AND pluginId=?', account, pluginId);
+  }
+  async countByDigest(digest) {
+    const r = await this.db.get('SELECT COUNT(*) AS n FROM plugin_installs WHERE digest=?', digest);
+    return r?.n ?? 0;
+  }
+}
+
+// --- Memory ------------------------------------------------------------------
+
+export class MemoryPluginInstallStore extends PluginInstallStore {
+  constructor() { super(); this.map = new Map(); }
+  #key(a, p) { return `${a}\0${p}`; }
+  async put(record) { const r = normalize(record); this.map.set(this.#key(r.account, r.pluginId), r); return r; }
+  async get(account, pluginId) { const r = this.map.get(this.#key(account, pluginId)); return r ? { ...r } : null; }
+  async list(account) { return [...this.map.values()].filter((r) => r.account === account).sort((a, b) => b.updatedAt - a.updatedAt).map((r) => ({ ...r })); }
+  async all() { return [...this.map.values()].map((r) => ({ ...r })); }
+  async delete(account, pluginId) { this.map.delete(this.#key(account, pluginId)); }
+  async countByDigest(digest) { return [...this.map.values()].filter((r) => r.digest === digest).length; }
+}
+
+function normalize(record) {
+  const now = record.updatedAt ?? Date.now();
+  return {
+    account: record.account, pluginId: record.pluginId, version: record.version ?? null,
+    scope: record.scope ?? 'account', grants: record.grants ?? [], indexers: record.indexers ?? [],
+    config: record.config ?? {}, secrets: record.secrets ?? {}, installedBy: record.installedBy ?? null,
+    adminApprovedBy: record.adminApprovedBy ?? null, packageRef: record.packageRef ?? null, digest: record.digest ?? null,
+    createdAt: record.createdAt ?? now, updatedAt: now,
+  };
+}
+// A corrupt JSON column is a real possibility (a partial write, a hand-edited db), and
+// it threw a bare SyntaxError straight out to the router — a 500 with a parser message
+// rather than something a caller can act on.
+function parseJson(text, fallback, what) {
+  if (text == null || text === '') return fallback;
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    throw TroveError.internal(`This plugin's stored ${what} is corrupt and could not be read`, { cause: err });
+  }
+}
+
+function hydrate(row) {
+  if (!row) return null;
+  const out = { ...row };
+  for (const f of JSON_FIELDS) out[f] = parseJson(row[f], (f === 'config' || f === 'secrets' ? {} : []), f);
+  return out;
+}

package/packages/core/src/plugins/package.js

@@ -0,0 +1,102 @@
+// Server-side plugin package parsing. The server independently re-parses an uploaded
+// package (never trusting the client that produced it), pulling out the manifest, the
+// verified identity, the declared capabilities and contributions, and a content digest
+// used for dedupe/integrity.
+
+import { unzipSync, strFromU8 } from 'fflate';
+import { TroveError } from '../errors.js';
+import { assertIdentity, pluginId } from './identity.js';
+import { declaredContributions, serverIndexers, declaredOpeners } from './contributions.js';
+
+export const ALL_CAPABILITIES = ['files', 'storage', 'ui', 'commands', 'indexer', 'opener', 'network', 'media', 'dock'];
+
+export { serverIndexers, declaredOpeners, declaredContributions };
+
+/** SHA-256 hex digest of the raw package bytes (content address). */
+export async function digestBytes(bytes) {
+  const buf = await crypto.subtle.digest('SHA-256', bytes);
+  return 'sha256:' + [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+/** Declared capability ids from a manifest (object `{cap: opts}` or array form). */
+export function capabilityList(manifest) {
+  const caps = manifest && manifest.capabilities;
+  if (Array.isArray(caps)) return caps.filter(Boolean);
+  if (caps && typeof caps === 'object') {
+    return Object.entries(caps).filter(([, v]) => v !== false && v != null).map(([k]) => k);
+  }
+  return [];
+}
+
+/** Whether the granted storage includes the shared `domain` scope. */
+export function usesSharedStorage(manifest) {
+  const opt = manifest?.capabilities?.storage;
+  return !!(opt && typeof opt === 'object' && opt.domain);
+}
+
+// A package's COMPRESSED size is capped at the route; its INFLATED size was not, and a
+// zip will happily turn 1 MB into 1 GB. `unzipSync` is synchronous, so that is a
+// gigabyte of RSS and thirteen seconds of blocked event loop for one request — from an
+// unauthenticated caller on the zero-config drive, since the install route only asks for
+// a principal and the shared anonymous one satisfies it.
+//
+// fflate's `filter` runs against the central directory BEFORE any entry is inflated, so
+// the declared sizes are the cheapest possible place to refuse. 64 MiB and 2,000 files
+// are far beyond any real plugin (the largest thing in one is a wasm blob) and far below
+// what hurts.
+const MAX_INFLATED_BYTES = 64 * 1024 * 1024;
+const MAX_ENTRIES = 2000;
+
+export function boundedUnzip(bytes) {
+  let total = 0;
+  let count = 0;
+  try {
+    return unzipSync(bytes, {
+      filter(file) {
+        if (++count > MAX_ENTRIES) throw TroveError.tooLarge(`Package has more than ${MAX_ENTRIES} files`);
+        total += file.originalSize || 0;
+        if (total > MAX_INFLATED_BYTES) {
+          throw TroveError.tooLarge(`Package expands to more than ${Math.round(MAX_INFLATED_BYTES / 1024 / 1024)} MB`);
+        }
+        return true;
+      },
+    });
+  } catch (err) {
+    if (err instanceof TroveError) throw err;
+    throw TroveError.invalid('Package is not a valid zip', { cause: err });
+  }
+}
+
+/**
+ * Parse an uploaded package zip. Returns { manifest, pluginId, files, capabilities,
+ * contributions, indexers, openers, digest }. Throws INVALID on a missing/malformed
+ * manifest, an unverifiable identity, or a bad contribution declaration.
+ * @param {Uint8Array} bytes
+ */
+export async function parsePluginPackage(bytes) {
+  const files = boundedUnzip(bytes);
+  const manifestRaw = files['manifest.json'];
+  if (!manifestRaw) throw TroveError.invalid('Package is missing manifest.json');
+  let manifest;
+  try {
+    manifest = JSON.parse(strFromU8(manifestRaw));
+  } catch (err) {
+    throw TroveError.invalid('manifest.json is not valid JSON', { cause: err });
+  }
+  // Identity first: everything else (contribution URIs, install records, storage
+  // scopes) is addressed under `<domain>/<name>`, so an anonymous package has no
+  // address space to live in and is rejected outright.
+  assertIdentity(manifest);
+  const capabilities = capabilityList(manifest).filter((c) => ALL_CAPABILITIES.includes(c));
+  return {
+    manifest,
+    pluginId: pluginId(manifest),
+    files,
+    capabilities,
+    contributions: declaredContributions(manifest),
+    indexers: serverIndexers(manifest),
+    openers: declaredOpeners(manifest),
+    sharedStorage: usesSharedStorage(manifest),
+    digest: await digestBytes(bytes),
+  };
+}

package/packages/core/src/plugins/packageStore.js

@@ -0,0 +1,61 @@
+// PackageStore — pluggable bulk storage for installed plugin package blobs (the
+// zips). Kept separate from install *records* (which live in SQLite): the blobs are
+// bulk data an operator usually wants on S3/R2 or a filesystem, and possibly on a
+// different backend than user files. The default just wraps the primary
+// StorageBackend under a prefix; inject any other StorageBackend (or a bespoke
+// PackageStore) to point packages elsewhere.
+//
+// Blobs are addressed by an opaque `ref` (see PluginService — `account/plugin/ver.zip`).
+// Content is deduped by digest at the service layer, so `put` is effectively idempotent.
+
+import { PrefixedStorage } from '../storage/prefixed.js';
+import { TroveError } from '../errors.js';
+
+export class PackageStore {
+  /** @param {string} ref @param {Uint8Array} bytes */
+  async put(ref, bytes) { throw TroveError.unsupported('PackageStore.put'); }
+  /** @returns {Promise<{stream: ReadableStream, size: number}>} */
+  async get(ref) { throw TroveError.unsupported('PackageStore.get'); }
+  /** @returns {Promise<boolean>} */
+  async has(ref) { throw TroveError.unsupported('PackageStore.has'); }
+  async delete(ref) {}
+  /** Optional: a URL a device can GET the package from directly. */
+  async presignGet(ref, opts) { throw TroveError.unsupported('This package store cannot presign'); }
+}
+
+/**
+ * The key space plugin packages live in.
+ *
+ * Exported because the collection SCANNER has to skip it, and the two drifted: the
+ * scanner's reserved list said `plugins/` while this said `_plugins/`, so every
+ * account's package was adopted into the default collection as an ordinary file.
+ * One constant, one source of truth.
+ */
+export const PACKAGE_PREFIX = '_plugins/';
+
+/** Default PackageStore: a namespaced view over any StorageBackend. */
+export class StoragePackageStore extends PackageStore {
+  /** @param {import('../storage/interface.js').StorageBackend} storage */
+  constructor(storage, { prefix = PACKAGE_PREFIX } = {}) {
+    super();
+    this.storage = prefix ? new PrefixedStorage(storage, prefix) : storage;
+  }
+  async put(ref, bytes) {
+    return this.storage.put(ref, bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes), { contentType: 'application/zip' });
+  }
+  async get(ref) {
+    return this.storage.get(ref);
+  }
+  async has(ref) {
+    try { await this.storage.head(ref); return true; } catch (err) {
+      if (err?.code === 'not_found') return false;
+      throw err;
+    }
+  }
+  async delete(ref) {
+    return this.storage.delete(ref).catch(() => {});
+  }
+  async presignGet(ref, opts) {
+    return this.storage.presignGet(ref, opts);
+  }
+}