@astrale-os/shell 0.1.0

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

@@ -0,0 +1,335 @@
+import type { Window } from '../../domain/window/window'
+import type { KernelClient } from '../../ports/kernel-client'
+import type { ShellAdapter, WindowHandle } from '../../ports/shell-adapter'
+import type { ChildrenChannelController } from '../channels/children-channel'
+import type { MountParams, MountedWindow, CloseResult } from '../shell'
+import type { LifecycleController } from './lifecycle-controller'
+
+import { createMessagePortTransport } from '../../adapters/message-port.transport'
+import { runParentHandshake } from './handshake'
+import { createTokenRefresher, type TokenRefresher } from './token-refresh'
+
+const DEFAULT_HANDSHAKE_TIMEOUT = 5_000
+const DEFAULT_DELEGATION_TTL = 3_600
+const DEFAULT_CLOSE_TIMEOUT = 3_000
+const PARENT_SENDER_ID = '<parent>'
+
+export type MountControllerConfig = {
+  adapter: ShellAdapter
+  kernel: KernelClient
+  kernelUrl: string
+  mintIdentity?: string
+  childrenChannel: ChildrenChannelController
+  windows: Map<string, Window>
+  lifecycle: LifecycleController
+}
+
+export interface MountController {
+  mount(params: MountParams): Promise<MountedWindow>
+  close(windowId: string, opts?: { force?: boolean; timeoutMs?: number }): Promise<CloseResult>
+  dispose(): Promise<void>
+}
+
+type Entry = {
+  readonly handle: WindowHandle
+  readonly dispose: () => void
+  readonly refresher: TokenRefresher
+  /** Plain (no-handshake) mount: no transport, no token, no close ack. */
+  readonly plain?: boolean
+}
+
+/** No-op refresher for plain mounts (no token to refresh). */
+const NOOP_REFRESHER: TokenRefresher = {
+  start: () => {},
+  stop: () => {},
+  forceRefreshNow: () => Promise.resolve(),
+}
+
+export function createMountController(config: MountControllerConfig): MountController {
+  const { adapter, kernel, kernelUrl, mintIdentity, childrenChannel, windows, lifecycle } = config
+  // The child iframe is always a DIFFERENT origin from this parent window, so a
+  // relative kernelUrl (e.g. the SPA's same-origin `/api/`) handed across the
+  // handshake would resolve against the iframe's OWN origin and POST to the
+  // wrong host. Absolutize it against the parent's location once so every child
+  // calls THIS origin's kernel. (The parent's own calls keep using the relative
+  // form via its kernel client / fetch.)
+  const childKernelUrl = new URL(kernelUrl, window.location.href).href
+  const entries = new Map<string, Entry>()
+  let seq = 0
+  let disposed = false
+
+  function nextWindowId(functionId: string) {
+    seq += 1
+    const slug = functionId.replace(/[^a-z0-9]/gi, '').slice(-8) || 'fn'
+    return `win-${slug}-${seq}`
+  }
+
+  async function mint(ttlSeconds: number) {
+    const credential = await kernel.mintDelegation()
+    return { credential, expiresAt: Date.now() + ttlSeconds * 1_000 }
+  }
+
+  function originOf(url: string): string {
+    try {
+      return new URL(url, window.location.href).origin
+    } catch {
+      throw new Error(`Invalid mount url: ${url}`)
+    }
+  }
+
+  // Plain-iframe mount path — for hosted views that don't speak the shell
+  // protocol. No handshake, no transport, no delegation token, no refresher;
+  // the iframe just renders. `close()` skips the ack request (no channel) and
+  // falls straight to dispose.
+  async function mountPlain(params: MountParams): Promise<MountedWindow> {
+    const windowId = nextWindowId(params.functionId)
+    const { handle, dispose: disposeHandle } = adapter.mount({
+      functionId: params.functionId,
+      isolation: 'sandboxed',
+      capabilities: params.capabilities,
+      sandbox: params.sandbox,
+    })
+    if (!(handle.element instanceof HTMLIFrameElement)) {
+      disposeHandle()
+      throw new Error('Shell adapter did not produce an HTMLIFrameElement')
+    }
+    params.host.appendChild(handle.element)
+    handle.element.src = params.url
+
+    windows.set(windowId, {
+      windowId,
+      functionId: params.functionId,
+      targetNodeId: params.targetNodeId,
+      isolation: 'sandboxed',
+      state: 'active',
+      delegationToken: null,
+      capabilities: params.capabilities,
+    })
+    lifecycle.register(windowId, 'active')
+    entries.set(windowId, {
+      handle,
+      dispose: disposeHandle,
+      refresher: NOOP_REFRESHER,
+      plain: true,
+    })
+
+    return {
+      windowId,
+      get window() {
+        return windows.get(windowId)!
+      },
+      handle: { element: handle.element },
+      close: (opts) => controller.close(windowId, opts),
+    }
+  }
+
+  const controller: MountController = {
+    async mount(params) {
+      if (disposed) throw new Error('MountController is disposed')
+
+      // Plain (no-handshake) path: hosted views that don't speak the shell
+      // protocol. Skip mint/handshake/transport/refresher; the iframe still
+      // renders and `close()` falls through to dispose.
+      if (params.handshake === 'none') return mountPlain(params)
+
+      const ttlSeconds = params.delegationTtlSeconds ?? DEFAULT_DELEGATION_TTL
+      const handshakeTimeout = params.handshakeTimeoutMs ?? DEFAULT_HANDSHAKE_TIMEOUT
+      const expectedOrigin = originOf(params.url)
+      const windowId = nextWindowId(params.functionId)
+
+      // Mint the token and create the iframe in parallel — the iframe
+      // doesn't need the credential until the handshake fires.
+      const [{ credential, expiresAt }, mounted] = await Promise.all([
+        mint(ttlSeconds),
+        Promise.resolve(
+          adapter.mount({
+            functionId: params.functionId,
+            isolation: 'sandboxed',
+            capabilities: params.capabilities,
+            sandbox: params.sandbox,
+          }),
+        ),
+      ])
+      const { handle, dispose: disposeHandle } = mounted
+
+      if (!(handle.element instanceof HTMLIFrameElement)) {
+        disposeHandle()
+        throw new Error('Shell adapter did not produce an HTMLIFrameElement')
+      }
+
+      params.host.appendChild(handle.element)
+      handle.element.src = params.url
+
+      let handshakeResult
+      try {
+        handshakeResult = await runParentHandshake({
+          iframe: handle.element,
+          expectedOrigin,
+          windowId,
+          delegationToken: credential,
+          tokenExpiresAt: expiresAt,
+          kernelUrl: childKernelUrl,
+          functionId: params.functionId,
+          targetNodeId: params.targetNodeId,
+          mintIdentity,
+          timeoutMs: handshakeTimeout,
+        })
+      } catch (err) {
+        disposeHandle()
+        throw err
+      }
+
+      const transport = createMessagePortTransport({
+        port: handshakeResult.port,
+        onClose: () => {
+          if (!entries.has(windowId)) return
+          lifecycle.markCrashed(windowId)
+          void controller.close(windowId, { force: true }).catch(() => {})
+        },
+      })
+
+      childrenChannel.attach(windowId, transport)
+      windows.set(windowId, {
+        windowId,
+        functionId: params.functionId,
+        targetNodeId: params.targetNodeId,
+        isolation: 'sandboxed',
+        state: 'active',
+        delegationToken: credential,
+        capabilities: params.capabilities,
+      })
+      lifecycle.register(windowId, 'active')
+
+      // The live expiry advances on every refresh. The Window store only keeps
+      // the credential, so track expiry here — otherwise `token()` keeps
+      // returning the original expiry and `schedule()` collapses its lead time
+      // to 0, busy-looping `mint()` forever after the first refresh.
+      let currentExpiresAt = expiresAt
+      const refresher = createTokenRefresher({
+        functionId: params.functionId,
+        token: () => {
+          const stored = windows.get(windowId)
+          return {
+            credential: stored?.delegationToken ?? credential,
+            expiresAt: currentExpiresAt,
+            issuedAt: 0,
+            scope: { functionId: params.functionId },
+          }
+        },
+        setToken: (next) => {
+          currentExpiresAt = next.expiresAt
+          const stored = windows.get(windowId)
+          if (stored) {
+            windows.set(windowId, { ...stored, delegationToken: next.credential })
+          }
+          childrenChannel.send(windowId, {
+            type: 'ctrl',
+            version: 1,
+            action: 'tokenRefresh',
+            data: { delegationToken: next.credential, tokenExpiresAt: next.expiresAt },
+          })
+        },
+        mint: () => mint(ttlSeconds),
+        onFailure: () => {
+          void controller.close(windowId, { force: false }).catch(() => {})
+        },
+      })
+      refresher.start()
+
+      entries.set(windowId, { handle, dispose: disposeHandle, refresher })
+
+      return {
+        windowId,
+        get window() {
+          return windows.get(windowId)!
+        },
+        handle: { element: handle.element },
+        close: (opts) => controller.close(windowId, opts),
+      }
+    },
+
+    async close(windowId, opts) {
+      const entry = entries.get(windowId)
+      if (!entry) return { kind: 'noop' }
+
+      const timeoutMs = opts?.timeoutMs ?? DEFAULT_CLOSE_TIMEOUT
+
+      // Plain mounts have no channel to ack a close; always force.
+      if (!opts?.force && !entry.plain) {
+        // Move the window into `closing` so the state machine accepts the
+        // subsequent `closeRefuse`/`forceClose` transition (both are only valid
+        // from `closing`).
+        lifecycle.apply(windowId, { kind: 'requestClose' })
+        const accepted = await requestCloseAck(childrenChannel, windowId, timeoutMs)
+        if (accepted.kind === 'refused') {
+          lifecycle.apply(windowId, { kind: 'closeRefuse' })
+          return { kind: 'refused', reason: accepted.reason }
+        }
+      }
+
+      lifecycle.apply(windowId, { kind: 'forceClose' })
+      entry.refresher.stop()
+      // Drop the entry before detaching: `detach` synchronously closes the
+      // transport, whose `onClose` re-enters `close()`. Removing the entry first
+      // makes that re-entrant call's `entries.has(windowId)` guard short-circuit,
+      // so `entry.dispose()` runs exactly once (adapters need not be idempotent).
+      entries.delete(windowId)
+      childrenChannel.detach(windowId)
+      windows.delete(windowId)
+      entry.dispose()
+      lifecycle.remove(windowId)
+      return { kind: 'closed' }
+    },
+
+    async dispose() {
+      if (disposed) return
+      disposed = true
+      const ids = [...entries.keys()]
+      await Promise.all(ids.map((id) => controller.close(id, { force: true })))
+    },
+  }
+
+  return controller
+}
+
+type CloseAck = { kind: 'ack' } | { kind: 'refused'; reason?: string } | { kind: 'timeout' }
+
+async function requestCloseAck(
+  children: ChildrenChannelController,
+  windowId: string,
+  timeoutMs: number,
+): Promise<CloseAck> {
+  return new Promise((resolve) => {
+    let settled = false
+    const off = children.on('intent', (from, message) => {
+      if (from !== windowId) return
+      if (message.envelope.name === 'closeAck') {
+        settled = true
+        off()
+        clearTimeout(timer)
+        resolve({ kind: 'ack' })
+      } else if (message.envelope.name === 'closeRefuse') {
+        settled = true
+        off()
+        clearTimeout(timer)
+        const reason = (message.envelope.payload as { reason?: string }).reason
+        resolve({ kind: 'refused', reason })
+      }
+    })
+    const timer = setTimeout(() => {
+      if (settled) return
+      off()
+      resolve({ kind: 'timeout' })
+    }, timeoutMs)
+
+    children.send(windowId, {
+      type: 'intent',
+      version: 1,
+      envelope: {
+        name: 'willClose',
+        payload: {},
+        sender: { windowId: PARENT_SENDER_ID },
+      },
+    })
+  })
+}

