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

package/src/lib/provision-instance.ts

@@ -9,12 +9,10 @@ import { createOwnedInstance } from './admin-instance'
 import { setActive, upsertManagedBookmark } from './instance'
 import { withSpinner } from './log'
 import { isMachine } from './output'
-import { promptSelect } from './prompt'
 import { validateSlug } from './validation'
 
 export type ProvisionOpts = KernelCommandOpts &
   AdminTargetCommandOpts & {
-    hostId?: string
     // Global flags (program.ts) that force non-interactive — mirrors `instance use`.
     ci?: boolean
     noPrompt?: boolean
@@ -35,10 +33,10 @@ export type ProvisionResult = {
 const SAGA_TIMEOUT_MS = '240000'
 
 /**
- * Provision an alpha instance through the admin kernel, then bookmark it and
+ * Provision an instance through the admin kernel, then bookmark it and
  * make it the active target. Extracted from `instance create` so `astrale
- * setup` provisions through the exact same saga (auth assertion → alphaCreate →
- * bookmark → set-active), including the interactive multi-host picker.
+ * setup` provisions through the exact same saga (auth assertion → create →
+ * bookmark → set-active).
  *
  * Presentation is deliberately minimal here (a spinner + a one-line success);
  * the caller renders anything richer — `setup` follows this with a hero panel.
@@ -48,15 +46,10 @@ export async function provisionInstance(
   opts: ProvisionOpts,
 ): Promise<ProvisionResult> {
   validateSlug(slug)
-  await assertAlphaCreateAuth(opts)
-  // The created instance must belong to the LOGGED-IN identity — never to an
-  // identity pinned on the admin bookmark (that mismatch silently made a fresh
-  // user's instance unusable). `--as` still wins.
-  if (!opts.as) opts = { ...opts, as: (await readIdentities()).default }
+  const authentication = await instanceCreateAuthentication(opts)
+  opts = authentication.opts
 
   const machine = isMachine(opts)
-  const interactive = !!process.stdin.isTTY && !(opts.ci || opts.noPrompt || process.env.CI)
-
   let repointedFrom: string | undefined
   let selectionError: unknown = null
   // The global 30s default doesn't just fail the CLIENT: the disconnect kills
@@ -65,21 +58,24 @@ export async function provisionInstance(
   // timeout; an explicit --timeout still wins.
   const createOpts = { ...opts, timeout: opts.timeout ?? SAGA_TIMEOUT_MS }
 
-  const runProvision = (hostId: string | undefined) =>
+  const runProvision = () =>
     withSpinner(
       `Provisioning instance ${slug}`,
       !machine,
       async () => {
-        const created = await createOwnedInstance(createOpts, slug, hostId)
+        const created = await createOwnedInstance(createOpts, slug)
         try {
           // Org id from the create response — authoritative for token scoping
           // (the router's /auth/org is eventually consistent).
-          const bookmarked = await upsertManagedBookmark(
-            slug,
+          const bookmarked = await upsertManagedBookmark({
+            key: slug,
             slug,
-            created.url,
-            created.organizationId,
-          )
+            url: created.url,
+            ...(created.organizationId ? { organizationId: created.organizationId } : {}),
+            ...(authentication.defaultIdentity
+              ? { defaultIdentity: authentication.defaultIdentity }
+              : {}),
+          })
           repointedFrom = bookmarked.repointedFrom
           await setActive(slug)
         } catch (e) {
@@ -93,23 +89,7 @@ export async function provisionInstance(
       },
     )
 
-  // Host placement is chosen SERVER-side (the caller's ready + USE-granted
-  // hosts). We recover ONLY from its multi-host ambiguity: pop a picker and
-  // retry with the chosen host_id — the ambiguity error throws before any
-  // provisioning side effect, so the retry is clean. No host / permission /
-  // capacity / a non-interactive run all reject through to the caller's `fatal`,
-  // surfacing the server's own message plus the listed ids. An explicit
-  // `--host-id` skips all of this.
-  const created = await runProvision(opts.hostId).catch(async (e: unknown) => {
-    const hostIds = !opts.hostId && interactive ? parseEligibleHostIds(e) : null
-    if (!hostIds) throw e
-    const chosen = await promptSelect(
-      `${hostIds.length} hosts available — pick one to provision on`,
-      hostIds.map((hid) => ({ name: hid, value: hid })),
-    )
-    if (!chosen) throw e
-    return runProvision(chosen)
-  })
+  const created = await runProvision()
 
   // Warnings go to stderr so machine-readable stdout stays clean.
   const warn = (msg: string) => console.error(chalk.yellow('⚠'), msg)
@@ -124,31 +104,28 @@ export async function provisionInstance(
   return { created, slug, repointedFrom, ...(selectionError ? { selectionError } : {}) }
 }
 
-/**
- * Recover the eligible host ids from alphaCreate's multi-host error
- * ("N ready hosts are assigned (id1, id2). Specify host_id…") — only when
- * there's a real choice (>1). Returns null for any other error (no host,
- * permission, capacity). Deliberately coupled to that message wording (Option
- * B: no admin-side change); if it ever drifts we simply stop offering the
- * picker and the raw error is shown instead — no worse than before.
- */
-export function parseEligibleHostIds(error: unknown): string[] | null {
-  const text = error instanceof Error ? error.message : String(error)
-  const match = /ready hosts are assigned \(([^)]+)\)/.exec(text)
-  if (!match) return null
-  const ids = match[1]!
-    .split(',')
-    .map((s) => s.trim())
-    .filter(Boolean)
-  return ids.length > 1 ? ids : null
+async function instanceCreateAuthentication(opts: ProvisionOpts): Promise<{
+  readonly opts: ProvisionOpts
+  readonly defaultIdentity?: string
+}> {
+  if (opts.creds) return { opts }
+  const store = await readIdentities()
+  const defaultIdentity = selectInstanceCreateIdentity(store, opts)
+  return {
+    opts: opts.as ? opts : { ...opts, as: defaultIdentity },
+    defaultIdentity,
+  }
 }
 
-async function assertAlphaCreateAuth(opts: Pick<ProvisionOpts, 'as' | 'creds'>): Promise<void> {
-  if (opts.creds) return
-  assertAlphaCreateIdentity(await readIdentities(), opts)
+export function selectInstanceCreateIdentity(
+  store: IdentityStore,
+  opts: Pick<ProvisionOpts, 'as'> = {},
+): string {
+  assertInstanceCreateIdentity(store, opts)
+  return opts.as ?? store.default
 }
 
-export function assertAlphaCreateIdentity(
+export function assertInstanceCreateIdentity(
   store: IdentityStore,
   opts: Pick<ProvisionOpts, 'as'> = {},
 ): void {

package/src/lib/update.ts

@@ -1,5 +1,15 @@
 import { createHash } from 'node:crypto'
-import { chmod, copyFile, mkdir, mkdtemp, readFile, rename, rm, writeFile } from 'node:fs/promises'
+import {
+  chmod,
+  copyFile,
+  mkdir,
+  mkdtemp,
+  readFile,
+  realpath,
+  rename,
+  rm,
+  writeFile,
+} from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { z } from 'zod'
@@ -61,9 +71,26 @@ export type UpdateRequest = {
   currentVersion: string
   platform?: Platform
   installPath?: string
+  execution?: UpdateExecution
 }
 
+export type UpdateExecution =
+  | { kind: 'standalone'; executable: string }
+  | { kind: 'package-managed'; executable: string }
+
+const admittedScriptInstall = Symbol('admittedScriptInstall')
+export type AdmittedScriptInstall = Readonly<{
+  metadata: InstallMetadata
+  executable: string
+  [admittedScriptInstall]: true
+}>
+
 export type UpdateResult =
+  | {
+      status: 'managed'
+      currentVersion: string
+      executable: string
+    }
   | {
       status: 'up-to-date'
       currentVersion: string
@@ -106,50 +133,138 @@ export function platformKey(platform: Platform): string {
   return `${platform.os}-${platform.arch}`
 }
 
-/**
- * True when running as the Bun-compiled standalone binary (Linux/macOS), which
- * self-updates by swapping its own file. The Node/npm build does not expose
- * `process.versions.bun`; it is managed by the user's package manager instead.
- */
-function isStandaloneBinary(): boolean {
-  return Boolean((process.versions as { bun?: string }).bun)
+export function classifyUpdateExecution(input: {
+  bunVersion?: string
+  executable: string
+  entry?: string
+}): UpdateExecution {
+  return input.bunVersion && input.entry?.startsWith('/$bunfs/')
+    ? { kind: 'standalone', executable: input.executable }
+    : { kind: 'package-managed', executable: input.executable }
+}
+
+export function detectUpdateExecution(): UpdateExecution {
+  return classifyUpdateExecution({
+    bunVersion: (process.versions as { bun?: string }).bun,
+    executable: process.execPath,
+    entry: process.argv[1],
+  })
+}
+
+export function packageManagedUpdateError(executable: string): AstraleError {
+  return new AstraleError(
+    'UPDATE_PACKAGE_MANAGED',
+    'This Astrale build is managed by your package manager.',
+    `Active binary: ${executable}. Update it with npm, pnpm, or bun; or put the official script installation first on PATH.`,
+  )
 }
 
 export async function readInstallMetadata(path = INSTALL_PATH): Promise<InstallMetadata> {
   let raw: string
   try {
     raw = await readFile(path, 'utf8')
-  } catch {
-    throw isStandaloneBinary()
-      ? new AstraleError(
-          'UPDATE_NOT_SCRIPT_INSTALLED',
-          'Astrale was not installed by the official install script.',
-          'Reinstall with: curl -fsSL https://raw.githubusercontent.com/astrale-os/cli/main/install.sh | sh',
-        )
-      : new AstraleError(
-          'UPDATE_PACKAGE_MANAGED',
-          'This Astrale build is managed by your package manager.',
-          'Update with: npm install -g @astrale-os/cli@latest  (or pnpm/bun)',
-        )
+  } catch (error) {
+    if (!isMissingFile(error)) throw error
+    throw new AstraleError(
+      'UPDATE_NOT_SCRIPT_INSTALLED',
+      'Astrale was not installed by the official install script.',
+      'Reinstall with: curl -fsSL https://raw.githubusercontent.com/astrale-os/cli/main/install.sh | sh',
+    )
   }
 
-  const parsed = InstallMetadataSchema.safeParse(JSON.parse(raw))
+  let decoded: unknown
+  try {
+    decoded = JSON.parse(raw)
+  } catch {
+    throw badInstallMetadata(path)
+  }
+  const parsed = InstallMetadataSchema.safeParse(decoded)
   if (!parsed.success) {
+    throw badInstallMetadata(path)
+  }
+  return parsed.data
+}
+
+function isMissingFile(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && 'code' in error && error.code === 'ENOENT'
+}
+
+function badInstallMetadata(path: string): AstraleError {
+  return new AstraleError(
+    'UPDATE_BAD_INSTALL_METADATA',
+    `Invalid install metadata at ${path}.`,
+    'Reinstall with: curl -fsSL https://raw.githubusercontent.com/astrale-os/cli/main/install.sh | sh',
+  )
+}
+
+export async function admitScriptInstall(
+  meta: InstallMetadata,
+  execution: Extract<UpdateExecution, { kind: 'standalone' }>,
+): Promise<AdmittedScriptInstall> {
+  const [running, recorded] = await Promise.all([
+    realpathIfExists(execution.executable),
+    realpathIfExists(meta.bin),
+  ])
+  if (running === undefined || recorded === undefined || running !== recorded) {
     throw new AstraleError(
-      'UPDATE_BAD_INSTALL_METADATA',
-      `Invalid install metadata at ${path}.`,
-      'Reinstall with: curl -fsSL https://raw.githubusercontent.com/astrale-os/cli/main/install.sh | sh',
+      'UPDATE_INSTALL_MISMATCH',
+      'The running Astrale binary does not own the recorded script installation.',
+      `Running binary: ${execution.executable}; recorded binary: ${meta.bin}. Refusing to replace a different installation.`,
     )
   }
-  return parsed.data
+  return Object.freeze({
+    metadata: meta,
+    executable: running,
+    [admittedScriptInstall]: true as const,
+  })
+}
+
+async function realpathIfExists(path: string): Promise<string | undefined> {
+  try {
+    return await realpath(path)
+  } catch (error) {
+    if (isMissingFile(error)) return undefined
+    throw error
+  }
 }
 
 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(
@@ -174,8 +289,138 @@ export function shouldUpdate(currentVersion: string, manifestVersion: string): b
   return currentVersion !== manifestVersion
 }
 
-export async function updateAstrale(req: UpdateRequest): Promise<UpdateResult> {
-  const meta = await readInstallMetadata(req.installPath)
+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 {
+      status: 'managed',
+      currentVersion: req.currentVersion,
+      executable: execution.executable,
+    }
+  }
+
+  const install = await admitScriptInstall(await readInstallMetadata(req.installPath), execution)
+  const meta = install.metadata
   const currentVersion = meta.version ?? req.currentVersion
   const channel = req.channel ?? meta.channel ?? DEFAULT_UPDATE_CHANNEL
   const platform = req.platform ?? detectPlatform()
@@ -226,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/validation.ts

@@ -1,4 +1,4 @@
-import { isDnsLabel } from '@astrale-os/sdk/domain'
+import { isDnsLabel } from '@astrale-os/sdk/value'
 import { z } from 'zod'
 
 import { ReservedSlugError } from '../errors'
@@ -21,7 +21,7 @@ export function validateName(name: string, entity: string): void {
 }
 
 export function validateSlug(slug: string): void {
-  // Canonical DNS-label rule (`@astrale-os/sdk/domain`): a slug becomes a
+  // Canonical Core DNS-label rule: a slug becomes a
   // hostname label, so reject anything not DNS-safe (§4.7).
   if (!slug || !isDnsLabel(slug)) {
     throw new Error(

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 },
+  )
+}