Hallpass TypeScript SDK

Agent key material, JWT signing, message proofs, and a typed API client for Hallpass.

Install

npm install @hallpass/sdk

Quick start

import {
  createClient,
  createMessageProofBundle,
  loadAgentKeyMaterial,
  verifyMessageBundle,
} from '@hallpass/sdk';

const client = createClient({ baseUrl: 'https://hallpass.org/api/v1' });
const keyMaterial = await loadAgentKeyMaterial();

const bundle = createMessageProofBundle({
  principalUsername: 'alice',
  body: 'Invoice #1234 approved',
  authorLabel: 'Billing Agent',
  keyMaterial,
});

const { data } = await verifyMessageBundle({ client, body: bundle });
console.log(data.overall_decision); // "verified"

API

Key material

• generateAgentKeyMaterial() — Generates an ECDSA P-256 key pair, DID, verification method, and key fingerprint.
• loadAgentKeyMaterial() — Loads key material from HALLPASS_AGENT_KEY (JSON), HALLPASS_AGENT_KEY_FILE (path), or agent-key.json.
• didJwk(publicJwk) — Derives a did:jwk from a public JWK.
• verificationMethodForDid(did) — Returns the #0 verification method for a DID.
• fingerprintPublicJwk(publicJwk) — SHA-256 hex fingerprint of a public JWK.

JWT

• signCompactJwt(payload, privateJwk, header?) — Signs a compact JWT with ES256.
• verifyCompactJwt(jwt, publicJwk) — Verifies a compact JWT signature and returns { valid, payload, header }.
• decodeCompactJwt(jwt) — Decodes a JWT without signature verification.

Messages

• createMessageProofBundle({ principalUsername, body, authorLabel, keyMaterial }) — Creates a signed message proof bundle.
• verifyMessageProofBundle(bundle) — Locally verifies a bundle's signature and key consistency.

Challenges

• createAgentChallengeResponse({ challenge, keyMaterial }) — Signs a challenge token to prove key possession.

Delegation

• createDelegationJwt(payload, privateJwk) — Signs a delegation JWT for self-managed key mode.

HTTP client

• createClient({ baseUrl }) — Returns a typed API client generated from the OpenAPI spec.

Environment variables

| Variable | Description | |---|---| | HALLPASS_AGENT_KEY | Agent key material as JSON | | HALLPASS_AGENT_KEY_FILE | Path to agent key material file |

License

MIT