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

package/dist/types.d.ts

@@ -0,0 +1,187 @@
+import type { Access, Field, Payload, PayloadRequest } from 'payload';
+export type ID = string | number;
+export type Req = Partial<PayloadRequest>;
+/**
+ * How people get an account.
+ * - `open`: anyone who verifies their email gets an active account.
+ * - `approval`: verified requests wait as disabled accounts until staff approve or decline.
+ * - `invite-only`: the form refuses; accounts come only from the site's own invitations.
+ * - `closed`: the form refuses; nobody can ask.
+ */
+export type SignupMode = 'open' | 'approval' | 'invite-only' | 'closed';
+export declare const MODES: SignupMode[];
+/** A user's place in sign-up. Accounts are made on confirming, as `pending` (or `active` in open mode); accounts made any other way are `active`. */
+export type SignupStatus = 'pending' | 'active';
+/** A request's place in the queue. */
+export type RequestStatus = 'unverified' | 'pending' | 'approved' | 'declined';
+/** What a site check says about a request. Return nothing (or `{}`) to let it through. */
+export type CheckResult = {
+    /** Refuse, with this message shown to the person. Nothing is stored. */
+    refuse?: string;
+    /** Let it through, but show this to staff in the queue (for example "minor"). */
+    flag?: string;
+    /** Extra values for the new user (for example a minor flag), merged after `toUser`. */
+    userData?: Record<string, unknown>;
+    /**
+     * `Set-Cookie` header values for the response (for example a "stay blocked" cookie), refusals included. Sign-up's
+     * endpoint sets them; `submitSignup` hands them back for a site's own form. Single-line strings only: anything
+     * else is a broken check, and refuses.
+     */
+    setCookies?: string[];
+};
+/**
+ * `data` is the request's details (kept); `answers` are for checks only and never stored. `req` is the request
+ * itself, headers and all. A check typed to take less (a `Partial<PayloadRequest>`) fits too.
+ */
+export type Check = (args: {
+    data: Record<string, unknown>;
+    answers: Record<string, unknown>;
+    email: string;
+    req: PayloadRequest;
+    payload: Payload;
+}) => CheckResult | void | Promise<CheckResult | void>;
+/**
+ * A check run again when the person confirms, before the account is made, for what can change in the meantime
+ * (a domain blocked since, sign-up closed to a group). It sees the stored details and the request's flag, never
+ * the check-only answers, which were never stored. A refusal declines the request; a check that throws refuses
+ * for now and the link keeps working.
+ */
+export type ConfirmCheck = (args: {
+    data: Record<string, unknown>;
+    email: string;
+    flag: string | null;
+    req: PayloadRequest;
+    payload: Payload;
+}) => CheckResult | void | Promise<CheckResult | void>;
+export type Email = {
+    subject: string;
+    html: string;
+    text: string;
+};
+export type EmailContext = {
+    email: string;
+    name?: string;
+    req: Req;
+    payload: Payload;
+};
+export type Emails = {
+    /** The link that proves they own the address. Sent for new requests (and again on a repeat). */
+    verify: (ctx: EmailContext & {
+        url: string;
+        hours: number;
+    }) => Email | Promise<Email>;
+    /** After verifying, in approval mode: "we'll be in touch". */
+    pending: (ctx: EmailContext) => Email | Promise<Email>;
+    /** Approved, or verified in open mode: "you're in". */
+    approved: (ctx: EmailContext & {
+        signInURL: string;
+    }) => Email | Promise<Email>;
+    /** Declined: polite, with the optional note staff wrote for them. */
+    declined: (ctx: EmailContext & {
+        note?: string;
+    }) => Email | Promise<Email>;
+    /** Someone asked with an address that already has an account: sent instead of a request, so the form never tells. */
+    alreadyHasAccount: (ctx: EmailContext & {
+        signInURL: string;
+        resetURL: string;
+    }) => Email | Promise<Email>;
+};
+/** What a rate limit is counting. */
+export type LimitKind = 'address' | 'email' | 'site' | 'verify';
+/** Returns true to allow. Throwing, or anything else, refuses (fail closed). */
+export type RateLimit = (kind: LimitKind, key: string, req: Req) => boolean | Promise<boolean>;
+export type SignupPluginOptions = {
+    /** The auth collection accounts are made in. Default: `config.admin.user`, else `users`. */
+    users?: string;
+    /** Slugs. Defaults: `signup-requests`, `signup-settings` (a global), `signup-attempts`. */
+    slugs?: {
+        requests?: string;
+        settings?: string;
+        attempts?: string;
+    };
+    /** The request's details: plain Payload fields, validated by Payload and shown to staff. Email and password are built in. */
+    fields?: Field[];
+    /** Run at submit, in order. A refusal stops the request; a check that throws refuses it (fail closed). */
+    checks?: Check[];
+    /** Run when the person confirms, in order, before the account is made. Optional; see `ConfirmCheck`. */
+    confirmChecks?: ConfirmCheck[];
+    /** Map a request's details onto the new user. Default: copies `name` when there is one. */
+    toUser?: (data: Record<string, unknown>) => Record<string, unknown>;
+    /** After approval (or verification in open mode), inside the same transaction: give roles, memberships. Throw to refuse. */
+    onApprove?: (args: {
+        user: Record<string, unknown>;
+        request: Record<string, unknown>;
+        req: Req;
+        payload: Payload;
+    }) => void | Promise<void>;
+    /** Email bodies. Plain-text defaults otherwise. */
+    emails?: Partial<Emails>;
+    /** Where links point. `verifyURL` gets the token; defaults use `serverURL`. */
+    urls?: {
+        verify?: (token: string) => string;
+        signIn?: string;
+        resetPassword?: string;
+    };
+    /** The site's rate limiter. Default: a built-in one that stores hashed keys only. */
+    rateLimit?: RateLimit;
+    /** Built-in limiter's limits per hour. Defaults: 5 per address, 3 per email, 200 site-wide, 20 verify attempts per address. */
+    limits?: Partial<Record<LimitKind, number>>;
+    /** The person's network address, for rate limits. Default: the first `x-forwarded-for` entry, else `x-real-ip`. */
+    clientAddress?: (req: Req) => string | null;
+    /** A human check, such as Turnstile. Returns true for a person; false or throwing refuses. */
+    verifyHuman?: (args: {
+        token: string | undefined;
+        address: string | null;
+        req: Req;
+    }) => boolean | Promise<boolean>;
+    /**
+     * Who decides requests and changes the mode. Required: the plugin won't start without it, so a site can't leave the
+     * queue open to every signed-in member by accident. Only an answer of exactly `true`, for a signed-in user, counts;
+     * anything else, a query (`Where`) or a thrown error included, is a no. Typed as Payload's `Access` so existing rules fit.
+     */
+    access: {
+        manage: Access;
+    };
+    /** A field that separates sites, such as `tenant`. The request takes its value from `scopeFor`. */
+    scopeField?: string;
+    /** Which site a request belongs to (with `scopeField`). Return null to refuse. */
+    scopeFor?: (req: Req) => ID | null | Promise<ID | null>;
+    /** Days a decided, abandoned or unverified request is kept. Default 90. */
+    retentionDays?: number;
+    /**
+     * Which of your fields the confirm page shows, by name, so the person can see it's their request. Default: none,
+     * only the email. Someone who mistypes their address sends the link to a stranger's inbox, so show only what's
+     * safe for a stranger to read. Hidden fields and fields with their own read access are never shown.
+     */
+    confirmShows?: string[];
+    /** Hours a verification link works. Default 48. */
+    verifyHours?: number;
+    /** Minimum password length. Default 10. */
+    minPasswordLength?: number;
+    /** Overrides the admin setting when set, as a hard lock. Default: `process.env.SIGNUP_MODE`. */
+    forceMode?: SignupMode | null;
+    /** Admin group. Default 'Sign-up'. */
+    adminGroup?: string;
+};
+export type ResolvedSignup = Required<Pick<SignupPluginOptions, 'retentionDays' | 'verifyHours' | 'minPasswordLength' | 'adminGroup'>> & {
+    users: string;
+    requests: string;
+    settings: string;
+    attempts: string;
+    fields: Field[];
+    checks: Check[];
+    confirmChecks: ConfirmCheck[];
+    toUser: NonNullable<SignupPluginOptions['toUser']>;
+    onApprove?: SignupPluginOptions['onApprove'];
+    emails: Emails;
+    urls: SignupPluginOptions['urls'];
+    rateLimit?: RateLimit;
+    limits: Record<LimitKind, number>;
+    clientAddress: NonNullable<SignupPluginOptions['clientAddress']>;
+    verifyHuman?: SignupPluginOptions['verifyHuman'];
+    manage: Access;
+    scopeField?: string;
+    scopeFor?: SignupPluginOptions['scopeFor'];
+    forceMode: SignupMode | null;
+    confirmShows: string[];
+};

