@anthusai/papyrus 5.19.0 → 5.20.0

package/infra/amplify-app-shell.js

@@ -4,7 +4,7 @@ import * as amplify from "aws-cdk-lib/aws-amplify";
 import { SecureStringParameter } from "./secure-string-parameter.js";
 import { GITHUB_OIDC_PROVIDER_HOST } from "./github-oidc-provider.js";
 import { cmsProductionBuildSpec, cmsStagingBuildSpec, readerBuildSpec } from "./build-specs.js";
-import { PROSPECTUS_PAPYRUS_SITE_ROUTES, hasCmsApp, isStagingEnabled, resolveRedirectSubDomainPrefix, resolveCmsHostName, resolveSiteOrigin, githubOidcSubjects, resolveGithubRepository, resolveProspectusAccountsEndpoint, resolveProspectusSessionSealingParameterName, resolveRevalidateSecretParameterName, resolveStackName, resolveStagingDomainName, resolveStoragePreviewPrefix } from "./site-config.js";
+import { PROSPECTUS_PAPYRUS_SITE_ROUTES, hasCmsApp, isStagingEnabled, resolveRedirectSubDomainPrefix, resolveCmsHostName, resolveSiteOrigin, githubOidcSubjects, resolveGithubRepository, resolveProspectusAccountsEndpoint, resolveProspectusSessionSealingParameterName, resolveReaderPollSecretParameterName, resolveRevalidateSecretParameterName, resolveStackName, resolveStagingDomainName, resolveStoragePreviewPrefix } from "./site-config.js";
 function environmentVariables(variables) {
     return Object.entries(variables).map(([name, value]) => ({ name, value }));
 }
@@ -123,6 +123,20 @@ export class AmplifyAppShellStack extends Stack {
                 resources: [prospectusSessionSealing.parameterArn],
             }));
         }
