@reuters-graphics/gfx-better-auth 0.1.0

package/dist/server/handle.d.ts

@@ -0,0 +1,62 @@
+import { type Handle } from '@sveltejs/kit';
+import type { GfxAuth } from './auth.js';
+export declare const SIGN_IN_ROUTE = "/magic-link";
+export declare const SENT_ROUTE = "/magic-link/sent";
+export declare const CONFIRM_ROUTE = "/magic-link/confirm";
+export declare const SIGN_OUT_ROUTE = "/sign-out";
+export interface GfxAuthHandleOptions {
+    auth: GfxAuth;
+    /**
+     * Paths that do not require a session. Supports a trailing `*`, e.g.
+     * `['/embed/*', '/about']`. `/api/auth/*` and the sign-in pages are always
+     * public and need not be listed.
+     */
+    publicPaths?: string[];
+    /**
+     * Pass `building` from `$app/environment` if your app prerenders anything.
+     *
+     * During prerendering the handle would otherwise try a session lookup, and
+     * there is no database at build time. It is an option rather than an import
+     * because `building` is SvelteKit-specific and importing `$app/environment`
+     * here would make this whole entry unloadable outside Vite (ADR-0016) —
+     * whereas your `hooks.server.ts` is always inside SvelteKit, so it can
+     * supply it in one line.
+     *
+     * Defaults to `false`, which is correct for an app that prerenders nothing.
+     */
+    building?: boolean;
+    /**
+     * Opt out of a built-in page to supply your own route file. Usually
+     * unnecessary — defining a route at the path is enough, and the handle
+     * defers to it automatically.
+     */
+    routes?: {
+        signIn?: boolean;
+        sent?: boolean;
+        confirm?: boolean;
+        signOut?: boolean;
+    };
+}
+/**
+ * 🚨 **Open-redirect guard.** `next` and `callbackURL` arrive from a query
+ * string, so they are attacker-controlled: `?next=https://evil.example` would
+ * otherwise hand a freshly signed-in user straight to an attacker's page,
+ * which is a textbook post-authentication open redirect.
+ *
+ * Only same-site absolute paths are allowed. `//evil.example` is rejected
+ * because browsers read it as protocol-relative, and backslashes because some
+ * agents normalise them to slashes.
+ */
+export declare const safeRedirectTarget: (value: unknown) => string | null;
+/**
+ * One handle that mounts the whole auth surface.
+ *
+ * ```ts
+ * // src/hooks.server.ts
+ * export const handle = sequence(gfxAuth({ auth }), myHandle);
+ * ```
+ *
+ * ⚠️ **It must come before anything that reads `event.locals.user`**, and a
+ * wrong order fails confusingly rather than loudly.
+ */
+export declare const gfxAuth: (options: GfxAuthHandleOptions) => Handle;

package/dist/server/handle.js

