HMAC service auth and replay protection

Trusted callers sign every request with a shared secret. The implementation is packages/security/src/index.ts (@perform/security). It fronts the internal provisioning routes, the admin default routes, the whole web gateway and, when a request claims to come from the web proxy, the public signing lane.

Headers

Header	Value
`x-service-id`	The calling service’s id. The only id configured is `web`.
`x-timestamp`	Milliseconds since the Unix epoch, as a string.
`x-nonce`	A unique, single use value. Callers use a UUID.
`x-signature`	Hex encoded HMAC-SHA256 of the canonical string.

Canonical string

Five fields joined by newlines:

METHOD
/v1/web/clients?page=1
1767225600000
6f1c2a9e-5c1b-4b8e-9a53-2d7f0c3a1e44
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Line	Source on the server
Method	`req.method`, upper cased
Path	`req.originalUrl`, which includes the query string
Timestamp	`x-timestamp`
Nonce	`x-nonce`
Body hash	`sha256Hex(req.rawBody)`, or the hash of the empty string when there is no body

export function canonicalString(payload: SignaturePayload): string {
  return [
    payload.method.toUpperCase(),
    payload.path,
    payload.timestamp,
    payload.nonce,
    payload.bodyHash,
  ].join('\n');
}

export function signPayload(secret: string, payload: SignaturePayload): string {
  return createHmac('sha256', secret).update(canonicalString(payload)).digest('hex');
}

Three details cause most signature mismatches:

The path includes the query string. Sign exactly what you send, in the same order and encoding.
The body hash covers bytes. The server hashes the raw buffer captured by the body parser’s verify hook, not a re-serialized object. Sign the exact string or bytes you put on the wire. Binary bodies (a media upload part) are hashed as bytes, never decoded as UTF-8 first.
An empty body hashes the empty string. A GET signs sha256('').

Verification order

requireServiceAuth({ nonceStore, secrets, windowMs? }) checks in this order. Every failure is 401 UNAUTHORIZED.

Step	Failure message
All four headers present	`missing service auth headers`
`secrets[serviceId]` exists	`unknown service`
Timestamp within the window (default 300,000 ms, either direction)	`stale or invalid timestamp`
Signature matches, compared with `timingSafeEqual`	`invalid service signature`
Nonce not seen before	`nonce already used`

On success it sets req.service = { id: serviceId }. The nonce is consumed last, after the signature is verified. An attacker without the secret cannot burn nonces or fill the store.

The nonce store

export type NonceStore = {
  consume: (nonce: string, ttlSeconds: number) => Promise<boolean>;
};

createRedisNonceStore(redis, prefix = 'perform:nonce') implements it with one atomic command:

SET perform:nonce:<nonce> 1 EX <ttl> NX

consume returns true when the key was set (first use) and false when it already existed (replay). The TTL is the window in seconds plus 60, so a nonce is remembered slightly longer than its timestamp can be valid. The store uses the shared Redis connection from the queue factory. If Redis is down, consume rejects and the request fails with 500. Signed lanes fail closed.

Replay protection without a signature

replayProtection({ nonceStore, windowMs? }) is the lighter guard in front of the bearer lane. It checks only freshness and uniqueness:

Condition	Result
`x-nonce` or `x-timestamp` missing	`400 BAD_REQUEST`, `missing x-nonce or x-timestamp header`
Timestamp outside the window	`401 UNAUTHORIZED`, `stale or invalid timestamp`
Nonce already used	`401 UNAUTHORIZED`, `nonce already used`

It does not bind the nonce to the request, so by itself it only stops a verbatim replay of a captured request. On the bearer lane the session token is the credential. Signed lanes are mounted before router.use(replay), because requireServiceAuth already consumed the nonce. Running both would reject every signed request as a replay.

Which lanes need what

Lane	Signature	Replay headers
`/v1/internal`, `/v1/admin`, `/v1/web`	yes	yes, as part of the signature
`/v1/public/sign` with `x-service-id`	yes	yes
Bearer (`/v1/studios`, `/v1/clients`, `/v1/whatsapp`)	no	yes
Trainee, partner, automation, public, webhooks, `/mcp`, `/api`	no	no

