@plitzi/sdk-server 0.37.2 → 0.37.4

package/dist/core/http/stages/sessionRenewal.js

@@ -0,0 +1,81 @@
+import { readRenewalGuard, readSessionHint, readSessionToken, writeRenewalGuard } from "../../auth/session.js";
+import { isDocumentNavigation, renewForNavigation } from "../../auth/renewal.js";
+//#region src/core/http/stages/sessionRenewal.ts
+/** Renewal this close to its deadline is not worth the round trip: it would be refused on arrival. */
+var REFRESH_MARGIN_SECONDS = 30;
+var nowInSeconds = () => Math.floor(Date.now() / 1e3);
+/**
+* This page's own address, absolute, for a renewal served by another host to send the browser back to. The port is
+* read off the authority rather than taken whole, so a forged `Host` cannot put anything but digits after the name.
+*/
+var pageUrl = (req) => {
+	const authority = req.headers[":authority"] ?? req.headers.host ?? "";
+	const port = /:(\d{1,5})$/u.exec(authority)?.[1];
+	return `${req.protocol}://${req.hostname}${port ? `:${port}` : ""}${req.path}${req.search}`;
+};
+/**
+* Whether this page request comes from a browser whose session has only half-lapsed.
+*
+* The access cookie dies with its token, while the refresh cookie lives on — confined to the refresh path, so it never
+* reaches a page. Rendered now, the page would be a guest's, and the browser, which renews as soon as it boots, would
+* swap it for the signed-in one: a guest page in the HTML, a different page on screen, and a guest-only page shown
+* and then redirected away from instead of answered with a redirect.
+*
+* The readable hint is what tells the two apart without presenting anything: it outlives the access cookie exactly
+* as long as renewal is still possible. It is also what keeps this from looping — a renewal that succeeds rewrites
+* it with an access expiry in the future, one that is refused clears it, and one that fails any other way leaves the
+* guard cookie behind.
+*/
+var halfLapsed = (req, cookie) => {
+	if (readSessionToken(req, cookie) !== void 0 || readRenewalGuard(req, cookie)) return false;
+	const hint = readSessionHint(req, cookie);
+	if (!hint?.refreshExpiresAt) return false;
+	const now = nowInSeconds();
+	return hint.expiresAt <= now && hint.refreshExpiresAt > now + REFRESH_MARGIN_SECONDS;
+};
+/**
+* Sends a page request from a half-lapsed session to renew first — to `url`, the renewal endpoint — so the server
+* renders the visitor the browser is going to end up with. See `renewForNavigation` for the other half.
+*
+* `url` is a path when this server serves `/auth` itself, and an absolute URL when another host does; the page's
+* own address travels as `redirect` accordingly, and the endpoint only sends the browser back to a host that shares
+* the session's cookies. Only whole-tab `GET` navigations take part: a renewal rotates the session.
+*/
+var createSessionRenewalStage = (url) => {
+	const sameHost = url.startsWith("/") && !url.startsWith("//");
+	const renewalPath = sameHost ? new URL(url, "http://localhost").pathname : void 0;
+	return ({ req, res, config }) => {
+		if (req.method !== "GET" || req.path === renewalPath || !isDocumentNavigation(req.headers)) return false;
+		if (!halfLapsed(req, config.authCookie)) return false;
+		const target = new URL(url, pageUrl(req));
+		target.searchParams.set("redirect", sameHost ? `${req.path}${req.search}` : pageUrl(req));
+		writeRenewalGuard(req, res, config.authCookie);
+		res.setStatus(303);
+		res.setHeader("Cache-Control", "no-store");
+		res.setHeader("Location", sameHost ? `${target.pathname}${target.search}` : target.toString());
+		res.end();
+		return true;
+	};
+};
+/**
+* The renewal endpoint, on a page server that serves `/auth` itself: `GET <basePath>/refresh`. The `POST` flow at the
+* same path is the auth API stage's; this one only ever answers a whole-tab navigation.
+*/
+var createRenewalEndpointStage = (auth) => {
+	const path = `${auth.basePath}/refresh`;
+	return async ({ req, res }) => {
+		if (req.method !== "GET" || req.path !== path || !isDocumentNavigation(req.headers)) return false;
+		const location = await renewForNavigation(req, res, {
+			api: auth.api,
+			cookies: auth.cookies,
+			csrf: auth.csrf
+		});
+		res.setStatus(303);
+		res.setHeader("Cache-Control", "no-store");
+		res.setHeader("Location", location);
+		res.end();
+		return true;
+	};
+};
+//#endregion
+export { createRenewalEndpointStage, createSessionRenewalStage };

