Integrate licensing that fights back.

IDEM=$(openssl rand -hex 16)   # 16 random bytes from a cryptographic source
CN=$(openssl rand -hex 8)      # fresh per request, never reused
# Send the SAME Idempotency-Key on every retry of this attempt, and forget it
# once the call succeeds. A retry under a new key burns another device slot, and
# the default cap is one, so the customer is locked out of their own product.
CODE=$(curl -sS -D act.hdr -o act.json -w '%{http_code}' \
  -X POST "$BASE/v1/sess/activate" \
  -H "Content-Type: application/json" \
  -H "x-licentry-build: $BUILD_TOKEN" \
  -H "x-licentry-protocol: 1" \
  -H "Idempotency-Key: $IDEM" \
  -d "$(jq -cn --arg n "$CN" '{
    licenseKey: "aB3xK9m-7Qp2n-M4kL8z-Xy1Wq9r",
    deviceHash: "9f2c41d8b7a6e35c0d419b8a72e6c15d3f8074ba9e2d6c1785af30b9e4c26a71",
    clientNonce: $n
  }')")
# The device hash is 64 hex characters, all of them. A shortened one is
# 400 Invalid request body, and the refusal does not name the field.
# Build it only from identifiers that read without elevation, so it is the same
# value whether or not the customer runs as administrator. A hash that moves
# between runs revokes the session with 403 license_suspended and records a
# hardware mismatch against the licence.
# licentry_accepted comes from the verify sample below. It refuses an unsigned
# response, a bad signature, a stale timestamp, a non-2xx status, and an echoed
# clientNonce that is not the one this call sent.
licentry_accepted "$CODE" act.hdr act.json "$CN" || exit 1
ACCESS_TOKEN=$(jq -r .accessToken act.json)
REFRESH_TOKEN=$(jq -r .refreshToken act.json)
SEQ=1; SERVER_NONCE=""         # a new session starts its own nonce chain

#include <curl/curl.h>

static size_t sink(char* p, size_t sz, size_t n, void* o) {
  static_cast<std::string*>(o)->append(p, sz * n);
  return sz * n;
}

// hdrSink fills this from CURLOPT_HEADERFUNCTION. sig stays empty when the
// server sent no X-Licentry-Sig, and an empty sig is a refusal, not a skip: a
// product with vendor response signing on and an account key the server cannot
// load answers with no signature header at all.
struct SigHdr { std::vector<uint8_t> sig; std::string ts, kid; };
static size_t hdrSink(char* p, size_t sz, size_t n, void* o);

// idemKey is the caller's: 16 random bytes from a cryptographic source, made
// once per activation attempt and passed in unchanged on every retry of that
// attempt, then dropped. A retry under a new key burns another device slot, and
// the default cap is one.
bool activate(const Cfg& cfg, const std::string& deviceHash,
              const std::string& idemKey, Session& out) {
  const std::string clientNonce = randomHex(8);  // fresh per request
  std::string body = R"({"licenseKey":")" + cfg.licenseKey +
                     R"(","deviceHash":")" + deviceHash +
                     R"(","clientNonce":")" + clientNonce + R"("})";
  std::string resp;
  SigHdr hdr;
  curl_slist* h = curl_slist_append(nullptr, "Content-Type: application/json");
  h = curl_slist_append(h, ("x-licentry-build: " + cfg.buildToken).c_str());
  h = curl_slist_append(h, "x-licentry-protocol: 1");
  h = curl_slist_append(h, ("Idempotency-Key: " + idemKey).c_str());
  CURL* c = curl_easy_init();
  curl_easy_setopt(c, CURLOPT_URL, (cfg.base + "/v1/sess/activate").c_str());
  curl_easy_setopt(c, CURLOPT_POSTFIELDS, body.c_str());
  curl_easy_setopt(c, CURLOPT_HTTPHEADER, h);
  curl_easy_setopt(c, CURLOPT_WRITEFUNCTION, sink);
  curl_easy_setopt(c, CURLOPT_WRITEDATA, &resp);
  curl_easy_setopt(c, CURLOPT_HEADERFUNCTION, hdrSink);
  curl_easy_setopt(c, CURLOPT_HEADERDATA, &hdr);
  curl_easy_perform(c);
  long code = 0;
  curl_easy_getinfo(c, CURLINFO_RESPONSE_CODE, &code);
  curl_slist_free_all(h);
  curl_easy_cleanup(c);

  // Gate on accepted, never on verifySig: a verified 403 is still a refusal.
  if (!accepted(cfg.pinned(hdr.kid), (int)code, hdr.ts, resp, hdr.sig, time(nullptr)))
    return false;
  auto j = json::parse(resp, nullptr, false);
  // The echo is the body field clientNonce, and it sits inside the signed
  // material. Activate is the response carrying engineParams and the offline
  // grace token, so an unchecked one is another machine's session replayed here.
  if (j.is_discarded() || j.value("clientNonce", "") != clientNonce) return false;
  out.accessToken  = j["accessToken"];
  out.refreshToken = j["refreshToken"];
  out.seq = 1;
  out.serverNonce.clear();   // a new session starts its own nonce chain
  return true;
}

using System.Net.Http.Json;
using System.Text.Json;

record Session(string accessToken, string refreshToken, string expiresAt,
               string refreshExpiresAt, long revocationVersion, JsonElement product,
               bool idempotent, string offlineGraceJwt, string clientNonce);

// idempotencyKey is the caller's: 16 random bytes from a cryptographic source,
// made once per activation attempt and passed in unchanged on every retry of
// that attempt, then dropped. A retry under a new key burns another device slot,
// and the default cap is one.
async Task<Session> Activate(HttpClient http, string licenseKey, string deviceHash,
                             string buildToken, string idempotencyKey,
                             IReadOnlyDictionary<string, ECDsa> pinned) {
    // Fresh per request and never reused. The server echoes it inside the
    // signed body, which is the only thing separating a live answer from a
    // recording of one.
    var clientNonce = Convert.ToHexString(RandomNumberGenerator.GetBytes(8));
    var req = new HttpRequestMessage(HttpMethod.Post, "/v1/sess/activate") {
        Content = JsonContent.Create(new { licenseKey, deviceHash, clientNonce })
    };
    req.Headers.Add("x-licentry-build", buildToken);
    req.Headers.Add("x-licentry-protocol", "1");
    req.Headers.Add("Idempotency-Key", idempotencyKey);
    var res = await http.SendAsync(req);
    var raw = await res.Content.ReadAsByteArrayAsync();

    // Verify throws on a missing or bad signature, so this path fails closed.
    // Then branch on the status it hands back: a verified 403 is still a refusal.
    var v = Verify(res, raw, pinned);
    if (v.Status != 201) throw new InvalidOperationException("activate refused");
    var session = JsonSerializer.Deserialize<Session>(v.Body)!;
    // The echo is the body field clientNonce. Activate is the response carrying
    // engineParams and the offline grace token, so an unchecked one is another
    // machine's session replayed onto this one.
    if (session.clientNonce != clientNonce) {
        throw new InvalidOperationException("nonce echo mismatch");
    }
    return session;
}

import secrets
import requests


# idem_key belongs to the caller: secrets.token_hex(16), made once per activation
# attempt and passed in unchanged on every retry of that attempt, then dropped.
# A retry under a new key burns another device slot, and the default cap is one,
# so the value has to outlive this function.
def activate(base, build_token, license_key, device_hash, idem_key, pinned):
    client_nonce = secrets.token_hex(8)  # fresh per request, never reused
    r = requests.post(
        f"{base}/v1/sess/activate",
        headers={
            "Content-Type": "application/json",
            "x-licentry-build": build_token,
            "x-licentry-protocol": "1",
            "Idempotency-Key": idem_key,
        },
        json={"licenseKey": license_key, "deviceHash": device_hash,
              "clientNonce": client_nonce},
        timeout=10,
    )
    # verify raises on a missing or bad signature, so this fails closed. Branch
    # on the status it hands back: a verified 403 is still a refusal.
    status, session = verify(r, pinned)
    if status != 201:
        raise RuntimeError("activate refused")
    # The echo is the body field clientNonce. Activate is the response carrying
    # engineParams and the offline grace token, so an unchecked one is another
    # machine's session replayed onto this one.
    if session.get("clientNonce") != client_nonce:
        raise RuntimeError("nonce echo mismatch")
    return session

import { randomBytes } from "node:crypto";

// idemKey belongs to the caller: randomBytes(16).toString("hex"), made once per
// activation attempt and passed in unchanged on every retry of that attempt,
// then dropped. A retry under a new key burns another device slot, and the
// default cap is one, so the value has to outlive this call.
export async function activate({ base, buildToken, licenseKey, deviceHash,
                                 idemKey, pinned }) {
  const clientNonce = randomBytes(8).toString("hex");  // fresh per request, never reused
  const res = await fetch(`${base}/v1/sess/activate`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-licentry-build": buildToken,
      "x-licentry-protocol": "1",
      "Idempotency-Key": idemKey,
    },
    body: JSON.stringify({ licenseKey, deviceHash, clientNonce }),
  });
  // verifySigned throws on a missing or bad signature, so this fails closed.
  // Branch on the status it hands back: a verified 403 is still a refusal.
  const { status, body } = await verifySigned(res, pinned);
  if (status !== 201) throw new Error("activate refused");
  // The echo is the body field clientNonce. Activate is the response carrying
  // engineParams and the offline grace token, so an unchecked one is another
  // machine's session replayed onto this one.
  if (body.clientNonce !== clientNonce) throw new Error("nonce echo mismatch");
  return { ...body, seq: 1, serverNonce: "" };
}

type Session struct {
	AccessToken       string `json:"accessToken"`
	RefreshToken      string `json:"refreshToken"`
	ExpiresAt         string `json:"expiresAt"`
	RefreshExpiresAt  string `json:"refreshExpiresAt"`
	RevocationVersion int64  `json:"revocationVersion"`
	ClientNonce       string `json:"clientNonce"`
}

// idemKey is the caller's: 16 random bytes, hex encoded, made once per
// activation attempt and passed in unchanged on every retry of that attempt,
// then dropped. A retry under a new key burns another device slot, and the
// default cap is one.
func Activate(base, build, key, deviceHash, idemKey string,
	pinned map[string]*ecdsa.PublicKey) (*Session, error) {
	cn := make([]byte, 8)
	rand.Read(cn)
	clientNonce := hex.EncodeToString(cn) // fresh per request, never reused
	body, _ := json.Marshal(map[string]string{"licenseKey": key, "deviceHash": deviceHash,
		"clientNonce": clientNonce})
	req, _ := http.NewRequest("POST", base+"/v1/sess/activate", bytes.NewReader(body))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("x-licentry-build", build)
	req.Header.Set("x-licentry-protocol", "1")
	req.Header.Set("Idempotency-Key", idemKey) // same key on every retry of this call
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer res.Body.Close()
	raw, err := io.ReadAll(res.Body) // the signature covers these exact bytes
	if err != nil {
		return nil, err
	}
	// Gate on Accepted, never on Verify: a verified 403 is still a refusal. A
	// response carrying no X-Licentry-Sig fails here rather than slipping past.
	if !Accepted(res, raw, pinned) {
		return nil, fmt.Errorf("activate refused: %s", res.Status)
	}
	var s Session
	if err := json.Unmarshal(raw, &s); err != nil {
		return nil, err
	}
	// The echo is the body field clientNonce. Activate is the response carrying
	// engineParams and the offline grace token, so an unchecked one is another
	// machine's session replayed onto this one.
	if s.ClientNonce != clientNonce {
		return nil, errors.New("nonce echo mismatch")
	}
	return &s, nil
}

use serde_json::{json, Value};

// idem is the caller's: 16 random bytes, hex encoded, made once per activation
// attempt and passed in unchanged on every retry of that attempt, then dropped.
// A retry under a new key burns another device slot, and the default cap is one.
pub async fn activate(base: &str, build: &str, key: &str, device_hash: &str,
                      idem: &str, pinned: &HashMap<String, VerifyingKey>)
                      -> anyhow::Result<Value> {
    // Fresh per request, never reused.
    let client_nonce: String = (0..16)
        .map(|_| char::from_digit(rand::random::<u32>() % 16, 16).unwrap())
        .collect();
    let res = reqwest::Client::new()
        .post(format!("{base}/v1/sess/activate"))
        .header("Content-Type", "application/json")
        .header("x-licentry-build", build)
        .header("x-licentry-protocol", "1")
        .header("Idempotency-Key", idem) // same value on every retry of this activate
        .json(&json!({ "licenseKey": key, "deviceHash": device_hash,
                       "clientNonce": client_nonce }))
        .send()
        .await?;
    let status = res.status().as_u16();
    let headers = res.headers().clone();
    let raw = res.bytes().await?;   // the signature covers these exact bytes
    // One call refuses an unsigned response, a bad signature, a stale timestamp
    // and a non-2xx status, so the question mark cannot turn a refusal into a
    // green light.
    verify(status, &headers, &raw, pinned)?;
    let body: Value = serde_json::from_slice(&raw)?;
    // The echo is the body field clientNonce. Activate is the response carrying
    // engineParams and the offline grace token, so an unchecked one is another
    // machine's session replayed onto this one.
    if body.get("clientNonce").and_then(Value::as_str) != Some(client_nonce.as_str()) {
        anyhow::bail!("nonce echo mismatch");
    }
    Ok(body)
}

HttpClient http = HttpClient.newHttpClient();
// idempotencyKey belongs to the caller: 16 random bytes, hex encoded, made once
// per activation attempt and sent unchanged on every retry of that attempt, then
// dropped. A retry under a new key burns another device slot, and the default
// cap is one.
byte[] nonceBytes = new byte[8];
SecureRandom.getInstanceStrong().nextBytes(nonceBytes);
String clientNonce = HexFormat.of().formatHex(nonceBytes); // fresh per request
String body = mapper.writeValueAsString(
        Map.of("licenseKey", licenseKey, "deviceHash", deviceHash,
               "clientNonce", clientNonce));
HttpRequest req = HttpRequest.newBuilder(URI.create(base + "/v1/sess/activate"))
        .header("Content-Type", "application/json")
        .header("x-licentry-build", buildToken)
        .header("x-licentry-protocol", "1")
        .header("Idempotency-Key", idempotencyKey)  // same value on every retry
        .POST(HttpRequest.BodyPublishers.ofString(body))
        .build();

// The signature covers the raw bytes, so ask for bytes rather than a String.
HttpResponse<byte[]> res = http.send(req, HttpResponse.BodyHandlers.ofByteArray());
// Gate on accepted, never on verify: a verified 403 is still a refusal, and a
// response carrying no X-Licentry-Sig fails here rather than slipping past.
if (!accepted(res, PINNED)) {
    throw new IllegalStateException("activate refused: " + res.statusCode());
}
Session session = mapper.readValue(res.body(), Session.class);
// The echo is the body field clientNonce. Activate is the response carrying
// engineParams and the offline grace token, so an unchecked one is another
// machine's session replayed onto this one.
if (!clientNonce.equals(session.clientNonce())) {
    throw new IllegalStateException("nonce echo mismatch");
}
int seq = 1;
String serverNonce = "";   // a new session starts its own nonce chain

<?php
// $idemKey belongs to the caller: bin2hex(random_bytes(16)), made once per
// activation attempt and sent unchanged on every retry of that attempt, then
// dropped. A retry under a new key burns another device slot, and the default
// cap is one.
// $clientNonce is fresh per request and never reused. The server echoes it
// inside the signed body, and comparing the echo is what proves the answer is
// yours rather than a recording of somebody else's.
$clientNonce = bin2hex(random_bytes(8));
$body = json_encode(['licenseKey' => $licenseKey, 'deviceHash' => $deviceHash,
                     'clientNonce' => $clientNonce]);
$ch = curl_init($base . '/v1/sess/activate');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'x-licentry-build: ' . $buildToken,
        'x-licentry-protocol: 1',
        'Idempotency-Key: ' . $idemKey, // same value on every retry of this activate
    ],
]);
$h = [];
collectHeaders($ch, $h);   // from the verify sample
$res = curl_exec($ch);
$code = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

// Gate on licentryAccepted, never on licentryVerify: a verified 403 is still a
// refusal, and an answer carrying no X-Licentry-Sig is refused here.
if (!licentryAccepted($code, $h, $res, $pinned)) {
    throw new RuntimeException('activate refused');
}
$session = json_decode($res, true);
// The echo is the body field clientNonce. Activate is the response carrying
// engineParams and the offline grace token, so an unchecked one is another
// machine's session replayed onto this one.
if (($session['clientNonce'] ?? null) !== $clientNonce) {
    throw new RuntimeException('nonce echo mismatch');
}

struct Session: Decodable {
    let accessToken: String, refreshToken: String
    let expiresAt: String, refreshExpiresAt: String
    let revocationVersion: Int
    let clientNonce: String?
}

