feat(fingerprint): support caller-supplied fingerprint ID via x-fingerprint-id header

[ShankarSinghC]

Add an optional x-fingerprint-id request header to POST /data/fingerprint.

Behaviour:

• Header absent, hash not found -> generate ID, insert, return (existing flow unchanged)
• Header absent, hash found -> return stored ID
• Header present (valid), hash not found -> insert using caller-supplied ID, return it
• Header present (valid), hash found -> return stored ID, header ignored
• Header present (invalid) -> 422 ValidationError before any DB call

Header format: exactly 20 alphanumeric characters (0-9 a-z A-Z).

Test cases

Scenario A — hash not found, no header (server generates ID)

curl -X POST http://localhost:3000/data/fingerprint \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: public" \
  -d '{"data":"4111111111111111","key":"mysecretkey"}'

Response 200 OK

{"fingerprint_id":"DxgSyhrG6RTnCUZmcLky"}

The server generated and stored a fresh 20-char ID for this (data, key) pair.

---

Scenario B — hash not found, caller supplies ID

curl -X POST http://localhost:3000/data/fingerprint \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: public" \
  -H "x-fingerprint-id: MyCustomId0123456789" \
  -d '{"data":"5500005555555559","key":"mysecretkey"}'

Response 200 OK

{"fingerprint_id":"MyCustomId0123456789"}

The record was inserted using the caller-supplied ID.

---

Scenario C — hash already exists, no header (returns stored ID)

Same request as Scenario A:

curl -X POST http://localhost:3000/data/fingerprint \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: public" \
  -d '{"data":"4111111111111111","key":"mysecretkey"}'

Response 200 OK

{"fingerprint_id":"DxgSyhrG6RTnCUZmcLky"}

Hash was found; the originally stored ID is returned and nothing is inserted.

---

Scenario D — hash already exists, header present (header ignored)

curl -X POST http://localhost:3000/data/fingerprint \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: public" \
  -H "x-fingerprint-id: SomeOtherId123456789" \
  -d '{"data":"4111111111111111","key":"mysecretkey"}'

Response 200 OK

{"fingerprint_id":"DxgSyhrG6RTnCUZmcLky"}

The x-fingerprint-id header is ignored because the hash already has a stored record.

---

Scenario E — invalid header value

Too short — TooShort123456789 (17 chars)

curl -X POST http://localhost:3000/data/fingerprint \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: public" \
  -H "x-fingerprint-id: TooShort123456789" \
  -d '{"data":"4111111111111111","key":"mysecretkey"}'

Response

{"code":"TE_03","message":"Failed while validation: x-fingerprint-id must be exactly 20 alphanumeric characters","data":null}

Non-alphanumeric characters — bad-id-val-here12345 (20 chars, contains -)

curl -X POST http://localhost:3000/data/fingerprint \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: public" \
  -H "x-fingerprint-id: bad-id-val-here12345" \
  -d '{"data":"4111111111111111","key":"mysecretkey"}'

Response

{"code":"TE_03","message":"Failed while validation: x-fingerprint-id must be exactly 20 alphanumeric characters","data":null}