sh3-core 0.8.0 → 0.8.2

package/dist/documents/sync/index.d.ts

@@ -1,6 +1,5 @@
 export type { SyncScope, SyncHandle, ManifestEntry, ApplyEntry, ApplyOpts, ApplyOutcome, ApplyBatchResult, ConflictPolicy, ConflictResolution, ConflictContext, JournalEntry, ChangePage, GrantRecord, } from './types';
 export { PERMISSION_DOCUMENTS_SYNC, SYNC_RESERVED_SHARD_ID, ScopeNotGrantedError, ScopeRevokedError, TenantMismatchError, } from './types';
-export { createSyncRegistry, type SyncRegistry } from './registry';
-export { getSyncBundle } from './singleton';
+export type { SyncRegistry } from './registry';
 export { default as SyncGrantPicker } from './components/SyncGrantPicker.svelte';
 export { default as DocumentSyncExplorer } from './components/DocumentSyncExplorer.svelte';

package/dist/documents/sync/index.js

@@ -6,7 +6,5 @@
  * it is imported directly by SyncGrantPicker.svelte only.
  */
 export { PERMISSION_DOCUMENTS_SYNC, SYNC_RESERVED_SHARD_ID, ScopeNotGrantedError, ScopeRevokedError, TenantMismatchError, } from './types';
-export { createSyncRegistry } from './registry';
-export { getSyncBundle } from './singleton';
 export { default as SyncGrantPicker } from './components/SyncGrantPicker.svelte';
 export { default as DocumentSyncExplorer } from './components/DocumentSyncExplorer.svelte';

package/dist/documents/sync/observer.d.ts

@@ -0,0 +1,3 @@
+import type { DocumentBackend } from '../types';
+import type { SyncRegistry } from './registry';
+export declare function createSyncRegistryAccessor(backend: DocumentBackend, tenantId: string): () => SyncRegistry;

package/dist/documents/sync/observer.js

@@ -0,0 +1,45 @@
+/*
+ * Observer factory for ctx.syncRegistry.
+ *
+ * Returns a lazy accessor that resolves to the same SyncRegistry instance
+ * backed by the per-tenant sync bundle. Observer-class shards (e.g. the
+ * file-explorer) and connector shards share one view of grants and
+ * conflicts.
+ *
+ * Gated upstream on the 'documents:browse' permission — granting remains
+ * exclusive to <SyncGrantPicker />.
+ */
+import { getSyncBundle } from './singleton';
+export function createSyncRegistryAccessor(backend, tenantId) {
+    let cached = null;
+    let initPromise = null;
+    function resolve() {
+        if (cached)
+            return Promise.resolve(cached);
+        if (!initPromise) {
+            initPromise = getSyncBundle(backend, tenantId).then(({ registry }) => {
+                cached = registry;
+                return registry;
+            });
+        }
+        return initPromise;
+    }
+    return () => {
+        const proxy = {
+            async list(connectorId) {
+                return (await resolve()).list(connectorId);
+            },
+            async revoke(connectorId, scope) {
+                return (await resolve()).revoke(connectorId, scope);
+            },
+            listConflicts: (async (shardId) => {
+                const r = await resolve();
+                return shardId === undefined ? r.listConflicts() : r.listConflicts(shardId);
+            }),
+            async listAllConnectorIds() {
+                return (await resolve()).listAllConnectorIds();
+            },
+        };
+        return proxy;
+    };
+}

package/dist/documents/sync/registry.d.ts

