@openagentid/sdk API

export declare const OpenAgent: { readonly configure: (config?: OpenAgentConfig) => OpenAgentRuntime; readonly runtime: () => OpenAgentRuntime; readonly createAgent: (input: CreateAgentInput) => Promise<OpenAgentInstance>; readonly loadAgent: (did: Did, skills?: readonly SkillId[]) => Promise<OpenAgentInstance>; readonly authenticate: (req: Request, options?: VerifyRequestOptions) => Promise<AuthContext>; };

export declare class OpenAgentRuntime {
  constructor(config?: OpenAgentConfig): OpenAgentRuntime;
  config(): Readonly<ResolvedOpenAgentConfig>;
  identity(): IdentityProvider;
  arsenal(): ArsenalClient;
  verification(): VerificationClient;
  createAgent(input: CreateAgentInput): Promise<OpenAgentInstance>;
  loadAgent(did: Did, skills?: readonly SkillId[]): Promise<OpenAgentInstance>;
  authenticate(req: Request, options?: VerifyRequestOptions): Promise<AuthContext>;
}

/** A live, fully-authenticated agent handle. */
export interface OpenAgentInstance {
    /** The agent's DID. */
    readonly did: Did;
    /** The raw OAS identity document. */
    readonly document: IdentityDocument;
    /** Skills policy bound to this agent. */
    skillsPolicy(): SkillsPolicy;
    /** Replace the agent's skills policy (immutable — returns a new instance). */
    withSkillsPolicy(policy: SkillsPolicy): OpenAgentInstance;
    /** Fetch a credential handle for `provider`. */
    credentialsFor(provider: string, scopes?: readonly string[]): Promise<CredentialHandle>;
    /** Underlying identity provider (escape hatch). */
    identity(): IdentityProvider;
}

/**
 * Global SDK configuration.
 *
 * All fields are optional; sensible defaults are applied by
 * {@link OpenAgent.configure}. The SDK works with zero configuration for
 * local development and test environments.
 */
export interface OpenAgentConfig {
    /** Override the default namespace (`l1fe`). */
    namespace?: string;
    /**
     * Transport endpoints. If omitted, the SDK assumes it is running in-process
     * with the underlying libraries (useful for tests) or that the wrapped
     * SDKs will read their own env vars.
     */
    endpoints?: {
        oasResolver?: string;
        arsenalBroker?: string;
        aegisVerifier?: string;
    };
    /**
     * Inject a custom `fetch`. Defaults to globalThis.fetch (native on Node 20+,
     * Bun, Deno, browsers, Workers).
     */
    fetch?: typeof fetch;
    /** Optional structured logger. */
    logger?: Logger;
    /** Override the abort timeout (ms) for HTTP calls. Default: 30000. */
    requestTimeoutMs?: number;
    /**
     * Pre-constructed subsystem clients (advanced). When provided, the SDK
     * uses them directly instead of constructing its own.
     */
    clients?: OpenAgentClients;
}

/**
 * Forward-declared clients for the three wrapped subsystems.
 *
 * Concrete interfaces live in the per-module files so that this config file
 * does not depend on internal implementation details.
 */
export interface OpenAgentClients {
    readonly identity?: unknown;
    readonly credentials?: unknown;
    readonly verification?: unknown;
}

/** Resolved configuration with all defaults applied. */
export interface ResolvedOpenAgentConfig {
    namespace: string;
    endpoints: {
        oasResolver?: string;
        arsenalBroker?: string;
        aegisVerifier?: string;
    };
    fetch: typeof fetch;
    logger: Logger;
    requestTimeoutMs: number;
    clients: OpenAgentClients;
}

export type CreateAgentInput = z.infer<typeof createAgentInputSchema>;

/** Logger interface — structured, dependency-free. */
export interface Logger {
    debug(msg: string, fields?: Record<string, unknown>): void;
    info(msg: string, fields?: Record<string, unknown>): void;
    warn(msg: string, fields?: Record<string, unknown>): void;
    error(msg: string, fields?: Record<string, unknown>): void;
}