@@ -0,0 +1,252 @@
+import { redirect } from '@sveltejs/kit';
+import { svelteKitHandler, isAuthPath } from 'better-auth/svelte-kit';
+// 🚨 `esm-env`, not `$app/environment`. Both give a compile-time constant that
+// tree-shakes dev-only code out of a production build, but `$app/*` only
+// resolves inside a Vite build — so importing it here made the whole `/server`
+// entry unloadable from plain Node, breaking better-auth's CLI, migration
+// scripts, `gfx-auth doctor`, and `signInAs` in a Playwright `globalSetup`
+// (ADR-0016). `svelte-package` warns about this on every build.
+import { DEV } from 'esm-env';
+import { consumeDevMagicLink } from './dev.js';
+import { confirmPage, html, sentPage, signInPage, signOutPage, } from './pages.js';
+export const SIGN_IN_ROUTE = '/magic-link';
+export const SENT_ROUTE = '/magic-link/sent';
+export const CONFIRM_ROUTE = '/magic-link/confirm';
+export const SIGN_OUT_ROUTE = '/sign-out';
+/**
+ * Matches a path against a `publicPaths` entry.
+ *
+ * The `+ '/'` boundary is deliberate: without it `/login` would also match
+ * `/loginfoo`, which is how a public-path list quietly becomes a hole.
+ */
+const matches = (pathname, pattern) => {
+    if (pattern.endsWith('/*')) {
+        const base = pattern.slice(0, -2);
+        return pathname === base || pathname.startsWith(base + '/');
+    }
+    return pathname === pattern || pathname === pattern + '/';
+};
+/**
+ * 🚨 **Open-redirect guard.** `next` and `callbackURL` arrive from a query
+ * string, so they are attacker-controlled: `?next=https://evil.example` would
+ * otherwise hand a freshly signed-in user straight to an attacker's page,
+ * which is a textbook post-authentication open redirect.
+ *
+ * Only same-site absolute paths are allowed. `//evil.example` is rejected
+ * because browsers read it as protocol-relative, and backslashes because some
+ * agents normalise them to slashes.
+ */
+export const safeRedirectTarget = (value) => {
+    if (typeof value !== 'string' || value === '')
+        return null;
+    if (!value.startsWith('/'))
+        return null;
+    if (value.startsWith('//') || value.startsWith('/\\'))
+        return null;
+    if (value.includes('\\'))
+        return null;
+    return value;
+};
+/**
+ * One handle that mounts the whole auth surface.
+ *
+ * ```ts
+ * // src/hooks.server.ts
+ * export const handle = sequence(gfxAuth({ auth }), myHandle);
+ * ```
+ *
+ * ⚠️ **It must come before anything that reads `event.locals.user`**, and a
+ * wrong order fails confusingly rather than loudly.
+ */
+export const gfxAuth = (options) => {
+    const { auth, publicPaths = [], routes = {}, building = false } = options;
+    const enabled = {
+        [SIGN_IN_ROUTE]: routes.signIn !== false,
+        [SENT_ROUTE]: routes.sent !== false,
+        [CONFIRM_ROUTE]: routes.confirm !== false,
+        [SIGN_OUT_ROUTE]: routes.signOut !== false,
+    };
+    const appName = auth.options.appName ?? 'this app';
+    return async ({ event, resolve }) => {
+        const { pathname } = event.url;
+        // 1. better-auth's own endpoints. Handled and returned before anything
+        //    else — they must not be guarded, and they do not need locals.
+        if (isAuthPath(event.request.url, auth.options)) {
+            return svelteKitHandler({ auth, event, resolve, building });
+        }
+        // Nothing below may touch the database while prerendering.
+        if (building)
+            return resolve(event);
+        // 2. Populate locals.
+        const result = await auth.api.getSession({
+            headers: event.request.headers,
+        });
+        const user = (result?.user ?? null);
+        // 🚨 The kill switch (ADR-0004). A disabled user is treated as signed
+        // out on **every request**, so revoking access does not wait for their
+        // session to expire. This is why `session.cookieCache` is off: a cached
+        // session is one this check never sees.
+        const disabled = !!user?.disabledAt;
+        // Cast because the package cannot see the consumer's merged `App.Locals`;
+        // `GfxAuthLocals` is what they are asked to extend it with.
+        const locals = event.locals;
+        locals.user = disabled ? null : user;
+        locals.session =
+            disabled ? null : (result?.session ?? null);
+        // 3. Our pages — but only where the app has not defined its own route.
+        //    `event.route.id` is null exactly when no route matched, which is the
+        //    whole deferral mechanism (ADR-0002).
+        //
+        //    ⚠️ This is a "whose page renders" decision, never an authorization
+        //    one — SvelteKit's own docs warn `route.id` is not for that, and the
+        //    guard below deliberately uses `pathname` instead.
+        if (event.route.id === null && enabled[pathname]) {
+            const served = await servePage(event, { auth, appName });
+            if (served)
+                return served;
+        }
+        // 4. Guard.
+        const isPublic = pathname === SIGN_IN_ROUTE ||
+            pathname === SENT_ROUTE ||
+            pathname === CONFIRM_ROUTE ||
+            // Signing out must not require being signed in: otherwise a stale or
+            // half-broken session bounces to the sign-in page with no way out.
+            pathname === SIGN_OUT_ROUTE ||
+            publicPaths.some((p) => matches(pathname, p));
+        if (!locals.user && !isPublic) {
+            const next = pathname + event.url.search;
+            redirect(302, `${SIGN_IN_ROUTE}?next=${encodeURIComponent(next)}`);
+        }
+        return resolve(event);
+    };
+};
+/**
+ * The page half. Returns `null` if this request is not one of ours, so the
+ * caller falls through to `resolve`.
+ */
+const servePage = async (event, ctx) => {
+    const { auth, appName } = ctx;
+    const { pathname } = event.url;
+    const method = event.request.method;
+    if (method !== 'GET' && method !== 'POST')
+        return null;
+    // ── /magic-link ─────────────────────────────────────────────────────────
+    if (pathname === SIGN_IN_ROUTE) {
+        const next = safeRedirectTarget(event.url.searchParams.get('next'));
+        if (method === 'GET')
+            return html(signInPage({ appName, next }));
+        const form = await event.request.formData();
+        const email = String(form.get('email') ?? '');
+        const formNext = safeRedirectTarget(form.get('next')) ?? next;
+        try {
+            await auth.api.signInMagicLink({
+                body: { email, callbackURL: formNext ?? '/' },
+                // Required, not optional: the endpoint declares `requireHeaders` so it
+                // can see the origin, IP and user agent.
+                headers: event.request.headers,
+            });
+        }
+        catch (error) {
+            // The gate refuses non-TR addresses here (ADR-0004). Show the message
+            // rather than a 403 page — the endpoint is the trust boundary, this is
+            // only how a human finds out.
+            const message = error?.body?.message ??
+                error?.message ??
+                'Something went wrong sending your link. Try again.';
+            return html(signInPage({ appName, next: formNext, error: message, email }), 400);
+        }
+        const sent = new URL(SENT_ROUTE, event.url.origin);
+        sent.searchParams.set('email', email);
+        if (formNext)
+            sent.searchParams.set('next', formNext);
+        return new Response(null, {
+            status: 303,
+            headers: { location: sent.pathname + sent.search },
+        });
+    }
+    // ── /magic-link/sent ────────────────────────────────────────────────────
+    if (pathname === SENT_ROUTE) {
+        if (method !== 'GET')
+            return null;
+        const email = event.url.searchParams.get('email');
+        if (!email)
+            redirect(302, SIGN_IN_ROUTE);
+        // `DEV` is a compile-time constant in any Vite build, so this whole
+        // branch — and the import it reaches — is tree-shaken out of production.
+        // The guarantee is the build, not the condition (ADR-0003), and it is
+        // verified against a real consumer build by `pnpm run verify:install`.
+        const devUrl = DEV ? consumeDevMagicLink(email) : null;
+        return html(sentPage({ appName, email, devUrl }));
+    }
+    // ── /sign-out ───────────────────────────────────────────────────────────
+    if (pathname === SIGN_OUT_ROUTE) {
+        // 🚨 GET only ever renders a form. Signing out on GET would let a
+        // link-prefetcher or a cross-site `<img src="/sign-out">` do it — the same
+        // shape of bug as the SafeLinks one this package exists for.
+        if (method === 'GET')
+            return html(signOutPage({ appName }));
+        // Delegate to better-auth rather than clearing the cookie ourselves, so
+        // the session row is deleted too and the cookie attributes match the ones
+        // that set it.
+        //
+        // ⚠️ A plain HTML form cannot call it directly: the endpoint accepts only
+        // `application/json` and answers a form post with 415. That is the whole
+        // reason this route exists — without it, a package whose sign-in needs no
+        // JavaScript would need JavaScript to sign out.
+        const headers = new Headers({ 'content-type': 'application/json' });
+        const cookie = event.request.headers.get('cookie');
+        if (cookie)
+            headers.set('cookie', cookie);
+        // Forwarded so better-auth can still do its own origin check on this.
+        const origin = event.request.headers.get('origin');
+        if (origin)
+            headers.set('origin', origin);
+        const result = await auth.handler(new Request(new URL('/api/auth/sign-out', event.url.origin), {
+            method: 'POST',
+            headers,
+            body: '{}',
+        }));
+        const out = new Headers({ location: SIGN_IN_ROUTE });
+        // `getSetCookie` keeps them separate; a plain `get` would join multiple
+        // cookies with a comma and produce one malformed header.
+        for (const c of result.headers.getSetCookie())
+            out.append('set-cookie', c);
+        return new Response(null, { status: 303, headers: out });
+    }
+    // ── /magic-link/confirm ─────────────────────────────────────────────────
+    if (pathname === CONFIRM_ROUTE) {
+        if (method === 'GET') {
+            const token = event.url.searchParams.get('token');
+            if (!token)
+                redirect(302, SIGN_IN_ROUTE);
+            // 🚨 The token is rendered, never used. A SafeLinks scanner reaches
+            // exactly this far and no further — which is the entire point of the
+            // page existing (ADR-0002).
+            return html(confirmPage({
+                appName,
+                token,
+                callbackURL: safeRedirectTarget(event.url.searchParams.get('callbackURL')),
+            }));
+        }
+        const form = await event.request.formData();
+        const token = String(form.get('token') ?? '');
+        if (!token)
+            return html(confirmPage({
+                appName,
+                token: '',
+                error: 'That sign-in link was incomplete. Request a new one.',
+            }), 400);
+        // Hand the browser to the verify endpoint. It is a redirect rather than a
+        // server-side `auth.api` call on purpose: the exchange then happens on a
+        // real request that better-auth is handling, so `Set-Cookie` lands
+        // without needing the `sveltekitCookies` plugin.
+        const verify = new URL('/api/auth/magic-link/verify', event.url.origin);
+        verify.searchParams.set('token', token);
+        verify.searchParams.set('callbackURL', safeRedirectTarget(form.get('callbackURL')) ?? '/');
+        return new Response(null, {
+            status: 303,
+            headers: { location: verify.pathname + verify.search },
+        });
+    }
+    return null;
+};