// idemKey belongs to the caller: 16 random bytes, hex encoded, made once per
// activation attempt and sent unchanged on every retry of that attempt, then
// dropped. A retry under a new key burns another device slot, and the default
// cap is one.
func activate(base: URL, build: String, key: String, deviceHash: String,
              idemKey: String,
              pinned: [String: P256.Signing.PublicKey]) async throws -> Session {
    var req = URLRequest(url: base.appending(path: "v1/sess/activate"))
    req.httpMethod = "POST"
    req.setValue("application/json", forHTTPHeaderField: "Content-Type")
    req.setValue(build, forHTTPHeaderField: "x-licentry-build")
    req.setValue("1", forHTTPHeaderField: "x-licentry-protocol")
    req.setValue(idemKey, forHTTPHeaderField: "Idempotency-Key")  // reuse on retry
    var nonceBytes = [UInt8](repeating: 0, count: 8)
    _ = SecRandomCopyBytes(kSecRandomDefault, nonceBytes.count, &nonceBytes)
    let clientNonce = nonceBytes.map { String(format: "%02x", $0) }.joined()
    req.httpBody = try JSONEncoder().encode(["licenseKey": key,
                                             "deviceHash": deviceHash,
                                             "clientNonce": clientNonce])
    let (data, res) = try await URLSession.shared.data(for: req)
    // Gate on accepted, never on verify: a verified 403 is still a refusal, and
    // a response carrying no X-Licentry-Sig is refused inside rather than skipped.
    guard let http = res as? HTTPURLResponse,
          accepted(http, body: data, pinned: pinned) else {
        throw LicentryError.activation("activate refused")
    }
    let session = try JSONDecoder().decode(Session.self, from: data)
    // The echo is the body field clientNonce. Activate is the response carrying
    // engineParams and the offline grace token, so an unchecked one is another
    // machine's session replayed onto this one.
    guard session.clientNonce == clientNonce else {
        throw LicentryError.activation("nonce echo mismatch")
    }
    return session
}

val JSON = "application/json".toMediaType()

// idemKey belongs to the caller: 16 random bytes, hex encoded, made once per
// activation attempt and sent unchanged on every retry of that attempt, then
// dropped. A retry under a new key burns another device slot, and the default
// cap is one.
fun activate(base: String, build: String, key: String, deviceHash: String,
             idemKey: String, pinned: Map<String, PublicKey>): Session {
    val clientNonce = ByteArray(8).also { SecureRandom().nextBytes(it) }
        .joinToString("") { "%02x".format(it) }   // fresh per request
    val body = JSONObject()
        .put("licenseKey", key)
        .put("deviceHash", deviceHash)
        .put("clientNonce", clientNonce)
        .toString()
    val req = Request.Builder()
        .url("$base/v1/sess/activate")
        .addHeader("x-licentry-build", build)
        .addHeader("x-licentry-protocol", "1")
        .addHeader("Idempotency-Key", idemKey) // same value on every retry
        .post(body.toRequestBody(JSON))
        .build()
    client.newCall(req).execute().use { res ->
        val raw = res.body!!.bytes()   // the signature covers these exact bytes
        // Gate on accepted, never on verify: a verified 403 is still a refusal,
        // and an answer carrying no X-Licentry-Sig is refused inside it.
        check(accepted(res, raw, pinned)) { "activate refused" }
        val session = gson.fromJson(String(raw), Session::class.java)
        // The echo is the body field clientNonce. Activate is the response
        // carrying engineParams and the offline grace token, so an unchecked one
        // is another machine's session replayed onto this one.
        check(session.clientNonce == clientNonce) { "nonce echo mismatch" }
        return session
    }
}

require "json"
require "net/http"
require "securerandom"

# idem_key belongs to the caller: SecureRandom.hex(16), made once per activation
# attempt and passed in unchanged on every retry of that attempt, then dropped.
# A retry under a new key burns another device slot, and the default cap is one,
# so the value has to outlive this method.
def activate(base, build_token, license_key, device_hash, idem_key, pinned)
  client_nonce = SecureRandom.hex(8) # fresh per request, never reused
  uri = URI("#{base}/v1/sess/activate")
  req = Net::HTTP::Post.new(uri)
  req["Content-Type"] = "application/json"
  req["x-licentry-build"] = build_token
  req["x-licentry-protocol"] = "1"
  req["Idempotency-Key"] = idem_key
  req.body = JSON.generate(licenseKey: license_key, deviceHash: device_hash,
                           clientNonce: client_nonce)
  res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
  # verify! raises on a missing or bad signature, so this fails closed. Branch on
  # the status it hands back: a verified 403 is still a refusal.
  status, session = verify!(res, res.body, pinned)
  raise "activate refused" unless status == 201

  # The echo is the body field clientNonce. Activate is the response carrying
  # engineParams and the offline grace token, so an unchecked one is another
  # machine's session replayed onto this one.
  raise "nonce echo mismatch" unless session["clientNonce"] == client_nonce

  session
end

# Two functions, because they answer two different questions.
#   licentry_verify   did the server really send this, and send it to me?
#   licentry_accepted that, AND is the answer yes? A verified 403 is still a no.
# Both take: <status> <header file> <body file> <the clientNonce you sent>
licentry_verify() {
  _code=$1; _hd=$2; _bd=$3; _cn=$4
  hdr() { grep -i "^$1:" "$_hd" | tr -d '\r' | cut -d' ' -f2-; }
  SIG=$(hdr X-Licentry-Sig); TS=$(hdr X-Licentry-Sig-Ts); KID=$(hdr X-Licentry-Sig-Kid)
  # NO HEADER IS A REFUSAL, not a skip. A product with vendor response signing on
  # and an account key the server cannot load sends no signature at all, and
  # "check it when it is there" turns exactly that case into a free pass.
  [ -n "$SIG" ] && [ -n "$TS" ] && [ -n "$KID" ] \
    || { echo "unsigned response, refusing" >&2; return 1; }
  # TWO SIDED. "now - ts < 300" alone is defeated permanently by setting the
  # system clock back: the difference goes negative, and negative is less than
  # 300, so a signature of any age passes. Compare the absolute skew.
  SKEW=$(( $(date +%s) - TS )); [ "$SKEW" -lt 0 ] && SKEW=$(( -SKEW ))
  [ "$SKEW" -le 300 ] || { echo "signature timestamp outside tolerance" >&2; return 1; }
  DIGEST=$(openssl dgst -sha256 -r "$_bd" | cut -d' ' -f1)
  printf '%s|%s|%s' "$_code" "$TS" "$DIGEST" > canon.txt
  # the header is raw r||s, openssl dgst only reads DER, so wrap it before verifying
  printf %s "$SIG" | base64 -d | p1363-to-der > sig.der
  openssl dgst -sha256 -verify "keys/$KID.pem" -signature sig.der canon.txt \
    || { echo "rejecting response" >&2; return 1; }
  # A valid signature says the server sent this body. The echo says it sent it to
  # YOU: a recording of someone else's 200 verifies just as well without this.
  [ "$(jq -r .clientNonce "$_bd")" = "$_cn" ] \
    || { echo "nonce echo mismatch" >&2; return 1; }
}

# Gate on this one. A good signature only proves the server said this, and it
# signs its refusals too. The status is inside the signed material, so reading it
# here is reading something the server committed to.
licentry_accepted() {
  licentry_verify "$@" || return 1
  case "$1" in 2??) return 0 ;; esac
  echo "server refused: HTTP $1" >&2
  return 1
}

#include <openssl/ecdsa.h>
#include <openssl/evp.h>
#include <openssl/sha.h>

// pinned is the key named by X-Licentry-Sig-Kid; rs is the raw 64 byte r||s.
// A response with no X-Licentry-Sig arrives here as an empty rs and fails the
// size check below: no header is a refusal, not a skip.
bool verifySig(EVP_PKEY* pinned, int status, const std::string& ts,
               const std::string& body, const std::vector<uint8_t>& rs, long now) {
  // Two-sided: a rewound wall clock must not widen the replay window.
  if (rs.size() != 64 || std::labs(now - std::stol(ts)) > 300) return false;
  unsigned char d[32];
  SHA256(reinterpret_cast<const unsigned char*>(body.data()), body.size(), d);
  char hex[65];
  for (int i = 0; i < 32; i++) sprintf(hex + i * 2, "%02x", d[i]);
  std::string msg = std::to_string(status) + "|" + ts + "|" + std::string(hex, 64);
  ECDSA_SIG* sig = ECDSA_SIG_new();
  ECDSA_SIG_set0(sig, BN_bin2bn(rs.data(), 32, nullptr),
                 BN_bin2bn(rs.data() + 32, 32, nullptr));
  unsigned char* der = nullptr;                 // OpenSSL verifies DER, not P1363
  int derLen = i2d_ECDSA_SIG(sig, &der);
  EVP_MD_CTX* ctx = EVP_MD_CTX_new();
  EVP_DigestVerifyInit(ctx, nullptr, EVP_sha256(), nullptr, pinned);
  bool ok = EVP_DigestVerify(ctx, der, derLen,
                             reinterpret_cast<const unsigned char*>(msg.data()),
                             msg.size()) == 1;
  EVP_MD_CTX_free(ctx); OPENSSL_free(der); ECDSA_SIG_free(sig);
  return ok;
}

// Call this, not verifySig, at the point where the answer decides anything.
// A signed 403 license_suspended verifies perfectly: the server really did say
// it. Treating "signature valid" as "licence valid" is the mistake that turns a
// correct implementation into an open door.
bool accepted(EVP_PKEY* pinned, int status, const std::string& ts,
              const std::string& body, const std::vector<uint8_t>& rs, long now) {
  if (!verifySig(pinned, status, ts, body, rs, now)) return false;
  return status >= 200 && status < 300;
}

using System.Security.Cryptography;
using System.Text;

// pinned holds P-256 keys by kid; VerifyData reads the raw r||s, no DER wrapping
// Returns the STATUS alongside the body. A bool would read as "everything is
// fine", and a signed 403 license_suspended would satisfy it: the server really
// did sign that refusal. Callers must branch on Status, not on the call itself.
readonly record struct Verified(int Status, byte[] Body);

static Verified Verify(HttpResponseMessage res, byte[] rawBody,
                       IReadOnlyDictionary<string, ECDsa> pinned) {
    // No X-Licentry-Sig at all is a REFUSAL, not a skip. A product with vendor
    // response signing on and an account key the server cannot load answers with
    // no signature header, and "check it when it is there" waves that through.
    if (!res.Headers.TryGetValues("X-Licentry-Sig", out _))
        throw new CryptographicException("unsigned response");
    var ts = long.Parse(res.Headers.GetValues("X-Licentry-Sig-Ts").First());
    // Two-sided: a rewound wall clock must not widen the replay window.
    if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - ts) > 300)
        throw new CryptographicException("stale signature");
    var kid = res.Headers.GetValues("X-Licentry-Sig-Kid").First();
    if (!pinned.TryGetValue(kid, out var key))
        throw new CryptographicException("unknown kid");
    var sig = Convert.FromBase64String(res.Headers.GetValues("X-Licentry-Sig").First());
    if (sig.Length != 64) throw new CryptographicException("expected raw r||s");
    var digest = Convert.ToHexString(SHA256.HashData(rawBody)).ToLowerInvariant();
    var msg = Encoding.UTF8.GetBytes($"{(int)res.StatusCode}|{ts}|{digest}");
    if (!key.VerifyData(msg, sig, HashAlgorithmName.SHA256,
                        DSASignatureFormat.IeeeP1363FixedFieldConcatenation))
        throw new CryptographicException("bad signature");
    return new Verified((int)res.StatusCode, rawBody);
}

import base64
import hashlib
import time
from cryptography.exceptions import InvalidSignature
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.asymmetric import ec, utils


def verify(resp, pinned):  # pinned: kid -> EllipticCurvePublicKey
    # No X-Licentry-Sig at all is a REFUSAL, not a skip. A product with vendor
    # response signing on and an account key the server cannot load answers with
    # no signature header, and "check it when it is there" waves that through.
    if "X-Licentry-Sig" not in resp.headers:
        raise InvalidSignature("unsigned response")
    ts = int(resp.headers["X-Licentry-Sig-Ts"])
    key = pinned.get(resp.headers["X-Licentry-Sig-Kid"])
    if key is None or abs(time.time() - ts) > 300:
        raise InvalidSignature("unknown kid or stale timestamp")
    raw = base64.b64decode(resp.headers["X-Licentry-Sig"])
    if len(raw) != 64:
        raise InvalidSignature("expected raw r||s")
    der = utils.encode_dss_signature(int.from_bytes(raw[:32], "big"),
                                     int.from_bytes(raw[32:], "big"))
    digest = hashlib.sha256(resp.content).hexdigest()
    msg = f"{resp.status_code}|{ts}|{digest}".encode()
    key.verify(der, msg, ec.ECDSA(hashes.SHA256()))  # raises, so callers fail closed
    # Hand back the status too. Returning only the body invites
    # "if verify(resp, pinned): run()", and a signed 403 license_suspended is a
    # truthy dict: the server really did sign that refusal.
    return resp.status_code, resp.json()

import { webcrypto as crypto } from "node:crypto";

// pinned: kid -> CryptoKey imported as ECDSA P-256; WebCrypto wants the raw r||s
export async function verifySigned(res, pinned) {
  const raw = Buffer.from(await res.arrayBuffer());
  // No x-licentry-sig at all is a REFUSAL, not a skip. A product with vendor
  // response signing on and an account key the server cannot load answers with
  // no signature header, and "check it when it is there" waves that through.
  if (!res.headers.get("x-licentry-sig")) throw new Error("unsigned response");
  const ts = Number(res.headers.get("x-licentry-sig-ts"));
  const key = pinned.get(res.headers.get("x-licentry-sig-kid"));
  if (!key || Math.abs(Date.now() / 1000 - ts) > 300) {
    throw new Error("unknown kid or stale timestamp");
  }
  const sig = Buffer.from(res.headers.get("x-licentry-sig"), "base64");
  const hash = await crypto.subtle.digest("SHA-256", raw);
  const digest = Buffer.from(hash).toString("hex");
  const msg = new TextEncoder().encode(`${res.status}|${ts}|${digest}`);
  const ok = await crypto.subtle.verify({ name: "ECDSA", hash: "SHA-256" },
                                        key, sig, msg);
  if (!ok) throw new Error("bad signature");  // fail closed, never use the body
  // Return the STATUS too. A verified 403 license_suspended is still a refusal:
  // a helper that hands back only the body invites "if (await verify(res)) run()".
  return { status: res.status, body: JSON.parse(raw.toString("utf8")) };
}

// the header carries raw r||s, so split it and hand the halves to ecdsa.Verify
func Verify(res *http.Response, body []byte, pinned map[string]*ecdsa.PublicKey) bool {
	ts, err := strconv.ParseInt(res.Header.Get("X-Licentry-Sig-Ts"), 10, 64)
	// Two-sided: a rewound wall clock must not widen the replay window.
	skew := time.Now().Unix() - ts
	if err != nil || skew > 300 || skew < -300 {
		return false
	}
	pub, ok := pinned[res.Header.Get("X-Licentry-Sig-Kid")]
	if !ok {
		return false
	}
	// No X-Licentry-Sig at all is a refusal, not a skip: a product with vendor
	// response signing on and an account key the server cannot load answers with
	// no signature header, and "check it when it is there" waves that through.
	sigHdr := res.Header.Get("X-Licentry-Sig")
	if sigHdr == "" {
		return false
	}
	sig, err := base64.StdEncoding.DecodeString(sigHdr)
	if err != nil || len(sig) != 64 {
		return false
	}
	sum := sha256.Sum256(body)
	msg := fmt.Sprintf("%d|%d|%x", res.StatusCode, ts, sum)
	digest := sha256.Sum256([]byte(msg))
	r := new(big.Int).SetBytes(sig[:32])
	s := new(big.Int).SetBytes(sig[32:])
	return ecdsa.Verify(pub, digest[:], r, s) // false means drop the response
}

// Accepted is what call sites should use. Verify answers "did the server sign
// this", which a 403 license_suspended also satisfies, so verifying alone is
// not permission to run. The status travels inside the signed material, so
// checking it here is checking something the server committed to.
func Accepted(res *http.Response, body []byte, pinned map[string]*ecdsa.PublicKey) bool {
	if !Verify(res, body, pinned) {
		return false
	}
	return res.StatusCode >= 200 && res.StatusCode < 300
}

use p256::ecdsa::{signature::Verifier, Signature, VerifyingKey};
use sha2::{Digest, Sha256};

// Signature::from_slice takes the raw 64 byte r||s the header carries
pub fn verify(status: u16, headers: &HeaderMap, body: &[u8],
              pinned: &HashMap<String, VerifyingKey>) -> Result<(), Error> {
    // Indexing a HeaderMap panics when the header is absent, and a panic is not
    // a refusal. No X-Licentry-Sig at all IS a refusal: a product with vendor
    // response signing on and an account key the server cannot load answers with
    // no signature header, and "check it when it is there" waves that through.
    let sig_hdr = headers.get("x-licentry-sig").ok_or(Error::Unsigned)?;
    let ts: i64 = headers.get("x-licentry-sig-ts").ok_or(Error::Unsigned)?
        .to_str()?.parse()?;
    if (Utc::now().timestamp() - ts).abs() > 300 {
        return Err(Error::Stale);
    }
    let kid = headers.get("x-licentry-sig-kid").ok_or(Error::Unsigned)?.to_str()?;
    let key = pinned.get(kid).ok_or(Error::UnknownKid)?;
    let raw = BASE64.decode(sig_hdr.as_bytes())?;
    let sig = Signature::from_slice(&raw)?;
    let digest = hex::encode(Sha256::digest(body));
    let msg = format!("{status}|{ts}|{digest}");
    key.verify(msg.as_bytes(), &sig).map_err(|_| Error::BadSignature)?;
    // Ok(()) here would mean "authentic", and callers read that as "allowed".
    // A 403 license_suspended is authentic. Separate the two so the question
    // mark operator cannot silently turn a refusal into a green light.
    if !(200..300).contains(&status) {
        return Err(Error::Refused(status));
    }
    Ok(())
}