+        if (prospectusAccountsApiStageArn && config.cms.readerRetirementPoll) {
+            // Prospectus admits one caller per site, this compute role, so the scheduled snapshot run reaches the retired-subject
+            // route through the CMS route /api/reader/retired, which it authenticates with this secret.
+            const readerPollSecret = new SecureStringParameter(this, "ReaderPollSecretParameter", {
+                parameterName: resolveReaderPollSecretParameterName(config),
+                description: `Authorizes the scheduled reader snapshot run to call the retired-subject route of ${cmsAppName}`,
+            });
+            prospectusEnvironment.PAPYRUS_READER_POLL_SECRET_PARAMETER = readerPollSecret.parameterName;
+            computeRole.addToPolicy(new iam.PolicyStatement({
+                sid: "ReadReaderPollSecret",
+                actions: ["ssm:GetParameter"],
+                resources: [readerPollSecret.parameterArn],
+            }));
+        }
         if (prospectusAccountsApiStageArn) {
             computeRole.addToPolicy(new iam.PolicyStatement({
                 sid: "InvokeProspectusAccountsAsRegisteredSite",

package/infra/amplify-app-shell.ts

@@ -5,7 +5,7 @@ import * as amplify from "aws-cdk-lib/aws-amplify";
 import { SecureStringParameter } from "./secure-string-parameter";
 import { GITHUB_OIDC_PROVIDER_HOST } from "./github-oidc-provider";
 import { cmsProductionBuildSpec, cmsStagingBuildSpec, readerBuildSpec } from "./build-specs";
-import { AmplifyAppShellSiteConfig, PROSPECTUS_PAPYRUS_SITE_ROUTES, ReaderCustomHeaderRule, hasCmsApp, isStagingEnabled, resolveRedirectSubDomainPrefix, resolveCmsHostName, resolveSiteOrigin, githubOidcSubjects, resolveGithubRepository, resolveProspectusAccountsEndpoint, resolveProspectusSessionSealingParameterName, resolveRevalidateSecretParameterName, resolveStackName, resolveStagingDomainName, resolveStoragePreviewPrefix } from "./site-config";
+import { AmplifyAppShellSiteConfig, PROSPECTUS_PAPYRUS_SITE_ROUTES, ReaderCustomHeaderRule, hasCmsApp, isStagingEnabled, resolveRedirectSubDomainPrefix, resolveCmsHostName, resolveSiteOrigin, githubOidcSubjects, resolveGithubRepository, resolveProspectusAccountsEndpoint, resolveProspectusSessionSealingParameterName, resolveReaderPollSecretParameterName, resolveRevalidateSecretParameterName, resolveStackName, resolveStagingDomainName, resolveStoragePreviewPrefix } from "./site-config";
 
 function environmentVariables(variables: Record<string, string>): amplify.CfnBranch.EnvironmentVariableProperty[] {
   return Object.entries(variables).map(([name, value]) => ({ name, value }));
@@ -136,6 +136,22 @@ export class AmplifyAppShellStack extends Stack {
         }),
       );
     }
+    if (prospectusAccountsApiStageArn && config.cms.readerRetirementPoll) {
+      // Prospectus admits one caller per site, this compute role, so the scheduled snapshot run reaches the retired-subject
+      // route through the CMS route /api/reader/retired, which it authenticates with this secret.
+      const readerPollSecret = new SecureStringParameter(this, "ReaderPollSecretParameter", {
+        parameterName: resolveReaderPollSecretParameterName(config),
+        description: `Authorizes the scheduled reader snapshot run to call the retired-subject route of ${cmsAppName}`,
+      });
+      prospectusEnvironment.PAPYRUS_READER_POLL_SECRET_PARAMETER = readerPollSecret.parameterName;
+      computeRole.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "ReadReaderPollSecret",
+          actions: ["ssm:GetParameter"],
+          resources: [readerPollSecret.parameterArn],
+        }),
+      );
+    }
     if (prospectusAccountsApiStageArn) {
       computeRole.addToPolicy(
         new iam.PolicyStatement({

package/infra/site-config.js

@@ -35,7 +35,7 @@ const GITHUB_REPO_PATTERN = /^[A-Za-z0-9_.-]+$/;
 const COGNITO_DOMAIN_PREFIX_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
 const COGNITO_RESERVED_WORDS = ["aws", "amazon", "cognito"];
 const PROSPECTUS_ACCOUNTS_API_STAGE_ARN_PATTERN = /^arn:aws:execute-api:[a-z0-9-]+:\d{12}:[a-z0-9]+\/api$/;
-const TEMPLATE_MANAGED_ENVIRONMENT_KEYS = ["PAPYRUS_COGNITO_DOMAIN_PREFIX", "PAPYRUS_APPLY_COGNITO_DOMAIN_PREFIX", "PAPYRUS_DISABLE_GOOGLE_OAUTH", "PAPYRUS_REVALIDATE_SECRET_PARAMETER", "PAPYRUS_PROSPECTUS_ACCOUNTS_ENDPOINT", "PAPYRUS_PROSPECTUS_SESSION_SECRET_PARAMETER", "PAPYRUS_PROSPECTUS_SITE_PRODUCT", "PAPYRUS_SITE_ORIGIN"];
+const TEMPLATE_MANAGED_ENVIRONMENT_KEYS = ["PAPYRUS_COGNITO_DOMAIN_PREFIX", "PAPYRUS_APPLY_COGNITO_DOMAIN_PREFIX", "PAPYRUS_DISABLE_GOOGLE_OAUTH", "PAPYRUS_REVALIDATE_SECRET_PARAMETER", "PAPYRUS_PROSPECTUS_ACCOUNTS_ENDPOINT", "PAPYRUS_PROSPECTUS_SESSION_SECRET_PARAMETER", "PAPYRUS_PROSPECTUS_SITE_PRODUCT", "PAPYRUS_READER_POLL_SECRET_PARAMETER", "PAPYRUS_SITE_ORIGIN"];
 /** Routes Prospectus admits for a registered Papyrus site (Prospectus accounts/papyrus-sites.ts). */
 export const PROSPECTUS_PAPYRUS_SITE_ROUTES = [
     "GET/v1/identities/me",
@@ -63,6 +63,9 @@ function originOfRedirectUrl(value) {
 export function resolveProspectusSessionSealingParameterName(config) {
     return `/papyrus/${config.siteId}/prospectus-session-sealing`;
 }
+export function resolveReaderPollSecretParameterName(config) {
+    return `/papyrus/${config.siteId}/reader-poll-secret`;
+}
 export function resolveRevalidateSecretParameterName(config) {
     return `/papyrus/${config.siteId}/revalidate-secret`;
 }
@@ -222,7 +225,7 @@ function parseStagingPreview(value) {
 }
 function parseCms(value) {
     const cmsRecord = requireObject(value, "cms");
-    rejectUnknownKeys(cmsRecord, ["appName", "domainName", "staging", "cognitoDomainPrefix", "applyCognitoDomainPrefix", "buildComputeType", "environment", "stagingDomainName", "domainPrefix", "siteOrigin", "stagingDomainPrefix", "redirects", "stagingPreview", "prospectusAccountsApiStageArn", "deployStackInBuild"], "cms");
+    rejectUnknownKeys(cmsRecord, ["appName", "domainName", "staging", "cognitoDomainPrefix", "applyCognitoDomainPrefix", "buildComputeType", "environment", "stagingDomainName", "domainPrefix", "siteOrigin", "stagingDomainPrefix", "redirects", "stagingPreview", "prospectusAccountsApiStageArn", "readerRetirementPoll", "deployStackInBuild"], "cms");
     const buildComputeType = cmsRecord.buildComputeType;
     if (buildComputeType !== undefined && buildComputeType !== "STANDARD" && buildComputeType !== "STANDARD_8GB") {
         fail("cms.buildComputeType", `must be "STANDARD" or "STANDARD_8GB", got ${JSON.stringify(buildComputeType)}`);
@@ -233,6 +236,12 @@ function parseCms(value) {
     if (cmsRecord.applyCognitoDomainPrefix !== undefined && typeof cmsRecord.applyCognitoDomainPrefix !== "boolean") {
         fail("cms.applyCognitoDomainPrefix", `must be a boolean, got ${JSON.stringify(cmsRecord.applyCognitoDomainPrefix)}`);
     }
+    if (cmsRecord.readerRetirementPoll !== undefined && typeof cmsRecord.readerRetirementPoll !== "boolean") {
+        fail("cms.readerRetirementPoll", `must be a boolean, got ${JSON.stringify(cmsRecord.readerRetirementPoll)}`);
+    }
+    if (cmsRecord.readerRetirementPoll === true && cmsRecord.prospectusAccountsApiStageArn === undefined) {
+        fail("cms.readerRetirementPoll", "requires cms.prospectusAccountsApiStageArn: the poll calls Prospectus as the site");
+    }
     if (cmsRecord.deployStackInBuild !== undefined && typeof cmsRecord.deployStackInBuild !== "boolean") {
         fail("cms.deployStackInBuild", `must be a boolean, got ${JSON.stringify(cmsRecord.deployStackInBuild)}`);
     }
@@ -250,6 +259,7 @@ function parseCms(value) {
         stagingDomainPrefix: optionalString(cmsRecord.stagingDomainPrefix, "cms.stagingDomainPrefix", DOMAIN_PREFIX_PATTERN, "single DNS label"),
         redirects: parseRedirects(cmsRecord.redirects),
         deployStackInBuild: cmsRecord.deployStackInBuild,
+        readerRetirementPoll: cmsRecord.readerRetirementPoll,
         stagingPreview: parseStagingPreview(cmsRecord.stagingPreview),
         prospectusAccountsApiStageArn: optionalString(cmsRecord.prospectusAccountsApiStageArn, "cms.prospectusAccountsApiStageArn", PROSPECTUS_ACCOUNTS_API_STAGE_ARN_PATTERN, "arn:aws:execute-api:<region>:<account>:<api id>/api"),
     };

package/infra/site-config.ts

@@ -44,6 +44,12 @@ export type CmsConfig = {
   stagingDomainPrefix?: string;
   redirects?: CmsRedirect[];
   prospectusAccountsApiStageArn?: string;
+  /**
+   * The site is a public-reader site that polls Prospectus for retired reader subjects. The template then generates a
+   * shared secret that the scheduled snapshot run presents to the CMS route `/api/reader/retired` (requires
+   * `prospectusAccountsApiStageArn`; docs/reader-steering.md).
+   */
+  readerRetirementPoll?: boolean;
   deployStackInBuild?: boolean;
 };
 
@@ -146,7 +152,7 @@ const GITHUB_REPO_PATTERN = /^[A-Za-z0-9_.-]+$/;
 const COGNITO_DOMAIN_PREFIX_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
 const COGNITO_RESERVED_WORDS = ["aws", "amazon", "cognito"];
 const PROSPECTUS_ACCOUNTS_API_STAGE_ARN_PATTERN = /^arn:aws:execute-api:[a-z0-9-]+:\d{12}:[a-z0-9]+\/api$/;
-const TEMPLATE_MANAGED_ENVIRONMENT_KEYS = ["PAPYRUS_COGNITO_DOMAIN_PREFIX", "PAPYRUS_APPLY_COGNITO_DOMAIN_PREFIX", "PAPYRUS_DISABLE_GOOGLE_OAUTH", "PAPYRUS_REVALIDATE_SECRET_PARAMETER", "PAPYRUS_PROSPECTUS_ACCOUNTS_ENDPOINT", "PAPYRUS_PROSPECTUS_SESSION_SECRET_PARAMETER", "PAPYRUS_PROSPECTUS_SITE_PRODUCT", "PAPYRUS_SITE_ORIGIN"];
+const TEMPLATE_MANAGED_ENVIRONMENT_KEYS = ["PAPYRUS_COGNITO_DOMAIN_PREFIX", "PAPYRUS_APPLY_COGNITO_DOMAIN_PREFIX", "PAPYRUS_DISABLE_GOOGLE_OAUTH", "PAPYRUS_REVALIDATE_SECRET_PARAMETER", "PAPYRUS_PROSPECTUS_ACCOUNTS_ENDPOINT", "PAPYRUS_PROSPECTUS_SESSION_SECRET_PARAMETER", "PAPYRUS_PROSPECTUS_SITE_PRODUCT", "PAPYRUS_READER_POLL_SECRET_PARAMETER", "PAPYRUS_SITE_ORIGIN"];
 
 /** Routes Prospectus admits for a registered Papyrus site (Prospectus accounts/papyrus-sites.ts). */
 export const PROSPECTUS_PAPYRUS_SITE_ROUTES = [
@@ -177,6 +183,10 @@ export function resolveProspectusSessionSealingParameterName(config: Pick<Amplif
   return `/papyrus/${config.siteId}/prospectus-session-sealing`;
 }
 
+export function resolveReaderPollSecretParameterName(config: Pick<AmplifyAppShellSiteConfig, "siteId">): string {
+  return `/papyrus/${config.siteId}/reader-poll-secret`;
+}
+
 export function resolveRevalidateSecretParameterName(config: Pick<AmplifyAppShellSiteConfig, "siteId">): string {
   return `/papyrus/${config.siteId}/revalidate-secret`;
 }
@@ -336,7 +346,7 @@ function parseStagingPreview(value: unknown): StagingPreviewConfig | undefined {
 
 function parseCms(value: unknown): CmsConfig {
   const cmsRecord = requireObject(value, "cms");
-  rejectUnknownKeys(cmsRecord, ["appName", "domainName", "staging", "cognitoDomainPrefix", "applyCognitoDomainPrefix", "buildComputeType", "environment", "stagingDomainName", "domainPrefix", "siteOrigin", "stagingDomainPrefix", "redirects", "stagingPreview", "prospectusAccountsApiStageArn", "deployStackInBuild"], "cms");
+  rejectUnknownKeys(cmsRecord, ["appName", "domainName", "staging", "cognitoDomainPrefix", "applyCognitoDomainPrefix", "buildComputeType", "environment", "stagingDomainName", "domainPrefix", "siteOrigin", "stagingDomainPrefix", "redirects", "stagingPreview", "prospectusAccountsApiStageArn", "readerRetirementPoll", "deployStackInBuild"], "cms");
   const buildComputeType = cmsRecord.buildComputeType;
   if (buildComputeType !== undefined && buildComputeType !== "STANDARD" && buildComputeType !== "STANDARD_8GB") {
     fail("cms.buildComputeType", `must be "STANDARD" or "STANDARD_8GB", got ${JSON.stringify(buildComputeType)}`);
@@ -347,6 +357,12 @@ function parseCms(value: unknown): CmsConfig {
   if (cmsRecord.applyCognitoDomainPrefix !== undefined && typeof cmsRecord.applyCognitoDomainPrefix !== "boolean") {
     fail("cms.applyCognitoDomainPrefix", `must be a boolean, got ${JSON.stringify(cmsRecord.applyCognitoDomainPrefix)}`);
   }
+  if (cmsRecord.readerRetirementPoll !== undefined && typeof cmsRecord.readerRetirementPoll !== "boolean") {
+    fail("cms.readerRetirementPoll", `must be a boolean, got ${JSON.stringify(cmsRecord.readerRetirementPoll)}`);
+  }
+  if (cmsRecord.readerRetirementPoll === true && cmsRecord.prospectusAccountsApiStageArn === undefined) {
+    fail("cms.readerRetirementPoll", "requires cms.prospectusAccountsApiStageArn: the poll calls Prospectus as the site");
+  }
   if (cmsRecord.deployStackInBuild !== undefined && typeof cmsRecord.deployStackInBuild !== "boolean") {
     fail("cms.deployStackInBuild", `must be a boolean, got ${JSON.stringify(cmsRecord.deployStackInBuild)}`);
   }
@@ -369,6 +385,7 @@ function parseCms(value: unknown): CmsConfig {
     stagingDomainPrefix: optionalString(cmsRecord.stagingDomainPrefix, "cms.stagingDomainPrefix", DOMAIN_PREFIX_PATTERN, "single DNS label"),
     redirects: parseRedirects(cmsRecord.redirects),
     deployStackInBuild: cmsRecord.deployStackInBuild as boolean | undefined,
+    readerRetirementPoll: cmsRecord.readerRetirementPoll as boolean | undefined,
     stagingPreview: parseStagingPreview(cmsRecord.stagingPreview),
     prospectusAccountsApiStageArn: optionalString(
       cmsRecord.prospectusAccountsApiStageArn,

package/lib/editorial-checks.ts

@@ -38,7 +38,8 @@ export type EditorialSegment = {
   text?: string;
 };
 
-export type LaneStatus = { status: "ran" | "disabled" | "unavailable" | "failed" | "partial"; reason?: string; detectors?: number };
+/** "skipped": Papyrus did not ask for judgments because the publication has no mission or policy for them to apply. */
+export type LaneStatus = { status: "ran" | "disabled" | "unavailable" | "failed" | "partial" | "skipped"; reason?: string; detectors?: number };
 
 export type EditorialCheckResult = {
   schemaVersion: 1;
@@ -49,7 +50,8 @@ export type EditorialCheckResult = {
   protected: { kind: string; start: number; end: number }[];
   findings: EditorialFinding[];
   coverage: unknown[];
-  lanes: { rules: LaneStatus; classifier: LaneStatus };
+  /** lanes.section is "skipped" when the story's section has no NewsroomSection record to take a mission and policy from. */
+  lanes: { rules: LaneStatus; classifier: LaneStatus; section?: LaneStatus };
   usage?: Record<string, number>;
 };
 
@@ -164,8 +166,10 @@ export function describeProbability(finding: EditorialFinding): string | null {
 
 export function laneNotice(result: EditorialCheckResult): string | null {
   const classifier = result.lanes.classifier;
+  if (classifier.status === "skipped") return `Mission-based checks skipped: ${classifier.reason ?? "this publication has no mission yet"}.`;
   if (classifier.status === "partial") return `Some sentences were not judged: ${classifier.reason ?? "the check ran out of time"}.`;
   if (classifier.status === "failed") return `The judgment checks failed: ${classifier.reason ?? "unknown error"}. Rule checks still ran.`;
   if (classifier.status === "unavailable" && (classifier.detectors ?? 0) === 0 && classifier.reason) return `Judgment checks are not configured: ${classifier.reason}.`;
+  if (result.lanes.section?.status === "skipped") return `Section-based checks skipped: ${result.lanes.section.reason ?? "no section configuration"}.`;
   return null;
 }

package/lib/prospectus-session.ts

@@ -39,6 +39,7 @@ export interface ProspectusSignedInSession {
   accessToken: string;
   accessTokenExpiresAt: number;
   selectedAccountId?: string;
+  siteSubject?: string;
 }
 
 function sealingKeyForCookie(sealingSecret: string, cookieName: string): Buffer {

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

@@ -166,6 +166,7 @@ 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, siteOriginFor(request, options)), { status: 303, headers: NO_STORE_HEADERS });
     response.cookies.set(
@@ -198,11 +199,10 @@ async function handleProspectusSessionReadRoute(request: NextRequest, options: P
       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"),
         ),

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(() => ({}));
@@ -156,6 +173,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;

package/lib/reader-api.ts

@@ -0,0 +1,143 @@
+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;
+export const READER_MAXIMUM_SUBJECTS = 50;
+export const READER_SUBJECT_KEY = /^[A-Za-z0-9._:-]{1,200}$/;
+
+export type ReaderAction = "me" | "handle" | "vote" | "rating";
+
+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): 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 > READER_MAXIMUM_BODY_BYTES) return { response: failure(413, "payload_too_large", "The request body is too large.") };
+  const text = await request.text();
+  if (Buffer.byteLength(text, "utf8") > READER_MAXIMUM_BODY_BYTES) 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);
+  }
+  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.");
+  }
+}

package/lib/reader-retirement-route.ts

@@ -0,0 +1,89 @@
+import { NextResponse, type NextRequest } from "next/server";
+import { GetParameterCommand, SSMClient } from "@aws-sdk/client-ssm";
+import { SiteOriginNotConfiguredError, publicSiteOrigin, siteOriginNotConfiguredResponse } from "./site-origin";
+import { resolveProspectusSignInRuntime, type ProspectusSignInRuntime } from "./prospectus-session";
+import { ProspectusAccountsError } from "./prospectus-site-identity";
+import { secretsMatch } from "./revalidate-secret";
+
+export const READER_POLL_SECRET_PARAMETER_ENV = "PAPYRUS_READER_POLL_SECRET_PARAMETER";
+export const READER_POLL_SECRET_HEADER = "x-papyrus-reader-poll-secret";
+export const READER_POLL_SECRET_CACHE_MILLISECONDS = 5 * 60 * 1000;
+const CURSOR_PATTERN = /^[A-Za-z0-9._~=+/-]{1,512}$/;
+const NO_STORE_HEADERS = { "cache-control": "no-store" };
+
+export interface ReaderRetirementRouteOptions {
+  environment?: Record<string, string | undefined>;
+  readSecret?: (parameterName: string) => Promise<string | null>;
+  resolveRuntime?: (siteOrigin: string) => Promise<Pick<ProspectusSignInRuntime, "accounts"> | null>;
+  now?: number;
+}
+
+type CachedSecret = { parameterName: string; value: string; expiresAt: number };
+let cachedSecret: CachedSecret | null = null;
+let defaultSsmClient: SSMClient | null = null;
+
+export function resetReaderPollSecretCache(): void {
+  cachedSecret = null;
+}
+
+async function readSecretFromSsm(parameterName: string): Promise<string | null> {
+  defaultSsmClient ??= new SSMClient({});
+  const response = await defaultSsmClient.send(new GetParameterCommand({ Name: parameterName, WithDecryption: true }));
+  return response.Parameter?.Value?.trim() || null;
+}
+
+async function loadReaderPollSecret(options: ReaderRetirementRouteOptions, environment: Record<string, string | undefined>): Promise<string | null> {
+  const parameterName = environment[READER_POLL_SECRET_PARAMETER_ENV]?.trim();
+  if (!parameterName) return null;
+  const now = options.now ?? Date.now();
+  if (cachedSecret && cachedSecret.parameterName === parameterName && cachedSecret.expiresAt > now) return cachedSecret.value;
+  try {
+    const value = (await (options.readSecret ?? readSecretFromSsm)(parameterName))?.trim();
+    if (!value) return null;
+    cachedSecret = { parameterName, value, expiresAt: now + READER_POLL_SECRET_CACHE_MILLISECONDS };
+    return value;
+  } catch (error) {
+    console.error(`Reader poll secret could not be read (${error instanceof Error ? error.name : "error"}).`);
+    return null;
+  }
+}
+
+function failure(status: number, error: string, message: string): NextResponse {
+  return NextResponse.json({ error, message }, { status, headers: NO_STORE_HEADERS });
+}
+
+/**
+ * The scheduled snapshot run's way to Prospectus's retired-subject route. Prospectus admits one caller per site, this
+ * app's compute role, so the run cannot call it directly: it calls this route with a shared secret from SSM, and the route
+ * calls Prospectus as the compute role and passes the answer through. Anyone without the secret gets 401, and a site
+ * without the secret parameter gets 503, so this is never open.
+ */
+export async function handleReaderRetiredSubjects(request: NextRequest, options: ReaderRetirementRouteOptions = {}): Promise<NextResponse> {
+  const environment = options.environment ?? process.env;
+  const expected = await loadReaderPollSecret(options, environment);
+  if (!expected) return failure(503, "reader_poll_unavailable", "The retirement poll is not configured for this site.");
+  if (!secretsMatch(request.headers.get(READER_POLL_SECRET_HEADER), expected)) return failure(401, "unauthorized", "Missing or wrong poll secret.");
+
+  const since = request.nextUrl.searchParams.get("since") ?? undefined;
+  const unknownParameters = [...request.nextUrl.searchParams.keys()].filter((key) => key !== "since");
+  if (unknownParameters.length > 0 || (since !== undefined && !CURSOR_PATTERN.test(since))) {
+    return failure(400, "invalid_since", "Send only a since cursor.");
+  }
+  let siteOrigin: string;
+  try {
+    siteOrigin = publicSiteOrigin(request, environment);
+  } catch (error) {
+    if (error instanceof SiteOriginNotConfiguredError) return siteOriginNotConfiguredResponse(error);
+    throw error;
+  }
+  const runtime = await (options.resolveRuntime ?? ((origin) => resolveProspectusSignInRuntime(origin, { environment })))(siteOrigin);
+  if (!runtime) return failure(503, "prospectus_sign_in_unavailable", "Prospectus is not configured for this site.");
+  try {
+    const page = await runtime.accounts.retiredSiteSubjects(since);
+    return NextResponse.json({ retired: page.retired, cursor: page.cursor, more: page.more }, { headers: NO_STORE_HEADERS });
+  } catch (error) {
+    if (error instanceof ProspectusAccountsError) return failure(error.status === 400 ? 400 : 502, error.code, error.message);
+    console.error(`Prospectus retired subjects failed (${error instanceof Error ? error.name : "error"}).`);
+    return failure(502, "prospectus_unavailable", "Prospectus could not be reached.");
+  }
+}

package/lib/reader-subject.md

@@ -0,0 +1,29 @@
+# Reader subject
+
+`readerSubject(session)` in `reader-subject.ts` is the only place a reader's identity for the reader API is
+decided. It returns the per-site pairwise `siteSubject` (`ss1_` plus 43 base64url characters) that Prospectus
+puts on `person.siteSubject`, or `null`.
+
+## Production
+
+Only the `siteSubject` the sealed session cookie carries counts. While Prospectus does not return one, the
+accessor returns `null`, every reader route answers `503 reader_identity_unavailable`, and the reader features
+stay off. There is no other flag. The global Prospectus person id is never used as a reader key.
+
+## Development and test only
+
+When `SITE_ENV` is `development` or `test`, `NODE_ENV` is not `production` and `PAPYRUS_READER_DEV_SECRET`
+holds at least 16 characters, a session without a `siteSubject` gets the interim value
+`ssdev_` plus `base64url(HMAC-SHA-256(devSecret, personId))`.
+
+That path never runs in production. No remap from `ssdev_` values to `ss1_` values is ever needed: production
+reader writes stay closed until `siteSubject` is live, so no production row is ever keyed on an interim value.
+The `reader-actions` function also refuses `ssdev_` subjects unless the site was synthesized with a
+development or test `SITE_ENV`.
+
+## Staff
+
+`readerIsStaff(session)` reads the `cognito:groups` claim from the access token inside the sealed session
+cookie (`editor` or `admin`). The cookie is written by the site's own callback route, so the token is trusted
+the way the rest of the session is. The reader API passes the result to the function as `isStaff`; clients never
+send it.

package/lib/reader-subject.ts

@@ -0,0 +1,53 @@
+import { createHmac } from "node:crypto";
+import type { ProspectusSignedInSession } from "./prospectus-session";
+
+export const SITE_SUBJECT_PATTERN = /^ss1_[A-Za-z0-9_-]{43}$/;
+export const INTERIM_SUBJECT_PATTERN = /^ssdev_[A-Za-z0-9_-]{43}$/;
+export const READER_DEV_SECRET_ENV = "PAPYRUS_READER_DEV_SECRET";
+export const READER_STAFF_GROUPS = ["editor", "admin"] as const;
+
+const MINIMUM_DEV_SECRET_LENGTH = 16;
+const INTERIM_SUBJECT_PREFIX = "ssdev_";
+const INTERIM_ENVIRONMENTS = ["development", "test"];
+
+type EnvironmentVariables = Record<string, string | undefined>;
+
+export function interimSubjectsAllowed(environment: EnvironmentVariables = process.env): boolean {
+  if (environment.NODE_ENV === "production") return false;
+  const siteEnvironment = (environment.SITE_ENV ?? "").trim();
+  if (!INTERIM_ENVIRONMENTS.includes(siteEnvironment)) return false;
+  return (environment[READER_DEV_SECRET_ENV] ?? "").length >= MINIMUM_DEV_SECRET_LENGTH;
+}
+
+export function interimSubject(personId: string, devSecret: string): string {
+  return INTERIM_SUBJECT_PREFIX + createHmac("sha256", devSecret).update(personId).digest("base64url");
+}
+
+/**
+ * The reader's per-site pairwise id, or null. Production reads only the siteSubject Prospectus returned;
+ * the interim `ssdev_` value exists in development and test only (lib/reader-subject.md).
+ */
+export function readerSubject(
+  session: Pick<ProspectusSignedInSession, "personId" | "siteSubject"> | null | undefined,
+  environment: EnvironmentVariables = process.env,
+): string | null {
+  if (!session) return null;
+  if (typeof session.siteSubject === "string" && SITE_SUBJECT_PATTERN.test(session.siteSubject)) return session.siteSubject;
+  if (!interimSubjectsAllowed(environment) || !session.personId) return null;
+  return interimSubject(session.personId, environment[READER_DEV_SECRET_ENV] as string);
+}
+
+/** Staff membership from the Cognito groups claim of the access token that the sealed session cookie carries. */
+export function readerIsStaff(session: Pick<ProspectusSignedInSession, "accessToken"> | null | undefined): boolean {
+  const token = session?.accessToken;
+  if (typeof token !== "string") return false;
+  const payload = token.split(".")[1];
+  if (!payload) return false;
+  try {
+    const claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf8")) as { "cognito:groups"?: unknown };
+    const groups = claims["cognito:groups"];
+    return Array.isArray(groups) && groups.some((group) => (READER_STAFF_GROUPS as readonly unknown[]).includes(group));
+  } catch {
+    return false;
+  }
+}