package/dist/server/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Server entry — everything that touches the database, Postmark or a session.
+ *
+ * 🚨 Never import this from a component. The entry-point split is a safety
+ * boundary, not tidiness: this is what stops something reaching for a secret
+ * ending up in a client bundle. `/client` is the browser-safe half.
+ */
+export { createGfxAuth, type GfxAuth } from './auth.js';
+export { gfxAuth, SIGN_IN_ROUTE, SENT_ROUTE, CONFIRM_ROUTE, SIGN_OUT_ROUTE, type GfxAuthHandleOptions, } from './handle.js';
+export { requireUser } from './guard.js';
+export { signInAs } from './testing.js';
+export type { GfxAuthConfig, GfxAuthOptions, SignInEmail } from './config.js';

package/dist/server/index.js

@@ -0,0 +1,11 @@
+/**
+ * Server entry — everything that touches the database, Postmark or a session.
+ *
+ * 🚨 Never import this from a component. The entry-point split is a safety
+ * boundary, not tidiness: this is what stops something reaching for a secret
+ * ending up in a client bundle. `/client` is the browser-safe half.
+ */
+export { createGfxAuth } from './auth.js';
+export { gfxAuth, SIGN_IN_ROUTE, SENT_ROUTE, CONFIRM_ROUTE, SIGN_OUT_ROUTE, } from './handle.js';
+export { requireUser } from './guard.js';
+export { signInAs } from './testing.js';

