@plitzi/sdk-server 0.33.2 → 0.34.0

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

@@ -1,7 +1,8 @@
-import { AccountAdapters, AuthApiConfig } from './api';
+import { AccountAdapters, AuthApiConfig, AuthOutcome } from './api';
 import { AuthPolicy, Requirement } from './authorize';
 import { CredentialCarrier } from './credentials';
 import { IdentityAdapters, IdentityConfig } from './identity';
+import { CookieSink } from './session';
 import { TokenConfig } from './tokens';
 import { SSRAuthCookie, SSRSession, SSRUser } from '@plitzi/sdk-shared';
 /**
@@ -40,6 +41,15 @@ export interface AuthConfig {
     fallback?: Requirement;
     /** Extra rules, applied BEFORE the derived `/auth` ones so a deployment can always widen its own surface. */
     rules?: AuthPolicy['rules'];
+    /**
+     * Cross-site request forgery. **On, and it configures itself** from what is already here: the token secret signs
+     * it, the cookie naming above scopes it, and `identity.platformOrigins` says which sites are this deployment's.
+     *
+     * `false` turns it off, for a deployment that has its own. There is nothing else to say about it, deliberately —
+     * every dial this used to have was one more thing to understand before you could start, and none of them had a
+     * second answer worth having.
+     */
+    csrf?: false;
 }
 /**
  * The whole auth cycle, wired.
@@ -59,18 +69,16 @@ export interface AuthConfig {
  */
 export declare const createAuth: (config: AuthConfig) => {
     tokens: {
-        lifetimes: {
-            access: 86400;
-            refresh: number;
-            agent: number;
-            widget: number;
-        };
-        generateUserToken: (userId: number | string) => string;
+        lifetimes: Record<"session" | "refresh" | "widget" | "agent" | "access" | "mfaChallenge", number>;
+        issuer: string;
+        generateUserToken: (userId: number | string, { actingAs, ttlSeconds }?: import('./tokens').UserTokenOptions) => string;
         generateRefreshToken: (userId: number | string) => string;
         generateWidgetToken: () => string;
+        generateMfaChallenge: (userId: number | string) => string;
         generateSpaceToken: (spaceId: number | string, origins: string[], scope?: import('./tokens').SpaceScope, { expiresAt }?: import('./tokens').SpaceTokenOptions) => string;
         verifyUserToken: (token: string) => import('./tokens').VerifyResult<import('./tokens').UserTokenPayload>;
         verifyRefreshToken: (token: string) => import('./tokens').VerifyResult<import('./tokens').RefreshTokenPayload>;
+        verifyMfaChallenge: (token: string) => import('./tokens').VerifyResult<import('./tokens').MfaChallengePayload>;
         verifyWidgetToken: (token: string) => import('./tokens').VerifyResult<import('./tokens').WidgetTokenPayload>;
         verifySpaceToken: (token: string) => import('./tokens').VerifyResult<import('./tokens').SpaceTokenPayload & {
             spaceId: number;
@@ -95,38 +103,79 @@ export declare const createAuth: (config: AuthConfig) => {
             passwordReset: boolean;
             emailVerification: boolean;
             exchange: boolean;
+            mfa: boolean;
+            passwordless: boolean;
+            profile: boolean;
+            passwordChange: boolean;
+            accountDeletion: boolean;
+            sessionList: boolean;
+            administration: boolean;
+            emailChange: boolean;
+            impersonation: boolean;
+        };
+        describe: () => AuthOutcome;
+        session: (actor?: import('./identity').Actor) => AuthOutcome;
+        login: (credentials: Record<string, unknown>, carrier?: CredentialCarrier) => Promise<AuthOutcome>;
+        completeMfa: (mfaToken: string, code: string, carrier?: CredentialCarrier) => Promise<AuthOutcome>;
+        passwordless: {
+            request: (email: string, carrier?: CredentialCarrier) => Promise<AuthOutcome>;
+            complete: (email: string, code: string, carrier?: CredentialCarrier) => Promise<AuthOutcome>;
+        };
+        mfa: {
+            status: (actor: import('./identity').Actor | undefined) => Promise<AuthOutcome>;
+            begin: (actor: import('./identity').Actor | undefined) => Promise<AuthOutcome>;
+            confirm: (actor: import('./identity').Actor | undefined, code: string) => Promise<AuthOutcome>;
+            disable: (actor: import('./identity').Actor | undefined, password?: string) => Promise<AuthOutcome>;
         };
-        describe: () => import('./api').AuthOutcome;
-        session: (actor?: import('./identity').Actor) => import('./api').AuthOutcome;
-        login: (credentials: Record<string, unknown>) => Promise<import('./api').AuthOutcome>;
-        refresh: (refreshToken?: string) => Promise<import('./api').AuthOutcome>;
+        refresh: (refreshToken?: string, carrier?: CredentialCarrier) => Promise<AuthOutcome>;
         logout: (credentials: {
             accessToken?: string;
             refreshToken?: string;
-        }) => Promise<import('./api').AuthOutcome>;
-        revokeSessions: (userId?: number) => Promise<import('./api').AuthOutcome>;
-        exchange: (provider: string, token: string, carrier: CredentialCarrier) => Promise<import('./api').AuthOutcome>;
-        signup: (fields: Record<string, unknown>) => Promise<import('./api').AuthOutcome>;
-        forgotPassword: (email: string) => Promise<import('./api').AuthOutcome>;
-        resetPassword: (token: string, password: string) => Promise<import('./api').AuthOutcome>;
-        validateAccount: (token: string) => Promise<import('./api').AuthOutcome>;
-        resendVerification: (email: string) => Promise<import('./api').AuthOutcome>;
-        issueSession: (userId: number) => Promise<SSRSession>;
+        }) => Promise<AuthOutcome>;
+        revokeSessions: (userId?: number) => Promise<AuthOutcome>;
+        exchange: (provider: string, token: string, carrier: CredentialCarrier) => Promise<AuthOutcome>;
+        exchangeAccount: (provider: string, token: string, carrier: CredentialCarrier) => Promise<import('./api').ExchangeResult>;
+        signup: (fields: Record<string, unknown>) => Promise<AuthOutcome>;
+        forgotPassword: (email: string) => Promise<AuthOutcome>;
+        resetPassword: (token: string, password: string) => Promise<AuthOutcome>;
+        validateAccount: (token: string) => Promise<AuthOutcome>;
+        resendVerification: (email: string, redirect?: string) => Promise<AuthOutcome>;
+        updateProfile: (actor: import('./identity').Actor | undefined, fields: Record<string, unknown>) => Promise<AuthOutcome>;
+        confirmEmailChange: (token: string) => Promise<AuthOutcome>;
+        changePassword: (actor: import('./identity').Actor | undefined, currentPassword: string, newPassword: string) => Promise<AuthOutcome>;
+        deleteSelf: (actor: import('./identity').Actor | undefined, password?: string) => Promise<AuthOutcome>;
+        listSessions: (actor: import('./identity').Actor | undefined) => Promise<AuthOutcome>;
+        revokeSession: (actor: import('./identity').Actor | undefined, sessionId: number) => Promise<AuthOutcome>;
+        revokeOtherSessions: (actor: import('./identity').Actor | undefined) => Promise<AuthOutcome>;
+        admin: {
+            list: (actor: import('./identity').Actor | undefined, query: import('./api').AccountQuery) => Promise<AuthOutcome>;
+            get: (actor: import('./identity').Actor | undefined, userId: number) => Promise<AuthOutcome>;
+            setStatus: (actor: import('./identity').Actor | undefined, userId: number, status: import('./api').AccountStatus) => Promise<AuthOutcome>;
+            setRoles: (actor: import('./identity').Actor | undefined, userId: number, roles: unknown) => Promise<AuthOutcome>;
+            remove: (actor: import('./identity').Actor | undefined, userId: number) => Promise<AuthOutcome>;
+            impersonate: (actor: import('./identity').Actor | undefined, userId: number, carrier?: CredentialCarrier) => Promise<AuthOutcome>;
+        };
+        issueCsrf: (sessionToken?: string) => AuthOutcome;
+        issueSession: (userId: number, context?: import('./api').SessionContext, options?: {
+            actingAs?: number;
+            ttlSeconds?: number;
+            renewable?: boolean;
+        }) => Promise<SSRSession>;
         resolveActor: (carrier: CredentialCarrier) => Promise<import('./identity').ActorResult>;
     };
     cookies: {
         write: (req: {
             hostname: string;
-        }, res: import('./session').CookieSink, session: SSRSession) => void;
+        }, res: CookieSink, session: SSRSession) => void;
         clear: (req: {
             hostname: string;
-        }, res: import('./session').CookieSink) => void;
+        }, res: CookieSink) => void;
         writeFlow: (req: {
             hostname: string;
-        }, res: import('./session').CookieSink, value: string, ttlSeconds: number) => void;
+        }, res: CookieSink, value: string, ttlSeconds: number) => void;
         clearFlow: (req: {
             hostname: string;
-        }, res: import('./session').CookieSink) => void;
+        }, res: CookieSink) => void;
         readFlow: (req: import('./session').CookieCarrier) => string | undefined;
         resolveSessionToken: (req: import('./session').CookieCarrier) => string | undefined;
         resolveRefreshToken: (req: import('./session').CookieCarrier, body?: unknown) => string | undefined;
