Module handshake 

Core handshake logic for the OpenAgent Core Protocol identity flow.

Implements the normative rules from the Core Protocol Specification: nonce shape (Section 7), challenge construction (Sections 4 / 15.2), the JCS signing payload (Section 5), and proof validation (Section 15.3). The specification is the authority; this module is its implementation.

Constants

AUTH_ENDPOINT_PATH

Well-known path for the auth endpoint.

DEFAULT_CHALLENGE_TTL_SECS

Default challenge TTL in seconds (Section 7: default 30s, max 300s).

DEFAULT_SESSION_TTL_SECS

Default session TTL in seconds (5 minutes).

MAX_CHALLENGE_TTL_SECS

Maximum challenge TTL in seconds (Section 7).

PROVE_ENDPOINT_PATH

Well-known path for the prove endpoint.

WELL_KNOWN_PATH

Well-known path for discovery.

Functions

canonical_challenge_bytes

The signing payload for an IdentityProof: the JCS-canonicalized (RFC 8785) UTF-8 bytes of the challenge object, with no framing, prefix, or envelope (Section 5 / Section 15.2).

generate_nonce

Generate a nonce per Section 7: 32 CSPRNG bytes as 64 lowercase hex chars.

new_challenge

Construct a fresh IdentityChallenge for origin, stamping the current UTC time in the Section 4 format (Z suffix, seconds precision).

validate_challenge

Validate an IdentityChallenge against the Section 4 field constraints.

validate_nonce

The nonce field: exactly 64 lowercase hex characters (Section 7).

validate_origin

The origin field: scheme://host[:port] per RFC 6454 (Section 4.2).

validate_proof_shape

Validate an IdentityProof against a challenge (Section 15.3): the echoed nonce must match, and the key shape must match the declared scheme. Signature verification itself belongs to the verifier, which knows the trusted key set.

validate_timestamp

The timestamp field: ISO 8601 UTC with Z suffix and seconds precision (Section 4.2). Fractional seconds and numeric offsets are rejected.