@plitzi/sdk-server 0.33.2 → 0.34.0

package/dist/core/auth/routes.js

@@ -1,3 +1,4 @@
+import { csrfFailureMessage } from "./csrf.js";
 //#region src/core/auth/routes.ts
 var body = (req) => req.body ?? {};
 /** A body field as a string, whatever arrived. Handlers validate what they need; this only stops `[object Object]`. */
@@ -5,6 +6,32 @@ var field = (req, name) => {
 	const value = body(req)[name];
 	return typeof value === "string" ? value : "";
 };
+/** A body field as a whole number. `NaN` for anything else, which every handler refuses as a missing id. */
+var numberField = (req, name) => {
+	const value = body(req)[name];
+	if (typeof value === "number") return value;
+	return typeof value === "string" ? Number.parseInt(value, 10) : NaN;
+};
+var queryText = (req, name) => {
+	const value = req.query?.[name];
+	return typeof value === "string" && value ? value : void 0;
+};
+var queryNumber = (req, name) => {
+	const parsed = Number.parseInt(queryText(req, name) ?? "", 10);
+	return Number.isFinite(parsed) ? parsed : void 0;
+};
+/**
+* Whatever arrived as `roles`, unexamined.
+*
+* Deliberately NOT coerced to a list here. It was, and a client sending `roles: "editor"` — the obvious mistake —
+* got an empty list, which `setRoles` faithfully applied: every role removed, and a 200 saying it worked. The
+* handler validates instead, so the wrong shape is a 400.
+*/
+var rolesOf = (req) => body(req).roles;
+var SUBJECT_OF = {
+	signIn: "signIn",
+	grant: "delegated"
+};
 /**
 * The whole `/auth` surface as data: which method and path each flow answers on, what a caller must present, and what
 * to call.
@@ -24,6 +51,17 @@ var FLOWS = [
 		requirement: "public",
 		run: (api) => api.describe()
 	},
+	(
+	/**
+	* A token to write with, for a page that has none. Public because signing IN needs one: without a token before
+	* anybody is authenticated, another site can log a visitor into an account it controls.
+	*/
+	{
+		method: "GET",
+		path: "/csrf",
+		requirement: "public",
+		run: (api, cookies, req) => api.issueCsrf(cookies.resolveSessionToken(req))
+	}),
 	{
 		method: "GET",
 		path: "/session",
@@ -34,18 +72,21 @@ var FLOWS = [
 		method: "POST",
 		path: "/login",
 		requirement: "public",
-		run: (api, _cookies, req) => api.login(body(req))
+		csrf: "signIn",
+		run: (api, _cookies, req) => api.login(body(req), req)
 	},
 	{
 		method: "POST",
 		path: "/refresh",
 		requirement: "public",
-		run: (api, cookies, req) => api.refresh(cookies.resolveRefreshToken(req, req.body))
+		csrf: "none",
+		run: (api, cookies, req) => api.refresh(cookies.resolveRefreshToken(req, req.body), req)
 	},
 	{
 		method: "POST",
 		path: "/logout",
 		requirement: "public",
+		csrf: "none",
 		run: (api, cookies, req) => api.logout({
 			accessToken: cookies.resolveSessionToken(req),
 			refreshToken: cookies.resolveRefreshToken(req, req.body)
@@ -61,44 +102,207 @@ var FLOWS = [
 		method: "POST",
 		path: "/exchange",
 		requirement: "grant",
+		csrf: "grant",
 		run: (api, _cookies, req) => api.exchange(field(req, "provider"), field(req, "token"), req)
 	},
 	{
 		method: "POST",
 		path: "/signup",
 		requirement: "public",
+		csrf: "signIn",
 		run: (api, _cookies, req) => api.signup(body(req))
 	},
 	{
 		method: "POST",
 		path: "/forgot-password",
 		requirement: "public",
+		csrf: "signIn",
 		run: (api, _cookies, req) => api.forgotPassword(field(req, "email"))
 	},
 	{
 		method: "POST",
 		path: "/reset-password",
 		requirement: "public",
+		csrf: "signIn",
 		run: (api, _cookies, req) => api.resetPassword(field(req, "token"), field(req, "password"))
 	},
 	{
 		method: "POST",
 		path: "/validate-account",
 		requirement: "public",
+		csrf: "signIn",
 		run: (api, _cookies, req) => api.validateAccount(field(req, "token"))
 	},
+	{
+		/**
+		* Confirms an address change the account asked for. Public and `signIn`-guarded because the link lands in a
+		* mail client, and the browser that opens it may be one that has never seen this deployment.
+		*/
+		method: "POST",
+		path: "/confirm-email",
+		requirement: "public",
+		csrf: "signIn",
+		run: (api, _cookies, req) => api.confirmEmailChange(field(req, "token"))
+	},
 	{
 		method: "POST",
 		path: "/resend-verification-email",
 		requirement: "public",
-		run: (api, _cookies, req) => api.resendVerification(field(req, "email"))
+		csrf: "signIn",
+		run: (api, _cookies, req) => api.resendVerification(field(req, "email"), field(req, "redirect"))
+	},
+	{
+		method: "POST",
+		path: "/profile",
+		requirement: "actor",
+		run: (api, _cookies, req) => api.updateProfile(req.actor, body(req))
+	},
+	{
+		method: "POST",
+		path: "/password",
+		requirement: "actor",
+		run: (api, _cookies, req) => api.changePassword(req.actor, field(req, "currentPassword"), field(req, "password"))
+	},
+	{
+		method: "POST",
+		path: "/delete-account",
+		requirement: "actor",
+		run: (api, _cookies, req) => api.deleteSelf(req.actor, field(req, "password"))
+	},
+	{
+		method: "GET",
+		path: "/sessions",
+		requirement: "actor",
+		run: (api, _cookies, req) => api.listSessions(req.actor)
+	},
+	{
+		method: "POST",
+		path: "/sessions/revoke-one",
+		requirement: "actor",
+		run: (api, _cookies, req) => api.revokeSession(req.actor, numberField(req, "sessionId"))
+	},
+	{
+		method: "POST",
+		path: "/sessions/revoke-others",
+		requirement: "actor",
+		run: (api, _cookies, req) => api.revokeOtherSessions(req.actor)
+	},
+	{
+		method: "POST",
+		path: "/passwordless/request",
+		requirement: "public",
+		csrf: "signIn",
+		run: (api, _cookies, req) => api.passwordless.request(field(req, "email"), req)
+	},
+	{
+		method: "POST",
+		path: "/passwordless/complete",
+		requirement: "public",
+		csrf: "signIn",
+		run: (api, _cookies, req) => api.passwordless.complete(field(req, "email"), field(req, "code"), req)
+	},
+	{
+		method: "POST",
+		path: "/mfa/complete",
+		requirement: "public",
+		csrf: "signIn",
+		run: (api, _cookies, req) => api.completeMfa(field(req, "mfaToken"), field(req, "code"), req)
+	},
+	{
+		method: "GET",
+		path: "/mfa",
+		requirement: "actor",
+		run: (api, _cookies, req) => api.mfa.status(req.actor)
+	},
+	{
+		method: "POST",
+		path: "/mfa/begin",
+		requirement: "actor",
+		run: (api, _cookies, req) => api.mfa.begin(req.actor)
+	},
+	{
+		method: "POST",
+		path: "/mfa/confirm",
+		requirement: "actor",
+		run: (api, _cookies, req) => api.mfa.confirm(req.actor, field(req, "code"))
+	},
+	{
+		method: "POST",
+		path: "/mfa/disable",
+		requirement: "actor",
+		run: (api, _cookies, req) => api.mfa.disable(req.actor, field(req, "password"))
+	},
+	{
+		method: "GET",
+		path: "/admin/accounts",
+		requirement: "actor",
+		run: (api, _cookies, req) => api.admin.list(req.actor, {
+			search: queryText(req, "search"),
+			status: queryText(req, "status"),
+			limit: queryNumber(req, "limit"),
+			offset: queryNumber(req, "offset")
+		})
+	},
+	{
+		method: "GET",
+		path: "/admin/account",
+		requirement: "actor",
+		run: (api, _cookies, req) => api.admin.get(req.actor, queryNumber(req, "id") ?? NaN)
+	},
+	{
+		method: "POST",
+		path: "/admin/account/status",
+		requirement: "actor",
+		run: (api, _cookies, req) => api.admin.setStatus(req.actor, numberField(req, "userId"), field(req, "status"))
+	},
+	{
+		method: "POST",
+		path: "/admin/account/roles",
+		requirement: "actor",
+		run: (api, _cookies, req) => api.admin.setRoles(req.actor, numberField(req, "userId"), rolesOf(req))
+	},
+	{
+		method: "POST",
+		path: "/admin/account/delete",
+		requirement: "actor",
+		run: (api, _cookies, req) => api.admin.remove(req.actor, numberField(req, "userId"))
+	},
+	{
+		method: "POST",
+		path: "/admin/impersonate",
+		requirement: "actor",
+		run: (api, _cookies, req) => api.admin.impersonate(req.actor, numberField(req, "userId"), req)
 	}
 ];
+/** Whether this request has to present a token, which is `csrf`'s judgement — given what the flow does. */
+var csrfNeeded = (csrf, policy, carrier) => policy === "none" ? false : csrf.required(carrier, policy ? SUBJECT_OF[policy] : "write");
 /** The flows, ready to mount. Which of them actually answer is decided by the API itself — no adapter, no endpoint —
 *  so mounting all of them is correct even for a deployment that offers three. */
-var authRoutes = ({ api, cookies }) => FLOWS.map(({ run, ...route }) => ({
+var authRoutes = ({ api, cookies, csrf }) => FLOWS.map(({ run, csrf: policy, ...route }) => ({
 	...route,
-	handler: (req) => run(api, cookies, req)
+	handler: async (req) => {
+		/**
+		* Checked before the flow runs. The session the token must be bound to is whatever this request carries — an
+		* unbound token satisfies a signed-out caller, which is how signing in is protected when a deployment asks
+		* for that.
+		*/
+		const carrier = {
+			...req,
+			method: route.method
+		};
+		if (csrf && csrfNeeded(csrf, policy, carrier)) {
+			const result = csrf.verify(carrier, cookies.resolveSessionToken(req));
+			if (!result.ok) return {
+				ok: false,
+				status: 403,
+				body: {
+					error: csrfFailureMessage[result.reason],
+					reason: result.reason
+				}
+			};
+		}
+		return run(api, cookies, req);
+	}
 }));
 /**
 * The same flows as authorization rules, for the guard that runs in front of them.
@@ -120,10 +324,31 @@ var authPolicyRules = (prefix = "/auth") => {
 * to do that, and because getting this half wrong — writing the session but not its readable hint, or clearing one of
 * the three on sign-out — is the failure that looks like a session that exists and then does not.
 */
-var applySessionOutcome = (req, res, outcome, cookies) => {
-	if (!outcome.ok) return;
-	if (outcome.session) cookies.write(req, res, outcome.session);
-	if (outcome.endSession) cookies.clear(req, res);
+var applySessionOutcome = (req, res, outcome, cookies, csrf) => {
+	/**
+	* A refusal can still have something to say about the cookies — see `endSession` on the failing outcome. It is
+	* the only thing it may say: nothing is granted from a flow that failed.
+	*/
+	if (!outcome.ok) {
+		if (outcome.endSession) cookies.clear(req, res);
+		return;
+	}
+	if (outcome.session) {
+		cookies.write(req, res, outcome.session);
+		/**
+		* A fresh CSRF token, bound to the session that was just granted.
+		*
+		* Not optional housekeeping: the token a signed-out page was holding is bound to nobody, and every write it
+		* attempts after signing in would be refused as a mismatch. Re-issuing here is what makes signing in and then
+		* doing something work without the client knowing this exists.
+		*/
+		csrf?.write(req, res, csrf.issue(outcome.session.token));
+	}
+	if (outcome.endSession) {
+		cookies.clear(req, res);
+		csrf?.clear(req, res);
+	}
+	if (outcome.csrf !== void 0) csrf?.write(req, res, outcome.csrf);
 };
 //#endregion
 export { applySessionOutcome, authPolicyRules, authRoutes };

package/dist/core/auth/session.d.ts

@@ -22,6 +22,12 @@ export type SessionCookieParams = {
  * refuse one on a single-label host) and lax SameSite, because Secure + SameSite=None over plain http is dropped.
  */
 export declare const isLocalHost: (hostname: string) => boolean;
+/**
+ * The last two labels of the host, so a session established on one sub-domain is carried by its siblings — an app
+ * and the API it talks to are rarely the same host. Local and IP hosts get no domain at all: browsers refuse a
+ * Domain on a single-label host, and one written for an address would never be sent back to it.
+ */
+export declare const registrableDomain: (hostname: string) => string | undefined;
 /**
  * Everything about how a session cookie is written, derived from the request host unless the deployment says
  * otherwise. The defaults are the ones a server on a real domain needs: a cookie shared across sub-domains, and
@@ -38,6 +44,11 @@ export declare const sessionCookieParams: (hostname: string, config?: SSRAuthCoo
  * same question with `credentials: 'include'`.
  */
 export declare const sessionHintValue: (expiresAt: number, refreshExpiresAt?: number) => string;
+/**
+ * Adds to `Set-Cookie` rather than replacing it. A handler may already have written one — clearing an OAuth flow
+ * before granting the session it produced is exactly that — and replacing the header would silently drop it.
+ */
+export declare const appendCookies: (res: CookieSink, cookies: string[]) => void;
 /**
  * Writes a granted session onto the response: the credential itself, the refresh half confined to its own path, and
  * the readable hint. One call, because the three only make sense together — a hint that outlives its session sends

package/dist/core/auth/session.js

@@ -162,4 +162,4 @@ var createSessionCookies = (config) => ({
 	}
 });
 //#endregion
-export { clearFlowCookie, clearSessionCookies, createSessionCookies, isLocalHost, readFlowCookie, readRefreshToken, readSessionToken, sessionCookieParams, sessionHintValue, writeFlowCookie, writeSessionCookies };
+export { appendCookies, clearFlowCookie, clearSessionCookies, createSessionCookies, isLocalHost, readFlowCookie, readRefreshToken, readSessionToken, registrableDomain, sessionCookieParams, sessionHintValue, writeFlowCookie, writeSessionCookies };

package/dist/core/auth/spaceTokens.d.ts

@@ -25,6 +25,18 @@ export interface SpaceTokenAdapters {
         origins?: string[];
         expiresAt?: number | null;
     }) => Promise<void>;
+    /**
+     * Store a NEW credential beside the space's public one. Only the secret scopes are ever created this way — the
+     * public row is created with the space and rotated in place thereafter — so a deployment that issues none may
+     * leave it out and `issueHost` refuses.
+     */
+    create?: (values: {
+        spaceId: number;
+        token: string;
+        scope: SpaceScope;
+        origins: string[];
+        expiresAt: number | null;
+    }) => Promise<SpaceTokenRecord>;
     remove: (id: number) => Promise<void>;
     /**
      * The domain list is two policies at once — where the credential may be presented, and who may frame the space — so
@@ -91,6 +103,29 @@ export declare const createSpaceTokenApi: ({ tokens, adapters }: {
         domains: string[];
         warning: string;
     }>>;
+    /**
+     * Issue a **host** credential: the space's read access for a SERVER that renders it as its own.
+     *
+     * A separate credential rather than letting the public one do it, because the two are protected by different
+     * things and only one of them can be published. A `render` token is safe in a page precisely because it is held
+     * to the origins it declares — a check that only means anything when a browser is the one making the claim. A
+     * server has no origin to state, so admitting the public token without one would make a key lifted from anybody's
+     * published page enough to serve a byte-identical clone of their site. This one is admitted without an origin
+     * because possessing it is itself the proof, which is only true while it stays secret: it is returned once, never
+     * embedded, and revocable on its own row.
+     *
+     * `label` is what the owner will read in the list when deciding which one to revoke — the deployment it was
+     * issued to. It is stored where a render token keeps its domains, since a host credential is bound to none.
+     */
+    issueHost(context: SpaceTokenContext, label: unknown, { expiresAt }?: {
+        expiresAt?: number | null;
+    }): Promise<SpaceTokenOutcome<{
+        id: number;
+        token: string;
+        label: string;
+        expiresAt: number | null;
+        warning: string;
+    }>>;
     readDomains(context: SpaceTokenContext): Promise<SpaceTokenOutcome<{
         domains: string[];
     }>>;
@@ -116,8 +151,9 @@ export declare const createSpaceTokenApi: ({ tokens, adapters }: {
     }>>;
     /**
      * The space's credentials, so a leak can be seen and acted on. Never the secrets themselves: an `agent` grant
-     * writes, and listing it would turn permission to read into a way to obtain it. The public one is published by
-     * construction and has its own endpoint.
+     * writes and a `host` grant serves the space from somebody else's server, so listing either would turn
+     * permission to read into a way to obtain it. The public one is published by construction and has its own
+     * endpoint.
      */
     list(context: SpaceTokenContext): Promise<SpaceTokenOutcome<{
         tokens: SpaceTokenSummary[];

package/dist/core/auth/spaceTokens.js

@@ -1,6 +1,12 @@
 import { normalizeDomain } from "./domains.js";
 //#region src/core/auth/spaceTokens.ts
 var ROTATION_WARNING = "The previous token stopped working. Every site embedding it must be redeployed.";
+/**
+* Said once, at the only moment it can be acted on. A host credential is the space's read access WITHOUT the origin
+* check that makes the public one safe to publish, so what keeps it from being a way to clone the space is that it
+* stays secret — and a caller who does not know it is never shown again will paste it into a page.
+*/
+var HOST_SECRET_WARNING = "Store this now — it is not shown again. Unlike the public token it is NOT safe to embed in a page or commit to a public repository: anyone holding it can serve this space from their own server. Revoke it if it leaks.";
 var DAY_SECONDS = 86400;
 var now = () => Math.floor(Date.now() / 1e3);
 var notFound = {
@@ -81,6 +87,51 @@ var createSpaceTokenApi = ({ tokens, adapters }) => {
 				}
 			};
 		},
+		/**
+		* Issue a **host** credential: the space's read access for a SERVER that renders it as its own.
+		*
+		* A separate credential rather than letting the public one do it, because the two are protected by different
+		* things and only one of them can be published. A `render` token is safe in a page precisely because it is held
+		* to the origins it declares — a check that only means anything when a browser is the one making the claim. A
+		* server has no origin to state, so admitting the public token without one would make a key lifted from anybody's
+		* published page enough to serve a byte-identical clone of their site. This one is admitted without an origin
+		* because possessing it is itself the proof, which is only true while it stays secret: it is returned once, never
+		* embedded, and revocable on its own row.
+		*
+		* `label` is what the owner will read in the list when deciding which one to revoke — the deployment it was
+		* issued to. It is stored where a render token keeps its domains, since a host credential is bound to none.
+		*/
+		async issueHost(context, label, { expiresAt = null } = {}) {
+			if (!adapters.create) return {
+				ok: false,
+				status: 501,
+				body: { error: "This deployment does not issue host tokens" }
+			};
+			if (typeof label !== "string" || label.trim() === "") return {
+				ok: false,
+				status: 400,
+				body: { error: "label is required — name the deployment this credential is for, so it can be revoked" }
+			};
+			const name = label.trim();
+			const token = tokens.generateSpaceToken(context.spaceId, [name], "host", { expiresAt });
+			return {
+				ok: true,
+				status: 201,
+				body: {
+					id: (await adapters.create({
+						spaceId: context.spaceId,
+						token,
+						scope: "host",
+						origins: [name],
+						expiresAt
+					})).id,
+					token,
+					label: name,
+					expiresAt,
+					warning: HOST_SECRET_WARNING
+				}
+			};
+		},
 		async readDomains(context) {
 			const record = await adapters.loadDefault(context.spaceId);
 			return record ? {
@@ -160,8 +211,9 @@ var createSpaceTokenApi = ({ tokens, adapters }) => {
 		},
 		/**
 		* The space's credentials, so a leak can be seen and acted on. Never the secrets themselves: an `agent` grant
-		* writes, and listing it would turn permission to read into a way to obtain it. The public one is published by
-		* construction and has its own endpoint.
+		* writes and a `host` grant serves the space from somebody else's server, so listing either would turn
+		* permission to read into a way to obtain it. The public one is published by construction and has its own
+		* endpoint.
 		*/
 		async list(context) {
 			return {

package/dist/core/auth/throttle.d.ts

@@ -0,0 +1,5 @@
+import { ThrottleAttempt } from './api';
+export declare const createMemoryRateLimit: () => ((attempt: ThrottleAttempt) => Promise<{
+    allowed: boolean;
+    retryAfter?: number;
+}>);

package/dist/core/auth/throttle.js

@@ -0,0 +1,81 @@
+//#region src/core/auth/throttle.ts
+/** Attempts allowed per window, per key, per action. */
+var LIMITS = {
+	/** Credential stuffing is the thing being priced out. Ten wrong passwords in five minutes is already a lot. */
+	login: {
+		attempts: 10,
+		windowSeconds: 300
+	},
+	signup: {
+		attempts: 5,
+		windowSeconds: 3600
+	},
+	/** Mailing flows are throttled by address, or the endpoint is a way to send somebody a hundred emails. */
+	forgotPassword: {
+		attempts: 5,
+		windowSeconds: 3600
+	},
+	/** By token: without this a reset token is guessable by trying, however opaque it is. */
+	resetPassword: {
+		attempts: 10,
+		windowSeconds: 3600
+	},
+	changePassword: {
+		attempts: 10,
+		windowSeconds: 300
+	},
+	exchange: {
+		attempts: 30,
+		windowSeconds: 300
+	},
+	/** Six digits is a million guesses, so the limit is what makes a second factor worth anything. */
+	mfa: {
+		attempts: 5,
+		windowSeconds: 300
+	},
+	passwordless: {
+		attempts: 5,
+		windowSeconds: 900
+	}
+};
+/** Stop the map growing without bound on a server nobody is attacking politely. */
+var SWEEP_EVERY = 1e3;
+var createMemoryRateLimit = () => {
+	const hits = /* @__PURE__ */ new Map();
+	let sinceSweep = 0;
+	const sweep = (now) => {
+		for (const [key, times] of hits) {
+			const action = key.slice(0, key.indexOf(":"));
+			const live = times.filter((at) => at > now - LIMITS[action].windowSeconds);
+			if (live.length === 0) hits.delete(key);
+			else hits.set(key, live);
+		}
+	};
+	return (attempt) => {
+		const { attempts, windowSeconds } = LIMITS[attempt.action];
+		const now = Math.floor(Date.now() / 1e3);
+		const key = `${attempt.action}:${attempt.key}`;
+		/**
+		* It worked, so nothing is being guarded against any more. Without this the counter cannot tell ten failures
+		* from ten sign-ins — the check runs before the password is examined — and an app that signs the same account
+		* in repeatedly would lock it out by succeeding.
+		*/
+		if (attempt.succeeded) {
+			hits.delete(key);
+			return Promise.resolve({ allowed: true });
+		}
+		if (++sinceSweep >= SWEEP_EVERY) {
+			sinceSweep = 0;
+			sweep(now);
+		}
+		const recent = (hits.get(key) ?? []).filter((at) => at > now - windowSeconds);
+		if (recent.length >= attempts) return Promise.resolve({
+			allowed: false,
+			retryAfter: Math.max(1, recent[0] + windowSeconds - now)
+		});
+		hits.set(key, [...recent, now]);
+		return Promise.resolve({ allowed: true });
+	};
+};
+//#endregion
+export { createMemoryRateLimit };

package/dist/core/auth/throttle.test.d.ts

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