Older notes say every authenticated /v1 request carries a nonce. That is no longer true. The trainee app, API key callers and webhooks send none.

Signing a request

@perform/security ships a client for server to server callers:

const client = createServiceClient({
  baseUrl: 'http://localhost:3031',
  serviceId: 'web',
  secret: process.env.SERVICE_AUTH_SECRET,
});

const result = await client.request<{ ok: true; data: unknown }>({
  method: 'POST',
  path: '/v1/internal/studios',
  body: { externalOrgId: 'org_123', name: 'Studio', slug: 'studio' },
});

request serializes the body once with JSON.stringify, signs that exact string, sets the four headers plus content-type: application/json, and throws on a non 2xx response. Extra headers (the web user context) go in init.headers. The web app has its own equivalent, coreApiFetch in its core-api.ts, and @repo/auth signs by hand in lib/provision-coach.ts for POST /v1/internal/coaches. All three build the same canonical string. To sign from a shell for debugging:

SECRET="YOUR_SERVICE_AUTH_SECRET"
METHOD="GET"
REQ_PATH="/v1/web/studios/current"
TS=$(($(date +%s) * 1000))
NONCE=$(uuidgen)
BODY_HASH=$(printf '' | shasum -a 256 | cut -d' ' -f1)
SIG=$(printf '%s\n%s\n%s\n%s\n%s' "$METHOD" "$REQ_PATH" "$TS" "$NONCE" "$BODY_HASH" \
  | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $NF}')

curl "http://localhost:3031$REQ_PATH" \
  -H "x-service-id: web" -H "x-timestamp: $TS" -H "x-nonce: $NONCE" -H "x-signature: $SIG" \
  -H "x-studio-id: YOUR_ORG_ID" -H "x-user-id: YOUR_USER_ID" -H "x-user-role: OWNER"

Exports

Export	Purpose
`sha256Hex(input)`	Hex SHA-256 of a string or bytes.
`canonicalString(payload)`, `signPayload(secret, payload)`, `verifySignature(secret, payload, signature)`	The signing primitives. `verifySignature` is timing safe and returns false on a length mismatch.
`generateNonce()`	`randomUUID()`.
`createRedisNonceStore(redis, prefix?)`	The Redis nonce store.
`replayProtection(options)`	Express middleware, nonce and timestamp only.
`requireServiceAuth(options)`	Express middleware, full signature check.
`createServiceClient(options)`	Signing HTTP client.
Types	`SignaturePayload`, `NonceStore`, `ReplayProtectionOptions`, `ServiceAuthOptions`, `ServiceClientOptions`, `ServiceRequestInit`, `ServiceClient`

Operating notes

SERVICE_AUTH_SECRET must be the same value in the API and in the web app. Rotate both together. There is one secret per service id and no overlap window, so a rotation needs both sides deployed at once.
Clock skew larger than 5 minutes between caller and API makes every request fail with stale or invalid timestamp.
A reverse proxy that rewrites the path or re-encodes the query string breaks signatures, because the server signs req.originalUrl.
The logger does not redact x-signature, but the HTTP log serializer only records host, content-type and x-request-id from the request headers, so signatures and nonces do not reach the logs.

Overview

Getting set up

Conventions

Backend architecture

Building backend modules

Backend security and access

Background work and delivery

Backend platform features

Backend operations

Backend packages

Data model

JSON shapes

Web app: basics

Web app: data and API

Web app: auth, organizations and billing

Web app: UI foundations

Web app: feature areas

Web app: quality and delivery

Trainee app: foundations

Trainee app: UI

Trainee app: workouts

Trainee app: nutrition

Trainee app: forms, content and tracking

Trainee app: device features

Trainee app: native, build and release

Messaging integrations

Platform integrations

External API and automation

Operations

HMAC service auth and replay protection

Headers

Canonical string

Verification order

The nonce store

Replay protection without a signature

Which lanes need what

Signing a request

Exports

Operating notes

​Headers

​Canonical string

​Verification order

​The nonce store

​Replay protection without a signature

​Which lanes need what

​Signing a request

​Exports

​Operating notes

Headers

Canonical string

Verification order

The nonce store

Replay protection without a signature

Which lanes need what

Signing a request

Exports

Operating notes