@acms-subir/core 0.1.0 → 0.3.0

package/src/lib/agent.ts

@@ -0,0 +1,114 @@
+import { z } from 'zod';
+import sanitizeHtml from 'sanitize-html';
+import { renderMarkdown } from './markdown';
+import { slugify, type Page, type Post } from './schema';
+import { CONTENT } from './content';
+import type { ContentRepository } from './repo/types';
+import { ApiError } from './api';
+import { EventToolInputs } from './calendar/agent-schema';
+import { runEventTool, type AgentContext, type EventToolInput } from './calendar/agent';
+import { BookingToolInputs, BOOKING_TOOL_NAMES, runBookingTool } from './booking/agent';
+
+const Kind = z.enum(['posts', 'pages']);
+const fields = {
+  title: z.string().trim().min(1).max(300).optional(),
+  content: z.string().max(100_000).optional(),
+  excerpt: z.string().max(2000).optional(),
+  tags: z.array(z.string().trim().min(1).max(100)).max(50).optional(),
+  seoTitle: z.string().max(300).optional(), seoDesc: z.string().max(2000).optional(),
+};
+export const AgentInput = z.discriminatedUnion('tool', [
+  z.object({ tool: z.literal('list_content'), arguments: z.object({ kind: Kind, collection: z.string().optional(), query: z.string().max(200).optional(), offset: z.number().int().min(0).default(0), limit: z.number().int().min(1).max(100).default(25) }).strict() }).strict(),
+  z.object({ tool: z.literal('get_content'), arguments: z.object({ kind: Kind, id: z.string().min(1) }).strict() }).strict(),
+  z.object({ tool: z.literal('create_draft'), arguments: z.object({ ...fields, kind: Kind, title: z.string().trim().min(1).max(300), slug: z.string().max(300).optional(), collection: z.string().optional() }).strict() }).strict(),
+  z.object({ tool: z.literal('update_content'), arguments: z.object({ ...fields, kind: Kind, id: z.string().min(1) }).strict() }).strict(),
+  z.object({ tool: z.literal('publish_content'), arguments: z.object({ kind: Kind, id: z.string().min(1) }).strict() }).strict(),
+  ...EventToolInputs,
+  ...BookingToolInputs,
+]);
+export function renderAgentMarkdown(markdown: string): string {
+  const html = sanitizeHtml(renderMarkdown(markdown), {
+    allowedTags: [...sanitizeHtml.defaults.allowedTags, 'img'],
+    allowedAttributes: { ...sanitizeHtml.defaults.allowedAttributes, img: ['src', 'alt', 'title'], code: ['class'] },
+    allowedSchemes: ['http', 'https', 'mailto'], allowProtocolRelative: false,
+  });
+  // Editors/public templates fall back to legacy Markdown when bodyHtml is
+  // empty. Keep that fallback from reintroducing stripped HTML-only input.
+  return html || (markdown ? '<p></p>' : '');
+}
+const editUrl = (kind: 'posts' | 'pages', doc: { id: string; collection?: string }) => kind === 'pages' ? `/admin/pages/${doc.id}` : `/admin/c/${doc.collection}/${doc.id}`;
+
+export async function runAgentTool(repo: ContentRepository, raw: unknown, allowPublish: boolean, ctx: AgentContext = { origin: '' }) {
+  const parsed = AgentInput.parse(raw);
+  if ((BOOKING_TOOL_NAMES as readonly string[]).includes(parsed.tool)) {
+    return runBookingTool(repo, parsed as never, allowPublish, ctx);
+  }
+  if (parsed.tool.endsWith('_event') || parsed.tool === 'list_events' || parsed.tool === 'list_calendars') {
+    return runEventTool(repo, parsed as EventToolInput, allowPublish, ctx);
+  }
+  const input = parsed as Extract<typeof parsed, { tool: 'list_content' | 'get_content' | 'create_draft' | 'update_content' | 'publish_content' }>;
+  const args = input.arguments;
+  const isPost = args.kind === 'posts';
+  if (input.tool === 'list_content') {
+    const a = input.arguments;
+    if (a.collection && !CONTENT.collections[a.collection]) throw new ApiError(400, 'Unknown collection.');
+    let docs: (Page | Post)[] = isPost ? await repo.listPosts(a.collection) : await repo.listPages();
+    if (a.query) docs = docs.filter((d) => `${d.title} ${d.slug}`.toLowerCase().includes(a.query!.toLowerCase()));
+    return { total: docs.length, offset: a.offset, items: docs.slice(a.offset, a.offset + a.limit).map((d) => ({ id: d.id, title: d.title, slug: d.slug, status: d.status, updatedAt: d.updatedAt, hasPendingDraft: !!d.draft, editUrl: editUrl(a.kind, d) })) };
+  }
+  if (input.tool === 'create_draft') {
+    const a = input.arguments;
+    if (isPost && !CONTENT.collections[a.collection ?? 'posts']) throw new ApiError(400, 'Unknown collection.');
+    if (!isPost && (a.tags !== undefined || a.excerpt !== undefined || a.collection !== undefined)) throw new ApiError(400, 'Tags, excerpts, and collections apply only to posts.');
+    const base = slugify(a.slug || a.title) || 'untitled';
+    let slug = base;
+    for (let n = 2; isPost ? await repo.getPostBySlug(slug, a.collection ?? 'posts') : await repo.getPageBySlug(slug); n++) slug = `${base}-${n}`;
+    const data = contentFields(a);
+    const doc = isPost ? await repo.createPost({ title: a.title, slug, collection: a.collection }) : await repo.createPage({ title: a.title, slug });
+    if (isPost) { await repo.updatePost(doc.id, data); if (a.tags) await repo.ensureTags(a.tags); }
+    else await repo.updatePage(doc.id, pageFields(data));
+    return { id: doc.id, slug, status: 'draft', editUrl: editUrl(a.kind, doc) };
+  }
+  const a = input.arguments;
+  const doc = isPost ? await repo.getPost(a.id) : await repo.getPage(a.id);
+  if (!doc) throw new ApiError(404, 'Content not found.');
+  if (input.tool === 'get_content') return { ...doc, editUrl: editUrl(a.kind, doc) };
+  if (input.tool === 'publish_content') {
+    if (!allowPublish) throw new ApiError(403, 'Agent publishing is disabled. An owner can enable it in Settings.');
+    // Existing editor drafts can rename content; agents never publish those
+    // implicitly because doing so requires redirect/homepage handling.
+    if (doc.draft && Object.keys(doc.draft).some((key) => !['title', 'body', 'bodyHtml', 'bodyJson', 'excerpt', 'tags', 'seoTitle', 'seoDesc', 'savedAt'].includes(key))) {
+      throw new ApiError(409, 'This draft contains editor layout or routing changes. Publish it from the admin editor.');
+    }
+    if (isPost) {
+      if (doc.draft) await repo.applyPostDraft(doc.id);
+      const updated = await repo.getPost(doc.id);
+      if (updated?.tags.length) await repo.ensureTags(updated.tags);
+      await repo.updatePost(doc.id, { status: 'published', scheduledAt: null });
+    } else {
+      if (doc.draft) await repo.applyPageDraft(doc.id);
+      await repo.updatePage(doc.id, { status: 'published' });
+    }
+    return { id: doc.id, status: 'published', editUrl: editUrl(a.kind, doc) };
+  }
+  const changes = input.arguments;
+  if (!isPost && (changes.tags !== undefined || changes.excerpt !== undefined)) throw new ApiError(400, 'Tags and excerpts apply only to posts.');
+  const data = contentFields(changes);
+  if (!Object.keys(data).length) throw new ApiError(400, 'Provide at least one content field to update.');
+  const staged = doc.status === 'published' || doc.status === 'scheduled';
+  if (isPost) {
+    if (staged) await repo.savePostDraft(doc.id, data); else await repo.updatePost(doc.id, data);
+    if (changes.tags) await repo.ensureTags(changes.tags);
+  } else {
+    if (staged) await repo.savePageDraft(doc.id, pageFields(data)); else await repo.updatePage(doc.id, pageFields(data));
+  }
+  return { id: doc.id, status: doc.status, staged, editUrl: editUrl(a.kind, doc) };
+}
+function contentFields(args: z.infer<z.ZodObject<typeof fields>>) {
+  const { content, ...rest } = z.object(fields).parse(args);
+  return { ...rest, ...(content !== undefined ? { body: content, bodyJson: '', bodyHtml: renderAgentMarkdown(content) } : {}) };
+}
+function pageFields(data: ReturnType<typeof contentFields>) {
+  const { body: _body, tags: _tags, excerpt: _excerpt, ...rest } = data;
+  return rest;
+}

