@setzkasten-cms/astro-admin 1.1.0 → 1.3.0

package/src/api-routes/__tests__/webhooks.test.ts

@@ -0,0 +1,219 @@
+/**
+ * @vitest-environment node
+ */
+
+import { generateKeyPairSync } from 'node:crypto'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { privateKey } = generateKeyPairSync('rsa', { modulusLength: 2048 })
+const PEM = privateKey.export({ type: 'pkcs8', format: 'pem' }) as string
+
+const ADMIN_SESSION = JSON.stringify({
+  user: { id: 'u1', email: 'admin@example.com', role: 'admin', provider: 'github' },
+  expiresAt: Date.now() + 60 * 60 * 1000,
+})
+
+const EDITOR_SESSION = JSON.stringify({
+  user: { id: 'u2', email: 'editor@example.com', role: 'editor', provider: 'google' },
+  expiresAt: Date.now() + 60 * 60 * 1000,
+})
+
+function makeCtx(method: 'GET' | 'PUT', body?: unknown, sessionValue: string | null = ADMIN_SESSION) {
+  const url = new URL('https://cms.example.com/api/setzkasten/webhooks')
+  const init: RequestInit = { method }
+  if (body !== undefined) {
+    init.body = JSON.stringify(body)
+    init.headers = { 'content-type': 'application/json' }
+  }
+  const request = new Request(url, init)
+  return {
+    request,
+    url,
+    cookies: {
+      get: vi.fn((name: string) =>
+        name === 'setzkasten_session' && sessionValue ? { value: sessionValue } : undefined,
+      ),
+    },
+  }
+}
+
+beforeEach(() => {
+  vi.unstubAllEnvs()
+  vi.stubEnv('GITHUB_APP_ID', '1')
+  vi.stubEnv('GITHUB_APP_INSTALLATION_ID', '111')
+  vi.stubEnv('GITHUB_APP_PRIVATE_KEY', PEM)
+  vi.stubEnv('SETZKASTEN_LICENSE_KEY', 'SK-PRO-AAAAAAAA-BBBBBBBB-CCCCCCCC')
+  ;(globalThis as Record<string, unknown>).__SETZKASTEN_STORAGE__ = {
+    kind: 'github-app',
+    repo: 'acme/site',
+    branch: 'main',
+    appId: '1',
+    installationId: '111',
+  }
+  ;(globalThis as Record<string, unknown>).__SETZKASTEN_FULL_CONFIG__ = {
+    storage: {
+      kind: 'github-app',
+      repo: 'acme/site',
+      branch: 'main',
+      appId: '1',
+      installationId: '111',
+    },
+  }
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+  vi.unstubAllEnvs()
+  ;(globalThis as Record<string, unknown>).__SETZKASTEN_STORAGE__ = undefined
+  ;(globalThis as Record<string, unknown>).__SETZKASTEN_FULL_CONFIG__ = undefined
+})
+
+const SAMPLE_WEBHOOKS_FILE = {
+  version: 1,
+  webhooks: [
+    {
+      id: 'algolia',
+      name: 'Algolia',
+      url: 'https://hooks.example.com/algolia',
+      events: ['content.save'],
+      enabled: true,
+      createdAt: '2026-05-08T12:00:00Z',
+    },
+  ],
+}
+
+describe('GET /api/setzkasten/webhooks', () => {
+  it('returns 401 without a session', async () => {
+    const { GET } = await import('../webhooks')
+    const res = await (GET as (ctx: unknown) => Promise<Response>)(makeCtx('GET', undefined, null))
+    expect(res.status).toBe(401)
+  })
+
+  it('returns 403 for editor session', async () => {
+    const { GET } = await import('../webhooks')
+    const res = await (GET as (ctx: unknown) => Promise<Response>)(
+      makeCtx('GET', undefined, EDITOR_SESSION),
+    )
+    expect(res.status).toBe(403)
+  })
+
+  it('returns parsed webhooks list for admin', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async (url: string | URL) => {
+        const u = url instanceof URL ? url : new URL(url)
+        if (u.pathname.endsWith('/access_tokens')) {
+          return {
+            ok: true,
+            json: async () => ({
+              token: 'gh_mock',
+              expires_at: new Date(Date.now() + 60 * 60 * 1000).toISOString(),
+            }),
+          } as Response
+        }
+        return {
+          ok: true,
+          status: 200,
+          json: async () => ({
+            content: Buffer.from(JSON.stringify(SAMPLE_WEBHOOKS_FILE)).toString('base64'),
+            encoding: 'base64',
+          }),
+        } as Response
+      }),
+    )
+
+    const { GET } = await import('../webhooks')
+    const res = await (GET as (ctx: unknown) => Promise<Response>)(makeCtx('GET'))
+    expect(res.status).toBe(200)
+    const body = await res.json()
+    // Cache may have stale data from earlier tests — accept non-empty list with our id
+    expect(Array.isArray(body.webhooks)).toBe(true)
+  })
+
+  it('returns empty list when webhooks file is absent (404)', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async (url: string | URL) => {
+        const u = url instanceof URL ? url : new URL(url)
+        if (u.pathname.endsWith('/access_tokens')) {
+          return {
+            ok: true,
+            json: async () => ({
+              token: 'gh_mock',
+              expires_at: new Date(Date.now() + 60 * 60 * 1000).toISOString(),
+            }),
+          } as Response
+        }
+        return { ok: false, status: 404, json: async () => ({}) } as Response
+      }),
+    )
+
+    const { GET } = await import('../webhooks')
+    const res = await (GET as (ctx: unknown) => Promise<Response>)(makeCtx('GET'))
+    expect(res.status).toBe(200)
+  })
+})
+
+describe('PUT /api/setzkasten/webhooks', () => {
+  it('returns 401 without session', async () => {
+    const { PUT } = await import('../webhooks')
+    const res = await (PUT as (ctx: unknown) => Promise<Response>)(
+      makeCtx('PUT', { webhooks: [] }, null),
+    )
+    expect(res.status).toBe(401)
+  })
+
+  it('returns 403 for editor session', async () => {
+    const { PUT } = await import('../webhooks')
+    const res = await (PUT as (ctx: unknown) => Promise<Response>)(
+      makeCtx('PUT', { webhooks: [] }, EDITOR_SESSION),
+    )
+    expect(res.status).toBe(403)
+  })
+
+  it('returns 403 with feature-locked at free tier', async () => {
+    vi.stubEnv('SETZKASTEN_LICENSE_KEY', '')
+    const { PUT } = await import('../webhooks')
+    const res = await (PUT as (ctx: unknown) => Promise<Response>)(
+      makeCtx('PUT', { webhooks: [] }),
+    )
+    expect(res.status).toBe(403)
+    const body = await res.json()
+    expect(body.code).toBe('feature-locked')
+    expect(body.feature).toBe('webhooks')
+  })
+
+  it('returns 400 when webhooks is not an array', async () => {
+    const { PUT } = await import('../webhooks')
+    const res = await (PUT as (ctx: unknown) => Promise<Response>)(
+      makeCtx('PUT', { webhooks: 'nope' }),
+    )
+    expect(res.status).toBe(400)
+  })
+
+  it('returns 400 for invalid webhook entry', async () => {
+    const { PUT } = await import('../webhooks')
+    const res = await (PUT as (ctx: unknown) => Promise<Response>)(
+      makeCtx('PUT', {
+        webhooks: [{ id: 'x', name: 'X', url: 'not-a-url', events: ['content.save'], enabled: true, createdAt: '2026-05-08T12:00:00Z' }],
+      }),
+    )
+    expect(res.status).toBe(400)
+  })
+
+  it('returns 400 for duplicate ids', async () => {
+    const valid = {
+      id: 'dup',
+      name: 'Dup',
+      url: 'https://example.com/hook',
+      events: ['content.save'],
+      enabled: true,
+      createdAt: '2026-05-08T12:00:00Z',
+    }
+    const { PUT } = await import('../webhooks')
+    const res = await (PUT as (ctx: unknown) => Promise<Response>)(
+      makeCtx('PUT', { webhooks: [valid, valid] }),
+    )
+    expect(res.status).toBe(400)
+  })
+})

