@astrale-os/shell 0.1.0

package/src/application/channels/parent-channel.ts

@@ -0,0 +1,43 @@
+import type { ShellMessage } from '../../domain/message/types'
+import type { Transport } from '../../ports/transport'
+import type { MessageObserver } from './observer'
+import type { MessageHandler, MessageOf, MessageType } from './types'
+
+import { createMessageListeners } from './types'
+
+export interface ParentChannel {
+  send(message: ShellMessage): void
+  on<T extends MessageType>(type: T, handler: MessageHandler<MessageOf<T>>): () => void
+}
+
+export interface ParentChannelController extends ParentChannel {
+  dispose(): void
+}
+
+export type ParentChannelConfig = {
+  transport: Transport
+  observer: MessageObserver
+}
+
+export function createParentChannel(config: ParentChannelConfig): ParentChannelController {
+  const { transport, observer } = config
+  const listeners = createMessageListeners()
+
+  transport.onMessage((message) => {
+    observer.notify('inbound', message)
+    listeners.dispatch(message)
+  })
+
+  return {
+    send(message) {
+      observer.notify('outbound', message)
+      transport.send(message)
+    },
+    on(type, handler) {
+      return listeners.on(type, handler)
+    },
+    dispose() {
+      transport.close()
+    },
+  }
+}

package/src/application/channels/types.ts

@@ -0,0 +1,41 @@
+import type { ShellMessage } from '../../domain/message/types'
+
+export type MessageHandler<M extends ShellMessage = ShellMessage> = (message: M) => void
+
+export type MessageType = ShellMessage['type']
+
+export type MessageOf<T extends MessageType> = Extract<ShellMessage, { type: T }>
+
+export interface MessageListeners {
+  on<T extends MessageType>(type: T, handler: MessageHandler<MessageOf<T>>): () => void
+  dispatch(message: ShellMessage): void
+}
+
+export function createMessageListeners(): MessageListeners {
+  const byType = new Map<MessageType, Set<MessageHandler>>()
+
+  return {
+    on(type, handler) {
+      let bucket = byType.get(type)
+      if (!bucket) {
+        bucket = new Set()
+        byType.set(type, bucket)
+      }
+      bucket.add(handler as MessageHandler)
+      return () => {
+        bucket.delete(handler as MessageHandler)
+      }
+    },
+    dispatch(message) {
+      const bucket = byType.get(message.type)
+      if (!bucket || bucket.size === 0) return
+      for (const handler of bucket) {
+        try {
+          handler(message)
+        } catch {
+          // one rogue handler must not break siblings
+        }
+      }
+    },
+  }
+}

package/src/application/intent/pipeline-runner.ts

@@ -0,0 +1,36 @@
+import type { IntentMiddleware } from '../../domain/intent/pipeline'
+import type { IntentMessage } from '../../domain/message/types'
+
+export interface IntentPipeline {
+  use(middleware: IntentMiddleware): void
+  run(message: IntentMessage, terminate: () => Promise<void>): Promise<void>
+}
+
+/**
+ * Composable middleware runner. Each middleware may transform, short-circuit,
+ * or wrap the call to `next`. `terminate` is the innermost handler (router).
+ */
+export function createIntentPipeline(): IntentPipeline {
+  const middlewares: IntentMiddleware[] = []
+
+  return {
+    use(middleware) {
+      middlewares.push(middleware)
+    },
+
+    async run(message, terminate) {
+      let i = -1
+      const dispatch = async (idx: number): Promise<void> => {
+        if (idx <= i) throw new Error('next() called multiple times')
+        i = idx
+        if (idx === middlewares.length) {
+          await terminate()
+          return
+        }
+        const mw = middlewares[idx]!
+        await mw(message, () => dispatch(idx + 1))
+      }
+      await dispatch(0)
+    },
+  }
+}

package/src/application/intent/request.ts

