@nordax/hap

Human Authorization Protocol — Verification SDK

Parse, validate, and verify W3C VC 2.0 agent authorization credentials.

Specification · npm · Nordax AI

Overview

@nordax/hap is the official verification SDK for the Human Authorization Protocol (HAP). It lets any application — AI agent, API gateway, or backend service — verify that an agent has been authorized by a real human before acting on their behalf.

• Zero runtime dependencies — pure TypeScript, Node.js built-ins only
• ESM-only — tree-shakeable, modern module format
• Verification only — no issuance logic, no secrets, no server dependencies

Install

npm install @nordax/hap

pnpm add @nordax/hap

yarn add @nordax/hap

Quick Start

Verify a credential

import { verifyHAPCredential } from "@nordax/hap";

const result = await verifyHAPCredential(credential);

if (result.valid) {
  console.log("Agent authorized:", result.credential?.credentialSubject.agent_id);
  console.log("Actions:", result.credential?.credentialSubject.authorization_scope.actions);
} else {
  console.log("Verification failed:", result.status);
  console.log("Errors:", result.errors);
}

Parse and inspect

import { parseHAPCredential, getAuthorizationScope, isExpired, isActive } from "@nordax/hap";

const credential = parseHAPCredential(jsonFromApi);

const scope = getAuthorizationScope(credential);
console.log("Permitted actions:", scope.actions);
console.log("Spending limit:", scope.spendingLimits?.maxPerTransaction);

console.log("Expired:", isExpired(credential));
console.log("Active:", isActive(credential));

Offline verification

const result = await verifyHAPCredential(credential, {
  checkStatus: false, // skip the status endpoint — expiry + structure only
});

Custom fetch & timeout

const result = await verifyHAPCredential(credential, {
  fetch: myCustomFetch,
  statusTimeoutMs: 3000,
});

API Reference

verifyHAPCredential(credential, options?)

Full verification pipeline:

| Step | Check | Authoritative? | |------|-------|:--------------:| | 1 | Structure — conforms to HAP credential schema | Yes | | 2 | Expiration — expirationDate vs current UTC | Yes | | 3 | Status — real-time fetch of credentialStatus.id endpoint | Yes |

Returns HAPVerifyResult:

interface HAPVerifyResult {
  valid: boolean;
  status: "active" | "expired" | "revoked" | "suspended" | "not_found" | "invalid_signature";
  credential?: HAPCredential;
  authId?: string;
  verifiedAt?: string;
  errors?: string[];
}

Options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | checkStatus | boolean | true | Fetch the status endpoint for revocation check | | fetch | typeof fetch | globalThis.fetch | Custom fetch implementation | | statusTimeoutMs | number | 5000 | Timeout for the status endpoint request |

parseHAPCredential(input)

Validates structural shape of an HAP credential. Throws on invalid input. No network calls.

getAuthorizationScope(credential)

Extracts the authorization_scope from a parsed credential.

isExpired(credential)

Returns true if the credential is past its expirationDate.

isActive(credential)

Returns true if current time is between issuanceDate and expirationDate. Does not check revocation — use verifyHAPCredential for a full check.

Types

All types are exported for use in your own type definitions:

import type {
  HAPCredential,        // Full W3C VC 2.0 credential structure
  HAPScope,             // Authorization scope (actions, categories, limits, regions)
  HAPVerifyResult,      // Verification result
  HAPVerifyOptions,     // Options for verifyHAPCredential
  HAPStatusResponse,    // Status endpoint response shape
  HAPStatus,            // "active" | "expired" | "revoked" | "suspended" | ...
  AgentType,            // "ai_assistant" | "api_client" | "automation" | "service_agent"
  VerificationLevel,    // "basic" | "enhanced" | "full"
} from "@nordax/hap";

What this SDK does NOT include

This SDK is verification only. The following are proprietary to Nordax AI and are not included:

| Not included | Why | |-------------|-----| | Credential issuance | Server-side only — requires Ed25519 keys | | Database access | No ORM or storage dependencies | | Key management | Signing keys never leave the issuer | | Authentication | No Clerk, no secrets, no env vars |

Roadmap

| Version | Feature | Status | |---------|---------|--------| | v0.1 | Structure validation, expiration check, status endpoint | ✅ Released | | v0.2 | Ed25519 signature verification with public key resolver | Planned | | v0.3 | Credential presentation helpers, scope matching utilities | Planned |

Specification

Read the full HAP specification at nordax.ai/protocol/hap

License

Apache-2.0 — Copyright 2026 Northern Axis, LLC

Copyright 2026 Northern Axis, LLC DBA Nordax Digital.