Key Management & Sovereignty

The core of Planbok's security model is the absolute sovereignty of the user or organization over their assets. We achieve this through a "Blinding" mechanism that ensures Node 1's share is cryptographically locked by entropy that Planbok does not control.

The Blinding Mechanism

In self-custodial and trustless models, Node 1 does not store its key share in a usable state. Instead, it stores a Wrapped Share. To unwrap this share, a "Blinding Secret" must be provided by the client during every sensitive operation.

1. PIN-Blinding (Customer Custody)

For individual users, the blinding secret is derived from their personal PIN.

• Argon2id Hashing: The PIN is hashed client-side using Argon2id with a unique salt. This ensures resistance to brute-force and GPU-based attacks.
• Zero-Knowledge: Planbok never receives the PIN. We only receive the high-entropy result used to unwrap the share.
• Client-Side Storage: The salt required for hashing is stored in the user's browser or mobile app, adding a "something you have" factor to the "something you know" (the PIN).

2. Organization Secret (Trustless MPC)

For organizations requiring the highest level of sovereignty, we provide a Trustless MPC mode.

• Master Entropy: During organization registration, a 32-byte Organization Secret is generated and encrypted for Node 1.
• Cryptographic Barrier: Every organizational transaction must include the Encrypted Organization Secret. Without it, Node 1 cannot participate in the signing protocol.
• Recovery: The Organization Secret is the sole key required for independent Private Key Export.

Standard MPC (Managed Sovereignty)

Standard MPC is designed for businesses that prioritize operational velocity and native institutional management.

• Automated Signing: In this model, both Node 1 and Node 2 shares are managed within Planbok's secure infrastructure.
• Vault-Backed Encryption: Shares are encrypted at rest using hardware-backed secrets (HSM/Vault).
• Control via RBAC: Security is enforced through authenticated API sessions and granular Role-Based Access Control, allowing for high-frequency treasury operations without manual secret injection.

Security Model Comparison

Ciphertext Rotation

Planbok enforces Ciphertext Rotation to maintain high security hygiene without requiring a migration of funds to new wallet addresses. When a user updates their PIN or an organization rotates their secret ciphertext:

1. Secret Retention: The underlying Entity Secret (the entropy that generates the keys) remains unchanged to ensure wallet addresses stay consistent.
2. Ciphertext Re-wrapping: The client-side re-encrypts (re-wraps) this secret with the new PIN or secret using a fresh IV.
3. Encrypted Update: This new ciphertext (wrappedSecret) is updated in Planbok's database.

This ensures that even if an old ciphertext was somehow compromised, it would be useless after a rotation as the client now requires the new PIN to unlock the current ciphertext.

API Key Rotation

Separately from wallet key material, Planbok periodically rotates the internal key it uses to store API keys. API keys themselves are never stored in readable form: what we keep is a one-way digest, so rotating the digest key would normally invalidate every stored digest at once.

To avoid taking anyone offline, rotation runs through a 30-day window:

1. Re-digest on use. The first time an API key is used after a rotation begins, it is silently re-digested under the new key. Nothing changes for the caller. Most active integrations migrate within minutes.
2. Window closes at 30 days. Any key that was not used at all during the window is retired, because 30 days of continuous inactivity means the integration is dormant rather than merely quiet.
3. Explicit error. Attempting to use a retired key returns 401 with a message stating that the key was not used during the rotation window and has been revoked. This is distinct from the error for an unknown key, so you can tell a dormant key from a wrong one.

What you need to do

Usually nothing. Active keys migrate on their own, and you do not need to rotate or reissue anything.

If you hold an API key that you use less often than every 30 days, either use it once during a rotation window or replace it with a new one. You can create and revoke keys at any time from your organization dashboard.

Why we do it this way

Retiring dormant keys is what allows the previous digest key to be deleted from our infrastructure rather than retained indefinitely. Keeping the old key around forever to recognise a dormant key would defeat the purpose of rotating it. A 30-day window is the balance: long enough that any live integration will call at least once, short enough that the old key does not outlive its usefulness.

A note on scope: magic-link sign-in tokens are digested with the same mechanism but are valid for 11 minutes and consumed on first use. They expire on their own and are unaffected by this policy.