Holochain Integration

Flowsta is built on Holochain, providing true zero-knowledge architecture and decentralized identity.

Holochain Powers Flowsta

Flowsta uses Holochain as the foundation for its zero-knowledge authentication system. All user private data is stored on Holochain's distributed hash table (DHT), encrypted client-side so that even Flowsta cannot access it.

What Holochain Enables

Feature	How Holochain Helps
Zero-Knowledge Storage	User data encrypted and stored on DHT - Flowsta staff physically cannot access it
Decentralized Identity	Each user has an agent public key that serves as their cryptographic identity
W3C DIDs	User identities are W3C Decentralized Identifiers (DIDs) anchored to Holochain
Censorship Resistance	No central authority can revoke or modify user identities
Data Portability	Users own their data and can export it anytime

Architecture Overview

graph TB
    subgraph "Client Side"
        User[User Browser]
        Encrypt[Client-Side Encryption]
    end
    
    subgraph "Flowsta Infrastructure"
        API[Auth API]
        PG[(PostgreSQL<br/>Lookup Data Only)]
        HC[Holochain Conductor]
    end
    
    subgraph "Holochain DHT"
        Identity[Identity DNA<br/>Public Profile]
        Private[Private DNA<br/>Encrypted Data]
    end
    
    User --> Encrypt
    Encrypt --> API
    API --> PG
    API --> HC
    HC --> Identity
    HC --> Private

Two Holochain DNAs

Flowsta uses two separate Holochain DNAs:

Identity DNA (Public)

• Display name, profile picture
• Public agent key
• Publicly readable by other users

Private DNA (Encrypted)

• Email (encrypted)
• Recovery phrase (encrypted)
• Session data (encrypted)
• OAuth activity logs
• Only readable by the user who created it

Zero-Knowledge Guarantee

All data in the Private DNA is encrypted with keys derived from the user's password. Flowsta servers never see the unencrypted data or the encryption keys.

For Holochain Developers

If you're building a Holochain application, you have two options for integrating with Flowsta:

Option 1: Use Flowsta for Authentication Only

Use Flowsta's OAuth system for user authentication, but manage your own Holochain agent keys:

import { FlowstaAuth } from '@flowsta/auth';

const auth = new FlowstaAuth({
  clientId: 'your-client-id',
  redirectUri: 'https://yourapp.com/callback',
  scopes: ['openid', 'public_key', 'did'] // Get user identity, not signing
});

// User authenticates
const user = await auth.handleCallback();

// Use their Flowsta identity but your own Holochain keys
console.log('User DID:', user.did);
console.log('User agent key (Flowsta):', user.agentPubKey);

// Your app can generate its own agent key for the user
// or use the Flowsta key as an identifier

This approach:

• ✅ Gives users a consistent identity across apps
• ✅ You control your own Holochain infrastructure
• ✅ No dependency on Flowsta for signing

Option 2: Use Flowsta's Signing Service

Let Flowsta sign Holochain actions on behalf of your users:

import { FlowstaAuth } from '@flowsta/auth';
import { createHolochainClient } from '@flowsta/holochain';

const auth = new FlowstaAuth({
  clientId: 'your-client-id',
  redirectUri: 'https://yourapp.com/callback',
  scopes: ['openid', 'holochain:sign'] // Request signing permission
});

const holochain = createHolochainClient(auth);

// Sign Holochain actions via Flowsta
const result = await holochain.signAction({
  action: { type: 'CreateEntry', ... }
});

This approach:

• ✅ No Holochain conductor setup required
• ✅ Users have one key across all participating apps
• ✅ Built-in consent management
• 🔐 Private keys never leave Flowsta - you only receive signatures
• ⚠️ Requires network connection to Flowsta

Your App Never Receives Private Keys

The signing service returns only the cryptographic signature and the user's public key. Private signing keys are securely stored on Flowsta's Holochain conductor and are never exposed through the API.

→ Learn more about the Signing Service

For Non-Holochain Developers

You don't need to know anything about Holochain to use Flowsta! The standard OAuth integration works like any other identity provider:

import { FlowstaAuth } from '@flowsta/auth';

const auth = new FlowstaAuth({
  clientId: 'your-client-id',
  redirectUri: 'https://yourapp.com/callback',
  scopes: ['openid', 'email', 'display_name']
});

// Standard OAuth flow
auth.login();

// Get user info
const user = await auth.handleCallback();
console.log('User:', user.displayName, user.email);

Holochain runs behind the scenes to provide zero-knowledge data storage, but you interact with Flowsta through standard OAuth 2.0.

Optional: Use the Signing Service

Even if your app isn't built on Holochain, you can use the signing service to:

• Cryptographically sign data using the user's Flowsta agent key
• Verify signatures to prove data authenticity
• Create audit trails with cryptographic proof

Your application only receives the signature - private keys are never exposed and remain securely stored on Flowsta's infrastructure.

→ Learn more about the Signing Service

Next Steps

• Signing Service - Use Flowsta to sign Holochain actions
• SDK Reference - Full @flowsta/auth documentation
• OAuth Flow - Understand the authentication flow
• API Reference - REST API endpoints

Learn More About Holochain

• Holochain.org - Official Holochain website
• Holochain Developer Portal - Build on Holochain
• Holochain Forum - Community discussions