package/dist/types.js

@@ -0,0 +1 @@
+export const MODES = ['open', 'approval', 'invite-only', 'closed'];

package/dist/util.d.ts

@@ -0,0 +1,54 @@
+import { APIError, type Payload, type PayloadRequest } from 'payload';
+import type { ID, Req, ResolvedSignup } from './types.js';
+/** A refusal the person sees, with a code for the site to branch on. */
+export declare class SignupError extends APIError<{
+    code: string;
+}> {
+    code: string;
+    /** `Set-Cookie` values from the site's checks, for the response that carries this refusal. */
+    setCookies?: string[];
+    constructor(code: string, message: string, status?: number);
+}
+export declare const signupOf: (payload: Payload) => ResolvedSignup;
+export declare const normalizeEmail: (email: unknown) => string;
+export declare const validEmail: (email: string) => boolean;
+/** A random token for a link, and the hash that's stored instead of it. */
+export declare const newToken: () => string;
+export declare const hashToken: (secret: string, token: string) => string;
+/** Keys for rate limits are stored hashed, never as raw addresses or emails. */
+export declare const hashKey: (secret: string, kind: string, key: string) => string;
+export declare const idOf: (v: unknown) => ID | null;
+/**
+ * The default client address: `x-real-ip` when present (set by the host's proxy, such as Vercel's), else the last
+ * `x-forwarded-for` entry, which is the one a single trusted proxy appended. Earlier entries come from the visitor
+ * and can say anything. Behind any other arrangement of proxies, pass your own `clientAddress`.
+ */
+export declare const defaultClientAddress: (req: Req) => string | null;
+/** Run `fn` in a transaction, or inside the caller's when `req` already has one. */
+export declare function transaction<T>(payload: Payload, req: Req | undefined, fn: (req: Req) => Promise<T>): Promise<T>;
+/** The request Payload operations want, from a partial one. The copy keeps `headers`, a getter a spread would drop. */
+export declare const asReq: (payload: Payload, req: Req) => PayloadRequest;
+/**
+ * The request itself, never a copy: a spread drops the getters of the request Payload made (`headers` among them),
+ * so checks and limits would see no headers and no client address. A request Payload made is used as it is. A
+ * partial one (a site calling `submitSignup` from its own code) is completed in place by Payload's `createLocalReq`.
+ */
+export declare function requestFor(payload: Payload, req?: Req): Promise<PayloadRequest>;
+/**
+ * The `Set-Cookie` values a check returned. Only printable ASCII (space to `~`), as RFC 6265's cookie syntax allows:
+ * anything else (a line break, a control character, any character past `~`) is a broken check, and refuses before
+ * anything is stored or emailed, rather than failing later when the header is set.
+ */
+export declare function cookiesOf(value: unknown): string[];
+/**
+ * Run a check with a response-header list of its own, so it can't add headers to Sign-up's response through
+ * `req.responseHeaders` (Payload's router sends that list). Cookies go through `setCookies`, which are checked.
+ * The request's own list (an auth strategy's refreshed cookie, say) is put back as it was.
+ */
+export declare function withOwnResponseHeaders<T>(req: PayloadRequest, fn: () => T | Promise<T>): Promise<T>;
+/** Plain paragraphs as both text and simple HTML. */
+export declare const plainEmail: (subject: string, paragraphs: string[]) => {
+    subject: string;
+    text: string;
+    html: string;
+};

