Migrating HMAC → Signed Connect Delivery

​

The one move

1. Meets the OCSS security bar (kills a bearer secret the spec explicitly bans).
2. Collapses the provider config to the 3-field createLink (one key it already holds).
3. Collapses the platform receiver to one route + an allowlist.
4. Removes the failure modes that make the connect leg brittle.

​

Why HMAC is a genuine risk

​

The security event is DELETION, not the flag

both mode is itself the live vulnerability. While a receiver still holds its HMAC secret, an attacker with that secret can forge via the HMAC path even though signed is available — a downgrade attack on your own migration mechanism. Flipping the posture flag to signed does not close the hole; deleting the secret does.

• Stop minting new HMAC secrets. Every new receiver is signed-only (createConnectReceiver defaults to signed; legacyHmacSecret is opt-in).
• authorize is required at signed-only posture. Role-gate-alone (trust any accredited enforcement-agent) is the never-ship baseline; the platform’s provider allowlist is the real authorization control. createConnectReceiver makes authorize a required field so that baseline is unrepresentable.

​

The safe cutover — per receiver

​

1. Platform: run the signed receiver in both

// app/api/ocss/connect/route.ts
import { createConnectReceiver } from "@phosra/gatekeeper/next"
import { store }   from "@/lib/ocss/store"
import { onBound } from "@/lib/ocss/apply"

export const { POST } = createConnectReceiver({
  env:        "production",
  did:        "did:ocss:notflix",
  seed:       process.env.OCSS_SENDER_SEED_B64URL!,
  authorize:  ["did:ocss:custo"],                 // add the provider DID(s) you accept
  store, onBound,
  legacyHmacSecret: process.env.OCSS_CONNECT_SECRET,  // DRAIN WINDOW ONLY — delete in step 4
})

​

2. Provider: go signed (default) — stop passing the secret

const r = await link.connect.finish({ /* … */ })   // signed by default

if (r.deliveryScheme !== "ed25519-did") {
  // still going out over HMAC — investigate before you delete the secret
}

​

3. Confirm zero HMAC traffic

• Provider: every connect.finish / provision result reports deliveryScheme === "ed25519-did" (and delivered === true).
• Platform: your receiver logs / metrics show every accepted delivery took the signed path, none the ocss-ext01/provision.v1 HMAC dispatch.

​

4. Platform: DELETE the secret — the completion event

export const { POST } = createConnectReceiver({
  env:       "production",
  did:       "did:ocss:notflix",
  seed:      process.env.OCSS_SENDER_SEED_B64URL!,
  authorize: ["did:ocss:custo"],
  store, onBound,
  // legacyHmacSecret removed — DELETE OCSS_CONNECT_SECRET from the environment
})

​

The new dependency: Trust-List liveness

​

Audience-binding and replay-freshness

• Audience binding (RFC 8707). The envelope binds to your receiver DID (audience_did = your did), so a captured delivery cannot be replayed to a different receiver. The SDK rejects an audience mismatch before onBound.
• Replay-freshness. A tight created window (createdSkewSec, default 300s) plus idempotency on the endpoint_id_label defeats same-receiver replay — a re-sent label returns a 2xx idempotently without re-binding.

​

Checklist

• New receivers are signed-only (no legacyHmacSecret). No new HMAC secrets minted.
• authorize lists exactly the provider DIDs you accept — nothing wider.
• Migrating receiver runs both (legacyHmacSecret set) — temporarily.
• Provider delivers signed by default; deliveryScheme === "ed25519-did" on every result.
• Zero HMAC traffic confirmed from both ends across a full cycle.
• Secret deleted from env + secret store; legacyHmacSecret removed. ← completion.
• Last-known-good Trust-List caching in place for the liveness dependency.

​

Next

• Provider · createLink (writer-plane compatibility)
• Platform · createConnectReceiver (legacy connect receiver)
• OCSS Trust Framework — the pinned-root model this rests on