Changelog

v5.5

Backups: choose your recovery model

The Backups guide now opens with a recovery-model decision table instead of assuming one shape fits all apps: recognition for shared-DHT apps (the network is the durability; data re-syncs on sign-in, nothing is replayed), replay for per-user-DHT and single-author apps (the Vault backup is the durability; restoreFromVault or your own walker re-commits records), and extension blocks for data that isn't on Holochain at all. All three ride the same canonical payload, and most real apps mix them - ProofPoll (recognition + key escrow) and Your Own AI (replay + extension blocks) are cited as live references.

New sections alongside it: What your users see (how one payload becomes the Your Data listing with per-entry-type counts, the per-app Export, and the all-app Download All Data), When restore runs (detection patterns, key-before-records ordering, idempotency), and Non-Holochain data: extension blocks (settings, images, and local encrypted files in the same backup, with _readme and readable-view guidelines). Building Holochain Apps carries the model choice in brief, and Data Portability now documents the per-app Export and how apps bring their own data back after a restore.

SDK v2.6.0: an empty backup never overwrites a real one

@flowsta/holochain 2.6.0 guards the reinstall window where auto-backup fires before recovery has run: a payload with zero user records no longer overwrites a non-empty Vault backup. On by default (protectNonEmpty), surfaced as EmptyBackupSkippedError on onError, with wouldOverwriteNonEmptyBackup() exported for apps that post with backupToVault directly. Documented under startAutoBackup and in the error table.

v5.4

Encrypted private data: pick the key model first

The encrypted entries guidance previously taught one pattern (agent-key crypto_box) and said the DHT itself was the backup. That was only half the story: peers replicate ciphertext, but if the key lives solely in one device's lair keystore, the data still dies with the device. The section now opens with a key-model decision table - agent-key crypto_box for single-device data, a secret-derived symmetric key for multi-device and recoverable data (the model Flowsta Vault itself uses in production), or a random local key with a key-export UX for standalone-first apps - plus sealed-envelope and per-user network-seed guidance for apps that also need to hide metadata. Building Holochain Apps carries the same guide in brief.

When a backup SHOULD carry a key

The backups page taught that backups carry data only and the Vault supplies the keys - true when your app's cryptography derives from the user's Flowsta identity, but not when your app generates independent key material (its own agent key, or a local data-encryption key). Those belong in the app_keys block on your canonical payload: Vault preserves it verbatim, so it reaches both the single-app export and the full "Download Export", keeping every export self-sufficient per CAL §4.2.1.

v5.3

What the Vault sends home

New page: What the Vault Sends Home - a complete, field-by-field account of the Vault's background traffic. The short version: a version check on unlock (nothing about you), one small usage record per connected app per calendar month (a random per-app ID and a use counter, synced when possible), and a signed Sign It quota count when you publish. Pseudonymous to Flowsta for billing, aggregate-only to developers, nothing to anyone else - with links to the open-source code that does the sending.

v5.2

2FA references retired

Two-factor authentication protected password sign-ins - and signing in with Flowsta no longer uses a password. Every sign-in is approved by you in your Vault instead, so there is no separate 2FA feature. (Your vault password remains - it unlocks the Vault on your device, and never leaves it.) Removed the remaining mentions: the sessions protections table and recommendations now describe Vault approval, and the reserved user.2fa.* webhook events are gone from event types.

v5.1

Consented email sharing

The email scope now does something: it asks the user to share their address at the consent screen. Flowsta still stores no email for the account - the user provides the address (pre-filled from their Vault when available), Flowsta verifies it against the account's hash and requires it to be verified, and the shared copy is held on your app's grant only. /oauth/userinfo then returns email and email_verified for your app; revoking the app deletes the shared copy.

Every page that said "email is never returned" now teaches the sharing model instead: OAuth overview, quickstart, API reference, security, vanilla JS guide, SDK, and login button. The design guidance is unchanged and now enforceable: treat email as optional and revocable - key your accounts on sub.

v5.0

