Backup and restore

A backup is a snapshot of the TessariDB node taken while it serves; the key-encryption key and the pepper are kept apart from it, and a restore needs both.

Everything the server keeps is in its TessariDB store, so a backup is a snapshot of the node, taken while it serves:

TESSARIDB_PASSWORD="$OWNER_PASSWORD" tessaridb --at <store address> --user <owner> --backup oauth.snapshot

Start the node with --encryption-key-file and every snapshot it writes is sealed under that key. Check each one where it was written, before keeping it:

tessaridb --verify oauth.snapshot --backup-key-file <key file>

It says what the file holds and exits non-zero for a file cut short or a wrong key. A passing verify is not a restore: rehearse one.

What a snapshot does not hold

The server's key-encryption key (TESSARIDB_OAUTH_KEK) and its password pepper (TESSARIDB_OAUTH_PEPPER). Without them the restored signing keys cannot be opened and no password verifies. Keep both with the store's encryption key, apart from the snapshots.

Restoring

Replay the snapshot into an empty directory: tessaridb <dir> --restore oauth.snapshot --encryption-key-file <key file>.
Serve that directory.
Start the server with the same key-encryption key, pepper and TESSARIDB_OAUTH_REGION.

Users sign in with the passwords they had, the keys that signed are published again, and refresh tokens issued before the snapshot work. A signing key withdrawn after the snapshot was taken comes back as it stood, so withdraw it again before serving traffic.

Keeping snapshots

Nothing bounds how long snapshot files are kept; delete them on a schedule. Each one holds every account's password hash and every company's sealed signing keys, and an older one brings back sessions, grants and keys that have since ended.