@reuters-graphics/gfx-better-auth 0.1.0

package/dist/schema/index.js

@@ -0,0 +1,108 @@
+import { boolean, pgTable, text, timestamp } from 'drizzle-orm/pg-core';
+/**
+ * The four tables better-auth needs, as **column objects you spread** plus
+ * pre-assembled tables for apps that don't extend them.
+ *
+ * The package ships table *definitions*; each app owns its own migration
+ * history (ADR-0005). Re-export from your schema barrel and point
+ * `drizzle.config.ts` at that — drizzle-kit follows imports into
+ * `node_modules` happily:
+ *
+ * ```ts
+ * // src/lib/server/db/schema/index.ts
+ * export * from '@reuters-graphics/gfx-better-auth/schema';
+ * export * from './your-tables';
+ * ```
+ *
+ * To add columns, spread instead of re-exporting, and tell better-auth about
+ * them via `additionalUserFields` (ADR-0006 — roles are the app's, not ours):
+ *
+ * ```ts
+ * export const user = pgTable('user', { ...userColumns, role: text('role') });
+ * ```
+ */
+/**
+ * ⚠️ **Every timestamp is `timestamptz`, and `decision-desk`'s are not.**
+ *
+ * A bare `timestamp` column stores no offset, so the value is not an instant:
+ * the driver writes UTC and reads it back as local, and on a machine in BST
+ * every row comes back an hour early. It round-trips consistently inside one
+ * process — which is why decision-desk works — but `session.expires_at` is a
+ * security-relevant value and "consistent, given identical timezones" is not a
+ * property worth depending on (ADR-0012).
+ *
+ * Migrating from a decision-desk-shaped schema therefore needs an
+ * `ALTER TABLE … ALTER COLUMN … TYPE timestamptz`.
+ */
+export const userColumns = {
+    id: text('id').primaryKey(),
+    name: text('name').notNull(),
+    email: text('email').notNull().unique(),
+    emailVerified: boolean('email_verified').notNull(),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull(),
+    /**
+     * ⚠️ **Required by better-auth, and always `null` for us.** It is part of
+     * better-auth's core user model for social providers, which this package
+     * does not have — we are magic-link only, and nothing ever writes it.
+     *
+     * It is not optional. Omitting it makes better-auth ≥ 1.7 refuse the schema
+     * outright (`SchemaMismatchError`, `Missing columns: user.image`) on the
+     * first request — not at construction, so it surfaces as a failed login
+     * rather than a failed boot. `schema.test.ts` asserts the whole contract
+     * against `getAuthTables()` so the next such column is caught by a test
+     * instead of by a consumer.
+     */
+    image: text('image'),
+    /**
+     * The kill switch (ADR-0004). Checked on every request, so a departed
+     * colleague is out immediately rather than when their session lapses.
+     * Set automatically when Postmark reports the address inactive.
+     */
+    disabledAt: timestamp('disabled_at', { withTimezone: true }),
+};
+export const user = pgTable('user', userColumns);
+export const sessionColumns = {
+    id: text('id').primaryKey(),
+    expiresAt: timestamp('expires_at', { withTimezone: true }).notNull(),
+    token: text('token').notNull().unique(),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull(),
+    ipAddress: text('ip_address'),
+    userAgent: text('user_agent'),
+    userId: text('user_id')
+        .notNull()
+        .references(() => user.id, { onDelete: 'cascade' }),
+};
+export const session = pgTable('session', sessionColumns);
+export const accountColumns = {
+    id: text('id').primaryKey(),
+    accountId: text('account_id').notNull(),
+    providerId: text('provider_id').notNull(),
+    userId: text('user_id')
+        .notNull()
+        .references(() => user.id, { onDelete: 'cascade' }),
+    accessToken: text('access_token'),
+    refreshToken: text('refresh_token'),
+    idToken: text('id_token'),
+    accessTokenExpiresAt: timestamp('access_token_expires_at', {
+        withTimezone: true,
+    }),
+    refreshTokenExpiresAt: timestamp('refresh_token_expires_at', {
+        withTimezone: true,
+    }),
+    scope: text('scope'),
+    password: text('password'),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull(),
+};
+export const account = pgTable('account', accountColumns);
+export const verificationColumns = {
+    id: text('id').primaryKey(),
+    identifier: text('identifier').notNull(),
+    value: text('value').notNull(),
+    expiresAt: timestamp('expires_at', { withTimezone: true }).notNull(),
+    createdAt: timestamp('created_at', { withTimezone: true }),
+    updatedAt: timestamp('updated_at', { withTimezone: true }),
+};
+export const verification = pgTable('verification', verificationColumns);

