sh3-core 0.8.1 → 0.8.2

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.d.ts

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

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,32 @@
+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[];
+    connectorId?: string;
+    createdAt: string;
+    expiresAt?: string;
+}
+export interface MintOpts {
+    label: string;
+    scopes: string[];
+    connectorId?: 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';
+    }
+}

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

@@ -10,6 +10,8 @@
  * The server bundle is a separate ESM file whose default export conforms
  * to the `ServerShard` interface.
  */
+import type { SyncHandle } from '../documents/sync/types';
+import type { SyncRegistry } from '../documents/sync/registry';
 /**
  * Context provided by sh3-server when mounting a server shard's routes.
  */
@@ -22,14 +24,31 @@ 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;
+    /**
+     * Obtain a tenant-scoped SyncHandle from a server-side route handler.
+     * The handle enforces GrantRecord checks exactly like the client-side
+     * one. Throws if the shard's manifest does not declare `documents:sync`.
+     */
+    sync: (tenantId: string, connectorId: string) => Promise<SyncHandle>;
+    /** Tenant-scoped SyncRegistry accessor — grant enumeration/listing. */
+    syncRegistry: (tenantId: string) => SyncRegistry;
 }
 /**
  * The interface a server shard bundle must default-export.

package/dist/server-sync.d.ts

@@ -0,0 +1,6 @@
+export { getSyncBundle } from './documents/sync/singleton';
+export { createSyncHandle } from './documents/sync/handle';
+export { createSyncRegistry } from './documents/sync/registry';
+export type { SyncHandle } from './documents/sync/types';
+export type { SyncRegistry } from './documents/sync/registry';
+export type { DocumentBackend, DocumentMeta } from './documents/types';