@specbook/ui 0.1.0 → 0.2.0

package/src/panel/OAuthSignIn.tsx

@@ -0,0 +1,163 @@
+import { isDiscovery, type OAuthSettings } from '@specbook/core'
+import { useEffect, useRef, useState } from 'preact/hooks'
+import { noteExpiry, recallClientId, redirectUri, rememberClientId, signIn } from '../oauth'
+import { engine } from '../runtime'
+import { secretStore } from '../secrets'
+import { env, version } from '../store'
+
+type Status = { kind: 'idle' } | { kind: 'busy' } | { kind: 'error'; message: string }
+
+interface Endpoints {
+  authorizationUrl: string
+  scopes: Record<string, string>
+}
+
+/**
+ * "Sign in" for a scheme with an authorization code flow, or an OpenID Connect provider. The token lands
+ * in the same tab-scoped store, bound to the API's origin, that a pasted value would, so everything
+ * downstream is unchanged. A failure or a cancel only reports itself: the paste field next to this stays
+ * usable.
+ */
+export function OAuthSignIn({
+  service,
+  profile,
+  origin,
+  secret,
+  oauth,
+  onSignedIn,
+}: {
+  service: string
+  profile: string
+  origin: string
+  /** the secret the profile's `apply` reads; the token is stored under it */
+  secret: string
+  oauth: OAuthSettings
+  onSignedIn(): void
+}) {
+  // one provider, one remembered client id: keyed by the address that identifies the provider
+  const providerKey = isDiscovery(oauth) ? oauth.openIdConnectUrl : oauth.authorizationUrl
+  const [clientId, setClientId] = useState(
+    () => oauth.clientId ?? recallClientId(providerKey) ?? '',
+  )
+  const [endpoints, setEndpoints] = useState<Endpoints | undefined>(undefined)
+  const [picked, setPicked] = useState<string[]>([])
+  const [status, setStatus] = useState<Status>({ kind: 'idle' })
+  const abort = useRef<AbortController | undefined>(undefined)
+  const busy = status.kind === 'busy'
+  const [attempt, setAttempt] = useState(0)
+
+  // The provider's endpoints are settled before a click: the popup has to open from the click itself,
+  // and an OpenID Connect provider has to be asked where it is first.
+  useEffect(() => {
+    let on = true
+    setEndpoints(undefined)
+    setStatus((s) => (s.kind === 'busy' ? s : { kind: 'idle' }))
+    engine
+      .oauthEndpoints({ env: env.value, version: version.value, profile })
+      .then((found) => {
+        if (!on) return
+        setEndpoints(found)
+        // OpenID Connect asks for `openid` alone until more is ticked; a plain OAuth scheme lists what
+        // its operations need, so those are all ticked
+        setPicked(isDiscovery(oauth) ? ['openid'] : Object.keys(found.scopes))
+      })
+      .catch((e: unknown) => {
+        if (on) setStatus({ kind: 'error', message: e instanceof Error ? e.message : String(e) })
+      })
+    return () => {
+      on = false
+    }
+  }, [profile, env.value, version.value, attempt])
+
+  const scopeNames = Object.keys(endpoints?.scopes ?? {})
+
+  // called from the click itself: the popup must open before anything is awaited
+  const start = () => {
+    if (!endpoints) return setAttempt((n) => n + 1)
+    const id = clientId.trim()
+    if (!id)
+      return setStatus({ kind: 'error', message: 'Enter the client id registered for this page.' })
+    const ctl = new AbortController()
+    abort.current = ctl
+    setStatus({ kind: 'busy' })
+    rememberClientId(providerKey, id)
+    signIn({
+      authorizationUrl: endpoints.authorizationUrl,
+      clientId: id,
+      scopes: picked,
+      signal: ctl.signal,
+      exchange: (fields, signal) =>
+        engine.oauthExchange({ env: env.value, version: version.value, profile, fields, signal }),
+    })
+      .then((token) => {
+        secretStore.set(origin, secret, token.accessToken)
+        noteExpiry(origin, secret, token.expiresIn)
+        setStatus({ kind: 'idle' })
+        onSignedIn()
+      })
+      .catch((e: unknown) =>
+        setStatus({ kind: 'error', message: e instanceof Error ? e.message : String(e) }),
+      )
+  }
+
+  const failedLookup = !endpoints && status.kind === 'error'
+  // the idle line (the address to register) is the only one a phone can do without
+  const hint = !busy && status.kind !== 'error' && !!endpoints
+  return (
+    <span class="needs-var oauth-signin">
+      <input
+        type="text"
+        autocomplete="off"
+        aria-label={`Client id for ${service}`}
+        placeholder="client id"
+        value={clientId}
+        disabled={busy}
+        onInput={(e) => setClientId((e.target as HTMLInputElement).value)}
+      />
+      {busy ? (
+        <button type="button" class="link" onClick={() => abort.current?.abort()}>
+          Cancel
+        </button>
+      ) : (
+        <button type="button" class="btn" disabled={!endpoints && !failedLookup} onClick={start}>
+          {failedLookup ? 'Try again' : 'Sign in'}
+        </button>
+      )}
+      {scopeNames.length > 0 && (
+        <details>
+          <summary class="muted small">
+            Scopes ({picked.length} of {scopeNames.length})
+          </summary>
+          {scopeNames.map((s) => (
+            <label class="small" title={endpoints?.scopes[s] || undefined}>
+              <input
+                type="checkbox"
+                checked={picked.includes(s)}
+                disabled={busy}
+                onChange={(e) =>
+                  setPicked((p) =>
+                    (e.target as HTMLInputElement).checked ? [...p, s] : p.filter((x) => x !== s),
+                  )
+                }
+              />{' '}
+              <code>{s}</code>
+            </label>
+          ))}
+        </details>
+      )}
+      <span
+        class={`muted small oauth-status ${hint ? 'oauth-hint' : ''}`}
+        role="status"
+        aria-live="polite"
+      >
+        {busy
+          ? 'Waiting for the sign-in window…'
+          : status.kind === 'error'
+            ? status.message
+            : !endpoints
+              ? 'Looking up the provider…'
+              : `Register this redirect URI with the provider: ${redirectUri()}`}
+      </span>
+    </span>
+  )
+}

