@antasphere/chassis-server 1.0.0

package/test/unit/clock-skew.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest';
+import { describeHubClockSkew, hubClockSkewMs } from '../../src/entitlements/clock-skew.js';
+
+/**
+ * The hub clock probe (PRDCT-2644): one GET of the discovery document, the
+ * `Date` header read against the local clock; null on anything unreadable,
+ * never a throw; a sentence only past the hub's five-minute forward window.
+ */
+
+const ISSUER = 'https://hub.test/';
+const NOW = Date.parse('2026-09-23T12:00:00.000Z');
+const MIN = 60_000;
+
+function answering(headers: Record<string, string>) {
+  const calls: Array<{ url: string; method: string | undefined }> = [];
+  const fetchImpl = (async (input: string | URL | Request, init?: RequestInit) => {
+    calls.push({ url: String(input), method: init?.method });
+    return new Response('{}', { status: 200, headers });
+  }) as typeof fetch;
+  return { calls, fetchImpl };
+}
+
+describe('hubClockSkewMs', () => {
+  it('a hub seven minutes behind reads as +7 minutes, and the sentence says ahead', async () => {
+    const f = answering({ date: new Date(NOW - 7 * MIN).toUTCString() });
+    const skew = await hubClockSkewMs(ISSUER, { fetchImpl: f.fetchImpl, now: () => NOW });
+    expect(skew).toBe(7 * MIN);
+    expect(f.calls).toEqual([{ url: 'https://hub.test/.well-known/openid-configuration', method: 'GET' }]);
+    const sentence = describeHubClockSkew(skew!);
+    expect(sentence).toBe(
+      "this instance's clock is 7 minutes ahead of the hub's; usage events it stamps would be refused by the hub's window"
+    );
+  });
+
+  it('a hub seven minutes ahead reads as −7 minutes, and the sentence says behind', async () => {
+    const f = answering({ date: new Date(NOW + 7 * MIN).toUTCString() });
+    const skew = await hubClockSkewMs(ISSUER, { fetchImpl: f.fetchImpl, now: () => NOW });
+    expect(skew).toBe(-7 * MIN);
+    expect(describeHubClockSkew(skew!)).toMatch(/7 minutes behind the hub's/);
+  });
+
+  it('within five minutes either way there is no sentence (the bound is inclusive)', async () => {
+    const f = answering({ date: new Date(NOW - 3 * MIN).toUTCString() });
+    const skew = await hubClockSkewMs(ISSUER, { fetchImpl: f.fetchImpl, now: () => NOW });
+    expect(skew).toBe(3 * MIN);
+    expect(describeHubClockSkew(skew!)).toBeNull();
+    expect(describeHubClockSkew(5 * MIN)).toBeNull();
+    expect(describeHubClockSkew(-5 * MIN)).toBeNull();
+    expect(describeHubClockSkew(5 * MIN + 1)).not.toBeNull();
+  });
+
+  it('no Date header reads as null', async () => {
+    const f = answering({});
+    expect(await hubClockSkewMs(ISSUER, { fetchImpl: f.fetchImpl, now: () => NOW })).toBeNull();
+  });
+
+  it('an unparseable Date header reads as null', async () => {
+    const f = answering({ date: 'not a date' });
+    expect(await hubClockSkewMs(ISSUER, { fetchImpl: f.fetchImpl, now: () => NOW })).toBeNull();
+  });
+
+  it('a fetch that throws reads as null, never a throw', async () => {
+    const fetchImpl = (async () => {
+      throw new TypeError('fetch failed');
+    }) as unknown as typeof fetch;
+    await expect(hubClockSkewMs(ISSUER, { fetchImpl, now: () => NOW })).resolves.toBeNull();
+  });
+});

package/test/unit/cross-site.test.ts

@@ -0,0 +1,166 @@
+import { describe, expect, it } from 'vitest';
+import { Hono } from 'hono';
+import { crossSiteGuard } from '@antasphere/chassis-server/middleware';
+
+/**
+ * BROW-2: nothing under /api/v1 checked Origin or Sec-Fetch metadata, so every
+ * session-authenticated business route was drivable from any page the victim
+ * had open. Better Auth's own check covers only its `/sign-in` paths.
+ */
+function app(): Hono {
+  const api = new Hono();
+  api.use('*', crossSiteGuard({ publicBaseUrl: 'https://app.example.com' }));
+  api.get('/orgs', (c) => c.json({ read: true }));
+  api.post('/orgs', (c) => c.json({ created: true }, 201));
+  api.delete('/orgs/:id', (c) => c.json({ deleted: true }));
+  api.post('/auth/oauth2/token', (c) => c.json({ token: 'x' }));
+  api.post('/auth/sign-in/email', (c) => c.json({ signed: true }));
+  const root = new Hono();
+  root.route('/api/v1', api);
+  return root;
+}
+
+const post = (headers: Record<string, string>) => app().request('/api/v1/orgs', { method: 'POST', headers });
+
+describe('crossSiteGuard', () => {
+  it('rejects a cross-site credentialed POST before the handler', async () => {
+    const res = await post({
+      'sec-fetch-site': 'cross-site',
+      origin: 'https://evil.example',
+      cookie: 'session=abc'
+    });
+    expect(res.status).toBe(403);
+    expect(await res.json()).toMatchObject({ error: { code: 'cross_site_forbidden' } });
+  });
+
+  it('rejects an untrusted Origin even when Sec-Fetch metadata is absent (older browsers)', async () => {
+    const res = await post({ origin: 'https://evil.example', cookie: 'session=abc' });
+    expect(res.status).toBe(403);
+  });
+
+  it('rejects an opaque `Origin: null` (sandboxed iframe / redirected form post)', async () => {
+    const res = await post({ origin: 'null', cookie: 'session=abc' });
+    expect(res.status).toBe(403);
+  });
+
+  it('rejects a same-site-but-different-origin POST from a sibling subdomain', async () => {
+    // Sec-Fetch-Site says `same-site`, so the cross-site arm does not fire —
+    // the Origin arm must. A host-only session cookie IS sent on these.
+    const res = await post({
+      'sec-fetch-site': 'same-site',
+      origin: 'https://marketing.example.com',
+      cookie: 'session=abc'
+    });
+    expect(res.status).toBe(403);
+  });
+
+  it('covers every unsafe method, not just POST', async () => {
+    const res = await app().request('/api/v1/orgs/1', {
+      method: 'DELETE',
+      headers: { 'sec-fetch-site': 'cross-site' }
+    });
+    expect(res.status).toBe(403);
+  });
+
+  it('allows the dashboard: same-origin POST with the app Origin', async () => {
+    const res = await app().request('https://app.example.com/api/v1/orgs', {
+      method: 'POST',
+      headers: {
+        'sec-fetch-site': 'same-origin',
+        origin: 'https://app.example.com',
+        cookie: 'session=abc'
+      }
+    });
+    expect(res.status).toBe(201);
+  });
+
+  it('allows the serving origin even when it is not PUBLIC_BASE_URL (dev proxy, previews)', async () => {
+    const res = await app().request('http://localhost:5173/api/v1/orgs', {
+      method: 'POST',
+      headers: { origin: 'http://localhost:5173', 'sec-fetch-site': 'same-origin' }
+    });
+    expect(res.status).toBe(201);
+  });
+
+  it('leaves non-browser clients alone (no Origin, no Sec-Fetch)', async () => {
+    const res = await post({ 'content-type': 'application/json' });
+    expect(res.status).toBe(201);
+  });
+
+  it('never blocks bearer-authenticated calls — those are not ambient credentials', async () => {
+    const res = await post({
+      authorization: 'Bearer pk_live_something',
+      origin: 'https://some-mcp-client.example',
+      'sec-fetch-site': 'cross-site'
+    });
+    expect(res.status).toBe(201);
+  });
+
+  it('exempts the deliberate wildcard-CORS OAuth endpoints', async () => {
+    const res = await app().request('/api/v1/auth/oauth2/token', {
+      method: 'POST',
+      headers: { origin: 'https://claude.ai', 'sec-fetch-site': 'cross-site' }
+    });
+    expect(res.status).toBe(200);
+  });
+
+  it('does NOT exempt the cookie-bearing auth endpoints', async () => {
+    const res = await app().request('/api/v1/auth/sign-in/email', {
+      method: 'POST',
+      headers: { origin: 'https://evil.example', 'sec-fetch-site': 'cross-site' }
+    });
+    expect(res.status).toBe(403);
+  });
+
+  it('leaves safe methods readable — CORS already stops the attacker seeing them', async () => {
+    const res = await app().request('/api/v1/orgs', {
+      headers: { 'sec-fetch-site': 'cross-site', origin: 'https://evil.example' }
+    });
+    expect(res.status).toBe(200);
+  });
+
+  describe('deniedOrigins — the viewer origin (PRDCT-1352)', () => {
+    const VIEWER = 'https://decks.example.net';
+    function gated(): Hono {
+      const api = new Hono();
+      api.use(
+        '*',
+        crossSiteGuard({
+          publicBaseUrl: 'https://app.example.com',
+          // Even listed as trusted, denial wins: an operator cannot re-open it by accident.
+          extraTrustedOrigins: [VIEWER],
+          deniedOrigins: [VIEWER]
+        })
+      );
+      api.post('/orgs', (c) => c.json({ created: true }, 201));
+      const root = new Hono();
+      root.route('/api/v1', api);
+      return root;
+    }
+
+    it('refuses the viewer origin even when it IS the serving origin', async () => {
+      const res = await gated().request(`${VIEWER}/api/v1/orgs`, {
+        method: 'POST',
+        headers: { origin: VIEWER, 'sec-fetch-site': 'same-origin', cookie: 'session=abc' }
+      });
+      expect(res.status).toBe(403);
+      expect(await res.json()).toMatchObject({ error: { code: 'cross_site_forbidden' } });
+    });
+
+    it('refuses the viewer origin arriving at the app origin', async () => {
+      const res = await gated().request('https://app.example.com/api/v1/orgs', {
+        method: 'POST',
+        headers: { origin: VIEWER, 'sec-fetch-site': 'cross-site', cookie: 'session=abc' }
+      });
+      expect(res.status).toBe(403);
+    });
+
+    it('still lets the app origin through', async () => {
+      const res = await gated().request('https://app.example.com/api/v1/orgs', {
+        method: 'POST',
+        headers: { origin: 'https://app.example.com', 'sec-fetch-site': 'same-origin' }
+      });
+      expect(res.status).toBe(201);
+    });
+  });
+});

package/test/unit/declared-credits.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from 'vitest';
+import { declaredCredits } from '@antasphere/chassis-contract';
+
+/** The price an action declares is what a test can compute from the declaration (PRDCT-2627). */
+describe('declaredCredits', () => {
+  it('prices a quantity from the declaration: credits per `per` units, exact', () => {
+    const MB = 1024 * 1024;
+    const upload = { creditsPerUnit: 5, unit: 'bytes', per: MB };
+    expect(declaredCredits(upload, 20 * MB)).toBe(100);
+    expect(declaredCredits(upload, 43)).toBeCloseTo(0.000205, 6);
+    expect(declaredCredits({ creditsPerUnit: 50 }, 1)).toBe(50);
+  });
+});

package/test/unit/demo-pass-rules.test.ts

@@ -0,0 +1,192 @@
+import { describe, expect, it } from 'vitest';
+import {
+  DEMO_PASS_DEFAULT_MINUTES,
+  DEMO_PASS_MAX_MINUTES,
+  DEMO_SESSION_REFUSED_AUTH_PATHS,
+  demoSessionAuthRefusal,
+  isDemoAddress,
+  isDemoSignInHost,
+  isSafeDemoPath,
+  parseDemoEmailDomains,
+  parseDemoHosts
+} from '@antasphere/chassis-server/identity';
+import { INSECURE_SETUP_ORIGINS, SECURE_SETUP_ORIGINS } from '@antasphere/chassis-server/testing';
+
+/**
+ * The demo pass's pure rules (the demo pass spec, sections 1 to 3). A pass is
+ * a sign-in-equivalent link, so every one of these is a boundary: the host
+ * the switch may be on, the addresses a pass may open, the page it lands on.
+ */
+
+const NONE: ReadonlySet<string> = new Set();
+
+describe('the lifetime constants', () => {
+  it('default to one day and stop at one week', () => {
+    expect(DEMO_PASS_DEFAULT_MINUTES).toBe(1440);
+    expect(DEMO_PASS_MAX_MINUTES).toBe(10080);
+  });
+});
+
+describe('parseDemoHosts / parseDemoEmailDomains', () => {
+  it('are empty for unset and blank input', () => {
+    expect(parseDemoHosts(undefined).size).toBe(0);
+    expect(parseDemoHosts('').size).toBe(0);
+    expect(parseDemoHosts('   ').size).toBe(0);
+    expect(parseDemoEmailDomains(undefined).size).toBe(0);
+  });
+
+  it('trim, lowercase and dedupe the entries', () => {
+    const set = parseDemoHosts(' Demo.Example.io ,staging.acme.test, demo.example.io');
+    expect([...set].sort()).toEqual(['demo.example.io', 'staging.acme.test']);
+  });
+
+  it.each([
+    ['a scheme', 'https://demo.example.io', /scheme/],
+    ['a path', 'demo.example.io/app', /path/],
+    ['a port', 'demo.example.io:8443', /port/],
+    ['a space', 'demo example.io', /space/],
+    ['a wildcard', '*.example.io', /wildcard/],
+    ['an empty label', 'demo..example.io', /empty label/],
+    ['a leading dot', '.example.io', /empty label/],
+    ['a trailing dot', 'example.io.', /empty label/],
+    ['a character no hostname carries', 'demo_host.example.io', /not a hostname/]
+  ])('refuse an entry with %s, naming the variable and the entry', (_what, entry, reason) => {
+    expect(() => parseDemoHosts(`ok.example.io,${entry}`)).toThrow(reason);
+    expect(() => parseDemoHosts(entry)).toThrow(/DEMO_SIGN_IN_HOSTS/);
+    expect(() => parseDemoEmailDomains(entry)).toThrow(/DEMO_SIGN_IN_EMAIL_DOMAINS/);
+  });
+
+  it('refuse a list of separators only rather than arm an empty one', () => {
+    expect(() => parseDemoHosts(',,')).toThrow(/at least one hostname/);
+  });
+});
+
+describe('isDemoSignInHost: loopback, or listed exactly', () => {
+  // The loopback half of the setup-origin table: every plaintext origin the
+  // setup wizard accepts is loopback by construction (the https ones are
+  // accepted there for their transport, which says nothing about the host).
+  const LOOPBACK = SECURE_SETUP_ORIGINS.filter((url) => url.startsWith('http://'));
+  const PUBLIC = [
+    ...SECURE_SETUP_ORIGINS.filter((url) => url.startsWith('https://')),
+    ...INSECURE_SETUP_ORIGINS
+  ];
+
+  it.each(LOOPBACK)('accepts %s with an empty list', (url) => {
+    expect(isDemoSignInHost(url, NONE)).toBe(true);
+  });
+
+  it.each(PUBLIC)('REFUSES %s with an empty list (look-alike hosts included)', (url) => {
+    expect(isDemoSignInHost(url, NONE)).toBe(false);
+  });
+
+  it('accepts a public host once it is listed, and only that exact host', () => {
+    const hosts = parseDemoHosts('platform.example.com');
+    expect(isDemoSignInHost('https://platform.example.com', hosts)).toBe(true);
+    expect(isDemoSignInHost('https://PLATFORM.example.com/base', hosts)).toBe(true);
+    expect(isDemoSignInHost('https://app.platform.example.com', hosts)).toBe(false);
+    expect(isDemoSignInHost('https://platform.example.com.evil.test', hosts)).toBe(false);
+  });
+
+  it('fails closed on anything it cannot parse', () => {
+    expect(isDemoSignInHost('not a url', NONE)).toBe(false);
+    expect(isDemoSignInHost('', parseDemoHosts('localhost'))).toBe(false);
+  });
+});
+
+describe('isDemoAddress: reserved example and test domains, or an operator-listed one', () => {
+  it.each([
+    'a@example.com',
+    'a@example.net',
+    'a@example.org',
+    'a@sub.example.org',
+    'a@team.test',
+    'a@x.localhost',
+    'a@shop.example',
+    'a@nowhere.invalid',
+    'A@EXAMPLE.COM',
+    'a@Team.Test'
+  ])('accepts %s', (email) => {
+    expect(isDemoAddress(email, NONE)).toBe(true);
+  });
+
+  it.each([
+    'a@notexample.com',
+    'a@example.com.evil.io',
+    'a@gmail.com',
+    'a@testing.io',
+    'a@test.io',
+    '"a@example.com"@gmail.com',
+    'a@example.com@gmail.com',
+    'a@.test',
+    'a@example..com',
+    'a@',
+    '@example.com',
+    'no-at-sign.example.com'
+  ])('refuses %s', (email) => {
+    expect(isDemoAddress(email, NONE)).toBe(false);
+  });
+
+  it('judges the part after the LAST @', () => {
+    expect(isDemoAddress('"a@gmail.com"@example.com', NONE)).toBe(true);
+  });
+
+  it('adds the operator domains and their subdomains, on a label boundary', () => {
+    const extra = parseDemoEmailDomains('demo.acme.io');
+    expect(isDemoAddress('a@demo.acme.io', extra)).toBe(true);
+    expect(isDemoAddress('a@eu.demo.acme.io', extra)).toBe(true);
+    expect(isDemoAddress('A@DEMO.ACME.IO', extra)).toBe(true);
+    expect(isDemoAddress('a@acme.io', extra)).toBe(false);
+    expect(isDemoAddress('a@xdemo.acme.io', extra)).toBe(false);
+    expect(isDemoAddress('a@demo.acme.io.evil.test.com', extra)).toBe(false);
+  });
+});
+
+describe('isSafeDemoPath: one leading slash, no fragment, no control character', () => {
+  it.each(['/', '/decks/1?x=1', '/settings/members', '/a/b?c=d&e=%2F'])('accepts %s', (path) => {
+    expect(isSafeDemoPath(path)).toBe(true);
+  });
+
+  it('accepts a path of exactly 2048 characters', () => {
+    expect(isSafeDemoPath('/' + 'a'.repeat(2047))).toBe(true);
+  });
+
+  it.each([
+    ['empty', ''],
+    ['protocol-relative', '//evil'],
+    ['backslash-relative', '/\\evil'],
+    ['relative', 'decks'],
+    ['absolute URL', 'https://evil.test/'],
+    ['a fragment', '/a#b'],
+    ['a space', '/a b'],
+    ['a control character', '/a\u0001b'],
+    ['a newline', '/a\nb'],
+    ['DEL', '/a\u007fb'],
+    ['2049 characters', '/' + 'a'.repeat(2048)]
+  ])('refuses %s', (_what, path) => {
+    expect(isSafeDemoPath(path)).toBe(false);
+  });
+});
+
+describe('demoSessionAuthRefusal: what a pass’s session may not do at the sign-in library', () => {
+  it('refuses every listed path', () => {
+    expect(DEMO_SESSION_REFUSED_AUTH_PATHS.length).toBe(27);
+    for (const path of DEMO_SESSION_REFUSED_AUTH_PATHS) {
+      expect(demoSessionAuthRefusal(path), path).toBe(true);
+    }
+    // A session's dynamic client registration stores the client under the person.
+    expect(demoSessionAuthRefusal('/oauth2/register')).toBe(true);
+  });
+
+  it('refuses them whatever the case, and with one trailing slash', () => {
+    expect(demoSessionAuthRefusal('/Change-Password')).toBe(true);
+    expect(demoSessionAuthRefusal('/OAUTH2/AUTHORIZE')).toBe(true);
+    expect(demoSessionAuthRefusal('/change-password/')).toBe(true);
+    expect(demoSessionAuthRefusal('/Two-Factor/Enable/')).toBe(true);
+  });
+
+  it('allows reading the session, signing out, signing in and redeeming', () => {
+    for (const path of ['/get-session', '/sign-out', '/sign-in/email', '/demo/redeem']) {
+      expect(demoSessionAuthRefusal(path), path).toBe(false);
+    }
+  });
+});

package/test/unit/email-driver.test.ts

@@ -0,0 +1,127 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createEmailDriver, type EmailMessage } from '@antasphere/chassis-server/email';
+import type { Logger } from '@antasphere/chassis-server/logger';
+
+const logger = { info: () => {}, warn: () => {}, error: () => {} } as unknown as Logger;
+
+/** The factory takes a Pick of Env, so the tests build exactly that shape. */
+type FactoryEnv = Parameters<typeof createEmailDriver>[0];
+const env = (over: Partial<FactoryEnv> = {}): FactoryEnv => ({ EMAIL_DRIVER: 'none', ...over }) as FactoryEnv;
+
+describe('createEmailDriver', () => {
+  it('defaults to the none driver, which never delivers', () => {
+    const driver = createEmailDriver(env(), logger);
+    expect(driver.name).toBe('none');
+    expect(driver.delivers).toBe(false);
+  });
+
+  it('builds each delivering driver when its credential and sender are present', () => {
+    const from = 'Things <noreply@example.com>';
+    expect(
+      createEmailDriver(env({ EMAIL_DRIVER: 'smtp', SMTP_URL: 'smtp://h:25', EMAIL_FROM: from }), logger).name
+    ).toBe('smtp');
+    expect(
+      createEmailDriver(env({ EMAIL_DRIVER: 'resend', RESEND_API_KEY: 're_x', EMAIL_FROM: from }), logger)
+        .name
+    ).toBe('resend');
+    const brevo = createEmailDriver(
+      env({ EMAIL_DRIVER: 'brevo', BREVO_API_KEY: 'xkeysib-x', EMAIL_FROM: from }),
+      logger
+    );
+    expect(brevo.name).toBe('brevo');
+    expect(brevo.delivers).toBe(true);
+  });
+
+  // A driver that boots without its credential would fail at the first send,
+  // which is the flow a user is waiting on; it must fail at boot instead.
+  it('refuses a delivering driver that is missing its credential or its sender', () => {
+    const from = 'Things <noreply@example.com>';
+    expect(() => createEmailDriver(env({ EMAIL_DRIVER: 'brevo', EMAIL_FROM: from }), logger)).toThrow(
+      'EMAIL_DRIVER=brevo requires BREVO_API_KEY'
+    );
+    expect(() =>
+      createEmailDriver(env({ EMAIL_DRIVER: 'brevo', BREVO_API_KEY: 'xkeysib-x' }), logger)
+    ).toThrow('EMAIL_DRIVER=brevo requires EMAIL_FROM');
+    expect(() => createEmailDriver(env({ EMAIL_DRIVER: 'resend', EMAIL_FROM: from }), logger)).toThrow(
+      'EMAIL_DRIVER=resend requires RESEND_API_KEY'
+    );
+    expect(() => createEmailDriver(env({ EMAIL_DRIVER: 'smtp', EMAIL_FROM: from }), logger)).toThrow(
+      'EMAIL_DRIVER=smtp requires SMTP_URL'
+    );
+  });
+});
+
+describe('the brevo driver on the wire', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  const send = async (
+    from: string,
+    response: Response,
+    message: EmailMessage = { to: 'her@example.com', subject: 'Subject', html: '<p>Body</p>' }
+  ) => {
+    const fetchMock = vi.fn(async () => response);
+    vi.stubGlobal('fetch', fetchMock);
+    const driver = createEmailDriver(
+      { EMAIL_DRIVER: 'brevo', BREVO_API_KEY: 'xkeysib-secret', EMAIL_FROM: from } as FactoryEnv,
+      logger
+    );
+    const result = await driver.send(message).then(
+      () => null,
+      (error: Error) => error
+    );
+    return { result, fetchMock };
+  };
+
+  it('posts the message to Brevo with the key in the api-key header', async () => {
+    const { result, fetchMock } = await send(
+      'Things <noreply@example.com>',
+      new Response('{}', { status: 201 })
+    );
+    expect(result).toBeNull();
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchMock.mock.calls[0] as unknown as [string, RequestInit];
+    expect(url).toBe('https://api.brevo.com/v3/smtp/email');
+    expect(init.method).toBe('POST');
+    expect((init.headers as Record<string, string>)['api-key']).toBe('xkeysib-secret');
+    const body = JSON.parse(init.body as string);
+    // `Name <addr>` is split into Brevo's own sender shape.
+    expect(body.sender).toEqual({ name: 'Things', email: 'noreply@example.com' });
+    expect(body.to).toEqual([{ email: 'her@example.com' }]);
+    expect(body.subject).toBe('Subject');
+    expect(body.htmlContent).toBe('<p>Body</p>');
+    // An absent text part is omitted, never sent as undefined/null.
+    expect('textContent' in body).toBe(false);
+  });
+
+  it('passes a bare sender address through and carries the text part when there is one', async () => {
+    const { fetchMock } = await send('noreply@example.com', new Response('{}', { status: 201 }), {
+      to: 'her@example.com',
+      subject: 'Subject',
+      html: '<p>Body</p>',
+      text: 'Body'
+    });
+    const body = JSON.parse((fetchMock.mock.calls[0] as unknown as [string, RequestInit])[1].body as string);
+    expect(body.sender).toEqual({ email: 'noreply@example.com' });
+    expect(body.textContent).toBe('Body');
+  });
+
+  // The response body names the reason and may echo the request, so it must not
+  // reach the thrown message a caller could relay onward.
+  it('maps a refusal to its cause without leaking the response body', async () => {
+    const leak = 'unverified sender her@example.com and xkeysib-secret';
+    const cases: [number, string][] = [
+      [401, 'brevo: authentication failed'],
+      [429, 'brevo: rate limited'],
+      [503, 'brevo: temporarily unavailable'],
+      [400, 'brevo: refused the message (400)']
+    ];
+    for (const [status, expected] of cases) {
+      const { result } = await send('noreply@example.com', new Response(leak, { status }));
+      expect(result?.message).toBe(expected);
+      expect(result?.message).not.toContain('xkeysib-secret');
+      expect(result?.message).not.toContain('her@example.com');
+    }
+  });
+});