@specbook/ui 0.1.0 → 0.2.0

package/src/engine.ts

@@ -3,10 +3,13 @@ import {
   type AuthProfile,
   createFetchTransport,
   createMockTransport,
+  type DiscoveredEndpoints,
   deepMerge,
   type Example,
   installFaker,
+  isDiscovery,
   type OpMeta,
+  parseDiscovery,
   prepareFaker,
   type RequestDef,
   type RunEvent,
@@ -22,6 +25,17 @@ import { type ExtensionBridge, extensionTransport } from './extension'
 import { absoluteBase, routingTransport, withPageSecrets } from './routing'
 import { originOf, type SecretStore, secretStore } from './secrets'
 
+/**
+ * The reserved service name a sign-in's token exchange is addressed to. The dev server's proxy answers
+ * `auth:<profile>` from the profile's own `oauth.tokenUrl` (the same prefix lives in `@specbook/vite`).
+ */
+const AUTH_SERVICE_PREFIX = 'auth:'
+const authService = (profile: string) => `${AUTH_SERVICE_PREFIX}${encodeURIComponent(profile)}`
+/** Likewise for an OpenID Connect discovery document, whose host may differ from the token endpoint's. */
+const DISCOVERY_SERVICE_PREFIX = 'discovery:'
+const discoveryService = (profile: string) =>
+  `${DISCOVERY_SERVICE_PREFIX}${encodeURIComponent(profile)}`
+
 export interface ExampleEntry {
   name: string
   source: 'generated' | 'project'
@@ -108,6 +122,17 @@ export function createEngine(reg: Registry, opts: EngineOptions = {}) {
     return out
   }
 
+  /** One line per environment that has a description, for the pickers' tooltips. */
+  async function environmentNotes(version: number): Promise<Record<string, string>> {
+    const c = await config(version)
+    const out: Record<string, string> = {}
+    for (const [name, e] of Object.entries(c.environments ?? {})) {
+      const note = (e as { description?: string } | undefined)?.description
+      if (note) out[name] = note
+    }
+    return out
+  }
+
   async function environments(version: number): Promise<string[]> {
     const c = await config(version)
     const envs = new Set<string>(['mock'])
@@ -147,12 +172,19 @@ export function createEngine(reg: Registry, opts: EngineOptions = {}) {
    * One transport per run, routing each request by its service (`routeFor`). Typed values are bound to
    * the API's origin first; placeholders left over are filled by the dev server or reported as missing.
    */
-  async function transportFor(env: string, proxyBase: string, version: number): Promise<Transport> {
+  async function transportFor(
+    env: string,
+    proxyBase: string,
+    version: number,
+    /** extra services by name -> base URL: a sign-in's token endpoint, which is not a configured service */
+    extra: Record<string, string> = {},
+  ): Promise<Transport> {
     if (env === 'mock') return createMockTransport({ loader: mockLoader })
     const cfg = await config(version)
     const pageHref = globalThis.location?.href
     const pageOrigin = globalThis.location?.origin
     const baseOf = (service: string) => {
+      if (extra[service]) return extra[service]
       const url = cfg.services?.[service]?.baseUrl?.[env]
       if (!url) throw new Error(`No base URL for ${service} in the "${env}" environment`)
       return absoluteBase(url, pageHref)
@@ -194,6 +226,14 @@ export function createEngine(reg: Registry, opts: EngineOptions = {}) {
           return await inner(req, signal)
         } catch (e) {
           // a blocked cross-origin call surfaces as a bare TypeError("Failed to fetch")
+          if (
+            e instanceof TypeError &&
+            (req.service.startsWith(AUTH_SERVICE_PREFIX) ||
+              req.service.startsWith(DISCOVERY_SERVICE_PREFIX))
+          )
+            throw new Error(
+              `The browser could not reach the sign-in provider (${extra[req.service] ?? 'unknown'}). It probably does not allow calls from this page (CORS). Embedding the viewer on the API's origin does not help when the sign-in server is on another host; the browser extension can make the call. You can still paste an access token.`,
+            )
           if (e instanceof TypeError)
             throw new Error(
               `The browser could not reach ${req.service} in "${env}". The API probably does not allow calls from this page (CORS). It works when the viewer runs on the API's own origin: embed it in the API's docs route ("Embed the viewer" in the README). Mock data keeps working.`,
@@ -219,6 +259,105 @@ export function createEngine(reg: Registry, opts: EngineOptions = {}) {
     }
   }
 
+  type SignInEndpoints = DiscoveredEndpoints & { scopes: Record<string, string> }
+  const discovered = new Map<string, Promise<DiscoveredEndpoints>>()
+
+  /**
+   * Where a profile signs in: the endpoints its config writes out, or the ones its OpenID Connect
+   * discovery document names. The document is fetched the way any other call from the page is (through
+   * the dev server's proxy when there is one) and remembered for the life of the page.
+   */
+  async function oauthEndpoints(i: {
+    env: string
+    version: number
+    profile: string
+    proxyBase?: string
+    signal?: AbortSignal
+  }): Promise<SignInEndpoints> {
+    if (i.env === 'mock') throw new Error('Sign in needs a live environment, not mock')
+    const oauth = ((await config(i.version)).auth?.[i.profile] as AuthProfile | undefined)?.oauth
+    if (!oauth) throw new Error(`"${i.profile}" has no sign-in configured`)
+    if (!isDiscovery(oauth))
+      return {
+        authorizationUrl: oauth.authorizationUrl,
+        tokenUrl: oauth.tokenUrl,
+        scopes: oauth.scopes ?? {},
+      }
+
+    const url = new URL(oauth.openIdConnectUrl)
+    let found = discovered.get(url.href)
+    if (!found) {
+      found = (async () => {
+        const service = discoveryService(i.profile)
+        const send = await transportFor(i.env, i.proxyBase ?? '/__specbook/proxy', i.version, {
+          [service]: url.origin,
+        })
+        const res = await send(
+          {
+            service,
+            opId: 'oidc-discovery',
+            method: 'GET',
+            url: url.pathname,
+            query: Object.fromEntries(url.searchParams),
+            headers: { accept: 'application/json' },
+            encoding: 'none',
+          },
+          i.signal,
+        )
+        if (res.status >= 400)
+          throw new Error(`The provider's discovery document answered ${res.status}`)
+        return parseDiscovery(res.body)
+      })()
+      discovered.set(url.href, found)
+      // a failure is not remembered: the next click tries again
+      found.catch(() => discovered.delete(url.href))
+    }
+    const endpoints = await found
+    return {
+      ...endpoints,
+      scopes: oauth.scopes && Object.keys(oauth.scopes).length ? oauth.scopes : endpoints.scopes,
+    }
+  }
+
+  /**
+   * A sign-in's code exchange, sent the way any other call from this page is: through the dev server's
+   * proxy when there is one, else direct or through the extension. The token endpoint comes from the
+   * profile in the config (or its discovery document), never from the caller, so the proxy only ever
+   * forwards to the project's own.
+   */
+  async function oauthExchange(i: {
+    env: string
+    version: number
+    profile: string
+    fields: Record<string, string>
+    proxyBase?: string
+    signal?: AbortSignal
+  }): Promise<unknown> {
+    const { tokenUrl } = await oauthEndpoints(i)
+    const token = new URL(tokenUrl)
+    const service = authService(i.profile)
+    const send = await transportFor(i.env, i.proxyBase ?? '/__specbook/proxy', i.version, {
+      [service]: token.origin,
+    })
+    const res = await send(
+      {
+        service,
+        opId: 'oauth-token',
+        method: 'POST',
+        url: token.pathname,
+        query: Object.fromEntries(token.searchParams),
+        headers: { accept: 'application/json' },
+        body: i.fields,
+        encoding: 'form',
+      },
+      i.signal,
+    )
+    const body = res.body as { error?: unknown } | undefined
+    if (res.status >= 400 && typeof body?.error !== 'string')
+      throw new Error(`The token endpoint answered ${res.status}`)
+    return res.body
+  }
+
   const norm = (p: string) => p.replace(/^\.\//, '')
 
   /** Display order: the author's examples first, generated ones last. */
@@ -400,7 +539,10 @@ export function createEngine(reg: Registry, opts: EngineOptions = {}) {
     config,
     environments,
     environmentRisks,
+    environmentNotes,
     managedSecrets,
+    oauthEndpoints,
+    oauthExchange,
     run,
     operationRequest,
     operationMeta,

package/src/main.tsx

@@ -1,5 +1,6 @@
 import { render } from 'preact'
 import { App } from './app'
+import { handleOAuthCallback } from './oauth-callback'
 import { applyTheme } from './theme'
 import 'prism-code-editor/layout.css'
 import 'prism-code-editor/autocomplete.css'
@@ -9,7 +10,14 @@ import './styles/app.css'
 import './styles/panel.css'
 
 applyTheme()
-render(<App />, document.getElementById('app') as HTMLElement)
+// A sign-in's return leg is handed to the tab that started it; this page then has nothing to draw. Under the
+// viewer shell or an embed (which import this) that was settled before they got here, and running it again
+// would strip a host page's own `?code=&state=` that the embed deliberately left alone.
+const underShell =
+  (globalThis as { __SPECBOOK_VIEWER__?: unknown }).__SPECBOOK_VIEWER__ !== undefined
+void (underShell ? Promise.resolve(false) : handleOAuthCallback()).then((handled) => {
+  if (!handled) render(<App />, document.getElementById('app') as HTMLElement)
+})
 
 if (import.meta.hot) {
   import.meta.hot.on('specbook:registry-changed', () => location.reload())

package/src/oauth-callback.ts

@@ -0,0 +1,87 @@
+/**
+ * The return leg of a sign-in. The identity provider redirects the popup to a page with `?code=&state=`
+ * (or `?error=`). Run first on boot: when the tab that started the sign-in is waiting for this `state`
+ * it takes the result and this popup closes without drawing the app.
+ *
+ * Two ways to reach the waiting tab, because each survives what the other does not:
+ * - a same-origin `BroadcastChannel`: providers that send `Cross-Origin-Opener-Policy` sever
+ *   `window.opener`, but a channel still connects the two pages;
+ * - `window.opener.postMessage`: a viewer inside an iframe on another site has partitioned storage, so its
+ *   channel never hears a top-level popup, but its window is still the popup's opener.
+ *
+ * A stray visit to a URL that merely looks like a callback is told nobody is waiting and carries on as a
+ * normal page load. The hosted site's own callback page (`landing/oauth/callback/callback.js`) does the same
+ * in plain JS; keep the two in step.
+ */
+export const OAUTH_CHANNEL = 'specbook-oauth'
+
+export type OAuthMessage =
+  | { type: 'callback'; state: string; code?: string; error?: string; description?: string }
+  | { type: 'ack'; state: string }
+
+/** How long a callback page waits to be told that someone is waiting for it. */
+const ACK_WAIT_MS = 1500
+
+export interface CallbackOptions {
+  /**
+   * Remove `?code=&state=` from the address even when no tab claims it (default). An embedded viewer sets
+   * this to false: the page belongs to someone else, and its query may be their own application's sign-in.
+   */
+  stripWhenUnclaimed?: boolean
+}
+
+/** true when this page load was a sign-in's return and has been handed over: do not boot the app. */
+export function handleOAuthCallback(options: CallbackOptions = {}): Promise<boolean> {
+  const strip = options.stripWhenUnclaimed ?? true
+  const here = globalThis.location
+  if (!here || (typeof BroadcastChannel === 'undefined' && !globalThis.opener))
+    return Promise.resolve(false)
+  const q = new URLSearchParams(here.search)
+  const state = q.get('state')
+  if (!state || !(q.has('code') || q.has('error'))) return Promise.resolve(false)
+
+  const message: OAuthMessage = {
+    type: 'callback',
+    state,
+    ...(q.get('code') ? { code: q.get('code') as string } : {}),
+    ...(q.get('error') ? { error: q.get('error') as string } : {}),
+    ...(q.get('error_description') ? { description: q.get('error_description') as string } : {}),
+  }
+  // the code and state are single-use and do not belong in history or a copied address
+  const clean = () => history.replaceState(null, '', here.pathname + here.hash)
+  if (strip) clean()
+
+  return new Promise((resolve) => {
+    const channel =
+      typeof BroadcastChannel === 'undefined' ? null : new BroadcastChannel(OAUTH_CHANNEL)
+    let finished = false
+    const finish = (handled: boolean) => {
+      if (finished) return
+      finished = true
+      clearTimeout(timer)
+      channel?.close()
+      removeEventListener('message', onMessage)
+      resolve(handled)
+    }
+    const claimed = () => {
+      if (finished) return
+      clean()
+      finish(true)
+      document.body.textContent = 'Signed in. You can close this window.'
+      window.close()
+    }
+    const isAck = (d: OAuthMessage | undefined) => d?.type === 'ack' && d.state === state
+    const onMessage = (e: MessageEvent<OAuthMessage>) => {
+      if (e.origin === here.origin && isAck(e.data)) claimed()
+    }
+    const timer = setTimeout(() => finish(false), ACK_WAIT_MS)
+    if (channel) channel.onmessage = (e: MessageEvent<OAuthMessage>) => isAck(e.data) && claimed()
+    addEventListener('message', onMessage)
+    channel?.postMessage(message)
+    try {
+      window.opener?.postMessage(message, here.origin)
+    } catch {
+      /* the opener is cross-origin or gone: the channel is the only way */
+    }
+  })
+}

package/src/oauth.ts

@@ -0,0 +1,194 @@
+import {
+  authorizeUrl,
+  createPkce,
+  newState,
+  OAuthError,
+  parseCallback,
+  parseTokenResponse,
+  tokenRequestFields,
+} from '@specbook/core'
+import { OAUTH_CHANNEL, type OAuthMessage } from './oauth-callback'
+
+/**
+ * Page side of "Sign in": opens the provider in a popup, waits for the return leg
+ * (`oauth-callback.ts`), exchanges the code and hands back the access token. The verifier and the `state`
+ * live in this closure only: not in the URL, not in storage, not in a log.
+ */
+
+/**
+ * The address a provider sends the person back to, and the one to register with it.
+ *
+ * The hosted site declares a stable, unversioned callback page (a `<meta>` its assembly adds to the viewer's
+ * `index.html`), so what people register does not change with the viewer's channel (`/v1/`, `/v2/`).
+ * Anywhere else (a self-hosted copy, an embed on a host page, the dev server) it is the page's own address.
+ */
+export const redirectUri = (): string => {
+  const declared = document
+    .querySelector<HTMLMetaElement>('meta[name="specbook-oauth-callback"]')
+    ?.content.trim()
+  if (declared) {
+    try {
+      return new URL(declared, location.origin).href
+    } catch {
+      /* not an address: fall back to the page's own */
+    }
+  }
+  return `${location.origin}${location.pathname}`
+}
+
+export interface SignInInput {
+  authorizationUrl: string
+  clientId: string
+  scopes: string[]
+  /** posts the form to the token endpoint and returns the parsed response body */
+  exchange(fields: Record<string, string>, signal?: AbortSignal): Promise<unknown>
+  signal?: AbortSignal
+  /** how long to wait for the person to finish (default five minutes) */
+  timeoutMs?: number
+}
+
+/**
+ * Call this straight from a click: the popup has to open before anything is awaited or the browser
+ * blocks it.
+ */
+export async function signIn(
+  i: SignInInput,
+): Promise<{ accessToken: string; expiresIn?: number; scope?: string }> {
+  // opened blank and pointed at the provider once the challenge exists, which keeps Safari's
+  // user-activation rule happy
+  const popup = window.open('', OAUTH_CHANNEL, 'popup,width=520,height=720')
+  if (!popup)
+    throw new OAuthError(
+      'The browser blocked the sign-in window. Allow pop-ups for this page and try again.',
+    )
+
+  const channel = new BroadcastChannel(OAUTH_CHANNEL)
+  let onWindowMessage: ((e: MessageEvent<OAuthMessage>) => void) | undefined
+  try {
+    const { verifier, challenge } = await createPkce()
+    const state = newState()
+    const redirect = redirectUri()
+
+    const returned = new Promise<OAuthMessage & { type: 'callback' }>((resolve, reject) => {
+      const timer = setTimeout(
+        () => reject(new OAuthError('Sign-in timed out. Try again.')),
+        i.timeoutMs ?? 5 * 60_000,
+      )
+      const stop = () => clearTimeout(timer)
+      i.signal?.addEventListener('abort', () => {
+        stop()
+        reject(new OAuthError('Sign-in was cancelled.'))
+      })
+      // the return arrives over the channel or from the popup as its opener; both carry the same message,
+      // and the one that arrives second is a repeat of the first
+      const take = (m: OAuthMessage | undefined, ack: (a: OAuthMessage) => void) => {
+        if (m?.type !== 'callback' || m.state !== state) return
+        stop()
+        ack({ type: 'ack', state })
+        resolve(m)
+      }
+      channel.onmessage = (e: MessageEvent<OAuthMessage>) =>
+        take(e.data, (a) => channel.postMessage(a))
+      onWindowMessage = (e: MessageEvent<OAuthMessage>) => {
+        // only this origin's own callback page: another site cannot hand us a code
+        if (e.origin !== location.origin) return
+        take(e.data, (a) => (e.source as Window | null)?.postMessage(a, location.origin))
+      }
+      addEventListener('message', onWindowMessage)
+    })
+
+    popup.location.href = authorizeUrl({
+      authorizationUrl: i.authorizationUrl,
+      clientId: i.clientId,
+      redirectUri: redirect,
+      scopes: i.scopes,
+      state,
+      challenge,
+    })
+
+    const back = await returned
+    const { code } = parseCallback(
+      {
+        state: back.state,
+        ...(back.code ? { code: back.code } : {}),
+        ...(back.error ? { error: back.error } : {}),
+        ...(back.description ? { error_description: back.description } : {}),
+      },
+      state,
+    )
+    const body = await i.exchange(
+      tokenRequestFields({ code, verifier, clientId: i.clientId, redirectUri: redirect }),
+      i.signal,
+    )
+    return parseTokenResponse(body)
+  } finally {
+    channel.close()
+    if (onWindowMessage) removeEventListener('message', onWindowMessage)
+    try {
+      popup.close()
+    } catch {
+      /* a severed popup cannot be closed from here; the callback page closes itself */
+    }
+  }
+}
+
+// ---- small per-browser conveniences: a client id is public, and an expiry note is not a secret ----
+
+const CLIENTS = 'specbook.oauth.clients.v1'
+const EXPIRY = 'specbook.oauth.expiry.v1'
+
+const readJson = (store: Storage, key: string): Record<string, any> => {
+  try {
+    return JSON.parse(store.getItem(key) ?? '{}')
+  } catch {
+    return {}
+  }
+}
+const writeJson = (store: Storage, key: string, value: unknown) => {
+  try {
+    store.setItem(key, JSON.stringify(value))
+  } catch {
+    /* blocked or full: the page still works without it */
+  }
+}
+
+export const recallClientId = (authorizationUrl: string): string | undefined => {
+  try {
+    return readJson(localStorage, CLIENTS)[authorizationUrl]
+  } catch {
+    return undefined
+  }
+}
+
+export const rememberClientId = (authorizationUrl: string, clientId: string): void => {
+  try {
+    writeJson(localStorage, CLIENTS, {
+      ...readJson(localStorage, CLIENTS),
+      [authorizationUrl]: clientId,
+    })
+  } catch {
+    /* no storage */
+  }
+}
+
+const expiryKey = (origin: string, name: string) => `${origin}\n${name}`
+
+/** Remembered for this tab only, to say "expires in 59 min"; the token itself stays in the secret store. */
+export const noteExpiry = (origin: string, name: string, expiresIn: number | undefined): void => {
+  try {
+    const t = readJson(sessionStorage, EXPIRY)
+    if (expiresIn === undefined) delete t[expiryKey(origin, name)]
+    else t[expiryKey(origin, name)] = Date.now() + expiresIn * 1000
+    writeJson(sessionStorage, EXPIRY, t)
+  } catch {
+    /* no storage */
+  }
+}
+
+export const expiryOf = (origin: string, name: string): number | undefined => {
+  try {
+    return readJson(sessionStorage, EXPIRY)[expiryKey(origin, name)]
+  } catch {
+    return undefined
+  }
+}

package/src/panel/CodeSample.tsx

@@ -11,7 +11,7 @@ import {
 import type { ComponentChildren } from 'preact'
 import { useCallback, useEffect, useMemo, useState } from 'preact/hooks'
 import { engine } from '../runtime'
-import { version } from '../store'
+import { env, version } from '../store'
 import { type Draft, requestParts } from './draft'
 
 const LANG_KEY = 'specbook:code-lang'
@@ -54,14 +54,15 @@ export function CodeSample({ service, profile, secured, make, sent }: Props) {
       if (!live) return
       const svc = c.services?.[service]
       const urls = svc?.baseUrl ?? {}
-      setBase(urls.live ?? Object.values(urls)[0])
+      // the environment being used, so a sample for the sandbox points at the sandbox
+      setBase(urls[env.value] ?? urls.live ?? Object.values(urls)[0])
       const name = profile === 'service' ? svc?.auth : profile
       setApplied(name ? (c.auth?.[name] as AuthProfile | undefined)?.apply : undefined)
     })
     return () => {
       live = false
     }
-  }, [service, profile])
+  }, [service, profile, env.value])
 
   const built = useMemo<{ text?: string; error?: string }>(() => {
     try {