hypercerts-org / hypercerts-org/ePDS
Add version number to callback HMAC protocol
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 8
- Forks
- 4
- Avg merge
- 5d 11h
- Merged PRs (30d)
- 3
Description
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
versionfield (e.g.1) as the first element of the signed payload verifyCallbackchecks 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.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start in packages/shared/src/crypto.ts by reading CallbackParams, signCallback, and verifyCallback, then compare the current five- and six-field payload formats described in #13. Define the version and transition behavior before changing the signing and verification paths. Done means mismatched versions produce a clear error and the chosen rolling-deployment behavior is covered.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- authentication, backend-api-design, security
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100