@3sln/trove 0.0.2

package/packages/web/src/platform/pluginMedia.js

@@ -0,0 +1,62 @@
+// MediaController — bridges a plugin frame's playback to the OS via
+// navigator.mediaSession, so a sandboxed audio/video viewer surfaces real transport
+// controls (lock screen, media keys, notification shade).
+//
+// The host owns the single global mediaSession; the LAST frame to touch it becomes
+// the owner. OS actions fire back over that frame's own RPC channel, so a handler is
+// only ever wired to a live frame — and the handlers a frame registered are released
+// when it goes away (otherwise the OS would call into a dead channel).
+
+export class MediaController {
+  constructor() {
+    this.owner = null; // the frame currently driving navigator.mediaSession
+  }
+
+  #session() {
+    return typeof navigator !== 'undefined' ? navigator.mediaSession : null;
+  }
+
+  /** Apply one media operation for `frame`. kind: metadata|playbackState|position|action|clear */
+  apply(frame, kind, params = {}) {
+    const ms = this.#session();
+    if (!ms) return { ok: false };
+    if (frame && kind !== 'clear') { this.owner = frame; frame.mediaOwner = true; }
+    try {
+      if (kind === 'metadata') {
+        ms.metadata = typeof MediaMetadata !== 'undefined'
+          ? new MediaMetadata({ title: params.title || '', artist: params.artist || '', album: params.album || '', artwork: params.artwork || [] })
+          : ms.metadata;
+      } else if (kind === 'playbackState') {
+        ms.playbackState = params.state || 'none';
+      } else if (kind === 'position' && ms.setPositionState) {
+        ms.setPositionState({ duration: params.duration || 0, position: params.position || 0, playbackRate: params.playbackRate || 1 });
+      } else if (kind === 'action') {
+        ms.setActionHandler?.(params.action, params.on ? () => frame?.channel?.emit('media:action', { action: params.action }) : null);
+        // Remember which actions this frame registered, so we can release them when
+        // the frame goes away (otherwise the OS handler points at a dead channel).
+        if (frame) { frame.mediaActions ||= new Set(); params.on ? frame.mediaActions.add(params.action) : frame.mediaActions.delete(params.action); }
+      } else if (kind === 'clear') {
+        if (frame && this.owner && this.owner !== frame) return { ok: true }; // don't clear someone else's session
+        this.releaseActions(frame);
+        ms.metadata = null;
+        ms.playbackState = 'none';
+        this.owner = null;
+      }
+    } catch { /* unsupported action/state */ }
+    return { ok: true };
+  }
+
+  /** Detach the OS media-transport handlers a frame registered (on teardown). */
+  releaseActions(frame) {
+    const ms = this.#session();
+    if (!ms || !frame?.mediaActions) return;
+    for (const action of frame.mediaActions) { try { ms.setActionHandler?.(action, null); } catch { /* ignore */ } }
+    frame.mediaActions.clear();
+  }
+
+  /** Frame teardown: give up the session if this frame owned it, then drop its handlers. */
+  releaseFrame(frame) {
+    if (this.owner === frame) { this.owner = null; this.apply(frame, 'clear', {}); }
+    this.releaseActions(frame); // drop handlers even if this frame wasn't the owner
+  }
+}

package/packages/web/src/platform/pluginModules.js

