Changelog

v6.7

Vault 1.7.0 runs Holochain 0.7.1: what changes for your app

The Vault moves people's records from the Holochain 0.6 networks to the 0.7 networks by itself, the first time each device unlocks after updating; devices update one at a time and stay in step meanwhile. For your app:

• Nothing has to change, and there is no date. Your app keeps working on whichever Holochain line it runs today. The link signature the Vault makes for agent linking is the same on both lines, and @flowsta/holochain 3.10.3 works with Vault 1.7.0 unchanged; it talks to the Vault, not to a Holochain line.
• When your DNA moves to 0.7.1, depend on flowsta-agent-linking at tag v0.4.0 (integrity 0.3.0, coordinator 0.4.0; hdi =0.8.1, hdk =0.7.1, Rust 1.94+); v0.3.0 stays the 0.6 tag. A DNA rebuilt for 0.7 has a new hash, so it is a new network: your users' data crosses only if your app copies it (Build a Holochain App, Quickstart).
• Flowsta's bootstrap for the 0.7 networks is bootstrap-7.flowsta.com, beside bootstrap.flowsta.com for 0.6; both keep serving, with the same sign-in (Where the devices meet).
• GET /status names the identity only to a page that may know it. agent_pub_key, did and active_identity go to Flowsta's own sites, sites the person remembered, apps the person linked, and local callers; any other page gets null for all three and learns only whether a Vault is installed and unlocked. A web page that read the agent key before linking should link first.
• GET /status also says which Holochain lines the Vault runs (holochain_lines) and which one the person's records are on (records_on); apps need not act on either.

v6.6

One Permanent ID per identity

A DID is did:flowsta: + the agent key the identity signs with now, spelled u + base64url, the same string the Vault's /status reports, the SDK's getVaultStatus() returns and flowsta.com shows as the Permanent ID. An identity that moved into the Vault from flowsta.com takes the DID of its Vault key at the move (Identity); its earlier DID keeps resolving at GET /did/{did} to the current DID, which lists the earlier one under alsoKnownAs. DIDs minted before October 2026 spelled the key as uhCAk + base58; every Flowsta endpoint that takes a DID or agent key still reads that spelling. DID documents now carry the 32-byte Ed25519 key as publicKeyMultibase (z6Mk…).

v6.5

Keeping the devices in step, and showing who is there

A seventh rule and a new section, Keeping the devices in step: post a backup after every change that should travel, not only after Holochain writes - or an item with no data yet never leaves the device it was made on; and poll the backup list once a minute, reading a sibling's copy only when its created_at moved, so changes show in a minute or two instead of five.

New in the Vault IPC: GET /devices (Vault 1.6.1+) lists the person's devices with when this Vault last heard from each. Every unlocked Vault announces itself at least every two minutes, so a device heard recently is reachable now and one not heard is locked, asleep or off - show that, and a change that waits for it explains itself. The Keeping the devices in step section gains the habit.

In the SDK (3.10.2 - 3.10.3), keepRegistered registers each note once, does not read the server's 32-note listing cap as a stall, and judges a stall only on the server the conductor was configured with (conductorServer, registeredElsewhere).

@flowsta/holochain 3.8.0 was never published to npm: its additions (getAppSecret, getAppNetworkSecret, the named-device backup read) first shipped in 3.9.0, and the SDK page now says so.

Content Rights: the commercial option reads "Open to licensing inquiries", as in the Vault from 1.6.1 (the stored value, open_to_licensing, is unchanged).

v6.4

Where your app's devices meet, and keeping a device listed

Two things made explicit after building multi-device sync into Flowsta's own apps. First, where a Holochain app's devices find each other is the conductor's network: config, not the SDK: any kitsune2 bootstrap server works, your users' devices never join Flowsta's networks, and bootstrap.flowsta.com is optional for your app and tied to registering it. Said on Where the devices meet, in Build a Holochain App and on Holochain Architecture.