package/src/lib/ai-config.ts

@@ -0,0 +1,58 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { env } from './env';
+
+import type { AiConfig } from './ai-schema';
+
+// Only owners configure this destination. Private addresses are intentional
+// for Node deployments on a tailnet. Never accept per-generation URLs.
+export function normalizeAiUrl(provider: AiConfig['provider'], raw: string): string {
+  if (provider === 'openai') return 'https://api.openai.com/v1';
+  let url: URL;
+  try { url = new URL(raw.trim()); } catch { throw new Error('Enter a full API URL starting with https:// or http://.'); }
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+    throw new Error('API URL must use HTTP(S), without credentials, query parameters, or a fragment.');
+  }
+  let path = url.pathname.replace(/\/+$/, '');
+  if (/\/(management\.html|v0\/management)(\/|$)/i.test(path)) throw new Error('Use the proxy API base URL, not the CPAMC management URL.');
+  if (/\/(chat\/completions|responses|models)$/.test(path)) throw new Error('Enter the API base URL, not an individual endpoint.');
+  // Custom providers may serve at the root, /v1, /api/v4, or another prefix.
+  // Use the supplied base exactly; never guess a provider's API version.
+  url.pathname = path;
+  return url.href.replace(/\/+$/, '');
+}
+function encryptionKey(): Buffer {
+  const secret = env('SESSION_SECRET');
+  if (!secret) throw new Error('SESSION_SECRET is required to store AI credentials.');
+  return createHash('sha256').update(`acms:ai:v1:${secret}`).digest();
+}
+export function encryptApiKey(value: string): string {
+  if (!value) return '';
+  const iv = randomBytes(12);
+  const cipher = createCipheriv('aes-256-gcm', encryptionKey(), iv);
+  const ciphertext = Buffer.concat([cipher.update(value, 'utf8'), cipher.final()]);
+  return [iv, cipher.getAuthTag(), ciphertext].map((v) => v.toString('base64url')).join('.');
+}
+export function decryptApiKey(value: string): string {
+  if (!value) return '';
+  try {
+    const parts = value.split('.');
+    if (parts.length !== 3) throw new Error();
+    const [iv, tag, ciphertext] = parts.map((v) => Buffer.from(v, 'base64url'));
+    const decipher = createDecipheriv('aes-256-gcm', encryptionKey(), iv);
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');
+  } catch { throw new Error('The saved AI key cannot be decrypted. Re-enter it in Settings.'); }
+}
+export const hashAgentKey = (key: string) => createHash('sha256').update(key).digest('hex');
+export function validAgentKey(key: string, hash: string): boolean {
+  if (!key || !/^[a-f0-9]{64}$/.test(hash)) return false;
+  return timingSafeEqual(Buffer.from(hashAgentKey(key), 'hex'), Buffer.from(hash, 'hex'));
+}
+export function generateAgentKey() {
+  const token = `acms_agent_${randomBytes(32).toString('hex')}`;
+  return { token, keyHash: hashAgentKey(token), keyPrefix: token.slice(0, 18) };
+}
+export function publicAiConfig(ai: AiConfig) {
+  const { encryptedKey, ...config } = ai;
+  return { ...config, hasApiKey: !!encryptedKey };
+}