package/dist/server/auth.d.ts

@@ -0,0 +1,67 @@
+import type { BetterAuthOptions } from 'better-auth/types';
+import { type GfxAuthOptions } from './config.js';
+/**
+ * Build the configured better-auth instance.
+ *
+ * Everything opinionated lives here so a consumer does not have to know it:
+ * the domain gate, the SafeLinks indirection, the kill switch, session TTL and
+ * the development inbox.
+ *
+ * @example
+ * ```ts
+ * export const auth = createGfxAuth({
+ *   db,
+ *   appName: 'lightbox',
+ *   baseURL: env.PUBLIC_APP_URL,
+ *   secret: env.BETTER_AUTH_SECRET,
+ *   postmark: { token: env.POSTMARK_API_KEY, from: '…', messageStream: '…' },
+ * });
+ * ```
+ */
+export declare const createGfxAuth: (options: GfxAuthOptions) => GfxAuth;
+/**
+ * The auth instance, as a **hand-written type rather than an inferred one**.
+ *
+ * 🚨 This annotation is load-bearing, and removing it breaks the published
+ * package in a way `publint` cannot see. better-auth's inferred return type
+ * transitively names `@better-auth/core/db/internal`, which under pnpm lives
+ * at a hashed, non-portable path — so `svelte-package` **silently fails to
+ * emit `dist/server/auth.d.ts`**, warns, and exits 0. A consumer then gets
+ * `TS7016: Could not find a declaration file for module './auth.js'` on
+ * install: exactly the "installs and then cannot be imported" failure this
+ * repo is most afraid of.
+ *
+ * `pnpm build` now fails if any `dist` module lacks its declaration, so this
+ * cannot regress silently — see `scripts/check-declarations.mjs`.
+ *
+ * ⚠️ The cost is that this is narrower than better-auth's own instance type:
+ * it is the surface this package uses and promises, not all of `auth.api`. If
+ * you need the rest, derive it in your own app where inference is free:
+ *
+ * ```ts
+ * const auth = createGfxAuth({ … });
+ * // your own precise handle on it, if you need one:
+ * type MyAuth = typeof auth;
+ * ```
+ */
+export interface GfxAuth {
+    /** better-auth's request handler, mounted by {@link gfxAuth}. */
+    handler: (request: Request) => Promise<Response>;
+    /** The resolved better-auth options, read by `isAuthPath` and `svelteKitHandler`. */
+    options: BetterAuthOptions;
+    api: {
+        getSession: (input: {
+            headers: Headers;
+        }) => Promise<{
+            user?: unknown;
+            session?: unknown;
+        } | null>;
+        signInMagicLink: (input: {
+            body: {
+                email: string;
+                callbackURL?: string;
+            };
+            headers: Headers;
+        }) => Promise<unknown>;
+    };
+}

package/dist/server/auth.js

