@3sln/trove 0.0.2

package/packages/core/src/notifications/webpush.js

@@ -0,0 +1,217 @@
+// Web Push over VAPID (RFC 8292), built on Web Crypto (crypto.subtle) so it runs
+// unchanged on Node ≥20, Bun, Deno, and Cloudflare Workers — no Node crypto, no
+// external deps (web-push et al. all pull in Node crypto).
+//
+// DESIGN — bodyless (no-payload) pushes:
+// We deliberately send DATA-LESS web pushes: a VAPID-authenticated POST to the
+// subscription endpoint carrying only a TTL (and optional urgency/topic), with
+// an empty body. This AVOIDS the whole RFC 8291 payload-encryption stack — the
+// ECDH key agreement over the subscription's p256dh key, the HKDF salt/IKM
+// derivation, and aes128gcm content encoding. When the browser wakes the
+// service worker for a data-less push, the worker calls back to our server to
+// fetch whatever notifications are pending. So the subscription's `keys`
+// (p256dh/auth) are never used here, and there is NO message encryption in this
+// file — only VAPID (RFC 8292) request authorization.
+//
+// VAPID auth = a P-256 ECDSA (ES256) signed JWT identifying our application
+// server, sent as `Authorization: vapid t=<jwt>, k=<appServerPublicKey>`.
+
+import { TroveError } from '../errors.js';
+import { withRetry } from '../retry.js';
+
+const enc = new TextEncoder();
+
+// --- base64url (no padding) ---------------------------------------------------
+
+/** Encode bytes as base64url without padding. */
+export function base64urlEncode(bytes) {
+  const b = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  let bin = '';
+  for (let i = 0; i < b.length; i++) bin += String.fromCharCode(b[i]);
+  return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+/** Decode a base64url (padded or not) string to bytes. */
+export function base64urlDecode(str) {
+  const b64 = String(str).replace(/-/g, '+').replace(/_/g, '/') + '==='.slice((str.length + 3) % 4);
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+// --- key generation / import --------------------------------------------------
+
+/**
+ * Generate a VAPID application-server keypair (P-256 / ES256).
+ * @returns {Promise<{publicKey: string, privateKey: string}>}
+ *   `publicKey`  — the uncompressed EC point (65 bytes: 0x04 || X || Y),
+ *                  base64url-encoded. This is the value browsers expect as
+ *                  `applicationServerKey` in PushManager.subscribe().
+ *   `privateKey` — the raw 32-byte scalar `d`, base64url-encoded.
+ */
+export async function generateVapidKeys() {
+  const pair = await crypto.subtle.generateKey(
+    { name: 'ECDSA', namedCurve: 'P-256' },
+    true,
+    ['sign', 'verify'],
+  );
+  const jwk = await crypto.subtle.exportKey('jwk', pair.privateKey);
+  // Reassemble the uncompressed point from the JWK's x/y coordinates.
+  const x = base64urlDecode(jwk.x);
+  const y = base64urlDecode(jwk.y);
+  const point = new Uint8Array(65);
+  point[0] = 0x04;
+  point.set(x, 1);
+  point.set(y, 33);
+  return {
+    publicKey: base64urlEncode(point),
+    privateKey: jwk.d, // JWK `d` is already raw base64url of the 32-byte scalar.
+  };
+}
+
+/**
+ * Import a stored `{publicKey, privateKey}` (base64url) as a signing CryptoKey.
+ * The private JWK needs the matching public coordinates x/y, which we recover
+ * from the stored uncompressed public point.
+ * @returns {Promise<CryptoKey>}
+ */
+export async function importVapidPrivateKey({ publicKey, privateKey }) {
+  const point = base64urlDecode(publicKey);
+  if (point.length !== 65 || point[0] !== 0x04) {
+    throw TroveError.invalid('VAPID publicKey must be a 65-byte uncompressed P-256 point');
+  }
+  const x = base64urlEncode(point.subarray(1, 33));
+  const y = base64urlEncode(point.subarray(33, 65));
+  return crypto.subtle.importKey(
+    'jwk',
+    { kty: 'EC', crv: 'P-256', d: privateKey, x, y, ext: true },
+    { name: 'ECDSA', namedCurve: 'P-256' },
+    false,
+    ['sign'],
+  );
+}
+
+// --- service ------------------------------------------------------------------
+
+const GONE_STATUSES = new Set([404, 410]);
+
+export class WebPushService {
+  /**
+   * @param {object} o
+   * @param {string} o.publicKey  base64url uncompressed P-256 point (65 bytes)
+   * @param {string} o.privateKey base64url raw 32-byte scalar `d`
+   * @param {string} o.subject    VAPID `sub` claim — a `mailto:` or https URL
+   */
+  constructor({ publicKey, privateKey, subject } = {}) {
+    if (!publicKey || !privateKey) {
+      throw TroveError.invalid('WebPushService requires publicKey and privateKey');
+    }
+    if (!subject || !/^(mailto:|https:\/\/)/.test(subject)) {
+      throw TroveError.invalid('WebPushService subject must be a mailto: or https URL');
+    }
+    this.publicKey = publicKey;
+    this.privateKey = privateKey;
+    this.subject = subject;
+    this._signingKey = null; // lazily imported, then cached
+  }
+
+  async _key() {
+    if (!this._signingKey) {
+      this._signingKey = await importVapidPrivateKey({
+        publicKey: this.publicKey,
+        privateKey: this.privateKey,
+      });
+    }
+    return this._signingKey;
+  }
+
+  /**
+   * Build a VAPID JWT for a given endpoint audience.
+   * @param {string} aud  origin of the push endpoint (scheme + host)
+   * @param {number} now  epoch millis; exp = now + 12h
+   * @returns {Promise<string>} the compact JWS (header.payload.signature)
+   */
+  async _signJwt(aud, now) {
+    const header = base64urlEncode(enc.encode(JSON.stringify({ typ: 'JWT', alg: 'ES256' })));
+    const payload = base64urlEncode(
+      enc.encode(
+        JSON.stringify({
+          aud,
+          exp: Math.floor(now / 1000) + 12 * 60 * 60, // 12 hours
+          sub: this.subject,
+        }),
+      ),
+    );
+    const signingInput = `${header}.${payload}`;
+    // Web Crypto returns the raw r||s (64 bytes) that JWS ES256 wants — NOT DER.
+    const sig = await crypto.subtle.sign(
+      { name: 'ECDSA', hash: 'SHA-256' },
+      await this._key(),
+      enc.encode(signingInput),
+    );
+    return `${signingInput}.${base64urlEncode(new Uint8Array(sig))}`;
+  }
+
+  /**
+   * Send a bodyless web push to a subscription.
+   * @param {{endpoint: string, keys?: object}} subscription  standard PushSubscription JSON
+   * @param {object} [o]
+   * @param {number} [o.ttl=2419200]      seconds the push service holds the message (default 28d)
+   * @param {string} [o.urgency='normal'] very-low | low | normal | high
+   * @param {string} [o.topic]            optional collapse key
+   * @param {number} [o.now=Date.now()]   epoch millis (for JWT exp; injectable for sandboxes/tests)
+   * @param {AbortSignal} [o.signal]
+   * @returns {Promise<{ok: boolean, status: number, gone?: boolean}>}
+   *   `{ ok: false, gone: true }` when the subscription is dead (404/410) — the
+   *   caller should delete it. Never throws for `gone`.
+   */
+  async send(subscription, { ttl = 2419200, urgency = 'normal', topic, now = Date.now(), signal } = {}) {
+    const endpoint = subscription?.endpoint;
+    if (!endpoint) throw TroveError.invalid('subscription.endpoint is required');
+
+    let aud;
+    try {
+      aud = new URL(endpoint).origin;
+    } catch (e) {
+      throw TroveError.invalid('subscription.endpoint is not a valid URL', { cause: e });
+    }
+
+    const jwt = await this._signJwt(aud, now);
+    const headers = {
+      Authorization: `vapid t=${jwt}, k=${this.publicKey}`,
+      TTL: String(ttl),
+      Urgency: urgency,
+      'Content-Length': '0',
+    };
+    if (topic) headers.Topic = topic;
+
+    return withRetry(
+      async () => {
+        let res;
+        try {
+          // `redirect: 'error'` because a push service that 302s us somewhere is either
+          // broken or walking us onto an internal host the subscribe-time check refused.
+          res = await fetch(endpoint, { method: 'POST', headers, body: '', signal, redirect: 'error' });
+        } catch (e) {
+          // Network failure — let withRetry classify it (wrapError → transient).
+          throw e;
+        }
+
+        const status = res.status;
+        // Dead subscription: signal the caller to delete it. Never throw.
+        if (GONE_STATUSES.has(status)) return { ok: false, gone: true, status };
+        // Throttling / server errors are retryable.
+        if (status === 429 || status >= 500) {
+          throw TroveError.transient(`Push endpoint returned ${status}`, { details: { status } });
+        }
+        // Any other non-2xx is a permanent client error (bad JWT, bad request…).
+        if (status < 200 || status >= 300) {
+          throw TroveError.invalid(`Push endpoint returned ${status}`, { details: { status } });
+        }
+        return { ok: true, status };
+      },
+      { signal },
+    );
+  }
+}

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

@@ -0,0 +1,177 @@
+// What a package contributes — declared in its manifest as ONE map of
+// `name -> contribution`, where each contribution states its own `type` and that
+// type's options:
+//
+//   "contributes": {
+//     "player":  { "type": "opener",     "title": "Demo Player",
+//                  "match": { "ext": [".demo"] }, "entry": "src/openers/player.js" },
+//     "pdf":     { "type": "indexer",    "match": { "ext": [".pdf"] }, "entry": "src/indexers/pdf.js" },
+//     "tap":     { "type": "command",    "title": "Demo: Tap" },
+//     "status":  { "type": "statusItem", "slot": "right" },
+//     "busy":    { "type": "register",   "default": false },
+//     "keys":    { "type": "keymap",     "path": "keymaps/default.json" }
+//   }
+//
+// One map, not a collection per kind, because the kinds never needed separate
+// namespaces — they needed a shared one. Here "status" is a single name under this
+// plugin, so its status item, its register and its command can't shadow each other,
+// and `trove+contrib:acme.com/docs/status` names exactly one thing in the world.
+//
+// Each contribution's `entry` (openers, indexers) points into the plugin's ONE module
+// tree — they are not nested sub-packages, so everything in a plugin shares modules
+// and code. What gets opened or indexed depends only on which entry module runs.
+
+import { TroveError } from '../errors.js';
+import { contribUri, isValidName, pluginId } from './identity.js';
+
+/** Every contribution type a package may declare, with how its options are normalized. */
+const TYPES = {
+  // A command in the palette. Its handler lives in the plugin's primary frame.
+  command: {
+    normalize: (c) => ({
+      title: c.title || null, category: c.category || null, icon: c.icon || null,
+      when: c.when || null, palette: c.palette !== false, offline: !!c.offline,
+    }),
+  },
+  // A viewer for matching files, rendered by `entry` in its own sandboxed frame.
+  opener: {
+    needsEntry: true,
+    normalize: (c) => ({
+      title: c.title || null, match: normalizeMatch(c.match), priority: c.priority ?? 50,
+      when: c.when || null, offline: !!c.offline, dock: c.dock || null,
+    }),
+  },
+  // Indexes matching files. ALWAYS runs on the server (see serverIndexers).
+  indexer: {
+    needsEntry: true,
+    normalize: (c) => ({ title: c.title || null, match: normalizeMatch(c.match) }),
+  },
+  // A slot in the status bar. The plugin pushes content into it at runtime; for now
+  // the only content type is sanitized HTML.
+  statusItem: {
+    normalize: (c) => {
+      const slot = c.slot === 'left' ? 'left' : 'right';
+      const render = c.render || 'html';
+      if (render !== 'html') throw TroveError.invalid(`statusItem "render" must be "html" (got ${JSON.stringify(render)})`);
+      return { slot, render, order: c.order ?? 0, when: c.when || null, offline: !!c.offline, command: c.command || null };
+    },
+  },
+  // A context value slot the plugin drives at runtime, referenceable from when-clauses
+  // in keymaps, commands and other contributions (the equivalent of a VS Code context key).
+  register: {
+    normalize: (c) => ({ default: c.default ?? null, description: c.description || null }),
+  },
+  // A keymap JSON file in the package: [{ key, command, when?, args? }, …].
+  keymap: {
+    normalize: (c) => {
+      if (!c.path || typeof c.path !== 'string') throw TroveError.invalid('keymap contribution needs a "path" to a JSON file in the package');
+      return { path: c.path };
+    },
+  },
+};
+
+export const CONTRIBUTION_TYPES = Object.keys(TYPES);
+
+/**
+ * Every contribution a manifest declares, normalized and addressed by URI.
+ * Throws INVALID on a malformed declaration — a package that lies about what it
+ * contributes must not install, because the install review is what the user approved.
+ * @returns {Array<{name:string, uri:string, type:string, entry?:string}>}
+ */
+export function declaredContributions(manifest) {
+  const map = manifest?.contributes;
+  if (map == null) return [];
+  if (typeof map !== 'object' || Array.isArray(map)) {
+    throw TroveError.invalid('manifest "contributes" must be a map of name -> contribution');
+  }
+  const out = [];
+  for (const [name, raw] of Object.entries(map)) {
+    if (!raw || typeof raw !== 'object') throw TroveError.invalid(`Contribution "${name}" must be an object`);
+    if (!isValidName(name)) throw TroveError.invalid(`Invalid contribution name "${name}"`);
+    const spec = TYPES[raw.type];
+    if (!spec) {
+      throw TroveError.invalid(`Contribution "${name}" has unknown type ${JSON.stringify(raw.type)} (expected one of ${CONTRIBUTION_TYPES.join(', ')})`);
+    }
+    const entry = raw.entry || manifest.entry;
+    if (spec.needsEntry && !entry) throw TroveError.invalid(`Contribution "${name}" (${raw.type}) needs an "entry" module`);
+    out.push({
+      name,
+      uri: contribUri(manifest, name),
+      pluginId: pluginId(manifest),
+      type: raw.type,
+      ...spec.normalize(raw),
+      ...(spec.needsEntry ? { entry } : {}),
+    });
+  }
+  return out;
+}
+
+/** Just the declared contributions of one type. */
+export function contributionsOfType(manifest, type) {
+  return declaredContributions(manifest).filter((c) => c.type === type);
+}
+
+/**
+ * The indexers the server will run. Indexing is a property of the DRIVE, not of
+ * whoever happens to have a tab open: it must happen once per upload regardless of
+ * which client did the uploading, so an indexer contribution is always server-side.
+ * (Not to be confused with the `indexer` capability, which lets a plugin push its own
+ * contributions for a node it's looking at — that one is a client action.)
+ */
+export function serverIndexers(manifest) {
+  return contributionsOfType(manifest, 'indexer').map((i) => ({
+    id: i.uri, name: i.name, title: i.title || i.name, match: i.match, entry: i.entry,
+  }));
+}
+
+/** Openers a package declares, each pointing at the entry module that renders it. */
+export function declaredOpeners(manifest) {
+  return contributionsOfType(manifest, 'opener');
+}
+
+/**
+ * Parse a keymap file's contents: a JSON array of `{ key, command, when?, args? }`
+ * (an object with a `bindings` array is also accepted). Entries missing a key or a
+ * command are dropped rather than failing the whole map — one bad line shouldn't cost
+ * a plugin every other shortcut it ships.
+ */
+export function parseKeymap(text) {
+  let doc;
+  try {
+    doc = JSON.parse(text);
+  } catch (err) {
+    throw TroveError.invalid('Keymap file is not valid JSON', { cause: err });
+  }
+  const list = Array.isArray(doc) ? doc : Array.isArray(doc?.bindings) ? doc.bindings : null;
+  if (!list) throw TroveError.invalid('Keymap file must be a JSON array of bindings');
+  return list
+    .filter((b) => b && typeof b.key === 'string' && typeof b.command === 'string')
+    .map((b) => ({
+      key: b.key, command: b.command,
+      when: typeof b.when === 'string' ? b.when : null,
+      args: Array.isArray(b.args) ? b.args : undefined,
+    }));
+}
+
+/**
+ * A file-match selector, coerced into the shape `selectorMatches` actually indexes.
+ *
+ * It was passed through verbatim, so `"match": { "ext": ".demo" }` — a string where an
+ * array belongs, which no validation rejected — installed cleanly and then threw
+ * `(selector.ext || []).some is not a function` at selection time. Server-side the
+ * throw was swallowed, so the plugin backfilled nothing and indexed nothing with no
+ * error anywhere; in the browser `openersFor` is unguarded, so ONE bad declaration
+ * broke opener selection for every file in the drive.
+ */
+function normalizeMatch(match) {
+  if (!match || typeof match !== 'object' || Array.isArray(match)) return {};
+  const list = (v) => (v == null ? undefined : (Array.isArray(v) ? v : [v]).filter((x) => typeof x === 'string'));
+  const out = {};
+  const ext = list(match.ext);
+  const mime = list(match.mime ?? match.contentType);
+  if (ext) out.ext = ext;
+  if (mime) out.mime = mime;
+  // A `match` function can only come from in-process code, never from a manifest.
+  if (typeof match.match === 'function') out.match = match.match;
+  return out;
+}

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

@@ -0,0 +1,98 @@
+// Plugin identity and contribution URIs.
+//
+// A plugin is identified by its DOMAIN plus its NAME — never by a self-chosen opaque
+// id. The domain is proven (the package is signed, and the domain publishes the
+// signing key via assetlinks), so identity is verifiable rather than claimed. That
+// gives us three things at once:
+//
+//   • no squatting: only acme.com can publish acme.com/docs
+//   • versioning: acme.com/docs@2 is the same plugin as acme.com/docs@1, and a
+//     different plugin from acme.com/sheets — which a self-chosen id can't express
+//   • no cross-kind collisions: every contribution lives under its plugin, so an
+//     opener, a status slot, a register and a command can all be called "status"
+//     without colliding with each other or with another plugin's "status".
+//
+// Every contribution is addressed by a URI:
+//
+//   trove+contrib:<domain>/<plugin>/<contribution>
+//   e.g. trove+contrib:acme.com/docs/pdfViewer
+//
+// The host's own built-in contributions use the reserved `core` domain, so the
+// address space has exactly one shape:  trove+contrib:core/workbench/explorer.delete
+
+import { TroveError } from '../errors.js';
+
+export const CONTRIB_SCHEME = 'trove+contrib:';
+export const CORE_DOMAIN = 'core';
+
+// A DNS-ish domain (lowercase labels, dots) — or the reserved `core`.
+const DOMAIN_RE = /^(?:core|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+)$/;
+// A plugin or contribution name: lowercase-ish segment, no slashes or spaces.
+const NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+
+export function isValidDomain(domain) {
+  return typeof domain === 'string' && DOMAIN_RE.test(domain);
+}
+export function isValidName(name) {
+  return typeof name === 'string' && NAME_RE.test(name);
+}
+
+/** The plugin's identity: `<domain>/<name>`. Stable across versions. */
+export function pluginId(manifest) {
+  assertIdentity(manifest);
+  return `${manifest.domain}/${manifest.name}`;
+}
+
+/** The full URI for one of a plugin's contributions. */
+export function contribUri(manifest, contributionName) {
+  if (!isValidName(contributionName)) {
+    throw TroveError.invalid(`Invalid contribution name "${contributionName}"`);
+  }
+  return `${CONTRIB_SCHEME}${pluginId(manifest)}/${contributionName}`;
+}
+
+// The host's own contributions are addressed exactly like a plugin's: the reserved
+// `core` domain, and `workbench` as the package within it. So the address space has
+// one shape everywhere, and core names share a single namespace just as a plugin's do.
+export const CORE_PACKAGE = 'workbench';
+
+/** A URI for one of the host's own built-in contributions. */
+export function coreUri(name) {
+  return `${CONTRIB_SCHEME}${CORE_DOMAIN}/${CORE_PACKAGE}/${name}`;
+}
+
+/** Parse a contribution URI into its parts, or null if it isn't one. */
+export function parseContribUri(uri) {
+  if (typeof uri !== 'string' || !uri.startsWith(CONTRIB_SCHEME)) return null;
+  const rest = uri.slice(CONTRIB_SCHEME.length);
+  const i = rest.indexOf('/');
+  const j = rest.indexOf('/', i + 1);
+  if (i < 0 || j < 0) return null;
+  const domain = rest.slice(0, i);
+  const plugin = rest.slice(i + 1, j);
+  const name = rest.slice(j + 1);
+  if (!domain || !plugin || !name) return null;
+  return { domain, plugin, name, pluginId: `${domain}/${plugin}` };
+}
+
+/** Whether `uri` belongs to the plugin described by `manifest`. */
+export function ownsUri(manifest, uri) {
+  const p = parseContribUri(uri);
+  return !!p && p.pluginId === `${manifest.domain}/${manifest.name}`;
+}
+
+/**
+ * Every package must carry a verifiable identity: a domain it belongs to and a name
+ * within that domain. Anonymous/self-identified packages are not installable.
+ */
+export function assertIdentity(manifest) {
+  if (!isValidDomain(manifest?.domain)) {
+    throw TroveError.invalid(`Plugin manifest needs a valid "domain" (got ${JSON.stringify(manifest?.domain)})`);
+  }
+  if (!isValidName(manifest?.name)) {
+    throw TroveError.invalid(`Plugin manifest needs a valid "name" (got ${JSON.stringify(manifest?.name)})`);
+  }
+  if (manifest.domain === CORE_DOMAIN) {
+    throw TroveError.invalid('The "core" domain is reserved for built-in contributions');
+  }
+}