package/dist/core/http/stages/sessionRenewal.test.d.ts

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

package/dist/core/http/stages/signInRoute.d.ts

@@ -0,0 +1,2 @@
+import { Stage } from '../types';
+export declare const signInStage: Stage;

package/dist/core/http/stages/signInRoute.js

@@ -0,0 +1,139 @@
+import { requestOrigin } from "../../requestParser.js";
+import { safeRedirectTarget } from "../navigation.js";
+import { appendCookies, writeSessionCookies } from "../../auth/session.js";
+import { readCookies } from "../../auth/credentials.js";
+import { createHash, randomBytes } from "node:crypto";
+//#region src/core/http/stages/signInRoute.ts
+/**
+* Signing a visitor in by redirect (`config.signIn`): out to an authorization server, back with a code, and a session
+* of this host's own made from it through `exchangeCredential`.
+*
+* Everything that decides whether the person may sign in, and into what, is the authorization server's and the
+* exchange adapter's. What is here is the part that is the same for any of them: registering this host as a client,
+* PKCE, the state that ties the callback to the browser that started, and never sending anybody off-site on the way
+* back.
+*/
+/**
+* The flow's state, in the browser that started it. `__Host-` is the point: a cookie with that prefix cannot carry a
+* Domain, so a sibling host — another space on the same parent domain — cannot plant one and finish a sign-in it
+* started in this browser, as whoever it signed in as.
+*/
+var STATE_COOKIE = "__Host-sign-in";
+var STATE_TTL_SECONDS = 600;
+var base64url = (bytes) => bytes.toString("base64url");
+var readState = (req) => {
+	const raw = readCookies(req)[STATE_COOKIE];
+	if (!raw) return;
+	try {
+		const parsed = JSON.parse(Buffer.from(raw, "base64url").toString("utf-8"));
+		return typeof parsed.state === "string" && typeof parsed.verifier === "string" && typeof parsed.returnTo === "string" ? {
+			state: parsed.state,
+			verifier: parsed.verifier,
+			returnTo: parsed.returnTo
+		} : void 0;
+	} catch {
+		return;
+	}
+};
+var stateCookie = (value, maxAge) => `${STATE_COOKIE}=${value}; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=${maxAge}`;
+/**
+* The client id this host is registered under, per authorization server and redirect address. Registration is
+* idempotent there — the same metadata is the same client — so each process asks once and keeps the answer.
+*/
+var clients = /* @__PURE__ */ new Map();
+var clientFor = (signIn, redirectUri, hostname) => {
+	const key = `${signIn.registerUrl} ${redirectUri}`;
+	const known = clients.get(key);
+	if (known) return known;
+	const registering = (async () => {
+		const response = await fetch(signIn.registerUrl, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({
+				client_name: hostname,
+				redirect_uris: [redirectUri],
+				grant_types: ["authorization_code"],
+				response_types: ["code"],
+				token_endpoint_auth_method: "none"
+			})
+		});
+		const body = await response.json();
+		if (!response.ok || typeof body.client_id !== "string") throw new Error(`Registering ${hostname} with the authorization server failed (${response.status})`);
+		return body.client_id;
+	})();
+	clients.set(key, registering);
+	registering.catch(() => clients.delete(key));
+	return registering;
+};
+var redirect = (res, location) => {
+	res.setStatus(303);
+	res.setHeader("Location", location);
+	res.end();
+	return true;
+};
+var signInStage = async (ctx) => {
+	const { config, req, res } = ctx;
+	const { signIn } = config;
+	if (!signIn || req.method !== "GET") return false;
+	const path = signIn.path ?? "/auth/sign-in";
+	const callbackPath = `${path}/callback`;
+	if (req.path !== path && req.path !== callbackPath) return false;
+	const { exchangeCredential, getSpaceDeployment } = config.adapters;
+	const origin = requestOrigin(req);
+	if (!exchangeCredential || !getSpaceDeployment || !origin) {
+		res.setStatus(404);
+		res.end();
+		return true;
+	}
+	const redirectUri = `${origin}${callbackPath}`;
+	if (req.path === path) {
+		const deployment = await getSpaceDeployment(req);
+		if (typeof deployment.spaceId !== "number") {
+			res.setStatus(404);
+			res.end();
+			return true;
+		}
+		const clientId = await clientFor(signIn, redirectUri, req.hostname);
+		const verifier = base64url(randomBytes(32));
+		const state = base64url(randomBytes(16));
+		const flow = {
+			state,
+			verifier,
+			returnTo: safeRedirectTarget(req, "return")
+		};
+		appendCookies(res, [stateCookie(base64url(Buffer.from(JSON.stringify(flow))), STATE_TTL_SECONDS)]);
+		const authorize = new URL(signIn.authorizeUrl);
+		authorize.search = new URLSearchParams({
+			response_type: "code",
+			client_id: clientId,
+			redirect_uri: redirectUri,
+			scope: signIn.scope(deployment.spaceId),
+			state,
+			code_challenge: base64url(createHash("sha256").update(verifier).digest()),
+			code_challenge_method: "S256"
+		}).toString();
+		return redirect(res, authorize.toString());
+	}
+	const flow = readState(req);
+	appendCookies(res, [stateCookie("", 0)]);
+	const code = req.query["code"];
+	if (!flow || !code || req.query["state"] !== flow.state) return redirect(res, flow?.returnTo ?? "/");
+	const token = await fetch(signIn.tokenUrl, {
+		method: "POST",
+		headers: { "Content-Type": "application/x-www-form-urlencoded" },
+		body: new URLSearchParams({
+			grant_type: "authorization_code",
+			code,
+			redirect_uri: redirectUri,
+			client_id: await clientFor(signIn, redirectUri, req.hostname),
+			code_verifier: flow.verifier
+		}).toString()
+	});
+	const granted = await token.json();
+	if (!token.ok || typeof granted.access_token !== "string") return redirect(res, flow.returnTo);
+	const result = await exchangeCredential(signIn.provider, granted.access_token, req);
+	if (result.ok) writeSessionCookies(req, res, result.session, config.authCookie);
+	return redirect(res, flow.returnTo);
+};
+//#endregion
+export { signInStage };

