@3sln/trove 0.0.7 → 0.0.9

package/packages/web/src/bl/trust.js

@@ -0,0 +1,109 @@
+// What a plugin package's signature actually means.
+//
+// This is a security classification, not a label. It decided the same four states in two
+// different components — the installed-plugin list and the install-review dialog — with two
+// different sets of words, and the distinction that matters most was the one that drifted:
+//
+//   `invalid` is NOT `unverified`. Unverified means nobody signed it, which is the ordinary
+//   case for a plugin you got from a friend. Invalid means it WAS signed and the signature
+//   does not verify — the bytes are not the bytes that were signed. That is the one state
+//   implying someone altered the package, and the list once rendered it in the same amber as
+//   the benign case, because the two `if` ladders were maintained separately and one of them
+//   was missing a branch.
+//
+// So the classification lives here, once, and the components choose their own wording from
+// `status`. What is a security judgement is in the business layer; how many characters fit
+// in a badge is not.
+
+/**
+ * Whether a package may be installed at all, and on what terms.
+ *
+ * Three answers, because the states differ in kind rather than in degree:
+ *
+ *   - `invalid` is REFUSED. It means the package was signed and the signature does not
+ *     verify — the bytes are not the bytes that were signed. No development workflow
+ *     produces that; it means the package was altered in transit or at rest. There is
+ *     nothing for a user to weigh, so they are not asked.
+ *
+ *   - `unverified` is installable but only DELIBERATELY. Nobody signed it, which is the
+ *     ordinary state of a plugin you are writing: you cannot sign a package you are still
+ *     changing. So it stays possible, behind an acknowledgement that says what is being
+ *     given up — no publisher, no proof the code is what its author shipped.
+ *
+ *   - `signed` carries a real signature whose domain does not vouch for the key. That is a
+ *     claim to a namespace rather than a proof of one, so it is said prominently and left
+ *     to the user; refusing it would block a valid publisher whose assetlinks are merely
+ *     misconfigured.
+ *
+ * This is also what closes namespace squatting. A package claiming another publisher's
+ * domain is unverified by construction — the real domain does not publish its key — so it
+ * cannot be installed without the user being told exactly that.
+ */
+export function installPolicyFor(trust) {
+  const t = describeTrust(trust);
+  if (t.status === 'invalid') {
+    return {
+      status: t.status,
+      allowed: false,
+      requiresAcknowledgement: false,
+      headline: 'This package has been altered',
+      detail: `${t.explanation}. It was signed, and the signature does not match its contents — so it is not what its author published. Trove will not install it.`,
+    };
+  }
+  if (t.status === 'unverified') {
+    return {
+      status: t.status,
+      allowed: true,
+      requiresAcknowledgement: true,
+      headline: 'Unsigned — for development only',
+      detail: 'Nobody has signed this package, so there is no way to tell who wrote it or whether it has been altered since. Install it only if you built it yourself or you trust wherever you got it from.',
+    };
+  }
+  if (t.status === 'signed') {
+    return {
+      status: t.status,
+      allowed: true,
+      requiresAcknowledgement: false,
+      headline: 'Signed, but the domain does not vouch for the key',
+      detail: `${t.explanation}. The signature is real; what is unproven is that ${t.domain || 'the publisher'} authorised it.`,
+    };
+  }
+  return { status: t.status, allowed: true, requiresAcknowledgement: false, headline: null, detail: null };
+}
+
+/**
+ * @param {{status?: string, domain?: string, reason?: string}|null} trust
+ * @returns {{status: string, tone: string, icon: string, domain: string|null, explanation: string, severity: number}}
+ */
+export function describeTrust(trust) {
+  const t = trust || {};
+  switch (t.status) {
+    case 'verified':
+      return {
+        status: 'verified', tone: 'verified', icon: 'check', domain: t.domain || null,
+        explanation: t.domain
+          ? `Signed by a key published at ${t.domain}`
+          : 'Signed by a key the publishing domain vouches for',
+        severity: 0,
+      };
+    case 'signed':
+      return {
+        status: 'signed', tone: 'signed', icon: 'info', domain: t.domain || null,
+        explanation: t.reason || 'Signed, but the domain does not vouch for the key',
+        severity: 1,
+      };
+    case 'invalid':
+      return {
+        status: 'invalid', tone: 'invalid', icon: 'warn', domain: t.domain || null,
+        // Said plainly. This is the only state that means tampering rather than absence.
+        explanation: t.reason || 'The signature did not verify — this package may have been altered',
+        severity: 3,
+      };
+    default:
+      return {
+        status: 'unverified', tone: 'unverified', icon: 'warn', domain: t.domain || null,
+        explanation: t.reason || 'This plugin is not signed',
+        severity: 2,
+      };
+  }
+}

