@atlasauth/emulator-core 0.2.0 → 0.3.1

package/dist/handlers/messaging.js

@@ -1,12 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.keyStore = void 0;
 exports.installMessaging = installMessaging;
 exports.messagingHandlers = messagingHandlers;
 const crypto_util_1 = require("../crypto-util");
 const errors_1 = require("../errors");
+const messaging_callbacks_1 = require("../messaging-callbacks");
 const store_1 = require("../store");
 const support_1 = require("./support");
 const util_1 = require("./util");
+const emu4_sns_1 = require("./emu4-sns");
 /**
  * The messaging layer behind every email, SMS, WhatsApp, voice and push message the engine sends: the message ledger
  * (`GET /v1/messages`, one row per message with attempts and a delivery timeline), the suppression list (a suppressed
@@ -14,6 +17,14 @@ const util_1 = require("./util");
  * fallback providers tried when the primary fails) and per-country SMS routes. Nothing leaves the process: delivery
  * means the message reached `engine.messages`. To exercise failover, make a provider fail with
  * `POST /__emulator/messaging/faults`; to play a provider's delivery callback, `POST /__emulator/messaging/feedback`.
+ *
+ * Per-channel providers: `PUT /v1/messaging_providers/{email,sms,push}` picks the provider of a channel (WhatsApp and voice ride
+ * the SMS provider's Twilio account, as on the real API), every ledger row records the `provider` and `channel` it went through, and
+ * `POST /__emulator/messaging/require_providers` makes a channel with no provider fail instead of using the built-in sink.
+ *
+ * Provider callbacks: `POST /v1/webhooks/{provider}/{instance_id}` verifies each provider's own signature (or URL token) before
+ * it touches the ledger. `GET /__emulator/messaging/signing_keys` lists the test secrets and `POST /__emulator/messaging/sign`
+ * builds a correctly signed (or tampered, or stale) callback for a ledger message.
  */
 const CHANNELS = ['email', 'sms', 'whatsapp', 'voice', 'push'];
 const STATUSES = ['queued', 'sent', 'delivered', 'failed', 'bounced', 'complained', 'suppressed'];
@@ -25,17 +36,38 @@ const TRANSPORTS = {
     push: ['fcm', 'apns', 'onesignal'],
 };
 const RECEIVERS = [
-    { provider: 'ses', channel: 'email', verification: 'signature', events: ['delivery', 'bounce', 'complaint'], secret: 'SNS topic ARNs' },
-    { provider: 'sendgrid', channel: 'email', verification: 'signature', events: ['delivered', 'bounce', 'spamreport'], secret: 'signed event webhook public key' },
-    { provider: 'brevo', channel: 'email', verification: 'token', events: ['delivered', 'hard_bounce', 'spam'], secret: null },
-    { provider: 'mailgun', channel: 'email', verification: 'signature', events: ['delivered', 'failed', 'complained'], secret: 'HTTP webhook signing key' },
-    { provider: 'postmark', channel: 'email', verification: 'token', events: ['Delivery', 'Bounce', 'SpamComplaint'], secret: null },
-    { provider: 'resend', channel: 'email', verification: 'signature', events: ['email.delivered', 'email.bounced', 'email.complained'], secret: 'whsec_ signing secret' },
-    { provider: 'smtp2go', channel: 'email', verification: 'token', events: ['delivered', 'bounce', 'spam'], secret: null },
-    { provider: 'twilio', channel: 'sms', verification: 'signature', events: ['delivered', 'undelivered', 'failed'], secret: null },
-    { provider: 'vonage', channel: 'sms', verification: 'signature_or_token', events: ['delivered', 'failed'], secret: 'signature secret' },
-    { provider: 'messagebird', channel: 'sms', verification: 'signature', events: ['delivered', 'delivery_failed'], secret: 'signing key' },
+    { provider: 'ses', channel: 'email', verification: 'token', secret: 'Optional: comma-separated SNS topic ARNs to accept (any other topic is refused). Amazon SNS signatures are always verified.', events: 'Bounce, Complaint and Delivery notifications through an SNS topic subscribed over HTTPS.' },
+    { provider: 'brevo', channel: 'email', verification: 'token', secret: null, events: 'Transactional webhook: request, delivered, hard_bounce, soft_bounce, blocked, spam, invalid_email, unsubscribed, error. Send the token as a bearer header.' },
+    { provider: 'mailgun', channel: 'email', verification: 'signature', secret: 'Your Mailgun HTTP webhook signing key.', events: 'accepted, delivered, failed (temporary and permanent), complained, unsubscribed.' },
+    { provider: 'smtp2go', channel: 'email', verification: 'token', secret: null, events: 'processed, delivered, bounce, reject, spam, unsubscribe.' },
+    { provider: 'postmark', channel: 'email', verification: 'token', secret: null, events: 'Delivery, Bounce, SpamComplaint, SubscriptionChange. Use HTTP basic auth with the token as the password.' },
+    { provider: 'sendgrid', channel: 'email', verification: 'signature_or_token', secret: 'The public key of your SendGrid signed event webhook (base64).', events: 'processed, delivered, bounce, blocked, dropped, spamreport, unsubscribe.' },
+    { provider: 'resend', channel: 'email', verification: 'signature', secret: 'The signing secret (whsec_...) of your Resend webhook. Managed email on Resend registers its own and needs none.', events: 'email.sent, email.delivered, email.bounced, email.complained, email.failed.' },
+    { provider: 'twilio', channel: 'sms', verification: 'signature', secret: null, events: 'Message status callbacks. Verified with the auth token of your Twilio SMS provider.' },
+    { provider: 'vonage', channel: 'sms', verification: 'signature_or_token', secret: 'Your Vonage signature secret, as `sha256:<secret>` (or md5hash, md5, sha1, sha512 as the prefix).', events: 'SMS delivery receipts.' },
+    { provider: 'messagebird', channel: 'sms', verification: 'signature_or_token', secret: 'Your MessageBird request-signing key.', events: 'SMS status reports.' },
 ];
