@acms-subir/core 0.3.9 → 0.3.11

package/src/lib/mobile/guest-store.ts

@@ -0,0 +1,62 @@
+import type { SqlDriver } from '../repo/sql';
+
+// Guest sign-in storage: one pending code per address and one session per
+// signed-in device. Only SHA-256 hashes of codes and tokens are stored.
+
+/** guest app sessions end after this long unused */
+export const GUEST_IDLE_MS = 90 * 86_400_000;
+
+export interface GuestSession { id: string; email: string; deviceName: string; createdAt: number; lastSeenAt: number }
+const session = (r: Record<string, unknown>): GuestSession => ({ id: String(r.id), email: String(r.email), deviceName: String(r.device_name ?? ''), createdAt: Number(r.created_at), lastSeenAt: Number(r.last_seen_at) });
+
+export class GuestStore {
+  constructor(private driver: () => Promise<SqlDriver>) {}
+  /** replaces any earlier code for the address (a new request voids the old code) */
+  async saveCode(email: string, codeHash: string, expiresAt: number, now = Date.now()) {
+    await (await this.driver()).run(`INSERT INTO guest_codes (email, code_hash, attempts, expires_at, created_at) VALUES (?, ?, 0, ?, ?)
+      ON CONFLICT(email) DO UPDATE SET code_hash = excluded.code_hash, attempts = 0, expires_at = excluded.expires_at, created_at = excluded.created_at`, [email, codeHash, expiresAt, now]);
+  }
+  async code(email: string) {
+    const r = (await (await this.driver()).all('SELECT code_hash, attempts, expires_at, created_at FROM guest_codes WHERE email = ?', [email]))[0];
+    return r ? { codeHash: String(r.code_hash), attempts: Number(r.attempts), expiresAt: Number(r.expires_at), createdAt: Number(r.created_at) } : null;
+  }
+  /**
+   * counts one verification attempt in a single statement, so concurrent
+   * guesses can't exceed `maxTries`; returns the code hash it was counted
+   * against, or null when there is no live code with tries left
+   */
+  async attempt(email: string, maxTries: number, now = Date.now()) {
+    const r = (await (await this.driver()).all('UPDATE guest_codes SET attempts = attempts + 1 WHERE email = ? AND attempts < ? AND expires_at > ? RETURNING code_hash, attempts', [email, maxTries, now]))[0];
+    return r ? { codeHash: String(r.code_hash), attempts: Number(r.attempts) } : null;
+  }
+  /** deletes this exact code; true for exactly one caller, so a code signs in once */
+  async consumeCode(email: string, codeHash: string) {
+    return (await (await this.driver()).all('DELETE FROM guest_codes WHERE email = ? AND code_hash = ? RETURNING email', [email, codeHash])).length > 0;
+  }
+  async deleteCode(email: string) { await (await this.driver()).run('DELETE FROM guest_codes WHERE email = ?', [email]); }
+
+  /** keeps the newest `keep` sessions per address so old devices age out */
+  async createSession(s: { id: string; tokenHash: string; email: string; deviceName: string }, now = Date.now(), keep = 20) {
+    const d = await this.driver();
+    await d.batch([
+      { sql: 'INSERT INTO guest_sessions (id, token_hash, email, device_name, created_at, last_seen_at) VALUES (?, ?, ?, ?, ?, ?)', args: [s.id, s.tokenHash, s.email, s.deviceName, now, now] },
+      { sql: 'DELETE FROM guest_sessions WHERE email = ? AND id NOT IN (SELECT id FROM guest_sessions WHERE email = ? ORDER BY last_seen_at DESC LIMIT ?)', args: [s.email, s.email, keep] },
+    ]);
+  }
+  async sessionByHash(tokenHash: string) {
+    const r = (await (await this.driver()).all('SELECT * FROM guest_sessions WHERE token_hash = ?', [tokenHash]))[0];
+    return r ? session(r) : null;
+  }
+  async touch(id: string, now = Date.now()) { await (await this.driver()).run('UPDATE guest_sessions SET last_seen_at = ? WHERE id = ?', [now, id]); }
+  async deleteSession(id: string) { await (await this.driver()).run('DELETE FROM guest_sessions WHERE id = ?', [id]); }
+  /** every device signs out (owner switch "Sign out all") */
+  async deleteAll() { await (await this.driver()).run('DELETE FROM guest_sessions'); }
+  async count(since = 0) { return Number((await (await this.driver()).all('SELECT COUNT(*) AS n FROM guest_sessions WHERE last_seen_at >= ?', [since]))[0]?.n ?? 0); }
+  /** drops expired codes and sessions unused for `idleMs` */
+  async purge(idleMs: number, now = Date.now()) {
+    await (await this.driver()).batch([
+      { sql: 'DELETE FROM guest_codes WHERE expires_at <= ?', args: [now] },
+      { sql: 'DELETE FROM guest_sessions WHERE last_seen_at <= ?', args: [now - idleMs] },
+    ]);
+  }
+}

package/src/lib/mobile/guest.ts