@@ -0,0 +1,90 @@
+// Multi-file plugins — native ESM without a bundler. A package can put its code
+// under `src/` and use ordinary relative imports (`import './util.js'`); assets
+// live anywhere else and are reached as opaque resources. We can't just let the
+// sandboxed frame import these: it's on an opaque origin and can't fetch its own
+// files, and a blob: module's base URL is meaningless so `./util.js` wouldn't
+// resolve. So the host loads every `src/*.js` module as a blob: URL inside the
+// frame and wires them together with an import map — and, because an import map is
+// keyed by name (not text order), circular imports and any load order just work.
+//
+// The one preprocessing step: relative specifiers are rewritten to a canonical
+// `trove:/<path>` key (resolved against the importing module) so they match the
+// import map instead of resolving against the opaque blob base. We use
+// es-module-lexer to find the exact specifier spans, so strings/comments/regex are
+// never touched. The SDK is exposed as the bare specifier `trove`, so plugins can
+// write either `import { activate } from 'trove'` or use the `globalThis.trove`
+// the injected SDK also sets.
+
+import { init, parse } from 'es-module-lexer';
+
+const JS_RE = /\.m?js$/i;
+
+/** A file that participates in the module graph (code under `src/`). */
+export function isSourceModule(path) {
+  return /^src\//i.test(path) && JS_RE.test(path);
+}
+
+/** Whether a package should run in ESM module mode (its entry is a src module). */
+export function isModuleEntry(manifest) {
+  return isSourceModule(manifest.entry || '');
+}
+
+function dirParts(p) {
+  const i = p.lastIndexOf('/');
+  return (i < 0 ? '' : p.slice(0, i)).split('/').filter(Boolean);
+}
+
+/** Resolve a relative specifier against the importer's package path. */
+function resolvePath(importer, spec) {
+  const stack = dirParts(importer);
+  for (const part of spec.split('/')) {
+    if (part === '' || part === '.') continue;
+    else if (part === '..') stack.pop();
+    else stack.push(part);
+  }
+  return stack.join('/');
+}
+
+/**
+ * Build the rewritten module set + entry for a package. Returns
+ * { modules: { path: code }, entry } where each module's relative imports point at
+ * canonical `trove:/<path>` keys. Only `src/*.js` files are included.
+ */
+export async function buildModuleGraph(pkg) {
+  await init;
+  const modules = {};
+  for (const [path, bytes] of pkg.files) {
+    if (isSourceModule(path)) modules[path] = new TextDecoder().decode(bytes);
+  }
+  const has = (p) => Object.prototype.hasOwnProperty.call(modules, p);
+  const resolveModule = (importer, spec) => {
+    const r = resolvePath(importer, spec);
+    if (has(r)) return r;
+    if (has(r + '.js')) return r + '.js';
+    if (has(r + '.mjs')) return r + '.mjs';
+    if (has(r + '/index.js')) return r + '/index.js';
+    return r; // unresolved → import fails with a clear "no such module" error
+  };
+  const rewritten = {};
+  for (const [path, code] of Object.entries(modules)) {
+    rewritten[path] = rewriteSpecifiers(code, path, resolveModule);
+  }
+  return { modules: rewritten, entry: pkg.manifest.entry };
+}
+
+/** Rewrite relative import specifiers in one module to canonical map keys. */
+export function rewriteSpecifiers(code, path, resolveModule) {
+  const [imports] = parse(code);
+  let out = '';
+  let last = 0;
+  for (const imp of imports) {
+    if (imp.n == null) continue;        // dynamic import with a non-literal argument
+    if (imp.n[0] !== '.') continue;     // only relative specifiers are remapped
+    const key = 'trove:/' + resolveModule(path, imp.n);
+    // Static spans exclude the quotes; dynamic import() spans include them.
+    const replacement = imp.d === -1 ? key : JSON.stringify(key);
+    out += code.slice(last, imp.s) + replacement;
+    last = imp.e;
+  }
+  return out + code.slice(last);
+}

package/packages/web/src/platform/pluginNet.js

