Agent Linking

Link your Holochain app's agent key with the user's Flowsta Vault identity.

Flowsta Vault acts as a local identity provider for Holochain apps. When a user approves a link request, the Vault signs a cryptographic attestation that is committed to your app's DHT as an IsSamePersonEntry. Anyone on your DHT can verify the link using Ed25519 cryptography - no shared DNA or API dependency required.

How It Works

Prerequisites

1. Register your app at dev.flowsta.com to get a client_id
2. Add the flowsta-agent-linking zomes to your DNA (see Integration Guide)
3. Install the SDK: npm install @flowsta/holochain

Quick Start

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

// Link identity
const result = await linkFlowstaIdentity({
  appName: 'ChessChain',
  clientId: 'flowsta_app_abc123...', // from dev.flowsta.com
  localAgentPubKey: myAgentKey,      // uhCAk... format
});

// Commit to your DHT
await appWebsocket.callZome({
  role_name: 'chess',
  zome_name: 'agent_linking',
  fn_name: 'create_external_link',
  payload: {
    external_agent: decodeHashFromBase64(result.payload.vaultAgentPubKey),
    external_signature: base64ToSignature(result.payload.vaultSignature),
  },
});

// Query linked identities
const linked = await getFlowstaIdentity({
  appWebsocket,
  roleName: 'chess',
  agentPubKey: myAgentKey,
});

Integration Guide

1. Add zomes to your DNA

Add the flowsta-agent-linking crate to your DNA's integrity and coordinator zomes:

# integrity Cargo.toml
[dependencies]
flowsta-agent-linking-integrity = { git = "https://github.com/WeAreFlowsta/flowsta-agent-linking" }

# coordinator Cargo.toml
[dependencies]
flowsta-agent-linking-coordinator = { git = "https://github.com/WeAreFlowsta/flowsta-agent-linking" }

Reference them in your dna.yaml:

integrity:
  zomes:
    - name: agent_linking_integrity
      bundled: ../../target/.../flowsta_agent_linking_integrity.wasm
coordinator:
  zomes:
    - name: agent_linking
      bundled: ../../target/.../flowsta_agent_linking_coordinator.wasm
      dependencies:
        - name: agent_linking_integrity

2. Install SDK

npm install @flowsta/holochain

3. Register your app

Go to dev.flowsta.com and create an app to get a client_id.

API Reference

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/unlocked
revokeFlowstaIdentity(options)	Notify Vault of revocation
checkFlowstaLinkStatus(options)	Check if Vault still considers agent linked

Zome Functions

Function	Description
create_external_link(ExternalLinkInput)	Commit attestation to DHT
get_linked_agents(AgentPubKey)	Get all linked agents
are_agents_linked(AgentPair)	Check if two agents are linked
revoke_link(ActionHash)	Revoke a link (either agent can revoke)

Error Handling

Error	Cause	Suggested UX
VaultNotFoundError	Vault not running	"Install or start Flowsta Vault"
VaultLockedError	Vault is locked	"Please unlock your Flowsta Vault"
UserDeniedError	User rejected dialog	"Identity linking cancelled"
InvalidClientIdError	Bad client_id	"App not registered"
MissingClientIdError	No client_id	Developer error
ApiUnreachableError	Can't verify app	"Check internet connection"

Security

• User-custodied keys: Private keys never leave the user's device (Flowsta Vault)
• Purpose-specific signatures: Vault computes the signing payload itself, preventing apps from tricking 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 the attestation using Ed25519 public key cryptography
• Revocable: Either party can revoke a link at any time

Next Steps

• SDK Reference - Full @flowsta/auth documentation
• OAuth Flow - Standard authentication flow
• Holochain Overview - How Flowsta uses Holochain