@astrale-os/shell 0.1.0

package/src/domain/message/errors.ts

@@ -0,0 +1,9 @@
+export type ErrorCode =
+  | 'HANDSHAKE_TIMEOUT'
+  | 'ORIGIN_MISMATCH'
+  | 'WINDOW_UNAVAILABLE'
+  | 'UNSUPPORTED_VERSION'
+  | 'INTENT_NOT_ALLOWED'
+  | 'DELIVERY_FAILED'
+  | 'TOKEN_REFRESH_FAILED'
+  | 'NO_VIEW_AVAILABLE'

package/src/domain/message/registries.ts

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

@@ -0,0 +1,32 @@
+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/domain/window/config.ts

@@ -0,0 +1,28 @@
+import type { IntentRegistry } from '../message/registries'
+
+export interface SandboxProfile {
+  readonly allowScripts: boolean
+  readonly allowForms: boolean
+  readonly allowPopups: boolean
+  readonly allowSameOrigin: boolean
+  readonly allowModals: boolean
+}
+
+export interface WindowCapabilities {
+  readonly intents: ReadonlyArray<keyof IntentRegistry>
+}
+
+export interface WindowConfig {
+  readonly functionId: string
+  readonly isolation: 'sandboxed' | 'shared'
+  readonly capabilities: WindowCapabilities
+  /**
+   * Sandbox profile for the iframe.
+   * - `undefined` → adapter default (`DEFAULT_SANDBOX` in iframe.shell-adapter).
+   * - `SandboxProfile` → explicit flag set, becomes the `sandbox=…` attribute.
+   * - `null` → opt out: no `sandbox` attribute on the iframe at all (the
+   *   browser's cross-origin policy is the only remaining isolation). Used
+   *   for first-party trusted views per the GUI allowlist.
+   */
+  readonly sandbox?: SandboxProfile | null
+}

package/src/domain/window/lifecycle.ts

@@ -0,0 +1,39 @@
+import type { WindowState } from './window'
+
+export type LifecycleEvent =
+  | { kind: 'hide' }
+  | { kind: 'restore' }
+  | { kind: 'requestClose' }
+  | { kind: 'closeAck' }
+  | { kind: 'closeRefuse' }
+  | { kind: 'forceClose' }
+
+export type TransitionResult = { ok: true; next: WindowState } | { ok: false; reason: string }
+
+/**
+ * Pure state-machine transition. Used by the lifecycle controller —
+ * no timers, no side effects here.
+ */
+export function transition(state: WindowState, event: LifecycleEvent): TransitionResult {
+  switch (state) {
+    case 'active':
+      if (event.kind === 'hide') return { ok: true, next: 'hidden' }
+      if (event.kind === 'requestClose') return { ok: true, next: 'closing' }
+      if (event.kind === 'forceClose') return { ok: true, next: 'closed' }
+      break
+    case 'hidden':
+      if (event.kind === 'restore') return { ok: true, next: 'active' }
+      if (event.kind === 'requestClose') return { ok: true, next: 'closing' }
+      if (event.kind === 'forceClose') return { ok: true, next: 'closed' }
+      break
+    case 'closing':
+      if (event.kind === 'closeAck') return { ok: true, next: 'closed' }
+      if (event.kind === 'closeRefuse') return { ok: true, next: 'active' }
+      if (event.kind === 'forceClose') return { ok: true, next: 'closed' }
+      break
+    case 'closed':
+      // Terminal — no transitions out.
+      break
+  }
+  return { ok: false, reason: `invalid transition ${state}.${event.kind}` }
+}

package/src/domain/window/window.ts

@@ -0,0 +1,13 @@
+import type { WindowCapabilities } from './config'
+
+export type WindowState = 'active' | 'hidden' | 'closing' | 'closed'
+
+export interface Window {
+  readonly windowId: string
+  readonly functionId: string
+  readonly targetNodeId?: string
+  readonly isolation: 'sandboxed' | 'shared'
+  readonly state: WindowState
+  readonly delegationToken: string | null
+  readonly capabilities: WindowCapabilities
+}

package/src/index.ts