export declare const resolveConfig: (config?: OpenAgentConfig) => ResolvedOpenAgentConfig;

export declare const silentLogger: Logger;

export declare const createAgentInputSchema: z.ZodObject<{ parent: z.ZodString; name: z.ZodString; scopes: z.ZodArray<z.ZodString>; namespace: z.ZodOptional<z.ZodString>; skills: z.ZodOptional<z.ZodArray<z.ZodString>>; metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>; }, z.core.$strict>;

export declare const didSchema: z.ZodString;

export declare const scopeSchema: z.ZodString;

export declare const providerSchema: z.ZodString;

export declare const DEFAULT_NAMESPACE: "l1fe";

export declare const DEFAULT_REQUEST_TIMEOUT_MS: 30000;

export declare const DID_REGEX: RegExp;

/** Fully qualified `did:oas` identifier. */
export type Did = string;

/** OAS identity document fragment — minimum fields needed by the SDK. */
export interface IdentityDocument {
    /** Canonical DID. */
    did: Did;
    /** Parent DID (lineage). */
    parent: Did;
    /** Multibase-encoded Ed25519 public key. */
    publicKeyMultibase: string;
    /** Entity kind — `agent`, `tool`, etc. */
    kind: string;
    /** Granted scopes. */
    scopes: readonly string[];
    /** ISO-8601 creation timestamp. */
    createdAt: string;
    /** Opaque metadata. */
    metadata?: Record<string, unknown>;
}

/**
 * The OAS identity facade. Concrete providers come from `@openagentid/oas-sdk`
 * (production) or from {@link StubIdentityProvider} (test / offline dev).
 */
export interface IdentityProvider {
    /** Create a new OAS identity descended from `input.parent`. */
    createAgentIdentity(input: CreateAgentInput): Promise<IdentityDocument>;
    /** Resolve an existing DID to its identity document. */
    resolve(did: Did): Promise<IdentityDocument>;
    /** Sign a challenge (e.g. from AEGIS) with the agent's private key. */
    signChallenge(did: Did, challenge: Uint8Array): Promise<SignedAssertion>;
    /** Return the public key for a DID (multibase). */
    publicKey(did: Did): Promise<string>;
}

/** Signed credential returned by the identity provider. */
export interface SignedAssertion {
    /** JWS / JWT / OAS assertion envelope (base64url). */
    token: string;
    /** Raw signature bytes (base64). */
    signature: string;
    /** DID of the signer. */
    signer: Did;
    /** Unix timestamp when the assertion was minted. */
    issuedAt: number;
    /** Unix timestamp after which the assertion is invalid. */
    expiresAt: number;
}

export declare const parseIdentityDocument: (raw: unknown) => IdentityDocument;

export declare const toIdentityProvider: (client: unknown) => IdentityProvider;

export declare const identityDocumentSchema: z.ZodObject<{ did: z.ZodString; parent: z.ZodString; publicKeyMultibase: z.ZodString; kind: z.ZodString; scopes: z.ZodReadonly<z.ZodArray<z.ZodString>>; createdAt: z.ZodString; metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>; }, z.core.$strict>;

/**
 * Arsenal broker client facade. The real client lives in `@openagentid/arsenal-sdk`
 * and is injected by the application; see `INTEGRATION_NOTES.md`.
 */
export interface ArsenalClient {
    /** Request a scoped credential for `provider` on behalf of `agentDid`. */
    requestCredential(params: {
        agentDid: Did;
        provider: string;
        scopes?: readonly string[];
    }): Promise<IssuedCredential>;
    /** Optionally release / revoke a previously issued credential. */
    release?(credentialProxyUrl: string): Promise<void>;
}

/**
 * A live, fetch-ready credential bound to an agent DID + provider.
 *
 * The fetch method is a drop-in replacement for `globalThis.fetch`. The
 * underlying credential is refreshed lazily when the caller invokes
 * `refresh()` — auto-rotation stays out of the per-request hot path.
 */
export interface CredentialHandle {
    readonly provider: string;
    readonly agentDid: Did;
    readonly expiresAt: number;
    /**
     * Drop-in replacement for the global `fetch`. The `X-Arsenal-Target`
     * header is set to the original URL and the request is routed through
     * the Arsenal credential proxy.
     *
     * Streaming responses (SSE, chunked JSON, transfer-encoding: chunked)
     * are fully supported because the return value is a standard `Response`.
     */
    fetch: typeof fetch;
    /** Mint a fresh credential and return a new handle. */
    refresh(): Promise<CredentialHandle>;
    /** Release the credential (best-effort; safe to call multiple times). */
    release(): Promise<void>;
}

/** A short-lived credential minted by the Arsenal broker. */
export interface IssuedCredential {
    /** Provider identifier this credential targets. */
    provider: string;
    /**
     * Credential material location. Arsenal's broker returns pre-signed proxy
     * URLs rather than raw secrets; raw tokens never leave the broker.
     */
    proxyUrl: string;
    /** Unix timestamp after which the credential is invalid. */
    expiresAt: number;
    /** Optional ceiling on how many requests this credential can issue. */
    remainingCalls?: number;
    /** Arbitrary metadata (tenant, project, region). */
    metadata?: Record<string, unknown>;
}

export declare const createCredentialHandle: (params: CreateCredentialHandleParams) => Promise<CredentialHandle>;

/** A resolved, authenticated caller identity. */
export interface AuthContext {
    /** The calling agent's DID. */
    readonly did: Did;
    /** The root HMR/MHR this agent chains to. */
    readonly root: Did;
    /** Delegation chain from `root` → `did`. Ordered, length ≥ 1. */
    readonly lineage: readonly Did[];
    /** OAS + Sigil authority proof required for privileged access. */
    readonly lineageAuthority?: LineageAuthorityContext;
    /** Scopes granted to this caller for this request. */
    readonly scopes: readonly string[];
    /** Unix timestamp when the underlying assertion expires. */
    readonly expiresAt: number;
    /** Raw bearer the caller presented, for audit logging. */
    readonly presentedToken?: string;
    /** Arbitrary claims passed through from AEGIS. */
    readonly claims?: Readonly<Record<string, unknown>>;
}

/** Sigil-backed lineage authority attached by an OAS verifier. */
export interface LineageAuthorityContext {
    /** DID whose privileged authority was verified. */
    readonly subject: Did;
    /** Backend/source identifier, normally `sigil_gal`. */
    readonly source: string;
    /** Finalized root DID for the verified path. */
    readonly root: Did;
    /** Reconstructed finalized path, ordered root to caller. */
    readonly path: readonly Did[];
    /** Sigil block height at which this authority was finalized. */
    readonly finalizedBlock: number;
    /** Authority path kind, e.g. `human_to_agent`. */
    readonly pathKind: string;
    /** Scopes proven by this lineage path. */
    readonly scopes: readonly string[];
    /** Generation/depth from root to subject. */
    readonly generation: number;
    /** Accepted root kind for this authority path. */
    readonly rootKind?: string;
    /** Optional org lineage root commitment for org-scoped authority. */
    readonly orgRootCommitment?: string;
    /** Optional expiry timestamp for the authority edge/path. */
    readonly expiresAt?: string;
}

/** Runtime hook that turns an authenticated context into OAS/Sigil authority. */
export interface PrivilegedAuthorityVerifier {
    verify(ctx: AuthContext, options: VerifyRequestOptions): Promise<LineageAuthorityContext>;
}

/**
 * AEGIS verifier facade. Concrete implementation lives in `@openagentid/aegis-sdk`.
 *
 * The OpenAgent SDK never decodes assertions itself — it delegates to
 * AEGIS for all verification, lineage walking, and policy evaluation.
 */
