kanban-lite 1.2.2 → 1.2.4

package/src/sdk/plugins/index.ts

@@ -138,6 +138,8 @@ interface AuthPluginModule {
   readonly createRbacIdentityPlugin?: unknown
   /** Optional factory for a configurable policy plugin. When present it is called with the provider options from `.kanban.json` so plugins can apply per-deployment overrides such as a custom RBAC matrix. */
   readonly createAuthPolicyPlugin?: ((options?: Record<string, unknown>) => unknown) | unknown
+  /** Optional factory for a configurable identity plugin. When present it is called with the provider options from `.kanban.json` so plugins can apply per-deployment overrides such as an explicit API token. */
+  readonly createAuthIdentityPlugin?: ((options?: Record<string, unknown>) => unknown) | unknown
   readonly default?: unknown
 }
 
@@ -345,7 +347,7 @@ function resolveAuthIdentityPlugin(ref: ProviderRef): AuthIdentityPlugin {
   if (ref.provider === 'noop') return NOOP_IDENTITY_PLUGIN
   if (ref.provider === 'rbac') return RBAC_IDENTITY_PLUGIN
   const packageName = AUTH_PROVIDER_ALIASES.get(ref.provider) ?? ref.provider
-  return loadExternalAuthIdentityPlugin(packageName, ref.provider)
+  return loadExternalAuthIdentityPlugin(packageName, ref.provider, ref.options)
 }
 
 function resolveAuthPolicyPlugin(ref: ProviderRef): AuthPolicyPlugin {
@@ -621,6 +623,13 @@ export type StandaloneHttpHandler = (request: StandaloneHttpRequestContext) => P
  * resolved the active workspace capability selections.
  */
 export interface StandaloneHttpPluginRegistrationOptions {
+  /**
+   * Active SDK instance backing the standalone runtime, when provided by the host.
+   *
+   * Plugin registration code may use the full public {@link KanbanSDK} surface,
+   * including `getConfigSnapshot()`, when this seam is available.
+   */
+  readonly sdk?: KanbanSDK
   /** Absolute workspace root containing `.kanban.json`. */
   readonly workspaceRoot: string
   /** Absolute workspace `.kanban` directory. */
@@ -1087,8 +1096,14 @@ function selectAuthPolicyPlugin(mod: AuthPluginModule, providerId: string): Auth
   return null
 }
 
-function loadExternalAuthIdentityPlugin(packageName: string, providerId: string): AuthIdentityPlugin {
+function loadExternalAuthIdentityPlugin(packageName: string, providerId: string, options?: Record<string, unknown>): AuthIdentityPlugin {
   const mod = loadExternalModule(packageName) as AuthPluginModule
+
+  if (options !== undefined && typeof mod.createAuthIdentityPlugin === 'function') {
+    const created = (mod.createAuthIdentityPlugin as (opts?: Record<string, unknown>) => unknown)(options)
+    if (isValidAuthIdentityPlugin(created, providerId)) return created
+  }
+
   const plugin = selectAuthIdentityPlugin(mod, providerId)
   if (!plugin) {
     throw new Error(

package/src/sdk/types.d.ts

@@ -58,7 +58,7 @@ export type SDKBeforeEventType = 'card.create' | 'card.update' | 'card.move' | '
  *
  * @see AfterEventPayload for the payload envelope passed to after-event listeners.
  */
-export type SDKAfterEventType = 'task.created' | 'task.updated' | 'task.moved' | 'task.deleted' | 'comment.created' | 'comment.updated' | 'comment.deleted' | 'column.created' | 'column.updated' | 'column.deleted' | 'attachment.added' | 'attachment.removed' | 'settings.updated' | 'board.created' | 'board.updated' | 'board.deleted' | 'board.action' | 'board.log.added' | 'board.log.cleared' | 'log.added' | 'log.cleared' | 'storage.migrated' | 'form.submitted' | 'auth.allowed' | 'auth.denied';
+export type SDKAfterEventType = 'task.created' | 'task.updated' | 'task.moved' | 'task.deleted' | 'comment.created' | 'comment.updated' | 'comment.deleted' | 'column.created' | 'column.updated' | 'column.deleted' | 'attachment.added' | 'attachment.removed' | 'settings.updated' | 'board.created' | 'board.updated' | 'board.deleted' | 'board.action' | 'card.action.triggered' | 'board.log.added' | 'board.log.cleared' | 'log.added' | 'log.cleared' | 'storage.migrated' | 'form.submitted' | 'auth.allowed' | 'auth.denied';
 /**
  * Union of all SDK event types (before-events and after-events).
  *
@@ -468,29 +468,11 @@ export declare class CardStateError extends Error {
     constructor(code: CardStateErrorCode, message: string);
 }
 /**
- * Minimal SDK webhook facade supplied to CLI plugins via {@link CliPluginContext}.
- *
- * Structural subset of `KanbanSDK`; plugins should use this surface instead of
- * importing `KanbanSDK` directly so they remain decoupled from core internals.
+ * @deprecated Use {@link KanbanSDK}. CLI plugin hosts now advertise the full
+ * public SDK surface, including `getConfigSnapshot()`, instead of a narrowed
+ * webhook-only facade.
  */
-export interface CliPluginSdk {
-    /**
-     * Returns the SDK extension bag contributed by the plugin with the given id,
-     * when the host is backed by a full `KanbanSDK` instance.
-     *
-     * CLI plugins should prefer this extension path when available and fall back
-     * to compatibility methods only when running against older or mocked SDK facades.
-     */
-    getExtension?<T extends Record<string, unknown> = Record<string, unknown>>(id: string): T | undefined;
-    listWebhooks(): Webhook[];
-    createWebhook(input: {
-        url: string;
-        events: string[];
-        secret?: string;
-    }): Promise<Webhook>;
-    updateWebhook(id: string, updates: Partial<Pick<Webhook, 'url' | 'events' | 'secret' | 'active'>>): Promise<Webhook | null>;
-    deleteWebhook(id: string): Promise<boolean>;
-}
+export type CliPluginSdk = KanbanSDK;
 /**
  * Runtime context supplied to a {@link KanbanCliPlugin} when it is invoked by
  * the `kl` CLI.
@@ -503,10 +485,12 @@ export interface CliPluginContext {
      *
      * Present when the plugin is invoked through the core `kl` CLI.
      * Absent in isolated unit tests or standalone invocations.
-     * Plugins should prefer this over constructing their own SDK so that
-     * SDK-level auth policy is honoured.
+    * Plugins may use the full public {@link KanbanSDK} contract here, including
+    * extension lookup and `getConfigSnapshot()`, instead of relying on older
+    * helper-only SDK facades. Plugins should prefer this over constructing their
+    * own SDK so that SDK-level auth policy is honoured.
      */
-    sdk?: CliPluginSdk;
+    sdk?: KanbanSDK;
     /**
      * Core-owned CLI auth helper.
      *

package/src/sdk/types.ts

@@ -1,5 +1,6 @@
 import type { Card, CardFormAttachment, CardFormDataMap, Priority, ResolvedFormDescriptor } from '../shared/types'
 import type { CapabilitySelections, Webhook } from '../shared/config'
+import type { KanbanSDK } from './KanbanSDK'
 import type { StorageEngine, StorageEngineType } from './plugins/types'
 import type { CardStateCursor } from './plugins'
 
@@ -118,6 +119,7 @@ export type SDKAfterEventType =
   | 'board.updated'
   | 'board.deleted'
   | 'board.action'
+  | 'card.action.triggered'
   | 'board.log.added'
   | 'board.log.cleared'
   | 'log.added'
@@ -614,28 +616,11 @@ export class CardStateError extends Error {
 }
 
 /**
- * Minimal SDK webhook facade supplied to CLI plugins via {@link CliPluginContext}.
- *
- * Structural subset of `KanbanSDK`; plugins should use this surface instead of
- * importing `KanbanSDK` directly so they remain decoupled from core internals.
+ * @deprecated Use {@link KanbanSDK}. CLI plugin hosts now advertise the full
+ * public SDK surface, including `getConfigSnapshot()`, instead of a narrowed
+ * webhook-only facade.
  */
-export interface CliPluginSdk {
-  /**
-   * Returns the SDK extension bag contributed by the plugin with the given id,
-   * when the host is backed by a full `KanbanSDK` instance.
-   *
-   * CLI plugins should prefer this extension path when available and fall back
-   * to compatibility methods only when running against older or mocked SDK facades.
-   */
-  getExtension?<T extends Record<string, unknown> = Record<string, unknown>>(id: string): T | undefined
-  listWebhooks(): Webhook[]
-  createWebhook(input: { url: string; events: string[]; secret?: string }): Promise<Webhook>
-  updateWebhook(
-    id: string,
-    updates: Partial<Pick<Webhook, 'url' | 'events' | 'secret' | 'active'>>,
-  ): Promise<Webhook | null>
-  deleteWebhook(id: string): Promise<boolean>
-}
+export type CliPluginSdk = KanbanSDK
 
 /**
  * Runtime context supplied to a {@link KanbanCliPlugin} when it is invoked by
@@ -649,10 +634,12 @@ export interface CliPluginContext {
    *
    * Present when the plugin is invoked through the core `kl` CLI.
    * Absent in isolated unit tests or standalone invocations.
-   * Plugins should prefer this over constructing their own SDK so that
-   * SDK-level auth policy is honoured.
+   * Plugins may use the full public {@link KanbanSDK} contract here, including
+   * extension lookup and `getConfigSnapshot()`, instead of relying on older
+   * helper-only SDK facades. Plugins should prefer this over constructing their
+   * own SDK so that SDK-level auth policy is honoured.
    */
-  sdk?: CliPluginSdk
+  sdk?: KanbanSDK
   /**
    * Core-owned CLI auth helper.
    *

package/src/sdk/webhooks.ts

@@ -32,10 +32,15 @@ import type { SDKEventType } from './types'
 export function fireWebhooks(workspaceRoot: string, event: SDKEventType, data: unknown): void {
   const config = readConfig(workspaceRoot)
   const webhooks = config.webhooks || []
+  console.log(`[kanban-lite/webhooks] fireWebhooks: event=${event} | total=${webhooks.length} registered`)
   const matching = webhooks.filter(
     w => w.active && (w.events.includes('*') || w.events.includes(event))
   )
-  if (matching.length === 0) return
+  if (matching.length === 0) {
+    console.log(`[kanban-lite/webhooks] no matching webhooks for event=${event} (${webhooks.filter(w => !w.active).length} inactive)`)
+    return
+  }
+  console.log(`[kanban-lite/webhooks] firing ${matching.length} webhook(s) for event=${event}: ${matching.map(w => w.id).join(', ')}`)
 
   const payload = JSON.stringify({
     event,
@@ -73,6 +78,7 @@ async function deliverWebhook(webhook: Webhook, event: string, payload: string):
     'X-Webhook-Event': event
   }
 
+  const hasSecret = !!webhook.secret
   if (webhook.secret) {
     const signature = crypto
       .createHmac('sha256', webhook.secret)
@@ -81,6 +87,10 @@ async function deliverWebhook(webhook: Webhook, event: string, payload: string):
     headers['X-Webhook-Signature'] = `sha256=${signature}`
   }
 
+  console.log(
+    `[kanban-lite/webhooks] → POST ${webhook.url} | event=${event} | id=${webhook.id} | secret=${hasSecret ? 'yes' : 'no'} | payloadBytes=${Buffer.byteLength(payload)}`,
+  )
+
   return new Promise((resolve, reject) => {
     const req = transport.request(
       {
@@ -92,6 +102,9 @@ async function deliverWebhook(webhook: Webhook, event: string, payload: string):
         timeout: 10000
       },
       (res) => {
+        console.log(
+          `[kanban-lite/webhooks] ← ${res.statusCode} ${res.statusMessage ?? ''} | id=${webhook.id} | url=${webhook.url}`,
+        )
         res.resume() // drain response
         if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
           resolve()
@@ -100,8 +113,12 @@ async function deliverWebhook(webhook: Webhook, event: string, payload: string):
         }
       }
     )
-    req.on('error', reject)
+    req.on('error', (err) => {
+      console.error(`[kanban-lite/webhooks] request error | id=${webhook.id} | url=${webhook.url}:`, err.message)
+      reject(err)
+    })
     req.on('timeout', () => {
+      console.error(`[kanban-lite/webhooks] timeout | id=${webhook.id} | url=${webhook.url}`)
       req.destroy()
       reject(new Error('Timeout'))
     })

package/src/shared/config.ts

@@ -191,7 +191,10 @@ export interface KanbanConfig {
   webhooks?: Webhook[]
   /** Label definitions keyed by label name, with color and optional group. */
   labels?: Record<string, LabelDefinition>
-  /** Optional URL to POST to when a card action is triggered. */
+  /**
+   * @deprecated Removed in favour of the webhook plugin. Register a webhook
+   * for the `card.action.triggered` event instead.
+   */
   actionWebhookUrl?: string
   /**
    * Global auto-increment card ID counter shared across all boards.
@@ -271,6 +274,13 @@ export interface KanbanConfig {
   customHeadHtml?: string
   /** Path to an HTML file (relative to workspace root) whose content is injected into the standalone board's `<head>` element. Takes precedence over `customHeadHtml`. */
   customHeadHtmlFile?: string
+  /**
+   * Optional URL base path prefix for subfolder reverse-proxy deployments
+   * (e.g. `'/kanban'`). Must start with `/` and have no trailing slash.
+   * When set, all asset URLs, the WebSocket endpoint, and API routes are
+   * served under this prefix. Only applies to the standalone server.
+   */
+  basePath?: string
 }
 
 // Legacy v1 config (for migration)
@@ -419,11 +429,105 @@ function migrateConfigV1ToV2(raw: Record<string, unknown>): KanbanConfig {
   return v2
 }
 
+/**
+ * Loads key–value pairs from a `.env` file in the given directory into
+ * `process.env`. Existing environment variables are never overwritten so that
+ * real OS-level values always take precedence over file-based defaults.
+ * Silently does nothing if the file does not exist.
+ *
+ * @param dir - Directory that may contain a `.env` file.
+ */
+function loadDotEnv(dir: string): void {
+  const envPath = path.join(dir, '.env')
+  let content: string
+  try {
+    content = fs.readFileSync(envPath, 'utf-8')
+  } catch {
+    return
+  }
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim()
+    if (!trimmed || trimmed.startsWith('#')) continue
+    const eqIdx = trimmed.indexOf('=')
+    if (eqIdx < 1) continue
+    const key = trimmed.slice(0, eqIdx).trim()
+    let val = trimmed.slice(eqIdx + 1).trim()
+    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+      val = val.slice(1, -1)
+    }
+    if (process.env[key] === undefined) {
+      process.env[key] = val
+    }
+  }
+}
+
+/**
+ * Recursively resolves `${VAR_NAME}` placeholders in all string values of a
+ * parsed config object against `process.env`. Mutates the object in place.
+ *
+ * Throws a descriptive error when a referenced environment variable is not
+ * set, including the JSON path to the offending value so the operator can
+ * locate it quickly. Example error message:
+ *
+ * ```
+ * missing ALICE_PASSWORD_HASH in .kanban.json: .plugins."auth.identity".options.users[3].password "${ALICE_PASSWORD_HASH}"
+ * ```
+ *
+ * Keys that contain non-identifier characters (e.g. dots) are quoted in the
+ * path segment, matching the convention used in `.kanban.json` error messages.
+ *
+ * @param node - The current node to process (object, array, string, or scalar).
+ * @param configFileName - Config filename used in error messages (e.g. `'.kanban.json'`).
+ * @param nodePath - JSON path accumulated so far (empty string at root).
+ * @returns The processed node (same reference for objects/arrays; new primitive for strings).
+ */
+function resolveConfigEnvVars(node: unknown, configFileName: string, nodePath = ''): unknown {
+  const isFormDefaultDataPath = /^\.forms\.(?:[^.]+|"[^"]+")\.data(?:$|[.\[])/.test(nodePath)
+
+  if (isFormDefaultDataPath) {
+    return node
+  }
+
+  if (typeof node === 'string') {
+    return node.replace(/\$\{([^}]+)\}/g, (_match, varName: string) => {
+      const envValue = process.env[varName]
+      if (envValue === undefined) {
+        throw new Error(
+          `missing ${varName} in ${configFileName}: ${nodePath} "${node}"`
+        )
+      }
+      return envValue
+    })
+  }
+  if (Array.isArray(node)) {
+    for (let i = 0; i < node.length; i++) {
+      node[i] = resolveConfigEnvVars(node[i], configFileName, `${nodePath}[${i}]`)
+    }
+    return node
+  }
+  if (node !== null && typeof node === 'object') {
+    const obj = node as Record<string, unknown>
+    for (const key of Object.keys(obj)) {
+      const jsonKey = /[^a-zA-Z0-9_]/.test(key) ? `"${key}"` : key
+      const childPath = nodePath ? `${nodePath}.${jsonKey}` : `.${jsonKey}`
+      obj[key] = resolveConfigEnvVars(obj[key], configFileName, childPath)
+    }
+    return obj
+  }
+  return node
+}
+
 /**
  * Reads the kanban config from disk. If the file is missing or unreadable,
  * returns the default config. If the file contains a v1 config, it is
  * automatically migrated to v2 format and persisted back to disk.
  *
+ * Any `${VAR_NAME}` placeholders found in string values are resolved against
+ * `process.env` before the config is returned. If a referenced environment
+ * variable is not set the process will throw a descriptive error rather than
+ * silently falling back to defaults, because an unresolved secret is never a
+ * safe default.
+ *
  * @param workspaceRoot - Absolute path to the workspace root directory.
  * @returns The parsed (and possibly migrated) kanban configuration.
  *
@@ -434,8 +538,32 @@ function migrateConfigV1ToV2(raw: Record<string, unknown>): KanbanConfig {
 export function readConfig(workspaceRoot: string): KanbanConfig {
   const filePath = configPath(workspaceRoot)
   const defaults = { ...DEFAULT_CONFIG, boards: { default: { ...DEFAULT_BOARD_CONFIG, columns: [...DEFAULT_COLUMNS] } } }
+
+  // Parse the file first; fall back to defaults only for read/parse failures.
+  let raw: Record<string, unknown>
+  try {
+    raw = JSON.parse(fs.readFileSync(filePath, 'utf-8'))
+  } catch {
+    return defaults
+  }
+
+  // Load .env from workspace root before resolving placeholders so that
+  // variables defined there are available without requiring the operator to
+  // export them in their shell.
+  loadDotEnv(workspaceRoot)
+
+  // Resolve ${VAR_NAME} env placeholders. A missing env variable is a known,
+  // operator-caused misconfiguration and should produce a clean, actionable
+  // error rather than a Node.js stack trace.
+  try {
+    resolveConfigEnvVars(raw, CONFIG_FILENAME)
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    process.stderr.write(`\nConfiguration error: ${msg}\n\nSet the missing environment variable before starting the server.\n\n`)
+    process.exit(1)
+  }
+
   try {
-    const raw = JSON.parse(fs.readFileSync(filePath, 'utf-8'))
     // True v1: explicitly version 1, OR version absent AND no boards object
     // A versionless modern config (has a boards object) must NOT be treated as v1
     const isV1 = raw.version === 1 || (!raw.version && !(typeof raw.boards === 'object' && raw.boards !== null && !Array.isArray(raw.boards)))

package/src/standalone/__tests__/server.integration.test.ts

@@ -350,6 +350,86 @@ describe('Standalone Server Integration', () => {
       }
     })
 
+    it('passes the resolved public SDK to standalone plugin registration and request contexts', async () => {
+      const cleanup = installTempPackage(
+        'standalone-sdk-context-test-plugin',
+        `module.exports = {
+  authIdentityPlugin: {
+    manifest: { id: 'standalone-sdk-context-test-plugin', provides: ['auth.identity'] },
+    async resolveIdentity() {
+      return { subject: 'standalone-sdk-context-test-plugin' }
+    },
+  },
+  standaloneHttpPlugin: {
+    manifest: { id: 'standalone-sdk-context-test-plugin', provides: ['standalone.http'] },
+    registerMiddleware() {
+      return [async (request) => {
+        if (!request.route('GET', '/api/plugin-sdk-context')) return false
+        request.mergeAuthContext({ actorHint: 'middleware-auth-context' })
+        return false
+      }]
+    },
+    registerRoutes(options) {
+      return [async (request) => {
+        if (!request.route('GET', '/api/plugin-sdk-context')) return false
+        const registrationSnapshot = options.sdk ? options.sdk.getConfigSnapshot() : null
+        const requestSnapshot = request.sdk.getConfigSnapshot()
+        const registrationBoard = options.sdk ? options.sdk.getBoard('default') : null
+        const requestBoard = request.sdk.getBoard('default')
+        request.res.statusCode = 200
+        request.res.setHeader('Content-Type', 'application/json')
+        request.res.end(JSON.stringify({
+          ok: true,
+          registrationSdkAvailable: !!options.sdk,
+          registrationPort: registrationSnapshot ? registrationSnapshot.port ?? null : null,
+          registrationBoardName: registrationBoard ? registrationBoard.name : null,
+          requestPort: requestSnapshot.port ?? null,
+          requestBoardName: requestBoard.name,
+          workspaceRootMatches: options.workspaceRoot === request.workspaceRoot,
+          kanbanDirMatches: options.kanbanDir === request.kanbanDir,
+          actorHint: request.getAuthContext().actorHint ?? null,
+        }))
+        return true
+      }]
+    },
+  },
+}
+`,
+      )
+
+      const workspaceRoot = path.dirname(tempDir)
+      const resolvedConfigPath = writeWorkspaceConfig(workspaceRoot, {
+        port,
+        auth: {
+          'auth.identity': { provider: 'standalone-sdk-context-test-plugin' },
+          'auth.policy': { provider: 'noop' },
+        },
+      })
+
+      const localPort = await getPort()
+      const localServer = startServer(tempDir, localPort, webviewDir, resolvedConfigPath)
+      await sleep(200)
+
+      try {
+        const res = await httpGet(`http://localhost:${localPort}/api/plugin-sdk-context`)
+        expect(res.status).toBe(200)
+        expect(JSON.parse(res.body)).toEqual({
+          ok: true,
+          registrationSdkAvailable: true,
+          registrationPort: port,
+          registrationBoardName: 'Default',
+          requestPort: port,
+          requestBoardName: 'Default',
+          workspaceRootMatches: true,
+          kanbanDirMatches: true,
+          actorHint: 'middleware-auth-context',
+        })
+      } finally {
+        cleanup()
+        await new Promise<void>((resolve) => localServer.close(() => resolve()))
+      }
+    })
+
     it('starts even when the Swagger UI package logo file is unavailable', async () => {
       vi.resetModules()
 
@@ -2561,7 +2641,7 @@ describe('Standalone Server Integration', () => {
       const kanbanJson = path.join(path.dirname(tempDir), '.kanban.json')
       fs.writeFileSync(kanbanJson, JSON.stringify({
         version: 2,
-        boards: { default: { name: 'Default', columns: [], nextCardId: 1, defaultStatus: 'backlog', defaultPriority: 'medium' } },
+        boards: { default: { name: 'Default', columns: [{ id: 'backlog', name: 'Backlog' }], nextCardId: 1, defaultStatus: 'backlog', defaultPriority: 'medium' } },
         defaultBoard: 'default',
         kanbanDirectory: '.kanban',
         forms: {
@@ -2585,7 +2665,6 @@ describe('Standalone Server Integration', () => {
         }
       }, null, 2), 'utf-8')
 
-
       const createRes = await httpRequest('POST', `http://localhost:${port}/api/tasks`, {
         content: '# Interpolation Regression Card',
         status: 'backlog',

package/src/standalone/internal/runtime.ts

@@ -6,20 +6,25 @@ import { KanbanSDK } from '../../sdk/KanbanSDK'
 import type { StandaloneContext } from '../context'
 import { broadcastLogsUpdatedToEditingClients, getClientsEditingCard } from '../broadcastService'
 
-export const indexHtml = `<!DOCTYPE html>
+export function getIndexHtml(basePath = ''): string {
+  return `<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <link rel="icon" type="image/svg+xml" href="/favicon.svg">
-  <link href="/style.css" rel="stylesheet">
+  <link rel="icon" type="image/svg+xml" href="${basePath}/favicon.svg">
+  <link href="${basePath}/style.css" rel="stylesheet">
   <title>Kanban Board</title>
+  <script>window.__KB_BASE__ = ${JSON.stringify(basePath)}<\/script>
 </head>
 <body>
   <div id="root"></div>
-  <script type="module" src="/index.js"></script>
+  <script type="module" src="${basePath}/index.js"><\/script>
 </body>
 </html>`
+}
+
+export const indexHtml = getIndexHtml()
 
 export interface StandaloneRuntime {
   absoluteKanbanDir: string
@@ -46,13 +51,13 @@ function resolveStandaloneWebviewDir(webviewDir?: string): string {
   return candidates[0]
 }
 
-export function createStandaloneRuntime(kanbanDir: string, webviewDir?: string, httpServer?: http.Server): StandaloneRuntime {
+export function createStandaloneRuntime(kanbanDir: string, webviewDir?: string, httpServer?: http.Server, basePath?: string): StandaloneRuntime {
   const absoluteKanbanDir = path.resolve(kanbanDir)
   const workspaceRoot = path.dirname(absoluteKanbanDir)
   const resolvedWebviewDir = resolveStandaloneWebviewDir(webviewDir)
 
   const server = httpServer ?? http.createServer()
-  const wss = new WebSocketServer({ server, path: '/ws' })
+  const wss = new WebSocketServer({ server, path: (basePath || '') + '/ws' })
 
   const ctx = {} as StandaloneContext
   const sdk = new KanbanSDK(absoluteKanbanDir, {

package/src/standalone/internal/websocket.ts

@@ -1,11 +1,21 @@
+import * as http from 'http'
 import { extractAuthContext, getAuthErrorLike } from '../authUtils'
+import type { AuthContext } from '../../sdk/types'
 import type { StandaloneContext } from '../context'
 import { clearClientEditingCard, setClientEditingCard } from '../broadcastService'
 import { handleMessage } from '../messageHandlers'
 
-export function attachWebSocketHandlers(ctx: StandaloneContext): void {
-  ctx.wss.on('connection', (ws, req) => {
-    const authContext = extractAuthContext(req)
+export function attachWebSocketHandlers(
+  ctx: StandaloneContext,
+  resolveAuthContext?: (req: http.IncomingMessage) => Promise<AuthContext>,
+): void {
+  ctx.wss.on('connection', async (ws, req) => {
+    let authContext: AuthContext
+    try {
+      authContext = resolveAuthContext ? await resolveAuthContext(req) : extractAuthContext(req)
+    } catch {
+      authContext = extractAuthContext(req)
+    }
     setClientEditingCard(ctx, ws, null)
     ws.on('message', (data) => {
       let message: unknown