// plain SHA256withECDSA parses DER; the P1363 variant takes the raw r||s directly
static boolean verify(HttpResponse<byte[]> res, Map<String, PublicKey> pinned)
        throws Exception {
    HttpHeaders h = res.headers();
    // No X-Licentry-Sig at all is a REFUSAL, not a skip. A product with vendor
    // response signing on and an account key the server cannot load answers with
    // no signature header, and "check it when it is there" waves that through.
    if (h.firstValue("X-Licentry-Sig").isEmpty()
            || h.firstValue("X-Licentry-Sig-Ts").isEmpty()) return false;
    long ts = Long.parseLong(h.firstValue("X-Licentry-Sig-Ts").orElseThrow());
    // Two-sided: a rewound wall clock must not widen the replay window.
    if (Math.abs(Instant.now().getEpochSecond() - ts) > 300) return false;
    PublicKey key = pinned.get(h.firstValue("X-Licentry-Sig-Kid").orElse(""));
    if (key == null) return false;
    byte[] rs = Base64.getDecoder()
            .decode(h.firstValue("X-Licentry-Sig").orElseThrow());
    if (rs.length != 64) return false;
    String digest = HexFormat.of().formatHex(
            MessageDigest.getInstance("SHA-256").digest(res.body()));
    String msg = res.statusCode() + "|" + ts + "|" + digest;
    Signature v = Signature.getInstance("SHA256withECDSAinP1363Format");
    v.initVerify(key);
    v.update(msg.getBytes(StandardCharsets.UTF_8));
    return v.verify(rs); // a false here must reject the response
}

// Use this where the answer decides whether the product runs. verify() asks
// whether the server signed the response, and it signs its refusals too, so a
// 403 license_suspended passes it. The status is covered by the signature, so
// testing it here is testing something that cannot be edited in transit.
static boolean accepted(HttpResponse<byte[]> res, Map<String, PublicKey> pinned)
        throws Exception {
    if (!verify(res, pinned)) return false;
    return res.statusCode() >= 200 && res.statusCode() < 300;
}

<?php
// Call this before curl_exec to capture the response headers, lowercased.
function collectHeaders($ch, array &$h): void
{
    curl_setopt($ch, CURLOPT_HEADERFUNCTION, function ($ch, $line) use (&$h) {
        $p = explode(':', $line, 2);
        if (count($p) === 2) {
            $h[strtolower(trim($p[0]))] = trim($p[1]);
        }
        return strlen($line);
    });
}

// openssl_verify parses DER, the header is raw r||s, so wrap it first
function licentryVerify(int $status, array $h, string $body, array $pinned): bool
{
    // No X-Licentry-Sig at all is a REFUSAL, not a skip. A product with vendor
    // response signing on and an account key the server cannot load answers with
    // no signature header, and "check it when it is there" waves that through.
    if (!isset($h['x-licentry-sig'], $h['x-licentry-sig-ts'], $h['x-licentry-sig-kid'])) {
        return false;
    }
    $ts = (int) $h['x-licentry-sig-ts'];
    if (abs(time() - $ts) > 300) {
        return false;
    }
    $pem = $pinned[$h['x-licentry-sig-kid']] ?? null;
    if ($pem === null) {
        return false;
    }
    $rs = base64_decode($h['x-licentry-sig'], true);
    if ($rs === false || strlen($rs) !== 64) {
        return false;
    }
    $der = derFromP1363($rs);
    $msg = $status . '|' . $ts . '|' . hash('sha256', $body);
    return openssl_verify($msg, $der, $pem, OPENSSL_ALGO_SHA256) === 1;
}

// Gate on this, not on licentryVerify. The server signs its refusals as well as
// its approvals, so a 403 license_suspended clears the signature check. The
// status is inside the signed material, which is why it is safe to trust here.
function licentryAccepted(int $status, array $h, string $body, array $pinned): bool
{
    if (!licentryVerify($status, $h, $body, $pinned)) {
        return false;
    }
    return $status >= 200 && $status < 300;
}

import CryptoKit

// ECDSASignature(rawRepresentation:) is exactly the r||s the header carries
func verify(_ res: HTTPURLResponse, body: Data,
            pinned: [String: P256.Signing.PublicKey]) -> Bool {
    func h(_ n: String) -> String? { res.value(forHTTPHeaderField: n) }
    guard let tsText = h("X-Licentry-Sig-Ts"), let ts = TimeInterval(tsText),
          let kid = h("X-Licentry-Sig-Kid"), let key = pinned[kid],
          let sigText = h("X-Licentry-Sig"),
          let raw = Data(base64Encoded: sigText), raw.count == 64,
          abs(Date().timeIntervalSince1970 - ts) <= 300,
          let sig = try? P256.Signing.ECDSASignature(rawRepresentation: raw)
    // A missing header lands here and returns false: an unsigned response is a
    // REFUSAL, not a skip. A product with vendor response signing on and an
    // account key the server cannot load sends no signature header at all.
    else { return false }
    let digest = SHA256.hash(data: body).map { String(format: "%02x", $0) }.joined()
    let msg = Data("\(res.statusCode)|\(Int(ts))|\(digest)".utf8)
    return key.isValidSignature(sig, for: msg)
}

// Branch on this at the point of decision. verify answers "is this really from
// the server", and the server signs refusals too, so a 403 license_suspended
// returns true. The status is part of what was signed, so reading it here is
// reading a value the server committed to.
func accepted(_ res: HTTPURLResponse, body: Data,
              pinned: [String: P256.Signing.PublicKey]) -> Bool {
    guard verify(res, body: body, pinned: pinned) else { return false }
    return (200..<300).contains(res.statusCode)
}

// SHA256withECDSA would want DER; the P1363 name verifies the raw r||s as sent
fun verify(res: Response, body: ByteArray, pinned: Map<String, PublicKey>): Boolean {
    val ts = res.header("X-Licentry-Sig-Ts")?.toLongOrNull() ?: return false
    // Two-sided: a rewound wall clock must not widen the replay window.
    if (abs(Instant.now().epochSecond - ts) > 300) return false
    val key = pinned[res.header("X-Licentry-Sig-Kid")] ?: return false
    // No X-Licentry-Sig at all is a REFUSAL, not a skip. A product with vendor
    // response signing on and an account key the server cannot load answers with
    // no signature header, and "check it when it is there" waves that through.
    val sigHdr = res.header("X-Licentry-Sig") ?: return false
    val rs = Base64.getDecoder().decode(sigHdr)
    if (rs.size != 64) return false
    val digest = MessageDigest.getInstance("SHA-256").digest(body)
        .joinToString("") { "%02x".format(it) }
    val msg = listOf(res.code, ts, digest).joinToString("|")
    val v = Signature.getInstance("SHA256withECDSAinP1363Format")
    v.initVerify(key)
    v.update(msg.toByteArray())
    return v.verify(rs) // false means drop the response
}

// Gate on this. verify only says the bytes came from the server, and the server
// signs its refusals too, so a 403 license_suspended satisfies it. The status is
// covered by the signature, so it cannot have been rewritten in transit.
fun accepted(res: Response, body: ByteArray, pinned: Map<String, PublicKey>): Boolean {
    if (!verify(res, body, pinned)) return false
    return res.code in 200..299
}

require "openssl"

# the header is raw r||s, OpenSSL verifies DER, so rebuild the ASN.1 sequence
def verify!(res, body, pinned)
  # No X-Licentry-Sig at all is a REFUSAL, not a skip. A product with vendor
  # response signing on and an account key the server cannot load answers with
  # no signature header, and "check it when it is there" waves that through.
  raise "unsigned response" if res["X-Licentry-Sig"].nil?

  ts = res["X-Licentry-Sig-Ts"].to_i
  raise "stale signature" if (Time.now.to_i - ts).abs > 300

  key = pinned.fetch(res["X-Licentry-Sig-Kid"])
  rs = res["X-Licentry-Sig"].unpack1("m")
  raise "expected raw r||s" unless rs.bytesize == 64

  r = OpenSSL::BN.new(rs[0, 32].unpack1("H*"), 16)
  s = OpenSSL::BN.new(rs[32, 32].unpack1("H*"), 16)
  der = OpenSSL::ASN1::Sequence.new([OpenSSL::ASN1::Integer.new(r),
                                     OpenSSL::ASN1::Integer.new(s)]).to_der
  msg = "#{res.code}|#{ts}|#{OpenSSL::Digest::SHA256.hexdigest(body)}"
  raise "signature rejected" unless key.verify(OpenSSL::Digest.new("SHA256"), der, msg)

  # Return the status with the body. Handing back only the body reads as
  # success at the call site, and a signed 403 license_suspended is a perfectly
  # authentic refusal. The status is inside the signed material, so it is safe
  # to act on once the signature checks out.
  [res.code.to_i, JSON.parse(body)]
end

# activate, refresh_session and stop_licensed_work are your own functions: the
# first two are the samples above, and each returns non-zero when refused.
SEQ=1            # back to 1 after activate and after every refresh
SERVER_NONCE=""  # empty on the first beat, then whatever the server last sent
REACTIVATED=0
while :; do
  CN=$(openssl rand -hex 8)   # fresh every request, never reused
  REQ=$(printf '{"seq":%d,"deviceHash":"%s","serverNonce":"%s","clientNonce":"%s"}' \
    "$SEQ" "$DEVICE_HASH" "$SERVER_NONCE" "$CN")
  CODE=$(curl -sS -D beat.hdr -o beat.json -w '%{http_code}' \
    -X POST "$BASE/v1/sess/heartbeat" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -H "x-licentry-build: $BUILD_TOKEN" \
    -H "x-licentry-protocol: 1" \
    -d "$REQ")
  # 429 and 5xx decide nothing about the licence and need not come from the app
  # at all, so they are handled before verification. Back off and resend the
  # IDENTICAL body: same SEQ, same SERVER_NONCE, same request.
  case "$CODE" in 429|5??) sleep 30; continue ;; esac
  # Everything below decides whether the product keeps running, so verify it
  # before reading a single field out of the body.
  licentry_verify "$CODE" beat.hdr beat.json "$CN" || exit 1
  ERR=$(jq -r '.error // ""' beat.json)
  case "$CODE" in
    200) ;;
    403|426) echo "terminal: $ERR" >&2; exit 1 ;;   # killed, suspended, build retired
    409) refresh_session || exit 1; SEQ=1; continue ;;  # the nonce chain carries over
    401)
      case "$ERR" in
        invalid_session)    # evicted or gone. Activate ONCE, after a backoff.
          [ "$REACTIVATED" = 1 ] && { echo "activation did not hold" >&2; exit 1; }
          REACTIVATED=1; sleep 5
          activate || exit 1; SEQ=1; SERVER_NONCE=""; continue ;;
        expired)            # refresh; activate only if the refresh is refused too
          refresh_session || { activate || exit 1; SERVER_NONCE=""; }
          SEQ=1; continue ;;
        revoked)            # terminal. Stop, and point the user at their seller.
          echo "licence revoked" >&2; exit 1 ;;
        stale_revocation)   # stop the licensed work first, then honour the answer
          stop_licensed_work
          activate || exit 1; SEQ=1; SERVER_NONCE=""; continue ;;
        nonce_mismatch)     # a refresh cannot repair the chain, only a new session
          activate || exit 1; SEQ=1; SERVER_NONCE=""; continue ;;
        dpop_*)             # dpop_required and every other dpop_ code
          # Mint a FRESH proof and repeat this beat unchanged: same SEQ, same
          # SERVER_NONCE. Activating again spends a device slot on something a
          # new proof fixes on its own.
          continue ;;
        *)                  # a bare sentence with no code: the Authorization
          # header is missing or blank. That is a bug in this script, and
          # another activation will not fix it.
          echo "fix the Authorization header: $ERR" >&2; exit 1 ;;
      esac ;;
    *) echo "permanent: HTTP $CODE $ERR" >&2; exit 1 ;;  # a 400 never clears on a timer
  esac
  SERVER_NONCE=$(jq -r .serverNonce beat.json)
  EXP=$(jq -r .expiresAt beat.json)
  SEQ=$((SEQ + 1))
  sleep $(( ($(date -d "$EXP" +%s) - $(date +%s)) / 2 ))
done

// Returns the HTTP status and fills out and hdr. 200 on its own is not
// permission to run: the caller verifies before it reads a field.
long heartbeat(CURL* c, const Cfg& cfg, const std::string& base,
               const std::string& access, int seq, const std::string& deviceHash,
               const std::string& serverNonce, const std::string& clientNonce,
               std::string& out, SigHdr& hdr) {
  // deviceHash is REQUIRED and the body is strict: omit it and every beat is 400.
  // serverNonce is the value from the previous beat, empty string on the first.
  std::string body = R"({"seq":)" + std::to_string(seq) +
                     R"(,"deviceHash":")" + deviceHash +
                     R"(","serverNonce":")" + serverNonce +
                     R"(","clientNonce":")" + clientNonce + R"("})";
  curl_slist* h = curl_slist_append(nullptr, "Content-Type: application/json");
  h = curl_slist_append(h, ("Authorization: Bearer " + access).c_str());
  h = curl_slist_append(h, ("x-licentry-build: " + cfg.buildToken).c_str());
  h = curl_slist_append(h, "x-licentry-protocol: 1");
  // add "DPoP: <proof>" here when the session is DPoP bound
  curl_easy_setopt(c, CURLOPT_URL, (base + "/v1/sess/heartbeat").c_str());
  curl_easy_setopt(c, CURLOPT_POSTFIELDS, body.c_str());
  curl_easy_setopt(c, CURLOPT_HTTPHEADER, h);
  curl_easy_setopt(c, CURLOPT_WRITEFUNCTION, sink);
  curl_easy_setopt(c, CURLOPT_WRITEDATA, &out);
  curl_easy_setopt(c, CURLOPT_HEADERFUNCTION, hdrSink);
  curl_easy_setopt(c, CURLOPT_HEADERDATA, &hdr);
  curl_easy_perform(c);
  long code = 0;
  curl_easy_getinfo(c, CURLINFO_RESPONSE_CODE, &code);
  curl_slist_free_all(h);
  return code;
}

// The loop. Each refusal below wants a different answer, and re-activating on
// all of them spends the device slot on problems a refresh would have fixed.
void runSession(CURL* c, const Cfg& cfg, Session& s) {
  bool reactivated = false;
  // One idempotency key per activation attempt; reuse it only if THAT attempt is
  // retried after a dropped response.
  auto reactivate = [&] { return activate(cfg, s.deviceHash, randomHex(16), s); };
  for (;;) {
    const std::string cn = randomHex(8);
    std::string out;
    SigHdr hdr;
    long code = heartbeat(c, cfg, cfg.base, s.accessToken, s.seq, s.deviceHash,
                          s.serverNonce, cn, out, hdr);
    // Not licence decisions, and they need not come from the app at all: back
    // off and resend the IDENTICAL body, same seq and same serverNonce.
    if (code == 429 || code >= 500) { sleepSeconds(30); continue; }
    // Verify before reading a single field. An empty hdr.sig fails here.
    if (!verifySig(cfg.pinned(hdr.kid), (int)code, hdr.ts, out, hdr.sig, time(nullptr)))
      return stopLicensedWork();
    auto j = json::parse(out, nullptr, false);
    if (j.is_discarded() || j.value("clientNonce", "") != cn) return stopLicensedWork();
    const std::string err = j.value("error", "");

    if (code == 403 || code == 426) return stopLicensedWork();  // killed, suspended, retired
    if (code == 409) {                                          // seq out of step
      if (!refreshSession(c, cfg, cfg.base, s.refreshToken, s.deviceHash, s))
        return stopLicensedWork();
      continue;                        // refresh sets seq to 1; the chain carries over
    }
    if (code == 401) {
      if (err == "invalid_session") {  // evicted or gone: activate ONCE, after a backoff
        if (reactivated) return stopLicensedWork();
        reactivated = true;
        sleepSeconds(5);
        if (!reactivate()) return stopLicensedWork();
        continue;
      }
      if (err == "expired") {          // refresh, and activate only if that is refused too
        if (!refreshSession(c, cfg, cfg.base, s.refreshToken, s.deviceHash, s) &&
            !reactivate()) return stopLicensedWork();
        continue;
      }
      if (err == "revoked") return stopLicensedWork();   // terminal, do not loop
      if (err == "stale_revocation") { // stop the licensed work, then honour the answer
        stopLicensedWork();
        if (!reactivate()) return;
        continue;
      }
      if (err == "nonce_mismatch") {   // only a new session repairs the chain
        if (!reactivate()) return stopLicensedWork();
        continue;
      }
      // dpop_required and every other dpop_ code: mint a FRESH proof and repeat
      // this beat unchanged, same seq and same serverNonce.
      if (err.rfind("dpop_", 0) == 0) continue;
      // A bare sentence with no code: the Authorization header is missing or
      // blank. That is a bug here, and another activation will not fix it.
      return stopLicensedWork();
    }
    if (code != 200) return stopLicensedWork();  // 400 and friends never clear on a timer

    s.serverNonce = j.value("serverNonce", "");
    s.seq++;
    sleepUntilHalfOf(j.value("expiresAt", ""));
  }
}

