passport-transparency

List

List grants issued by the authenticated passport holder.

// List active grants
const { data } = await client.passport.grants.list({ status: 'active' });

// List all capability grants
const { data } = await client.passport.grants.list({ kind: 'capability' });

Get

Retrieve a single grant with full scopes, constraints, and last_used_at.

Revoke

Revoke a grant immediately. For delegation grants: writes to delegation_grants.status = 'revoked'. For capability grants: sets revoked_at timestamp. Both cases log a 'grant.revoked' activity event.

await client.passport.grants.revoke('dg_abc123', { reason: 'no longer needed' });

Narrow

Narrow the scopes on an existing delegation grant. New scopes must be a strict subset of the existing scopes — narrowing cannot expand authority.

// Remove write:calendar, keep read:calendar
await client.passport.grants.narrow('dg_abc123', {
  scopes: ['read:calendar']
});

Pause

Pause a grant temporarily. The grant remains valid but will be rejected on any usage attempt until unpaused. Prefer pause over revoke when you want to restore access later without re-granting.

await client.passportTransparency.grants.pause('dg_abc123');

Unpause

Resume a previously paused grant.

await client.passportTransparency.grants.unpause('dg_abc123');

Expire

Shorten the expiry of a grant. The new expiry must be earlier than the current expiry — this operation cannot extend authority.

await client.passportTransparency.grants.expire('dg_abc123', {
  expires_at: '2026-04-01T00:00:00Z'
});

List

List activity events for the authenticated passport holder.

// Activity this week
const { data } = await client.passport.activity.list({
  from: '2026-02-20T00:00:00Z',
  to: '2026-02-27T23:59:59Z',
});

// High-risk events only
const { data } = await client.passport.activity.list({
  risk_level: 'high',
});

// Blocked actions
const { data } = await client.passport.activity.list({
  event_type: 'action.blocked,escalation.triggered',
});

Get Receipt

Retrieve a single activity event with full proof linkage (receipt). The receipt includes proofs.provenance_ref, proofs.attestation_ref, and proofs.ledger_anchor_ref for cryptographic verification. Never exposes raw vault contents.

Proof

Fetch the Merkle proof for an activity event from the distributed ledger. Returns a LedgerProof that can be used to independently verify the event without trusting HUMΛN's servers. The caller can recompute the Merkle root from proof.leaf + proof.siblings + proof.path and compare it to proof.root. Three response cases: - 200 → proof returned, event is anchored and verifiable - 404 → event not yet anchored (batches run every 10 minutes) - 503 → ledger temporarily unavailable (event data is still valid) Canon: kb/13_foundational_principles.md P7

const proof = await client.passportTransparency.activity.proof('evt_abc123');
// proof.leaf, proof.root, proof.siblings, proof.path

Types

interface GrantView {
  /** The subject (passport holder) who issued this grant */
  granter_did: string;
  /** Agent, service, or human who holds this grant */
  delegatee_did: string;
  /** Capability scopes granted */
  scopes: string[];
  /** Maximum risk tier this grant permits */
  risk_ceiling: RiskCeiling;
  /** Operational constraints (time window, max actions, purpose tags, etc.) */
  constraints: Record<string, unknown>;
  /** Updated each time an agent invokes under this delegation */
  last_used_at: string | null;
  /** Optional Merkle anchor proof reference */
  ledger_anchor_ref: string | null;
}

interface ActivityProofs {
  /** provenance_graphs.task_id or node id */
  provenance_ref: string | null;
  /** Merkle attestation reference */
  attestation_ref: string | null;
  /** Ledger anchor proof hash */
  ledger_anchor_ref: string | null;
}

interface ActivityFeedItem {
  /** The minimum-floor outcome — always visible */
  outcome: ActivityOutcome;
  /** The minimum-floor risk level — always visible */
  risk_level: ActivityRiskLevel;
  /** Category-level data access (e.g. 'calendar_event') — org may gate */
  data_categories: string[] | null;
  /** User-readable reason code — org may gate */
  purpose: string | null;
  /** Cryptographic proof references */
  proofs: ActivityProofs;
}

interface LedgerProof {
  /** SHA-256 hash of the event content (the leaf node) */
  leaf: string;
  /** Merkle root of the batch this event was anchored in */
  root: string;
  /** Sibling hashes required to recompute the root from the leaf */
  siblings: string[];
  /** Whether each sibling is left or right of the current node */
  path: ('left' | 'right')[];
}