@plitzi/sdk-server 0.32.24 → 0.33.0

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

@@ -0,0 +1,50 @@
+import { AuthApi, AuthOutcome } from './api';
+import { AuthPolicy, Requirement } from './authorize';
+import { CredentialCarrier } from './credentials';
+import { Actor } from './identity';
+import { CookieSink, SessionCookies } from './session';
+/**
+ * A request, as the auth flows need to read one. Everything here is either already on a `node:http` request or was
+ * put there by the host: the parsed body, and the actor the guard resolved. No framework appears in it, because the
+ * flows below have no opinion about how the request arrived.
+ */
+export interface AuthRequest extends CredentialCarrier {
+    body?: unknown;
+    /** Whoever `createAuthorizer` resolved for this request, when it resolved anyone. */
+    actor?: Actor;
+}
+export interface AuthRoute {
+    method: 'GET' | 'POST';
+    /** Relative to wherever the host mounts them — `/auth`, conventionally. */
+    path: string;
+    /**
+     * What a caller must present. Carried on the descriptor because it is a property OF the flow, not of the host: a
+     * sign-in endpoint is public because signing in is what a stranger does, and `/auth/refresh` and `/auth/logout` are
+     * public because they authenticate themselves with the refresh credential — a session whose access token has
+     * lapsed must still be able to renew or end itself, or a live refresh token could never be revoked.
+     */
+    requirement: Requirement;
+    handler: (req: AuthRequest) => Promise<AuthOutcome> | AuthOutcome;
+}
+/** 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. */
+export declare const authRoutes: ({ api, cookies }: {
+    api: AuthApi;
+    cookies: SessionCookies;
+}) => AuthRoute[];
+/**
+ * The same flows as authorization rules, for the guard that runs in front of them.
+ *
+ * Derived rather than restated, because a host keeping its own list has to remember to edit it every time this table
+ * changes. Forgetting in one direction hides a sign-in endpoint behind the session it exists to create; forgetting in
+ * the other opens one that was never meant to be reachable. `prefix` is wherever the host mounted them.
+ */
+export declare const authPolicyRules: (prefix?: string) => AuthPolicy["rules"];
+/**
+ * Does what an outcome says about the session cookies. Separate from sending the body because only the host knows how
+ * 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.
+ */
+export declare const applySessionOutcome: (req: {
+    hostname: string;
+}, res: CookieSink, outcome: AuthOutcome, cookies: SessionCookies) => void;

package/dist/core/auth/routes.js