package/dist/core/http/stages/signInRoute.test.d.ts

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

package/dist/core/http/types.d.ts

@@ -1,6 +1,8 @@
+import { UpgradeRequest } from './socketResponse';
 import { RawResponse } from '../../helpers/buildResponseHelpers';
 import { ServerCaches } from '../../helpers/cache';
 import { ActionsModule } from '../../modules/actions';
+import { RealtimeModule } from '../../modules/realtime';
 import { PluginManager } from '../../plugins/manager';
 import { SSRPageServerConfig, SSRRequest, SSRResponseHelpers, SSRServerConfig, SSRTemplateFn } from '@plitzi/sdk-shared';
 import { IncomingMessage } from 'node:http';
@@ -22,12 +24,19 @@ export interface BaseContext {
      * spend real work on behalf of a caller should hand this to whatever they call.
      */
     signal: AbortSignal;
+    /**
+     * Present when the request asks to switch protocols (a WebSocket). The stage that takes it performs the switch on
+     * the socket and marks it `taken`; any other answer is written to the socket as HTTP and closes it.
+     */
+    upgrade?: UpgradeRequest;
 }
 export interface SSRContext extends BaseContext {
     config: SSRPageServerConfig;
     /** Built at boot when the deployment configured `action.lookups`, so its task registry is validated once and
      *  its guards are a single set for the process. Absent means this server runs no actions. */
     actions?: ActionsModule;
+    /** The realtime channels, built at boot unless the config turned them off. Absent means `/_realtime` is not served. */
+    realtime?: RealtimeModule;
     renderFn: SSRTemplateFn;
     caches: ServerCaches;
     pluginManager: PluginManager;

package/dist/core/http/webExchange.d.ts

@@ -0,0 +1,18 @@
+import { IncomingMessage } from 'node:http';
+/** What a response is written onto: node's own, or the page server's raw one. */
+export type WebResponseSink = {
+    writeHead(statusCode: number, headers: Record<string, string>): unknown;
+    write(chunk: Buffer): unknown;
+    end(): unknown;
+};
+/**
+ * An incoming request as a web `Request` at `url` — its headers but those named in `without` (lower case), and its
+ * body read whole, within the server's body limit. What a web-standard handler takes: an MCP transport, an endpoint a
+ * space runtime declares.
+ */
+export declare const webRequestOf: (raw: IncomingMessage, url: string, without?: readonly string[]) => Promise<Request>;
+/**
+ * A web `Response` written onto a node one: its status and headers, then its body as it comes — a stream too, chunk by
+ * chunk, which is what an event stream needs — until it ends or `signal` says the caller went away.
+ */
+export declare const writeWebResponse: (rawRes: WebResponseSink, response: Response, signal?: AbortSignal) => Promise<void>;

package/dist/core/http/webExchange.js

@@ -0,0 +1,53 @@
+import { readRawBytes } from "../requestParser.js";
+//#region src/core/http/webExchange.ts
+var BODYLESS = /* @__PURE__ */ new Set(["GET", "HEAD"]);
+/**
+* An incoming request as a web `Request` at `url` — its headers but those named in `without` (lower case), and its
+* body read whole, within the server's body limit. What a web-standard handler takes: an MCP transport, an endpoint a
+* space runtime declares.
+*/
+var webRequestOf = async (raw, url, without = []) => {
+	const headers = new Headers();
+	Object.entries(raw.headers).forEach(([name, value]) => {
+		if (name.startsWith(":") || without.includes(name)) return;
+		(Array.isArray(value) ? value : value === void 0 ? [] : [value]).forEach((one) => headers.append(name, one));
+	});
+	const method = raw.method ?? "GET";
+	return new Request(url, {
+		method,
+		headers,
+		...BODYLESS.has(method) ? {} : { body: new Uint8Array(await readRawBytes(raw)) }
+	});
+};
+/**
+* A web `Response` written onto a node one: its status and headers, then its body as it comes — a stream too, chunk by
+* chunk, which is what an event stream needs — until it ends or `signal` says the caller went away.
+*/
+var writeWebResponse = async (rawRes, response, signal) => {
+	const headers = {};
+	response.headers.forEach((value, name) => {
+		headers[name] = value;
+	});
+	rawRes.writeHead(response.status, headers);
+	if (!response.body) {
+		rawRes.end();
+		return;
+	}
+	const reader = response.body.getReader();
+	const stop = () => {
+		reader.cancel();
+	};
+	signal?.addEventListener("abort", stop, { once: true });
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			rawRes.write(Buffer.from(value));
+		}
+	} catch {} finally {
+		signal?.removeEventListener("abort", stop);
+		rawRes.end();
+	}
+};
+//#endregion
+export { webRequestOf, writeWebResponse };

