@setzkasten-cms/astro-admin 0.8.0 → 1.3.0

package/src/api-routes/_role-resolver.ts

@@ -0,0 +1,60 @@
+import { resolveRoleForUser, type UserRole, type AuthProviderKind } from '@setzkasten-cms/core'
+import { resolveStorageConfig } from './_storage-config'
+import { resolveConfigRepoToken } from './_github-token'
+import { readEditorsFileStatus } from './editors'
+
+/**
+ * Builds the role-resolver callback that auth-adapters call per OAuth
+ * callback. Reads the live `_editors.json` (case-insensitive lookup) and
+ * combines it with the configured `allowedEmails` env list. Callers pass
+ * the resolver into `createGitHubAuth` / `createGoogleAuth` /
+ * `verifyFirebaseJwt` so role assignment happens once, in one place.
+ *
+ * Returns `null` when the user is not allowed at all, otherwise the
+ * effective role.
+ */
+export function makeRoleResolver(
+  provider: AuthProviderKind,
+  allowedEmails: readonly string[] | undefined,
+): (email: string) => Promise<UserRole | null> {
+  return async (email: string): Promise<UserRole | null> => {
+    const editors = await loadEditorsForResolution()
+    const result = resolveRoleForUser(email, provider, editors, allowedEmails)
+    return result.ok ? result.resolution.role : null
+  }
+}
+
+/**
+ * Reads `_editors.json` for role-resolution purposes.
+ *
+ * Returns `undefined` when the file is genuinely absent (treated as "no
+ * editors yet" — bootstrap path applies). Throws when the read errors out
+ * to fail-closed: an unreachable storage backend must never silently fall
+ * through to the bootstrap path and grant admin to everyone in
+ * `allowedEmails`.
+ */
+async function loadEditorsForResolution() {
+  const storage = resolveStorageConfig()
+  if (!storage) return undefined
+
+  const tokenResult = await resolveConfigRepoToken()
+  if (!tokenResult.ok) {
+    throw new Error(`role-resolver: token unavailable (${tokenResult.error.message})`)
+  }
+
+  const serverConfig = (globalThis as {
+    __SETZKASTEN_CONFIG__?: { storage?: { contentPath?: string } }
+  }).__SETZKASTEN_CONFIG__
+  const contentPath = serverConfig?.storage?.contentPath ?? 'content'
+
+  const status = await readEditorsFileStatus(
+    storage.owner,
+    storage.repo,
+    storage.branch,
+    contentPath,
+    tokenResult.value,
+  )
+  if (status.kind === 'absent') return undefined
+  if (status.kind === 'present') return status.editors
+  throw new Error(`role-resolver: ${status.message}`)
+}

package/src/api-routes/_session-cookie.ts

@@ -0,0 +1,42 @@
+/**
+ * Centralised builder for the session-cookie attributes. Two routes set the
+ * cookie today (auth-callback for GitHub OAuth, auth-setzkasten-login for
+ * Firebase) — both must share the exact same domain/secure/path so the
+ * cookie can be read across the admin and (in standalone setups) the
+ * managed website on a sibling subdomain.
+ */
+
+export interface SessionCookieOptions {
+  readonly httpOnly: true
+  readonly secure: boolean
+  readonly sameSite: 'lax'
+  readonly path: '/'
+  readonly maxAge: number
+  readonly domain?: string
+}
+
+const SESSION_MAX_AGE_SECONDS = 60 * 60 * 24 * 7
+
+export function sessionCookieOptions(secure: boolean): SessionCookieOptions {
+  return {
+    httpOnly: true,
+    secure,
+    sameSite: 'lax',
+    path: '/',
+    maxAge: SESSION_MAX_AGE_SECONDS,
+    ...(resolveCookieDomain() ? { domain: resolveCookieDomain()! } : {}),
+  }
+}
+
+function resolveCookieDomain(): string | undefined {
+  const fullConfig = (globalThis as Record<string, unknown>).__SETZKASTEN_FULL_CONFIG__ as
+    | { auth?: { cookieDomain?: string } }
+    | undefined
+  const fromConfig = fullConfig?.auth?.cookieDomain
+  if (typeof fromConfig === 'string' && fromConfig) return fromConfig
+
+  const fromEnv = process.env.SETZKASTEN_COOKIE_DOMAIN
+  if (typeof fromEnv === 'string' && fromEnv) return fromEnv
+
+  return undefined
+}

