@merijnslegers/admin 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Merijn Slegers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,232 @@
-# Temporary Holding Version
+# @merijnslegers/admin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The admin login of the software factory (F-0011), and image resizing in the
+browser (F-0008). Each person signs in to `/admin` with their own email address
+and password through Supabase Auth. Who may enter is an allow list the project
+passes in, checked on every request.
+
+The package holds the login, the access rules and the headers. The screens, the
+components, the navigation and every sentence a user reads stay in the project,
+in its own look and language.
+
+```bash
+pnpm add @merijnslegers/admin @supabase/ssr @supabase/supabase-js
+```
+
+| Import                        | What it holds                                                            | Where it runs |
+| ----------------------------- | ------------------------------------------------------------------------ | ------------- |
+| `@merijnslegers/admin/server` | `createAdmin`: the hook and the functions for the login screens          | server only   |
+| `@merijnslegers/admin/rules`  | The pure rules: allow list, return path, Origin check, headers, password | anywhere      |
+| `@merijnslegers/admin/resize` | `resizeImage` and `resizeFormFiles`                                      | browser       |
+
+## Connecting a project
+
+**The settings.** Four variables, declared in `src/env.ts` and read at runtime
+(F-0005). The package reads none of them itself.
+
+| Variable                    | What it is                                                              |
+| --------------------------- | ----------------------------------------------------------------------- |
+| `SUPABASE_URL`              | The project's Supabase address (F-0009)                                 |
+| `SUPABASE_ANON_KEY`         | Only for logging in; it reads or writes no table                        |
+| `SUPABASE_SERVICE_ROLE_KEY` | Already there for the database (F-0004); here only to create a new user |
+| `ADMIN_EMAILS`              | Who may enter: addresses separated by commas, spaces or new lines       |
+
+Without one of them nobody gets in, the build still works, and
+`missingSettings()` names what is missing so the login screen can show it.
+A project whose variables are named differently passes `settingNames`.
+
+**One module**, `src/lib/server/admin.ts`:
+
+```ts
+import { createAdmin } from '@merijnslegers/admin/server';
+import {
+	ADMIN_EMAILS,
+	SUPABASE_ANON_KEY,
+	SUPABASE_SERVICE_ROLE_KEY,
+	SUPABASE_URL
+} from '$app/env/private';
+
+export const admin = createAdmin({
+	supabaseUrl: SUPABASE_URL,
+	anonKey: SUPABASE_ANON_KEY,
+	serviceRoleKey: SUPABASE_SERVICE_ROLE_KEY,
+	allowList: ADMIN_EMAILS,
+	// Optional: a project in Dutch names its screens in Dutch.
+	paths: { login: '/admin/inloggen', password: '/admin/wachtwoord' },
+	// Optional: the hook's 401 and 403 in the project's own words.
+	responses: {
+		unauthorized: 'U bent niet ingelogd.',
+		forbidden: 'Dit verzoek kwam niet van onze eigen site.'
+	}
+});
+```
+
+**The hook**, in `src/hooks.server.ts`. With other hooks, combine them with
+`sequence`.
+
+```ts
+import { admin } from '#lib/server/admin.js';
+
+export const handle = admin.handle;
+```
+
+For everything under the admin path it:
+
+- lets the login and password screens through without a session;
+- sends a page, a link from a mail or a form without a session to the login
+  screen, and back to where it was afterwards (only within the admin path);
+- answers any other request without a session with a 401;
+- answers a request that can change something with a 403 when it does not come
+  from the site's own origin, even when SvelteKit's own check is off for a
+  webhook;
+- gives that 401 or 403 the text from `responses` as plain text, or an empty
+  body without it, so the package chooses no words of its own;
+- puts `ADMIN_HEADERS` on every response: no framing, `noindex`, `no-store`,
+  a referrer that stays on the site.
+
+Someone signed in is in `event.locals.admin` (`{ email }`). Declare it in
+`src/app.d.ts`:
+
+```ts
+declare global {
+	namespace App {
+		interface Locals {
+			admin?: import('@merijnslegers/admin/server').Admin;
+		}
+	}
+}
+```
+
+A webhook belongs under `/api`, never under the admin path.
+
+**Remote functions** are called at `/_app/remote/...`, outside the admin path,
+so the hook does not guard them. An admin remote function checks
+`admin.currentAdmin(cookies)` itself, first thing.
+
+**The screens.** The login and password screens use `+page@.svelte`, so they do
+not hang under the admin layout, which belongs to someone signed in. Their
+actions call the package and turn its outcome into the project's own words:
+
+```ts
+// src/routes/admin/inloggen/+page.server.ts
+import { fail, redirect } from '@sveltejs/kit';
+import { safeReturnPath } from '@merijnslegers/admin/rules';
+import { admin } from '#lib/server/admin.js';
+
+const TEXT = {
+	invalid_credentials: 'Dit e-mailadres en wachtwoord horen niet bij elkaar.',
+	rate_limited: 'Te veel pogingen. Wacht een paar minuten.',
+	missing_setting: 'Dit e-mailadres en wachtwoord horen niet bij elkaar.'
+};
+
+export const load = async ({ cookies, url }) => {
+	const to = safeReturnPath(url.searchParams.get('to'), admin.paths);
+	if (await admin.currentAdmin(cookies)) redirect(303, to);
+	return { to, missing: admin.missingSettings() };
+};
+
+export const actions = {
+	signIn: async ({ request, cookies }) => {
+		const data = await request.formData();
+		const email = String(data.get('email') ?? '');
+		const outcome = await admin.signIn(cookies, email, String(data.get('password') ?? ''));
+		if (outcome !== 'ok')
+			return fail(outcome === 'rate_limited' ? 429 : 400, { email, error: TEXT[outcome] });
+		redirect(303, safeReturnPath(String(data.get('to') ?? ''), admin.paths));
+	}
+};
+```
+
+| Function                                   | Outcomes                                                                                                                           |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `signIn(cookies, email, password)`         | `ok`, `invalid_credentials`, `rate_limited`, `missing_setting`                                                                     |
+| `sendPasswordLink(cookies, email, origin)` | `ok`, `invalid_email`, `rate_limited`, `send_failed`                                                                               |
+| `setPassword(cookies, input)`              | `ok`, `password_too_short`, `passwords_differ`, `link_invalid`, `not_signed_in`, `weak_password`, `save_failed`, `missing_setting` |
+| `signOut(cookies)`                         | nothing                                                                                                                            |
+
+Some outcomes say nothing on purpose:
+
+- An address that is not on the list gets `invalid_credentials`, just like a
+  wrong password, and Supabase is not called.
+- `sendPasswordLink` answers `ok` for every valid address, and only one on the
+  list gets a mail.
+
+So no screen gives away who has access.
+
+**A password link** works for a first password and a forgotten one alike:
+
+- `sendPasswordLink` creates the user if they do not exist yet. You never create
+  one by hand.
+- On the password screen, `readPasswordLink(url)` reads the link in `load` and
+  puts it in the form.
+- `setPassword` uses the link only once the password is saved, because mail
+  programs and virus scanners open links in advance.
+- Both kinds of link work: `token_hash` (your own mail template, any browser)
+  and `code` (Supabase's default template, only in the browser that asked for
+  it).
+- Someone signed in sets a new password on the same screen, without a link.
+- A password is at least `PASSWORD_MIN_LENGTH` (10) characters.
+
+## Settings in Supabase
+
+Under Authentication:
+
+- **URL Configuration, Redirect URLs:** the password screen on the production
+  domain, such as `https://www.<domain>/admin/password`, and on the previews.
+  - Mind `www`: the link is built from the address the person is on.
+  - Supabase replaces an address that is not listed by the Site URL, and then
+    the link does not work.
+- **"Allow new users to sign up"** may be off. The package creates users with
+  the `service_role` key, which does not look at it.
+- **Emails, SMTP Settings:** your own mail server, through Resend
+  (`smtp.resend.com`, port 465, user `resend`, an API key of its own as
+  password). Without it, Supabase only mails members of its own organisation, a
+  few per hour, and you cannot change the templates.
+- **Emails, template "Reset password":** the link as
+  `{{ .RedirectTo }}?token_hash={{ .TokenHash }}` instead of
+  `{{ .ConfirmationURL }}`. It then goes straight to your own screen and is used
+  only on saving.
+
+## Resizing images
+
+In the browser, before the upload (F-0008). The project sets the width and the
+format per kind of image, in one place:
+
+```ts
+import { resizeFormFiles, resizeImage } from '@merijnslegers/admin/resize';
+
+const SCREENSHOT = { maxWidth: 2000 }; // webp, for the site
+const MAIL_PHOTO = { maxWidth: 1200, format: 'mail' } as const; // JPEG, PNG kept
+
+await resizeFormFiles(formData, 'images', SCREENSHOT);
+const photo = await resizeImage(file, MAIL_PHOTO);
+```
+
+- **`webp`** (the default) for images on the site.
+- **`mail`** for images in an email. Many mail clients (Outlook) do not show
+  webp, so the image becomes JPEG, and a PNG stays PNG because it often holds
+  transparency.
+- A phone photo stays upright (its EXIF orientation).
+- An image that is already narrow enough and under 1 MB is left alone.
+- SVG and GIF are never drawn again.
+- When the browser cannot do it, or the result is not smaller, the original
+  goes and the server decides. With `mail`, a webp or AVIF is always turned
+  into JPEG, even when that is larger.
+- A browser without `OffscreenCanvas` draws on an ordinary canvas instead.
+
+## Tests
+
+The rules and the resize plan are pure; `npm test` at the repo root runs their
+tests. A project's own tests use the same rules without Supabase, for instance
+for its own screen names:
+
+```ts
+// F-0011
+import { adminPaths, safeReturnPath } from '@merijnslegers/admin/rules';
+
+const paths = adminPaths({ login: '/admin/inloggen', password: '/admin/wachtwoord' });
+
+it('never sends you back to the login screen', () => {
+	expect(safeReturnPath('/admin/inloggen', paths)).toBe('/admin');
+});
+```

