@acms-subir/core 0.3.3-next.20260929113209 → 0.3.3

package/src/lib/editor/auth.ts

@@ -0,0 +1,264 @@
+import { Role } from '../schema';
+import { createHmac } from 'node:crypto';
+import { env } from '../env';
+import { sha256Hex } from '../api-keys';
+import { ApiError } from '../api';
+import { redirectUriProblem } from '../mobile/config.mjs';
+import type { ContentRepository } from '../repo/types';
+import { EDITOR } from './config';
+
+// Editor-app sign-in: OAuth 2.0 authorization code + PKCE (RFC 6749, 7636)
+// for native apps (RFC 8252). The app opens /admin/app-auth in the system
+// browser, the signed-in person approves, the browser returns to the app's
+// allowlisted redirect URI with a one-time code, and the app trades code +
+// verifier for per-device tokens. The app never sees a password or cookie.
+//
+// Secrets: opaque random tokens with recognizable prefixes, stored only as
+// SHA-256 hashes. Access tokens are short-lived; refresh tokens rotate on
+// every use, and presenting a rotated one revokes the whole device (theft) —
+// unless it is a retry within a short grace window whose previous answer was
+// never used (a lost network response), see tokenGrant.
+// The role is read live from the user on every request, never frozen.
+
+export const ACCESS_PREFIX = 'acms_dev_a_';
+export const REFRESH_PREFIX = 'acms_dev_r_';
+export const CODE_PREFIX = 'acms_code_';
+const TOKEN_BODY = /^[0-9a-f]{64}$/;
+
+const hex = (bytes: Uint8Array) => [...bytes].map((b) => b.toString(16).padStart(2, '0')).join('');
+export const randomToken = (prefix: string) => prefix + hex(crypto.getRandomValues(new Uint8Array(32)));
+const wellFormed = (token: string, prefix: string) => token.startsWith(prefix) && TOKEN_BODY.test(token.slice(prefix.length));
+
+/** constant-time string comparison (length leaks, content doesn't) */
+export function safeEqual(a: string, b: string): boolean {
+  const len = Math.max(a.length, b.length);
+  let diff = a.length ^ b.length;
+  for (let i = 0; i < len; i++) diff |= (a.charCodeAt(i) || 0) ^ (b.charCodeAt(i) || 0);
+  return diff === 0;
+}
+
+const base64url = (bytes: Uint8Array) => btoa(String.fromCharCode(...bytes)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+/** PKCE S256: BASE64URL(SHA256(ASCII(verifier))) */
+export async function s256(verifier: string): Promise<string> {
+  return base64url(new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier))));
+}
+
+// ---- redirect URIs ---------------------------------------------------------
+
+const LOOPBACK = new Set(['127.0.0.1', '[::1]', 'localhost']);
+/**
+ * Exact match against acms({ mobile: { editor: { redirectUris } } }). The one
+ * exception (RFC 8252 §7.3): an http loopback entry matches any port, since
+ * the OS picks the app's listening port at run time.
+ */
+export function allowedRedirect(uri: string): boolean {
+  if (!uri || redirectUriProblem(uri)) return false;
+  return EDITOR.redirectUris.some((allowed) => {
+    if (allowed === uri) return true;
+    try {
+      const a = new URL(allowed), b = new URL(uri);
+      return a.protocol === 'http:' && b.protocol === 'http:' && LOOPBACK.has(a.hostname) && a.hostname === b.hostname
+        && a.pathname === b.pathname && a.search === b.search;
+    } catch { return false; }
+  });
+}
+
+export function redirectWith(uri: string, params: Record<string, string>): string {
+  const url = new URL(uri);
+  for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
+  return url.href;
+}
+
+// ---- the authorization request ---------------------------------------------
+
+export interface AuthorizeParams { clientId: string; redirectUri: string; codeChallenge: string; state: string; deviceName: string }
+export type AuthorizeCheck =
+  | { ok: true; params: AuthorizeParams }
+  /** redirect=false: the client or return address can't be trusted, so the error is shown in the browser */
+  | { ok: false; error: string; message: string; redirect: false }
+  | { ok: false; error: string; message: string; redirect: true; redirectUri: string; state: string };
+
+const CLIENT_ID = /^[A-Za-z0-9._:-]{1,100}$/;
+const CHALLENGE = /^[A-Za-z0-9_-]{43}$/;
+const STATE = /^[\x21-\x7e]{1,500}$/;
+const VERIFIER = /^[A-Za-z0-9._~-]{43,128}$/;
+const KNOWN = ['response_type', 'client_id', 'redirect_uri', 'code_challenge', 'code_challenge_method', 'state', 'device_name', 'scope'];
+
+export function cleanDeviceName(raw: string): string {
+  return raw.replace(/[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u2028-\u202e\u2066-\u2069]/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 60);
+}
+
+export function checkAuthorize(search: URLSearchParams): AuthorizeCheck {
+  const one = (k: string) => search.getAll(k).length > 1 ? null : (search.get(k) ?? '');
+  const clientId = one('client_id'), redirectUri = one('redirect_uri');
+  if (clientId === null || !CLIENT_ID.test(clientId)) return { ok: false, error: 'invalid_client', message: 'The app didn’t say who it is (client_id).', redirect: false };
+  if (redirectUri === null || !allowedRedirect(redirectUri)) {
+    return { ok: false, error: 'invalid_redirect_uri', message: 'This app’s return address isn’t on this site’s list of allowed editor apps. The site owner adds it in acms({ mobile: { editor: { redirectUris } } }).', redirect: false };
+  }
+  const state = one('state');
+  const fail = (error: string, message: string): AuthorizeCheck => ({ ok: false, error, message, redirect: true, redirectUri, state: state && STATE.test(state) ? state : '' });
+  if (KNOWN.some((k) => search.getAll(k).length > 1)) return fail('invalid_request', 'A sign-in parameter was repeated.');
+  if (one('response_type') !== 'code') return fail('unsupported_response_type', 'Only response_type=code is supported.');
+  if (one('code_challenge_method') !== 'S256') return fail('invalid_request', 'PKCE with code_challenge_method=S256 is required.');
+  const codeChallenge = one('code_challenge') ?? '';
+  if (!CHALLENGE.test(codeChallenge)) return fail('invalid_request', 'code_challenge must be a 43-character base64url S256 hash.');
+  if (!state || !STATE.test(state)) return fail('invalid_request', 'state is required (1–500 visible ASCII characters).');
+  return { ok: true, params: { clientId, redirectUri, codeChallenge, state, deviceName: cleanDeviceName(one('device_name') ?? '') } };
+}
+
+// ---- consent form ticket (CSRF) ----------------------------------------------
+// The approve form carries an HMAC bound to this browser's session cookie and
+// to the exact request (app, return address, challenge, state), valid ten
+// minutes. A forged or replayed-elsewhere POST can't produce one.
+
+const TICKET_MS = 10 * 60_000;
+function ticketSig(session: string, p: AuthorizeParams, exp: number) {
+  const secret = env('SESSION_SECRET');
+  if (!secret) throw new Error('SESSION_SECRET is not set — add it to .env');
+  return createHmac('sha256', secret).update(JSON.stringify(['acms-app-auth-v1', session, p.clientId, p.redirectUri, p.codeChallenge, p.state, exp])).digest('hex');
+}
+export function consentTicket(session: string, p: AuthorizeParams, now = Date.now()): string {
+  const exp = now + TICKET_MS;
+  return `${exp}.${ticketSig(session, p, exp)}`;
+}
+export function checkConsentTicket(ticket: string, session: string, p: AuthorizeParams, now = Date.now()): boolean {
+  const [expRaw, sig] = ticket.split('.');
+  const exp = Number(expRaw);
+  if (!session || !sig || !/^\d{10,16}$/.test(expRaw ?? '') || exp < now || exp > now + TICKET_MS) return false;
+  return safeEqual(sig, ticketSig(session, p, exp));
+}
+
+/** approve: a one-time code bound to the user, app, return address and challenge */
+export async function issueCode(repo: ContentRepository, user: { id: string; sessionVersion: number }, p: AuthorizeParams, deviceName: string, now = Date.now()): Promise<string> {
+  const code = randomToken(CODE_PREFIX);
+  await repo.editor.createCode({ hash: await sha256Hex(code), userId: user.id, clientId: p.clientId, redirectUri: p.redirectUri,
+    challenge: p.codeChallenge, deviceName: cleanDeviceName(deviceName) || 'Phone', sessionVersion: user.sessionVersion, expiresAt: now + EDITOR.codeMs }, now);
+  return code;
+}
+
+// ---- token endpoint --------------------------------------------------------
+
+export class OAuthError extends Error {
+  constructor(public status: number, public error: string, message: string) { super(message); }
+}
+const invalidGrant = (why: string) => new OAuthError(400, 'invalid_grant', why);
+
+export interface TokenResponse {
+  access_token: string; token_type: 'Bearer'; expires_in: number;
+  refresh_token: string; refresh_token_expires_in: number;
+  user: { id: string; name: string; email: string; role: Role };
+  device: { id: string; name: string };
+}
+
+async function pair(now: number) {
+  const access = randomToken(ACCESS_PREFIX), refresh = randomToken(REFRESH_PREFIX);
+  return { plain: { access, refresh }, hashed: { access: await sha256Hex(access), accessExpires: now + EDITOR.accessTokenMs, refresh: await sha256Hex(refresh), refreshExpires: now + EDITOR.refreshTokenMs } };
+}
+async function liveUser(repo: ContentRepository, id: string, sessionVersion: number) {
+  const [user, version] = await Promise.all([repo.getUser(id), repo.email.sessionVersion(id)]);
+  return user && version === sessionVersion ? user : null;
+}
+function tokenResponse(t: { access: string; refresh: string }, user: { id: string; name: string; email: string; role: string }, device: { id: string; name: string }): TokenResponse {
+  return { access_token: t.access, token_type: 'Bearer', expires_in: Math.floor(EDITOR.accessTokenMs / 1000), refresh_token: t.refresh,
+    refresh_token_expires_in: Math.floor(EDITOR.refreshTokenMs / 1000),
+    user: { id: user.id, name: user.name, email: user.email, role: Role.parse(user.role) }, device };
+}
+
+export async function tokenGrant(repo: ContentRepository, form: Record<string, string>, now = Date.now()): Promise<TokenResponse> {
+  const grant = form.grant_type;
+  if (grant === 'authorization_code') {
+    const { code = '', code_verifier: verifier = '', redirect_uri: redirectUri = '', client_id: clientId = '' } = form;
+    if (!code || !verifier || !redirectUri || !clientId) throw new OAuthError(400, 'invalid_request', 'code, code_verifier, redirect_uri and client_id are required.');
+    if (!wellFormed(code, CODE_PREFIX)) throw invalidGrant('The sign-in code is invalid or expired.');
+    const spent = await repo.editor.consumeCode(await sha256Hex(code), now);
+    if (!spent) throw invalidGrant('The sign-in code is invalid or expired.');
+    const c = spent.code;
+    if (spent.reused) {
+      // a replayed code means it leaked: whatever it produced is signed out
+      if (c.deviceId) await repo.editor.revokeDevice(c.deviceId, 'sign-in code reused', now);
+      throw invalidGrant('The sign-in code was already used.');
+    }
+    if (c.expiresAt <= now) throw invalidGrant('The sign-in code expired. Sign in again.');
+    // every check runs; the code is already burned whatever the outcome
+    const checks = [safeEqual(clientId, c.clientId), safeEqual(redirectUri, c.redirectUri), VERIFIER.test(verifier) && safeEqual(await s256(verifier), c.challenge), allowedRedirect(c.redirectUri)];
+    if (checks.includes(false)) throw invalidGrant('The sign-in code doesn’t match this app, return address or verifier.');
+    const user = await liveUser(repo, c.userId, c.sessionVersion);
+    if (!user) throw invalidGrant('This account changed since sign-in. Sign in again.');
+    const device = { id: crypto.randomUUID(), name: c.deviceName };
+    const t = await pair(now);
+    await repo.editor.createDevice({ id: device.id, userId: user.id, name: device.name, clientId: c.clientId, sessionVersion: c.sessionVersion }, t.hashed, now);
+    await repo.editor.bindCode(c.hash, device.id);
+    await repo.editor.prune(now).catch(() => {});
+    return tokenResponse(t.plain, user, device);
+  }
+  if (grant === 'refresh_token') {
+    const token = form.refresh_token ?? '';
+    if (!token) throw new OAuthError(400, 'invalid_request', 'refresh_token is required.');
+    if (!wellFormed(token, REFRESH_PREFIX)) throw invalidGrant('The refresh token is invalid or expired.');
+    const hash = await sha256Hex(token);
+    const spent = await repo.editor.spendRefresh(hash, now);
+    if (!spent) throw invalidGrant('The refresh token is invalid or expired.');
+    // A rotated token presented again is theft, except for a short grace: the
+    // app retrying a refresh whose response it lost (the pair it produced was
+    // never used). That retry gets a new pair; the lost one is retired.
+    if (spent.reused && (spent.expired || !await repo.editor.retireUnusedSuccessor(hash, spent.usedAt ?? 0, now, EDITOR.refreshGraceMs))) {
+      await repo.editor.revokeDevice(spent.deviceId, 'refresh token reused', now);
+      throw invalidGrant('This refresh token was already used, so the device was signed out. Sign in again.');
+    }
+    if (spent.expired) throw invalidGrant('The session expired. Sign in again.');
+    const device = await repo.editor.getDevice(spent.deviceId);
+    if (!device || device.revokedAt !== null) throw invalidGrant('This device was signed out. Sign in again.');
+    if (form.client_id && !safeEqual(form.client_id, device.clientId)) throw invalidGrant('The refresh token belongs to another app.');
+    const user = await liveUser(repo, device.userId, device.sessionVersion);
+    if (!user) {
+      await repo.editor.revokeDevice(device.id, 'account changed', now);
+      throw invalidGrant('This account changed. Sign in again.');
+    }
+    const t = await pair(now);
+    await repo.editor.rotate(device.id, t.hashed, now, hash);
+    return tokenResponse(t.plain, user, { id: device.id, name: device.name });
+  }
+  throw new OAuthError(400, 'unsupported_grant_type', 'Use grant_type=authorization_code or refresh_token.');
+}
+
+/** sign out (RFC 7009): either token revokes its device; unknown tokens succeed silently */
+export async function revokeToken(repo: ContentRepository, token: string, now = Date.now()) {
+  if (!wellFormed(token, ACCESS_PREFIX) && !wellFormed(token, REFRESH_PREFIX)) return;
+  const deviceId = await repo.editor.deviceForToken(await sha256Hex(token));
+  if (deviceId) await repo.editor.revokeDevice(deviceId, 'signed out in the app', now);
+}
+
+// ---- bearer authentication for /api/v1/admin/* -----------------------------
+
+export interface EditorPrincipal {
+  user: { id: string; name: string; email: string; role: Role };
+  device: { id: string; name: string; clientId: string };
+  /** how writes are attributed: "editor:<id> via <device>" */
+  actor: string;
+}
+
+export function bearerToken(request: Request): string {
+  const auth = request.headers.get('authorization') ?? '';
+  const m = /^Bearer[ ]+([^\s]+)\s*$/i.exec(auth);
+  return m ? m[1] : '';
+}
+
+/** Device access tokens only: cookie sessions never authenticate here (no CSRF surface). */
+export async function authenticateDevice(request: Request, repo: ContentRepository, now = Date.now()): Promise<EditorPrincipal> {
+  const token = bearerToken(request);
+  if (!token) throw new ApiError(401, 'Sign in through the app: send Authorization: Bearer <access token>.');
+  if (!wellFormed(token, ACCESS_PREFIX)) throw new ApiError(401, 'The access token is invalid or expired.');
+  const access = await repo.editor.access(await sha256Hex(token), now);
+  if (!access) throw new ApiError(401, 'The access token is invalid, expired or signed out.');
+  if (access.user.sessionVersion !== access.device.sessionVersion) {
+    await repo.editor.revokeDevice(access.device.id, 'password changed', now);
+    throw new ApiError(401, 'This account changed. Sign in again.');
+  }
+  await repo.editor.touch(access.device.id, now);
+  const { user, device } = access;
+  return {
+    user: { id: user.id, name: user.name, email: user.email, role: user.role },
+    device: { id: device.id, name: device.name, clientId: device.clientId },
+    actor: `${user.role}:${user.id} via ${device.name}`.slice(0, 200),
+  };
+}

