test(core,trigger-api): pin the timestamped signature form, its window, and the body-only control

Claude-Session: https://claude.ai/code/session_01CBAfsWMSfM3EToQGVStEcp
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

packages/core/src/security/http-signature.test.ts

@@ -1,7 +1,21 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
-import { describe, it, expect } from 'vitest';
-import { HTTP_SIGNATURE_HEADER, signHttpBody } from '../index.js';
+import { timingSafeEqual } from 'node:crypto';
+import { afterEach, beforeEach, describe, it, expect, vi } from 'vitest';
+import {
+    HTTP_SIGNATURE_HEADER,
+    HTTP_SIGNATURE_TOLERANCE_SECONDS,
+    signHttpBody,
+    signHttpBodyAt,
+    verifyHttpSignature,
+} from '../index.js';
+
+// The constant-time pin below counts calls to `timingSafeEqual`; the wrapper
+// keeps its behaviour byte for byte.
+vi.mock('node:crypto', async (importOriginal) => {
+    const actual = await importOriginal<typeof import('node:crypto')>();
+    return { ...actual, timingSafeEqual: vi.fn(actual.timingSafeEqual) };
+});
 
 /**
  * The scheme's wire form, pinned by literal values rather than by recomputing
@@ -30,3 +44,144 @@ describe('the outbound HTTP signature scheme', () => {
         expect(signHttpBody('{"a": 1}', 'shh')).not.toBe(signHttpBody('{"a":1}', 'shh'));
     });
 });
+
+/**
+ * The timestamped form: the same literal-value discipline as above. Every
+ * receiver of a `t=…,v1=…` value — ours and anyone else's — relies on these
+ * exact bytes, and on the timestamp being inside the signed material.
+ */
+describe('the timestamped form of the HTTP signature scheme', () => {
+    it('is t=<seconds>,v1= plus the lowercase hex HMAC-SHA256 of "<t>.<body>"', () => {
+        expect(signHttpBodyAt('{"a":1}', 'shh', 1760000000)).toBe(
+            't=1760000000,v1=f5f3d98fe723d34c35649871bfa9eb4530a1b2f197e96e6e8c1b95a984e3d46d',
+        );
+        expect(signHttpBodyAt('', 'flow-hook-secret', 0)).toBe(
+            't=0,v1=6433f1bb31a3f1b7ddbc61b4e6361758e607526ac9953cb6a91389500ffefad0',
+        );
+    });
+
+    it('signs the timestamp: the same body at another second is another signature', () => {
+        const at = signHttpBodyAt('{"a":1}', 'shh', 1760000000).split(',v1=')[1];
+        const next = signHttpBodyAt('{"a":1}', 'shh', 1760000001).split(',v1=')[1];
+        expect(next).not.toBe(at);
+        // And it is not the body-only HMAC with a timestamp beside it.
+        expect(at).not.toBe(signHttpBody('{"a":1}', 'shh').slice('sha256='.length));
+    });
+
+    it('refuses a timestamp that is not a non-negative whole number of seconds', () => {
+        for (const bad of [-1, 1.5, Number.NaN, Number.POSITIVE_INFINITY, Number.MAX_SAFE_INTEGER + 1]) {
+            expect(() => signHttpBodyAt('{}', 'shh', bad)).toThrow(RangeError);
+        }
+    });
+
+    it('has a fixed five-minute tolerance window', () => {
+        expect(HTTP_SIGNATURE_TOLERANCE_SECONDS).toBe(300);
+    });
+});
+
+describe('verifyHttpSignature — the receiver\'s half of both forms', () => {
+    const NOW = 1760000000;
+    const BODY = '{"event":"paid","id":"evt_1"}';
+    const SECRET = 'pin-verify-secret-7c1e';
+
+    beforeEach(() => {
+        vi.useFakeTimers({ toFake: ['Date'] });
+        vi.setSystemTime(NOW * 1000);
+        vi.mocked(timingSafeEqual).mockClear();
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+
+    it('accepts a fresh timestamped value, as the v1 form', () => {
+        expect(verifyHttpSignature(BODY, SECRET, signHttpBodyAt(BODY, SECRET, NOW))).toEqual({ valid: true, scheme: 'v1' });
+    });
+
+    it('accepts a timestamp at either edge of the window, and refuses one second past either edge', () => {
+        const at = (t: number) => verifyHttpSignature(BODY, SECRET, signHttpBodyAt(BODY, SECRET, t));
+        expect(at(NOW - HTTP_SIGNATURE_TOLERANCE_SECONDS)).toEqual({ valid: true, scheme: 'v1' });
+        expect(at(NOW + HTTP_SIGNATURE_TOLERANCE_SECONDS)).toEqual({ valid: true, scheme: 'v1' });
+        expect(at(NOW - HTTP_SIGNATURE_TOLERANCE_SECONDS - 1)).toEqual({ valid: false, reason: 'outside-window' });
+        expect(at(NOW + HTTP_SIGNATURE_TOLERANCE_SECONDS + 1)).toEqual({ valid: false, reason: 'outside-window' });
+    });
+
+    it('refuses a value it accepted once the clock has moved past the window — a replay', () => {
+        const header = signHttpBodyAt(BODY, SECRET, NOW);
+        expect(verifyHttpSignature(BODY, SECRET, header)).toEqual({ valid: true, scheme: 'v1' });
+        vi.setSystemTime((NOW + HTTP_SIGNATURE_TOLERANCE_SECONDS + 1) * 1000);
+        expect(verifyHttpSignature(BODY, SECRET, header)).toEqual({ valid: false, reason: 'outside-window' });
+    });
+
+    it('refuses a timestamp the HMAC does not cover — never a fallback to the body-only form', () => {
+        const bodyOnlyHex = signHttpBody(BODY, SECRET).slice('sha256='.length);
+        // A captured body-only signature, re-labelled with a fresh timestamp.
+        expect(verifyHttpSignature(BODY, SECRET, `t=${NOW},v1=${bodyOnlyHex}`)).toEqual({ valid: false, reason: 'mismatch' });
+        // A genuine value whose timestamp was moved into the window.
+        const stale = signHttpBodyAt(BODY, SECRET, NOW - 3600);
+        const moved = stale.replace(`t=${NOW - 3600},`, `t=${NOW},`);
+        expect(moved).not.toBe(stale);
+        expect(verifyHttpSignature(BODY, SECRET, moved)).toEqual({ valid: false, reason: 'mismatch' });
+    });
+
+    it('refuses the wrong secret and the wrong body in the timestamped form', () => {
+        expect(verifyHttpSignature(BODY, SECRET, signHttpBodyAt(BODY, 'another-secret', NOW)))
+            .toEqual({ valid: false, reason: 'mismatch' });
+        expect(verifyHttpSignature(`${BODY} `, SECRET, signHttpBodyAt(BODY, SECRET, NOW)))
+            .toEqual({ valid: false, reason: 'mismatch' });
+    });
+
+    it('refuses every value that claims the timestamped form without its exact shape', () => {
+        const hex = signHttpBodyAt(BODY, SECRET, NOW).split(',v1=')[1]!;
+        for (const malformed of [
+            `t=${NOW}`,
+            `t=${NOW},v1=`,
+            `t=${NOW},v1=${hex.slice(1)}`,
+            `t=${NOW},v1=${hex.toUpperCase()}`,
+            `v1=${hex},t=${NOW}`,
+            `t=0${NOW},v1=${hex}`,
+            `t=+${NOW},v1=${hex}`,
+            `t=${NOW}.5,v1=${hex}`,
+            `t=${NOW},v1=${hex},v0=${hex}`,
+            `t=${NOW},v1=${hex},v1=${hex}`,
+            `t = ${NOW}, v1 = ${hex}`,
+            `t=${NOW},sha256=${hex}`,
+            `T=${NOW},V1=${hex}`,
+            'garbage',
+        ]) {
+            expect(verifyHttpSignature(BODY, SECRET, malformed), malformed).toEqual({ valid: false, reason: 'malformed' });
+        }
+    });
+
+    it('still accepts the body-only form, as body-only, and refuses a wrong one', () => {
+        expect(verifyHttpSignature(BODY, SECRET, signHttpBody(BODY, SECRET))).toEqual({ valid: true, scheme: 'body-only' });
+        expect(verifyHttpSignature(BODY, SECRET, signHttpBody(BODY, 'another-secret'))).toEqual({ valid: false, reason: 'mismatch' });
+        expect(verifyHttpSignature(BODY, SECRET, 'sha256=zz')).toEqual({ valid: false, reason: 'mismatch' });
+        // The body-only form signs no time, so the clock never refuses it.
+        vi.setSystemTime((NOW + 10 * 365 * 24 * 3600) * 1000);
+        expect(verifyHttpSignature(BODY, SECRET, signHttpBody(BODY, SECRET))).toEqual({ valid: true, scheme: 'body-only' });
+    });
+
+    it('trims the header, and reads a missing or blank one as absent', () => {
+        expect(verifyHttpSignature(BODY, SECRET, `  ${signHttpBodyAt(BODY, SECRET, NOW)}  `)).toEqual({ valid: true, scheme: 'v1' });
+        expect(verifyHttpSignature(BODY, SECRET, ` ${signHttpBody(BODY, SECRET)}\t`)).toEqual({ valid: true, scheme: 'body-only' });
+        for (const absent of [undefined, '', '   ']) {
+            expect(verifyHttpSignature(BODY, SECRET, absent)).toEqual({ valid: false, reason: 'absent' });
+        }
+    });
+
+    it('decides every well-formed value of either form by a constant-time comparison', () => {
+        const compare = vi.mocked(timingSafeEqual);
+        const cases: Array<[string, boolean]> = [
+            [signHttpBodyAt(BODY, SECRET, NOW), true],
+            [signHttpBodyAt(BODY, 'another-secret', NOW), false],
+            [signHttpBody(BODY, SECRET), true],
+            [signHttpBody(BODY, 'another-secret'), false],
+        ];
+        for (const [header, valid] of cases) {
+            compare.mockClear();
+            expect(verifyHttpSignature(BODY, SECRET, header).valid, header).toBe(valid);
+            expect(compare, header).toHaveBeenCalledTimes(1);
+            expect(compare.mock.results[0]!.value, header).toBe(valid);
+        }
+    });
+});

packages/triggers/trigger-api/src/api-trigger.test.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { createHmac } from 'node:crypto';
-import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { ApiTrigger, verifySignature } from './api-trigger.js';
 import type { QueueServiceSurface } from './api-trigger.js';
 
@@ -221,3 +221,139 @@ describe('ApiTrigger — a secret read at verification time', () => {
         expect(reads).toBe(0);
     });
 });
+
+/**
+ * The timestamped signature form beside the body-only one. A third-party
+ * sender computes it on its own, so the helper below derives it with
+ * `createHmac` directly from the published recipe rather than through
+ * `@objectstack/core`: these pins check the receiver against the wire form,
+ * not against the function it verifies with.
+ *
+ *   x-objectstack-signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">
+ *
+ * Every refusal asserts the whole bad-signature envelope — `401`, code
+ * `INVALID_SIGNATURE` — and that nothing reached the queue.
+ */
+describe('ApiTrigger — the timestamped signature form', () => {
+    const NOW = 1760000000;
+    const WINDOW = 300;
+    const SECRET = 'pin-trigger-v1-3f9a';
+    const BODY = JSON.stringify({ event: 'invoice.paid', id: 'evt_77' });
+    const REFUSED = { status: 401, body: { success: false, error: { code: 'INVALID_SIGNATURE', message: 'Signature verification failed.' } } };
+
+    function sigV1(secret: string, body: string, t: number): string {
+        return `t=${t},v1=` + createHmac('sha256', secret).update(`${t}.${body}`, 'utf8').digest('hex');
+    }
+
+    let queue: ReturnType<typeof makeFakeQueue>;
+    let log: { info: ReturnType<typeof vi.fn>; warn: ReturnType<typeof vi.fn> };
+    let trigger: ApiTrigger;
+    let runs: any[];
+
+    beforeEach(() => {
+        vi.useFakeTimers({ toFake: ['Date'] });
+        vi.setSystemTime(NOW * 1000);
+        queue = makeFakeQueue();
+        log = { info: vi.fn(), warn: vi.fn() };
+        trigger = new ApiTrigger(() => queue, log as any);
+        runs = [];
+        trigger.start({ flowName: 'invoice_intake', config: { hookId: 'hk_v1', secret: SECRET } }, async (ctx) => { runs.push(ctx); });
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+
+    const post = (signatureHeader: string | undefined, rawBody = BODY) =>
+        trigger.handleRequest({ flowName: 'invoice_intake', hookId: 'hk_v1', rawBody, signatureHeader });
+
+    /** The deprecation lines this trigger has logged so far. */
+    const deprecationLines = () =>
+        log.warn.mock.calls.map((c) => String(c[0])).filter((line) => line.includes('deprecated'));
+
+    it('accepts a fresh timestamped post: 202, enqueued, the flow runs — and no deprecation line', async () => {
+        const res = await post(sigV1(SECRET, BODY, NOW));
+        expect(res.status).toBe(202);
+        expect(res.body).toEqual({ accepted: true, messageId: 'msg_1' });
+        expect(await queue.deliver()).toBe(1);
+        expect(runs[0].record).toEqual({ event: 'invoice.paid', id: 'evt_77' });
+        expect(deprecationLines()).toEqual([]);
+    });
+
+    it('refuses a replay outside the window: the post it accepted, sent again later, is a 401 and is not enqueued', async () => {
+        const header = sigV1(SECRET, BODY, NOW);
+        expect((await post(header)).status).toBe(202);
+        expect(queue.published).toHaveLength(1);
+
+        vi.setSystemTime((NOW + WINDOW + 1) * 1000);
+        expect(await post(header)).toEqual(REFUSED);
+        expect(queue.published).toHaveLength(1);
+    });
+
+    it('refuses a stale timestamp the HMAC genuinely covers, and a future one past the window; accepts the edges', async () => {
+        expect(await post(sigV1(SECRET, BODY, NOW - WINDOW - 1))).toEqual(REFUSED);
+        expect(await post(sigV1(SECRET, BODY, NOW + WINDOW + 1))).toEqual(REFUSED);
+        expect(queue.published).toEqual([]);
+        expect((await post(sigV1(SECRET, BODY, NOW - WINDOW))).status).toBe(202);
+        expect((await post(sigV1(SECRET, BODY, NOW + WINDOW))).status).toBe(202);
+    });
+
+    it('refuses a stale timestamp carried with a valid BODY-ONLY signature — a timestamp claims the versioned form, with no fallback', async () => {
+        const bodyOnlyHex = sig(SECRET, BODY).slice('sha256='.length);
+        for (const t of [NOW - WINDOW - 1, NOW - 3600, NOW]) {
+            expect(await post(`t=${t},v1=${bodyOnlyHex}`), `v1 at ${t}`).toEqual(REFUSED);
+            expect(await post(`t=${t},sha256=${bodyOnlyHex}`), `sha256 at ${t}`).toEqual(REFUSED);
+        }
+        expect(queue.published).toEqual([]);
+        expect(deprecationLines()).toEqual([]);
+    });
+
+    it('refuses a malformed timestamped value with the same envelope a bad signature gets', async () => {
+        const hex = sigV1(SECRET, BODY, NOW).split(',v1=')[1]!;
+        for (const malformed of [
+            `t=${NOW}`,
+            `t=${NOW},v1=${hex.slice(2)}`,
+            `t=${NOW},v1=${hex.toUpperCase()}`,
+            `v1=${hex},t=${NOW}`,
+            `t=0${NOW},v1=${hex}`,
+            `t=abc,v1=${hex}`,
+            `t=${NOW},v1=${hex},v0=${hex}`,
+        ]) {
+            expect(await post(malformed), malformed).toEqual(REFUSED);
+        }
+        // The same envelope as a plain bad signature.
+        expect(await post(sig('not-the-secret', BODY))).toEqual(REFUSED);
+        expect(queue.published).toEqual([]);
+    });
+
+    it('refuses the timestamped form under the wrong secret, or over a body other than the one received', async () => {
+        expect(await post(sigV1('not-the-secret', BODY, NOW))).toEqual(REFUSED);
+        expect(await post(sigV1(SECRET, BODY, NOW), `${BODY}\n`)).toEqual(REFUSED);
+        expect(queue.published).toEqual([]);
+    });
+
+    it('CONTROL: still accepts a body-only signature, and logs its deprecation once per armed hook, naming the flow and the hook', async () => {
+        expect((await post(sig(SECRET, BODY))).status).toBe(202);
+        expect((await post(sig(SECRET, BODY))).status).toBe(202);
+        expect(queue.published).toHaveLength(2);
+
+        const lines = deprecationLines();
+        expect(lines).toHaveLength(1);
+        expect(lines[0]).toContain("flow 'invoice_intake'");
+        expect(lines[0]).toContain("hook 'hk_v1'");
+        expect(lines[0]).toContain('t=<unix seconds>,v1=');
+
+        // A timestamped post adds nothing to it; re-arming the hook says it once more.
+        expect((await post(sigV1(SECRET, BODY, NOW))).status).toBe(202);
+        expect(deprecationLines()).toHaveLength(1);
+        trigger.stop('invoice_intake');
+        trigger.start({ flowName: 'invoice_intake', config: { hookId: 'hk_v1', secret: SECRET } }, async () => {});
+        expect((await post(sig(SECRET, BODY))).status).toBe(202);
+        expect(deprecationLines()).toHaveLength(2);
+    });
+
+    it('verifySignature, the exported check, accepts both forms and refuses a stale one', () => {
+        expect(verifySignature(SECRET, BODY, sigV1(SECRET, BODY, NOW))).toBe(true);
+        expect(verifySignature(SECRET, BODY, sig(SECRET, BODY))).toBe(true);
+        expect(verifySignature(SECRET, BODY, sigV1(SECRET, BODY, NOW - WINDOW - 1))).toBe(false);
+    });
+});