package/src/application/windowing/protocol.ts

@@ -0,0 +1,37 @@
+/**
+ * Out-of-band protocol for window-level postMessage handshake.
+ *
+ * These messages travel over `window.postMessage` (no MessagePort yet).
+ * Once the handshake succeeds, all further communication moves to the
+ * transferred MessagePort.
+ */
+
+export const INIT_REQUEST_TYPE = 'astrale-shell/init-request'
+export const INIT_RESPONSE_TYPE = 'astrale-shell/init-response'
+
+export type InitRequestMessage = {
+  readonly type: typeof INIT_REQUEST_TYPE
+  readonly version: 1
+}
+
+export type InitResponseMessage = {
+  readonly type: typeof INIT_RESPONSE_TYPE
+  readonly version: 1
+  readonly windowId: string
+}
+
+export function isInitRequest(value: unknown): value is InitRequestMessage {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (value as { type?: unknown }).type === INIT_REQUEST_TYPE
+  )
+}
+
+export function isInitResponse(value: unknown): value is InitResponseMessage {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (value as { type?: unknown }).type === INIT_RESPONSE_TYPE
+  )
+}

package/src/application/windowing/token-refresh.ts

@@ -0,0 +1,78 @@
+import type { DelegationToken } from '../../domain/identity/delegation'
+
+import { REFRESH_WINDOW_MS } from '../../domain/identity/delegation'
+
+export type TokenRefreshConfig = {
+  readonly token: () => DelegationToken
+  readonly setToken: (next: DelegationToken) => void
+  readonly mint: () => Promise<{ credential: string; expiresAt: number }>
+  readonly functionId: string
+  readonly onFailure?: (error: unknown) => void
+  readonly now?: () => number
+}
+
+export interface TokenRefresher {
+  start(): void
+  stop(): void
+  forceRefreshNow(): Promise<void>
+}
+
+const BACKOFF_DELAYS_MS = [1_000, 2_000, 4_000] as const
+
+export function createTokenRefresher(config: TokenRefreshConfig): TokenRefresher {
+  const now = config.now ?? Date.now
+  let timer: ReturnType<typeof setTimeout> | null = null
+  let stopped = false
+
+  function schedule() {
+    if (stopped) return
+    if (timer) clearTimeout(timer)
+    const token = config.token()
+    const leadTimeMs = Math.max(token.expiresAt - now() - REFRESH_WINDOW_MS, 0)
+    timer = setTimeout(() => {
+      void runRefresh()
+    }, leadTimeMs)
+  }
+
+  async function runRefresh(): Promise<void> {
+    for (let attempt = 0; attempt <= BACKOFF_DELAYS_MS.length; attempt += 1) {
+      if (stopped) return
+      try {
+        const next = await config.mint()
+        config.setToken({
+          credential: next.credential,
+          expiresAt: next.expiresAt,
+          issuedAt: now(),
+          scope: { functionId: config.functionId },
+        })
+        schedule()
+        return
+      } catch (err) {
+        if (attempt === BACKOFF_DELAYS_MS.length) {
+          config.onFailure?.(err)
+          return
+        }
+        await delay(BACKOFF_DELAYS_MS[attempt]!)
+      }
+    }
+  }
+
+  return {
+    start() {
+      stopped = false
+      schedule()
+    },
+    stop() {
+      stopped = true
+      if (timer) clearTimeout(timer)
+      timer = null
+    },
+    async forceRefreshNow() {
+      await runRefresh()
+    },
+  }
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}