package/packages/web/src/bl/viewState.js

@@ -0,0 +1,60 @@
+// View state: what the UI is in the middle of doing.
+//
+// Which keybinding is mid-capture, what has been typed into a dialog that has not been
+// submitted, which capabilities are ticked in a plugin review. None of it is drive state —
+// it is thrown away when the dialog closes — but all of it decides what is on screen, and
+// anything that decides what is on screen is engine state. A component reads it through a
+// query and writes it through an action, the same as everything else.
+//
+// The history is worth keeping because it went wrong twice in the same direction. It began
+// as module-level `let`s mutated in place, with a `rerender()` hook threaded through
+// fourteen modules so the leaf that changed one could poke the root into redrawing — data
+// down, invalidation back up out of band. Moving it into a cell fixed the invalidation and
+// left a second version of the same mistake: components still READ it by calling the module
+// during their own render, and two of them WROTE to it there as well, to lazily initialise a
+// default. A render that writes state is a render with a side effect.
+//
+// So this is a resource now, and the lazy-initialise trick is gone: where a component used
+// to write a default on first render, it now computes one and writes nothing until the user
+// does something. `ref` is what makes that possible — it records which dialog instance the
+// value belongs to, so a stale entry is simply ignored rather than needing to be cleared.
+//
+// The holder itself is a slice in bl/state.js; what stays here is how to read one.
+
+/**
+ * The slice for `key`, or `fallback` when it belongs to a different dialog instance.
+ *
+ * Two components keep a draft that must reset when the dialog is reopened. They used to do
+ * that by writing the default during the render that noticed the mismatch. Deriving it
+ * instead means the render stays a pure function of the state it was given, and the first
+ * write happens when the user actually changes something.
+ *
+ * @param {object} slice the view-state slice from the query
+ * @param {string} key
+ * @param {object} ref the dialog instance the value must belong to
+ * @param {any} fallback
+ */
+export function draftFor(slice, key, ref, fallback) {
+  const held = slice?.[key];
+  return held && held.ref === ref ? held : { ref, ...fallback };
+}
+
+/** Where a prompt dialog's typed value lives while it is being typed. */
+export const PROMPT = 'promptValue';
+
+/**
+ * What has been typed into the open prompt, or its initial value.
+ *
+ * The prompt kept this in a `let` closed over by the render and mutated by the input
+ * handler, and handed it back through an `onSubmit` callback — which meant a FUNCTION was
+ * living in the dialog spec, and the dialog spec is engine state. Keeping the value here
+ * instead lets a prompt carry actions like everything else, and each action reads what was
+ * typed rather than being handed it.
+ *
+ * `ref` ties it to the dialog instance, so reopening starts from the new initial value
+ * rather than whatever the last prompt left behind.
+ */
+export function promptValueOf(slice, dialog) {
+  const held = slice?.[PROMPT];
+  return held && held.ref === dialog ? held.value : (dialog?.value ?? '');
+}

package/packages/web/src/bl/views.js

