Skip to content

Using FactorSeal

Platform Biometric method Intended hardware binding Status
macOS Touch ID Keychain/Secure Enclave key-use policy Implemented; physical-device release acceptance remains
Windows Windows Hello fingerprint, face, or PIN TPM sealed-data object nested inside Windows Hello PRF encryption Implemented; physical-device prompt and policy acceptance remains
Linux No portable built-in biometric path TPM 2.0 supports hardware wrapping, but fprintd does not provide a hardware-bound secret Password-backed TPM unlock only

The vault encryption and ML-DSA signatures are designed to resist quantum attacks. Native biometric enforcement still inherits the cryptographic and certification properties of Secure Enclave or Windows Hello, so Factorseal does not claim that those complete platform paths are post-quantum certified.

Factorseal requires a supported platform enclave: TPM 2.0 on Linux and Windows, or Secure Enclave on macOS. Software keyring and DPAPI-only fallbacks are rejected. Once the factorseal binary is installed, create a vault:

Terminal window
$ factorseal init

When run in a terminal, initialization briefly introduces the vault and asks you to choose password, biometric, password AND biometric, or password OR biometric unlocking. The default is password. It then creates the hardware-protected vault, authorizes that exact CLI executable for the durable keyring, and leaves the vault sealed. Non-interactive initialization also defaults to password unless --unlock is passed explicitly.

Password slots use memory-hard Argon2id by default. Deployments that require a NIST-standardized algorithm profile can opt into PBKDF2-HMAC-SHA-256 with factorseal init --fips. This selects algorithms suitable for a future validated provider boundary; it does not make the current build FIPS validated.

Unlock policies use AND inside one comma-separated group and OR between repeated groups. Platform hardware binding is implicit in every group:

Terminal window
$ factorseal init --unlock password,biometric
$ factorseal init --unlock password --unlock biometric
$ factorseal init --fips

The first policy requires password AND biometric approval. The second accepts password OR biometric approval. A biometric-only policy does not ask for a Factorseal password. The first repeated group is the preferred unlock method; override it when starting the agent, for example factorseal agent --unlock biometric.

Start an unsealed service in one terminal:

Terminal window
$ factorseal agent

Or use the separately packaged graphical host:

Terminal window
$ factorseal desktop

Desktop initializes and unseals the same vault through a dedicated CLI worker, which hosts the authenticated endpoint. On Linux, Desktop hosts the org.freedesktop.secrets adapter and accesses the worker through authenticated IPC. The GUI releases its unlock password after handoff; the worker wipes that factor before serving. Install the CLI alongside Desktop or set FACTORSEAL_CLI_EXECUTABLE to its absolute path. It is an alternative to factorseal agent, not a client of it, so do not configure both to autostart. Repeated Desktop launches activate the existing per-vault instance. On Linux, the Desktop package registers D-Bus activation for org.freedesktop.secrets. Desktop keeps answering while sealed, but credential searches open a compact access dialog and resume after approval and authentication. Native socket and SecretSpec clients also require Desktop to be unsealed first. Request parsing and personal sync run in separate confined helper processes installed beside the CLI. On Linux the sync helper requires Landlock ABI 3, so personal sync needs kernel 6.2 or later; distributions such as Debian 12 and Ubuntu 22.04 ship older kernels and cannot run it. The parser helper works on every supported kernel. Sealing removes the native service endpoint and all unwrapped vault keys.

If the vault does not exist yet, factorseal agent stays alive, logs the initialization instruction, and continues automatically after factorseal init creates it. Packaged background launchers use this same behavior on every desktop platform.

Then store a durable project secret from another terminal:

Terminal window
$ factorseal set --project my-app github --field token
$ factorseal get --project my-app github --field token
$ factorseal delete --project my-app github --field token

Browse project and address metadata without retrieving any values:

Terminal window
$ factorseal projects
"my-app"
$ factorseal list --project my-app
{"kind":"native","coordinates":{"item":"github","field":"token"}}

Show what changed in a project, newest first, without reading any value:

