@astrale-os/shell 0.1.0

package/src/application/shell.ts

@@ -0,0 +1,433 @@
+import type { FunctionSchema } from '@astrale-os/kernel-client'
+
+import type { IntentMiddleware } from '../domain/intent/pipeline'
+import type { IntentRegistry } from '../domain/message/registries'
+import type { WindowCapabilities, SandboxProfile } from '../domain/window/config'
+import type { Window } from '../domain/window/window'
+import type { KernelClient } from '../ports/kernel-client'
+import type { ShellAdapter } from '../ports/shell-adapter'
+import type { ChildrenChannel, ChildrenChannelController } from './channels/children-channel'
+import type { MessageObserver, ObserverHandler } from './channels/observer'
+import type { ParentChannel, ParentChannelController } from './channels/parent-channel'
+import type { IntentPipeline } from './intent/pipeline-runner'
+import type { LocalIntentHandler } from './intent/router'
+import type { KernelFacadeController } from './kernel-facade'
+import type { LifecycleController } from './windowing/lifecycle-controller'
+import type { MountController } from './windowing/mount-controller'
+
+import { createKernelClientAdapter } from '../adapters/kernel-client.adapter'
+import { createChildrenChannel } from './channels/children-channel'
+import { createMessageObserver } from './channels/observer'
+import { createIntentPipeline } from './intent/pipeline-runner'
+import { createIntentRouter } from './intent/router'
+import { createKernelFacade } from './kernel-facade'
+import { performChildInit } from './windowing/child-init'
+import { createLifecycleController } from './windowing/lifecycle-controller'
+import { createMountController } from './windowing/mount-controller'
+
+// ─── Re-exports ─────────────────────────────────────────────────────────────
+
+export type { MessageDirection, ObserverHandler } from './channels/observer'
+export type { ParentChannel } from './channels/parent-channel'
+export type { ChildrenChannel } from './channels/children-channel'
+export type { MessageHandler } from './channels/types'
+
+// ─── Mount API ──────────────────────────────────────────────────────────────
+
+export type MountParams = {
+  readonly host: HTMLElement
+  readonly url: string
+  readonly functionId: string
+  readonly capabilities: WindowCapabilities
+  readonly targetNodeId?: string
+  /** See `WindowConfig.sandbox` — `null` opts the iframe out of the attribute. */
+  readonly sandbox?: SandboxProfile | null
+  readonly handshakeTimeoutMs?: number
+  readonly delegationTtlSeconds?: number
+  /**
+   * `'shell'` (default) runs the parent-side handshake, opening a MessagePort
+   * transport with delegation tokens and an intent channel. `'none'` mounts a
+   * plain iframe with no transport — used for hosted views that don't speak
+   * the shell protocol (`BlaxelComputer.deployFunction(kind:'view')`), so they
+   * render immediately instead of paying the 5 s handshake timeout. In `'none'`
+   * mode `capabilities` / `targetNodeId` / `delegationTtlSeconds` are inert
+   * (no channel to deliver them).
+   */
+  readonly handshake?: 'shell' | 'none'
+}
+
+export type CloseResult =
+  | { kind: 'closed' }
+  | { kind: 'refused'; reason?: string }
+  | { kind: 'noop' }
+
+export type MountedWindow = {
+  readonly windowId: string
+  readonly window: Window
+  readonly handle: { element: HTMLIFrameElement | HTMLElement }
+  close(opts?: { force?: boolean; timeoutMs?: number }): Promise<CloseResult>
+}
+
+// ─── Shell ──────────────────────────────────────────────────────────────────
+
+export interface Shell {
+  readonly parent: ParentChannel | null
+  readonly children: ChildrenChannel
+  readonly kernel: KernelClient
+  readonly windows: ReadonlyMap<string, Window>
+  readonly targetNodeId?: string
+
+  use(middleware: IntentMiddleware): Shell
+  onMessage(handler: ObserverHandler): () => void
+  onIntent<K extends keyof IntentRegistry>(name: K, handler: LocalIntentHandler<K>): () => void
+
+  mount(params: MountParams): Promise<MountedWindow>
+  close(windowId: string, opts?: { force?: boolean; timeoutMs?: number }): Promise<CloseResult>
+
+  init(): Promise<Shell>
+  dispose(): Promise<void>
+}
+
+// ─── Config ─────────────────────────────────────────────────────────────────
+
+export type StandaloneConfig = {
+  readonly mode: 'standalone'
+  readonly kernelUrl: string
+  readonly credential?: string
+  readonly getCredential?: () => string
+  readonly mintIdentity?: string
+  readonly schema?: FunctionSchema[]
+  readonly adapter?: ShellAdapter
+  readonly windowId?: string
+  /**
+   * Optional wire-layer `fetch` shim for the kernel transport. A cookie-fronted
+   * SPA passes a wrapper adding `credentials:'include'` + refresh-on-401 and an
+   * empty `credential`, so a router unseals the cookie into a Bearer (the SPA
+   * holds no token). Omit it (the default) for token-based callers — including
+   * every sandboxed child view, which authenticates with a delegation token.
+   */
+  readonly fetch?: typeof fetch
+}
+
+export type SandboxedConfig = {
+  readonly mode: 'sandboxed'
+  readonly schema?: FunctionSchema[]
+  readonly parentWindow?: WindowProxy
+  readonly initTimeoutMs?: number
+  readonly adapter?: ShellAdapter
+}
+
+export type ShellConfig = StandaloneConfig | SandboxedConfig
+
+const DEFAULT_ROOT_WINDOW_ID = 'root'
+/** Trusted sender id stamped on intents arriving from the parent channel. */
+const PARENT_SENDER_ID = '<parent>'
+
+// ─── Factory ────────────────────────────────────────────────────────────────
+
+export function createShell(config: ShellConfig): Shell {
+  return config.mode === 'standalone' ? createStandaloneShell(config) : createSandboxedShell(config)
+}
+
+// ─── Standalone ─────────────────────────────────────────────────────────────
+
+function createStandaloneShell(config: StandaloneConfig): Shell {
+  const windowId = config.windowId ?? DEFAULT_ROOT_WINDOW_ID
+  const observer = createMessageObserver()
+  const getCredential =
+    config.getCredential ??
+    (() => {
+      if (config.credential === undefined) {
+        throw new Error('Standalone shell requires credential or getCredential')
+      }
+      return config.credential
+    })
+  const adapter = createKernelClientAdapter({
+    url: config.kernelUrl,
+    schema: config.schema,
+    getCredential,
+    mintIdentity: config.mintIdentity,
+    fetch: config.fetch,
+  })
+  const kernel = createKernelFacade({
+    adapter,
+    getCredential,
+    url: config.kernelUrl,
+    mintIdentity: config.mintIdentity,
+  })
+
+  const lifecycle = createLifecycleController()
+  const windows = new Map<string, Window>()
+
+  const childrenChannel = createChildrenChannel({
+    observer,
+    onDeliveryFailed: (toWindowId) => lifecycle.markCrashed(toWindowId),
+  })
+
+  const pipeline = createIntentPipeline()
+  const router = createIntentRouter({
+    selfWindowId: windowId,
+    pipeline,
+    parent: null,
+    children: childrenChannel,
+    windows,
+  })
+
+  childrenChannel.on('intent', (windowId, message) => {
+    void router.handleInbound('child', message, windowId)
+  })
+
+  let mountController: MountController | null = null
+  function getMountController(): MountController {
+    if (mountController) return mountController
+    if (!config.adapter) {
+      throw new Error('Shell.mount() requires a ShellAdapter in the config')
+    }
+    mountController = createMountController({
+      adapter: config.adapter,
+      kernel,
+      kernelUrl: config.kernelUrl,
+      mintIdentity: config.mintIdentity,
+      childrenChannel,
+      windows,
+      lifecycle,
+    })
+    return mountController
+  }
+
+  return buildShellFacade({
+    parent: null,
+    childrenChannel,
+    kernel,
+    pipeline,
+    observer,
+    lifecycle,
+    windows,
+    getMountController,
+    onIntent: (name, handler) => router.onLocal(name, handler),
+    onDispose: async () => {
+      if (mountController) await mountController.dispose()
+      childrenChannel.dispose()
+      adapter.disconnect()
+    },
+  })
+}
+
+// ─── Sandboxed child ────────────────────────────────────────────────────────
+
+type SandboxedState = {
+  windowId: string
+  kernelUrl: string
+  targetNodeId?: string
+  mintIdentity?: string
+  kernel: KernelFacadeController
+  parent: ParentChannelController
+}
+
+function createSandboxedShell(config: SandboxedConfig): Shell {
+  const observer = createMessageObserver()
+  const lifecycle = createLifecycleController()
+  const windows = new Map<string, Window>()
+  const childrenChannel = createChildrenChannel({
+    observer,
+    onDeliveryFailed: (toWindowId) => lifecycle.markCrashed(toWindowId),
+  })
+  const pipeline = createIntentPipeline()
+
+  let state: SandboxedState | null = null
+  let router: ReturnType<typeof createIntentRouter> | null = null
+  let mountController: MountController | null = null
+
+  // Buffer intent subscriptions made before `init()` resolves — the router
+  // is only built once the handshake completes, but consumers want to call
+  // `onIntent` at construction time.
+  type PendingIntentSub = {
+    name: string
+    handler: LocalIntentHandler
+    unsubscribed: boolean
+    off?: () => void
+  }
+  const pendingIntentSubs: PendingIntentSub[] = []
+
+  function subscribeIntent<K extends keyof IntentRegistry>(
+    name: K,
+    handler: LocalIntentHandler<K>,
+  ): () => void {
+    if (router) return router.onLocal(name, handler)
+    const entry: PendingIntentSub = {
+      name: name as string,
+      handler: handler as LocalIntentHandler,
+      unsubscribed: false,
+    }
+    pendingIntentSubs.push(entry)
+    return () => {
+      entry.unsubscribed = true
+      // After init, `off` is the router's real disposer (set during replay);
+      // before init, flipping `unsubscribed` is enough (replay skips it).
+      entry.off?.()
+    }
+  }
+
+  const requireState = (): SandboxedState => {
+    if (!state) throw new Error('Sandboxed shell not initialized — call shell.init() first')
+    return state
+  }
+
+  const kernelProxy: KernelClient = {
+    call: (path, params) => requireState().kernel.call(path, params),
+    mintDelegation: () => requireState().kernel.mintDelegation(),
+    authToken: () => requireState().kernel.authToken(),
+    get url() {
+      return requireState().kernel.url
+    },
+  }
+
+  const parentProxy: ParentChannel = {
+    send: (message) => requireState().parent.send(message),
+    on: (type, handler) => requireState().parent.on(type, handler),
+  }
+
+  function getMountController(): MountController {
+    if (mountController) return mountController
+    if (!config.adapter) {
+      throw new Error('Shell.mount() requires a ShellAdapter in the config')
+    }
+    const current = requireState()
+    mountController = createMountController({
+      adapter: config.adapter,
+      kernel: kernelProxy,
+      kernelUrl: current.kernelUrl,
+      mintIdentity: current.mintIdentity,
+      childrenChannel,
+      windows,
+      lifecycle,
+    })
+    return mountController
+  }
+
+  return buildShellFacade({
+    parent: parentProxy,
+    childrenChannel,
+    kernel: kernelProxy,
+    pipeline,
+    observer,
+    lifecycle,
+    windows,
+    getMountController,
+    targetNodeId: () => state?.targetNodeId,
+    onIntent: subscribeIntent,
+    init: async () => {
+      const result = await performChildInit({
+        parent: config.parentWindow ?? window.parent,
+        timeoutMs: config.initTimeoutMs,
+        schema: config.schema,
+      })
+
+      state = {
+        windowId: result.windowId,
+        kernelUrl: result.kernelUrl,
+        targetNodeId: result.targetNodeId,
+        mintIdentity: result.mintIdentity,
+        kernel: result.kernel,
+        parent: result.parentChannel(observer),
+      }
+
+      router = createIntentRouter({
+        selfWindowId: state.windowId,
+        pipeline,
+        parent: state.parent,
+        children: childrenChannel,
+        windows,
+      })
+
+      childrenChannel.on('intent', (windowId, message) => {
+        void router!.handleInbound('child', message, windowId)
+      })
+      state.parent.on('intent', (message) => {
+        void router!.handleInbound('parent', message, PARENT_SENDER_ID)
+      })
+
+      // Replay subscriptions registered before init. Capture each real disposer
+      // so a post-init unsubscribe (via the closure returned at subscribe time)
+      // actually removes the handler from the router instead of no-op'ing.
+      for (const entry of pendingIntentSubs) {
+        if (entry.unsubscribed) continue
+        entry.off = router.onLocal(entry.name as keyof IntentRegistry, entry.handler)
+      }
+      pendingIntentSubs.length = 0
+    },
+    onDispose: async () => {
+      if (mountController) await mountController.dispose()
+      childrenChannel.dispose()
+      state?.parent.dispose()
+      state?.kernel.dispose()
+    },
+  })
+}
+
+// ─── Shared facade builder ──────────────────────────────────────────────────
+
+type FacadeDeps = {
+  parent: ParentChannel | null
+  childrenChannel: ChildrenChannelController
+  kernel: KernelClient
+  pipeline: IntentPipeline
+  observer: MessageObserver
+  lifecycle: LifecycleController
+  windows: Map<string, Window>
+  getMountController: () => MountController
+  onIntent: <K extends keyof IntentRegistry>(name: K, handler: LocalIntentHandler<K>) => () => void
+  targetNodeId?: () => string | undefined
+  init?: () => Promise<void>
+  onDispose: () => Promise<void>
+}
+
+function buildShellFacade(deps: FacadeDeps): Shell {
+  let disposed = false
+
+  const shell: Shell = {
+    get parent() {
+      return deps.parent
+    },
+    children: deps.childrenChannel,
+    kernel: deps.kernel,
+    windows: deps.windows,
+    get targetNodeId() {
+      return deps.targetNodeId?.()
+    },
+
+    use(middleware) {
+      deps.pipeline.use(middleware)
+      return shell
+    },
+
+    onMessage(handler) {
+      return deps.observer.subscribe(handler)
+    },
+
+    onIntent(name, handler) {
+      return deps.onIntent(name, handler)
+    },
+
+    mount(params) {
+      return deps.getMountController().mount(params)
+    },
+
+    close(windowId, opts) {
+      return deps.getMountController().close(windowId, opts)
+    },
+
+    async init() {
+      if (deps.init) await deps.init()
+      return shell
+    },
+
+    async dispose() {
+      if (disposed) return
+      disposed = true
+      await deps.onDispose()
+    },
+  }
+
+  return shell
+}