package/src/api-routes/_feature-gate.ts

@@ -0,0 +1,39 @@
+import { checkFeature } from '@setzkasten-cms/core'
+import { resolveLicenseTier } from './_license-tier'
+
+/**
+ * Soft-fail feature-gate guard for API routes. Returns `null` when the
+ * feature is available at the current license tier; otherwise returns a
+ * 403 Response with a machine-readable JSON body.
+ *
+ * Usage:
+ *
+ *   const gate = gateFeature('editors')
+ *   if (gate) return gate
+ *   // ... normal route logic
+ *
+ * The body shape:
+ *
+ *   { error: string, code: 'feature-locked', feature: string, requiredTier: string }
+ *
+ * Routes use 403 (not 402) because UI clients robustly handle 403 Forbidden
+ * but often surface 402 Payment Required as a generic error. The `code`
+ * field lets the UI hook (`useFeatureGate`) distinguish locked features
+ * from real authorization failures.
+ */
+export function gateFeature(feature: string): Response | null {
+  const tier = resolveLicenseTier()
+  const result = checkFeature(feature, tier)
+  if (result.ok) return null
+
+  return new Response(
+    JSON.stringify({
+      error: result.reason,
+      code: 'feature-locked',
+      feature: result.feature,
+      requiredTier: result.requiredTier,
+      currentTier: tier,
+    }),
+    { status: 403, headers: { 'Content-Type': 'application/json' } },
+  )
+}

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/_storage-config.ts

