ProxyAuth / Security

sync, in groups: build constants as a trust boundary, not just a deployment chore

ProxyAuthSecurity / Key materialUpdated on 2026-09-18

Two ProxyAuth instances compiled from the same source, with the same config.json, still reject each other’s tokens. Their per-build constants — including the 32-byte build secret that feeds key derivation — differ, so their keys differ. sync export and sync import exist to fix that, and they are usually described exactly that way: the step you run before multi-node SSO works.

That framing undersells them. What they actually let you do is decide which instances trust each other, and by omission which ones do not.

What sync moves, precisely

On the source instance:

$ proxyauth sync export
Key export Success (secret key encrypted with AppConfig password)

It generates a fresh OpenPGP certificate with Sequoia and writes it to key.asc, with the private key material encrypted under a passphrase derived from that instance’s secret. It then encrypts the current build constants — version, build time, build random value, two build seeds, the build epoch, the 32-byte HKDF salt and the shuffle order — into data.gpg, addressed to that certificate. Both files land in the current working directory.

On each target instance:

# place key.asc and data.gpg in /etc/proxyauth/import/
$ proxyauth sync

The target unlocks key.asc with its own secret, decrypts data.gpg, validates the result, and adopts the constants. From then on it builds and verifies tokens exactly as the source does.

Two prerequisites follow:

  • Same secret on both sides. It is what protects key.asc, and it is the other half of the key. Sync carries only the build half.
  • A current source. A keystore whose build secret is shorter than 32 bytes is refused with the reason named. Upgrade the source and export again rather than downgrading the target.

What a build constant separates

Start from the failure case. An attacker gets code execution on one instance. They read config.json, so they have secret. They have the binary, so they have its constants. They can now mint tokens that instance accepts.

What happens next depends on the architecture:

  • One key shared by the whole fleet — every node accepts the forged tokens. One intrusion, fleet-wide compromise.
  • Central session store — reach the store and you read and write everyone’s sessions.
  • Per-build constants — the forged tokens work where those constants are in use, and nowhere else. The rest of the fleet keeps rejecting them without anyone doing anything.

Not a smaller problem than a stolen key — a contained one.

sync is per-pair, not per-fleet

Nothing in sync operates on “the fleet”. It produces two files on one machine, and you carry them wherever you choose. Import them on three of eight nodes and you have exactly that: three that agree, five that do not. The choice was never “segmented or SSO”. It is where you draw the line.

A worked example

One organisation, three quite different surfaces. Group instances by blast radius, not by convenience:

group A — public front
  proxy-fr-01, proxy-fr-02, proxy-fr-03   ← one shared set of constants

group B — internal admin
  proxy-adm-01, proxy-adm-02              ← a second, unrelated set

group C — back-office / billing
  proxy-bo-01                             ← never synced with anything

Group A:

# on proxy-fr-01
$ cd /srv/sync-a && proxyauth sync export

# copy key.asc and data.gpg to /etc/proxyauth/import/ on fr-02 and fr-03
$ proxyauth sync

Group B repeats the procedure from its own source, with its own secret. Group C is left alone: its constants were drawn at compile time and never leave it.

A session on the public front works on all three of its nodes. It is not, and cannot become, a session on the admin panels. Compromise proxy-fr-02 and the attacker can forge tokens for group A — the same users those nodes already serve. B and C do not move.

The blast radius equals the group, and the group is something you chose.

Tokens are not the only shared state

Two other things must be grouped consistently, or the boundary leaks through them:

  • Revocation. redis carries revocations between every instance pointed at the same Redis database, and the sync loop scans broadly. Give each group its own Redis database number.
  • Accounts. Instances sharing a databases block share users, but that does not make them accept each other’s tokens. Sharing accounts across groups is fine; it is token validity that the constants gate.

Delete the export artifacts

key.asc is protected by a passphrase derived from secret, and data.gpg holds the constants. Left in /etc/proxyauth/import/ after a successful import, they turn a config.json disclosure back into a compromise of the group’s constants — the exact scenario the two-secret design exists to prevent.

Move them out of band, import, then remove them from both machines:

$ proxyauth sync && \
  shred -u /etc/proxyauth/import/key.asc /etc/proxyauth/import/data.gpg

What this does not cover yet

Groups are not named anywhere. A group exists in the operator’s head and in who received which data.gpg. A token from the wrong group fails like a corrupt or expired one. A group identifier checked before decryption would turn “invalid token” into “token belongs to another zone”.

Fleet shape is not observable. Nothing reports which instances share constants. A node left out of a group shows up as intermittent logouts on one machine behind the load balancer.

Rotation is per instance. Regenerating a compromised group’s constants means a rebuild and a fresh export, node by node.

The OIDC signing key does not follow groups. Every oidc: vhost on an instance shares one RSA key read from disk. An attacker on any instance holding that key can sign id_tokens every relying party trusting its JWKS will accept. Group boundaries protect /auth sessions; they do not yet extend to the OIDC provider.

Where this is going

All of the above works today and all of it is manual — fine for three nodes, unpleasant past a dozen. The natural next step is to let BlakeGate carry group membership, so a group is declared once, named, inspectable and rotatable as a unit.

A distributor of key material is itself a trust anchor, and any such design has to ensure that holding the channel is not enough to mint a token: instances keep their own secret, the channel carries only the half they cannot use alone, changes are authenticated and logged, and an instance refuses anything that would weaken what it already has — exactly as sync already refuses a short build secret.

Instances that do not trust each other until you say so is the useful default. Sync the ones that genuinely serve the same users, give each group its own revocation bus, delete the files afterwards — and leave the boundary standing everywhere else.