blume 1.0.3 → 1.1.0

package/src/components/openapi/Authorization.astro

@@ -0,0 +1,80 @@
+---
+import {
+  type OperationSecurity,
+  schemeCarrier,
+  schemeLabel,
+} from "./security.ts";
+
+interface Props {
+  security: OperationSecurity;
+}
+
+const { security } = Astro.props;
+---
+
+{
+  security.alternatives.length > 0 && (
+    <section class="mt-6">
+      <div
+        aria-level="2"
+        class="mb-2 font-semibold text-foreground text-sm"
+        role="heading"
+      >
+        Authorization
+      </div>
+      {security.optional && (
+        <p class="mb-2 text-muted-foreground text-sm">
+          Optional — this operation also accepts unauthenticated requests.
+        </p>
+      )}
+      {security.alternatives.map((alternative, index) => (
+        <>
+          {index > 0 && (
+            <div class="my-2 font-medium text-[0.625rem] text-muted-foreground uppercase tracking-wide">
+              or
+            </div>
+          )}
+          <div class="not-prose rounded-blume border border-border px-4">
+            {alternative.map((resolved) => {
+              const carrier = schemeCarrier(resolved);
+              return (
+                <div class="border-border border-t py-3 first:border-t-0">
+                  <div class="flex flex-wrap items-baseline gap-x-2 gap-y-1">
+                    <code class="font-mono text-foreground text-sm">
+                      {carrier?.name ?? resolved.key}
+                    </code>
+                    <span class="text-muted-foreground text-xs">
+                      {schemeLabel(resolved)}
+                      {carrier ? ` · ${carrier.in}` : ""}
+                    </span>
+                    {!security.optional && (
+                      <span class="font-medium text-[0.625rem] text-red-600 uppercase tracking-wide dark:text-red-400">
+                        required
+                      </span>
+                    )}
+                  </div>
+                  {resolved.scheme?.description && (
+                    <div
+                      class="mt-1 text-muted-foreground text-sm"
+                      set:text={resolved.scheme.description}
+                    />
+                  )}
+                  {resolved.scopes.length > 0 && (
+                    <div class="mt-1 flex flex-wrap items-center gap-1 text-xs">
+                      <span class="text-muted-foreground">Scopes:</span>
+                      {resolved.scopes.map((scope) => (
+                        <code class="rounded bg-muted px-1 py-0.5 text-foreground">
+                          {scope}
+                        </code>
+                      ))}
+                    </div>
+                  )}
+                </div>
+              );
+            })}
+          </div>
+        </>
+      ))}
+    </section>
+  )
+}

package/src/components/openapi/Operation.astro

@@ -6,7 +6,15 @@ import {
   resolveComponentRef,
   type SchemaLike,
 } from "./helpers.ts";
+import {
+  effectiveSecurity,
+  resolveSecurity,
+  sampleAuth,
+  type SecurityRequirementLike,
+  type SecuritySchemeLike,
+} from "./security.ts";
 import { buildRequestSample, sampleLanguages } from "./snippets.ts";
+import Authorization from "./Authorization.astro";
 import MethodBadge from "./MethodBadge.astro";
 import ParametersTable from "./ParametersTable.astro";
 import RequestBody from "./RequestBody.astro";
@@ -43,6 +51,7 @@ interface FullOperation {
   parameters?: ParameterLike[];
   requestBody?: RequestBodyLike;
   responses?: Record<string, ResponseLike>;
+  security?: SecurityRequirementLike[];
 }
 
 const { source, id } = Astro.props;
@@ -59,7 +68,9 @@ const doc = (spec?.document ?? {}) as {
     parameters?: Record<string, ParameterLike>;
     requestBodies?: Record<string, RequestBodyLike>;
     responses?: Record<string, ResponseLike>;
+    securitySchemes?: Record<string, SecuritySchemeLike>;
   };
+  security?: SecurityRequirementLike[];
   servers?: { url?: string }[];
 };
 const pathItem = ref ? doc.paths?.[ref.path] : undefined;