package/src/application/windowing/child-init.ts

@@ -0,0 +1,137 @@
+import type { FunctionSchema } from '@astrale-os/kernel-client'
+
+import type { DelegationToken } from '../../domain/identity/delegation'
+import type { CtrlMessage } from '../../domain/message/types'
+import type { MessageObserver } from '../channels/observer'
+import type { ParentChannelController } from '../channels/parent-channel'
+
+import { createKernelClientAdapter } from '../../adapters/kernel-client.adapter'
+import { createMessagePortTransport } from '../../adapters/message-port.transport'
+import { createParentChannel } from '../channels/parent-channel'
+import {
+  createDelegationKernelFacade,
+  type DelegationKernelFacadeController,
+} from '../kernel-facade'
+import { INIT_REQUEST_TYPE, isInitResponse } from './protocol'
+
+export type ChildInitParams = {
+  readonly parent: WindowProxy
+  readonly timeoutMs?: number
+  readonly schema?: FunctionSchema[]
+}
+
+export type ChildInitResult = {
+  readonly windowId: string
+  readonly parentChannel: (observer: MessageObserver) => ParentChannelController
+  readonly kernel: DelegationKernelFacadeController
+  readonly initialToken: DelegationToken
+  readonly functionId: string
+  readonly kernelUrl: string
+  readonly targetNodeId?: string
+  readonly mintIdentity?: string
+}
+
+const DEFAULT_TIMEOUT = 5_000
+
+/** Child-side init: post INIT_REQUEST, receive MessagePort + ctrl:handshake, ack. */
+export function performChildInit(params: ChildInitParams): Promise<ChildInitResult> {
+  const { parent } = params
+  const timeoutMs = params.timeoutMs ?? DEFAULT_TIMEOUT
+
+  return new Promise((resolve, reject) => {
+    let port: MessagePort | null = null
+
+    const timer = setTimeout(() => {
+      cleanup()
+      reject(new Error(`Shell child init timed out after ${timeoutMs}ms`))
+    }, timeoutMs)
+
+    function cleanup() {
+      clearTimeout(timer)
+      window.removeEventListener('message', onWindowMessage)
+      if (port) port.onmessage = null
+    }
+
+    function onHandshake(handshakePort: MessagePort) {
+      return (ev: MessageEvent) => {
+        const msg = ev.data
+        if (!msg || msg.type !== 'ctrl' || (msg as CtrlMessage).action !== 'handshake') return
+
+        const data = (msg as CtrlMessage<'handshake'>).data
+        handshakePort.postMessage({
+          type: 'ctrl',
+          version: 1,
+          action: 'handshakeAck',
+          data: { windowId: data.windowId },
+        } satisfies CtrlMessage<'handshakeAck'>)
+        cleanup()
+
+        const initialToken: DelegationToken = {
+          credential: data.delegationToken,
+          scope: { functionId: data.functionId },
+          issuedAt: Date.now(),
+          expiresAt: data.tokenExpiresAt,
+        }
+
+        let currentToken: DelegationToken = initialToken
+        const adapter = createKernelClientAdapter({
+          url: data.kernelUrl,
+          schema: params.schema,
+          getCredential: () => currentToken.credential,
+          mintIdentity: data.mintIdentity,
+        })
+        const kernel = createDelegationKernelFacade({
+          adapter,
+          initialToken,
+          url: data.kernelUrl,
+          mintIdentity: data.mintIdentity,
+          onTokenChange: (next) => {
+            currentToken = next
+          },
+        })
+
+        resolve({
+          windowId: data.windowId,
+          functionId: data.functionId,
+          kernelUrl: data.kernelUrl,
+          targetNodeId: data.targetNodeId,
+          mintIdentity: data.mintIdentity,
+          initialToken,
+          kernel,
+          parentChannel: (observer) => {
+            const transport = createMessagePortTransport({ port: handshakePort })
+            const channel = createParentChannel({ transport, observer })
+
+            channel.on('ctrl', (message) => {
+              if (message.action !== 'tokenRefresh') return
+              const refresh = message as CtrlMessage<'tokenRefresh'>
+              kernel.setToken({
+                credential: refresh.data.delegationToken,
+                scope: { functionId: data.functionId },
+                issuedAt: Date.now(),
+                expiresAt: refresh.data.tokenExpiresAt,
+              })
+            })
+
+            return channel
+          },
+        })
+      }
+    }
+
+    function onWindowMessage(ev: MessageEvent) {
+      if (!isInitResponse(ev.data)) return
+      if (ev.source !== parent) return
+      const [receivedPort] = ev.ports
+      if (!receivedPort) return
+      port = receivedPort
+      port.onmessage = onHandshake(receivedPort)
+      port.start()
+    }
+
+    window.addEventListener('message', onWindowMessage)
+
+    // targetOrigin="*" — the parent verifies our event.origin on its side.
+    parent.postMessage({ type: INIT_REQUEST_TYPE, version: 1 }, '*')
+  })
+}

