@setzkasten-cms/astro-admin 0.8.0 → 1.3.0

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

@@ -0,0 +1,112 @@
+/**
+ * @vitest-environment node
+ */
+
+import { type Result, type WebsiteEntry, ok } from '@setzkasten-cms/core'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { __resetWebsiteResolverForTests } from '../_website-resolver'
+
+const ENTRY_A: WebsiteEntry = {
+  id: 'site-a',
+  name: 'Site A',
+  repo: 'acme/site-a',
+  branch: 'main',
+  previewOrigin: 'https://a.example.com',
+  githubApp: { appId: '1', installationId: '101' },
+}
+
+const ENTRY_B: WebsiteEntry = {
+  id: 'site-b',
+  name: 'Site B',
+  repo: 'acme/site-b',
+  branch: 'develop',
+  previewOrigin: 'https://b.example.com',
+  githubApp: { appId: '1', installationId: '202' },
+  allowedEmails: ['secret@example.com'],
+}
+
+function makeRegistry(entries: readonly WebsiteEntry[]) {
+  return {
+    list: vi.fn(async (): Promise<Result<readonly WebsiteEntry[]>> => ok(entries)),
+    get: vi.fn(async (id: string): Promise<Result<WebsiteEntry | null>> => {
+      return ok(entries.find((e) => e.id === id) ?? null)
+    }),
+  }
+}
+
+function makeCtx(sessionValue?: string) {
+  return {
+    request: new Request('https://cms.example.com/api/setzkasten/websites'),
+    cookies: {
+      get: vi.fn((name: string) =>
+        name === 'setzkasten_session' && sessionValue ? { value: sessionValue } : undefined,
+      ),
+    },
+  }
+}
+
+import { GET } from '../websites-list'
+
+describe('GET /api/setzkasten/websites', () => {
+  afterEach(() => __resetWebsiteResolverForTests(null))
+
+  it('returns 401 when no session cookie is present', async () => {
+    __resetWebsiteResolverForTests({ mode: 'multi', registry: makeRegistry([ENTRY_A]) })
+
+    const res = await (GET as (ctx: unknown) => Promise<Response>)(makeCtx())
+
+    expect(res.status).toBe(401)
+  })
+
+  it('returns the list of websites when authenticated', async () => {
+    __resetWebsiteResolverForTests({
+      mode: 'multi',
+      registry: makeRegistry([ENTRY_A, ENTRY_B]),
+    })
+
+    const res = await (GET as (ctx: unknown) => Promise<Response>)(makeCtx('valid'))
+    const body = await res.json()
+
+    expect(res.status).toBe(200)
+    expect(body.websites).toHaveLength(2)
+    expect(body.websites[0].id).toBe('site-a')
+    expect(body.websites[1].id).toBe('site-b')
+  })
+
+  it('does not expose githubApp installation ids in the response', async () => {
+    __resetWebsiteResolverForTests({
+      mode: 'multi',
+      registry: makeRegistry([ENTRY_B]),
+    })
+
+    const res = await (GET as (ctx: unknown) => Promise<Response>)(makeCtx('valid'))
+    const body = await res.json()
+
+    expect(body.websites[0]).not.toHaveProperty('githubApp')
+    expect(JSON.stringify(body)).not.toContain('202')
+  })
+
+  it('does not expose allowedEmails in the response', async () => {
+    __resetWebsiteResolverForTests({
+      mode: 'multi',
+      registry: makeRegistry([ENTRY_B]),
+    })
+
+    const res = await (GET as (ctx: unknown) => Promise<Response>)(makeCtx('valid'))
+    const body = await res.json()
+
+    expect(body.websites[0]).not.toHaveProperty('allowedEmails')
+    expect(JSON.stringify(body)).not.toContain('secret@example.com')
+  })
+
+  it('returns the synthesized entry in single-repo mode', async () => {
+    __resetWebsiteResolverForTests({ mode: 'single', synthesized: ENTRY_A })
+
+    const res = await (GET as (ctx: unknown) => Promise<Response>)(makeCtx('valid'))
+    const body = await res.json()
+
+    expect(res.status).toBe(200)
+    expect(body.websites).toHaveLength(1)
+    expect(body.websites[0].id).toBe(ENTRY_A.id)
+  })
+})

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

@@ -1,10 +1,9 @@
 import { canEditPage } from '@setzkasten-cms/auth'
-import type { AuthSession, SetzKastenConfig } from '@setzkasten-cms/core'
+import type { AuthSession, ContentEditorConfig, SetzKastenConfig } from '@setzkasten-cms/core'
+import { resolveStorageConfig } from './_storage-config'
+import { resolveConfigRepoToken } from './_github-token'
+import { readEditorsFileStatus } from './editors'
 
-/**
- * Parses the raw session cookie value.
- * Returns null if missing or invalid.
- */
 export function parseSession(raw: string | undefined): AuthSession | null {
   if (!raw) return null
   try {
@@ -15,18 +14,140 @@ export function parseSession(raw: string | undefined): AuthSession | null {
 }
 
 /**
- * Returns a 403 Response if the session user may NOT edit the given page.
- * Returns null (= allowed) otherwise.
+ * 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:
  *
- * Admins always pass. Editors are checked against config.auth.editors.
+ *   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 function guardPageAccess(
+export async function guardPageAccess(
   session: AuthSession | null,
   pageKey: string,
   fullConfig: SetzKastenConfig | undefined,
-): Response | null {
+  request?: Request,
+): Promise<Response | null> {
   if (!session) return new Response('Unauthorized', { status: 401 })
-  if (!fullConfig) return null // no config = no restrictions
-  if (canEditPage(session, pageKey, fullConfig)) return null
-  return new Response('Forbidden: you do not have access to this page', { status: 403 })
+
+  // 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/_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/_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`))
+}