package/src/api-routes/_storage-config.ts

@@ -1,8 +1,23 @@
 /**
- * Resolve storage config from all available sources:
- * 1. Request body (explicit override)
- * 2. __SETZKASTEN_STORAGE__ (Vite define, embedded at build time — works everywhere)
- * 3. globalThis.__SETZKASTEN_CONFIG__ (injectScript, only works for rendered pages)
+ * Storage resolution helpers for admin API routes.
+ *
+ * Two entry points:
+ *
+ * - {@link resolveStorageConfigForRequest} (default for content routes) —
+ *   resolves the **active website** for a request. In single mode this
+ *   is always the integration's website; in multi mode it is the website
+ *   selected by the X-SK-Website header.
+ *
+ * - {@link resolveStorageConfig} (build-time only, used by auth-guard
+ *   for the editors file) — returns the integration's build-time storage
+ *   target. In single mode this is the website repo; in multi mode it
+ *   is the config repo (where `_editors.json` lives next to
+ *   `websites.json`).
+ *
+ * The lookup chain inside `resolveStorageConfig`:
+ * 1. Request body override (explicit `{ owner, repo, branch }` payload)
+ * 2. `__SETZKASTEN_STORAGE__` Vite define (embedded at build time)
+ * 3. `globalThis.__SETZKASTEN_CONFIG__` (injectScript, SSR-only fallback)
  */
 
 declare const __SETZKASTEN_STORAGE__: {
@@ -23,6 +38,13 @@ export interface StorageConfig {
   projectPrefix: string
 }
 
+/**
+ * Returns the integration's build-time storage target. Used by the
+ * auth-guard to read the editors file (which lives next to the build-
+ * time storage in both single and multi mode) and by tests that want
+ * to bypass the per-request resolver. Most content routes should use
+ * {@link resolveStorageConfigForRequest} instead.
+ */
 export function resolveStorageConfig(body?: {
   owner?: string
   repo?: string
@@ -52,3 +74,54 @@ export function prefixPath(filePath: string, projectPrefix: string): string {
   if (!projectPrefix) return filePath
   return `${projectPrefix}/${filePath}`
 }
+
+/**
+ * Standalone-aware variant: resolves storage from the active website
+ * (X-SK-Website header → WebsitesRegistry) before falling back to the
+ * single-repo build-time configuration.
+ *
+ * Body overrides still win over both — useful for routes that take an
+ * explicit `{ owner, repo, branch }` payload.
+ */
+export async function resolveStorageConfigForRequest(
+  request: Request,
+  body?: { owner?: string; repo?: string; branch?: string },
+): Promise<StorageConfig | null> {
+  // The build-time integration knows the monorepo layout (e.g. project
+  // prefix `apps/website/`). Carry that through so routes that touch
+  // source files — section templates for set:html upgrades, the migrator,
+  // etc. — resolve to the correct path. When the request targets a
+  // *different* repo than the build, the prefix doesn't apply, so we
+  // only inherit it for matching owner/repo.
+  const buildConfig = typeof __SETZKASTEN_STORAGE__ !== 'undefined' ? __SETZKASTEN_STORAGE__ : null
+  const inheritPrefix = (owner: string, repo: string): string => {
+    if (!buildConfig?.projectPrefix) return ''
+    if (buildConfig.owner === owner && buildConfig.repo === repo) return buildConfig.projectPrefix
+    return ''
+  }
+
+  if (body?.owner && body.repo) {
+    return {
+      owner: body.owner,
+      repo: body.repo,
+      branch: body.branch ?? 'main',
+      projectPrefix: inheritPrefix(body.owner, body.repo),
+    }
+  }
+
+  const { resolveCurrentWebsite } = await import('./_website-resolver.js')
+  const resolved = await resolveCurrentWebsite(request)
+  if (resolved.ok) {
+    const [owner, repo] = resolved.value.repo.split('/')
+    if (owner && repo) {
+      return {
+        owner,
+        repo,
+        branch: resolved.value.branch,
+        projectPrefix: inheritPrefix(owner, repo),
+      }
+    }
+  }
+
+  return resolveStorageConfig(body)
+}

package/src/api-routes/_vercel-origin.ts

@@ -0,0 +1,22 @@
+/**
+ * Derives the real public origin on Vercel (and any reverse-proxy setup).
+ *
+ * Problem: Inside a Vercel serverless function, both `request.url` and
+ * Astro's `url` context resolve to the internal function host
+ * (e.g. "https://localhost"), not the public hostname.
+ *
+ * Solution: Read the x-forwarded-host and x-forwarded-proto headers that
+ * Vercel's edge layer sets on every inbound request.
+ *
+ * Falls back gracefully to the `host` header and `https` for local dev
+ * or non-Vercel environments.
+ */
+export function getPublicOrigin(request: Request): string {
+  const host =
+    request.headers.get('x-forwarded-host') ??
+    request.headers.get('host') ??
+    'localhost'
+  const proto =
+    request.headers.get('x-forwarded-proto')?.split(',')[0]?.trim() ?? 'https'
+  return `${proto}://${host}`
+}

package/src/api-routes/_webhook-dispatcher.ts

@@ -0,0 +1,120 @@
+import {
+  parseWebhooksFile,
+  selectWebhooksForEvent,
+  type WebhookConfig,
+  type WebhookEvent,
+  type WebhookPayload,
+} from '@setzkasten-cms/core'
+import { resolveStorageConfigForRequest } from './_storage-config'
+import { resolveGitHubTokenForRequest } from './_github-token'
+import { cachedFetch } from './_github-cache'
+import { recordWebhookFire } from './_webhook-status-store'
+import { signPayload } from './_webhook-signing'
+
+const WEBHOOKS_FILE = (contentPath: string) => `${contentPath}/_webhooks.json`
+const DISPATCH_TIMEOUT_MS = 5_000
+
+/**
+ * Fire all enabled webhooks subscribed to `event`. Best-effort —
+ * each request runs with a 5s timeout; failures are recorded in the
+ * in-memory status store but do not throw or block the caller.
+ *
+ * Caller-side: invoke as `void fireWebhooks(...)` to make the
+ * fire-and-forget intent explicit.
+ */
+export async function fireWebhooks(
+  event: WebhookEvent,
+  payload: Omit<WebhookPayload, 'event' | 'timestamp'>,
+  request: Request,
+): Promise<void> {
+  try {
+    const webhooks = await loadWebhooksForRequest(request)
+    if (!webhooks || webhooks.length === 0) return
+
+    const targets = selectWebhooksForEvent(webhooks, event)
+    if (targets.length === 0) return
+
+    const fullPayload: WebhookPayload = {
+      event,
+      timestamp: new Date().toISOString(),
+      ...payload,
+    }
+    const body = JSON.stringify(fullPayload)
+
+    await Promise.all(targets.map((w) => fireOne(w, event, body)))
+  } catch (err) {
+    // Dispatcher failures must not break the save flow.
+    console.error('[setzkasten] webhook dispatch failed:', err)
+  }
+}
+
+async function fireOne(
+  webhook: WebhookConfig,
+  event: WebhookEvent,
+  body: string,
+): Promise<void> {
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+    'X-Setzkasten-Event': event,
+    'X-Setzkasten-Delivery': crypto.randomUUID(),
+  }
+  if (webhook.secret) {
+    headers['X-Setzkasten-Signature'] = `sha256=${signPayload(body, webhook.secret)}`
+  }
+
+  try {
+    const res = await fetch(webhook.url, {
+      method: 'POST',
+      headers,
+      body,
+      signal: AbortSignal.timeout(DISPATCH_TIMEOUT_MS),
+    })
+    recordWebhookFire(webhook.id, res.status)
+  } catch (err) {
+    recordWebhookFire(webhook.id, 'error')
+    console.warn(`[setzkasten] webhook "${webhook.id}" failed:`, err)
+  }
+}
+
+async function loadWebhooksForRequest(
+  request: Request,
+): Promise<readonly WebhookConfig[] | null> {
+  const tokenResult = await resolveGitHubTokenForRequest(request)
+  if (!tokenResult.ok) return null
+
+  const storage = await resolveStorageConfigForRequest(request)
+  if (!storage) return null
+
+  const serverConfig = (globalThis as {
+    __SETZKASTEN_CONFIG__?: { storage?: { contentPath?: string } }
+  }).__SETZKASTEN_CONFIG__
+  const contentPath = serverConfig?.storage?.contentPath ?? 'content'
+  const { owner, repo, branch } = storage
+
+  const cacheKey = `webhooks:${owner}/${repo}:${branch}`
+  return cachedFetch(cacheKey, 60_000, async () => {
+    const res = await fetch(
+      `https://api.github.com/repos/${owner}/${repo}/contents/${WEBHOOKS_FILE(contentPath)}?ref=${branch}`,
+      {
+        headers: {
+          Authorization: `Bearer ${tokenResult.value}`,
+          Accept: 'application/vnd.github+json',
+          'X-GitHub-Api-Version': '2022-11-28',
+        },
+      },
+    )
+    if (res.status === 404) return [] as readonly WebhookConfig[]
+    if (!res.ok) return null
+    const data = (await res.json()) as { content: string; encoding: string }
+    const raw =
+      data.encoding === 'base64'
+        ? Buffer.from(data.content, 'base64').toString('utf-8')
+        : data.content
+    const parsed = parseWebhooksFile(raw)
+    if (!parsed.ok) {
+      console.warn('[setzkasten] _webhooks.json parse error:', parsed.error.message)
+      return null
+    }
+    return parsed.value.webhooks
+  })
+}

package/src/api-routes/_webhook-signing.ts

@@ -0,0 +1,13 @@
+import { createHmac } from 'node:crypto'
+
+/**
+ * HMAC-SHA256 signature of the webhook payload body, hex-encoded.
+ * Receivers verify with the same secret and the **raw** request body —
+ * pattern is identical to GitHub webhooks.
+ *
+ * Lives in astro-admin (not core) because it imports node:crypto.
+ * core's "zero external deps" rule keeps it edge/browser-runnable.
+ */
+export function signPayload(body: string, secret: string): string {
+  return createHmac('sha256', secret).update(body, 'utf8').digest('hex')
+}

package/src/api-routes/_webhook-status-store.ts

@@ -0,0 +1,31 @@
+/**
+ * In-memory webhook status — last fired timestamp + last HTTP status per
+ * webhook id. Survives only the server process; cold-start losses are
+ * acceptable because this is a status display, not the source of truth.
+ *
+ * Persisting to `_webhooks.json` would create a commit-storm
+ * (every save → webhook fire → webhook commit → trigger save → …). The
+ * UI just refetches `/webhooks/status` after a test-fire or save.
+ */
+
+export interface WebhookStatusEntry {
+  readonly lastFiredAt: string
+  readonly lastStatus: number | 'error'
+}
+
+const store = new Map<string, WebhookStatusEntry>()
+
+export function recordWebhookFire(id: string, status: number | 'error'): void {
+  store.set(id, { lastFiredAt: new Date().toISOString(), lastStatus: status })
+}
+
+export function getWebhookStatus(): Record<string, WebhookStatusEntry> {
+  const out: Record<string, WebhookStatusEntry> = {}
+  for (const [k, v] of store.entries()) out[k] = v
+  return out
+}
+
+/** Test-only — clears the in-memory map. */
+export function _resetWebhookStatusForTests(): void {
+  store.clear()
+}

package/src/api-routes/_website-resolver.ts

@@ -0,0 +1,243 @@
+import {
+  type Result,
+  type WebsiteEntry,
+  type WebsitesRegistryProvider,
+  err,
+  notFoundError,
+  ok,
+  validationError,
+} from '@setzkasten-cms/core'
+import { GitHubAppClient, GitHubWebsitesRegistry } from '@setzkasten-cms/github-adapter'
+
+/**
+ * Per-request resolver for the active website.
+ *
+ * Standalone mode: looks up the entry matching the X-SK-Website request
+ * header in the websites registry (config-repo).
+ *
+ * Single-repo mode (backward compat): returns a synthesized WebsiteEntry
+ * built from the integration's build-time storage + GitHub-App ENV vars.
+ * The header is ignored.
+ */
+
+interface MultiState {
+  readonly mode: 'multi'
+  readonly registry: WebsitesRegistryProvider
+}
+
+interface SingleRepoState {
+  readonly mode: 'single'
+  readonly synthesized: WebsiteEntry
+}
+
+type ResolverState = MultiState | SingleRepoState | null
+
+let state: ResolverState = null
+
+/** Test/admin hook: install or clear the resolver state. */
+export function __resetWebsiteResolverForTests(next: ResolverState): void {
+  state = next
+}
+
+/**
+ * Configure the resolver state explicitly. Currently only the test suite
+ * uses this — production wiring runs lazily through
+ * {@link bootstrapResolverFromGlobals} on the first request, since the
+ * Astro integration doesn't have an obvious "initialize once" hook
+ * (`astro:server:start` runs in dev only). The export stays available so
+ * a future integration-startup wire-up has a typed entry point.
+ */
+export function configureWebsiteResolver(next: ResolverState): void {
+  state = next
+}
+
+interface FullConfig {
+  storage?:
+    | {
+        // 'single' is canonical; 'github-app' is the legacy alias.
+        kind: 'single' | 'github-app' | 'local'
+        repo?: string
+        appId?: string
+        installationId?: string
+      }
+    | {
+        // 'multi' is canonical; 'standalone' is the legacy alias.
+        kind: 'multi' | 'standalone'
+        configRepo: string
+        configBranch?: string
+        appId: string
+        installationId: string
+      }
+}
+
+function isMultiKind(kind: unknown): boolean {
+  return kind === 'multi' || kind === 'standalone'
+}
+
+interface BuildTimeStorage {
+  owner: string
+  repo: string
+  branch: string
+}
+
+// Vite define-injected literals. The integration (`packages/astro/src/
+// integration.ts`) sets them via the build-time Vite define plugin, so by
+// the time this code runs in a compiled API route the literals are
+// substituted with their JSON values. globalThis-style reads break on
+// cold-start serverless functions because the integration's
+// page-ssr injectScript only fires for SSR pages, never for API-only
+// invocations.
+declare const __SETZKASTEN_FULL_CONFIG__: FullConfig | null | undefined
+declare const __SETZKASTEN_STORAGE__: BuildTimeStorage | null | undefined
+declare const __SETZKASTEN_WEBSITE_URL__: string | undefined
+
+/**
+ * Lazy bootstrap from build-time globals. Reads `__SETZKASTEN_FULL_CONFIG__`
+ * and `__SETZKASTEN_STORAGE__` (set by the Astro integration via Vite
+ * define — literals only, NOT globalThis) to derive single-repo or
+ * standalone state. Idempotent — does nothing if the resolver is already
+ * configured.
+ */
+export function bootstrapResolverFromGlobals(): void {
+  if (state !== null) return
+
+  const fullConfig =
+    (typeof __SETZKASTEN_FULL_CONFIG__ !== 'undefined' ? __SETZKASTEN_FULL_CONFIG__ : null) ??
+    ((globalThis as Record<string, unknown>).__SETZKASTEN_FULL_CONFIG__ as
+      | FullConfig
+      | undefined)
+  const buildStorage =
+    (typeof __SETZKASTEN_STORAGE__ !== 'undefined' ? __SETZKASTEN_STORAGE__ : null) ??
+    ((globalThis as Record<string, unknown>).__SETZKASTEN_STORAGE__ as
+      | BuildTimeStorage
+      | undefined)
+
+  const storageKind = fullConfig?.storage?.kind
+  if (isMultiKind(storageKind)) {
+    const standalone = fullConfig?.storage as {
+      kind: 'multi' | 'standalone'
+      configRepo: string
+      configBranch?: string
+      appId: string
+      installationId: string
+    }
+    const privateKey = process.env.GITHUB_APP_PRIVATE_KEY
+    if (!privateKey) {
+      // Without the private key the resolver can't mint installation tokens;
+      // every Multi-Mode request would 400 with a confusing "X-SK-Website
+      // header missing" message instead of the actual root cause.
+      console.error(
+        '[setzkasten] Multi-mode resolver bootstrap failed: GITHUB_APP_PRIVATE_KEY is not set in env. ' +
+          'Set it on the standalone-admin deployment so the registry can be loaded.',
+      )
+      return
+    }
+    const [owner, repo] = standalone.configRepo.split('/')
+    if (!owner || !repo) {
+      console.error(
+        `[setzkasten] Multi-mode resolver bootstrap failed: storage.configRepo "${standalone.configRepo}" is not in "owner/repo" form.`,
+      )
+      return
+    }
+
+    const client = new GitHubAppClient(
+      { appId: standalone.appId, installationId: standalone.installationId, privateKey },
+      { owner, repo, branch: standalone.configBranch ?? 'main' },
+    )
+    const registry = new GitHubWebsitesRegistry({
+      reader: { read: (path) => client.getFileContent(path) },
+      path: 'websites.json',
+      ttlMs: 60_000,
+    })
+    state = { mode: 'multi', registry }
+    return
+  }
+
+  if (!buildStorage) return
+
+  const appId = process.env.GITHUB_APP_ID ?? ''
+  const installationId = process.env.GITHUB_APP_INSTALLATION_ID ?? ''
+  // Source of truth: __SETZKASTEN_WEBSITE_URL__ Vite define (mirrors
+  // astro.config.mjs#site, dev-server origin in dev) — same value the
+  // updater registers licenses with. As a Vite literal it survives
+  // cold-start API-only function invocations (unlike __SETZKASTEN_CONFIG__
+  // which is only set via injectScript on page-ssr renders).
+  // PUBLIC_SITE_URL stays as an escape hatch for setups without `site:`.
+  const websiteUrlLiteral =
+    typeof __SETZKASTEN_WEBSITE_URL__ !== 'undefined' ? __SETZKASTEN_WEBSITE_URL__ : ''
+  const previewOrigin =
+    websiteUrlLiteral ||
+    process.env.PUBLIC_SITE_URL ||
+    'http://localhost:4321'
+
+  state = {
+    mode: 'single',
+    synthesized: {
+      id: 'default',
+      name: buildStorage.repo,
+      repo: `${buildStorage.owner}/${buildStorage.repo}`,
+      branch: buildStorage.branch,
+      previewOrigin,
+      githubApp: { appId, installationId },
+    },
+  }
+}
+
+const HEADER = 'x-sk-website'
+
+export async function resolveCurrentWebsite(request: Request): Promise<Result<WebsiteEntry>> {
+  if (state === null) bootstrapResolverFromGlobals()
+  if (state === null) {
+    return err(
+      validationError(
+        ['websiteResolver'],
+        'not-configured',
+        'Website resolver not configured — call configureWebsiteResolver() at integration startup.',
+      ),
+    )
+  }
+
+  if (state.mode === 'single') {
+    return ok(state.synthesized)
+  }
+
+  const requested = request.headers.get(HEADER)?.trim() ?? ''
+
+  if (!requested) {
+    const list = await state.registry.list()
+    if (!list.ok) return list
+
+    const sole = list.value.length === 1 ? list.value[0] : undefined
+    if (sole) return ok(sole)
+
+    return err(
+      validationError(
+        [HEADER],
+        'required',
+        'Standalone mode requires the X-SK-Website request header (registry has multiple entries).',
+      ),
+    )
+  }
+
+  const found = await state.registry.get(requested)
+  if (!found.ok) return found
+  if (!found.value) return err(notFoundError(`website:${requested}`))
+
+  return ok(found.value)
+}
+
+/**
+ * Lists all websites known to the resolver.
+ * Standalone mode: defers to the registry. Single-repo mode: returns the
+ * synthesized entry as a one-element list.
+ */
+export async function listAllWebsites(): Promise<Result<readonly WebsiteEntry[]>> {
+  if (state === null) bootstrapResolverFromGlobals()
+  if (state === null) {
+    return err(
+      validationError(['websiteResolver'], 'not-configured', 'Website resolver not configured.'),
+    )
+  }
+  if (state.mode === 'single') return ok([state.synthesized])
+  return state.registry.list()
+}