@@ -0,0 +1,64 @@
+// Which of the registered views should draw the results.
+//
+// The reactive half — which views exist, their when-clauses, which one the user pinned —
+// is the `views` query. This is the rest: arithmetic over the items on screen.
+//
+// Still a plain function rather than part of that query only because the launcher assembles
+// the items mid-render. They are themselves derived from the explorer and search state, so
+// this folds into a query as soon as that assembly does.
+//
+// It lived in ui/components/views/index.js, which was half a job: the registry reads moved
+// into the engine and the DECISION stayed in the render layer. Choosing a layout from what
+// a collection contains is a claim about the drive, not about markup.
+
+/** Where a pinned view choice is remembered. */
+export const SETTING = 'explorer.view';
+
+/**
+ * The view to draw with, in order of how much someone meant it.
+ *
+ * 1. A saved choice — they pressed a button. Nothing infers its way past that.
+ * 2. The search transformer's hint, when there is a search on screen. It read the
+ *    sentence: "photos from the trip last summer" is a request for a gallery as much as
+ *    it is a query, and nothing downstream can recover that from a list of content types.
+ * 3. A view whose `match` suits what is actually there — a collection of photographs
+ *    opens as a grid without anyone asking.
+ * 4. The highest priority, which is the list.
+ *
+ * A hint naming a view this build doesn't have is ignored, not an error: the transformer
+ * is deployment configuration and may outlive the build it was written against.
+ *
+ * PURE. It used to take `platform` and read the contribution registry, the context keys and
+ * the settings mid-render — three reads that nothing invalidated on, so the launcher only
+ * kept up because the shell's snapshot was coarse enough to redraw it anyway. The reactive
+ * half is the `views` query now; what is left is arithmetic over the items already on
+ * screen, which is the one input that cannot be a query (there is no sensible key for "these
+ * forty search results").
+ *
+ * @param {{views: Array, saved: string|null}} slice from the `views` query
+ * @param {Array} items the rows being drawn, `{ node }`-shaped
+ * @param {string|null} hint the search transformer's suggestion, if this is a search
+ */
+export function pickView({ views = [], saved = null } = {}, items = [], hint = null) {
+  if (!views.length) return null;
+  const chosen = saved && views.find((v) => v.id === saved);
+  if (chosen) return chosen;
+  const suggested = hint && views.find((v) => v.id === hint);
+  if (suggested) return suggested;
+  const nodes = items.map((i) => i.node).filter(Boolean);
+  if (nodes.length >= 3) {
+    const suits = (v) => v.match && Object.keys(v.match).length
+      && nodes.filter((n) => matchesView(v, n)).length / nodes.length > 0.6;
+    const fitted = views.find(suits);
+    if (fitted) return fitted;
+  }
+  return views[0];
+}
+
+function matchesView(view, node) {
+  const ct = node.contentType || '';
+  const name = (node.name || '').toLowerCase();
+  const ext = name.includes('.') ? name.slice(name.lastIndexOf('.')) : '';
+  if ((view.match.ext || []).includes(ext)) return true;
+  return (view.match.mime || []).some((m) => (m.endsWith('/*') ? ct.startsWith(m.slice(0, -1)) : ct === m));
+}

package/packages/web/src/bl/watchQuery.js

