@selvajs/server 1.1.0 → 1.2.0

package/dist/notifications/index.d.ts

@@ -0,0 +1,3 @@
+export { SmtpNotificationProvider } from './smtp-provider.js';
+export { readSmtpConfig, type SmtpConfig, type SmtpEnv } from './smtp-config.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/notifications/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/notifications/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,KAAK,UAAU,EAAE,KAAK,OAAO,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/notifications/index.js

@@ -0,0 +1,3 @@
+export { SmtpNotificationProvider } from './smtp-provider.js';
+export { readSmtpConfig } from './smtp-config.js';
+//# sourceMappingURL=index.js.map

package/dist/notifications/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/notifications/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAiC,MAAM,kBAAkB,CAAC"}

package/dist/notifications/smtp-config.d.ts

@@ -0,0 +1,37 @@
+export interface SmtpConfig {
+    host: string;
+    port: number;
+    secure: boolean;
+    auth?: {
+        user: string;
+        pass: string;
+    };
+    from: string;
+}
+/** The env vars this provider reads. The app passes `process.env` or its framework equivalent. */
+export interface SmtpEnv {
+    SMTP_HOST?: string;
+    SMTP_PORT?: string;
+    SMTP_USER?: string;
+    SMTP_PASS?: string;
+    SMTP_FROM?: string;
+    SMTP_SECURE?: string;
+    [key: string]: string | undefined;
+}
+/**
+ * Read SMTP settings from an env bag. Taken as a parameter rather than read
+ * from `process.env` directly: under `vite dev` the framework does not mirror
+ * `.env` into `process.env`, so the app must hand over its own resolved env
+ * (`$env/dynamic/private` in SvelteKit) or overrides silently fall back to
+ * defaults.
+ *
+ * Returns null when mail is not configured — the caller treats that as "no
+ * mail", not as an error.
+ *
+ * Throws only when `SMTP_HOST` is set but `SMTP_FROM` is missing: that
+ * combination is a half-finished config, and failing loudly beats silently
+ * never sending. Every message needs an envelope sender, and guessing one
+ * produces mail that fails SPF at the recipient.
+ */
+export declare function readSmtpConfig(env: SmtpEnv): SmtpConfig | null;
+//# sourceMappingURL=smtp-config.d.ts.map

package/dist/notifications/smtp-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"smtp-config.d.ts","sourceRoot":"","sources":["../../src/notifications/smtp-config.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACtC,IAAI,EAAE,MAAM,CAAC;CACb;AAED,kGAAkG;AAClG,MAAM,WAAW,OAAO;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IAKrB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CAClC;AAOD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,GAAG,IAAI,CAsB9D"}

package/dist/notifications/smtp-config.js

@@ -0,0 +1,41 @@
+function parsePort(raw) {
+    const n = Number(raw ?? 587);
+    return Number.isInteger(n) && n > 0 && n < 65536 ? n : 587;
+}
+/**
+ * Read SMTP settings from an env bag. Taken as a parameter rather than read
+ * from `process.env` directly: under `vite dev` the framework does not mirror
+ * `.env` into `process.env`, so the app must hand over its own resolved env
+ * (`$env/dynamic/private` in SvelteKit) or overrides silently fall back to
+ * defaults.
+ *
+ * Returns null when mail is not configured — the caller treats that as "no
+ * mail", not as an error.
+ *
+ * Throws only when `SMTP_HOST` is set but `SMTP_FROM` is missing: that
+ * combination is a half-finished config, and failing loudly beats silently
+ * never sending. Every message needs an envelope sender, and guessing one
+ * produces mail that fails SPF at the recipient.
+ */
+export function readSmtpConfig(env) {
+    const host = env.SMTP_HOST?.trim();
+    if (!host)
+        return null;
+    const from = env.SMTP_FROM?.trim();
+    if (!from) {
+        throw new Error('SMTP_HOST is set but SMTP_FROM is missing — mail needs a sender address.');
+    }
+    const port = parsePort(env.SMTP_PORT);
+    const user = env.SMTP_USER?.trim();
+    const pass = env.SMTP_PASS;
+    return {
+        host,
+        port,
+        // Port 465 is implicit TLS; 587 and 25 start plaintext and upgrade via
+        // STARTTLS, which nodemailer does on its own when `secure` is false.
+        secure: env.SMTP_SECURE ? env.SMTP_SECURE === 'true' : port === 465,
+        auth: user && pass ? { user, pass } : undefined,
+        from
+    };
+}
+//# sourceMappingURL=smtp-config.js.map