The vault-first rewrite: every page audited against the shipping code, and the whole site now teaches one mental model - your identity lives on your device, and no one sits between you and a sign-in or a signature.

The model, taught first

The homepage and Getting Started now lead with how Flowsta accounts actually work: keys derive from the recovery phrase on the user's device, there is no password anywhere, and every sign-in - web or desktop - is the user approving with their Vault. The Security section was rewritten around the same story: zero-knowledge now describes device-held keys and sealed records (not server-side encryption), sessions explains the three-token model with honest lifetimes, and data portability teaches the rule that matters: your recovery phrase restores your identity; your export file restores your data - including the new Restore from an Export.

Sign It: signing happens in the Vault

The Sign It section now teaches Vault signing as the way it works - per-signature approval, keys never leaving the device - with the API-token path clearly marked legacy. New: Signing Quotas & Sponsored Signing - app-initiated signatures draw from your org's monthly pool (Free 250, Spark 2,500, Pro 25,000) so your users never spend their personal quota on your product, with an honest fallback when a pool runs dry. The verification, content-rights, and badge references now document the exact response shapes the API returns.

Corrections worth knowing about

• The login button performs a full-page redirect; the previously documented onSuccess callback never fired and is gone from all examples - handle the code on your redirect URI page. From @flowsta/auth 2.3.1, handleCallback() completes button-initiated flows directly.
• email is now opt-in end to end: it's no longer in the SDK default request scopes (@flowsta/auth 2.3.2, @flowsta/login-button 0.1.6) or the default scopes for new apps on dev.flowsta.com. Requesting a scope your app hasn't enabled fails with invalid_scope.
• Flowsta accounts don't expose an email address to apps (the server holds only a hash). Every place that promised email delivery now says so - ask your users directly if you need one.
• Agent-linking examples now use the public crate's real API: create_external_link with external_agent/external_signature. One canonical Agent Linking guide replaces the two overlapping pages.
• Access tokens are opaque to your app - validate by calling /oauth/userinfo. The refresh grant does not rotate refresh tokens.
• The Vault IPC reference now documents the real error envelope, /sign-document (including sponsored signing), and six previously undocumented endpoints.
• The Vault sign-in endpoints (/auth/vault/challenge + /auth/vault/token) and the SDK's authenticateWithVault, relay login, and buildBackupPayload are now documented.
• Holochain architecture now covers all three DNAs and the live community DHT nodes - anyone can run one via flowsta-dht-node.

v4.7

Retires the @flowsta/auth-tauri package and rewrites the desktop authentication guide around @flowsta/holochain.

Removed: @flowsta/auth-tauri

The package is deprecated on npm and its docs are gone. It predated the current Vault integration model and had apps collect the user's vault password - desktop apps never handle credentials. Everything it offered (and more) lives in @flowsta/holochain over local IPC: status, sign-in, identity linking, document signing, and backups.

SDK releases: @flowsta/auth 2.3.0, @flowsta/holochain 2.5.0

@flowsta/auth 2.3.0 makes signing Vault-first: signFile() signs through Flowsta Vault whenever it's running (the user approves in the Vault; keys never leave the device), and throwing a typed VaultRequiredError when there's no Vault. New typed errors (VaultRequiredError, UserDeniedError) replace opaque failures, and FlowstaUser.email is now documented honestly: device-hosted accounts never expose an email - ask the user if your app needs one.

@flowsta/holochain 2.5.0 adds multi-cell backups (additionalCells), documents that restore re-authors entries (new action hashes - see the restore warning), and wires the previously-unused typed errors: BackupTooLargeError now throws on the 50 MB limit and DispatcherFailedError when every record fails to restore.

Rewritten: Desktop App Authentication

The desktop guide now documents the real flow: probe the Vault with getVaultStatus(), sign a server-issued challenge with authenticateWithVault(), and exchange the signature for a session - the first public documentation of the Vault sign-in handshake for desktop apps. The user approves in the Vault UI; no password exists anywhere in the flow.

v4.6

Documents Vault 0.7.0 integration - how apps re-link after a Vault reset and the stricter native-client auth - plus a privacy caveat for encrypted entries.