@@ -0,0 +1,73 @@
+// Reading an engine query from the render layer.
+//
+// Mostly this exists to be the ONE place that knows how a query reaches a component. The
+// bridging itself is a single call; the value is that it is not re-derived at fifteen call
+// sites, and that if it ever needs an initial value or an error view, there is somewhere to
+// put it.
+//
+// `engine.query(q)` answers an observable — `subscribe({next, error, complete})` — and dodo's
+// `watch` takes a Cell — `onDirty(fn)` plus `getValue()`. `fromObservable` already bridges
+// exactly those two shapes, so this is thin on purpose: the point is that there is ONE place
+// that knows how a query reaches a component, rather than the adapter being re-derived at
+// every call site.
+//
+// The subscription belongs to the CELL, not to the component: dodo connects a cell when its
+// first watcher attaches and disconnects when the last one leaves, which is the same
+// lifetime ngin gives a query realization. So a region that scrolls out of the tree stops
+// observing, the query's `kill` runs, and whatever it was holding is released — without any
+// component writing teardown.
+//
+// See docs/tickets/009.
+
+import { fromObservable, PENDING } from '../runtime.js';
+
+/**
+ * Cache the bridged cell per (engine, query instance).
+ *
+ * Not, as this first claimed, because two cells would "undo ngin's sharing" — they would
+ * not. Measured: two independent `fromObservable(engine.query(q))` over one instance boot
+ * the query ONCE and kill it once, because ngin shares the realization by instance and does
+ * not care how many observers arrive or through what. The sharing was never at risk.
+ *
+ * What the cache actually buys is smaller and worth stating accurately:
+ *
+ *   - **Idempotence.** `watchQuery` can be called freely and returns the same cell, so it
+ *     is safe in a render. Without it, `watch` — which compares its source by identity and
+ *     resubscribes when it changes — would tear down and re-establish every pass.
+ *   - **One fan-out per change** instead of one per bridge. Each extra cell is another
+ *     observer on the controller and another invalidation to propagate.
+ *
+ * Neither is correctness, so this is an optimisation and a convenience, not a safeguard.
+ * The safeguard against duplicate realizations is interning the query instance — see
+ * bl/intern.js, which is where that problem is actually solved.
+ *
+ * Weak on the engine so a disposed engine takes its cells with it, and weak on the query so
+ * an interned instance that falls out of use does too.
+ */
+const cells = new WeakMap();
+
+/**
+ * @param {object} engine
+ * @param {object} queryInstance an INTERNED instance — see bl/intern.js
+ * @returns {object} a dodo Cell, PENDING until the query produces its first value
+ */
+export function watchQuery(engine, queryInstance) {
+  let forEngine = cells.get(engine);
+  if (!forEngine) {
+    forEngine = new WeakMap();
+    cells.set(engine, forEngine);
+  }
+  let cell = forEngine.get(queryInstance);
+  if (!cell) {
+    // A query may declare what it means before it knows — `initial = null` for something
+    // fetched over the network, say. Without one the cell is PENDING, and PENDING reaching
+    // a `watch` renders its placeholder: fine for a region that can show an empty bar for a
+    // frame, wrong for a snapshot feeding the whole shell, which would blank until the
+    // request came back. The initial belongs to the query rather than to this call, so it
+    // cannot differ between two call sites reading the same thing.
+    const initial = 'initial' in queryInstance ? queryInstance.initial : PENDING;
+    cell = fromObservable(engine.query(queryInstance), { initial });
+    forEngine.set(queryInstance, cell);
+  }
+  return cell;
+}

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

@@ -238,6 +238,28 @@ export class TroveApiClient {
     return this.request('POST', '/api/collections', { body });
   }
 
