@astrale-os/shell 0.1.0 → 0.2.0

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

@@ -1,335 +0,0 @@
-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/domain/identity/path.ts

@@ -1,14 +0,0 @@
-/**
- * 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

@@ -1,38 +0,0 @@
-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/pipeline.ts

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

package/src/domain/intent/router.ts

@@ -1,6 +0,0 @@
-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>
-}

package/src/domain/message/registries.ts

@@ -1,76 +0,0 @@
-export interface ViewRef {
-  readonly viewId: string
-  readonly functionId: string
-  readonly label?: string
-}
-
-/**
- * Intent registry — extensible via declaration merging.
- *
- * Consumers extend via:
- *   declare module '@astrale-os/shell' {
- *     interface IntentRegistry { ... }
- *   }
- */
-export interface IntentRegistry {
-  open: { payload: { nodeId: string; viewId?: string }; response: { windowId: string } }
-  close: { payload: { windowId: string }; response: void }
-  focus: { payload: { nodeId: string }; response: void }
-  willClose: { payload: Record<string, never>; response: void }
-  closeAck: { payload: Record<string, never>; response: void }
-  closeRefuse: { payload: { reason: string }; response: void }
-  pickView: { payload: { views: ViewRef[] }; response: { viewId: string } }
-  receive: { payload: { data: unknown; sourceIntent: string }; response: void }
-  /**
-   * Hot-swap — parent pushes a new target node to an already-mounted view
-   * without remounting. The child reads `targetNodeId` at handshake time
-   * for the initial value; `setTarget` replaces it for the lifetime of the
-   * window.
-   */
-  setTarget: { payload: { nodeId: string }; response: void }
-  /**
-   * Child → parent: a view asks the user to grant `perms` (a permission
-   * bitmask) on `node` to `identity` (the beneficiary subject). Both `node`
-   * and `identity` are bare node ids (e.g. the view's `targetNodeId`, or
-   * `whoami().id` for "grant to myself") — the root shell addresses them as
-   * `@<id>`. The root shell (GUI) surfaces a modal, computes the delta vs.
-   * what the subject already holds, and — on approval — grants only the
-   * missing bits under the GUI user's own credential. `reason` is shown to
-   * the user. `response.perms` is the bitmask actually granted (0 if
-   * declined / nothing was missing).
-   *
-   * Reaches a handler only from a view mounted as a DIRECT child of the root
-   * shell — the default intent policy does not bubble past one hop.
-   */
-  requestAccess: {
-    payload: { node: string; identity: string; perms: number; reason?: string }
-    response: { granted: boolean; perms: number }
-  }
-  /**
-   * Generic correlated reply channel. The default intent transport is
-   * fire-and-forget; `requestIntent()` sends an intent carrying a
-   * `correlationId` and awaits an `intentReply` whose payload echoes it back
-   * with the handler's `result`. Routed to the resolver purely by
-   * `correlationId` — it intentionally matches no local handler.
-   */
-  intentReply: { payload: { correlationId: string; result: unknown }; response: void }
-}
-
-/**
- * Control message registry — extensible via declaration merging.
- */
-export interface CtrlRegistry {
-  handshake: {
-    data: {
-      delegationToken: string
-      tokenExpiresAt: number
-      windowId: string
-      kernelUrl: string
-      functionId: string
-      targetNodeId?: string
-      mintIdentity?: string
-    }
-  }
-  handshakeAck: { data: { windowId: string } }
-  tokenRefresh: { data: { delegationToken: string; tokenExpiresAt: number } }
-}

package/src/domain/message/types.ts

@@ -1,32 +0,0 @@
-import type { ErrorCode } from './errors'
-import type { CtrlRegistry, IntentRegistry } from './registries'
-
-export type IntentEnvelope<K extends keyof IntentRegistry = keyof IntentRegistry> = {
-  readonly name: K
-  readonly payload: IntentRegistry[K]['payload']
-  readonly sender: { readonly windowId: string }
-  readonly correlationId?: string
-}
-
-export type IntentMessage<K extends keyof IntentRegistry = keyof IntentRegistry> = {
-  readonly type: 'intent'
-  readonly version: 1
-  readonly envelope: IntentEnvelope<K>
-}
-
-export type CtrlMessage<K extends keyof CtrlRegistry = keyof CtrlRegistry> = {
-  readonly type: 'ctrl'
-  readonly version: 1
-  readonly action: K
-  readonly data: CtrlRegistry[K]['data']
-}
-
-export type ErrorMessage = {
-  readonly type: 'error'
-  readonly version: 1
-  readonly code: ErrorCode
-  readonly message: string
-  readonly context?: unknown
-}
-
-export type ShellMessage = IntentMessage | CtrlMessage | ErrorMessage

package/src/ports/kernel-client.ts

@@ -1,32 +0,0 @@
-export interface KernelClient {
-  call(path: string, params: unknown): Promise<unknown>
-  /**
-   * Produce a credential usable by a child shell.
-   *
-   * v1: returns a fresh identity credential scoped to the current principal.
-   * Future (SDK v2): will accept `{ functionId }` to scope the delegation
-   * to a specific Function — tracked in `.dev/todo/shell-sdk-v2-delegation.md`.
-   */
-  mintDelegation(): Promise<string>
-  /**
-   * Return the JWT this shell currently uses to authenticate `call`. Iframes
-   * use it to make their own authenticated HTTP requests to the kernel —
-   * e.g. when a third-party SDK like Vercel AI's `useChat` issues a raw
-   * `fetch()` that can't run through `call()`. Callers form the Authorization
-   * header themselves: `Authorization: \`Bearer ${shell.kernel.authToken()}\``.
-   *
-   * The value is the *current* token; the parent shell auto-refreshes it
-   * before expiry, so always read fresh on each request rather than caching.
-   */
-  authToken(): string
-  /**
-   * URL of the kernel this shell talks to. Pair with `authToken()` when an
-   * iframe needs to make a raw `fetch()` from a third-party SDK (e.g.
-   * Vercel AI's `useChat`): the kernel-issued JWT's `aud` matches the
-   * kernel's own issuer, so requests must target the kernel directly. If
-   * a sandboxed iframe POSTs to its own `window.location.origin` (the
-   * worker hosting the iframe), the worker's audience check rejects the
-   * cred with "Credential audience mismatch".
-   */
-  readonly url: string
-}