@flowsta/holochain

SDK for integrating Holochain apps with Flowsta Vault.

@flowsta/holochain provides functions for agent identity linking, Vault communication, and CAL-compliant backups. It wraps Flowsta Vault's IPC endpoints into a simple TypeScript API.

Installation

npm install @flowsta/holochain

Agent Linking

linkFlowstaIdentity

Request an identity link from the user's Flowsta Vault:

import { linkFlowstaIdentity } from '@flowsta/holochain';

const result = await linkFlowstaIdentity({
  appName: 'ChessChain',
  clientId: 'flowsta_app_abc123',
  localAgentPubKey: myAgentKey,   // uhCAk... format
});

// Commit to your DHT
await appWebsocket.callZome({
  role_name: 'my-role',
  zome_name: 'agent_linking',
  fn_name: 'create_direct_link',
  payload: {
    other_agent: decodeHashFromBase64(result.payload.vaultAgentPubKey),
    other_signature: base64ToSignature(result.payload.vaultSignature),
  },
});

getFlowstaIdentity

Query linked agents on your DHT. Returns an array of linked agent public keys (as raw bytes):

import { getFlowstaIdentity } from '@flowsta/holochain';

const linkedAgents = await getFlowstaIdentity({
  appWebsocket,
  roleName: 'my-role',
  agentPubKey: someAgentKey, // Uint8Array from @holochain/client
});

// linkedAgents is Uint8Array[] - array of linked agent public keys
if (linkedAgents.length > 0) {
  console.log(`Linked to ${linkedAgents.length} Flowsta identities`);
}

getVaultStatus

Check if Vault is running and unlocked:

import { getVaultStatus } from '@flowsta/holochain';

const status = await getVaultStatus();
// { unlocked: boolean, version?: string, agentPubKey?: string }

revokeFlowstaIdentity

Notify Vault that a link has been revoked. Best-effort - if Vault is not running, returns { success: false } without throwing:

import { revokeFlowstaIdentity } from '@flowsta/holochain';

await revokeFlowstaIdentity({
  appName: 'ChessChain',
  localAgentPubKey: myAgentKey, // uhCAk... format
});

checkFlowstaLinkStatus

Check if Vault still considers an agent linked. Returns { linked: false } if Vault is not running:

import { checkFlowstaLinkStatus } from '@flowsta/holochain';

const status = await checkFlowstaLinkStatus({
  clientId: 'flowsta_app_abc123',
  localAgentPubKey: myAgentKey, // uhCAk... format
});

if (status.linked) {
  console.log('App name:', status.appName);
}

Backups

startAutoBackup

Start automatic backups to Vault's encrypted local storage:

import { startAutoBackup } from '@flowsta/holochain';

const stopBackup = startAutoBackup({
  clientId: 'flowsta_app_abc123',
  appName: 'ChessChain',
  getData: async () => {
    // Return whatever data you want backed up
    return { moves: [...], settings: {...} };
  },
  intervalMinutes: 60, // Default: 60
  onSuccess: (result) => console.log('Backup saved:', result.label),
  onError: (err) => console.error('Backup failed:', err),
});

// Stop when your app closes
stopBackup();

backupToVault

Trigger a manual backup:

import { backupToVault } from '@flowsta/holochain';

const result = await backupToVault(
  {
    clientId: 'flowsta_app_abc123',
    appName: 'ChessChain',
    label: 'latest',
  },
  { moves: [...], settings: {...} },
);

retrieveFromVault

Retrieve a stored backup:

import { retrieveFromVault } from '@flowsta/holochain';

const data = await retrieveFromVault({
  clientId: 'flowsta_app_abc123',
  label: 'latest',
});

Error Types

Error	Description
VaultNotFoundError	Vault not running or not installed
VaultLockedError	Vault is locked
UserDeniedError	User rejected the approval dialog
InvalidClientIdError	Client ID not registered
MissingClientIdError	No client_id provided
ApiUnreachableError	Cannot reach Flowsta API

Function Reference

Function	Description
linkFlowstaIdentity(options)	Request identity link from Vault
getFlowstaIdentity(options)	Query linked agents on DHT
getVaultStatus(ipcUrl?)	Check Vault status
revokeFlowstaIdentity(options)	Notify Vault of revocation
checkFlowstaLinkStatus(options)	Check link status in Vault
startAutoBackup(options)	Start automatic backups
backupToVault(options, data)	Store data in Vault
retrieveFromVault(options)	Retrieve stored backup
listVaultBackups(ipcUrl?)	List all backups in Vault

Next Steps

• Building Holochain Apps - Step-by-step integration guide
• Agent Linking - How attestations work
• IPC Endpoints - Raw IPC API reference