Skip to content

Add version number to callback HMAC protocol #17

Description

@aspiers

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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions