@anthusai/papyrus 1.0.0-next.50 → 1.0.0-next.51

package/amplify/data/resource.js

@@ -12,7 +12,7 @@ import { emailSubmissionProcessor } from "../functions/email-submission-processo
 import { sesInboundReceive } from "../functions/ses-inbound-receive/resource.js";
 import { slackDelivery } from "../functions/slack-delivery/resource.js";
 import { slackEvents } from "../functions/slack-events/resource.js";
-import { schema as leanSchema } from "./schema.js";
+import { schema as leanSchema, schemaWithPlugins } from "./schema.js";
 const authoringOperations = [
     "read",
     "create",
@@ -2009,13 +2009,19 @@ const schema = a.schema({
     allow.resource(slackEvents),
     allow.resource(slackDelivery),
 ]);
-export const data = defineData({
-    name: "PapyrusCmsApi",
-    schema: leanSchema,
-    authorizationModes: {
-        defaultAuthorizationMode: "userPool",
-        apiKeyAuthorizationMode: {
-            expiresInDays: 365,
+/**
+ * The site's data API. Amplify allows one `defineData` per backend and registers it when called, so this is
+ * a function: a site without plugins passes none and gets exactly the base schema.
+ */
+export function defineSiteData(pluginDefinitions = {}) {
+    return defineData({
+        name: "PapyrusCmsApi",
+        schema: Object.keys(pluginDefinitions).length === 0 ? leanSchema : schemaWithPlugins(pluginDefinitions),
+        authorizationModes: {
+            defaultAuthorizationMode: "userPool",
+            apiKeyAuthorizationMode: {
+                expiresInDays: 365,
+            },
         },
-    },
-});
+    });
+}

package/amplify/data/resource.ts

@@ -12,7 +12,7 @@ import { emailSubmissionProcessor } from "../functions/email-submission-processo
 import { sesInboundReceive } from "../functions/ses-inbound-receive/resource";
 import { slackDelivery } from "../functions/slack-delivery/resource";
 import { slackEvents } from "../functions/slack-events/resource";
-import { schema as leanSchema } from "./schema";
+import { schema as leanSchema, schemaWithPlugins } from "./schema";
 const authoringOperations: ("read" | "create" | "update" | "delete")[] = [
   "read",
   "create",
@@ -2125,13 +2125,19 @@ const schema = a.schema({
 
 export type Schema = ClientSchema<typeof schema>;
 
-export const data = defineData({
-  name: "PapyrusCmsApi",
-  schema: leanSchema,
-  authorizationModes: {
-    defaultAuthorizationMode: "userPool",
-    apiKeyAuthorizationMode: {
-      expiresInDays: 365,
+/**
+ * The site's data API. Amplify allows one `defineData` per backend and registers it when called, so this is
+ * a function: a site without plugins passes none and gets exactly the base schema.
+ */
+export function defineSiteData(pluginDefinitions: Record<string, unknown> = {}) {
+  return defineData({
+    name: "PapyrusCmsApi",
+    schema: Object.keys(pluginDefinitions).length === 0 ? leanSchema : schemaWithPlugins(pluginDefinitions),
+    authorizationModes: {
+      defaultAuthorizationMode: "userPool",
+      apiKeyAuthorizationMode: {
+        expiresInDays: 365,
+      },
     },
-  },
-});
+  });
+}

package/amplify/data/schema.js

@@ -20,7 +20,7 @@ const categoryWriteGroups = ["editor", "admin"];
 const categoryAppendOnlyOperations = ["read", "create"];
 const modelWithoutSubscriptions = (fields) => a.model(fields).disableOperations(["subscriptions"]);
 const realtimeModel = (fields) => a.model(fields);
-export const schema = a.schema({
+const baseDefinitions = {
     UserProfile: modelWithoutSubscriptions({
         id: a.id().required(),
         email: a.email(),
@@ -1841,7 +1841,8 @@ export const schema = a.schema({
         allow.guest().to(["read"]),
         allow.groups(contentWriteGroups),
     ]),
-}).authorization((allow) => [
+};
+export const schema = a.schema(baseDefinitions).authorization((allow) => [
     allow.resource(categoryAction),
     allow.resource(contentActions),
     allow.resource(manageUserRole),
@@ -1849,3 +1850,14 @@ export const schema = a.schema({
     allow.resource(newsroomSummary),
     allow.resource(procedureAction),
 ]);
+/** The deployed schema of a site that enables plugins: the base definitions plus what each plugin contributes (docs/plugins.md). */
+export function schemaWithPlugins(pluginDefinitions) {
+    return a.schema({ ...baseDefinitions, ...pluginDefinitions }).authorization((allow) => [
+        allow.resource(categoryAction),
+        allow.resource(contentActions),
+        allow.resource(manageUserRole),
+        allow.resource(modelAttachmentUpload),
+        allow.resource(newsroomSummary),
+        allow.resource(procedureAction),
+    ]);
+}

package/amplify/data/schema.ts

@@ -23,7 +23,7 @@ const modelWithoutSubscriptions = <Fields extends Parameters<typeof a.model>[0]>
   a.model(fields).disableOperations(["subscriptions"]);
 const realtimeModel = <Fields extends Parameters<typeof a.model>[0]>(fields: Fields) => a.model(fields);
 
-export const schema = a.schema({
+const baseDefinitions = {
   UserProfile: modelWithoutSubscriptions({
       id: a.id().required(),
       email: a.email(),
@@ -1947,7 +1947,9 @@ export const schema = a.schema({
       allow.guest().to(["read"]),
       allow.groups(contentWriteGroups),
     ]),
-}).authorization((allow) => [
+};
+
+export const schema = a.schema(baseDefinitions).authorization((allow) => [
   allow.resource(categoryAction),
   allow.resource(contentActions),
   allow.resource(manageUserRole),
@@ -1956,4 +1958,16 @@ export const schema = a.schema({
   allow.resource(procedureAction),
 ]);
 
+/** The deployed schema of a site that enables plugins: the base definitions plus what each plugin contributes (docs/plugins.md). */
+export function schemaWithPlugins(pluginDefinitions: Record<string, any>) {
+  return a.schema({ ...baseDefinitions, ...pluginDefinitions } as typeof baseDefinitions).authorization((allow) => [
+    allow.resource(categoryAction),
+    allow.resource(contentActions),
+    allow.resource(manageUserRole),
+    allow.resource(modelAttachmentUpload),
+    allow.resource(newsroomSummary),
+    allow.resource(procedureAction),
+  ]);
+}
+
 export type Schema = ClientSchema<typeof schema>;

package/amplify/plugins/registry.js

@@ -0,0 +1,19 @@
+import { signupPlugin } from "./signup/papyrus.plugin.js";
+/** Plugins are packaged with Papyrus and pinned by its version: there is no registry to fetch from. */
+export const KNOWN_PLUGINS = {
+    signup: signupPlugin,
+};
+export function resolvePlugins(requests) {
+    const resolved = [];
+    for (const request of requests ?? []) {
+        const name = typeof request === "string" ? request : request.name;
+        const plugin = KNOWN_PLUGINS[name];
+        if (plugin === undefined) {
+            throw new Error(`Unknown plugin "${name}". Known plugins: ${Object.keys(KNOWN_PLUGINS).join(", ")}`);
+        }
+        if (resolved.some((entry) => entry.plugin.manifest.name === name))
+            throw new Error(`Plugin "${name}" is listed twice.`);
+        resolved.push({ plugin, config: plugin.resolveConfig(request) });
+    }
+    return resolved;
+}

package/amplify/plugins/registry.ts

@@ -0,0 +1,23 @@
+import type { PapyrusPlugin, PluginRequest } from "./types";
+import { signupPlugin } from "./signup/papyrus.plugin";
+
+/** Plugins are packaged with Papyrus and pinned by its version: there is no registry to fetch from. */
+export const KNOWN_PLUGINS: Record<string, PapyrusPlugin<any, any>> = {
+  signup: signupPlugin,
+};
+
+export type ResolvedPlugin = { plugin: PapyrusPlugin<any, any>; config: unknown };
+
+export function resolvePlugins(requests: PluginRequest[] | undefined): ResolvedPlugin[] {
+  const resolved: ResolvedPlugin[] = [];
+  for (const request of requests ?? []) {
+    const name = typeof request === "string" ? request : request.name;
+    const plugin = KNOWN_PLUGINS[name];
+    if (plugin === undefined) {
+      throw new Error(`Unknown plugin "${name}". Known plugins: ${Object.keys(KNOWN_PLUGINS).join(", ")}`);
+    }
+    if (resolved.some((entry) => entry.plugin.manifest.name === name)) throw new Error(`Plugin "${name}" is listed twice.`);
+    resolved.push({ plugin, config: plugin.resolveConfig(request) });
+  }
+  return resolved;
+}

package/amplify/plugins/signup/function/handler.py

@@ -0,0 +1,200 @@
+"""submitSignup: the only operation of the signup plugin that a guest can call.
+
+A guest sends a form name and an email-like value. This handler throttles the
+caller, validates and length-limits every argument, drops honeypot and too-fast
+submissions without telling the sender, and writes one SignupEntry through the
+GraphQL API under an id derived from the content, so repeating a submission
+changes nothing. Guests never read entries back.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Callable
+
+STATUS_ACCEPTED = "accepted"
+STATUS_INVALID = "invalid"
+STATUS_EXPIRED = "expired"
+STATUS_THROTTLED = "throttled"
+
+MAXIMUM_ARGUMENT_CHARACTERS = 1000
+MAXIMUM_VALUE_CHARACTERS = 254
+MINIMUM_FILL_SECONDS = 2
+MAXIMUM_AGE_SECONDS = 24 * 60 * 60
+RATE_WINDOW_SECONDS = 60
+COUNTER_LIFETIME_SECONDS = 5 * 60
+DEFAULT_ADDRESS_LIMIT_PER_WINDOW = 20
+DEFAULT_IDENTITY_LIMIT_PER_WINDOW = 5
+FORBIDDEN_FIRST_CHARACTERS = "=+-@"
+FORM_NAME = re.compile(r"[a-z0-9][a-z0-9-]{0,39}")
+RENDERED_AT = re.compile(r"[0-9]{1,16}")
+LABEL = r"[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?"
+EMAIL_LIKE = re.compile(rf"[A-Za-z0-9.!#$%&'*+/=?^_`{{|}}~-]{{1,64}}@{LABEL}(?:\.{LABEL})+")
+CREATE_ENTRY_MUTATION = (
+    "mutation CreateSignupEntry($input: CreateSignupEntryInput!) { createSignupEntry(input: $input) { id } }"
+)
+ALREADY_STORED_MARKERS = ("ConditionalCheckFailed", "conditional request failed")
+
+
+@dataclass(frozen=True)
+class SignupSettings:
+    forms: frozenset[str]
+    address_limit: int = DEFAULT_ADDRESS_LIMIT_PER_WINDOW
+    identity_limit: int = DEFAULT_IDENTITY_LIMIT_PER_WINDOW
+
+
+def settings_from_environment(environment: dict[str, str] | None = None) -> SignupSettings:
+    environment = os.environ if environment is None else environment
+    forms = frozenset(name.strip() for name in environment.get("PAPYRUS_SIGNUP_FORMS", "").split(",") if name.strip())
+    return SignupSettings(
+        forms=forms,
+        address_limit=int(environment.get("PAPYRUS_SIGNUP_ADDRESS_LIMIT", DEFAULT_ADDRESS_LIMIT_PER_WINDOW)),
+        identity_limit=int(environment.get("PAPYRUS_SIGNUP_IDENTITY_LIMIT", DEFAULT_IDENTITY_LIMIT_PER_WINDOW)),
+    )
+
+
+def result(status: str, message: str = "") -> dict[str, str]:
+    return {"status": status, "message": message}
+
+
+def normalized_value(value: str) -> str:
+    local, _, domain = value.partition("@")
+    return f"{local}@{domain.lower()}"
+
+
+def entry_identifier(form: str, value: str) -> str:
+    return hashlib.sha256(f"{form}\n{normalized_value(value)}".encode("utf-8")).hexdigest()[:32]
+
+
+def valid_value(value: str) -> bool:
+    return (
+        0 < len(value) <= MAXIMUM_VALUE_CHARACTERS
+        and value[0] not in FORBIDDEN_FIRST_CHARACTERS
+        and EMAIL_LIKE.fullmatch(value) is not None
+    )
+
+
+def caller_address(identity: dict[str, Any] | None) -> str:
+    """The last of AppSync's sourceIp list: the connection's address. A sender-supplied x-forwarded-for only adds earlier entries."""
+    addresses = [str(address).strip() for address in (identity or {}).get("sourceIp") or [] if str(address).strip()]
+    return addresses[-1] if addresses else "unknown"
+
+
+def rate_key(kind: str, subject: str, now_seconds: float) -> str:
+    window = int(now_seconds // RATE_WINDOW_SECONDS)
+    return f"{kind}#{hashlib.sha256(subject.encode('utf-8')).hexdigest()[:24]}#{window}"
+
+
+def parse_rendered_at(text: str) -> float | None:
+    return int(text) / 1000.0 if RENDERED_AT.fullmatch(text) else None
+
+
+def submit_signup(
+    arguments: dict[str, Any],
+    *,
+    address: str,
+    identity_id: str | None,
+    now_seconds: float,
+    settings: SignupSettings,
+    count_hit: Callable[[str, int], int],
+    store_entry: Callable[[dict[str, str]], bool],
+) -> dict[str, str]:
+    if count_hit(rate_key("address", address, now_seconds), COUNTER_LIFETIME_SECONDS) > settings.address_limit:
+        return result(STATUS_THROTTLED, "Too many requests. Try again in a minute.")
+    if identity_id and count_hit(rate_key("identity", identity_id, now_seconds), COUNTER_LIFETIME_SECONDS) > settings.identity_limit:
+        return result(STATUS_THROTTLED, "Too many requests. Try again in a minute.")
+
+    form, value = arguments.get("form"), arguments.get("value")
+    honeypot, rendered_at = arguments.get("website"), arguments.get("renderedAt")
+    texts = [form, value, honeypot, rendered_at]
+    if any(text is not None and not isinstance(text, str) for text in texts):
+        return result(STATUS_INVALID, "Malformed request.")
+    if any(text is not None and len(text) > MAXIMUM_ARGUMENT_CHARACTERS for text in texts):
+        return result(STATUS_INVALID, "Request too large.")
+    if not isinstance(form, str) or not FORM_NAME.fullmatch(form) or form not in settings.forms:
+        return result(STATUS_INVALID, "Unknown form.")
+    if not isinstance(value, str) or not valid_value(value):
+        return result(STATUS_INVALID, "Enter a valid email address.")
+    rendered_seconds = parse_rendered_at(rendered_at) if isinstance(rendered_at, str) else None
+    if rendered_seconds is None:
+        return result(STATUS_INVALID, "Malformed request.")
+    age_seconds = now_seconds - rendered_seconds
+    if age_seconds > MAXIMUM_AGE_SECONDS:
+        return result(STATUS_EXPIRED, "This form has expired. Reload the page and try again.")
+    if honeypot or age_seconds < MINIMUM_FILL_SECONDS:
+        return result(STATUS_ACCEPTED)
+
+    submitted_at = datetime.fromtimestamp(now_seconds, tz=timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.000Z")
+    store_entry(
+        {
+            "id": entry_identifier(form, value),
+            "form": form,
+            "value": normalized_value(value),
+            "submittedAt": submitted_at,
+        }
+    )
+    return result(STATUS_ACCEPTED)
+
+
+def counting_hits(table_name: str, client: Any = None) -> Callable[[str, int], int]:
+    import boto3
+
+    table_client = client or boto3.client("dynamodb")
+
+    def count_hit(key: str, lifetime_seconds: int) -> int:
+        response = table_client.update_item(
+            TableName=table_name,
+            Key={"pk": {"S": key}},
+            UpdateExpression="ADD hits :one SET expiresAt = :expires",
+            ExpressionAttributeValues={
+                ":one": {"N": "1"},
+                ":expires": {"N": str(int(time.time()) + lifetime_seconds)},
+            },
+            ReturnValues="UPDATED_NEW",
+        )
+        return int(response["Attributes"]["hits"]["N"])
+
+    return count_hit
+
+
+def storing_entries(endpoint: str, region: str) -> Callable[[dict[str, str]], bool]:
+    import boto3
+    from botocore.auth import SigV4Auth
+    from botocore.awsrequest import AWSRequest
+
+    def store_entry(entry: dict[str, str]) -> bool:
+        body = json.dumps({"query": CREATE_ENTRY_MUTATION, "variables": {"input": entry}}).encode("utf-8")
+        request = AWSRequest(method="POST", url=endpoint, data=body, headers={"content-type": "application/json"})
+        SigV4Auth(boto3.Session().get_credentials().get_frozen_credentials(), "appsync", region).add_auth(request)
+        http_request = urllib.request.Request(endpoint, data=body, headers=dict(request.headers.items()), method="POST")
+        with urllib.request.urlopen(http_request, timeout=10) as response:
+            payload = json.loads(response.read())
+        errors = payload.get("errors") or []
+        if not errors:
+            return True
+        if all(any(marker in str(error) for marker in ALREADY_STORED_MARKERS) for error in errors):
+            return False
+        raise RuntimeError(f"createSignupEntry failed: {errors}")
+
+    return store_entry
+
+
+def handler(event: dict[str, Any], _context: Any = None) -> dict[str, str]:
+    identity = event.get("identity") or {}
+    return submit_signup(
+        event.get("arguments") or {},
+        address=caller_address(identity),
+        identity_id=identity.get("cognitoIdentityId"),
+        now_seconds=time.time(),
+        settings=settings_from_environment(),
+        count_hit=counting_hits(os.environ["PAPYRUS_SIGNUP_RATE_TABLE"]),
+        store_entry=storing_entries(os.environ["PAPYRUS_GRAPHQL_ENDPOINT"], os.environ["AWS_REGION"]),
+    )

package/amplify/plugins/signup/function/resource.js

@@ -0,0 +1,27 @@
+import { defineFunction } from "@aws-amplify/backend";
+import { Duration, RemovalPolicy } from "aws-cdk-lib";
+import { AttributeType, BillingMode, Table } from "aws-cdk-lib/aws-dynamodb";
+import { Effect, PolicyStatement } from "aws-cdk-lib/aws-iam";
+import { Architecture, Code, Function, Runtime } from "aws-cdk-lib/aws-lambda";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const functionDirectory = path.dirname(fileURLToPath(import.meta.url));
+export const signupSubmit = defineFunction((scope) => {
+    const rateTable = new Table(scope, "PapyrusSignupRateCounters", {
+        partitionKey: { name: "pk", type: AttributeType.STRING },
+        billingMode: BillingMode.PAY_PER_REQUEST,
+        timeToLiveAttribute: "expiresAt",
+        removalPolicy: RemovalPolicy.DESTROY,
+    });
+    const lambda = new Function(scope, "papyrus-signup-submit", {
+        runtime: Runtime.PYTHON_3_12,
+        architecture: Architecture.ARM_64,
+        handler: "handler.handler",
+        timeout: Duration.seconds(10),
+        memorySize: 256,
+        code: Code.fromAsset(functionDirectory, { exclude: ["*.ts", "__pycache__", "*.pyc"] }),
+        environment: { PAPYRUS_SIGNUP_RATE_TABLE: rateTable.tableName },
+    });
+    lambda.addToRolePolicy(new PolicyStatement({ effect: Effect.ALLOW, actions: ["dynamodb:UpdateItem"], resources: [rateTable.tableArn] }));
+    return lambda;
+}, { resourceGroupName: "data" });

package/amplify/plugins/signup/function/resource.ts

@@ -0,0 +1,35 @@
+import { defineFunction } from "@aws-amplify/backend";
+import { Duration, RemovalPolicy } from "aws-cdk-lib";
+import { AttributeType, BillingMode, Table } from "aws-cdk-lib/aws-dynamodb";
+import { Effect, PolicyStatement } from "aws-cdk-lib/aws-iam";
+import { Architecture, Code, Function, Runtime } from "aws-cdk-lib/aws-lambda";
+import type { Construct } from "constructs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const functionDirectory = path.dirname(fileURLToPath(import.meta.url));
+
+export const signupSubmit = defineFunction(
+  (scope: Construct) => {
+    const rateTable = new Table(scope, "PapyrusSignupRateCounters", {
+      partitionKey: { name: "pk", type: AttributeType.STRING },
+      billingMode: BillingMode.PAY_PER_REQUEST,
+      timeToLiveAttribute: "expiresAt",
+      removalPolicy: RemovalPolicy.DESTROY,
+    });
+    const lambda = new Function(scope, "papyrus-signup-submit", {
+      runtime: Runtime.PYTHON_3_12,
+      architecture: Architecture.ARM_64,
+      handler: "handler.handler",
+      timeout: Duration.seconds(10),
+      memorySize: 256,
+      code: Code.fromAsset(functionDirectory, { exclude: ["*.ts", "__pycache__", "*.pyc"] }),
+      environment: { PAPYRUS_SIGNUP_RATE_TABLE: rateTable.tableName },
+    });
+    lambda.addToRolePolicy(
+      new PolicyStatement({ effect: Effect.ALLOW, actions: ["dynamodb:UpdateItem"], resources: [rateTable.tableArn] }),
+    );
+    return lambda;
+  },
+  { resourceGroupName: "data" },
+);

package/amplify/plugins/signup/papyrus.plugin.js

@@ -0,0 +1,59 @@
+import { Stack } from "aws-cdk-lib";
+import { Effect, PolicyStatement } from "aws-cdk-lib/aws-iam";
+import { signupSubmit } from "./function/resource.js";
+import { signupSchemaDefinitions } from "./schema.js";
+import { SIGNUP_MUTATION_FIELD, WAF_MINIMUM_RATE_LIMIT, addSignupRateLimit } from "./waf.js";
+const FORM_NAME = /^[a-z0-9][a-z0-9-]{0,39}$/;
+const KNOWN_KEYS = new Set(["name", "forms", "addressLimitPerMinute", "waf"]);
+export const signupManifest = {
+    name: "signup",
+    contract: 1,
+    models: ["SignupEntry"],
+    mutations: [SIGNUP_MUTATION_FIELD],
+    guest: { mutations: [SIGNUP_MUTATION_FIELD] },
+    newsroomPanels: [{ id: "signups", label: "Signups" }],
+    staticAssets: ["_plugins/papyrus-signup@1.js"],
+};
+export function resolveSignupConfig(request) {
+    const raw = typeof request === "string" ? { name: request } : request;
+    const unknown = Object.keys(raw).filter((key) => !KNOWN_KEYS.has(key));
+    if (unknown.length > 0)
+        throw new Error(`Unknown signup plugin settings: ${unknown.join(", ")}`);
+    const forms = raw.forms ?? ["newsletter"];
+    if (!Array.isArray(forms) || forms.length === 0 || !forms.every((form) => typeof form === "string" && FORM_NAME.test(form))) {
+        throw new Error("signup plugin forms must be a non-empty list of lowercase names (letters, digits, hyphens; at most 40 characters)");
+    }
+    const addressLimitPerMinute = raw.addressLimitPerMinute ?? 20;
+    if (!Number.isInteger(addressLimitPerMinute) || addressLimitPerMinute < WAF_MINIMUM_RATE_LIMIT || addressLimitPerMinute > 1000) {
+        throw new Error(`signup plugin addressLimitPerMinute must be an integer from ${WAF_MINIMUM_RATE_LIMIT} to 1000`);
+    }
+    const waf = raw.waf ?? true;
+    if (typeof waf !== "boolean")
+        throw new Error("signup plugin waf must be a boolean");
+    return { forms: [...new Set(forms)], addressLimitPerMinute, waf };
+}
+export const signupPlugin = {
+    manifest: signupManifest,
+    resolveConfig: resolveSignupConfig,
+    functions: () => ({ signupSubmit }),
+    schemaDefinitions: signupSchemaDefinitions,
+    publicSettings: (config) => ({ contract: signupManifest.contract, forms: config.forms }),
+    wire(backend, config, context) {
+        const lambda = backend.signupSubmit.resources.lambda;
+        const stack = Stack.of(lambda);
+        lambda.addEnvironment("PAPYRUS_GRAPHQL_ENDPOINT", context.graphqlEndpoint);
+        lambda.addEnvironment("PAPYRUS_SIGNUP_FORMS", config.forms.join(","));
+        lambda.addEnvironment("PAPYRUS_SIGNUP_ADDRESS_LIMIT", String(config.addressLimitPerMinute));
+        lambda.addToRolePolicy(new PolicyStatement({
+            effect: Effect.ALLOW,
+            actions: ["appsync:GraphQL"],
+            resources: [`arn:aws:appsync:${stack.region}:${stack.account}:apis/${context.graphqlApiId}/types/Mutation/fields/createSignupEntry`],
+        }));
+        if (config.waf) {
+            addSignupRateLimit(context.createStack("signup-protection"), {
+                graphqlApiArn: `arn:aws:appsync:${stack.region}:${stack.account}:apis/${context.graphqlApiId}`,
+                limit: config.addressLimitPerMinute,
+            });
+        }
+    },
+};

package/amplify/plugins/signup/papyrus.plugin.ts

@@ -0,0 +1,74 @@
+import { Stack } from "aws-cdk-lib";
+import { Effect, PolicyStatement } from "aws-cdk-lib/aws-iam";
+import type { Function as LambdaFunction } from "aws-cdk-lib/aws-lambda";
+import type { PapyrusPlugin, PluginManifest, PluginRequest, PluginWiringContext } from "../types";
+import { signupSubmit } from "./function/resource";
+import { signupSchemaDefinitions } from "./schema";
+import { SIGNUP_MUTATION_FIELD, WAF_MINIMUM_RATE_LIMIT, addSignupRateLimit } from "./waf";
+
+export type SignupPluginConfig = {
+  /** Form names the site accepts. A submission naming any other form is rejected. */
+  forms: string[];
+  /** Most submissions one address may make in a minute: enforced by the function and, with `waf`, by the web ACL. */
+  addressLimitPerMinute: number;
+  /** A regional web ACL with a rate-based rule on the API (about 6 USD a month). Off: the function's counters only. */
+  waf: boolean;
+};
+
+const FORM_NAME = /^[a-z0-9][a-z0-9-]{0,39}$/;
+const KNOWN_KEYS = new Set(["name", "forms", "addressLimitPerMinute", "waf"]);
+
+export const signupManifest: PluginManifest = {
+  name: "signup",
+  contract: 1,
+  models: ["SignupEntry"],
+  mutations: [SIGNUP_MUTATION_FIELD],
+  guest: { mutations: [SIGNUP_MUTATION_FIELD] },
+  newsroomPanels: [{ id: "signups", label: "Signups" }],
+  staticAssets: ["_plugins/papyrus-signup@1.js"],
+};
+
+export function resolveSignupConfig(request: PluginRequest): SignupPluginConfig {
+  const raw = typeof request === "string" ? { name: request } : request;
+  const unknown = Object.keys(raw).filter((key) => !KNOWN_KEYS.has(key));
+  if (unknown.length > 0) throw new Error(`Unknown signup plugin settings: ${unknown.join(", ")}`);
+  const forms = (raw.forms as string[] | undefined) ?? ["newsletter"];
+  if (!Array.isArray(forms) || forms.length === 0 || !forms.every((form) => typeof form === "string" && FORM_NAME.test(form))) {
+    throw new Error("signup plugin forms must be a non-empty list of lowercase names (letters, digits, hyphens; at most 40 characters)");
+  }
+  const addressLimitPerMinute = (raw.addressLimitPerMinute as number | undefined) ?? 20;
+  if (!Number.isInteger(addressLimitPerMinute) || addressLimitPerMinute < WAF_MINIMUM_RATE_LIMIT || addressLimitPerMinute > 1000) {
+    throw new Error(`signup plugin addressLimitPerMinute must be an integer from ${WAF_MINIMUM_RATE_LIMIT} to 1000`);
+  }
+  const waf = (raw.waf as boolean | undefined) ?? true;
+  if (typeof waf !== "boolean") throw new Error("signup plugin waf must be a boolean");
+  return { forms: [...new Set(forms)], addressLimitPerMinute, waf };
+}
+
+export const signupPlugin: PapyrusPlugin<SignupPluginConfig, { signupSubmit: typeof signupSubmit }> = {
+  manifest: signupManifest,
+  resolveConfig: resolveSignupConfig,
+  functions: () => ({ signupSubmit }),
+  schemaDefinitions: signupSchemaDefinitions,
+  publicSettings: (config) => ({ contract: signupManifest.contract, forms: config.forms }),
+  wire(backend, config, context: PluginWiringContext) {
+    const lambda = backend.signupSubmit.resources.lambda as LambdaFunction;
+    const stack = Stack.of(lambda);
+    lambda.addEnvironment("PAPYRUS_GRAPHQL_ENDPOINT", context.graphqlEndpoint);
+    lambda.addEnvironment("PAPYRUS_SIGNUP_FORMS", config.forms.join(","));
+    lambda.addEnvironment("PAPYRUS_SIGNUP_ADDRESS_LIMIT", String(config.addressLimitPerMinute));
+    lambda.addToRolePolicy(
+      new PolicyStatement({
+        effect: Effect.ALLOW,
+        actions: ["appsync:GraphQL"],
+        resources: [`arn:aws:appsync:${stack.region}:${stack.account}:apis/${context.graphqlApiId}/types/Mutation/fields/createSignupEntry`],
+      }),
+    );
+    if (config.waf) {
+      addSignupRateLimit(context.createStack("signup-protection"), {
+        graphqlApiArn: `arn:aws:appsync:${stack.region}:${stack.account}:apis/${context.graphqlApiId}`,
+        limit: config.addressLimitPerMinute,
+      });
+    }
+  },
+};

package/amplify/plugins/signup/schema.js

@@ -0,0 +1,40 @@
+import { a } from "@aws-amplify/backend";
+import { signupSubmit } from "./function/resource.js";
+/**
+ * SignupEntry is never guest-readable and has no create rule for anyone: only the
+ * submitSignup function (IAM) writes it. Editors and admins list it; admins delete.
+ */
+export function signupSchemaDefinitions() {
+    return {
+        SignupEntry: a
+            .model({
+            id: a.id().required(),
+            form: a.string().required(),
+            value: a.string().required(),
+            submittedAt: a.datetime().required(),
+        })
+            .disableOperations(["subscriptions"])
+            .secondaryIndexes((index) => [
+            index("form").sortKeys(["submittedAt"]).queryField("listSignupEntriesByFormAndSubmittedAt"),
+        ])
+            .authorization((allow) => [
+            allow.group("editor").to(["read"]),
+            allow.group("admin").to(["read", "delete"]),
+        ]),
+        SignupReceipt: a.customType({
+            status: a.string().required(),
+            message: a.string(),
+        }),
+        submitSignup: a
+            .mutation()
+            .arguments({
+            form: a.string().required(),
+            value: a.string().required(),
+            renderedAt: a.string().required(),
+            website: a.string(),
+        })
+            .returns(a.ref("SignupReceipt"))
+            .authorization((allow) => [allow.guest()])
+            .handler(a.handler.function(signupSubmit)),
+    };
+}

package/amplify/plugins/signup/schema.ts

@@ -0,0 +1,41 @@
+import { a } from "@aws-amplify/backend";
+import { signupSubmit } from "./function/resource";
+
+/**
+ * SignupEntry is never guest-readable and has no create rule for anyone: only the
+ * submitSignup function (IAM) writes it. Editors and admins list it; admins delete.
+ */
+export function signupSchemaDefinitions() {
+  return {
+    SignupEntry: a
+      .model({
+        id: a.id().required(),
+        form: a.string().required(),
+        value: a.string().required(),
+        submittedAt: a.datetime().required(),
+      })
+      .disableOperations(["subscriptions"])
+      .secondaryIndexes((index) => [
+        index("form").sortKeys(["submittedAt"]).queryField("listSignupEntriesByFormAndSubmittedAt"),
+      ])
+      .authorization((allow) => [
+        allow.group("editor").to(["read"]),
+        allow.group("admin").to(["read", "delete"]),
+      ]),
+    SignupReceipt: a.customType({
+      status: a.string().required(),
+      message: a.string(),
+    }),
+    submitSignup: a
+      .mutation()
+      .arguments({
+        form: a.string().required(),
+        value: a.string().required(),
+        renderedAt: a.string().required(),
+        website: a.string(),
+      })
+      .returns(a.ref("SignupReceipt"))
+      .authorization((allow) => [allow.guest()])
+      .handler(a.handler.function(signupSubmit)),
+  };
+}

package/amplify/plugins/signup/waf.js

@@ -0,0 +1,48 @@
+import { CfnWebACL, CfnWebACLAssociation } from "aws-cdk-lib/aws-wafv2";
+export const SIGNUP_MUTATION_FIELD = "submitSignup";
+export const WAF_MINIMUM_RATE_LIMIT = 10;
+export const WAF_EVALUATION_WINDOW_SECONDS = 60;
+/**
+ * A regional web ACL on the AppSync API with one rate-based rule: more than `limit`
+ * submitSignup requests from one address in a minute are blocked with a 429 before
+ * the function runs. Only requests whose body names the mutation count, so reads,
+ * newsroom saves and CLI imports from the same address are never limited.
+ */
+export function addSignupRateLimit(scope, input) {
+    if (!Number.isInteger(input.limit) || input.limit < WAF_MINIMUM_RATE_LIMIT) {
+        throw new Error(`signup waf rate limit must be an integer of at least ${WAF_MINIMUM_RATE_LIMIT} (AWS WAF minimum)`);
+    }
+    const acl = new CfnWebACL(scope, "PapyrusSignupWebAcl", {
+        scope: "REGIONAL",
+        defaultAction: { allow: {} },
+        visibilityConfig: { cloudWatchMetricsEnabled: true, metricName: "PapyrusSignupWebAcl", sampledRequestsEnabled: true },
+        rules: [
+            {
+                name: "SignupRateLimitPerAddress",
+                priority: 0,
+                action: { block: { customResponse: { responseCode: 429 } } },
+                visibilityConfig: { cloudWatchMetricsEnabled: true, metricName: "SignupRateLimitPerAddress", sampledRequestsEnabled: true },
+                statement: {
+                    rateBasedStatement: {
+                        limit: input.limit,
+                        evaluationWindowSec: WAF_EVALUATION_WINDOW_SECONDS,
+                        aggregateKeyType: "IP",
+                        scopeDownStatement: {
+                            byteMatchStatement: {
+                                searchString: SIGNUP_MUTATION_FIELD,
+                                positionalConstraint: "CONTAINS",
+                                fieldToMatch: { body: { oversizeHandling: "NO_MATCH" } },
+                                textTransformations: [{ priority: 0, type: "NONE" }],
+                            },
+                        },
+                    },
+                },
+            },
+        ],
+    });
+    new CfnWebACLAssociation(scope, "PapyrusSignupWebAclAssociation", {
+        resourceArn: input.graphqlApiArn,
+        webAclArn: acl.attrArn,
+    });
+    return acl;
+}

package/amplify/plugins/signup/waf.ts

@@ -0,0 +1,51 @@
+import { CfnWebACL, CfnWebACLAssociation } from "aws-cdk-lib/aws-wafv2";
+import type { Construct } from "constructs";
+
+export const SIGNUP_MUTATION_FIELD = "submitSignup";
+export const WAF_MINIMUM_RATE_LIMIT = 10;
+export const WAF_EVALUATION_WINDOW_SECONDS = 60;
+
+/**
+ * A regional web ACL on the AppSync API with one rate-based rule: more than `limit`
+ * submitSignup requests from one address in a minute are blocked with a 429 before
+ * the function runs. Only requests whose body names the mutation count, so reads,
+ * newsroom saves and CLI imports from the same address are never limited.
+ */
+export function addSignupRateLimit(scope: Construct, input: { graphqlApiArn: string; limit: number }): CfnWebACL {
+  if (!Number.isInteger(input.limit) || input.limit < WAF_MINIMUM_RATE_LIMIT) {
+    throw new Error(`signup waf rate limit must be an integer of at least ${WAF_MINIMUM_RATE_LIMIT} (AWS WAF minimum)`);
+  }
+  const acl = new CfnWebACL(scope, "PapyrusSignupWebAcl", {
+    scope: "REGIONAL",
+    defaultAction: { allow: {} },
+    visibilityConfig: { cloudWatchMetricsEnabled: true, metricName: "PapyrusSignupWebAcl", sampledRequestsEnabled: true },
+    rules: [
+      {
+        name: "SignupRateLimitPerAddress",
+        priority: 0,
+        action: { block: { customResponse: { responseCode: 429 } } },
+        visibilityConfig: { cloudWatchMetricsEnabled: true, metricName: "SignupRateLimitPerAddress", sampledRequestsEnabled: true },
+        statement: {
+          rateBasedStatement: {
+            limit: input.limit,
+            evaluationWindowSec: WAF_EVALUATION_WINDOW_SECONDS,
+            aggregateKeyType: "IP",
+            scopeDownStatement: {
+              byteMatchStatement: {
+                searchString: SIGNUP_MUTATION_FIELD,
+                positionalConstraint: "CONTAINS",
+                fieldToMatch: { body: { oversizeHandling: "NO_MATCH" } },
+                textTransformations: [{ priority: 0, type: "NONE" }],
+              },
+            },
+          },
+        },
+      },
+    ],
+  });
+  new CfnWebACLAssociation(scope, "PapyrusSignupWebAclAssociation", {
+    resourceArn: input.graphqlApiArn,
+    webAclArn: acl.attrArn,
+  });
+  return acl;
+}

package/amplify/plugins/types.js

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

package/amplify/plugins/types.ts

@@ -0,0 +1,39 @@
+import type { Construct } from "constructs";
+
+/** How a site asks for a plugin in `papyrus.config.ts`: `plugins: ["signup"]` or `plugins: [{ name: "signup", forms: ["news"] }]`. */
+export type PluginRequest = string | ({ name: string } & Record<string, unknown>);
+
+/** What a plugin declares about itself. A test pins the schema, the guest rules and the static files to this. */
+export type PluginManifest = {
+  name: string;
+  /** Public contract version. Bump it when a mutation input, a model field, an element name or an attribute changes. No compatibility shims. */
+  contract: number;
+  models: string[];
+  mutations: string[];
+  /** What an anonymous visitor may call. Everything else is closed to guests. */
+  guest: { mutations: string[] };
+  newsroomPanels: { id: string; label: string }[];
+  /** Keys the projector writes into the site bucket when the plugin is enabled. */
+  staticAssets: string[];
+};
+
+/** Where the deploy-time wiring puts its resources. Filled in by `defineSiteBackend`. */
+export type PluginWiringContext = {
+  createStack: (name: string) => Construct;
+  graphqlApiId: string;
+  graphqlEndpoint: string;
+};
+
+export type PapyrusPlugin<Config, Functions = unknown> = {
+  manifest: PluginManifest;
+  /** Validates the request and fills in defaults. Throws a readable error. */
+  resolveConfig: (request: PluginRequest) => Config;
+  /** Amplify function resources the plugin adds to `defineBackend`. */
+  functions: () => Functions;
+  /** Models and custom operations merged into the site schema. */
+  schemaDefinitions: () => Record<string, unknown>;
+  /** The settings the newsroom and the page component may read from `amplify_outputs.json` (`custom.papyrusPlugins.<name>`). Never secrets. */
+  publicSettings: (config: Config) => Record<string, unknown>;
+  /** Everything that needs the backend to exist: IAM, environment, WAF, outputs. */
+  wire: (backend: any, config: Config, context: PluginWiringContext) => void;
+};

package/amplify/plugins/wire.js

@@ -0,0 +1,24 @@
+export const PLUGINS_ENVIRONMENT_VARIABLE = "PAPYRUS_PLUGINS";
+export const PLUGINS_OUTPUT_KEY = "papyrusPlugins";
+/**
+ * Deploy-time wiring for every enabled plugin. A site without plugins reaches no line of this:
+ * nothing is added to the stacks, the environment or the outputs.
+ */
+export function wirePlugins(backend, plugins, contentActionsLambda) {
+    if (plugins.length === 0)
+        return;
+    const graphqlApi = backend.data.resources.graphqlApi;
+    const context = {
+        createStack: (name) => backend.createStack(name),
+        graphqlApiId: graphqlApi.apiId,
+        graphqlEndpoint: backend.data.resources.cfnResources.cfnGraphqlApi.attrGraphQlUrl,
+    };
+    for (const { plugin, config } of plugins)
+        plugin.wire(backend, config, context);
+    contentActionsLambda.addEnvironment(PLUGINS_ENVIRONMENT_VARIABLE, plugins.map(({ plugin }) => plugin.manifest.name).join(","));
+    backend.addOutput({
+        custom: {
+            [PLUGINS_OUTPUT_KEY]: Object.fromEntries(plugins.map(({ plugin, config }) => [plugin.manifest.name, plugin.publicSettings(config)])),
+        },
+    });
+}

package/amplify/plugins/wire.ts

@@ -0,0 +1,26 @@
+import type { Function as LambdaFunction } from "aws-cdk-lib/aws-lambda";
+import type { ResolvedPlugin } from "./registry";
+
+export const PLUGINS_ENVIRONMENT_VARIABLE = "PAPYRUS_PLUGINS";
+export const PLUGINS_OUTPUT_KEY = "papyrusPlugins";
+
+/**
+ * Deploy-time wiring for every enabled plugin. A site without plugins reaches no line of this:
+ * nothing is added to the stacks, the environment or the outputs.
+ */
+export function wirePlugins(backend: any, plugins: ResolvedPlugin[], contentActionsLambda: LambdaFunction): void {
+  if (plugins.length === 0) return;
+  const graphqlApi = backend.data.resources.graphqlApi;
+  const context = {
+    createStack: (name: string) => backend.createStack(name),
+    graphqlApiId: graphqlApi.apiId as string,
+    graphqlEndpoint: backend.data.resources.cfnResources.cfnGraphqlApi.attrGraphQlUrl as string,
+  };
+  for (const { plugin, config } of plugins) plugin.wire(backend, config, context);
+  contentActionsLambda.addEnvironment(PLUGINS_ENVIRONMENT_VARIABLE, plugins.map(({ plugin }) => plugin.manifest.name).join(","));
+  backend.addOutput({
+    custom: {
+      [PLUGINS_OUTPUT_KEY]: Object.fromEntries(plugins.map(({ plugin, config }) => [plugin.manifest.name, plugin.publicSettings(config)])),
+    },
+  });
+}

package/amplify/site-backend-config.ts

@@ -1,3 +1,5 @@
+import type { PluginRequest } from "./plugins/types";
+
 /**
  * Per-site backend configuration: the argument of `defineSiteBackend(site)`.
  * Config is passed in; the environment is only a fallback so Papyrus's own
@@ -171,6 +173,11 @@ export type PapyrusSiteBackendConfig = {
    * site out. See `resolveSitePublication`.
    */
   publication?: PapyrusPublicationConfig | false;
+  /**
+   * Deploy-time plugins (docs/plugins.md): `["signup"]`, or `[{ name: "signup", forms: ["news"] }]`.
+   * Unset: no plugin, and the synthesized backend is exactly what it was before plugins existed.
+   */
+  plugins?: PluginRequest[];
   features?: {
     consoleResponder?: boolean;
     inboundEmail?: boolean;

package/amplify/site-backend.js

@@ -18,7 +18,9 @@ import { revalidateSecretReadStatement } from "./revalidate-secret-policy.js";
 import { revalidateDistributionEnvironment, revalidateInvalidationStatement, validateRevalidateDistributionIds, } from "./revalidate-invalidation-settings.js";
 import { addInvalidationPathAlarm } from "./publication/invalidation-alarm.js";
 import { applyCognitoDomainPrefix, authConfigFromEnv, defineSiteAuth } from "./auth/resource.js";
-import { data } from "./data/resource.js";
+import { defineSiteData } from "./data/resource.js";
+import { resolvePlugins } from "./plugins/registry.js";
+import { wirePlugins } from "./plugins/wire.js";
 import { assignmentAction } from "./functions/assignment-action/resource.js";
 import { categoryAction } from "./functions/category-action/resource.js";
 import { ConsoleChatResponderStack } from "./functions/console-chat-responder/resource.js";
@@ -76,12 +78,16 @@ export function defineSiteBackend(papyrusSite) {
     const publicationPlan = planS3ProjectionBackend(publication);
     const renditionsPlan = planRenditions(publication, process.cwd());
     setSiteFilesForContentActionsBundle(publicationPlan.enabled ? publicationPlan.siteFiles : undefined);
+    const plugins = resolvePlugins(site.plugins);
+    const pluginDefinitions = Object.assign({}, ...plugins.map(({ plugin }) => plugin.schemaDefinitions()));
+    const pluginFunctions = Object.assign({}, ...plugins.map(({ plugin }) => plugin.functions()));
     const backend = defineBackend({
+        ...pluginFunctions,
         assignmentAction,
         auth: defineSiteAuth(authConfig),
         categoryAction,
         contentActions,
-        data,
+        data: defineSiteData(pluginDefinitions),
         knowledgeQuery,
         manageUserRole,
         modelAttachmentUpload,
@@ -571,5 +577,6 @@ export function defineSiteBackend(papyrusSite) {
                 : null,
         },
     });
+    wirePlugins(backend, plugins, contentActionsLambda);
     return backend;
 }

package/amplify/site-backend.ts

@@ -25,7 +25,9 @@ import {
 } from "./revalidate-invalidation-settings";
 import { addInvalidationPathAlarm } from "./publication/invalidation-alarm";
 import { applyCognitoDomainPrefix, authConfigFromEnv, defineSiteAuth } from "./auth/resource";
-import { data } from "./data/resource";
+import { defineSiteData } from "./data/resource";
+import { resolvePlugins } from "./plugins/registry";
+import { wirePlugins } from "./plugins/wire";
 import { assignmentAction } from "./functions/assignment-action/resource";
 import { categoryAction } from "./functions/category-action/resource";
 import { ConsoleChatResponderStack } from "./functions/console-chat-responder/resource";
@@ -97,12 +99,16 @@ export function defineSiteBackend(papyrusSite: PapyrusSite) {
   const publicationPlan = planS3ProjectionBackend(publication);
   const renditionsPlan = planRenditions(publication, process.cwd());
   setSiteFilesForContentActionsBundle(publicationPlan.enabled ? publicationPlan.siteFiles : undefined);
+  const plugins = resolvePlugins(site.plugins);
+  const pluginDefinitions = Object.assign({}, ...plugins.map(({ plugin }) => plugin.schemaDefinitions()));
+  const pluginFunctions: Record<never, never> = Object.assign({}, ...plugins.map(({ plugin }) => plugin.functions()));
   const backend = defineBackend({
+    ...pluginFunctions,
     assignmentAction,
     auth: defineSiteAuth(authConfig),
     categoryAction,
     contentActions,
-    data,
+    data: defineSiteData(pluginDefinitions),
     knowledgeQuery,
     manageUserRole,
     modelAttachmentUpload,
@@ -707,5 +713,7 @@ export function defineSiteBackend(papyrusSite: PapyrusSite) {
         : null,
     },
   });
+  wirePlugins(backend, plugins, contentActionsLambda);
+
   return backend;
 }

package/components/signup-entries-panel.tsx

@@ -0,0 +1,94 @@
+"use client";
+
+import { generateClient } from "aws-amplify/data";
+import amplifyOutputs from "papyrus-amplify-outputs";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { signupForms, type PluginOutputs } from "../lib/plugin-settings";
+import { signupEntriesToCsv, type SignupEntryRecord } from "../lib/signup-csv";
+
+const LIST_QUERY = `query ListSignupEntries($form: String!, $nextToken: String) {
+  listSignupEntriesByFormAndSubmittedAt(form: $form, sortDirection: DESC, limit: 200, nextToken: $nextToken) {
+    items { id form value submittedAt }
+    nextToken
+  }
+}`;
+
+type ListResult = { data?: { listSignupEntriesByFormAndSubmittedAt?: { items: SignupEntryRecord[]; nextToken?: string | null } }; errors?: { message?: string }[] };
+
+async function loadAllEntries(form: string): Promise<SignupEntryRecord[]> {
+  const client = generateClient({ authMode: "userPool" });
+  const entries: SignupEntryRecord[] = [];
+  let nextToken: string | null | undefined;
+  do {
+    const result = (await client.graphql({ query: LIST_QUERY, variables: { form, nextToken } })) as ListResult;
+    if (result.errors?.length) throw new Error(result.errors[0]?.message ?? "Could not load signups.");
+    const page = result.data?.listSignupEntriesByFormAndSubmittedAt;
+    entries.push(...(page?.items ?? []));
+    nextToken = page?.nextToken;
+  } while (nextToken);
+  return entries;
+}
+
+export function SignupEntriesPanel() {
+  const forms = useMemo(() => signupForms(amplifyOutputs as PluginOutputs), []);
+  const [form, setForm] = useState(forms[0] ?? "");
+  const [entries, setEntries] = useState<SignupEntryRecord[] | null>(null);
+  const [problem, setProblem] = useState<string | null>(null);
+
+  const refresh = useCallback(async () => {
+    if (!form) return;
+    setEntries(null);
+    setProblem(null);
+    try {
+      setEntries(await loadAllEntries(form));
+    } catch (error) {
+      setProblem(error instanceof Error ? error.message : "Could not load signups.");
+    }
+  }, [form]);
+
+  useEffect(() => {
+    void refresh();
+  }, [refresh]);
+
+  const exportCsv = () => {
+    if (!entries) return;
+    const url = URL.createObjectURL(new Blob([signupEntriesToCsv(entries)], { type: "text/csv;charset=utf-8" }));
+    const link = document.createElement("a");
+    link.href = url;
+    link.download = `signups-${form}.csv`;
+    link.click();
+    URL.revokeObjectURL(url);
+  };
+
+  return (
+    <section aria-labelledby="newsroom-signups-title" data-news-desk-admin-panel="signups">
+      <h3 id="newsroom-signups-title">Signups</h3>
+      <p>Addresses people entered in the site&apos;s signup forms. Only editors and admins can see them.</p>
+      <label>
+        Form{" "}
+        <select value={form} onChange={(event) => setForm(event.target.value)} disabled={forms.length < 2}>
+          {forms.map((name) => (
+            <option key={name} value={name}>{name}</option>
+          ))}
+        </select>
+      </label>{" "}
+      <button type="button" onClick={() => void refresh()}>Refresh</button>{" "}
+      <button type="button" onClick={exportCsv} disabled={!entries || entries.length === 0}>Export CSV</button>
+      <p role="status" aria-live="polite">
+        {problem ? `Error: ${problem}` : entries === null ? "Loading..." : `${entries.length} ${entries.length === 1 ? "entry" : "entries"}`}
+      </p>
+      {entries && entries.length > 0 ? (
+        <table>
+          <thead>
+            <tr><th scope="col">Submitted</th><th scope="col">Address</th></tr>
+          </thead>
+          <tbody>
+            {entries.map((entry) => (
+              <tr key={entry.id}><td>{entry.submittedAt}</td><td>{entry.value}</td></tr>
+            ))}
+          </tbody>
+        </table>
+      ) : null}
+    </section>
+  );
+}

package/components/topic-steering-workspace.tsx

@@ -10,6 +10,9 @@ import Link from "next/link";
 import { usePathname, useRouter } from "next/navigation";
 import type { ReactNode, RefObject } from "react";
 import { useCallback, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, useTransition } from "react";
+import amplifyOutputs from "papyrus-amplify-outputs";
+import { SignupEntriesPanel } from "./signup-entries-panel";
+import { pluginSettings, type PluginOutputs } from "../lib/plugin-settings";
 import { generateClient } from "aws-amplify/data";
 import type { Schema } from "../amplify/data/resource";
 import {
@@ -235,7 +238,7 @@ type AssignmentAction = "claim" | "release" | "complete" | "cancel" | "reopen" |
 type ReportingPacketReviewDecision = "select" | "merge" | "brief" | "hold" | "kill";
 type AssignmentDeskViewMode = "queue" | "budget";
 type UserRoleAction = "grant" | "revoke";
-type AdministrationPanel = "users" | "policies" | "sections" | "procedures";
+type AdministrationPanel = "users" | "policies" | "sections" | "procedures" | "signups";
 export type NewsDeskTab = "overview" | "desks" | "topics" | "concepts" | "references" | "insights" | "messages" | "assignments" | "administration" | "search";
 type LexicalRuleScope = "publication" | "corpus" | "classifier" | "category";
 type AnalysisReindexMode = "online-update" | "classifier-retrain" | "scoped-topic-rebuild" | "entity-graph-rebuild" | "generated-analysis-rebuild";
@@ -4452,8 +4455,20 @@ function AdministrationDeskView({
                 <strong>Procedures</strong>
                 <span>Procedure registry and versioned Tactus code</span>
               </Link>
+              {signupPluginEnabled() ? (
+                <Link
+                  href={administrationPanelHref("signups", isDemo)}
+                  data-news-desk-admin-nav="signups"
+                  data-active={administrationPanel === "signups" || undefined}
+                  onClick={() => onPanelChange("signups")}
+                >
+                  <strong>Signups</strong>
+                  <span>Addresses from the site&apos;s signup forms</span>
+                </Link>
+              ) : null}
             </nav>
             <div className="news-desk-settings-panel">
+              {administrationPanel === "signups" ? <SignupEntriesPanel /> : null}
               {administrationPanel === "users" ? (
                 <AdministrationUsersPanel
                   canManageUsers={canManageUsers}
@@ -13646,8 +13661,13 @@ function semanticVersionKey(kind: string, id: string): string {
   return `${kind}#${id}`;
 }
 
+function signupPluginEnabled(): boolean {
+  return pluginSettings(amplifyOutputs as PluginOutputs, "signup") !== null;
+}
+
 function normalizeAdministrationPanel(value: string | null | undefined): AdministrationPanel {
   if (value === "policies" || value === "sections" || value === "procedures") return value;
+  if (value === "signups" && signupPluginEnabled()) return value;
   return "users";
 }
 

package/lib/plugin-settings.ts

@@ -0,0 +1,11 @@
+export type PluginOutputs = { custom?: { papyrusPlugins?: Record<string, Record<string, unknown>> } };
+
+/** The settings a deployed plugin published in `amplify_outputs.json`, or null when the site did not enable it. */
+export function pluginSettings(outputs: PluginOutputs | null | undefined, name: string): Record<string, unknown> | null {
+  return outputs?.custom?.papyrusPlugins?.[name] ?? null;
+}
+
+export function signupForms(outputs: PluginOutputs | null | undefined): string[] {
+  const forms = pluginSettings(outputs, "signup")?.forms;
+  return Array.isArray(forms) ? forms.filter((form): form is string => typeof form === "string") : [];
+}

package/lib/signup-csv.ts

@@ -0,0 +1,24 @@
+export type SignupEntryRecord = {
+  id: string;
+  form: string;
+  value: string;
+  submittedAt: string;
+};
+
+export const SIGNUP_CSV_HEADER = ["form", "value", "submittedAt"] as const;
+const FORMULA_STARTS = new Set(["=", "+", "-", "@", "\t", "\r"]);
+
+/** A spreadsheet runs a cell that starts with one of these as a formula; a leading quote makes it text. */
+export function neutralizeFormula(cell: string): string {
+  return cell !== "" && FORMULA_STARTS.has(cell[0]) ? `'${cell}` : cell;
+}
+
+export function csvCell(cell: string): string {
+  const safe = neutralizeFormula(cell);
+  return /[",\r\n]/.test(safe) ? `"${safe.replace(/"/g, '""')}"` : safe;
+}
+
+export function signupEntriesToCsv(entries: SignupEntryRecord[]): string {
+  const rows = entries.map((entry) => SIGNUP_CSV_HEADER.map((column) => csvCell(String(entry[column] ?? ""))).join(","));
+  return `${[SIGNUP_CSV_HEADER.join(","), ...rows].join("\r\n")}\r\n`;
+}

package/package.json

@@ -104,6 +104,7 @@
     "./components/reference-relevance-review": "./components/reference-relevance-review.tsx",
     "./components/reference-source-preview": "./components/reference-source-preview.tsx",
     "./components/settings-page": "./components/settings-page.tsx",
+    "./components/signup-entries-panel": "./components/signup-entries-panel.tsx",
     "./components/staging-banner": "./components/staging-banner.tsx",
     "./components/topic-steering-workspace": "./components/topic-steering-workspace.tsx",
     "./components/ui/badge": "./components/ui/badge.tsx",
@@ -190,6 +191,7 @@
     "./lib/papyrus-object-kinds": "./lib/papyrus-object-kinds.ts",
     "./lib/papyrus-web-locations": "./lib/papyrus-web-locations.ts",
     "./lib/pilobol-sample": "./lib/pilobol-sample.ts",
+    "./lib/plugin-settings": "./lib/plugin-settings.ts",
     "./lib/presentation-footer": "./lib/presentation-footer.ts",
     "./lib/pretext-layout": "./lib/pretext-layout.ts",
     "./lib/public-placeholder-config": "./lib/public-placeholder-config.ts",
@@ -211,6 +213,7 @@
     "./lib/robots-policy": "./lib/robots-policy.ts",
     "./lib/root-route-redirect": "./lib/root-route-redirect.ts",
     "./lib/semantic-graph": "./lib/semantic-graph.ts",
+    "./lib/signup-csv": "./lib/signup-csv.ts",
     "./lib/site-brand-tenant": "./lib/site-brand-tenant.ts",
     "./lib/site-brand": "./lib/site-brand.ts",
     "./lib/site-env": "./lib/site-env.ts",
@@ -303,7 +306,7 @@
       "optional": true
     }
   },
-  "version": "1.0.0-next.50",
+  "version": "1.0.0-next.51",
   "dependencies": {
     "@aws-amplify/adapter-nextjs": "^1.7.3",
     "@aws-sdk/client-cognito-identity-provider": "3.1045.0",

package/routes.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.0-next.50",
+  "version": "1.0.0-next.51",
   "routes": [
     {
       "file": "app/%5F_preview/[[...path]]/route.ts",