@ai-universe/receipt-utils

TypeScript helpers for issuing and verifying signed receipts using jose. The library prefers asymmetric Ed25519/ES256 keys, publishes JWKS documents for verifiers, and enforces freshness/field validation when receipts are checked.

Features

• 🔐 Compact JWS receipts with kid headers for JWKS-based verification
• 🗝️ Ed25519 key generation and JWK/JWKS exports for publishing at .well-known/jwks.json
• ✅ Optional freshness, nonce, request ID, and body-hash checks during verification
• 🧩 Typed receipt payloads that match the suggested server response pattern

Usage

Installation

From the repository root, install dependencies and build the package:

cd shared-libs/packages/receipt-utils
npm install
npm run build

Issue a receipt

import { generateEd25519KeyPair, signReceipt } from '@ai-universe/receipt-utils';

const { privateKey, jwks } = await generateEd25519KeyPair('receipt-key');

const receiptJws = await signReceipt(
  {
    req_id: 'uuid',
    uid: 'DLJwXoPZSQUzlb6JQHFOmi0HZWB2',
    op: 'secondOpinion.ask',
    models: [{ id: 'gpt-4o', tokens: 17551, cost: 0.093225 }],
    hash: 'sha256:<hex of response body>',
    nonce: 'client-supplied'
  },
  privateKey,
  { kid: 'receipt-key', alg: 'EdDSA' }
);

Verify a receipt

import { verifyReceipt } from '@ai-universe/receipt-utils';

const verification = await verifyReceipt(receiptJws, jwks, {
  expectedKid: 'receipt-key',
  expectedAlg: 'EdDSA',
  expectedReqId: 'uuid',
  expectedNonce: 'client-supplied',
  expectedHash: 'sha256:<hex of response body>',
  // Default freshness window is 5 minutes with 10 seconds of future skew allowance
});

console.log(verification.payload.ts); // ISO timestamp captured at signing time

Publish the jwks from generateEd25519KeyPair (or createPublicJwks) at an endpoint such as /\.well-known/jwks.json so clients can resolve the kid used in the JWS header.