@glw907/cairn-cms 0.37.0 → 0.38.0

package/src/lib/sveltekit/admin-response.ts

@@ -0,0 +1,23 @@
+// Shared response helpers for cairn's admin pages: the baseline security headers and a branded
+// full-document response. Extracted from guard.ts so the guard's resolve path and the condition
+// renderer share one definition.
+
+/**
+ * Attach the baseline security headers to an admin response. No full CSP; see the auth-hardening
+ * design. frame-ancestors is the modern clickjacking control and the one CSP directive included.
+ */
+export function applySecurityHeaders(headers: Headers): void {
+  headers.set('X-Content-Type-Options', 'nosniff');
+  headers.set('X-Frame-Options', 'DENY');
+  headers.set('Content-Security-Policy', "frame-ancestors 'none'");
+  headers.set('Referrer-Policy', 'no-referrer');
+  headers.set('Strict-Transport-Security', 'max-age=63072000; includeSubDomains');
+  headers.set('Permissions-Policy', 'camera=(), microphone=(), geolocation=()');
+}
+
+/** A branded full-document admin page, hardened with the baseline headers and never cached. */
+export function brandedAdminPage(status: number, body: string): Response {
+  const headers = new Headers({ 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' });
+  applySecurityHeaders(headers);
+  return new Response(body, { status, headers });
+}

package/src/lib/sveltekit/auth-routes.ts

@@ -13,7 +13,7 @@ import {
   sessionCookieName,
 } from '../auth/crypto.js';
 import { findEditor, issueToken, consumeToken, createSession, deleteSession, recentlyIssued } from '../auth/store.js';
-import { buildMagicLinkMessage, cloudflareSend, type AuthBranding, type SendMagicLink } from '../email.js';
+import { buildMagicLinkMessage, cloudflareSend, emailSendFailure, errorCode, type AuthBranding, type SendMagicLink } from '../email.js';
 import { issueCsrfToken } from './csrf.js';
 import { log } from '../log/index.js';
 import type { RequestContext } from './types.js';
@@ -23,15 +23,37 @@ export interface AuthRoutesConfig {
   send?: SendMagicLink;
 }
 
+/**
+ * The request-action result. `status` is the discriminant; `sent` is kept for a site rendering its
+ * own form against `form.sent`, so the field is additive. The neutral and send-ok paths return the
+ * identical `{ status: 'sent', sent: true }`, so the common case never leaks allowlist membership.
+ */
+export type RequestResult =
+  | { status: 'sent'; sent: true }
+  | { status: 'send_error'; sent: false }
+  | { status: 'throttled'; sent: false };
+
+/**
+ * The loggable form of a send failure. The engine's own senders throw clean errors, but `send` is
+ * an injection seam, and a custom sender's thrown error may embed the failed message and with it
+ * the magic link. Scrub any token query value and cap the length, so the documented "records never
+ * carry a token" guarantee holds for the seam too.
+ */
+function scrubSendError(err: unknown): string {
+  return String(err)
+    .replace(/([?&]token=)[^&\s"'<]+/g, '$1[redacted]')
+    .slice(0, 300);
+}
+
 export function createAuthRoutes(config: AuthRoutesConfig) {
   const send = config.send ?? cloudflareSend;
 
   /**
-   * POST /admin/auth/request. Looks the email up in the allowlist; on a match, issues a token
-   * and emails the confirmation link. The response is identical whether or not the email is
-   * allow-listed, so the endpoint never leaks membership.
+   * POST /admin/auth/request. Looks the email up in the allowlist; on a match, issues a token,
+   * emails the confirmation link, and awaits the send so the status reflects its outcome. The
+   * neutral and send-ok responses are identical, so the common case never leaks membership.
    */
-  async function requestAction(event: RequestContext): Promise<{ sent: true }> {
+  async function requestAction(event: RequestContext): Promise<RequestResult> {
     const env = event.platform?.env ?? {};
     const origin = requireOrigin(env);
     const db = requireDb(env);
@@ -43,31 +65,39 @@ export function createAuthRoutes(config: AuthRoutesConfig) {
     log.info('auth.link.requested', { email: email.slice(0, 320) });
 
     const editor = email ? await findEditor(db, email) : null;
-    if (editor) {
-      const now = Date.now();
-      // Per-email cooldown: skip the reissue and send when a token for this email was issued within
-      // the window, so the endpoint cannot flood an editor's inbox. The response is unchanged, so
-      // the non-leak property holds.
-      if (!(await recentlyIssued(db, email, now - SEND_COOLDOWN_MS))) {
-        const token = generateToken();
-        await issueToken(db, email, await hashToken(token), now + TOKEN_TTL_MS, now);
-        log.info('auth.token.minted', { email, expiresAt: now + TOKEN_TTL_MS });
-        const link = `${origin}/admin/auth/confirm?token=${encodeURIComponent(token)}`;
-        // The token row is the security-critical write the email depends on, so it is awaited. The
-        // send is a post-response side effect, handed to waitUntil so a slow email provider does not
-        // hold the response. An absent waitUntil (local dev, tests) falls back to await. A send
-        // failure is logged so observability survives a backgrounded send.
-        const sending = send(env, buildMagicLinkMessage({ to: email, branding: config.branding, link })).catch(
-          (err) => log.error('auth.link.send_failed', { email, error: String(err) }),
-        );
-        // adapter-cloudflare exposes the ExecutionContext as platform.ctx; platform.context is a
-        // deprecated alias kept as a fallback so an adapter that drops it keeps backgrounding.
-        const ctx = event.platform?.ctx ?? event.platform?.context;
-        if (ctx?.waitUntil) ctx.waitUntil(sending);
-        else await sending;
-      }
+    // Non-editor: byte-identical to the editor send-ok path, so the response body never leaks
+    // membership. Response timing still differs (the editor path awaits the send), the side-channel
+    // the design accepts as strictly weaker than the explicit throttled signal below.
+    if (!editor) return { status: 'sent', sent: true };
+
+    const now = Date.now();
+    // Per-email cooldown: an editor who requested within the window gets the throttled signal rather
+    // than a second email. This reveals editor membership, the deliberate relaxed-non-leak posture.
+    if (await recentlyIssued(db, email, now - SEND_COOLDOWN_MS)) {
+      return { status: 'throttled', sent: false };
+    }
+
+    const token = generateToken();
+    await issueToken(db, email, await hashToken(token), now + TOKEN_TTL_MS, now);
+    log.info('auth.token.minted', { email, expiresAt: now + TOKEN_TTL_MS });
+    const link = `${origin}/admin/auth/confirm?token=${encodeURIComponent(token)}`;
+    // The token row is the security-critical write the email depends on, so it is awaited first.
+    // The send is now awaited too (no waitUntil backgrounding), so its outcome drives the response:
+    // confirm the link went out before telling an editor to check their inbox. The cost is one
+    // email-API round trip on the login POST, the right trade for a login flow.
+    try {
+      await send(env, buildMagicLinkMessage({ to: email, branding: config.branding, link }));
+    } catch (err) {
+      // Map the binding failure to its registered condition (carried as a CairnError with the
+      // original as cause), and log the greppable code plus the conditionId so the next onboarding
+      // gap reads straight to its fix. The editor sees only a generic message, never this detail.
+      const failure = emailSendFailure(err);
+      log.error('auth.link.send_failed', { email, error: scrubSendError(err), code: errorCode(err), conditionId: failure.conditionId });
+      // A plain 200 with a status field, not fail(): the result stays one uniform union for the
+      // page, and the failure is already observable through the error-level log record.
+      return { status: 'send_error', sent: false };
     }
-    return { sent: true };
+    return { status: 'sent', sent: true };
   }
 
   /** GET /admin/login. Public. Carries the site name, an optional `?error`, and the CSRF token. */

package/src/lib/sveltekit/condition-response.ts

@@ -0,0 +1,38 @@
+// The runtime renderer leg of the diagnostics model: map a condition to the Response the guard
+// serves. Re-homes the three rejection responses guard.ts built inline, keyed by condition id, so
+// the guard's reason, the registered condition, and the served page stay in step.
+import { brandedAdminPage } from './admin-response.js';
+import { httpsRequiredPage } from './https-required-page.js';
+import { csrfRequiredPage } from './csrf-required-page.js';
+import { condition } from '../diagnostics/index.js';
+
+/** The guard.rejected reasons, each mapped to its registered condition id. */
+export const REASON_CONDITION = {
+  https: 'edge.https-not-forced',
+  csrf: 'auth.csrf-token-invalid',
+  origin: 'auth.csrf-origin-mismatch',
+} as const;
+
+export type GuardReason = keyof typeof REASON_CONDITION;
+
+/** Render the Response the guard serves for a rejection, by its condition id. */
+export function renderConditionResponse(id: string, ctx: { url?: URL } = {}): Response {
+  // Assert the id is registered before rendering, keeping the renderer in 1:1 with the registry.
+  condition(id);
+  switch (id) {
+    case REASON_CONDITION.https: {
+      const httpsUrl = new URL(ctx.url!);
+      httpsUrl.protocol = 'https:';
+      return brandedAdminPage(400, httpsRequiredPage(httpsUrl.toString()));
+    }
+    case REASON_CONDITION.csrf:
+      return brandedAdminPage(403, csrfRequiredPage());
+    case REASON_CONDITION.origin:
+      return new Response('Cross-site POST form submissions are forbidden', {
+        status: 403,
+        headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+      });
+    default:
+      throw new Error(`no runtime renderer for condition: ${id}`);
+  }
+}

package/src/lib/sveltekit/guard.ts

@@ -4,9 +4,9 @@
 import { redirect, error } from '@sveltejs/kit';
 import { resolveSession } from '../auth/store.js';
 import { sessionCookieName } from '../auth/crypto.js';
-import { httpsRequiredPage } from './https-required-page.js';
 import { isUnsafeFormRequest, originMatches, validateCsrfToken } from './csrf.js';
-import { csrfRequiredPage } from './csrf-required-page.js';
+import { applySecurityHeaders } from './admin-response.js';
+import { renderConditionResponse } from './condition-response.js';
 import { log } from '../log/index.js';
 import type { Editor } from '../auth/types.js';
 import type { HandleInput, RequestContext } from './types.js';
@@ -36,46 +36,6 @@ function isLocalHost(hostname: string): boolean {
   );
 }
 
-/**
- * Attach the baseline security headers to an admin response. No full CSP; see the auth-hardening
- * design. frame-ancestors is the modern clickjacking control and the one CSP directive included.
- */
-function applySecurityHeaders(headers: Headers): void {
-  headers.set('X-Content-Type-Options', 'nosniff');
-  headers.set('X-Frame-Options', 'DENY');
-  headers.set('Content-Security-Policy', "frame-ancestors 'none'");
-  headers.set('Referrer-Policy', 'no-referrer');
-  headers.set('Strict-Transport-Security', 'max-age=63072000; includeSubDomains');
-  headers.set('Permissions-Policy', 'camera=(), microphone=(), geolocation=()');
-}
-
-/** A branded full-document admin page, hardened with the baseline headers and never cached. */
-function brandedAdminPage(status: number, body: string): Response {
-  const headers = new Headers({ 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' });
-  applySecurityHeaders(headers);
-  return new Response(body, { status, headers });
-}
-
-/** The hardened 400 help page for a deployed admin request that arrived over http. */
-function httpsRequiredResponse(url: URL): Response {
-  const httpsUrl = new URL(url);
-  httpsUrl.protocol = 'https:';
-  return brandedAdminPage(400, httpsRequiredPage(httpsUrl.toString()));
-}
-
-/** A plain 403 for a non-admin cross-origin form POST, matching the framework's wording. */
-function csrfForbidden(): Response {
-  return new Response('Cross-site POST form submissions are forbidden', {
-    status: 403,
-    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
-  });
-}
-
-/** The branded 403 for a failed admin double-submit token check. */
-function csrfRequiredResponse(): Response {
-  return brandedAdminPage(403, csrfRequiredPage());
-}
-
 /** The SvelteKit `Handle` that guards `/admin/**` and hardens admin responses. */
 export function createAuthGuard() {
   return async function handle({ event, resolve }: HandleInput): Promise<Response> {
@@ -86,7 +46,7 @@ export function createAuthGuard() {
     if (!isAdminPath(pathname)) {
       if (isUnsafeFormRequest(event.request) && !originMatches(event)) {
         log.warn('guard.rejected', { reason: 'origin', path: pathname });
-        return csrfForbidden();
+        return renderConditionResponse('auth.csrf-origin-mismatch');
       }
       return resolve(event);
     }
@@ -97,14 +57,14 @@ export function createAuthGuard() {
     // posts. Local http (wrangler dev) is exempt.
     if (event.url.protocol === 'http:' && !isLocalHost(event.url.hostname)) {
       log.warn('guard.rejected', { reason: 'https', path: pathname });
-      return httpsRequiredResponse(event.url);
+      return renderConditionResponse('edge.https-not-forced', { url: event.url });
     }
 
     // Rule 1 - admin: every unsafe form POST carries a valid double-submit token, else the branded
     // 403 before resolve() runs. This covers the public login/auth posts too.
     if (isUnsafeFormRequest(event.request) && !(await validateCsrfToken(event))) {
       log.warn('guard.rejected', { reason: 'csrf', path: pathname });
-      return csrfRequiredResponse();
+      return renderConditionResponse('auth.csrf-token-invalid');
     }
 
     if (!isPublicAdminPath(pathname)) {

package/src/lib/sveltekit/index.ts

@@ -1,7 +1,7 @@
 // SvelteKit server logic consumed by site route shims: the guard plus the auth, editor,
 // content, and health route factories and functions.
 export { createAuthGuard, requireSession, requireOwner } from './guard.js';
-export { createAuthRoutes, type AuthRoutesConfig } from './auth-routes.js';
+export { createAuthRoutes, type AuthRoutesConfig, type RequestResult } from './auth-routes.js';
 export { createEditorRoutes } from './editors-routes.js';
 export { createContentRoutes } from './content-routes.js';
 export type {