@extantape/payload-plugin-signup 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EXTANT APE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,121 @@
-# Temporary Holding Version
+# payload-plugin-signup
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Sign-up for Payload: open, approval, invite-only or closed, switched in the admin. Requests are verified by email and wait as disabled accounts for an approve or decline, with no account enumeration.
+
+**Status:** 0.1.0 is on npm. 0.1.1 (the confirm page's details, checks again at confirm, the request itself handed to checks, and cookies from checks) is on main, not released yet. 55 tests pass against a real MongoDB (in memory, single-node replica set) on Payload 3.92: every mode, confirming, approving and declining, that nobody can set up an account under someone else's address, the same answer for every address, refusals that fail closed (at asking and at confirming), rate limits (including through the real endpoints), what staff and members can and can't see or change, rollback, and retention. An independent security read found two problems before release, both fixed and tested (see [docs/decisions.md](docs/decisions.md)). Nothing has run on a real site yet, and no real email has been sent: the tests capture email. Integration into the Captive Origins platform is next.
+
+## What it does
+
+- **Four modes**, chosen in **Sign-up settings** in the admin and in force at once, with no deploy:
+  - **Open:** anyone who confirms their email gets an account.
+  - **Approval:** a confirmed request waits as a disabled account until staff approve or decline it.
+  - **Invite only:** the form refuses, with your message. Accounts come from your own invitations.
+  - **Closed:** the form refuses, with your message.
+  `SIGNUP_MODE` (or the `forceMode` option) locks the mode from configuration. Anything unreadable or unknown counts as closed.
+- **A request** has an email and your own fields (plain Payload fields, so Payload validates them and the admin shows them). No account and no password yet. Sign-up emails a link. Opening it shows a short form: the person chooses their password and presses "Confirm my email". Opening the link alone changes nothing, because mail scanners open links. Only then is the account made, so only the person with the inbox can set one up under that address. In approval mode it can't sign in until it's approved.
+- **The same answer every time:** "Thanks. Check your email to continue." That goes for a new address, one that already has an account (its owner gets an email saying so), and one that's already waiting. The form never tells anyone whether an address has an account, and each case does the same lookups, so the timing gives little away (not measured, so not promised). "Waiting for approval" is only shown at sign-in, after the password matched.
+- **Staff decide in the admin.** Open a request and set Status to Approved or Declined, or select several and use Edit. A waiting request can only be approved or declined; nothing else on it can be changed. Approving activates the account, runs your `onApprove` (roles, memberships), and emails "You're in". Declining deletes the account, which never signed in, and sends a polite email with your optional note. If `onApprove` fails, nothing changes and no email goes out.
+- **Your checks** run before anything is stored, for example an age gate. A check can refuse with a message, flag the request for staff ("minor"), or add values to the new account. Answers meant only for checks (`answers`, such as a birth month and year) are never stored. A check that breaks refuses the request. See [Checks](#checks).
+- **Checks again at confirm** (`confirmChecks`, optional): run when the person confirms, before the account is made, with the stored details and flag but never the check-only answers. A refusal declines the request; a check that breaks refuses for now and the link still works later.
+- **Rate limits** per network address, per email and site-wide. Past the email limit, nothing happens, with the same answer. Use your own limiter, or the built-in one, which stores only hashed keys. A limiter that breaks refuses.
+  - Which address counts: by default, `x-real-ip` when the request has it (Vercel sets it), otherwise the last `x-forwarded-for` entry, the one added by the proxy in front of the site. That's only right behind one trusted proxy that sets one of these. Behind several proxies, a CDN with its own header, or no proxy at all (where a visitor can send any of these headers), pass `clientAddress` with the header your host vouches for. Requests with no address share one "unknown" count.
+  - The site-wide limit (200 an hour) is a cheap way for anyone to block sign-up for an hour. On a public site, use `verifyHuman` (Turnstile or similar) as well.
+- **No back door:** once a site has users, an account can't be created by a signed-out API call. Accounts come through sign-up, from staff, or from your own code.
+- **Retention:** requests decided, abandoned or never confirmed are deleted after 90 days (`retentionDays`), with any account that was never confirmed. Waiting requests stay until someone decides them. Run `pruneSignupRequests(payload)` daily.
+- **A human check** (Turnstile or similar) through `verifyHuman`. Nothing is wired by default; on a public site, wire one.
+- **Who manages it is yours to say, and required.** `access.manage` decides who sees and decides requests and changes the mode, and only an exact `true` counts: see [Access](#access). The plugin won't start without it, so a site can't leave the queue open to every signed-in member. `signupStatus` is shown only to the account itself and to managers. What checks set for the account (a minor flag, say) is kept out of the queue's view.
+
+## On its own, and with others
+
+**On its own:** it needs a users auth collection, Payload's email, and your `access.manage`. Checks, roles on approval and a human check are functions you pass in. It imports no other Captive Origins plugin.
+
+**Works with:**
+- **Age Gate:** its `ageGateCheck` goes in `checks`. A too-young person is refused, a minor is flagged in the queue, and `minorUntil` is written to the new account. The birth month and year stay in `answers` and are never stored. Its "stay blocked" cookie comes back through `setCookies`, from Age Gate's next release. Age Gate 0.1.x set it on `req.responseHeaders`, which Sign-up doesn't pass on (see [Checks](#checks)), so with 0.1.x the cookie is not set.
+- **A tenant plugin** (such as Payload's multi-tenant plugin): pass `scopeField` and `scopeFor`, and add `signup-requests` to its collections, so each site sees its own queue.
+
+**Family:** It's part of the **Identity** family (a working draft): plugins designed to sit together for accounts and access. Age Gate is the member it's wired to today.
+
+## Install
+
+```sh
+npm install @extantape/payload-plugin-signup
+```
+
+```ts
+import { signupPlugin } from '@extantape/payload-plugin-signup'
+
+export default buildConfig({
+  plugins: [
+    signupPlugin({
+      fields: [
+        { name: 'firstName', type: 'text', required: true },
+        { name: 'lastName', type: 'text', required: true },
+      ],
+      toUser: (d) => ({ name: `${d.firstName} ${d.lastName}` }),
+      checks: [myAgeGate], // ({ data, answers, email, req, payload }) => { refuse?, flag?, userData?, setCookies? }
+      onApprove: async ({ user, req, payload }) => {
+        /* give roles */
+      },
+      access: { manage: ({ req }) => req.user?.role === 'admin' }, // required
+      emails: { verify: myBrandedVerifyEmail }, // any of verify, pending, approved, declined, alreadyHasAccount
+      urls: { signIn: 'https://example.com/login', resetPassword: 'https://example.com/forgot-password' },
+    }),
+  ],
+})
+```
+
+Build the collections' indexes before first use (`signup-requests`, `signup-attempts`, and the new `signupStatus` on your users). If you build your own confirm page, show what was asked for with `readSignupRequest`, ask for the password there and post `{ token, password }`; never confirm when the page loads. With a tenant plugin, pass `scopeField` and `scopeFor`, and add `signup-requests` to your tenant plugin's collections, so each site sees its own queue. The mode setting is one for the whole install.
+
+## Checks
+
+A check is a function in `checks`, run in order when a request comes in:
+
+```ts
+type Check = (args: { data; answers; email; req: PayloadRequest; payload }) =>
+  { refuse?: string; flag?: string; userData?: Record<string, unknown>; setCookies?: string[] } | void
+```
+
+- `req` is the request itself, headers and cookies included. A check written to take less (`Partial<PayloadRequest>`) still fits. Calling `submitSignup` from your own code with a partial request, or none, is fine: Payload's `createLocalReq` completes it, with empty headers.
+- `setCookies` are whole `Set-Cookie` values. `POST /api/signup/request` sets them on its response, whether the request is taken or refused. `submitSignup` hands them back as `setCookies` on its result, or on the `SignupError` it throws, so your own form can set them. Each must be printable ASCII (space to `~`), as cookie syntax allows; anything else counts as a broken check and refuses (503 `checkFailed`) before anything is stored or emailed.
+- Confirm checks (`confirmChecks`) work the same way: they get the request itself, and their `setCookies` go on the `POST /api/signup/verify` response, as JSON or the page, confirmed or refused. `verifySignup` hands them back on its result or its `SignupError`.
+- Nothing else about the response is a check's to change. Each check runs with an empty `req.responseHeaders` of its own, and Sign-up throws that list away afterwards, so headers a check adds there never reach the response. The request's own list (an auth strategy's, say) is put back untouched. Sign-up and its checks don't import each other: the check returns plain values.
+
+## Endpoints
+
+| Method and path | Body | Answer |
+| --- | --- | --- |
+| `GET /api/signup/mode` | | `{ mode, accepting, message }` |
+| `POST /api/signup/request` | `{ email, details, answers?, humanToken? }` | 202 `{ ok, message }`, or an error `{ error: { code, message } }`, either with any cookies the checks set |
+| `GET /api/signup/verify?token=` | | A small page: what was asked for (email and details), then choose a password and confirm |
+| `POST /api/signup/verify` | `{ token, password }` as JSON, or the page's form (`token`, `password`, `confirm`) | JSON `{ status: 'pending' or 'active' }`, or a page |
+
+Error codes: `closed`, `inviteOnly`, `email`, `password`, `passwordMismatch` (the page only), `refused`, `checkFailed`, `human`, `busy`, `badLink`, `hasAccount` (an account was made for the address since they asked). The same functions are exported for your own pages: `submitSignup`, `verifySignup`, `currentMode`, and `readSignupRequest` to show what was asked for on your confirm page (it only reads; the link still works). The confirm page shows only the email and the fields you list in `confirmShows` (default none), because a mistyped address sends the link to a stranger. Hidden fields and fields with their own read access never show.
+
+## Access
+
+`access.manage` decides who manages sign-up, and only an answer of exactly `true`, for a signed-in
+user, counts. Anything else is a no: `false`, `1`, `'yes'`, an object, a query (`Where`), or an error
+thrown or rejected. An error doesn't escape as a 500: REST answers 403, as for anyone else who isn't a
+manager. It's typed as Payload's `Access` so existing rules fit, but what it returns is never passed to
+Payload, so an object that looks like a query can't widen the queue to every request.
+
+| Where | A manager | Anyone else, or signed out |
+|---|---|---|
+| Sign-up requests (applicants' emails and details) | Reads, decides, deletes | Nothing |
+| Sign-up settings (the mode and messages) | Reads and changes | Nothing |
+| An account's `signupStatus` | Reads | Only the account itself reads its own |
+
+Nobody creates requests or changes `signupStatus` directly: the plugin does. Each site seeing only its
+own queue comes from a tenant plugin with `scopeField` (above), not from a query in `access.manage`.
+
+## Commands
+
+```sh
+npm test          # integration tests, in-memory MongoDB
+npm run typecheck
+npm run build
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/access.d.ts

@@ -0,0 +1,11 @@
+import type { PayloadRequest } from 'payload';
+import type { ResolvedSignup } from './types.js';
+/** Only an answer of exactly `true` passes; anything else, a thrown error included, is no. */
+export declare function exactlyTrue(check: () => unknown): Promise<boolean>;
+/**
+ * A signed-in manager: `access.manage` answered exactly `true`. A truthy value, a query (`Where`) or an error is a no,
+ * and the site's answer is never handed to Payload, so an object can't widen access to every request.
+ */
+export declare const isManager: (o: Pick<ResolvedSignup, "manage">, args: {
+    req: PayloadRequest;
+}) => Promise<boolean>;

package/dist/access.js

@@ -0,0 +1,14 @@
+/** Only an answer of exactly `true` passes; anything else, a thrown error included, is no. */
+export async function exactlyTrue(check) {
+    try {
+        return (await check()) === true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * A signed-in manager: `access.manage` answered exactly `true`. A truthy value, a query (`Where`) or an error is a no,
+ * and the site's answer is never handed to Payload, so an object can't widen access to every request.
+ */
+export const isManager = (o, args) => args.req.user ? exactlyTrue(() => o.manage(args)) : Promise.resolve(false);

package/dist/collections.d.ts

@@ -0,0 +1,10 @@
+import type { CollectionConfig, Field, GlobalConfig } from 'payload';
+import { type ResolvedSignup } from './types.js';
+/** Sign-up requests: the queue staff work through. Made only by the plugin; staff change only the decision. */
+export declare function requestsCollection(o: ResolvedSignup): CollectionConfig;
+/** The mode, and what the form says while sign-up is shut. */
+export declare function settingsGlobal(o: ResolvedSignup): GlobalConfig;
+/** Rate-limit counts for the built-in limiter: hashed keys and times, nothing else. */
+export declare function attemptsCollection(o: ResolvedSignup): CollectionConfig;
+/** Added to the auth collection: where an account is in sign-up. Accounts made any other way are active. */
+export declare function signupStatusField(o: ResolvedSignup): Field;

package/dist/collections.js

@@ -0,0 +1,147 @@
+import { isManager } from './access.js';
+import { decide } from './flow.js';
+import { MODES } from './types.js';
+import { SignupError } from './util.js';
+const nobody = () => false;
+/** Sign-up requests: the queue staff work through. Made only by the plugin; staff change only the decision. */
+export function requestsCollection(o) {
+    // Only an exact `true` from `access.manage` makes a manager; a truthy value, a query or a thrown error is a no.
+    const manager = (args) => isManager(o, args);
+    const internal = { hidden: true };
+    return {
+        slug: o.requests,
+        labels: { singular: 'Sign-up request', plural: 'Sign-up requests' },
+        admin: {
+            group: o.adminGroup,
+            useAsTitle: 'email',
+            defaultColumns: ['email', 'status', 'flag', 'createdAt'],
+            description: 'People asking for an account. Open one and set Status to Approved or Declined, or select several and use Edit. Unverified ones haven\'t confirmed their email yet, and have no account. Decided, abandoned and unverified requests are deleted after ' +
+                `${o.retentionDays} days.`,
+            listSearchableFields: ['email'],
+        },
+        access: { read: manager, update: manager, create: nobody, delete: manager },
+        fields: [
+            { name: 'email', type: 'email', required: true, index: true, admin: { readOnly: true } },
+            {
+                name: 'status',
+                type: 'select',
+                required: true,
+                defaultValue: 'unverified',
+                index: true,
+                options: [
+                    { label: 'Unverified', value: 'unverified' },
+                    { label: 'Waiting for a decision', value: 'pending' },
+                    { label: 'Approved', value: 'approved' },
+                    { label: 'Declined', value: 'declined' },
+                ],
+                admin: { position: 'sidebar', description: 'Change a waiting request to Approved or Declined. Nothing else can be changed here.' },
+            },
+            { name: 'flag', type: 'text', admin: { readOnly: true, position: 'sidebar', description: 'Something the site\'s checks want you to see, for example that the person is a minor.' } },
+            {
+                name: 'note',
+                type: 'textarea',
+                maxLength: 500,
+                admin: { description: 'Optional. Sent to them with a decline, word for word. Leave it empty for the standard polite email.' },
+            },
+            { name: 'details', type: 'group', fields: o.fields.length ? o.fields : [{ name: 'none', type: 'text', admin: { hidden: true } }], admin: { readOnly: true } },
+            { name: 'user', type: 'relationship', relationTo: o.users, admin: { readOnly: true, position: 'sidebar' } },
+            { name: 'verifiedAt', type: 'date', admin: { readOnly: true, position: 'sidebar', date: { pickerAppearance: 'dayAndTime' } } },
+            { name: 'decidedAt', type: 'date', index: true, admin: { readOnly: true, position: 'sidebar', date: { pickerAppearance: 'dayAndTime' } } },
+            { name: 'decidedBy', type: 'relationship', relationTo: o.users, admin: { readOnly: true, position: 'sidebar', description: 'Empty when it was approved automatically (open sign-up).' } },
+            // What the site's checks set for the account (a minor flag, say): applied on confirming, read by nobody.
+            { name: 'userData', type: 'json', admin: internal, access: { read: nobody } },
+            { name: 'tokenHash', type: 'text', index: true, admin: internal, access: { read: nobody } },
+            { name: 'tokenExpires', type: 'date', admin: internal },
+        ],
+        hooks: {
+            beforeChange: [
+                async ({ data, originalDoc, operation, req, context }) => {
+                    if (operation !== 'update' || context?.signupInternal)
+                        return data;
+                    // Staff change only the decision, and only on a waiting request. Everything else stays as the plugin wrote it.
+                    const from = originalDoc?.status;
+                    const to = data.status ?? from;
+                    for (const key of ['email', 'details', 'user', 'flag', 'verifiedAt', 'decidedAt', 'decidedBy', 'userData', 'tokenHash', 'tokenExpires'])
+                        data[key] = originalDoc?.[key];
+                    if (to === from)
+                        return data;
+                    if (from !== 'pending')
+                        throw new SignupError('notWaiting', from === 'unverified' ? 'This request isn\'t verified yet, so it can\'t be decided.' : 'This request has already been decided.');
+                    if (to !== 'approved' && to !== 'declined')
+                        throw new SignupError('badDecision', 'A waiting request can only be approved or declined.');
+                    return decide(req.payload, { ...originalDoc, ...data }, to, req);
+                },
+            ],
+        },
+        timestamps: true,
+    };
+}
+/** The mode, and what the form says while sign-up is shut. */
+export function settingsGlobal(o) {
+    const manager = (args) => isManager(o, args);
+    return {
+        slug: o.settings,
+        label: 'Sign-up settings',
+        admin: { group: o.adminGroup },
+        access: { read: manager, update: manager },
+        fields: [
+            {
+                name: 'mode',
+                type: 'select',
+                required: true,
+                defaultValue: 'closed',
+                options: [
+                    { label: 'Open: anyone who confirms their email gets an account', value: MODES[0] },
+                    { label: 'Approval: requests wait for a person to approve them', value: MODES[1] },
+                    { label: 'Invite only: the form is shut; accounts come from invitations', value: MODES[2] },
+                    { label: 'Closed: nobody can ask', value: MODES[3] },
+                ],
+                admin: {
+                    description: o.forceMode ? `Locked to "${o.forceMode}" by the site's configuration; this setting is ignored until that's removed.` : 'Takes effect at once, with no deploy.',
+                },
+            },
+            { name: 'inviteOnlyMessage', type: 'textarea', maxLength: 500, admin: { description: 'Shown on the form in invite-only mode. Empty: "Sign-up is by invitation for now."' } },
+            { name: 'closedMessage', type: 'textarea', maxLength: 500, admin: { description: 'Shown on the form when closed. Empty: "Sign-up is closed for now."' } },
+        ],
+    };
+}
+/** Rate-limit counts for the built-in limiter: hashed keys and times, nothing else. */
+export function attemptsCollection(o) {
+    return {
+        slug: o.attempts,
+        admin: { hidden: true },
+        access: { read: nobody, create: nobody, update: nobody, delete: nobody },
+        fields: [
+            { name: 'kind', type: 'text', required: true, index: true },
+            { name: 'keyHash', type: 'text', required: true, index: true },
+            { name: 'at', type: 'date', required: true, index: true },
+        ],
+    };
+}
+/** Added to the auth collection: where an account is in sign-up. Accounts made any other way are active. */
+export function signupStatusField(o) {
+    return {
+        name: 'signupStatus',
+        type: 'select',
+        defaultValue: 'active',
+        index: true,
+        options: [
+            { label: 'Active', value: 'active' },
+            { label: 'Waiting for approval', value: 'pending' },
+        ],
+        // Read by the account itself and by sign-up's managers; set only by the plugin.
+        access: {
+            create: nobody,
+            update: nobody,
+            read: async (args) => {
+                const { req, doc } = args;
+                if (!req.user)
+                    return false;
+                if (doc?.id !== undefined && String(req.user.id) === String(doc.id))
+                    return true;
+                return isManager(o, args);
+            },
+        },
+        admin: { position: 'sidebar', readOnly: true, description: 'Set by sign-up. Only active accounts can sign in.' },
+    };
+}

package/dist/emails.d.ts

@@ -0,0 +1,3 @@
+import type { Emails } from './types.js';
+/** Plain defaults. Sites pass their own, branded versions with `emails`. */
+export declare const defaultEmails: Emails;

package/dist/emails.js

@@ -0,0 +1,25 @@
+import { plainEmail } from './util.js';
+/** Plain defaults. Sites pass their own, branded versions with `emails`. */
+export const defaultEmails = {
+    verify: ({ url, hours }) => plainEmail('Confirm your email to finish signing up', [
+        'Someone asked for an account with this email address. If that was you, confirm it here:',
+        url,
+        `The link works for ${hours} hours. If you didn't ask, you can ignore this email and nothing will happen.`,
+    ]),
+    pending: () => plainEmail('Thanks, your request is in', [
+        'Your email is confirmed and your request is waiting for a person to look at it.',
+        'We\'ll email you as soon as it\'s decided. You don\'t need to do anything else.',
+    ]),
+    approved: ({ signInURL }) => plainEmail('You\'re in', ['Your account is ready. Sign in with the email and password you chose:', signInURL]),
+    declined: ({ note }) => plainEmail('About your account request', [
+        'Thank you for asking. We can\'t open an account for you at the moment.',
+        ...(note ? [note] : []),
+        'Your request and the details you gave us will be deleted.',
+    ]),
+    alreadyHasAccount: ({ signInURL, resetURL }) => plainEmail('You already have an account', [
+        'Someone asked for a new account with this email address, but you already have one.',
+        `Sign in here: ${signInURL}`,
+        `If you've forgotten your password, you can set a new one here: ${resetURL}`,
+        'If you didn\'t ask, you can ignore this email.',
+    ]),
+};

package/dist/endpoints.d.ts

@@ -0,0 +1,2 @@
+import type { Endpoint } from 'payload';
+export declare const signupEndpoints: Endpoint[];

package/dist/endpoints.js

@@ -0,0 +1,137 @@
+import { currentMode, readSignupRequest, submitSignup, verifySignup } from './flow.js';
+import { SignupError } from './util.js';
+/** A JSON answer. `setCookies` are the cookies the site's checks asked for, set on this response. */
+const json = (body, status = 200, setCookies = []) => {
+    const headers = new Headers({ 'Cache-Control': 'no-store' });
+    for (const cookie of setCookies)
+        headers.append('Set-Cookie', cookie);
+    return Response.json(body, { status, headers });
+};
+const failure = (error, req) => {
+    if (error instanceof SignupError)
+        return json({ error: { code: error.code, message: error.message } }, error.status, error.setCookies);
+    req.payload.logger.error({ err: error, msg: 'signup: request failed' });
+    return json({ error: { code: 'error', message: 'Something went wrong. Please try again later.' } }, 500);
+};
+const body = async (req) => {
+    try {
+        const type = req.headers.get('content-type') ?? '';
+        if (type.includes('application/x-www-form-urlencoded') || type.includes('multipart/form-data'))
+            return Object.fromEntries((await req.formData()).entries());
+        return ((await req.json?.()) ?? {});
+    }
+    catch {
+        return {};
+    }
+};
+const escape = (s) => s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+/** A bare page for sites without their own: readable, keyboard-friendly, no scripts. */
+const page = (title, inner, status = 200, setCookies = []) => withSetCookies(new Response(`<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="robots" content="noindex"><title>${escape(title)}</title>` +
+    '<style>body{font:16px/1.5 system-ui,sans-serif;max-width:32rem;margin:4rem auto;padding:0 1rem;color:#1a1a1a;background:#fff}button{font:inherit;padding:.6rem 1.2rem;border-radius:.4rem;border:0;background:#1a4d2e;color:#fff;cursor:pointer}button:focus-visible,input:focus-visible{outline:3px solid #f2a900;outline-offset:2px}dl{display:grid;grid-template-columns:max-content 1fr;gap:.25rem 1rem}dt{font-weight:600}dd{margin:0}input{font:inherit;padding:.5rem;width:100%;max-width:20rem;box-sizing:border-box}.error{color:#b00020;font-weight:600}@media (prefers-color-scheme:dark){.error{color:#ff8a80}}@media (prefers-color-scheme:dark){body{background:#121212;color:#eee}}</style>' +
+    `</head><body><main><h1>${escape(title)}</h1>${inner}</main></body></html>`, { status, headers: { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store', 'Referrer-Policy': 'no-referrer' } }), setCookies);
+/** Set the cookies the site's checks asked for on this response. */
+function withSetCookies(res, setCookies = []) {
+    for (const cookie of setCookies)
+        res.headers.append('Set-Cookie', cookie);
+    return res;
+}
+/** What they asked for, so they can see it's their request before confirming. */
+const summary = (shown) => shown
+    ? `<p>You asked for an account as <strong>${escape(shown.email)}</strong>.</p>` +
+        (shown.details.length ? `<dl>${shown.details.map((d) => `<dt>${escape(d.label)}</dt><dd>${escape(d.value)}</dd>`).join('')}</dl>` : '')
+    : '';
+/** Choose a password, twice, then confirm. Labels and autocomplete hints for password managers and screen readers. */
+const confirmForm = (req, token, shown = null) => {
+    const min = req.payload.config.custom?.signup?.minPasswordLength ?? 10;
+    return (summary(shown) +
+        `<p>Choose the password for your account, then press the button to confirm this is your email address.</p>` +
+        `<form method="post" action="${escape(req.payload.config.routes.api)}/signup/verify">` +
+        `<input type="hidden" name="token" value="${escape(token)}">` +
+        `<p><label for="password">Password (at least ${min} characters)</label><br><input id="password" name="password" type="password" autocomplete="new-password" minlength="${min}" maxlength="256" required></p>` +
+        `<p><label for="confirm">The same password again</label><br><input id="confirm" name="confirm" type="password" autocomplete="new-password" minlength="${min}" maxlength="256" required></p>` +
+        `<button type="submit">Confirm my email</button></form>` +
+        `<p>If you didn't ask for an account, close this page. Nothing happens unless you press the button.</p>`);
+};
+export const signupEndpoints = [
+    {
+        // What the form should show: open to requests or not, and the message when it isn't.
+        path: '/signup/mode',
+        method: 'get',
+        handler: async (req) => {
+            const { mode, message } = await currentMode(req.payload);
+            return json({ mode, accepting: mode === 'open' || mode === 'approval', message });
+        },
+    },
+    {
+        path: '/signup/request',
+        method: 'post',
+        handler: async (req) => {
+            try {
+                const b = await body(req);
+                const { setCookies, ...out } = await submitSignup(req.payload, { email: b.email, details: b.details, answers: b.answers, humanToken: typeof b.humanToken === 'string' ? b.humanToken : undefined }, req);
+                return json(out, 202, setCookies);
+            }
+            catch (error) {
+                return failure(error, req);
+            }
+        },
+    },
+    {
+        // The link in the email. Opening it never verifies by itself (mail scanners open links): the person chooses
+        // their password here and presses the button, so the account is made by whoever owns the inbox.
+        path: '/signup/verify',
+        method: 'get',
+        handler: async (req) => {
+            const token = new URL(req.url ?? 'http://x').searchParams.get('token') ?? '';
+            // Show the request so they know what they're confirming. Reading changes nothing, so a mail scanner opening
+            // the link is harmless. A dead link says so now, rather than after they've typed a password twice.
+            try {
+                return page('Confirm your email', confirmForm(req, token, await readSignupRequest(req.payload, { token }, req)));
+            }
+            catch (error) {
+                if (error instanceof SignupError && error.code === 'badLink')
+                    return page('That didn\'t work', `<p>${escape(error.message)}</p>`, 400);
+                if (!(error instanceof SignupError))
+                    req.payload.logger.error({ err: error, msg: 'signup: request not readable for the confirm page' });
+                // Too many tries or a lookup that broke: the form still works, without the summary.
+                return page('Confirm your email', confirmForm(req, token));
+            }
+        },
+    },
+    {
+        path: '/signup/verify',
+        method: 'post',
+        handler: async (req) => {
+            const b = await body(req);
+            const html = !(req.headers.get('content-type') ?? '').includes('json');
+            try {
+                // The page asks twice; the JSON API leaves that to the site's own form.
+                if (html && b.password !== b.confirm)
+                    throw new SignupError('passwordMismatch', 'The two passwords don\'t match. Please type the same password twice.');
+                const { setCookies, ...out } = await verifySignup(req.payload, { token: b.token, password: b.password }, req);
+                if (!html)
+                    return json(out, 200, setCookies);
+                return out.status === 'active'
+                    ? page('You\'re in', '<p>Your email is confirmed and your account is ready. We\'ve sent you an email with the sign-in link.</p>', 200, setCookies)
+                    : page('Thanks, you\'re on the list', '<p>Your email is confirmed. A person will look at your request, and we\'ll email you when it\'s decided.</p>', 200, setCookies);
+            }
+            catch (error) {
+                if (!html)
+                    return failure(error, req);
+                const message = error instanceof SignupError ? error.message : 'Something went wrong. Please try again later.';
+                // A password problem keeps the form, so they can try again with the same link.
+                if (error instanceof SignupError && (error.code === 'password' || error.code === 'passwordMismatch')) {
+                    // A short password came back from verifySignup, which already counted this try. A mismatch never reached
+                    // it, so that read counts, and the page can't be used to read past the limit.
+                    const shown = await readSignupRequest(req.payload, { token: b.token }, req, { countAttempt: error.code === 'passwordMismatch' }).catch((e) => {
+                        if (!(e instanceof SignupError))
+                            req.payload.logger.error({ err: e, msg: 'signup: request not readable for the confirm page' });
+                        return null;
+                    });
+                    return page('Confirm your email', `<p role="alert" class="error">${escape(message)}</p>${confirmForm(req, String(b.token ?? ''), shown)}`, 400);
+                }
+                return page('That didn\'t work', `<p>${escape(message)}</p>`, error instanceof SignupError ? error.status : 500, error instanceof SignupError ? error.setCookies : []);
+            }
+        },
+    },
+];

package/dist/flow.d.ts

@@ -0,0 +1,93 @@
+import type { Payload } from 'payload';
+import type { Req, SignupMode } from './types.js';
+type Doc = Record<string, any>;
+/** What the form says for every request it takes, whatever happened, so it never tells who has an account. */
+export declare const RECEIVED = "Thanks. Check your email to continue.";
+/**
+ * The mode now. The site's lock (`forceMode`, or `SIGNUP_MODE`) wins, then the admin setting. Anything that
+ * can't be read or isn't a known mode is `closed`: sign-up fails shut.
+ */
+export declare function currentMode(payload: Payload): Promise<{
+    mode: SignupMode;
+    message: string | null;
+}>;
+/** What a taken request answers. `setCookies` is there only when a check asked for cookies. */
+export type SubmitResult = {
+    ok: true;
+    message: string;
+    setCookies?: string[];
+};
+export type SignupInput = {
+    email?: unknown;
+    /** The request's details, checked against the site's `fields` and kept with the request. */
+    details?: unknown;
+    /** Answers only the site's checks see, never stored (for example a birth month and year for an age gate). */
+    answers?: unknown;
+    humanToken?: string;
+};
+/**
+ * Take a sign-up request. No account and no password yet: the account is made when the address's owner confirms
+ * and chooses a password (`verifySignup`), so nobody can set up an account under someone else's address.
+ *
+ * Refusals the person can act on (mode, a bad email, a site check, too many tries) throw a `SignupError`.
+ * Everything else ends in the same `{ ok: true }` and an email, whether the address is new, already has an
+ * account, or is already waiting: the form never tells. Each case does the same lookups.
+ *
+ * Cookies the checks ask for come back as `setCookies`, on the result or on the refusal (`SignupError`), for the
+ * response. Sign-up's own endpoint sets them; a site's own form should too.
+ */
+export declare function submitSignup(payload: Payload, input: SignupInput, req?: Req): Promise<SubmitResult>;
+export type RequestDetail = {
+    name: string;
+    label: string;
+    value: string;
+};
+/**
+ * What the person asked for, from the link, so the confirm page can show it before they press the button: the
+ * email, and the fields the site listed in `confirmShows`, as words. Only those: a mistyped address sends the link
+ * to a stranger. Hidden fields and fields with their own read access are never shown, even when listed. Answers
+ * meant only for checks were never stored, and what checks set for the account isn't shown. It only reads: the
+ * link still works afterwards. An unknown, used or expired link gets the same `badLink` refusal as confirming would.
+ * `countAttempt: false` is for a page that just counted one through `verifySignup`.
+ */
+export declare function readSignupRequest(payload: Payload, input: {
+    token?: unknown;
+}, req?: Req, { countAttempt }?: {
+    countAttempt?: boolean;
+}): Promise<{
+    email: string;
+    details: RequestDetail[];
+}>;
+export type VerifyInput = {
+    token?: unknown;
+    password?: unknown;
+};
+/** What a confirm answers. `setCookies` is there only when a confirm check asked for cookies. */
+export type VerifyResult = {
+    status: 'pending' | 'active';
+    setCookies?: string[];
+};
+/**
+ * Confirm the email from the link, choosing the account's password: only the person with the inbox can do this,
+ * so the account belongs to the address's owner. The account is made now: waiting for approval, or (open mode)
+ * active at once. If sign-up was shut since they asked, the request still waits for staff.
+ */
+export declare function verifySignup(payload: Payload, input: VerifyInput, req?: Req): Promise<VerifyResult>;
+/**
+ * Approve or decline a waiting request, inside the caller's transaction: approving activates the account and runs
+ * the site's `onApprove`; declining deletes the account (it never signed in). Returns the request's new data. The
+ * email goes after the transaction commits; a failed email is logged and doesn't undo the decision.
+ */
+export declare function decide(payload: Payload, request: Doc, to: 'approved' | 'declined', req: Req): Promise<Doc>;
+/** Send what `decide` queued on this request. */
+export declare function flushAfterCommit(req: Req): Promise<void>;
+/**
+ * Delete what's past its time: requests decided, abandoned or never confirmed more than `retentionDays` ago, and
+ * rate-limit counts older than a day. Waiting requests are kept until
+ * someone decides them. Run it daily, from the site's scheduled job.
+ */
+export declare function pruneSignupRequests(payload: Payload, now?: Date): Promise<{
+    requests: number;
+    attempts: number;
+}>;
+export {};