New: re-linking after a Vault reset

The link-status guidance on the SDK page now covers a Vault reset as a cause of the unlinked state. A full reset clears every app link, so unlinked fires after a reset even when the user reconnects with the same recovery phrase - the identity is unchanged, but the link has to be re-made. Two re-linking patterns are documented: ProofPoll's user-initiated Reconnect banner, and Your Own AI's auto re-link on launch. Either way, never silently revoke.

New: native clients must send an Origin header

The Vault IPC reference now states that native (Tauri) clients must send an Origin header on IPC requests. Linking and then authenticating from the same origin within one unlock session shows one approval dialog, not two - the link approval covers the follow-up authenticate, re-prompting after Vault relocks.

New: metadata caveat for encrypted entries

The encrypted-entries guidance now spells out that while an entry body stays sealed, link types and anchors are public on the DHT - so the kind, count, timing, and relationships of private entries can be inferred from the link graph. It includes mitigations (a single opaque link type, encrypting references inside the payload) plus reminders to cap ciphertext size in validation, enforce author-only deletes at the integrity level, and that "deleted" DHT data is tombstoned, not erased.

v4.5

Corrects the backup / CAL §4.2.1 documentation. An earlier entry described per-backup lair_* key fields; those were removed in @flowsta/holochain@2.4.4 because they don't reflect how Flowsta works.

Corrected: where CAL key material comes from

A backup carries data only. CAL §4.2.1 completeness is satisfied at the Vault level: the Vault's "Export All Data" includes the user's data plus their device seed (the key material their 24-word recovery phrase derives), so the export is self-sufficient - re-derivable on any compatible Holochain conductor, with no lock-in.

Restore on a new device is recognition, not replay: the user signs in with their Flowsta identity, the Vault recognizes their agent set, and on-network data re-syncs from the DHT. See the Backups section.

v4.3

Documents @flowsta/holochain@2.4.x - the SDK release that adds canonical-shape backups, reinstall recovery, and the Cryptographic Autonomy License §4.2.1 data-export pipeline.

New: canonical-shape backups

The Backups section on the SDK page now leads with the canonical v1 payload format. Each backed-up record carries:

• A human_readable view of what the user authored (decoded entry as plain JSON).
• A raw_record view (the signed Holochain bytes) for restore + verification.

When a backup follows this shape, the Vault auto-surfaces per-entry-type counts on the Your Data page ("12 polls, 38 votes") and inlines the human-readable view of each record into the user's data export - what every CAL-licensed Holochain app is obliged to provide under §4.2.1.

The legacy getData()-based startAutoBackup signature still works for backwards compatibility.

New: restoreFromVault + reinstall recovery

The new restoreFromVault walker fetches a backup and calls your dispatcher once per record. You write one match on entryType to re-create entries via your zome functions; the SDK handles iteration, progress, idempotency, and failure aggregation.

The Reinstall recovery section documents the canonical pattern: check listVaultBackups on first launch, show a restore prompt if there's a backup and the local source chain is empty, replay via restoreFromVault. ProofPoll is the live reference.

New: dumpCellStateForBackup + AdminWebsocketLike

The SDK now exposes dumpCellStateForBackup which builds a canonical payload from an AdminWebsocket instance. It accepts a duck-typed AdminWebsocketLike interface so the SDK stays runtime-dependency-free. For apps whose frontend only has an AppWebsocket, the canonical payload can be built on the Rust side from zome queries - see the Rust-side alternative section.

New: write-triggered backups + heartbeat

startAutoBackup gains a new signature with:

• triggerOnWrite: true (default) - backups debounce 30s after each controller.triggerBackupSoon() call from your zome-write success handlers.
• heartbeatMinutes: 30 (default) - a safety-net retry that catches transient failures (Vault locked, IPC blip) without spamming when nothing has changed.
• label: "latest" (default) - single overwriting backup. The 10-snapshot capacity is still there if you opt in with timestamped labels.

