AbadgeAgentClient

AbadgeAgentClient is the agent runtime client. It owns the bearer credential, runs the keypair challenge / session exchange, refreshes tokens before they expire, and exposes the access.* methods.

Construction

Agents authenticate only via an Ed25519 keypair. The client runs the challenge / session exchange itself; there is no constructor option for a pre-minted session token.

import { AbadgeAgentClient } from "@abadge/sdk";

const agent = new AbadgeAgentClient({
  apiUrl: "https://api.abadge.io",
  agentId: "agent_...",
  privateKey: ed25519PrivateKey,   // CryptoKey, JWK object, or JSON-serialized JWK string
});

string

required

string

required

CryptoKey | Ed25519PrivateKeyJwk | string

required

Ed25519 private key. Strings are parsed as JWK JSON at construction; malformed keys fail fast.

(error, attempt) => void

Callback fired on each background refresh failure. After the bounded retry budget is exhausted, the client flips to sessionExpired and outgoing calls reject with SESSION_REFRESH_FAILED.

Lifecycle

You must connect() before making requests:

await agent.connect();

// ... use the client ...

agent.disconnect();

connect() performs the Ed25519 challenge / exchange and starts a background refresher that re-exchanges the session when fewer than 2 minutes of TTL remain. The refresh timer is .unref()’d so it does not keep the event loop alive on its own. disconnect() stops the refresher.

Enrollment

The first time a keypair agent runs, it can use its bootstrap token to enroll:

agent.enroll(bootstrapToken: string, publicKey: string);

After enrollment, future connect() calls use the keypair session exchange.

Access methods

These enforce the capability matrix and audit every attempt.

`access.read(itemId, opts?)`

Read an item. Server-managed items return the decrypted payload; ZK items return the encrypted envelope for local daemon decryption. Requires: the read capability (ZK items resolve locally only). Returns a discriminated union on storageMode:

const result = await agent.access.read(itemId);
if (result.storageMode === "server_managed") {
  const value = result.payload.fields.password;
} else {
  // ZK envelope: decrypt client-side via daemon
  const { encryptedItemKey, ciphertext, cryptoVersion } = result;
}

// Specific field for a multi-field server-managed item
const result = await agent.access.read(itemId, { field: "password" });
if (result.storageMode !== "server_managed") throw new Error("Expected server_managed");
const value = result.payload.fields.password;

`access.use(target, opts)`

Mint a short-lived mount handle for local injection (env var or temp file). The daemon redeems the handle for the actual material. Requires: the use capability. Local agent only.

// Single item
const { mountId } = await agent.access.use(
  { itemId },
  { delivery: "env", field: "password" },
);

// All items in a profile the agent has use grants on
const handles = await agent.access.use(
  { profileId: "prof_..." },
  { delivery: "env" },
);

Other methods

agent.getCurrentAgent();                // Get this agent's own record ({ agent })
agent.listItems();                      // Metadata only — scoped to items with a grant
agent.getItem(itemId);                  // Full item record (ciphertext for ZK)
agent.getAudit(filters?);               // Structured audit listing

Background refresh

Keypair clients schedule a background refresh at T-2 minutes before the current abs_... session expires. If a refresh fails, the SDK retries with the bounded-exponential schedule 30s → 60s → 120s → 240s → 300s. After all five attempts fail, the client flips to sessionExpired and subsequent requests reject with SESSION_REFRESH_FAILED. Recover by calling disconnect() and connect() again, or instantiate a fresh client:

try {
  const result = await agent.access.read(itemId);
} catch (err) {
  if (err instanceof AbadgeApiError && err.code === "SESSION_REFRESH_FAILED") {
    agent.disconnect();
    await agent.connect();
  }
  throw err;
}

Example

import { AbadgeAgentClient } from "@abadge/sdk";

const agent = new AbadgeAgentClient({
  apiUrl: "https://api.abadge.io",
  agentId: "agent_...",
  privateKey: ed25519PrivateKey,
});

await agent.connect();

const result = await agent.access.read(itemId);
if (result.storageMode !== "server_managed") throw new Error("Expected server_managed item");
const token = result.payload.fields.token as string;

// Use the token...

agent.disconnect();

Field delivery

The field option on access.read and access.use selects a specific named field from a multi-field item. Resolution is centralized in resolveFieldValue from @abadge/core/secret-delivery (re-exported from the SDK).

Case	Result
Single-field item, `field` omitted	The field is returned
Multi-field item, `field` omitted	`MULTI_FIELD_ITEM` with `meta.availableFields`
`field` specified but missing	`FIELD_NOT_FOUND` with `meta.availableFields`

See Field delivery for details.

Errors

Wrapped in AbadgeApiError. See Error handling.

Introduction

Organizations

Members & invites

API keys

Profiles

Items

Agents

Agent sessions

Permissions

Access

Audit

System

SDK

AbadgeAgentClient

Construction

Lifecycle

Enrollment

Access methods

`access.read(itemId, opts?)`

`access.use(target, opts)`

Other methods

Background refresh

Example

Field delivery

Errors

​Construction

​Lifecycle

​Enrollment

​Access methods

​access.read(itemId, opts?)

​access.use(target, opts)

​Other methods

​Background refresh

​Example

​Field delivery

​Errors

Construction

Lifecycle

Enrollment

Access methods

`access.read(itemId, opts?)`

`access.use(target, opts)`

Other methods

Background refresh

Example

Field delivery

Errors