@@ -0,0 +1,129 @@
+//#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]`. */
+var field = (req, name) => {
+	const value = body(req)[name];
+	return typeof value === "string" ? value : "";
+};
+/**
+* The whole `/auth` surface as data: which method and path each flow answers on, what a caller must present, and what
+* to call.
+*
+* A table rather than a router, because this server does not know what the host is — a deployment may serve it from
+* Express, from Fastify, or from a bare `node:http` switch. Mapping twelve descriptors onto any of those is a handful
+* of lines; getting the paths, the methods and the credential precedence subtly wrong is a session that silently does
+* not work.
+*
+* One table, read twice — once for the handlers and once for the guard in front of them — so the two can never
+* disagree about which of these a stranger may reach.
+*/
+var FLOWS = [
+	{
+		method: "GET",
+		path: "/capabilities",
+		requirement: "public",
+		run: (api) => api.describe()
+	},
+	{
+		method: "GET",
+		path: "/session",
+		requirement: "actor",
+		run: (api, _cookies, req) => api.session(req.actor)
+	},
+	{
+		method: "POST",
+		path: "/login",
+		requirement: "public",
+		run: (api, _cookies, req) => api.login(body(req))
+	},
+	{
+		method: "POST",
+		path: "/refresh",
+		requirement: "public",
+		run: (api, cookies, req) => api.refresh(cookies.resolveRefreshToken(req, req.body))
+	},
+	{
+		method: "POST",
+		path: "/logout",
+		requirement: "public",
+		run: (api, cookies, req) => api.logout({
+			accessToken: cookies.resolveSessionToken(req),
+			refreshToken: cookies.resolveRefreshToken(req, req.body)
+		})
+	},
+	{
+		method: "POST",
+		path: "/sessions/revoke",
+		requirement: "actor",
+		run: (api, _cookies, req) => api.revokeSessions(req.actor?.id)
+	},
+	{
+		method: "POST",
+		path: "/exchange",
+		requirement: "grant",
+		run: (api, _cookies, req) => api.exchange(field(req, "provider"), field(req, "token"), req)
+	},
+	{
+		method: "POST",
+		path: "/signup",
+		requirement: "public",
+		run: (api, _cookies, req) => api.signup(body(req))
+	},
+	{
+		method: "POST",
+		path: "/forgot-password",
+		requirement: "public",
+		run: (api, _cookies, req) => api.forgotPassword(field(req, "email"))
+	},
+	{
+		method: "POST",
+		path: "/reset-password",
+		requirement: "public",
+		run: (api, _cookies, req) => api.resetPassword(field(req, "token"), field(req, "password"))
+	},
+	{
+		method: "POST",
+		path: "/validate-account",
+		requirement: "public",
+		run: (api, _cookies, req) => api.validateAccount(field(req, "token"))
+	},
+	{
+		method: "POST",
+		path: "/resend-verification-email",
+		requirement: "public",
+		run: (api, _cookies, req) => api.resendVerification(field(req, "email"))
+	}
+];
+/** 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 }) => ({
+	...route,
+	handler: (req) => run(api, cookies, req)
+}));
+/**
+* The same flows as authorization rules, for the guard that runs in front of them.
+*
+* Derived rather than restated, because a host keeping its own list has to remember to edit it every time this table
+* changes. Forgetting in one direction hides a sign-in endpoint behind the session it exists to create; forgetting in
+* the other opens one that was never meant to be reachable. `prefix` is wherever the host mounted them.
+*/
+var authPolicyRules = (prefix = "/auth") => {
+	const byRequirement = /* @__PURE__ */ new Map();
+	for (const { path, requirement } of FLOWS) byRequirement.set(requirement, [...byRequirement.get(requirement) ?? [], `${prefix}${path}`]);
+	return [...byRequirement].map(([requirement, paths]) => ({
+		match: paths,
+		requirement
+	}));
+};
+/**
+* Does what an outcome says about the session cookies. Separate from sending the body because only the host knows how
+* 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);
+};
+//#endregion
+export { applySessionOutcome, authPolicyRules, authRoutes };

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

@@ -0,0 +1,128 @@
+import { SSRAuthCookie, SSRRequest, SSRSession } from '@plitzi/sdk-shared';
+/**
+ * Anything that can carry `Set-Cookie`. Express `Response` and this server's own helpers both satisfy it, which is
+ * what lets one writer serve both — a deployment that wrote its own would drift from the one SSR uses, and a session
+ * established on one side would be invisible to the other.
+ */
+export interface CookieSink {
+    setHeader: (name: string, value: string | string[]) => void;
+    getHeader?: (name: string) => string | string[] | number | undefined;
+    headers?: Record<string, string | string[] | number | undefined>;
+}
+export type SessionCookieParams = {
+    name: string;
+    domain?: string;
+    secure: boolean;
+    sameSite: 'lax' | 'none';
+    refreshPath: string;
+    hintSuffix: string;
+};
+/**
+ * Whether the host is a loopback name or a `.localhost` sibling. Local hosts get no Domain on their cookies (browsers
+ * 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;
+/**
+ * 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
+ * SameSite=None + Secure so it survives the app and the API being different hosts. A local server gets the
+ * opposite, because Secure + SameSite=None over plain http is dropped by every browser.
+ */
+export declare const sessionCookieParams: (hostname: string, config?: SSRAuthCookie) => SessionCookieParams;
+/**
+ * The value of the readable companion cookie: `<access expiry>.<refresh expiry>`, unix seconds, refresh optional.
+ *
+ * It exists because the session cookie is httpOnly — correctly — which leaves a page unable to tell whether the
+ * browser holds a session at all. Answering that costs a request per page load otherwise, and the answer is usually
+ * "nobody is signed in". This carries no credential: any script that can read it could have asked the backend the
+ * same question with `credentials: 'include'`.
+ */
+export declare const sessionHintValue: (expiresAt: number, refreshExpiresAt?: number) => string;
+/**
+ * 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
+ * clients to renew something that is gone, and one that dies early signs out a live session.
+ */
+export declare const writeSessionCookies: (req: {
+    hostname: string;
+}, res: CookieSink, session: SSRSession, config?: SSRAuthCookie) => void;
+/** Ends the session in this browser. Every cookie the grant wrote is cleared, the readable one included. */
+export declare const clearSessionCookies: (req: {
+    hostname: string;
+}, res: CookieSink, config?: SSRAuthCookie) => void;
+/**
+ * The cookie a social sign-in leaves behind while the browser is away at the provider. Same family, same policy, so
+ * it is written here rather than by whoever happens to be driving the flow. Path `/` because a deployment may serve
+ * its API under a prefix, and the callback would then miss a cookie scoped to `/auth`.
+ */
+export declare const writeFlowCookie: (req: {
+    hostname: string;
+}, res: CookieSink, value: string, ttlSeconds: number, config?: SSRAuthCookie) => void;
+export declare const clearFlowCookie: (req: {
+    hostname: string;
+}, res: CookieSink, config?: SSRAuthCookie) => void;
+/** The value that flow cookie carries, for the callback leg. */
+export declare const readFlowCookie: (req: SSRRequest | {
+    headers: {
+        cookie?: string;
+    };
+    hostname: string;
+}, config?: SSRAuthCookie) => string | undefined;
+/** The session credential this request carries, for an adapter that resolves identity from it. */
+export declare const readSessionToken: (req: SSRRequest | {
+    headers: {
+        cookie?: string;
+    };
+    hostname: string;
+}, config?: SSRAuthCookie) => string | undefined;
+/** The renewal credential, which rides in its own cookie confined to the refresh path. */
+export declare const readRefreshToken: (req: SSRRequest | {
+    headers: {
+        cookie?: string;
+    };
+    hostname: string;
+}, config?: SSRAuthCookie) => string | undefined;
+/** Anything a credential can be read off: this server's own request, an Express one, a bare `node:http` one. */
+export type CookieCarrier = SSRRequest | {
+    headers: {
+        cookie?: string;
+        authorization?: string;
+    };
+    hostname: string;
+};
+/**
+ * The cookie side of a session with this deployment's naming already bound in.
+ *
+ * The functions above take the naming on every call, which is right for the server's own internals and tedious for a
+ * host that answers dozens of requests with the same configuration. Nothing here knows about any framework: it takes
+ * a request that can be read and something that can carry `Set-Cookie`, which is as true of `node:http` as it is of
+ * Express — a self-hoster running neither still gets the whole cycle.
+ */
+export declare const createSessionCookies: (config?: SSRAuthCookie) => {
+    write: (req: {
+        hostname: string;
+    }, res: CookieSink, session: SSRSession) => void;
+    clear: (req: {
+        hostname: string;
+    }, res: CookieSink) => void;
+    /** Holds a social sign-in between its two legs: the CSRF nonce and the PKCE verifier. */
+    writeFlow: (req: {
+        hostname: string;
+    }, res: CookieSink, value: string, ttlSeconds: number) => void;
+    clearFlow: (req: {
+        hostname: string;
+    }, res: CookieSink) => void;
+    readFlow: (req: CookieCarrier) => string | undefined;
+    /**
+     * The session credential from `Authorization: Bearer` or the cookie, so one endpoint serves a bearer client and a
+     * browser. The header wins: a caller that went to the trouble of presenting one means it.
+     */
+    resolveSessionToken: (req: CookieCarrier) => string | undefined;
+    /**
+     * The renewal credential from the request body (`refresh_token`, for API clients) or its cookie (for browsers).
+     * The body wins when both are present, mirroring how the session credential is resolved. `body` is whatever the
+     * host parsed — this only reads one field off it, so a host that parses JSON its own way still fits.
+     */
+    resolveRefreshToken: (req: CookieCarrier, body?: unknown) => string | undefined;
+};
+export type SessionCookies = ReturnType<typeof createSessionCookies>;

