@soulcraft/sdk 1.0.0

package/dist/server/handlers.d.ts

@@ -0,0 +1,216 @@
+/**
+ * @module server/handlers
+ * @description HTTP RPC and WebSocket handler factories for mounting Brainy server endpoints.
+ *
+ * Products mount exactly two routes:
+ * - `POST /api/brainy/rpc` — handled by {@link createBrainyHandler}
+ * - `GET /api/brainy/ws` — WebSocket upgrade handled by {@link createBrainyWsHandler}
+ *
+ * Both factories are framework-agnostic — they accept and return `Request` / `Response`
+ * objects (Fetch API), making them compatible with SvelteKit, Hono, and raw Bun.serve.
+ *
+ * ## HTTP RPC handler
+ *
+ * Accepts `{ method: string, args: unknown[] }` as a JSON body and returns
+ * `{ result: unknown }` or `{ error: { code, message } }`. All authentication and
+ * authorization is delegated to the caller-supplied callbacks.
+ *
+ * ## WebSocket handler
+ *
+ * Accepts binary MessagePack frames. See wire protocol in `transports/ws.ts`.
+ * The `broadcastChange()` method on the returned handler pushes `BrainyChangeEvent`
+ * objects to connected clients.
+ *
+ * @example SvelteKit route mounting the HTTP handler
+ * ```typescript
+ * // src/routes/api/brainy/rpc/+server.ts
+ * import { createBrainyHandler } from '@soulcraft/sdk/server'
+ * import { pool } from '$lib/server/sdk'
+ * import { verifySession } from '$lib/server/auth'
+ *
+ * const handler = createBrainyHandler({
+ *   resolveBrain: async (req) => {
+ *     const userId = req.headers.get('x-user-id') ?? ''
+ *     const workspaceId = req.headers.get('x-workspace-id') ?? ''
+ *     return pool.forUser(userId, workspaceId)
+ *   },
+ *   authenticate: async (req) => verifySession(req.headers.get('cookie') ?? ''),
+ * })
+ *
+ * export const POST: RequestHandler = ({ request }) => handler(request)
+ * ```
+ *
+ * @example Bun.serve WebSocket upgrade
+ * ```typescript
+ * import { createBrainyWsHandler } from '@soulcraft/sdk/server'
+ * import { pool } from './sdk'
+ * import { verifyCapabilityToken } from '@soulcraft/sdk'
+ *
+ * const wsHandler = createBrainyWsHandler({
+ *   resolveBrain: (scope) => pool.forTenant(scope),
+ *   authenticate: (token, scope) => verifyCapabilityToken(token, process.env.VENUE_RPC_SECRET!),
+ * })
+ *
+ * Bun.serve({
+ *   async fetch(req, server) {
+ *     if (req.url.endsWith('/api/brainy/ws')) {
+ *       const session = await wsHandler.handleUpgrade(req)
+ *       if (!session) return new Response('Unauthorized', { status: 401 })
+ *       server.upgrade(req, { data: session })
+ *       return undefined
+ *     }
+ *     return new Response('Not found', { status: 404 })
+ *   },
+ *   websocket: {
+ *     async message(ws, data) {
+ *       await wsHandler.handleMessage(ws.data, data as ArrayBuffer, (msg) => ws.send(msg))
+ *     },
+ *   },
+ * })
+ * ```
+ */
+import type { Brainy } from '@soulcraft/brainy';
+import { LocalTransport } from '../transports/local.js';
+import type { BrainyChangeEvent } from '../modules/brainy/events.js';
+/**
+ * Configuration for {@link createBrainyHandler}.
+ */
+export interface BrainyHandlerConfig {
+    /**
+     * Resolves the Brainy instance to dispatch this request against.
+     *
+     * Called on every request. Use request headers (org slug, workspace ID, etc.)
+     * to select the correct instance from the pool.
+     *
+     * @param request - The incoming HTTP Request.
+     * @returns The Brainy instance for this request's scope.
+     */
+    resolveBrain: (request: Request) => Promise<Brainy>;
+    /**
+     * Authenticates the incoming request.
+     *
+     * Return any truthy value (claims, session object, etc.) on success.
+     * Return `null` or `undefined` to reject the request with HTTP 401.
+     *
+     * @param request - The incoming HTTP Request.
+     * @returns An auth context on success, or `null` to reject.
+     */
+    authenticate: (request: Request) => Promise<unknown | null>;
+    /**
+     * Optional per-call authorization check.
+     *
+     * Called after `authenticate()` succeeds. Return `false` or `null` to
+     * reject with HTTP 403.
+     *
+     * @param method - Dot-separated Brainy method name.
+     * @param args - Positional arguments from the request body.
+     * @param auth - The auth context returned by `authenticate()`.
+     * @returns `true` to allow, `false` / `null` to deny.
+     */
+    authorize?: (method: string, args: unknown[], auth: unknown) => boolean | null | Promise<boolean | null>;
+    /**
+     * Methods that are blocked for all callers regardless of auth.
+     *
+     * @default []
+     */
+    blockedMethods?: string[];
+}
+/**
+ * Creates a Fetch-API-compatible HTTP handler for Brainy RPC calls.
+ *
+ * Mount at `POST /api/brainy/rpc` in your product's router.
+ *
+ * @param config - Handler configuration.
+ * @returns `(request: Request) => Promise<Response>`
+ */
+export declare function createBrainyHandler(config: BrainyHandlerConfig): (request: Request) => Promise<Response>;
+/**
+ * Configuration for {@link createBrainyWsHandler}.
+ */
+export interface BrainyWsHandlerConfig {
+    /**
+     * Resolves the Brainy instance for the given scope (e.g. tenant slug).
+     *
+     * @param scope - The `?scope=` query param from the WebSocket URL.
+     * @returns The Brainy instance for this scope.
+     */
+    resolveBrain: (scope: string) => Promise<Brainy>;
+    /**
+     * Authenticates the WebSocket upgrade request.
+     *
+     * The `token` is extracted from `Authorization: Bearer <token>`. Return `null`
+     * to close the socket with code 4001 (unauthorized).
+     *
+     * @param token - The bearer token from the Authorization header.
+     * @param scope - The requested scope from the URL.
+     * @returns An auth context on success, or `null` to reject.
+     */
+    authenticate: (token: string, scope: string) => Promise<unknown | null>;
+    /**
+     * Optional per-call authorization check.
+     *
+     * @param method - Dot-separated Brainy method name.
+     * @param args - Positional arguments.
+     * @param auth - The auth context from `authenticate()`.
+     * @returns `true` to allow, `false` / `null` to deny.
+     */
+    authorize?: (method: string, args: unknown[], auth: unknown) => boolean | null | Promise<boolean | null>;
+    /** Methods blocked for all callers. @default [] */
+    blockedMethods?: string[];
+}
+/** Per-connection session state stored on the WebSocket. */
+export interface WsSession {
+    /** The tenant scope extracted from `?scope=`. */
+    scope: string;
+    /** The auth context returned by `authenticate()`. */
+    auth: unknown;
+    /** The resolved Brainy instance for this scope. */
+    brain: Brainy;
+    /** Local transport wrapping the Brainy instance for this session. */
+    transport: LocalTransport;
+}
+/**
+ * The object returned by {@link createBrainyWsHandler}.
+ */
+export interface BrainyWsHandler {
+    /**
+     * Handles a WebSocket upgrade request.
+     *
+     * Extracts the token and scope from the request, authenticates, and resolves
+     * the Brainy instance. Returns `null` if authentication fails (caller should
+     * respond with 401 and not proceed with the upgrade).
+     *
+     * @param request - The HTTP upgrade Request.
+     * @returns Session state on success, or `null` on auth failure.
+     */
+    handleUpgrade(request: Request): Promise<WsSession | null>;
+    /**
+     * Processes an incoming WebSocket message.
+     *
+     * Decodes the MessagePack frame, dispatches the RPC, and calls `send` with
+     * the encoded response.
+     *
+     * @param session - The session state from `handleUpgrade()`.
+     * @param data - Raw binary message frame.
+     * @param send - Callback to send a binary response to this client.
+     */
+    handleMessage(session: WsSession, data: ArrayBuffer | Uint8Array, send: (msg: Uint8Array) => void): Promise<void>;
+    /**
+     * Broadcasts a Brainy change event to a connected client.
+     *
+     * Call this from your mutation hooks or after `brain.add()` / `brain.update()` /
+     * `brain.delete()` to push real-time updates to the client.
+     *
+     * @param event - The change event to broadcast.
+     * @param send - Callback to send the encoded event to the target client.
+     */
+    broadcastChange(event: BrainyChangeEvent, send: (msg: Uint8Array) => void): void;
+}
+/**
+ * Creates a server-side WebSocket handler for bidirectional Brainy RPC + change push.
+ *
+ * @param config - Handler configuration.
+ * @returns A {@link BrainyWsHandler} instance.
+ */
+export declare function createBrainyWsHandler(config: BrainyWsHandlerConfig): BrainyWsHandler;
+//# sourceMappingURL=handlers.d.ts.map

