platform
Credential vault
CatState never stores plaintext provider tokens. Credentials are sealed with AES-256-GCM under a per-credential data-encryption key, itself wrapped by a KMS master key.
Envelope encryption
When you register a provider credential, the platform requests a unique 256-bit DEK from KMS — one per credential row, never shared across your org's other providers. The credential is encrypted with AES-256-GCM (96-bit IV, 128-bit auth tag); the ciphertext, encrypted DEK, IV, and tag are stored together in PostgreSQL.
plaintext token│▼ AES-256-GCM ◄── per-credential DEK ◄── KMS master key│ciphertext_token + ciphertext_dek + iv + auth_tag → PostgreSQL
If a decrypted DEK is ever exposed, the blast radius is one provider link — not your entire org.
Registering a credential
cred = cs.vault.add_credential(provider="ibm",token="...", # sent once over TLS, never storeddevice_allowlist=["ibm:brisbane", "ibm:osaka", "simulator:*"],default_routing_strategy="BEST",)print(cred.status) # ACTIVE (health-checked on creation)
Decryption & zeroization
Provider tokens are decrypted only inside transient worker memory during outbound dispatch. The plaintext lives in a mutable bytearray that is explicitly zeroed with a memset after the request completes — never converted to an immutable string, never logged, never included in telemetry.
Rotation
Credentials are health-checked on creation, on dispatch failure, and every 6 hours. Rotating is zero-downtime: the new version takes over for future jobs while in-flight jobs finish on the old credential, which is soft-deleted once drained.