@@ -0,0 +1,71 @@
+// Declared network endpoints — the allowlist a plugin must publish before it can
+// talk to the web. The sandboxed iframe can't reach the network at all (strict
+// `connect-src 'none'` CSP + opaque origin); every request is brokered by the host
+// over the MessagePort, and the host only makes it if the URL matches one of these
+// declared endpoints. So the manifest's `network` array is the *complete* list of
+// hosts a plugin can ever reach, shown to the user at install time and enforced at
+// runtime.
+//
+// An endpoint is a URL prefix: scheme + host (optionally `*.`-wildcarded) + port +
+// path prefix. A request matches when its scheme, host, port, and path-prefix all
+// agree. Query strings and fragments are ignored in the pattern.
+
+/** Parse one endpoint pattern; throws on anything that isn't an http(s) URL. */
+export function parseEndpoint(pattern) {
+  // Strip a leading `*.` wildcard BEFORE parsing — `*` isn't a valid host code
+  // point, and URL parsers disagree on how to mangle it (Chromium vs ada/Node),
+  // so we never hand it to `new URL()`.
+  const wild = /^([a-z][a-z0-9+.-]*:\/\/)\*\.(.+)$/i.exec(pattern);
+  const wildcard = !!wild;
+  let u;
+  try {
+    u = new URL(wildcard ? wild[1] + wild[2] : pattern);
+  } catch {
+    throw new Error(`Invalid network endpoint "${pattern}" (must be an absolute http(s) URL)`);
+  }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') {
+    throw new Error(`Network endpoint "${pattern}" must use http or https`);
+  }
+  const host = u.hostname.toLowerCase();
+  if (!host) throw new Error(`Network endpoint "${pattern}" has no host`);
+  return { scheme: u.protocol, host, wildcard, port: u.port, pathPrefix: u.pathname || '/', raw: pattern };
+}
+
+/** Parse a manifest's `network` list, silently dropping malformed entries. */
+export function normalizeEndpoints(list) {
+  const out = [];
+  for (const p of list || []) {
+    try { out.push(parseEndpoint(p)); } catch { /* skip — validated separately at parse time */ }
+  }
+  return out;
+}
+
+/** Does a request URL fall under a single parsed endpoint? */
+export function matchesEndpoint(ep, url) {
+  let u;
+  try { u = new URL(url); } catch { return false; }
+  if (u.protocol !== ep.scheme) return false;
+  const host = u.hostname.toLowerCase();
+  if (ep.wildcard) {
+    if (host !== ep.host && !host.endsWith('.' + ep.host)) return false;
+  } else if (host !== ep.host) {
+    return false;
+  }
+  if (u.port !== ep.port) return false; // '' === '' for default ports (browser normalizes)
+  return u.pathname.startsWith(ep.pathPrefix);
+}
+
+/** Is `url` allowed by the plugin's declared endpoint list? */
+export function isAllowedUrl(endpoints, url) {
+  return normalizeEndpoints(endpoints).some((ep) => matchesEndpoint(ep, url));
+}
+
+/** A human-friendly summary of declared endpoints for the review UI. */
+export function endpointSummary(endpoints) {
+  return normalizeEndpoints(endpoints).map((e) => ({
+    scheme: e.scheme.replace(':', ''),
+    host: (e.wildcard ? '*.' : '') + e.host + (e.port ? ':' + e.port : ''),
+    path: e.pathPrefix === '/' ? '' : e.pathPrefix,
+    raw: e.raw,
+  }));
+}

package/packages/web/src/platform/pluginPackage.js