package/dist/server/handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../src/server/handlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AACvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AAMpE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;OAQG;IACH,YAAY,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAEnD;;;;;;;;OAQG;IACH,YAAY,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAA;IAE3D;;;;;;;;;;OAUG;IACH,SAAS,CAAC,EAAE,CACV,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EAAE,EACf,IAAI,EAAE,OAAO,KACV,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAA;IAE7C;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;CAC1B;AAQD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,mBAAmB,GAC1B,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CA0DzC;AAMD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;OAKG;IACH,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAEhD;;;;;;;;;OASG;IACH,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAA;IAEvE;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,CACV,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EAAE,EACf,IAAI,EAAE,OAAO,KACV,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAA;IAE7C,mDAAmD;IACnD,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;CAC1B;AAED,4DAA4D;AAC5D,MAAM,WAAW,SAAS;IACxB,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAA;IACb,qDAAqD;IACrD,IAAI,EAAE,OAAO,CAAA;IACb,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAA;IACb,qEAAqE;IACrE,SAAS,EAAE,cAAc,CAAA;CAC1B;AASD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;;;OASG;IACH,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAA;IAE1D;;;;;;;;;OASG;IACH,aAAa,CACX,OAAO,EAAE,SAAS,EAClB,IAAI,EAAE,WAAW,GAAG,UAAU,EAC9B,IAAI,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,IAAI,GAC9B,OAAO,CAAC,IAAI,CAAC,CAAA;IAEhB;;;;;;;;OAQG;IACH,eAAe,CAAC,KAAK,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,IAAI,GAAG,IAAI,CAAA;CACjF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,eAAe,CAkEpF"}