Second, a sixth multi-device rule, Keep the device listed: a Holochain 0.6 conductor that is awake and cut off for more than 3 minutes across an agent-note re-sign is never listed on its bootstrap again until it restarts (measured 2026-10-19). @flowsta/holochain 3.10.x adds keepRegistered, the restart-free cure Flowsta's own apps ship (3.10.2 registers each note once and knows the server's 32-per-network cap).

v6.3

Open your web app signed in, and a Sign-in UX guide

A desktop app can now send the person to its web app already signed in, with no second Vault approval and nothing to type: openWebSignedIn() in @flowsta/holochain 3.9.0 runs the web sign-in from the desktop app and opens the callback URL with the PKCE verifier in the fragment; @flowsta/login-button 0.2.0 adopts it on the callback page. The web app is declared as the desktop app's companion in the portal (Register your app); the Vault (1.6.1+) signs a web-login challenge only for an app's own client or its companion. Code and what to show the person: Desktop App Authentication. Desktop apps that want no dialog on a return sign-in send their link key as localAgentPubKey; the Vault (1.6.1+) signs silently for a remembered non-browser origin only when it matches.

New page: Sign-in UX - the five Vault states and the one true thing to say for each, why a web page should never probe the Vault itself, one thing at a time, the relay as the person sees it, device identity against web identity, and the copy rules we hold our own apps to.

v6.2

One private network per app, on every device

For apps whose users install them on several devices: Flowsta Vault 1.6.1 adds POST /app-secret, a secret derived from the identity and scoped to your app that is the same on every one of the person's devices, and a device parameter on /backup/retrieve to read one named device's copy; /backup/list names the other devices (name, platform, generation). @flowsta/holochain 3.8.0 (first published as 3.9.0) wraps them as getAppNetworkSecret / getAppSecret and documents the five rules for an app's own data across devices.

v6.1

One identity on several devices

Flowsta Vault 1.6.0 puts one identity on every device the person owns. The new Several devices page covers the two doors (a code shown on the new device and typed on one the person already has, or the recovery phrase), what follows the identity (records, connections as consent, remembered sites, app-backup copies, activity, signatures), who can add devices (the enrollment key and its 7-day rule), removing a device, the locked-but-syncing Vault, and the first minutes after opening.

For apps: nothing in the contract changes; an app links on each device, a Disconnect reaches every device, and a signature from a device's own key resolves to the person. @flowsta/holochain 3.7.0 adds retrieveFromVault({ across: 'devices' }) → fromDevice and listVaultBackups().otherDevices; the bridge reference documents across, from_device, other_devices and label_required. Export Data is format 3.0: every key this device holds and the other devices' backup copies. What the Vault sends home lists the device registry fields.

v6.0.1

Identity switching: removing one identity while others remain selects one of them for the next unlock, and active_identity names it while the Vault stays locked. The Vault holds no identity only after Erase everything or after the last identity is removed.

v6.0

A new shape for the docs, and a lot more of them

The site is now organised by who arrives. The nav reads Start · Web apps · Holochain apps · Sign It · Reference, and every page sits in the door it belongs to.

• Start asks what you are building and sends you to your path in one click. It also holds the pages that explain the model: the Vault, Security & Privacy, Sessions & Tokens, architecture and DIDs.
• Web apps is the OAuth path end to end, with webhooks alongside it and the two web packages at the bottom of the sidebar.
• Holochain apps opens with your options and a clear split between what a linked app must do and what it may add. Build a Holochain app is the step-by-step guide, and Desktop apps covers a desktop app that signs in through the Vault without Holochain.
• Reference gathers the three SDK packages, the REST and OAuth APIs, the Vault's local bridge and the machine-readable index in one place.

Moved pages redirect, so old links keep working.

Identity switching, for app developers

Flowsta Vault 1.5.0 holds more than one identity on a device. The new Identity switching page describes what an app observes, the three rules every Holochain app follows, and the two ways to build for it, with what the person sees in each. The bridge reference documents the new status fields, expected_identity on any request, and the one-Vault-per-computer-account rule.

