SigID JavaScript Agent SDK¶

Agent workspace setup, Ed25519 authentication, and human delegation for Node.js 22+ and Bun. This is an importable JavaScript library: it has no native executable, postinstall script, shell, or filesystem dependency. It uses Fetch, Web Crypto for Ed25519, and the runtime's node:crypto SHA-256 implementation.

The package is implemented in this repository; its first npm publication is pending. Once published, install with npm install @sigid/agent or bun add @sigid/agent. A workspace checkout can import it after bun run --cwd sdks/js/agent build.

Retain an identity first¶

The host owns key storage. Save the key before making registration requests: bootstrap can register an agent before a later provisioning or network failure. Never generate a replacement key automatically after such a failure.

import { AgentClient, AgentIdentity } from "@sigid/agent";

// First use: save key.keyPair in a host store that supports CryptoKeys.
const key = await AgentIdentity.generate(); // private key is non-extractable
await keyStore.create("sigid-agent", key.keyPair);

// Subsequent runs: restore the SAME identity.
const identity = await AgentIdentity.fromKeyPair(await keyStore.read("sigid-agent"));
const agent = new AgentClient({ identity, origin: "https://auth.sigid.org" });

keyStore is supplied by your environment; create should reject an existing name. For secret stores that accept serialized values, explicitly generate with { extractable: true }, save await key.exportPrivateJwk() securely, and restore with AgentIdentity.fromJwk(jwk). JWK exports contain the private key. The SDK never chooses plaintext disk storage, logs secrets, or uploads private keys.

Bootstrap a workspace¶

const workspace = await agent.bootstrapWorkspace({
  name: "my-agent",
  redirectUris: ["https://my-app.example/auth/callback"],
  framework: "nextjs", // generic, nextjs, react, or svelte
  signal: AbortSignal.timeout(10 * 60 * 1000),
});

This discovers the real control-plane UUID, signs the registration proof, solves proof-of-work, respects the minimum duration, and submits completion once. The full response includes organization, environment, application, separate control-plane and tenant tokens, and once-only fixture credentials. Store it securely; do not print the response into agent prompts or logs.

On a completion failure, authenticate with the retained identity and inspect existing resources using the documented API before resuming provisioning. The SDK does not replay completion or silently create another workspace.

Authenticate an existing agent¶

const binding = await agent.discoverBootstrap();
const direct = await agent.authenticate({
  tenantId: binding.tenant_id,
  audience: binding.issuer,
  scope: "openid profile org:read",
});

For other environments, supply their real tenant UUID and the expected challenge audience using audience if it differs from the API origin. The SDK verifies the response's audience, client ID, scope hash, key fingerprint, algorithm, and timestamps before signing. It returns tokens without creating a global cache.

Request human delegation¶

const approval = await agent.requestDelegation({
  accessToken: direct.access_token,
  audience: "sigid", // choose the actual target API audience
  scope: "applications:manage", // choose only the permissions needed
});

// Deliver these fields to the human through your host's UI:
await showApprovalLink(approval.verificationUri, approval.userCode);

const delegated = await approval.waitForApproval({
  signal: AbortSignal.timeout(5 * 60 * 1000),
});

showApprovalLink is your host integration, not an SDK function. The human must complete the real SigID approval page with the required assurance. Polling respects authorization_pending, slow_down, Retry-Interval, Retry-After, denial, and expiration. Concurrent waits on the same request are rejected. Unexpected transport failures stop polling because an approved code may already have been consumed. Delegated tokens never overwrite direct tokens.

Runtime and error behavior¶

• Configure a HTTPS origin; HTTP is accepted only for loopback development.
• HTTP redirects are rejected. Credentials stay on the configured origin.
• The request timeout defaults to 30 seconds; response bodies are capped at 1 MiB.
• Proof-of-work accepts the existing sha256d algorithm and 8–24 difficulty bits, yields to the event loop, and has an expiry and a configurable budget.
• AgentSdkError exposes code, HTTP status, requestId, and rate-limit retry timing without copying potentially sensitive response bodies.
• fetch can be injected for host networking policies or testing; it must implement Fetch redirect and abort semantics.
• This package requires JavaScript execution. HTTP-only agents need a host capable of key operations or a separately designed authentication flow.
• This implements SigID's existing protocols, not ID-JAG or WorkOS's auth.md registration profile.

See SigID agent documentation.