@@ -4,7 +4,10 @@ export declare function __grantInternal(backend: DocumentBackend, tenantId: stri
 export interface SyncRegistry {
     list(connectorId?: string): Promise<GrantRecord[]>;
     revoke(connectorId: string, scope: SyncScope): Promise<void>;
+    /** Per-shard conflict enumeration. */
     listConflicts(shardId: string): Promise<ConflictResolution[]>;
+    /** Tenant-wide conflict enumeration (fans out over every shard). */
+    listConflicts(): Promise<ConflictResolution[]>;
     listAllConnectorIds(): Promise<string[]>;
 }
 export declare function createSyncRegistry(backend: DocumentBackend, tenantId: string): SyncRegistry;

package/dist/documents/sync/registry.js

@@ -56,7 +56,14 @@ export function createSyncRegistry(backend, tenantId) {
                 await writeJson(backend, tenantId, grantPath(connectorId), next);
         },
         async listConflicts(shardId) {
-            return conflicts.listConflicts(shardId);
+            if (shardId !== undefined)
+                return conflicts.listConflicts(shardId);
+            const shards = await backend.listAllShards(tenantId);
+            const out = [];
+            for (const s of shards) {
+                out.push(...(await conflicts.listConflicts(s)));
+            }
+            return out;
         },
         async listAllConnectorIds() {
             const paths = await listJsonPaths(backend, tenantId, GRANTS_PREFIX);

package/dist/documents/sync/registry.test.js

@@ -39,4 +39,15 @@ describe('syncRegistry', () => {
         await __grantInternal(backend, 'tenant-a', 'conn-A', { kind: 'tenant' });
         expect((await reg.list('conn-A')).length).toBe(1);
     });
+    it('listConflicts() with no args returns conflicts across all shards', async () => {
+        var _a, _b;
+        // Seed conflict artifacts directly via the backend (matches
+        // ConflictManager's artifact naming).
+        await backend.write('tenant-a', 'shard-a', 'doc.md.sync-conflict-connA-111', 'remote-a');
+        await backend.write('tenant-a', 'shard-b', 'other.md.sync-conflict-connB-222', 'remote-b');
+        const all = await reg.listConflicts();
+        expect(all.map((c) => c.shardId).sort()).toEqual(['shard-a', 'shard-b']);
+        expect((_a = all.find((c) => c.shardId === 'shard-a')) === null || _a === void 0 ? void 0 : _a.path).toBe('doc.md');
+        expect((_b = all.find((c) => c.shardId === 'shard-b')) === null || _b === void 0 ? void 0 : _b.path).toBe('other.md');
+    });
 });

package/dist/documents/types.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Manifest permission string: grants tenant-wide document observation
+ * (`ctx.browse`) and sync registry visibility (`ctx.syncRegistry`).
+ * Read-only; writes still flow through the shard's own `ctx.documents()`.
+ */
+export declare const PERMISSION_DOCUMENTS_BROWSE = "documents:browse";
 /**
  * Format hint for document content. Determines whether reads return a string
  * (`text`) or an `ArrayBuffer` (`binary`).
@@ -50,6 +56,18 @@ export interface DocumentBackend {
     list(tenantId: string, shardId: string): Promise<DocumentMeta[]>;
     /** Return true if the document at `path` exists. */
     exists(tenantId: string, shardId: string, path: string): Promise<boolean>;
+    /**
+     * List every shard id that currently has at least one document stored
+     * for this tenant. Tenant-wide observation primitive.
+     */
+    listAllShards(tenantId: string): Promise<string[]>;
+    /**
+     * List every document in the tenant across all shards. Each entry
+     * carries the owning `shardId`. Tenant-wide observation primitive.
+     */
+    listAllDocuments(tenantId: string): Promise<Array<DocumentMeta & {
+        shardId: string;
+    }>>;
 }
 /**
  * Shard-facing document handle returned by `ctx.documents()`. Binds

package/dist/documents/types.js

@@ -9,4 +9,9 @@
  * The document zone is a parallel subsystem — it does not extend
  * ZoneName or ZoneSchema. Shards access it via `ctx.documents()`.
  */
-export {};
+/**
+ * Manifest permission string: grants tenant-wide document observation
+ * (`ctx.browse`) and sync registry visibility (`ctx.syncRegistry`).
+ * Read-only; writes still flow through the shard's own `ctx.documents()`.
+ */
+export const PERMISSION_DOCUMENTS_BROWSE = 'documents:browse';

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 {};