package/dist/core/auth/session.js

@@ -0,0 +1,165 @@
+import { isIP } from "node:net";
+//#region src/core/auth/session.ts
+var LOCAL_HOSTS = [
+	"localhost",
+	"127.0.0.1",
+	"::1"
+];
+/**
+* Whether the host is a loopback name or a `.localhost` sibling. Local hosts get no Domain on their cookies (browsers
+* refuse one on a single-label host) and lax SameSite, because Secure + SameSite=None over plain http is dropped.
+*/
+var isLocalHost = (hostname) => LOCAL_HOSTS.includes(hostname) || hostname.endsWith(".localhost");
+var isIpAddress = (hostname) => isIP(hostname) !== 0;
+/**
+* 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.
+*/
+var registrableDomain = (hostname) => {
+	if (isLocalHost(hostname) || isIpAddress(hostname)) return;
+	const match = /([^.]+\.[^.]+)$/.exec(hostname);
+	return match ? `.${match[1]}` : void 0;
+};
+var resolve = (value, hostname, fallback) => {
+	if (typeof value === "function") return value(hostname);
+	return value ?? fallback;
+};
+/**
+* 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
+* SameSite=None + Secure so it survives the app and the API being different hosts. A local server gets the
+* opposite, because Secure + SameSite=None over plain http is dropped by every browser.
+*/
+var sessionCookieParams = (hostname, config = {}) => {
+	const local = isLocalHost(hostname);
+	return {
+		name: resolve(config.name, hostname, "plitzi_session"),
+		domain: resolve(config.domain, hostname, registrableDomain(hostname)),
+		secure: config.secure ?? !local,
+		sameSite: config.sameSite ?? (local ? "lax" : "none"),
+		refreshPath: config.refreshPath ?? "/auth",
+		hintSuffix: config.hintSuffix ?? "_hint"
+	};
+};
+/**
+* The value of the readable companion cookie: `<access expiry>.<refresh expiry>`, unix seconds, refresh optional.
+*
+* It exists because the session cookie is httpOnly — correctly — which leaves a page unable to tell whether the
+* browser holds a session at all. Answering that costs a request per page load otherwise, and the answer is usually
+* "nobody is signed in". This carries no credential: any script that can read it could have asked the backend the
+* same question with `credentials: 'include'`.
+*/
+var sessionHintValue = (expiresAt, refreshExpiresAt) => `${Math.floor(expiresAt)}.${refreshExpiresAt === void 0 ? "" : Math.floor(refreshExpiresAt)}`;
+var serializeCookie = (name, value, maxAgeSeconds, params, { httpOnly = true, path = "/" } = {}) => {
+	const parts = [
+		`${name}=${encodeURIComponent(value)}`,
+		`Path=${path}`,
+		...httpOnly ? ["HttpOnly"] : [],
+		`SameSite=${params.sameSite === "none" ? "None" : "Lax"}`,
+		`Max-Age=${Math.max(0, Math.floor(maxAgeSeconds))}`
+	];
+	if (params.domain) parts.push(`Domain=${params.domain}`);
+	if (params.secure) parts.push("Secure");
+	return parts.join("; ");
+};
+var nowInSeconds = () => Math.floor(Date.now() / 1e3);
+/**
+* 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.
+*/
+var appendCookies = (res, cookies) => {
+	const existing = res.getHeader?.("set-cookie") ?? res.headers?.["set-cookie"];
+	const previous = Array.isArray(existing) ? existing : typeof existing === "string" ? [existing] : [];
+	res.setHeader("Set-Cookie", [...previous, ...cookies]);
+};
+/**
+* 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
+* clients to renew something that is gone, and one that dies early signs out a live session.
+*/
+var writeSessionCookies = (req, res, session, config) => {
+	const params = sessionCookieParams(req.hostname, config);
+	const now = nowInSeconds();
+	const cookies = [serializeCookie(params.name, session.token, session.expiresAt - now, params)];
+	if (session.refreshToken) cookies.push(serializeCookie(`${params.name}_refresh`, session.refreshToken, (session.refreshExpiresAt ?? session.expiresAt) - now, params, { path: params.refreshPath }));
+	cookies.push(serializeCookie(`${params.name}${params.hintSuffix}`, sessionHintValue(session.expiresAt, session.refreshExpiresAt), (session.refreshExpiresAt ?? session.expiresAt) - now, params, { httpOnly: false }));
+	appendCookies(res, cookies);
+};
+/** Ends the session in this browser. Every cookie the grant wrote is cleared, the readable one included. */
+var clearSessionCookies = (req, res, config) => {
+	const params = sessionCookieParams(req.hostname, config);
+	appendCookies(res, [
+		serializeCookie(params.name, "", 0, params),
+		serializeCookie(`${params.name}_refresh`, "", 0, params, { path: params.refreshPath }),
+		serializeCookie(`${params.name}${params.hintSuffix}`, "", 0, params, { httpOnly: false })
+	]);
+};
+/**
+* The cookie a social sign-in leaves behind while the browser is away at the provider. Same family, same policy, so
+* it is written here rather than by whoever happens to be driving the flow. Path `/` because a deployment may serve
+* its API under a prefix, and the callback would then miss a cookie scoped to `/auth`.
+*/
+var writeFlowCookie = (req, res, value, ttlSeconds, config) => {
+	const params = sessionCookieParams(req.hostname, config);
+	appendCookies(res, [serializeCookie(`${params.name}_oauth`, value, ttlSeconds, params)]);
+};
+var clearFlowCookie = (req, res, config) => {
+	const params = sessionCookieParams(req.hostname, config);
+	appendCookies(res, [serializeCookie(`${params.name}_oauth`, "", 0, params)]);
+};
+/** The value that flow cookie carries, for the callback leg. */
+var readFlowCookie = (req, config) => readCookie(req, `${sessionCookieParams(req.hostname, config).name}_oauth`);
+var parseCookieHeader = (header) => {
+	const cookies = {};
+	for (const part of header.split(";")) {
+		const separator = part.indexOf("=");
+		if (separator === -1) continue;
+		cookies[part.slice(0, separator).trim()] = decodeURIComponent(part.slice(separator + 1).trim());
+	}
+	return cookies;
+};
+var readCookie = (req, name) => {
+	const header = req.headers.cookie;
+	return header ? parseCookieHeader(header)[name] || void 0 : void 0;
+};
+/** The session credential this request carries, for an adapter that resolves identity from it. */
+var readSessionToken = (req, config) => readCookie(req, sessionCookieParams(req.hostname, config).name);
+/** The renewal credential, which rides in its own cookie confined to the refresh path. */
+var readRefreshToken = (req, config) => readCookie(req, `${sessionCookieParams(req.hostname, config).name}_refresh`);
+/**
+* The cookie side of a session with this deployment's naming already bound in.
+*
+* The functions above take the naming on every call, which is right for the server's own internals and tedious for a
+* host that answers dozens of requests with the same configuration. Nothing here knows about any framework: it takes
+* a request that can be read and something that can carry `Set-Cookie`, which is as true of `node:http` as it is of
+* Express — a self-hoster running neither still gets the whole cycle.
+*/
+var createSessionCookies = (config) => ({
+	write: (req, res, session) => writeSessionCookies(req, res, session, config),
+	clear: (req, res) => clearSessionCookies(req, res, config),
+	/** Holds a social sign-in between its two legs: the CSRF nonce and the PKCE verifier. */
+	writeFlow: (req, res, value, ttlSeconds) => writeFlowCookie(req, res, value, ttlSeconds, config),
+	clearFlow: (req, res) => clearFlowCookie(req, res, config),
+	readFlow: (req) => readFlowCookie(req, config),
+	/**
+	* The session credential from `Authorization: Bearer` or the cookie, so one endpoint serves a bearer client and a
+	* browser. The header wins: a caller that went to the trouble of presenting one means it.
+	*/
+	resolveSessionToken: (req) => {
+		const header = req.headers.authorization;
+		return (header?.startsWith("Bearer ") ? header.slice(7).trim() : "") || readSessionToken(req, config);
+	},
+	/**
+	* The renewal credential from the request body (`refresh_token`, for API clients) or its cookie (for browsers).
+	* The body wins when both are present, mirroring how the session credential is resolved. `body` is whatever the
+	* host parsed — this only reads one field off it, so a host that parses JSON its own way still fits.
+	*/
+	resolveRefreshToken: (req, body) => {
+		const presented = body?.refresh_token;
+		if (typeof presented === "string" && presented.trim() !== "") return presented.trim();
+		return readRefreshToken(req, config);
+	}
+});
+//#endregion
+export { clearFlowCookie, clearSessionCookies, createSessionCookies, isLocalHost, readFlowCookie, readRefreshToken, readSessionToken, sessionCookieParams, sessionHintValue, writeFlowCookie, writeSessionCookies };

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