@@ -0,0 +1,160 @@
+import { z } from 'zod';
+import type { ContentRepository } from '../repo/types';
+import type { Booking } from '../schema';
+import { ApiError, readJson } from '../api';
+import { sha256Hex } from '../api-keys';
+import { randomToken, safeEqual } from '../editor/auth';
+import { CALENDAR, bookingsEnabled, manageUrl } from '../calendar/config';
+import { encrypt, encryptionAvailable, resolveConfig, validAddress } from '../email/config';
+import { kickEmail } from '../email/service';
+import { guestChanges } from '../booking/service';
+import { siteOrigin } from '../seo';
+import { waitUntilFrom } from '../webhooks';
+import { pageQuery, queryParams } from './http';
+import { failureLock } from './access';
+import type { PublicContext } from './route';
+import { GUEST_IDLE_MS } from './guest-store';
+export { GUEST_IDLE_MS };
+
+// Guest sign-in for "My bookings": the visitor proves they read an inbox.
+// POST /guest/code emails a 6-digit code (10 minutes, 5 tries, only its hash
+// is stored); POST /guest/token trades email + code for a per-device token
+// (opaque, hashed at rest, ends after 90 days unused). The token reads that
+// address's bookings and nothing else — it never reaches staff routes.
+// Replies never say whether an address has bookings.
+
+export const GUEST_PREFIX = 'acms_guest_';
+const CODE_MS = 10 * 60_000;
+const MAX_TRIES = 5;
+// wrong codes per address per day before sign-in for it pauses (guessing 6 digits stays hopeless)
+const EMAIL_FAILURES_PER_DAY = 10;
+const SITE_CODES_PER_HOUR = 200;
+const TOKEN = /^acms_guest_[0-9a-f]{64}$/;
+
+/** guest sign-in needs the owner switch, working email and an encryption key */
+export async function guestSignInReady(repo: ContentRepository, locals?: unknown) {
+  const settings = await repo.getSettings();
+  if (!settings.mobileAccess.guestSignIn || !CALENDAR.enabled) return false;
+  const c = resolveConfig(await repo.email.config(), locals);
+  return !c.error && c.provider !== 'none' && c.config.enabled && encryptionAvailable(locals);
+}
+async function requireGuest(c: PublicContext) {
+  if (!await guestSignInReady(c.repo, c.locals)) throw new ApiError(404, 'This feature is turned off.');
+}
+const emailField = z.string().trim().toLowerCase().max(254).refine(validAddress, 'Enter a valid email address.');
+const hash = (email: string, code: string) => sha256Hex(`guest-code:${email}:${code}`);
+function sixDigits() {
+  // rejection sampling keeps every code equally likely
+  const buf = new Uint32Array(1);
+  do crypto.getRandomValues(buf); while (buf[0] >= 4_294_000_000);
+  return String(buf[0] % 1_000_000).padStart(6, '0');
+}
+
+export const codeInput = z.object({ email: emailField }).strict();
+export async function requestCode(c: PublicContext) {
+  await requireGuest(c);
+  const { email } = codeInput.parse(await readJson(c.request, 1000));
+  if (!await c.repo.email.rateLimit(`guest:code:ip:${await sha256Hex(c.address)}`, 20, 15 * 60_000)) throw new ApiError(429, 'Too many requests. Try again in a few minutes.', 900);
+  // site-wide ceiling: rotating client addresses can't turn this into a mail cannon
+  if (!await c.repo.email.rateLimit('guest:code:site', SITE_CODES_PER_HOUR, 3_600_000)) throw new ApiError(429, 'Sign-in is busy right now. Try again in a little while.', 3600);
+  const emailKey = await sha256Hex(email);
+  // an address that already got 3 codes, or that ran out of guesses today, quietly gets no more
+  if (!await c.repo.email.rateLimited(`guest:fail:email:${emailKey}`, EMAIL_FAILURES_PER_DAY)
+    && await c.repo.email.rateLimit(`guest:code:email:${emailKey}`, 3, 15 * 60_000)) {
+    const now = Date.now(), code = sixDigits(), dedupe = `guest-code:${crypto.randomUUID()}`;
+    await c.repo.guests.saveCode(email, await hash(email, code), now + CODE_MS, now);
+    const config = await c.repo.email.config();
+    await c.repo.email.enqueue({ dedupe, kind: 'guest-code', recipient: email, configVersion: config?.version ?? 0, expiresAt: now + CODE_MS,
+      payload: JSON.stringify({ issuedAt: now, code: encrypt(code, `guest-code:${dedupe}`, c.locals) }) });
+    await kickEmail(c.repo, c.locals, waitUntilFrom(c.locals));
+  }
+  return { sent: true as const, expiresInMinutes: CODE_MS / 60_000 };
+}
+
+export const tokenInput = z.object({
+  email: emailField, code: z.string().regex(/^\d{6}$/, 'Enter the 6-digit code.'),
+  // shown to the owner ("Ana's iPhone"); optional
+  deviceName: z.string().trim().max(80).default(''),
+}).strict();
+export async function exchangeCode(c: PublicContext) {
+  await requireGuest(c);
+  const body = tokenInput.parse(await readJson(c.request, 1000));
+  const lock = await failureLock(c.repo, 'guest-code', c.address, 30);
+  await lock.check();
+  // per address, across every code: new codes reset the 5 tries, not this budget
+  const failKey = `guest:fail:email:${await sha256Hex(body.email)}`;
+  if (await c.repo.email.rateLimited(failKey, EMAIL_FAILURES_PER_DAY)) {
+    await c.repo.guests.deleteCode(body.email);
+    throw new ApiError(400, 'That code is wrong or has expired. Check the latest email or ask for a new code.');
+  }
+  // the try is counted and the code consumed atomically: concurrent requests
+  // can't share one code or squeeze in extra guesses (spent codes stay until
+  // purged; attempt() already refuses them)
+  const tried = await c.repo.guests.attempt(body.email, MAX_TRIES);
+  const ok = !!tried && safeEqual(tried.codeHash, await hash(body.email, body.code)) && await c.repo.guests.consumeCode(body.email, tried.codeHash);
+  if (!ok) {
+    await lock.miss();
+    await c.repo.email.rateLimit(failKey, EMAIL_FAILURES_PER_DAY, 86_400_000);
+    throw new ApiError(400, 'That code is wrong or has expired. Check the latest email or ask for a new code.');
+  }
+  const token = randomToken(GUEST_PREFIX);
+  await c.repo.guests.createSession({ id: crypto.randomUUID(), tokenHash: await sha256Hex(token), email: body.email, deviceName: body.deviceName });
+  return { accessToken: token, tokenType: 'Bearer' as const, email: body.email, idleDays: GUEST_IDLE_MS / 86_400_000 };
+}
+
+/** the signed-in guest behind `Authorization: Bearer acms_guest_…` */
+export async function authenticateGuest(c: PublicContext) {
+  await requireGuest(c);
+  const raw = /^Bearer (\S+)$/.exec(c.request.headers.get('authorization') ?? '')?.[1] ?? '';
+  const lock = await failureLock(c.repo, 'guest-token', c.address);
+  await lock.check();
+  const session = TOKEN.test(raw) ? await c.repo.guests.sessionByHash(await sha256Hex(raw)) : null;
+  const now = Date.now();
+  if (!session || session.lastSeenAt <= now - GUEST_IDLE_MS) {
+    await lock.miss();
+    if (session) await c.repo.guests.deleteSession(session.id);
+    throw new ApiError(401, 'Sign in again.');
+  }
+  // sliding expiry without a write on every request
+  if (now - session.lastSeenAt > 3_600_000) await c.repo.guests.touch(session.id, now);
+  return session;
+}
+
+export const myBookingsQuery = z.object({ when: z.enum(['upcoming', 'past']).default('upcoming'), ...pageQuery }).strict();
+export async function myBookings(c: PublicContext) {
+  const q = myBookingsQuery.parse(queryParams(c.url));
+  const session = await authenticateGuest(c);
+  const settings = await c.repo.getSettings();
+  const origin = siteOrigin(settings, c.url);
+  const now = Date.now();
+  const kinds: Booking['kind'][] = bookingsEnabled() ? ['booking', 'rsvp'] : ['rsvp'];
+  const start = (q.page - 1) * q.limit;
+  // filtered, ordered and paged in SQL (one extra row says whether there is a next page)
+  const [list, resources, links, events] = await Promise.all([
+    c.repo.listBookings({ email: session.email, kinds, ...(q.when === 'upcoming' ? { from: now } : { endedBy: now, newestFirst: true }), limit: q.limit + 1, offset: start }),
+    c.repo.listResources(), c.repo.listBookingLinks(), c.repo.listEvents(),
+  ]);
+  const res = new Map(resources.map((r) => [r.id, r])), lnk = new Map(links.map((l) => [l.id, l])), ev = new Map(events.map((e) => [e.id, e]));
+  return {
+    email: session.email,
+    items: list.slice(0, q.limit).map((b) => {
+      const resource = res.get(b.resourceId), link = lnk.get(b.linkId) ?? null, event = ev.get(b.eventId);
+      return {
+        id: b.id, reference: b.id.slice(0, 8).toUpperCase(), kind: b.kind as 'booking' | 'rsvp', status: b.status,
+        start: new Date(b.start).toISOString(), end: new Date(b.end).toISOString(), seats: b.seats,
+        title: event ? event.title : [resource?.name, link?.name].filter(Boolean).join(' · ') || 'Booking',
+        // use with the Booking-Token header on /bookings/manage/*
+        manageToken: b.manageToken, manageUrl: origin + manageUrl(b.manageToken),
+        can: guestChanges(b, link, now),
+      };
+    }),
+    pagination: { page: q.page, limit: q.limit, nextPage: list.length > q.limit ? q.page + 1 : null },
+  };
+}
+
+export async function revokeGuest(c: PublicContext) {
+  const session = await authenticateGuest(c);
+  await c.repo.guests.deleteSession(session.id);
+  return { signedOut: true as const };
+}
+