package/src/lib/ai-schema.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+
+// Read legacy provider names as Custom without changing saved URLs or keys.
+export const AiProvider = z.enum(['openai', 'custom', 'cliproxy', 'tailscale'])
+  .transform((provider): 'openai' | 'custom' => provider === 'openai' ? 'openai' : 'custom');
+
+export const AiConfig = z.object({
+  enabled: z.boolean().default(false),
+  provider: AiProvider.default('openai'),
+  baseUrl: z.string().default('https://api.openai.com/v1'),
+  model: z.string().default(''),
+  encryptedKey: z.string().default(''),
+}).default({});
+export type AiConfig = z.infer<typeof AiConfig>;
+export const AgentConfig = z.object({
+  enabled: z.boolean().default(false),
+  keyHash: z.string().default(''),
+  keyPrefix: z.string().default(''),
+  allowPublish: z.boolean().default(false),
+}).default({});
+export type AgentConfig = z.infer<typeof AgentConfig>;
+

package/src/lib/ai.ts

@@ -0,0 +1,90 @@
+import { z } from 'zod';
+import type { AiConfig } from './ai-schema';
+import { decryptApiKey, normalizeAiUrl } from './ai-config';
+import { ApiError, readResponseJson } from './api';
+import { CleanupInput, cleanupInstructions } from './documents/cleanup';
+import { francAll } from 'franc-min';
+
+async function providerRequest(config: AiConfig, path: string, payload?: unknown): Promise<unknown> {
+  const baseUrl = normalizeAiUrl(config.provider, config.baseUrl);
+  let key: string;
+  try { key = decryptApiKey(config.encryptedKey); }
+  catch { throw new ApiError(409, 'The saved AI key cannot be decrypted. Re-enter it in Settings.'); }
+  if (config.provider === 'openai' && !key) throw new ApiError(400, 'Add your OpenAI API key in Settings.');
+  let response: Response;
+  try {
+    response = await fetch(`${baseUrl}/${path}`, {
+      method: payload ? 'POST' : 'GET', redirect: 'error', signal: AbortSignal.timeout(payload ? 90_000 : 15_000),
+      headers: { Accept: 'application/json', ...(key ? { Authorization: `Bearer ${key}` } : {}), ...(payload ? { 'Content-Type': 'application/json' } : {}) },
+      ...(payload ? { body: JSON.stringify(payload) } : {}),
+    });
+  } catch {
+    throw new ApiError(502, new URL(baseUrl).hostname.endsWith('.ts.net')
+      ? 'Cannot reach the Tailscale proxy. The Node server must be on your tailnet; Cloudflare needs a publicly reachable endpoint. Check the URL, Tailscale access, and proxy service.'
+      : 'Cannot reach the AI provider. Check the API URL and network connection.');
+  }
+  if (!response.ok) {
+    await response.body?.cancel();
+    const detail = response.status === 401 || response.status === 403 ? 'Check the client API key and provider access.'
+      : response.status === 429 ? 'Provider quota or rate limit reached. Try again later.'
+      : response.status === 404 ? 'Check the API base URL and selected model.' : 'Check the provider service and model.';
+    throw new ApiError(502, `AI provider returned HTTP ${response.status}. ${detail}`);
+  }
+  try { return await readResponseJson(response, 2_000_000); }
+  catch { throw new ApiError(502, 'Provider returned an invalid or oversized JSON response. Check that the URL serves the AI API.'); }
+}
+export async function listAiModels(config: AiConfig) {
+  const result = z.object({ data: z.array(z.object({ id: z.string() })) }).safeParse(await providerRequest(config, 'models'));
+  if (!result.success) throw new ApiError(502, 'Provider did not return an OpenAI-compatible model list.');
+  return [...new Set(result.data.data.map((m) => m.id))].sort();
+}
+async function requestCleanupText(config: AiConfig, instruction: string, input: string) {
+  if (!config.enabled) throw new ApiError(409, 'AI is disabled. Enable it in Settings → AI & agents.');
+  if (!config.model) throw new ApiError(400, 'Choose an AI model in Settings.');
+  if (config.provider === 'openai') {
+    const raw = await providerRequest(config, 'responses', { model: config.model, instructions: instruction, input, store: false, max_output_tokens: 16384 });
+    const result = z.object({ status: z.string().optional(), output: z.array(z.object({ content: z.array(z.object({ type: z.string(), text: z.string().optional() })).optional() })).optional() }).safeParse(raw);
+    if (!result.success || result.data.status === 'incomplete' || result.data.status === 'failed') throw new ApiError(502, 'The provider could not complete the cleanup. Try a smaller document or a model with a larger output limit.');
+    const text = result.data.output?.flatMap((o) => o.content ?? []).filter((c) => c.type === 'output_text').map((c) => c.text ?? '').join('\n').trim();
+    if (!text) throw new ApiError(502, 'The provider returned no cleaned text. Try another model.');
+    return text;
+  }
+  const raw = await providerRequest(config, 'chat/completions', { model: config.model, messages: [{ role: 'system', content: instruction }, { role: 'user', content: input }], stream: false, max_tokens: 16384 });
+  const result = z.object({ choices: z.array(z.object({ message: z.object({ content: z.string().nullable() }), finish_reason: z.string().nullish() })) }).safeParse(raw);
+  const choice = result.success ? result.data.choices[0] : null;
+  if (!choice?.message.content?.trim() || choice.finish_reason === 'length') throw new ApiError(502, 'The provider returned empty or incomplete text. Try another model or a smaller document.');
+  return choice.message.content.trim();
+}
+
+
+// This is a conservative guard, not a language guarantee: short/ambiguous or
+// mixed-language documents still need review. Reject clear full-document
+// language switches rather than silently accepting a translated result.
+function languageChanged(source: string, cleaned: string): boolean {
+  if (source.length < 160 || cleaned.length < 160) return false;
+  const before = francAll(source, { minLength: 160 });
+  const after = francAll(cleaned, { minLength: 160 });
+  if (before[0]?.[0] === 'und' || after[0]?.[0] === 'und' || before[0]?.[0] === after[0]?.[0]) return false;
+  const beforeInAfter = after.find(([lang]) => lang === before[0]?.[0])?.[1] ?? 0;
+  const afterInBefore = before.find(([lang]) => lang === after[0]?.[0])?.[1] ?? 0;
+  return beforeInAfter < 0.7 && afterInBefore < 0.7;
+}
+
+export async function cleanDocument(config: AiConfig, raw: unknown) {
+  const input = CleanupInput.parse(raw);
+  const response = await requestCleanupText(config, cleanupInstructions(input), JSON.stringify({
+    cleanupNotes: input.notes, sourceDocument: input.source,
+  }));
+  let parsed: unknown;
+  try { parsed = JSON.parse(response.replace(/^```(?:json)?\s*\n?/, '').replace(/\n?```$/, '').trim()); }
+  catch { throw new ApiError(502, 'The provider returned an unreadable cleanup result. Your original document is unchanged. Try again.'); }
+  const result = z.object({ text: z.string().trim().min(1).max(100_000), warnings: z.array(z.string().max(1000)).max(30).default([]) }).safeParse(parsed);
+  if (!result.success) throw new ApiError(502, 'The provider returned an invalid cleanup result. Your original document is unchanged.');
+  if (!input.translate && languageChanged(input.source, result.data.text)) {
+    throw new ApiError(502, 'The cleanup appears to change the document language without permission. The result was rejected; retry or use another model.');
+  }
+  if (!input.translate && result.data.text.replace(/\s+/g, ' ').length < input.source.replace(/\s+/g, ' ').length * 0.55) {
+    throw new ApiError(502, 'The cleanup appears to omit too much source content. The result was rejected. Try a smaller document or another model.');
+  }
+  return { ...result.data, model: config.model };
+}

