@anthusai/papyrus 1.0.0-next.9 → 1.0.0

package/amplify/inbound-email/ses-intake.js

@@ -0,0 +1,86 @@
+import { Duration } from "aws-cdk-lib";
+import * as route53 from "aws-cdk-lib/aws-route53";
+import * as ses from "aws-cdk-lib/aws-ses";
+import * as sesActions from "aws-cdk-lib/aws-ses-actions";
+import { AwsCustomResource, AwsCustomResourcePolicy, PhysicalResourceId } from "aws-cdk-lib/custom-resources";
+/**
+ * Adds the SES receipt resources directly to `scope` (no wrapper construct) so
+ * the logical ids of the live p.apyr.us stack stay unchanged.
+ */
+export function addInboundEmailSesIntake(scope, props) {
+    if (props.domainIdentity) {
+        const { domain, hostedZoneId, hostedZoneName, recordName } = props.domainIdentity;
+        const zone = route53.HostedZone.fromHostedZoneAttributes(scope, "PapyrusInboundDnsZone", {
+            hostedZoneId,
+            zoneName: hostedZoneName,
+        });
+        const verifyDomain = new AwsCustomResource(scope, "VerifyInboundEmailDomain", {
+            onCreate: {
+                service: "SES",
+                action: "verifyDomainIdentity",
+                parameters: { Domain: domain },
+                physicalResourceId: PhysicalResourceId.of(`ses-domain-verify-${domain}`),
+            },
+            onUpdate: {
+                service: "SES",
+                action: "verifyDomainIdentity",
+                parameters: { Domain: domain },
+                physicalResourceId: PhysicalResourceId.of(`ses-domain-verify-${domain}`),
+            },
+            policy: AwsCustomResourcePolicy.fromSdkCalls({
+                resources: AwsCustomResourcePolicy.ANY_RESOURCE,
+            }),
+            timeout: Duration.minutes(2),
+        });
+        new route53.TxtRecord(scope, "PapyrusInboundEmailDomainVerification", {
+            zone,
+            recordName: `_amazonses.${recordName}`,
+            ttl: Duration.minutes(5),
+            values: [verifyDomain.getResponseField("VerificationToken")],
+        });
+    }
+    const ruleSet = props.existingRuleSetName
+        ? ses.ReceiptRuleSet.fromReceiptRuleSetName(scope, "PapyrusInboundEmailRuleSet", props.existingRuleSetName)
+        : new ses.ReceiptRuleSet(scope, "PapyrusInboundEmailRuleSet", {
+            receiptRuleSetName: props.ruleSetName,
+        });
+    ruleSet.addRule("PapyrusInboundSubmissions", {
+        receiptRuleName: props.ruleName,
+        recipients: props.recipients,
+        enabled: true,
+        scanEnabled: true,
+        tlsPolicy: ses.TlsPolicy.REQUIRE,
+        actions: [
+            new sesActions.S3({
+                bucket: props.storageBucket,
+                objectKeyPrefix: "inbound-email/",
+            }),
+        ],
+    });
+    if (props.activateRuleSet && !props.existingRuleSetName) {
+        new AwsCustomResource(scope, "ActivateInboundEmailRuleSet", {
+            onCreate: {
+                service: "SES",
+                action: "setActiveReceiptRuleSet",
+                parameters: { RuleSetName: ruleSet.receiptRuleSetName },
+                physicalResourceId: PhysicalResourceId.of(`activate-${ruleSet.receiptRuleSetName}`),
+            },
+            onUpdate: {
+                service: "SES",
+                action: "setActiveReceiptRuleSet",
+                parameters: { RuleSetName: ruleSet.receiptRuleSetName },
+                physicalResourceId: PhysicalResourceId.of(`activate-${ruleSet.receiptRuleSetName}`),
+            },
+            onDelete: {
+                service: "SES",
+                action: "setActiveReceiptRuleSet",
+                parameters: { RuleSetName: null },
+            },
+            policy: AwsCustomResourcePolicy.fromSdkCalls({
+                resources: AwsCustomResourcePolicy.ANY_RESOURCE,
+            }),
+            timeout: Duration.minutes(2),
+        });
+    }
+    return { ruleSet };
+}

package/amplify/inbound-email/ses-intake.ts

