@soulcraft/sdk 2.8.0 → 3.0.0

package/docs/KIT-APP-GUIDE.md

@@ -13,7 +13,7 @@ A kit app is a full-stack application powered by three things:
 ```
 @soulcraft/kits     → Domain config (kit.json manifest + SKILL.md prompts)
 @soulcraft/sdk      → Runtime: data, AI, files, realtime, auth, notifications
-Your app code       → Svelte frontend + Hono/Bun backend that wires them together
+Your app code       → Svelte frontend + Bun/SvelteKit backend that wires them together
 ```
 
 The SDK is your single source of truth for everything the app does at runtime.
@@ -29,9 +29,15 @@ bun add @soulcraft/sdk @soulcraft/brainy @soulcraft/kits
 ```
 
 ```typescript
-// server.ts — minimal kit app server
-import { Hono } from 'hono'
-import { BrainyInstancePool, createSDK, createAuthMiddleware } from '@soulcraft/sdk/server'
+// server.ts — minimal kit app server (Bun)
+import {
+  BrainyInstancePool,
+  createSDK,
+  createRequestAuthMiddleware,
+  createRemoteSessionVerifier,
+  createDevSessionVerifier,
+  getUser,
+} from '@soulcraft/sdk/server'
 import { AI_MODELS } from '@soulcraft/sdk'
 
 const pool = new BrainyInstancePool({
@@ -41,15 +47,21 @@ const pool = new BrainyInstancePool({
   maxInstances: 100,
 })
 
-const app = new Hono()
+const verifySession = process.env.SOULCRAFT_IDP_URL
+  ? createRemoteSessionVerifier({ idpUrl: process.env.SOULCRAFT_IDP_URL })
+  : createDevSessionVerifier({ role: 'owner' })
+const { requireAuth } = createRequestAuthMiddleware(verifySession)
 
-app.get('/api/ask', async (c) => {
-  const brain = await pool.forUser('user-hash', 'workspace-id')
-  const sdk = createSDK({ brain })
+async function handleAsk(req: Request): Promise<Response> {
+  return requireAuth(req, async () => {
+    const user = getUser(req)!
+    const url = new URL(req.url)
+    const brain = await pool.forUser(user.emailHash, 'workspace-id')
+    const sdk = createSDK({ brain })
 
-  const kit = await sdk.kits.load('your-kit-id')
-  const response = await sdk.ai.complete({
-    messages: [{ role: 'user', content: c.req.query('q') ?? 'Hello' }],
+    const kit = await sdk.kits.load('your-kit-id')
+    const response = await sdk.ai.complete({
+      messages: [{ role: 'user', content: url.searchParams.get('q') ?? 'Hello' }],
     systemPrompt: kit?.shared?.aiPersona,
     model: AI_MODELS.sonnet,
   })
@@ -67,9 +79,9 @@ export default { port: 3000, fetch: app.fetch, idleTimeout: 255 }
 Three import paths — **always use the right one**:
 
 ```typescript
-// 1. SERVER — Hono routes, SvelteKit +server.ts, Bun scripts, background jobs
-import { BrainyInstancePool, createSDK, createAuthMiddleware } from '@soulcraft/sdk/server'
-import type { SoulcraftSessionUser, AuthContext } from '@soulcraft/sdk'
+// 1. SERVER — SvelteKit +server.ts, Bun scripts, background jobs
+import { BrainyInstancePool, createSDK, createRequestAuthMiddleware, getUser } from '@soulcraft/sdk/server'
+import type { SoulcraftSessionUser } from '@soulcraft/sdk'
 
 // 2. BROWSER — Svelte components, SvelteKit +page.svelte, kit frontend code
 import { createBrainyProxy, HttpTransport, WsTransport, joinHallRoom } from '@soulcraft/sdk/client'
@@ -635,44 +647,39 @@ await pool.shutdown()
 
 ## Authentication
 
-### Middleware (Hono)
+### Auth Middleware (Framework-Agnostic)
 
 ```typescript
-import { betterAuth } from 'better-auth'
-import { Database } from 'bun:sqlite'
 import {
-  SOULCRAFT_USER_FIELDS,
-  SOULCRAFT_SESSION_CONFIG,
-  computeEmailHash,
-  createAuthMiddleware,
+  createRequestAuthMiddleware,
+  createRemoteSessionVerifier,
+  createDevSessionVerifier,
+  getUser,
 } from '@soulcraft/sdk/server'
 
-const auth = betterAuth({
-  database: new Database('./auth.db'),
-  secret: process.env.BETTER_AUTH_SECRET!,
-  session: SOULCRAFT_SESSION_CONFIG,
-  user: { additionalFields: SOULCRAFT_USER_FIELDS },
-  databaseHooks: {
-    user: {
-      create: {
-        before: async (user) => ({
-          data: { ...user, emailHash: computeEmailHash(user.email), platformRole: 'creator' }
-        }),
-      },
-    },
-  },
-})
+const verifySession = process.env.SOULCRAFT_IDP_URL
+  ? createRemoteSessionVerifier({ idpUrl: process.env.SOULCRAFT_IDP_URL })
+  : createDevSessionVerifier({ role: 'owner' })
 
-const { requireAuth, optionalAuth } = createAuthMiddleware(auth)
+const { requireAuth, optionalAuth } = createRequestAuthMiddleware(verifySession)
 
-app.all('/api/auth/*', (c) => auth.handler(c.req.raw))
+// SvelteKit hooks.server.ts:
+export const handle = async ({ event, resolve }) => {
+  const response = await requireAuth(event.request, () => resolve(event))
+  event.locals.user = getUser(event.request)
+  return response
+}
 
-app.get('/api/data', requireAuth, async (c) => {
-  const user = c.get('user')!   // SoulcraftSessionUser — id, email, emailHash, platformRole
-  const brain = await pool.forUser(user.emailHash, 'main')
-  const sdk = createSDK({ brain })
-  // ...
-})
+// Or in a Bun route:
+async function handleData(req: Request): Promise<Response> {
+  return requireAuth(req, async () => {
+    const user = getUser(req)! // SoulcraftSessionUser — id, email, emailHash, platformRole
+    const brain = await pool.forUser(user.emailHash, 'main')
+    const sdk = createSDK({ brain })
+    // ...
+    return new Response(JSON.stringify({ ok: true }))
+  })
+}
 ```
 
 ### Capability Tokens (Cross-Product Server Calls)
@@ -766,16 +773,13 @@ await sdk.versions.restore('product-lavender-soy', 3)
 A complete kit app server combining auth, data, AI, and events:
 
 ```typescript
-import { Hono } from 'hono'
-import { betterAuth } from 'better-auth'
-import { Database } from 'bun:sqlite'
 import {
   BrainyInstancePool,
   createSDK,
-  createAuthMiddleware,
-  SOULCRAFT_USER_FIELDS,
-  SOULCRAFT_SESSION_CONFIG,
-  computeEmailHash,
+  createRequestAuthMiddleware,
+  createRemoteSessionVerifier,
+  createDevSessionVerifier,
+  getUser,
 } from '@soulcraft/sdk/server'
 import { AI_MODELS } from '@soulcraft/sdk'
 
@@ -785,23 +789,11 @@ const KIT_ID = 'your-kit-id'
 
 // ── Auth ──────────────────────────────────────────────────────────────────────
 
-const auth = betterAuth({
-  database: new Database('./auth.db'),
-  secret: process.env.BETTER_AUTH_SECRET!,
-  session: SOULCRAFT_SESSION_CONFIG,
-  user: { additionalFields: SOULCRAFT_USER_FIELDS },
-  databaseHooks: {
-    user: {
-      create: {
-        before: async (u) => ({
-          data: { ...u, emailHash: computeEmailHash(u.email), platformRole: 'creator' },
-        }),
-      },
-    },
-  },
-})
+const verifySession = process.env.SOULCRAFT_IDP_URL
+  ? createRemoteSessionVerifier({ idpUrl: process.env.SOULCRAFT_IDP_URL })
+  : createDevSessionVerifier({ role: 'owner' })
 
-const { requireAuth } = createAuthMiddleware(auth)
+const { requireAuth } = createRequestAuthMiddleware(verifySession)
 
 // ── Brainy pool ───────────────────────────────────────────────────────────────
 
@@ -813,54 +805,63 @@ const pool = new BrainyInstancePool({
   flushOnEvict: true,
 })
 
-// ── App ───────────────────────────────────────────────────────────────────────
+// ── Route handlers ────────────────────────────────────────────────────────────
 
-const app = new Hono()
+async function handleItems(req: Request): Promise<Response> {
+  return requireAuth(req, async () => {
+    const user = getUser(req)!
+    const brain = await pool.forUser(user.emailHash, 'main')
+    const sdk = createSDK({ brain })
 
-app.all('/api/auth/*', (c) => auth.handler(c.req.raw))
-
-app.get('/api/items', requireAuth, async (c) => {
-  const user = c.get('user')!
-  const brain = await pool.forUser(user.emailHash, 'main')
-  const sdk = createSDK({ brain })
+    const items = await sdk.brainy.find({
+      query: 'all items',
+      limit: 100,
+    })
 
-  const items = await sdk.brainy.find({
-    query: 'all items',
-    limit: 100,
+    return new Response(JSON.stringify({ items }), {
+      headers: { 'Content-Type': 'application/json' },
+    })
   })
+}
 
-  return c.json({ items })
-})
+async function handleAsk(req: Request): Promise<Response> {
+  return requireAuth(req, async () => {
+    const user = getUser(req)!
+    const { question } = await req.json() as { question: string }
 
-app.post('/api/ask', requireAuth, async (c) => {
-  const user = c.get('user')!
-  const { question } = await c.req.json<{ question: string }>()
+    const brain = await pool.forUser(user.emailHash, 'main')
+    const sdk = createSDK({ brain })
 
-  const brain = await pool.forUser(user.emailHash, 'main')
-  const sdk = createSDK({ brain })
+    const kit = await sdk.kits.load(KIT_ID)
+    const skills = await sdk.skills.list({ kitId: KIT_ID })
 
-  const kit = await sdk.kits.load(KIT_ID)
-  const skills = await sdk.skills.list({ kitId: KIT_ID })
+    const systemPrompt = [
+      kit?.shared?.aiPersona,
+      ...skills.map(s => s.content),
+    ].filter(Boolean).join('\n\n---\n\n')
 
-  const systemPrompt = [
-    kit?.shared?.aiPersona,
-    ...skills.map(s => s.content),
-  ].filter(Boolean).join('\n\n---\n\n')
+    const response = await sdk.ai.complete({
+      messages: [{ role: 'user', content: question }],
+      systemPrompt,
+      model: AI_MODELS.sonnet,
+    })
 
-  const response = await sdk.ai.complete({
-    messages: [{ role: 'user', content: question }],
-    systemPrompt,
-    model: AI_MODELS.sonnet,
+    return new Response(JSON.stringify({ answer: response.text }), {
+      headers: { 'Content-Type': 'application/json' },
+    })
   })
-
-  return c.json({ answer: response.text })
-})
+}
 
 // ── Server ────────────────────────────────────────────────────────────────────
 
 export default {
   port: Number(process.env.PORT ?? 3000),
-  fetch: app.fetch,
+  fetch(req: Request): Promise<Response> | Response {
+    const url = new URL(req.url)
+    if (url.pathname === '/api/items') return handleItems(req)
+    if (url.pathname === '/api/ask' && req.method === 'POST') return handleAsk(req)
+    return new Response('Not found', { status: 404 })
+  },
   idleTimeout: 255,   // CRITICAL: prevents Bun's 10s default from killing long Brainy inits
 }
 ```

package/docs/USAGE.md

@@ -4,7 +4,7 @@ This guide is for engineers, AI assistants, kit developers, and anyone building
 the Soulcraft platform. It covers every implemented module with working examples.
 
 **Three rules to remember:**
-1. Server code (Hono, SvelteKit routes, Bun backends) imports from `@soulcraft/sdk/server`
+1. Server code (SvelteKit routes, Bun backends) imports from `@soulcraft/sdk/server`
 2. Browser code (kit apps, Svelte components) imports from `@soulcraft/sdk/client`
 3. Shared types import from `@soulcraft/sdk`
 
@@ -512,49 +512,39 @@ console.log(claims.exp)     // expiry timestamp (ms)
 
 ## Auth Middleware
 
-The SDK provides Hono middleware that resolves better-auth sessions and injects the
-typed user into request context.
+The SDK provides framework-agnostic auth middleware using Web Standard
+Request/Response. Works with SvelteKit, Bun.serve, Deno, and any server.
 
 ```typescript
-import { betterAuth } from 'better-auth'
 import {
-  SOULCRAFT_USER_FIELDS,
-  SOULCRAFT_SESSION_CONFIG,
-  computeEmailHash,
-  createAuthMiddleware,
+  createRequestAuthMiddleware,
+  createRemoteSessionVerifier,
+  createDevSessionVerifier,
+  getUser,
 } from '@soulcraft/sdk/server'
-import type { AuthContext } from '@soulcraft/sdk/server'
-
-// 1. Configure better-auth with Soulcraft fields:
-const auth = betterAuth({
-  database: new Database('./auth.db'),
-  secret: process.env.BETTER_AUTH_SECRET!,
-  session: SOULCRAFT_SESSION_CONFIG,     // 30-day sessions, 24h refresh
-  user: { additionalFields: SOULCRAFT_USER_FIELDS },
-  databaseHooks: {
-    user: {
-      create: {
-        before: async (user) => ({
-          data: { ...user, emailHash: computeEmailHash(user.email), platformRole: 'creator' }
-        })
-      }
-    }
-  },
-})
-
-// 2. Create middleware:
-const { requireAuth, optionalAuth } = createAuthMiddleware(auth)
 
-// 3. Use in routes:
-app.all('/api/auth/*', (c) => auth.handler(c.req.raw))
+// 1. Create a session verifier:
+const verifySession = process.env.SOULCRAFT_IDP_URL
+  ? createRemoteSessionVerifier({ idpUrl: process.env.SOULCRAFT_IDP_URL })
+  : createDevSessionVerifier({ role: 'owner' })
 
-app.get('/api/data', requireAuth, async (c) => {
-  const user = c.get('user')!   // SoulcraftSessionUser — always non-null after requireAuth
-  // user.id, user.email, user.emailHash, user.platformRole
-})
+// 2. Create middleware:
+const { requireAuth, optionalAuth } = createRequestAuthMiddleware(verifySession)
+
+// 3. Use in routes (SvelteKit example):
+// hooks.server.ts
+export const handle = async ({ event, resolve }) => {
+  const response = await requireAuth(event.request, () => resolve(event))
+  event.locals.user = getUser(event.request)
+  return response
+}
 
-app.get('/api/public', optionalAuth, async (c) => {
-  const user = c.get('user')    // SoulcraftSessionUser | null
+// 4. Use in routes (Bun example):
+Bun.serve({
+  fetch: (req) => optionalAuth(req, async () => {
+    const user = getUser(req) // SoulcraftSessionUser | null
+    return new Response(JSON.stringify({ user: user?.email ?? 'anonymous' }))
+  }),
 })
 ```
 
@@ -810,9 +800,9 @@ When helping implement Soulcraft server code, follow this checklist:
 
 **1. Import correctly:**
 ```typescript
-// Server code (Hono, SvelteKit server routes, Bun scripts):
-import { BrainyInstancePool, createSDK, createAuthMiddleware, computeEmailHash } from '@soulcraft/sdk/server'
-import type { SoulcraftSessionUser, AuthContext } from '@soulcraft/sdk'
+// Server code (SvelteKit server routes, Bun scripts):
+import { BrainyInstancePool, createRequestAuthMiddleware, computeEmailHash, getUser } from '@soulcraft/sdk/server'
+import type { SoulcraftSessionUser } from '@soulcraft/sdk'
 
 // Shared types only:
 import { AI_MODELS } from '@soulcraft/sdk'

package/docs/kit-sdk-guide.md

@@ -32,10 +32,10 @@ Install the SDK in your server application:
 bun add @soulcraft/sdk @soulcraft/brainy
 ```
 
-For server-side use (Node.js, Bun, Hono, SvelteKit server routes):
+For server-side use (Node.js, Bun, SvelteKit server routes):
 
 ```typescript
-import { BrainyInstancePool, createSDK, createAuthMiddleware } from '@soulcraft/sdk/server'
+import { BrainyInstancePool, createSDK, createRequestAuthMiddleware, getUser } from '@soulcraft/sdk/server'
 import type { SoulcraftSessionUser } from '@soulcraft/sdk'
 ```
 
@@ -348,16 +348,13 @@ if (!claims) return c.json({ error: 'Unauthorized' }, 401)
 A minimal kit application combining auth, Brainy, and AI:
 
 ```typescript
-import { Hono } from 'hono'
-import { betterAuth } from 'better-auth'
-import { Database } from 'bun:sqlite'
 import {
   BrainyInstancePool,
   createSDK,
-  createAuthMiddleware,
-  SOULCRAFT_USER_FIELDS,
-  SOULCRAFT_SESSION_CONFIG,
-  computeEmailHash,
+  createRequestAuthMiddleware,
+  createRemoteSessionVerifier,
+  createDevSessionVerifier,
+  getUser,
 } from '@soulcraft/sdk/server'
 import { AI_MODELS } from '@soulcraft/sdk'
 import { kitRegistry } from '@soulcraft/kits'
@@ -366,22 +363,10 @@ import { kitRegistry } from '@soulcraft/kits'
 const kit = kitRegistry['wicks-and-whiskers']
 
 // ── Auth ──────────────────────────────────────────────────────────────────────
-const auth = betterAuth({
-  database: new Database('./auth.db'),
-  secret: process.env.BETTER_AUTH_SECRET!,
-  session: SOULCRAFT_SESSION_CONFIG,
-  user: { additionalFields: SOULCRAFT_USER_FIELDS },
-  databaseHooks: {
-    user: {
-      create: {
-        before: async (u) => ({
-          data: { ...u, emailHash: computeEmailHash(u.email), platformRole: 'creator' }
-        })
-      }
-    }
-  },
-})
-const { requireAuth } = createAuthMiddleware(auth)
+const verifySession = process.env.SOULCRAFT_IDP_URL
+  ? createRemoteSessionVerifier({ idpUrl: process.env.SOULCRAFT_IDP_URL })
+  : createDevSessionVerifier({ role: 'owner' })
+const { requireAuth } = createRequestAuthMiddleware(verifySession)
 
 // ── Brainy pool ───────────────────────────────────────────────────────────────
 const pool = new BrainyInstancePool({
@@ -391,48 +376,62 @@ const pool = new BrainyInstancePool({
   maxInstances: 100,
 })
 
-// ── Hono app ──────────────────────────────────────────────────────────────────
-const app = new Hono()
+// ── Route handlers ────────────────────────────────────────────────────────────
 
-app.all('/api/auth/*', (c) => auth.handler(c.req.raw))
+async function handleInventory(req: Request): Promise<Response> {
+  return requireAuth(req, async () => {
+    const user = getUser(req)!
+    const brain = await pool.forUser(user.emailHash, 'main')
+    const sdk = createSDK({ brain })
 
-app.get('/api/inventory', requireAuth, async (c) => {
-  const user = c.get('user')!
-  const brain = await pool.forUser(user.emailHash, 'main')
-  const sdk = createSDK({ brain })
+    const items = await sdk.brainy.find({
+      query: 'inventory items in stock',
+      type: 'Product',
+      limit: 50,
+    })
 
-  const items = await sdk.brainy.find({
-    query: 'inventory items in stock',
-    type: 'Product',
-    limit: 50,
+    return new Response(JSON.stringify({ kit: kit.name, items }), {
+      headers: { 'Content-Type': 'application/json' },
+    })
   })
+}
 
-  return c.json({ kit: kit.name, items })
-})
-
-app.post('/api/ask', requireAuth, async (c) => {
-  const user = c.get('user')!
-  const { question } = await c.req.json<{ question: string }>()
-
-  const brain = await pool.forUser(user.emailHash, 'main')
-  const sdk = createSDK({ brain })
-
-  const skills = await sdk.skills.list({ kitId: 'wicks-and-whiskers' })
-  const systemPrompt = [
-    kit.shared.aiPersona,
-    ...skills.map(s => s.content),
-  ].join('\n\n')
-
-  const response = await sdk.ai.complete({
-    messages: [{ role: 'user', content: question }],
-    systemPrompt,
-    model: AI_MODELS.haiku,
+async function handleAsk(req: Request): Promise<Response> {
+  return requireAuth(req, async () => {
+    const user = getUser(req)!
+    const { question } = await req.json() as { question: string }
+
+    const brain = await pool.forUser(user.emailHash, 'main')
+    const sdk = createSDK({ brain })
+
+    const skills = await sdk.skills.list({ kitId: 'wicks-and-whiskers' })
+    const systemPrompt = [
+      kit.shared.aiPersona,
+      ...skills.map(s => s.content),
+    ].join('\n\n')
+
+    const response = await sdk.ai.complete({
+      messages: [{ role: 'user', content: question }],
+      systemPrompt,
+      model: AI_MODELS.haiku,
+    })
+
+    return new Response(JSON.stringify({ answer: response.text }), {
+      headers: { 'Content-Type': 'application/json' },
+    })
   })
+}
 
-  return c.json({ answer: response.text })
-})
-
-export default app
+// ── Bun server ────────────────────────────────────────────────────────────────
+export default {
+  port: Number(process.env.PORT ?? 3000),
+  fetch(req: Request) {
+    const url = new URL(req.url)
+    if (url.pathname === '/api/inventory') return handleInventory(req)
+    if (url.pathname === '/api/ask' && req.method === 'POST') return handleAsk(req)
+    return new Response('Not found', { status: 404 })
+  },
+}
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/sdk",
-  "version": "2.8.0",
+  "version": "3.0.0",
   "description": "The unified Soulcraft platform SDK — data, auth, AI, billing, and notifications",
   "type": "module",
   "publishConfig": {