package/src/lib/editor/bookings.ts

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+import type { ContentRepository } from '../repo/types';
+import type { Booking, BookingStatus } from '../schema';
+import { ApiError } from '../api';
+import { bookingsEnabled } from '../calendar/config';
+import { bookingJson, setBookingStatus } from '../booking/service';
+import { siteOrigin } from '../seo';
+import { waitUntilFrom } from '../webhooks';
+import { pageQuery } from '../mobile/http';
+
+// Bookings inbox for editor apps: the same status changes as Admin →
+// Bookings (confirm, decline, cancel; the guest is emailed, webhooks fire),
+// available to every signed-in owner or editor exactly like the web page.
+
+export const InboxQuery = z.object({
+  /** active = pending + confirmed (default); pending requests always sort first */
+  status: z.enum(['active', 'pending', 'confirmed', 'declined', 'cancelled', 'all']).default('active'),
+  from: z.string().datetime({ offset: true }).optional(),
+  ...pageQuery,
+}).strict();
+export const BookingActionInput = z.object({ message: z.string().max(1000).optional() }).strict();
+
+export function requireBookings() {
+  if (!bookingsEnabled()) throw new ApiError(404, 'Bookings are turned off on this site.');
+}
+
+export async function inbox(repo: ContentRepository, q: z.infer<typeof InboxQuery>, now = Date.now()) {
+  requireBookings();
+  const statuses: BookingStatus[] | undefined = q.status === 'all' ? undefined : q.status === 'active' ? ['pending', 'confirmed'] : [q.status];
+  const [list, resources, events] = await Promise.all([
+    repo.listBookings({ from: q.from ? Date.parse(q.from) : now - 86_400_000, statuses, kinds: ['booking', 'rsvp'] }),
+    repo.listResources(), repo.listEvents(),
+  ]);
+  const res = new Map(resources.map((r) => [r.id, r.name])), ev = new Map(events.map((e) => [e.id, e.title]));
+  list.sort((a, b) => Number(b.status === 'pending') - Number(a.status === 'pending') || a.start - b.start);
+  const start = (q.page - 1) * q.limit;
+  return {
+    pending: list.filter((b) => b.status === 'pending').length,
+    items: list.slice(start, start + q.limit).map((b) => bookingView(b, res, ev)),
+    pagination: { page: q.page, limit: q.limit, nextPage: start + q.limit < list.length ? q.page + 1 : null },
+  };
+}
+
+function bookingView(b: Booking, res: Map<string, string>, ev: Map<string, string>) {
+  return { ...bookingJson(b), title: b.kind === 'rsvp' ? ev.get(b.eventId) ?? 'Event' : res.get(b.resourceId) ?? 'Booking', notes: b.notes, updatedAt: new Date(b.updatedAt).toISOString() };
+}
+
+const TO: Record<string, BookingStatus> = { approve: 'confirmed', decline: 'declined', cancel: 'cancelled' };
+
+export async function bookingAction(repo: ContentRepository, id: string, action: string, body: z.infer<typeof BookingActionInput>, ctx: { url: URL; locals: unknown }) {
+  requireBookings();
+  const to = TO[action];
+  if (!to) throw new ApiError(404, 'Unknown action.');
+  const b = await repo.getBooking(id);
+  if (!b || b.kind === 'block') throw new ApiError(404, 'Booking not found.');
+  const flow = { origin: siteOrigin(await repo.getSettings(), ctx.url), locals: ctx.locals, waitUntil: waitUntilFrom(ctx.locals) };
+  const next = await setBookingStatus(repo, b, to, flow, body.message?.trim() || undefined);
+  const [resources, events] = await Promise.all([repo.listResources(), repo.listEvents()]);
+  return bookingView(next, new Map(resources.map((r) => [r.id, r.name])), new Map(events.map((e) => [e.id, e.title])));
+}

