Forlabs Vault security model (one page)
Forlabs Vault lets an AI agent pay only inside limits a user has signed with a passkey. It records every decision so that tampering is always detectable. We do not claim it is "unhackable".
What we hold, and how
| Asset | Storage | Who can use it |
|---|---|---|
Your PG secret key (e.g. Toss test_sk_…) |
AES-256-GCM. The AAD binds each ciphertext to its tenant and rail. Gate 0 uses an env KEK; KMS/HSM comes after gate 1 | Only the charge path, at call time. Never returned or logged |
| Users' billing keys | Same envelope. The AAD binds each key to its instrument row | Same |
| Your API keys | sha256 only | — |
| User-token key | Ed25519 public key only. You keep the private key | — |
We never touch settlement funds; money moves PG → you.
What a signature means
- The agent can only propose a mandate. It takes effect only when the user signs it with a passkey on our own origin. Signing never happens in your iframe or your app: we send
frame-ancestors 'none'and pin both rpId and origin. - The passkey signs
H(JCS(mandate) ‖ nonce ‖ mandate_id), so the signature covers the exact bytes displayed. Every signed field is shown on screen, and a test enforces this. - The card is part of the signature through
instrument_fingerprint, so a charge on a different card is refused. - User verification (biometric or PIN) is required. Nonces are single-use, and a failed attempt still burns its nonce.
What we enforce
- Limits: per-charge, total, merchant, period and card. Above the approval threshold, the charge needs a passkey approval on the user's phone. That approval is checked against the limits again at the moment of approval.
- Limits come from the signature, not the database row: before every charge and every approval, the vault re-proves the mandate against the user's passkey.
- It checks that the stored body matches its hash, and that the hash and signature match the
mandate_signedchain event. - It checks that the signing key was enrolled on the chain first, that the WebAuthn signature verifies over that body, and that the mandate has not been revoked on the chain.
- Editing a limit in the database therefore stops payments; it does not raise them. The charge is refused with
mandate_integrity_failed, the refusal is recorded on the chain, and you get amandate.integrity_failedwebhook. - Spend accounting: spent = succeeded + reserved + unknown. A payment whose outcome we can't see counts as spent until reconciliation settles it.
- Concurrency: the mandate row is locked while the policy runs. Concurrent charges cannot overshoot the limit (tested).
- Idempotency:
(tenant, Idempotency-Key)is unique. The same key with a different body gets a 409.
How tampering is detected
- Event chain: every state change is appended to a per-tenant hash chain in the same transaction as the change. The table is append-only.
- Signed receipts: every charge response carries an Ed25519-signed receipt
{tenant, seq, head_hash, ts}. You keep the receipts. If anyone, including us, rewrote history, your receipts would no longer match. - Timestamps: every tenant's chain head is timestamped by an RFC 3161 TSA (SSL.com by default) once a day and again at each export.
- A daily anchor proves the events up to that point existed by that time.
- An export anchor proves only when the bundle was made, and is labelled as such.
- If the TSA is down, the export still goes out, says so in the bundle, and the next daily anchor retries.
- PG reconciliation: we pull your PG's full ledger and match it 1:1 against the chain. Any payment that didn't go through the vault shows up as
out_of_mandate. Holding your key does not stop you from re-issuing it at the PG, so this reconciliation is the real guarantee. - Offline verifier:
python -m verifier bundle.json --receipt-key … --origin … --rp-id …checks the evidence bundle with no network access to us: passkey signature, chain, receipts (including the ones you kept), rpId, origin, UV flag, signCount, and a recomputation of the ledger match. The export receipt also signs a hash of the whole bundle, so a change to any byte fails. Pass--tsa-rootto check anchors against a pinned TSA root.
Accepted risks (stated, not hidden)
- First passkey enrollment:
- The vault accepts enrollment on your signed user token alone.
- If your token key leaks, or an insider at your company abuses it, a fake enrollment is possible.
- We detect it rather than prevent it: every enrollment becomes a
credential_registeredchain event and acredential.registeredwebhook to you. - Copy email: sent to the email in your token, which is your claim, not a value we verified. The done page says a copy was sent only after the mail server accepted it.
- Approval link: delivered only through your webhook (and in sandbox responses). Opening it is not enough to approve: approving needs the user's passkey, and the signature covers amount, merchant and the agent's description. Declining needs no passkey.
- Revocation: requires the user's passkey. The signed revocation is recorded on the chain, and the offline verifier checks it.
- Full server compromise: an attacker who controls our code, not just the database, can skip any runtime check. We cannot prevent that before gate 1 (KMS/HSM, tenant co-signing). It cannot go unseen, though: rewriting the record breaks your receipts and the TSA anchors.
- Gate 0 key custody: the KEK lives in the environment. Moving to KMS/HSM is a gate 1 item.
Report a vulnerability
Email support@forlabs.io. We acknowledge within 2 business days.