sh3-core 0.8.1 → 0.8.2

package/dist/Shell.svelte

@@ -25,6 +25,8 @@
   import { isAuthenticated, isLocalOwner, getUser, logout } from './auth/index';
   import iconsUrl from './assets/icons.svg';
   import GuestBanner from './auth/GuestBanner.svelte';
+  import ConsentDialog from './keys/ConsentDialog.svelte';
+  import { startServerSideStream } from './keys/revocation-bus.svelte';
 
   const authenticated = $derived(isAuthenticated());
   const user = $derived(getUser());
@@ -97,6 +99,15 @@
     }));
     return () => unbindFloatStore();
   });
+
+  // Open the server-sent events stream for key revocations.
+  // Forwards server-side revocations to the local revocation bus so that
+  // onKeyRevoked fires on the owning shard even when the user revokes from
+  // the Keys & Peers shell view (not via the shard's own ctx.keys.revoke).
+  $effect(() => {
+    const stop = startServerSideStream();
+    return stop;
+  });
 </script>
 
 <div class="shell">
@@ -165,6 +176,14 @@
       </div>
     {/each}
   </div>
+
+  <!--
+    Shell-owned consent dialog for ctx.keys.mint().
+    Mounted unconditionally so the listener is always registered; it renders
+    nothing until a shard calls ctx.keys.mint().
+    z-index 9999 (inline in the component) keeps it above all overlay layers.
+  -->
+  <ConsentDialog />
 </div>
 
 <style>

package/dist/api.d.ts

@@ -29,6 +29,9 @@ export type { RegistryIndex, PackageEntry, PackageVersion, RequiredDependency, I
 export type { ResolvedPackage } from './registry/client';
 export { fetchRegistries, fetchBundle, buildPackageMeta } from './registry/client';
 export { validateRegistryIndex } from './registry/schema';
+export { PERMISSION_KEYS_MINT, ScopeEscalationError, ConsentDeniedError, type ShardContextKeys, type ApiKeyPublic, type MintOpts, } from './keys/types';
+export { registerConsentListener, resolveConsent, type ConsentRequest } from './keys/consent.svelte';
+export { subscribe as subscribeKeyRevocation } from './keys/revocation-bus.svelte';
 export { isAdmin, isAuthenticated, isGuest, getUser, getAuthHeader } from './auth/index';
 export type { AuthUser, AuthSession, BootConfig } from './auth/types';
 /** Runtime feature flags for target-dependent behavior. */

package/dist/api.js

@@ -41,6 +41,11 @@ export { default as DocumentSyncExplorer } from './documents/sync/components/Doc
 export { registeredShards, activeShards } from './shards/activate.svelte';
 export { fetchRegistries, fetchBundle, buildPackageMeta } from './registry/client';
 export { validateRegistryIndex } from './registry/schema';
+// Key mint/revoke types — client shards that declare `keys:mint` get ctx.keys.
+export { PERMISSION_KEYS_MINT, ScopeEscalationError, ConsentDeniedError, } from './keys/types';
+export { registerConsentListener, resolveConsent } from './keys/consent.svelte';
+// Revocation bus — subscribe to key revocation events (for advanced integrations).
+export { subscribe as subscribeKeyRevocation } from './keys/revocation-bus.svelte';
 // Admin mode (framework-internal components read admin status).
 export { isAdmin, isAuthenticated, isGuest, getUser, getAuthHeader } from './auth/index';
 /** Runtime feature flags for target-dependent behavior. */

package/dist/app/admin/ApiKeysView.svelte

@@ -3,14 +3,13 @@
    * Admin API Keys view — list, create, reveal, revoke API keys.
    */
 
-  interface ApiKey {
+  interface ApiKeyPublic {
     id: string;
-    key: string;
     label: string;
     createdAt: string;
   }
 
-  let keys = $state<ApiKey[]>([]);
+  let keys = $state<ApiKeyPublic[]>([]);
   let loading = $state(true);
   let error = $state<string | null>(null);
 
@@ -19,8 +18,9 @@
   let newLabel = $state('');
   let createError = $state<string | null>(null);
 
-  // Reveal state — tracks which key ids have been revealed
-  let revealed = $state<Set<string>>(new Set());
+  // Just-created key — the raw bearer value is returned once by the server.
+  // Displayed until the admin dismisses it, then never recoverable.
+  let justCreated = $state<{ id: string; key: string } | null>(null);
 
   // Delete confirmation
   let confirmingId = $state<string | null>(null);
@@ -53,9 +53,8 @@
         createError = body.error || 'Failed to create key';
         return;
       }
-      const created: ApiKey = await res.json();
-      revealed.add(created.id);
-      revealed = new Set(revealed);
+      const created: { id: string; key: string } = await res.json();
+      justCreated = { id: created.id, key: created.key };
       newLabel = '';
       showCreate = false;
       await fetchKeys();
@@ -64,15 +63,6 @@
     }
   }
 