@@ -0,0 +1,87 @@
+import { NO_PERMS } from '@astrale-os/kernel-core/permissions'
+
+import type { IntentRegistry } from '../../domain/message/registries'
+import type { IntentMessage } from '../../domain/message/types'
+import type { ChildrenChannel } from '../channels/children-channel'
+import type { ParentChannel } from '../channels/parent-channel'
+import type { Shell } from '../shell'
+
+/**
+ * Request/reply over the otherwise fire-and-forget intent transport.
+ *
+ * The child raises `name` with a generated `correlationId` and awaits the
+ * `intentReply` whose payload echoes that id. The reply also re-enters the
+ * child router as an inbound parent intent, but no handler is registered for
+ * `intentReply`, so it is harmlessly dropped there — only this resolver,
+ * matching by `correlationId`, consumes it.
+ *
+ * No timeout by design: callers (e.g. `requestAccess`) wait on a human, and
+ * the parent always replies on every path. A dead parent means the view is
+ * gone too, so a never-resolving promise cannot strand a live view.
+ */
+export function requestIntent<K extends keyof IntentRegistry>(
+  parent: ParentChannel,
+  name: K,
+  payload: IntentRegistry[K]['payload'],
+): Promise<IntentRegistry[K]['response']> {
+  const correlationId = crypto.randomUUID()
+  return new Promise((resolve) => {
+    const off = parent.on('intent', (message) => {
+      if (message.envelope.name !== 'intentReply') return
+      const reply = message.envelope.payload as IntentRegistry['intentReply']['payload']
+      if (reply.correlationId !== correlationId) return
+      off()
+      resolve(reply.result as IntentRegistry[K]['response'])
+    })
+    parent.send({
+      type: 'intent',
+      version: 1,
+      envelope: { name, payload, sender: { windowId: 'self' }, correlationId },
+    })
+  })
+}
+
+/**
+ * Parent-side counterpart to `requestIntent`: deliver `result` back to the
+ * originating child window, keyed by the request's `correlationId`. No-op for
+ * a request that carried no `correlationId` (a fire-and-forget intent), or if
+ * the child window has since detached (best-effort, drops silently).
+ */
+export function replyToIntent<K extends keyof IntentRegistry>(
+  children: ChildrenChannel,
+  windowId: string,
+  request: IntentMessage<K>,
+  result: IntentRegistry[K]['response'],
+): void {
+  const correlationId = request.envelope.correlationId
+  if (!correlationId) return
+  children.send(windowId, {
+    type: 'intent',
+    version: 1,
+    envelope: {
+      name: 'intentReply',
+      payload: { correlationId, result },
+      sender: { windowId: 'root' },
+    },
+  })
+}
+
+/**
+ * View SDK convenience: ask the user (via the root shell) to grant `perms` on
+ * `node` to `identity`. Resolves with the bitmask actually granted (0 if the
+ * user declined or there was no parent to ask). The view typically passes its
+ * own identity (from `whoami`) as `identity`.
+ */
+export function requestAccess(
+  shell: Shell,
+  opts: IntentRegistry['requestAccess']['payload'],
+): Promise<IntentRegistry['requestAccess']['response']> {
+  if (!shell.parent) return Promise.resolve({ granted: false, perms: NO_PERMS })
+  // A sandboxed shell's `parent` is a proxy that throws until `init()` resolves;
+  // honour the documented "no parent to ask" fallback instead of surfacing that
+  // opaque rejection to the caller.
+  return requestIntent(shell.parent, 'requestAccess', opts).catch(() => ({
+    granted: false,
+    perms: NO_PERMS,
+  }))
+}

package/src/application/intent/router.ts