Returns an AutoBackupController { triggerBackupSoon(), stop() }.

New: backup-side error types

• BackupTooLargeError - payload exceeds Vault's 50 MB per-app limit.
• DispatcherFailedError - a restore dispatcher threw on a record; the full record + cause are attached for retry.
• RestoreInProgressError - concurrent restoreFromVault calls collide.
• DecodeFailedError - your decodeRecordForExport threw; backup keeps going for other records.

Updated: getVaultStatus returns webUsername

Alongside the existing displayName + profilePicture, getVaultStatus() now returns webUsername - the unique global username the user claimed at flowsta.com. Scope-gated at link time: the field is only populated when your app's client_id has the username scope configured at dev.flowsta.com.

v4.2

Documents @flowsta/holochain@2.3.0 - the SDK release that introduces the canonical "graceful banner, never auto-revoke" pattern for third-party apps integrating Flowsta identity.

New: getFlowstaLinkStatus - three-state link status

The getFlowstaLinkStatus reference on the SDK page documents the new function and its three-state return shape:

• linked - Vault is running and recognizes the app's agent
• unlinked - Vault is running but does NOT recognize the agent (the user switched Flowsta accounts, restored Vault from a different recovery phrase, or unlinked from the Vault UI)
• offline - Vault is not reachable; trust local link state as authoritative

This replaces the boolean returned by checkFlowstaLinkStatus, which collapsed the unlinked and offline states and led apps to silently revoke users when the Vault was simply closed.

Recommended UX pattern: never auto-revoke

The SDK page now documents the canonical pattern: render a top-of-page banner when state is unlinked, offering Reconnect (re-link with the current Vault account) or Disconnect (deliberately revoke). Never silently revoke. Past data attributed to the local agent stays the user's regardless of the Vault link choice. ProofPoll is linked as the reference implementation.

Updated: getVaultStatus returns display info

The getVaultStatus reference covers the two new fields on the result - displayName and profilePicture for the currently-unlocked account - so apps can render "Signed in as <Name>" without a separate /status request.

Deprecated

checkFlowstaLinkStatus is marked deprecated across the SDK reference, the Vault agent-linking page, and the Holochain integration page. It still works for backwards compatibility; new code should use getFlowstaLinkStatus.

Packages published

• @flowsta/holochain@2.3.0

---

v4.1

Post-launch polish and integrator-facing additions for Sign It.

New: Badge & Widget reference

A dedicated Badge & Widget page covering the embeddable widget.js and the underlying badge API. Includes attribute reference (data-flowsta-hash, data-flowsta-style, data-flowsta-theme), style variants (card / badge / minimal), SVG and JSON rendering endpoints, and examples for HTML, React, static sites, and CSP-locked environments.

New: Content Rights API endpoint

The Content Rights page now documents the machine-readable endpoint for AI training pipelines, search engines, and content platforms:

• GET /api/v1/sign-it/content-rights?hash=<sha256> - returns signer-declared license, AI-training policy, commercial-licensing stance, and contact preference as JSON
• Aggregation rules - most restrictive policy wins when multiple signers declare different rights; revoked signatures are excluded
• 5-minute edge caching - safe for CDN/pipeline use at scale
• Python example - drop-in check for AI training pipelines

Adopting the Standard

The Content Rights field set is open - no proprietary schema, no license fees, no API key. We'd like the same enum values (license, ai_training, commercial_licensing, contact_preference) to become a de-facto standard so a single query surfaces rights regardless of which service signed the file. Details →

SDK cross-links

• /sdk/auth and /sdk/holochain now surface the Sign It methods directly, each linking to the full Sign It SDK Reference.
• SigningDnaNotInstalledError added to the desktop error-handling example in the Developer Guide.

Packages published

The Sign It methods covered across the v4.0 documentation are live on npm:

• @flowsta/auth@2.2.0
• @flowsta/holochain@2.2.0

---

v4.0

Flowsta is now three building blocks, not one. This release adds cryptographic file signing and real-time webhooks as first-class products, alongside the existing sovereign login.