package/dist/server/handlers.js

@@ -0,0 +1,214 @@
+/**
+ * @module server/handlers
+ * @description HTTP RPC and WebSocket handler factories for mounting Brainy server endpoints.
+ *
+ * Products mount exactly two routes:
+ * - `POST /api/brainy/rpc` — handled by {@link createBrainyHandler}
+ * - `GET /api/brainy/ws` — WebSocket upgrade handled by {@link createBrainyWsHandler}
+ *
+ * Both factories are framework-agnostic — they accept and return `Request` / `Response`
+ * objects (Fetch API), making them compatible with SvelteKit, Hono, and raw Bun.serve.
+ *
+ * ## HTTP RPC handler
+ *
+ * Accepts `{ method: string, args: unknown[] }` as a JSON body and returns
+ * `{ result: unknown }` or `{ error: { code, message } }`. All authentication and
+ * authorization is delegated to the caller-supplied callbacks.
+ *
+ * ## WebSocket handler
+ *
+ * Accepts binary MessagePack frames. See wire protocol in `transports/ws.ts`.
+ * The `broadcastChange()` method on the returned handler pushes `BrainyChangeEvent`
+ * objects to connected clients.
+ *
+ * @example SvelteKit route mounting the HTTP handler
+ * ```typescript
+ * // src/routes/api/brainy/rpc/+server.ts
+ * import { createBrainyHandler } from '@soulcraft/sdk/server'
+ * import { pool } from '$lib/server/sdk'
+ * import { verifySession } from '$lib/server/auth'
+ *
+ * const handler = createBrainyHandler({
+ *   resolveBrain: async (req) => {
+ *     const userId = req.headers.get('x-user-id') ?? ''
+ *     const workspaceId = req.headers.get('x-workspace-id') ?? ''
+ *     return pool.forUser(userId, workspaceId)
+ *   },
+ *   authenticate: async (req) => verifySession(req.headers.get('cookie') ?? ''),
+ * })
+ *
+ * export const POST: RequestHandler = ({ request }) => handler(request)
+ * ```
+ *
+ * @example Bun.serve WebSocket upgrade
+ * ```typescript
+ * import { createBrainyWsHandler } from '@soulcraft/sdk/server'
+ * import { pool } from './sdk'
+ * import { verifyCapabilityToken } from '@soulcraft/sdk'
+ *
+ * const wsHandler = createBrainyWsHandler({
+ *   resolveBrain: (scope) => pool.forTenant(scope),
+ *   authenticate: (token, scope) => verifyCapabilityToken(token, process.env.VENUE_RPC_SECRET!),
+ * })
+ *
+ * Bun.serve({
+ *   async fetch(req, server) {
+ *     if (req.url.endsWith('/api/brainy/ws')) {
+ *       const session = await wsHandler.handleUpgrade(req)
+ *       if (!session) return new Response('Unauthorized', { status: 401 })
+ *       server.upgrade(req, { data: session })
+ *       return undefined
+ *     }
+ *     return new Response('Not found', { status: 404 })
+ *   },
+ *   websocket: {
+ *     async message(ws, data) {
+ *       await wsHandler.handleMessage(ws.data, data as ArrayBuffer, (msg) => ws.send(msg))
+ *     },
+ *   },
+ * })
+ * ```
+ */
+import { encode, decode } from '@msgpack/msgpack';
+import { LocalTransport } from '../transports/local.js';
+/**
+ * Creates a Fetch-API-compatible HTTP handler for Brainy RPC calls.
+ *
+ * Mount at `POST /api/brainy/rpc` in your product's router.
+ *
+ * @param config - Handler configuration.
+ * @returns `(request: Request) => Promise<Response>`
+ */
+export function createBrainyHandler(config) {
+    const { resolveBrain, authenticate, authorize, blockedMethods = [] } = config;
+    return async function brainyRpcHandler(request) {
+        // ── Auth ──────────────────────────────────────────────────────────────
+        const auth = await authenticate(request);
+        if (!auth)
+            return _jsonError(401, 'UNAUTHORIZED', 'Authentication required');
+        // ── Parse ─────────────────────────────────────────────────────────────
+        let body;
+        try {
+            body = (await request.json());
+        }
+        catch {
+            return _jsonError(400, 'BAD_REQUEST', 'Request body must be valid JSON');
+        }
+        if (typeof body.method !== 'string' || !Array.isArray(body.args)) {
+            return _jsonError(400, 'BAD_REQUEST', '{ method: string, args: unknown[] } required');
+        }
+        const method = body.method;
+        const args = body.args;
+        // ── Blocklist ─────────────────────────────────────────────────────────
+        if (blockedMethods.includes(method)) {
+            return _jsonError(403, 'FORBIDDEN', `Method '${method}' is not available via RPC`);
+        }
+        // ── Authorize ─────────────────────────────────────────────────────────
+        if (authorize) {
+            const allowed = await authorize(method, args, auth);
+            if (!allowed) {
+                return _jsonError(403, 'FORBIDDEN', `Not authorized to call '${method}'`);
+            }
+        }
+        // ── Resolve brain + dispatch ──────────────────────────────────────────
+        let brain;
+        try {
+            brain = await resolveBrain(request);
+        }
+        catch (err) {
+            console.error('[SDK/handler] resolveBrain threw:', err);
+            return _jsonError(503, 'BRAIN_UNAVAILABLE', 'Brainy instance not available');
+        }
+        const transport = new LocalTransport(brain);
+        try {
+            const result = await transport.call(method, args);
+            return new Response(JSON.stringify({ result }), {
+                status: 200,
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return _jsonError(500, 'RPC_ERROR', message);
+        }
+    };
+}
+/**
+ * Creates a server-side WebSocket handler for bidirectional Brainy RPC + change push.
+ *
+ * @param config - Handler configuration.
+ * @returns A {@link BrainyWsHandler} instance.
+ */
+export function createBrainyWsHandler(config) {
+    const { resolveBrain, authenticate, authorize, blockedMethods = [] } = config;
+    return {
+        async handleUpgrade(request) {
+            const url = new URL(request.url);
+            const scope = url.searchParams.get('scope') ?? '';
+            const authHeader = request.headers.get('authorization') ?? '';
+            const token = authHeader.startsWith('Bearer ') ? authHeader.slice(7) : '';
+            const auth = await authenticate(token, scope);
+            if (!auth)
+                return null;
+            const brain = await resolveBrain(scope);
+            const transport = new LocalTransport(brain);
+            return { scope, auth, brain, transport };
+        },
+        async handleMessage(session, data, send) {
+            let decoded;
+            try {
+                decoded = decode(data instanceof ArrayBuffer ? new Uint8Array(data) : data);
+            }
+            catch {
+                return; // Malformed frame — silently ignore
+            }
+            if (!decoded || typeof decoded !== 'object')
+                return;
+            const req = decoded;
+            if (typeof req.id !== 'string' || typeof req.method !== 'string' || !Array.isArray(req.args)) {
+                return;
+            }
+            const { id, method, args } = req;
+            if (blockedMethods.includes(method)) {
+                send(encode({ id, error: { code: 'FORBIDDEN', message: `Method '${method}' blocked` } }));
+                return;
+            }
+            if (authorize) {
+                const allowed = await authorize(method, args, session.auth);
+                if (!allowed) {
+                    send(encode({ id, error: { code: 'FORBIDDEN', message: `Not authorized: '${method}'` } }));
+                    return;
+                }
+            }
+            try {
+                const result = await session.transport.call(method, args);
+                send(encode({ id, result }));
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                send(encode({ id, error: { code: 'RPC_ERROR', message } }));
+            }
+        },
+        broadcastChange(event, send) {
+            send(encode(event));
+        },
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Internal helpers
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Builds a JSON error response with `{ error: { code, message } }` body.
+ *
+ * @param status - HTTP status code.
+ * @param code - Machine-readable error code.
+ * @param message - Human-readable description.
+ * @returns A `Response` with the error payload.
+ */
+function _jsonError(status, code, message) {
+    return new Response(JSON.stringify({ error: { code, message } }), {
+        status,
+        headers: { 'Content-Type': 'application/json' },
+    });
+}
+//# sourceMappingURL=handlers.js.map

package/dist/server/handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.js","sourceRoot":"","sources":["../../src/server/handlers.ts"],"names":[],"mappings":"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"}

package/dist/server/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @module @soulcraft/sdk/server
+ * @description Server entry point for @soulcraft/sdk. Exports everything needed to
+ * run the SDK in a product backend (Hono, SvelteKit, or any Bun/Node server).
+ *
+ * Includes: Brainy instance pool, HTTP and WebSocket RPC handler factories, and
+ * capability token utilities.
+ *
+ * This entry point must never be imported in browser bundles — it has hard
+ * server-only dependencies (`@soulcraft/brainy`, `lru-cache`, `crypto`, `fs`).
+ *
+ * @example Workshop server setup
+ * ```typescript
+ * import { BrainyInstancePool, createBrainyHandler, createBrainyWsHandler, computeEmailHash } from '@soulcraft/sdk/server'
+ * import { verifyCapabilityToken } from '@soulcraft/sdk'
+ *
+ * const pool = new BrainyInstancePool({
+ *   storage: 'mmap-filesystem',
+ *   dataPath: '/mnt/brainy-data',
+ *   strategy: 'per-user',
+ *   maxInstances: 200,
+ *   flushOnEvict: true,
+ * })
+ *
+ * const rpcHandler = createBrainyHandler({
+ *   resolveBrain: (req) => {
+ *     const userId = req.headers.get('x-email-hash') ?? ''
+ *     const workspaceId = req.headers.get('x-workspace-id') ?? ''
+ *     return pool.forUser(userId, workspaceId)
+ *   },
+ *   authenticate: (req) => verifySession(req.headers.get('cookie') ?? ''),
+ * })
+ * ```
+ */
+export { BrainyInstancePool, BrainyInitializingError, computeEmailHash, } from './instance-pool.js';
+export type { InstancePoolConfig, InstancePoolStats, } from './instance-pool.js';
+export { createBrainyHandler, createBrainyWsHandler, } from './handlers.js';
+export type { BrainyHandlerConfig, BrainyWsHandlerConfig, BrainyWsHandler, WsSession, } from './handlers.js';
+export { createHallRoomHandler, generateTurnCredentials, } from './hall-handlers.js';
+export type { HallRoomHandlerConfig, HallRoomHandler, HallSession, TurnCredentialOptions, TurnCredentials, } from './hall-handlers.js';
+export { createAuthMiddleware, createRemoteSessionVerifier, AUTH_USER_KEY, } from '../modules/auth/middleware.js';
+export type { AuthMiddlewareOptions, AuthMiddleware, AuthContext, BetterAuthLike, RemoteSessionVerifierOptions, } from '../modules/auth/middleware.js';
+export { createBackchannelLogoutHandler } from '../modules/auth/backchannel.js';
+export type { BackchannelLogoutConfig, BackchannelAuthLike, } from '../modules/auth/backchannel.js';
+export { SOULCRAFT_USER_FIELDS, SOULCRAFT_SESSION_CONFIG, getAuthMode, getOIDCClientConfig, } from '../modules/auth/config.js';
+export { createSDK } from './create-sdk.js';
+export type { CreateSDKOptions } from './create-sdk.js';
+export type { ServerSDKOptions } from '../types.js';
+export { createCapabilityToken, verifyCapabilityToken } from '../modules/brainy/auth.js';
+export type { CreateCapabilityTokenOptions, CapabilityTokenClaims } from '../modules/brainy/auth.js';
+export { LocalTransport } from '../transports/local.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,oBAAoB,CAAA;AAC3B,YAAY,EACV,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,oBAAoB,CAAA;AAG3B,OAAO,EACL,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,eAAe,CAAA;AACtB,YAAY,EACV,mBAAmB,EACnB,qBAAqB,EACrB,eAAe,EACf,SAAS,GACV,MAAM,eAAe,CAAA;AAGtB,OAAO,EACL,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,oBAAoB,CAAA;AAC3B,YAAY,EACV,qBAAqB,EACrB,eAAe,EACf,WAAW,EACX,qBAAqB,EACrB,eAAe,GAChB,MAAM,oBAAoB,CAAA;AAG3B,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,aAAa,GACd,MAAM,+BAA+B,CAAA;AACtC,YAAY,EACV,qBAAqB,EACrB,cAAc,EACd,WAAW,EACX,cAAc,EACd,4BAA4B,GAC7B,MAAM,+BAA+B,CAAA;AACtC,OAAO,EAAE,8BAA8B,EAAE,MAAM,gCAAgC,CAAA;AAC/E,YAAY,EACV,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,gCAAgC,CAAA;AAGvC,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,WAAW,EACX,mBAAmB,GACpB,MAAM,2BAA2B,CAAA;AAGlC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAGvD,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AACnD,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAA;AACxF,YAAY,EAAE,4BAA4B,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAA;AACpG,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA"}

package/dist/server/index.js

@@ -0,0 +1,50 @@
+/**
+ * @module @soulcraft/sdk/server
+ * @description Server entry point for @soulcraft/sdk. Exports everything needed to
+ * run the SDK in a product backend (Hono, SvelteKit, or any Bun/Node server).
+ *
+ * Includes: Brainy instance pool, HTTP and WebSocket RPC handler factories, and
+ * capability token utilities.
+ *
+ * This entry point must never be imported in browser bundles — it has hard
+ * server-only dependencies (`@soulcraft/brainy`, `lru-cache`, `crypto`, `fs`).
+ *
+ * @example Workshop server setup
+ * ```typescript
+ * import { BrainyInstancePool, createBrainyHandler, createBrainyWsHandler, computeEmailHash } from '@soulcraft/sdk/server'
+ * import { verifyCapabilityToken } from '@soulcraft/sdk'
+ *
+ * const pool = new BrainyInstancePool({
+ *   storage: 'mmap-filesystem',
+ *   dataPath: '/mnt/brainy-data',
+ *   strategy: 'per-user',
+ *   maxInstances: 200,
+ *   flushOnEvict: true,
+ * })
+ *
+ * const rpcHandler = createBrainyHandler({
+ *   resolveBrain: (req) => {
+ *     const userId = req.headers.get('x-email-hash') ?? ''
+ *     const workspaceId = req.headers.get('x-workspace-id') ?? ''
+ *     return pool.forUser(userId, workspaceId)
+ *   },
+ *   authenticate: (req) => verifySession(req.headers.get('cookie') ?? ''),
+ * })
+ * ```
+ */
+// ── Instance pool ─────────────────────────────────────────────────────────────
+export { BrainyInstancePool, BrainyInitializingError, computeEmailHash, } from './instance-pool.js';
+// ── Handler factories ─────────────────────────────────────────────────────────
+export { createBrainyHandler, createBrainyWsHandler, } from './handlers.js';
+// ── Hall handler factories ────────────────────────────────────────────────────
+export { createHallRoomHandler, generateTurnCredentials, } from './hall-handlers.js';
+// ── Auth middleware + backchannel logout ──────────────────────────────────────
+export { createAuthMiddleware, createRemoteSessionVerifier, AUTH_USER_KEY, } from '../modules/auth/middleware.js';
+export { createBackchannelLogoutHandler } from '../modules/auth/backchannel.js';
+// ── Auth config helpers (also on shared entry, duplicated here for convenience) ─
+export { SOULCRAFT_USER_FIELDS, SOULCRAFT_SESSION_CONFIG, getAuthMode, getOIDCClientConfig, } from '../modules/auth/config.js';
+// ── createSDK factory ─────────────────────────────────────────────────────────
+export { createSDK } from './create-sdk.js';
+export { createCapabilityToken, verifyCapabilityToken } from '../modules/brainy/auth.js';
+export { LocalTransport } from '../transports/local.js';
+//# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,iFAAiF;AACjF,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,oBAAoB,CAAA;AAM3B,iFAAiF;AACjF,OAAO,EACL,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,eAAe,CAAA;AAQtB,iFAAiF;AACjF,OAAO,EACL,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,oBAAoB,CAAA;AAS3B,iFAAiF;AACjF,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,aAAa,GACd,MAAM,+BAA+B,CAAA;AAQtC,OAAO,EAAE,8BAA8B,EAAE,MAAM,gCAAgC,CAAA;AAM/E,mFAAmF;AACnF,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,WAAW,EACX,mBAAmB,GACpB,MAAM,2BAA2B,CAAA;AAElC,iFAAiF;AACjF,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAK3C,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAA;AAExF,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA"}