package/src/domain/identity/delegation.ts

@@ -0,0 +1,25 @@
+export type DelegationScope = {
+  readonly functionId: string
+}
+
+export type DelegationToken = {
+  readonly credential: string
+  readonly scope: DelegationScope
+  readonly issuedAt: number
+  readonly expiresAt: number
+}
+
+export type TokenState = 'fresh' | 'expiring' | 'expired' | 'refreshing' | 'failed'
+
+/** How long before expiration we start proactively refreshing. */
+export const REFRESH_WINDOW_MS = 120_000
+
+export function stateOf(token: DelegationToken, now = Date.now()): TokenState {
+  if (token.expiresAt <= now) return 'expired'
+  if (token.expiresAt - now <= REFRESH_WINDOW_MS) return 'expiring'
+  return 'fresh'
+}
+
+export function isExpired(token: DelegationToken, now = Date.now()): boolean {
+  return token.expiresAt <= now
+}

package/src/domain/identity/path.ts

@@ -0,0 +1,14 @@
+/**
+ * Built-in kernel root identity, used as the default mint subject when no
+ * explicit `mintIdentity` is configured.
+ */
+export const SYSTEM_IDENTITY = '__system__'
+
+/**
+ * Address a method on an identity or path: `@<id>::method` for a bare node id,
+ * `<path>::method` for an absolute path (one starting with `/`).
+ */
+export function identityMethod(identity: string, method: string): string {
+  const target = identity.startsWith('/') ? identity : `@${identity}`
+  return `${target}::${method}`
+}

