Receipts

Every create, reveal and denial (a wrong passphrase or a wrong audience proof) returns a receipt, and so do an adoption and a policy change: a compact JWS signed by ckrets. A denial's receipt is in the problem body's receipt field (on the 401 or the 403). A revocation answers 204 with no body; status shows it. Webhook deliveries are signed the same way. A receipt lets the sender prove what was handed over, to whom and when, and you can check it without ckrets being up. The API is live in beta (0.9.0).

#Format

Header: {"alg":"ES256","kid":"<key id>","typ":"ckrets-receipt+jwt"}. Payload claims:

Scroll the table sideways.

#Which claims each receipt carries

Every receipt has iss, ver, iat, jti, typ and ce. Then, for the agent API:

Scroll the table sideways.

Puzzle, adopt and policy receipts add app. A receipt is readable by whoever holds it: cre, rcp, aud and pur name the parties and say why, so keep purpose free of anything you would not show the recipient or a third party.

#Worked vectors

dig: with digestKey = AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8 (the bytes 0 to 31) and value = LAB_7f3a0c9d2e, dig = hmac-sha256:rF0rV51ShGDAmgesKvcAWTcrJyiuz-huLCoCoq7NF1Y.

pol: a create with ttl 15m, reveals 1, no passphrase and audience {"type":"key","id":"key_7TQM4C8R2D5F6G7H8J9K0M1N2P"} hashes this string (keys sorted, no spaces, the audience as a JSON string):

{"audience":"{\"type\":\"key\",\"id\":\"key_7TQM4C8R2D5F6G7H8J9K0M1N2P\"}","passphrase":false,"reveals":1,"ttl":900}

so pol = sha256:30b0d205177533d6a8ba38728e5ca64360f92935fdf6ddf66144369952fe3a2f. With no audience, a passphrase and ttl 1h: {"audience":null,"passphrase":true,"reveals":1,"ttl":3600}, pol = sha256:9f06debd1b664a492876d0cab8640896c7f4877e6447639cd2defa4555600d57.

#Verifying one

1. Fetch <origin>/.well-known/jwks.json once and keep it, where <origin> is the receipt's expected iss (https://ckrets.ai in production; a staging or lab deployment serves its own keys). Pick the key by the receipt's kid, never by its place in the list. In v1 each deployment signs with one key and no rotation is scheduled; if a key is ever retired, it stays listed for 13 months, so an old receipt still finds its kid.
2. Find the key whose kid matches the receipt header, verify the ES256 signature, check iss.
3. Check tok against the token you hold. If you hold the value and its digestKey (the creator gets it at create, the recipient with each reveal), recompute dig.

import { compactVerify, createLocalJWKSet } from "jose";
const jwks = createLocalJWKSet(await (await fetch("https://ckrets.ai/.well-known/jwks.json")).json());
const { payload } = await compactVerify(receipt, jwks);
const claims = JSON.parse(new TextDecoder().decode(payload));

import json, jwt                      # pip install "pyjwt[crypto]"
jwks = jwt.PyJWKSet.from_json(open("ckrets-jwks.json").read())
kid = jwt.get_unverified_header(receipt)["kid"]
claims = jwt.decode(receipt, key=jwks[kid].key, algorithms=["ES256"], options={"verify_aud": False, "verify_exp": False})

aud is an object and exp is the secret's expiry, so turn off a JWT library's audience and expiry checks (as the Python lines do; compactVerify checks no claims). POST /v1/receipts/verify does the same check server-side as a convenience and always answers 200: {valid: true, claims}, or {valid: false} for a tampered, malformed or missing receipt. Prefer verifying yourself.

#Why the digest is keyed

An unkeyed hash of a short value (a six-digit code, a common password, "hello") is reversed by lookup, so dig is an HMAC under a per-secret digestKey that only the creator and the recipient receive. A receipt shown to anyone else says which secret and when, not what it held.

#What a receipt proves, and what it does not

It proves ckrets recorded that event, at that time, for that token digest and policy. It does not prove what the recipient did with the value afterwards. A reveal receipt with an audience proves the named party collected; a reveal receipt without one proves only that someone holding the URL did.