package/dist/util.js

@@ -0,0 +1,116 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { APIError, createLocalReq } from 'payload';
+/** A refusal the person sees, with a code for the site to branch on. */
+export class SignupError extends APIError {
+    code;
+    /** `Set-Cookie` values from the site's checks, for the response that carries this refusal. */
+    setCookies;
+    constructor(code, message, status = 400) {
+        super(message, status, { code }, true);
+        this.code = code;
+    }
+}
+export const signupOf = (payload) => {
+    const o = payload.config.custom?.signup;
+    if (!o)
+        throw new Error('Sign-up: the plugin is not configured on this site.');
+    return o;
+};
+export const normalizeEmail = (email) => (typeof email === 'string' ? email.trim().toLowerCase() : '');
+export const validEmail = (email) => email.length <= 254 && /^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email);
+/** A random token for a link, and the hash that's stored instead of it. */
+export const newToken = () => randomBytes(32).toString('base64url');
+export const hashToken = (secret, token) => createHash('sha256').update(`${secret}:signup:${token}`).digest('hex');
+/** Keys for rate limits are stored hashed, never as raw addresses or emails. */
+export const hashKey = (secret, kind, key) => createHash('sha256').update(`${secret}:signup-limit:${kind}:${key}`).digest('hex');
+export const idOf = (v) => {
+    if (v === null || v === undefined || v === '')
+        return null;
+    if (typeof v === 'object')
+        return (v.id ?? null);
+    return v;
+};
+/**
+ * The default client address: `x-real-ip` when present (set by the host's proxy, such as Vercel's), else the last
+ * `x-forwarded-for` entry, which is the one a single trusted proxy appended. Earlier entries come from the visitor
+ * and can say anything. Behind any other arrangement of proxies, pass your own `clientAddress`.
+ */
+export const defaultClientAddress = (req) => {
+    const h = req.headers;
+    const real = h?.get?.('x-real-ip')?.trim();
+    if (real)
+        return real;
+    return h?.get?.('x-forwarded-for')?.split(',').at(-1)?.trim() || null;
+};
+/** Run `fn` in a transaction, or inside the caller's when `req` already has one. */
+export async function transaction(payload, req, fn) {
+    // Copies of req share one context object, so work queued inside (emails) is seen outside.
+    if (req)
+        req.context ??= {};
+    const base = { ...(req ?? {}), headers: req?.headers, payload };
+    if (base.transactionID)
+        return fn(base);
+    const id = (await payload.db.beginTransaction?.()) ?? undefined;
+    const r = { ...base, transactionID: id };
+    try {
+        const out = await fn(r);
+        if (id)
+            await payload.db.commitTransaction(id);
+        return out;
+    }
+    catch (error) {
+        if (id)
+            await payload.db.rollbackTransaction(id).catch(() => undefined);
+        throw error;
+    }
+}
+/** The request Payload operations want, from a partial one. The copy keeps `headers`, a getter a spread would drop. */
+export const asReq = (payload, req) => ({ ...req, headers: req.headers, payload });
+/**
+ * The request itself, never a copy: a spread drops the getters of the request Payload made (`headers` among them),
+ * so checks and limits would see no headers and no client address. A request Payload made is used as it is. A
+ * partial one (a site calling `submitSignup` from its own code) is completed in place by Payload's `createLocalReq`.
+ */
+export async function requestFor(payload, req = {}) {
+    if (req.payload && req.payloadAPI && req.headers)
+        return req;
+    return createLocalReq({ req }, payload);
+}
+/**
+ * The `Set-Cookie` values a check returned. Only printable ASCII (space to `~`), as RFC 6265's cookie syntax allows:
+ * anything else (a line break, a control character, any character past `~`) is a broken check, and refuses before
+ * anything is stored or emailed, rather than failing later when the header is set.
+ */
+export function cookiesOf(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value) || !value.every((c) => typeof c === 'string' && /^[\x20-\x7e]+$/.test(c)))
+        throw new Error('Sign-up: a check returned setCookies that are not a list of printable ASCII strings.');
+    return [...value];
+}
+/**
+ * Run a check with a response-header list of its own, so it can't add headers to Sign-up's response through
+ * `req.responseHeaders` (Payload's router sends that list). Cookies go through `setCookies`, which are checked.
+ * The request's own list (an auth strategy's refreshed cookie, say) is put back as it was.
+ */
+export async function withOwnResponseHeaders(req, fn) {
+    const had = Object.prototype.hasOwnProperty.call(req, 'responseHeaders');
+    const own = req.responseHeaders;
+    req.responseHeaders = new Headers();
+    try {
+        return await fn();
+    }
+    finally {
+        if (had)
+            req.responseHeaders = own;
+        else
+            delete req.responseHeaders;
+    }
+}
+const escape = (s) => s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+/** Plain paragraphs as both text and simple HTML. */
+export const plainEmail = (subject, paragraphs) => ({
+    subject,
+    text: paragraphs.join('\n\n'),
+    html: paragraphs.map((p) => `<p>${escape(p).replace(/(https?:\/\/\S+)/g, '<a href="$1">$1</a>')}</p>`).join('\n'),
+});

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@extantape/payload-plugin-signup",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "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.",
+  "homepage": "https://github.com/ExtantApe/payload-plugin-signup#readme",
+  "bugs": {
+    "url": "https://github.com/ExtantApe/payload-plugin-signup/issues"
+  },
+  "keywords": [
+    "payload",
+    "payload-plugin",
+    "payloadcms",
+    "authentication",
+    "multi-tenant",
+    "signup",
+    "registration",
+    "approval",
+    "waitlist",
+    "invite-only",
+    "email-verification"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ExtantApe/payload-plugin-signup.git"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "leak-check": "bash scripts/leak-check.sh",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run typecheck && npm test"
+  },
+  "peerDependencies": {
+    "payload": "^3.80.0"
+  },
+  "devDependencies": {
+    "@payloadcms/db-mongodb": "3.92.1",
+    "@types/node": "^24.0.0",
+    "graphql": "^16.14.2",
+    "mongodb-memory-server": "^11.3.0",
+    "payload": "3.92.1",
+    "typescript": "^5.9.0",
+    "vitest": "^3.2.0"
+  }
+}