Skip to content

Per-domain hooks: who may hold an address, and a stored-mail notification - #6

Merged
oceanseth merged 2 commits into
mainfrom
fable52/domain-hooks
Nov 17, 2026
Merged

oceanseth merged 2 commits into
mainfrom
fable52/domain-hooks

Conversation

@oceanseth

Copy link
Copy Markdown
Owner

What

One VCMail Lambda can serve several mail domains. This lets each domain add its own rules in a file named after it, api/domain-hooks/<domain>.js. Two optional hooks, both documented in api/domain-hooks/_template.js:

  • verifyUsername decides whether a user may claim a new address. It runs in setupEmail before anything is written, and is skipped when the caller already holds the address. It fails closed: if the hook throws, takes longer than 12 seconds, or returns anything other than { allowed: true }, the address is refused.
  • onEmailStored is told about each message after it is stored, with source: 'ses' for mail from outside and 'local' for mail between two addresses on the domain. It runs once every recipient of a message is stored, so it cannot hold mail up. Errors are logged and ignored, and it is cut off after 5 seconds.

A domain without a hook file behaves exactly as before.

masky.ai

api/domain-hooks/masky.ai.js hands both decisions to the Masky API by invoking its Lambda directly, so the rules for masky.ai addresses live in one place. The role needs lambda:InvokeFunction on that function.

Also

  • The address index and the mail profile are written by the API only. database.rules.json and sendEmail now reflect that. This supersedes Username index: holder-only writes #5.
  • sendEmail keeps the subject to one header line.
  • storeEmailForUser returns what it stored.
  • npm test runs both test files.

Testing

  • 35 tests pass (npm test), 32 of them new: the hook runner (allow, refuse, throw, hang, load failure, non-answers), the masky.ai hook, setupEmail with and without a hook, sendEmail, and the order of storing and notifying for a message with several recipients.

Deploying

The Lambda bundle must include api/domainHooks.js and the api/domain-hooks/ directory.

🤖 Generated with Claude Code

…tion

A domain can add api/domain-hooks/<domain>.js with two optional hooks,
documented in api/domain-hooks/_template.js:

- verifyUsername decides whether a user may claim a new address. It fails
  closed: no explicit yes, no address.
- onEmailStored is told about each message once every recipient of it is
  stored, so it cannot hold mail up.

Domains without a hook file behave as before. Adds the masky.ai hooks,
which hand both decisions to the Masky API.

The address index and mail profile are written by the API only; the rules
file and sendEmail now reflect that. A subject is kept to one header line.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Usernames may contain a dot, but the address index is keyed by username and
a Realtime Database key cannot hold one, so setting up first.last failed.
The index key now stores a dot as a comma; names without a dot keep their
key, so existing entries are unchanged.

- A username cannot start or end with a dot or have two in a row.
- Only a well-formed username is looked up in the index.
- Delivery between two addresses on a domain no longer depends on the
  capitalisation of the recipient.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant