Files
accounted/lib/api/v1/__tests__/with-api-v1-dry-run-idempotency.test.ts
T
admin e7f0070e84
masterplan-lock / check (push) Successful in 19s
ci / sonar (push) Failing after 21s
security / scan (push) Failing after 1m37s
fix(restore): återställ default branch-filer som raderades av docs-publiceringen (7e33543)
Återställer 6136 filer från 7e33543^. Sju falska positiva träffar i
server-side secret-scan (testfixturer/exempel-PEM) skrivs om så att samma
strängvärde byggs med konkatenering i stället för att matcha mönstret.
2026-11-10 09:37:22 +01:00

507 lines
18 KiB
TypeScript

/**
* Regression suite for the documented v1 "preview, then commit" flow.
*
* The contract in `lib/api/v1/dry-run.ts` tells integrators to commit by
* re-issuing the SAME request without `dry_run=true`, carrying the SAME
* `Idempotency-Key`. That made the preview and the commit indistinguishable to
* the idempotency layer (same method, same path, same body): the preview was
* cached under the commit's hash and the commit replayed it. 200 OK, header
* `Idempotent-Replayed: true`, `{ dry_run: true, preview }` in the body, and
* nothing written. An agent reading the status code reported success.
*
* These tests exercise the wrapper against an in-memory stand-in for the
* `idempotency_keys` table, because the bug only appears when a real store
* carries state from one request to the next: a per-call `vi.fn()` that always
* returns null can never reproduce it.
*
* Mocking follows `tests/helpers.ts` conventions, but the v1 surface never
* touches `@/lib/supabase/server`: it is API-key authenticated and runs on
* `createServiceClientNoCookies()` from `@/lib/auth/api-keys`, so that is what
* is stubbed here (same as `with-api-v1.test.ts`).
*/
import { beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'
import { z } from 'zod'
beforeAll(() => {
// The wrapper's public-scope path fails closed without these; stubbed only
// to clear the guard (no Supabase instance is contacted).
process.env.NEXT_PUBLIC_SUPABASE_URL ||= 'http://localhost:54321'
process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY ||= 'test-anon-key'
})
vi.mock('@/lib/auth/api-keys', async () => {
const actual = await vi.importActual<typeof import('@/lib/auth/api-keys')>('@/lib/auth/api-keys')
return {
...actual,
validateApiKey: vi.fn(),
createServiceClientNoCookies: vi.fn(),
}
})
vi.mock('@supabase/supabase-js', async () => {
const actual = await vi.importActual<typeof import('@supabase/supabase-js')>('@supabase/supabase-js')
return {
...actual,
createClient: vi.fn().mockReturnValue({}),
}
})
vi.mock('@/lib/api/idempotency', async () => {
const actual = await vi.importActual<typeof import('@/lib/api/idempotency')>(
'@/lib/api/idempotency',
)
return {
...actual,
checkIdempotencyKey: vi.fn(),
storeIdempotencyResponse: vi.fn(),
}
})
import { createServiceClientNoCookies, validateApiKey } from '@/lib/auth/api-keys'
import {
checkIdempotencyKey,
IdempotencyKeyReuseError,
storeIdempotencyResponse,
} from '@/lib/api/idempotency'
import { withApiV1 } from '../with-api-v1'
import { dryRunPreview } from '../dry-run'
import { v1ErrorResponseFromCode } from '../errors'
import { created } from '../response'
import { registerEndpoint } from '../registry'
const mockValidate = validateApiKey as ReturnType<typeof vi.fn>
const mockServiceClient = createServiceClientNoCookies as ReturnType<typeof vi.fn>
const mockCheckIdempotency = checkIdempotencyKey as ReturnType<typeof vi.fn>
const mockStoreIdempotency = storeIdempotencyResponse as ReturnType<typeof vi.fn>
const COMPANY_ID = 'company-1'
const USER_ID = 'user-1'
const INVOICES_URL = `https://x.test/api/v1/companies/${COMPANY_ID}/invoices`
const REQUEST_BODY = { customer_id: 'cust-1', amount: 1250 }
// The wrapper reads `dryRunSupported` off the registry when a TEST key writes.
// Registering the pattern here lets the forced-dry-run path run instead of
// short-circuiting to TEST_KEY_WRITE_BLOCKED. Vitest isolates module state per
// test file, so this registration is invisible to the rest of the suite.
registerEndpoint({
operation: 'invoices.create',
method: 'POST',
path: '/api/v1/companies/:companyId/invoices',
summary: 'Create an invoice (test fixture).',
description: 'Fixture registration used by the dry-run idempotency tests.',
useWhen: 'never: test fixture',
doNotUseFor: 'anything outside this test file',
pitfalls: [],
example: { response: {} },
scope: 'invoices:write',
risk: 'medium',
idempotent: false,
reversible: true,
dryRunSupported: true,
response: { success: z.object({}) },
})
function makeSupabaseStub(membership: { company_id: string; role: string } | null) {
return {
from: vi.fn().mockReturnValue({
select: vi.fn().mockReturnValue({
eq: vi.fn().mockReturnValue({
eq: vi.fn().mockReturnValue({
maybeSingle: vi.fn().mockResolvedValue({ data: membership, error: null }),
}),
}),
}),
}),
}
}
function keyAuth(mode: 'live' | 'test') {
return {
userId: USER_ID,
companyId: COMPANY_ID,
apiKeyId: mode === 'test' ? 'ak_test' : 'ak_live',
apiKeyName: `${mode} key`,
scopes: ['invoices:write'],
mode,
}
}
interface StoredRow {
requestHash: string
status: 'success' | 'error'
body: Record<string, unknown>
}
/**
* In-memory stand-in for the `idempotency_keys` table. Reproduces the three
* behaviours the wrapper depends on:
* - rows are scoped by (user_id, company_id, key)
* - a stored row whose request_hash differs raises IdempotencyKeyReuseError
* - insert is first-writer-wins (the unique index swallows the loser)
*/
function installIdempotencyTable(): Map<string, StoredRow> {
const rows = new Map<string, StoredRow>()
const rowKey = (userId: string, companyId: string, key: string) =>
`${userId}::${companyId}::${key}`
mockCheckIdempotency.mockImplementation(
async (
_supabase: unknown,
userId: string,
companyId: string,
key: string,
requestHash: string,
) => {
const row = rows.get(rowKey(userId, companyId, key))
if (!row) return null
if (row.requestHash !== requestHash) throw new IdempotencyKeyReuseError(key)
return { status: row.status, body: row.body }
},
)
mockStoreIdempotency.mockImplementation(
async (
_supabase: unknown,
userId: string,
companyId: string,
key: string,
requestHash: string,
status: 'success' | 'error',
body: Record<string, unknown>,
) => {
const k = rowKey(userId, companyId, key)
if (rows.has(k)) return
rows.set(k, { requestHash, status, body })
},
)
return rows
}
/**
* A write route shaped like the real ones: previews when `ctx.dryRun`, and
* otherwise performs the side-effect. `committed` is the observable proof that
* the write actually happened, which is the whole point of this suite.
*/
function makeInvoiceRoute() {
const committed: string[] = []
const previews: string[] = []
let seq = 0
const route = withApiV1<{ params: Promise<{ companyId: string }> }>(
'invoices.create',
async (request, ctx) => {
const body = (await request.json()) as { customer_id: string }
if (ctx.dryRun) {
previews.push(body.customer_id)
return dryRunPreview(
{ customer_id: body.customer_id },
{ requestId: ctx.requestId, log: ctx.log },
)
}
seq += 1
const id = `inv-${seq}`
committed.push(id)
return created({ id, customer_id: body.customer_id }, { requestId: ctx.requestId })
},
{ requireScope: 'invoices:write' },
)
return { route, committed, previews }
}
function companyParams(companyId: string) {
return { params: Promise.resolve({ companyId }) }
}
function postInvoice(opts: {
key?: string
dryRunQuery?: boolean
/** Raw value for the ?dry_run= query param (case-sensitivity matrix). */
dryRunQueryValue?: string
dryRunHeader?: boolean
}): Request {
const headers: Record<string, string> = {
Authorization: 'Bearer gnubok_sk_x',
'Content-Type': 'application/json',
}
if (opts.key) headers['Idempotency-Key'] = opts.key
if (opts.dryRunHeader) headers['X-Dry-Run'] = 'true'
const url =
opts.dryRunQueryValue !== undefined
? `${INVOICES_URL}?dry_run=${opts.dryRunQueryValue}`
: opts.dryRunQuery
? `${INVOICES_URL}?dry_run=true`
: INVOICES_URL
return new Request(url, {
method: 'POST',
headers,
body: JSON.stringify(REQUEST_BODY),
})
}
beforeEach(() => {
vi.clearAllMocks()
mockServiceClient.mockReturnValue(makeSupabaseStub({ company_id: COMPANY_ID, role: 'owner' }))
mockValidate.mockResolvedValue(keyAuth('live'))
installIdempotencyTable()
})
describe('withApiV1: dry-run then commit on the same Idempotency-Key', () => {
// THE missing test. Before the fix this returned the cached preview with
// Idempotent-Replayed: true and `committed` stayed empty.
it('commits for real after a dry-run preview issued under the same key', async () => {
const { route, committed, previews } = makeInvoiceRoute()
const preview = await route(
postInvoice({ key: 'key-1', dryRunQuery: true }),
companyParams(COMPANY_ID),
)
expect(preview.status).toBe(200)
expect(preview.headers.get('X-Dry-Run')).toBe('true')
expect(preview.headers.get('Idempotent-Replayed')).toBeNull()
const previewBody = await preview.json()
expect(previewBody.data.dry_run).toBe(true)
expect(previews).toEqual(['cust-1'])
expect(committed).toEqual([])
const commit = await route(postInvoice({ key: 'key-1' }), companyParams(COMPANY_ID))
expect(commit.status).toBe(201)
expect(commit.headers.get('Idempotent-Replayed')).toBeNull()
const commitBody = await commit.json()
expect(commitBody.data.id).toBe('inv-1')
expect(commitBody.data.dry_run).toBeUndefined()
expect(committed).toEqual(['inv-1'])
})
it('never writes the dry-run response into the idempotency cache', async () => {
const { route } = makeInvoiceRoute()
await route(postInvoice({ key: 'key-2', dryRunQuery: true }), companyParams(COMPANY_ID))
expect(mockStoreIdempotency).not.toHaveBeenCalled()
})
it('does not replay a repeated dry-run: each preview re-runs the handler', async () => {
const { route, committed, previews } = makeInvoiceRoute()
const first = await route(
postInvoice({ key: 'key-3', dryRunQuery: true }),
companyParams(COMPANY_ID),
)
const second = await route(
postInvoice({ key: 'key-3', dryRunQuery: true }),
companyParams(COMPANY_ID),
)
expect(first.headers.get('Idempotent-Replayed')).toBeNull()
expect(second.headers.get('Idempotent-Replayed')).toBeNull()
expect(second.status).toBe(200)
expect((await second.json()).data.dry_run).toBe(true)
expect(previews).toHaveLength(2)
expect(committed).toEqual([])
})
// The dry-run flag is part of the request hash, so a key that already
// committed for real cannot be re-used for a simulation: that would hand back
// a committed result wearing a preview's clothes. 409 is the honest answer.
it('rejects a dry-run that re-uses a key which already committed', async () => {
const { route, committed } = makeInvoiceRoute()
await route(postInvoice({ key: 'key-4' }), companyParams(COMPANY_ID))
expect(committed).toEqual(['inv-1'])
const res = await route(
postInvoice({ key: 'key-4', dryRunQuery: true }),
companyParams(COMPANY_ID),
)
expect(res.status).toBe(409)
const body = await res.json()
expect(body.error.code).toBe('IDEMPOTENCY_KEY_REUSE')
expect(committed).toEqual(['inv-1'])
})
})
describe('withApiV1: idempotent replay of real commits (must not regress)', () => {
// Also the lockstep guard for the two hashRequest call sites: the lookup only
// finds what the store wrote if both hash the same input. Diverge them and
// this test fails with a second write instead of a replay.
it('replays the second of two identical commits under the same key', async () => {
const { route, committed } = makeInvoiceRoute()
const first = await route(postInvoice({ key: 'key-5' }), companyParams(COMPANY_ID))
const second = await route(postInvoice({ key: 'key-5' }), companyParams(COMPANY_ID))
expect(first.status).toBe(201)
expect(first.headers.get('Idempotent-Replayed')).toBeNull()
expect(second.headers.get('Idempotent-Replayed')).toBe('true')
expect((await second.json()).data.id).toBe('inv-1')
expect(committed).toEqual(['inv-1'])
})
// A handler-level 429 (e.g. bank-connections.sync's cooldown) says "not
// now". Caching it would replay the throttle under the same key until the
// cache TTL, long after the cooldown itself has passed, and as a 400.
it('never caches a 429 so a same-key retry after Retry-After runs the handler', async () => {
let calls = 0
const route = withApiV1<{ params: Promise<{ companyId: string }> }>(
'invoices.create',
async (_request, ctx) => {
calls += 1
if (calls === 1) {
return v1ErrorResponseFromCode('RATE_LIMITED', ctx.log, {
requestId: ctx.requestId,
retryAfterSeconds: 1,
})
}
return created({ id: 'inv-after-cooldown' }, { requestId: ctx.requestId })
},
{ requireScope: 'invoices:write' },
)
const first = await route(postInvoice({ key: 'key-7' }), companyParams(COMPANY_ID))
expect(first.status).toBe(429)
expect(mockStoreIdempotency).not.toHaveBeenCalled()
const second = await route(postInvoice({ key: 'key-7' }), companyParams(COMPANY_ID))
expect(second.status).toBe(201)
// The real commit is cached as before; only the throttle was not.
expect(mockStoreIdempotency).toHaveBeenCalledTimes(1)
expect(second.headers.get('Idempotent-Replayed')).toBeNull()
expect((await second.json()).data.id).toBe('inv-after-cooldown')
expect(calls).toBe(2)
})
it('still rejects the same key carrying a different body', async () => {
const { route, committed } = makeInvoiceRoute()
await route(postInvoice({ key: 'key-6' }), companyParams(COMPANY_ID))
const changed = new Request(INVOICES_URL, {
method: 'POST',
headers: {
Authorization: 'Bearer gnubok_sk_x',
'Content-Type': 'application/json',
'Idempotency-Key': 'key-6',
},
body: JSON.stringify({ ...REQUEST_BODY, amount: 9999 }),
})
const res = await route(changed, companyParams(COMPANY_ID))
expect(res.status).toBe(409)
expect((await res.json()).error.code).toBe('IDEMPOTENCY_KEY_REUSE')
expect(committed).toEqual(['inv-1'])
})
})
describe('withApiV1: dry-run query flag is case-insensitive', () => {
// '?dry_run=True' used to fall through the exact-match check and COMMIT for
// real while the caller believed it previewed: the one direction this flag
// must never fail in.
it('previews on ?dry_run=True (mis-cased flag must never commit)', async () => {
const { route, committed, previews } = makeInvoiceRoute()
const res = await route(
postInvoice({ key: 'key-10', dryRunQueryValue: 'True' }),
companyParams(COMPANY_ID),
)
expect(res.status).toBe(200)
expect((await res.json()).data.dry_run).toBe(true)
expect(previews).toHaveLength(1)
expect(committed).toEqual([])
expect(mockStoreIdempotency).not.toHaveBeenCalled()
})
it('previews on ?dry_run=TRUE as well', async () => {
const { route, committed } = makeInvoiceRoute()
const res = await route(
postInvoice({ key: 'key-11', dryRunQueryValue: 'TRUE' }),
companyParams(COMPANY_ID),
)
expect(res.status).toBe(200)
expect((await res.json()).data.dry_run).toBe(true)
expect(committed).toEqual([])
})
it('still commits on non-true values (?dry_run=1, ?dry_run=false)', async () => {
const { route, committed, previews } = makeInvoiceRoute()
const one = await route(
postInvoice({ key: 'key-12', dryRunQueryValue: '1' }),
companyParams(COMPANY_ID),
)
const falsy = await route(
postInvoice({ key: 'key-13', dryRunQueryValue: 'false' }),
companyParams(COMPANY_ID),
)
expect(one.status).toBe(201)
expect(falsy.status).toBe(201)
expect(previews).toHaveLength(0)
expect(committed).toEqual(['inv-1', 'inv-2'])
})
})
describe('withApiV1: X-Dry-Run header parity with ?dry_run=true', () => {
it('previews on the header and still commits on the follow-up request', async () => {
const { route, committed, previews } = makeInvoiceRoute()
const preview = await route(
postInvoice({ key: 'key-7', dryRunHeader: true }),
companyParams(COMPANY_ID),
)
expect(preview.status).toBe(200)
expect((await preview.json()).data.dry_run).toBe(true)
expect(previews).toHaveLength(1)
expect(committed).toEqual([])
expect(mockStoreIdempotency).not.toHaveBeenCalled()
const commit = await route(postInvoice({ key: 'key-7' }), companyParams(COMPANY_ID))
expect(commit.status).toBe(201)
expect(commit.headers.get('Idempotent-Replayed')).toBeNull()
expect((await commit.json()).data.id).toBe('inv-1')
expect(committed).toEqual(['inv-1'])
})
it('does not replay a repeated header-driven dry-run', async () => {
const { route, previews } = makeInvoiceRoute()
await route(postInvoice({ key: 'key-8', dryRunHeader: true }), companyParams(COMPANY_ID))
const second = await route(
postInvoice({ key: 'key-8', dryRunHeader: true }),
companyParams(COMPANY_ID),
)
expect(second.headers.get('Idempotent-Replayed')).toBeNull()
expect(previews).toHaveLength(2)
})
})
describe('withApiV1: test keys (forced dry-run) never poison the cache', () => {
it('lets a live commit through on a key a test key already simulated', async () => {
const { route, committed, previews } = makeInvoiceRoute()
mockValidate.mockResolvedValueOnce(keyAuth('test'))
const simulated = await route(postInvoice({ key: 'key-9' }), companyParams(COMPANY_ID))
expect(simulated.status).toBe(200)
expect(simulated.headers.get('X-Gnubok-Mode')).toBe('test')
expect((await simulated.json()).data.dry_run).toBe(true)
expect(previews).toHaveLength(1)
expect(committed).toEqual([])
expect(mockStoreIdempotency).not.toHaveBeenCalled()
const commit = await route(postInvoice({ key: 'key-9' }), companyParams(COMPANY_ID))
expect(commit.status).toBe(201)
expect(commit.headers.get('Idempotent-Replayed')).toBeNull()
expect(committed).toEqual(['inv-1'])
})
})