The session id
A SHA-256 hash over the first two messages, exactly as sent. A CONFIRM over other messages is refused as a downgrade.
kya-handshake/0.1: before two agents work together, both prove who they are, who they act for and what they may do, in three signed messages. Part of the Zuger Agent Protocol (ZAP). Built on open standards.
THE THREE MESSAGES
Each message is a JWS signed with the sender’s agent key, carried in an HTTP message signed with the same key.
Who the initiator is, its credential with only the disclosures the responder asks for, who it acts for, what it wants to do and the versions it speaks. A fresh nonce.
To the responder
The responder’s own credential and nonce, and its decision: accept, refuse with a code, or wait for a person’s approval. If it accepts, its terms and the version chosen.
To the initiator
The initiator echoes the responder’s nonce and signs a hash of the first two messages. That hash is the session’s id.
To the responder
THE SESSION
A SHA-256 hash over the first two messages, exactly as sent. A CONFIRM over other messages is refused as a downgrade.
From the responder’s answer, fifteen minutes at most, and ending early if either credential expires.
Each carries the session id in a signed header. A revocation is seen at the next handshake, which is why sessions are short.
TRANSPORTS
| Transport | How | Status |
|---|---|---|
| HTTPS | HELLO and CONFIRM are POST requests to the responder’s handshake endpoint; HELLO-BACK is the signed response. Every signature lives 60 seconds at most. | Draft |
| A2A | An agent card names the handshake as an extension, and the handshake runs over HTTPS before the A2A calls. | Draft |
| MCP | Not this handshake. MCP sessions follow KYA-OS instead. | Planned |
# ① HELLO, as it travels over HTTPS
POST /handshake HTTP/1.1
Content-Type: application/jwt
Content-Digest: sha-256=:…:
Signature-Input: kya=("@method" "@target-uri" "@authority" "content-digest");created=…;expires=…;nonce="<nonce_a>";keyid="…";alg="ed25519";tag="kya/v0.1"
Signature: kya=:…:
<compact JWS, typ kya-hs-hello+jwt>RESULT CODES
Checks run in a fixed order, and the first failure is the answer.
| Code | Meaning |
|---|---|
HS_OK | Every check passed. |
HS_UNTRUSTED_ISSUER | The credential’s issuer is not on the local trust list, or not at that assurance. |
HS_BAD_SIGNATURE | The issuer’s signature, or the disclosures, do not verify. |
HS_EXPIRED | The credential, or the session, has expired. |
HS_REVOKED | The credential is revoked, or its status cannot be read. |
HS_NOT_LOGGED | No valid inclusion proof in the public log. |
HS_KEY_MISMATCH | A message or its signature is not made by the credential’s key. |
HS_REPLAY | Not fresh: a nonce used before, or a time outside the window. |
HS_LOW_ASSURANCE | Assurance below the policy’s minimum, or a required disclosure missing. |
HS_OUT_OF_SCOPE | The scopes asked for are not covered, or the chain of who acts for whom is too deep. |
HS_LOW_REPUTATION | Reputation below the policy’s minimum. |
HS_BLOCKED | The operator or agent is blocked, or the skill is not offered. |
HS_NEEDS_APPROVAL | The value is above the threshold: a person decides. |
HS_TIMEOUT | A wait for a person’s approval passed its time limit. |
HS_CHANNEL_MISMATCH | The binding in the application failed. It is not a TLS result. |
HS_DOWNGRADE | A lower version than both sides offer, or a transcript over other messages. |
HS_BAD_ALG | An algorithm not on the allow list. |
HS_FROZEN | The agent is frozen. |
HS_MALFORMED | The input fails before any cryptography: its shape, its size or its version. |
CONFORMANCE CHECKLIST
WHAT IT PROVES
Each side holds its credential’s key, freshly, over a nonce the other side chose, for this address, inside this exchange. A message cannot be moved to another exchange or peer without failing.
That the exchange ran over a particular TLS connection: a party that ends TLS for one side can relay messages unchanged. Nor that an agent behaves well.
A formal model of these claims. An outside specialist will build it before the handshake is public.
CODE AND VECTORS
The handshake ships in the SDKs. They are not published yet.
Coming soonA case for every result code, made deterministically. They will be published with the specification.
Coming soonThe five layers, the specifications and what passes its tests.
Developer docsStandardsLog in to pick up where the agents left off
By continuing you agree to our Terms & Privacy Policy
Don’t have an account? Create account
Free to start · No card
By continuing you agree to our Terms & Privacy Policy
Already have an account? Log in
If has an account, six digits are on their way. They work once, for ten minutes.
New to Zuger? Create account · Use another address
If can be used, a link is on its way.
Open it on the device you want to sign in with — your phone, most likely. It works once, expires in a few hours, and can only create a passkey: it cannot read anything or approve anything.