@astrale-os/cli 1.0.0-beta.19 → 1.0.0-beta.20

package/src/lib/__tests__/view-external-open-intent.test.ts

@@ -0,0 +1,150 @@
+import type { ChildrenChannel, ExternalOpenRequest, Shell } from '@astrale-os/shell'
+
+import { capabilitiesMiddleware, createIntentPipeline, createIntentRouter } from '@astrale-os/shell'
+import { describe, expect, mock, test } from 'bun:test'
+
+import type { ExternalOpenIntentMessage } from '../view/external-open-intent'
+
+import {
+  installExternalOpenIntentHandler,
+  openExternalBrowserWindow,
+} from '../view/external-open-intent'
+import { viewHostCapabilities } from '../view/host-capabilities'
+
+describe('View external navigation host effect', () => {
+  test('the real Shell pipeline opens only an exact granted origin and replies to the physical child', async () => {
+    const sent: Array<{ windowId: string; message: unknown }> = []
+    const children = {
+      send: (windowId: string, value: unknown) => sent.push({ windowId, message: value }),
+      has: () => true,
+      on: () => () => undefined,
+      onClose: () => () => undefined,
+    } as ChildrenChannel
+    const capabilities = viewHostCapabilities(['https://connect.nango.dev'])
+    const pipeline = createIntentPipeline()
+    pipeline.use(
+      capabilitiesMiddleware({
+        lookup: (sender) => (sender === 'physical-child' ? capabilities : undefined),
+      }),
+    )
+    const router = createIntentRouter({
+      selfWindowId: 'root',
+      pipeline,
+      parent: null,
+      children,
+    })
+    const open = mock((_request: ExternalOpenRequest) => true)
+    installExternalOpenIntentHandler(
+      {
+        children,
+        onIntent: router.onLocal.bind(router),
+      } as unknown as Shell,
+      { open },
+    )
+
+    await router.handleInbound(
+      'child',
+      message('https://connect.nango.dev/session', 'forged-sibling'),
+      'physical-child',
+    )
+
+    expect(open).toHaveBeenCalledTimes(1)
+    expect(sent).toEqual([
+      {
+        windowId: 'physical-child',
+        message: expect.objectContaining({
+          envelope: expect.objectContaining({
+            payload: { correlationId: 'request-1', result: { outcome: 'opened' } },
+          }),
+        }),
+      },
+    ])
+
+    for (const denied of [
+      'http://connect.nango.dev/session',
+      'https://sub.connect.nango.dev/session',
+      'https://connect.nango.dev:444/session',
+      'https://evil.example/session',
+    ]) {
+      await router.handleInbound('child', message(denied), 'physical-child')
+    }
+    await router.handleInbound('child', message('https://connect.nango.dev/session'), 'ungranted')
+    expect(open).toHaveBeenCalledTimes(1)
+    expect(sent).toHaveLength(1)
+  })
+
+  test('reports a popup block through the admitted pipeline', async () => {
+    const sent = mock((_windowId: string, _message: unknown) => undefined)
+    const children = {
+      send: sent,
+      has: () => true,
+      on: () => () => undefined,
+      onClose: () => () => undefined,
+    } as ChildrenChannel
+    const pipeline = createIntentPipeline()
+    pipeline.use(
+      capabilitiesMiddleware({
+        lookup: () => viewHostCapabilities(['https://connect.nango.dev']),
+      }),
+    )
+    const router = createIntentRouter({ selfWindowId: 'root', pipeline, parent: null, children })
+    installExternalOpenIntentHandler(
+      { children, onIntent: router.onLocal.bind(router) } as unknown as Shell,
+      { open: () => false },
+    )
+
+    await router.handleInbound('child', message('https://connect.nango.dev/session'), 'child-1')
+
+    expect(sent).toHaveBeenCalledWith(
+      'child-1',
+      expect.objectContaining({
+        envelope: expect.objectContaining({
+          payload: { correlationId: 'request-1', result: { outcome: 'blocked' } },
+        }),
+      }),
+    )
+  })
+
+  test('isolates a fresh inert context before navigating and closes it when isolation fails', () => {
+    const replace = mock((_url: string) => undefined)
+    const opened = { opener: {}, location: { replace }, close: mock(() => undefined) }
+    const open = mock(() => opened)
+
+    expect(
+      openExternalBrowserWindow({ open } as never, {
+        url: 'https://connect.nango.dev/session',
+        mode: 'popup',
+      }),
+    ).toBe(true)
+    expect(open).toHaveBeenCalledWith('', '_blank', 'popup,width=720,height=760')
+    expect(opened.opener).toBeNull()
+    expect(replace).toHaveBeenCalledWith('https://connect.nango.dev/session')
+
+    const close = mock(() => undefined)
+    const unsafe = Object.defineProperty({ close, location: { replace: mock() } }, 'opener', {
+      set: () => {
+        throw new Error('opener isolation refused')
+      },
+    })
+    expect(
+      openExternalBrowserWindow({ open: () => unsafe } as never, {
+        url: 'https://connect.nango.dev/session',
+        mode: 'tab',
+      }),
+    ).toBe(false)
+    expect(close).toHaveBeenCalledTimes(1)
+  })
+})
+
+function message(url: string, sender = 'child-1'): ExternalOpenIntentMessage {
+  return {
+    type: 'intent',
+    version: 1,
+    envelope: {
+      name: 'browser.openExternal',
+      payload: { url, mode: 'popup' },
+      sender: { windowId: sender },
+      correlationId: 'request-1',
+    },
+  }
+}