+/** Signature-only providers: with no stored secret the sign helper uses the test secret, so a callback can be built before anything is stored. */
+const SIGNED_ONLY = new Set(['mailgun', 'resend', 'twilio']);
+const GET_RECEIVERS = ['vonage', 'messagebird'];
+const EMAIL_TRANSPORTS = ['resend', 'ses', 'smtp', 'brevo', 'mailgun', 'smtp2go', 'hermetica', 'webhook'];
+const SMS_TRANSPORTS = ['twilio', 'vonage', 'messagebird', 'plivo', 'telnyx', 'sinch', 'infobip', 'clicksend', 'bandwidth', 'aws_sns', 'webhook'];
+const PUSH_TRANSPORTS = ['apns_fcm', 'expo'];
+const PROVIDER_TRANSPORTS = { email: EMAIL_TRANSPORTS, sms: SMS_TRANSPORTS, push: PUSH_TRANSPORTS };
+/** shortcut: one write-only key list for every transport and a required-key table for the common ones, where the real API validates each transport's full schema; widen when a transport's own keys matter. */
+const SECRET_KEYS = new Set(['api_key', 'api_secret', 'private_key', 'access_key', 'api_token', 'auth_token', 'secret_access_key', 'access_key_id', 'session_token', 'password', 'signing_secret', 'apns_auth_key', 'fcm_service_account', 'secret', 'token']);
+const REQUIRED_KEYS = { resend: ['api_key'], brevo: ['api_key'], mailgun: ['api_key', 'domain'], smtp2go: ['api_key'], hermetica: ['api_key'], ses: ['region', 'access_key_id', 'secret_access_key'], smtp: ['host'], webhook: ['url', 'signing_secret'], twilio: ['account_sid', 'auth_token'], vonage: ['api_key', 'api_secret'], messagebird: ['access_key'], plivo: ['auth_id', 'auth_token'], telnyx: ['api_key'], sinch: ['service_plan_id', 'api_token'], infobip: ['base_url', 'api_key'], clicksend: ['username', 'api_key'] };
+const RANK = { queued: 0, sent: 1, delivered: 2, failed: 3, bounced: 4, complained: 5, suppressed: 6, blocked: 6 };
+const EVENT_NAMES = {
+    delivered: (c) => (c === 'email' ? 'email.delivered' : 'sms.delivered'),
+    bounced: (c) => (c === 'email' ? 'email.bounced' : null),
+    complained: (c) => (c === 'email' ? 'email.complained' : null),
+    failed: (c) => (c === 'email' ? 'email.failed' : 'sms.failed'),
+    sent: () => null,
+};
+const TEST_CHANNELS = ['email', 'sms', 'push', 'whatsapp', 'voice'];
+const RAW_RECEIVER = /^\/v1\/webhooks\/[a-z0-9]+\/[^/]+\/?$/;
+const rawBodies = new WeakMap();
 const CALLING_CODES = { '1': 'US', '44': 'GB', '49': 'DE', '33': 'FR', '34': 'ES', '39': 'IT', '31': 'NL', '61': 'AU', '91': 'IN', '81': 'JP', '55': 'BR', '52': 'MX', '353': 'IE', '46': 'SE', '47': 'NO', '45': 'DK', '41': 'CH', '43': 'AT', '32': 'BE', '48': 'PL', '351': 'PT', '65': 'SG', '64': 'NZ', '27': 'ZA', '234': 'NG', '971': 'AE' };
 const E164 = /^\+[1-9]\d{6,14}$/;
 const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
@@ -46,10 +78,15 @@ const st = (0, support_1.engineState)((e) => ({
     suppressions: new store_1.Table('message_suppressions', e.clock.now, 'msup'),
     fallbacks: new store_1.Table('messaging_fallbacks', e.clock.now, 'mfb'),
     routes: new Map(),
-    secrets: new Map(),
+    providers: new store_1.Table('messaging_providers_config', e.clock.now, 'mprov'),
+    receivers: new Map(),
+    seen: new Set(),
+    testSends: new Map(),
+    requireProviders: false,
     settings: { auto_suppress: true, failover_enabled: true, ledger_retention_days: 90, updated_at: null },
     faults: [],
 }));
