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

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)),
+    };
+}