package/src/lib/mobile/http.ts

@@ -4,11 +4,11 @@ import { BookingError } from '../booking/service';
 import { sha256Hex } from '../api-keys';
 import type { ContentRepository } from '../repo/types';
 
-const headers = {
+export const headers = {
   'Access-Control-Allow-Origin': '*',
   'Access-Control-Allow-Methods': 'GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS',
   // Authorization carries editor-app bearer tokens; no route reads cookies
-  'Access-Control-Allow-Headers': 'Authorization, Content-Type, Idempotency-Key, If-None-Match',
+  'Access-Control-Allow-Headers': 'Authorization, Booking-Token, Content-Type, Idempotency-Key, If-None-Match',
   'Access-Control-Expose-Headers': 'ETag, Retry-After, Idempotency-Replayed',
   'X-Content-Type-Options': 'nosniff',
   'Cache-Control': 'no-store',
@@ -25,9 +25,10 @@ export async function publicResponse(request: Request, data: unknown, raw = fals
   res.headers.set('ETag', etag);
   // Revalidate even fresh-looking content: unpublishing must take effect.
   res.headers.set('Cache-Control', 'public, max-age=0, must-revalidate');
-  const match = request.headers.get('if-none-match')?.split(',').some((s) => s.trim().replace(/^W\//, '') === etag || s.trim() === '*');
-  return match ? new Response(null, { status: 304, headers: res.headers }) : res;
+  return etagMatches(request, etag) ? new Response(null, { status: 304, headers: res.headers }) : res;
 }
+export const etagMatches = (request: Request, etag: string) =>
+  request.headers.get('if-none-match')?.split(',').some((s) => s.trim().replace(/^W\//, '') === etag || s.trim() === '*') ?? false;
 export function failure(error: unknown) {
   const status = error instanceof ApiError || error instanceof BookingError ? error.status : error instanceof z.ZodError ? 400 : 500;
   const codes: Record<number, string> = { 400: 'invalid_request', 401: 'unauthorized', 403: 'forbidden', 404: 'not_found', 405: 'method_not_allowed', 409: 'conflict', 410: 'gone', 413: 'payload_too_large', 415: 'unsupported_media_type', 429: 'rate_limited', 502: 'upstream_error' };
@@ -35,7 +36,7 @@ export function failure(error: unknown) {
     code: codes[status] ?? 'internal_error',
     message: status === 500 ? 'Request failed. Please try again.' : error instanceof z.ZodError ? 'Invalid request parameters.' : (error as Error).message,
     ...(error instanceof z.ZodError ? { issues: error.issues.map(({ path, message }) => ({ path, message })) } : {}),
-  } }, { status, headers: { ...headers, ...(status === 429 ? { 'Retry-After': '60' } : {}),
+  } }, { status, headers: { ...headers, ...(status === 429 ? { 'Retry-After': String((error as ApiError).retryAfter ?? 60) } : {}),
     ...(status === 401 ? { 'WWW-Authenticate': 'Bearer realm="acms", error="invalid_token"' } : {}) } });
 }
 export async function limitRequest(repo: ContentRepository, address: string, write = false) {

package/src/lib/mobile/links.ts

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+import type { ContentRepository } from '../repo/types';
+import type { Link } from '../schema';
+import { siteOrigin } from '../seo';
+import { socialIconPath } from '../socialIcons';
+import { safeUrl } from './content';
+import { queryParams } from './http';
+import { requireAccess } from './access';
+
+// The links page (link-in-bio) for apps: the same visible blocks in the same
+// order. Buttons point at /go/<id> so taps still count; raw HTML embeds stay
+// website-only and arrive as `embed` with the page URL to open instead.
+
+const HEX = /^#[0-9a-f]{6}$/i;
+const str = (v: unknown) => (typeof v === 'string' ? v : '');
+
+function icon(l: Link, origin: string) {
+  const value = l.icon.trim();
+  if (!value) return null;
+  if (value.startsWith('<svg')) return { type: 'svg' as const, value };
+  if (value === 'favicon') {
+    try { return { type: 'image' as const, value: `https://www.google.com/s2/favicons?domain=${new URL(l.url).hostname}&sz=64` }; } catch { return null; }
+  }
+  if (value.startsWith('http') || value.startsWith('/')) { const url = safeUrl(value, origin); return url ? { type: 'image' as const, value: url } : null; }
+  return { type: 'emoji' as const, value: value.slice(0, 16) };
+}
+
+function shown(l: Link) {
+  if (l.meta?.hidden) return false;
+  if (l.kind === 'link' || l.kind === 'email' || l.kind === 'phone') return Boolean(l.url.trim());
+  if (l.kind === 'heading') return Boolean(l.label.trim());
+  if (l.kind === 'text' || l.kind === 'html') return Boolean(l.html.trim());
+  return true;
+}
+
+function item(l: Link, origin: string, page: string) {
+  const style = { color: HEX.test(str(l.meta.color)) ? str(l.meta.color) : null, textColor: HEX.test(str(l.meta.textColor)) ? str(l.meta.textColor) : null };
+  switch (l.kind) {
+    case 'heading': return { id: l.id, kind: 'heading' as const, label: l.label };
+    case 'text': return { id: l.id, kind: 'text' as const, text: l.html };
+    case 'spacer': return { id: l.id, kind: 'spacer' as const, size: (['s', 'm', 'l'].includes(str(l.meta.size)) ? str(l.meta.size) : 'm') as 's' | 'm' | 'l' };
+    case 'live': return { id: l.id, kind: 'live' as const };
+    case 'html': return { id: l.id, kind: 'embed' as const, url: page };
+    case 'email': return { id: l.id, kind: 'email' as const, label: l.label || l.url, url: `mailto:${l.url.trim()}`, icon: icon(l, origin), ...style };
+    case 'phone': return { id: l.id, kind: 'phone' as const, label: l.label || l.url, url: `tel:${l.url.replace(/[^+\d]/g, '')}`, icon: icon(l, origin), ...style };
+    case 'vcard': {
+      const m = l.meta;
+      return { id: l.id, kind: 'contact' as const, label: l.label || 'Save contact', icon: icon(l, origin), ...style,
+        contact: { firstName: str(m.firstName), lastName: str(m.lastName), organization: str(m.org), phone: str(m.phone), email: str(m.email), url: safeUrl(str(m.url), origin) } };
+    }
+    default: return { id: l.id, kind: 'link' as const, label: l.label, url: `${origin}/go/${encodeURIComponent(l.id)}`, destination: safeUrl(l.url, origin), icon: icon(l, origin), ...style };
+  }
+}
+
+export async function getLinks(repo: ContentRepository, url: URL) {
+  z.object({}).strict().parse(queryParams(url));
+  const settings = await requireAccess(repo, 'links');
+  const origin = siteOrigin(settings, url);
+  const [links, nav] = await Promise.all([repo.listLinks(), repo.listNavItems()]);
+  const page = `${origin}/links`;
+  return {
+    name: settings.linksName || settings.siteTitle,
+    bio: settings.linksBio || settings.tagline,
+    avatar: safeUrl(settings.linksAvatar, origin),
+    url: page,
+    socials: nav.filter((n) => n.area === 'social').map((n) => ({ label: n.label, url: safeUrl(n.url, origin, true), iconPath: socialIconPath(n.url) })).filter((n) => n.url),
+    items: links.filter(shown).map((l) => item(l, origin, page)).filter((i) => !('url' in i) || i.url),
+  };
+}

package/src/lib/mobile/manage.ts

@@ -0,0 +1,114 @@
+import { z } from 'zod';
+import type { Booking, BookingLink, CalEvent, Resource, Settings } from '../schema';
+import { ApiError, readJson } from '../api';
+import { bookingsEnabled, eventUrl, manageUrl } from '../calendar/config';
+import { eventTimeZone, locationLine } from '../calendar/events';
+import { resourceZone, linkLengths } from '../booking/availability';
+import { bookingIcs } from '../booking/emails';
+import { guestCancel, guestChanges, guestMoveLink, guestReschedule } from '../booking/service';
+import { siteOrigin } from '../seo';
+import { waitUntilFrom } from '../webhooks';
+import { isoDay, queryParams } from './http';
+import { requireCalendar, availabilityFor } from './calendar';
+import { requireAccess, failureLock } from './access';
+import type { PublicContext } from './route';
+
+// A booker's own booking, from an app: the private token every confirmation
+// email links to is the credential. It travels in the Booking-Token header,
+// never the URL, so it stays out of access logs and analytics. Unknown tokens
+// count against the caller's address (20 misses / 10 min → locked out).
+
+export const BOOKING_TOKEN_HEADER = 'Booking-Token';
+const TOKEN = /^[A-Za-z0-9_-]{16,128}$/;
+
+interface Managed { booking: Booking; settings: Settings; resource: Resource | null; link: BookingLink | null; event: CalEvent | null; origin: string }
+
+async function managed(c: PublicContext): Promise<Managed> {
+  requireCalendar();
+  const settings = await requireAccess(c.repo, 'bookingChanges');
+  const token = c.request.headers.get(BOOKING_TOKEN_HEADER) ?? '';
+  if (!token) throw new ApiError(400, `Send the booking’s token in the ${BOOKING_TOKEN_HEADER} header.`);
+  const lock = await failureLock(c.repo, 'booking-token', c.address);
+  await lock.check();
+  const booking = TOKEN.test(token) ? await c.repo.getBookingByToken(token) : null;
+  if (!booking || booking.kind === 'block' || (!bookingsEnabled() && booking.kind !== 'rsvp')) {
+    await lock.miss();
+    throw new ApiError(404, 'Booking not found.');
+  }
+  const [resource, link, event] = await Promise.all([
+    booking.resourceId ? c.repo.getResource(booking.resourceId) : null,
+    booking.linkId ? c.repo.getBookingLink(booking.linkId) : null,
+    booking.eventId ? c.repo.getEvent(booking.eventId) : null,
+  ]);
+  return { booking, settings, resource, link, event, origin: siteOrigin(settings, c.url) };
+}
+
+function view(m: Managed, booking = m.booking) {
+  const { resource, link, event, settings, origin } = m;
+  const can = guestChanges(booking, link);
+  return {
+    booking: {
+      id: booking.id, reference: booking.id.slice(0, 8).toUpperCase(), kind: booking.kind as 'booking' | 'rsvp', status: booking.status,
+      start: new Date(booking.start).toISOString(), end: new Date(booking.end).toISOString(),
+      allDay: event ? event.allDay : link?.mode === 'day',
+      timezone: event ? eventTimeZone(event, settings) : resource ? resourceZone(resource, settings.timezone) : settings.timezone || 'UTC',
+      seats: booking.seats, name: booking.name, email: booking.email, phone: booking.phone, answers: booking.answers,
+      createdAt: new Date(booking.createdAt).toISOString(),
+    },
+    title: event ? event.title : [resource?.name, link?.name].filter(Boolean).join(' · ') || 'Booking',
+    location: event ? locationLine(event.location) : resource?.name ?? '',
+    resource: resource ? { slug: resource.slug, name: resource.name } : null,
+    link: link ? { slug: link.slug, name: link.name, mode: link.mode, lengths: linkLengths(link) } : null,
+    event: event ? { slug: event.slug, title: event.title, url: origin + eventUrl(event.slug) } : null,
+    // the web page for this booking (the same private link the emails carry)
+    manageUrl: origin + manageUrl(booking.manageToken),
+    can,
+  };
+}
+const flow = (m: Managed, c: PublicContext) => ({ origin: m.origin, locals: c.locals, waitUntil: waitUntilFrom(c.locals) });
+
+export const getManaged = async (c: PublicContext) => view(await managed(c));
+
+export async function cancelManaged(c: PublicContext) {
+  const m = await managed(c);
+  return view(m, await guestCancel(c.repo, m.booking, flow(m, c)));
+}
+
+export const manageAvailabilityQuery = z.object({
+  from: isoDay.optional(), days: z.coerce.number().int().min(1).max(31).default(7), minutes: z.coerce.number().int().min(1).max(44640).optional(),
+}).strict();
+export async function managedAvailability(c: PublicContext) {
+  const q = manageAvailabilityQuery.parse(queryParams(c.url));
+  const m = await managed(c);
+  if (!guestChanges(m.booking, m.link).reschedule || !m.resource || !m.link) throw new ApiError(409, 'This booking can’t be moved.');
+  // only times the move itself would accept (outside the change cutoff)
+  return availabilityFor(c.repo, m.resource, guestMoveLink(m.link), m.settings, q, m.booking.id);
+}
+
+export const rescheduleInput = z.object({
+  start: z.string().datetime({ offset: true }),
+  // range/day links: the new length; default keeps the current length
+  minutes: z.number().int().min(1).max(44640).optional(),
+}).strict();
+export async function rescheduleManaged(c: PublicContext) {
+  const body = rescheduleInput.parse(await readJson(c.request, 2000));
+  const m = await managed(c);
+  const start = Date.parse(body.start);
+  const minutes = body.minutes ?? Math.round((m.booking.end - m.booking.start) / 60_000);
+  // availability rules check everything else (hours, notice, overlaps)
+  if (m.link?.mode === 'range' && body.minutes !== undefined && !linkLengths(m.link).includes(minutes)) throw new ApiError(400, 'Pick one of the booking type’s lengths.');
+  return view(m, await guestReschedule(c.repo, m.booking, start, start + minutes * 60_000, flow(m, c)));
+}
+
+export async function managedIcs(c: PublicContext) {
+  z.object({}).strict().parse(queryParams(c.url));
+  const m = await managed(c);
+  const v = view(m);
+  const body = bookingIcs(m.booking, v.title, v.location, v.manageUrl, new URL(m.origin).host, m.booking.status === 'cancelled' ? 'CANCEL' : 'REQUEST', { allDay: v.booking.allDay });
+  return new Response(body, { headers: {
+    'Content-Type': 'text/calendar; charset=utf-8', 'Content-Disposition': 'attachment; filename="booking.ics"',
+    'Cache-Control': 'no-store', 'Access-Control-Allow-Origin': '*', 'X-Content-Type-Options': 'nosniff',
+  } });
+}
+
+export type ManagedBooking = ReturnType<typeof view>;

package/src/lib/mobile/openapi.ts

@@ -5,6 +5,10 @@ import { contentQuery, contentDetailQuery } from './content';
 import { eventsQuery, availabilityQuery } from './calendar';
 import { bookingInput } from './bookings';
 import { pagesQuery } from './pages';
+import { searchQuery } from './search';
+import { manageAvailabilityQuery, rescheduleInput } from './manage';
+import { formResponseInput } from './forms';
+import { codeInput, tokenInput, myBookingsQuery } from './guest';
 import { deviceInput, deviceUpdate } from '../push/api';
 import { pageQuery, queryParams } from './http';
 import * as schemas from './schemas';
@@ -24,7 +28,7 @@ const readHeaders = {
 };
 const errors = Object.fromEntries([400, 404, 405, 429, 500].map(status => [status, {
   description: status === 429 ? 'Read limit exceeded (300/minute/client address).' : 'Request failed.', content: media(ref('Error')),
-  ...(status === 429 ? { headers: { 'Retry-After': { schema: { type: 'string', const: '60' } } } } : {}),
+  ...(status === 429 ? { headers: { 'Retry-After': { description: 'Seconds to wait: 60 for per-minute limits, longer for hourly, daily and lockout limits.', schema: { type: 'string' } } } } : {}),
 }]));
 function parameters(query: z.AnyZodObject) {
   return Object.entries(query.shape).map(([name, schema]) => ({ name, in: 'query', required: !(schema as z.ZodTypeAny).isOptional(), schema: jsonSchema(schema as z.ZodTypeAny) }));
@@ -37,13 +41,16 @@ export async function getOpenApi(_repo: ContentRepository, url: URL) {
     ['/theme', 'Active Design tokens including overrides', empty, ref('Theme')],
     ['/pages/home', 'Published home page and resolved sections', pagesQuery, ref('Page')],
     ['/pages/{slug}', 'Published page and resolved sections (slug may contain slashes)', pagesQuery, ref('Page')],
-    ['/content', 'Published content in the requested language', contentQuery, jsonSchema(z.object({ locale: z.string().nullable(), items: z.array(schemas.ContentSummary), pagination: schemas.Pagination }))],
+    ['/content', 'Published content in the requested language; q (requires search) returns ranked matches, posts before pages, up to 200 per kind', contentQuery, jsonSchema(z.object({ locale: z.string().nullable(), items: z.array(schemas.ContentSummary), pagination: schemas.Pagination }))],
     ['/content/{id}', 'Published content detail', contentDetailQuery, ref('Content')],
+    ['/search', 'Ranked matches across posts, pages and events (top limit per group); requires search', searchQuery, ref('SearchResults')],
     ['/events', 'Public event occurrences; requires calendar', eventsQuery, ref('Events')],
     ['/calendars', 'Public calendars; requires calendar', empty, ref('Calendars')],
     ['/resources', 'Public resources and booking links; requires bookings', z.object(pageQuery).strict(), ref('Resources')],
     ['/availability', 'Current availability; requires bookings', availabilityQuery, ref('Availability'), false],
     ['/push/topics', 'Topics an app can offer as notification toggles; requires push', empty, ref('PushTopics')],
+    ['/links', 'The links page: profile, socials and visible blocks in order (owner switch: links)', empty, ref('Links')],
+    ['/forms/{id}', 'A published form’s questions; 410 when it stopped accepting responses (owner switch: forms)', empty, ref('Form')],
     ['/openapi.json', 'OpenAPI 3.1 document (no v1 envelope)', empty, { type: 'object', required: ['openapi', 'info', 'paths', 'components'] }],
   ];
   for (const [path, summary, query, schema, cache = true] of reads) {
@@ -72,6 +79,35 @@ export async function getOpenApi(_repo: ContentRepository, url: URL) {
     },
     options: { summary: 'Public CORS preflight', responses: { 204: { description: 'No body.' } } },
   };
+  // private reads and writes: no-store, credential in a header, never the URL
+  const bookingToken = { name: 'Booking-Token', in: 'header', required: true, description: 'The booking’s private token (manageToken from POST /bookings or GET /guest/bookings). Unknown tokens count against the caller: 20 misses in 10 minutes locks the address out for a while.', schema: { type: 'string' } };
+  const priv = (summary: string, response: unknown, o: { query?: z.AnyZodObject; body?: z.ZodTypeAny; header?: unknown; guest?: boolean; status?: number; description?: string; write?: boolean } = {}) => ({
+    summary, ...(o.description ? { description: o.description } : {}),
+    ...(o.guest ? { security: [{ guestToken: [] }] } : {}),
+    parameters: [...(o.query ? parameters(o.query) : []), ...(o.header ? [o.header] : [])],
+    ...(o.body ? { requestBody: { required: true, content: media(jsonSchema(o.body)) } } : {}),
+    responses: { ...errors, ...(o.write ? Object.fromEntries([409, 410, 413, 415].map(code => [code, { description: 'Request rejected.', content: media(ref('Error')) }])) : {}),
+      ...(o.guest ? { 401: { description: 'Missing, expired or signed-out guest token: sign in again.', content: media(ref('Error')) } } : {}),
+      [o.status ?? 200]: { description: 'Success.', headers: { 'Cache-Control': { schema: { type: 'string', const: 'no-store' } } }, content: media(envelope(response)) } },
+  });
+  const cors = { options: { summary: 'Public CORS preflight', responses: { 204: { description: 'No body.' } } } };
+  const manageNote = 'Requires the calendar and the owner switch bookingChanges. Same rules and emails as the booking’s web page; a booking type’s change cutoff closes guest changes that many hours before the start.';
+  paths['/api/v1/bookings/manage'] = { get: priv('The booker’s own booking: status, time, place, what they may still change', ref('ManagedBooking'), { header: bookingToken, description: manageNote }), ...cors };
+  paths['/api/v1/bookings/manage/cancel'] = { post: priv('Cancel the booking (repeating is harmless)', ref('ManagedBooking'), { header: bookingToken, write: true, description: manageNote }), ...cors };
+  paths['/api/v1/bookings/manage/availability'] = { get: priv('Open times for moving the booking (its own time counts as free)', ref('Availability'), { header: bookingToken, query: manageAvailabilityQuery, description: manageNote }), ...cors };
+  paths['/api/v1/bookings/manage/reschedule'] = { post: priv('Move the booking to a new start (room bookings, not RSVPs)', ref('ManagedBooking'), { header: bookingToken, body: rescheduleInput, write: true, description: manageNote }), ...cors };
+  paths['/api/v1/bookings/manage/ics'] = { get: { summary: 'Calendar file for the booking (text/calendar, no v1 envelope)', parameters: [bookingToken],
+    responses: { ...errors, 200: { description: 'An iCalendar file.', content: { 'text/calendar': { schema: { type: 'string' } } } } } }, ...cors };
+  paths['/api/v1/forms/{id}/responses'] = { post: { ...priv('Send a response to a published form', ref('FormReceipt'), { body: formResponseInput, write: true, status: 201,
+    description: 'Same validation as the web form. Idempotency-Key (UUID v4) is the response id: retries never duplicate. 10 responses per address per form per minute, plus the owner’s daily ceiling per form (429). version from GET /forms/{id}: a changed form answers 409. Leave website empty (spam trap).' }),
+    parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string' } }, { name: 'Idempotency-Key', in: 'header', required: true, schema: { type: 'string', format: 'uuid' } }] }, ...cors };
+  const guestNote = 'Guest sign-in needs the calendar, working email, EMAIL_ENCRYPTION_KEY and the owner switch guestSignIn (site.features.guestSignIn); 404 otherwise.';
+  paths['/api/v1/guest/code'] = { post: priv('Email a 6-digit sign-in code (always answers the same, whether or not the address has bookings)', ref('GuestCodeSent'), { body: codeInput, write: true, status: 202,
+    description: `${guestNote} Codes last 10 minutes; a new request voids the old code. 3 codes per address and 20 per client address per 15 minutes.` }), ...cors };
+  paths['/api/v1/guest/token'] = { post: priv('Trade email + code for a guest token for this device', ref('GuestToken'), { body: tokenInput, write: true,
+    description: `${guestNote} 5 tries per code; 30 failures per client address in 10 minutes locks it out. Keep the token in secure storage; it ends after 90 days unused.` }), ...cors };
+  paths['/api/v1/guest/bookings'] = { get: priv('Bookings and RSVPs made with the signed-in email (upcoming or past)', ref('GuestBookings'), { query: myBookingsQuery, guest: true, description: guestNote }), ...cors };
+  paths['/api/v1/guest/revoke'] = { post: priv('Sign this device out', ref('GuestSignedOut'), { guest: true, write: true }), ...cors };
   const writeErrors = { ...errors, 429: { ...errors[429], description: 'Write limit exceeded (20/minute/client address).' },
     ...Object.fromEntries([413, 415].map(code => [code, { description: 'Request rejected.', content: media(ref('Error')) }])) };
   const noStore = { 'Cache-Control': { schema: { type: 'string', const: 'no-store' } } };
@@ -101,11 +137,11 @@ export async function getOpenApi(_repo: ContentRepository, url: URL) {
   };
   Object.assign(paths, editorPaths(jsonSchema));
   return {
-    openapi: '3.1.0', info: { title: 'ACMS Mobile API', version: '1.0.0', description: 'Public API: no authentication. Disabled modules are not registered. Unknown or duplicate query parameters are rejected. locale selects translated words with main-language fallback; unknown locales return 400. Editor API (tag Editor): /api/v1/auth/* and /api/v1/admin/*, registered only when acms({ mobile: { editor } }) is configured; staff sign in through the browser (OAuth 2.0 authorization code + PKCE) and send the device access token as a Bearer header. Cookies never authenticate it.' },
+    openapi: '3.1.0', info: { title: 'ACMS Mobile API', version: '1.0.0', description: 'Public API: no authentication, except a booking’s own routes (/bookings/manage/*: its private token in the Booking-Token header) and guest sign-in (/guest/*: a guest token from an emailed code). Owner switches in Admin → Mobile app turn app features off (404). Disabled modules are not registered. Unknown or duplicate query parameters are rejected. locale selects translated words with main-language fallback; unknown locales return 400. Editor API (tag Editor): /api/v1/auth/* and /api/v1/admin/*, registered only when acms({ mobile: { editor } }) is configured; staff sign in through the browser (OAuth 2.0 authorization code + PKCE) and send the device access token as a Bearer header. Cookies never authenticate it.' },
     tags: [{ name: 'Public', description: 'Visitor apps: no authentication.' }, { name: 'Editor', description: 'Editor apps: device sign-in and the admin API.' }],
     paths, components: {
       schemas: Object.fromEntries([...Object.entries(schemas), ...Object.entries(editorSchemas)].map(([name, schema]) => [name, jsonSchema(schema as z.ZodTypeAny)])),
-      securitySchemes: editorSecuritySchemes,
+      securitySchemes: { ...editorSecuritySchemes, guestToken: { type: 'http', scheme: 'bearer', bearerFormat: 'acms_guest_…', description: 'Guest token from POST /api/v1/guest/token. Reads that email’s bookings only.' } },
     },
   };
 }

package/src/lib/mobile/route.ts

@@ -1,16 +1,28 @@
 import type { APIRoute } from 'astro';
 import type { ContentRepository } from '../repo/types';
 import { getRepo } from '../repo';
-import { limitRequest, failure, publicResponse, response } from './http';
-export function readRoute(load: (repo: ContentRepository, url: URL, id: string) => Promise<unknown>, cache = true, raw = false): APIRoute {
+import { userConfig } from 'virtual:acms-config';
+import { limitRequest, failure, response, headers as baseHeaders, etagMatches } from './http';
+import { API_REVALIDATE } from '../cache/policy';
+import { CACHE } from '../cache/config';
+import { memoryGet, memorySet } from '../cache/memory';
+
+type Load = (repo: ContentRepository, url: URL, id: string, locals: unknown) => Promise<unknown>;
+/**
+ * A public, cacheable read. `timeless` routes depend only on stored content;
+ * the rest (upcoming events, dynamic page blocks, search) also change with
+ * the clock, so their ETag rolls over every cache.maxAge seconds too.
+ */
+export function readRoute(load: Load, cache = true, raw = false, opts: { timeless?: boolean } = {}): APIRoute {
   return async context => {
     try {
       const repo = await getRepo(context.locals);
       let address = 'unknown';
       try { address = context.clientAddress || address; } catch { /* adapters without a client address share a bucket */ }
       await limitRequest(repo, address);
-      const data = await load(repo, context.url, context.params.id ?? context.params.slug ?? '');
-      const res = cache ? await publicResponse(context.request, data, raw) : response(data);
+      const id = context.params.id ?? context.params.slug ?? '';
+      const res = cache ? await versionedResponse(repo, context, () => load(repo, context.url, id, context.locals), raw, opts.timeless)
+        : response(await load(repo, context.url, id, context.locals));
       return context.request.method === 'HEAD' ? new Response(null, { status: res.status, headers: res.headers }) : res;
     } catch (error) {
       const res = failure(error);
@@ -18,3 +30,50 @@ export function readRoute(load: (repo: ContentRepository, url: URL, id: string)
     }
   };
 }
+
+const CORE = String((userConfig as { coreVersion?: string }).coreVersion ?? '0');
+// The ETag comes from the content version (plus the framework version, and
+// a time window for clock-dependent routes), so a matching If-None-Match is
+// answered 304 before any content is loaded or serialized.
+async function versionedResponse(repo: ContentRepository, context: { request: Request; url: URL; locals: unknown }, build: () => Promise<unknown>, raw: boolean, timeless = false) {
+  const { version } = await repo.getCacheState();
+  const window = timeless ? '' : `.${Math.floor(Date.now() / (Math.max(CACHE.maxAge, 1) * 1000))}`;
+  const etag = `"c${version}${window}-${CORE}"`;
+  const h = new Headers(baseHeaders);
+  h.set('ETag', etag);
+  h.set('Cache-Control', API_REVALIDATE);
+  h.set('Content-Type', 'application/json');
+  if (etagMatches(context.request, etag)) return new Response(null, { status: 304, headers: h });
+  // Node only: Workers isolates are short-lived and many
+  const memory = CACHE.enabled && CACHE.memory && !(context.locals as { runtime?: unknown } | undefined)?.runtime;
+  const key = `${etag} ${context.url.href}`;
+  let body = memory ? memoryGet(key) : undefined;
+  if (body === undefined) {
+    const data = await build();
+    body = JSON.stringify(raw ? data : { version: 1, data });
+    if (memory) memorySet(key, body);
+  }
+  return new Response(body, { status: 200, headers: h });
+}
+
+export interface PublicContext { repo: ContentRepository; request: Request; url: URL; address: string; params: Record<string, string | undefined>; locals: unknown }
+/**
+ * A private or write route on the public API: rate limited per client
+ * address (reads 300/min, writes 20/min), never cached, v1 envelope.
+ * Handlers may return a Response (files, custom status).
+ */
+export function privateRoute(handler: (c: PublicContext) => Promise<unknown>, opts: { write?: boolean; status?: number } = {}): APIRoute {
+  return async context => {
+    try {
+      const repo = await getRepo(context.locals);
+      let address = 'unknown';
+      try { address = context.clientAddress || address; } catch { /* adapters without a client address share a bucket */ }
+      await limitRequest(repo, address, opts.write);
+      const data = await handler({ repo, request: context.request, url: context.url, address, params: context.params, locals: context.locals });
+      if (data instanceof Response) return data;
+      return response(data, opts.status ?? 200);
+    } catch (error) {
+      return failure(error);
+    }
+  };
+}