package/src/lib/editor/config.ts

@@ -0,0 +1,25 @@
+// Editor apps: staff sign in on a phone through the browser (OAuth 2.0 +
+// PKCE) and edit through /api/v1/admin/*. Configured per project:
+//   acms({ mobile: { editor: { name: 'Grace Staff', redirectUris: ['org.grace.staff://auth'] } } })
+// Off unless redirect URIs are listed: the sign-in page, token endpoints and
+// /api/v1/admin/* are then not registered at all, and nothing issues codes.
+import { userConfig } from 'virtual:acms-config';
+import { ApiError } from '../api';
+
+const cfg = userConfig.mobile?.editor;
+
+// mutable so tests can exercise both states
+export const EDITOR = {
+  enabled: cfg?.enabled === true && (cfg?.redirectUris?.length ?? 0) > 0,
+  name: cfg?.name ?? '',
+  redirectUris: [...(cfg?.redirectUris ?? [])] as string[],
+  accessTokenMs: (cfg?.accessTokenMinutes ?? 60) * 60_000,
+  refreshTokenMs: (cfg?.refreshTokenDays ?? 90) * 86_400_000,
+  codeMs: 120_000,
+  /** a retried refresh within this window, whose answer was never used, isn't treated as theft */
+  refreshGraceMs: 60_000,
+};
+
+export function requireEditorApps() {
+  if (!EDITOR.enabled) throw new ApiError(404, 'This feature is disabled.');
+}