package/src/lib/analytics.ts

@@ -0,0 +1,121 @@
+// Analytics providers (Umami, Meta Pixel, TikTok Pixel): builds the script
+// markup Site.astro renders into the public <head> via set:html. Because the
+// output bypasses Astro's escaping, nothing is emitted unless the stored
+// ID/URL passes its validator — a bad value renders nothing, never broken or
+// injected markup. The admin form rejects invalid values with the same rules.
+import type { Settings } from './schema';
+
+export const UMAMI_ID_RE = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i;
+export const META_PIXEL_ID_RE = /^\d{5,20}$/;
+export const TIKTOK_PIXEL_ID_RE = /^[A-Z0-9_-]{8,40}$/i;
+
+// https only (self-hosted instances included); returns the normalized href,
+// whose serialization percent-encodes quotes/angle brackets, so the value is
+// attribute-safe. Belt and braces: reject anything still risky post-encode.
+export function normalizeScriptUrl(url: string): string {
+  try {
+    const href = new URL(url).href;
+    if (new URL(url).protocol !== 'https:' || /["'<>\s]/.test(href)) return '';
+    return href;
+  } catch {
+    return '';
+  }
+}
+
+type Analytics = Settings['analytics'];
+
+function umamiTag(a: Analytics['umami']): string {
+  const src = normalizeScriptUrl(a.scriptUrl);
+  if (!a.enabled || !UMAMI_ID_RE.test(a.websiteId) || !src) return '';
+  return `<script defer src="${src}" data-website-id="${a.websiteId.toLowerCase()}"></script>`;
+}
+
+// The replay recorder lives next to the tracker on the same instance:
+// swap the URL's last path segment for recorder.js and re-validate.
+export function umamiRecorderUrl(scriptUrl: string): string {
+  const src = normalizeScriptUrl(scriptUrl);
+  if (!src) return '';
+  const url = new URL(src);
+  url.pathname = url.pathname.replace(/[^/]*$/, 'recorder.js');
+  return normalizeScriptUrl(url.href);
+}
+
+// Session replay (Umami v3.1+): a second tag mirroring the dashboard-generated
+// snippet. Attributes are re-clamped here because, like the rest of this file,
+// the output bypasses Astro escaping — schema-invalid values render defaults,
+// never broken markup.
+function umamiReplayTag(a: Analytics['umami']): string {
+  const src = umamiRecorderUrl(a.scriptUrl);
+  if (!a.enabled || !a.replay.enabled || !UMAMI_ID_RE.test(a.websiteId) || !src) return '';
+  const rate =
+    Number.isFinite(a.replay.sampleRate) && a.replay.sampleRate >= 0.01 && a.replay.sampleRate <= 1
+      ? a.replay.sampleRate
+      : 0.15;
+  const mask = a.replay.maskLevel === 'strict' ? 'strict' : 'moderate';
+  const duration =
+    Number.isInteger(a.replay.maxDuration) && a.replay.maxDuration > 0 ? a.replay.maxDuration : 300000;
+  return `<script defer src="${src}" data-website-id="${a.websiteId.toLowerCase()}" data-sample-rate="${rate}" data-mask-level="${mask}" data-max-duration="${duration}"></script>`;
+}
+
+// Meta's standard base code: fbq loader + PageView, with the no-JS pixel
+// image fallback. The ID is digits-only by validation, so safe to inline.
+function metaPixelTag(a: Analytics['metaPixel']): string {
+  if (!a.enabled || !META_PIXEL_ID_RE.test(a.pixelId)) return '';
+  return `<script>
+!function(f,b,e,v,n,t,s){if(f.fbq)return;n=f.fbq=function(){n.callMethod?
+n.callMethod.apply(n,arguments):n.queue.push(arguments)};if(!f._fbq)f._fbq=n;
+n.push=n;n.loaded=!0;n.version='2.0';n.queue=[];t=b.createElement(e);t.async=!0;
+t.src=v;s=b.getElementsByTagName(e)[0];s.parentNode.insertBefore(t,s)}(window,
+document,'script','https://connect.facebook.net/en_US/fbevents.js');
+fbq('init', '${a.pixelId}');
+fbq('track', 'PageView');
+</script>
+<noscript><img height="1" width="1" style="display:none" src="https://www.facebook.com/tr?id=${a.pixelId}&ev=PageView&noscript=1"/></noscript>`;
+}
+
+// TikTok's published base code (experimental — untested live): ttq loader +
+// page(). ID is restricted to [A-Z0-9_-] by validation.
+function tiktokPixelTag(a: Analytics['tiktokPixel']): string {
+  if (!a.enabled || !TIKTOK_PIXEL_ID_RE.test(a.pixelId)) return '';
+  return `<script>
+!function (w, d, t) {
+w.TiktokAnalyticsObject=t;var ttq=w[t]=w[t]||[];ttq.methods=["page","track","identify","instances","debug","on","off","once","ready","alias","group","enableCookie","disableCookie"],ttq.setAndDefer=function(t,e){t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}};for(var i=0;i<ttq.methods.length;i++)ttq.setAndDefer(ttq,ttq.methods[i]);ttq.instance=function(t){for(var e=ttq._i[t]||[],n=0;n<e.length;n++)ttq.setAndDefer(e[n],ttq.methods[n]);return e},ttq.load=function(e,n){var i="https://analytics.tiktok.com/i18n/pixel/events.js";ttq._i=ttq._i||{},ttq._i[e]=[],ttq._i[e]._u=i,ttq._t=ttq._t||{},ttq._t[e]=+new Date,ttq._o=ttq._o||{},ttq._o[e]=n||{};var o=document.createElement("script");o.type="text/javascript",o.async=!0,o.src=i+"?sdkid="+e+"&lib="+t;var a=document.getElementsByTagName("script")[0];a.parentNode.insertBefore(o,a)};
+ttq.load('${a.pixelId}');
+ttq.page();
+}(window, document, 'ttq');
+</script>`;
+}
+
+export function analyticsHead(settings: Settings): string {
+  const a = settings.analytics;
+  return [umamiTag(a.umami), umamiReplayTag(a.umami), metaPixelTag(a.metaPixel), tiktokPixelTag(a.tiktokPixel)]
+    .filter(Boolean)
+    .join('\n');
+}
+
+// Event names are author-typed; collapse whitespace so "Sign  up " and
+// "Sign up" count as one event in the dashboards.
+export function cleanEventName(name: string): string {
+  return name.replace(/\s+/g, ' ').trim();
+}
+
+// Click-event bridge: elements carrying data-umami-event (editor cards, the
+// links page) are counted by Umami natively — this dispatcher only exists to
+// forward the same clicks to the ad pixels, so it is emitted solely when one
+// of them is actually enabled. Umami-only sites ship zero extra JS.
+export function analyticsBody(settings: Settings): string {
+  const a = settings.analytics;
+  const meta = a.metaPixel.enabled && META_PIXEL_ID_RE.test(a.metaPixel.pixelId);
+  const tiktok = a.tiktokPixel.enabled && TIKTOK_PIXEL_ID_RE.test(a.tiktokPixel.pixelId);
+  if (!meta && !tiktok) return '';
+  return `<script>
+document.addEventListener('click', function (e) {
+  var el = e.target && e.target.closest && e.target.closest('[data-umami-event]');
+  if (!el) return;
+  var name = el.getAttribute('data-umami-event');
+  if (!name) return;
+  if (window.fbq) window.fbq('trackCustom', name);
+  if (window.ttq) window.ttq.track(name);
+});
+</script>`;
+}

package/src/lib/api-keys.ts

@@ -0,0 +1,65 @@
+// Scoped API keys for the integration APIs (/api/calendar/*, and bookings
+// later). A key is shown once at creation; only its SHA-256 hash is stored.
+// The agent key from Settings → AI & agents also authenticates here and
+// counts as every scope, so existing agent setups keep working.
+import type { ContentRepository } from './repo/types';
+import type { ApiScope } from './schema';
+import { ApiError } from './api';
+import { validAgentKey } from './ai-config';
+
+export const API_KEY_PREFIX = 'acms_key_';
+
+const hex = (bytes: ArrayBuffer | Uint8Array) =>
+  [...new Uint8Array(bytes)].map((b) => b.toString(16).padStart(2, '0')).join('');
+
+export async function sha256Hex(value: string): Promise<string> {
+  return hex(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(value)));
+}
+
+export function generateApiKey(): string {
+  return API_KEY_PREFIX + hex(crypto.getRandomValues(new Uint8Array(24)));
+}
+
+// creates the record and returns the plaintext key — the only time it exists
+export async function issueApiKey(repo: ContentRepository, name: string, scopes: ApiScope[]) {
+  const key = generateApiKey();
+  const record = await repo.createApiKey({
+    name: name.trim() || 'API key',
+    prefix: key.slice(0, API_KEY_PREFIX.length + 6),
+    keyHash: await sha256Hex(key),
+    scopes: [...new Set(scopes)],
+  });
+  return { key, record };
+}
+
+export interface ApiPrincipal {
+  via: 'key' | 'agent';
+  name: string;
+  scopes: Set<ApiScope> | 'all';
+}
+
+export const hasScope = (p: ApiPrincipal, scope: ApiScope) => p.scopes === 'all' || p.scopes.has(scope);
+
+// null = no (or an unknown) bearer token; callers decide whether anonymous
+// access is fine (public calendars) or a 401
+export async function authenticate(request: Request, repo: ContentRepository): Promise<ApiPrincipal | null> {
+  const auth = request.headers.get('authorization') ?? '';
+  const token = auth.startsWith('Bearer ') ? auth.slice(7).trim() : '';
+  if (!token) return null;
+  if (token.startsWith(API_KEY_PREFIX)) {
+    const key = await repo.findApiKeyByHash(await sha256Hex(token));
+    return key ? { via: 'key', name: key.name, scopes: new Set(key.scopes) } : null;
+  }
+  const { agent } = await repo.getSettings();
+  if (agent.enabled && validAgentKey(token, agent.keyHash)) return { via: 'agent', name: 'Agent key', scopes: 'all' };
+  return null;
+}
+
+export async function requireScope(request: Request, repo: ContentRepository, scope: ApiScope): Promise<ApiPrincipal> {
+  const principal = await authenticate(request, repo);
+  if (!principal) {
+    throw new ApiError(401, 'Send an API key: Authorization: Bearer <key>.');
+  }
+  if (!hasScope(principal, scope)) throw new ApiError(403, `This key is missing the ${scope} scope.`);
+  return principal;
+}

package/src/lib/api.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+import { validateSession, OWNER_ENV, SESSION_COOKIE } from './auth';
+import type { ContentRepository } from './repo/types';
+
+export class ApiError extends Error {
+  constructor(public status: number, message: string) { super(message); }
+}
+export const json = (body: unknown, status = 200) => Response.json(body, {
+  status, headers: { 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff' },
+});
+export function apiError(error: unknown): Response {
+  if (error instanceof ApiError) return json({ error: error.message }, error.status);
+  if (error instanceof z.ZodError) return json({ error: 'Invalid request', issues: error.issues.map(({ path, message }) => ({ path, message })) }, 400);
+  return json({ error: 'Request failed. Please try again.' }, 500);
+}
+export async function readJson(request: Request, maxBytes = 300_000): Promise<unknown> {
+  if (!request.headers.get('content-type')?.toLowerCase().startsWith('application/json')) throw new ApiError(415, 'Use Content-Type: application/json.');
+  return readResponseJson(request, maxBytes);
+}
+export async function readResponseJson(source: Request | Response, maxBytes: number): Promise<unknown> {
+  if (Number(source.headers.get('content-length')) > maxBytes) throw new ApiError(413, 'Payload too large.');
+  const reader = source.body?.getReader();
+  if (!reader) throw new ApiError(400, 'JSON body is required.');
+  const chunks: Uint8Array[] = [];
+  let length = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      length += value.byteLength;
+      if (length > maxBytes) { await reader.cancel(); throw new ApiError(413, 'Payload too large.'); }
+      chunks.push(value);
+    }
+  } finally { reader.releaseLock(); }
+  const bytes = new Uint8Array(length);
+  let offset = 0;
+  for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.length; }
+  try { return JSON.parse(new TextDecoder().decode(bytes)); }
+  catch { throw new ApiError(400, 'Body must be valid JSON.'); }
+}
+export async function requireSession(
+  request: Request, cookies: { get(name: string): { value: string } | undefined }, repo: ContentRepository, ownerOnly = false,
+) {
+  const id = (await validateSession(cookies.get(SESSION_COOKIE)?.value, repo));
+  if (!id) throw new ApiError(401, 'Sign in to continue.');
+  const user = id === OWNER_ENV ? null : await repo.getUser(id);
+  if (id !== OWNER_ENV && (!user || (ownerOnly && user.role !== 'owner'))) throw new ApiError(403, 'Owner access is required.');
+  const origin = request.headers.get('origin');
+  if ((origin && origin !== new URL(request.url).origin) || request.headers.get('sec-fetch-site') === 'cross-site') {
+    throw new ApiError(403, 'Cross-origin requests are not allowed.');
+  }
+}