package/dist/core/oauth/authorize.js

@@ -1,9 +1,11 @@
 import { renderConsentPage } from "./consentPage.js";
+import { dropPending, getClient, getPending, putCode, putPending } from "./records.js";
+import { issueContextFor } from "./issueContext.js";
 import { AUTHORIZE_PATH } from "./metadata.js";
 import { field, optionalField } from "./params.js";
 import { randomId } from "./pkce.js";
-import { dropPending, getClient, getPending, putCode, putPending } from "./records.js";
 import { redirectToSignIn, redirectWithCode, redirectWithError, sendErrorPage, sendHtml } from "./respond.js";
+import { isLoopbackRedirectUri } from "./register.js";
 //#region src/core/oauth/authorize.ts
 var DEFAULT_CODE_TTL_SECONDS = 60;
 var DEFAULT_GUEST_LABEL = "Continue without an account";
@@ -27,6 +29,12 @@ var hiddenFieldsFor = (request, pendingId) => {
 	if (pendingId !== void 0) hidden["pending"] = pendingId;
 	return hidden;
 };
+/** Who is asking and where the answer goes, as the grant screen shows it (see `OAuthConsentView.client`). */
+var consentClient = (request) => ({
+	name: request.clientName,
+	redirectHost: new URL(request.redirectUri).host,
+	loopback: isLoopbackRedirectUri(request.redirectUri)
+});
 var renderConsent = (res, view) => {
 	sendHtml(res, 200, renderConsentPage(view));
 };
