@anthusai/papyrus 2.0.0-next.10 → 2.0.0-next.100

package/lib/prospectus-session.ts

@@ -1,5 +1,6 @@
 import { createCipheriv, createDecipheriv, hkdfSync, randomBytes } from "node:crypto";
-import { GetSecretValueCommand, SecretsManagerClient } from "@aws-sdk/client-secrets-manager";
+import { GetParameterCommand, SSMClient } from "@aws-sdk/client-ssm";
+import type { NextRequest } from "next/server";
 import { readAmplifyOutputsFile } from "./amplify-outputs-path";
 import {
   ProspectusSiteAccounts,
@@ -21,7 +22,7 @@ import {
 export const PROSPECTUS_PENDING_SIGN_IN_COOKIE = "__Host-papyrus-prospectus-pending";
 export const PROSPECTUS_SESSION_COOKIE = "__Host-papyrus-prospectus-session";
 export const PROSPECTUS_ACCOUNTS_ENDPOINT_ENV = "PAPYRUS_PROSPECTUS_ACCOUNTS_ENDPOINT";
-export const PROSPECTUS_SESSION_SECRET_ARN_ENV = "PAPYRUS_PROSPECTUS_SESSION_SECRET_ARN";
+export const PROSPECTUS_SESSION_SECRET_PARAMETER_ENV = "PAPYRUS_PROSPECTUS_SESSION_SECRET_PARAMETER";
 export const PROSPECTUS_SESSION_SECRET_CACHE_MILLISECONDS = 5 * 60 * 1000;
 
 const SEALED_COOKIE_FORMAT_VERSION = "v1";
@@ -39,6 +40,21 @@ export interface ProspectusSignedInSession {
   accessToken: string;
   accessTokenExpiresAt: number;
   selectedAccountId?: string;
+  siteSubject?: string;
+}
+
+/** Open the existing sealed Prospectus session cookie for one server request. */
+export function signedInProspectusSession(
+  request: Pick<NextRequest, "cookies">,
+  sealingSecret: string,
+  nowInSeconds?: number,
+): ProspectusSignedInSession | null {
+  return openProspectusCookie<ProspectusSignedInSession>(
+    sealingSecret,
+    PROSPECTUS_SESSION_COOKIE,
+    request.cookies.get(PROSPECTUS_SESSION_COOKIE)?.value,
+    nowInSeconds,
+  );
 }
 
 function sealingKeyForCookie(sealingSecret: string, cookieName: string): Buffer {
@@ -101,37 +117,37 @@ export function sameSiteReturnPath(requestedReturnPath: string | null | undefine
   return `${parsed.pathname}${parsed.search}${parsed.hash}`;
 }
 
-export type ProspectusSessionSecretReader = (secretArn: string) => Promise<string | null>;
+export type ProspectusSessionSecretReader = (parameterName: string) => Promise<string | null>;
 
-type CachedSealingSecret = { secretArn: string; value: string; expiresAt: number };
+type CachedSealingSecret = { parameterName: string; value: string; expiresAt: number };
 
 let cachedSealingSecret: CachedSealingSecret | null = null;
-let defaultSecretsManagerClient: SecretsManagerClient | null = null;
+let defaultSsmClient: SSMClient | null = null;
 
 export function resetProspectusSessionSecretCache(): void {
   cachedSealingSecret = null;
 }
 
-async function readSealingSecretFromSecretsManager(secretArn: string): Promise<string | null> {
-  defaultSecretsManagerClient ??= new SecretsManagerClient({});
-  const response = await defaultSecretsManagerClient.send(new GetSecretValueCommand({ SecretId: secretArn }));
-  return response.SecretString?.trim() || null;
+export async function readSealingSecretFromSsm(parameterName: string, client?: Pick<SSMClient, "send">): Promise<string | null> {
+  defaultSsmClient ??= new SSMClient({});
+  const response = await (client ?? defaultSsmClient).send(new GetParameterCommand({ Name: parameterName, WithDecryption: true }));
+  return response.Parameter?.Value?.trim() || null;
 }
 
 export async function loadProspectusSessionSealingSecret(
   options: { environment?: Record<string, string | undefined>; readSecret?: ProspectusSessionSecretReader; now?: number } = {},
 ): Promise<string | null> {
   const environment = options.environment ?? process.env;
-  const secretArn = environment[PROSPECTUS_SESSION_SECRET_ARN_ENV]?.trim();
-  if (!secretArn) return null;
+  const parameterName = environment[PROSPECTUS_SESSION_SECRET_PARAMETER_ENV]?.trim();
+  if (!parameterName) return null;
   const now = options.now ?? Date.now();
-  if (cachedSealingSecret && cachedSealingSecret.secretArn === secretArn && cachedSealingSecret.expiresAt > now) {
+  if (cachedSealingSecret && cachedSealingSecret.parameterName === parameterName && cachedSealingSecret.expiresAt > now) {
     return cachedSealingSecret.value;
   }
   try {
-    const value = (await (options.readSecret ?? readSealingSecretFromSecretsManager)(secretArn))?.trim();
+    const value = (await (options.readSecret ?? readSealingSecretFromSsm)(parameterName))?.trim();
     if (!value || value.length < MINIMUM_SEALING_SECRET_LENGTH) return null;
-    cachedSealingSecret = { secretArn, value, expiresAt: now + PROSPECTUS_SESSION_SECRET_CACHE_MILLISECONDS };
+    cachedSealingSecret = { parameterName, value, expiresAt: now + PROSPECTUS_SESSION_SECRET_CACHE_MILLISECONDS };
     return value;
   } catch (error) {
     console.error(`Prospectus session sealing secret could not be read (${error instanceof Error ? error.name : "error"}).`);

package/lib/prospectus-sign-in-routes.ts

@@ -12,6 +12,7 @@ import {
   PROSPECTUS_SESSION_COOKIE,
   openProspectusCookie,
   resolveProspectusSignInRuntime,
+  signedInProspectusSession,
   sameSiteReturnPath,
   sealProspectusCookie,
   sealedCookieAttributes,
@@ -25,6 +26,7 @@ import {
   publishingAccountsForSite,
   type PublicationCapability,
 } from "./prospectus-publication-access";
+import { SiteOriginNotConfiguredError, publicSiteOrigin, siteOriginNotConfiguredResponse } from "./site-origin";
 
 /**
  * The site's sign-in routes for Prospectus accounts: start (challenge, then the
@@ -38,6 +40,10 @@ export interface ProspectusSignInRouteOptions {
   siteProduct?: string | null;
   completionOverrides?: Pick<CompleteProspectusGoogleSignInInput, "verifyCognitoTokens" | "fetcher">;
   nowInSeconds?: () => number;
+  /** Trusted configuration the public site origin is read from; defaults to process.env. */
+  environment?: Record<string, string | undefined>;
+  /** Receives each sign-in failure line; defaults to console.error so it reaches the compute log. */
+  log?: (line: string) => void;
 }
 
 const NO_STORE_HEADERS = { "cache-control": "no-store" };
@@ -50,8 +56,22 @@ function currentTimeInSeconds(options: ProspectusSignInRouteOptions): number {
   return options.nowInSeconds?.() ?? Math.floor(Date.now() / 1000);
 }
 
+function siteOriginFor(request: NextRequest, options: ProspectusSignInRouteOptions): string {
+  return publicSiteOrigin(request, options.environment);
+}
+
 async function signInRuntimeFor(request: NextRequest, options: ProspectusSignInRouteOptions): Promise<ProspectusSignInRuntime | null> {
-  return (options.resolveRuntime ?? resolveProspectusSignInRuntime)(request.nextUrl.origin);
+  return (options.resolveRuntime ?? resolveProspectusSignInRuntime)(siteOriginFor(request, options));
+}
+
+/** Runs a route and answers a missing site origin with 503 site_origin_not_configured, never a localhost redirect. */
+async function failingClosedWithoutSiteOrigin(route: () => Promise<NextResponse>): Promise<NextResponse> {
+  try {
+    return await route();
+  } catch (error) {
+    if (error instanceof SiteOriginNotConfiguredError) return siteOriginNotConfiguredResponse(error);
+    throw error;
+  }
 }
 
 function signInUnavailableResponse(): NextResponse {
@@ -65,30 +85,62 @@ function clearSealedCookie(response: NextResponse, cookieName: string): void {
   response.cookies.set(cookieName, "", sealedCookieAttributes(0, 0));
 }
 
+/** A JSON failure, for the routes the page script calls with fetch (session, account selection and creation). */
 function signInFailedResponse(status: number, code: string, message: string): NextResponse {
   return NextResponse.json({ error: code, message }, { status, headers: NO_STORE_HEADERS });
 }
 
-export function signedInProspectusSession(
-  request: NextRequest,
-  sealingSecret: string,
-  nowInSeconds?: number,
-): ProspectusSignedInSession | null {
-  return openProspectusCookie<ProspectusSignedInSession>(
-    sealingSecret,
-    PROSPECTUS_SESSION_COOKIE,
-    request.cookies.get(PROSPECTUS_SESSION_COOKIE)?.value,
-    nowInSeconds,
-  );
+/**
+ * A failed sign-in never leaves the browser on /api/auth/prospectus/callback: it answers 303 to the page the reader started from
+ * (or the home page when that is not known) with `sign_in_error=<code>`, which the reader plugin turns into a short message.
+ */
+/** Which callback step failed; with the code it tells an operator where a reader's sign-in stopped. */
+type SignInFailureBranch = "pending_cookie" | "provider_error" | "missing_parameters" | "completion" | "unexpected";
+
+/**
+ * One structured line per failed callback: `prospectus_sign_in_failed {"code":...,"branch":...}`. It carries only the
+ * code, the branch, and (for errors from completing the sign-in) the HTTP status, Prospectus error code, its rule text
+ * (`prospectusMessage`, which names the broken rule and carries no personal data) and error name.
+ * Never tokens, authorization codes, state, emails or subjects.
+ */
+function logSignInFailure(
+  options: ProspectusSignInRouteOptions,
+  entry: { code: string; branch: SignInFailureBranch; httpStatus?: number; prospectusError?: string; prospectusMessage?: string; errorName?: string },
+): void {
+  (options.log ?? console.error)(`prospectus_sign_in_failed ${JSON.stringify(entry)}`);
+}
+
+function signInFailedRedirect(request: NextRequest, options: ProspectusSignInRouteOptions, returnPath: string | null, code: string): NextResponse {
+  const target = new URL(returnPath ?? "/", siteOriginFor(request, options));
+  target.searchParams.set("sign_in_error", /^[a-z0-9_]{1,60}$/.test(code) ? code : "sign_in_failed");
+  return NextResponse.redirect(target, { status: 303, headers: NO_STORE_HEADERS });
 }
 
-export async function handleProspectusSignInStart(request: NextRequest, options: ProspectusSignInRouteOptions = {}): Promise<NextResponse> {
+export { signedInProspectusSession } from "./prospectus-session";
+
+/** `returnTo` from the query (a link) or, for the POST form the reader plugin's button submits, from the form body. */
+async function requestedReturnPath(request: NextRequest): Promise<string | null> {
+  if (request.method !== "POST") return request.nextUrl.searchParams.get("returnTo");
+  try {
+    const value = (await request.formData()).get("returnTo");
+    return typeof value === "string" ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+/** GET (a link) or POST (the reader plugin's "Sign in" button, so people are never sent to an /api URL) starts the Google sign-in with a 303 to Google. */
+export function handleProspectusSignInStart(request: NextRequest, options: ProspectusSignInRouteOptions = {}): Promise<NextResponse> {
+  return failingClosedWithoutSiteOrigin(() => handleProspectusSignInStartRoute(request, options));
+}
+
+async function handleProspectusSignInStartRoute(request: NextRequest, options: ProspectusSignInRouteOptions): Promise<NextResponse> {
   const runtime = await signInRuntimeFor(request, options);
   if (!runtime) return signInUnavailableResponse();
   const { authorizationUrl, pendingSignIn } = await beginProspectusGoogleSignIn(runtime.accounts, runtime.cognitoClient);
   const pendingSignInCookie: PendingProspectusSignInCookie = {
     ...pendingSignIn,
-    returnPath: sameSiteReturnPath(request.nextUrl.searchParams.get("returnTo")),
+    returnPath: sameSiteReturnPath(await requestedReturnPath(request)),
   };
   const response = NextResponse.redirect(authorizationUrl, { status: 303, headers: NO_STORE_HEADERS });
   response.cookies.set(
@@ -99,7 +151,11 @@ export async function handleProspectusSignInStart(request: NextRequest, options:
   return response;
 }
 
-export async function handleProspectusSignInCallback(request: NextRequest, options: ProspectusSignInRouteOptions = {}): Promise<NextResponse> {
+export function handleProspectusSignInCallback(request: NextRequest, options: ProspectusSignInRouteOptions = {}): Promise<NextResponse> {
+  return failingClosedWithoutSiteOrigin(() => handleProspectusSignInCallbackRoute(request, options));
+}
+
+async function handleProspectusSignInCallbackRoute(request: NextRequest, options: ProspectusSignInRouteOptions): Promise<NextResponse> {
   const runtime = await signInRuntimeFor(request, options);
   if (!runtime) return signInUnavailableResponse();
   const nowInSeconds = currentTimeInSeconds(options);
@@ -121,12 +177,16 @@ async function completeCallback(
   options: ProspectusSignInRouteOptions,
   nowInSeconds: number,
 ): Promise<NextResponse> {
-  if (!pendingSignIn) return signInFailedResponse(401, "sign_in_expired", "This sign-in is no longer pending. Start again.");
+  const failed = (code: string, branch: SignInFailureBranch, detail: { httpStatus?: number; prospectusError?: string; prospectusMessage?: string; errorName?: string } = {}) => {
+    logSignInFailure(options, { code, branch, ...detail });
+    return signInFailedRedirect(request, options, pendingSignIn?.returnPath ?? null, code);
+  };
+  if (!pendingSignIn) return failed("sign_in_expired", "pending_cookie");
   const searchParams = request.nextUrl.searchParams;
-  if (searchParams.get("error")) return signInFailedResponse(401, "sign_in_declined", "Google sign-in did not complete.");
+  if (searchParams.get("error")) return failed("sign_in_declined", "provider_error");
   const authorizationCode = searchParams.get("code");
   const returnedState = searchParams.get("state");
-  if (!authorizationCode || !returnedState) return signInFailedResponse(400, "sign_in_incomplete", "The sign-in response is missing its code or state.");
+  if (!authorizationCode || !returnedState) return failed("sign_in_incomplete", "missing_parameters");
   try {
     const signedIn = await completeProspectusGoogleSignIn({
       accounts: runtime.accounts,
@@ -141,8 +201,9 @@ async function completeCallback(
       personId: signedIn.person.id,
       accessToken: signedIn.accessToken,
       accessTokenExpiresAt: signedIn.accessTokenExpiresAt,
+      ...(signedIn.person.siteSubject ? { siteSubject: signedIn.person.siteSubject } : {}),
     };
-    const response = NextResponse.redirect(new URL(pendingSignIn.returnPath, request.nextUrl.origin), { status: 303, headers: NO_STORE_HEADERS });
+    const response = NextResponse.redirect(new URL(pendingSignIn.returnPath, siteOriginFor(request, options)), { status: 303, headers: NO_STORE_HEADERS });
     response.cookies.set(
       PROSPECTUS_SESSION_COOKIE,
       sealProspectusCookie(runtime.sealingSecret, PROSPECTUS_SESSION_COOKIE, session, session.accessTokenExpiresAt),
@@ -150,13 +211,16 @@ async function completeCallback(
     );
     return response;
   } catch (error) {
-    if (error instanceof ProspectusAccountsError) return signInFailedResponse(error.status, error.code, error.message);
-    console.error(`Prospectus sign-in failed (${error instanceof Error ? error.name : "error"}).`);
-    return signInFailedResponse(401, "sign_in_failed", "Sign-in could not be completed.");
+    if (error instanceof ProspectusAccountsError) return failed(error.code, "completion", { httpStatus: error.status, prospectusError: error.code, prospectusMessage: error.message.slice(0, 300) });
+    return failed("sign_in_failed", "unexpected", { errorName: error instanceof Error ? error.name : "error" });
   }
 }
 
-export async function handleProspectusSessionRead(request: NextRequest, options: ProspectusSignInRouteOptions = {}): Promise<NextResponse> {
+export function handleProspectusSessionRead(request: NextRequest, options: ProspectusSignInRouteOptions = {}): Promise<NextResponse> {
+  return failingClosedWithoutSiteOrigin(() => handleProspectusSessionReadRoute(request, options));
+}
+
+async function handleProspectusSessionReadRoute(request: NextRequest, options: ProspectusSignInRouteOptions): Promise<NextResponse> {
   const runtime = await signInRuntimeFor(request, options);
   if (!runtime) return signInUnavailableResponse();
   const session = signedInProspectusSession(request, runtime.sealingSecret, currentTimeInSeconds(options));
@@ -169,11 +233,10 @@ export async function handleProspectusSessionRead(request: NextRequest, options:
       return response;
     }
     const publishingAccounts = publishingAccountsForSite(directory.accounts, siteProductFor(options));
+    // Only what the UI reads: no person id, siteSubject or account list ever goes to the browser.
     return NextResponse.json(
       {
         signedIn: true,
-        person: directory.person,
-        accounts: directory.accounts,
         cyclotronLabAccess: directory.accounts.some((account) =>
           account.products.some((product) => product.product === CYCLOTRON_LAB_PRODUCT && product.status === "active"),
         ),
@@ -196,9 +259,13 @@ export async function handleProspectusSessionRead(request: NextRequest, options:
   }
 }
 
-export async function handleProspectusSignOut(request: NextRequest, options: ProspectusSignInRouteOptions = {}): Promise<NextResponse> {
+export function handleProspectusSignOut(request: NextRequest, options: ProspectusSignInRouteOptions = {}): Promise<NextResponse> {
+  return failingClosedWithoutSiteOrigin(() => handleProspectusSignOutRoute(request, options));
+}
+
+async function handleProspectusSignOutRoute(request: NextRequest, options: ProspectusSignInRouteOptions): Promise<NextResponse> {
   const runtime = await signInRuntimeFor(request, options);
-  const signedOutDestination = new URL("/", request.nextUrl.origin);
+  const signedOutDestination = new URL("/", siteOriginFor(request, options));
   const destination = runtime
     ? new URL(
       `/logout?${new URLSearchParams({ client_id: runtime.cognitoClient.clientId, logout_uri: signedOutDestination.toString() })}`,
@@ -250,10 +317,14 @@ export async function currentProspectusPublishingSelection(
   }
 }
 
-export async function handleProspectusAccountSelection(request: NextRequest, options: ProspectusSignInRouteOptions = {}): Promise<NextResponse> {
+export function handleProspectusAccountSelection(request: NextRequest, options: ProspectusSignInRouteOptions = {}): Promise<NextResponse> {
+  return failingClosedWithoutSiteOrigin(() => handleProspectusAccountSelectionRoute(request, options));
+}
+
+async function handleProspectusAccountSelectionRoute(request: NextRequest, options: ProspectusSignInRouteOptions): Promise<NextResponse> {
   const runtime = await signInRuntimeFor(request, options);
   if (!runtime) return signInUnavailableResponse();
-  if (request.headers.get("origin") !== request.nextUrl.origin) {
+  if (request.headers.get("origin") !== siteOriginFor(request, options)) {
     return signInFailedResponse(403, "cross_origin_selection", "Choose an account from this site.");
   }
   const nowInSeconds = currentTimeInSeconds(options);
@@ -287,10 +358,14 @@ const MAXIMUM_PUBLISHING_ACCOUNT_NAME_LENGTH = 150;
 const DEFAULT_PUBLISHING_ACCOUNT_NAME = "Publishing account";
 const IDEMPOTENCY_KEY_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
-export async function handleProspectusPublishingAccountCreation(request: NextRequest, options: ProspectusSignInRouteOptions = {}): Promise<NextResponse> {
+export function handleProspectusPublishingAccountCreation(request: NextRequest, options: ProspectusSignInRouteOptions = {}): Promise<NextResponse> {
+  return failingClosedWithoutSiteOrigin(() => handleProspectusPublishingAccountCreationRoute(request, options));
+}
+
+async function handleProspectusPublishingAccountCreationRoute(request: NextRequest, options: ProspectusSignInRouteOptions): Promise<NextResponse> {
   const runtime = await signInRuntimeFor(request, options);
   if (!runtime) return signInUnavailableResponse();
-  if (request.headers.get("origin") !== request.nextUrl.origin) {
+  if (request.headers.get("origin") !== siteOriginFor(request, options)) {
     return signInFailedResponse(403, "cross_origin_creation", "Create an account from this site.");
   }
   const nowInSeconds = currentTimeInSeconds(options);

package/lib/prospectus-site-identity.ts

@@ -24,6 +24,7 @@ export type ProspectusOperation = "console:read" | "console:write" | "members:re
 export interface ProspectusPerson {
   id: string;
   createdAt: string;
+  siteSubject?: string;
 }
 
 export interface ProspectusAccountAuthorization {
@@ -36,6 +37,20 @@ export interface ProspectusAccountAuthorization {
   revision: number;
 }
 
+/** One retired reader site subject, from `GET /v1/accounts/site-subjects/retired` (reader sites only). */
+export interface ProspectusRetiredSiteSubject {
+  siteSubject: string;
+  reason: "deleted" | "merged";
+  survivingSiteSubject?: string;
+  retiredAt: string;
+}
+
+export interface ProspectusRetiredSiteSubjectsPage {
+  retired: ProspectusRetiredSiteSubject[];
+  cursor: string;
+  more: boolean;
+}
+
 export interface ProspectusDirectoryAccount {
   id: string;
   name: string;
@@ -100,8 +115,10 @@ export function signedProspectusTransport(options: SignedProspectusTransportOpti
       ...(payload ? { "content-type": "application/json" } : {}),
     };
     const signer = new SignatureV4({ service: "execute-api", region: options.region, credentials, sha256: Sha256 });
+    // The query string is part of what API Gateway verifies, so it has to be signed as well as sent.
+    const query: Record<string, string> = Object.fromEntries(url.searchParams.entries());
     const signed = await signer.sign(
-      new HttpRequest({ protocol: url.protocol, hostname: url.hostname, path: url.pathname, method, headers, body: payload }),
+      new HttpRequest({ protocol: url.protocol, hostname: url.hostname, path: url.pathname, method, headers, body: payload, query }),
     );
     const response = await fetcher(url, { method, headers: signed.headers, body: payload, cache: "no-store", redirect: "error" });
     const responseBody = await response.json().catch(() => ({}));
@@ -115,19 +132,28 @@ export function signedProspectusTransport(options: SignedProspectusTransportOpti
 export class ProspectusSiteAccounts {
   constructor(private readonly transport: ProspectusTransport) {}
 
-  requestGoogleSignInChallenge(): Promise<{ challengeId: string; nonce: string; expiresAt: number }> {
+  requestGoogleSignInChallenge(): Promise<{ challengeId: string; nonce: string; expiresAt: number; challengeToken?: string }> {
     return this.transport({ path: "/v1/identities/google/challenge", method: "POST", body: {} }) as Promise<{
       challengeId: string;
       nonce: string;
       expiresAt: number;
+      challengeToken?: string;
     }>;
   }
 
-  resolveGoogleSignIn(challengeId: string, humanAccessToken: string, identityToken: string): Promise<{ person: ProspectusPerson }> {
+  /**
+   * When Prospectus signs its challenges it stores nothing, so the signed `challengeToken` is the only proof the
+   * challenge exists and must be sent back unchanged. Without a token (a service that stores challenges) the ID is sent.
+   */
+  resolveGoogleSignIn(
+    challenge: { challengeId: string; challengeToken?: string },
+    humanAccessToken: string,
+    identityToken: string,
+  ): Promise<{ person: ProspectusPerson }> {
     return this.transport({
       path: "/v1/identities/google/resolve",
       method: "POST",
-      body: { challengeId },
+      body: challenge.challengeToken ? { challengeToken: challenge.challengeToken } : { challengeId: challenge.challengeId },
       humanAccessToken,
       identityToken,
     }) as Promise<{ person: ProspectusPerson }>;
@@ -156,6 +182,12 @@ export class ProspectusSiteAccounts {
     }) as Promise<{ account: { id: string; name: string; role: ProspectusRole } }>;
   }
 
+  /** The calling site's retired reader subjects since `since` (omit it the first time): at most 100, oldest first. */
+  retiredSiteSubjects(since?: string): Promise<ProspectusRetiredSiteSubjectsPage> {
+    const query = since ? `?since=${encodeURIComponent(since)}` : "";
+    return this.transport({ path: `/v1/accounts/site-subjects/retired${query}`, method: "GET" }) as Promise<ProspectusRetiredSiteSubjectsPage>;
+  }
+
   accountDirectory(humanAccessToken: string): Promise<{ person: ProspectusPerson | null; accounts: ProspectusDirectoryAccount[] }> {
     return this.transport({ path: "/v1/account-directory", method: "GET", humanAccessToken }) as Promise<{
       person: ProspectusPerson | null;
@@ -174,6 +206,8 @@ export interface GoogleOnlyCognitoClient {
 export interface PendingProspectusSignIn {
   challengeId: string;
   nonce: string;
+  /** The signed challenge from Prospectus, present when it signs challenges instead of storing them. */
+  challengeToken?: string;
   state: string;
   codeVerifier: string;
   expiresAt: number;
@@ -219,7 +253,13 @@ export async function beginProspectusGoogleSignIn(
   }).toString();
   return {
     authorizationUrl: authorizationUrl.toString(),
-    pendingSignIn: { challengeId: challenge.challengeId, nonce: challenge.nonce, state, codeVerifier, expiresAt: challenge.expiresAt },
+    pendingSignIn: {
+      challengeId: challenge.challengeId,
+      nonce: challenge.nonce,
+      ...(challenge.challengeToken ? { challengeToken: challenge.challengeToken } : {}),
+      state, codeVerifier,
+      expiresAt: challenge.expiresAt,
+    },
   };
 }
 
@@ -280,7 +320,7 @@ export async function completeProspectusGoogleSignIn(
     expiresInSeconds: Number(tokenBody.expires_in) || 0,
   };
   await (input.verifyCognitoTokens ?? cognitoTokenVerifier(input.cognitoClient))(tokens, input.pendingSignIn.nonce);
-  const { person } = await input.accounts.resolveGoogleSignIn(input.pendingSignIn.challengeId, tokens.accessToken, tokens.idToken);
+  const { person } = await input.accounts.resolveGoogleSignIn(input.pendingSignIn, tokens.accessToken, tokens.idToken);
   return {
     person,
     accessToken: tokens.accessToken,

package/lib/reader-api.ts

@@ -0,0 +1,145 @@
+import { NextResponse, type NextRequest } from "next/server";
+import { readAmplifyOutputsFile } from "./amplify-outputs-path";
+import { loadProspectusSessionSealingSecret, type ProspectusSignedInSession } from "./prospectus-session";
+import { signedInProspectusSession } from "./prospectus-sign-in-routes";
+import { readerIsStaff, readerSubject } from "./reader-subject";
+import { SiteOriginNotConfiguredError, publicSiteOrigin, siteOriginNotConfiguredResponse } from "./site-origin";
+
+export const READER_ACTIONS_FUNCTION_ENV = "PAPYRUS_READER_ACTIONS_FUNCTION";
+export const READER_MAXIMUM_BODY_BYTES = 4096;
+/** Larger bodies for actions that carry reader text: a URL, a title and a note; a comment of 2,000 characters. */
+export const READER_BODY_BYTES_BY_ACTION: Partial<Record<ReaderAction, number>> = { submit: 8192, comment: 12288, "comment-edit": 12288 };
+export const READER_MAXIMUM_SUBJECTS = 50;
+export const READER_SUBJECT_KEY = /^[A-Za-z0-9._:-]{1,200}$/;
+
+export type ReaderAction = "me" | "handle" | "vote" | "rating" | "submit" | "comment" | "comment-edit" | "comment-delete" | "report" | "flag";
+
+export interface ReaderActionEvent {
+  publication: string;
+  siteSubject: string;
+  isStaff: boolean;
+  action: ReaderAction;
+  payload: Record<string, unknown>;
+}
+
+export interface ReaderActionResult {
+  statusCode: number;
+  body: Record<string, unknown>;
+}
+
+export type ReaderActionInvoker = (functionName: string, event: ReaderActionEvent) => Promise<ReaderActionResult>;
+
+export interface ReaderApiOptions {
+  environment?: Record<string, string | undefined>;
+  invoke?: ReaderActionInvoker;
+  actionsFunctionName?: string | null;
+  loadSealingSecret?: () => Promise<string | null>;
+  nowInSeconds?: number;
+}
+
+const NO_STORE_HEADERS = { "cache-control": "no-store" };
+
+function failure(status: number, error: string, message: string, extra: Record<string, unknown> = {}, headers: Record<string, string> = {}): NextResponse {
+  return NextResponse.json({ error, message, ...extra }, { status, headers: { ...NO_STORE_HEADERS, ...headers } });
+}
+
+export function identityUnavailableResponse(): NextResponse {
+  return failure(503, "reader_identity_unavailable", "Reader sign-in is not open yet.");
+}
+
+function actionsFunctionNameFrom(options: ReaderApiOptions, environment: Record<string, string | undefined>): string | null {
+  if (options.actionsFunctionName !== undefined) return options.actionsFunctionName;
+  const fromEnvironment = (environment[READER_ACTIONS_FUNCTION_ENV] ?? "").trim();
+  if (fromEnvironment) return fromEnvironment;
+  const outputs = readAmplifyOutputsFile() as { custom?: { readerSteering?: { actionsFunction?: unknown } | null } } | null;
+  const fromOutputs = outputs?.custom?.readerSteering?.actionsFunction;
+  return typeof fromOutputs === "string" && fromOutputs.trim() ? fromOutputs.trim() : null;
+}
+
+export async function invokeReaderActionsLambda(functionName: string, event: ReaderActionEvent): Promise<ReaderActionResult> {
+  const { InvokeCommand, LambdaClient } = await import("@aws-sdk/client-lambda");
+  const response = await new LambdaClient({}).send(
+    new InvokeCommand({ FunctionName: functionName, InvocationType: "RequestResponse", Payload: Buffer.from(JSON.stringify(event)) }),
+  );
+  if (response.FunctionError || !response.Payload) throw new Error("reader-actions failed");
+  const result = JSON.parse(Buffer.from(response.Payload).toString("utf8")) as Partial<ReaderActionResult>;
+  if (typeof result.statusCode !== "number" || typeof result.body !== "object" || result.body === null) throw new Error("reader-actions returned an unexpected shape");
+  return { statusCode: result.statusCode, body: result.body as Record<string, unknown> };
+}
+
+async function readJsonBody(request: NextRequest, maximumBytes: number): Promise<{ payload: Record<string, unknown> } | { response: NextResponse }> {
+  const contentType = (request.headers.get("content-type") ?? "").split(";")[0].trim().toLowerCase();
+  if (contentType !== "application/json") return { response: failure(415, "unsupported_media_type", "Send application/json.") };
+  const declared = Number(request.headers.get("content-length") ?? "0");
+  if (Number.isFinite(declared) && declared > maximumBytes) return { response: failure(413, "payload_too_large", "The request body is too large.") };
+  const text = await request.text();
+  if (Buffer.byteLength(text, "utf8") > maximumBytes) return { response: failure(413, "payload_too_large", "The request body is too large.") };
+  try {
+    const parsed = JSON.parse(text) as unknown;
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("not an object");
+    return { payload: parsed as Record<string, unknown> };
+  } catch {
+    return { response: failure(400, "invalid_json", "The request body is not a JSON object.") };
+  }
+}
+
+function subjectsFromQuery(request: NextRequest): { payload: Record<string, unknown> } | { response: NextResponse } {
+  const raw = request.nextUrl.searchParams.get("subjects") ?? "";
+  const subjects = raw === "" ? [] : raw.split(",");
+  if (subjects.length > READER_MAXIMUM_SUBJECTS || !subjects.every((subject) => READER_SUBJECT_KEY.test(subject))) {
+    return { response: failure(400, "invalid_subjects", `Send at most ${READER_MAXIMUM_SUBJECTS} comma separated item keys.`) };
+  }
+  return { payload: { subjects } };
+}
+
+async function signedInReaderSession(request: NextRequest, options: ReaderApiOptions): Promise<ProspectusSignedInSession | null | "unavailable"> {
+  const sealingSecret = await (options.loadSealingSecret ?? (() => loadProspectusSessionSealingSecret({ environment: options.environment })))();
+  if (!sealingSecret) return "unavailable";
+  return signedInProspectusSession(request, sealingSecret, options.nowInSeconds);
+}
+
+/**
+ * One reader route: session, readerSubject (503 while Prospectus has no siteSubject), Origin, JSON size, then the
+ * reader-actions function. The siteSubject only travels to the function and never into a response.
+ */
+export async function handleReaderRequest(request: NextRequest, action: ReaderAction, options: ReaderApiOptions = {}): Promise<NextResponse> {
+  const environment = options.environment ?? process.env;
+  let origin: string;
+  try {
+    origin = publicSiteOrigin(request, environment);
+  } catch (error) {
+    if (error instanceof SiteOriginNotConfiguredError) return siteOriginNotConfiguredResponse(error);
+    throw error;
+  }
+  const session = await signedInReaderSession(request, options);
+  if (session === "unavailable") return identityUnavailableResponse();
+  if (!session) return failure(401, "signed_out", "Sign in to continue.");
+  const siteSubject = readerSubject(session, environment);
+  if (siteSubject === null) return identityUnavailableResponse();
+
+  let parsed: { payload: Record<string, unknown> } | { response: NextResponse };
+  if (action === "me") {
+    parsed = subjectsFromQuery(request);
+  } else {
+    if (request.headers.get("origin") !== origin) return failure(403, "origin_mismatch", "This request did not come from this site.");
+    parsed = await readJsonBody(request, READER_BODY_BYTES_BY_ACTION[action] ?? READER_MAXIMUM_BODY_BYTES);
+  }
+  if ("response" in parsed) return parsed.response;
+
+  const functionName = actionsFunctionNameFrom(options, environment);
+  if (!functionName) return failure(503, "reader_actions_unavailable", "Reader features are not enabled for this site.");
+  try {
+    const result = await (options.invoke ?? invokeReaderActionsLambda)(functionName, {
+      publication: new URL(origin).host,
+      siteSubject,
+      isStaff: readerIsStaff(session),
+      action,
+      payload: parsed.payload,
+    });
+    const retryAfter: Record<string, string> = typeof result.body.retryAfter === "number" ? { "retry-after": String(result.body.retryAfter) } : {};
+    return NextResponse.json(result.body, { status: result.statusCode, headers: { ...NO_STORE_HEADERS, ...retryAfter } });
+  } catch (error) {
+    console.error(`Reader action ${action} failed (${error instanceof Error ? error.name : "error"}).`);
+    return failure(502, "reader_actions_failed", "Reader features could not be reached.");
+  }
+}