Appearance

Changelog ​

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 recognises 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.

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

  • linked — Vault is running and recognises the app's agent
  • unlinked — Vault is running but does NOT recognise 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.

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 ​

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/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:

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 organisation: 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 Reorganisation ​

  • 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)
typescript
// v1.x (removed)
await auth.login(email, password);

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

Documentation licensed under CC BY-SA 4.0.

Copyright © 2025-2026 Flowsta