sh3-core 0.8.1 → 0.9.0

package/dist/server-shard/types.d.ts

@@ -10,6 +10,51 @@
  * The server bundle is a separate ESM file whose default export conforms
  * to the `ServerShard` interface.
  */
+import type { DocumentMeta } from '../documents/types';
+import type { SyncPolicy, ConflictFile } from '../documents/sync-types';
+/**
+ * Per-tenant document API exposed to server shards via
+ * `ServerShardContext.documents(tenantId)`. Every method is
+ * permission-checked by the host at call time.
+ */
+export interface TenantDocumentAPI {
+    read(shardId: string, path: string): Promise<string | null>;
+    exists(shardId: string, path: string): Promise<boolean>;
+    list(shardId: string): Promise<DocumentMeta[]>;
+    listAll(): Promise<Array<DocumentMeta & {
+        shardId: string;
+    }>>;
+    write(shardId: string, path: string, content: string | Uint8Array, metadata?: Record<string, unknown>): Promise<{
+        version: number;
+        syncState: 'synced' | 'pending';
+    }>;
+    delete(shardId: string, path: string): Promise<void>;
+    applyFromPeer(input: {
+        shardId: string;
+        path: string;
+        content: string | Uint8Array;
+        incomingVersion: number;
+        expectedLocalVersion: number;
+        origin: string;
+        deleted?: boolean;
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        applied: true;
+        version: number;
+    } | {
+        applied: false;
+        reason: 'stale' | 'conflict' | 'conflict-extended';
+    }>;
+    getTick(): Promise<number>;
+    readPolicy(): Promise<SyncPolicy | null>;
+    writePolicy(policy: SyncPolicy): Promise<void>;
+    listConflicts(): Promise<Array<{
+        shardId: string;
+        path: string;
+    }>>;
+    readConflict(shardId: string, path: string): Promise<ConflictFile | null>;
+    resolveConflict(shardId: string, path: string, choice: 'local' | string | Uint8Array): Promise<void>;
+}
 /**
  * Context provided by sh3-server when mounting a server shard's routes.
  */
@@ -22,14 +67,33 @@ export interface ServerShardContext {
      * Path: `<dataDir>/shards/<shard-id>/`
      */
     dataDir: string;
+    /** Permission strings declared in the paired client manifest, empty if no manifest. */
+    permissions: string[];
     /**
      * Hono middleware that rejects non-admin callers.
-     * Apply per-route to protect mutation endpoints. Public read routes
-     * should not use this.
+     * Backwards-compatible alias for scopeRequired('admin:*'). Prefer the generic form.
      *
      * Usage: `router.post('/publish', ctx.adminOnly, handler)`
      */
     adminOnly: MiddlewareHandler;
+    /** 403 unless caller has the named scope (or admin:*). */
+    scopeRequired: (scope: string) => MiddlewareHandler;
+    /** 401 unless caller has a non-null tenantId. */
+    tenantRequired: MiddlewareHandler;
+    /**
+     * WebSocket upgrade registration — unchanged from 0.8.1.
+     */
+    wsRegister?: (onConnect: (ws: any, c: any) => void) => any;
+    /** Tenant ids that currently have doc content on this server. */
+    tenants(): string[];
+    /** Per-tenant document API, permission-checked per operation. */
+    documents(tenant: string): TenantDocumentAPI;
+    /**
+     * Declare the server's role for a tenant. Called by shards with
+     * `sync:peer` permission. No-op unless the caller holds it.
+     * Absent => 'primary' behavior at the store.
+     */
+    setPeerRole(tenant: string, role: 'primary' | 'replica'): void;
 }
 /**
  * The interface a server shard bundle must default-export.
@@ -45,6 +109,8 @@ export interface ServerShard {
      * May be async if the shard needs to initialise resources before serving.
      */
     routes: (router: HonoLike, context: ServerShardContext) => void | Promise<void>;
+    /** Optional shutdown hook. Called once on server SIGTERM/SIGINT. */
+    teardown?(): void | Promise<void>;
 }
 /**
  * Hono MiddlewareHandler type — duplicated here to avoid importing hono

package/dist/sh3core-shard/ShellHome.svelte

@@ -1,17 +1,29 @@
 <script lang="ts">
   /*
-   * Shell home — the view shown when no app is active. Sections:
-   *   1. User apps — always visible
-   *   2. Admin apps — visible when user has admin role
+   * Shell home — the view shown when no app is active.
+   *
+   * Layout: a title header, a filter bar, then one grid per visible
+   * section (User apps always, Admin apps when elevated). Each app is
+   * rendered as a square card; the whole card is the launch action.
    */
 
   import { listRegisteredApps, launchApp, isAdmin, VERSION } from '../api';
   import ShellTitle from './ShellTitle.svelte';
 