package/dist/server/pages.d.ts

@@ -0,0 +1,53 @@
+export interface SignInPageProps {
+    appName: string;
+    /** Path to return to after signing in. */
+    next?: string | null;
+    error?: string | null;
+    email?: string | null;
+}
+export declare const signInPage: ({ appName, next, error, email, }: SignInPageProps) => string;
+export interface SentPageProps {
+    appName: string;
+    email: string;
+    /**
+     * In development only: the stashed confirm URL, rendered as a link so the
+     * inbox can be skipped without skipping the flow (ADR-0007). Always `null`
+     * in production.
+     */
+    devUrl?: string | null;
+}
+export declare const sentPage: ({ appName, email, devUrl }: SentPageProps) => string;
+export interface ConfirmPageProps {
+    appName: string;
+    token: string;
+    callbackURL?: string | null;
+    error?: string | null;
+}
+/**
+ * 🚨 **The reason this package owns a route at all.**
+ *
+ * Outlook SafeLinks pre-fetches URLs in email, and a magic-link token is
+ * consumed atomically on first verification — better-auth 1.7 deprecated
+ * `allowedAttempts` and now ignores it, so a scanner's GET
+ * would burn the token and the real click would fail.
+ *
+ * So a scanner must only ever reach **a page**. The token rides through the
+ * HTML in a hidden input and is exchanged on submit, which a pre-fetcher does
+ * not do. Nothing in this page's rendering may touch or verify the token.
+ */
+export declare const confirmPage: ({ appName, token, callbackURL, error, }: ConfirmPageProps) => string;
+export interface SignOutPageProps {
+    appName: string;
+}
+/**
+ * ⚠️ **Sign-out is a POST, and this page exists so it can be.**
+ *
+ * It would be easier to sign out on `GET /sign-out`, and that would be wrong
+ * twice over: a link-prefetcher would sign people out just by scanning a page
+ * — the same class of bug as the SafeLinks one this package was built around —
+ * and any cross-site `<img src="/sign-out">` would too.
+ *
+ * So the state change needs a POST, and a POST with no JavaScript needs a form.
+ */
+export declare const signOutPage: ({ appName }: SignOutPageProps) => string;
+export declare const html: (body: string, status?: number) => Response;

