@specbook/core 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specbook/core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "The runner, mock engine, template engine and shared proxy behind Specbook: Storybook for APIs.",
   "keywords": [
     "specbook",

package/src/config.ts

@@ -11,6 +11,8 @@ export interface EnvironmentConfig {
    * "prod", amber otherwise (`mock` is always neutral).
    */
   risk?: 'production' | 'sandbox'
+  /** One line on what this environment is; shown as the tooltip of its entry in the pickers. */
+  description?: string
 }
 
 export interface ServiceConfig<E extends string = string> {

package/src/index.ts

@@ -6,6 +6,7 @@ export { fromFormRows, fromRows, toFormRows, toRows } from './example'
 export type { FakerConfig } from './faker'
 export { faker, fakerLocaleNames, installFaker, prepareFaker, setFaker } from './faker'
 export * from './mock'
+export * from './oauth'
 export * from './proxy/index'
 export * from './reporters/index'
 export { defineOperation, request } from './request'
@@ -15,7 +16,15 @@ export type { Sequence, SequenceMeta, StepCtx, StepNode } from './sequence'
 export { sequence } from './sequence'
 export type { SnippetInput, SnippetLang } from './snippets'
 export { snippetLangs, toSnippet } from './snippets'
-export { authFromSpec, type JsonAuthProfile, liveBaseUrl, type SpecAuth } from './spec-config'
+export {
+  authFromSpec,
+  type JsonAuthProfile,
+  liveBaseUrl,
+  MAX_SERVERS,
+  openApiServers,
+  type ServerEntry,
+  type SpecAuth,
+} from './spec-config'
 export {
   collectPlaceholders,
   deepMerge,

package/src/oauth.ts

@@ -0,0 +1,164 @@
+/**
+ * OAuth 2.0 authorization code with PKCE (RFC 7636), as pure helpers over Web Crypto so the browser and
+ * Node run the same code. Nothing here stores anything: a verifier is held by the caller, in memory.
+ */
+
+export class OAuthError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'OAuthError'
+  }
+}
+
+/** The endpoints are written out: an OAuth 2.0 authorization code flow. */
+export interface OAuthEndpoints {
+  authorizationUrl: string
+  tokenUrl: string
+  /** scope name -> description */
+  scopes?: Record<string, string>
+  /** a public identifier; pre-fills the sign-in prompt */
+  clientId?: string
+}
+
+/** The endpoints are found in an OpenID Connect discovery document. */
+export interface OAuthDiscovery {
+  openIdConnectUrl: string
+  scopes?: Record<string, string>
+  clientId?: string
+}
+
+/** What a spec or a config profile declares for an interactive sign-in. */
+export type OAuthSettings = OAuthEndpoints | OAuthDiscovery
+
+export const isDiscovery = (o: OAuthSettings): o is OAuthDiscovery => 'openIdConnectUrl' in o
+
+/** Endpoints read from a discovery document. */
+export interface DiscoveredEndpoints {
+  authorizationUrl: string
+  tokenUrl: string
+  /** scope name -> '' (a discovery document lists names only) */
+  scopes: Record<string, string>
+}
+
+/**
+ * The two endpoints a sign-in needs, from `/.well-known/openid-configuration`. Only the access token is
+ * used, so nothing else in the document (ID-token signing keys, `nonce` support) matters here.
+ */
+export function parseDiscovery(json: unknown): DiscoveredEndpoints {
+  const d = (json && typeof json === 'object' ? json : {}) as Record<string, unknown>
+  const url = (v: unknown) => (typeof v === 'string' && /^https?:\/\//i.test(v) ? v : undefined)
+  const authorizationUrl = url(d.authorization_endpoint)
+  const tokenUrl = url(d.token_endpoint)
+  if (!authorizationUrl || !tokenUrl)
+    throw new OAuthError('The provider’s discovery document has no authorization or token endpoint')
+  const supported = Array.isArray(d.scopes_supported)
+    ? d.scopes_supported.filter((x): x is string => typeof x === 'string')
+    : []
+  // `openid` is what makes it an OpenID Connect request; list it first even when the document omits it
+  const names = ['openid', ...supported.filter((x) => x !== 'openid')]
+  return { authorizationUrl, tokenUrl, scopes: Object.fromEntries(names.map((n) => [n, ''])) }
+}
+
+const base64url = (bytes: Uint8Array): string => {
+  let bin = ''
+  for (const b of bytes) bin += String.fromCharCode(b)
+  return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
+
+const random = (bytes: number) => base64url(crypto.getRandomValues(new Uint8Array(bytes)))
+
+/** `code_challenge` for a verifier: BASE64URL(SHA-256(verifier)). */
+export async function challengeFor(verifier: string): Promise<string> {
+  // WebCrypto's `subtle` exists only on a secure page (https, or localhost); a viewer served over plain
+  // http, or framed inside such a page, has none. Say so, rather than fail on `undefined.digest`.
+  if (!globalThis.crypto?.subtle)
+    throw new OAuthError(
+      'Sign-in needs a secure page (https, or localhost). Open the viewer over https, or paste an access token.',
+    )
+  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier))
+  return base64url(new Uint8Array(digest))
+}
+
+/** A fresh verifier (64 characters from the unreserved set) and its S256 challenge. */
+export async function createPkce(): Promise<{ verifier: string; challenge: string }> {
+  const verifier = random(48)
+  return { verifier, challenge: await challengeFor(verifier) }
+}
+
+export const newState = (): string => random(24)
+
+export function authorizeUrl(o: {
+  authorizationUrl: string
+  clientId: string
+  redirectUri: string
+  scopes?: string[]
+  state: string
+  challenge: string
+}): string {
+  const url = new URL(o.authorizationUrl)
+  url.searchParams.set('response_type', 'code')
+  url.searchParams.set('client_id', o.clientId)
+  url.searchParams.set('redirect_uri', o.redirectUri)
+  if (o.scopes?.length) url.searchParams.set('scope', o.scopes.join(' '))
+  url.searchParams.set('state', o.state)
+  url.searchParams.set('code_challenge', o.challenge)
+  url.searchParams.set('code_challenge_method', 'S256')
+  return url.toString()
+}
+
+/** The code from the redirect, once `state` has been checked; throws what the server or the check said. */
+export function parseCallback(
+  params: URLSearchParams | Record<string, string | null | undefined>,
+  expectedState: string,
+): { code: string } {
+  const get = (k: string) =>
+    (params instanceof URLSearchParams ? params.get(k) : params[k]) ?? undefined
+  const error = get('error')
+  if (error) {
+    const detail = get('error_description')
+    throw new OAuthError(`Sign-in was refused: ${detail ? `${error} (${detail})` : error}`)
+  }
+  if (get('state') !== expectedState)
+    throw new OAuthError('Sign-in was rejected: the response did not match this request (state)')
+  const code = get('code')
+  if (!code) throw new OAuthError('Sign-in returned no authorization code')
+  return { code }
+}
+
+/** The form fields of the code exchange. A public client sends the verifier and no client secret. */
+export function tokenRequestFields(o: {
+  code: string
+  verifier: string
+  clientId: string
+  redirectUri: string
+}): Record<string, string> {
+  return {
+    grant_type: 'authorization_code',
+    code: o.code,
+    redirect_uri: o.redirectUri,
+    client_id: o.clientId,
+    code_verifier: o.verifier,
+  }
+}
+
+export const tokenRequestBody = (o: Parameters<typeof tokenRequestFields>[0]): string =>
+  new URLSearchParams(tokenRequestFields(o)).toString()
+
+export function parseTokenResponse(json: unknown): {
+  accessToken: string
+  expiresIn?: number
+  scope?: string
+} {
+  const r = (json && typeof json === 'object' ? json : {}) as Record<string, unknown>
+  if (typeof r.error === 'string') {
+    const detail = typeof r.error_description === 'string' ? ` (${r.error_description})` : ''
+    throw new OAuthError(`The token endpoint refused the code: ${r.error}${detail}`)
+  }
+  if (typeof r.access_token !== 'string' || r.access_token === '')
+    throw new OAuthError('The token endpoint returned no access token')
+  return {
+    accessToken: r.access_token,
+    ...(typeof r.expires_in === 'number' ? { expiresIn: r.expires_in } : {}),
+    ...(typeof r.scope === 'string' ? { scope: r.scope } : {}),
+  }
+}

package/src/runner/run.ts

@@ -1,6 +1,7 @@
 import { createAsserter } from '../assert'
 import { ControlError, type Controls, describeControls, resolveControls } from '../controls'
 import type { Example, ExampleLoader, FileReader } from '../example'
+import type { OAuthSettings } from '../oauth'
 import { MissingSecretsError, maskDeep } from '../secrets'
 import type { Sequence, StepCtx } from '../sequence'
 import {
@@ -40,6 +41,8 @@ export interface AuthProfile {
   token?: (res: ApiResponse<number, any>) => Session
   apply: { headers?: Record<string, string>; query?: Record<string, string> }
   retryOn401?: boolean
+  /** an interactive sign-in the UI can offer (authorization code with PKCE); the runner ignores it */
+  oauth?: OAuthSettings
 }
 
 export type RunEvent =

package/src/spec-config.ts

@@ -3,11 +3,43 @@
  * the CLI's `preview` and the browser viewer, so both read a spec the same way.
  */
 
+import type { OAuthSettings } from './oauth'
+
 const isUrl = (s: string) => /^https?:\/\//i.test(s)
 
 export interface JsonAuthProfile {
   title: string
   apply: { headers?: Record<string, string>; query?: Record<string, string> }
+  /** present when the scheme has an authorization code flow the UI can sign in to */
+  oauth?: OAuthSettings
+}
+
+/** An OpenID Connect scheme: the discovery document says where to sign in. */
+function discovery(s: any, base: string | undefined): OAuthSettings | undefined {
+  if (typeof s.openIdConnectUrl !== 'string' || s.openIdConnectUrl === '') return undefined
+  try {
+    return { openIdConnectUrl: new URL(s.openIdConnectUrl, base).toString() }
+  } catch {
+    return undefined
+  }
+}
+
+/** The authorization code flow of an OAuth scheme (OpenAPI 3 `flows`, or Swagger 2 `accessCode`). */
+function codeFlow(s: any, base: string | undefined): OAuthSettings | undefined {
+  const flow = s.flows?.authorizationCode ?? (s.flow === 'accessCode' ? s : undefined)
+  if (!flow?.authorizationUrl || !flow?.tokenUrl) return undefined
+  const abs = (u: string) => {
+    try {
+      return new URL(u, base).toString()
+    } catch {
+      return u
+    }
+  }
+  return {
+    authorizationUrl: abs(flow.authorizationUrl),
+    tokenUrl: abs(flow.tokenUrl),
+    ...(flow.scopes && Object.keys(flow.scopes).length ? { scopes: flow.scopes } : {}),
+  }
 }
 
 export interface SpecAuth {
@@ -28,7 +60,7 @@ const secretName = (scheme: string) =>
  * Turns a document's security schemes into auth profiles whose secrets are filled in at run time, so
  * previewing a protected API only needs the user to paste a key. OAuth-style schemes take an access token.
  */
-export function authFromSpec(api: any): SpecAuth {
+export function authFromSpec(api: any, source?: string): SpecAuth {
   const schemes: Record<string, any> =
     api.components?.securitySchemes ?? api.securityDefinitions ?? {}
   const out: SpecAuth = { auth: {}, secrets: {} }
@@ -37,6 +69,7 @@ export function authFromSpec(api: any): SpecAuth {
     const ref = `{{secrets.${secret}}}`
     let apply: JsonAuthProfile['apply'] | undefined
     let title = name
+    let oauth: OAuthSettings | undefined
     if (s.type === 'apiKey') {
       const key = s.name as string
       if (s.in === 'header') apply = { headers: { [key]: ref } }
@@ -55,10 +88,12 @@ export function authFromSpec(api: any): SpecAuth {
       title = `${name} (basic auth, paste base64 of user:password)`
     } else if (s.type === 'oauth2' || s.type === 'openIdConnect') {
       apply = { headers: { authorization: `Bearer ${ref}` } }
-      title = `${name} (OAuth, paste an access token)`
+      const base = source && isUrl(source) ? source : undefined
+      oauth = s.type === 'oauth2' ? codeFlow(s, base) : discovery(s, base)
+      title = `${name} (OAuth, ${oauth ? 'sign in or ' : ''}paste an access token)`
     }
     if (!apply) continue
-    out.auth[name] = { title, apply }
+    out.auth[name] = { title, apply, ...(oauth ? { oauth } : {}) }
     out.secrets[secret] = {}
   }
   // the document's top-level `security` says which scheme most operations use
@@ -69,16 +104,112 @@ export function authFromSpec(api: any): SpecAuth {
   return out
 }
 
-/** Where the API lives, from `servers[0]` (OpenAPI 3) or `host`/`basePath` (Swagger 2). */
-export function liveBaseUrl(api: any, source: string): string | undefined {
-  const server = api.servers?.[0]?.url as string | undefined
-  if (server) {
-    if (isUrl(server)) return server.replace(/\/$/, '')
-    if (isUrl(source)) return new URL(server, source).toString().replace(/\/$/, '')
-    return undefined
+/** One server a spec lists, as an environment the UI can switch to. */
+export interface ServerEntry {
+  /** the environment name: `live` for the first, else a slug of its description or host */
+  name: string
+  url: string
+  description?: string
+}
+
+/** `live` plus this many minus one: a spec with a server per region should not bury the picker. */
+export const MAX_SERVERS = 20
+
+const slug = (s: string) =>
+  s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 24)
+    .replace(/-+$/, '')
+
+/** An absolute address for one `servers` entry: variables at their defaults, a relative URL against `source`. */
+function resolveServer(entry: any, source: string | undefined): string | undefined {
+  if (typeof entry?.url !== 'string') return undefined
+  const url = entry.url
+    .replace(/\{([^}]+)\}/g, (whole: string, key: string) => {
+      const d = entry.variables?.[key]?.default
+      return d === undefined || d === null ? whole : String(d)
+    })
+    .trim()
+  if (/\{[^}]*\}/.test(url)) return undefined
+  if (isUrl(url)) return url.replace(/\/+$/, '')
+  if (source) {
+    try {
+      return new URL(url, source).toString().replace(/\/+$/, '')
+    } catch {
+      /* not an address */
+    }
   }
-  if (api.host)
-    return `${api.schemes?.[0] ?? 'https'}://${api.host}${api.basePath ?? ''}`.replace(/\/$/, '')
-  if (isUrl(source)) return new URL(source).origin
   return undefined
 }
+
+/**
+ * The servers a document lists, as environments. The first is `live` (what a single-server spec has always
+ * had); the rest are named from their description, else their host, and are always a valid environment name.
+ *
+ * `needsBaseUrl` is true when the first server is relative and `source` cannot resolve it: the person is
+ * asked for the address, and what they type is `live`. `omitted` counts usable servers beyond `MAX_SERVERS`.
+ */
+export function openApiServers(
+  api: any,
+  source: string,
+): { servers: ServerEntry[]; needsBaseUrl: boolean; omitted: number } {
+  const src = isUrl(source) ? source : undefined
+  const listed: any[] = Array.isArray(api.servers) ? api.servers : []
+  const servers: ServerEntry[] = []
+  const describe = (e: any) =>
+    typeof e?.description === 'string' && e.description.trim() !== ''
+      ? { description: e.description.trim() as string }
+      : {}
+
+  if (listed.length === 0) {
+    // Swagger 2, or an OpenAPI 3 document that says nothing: the host, else wherever it was fetched from
+    if (api.host)
+      servers.push({
+        name: 'live',
+        url: `${api.schemes?.[0] ?? 'https'}://${api.host}${api.basePath ?? ''}`.replace(
+          /\/+$/,
+          '',
+        ),
+      })
+    else if (src) servers.push({ name: 'live', url: new URL(src).origin })
+    return { servers, needsBaseUrl: false, omitted: 0 }
+  }
+
+  const first = resolveServer(listed[0], src)
+  if (first) servers.push({ name: 'live', url: first, ...describe(listed[0]) })
+  const needsBaseUrl =
+    !first && typeof listed[0]?.url === 'string' && !/^https?:\/\//i.test(listed[0].url)
+
+  const taken = new Set(['mock', 'live'])
+  const seen = new Set(servers.map((x) => x.url))
+  let omitted = 0
+  for (const entry of listed.slice(1)) {
+    const url = resolveServer(entry, src)
+    if (!url || seen.has(url)) continue
+    if (servers.length >= MAX_SERVERS) {
+      omitted++
+      continue
+    }
+    seen.add(url)
+    const host = (() => {
+      try {
+        return new URL(url).host
+      } catch {
+        return ''
+      }
+    })()
+    const base = slug(describe(entry).description ?? '') || slug(host) || 'server'
+    let name = base
+    for (let n = 2; taken.has(name); n++) name = `${base}-${n}`
+    taken.add(name)
+    servers.push({ name, url, ...describe(entry) })
+  }
+  return { servers, needsBaseUrl, omitted }
+}
+
+/** Where the API lives, from `servers[0]` (OpenAPI 3) or `host`/`basePath` (Swagger 2). */
+export function liveBaseUrl(api: any, source: string): string | undefined {
+  return openApiServers(api, source).servers.find((s) => s.name === 'live')?.url
+}