Skip to content
ManykindManykindmanykind

Vault SDK (@cef-ai/vault-sdk)

Terminal window
npm install @cef-ai/vault-sdk@5.5.0

The vault SDK is the client for a vault: create or open it, publish and read events, store objects, connect agents, read the Memory Bank, and manage members. It runs in Node and the browser.

Construction

import { VaultSDK, KeypairWallet } from "@cef-ai/vault-sdk";


const sdk = new VaultSDK({
  endpoint: vaultApiUrl,
  garEndpoint: garUrl,
  signer: await KeypairWallet.fromSeed(seed),
});
VaultSDKConfig Meaning
endpoint vault-api base URL. Required.
signer A Signer. Signs requests and consent agreements.
auth A custom AuthProvider; overrides signer for requests.
garEndpoint Agreement registry URL. Needed for vault.agents.connect.
chainUrl Chain RPC URL. Needed by vault.ensure() on the wallet path.
s3GatewayAuthInfoUrl Gateway /auth/info URL, for onboarding.
marketplaceEndpoint Marketplace URL for sdk.marketplace.
fetch, timeoutMs Transport overrides.
Signer / auth Use
KeypairWallet.fromSeed(seed) Server: a raw 32-byte ed25519 seed.
CereWallet.fromMnemonic(…), CereWallet.fromKeystore(…) A wallet from a mnemonic or keystore.
new WalletAuthProvider(signer) Sign each request (the default when you pass signer).
new DelegationAuthProvider(token) Authenticate with a delegation bearer token instead of signing.
new NoAuth() Unauthenticated calls.

Opening a vault

Method Returns
sdk.vault.ensure(opts?) Your vault, creating it on first use. opts: onboard (default true), onProgress, chainUrl. Idempotent.
sdk.vault.current() Your own vault.
sdk.vault.byId(vaultId) A vault by id, typically an organization’s.
sdk.vault.rename(vaultId, displayName) Sets the vault’s name. Owner only.

ensure() throws OnboardingRequiredError when the wallet still needs its on-chain gateway registration, and OnboardingTimeoutError when onboarding does not finish in time. onProgress reports inspecting-wallet, funding-wallet, gateway-authorization-required, and later steps.

Vault

Member Does
id, bucketId, walletPubkey, displayName, status Vault record. isDisconnected() is true when its storage credential can no longer be refreshed.
scopes.list(), .get(name), .create(req), .update(name, req), .delete(name) Manage scopes.
scope(name) A ScopeHandle.
service(asPubKey) An Agent Service’s cubbies in this vault: list(), cubby(alias).query/exec/provision/delete.
agents.connect(input) Connect an agent. See Connect to a vault.
agents.list(), agents.get(agentId) AgentConnectionHandles.
agents.connections(agentId), .setConnection(agentId, connectionId, body), .removeConnection(…) An agent’s access to the vault’s connector connections.
connections Connector connections: list, create, update, revoke, actions. See Connectors.
connectors() The connector catalog.
webhooks Webhook triggers of connected workflows: list(agentId), createKey, revokeKey. A key’s secret is returned once.
memory Memory Bank reads: search, list, get, neighbours, countByType. Writes happen in agents through ctx.memory.
jobs.list({ state?, cursor?, limit? }), jobs.get(jobId) Runs. JobHandle: get(), tasks.list/get/logs/subscribe.

ScopeHandle

Member Does
publish(input) Publish one event. input: { type, context, payload, role?, target?, correlationId?, metadata?, parents?, timestamp? }. Resolves { eventId }; throws when the vault rejects it.
subscribe(filter, handler, opts?) Follow one stream. filter: { context, types?, from? }. opts: intervalMs (default 1000), pageSize (default 100), onError, maxBackoffMs. Returns { unsubscribe(), closed }.
subscribeAll(filter, handler, opts?) Follow every stream in the scope. filter: { types? }. refreshIntervalMs (default 30000) picks up new streams.
streams.list(opts?), streams.get(context) Stream summaries.
stream(context).events.list(opts?) A stream’s events, paged.
objects.upload(path, data, opts?) Upload bytes. opts.publishEvent also publishes an event carrying vaultPath.
objects.get, .head, .presignedUrl(path, { ttlSeconds? }), .delete, .list({ prefix? }) Object storage.

AgentConnectionHandle

Fields: vaultId, agentId, scope, scopes, version, asPubKey, cubbyAliases, status, ceiling, bundle ({ bucketId, cid }, the pinned code), createdAt, updatedAt.

Method Does
update(settings) Update the connection’s settings.
setCeiling({ gpuUnits?, a2aTokens? }) Set spend limits; 0 or absent means no limit on that axis.
cubby(alias) query(sql, params) / exec(sql, params) on the agent’s cubby.
disconnect() Remove the connection. Cubby data stays.

Memberships

sdk.memberships: mine() (vaults you belong to), list(vaultId), signedRoster(vaultId), put(…), putScopes(…), remove(vaultId, memberPubkey), scopes(vaultId, memberPubkey). put and putScopes need a signer: the owner signs the grant document. See Vault members.

Other exports

Export Use
signAndSubmitAgreement, GarClient, getAsPubkey Sign and submit a consent agreement yourself.
mintDelegationTokens, VAULT_DELEGATION_OPERATIONS, REGISTRY_DELEGATION_OPERATIONS The owner’s delegation tokens.
verifySignedRoster, verifyGrant, decodeGrantDoc Verify a signed member roster.
sdk.health Service health.
sdk.marketplace.getAgent(agentId, version?), .list(opts?) Read the marketplace listing.

Lower-level clients are under @cef-ai/vault-sdk/internal.

Errors

Class When
VaultRequestError Any vault-api error. Fields: status, code, retryable. Match on code.
BundleChangedError 409 BUNDLE_CHANGED. requestedCid, currentCid.
ReconsentRequiredError 409 RECONSENT_REQUIRED. previousCid, currentCid.
CeilingUnknownError A scope write could not be signed because the member’s privacy ceiling is unknown.
VaultNotImplementedError 501.
VaultSignerRequiredError A method that needs a signer was called without one.
OnboardingRequiredError, OnboardingTimeoutError From ensure().

All codes: Errors.