package/src/lib/__tests__/view-external-open-origins.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, test } from 'bun:test'
+
+import { admitExternalOpenOrigins } from '../view/external-open-origins'
+
+describe('View external navigation grants', () => {
+  test('defaults to no authority and canonicalizes exact HTTPS origins', () => {
+    expect(admitExternalOpenOrigins(undefined)).toEqual([])
+    expect(
+      admitExternalOpenOrigins([
+        'https://connect.nango.dev',
+        'https://connect.nango.dev/',
+        'https://connect.composio.dev:443',
+      ]),
+    ).toEqual(['https://connect.nango.dev', 'https://connect.composio.dev'])
+  })
+
+  test.each([
+    'http://connect.nango.dev',
+    'https://user@connect.nango.dev',
+    'https://connect.nango.dev/path',
+    'https://connect.nango.dev?session=secret',
+    'https://*.example.com',
+    'not-a-url',
+  ])('rejects a non-origin grant: %s', (candidate) => {
+    expect(() => admitExternalOpenOrigins([candidate])).toThrow('exact HTTPS origin')
+  })
+})

package/src/lib/__tests__/view-server.test.ts

@@ -60,12 +60,20 @@ describe('view session server credentials', () => {
         issuer: 'https://kernel.test',
         direct: true,
       },
+      externalOrigins: ['https://connect.nango.dev'],
       idleMs: 60_000,
     } satisfies ViewServeConfig
     const server = startViewServer(config)
     await once(server, 'listening')
 
     try {
+      const configResponse = await fetch(`http://127.0.0.1:${port}/s/${nonce}/config.json`)
+      expect(configResponse.status).toBe(200)
+      expect(await configResponse.json()).toMatchObject({
+        sessionId: 'v-plain',
+        externalOrigins: ['https://connect.nango.dev'],
+      })
+
       const response = await fetch(`http://127.0.0.1:${port}/s/${nonce}/token`, {
         method: 'POST',
       })

package/src/lib/__tests__/view-session.test.ts

@@ -69,6 +69,7 @@ describe('view session private state', () => {
         issuer: 'https://kernel.test',
         direct: true,
       },
+      externalOrigins: [],
       idleMs: 60_000,
     } satisfies ViewServeConfig
 

package/src/lib/update.ts

@@ -231,9 +231,40 @@ async function realpathIfExists(path: string): Promise<string | undefined> {
 export async function writeInstallMetadata(
   meta: InstallMetadata,
   path = INSTALL_PATH,
+  filesystem: Pick<CohortFilesystem, 'mkdir' | 'rename' | 'rm'> &
+    Pick<typeof import('node:fs/promises'), 'writeFile'> = { mkdir, rename, rm, writeFile },
 ): Promise<void> {
-  await mkdir(dirname(path), { recursive: true })
-  await writeFile(path, JSON.stringify(meta, null, 2) + '\n')
+  const staged = `${path}.next`
+  const previous = `${path}.previous`
+  await filesystem.mkdir(dirname(path), { recursive: true })
+  await filesystem.rm(staged, { force: true })
+  await filesystem.rm(previous, { force: true })
+  await filesystem.writeFile(staged, JSON.stringify(meta, null, 2) + '\n')
+
+  let backedUp = false
+  try {
+    try {
+      await filesystem.rename(path, previous)
+      backedUp = true
+    } catch (error) {
+      if (!isMissingFile(error)) throw error
+    }
+    await filesystem.rename(staged, path)
+    await filesystem.rm(previous, { force: true })
+  } catch (error) {
+    const rollback: unknown[] = []
+    if (backedUp) {
+      await filesystem.rename(previous, path).catch((failure) => rollback.push(failure))
+    }
+    await filesystem.rm(staged, { force: true }).catch((failure) => rollback.push(failure))
+    if (rollback.length > 0) {
+      throw new AggregateError(
+        [error, ...rollback],
+        'Install metadata update and rollback both failed.',
+      )
+    }
+    throw error
+  }
 }
 
 export function releaseBase(
@@ -258,7 +289,127 @@ export function shouldUpdate(currentVersion: string, manifestVersion: string): b
   return currentVersion !== manifestVersion
 }
 
-export async function updateAstrale(req: UpdateRequest): Promise<UpdateResult> {
+interface CohortFilesystem {
+  readonly chmod: typeof chmod
+  readonly copyFile: typeof copyFile
+  readonly mkdir: typeof mkdir
+  readonly rename: typeof rename
+  readonly rm: typeof rm
+}
+
+const defaultCohortFilesystem: CohortFilesystem = { chmod, copyFile, mkdir, rename, rm }
+
+export interface StandaloneCohortReplacement {
+  readonly finalize: () => Promise<void>
+  readonly rollback: () => Promise<void>
+}
+
+/** Replace the standalone executable and its Viewer as one rollback-safe cohort. */
+export async function replaceStandaloneCohort(
+  installedBinary: string,
+  nextBinary: string,
+  nextViewerDist: string,
+  filesystem: Partial<CohortFilesystem> = {},
+): Promise<StandaloneCohortReplacement> {
+  const fs = { ...defaultCohortFilesystem, ...filesystem }
+  const binDirectory = dirname(installedBinary)
+  const previousBinary = `${installedBinary}.previous`
+  const stagedBinary = `${installedBinary}.next`
+  const viewer = join(binDirectory, 'viewer')
+  const previousViewer = join(binDirectory, 'viewer.previous')
+  const stagedViewer = join(binDirectory, 'viewer.next')
+  const stagedViewerDist = join(stagedViewer, 'dist')
+
+  try {
+    await fs.rm(stagedViewer, { recursive: true, force: true })
+    await fs.mkdir(stagedViewerDist, { recursive: true })
+    await fs.copyFile(join(nextViewerDist, 'main.js'), join(stagedViewerDist, 'main.js'))
+    await fs.copyFile(join(nextViewerDist, 'index.html'), join(stagedViewerDist, 'index.html'))
+    await fs.copyFile(installedBinary, previousBinary)
+    await fs.copyFile(nextBinary, stagedBinary)
+    await fs.chmod(stagedBinary, 0o755)
+  } catch (error) {
+    await fs.rm(stagedViewer, { recursive: true, force: true }).catch(() => undefined)
+    await fs.rm(stagedBinary, { force: true }).catch(() => undefined)
+    throw error
+  }
+
+  await fs.rm(previousViewer, { recursive: true, force: true })
+  let viewerBackedUp = false
+  let viewerCommitted = false
+  let binaryCommitted = false
+  try {
+    try {
+      await fs.rename(viewer, previousViewer)
+      viewerBackedUp = true
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+    }
+    await fs.rename(stagedViewer, viewer)
+    viewerCommitted = true
+    await fs.rename(stagedBinary, installedBinary)
+    binaryCommitted = true
+  } catch (error) {
+    const rollback: unknown[] = []
+    if (binaryCommitted) {
+      await fs.copyFile(previousBinary, installedBinary).catch((failure) => rollback.push(failure))
+      await fs.chmod(installedBinary, 0o755).catch((failure) => rollback.push(failure))
+    }
+    if (viewerCommitted) {
+      await fs
+        .rm(viewer, { recursive: true, force: true })
+        .catch((failure) => rollback.push(failure))
+    }
+    if (viewerBackedUp) {
+      await fs.rename(previousViewer, viewer).catch((failure) => rollback.push(failure))
+    }
+    if (rollback.length > 0) {
+      throw new AggregateError([error, ...rollback], 'Standalone update and rollback both failed.')
+    }
+    throw error
+  } finally {
+    await fs.rm(stagedViewer, { recursive: true, force: true }).catch(() => undefined)
+    await fs.rm(stagedBinary, { force: true }).catch(() => undefined)
+  }
+
+  let settled = false
+  return Object.freeze({
+    finalize: async () => {
+      if (settled) return
+      settled = true
+      await fs.rm(previousViewer, { recursive: true, force: true }).catch(() => undefined)
+    },
+    rollback: async () => {
+      if (settled) return
+      settled = true
+      const rollback: unknown[] = []
+      await fs.copyFile(previousBinary, installedBinary).catch((failure) => rollback.push(failure))
+      await fs.chmod(installedBinary, 0o755).catch((failure) => rollback.push(failure))
+      await fs
+        .rm(viewer, { recursive: true, force: true })
+        .catch((failure) => rollback.push(failure))
+      if (viewerBackedUp) {
+        await fs.rename(previousViewer, viewer).catch((failure) => rollback.push(failure))
+      }
+      if (rollback.length > 0) {
+        throw new AggregateError(rollback, 'Standalone update rollback failed.')
+      }
+    },
+  })
+}
+
+interface UpdateDependencies {
+  readonly replaceStandaloneCohort: typeof replaceStandaloneCohort
+  readonly writeInstallMetadata: typeof writeInstallMetadata
+}
+
+const defaultUpdateDependencies = Object.freeze({ replaceStandaloneCohort, writeInstallMetadata })
+
+export async function updateAstrale(
+  req: UpdateRequest,
+  dependencies: Partial<UpdateDependencies> = {},
+): Promise<UpdateResult> {
+  const update = { ...defaultUpdateDependencies, ...dependencies }
   const execution = req.execution ?? detectUpdateExecution()
   if (execution.kind === 'package-managed') {
     return {
@@ -320,25 +471,33 @@ export async function updateAstrale(req: UpdateRequest): Promise<UpdateResult> {
 
     await extractTarGz(archive, tmp)
     const nextBin = join(tmp, 'astrale')
+    const nextViewer = join(tmp, 'viewer', 'dist')
     await chmod(nextBin, 0o755)
     await smokeVersion(nextBin, manifest.binaryVersion ?? manifest.version)
 
-    const previous = `${meta.bin}.previous`
-    const staged = `${meta.bin}.next`
-    await copyFile(meta.bin, previous).catch(() => undefined)
-    await copyFile(nextBin, staged)
-    await chmod(staged, 0o755)
-    await rename(staged, meta.bin)
-
-    await writeInstallMetadata(
-      {
-        ...meta,
-        channel: manifest.channel,
-        version: manifest.version,
-        installedAt: new Date().toISOString(),
-      },
-      req.installPath,
-    )
+    const replacement = await update.replaceStandaloneCohort(meta.bin, nextBin, nextViewer)
+    try {
+      await update.writeInstallMetadata(
+        {
+          ...meta,
+          channel: manifest.channel,
+          version: manifest.version,
+          installedAt: new Date().toISOString(),
+        },
+        req.installPath,
+      )
+    } catch (error) {
+      try {
+        await replacement.rollback()
+      } catch (rollbackError) {
+        throw new AggregateError(
+          [error, rollbackError],
+          'Standalone update metadata commit and cohort rollback both failed.',
+        )
+      }
+      throw error
+    }
+    await replacement.finalize()
 
     return {
       status: 'updated',

package/src/lib/view/assets.ts

@@ -8,7 +8,11 @@ import { fileURLToPath } from 'node:url'
  * (`<pkg>/viewer/dist`). The module URL is authoritative because npm global
  * installs expose the CLI through a bin symlink outside the package root.
  */
-export function viewerDistDir(moduleUrl = import.meta.url, entry = process.argv[1] ?? '.'): string {
+export function viewerDistDir(
+  moduleUrl = import.meta.url,
+  entry = process.argv[1] ?? '.',
+  executable = process.execPath,
+): string {
   const override = process.env.ASTRALE_VIEWER_DIR
   if (override) return override
 
@@ -16,7 +20,12 @@ export function viewerDistDir(moduleUrl = import.meta.url, entry = process.argv[
   const published = join(moduleDirectory, '..', 'viewer', 'dist')
   const source = join(moduleDirectory, '..', '..', '..', 'viewer', 'dist')
   const legacy = join(dirname(entry), '..', 'viewer', 'dist')
-  const complete = [published, source, legacy].find(hasViewerBundle)
+  const standalone = entry.startsWith('/$bunfs/')
+    ? join(dirname(executable), 'viewer', 'dist')
+    : undefined
+  const complete = [standalone, published, source, legacy].find(
+    (candidate): candidate is string => candidate !== undefined && hasViewerBundle(candidate),
+  )
   if (complete) return complete
 
   // A source checkout may intentionally omit generated dist assets. Keep the

package/src/lib/view/external-open-intent.ts

@@ -0,0 +1,41 @@
+import type { ExternalOpenRequest, IntentMessage, Shell } from '@astrale-os/shell'
+
+import { replyToIntent } from '@astrale-os/shell'
+
+export interface ExternalOpenIntentHost {
+  open(request: ExternalOpenRequest): boolean
+}
+
+/** Register the root host's browser-owned external navigation effect. */
+export function installExternalOpenIntentHandler(
+  shell: Shell,
+  host: ExternalOpenIntentHost,
+): () => void {
+  return shell.onIntent('browser.openExternal', (message) => {
+    const opened = host.open(message.envelope.payload)
+    replyToIntent(shell.children, message.envelope.sender.windowId, message, {
+      outcome: opened ? 'opened' : 'blocked',
+    })
+  })
+}
+
+/** Open an external document without retaining a cross-origin opener capability. */
+export function openExternalBrowserWindow(
+  browser: Pick<Window, 'open'>,
+  request: ExternalOpenRequest,
+): boolean {
+  const popup = request.mode === 'popup'
+  const opened = browser.open('', '_blank', popup ? 'popup,width=720,height=760' : undefined)
+  if (opened === null) return false
+  try {
+    opened.opener = null
+    if (opened.opener !== null) throw new Error('Browser retained the opener capability.')
+    opened.location.replace(request.url)
+  } catch {
+    opened.close()
+    return false
+  }
+  return true
+}
+
+export type ExternalOpenIntentMessage = IntentMessage<'browser.openExternal'>

package/src/lib/view/external-open-origins.ts

@@ -0,0 +1,37 @@
+import { AstraleError } from '../../errors.js'
+
+/** Admit exact HTTPS origins explicitly granted by the CLI operator. */
+export function admitExternalOpenOrigins(input: readonly string[] | undefined): readonly string[] {
+  if (input === undefined) return Object.freeze([])
+  const admitted = new Set<string>()
+  for (const candidate of input) {
+    let url: URL
+    try {
+      url = new URL(candidate)
+    } catch (cause) {
+      throw invalidExternalOrigin(candidate, cause)
+    }
+    if (
+      url.protocol !== 'https:' ||
+      url.hostname.includes('*') ||
+      url.username !== '' ||
+      url.password !== '' ||
+      url.pathname !== '/' ||
+      url.search !== '' ||
+      url.hash !== ''
+    ) {
+      throw invalidExternalOrigin(candidate)
+    }
+    admitted.add(url.origin)
+  }
+  return Object.freeze([...admitted])
+}
+
+function invalidExternalOrigin(candidate: string, cause?: unknown): AstraleError {
+  return new AstraleError(
+    'INVALID_EXTERNAL_ORIGIN',
+    `External navigation grant "${candidate}" is not an exact HTTPS origin.`,
+    'Pass an origin such as https://connect.example.com with no credentials, path, query, or fragment.',
+    cause === undefined ? undefined : { cause },
+  )
+}

package/src/lib/view/host-capabilities.ts

@@ -0,0 +1,17 @@
+import type { HostCapabilities } from '@astrale-os/shell'
+
+import { admitHostCapabilities } from '@astrale-os/shell'
+
+/** Build the exact host grant handed to a CLI-hosted View session. */
+export function viewHostCapabilities(externalOrigins: readonly string[]): HostCapabilities {
+  return admitHostCapabilities({
+    version: 1,
+    navigation: {
+      openView: {},
+      ...(externalOrigins.length === 0 ? {} : { external: { origins: externalOrigins } }),
+    },
+    actions: {},
+    browser: {},
+    access: {},
+  })
+}

package/src/lib/view/server.ts

@@ -101,6 +101,7 @@ export function startViewServer(config: ViewServeConfig): Server {
         identity: session.identity ?? null,
         instance: session.instance ?? null,
         sessionId: session.id,
+        externalOrigins: config.externalOrigins,
       })
       return
     }

package/src/lib/view/session.ts

@@ -41,6 +41,8 @@ export type ViewServeConfig = {
    * handles CORS and self-signed local CAs.
    */
   proxy: { kernelUrl: string; issuer: string; caFile?: string; direct: boolean }
+  /** Exact HTTPS origins the operator consented to open from this View session. */
+  externalOrigins: readonly string[]
   idleMs: number
 }
 

package/src/program/__tests__/program.test.ts

@@ -195,7 +195,7 @@ describe('program composition', () => {
       'whoami',
     ])
     expect(createHash('sha256').update(JSON.stringify(surface)).digest('hex')).toBe(
-      '958b54c4eeee1bab77efeac734bd11fe5a0b103aae69788de7db5418e5652f64',
+      '51546dd7ea5cbf25efbd41f0cd09ceb480abad5be489fc16743500a18e3a02c6',
     )
   })
 

package/studio/package.json

@@ -21,8 +21,8 @@
     "typecheck": "tsgo --noEmit"
   },
   "dependencies": {
-    "@astrale-os/sdk": "0.5.0-beta.49",
-    "@astrale-os/shell": "0.4.2-beta.3",
+    "@astrale-os/sdk": "0.5.0-beta.50",
+    "@astrale-os/shell": "0.4.2-beta.5",
     "@dagrejs/dagre": "^3.0.0",
     "@radix-ui/react-collapsible": "^1.1.0",
     "@radix-ui/react-dialog": "^1.1.6",