Request Signing

openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out private-key.pem

openssl rsa -in private-key.pem -pubout -out public-key.pem

Content-Digest: sha-256=:rNFh5H4dKqPKimxTAAh5HGIXB7cKBUuisVyMk/LC4eA=:
Signature-Input: sig=("@method" "@path" "@query" "content-digest");created=1757337600;alg="rsa-v1_5-sha256";nonce="3f0c9a4e-7b1d-4c8e-9f2a-5d6b8c1e0a47"
Signature: sig=:<base64 signature>:

"@method": POST
"@path": /suppliers/v1/suppliers
"@query": ?
"content-digest": sha-256=:rNFh5H4dKqPKimxTAAh5HGIXB7cKBUuisVyMk/LC4eA=:
"@signature-params": ("@method" "@path" "@query" "content-digest");created=1757337600;alg="rsa-v1_5-sha256";nonce="3f0c9a4e-7b1d-4c8e-9f2a-5d6b8c1e0a47"

import { createHash, createSign, randomUUID } from "node:crypto";

// The private key comes from your vault at runtime.
const PRIVATE_KEY = process.env.CS_SIGNATURE_PRIVATE_KEY!;
const BASE_URL = process.env.CS_BASE_URL!; // https://api-sandbox.contasimples.com
const USER_AGENT = "my-app/1.0";

type SignedRequest = {
  method: string;
  target: string; // path with the query, already encoded, as it goes in the URL
  token: string;
  payload?: unknown;
};

export async function signedRequest({
  method,
  target,
  token,
  payload
}: SignedRequest): Promise<Response> {
  // Serialize only once. The digest and the request use the same string.
  const body = payload === undefined ? "" : JSON.stringify(payload);

  return fetch(`${BASE_URL}${target}`, {
    method,
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
      "User-Agent": USER_AGENT,
      ...signatureHeaders(method, target, body)
    },
    // With no body, send undefined. Sending "" changes what the server receives.
    body: body || undefined
  });
}

function signatureHeaders(method: string, target: string, body: string): Record<string, string> {
  const queryStart = target.indexOf("?");
  const path = queryStart === -1 ? target : target.slice(0, queryStart);
  const query = queryStart === -1 ? "?" : target.slice(queryStart);

  const components = ['"@method"', '"@path"', '"@query"'];
  const lines = [`"@method": ${method.toUpperCase()}`, `"@path": ${path}`, `"@query": ${query}`];
  const headers: Record<string, string> = {};

  if (body) {
    headers["Content-Digest"] = `sha-256=:${createHash("sha256").update(body, "utf8").digest("base64")}:`;
    components.push('"content-digest"');
    lines.push(`"content-digest": ${headers["Content-Digest"]}`);
  }

  const created = Math.floor(Date.now() / 1000);
  const params = `(${components.join(" ")});created=${created};alg="rsa-v1_5-sha256";nonce="${randomUUID()}"`;
  lines.push(`"@signature-params": ${params}`);

  const signature = createSign("RSA-SHA256")
    .update(lines.join("
"), "utf8")
    .sign(PRIVATE_KEY, "base64");

  headers["Signature-Input"] = `sig=${params}`;
  headers["Signature"] = `sig=:${signature}:`;
  return headers;
}

// Write with a body.
await signedRequest({
  method: "POST",
  target: "/suppliers/v1/suppliers",
  token: accessToken,
  payload: { name: "Example Supplier", document: "00000000000191" }
});

// Reads are signed too. The query is built once and used in the signed path.
const query = new URLSearchParams({ startDate: "2025-01-01", endDate: "2025-01-31" });

await signedRequest({
  method: "GET",
  target: `/statements/v1/banking?${query}`,
  token: accessToken
});

TOKEN="${CS_ACCESS_TOKEN}"
BASE_URL="https://api-sandbox.contasimples.com"
METHOD="POST"
TARGET_PATH="/suppliers/v1/suppliers"
QUERY="?"
BODY='{"name":"Example Supplier","document":"00000000000191"}'
CREATED=$(date +%s)
NONCE=$(uuidgen | tr '[:upper:]' '[:lower:]')

# printf and not echo, because echo appends 
 and the digest does not match.
DIGEST="sha-256=:$(printf '%s' "$BODY" | openssl dgst -sha256 -binary | openssl base64 -A):"
PARAMS="("@method" "@path" "@query" "content-digest");created=${CREATED};alg="rsa-v1_5-sha256";nonce="${NONCE}""

# -A keeps the base64 on one line. With line breaks, the header is rejected before it reaches the API.
SIGNATURE=$(printf '"@method": %s
"@path": %s
"@query": %s
"content-digest": %s
"@signature-params": %s' \
    "$METHOD" "$TARGET_PATH" "$QUERY" "$DIGEST" "$PARAMS" \
  | openssl dgst -sha256 -sign private-key.pem \
  | openssl base64 -A)

# --data-binary and not -d, because -d removes the line breaks from the body.
curl -X "$METHOD" "${BASE_URL}${TARGET_PATH}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Digest: ${DIGEST}" \
  -H "Signature-Input: sig=${PARAMS}" \
  -H "Signature: sig=:${SIGNATURE}:" \
  --data-binary "$BODY"

TARGET_PATH="/statements/v1/banking"
QUERY="?startDate=2025-01-01&endDate=2025-01-31"
CREATED=$(date +%s)
NONCE=$(uuidgen | tr '[:upper:]' '[:lower:]')
PARAMS="("@method" "@path" "@query");created=${CREATED};alg="rsa-v1_5-sha256";nonce="${NONCE}""

SIGNATURE=$(printf '"@method": GET
"@path": %s
"@query": %s
"@signature-params": %s' \
    "$TARGET_PATH" "$QUERY" "$PARAMS" \
  | openssl dgst -sha256 -sign private-key.pem \
  | openssl base64 -A)

curl -X GET "${BASE_URL}${TARGET_PATH}${QUERY}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "User-Agent: my-app/1.0" \
  -H "Signature-Input: sig=${PARAMS}" \
  -H "Signature: sig=:${SIGNATURE}:"

printf '"@method": %s
"@path": %s
"@query": %s
"content-digest": %s
"@signature-params": %s' \
  "$METHOD" "$TARGET_PATH" "$QUERY" "$DIGEST" "$PARAMS" > signature-base.txt
printf '%s' "$SIGNATURE" | openssl base64 -d -A > signature.bin

openssl dgst -sha256 -verify public-key.pem -signature signature.bin signature-base.txt
# Verified OK