New: Sign It - Cryptographic File Signing

A new product pillar. Users sign files with their Flowsta identity; anyone can verify on a public Holochain DHT. No keys to manage, no servers to run.

• Intent types - Authorship, Approval, Witness, Receipt, Agreement
• Content rights - declare license and AI training policy at sign time
• AI disclosure - None, Assisted, or Generated per signed file
• Multi-signer - multiple agents can co-sign the same file hash
• Revocation - the signer can revoke with an optional reason; the revocation is itself a signed action
• Perceptual matching - fuzzy lookup for images, audio, and video (finds resized, cropped, or recompressed copies)
• Thumbnails - signers can attach a data:image/... thumbnail (≤ 15 KB) to their signature
• Blind contact relay - anyone can message a signer without learning their email

New section: Sign It - overview, quickstart, content rights, developer guide, SDK reference, and verification API.

New: Real-Time Webhooks

Subscribe your server to events from your OAuth app's users. Every payload is HMAC-SHA256 signed with a per-webhook secret.

Events currently firing:

• sign.created
• sign.revoked
• oauth.authorized
• oauth.token.revoked
• user.profile.updated

Reserved for future work: user.2fa.enabled, user.2fa.disabled, subscription.upgraded, subscription.downgraded, subscription.cancelled.

Delivery is fire-and-forget with a 10-second timeout; webhooks are auto-disabled after 10 consecutive failures and can be re-enabled with PUT { active: true }.

New section: Webhooks - overview, event types and payloads, HMAC verification with Node and Python examples, delivery and failure policy.

New: API Endpoints

Sign It

• POST /api/v1/sign-it/sign - sign a file hash
• POST /api/v1/sign-it/sign-batch - sign up to 100 hashes per request
• POST /api/v1/sign-it/revoke - revoke a signature you created
• GET /api/v1/sign-it/verify - hash lookup
• POST /api/v1/sign-it/verify-file - upload a file for server-side perceptual fingerprinting (50 MB max)
• POST /api/v1/sign-it/verify-fuzzy - fuzzy lookup from pre-computed perceptual hash bands
• POST /api/v1/sign-it/fingerprint - compute a perceptual hash with the same algorithm Vault uses (50 MB max)
• POST /api/v1/sign-it/set-thumbnail - attach a thumbnail to an existing signature
• GET /api/v1/sign-it/my-signatures - list signatures by the authenticated user
• GET /api/v1/sign-it/creator/:id - public profile and signatures for a signer
• GET /api/v1/sign-it/badge - verification badge (SVG / JSON)
• GET /api/v1/sign-it/content-rights - query content rights for a file hash
• POST /api/v1/sign-it/contact - blind email relay to a signer

Webhooks

• GET /api/v1/webhooks/events - list available event types (public)
• POST /api/v1/webhooks - register a webhook
• GET /api/v1/webhooks - list webhooks on an app
• PUT /api/v1/webhooks/:id - update url, events, filters, or active
• DELETE /api/v1/webhooks/:id - delete

New: Signing DNA

A third public Holochain DNA dedicated to Sign It signatures. Integrity and coordinator zomes cover signature entries, content rights manifests, perceptual hash bands, multi-signer links, revocations, and public creator profiles.

New: Tier Gating & Quotas

• Sign It quotas - monthly signature quotas per developer tier (Free 250, Spark 2,500, Pro 25,000, Enterprise custom). Overage metered per 100 signatures and billed via Stripe on Spark ($1/100) and Pro ($0.50/100). Verification is always free and unlimited.
• Webhook limits - webhook endpoints counted per organization: Free 0, Spark 10, Pro 100, Enterprise unlimited. Paid tiers only.

SDK Updates

• @flowsta/auth - new Sign It methods: hashFile(), signFile(), signBatch(), verifyFile(), getContentRights(), signDocument(), getSigningStatus(). Full reference at Sign It SDK Reference.

Docs Reorganization

