sh3-core 0.8.1 → 0.9.0

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, peerId)
+  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.peerRole || current.peerId}
+          <dt>Peer</dt>
+          <dd>{current.peerRole ?? '—'}{current.peerId ? ` · ${current.peerId}` : ''}</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.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.js

@@ -0,0 +1,54 @@
+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: ['sync:peer'], peerRole: 'replica', peerId: '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(['sync:peer']);
+        expect(req.peerRole).toBe('replica');
+        expect(req.peerId).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 {};

package/dist/keys/revocation-bus.svelte.js

@@ -0,0 +1,92 @@
+/**
+ * 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.
+ */
+const handlersByShard = new Map();
+/**
+ * Recently-emitted (shardId → Set<keyId>) with per-entry TTL timers.
+ * Prevents double-firing when a local emit() is followed by the same
+ * event arriving via SSE (or vice-versa) within the dedup window.
+ */
+const recentByShard = new Map();
+const DEDUP_TTL_MS = 5000;
+function markRecent(shardId, keyId) {
+    let set = recentByShard.get(shardId);
+    if (!set) {
+        set = new Set();
+        recentByShard.set(shardId, set);
+    }
+    set.add(keyId);
+    setTimeout(() => {
+        set.delete(keyId);
+        if (set.size === 0)
+            recentByShard.delete(shardId);
+    }, DEDUP_TTL_MS);
+}
+function isRecent(shardId, keyId) {
+    var _a, _b;
+    return (_b = (_a = recentByShard.get(shardId)) === null || _a === void 0 ? void 0 : _a.has(keyId)) !== null && _b !== void 0 ? _b : false;
+}
+/**
+ * Subscribe to revocation events for a specific shard, or for all shards
+ * by passing `'*'` as the shardId.
+ * Returns an unsubscribe function.
+ */
+export function subscribe(shardId, handler) {
+    var _a;
+    const set = (_a = handlersByShard.get(shardId)) !== null && _a !== void 0 ? _a : new Set();
+    set.add(handler);
+    handlersByShard.set(shardId, set);
+    return () => { set.delete(handler); };
+}
+/**
+ * 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 function emit(shardId, keyId) {
+    if (!shardId)
+        return;
+    if (isRecent(shardId, keyId))
+        return;
+    markRecent(shardId, keyId);
+    const set = handlersByShard.get(shardId);
+    if (set)
+        for (const h of set)
+            h(keyId);
+    const star = handlersByShard.get('*');
+    if (star)
+        for (const h of star)
+            h(keyId);
+}
+/**
+ * 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 function startServerSideStream() {
+    if (typeof EventSource === 'undefined')
+        return () => { };
+    const es = new EventSource('/api/keys/events', { withCredentials: true });
+    es.onmessage = (msg) => {
+        try {
+            const ev = JSON.parse(msg.data);
+            emit(ev.shardId, ev.id);
+        }
+        catch (_a) {
+            // Ignore malformed messages.
+        }
+    };
+    return () => es.close();
+}

package/dist/keys/revocation-bus.test.js

@@ -0,0 +1,95 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { subscribe, emit } from './revocation-bus.svelte';
+// Use fake timers so dedup TTL tests don't wait 5 s.
+// Individual tests that need it call vi.useFakeTimers(); others rely on real timers.
+afterEach(() => {
+    vi.restoreAllMocks();
+});
+describe('revocation-bus', () => {
+    it('fires the handler for the correct shardId', () => {
+        const received = [];
+        const off = subscribe('my-shard', (id) => received.push(id));
+        try {
+            emit('my-shard', 'key-1');
+            expect(received).toEqual(['key-1']);
+        }
+        finally {
+            off();
+        }
+    });
+    it('does not fire for a different shardId', () => {
+        const received = [];
+        const off = subscribe('shard-a', (id) => received.push(id));
+        try {
+            emit('shard-b', 'key-1');
+            expect(received).toHaveLength(0);
+        }
+        finally {
+            off();
+        }
+    });
+    it('does not fire after unsubscribe', () => {
+        const received = [];
+        const off = subscribe('my-shard', (id) => received.push(id));
+        off();
+        emit('my-shard', 'key-1');
+        expect(received).toHaveLength(0);
+    });
+    it('is a no-op when shardId is null', () => {
+        // Should not throw.
+        expect(() => emit(null, 'key-1')).not.toThrow();
+    });
+    it('supports multiple subscribers for the same shard', () => {
+        const a = [];
+        const b = [];
+        const offA = subscribe('shared', (id) => a.push(id));
+        const offB = subscribe('shared', (id) => b.push(id));
+        try {
+            emit('shared', 'k');
+            expect(a).toEqual(['k']);
+            expect(b).toEqual(['k']);
+        }
+        finally {
+            offA();
+            offB();
+        }
+    });
+    it('deduplicates back-to-back emits for the same (shard, key) pair', () => {
+        vi.useFakeTimers();
+        try {
+            const received = [];
+            const off = subscribe('dedup-shard', (id) => received.push(id));
+            try {
+                emit('dedup-shard', 'key-dup');
+                emit('dedup-shard', 'key-dup'); // duplicate within TTL window
+                expect(received).toHaveLength(1);
+                expect(received[0]).toBe('key-dup');
+            }
+            finally {
+                off();
+            }
+        }
+        finally {
+            vi.useRealTimers();
+        }
+    });
+    it('re-fires after the dedup TTL has elapsed', () => {
+        vi.useFakeTimers();
+        try {
+            const received = [];
+            const off = subscribe('dedup-ttl-shard', (id) => received.push(id));
+            try {
+                emit('dedup-ttl-shard', 'key-x');
+                vi.advanceTimersByTime(6000); // past the 5 s TTL
+                emit('dedup-ttl-shard', 'key-x');
+                expect(received).toHaveLength(2);
+            }
+            finally {
+                off();
+            }
+        }
+        finally {
+            vi.useRealTimers();
+        }
+    });
+});

package/dist/keys/types.d.ts

@@ -0,0 +1,34 @@
+export declare const PERMISSION_KEYS_MINT = "keys:mint";
+export interface ApiKeyPublic {
+    id: string;
+    label: string;
+    tenantId: string | null;
+    ownerUserId: string | null;
+    mintedByShardId: string | null;
+    scopes: string[];
+    peerRole?: 'primary' | 'replica';
+    peerId?: string;
+    createdAt: string;
+    expiresAt?: string;
+}
+export interface MintOpts {
+    label: string;
+    scopes: string[];
+    peerRole?: 'primary' | 'replica';
+    peerId?: string;
+    expiresIn?: number;
+}
+export interface ShardContextKeys {
+    mint(opts: MintOpts): Promise<{
+        id: string;
+        key: string;
+    }>;
+    list(): Promise<ApiKeyPublic[]>;
+    revoke(id: string): Promise<void>;
+}
+export declare class ScopeEscalationError extends Error {
+    constructor(scope: string);
+}
+export declare class ConsentDeniedError extends Error {
+    constructor();
+}

package/dist/keys/types.js

@@ -0,0 +1,13 @@
+export const PERMISSION_KEYS_MINT = 'keys:mint';
+export class ScopeEscalationError extends Error {
+    constructor(scope) {
+        super(`Shard may not mint a key with scope '${scope}' — not declared in manifest.`);
+        this.name = 'ScopeEscalationError';
+    }
+}
+export class ConsentDeniedError extends Error {
+    constructor() {
+        super('User denied key creation.');
+        this.name = 'ConsentDeniedError';
+    }
+}