package/dist/server/pages.js

@@ -0,0 +1,133 @@
+import { escapeHtml } from './escape.js';
+/**
+ * The three built-in pages, as HTML strings (ADR-0008).
+ *
+ * A `Handle` returns a `Response`, so it cannot render a SvelteKit page and
+ * there are no form actions — the hook handles the POSTs itself. That makes
+ * these plain strings rather than components, and makes escaping our job:
+ * **every interpolation goes through `escapeHtml`.**
+ *
+ * The forms are plain HTML POSTs with no JavaScript, so sign-in works in a
+ * text browser and with scripting disabled. For the one flow that must never
+ * break, that is a feature rather than a limitation.
+ *
+ * These are a **fallback**, not a design system. An app that cares defines its
+ * own route file and the handle defers to it.
+ */
+const STYLES = `
+  :root { color-scheme: light dark; --fg: #1a1a1a; --muted: #5c6370;
+    --bg: #f4f5f7; --card: #ffffff; --line: #dfe2e8; --accent: #1a1a1a; }
+  @media (prefers-color-scheme: dark) {
+    :root { --fg: #f0f1f3; --muted: #9aa2af; --bg: #16181d; --card: #1f2228;
+      --line: #32363f; --accent: #f0f1f3; }
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; min-height: 100vh; display: grid; place-items: center;
+    padding: 24px; background: var(--bg); color: var(--fg);
+    font: 16px/1.5 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif; }
+  main { width: 100%; max-width: 27rem; background: var(--card);
+    border: 1px solid var(--line); border-radius: 10px; padding: 32px; }
+  h1 { margin: 0 0 4px; font-size: 1.25rem; letter-spacing: -0.01em; }
+  p { margin: 0 0 20px; color: var(--muted); font-size: 0.9375rem; }
+  label { display: block; font-size: 0.8125rem; font-weight: 600; margin-bottom: 6px; }
+  input[type=email] { width: 100%; padding: 10px 12px; font-size: 1rem;
+    color: var(--fg); background: var(--bg); border: 1px solid var(--line);
+    border-radius: 6px; }
+  input[type=email]:focus-visible { outline: 2px solid var(--accent); outline-offset: 1px; }
+  button { width: 100%; margin-top: 16px; padding: 11px 16px; font: inherit;
+    font-weight: 600; color: var(--card); background: var(--accent);
+    border: 0; border-radius: 6px; cursor: pointer; }
+  button:hover { opacity: 0.85; }
+  .note { margin: 20px 0 0; padding-top: 16px; border-top: 1px solid var(--line);
+    font-size: 0.8125rem; }
+  .err { margin: 0 0 20px; padding: 10px 12px; border-radius: 6px;
+    background: #fdeaea; color: #8c1c1c; font-size: 0.875rem; }
+  @media (prefers-color-scheme: dark) { .err { background: #3a1d1d; color: #f3b5b5; } }
+  a { color: inherit; }
+`;
+const shell = (title, appName, body) => `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex, nofollow">
+<title>${escapeHtml(title)} · ${escapeHtml(appName)}</title>
+<style>${STYLES}</style>
+</head>
+<body>
+<main>
+${body}
+</main>
+</body>
+</html>`;
+export const signInPage = ({ appName, next, error, email, }) => shell('Sign in', appName, `<h1>Sign in to ${escapeHtml(appName)}</h1>
+<p>We'll email you a link. No password needed.</p>
+${error ? `<p class="err">${escapeHtml(error)}</p>` : ''}
+<form method="post">
+${next ? `<input type="hidden" name="next" value="${escapeHtml(next)}">` : ''}
+<label for="email">Thomson Reuters email</label>
+<input id="email" name="email" type="email" inputmode="email"
+  autocomplete="email" autocapitalize="off" spellcheck="false" required
+  placeholder="you@thomsonreuters.com"${email ? ` value="${escapeHtml(email)}"` : ''}>
+<button type="submit">Email me a link</button>
+</form>
+<p class="note">Only Thomson Reuters staff can sign in.</p>`);
+export const sentPage = ({ appName, email, devUrl }) => shell('Check your email', appName, `<h1>Check your email</h1>
+<p>We sent a sign-in link to <strong>${escapeHtml(email)}</strong>. Open it in
+this browser to continue.</p>
+${devUrl ?
+    `<p class="err" style="background:#e8f0fe;color:#1a3d7c">
+<strong>Development.</strong> No email was sent.</p>
+<a href="${escapeHtml(devUrl)}"><button type="button">Open the sign-in link</button></a>
+<p class="note">This is a real, single-use token and it goes through the same
+confirm page a link from your inbox would.</p>`
+    : `<p class="note">The link expires shortly. If it doesn't arrive, check your
+spam folder, then <a href=".">request another</a>.</p>`}`);
+/**
+ * 🚨 **The reason this package owns a route at all.**
+ *
+ * Outlook SafeLinks pre-fetches URLs in email, and a magic-link token is
+ * consumed atomically on first verification — better-auth 1.7 deprecated
+ * `allowedAttempts` and now ignores it, so a scanner's GET
+ * would burn the token and the real click would fail.
+ *
+ * So a scanner must only ever reach **a page**. The token rides through the
+ * HTML in a hidden input and is exchanged on submit, which a pre-fetcher does
+ * not do. Nothing in this page's rendering may touch or verify the token.
+ */
+export const confirmPage = ({ appName, token, callbackURL, error, }) => shell('Confirm sign-in', appName, `<h1>Confirm sign-in</h1>
+<p>One more click and you're in to ${escapeHtml(appName)}.</p>
+${error ? `<p class="err">${escapeHtml(error)}</p>` : ''}
+<form method="post">
+<input type="hidden" name="token" value="${escapeHtml(token)}">
+${callbackURL ? `<input type="hidden" name="callbackURL" value="${escapeHtml(callbackURL)}">` : ''}
+<button type="submit">Sign in</button>
+</form>
+<p class="note">This extra step exists because corporate email scanners open
+links before you do, which would otherwise use up your one-time code.</p>`);
+/**
+ * ⚠️ **Sign-out is a POST, and this page exists so it can be.**
+ *
+ * It would be easier to sign out on `GET /sign-out`, and that would be wrong
+ * twice over: a link-prefetcher would sign people out just by scanning a page
+ * — the same class of bug as the SafeLinks one this package was built around —
+ * and any cross-site `<img src="/sign-out">` would too.
+ *
+ * So the state change needs a POST, and a POST with no JavaScript needs a form.
+ */
+export const signOutPage = ({ appName }) => shell('Sign out', appName, `<h1>Sign out of ${escapeHtml(appName)}?</h1>
+<p>You'll need a new sign-in link to get back in.</p>
+<form method="post">
+<button type="submit">Sign out</button>
+</form>`);
+export const html = (body, status = 200) => new Response(body, {
+    status,
+    headers: {
+        'content-type': 'text/html; charset=utf-8',
+        // These pages carry a token in the markup. They must not be stored by a
+        // shared cache, and they have no business in a search index.
+        'cache-control': 'no-store, must-revalidate',
+        'referrer-policy': 'no-referrer',
+        'x-robots-tag': 'noindex, nofollow',
+    },
+});