+  let filter = $state('');
+
   const apps = $derived(listRegisteredApps());
-  const userApps = $derived(apps.filter(m => !m.admin));
-  const adminApps = $derived(apps.filter(m => m.admin));
   const elevated = $derived(isAdmin());
+
+  function matches(m: { id: string; label: string }, q: string): boolean {
+    if (!q) return true;
+    const needle = q.toLowerCase();
+    return m.label.toLowerCase().includes(needle) || m.id.toLowerCase().includes(needle);
+  }
+
+  const userApps = $derived(apps.filter((m) => !m.admin && matches(m, filter)));
+  const adminApps = $derived(apps.filter((m) => m.admin && matches(m, filter)));
+  const totalVisible = $derived(userApps.length + (elevated ? adminApps.length : 0));
 </script>
 
 <div class="shell-home">
@@ -26,54 +38,68 @@
     </div>
   </header>
 
+  <div class="shell-home-filter">
+    <input
+      type="search"
+      placeholder="Filter apps…"
+      bind:value={filter}
+      aria-label="Filter apps by name"
+      class="shell-home-filter-input"
+    />
+  </div>
+
   {#if userApps.length > 0}
     <section class="shell-home-section">
       <h2 class="shell-home-section-title">Apps</h2>
-      <ul class="shell-home-list">
+      <div class="shell-home-grid">
         {#each userApps as manifest (manifest.id)}
-          <li class="shell-home-entry">
-            <div class="shell-home-entry-label">{manifest.label}</div>
-            <div class="shell-home-entry-meta">
-              {manifest.id} · v{manifest.version}
+          <button
+            type="button"
+            class="shell-home-card"
+            onclick={() => launchApp(manifest.id)}
+            title="Launch {manifest.label}"
+          >
+            <div class="shell-home-card-label">{manifest.label}</div>
+            <div class="shell-home-card-meta">
+              <span class="shell-home-card-id">{manifest.id}</span>
+              <span class="shell-home-card-version">v{manifest.version}</span>
             </div>
-            <button
-              type="button"
-              class="shell-home-launch"
-              onclick={() => launchApp(manifest.id)}
-            >
-              Launch
-            </button>
-          </li>
+          </button>
         {/each}
-      </ul>
+      </div>
     </section>
   {/if}
 
   {#if elevated && adminApps.length > 0}
     <section class="shell-home-section">
       <h2 class="shell-home-section-title">Admin</h2>
-      <ul class="shell-home-list">
+      <div class="shell-home-grid">
         {#each adminApps as manifest (manifest.id)}
-          <li class="shell-home-entry">
-            <div class="shell-home-entry-label">{manifest.label}</div>
-            <div class="shell-home-entry-meta">
-              {manifest.id} · v{manifest.version}
+          <button
+            type="button"
+            class="shell-home-card"
+            onclick={() => launchApp(manifest.id)}
+            title="Launch {manifest.label}"
+          >
+            <div class="shell-home-card-label">{manifest.label}</div>
+            <div class="shell-home-card-meta">
+              <span class="shell-home-card-id">{manifest.id}</span>
+              <span class="shell-home-card-version">v{manifest.version}</span>
             </div>
-            <button
-              type="button"
-              class="shell-home-launch"
-              onclick={() => launchApp(manifest.id)}
-            >
-              Launch
-            </button>
-          </li>
+          </button>
         {/each}
-      </ul>
+      </div>
     </section>
   {/if}
 
-  {#if userApps.length === 0 && (!elevated || adminApps.length === 0)}
-    <p class="shell-home-empty">No apps registered.</p>
+  {#if totalVisible === 0}
+    <p class="shell-home-empty">
+      {#if apps.length === 0}
+        No apps registered.
+      {:else}
+        No apps match “{filter}”.
+      {/if}
+    </p>
   {/if}
 </div>
 
@@ -93,7 +119,7 @@
   }
   .shell-home-header {
     text-align: center;
-    margin-bottom: 32px;
+    margin-bottom: 24px;
     display: flex;
     flex-direction: column;
     align-items: center;
@@ -136,14 +162,38 @@
     position: relative;
     top: -1px;
   }
+  .shell-home-filter {
+    width: 100%;
+    max-width: 720px;
+    margin-bottom: 24px;
+  }
+  .shell-home-filter-input {
+    width: 100%;
+    padding: 10px 14px;
+    font: inherit;
+    font-size: 14px;
+    color: var(--shell-fg);
+    background: var(--shell-bg-elevated);
+    border: 1px solid var(--shell-border);
+    border-radius: var(--shell-radius-md);
+    outline: none;
+    transition: border-color 120ms ease, box-shadow 120ms ease;
+  }
+  .shell-home-filter-input::placeholder {
+    color: var(--shell-fg-muted);
+  }
+  .shell-home-filter-input:focus {
+    border-color: var(--shell-accent);
+    box-shadow: 0 0 0 2px color-mix(in srgb, var(--shell-accent) 25%, transparent);
+  }
   .shell-home-empty {
     color: var(--shell-fg-muted);
     font-style: italic;
   }
   .shell-home-section {
     width: 100%;
-    max-width: 440px;
-    margin-bottom: 24px;
+    max-width: 720px;
+    margin-bottom: 28px;
   }
   .shell-home-section-title {
     font-size: 13px;
@@ -153,40 +203,67 @@
     color: var(--shell-fg-subtle);
     margin: 0 0 12px;
   }
-  .shell-home-list {
-    list-style: none;
-    margin: 0;
-    padding: 0;
+  .shell-home-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(80px, 1fr));
+    gap: 10px;
+  }
+  .shell-home-card {
+    aspect-ratio: 1 / 1;
     display: flex;
     flex-direction: column;
-    gap: 12px;
-  }
-  .shell-home-entry {
-    display: grid;
-    grid-template-columns: 1fr auto;
-    grid-template-rows: auto auto;
-    gap: 4px 16px;
-    align-items: center;
-    padding: 14px 18px;
+    justify-content: space-between;
+    text-align: left;
+    padding: 10px;
     background: var(--shell-grad-bg-elevated, var(--shell-bg-elevated));
     border: 1px solid var(--shell-border);
     border-radius: var(--shell-radius-md);
+    color: inherit;
+    font: inherit;
+    cursor: pointer;
+    box-shadow: 0 2px 6px rgba(0, 0, 0, 0.25), 0 1px 2px rgba(0, 0, 0, 0.15);
+    transition: transform 120ms ease, border-color 120ms ease, box-shadow 120ms ease, background 120ms ease;
+  }
+  .shell-home-card:hover {
+    border-color: var(--shell-accent);
+    transform: translateY(-1px);
+    box-shadow:
+      0 6px 14px rgba(0, 0, 0, 0.3),
+      0 0 0 1px color-mix(in srgb, var(--shell-accent) 35%, transparent),
+      0 4px 12px color-mix(in srgb, var(--shell-accent) 18%, transparent);
   }
-  .shell-home-entry-label {
-    grid-column: 1;
-    grid-row: 1;
+  .shell-home-card:focus-visible {
+    outline: none;
+    border-color: var(--shell-accent);
+    box-shadow: 0 0 0 2px color-mix(in srgb, var(--shell-accent) 40%, transparent);
+  }
+  .shell-home-card:active {
+    transform: translateY(0);
+  }
+  .shell-home-card-label {
     font-weight: 600;
+    font-size: 12px;
+    line-height: 1.2;
+    overflow: hidden;
+    display: -webkit-box;
+    -webkit-box-orient: vertical;
+    -webkit-line-clamp: 2;
+    line-clamp: 2;
   }
-  .shell-home-entry-meta {
-    grid-column: 1;
-    grid-row: 2;
-    font-size: 11px;
+  .shell-home-card-meta {
+    display: flex;
+    flex-direction: column;
+    gap: 1px;
+    font-size: 9px;
     color: var(--shell-fg-subtle);
+    min-width: 0;
   }
-  .shell-home-launch {
-    grid-column: 2;
-    grid-row: 1 / span 2;
-    padding: 8px 16px;
-    font-weight: 600;
+  .shell-home-card-id {
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+  .shell-home-card-version {
+    color: var(--shell-fg-muted);
   }
 </style>

package/dist/sh3core-shard/sh3coreShard.svelte.js

@@ -23,13 +23,17 @@
  */
 import { mount, unmount } from 'svelte';
 import ShellHome from './ShellHome.svelte';
+import KeysAndPeers from '../shell/views/KeysAndPeers.svelte';
 import { VERSION } from '../version';
 export const sh3coreShard = {
     manifest: {
         id: '__sh3core__',
         label: 'SH3 Core',
         version: VERSION,
-        views: [{ id: 'sh3core:home', label: 'Home' }],
+        views: [
+            { id: 'sh3core:home', label: 'Home' },
+            { id: 'shell:keys-and-peers', label: 'Keys & Peers' },
+        ],
     },
     activate(ctx) {
         const factory = {
@@ -43,7 +47,14 @@ export const sh3coreShard = {
                 };
             },
         };
+        const keysFactory = {
+            mount(container, _context) {
+                const instance = mount(KeysAndPeers, { target: container });
+                return { unmount() { unmount(instance); } };
+            },
+        };
         ctx.registerView('sh3core:home', factory);
+        ctx.registerView('shell:keys-and-peers', keysFactory);
     },
     autostart() {
         // Intentionally empty. Defining this field is what puts the sh3core

package/dist/shards/activate-on-key-revoked.test.js

@@ -0,0 +1,60 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { MemoryDocumentBackend } from '../documents/backends';
+import { __setDocumentBackend, __setTenantId } from '../documents/config';
+import { registerShard, activateShard, deactivateShard, __resetShardRegistryForTest } from './activate.svelte';
+import { emit } from '../keys/revocation-bus.svelte';
+describe('onKeyRevoked hook wiring', () => {
+    beforeEach(() => {
+        __resetShardRegistryForTest();
+        __setDocumentBackend(new MemoryDocumentBackend());
+        __setTenantId('tenant-a');
+    });
+    it('fires onKeyRevoked when the bus emits for the shard', async () => {
+        const received = [];
+        registerShard({
+            manifest: { id: 'hook-shard', label: 'h', version: '0.0.0', views: [] },
+            activate() { },
+            onKeyRevoked(id) { received.push(id); },
+        });
+        await activateShard('hook-shard');
+        emit('hook-shard', 'key-abc');
+        // Handler is async; give microtasks a chance to flush.
+        await Promise.resolve();
+        expect(received).toEqual(['key-abc']);
+    });
+    it('does not fire for a different shardId', async () => {
+        const received = [];
+        registerShard({
+            manifest: { id: 'shard-x', label: 'x', version: '0.0.0', views: [] },
+            activate() { },
+            onKeyRevoked(id) { received.push(id); },
+        });
+        await activateShard('shard-x');
+        emit('shard-y', 'key-other');
+        await Promise.resolve();
+        expect(received).toHaveLength(0);
+    });
+    it('does not fire after deactivation', async () => {
+        const received = [];
+        registerShard({
+            manifest: { id: 'shard-deact', label: 'd', version: '0.0.0', views: [] },
+            activate() { },
+            onKeyRevoked(id) { received.push(id); },
+        });
+        await activateShard('shard-deact');
+        deactivateShard('shard-deact');
+        emit('shard-deact', 'key-gone');
+        await Promise.resolve();
+        expect(received).toHaveLength(0);
+    });
+    it('does not subscribe when onKeyRevoked is absent', async () => {
+        // Should not throw — just silently skips subscribing.
+        registerShard({
+            manifest: { id: 'no-hook', label: 'n', version: '0.0.0', views: [] },
+            activate() { },
+        });
+        await expect(activateShard('no-hook')).resolves.toBeUndefined();
+        // Emitting for a shard with no listener is a no-op.
+        expect(() => emit('no-hook', 'k')).not.toThrow();
+    });
+});

package/dist/shards/activate.svelte.js

@@ -23,12 +23,11 @@ import { fetchEnvState, putEnvState } from '../env/client';
 import { isAdmin as checkIsAdmin } from '../auth/index';
 import { createZoneManager } from '../state/manage';
 import { PERMISSION_STATE_MANAGE } from '../state/types';
-import { PERMISSION_DOCUMENTS_SYNC } from '../documents/sync/types';
 import { PERMISSION_DOCUMENTS_BROWSE } from '../documents/types';
 import { createBrowseCapability } from '../documents/browse';
-import { getSyncBundle } from '../documents/sync/singleton';
-import { createSyncHandle } from '../documents/sync/handle';
-import { createSyncRegistryAccessor } from '../documents/sync/observer';
+import { createShardKeysApi } from '../keys/client';
+import { PERMISSION_KEYS_MINT } from '../keys/types';
+import { subscribe } from '../keys/revocation-bus.svelte';
 /**
  * Reactive registry of every shard known to the host. Keys are shard ids.
  * Populated once at boot by the glob-discovery loop in main.ts (through
@@ -140,29 +139,27 @@ export async function activateShard(id) {
         browse: ((_b = shard.manifest.permissions) === null || _b === void 0 ? void 0 : _b.includes(PERMISSION_DOCUMENTS_BROWSE))
             ? createBrowseCapability(getTenantId(), getDocumentBackend())
             : undefined,
-        syncRegistry: ((_c = shard.manifest.permissions) === null || _c === void 0 ? void 0 : _c.includes(PERMISSION_DOCUMENTS_BROWSE))
-            ? createSyncRegistryAccessor(getDocumentBackend(), getTenantId())
-            : undefined,
-        sync: ((_d = shard.manifest.permissions) === null || _d === void 0 ? void 0 : _d.includes(PERMISSION_DOCUMENTS_SYNC))
-            ? () => {
-                const backend = getDocumentBackend();
-                const tenantId = getTenantId();
-                const bundlePromise = getSyncBundle(backend, tenantId);
-                const handlePromise = bundlePromise.then(({ engine, registry }) => createSyncHandle({ tenantId, connectorId: id, engine, registry }));
-                return {
-                    connectorId: id,
-                    grantedScopes: async () => (await handlePromise).grantedScopes(),
-                    getManifest: async (scope) => (await handlePromise).getManifest(scope),
-                    changesSince: async (scope, cursor) => (await handlePromise).changesSince(scope, cursor),
-                    ack: async (scope, cursor) => (await handlePromise).ack(scope, cursor),
-                    apply: async (scope, entry, opts) => (await handlePromise).apply(scope, entry, opts),
-                    applyBatch: async (scope, manifest, opts) => (await handlePromise).applyBatch(scope, manifest, opts),
-                    forget: async (scope, path) => (await handlePromise).forget(scope, path),
-                };
-            }
+        keys: ((_c = shard.manifest.permissions) === null || _c === void 0 ? void 0 : _c.includes(PERMISSION_KEYS_MINT))
+            ? createShardKeysApi({
+                shardId: id,
+                shardPermissions: (_d = shard.manifest.permissions) !== null && _d !== void 0 ? _d : [],
+            })
             : undefined,
     };
     entry.ctx = ctx;
+    // Wire onKeyRevoked hook: subscribe to the revocation bus for this shard.
+    // Only shards that declare the hook incur the subscription overhead.
+    if (shard.onKeyRevoked) {
+        const off = subscribe(id, async (keyId) => {
+            try {
+                await shard.onKeyRevoked(keyId);
+            }
+            catch (err) {
+                console.error(`[sh3] onKeyRevoked failed in "${id}":`, err);
+            }
+        });
+        entry.cleanupFns.push(async () => off());
+    }
     active.set(id, entry);
     activeShards.set(id, shard);
     await shard.activate(ctx);

package/dist/shards/types.d.ts

@@ -2,10 +2,10 @@ import type { StateZones } from '../state/zones.svelte';
 import type { ZoneSchema, ZoneManager } from '../state/types';
 import type { DocumentHandle, DocumentHandleOptions } from '../documents/types';
 import type { BrowseCapability } from '../documents/browse';
-import type { SyncHandle } from '../documents/sync/types';
-import type { SyncRegistry } from '../documents/sync/registry';
 import type { EnvState } from '../env/types';
 import type { Verb } from '../verbs/types';
+import type { ShardContextKeys } from '../keys/types';
+export { PERMISSION_KEYS_MINT, type ShardContextKeys, type ApiKeyPublic, type MintOpts, ScopeEscalationError, ConsentDeniedError } from '../keys/types';
 /**
  * The object returned by `ViewFactory.mount`. The framework calls
  * `unmount()` when the slot goes away, and `onResize(w, h)` whenever the
@@ -212,12 +212,6 @@ export interface ShardContext {
      * `if (ctx.zones)` before use.
      */
     zones?: ZoneManager;
-    /**
-     * Cross-shard document sync API. Only present when the shard's
-     * manifest declares the `'documents:sync'` permission. Check with
-     * `if (ctx.sync)` before use.
-     */
-    sync?: () => SyncHandle;
     /**
      * Tenant-wide document browse API. Read-only enumeration and change
      * subscription across every shard's documents for the active tenant.
@@ -227,12 +221,10 @@ export interface ShardContext {
      */
     browse?: BrowseCapability;
     /**
-     * Sync registry observer. Read-only list/revoke/conflict enumeration
-     * for explorer-class shards. Only present when the shard declares
-     * `'documents:browse'`. Granting still happens exclusively via
-     * `<SyncGrantPicker />`.
+     * Mint/list/revoke keys minted by this shard. Only available when the
+     * manifest declares the `keys:mint` permission.
      */
-    syncRegistry?: () => SyncRegistry;
+    keys?: ShardContextKeys;
 }
 /**
  * A shard module. Shards are the fundamental unit of contribution in SH3.
@@ -274,6 +266,8 @@ export interface Shard {
      * `ShardContext` that `activate` received.
      */
     resume?(ctx: ShardContext): void | Promise<void>;
+    /** Fires when a key minted by this shard is revoked from any source. */
+    onKeyRevoked?(id: string): void | Promise<void>;
 }
 /**
  * Source-level shape of a shard as written by external package authors.

package/dist/shards/types.js

@@ -17,4 +17,4 @@
  * activation events. They'll slot into `ShardContext` as new `register*`
  * methods without disturbing the phase-4 shape.
  */
-export {};
+export { PERMISSION_KEYS_MINT, ScopeEscalationError, ConsentDeniedError } from '../keys/types';