Platform secrets

coming The PlatformSecrets file and the provision secrets commands are a settled design, not in a released version yet. The classes below already describe what an installation holds today.

Four kinds of secret

Kind	Examples	Made by	You supply	Back up offline	Rotation
Encryption keys	TinyVault’s root key, TinyGuard’s encryption key, TinyConductor’s signing-key encryption key	the product’s own init command, once	nothing (or a key in your cloud key service)	yes	on demand, in generations: add a new key, re-encrypt, retire the old one
Platform start-up credentials	database logins, provisioning keys, the break-glass administrator, session keys	the provisioner, or your own secret manager	nothing	no: make new ones and rotate	on demand
Credentials the platform issues	sign-in client secrets, TinyVault access keys	TinyGuard or TinyVault, asked by the provisioner	nothing	no: issue new ones	on demand, with an overlap
Outside credentials	AI provider keys, mail passwords, passwords of your systems	the outside provider	yes, once	in your password manager or secret manager	by their owner, as a new version in TinyVault

So the only secrets you supply are the outside credentials, and the only ones you must back up are the three encryption keys.

Declaring them

apiVersion: tinyblox.ai/v1alpha1
kind: PlatformSecrets
metadata:
  name: production
spec:
  secrets:
    - name: tinyconductor-pg-owner
      shape: { type: basic-auth, username: tinyconductor_owner, password: { random: 32 } }
    - name: tinyconductor-session-keys
      shape: { type: keyring, key: { random: 32 } }
      rotation: { overlap: P14D }
    - name: tinyvault-keys
      source: product                # made by TinyVault's own init command
      backup: offline                # the run warns until an offline copy is confirmed
    - name: tinyvault-pg
      source: supplied               # your database administrator made it; the run only checks it
      shape: { type: basic-auth }

• provision secrets ensure creates what is missing, never overwrites a Secret that exists, and never prints a value.
• provision rotate <name> rotates one secret when you ask. Nothing rotates on a schedule by itself.
• source: supplied is for secrets your own secret manager delivers (for example through the External Secrets Operator): the run only checks that they exist.

Rotation without an outage

Secret	How it rotates
Database runtime login	two logins take turns: the idle one gets a new password, the product moves to it, then the other one changes too
Database owner login	a new password in place; the next migration Job uses it
Sign-in client secret	the identity provider keeps the old secret valid for an overlap window
Session and signing keys	a keyring with a current, a next and a previous key, so nothing signed shortly before stops working
Encryption keys	in generations; the offline copy is updated before the old generation is retired