package/dist/server/testing.d.ts

@@ -0,0 +1,31 @@
+import type { GfxAuth } from './auth.js';
+/**
+ * Sign in as `email` and return the session cookie, for Playwright
+ * `globalSetup` and integration tests. No inbox, no browser.
+ *
+ * ```ts
+ * const { cookie } = await signInAs(auth, 'jane.doe@thomsonreuters.com');
+ * await context.addCookies([parse(cookie)]);
+ * ```
+ *
+ * 🚨 **Never expose this over HTTP.** It is guarded by `DEV` from `esm-env` —
+ * a compile-time constant in any Vite build, so the body is tree-shaken out of
+ * production — with a runtime assertion behind that.
+ *
+ * `esm-env` rather than `$app/environment` because **this has to work in plain
+ * Node**: a Playwright `globalSetup` runs outside Vite, and with the old import
+ * it could not even be loaded there — which is the one place it is documented
+ * for (ADR-0016).
+ *
+ * ⚠️ It drives the **real** flow rather than minting a session directly:
+ * request a link, read it from the development stash, exchange the token. So
+ * it exercises the same code path production runs and needs no better-auth
+ * internals, which also means it depends on `dev.skipInbox` being on. If you
+ * set `EMAIL_MAGIC_LINKS=1` or `dev.skipInbox: false`, this throws rather than
+ * silently signing nobody in.
+ *
+ * The domain gate still applies, so `email` must be a Thomson Reuters address.
+ */
+export declare const signInAs: (auth: GfxAuth, email: string) => Promise<{
+    cookie: string;
+}>;