Terminal window
$ factorseal history --project my-app
{"version":1,"seq":1,"at":1756742400,"operation":{"type":"delete"},"address":{"domain":"secret_spec","address":{"kind":"native","coordinates":{"item":"github","field":"token"}}},"previous_version_id":"…","provenance":{"source":"caller","principal":{…}},"device_key_id":[…]}

An entry names the address, the operation, the value version it created or replaced, and the transport-authenticated caller or service reason it was performed for. It never contains the value itself.

All three commands follow every bounded vault cursor automatically. Pass --json to emit one JSON array instead of JSON-quoted projects or one compact object per line.

set prompts without echo when standard input is a terminal. It can also read exact bytes from standard input or --value-file:

Terminal window
$ printf '%s' 'secret value' | factorseal set --project my-app github --field token
$ factorseal set --project my-app github --field token --value-file ./token.bin

--project may also come from SECRETSPEC_PROJECT. Without --field, the CLI stores a conventional SecretSpec address using --profile (which defaults to default). With --field, it stores a native SecretSpec address. get writes the exact stored bytes without adding a newline. factorseal status reads validated public metadata without unsealing and reports whether a matching service is reachable.

Replacing or upgrading the binary changes its executable digest. Stop the service and run factorseal grant-cli to authorize the new CLI executable. The project approval must also be renewed for the new executable.

Seal the running service immediately when it is no longer needed:

Terminal window
$ factorseal seal

Create or restore a portable, versioned FactorSeal archive while the vault is unsealed:

Terminal window
$ factorseal export backup.factorseal
Archive passphrase:
Confirm archive passphrase:
$ factorseal import backup.factorseal
Archive passphrase:
$ factorseal import backup.factorseal --replace-existing

Native archives include every portable vault document and are encrypted with AES-256-GCM using a separate Argon2id-stretched passphrase. For unattended jobs, use --passphrase-file with a private regular file (mode 0600 on Unix). Imports preserve existing entries unless --replace-existing is explicitly passed. Exports read the live vault and fail if its contents change during collection; retry the export in that case. Linux keyring metadata and values restore together, preserving unrelated destination items. Archive v2 readers also convert v1 archives during import.

Password-manager formats operate on Personal Secrets only:

Terminal window
$ factorseal import bitwarden.json --format bitwarden-json
$ factorseal export onepassword.csv --format 1password-csv
$ factorseal export keepass.csv --format keepass-csv

Bitwarden JSON, 1Password CSV, and KeePass CSV are plaintext formats. FactorSeal prints a warning and writes exports through a private temporary file before atomically replacing the destination. Exports reject items whose fields or metadata the selected format cannot preserve; use an encrypted FactorSeal archive for a lossless backup. Duplicate imported titles receive stable, collision-free suffixes.

For an open credential interchange format, use CXF 1.0 encrypted with age:

Terminal window
$ factorseal export credentials.cxf.json.age --format cxf-age
Archive passphrase:
Confirm archive passphrase:
$ factorseal import credentials.cxf.json.age --format cxf-age
Archive passphrase:

In desktop, choose Transfer credentials, then Encrypted transfer. Choose Back up vault to create or restore a FactorSeal backup; that flow selects the backup format automatically. --passphrase-file and --replace-existing work as with native archives.

For encryption to a recipient’s hybrid post-quantum key, generate a key with age 1.3 or later:

Terminal window
$ age-keygen -pq -o identity.txt
$ age-keygen -y identity.txt > recipient.txt
$ factorseal export credentials.cxf.json.age --format cxf-age --recipient-file recipient.txt
$ factorseal import credentials.cxf.json.age --format cxf-age --identity-file identity.txt

Share recipient.txt with the exporting device and keep identity.txt private on the importing device. Desktop exposes this as Post-quantum key, with a file chooser for the public recipient or private identity. Both interfaces accept exactly one hybrid key per file, with standard age comments and blank lines. Private identity files must be unencrypted and accessible only to your account. Classical age keys and SSH keys are rejected; key-file options cannot be combined with --passphrase-file. FactorSeal does not need an external age executable to encrypt or decrypt.

Hybrid mode uses ML-KEM-768 + X25519. Both age modes retain the standard 128-bit file key; hybrid mode does not raise that to 256 bits. Passphrase mode uses symmetric encryption and its security also depends on passphrase strength. See the age post-quantum security rationale.

