Privacy-Preserving Lending Voucher

POST /api/lending/credential/issue

Plaintext JSON for the bound voucher index fields, opaque ciphertext for the encrypted financial history the integrator produced on-device. One voucher per signature; replay within the validity window re-issues the same voucher deterministically.

Time-bound canonicalization

The issuer signs a canonical UTF-8 string built from a structured object whose keys are sorted alphabetically and rendered with no whitespace. The signed bytes cover voucher_id, user_pubkey, claim_id, ciphertext_hash, the issuer name, issued_at, valid_until, and validity_window_seconds. The signed voucher_id — not the encrypted financial claim — is the audit point: a regulator confirms issuance without ever holding the borrower's plaintext history.

Validity bounds

The time-bounded voucher lifetime is clamped to 60…86400s. The same shape also accepts an absolute ISO-8601 valid_until; the two are mutually exclusive.

Canonicalization rule

JSON.stringify(obj) with keys sorted alphabetically and no whitespace.

Deterministic voucher_id

Issuer identity

The signing key is server-owned. When LENDING_ISSUER_PRIVATE_KEY is unset the endpoint still works but issues vouchers with an ephemeral key (mock_key: true); those vouchers will not verify across restarts. The fingerprint below is the 16-character SPKI body prefix a visitor can compare against the issuer detail on /lending/applications/<voucher_id> to confirm the issuance event and the lookup describe the same signing identity.

-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEA1S5zx5DeS9xUSSBnME3/cxPFhCbPMgpMc5WFrXcaWQ4=
-----END PUBLIC KEY-----

Required fields

All fields are required, except where noted. Any missing or invalid field produces a 400 with the offending fields listed in errors.

JSON body the integrator posts

The values below come straight from the live contract — what the integrator sends and what the server signs.

{
  "user_pubkey": "pk_loan_4f7e2c1a",
  "claim_id": "clm_01J9Q",
  "ciphertext": "0x9f3a8c1d_demo_ciphertext_octets",
  "validity_seconds": 3600
}

curl invocation

One command — sends the example envelope to the live issuer. The host is whatever the request landed on; the path is the same everywhere.

curl -X POST https://automa-labs-ai.polsia.app/api/lending/credential/issue \
  -H "Content-Type: application/json" \
  -d '{
  "user_pubkey": "pk_loan_4f7e2c1a",
  "claim_id": "clm_01J9Q",
  "ciphertext": "0x9f3a8c1d_demo_ciphertext_octets",
  "validity_seconds": 3600
}'

What the server can give back

Every terminal status the integrator needs to handle.

The signed voucher, not the encrypted claim, is the audit point.

A borrower produces an encrypted financial-history claim on-device, the issuer signs a deterministic time-bounded voucher over the claim hash, and a lender settles against the voucher without ever receiving plaintext financials — the /lending flow end-to-end. Apply at /lending/apply, track any vch_<hex> voucher at /lending/applications/<voucher_id>, and drop the curl above into your underwriting pipeline to issue one signer-on-behalf flow. Two distinct borrowers always produce two distinct voucher IDs even when the ciphertext itself stays opaque: the vch_<sha256[:32]> namespace is portable, the replay window is floored by validity_seconds, and the signing identity is server-owned — the issuance event is the audit point, never the encrypted financial history.

What happens to a successful voucher

Every accepted voucher is written to the lending_credentials table, keyed UNIQUE on voucher_id, and indexed on user_pubkey and valid_until. The same contract — including the example envelope and the response shapes — is published as plain JSON at https://automa-labs-ai.polsia.app/api/lending/credential/issue, so an integrator can pull the spec straight off the live endpoint rather than caching this page.