SDK Reference

Installation

npm install @humanauth/sdk

@humanauth/harp is no longer needed. Protocol types and crypto primitives are included in the SDK.

HumanAuthClient

The primary class for sending requests to humans and receiving responses.

Constructor

import { HumanAuthClient } from "@humanauth/sdk";

const client = HumanAuthClient.fromPairing(pairing);

Creates a client from a saved Pairing. The client handles encryption, relay communication, signature verification, and polling.

authorize(options)

Request binary approval. Blocks by default until the human responds or TTL expires.

const result = await client.authorize({
  action: "deploy_production",
  description: "Deploy API v2.1.0 to production",
  severity: "high",
  parameters: { service: "api", version: "2.1.0" },
  reasoning: "New features ready, all tests passing",
  ttl: 300,
});

if (result.decision === "approved") {
  await deploy();
} else {
  console.log(`Denied: ${result.reason}`);
}

AuthorizeOptions:

Field	Type	Required	Default	Description
action	string	Yes	—	Action identifier
description	string	Yes	—	Human-readable description
severity	Severity	No	”medium”	low, medium, high, critical
assurance	Assurance	No	”biometric”	tap, biometric, elevated
parameters	Record<string, unknown>	No	—	Action parameters for context
reasoning	string	No	—	Why the agent wants this
context	Record<string, unknown>	No	—	Cross-protocol references
ttl	number	No	300	Timeout in seconds (max 86400)
blocking	boolean	No	true	If false, returns request_id immediately
callbackUrl	string	No	—	Webhook URL for non-blocking
callbackSecret	string	No	—	HMAC secret for webhook

AuthorizeResult:

interface AuthorizeResult {
  decision: "approved" | "denied";
  reason?: string;
}

collect(options)

Request structured data input. Blocks by default.

const result = await client.collect({
  action: "deployment_config",
  description: "Please configure the deployment",
  schema: {
    fields: [
      {
        name: "target",
        type: "select",
        label: "Deploy Target",
        required: true,
        options: [
          { value: "staging", label: "Staging" },
          { value: "production", label: "Production" },
        ],
      },
      {
        name: "notify_team",
        type: "checkbox",
        label: "Notify team on Slack",
        default: true,
      },
    ],
  },
  severity: "medium",
  ttl: 600,
});

console.log(result.form_data);
// { target: "staging", notify_team: true }

CollectOptions:

Field	Type	Required	Default	Description
action	string	Yes	—	Action identifier
description	string	Yes	—	What data you need and why
schema	CollectSchema	Yes	—	Form definition (max 20 fields)
severity	Severity	No	”medium”	How sensitive is this data
assurance	Assurance	No	”biometric”	Authentication level
parameters	Record<string, unknown>	No	—	Additional context
reasoning	string	No	—	Why you need this data
context	Record<string, unknown>	No	—	Cross-protocol references
ttl	number	No	600	Timeout in seconds
blocking	boolean	No	true	If false, returns request_id immediately
callbackUrl	string	No	—	Webhook URL
callbackSecret	string	No	—	HMAC secret

CollectResult:

interface CollectResult {
  form_data: Record<string, unknown>;
  reason?: string;
}

CollectSchema:

interface CollectSchema {
  fields: CollectField[];    // max 20 fields
  submitLabel?: string;      // custom submit button text
}

interface CollectField {
  name: string;
  type: "select" | "multiselect" | "checkbox" | "number" | "datetime";
  label: string;
  description?: string;
  required?: boolean;
  default?: unknown;
  options?: { value: string; label: string }[];  // for select/multiselect
  min?: number;           // for number
  max?: number;           // for number
  step?: number;          // for number
  minDate?: string;       // for datetime (ISO 8601)
  maxDate?: string;       // for datetime (ISO 8601)
}

inform(options)

Send a notification. Always fire-and-forget — returns after relay acknowledges receipt.

await client.inform({
  action: "deploy_complete",
  description: "Deployment to staging completed successfully",
  severity: "low",
  category: "result",
});

InformOptions:

Field	Type	Required	Default	Description
action	string	Yes	—	Action name or context
description	string	Yes	—	Notification message
severity	Severity	No	”low”	Urgency level
category	string	No	”general”	escalation, result, status, error, general
parameters	Record<string, unknown>	No	—	Additional context
reasoning	string	No	—	Why you’re sending this
callbackUrl	string	No	—	Webhook fires on “viewed” state
callbackSecret	string	No	—	HMAC secret

Returns Promise<void>.

cancel(requestId)

Cancel a pending request.

await client.cancel("req_abc123");

Only works when the request is in pending state. Throws if already delivered/decided.

status(requestId)

Check the current status of a request.

const status = await client.status("req_abc123");
console.log(status);
// { request_id: "req_abc123", status: "viewed", created_at: 1712345678, delivered_at: 1712345680, viewed_at: 1712345690 }

RequestStatus:

interface RequestStatus {
  request_id: string;
  status: "pending" | "delivered" | "viewed" | "decided" | "expired" | "cancelled";
  created_at: number;
  delivered_at?: number;
  viewed_at?: number;
  decided_at?: number;
}

Types

Pairing

interface Pairing {
  pair_id: string;
  platform_id: string;
  platform_name: string;
  device_id: string;
  shared_secret: Uint8Array;
  encryption_key: Uint8Array;
  platform_auth_key: Uint8Array;
  app_auth_key: Uint8Array;
  signing_pub: Uint8Array;
  relay_url: string;
  paired_at: string;
}

Severity / Assurance

type Severity = "low" | "medium" | "high" | "critical";
type Assurance = "tap" | "biometric" | "elevated";

Pairing Management

loadPairing(pairId)

import { loadPairing } from "@humanauth/sdk";
const pairing = await loadPairing("pair_abc123");

listPairings()

import { listPairings } from "@humanauth/sdk";
const pairings = await listPairings();

Crypto Module

encrypt(key, plaintext)

import { encrypt } from "@humanauth/sdk";
const { nonce, ciphertext } = encrypt(encryptionKey, plaintextBytes);

decrypt(key, nonce, ciphertext)

import { decrypt } from "@humanauth/sdk";
const plaintext = decrypt(encryptionKey, nonce, ciphertext);

deriveSharedSecret(privateKey, publicKey)

import { deriveSharedSecret } from "@humanauth/sdk";
const sharedSecret = deriveSharedSecret(myPrivateKey, theirPublicKey);

deriveKeys(sharedSecret)

import { deriveKeys } from "@humanauth/sdk";
const { encryption_key, platform_auth_key, app_auth_key } = deriveKeys(sharedSecret);

Environment Variables

Variable	Default	Description
HARP_PAIRINGS_DIR	~/.harp/pairings	Directory for saved pairing files
HARP_AUDIT_DIR	~/.harp/audit	Directory for audit log files