-  function toggleReveal(id: string) {
-    if (revealed.has(id)) {
-      revealed.delete(id);
-    } else {
-      revealed.add(id);
-    }
-    revealed = new Set(revealed);
-  }
-
   async function revokeKey(id: string) {
     confirmingId = null;
     try {
@@ -80,8 +70,7 @@
         method: 'DELETE',
         credentials: 'include',
       });
-      revealed.delete(id);
-      revealed = new Set(revealed);
+      if (justCreated?.id === id) justCreated = null;
       await fetchKeys();
     } catch { /* ignore */ }
   }
@@ -92,10 +81,6 @@
     });
   }
 
-  function maskKey(key: string): string {
-    return key.slice(0, 8) + '\u2026' + key.slice(-4);
-  }
-
   fetchKeys();
 </script>
 
@@ -107,6 +92,14 @@
     </button>
   </div>
 
+  {#if justCreated}
+    <div class="admin-key-created">
+      <div class="admin-key-created-label">New key — copy now, it won't be shown again:</div>
+      <code class="admin-key-value">{justCreated.key}</code>
+      <button type="button" class="admin-btn-secondary" onclick={() => { justCreated = null; }}>Dismiss</button>
+    </div>
+  {/if}
+
   {#if showCreate}
     <form class="admin-create-form" onsubmit={(e) => { e.preventDefault(); createKey(); }}>
       <input class="admin-input" type="text" placeholder="Key label" bind:value={newLabel} />
@@ -128,12 +121,8 @@
           <div class="admin-key-info">
             <span class="admin-key-label">{k.label}</span>
             <span class="admin-key-meta">{k.id} &middot; {formatDate(k.createdAt)}</span>
-            <code class="admin-key-value">{revealed.has(k.id) ? k.key : maskKey(k.key)}</code>
           </div>
           <div class="admin-key-actions">
-            <button type="button" class="admin-btn-secondary" onclick={() => toggleReveal(k.id)}>
-              {revealed.has(k.id) ? 'Hide' : 'Reveal'}
-            </button>
             {#if confirmingId === k.id}
               <button type="button" class="admin-btn-danger" onclick={() => revokeKey(k.id)}>Confirm</button>
               <button type="button" class="admin-btn-secondary" onclick={() => { confirmingId = null; }}>Cancel</button>

package/dist/keys/ConsentDialog.svelte

@@ -0,0 +1,176 @@
+<!--
+  Shell-owned consent dialog. Listens for consent requests and routes the
+  user's Approve/Deny back into the runtime via resolveConsent().
+
+  Mounted once by the shell at boot; never by shards.
+
+  Security: all shard-provided strings (shardId, label, scope, connectorId)
+  are rendered as plain text via Svelte's default interpolation — no @html.
+-->
+<script lang="ts">
+  import { registerConsentListener, resolveConsent, type ConsentRequest } from './consent.svelte';
+
+  let current = $state<ConsentRequest | null>(null);
+
+  $effect(() => {
+    const off = registerConsentListener((req) => { current = req; });
+    return off;
+  });
+
+  function approve(): void {
+    if (!current) return;
+    resolveConsent(current.requestId, true);
+    current = null;
+  }
+
+  function deny(): void {
+    if (!current) return;
+    resolveConsent(current.requestId, false);
+    current = null;
+  }
+</script>
+
+{#if current}
+  <div class="sh3-consent-backdrop" role="dialog" aria-modal="true" aria-label="Key creation consent">
+    <div class="sh3-consent-card">
+      <h2 class="sh3-consent-title">
+        <span>{current.shardId}</span> wants to create a key
+      </h2>
+      <dl class="sh3-consent-fields">
+        <dt>Label</dt>
+        <dd>{current.label}</dd>
+        <dt>Scopes</dt>
+        <dd class="sh3-consent-scopes">
+          {#each current.scopes as s (s)}
+            <code class="sh3-consent-scope">{s}</code>
+          {/each}
+        </dd>
+        {#if current.connectorId}
+          <dt>Connector</dt>
+          <dd>{current.connectorId}</dd>
+        {/if}
+        {#if current.expiresIn}
+          <dt>Expires in</dt>
+          <dd>{Math.round(current.expiresIn / 1000)}s</dd>
+        {/if}
+      </dl>
+      <div class="sh3-consent-actions">
+        <!-- Deny has autofocus — safe default per spec -->
+        <button type="button" class="sh3-consent-deny" onclick={deny} autofocus>Deny</button>
+        <button type="button" class="sh3-consent-approve" onclick={approve}>Approve</button>
+      </div>
+    </div>
+  </div>
+{/if}
+
+<style>
+  .sh3-consent-backdrop {
+    position: fixed;
+    inset: 0;
+    background: rgba(0, 0, 0, 0.55);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    z-index: 9999;
+  }
+
+  .sh3-consent-card {
+    background: var(--shell-bg-elevated, #222);
+    color: var(--shell-fg, #eee);
+    border: 1px solid var(--shell-border, #444);
+    padding: 1.5rem;
+    border-radius: 8px;
+    min-width: 360px;
+    max-width: 520px;
+    box-shadow: 0 8px 32px rgba(0, 0, 0, 0.4);
+  }
+
+  .sh3-consent-title {
+    margin: 0 0 1rem;
+    font-size: 1rem;
+    font-weight: 600;
+    color: var(--shell-fg, #eee);
+  }
+
+  .sh3-consent-title span {
+    color: var(--shell-accent, #7eb8f7);
+  }
+
+  .sh3-consent-fields {
+    margin: 0 0 1rem;
+    display: grid;
+    grid-template-columns: auto 1fr;
+    column-gap: 0.75rem;
+    row-gap: 0.25rem;
+    align-items: baseline;
+  }
+
+  .sh3-consent-fields dt {
+    font-weight: 600;
+    color: var(--shell-fg-muted, #aaa);
+    font-size: 0.8rem;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    padding-top: 0.35rem;
+  }
+
+  .sh3-consent-fields dd {
+    margin: 0;
+    padding-top: 0.35rem;
+    word-break: break-word;
+  }
+
+  .sh3-consent-scopes {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.25rem;
+  }
+
+  .sh3-consent-scope {
+    display: inline-block;
+    padding: 0.1rem 0.35rem;
+    background: rgba(255, 255, 255, 0.08);
+    border: 1px solid rgba(255, 255, 255, 0.12);
+    border-radius: 3px;
+    font-size: 0.82em;
+    font-family: var(--shell-font-mono, monospace);
+  }
+
+  .sh3-consent-actions {
+    display: flex;
+    justify-content: flex-end;
+    gap: 0.5rem;
+    margin-top: 1.25rem;
+  }
+
+  .sh3-consent-deny,
+  .sh3-consent-approve {
+    padding: 0.4rem 1rem;
+    border-radius: 4px;
+    font-size: 0.875rem;
+    cursor: pointer;
+    border: 1px solid transparent;
+    transition: opacity 0.1s;
+  }
+
+  .sh3-consent-deny {
+    background: transparent;
+    color: var(--shell-fg-muted, #aaa);
+    border-color: var(--shell-border, #444);
+  }
+
+  .sh3-consent-deny:hover {
+    color: var(--shell-fg, #eee);
+    border-color: var(--shell-fg-muted, #aaa);
+  }
+
+  .sh3-consent-approve {
+    background: var(--shell-accent, #7eb8f7);
+    color: #000;
+    border-color: var(--shell-accent, #7eb8f7);
+  }
+
+  .sh3-consent-approve:hover {
+    opacity: 0.85;
+  }
+</style>

package/dist/keys/ConsentDialog.svelte.d.ts

@@ -0,0 +1,3 @@
+declare const ConsentDialog: import("svelte").Component<Record<string, never>, {}, "">;
+type ConsentDialog = ReturnType<typeof ConsentDialog>;
+export default ConsentDialog;

package/dist/keys/client.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Client-side ctx.keys factory. Calls /api/keys endpoints with the current
+ * session cookie (no bearer token — session auth is the only supported
+ * principal for this API).
+ *
+ * The shard's manifest permissions are enforced here (scope subset check)
+ * before the consent dialog is even shown.
+ */
+import type { ShardContextKeys } from './types';
+export declare function createShardKeysApi(params: {
+    shardId: string;
+    shardPermissions: string[];
+}): ShardContextKeys;

package/dist/keys/client.js

@@ -0,0 +1,65 @@
+/**
+ * Client-side ctx.keys factory. Calls /api/keys endpoints with the current
+ * session cookie (no bearer token — session auth is the only supported
+ * principal for this API).
+ *
+ * The shard's manifest permissions are enforced here (scope subset check)
+ * before the consent dialog is even shown.
+ */
+import { ConsentDeniedError, ScopeEscalationError } from './types';
+import { requestConsent } from './consent.svelte';
+import { emit } from './revocation-bus.svelte';
+export function createShardKeysApi(params) {
+    const { shardId, shardPermissions } = params;
+    const assertScopesSubset = (scopes) => {
+        for (const s of scopes) {
+            if (!shardPermissions.includes(s) && !shardPermissions.includes('admin:*')) {
+                throw new ScopeEscalationError(s);
+            }
+        }
+    };
+    return {
+        async mint(opts) {
+            assertScopesSubset(opts.scopes);
+            const approved = await requestConsent(shardId, opts);
+            if (!approved)
+                throw new ConsentDeniedError();
+            const ticketRes = await fetch('/api/keys/consent', {
+                method: 'POST',
+                credentials: 'include',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(Object.assign({ shardId }, opts)),
+            });
+            if (!ticketRes.ok)
+                throw new Error(`Consent ticket failed: ${ticketRes.status}`);
+            const { ticket } = await ticketRes.json();
+            const mintRes = await fetch('/api/keys', {
+                method: 'POST',
+                credentials: 'include',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ ticket }),
+            });
+            if (!mintRes.ok)
+                throw new Error(`Mint failed: ${mintRes.status}`);
+            return mintRes.json();
+        },
+        async list() {
+            const res = await fetch('/api/keys', { credentials: 'include' });
+            if (!res.ok)
+                throw new Error(`List failed: ${res.status}`);
+            const all = (await res.json());
+            return all.filter((k) => k.mintedByShardId === shardId);
+        },
+        async revoke(id) {
+            const res = await fetch(`/api/keys/${encodeURIComponent(id)}`, {
+                method: 'DELETE',
+                credentials: 'include',
+            });
+            if (!res.ok && res.status !== 404)
+                throw new Error(`Revoke failed: ${res.status}`);
+            // Notify local bus immediately so the owning shard's onKeyRevoked fires
+            // even if the SSE stream hasn't delivered the server-side echo yet.
+            emit(shardId, id);
+        },
+    };
+}

package/dist/keys/client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/keys/client.test.js

@@ -0,0 +1,44 @@
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import { createShardKeysApi } from './client';
+import { ScopeEscalationError, ConsentDeniedError } from './types';
+import { registerConsentListener, resolveConsent } from './consent.svelte';
+describe('createShardKeysApi', () => {
+    beforeEach(() => {
+        vi.stubGlobal('fetch', vi.fn());
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it('throws ScopeEscalationError when minting outside declared scopes', async () => {
+        const api = createShardKeysApi({ shardId: 'x', shardPermissions: ['state:manage'] });
+        await expect(api.mint({ label: 'l', scopes: ['documents:sync'] })).rejects.toBeInstanceOf(ScopeEscalationError);
+    });
+    it('throws ConsentDeniedError when the user denies', async () => {
+        const off = registerConsentListener((req) => {
+            queueMicrotask(() => resolveConsent(req.requestId, false));
+        });
+        try {
+            const api = createShardKeysApi({ shardId: 'x', shardPermissions: ['documents:sync'] });
+            await expect(api.mint({ label: 'l', scopes: ['documents:sync'] })).rejects.toBeInstanceOf(ConsentDeniedError);
+        }
+        finally {
+            off();
+        }
+    });
+    it('mints when consent approves and server responds', async () => {
+        const off = registerConsentListener((req) => {
+            queueMicrotask(() => resolveConsent(req.requestId, true));
+        });
+        const fetchMock = vi.mocked(fetch);
+        fetchMock.mockResolvedValueOnce(new Response(JSON.stringify({ ticket: 'tk_1' }), { status: 200 }));
+        fetchMock.mockResolvedValueOnce(new Response(JSON.stringify({ id: 'abc', key: 'sh3_xyz' }), { status: 200 }));
+        try {
+            const api = createShardKeysApi({ shardId: 'sh', shardPermissions: ['documents:sync'] });
+            const out = await api.mint({ label: 'l', scopes: ['documents:sync'] });
+            expect(out.key).toBe('sh3_xyz');
+        }
+        finally {
+            off();
+        }
+    });
+});

package/dist/keys/consent.svelte.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Shell-owned consent runtime — only place that can approve or deny a mint.
+ *
+ * The client shard calls requestConsent(); the shell shows ConsentDialog.svelte
+ * and calls resolveConsent(...) on user action.
+ */
+import type { MintOpts } from './types';
+export interface ConsentRequest extends MintOpts {
+    requestId: string;
+    shardId: string;
+}
+type Listener = (req: ConsentRequest) => void;
+export declare function registerConsentListener(fn: Listener): () => void;
+export declare function requestConsent(shardId: string, opts: MintOpts): Promise<boolean>;
+export declare function resolveConsent(requestId: string, approved: boolean): void;
+export {};

package/dist/keys/consent.svelte.js

@@ -0,0 +1,29 @@
+/**
+ * Shell-owned consent runtime — only place that can approve or deny a mint.
+ *
+ * The client shard calls requestConsent(); the shell shows ConsentDialog.svelte
+ * and calls resolveConsent(...) on user action.
+ */
+const pending = new Map();
+let listener = null;
+export function registerConsentListener(fn) {
+    listener = fn;
+    return () => { if (listener === fn)
+        listener = null; };
+}
+export async function requestConsent(shardId, opts) {
+    if (!listener)
+        throw new Error('No consent listener registered — the shell must mount ConsentDialog.');
+    const requestId = `c_${Math.random().toString(36).slice(2)}${Date.now()}`;
+    return new Promise((resolve) => {
+        pending.set(requestId, { resolve });
+        listener(Object.assign(Object.assign({}, opts), { shardId, requestId }));
+    });
+}
+export function resolveConsent(requestId, approved) {
+    const entry = pending.get(requestId);
+    if (!entry)
+        return;
+    pending.delete(requestId);
+    entry.resolve(approved);
+}

package/dist/keys/consent.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/keys/consent.test.js

@@ -0,0 +1,53 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { registerConsentListener, requestConsent, resolveConsent, } from './consent.svelte';
+describe('consent runtime', () => {
+    // Always clean up the listener after each test to avoid cross-test leakage.
+    const cleanups = [];
+    afterEach(() => { cleanups.forEach((fn) => fn()); cleanups.length = 0; });
+    it('throws when no listener is registered', async () => {
+        await expect(requestConsent('my-shard', { label: 'test', scopes: ['state:manage'] })).rejects.toThrow('No consent listener registered');
+    });
+    it('delivers the request to the listener with correct shape', async () => {
+        const received = [];
+        const off = registerConsentListener((req) => {
+            received.push(req);
+            queueMicrotask(() => resolveConsent(req.requestId, true));
+        });
+        cleanups.push(off);
+        await requestConsent('shard-a', { label: 'My key', scopes: ['documents:sync'], connectorId: 'peer-x' });
+        expect(received).toHaveLength(1);
+        const req = received[0];
+        expect(req.shardId).toBe('shard-a');
+        expect(req.label).toBe('My key');
+        expect(req.scopes).toEqual(['documents:sync']);
+        expect(req.connectorId).toBe('peer-x');
+        expect(typeof req.requestId).toBe('string');
+    });
+    it('resolves true when approved', async () => {
+        const off = registerConsentListener((req) => {
+            queueMicrotask(() => resolveConsent(req.requestId, true));
+        });
+        cleanups.push(off);
+        const result = await requestConsent('shard-b', { label: 'l', scopes: ['state:manage'] });
+        expect(result).toBe(true);
+    });
+    it('resolves false when denied', async () => {
+        const off = registerConsentListener((req) => {
+            queueMicrotask(() => resolveConsent(req.requestId, false));
+        });
+        cleanups.push(off);
+        const result = await requestConsent('shard-c', { label: 'l', scopes: ['state:manage'] });
+        expect(result).toBe(false);
+    });
+    it('ignores resolveConsent calls with unknown requestId', () => {
+        // Should not throw — just a no-op.
+        expect(() => resolveConsent('does-not-exist', true)).not.toThrow();
+    });
+    it('the deregistration returned by registerConsentListener removes the listener', async () => {
+        const off = registerConsentListener(() => {
+            throw new Error('Should not be called');
+        });
+        off(); // deregister immediately
+        await expect(requestConsent('shard-d', { label: 'l', scopes: ['state:manage'] })).rejects.toThrow('No consent listener registered');
+    });
+});

package/dist/keys/revocation-bus.svelte.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Notifies active shards when one of their minted keys is revoked —
+ * regardless of whether the revocation was initiated by the shell UI,
+ * the shard itself, or another tab.
+ *
+ * The bus is populated by a server-sent events stream on /api/keys/events
+ * (wired by the shell runtime at boot) and/or by local revoke() calls.
+ */
+type Handler = (keyId: string) => void;
+/**
+ * Subscribe to revocation events for a specific shard, or for all shards
+ * by passing `'*'` as the shardId.
+ * Returns an unsubscribe function.
+ */
+export declare function subscribe(shardId: string | '*', handler: Handler): () => void;
+/**
+ * Emit a revocation event for the given shardId.
+ * No-op if shardId is null or has no subscribers.
+ * Deduplicates events: if the same (shardId, keyId) pair was already emitted
+ * within the last 5 s it is silently dropped (covers local-then-SSE and
+ * SSE-then-local orderings).
+ * Internal use only — called by client.ts and the SSE stream bootstrap.
+ */
+export declare function emit(shardId: string | null, keyId: string): void;
+/**
+ * Open a server-sent events stream at /api/keys/events and forward
+ * revocation events into the local bus.
+ *
+ * Should be called once at shell boot. Returns a cleanup function that
+ * closes the EventSource.
+ *
+ * No-op in environments without EventSource (e.g. Node test runner).
+ */
+export declare function startServerSideStream(): () => void;
+export {};