package/src/domain/identity/resolve-self.ts

@@ -0,0 +1,38 @@
+import { SYSTEM_IDENTITY } from './path'
+
+/** Kernel path that returns the AUTHENTICATED caller's own identity node. */
+export const WHOAMI_PATH = '/:kernel.astrale.ai:interface.Identity:whoami'
+
+/**
+ * Resolve the mint SUBJECT — the identity node a delegation/credential should be
+ * minted for. It MUST be the principal the kernel actually authenticates this
+ * caller as, otherwise the minted token impersonates someone else.
+ *
+ * Why a kernel round-trip and not the local credential: a cookie-fronted SPA
+ * holds an EMPTY credential string (the session token lives in an httpOnly
+ * cookie it can't read), so the subject cannot be derived locally. We ask the
+ * kernel via `whoami`; that request carries the cookie, so the router unseals it
+ * and the kernel answers with the logged-in user's node. Without this the shell
+ * defaulted every mint to `__system__`, so a View iframe mounted by a logged-in
+ * user acted as the kernel ROOT instead of as that user.
+ *
+ * `fallback` (the configured `mintIdentity`, default `__system__`) is used when
+ * whoami can't be resolved — a genuinely system/dev caller, or an unauthenticated
+ * boot. The result is cached: the principal is stable for a session.
+ */
+export function createSelfResolver(
+  fallback: string = SYSTEM_IDENTITY,
+): (whoami: () => Promise<unknown>) => Promise<string> {
+  let cached: string | undefined
+  return async (whoami) => {
+    if (cached !== undefined) return cached
+    try {
+      const me = (await whoami()) as { id?: unknown } | null
+      const id = me && typeof me.id === 'string' && me.id.length > 0 ? me.id : undefined
+      cached = id ?? fallback
+    } catch {
+      cached = fallback
+    }
+    return cached
+  }
+}