export interface VerificationClient {
    verifyRequest(req: Request, options?: VerifyRequestOptions): Promise<AuthContext>;
    /** Issue a short-lived challenge for challenge-response auth. */
    issueChallenge(): Promise<{
        challenge: Uint8Array;
        challengeId: string;
    }>;
    /** Verify a challenge response (typically from a worker/CLI flow). */
    verifyChallengeResponse(params: {
        challengeId: string;
        agentDid: Did;
        signatureBase64: string;
    }): Promise<AuthContext>;
}

/** Options for {@link VerificationClient.verifyRequest}. */
export interface VerifyRequestOptions {
    /** Require the caller to hold all of these scopes; otherwise throw. */
    requiredScopes?: readonly string[];
    /** Require the caller's lineage to include (or equal) this DID. */
    requiredAncestor?: Did;
    /** Require a Sigil-backed OAS lineage authority result. */
    requirePrivilegedAuthority?: boolean;
    /** Required authority path kind when privileged authority is required. */
    requiredAuthorityPath?: string;
    /** Extra clock skew tolerance (seconds). Default: 60. */
    clockSkewSeconds?: number;
}

export declare class PrivilegedAuthorityVerificationClient {
  constructor(inner: VerificationClient, authorityVerifier: PrivilegedAuthorityVerifier): PrivilegedAuthorityVerificationClient;
  verifyRequest(req: Request, options?: VerifyRequestOptions): Promise<AuthContext>;
  issueChallenge(): Promise<{ challenge: Uint8Array; challengeId: string; }>;
  verifyChallengeResponse(params: { challengeId: string; agentDid: Did; signatureBase64: string; }): Promise<AuthContext>;
}

export declare const extractBearerToken: (req: Request) => string | null;

export declare const assertScopes: (ctx: AuthContext, required: readonly string[]) => void;

export declare const assertAncestor: (ctx: AuthContext, ancestor: Did) => void;

export declare const toVerificationClient: (client: unknown) => VerificationClient;

/** A skill identifier such as `frontend-design` or `sql-query`. */
export type SkillId = string;

/** The minimum contract the OpenAgent SDK expects from a skills policy. */
export interface SkillsPolicy {
    /** Return true if the agent may invoke `skill`. */
    canInvoke(skill: SkillId): boolean;
    /** Throw a {@link SkillDeniedError} if `skill` is not allowed. */
    assertCanInvoke(skill: SkillId): void;
    /** List all skills the agent is currently permitted to invoke. */
    listAllowed(): readonly SkillId[];
    /** Produce a new policy with an additional skill. */
    grant(skill: SkillId): SkillsPolicy;
    /** Produce a new policy without `skill`. */
    revoke(skill: SkillId): SkillsPolicy;
}

export declare class InMemorySkillsPolicy {
  constructor(skills?: readonly SkillId[]): InMemorySkillsPolicy;
  canInvoke(skill: SkillId): boolean;
  assertCanInvoke(skill: SkillId): void;
  listAllowed(): readonly SkillId[];
  grant(skill: SkillId): SkillsPolicy;
  revoke(skill: SkillId): SkillsPolicy;
}

export declare const denyAllSkills: SkillsPolicy;

export declare const allowAllSkills: SkillsPolicy;

export declare const act: { readonly verify: (token: Uint8Array) => ActVerifierBuilder; readonly setCryptoBinding: (binding: ActVerifyBinding) => void; };

export declare class ActVerifierBuilder {
  constructor(token: Uint8Array): ActVerifierBuilder;
  issuer(iss: string): this;
  forAudience(audience: string): this;
  requireScope(scope: string): this;
  requireScopes(scopes: string[]): this;
  trustedKeys(keys: Uint8Array[]): this;
  withLeeway(seconds: number): this;
  atTime(unixSeconds: number): this;
  run(): Promise<ActClaims>;
}

export declare const setActCryptoBinding: (binding: ActVerifyBinding) => void;