@@ -0,0 +1,110 @@
+import { Duration } from "aws-cdk-lib";
+import * as route53 from "aws-cdk-lib/aws-route53";
+import * as ses from "aws-cdk-lib/aws-ses";
+import * as sesActions from "aws-cdk-lib/aws-ses-actions";
+import type * as s3 from "aws-cdk-lib/aws-s3";
+import { AwsCustomResource, AwsCustomResourcePolicy, PhysicalResourceId } from "aws-cdk-lib/custom-resources";
+import type { Construct } from "constructs";
+
+export type InboundEmailSesIntakeProps = {
+  storageBucket: s3.IBucket;
+  recipients: string[];
+  ruleSetName: string;
+  /** Adds the rule to a rule set another stack owns instead of creating one. */
+  existingRuleSetName?: string;
+  /** `undefined` lets CloudFormation generate the name (the live p.apyr.us rule). */
+  ruleName?: string;
+  /** Only the legacy p.apyr.us pipeline sets this; a new site never activates a rule set. */
+  activateRuleSet: boolean;
+  domainIdentity?: {
+    domain: string;
+    hostedZoneId: string;
+    hostedZoneName: string;
+    recordName: string;
+  };
+};
+
+/**
+ * Adds the SES receipt resources directly to `scope` (no wrapper construct) so
+ * the logical ids of the live p.apyr.us stack stay unchanged.
+ */
+export function addInboundEmailSesIntake(scope: Construct, props: InboundEmailSesIntakeProps) {
+  if (props.domainIdentity) {
+    const { domain, hostedZoneId, hostedZoneName, recordName } = props.domainIdentity;
+    const zone = route53.HostedZone.fromHostedZoneAttributes(scope, "PapyrusInboundDnsZone", {
+      hostedZoneId,
+      zoneName: hostedZoneName,
+    });
+    const verifyDomain = new AwsCustomResource(scope, "VerifyInboundEmailDomain", {
+      onCreate: {
+        service: "SES",
+        action: "verifyDomainIdentity",
+        parameters: { Domain: domain },
+        physicalResourceId: PhysicalResourceId.of(`ses-domain-verify-${domain}`),
+      },
+      onUpdate: {
+        service: "SES",
+        action: "verifyDomainIdentity",
+        parameters: { Domain: domain },
+        physicalResourceId: PhysicalResourceId.of(`ses-domain-verify-${domain}`),
+      },
+      policy: AwsCustomResourcePolicy.fromSdkCalls({
+        resources: AwsCustomResourcePolicy.ANY_RESOURCE,
+      }),
+      timeout: Duration.minutes(2),
+    });
+    new route53.TxtRecord(scope, "PapyrusInboundEmailDomainVerification", {
+      zone,
+      recordName: `_amazonses.${recordName}`,
+      ttl: Duration.minutes(5),
+      values: [verifyDomain.getResponseField("VerificationToken")],
+    });
+  }
+
+  const ruleSet = props.existingRuleSetName
+    ? ses.ReceiptRuleSet.fromReceiptRuleSetName(scope, "PapyrusInboundEmailRuleSet", props.existingRuleSetName)
+    : new ses.ReceiptRuleSet(scope, "PapyrusInboundEmailRuleSet", {
+        receiptRuleSetName: props.ruleSetName,
+      });
+  ruleSet.addRule("PapyrusInboundSubmissions", {
+    receiptRuleName: props.ruleName,
+    recipients: props.recipients,
+    enabled: true,
+    scanEnabled: true,
+    tlsPolicy: ses.TlsPolicy.REQUIRE,
+    actions: [
+      new sesActions.S3({
+        bucket: props.storageBucket,
+        objectKeyPrefix: "inbound-email/",
+      }),
+    ],
+  });
+
+  if (props.activateRuleSet && !props.existingRuleSetName) {
+    new AwsCustomResource(scope, "ActivateInboundEmailRuleSet", {
+      onCreate: {
+        service: "SES",
+        action: "setActiveReceiptRuleSet",
+        parameters: { RuleSetName: ruleSet.receiptRuleSetName },
+        physicalResourceId: PhysicalResourceId.of(`activate-${ruleSet.receiptRuleSetName}`),
+      },
+      onUpdate: {
+        service: "SES",
+        action: "setActiveReceiptRuleSet",
+        parameters: { RuleSetName: ruleSet.receiptRuleSetName },
+        physicalResourceId: PhysicalResourceId.of(`activate-${ruleSet.receiptRuleSetName}`),
+      },
+      onDelete: {
+        service: "SES",
+        action: "setActiveReceiptRuleSet",
+        parameters: { RuleSetName: null },
+      },
+      policy: AwsCustomResourcePolicy.fromSdkCalls({
+        resources: AwsCustomResourcePolicy.ANY_RESOURCE,
+      }),
+      timeout: Duration.minutes(2),
+    });
+  }
+
+  return { ruleSet };
+}

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