package/dist/notifications/smtp-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"smtp-config.js","sourceRoot":"","sources":["../../src/notifications/smtp-config.ts"],"names":[],"mappings":"AAuBA,SAAS,SAAS,CAAC,GAAuB;IACzC,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC;IAC7B,OAAO,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;AAC5D,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,cAAc,CAAC,GAAY;IAC1C,MAAM,IAAI,GAAG,GAAG,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC;IACnC,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IAEvB,MAAM,IAAI,GAAG,GAAG,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC;IACnC,IAAI,CAAC,IAAI,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,0EAA0E,CAAC,CAAC;IAC7F,CAAC;IAED,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACtC,MAAM,IAAI,GAAG,GAAG,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC;IACnC,MAAM,IAAI,GAAG,GAAG,CAAC,SAAS,CAAC;IAE3B,OAAO;QACN,IAAI;QACJ,IAAI;QACJ,uEAAuE;QACvE,qEAAqE;QACrE,MAAM,EAAE,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,KAAK,GAAG;QACnE,IAAI,EAAE,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS;QAC/C,IAAI;KACJ,CAAC;AACH,CAAC"}

package/dist/notifications/smtp-provider.d.ts

@@ -0,0 +1,18 @@
+import { type ILogger, type INotificationProvider, type OutboundMessage, type SendResult } from '@selvajs/platform';
+import { type SmtpEnv } from './smtp-config.js';
+/**
+ * SMTP transport. Any server works — a transactional provider, an internal
+ * relay, or a mailbox with an app password.
+ *
+ * Settings are read per send rather than cached, so a restart is the only
+ * thing needed to reconfigure and a rotated password takes effect without
+ * anyone remembering there is a cache.
+ */
+export declare class SmtpNotificationProvider implements INotificationProvider {
+    private readonly env;
+    readonly name = "SMTP";
+    constructor(env: SmtpEnv);
+    send(message: OutboundMessage, log?: ILogger): Promise<SendResult>;
+    isConfigured(): boolean;
+}
+//# sourceMappingURL=smtp-provider.d.ts.map

package/dist/notifications/smtp-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"smtp-provider.d.ts","sourceRoot":"","sources":["../../src/notifications/smtp-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,KAAK,OAAO,EACZ,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAkB,KAAK,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAEhE;;;;;;;GAOG;AACH,qBAAa,wBAAyB,YAAW,qBAAqB;IAGzD,OAAO,CAAC,QAAQ,CAAC,GAAG;IAFhC,QAAQ,CAAC,IAAI,UAAU;gBAEM,GAAG,EAAE,OAAO;IAEnC,IAAI,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,GAAE,OAA0B,GAAG,OAAO,CAAC,UAAU,CAAC;IA6C1F,YAAY,IAAI,OAAO;CAOvB"}

package/dist/notifications/smtp-provider.js