package/package.json

@@ -1,6 +1,41 @@
 {
-  "name": "@merijnslegers/admin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@merijnslegers/admin",
+	"version": "0.2.0",
+	"description": "The admin login of the software factory: Supabase Auth with an allow list, the access rules and headers, and image resizing in the browser.",
+	"license": "MIT",
+	"type": "module",
+	"exports": {
+		"./rules": {
+			"types": "./src/rules.d.ts",
+			"default": "./src/rules.js"
+		},
+		"./server": {
+			"types": "./src/server.d.ts",
+			"default": "./src/server.js"
+		},
+		"./resize": {
+			"types": "./src/resize.d.ts",
+			"default": "./src/resize.js"
+		}
+	},
+	"files": [
+		"src",
+		"README.md"
+	],
+	"engines": {
+		"node": ">=22.17"
+	},
+	"peerDependencies": {
+		"@supabase/ssr": "^0.12.7",
+		"@supabase/supabase-js": "^2.118.0",
+		"@sveltejs/kit": "^3.0.0"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Merijnslegers90/software-factory.git",
+		"directory": "packages/admin"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}

package/src/resize.d.ts

@@ -0,0 +1,33 @@
+/** `webp` for images on the site; `mail` (JPEG, PNG kept) for images in an email. */
+export type ImageFormat = 'webp' | 'mail';
+
+export interface ResizeOptions {
+	/** The maximum width for this kind of image, in pixels. */
+	maxWidth: number;
+	format?: ImageFormat;
+	/** 0 to 1, for webp and JPEG. 0.85 by default. */
+	quality?: number;
+}
+
+export interface ResizePlan {
+	width: number;
+	height: number;
+	type: 'image/webp' | 'image/jpeg' | 'image/png';
+	extension: 'webp' | 'jpg' | 'png';
+}
+
+export const SKIP_BELOW_BYTES: number;
+export function keepsAsIs(type: string): boolean;
+export function mustConvert(type: string, format: ImageFormat): boolean;
+export function targetType(type: string, format: ImageFormat): ResizePlan['type'];
+export function resizePlan(
+	image: { type: string; size: number; width: number; height: number },
+	options: { maxWidth: number; format?: ImageFormat }
+): ResizePlan | null;
+export function renamed(name: string, extension: string): string;
+export function resizeImage(file: File, options: ResizeOptions): Promise<File>;
+export function resizeFormFiles(
+	formData: FormData,
+	field: string,
+	options: ResizeOptions
+): Promise<void>;

package/src/resize.js

@@ -0,0 +1,113 @@
+// Resizes images in the browser before they are uploaded (F-0008). A function
+// on Vercel accepts about 4.5 MB per request, and a photo from a phone is a few
+// megabytes. The plan (what to do with which file) is pure and tested; the
+// drawing itself needs a browser.
+
+/** Leave an image alone that is already narrow enough and smaller than this: compressing it again only makes it worse. */
+export const SKIP_BELOW_BYTES = 1024 * 1024;
+
+/** SVG is not drawn on a canvas; a GIF would lose its animation. */
+export function keepsAsIs(type) {
+	return !/^image\//.test(type) || type === 'image/gif' || type === 'image/svg+xml';
+}
+
+/**
+ * The type a resized image gets. `webp` for the site. `mail` for an image in an
+ * email: many mail clients (Outlook) do not show webp, so it becomes JPEG, and
+ * a PNG stays PNG because it often holds transparency (a logo) that turns
+ * black in a JPEG.
+ */
+export function targetType(type, format) {
+	if (format === 'mail') return type === 'image/png' ? 'image/png' : 'image/jpeg';
+	return 'image/webp';
+}
+
+/**
+ * Whether the original may not go as it is, whatever its size: a webp or AVIF
+ * in a mail would not show in many mail clients.
+ */
+export function mustConvert(type, format) {
+	return format === 'mail' && type !== 'image/jpeg' && type !== 'image/png';
+}
+
+const EXTENSIONS = { 'image/webp': 'webp', 'image/jpeg': 'jpg', 'image/png': 'png' };
+
+/**
+ * What to do with an image of this type, size and width: null to keep the
+ * original, or the size and type to draw it at.
+ */
+export function resizePlan({ type, size, width, height }, { maxWidth, format = 'webp' }) {
+	if (keepsAsIs(type)) return null;
+	if (width <= maxWidth && size <= SKIP_BELOW_BYTES && !mustConvert(type, format)) return null;
+	const scale = Math.min(1, maxWidth / width);
+	const target = targetType(type, format);
+	return {
+		width: Math.max(1, Math.round(width * scale)),
+		height: Math.max(1, Math.round(height * scale)),
+		type: target,
+		extension: EXTENSIONS[target]
+	};
+}
+
+/** The file name with the extension of the new type; the server derives the storage path from it. */
+export function renamed(name, extension) {
+	return `${String(name).replace(/\.[^.]+$/, '') || 'image'}.${extension}`;
+}
+
+/**
+ * Resizes one image. When it cannot (a format the browser cannot unpack, no
+ * canvas) or the result is not smaller, the original goes and the server
+ * decides.
+ */
+export async function resizeImage(file, { maxWidth, format = 'webp', quality = 0.85 }) {
+	if (keepsAsIs(file.type)) return file;
+	let bitmap;
+	try {
+		// from-image: otherwise an upright phone photo comes back lying down,
+		// because the rotation is only in its EXIF data.
+		bitmap = await createImageBitmap(file, { imageOrientation: 'from-image' });
+		const plan = resizePlan(
+			{ type: file.type, size: file.size, width: bitmap.width, height: bitmap.height },
+			{ maxWidth, format }
+		);
+		if (!plan) return file;
+
+		const blob = await draw(bitmap, plan, plan.type === 'image/png' ? undefined : quality);
+		// A browser that cannot write the type (webp in an older Safari) quietly
+		// gives a PNG instead; then the original is the better choice.
+		if (!blob || blob.type !== plan.type) return file;
+		if (blob.size >= file.size && !mustConvert(file.type, format)) return file;
+		return new File([blob], renamed(file.name, plan.extension), { type: plan.type });
+	} catch (err) {
+		console.error('Resizing failed, the original is used:', err);
+		return file;
+	} finally {
+		bitmap?.close();
+	}
+}
+
+async function draw(bitmap, plan, quality) {
+	if (typeof OffscreenCanvas !== 'undefined') {
+		const canvas = new OffscreenCanvas(plan.width, plan.height);
+		const context = canvas.getContext('2d');
+		if (!context) return null;
+		context.drawImage(bitmap, 0, 0, plan.width, plan.height);
+		return canvas.convertToBlob({ type: plan.type, quality });
+	}
+	const canvas = document.createElement('canvas');
+	canvas.width = plan.width;
+	canvas.height = plan.height;
+	const context = canvas.getContext('2d');
+	if (!context) return null;
+	context.drawImage(bitmap, 0, 0, plan.width, plan.height);
+	return new Promise((done) => canvas.toBlob(done, plan.type, quality));
+}
+
+/** Replaces the files in one field of a FormData by resized versions. */
+export async function resizeFormFiles(formData, field, options) {
+	const files = formData.getAll(field).filter((v) => v instanceof File && v.size > 0);
+	formData.delete(field);
+	for (const file of await Promise.all(files.map((f) => resizeImage(f, options)))) {
+		formData.append(field, file);
+	}
+}

package/src/rules.d.ts

@@ -0,0 +1,72 @@
+export interface AdminPaths {
+	/** The admin path, `/admin` by default. */
+	base: string;
+	/** The login screen, `<base>/login` by default. */
+	login: string;
+	/** The password screen, `<base>/password` by default. */
+	password: string;
+}
+
+export type AdminDecision =
+	| { kind: 'pass' }
+	| { kind: 'redirect'; location: string }
+	| { kind: 'unauthorized' }
+	| { kind: 'forbidden' };
+
+/** The project's own words for the hook's 401 and 403. A missing one is an empty body. */
+export interface AdminResponses {
+	unauthorized?: string;
+	forbidden?: string;
+}
+
+export interface SettingNames {
+	supabaseUrl: string;
+	anonKey: string;
+	serviceRoleKey: string;
+	allowList: string;
+}
+
+export const PASSWORD_MIN_LENGTH: number;
+export const ADMIN_HEADERS: Readonly<Record<string, string>>;
+
+export function adminPaths(paths?: Partial<AdminPaths>): AdminPaths;
+export function decodePath(pathname: string): string | null;
+export function isAdminPath(pathname: string, paths: AdminPaths): boolean;
+export function isOpenPath(pathname: string, paths: AdminPaths): boolean;
+export function normaliseEmail(email: string | null | undefined): string;
+export function parseAllowList(list: string | null | undefined): Set<string>;
+export function mayManage(email: string | null | undefined, allowList: Set<string>): boolean;
+export function passwordProblem(
+	password: string,
+	repeat: string
+): 'password_too_short' | 'passwords_differ' | null;
+export function safeReturnPath(to: string | null | undefined, paths: AdminPaths): string;
+export function loginAddress(from: URL, paths: AdminPaths): string;
+export function fromOtherSite(method: string, origin: string | null, ownOrigin: string): boolean;
+export function adminDecision(request: {
+	url: URL;
+	method: string;
+	contentType: string | null;
+	origin: string | null;
+	signedIn: boolean;
+	paths: AdminPaths;
+}): AdminDecision;
+export function refusal(kind: 'unauthorized' | 'forbidden', responses?: AdminResponses): Response;
+export function missingSettings(
+	settings: {
+		supabaseUrl: string;
+		anonKey: string;
+		allowList: Set<string>;
+	},
+	names: SettingNames
+): string[];
+export function signInOutcome(
+	error: { status?: number; code?: string } | null
+): 'ok' | 'rate_limited' | 'invalid_credentials';
+export function linkOutcome(
+	error: { status?: number; code?: string } | null
+): 'ok' | 'rate_limited' | 'send_failed';
+export function passwordOutcome(
+	error: { status?: number; code?: string } | null
+): 'ok' | 'weak_password' | 'save_failed';
+export function readPasswordLink(url: URL): { tokenHash: string; code: string; linkError: boolean };

package/src/rules.js

@@ -0,0 +1,209 @@
+// The rules around the admin login (F-0011). Pure, so they are tested without
+// Supabase or SvelteKit (F-0006). The calls to Supabase are in server.js.
+
+/** Longer than the six characters Supabase asks by default. A short sentence or a password manager makes it easily. */
+export const PASSWORD_MIN_LENGTH = 10;
+
+/**
+ * Every response under the admin path gets these headers. Not in a frame, so
+ * no other site can lay our buttons under a page of its own; not in a search
+ * engine; not in a cache; and no admin address (with an email or an invoice in
+ * it) as referrer to another service.
+ */
+export const ADMIN_HEADERS = Object.freeze({
+	'Content-Security-Policy': "frame-ancestors 'none'",
+	'X-Frame-Options': 'DENY',
+	'X-Robots-Tag': 'noindex, nofollow',
+	'Referrer-Policy': 'same-origin',
+	'X-Content-Type-Options': 'nosniff',
+	'Cache-Control': 'private, no-store'
+});
+
+/** The admin path and its two screens that open without a session. */
+export function adminPaths({ base = '/admin', login, password } = {}) {
+	const root = base.replace(/\/+$/, '') || '/admin';
+	return {
+		base: root,
+		login: login ?? `${root}/login`,
+		password: password ?? `${root}/password`
+	};
+}
+
+/**
+ * The path as SvelteKit decodes it to pick a route. Comparing the raw path
+ * would let `/%61dmin/orders` reach the route `/admin/orders` past the hook.
+ * Null when it cannot be decoded.
+ */
+export function decodePath(pathname) {
+	try {
+		return pathname.split('%25').map(decodeURI).join('%25');
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Whether a path is the admin path or below it, after decoding. `/administration`
+ * is not. A path that cannot be decoded counts as admin, so it stays closed.
+ */
+export function isAdminPath(pathname, paths) {
+	const path = decodePath(pathname);
+	return path === null || path === paths.base || path.startsWith(paths.base + '/');
+}
+
+/** The screens under the admin path you must reach without a session, after decoding. */
+export function isOpenPath(pathname, paths) {
+	const path = decodePath(pathname);
+	return path !== null && (path === paths.login || path === paths.password);
+}
+
+/** An email address as we compare it: without spaces, in lower case. */
+export function normaliseEmail(email) {
+	return String(email ?? '')
+		.trim()
+		.toLowerCase();
+}
+
+/**
+ * The allow list from `ADMIN_EMAILS`: addresses separated by commas,
+ * semicolons, spaces or new lines. An entry without `@` is a typo and does not
+ * count.
+ */
+export function parseAllowList(list) {
+	return new Set(
+		String(list ?? '')
+			.split(/[\s,;]+/)
+			.map(normaliseEmail)
+			.filter((email) => email.includes('@'))
+	);
+}
+
+/** Whether this address may manage. Without an address, never. */
+export function mayManage(email, allowList) {
+	return !!email && allowList.has(normaliseEmail(email));
+}
+
+/** What is wrong with a new password, or null when it is fine. */
+export function passwordProblem(password, repeat) {
+	if (String(password ?? '').length < PASSWORD_MIN_LENGTH) return 'password_too_short';
+	if (password !== repeat) return 'passwords_differ';
+	return null;
+}
+
+/**
+ * Where to go after logging in. The address comes from a link, so only a path
+ * within the admin path on our own site counts; otherwise a link such as
+ * `?to=https://elsewhere` would turn our login screen into a relay.
+ */
+export function safeReturnPath(to, paths) {
+	if (!to || !to.startsWith('/') || to.startsWith('//') || to.includes('\\')) return paths.base;
+	const origin = 'https://admin.invalid';
+	let url;
+	try {
+		url = new URL(to, origin);
+	} catch {
+		return paths.base;
+	}
+	if (
+		url.origin !== origin ||
+		!isAdminPath(url.pathname, paths) ||
+		isOpenPath(url.pathname, paths)
+	) {
+		return paths.base;
+	}
+	return url.pathname + url.search;
+}
+
+/** The login screen, with the path you came from. Read back with `safeReturnPath`. */
+export function loginAddress(from, paths) {
+	const to = from.pathname + from.search;
+	return to === paths.base ? paths.login : `${paths.login}?to=${encodeURIComponent(to)}`;
+}
+
+/**
+ * Whether a request comes from another site. Every method that can change
+ * something, a fetch with JSON too, must come from our own origin. A browser
+ * always sets an Origin on such a request; without one, it was not a form on
+ * our screen. This holds even when SvelteKit's own check is off for a webhook.
+ */
+export function fromOtherSite(method, origin, ownOrigin) {
+	if (method === 'GET' || method === 'HEAD' || method === 'OPTIONS') return false;
+	return origin !== ownOrigin;
+}
+
+const FORM = /^(multipart\/form-data|application\/x-www-form-urlencoded)/;
+
+/**
+ * What the hook does with a request under the admin path.
+ *
+ * - `pass`: let it through.
+ * - `redirect`: a page, a link from a mail or a form without a session goes to
+ *   the login screen (`location`), and back afterwards.
+ * - `unauthorized`: a fetch to an endpoint without a session gets a 401; there
+ *   is nowhere to send it.
+ * - `forbidden`: it can change something and does not come from our site.
+ */
+export function adminDecision({ url, method, contentType, origin, signedIn, paths }) {
+	if (signedIn || isOpenPath(url.pathname, paths)) {
+		return fromOtherSite(method, origin, url.origin) ? { kind: 'forbidden' } : { kind: 'pass' };
+	}
+	if (method === 'GET' || method === 'HEAD' || FORM.test(contentType ?? '')) {
+		return { kind: 'redirect', location: loginAddress(url, paths) };
+	}
+	return { kind: 'unauthorized' };
+}
+
+/**
+ * The answer to an `unauthorized` (401) or `forbidden` (403) decision. The
+ * package chooses no words (F-0011): the body is the project's own text from
+ * `responses`, or empty when it passes none. `ADMIN_HEADERS` are on it too.
+ */
+export function refusal(kind, responses = {}) {
+	const status = kind === 'forbidden' ? 403 : 401;
+	const text = (kind === 'forbidden' ? responses.forbidden : responses.unauthorized) ?? '';
+	const headers = new Headers(ADMIN_HEADERS);
+	if (!text) return new Response(null, { status, headers });
+	headers.set('Content-Type', 'text/plain; charset=utf-8');
+	return new Response(text, { status, headers });
+}
+
+/**
+ * The settings logging in needs that are missing, by the names the project
+ * gave them. Empty when everything is there. Without them nobody gets in
+ * (F-0005). The service_role key is not among them: only a password link
+ * needs it, and the database has it anyway (F-0004).
+ */
+export function missingSettings(settings, names) {
+	const missing = [];
+	if (!settings.supabaseUrl) missing.push(names.supabaseUrl);
+	if (!settings.anonKey) missing.push(names.anonKey);
+	if (settings.allowList.size === 0) missing.push(names.allowList);
+	return missing;
+}
+
+/** The outcome of signing in, from Supabase's error. */
+export function signInOutcome(error) {
+	if (!error) return 'ok';
+	return error.status === 429 ? 'rate_limited' : 'invalid_credentials';
+}
+
+/** The outcome of sending a password link, from Supabase's error. */
+export function linkOutcome(error) {
+	if (!error) return 'ok';
+	return error.status === 429 ? 'rate_limited' : 'send_failed';
+}
+
+/** The outcome of saving a password, from Supabase's error. The same password as now is fine: you know it already. */
+export function passwordOutcome(error) {
+	if (!error || error.code === 'same_password') return 'ok';
+	return error.code === 'weak_password' ? 'weak_password' : 'save_failed';
+}
+
+/** The link parameters on the password screen. They are used only on saving, never on opening. */
+export function readPasswordLink(url) {
+	return {
+		tokenHash: url.searchParams.get('token_hash') ?? '',
+		code: url.searchParams.get('code') ?? '',
+		linkError: url.searchParams.has('error')
+	};
+}

package/src/server.d.ts

@@ -0,0 +1,54 @@
+import type { Cookies } from '@sveltejs/kit';
+import type { Handle } from '@sveltejs/kit/hooks';
+import type { AdminPaths, AdminResponses, SettingNames } from './rules.js';
+
+export interface AdminOptions {
+	/** Read at runtime in the project's src/env.ts (F-0005). An empty string means missing. */
+	supabaseUrl: string;
+	anonKey: string;
+	serviceRoleKey: string;
+	/** `ADMIN_EMAILS`: addresses separated by commas, semicolons, spaces or new lines. */
+	allowList: string;
+	/** Where the admin lives and its two open screens. */
+	paths?: Partial<AdminPaths>;
+	/** The names `missingSettings()` reports, if the project's variables are named differently. */
+	settingNames?: Partial<SettingNames>;
+	/** The body of the hook's 401 and 403, in the project's own words. Without it the body is empty. */
+	responses?: AdminResponses;
+}
+
+export interface Admin {
+	email: string;
+}
+
+export type SignInOutcome = 'ok' | 'invalid_credentials' | 'rate_limited' | 'missing_setting';
+export type LinkOutcome = 'ok' | 'invalid_email' | 'rate_limited' | 'send_failed';
+export type PasswordOutcome =
+	| 'ok'
+	| 'password_too_short'
+	| 'passwords_differ'
+	| 'link_invalid'
+	| 'not_signed_in'
+	| 'weak_password'
+	| 'save_failed'
+	| 'missing_setting';
+
+export interface AdminLogin {
+	paths: AdminPaths;
+	/** For hooks.server.ts. Sets `event.locals.admin` when someone is signed in. */
+	handle: Handle;
+	currentAdmin(cookies: Cookies): Promise<Admin | null>;
+	mayLogIn(email: string): boolean;
+	/** The names of the settings that are missing; empty when everything is there. */
+	missingSettings(): string[];
+	signIn(cookies: Cookies, email: string, password: string): Promise<SignInOutcome>;
+	/** `ok` for every valid address, on the list or not; only one on the list gets a mail. */
+	sendPasswordLink(cookies: Cookies, email: string, origin: string): Promise<LinkOutcome>;
+	setPassword(
+		cookies: Cookies,
+		input: { tokenHash?: string; code?: string; password: string; repeat: string }
+	): Promise<PasswordOutcome>;
+	signOut(cookies: Cookies): Promise<void>;
+}
+
+export function createAdmin(options: AdminOptions): AdminLogin;

package/src/server.js

@@ -0,0 +1,213 @@
+// The admin login with Supabase Auth (F-0011). Server-only: the keys and the
+// cookie stay on the server, the browser never talks to Supabase itself.
+//
+// The client with the anon key is only for logging in and reads or writes no
+// table. The database stays with the service_role key, as everywhere (F-0004);
+// that key is used here only to create a user on their first password link.
+//
+// The package reads no environment variable. The project reads them in its
+// src/env.ts at runtime (F-0005) and passes them in; a missing one is an empty
+// string, and then nobody gets in.
+
+import { redirect } from '@sveltejs/kit';
+import { createServerClient } from '@supabase/ssr';
+import { createClient } from '@supabase/supabase-js';
+import {
+	ADMIN_HEADERS,
+	adminDecision,
+	adminPaths,
+	isAdminPath,
+	linkOutcome,
+	mayManage,
+	missingSettings,
+	normaliseEmail,
+	parseAllowList,
+	passwordOutcome,
+	passwordProblem,
+	refusal,
+	signInOutcome
+} from './rules.js';
+
+const DEFAULT_NAMES = {
+	supabaseUrl: 'SUPABASE_URL',
+	anonKey: 'SUPABASE_ANON_KEY',
+	serviceRoleKey: 'SUPABASE_SERVICE_ROLE_KEY',
+	allowList: 'ADMIN_EMAILS'
+};
+
+export function createAdmin(options) {
+	const paths = adminPaths(options.paths);
+	const settings = {
+		supabaseUrl: options.supabaseUrl ?? '',
+		anonKey: options.anonKey ?? '',
+		serviceRoleKey: options.serviceRoleKey ?? '',
+		allowList: parseAllowList(options.allowList)
+	};
+	const names = { ...DEFAULT_NAMES, ...options.settingNames };
+	const missing = missingSettings(settings, names);
+	const ready = missing.length === 0;
+
+	function mayLogIn(email) {
+		return mayManage(email, settings.allowList);
+	}
+
+	/** The login client for this request. The cookie belongs to the admin path only, and no script in the browser needs it. */
+	function authClient(cookies) {
+		return createServerClient(settings.supabaseUrl, settings.anonKey, {
+			cookies: {
+				getAll: () => cookies.getAll(),
+				setAll: (toSet) => {
+					for (const { name, value, options: cookieOptions } of toSet) {
+						cookies.set(name, value, {
+							...cookieOptions,
+							path: paths.base,
+							httpOnly: true,
+							sameSite: 'lax'
+						});
+					}
+				}
+			}
+		});
+	}
+
+	/**
+	 * Who is signed in with this cookie, or null. `getClaims` checks the
+	 * token's signature and refreshes an expired one. An address no longer on
+	 * the allow list does not count, even with a valid session: that is how
+	 * someone's access is taken away.
+	 */
+	async function currentAdmin(cookies) {
+		if (!ready) return null;
+		const { data, error } = await authClient(cookies).auth.getClaims();
+		if (error || !data) return null;
+		const email = data.claims.email;
+		return typeof email === 'string' && mayLogIn(email) ? { email: normaliseEmail(email) } : null;
+	}
+
+	/** The hook for hooks.server.ts. Combine it with others through `sequence`. */
+	async function handle({ event, resolve }) {
+		if (!isAdminPath(event.url.pathname, paths)) return resolve(event);
+
+		const admin = await currentAdmin(event.cookies);
+		if (admin) event.locals.admin = admin;
+
+		const decision = adminDecision({
+			url: event.url,
+			method: event.request.method,
+			contentType: event.request.headers.get('content-type'),
+			origin: event.request.headers.get('origin'),
+			signedIn: !!admin,
+			paths
+		});
+		// SvelteKit turns this redirect into the right answer for a page load
+		// and for a form with use:enhance. It has no content that could end up
+		// in a frame, a search engine or a cache.
+		if (decision.kind === 'redirect') redirect(303, decision.location);
+
+		const response =
+			decision.kind === 'pass'
+				? await resolve(event)
+				: refusal(decision.kind, options.responses);
+		for (const [name, value] of Object.entries(ADMIN_HEADERS)) response.headers.set(name, value);
+		return response;
+	}
+
+	/**
+	 * An address not on the list gets the same outcome as a wrong password,
+	 * and Supabase is not called. So the screen gives away nothing about who
+	 * has access.
+	 */
+	async function signIn(cookies, email, password) {
+		if (!ready) return 'missing_setting';
+		if (!mayLogIn(email) || !password) return 'invalid_credentials';
+		const { error } = await authClient(cookies).auth.signInWithPassword({
+			email: normaliseEmail(email),
+			password
+		});
+		if (error && error.status !== 429 && error.code !== 'invalid_credentials') {
+			console.error('Admin sign in failed:', error.message);
+		}
+		return signInOutcome(error);
+	}
+
+	/**
+	 * Sends a link to set a password, the first time or when it is forgotten.
+	 * Supabase only mails a user that exists, so someone on the list who is no
+	 * user yet is created first, without a password. The outcome is the same
+	 * for every address, and only one on the list gets a mail.
+	 *
+	 * The link goes to the project's own password screen, which uses it only
+	 * once the password is saved.
+	 */
+	async function sendPasswordLink(cookies, email, origin) {
+		if (!normaliseEmail(email).includes('@')) return 'invalid_email';
+		if (!ready || !mayLogIn(email)) return 'ok';
+		if (!settings.serviceRoleKey) {
+			console.error(`Sending password link failed: ${names.serviceRoleKey} is missing.`);
+			return 'send_failed';
+		}
+
+		const service = createClient(settings.supabaseUrl, settings.serviceRoleKey, {
+			auth: { autoRefreshToken: false, persistSession: false }
+		});
+		const { error: createError } = await service.auth.admin.createUser({
+			email: normaliseEmail(email),
+			email_confirm: true
+		});
+		// Existing already is exactly right.
+		if (createError && createError.code !== 'email_exists') {
+			console.error('Creating admin user failed:', createError.message);
+			return linkOutcome(createError);
+		}
+		const { error } = await authClient(cookies).auth.resetPasswordForEmail(normaliseEmail(email), {
+			redirectTo: origin + paths.password
+		});
+		if (error) console.error('Sending password link failed:', error.message);
+		return linkOutcome(error);
+	}
+
+	/**
+	 * Saves a new password, with the link from the mail (`tokenHash` or `code`)
+	 * or while signed in. The password is checked first: a link works only
+	 * once, so it is spent only when the rest is right.
+	 */
+	async function setPassword(cookies, { tokenHash = '', code = '', password, repeat }) {
+		const problem = passwordProblem(password, repeat);
+		if (problem) return problem;
+		if (!ready) return 'missing_setting';
+
+		const supabase = authClient(cookies);
+		if (tokenHash || code) {
+			const { data, error } = tokenHash
+				? await supabase.auth.verifyOtp({ token_hash: tokenHash, type: 'recovery' })
+				: await supabase.auth.exchangeCodeForSession(code);
+			if (error || !mayLogIn(data.user?.email ?? '')) {
+				if (!error) await supabase.auth.signOut({ scope: 'local' });
+				return 'link_invalid';
+			}
+		} else if (!(await currentAdmin(cookies))) {
+			return 'not_signed_in';
+		}
+
+		const { error } = await supabase.auth.updateUser({ password });
+		const outcome = passwordOutcome(error);
+		if (outcome === 'save_failed') console.error('Saving password failed:', error.message);
+		return outcome;
+	}
+
+	async function signOut(cookies) {
+		if (ready) await authClient(cookies).auth.signOut({ scope: 'local' });
+	}
+
+	return {
+		paths,
+		handle,
+		currentAdmin,
+		mayLogIn,
+		missingSettings: () => [...missing],
+		signIn,
+		sendPasswordLink,
+		setPassword,
+		signOut
+	};
+}