handshake_challenge

Category: auth
Access: write
Audience: internal (ordinary users do not normally call this directly)

Purpose

Begins a hybrid session handshake and returns a one-time challenge with the server's ephemeral key material. Spoke machinery only; completion must run on the same connection.

Arguments

Required: ref_kind, ref_id.

Optional: client_instance_id, client_kind, client_name, client_version, transport, user_agent.

ref_kind. Note: One of bootstrap, ticket.
ref_id. Note: Shape-checked only here; validity is never decided until complete, so refs cannot be probed.
client_instance_id. Note: Optional client metadata stored with the challenge slot; never authority.
client_kind. Note: Optional session kind (client or spoke), bound into the session row at complete; absent means legacy direct. Invalid values fail the challenge.
client_name. Note: Optional client metadata stored with the challenge slot; never authority.
client_version. Note: Optional client metadata stored with the challenge slot; never authority.
transport. Note: Optional client metadata stored with the challenge slot; never authority.
user_agent. Note: Optional client metadata stored with the challenge slot; never authority.

Result

Object with challenge_id, server_ecdh and server_kem public material, suite, and expires_in seconds.

Boundaries

Pre-authentication call on the same connection that must later complete. Challenge slots are single-process, bounded (64), and expire after 300 seconds. Ordinary users never call this directly; spokes do.

Lifecycle / side effects

Holds one single-use challenge with fresh ephemeral P-256 plus ML-KEM-768 public material. The slot is consumed by exactly one complete attempt, success or failure.

Errors

Bad ref shape, invalid client kind, overlong metadata, or a full challenge heap deny generically as a normal handshake failed payload. No failure leaks whether a ref exists.

Example

{
  "ref_id": "<uuid>",
  "ref_kind": "ticket"
}

Result shape:

{
  "challenge_id": "<uuid>",
  "expires_in": 300,
  "server_ecdh": "<b64u>",
  "server_kem": "<b64u>",
  "suite": "HYBRID{P-256,ML-KEM-768}+HKDF-SHA512+A256GCM"
}