@setzkasten-cms/astro-admin 0.6.0 → 1.1.0

package/src/api-routes/__tests__/websites-remove.test.ts

@@ -0,0 +1,155 @@
+/**
+ * @vitest-environment node
+ */
+
+import { generateKeyPairSync } from 'node:crypto'
+import type { WebsiteEntry } from '@setzkasten-cms/core'
+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 REGISTRY = {
+  websites: [
+    {
+      id: 'keep-me',
+      name: 'Keep Me',
+      repo: 'acme/keep',
+      branch: 'main',
+      previewOrigin: 'https://keep.example.com',
+      githubApp: { appId: '1', installationId: '111' },
+    },
+    {
+      id: 'remove-me',
+      name: 'Remove Me',
+      repo: 'acme/remove',
+      branch: 'main',
+      previewOrigin: 'https://remove.example.com',
+      githubApp: { appId: '1', installationId: '222' },
+    },
+  ],
+}
+
+// Admin sessions only — websites-remove is admin-gated.
+const ADMIN_SESSION = JSON.stringify({
+  user: {
+    id: 'u1',
+    email: 'admin@example.com',
+    role: 'admin',
+    provider: 'github',
+  },
+  expiresAt: Date.now() + 60 * 60 * 1000,
+})
+
+function makeCtx(body: unknown, sessionValue: string | null = ADMIN_SESSION) {
+  const request = new Request('https://cms.example.com/api/setzkasten/websites/remove', {
+    method: 'POST',
+    body: JSON.stringify(body),
+    headers: { 'content-type': 'application/json' },
+  })
+  return {
+    request,
+    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)
+  ;(globalThis as Record<string, unknown>).__SETZKASTEN_FULL_CONFIG__ = {
+    storage: {
+      kind: 'standalone',
+      configRepo: 'acme/cms-config',
+      configBranch: 'main',
+      appId: '1',
+      installationId: '111',
+    },
+  }
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+  vi.unstubAllEnvs()
+  ;(globalThis as Record<string, unknown>).__SETZKASTEN_FULL_CONFIG__ = undefined
+})
+
+function mockGithubFetch() {
+  const calls: Array<{ url: string; method?: string; body?: unknown }> = []
+  const fetchMock = vi.fn(async (url: string, init?: RequestInit) => {
+    calls.push({ url, method: init?.method, body: init?.body })
+    if (url.includes('/access_tokens')) {
+      return {
+        ok: true,
+        json: async () => ({
+          token: 'gh_mock',
+          expires_at: new Date(Date.now() + 60 * 60 * 1000).toISOString(),
+        }),
+      } as Response
+    }
+    if (url.includes('/contents/websites.json') && (init?.method ?? 'GET') === 'GET') {
+      return {
+        ok: true,
+        json: async () => ({
+          content: Buffer.from(JSON.stringify(REGISTRY)).toString('base64'),
+          sha: 'reg-sha',
+        }),
+      } as Response
+    }
+    if (url.includes('/contents/websites.json') && init?.method === 'PUT') {
+      return {
+        ok: true,
+        json: async () => ({ content: { sha: 'new-sha' } }),
+      } as Response
+    }
+    throw new Error(`unexpected URL: ${url} method=${init?.method}`)
+  })
+  vi.stubGlobal('fetch', fetchMock)
+  return calls
+}
+
+describe('POST /api/setzkasten/websites/remove', () => {
+  it('returns 401 without a session', async () => {
+    const { POST } = await import('../websites-remove')
+    const res = await (POST as (ctx: unknown) => Promise<Response>)(makeCtx({ id: 'x' }, null))
+
+    expect(res.status).toBe(401)
+  })
+
+  it('returns 400 when body has no id', async () => {
+    const { POST } = await import('../websites-remove')
+    const res = await (POST as (ctx: unknown) => Promise<Response>)(makeCtx({}))
+
+    expect(res.status).toBe(400)
+  })
+
+  it('returns 404 when the id does not exist', async () => {
+    mockGithubFetch()
+
+    const { POST } = await import('../websites-remove')
+    const res = await (POST as (ctx: unknown) => Promise<Response>)(makeCtx({ id: 'nope' }))
+
+    expect(res.status).toBe(404)
+  })
+
+  it('removes the entry and writes the updated registry', async () => {
+    const calls = mockGithubFetch()
+
+    const { POST } = await import('../websites-remove')
+    const res = await (POST as (ctx: unknown) => Promise<Response>)(makeCtx({ id: 'remove-me' }))
+
+    expect(res.status).toBe(200)
+
+    const putCall = calls.find((c) => c.method === 'PUT')
+    expect(putCall).toBeDefined()
+    const writtenBody = JSON.parse(String(putCall!.body)) as { content: string; sha?: string }
+    expect(writtenBody.sha).toBe('reg-sha')
+    const decoded = JSON.parse(Buffer.from(writtenBody.content, 'base64').toString('utf-8'))
+    expect(decoded.websites.map((w: WebsiteEntry) => w.id)).toEqual(['keep-me'])
+  })
+})