@@ -84,6 +95,11 @@ const responses = Object.fromEntries(
   ])
 );
 
+const security = resolveSecurity(
+  effectiveSecurity(operation?.security, doc.security),
+  doc.components?.securitySchemes
+);
+
 const sample =
   ref && operation
     ? buildRequestSample(
@@ -91,7 +107,8 @@ const sample =
         ref.method,
         ref.path,
         doc.servers ?? [],
-        schemas
+        schemas,
+        sampleAuth(security)
       )
     : null;
 const languages = sampleLanguages(spec?.codeSamples ?? []);
@@ -115,6 +132,7 @@ const languages = sampleLanguages(spec?.codeSamples ?? []);
       </div>
       <div class="grid grid-cols-1 items-start gap-x-10 gap-y-8 xl:grid-cols-[minmax(0,1fr)_minmax(0,28rem)]">
         <div>
+          <Authorization security={security} />
           <ParametersTable parameters={params} schemas={schemas} />
           {requestBody && (
             <RequestBody

package/src/components/openapi/ParametersTable.astro

@@ -39,7 +39,7 @@ const groups = SECTIONS.map((section) => ({
   groups.map((group) => (
     <section class="mt-6">
       <div
-        aria-level="3"
+        aria-level="2"
         class="mb-2 font-semibold text-foreground text-sm"
         role="heading"
       >

package/src/components/openapi/security.ts

@@ -0,0 +1,201 @@
+/**
+ * Security (authorization) resolution for the OpenAPI components. An operation
+ * enforces its own `security` when declared — an empty array explicitly makes
+ * it public — and inherits the document's root `security` otherwise. Within the
+ * resolved list, each requirement object is one way to authorize (OR between
+ * entries), and every scheme named inside a single requirement is needed
+ * together (AND). Pure and dependency-free like `helpers.ts`, so it runs in the
+ * browser build with no server-only imports.
+ */
+
+/** A permissive view of an OpenAPI security scheme — only the fields we render. */
+export interface SecuritySchemeLike {
+  type?: string;
+  description?: string;
+  /** `apiKey`: the parameter name the key is sent as. */
+  name?: string;
+  /** `apiKey`: where the key goes — `header`, `query`, or `cookie`. */
+  in?: string;
+  /** `http`: the HTTP auth scheme, e.g. `bearer` or `basic`. */
+  scheme?: string;
+  /** `http` bearer: a hint at the token format, e.g. `JWT`. */
+  bearerFormat?: string;
+  [key: string]: unknown;
+}
+
+/** One security requirement: scheme name -> required scopes (empty outside OAuth). */
+export type SecurityRequirementLike = Record<string, string[]>;
+
+/** A scheme resolved out of `components.securitySchemes`, with its scopes. */
+export interface ResolvedScheme {
+  /** The scheme's component name, e.g. `bearerAuth`. */
+  key: string;
+  /** The scheme object; undefined when the requirement names an unknown one. */
+  scheme?: SecuritySchemeLike;
+  scopes: string[];
+}
+
+/** The security state one operation renders. */
+export interface OperationSecurity {
+  /** Ways to authorize (OR); every scheme within one entry is required (AND). */
+  alternatives: ResolvedScheme[][];
+  /** True when an empty requirement also allows unauthenticated calls. */
+  optional: boolean;
+}
+
+/**
+ * The requirement list an operation actually enforces: its own `security` when
+ * declared — the OpenAPI override rule, where `[]` removes the default and
+ * makes the operation public — else the document's root `security`.
+ */
+export const effectiveSecurity = (
+  operation?: SecurityRequirementLike[],
+  document?: SecurityRequirementLike[]
+): SecurityRequirementLike[] => operation ?? document ?? [];
+
+/**
+ * Resolve requirement names against `components.securitySchemes`. A name with
+ * no matching component is kept (with `scheme` undefined) so an inconsistent
+ * spec still renders the requirement instead of silently dropping it. An empty
+ * requirement object — the spec idiom for "auth optional" — contributes no
+ * alternative and flips `optional` instead.
+ */
+export const resolveSecurity = (
+  requirements: SecurityRequirementLike[],
+  schemes: Record<string, SecuritySchemeLike> | undefined
+): OperationSecurity => {
+  const alternatives: ResolvedScheme[][] = [];
+  let optional = false;
+  for (const requirement of requirements) {
+    const entries = Object.entries(requirement ?? {});
+    if (entries.length === 0) {
+      optional = true;
+      continue;
+    }
+    alternatives.push(
+      entries.map(([key, scopes]) => ({
+        key,
+        scheme: schemes?.[key],
+        scopes: Array.isArray(scopes)
+          ? scopes.filter((scope): scope is string => typeof scope === "string")
+          : [],
+      }))
+    );
+  }
+  return { alternatives, optional };
+};
+
+const capitalize = (text: string): string =>
+  text.charAt(0).toUpperCase() + text.slice(1);
+
+/** A short human label for a scheme row, e.g. `Bearer token` or `API key`. */
+export const schemeLabel = (resolved: ResolvedScheme): string => {
+  const { scheme } = resolved;
+  switch (scheme?.type) {
+    case "http": {
+      const kind = (scheme.scheme ?? "").toLowerCase();
+      if (kind === "bearer") {
+        return scheme.bearerFormat
+          ? `Bearer token (${scheme.bearerFormat})`
+          : "Bearer token";
+      }
+      if (kind === "basic") {
+        return "Basic auth";
+      }
+      return kind ? `HTTP ${kind}` : "HTTP auth";
+    }
+    case "apiKey": {
+      return "API key";
+    }
+    case "oauth2": {
+      return "OAuth2 access token";
+    }
+    case "openIdConnect": {
+      return "OpenID Connect token";
+    }
+    case "mutualTLS": {
+      return "Mutual TLS";
+    }
+    default: {
+      // Unknown scheme ref: the component name is the best label available.
+      return resolved.key;
+    }
+  }
+};
+
+/**
+ * Where the credential travels: the header/query/cookie parameter it occupies.
+ * Undefined for schemes with no request parameter (mutual TLS) and for unknown
+ * refs, where guessing a location would be misleading.
+ */
+export const schemeCarrier = (
+  resolved: ResolvedScheme
+): { name: string; in: string } | undefined => {
+  const { scheme } = resolved;
+  switch (scheme?.type) {
+    case "http":
+    case "oauth2":
+    case "openIdConnect": {
+      return { in: "header", name: "Authorization" };
+    }
+    case "apiKey": {
+      return { in: scheme.in ?? "header", name: scheme.name ?? resolved.key };
+    }
+    default: {
+      return undefined;
+    }
+  }
+};
+
+/** Placeholder credentials the request samples send. */
+export interface SampleAuth {
+  headers: Record<string, string>;
+  query: Record<string, string>;
+}
+
+/**
+ * Placeholder credentials for an operation's request samples, from its first
+ * alternative (the spec's preferred way to authorize). Schemes that don't
+ * travel in the request (mutual TLS) and unknown refs contribute nothing.
+ */
+export const sampleAuth = (security: OperationSecurity): SampleAuth => {
+  const headers: Record<string, string> = {};
+  const query: Record<string, string> = {};
+  const cookies: string[] = [];
+  for (const resolved of security.alternatives[0] ?? []) {
+    const { scheme } = resolved;
+    switch (scheme?.type) {
+      case "http": {
+        const kind = (scheme.scheme ?? "bearer").toLowerCase();
+        headers.Authorization =
+          kind === "bearer"
+            ? "Bearer YOUR_TOKEN"
+            : `${capitalize(kind)} YOUR_CREDENTIALS`;
+        break;
+      }
+      case "oauth2":
+      case "openIdConnect": {
+        headers.Authorization = "Bearer YOUR_ACCESS_TOKEN";
+        break;
+      }
+      case "apiKey": {
+        const name = scheme.name ?? resolved.key;
+        if (scheme.in === "query") {
+          query[name] = "YOUR_API_KEY";
+        } else if (scheme.in === "cookie") {
+          cookies.push(`${name}=YOUR_API_KEY`);
+        } else {
+          headers[name] = "YOUR_API_KEY";
+        }
+        break;
+      }
+      default: {
+        break;
+      }
+    }
+  }
+  if (cookies.length > 0) {
+    headers.Cookie = cookies.join("; ");
+  }
+  return { headers, query };
+};

package/src/components/openapi/snippets.ts

@@ -1,5 +1,6 @@
 import { exampleValue, toJson } from "./helpers.ts";
 import type { SchemaLike } from "./helpers.ts";
+import type { SampleAuth } from "./security.ts";
 
 /**
  * Request example + code-sample generation for an operation. Kept separate from
@@ -43,16 +44,22 @@ const jsonContentType = (
   return entries.find(([type]) => type.includes("json")) ?? entries[0];
 };
 
-/** The `?a=1&b=2` query string from an operation's required query params. */
+/**
+ * The `?a=1&b=2` query string from an operation's required query params, plus
+ * any extra entries (a query-borne API key from the security requirements).
+ */
 const queryString = (
   params: ParamLike[],
-  schemas: Record<string, SchemaLike>
+  schemas: Record<string, SchemaLike>,
+  extra: Record<string, string>
 ): string => {
   const query: string[] = [];
+  const seen = new Set<string>();
   for (const param of params) {
     if (!(param.in === "query" && param.required && param.name)) {
       continue;
     }
+    seen.add(param.name);
     const value = param.example ?? exampleValue(param.schema, schemas);
     query.push(
       `${encodeURIComponent(param.name)}=${encodeURIComponent(
@@ -60,16 +67,46 @@ const queryString = (
       )}`
     );
   }
+  for (const [name, value] of Object.entries(extra)) {
+    // A spec may declare the credential as an explicit query parameter too;
+    // its (better) example wins over the auth placeholder, as in headers.
+    if (seen.has(name)) {
+      continue;
+    }
+    query.push(`${encodeURIComponent(name)}=${encodeURIComponent(value)}`);
+  }
   return query.length > 0 ? `?${query.join("&")}` : "";
 };
 
+/**
+ * The sample's headers: auth placeholders first, so a spec that also declares
+ * the credential as an explicit header parameter overrides them with its own
+ * (better) example.
+ */
+const headerValues = (
+  params: ParamLike[],
+  schemas: Record<string, SchemaLike>,
+  auth: SampleAuth | undefined
+): Record<string, string> => {
+  const headers: Record<string, string> = { ...auth?.headers };
+  for (const param of params) {
+    if (param.in === "header" && param.required && param.name) {
+      headers[param.name] = String(
+        param.example ?? exampleValue(param.schema, schemas) ?? ""
+      );
+    }
+  }
+  return headers;
+};
+
 /** Assemble a representative request from an operation and the spec servers. */
 export const buildRequestSample = (
   operation: OperationLike,
   method: string,
   path: string,
   servers: { url?: string }[],
-  schemas: Record<string, SchemaLike>
+  schemas: Record<string, SchemaLike>,
+  auth?: SampleAuth
 ): RequestSample => {
   const base = (servers[0]?.url ?? "").replace(TRAILING_SLASH, "");
   const params = operation.parameters ?? [];
@@ -85,16 +122,8 @@ export const buildRequestSample = (
     }
   }
 
-  const search = queryString(params, schemas);
-
-  const headers: Record<string, string> = {};
-  for (const param of params) {
-    if (param.in === "header" && param.required && param.name) {
-      headers[param.name] = String(
-        param.example ?? exampleValue(param.schema, schemas) ?? ""
-      );
-    }
-  }
+  const search = queryString(params, schemas, auth?.query ?? {});
+  const headers = headerValues(params, schemas, auth);
 
   const media = jsonContentType(operation.requestBody?.content);
   let body: string | undefined;

package/src/core/config-input.ts

@@ -10,6 +10,7 @@ import type {
   SidebarItemConfig,
 } from "./schema.ts";
 import type { ContentSource } from "./sources/types.ts";
+import type { StandardSchema } from "./standard-schema.ts";
 
 /**
  * The public, hand-documented authoring type for `blume.config.ts`.
@@ -452,6 +453,16 @@ export interface MixedbreadSearch {
   storeId: string;
 }
 
+/** A curated link for the search dialog empty state. */
+export interface SearchPopularLink {
+  /** Internal route or external URL. */
+  href: string;
+  /** Built-in icon name shown beside the label; defaults to the file glyph. */
+  icon?: string;
+  /** Link label shown in the dialog. */
+  label: string;
+}
+
 /**
  * Search backend. The default `orama` builds a local index at build time (and
  * runs in dev); hosted providers need their credential block below. `none`
@@ -469,6 +480,11 @@ export interface SearchConfig {
   mixedbread?: MixedbreadSearch;
   /** Orama Cloud credentials (required when `provider` is `orama-cloud`). */
   oramaCloud?: OramaCloudSearch;
+  /**
+   * Curated links for the Cmd+K empty state. When omitted or empty, the first
+   * sidebar pages are shown instead.
+   */
+  popular?: SearchPopularLink[];
   /** Which backend powers search. Defaults to `orama`. */
   provider?: SearchProvider;
   /** Typesense credentials (required when `provider` is `typesense`). */
@@ -711,6 +727,49 @@ export interface RssConfig {
   types?: string[];
 }
 
+/** Colors used by generated Open Graph cards. Any CSS color — hex, `oklch(…)`, `rgb(…)`, named. */
+export interface OgPaletteConfig {
+  /** Fallback mark color. Defaults to the light theme accent. */
+  accent?: string;
+  /** Card background. */
+  background?: string;
+  /** Footer divider. */
+  border?: string;
+  /** Headline and `currentColor` logo color. */
+  foreground?: string;
+  /** Description and footer text. */
+  muted?: string;
+}
+
+/** Per-page Open Graph image generation. */
+export interface OgConfig {
+  /**
+   * Generate an OG image per page. Defaults to on once a deployment `site`
+   * URL is known and off otherwise (`og:image` must be absolute). An explicit
+   * value always wins.
+   */
+  enabled?: boolean;
+  /**
+   * Google Font families for the generated card, extending Takumi's Latin-only
+   * default so non-Latin titles (CJK, and so on) render instead of tofu.
+   * Fetched from Google Fonts at build. A bare string loads the family's
+   * default weights; the object form pins weights (`700`, `[400, 700]`, or a
+   * `"100..900"` variable range) and styles.
+   */
+  fonts?: (
+    | string
+    | {
+        name: string;
+        style?: "normal" | "italic" | ("normal" | "italic")[];
+        weight?: number | number[] | string;
+      }
+  )[];
+  /** Local SVG used in the generated card instead of the site logo. */
+  logo?: string;
+  /** Optional generated-card colors. */
+  palette?: OgPaletteConfig;
+}
+
 /** Discoverability: OG images, feeds, sitemap, robots, and structured data. */
 export interface SeoConfig {
   /**
@@ -721,14 +780,7 @@ export interface SeoConfig {
   /** robots.txt `Content-Signal` usage declaration. Defaults to `true`. */
   contentSignals?: ContentSignalsConfig;
   /** Per-page Open Graph image generation. */
-  og?: {
-    /**
-     * Generate an OG image per page. Defaults to on once a deployment `site`
-     * URL is known and off otherwise (`og:image` must be absolute). An explicit
-     * value always wins.
-     */
-    enabled?: boolean;
-  };
+  og?: OgConfig;
   /** Generate robots.txt (with a Sitemap reference when available). Defaults to `true`. */
   robots?: boolean;
   /** RSS/Atom feeds. */
@@ -897,6 +949,38 @@ export type ExportConfig =
       pdf?: boolean;
     };
 
+/**
+ * Opt-in custom frontmatter keys. Page frontmatter is strictly validated —
+ * an unknown key fails the build so typos are caught — and `extend` carves
+ * out project-specific keys from that rule, each validated by a schema you
+ * supply.
+ */
+export interface FrontmatterConfig {
+  /**
+   * Extra frontmatter keys pages may carry, mapped to their validation
+   * schemas — any library implementing Standard Schema works (Zod — the
+   * version your project installs, 3.24+ or 4 — Valibot, ArkType):
+   *
+   * ```ts
+   * import { z } from "zod";
+   *
+   * frontmatter: {
+   *   extend: {
+   *     owner: z.string(),
+   *     reviewedAt: z.coerce.date().optional(),
+   *   },
+   * },
+   * ```
+   *
+   * Every declared key is validated on every page — absent ones included —
+   * so a required schema enforces the key site-wide; mark it `.optional()`
+   * to validate only when present. Validated values are preserved on each
+   * page record's `custom` field. Built-in frontmatter fields cannot be
+   * redeclared.
+   */
+  extend?: Record<string, StandardSchema>;
+}
+
 /**
  * "Last updated" timestamps. `false` (default) disables them; `true` derives
  * each date from git history; the object form selects the source. A page's
@@ -970,6 +1054,8 @@ export interface BlumeConfig {
   export?: ExportConfig;
   /** Show the per-page "Was this helpful?" widget. Defaults to `true`. */
   feedback?: boolean;
+  /** Opt-in custom frontmatter keys, validated by schemas you supply. */
+  frontmatter?: FrontmatterConfig;
   /** Source repository (Edit-this-page links and the header repo link). */
   github?: GithubConfig;
   /** Internationalization (opt-in multi-locale). */

package/src/core/data.ts

@@ -1,3 +1,4 @@
+import type { OgFont } from "../og/card.ts";
 import type { UIStrings } from "./i18n-ui.ts";
 import type { ResolvedConfig, SearchProvider } from "./schema.ts";
 import type { Navigation, RouteAlternate } from "./types.ts";
@@ -15,6 +16,10 @@ export interface BlumeLogo {
   svg?: string;
   light?: string;
   dark?: string;
+  dimensions?: {
+    dark?: { height: number; width: number };
+    light?: { height: number; width: number };
+  };
   alt: string;
   href: string;
   /** Wordmark text beside the mark; `undefined` falls back to the site title. */
@@ -109,10 +114,21 @@ export interface BlumeDataConfig {
   /** Hosted MCP server, or `null` when MCP is off. */
   mcp: { name: string; route: string } | null;
   /** Open Graph image generation. */
-  og: { enabled: boolean };
+  og: {
+    enabled: boolean;
+    /** Extra Google Font family specs for the card renderer, fetched at build. */
+    fonts?: OgFont[];
+    logo?: string;
+    palette?: ResolvedConfig["seo"]["og"]["palette"];
+  };
   /** Repository URL for header/edit links, or `null`. */
   repoUrl: string | null;
-  search: { enabled: boolean; provider: SearchProvider };
+  search: {
+    enabled: boolean;
+    /** Resolved empty-state links; empty when unset (Search falls back to sidebar). */
+    popular: { icon?: string; label: string; route: string }[];
+    provider: SearchProvider;
+  };
   /** Deployment site URL, or `null` when none is configured/detected. */
   site: string | null;
   structuredData: boolean;

package/src/core/deployment-env.ts

@@ -44,6 +44,15 @@ const PLATFORMS: Platform[] = [
   },
 ];
 
+/**
+ * Adapters whose `deployment.site` arrives from platform env vars at deploy
+ * time. Consumers (e.g. the audit) use this to tell "site is missing" apart
+ * from "site is missing *here*, but the platform will set it".
+ */
+export const SITE_INFERRING_ADAPTERS: ReadonlySet<string> = new Set(
+  PLATFORMS.map((platform) => platform.adapter)
+);
+
 /**
  * Fill in `deployment.adapter` and `deployment.site` from platform env vars
  * (Vercel, Netlify, Cloudflare Pages) when the user hasn't set them. Explicit