record Beat(bool ok, string expiresAt, long revocationVersion,
            string serverNonce, string clientNonce, string error);

int seq = 1;              // 1 after activate and after every refresh
string serverNonce = "";  // empty on the first beat
bool reactivated = false;
while (running) {
    var clientNonce = Convert.ToHexString(RandomNumberGenerator.GetBytes(8));
    var req = new HttpRequestMessage(HttpMethod.Post, "/v1/sess/heartbeat") {
        Content = JsonContent.Create(new {
            seq, deviceHash, serverNonce, clientNonce
        })
    };
    req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
    req.Headers.Add("x-licentry-build", buildToken);
    req.Headers.Add("x-licentry-protocol", "1");
    var res = await http.SendAsync(req);
    var raw = await res.Content.ReadAsByteArrayAsync();
    var code = (int)res.StatusCode;

    // Not licence decisions, and they need not come from the app at all. Back
    // off and resend the IDENTICAL body: same seq, same serverNonce.
    if (code == 429 || code >= 500) { await Task.Delay(30_000); continue; }

    // Everything below decides whether the product keeps running, so verify
    // before reading a field. Verify throws on an unsigned or forged response.
    var v = Verify(res, raw, pinned);
    var beat = JsonSerializer.Deserialize<Beat>(v.Body)!;
    if (beat.clientNonce != clientNonce) { Shutdown(); return; }

    // Terminal. An operator kill, a suspend or a retired build all land here,
    // and treating them as "try again later" is how a revoked licence keeps
    // running: blocking the API host would become the whole bypass.
    if (code == 403 || code == 426) { Shutdown(); return; }
    if (code == 409) {                              // seq out of step
        if (await Refresh() is null) { Shutdown(); return; }
        seq = 1; continue;                          // the nonce chain carries over
    }
    if (code == 401) {
        switch (beat.error) {
            case "invalid_session":     // evicted or gone: activate ONCE, after a backoff
                if (reactivated) { Shutdown(); return; }
                reactivated = true;
                await Task.Delay(5_000);
                await Activate(); seq = 1; serverNonce = ""; continue;
            case "expired":             // refresh, and activate only if that is refused too
                if (await Refresh() is null) { await Activate(); serverNonce = ""; }
                seq = 1; continue;
            case "revoked":             // terminal. Do not loop.
                Shutdown(); return;
            case "stale_revocation":    // stop the licensed work, then honour the answer
                StopLicensedWork();
                await Activate(); seq = 1; serverNonce = ""; continue;
            case "nonce_mismatch":      // only a new session repairs the chain
                await Activate(); seq = 1; serverNonce = ""; continue;
            default:
                // dpop_required and every other dpop_ code: mint a FRESH proof
                // and repeat this beat unchanged, same seq and same serverNonce.
                if (beat.error?.StartsWith("dpop_") == true) continue;
                // A bare sentence with no code: the Authorization header is
                // missing or blank. A bug here, and activating cannot fix it.
                Shutdown(); return;
        }
    }
    if (code != 200) { Shutdown(); return; }  // 400 and friends never clear on a timer

    serverNonce = beat.serverNonce;
    seq++;
    await Task.Delay(HalfOf(beat.expiresAt));
}

seq = 1            # 1 after activate and after every refresh
server_nonce = ""  # empty on the first beat
reactivated = False
while running:
    client_nonce = secrets.token_hex(8)
    r = requests.post(
        f"{BASE}/v1/sess/heartbeat",
        headers={"Authorization": f"Bearer {access_token}",
                 "x-licentry-build": BUILD_TOKEN, "x-licentry-protocol": "1"},
        json={"seq": seq, "deviceHash": device_hash,
              "serverNonce": server_nonce, "clientNonce": client_nonce},
        timeout=10,
    )
    # Not licence decisions, and they need not come from the app at all. Back off
    # and resend the IDENTICAL body: same seq, same server_nonce.
    if r.status_code == 429 or r.status_code >= 500:
        time.sleep(30); continue

    # Everything below decides whether the product keeps running, so verify
    # before reading a field. verify raises on an unsigned or forged response.
    status, beat = verify(r, PINNED)
    if beat.get("clientNonce") != client_nonce:
        shutdown(); break          # not an answer to this request

    # Terminal: killed, suspended, or the build was retired. Do not fall through
    # to a retry, and do not read the body for a value that is not there.
    if status in (403, 426):
        shutdown(); break
    if status == 409:              # seq out of step
        if not refresh():
            shutdown(); break
        seq = 1; continue          # the nonce chain carries over
    if status == 401:
        err = beat.get("error", "")
        if err == "invalid_session":   # evicted or gone: activate ONCE, after a backoff
            if reactivated:
                shutdown(); break
            reactivated = True
            time.sleep(5)
            activate(); seq = 1; server_nonce = ""; continue
        if err == "expired":           # refresh, and activate only if that is refused too
            if not refresh():
                activate(); server_nonce = ""
            seq = 1; continue
        if err == "revoked":           # terminal. Do not loop.
            shutdown(); break
        if err == "stale_revocation":  # stop the licensed work, then honour the answer
            stop_licensed_work()
            activate(); seq = 1; server_nonce = ""; continue
        if err == "nonce_mismatch":    # only a new session repairs the chain
            activate(); seq = 1; server_nonce = ""; continue
        if err.startswith("dpop_"):
            # dpop_required and every other dpop_ code: mint a FRESH proof and
            # repeat this beat unchanged, same seq and same server_nonce.
            continue
        # A bare sentence with no code: the Authorization header is missing or
        # blank. That is a bug here, and activating again will not fix it.
        shutdown(); break
    if status != 200:              # 400 and friends never clear on a timer
        shutdown(); break

    server_nonce = beat.get("serverNonce", "")
    seq += 1
    time.sleep(half_of(beat["expiresAt"]))

let seq = 1;            // 1 after activate and after every refresh
let serverNonce = '';   // empty on the first beat
let reactivated = false;

