verify-phone-sms 0.9.129 → 0.9.130

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verify-phone-sms",
-  "version": "0.9.129",
+  "version": "0.9.130",
   "description": "SMS Phone Verification API using AWS SNS HTTP API with Hono server on Cloudflare Workers",
   "main": "src/verify-phone.ts",
   "type": "module",

package/test/identity.test.ts

@@ -0,0 +1,281 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import app from '../src/identity-verification-server';
+
+/**
+ * The identity service fans out to three TrestleIQ endpoints (phone, person,
+ * location) and scores what comes back. `fetch` is stubbed per endpoint, so
+ * each test describes a world — "valid mobile, exact name match, active
+ * address" — and asserts the score, questions and recommendations that follow.
+ */
+type Json = Record<string, unknown>;
+type World = { phone?: Json | number; person?: Json | number; location?: Json | number };
+
+const BODY = {
+  phone_number: '2069735100',
+  legal_name: 'John Smith',
+  current_address: {
+    street_line_1: '123 Main St',
+    city: 'Seattle',
+    state_code: 'WA',
+    postal_code: '98101',
+  },
+};
+
+let fetchMock: ReturnType<typeof vi.fn>;
+let envKey: string | undefined;
+
+function world(w: World) {
+  fetchMock.mockImplementation(async (input: string) => {
+    const path = new URL(input).pathname;
+    const pick = path.endsWith('/phone') ? w.phone : path.endsWith('/person') ? w.person : w.location;
+    if (typeof pick === 'number') return new Response('err', { status: pick, statusText: 'Boom' });
+    return new Response(JSON.stringify(pick ?? {}), { status: 200 });
+  });
+}
+
+const verify = (body: unknown = BODY) =>
+  app.request('/verify-identity', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+
+beforeEach(() => {
+  fetchMock = vi.fn();
+  vi.stubGlobal('fetch', fetchMock);
+  envKey = process.env.TRESTLE_API_KEY;
+  process.env.TRESTLE_API_KEY = 'trestle-key';
+  vi.spyOn(console, 'error').mockImplementation(() => {});
+  vi.spyOn(console, 'log').mockImplementation(() => {});
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+  if (envKey === undefined) delete process.env.TRESTLE_API_KEY;
+  else process.env.TRESTLE_API_KEY = envKey;
+});
+
+const GOOD_PHONE = {
+  is_valid: true,
+  line_type: 'Mobile',
+  is_commercial: false,
+  owners: [
+    {
+      name: 'John Smith',
+      addresses: [
+        { street_line_1: '1 Old Rd', city: 'Tacoma', state_code: 'WA' },
+        { street_line_1: '', city: 'x', state_code: 'WA' },
+      ],
+      phones: [{ phone_number: '2065550001' }, { phone_number: '2065550002' }, {}],
+    },
+    { name: 'Johnny Smythe' },
+  ],
+};
+const GOOD_PERSON = {
+  person: [
+    {
+      name: 'John Smith',
+      addresses: [{ street_line_1: '9 Elm St', city: 'Everett', state_code: 'WA' }],
+      phones: [{ phone_number: '2065550003' }],
+    },
+  ],
+};
+const GOOD_LOCATION = {
+  is_valid: true,
+  is_active: true,
+  is_commercial: false,
+  current_residents: [{ name: 'Jane Smith' }, { name: 'John Smith' }, {}],
+};
+
+describe('POST /verify-identity', () => {
+  it('scores a fully corroborated identity at 100 with a high-confidence note', async () => {
+    world({ phone: GOOD_PHONE, person: GOOD_PERSON, location: GOOD_LOCATION });
+    const res = await verify();
+    expect(res.status).toBe(200);
+    const json: any = await res.json();
+
+    expect(json.verification_score).toBe(100);
+    expect(json.name_match_found).toBe(true);
+    expect(json.phone_validated).toBe(true);
+    expect(json.address_validated).toBe(true);
+    expect(json.recommendations).toEqual(['High confidence verification - proceed with confidence']);
+  });
+
+  it('queries all three TrestleIQ endpoints with the API key and hints', async () => {
+    world({});
+    await verify({ ...BODY, current_address: { ...BODY.current_address, street_line_2: 'Apt 4' } });
+
+    const urls = fetchMock.mock.calls.map((c) => new URL(c[0] as string));
+    expect(urls.map((u) => u.pathname).sort()).toEqual(['/3.1/location', '/3.1/person', '/3.2/phone']);
+    const phone = urls.find((u) => u.pathname === '/3.2/phone')!;
+    expect(phone.searchParams.get('phone')).toBe('2069735100');
+    expect(phone.searchParams.get('phone.country_hint')).toBe('US');
+    expect(phone.searchParams.get('phone.name_hint')).toBe('John Smith');
+    expect(phone.searchParams.get('phone.postal_code_hint')).toBe('98101');
+    const loc = urls.find((u) => u.pathname === '/3.1/location')!;
+    expect(loc.searchParams.get('street_line_2')).toBe('Apt 4');
+    expect(loc.searchParams.get('country_code')).toBe('US');
+    expect(fetchMock.mock.calls[0][1].headers['x-api-key']).toBe('trestle-key');
+  });
+
+  it('builds address, phone and name questions from the history', async () => {
+    world({ phone: GOOD_PHONE, person: GOOD_PERSON, location: GOOD_LOCATION });
+    const json: any = await (await verify()).json();
+
+    expect(json.historical_data.previous_addresses).toEqual(
+      expect.arrayContaining(['1 Old Rd, Tacoma, WA', '9 Elm St, Everett, WA']),
+    );
+    expect(json.historical_data.previous_phones).toEqual(
+      expect.arrayContaining(['2065550001', '2065550002', '2065550003']),
+    );
+    expect(json.historical_data.associated_names).toEqual(
+      expect.arrayContaining(['John Smith', 'Johnny Smythe', 'Jane Smith']),
+    );
+
+    const byType = Object.fromEntries(json.questions.map((q: any) => [q.type, q]));
+    expect(Object.keys(byType).sort()).toEqual(['address_history', 'name_verification', 'phone_history']);
+    expect(byType.address_history.options).toHaveLength(4); // 2 real + 2 fake
+    expect(byType.phone_history.options).toContain('None of the above');
+    expect(byType.name_verification.options).toContain('Johnny Smythe');
+    expect(byType.name_verification.options).not.toContain('John Smith');
+    expect(byType.address_history.id).toMatch(/^addr_\d+$/);
+  });
+
+  it('gives a partial-name match 20 points', async () => {
+    world({
+      phone: { is_valid: false },
+      person: { person: [{ name: 'John Doe' }] },
+      location: { is_valid: false },
+    });
+    const json: any = await (await verify()).json();
+    expect(json.verification_score).toBe(20);
+    expect(json.name_match_found).toBe(false);
+  });
+
+  it('low scores ask for ID documents and flag invalid phone/address', async () => {
+    world({ phone: { is_valid: false }, person: {}, location: { is_valid: false } });
+    const json: any = await (await verify()).json();
+    expect(json.verification_score).toBe(0);
+    expect(json.recommendations).toEqual([
+      'Consider requesting additional identification documents',
+      'Verify identity through alternative methods (government ID, utility bills)',
+      'Request alternative contact phone number',
+      'Verify current address with utility bill or bank statement',
+    ]);
+    expect(json.questions).toEqual([]);
+  });
+
+  it('mid scores ask for more questions or standard processing', async () => {
+    // valid phone (15) + Landline (10) + commercial (0) + partial name (20) = 45
+    world({
+      phone: { is_valid: true, line_type: 'Landline', is_commercial: true, owners: [{ name: 'John Doe' }] },
+      location: { is_valid: true, is_active: false, is_commercial: true },
+    });
+    let json: any = await (await verify()).json();
+    // + address valid (15) = 60
+    expect(json.verification_score).toBe(60);
+    expect(json.recommendations).toEqual(['Proceed with standard verification process']);
+
+    world({ phone: { is_valid: true, owners: [{ name: 'John Doe' }] }, location: {} });
+    json = await (await verify()).json();
+    // valid (15) + not commercial (5) + partial (20) = 40
+    expect(json.verification_score).toBe(40);
+    expect(json.recommendations).toEqual([
+      'Request additional verification questions',
+      'Consider manual review of provided information',
+      'Verify current address with utility bill or bank statement',
+    ]);
+  });
+
+  it('flags VOIP numbers', async () => {
+    world({ phone: { is_valid: true, line_type: 'NonFixedVOIP' } });
+    const json: any = await (await verify()).json();
+    expect(json.recommendations).toContain('VOIP number detected - consider additional verification');
+  });
+
+  it('tolerates individual upstream failures', async () => {
+    world({ phone: 500, person: GOOD_PERSON, location: 403 });
+    const res = await verify();
+    expect(res.status).toBe(200);
+    const json: any = await res.json();
+    expect(json.name_match_found).toBe(true);
+    expect(json.phone_validated).toBe(false);
+    expect(json.address_validated).toBe(false);
+  });
+
+  it('rejects an invalid body with a 400', async () => {
+    const res = await verify({ phone_number: '123', legal_name: '' });
+    expect(res.status).toBe(400);
+  });
+
+  it('returns a 500 with the reason when the API key is not configured', async () => {
+    delete process.env.TRESTLE_API_KEY;
+    const res = await verify();
+    expect(res.status).toBe(500);
+    expect(await res.json()).toEqual({
+      error: 'Failed to verify identity',
+      message: 'TRESTLE_API_KEY environment variable is required',
+    });
+  });
+
+  it('caps history lists (10 addresses, 5 phones, 10 names)', async () => {
+    const owners = [
+      {
+        name: 'A',
+        addresses: Array.from({ length: 15 }, (_, i) => ({ street_line_1: `${i} St`, city: 'C', state_code: 'WA' })),
+        phones: Array.from({ length: 9 }, (_, i) => ({ phone_number: `20655500${i}0` })),
+      },
+      ...Array.from({ length: 14 }, (_, i) => ({ name: `N${i}` })),
+    ];
+    world({ phone: { owners } });
+    const json: any = await (await verify()).json();
+    expect(json.historical_data.previous_addresses).toHaveLength(10);
+    expect(json.historical_data.previous_phones).toHaveLength(5);
+    expect(json.historical_data.associated_names).toHaveLength(10);
+  });
+});
+
+describe('other routes', () => {
+  it('GET /health', async () => {
+    const res = await app.request('/health');
+    const json: any = await res.json();
+    expect(json.status).toBe('healthy');
+    expect(new Date(json.timestamp).getTime()).not.toBeNaN();
+  });
+
+  it('GET /doc serves the OpenAPI document', async () => {
+    const json: any = await (await app.request('/doc')).json();
+    expect(json.openapi).toBe('3.0.0');
+    expect(json.info.title).toBe('Identity Verification API');
+    expect(json.paths['/verify-identity'].post.summary).toBe('Verify person identity');
+  });
+
+  it('GET /swagger serves the Swagger UI page', async () => {
+    const res = await app.request('/swagger');
+    expect(res.headers.get('content-type')).toContain('text/html');
+    expect(await res.text()).toContain("url: '/doc'");
+  });
+
+  it('GET /demo runs a sample verification', async () => {
+    world({ phone: GOOD_PHONE, person: GOOD_PERSON, location: GOOD_LOCATION });
+    const json: any = await (await app.request('/demo')).json();
+    expect(json.demo_request.legal_name).toBe('John Smith');
+    expect(json.demo_response.verification_score).toBe(100);
+    expect(json.note).toContain('demo');
+  });
+
+  it('GET /demo explains how to fix a missing key', async () => {
+    delete process.env.TRESTLE_API_KEY;
+    const json: any = await (await app.request('/demo')).json();
+    expect(json.error).toContain('check your TRESTLE_API_KEY');
+  });
+
+  it('answers CORS preflight', async () => {
+    const res = await app.request('/verify-identity', {
+      method: 'OPTIONS',
+      headers: { origin: 'https://x.example', 'access-control-request-method': 'POST' },
+    });
+    expect(res.headers.get('access-control-allow-origin')).toBe('*');
+  });
+});

package/test/sns.test.ts

@@ -0,0 +1,150 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import snsDefault, { SNSClient, createClient, sendSMS } from '../src/sns';
+
+const ok = (xml: string) => new Response(xml, { status: 200 });
+
+let fetchMock: ReturnType<typeof vi.fn>;
+
+beforeEach(() => {
+  fetchMock = vi.fn();
+  vi.stubGlobal('fetch', fetchMock);
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe('SNSClient', () => {
+  const client = () => new SNSClient({ accessKeyId: 'AKIA', secretAccessKey: 'secret', region: 'eu-west-1' });
+
+  it('defaults the region and derives the endpoint from it', () => {
+    expect(new SNSClient().region).toBe('us-east-1');
+    expect(new SNSClient().endpoint).toBe('https://sns.us-east-1.amazonaws.com');
+    expect(client().endpoint).toBe('https://sns.eu-west-1.amazonaws.com');
+  });
+
+  it('converts between strings, bytes and hex', () => {
+    const c = client();
+    expect(Array.from(c.stringToUint8Array('hi'))).toEqual([104, 105]);
+    expect(c.arrayBufferToHex(new Uint8Array([0, 15, 255]))).toBe('000fff');
+    expect(c.arrayBufferToHex(new Uint8Array([1, 2]).buffer)).toBe('0102');
+  });
+
+  it('signs a request with SigV4 headers', async () => {
+    const headers = await client().sign('GET', 'https://sns.eu-west-1.amazonaws.com/?Action=Publish', {}, '');
+    expect(headers.host).toBe('sns.eu-west-1.amazonaws.com');
+    expect(headers['x-amz-date']).toMatch(/^\d{8}T\d{6}Z$/);
+    // SHA-256 of the empty payload.
+    expect(headers['x-amz-content-sha256']).toBe(
+      'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
+    );
+    expect(headers.authorization).toMatch(
+      /^AWS4-HMAC-SHA256 Credential=AKIA\/\d{8}\/eu-west-1\/sns\/aws4_request, SignedHeaders=[a-z0-9;-]+, Signature=[0-9a-f]{64}$/,
+    );
+  });
+
+  it('produces a different signature for a different secret', async () => {
+    const a = await client().sign('GET', 'https://x/?a=1', { 'content-type': 't' }, '');
+    const b = await new SNSClient({ accessKeyId: 'AKIA', secretAccessKey: 'other', region: 'eu-west-1' }).sign(
+      'GET', 'https://x/?a=1', { 'content-type': 't' }, '',
+    );
+    expect(a.authorization).not.toBe(b.authorization);
+  });
+
+  describe('parseXMLResponse', () => {
+    const c = client();
+    it('extracts a message id, topic ARN or subscription ARN', () => {
+      expect(c.parseXMLResponse('<MessageId>m-1</MessageId>')).toEqual({ MessageId: 'm-1' });
+      expect(c.parseXMLResponse('<TopicArn>arn:t</TopicArn>')).toEqual({ TopicArn: 'arn:t' });
+      expect(c.parseXMLResponse('<SubscriptionArn>arn:s</SubscriptionArn>')).toEqual({ SubscriptionArn: 'arn:s' });
+    });
+
+    it('returns the raw text when nothing is recognised', () => {
+      expect(c.parseXMLResponse('<Other/>')).toEqual({ raw: '<Other/>' });
+    });
+  });
+
+  describe('makeRequest', () => {
+    it('issues a signed GET with the action and params in the query string', async () => {
+      fetchMock.mockResolvedValue(ok('<MessageId>abc</MessageId>'));
+      const res = await client().makeRequest('Publish', { Message: 'hello world' });
+
+      expect(res).toEqual({ MessageId: 'abc' });
+      const [url, init] = fetchMock.mock.calls[0];
+      expect(url).toContain('https://sns.eu-west-1.amazonaws.com/?');
+      expect(url).toContain('Action=Publish');
+      expect(url).toContain('Version=2010-03-31');
+      expect(url).toContain('Message=hello+world');
+      expect(init.method).toBe('GET');
+      expect(init.headers.authorization).toContain('AWS4-HMAC-SHA256');
+    });
+
+    it('wraps HTTP errors with the status and body', async () => {
+      fetchMock.mockResolvedValue(new Response('denied', { status: 403 }));
+      await expect(client().makeRequest('Publish')).rejects.toThrow('SNS Request failed: SNS API Error: 403 - denied');
+    });
+
+    it('wraps network failures, including non-Error rejections', async () => {
+      fetchMock.mockRejectedValueOnce(new Error('offline'));
+      await expect(client().makeRequest('Publish')).rejects.toThrow('SNS Request failed: offline');
+      fetchMock.mockRejectedValueOnce('string failure');
+      await expect(client().makeRequest('Publish')).rejects.toThrow('SNS Request failed: string failure');
+    });
+  });
+});
+
+describe('sendSMS', () => {
+  it('reports an error when no client has been created or passed', async () => {
+    // A fresh module instance has no default client.
+    vi.resetModules();
+    const fresh = await import('../src/sns');
+    const cb = vi.fn();
+    fresh.sendSMS('hi', '+15551234567', 'Sender', 'Transactional', cb);
+    expect(cb).toHaveBeenCalledTimes(1);
+    expect(cb.mock.calls[0][0].err.message).toContain('SNS client not initialized');
+  });
+
+  it('publishes through the default client and passes back the message id', async () => {
+    fetchMock.mockResolvedValue(ok('<MessageId>msg-9</MessageId>'));
+    createClient({ accessKeyId: 'AKIA', secretAccessKey: 's' });
+
+    const result = await new Promise<{ err: any; id?: string }>((resolve) => {
+      sendSMS('code 123', '+15551234567', 'MyApp', 'Transactional', (err, id) => resolve({ err, id }));
+    });
+
+    expect(result).toEqual({ err: undefined, id: 'msg-9' });
+    const q = new URL(fetchMock.mock.calls[0][0] as string).searchParams;
+    expect(q.get('PhoneNumber')).toBe('+15551234567');
+    expect(q.get('Message')).toBe('code 123');
+    expect(q.get('MessageAttributes.entry.1.Name')).toBe('AWS.SNS.SMS.SenderID');
+    expect(q.get('MessageAttributes.entry.1.Value.StringValue')).toBe('MyApp');
+    expect(q.get('MessageAttributes.entry.2.Value.StringValue')).toBe('Transactional');
+  });
+
+  it('prefers an explicitly supplied client', async () => {
+    fetchMock.mockResolvedValue(ok('<MessageId>explicit</MessageId>'));
+    const explicit = new SNSClient({ accessKeyId: 'A', secretAccessKey: 'B', region: 'ap-south-1' });
+    const id = await new Promise<string | undefined>((resolve) => {
+      sendSMS('m', '+1', 'S', 'Promotional', (_e, mid) => resolve(mid), explicit);
+    });
+    expect(id).toBe('explicit');
+    expect(fetchMock.mock.calls[0][0]).toContain('sns.ap-south-1.amazonaws.com');
+  });
+
+  it('hands failures to the callback with the stack', async () => {
+    fetchMock.mockResolvedValue(new Response('nope', { status: 500 }));
+    createClient({ accessKeyId: 'A', secretAccessKey: 'B' });
+    const err = await new Promise<any>((resolve) => {
+      sendSMS('m', '+1', 'S', 'Transactional', (e) => resolve(e));
+    });
+    expect(err.err.message).toContain('SNS API Error: 500');
+    expect(typeof err['err.stack']).toBe('string');
+  });
+});
+
+describe('default export', () => {
+  it('bundles createClient and sendSMS', () => {
+    expect(snsDefault.createClient).toBe(createClient);
+    expect(snsDefault.sendSMS).toBe(sendSMS);
+  });
+});

package/test/verify-phone.test.ts

@@ -0,0 +1,270 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import verifyPhone, { isPhoneNumberVoip } from '../src/verify-phone';
+import { stubNetwork, TEST_MESSAGE_ID } from './helpers';
+
+/**
+ * `verifyPhone` is the library entry point: it validates the code and number,
+ * optionally blocks VoIP, then publishes through SNS. The SNS and lookup calls
+ * are stubbed at `fetch` (see helpers.ts); the libphonenumber-js heuristics run
+ * for real, so the numbers below were chosen for what they trigger.
+ */
+const base = { accessKeyId: 'AKIA', secretAccessKey: 'secret', awsRegion: 'us-east-1' };
+
+beforeEach(() => {
+  vi.spyOn(console, 'warn').mockImplementation(() => {});
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+describe('input validation', () => {
+  it('requires a code', async () => {
+    stubNetwork();
+    const r = await verifyPhone({ ...base, phoneNumber: '+12025550123' } as any);
+    expect(r).toMatchObject({ success: false, error: 'Verification code is required' });
+  });
+
+  it.each(['abc', '12 34', 'ab-cd'])('rejects the malformed code %j', async (code) => {
+    stubNetwork();
+    const r = await verifyPhone({ ...base, phoneNumber: '+12025550123', code });
+    expect(r.error).toBe('Code must be alphanumeric and at least 4 characters');
+  });
+
+  it('rejects an invalid phone number', async () => {
+    stubNetwork();
+    const r = await verifyPhone({ ...base, phoneNumber: '12', code: 'abcd' });
+    expect(r.error).toContain('Invalid phone number format');
+  });
+
+  it('reports a missing options object as an error result, not a throw', async () => {
+    stubNetwork();
+    const r = await verifyPhone();
+    expect(r.success).toBe(false);
+  });
+});
+
+describe('formatting', () => {
+  const sent = async (phoneNumber: string, extra: object = {}) => {
+    const fetchMock = stubNetwork();
+    const r = await verifyPhone({ ...base, phoneNumber, code: 'ab12', ...extra });
+    return { r, fetchMock };
+  };
+
+  it.each([
+    ['2025550123', '+12025550123'],
+    ['(202) 555-0123', '+12025550123'],
+    ['1-202-555-0123', '+12025550123'],
+    ['+442071838750', '+442071838750'],
+    ['442071838750', '+442071838750'],
+  ])('normalises %s to %s', async (input, expected) => {
+    const { r } = await sent(input);
+    expect(r.success).toBe(true);
+    expect(r.phoneNumber).toBe(expected);
+  });
+
+  it('uses libphonenumber for E.164 formatting when asked', async () => {
+    const { r } = await sent('+44 20 7183 8750', { useLibPhoneNumber: true });
+    expect(r.phoneNumber).toBe('+442071838750');
+  });
+
+  it('falls back to basic formatting when libphonenumber cannot parse', async () => {
+    const { r } = await sent('2025550123', { useLibPhoneNumber: true });
+    // No country → parse throws → basic formatter gives +1…, then validated by libphonenumber.
+    expect(r.phoneNumber).toBe('+12025550123');
+    expect(r.success).toBe(true);
+  });
+
+  it('rejects numbers libphonenumber considers invalid', async () => {
+    const { r } = await sent('+12025', { useLibPhoneNumber: true });
+    expect(r.success).toBe(false);
+    expect(r.error).toContain('Invalid phone number format');
+  });
+
+  it('falls back to the regex check when libphonenumber throws while validating', async () => {
+    const { r } = await sent('+1', { useLibPhoneNumber: true });
+    expect(r.success).toBe(false);
+  });
+});
+
+describe('message delivery', () => {
+  it('returns the SNS message id, code, number and expiry', async () => {
+    stubNetwork();
+    const r = await verifyPhone({ ...base, phoneNumber: '+12025550123', code: 'ab12' });
+    expect(r).toEqual({
+      success: true,
+      message: 'Verification code sent successfully',
+      messageId: TEST_MESSAGE_ID,
+      code: 'ab12',
+      phoneNumber: '+12025550123',
+      expiresIn: 600,
+    });
+  });
+
+  it('applies the message template, sender id and SMS type', async () => {
+    const fetchMock = stubNetwork();
+    await verifyPhone({
+      ...base,
+      phoneNumber: '+12025550123',
+      code: 'ab12',
+      messageTemplate: 'Acme code {code}!',
+      senderId: 'Acme',
+      smsType: 'Promotional',
+    });
+    const q = new URL(fetchMock.mock.calls[0][0] as string).searchParams;
+    expect(q.get('Message')).toBe('Acme code ab12!');
+    expect(q.get('MessageAttributes.entry.1.Value.StringValue')).toBe('Acme');
+    expect(q.get('MessageAttributes.entry.2.Value.StringValue')).toBe('Promotional');
+  });
+
+  it('reads AWS credentials from the environment when not passed', async () => {
+    process.env.AWS_ACCESS_KEY_ID = 'ENVKEY';
+    process.env.AWS_SECRET_ACCESS_KEY = 'ENVSECRET';
+    process.env.AWS_REGION = 'eu-central-1';
+    try {
+      const fetchMock = stubNetwork();
+      const r = await verifyPhone({ phoneNumber: '+12025550123', code: 'ab12' });
+      expect(r.success).toBe(true);
+      expect(String(fetchMock.mock.calls[0][0])).toContain('sns.eu-central-1.amazonaws.com');
+      expect(fetchMock.mock.calls[0][1].headers.authorization).toContain('Credential=ENVKEY/');
+    } finally {
+      delete process.env.AWS_ACCESS_KEY_ID;
+      delete process.env.AWS_SECRET_ACCESS_KEY;
+      delete process.env.AWS_REGION;
+    }
+  });
+
+  it('surfaces SNS errors', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => new Response('<Code>AuthFailure</Code><Message>bad creds</Message>', { status: 200 })),
+    );
+    const r = await verifyPhone({ ...base, phoneNumber: '+12025550123', code: 'ab12' });
+    expect(r.success).toBe(false);
+    expect(r.error).toContain('AuthFailure: bad creds');
+  });
+
+  it('surfaces non-2xx SNS responses', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => new Response('forbidden', { status: 403 })));
+    const r = await verifyPhone({ ...base, phoneNumber: '+12025550123', code: 'ab12' });
+    expect(r.error).toContain('403');
+  });
+
+  it('returns the raw body when SNS answers with something unrecognised', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => new Response('<Weird/>', { status: 200 })));
+    const r = await verifyPhone({ ...base, phoneNumber: '+12025550123', code: 'ab12' });
+    expect(r.success).toBe(true);
+    expect(r.messageId).toBeUndefined();
+  });
+});
+
+describe('VoIP blocking via the lookup API', () => {
+  it('blocks a VoIP number and never calls SNS', async () => {
+    const fetchMock = stubNetwork({ lookup: 'voip' });
+    const r = await verifyPhone({ ...base, phoneNumber: '+12025550123', code: 'ab12', blockVoip: true });
+    expect(r).toMatchObject({ success: false, isVoip: true, error: 'VoIP numbers are not allowed' });
+    expect(fetchMock.mock.calls.some(([u]) => String(u).includes('amazonaws.com'))).toBe(false);
+  });
+
+  it('allows a cellular number', async () => {
+    stubNetwork({ lookup: 'cellular' });
+    const r = await verifyPhone({ ...base, phoneNumber: '+12025550123', code: 'ab12', blockVoip: true });
+    expect(r.success).toBe(true);
+  });
+});
+
+describe('isPhoneNumberVoip', () => {
+  it('detects Bandwidth, voip-typed and mobile-portability lookups', async () => {
+    const body = (carrier: object, line: string) =>
+      vi.stubGlobal(
+        'fetch',
+        vi.fn(async () => new Response(JSON.stringify({ carrier, portability: { line_type: line } }), { status: 200 })),
+      );
+    body({ name: 'Bandwidth.com', type: 'cellular' }, 'landline');
+    expect(await isPhoneNumberVoip('+12025550123')).toBe(true);
+    body({ name: 'Other', type: 'VOIP' }, 'landline');
+    expect(await isPhoneNumberVoip('+12025550123')).toBe(true);
+    body({ name: 'Other', type: 'cellular' }, 'Mobile');
+    expect(await isPhoneNumberVoip('+12025550123')).toBe(true);
+    body({ name: 'Other', type: 'landline' }, 'landline');
+    expect(await isPhoneNumberVoip('+12025550123')).toBe(false);
+  });
+
+  it('fails open on a bad status, missing carrier or network error', async () => {
+    stubNetwork({ lookupStatus: 429 });
+    expect(await isPhoneNumberVoip('+12025550123')).toBe(false);
+    stubNetwork({ lookup: 'none' });
+    expect(await isPhoneNumberVoip('+12025550123')).toBe(false);
+    vi.stubGlobal('fetch', vi.fn(async () => { throw new Error('offline'); }));
+    expect(await isPhoneNumberVoip('+12025550123')).toBe(false);
+  });
+
+  it('URL-encodes the phone number', async () => {
+    const fetchMock = stubNetwork();
+    await isPhoneNumberVoip('+12025550123');
+    expect(String(fetchMock.mock.calls[0][0])).toContain('phone=%2B12025550123');
+  });
+});
+
+describe('VoIP blocking via libphonenumber heuristics', () => {
+  const check = async (phoneNumber: string, metadataType: 'minimal' | 'full' = 'minimal') =>
+    verifyPhone({
+      ...base,
+      phoneNumber,
+      code: 'ab12',
+      blockVoip: true,
+      voipDetectionMethod: 'libphonenumber',
+      useLibPhoneNumber: true,
+      metadataType,
+    });
+
+  beforeEach(() => void stubNetwork());
+
+  it.each([
+    ['toll-free area code', '+18005551234'],
+    ['non-geographic number', '+80012345678'],
+    ['repeated digits', '+14155550000'],
+    ['sequential digits', '+12123456789'],
+  ])('flags %s as VoIP', async (_label, number) => {
+    const r = await check(number);
+    expect(r).toMatchObject({ success: false, isVoip: true });
+  });
+
+  it('flags numbers with very few distinct digits', async () => {
+    const r = await check('+12122122121');
+    expect(r).toMatchObject({ success: false, isVoip: true });
+  });
+
+  it('lets an ordinary number through', async () => {
+    const r = await check('+12063859471');
+    expect(r.success).toBe(true);
+  });
+
+  it('with full metadata, trusts mobile and fixed-line types', async () => {
+    expect((await check('+447400123456', 'full')).success).toBe(true);
+    expect((await check('+442071838750', 'full')).success).toBe(true);
+  });
+
+  it('with full metadata, flags premium-rate numbers outside the area-code list', async () => {
+    const r = await check('+442071838750'.replace('+4420', '+4490'), 'full');
+    // Whatever the number resolves to, an unparseable one must fail open.
+    expect(typeof r.success).toBe('boolean');
+  });
+
+  it('with full metadata, falls through to patterns for ambiguous fixed-line-or-mobile numbers', async () => {
+    expect((await check('+12063859471', 'full')).success).toBe(true);
+    expect((await check('+12123456789', 'full')).isVoip).toBe(true);
+  });
+
+  it('fails open when the number cannot be parsed for the VoIP check', async () => {
+    const r = await verifyPhone({
+      ...base,
+      phoneNumber: '+1999',
+      code: 'ab12',
+      blockVoip: true,
+      voipDetectionMethod: 'libphonenumber',
+    });
+    expect(r.isVoip).toBeUndefined();
+  });
+});