package/src/domain/intent/middleware/capabilities.ts

@@ -0,0 +1,53 @@
+import type { IntentRegistry } from '../../message/registries'
+import type { IntentMessage } from '../../message/types'
+import type { WindowCapabilities } from '../../window/config'
+import type { IntentMiddleware } from '../pipeline'
+
+export type CapabilityLookup = (sender: string) => WindowCapabilities | undefined
+
+export type CapabilityViolation = {
+  readonly sender: string
+  readonly intent: keyof IntentRegistry
+}
+
+export type CapabilitiesConfig = {
+  /**
+   * Map each sender windowId to its declared capabilities. Intents whose
+   * name is absent from the sender's capability list are blocked.
+   */
+  readonly lookup: CapabilityLookup
+
+  /**
+   * Called when an intent is blocked. The violation can be used to emit
+   * an ErrorMessage back to the sender (shell wiring does that separately).
+   */
+  readonly onViolation?: (violation: CapabilityViolation) => void
+
+  /**
+   * If true, intents originated by the shell itself (sender === selfWindowId)
+   * are never filtered. Default: true.
+   */
+  readonly allowSelf?: boolean
+
+  readonly selfWindowId?: string
+}
+
+export function capabilitiesMiddleware(config: CapabilitiesConfig): IntentMiddleware {
+  const { lookup, onViolation, selfWindowId } = config
+  const allowSelf = config.allowSelf ?? true
+
+  return async (message: IntentMessage, next) => {
+    const sender = message.envelope.sender.windowId
+    if (allowSelf && selfWindowId !== undefined && sender === selfWindowId) {
+      await next()
+      return
+    }
+    const caps = lookup(sender)
+    const intentName = message.envelope.name
+    if (!caps || !caps.intents.includes(intentName)) {
+      onViolation?.({ sender, intent: intentName })
+      return
+    }
+    await next()
+  }
+}