async function beat() {
  const clientNonce = randomBytes(8).toString('hex');
  const res = await fetch(`${BASE}/v1/sess/heartbeat`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${accessToken}`,
      'x-licentry-build': BUILD_TOKEN,
      'x-licentry-protocol': '1',
    },
    body: JSON.stringify({ seq, deviceHash, serverNonce, clientNonce }),
  });

  // Not licence decisions, and they need not come from the app at all. Back off
  // and resend the IDENTICAL body: same seq, same serverNonce.
  if (res.status === 429 || res.status >= 500) return schedule(30_000);

  // Everything below decides whether the product keeps running, so verify
  // first. verifySigned throws on an unsigned or forged response.
  const { status, body: b } = await verifySigned(res, pinned);
  if (b.clientNonce !== clientNonce) return shutdown();

  // Terminal. Anything that reschedules here turns an operator kill into a
  // retry loop, which is exactly what the kill is meant to stop.
  if (status === 403 || status === 426) return shutdown();
  if (status === 409) {                        // seq out of step
    if (!(await refresh())) return shutdown();
    seq = 1;                                   // the nonce chain carries over
    return schedule(0);
  }
  if (status === 401) {
    const err = b.error ?? '';
    if (err === 'invalid_session') {           // evicted or gone: activate ONCE
      if (reactivated) return shutdown();
      reactivated = true;
      await new Promise((r) => setTimeout(r, 5_000));   // back off first
      await activate();
      seq = 1; serverNonce = '';
      return schedule(0);
    }
    if (err === 'expired') {                   // refresh, activate only if that fails too
      if (!(await refresh())) { await activate(); serverNonce = ''; }
      seq = 1;
      return schedule(0);
    }
    if (err === 'revoked') return shutdown();  // terminal. Do not loop.
    if (err === 'stale_revocation') {          // stop the work, then honour the answer
      stopLicensedWork();
      await activate();
      seq = 1; serverNonce = '';
      return schedule(0);
    }
    if (err === 'nonce_mismatch') {            // only a new session repairs the chain
      await activate();
      seq = 1; serverNonce = '';
      return schedule(0);
    }
    // dpop_required and every other dpop_ code: mint a FRESH proof and repeat
    // this beat unchanged, same seq and same serverNonce.
    if (err.startsWith('dpop_')) return schedule(0);
    // A bare sentence with no code: the Authorization header is missing or
    // blank. That is a bug here, and activating again will not fix it.
    return shutdown();
  }
  if (status !== 200) return shutdown();   // 400 and friends never clear on a timer

  serverNonce = b.serverNonce ?? '';
  seq += 1;
  schedule(halfOf(b.expiresAt));
}

type beatResp struct {
	OK               bool   `json:"ok"`
	ExpiresAt        string `json:"expiresAt"`
	RevocationVersion int64 `json:"revocationVersion"`
	ServerNonce      string `json:"serverNonce"`
	ClientNonce      string `json:"clientNonce"`
	Error            string `json:"error"`
}

// beat classifies the answer. Each sentinel wants a different response from the
// caller, and re-activating on all of them spends the single device slot on
// problems a refresh would have fixed.
func beat(seq int, serverNonce string) (*beatResp, error) {
	cn := make([]byte, 8)
	rand.Read(cn)
	clientNonce := hex.EncodeToString(cn)

	body, _ := json.Marshal(map[string]any{
		"seq": seq, "deviceHash": deviceHash,
		"serverNonce": serverNonce, "clientNonce": clientNonce,
	})
	req, _ := http.NewRequest("POST", base+"/v1/sess/heartbeat", bytes.NewReader(body))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer "+accessToken)
	req.Header.Set("x-licentry-build", buildToken)
	req.Header.Set("x-licentry-protocol", "1")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, ErrOffline // network: your offline policy, not a licence decision
	}
	defer res.Body.Close()
	raw, _ := io.ReadAll(res.Body) // the signature covers these exact bytes

	// Not a licence decision, and need not come from the app at all.
	if res.StatusCode == 429 || res.StatusCode >= 500 {
		return nil, ErrOffline
	}
	// Everything below decides whether the product keeps running, so verify
	// before reading a field. A missing X-Licentry-Sig fails here.
	if !Verify(res, raw, pinned) {
		return nil, ErrTerminal
	}
	var b beatResp
	if err := json.Unmarshal(raw, &b); err != nil {
		return nil, ErrTerminal
	}
	if b.ClientNonce != clientNonce {
		return nil, ErrTerminal // answer to a different request, or a replay
	}

	switch res.StatusCode {
	case 200:
		return &b, nil
	case 403, 426:
		return nil, ErrTerminal // killed, suspended, build retired: stop
	case 409:
		return nil, ErrRefreshFirst // seq out of step
	case 401:
		break
	default:
		return nil, ErrPermanent // a 400 never clears on a timer
	}
	switch b.Error {
	case "invalid_session":
		return nil, ErrReactivateOnce
	case "expired":
		return nil, ErrRefreshFirst
	case "revoked":
		return nil, ErrTerminal
	case "stale_revocation":
		return nil, ErrStaleRevocation
	case "nonce_mismatch":
		return nil, ErrReactivateOnce // a refresh cannot repair the chain
	}
	if strings.HasPrefix(b.Error, "dpop_") {
		return nil, ErrSameBeatAgain
	}
	return nil, ErrClientBug // a bare sentence, no code
}

// What the caller does with each of them:
//   nil                 store ServerNonce, seq++, sleep to half of ExpiresAt
//   ErrOffline          back off, then resend the IDENTICAL body: same seq, same nonce
//   ErrSameBeatAgain    mint a FRESH DPoP proof, repeat this beat: same seq, same nonce
//   ErrRefreshFirst     refresh (seq back to 1, chain carries over); activate only
//                       if the refresh is refused as well
//   ErrReactivateOnce   back off, activate ONCE; if the next beat refuses again, stop
//   ErrStaleRevocation  stop the licensed work, activate, then honour the answer
//   ErrTerminal         stop. Do not loop.
//   ErrClientBug        the Authorization header is missing or blank. Fix the
//                       header; another activation will not help
//   ErrPermanent        stop. Retrying this on a timer loops forever

#[derive(Deserialize)]
struct Beat {
    #[serde(rename = "expiresAt")] expires_at: Option<String>,
    #[serde(rename = "serverNonce")] server_nonce: Option<String>,
    #[serde(rename = "clientNonce")] client_nonce: Option<String>,
    error: Option<String>,
}

// deviceHash is REQUIRED by the strict body schema. Sending only seq is a 400
// on every beat, and the build header is required as soon as the product asks
// for one.
fn beat(seq: u32, server_nonce: &str) -> Result<Beat> {
    let client_nonce: String = (0..16)
        .map(|_| char::from_digit(rand::random::<u32>() % 16, 16).unwrap())
        .collect();

    let res = client
        .post(format!("{base}/v1/sess/heartbeat"))
        .bearer_auth(&access_token)
        .header("x-licentry-build", &build_token)
        .header("x-licentry-protocol", "1")
        .json(&json!({
            "seq": seq,
            "deviceHash": device_hash,
            "serverNonce": server_nonce,
            "clientNonce": client_nonce,
        }))
        .send()?;

    let status = res.status().as_u16();
    let headers = res.headers().clone();
    let raw = res.bytes()?;   // the signature covers these exact bytes

    // Not a licence decision, and need not come from the app at all: back off
    // and resend the IDENTICAL body, same seq and same server_nonce.
    if status == 429 || status >= 500 {
        bail!(Offline);
    }
    // Everything below decides whether the product keeps running, so verify
    // before reading a field. An unsigned response is refused here.
    match verify(status, &headers, &raw, &pinned) {
        Ok(()) => {}
        Err(Error::Refused(_)) => {}   // signed refusal, classified below
        Err(e) => bail!(e),            // unverified: drop it and stop
    }
    let b: Beat = serde_json::from_slice(&raw)?;
    if b.client_nonce.as_deref() != Some(client_nonce.as_str()) {
        bail!(Terminal);
    }

    match status {
        200 => return Ok(b),
        403 | 426 => bail!(Terminal),      // killed, suspended, build retired
        409 => bail!(RefreshFirst),        // seq out of step
        401 => {}
        _ => bail!(Permanent),             // a 400 never clears on a timer
    }
    match b.error.as_deref().unwrap_or("") {
        "invalid_session" => bail!(ReactivateOnce),
        "expired" => bail!(RefreshFirst),
        "revoked" => bail!(Terminal),
        "stale_revocation" => bail!(StaleRevocation),
        "nonce_mismatch" => bail!(ReactivateOnce), // a refresh cannot repair the chain
        e if e.starts_with("dpop_") => bail!(SameBeatAgain),
        _ => bail!(ClientBug),             // a bare sentence, no code
    }
}

// What the caller does with each of them:
//   Ok               store server_nonce, seq += 1, sleep to half of expires_at
//   Offline          back off, then resend the IDENTICAL body: same seq, same nonce
//   SameBeatAgain    mint a FRESH DPoP proof, repeat this beat: same seq, same nonce
//   RefreshFirst     refresh (seq back to 1, chain carries over); activate only if
//                    the refresh is refused as well
//   ReactivateOnce   back off, activate ONCE; if the next beat refuses again, stop
//   StaleRevocation  stop the licensed work, activate, then honour the answer
//   Terminal         stop. Do not loop.
//   ClientBug        the Authorization header is missing or blank. Fix the header;
//                    another activation will not help
//   Permanent        stop. Retrying this on a timer loops forever

record Beat(boolean ok, String expiresAt, long revocationVersion,
            String serverNonce, String clientNonce, String error) {}

int seq = 1;              // 1 after activate and after every refresh
String serverNonce = "";  // empty on the first beat
boolean reactivated = false;

while (running) {
    byte[] n = new byte[8];
    SECURE_RANDOM.nextBytes(n);
    String clientNonce = HexFormat.of().formatHex(n);

    var body = MAPPER.writeValueAsString(Map.of(
        "seq", seq, "deviceHash", deviceHash,
        "serverNonce", serverNonce, "clientNonce", clientNonce));
    var req = HttpRequest.newBuilder(URI.create(base + "/v1/sess/heartbeat"))
        .header("Content-Type", "application/json")
        .header("Authorization", "Bearer " + accessToken)
        .header("x-licentry-build", buildToken)
        .header("x-licentry-protocol", "1")
        .POST(HttpRequest.BodyPublishers.ofString(body))
        .build();
    var res = client.send(req, HttpResponse.BodyHandlers.ofByteArray());
    int code = res.statusCode();

    // Not licence decisions, and they need not come from the app at all. Back
    // off and resend the IDENTICAL body: same seq, same serverNonce.
    if (code == 429 || code >= 500) { Thread.sleep(30_000); continue; }
    // Everything below decides whether the product keeps running, so verify
    // before parsing. A response with no X-Licentry-Sig fails here.
    if (!verify(res, PINNED)) { shutdown(); break; }

    Beat beat = MAPPER.readValue(res.body(), Beat.class);
    if (!clientNonce.equals(beat.clientNonce())) { shutdown(); break; }

    // Terminal. Do not retry: an error body has no expiresAt.
    if (code == 403 || code == 426) { shutdown(); break; }
    if (code == 409) {                          // seq out of step
        if (refresh() == null) { shutdown(); break; }
        seq = 1; continue;                      // the nonce chain carries over
    }
    if (code == 401) {
        String err = beat.error() == null ? "" : beat.error();
        if (err.equals("invalid_session")) {    // evicted or gone: activate ONCE
            if (reactivated) { shutdown(); break; }
            reactivated = true;
            Thread.sleep(5_000);                // back off before taking the seat back
            activate(); seq = 1; serverNonce = ""; continue;
        }
        if (err.equals("expired")) {            // refresh, activate only if that fails too
            if (refresh() == null) { activate(); serverNonce = ""; }
            seq = 1; continue;
        }
        if (err.equals("revoked")) { shutdown(); break; }  // terminal. Do not loop.
        if (err.equals("stale_revocation")) {   // stop the work, then honour the answer
            stopLicensedWork();
            activate(); seq = 1; serverNonce = ""; continue;
        }
        if (err.equals("nonce_mismatch")) {     // only a new session repairs the chain
            activate(); seq = 1; serverNonce = ""; continue;
        }
        // dpop_required and every other dpop_ code: mint a FRESH proof and
        // repeat this beat unchanged, same seq and same serverNonce.
        if (err.startsWith("dpop_")) { continue; }
        // A bare sentence with no code: the Authorization header is missing or
        // blank. That is a bug here, and activating again will not fix it.
        shutdown(); break;
    }
    if (code != 200) { shutdown(); break; }  // 400 and friends never clear on a timer

    serverNonce = beat.serverNonce() == null ? "" : beat.serverNonce();
    seq++;
    Thread.sleep(halfOf(beat.expiresAt()));
}

$seq = 1;           // 1 after activate and after every refresh
$serverNonce = '';  // empty on the first beat
$reactivated = false;

while ($running) {
    $clientNonce = bin2hex(random_bytes(8));
    $ch = curl_init("$base/v1/sess/heartbeat");
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Content-Type: application/json',
            "Authorization: Bearer $accessToken",
            "x-licentry-build: $buildToken",
            "x-licentry-protocol: 1",
        ],
        CURLOPT_POSTFIELDS => json_encode([
            'seq' => $seq, 'deviceHash' => $deviceHash,
            'serverNonce' => $serverNonce, 'clientNonce' => $clientNonce,
        ]),
    ]);
    $h = [];
    collectHeaders($ch, $h);
    $raw  = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);

    // Not licence decisions, and they need not come from the app at all. Back
    // off and resend the IDENTICAL body: same $seq, same $serverNonce.
    if ($code === 429 || $code >= 500) { sleep(30); continue; }
    // Everything below decides whether the product keeps running, so verify
    // before reading a field. An unsigned answer is refused here.
    if (!licentryVerify($code, $h, $raw, $pinned)) { shutdown(); break; }

    $beat = json_decode($raw, true);
    if (($beat['clientNonce'] ?? null) !== $clientNonce) { shutdown(); break; }
    $err = $beat['error'] ?? '';

    // Terminal: stop the licensed work. Anything that continues here would
    // dereference expiresAt on an error body and loop forever.
    if ($code === 403 || $code === 426) { shutdown(); break; }
    if ($code === 409) {                        // seq out of step
        if (refreshSession() === null) { shutdown(); break; }
        $seq = 1; continue;                     // the nonce chain carries over
    }
    if ($code === 401) {
        if ($err === 'invalid_session') {       // evicted or gone: activate ONCE
            if ($reactivated) { shutdown(); break; }
            $reactivated = true;
            sleep(5);                           // back off before taking the seat back
            activate(); $seq = 1; $serverNonce = ''; continue;
        }
        if ($err === 'expired') {               // refresh, activate only if that fails too
            if (refreshSession() === null) { activate(); $serverNonce = ''; }
            $seq = 1; continue;
        }
        if ($err === 'revoked') { shutdown(); break; }   // terminal. Do not loop.
        if ($err === 'stale_revocation') {      // stop the work, then honour the answer
            stopLicensedWork();
            activate(); $seq = 1; $serverNonce = ''; continue;
        }
        if ($err === 'nonce_mismatch') {        // only a new session repairs the chain
            activate(); $seq = 1; $serverNonce = ''; continue;
        }
        // dpop_required and every other dpop_ code: mint a FRESH proof and
        // repeat this beat unchanged, same $seq and same $serverNonce.
        if (str_starts_with($err, 'dpop_')) { continue; }
        // A bare sentence with no code: the Authorization header is missing or
        // blank. That is a bug here, and activating again will not fix it.
        shutdown(); break;
    }
    if ($code !== 200) { shutdown(); break; }   // a 400 never clears on a timer

    $serverNonce = $beat['serverNonce'] ?? '';
    $seq++;
    sleep(halfOf($beat['expiresAt']));
}

struct Beat: Decodable {
    let expiresAt: String?
    let serverNonce: String?
    let clientNonce: String?
    let error: String?
}

var seq = 1              // 1 after activate and after every refresh
var serverNonce = ""     // empty on the first beat

func beat() async throws -> Beat {
    var bytes = [UInt8](repeating: 0, count: 8)
    _ = SecRandomCopyBytes(kSecRandomDefault, bytes.count, &bytes)
    let clientNonce = bytes.map { String(format: "%02x", $0) }.joined()

    var req = URLRequest(url: base.appendingPathComponent("v1/sess/heartbeat"))
    req.httpMethod = "POST"
    req.setValue("application/json", forHTTPHeaderField: "Content-Type")
    req.setValue("Bearer \(accessToken)", forHTTPHeaderField: "Authorization")
    req.setValue(buildToken, forHTTPHeaderField: "x-licentry-build")
    req.setValue("1", forHTTPHeaderField: "x-licentry-protocol")
    req.httpBody = try JSONEncoder().encode([
        "seq": AnyEncodable(seq), "deviceHash": AnyEncodable(deviceHash),
        "serverNonce": AnyEncodable(serverNonce),
        "clientNonce": AnyEncodable(clientNonce),
    ])

    let (data, resp) = try await URLSession.shared.data(for: req)
    let http = resp as! HTTPURLResponse
    let code = http.statusCode

    // Not a licence decision, and need not come from the app at all: back off
    // and resend the IDENTICAL body, same seq and same serverNonce.
    if code == 429 || code >= 500 { throw LicenceError.offline }
    // Everything below decides whether the product keeps running, so verify
    // before reading a field. An unsigned response is refused in there.
    guard verify(http, body: data, pinned: pinned) else { throw LicenceError.terminal }

    let b = try JSONDecoder().decode(Beat.self, from: data)
    guard b.clientNonce == clientNonce else { throw LicenceError.terminal }

    switch code {
    case 200: break
    case 403, 426: throw LicenceError.terminal      // killed, suspended, retired
    case 409: throw LicenceError.refreshFirst       // seq out of step
    case 401:
        switch b.error ?? "" {
        case "invalid_session":  throw LicenceError.reactivateOnce
        case "expired":          throw LicenceError.refreshFirst
        case "revoked":          throw LicenceError.terminal
        case "stale_revocation": throw LicenceError.staleRevocation
        case "nonce_mismatch":   throw LicenceError.reactivateOnce
        case let e where e.hasPrefix("dpop_"): throw LicenceError.sameBeatAgain
        default: throw LicenceError.clientBug       // a bare sentence, no code
        }
    default: throw LicenceError.permanent           // a 400 never clears on a timer
    }

    serverNonce = b.serverNonce ?? ""
    seq += 1
    return b
}

// What the caller does with each of them:
//   returned Beat    store serverNonce, seq += 1, sleep to half of expiresAt
//   offline          back off, then resend the IDENTICAL body: same seq, same nonce
//   sameBeatAgain    mint a FRESH DPoP proof, repeat this beat: same seq, same nonce
//   refreshFirst     refresh (seq back to 1, chain carries over); activate only if
//                    the refresh is refused as well
//   reactivateOnce   back off, activate ONCE; if the next beat refuses again, stop
//   staleRevocation  stop the licensed work, activate, then honour the answer
//   terminal         stop. Do not loop.
//   clientBug        the Authorization header is missing or blank. Fix the header;
//                    another activation will not help
//   permanent        stop. Retrying this on a timer loops forever

data class Beat(val expiresAt: String, val serverNonce: String?,
                val clientNonce: String?, val error: String?)

var seq = 1             // 1 after activate and after every refresh
var serverNonce = ""    // empty on the first beat
var reactivated = false

while (running) {
    val clientNonce = ByteArray(8).also { SecureRandom().nextBytes(it) }
        .joinToString("") { "%02x".format(it) }

    val body = gson.toJson(mapOf(
        "seq" to seq, "deviceHash" to deviceHash,
        "serverNonce" to serverNonce, "clientNonce" to clientNonce))
    val req = Request.Builder()
        .url("$base/v1/sess/heartbeat")
        .addHeader("Authorization", "Bearer $accessToken")
        .addHeader("x-licentry-build", buildToken)
        .addHeader("x-licentry-protocol", "1")
        .post(body.toRequestBody("application/json".toMediaType()))
        .build()

    client.newCall(req).execute().use { res ->
        val code = res.code
        // Not licence decisions, and they need not come from the app at all.
        // Back off and resend the IDENTICAL body: same seq, same serverNonce.
        if (code == 429 || code >= 500) { Thread.sleep(30_000); return@use }
        val raw = res.body!!.bytes()
        // Everything below decides whether the product keeps running, so verify
        // before parsing. An unsigned response is refused inside verify.
        if (!verify(res, raw, pinned)) { shutdown(); return }
        val beat = gson.fromJson(String(raw), Beat::class.java)
        if (beat.clientNonce != clientNonce) { shutdown(); return }
        val err = beat.error ?: ""

        when {
            // Terminal. Parsing an error body for expiresAt throws instead of
            // stopping, which reads as a crash rather than a licence decision.
            code == 403 || code == 426 -> { shutdown(); return }
            code == 409 -> {                        // seq out of step
                if (refresh() == null) { shutdown(); return }
                seq = 1                             // the nonce chain carries over
            }
            code == 401 && err == "invalid_session" -> {   // evicted or gone
                if (reactivated) { shutdown(); return }     // activate ONCE
                reactivated = true
                Thread.sleep(5_000)                 // back off before taking the seat back
                activate(); seq = 1; serverNonce = ""
            }
            code == 401 && err == "expired" -> {    // refresh, activate only if that fails
                if (refresh() == null) { activate(); serverNonce = "" }
                seq = 1
            }
            code == 401 && err == "revoked" -> { shutdown(); return }  // do not loop
            code == 401 && err == "stale_revocation" -> {
                stopLicensedWork()                  // stop first, then honour the answer
                activate(); seq = 1; serverNonce = ""
            }
            code == 401 && err == "nonce_mismatch" -> {  // only a new session repairs it
                activate(); seq = 1; serverNonce = ""
            }
            // dpop_required and every other dpop_ code: mint a FRESH proof and
            // repeat this beat unchanged, same seq and same serverNonce.
            code == 401 && err.startsWith("dpop_") -> return@use
            // A bare sentence with no code: the Authorization header is missing
            // or blank. A bug here, and activating again will not fix it.
            code == 401 -> { shutdown(); return }
            code == 200 -> {
                serverNonce = beat.serverNonce ?: ""
                seq++
                Thread.sleep(halfOf(beat.expiresAt))
            }
            else -> { shutdown(); return }          // a 400 never clears on a timer
        }
    }
}

seq = 1           # 1 after activate and after every refresh
server_nonce = '' # empty on the first beat
reactivated = false

while running
  client_nonce = SecureRandom.hex(8)
  res = Net::HTTP.post(
    URI("#{BASE}/v1/sess/heartbeat"),
    { seq: seq, deviceHash: device_hash,
      serverNonce: server_nonce, clientNonce: client_nonce }.to_json,
    'Content-Type'     => 'application/json',
    'Authorization'    => "Bearer #{access_token}",
    'x-licentry-build' => BUILD_TOKEN,
    'x-licentry-protocol' => '1'
  )

  # Not licence decisions, and they need not come from the app at all. Back off
  # and resend the IDENTICAL body: same seq, same server_nonce.
  code = res.code.to_i
  if code == 429 || code >= 500
    sleep 30
    next
  end

  # Everything below decides whether the product keeps running, so verify before
  # reading a field. verify! raises on an unsigned or forged response.
  status, beat = verify!(res, res.body, PINNED)
  (shutdown; break) unless beat['clientNonce'] == client_nonce

  err = beat['error'].to_s
  # Terminal. Without these branches, sleep(nil) on an error body is the whole
  # failure mode: a revoked licence keeps the process alive and spinning.
  case status
  when 403, 426 then shutdown; break
  when 409                                   # seq out of step
    (shutdown; break) unless refresh
    seq = 1                                  # the nonce chain carries over
    next
  when 401
    case err
    when 'invalid_session'                   # evicted or gone: activate ONCE
      (shutdown; break) if reactivated
      reactivated = true
      sleep 5                                # back off before taking the seat back
      activate; seq = 1; server_nonce = ''; next
    when 'expired'                           # refresh, activate only if that fails too
      unless refresh
        activate
        server_nonce = ''
      end
      seq = 1
      next
    when 'revoked' then shutdown; break      # terminal. Do not loop.
    when 'stale_revocation'                  # stop the work, then honour the answer
      stop_licensed_work
      activate; seq = 1; server_nonce = ''; next
    when 'nonce_mismatch'                    # only a new session repairs the chain
      activate; seq = 1; server_nonce = ''; next
    else
      # dpop_required and every other dpop_ code: mint a FRESH proof and repeat
      # this beat unchanged, same seq and same server_nonce.
      next if err.start_with?('dpop_')

      # A bare sentence with no code: the Authorization header is missing or
      # blank. That is a bug here, and activating again will not fix it.
      shutdown
      break
    end
  when 200 then nil
  else shutdown; break                       # a 400 never clears on a timer
  end

  server_nonce = beat['serverNonce'].to_s
  seq += 1
  sleep half_of(beat['expiresAt'])
end

CN=$(openssl rand -hex 8)
CODE=$(curl -sS -D ref.hdr -o ref.json -w '%{http_code}' \
  -X POST "$BASE/v1/sess/refresh" \
  -H "Content-Type: application/json" \
  -H "x-licentry-build: $BUILD_TOKEN" \
  -H "x-licentry-protocol: 1" \
  -d "$(printf '{"refreshToken":"%s","deviceHash":"%s","clientNonce":"%s"}' \
        "$REFRESH_TOKEN" "$DEVICE_HASH" "$CN")")
# Signature, freshness, echo and status, all before a token is read out of the
# body. An unsigned answer is refused here, not waved through.
#   401 refresh_token_stale or invalid_session: the pair is dead, activate again
#   403 license_suspended, 426 build retired: terminal, stop
licentry_accepted "$CODE" ref.hdr ref.json "$CN" || exit 1
ACCESS_TOKEN=$(jq -r .accessToken ref.json)
REFRESH_TOKEN=$(jq -r .refreshToken ref.json)
EXPIRES_AT=$(jq -r .expiresAt ref.json)
SEQ=1            # the heartbeat sequence starts over at 1
# The nonce chain does NOT reset: keep the last SERVER_NONCE you hold. Refresh is
# also the only thing that refills the nonce retry budget, which is three.

// Returns false when the refresh was refused. Never returns a half-filled
// session: the caller must not keep using the old tokens after a refusal.
bool refreshSession(CURL* c, const Cfg& cfg, const std::string& base,
                    const std::string& refreshToken,
                    const std::string& deviceHash, Session& out) {
  // deviceHash is required: the deployment sets LICENSE_REFRESH_REQUIRE_DEVICE
  // and a bound session demands it regardless.
  std::string cn = randomHex(8);
  std::string body = R"({"refreshToken":")" + refreshToken +
                     R"(","deviceHash":")" + deviceHash +
                     R"(","clientNonce":")" + cn + R"("})";
  std::string resp;
  SigHdr hdr;
  curl_slist* h = curl_slist_append(nullptr, "Content-Type: application/json");
  h = curl_slist_append(h, ("x-licentry-build: " + cfg.buildToken).c_str());
  h = curl_slist_append(h, "x-licentry-protocol: 1");
  curl_easy_setopt(c, CURLOPT_URL, (base + "/v1/sess/refresh").c_str());
  curl_easy_setopt(c, CURLOPT_POSTFIELDS, body.c_str());
  curl_easy_setopt(c, CURLOPT_HTTPHEADER, h);
  curl_easy_setopt(c, CURLOPT_WRITEFUNCTION, sink);
  curl_easy_setopt(c, CURLOPT_WRITEDATA, &resp);
  curl_easy_setopt(c, CURLOPT_HEADERFUNCTION, hdrSink);
  curl_easy_setopt(c, CURLOPT_HEADERDATA, &hdr);
  curl_easy_perform(c);
  long code = 0;
  curl_easy_getinfo(c, CURLINFO_RESPONSE_CODE, &code);
  curl_slist_free_all(h);

  // Signature, freshness and status in one call, and an unsigned answer is
  // refused here: 401 means activate again, 403 and 426 are terminal.
  if (!accepted(cfg.pinned(hdr.kid), (int)code, hdr.ts, resp, hdr.sig, time(nullptr)))
    return false;
  auto j = json::parse(resp, nullptr, false);
  if (j.is_discarded() || j.value("clientNonce", "") != cn) return false;
  out.accessToken  = j["accessToken"];
  out.refreshToken = j["refreshToken"];
  out.expiresAt    = j["expiresAt"];
  out.seq = 1;         // the heartbeat sequence restarts; out.serverNonce does not
  return true;
}

record Refreshed(string accessToken, string refreshToken,
                 string expiresAt, string clientNonce);

// Returns null when the refresh was refused. The caller must stop, not carry on
// with the tokens it already had.
async Task<Refreshed?> Refresh() {
    var clientNonce = Convert.ToHexString(RandomNumberGenerator.GetBytes(8));
    var req = new HttpRequestMessage(HttpMethod.Post, "/v1/sess/refresh") {
        Content = JsonContent.Create(new { refreshToken, deviceHash, clientNonce })
    };
    req.Headers.Add("x-licentry-build", buildToken);
    req.Headers.Add("x-licentry-protocol", "1");
    var res = await http.SendAsync(req);
    var raw = await res.Content.ReadAsByteArrayAsync();

    // A refusal is not a session. Filling a Session object from an error body
    // leaves the old access token in place and reads as success to the caller.
    // Verify first, so an unsigned answer is refused rather than waved through.
    Verified v;
    try { v = Verify(res, raw, pinned); }
    catch (CryptographicException) { return null; }
    if (v.Status != 200) return null;   // 401 activate again, 403 and 426 terminal

    var r = JsonSerializer.Deserialize<Refreshed>(v.Body);
    if (r is null || r.clientNonce != clientNonce) return null;
    return r;   // seq restarts at 1; the nonce chain carries straight across
}

def refresh():
    client_nonce = secrets.token_hex(8)
    r = requests.post(
        f"{BASE}/v1/sess/refresh",
        headers={"x-licentry-build": BUILD_TOKEN, "x-licentry-protocol": "1"},
        json={"refreshToken": refresh_token, "deviceHash": device_hash,
              "clientNonce": client_nonce},
        timeout=10,
    )
    # Verify first, and refuse an unsigned answer instead of waving it through.
    # Indexing the body straight away raises KeyError on a refusal, which is a
    # crash where a decision belongs.
    try:
        status, s = verify(r, PINNED)
    except InvalidSignature:
        return None
    if status != 200:
        # 401 stale or invalid: activate again. 403/426: terminal.
        return None

    if s.get("clientNonce") != client_nonce:
        return None
    return {
        "access_token": s["accessToken"],
        "refresh_token": s["refreshToken"],
        "expires_at": s["expiresAt"],
        "seq": 1,   # heartbeat sequence restarts; the nonce chain does not
    }

async function refresh(session) {
  const clientNonce = randomBytes(8).toString('hex');
  const res = await fetch(`${BASE}/v1/sess/refresh`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-licentry-build': BUILD_TOKEN,
      'x-licentry-protocol': '1',
    },
    body: JSON.stringify({
      refreshToken: session.refreshToken, deviceHash, clientNonce,
    }),
  });

  // Do NOT merge the body into the session. Object.assign on a refusal keeps
  // the old accessToken, writes an error field onto the session and returns it
  // as though the refresh had worked, so a suspended licence carries on.
  // Verify first, so an unsigned answer is refused rather than waved through.
  let status, s;
  try {
    ({ status, body: s } = await verifySigned(res, pinned));
  } catch {
    return null;
  }
  if (status !== 200) return null;   // 401 activate again, 403 and 426 terminal
  if (s.clientNonce !== clientNonce) return null;
  return {
    accessToken: s.accessToken,
    refreshToken: s.refreshToken,
    expiresAt: s.expiresAt,
    seq: 1,   // heartbeat sequence restarts; the nonce chain does not
  };
}

// refresh returns (nil, err) on any refusal. It never returns a zero-valued
// Session with a nil error, which the caller would read as success.
func refresh() (*Session, error) {
	cn := make([]byte, 8)
	rand.Read(cn)
	clientNonce := hex.EncodeToString(cn)

	body, _ := json.Marshal(map[string]any{
		"refreshToken": refreshToken, "deviceHash": deviceHash,
		"clientNonce": clientNonce,
	})
	req, _ := http.NewRequest("POST", base+"/v1/sess/refresh", bytes.NewReader(body))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("x-licentry-build", buildToken)
	req.Header.Set("x-licentry-protocol", "1")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer res.Body.Close()
	raw, _ := io.ReadAll(res.Body) // the signature covers these exact bytes

	// Verify before the status, so an unsigned answer is refused rather than
	// waved through, and gate on Verify plus the status rather than on Verify
	// alone: the server signs its refusals too.
	if !Verify(res, raw, pinned) {
		return nil, ErrTerminal
	}
	switch res.StatusCode {
	case 200:
	case 401:
		return nil, ErrReactivateOnce
	case 403, 426:
		return nil, ErrTerminal
	default:
		return nil, ErrOffline
	}

	var s struct {
		AccessToken  string `json:"accessToken"`
		RefreshToken string `json:"refreshToken"`
		ExpiresAt    string `json:"expiresAt"`
		ClientNonce  string `json:"clientNonce"`
	}
	if err := json.Unmarshal(raw, &s); err != nil {
		return nil, err
	}
	if s.ClientNonce != clientNonce {
		return nil, ErrTerminal
	}
	return &Session{AccessToken: s.AccessToken, RefreshToken: s.RefreshToken,
		ExpiresAt: s.ExpiresAt, Seq: 1}, nil
}

#[derive(Deserialize)]
struct Refreshed {
    #[serde(rename = "accessToken")] access_token: String,
    #[serde(rename = "refreshToken")] refresh_token: String,
    #[serde(rename = "expiresAt")] expires_at: String,
    #[serde(rename = "clientNonce")] client_nonce: Option<String>,
}

fn refresh() -> Result<Session> {
    let client_nonce: String = (0..16)
        .map(|_| char::from_digit(rand::random::<u32>() % 16, 16).unwrap())
        .collect();

    let res = client
        .post(format!("{base}/v1/sess/refresh"))
        .header("x-licentry-build", &build_token)
        .header("x-licentry-protocol", "1")
        .json(&json!({
            "refreshToken": refresh_token,
            "deviceHash": device_hash,
            "clientNonce": client_nonce,
        }))
        .send()?;

    let status = res.status().as_u16();
    let headers = res.headers().clone();
    let raw = res.bytes()?;
    // Verify before the status, so an unsigned answer is refused rather than
    // waved through. Err(Refused) means the server signed a no, and it is a no.
    match verify(status, &headers, &raw, &pinned) {
        Ok(()) => {}
        Err(Error::Refused(401)) => bail!(ReactivateOnce), // stale or invalid pair
        Err(Error::Refused(403 | 426)) => bail!(Terminal),
        Err(Error::Refused(_)) => bail!(Offline),
        Err(_) => bail!(Unverified),                       // unsigned or forged
    }

    let s: Refreshed = serde_json::from_slice(&raw)?;
    if s.client_nonce.as_deref() != Some(client_nonce.as_str()) {
        bail!(Terminal);
    }
    Ok(Session { access_token: s.access_token, refresh_token: s.refresh_token,
                 expires_at: s.expires_at, seq: 1 })
}

record Refreshed(String accessToken, String refreshToken,
                 String expiresAt, String clientNonce) {}

// Returns null on any refusal. Do not rely on the JSON mapper to fail: with
// unknown-property handling relaxed, an error body deserializes into a record
// full of nulls and the caller carries on with a session that has no tokens.
Refreshed refresh() throws Exception {
    byte[] n = new byte[8];
    SECURE_RANDOM.nextBytes(n);
    String clientNonce = HexFormat.of().formatHex(n);

    var body = MAPPER.writeValueAsString(Map.of(
        "refreshToken", refreshToken, "deviceHash", deviceHash,
        "clientNonce", clientNonce));
    var req = HttpRequest.newBuilder(URI.create(base + "/v1/sess/refresh"))
        .header("Content-Type", "application/json")
        .header("x-licentry-build", buildToken)
        .header("x-licentry-protocol", "1")
        .POST(HttpRequest.BodyPublishers.ofString(body))
        .build();
    var res = client.send(req, HttpResponse.BodyHandlers.ofByteArray());

    // Gate on accepted rather than on the status alone: an unsigned answer is
    // refused here, and the server signs its refusals as well as its approvals.
    // 401 means activate again, 403 and 426 are terminal.
    if (!accepted(res, PINNED)) return null;
    Refreshed r = MAPPER.readValue(res.body(), Refreshed.class);
    if (r.accessToken() == null || !clientNonce.equals(r.clientNonce())) return null;
    return r;   // seq restarts at 1; the nonce chain carries straight across
}

function refreshSession(string $base, string $refreshToken, string $deviceHash,
                        string $buildToken, array $pinned): ?array {
    $clientNonce = bin2hex(random_bytes(8));
    $ch = curl_init("$base/v1/sess/refresh");
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Content-Type: application/json',
            "x-licentry-build: $buildToken",
            "x-licentry-protocol: 1",
        ],
        CURLOPT_POSTFIELDS => json_encode([
            'refreshToken' => $refreshToken,
            'deviceHash'   => $deviceHash,
            'clientNonce'  => $clientNonce,
        ]),
    ]);
    $h = [];
    collectHeaders($ch, $h);
    $raw  = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);

    // null, not an array with null tokens. A caller that gets back a shape it
    // recognises will use it. Gate on licentryAccepted so an unsigned answer is
    // refused too: 401 means activate again, 403 and 426 are terminal.
    if (!licentryAccepted($code, $h, $raw, $pinned)) return null;
    $s = json_decode($raw, true);
    if (($s['clientNonce'] ?? null) !== $clientNonce) return null;
    return [
        'accessToken'  => $s['accessToken'],
        'refreshToken' => $s['refreshToken'],
        'expiresAt'    => $s['expiresAt'],
        'seq'          => 1,
    ];
}

struct Refreshed: Decodable {
    let accessToken: String
    let refreshToken: String
    let expiresAt: String
    let clientNonce: String?
}

func refresh() async throws -> Refreshed {
    var bytes = [UInt8](repeating: 0, count: 8)
    _ = SecRandomCopyBytes(kSecRandomDefault, bytes.count, &bytes)
    let clientNonce = bytes.map { String(format: "%02x", $0) }.joined()

    var req = URLRequest(url: base.appendingPathComponent("v1/sess/refresh"))
    req.httpMethod = "POST"
    req.setValue("application/json", forHTTPHeaderField: "Content-Type")
    req.setValue(buildToken, forHTTPHeaderField: "x-licentry-build")
    req.setValue("1", forHTTPHeaderField: "x-licentry-protocol")
    req.httpBody = try JSONEncoder().encode([
        "refreshToken": refreshToken, "deviceHash": deviceHash,
        "clientNonce": clientNonce,
    ])

    let (data, resp) = try await URLSession.shared.data(for: req)
    let http = resp as! HTTPURLResponse
    // Verify before the status, so an unsigned answer is refused rather than
    // waved through, and read the status only once the signature checks out.
    guard verify(http, body: data, pinned: pinned) else { throw LicenceError.terminal }
    switch http.statusCode {
    case 200: break
    case 401: throw LicenceError.reactivateOnce
    case 403, 426: throw LicenceError.terminal
    default: throw LicenceError.offline
    }

    let s = try JSONDecoder().decode(Refreshed.self, from: data)
    guard s.clientNonce == clientNonce else { throw LicenceError.terminal }
    return s
}

data class Refreshed(val accessToken: String?, val refreshToken: String?,
                     val expiresAt: String?, val clientNonce: String?)

// Returns null on a refusal. Gson fills every field with null from an error
// body without complaining, so the status check is the only real guard.
fun refresh(): Refreshed? {
    val clientNonce = ByteArray(8).also { SecureRandom().nextBytes(it) }
        .joinToString("") { "%02x".format(it) }

    val body = gson.toJson(mapOf(
        "refreshToken" to refreshToken, "deviceHash" to deviceHash,
        "clientNonce" to clientNonce))
    val req = Request.Builder()
        .url("$base/v1/sess/refresh")
        .addHeader("x-licentry-build", buildToken)
        .addHeader("x-licentry-protocol", "1")
        .post(body.toRequestBody("application/json".toMediaType()))
        .build()

    client.newCall(req).execute().use { res ->
        val raw = res.body!!.bytes()
        // Gate on accepted rather than on the status alone: an unsigned answer
        // is refused here too. 401 means activate again, 403 and 426 terminal.
        if (!accepted(res, raw, pinned)) return null
        val s = gson.fromJson(String(raw), Refreshed::class.java)
        if (s.accessToken == null || s.clientNonce != clientNonce) return null
        return s   // seq restarts at 1; the nonce chain carries straight across
    }
}

def refresh
  client_nonce = SecureRandom.hex(8)
  res = Net::HTTP.post(
    URI("#{BASE}/v1/sess/refresh"),
    { refreshToken: refresh_token, deviceHash: device_hash,
      clientNonce: client_nonce }.to_json,
    'Content-Type'     => 'application/json',
    'x-licentry-build' => BUILD_TOKEN,
    'x-licentry-protocol' => '1'
  )

  # nil, not a Session with nil tokens. Returning a shape the caller recognises
  # is how a refusal turns into a session that quietly does nothing. Verify
  # first, so an unsigned answer is refused rather than waved through.
  begin
    status, s = verify!(res, res.body, PINNED)
  rescue StandardError
    return nil
  end
  return nil unless status == 200 # 401 activate again, 403 and 426 are terminal
  return nil unless s['clientNonce'] == client_nonce

  Session.new(
    access_token:  s['accessToken'],
    refresh_token: s['refreshToken'],
    expires_at:    s['expiresAt'],
    seq: 1 # heartbeat sequence restarts; the nonce chain does not
  )
end

# Call this when the user quits. maxConcurrentSessions defaults to 1, and a
# session that is never logged out holds its seat until the refresh window
# closes, which is days: the customer's own next launch is what gets evicted.
CN=$(openssl rand -hex 8)
CODE=$(curl -sS -D out.hdr -o out.json -w '%{http_code}' \
  -X POST "$BASE/v1/sess/logout" \
  -H "Content-Type: application/json" \
  -H "x-licentry-build: $BUILD_TOKEN" \
  -H "x-licentry-protocol: 1" \
  -d "$(jq -cn --arg t "$ACCESS_TOKEN" --arg n "$CN" \
        '{accessToken: $t, clientNonce: $n}')")
# On a DPoP bound session, add a DPoP header over this URL with ath over the
# access token. Without one a strict deployment answers 401 dpop_required, the
# logout does not happen, and the seat stays held.
# 200 {"ok":true}, never 204: a signature over an empty body proves nothing, so
# this route answers with a body, and the body carries the echo.
licentry_accepted "$CODE" out.hdr out.json "$CN" || exit 1

// Call this when the user quits. maxConcurrentSessions defaults to 1, and a
// session that is never logged out holds its seat until the refresh window
// closes, which is days: the customer's own next launch is what gets evicted.
bool logout(CURL* c, const Cfg& cfg, const std::string& base,
            const std::string& accessToken) {
  const std::string cn = randomHex(8);
  std::string body = R"({"accessToken":")" + accessToken +
                     R"(","clientNonce":")" + cn + R"("})";
  std::string resp;
  SigHdr hdr;
  curl_slist* h = curl_slist_append(nullptr, "Content-Type: application/json");
  h = curl_slist_append(h, ("x-licentry-build: " + cfg.buildToken).c_str());
  h = curl_slist_append(h, "x-licentry-protocol: 1");
  // On a DPoP bound session, add a DPoP header over this URL with ath over the
  // access token. Without one a strict deployment answers 401 dpop_required, the
  // logout does not happen, and the seat stays held.
  curl_easy_setopt(c, CURLOPT_URL, (base + "/v1/sess/logout").c_str());
  curl_easy_setopt(c, CURLOPT_POSTFIELDS, body.c_str());
  curl_easy_setopt(c, CURLOPT_HTTPHEADER, h);
  curl_easy_setopt(c, CURLOPT_WRITEFUNCTION, sink);
  curl_easy_setopt(c, CURLOPT_WRITEDATA, &resp);
  curl_easy_setopt(c, CURLOPT_HEADERFUNCTION, hdrSink);
  curl_easy_setopt(c, CURLOPT_HEADERDATA, &hdr);
  curl_easy_perform(c);
  long code = 0;
  curl_easy_getinfo(c, CURLINFO_RESPONSE_CODE, &code);
  curl_slist_free_all(h);

  // 200 {"ok":true}, never 204: a signature over an empty body proves nothing,
  // so this route answers with a body, and the body carries the echo.
  if (!accepted(cfg.pinned(hdr.kid), (int)code, hdr.ts, resp, hdr.sig, time(nullptr)))
    return false;
  auto j = json::parse(resp, nullptr, false);
  return !j.is_discarded() && j.value("clientNonce", "") == cn;
}

// Call this when the user quits. maxConcurrentSessions defaults to 1, and a
// session that is never logged out holds its seat until the refresh window
// closes, which is days: the customer's own next launch is what gets evicted.
async Task<bool> Logout(HttpClient http, string accessToken, string buildToken,
                        IReadOnlyDictionary<string, ECDsa> pinned) {
    var clientNonce = Convert.ToHexString(RandomNumberGenerator.GetBytes(8));
    // On a DPoP bound session, add a DPoP header over this URL with ath over the
    // access token. Without one a strict deployment answers 401 dpop_required,
    // the logout does not happen, and the seat stays held.
    var req = new HttpRequestMessage(HttpMethod.Post, "/v1/sess/logout") {
        Content = JsonContent.Create(new { accessToken, clientNonce })
    };
    req.Headers.Add("x-licentry-build", buildToken);
    req.Headers.Add("x-licentry-protocol", "1");
    var res = await http.SendAsync(req);
    var raw = await res.Content.ReadAsByteArrayAsync();

    // 200 {"ok":true}, never 204: a signature over an empty body proves nothing,
    // so this route answers with a body, and the body carries the echo.
    Verified v;
    try { v = Verify(res, raw, pinned); }
    catch (CryptographicException) { return false; }
    if (v.Status != 200) return false;
    var body = JsonSerializer.Deserialize<JsonElement>(v.Body);
    return body.TryGetProperty("clientNonce", out var echo) &&
           echo.GetString() == clientNonce;
}

# Call this when the user quits. maxConcurrentSessions defaults to 1, and a
# session that is never logged out holds its seat until the refresh window
# closes, which is days: the customer's own next launch is what gets evicted.
#
# On a DPoP bound session, add a DPoP header over this URL with ath over the
# access token. Without one a strict deployment answers 401 dpop_required, the
# logout does not happen, and the seat stays held.
def logout(base, build_token, access_token, pinned):
    client_nonce = secrets.token_hex(8)
    r = requests.post(
        f"{base}/v1/sess/logout",
        headers={"Content-Type": "application/json",
                 "x-licentry-build": build_token, "x-licentry-protocol": "1"},
        json={"accessToken": access_token, "clientNonce": client_nonce},
        timeout=10,
    )
    # 200 {"ok":true}, never 204: a signature over an empty body proves nothing,
    # so this route answers with a body, and the body carries the echo.
    try:
        status, body = verify(r, pinned)
    except InvalidSignature:
        return False
    return status == 200 and body.get("clientNonce") == client_nonce

// Call this when the user quits. maxConcurrentSessions defaults to 1, and a
// session that is never logged out holds its seat until the refresh window
// closes, which is days: the customer's own next launch is what gets evicted.
//
// On a DPoP bound session, add a DPoP header over this URL with ath over the
// access token. Without one a strict deployment answers 401 dpop_required, the
// logout does not happen, and the seat stays held.
export async function logout({ base, buildToken, accessToken, pinned }) {
  const clientNonce = randomBytes(8).toString("hex");
  const res = await fetch(`${base}/v1/sess/logout`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-licentry-build": buildToken,
      "x-licentry-protocol": "1",
    },
    body: JSON.stringify({ accessToken, clientNonce }),
  });
  // 200 {"ok":true}, never 204: a signature over an empty body proves nothing,
  // so this route answers with a body, and the body carries the echo.
  const { status, body } = await verifySigned(res, pinned);
  return status === 200 && body.clientNonce === clientNonce;
}

// Logout when the user quits. maxConcurrentSessions defaults to 1, and a
// session that is never logged out holds its seat until the refresh window
// closes, which is days: the customer's own next launch is what gets evicted.
func Logout(base, build, accessToken string, pinned map[string]*ecdsa.PublicKey) bool {
	cn := make([]byte, 8)
	rand.Read(cn)
	clientNonce := hex.EncodeToString(cn)

	body, _ := json.Marshal(map[string]string{
		"accessToken": accessToken, "clientNonce": clientNonce,
	})
	// On a DPoP bound session, add a DPoP header over this URL with ath over the
	// access token. Without one a strict deployment answers 401 dpop_required,
	// the logout does not happen, and the seat stays held.
	req, _ := http.NewRequest("POST", base+"/v1/sess/logout", bytes.NewReader(body))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("x-licentry-build", build)
	req.Header.Set("x-licentry-protocol", "1")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		return false
	}
	defer res.Body.Close()
	raw, _ := io.ReadAll(res.Body)

	// 200 {"ok":true}, never 204: a signature over an empty body proves nothing,
	// so this route answers with a body, and the body carries the echo.
	if !Accepted(res, raw, pinned) {
		return false
	}
	var b struct {
		ClientNonce string `json:"clientNonce"`
	}
	return json.Unmarshal(raw, &b) == nil && b.ClientNonce == clientNonce
}

// Call this when the user quits. maxConcurrentSessions defaults to 1, and a
// session that is never logged out holds its seat until the refresh window
// closes, which is days: the customer's own next launch is what gets evicted.
pub fn logout(base: &str, build: &str, access_token: &str,
              pinned: &HashMap<String, VerifyingKey>) -> Result<()> {
    let client_nonce: String = (0..16)
        .map(|_| char::from_digit(rand::random::<u32>() % 16, 16).unwrap())
        .collect();
    let res = client
        // On a DPoP bound session, add a DPoP header over this URL with ath over
        // the access token. Without one a strict deployment answers
        // 401 dpop_required, the logout does not happen, and the seat stays held.
        .post(format!("{base}/v1/sess/logout"))
        .header("x-licentry-build", build)
        .header("x-licentry-protocol", "1")
        .json(&json!({ "accessToken": access_token, "clientNonce": client_nonce }))
        .send()?;

    let status = res.status().as_u16();
    let headers = res.headers().clone();
    let raw = res.bytes()?;
    // 200 {"ok":true}, never 204: a signature over an empty body proves nothing,
    // so this route answers with a body, and the body carries the echo.
    verify(status, &headers, &raw, pinned)?;
    let b: Value = serde_json::from_slice(&raw)?;
    if b.get("clientNonce").and_then(Value::as_str) != Some(client_nonce.as_str()) {
        bail!(Terminal);
    }
    Ok(())
}

// Call this when the user quits. maxConcurrentSessions defaults to 1, and a
// session that is never logged out holds its seat until the refresh window
// closes, which is days: the customer's own next launch is what gets evicted.
boolean logout(String base, String accessToken, String buildToken) throws Exception {
    byte[] n = new byte[8];
    SECURE_RANDOM.nextBytes(n);
    String clientNonce = HexFormat.of().formatHex(n);

    var body = MAPPER.writeValueAsString(
        Map.of("accessToken", accessToken, "clientNonce", clientNonce));
    // On a DPoP bound session, add a DPoP header over this URL with ath over the
    // access token. Without one a strict deployment answers 401 dpop_required,
    // the logout does not happen, and the seat stays held.
    var req = HttpRequest.newBuilder(URI.create(base + "/v1/sess/logout"))
        .header("Content-Type", "application/json")
        .header("x-licentry-build", buildToken)
        .header("x-licentry-protocol", "1")
        .POST(HttpRequest.BodyPublishers.ofString(body))
        .build();
    var res = client.send(req, HttpResponse.BodyHandlers.ofByteArray());

    // 200 {"ok":true}, never 204: a signature over an empty body proves nothing,
    // so this route answers with a body, and the body carries the echo.
    if (!accepted(res, PINNED)) return false;
    JsonNode echo = MAPPER.readTree(res.body()).get("clientNonce");
    return echo != null && clientNonce.equals(echo.asText());
}

<?php
// Call this when the user quits. maxConcurrentSessions defaults to 1, and a
// session that is never logged out holds its seat until the refresh window
// closes, which is days: the customer's own next launch is what gets evicted.
function logoutSession(string $base, string $accessToken, string $buildToken,
                       array $pinned): bool {
    $clientNonce = bin2hex(random_bytes(8));
    // On a DPoP bound session, add a DPoP header over this URL with ath over the
    // access token. Without one a strict deployment answers 401 dpop_required,
    // the logout does not happen, and the seat stays held.
    $ch = curl_init("$base/v1/sess/logout");
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Content-Type: application/json',
            "x-licentry-build: $buildToken",
            'x-licentry-protocol: 1',
        ],
        CURLOPT_POSTFIELDS => json_encode([
            'accessToken' => $accessToken, 'clientNonce' => $clientNonce,
        ]),
    ]);
    $h = [];
    collectHeaders($ch, $h);
    $raw  = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);

    // 200 {"ok":true}, never 204: a signature over an empty body proves nothing,
    // so this route answers with a body, and the body carries the echo.
    if (!licentryAccepted($code, $h, $raw, $pinned)) {
        return false;
    }
    $b = json_decode($raw, true);
    return ($b['clientNonce'] ?? null) === $clientNonce;
}

struct LogoutAck: Decodable { let ok: Bool?; let clientNonce: String? }

// Call this when the user quits. maxConcurrentSessions defaults to 1, and a
// session that is never logged out holds its seat until the refresh window
// closes, which is days: the customer's own next launch is what gets evicted.
func logout(base: URL, build: String, accessToken: String,
            pinned: [String: P256.Signing.PublicKey]) async -> Bool {
    var bytes = [UInt8](repeating: 0, count: 8)
    _ = SecRandomCopyBytes(kSecRandomDefault, bytes.count, &bytes)
    let clientNonce = bytes.map { String(format: "%02x", $0) }.joined()

    // On a DPoP bound session, add a DPoP header over this URL with ath over the
    // access token. Without one a strict deployment answers 401 dpop_required,
    // the logout does not happen, and the seat stays held.
    var req = URLRequest(url: base.appendingPathComponent("v1/sess/logout"))
    req.httpMethod = "POST"
    req.setValue("application/json", forHTTPHeaderField: "Content-Type")
    req.setValue(build, forHTTPHeaderField: "x-licentry-build")
    req.setValue("1", forHTTPHeaderField: "x-licentry-protocol")
    req.httpBody = try? JSONEncoder().encode(["accessToken": accessToken,
                                              "clientNonce": clientNonce])

    // 200 {"ok":true}, never 204: a signature over an empty body proves nothing,
    // so this route answers with a body, and the body carries the echo.
    guard let pair = try? await URLSession.shared.data(for: req),
          let http = pair.1 as? HTTPURLResponse,
          accepted(http, body: pair.0, pinned: pinned),
          let ack = try? JSONDecoder().decode(LogoutAck.self, from: pair.0)
    else { return false }
    return ack.clientNonce == clientNonce
}

// Call this when the user quits. maxConcurrentSessions defaults to 1, and a
// session that is never logged out holds its seat until the refresh window
// closes, which is days: the customer's own next launch is what gets evicted.
fun logout(base: String, build: String, accessToken: String,
           pinned: Map<String, PublicKey>): Boolean {
    val clientNonce = ByteArray(8).also { SecureRandom().nextBytes(it) }
        .joinToString("") { "%02x".format(it) }
    val body = JSONObject()
        .put("accessToken", accessToken)
        .put("clientNonce", clientNonce)
        .toString()
    val req = Request.Builder()
        // On a DPoP bound session, add a DPoP header over this URL with ath over
        // the access token. Without one a strict deployment answers
        // 401 dpop_required, the logout does not happen, and the seat stays held.
        .url("$base/v1/sess/logout")
        .addHeader("x-licentry-build", build)
        .addHeader("x-licentry-protocol", "1")
        .post(body.toRequestBody(JSON))
        .build()
    client.newCall(req).execute().use { res ->
        val raw = res.body!!.bytes()
        // 200 {"ok":true}, never 204: a signature over an empty body proves
        // nothing, so this route answers with a body that carries the echo.
        if (!accepted(res, raw, pinned)) return false
        return JSONObject(String(raw)).optString("clientNonce") == clientNonce
    }
}

# Call this when the user quits. maxConcurrentSessions defaults to 1, and a
# session that is never logged out holds its seat until the refresh window
# closes, which is days: the customer's own next launch is what gets evicted.
#
# On a DPoP bound session, add a DPoP header over this URL with ath over the
# access token. Without one a strict deployment answers 401 dpop_required, the
# logout does not happen, and the seat stays held.
def logout(base, build_token, access_token, pinned)
  client_nonce = SecureRandom.hex(8)
  res = Net::HTTP.post(
    URI("#{base}/v1/sess/logout"),
    { accessToken: access_token, clientNonce: client_nonce }.to_json,
    'Content-Type'     => 'application/json',
    'x-licentry-build' => build_token,
    'x-licentry-protocol' => '1'
  )
  # 200 {"ok":true}, never 204: a signature over an empty body proves nothing,
  # so this route answers with a body, and the body carries the echo.
  status, body = verify!(res, res.body, pinned)
  status == 200 && body['clientNonce'] == client_nonce
rescue StandardError
  false
end

# One P-256 key per install, generated once and kept in the OS keystore.
openssl ecparam -name prime256v1 -genkey -noout -out dpop.pem
# Public JWK for activate. dpopPublicJwk is a JSON STRING, not an object.
JWK=$(openssl ec -in dpop.pem -pubout -outform DER 2>/dev/null | tail -c 64 | \
  xxd -p -c 64 | awk '{ x=substr($0,1,64); y=substr($0,65,64);
    cmd="printf %s " x " | xxd -r -p | basenc --base64url | tr -d =";
    cmd | getline X; close(cmd);
    cmd="printf %s " y " | xxd -r -p | basenc --base64url | tr -d =";
    cmd | getline Y; close(cmd);
    printf "{\"kty\":\"EC\",\"crv\":\"P-256\",\"x\":\"%s\",\"y\":\"%s\"}", X, Y }')

# The build header belongs on this call like any other session route. Without it
# a product with require_build_token on answers a deliberately generic
# activation_failed, which looks like a bad licence key and is very hard to
# diagnose from the client side.
curl -sS -X POST "$BASE/v1/sess/activate" -H "Content-Type: application/json" \
  -H "x-licentry-build: $BUILD_TOKEN" \
  -H "x-licentry-protocol: 1" \
  -d "$(jq -cn --arg k "$LICENSE_KEY" --arg d "$DEVICE_HASH" --arg j "$JWK" \
          --arg n "$(openssl rand -hex 8)" \
        '{licenseKey:$k, deviceHash:$d, dpopPublicJwk:$j, clientNonce:$n}')"

# Every later heartbeat/refresh needs a fresh proof. ath binds it to the token,
# jti makes it single use, and the server refuses a lifetime over 120s.
# On /v1/sess/refresh feed ath the REFRESH token, not the access token.
ath() { printf %s "$1" | openssl dgst -binary -sha256 | basenc --base64url | tr -d =; }
# Sign with a JOSE library: ES256 needs raw r||s, and openssl emits DER.

// Windows: hold the key in CNG (BCRYPT_ECDSA_P256_ALGORITHM) so it is never
// a file on disk. BCryptSignHash already returns raw r||s, which is what JOSE
// wants, so no DER unwrapping is needed here.
std::string b64url(const uint8_t* p, size_t n);   // no padding
std::string sha256B64Url(const std::string& s);

// Sent ONCE, at activate, as a JSON *string* in dpopPublicJwk.
std::string dpopPublicJwk(const std::vector<uint8_t>& x, const std::vector<uint8_t>& y) {
  return "{\"kty\":\"EC\",\"crv\":\"P-256\",\"x\":\"" +
         b64url(x.data(), 32) + "\",\"y\":\"" + b64url(y.data(), 32) + "\"}";
}

// One fresh proof per request. Reusing one is a replay: the server remembers jti.
// On /v1/sess/refresh pass the refresh token here: ath covers the token the call presents.
std::string dpopProof(BCRYPT_KEY_HANDLE key, const std::string& htm,
                      const std::string& htu, const std::string& accessToken) {
  const long now = (long)time(nullptr);
  std::string hdr = R"({"alg":"ES256","typ":"dpop+jwt"})";
  std::string body = "{\"htm\":\"" + htm + "\",\"htu\":\"" + htu +
      "\",\"ath\":\"" + sha256B64Url(accessToken) +
      "\",\"jti\":\"" + randomHex(16) +
      "\",\"iat\":" + std::to_string(now) +
      ",\"exp\":" + std::to_string(now + 60) + "}";
  std::string signingInput = b64urlStr(hdr) + "." + b64urlStr(body);
  std::vector<uint8_t> rs = signP256(key, sha256Raw(signingInput));  // 64 bytes
  return signingInput + "." + b64url(rs.data(), rs.size());
}
// Send as the DPoP request header. htu must be the exact URL you POST to.

using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

static string B64Url(byte[] b) => Convert.ToBase64String(b)
    .TrimEnd('=').Replace('+', '-').Replace('/', '_');

// Generate once per install and persist the key, not the JWK.
static ECDsa NewDpopKey() => ECDsa.Create(ECCurve.NamedCurves.nistP256);

// dpopPublicJwk is a JSON STRING in the activate body.
static string PublicJwk(ECDsa key) {
    var p = key.ExportParameters(false);
    return JsonSerializer.Serialize(new {
        kty = "EC", crv = "P-256", x = B64Url(p.Q.X!), y = B64Url(p.Q.Y!)
    });
}

// A fresh proof per request; jti is remembered server side, so never reuse one.
// On /v1/sess/refresh pass the refresh token here: ath covers the token the call presents.
static string DpopProof(ECDsa key, string htm, string htu, string accessToken) {
    long now = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
    string hdr = B64Url(Encoding.UTF8.GetBytes(
        JsonSerializer.Serialize(new { alg = "ES256", typ = "dpop+jwt" })));
    string ath = B64Url(SHA256.HashData(Encoding.UTF8.GetBytes(accessToken)));
    string body = B64Url(Encoding.UTF8.GetBytes(JsonSerializer.Serialize(new {
        htm, htu, ath, jti = Guid.NewGuid().ToString("N"),
        iat = now, exp = now + 60   // the server refuses a window over 120s
    })));
    string input = hdr + "." + body;
    // IeeeP1363 is raw r||s, which is what JOSE expects. The default is DER.
    byte[] sig = key.SignData(Encoding.UTF8.GetBytes(input), HashAlgorithmName.SHA256,
                              DSASignatureFormat.IeeeP1363FixedFieldConcatenation);
    return input + "." + B64Url(sig);
}
// req.Headers.Add("DPoP", DpopProof(key, "POST", url, accessToken));

import base64
import hashlib
import json
import secrets
import time
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import ec, utils


def b64u(b: bytes) -> str:
    return base64.urlsafe_b64encode(b).decode().rstrip("=")


def new_dpop_key():
    return ec.generate_private_key(ec.SECP256R1())  # once per install, then stored


def public_jwk(key) -> str:
    n = key.public_key().public_numbers()
    # A JSON STRING is what activate expects, not a nested object.
    return json.dumps({"kty": "EC", "crv": "P-256",
                       "x": b64u(n.x.to_bytes(32, "big")),
                       "y": b64u(n.y.to_bytes(32, "big"))}, separators=(",", ":"))


# On /v1/sess/refresh pass the refresh token here: ath covers the token the call presents.
def dpop_proof(key, htm: str, htu: str, access_token: str) -> str:
    now = int(time.time())
    hdr = b64u(json.dumps({"alg": "ES256", "typ": "dpop+jwt"},
                          separators=(",", ":")).encode())
    body = b64u(json.dumps({
        "htm": htm, "htu": htu,
        "ath": b64u(hashlib.sha256(access_token.encode()).digest()),
        "jti": secrets.token_hex(16),   # single use; the server remembers it
        "iat": now, "exp": now + 60,    # a window over 120s is refused
    }, separators=(",", ":")).encode())
    signing_input = f"{hdr}.{body}".encode()
    der = key.sign(signing_input, ec.ECDSA(hashes.SHA256()))
    r, s = utils.decode_dss_signature(der)   # JOSE wants raw r||s, not DER
    raw = r.to_bytes(32, "big") + s.to_bytes(32, "big")
    return f"{hdr}.{body}.{b64u(raw)}"

# headers={"DPoP": dpop_proof(key, "POST", url, access_token)}

import { webcrypto as crypto } from "node:crypto";

const b64u = (b) => Buffer.from(b).toString("base64url");

// Generate once, then persist the key. extractable:false keeps the private half
// out of your own process memory as a serialisable value.
export async function newDpopKey() {
  return crypto.subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" },
                                   false, ["sign"]);
}

// dpopPublicJwk is a JSON STRING in the activate body, not an object.
export async function publicJwk(pair) {
  const j = await crypto.subtle.exportKey("jwk", pair.publicKey);
  return JSON.stringify({ kty: "EC", crv: "P-256", x: j.x, y: j.y });
}

// On /v1/sess/refresh pass the refresh token here: ath covers the token the call presents.
export async function dpopProof(pair, htm, htu, accessToken) {
  const now = Math.floor(Date.now() / 1000);
  const hdr = b64u(JSON.stringify({ alg: "ES256", typ: "dpop+jwt" }));
  const ath = b64u(await crypto.subtle.digest("SHA-256",
                     new TextEncoder().encode(accessToken)));
  const body = b64u(JSON.stringify({
    htm, htu, ath,
    jti: crypto.randomUUID(),   // single use; the server remembers it
    iat: now, exp: now + 60,    // the server refuses a window over 120s
  }));
  const input = new TextEncoder().encode(hdr + "." + body);
  // WebCrypto ECDSA output is already raw r||s, which is what JOSE expects.
  const sig = await crypto.subtle.sign({ name: "ECDSA", hash: "SHA-256" },
                                       pair.privateKey, input);
  return hdr + "." + body + "." + b64u(sig);
}
// headers: { DPoP: await dpopProof(pair, "POST", url, accessToken) }

// Generate once per install with ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
// and persist it in the OS keystore.

func b64u(b []byte) string { return base64.RawURLEncoding.EncodeToString(b) }

// dpopPublicJwk is a JSON STRING in the activate body.
func PublicJWK(k *ecdsa.PrivateKey) string {
	x := make([]byte, 32)
	y := make([]byte, 32)
	k.X.FillBytes(x)
	k.Y.FillBytes(y)
	return fmt.Sprintf(`{"kty":"EC","crv":"P-256","x":"%s","y":"%s"}`, b64u(x), b64u(y))
}

// On /v1/sess/refresh pass the refresh token here: ath covers the token the call presents.
func DpopProof(k *ecdsa.PrivateKey, htm, htu, accessToken string) (string, error) {
	now := time.Now().Unix()
	hdr := b64u([]byte(`{"alg":"ES256","typ":"dpop+jwt"}`))
	sum := sha256.Sum256([]byte(accessToken))
	jti := make([]byte, 16)
	rand.Read(jti)
	claims, _ := json.Marshal(map[string]any{
		"htm": htm, "htu": htu, "ath": b64u(sum[:]),
		"jti": hex.EncodeToString(jti), // single use; the server remembers it
		"iat": now, "exp": now + 60,    // a window over 120s is refused
	})
	input := hdr + "." + b64u(claims)
	digest := sha256.Sum256([]byte(input))
	r, s, err := ecdsa.Sign(rand.Reader, k, digest[:])
	if err != nil {
		return "", err
	}
	// JOSE wants fixed-width raw r||s, not the ASN.1 form ecdsa.SignASN1 gives.
	rs := make([]byte, 64)
	r.FillBytes(rs[:32])
	s.FillBytes(rs[32:])
	return input + "." + b64u(rs), nil
}
// req.Header.Set("DPoP", proof)

use p256::ecdsa::{signature::Signer, Signature, SigningKey};
use sha2::{Digest, Sha256};

fn b64u(b: &[u8]) -> String { URL_SAFE_NO_PAD.encode(b) }

// SigningKey::random(&mut OsRng) once per install, then persist it.
pub fn public_jwk(key: &SigningKey) -> String {
    let pt = key.verifying_key().to_encoded_point(false);
    // dpopPublicJwk is a JSON STRING in the activate body.
    format!(
        r#"{{"kty":"EC","crv":"P-256","x":"{}","y":"{}"}}"#,
        b64u(pt.x().unwrap()), b64u(pt.y().unwrap())
    )
}

// On /v1/sess/refresh pass the refresh token here: ath covers the token the call presents.
pub fn dpop_proof(key: &SigningKey, htm: &str, htu: &str, access_token: &str) -> String {
    let now = Utc::now().timestamp();
    let hdr = b64u(br#"{"alg":"ES256","typ":"dpop+jwt"}"#);
    let ath = b64u(&Sha256::digest(access_token.as_bytes()));
    let jti: [u8; 16] = rand::random();
    let claims = serde_json::json!({
        "htm": htm, "htu": htu, "ath": ath,
        "jti": hex::encode(jti),      // single use; the server remembers it
        "iat": now, "exp": now + 60,  // a window over 120s is refused
    });
    let input = format!("{hdr}.{}", b64u(claims.to_string().as_bytes()));
    // p256 signs to fixed-width r||s already, which is what JOSE expects.
    let sig: Signature = key.sign(input.as_bytes());
    format!("{input}.{}", b64u(&sig.to_bytes()))
}
// .header("DPoP", dpop_proof(&key, "POST", url, access_token))

// KeyPairGenerator.getInstance("EC") with an ECGenParameterSpec of "secp256r1",
// generated once per install and kept in the platform KeyStore.

static String b64u(byte[] b) { return Base64.getUrlEncoder().withoutPadding().encodeToString(b); }

// dpopPublicJwk is a JSON STRING in the activate body.
static String publicJwk(ECPublicKey pub) {
    byte[] x = toFixed32(pub.getW().getAffineX());
    byte[] y = toFixed32(pub.getW().getAffineY());
    return "{\"kty\":\"EC\",\"crv\":\"P-256\",\"x\":\"" + b64u(x)
         + "\",\"y\":\"" + b64u(y) + "\"}";
}

// On /v1/sess/refresh pass the refresh token here: ath covers the token the call presents.
static String dpopProof(PrivateKey key, String htm, String htu, String accessToken)
        throws Exception {
    long now = Instant.now().getEpochSecond();
    String hdr = b64u("{\"alg\":\"ES256\",\"typ\":\"dpop+jwt\"}".getBytes(UTF_8));
    String ath = b64u(MessageDigest.getInstance("SHA-256")
            .digest(accessToken.getBytes(UTF_8)));
    String claims = String.format(
        "{\"htm\":\"%s\",\"htu\":\"%s\",\"ath\":\"%s\",\"jti\":\"%s\",\"iat\":%d,\"exp\":%d}",
        htm, htu, ath, UUID.randomUUID().toString().replace("-", ""), now, now + 60);
    String input = hdr + "." + b64u(claims.getBytes(UTF_8));
    // The P1363 variant emits raw r||s; plain SHA256withECDSA would emit DER.
    Signature s = Signature.getInstance("SHA256withECDSAinP1363Format");
    s.initSign(key);
    s.update(input.getBytes(UTF_8));
    return input + "." + b64u(s.sign());
}
// .header("DPoP", dpopProof(key, "POST", url, accessToken))

<?php
// openssl_pkey_new(['curve_name' => 'prime256v1', 'private_key_type' => OPENSSL_KEYTYPE_EC])
// once per install, then persist the PEM outside the web root.

function b64u(string $b): string { return rtrim(strtr(base64_encode($b), '+/', '-_'), '='); }

// dpopPublicJwk is a JSON STRING in the activate body.
function publicJwk($key): string {
    $d = openssl_pkey_get_details($key);
    return json_encode([
        'kty' => 'EC', 'crv' => 'P-256',
        'x' => b64u(str_pad($d['ec']['x'], 32, "\0", STR_PAD_LEFT)),
        'y' => b64u(str_pad($d['ec']['y'], 32, "\0", STR_PAD_LEFT)),
    ]);
}

// On /v1/sess/refresh pass the refresh token here: ath covers the token the call presents.
function dpopProof($key, string $htm, string $htu, string $accessToken): string {
    $now = time();
    $hdr = b64u(json_encode(['alg' => 'ES256', 'typ' => 'dpop+jwt']));
    $claims = b64u(json_encode([
        'htm' => $htm, 'htu' => $htu,
        'ath' => b64u(hash('sha256', $accessToken, true)),
        'jti' => bin2hex(random_bytes(16)),  // single use; the server remembers it
        'iat' => $now, 'exp' => $now + 60,   // a window over 120s is refused
    ]));
    $input = $hdr . '.' . $claims;
    openssl_sign($input, $der, $key, OPENSSL_ALGO_SHA256);
    // openssl emits DER; JOSE needs raw r||s, so unwrap the ASN.1 sequence.
    return $input . '.' . b64u(p1363FromDer($der));
}
// CURLOPT_HTTPHEADER => ['DPoP: ' . dpopProof($key, 'POST', $url, $accessToken)]

import CryptoKit
import Foundation

func b64u(_ d: Data) -> String {
    d.base64EncodedString().replacingOccurrences(of: "+", with: "-")
     .replacingOccurrences(of: "/", with: "_").replacingOccurrences(of: "=", with: "")
}

// P256.Signing.PrivateKey() once per install, stored in the Keychain.
func publicJwk(_ key: P256.Signing.PrivateKey) -> String {
    let raw = key.publicKey.rawRepresentation   // x || y, 32 bytes each
    // dpopPublicJwk is a JSON STRING in the activate body.
    return "{\"kty\":\"EC\",\"crv\":\"P-256\",\"x\":\"\(b64u(raw.prefix(32)))\",\"y\":\"\(b64u(raw.suffix(32)))\"}"
}

// On /v1/sess/refresh pass the refresh token here: ath covers the token the call presents.
func dpopProof(_ key: P256.Signing.PrivateKey, htm: String, htu: String,
               accessToken: String) throws -> String {
    let now = Int(Date().timeIntervalSince1970)
    let hdr = b64u(Data(#"{"alg":"ES256","typ":"dpop+jwt"}"#.utf8))
    let ath = b64u(Data(SHA256.hash(data: Data(accessToken.utf8))))
    let jti = UUID().uuidString.replacingOccurrences(of: "-", with: "")
    // exp - iat over 120s is refused; jti is single use.
    let claims = #"{"htm":"#(htm)","htu":"#(htu)","ath":"#(ath)","jti":"#(jti)","iat":#(now),"exp":#(now + 60)}"#
    let input = hdr + "." + b64u(Data(claims.utf8))
    let sig = try key.signature(for: Data(input.utf8))
    // rawRepresentation is r||s, which is what JOSE expects.
    return input + "." + b64u(sig.rawRepresentation)
}
// req.setValue(proof, forHTTPHeaderField: "DPoP")

// KeyPairGenerator.getInstance("EC") with "secp256r1", generated once and kept
// in the Android Keystore.

fun b64u(b: ByteArray): String = Base64.getUrlEncoder().withoutPadding().encodeToString(b)

// dpopPublicJwk is a JSON STRING in the activate body.
fun publicJwk(pub: ECPublicKey): String {
    val x = b64u(toFixed32(pub.w.affineX))
    val y = b64u(toFixed32(pub.w.affineY))
    return """{"kty":"EC","crv":"P-256","x":"$x","y":"$y"}"""
}

// On /v1/sess/refresh pass the refresh token here: ath covers the token the call presents.
fun dpopProof(key: PrivateKey, htm: String, htu: String, accessToken: String): String {
    val now = Instant.now().epochSecond
    val hdr = b64u("""{"alg":"ES256","typ":"dpop+jwt"}""".toByteArray())
    val ath = b64u(MessageDigest.getInstance("SHA-256").digest(accessToken.toByteArray()))
    val jti = UUID.randomUUID().toString().replace("-", "")
    // exp - iat over 120s is refused; jti is single use.
    val exp = now + 60
    val claims = """{"htm":"$htm","htu":"$htu","ath":"$ath","jti":"$jti","iat":$now,"exp":$exp}"""
    val input = hdr + "." + b64u(claims.toByteArray())
    // The P1363 name emits raw r||s; plain SHA256withECDSA would emit DER.
    val s = Signature.getInstance("SHA256withECDSAinP1363Format")
    s.initSign(key)
    s.update(input.toByteArray())
    return input + "." + b64u(s.sign())
}
// .header("DPoP", dpopProof(key, "POST", url, accessToken))

require "openssl"
require "json"
require "securerandom"
require "base64"

def b64u(b) = Base64.urlsafe_encode64(b, padding: false)

# OpenSSL::PKey::EC.generate("prime256v1") once per install, then persist it.
def public_jwk(key)
  pt = key.public_key.to_bn.to_s(2)   # 0x04 || x || y
  # dpopPublicJwk is a JSON STRING in the activate body.
  JSON.generate({ kty: "EC", crv: "P-256",
                  x: b64u(pt[1, 32]), y: b64u(pt[33, 32]) })
end

# On /v1/sess/refresh pass the refresh token here: ath covers the token the call presents.
def dpop_proof(key, htm, htu, access_token)
  now = Time.now.to_i
  hdr = b64u(JSON.generate({ alg: "ES256", typ: "dpop+jwt" }))
  claims = b64u(JSON.generate({
    htm: htm, htu: htu,
    ath: b64u(OpenSSL::Digest::SHA256.digest(access_token)),
    jti: SecureRandom.hex(16),   # single use; the server remembers it
    iat: now, exp: now + 60,     # a window over 120s is refused
  }))
  input = "#{hdr}.#{claims}"
  der = key.sign(OpenSSL::Digest.new("SHA256"), input)
  # OpenSSL emits DER; JOSE needs raw r||s, so unwrap the ASN.1 sequence.
  r, s = OpenSSL::ASN1.decode(der).value.map { _1.value }
  raw = [r.to_s(16).rjust(64, "0"), s.to_s(16).rjust(64, "0")].join
  "#{input}.#{b64u([raw].pack("H*"))}"
end
# req["DPoP"] = dpop_proof(key, "POST", url, access_token)