@@ -0,0 +1,71 @@
+import { NoopLogger } from '@selvajs/platform';
+import { readSmtpConfig } from './smtp-config.js';
+/**
+ * SMTP transport. Any server works — a transactional provider, an internal
+ * relay, or a mailbox with an app password.
+ *
+ * Settings are read per send rather than cached, so a restart is the only
+ * thing needed to reconfigure and a rotated password takes effect without
+ * anyone remembering there is a cache.
+ */
+export class SmtpNotificationProvider {
+    env;
+    name = 'SMTP';
+    constructor(env) {
+        this.env = env;
+    }
+    async send(message, log = new NoopLogger()) {
+        let config;
+        try {
+            config = readSmtpConfig(this.env);
+        }
+        catch (err) {
+            log.error('SMTP is misconfigured', {
+                component: 'SmtpNotificationProvider',
+                error: err instanceof Error ? err.message : String(err)
+            });
+            return { status: 'failed', reason: 'misconfigured' };
+        }
+        if (!config)
+            return { status: 'not-configured' };
+        try {
+            // Lazy: an instance with no SMTP_HOST never pays to load nodemailer.
+            const { createTransport } = await import('nodemailer');
+            const transport = createTransport({
+                host: config.host,
+                port: config.port,
+                secure: config.secure,
+                auth: config.auth
+            });
+            await transport.sendMail({
+                from: config.from,
+                to: message.to,
+                subject: message.subject,
+                text: message.text,
+                html: message.html
+            });
+            return { status: 'sent' };
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            // Recipient is personal data — logged at warn only, as the minimum
+            // needed to diagnose a bounce. Never the subject or body.
+            log.warn('Failed to send mail', {
+                component: 'SmtpNotificationProvider',
+                to: message.to,
+                kind: message.kind,
+                reason
+            });
+            return { status: 'failed', reason };
+        }
+    }
+    isConfigured() {
+        try {
+            return readSmtpConfig(this.env) !== null;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=smtp-provider.js.map

package/dist/notifications/smtp-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"smtp-provider.js","sourceRoot":"","sources":["../../src/notifications/smtp-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,UAAU,EAKV,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAgB,MAAM,kBAAkB,CAAC;AAEhE;;;;;;;GAOG;AACH,MAAM,OAAO,wBAAwB;IAGP;IAFpB,IAAI,GAAG,MAAM,CAAC;IAEvB,YAA6B,GAAY;QAAZ,QAAG,GAAH,GAAG,CAAS;IAAG,CAAC;IAE7C,KAAK,CAAC,IAAI,CAAC,OAAwB,EAAE,MAAe,IAAI,UAAU,EAAE;QACnE,IAAI,MAAM,CAAC;QACX,IAAI,CAAC;YACJ,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACnC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACd,GAAG,CAAC,KAAK,CAAC,uBAAuB,EAAE;gBAClC,SAAS,EAAE,0BAA0B;gBACrC,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;aACvD,CAAC,CAAC;YACH,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;QACtD,CAAC;QACD,IAAI,CAAC,MAAM;YAAE,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;QAEjD,IAAI,CAAC;YACJ,qEAAqE;YACrE,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC;YACvD,MAAM,SAAS,GAAG,eAAe,CAAC;gBACjC,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,IAAI,EAAE,MAAM,CAAC,IAAI;aACjB,CAAC,CAAC;YAEH,MAAM,SAAS,CAAC,QAAQ,CAAC;gBACxB,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,EAAE,EAAE,OAAO,CAAC,EAAE;gBACd,OAAO,EAAE,OAAO,CAAC,OAAO;gBACxB,IAAI,EAAE,OAAO,CAAC,IAAI;gBAClB,IAAI,EAAE,OAAO,CAAC,IAAI;aAClB,CAAC,CAAC;YACH,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QAC3B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACd,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAChE,mEAAmE;YACnE,0DAA0D;YAC1D,GAAG,CAAC,IAAI,CAAC,qBAAqB,EAAE;gBAC/B,SAAS,EAAE,0BAA0B;gBACrC,EAAE,EAAE,OAAO,CAAC,EAAE;gBACd,IAAI,EAAE,OAAO,CAAC,IAAI;gBAClB,MAAM;aACN,CAAC,CAAC;YACH,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;QACrC,CAAC;IACF,CAAC;IAED,YAAY;QACX,IAAI,CAAC;YACJ,OAAO,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC;QAC1C,CAAC;QAAC,MAAM,CAAC;YACR,OAAO,KAAK,CAAC;QACd,CAAC;IACF,CAAC;CACD"}

package/dist/ops/deploymentConfig.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Reverse-proxy and body-limit configuration rules, evaluated against a plain
+ * env bag. Pure predicates — no filesystem, no network, no process.
+ *
+ * These settings are read by adapter-node, not by Selva, so getting them wrong
+ * is invisible: nothing throws, nothing logs, and the deployment serves traffic
+ * while a whole class of requests fails. `selva doctor` reports them on the
+ * host; the admin health panel runs the same rules so an operator who never
+ * opens a shell still sees them.
+ *
+ * `packages/cli/src/checks/config.js` carries a duplicate of every rule here.
+ * Duplicated because the CLI is dependency-free by design — it scaffolds the
+ * deployment that installs this runtime, so it cannot import from it. A shared
+ * fixture table (`ops/__tests__/deployment-config-fixtures.js`) is asserted by
+ * both test suites, so a rule changed on one side fails CI on the other.
+ */
+/** Neutral severity. Callers map it onto their own presentation. */
+export type ConfigVerdict = 'ok' | 'warn' | 'fail';
+export interface ConfigFinding {
+    id: string;
+    label: string;
+    verdict: ConfigVerdict;
+    summary: string;
+    /** Concrete next step. Absent when the verdict is `ok`. */
+    remediation?: string;
+}
+/** Just the vars these rules read. Values are raw strings, as they come from `.env`. */
+export interface DeploymentEnv {
+    ORIGIN?: string;
+    ADDRESS_HEADER?: string;
+    XFF_DEPTH?: string;
+    BODY_SIZE_LIMIT?: string;
+    COMPUTE_REQUEST_MAX_BYTES?: string;
+    [key: string]: string | undefined;
+}
+/**
+ * Parse a `BODY_SIZE_LIMIT` the way adapter-node does, so this agrees with the
+ * thing that actually rejects the request.
+ *
+ * The quirk is load-bearing: adapter-node reads only the LAST character as the
+ * suffix, so `60mb` parses as the digits `60m` and happens to mean 60 MB, while
+ * `60xy` silently becomes NaN. Returns bytes, or null when the value is one
+ * adapter-node can't use.
+ */
+export declare function parseBodySizeLimit(raw: string | undefined | null): number | null;
+/**
+ * BODY_SIZE_LIMIT has to clear the compute request cap, or adapter-node's global
+ * backstop rejects the upload first — with a non-JSON body the app never sees
+ * and cannot log. Unset is the dangerous case, not a neutral one: adapter-node
+ * falls back to 512 KB, so every upload 413s on a deployment that looks fine.
+ */
+export declare function checkBodySizeLimit(env: DeploymentEnv): ConfigFinding;
+/**
+ * `ADDRESS_HEADER` / `XFF_DEPTH` are read by adapter-node, not by Selva, and
+ * unset they are invisible: nothing fails, nothing logs, and the deployment
+ * looks healthy.
+ *
+ * What actually happens is that `getClientAddress()` returns the socket peer,
+ * which behind a reverse proxy is the proxy — `127.0.0.1` for every request
+ * from every user. Login rate limiting keys on that, so the whole instance
+ * shares one bucket: five failed logins from anywhere return 429 to everyone,
+ * and only a *successful* login clears a bucket, which nobody can then reach.
+ *
+ * `ORIGIN` is the proxy tell. It is only needed when the app is served under a
+ * public URL it can't derive from its own socket, so its presence means a proxy
+ * is terminating requests. Without it we say nothing: on a directly-reachable
+ * app these settings are a footgun, since `X-Forwarded-For` is client-supplied
+ * and anyone could then pick their own rate-limit bucket.
+ */
+export declare function checkClientAddress(env: DeploymentEnv): ConfigFinding;
+/** Every deployment-config rule, in report order. */
+export declare function checkDeploymentConfig(env: DeploymentEnv): ConfigFinding[];
+//# sourceMappingURL=deploymentConfig.d.ts.map

package/dist/ops/deploymentConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deploymentConfig.d.ts","sourceRoot":"","sources":["../../src/ops/deploymentConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,oEAAoE;AACpE,MAAM,MAAM,aAAa,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AAEnD,MAAM,WAAW,aAAa;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,aAAa,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wFAAwF;AACxF,MAAM,WAAW,aAAa;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,yBAAyB,CAAC,EAAE,MAAM,CAAC;IAKnC,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CAClC;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAUhF;AAOD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,aAAa,GAAG,aAAa,CA0CpE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,aAAa,GAAG,aAAa,CAwDpE;AAED,qDAAqD;AACrD,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,aAAa,GAAG,aAAa,EAAE,CAEzE"}

package/dist/ops/deploymentConfig.js

@@ -0,0 +1,154 @@
+/**
+ * Reverse-proxy and body-limit configuration rules, evaluated against a plain
+ * env bag. Pure predicates — no filesystem, no network, no process.
+ *
+ * These settings are read by adapter-node, not by Selva, so getting them wrong
+ * is invisible: nothing throws, nothing logs, and the deployment serves traffic
+ * while a whole class of requests fails. `selva doctor` reports them on the
+ * host; the admin health panel runs the same rules so an operator who never
+ * opens a shell still sees them.
+ *
+ * `packages/cli/src/checks/config.js` carries a duplicate of every rule here.
+ * Duplicated because the CLI is dependency-free by design — it scaffolds the
+ * deployment that installs this runtime, so it cannot import from it. A shared
+ * fixture table (`ops/__tests__/deployment-config-fixtures.js`) is asserted by
+ * both test suites, so a rule changed on one side fails CI on the other.
+ */
+/**
+ * Parse a `BODY_SIZE_LIMIT` the way adapter-node does, so this agrees with the
+ * thing that actually rejects the request.
+ *
+ * The quirk is load-bearing: adapter-node reads only the LAST character as the
+ * suffix, so `60mb` parses as the digits `60m` and happens to mean 60 MB, while
+ * `60xy` silently becomes NaN. Returns bytes, or null when the value is one
+ * adapter-node can't use.
+ */
+export function parseBodySizeLimit(raw) {
+    if (raw == null || raw === '')
+        return null;
+    const value = String(raw).trim();
+    if (value === '')
+        return null;
+    const units = { K: 1024, M: 1024 * 1024, G: 1024 * 1024 * 1024 };
+    const multiplier = units[value.at(-1).toUpperCase()] ?? 1;
+    const bytes = Number(multiplier !== 1 ? value.slice(0, -1) : value) * multiplier;
+    if (!Number.isFinite(bytes) || bytes <= 0)
+        return null;
+    return bytes;
+}
+/** The app's own default for COMPUTE_REQUEST_MAX_BYTES (compute/limits.ts). */
+const COMPUTE_REQUEST_DEFAULT_BYTES = 256 * 1024 * 1024;
+const asMb = (bytes) => `${Math.round(bytes / (1024 * 1024))} MB`;
+/**
+ * BODY_SIZE_LIMIT has to clear the compute request cap, or adapter-node's global
+ * backstop rejects the upload first — with a non-JSON body the app never sees
+ * and cannot log. Unset is the dangerous case, not a neutral one: adapter-node
+ * falls back to 512 KB, so every upload 413s on a deployment that looks fine.
+ */
+export function checkBodySizeLimit(env) {
+    const base = { id: 'body-size-limit', label: 'Upload size limit' };
+    const raw = env.BODY_SIZE_LIMIT;
+    const requestCap = Number(env.COMPUTE_REQUEST_MAX_BYTES) || COMPUTE_REQUEST_DEFAULT_BYTES;
+    if (raw == null || raw === '') {
+        return {
+            ...base,
+            verdict: 'fail',
+            summary: 'BODY_SIZE_LIMIT is unset — adapter-node falls back to 512 KB, so uploads over ' +
+                'that fail with an opaque 413 no app log records.',
+            remediation: `Set BODY_SIZE_LIMIT to at least ${asMb(requestCap)} (the compute request cap) and restart.`
+        };
+    }
+    const bytes = parseBodySizeLimit(raw);
+    if (bytes === null) {
+        return {
+            ...base,
+            verdict: 'fail',
+            summary: `BODY_SIZE_LIMIT="${raw}" — adapter-node cannot parse this and throws on boot.`,
+            remediation: 'Use a byte count or a single K/M/G suffix, e.g. "256M".'
+        };
+    }
+    if (bytes < requestCap) {
+        return {
+            ...base,
+            verdict: 'warn',
+            summary: `BODY_SIZE_LIMIT=${raw} (${asMb(bytes)}) is below COMPUTE_REQUEST_MAX_BYTES ` +
+                `(${asMb(requestCap)}) — the global cap rejects first, making the compute cap dead config.`,
+            remediation: `Raise BODY_SIZE_LIMIT to at least ${asMb(requestCap)} and restart.`
+        };
+    }
+    return {
+        ...base,
+        verdict: 'ok',
+        summary: `BODY_SIZE_LIMIT=${raw} clears the compute request cap.`
+    };
+}
+/**
+ * `ADDRESS_HEADER` / `XFF_DEPTH` are read by adapter-node, not by Selva, and
+ * unset they are invisible: nothing fails, nothing logs, and the deployment
+ * looks healthy.
+ *
+ * What actually happens is that `getClientAddress()` returns the socket peer,
+ * which behind a reverse proxy is the proxy — `127.0.0.1` for every request
+ * from every user. Login rate limiting keys on that, so the whole instance
+ * shares one bucket: five failed logins from anywhere return 429 to everyone,
+ * and only a *successful* login clears a bucket, which nobody can then reach.
+ *
+ * `ORIGIN` is the proxy tell. It is only needed when the app is served under a
+ * public URL it can't derive from its own socket, so its presence means a proxy
+ * is terminating requests. Without it we say nothing: on a directly-reachable
+ * app these settings are a footgun, since `X-Forwarded-For` is client-supplied
+ * and anyone could then pick their own rate-limit bucket.
+ */
+export function checkClientAddress(env) {
+    const base = { id: 'client-address', label: 'Client IP behind proxy' };
+    const header = env.ADDRESS_HEADER;
+    const depth = env.XFF_DEPTH;
+    if (!env.ORIGIN) {
+        return {
+            ...base,
+            verdict: 'ok',
+            summary: 'ADDRESS_HEADER is not needed — ORIGIN is unset, so no reverse proxy is in play.'
+        };
+    }
+    if (!header) {
+        return {
+            ...base,
+            verdict: 'fail',
+            summary: 'ADDRESS_HEADER is unset while ORIGIN is set — every request looks like it came from ' +
+                'the proxy, so all users share ONE login rate-limit bucket. Five failed logins from ' +
+                'anyone locks out the whole instance for 15 minutes.',
+            remediation: 'Set ADDRESS_HEADER=X-Forwarded-For and XFF_DEPTH=<number of proxies>, then restart. ' +
+                'To count your proxies, see docs/self-hosting/deployment/reverse-proxy.md.'
+        };
+    }
+    if (header.toLowerCase() === 'x-forwarded-for' && !depth) {
+        return {
+            ...base,
+            verdict: 'warn',
+            summary: `ADDRESS_HEADER=${header} but XFF_DEPTH is unset. X-Forwarded-For is a ` +
+                'client-appendable list, so a caller can prepend fake entries — adapter-node needs ' +
+                'the proxy count to know which entry is real.',
+            remediation: 'Set XFF_DEPTH=1 for a single reverse proxy, 2 if a CDN or load balancer sits in ' +
+                'front of it. Unsure? docs/self-hosting/deployment/reverse-proxy.md shows how to ' +
+                'read the header the app actually receives.'
+        };
+    }
+    if (depth !== undefined && !/^[1-9][0-9]*$/.test(depth)) {
+        return {
+            ...base,
+            verdict: 'fail',
+            summary: `XFF_DEPTH="${depth}" is not a positive integer.`,
+            remediation: 'It counts proxies from the outside in — use 1 for a single reverse proxy.'
+        };
+    }
+    return {
+        ...base,
+        verdict: 'ok',
+        summary: `ADDRESS_HEADER=${header}${depth ? ` (XFF_DEPTH=${depth})` : ''}.`
+    };
+}
+/** Every deployment-config rule, in report order. */
+export function checkDeploymentConfig(env) {
+    return [checkClientAddress(env), checkBodySizeLimit(env)];
+}
+//# sourceMappingURL=deploymentConfig.js.map

package/dist/ops/deploymentConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deploymentConfig.js","sourceRoot":"","sources":["../../src/ops/deploymentConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AA4BH;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAA8B;IAChE,IAAI,GAAG,IAAI,IAAI,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC3C,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACjC,IAAI,KAAK,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAE9B,MAAM,KAAK,GAA2B,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,EAAE,CAAC;IACzF,MAAM,UAAU,GAAG,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAE,CAAC,WAAW,EAAE,CAAC,IAAI,CAAC,CAAC;IAC3D,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,UAAU,CAAC;IACjF,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACvD,OAAO,KAAK,CAAC;AACd,CAAC;AAED,+EAA+E;AAC/E,MAAM,6BAA6B,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,CAAC;AAExD,MAAM,IAAI,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,KAAK,CAAC;AAE1E;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAkB;IACpD,MAAM,IAAI,GAAG,EAAE,EAAE,EAAE,iBAAiB,EAAE,KAAK,EAAE,mBAAmB,EAAE,CAAC;IACnE,MAAM,GAAG,GAAG,GAAG,CAAC,eAAe,CAAC;IAChC,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,yBAAyB,CAAC,IAAI,6BAA6B,CAAC;IAE1F,IAAI,GAAG,IAAI,IAAI,IAAI,GAAG,KAAK,EAAE,EAAE,CAAC;QAC/B,OAAO;YACN,GAAG,IAAI;YACP,OAAO,EAAE,MAAM;YACf,OAAO,EACN,gFAAgF;gBAChF,kDAAkD;YACnD,WAAW,EAAE,mCAAmC,IAAI,CAAC,UAAU,CAAC,yCAAyC;SACzG,CAAC;IACH,CAAC;IAED,MAAM,KAAK,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;IACtC,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACpB,OAAO;YACN,GAAG,IAAI;YACP,OAAO,EAAE,MAAM;YACf,OAAO,EAAE,oBAAoB,GAAG,wDAAwD;YACxF,WAAW,EAAE,yDAAyD;SACtE,CAAC;IACH,CAAC;IAED,IAAI,KAAK,GAAG,UAAU,EAAE,CAAC;QACxB,OAAO;YACN,GAAG,IAAI;YACP,OAAO,EAAE,MAAM;YACf,OAAO,EACN,mBAAmB,GAAG,KAAK,IAAI,CAAC,KAAK,CAAC,uCAAuC;gBAC7E,IAAI,IAAI,CAAC,UAAU,CAAC,uEAAuE;YAC5F,WAAW,EAAE,qCAAqC,IAAI,CAAC,UAAU,CAAC,eAAe;SACjF,CAAC;IACH,CAAC;IAED,OAAO;QACN,GAAG,IAAI;QACP,OAAO,EAAE,IAAI;QACb,OAAO,EAAE,mBAAmB,GAAG,kCAAkC;KACjE,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAkB;IACpD,MAAM,IAAI,GAAG,EAAE,EAAE,EAAE,gBAAgB,EAAE,KAAK,EAAE,wBAAwB,EAAE,CAAC;IACvE,MAAM,MAAM,GAAG,GAAG,CAAC,cAAc,CAAC;IAClC,MAAM,KAAK,GAAG,GAAG,CAAC,SAAS,CAAC;IAE5B,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC;QACjB,OAAO;YACN,GAAG,IAAI;YACP,OAAO,EAAE,IAAI;YACb,OAAO,EAAE,iFAAiF;SAC1F,CAAC;IACH,CAAC;IAED,IAAI,CAAC,MAAM,EAAE,CAAC;QACb,OAAO;YACN,GAAG,IAAI;YACP,OAAO,EAAE,MAAM;YACf,OAAO,EACN,sFAAsF;gBACtF,qFAAqF;gBACrF,qDAAqD;YACtD,WAAW,EACV,sFAAsF;gBACtF,2EAA2E;SAC5E,CAAC;IACH,CAAC;IAED,IAAI,MAAM,CAAC,WAAW,EAAE,KAAK,iBAAiB,IAAI,CAAC,KAAK,EAAE,CAAC;QAC1D,OAAO;YACN,GAAG,IAAI;YACP,OAAO,EAAE,MAAM;YACf,OAAO,EACN,kBAAkB,MAAM,gDAAgD;gBACxE,oFAAoF;gBACpF,8CAA8C;YAC/C,WAAW,EACV,kFAAkF;gBAClF,kFAAkF;gBAClF,4CAA4C;SAC7C,CAAC;IACH,CAAC;IAED,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACzD,OAAO;YACN,GAAG,IAAI;YACP,OAAO,EAAE,MAAM;YACf,OAAO,EAAE,cAAc,KAAK,8BAA8B;YAC1D,WAAW,EAAE,2EAA2E;SACxF,CAAC;IACH,CAAC;IAED,OAAO;QACN,GAAG,IAAI;QACP,OAAO,EAAE,IAAI;QACb,OAAO,EAAE,kBAAkB,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,eAAe,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG;KAC3E,CAAC;AACH,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,qBAAqB,CAAC,GAAkB;IACvD,OAAO,CAAC,kBAAkB,CAAC,GAAG,CAAC,EAAE,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC;AAC3D,CAAC"}

package/dist/ops/index.d.ts

@@ -1,2 +1,3 @@
 export { parseSemver, isNewer, compareCore, satisfiesRange, type ReleaseChannel } from './semver.js';
+export { checkClientAddress, checkBodySizeLimit, checkDeploymentConfig, parseBodySizeLimit, type ConfigFinding, type ConfigVerdict, type DeploymentEnv } from './deploymentConfig.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/ops/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ops/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACN,WAAW,EACX,OAAO,EACP,WAAW,EACX,cAAc,EACd,KAAK,cAAc,EACnB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ops/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACN,WAAW,EACX,OAAO,EACP,WAAW,EACX,cAAc,EACd,KAAK,cAAc,EACnB,MAAM,aAAa,CAAC;AAErB,OAAO,EACN,kBAAkB,EAClB,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,EAClB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,MAAM,uBAAuB,CAAC"}

package/dist/ops/index.js

@@ -1,4 +1,5 @@
-// Deployment/ops helpers — channel-aware semver comparison and engines.node
-// range checks.
+// Deployment/ops helpers — channel-aware semver comparison, engines.node range
+// checks, and the reverse-proxy/body-limit configuration rules.
 export { parseSemver, isNewer, compareCore, satisfiesRange } from './semver.js';
+export { checkClientAddress, checkBodySizeLimit, checkDeploymentConfig, parseBodySizeLimit } from './deploymentConfig.js';
 //# sourceMappingURL=index.js.map

package/dist/ops/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ops/index.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,gBAAgB;AAEhB,OAAO,EACN,WAAW,EACX,OAAO,EACP,WAAW,EACX,cAAc,EAEd,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ops/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,gEAAgE;AAEhE,OAAO,EACN,WAAW,EACX,OAAO,EACP,WAAW,EACX,cAAc,EAEd,MAAM,aAAa,CAAC;AAErB,OAAO,EACN,kBAAkB,EAClB,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,EAIlB,MAAM,uBAAuB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@selvajs/server",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Transport-agnostic server building blocks for apps built on the Selva engine (limits, rate limiting, SSRF guard, remote-definition fetch, definition service + render loader); the solve core lives in @selvajs/solve/server",
   "license": "MIT",
   "author": "VektorNode",
@@ -70,6 +70,11 @@
       "selva-source": "./src/ops/index.ts",
       "types": "./dist/ops/index.d.ts",
       "import": "./dist/ops/index.js"
+    },
+    "./notifications": {
+      "selva-source": "./src/notifications/index.ts",
+      "types": "./dist/notifications/index.d.ts",
+      "import": "./dist/notifications/index.js"
     }
   },
   "files": [
@@ -79,24 +84,30 @@
     "!**/*.spec.*"
   ],
   "dependencies": {
-    "@selvajs/platform": "^0.19.1",
     "@selvajs/compute": "^4.0.2",
+    "@selvajs/platform": "^0.20.0",
     "@selvajs/schemas": "^5.0.1"
   },
   "peerDependencies": {
     "@sentry/node": ">=8",
+    "nodemailer": ">=7",
     "pino": ">=9"
   },
   "peerDependenciesMeta": {
     "@sentry/node": {
       "optional": true
     },
+    "nodemailer": {
+      "optional": true
+    },
     "pino": {
       "optional": true
     }
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
+    "@types/nodemailer": "^8.0.1",
+    "nodemailer": "^9.0.5",
     "typescript": "~6.0.3",
     "vitest": "^4.1.10",
     "@selvajs/config": "0.0.4"