@@ -0,0 +1,247 @@
+// Plugin packages — a plugin is a zip: manifest.json + an entry script + assets.
+// This parses/validates a package (from an uploaded file or a fetched URL) and
+// produces the summary shown in the pre-install review. Nothing here runs plugin
+// code — that only happens later, inside a sandboxed iframe.
+
+import { unzipSync } from 'fflate';
+import { parseEndpoint, endpointSummary } from './pluginNet.js';
+import { assertIdentity, pluginId, ownsUri, parseContribUri } from '@3sln/trove/core/plugins/identity.js';
+import { declaredContributions } from '@3sln/trove/core/plugins/contributions.js';
+
+const CAP_DESCRIPTIONS = {
+  files: 'Read your files, folders, and search index (via the host).',
+  storage: 'Keep its own SQLite database(s) — on the server and/or on this device.',
+  ui: 'Show a popup panel and toasts.',
+  commands: 'Add commands to the palette, and run the specific host commands it lists.',
+  opener: 'Preview/open file types.',
+  // Distinct from a declared indexer (which the SERVER runs on every upload): this
+  // capability lets the plugin itself push searchable content for a file it's looking at.
+  indexer: 'Add searchable content to your files.',
+  network: 'Connect to the internet — only the endpoints it declares (shown below).',
+  media: 'Show playback controls on your lock screen and notifications while it plays media.',
+  dock: 'Keep its viewer in a small floating window when you navigate away.',
+};
+
+// Capabilities that need an admin to grant (they touch shared data). None at the
+// moment — the `storage.domain` scope is instead gated on domain verification.
+export const ADMIN_ONLY_CAPS = new Set();
+
+/**
+ * The storage scopes a manifest declares: `{ plugin, domain }`. Each is a separate
+ * lazily-created SQLite database (server + client). The `domain` scope — shared
+ * across a vendor's plugins — is only usable by a domain-verified package.
+ */
+export function storageScopes(manifest) {
+  const opt = capabilityOptions(manifest, 'storage');
+  if (!opt) return { plugin: false, domain: false };
+  // `storage: true` (or `{}`) → the private plugin scope, nothing shared.
+  if (opt === true || (typeof opt === 'object' && !('plugin' in opt) && !('domain' in opt))) {
+    return { plugin: true, domain: false };
+  }
+  return { plugin: !!opt.plugin, domain: !!opt.domain };
+}
+
+export function describeCapability(cap) {
+  return CAP_DESCRIPTIONS[cap] || cap;
+}
+
+// Capabilities are declared as an object: each key is a capability, each value is
+// that capability's options. A capability that takes no options uses `true` (or an
+// empty object). e.g. { ui: true, network: { endpoints: ["https://api.example.com/"] } }.
+// A plain array of ids is also accepted (each treated as options-less) so simple
+// or hand-written manifests stay easy.
+export function capabilityEntries(manifest) {
+  const caps = manifest && manifest.capabilities;
+  const out = {};
+  if (Array.isArray(caps)) {
+    for (const id of caps) if (id) out[id] = {};
+  } else if (caps && typeof caps === 'object') {
+    for (const [id, val] of Object.entries(caps)) {
+      if (val === false || val == null) continue; // explicitly not requested
+      out[id] = val === true ? {} : val;
+    }
+  }
+  return out;
+}
+
+/** The declared capability ids. */
+export function capabilityList(manifest) {
+  return Object.keys(capabilityEntries(manifest));
+}
+
+/** Options declared for one capability, or null if it isn't declared. */
+export function capabilityOptions(manifest, id) {
+  const e = capabilityEntries(manifest);
+  return Object.prototype.hasOwnProperty.call(e, id) ? e[id] : null;
+}
+
+/** The network capability's declared endpoint prefixes (accepts a few shapes). */
+export function networkEndpoints(manifest) {
+  const opt = capabilityOptions(manifest, 'network');
+  if (opt) {
+    if (Array.isArray(opt)) return opt;                 // network: ["https://…"]
+    if (Array.isArray(opt.endpoints)) return opt.endpoints;
+    if (Array.isArray(opt.prefixes)) return opt.prefixes;
+  }
+  if (Array.isArray(manifest.network)) return manifest.network; // legacy top-level
+  return [];
+}
+
+/** The human-facing name: `displayName` if given, else the package name. */
+export function displayName(manifest) {
+  // A STRING, always — and this is a security boundary, not tidiness.
+  //
+  // dodo decides "is this argument a props map or a child?" by `x.constructor === Object`,
+  // and every prop on an HTML element is assigned as a DOM PROPERTY. `JSON.parse` gives
+  // objects whose constructor is Object, so a manifest with
+  // `"displayName": {"innerHTML": "<img src=x onerror=…>"}` — nothing validates it —
+  // reaches `span(plugin.name)` in the plugin panel and `h3(g.category)` in Settings as
+  // the FIRST argument, becomes the element's prop map, and executes in the host page.
+  // That is a complete escape from the opaque-origin, connect-src 'none' iframe.
+  const name = manifest?.displayName ?? manifest?.name;
+  return typeof name === 'string' && name.trim() ? name : 'Plugin';
+}
+
+/**
+ * The exact commands this plugin may ASK THE HOST TO RUN (ctx.commands.execute), each
+ * named by the URI it's contributed at — a built-in like `explorer.download`, or
+ * another plugin's `trove+contrib:acme.com/docs/export`. Like `network`, the
+ * capability carries its allowlist rather than being a blanket grant: "can run
+ * commands" is meaningless as a yes/no, because the interesting question is always
+ * *which* ones (`explorer.delete` is not `workbench.view.home`).
+ * Accepted shapes:
+ *   commands: true                          → contribute-only; executes nothing external
+ *   commands: ["explorer.download", …]      → exactly these
+ *   commands: { execute: ["…"] }            → exactly these
+ * A plugin may always execute its own commands — that's just calling itself.
+ */
+export function executableCommands(manifest) {
+  const opt = capabilityOptions(manifest, 'commands');
+  if (!opt) return [];
+  if (Array.isArray(opt)) return opt.filter(Boolean);
+  if (Array.isArray(opt.execute)) return opt.execute.filter(Boolean);
+  return [];
+}
+
+/**
+ * Whether `commandUri` is executable by the plugin described by `manifest`. A plugin
+ * always owns its own contributions (the URI is scoped under its domain and name), so
+ * ownership is decided by the address itself rather than by a naming convention or a
+ * registry lookup that could be raced.
+ */
+export function canExecuteCommand(manifest, commandUri, _ownerPluginId) {
+  if (!commandUri) return false;
+  if (parseContribUri(commandUri) && ownsUri(manifest, commandUri)) return true;
+  return executableCommands(manifest).includes(commandUri);
+}
+
+/** Parse zip bytes into { manifest, files:Map<path,Uint8Array>, raw }. */
+export function parsePackage(zipBytes) {
+  let entries;
+  try {
+    entries = unzipSync(zipBytes instanceof Uint8Array ? zipBytes : new Uint8Array(zipBytes));
+  } catch (err) {
+    throw new Error('Not a valid zip archive: ' + err.message);
+  }
+  const files = new Map();
+  for (const [path, bytes] of Object.entries(entries)) {
+    if (!path.endsWith('/')) files.set(path.replace(/^\.?\//, ''), bytes);
+  }
+  const manifestBytes = files.get('manifest.json');
+  if (!manifestBytes) throw new Error('Package is missing manifest.json');
+  let manifest;
+  try {
+    manifest = JSON.parse(new TextDecoder().decode(manifestBytes));
+  } catch (err) {
+    throw new Error('manifest.json is not valid JSON: ' + err.message);
+  }
+  validateManifest(manifest, files);
+  return { manifest, files, raw: zipBytes };
+}
+
+function validateManifest(m, files) {
+  const need = (c, msg) => { if (!c) throw new Error(msg); };
+  // Identity is mandatory: a package must say which DOMAIN it belongs to and its NAME
+  // within that domain. There is no anonymous/self-identified install — every
+  // contribution is addressed under `<domain>/<name>`, and the domain is what makes
+  // that address verifiable rather than merely claimed.
+  assertIdentity(m);
+  need(m.entry, 'manifest.entry (path to the plugin script) is required');
+  need(files.has(m.entry), `entry "${m.entry}" is not in the package`);
+  if (m.capabilities != null) {
+    need(Array.isArray(m.capabilities) || typeof m.capabilities === 'object',
+      'capabilities must be an object of { capability: options } (or an array of ids)');
+  }
+  if (m.icon) need(files.has(m.icon), `icon "${m.icon}" is not in the package`);
+  // Throws on a bad type, a missing entry module, or a malformed option — the review
+  // dialog must be able to show exactly what will be registered.
+  for (const c of declaredContributions(m)) {
+    if (c.entry) need(files.has(c.entry), `contribution "${c.name}" points at "${c.entry}", which is not in the package`);
+    if (c.type === 'keymap') need(files.has(c.path), `keymap "${c.name}" points at "${c.path}", which is not in the package`);
+  }
+  for (const ep of networkEndpoints(m)) parseEndpoint(ep); // throws on anything but an http(s) URL
+}
+
+/** Fetch a package from a URL (must be a zip). */
+export async function fetchPackage(url, fetchFn = globalThis.fetch.bind(globalThis)) {
+  let res;
+  try {
+    res = await fetchFn(url);
+  } catch (err) {
+    throw new Error('Could not fetch the plugin: ' + err.message);
+  }
+  if (!res.ok) throw new Error(`Could not fetch the plugin (HTTP ${res.status})`);
+  const bytes = new Uint8Array(await res.arrayBuffer());
+  return parsePackage(bytes);
+}
+
+/** A flat, review-friendly summary of everything the package declares. */
+export function reviewSummary(pkg, trust) {
+  const m = pkg.manifest;
+  const contributions = declaredContributions(m).map((c) => ({
+    kind: c.type, name: c.name, uri: c.uri,
+    title: c.title || c.name,
+    detail: c.type === 'opener' || c.type === 'indexer' ? selectorText(c.match)
+      // What it RUNS, not just where it sits. A status item can carry a command, and a
+      // review that only said "right of the status bar" gave the user nothing to refuse.
+      : c.type === 'statusItem' ? `${c.slot} of the status bar${c.command ? ` — runs ${c.command}` : ''}`
+        : c.type === 'keymap' ? c.path : '',
+    offline: !!c.offline,
+  }));
+  const verified = trust?.status === 'verified';
+  const scopes = storageScopes(m);
+  return {
+    id: pluginId(m), name: displayName(m), version: m.version || '0.0.0', description: m.description || '',
+    author: m.author || 'Unknown', domain: m.domain,
+    capabilities: capabilityList(m).map((cap) => ({ id: cap, description: describeCapability(cap), adminOnly: ADMIN_ONLY_CAPS.has(cap) })),
+    contributions,
+    settings: (m.settings || []).map((s) => ({ key: s.key, title: s.title || s.key, type: s.type, secret: !!s.secret })),
+    network: endpointSummary(networkEndpoints(m)),
+    // Exactly which host commands it may run. Resolved to titles by the review UI,
+    // which has the command registry; here we just surface the declared ids.
+    commands: executableCommands(m),
+    // Which SQLite stores it wants. `domain` (shared across a vendor's plugins) is
+    // only grantable for a verified package; flag it so the review can say why.
+    storage: (scopes.plugin || scopes.domain)
+      ? { plugin: scopes.plugin, domain: scopes.domain, domainBlocked: scopes.domain && !verified }
+      : null,
+    fileCount: pkg.files.size,
+    sizeBytes: [...pkg.files.values()].reduce((n, b) => n + b.length, 0),
+    trust,
+  };
+}
+
+/** The storage scopes actually granted at install: plugin if declared, domain if
+ * declared AND the package is domain-verified. */
+export function grantedStorageScopes(manifest, trust) {
+  const s = storageScopes(manifest);
+  return { plugin: s.plugin, domain: s.domain && trust?.status === 'verified' };
+}
+
+function selectorText(sel) {
+  if (!sel) return '';
+  const parts = [];
+  if (sel.ext?.length) parts.push(sel.ext.join(', '));
+  if (sel.mime?.length) parts.push(sel.mime.join(', '));
+  return parts.join(' · ');
+}