@@ -0,0 +1,137 @@
+import { SpaceScope, Tokens } from './tokens';
+/**
+ * A stored space credential, as whatever stores them reports one. `origins` is already parsed: how a deployment keeps
+ * the list (a joined column, a join table, a JSON blob) is its business and never leaks into the rules below.
+ */
+export interface SpaceTokenRecord {
+    id: number;
+    token: string;
+    scope: SpaceScope;
+    /** The space's public credential — the one published sites embed. Exactly one row per space carries this. */
+    isDefault: boolean;
+    origins: string[];
+    /** Unix seconds, or null for a credential that never expires. */
+    expiresAt: number | null;
+    userId?: number | null;
+    createdAt?: number;
+    updatedAt?: number;
+}
+export interface SpaceTokenAdapters {
+    loadDefault: (spaceId: number) => Promise<SpaceTokenRecord | undefined>;
+    find: (spaceId: number, tokenId: number) => Promise<SpaceTokenRecord | undefined>;
+    list: (spaceId: number) => Promise<SpaceTokenRecord[]>;
+    save: (id: number, values: {
+        token: string;
+        origins?: string[];
+        expiresAt?: number | null;
+    }) => Promise<void>;
+    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
+     * a deployment that caches either gets told the moment it changes, rather than serving the old one until its TTL.
+     */
+    onDomainsChanged?: (spaceId: number) => Promise<void>;
+}
+/**
+ * The floor a space is always reachable on: the platform-owned domain it is published under. Merged into every list so
+ * narrowing the domains to a custom one cannot lock a published site out of its own credential. Which domains those
+ * are is the deployment's to say — the rule that they are never dropped is not.
+ */
+export interface SpaceTokenContext {
+    spaceId: number;
+    defaultDomains: string[];
+}
+/**
+ * What a handler answers. The success body is typed per handler so a binding can reshape it — Plitzi's `GET /token`
+ * serves the bare credential for compatibility with its own older API — without casting its way back to it.
+ */
+export type SpaceTokenOutcome<B extends object = object> = {
+    ok: true;
+    status?: number;
+    body: B;
+} | {
+    ok: false;
+    status: number;
+    body: {
+        error: string;
+    } & Record<string, unknown>;
+};
+export type SpaceTokenSummary = Omit<SpaceTokenRecord, 'token' | 'origins'> & {
+    domains?: string[];
+    label?: string;
+};
+/**
+ * The lifecycle of a space's own credentials, over whatever stores them.
+ *
+ * Minting one is `tokens.generateSpaceToken`; everything around it is here, and it is all rule rather than storage:
+ * a credential whose claims changed is a **different credential**, so every edit below re-mints and the previous one
+ * stops working the instant it returns. Saying that once, in one place, is the point — a self-hoster who has to
+ * rediscover it discovers it as a published site that went dark.
+ */
+export declare const createSpaceTokenApi: ({ tokens, adapters }: {
+    tokens: Tokens;
+    adapters: SpaceTokenAdapters;
+}) => {
+    /**
+     * The space's public credential, rotated in place when it no longer verifies. Rotating on *outdated* and not only
+     * on expired is what this endpoint exists for: a site stranded on a credential from a previous token version would
+     * otherwise have no way back — nothing else can hand it a working one.
+     */
+    read(context: SpaceTokenContext): Promise<SpaceTokenOutcome<{
+        token: string;
+        domains: string[];
+    }>>;
+    /**
+     * Replace the public credential with a fresh one, keeping everything it declared. This is the control that expiry
+     * is often mistaken for: a render credential is meant to outlive any deadline, so revoking a leaked one is an act,
+     * not a wait.
+     */
+    rotate(context: SpaceTokenContext): Promise<SpaceTokenOutcome<{
+        token: string;
+        domains: string[];
+        warning: string;
+    }>>;
+    readDomains(context: SpaceTokenContext): Promise<SpaceTokenOutcome<{
+        domains: string[];
+    }>>;
+    setDomains(context: SpaceTokenContext, domains: unknown): Promise<SpaceTokenOutcome<{
+        token: string;
+        domains: string[];
+        warning?: string;
+    }>>;
+    readExpiry(context: SpaceTokenContext): Promise<SpaceTokenOutcome<{
+        expiresAt: number | null;
+        neverExpires: boolean;
+    }>>;
+    /**
+     * When the public credential should stop working — or never, which is the default. Both are legitimate: a site
+     * deployed once and left alone wants no deadline (an expiry there is a scheduled outage), while a campaign page
+     * meant to go quiet, or a credential handed to an agency for a fixed engagement, wants one.
+     */
+    setExpiry(context: SpaceTokenContext, expiresInDays: unknown): Promise<SpaceTokenOutcome<{
+        token: string;
+        expiresAt: number | null;
+        neverExpires: boolean;
+        warning: string;
+    }>>;
+    /**
+     * 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.
+     */
+    list(context: SpaceTokenContext): Promise<SpaceTokenOutcome<{
+        tokens: SpaceTokenSummary[];
+    }>>;
+    /**
+     * Revoke one credential. Dropping the record IS the revocation: every grant is looked up as it is verified, so it
+     * stops working at once whatever its claims still say.
+     *
+     * The public credential is deliberately not revocable this way — removing it leaves the published site with no
+     * credential at all, and replacing it is what a leak of that one calls for.
+     */
+    revoke(context: SpaceTokenContext, tokenId: number): Promise<SpaceTokenOutcome<{
+        message: string;
+        tokenId: number;
+    }>>;
+};
+export type SpaceTokenApi = ReturnType<typeof createSpaceTokenApi>;