@openparachute/hub 0.5.10-rc.6 → 0.5.10

package/src/oauth-ui.ts

@@ -82,6 +82,28 @@ export interface ConsentViewProps {
    * vault-config-and-scopes design — force the picker, don't default).
    */
   vaultPicker?: VaultPicker;
+  /**
+   * Named-vault display: substitute unnamed `vault:<verb>` rows with
+   * `vault:<displayVault>:<verb>` in the rendered scope list so the user
+   * sees the scope shape that will actually be minted into the token. The
+   * raw `scopes` value still drives the form-roundtrip; this only changes
+   * what the operator reads.
+   *
+   * - Non-admin user (assigned_vault set): pass the assigned vault name so
+   *   the row reads `vault:my-vault:read`.
+   * - Admin user with a single vault available + the picker pre-checks the
+   *   first option: pass that name so the displayed scope matches what the
+   *   default-Approve will mint.
+   * - Admin user with multiple vaults / no obvious default: pass `null` (or
+   *   omit) and the row renders as `vault:<TBD>:read` with a tooltip
+   *   pointing at the picker. Same explanation either way.
+   *
+   * Closes the "raw scope display" leg of the approval-UX bug — silent
+   * narrowing at mint surprised operators who thought they were granting
+   * vault-wide access. Now they see the named form on the consent screen
+   * itself.
+   */
+  displayVault?: string | null;
 }
 
 export interface VaultPicker {
@@ -89,6 +111,20 @@ export interface VaultPicker {
   unnamedVerbs: string[];
   /** Vault names registered on this host. Empty → caller can't approve. */
   availableVaults: string[];
+  /**
+   * Multi-user Phase 1 (design 2026-05-20-multi-user-phase-1.md, decision-pin
+   * "consent picker for non-admin users"): set when the signed-in user has a
+   * non-null `assigned_vault`. The picker renders the vault name as a
+   * read-only label with an admin-managed note instead of the free dropdown
+   * — the user can't choose a different vault. The form still POSTs the
+   * locked value via `vault_pick` so the server-side defense in
+   * `handleConsentSubmit` (which refuses mints whose picked vault disagrees
+   * with the user's `assigned_vault`) sees an unambiguous value.
+   *
+   * Admin users (assigned_vault === null) leave this undefined and see the
+   * full dropdown — existing behavior.
+   */
+  lockedVault?: string;
 }
 
 export interface ErrorViewProps {
@@ -99,10 +135,22 @@ export interface ErrorViewProps {
 
 /**
  * Props for the "App not yet approved" view rendered when an unapproved
- * client lands on `/oauth/authorize`. When `session` is true the operator is
- * authenticated to this hub from the browser making the request, so we render
- * an inline approve form (closes #208). When false we fall back to the
- * pre-#208 CLI-only message.
+ * client lands on `/oauth/authorize`. Two-branch UI:
+ *
+ *   - Authenticated admin (operator session present + same-origin) — render
+ *     the inline approve form (closes #208). One click flips the client to
+ *     `approved` and re-enters the OAuth flow at consent.
+ *   - Unauthenticated viewer — render TWO CTAs (no terminal mention):
+ *       1. Primary: "Sign in as admin to approve" → links to
+ *          `/login?next=/admin/approve-client/<client_id>` so the admin
+ *          lands directly on the approval page after sign-in.
+ *       2. Secondary: a fully-qualified shareable deep link to
+ *          `<hub_origin>/admin/approve-client/<client_id>` with a copy
+ *          button — the operator can send it to whoever runs the hub.
+ *
+ *   The CLI fallback (`parachute auth approve-client <id>`) was retired —
+ *   the web path is the path now. Operators who want the CLI still have it
+ *   in the shell; we no longer point new users there from the browser.
  */
 export interface ApprovePendingViewProps {
   /** Display name to show — falls back to client_id when no name was supplied at DCR. */
@@ -119,6 +167,13 @@ export interface ApprovePendingViewProps {
    * #244). Single-vault hubs leave this absent and the section omits.
    */
   requestedVault?: string;
+  /**
+   * Fully-qualified hub origin used to build the shareable approval
+   * deep-link in the unauthenticated branch. Required because the link
+   * the operator copies needs to work when opened in a different browser
+   * session — only the absolute URL gets that.
+   */
+  hubOrigin: string;
   /**
    * When set, render the inline approve form. The form posts to
    * `/oauth/authorize/approve` with the CSRF token + a `return_to` URL the
@@ -165,14 +220,25 @@ export function renderLogin(props: LoginViewProps): string {
 }
 
 export function renderConsent(props: ConsentViewProps): string {
-  const { params, clientName, clientId, scopes, vaultPicker, csrfToken } = props;
+  const { params, clientName, clientId, scopes, vaultPicker, csrfToken, displayVault } = props;
+  // Substitute unnamed `vault:<verb>` rows with the resolved named form so
+  // the operator sees the scope shape that will appear in the token. Raw
+  // `scopes` keeps the wire form for the hidden form fields; only what's
+  // rendered changes. See `ConsentViewProps.displayVault`.
+  const displayedScopes = scopes.map((s) => substituteVaultDisplay(s, displayVault));
   const scopeRows =
-    scopes.length === 0
+    displayedScopes.length === 0
       ? `<li class="scope scope-empty">No scopes requested — the app gets a session token only.</li>`
-      : scopes.map(renderScopeRow).join("\n");
+      : displayedScopes.map(renderScopeRow).join("\n");
   const pickerSection = vaultPicker ? renderVaultPicker(vaultPicker) : "";
+  // Approve is disabled when the picker can't yield a valid vault. The
+  // empty-vault branch (no vaults registered) is the original case. A
+  // locked-vault picker (multi-user Phase 1) always has a valid value via
+  // the hidden input, so Approve stays enabled.
   const approveDisabled =
-    vaultPicker && vaultPicker.availableVaults.length === 0 ? " disabled" : "";
+    vaultPicker && vaultPicker.lockedVault === undefined && vaultPicker.availableVaults.length === 0
+      ? " disabled"
+      : "";
   const body = `
     <div class="card">
       <div class="card-header">
@@ -209,6 +275,32 @@ export function renderConsent(props: ConsentViewProps): string {
 
 function renderVaultPicker(picker: VaultPicker): string {
   const verbList = picker.unnamedVerbs.map((v) => `<code>vault:${escapeHtml(v)}</code>`).join(", ");
+
+  // Multi-user Phase 1: non-admin users see the picker locked to their
+  // `assigned_vault`. The form still posts via `vault_pick` so the
+  // server-side defense in `handleConsentSubmit` sees the value — but the
+  // user can't change it through the UI. A small `<input type=hidden>` and
+  // a read-only label is the smallest diff that ships the lock without
+  // disabling the broader form flow (Approve / Deny still work).
+  if (picker.lockedVault !== undefined) {
+    const locked = escapeHtml(picker.lockedVault);
+    return `
+        <section class="vault-picker vault-picker-locked">
+          <h2 class="scopes-title">Vault</h2>
+          <p class="picker-help">
+            ${verbList} apply to your assigned vault.
+          </p>
+          <div class="vault-locked-row">
+            <code class="vault-locked-name">${locked}</code>
+            <span class="vault-locked-badge">Assigned</span>
+          </div>
+          <p class="vault-locked-note">
+            Assigned vault — admin-managed; you can't change this here.
+          </p>
+          <input type="hidden" name="vault_pick" value="${locked}" />
+        </section>`;
+  }
+
   if (picker.availableVaults.length === 0) {
     return `
         <section class="vault-picker vault-picker-empty">
@@ -240,21 +332,32 @@ function renderVaultPicker(picker: VaultPicker): string {
 }
 
 /**
- * "App not yet approved" page (#74). When the request carries a valid
- * operator session (#208), render the inline approve form so one click lands
- * the client as `approved` and re-enters the OAuth flow at consent. Without
- * a session, fall back to the original CLI-only message — anyone hitting
- * /oauth/authorize unauthenticated to the hub itself can't be trusted to
- * approve a DCR client from the browser, so they need to drop to a terminal
- * and run `parachute auth approve-client <id>`.
+ * "App not yet approved" page (#74). Two branches:
  *
- * The CLI fallback hint is shown in BOTH branches: a button-equipped operator
- * may still want the CLI invocation handy (different machine, scriptable
- * context). The button is the easy path; the CLI is always-available.
+ *   - **Authenticated operator with same-origin posture** (#208): render the
+ *     inline approve form so one click flips the client to `approved` and
+ *     re-enters the OAuth flow at consent.
+ *   - **Unauthenticated viewer** (Issue 1 in the approval-UX PR): render a
+ *     primary "Sign in as admin to approve" CTA wired to
+ *     `/login?next=/admin/approve-client/<id>` so the admin lands directly
+ *     on the approval page after sign-in, plus a secondary shareable
+ *     deep-link section (fully-qualified `<hub_origin>/admin/approve-client/<id>`
+ *     in a code block + Copy-to-clipboard button). The pre-rc.19 CLI hint
+ *     ("ask the operator to run `parachute auth approve-client <id>`") was
+ *     retired — the web path is the path now. CLI is still available for
+ *     terminal-first operators who already know it; we just stop pointing
+ *     new users there from a browser they're already in.
  */
 export function renderApprovePending(props: ApprovePendingViewProps): string {
-  const { clientName, clientId, redirectUris, requestedScopes, requestedVault, approveForm } =
-    props;
+  const {
+    clientName,
+    clientId,
+    redirectUris,
+    requestedScopes,
+    requestedVault,
+    hubOrigin,
+    approveForm,
+  } = props;
   const redirectList = redirectUris.map((u) => `<li><code>${escapeHtml(u)}</code></li>`).join("");
   const scopeRows =
     requestedScopes.length === 0
@@ -279,15 +382,8 @@ export function renderApprovePending(props: ApprovePendingViewProps): string {
         <input type="hidden" name="client_id" value="${escapeHtml(clientId)}" />
         <input type="hidden" name="return_to" value="${escapeHtml(approveForm.returnTo)}" />
         <button type="submit" class="btn btn-primary">Approve and continue</button>
-      </form>
-      <p class="approve-cli-hint">
-        Or run <code>parachute auth approve-client ${escapeHtml(clientId)}</code> from a terminal.
-      </p>`
-    : `
-      <p class="approve-cli-hint">
-        Ask the operator to run <code>parachute auth approve-client ${escapeHtml(clientId)}</code>
-        from a terminal, then try again.
-      </p>`;
+      </form>`
+    : renderUnauthenticatedApproveCtas(hubOrigin, clientId);
   const body = `
     <div class="card">
       <div class="card-header">
@@ -325,6 +421,111 @@ export function renderApprovePending(props: ApprovePendingViewProps): string {
   return baseDocument("App not yet approved", body);
 }
 
+/**
+ * Unauthenticated branch of `renderApprovePending`. Two CTAs:
+ *
+ *   1. Primary: "Sign in as admin to approve" → links to
+ *      `/login?next=/admin/approve-client/<client_id>` so the admin lands
+ *      on the approval page after sign-in.
+ *   2. Secondary: a fully-qualified shareable deep-link to
+ *      `<hub_origin>/admin/approve-client/<client_id>` with a Copy button
+ *      so the operator can send it to whoever runs the hub.
+ *
+ * Inline JS is scoped to the Copy button only — `navigator.clipboard.writeText`
+ * with a brief "Copied!" affordance. The button degrades gracefully when
+ * scripting is unavailable (the URL is still selectable + copyable from the
+ * `<code>` block via the OS clipboard).
+ */
+function renderUnauthenticatedApproveCtas(hubOrigin: string, clientId: string): string {
+  const approvalPath = `/admin/approve-client/${encodeURIComponent(clientId)}`;
+  const loginHref = `/login?next=${encodeURIComponent(approvalPath)}`;
+  const trimmedOrigin = hubOrigin.replace(/\/+$/, "");
+  const deepLink = `${trimmedOrigin}${approvalPath}`;
+  return `
+      <div class="approve-actions">
+        <a href="${escapeHtml(loginHref)}" class="btn btn-primary approve-signin-cta">
+          Sign in as admin to approve
+        </a>
+      </div>
+      <section class="approve-share">
+        <h2 class="scopes-title">Or send this link to your hub admin</h2>
+        <p class="approve-share-help">
+          Anyone with admin access on this hub can open the link below to approve the app.
+        </p>
+        <div class="approve-share-row">
+          <code class="approve-share-link" id="approve-share-link">${escapeHtml(deepLink)}</code>
+          <button
+            type="button"
+            class="btn btn-secondary approve-share-copy"
+            id="approve-share-copy"
+            data-link="${escapeHtml(deepLink)}"
+          >Copy link</button>
+        </div>
+      </section>
+      <script>
+        (function () {
+          var btn = document.getElementById('approve-share-copy');
+          if (!btn) return;
+          var defaultLabel = btn.textContent;
+          btn.addEventListener('click', function () {
+            var link = btn.dataset.link || '';
+            var done = function (ok) {
+              btn.textContent = ok ? 'Copied!' : 'Copy failed';
+              setTimeout(function () { btn.textContent = defaultLabel; }, 1600);
+            };
+            if (navigator.clipboard && navigator.clipboard.writeText) {
+              navigator.clipboard.writeText(link).then(function () { done(true); }, function () { done(false); });
+            } else {
+              // Fallback for browsers without async clipboard (older Safari,
+              // sandboxed iframes). Select the code block so the user can
+              // hit cmd/ctrl-C to copy manually.
+              try {
+                var range = document.createRange();
+                range.selectNode(document.getElementById('approve-share-link'));
+                var sel = window.getSelection();
+                if (sel) { sel.removeAllRanges(); sel.addRange(range); }
+                done(true);
+              } catch (e) {
+                done(false);
+              }
+            }
+          });
+        })();
+      </script>`;
+}
+
+/**
+ * Substitute an unnamed `vault:<verb>` scope with the resolved named form
+ * (`vault:<displayVault>:<verb>`) so consent / approval screens render
+ * what'll actually appear in the token rather than the raw OAuth request.
+ *
+ *   - `displayVault === undefined` → no substitution (keep input as-is).
+ *     Use this when the caller doesn't know what vault will be picked yet
+ *     and prefers the raw OAuth form. (Currently unused; reserved for the
+ *     pre-narrowing approve flow where the vault isn't known until consent.)
+ *   - `displayVault === null` → render with a `<TBD>` placeholder. Used on
+ *     the admin consent screen when the picker hasn't been touched yet, and
+ *     on the operator approval page where the vault is selected at the
+ *     per-user sign-in step, not at approve time.
+ *   - `displayVault === "name"` → render as `vault:name:verb` literally.
+ *
+ * Non-vault scopes pass through untouched. Already-named `vault:<x>:<verb>`
+ * scopes also pass through — the OAuth request already specified a vault,
+ * so there's nothing to resolve.
+ */
+export function substituteVaultDisplay(
+  scope: string,
+  displayVault: string | null | undefined,
+): string {
+  if (displayVault === undefined) return scope;
+  const parts = scope.split(":");
+  if (parts.length !== 2 || parts[0] !== "vault") return scope;
+  const verb = parts[1];
+  if (verb !== "read" && verb !== "write") return scope;
+  const vaultLabel = displayVault === null ? "<TBD>" : displayVault;
+  return `vault:${vaultLabel}:${verb}`;
+}
+
 export function renderError(props: ErrorViewProps): string {
   const body = `
     <div class="card">
@@ -344,8 +545,127 @@ export function renderError(props: ErrorViewProps): string {
   return baseDocument(props.title, body);
 }
 
+export interface UnknownClientViewProps {
+  /** The unknown client_id the request carried. Surfaced verbatim for debugging. */
+  clientId: string;
+  /**
+   * The redirect_uri the request carried, when present + parseable as
+   * `<one-of-our-bound-origins>/<path>`. Triggers the inline "Reset
+   * connection" affordance: the page emits a tiny JS snippet that clears
+   * the requesting SPA's DCR localStorage cache (any key prefixed
+   * `lens:dcr:`) on our own origin, then navigates to the redirect_uri's
+   * mount path so the SPA picks up a fresh DCR.
+   *
+   * Set to `null` when the redirect_uri is missing, malformed, or points
+   * at an origin we don't serve — those reach a third-party SPA we can't
+   * safely interact with from our DOM and we fall back to the static
+   * error variant.
+   */
+  selfOriginRedirectPath: string | null;
+}
+
+/**
+ * "Unknown application" page rendered when `/oauth/authorize` receives a
+ * `client_id` that's not in the hub's `clients` table. The single most-
+ * reported cause is a stale localStorage entry on the SPA side: the
+ * operator wiped `~/.parachute/hub.db` between testing iterations, but the
+ * browser still holds the old hub's DCR-cached client_id and keeps using
+ * it. The hub's behaviour is correct (reject unknown client_id, never
+ * grant an authorize request against an unregistered client) but the
+ * operator is stranded — they need to clear the SPA's cache and the SPA
+ * has no signal to do that on its own.
+ *
+ * Recovery affordance: when the redirect_uri points at an origin the hub
+ * itself serves (any entry in `hubBoundOrigins`), the page renders a
+ * "Reset connection" button. The button runs an inline JS snippet that
+ * clears every `lens:dcr:*` key from localStorage on the hub's own origin
+ * — since Notes (and any future Parachute SPA) is mounted at the hub's
+ * origin, they share localStorage with this error page — then navigates
+ * back to the redirect_uri's mount path. The SPA loads fresh, finds no
+ * cached client_id, and runs a brand-new DCR against the current hub.
+ *
+ * `lens:dcr:` is intentionally hardcoded: Notes' storage layer uses that
+ * prefix (see `parachute-notes/src/lib/vault/storage.ts`'s `DCR_PREFIX`).
+ * Future SPAs that follow the same hub-origin-mounted shape would need
+ * their prefix added here, or we extend the snippet to clear any key
+ * matching `.*:dcr:.*`. Today it's just Notes.
+ *
+ * No JS used outside the optional reset button — the static parts stay
+ * form-free + accessible to readers/screen-readers without script.
+ */
+export function renderUnknownClient(props: UnknownClientViewProps): string {
+  const safeClientId = escapeHtml(props.clientId);
+  const resetSection =
+    props.selfOriginRedirectPath !== null
+      ? `
+      <p>Most often this means the app's local connection state was saved
+        against a previous installation of this hub. Resetting the
+        connection clears the stale state and lets the app register
+        afresh.</p>
+      <div class="unknown-client-actions">
+        <button type="button" class="btn btn-primary" id="unknown-client-reset"
+          data-target="${escapeHtml(props.selfOriginRedirectPath)}">Reset connection &amp; reload</button>
+      </div>
+      <p class="fine">If the button doesn't help, clear site data for this
+        hub in your browser and reload the app.</p>
+      <script>
+        (function () {
+          var btn = document.getElementById('unknown-client-reset');
+          if (!btn) return;
+          btn.addEventListener('click', function () {
+            try {
+              // Notes (and other Parachute SPAs mounted at this hub's
+              // origin) cache DCR client_ids under the 'lens:dcr:' key
+              // prefix. Clear them all — a stale entry against a wiped
+              // hub.db is the canonical cause of this error.
+              var keys = [];
+              for (var i = 0; i < localStorage.length; i++) {
+                var k = localStorage.key(i);
+                if (k && k.indexOf('lens:dcr:') === 0) keys.push(k);
+              }
+              keys.forEach(function (k) { localStorage.removeItem(k); });
+            } catch (e) {
+              // localStorage may be unavailable (private mode, sandbox).
+              // The redirect still happens — the SPA will try DCR again
+              // and either succeed or surface its own diagnostic.
+            }
+            var target = btn.dataset.target || '/';
+            window.location.assign(target);
+          });
+        })();
+      </script>`
+      : `
+      <p class="error-help">
+        If you reached this from a third-party app, the app's OAuth
+        configuration may be wrong. You can safely close this window.
+      </p>`;
+  const body = `
+    <div class="card">
+      <div class="card-header">
+        <div class="brand">
+          <span class="brand-mark">⌬</span>
+          <span class="brand-name">Parachute</span>
+        </div>
+        <h1 class="error-title">Unknown application</h1>
+        <p class="subtitle">
+          This <code>client_id</code> is not registered with this hub:
+          <code>${safeClientId}</code>.
+        </p>
+      </div>
+      ${resetSection}
+    </div>`;
+  return baseDocument("Unknown application", body);
+}
+
 function renderScopeRow(scope: string): string {
-  const explanation = explainScope(scope);
+  // Special-case the `<TBD>` placeholder substituted by `substituteVaultDisplay`
+  // when the consent picker hasn't bound a vault yet — `explainScope` doesn't
+  // match it because `<` / `>` aren't in the vault-name charset, but the
+  // canonical verb-form does. Look up by the unnamed verb form so the
+  // explanation + level styling are still correct.
+  const tbdMatch = scope.match(/^vault:<TBD>:(read|write)$/);
+  const lookup = tbdMatch ? `vault:${tbdMatch[1]}` : scope;
+  const explanation = explainScope(lookup);
   if (!explanation) {
     return `<li class="scope scope-unknown">
       <code class="scope-name">${escapeHtml(scope)}</code>
@@ -354,12 +674,21 @@ function renderScopeRow(scope: string): string {
   }
   const cls = `scope scope-${explanation.level}`;
   const badge = badgeForLevel(explanation);
+  // Pending-vault hint surfaces the silent-narrowing semantics for admin
+  // operators who land on the consent screen before touching the picker.
+  // Once they pick, the form submission narrows the scope to the chosen
+  // vault — the rendered placeholder reflects that the vault is still
+  // open at this moment in the flow.
+  const pendingNote = tbdMatch
+    ? `<span class="scope-pending-note">A specific vault is picked below before approving.</span>`
+    : "";
   return `<li class="${cls}">
       <div class="scope-head">
         <code class="scope-name">${escapeHtml(scope)}</code>
         ${badge}
       </div>
       <span class="scope-label">${escapeHtml(explanation.label)}</span>
+      ${pendingNote}
     </li>`;
 }
 
@@ -561,6 +890,16 @@ const STYLES = `
     color: ${PALETTE.fgMuted};
     font-size: 0.88rem;
   }
+  .unknown-client-actions {
+    margin: 1.25rem 0 0.5rem;
+    display: flex;
+    flex-direction: column;
+    gap: 0.5rem;
+  }
+  .fine {
+    color: ${PALETTE.fgMuted};
+    font-size: 0.85rem;
+  }
 
   .scopes { margin: 0 0 1.5rem; }
   .scopes-title {
@@ -662,6 +1001,40 @@ const STYLES = `
   }
   .vault-picker-empty .picker-help { color: ${PALETTE.danger}; }
   .vault-picker-empty .picker-help code { color: ${PALETTE.fg}; }
+  .vault-picker-locked .picker-help { color: ${PALETTE.fgMuted}; }
+  .vault-locked-row {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    padding: 0.5rem 0.6rem;
+    border: 1px solid ${PALETTE.border};
+    border-radius: 6px;
+    background: ${PALETTE.cardBg};
+    margin: 0.25rem 0 0.5rem;
+  }
+  .vault-locked-name {
+    font-family: ${FONT_MONO};
+    font-size: 0.9rem;
+    color: ${PALETTE.fg};
+    flex: 1;
+  }
+  .vault-locked-badge {
+    display: inline-block;
+    font-size: 0.68rem;
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+    font-weight: 600;
+    padding: 0.1rem 0.5rem;
+    border-radius: 999px;
+    background: ${PALETTE.accentSoft};
+    color: ${PALETTE.accent};
+  }
+  .vault-locked-note {
+    margin: 0;
+    font-size: 0.82rem;
+    color: ${PALETTE.fgDim};
+    font-style: italic;
+  }
 
   .approve-meta {
     margin: 0 0 1.25rem;
@@ -713,23 +1086,63 @@ const STYLES = `
     word-break: break-all;
   }
   .approve-form { gap: 0; }
-  .approve-cli-hint {
+  .approve-actions {
     margin-top: 1rem;
-    padding-top: 0.85rem;
+    display: flex;
+    flex-direction: column;
+    gap: 0.5rem;
+  }
+  .approve-signin-cta {
+    display: inline-block;
+    text-align: center;
+    text-decoration: none;
+    line-height: 1.4;
+  }
+  .approve-signin-cta:hover {
+    background: ${PALETTE.accentHover};
+    color: ${PALETTE.cardBg};
+  }
+  .approve-share {
+    margin-top: 1.5rem;
+    padding-top: 1.25rem;
     border-top: 1px solid ${PALETTE.borderLight};
+  }
+  .approve-share-help {
+    margin: 0 0 0.6rem;
     color: ${PALETTE.fgMuted};
-    font-size: 0.85rem;
+    font-size: 0.88rem;
   }
-  .approve-cli-hint code {
+  .approve-share-row {
+    display: flex;
+    gap: 0.5rem;
+    align-items: stretch;
+    flex-wrap: wrap;
+  }
+  .approve-share-link {
+    flex: 1;
+    min-width: 0;
     font-family: ${FONT_MONO};
-    font-size: 0.8rem;
+    font-size: 0.82rem;
     background: ${PALETTE.bgSoft};
-    padding: 0.1rem 0.4rem;
-    border-radius: 4px;
+    padding: 0.55rem 0.65rem;
+    border-radius: 6px;
     color: ${PALETTE.fg};
     word-break: break-all;
+    border: 1px solid ${PALETTE.border};
+  }
+  .approve-share-copy {
+    flex-shrink: 0;
+    min-height: 0;
+    padding: 0.5rem 0.9rem;
+    font-size: 0.85rem;
+  }
+  .scope-pending-note {
+    display: block;
+    margin-top: 0.25rem;
+    font-size: 0.78rem;
+    color: ${PALETTE.fgDim};
+    font-style: italic;
   }
-
   .badge {
     display: inline-block;
     font-size: 0.7rem;

package/src/operator-token.ts

@@ -160,6 +160,10 @@ export async function mintOperatorToken(
     clientId: OPERATOR_TOKEN_CLIENT_ID,
     issuer: opts.issuer,
     ttlSeconds: opts.ttlSeconds ?? OPERATOR_TOKEN_TTL_SECONDS,
+    // Operator token — the hub-operator bearer. No per-user vault pin; the
+    // operator can act against any vault in this hub. Empty `vault_scope`
+    // is the "no restriction" sentinel (matches the admin OAuth shape).
+    vaultScope: [],
     extraClaims: { [OPERATOR_TOKEN_SCOPE_SET_CLAIM]: scopeSet },
     ...(opts.jti !== undefined ? { jti: opts.jti } : {}),
     ...(opts.now !== undefined ? { now: opts.now } : {}),

package/src/scope-explanations.ts

@@ -159,8 +159,33 @@ export function isRequestableScope(scope: string): boolean {
   return !isNonRequestableScope(scope);
 }
 
+/**
+ * Recognize narrowed vault scopes (`vault:<name>:<verb>`) and the wildcard
+ * display form (`vault:*:<verb>`) — both render with the same explanation as
+ * the corresponding unnamed `vault:<verb>` row, since they describe the same
+ * permission scoped to a specific (or unspecified-at-mint-time) vault.
+ *
+ * The hub narrows unnamed `vault:read` → `vault:<name>:read` at consent /
+ * token-mint via the picker (Q1 of the vault-config-and-scopes design); the
+ * consent screen now surfaces that narrowed form so the user sees the scope
+ * shape that will appear in the token. `vault:*:read` is the display-only
+ * shape we use on the operator approval page where no per-user vault has
+ * been selected yet (a specific vault is chosen during sign-in).
+ *
+ * Verb-only — admin verbs on a per-vault basis (`vault:<name>:admin`) are
+ * `NON_REQUESTABLE_SCOPES` by policy and never reach the consent screen, so
+ * we don't substitute for them here. Read / write get the matching label.
+ */
+const VAULT_VERB_RE = /^vault:[a-zA-Z0-9_*-]+:(read|write)$/;
+
 export function explainScope(scope: string): ScopeExplanation | null {
-  return SCOPE_EXPLANATIONS[scope] ?? null;
+  const direct = SCOPE_EXPLANATIONS[scope];
+  if (direct) return direct;
+  if (VAULT_VERB_RE.test(scope)) {
+    const verb = scope.split(":")[2] as "read" | "write";
+    return SCOPE_EXPLANATIONS[`vault:${verb}`] ?? null;
+  }
+  return null;
 }
 
 export function scopeIsAdmin(scope: string): boolean {