• New three-pillar framing across the homepage, Getting Started, and nav - sovereign login + Sign It + webhooks.
• New /webhooks/ section (overview, events, verification, delivery).
• /sign-it/ section expanded with developer guide, verification API reference, and SDK reference.
• Getting Started now covers four integration patterns - OAuth, Holochain agent linking, Sign It, and webhooks.

---

v3.1

Encrypted Public Entries

Apps can now store private data on the public DHT. Entries are encrypted client-side with lair's xsalsa20poly1305 crypto_box before being committed. Peers replicate the ciphertext for backup, but only the author can decrypt. See Encrypted Entries on Public DHT.

Improved Backups

• @flowsta/holochain v2.1.0 - Backups work while the Vault is locked (after first unlock)
• Auto-versioned snapshots - Each backup creates a new timestamped snapshot (up to 10 per app, oldest auto-rotated). No more overwriting "latest"
• Private data in exports - Encrypted entries are decrypted and included in backup exports for human readability
• Export format v4 - New private_data section with _readme fields and human-readable field names

Reference Implementation

ProofPoll v1.3 demonstrates the encrypted entry pattern with vote rationales (private notes on votes) and draft polls (encrypted until published), plus the complete DNA migration system across 4 versions.

---

v3.0

Flowsta Auth now supports web and desktop applications.

Previously, Flowsta Auth was an OAuth-only service for web apps. v3.0 introduces Flowsta Vault, identity linking for Holochain apps, and new SDK packages - making Flowsta Auth a complete authentication platform for both web and desktop.

New: Flowsta Vault

• Desktop identity manager - Tauri v2 app that runs a local Holochain conductor and lair keystore
• Agent linking - Third-party apps can request cryptographic identity attestations via IPC
• Connected apps management - Users see and control which apps are linked to their identity
• Auto-backups - CAL-compliant source chain backup support
• Data export - Users can export their Holochain data and keys at any time

New: Holochain App Integration

• Identity linking for Holochain apps - Apps add agent-linking zomes and use @flowsta/holochain to link their agent key with a user's Flowsta identity
• IsSamePersonEntry attestations - Cryptographic proof committed to your app's DHT, verifiable by any agent on the network
• IPC server - Vault exposes endpoints on localhost:27777 for app communication
• CAL compliance - Built-in support for Cryptographic Autonomy License requirements (data access, key access, data portability)

New: SDK Packages

• @flowsta/holochain - Agent linking and backup functions for Holochain apps
• @flowsta/auth-tauri (v0.1.0) - OAuth-style authentication for Tauri desktop apps through Vault
• @flowsta/login-button - Pre-built "Sign in with Flowsta" components for React, Vue, Qwik, and vanilla JS

New: Documentation

• Vault guide - Overview, Holochain app integration, agent linking, backups, Tauri apps, IPC reference
• Holochain section - Architecture, identity and DIDs, developer guide
• Security section - Zero-knowledge architecture, data portability
• SDK reference pages - Dedicated pages for each SDK package

Improved

• Getting started - Now covers both web OAuth and desktop Holochain integration paths
• Architecture docs - Two-DNA model, infrastructure diagram, cloud nodes
• Static SVG diagrams - All diagrams are now static SVGs for better SEO and accessibility

No Breaking Changes

Existing OAuth integrations using @flowsta/auth continue to work without changes. All v3.0 additions are new functionality.

---

v2.0

Initial public release of Flowsta Auth.

• OAuth 2.0 + PKCE - Authorization code flow without client secrets
• @flowsta/auth SDK (v2.0) - TypeScript SDK with React bindings
• Zero-knowledge privacy - Client-side encryption with Holochain storage
• W3C DIDs - Decentralized identifiers for every user
• Cross-partner SSO - One account across all partner sites
• Developer dashboard - App registration, analytics, and management at dev.flowsta.com

Breaking Changes from v1.x

• Removed direct email/password authentication from the SDK
• All authentication now goes through Flowsta's hosted login page (OAuth redirect)

// v1.x (removed)
await auth.login(email, password);

// v2.0+
auth.login(); // Redirects to login.flowsta.com
const user = await auth.handleCallback();