package/src/lib/editor/documents.ts

@@ -0,0 +1,227 @@
+import { z } from 'zod';
+import type { ContentRepository } from '../repo/types';
+import type { CalEvent, DocTranslations, Page, Post } from '../schema';
+import { slugify } from '../schema';
+import { ApiError } from '../api';
+import { CONTENT, collectionUrl } from '../content';
+import { CALENDAR, eventUrl } from '../calendar/config';
+import { normalizeEventTimes } from '../calendar/events';
+import { draftSavedAt, mergeEventDraft, mergePageDraft, mergePostDraft, pickEventDraft, pickPageDraft, pickPostDraft } from '../drafts';
+import { localeHomeUrl } from '../i18n';
+import { pageQuery } from '../mobile/http';
+import { applyEventUpdate, applyPageUpdate, applyPostUpdate, saveEvent, savePage, savePost, type SaveHooks } from '../content-service';
+
+// Posts, pages and events for editor apps. Reads show the document as it
+// will look after Update (staged edits merged); writes go through the same
+// content service as the admin editor, so live documents stage their edits
+// and every validation, redirect and side effect is identical. Staff have
+// the same document rights here as in the web admin.
+
+export type DocKind = 'post' | 'page' | 'event';
+type AnyDoc = Post | Page | CalEvent;
+export const DocKindParam = z.enum(['post', 'page', 'event']);
+
+export function kindEnabled(kind: DocKind) {
+  if (kind === 'event' && !CALENDAR.enabled) throw new ApiError(404, 'The calendar is turned off on this site.');
+}
+export async function loadDoc(repo: ContentRepository, kind: DocKind, id: string): Promise<AnyDoc> {
+  kindEnabled(kind);
+  const doc = kind === 'post' ? await repo.getPost(id) : kind === 'page' ? await repo.getPage(id) : await repo.getEvent(id);
+  if (!doc) throw new ApiError(404, `${kind === 'post' ? 'Post' : kind === 'page' ? 'Page' : 'Event'} not found.`);
+  return doc;
+}
+/** changes whenever the live row or its staged draft changes */
+export const revisionOf = (doc: AnyDoc) => `${doc.updatedAt}.${draftSavedAt(doc) ?? 0}`;
+export function checkRevision(doc: AnyDoc, revision: string) {
+  if (revision !== revisionOf(doc)) throw new ApiError(409, 'This document changed since you loaded it. Reload it and try again.');
+}
+/**
+ * Run a revision-checked write under the document's save lock: the revision
+ * check and the write happen as one step, so of two concurrent saves from
+ * the same revision exactly one wins and the other gets 409.
+ */
+export async function withDocLock<T>(repo: ContentRepository, kind: DocKind, id: string, work: () => Promise<T>): Promise<T> {
+  const key = `doc:${kind}:${id}`;
+  if (!await repo.editor.claim(key, Date.now())) throw new ApiError(409, 'Someone else is saving this document right now. Reload it and try again.');
+  try { return await work(); } finally { await repo.editor.release(key).catch(() => {}); }
+}
+export function mergedDoc(kind: DocKind, doc: AnyDoc): AnyDoc {
+  return kind === 'post' ? mergePostDraft(doc as Post) : kind === 'page' ? mergePageDraft(doc as Page) : mergeEventDraft(doc as CalEvent);
+}
+const iso = (ms: number | null | undefined) => (ms ? new Date(ms).toISOString() : null);
+const urlOf = (kind: DocKind, d: AnyDoc) => kind === 'post' ? collectionUrl((d as Post).collection, d.slug)
+  : kind === 'page' ? ((d as Page).isHome ? localeHomeUrl((d as Page).locale) : `/${d.slug}`) : eventUrl(d.slug);
+const imageOf = (kind: DocKind, d: AnyDoc) => (kind === 'page' ? '' : (d as Post | CalEvent).cover ?? '');
+
+export function summaryJson(kind: DocKind, raw: AnyDoc) {
+  const d = mergedDoc(kind, raw);
+  return {
+    id: raw.id, kind, collection: kind === 'post' ? (d as Post).collection : null, title: d.title, slug: d.slug, status: raw.status,
+    hasChanges: Boolean(raw.draft), url: urlOf(kind, raw), image: imageOf(kind, d), updatedAt: iso(raw.updatedAt)!, revision: revisionOf(raw),
+  };
+}
+
+export function docJson(kind: DocKind, raw: AnyDoc) {
+  const d = mergedDoc(kind, raw) as AnyDoc & Partial<Post & Page & CalEvent>;
+  return {
+    ...summaryJson(kind, raw),
+    excerpt: kind === 'page' ? '' : d.excerpt ?? '', bodyHtml: d.bodyHtml ?? '', tags: d.tags ?? [], cover: d.cover ?? '', coverAlt: d.coverAlt ?? '',
+    seoTitle: d.seoTitle ?? '', seoDesc: d.seoDesc ?? '', featured: Boolean(d.featured), template: d.template ?? '',
+    authorIds: kind === 'post' ? (d as Post).authorIds : [], locale: kind === 'page' ? (d as Page).locale || null : null, isHome: kind === 'page' ? (d as Page).isHome : false,
+    publishedAt: iso((raw as Post | CalEvent).publishedAt), scheduledAt: iso((raw as Post | CalEvent).scheduledAt), createdAt: iso(raw.createdAt)!,
+    event: kind === 'event' ? {
+      start: d.start!, end: d.end!, allDay: Boolean(d.allDay), timezone: d.timezone ?? '', rrule: d.rrule ?? '', exdates: d.exdates ?? [], cancelled: Boolean(d.cancelled),
+      location: d.location!, cta: d.cta!, calendarIds: d.calendarIds ?? [], fields: d.fields ?? {}, rsvp: d.rsvp!,
+    } : null,
+    languages: Object.keys((d.translations ?? {}) as DocTranslations),
+  };
+}
+
+// ---- list ----------------------------------------------------------------
+
+export const listQuery = z.object({
+  kind: DocKindParam.default('post'),
+  collection: z.string().max(100).optional(),
+  status: z.enum(['draft', 'scheduled', 'published', 'archived', 'changed']).optional(),
+  q: z.string().max(200).optional(),
+  ...pageQuery,
+}).strict();
+
+export async function listDocs(repo: ContentRepository, query: z.infer<typeof listQuery>) {
+  kindEnabled(query.kind);
+  if (query.collection && (query.kind !== 'post' || !CONTENT.collections[query.collection])) throw new ApiError(400, 'Unknown collection.');
+  let docs: AnyDoc[] = query.kind === 'post' ? await repo.listPosts(query.collection) : query.kind === 'page' ? await repo.listPages() : await repo.listEvents();
+  if (query.status === 'changed') docs = docs.filter((d) => d.draft);
+  else if (query.status) docs = docs.filter((d) => d.status === query.status);
+  const q = query.q?.trim().toLowerCase();
+  if (q) docs = docs.filter((d) => { const m = mergedDoc(query.kind, d); return `${m.title} ${m.slug}`.toLowerCase().includes(q); });
+  docs.sort((a, b) => b.updatedAt - a.updatedAt);
+  const start = (query.page - 1) * query.limit;
+  return {
+    items: docs.slice(start, start + query.limit).map((d) => summaryJson(query.kind, d)),
+    total: docs.length,
+    pagination: { page: query.page, limit: query.limit, nextPage: start + query.limit < docs.length ? query.page + 1 : null },
+  };
+}
+
+// ---- create --------------------------------------------------------------
+
+export const CreateInput = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('post'), title: z.string().trim().min(1).max(300), collection: z.string().max(100).default('posts') }).strict(),
+  z.object({ kind: z.literal('page'), title: z.string().trim().min(1).max(300) }).strict(),
+  z.object({ kind: z.literal('event'), title: z.string().trim().min(1).max(300), start: z.string().max(40), allDay: z.boolean().optional() }).strict(),
+]);
+
+export async function createDoc(repo: ContentRepository, input: z.infer<typeof CreateInput>, authorId: string) {
+  kindEnabled(input.kind);
+  const base = slugify(input.title) || 'untitled';
+  if (input.kind === 'post') {
+    if (!CONTENT.collections[input.collection]) throw new ApiError(400, `Unknown collection "${input.collection}".`);
+    let slug = base;
+    for (let n = 2; await repo.getPostBySlug(slug, input.collection); n++) slug = `${base}-${n}`;
+    const post = await repo.createPost({ title: input.title, slug, collection: input.collection });
+    // the person who started it is its author (editable afterwards)
+    await repo.updatePost(post.id, { authorIds: [authorId] });
+    return (await repo.getPost(post.id))!;
+  }
+  if (input.kind === 'page') {
+    let slug = base;
+    for (let n = 2; await repo.getPageBySlug(slug); n++) slug = `${base}-${n}`;
+    return repo.createPage({ title: input.title, slug });
+  }
+  let times: { start: string; end: string };
+  try { times = normalizeEventTimes({ start: input.start, end: '', allDay: input.allDay ?? !input.start.includes('T') }); }
+  catch (err) { throw new ApiError(400, err instanceof Error ? err.message : 'Invalid start time.'); }
+  let slug = base;
+  for (let n = 2; await repo.getEventBySlug(slug); n++) slug = `${base}-${n}`;
+  return repo.createEvent({ title: input.title, slug, start: times.start, end: times.end, allDay: input.allDay ?? !input.start.includes('T') });
+}
+
+// ---- save ----------------------------------------------------------------
+// Field rules mirror the admin save actions; status and schedule changes go
+// through the publish/unpublish/schedule actions instead.
+
+const text = (max: number) => z.string().max(max);
+const common = { title: text(1000), slug: text(300), bodyHtml: text(2_000_000), seoTitle: text(1000), seoDesc: text(5000), template: text(100) };
+export const PostFields = z.object({ ...common, excerpt: text(5000), tags: z.array(text(100)).max(100), cover: text(2000), coverAlt: text(1000),
+  featured: z.boolean(), collection: text(100), authorIds: z.array(text(100)).max(20) }).partial().strict();
+export const PageFields = z.object({ ...common, isHome: z.boolean(), locale: text(20) }).partial().strict();
+export const EventFields = z.object({ ...common, excerpt: text(1000), tags: z.array(text(100)).max(100), cover: text(2000), coverAlt: text(1000), featured: z.boolean(),
+  start: text(40), end: text(40), allDay: z.boolean(), timezone: text(100), rrule: text(500), exdates: z.array(text(40)).max(500), cancelled: z.boolean(),
+  location: z.object({ name: text(300), address: text(500), url: text(1000) }).strict(),
+  cta: z.object({ label: text(120), href: text(1000), style: z.enum(['primary', 'outline']) }).strict(),
+  calendarIds: z.array(text(100)).max(50), fields: z.record(text(2000)),
+  rsvp: z.object({ enabled: z.boolean(), capacity: z.number().int().min(0).max(100000), autoConfirm: z.boolean(), maxSeats: z.number().int().min(1).max(50) }).strict(),
+}).partial().strict();
+export const SaveInput = z.object({ revision: z.string().max(60), fields: z.record(z.unknown()) }).strict();
+
+export async function saveDoc(repo: ContentRepository, kind: DocKind, id: string, body: z.infer<typeof SaveInput>, hooks: SaveHooks) {
+  return withDocLock(repo, kind, id, () => saveDocLocked(repo, kind, id, body, hooks));
+}
+async function saveDocLocked(repo: ContentRepository, kind: DocKind, id: string, body: z.infer<typeof SaveInput>, hooks: SaveHooks) {
+  const before = await loadDoc(repo, kind, id);
+  checkRevision(before, body.revision);
+  if (kind === 'post') {
+    const fields = PostFields.parse(body.fields);
+    if (fields.authorIds) {
+      const known = new Set((await repo.listUsers()).map((u) => u.id));
+      fields.authorIds = [...new Set(fields.authorIds)].filter((a) => known.has(a));
+    }
+    // HTML written here replaces the editor's structured copy (it reloads from HTML)
+    return savePost(repo, id, { ...fields, ...(fields.bodyHtml !== undefined ? { bodyJson: '' } : {}) }, hooks);
+  }
+  if (kind === 'page') {
+    const fields = PageFields.parse(body.fields);
+    return savePage(repo, id, { ...fields, ...(fields.bodyHtml !== undefined ? { bodyJson: '' } : {}) }, undefined, hooks);
+  }
+  const fields = EventFields.parse(body.fields);
+  return saveEvent(repo, id, { ...fields, ...(fields.bodyHtml !== undefined ? { bodyJson: '' } : {}) }, hooks);
+}
+
+/** save through the right service with whatever fields (translations, status…) */
+export async function saveRaw(repo: ContentRepository, kind: DocKind, id: string, data: Record<string, unknown>, hooks: SaveHooks): Promise<AnyDoc> {
+  if (kind === 'post') return savePost(repo, id, data, hooks);
+  if (kind === 'page') return savePage(repo, id, data, undefined, hooks);
+  return saveEvent(repo, id, data, hooks);
+}
+
+// ---- publish / unpublish / schedule / discard ------------------------------
+
+export const ActionInput = z.object({ revision: z.string().max(60), at: z.string().datetime({ offset: true }).optional() }).strict();
+const live = (s: string) => s === 'published' || s === 'scheduled';
+const staged = (kind: DocKind, doc: AnyDoc) => !doc.draft ? {} : kind === 'post' ? pickPostDraft(doc.draft) : kind === 'page' ? pickPageDraft(doc.draft) : pickEventDraft(doc.draft);
+
+export async function docAction(repo: ContentRepository, kind: DocKind, id: string, action: string, body: z.infer<typeof ActionInput>, hooks: SaveHooks): Promise<AnyDoc> {
+  return withDocLock(repo, kind, id, () => docActionLocked(repo, kind, id, action, body, hooks));
+}
+async function docActionLocked(repo: ContentRepository, kind: DocKind, id: string, action: string, body: z.infer<typeof ActionInput>, hooks: SaveHooks): Promise<AnyDoc> {
+  const doc = await loadDoc(repo, kind, id);
+  checkRevision(doc, body.revision);
+  if (action === 'publish') {
+    // live + staged edits → Update; otherwise the status change (the editor's Publish)
+    let current = doc;
+    if (live(doc.status) && doc.draft) {
+      current = kind === 'post' ? await applyPostUpdate(repo, id, hooks) : kind === 'page' ? await applyPageUpdate(repo, id, hooks) : await applyEventUpdate(repo, id, hooks);
+    }
+    if (current.status === 'published') return current;
+    return saveRaw(repo, kind, id, { status: 'published', ...(kind === 'page' ? {} : { scheduledAt: null }) }, hooks);
+  }
+  if (action === 'unpublish') {
+    if (!live(doc.status)) throw new ApiError(409, 'This isn’t published.');
+    // staged edits become the draft's content, as the web editor sends them
+    return saveRaw(repo, kind, id, { ...staged(kind, doc), status: 'draft', ...(kind === 'page' ? {} : { scheduledAt: null }) }, hooks);
+  }
+  if (action === 'schedule') {
+    if (kind === 'page') throw new ApiError(400, 'Pages publish immediately; they can’t be scheduled.');
+    const at = body.at ? Date.parse(body.at) : NaN;
+    if (!Number.isFinite(at) || at <= Date.now()) throw new ApiError(400, 'Pick a future publish time to schedule.');
+    if (doc.status === 'published') throw new ApiError(409, 'This is already published. Unpublish it first.');
+    return saveRaw(repo, kind, id, { ...staged(kind, doc), status: 'scheduled', scheduledAt: at }, hooks);
+  }
+  if (action === 'discard') {
+    if (!doc.draft) return doc;
+    if (kind === 'post') await repo.discardPostDraft(id); else if (kind === 'page') await repo.discardPageDraft(id); else await repo.discardEventDraft(id);
+    return loadDoc(repo, kind, id);
+  }
+  throw new ApiError(404, 'Unknown action.');
+}

