Request Signing

Documentation Index

Fetch the complete documentation index at: https://docs.synheart.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Public API

signRequest(
  appId: String,
  method: String,
  path: String,
  bodyBytes: ByteArray,
) -> SignedHeaders

​

Message construction (normative)

method          = uppercase HTTP method, ASCII   (e.g. "POST")
path            = request path, ASCII             (e.g. "/ingest/v1/hsi")
                  no query string
timestamp_str   = Unix seconds, ASCII decimal     (e.g. "1709312345")
raw_body_bytes  = exact HTTP request body bytes on the wire
                  (empty bytes for GET / no body)

message = method || "\n" || path || "\n" || timestamp_str || "\n" || raw_body_bytes
signature = ECDSA-P256-SIGN(private_key, SHA256(message))

​

Six required headers

​

Nonce policy

• UUID v4. Generated fresh per request; never reused across requests for the same (app_id, device_id).
• Server enforces replay protection on write endpoints (POST, PUT, PATCH, DELETE) within the 300-second freshness window.
• Replay protection is RECOMMENDED for read endpoints.
• Server stores nonces with a 300-second TTL keyed by (device_id, nonce).

​

Timestamp policy

• Server-side freshness window: 300 seconds.
• SDK clock may drift; correctClockSkew(serverTimestamp) learns an offset from CLOCK_SKEW errors and applies it on subsequent signs.
• The SDK persists clock_offset_ms in local storage.

​

Server-side verification (RFC §8.4)

1. Extract the six headers; reject if any required header is missing.
2. Reject if abs(server_time - X-Synheart-Timestamp) > 300.
3. For write endpoints, reject if (device_id, nonce) has been seen in the freshness window.
4. Reconstruct the message: method + "\n" + path + "\n" + timestamp + "\n" + body_bytes.
5. Look up the public key by (app_id, device_id).
6. Verify ECDSA P-256 signature over SHA256(message).
7. Store the nonce with a 300-second TTL (write endpoints).

​

SignedHeaders type

class SignedHeaders {
  final String appId;
  final String deviceId;
  final String signature;
  final String timestamp;
  final String nonce;
  final String signatureVersion;  // default "1"

  Map<String, String> toMap();
}

​

Sig-Version evolution

• A new SignedHeaders.signatureVersion value emitted by the SDK.
• Server-side support for the new scheme until the previous version is fully retired.
• A capability response telling the SDK to upgrade.

​

Wiring through Synheart Core

1. Core constructs a DeviceAuthProvider over SynheartAuth.
2. Core registers the auth provider’s crypto callbacks with the Synheart runtime.
3. The runtime’s request-signing path builds X-Synheart-Proof (a compact JWS bound to the request URL+method) for HSI ingest. This is a different header from X-Synheart-Signature — both are hardware-backed by the same ECDSA P-256 key but cover different surfaces.
4. For non-runtime traffic, hosts call SynheartAuth.signRequest(...) directly and attach the six headers themselves.

​

What is not signed

• Query string components (signing is over path only). Servers that include sensitive parameters in query strings are responsible for separate validation.
• Headers other than the six listed above. The body and the path/method are the only signed surface.

​

Logging policy

​

Related

• Registration — how the public key reaches the server.
• Errors — CLOCK_SKEW, NONCE_REPLAY, KEY_INVALIDATED recovery.
• Cloud Protocol — X-Synheart-Proof for HSI ingest.