package/src/application/windowing/handshake.ts

@@ -0,0 +1,98 @@
+import type { CtrlMessage, ShellMessage } from '../../domain/message/types'
+
+import { INIT_RESPONSE_TYPE, isInitRequest } from './protocol'
+
+export type HandshakeParams = {
+  readonly iframe: HTMLIFrameElement
+  readonly expectedOrigin: string
+  readonly windowId: string
+  readonly delegationToken: string
+  readonly tokenExpiresAt: number
+  readonly kernelUrl: string
+  readonly functionId: string
+  readonly targetNodeId?: string
+  readonly mintIdentity?: string
+  readonly timeoutMs: number
+}
+
+export type HandshakeError =
+  | { code: 'HANDSHAKE_TIMEOUT'; message: string }
+  | { code: 'ORIGIN_MISMATCH'; message: string; actual: string; expected: string }
+  | { code: 'HANDSHAKE_FAILED'; message: string }
+
+export type HandshakeResult = {
+  readonly port: MessagePort
+}
+
+/** Parent-side handshake: wait for INIT_REQUEST, transfer a MessagePort, complete ctrl:handshake. */
+export function runParentHandshake(params: HandshakeParams): Promise<HandshakeResult> {
+  const { iframe, expectedOrigin, timeoutMs } = params
+
+  return new Promise((resolve, reject) => {
+    let port: MessagePort | null = null
+    const timer = setTimeout(() => {
+      cleanup()
+      reject({
+        code: 'HANDSHAKE_TIMEOUT',
+        message: `handshake timed out after ${timeoutMs}ms`,
+      } satisfies HandshakeError)
+    }, timeoutMs)
+
+    function cleanup() {
+      clearTimeout(timer)
+      window.removeEventListener('message', onInitRequest)
+      if (port) port.onmessage = null
+    }
+
+    function onInitRequest(event: MessageEvent) {
+      if (event.source !== iframe.contentWindow) return
+      if (!isInitRequest(event.data)) return
+
+      if (event.origin !== expectedOrigin) {
+        cleanup()
+        reject({
+          code: 'ORIGIN_MISMATCH',
+          message: `expected origin ${expectedOrigin}, got ${event.origin}`,
+          actual: event.origin,
+          expected: expectedOrigin,
+        } satisfies HandshakeError)
+        return
+      }
+
+      const channel = new MessageChannel()
+      port = channel.port1
+
+      port.onmessage = (ev: MessageEvent) => {
+        const msg = ev.data as ShellMessage
+        if (msg && msg.type === 'ctrl' && (msg as CtrlMessage).action === 'handshakeAck') {
+          cleanup()
+          resolve({ port: channel.port1 })
+        }
+      }
+
+      port.start()
+
+      iframe.contentWindow?.postMessage(
+        { type: INIT_RESPONSE_TYPE, version: 1 as const, windowId: params.windowId },
+        expectedOrigin,
+        [channel.port2],
+      )
+      port.postMessage({
+        type: 'ctrl',
+        version: 1,
+        action: 'handshake',
+        data: {
+          delegationToken: params.delegationToken,
+          tokenExpiresAt: params.tokenExpiresAt,
+          windowId: params.windowId,
+          kernelUrl: params.kernelUrl,
+          functionId: params.functionId,
+          targetNodeId: params.targetNodeId,
+          mintIdentity: params.mintIdentity,
+        },
+      } satisfies CtrlMessage<'handshake'>)
+    }
+
+    window.addEventListener('message', onInitRequest)
+  })
+}

package/src/application/windowing/lifecycle-controller.ts

@@ -0,0 +1,40 @@
+import type { WindowState } from '../../domain/window/window'
+
+import { transition, type LifecycleEvent } from '../../domain/window/lifecycle'
+
+export interface LifecycleController {
+  register(windowId: string, initial?: WindowState): void
+  apply(windowId: string, event: LifecycleEvent): WindowState | null
+  markCrashed(windowId: string): void
+  remove(windowId: string): void
+}
+
+export function createLifecycleController(): LifecycleController {
+  const states = new Map<string, WindowState>()
+
+  return {
+    register(windowId, initial = 'active') {
+      if (states.has(windowId)) return
+      states.set(windowId, initial)
+    },
+
+    apply(windowId, event) {
+      const prev = states.get(windowId)
+      if (prev === undefined) return null
+      const result = transition(prev, event)
+      if (!result.ok) return null
+      states.set(windowId, result.next)
+      return result.next
+    },
+
+    markCrashed(windowId) {
+      const prev = states.get(windowId)
+      if (prev === undefined || prev === 'closed') return
+      states.set(windowId, 'closed')
+    },
+
+    remove(windowId) {
+      states.delete(windowId)
+    },
+  }
+}