@@ -137,28 +186,84 @@ export declare const createAuth: (config: AuthConfig) => {
     basePath: string;
     /** The naming this was built with, so a page server takes it from here instead of being told a second time. */
     cookieConfig: SSRAuthCookie | undefined;
+    /**
+     * Cross-site request forgery: issuing tokens, writing the readable cookie, and the check. `undefined` when the
+     * deployment turned it off. The `/auth` routes below already enforce it.
+     */
+    csrf: {
+        issue: (sessionToken?: string) => string;
+        cookieName: (hostname: string) => string;
+        headerName: string;
+        write: (req: {
+            hostname: string;
+        }, res: CookieSink, token: string) => void;
+        clear: (req: {
+            hostname: string;
+        }, res: CookieSink) => void;
+        read: (carrier: import('./csrf').CsrfCarrier) => string | undefined;
+        required: (carrier: import('./csrf').CsrfCarrier, subject?: import('./csrf').CsrfSubject) => boolean;
+        verify: (carrier: import('./csrf').CsrfCarrier, sessionToken?: string) => import('./csrf').CsrfResult;
+    } | undefined;
     /** The `/auth` flows as descriptors, ready for whatever serves HTTP here. */
     routes: import('./routes').AuthRoute[];
     /** May this request proceed, and as whom. */
     authorize: (carrier: CredentialCarrier, path: string) => Promise<import('./authorize').AuthorizeResult>;
-    /** Does what a flow's answer says about the session cookies. */
+    /**
+     * Does what a flow's answer says about the cookies — the session, and the CSRF token that has to be re-issued
+     * alongside it. Bound to this deployment's `csrf`, so a caller cannot forget to pass it.
+     */
     applySession: (req: {
         hostname: string;
-    }, res: import('./session').CookieSink, outcome: import('./api').AuthOutcome, cookies: import('./session').SessionCookies) => void;
+    }, res: CookieSink, outcome: AuthOutcome) => void;
     /** Both halves of a space permission: a global capability, and membership of that space. */
     can: (actor: import('./identity').Actor, spaceId: number, permission: string) => Promise<boolean>;
     /**
-     * The three adapters a page server asks for, already answered. Spread these into `createServer`'s `adapters`
+     * WHO a page request carries, and nothing about signing anyone in or out.
+     *
+     * This is the set a deployment wants when its renderer and its sign-in live in different processes — a page
+     * server that must know who is looking at it, while the `/auth` flows are served by an API tier next to it.
+     * That shape had no name, so a deployment expressed it by reaching into `ssrAdapters` and lifting two keys out
+     * by hand: correct until a third identity adapter appears, which it then silently does not get.
+     *
+     * `exchangeCredential` belongs here rather than with the flows: turning a credential a browser already holds
+     * into a session is a question about identity, and it is the one the page server itself answers.
+     */
+    ssrIdentityAdapters: {
+        exchangeCredential?: ((provider: string, token: string, req: CredentialCarrier) => Promise<{
+            ok: true;
+            session: SSRSession;
+            user?: SSRUser;
+        } | {
+            ok: false;
+            error: string;
+            status?: number;
+            reason?: string;
+        }>) | undefined;
+        getUser: (req: CredentialCarrier) => Promise<SSRUser | undefined>;
+    };
+    /**
+     * Every adapter a page server asks for, already answered. Spread these into `createServer`'s `adapters`
      * and a rendered page knows who is looking at it, `POST /auth/login` signs them in, `POST /auth/logout` signs
-     * them out, and the cookies are written and cleared by the same code that reads them back.
+     * them out, and the cookies are written and cleared by the same code that reads them back. A renderer that
+     * serves no login of its own wants {@link ssrIdentityAdapters} instead.
      *
      * They exist because the page server speaks in sessions and users while the flows above answer in outcomes,
      * and translating between the two is a step with exactly one right answer — which makes it the server's, not
      * something for every deployment to rediscover.
      */
     ssrAdapters: {
-        authenticate: (credentials: Record<string, string>) => Promise<SSRSession | undefined>;
+        exchangeCredential?: ((provider: string, token: string, req: CredentialCarrier) => Promise<{
+            ok: true;
+            session: SSRSession;
+            user?: SSRUser;
+        } | {
+            ok: false;
+            error: string;
+            status?: number;
+            reason?: string;
+        }>) | undefined;
         getUser: (req: CredentialCarrier) => Promise<SSRUser | undefined>;
+        authenticate: (credentials: Record<string, string>) => Promise<SSRSession | undefined>;
         endSession: (req: CredentialCarrier) => Promise<void>;
     };
 };

