@specbook/vite 0.1.0 → 0.2.0

package/README.md

@@ -4,4 +4,4 @@ The Specbook plugin for Vite: the registry, the docs UI hooks and the dev server
 
 Part of [Specbook](https://github.com/specbook-dev/specbook), Storybook for APIs. See the repository for documentation.
 
-Source-available under the [Functional Source License (FSL-1.1-MIT)](LICENSE): free for internal and personal use, not for a competing commercial product, and each version becomes MIT two years after its release.
+Source-available under the [Functional Source License (FSL-1.1-MIT)](LICENSE). Free to use, including at work and in commercial projects; the only restriction is offering it, or something substantially similar built from it, to others as a competing commercial product or service. Each version becomes MIT two years after its release.

package/dist/index.js

@@ -5,78 +5,25 @@ import { createRequire } from "module";
 import { basename, dirname, join as join4, relative as relative4, resolve as resolve2, sep as sep4 } from "path";
 import fg4 from "fast-glob";
 
-// src/docs.ts
-import { readFile } from "fs/promises";
-import { relative, sep } from "path";
-import fg from "fast-glob";
-import { marked } from "marked";
-function frontmatter(src) {
-  const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(src);
-  if (!m) return { meta: {}, body: src };
-  const meta = {};
-  for (const line of m[1].split(/\r?\n/)) {
-    const i = line.indexOf(":");
-    if (i > 0)
-      meta[line.slice(0, i).trim()] = line.slice(i + 1).trim().replace(/^["']|["']$/g, "");
+// ../core/src/oauth.ts
+var OAuthError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "OAuthError";
   }
-  return { meta, body: src.slice(m[0].length) };
-}
-var OP_FOLDER = /(?:^|\/)(?:requests|apis)\/([^/]+)\/([^/]+)\/(?:readme|index)\.md$/i;
-var OP_FLAT = /(?:^|\/)(?:requests|apis)\/([^/]+)\/docs\/([^/]+)\.md$/i;
-var NOT_AN_OPERATION = /^(readme|index)$/i;
-function colocated(file) {
-  if (/\.seq\.md$/.test(file)) return { sequenceFile: file.replace(/\.md$/, ".ts") };
-  if (/\.req\.md$/.test(file)) return { requestFile: file.replace(/\.md$/, ".ts") };
-  const folder = OP_FOLDER.exec(file);
-  if (folder && folder[2] !== "docs") return { operation: `${folder[1]}/${folder[2]}` };
-  const flat = OP_FLAT.exec(file);
-  if (flat && !NOT_AN_OPERATION.test(flat[2]))
-    return { operation: `${flat[1]}/${flat[2]}` };
-  return void 0;
-}
-async function scanDocs(root) {
-  const files = await fg("**/*.md", {
-    cwd: root,
-    absolute: true,
-    ignore: ["**/node_modules/**", "**/.generated/**", "**/dist/**", "**/.git/**"]
-  });
-  const pages = [];
-  const claimed = /* @__PURE__ */ new Map();
-  for (const abs of files.sort()) {
-    const { meta, body } = frontmatter(await readFile(abs, "utf8"));
-    const file = relative(root, abs).split(sep).join("/");
-    const near = colocated(file);
-    if (!near && !meta.operation && !meta.sequence && !meta.page) continue;
-    const operation = meta.operation ?? near?.operation;
-    if (operation) {
-      const first = claimed.get(operation);
-      if (first) {
-        console.warn(
-          `[specbook] ${file} documents ${operation}, which ${first} already does; ignored`
-        );
-        continue;
-      }
-      claimed.set(operation, file);
-    }
-    pages.push({
-      file,
-      operation,
-      sequence: meta.sequence,
-      sequenceFile: near?.sequenceFile,
-      requestFile: near?.requestFile,
-      replace: meta.replace === "true" || void 0,
-      title: meta.title ?? meta.page,
-      html: marked.parse(body, { async: false })
-    });
-  }
-  return pages;
+};
+function parseDiscovery(json3) {
+  const d = json3 && typeof json3 === "object" ? json3 : {};
+  const url = (v) => typeof v === "string" && /^https?:\/\//i.test(v) ? v : void 0;
+  const authorizationUrl = url(d.authorization_endpoint);
+  const tokenUrl = url(d.token_endpoint);
+  if (!authorizationUrl || !tokenUrl)
+    throw new OAuthError("The provider\u2019s discovery document has no authorization or token endpoint");
+  const supported = Array.isArray(d.scopes_supported) ? d.scopes_supported.filter((x) => typeof x === "string") : [];
+  const names = ["openid", ...supported.filter((x) => x !== "openid")];
+  return { authorizationUrl, tokenUrl, scopes: Object.fromEntries(names.map((n) => [n, ""])) };
 }
 
-// src/environments.ts
-import { existsSync } from "fs";
-import { mkdir, readdir, readFile as readFile2, writeFile } from "fs/promises";
-import { join } from "path";
-
 // ../core/src/proxy/policy.ts
 var DEFAULT_METHODS = ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"];
 var DEFAULT_MAX_BODY = 25 * 1024 * 1024;
@@ -371,7 +318,119 @@ function parseDotenv(text) {
   return out;
 }
 
+// src/discovery.ts
+var FETCH_TIMEOUT_MS = 5e3;
+function createDiscovery(opts = {}) {
+  const f = opts.fetch ?? fetch;
+  const now = opts.now ?? Date.now;
+  const retryAfter = opts.retryAfterMs ?? 3e4;
+  const found = /* @__PURE__ */ new Map();
+  const failedAt = /* @__PURE__ */ new Map();
+  const inFlight = /* @__PURE__ */ new Map();
+  async function look(url) {
+    try {
+      const res = await f(url, {
+        headers: { accept: "application/json" },
+        signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+      });
+      if (!res.ok) throw new Error(`answered ${res.status}`);
+      const origin = new URL(parseDiscovery(await res.json()).tokenUrl).origin;
+      found.set(url, origin);
+      failedAt.delete(url);
+      return origin;
+    } catch (e) {
+      failedAt.set(url, now());
+      opts.warn?.(
+        `Could not read the OpenID Connect discovery document at ${url} (${e instanceof Error ? e.message : String(e)}). Sign in is unavailable until it can; pasting a token still works.`
+      );
+      return void 0;
+    }
+  }
+  return function tokenOrigin(url) {
+    const known = found.get(url);
+    if (known) return Promise.resolve(known);
+    const failed = failedAt.get(url);
+    if (failed !== void 0 && now() - failed < retryAfter) return Promise.resolve(void 0);
+    let pending = inFlight.get(url);
+    if (!pending) {
+      pending = look(url).finally(() => inFlight.delete(url));
+      inFlight.set(url, pending);
+    }
+    return pending;
+  };
+}
+
+// src/docs.ts
+import { readFile } from "fs/promises";
+import { relative, sep } from "path";
+import fg from "fast-glob";
+import { marked } from "marked";
+function frontmatter(src) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(src);
+  if (!m) return { meta: {}, body: src };
+  const meta = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    const i = line.indexOf(":");
+    if (i > 0)
+      meta[line.slice(0, i).trim()] = line.slice(i + 1).trim().replace(/^["']|["']$/g, "");
+  }
+  return { meta, body: src.slice(m[0].length) };
+}
+var OP_FOLDER = /(?:^|\/)(?:requests|apis)\/([^/]+)\/([^/]+)\/(?:readme|index)\.md$/i;
+var OP_FLAT = /(?:^|\/)(?:requests|apis)\/([^/]+)\/docs\/([^/]+)\.md$/i;
+var NOT_AN_OPERATION = /^(readme|index)$/i;
+function colocated(file) {
+  if (/\.seq\.md$/.test(file)) return { sequenceFile: file.replace(/\.md$/, ".ts") };
+  if (/\.req\.md$/.test(file)) return { requestFile: file.replace(/\.md$/, ".ts") };
+  const folder = OP_FOLDER.exec(file);
+  if (folder && folder[2] !== "docs") return { operation: `${folder[1]}/${folder[2]}` };
+  const flat = OP_FLAT.exec(file);
+  if (flat && !NOT_AN_OPERATION.test(flat[2]))
+    return { operation: `${flat[1]}/${flat[2]}` };
+  return void 0;
+}
+async function scanDocs(root) {
+  const files = await fg("**/*.md", {
+    cwd: root,
+    absolute: true,
+    ignore: ["**/node_modules/**", "**/.generated/**", "**/dist/**", "**/.git/**"]
+  });
+  const pages = [];
+  const claimed = /* @__PURE__ */ new Map();
+  for (const abs of files.sort()) {
+    const { meta, body } = frontmatter(await readFile(abs, "utf8"));
+    const file = relative(root, abs).split(sep).join("/");
+    const near = colocated(file);
+    if (!near && !meta.operation && !meta.sequence && !meta.page) continue;
+    const operation = meta.operation ?? near?.operation;
+    if (operation) {
+      const first = claimed.get(operation);
+      if (first) {
+        console.warn(
+          `[specbook] ${file} documents ${operation}, which ${first} already does; ignored`
+        );
+        continue;
+      }
+      claimed.set(operation, file);
+    }
+    pages.push({
+      file,
+      operation,
+      sequence: meta.sequence,
+      sequenceFile: near?.sequenceFile,
+      requestFile: near?.requestFile,
+      replace: meta.replace === "true" || void 0,
+      title: meta.title ?? meta.page,
+      html: marked.parse(body, { async: false })
+    });
+  }
+  return pages;
+}
+
 // src/environments.ts
+import { existsSync } from "fs";
+import { mkdir, readdir, readFile as readFile2, writeFile } from "fs/promises";
+import { join } from "path";
 var ENV_NAME = /^[A-Za-z0-9_-]+$/;
 var VAR_NAME = /^[A-Za-z_][\w.-]*$/;
 var environmentsDir = (root) => join(root, ".specbook", "environments");
@@ -541,6 +600,15 @@ function requestsDirFor(root) {
 }
 
 // src/proxy.ts
+var AUTH_SERVICE_PREFIX = "auth:";
+var DISCOVERY_SERVICE_PREFIX = "discovery:";
+var decode = (s) => {
+  try {
+    return decodeURIComponent(s);
+  } catch {
+    return s;
+  }
+};
 var MOUNT = "/__specbook/proxy";
 function readBody(req) {
   return new Promise((res, rej) => {
@@ -568,7 +636,13 @@ async function handleProxy2(req, res, deps) {
   const response = await handleProxy(request, {
     mount: MOUNT,
     policy: {
-      upstream: (env, service) => config.services[service]?.baseUrl[env],
+      upstream: (env, service) => {
+        if (service.startsWith(AUTH_SERVICE_PREFIX))
+          return config.tokenOrigins?.[decode(service.slice(AUTH_SERVICE_PREFIX.length))];
+        if (service.startsWith(DISCOVERY_SERVICE_PREFIX))
+          return config.discoveryOrigins?.[decode(service.slice(DISCOVERY_SERVICE_PREFIX.length))];
+        return config.services[service]?.baseUrl[env];
+      },
       // a developer's own machine: their local services are the point
       allowPrivateHosts: true
     },
@@ -805,6 +879,7 @@ function specbook(options) {
   let notifyRegistryChanged = () => {
   };
   const memorySecrets = {};
+  const tokenOriginOf = createDiscovery({ warn: (m) => server?.config.logger.warn(m) });
   async function registryCode() {
     const files = await scanProject(root);
     const manifests = {};
@@ -1088,11 +1163,27 @@ export const loadConfig = ${cfg ? imp(cfg) : '() => Promise.resolve({ default: {
     if (!server || !cfgFile) return { services: {}, secretNames: {} };
     const mod = await server.ssrLoadModule(cfgFile);
     const cfg = mod.default ?? {};
+    const tokenOrigins = {};
+    const discoveryOrigins = {};
+    for (const [name, profile] of Object.entries(cfg.auth ?? {})) {
+      try {
+        const { tokenUrl, openIdConnectUrl } = profile.oauth ?? {};
+        if (tokenUrl) tokenOrigins[name] = new URL(tokenUrl).origin;
+        else if (openIdConnectUrl) {
+          discoveryOrigins[name] = new URL(openIdConnectUrl).origin;
+          const token = await tokenOriginOf(openIdConnectUrl);
+          if (token) tokenOrigins[name] = token;
+        }
+      } catch {
+      }
+    }
     return {
       services: Object.fromEntries(
         Object.entries(cfg.services ?? {}).map(([k, v]) => [k, { baseUrl: v.baseUrl ?? {} }])
       ),
-      secretNames: cfg.secrets ?? {}
+      secretNames: cfg.secrets ?? {},
+      tokenOrigins,
+      discoveryOrigins
     };
   }
   return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specbook/vite",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "The Specbook plugin for Vite: the registry, the docs UI hooks and the dev server credential proxy.",
   "keywords": [
     "specbook",
@@ -34,8 +34,8 @@
     }
   },
   "dependencies": {
-    "@specbook/codegen": "0.1.0",
-    "@specbook/core": "0.1.0",
+    "@specbook/codegen": "0.2.0",
+    "@specbook/core": "0.2.0",
     "fast-glob": "3.3.2",
     "marked": "^18.1.1"
   },

package/src/discovery.ts

@@ -0,0 +1,60 @@
+import { parseDiscovery } from '@specbook/core'
+
+const FETCH_TIMEOUT_MS = 5_000
+
+/**
+ * Learns, on the server, where an OpenID Connect provider's token endpoint is. The page needs the proxy to
+ * forward its code exchange there, and the proxy only forwards to origins it was told about by the
+ * project's own config; a discovery document is the config's pointer to that origin. Successes are kept
+ * for the life of the dev server; a failure is not retried for a short while, so a provider that is down
+ * costs one slow request, not one per call.
+ */
+export function createDiscovery(
+  opts: {
+    fetch?: typeof fetch
+    retryAfterMs?: number
+    now?: () => number
+    warn?: (message: string) => void
+  } = {},
+) {
+  const f = opts.fetch ?? fetch
+  const now = opts.now ?? Date.now
+  const retryAfter = opts.retryAfterMs ?? 30_000
+  const found = new Map<string, string>()
+  const failedAt = new Map<string, number>()
+  const inFlight = new Map<string, Promise<string | undefined>>()
+
+  async function look(url: string): Promise<string | undefined> {
+    try {
+      const res = await f(url, {
+        headers: { accept: 'application/json' },
+        signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+      })
+      if (!res.ok) throw new Error(`answered ${res.status}`)
+      const origin = new URL(parseDiscovery(await res.json()).tokenUrl).origin
+      found.set(url, origin)
+      failedAt.delete(url)
+      return origin
+    } catch (e) {
+      failedAt.set(url, now())
+      opts.warn?.(
+        `Could not read the OpenID Connect discovery document at ${url} (${e instanceof Error ? e.message : String(e)}). Sign in is unavailable until it can; pasting a token still works.`,
+      )
+      return undefined
+    }
+  }
+
+  /** The origin of the provider's token endpoint, or `undefined` when discovery has failed. */
+  return function tokenOrigin(url: string): Promise<string | undefined> {
+    const known = found.get(url)
+    if (known) return Promise.resolve(known)
+    const failed = failedAt.get(url)
+    if (failed !== undefined && now() - failed < retryAfter) return Promise.resolve(undefined)
+    let pending = inFlight.get(url)
+    if (!pending) {
+      pending = look(url).finally(() => inFlight.delete(url))
+      inFlight.set(url, pending)
+    }
+    return pending
+  }
+}

package/src/index.ts

@@ -5,6 +5,7 @@ import { createRequire } from 'node:module'
 import { basename, dirname, join, relative, resolve, sep } from 'node:path'
 import fg from 'fast-glob'
 import type { Plugin, ViteDevServer } from 'vite'
+import { createDiscovery } from './discovery'
 import { scanDocs } from './docs'
 import {
   ensureEnvironmentsDir,
@@ -156,6 +157,8 @@ export function specbook(options: SpecbookPluginOptions): Plugin {
   let notifyRegistryChanged: () => void = () => {}
   /** Credentials entered in the UI: never written to disk, gone when the server stops. */
   const memorySecrets: Record<string, Record<string, string>> = {}
+  // where each OpenID Connect profile's token endpoint is, read once from its discovery document
+  const tokenOriginOf = createDiscovery({ warn: (m) => server?.config.logger.warn(m) })
 
   async function registryCode(): Promise<string> {
     const files = await scanProject(root)
@@ -438,12 +441,30 @@ export const loadConfig = ${cfg ? imp(cfg) : '() => Promise.resolve({ default: {
     const cfg = (mod.default ?? {}) as {
       services?: Record<string, { baseUrl?: Record<string, string> }>
       secrets?: Record<string, { env?: string }>
+      auth?: Record<string, { oauth?: { tokenUrl?: string; openIdConnectUrl?: string } }>
+    }
+    const tokenOrigins: Record<string, string> = {}
+    const discoveryOrigins: Record<string, string> = {}
+    for (const [name, profile] of Object.entries(cfg.auth ?? {})) {
+      try {
+        const { tokenUrl, openIdConnectUrl } = profile.oauth ?? {}
+        if (tokenUrl) tokenOrigins[name] = new URL(tokenUrl).origin
+        else if (openIdConnectUrl) {
+          discoveryOrigins[name] = new URL(openIdConnectUrl).origin
+          const token = await tokenOriginOf(openIdConnectUrl)
+          if (token) tokenOrigins[name] = token
+        }
+      } catch {
+        /* an unparsable URL is left out; a sign-in against it fails with a 404 */
+      }
     }
     return {
       services: Object.fromEntries(
         Object.entries(cfg.services ?? {}).map(([k, v]) => [k, { baseUrl: v.baseUrl ?? {} }]),
       ),
       secretNames: cfg.secrets ?? {},
+      tokenOrigins,
+      discoveryOrigins,
     }
   }
 

package/src/proxy.ts

@@ -4,6 +4,29 @@ import { handleProxy as proxy } from '@specbook/core'
 export interface ProxyConfig {
   services: Record<string, { baseUrl: Record<string, string | undefined> }>
   secretNames: Record<string, { env?: string }>
+  /**
+   * Origin of each OAuth profile's token endpoint, read from the project's own config. A sign-in
+   * exchanges its code through `<mount>/<env>/auth:<profile>/…`; the page chooses the path, never the host.
+   */
+  tokenOrigins?: Record<string, string>
+  /**
+   * Origin of each OpenID Connect profile's discovery document, addressed as
+   * `<mount>/<env>/discovery:<profile>/…` (the token endpoint may be on another host).
+   */
+  discoveryOrigins?: Record<string, string>
+}
+
+/** The reserved service name a sign-in's token exchange is addressed to. */
+export const AUTH_SERVICE_PREFIX = 'auth:'
+/** The reserved service name a sign-in's discovery document is fetched through. */
+export const DISCOVERY_SERVICE_PREFIX = 'discovery:'
+
+const decode = (s: string) => {
+  try {
+    return decodeURIComponent(s)
+  } catch {
+    return s
+  }
 }
 
 export interface ProxyDeps {
@@ -61,7 +84,13 @@ export async function handleProxy(
   const response = await proxy(request, {
     mount: MOUNT,
     policy: {
-      upstream: (env, service) => config.services[service]?.baseUrl[env],
+      upstream: (env, service) => {
+        if (service.startsWith(AUTH_SERVICE_PREFIX))
+          return config.tokenOrigins?.[decode(service.slice(AUTH_SERVICE_PREFIX.length))]
+        if (service.startsWith(DISCOVERY_SERVICE_PREFIX))
+          return config.discoveryOrigins?.[decode(service.slice(DISCOVERY_SERVICE_PREFIX.length))]
+        return config.services[service]?.baseUrl[env]
+      },
       // a developer's own machine: their local services are the point
       allowPrivateHosts: true,
     },