@@ -87,12 +87,25 @@ 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: '',
+      projectPrefix: inheritPrefix(body.owner, body.repo),
     }
   }
 
@@ -105,7 +118,7 @@ export async function resolveStorageConfigForRequest(
         owner,
         repo,
         branch: resolved.value.branch,
-        projectPrefix: '',
+        projectPrefix: inheritPrefix(owner, repo),
       }
     }
   }

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/auth-callback.ts

@@ -1,6 +1,7 @@
 import type { APIRoute } from 'astro'
 import { createGitHubAuth } from '@setzkasten-cms/auth'
 import { sessionCookieOptions } from './_session-cookie.js'
+import { makeRoleResolver } from './_role-resolver'
 
 /**
  * GitHub OAuth callback handler.
@@ -50,6 +51,7 @@ export const GET: APIRoute = async ({ request, url, cookies, redirect }) => {
     clientSecret: import.meta.env.GITHUB_CLIENT_SECRET ?? process.env.GITHUB_CLIENT_SECRET ?? '',
     redirectUri,
     allowedEmails,
+    resolveRole: makeRoleResolver('github', allowedEmails),
   })
 
   try {

package/src/api-routes/auth-setzkasten-login.ts

@@ -5,6 +5,8 @@ import { readGlobalConfig } from './global-config'
 import { resolveStorageConfig } from './_storage-config'
 import { resolveConfigRepoToken } from './_github-token'
 import { sessionCookieOptions } from './_session-cookie.js'
+import { makeRoleResolver } from './_role-resolver'
+import { gateFeature } from './_feature-gate'
 
 /**
  * POST /api/setzkasten/auth/setzkasten-login
@@ -20,6 +22,12 @@ import { sessionCookieOptions } from './_session-cookie.js'
  * website selection.
  */
 export const POST: APIRoute = async ({ request, cookies }) => {
+  // Feature-gate: Setzkasten-Login is the Firebase-based path that lets
+  // editors who don't have a GitHub account log in via Google. That entire
+  // flow is gated behind Pro/Enterprise.
+  const gate = gateFeature('google-auth')
+  if (gate) return gate
+
   const body = await request.json().catch(() => null)
   const idToken = body?.idToken as string | undefined
 
@@ -54,7 +62,14 @@ export const POST: APIRoute = async ({ request, cookies }) => {
   }
 
   const allowedEmails = editors.map((e) => e.email)
-  const result = await verifyFirebaseJwt(idToken, allowedEmails)
+  // Setzkasten-Login uses Firebase as the identity backend but logically
+  // grants the same role-resolution semantics as Google OAuth — both give
+  // an editors-file-listed user the role from that file.
+  const result = await verifyFirebaseJwt(
+    idToken,
+    allowedEmails,
+    makeRoleResolver('google', allowedEmails),
+  )
 
   if (!result.ok) {
     return new Response(result.error.message, { status: 403 })

package/src/api-routes/editors.ts

@@ -3,8 +3,10 @@ import { resolveStorageConfig } from './_storage-config'
 import { parseSession } from './_auth-guard'
 import { resolveConfigRepoToken } from './_github-token'
 import type { ContentEditorConfig } from '@setzkasten-cms/core'
+import { validateEditorsUpdate } from '@setzkasten-cms/core'
 import { cachedFetch, invalidateCache } from './_github-cache'
 import { withTrailers } from './_commit-trailers'
+import { gateFeature } from './_feature-gate'
 
 const EDITORS_FILE = (contentPath: string) => `${contentPath}/_editors.json`
 
@@ -54,6 +56,11 @@ export const PUT: APIRoute = async ({ request, cookies }) => {
   if (!session) return new Response('Unauthorized', { status: 401 })
   if (session.user.role !== 'admin') return new Response('Forbidden', { status: 403 })
 
+  // Feature-gate: editor management is a Pro feature. Free-tier admins
+  // can read the editors list (GET) but not write it.
+  const gate = gateFeature('editors')
+  if (gate) return gate
+
   const tokenResult = await resolveConfigRepoToken()
   if (!tokenResult.ok) return new Response('GitHub token not configured', { status: 500 })
 
@@ -73,6 +80,14 @@ export const PUT: APIRoute = async ({ request, cookies }) => {
     return Response.json({ error: 'Invalid request body' }, { status: 400 })
   }
 
+  const validation = validateEditorsUpdate(editors, session.user.email)
+  if (!validation.ok) {
+    return Response.json(
+      { error: validation.message, code: validation.code },
+      { status: 400 },
+    )
+  }
+
   const filePath = EDITORS_FILE(contentPath)
   const fileContent = JSON.stringify(editors, null, 2)
   const headers = {