package/dist/core/auth/createAuth.js

@@ -1,9 +1,10 @@
 import { createSessionCookies, sessionCookieParams } from "./session.js";
+import { createAuthorizer } from "./authorize.js";
 import { createTokens } from "./tokens.js";
+import { createAuthApi } from "./api.js";
 import { createCarriers, presentedOrigin } from "./credentials.js";
+import { createCsrf } from "./csrf.js";
 import { createIdentity } from "./identity.js";
-import { createAuthorizer } from "./authorize.js";
-import { createAuthApi } from "./api.js";
 import { applySessionOutcome, authPolicyRules, authRoutes } from "./routes.js";
 //#region src/core/auth/createAuth.ts
 /**
@@ -33,17 +34,80 @@ var createAuth = (config) => {
 		adapters: config.adapters,
 		config: config.identity
 	});
+	/**
+	* The hosts this deployment already declared are the ones its own pages are served from, which is exactly the
+	* question the sign-in check asks. Taken from there rather than asked for again: two lists that have to agree
+	* are two lists that will not.
+	*/
+	const csrf = config.csrf === false ? void 0 : createCsrf({
+		secret: config.tokens.secret,
+		cookie: config.cookie,
+		allowedOrigins: config.identity?.platformOrigins
+	});
 	const api = createAuthApi({
 		tokens,
 		identity,
 		adapters: config.adapters,
-		config: config.api
+		config: {
+			...config.api,
+			...csrf ? { csrf } : {}
+		}
 	});
 	const basePath = config.basePath ?? "/auth";
 	const policy = {
 		rules: [...config.rules ?? [], ...authPolicyRules(basePath)],
 		fallback: config.fallback ?? "actor"
 	};