+  /** Change a collection's settings — including turning encryption on. */
+  updateCollection(id, patch) {
+    return this.request('PATCH', `/api/collections/${encodeURIComponent(id)}`, { body: patch });
+  }
+
+  // --- key rotation ---------------------------------------------------------
+  //
+  // What a rotation would cost before anyone starts one: on a metered store it is a real
+  // bill, and the button should not be the first place that becomes apparent.
+  rotationEstimate(id) {
+    return this.request('GET', `/api/collections/${encodeURIComponent(id)}/rotate/estimate`);
+  }
+  rotationState(id) {
+    return this.request('GET', `/api/collections/${encodeURIComponent(id)}/rotate`);
+  }
+  beginRotation(id) {
+    return this.request('POST', `/api/collections/${encodeURIComponent(id)}/rotate`);
+  }
+  cancelRotation(id) {
+    return this.request('DELETE', `/api/collections/${encodeURIComponent(id)}/rotate`);
+  }
+
   // --- conversations, tags, sidecar ------------------------------------------
   sidecar(id) {
     return this.request('GET', `/api/items/${encodeURIComponent(id)}/sidecar`);
@@ -387,32 +409,57 @@ export class TroveApiClient {
   async upload(file, opts) {
     const name = opts.name || file.name || 'untitled';
     const size = file.size;
-    const plan = await this.request('POST', `${this.#scope(opts.collection)}/uploads`, {
-      body: { name, size, contentType: file.type || undefined },
+    // Every step of an upload is retried, not just the parts.
+    //
+    // Multipart parts already had this; nothing else did — so a transient failure on
+    // `create`, on the single presigned PUT, or on `complete` killed the whole upload on
+    // the first stumble, while the same failure mid-multipart was shrugged off. The
+    // single-PUT path is the one most uploads take (anything under the multipart floor),
+    // which is to say the retries were on the rarer half.
+    //
+    // `withRetry` decides what is worth retrying — see errors.js. Notably a lost upload
+    // session is NOT retryable, and must not be: a session that has genuinely expired or
+    // been aborted will never come back, and hammering it just delays the error. That
+    // case is what the manual retry is for.
+    const step = (fn) => withRetry(fn, {
       signal: opts.signal,
+      retries: 4,
+      onRetry: ({ attempt, delayMs, error }) => opts.onRetry?.({ attempt, delayMs, message: error.message }),
     });
+
+    const plan = await step(() => this.request('POST', `${this.#scope(opts.collection)}/uploads`, {
+      body: { name, size, contentType: file.type || undefined },
+      signal: opts.signal,
+    }));
     // Hand the caller the server upload id so a cancel/failure can abort the session
     // (otherwise a multipart upload leaks server + storage state).
     if (plan.uploadId) opts.onStart?.(plan.uploadId);
 
+    // Progress is measured against what TRAVELS, which is now the file itself even for an
+    // encrypted collection: the drive seals it on the way to the store, so nothing larger
+    // than the file ever leaves this tab.
     const progress = new ProgressAggregator(size, opts.onProgress);
     const t = plan.transfer || {};
     const completeUrl = plan.endpoints?.complete || `/api/uploads/${plan.uploadId}/complete`;
 
     if (plan.strategy === 'single') {
-      // One presigned PUT straight to storage (bytes never touch our server).
-      await xhrPut(t.url || plan.url, file, { headers: t.requiredHeaders, signal: opts.signal, onProgress: (l) => progress.set('single', l) });
-      const done = await this.request('POST', completeUrl, { body: {}, signal: opts.signal });
+      // One presigned PUT straight to storage (bytes never touch our server). The plan
+      // only ever chooses this for an UNENCRYPTED collection now — a presigned PUT of a
+      // file this client has not sealed would put plaintext in the bucket.
+      const body = file;
+      await step(() => xhrPut(t.url || plan.url, body, { headers: t.requiredHeaders, signal: opts.signal, onProgress: (l) => progress.set('single', l) }));
+      const done = await step(() => this.request('POST', completeUrl, { body: {}, signal: opts.signal }));
       return done.node;
     }
     if (plan.strategy === 'direct-single') {
-      await xhrPut(this.baseUrl + this.#partUrl(plan, 1), file, {
+      const body = file;
+      await step(() => xhrPut(this.baseUrl + this.#partUrl(plan, 1), body, {
         // Our own server, so it needs our bearer token; `t.authHeaders` lets the plan
         // add its own and wins on a clash.
         headers: { ...this.authHeaders(), ...t.authHeaders },
         signal: opts.signal, onProgress: (l) => progress.set(1, l),
-      });
-      const done = await this.request('POST', completeUrl, { body: {}, signal: opts.signal });
+      }));
+      const done = await step(() => this.request('POST', completeUrl, { body: {}, signal: opts.signal }));
       return done.node;
     }
 
@@ -459,7 +506,11 @@ export class TroveApiClient {
           () => this.#uploadPart(plan, n, blob, {
             signal: inner.signal, onProgress: (l) => progress.set(n, l),
           }),
-          { signal: inner.signal, retries: 4 },
+          {
+            signal: inner.signal,
+            retries: 4,
+            onRetry: ({ attempt, delayMs, error }) => opts.onRetry?.({ attempt, delayMs, part: n, message: error.message }),
+          },
         );
         results[n - 1] = { partNumber: n, etag };
       }
@@ -474,9 +525,9 @@ export class TroveApiClient {
     }
 
     const reportedParts = results.filter(Boolean);
-    const done = await this.request('POST', completeUrl, {
+    const done = await step(() => this.request('POST', completeUrl, {
       body: { parts: reportedParts }, signal: opts.signal,
-    });
+    }));
     return done.node;
   }
 
@@ -486,6 +537,7 @@ export class TroveApiClient {
     return tmpl.replace('{partNumber}', String(n));
   }
 