/** The claims of a verified ACT, as returned by the canonical verifier. */
export interface ActClaims {
    /** Token identifier. */
    jti: string;
    /** Subject: the OAS DID of the agent the token was issued to. */
    sub: string;
    /** Issuer: the broker instance that minted the token. */
    iss: string;
    /** Audiences this token is valid for. */
    aud: string[];
    /** Issued-at, seconds since the Unix epoch. */
    iat: number;
    /** Not-before, seconds since the Unix epoch. */
    nbf: number;
    /** Expiry, seconds since the Unix epoch. */
    exp: number;
    /** Tenant this token is scoped to. */
    tenant_id: string;
    /** Granted scopes (`service:resource:action`). */
    scope: string[];
    /** Proof-of-possession binding, when present. */
    cnf?: {
        key_fingerprint: string;
        alg: string;
    };
    /** Onward delegation constraints, when present. */
    delegation?: {
        allow_delegation: boolean;
        max_depth: number;
    };
    /** Issuer-defined extension claims (opaque to the format). */
    ext?: Record<string, unknown>;
}

/** Options accepted by the fluent verifier. */
export interface ActVerifyOptions {
    /** The trusted issuer string (required — see {@link ActVerifierBuilder.issuer}). */
    issuer?: string;
    /** The audience this verifier answers for (required). */
    audience?: string;
    /** Scopes the token must grant. Wildcards in the grant expand; literal in the request. */
    scopes?: string[];
    /** Raw 32-byte Ed25519 trusted public keys (required). */
    trustedKeys?: Uint8Array[];
    /** Symmetric clock-skew allowance in seconds. Default: 0. */
    leewaySeconds?: number;
    /** Pinned verification time (tests and decision replay). Default: system clock. */
    nowUnixSeconds?: number;
}

export declare const withAct: (config: RequireActConfig, handler: (req: Request, claims: ActClaims) => Promise<Response> | Response) => (req: Request) => Promise<Response>;

export declare const requireActExpress: (config: RequireActConfig) => (req: { headers: Record<string, string | string[] | undefined>; actClaims?: ActClaims; }, res: { status: (code: number) => { json: (body: unknown) => unknown; }; }, next: () => void) => Promise<void>;

/** Policy for the middleware: the verifier bindings plus optional scopes. */
export interface RequireActConfig {
    /** The trusted issuer string. */
    issuer: string;
    /** The audience this service answers for. */
    audience: string;
    /** Scopes every request must carry. Default: none. */
    scopes?: string[];
    /** Trusted Ed25519 public keys (raw 32 bytes each). */
    trustedKeys: Uint8Array[];
    /** Clock-skew allowance in seconds. Default: 0. */
    leewaySeconds?: number;
    /**
     * Extract the ACT envelope bytes from the request. Default: base64url of
     * the `Authorization: Bearer <token>` header value.
     */
    extractToken?: (req: Request) => Uint8Array | undefined;
    /**
     * Render the 401 response. Default: JSON `{ error }` with a
     * `WWW-Authenticate: OpenAgent` hint.
     */
    onUnauthorized?: (req: Request, reason: string) => Response;
}

export declare const keys: { readonly generate: () => Promise<AgentKeys>; readonly fromSeed: (seed: Uint8Array) => AgentKeys; readonly fromSeedHex: (hex: string) => AgentKeys; readonly fromEnv: (envVar: string) => AgentKeys; readonly saveSeed: (keys: AgentKeys, path: string) => Promise<void>; readonly fromSeedFile: (path: string) => Promise<AgentKeys>; readonly seedToHex: (bytes: Uint8Array) => string; readonly setCryptoBinding: (binding: KeyCryptoBinding) => void; };

export declare const setKeyCryptoBinding: (binding: KeyCryptoBinding) => void;

/** An agent's key material, derived from one seed. */
export interface AgentKeys {
    /** The 32-byte seed — the only thing that must be persisted. */
    readonly seed: Uint8Array;
    /** Ed25519 signing (private) key. */
    readonly signingKey: Uint8Array;
    /** Ed25519 verifying (public) key — the agent's identity fingerprint. */
    readonly verifyingKey: Uint8Array;
    /** X25519 encryption secret key (derived from the seed). */
    readonly encryptionSecretKey: Uint8Array;
    /** X25519 encryption public key (derived). */
    readonly encryptionPublicKey: Uint8Array;
}