The contents follow FIDO’s Credential Exchange Format 1.0, March 2026 errata; the file uses the open age v1 encryption format. No plaintext intermediary file is created. A standard age implementation can decrypt the file independently of FactorSeal, although destination managers may require that decryption step and must support CXF JSON import. This does not implement CXP. An opt-in macOS 26 desktop integration adds Apple’s system credential-transfer interface and a bundled credential-provider extension. It remains experimental pending live Apple Passwords acceptance.

CXF exports cover Personal secrets. Logins and API credentials use standard credential fields, verification-code seeds use standard TOTP credentials, and other text fields use labeled, typed custom sections. Small FactorSeal extensions retain local field types, section order, folders, and archive flags; other managers may ignore those extensions. TOTP URIs normalize during import. Re-export preserves imported CXF accounts, collections, and unknown properties while applying edits and removing deleted fields. Conflicting account metadata, raw edits to unsupported credentials, and source data from other formats block export before the destination file is changed. CXF file references without an attachment transport block import. Unknown credentials, including passkeys, are preserved as source data and reported as lacking full functional support; retaining a passkey does not enable authentication with it.

Keep using .factorseal for complete portable backups, including project addresses, system-keyring metadata, and expiry deadlines. Its existing v1/v2 readers remain compatible. After migrating, keep the old vault as a fallback and verify important credentials before relying exclusively on the new vault. See credential exchange design for the format boundary, resource limits, and compatibility tests.

Desktop imports show the validated item count and unsupported-data count before writing. For a CLI preview, add --dry-run to factorseal import; it validates the whole input without connecting to a vault. Imports commit individual records. If interrupted, retry the same input without --replace-existing to keep records already imported, including a write whose response was lost.

Personal items use a versioned record with a stable ID, category, ordered sections, and typed fields. Templates cover logins, secure notes, cards, identities, SSH keys, API credentials, passports, bank accounts, documents, and generic secrets. Fields have independent IDs and labels, so repeated labels and multiple passwords are supported. The desktop creation form offers templates and custom fields; values use masked, locked-memory input, including multiline values.

Existing v1 records and UTF-8 secret values migrate on read; subsequent writes use v2. Native encrypted archives retain all sections, fields, and source metadata. Unknown CSV columns become concealed custom fields. Bitwarden custom-field types and linked-field IDs are preserved. Unmapped Bitwarden properties are retained in encrypted source metadata and prevent exports to formats that would discard them.

Import 1Password’s richer export with:

Terminal window
$ factorseal import account.1pux --format 1password-1pux

1PUX v3 imports preserve sections, typed values, source metadata (including password history), and files. Files are currently stored as separate document items; source metadata retains their document IDs. The importer never extracts ZIP paths to disk, limits expanded archives to 128 MiB, and rejects missing referenced files. Each encoded personal item is limited to 512 KiB to fit the vault protocol. An oversized item fails preparation before any imported items are written. 1PUX is import-only; use an encrypted FactorSeal archive to back up these richer records. Preserving passkey or other unrecognized source data does not make it usable for authentication.

Desktop can pair devices using QR codes or tickets with explicit code approval and exchange encrypted personal-item changes through an iroh courier. Once configured, the courier can continue transferring ciphertext while Desktop remains open and the vault is sealed. Applying changes requires the vault worker to be unsealed. Project secrets, application grants, and device keys remain local. The mobile app pairs the same way and scans QR codes with the camera.

Sync is experimental. Peer application receipts, a conflict-resolution chooser, and controller transfer and removal UI are still missing. A connected peer does not confirm that it has applied your changes. Personal history includes old and deleted values, and newly enrolled readers receive that history. Sync does not replace a portable backup.

See the personal sync boundary for protocol, history-retention, and platform limitations.

FactorSeal keeps local crash reports and bounded operation logs for Desktop, the CLI, and vault workers. Export them from Desktop’s Settings → Diagnostics, or run factorseal diagnostics --output factorseal-diagnostics.json without unlocking the vault. Desktop can automatically submit crash reports when a Sentry DSN is configured; its Diagnostics settings control submission. See the diagnostics guide for storage, privacy, retention, and crash-capture limits.