package/src/api-routes/_auth-guard.ts

@@ -0,0 +1,153 @@
+import { canEditPage } from '@setzkasten-cms/auth'
+import type { AuthSession, ContentEditorConfig, SetzKastenConfig } from '@setzkasten-cms/core'
+import { resolveStorageConfig } from './_storage-config'
+import { resolveConfigRepoToken } from './_github-token'
+import { readEditorsFileStatus } from './editors'
+
+export function parseSession(raw: string | undefined): AuthSession | null {
+  if (!raw) return null
+  try {
+    return JSON.parse(raw) as AuthSession
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Returns 401 if the request has no valid session, 403 if the user is not
+ * an admin, or null (= allowed) otherwise. Used by every admin-only API
+ * endpoint so the role check is mechanically applied — never just
+ * `if (!session) return 401`, which lets editors hit admin-only routes.
+ */
+export function requireAdmin(rawSession: string | undefined): Response | null {
+  const session = parseSession(rawSession)
+  if (!session) {
+    return new Response(JSON.stringify({ error: 'Unauthorized' }), {
+      status: 401,
+      headers: { 'Content-Type': 'application/json' },
+    })
+  }
+  if (session.user.role !== 'admin') {
+    return new Response(JSON.stringify({ error: 'Forbidden: admin role required' }), {
+      status: 403,
+      headers: { 'Content-Type': 'application/json' },
+    })
+  }
+  return null
+}
+
+/**
+ * Returns a 403/503 Response if the session user may NOT edit the given page,
+ * or null (= allowed) otherwise.
+ *
+ * Authorization is two-layered:
+ *
+ *   1. Global editors (_editors.json in the config-repo) decide which pages
+ *      an editor account can touch at all. Admins always pass.
+ *
+ *   2. Per-website allowedEmails (in WebsiteEntry, multi-mode only) decide
+ *      which editors may operate on the website the request is targeting.
+ *      Without this layer, an editor could swap the X-SK-Website header
+ *      to any registered website id and inherit edit access transitively
+ *      from layer 1. Single-mode requests skip this layer because the
+ *      resolver returns no Result.ok for them.
+ *
+ * Fail-modes for layer 1:
+ *   - File absent (genuine 404)   → undefined → canEditPage allows
+ *     (semantic: "no restrictions configured")
+ *   - File present and parsed     → list → canEditPage applies it
+ *   - Fetch failed / parse failed → 503, deny access (was a silent grant
+ *     before review finding #1).
+ */
+export async function guardPageAccess(
+  session: AuthSession | null,
+  pageKey: string,
+  fullConfig: SetzKastenConfig | undefined,
+  request?: Request,
+): Promise<Response | null> {
+  if (!session) return new Response('Unauthorized', { status: 401 })
+
+  // Layer 1: global editors file
+  const editorsLookup = await resolveDynamicEditors()
+  if (!editorsLookup.ok) {
+    return new Response(
+      `Forbidden: editor permissions unavailable (${editorsLookup.error})`,
+      { status: 503 },
+    )
+  }
+  if (!canEditPage(session, pageKey, editorsLookup.editors)) {
+    return new Response('Forbidden: you do not have access to this page', { status: 403 })
+  }
+
+  // Layer 2: per-website allowedEmails (multi-mode only). Requires the
+  // request so we can re-route through the website resolver. Routes that
+  // don't pass `request` skip this layer — kept optional so the existing
+  // call sites compile without a coordinated update.
+  if (request) {
+    const denied = await guardWebsiteAccess(session, request)
+    if (denied) return denied
+  }
+
+  return null
+}
+
+/**
+ * Per-website authorization. Editors must be listed on
+ * `WebsiteEntry.allowedEmails` to operate on the website that the
+ * X-SK-Website header resolves to. Admins always pass; single-mode
+ * skips this check entirely (no website context).
+ *
+ * Returns 403 on deny, null on allow. Resolver failures are
+ * considered "no per-website restriction" — the global guard above
+ * already covers fail-closed for editors-file errors.
+ */
+export async function guardWebsiteAccess(
+  session: AuthSession,
+  request: Request,
+): Promise<Response | null> {
+  if (session.user.role === 'admin') return null
+
+  const { resolveCurrentWebsite } = await import('./_website-resolver.js')
+  const website = await resolveCurrentWebsite(request)
+  if (!website.ok) return null
+
+  const allowed = website.value.allowedEmails
+  if (!allowed || allowed.length === 0) return null
+
+  if (!allowed.includes(session.user.email)) {
+    return new Response(
+      `Forbidden: not allowed on website "${website.value.id}"`,
+      { status: 403 },
+    )
+  }
+  return null
+}
+
+type EditorsLookup =
+  | { ok: true; editors: readonly ContentEditorConfig[] | undefined }
+  | { ok: false; error: string }
+
+async function resolveDynamicEditors(): Promise<EditorsLookup> {
+  const storage = resolveStorageConfig()
+  if (!storage) return { ok: true, editors: undefined }
+
+  const tokenResult = await resolveConfigRepoToken()
+  if (!tokenResult.ok) {
+    return { ok: false, error: `token: ${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 { ok: true, editors: undefined }
+  if (status.kind === 'present') return { ok: true, editors: status.editors }
+  return { ok: false, error: status.message }
+}

package/src/api-routes/_commit-trailers.ts

@@ -0,0 +1,16 @@
+export const SETZKASTEN_CO_AUTHOR = 'Co-authored-by: Setzkasten <setzkasten@setzkasten.dev>'
+
+/**
+ * Appends git commit trailers to a commit message.
+ * Always includes the Setzkasten co-author; optionally includes the editor.
+ */
+export function withTrailers(message: string, editorEmail?: string | null): string {
+  const trailers = [SETZKASTEN_CO_AUTHOR]
+  if (editorEmail) {
+    const name = editorEmail.split('@')[0]!
+      .replace(/[._-]+/g, ' ')
+      .replace(/\b\w/g, c => c.toUpperCase())
+    trailers.push(`Co-authored-by: ${name} <${editorEmail}>`)
+  }
+  return `${message}\n\n${trailers.join('\n')}`
+}

package/src/api-routes/_github-cache.ts

@@ -0,0 +1,32 @@
+interface CacheEntry<T> {
+  value: T
+  fetchedAt: number
+}
+
+const cache = new Map<string, CacheEntry<unknown>>()
+
+export async function cachedFetch<T>(
+  key: string,
+  ttlMs: number,
+  fetcher: () => Promise<T>,
+): Promise<T> {
+  const entry = cache.get(key) as CacheEntry<T> | undefined
+  const now = Date.now()
+
+  if (entry !== undefined && now - entry.fetchedAt < ttlMs) {
+    return entry.value
+  }
+
+  try {
+    const value = await fetcher()
+    cache.set(key, { value, fetchedAt: now })
+    return value
+  } catch (err) {
+    if (entry !== undefined) return entry.value
+    throw err
+  }
+}
+
+export function invalidateCache(key: string): void {
+  cache.delete(key)
+}

package/src/api-routes/_github-token.ts

@@ -0,0 +1,64 @@
+import { err, authError, type Result } from '@setzkasten-cms/core'
+import { GitHubAppClient } from '@setzkasten-cms/github-adapter'
+
+/**
+ * Token for the **config repo** (in multi mode) or the **website repo**
+ * (in single mode). Reads the App credentials straight from ENV — no
+ * X-SK-Website routing involved. Used by config-management endpoints
+ * (`/websites/add`, `/websites/remove`) and any read of `_global_config.json`
+ * / `_editors.json` that lives next to the registry, not next to the
+ * editable content.
+ *
+ * In single mode this is the only relevant token; in multi mode it is
+ * the token for the config repo, while per-website operations use
+ * {@link resolveGitHubTokenForRequest}.
+ */
+export async function resolveConfigRepoToken(): Promise<Result<string>> {
+  const appId = process.env.GITHUB_APP_ID
+  const privateKey = process.env.GITHUB_APP_PRIVATE_KEY
+  const installationId = process.env.GITHUB_APP_INSTALLATION_ID
+
+  if (appId && privateKey && installationId) {
+    const client = new GitHubAppClient(
+      { appId, privateKey, installationId },
+      { owner: '', repo: '', branch: '' },
+    )
+    return client.getInstallationToken()
+  }
+
+  return err(
+    authError(
+      'GitHub App not configured. Set GITHUB_APP_ID, GITHUB_APP_PRIVATE_KEY, and GITHUB_APP_INSTALLATION_ID.',
+    ),
+  )
+}
+
+/**
+ * Token for the website resolved from the request's `X-SK-Website` header.
+ * In multi mode this picks the installation id of the active website;
+ * in single mode the resolver synthesises one website from build-time
+ * storage and returns the same token as {@link resolveConfigRepoToken}.
+ *
+ * The PEM private key always comes from `GITHUB_APP_PRIVATE_KEY` — one
+ * App, many installations.
+ */
+export async function resolveGitHubTokenForRequest(request: Request): Promise<Result<string>> {
+  const { resolveCurrentWebsite } = await import('./_website-resolver.js')
+  const website = await resolveCurrentWebsite(request)
+  if (!website.ok) return website
+
+  const privateKey = process.env.GITHUB_APP_PRIVATE_KEY
+  if (!privateKey) {
+    return err(authError('GitHub App not configured. Set GITHUB_APP_PRIVATE_KEY.'))
+  }
+
+  const client = new GitHubAppClient(
+    {
+      appId: website.value.githubApp.appId,
+      installationId: website.value.githubApp.installationId,
+      privateKey,
+    },
+    { owner: '', repo: '', branch: '' },
+  )
+  return client.getInstallationToken()
+}

package/src/api-routes/_license-tier.ts

@@ -0,0 +1,25 @@
+import type { FeatureTier } from '@setzkasten-cms/core'
+
+/**
+ * Server-side license-tier lookup based on the configured license key.
+ *
+ * The prefix is the canonical signal:
+ *   SK-PRO-...  → 'pro'
+ *   SK-ENT-...  → 'enterprise'
+ *   anything else (or unset) → 'free'
+ *
+ * The updater backend does the real validation (revocation, expiry); this
+ * function is enough to enforce honest-user limits at the API boundary.
+ * A bad actor faking a prefix will get 200 here but be flagged on the next
+ * dashboard register call — and the limit gate is a deterrent, not a
+ * payment system.
+ *
+ * Reads `SETZKASTEN_LICENSE_KEY` from the env first; future versions may
+ * add a config-repo `_global_config.json` fallback.
+ */
+export function resolveLicenseTier(): FeatureTier {
+  const raw = process.env.SETZKASTEN_LICENSE_KEY?.trim() ?? ''
+  if (raw.startsWith('SK-PRO-')) return 'pro'
+  if (raw.startsWith('SK-ENT-')) return 'enterprise'
+  return 'free'
+}

package/src/api-routes/_pages-meta-store.ts

@@ -0,0 +1,134 @@
+import {
+  emptyPagesMeta,
+  err,
+  networkError,
+  ok,
+  parsePagesMeta,
+  setPageLastModified,
+  type PagesMeta,
+  type Result,
+} from '@setzkasten-cms/core'
+import { withTrailers } from './_commit-trailers'
+
+/**
+ * Server-side read/write helpers for `_pages-meta.json`.
+ *
+ * - `readPagesMeta` returns the parsed registry plus its current SHA, or
+ *   an empty registry with `sha: null` when the file does not exist.
+ * - `recordPageEdit` updates a single page's `lastModified` timestamp and
+ *   commits back, retrying once on 409 (concurrent edit). Failures
+ *   propagate as network errors so callers can decide whether to log
+ *   silently or surface them.
+ */
+
+export interface PagesMetaTarget {
+  readonly owner: string
+  readonly repo: string
+  readonly branch: string
+  readonly contentPath: string
+  readonly token: string
+}
+
+interface PagesMetaSnapshot {
+  readonly meta: PagesMeta
+  readonly sha: string | null
+}
+
+const RELATIVE_PATH = '_pages-meta.json'
+// Spec: up to 3 attempts, then silent fail. With 5+ mutating routes firing
+// concurrently on a busy dashboard, the third attempt absorbs the burst.
+const MAX_RETRIES = 3
+
+function metaFilePath(contentPath: string): string {
+  return `${contentPath}/${RELATIVE_PATH}`
+}
+
+function ghHeaders(token: string) {
+  return {
+    Authorization: `Bearer ${token}`,
+    Accept: 'application/vnd.github+json',
+    'X-GitHub-Api-Version': '2022-11-28',
+    'Content-Type': 'application/json',
+  }
+}
+
+function ghContentsUrl(target: PagesMetaTarget): string {
+  return `https://api.github.com/repos/${target.owner}/${target.repo}/contents/${metaFilePath(target.contentPath)}`
+}
+
+export async function readPagesMeta(target: PagesMetaTarget): Promise<Result<PagesMetaSnapshot>> {
+  try {
+    const res = await fetch(`${ghContentsUrl(target)}?ref=${target.branch}`, {
+      headers: ghHeaders(target.token),
+    })
+
+    if (res.status === 404) {
+      return ok({ meta: emptyPagesMeta(), sha: null })
+    }
+    if (!res.ok) {
+      return err(networkError(`GitHub returned ${res.status} reading ${RELATIVE_PATH}`))
+    }
+
+    const data = (await res.json()) as { content: string; sha: string }
+    const decoded = Buffer.from(data.content, 'base64').toString('utf-8')
+    const parsed = parsePagesMeta(decoded)
+    if (!parsed.ok) return parsed
+    return ok({ meta: parsed.value, sha: data.sha })
+  } catch (cause) {
+    const message = cause instanceof Error ? cause.message : 'Unknown error'
+    return err(networkError(`Failed to read ${RELATIVE_PATH}: ${message}`, cause))
+  }
+}
+
+async function writePagesMeta(
+  target: PagesMetaTarget,
+  next: PagesMeta,
+  previousSha: string | null,
+): Promise<Response> {
+  const body: Record<string, unknown> = {
+    message: withTrailers('chore(meta): update _pages-meta.json'),
+    content: Buffer.from(JSON.stringify(next, null, 2)).toString('base64'),
+    branch: target.branch,
+  }
+  if (previousSha) body.sha = previousSha
+
+  return fetch(ghContentsUrl(target), {
+    method: 'PUT',
+    headers: ghHeaders(target.token),
+    body: JSON.stringify(body),
+  })
+}
+
+/**
+ * Records that `pageKey` was just edited. Reads the meta, sets the
+ * timestamp, writes back. On a 409 conflict (someone else committed
+ * meanwhile) the function re-reads and retries up to MAX_RETRIES times.
+ */
+export async function recordPageEdit(
+  target: PagesMetaTarget,
+  pageKey: string,
+  timestamp = Date.now(),
+): Promise<Result<void>> {
+  for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+    const current = await readPagesMeta(target)
+    if (!current.ok) return current
+
+    const next = setPageLastModified(current.value.meta, pageKey, timestamp)
+
+    let response: Response
+    try {
+      response = await writePagesMeta(target, next, current.value.sha)
+    } catch (cause) {
+      const message = cause instanceof Error ? cause.message : 'Unknown error'
+      return err(networkError(`Failed to write ${RELATIVE_PATH}: ${message}`, cause))
+    }
+
+    if (response.ok) return ok(undefined)
+    if (response.status === 409 && attempt < MAX_RETRIES - 1) continue
+
+    const text = await response.text().catch(() => '')
+    return err(networkError(`GitHub PUT failed: ${response.status} ${text}`))
+  }
+
+  return err(networkError(`recordPageEdit: exhausted ${MAX_RETRIES} retries`))
+}

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
+}