Agent Linking

Cryptographic identity attestations between your app and Flowsta Vault.

Agent linking creates an IsSamePersonEntry on your DHT that proves a user's app agent key and Flowsta Vault agent key belong to the same person. The proof is a pair of Ed25519 signatures - verifiable by anyone on your network without contacting Flowsta.

How It Works

The 78-Byte Payload

Vault constructs the signing payload itself (apps cannot influence what gets signed):

Bytes	Content
0-38	First agent public key (39 bytes: 3-byte prefix + 32-byte key + 4-byte checksum)
39-77	Second agent public key (39 bytes, same format)

The two 39-byte Holochain AgentPubKeys are sorted lexicographically to produce a canonical 78-byte payload. Both agents sign this payload. The dual-signature design means:

• The app agent attests "I am the same person as this Vault agent"
• The Vault agent attests "I am the same person as this app agent"
• Anyone can verify both signatures using the public keys in the payload

SDK Functions

Function	Description
linkFlowstaIdentity(options)	Request identity link from Vault
getFlowstaIdentity(options)	Query linked agents on your DHT
getVaultStatus(ipcUrl?)	Check if Vault is running and unlocked
revokeFlowstaIdentity(options)	Notify Vault of revocation
checkFlowstaLinkStatus(options)	Check if Vault still considers agent linked

linkFlowstaIdentity

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

const result = await linkFlowstaIdentity({
  appName: 'ChessChain',              // Shown in Vault's approval dialog
  clientId: 'flowsta_app_abc123',      // From dev.flowsta.com
  localAgentPubKey: myAgentKey,        // uhCAk... format (your app's agent key)
  ipcUrl: 'http://localhost:27777',    // Optional, this is the default
});

// result.payload:
// {
//   vaultAgentPubKey: string,  // uhCAk... format
//   vaultSignature: string,    // Base64-encoded Ed25519 signature
// }

getFlowstaIdentity

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

const linkedAgents = await getFlowstaIdentity({
  appWebsocket,                        // @holochain/client AppWebsocket
  roleName: 'my-role',                 // DNA role name
  agentPubKey: someAgentKey,           // Uint8Array - agent to look up
});

// Returns Uint8Array[] - array of linked agent public keys
// Empty array if not linked to any Flowsta identity

Zome Functions

These are the Holochain zome calls available after adding the flowsta-agent-linking zomes to your DNA:

Function	Input	Output	Description
create_direct_link	DirectLinkInput	ActionHash	Commit attestation to DHT
get_linked_agents	AgentPubKey	Vec<AgentPubKey>	Get all linked agents
are_agents_linked	AgentPair	bool	Check if two agents are linked
revoke_link	ActionHash	ActionHash	Revoke a link (either agent can revoke)

DirectLinkInput

{
  other_agent: Uint8Array,     // 39-byte Holochain AgentPubKey
  other_signature: Uint8Array, // 64-byte Ed25519 signature
}

Error Handling

Error	Cause	Suggested UX
VaultNotFoundError	Vault not running or not installed	"Install or start Flowsta Vault"
VaultLockedError	Vault is locked (passphrase required)	"Please unlock your Flowsta Vault"
UserDeniedError	User rejected the approval dialog	"Identity linking cancelled"
InvalidClientIdError	client_id not registered or invalid	Developer error - check registration
MissingClientIdError	No client_id provided	Developer error
ApiUnreachableError	Can't reach Flowsta API to verify app	"Check internet connection"

Security

• User-custodied keys - Private keys never leave the user's device
• Purpose-specific signatures - Vault computes the payload itself; apps cannot trick users into signing arbitrary data
• User approval required - Every link request shows an approval dialog in Vault
• Verifiable on-chain - Anyone on your DHT can verify using Ed25519 public key cryptography
• Revocable - Either agent can revoke a link at any time
• No shared infrastructure - Verification requires no API calls or shared DNAs

Next Steps

• Building Holochain Apps - Step-by-step integration guide
• @flowsta/holochain SDK - Full SDK documentation
• IPC Endpoints - Raw IPC API for custom implementations
• Holochain Architecture - How Flowsta's Holochain infrastructure works