@@ -0,0 +1,103 @@
+// ─── domain/message ─────────────────────────────────────────────────────────
+export type { ErrorCode } from './domain/message/errors'
+export type { IntentRegistry, CtrlRegistry, ViewRef } from './domain/message/registries'
+export type {
+  ShellMessage,
+  IntentMessage,
+  IntentEnvelope,
+  CtrlMessage,
+  ErrorMessage,
+} from './domain/message/types'
+
+// ─── domain/window ──────────────────────────────────────────────────────────
+export type { WindowConfig, WindowCapabilities, SandboxProfile } from './domain/window/config'
+export type { Window, WindowState } from './domain/window/window'
+export { transition as lifecycleTransition } from './domain/window/lifecycle'
+export type { LifecycleEvent, TransitionResult } from './domain/window/lifecycle'
+
+// ─── domain/intent ──────────────────────────────────────────────────────────
+export type { IntentMiddleware } from './domain/intent/pipeline'
+export type { IntentRouter } from './domain/intent/router'
+export { loggingMiddleware } from './domain/intent/middleware/logging'
+export type { LoggingConfig, LoggingEntry, LoggingSink } from './domain/intent/middleware/logging'
+export { capabilitiesMiddleware } from './domain/intent/middleware/capabilities'
+export type {
+  CapabilitiesConfig,
+  CapabilityLookup,
+  CapabilityViolation,
+} from './domain/intent/middleware/capabilities'
+export { rateLimitMiddleware } from './domain/intent/middleware/rate-limit'
+export type { RateLimitConfig, RateLimitViolation } from './domain/intent/middleware/rate-limit'
+
+// ─── domain/identity ────────────────────────────────────────────────────────
+export type { DelegationScope, DelegationToken, TokenState } from './domain/identity/delegation'
+export { stateOf, isExpired } from './domain/identity/delegation'
+
+// ─── ports ──────────────────────────────────────────────────────────────────
+export type { Transport } from './ports/transport'
+export type { ShellAdapter, WindowHandle } from './ports/shell-adapter'
+export type { KernelClient } from './ports/kernel-client'
+
+// ─── adapters ───────────────────────────────────────────────────────────────
+export { createKernelClientAdapter } from './adapters/kernel-client.adapter'
+export type {
+  KernelClientAdapter,
+  CreateKernelClientAdapterOpts,
+} from './adapters/kernel-client.adapter'
+export { createMessagePortTransport } from './adapters/message-port.transport'
+export type { MessagePortTransportConfig } from './adapters/message-port.transport'
+export { createIframeShellAdapter } from './adapters/iframe.shell-adapter'
+export type { IframeShellAdapterConfig } from './adapters/iframe.shell-adapter'
+
+// ─── application ────────────────────────────────────────────────────────────
+export type {
+  Shell,
+  ShellConfig,
+  StandaloneConfig,
+  SandboxedConfig,
+  MountParams,
+  MountedWindow,
+  CloseResult,
+  ParentChannel,
+  ChildrenChannel,
+  MessageDirection,
+  MessageHandler,
+  ObserverHandler,
+} from './application/shell'
+export { createShell } from './application/shell'
+
+// ─── application/windowing (advanced / testing) ─────────────────────────────
+export { runParentHandshake } from './application/windowing/handshake'
+export type {
+  HandshakeParams,
+  HandshakeError,
+  HandshakeResult,
+} from './application/windowing/handshake'
+export { performChildInit } from './application/windowing/child-init'
+export type { ChildInitParams, ChildInitResult } from './application/windowing/child-init'
+export { createTokenRefresher } from './application/windowing/token-refresh'
+export type { TokenRefreshConfig, TokenRefresher } from './application/windowing/token-refresh'
+
+// ─── application/intent (advanced / testing) ────────────────────────────────
+export { createIntentPipeline } from './application/intent/pipeline-runner'
+export type { IntentPipeline } from './application/intent/pipeline-runner'
+export { createIntentRouter } from './application/intent/router'
+export type {
+  IntentRouterController,
+  IntentRouterConfig,
+  IntentDecision,
+  IntentOrigin,
+  IntentPolicy,
+  IntentContext,
+  LocalIntentHandler,
+} from './application/intent/router'
+export { requestIntent, replyToIntent, requestAccess } from './application/intent/request'
+
+// ─── Init-request protocol (shared with host pages) ─────────────────────────
+export {
+  INIT_REQUEST_TYPE,
+  INIT_RESPONSE_TYPE,
+  isInitRequest,
+  isInitResponse,
+} from './application/windowing/protocol'
+export type { InitRequestMessage, InitResponseMessage } from './application/windowing/protocol'

package/src/ports/kernel-client.ts

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

package/src/ports/shell-adapter.ts

@@ -0,0 +1,11 @@
+import type { WindowConfig } from '../domain/window/config'
+
+export interface WindowHandle {
+  readonly element: HTMLIFrameElement | HTMLElement
+  readonly port: MessagePort | null
+  readonly origin: string
+}
+
+export interface ShellAdapter {
+  mount(config: WindowConfig): { handle: WindowHandle; dispose: () => void }
+}

package/src/ports/transport.ts

@@ -0,0 +1,7 @@
+import type { ShellMessage } from '../domain/message/types'
+
+export interface Transport {
+  send(message: ShellMessage): void
+  onMessage(handler: (message: ShellMessage) => void): void
+  close(): void
+}