hypercerts-org / hypercerts-org/ePDS

Add version number to callback HMAC protocol

Open
#17 0 comments 0 reactions 0 assignees View on GitHub

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:

  1. Include a version field (e.g. 1) as the first element of the signed payload
  2. verifyCallback checks the version and rejects unknown versions with a clear error
  3. 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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.