The Rust side
Three Rust libraries sit beside @flowsta/holochain. One is required for a linked app. The other two are optional, and you take them one piece at a time.
A Holochain desktop app (Tauri, or anything with a Rust back end) has two places that can talk to the person's Flowsta Vault: the page in the window, and the Rust process behind it. The page uses @flowsta/holochain. This page is about the Rust process: what Flowsta publishes for it, what each library gives your app, and what you can leave out.
The three libraries
| Library | What it is | Where it runs | Do you need it? |
|---|---|---|---|
flowsta-agent-linking | Two zomes that record, on your app's own network, that your app's agent and a Flowsta identity belong to the same person | In your DNA | Required for a linked app |
flowsta-vault-client | Finds the person's Vault from Rust, says which app a call is from, keeps the sign-in on the device, and keeps your app's own device key where a backup can carry it | In your app's Rust process | Optional. Needed once your Rust side calls the Vault or holds keys or profiles |
flowsta-hc-lines | Runs a Holochain conductor and key store inside a desktop app, keeps them running, and stops them cleanly | In your app's Rust process | Optional. It has nothing to do with identity; use it if you want the conductor handled for you |
All three are MIT licensed and public on GitHub. The two libraries for the Rust process are before 1.0: depend on them from git and pin a commit.
What is required
For an app that links its agent to a Flowsta identity:
- A
client_id, and the addresses your app connects from, from dev.flowsta.com. See Register Your App. - The two
flowsta-agent-linkingzomes in your DNA, at the tag for your Holochain version. See Agent Linking. @flowsta/holochainin the page, to ask the Vault for the link (linkFlowstaIdentity) and to tell it when the person disconnects (revokeFlowstaIdentity). The person approves the link in their Vault; that step always starts from the page.- One zome call,
create_external_link, with the signature the Vault returned. Make it from the page or from Rust.
That is a complete linked app. Nothing in Rust beyond your own zome call is required.
What is optional, and what each piece depends on
Take a row when your app needs what it gives. "Depends on" lists the other rows a piece needs first.
Identity and the Vault (flowsta-vault-client)
| Your app gets | Module | Depends on | How to |
|---|---|---|---|
| Rust calls to the Vault that find the right Vault and say which app they are from | vault | The link token from the page's sign-in | Talk to the Vault from Rust |
| The sign-in kept on the device, and a check before each write, so the app works with the Vault locked or closed | identity | vault | Check before a write |
| The person's name and picture shown while the Vault is closed | identity | vault | Show who is signed in |
| Opening the Vault app for the person | vault | Nothing | Open the Vault |
| Your app's own device key in a file, so a Vault backup can carry it | device_seed | Importing the seed into your key store | Keep the device key |
| Backups that never replace a key the person still needs | adopt | vault, device_seed, backups from the page | Back up safely |
| The same key, and so the same author, on a new computer | adopt | The two rows above, and a way to stop your conductor | Carry on from a new computer |
| One profile per Flowsta identity on one install | profiles | identity, device_seed | One profile per identity |
Running Holochain in the app (flowsta-hc-lines)
| Your app gets | Module | Depends on | How to |
|---|---|---|---|
| A conductor and key store started, watched and stopped by the library | supervisor, conductor, keystore | Bundled conductor and key store binaries | Run a conductor |
| Conductors asked to shut down properly at quit, and any left behind by a crash ended at the next launch | process, reap | Nothing | Stop cleanly |
| A start that works with no network, and a device that stays listed for its peers | rendezvous, keeper | The supervisor | Offline starts and staying listed |
| A stopped conductor brought back, and a restart before memory runs out | watch | The supervisor | Keep it running |
| A key's own history restored on a new device (Holochain 0.7) | admin, restore | The supervisor, and the device key from flowsta-vault-client | Restore on a new device |
| Two Holochain versions side by side, and the person's data moved from the old one to the new one | features line-06 and line-07; marker, pass, policy | The supervisor | Two versions side by side |
| A fix for a window crash on Linux computers with NVIDIA graphics | webview | Nothing | The Linux window fix |
Features that need no Rust library
These work from the page alone, through @flowsta/holochain:
- The person's profile fields, with their consent.
- Encrypted backups and reinstall recovery of your app's data.
- Document signing through Sign It.
- Signing in to your web service with the Vault.
- Recognizing a person's other devices: the
get_linked_agentszome call.
Page or Rust: which side does what
| Job | Page (@flowsta/holochain) | Rust (flowsta-vault-client) |
|---|---|---|
| Ask the Vault for the link; the person approves | Yes | No. The approval starts from the page |
| Tell the Vault the person disconnected | Yes | No |
| Post and read backups | Yes | Reads the backup, for the key check and the restore |
| Sign a document, sign in to a web service | Yes | No |
| Find the Vault among its ports | Yes | Yes, and it ignores a Vault that belongs to another user account on the same computer |
| Present your app's origin | The window's origin, set by the system | The origin you choose, so it can match the window's |
| Keep the link token | Browser storage | A file of your app's, set at each start |
| Check the sign-in before a write inside a command | No | Yes |
| Keep a device key, replace it, keep profiles | No | Yes |
The rule of thumb. If the page makes every call to the Vault, and your Rust side never calls the Vault and never manages keys or profiles, your app needs only @flowsta/holochain and the linking zomes. Add flowsta-vault-client when your Rust side does any of these:
- checks who is signed in before a zome write;
- reads the Vault backup (the key check, a restore);
- keeps your app's own device key, or replaces it;
- keeps one profile per identity;
- must ignore another user account's Vault on a shared computer.
Electron and other JavaScript desktop apps
An Electron app has no Rust process, and it does not need one. @flowsta/holochain is the whole Flowsta client there: linking, the link token, link status, backups and restore, signing, and finding the Vault among its ports. Make the calls from the window, which is where the request gets its origin. The linking zomes go in your DNA exactly as for any other app.
Four things to know:
- Serve the window from an origin. The Vault tells apps apart by the origin a request carries. Load your window from a scheme of your own (
app://yourapp, registered with Electron as a standard scheme so that requests carry it) or a local port, and register that origin. A window loaded straight from a file has no origin the Vault can check. - Calls from the main process say which origin they are. Node sends no origin by itself. If your main process (or a tool beside your app) calls the Vault, call
setVaultOriginwith your registered origin first; without it the Vault refuses the request to connect. - Keep the link token with your app's data. The SDK keeps it in the window's storage by default. If you keep a profile per identity, or your app's storage is cleared between runs, store the token yourself and hand it back at startup with
setVaultLinkToken. - The parts on this page that are Rust-only are conveniences built on the public Vault IPC and on plain files: the check before a write, the device key file, the safe order for replacing a key, profile folders, and running the conductor. An Electron app that wants them writes them in JavaScript against the same endpoints. The how-tos on the two library pages describe each one closely enough to follow.
Where the pieces meet
A Tauri app that uses all of it starts like this. Each step is optional except where your own app needs it.
fn main() {
// flowsta-hc-lines: both must run before anything else.
flowsta_hc_lines::process::interrupt_helper_or_continue();
flowsta_hc_lines::webview::apply();
// flowsta-hc-lines: end any conductor a crashed run left behind.
flowsta_hc_lines::reap::reap_orphaned_sidecars(&["holochain", "lair-keystore"]);
// flowsta-vault-client: one client for every Rust call to the Vault.
// (see "Talk to the Vault from Rust")
// flowsta-vault-client: pick the profile for the identity the Vault holds,
// load that profile's link token, then start the conductor in that folder.
}ProofPoll is a complete open-source app built this way: a Tauri app on a shared network, linked to Flowsta, with backups that carry its device key. Its src-tauri/src/ folder has a working version of every how-to on these pages.
Versions
| Library | Version | Holochain | Rust |
|---|---|---|---|
flowsta-agent-linking | tag v0.4.0 | 0.7.1 (hdi =0.8.1, hdk =0.7.1) | 1.94 or later |
flowsta-agent-linking | tag v0.3.0 | 0.6.x (hdi =0.7.0, hdk =0.6.0) | |
flowsta-vault-client | 0.2 | Any; it has no Holochain dependency | 1.93 or later |
flowsta-hc-lines | 0.1 | 0.7.1 (feature line-07), 0.6.1 (feature line-06) | 1.93 or later |
@flowsta/holochain | 3.11.0 | Any |
The link token and the "which app is calling" checks described on these pages apply from Vault 1.8.0. An older Vault ignores the extra fields, so one build of your app works with both.
Next
- flowsta-vault-client: the reference and how-tos for identity, keys and profiles.
- flowsta-hc-lines: the reference and how-tos for running Holochain in the app.
- Build a Holochain App: the linked app, step by step.
- Vault IPC Endpoints: what the libraries send, if you would sooner write the calls yourself.