@@ -0,0 +1,161 @@
+import type { IntentRegistry } from '../../domain/message/registries'
+import type { IntentMessage } from '../../domain/message/types'
+import type { Window } from '../../domain/window/window'
+import type { ChildrenChannelController } from '../channels/children-channel'
+import type { ParentChannel } from '../channels/parent-channel'
+import type { IntentPipeline } from './pipeline-runner'
+
+/**
+ * Decision produced by a routing policy: where an inbound intent should go.
+ *
+ *  - `local`: the shell (entry point or sandboxed parent) handles it itself.
+ *  - `parent`: forward upstream (only valid for sandboxed children).
+ *  - `child`: forward to a specific child window.
+ *  - `drop`: discard silently (e.g., handled fully by a middleware).
+ */
+export type IntentDecision<K extends keyof IntentRegistry = keyof IntentRegistry> =
+  | { kind: 'local'; message: IntentMessage<K> }
+  | { kind: 'parent'; message: IntentMessage<K> }
+  | { kind: 'child'; windowId: string; message: IntentMessage<K> }
+  | { kind: 'drop' }
+
+export type IntentOrigin = 'parent' | 'child' | 'self'
+
+export type IntentPolicy = (
+  message: IntentMessage,
+  ctx: IntentContext,
+) => IntentDecision | Promise<IntentDecision>
+
+export interface IntentContext {
+  readonly selfWindowId: string
+  readonly origin: IntentOrigin
+  readonly windows: ReadonlyMap<string, Window>
+  readonly hasParent: boolean
+}
+
+export type LocalIntentHandler<K extends keyof IntentRegistry = keyof IntentRegistry> = (
+  message: IntentMessage<K>,
+) => void | Promise<void>
+
+export interface IntentRouterController {
+  /**
+   * Route an inbound intent. `senderWindowId`, when provided, is the trusted
+   * windowId the channel authenticated; it overrides the (forgeable)
+   * `envelope.sender.windowId` before the pipeline runs.
+   */
+  handleInbound(
+    origin: IntentOrigin,
+    message: IntentMessage,
+    senderWindowId?: string,
+  ): Promise<void>
+  dispatchLocal(message: IntentMessage): Promise<void>
+  setPolicy(policy: IntentPolicy): void
+  onLocal<K extends keyof IntentRegistry>(name: K, handler: LocalIntentHandler<K>): () => void
+}
+
+export type IntentRouterConfig = {
+  selfWindowId: string
+  pipeline: IntentPipeline
+  parent: ParentChannel | null
+  children: ChildrenChannelController
+  windows: ReadonlyMap<string, Window>
+}
+
+/**
+ * Default policy:
+ *  - intent arrives from a child → handle locally
+ *  - intent arrives from the parent → handle locally
+ *  - intent initiated locally (self) → send up to parent if we have one,
+ *    otherwise keep it local
+ */
+function defaultPolicy(): IntentPolicy {
+  return (message, ctx) => {
+    if (ctx.origin === 'self') {
+      return ctx.hasParent ? { kind: 'parent', message } : { kind: 'local', message }
+    }
+    return { kind: 'local', message }
+  }
+}
+
+/** Return a copy of `message` with a trusted `sender.windowId`. */
+function withSender(message: IntentMessage, windowId: string): IntentMessage {
+  return { ...message, envelope: { ...message.envelope, sender: { windowId } } }
+}
+
+export function createIntentRouter(config: IntentRouterConfig): IntentRouterController {
+  const { pipeline, parent, children, windows, selfWindowId } = config
+  let policy: IntentPolicy = defaultPolicy()
+  const localHandlers = new Map<string, Set<LocalIntentHandler>>()
+
+  async function forward(decision: IntentDecision): Promise<void> {
+    switch (decision.kind) {
+      case 'drop':
+        return
+      case 'parent':
+        if (!parent) return
+        parent.send(decision.message)
+        return
+      case 'child':
+        if (!children.has(decision.windowId)) return
+        children.send(decision.windowId, decision.message)
+        return
+      case 'local': {
+        const bucket = localHandlers.get(decision.message.envelope.name)
+        if (!bucket) return
+        for (const handler of bucket) {
+          try {
+            await handler(decision.message)
+          } catch {
+            // Handler errors must not interrupt sibling handlers.
+          }
+        }
+        return
+      }
+    }
+  }
+
+  const ctxBase = {
+    selfWindowId,
+    windows,
+    hasParent: parent !== null,
+  } as const
+
+  return {
+    async handleInbound(origin, message, senderWindowId) {
+      // `envelope.sender.windowId` is attacker-controlled wire data: a sandboxed
+      // child can claim any id. Overwrite it with the windowId the channel
+      // authenticated so capability/rate-limit middleware can't be bypassed by a
+      // forged sender. The original message object is left untouched for raw
+      // channel listeners; only this routed copy carries the trusted id.
+      const inbound = senderWindowId === undefined ? message : withSender(message, senderWindowId)
+      await pipeline.run(inbound, async () => {
+        const decision = await policy(inbound, { ...ctxBase, origin })
+        await forward(decision)
+      })
+    },
+
+    async dispatchLocal(message) {
+      const stamped = withSender(message, selfWindowId)
+      await pipeline.run(stamped, async () => {
+        const decision = await policy(stamped, { ...ctxBase, origin: 'self' })
+        await forward(decision)
+      })
+    },
+
+    setPolicy(next) {
+      policy = next
+    },
+
+    onLocal(name, handler) {
+      let bucket = localHandlers.get(name as string)
+      if (!bucket) {
+        bucket = new Set()
+        localHandlers.set(name as string, bucket)
+      }
+      bucket.add(handler as LocalIntentHandler)
+      return () => {
+        bucket.delete(handler as LocalIntentHandler)
+      }
+    },
+  }
+}

package/src/application/kernel-facade.ts