/** The crypto-wasm binding shape key custody consumes. */
export interface KeyCryptoBinding {
    ed25519_generate_keypair(): {
        signing_key: Uint8Array;
        verifying_key: Uint8Array;
    };
    ed25519_public_from_private(signingKey: Uint8Array): Uint8Array;
    x25519_generate_keypair(): {
        secret_key: Uint8Array;
        public_key: Uint8Array;
    };
    x25519_public_from_secret?(secretKey: Uint8Array): Uint8Array;
    blake3_derive_key(context: string, keyMaterial: Uint8Array): Uint8Array;
}

try {
  await OpenAgent.createAgent({ ... });
} catch (err) {
  if (err instanceof OpenAgentError) {
    console.error(err.code, err.message);
  }
}

export declare class OpenAgentError {
  code: ErrorCodeValue;
  cause: unknown;
  context: Record<string, unknown>;
  constructor(message: string, details: ErrorDetails): OpenAgentError;
  toJSON(): Record<string, unknown>;
}

export declare class ConfigError {
  constructor(message: string, context?: Record<string, unknown>): ConfigError;
}

export declare class InputValidationError {
  constructor(message: string, cause?: unknown, context?: Record<string, unknown>): InputValidationError;
}

export declare class IdentityError {
  constructor(message: string, details: ErrorDetails): IdentityError;
}

export declare class CredentialError {
  constructor(message: string, details: ErrorDetails): CredentialError;
}

export declare class VerificationError {
  constructor(message: string, details: ErrorDetails): VerificationError;
}

export declare class SkillDeniedError {
  skill: string;
  constructor(skill: string, reason?: string, context?: Record<string, unknown>): SkillDeniedError;
}

export declare const ErrorCode: { readonly INVALID_CONFIG: "openagent/invalid-config"; readonly INVALID_INPUT: "openagent/invalid-input"; readonly NOT_INITIALIZED: "openagent/not-initialized"; readonly IDENTITY_CREATE_FAILED: "openagent/identity/create-failed"; readonly IDENTITY_RESOLVE_FAILED: "openagent/identity/resolve-failed"; readonly IDENTITY_SIGNATURE_INVALID: "openagent/identity/signature-invalid"; readonly IDENTITY_LINEAGE_INVALID: "openagent/identity/lineage-invalid"; readonly CREDENTIAL_FETCH_FAILED: "openagent/credentials/fetch-failed"; readonly CREDENTIAL_SCOPE_DENIED: "openagent/credentials/scope-denied"; readonly CREDENTIAL_PROVIDER_UNKNOWN: "openagent/credentials/provider-unknown"; readonly CREDENTIAL_EXPIRED: "openagent/credentials/expired"; readonly VERIFICATION_FAILED: "openagent/verification/failed"; readonly AUTH_REQUIRED: "openagent/verification/auth-required"; readonly AUTH_CHALLENGE_INVALID: "openagent/verification/challenge-invalid"; readonly SKILL_DENIED: "openagent/skills/denied"; readonly SKILL_UNKNOWN: "openagent/skills/unknown"; readonly NETWORK_ERROR: "openagent/network-error"; readonly SERIALIZATION_ERROR: "openagent/serialization-error"; readonly UNKNOWN: "openagent/unknown"; };

export type ErrorCodeValue = (typeof ErrorCode)[keyof typeof ErrorCode];

/** Structured error metadata attached to every {@link OpenAgentError}. */
export interface ErrorDetails {
    /** Stable machine-readable code. */
    code: ErrorCodeValue;
    /** Optional cause (native Error, SDK error, or anything). */
    cause?: unknown;
    /** Arbitrary structured context for logging. */
    context?: Record<string, unknown>;
}

export declare const wrapError: (err: unknown, fallbackMessage: string) => OpenAgentError;

export declare const getErrorMessage: (err: unknown) => string;

export declare const VERSION: "0.1.1";