Thetanuts wallet vault

A hosted authentication and encrypted-storage service for independent applications. Ranger is the first registered client.

Service boundary

The browser generates and imports EOA keys, evaluates WebAuthn PRF, encrypts vaults, decrypts keys and signs transactions. The server stores encrypted vault records, public WebAuthn verification data, and short-lived authentication and revision metadata. The server does not receive PRF outputs, private keys or recovery keys. This service is not a transaction signer or a smart-account service.

The service protects encrypted data at rest. An unlocked wallet trusts the client application's scripts. The API's separate origin does not protect a key from malicious code inside the client page.

Register a client

Registration is an operator-reviewed configuration change. Each application needs an exact HTTPS origin, a host-scoped WebAuthn RP ID and a separate tenant namespace. Ranger uses origin https://ranger.thetanuts.finance and RP ID ranger.thetanuts.finance. The API origin is https://wallet.thetanuts.finance. No wildcard origins, shared parent-domain RP, iframe login or public self-registration is supported. A new client must be configured in both service and copied client modules before it is enabled.

Client requirements

  1. Use discoverable passkeys with required user verification. Verify actual PRF output before calling a wallet encrypted.
  2. Serialize only the specified WebAuthn fields. Never upload PublicKeyCredential.toJSON() or unfiltered extension results: these can include the PRF encryption secret.
  3. Use the version 2 encrypted envelope, fresh IVs, context-bound AES-GCM and per-passkey root-key wrapping. Derive the EOA address again after decryption.
  4. Keep session tokens and decrypted keys in memory. Locking must invalidate signers, pending prompts and pending transactions. Never log credentials, keys, PRF output, ciphertext bodies or authentication tokens.
  5. Use credentials: omit and the exact-origin CORS contract. Every write needs an expected revision and fresh assertion bound to the payload digest. Read back and decrypt before reporting a save complete.
  6. Import wallets additively. Keep a legacy plaintext source until the encrypted record is committed and read back successfully. Preserve unreadable storage.
  7. Pin executable dependencies and enforce a restrictive CSP. Do not add analytics or arbitrary third-party code to a page that holds keys.
  8. Require users to save each EOA private key separately. A synced passkey is not a universal recovery guarantee. Provide an external-wallet fallback if PRF is unavailable.

Independent applications

Each subDAO owns a reviewed copy of the client modules and its site configuration. Vaults and credentials are separate across RPs. Users may explicitly import the same EOA key into another application, including an exported Odette key. The service does not share wallets automatically across sites.

Testing and rollout

Use the exact registered HTTPS origin for passkey tests. The shared thetanuts.finance/dev/ origin is not registered and cannot test Ranger's RP. Never use localhost for this integration. Test real mobile and desktop passkeys, a second device, unsupported PRF, cancellation, recovery, race conditions and both direct and paymaster signing. Deployment and new enrollment are separately controlled. Enrollment is disabled by default.

Protocol API: version 1. Encrypted envelope: version 2. Do not reinterpret unknown versions. See the API contract and current limitations.