@@ -0,0 +1,152 @@
+import { DEV } from 'esm-env';
+import { betterAuth } from 'better-auth';
+import { drizzleAdapter } from 'better-auth/adapters/drizzle';
+import { magicLink } from 'better-auth/plugins';
+import { APIError, createAuthMiddleware } from 'better-auth/api';
+import { isAllowedEmail, normaliseEmail } from '../domains.js';
+import { gfxAuthConfig, } from './config.js';
+import { stashDevMagicLink } from './dev.js';
+import { sendSignInEmail } from '../emails/index.js';
+/**
+ * Indirected through one function so the email module's exact signature is a
+ * detail of `src/emails/`, and so `sendEmail` can be injected in tests.
+ */
+const defaultSender = (message) => sendSignInEmail(message);
+/** The endpoint the domain gate guards. Mount-relative — no `/api/auth`. */
+const SIGN_IN_PATH = '/sign-in/magic-link';
+/**
+ * Build the configured better-auth instance.
+ *
+ * Everything opinionated lives here so a consumer does not have to know it:
+ * the domain gate, the SafeLinks indirection, the kill switch, session TTL and
+ * the development inbox.
+ *
+ * @example
+ * ```ts
+ * export const auth = createGfxAuth({
+ *   db,
+ *   appName: 'lightbox',
+ *   baseURL: env.PUBLIC_APP_URL,
+ *   secret: env.BETTER_AUTH_SECRET,
+ *   postmark: { token: env.POSTMARK_API_KEY, from: '…', messageStream: '…' },
+ * });
+ * ```
+ */
+export const createGfxAuth = (options) => {
+    const { db, additionalUserFields, sendEmail, ...rest } = options;
+    const config = gfxAuthConfig.parse(rest);
+    const send = sendEmail ?? defaultSender;
+    // ✅ **The same guard as everywhere else, and it tree-shakes.** This used to
+    // be a `process.env.NODE_ENV` check, on the reasoning that `$app/environment`
+    // could not be imported here because better-auth's CLI loads a consumer's
+    // auth instance from plain Node. That reasoning was sound and the workaround
+    // was pointless: the `/server` barrel re-exported modules that imported
+    // `$app/*` anyway, so the CLI was broken regardless (ADR-0016).
+    //
+    // `esm-env` resolves to a literal in any Vite build and to a runtime check in
+    // Node, so it is both tree-shakeable and loadable everywhere — which is what
+    // conventions § 3 was always trying to get.
+    const skipInbox = DEV && config.dev.skipInbox && !process.env.EMAIL_MAGIC_LINKS;
+    if (!skipInbox && !config.postmark.token) {
+        throw new Error('gfx-better-auth: no Postmark token, and the development inbox is not in use, ' +
+            'so no sign-in email could ever be sent. Set `postmark.token` ' +
+            '(POSTMARK_API_KEY), or run in development for the dev flow. ' +
+            'Failing at boot rather than at somebody’s first login attempt.');
+    }
+    const auth = betterAuth({
+        appName: config.appName,
+        baseURL: config.baseURL,
+        secret: config.secret,
+        database: drizzleAdapter(db, { provider: 'pg' }),
+        // better-auth rate-limits /sign-in/magic-link at 5 per 60s per IP, on by
+        // default in production. Exposed so a test can turn it on, and a consumer
+        // can turn it off — not otherwise reconfigured.
+        ...(config.rateLimit ? { rateLimit: config.rateLimit } : {}),
+        session: {
+            expiresIn: config.session.expiresIn,
+            updateAge: config.session.updateAge,
+            // 🚨 Off deliberately. A cached session is a session the `disabledAt`
+            // check cannot see — the kill switch has to be able to take effect on
+            // the next request, not at the end of a cache window (ADR-0004).
+            cookieCache: { enabled: false },
+        },
+        user: {
+            additionalFields: {
+                ...additionalUserFields,
+                /**
+                 * Declared so better-auth selects it, which is what lets the handle
+                 * see it on `locals.user` and treat a disabled user as signed out.
+                 * `input: false` keeps it off any client-writable surface — it would
+                 * otherwise be a self-service un-disable.
+                 */
+                disabledAt: { type: 'date', required: false, input: false },
+            },
+        },
+        plugins: [
+            magicLink({
+                expiresIn: config.magicLink.expiresIn,
+                // A leaked database backup should not contain usable login tokens.
+                // Costs nothing: the plaintext token is still handed to us below.
+                storeToken: 'hashed',
+                sendMagicLink: async ({ email, url, token }) => {
+                    // 🚨 THE SAFELINKS INDIRECTION. better-auth's `url` points at the
+                    // verify endpoint, which consumes the token on GET. Outlook
+                    // pre-fetches links in email, so that URL must never reach an inbox
+                    // — we point at a page instead, and the token is exchanged on
+                    // submit (ADR-0002).
+                    //
+                    // better-auth 1.7 deprecated and neutered `allowedAttempts`: a token is consumed
+                    // atomically on first verification, so this is the only available
+                    // mitigation, not merely the tidiest.
+                    const confirm = new URL('/magic-link/confirm', config.baseURL);
+                    confirm.searchParams.set('token', token);
+                    const callbackURL = new URL(url).searchParams.get('callbackURL');
+                    if (callbackURL)
+                        confirm.searchParams.set('callbackURL', callbackURL);
+                    if (skipInbox) {
+                        stashDevMagicLink(email, confirm.toString());
+                        return;
+                    }
+                    await send({
+                        to: email,
+                        url: confirm.toString(),
+                        appName: config.appName,
+                        expiresIn: config.magicLink.expiresIn,
+                        postmark: config.postmark,
+                    });
+                },
+            }),
+        ],
+        hooks: {
+            /**
+             * 🚨 **The entire access-control model, and it is here on purpose.**
+             *
+             * A check in the sign-in form is bypassed by posting to the endpoint
+             * directly, so the form is not a trust boundary. This is, and it is not
+             * configurable (ADR-0004).
+             */
+            before: createAuthMiddleware(async (ctx) => {
+                if (ctx.path !== SIGN_IN_PATH)
+                    return;
+                const body = (ctx.body ?? {});
+                const raw = typeof body.email === 'string' ? body.email : '';
+                const email = normaliseEmail(raw);
+                if (config.dev.enforceDomainGate && !isAllowedEmail(email)) {
+                    throw new APIError('FORBIDDEN', {
+                        message: 'Only Thomson Reuters email addresses can sign in to this app.',
+                    });
+                }
+                // Rewrite the body to the normalised address so one person is one
+                // user. Without this, `Jane.Doe+x@…` and `jane.doe@…` become two rows
+                // with two sets of saved work — and the gate is the only place that
+                // sees every sign-in, including direct POSTs.
+                return { context: { ...ctx, body: { ...body, email } } };
+            }),
+        },
+    });
+    // Narrowed deliberately, and the cast is the point rather than a shortcut:
+    // better-auth's inferred instance type cannot be named portably, so exposing
+    // it is what stops `dist/server/auth.d.ts` being generated at all. See
+    // {@link GfxAuth}.
+    return auth;
+};