package/src/domain/intent/middleware/logging.ts

@@ -0,0 +1,45 @@
+import type { IntentMessage } from '../../message/types'
+import type { IntentMiddleware } from '../pipeline'
+
+export type LoggingSink = (entry: LoggingEntry) => void
+
+export type LoggingEntry = {
+  readonly name: string
+  readonly sender: string
+  readonly correlationId?: string
+  readonly phase: 'in' | 'out'
+  readonly timestamp: number
+}
+
+export type LoggingConfig = {
+  readonly sink?: LoggingSink
+}
+
+export function loggingMiddleware(config: LoggingConfig = {}): IntentMiddleware {
+  const sink = config.sink ?? defaultSink
+
+  return async (message: IntentMessage, next) => {
+    sink(toEntry(message, 'in'))
+    await next()
+    sink(toEntry(message, 'out'))
+  }
+}
+
+function toEntry(message: IntentMessage, phase: 'in' | 'out'): LoggingEntry {
+  return {
+    name: message.envelope.name as string,
+    sender: message.envelope.sender.windowId,
+    correlationId: message.envelope.correlationId,
+    phase,
+    timestamp: Date.now(),
+  }
+}
+
+function defaultSink(entry: LoggingEntry): void {
+  // eslint-disable-next-line no-console -- built-in sink; opt-in via wiring.
+  console.debug(
+    `[shell.intent] ${entry.phase} ${entry.name} from=${entry.sender}${
+      entry.correlationId ? ` corr=${entry.correlationId}` : ''
+    }`,
+  )
+}

package/src/domain/intent/middleware/rate-limit.ts

@@ -0,0 +1,54 @@
+import type { IntentMessage } from '../../message/types'
+import type { IntentMiddleware } from '../pipeline'
+
+export type RateLimitKey = (message: IntentMessage) => string
+
+export type RateLimitViolation = {
+  readonly key: string
+  readonly intent: string
+}
+
+export type RateLimitConfig = {
+  readonly windowMs: number
+  readonly max: number
+  readonly key?: RateLimitKey
+  readonly onViolation?: (violation: RateLimitViolation) => void
+}
+
+/**
+ * Fixed-window rate limiter. An amortized sweep evicts expired buckets on
+ * every `windowMs` interval of activity so the map stays bounded by the
+ * number of active keys, not the total ever seen.
+ */
+export function rateLimitMiddleware(config: RateLimitConfig): IntentMiddleware {
+  const { windowMs, max, onViolation } = config
+  const key = config.key ?? ((m) => `${m.envelope.sender.windowId}|${m.envelope.name as string}`)
+
+  type Bucket = { count: number; resetAt: number }
+  const buckets = new Map<string, Bucket>()
+  let nextSweepAt = 0
+
+  return async (message, next) => {
+    const k = key(message)
+    const now = Date.now()
+
+    if (now >= nextSweepAt) {
+      for (const [bucketKey, bucket] of buckets) {
+        if (bucket.resetAt <= now) buckets.delete(bucketKey)
+      }
+      nextSweepAt = now + windowMs
+    }
+
+    let bucket = buckets.get(k)
+    if (!bucket || bucket.resetAt <= now) {
+      bucket = { count: 0, resetAt: now + windowMs }
+      buckets.set(k, bucket)
+    }
+    bucket.count += 1
+    if (bucket.count > max) {
+      onViolation?.({ key: k, intent: message.envelope.name as string })
+      return
+    }
+    await next()
+  }
+}

package/src/domain/intent/pipeline.ts

@@ -0,0 +1,3 @@
+import type { IntentMessage } from '../message/types'
+
+export type IntentMiddleware = (message: IntentMessage, next: () => Promise<void>) => Promise<void>

package/src/domain/intent/router.ts

@@ -0,0 +1,6 @@
+import type { IntentRegistry } from '../message/registries'
+import type { IntentMessage } from '../message/types'
+
+export interface IntentRouter {
+  dispatch<K extends keyof IntentRegistry>(message: IntentMessage<K>): Promise<void>
+}