Security and retention guidance
Operational guidance for running bide where an auditor will later ask you to prove what happened. It covers key custody, journal retention and archiving, backups, clocks, and least-privilege database roles. bide is a library: the runtime does not manage keys, retention or database permissions, so these are your controls. The threat model says what each control defends against.
Statements about bide's behavior cite the code or the guide that specifies it. Recommendations are marked as such and are not requirements of the library.
Key custody
Four kinds of secret and key exist in a deployment.
| Key | Used for | Held by | Compromise means |
|---|---|---|---|
| Tree-head (log) signing key | Signs tree heads, evidence seals, run certificates | The deployment, through an audit.Signer | Whoever holds it can sign a self-consistent forged log; only a head anchored elsewhere exposes it |
| Grant issuer key | Signs delegation grants; deliberately distinct from the tree-head key | The principal that issues authority | Authority can be minted in that principal's name |
| Approver keys | Each approver signs decisions over the exact call | Each approver | That approver's vote can be forged (a quorum needs k keys) |
| Webhook secrets | HMAC of notifications | Sender and receiver configuration | Notifications can be forged to that receiver |
What bide does today:
- Signing goes through the
audit.Signerinterface (Alg,PublicKey,Sign):Ed25519Signer,MLDSASignerandHybridSignerhold a key in process memory, and the shipped demo andbide initproject write keys as files (the demo writes the log seed with mode0600). Four signers keep the key outside the application:signer/pkcs11(Ed25519 throughCKM_EDDSA, or ECDSA P-256 throughCKM_ECDSA; tested against SoftHSM2 only, no hardware HSM tried)signer/awskms(Ed25519 or ECDSA P-256; tested against a fake KMS client only, never against AWS),signer/azurekv(ECDSA P-256 only, since Key Vault has no Ed25519; an HSM-protected key is required unlessAllowSoftwareKeyis set; tested against a fake client and the Azure SDK's in-process fake server, never against Azure) andsigner/gcpkms(Ed25519 or ECDSA P-256 through Google Cloud KMS; tested against an emulator and a fake client only, never against Google Cloud). The PKCS#11 signer takes the PIN from an environment variable or a file, the cloud signers authenticate through the cloud SDK's own credentials and never see them, and all four refuse a token or key of the wrong scheme. Under Ed25519 AWS KMS signs at most 4096 bytes, which a tree head with a very long run ID can exceed (evidence seals are 60 bytes and fit); under P-256 there is no limit. The Google Cloud KMS signer requires an HSM-protected key version by default; Google keeps Ed25519 keys in software only, so a bank that needs an HSM-protected Google key uses ECDSA P-256, and Ed25519 needsgcpkms.Config.SchemeandAllowSoftwareKey. There are no ML-DSA or hybrid keys in a token (key custody guide, known limitations). - Approvers whose keys are in a token or KMS decide from a terminal with
bide-hsm approve(a separate program built from source, since the PKCS#11 library needs cgo and thebidebinary is pure Go and reproducible). It names the key by a PKCS#11 URI or a KMS key ARN, takes the PIN from a file (mode0600) or an environment variable and never from the reference, and refuses a PKCS#11 key the token does not mark non-extractable unless told-allow-extractable. It is tested against SoftHSM2 and a fake KMS client only (key custody). - Verification never needs a private key. Auditors need only the public key, which must reach them out of band (
bide audit -pubkey), never from the bundle being checked. - The runtime does not rotate, revoke or escrow keys.
Recommendations:
- Separate the keys. The log key, the grant issuer key and each approver key are held by different principals. Do not let the application tier hold a key that lets it re-sign history without a check elsewhere.
- Keep the log key out of the application database and image. Load it from a secret manager or a mounted file with mode
0600owned by the service account. Never pass keys on the command line or in environment dumps, and keep them out of logs. - Use a signer that does not export the key (HSM or KMS) when one is available to you:
signer/pkcs11,signer/awskms,signer/azurekvorsigner/gcpkms, or your ownaudit.Signerover its signing call. Test the signer against your own token or key before relying on it, and setRequireNonExtractableon the PKCS#11 signer soOpenchecks the token marks the key non-extractable. - Anchor. Publish every signed head to a separate trust domain (
audit.NewAuditedStorewith anAnchor): another account's write-once storage, a transparency log, a timestamping service. Without it, tamper-evidence does not hold against whoever controls the database and the key (security model).anchor/awss3is the shipped one: an S3 bucket under Object Lock in compliance mode, in a separate AWS account, with the writer role from anchoring (no delete, no governance bypass), a retention at least as long as your journals, a bucket policy and service control policies that the application's administrators cannot change, and CloudTrail data events for the bucket delivered to a third account.anchor/gcsis the equivalent for Google Cloud: a bucket with a locked retention policy in a separate project, with the writer role from anchoring in Google Cloud Storage, organization policies and IAM deny policies the application's administrators cannot change, and Data Access audit logs sunk to a third place. Run and trail IDs either anchor must hold no personal data, since the anchor cannot be erased. - Rotate on a schedule and on suspicion, and never delete old public keys. Evidence signed under a retired key still needs that public key to verify. Keep a dated key register: key id (fingerprint), algorithm, first and last use, who held it, why it was retired.
- Approver keys: one per person, issued by your identity provider's process, and for approvers of consequential calls in an HSM or KMS (
bide-hsm approve) rather than a key file. Keep the PIN off the approver's disk where you can (an environment variable from the approver's secret store, not a file in a repository or a synced folder). bide refuses two approvers on one key but cannot see one person holding two (hitl-approval). - Webhook secrets rotate without downtime with
WithSecrets(current, previous)(notifications). Prefer mutual TLS and a pin where the receiver supports them. - Post-quantum. Anchors are long-lived. If your retention is many years, consider the hybrid scheme; ML-DSA cannot be used under Go's FIPS 140-3 module v1.0.0 (it can under v1.26.0 and later) (security model).
Retention and archiving
The full guide is Retention and archiving: what to keep, how to archive it so it verifies years later, key rotation and what deletion does to the proofs. This section is the short form.
To re-verify a run's evidence later, an auditor needs all of the following. Retain them together, for as long as your regulation or contract requires.
- The journal records of the run, as stored (an exported journal,
audit.JournalExport, or the database rows). Proofs are over the stored bytes, including each record's random salt, so a transformed copy does not verify. Records are not encrypted (security model); apply the same access control to the archive as to the database. - The signed tree heads you rely on, and their anchor-log entries. A head is the commitment; the journal alone proves nothing until a head covers it.
- The evidence packages you produced for material actions (
audit.Evidence), which carry the heads and inclusion proofs. - Every public key needed: the log key, grant issuer keys, and each approver key valid when a gate decided, plus the key register.
- The approver policy in force (the named approvers and k), because a tally records the policy it enforced and the auditor checks it against the allowlist they hold.
- The
bideversion that verifies them. Pre-1.0, a verifier reads only the current format of each artifact, so keep the release binary (or build from its tag) next to the evidence, with its checksums and signature (Verifying releases, stability). Record the version in the archive's manifest. - Notification trails and delivered payloads, if notifications are part of your control evidence (
notify.VerifyBodyre-checks a stored delivery).
Practices:
- Archive on completion. When a run ends, export its journal and evidence and write them, with the manifest, to write-once (WORM) storage in a different account from the database. Verify the archive by running
bide audit verify-evidenceagainst it before deleting anything from the live store. - Do not delete from the live journal while its heads are your only commitment. Journal compaction with proof continuity is a design note, not implemented. Today, removing records from the journal makes inclusion proofs for them impossible to produce. Archive first; delete only runs whose evidence is archived and verified.
- Absence proofs need the key sets projected from the journal, so archive those heads too if you may need to show that something never happened.
- Re-verify periodically. Run the verifier over a sample of the archive on a schedule, and always after upgrading
bide; a failure withaudit.ErrFormatmeans the verifier no longer reads that format. - Retention period is a legal decision. The library imposes none.
Backups
- Back up the database that holds the journal (
bide_steps,bide_events,bide_leases,bide_schema_version, and thenext_seqfunction, or the whole schema) with your normal point-in-time recovery. Backups carry the same sensitivity as the journal. - A restore can roll the journal back to an earlier state. The at-most-once guarantee reduces to "the journal did or did not record this step" (the guarantee). If you restore a database to a point before a step's attempt marker, bide will no longer know the effect fired, and may fire it again. After a restore, reconcile against the downstream systems before resuming runs: treat runs active at the time of the loss as having unknown outcomes. A rollback is also visible to anyone holding a later anchored head, because the restored log is not consistent with it. Do not "fix" that by re-signing.
- Restore into a separate environment first and verify (
bide audit) before pointing production at it. - The guarantee needs the store to survive the crash: use Postgres with synchronous commit and replication appropriate to your recovery objectives; SQLite is for one machine on a local disk, not a network file system (known limitations, stores).
- Test the restore. An untested backup is not evidence of recoverability.
Clocks and time
- Leases use the store's clock on Postgres. The Postgres store computes lease expiry with the database's
now(), so nodes compare against one clock rather than their own. SQLite computes expiry from the local system clock; a forward jump expires leases early, which the attempt claims keep safe (known limitations, stores). Lease expiry affects availability and duplicate work, not at-most-once. - Timers and halts use the process clock (
WithClock):Sleep,AwaitFordeadlines andWithMinHaltAge. A reconciler must setWithMinHaltAgeto cover the tool's real worst-case run time so it does not resolve a halt while the effect may still be landing (concepts). Keep the nodes of one deployment NTP-synchronized. - Tree-head timestamps are the signing process's clock. Verifiers reject a head more than a skew allowance (default five minutes) ahead of the verifier's clock and a head earlier than the head it extends; they do not bound how old a head may be (audit guide, timestamps). Run the verifier on a host with a trustworthy clock, and pin the verification time (
WithVerifyTime) when auditing a past period. - Approval decision times are claims.
decided_atis signed but is the approver's clock;recorded_atis the submitting process's clock, unsigned until a signed head covers it. Neither changes a count. For independent time, anchor heads to a timestamping service (known limitations). - Notification times are the notifying process's clock; an acknowledgement is not proof a person read it.
- A system clock that is wrong in the past or future will make evidence look odd without making it invalid. Record clock-sync monitoring in your own controls.
Least-privilege Postgres roles
The Postgres store creates its own tables when it is opened with the default Open: bide_steps, bide_leases, bide_schema_version, bide_events (prefix configurable with WithTablePrefix) and a next_seq function, in a schema you should pin with WithSchema. For least privilege, run that migration separately as the owner (bide migrate, or postgres.Migrate) and open the store with postgres.WithoutMigration, which creates and alters nothing and checks that the schema is there at the expected version (Postgres store guide). The journal tables are written by INSERT only; the running store issues no UPDATE or DELETE on bide_steps or bide_events. The one exception is a redaction (agent.Redact), which a SECURITY DEFINER function does for a separate role (below); no role is granted UPDATE on the table. Leases are inserted, updated and deleted.
The split below is verified by TestLeastPrivilegeRoles and TestWithoutMigration_LeastPrivilege in store/postgres (they run under the Integration job's Postgres): an owner role runs the migration, the service role (with no CREATE on the schema) opens the store WithoutMigration and drives a journal write, an attempt claim, a lease (acquire, renew, release, list) and the event store, and a read-only role inspects. Opening before the migration fails with postgres.ErrSchemaMissing, and a schema at another version with postgres.ErrSchemaVersion. Removing any one of the privileges below made the test fail: INSERT on the journal tables, each of the lease privileges, EXECUTE on bide_next_seq_v1, SELECT on the version table; the service role is also shown unable to UPDATE or DELETE the journal, the event trail or the schema version, or to drop a table. Tested on Postgres 16.
| Role | Purpose | Privileges |
|---|---|---|
bide_owner | Creates the schema (or owns it), runs bide migrate; owns the tables and bide_next_seq_v1 | Owner. Runs the migration at deploy time and after upgrading bide. Not used by the running service |
bide_app | The running service, opened with WithoutMigration | USAGE on the pinned schema; SELECT, INSERT on bide_steps and bide_events; SELECT, INSERT, UPDATE, DELETE on bide_leases; SELECT on bide_schema_version; EXECUTE on bide_next_seq_v1(text). No CREATE, no UPDATE or DELETE on the journal tables, no superuser |
bide_reader | bide view, auditors, exports | USAGE on the schema and SELECT on the four tables, opened with OpenReadOnly, which sets default_transaction_read_only so the server refuses writes on its connections |
bide_redactor | Only the tool that erases personal data from finished runs (retention guide) | USAGE on the schema; EXECUTE on bide_redact_v3(text, text, bytea, bigint), a SECURITY DEFINER function that re-checks the end marker, the lease, the protected records and the leaf hash server-side. No privilege on any table, so it cannot read or rewrite a row itself; the application role must not have it |
Notes:
- The service role needs no
CREATEwhen it opens the storeWithoutMigration. The defaultOpenrunsCREATE TABLE IF NOT EXISTS, for which Postgres checksCREATEon the schema even when the tables exist; do not use it under this role split.WithoutMigrationverifies instead, and the store checks thatbide_next_seq_v1has the owner of the steps table and the definition it expects, so a function planted by another role is refused. The governed event log (govern/postgreslog) has the same option andpostgreslog.Migrate. - Because the journal tables take inserts only, withholding
UPDATEandDELETEfrom the service role means a compromised service cannot edit or remove existing records through SQL it is allowed to run. That is a preventive control against rewriting history by the application; a database administrator, the owner role and anyone with superuser access are not constrained by it, so protect them separately and keep the anchor out of their reach. - Creating the lease indexes on a database from v0.9.0 requires the table owner, so run
bide migrateasbide_ownerafter an upgrade; a service onWithoutMigrationrefuses a schema without them (ErrSchemaMissing). - Pin the schema (
WithSchema) and grantCREATEon it only to the owner. The store trusts the schema's owner and every role able to create objects in it, and an unpinned store trusts every schema on the search path; the store's source documents these trust assumptions (store/postgres/postgres.go). Do not grantCREATEon the database to application roles. - Use TLS to Postgres, a dedicated database or schema for bide, network rules that admit only the service and tooling, and credentials from a secret manager.
- Turn on database audit logging for the owner and administrator roles, and for any
UPDATE/DELETEattempt on the journal tables. - Run
bide viewwith the read-only role, and over a copy for sensitive journals, since the viewer shows records in the clear.
A short checklist
- [ ] Log key, grant key and approver keys held by different principals; log key not in the application database.
- [ ] Heads anchored to a separate trust domain; anchor not writable by the operators of the database. With
anchor/gcs: a locked retention policy, a separate project,bide-anchor check -backend gcs(orReader.Audit) run on a schedule by a read-only identity and its findings alerted,OnErroron the store alerted, no personal data in run or trail IDs. Withanchor/awss3: compliance mode, a separate account,bide-anchor checkrun on a schedule by a read-only role and its findings alerted,OnErroron the store alerted, no personal data in run or trail IDs. - [ ] Key register with dated rotations; old public keys retained.
- [ ] Completed runs exported to WORM storage with heads, evidence, keys, policy and the verifying
bideversion; archive verified. - [ ] Restore procedure tested, including reconciliation of in-flight runs against downstream systems.
- [ ] NTP on every node; reconcilers set
WithMinHaltAge. - [ ] Owner, service and read-only database roles; schema pinned; TLS on.
- [ ] Release binaries verified before install (Verifying releases).