package/src/lib/auth.ts

@@ -15,7 +15,8 @@ function hmac(payload: string): string {
 }
 
 function safeEqual(a: string, b: string): boolean {
-  return a.length === b.length && timingSafeEqual(Buffer.from(a), Buffer.from(b));
+  const left = Buffer.from(a), right = Buffer.from(b);
+  return left.length === right.length && timingSafeEqual(left, right);
 }
 
 // ---- sessions -------------------------------------------------------------
@@ -27,26 +28,33 @@ function safeEqual(a: string, b: string): boolean {
 
 export const OWNER_ENV = '__owner_env__';
 
-export function createSessionToken(userId: string = OWNER_ENV): string {
+export function createSessionToken(userId: string = OWNER_ENV, version = 0): string {
   const exp = Date.now() + WEEK_MS;
   if (userId === OWNER_ENV) return `${exp}.${hmac(String(exp))}`;
-  return `u.${userId}.${exp}.${hmac(`${userId}.${exp}`)}`;
+  return `v.${userId}.${version}.${exp}.${hmac(`${userId}.${version}.${exp}`)}`;
 }
 
 // Returns the session's user id (OWNER_ENV for env-password sessions) or
 // null. Truthy/falsy compatible with the old boolean signature.
 export function verifySessionToken(token: string | undefined): string | null {
   if (!token) return null;
+  if (token.startsWith('v.')) {
+    const parts = token.split('.');
+    if (parts.length !== 5) return null;
+    const [, id, version, exp, sig] = parts;
+    if (!id || !/^\d+$/.test(version) || !Number.isFinite(Number(exp)) || Number(exp) < Date.now()) return null;
+    return safeEqual(sig, hmac(`${id}.${version}.${exp}`)) ? id : null;
+  }
   if (token.startsWith('u.')) {
     const parts = token.split('.');
     if (parts.length !== 4) return null;
     const [, userId, expStr, sig] = parts;
-    if (!userId || Number(expStr) < Date.now()) return null;
+    if (!userId || !Number.isFinite(Number(expStr)) || Number(expStr) < Date.now()) return null;
     return safeEqual(sig, hmac(`${userId}.${expStr}`)) ? userId : null;
   }
   const [expStr, sig] = token.split('.');
   if (!expStr || !sig) return null;
-  if (Number(expStr) < Date.now()) return null;
+  if (!Number.isFinite(Number(expStr)) || Number(expStr) < Date.now()) return null;
   return safeEqual(sig, hmac(expStr)) ? OWNER_ENV : null;
 }
 
@@ -92,3 +100,15 @@ export async function verifyPassword(password: string, stored: string): Promise<
 }
 
 export const SESSION_COOKIE = COOKIE;
+
+// All authorization paths must consult the database, not just the signature.
+export async function validateSession(token: string | undefined, localsOrRepo?: unknown): Promise<string | null> {
+  const id = verifySessionToken(token);
+  if (!id || id === OWNER_ENV) return id;
+  const { getRepo } = await import('./repo');
+  const repo = localsOrRepo && typeof localsOrRepo === 'object' && 'email' in localsOrRepo
+    ? localsOrRepo as import('./repo/types').ContentRepository : await getRepo(localsOrRepo);
+  const version = await repo.email.sessionVersion(id);
+  const expected = token!.startsWith('v.') ? Number(token!.split('.')[2]) : 0;
+  return version !== null && version === expected ? id : null;
+}

package/src/lib/backup/content.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import { Page, Post, Media, Link, Tag, User, NavItem, Redirect, Settings, Calendar, CalEvent, Resource, BookingLink, Booking } from '../schema';
+import type { ContentRepository } from '../repo/types';
+
+export const BookingRequest = z.object({ keyHash: z.string().regex(/^[a-f0-9]{64}$/), requestHash: z.string().regex(/^[a-f0-9]{64}$/), bookingId: z.string().min(1), createdAt: z.number().int().nonnegative() });
+export type BookingRequest = z.infer<typeof BookingRequest>;
+export const BackupContent = z.object({
+  format: z.literal('acms-backup'), version: z.number().int().min(1).max(5), exportedAt: z.string().optional(),
+  settings: Settings.partial(), pages: z.array(Page), posts: z.array(Post), media: z.array(Media), links: z.array(Link),
+  tags: z.array(Tag), navItems: z.array(NavItem), users: z.array(User), redirects: z.array(Redirect).default([]),
+  calendars: z.array(Calendar).default([]), events: z.array(CalEvent).default([]), resources: z.array(Resource).default([]),
+  bookingLinks: z.array(BookingLink).default([]), bookings: z.array(Booking).default([]), bookingRequests: z.array(BookingRequest).optional(),
+}).superRefine((data, ctx) => {
+  if (data.version >= 5 && !data.bookingRequests) ctx.addIssue({ code: 'custom', message: 'Version 5 requires booking retry records.' });
+  const keys = new Set<string>();
+  for (const r of data.bookingRequests ?? []) {
+    if (keys.has(r.keyHash)) ctx.addIssue({ code: 'custom', message: 'Duplicate booking retry key.' });
+    keys.add(r.keyHash);
+  }
+  for (const m of data.media) for (const key of [m.key, ...m.variants.map(v => v.key)]) {
+    if (!key || key.startsWith('/') || key.includes('..') || key.includes('\\') || /[\x00-\x1f]/.test(key)) ctx.addIssue({ code: 'custom', message: 'Unsafe media key.' });
+  }
+});
+export async function exportContent(repo: ContentRepository, now = Date.now()) {
+  const [settings, pages, posts, media, links, tags, navItems, users, redirects, calendars, events, resources, bookingLinks, bookingState] = await Promise.all([
+    repo.getSettings(), repo.listPages(), repo.listPosts(), repo.listMedia(), repo.listLinks(), repo.listTags(), repo.listNavItems(),
+    repo.listUsers(), repo.listRedirects(), repo.listCalendars(), repo.listEvents(), repo.listResources(), repo.listBookingLinks(), repo.exportBookingState(),
+  ]);
+  return {
+    format: 'acms-backup' as const, version: 5, exportedAt: new Date(now).toISOString(),
+    settings: { ...settings, ai: { ...settings.ai, enabled: false, encryptedKey: '' }, agent: { ...settings.agent, enabled: false, keyHash: '', keyPrefix: '', allowPublish: false } },
+    pages, posts, media, links, tags, navItems, users, redirects,
+    calendars: calendars.map(c => ({ ...c, feedToken: '' })), events,
+    resources: resources.map(r => ({ ...r, feedToken: '' })), bookingLinks, ...bookingState,
+  };
+}