Publishing signatures from an app

@flowsta/holochain 3.6 publishes a signDocument signature to the Sign It network from the person's own device when the app is linked, so anyone can verify it: publish option, published result, and typed errors for the two refusals. A web app on @flowsta/auth receives a local signature, and 2.6.1 returns the signature bytes. Sign It developer guide.

Desktop sign-in through the Vault

The desktop flow is written for a third-party app: your backend issues a nonce, the Vault signs it, your backend verifies and issues its own session. Desktop apps.

The agent-linking zome is public

Depend on flowsta-agent-linking at tag v0.3.0; the README carries the HDK pins. Its integrity zome lets only the two linked agents revoke an attestation or write its lookup links.

Reference pages, complete

The bridge reference now covers every route and error code the Vault emits and the flowsta:// links. The holochain SDK reference covers every export through 3.6, with a scenarios table for what each call does in each Vault state. Webhooks states exactly which events fire for whom. Sessions & Tokens describes the token model as it is. Every diagram renders in light and dark mode.

v5.15

Vault 1.5.0 - more than one identity, and one Vault per computer account

Flowsta Vault 1.5.0 holds more than one identity on a device: add another, created new or brought with its recovery phrase, choose one at unlock, and switch between them. One identity is open at a time, and apps follow the one that is unlocked. The Vault answers only processes of its own computer account, so on a shared computer each account's browsers and apps reach that account's own Vault.

For apps, GET /status gains active_identity (held even while locked), identity_epoch, instance_id, claims and initialized. Any request can carry expected_identity to pin the identity it acts for, and a Vault holding another refuses it (409 identity_mismatch). Linking an app agent already linked to another identity is refused with 409 agent_linked_elsewhere, and a Vault in another computer account answers 403 other_user. IPC reference. @flowsta/holochain 3.5.0 reads all of this already. holochain.

v5.14

Sign It: what a record holds, and the Permanent ID

