Problem
The HMAC-signed callback between auth-service and pds-core (signCallback/verifyCallback in packages/shared/src/crypto.ts) has no versioning. When the payload format changes (as in #13, which added a handle field), both services must be deployed simultaneously or callbacks fail silently.
There's no way for either side to detect that it's talking to a service using a different protocol version — it just gets signature mismatches.
Proposal
Add a single integer version number to the CallbackParams / HMAC payload:
- Include a
version field (e.g. 1) as the first element of the signed payload
verifyCallback checks the version and rejects unknown versions with a clear error
- Optionally support verifying against both version N and N-1 during a transition period, allowing rolling deployments without downtime
This would:
- Make protocol mismatches debuggable (clear error instead of opaque signature failure)
- Enable backward-compatible rolling deployments by temporarily accepting both versions
- Document the payload format history via version bumps
Context
Discovered during review of #13, which changed the payload from 5 fields to 6 fields (adding the handle slot). Currently both services must be deployed atomically to avoid breaking in-flight logins.
Problem
The HMAC-signed callback between auth-service and pds-core (
signCallback/verifyCallbackinpackages/shared/src/crypto.ts) has no versioning. When the payload format changes (as in #13, which added ahandlefield), both services must be deployed simultaneously or callbacks fail silently.There's no way for either side to detect that it's talking to a service using a different protocol version — it just gets signature mismatches.
Proposal
Add a single integer version number to the
CallbackParams/ HMAC payload:versionfield (e.g.1) as the first element of the signed payloadverifyCallbackchecks the version and rejects unknown versions with a clear errorThis would:
Context
Discovered during review of #13, which changed the payload from 5 fields to 6 fields (adding the handle slot). Currently both services must be deployed atomically to avoid breaking in-flight logins.