+	/**
+	* Identity as a page server sees it, kept apart from the sign-in flows so a deployment can take one without the
+	* other — see the `ssrIdentityAdapters` note below.
+	*
+	* `exchangeCredential` is omitted entirely when no exchange adapter was supplied. A key that is present but inert
+	* would make the page server advertise `sessionExchangeUrl` for a flow that answers 404 — and a browser-side
+	* identity provider handing its credential to an endpoint that is not there fails as a hydration mismatch, which
+	* is nowhere near where the mistake was made.
+	*/
+	const ssrIdentityAdapters = {
+		getUser: async (req) => {
+			const resolved = await identity.resolveActor(req);
+			if (!resolved.ok) return;
+			const { id, username, email, verified, permissions, roles, token, expiresAt } = resolved.actor;
+			return {
+				id,
+				username,
+				email,
+				verified,
+				permissions,
+				roles,
+				token,
+				expiresAt
+			};
+		},
+		...api.capabilities.exchange ? { exchangeCredential: async (provider, token, req) => {
+			const result = await api.exchangeAccount(provider, token, req);
+			if (!result.ok) return {
+				ok: false,
+				error: result.error,
+				status: result.status,
+				reason: result.reason
+			};
+			const { account, access, session } = result;
+			return {
+				ok: true,
+				session,
+				user: {
+					token: session.token,
+					expiresAt: session.expiresAt,
+					id: account.id,
+					username: account.username,
+					email: account.email,
+					verified: account.verified,
+					roles: access.roles,
+					permissions: access.permissions
+				}
+			};
+		} } : {}
+	};
 	return {
 		tokens,
 		identity,
@@ -55,21 +119,43 @@ var createAuth = (config) => {
 		basePath,
 		/** The naming this was built with, so a page server takes it from here instead of being told a second time. */
 		cookieConfig: config.cookie,
+		/**
+		* Cross-site request forgery: issuing tokens, writing the readable cookie, and the check. `undefined` when the
+		* deployment turned it off. The `/auth` routes below already enforce it.
+		*/
+		csrf,
 		/** The `/auth` flows as descriptors, ready for whatever serves HTTP here. */
 		routes: authRoutes({
 			api,
-			cookies
+			cookies,
+			csrf
 		}),
 		/** May this request proceed, and as whom. */
 		authorize: createAuthorizer(identity, policy),
-		/** Does what a flow's answer says about the session cookies. */
-		applySession: applySessionOutcome,
+		/**
+		* Does what a flow's answer says about the cookies — the session, and the CSRF token that has to be re-issued
+		* alongside it. Bound to this deployment's `csrf`, so a caller cannot forget to pass it.
+		*/
+		applySession: (req, res, outcome) => applySessionOutcome(req, res, outcome, cookies, csrf),
 		/** Both halves of a space permission: a global capability, and membership of that space. */
 		can: identity.can,
 		/**
-		* The three adapters a page server asks for, already answered. Spread these into `createServer`'s `adapters`
+		* WHO a page request carries, and nothing about signing anyone in or out.
+		*
+		* This is the set a deployment wants when its renderer and its sign-in live in different processes — a page
+		* server that must know who is looking at it, while the `/auth` flows are served by an API tier next to it.
+		* That shape had no name, so a deployment expressed it by reaching into `ssrAdapters` and lifting two keys out
+		* by hand: correct until a third identity adapter appears, which it then silently does not get.
+		*
+		* `exchangeCredential` belongs here rather than with the flows: turning a credential a browser already holds
+		* into a session is a question about identity, and it is the one the page server itself answers.
+		*/
+		ssrIdentityAdapters,
+		/**
+		* Every adapter a page server asks for, already answered. Spread these into `createServer`'s `adapters`
 		* and a rendered page knows who is looking at it, `POST /auth/login` signs them in, `POST /auth/logout` signs
-		* them out, and the cookies are written and cleared by the same code that reads them back.
+		* them out, and the cookies are written and cleared by the same code that reads them back. A renderer that
+		* serves no login of its own wants {@link ssrIdentityAdapters} instead.
 		*
 		* They exist because the page server speaks in sessions and users while the flows above answer in outcomes,
 		* and translating between the two is a step with exactly one right answer — which makes it the server's, not
@@ -80,24 +166,10 @@ var createAuth = (config) => {
 				const outcome = await api.login(credentials);
 				return outcome.ok ? outcome.session : void 0;
 			},
-			getUser: async (req) => {
-				const resolved = await identity.resolveActor(req);
-				if (!resolved.ok) return;
-				const { id, username, email, verified, permissions, roles, token, expiresAt } = resolved.actor;
-				return {
-					id,
-					username,
-					email,
-					verified,
-					permissions,
-					roles,
-					token,
-					expiresAt
-				};
-			},
 			endSession: async (req) => {
 				await api.logout({ accessToken: cookies.resolveSessionToken(req) });
-			}
+			},
+			...ssrIdentityAdapters
 		}
 	};
 };

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

@@ -22,8 +22,14 @@ export declare const createCarriers: (sessionCookieName: (hostname: string) => s
     spaceTokenCandidates: (carrier: CredentialCarrier) => string[];
 };
 /**
- * The origin the caller claims to be presenting from — the `Origin` header, falling back to the host it addressed.
- * Distinct from this server's own origin (see `requestOrigin` in the request parser): this one is the claim a
- * credential's domain binding is checked against.
+ * The origin the caller claims to be presenting from — the `Origin` header, and nothing else. Distinct from this
+ * server's own origin (see `requestOrigin` in the request parser): this one is the claim a credential's domain
+ * binding is checked against.
+ *
+ * Empty when the header is absent, which is a fact the caller downstream has to be able to see. This used to fall
+ * back to `carrier.hostname`, and that fallback could only ever deny: a hostname carries no scheme, so it matched no
+ * entry in any origins list, and every server-to-server caller — a self-hosted deployment reading its own space
+ * through `createCloudAdapters`, most of all — was refused with `origin-not-allowed` while the branch written to
+ * handle a missing Origin was unreachable.
  */
 export declare const presentedOrigin: (carrier: CredentialCarrier) => string;

package/dist/core/auth/credentials.js

@@ -39,10 +39,16 @@ var createCarriers = (sessionCookieName) => ({
 	}
 });
 /**
-* The origin the caller claims to be presenting from — the `Origin` header, falling back to the host it addressed.
-* Distinct from this server's own origin (see `requestOrigin` in the request parser): this one is the claim a
-* credential's domain binding is checked against.
+* The origin the caller claims to be presenting from — the `Origin` header, and nothing else. Distinct from this
+* server's own origin (see `requestOrigin` in the request parser): this one is the claim a credential's domain
+* binding is checked against.
+*
+* Empty when the header is absent, which is a fact the caller downstream has to be able to see. This used to fall
+* back to `carrier.hostname`, and that fallback could only ever deny: a hostname carries no scheme, so it matched no
+* entry in any origins list, and every server-to-server caller — a self-hosted deployment reading its own space
+* through `createCloudAdapters`, most of all — was refused with `origin-not-allowed` while the branch written to
+* handle a missing Origin was unreachable.
 */
-var presentedOrigin = (carrier) => headerValue(carrier.headers.origin) || carrier.hostname;
+var presentedOrigin = (carrier) => headerValue(carrier.headers.origin);
 //#endregion
 export { createCarriers, presentedOrigin };

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

@@ -0,0 +1,89 @@
+import { CookieSink } from './session';
+import { SSRAuthCookie } from '@plitzi/sdk-shared';
+export interface CsrfConfig {
+    /** Signs the tokens. `createAuth` uses the token secret, so a deployment never states this either. */
+    secret: string;
+    /** Naming and scope for the cookie, so it lands beside the session one. */
+    cookie?: SSRAuthCookie;
+    /**
+     * Origins that count as this deployment's own, beyond the request's own site.
+     *
+     * What it decides is which cross-site page may hand out a session — see `foreign` below. `createAuth` fills it
+     * from `identity.platformOrigins`, so a deployment that already declared its hosts has said this too, and this
+     * whole module ends up configuring itself.
+     */
+    allowedOrigins?: string[] | ((origin: string) => boolean);
+}
+/**
+ * What kind of flow a request is reaching, which is what decides when a token is demanded.
+ *
+ * - **`write`** — an action taken as somebody. Guarded whenever a cookie could have authenticated it.
+ * - **`signIn`** — hands out a session. There is no cookie to protect yet, and the attack is different: another
+ *   site signing a visitor into an account IT controls, so that what they do next is recorded against it. Guarded
+ *   by where the request came from, since that is what separates the attack from every legitimate sign-in.
+ * - **`delegated`** — also hands out a session, but the flow checks the caller's origin itself against something
+ *   narrower than any list here: `/auth/exchange` acts for a space and is refused unless the origin is one that
+ *   space declared. Applying the check below on top would refuse every legitimate embed.
+ */
+export type CsrfSubject = 'write' | 'signIn' | 'delegated';
+export type CsrfFailure = 'missing' | 'malformed' | 'expired' | 'mismatch';
+export declare const csrfFailureMessage: Record<CsrfFailure, string>;
+export type CsrfResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: CsrfFailure;
+};
+/** What a request has to look like for this to read it. Satisfied by Express, `node:http` plus a parse, and ours. */
+export interface CsrfCarrier {
+    method?: string;
+    headers: Record<string, string | string[] | undefined>;
+    hostname: string;
+    cookies?: Record<string, string>;
+    body?: unknown;
+}
+export declare const createCsrf: (config: CsrfConfig) => {
+    issue: (sessionToken?: string) => string;
+    /** The name the cookie lands under, for a client that reads it by hand. */
+    cookieName: (hostname: string) => string;
+    /** The header the echo is expected in, published by `GET /auth/csrf` so a client is never told it twice. */
+    headerName: string;
+    /** Readable on purpose: `httpOnly` would make it impossible for a page to echo it back. It is not a credential. */
+    write: (req: {
+        hostname: string;
+    }, res: CookieSink, token: string) => void;
+    /**
+     * Drops the cookie, on the same attributes it was written with — anything else leaves the original in place and
+     * adds a second one the browser then has to choose between.
+     *
+     * Called when a session ends. Nothing depended on it going: the token is signed over the session it belongs to,
+     * so once that session is revoked it verifies against nothing, and a write is only ever asked for a token when a
+     * session cookie is present. But a logout that leaves a cookie behind is one somebody has to reason about to
+     * dismiss, and on a shared browser "signed out" should mean nothing of the session is still sitting there.
+     */
+    clear: (req: {
+        hostname: string;
+    }, res: CookieSink) => void;
+    read: (carrier: CsrfCarrier) => string | undefined;
+    /**
+     * Does this request need a token at all?
+     *
+     * Two requests can never be forged into, whatever they are reaching, and neither is ever asked:
+     *
+     * - a **safe method**, which changes nothing;
+     * - one presenting **`Authorization: Bearer`** — a cross-origin page cannot set that header without a
+     *   preflight this server would have to allow, so requiring a token would break every API client to protect
+     *   nobody.
+     *
+     * After that it depends on what the flow does, which is what `subject` says — an action taken as somebody is
+     * protected by the session cookie's presence, a sign-in by where the request came from. See {@link CsrfSubject}.
+     */
+    required: (carrier: CsrfCarrier, subject?: CsrfSubject) => boolean;
+    /**
+     * The whole check. The echoed token must verify against the session the request carries, and — when the
+     * cookie is also present — match it. The second half costs nothing and blocks a token that leaked somewhere
+     * the cookie did not.
+     */
+    verify: (carrier: CsrfCarrier, sessionToken?: string) => CsrfResult;
+};
+export type Csrf = ReturnType<typeof createCsrf>;