package/dist/server/testing.js

@@ -0,0 +1,53 @@
+import { DEV } from 'esm-env';
+import { consumeDevMagicLink } from './dev.js';
+/**
+ * Sign in as `email` and return the session cookie, for Playwright
+ * `globalSetup` and integration tests. No inbox, no browser.
+ *
+ * ```ts
+ * const { cookie } = await signInAs(auth, 'jane.doe@thomsonreuters.com');
+ * await context.addCookies([parse(cookie)]);
+ * ```
+ *
+ * 🚨 **Never expose this over HTTP.** It is guarded by `DEV` from `esm-env` —
+ * a compile-time constant in any Vite build, so the body is tree-shaken out of
+ * production — with a runtime assertion behind that.
+ *
+ * `esm-env` rather than `$app/environment` because **this has to work in plain
+ * Node**: a Playwright `globalSetup` runs outside Vite, and with the old import
+ * it could not even be loaded there — which is the one place it is documented
+ * for (ADR-0016).
+ *
+ * ⚠️ It drives the **real** flow rather than minting a session directly:
+ * request a link, read it from the development stash, exchange the token. So
+ * it exercises the same code path production runs and needs no better-auth
+ * internals, which also means it depends on `dev.skipInbox` being on. If you
+ * set `EMAIL_MAGIC_LINKS=1` or `dev.skipInbox: false`, this throws rather than
+ * silently signing nobody in.
+ *
+ * The domain gate still applies, so `email` must be a Thomson Reuters address.
+ */
+export const signInAs = async (auth, email) => {
+    if (!DEV)
+        throw new Error('signInAs() is development-only and must never be reachable in production.');
+    const origin = auth.options.baseURL ?? 'http://localhost';
+    await auth.api.signInMagicLink({
+        body: { email, callbackURL: '/' },
+        headers: new Headers({ origin, 'content-type': 'application/json' }),
+    });
+    const stashed = consumeDevMagicLink(email);
+    if (!stashed)
+        throw new Error(`signInAs(): no development link was stashed for ${email}. ` +
+            'This needs `dev.skipInbox` on and `EMAIL_MAGIC_LINKS` unset.');
+    const token = new URL(stashed).searchParams.get('token');
+    if (!token)
+        throw new Error('signInAs(): the stashed link carried no token.');
+    const verify = new URL('/api/auth/magic-link/verify', origin);
+    verify.searchParams.set('token', token);
+    verify.searchParams.set('callbackURL', '/');
+    const response = await auth.handler(new Request(verify, { headers: { origin }, redirect: 'manual' }));
+    const cookie = response.headers.get('set-cookie');
+    if (!cookie)
+        throw new Error(`signInAs(): verifying the token set no cookie (status ${response.status}).`);
+    return { cookie };
+};

package/dist/types.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Merge into your app's `App.Locals` so `event.locals.user` is typed:
+ *
+ * ```ts
+ * // src/app.d.ts
+ * import type { GfxAuthLocals } from '@reuters-graphics/gfx-better-auth';
+ * declare global {
+ *   namespace App {
+ *     interface Locals extends GfxAuthLocals {}
+ *   }
+ * }
+ * export {};
+ * ```
+ */
+export interface GfxAuthUser {
+    id: string;
+    email: string;
+    name: string;
+    emailVerified: boolean;
+    disabledAt: Date | null;
+}
+export interface GfxAuthSession {
+    id: string;
+    userId: string;
+    expiresAt: Date;
+}
+export interface GfxAuthLocals {
+    user: GfxAuthUser | null;
+    session: GfxAuthSession | null;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};