package/src/panel/Panel.tsx

@@ -1,6 +1,6 @@
 import type { ComponentChildren } from 'preact'
-import { useEffect, useRef } from 'preact/hooks'
-import { env, environments } from '../store'
+import { useEffect, useLayoutEffect, useRef } from 'preact/hooks'
+import { env, environmentNote, environments } from '../store'
 
 interface Props {
   title: string
@@ -99,7 +99,9 @@ export function Panel({
     }
   }, [])
 
-  useEffect(() => {
+  // A layout effect, so the keys work from the moment the panel is on screen: an effect waits for the next
+  // frame, and a key pressed (or sent by a test, or a host page) before it was ignored
+  useLayoutEffect(() => {
     const key = (e: KeyboardEvent) => {
       if (e.key === 'Escape') onClose()
       if (e.key !== 'Tab' || !modal || !aside.current) return
@@ -153,7 +155,9 @@ export function Panel({
                 onChange={(e) => (env.value = (e.target as HTMLSelectElement).value)}
               >
                 {environments.value.map((e) => (
-                  <option value={e}>{e}</option>
+                  <option value={e} title={environmentNote.value[e]}>
+                    {e}
+                  </option>
                 ))}
               </select>
             </label>

package/src/panel/RequestPanel.tsx

@@ -243,6 +243,8 @@ export function RequestPanel({ service, op, variants, initial }: Props) {
       setError(e instanceof Error ? e.message : String(e))
     } finally {
       setRunning(false)
+      // what you sent a request to see is the response, so show it (the tab stays one click away)
+      setTab('response')
     }
   }
 

package/src/panel/SecretsBar.tsx

@@ -1,16 +1,25 @@
+import type { AuthProfile, OAuthSettings } from '@specbook/core'
 import { useEffect, useState } from 'preact/hooks'
+import { expiryOf, noteExpiry } from '../oauth'
 import { absoluteBase } from '../routing'
 import { engine } from '../runtime'
 import { originOf, SECRET_PLACEHOLDER, secretStore } from '../secrets'
 import { env, version } from '../store'
+import { OAuthSignIn } from './OAuthSignIn'
 
 interface Need {
   service: string
   origin: string
   title: string
   names: string[]
+  /** the config's name for the profile (the key a sign-in's token exchange is addressed by) */
+  profile: string
+  oauth?: OAuthSettings
 }
 
+const minutesLeft = (at: number | undefined) =>
+  at === undefined ? undefined : Math.max(0, Math.round((at - Date.now()) / 60_000))
+
 const SOURCE: Record<string, string> = {
   session: 'this session',
   process: 'environment variable',
@@ -67,7 +76,15 @@ export function SecretsBar({
             ),
           ),
         ]
-        if (names.length) out.push({ service, origin, title: profile.title ?? s.auth ?? '', names })
+        if (names.length)
+          out.push({
+            service,
+            origin,
+            title: profile.title ?? s.auth ?? '',
+            names,
+            profile: s.auth as string,
+            oauth: (profile as AuthProfile).oauth,
+          })
       }
       setNeeds(out)
     })
@@ -109,12 +126,18 @@ export function SecretsBar({
                 <code>{name}</code>
                 {has ? (
                   <>
-                    <span class="muted">✓ set</span>
+                    <span class="muted">
+                      ✓ set
+                      {n.oauth && minutesLeft(expiryOf(n.origin, name)) !== undefined
+                        ? ` · expires in ${minutesLeft(expiryOf(n.origin, name))} min`
+                        : ''}
+                    </span>
                     <button
                       type="button"
                       class="link"
                       onClick={() => {
                         secretStore.remove(n.origin, name)
+                        noteExpiry(n.origin, name, undefined)
                         bump((x) => x + 1)
                       }}
                     >
@@ -124,6 +147,16 @@ export function SecretsBar({
                 ) : (
                   <>
                     {from && <span class="muted">from {SOURCE[from] ?? from}</span>}
+                    {n.oauth && (
+                      <OAuthSignIn
+                        service={n.service}
+                        profile={n.profile}
+                        origin={n.origin}
+                        secret={name}
+                        oauth={n.oauth}
+                        onSignedIn={() => bump((x) => x + 1)}
+                      />
+                    )}
                     <input
                       type="password"
                       autocomplete="off"

package/src/store.ts

@@ -6,5 +6,7 @@ export const env = signal('mock')
 export const environments = signal<string[]>(['mock'])
 /** Environments the config marks `production` or `sandbox`; others are judged by their name. */
 export const environmentRisk = signal<Record<string, 'production' | 'sandbox'>>({})
+/** What the config says each environment is, for the tooltip of its entry in a picker. */
+export const environmentNote = signal<Record<string, string>>({})
 export const locale = signal<string | undefined>(undefined)
 export const seed = signal<number | undefined>(undefined)

package/src/styles/panel.css

@@ -715,13 +715,53 @@
   }
   .needs-var {
     display: inline-flex;
+    flex-wrap: wrap;
     align-items: center;
     gap: 6px;
+    min-width: 0;
+    max-width: 100%;
   }
   .needs-var input {
     width: 130px;
     min-width: 0;
   }
+  /* the pasted value looks like the client id field beside it */
+  .needs-var input[type="password"] {
+    padding: 5px 8px;
+    border: 1px solid var(--sb-border);
+    border-radius: var(--sb-radius-control);
+    background: var(--sb-surface);
+  }
+  /* Sign in: its own row inside the credential, so the client id, the button, the scopes and the status
+     wrap under each other on a narrow screen instead of running off the edge */
+  .oauth-signin {
+    flex: 1 1 100%;
+  }
+  .oauth-signin input[type="text"] {
+    flex: 1 1 140px;
+    width: auto;
+    max-width: 360px;
+  }
+  .oauth-signin details {
+    flex: 1 1 100%;
+    min-width: 0;
+  }
+  .oauth-signin input[type="checkbox"] {
+    flex: 0 0 auto;
+    width: auto;
+  }
+  .oauth-signin details label {
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    min-height: 28px;
+    overflow-wrap: anywhere;
+  }
+  .oauth-status {
+    flex: 1 1 100%;
+    min-width: 0;
+    overflow-wrap: anywhere;
+  }
   .rq-meta {
     display: flex;
     align-items: center;
@@ -1787,8 +1827,10 @@
       flex-wrap: wrap;
       padding-inline: var(--sb-space-3);
     }
-    /* the credentials note is in the chip's tooltip; not worth a line of a phone screen */
-    .secrets-note {
+    /* the credentials note is in the chip's tooltip; not worth a line of a phone screen. The redirect
+       address to register is a desktop job too; a problem or a wait is still shown */
+    .secrets-note,
+    .oauth-hint {
       display: none;
     }
     .secrets-folded,

package/src/viewer/embed.ts

@@ -9,6 +9,7 @@
  * The script takes the page over (it owns the document, as `/docs` does). `spec` may be relative.
  * `baseUrl` gives the API address when the document has none, `target` names another container.
  */
+import { handleOAuthCallback } from '../oauth-callback'
 import { SpecWorker } from './client'
 import { mountOpened } from './mount'
 
@@ -46,6 +47,10 @@ const say = (el: HTMLElement, text: string, error = false) => {
 }
 
 async function start() {
+  // A sign-in's popup comes back to this page, so the viewer is what has to hand the code on. The address
+  // is left alone unless a viewer tab claims it: the page is the host's, and its `?code=&state=` may be
+  // the host application's own sign-in.
+  if (await handleOAuthCallback({ stripWhenUnclaimed: false })) return
   const cfg = readConfig()
   const target = container(cfg.target)
   if (!cfg.spec)

package/src/viewer/main.tsx

@@ -1,5 +1,6 @@
 import { render } from 'preact'
 import { useEffect, useRef, useState } from 'preact/hooks'
+import { handleOAuthCallback } from '../oauth-callback'
 import { applyTheme } from '../theme'
 import { type OpenFailure, SpecWorker } from './client'
 import { mountOpened } from './mount'
@@ -282,4 +283,7 @@ function BasePrompt({
   )
 }
 
-render(<Picker initial={{ kind: 'idle' }} />, root)
+// a sign-in's return leg lands on this page too: hand it to the tab that started it, draw nothing here
+void handleOAuthCallback().then((handled) => {
+  if (!handled) render(<Picker initial={{ kind: 'idle' }} />, root)
+})

package/src/viewer/protocol.ts

@@ -1,3 +1,4 @@
+import type { ServerEntry } from '@specbook/core'
 import type { AuthProfileLike } from './registry-data'
 
 /** Where a spec comes from. */
@@ -26,6 +27,8 @@ export interface OpenResult {
   defaultProfile?: string
   /** absolute API address, from `servers` (resolved against the spec URL) or `host` */
   baseUrl?: string
+  /** every usable server the document lists, as environments; the first is `live` */
+  servers: ServerEntry[]
   /** a relative `servers` entry the person has to give a base URL for */
   needsBaseUrl: boolean
   warnings: string[]

package/src/viewer/registry-data.ts

@@ -1,4 +1,8 @@
+import type { OAuthSettings } from '@specbook/core'
+
 export interface AuthProfileLike {
   title: string
   apply: { headers?: Record<string, string>; query?: Record<string, string> }
+  /** the scheme's authorization code flow, when it has one the page can sign in to */
+  oauth?: OAuthSettings
 }

package/src/viewer/registry.ts

@@ -134,19 +134,28 @@ export const loadFaker = () =>
     },
   }))
 
-const baseUrl = v.baseUrl ?? open.baseUrl
+// `live` is the document's first server, or the address the person typed for it; the rest keep their own names
+const live = v.baseUrl ?? open.baseUrl
+const baseUrl: Record<string, string> = {
+  ...(live ? { live } : {}),
+  ...Object.fromEntries(open.servers.filter((s) => s.name !== 'live').map((s) => [s.name, s.url])),
+}
+const described = Object.fromEntries(
+  open.servers.filter((s) => s.description).map((s) => [s.name, { description: s.description }]),
+)
 export const loadConfig = () =>
   Promise.resolve({
     default: {
       project: service,
       secrets: open.secrets,
       auth: open.auth,
+      ...(Object.keys(described).length ? { environments: described } : {}),
       // one locale, so the header offers no locale choice
       faker: { default: 'en', locales: { en: ['en', 'base'] } },
       services: {
         [service]: {
           spec: '',
-          baseUrl: baseUrl ? { live: baseUrl } : {},
+          baseUrl,
           ...(open.defaultProfile ? { auth: open.defaultProfile } : {}),
         },
       },

package/src/viewer/worker.ts

@@ -1,6 +1,6 @@
 /// <reference lib="webworker" />
 import { generateData, type OperationMeta, openSpec } from '@specbook/codegen/browser'
-import { authFromSpec, liveBaseUrl } from '@specbook/core'
+import { authFromSpec, MAX_SERVERS, openApiServers } from '@specbook/core'
 import { bundleJson, type Parts, sortFiles } from './bundles'
 import type { OpenResult, Request, Response, Source } from './protocol'
 
@@ -112,11 +112,10 @@ async function open(id: number, source: Source, signal: AbortSignal): Promise<Op
       (o.examples as { name: string }[]).map((e) => e.name),
     ]),
   )
-  const { auth, secrets, defaultProfile } = authFromSpec(doc)
   const sourceUrl = source.kind === 'url' ? source.url : undefined
-  const baseUrl = liveBaseUrl(doc, sourceUrl ?? name ?? '')
-  const relativeServer =
-    typeof doc.servers?.[0]?.url === 'string' && !/^https?:\/\//i.test(doc.servers[0].url)
+  const { auth, secrets, defaultProfile } = authFromSpec(doc, sourceUrl)
+  const { servers, needsBaseUrl, omitted } = openApiServers(doc, sourceUrl ?? name ?? '')
+  const baseUrl = servers.find((s) => s.name === 'live')?.url
   return {
     service,
     title,
@@ -127,8 +126,14 @@ async function open(id: number, source: Source, signal: AbortSignal): Promise<Op
     secrets,
     defaultProfile,
     baseUrl,
-    needsBaseUrl: !baseUrl && relativeServer,
-    warnings,
+    servers,
+    needsBaseUrl,
+    warnings: omitted
+      ? [
+          ...warnings,
+          `This document lists ${servers.length + omitted} servers. The first ${MAX_SERVERS} are offered as environments.`,
+        ]
+      : warnings,
     timings: {
       ...(fetched !== undefined ? { fetch: Math.round(fetched) } : {}),
       parse: Math.round(parse),