The Flow Engine

The Flow Engine moves credentials as flows — directional motion between two devices, from a source into RAM, from RAM into a destination.

A flow is not an import and not an export. An import is also an export from somewhere else; those words pick one endpoint and pretend the other isn't part of the operation. Flow names the motion, not an endpoint, and names it honestly. It also carries the thing that makes the Flow Engine different from every other password-migration tool: no file in between. No CSV. No intermediate JSON on disk. No plaintext anywhere along the path.

The library has one entry point: FlowEngine.run(). Pass a source device to pull into SecuredBox. Pass a destination to push what is already in SecuredBox. Pass both to pull, preflight, and push in one call. A full pull-push flow holds a single-writer lock — a second pull-push flow initiated while the first is running is rejected with a failed event. Pull-only flows run concurrently.

Flows are fire-and-forget. The engine emits four event types and lets the caller handle them. The app renders them in the status bar; the MCP server aggregates them into one JSON response. Whatever the Flow Engine is doing right now, whoever called it can see.

SecuredBox is the RAM-only hub every flow passes through. Sources append BoxItem records to it. Destinations read them out. It is never written to disk, never synced, never exposed over a network. It is cleared on app quit, at the end of a full flow, or when a client calls clear.

Every item is self-aware. A BoxItem knows what fields it actually carries — a Chrome record typically holds only url, username, and password; a KeePassXC record might also carry an OTP seed, a passkey blob, and notes. Every configured device publishes the fields it accepts. The preflight is what happens when the two meet: before a push runs, the Flow Engine computes the field-by-field gap between the working set and the destination's schema and returns a report with the complete event — which fields transfer, which get dropped per destination. A record with only a password (a PIN), only a username (a passkey handle), or only a note is still a credential; destinations handle whatever they're given rather than filter items out.

Every item knows what it has. Every device knows what it wants. Nothing writes until the gap is computed.

The three states

The Flow Engine holds three kinds of state, each in a different place, each with a different lifetime.

Passwords. One-time password seeds. WebAuthn passkeys. Notes. Folders. Custom fields.

Not every device accepts every type. Chrome holds passwords only. KeePassXC holds almost everything. iCloud sits somewhere in between. The Flow Engine's job is to know the gap before the write begins, not to pretend the gap isn't there. The read/write table and the full field-preservation matrix live on the Protools page.