@@ -0,0 +1,143 @@
+import type { KernelClientAdapter } from '../adapters/kernel-client.adapter'
+import type { DelegationToken } from '../domain/identity/delegation'
+import type { KernelClient } from '../ports/kernel-client'
+
+import { identityMethod } from '../domain/identity/path'
+import { createSelfResolver, WHOAMI_PATH } from '../domain/identity/resolve-self'
+
+// ─── Base facade (standalone / user credential) ─────────────────────────────
+
+export type KernelFacadeConfig = {
+  adapter: KernelClientAdapter
+  credential?: string
+  getCredential?: () => string
+  /** Kernel URL — exposed to consumers via `KernelClient.url`. */
+  url: string
+  /**
+   * Explicit identity node to use as the mint subject. When omitted, the mint
+   * resolves the AUTHENTICATED caller via `whoami` (so a cookie-fronted GUI mints
+   * as the logged-in user, not the kernel root). Set this only to pin a subject.
+   */
+  mintIdentity?: string
+}
+
+export interface KernelFacadeController extends KernelClient {
+  dispose(): void
+}
+
+export function createKernelFacade(config: KernelFacadeConfig): KernelFacadeController {
+  const getCredential =
+    config.getCredential ??
+    (() => {
+      if (config.credential === undefined) {
+        throw new Error('KernelFacade requires credential or getCredential')
+      }
+      return config.credential
+    })
+  return buildCredentialFacade({
+    adapter: config.adapter,
+    getCredential,
+    url: config.url,
+    mintIdentity: config.mintIdentity,
+  })
+}
+
+// ─── Delegation facade (sandboxed mode) ─────────────────────────────────────
+
+export type DelegationKernelFacadeConfig = {
+  adapter: KernelClientAdapter
+  initialToken: DelegationToken
+  url: string
+  onTokenChange?: (token: DelegationToken) => void
+  mintIdentity?: string
+}
+
+export interface DelegationKernelFacadeController extends KernelFacadeController {
+  token(): DelegationToken
+  setToken(next: DelegationToken): void
+}
+
+export function createDelegationKernelFacade(
+  config: DelegationKernelFacadeConfig,
+): DelegationKernelFacadeController {
+  let token = config.initialToken
+  const base = buildCredentialFacade({
+    adapter: config.adapter,
+    getCredential: () => token.credential,
+    url: config.url,
+    mintIdentity: config.mintIdentity,
+  })
+
+  return {
+    ...base,
+    token() {
+      return token
+    },
+    setToken(next) {
+      if (next.credential === token.credential && next.expiresAt === token.expiresAt) return
+      token = next
+      config.onTokenChange?.(next)
+    },
+    // The delegation facade owns its adapter exclusively (created per child in
+    // `performChildInit`), so disposing it must tear the adapter down — unlike
+    // the standalone facade, where the caller owns the adapter's lifetime.
+    dispose() {
+      config.adapter.disconnect()
+    },
+  }
+}
+
+// ─── Shared facade builder ──────────────────────────────────────────────────
+
+type FacadeParams = {
+  adapter: KernelClientAdapter
+  getCredential: () => string
+  url: string
+  /** Explicit mint subject. When omitted, the authenticated caller is resolved via `whoami`. */
+  mintIdentity?: string
+}
+
+/**
+ * v1 note: we mint a fresh identity credential (grant-bearing, directly
+ * usable). Proper delegation composition (outer envelope via `Cred(...)`)
+ * requires SDK v2 — tracked in `.dev/todo/shell-sdk-v2-delegation.md`.
+ */
+function buildCredentialFacade(params: FacadeParams): KernelFacadeController {
+  const { adapter, getCredential, mintIdentity, url } = params
+  const resolveSelf = createSelfResolver()
+
+  return {
+    url,
+
+    call(path, callParams) {
+      return adapter.call(path, callParams, getCredential())
+    },
+
+    async mintDelegation() {
+      const subject =
+        mintIdentity ?? (await resolveSelf(() => adapter.call(WHOAMI_PATH, {}, getCredential())))
+      const result = await adapter.call(
+        identityMethod(subject, 'mintIdentityCredential'),
+        {},
+        getCredential(),
+      )
+      if (typeof result === 'string') return result
+      if (
+        result !== null &&
+        typeof result === 'object' &&
+        typeof (result as { credential?: unknown }).credential === 'string'
+      ) {
+        return (result as { credential: string }).credential
+      }
+      throw new Error('mintIdentityCredential returned an unexpected shape')
+    },
+
+    authToken() {
+      return getCredential()
+    },
+
+    dispose() {
+      // adapter lifetime is owned by the caller
+    },
+  }
+}