package/dist/server/config.d.ts

@@ -0,0 +1,81 @@
+import { z } from 'zod';
+/**
+ * Validated at construction so a missing secret fails at boot with a clear
+ * message, rather than at somebody's first login attempt.
+ */
+export declare const gfxAuthConfig: z.ZodObject<{
+    appName: z.ZodString;
+    baseURL: z.ZodString;
+    secret: z.ZodString;
+    postmark: z.ZodObject<{
+        token: z.ZodOptional<z.ZodString>;
+        from: z.ZodString;
+        messageStream: z.ZodString;
+    }, z.core.$strip>;
+    session: z.ZodPrefault<z.ZodObject<{
+        expiresIn: z.ZodDefault<z.ZodNumber>;
+        updateAge: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    magicLink: z.ZodPrefault<z.ZodObject<{
+        expiresIn: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    rateLimit: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    dev: z.ZodPrefault<z.ZodObject<{
+        skipInbox: z.ZodDefault<z.ZodBoolean>;
+        enforceDomainGate: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Validated config. `db` and `additionalUserFields` are passed alongside it
+ * rather than through Zod — the first is a Drizzle instance and the second is
+ * better-auth's own field descriptor shape, neither of which is worth
+ * re-describing here.
+ */
+export type GfxAuthConfig = z.input<typeof gfxAuthConfig>;
+/** What the package hands a sender. The transport is the sender's business. */
+export interface SignInEmail {
+    to: string;
+    /** The **confirm** page URL, already carrying the token. Never the verify endpoint. */
+    url: string;
+    appName: string;
+    /** Link lifetime in seconds, so the copy can say so without hardcoding it. */
+    expiresIn: number;
+    postmark: {
+        token?: string | undefined;
+        from: string;
+        messageStream: string;
+    };
+}
+export interface GfxAuthOptions extends GfxAuthConfig {
+    /**
+     * Your Drizzle instance. The `user` row lives in **your** database, so your
+     * data can foreign-key to it with a real cascade (ADR-0001).
+     */
+    db: any;
+    /**
+     * Override how the sign-in email is sent. Defaults to the package's
+     * Postmark sender.
+     *
+     * Exists mainly as a test seam — **no test may send real email or contact a
+     * real Postmark account**, and injecting a fake here is cleaner than
+     * mocking a module. A consumer with its own transport can also use it.
+     */
+    sendEmail?: (message: SignInEmail) => Promise<void>;
+    /**
+     * Extra columns you added to `user`, declared so better-auth selects them
+     * (ADR-0006 — roles are yours, not ours):
+     *
+     * ```ts
+     * export const user = pgTable('user', { ...userColumns, role: text('role') });
+     *
+     * createGfxAuth({ …, additionalUserFields: {
+     *   role: { type: 'string', required: false, input: false },
+     * } });
+     * ```
+     *
+     * ⚠️ `disabledAt` is declared for you and must not be redeclared here.
+     */
+    additionalUserFields?: Record<string, unknown>;
+}

package/dist/server/config.js

@@ -0,0 +1,105 @@
+import { z } from 'zod';
+/**
+ * Validated at construction so a missing secret fails at boot with a clear
+ * message, rather than at somebody's first login attempt.
+ */
+export const gfxAuthConfig = z.object({
+    /** Shown in the sign-in email and page, e.g. "lightbox". */
+    appName: z.string().min(1),
+    baseURL: z.string().url(),
+    secret: z
+        .string()
+        .min(32, 'BETTER_AUTH_SECRET must be at least 32 characters'),
+    postmark: z.object({
+        token: z.string().optional(),
+        from: z.string().email(),
+        messageStream: z.string().min(1),
+    }),
+    /**
+     * Session lifetime in seconds.
+     *
+     * ⚠️ **`expiresIn` is an _idle_ timeout, not an absolute cap.** better-auth
+     * refreshes a session on activity and sets `expiresAt = now + expiresIn`,
+     * so it is measured from last use, not from sign-in. An earlier version of
+     * this comment said otherwise and was wrong (ADR-0011).
+     *
+     * `updateAge` is not a safety control — it is how stale a session may get
+     * before better-auth bothers to rewrite the row.
+     *
+     * 🚨 **See `USAGE.md` for what this means for access control**, and for why
+     * `user.disabledAt` matters. Defaults follow decision-desk: 12h / 1h.
+     */
+    session: z
+        .object({
+        expiresIn: z
+            .number()
+            .int()
+            .positive()
+            .default(60 * 60 * 12),
+        updateAge: z
+            .number()
+            .int()
+            .positive()
+            .default(60 * 60),
+    })
+        // `prefault`, not `default`: Zod 4's `.default()` takes the OUTPUT type, so
+        // `{}` is rejected even though every field has its own default. `prefault`
+        // supplies the INPUT, letting the inner defaults fill it in.
+        .prefault({}),
+    magicLink: z
+        .object({
+        /**
+         * How long a link is valid, in seconds. Default 10 minutes.
+         *
+         * better-auth's own default is 5, which is tight for corporate mail —
+         * a message can sit in a scanner queue for a minute or two before it is
+         * even delivered. `rngs.io` has run 10 minutes in production for years.
+         *
+         * ⚠️ A token is single-use and consumed atomically on first
+         * verification, so a longer window widens the period in which an
+         * *unused* link in an inbox is live. It does not allow replay.
+         */
+        expiresIn: z
+            .number()
+            .int()
+            .positive()
+            .default(60 * 10),
+    })
+        .prefault({}),
+    /**
+     * Passed through to better-auth, which rate-limits `/sign-in/magic-link` and
+     * `/magic-link/verify` at **5 requests per 60s per IP** and enables that
+     * automatically in production. Without it, requesting a link is a way to
+     * mail-bomb a colleague.
+     *
+     * ⚠️ **The counters live in memory by default**, so on serverless each
+     * instance counts separately and the real limit is 5 × however many lambdas
+     * are warm. Better than nothing, and not a hard bound. Pass
+     * `{ enabled: true }` to force it on outside production.
+     */
+    rateLimit: z.object({ enabled: z.boolean().optional() }).optional(),
+    dev: z
+        .object({
+        /**
+         * Skip Postmark, stash the confirm URL, and render it as a link on
+         * `/magic-link/sent` — with a **real, single-use token**. The flow
+         * production runs, minus the inbox (ADR-0003, ADR-0007).
+         *
+         * ⚠️ **Do not "simplify" this into a redirect to the verify endpoint.**
+         * That skips `/magic-link/confirm`, which is the only reason this
+         * package owns a route at all, so the SafeLinks workaround would never
+         * run locally. ADR-0003 originally said to do exactly that, copying
+         * rngs.io; ADR-0007 is the correction.
+         *
+         * Set `EMAIL_MAGIC_LINKS=1` to opt back into real email.
+         */
+        skipInbox: z.boolean().default(true),
+        /**
+         * Keep the domain gate on in development. Defaults to `true`, unlike
+         * rngs.io — a gate that only runs in production is a gate nobody has
+         * tested (ADR-0004).
+         */
+        enforceDomainGate: z.boolean().default(true),
+    })
+        .prefault({}),
+});

package/dist/server/dev.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Keyed on the **normalised** address. Getting this wrong is a confusing bug
+ * rather than a loud one: typing `Jane.Doe+x@…` would stash under one key and
+ * the sent page would look under another, showing an empty page instead of an
+ * error.
+ */
+export declare const stashDevMagicLink: (email: string, url: string) => void;
+/**
+ * One-time-use, and expiring. Reading it removes it, so a link left in a
+ * long-open tab cannot be reused — the stash should be no weaker than the
+ * token it holds.
+ */
+export declare const consumeDevMagicLink: (email: string) => string | null;
+/** Test seam. Never called by the package itself. */
+export declare const clearDevMagicLinks: () => void;

package/dist/server/dev.js

@@ -0,0 +1,48 @@
+import { normaliseEmail } from '../domains.js';
+/**
+ * The development inbox: a link stashed in memory instead of emailed.
+ *
+ * `sendMagicLink` puts the **confirm** URL here and `/magic-link/sent` renders
+ * it as a link, so a local sign-in goes through `/magic-link/confirm` exactly
+ * as a click from a real inbox would (ADR-0007).
+ *
+ * 🚨 **Not a bypass.** The token is real, single-use and verified by the code
+ * path production runs. Only Postmark is skipped.
+ *
+ * ⚠️ **Do not replace this with a redirect to the verify endpoint.** That is
+ * what ADR-0003 originally said, copying `rngs.io`, and it skips the confirm
+ * page — so the SafeLinks workaround would never run locally, which is the one
+ * thing this whole design exists for.
+ *
+ * Process-local and deliberately so: it does not survive a restart and does
+ * not work across instances, which is correct for something that must never be
+ * reachable in production.
+ */
+const TTL_MS = 10 * 60 * 1000;
+const stash = new Map();
+/**
+ * Keyed on the **normalised** address. Getting this wrong is a confusing bug
+ * rather than a loud one: typing `Jane.Doe+x@…` would stash under one key and
+ * the sent page would look under another, showing an empty page instead of an
+ * error.
+ */
+export const stashDevMagicLink = (email, url) => {
+    stash.set(normaliseEmail(email), { url, expiresAt: Date.now() + TTL_MS });
+};
+/**
+ * One-time-use, and expiring. Reading it removes it, so a link left in a
+ * long-open tab cannot be reused — the stash should be no weaker than the
+ * token it holds.
+ */
+export const consumeDevMagicLink = (email) => {
+    const key = normaliseEmail(email);
+    const entry = stash.get(key);
+    if (!entry)
+        return null;
+    stash.delete(key);
+    if (entry.expiresAt < Date.now())
+        return null;
+    return entry.url;
+};
+/** Test seam. Never called by the package itself. */
+export const clearDevMagicLinks = () => stash.clear();

package/dist/server/escape.d.ts

@@ -0,0 +1,9 @@
+export declare const escapeHtml: (value: unknown) => string;
+/**
+ * Escape a value for use inside a URL query string.
+ *
+ * `encodeURIComponent` already removes everything dangerous to HTML, but the
+ * result is then interpolated into an attribute, so it is escaped too rather
+ * than relying on that being true.
+ */
+export declare const escapeUrlParam: (value: unknown) => string;

package/dist/server/escape.js

@@ -0,0 +1,28 @@
+/**
+ * HTML escaping for the built-in pages.
+ *
+ * 🚨 **This is load-bearing.** The pages are HTML template literals served
+ * straight from the handle (ADR-0008), so there is no framework escaping
+ * anything. Every interpolated value goes through here — the email address a
+ * visitor typed, an error message, `appName`, and above all **the token**.
+ *
+ * Escapes the five characters that matter in both element text and quoted
+ * attribute values, so one function is safe in either position. Attributes in
+ * the pages are always double-quoted.
+ */
+const REPLACEMENTS = {
+    '&': '&',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#39;',
+};
+export const escapeHtml = (value) => String(value ?? '').replace(/[&<>"']/g, (c) => REPLACEMENTS[c]);
+/**
+ * Escape a value for use inside a URL query string.
+ *
+ * `encodeURIComponent` already removes everything dangerous to HTML, but the
+ * result is then interpolated into an attribute, so it is escaped too rather
+ * than relying on that being true.
+ */
+export const escapeUrlParam = (value) => escapeHtml(encodeURIComponent(String(value ?? '')));

package/dist/server/guard.d.ts

@@ -0,0 +1,13 @@
+import type { RequestEvent } from '@sveltejs/kit';
+import type { GfxAuthUser } from '../types.js';
+/**
+ * Throw a 401 unless there is a signed-in, non-disabled user.
+ *
+ * ⚠️ **The "non-disabled" half is not enforced here.** This only reads
+ * `event.locals.user`; it is {@link gfxAuth} that treats a user with
+ * `disabledAt` set as signed out, so the guarantee holds *because* the handle
+ * ran first (ADR-0004). Called from an app whose `hooks.server.ts` does not
+ * include `gfxAuth`, this would happily return a disabled user — which is
+ * another reason hook order is documented as strictly as it is.
+ */
+export declare const requireUser: (event: RequestEvent) => GfxAuthUser;

package/dist/server/guard.js

@@ -0,0 +1,17 @@
+import { error } from '@sveltejs/kit';
+/**
+ * Throw a 401 unless there is a signed-in, non-disabled user.
+ *
+ * ⚠️ **The "non-disabled" half is not enforced here.** This only reads
+ * `event.locals.user`; it is {@link gfxAuth} that treats a user with
+ * `disabledAt` set as signed out, so the guarantee holds *because* the handle
+ * ran first (ADR-0004). Called from an app whose `hooks.server.ts` does not
+ * include `gfxAuth`, this would happily return a disabled user — which is
+ * another reason hook order is documented as strictly as it is.
+ */
+export const requireUser = (event) => {
+    const user = event.locals.user;
+    if (!user)
+        error(401, 'Unauthorized');
+    return user;
+};