package/src/lib/editor/http.ts

@@ -0,0 +1,48 @@
+import type { APIContext, APIRoute } from 'astro';
+import { getRepo } from '../repo';
+import type { ContentRepository } from '../repo/types';
+import { ApiError } from '../api';
+import { sha256Hex } from '../api-keys';
+import { failure, response } from '../mobile/http';
+import { authenticateDevice, type EditorPrincipal } from './auth';
+import { requireEditorApps } from './config';
+
+export interface EditorContext { context: APIContext; repo: ContentRepository; who: EditorPrincipal; now: number }
+
+const address = (context: APIContext) => { try { return context.clientAddress || 'unknown'; } catch { return 'unknown'; } };
+
+/**
+ * One /api/v1/admin/* handler: editor apps must be on, a device access token
+ * (never a cookie) identifies the person, requests are rate limited per
+ * device, and results use the v1 envelope. Handlers may return a Response.
+ */
+export function editorRoute(handler: (c: EditorContext) => Promise<unknown>, opts: { write?: boolean; status?: number; limit?: number } = {}): APIRoute {
+  return async (context) => {
+    try {
+      requireEditorApps();
+      const repo = await getRepo(context.locals);
+      const now = Date.now();
+      let who: EditorPrincipal;
+      try { who = await authenticateDevice(context.request, repo, now); }
+      catch (error) {
+        // failed bearer attempts are throttled per client address
+        if (!await repo.email.rateLimit(`editor:fail:${await sha256Hex(address(context))}`, 30, 60_000)) throw new ApiError(429, 'Too many requests. Try again in a minute.');
+        throw error;
+      }
+      const max = opts.limit ?? (opts.write ? 60 : 600);
+      if (!await repo.email.rateLimit(`editor:${opts.write ? 'write' : 'read'}:${opts.limit ? `${opts.limit}:` : ''}${who.device.id}`, max, 60_000)) throw new ApiError(429, 'Too many requests. Try again in a minute.');
+      const data = await handler({ context, repo, who, now });
+      if (data instanceof Response) return data;
+      return response(data, opts.status ?? 200);
+    } catch (error) {
+      // expected failures carry a status (ApiError, BookingError) or zod issues; only surprises are logged (never request data)
+      if (typeof (error as { status?: unknown })?.status !== 'number' && !(error instanceof Error && 'issues' in error)) console.error('acms editor api: request failed:', error instanceof Error ? error.message : error);
+      return failure(error);
+    }
+  };
+}
+
+/** audit trail for a write: who, through which device */
+export async function logWrite(c: EditorContext, action: string, target: string) {
+  await c.repo.editor.log({ userId: c.who.user.id, deviceId: c.who.device.id, action, target }, Date.now()).catch(() => {});
+}