+exports.keyStore = (0, support_1.engineState)(() => (0, messaging_callbacks_1.testKeys)());
 const mask = (channel, to) => {
     if (channel === 'email' || to.includes('@')) {
         const [l = '', d = ''] = to.split('@');
@@ -68,20 +105,46 @@ const countryOf = (to) => {
     }
     return null;
 };
-function takeFault(s, providerId, channel) {
-    const f = s.faults.find((x) => x.provider_id === providerId && (!x.channel || x.channel === channel) && x.times > 0);
+function takeFault(s, providerId, transport, channel) {
+    const f = s.faults.find((x) => (!x.provider_id || x.provider_id === providerId) && (!x.provider || x.provider === transport) && (!x.channel || x.channel === channel) && x.times > 0);
     if (!f)
         return false;
     f.times--;
     return true;
 }
-/** Install suppression, failover and the ledger on the engine's message sink. Called once by the engine. */
+const PHONE_CHANNELS = ['whatsapp', 'voice'];
+const providerChannel = (channel) => (PHONE_CHANNELS.includes(channel) ? 'sms' : channel);
+const activeFallbacks = (s, channel) => s.fallbacks.all().filter((f) => f.channel === channel && f.status === 'active').sort((a, b) => a.position - b.position);
+/** The providers a message on `channel` is tried through, in order: the channel's own provider, then its fallbacks. WhatsApp and voice use the SMS provider's Twilio account only. */
+function slotsFor(s, channel) {
+    const base = providerChannel(channel);
+    const cfg = s.providers.find((r) => r.channel === base);
+    if (!cfg && s.requireProviders)
+        return [];
+    const all = [{ id: 'primary', transport: cfg ? cfg.transport : 'emulator' }, ...activeFallbacks(s, base).map((f) => ({ id: f.id, transport: f.transport }))];
+    return PHONE_CHANNELS.includes(channel) && cfg ? all.filter((p) => p.transport === 'twilio') : all;
+}
+/** Install suppression, failover and the ledger on the engine's message sink, and the raw-body hook of the provider callback routes. Called once by the engine. */
 function installMessaging(e) {
+    // Callback signatures cover the exact bytes, and some providers post arrays or forms: hand those routes the raw body.
+    const handle = e.handle.bind(e);
+    e.handle = async (request) => {
+        if (request.method !== 'POST' || !RAW_RECEIVER.test(new URL(request.url).pathname))
+            return handle(request);
+        const raw = await request.text();
+        const headers = new Headers(request.headers);
+        const contentType = headers.get('content-type') ?? '';
+        headers.set('content-type', 'application/json');
+        const next = new Request(request.url, { method: 'POST', headers, body: '{}' });
+        rawBodies.set(next, { raw, contentType });
+        return handle(next);
+    };
     e.messages.route = (m) => {
         const s = st(e);
         const now = e.clock.now();
         const channel = CHANNELS.includes(m.channel) ? m.channel : 'email';
         const to = normalAddress(channel, m.to);
+        let order = slotsFor(s, channel);
         const row = s.ledger.insert({
             channel,
             template: typeof m.meta?.template === 'string' ? m.meta.template : 'custom',
@@ -89,7 +152,7 @@ function installMessaging(e) {
             country: channel === 'sms' ? countryOf(to) : null,
             status: 'queued',
             status_detail: null,
-            provider: null,
+            provider: order[0]?.transport ?? null,
             provider_message_id: null,
             attempts: [],
             timeline: [{ status: 'queued', at: now }],
@@ -102,20 +165,24 @@ function installMessaging(e) {
             row.timeline.push({ status: 'suppressed', at: now, detail: hit.reason });
             return { deliver: false };
         }
-        // Primary first (or the country's route for SMS), then active fallbacks in order, when failover is on.
-        const fb = s.fallbacks.all().filter((f) => f.channel === channel && f.status === 'active').sort((a, b) => a.position - b.position);
-        let order = [{ id: 'primary', transport: 'emulator' }, ...fb.map((f) => ({ id: f.id, transport: f.transport }))];
+        // The country's route for SMS goes first, then the rest in order; with failover off only the first is tried.
         const routed = row.country ? s.routes.get(row.country)?.provider_id : undefined;
         if (routed)
             order = [...order.filter((p) => p.id === routed), ...order.filter((p) => p.id !== routed)];
         if (!s.settings.failover_enabled)
             order = order.slice(0, 1);
+        if (!order.length) {
+            const detail = `no ${channel} provider is configured`;
+            Object.assign(row, { status: 'failed', status_detail: detail, updated_at: now });
+            row.timeline.push({ status: 'failed', at: now, detail });
+            return { deliver: false };
+        }
         for (const p of order) {
-            if (takeFault(s, p.id, channel)) {
-                row.attempts.push({ provider: p.transport, provider_id: p.id, status: 'failed', error: 'injected provider failure', at: e.clock.now() });
+            if (takeFault(s, p.id, p.transport, channel)) {
+                row.attempts.push({ provider: p.transport, provider_id: p.id, channel, status: 'failed', error: 'injected provider failure', at: e.clock.now() });
                 continue;
             }
-            row.attempts.push({ provider: p.transport, provider_id: p.id, status: 'sent', at: e.clock.now() });
+            row.attempts.push({ provider: p.transport, provider_id: p.id, channel, status: 'sent', at: e.clock.now() });
             return {
                 deliver: true,
                 done: () => {
@@ -171,6 +238,155 @@ const channelParam = (v) => {
     return v;
 };
 const failoverOrder = (e, channel) => ['primary', ...st(e).fallbacks.all().filter((f) => f.channel === channel && f.status === 'active').sort((a, b) => a.position - b.position).map((f) => f.id)];
+const providerView = (r) => r
+    ? {
+        object: 'messaging_provider',
+        configured: true,
+        id: r.id,
+        channel: r.channel,
+        transport: r.transport,
+        mode: r.mode,
+        from_address: r.from_address,
+        status: r.status,
+        config: Object.fromEntries(Object.entries(r.config).filter(([k]) => !SECRET_KEYS.has(k))),
+        secrets_set: Object.fromEntries(Object.entries(r.config).filter(([k]) => SECRET_KEYS.has(k)).map(([k]) => [k, true])),
+        updated_at: r.updated_at,
+    }
+    : null;
+const receiverRow = (e, provider) => {
+    const m = st(e).receivers;
+    if (!m.has(provider))
+        m.set(provider, { secret: null, last_event_at: null, last_error: null });
+    return m.get(provider);
+};
+async function receiverView(e, r, reveal) {
+    const row = st(e).receivers.get(r.provider);
+    const secretSet = Boolean(row?.secret);
+    const usesToken = r.verification === 'token' || (r.verification === 'signature_or_token' && !secretSet);
+    const base = `${e.issuer}/v1/webhooks/${r.provider}/${e.instanceId}`;
+    const token = usesToken && reveal ? await (0, messaging_callbacks_1.receiverToken)(e.instanceId, r.provider) : undefined;
+    return {
+        object: 'message_receiver',
+        provider: r.provider,
+        channel: r.channel,
+        verification: r.verification,
+        url: token && r.provider !== 'brevo' && r.provider !== 'postmark' ? `${base}?t=${token}` : base,
+        token_required: usesToken,
+        ...(token ? { token } : {}),
+        secret_set: secretSet,
+        secret_help: r.secret,
+        events: r.events,
+        last_event_at: row?.last_event_at ?? null,
+        last_error: row?.last_error ?? null,
+    };
+}
+async function checkSecret(provider, secret) {
+    const v = secret.trim();
+    if (!v || v.length > 4096)
+        throw new errors_1.EmulatorError('VALIDATION_FAILED', 'secret must be a non-empty string of at most 4096 characters.', 'secret');
+    if (provider === 'sendgrid') {
+        try {
+            await crypto.subtle.importKey('spki', Uint8Array.from(atob(v.replace(/\s+/g, '')), (c) => c.charCodeAt(0)), { name: 'ECDSA', namedCurve: 'P-256' }, false, ['verify']);
+        }
+        catch {
+            throw new errors_1.EmulatorError('VALIDATION_FAILED', 'secret must be the base64 public key of your SendGrid signed event webhook.', 'secret');
+        }
+    }
+    if (provider === 'ses' && !v.split(',').every((t) => /^arn:aws[a-z-]*:sns:[a-z0-9-]+:\d{12}:[A-Za-z0-9_-]{1,256}$/.test(t.trim())))
+        throw new errors_1.EmulatorError('VALIDATION_FAILED', 'secret must be a comma-separated list of SNS topic ARNs.', 'secret');
+    if (provider === 'resend' && !/^whsec_/.test(v))
+        throw new errors_1.EmulatorError('VALIDATION_FAILED', 'secret must be the Resend webhook signing secret (whsec_...).', 'secret');
+    return v;
+}
+/** What a verified callback does, whichever provider sent it: moves the ledger row (a later report never moves it back), suppresses on a hard bounce or complaint, emits the delivery event once per real change. */
+function applyEvents(e, events) {
+    const s = st(e);
+    for (const ev of events) {
+        const soft = ev.status === 'bounced' && ev.bounceType === 'soft';
+        const status = soft ? 'failed' : ev.status;
+        const detail = soft ? `soft bounce${ev.detail ? `: ${ev.detail}` : ''}` : ev.detail;
+        let row;
+        for (const id of ev.messageIds) {
+            row = s.ledger.find((r) => r.provider === ev.provider && r.provider_message_id === id);
+            if (row)
+                break;
+        }
+        let changed = true;
+        if (row) {
+            const last = row.timeline[row.timeline.length - 1];
+            changed = !(last && last.status === status && last.detail === detail?.slice(0, 300));
+            if (changed)
+                row.timeline.push({ status, at: ev.at, ...(detail ? { detail: detail.slice(0, 300) } : {}) });
+            if ((RANK[status] ?? 0) >= (RANK[row.status] ?? 0))
+                Object.assign(row, { status, status_detail: detail ?? null });
+            row.updated_at = e.clock.now();
+        }
+        if (ev.suppress && ev.recipient && s.settings.auto_suppress) {
+            const address = normalAddress(ev.channel, ev.recipient);
+            if (!s.suppressions.find((x) => x.address === address && (ev.channel !== 'email' || x.channel === 'email')))
+                addSuppression(e, ev.channel, address, ev.suppress, ev.provider, ev.detail ?? null, row?.id ?? null);
+        }
+        const name = changed ? EVENT_NAMES[ev.status]?.(ev.channel) : null;
+        if (name)
+            e.webhooks.emit(name, { object: 'message_delivery', message_id: row?.id ?? ev.messageIds[0] ?? '', channel: ev.channel, recipient: ev.recipient ?? null, ...(ev.status === 'bounced' && ev.bounceType ? { bounce_type: ev.bounceType } : {}), ...(ev.status === 'failed' || ev.status === 'bounced' ? { reason: (detail ?? ev.status).slice(0, 120) } : {}), provider: ev.provider, provider_message_id: ev.messageIds[0] ?? null, ledger_id: row?.id ?? null, at: ev.at });
+    }
+}
+/** A provider callback: verified with the provider's own scheme first; anything that does not verify is a 401 that changes nothing, the same answer whether the instance exists or not. */
+async function receive(c, provider) {
+    const e = c.engine;
+    const s = st(e);
+    const refuse = (message = 'Invalid webhook signature.') => new errors_1.EmulatorError('UNAUTHENTICATED', message);
+    if (c.params.instanceId !== e.instanceId)
+        throw refuse(provider === 'brevo' ? 'Invalid webhook token.' : undefined);
+    const stash = rawBodies.get(c.request);
+    const row = receiverRow(e, provider);
+    const u = new URL(c.request.url);
+    const path = `${u.pathname}${u.search}`;
+    const twilioTokens = [s.providers.find((r) => r.channel === 'sms' && r.transport === 'twilio')?.config.auth_token, ...activeFallbacks(s, 'sms').filter((f) => f.transport === 'twilio').map((f) => f.config?.auth_token)].filter((t) => typeof t === 'string' && !!t);
+    const out = await (0, messaging_callbacks_1.verifyCallback)({
+        provider,
+        raw: stash?.raw ?? '',
+        contentType: stash?.contentType ?? c.request.headers.get('content-type') ?? '',
+        headers: c.request.headers,
+        query: Object.fromEntries(c.query),
+        urls: [`${e.issuer}${path}`, `${u.origin}${path}`, `https://${u.host}${path}`],
+        secret: row.secret,
+        token: await (0, messaging_callbacks_1.receiverToken)(e.instanceId, provider),
+        twilioTokens,
+        snsCertificate: async (url) => (0, emu4_sns_1.snsCertificateFor)(e, url, (await (0, exports.keyStore)(e).rsa()).certPem),
+        now: Math.floor(e.clock.now() / 1000),
+    });
+    if (!out.ok) {
+        if (out.malformed)
+            return { status: 400, body: { errors: [{ code: 'VALIDATION_FAILED', message: out.message ?? 'Request body is not valid.' }] } };
+        row.last_error = out.why;
+        throw refuse(out.message);
+    }
+    // A provider redelivers what it thinks was not acknowledged: an event id already applied changes nothing.
+    const key = `${provider}:${out.id}`;
+    if (!s.seen.has(key)) {
+        s.seen.add(key);
+        applyEvents(e, out.events);
+        row.last_event_at = e.clock.now();
+        row.last_error = null;
+    }
+    // The real receiver visits the SNS confirmation URL; the emulator makes no request and records it instead (GET /__emulator/messaging/sns).
+    if (out.subscribeUrl)
+        (0, emu4_sns_1.snsState)(e).confirmations.push({ subscribe_url: out.subscribeUrl, at: e.clock.now() });
+    return { body: { received: true, ...(out.confirmed ? { confirmed: true } : {}) } };
+}
+const SCHEMES = {
+    ses: 'Amazon SNS message signature (the emulator signs with its own key) plus the URL token',
+    brevo: 'bearer token',
+    mailgun: 'HMAC-SHA256 of timestamp+token in the body signature object, with the webhook signing key',
+    smtp2go: 'URL token (bearer, basic-auth password or ?t=)',
+    postmark: 'URL token (basic-auth password, bearer or ?t=)',
+    sendgrid: 'ECDSA P-256 signature over timestamp+body (X-Twilio-Email-Event-Webhook-Signature) with the stored public key; the URL token when no key is stored',
+    resend: 'Svix signature (svix-id, svix-timestamp, svix-signature) with the whsec_ secret, 5 minute tolerance',
+    twilio: 'X-Twilio-Signature: base64 HMAC-SHA1 over the URL and the sorted form fields, with the auth token of the SMS provider',
+    vonage: 'sig over the sorted parameters with the signature secret; the URL token when no secret is stored',
+    messagebird: 'MessageBird-Signature: base64 HMAC-SHA256 over timestamp, query and body hash, with the signing key; the URL token when no key is stored',
+};
 function messagingHandlers() {
     const list = (e, channel) => ({ object: 'list', data: st(e).fallbacks.all().filter((f) => f.channel === channel).sort((a, b) => a.position - b.position).map(fallbackView), has_more: false, failover_order: failoverOrder(e, channel) });
     const saveFallback = (e, channel, b, existing) => {
@@ -408,47 +624,166 @@ function messagingHandlers() {
                 return { body: { object: 'messaging_settings', ...s } };
             },
         },
-        // ── status receivers ──
+        // ── per-channel providers ──
         {
             method: 'GET',
-            pattern: '/v1/message_receivers',
+            pattern: '/v1/messaging_providers',
             scope: 'messaging:read',
-            handler: (c) => ({
-                body: {
-                    object: 'list',
-                    has_more: false,
-                    data: RECEIVERS.map((r) => ({ object: 'message_receiver', provider: r.provider, channel: r.channel, verification: r.verification, url: `${c.engine.issuer}/v1/message_receivers/${r.provider}/${c.engine.instanceId}`, token_required: r.verification === 'token', secret_set: st(c.engine).secrets.has(r.provider), secret_help: r.secret, events: r.events, last_event_at: st(c.engine).secrets.get(r.provider) ?? null, last_error: null })),
-                },
-            }),
+            handler: (c) => {
+                const view = (ch) => providerView(st(c.engine).providers.find((r) => r.channel === ch));
+                return { body: { object: 'messaging_providers', email: view('email'), sms: view('sms'), push: view('push'), managed_email: null, development_email: null } };
+            },
         },
         {
+            method: 'GET',
+            pattern: '/v1/messaging_providers/:channel',
+            scope: 'messaging:read',
+            handler: (c) => {
+                const channel = c.params.channel;
+                if (!PROVIDER_TRANSPORTS[channel])
+                    throw (0, errors_1.notFound)('Messaging channel (use email, sms or push)');
+                const row = st(c.engine).providers.find((r) => r.channel === channel);
+                return { body: row ? providerView(row) : { object: 'messaging_provider', configured: false, channel, message: `No ${channel} provider is configured. PUT /v1/messaging_providers/${channel} to add one.` } };
+            },
+        },
+        ...['email', 'sms', 'push'].map((channel) => ({
             method: 'PUT',
-            pattern: '/v1/message_receivers/:provider/secret',
+            pattern: `/v1/messaging_providers/${channel}`,
             scope: 'messaging:write',
             handler: (c) => {
-                const r = RECEIVERS.find((x) => x.provider === c.params.provider);
-                if (!r)
-                    throw (0, errors_1.notFound)(`Provider (use one of: ${RECEIVERS.map((x) => x.provider).join(', ')})`);
-                if (r.secret === null)
-                    throw new errors_1.EmulatorError('VALIDATION_FAILED', `${r.provider} needs no verification secret.`, 'secret');
-                if (typeof c.body.secret !== 'string' || !c.body.secret.trim() || c.body.secret.length > 4096)
-                    throw new errors_1.EmulatorError('VALIDATION_FAILED', 'secret must be a non-empty string of at most 4096 characters.', 'secret');
-                if (r.provider === 'resend' && !c.body.secret.startsWith('whsec_'))
-                    throw new errors_1.EmulatorError('VALIDATION_FAILED', 'secret must be the Resend webhook signing secret (whsec_...).', 'secret');
-                st(c.engine).secrets.set(r.provider, c.engine.clock.now());
-                return { body: { object: 'message_receiver', provider: r.provider, secret_set: true } };
+                const e = c.engine;
+                const s = st(e);
+                const allowed = PROVIDER_TRANSPORTS[channel];
+                const transport = c.body.transport === 'hermeticor' ? 'hermetica' : c.body.transport;
+                if (typeof transport !== 'string' || !allowed.includes(transport))
+                    throw new errors_1.EmulatorError('VALIDATION_FAILED', `transport must be one of: ${allowed.join(', ')}.`, 'transport');
+                if (c.body.mode !== undefined && (channel !== 'email' || (c.body.mode !== 'standard' && c.body.mode !== 'development')))
+                    throw new errors_1.EmulatorError('VALIDATION_FAILED', channel === 'email' ? 'mode must be "standard" or "development".' : 'mode applies to the email provider only.', 'mode');
+                if (c.body.config !== undefined && (!c.body.config || typeof c.body.config !== 'object' || Array.isArray(c.body.config)))
+                    throw new errors_1.EmulatorError('VALIDATION_FAILED', 'config must be an object of provider settings.', 'config');
+                const existing = s.providers.find((r) => r.channel === channel);
+                // A secret the body leaves out (or sends empty) keeps the stored one, when the transport is unchanged.
+                const merged = { ...(existing && existing.transport === transport ? existing.config : {}) };
+                for (const [k, v] of Object.entries((c.body.config ?? {})))
+                    if (v !== '' && v !== null && v !== undefined)
+                        merged[k] = String(v);
+                const fromAddress = typeof c.body.from_address === 'string' && c.body.from_address.trim() ? c.body.from_address.trim() : null;
+                for (const k of REQUIRED_KEYS[transport] ?? [])
+                    if (!merged[k])
+                        throw new errors_1.EmulatorError('VALIDATION_FAILED', `config.${k} is required for ${transport}.`, `config.${k}`);
+                if (transport === 'twilio' && !merged.messaging_service_sid && !merged.from && !fromAddress)
+                    throw new errors_1.EmulatorError('VALIDATION_FAILED', 'twilio needs a sender: set from_address (or config.from) or config.messaging_service_sid.', 'config.messaging_service_sid');
+                if (transport === 'apns_fcm' && !merged.apns_auth_key && !merged.fcm_service_account)
+                    throw new errors_1.EmulatorError('VALIDATION_FAILED', 'apns_fcm needs config.apns_auth_key (with key id, team id and topic) or config.fcm_service_account (with project id).', 'config.apns_auth_key');
+                const mode = channel === 'email' ? (c.body.mode ?? (existing && existing.transport === transport ? existing.mode : 'standard')) : 'standard';
+                const fields = { channel, transport, from_address: fromAddress, config: merged, mode, status: 'active', updated_at: e.clock.now() };
+                return { body: providerView(existing ? Object.assign(existing, fields) : s.providers.insert(fields)) };
             },
-        },
+        })),
         {
             method: 'DELETE',
-            pattern: '/v1/message_receivers/:provider/secret',
+            pattern: '/v1/messaging_providers/:channel',
             scope: 'messaging:write',
             handler: (c) => {
-                if (!st(c.engine).secrets.delete(c.params.provider ?? ''))
-                    throw (0, errors_1.notFound)('Verification secret for that provider');
-                return { body: { object: 'message_receiver', provider: c.params.provider, deleted: true } };
+                const channel = c.params.channel;
+                if (!PROVIDER_TRANSPORTS[channel])
+                    throw new errors_1.EmulatorError('VALIDATION_FAILED', 'channel must be email, sms or push.', 'channel');
+                const row = st(c.engine).providers.find((r) => r.channel === channel);
+                if (!row)
+                    throw (0, errors_1.notFound)('A provider for that channel');
+                st(c.engine).providers.delete(row.id);
+                return { body: { object: 'messaging_provider', channel, deleted: true } };
             },
         },
+        {
+            method: 'POST',
+            pattern: '/v1/messaging_providers/:channel/test',
+            scope: 'messaging:write',
+            handler: (c) => {
+                const e = c.engine;
+                const s = st(e);
+                const channel = c.params.channel;
+                if (!TEST_CHANNELS.includes(channel))
+                    throw new errors_1.EmulatorError('VALIDATION_FAILED', 'channel must be email, sms, push, whatsapp or voice.', 'channel');
+                const to = typeof c.body.to === 'string' ? c.body.to.trim() : '';
+                if (!to)
+                    throw new errors_1.EmulatorError('VALIDATION_FAILED', 'A destination is required.', 'to');
+                // Throttled per key, like the real route: one test every 15 seconds, ten an hour.
+                const now = e.clock.now();
+                const hits = (s.testSends.get(c.key?.key ?? '') ?? []).filter((t) => now - t < 3_600_000);
+                if (hits.some((t) => now - t < 15_000))
+                    throw new errors_1.EmulatorError('RATE_LIMITED', 'Wait a moment before sending another test message.');
+                if (hits.length >= 10)
+                    throw new errors_1.EmulatorError('RATE_LIMITED', 'You have sent a lot of test messages in the last hour. Try again shortly.');
+                if (channel === 'push' ? to.length > 4096 || /\s/.test(to) : channel === 'email' ? !EMAIL.test(to) : !E164.test(to))
+                    throw new errors_1.EmulatorError('VALIDATION_FAILED', channel === 'push' ? 'Paste the device token to send to.' : channel === 'email' ? 'Enter a valid email address.' : 'Enter a phone number in E.164 form, e.g. +15550001111.', 'to');
+                // A test proves YOUR provider: with none configured for the channel it refuses, whatever the require_providers switch says.
+                const base = providerChannel(channel);
+                const cfg = s.providers.find((r) => r.channel === base);
+                if (!cfg || (PHONE_CHANNELS.includes(channel) && !slotsFor(s, channel).length))
+                    throw new errors_1.EmulatorError('VALIDATION_FAILED', `No ${channel} provider is configured for this instance. Add one before sending a test.`);
+                s.testSends.set(c.key?.key ?? '', [...hits, now]);
+                const address = normalAddress(channel, to);
+                e.messages.send({ channel, to: address, subject: channel === 'email' ? 'Atlas provider test' : undefined, body: 'This is a test message from Atlas. No action is needed.', meta: { template: 'provider_test' } });
+                const row = s.ledger.find((r) => r.template === 'provider_test' && r.channel === channel && r.recipient === address);
+                const shown = channel === 'push' ? `${to.slice(0, 6)}...${to.slice(-4)}` : to;
+                if (row.status === 'suppressed')
+                    throw new errors_1.EmulatorError('CONFLICT', 'That recipient is on the suppression list.');
+                if (row.status === 'failed')
+                    return { status: 502, body: { errors: [{ code: 'INTERNAL_ERROR', message: 'The provider rejected the test message.', meta: { ok: false, accepted: false, failure: 'provider_unreachable', provider: row.provider, provider_message_id: null, provider_status: null, provider_reason: row.status_detail } }] } };
+                return { body: { object: 'messaging_test', channel, sent_to: shown, ok: true, accepted: true, provider: row.provider, provider_message_id: row.provider_message_id } };
+            },
+        },
+        // ── status receivers: where each provider reports delivery ──
+        {
+            method: 'GET',
+            pattern: '/v1/message_receivers',
+            scope: 'messaging:read',
+            handler: async (c) => {
+                const k = c.key?.scopes;
+                const reveal = !k || k.includes('*') || k.includes('messaging:write');
+                return { body: { object: 'list', has_more: false, data: await Promise.all(RECEIVERS.map((r) => receiverView(c.engine, r, reveal))) } };
+            },
+        },
+        ...['/v1/message_receivers/:provider', '/v1/message_receivers/:provider/secret'].flatMap((pattern) => [
+            {
+                method: 'PUT',
+                pattern,
+                scope: 'messaging:write',
+                handler: async (c) => {
+                    const r = RECEIVERS.find((x) => x.provider === c.params.provider);
+                    if (!r)
+                        throw (0, errors_1.notFound)(`Provider (use one of: ${RECEIVERS.map((x) => x.provider).join(', ')})`);
+                    if (r.secret === null)
+                        throw new errors_1.EmulatorError('VALIDATION_FAILED', `${r.provider} needs no verification secret.`, 'secret');
+                    if (typeof c.body.secret !== 'string')
+                        throw new errors_1.EmulatorError('VALIDATION_FAILED', 'secret must be a string.', 'secret');
+                    const secret = await checkSecret(r.provider, c.body.secret);
+                    const row = receiverRow(c.engine, r.provider);
+                    row.secret = secret;
+                    return { body: await receiverView(c.engine, r, true) };
+                },
+            },
+            {
+                method: 'DELETE',
+                pattern,
+                scope: 'messaging:write',
+                handler: (c) => {
+                    const row = st(c.engine).receivers.get(c.params.provider ?? '');
+                    if (!row?.secret)
+                        throw (0, errors_1.notFound)('Verification secret for that provider');
+                    row.secret = null;
+                    return { body: { object: 'message_receiver', provider: c.params.provider, deleted: true } };
+                },
+            },
+        ]),
+        // ── provider callbacks: public, and refused unless the provider's own signature (or URL token) verifies ──
+        ...RECEIVERS.flatMap((r) => ['POST', ...(GET_RECEIVERS.includes(r.provider) ? ['GET'] : [])].map((method) => ({
+            method,
+            pattern: `/v1/webhooks/${r.provider}/:instanceId`,
+            public: true,
+            handler: (c) => receive(c, r.provider),
+        }))),
         // ── emulator controls: make a provider fail, play a delivery callback ──
         {
             method: 'POST',
@@ -456,7 +791,13 @@ function messagingHandlers() {
             public: true,
             handler: (c) => {
                 const times = (0, support_1.intIn)(c.body.times, 'times', 1, 1000, 1);
-                st(c.engine).faults.push({ provider_id: String(c.body.provider_id ?? 'primary'), channel: typeof c.body.channel === 'string' ? c.body.channel : undefined, times });
+                if (c.body.channel !== undefined && !CHANNELS.includes(c.body.channel))
+                    throw new errors_1.EmulatorError('VALIDATION_FAILED', `channel must be one of: ${CHANNELS.join(', ')}.`, 'channel');
+                if (c.body.provider !== undefined && typeof c.body.provider !== 'string')
+                    throw new errors_1.EmulatorError('VALIDATION_FAILED', 'provider must be a transport name such as resend or twilio.', 'provider');
+                // Name a slot (provider_id: primary or a fallback id), a transport (provider: resend, twilio ...), a channel, or any mix; naming neither slot nor transport means the primary.
+                const slot = c.body.provider_id !== undefined ? String(c.body.provider_id) : c.body.provider === undefined ? 'primary' : undefined;
+                st(c.engine).faults.push({ provider_id: slot, provider: c.body.provider, channel: c.body.channel, times });
                 return { status: 201, body: { ok: true } };
             },
         },
@@ -481,6 +822,72 @@ function messagingHandlers() {
                 return { body: { ok: true, status } };
             },
         },
+        {
+            method: 'POST',
+            pattern: '/__emulator/messaging/require_providers',
+            public: true,
+            handler: (c) => {
+                if (typeof c.body.enabled !== 'boolean')
+                    throw new errors_1.EmulatorError('VALIDATION_FAILED', 'enabled must be true or false.', 'enabled');
+                st(c.engine).requireProviders = c.body.enabled;
+                return { body: { ok: true, require_providers: c.body.enabled } };
+            },
+        },
+        {
+            method: 'GET',
+            pattern: '/__emulator/messaging/signing_keys',
+            public: true,
+            handler: async (c) => {
+                const e = c.engine;
+                const keys = (0, exports.keyStore)(e);
+                const data = await Promise.all(RECEIVERS.map(async (r) => ({
+                    object: 'messaging_signing_key',
+                    provider: r.provider,
+                    channel: r.channel,
+                    verification: r.verification,
+                    scheme: SCHEMES[r.provider],
+                    // What to store with PUT /v1/message_receivers/{provider} (SendGrid: the public key; Twilio: put it on the SMS provider as config.auth_token).
+                    secret: r.provider === 'sendgrid' ? (await keys.ec()).publicB64 : r.secret === null && r.provider !== 'twilio' ? null : r.provider === 'ses' ? null : await (0, messaging_callbacks_1.testSecret)(e.instanceId, r.provider),
+                    token: r.verification === 'signature' ? null : await (0, messaging_callbacks_1.receiverToken)(e.instanceId, r.provider),
+                    ...(r.provider === 'ses' ? { signing_cert_url: messaging_callbacks_1.SNS_CERT_URL, public_key: (await keys.rsa()).publicB64, certificate_pem: (await keys.rsa()).certPem } : {}),
+                    url: `${e.issuer}/v1/webhooks/${r.provider}/${e.instanceId}`,
+                })));
+                return { body: { object: 'list', data, has_more: false } };
+            },
+        },
+        {
+            method: 'POST',
+            pattern: '/__emulator/messaging/sign',
+            public: true,
+            handler: async (c) => {
+                const e = c.engine;
+                const s = st(e);
+                const provider = (0, support_1.oneOf)(c.body, 'provider', RECEIVERS.map((r) => r.provider));
+                const event = (0, support_1.oneOf)(c.body, 'event', ['sent', 'delivered', 'bounced', 'complained', 'failed'], 'delivered');
+                const bounce = (0, support_1.oneOf)(c.body, 'bounce', ['hard', 'soft'], 'hard');
+                const tamper = c.body.tamper === undefined ? undefined : (0, support_1.oneOf)(c.body, 'tamper', ['signature', 'stale']);
+                const row = c.body.message_id === undefined ? undefined : s.ledger.get(String(c.body.message_id));
+                if (c.body.message_id !== undefined && !row)
+                    throw (0, errors_1.notFound)('Message');
+                const messageId = typeof c.body.provider_message_id === 'string' && c.body.provider_message_id ? c.body.provider_message_id : row?.provider_message_id;
+                const recipient = typeof c.body.recipient === 'string' && c.body.recipient ? c.body.recipient : row?.recipient;
+                if (!messageId || !recipient)
+                    throw new errors_1.EmulatorError('VALIDATION_FAILED', 'Send message_id of a delivered message, or provider_message_id and recipient.', 'message_id');
+                const stored = s.receivers.get(provider)?.secret ?? null;
+                const twilioToken = s.providers.find((r) => r.channel === 'sms' && r.transport === 'twilio')?.config.auth_token;
+                const secret = provider === 'twilio' ? (twilioToken ?? (await (0, messaging_callbacks_1.testSecret)(e.instanceId, provider))) : (stored ?? (SIGNED_ONLY.has(provider) ? await (0, messaging_callbacks_1.testSecret)(e.instanceId, provider) : null));
+                const url = `${e.issuer}/v1/webhooks/${provider}/${e.instanceId}`;
+                let prepared;
+                try {
+                    prepared = await (0, messaging_callbacks_1.prepareCallback)({ provider, event, bounce, messageId, recipient, detail: typeof c.body.detail === 'string' ? c.body.detail : undefined, secret, token: await (0, messaging_callbacks_1.receiverToken)(e.instanceId, provider), url, now: Math.floor(e.clock.now() / 1000) - (tamper === 'stale' ? 3600 : 0), salt: tamper === 'signature' ? 'tampered' : '', topic: stored?.split(',')[0]?.trim() || 'arn:aws:sns:us-east-1:123456789012:atlas-emulator', keys: (0, exports.keyStore)(e) });
+                }
+                catch {
+                    throw new errors_1.EmulatorError('VALIDATION_FAILED', `The stored ${provider} secret cannot sign a callback. Store the secret from GET /__emulator/messaging/signing_keys.`, 'provider');
+                }
+                const query = new URLSearchParams(prepared.query).toString();
+                return { body: { object: 'messaging_callback', provider, method: 'POST', url: query ? `${url}?${query}` : url, headers: { 'content-type': prepared.content_type, ...prepared.headers }, body: prepared.body, signed_with: secret === null && provider !== 'ses' ? 'url token' : 'signature' } };
+            },
+        },
     ];
 }
 //# sourceMappingURL=messaging.js.map