Sign It now states exactly what a signature record holds on the network (hash, signature, key, time, intent, AI disclosure, content rights, integrity report, perceptual hash, edit chain, expiry, tags, public note, the signer's thumbnail, any revocation) and what is not there: the file, the file's name, and the display name, username and picture, which are Flowsta's record of who holds the key. A thumbnail is the signer's preview, not evidence; "Verified" is defined in one line. Identity & DIDs explains the DID the way the Vault now labels it: the Permanent ID, how your signatures and sign-ins prove they came from you.

v5.13

The docs site itself: real redirects, real 404s, and an index for AI assistants

Moved pages now answer with a permanent redirect instead of the home page: the old /oauth/* addresses go to /auth/*, and /vault/agent-linking goes to Agent Linking. An address that does not exist returns a 404 page and status. Every internal link is checked at build time. llms.txt is generated from the site's own navigation on every build, with the published package versions and the rules every integration shares, and llms-full.txt carries the full text of every page for assistants that read one file.

@flowsta/holochain 3.5.0 is published (additive): getVaultStatus returns activeIdentity, identityEpoch and instanceId when the Vault reports them, resolveVaultUrl prefers a locked Vault that holds your bound identity over an unlocked one holding someone else, onIdentityChanged compares the epoch, and the GET calls send expected_identity when bound. The Vault fields arrive with Flowsta Vault 1.5.0. holochain.

v5.12

Vault 1.4.0 - your data is kept per identity

Flowsta Vault 1.4.0 stores everything that belongs to a Flowsta identity - its keys, private records, links and app backups - in that identity's own folder on the device. An existing Vault moves its data there the first time it is unlocked; nothing changes in how you use it. This is the groundwork for switching between identities on one device in a later release. Security overview.

Restoring got a straight path: after a recovery-phrase restore the Vault asks whether to import your export or continue without, importing also puts your email back (confirmed against the account first), and a freshly restored Vault says "Syncing from the network" until your signatures have returned. The Your Data page now reads Export Data / Import Data with Export / Import buttons. Data portability. No change to the Vault's local bridge in this release.

@flowsta/holochain 3.3.0 (additive): partitionKeyFor(agentPubKey) gives apps the same per-identity key the Vault uses for its folders, so an app that keeps data for more than one identity can name its storage without writing the agent key into a name; getBoundIdentity() is documented as one slot per origin. holochain.

v5.11

Vault 1.3.0 - the email is decided in the Vault, and a password change cannot strand a Vault

Flowsta Vault 1.3.0 lets an app ask for the user's email in the Vault's own dialog: POST /authenticate takes scopes, shows the address that will be shared, and returns email + email_verified when the user allows - the same grant is filed with Flowsta, so the web consent page no longer asks anyone to type their address and GET /status serves it to linked apps that hold the grant. Only verified addresses are ever offered. Remembered sites now persist across lock and restart (the docs said "session-scoped"; that was true until 1.3.0), and a sign-in arriving at a locked Vault is held through the unlock. GET /backup/list lists each app's stored labels. In the Vault itself: email confirmed twice at setup, an email change from Settings, and a password change that is now all-or-nothing with a key store that repairs itself.

@flowsta/holochain 3.2.0 (additive): authenticateWithVault gains clientId + scopes and returns email / emailVerified; getVaultStatus and listVaultBackups expose the new fields. holochain.

A Vault restored from its recovery phrase now asks for the registered email once (Flowsta holds only its hash and confirms the match; POST /auth/confirm-email), so email sharing works again after a restore. The Vault also gains an Activity page: every sign-in (and whether a remembered site let it through), every email shared with an app or withdrawn, sites remembered and forgotten, apps unlinked, email and password changes, and identity setup - newest first, grouped by day, next to signatures, backups and links. Kept on the device only; the Overview shows the latest three.

Sign in with Flowsta: on a computer, the identity in the Vault outranks a remembered browser session. A session for a different identity is dropped and the sign-in runs again through the Vault; a locked or closed Vault is unlocked or opened first. How Flowsta accounts work.

v5.10

Which browsers reach a local Vault - corrected

The Vault sign-in docs said only Chromium browsers could reach http://127.0.0.1 from an HTTPS page. Verified against the browsers themselves: Firefox can too (loopback has been exempt from its mixed-content blocking for years), and Chrome 142+ asks for a Local Network Access permission before the first request - a denied permission looks like an absent Vault, so integrations should say so rather than "install the Vault". Safari still blocks the loopback, Brave blocks it silently unless the site is on Brave's allowlist, and phones have no Vault - those use the relay login. Sign in with your Vault and relay login updated.

SDKs: @flowsta/holochain 3.1.0 + @flowsta/auth 2.5.0 - "blocked" is not "not running"

Both packages now tell a browser-refused loopback request apart from an absent Vault: getVaultStatus() / detectVault() return blocked: true, and the Vault-dependent calls throw the new VaultBlockedError (vault_blocked) instead of VaultNotFoundError / VaultRequiredError. loopbackPermissionState() is exported from both. Vault probes declare targetAddressSpace: 'loopback'. Additive, no breaking changes. holochain · auth.

v5.9

SDK majors on npm: @flowsta/holochain 3.0.0 + @flowsta/auth 2.4.0 - and the docs now match

@flowsta/holochain 3.0.0 is a breaking release: error states can no longer be mistaken for "no data". retrieveFromVault returns null only for a CONFIRMED absent backup - an unreachable Vault throws VaultNotFoundError, a locked one VaultLockedError, a slot holding another identity's backup the new IdentityMismatchError, an unreadable slot FlowstaHolochainError; restoreFromVault propagates the same. backupToVault now guards itself on every write (the empty-over-non-empty refusal moved in from startAutoBackup, plus the bound-identity check). New: identity binding (linkFlowstaIdentity records who it linked with; write-shaped calls refuse a definite mismatch) and the Vault port sweep (127.0.0.1:27777-27779, resolveVaultUrl). Migration notes ride the package README.

@flowsta/auth 2.4.0: signFile() refuses to sign through a Vault holding a different identity than the signed-in user (VaultIdentityMismatchError - a new failure mode existing integrations should handle); detectVault() sweeps ports 27777-27779; agentKeysMatch exported.

Every SDK-facing page is updated to the new contract: the @flowsta/holochain reference (null-vs-throw semantics, the three write guards, identity binding and port-sweep sections, error and function tables), the @flowsta/auth reference (mismatch error, error table, agentKeysMatch, consented-email wording), and every code snippet that would now behave differently (restore examples gain try/catch; signing examples gain the mismatch branch). Also corrected while sweeping: fixed-port claims across six pages, email dropped from login-button example scopes (it's not a default and fails invalid_scope when unregistered), and the Sign It examples' profile scope replaced with real scopes - profile was never a valid scope.

v5.8

Authorship survives machine death: seed escrow for shared-DHT apps

The recognition recovery model grew its missing half. A shared-DHT app's records survive device loss on the network - but the agent key that authored them used to die with the machine, so a reinstall meant a new agent and orphaned authorship. Now the app generates its 32-byte agent seed app-side, imports it into lair, and escrows it in the canonical backup's app_keys block (device_seed_hex + version); on a new machine the app adopts the escrowed seed and continues as the same author - publish a poll, lose the machine, restore, and the poll still shows you wrote it. The recovery-model table row for shared DHTs now reads "recognition + seed adoption", and the new Seed adoption section documents the safety-critical ordering contract for the adopt step: stop processes platform-correctly, wipe key-derived state with verified removal, commit the seed only after the wipe is proven, abort changing nothing otherwise.

The Backups guide also gains a pipeline diagram (one payload → encrypted Vault storage, Your Data, the CAL export → restore by recovery model), and the Holochain overview now links the backup story prominently - it's a core part of the offer, not a footnote.

A second write guard joins the empty-backup rule from v5.5: an app whose payload carries app_keys must refuse to overwrite a backup escrowing a different key than its local one - without that check, a fresh install's first auto-backup would destroy the very key the user needs to restore. ProofPoll (v0.3.0) is the live reference for the whole model: device_seed.rs for seed generation and escrow, seed_adopt.rs for the adoption engine, the write guard, and the two-step restore UX. The CAL §4.2.1 section, Building Holochain Apps, Data Portability, and the IPC reference's app_keys schema are updated to match; guidance that previously said "back up the lair keystore" now points at escrow-and-import - lair-born seeds can't be extracted, which is exactly why the seed is born app-side.

v5.7

Backups grow with your data: per-object storage

Vault backups are no longer one snapshot per app. Named backups are app-managed objects that are never auto-rotated - store one per conversation, document, or whatever your data's natural unit is - while label-less timestamped snapshots keep the familiar keep-the-newest-10 rotation. The size cap is per object (50 MB), not per app: split large payloads into named parts, and read the cap from the new GET /backup/limits endpoint instead of hardcoding it. Compressed payloads ride the new data_base64 field with a gzip content_type - stored and returned byte-for-byte, and still human-readable in the user's Your Data exports, which the Vault decompresses for reading. The Your Data page presents per-object apps as what they are ("611 conversations") rather than a pile of snapshots.

Requires the Vault release carrying per-object storage; older Vaults respond 404 to /backup/limits - treat that as the single-snapshot world.

v5.6

The Vault sends less home: usage records are now two fields

Developer billing now counts active connections - how many accounts were connected to an app in a month - and the Vault's monthly usage record is exactly that: client_id + month_year, which app and which month, nothing else. No analytics ID, no use counter, no timestamps leave the device; the server derives its own opaque pseudonym for counting, and that pseudonym never travels anywhere. What the Vault Sends Home documents the record field by field.

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) is cited as the live reference.

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 an 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();