Security
How the plugin handles keys, webhooks and data, what it stores, what stays your responsibility, and how to report a vulnerability.
Keys and secrets
- Your Nuvion secret key and webhook signing secret stay on your server. The plugin never sends them to a browser and never logs them. Error messages from Nuvion calls do not include the request.
- Keep them in the environment or a secrets manager, never in the repository. With per-tenant credentials the functions you pass return the key at call time, and an empty value fails the call.
- Rotate a webhook secret by creating a new webhook, switching
webhookSecret, then deleting the old one.
Webhooks
- Signature. HMAC-SHA256 over
{timestamp}.{raw body}, compared in constant time. The plugin reads the raw bytes, which is why the webhook is handled before Better Auth parses the body. A bad or missing signature returns401. - Replay window. Set
webhookToleranceMs(for example five minutes). It is off until you set it. - Confirmation. A valid signature proves the event came from Nuvion's webhook, not that its body is true. By default (
confirmEvents) the plugin asks Nuvion whether the funding session settled or the transfer finished before it acts, and Nuvion's record wins. See Webhooks. - Duplicates. Event ids are unique, state changes are compare-and-set, and every transfer carries a reference derived from the leg and attempt, so a redelivery or a concurrent delivery cannot pay a leg twice.
- Responses. Only a temporary failure answers
503. Everything else is acknowledged, so a bad event cannot get your webhook blacklisted.
Authorization
- Payment, binding, fee-rule and reconcile endpoints need a Better Auth session of an
owneroradminof the organization concerned. A payer can read only their own payments. GET|POST /nuvion/cron/reconcileexists only when you setcronSecret(at least 16 characters) and is compared in constant time.- The webhook route is public by design: its authentication is the signature.
- Browser requests rely on Better Auth's own CSRF and origin checks. Add Better Auth's rate limiting to your sign-in and payment routes; the plugin does not add its own.
What the plugin stores
Tables with the nuvion prefix: payments (reference, amounts, status, the checkout session id, and the payer's user id when you charge without an organization), legs (who pays whom, amounts, state, provider references), event ids with timestamps, bindings (Nuvion entity and account ids), saved counterparty ids and fee rules.
It does not store card data, bank account numbers, identity documents or the personal details Nuvion sends in entity events. The onEntityUpdated hook receives only the entity id, status, parent id and the bound organizations.
The admin view
@umohpyro/better-auth-nuvion/react renders everything as text, with no inline styles, scripts or raw HTML, so it works under a strict Content Security Policy. See Styling the admin view.
What stays your responsibility
Your database and its backups, HTTPS, session and cookie settings, who is an admin of which organization, the code in your hooks, and the legal and compliance duties of taking payments in your market. The plugin moves money between Nuvion accounts that you configured; Nuvion's own onboarding and compliance (entities, KYC, account approval) stay with Nuvion and you.
Reporting a vulnerability
Please report it privately, not in a public issue. On GitHub use Security, Report a vulnerability on the repository. If that is not available to you, open an issue that says only that you have a security report, with no details, and a maintainer will arrange a private channel. Include the version, what you did and what you saw. You will get an acknowledgement, and a fix or a decision before anything is disclosed.
In scope: the plugin and engine (signature checks, event confirmation, authorization, key handling, anything that could move money to the wrong place or twice). Out of scope: Nuvion's own API and dashboard, which go to Nuvion, and vulnerabilities in Better Auth or other dependencies, which go upstream.