@@ -36,9 +44,16 @@ var renderConsent = (res, view) => {
 * Rebuilt from the params rather than read off `req.url` because the two can differ — a proxy may rewrite the
 * path — and what has to survive the round trip is the QUERY, which is the authorization request itself.
 */
+/**
+* Where `/authorize` is, for this server: its issuer and the path, joined — the issuer may carry a path of its own when
+* the server is mounted under a prefix, which resolving `/authorize` against it would drop. The same joining the
+* discovery document publishes the endpoint by.
+*/
+var authorizeEndpoint = (config, req) => new URL(`${(config.issuer ?? `https://${req.headers.host ?? ""}`).replace(/\/+$/u, "")}${AUTHORIZE_PATH}`);
+/** The same endpoint, as the path the grant screen's form posts to — this server's own origin, whatever it is. */
+var authorizeAction = (config) => config.issuer ? `${new URL(config.issuer).pathname.replace(/\/+$/u, "")}${AUTHORIZE_PATH}` : AUTHORIZE_PATH;
 var authorizeUrl = (config, req, params) => {
-	const base = config.issuer ?? `https://${req.headers.host ?? ""}`;
-	const url = new URL(AUTHORIZE_PATH, base);
+	const url = authorizeEndpoint(config, req);
 	for (const [key, value] of Object.entries(params)) if (typeof value === "string") url.searchParams.set(key, value);
 	return url.toString();
 };
@@ -73,8 +88,7 @@ var signInWithReturn = (config, req, params) => {
 * both paths already carry, instead of from whichever shape they came in.
 */
 var authorizeUrlFor = (config, req, request) => {
-	const base = config.issuer ?? `https://${req.headers.host ?? ""}`;
-	const url = new URL(AUTHORIZE_PATH, base);
+	const url = authorizeEndpoint(config, req);
 	url.searchParams.set("response_type", "code");
 	url.searchParams.set("client_id", request.clientId);
 	url.searchParams.set("redirect_uri", request.redirectUri);
@@ -98,6 +112,10 @@ var resolveRequest = async (config, res, params) => {
 		sendErrorPage(res, "Invalid redirect", "The application asked to be sent back to an address it did not register.");
 		return;
 	}
+	if (config.loopbackRedirectsOnly && !isLoopbackRedirectUri(redirectUri)) {
+		sendErrorPage(res, "Invalid redirect", "Only an application running on this computer can sign in here.");
+		return;
+	}
 	const state = optionalField(params, "state");
 	const responseType = field(params, "response_type");
 	if (responseType && responseType !== "code") {
@@ -112,6 +130,7 @@ var resolveRequest = async (config, res, params) => {
 	}
 	return {
 		clientId,
+		clientName: client.clientName,
 		redirectUri,
 		challenge,
 		state,
@@ -120,8 +139,11 @@ var resolveRequest = async (config, res, params) => {
 };
 /** Consent granted: mint the bearer now, park it behind a one-shot code and send the browser back. Minting here
 *  rather than at redemption keeps a failure the user can act on — no space, revoked access — on this screen. */
-var completeGrant = async (config, res, request, user, target) => {
-	const issued = await config.adapters.issueToken(user, target);
+var completeGrant = async (config, res, req, request, user, target) => {
+	const issued = await config.adapters.issueToken(user, target, await issueContextFor(config, request.clientId, {
+		req,
+		redirectUri: request.redirectUri
+	}));
 	if (!issued) {
 		redirectWithError(res, request.redirectUri, "access_denied", "The account may not grant access to this resource.", request.state);
 		return;
@@ -146,7 +168,7 @@ var completeGrant = async (config, res, request, user, target) => {
 * proves — on that POST — that identity was established before anything was granted.
 */
 var askForTarget = async (config, res, request, user, error) => {
-	const targets = await config.adapters.grantTargets(user);
+	const targets = await config.adapters.grantTargets(user, { scope: request.scope });
 	if (targets.length === 0) {
 		redirectWithError(res, request.redirectUri, "access_denied", "This account has nothing to grant access to.", request.state);
 		return;
@@ -161,12 +183,13 @@ var askForTarget = async (config, res, request, user, error) => {
 		user
 	});
 	renderConsent(res, {
-		action: AUTHORIZE_PATH,
+		action: authorizeAction(config),
 		hidden: hiddenFieldsFor(request, pendingId),
 		targets,
 		user,
 		canSwitchUser: config.adapters.signOut !== void 0,
 		error,
+		client: consentClient(request),
 		branding: config.branding ?? {}
 	});
 };
@@ -192,11 +215,12 @@ var handleAuthorizeStart = async (config, res, params, req) => {
 	}
 	if (config.guest) {
 		renderConsent(res, {
-			action: AUTHORIZE_PATH,
+			action: authorizeAction(config),
 			hidden: hiddenFieldsFor(request),
 			targets: [],
 			guest: guestView(config.guest),
 			signInUrl: signInWithReturn(config, req, params),
+			client: consentClient(request),
 			branding: config.branding ?? {}
 		});
 		return;
@@ -228,7 +252,7 @@ var handleAuthorizeSubmit = async (config, res, params, req) => {
 	}
 	const { guest } = config;
 	if (guest && optionalField(params, "guest")) {
-		await completeGrant(config, res, request, guest.user ?? DEFAULT_GUEST_USER, guest.target);
+		await completeGrant(config, res, req, request, guest.user ?? DEFAULT_GUEST_USER, guest.target);
 		return;
 	}
 	const pendingId = optionalField(params, "pending");
@@ -241,14 +265,14 @@ var handleAuthorizeSubmit = async (config, res, params, req) => {
 		redirectWithError(res, request.redirectUri, "access_denied", "The sign-in expired. Try connecting again.", request.state);
 		return;
 	}
-	const chosen = (await config.adapters.grantTargets(pending.user)).find((target) => target.value === field(params, "target"));
+	const chosen = (await config.adapters.grantTargets(pending.user, { scope: request.scope })).find((target) => target.value === field(params, "target"));
 	if (!chosen) {
 		await dropPending(config.adapters.store, pendingId);
 		await askForTarget(config, res, request, pending.user, "Choose what to grant access to.");
 		return;
 	}
 	await dropPending(config.adapters.store, pendingId);
-	await completeGrant(config, res, request, pending.user, chosen);
+	await completeGrant(config, res, req, request, pending.user, chosen);
 };
 //#endregion
 export { handleAuthorizeStart, handleAuthorizeSubmit };

package/dist/core/oauth/consentPage.js

@@ -24,6 +24,8 @@ var STYLES = `
   img.logo { display: block; height: 32px; margin-bottom: 20px; }
   h1 { margin: 0 0 6px; font-size: 20px; font-weight: 600; }
   p.lede { margin: 0 0 24px; color: var(--muted); font-size: 14px; }
+  p.client { margin: -12px 0 24px; padding: 10px 12px; border: 1px solid var(--line); border-radius: 8px;
+    font-size: 14px; }
   input:focus-visible, button:focus-visible { outline: 2px solid var(--accent); outline-offset: 1px; }
   ul.targets { list-style: none; margin: 0 0 20px; padding: 0; display: grid; gap: 8px; }
   ul.targets label { display: flex; gap: 10px; align-items: flex-start; margin: 0; padding: 12px;
@@ -73,6 +75,14 @@ var anonymousFields = (view) => {
 	return `${view.guest ? guestButton(view.guest) : ""}${signIn}`;
 };
 /**
+* Who is asking and where the grant goes. The name is whatever the client registered as, so it is never shown alone:
+* the destination host is what a person can check against the app they just opened.
+*/
+var clientNotice = (client) => {
+	const destination = client.loopback ? "an app on this computer" : `<strong>${escapeHtml(client.redirectHost)}</strong>`;
+	return `<p class="client"><strong>${escapeHtml(client.name)}</strong> is asking for access. If you continue, it is sent to ${destination}.</p>`;
+};
+/**
 * The grant screen — the ONE page this server renders, and it never asks who anybody is.
 *
 * It used to be two steps, the first of which took a username and a password. That is gone: signing in happens on
@@ -99,6 +109,7 @@ var renderConsentPage = (view) => {
     ${logo}
     <h1>${escapeHtml(productName)}</h1>
     <p class="lede">${lede}</p>
+    ${clientNotice(view.client)}
     ${error}
     <form method="post" action="${escapeHtml(view.action)}">
       ${hiddenFields(view.hidden)}

package/dist/core/oauth/issueContext.d.ts

@@ -0,0 +1,14 @@
+import { OAuthConfig, OAuthIssueContext, SSRRequest } from '@plitzi/sdk-shared';
+/**
+ * What `issueToken` is told about who it issues to, beyond the person: the application, as it registered, and the
+ * request the credential is issued on.
+ *
+ * The application is read from its registration rather than trusted from the request — a client names itself once,
+ * when it registers, and every credential its grants mint carries that name. A registration that has aged out of the
+ * store (a grant renewed for longer than the client record lives) is still an application, just an unnamed one.
+ */
+export declare const issueContextFor: (config: OAuthConfig, clientId: string, extra?: {
+    req?: SSRRequest;
+    replaces?: string;
+    redirectUri?: string;
+}) => Promise<OAuthIssueContext>;

package/dist/core/oauth/issueContext.js

@@ -0,0 +1,32 @@
+import { forwardedIp } from "../requestParser.js";
+import { getClient } from "./records.js";
+//#region src/core/oauth/issueContext.ts
+/**
+* What `issueToken` is told about who it issues to, beyond the person: the application, as it registered, and the
+* request the credential is issued on.
+*
+* The application is read from its registration rather than trusted from the request — a client names itself once,
+* when it registers, and every credential its grants mint carries that name. A registration that has aged out of the
+* store (a grant renewed for longer than the client record lives) is still an application, just an unnamed one.
+*/
+var issueContextFor = async (config, clientId, extra = {}) => {
+	const client = await getClient(config.adapters.store, clientId);
+	const userAgent = extra.req?.headers["user-agent"];
+	const ip = extra.req ? extra.req.ip ?? forwardedIp(extra.req.headers) : "";
+	const request = {
+		...typeof userAgent === "string" && userAgent ? { userAgent } : {},
+		...ip ? { ip } : {}
+	};
+	return {
+		client: {
+			clientId,
+			name: client?.clientName ?? "Unnamed application",
+			...client?.softwareId ? { softwareId: client.softwareId } : {}
+		},
+		...request.userAgent || request.ip ? { request } : {},
+		...extra.replaces ? { replaces: extra.replaces } : {},
+		...extra.redirectUri ? { redirectUri: extra.redirectUri } : {}
+	};
+};
+//#endregion
+export { issueContextFor };

package/dist/core/oauth/records.d.ts

@@ -4,6 +4,8 @@ import { OAuthGrantTarget, OAuthStore, OAuthUser } from '@plitzi/sdk-shared';
 export type ClientRecord = {
     clientId: string;
     clientName: string;
+    /** RFC 7591 `software_id`, when the client sent one. */
+    softwareId?: string;
     redirectUris: string[];
     /** When this registration was first handed out, so re-registering the same client keeps reporting its real age. */
     issuedAt: number;
@@ -37,6 +39,11 @@ export type RefreshRecord = {
     scope?: string;
     user: OAuthUser;
     target: OAuthGrantTarget;
+    /**
+     * What `issueToken` last minted for this grant. Handed back as `replaces` on the renewal, so the deployment can
+     * rotate that credential instead of adding another, and to `revokeToken` when the grant is revoked.
+     */
+    credential?: string;
 };
 /** A bearer this server handed out. The token a client holds is an opaque handle minted here, and this record is
  *  what it stands for — including `credential`, the thing the deployment's own adapters understand, which never

package/dist/core/oauth/register.d.ts

@@ -1,4 +1,6 @@
 import { OAuthConfig, SSRResponseHelpers } from '@plitzi/sdk-shared';
+/** Plain http on the loopback interface — the exception RFC 8252 carves out for a native app listening on a port. */
+export declare const isLoopbackRedirectUri: (value: string) => boolean;
 /** RFC 7591 dynamic client registration. A remote host has no way to be configured into this server ahead of
  *  time, so it registers itself on first connect; the record it gets back is only ever used to pin the redirect
  *  target, since a public client authenticates with PKCE rather than with credentials. */