+
   async #uploadPart(plan, n, blob, { signal, onProgress }) {
     const t = plan.transfer || {};
     if (plan.strategy === 'presign') {

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

@@ -15,16 +15,30 @@ export class CommandService {
     this.contributions = contributions;
     this.context = context;
     this.notifications = notifications;
-    this.handlers = new Map(); // id -> fn
+    this.handlers = new Map(); // id -> (...args) => Action | Action[] | null
+    // How a resolved command reaches the engine. Filled in by createApp, because this
+    // service is built with the rest of the platform and the engine does not exist yet.
+    //
+    // It is a seam rather than a smell: keystrokes and plugin RPC arrive from outside the
+    // engine and something has to carry them in. Until it is set, a command says so instead
+    // of silently doing nothing.
+    this.dispatch = () => {
+      throw new Error('CommandService has no dispatcher yet — see createApp');
+    };
   }
 
   /**
-   * Register a command. Accepts either register(id, handler) or a full spec
-   * object { id, title, handler, category, icon, when, palette }.
+   * Register a command. Accepts either register(id, actions) or a full spec object
+   * { id, title, actions, category, icon, when, palette }.
+   *
+   * `actions` is a PURE FACTORY: `(...args) => Action | Action[] | null`. It is not a
+   * handler, and the difference is the point — a handler did the work, which meant every
+   * menu item, keybinding and palette entry a person triggered went around the engine. A
+   * factory only says what should be dispatched, and `execute` dispatches it.
    */
-  register(idOrSpec, handler) {
-    const spec = typeof idOrSpec === 'string' ? { id: idOrSpec, handler } : idOrSpec;
-    if (spec.handler) this.handlers.set(spec.id, spec.handler);
+  register(idOrSpec, actions) {
+    const spec = typeof idOrSpec === 'string' ? { id: idOrSpec, actions } : idOrSpec;
+    if (spec.actions) this.handlers.set(spec.id, spec.actions);
     const dispose = this.contributions.register(spec.id, {
       type: 'command',
       title: spec.title ?? spec.id,
@@ -58,9 +72,20 @@ export class CommandService {
     return this.availability ? this.availability(cmd) : true;
   }
 
+  /**
+   * Run a command: resolve what it means, then dispatch it.
+   *
+   * The gating stays here rather than moving into an action, because it is the same three
+   * questions for every command however it was triggered — does it exist, is the plugin
+   * behind it answering, does its when-clause hold — and answering them in one place is
+   * what keeps a keybinding and a palette entry behaving identically.
+   *
+   * What is NOT here any more is the work. `actions` returns descriptions and this
+   * dispatches them, so the engine sees the command AND everything it causes.
+   */
   async execute(id, ...args) {
-    const handler = this.handlers.get(id);
-    if (!handler) {
+    const actionsFor = this.handlers.get(id);
+    if (!actionsFor) {
       this.notifications.error(`Command not found: ${id}`);
       return;
     }
@@ -71,7 +96,22 @@ export class CommandService {
     }
     if (!this.isEnabled(id)) return; // gated by when-clause
     try {
-      return await handler(...args);
+      const actions = actionsFor(...args);
+      if (!actions) return;
+      // One at a time, each genuinely finished before the next begins.
+      //
+      // `dispatch` answers an event FEED, not a promise for the work — awaiting it resolves
+      // immediately and the action runs afterwards, so a bare `await dispatch(a)` in a loop
+      // would start all of them at once while looking like it sequenced them. `next` on the
+      // terminal events is the actual completion signal.
+      //
+      // It resolves with whichever of complete/error/abort fired rather than rejecting, so
+      // a failing action does not throw here — but it does stop the rest, because a command
+      // whose first step failed rarely wants its second.
+      for (const action of [].concat(actions)) {
+        const settled = await this.dispatch(action).next(['complete', 'error', 'abort']);
+        if (settled?.type !== 'complete') break;
+      }
     } catch (err) {
       console.error(`Command ${id} failed`, err);
       this.notifications.error(err?.message || `Command failed: ${id}`);