Compatibility & Legacy
The legacy 1.x surfaces KYA-OS still read-accepts, and how to adopt the protocol in phases alongside OAuth and existing identity systems.
Compatibility & Legacy
Key Takeaways
- The 1.x line carries two coexisting profiles: the legacy session-bound profile and the self-contained per-request profile - Every legacy wire identifier below is still read-accepted; producers emit the canonical forms - Adoption is phased: proofs first, then delegation, then the card-era surfaces
- KYA-OS layers onto OAuth/OIDC rather than replacing it
KYA-OS evolved inside one major version, so the ratified v1 keeps reading every wire identifier earlier 1.x releases emitted. This page is the inventory of those legacy surfaces — exactly what is still accepted, how the SSOT labels each one, and what to emit today.
The legacy session profile
Early 1.x releases established an optional, time-bounded session via a handshake tool before issuing proofs. The ratified v1 model needs no session: every request carries its own self-contained proof. The session profile is retained unchanged for the 1.x line as an application-layer convenience, and is expected to be deprecated at 2.0 in favour of the self-contained profile.
| Legacy surface | Status in the SSOT |
|---|---|
_kyaos / _kyaos_handshake tools | The session profile's protocol tools. withKyaOs still registers _kyaos by default (handshakeExposure: "tool"); pass handshakeExposure: "none" to omit it. Outside the org.kya-os/decentralized-authority extension surface. |
_kyaos_delegation, _kyaos_proof, _kyaos_approvals arguments | The reserved _kyaos* control-argument namespace; stripped before tool handlers run. |
@kya-os/mcp/session subpath | The session manager behind the legacy profile (nonce handshake, session TTL, replay prevention). Still exported. |
| Legacy error codes | handshake_failed, session_expired, delegation_invalid, insufficient_scope, delegation_revoked, invalid_proof, did_not_found — retained for the session-bound path. |
Legacy proof carriers (read-accepted)
Proofs ride reverse-DNS keys in MCP _meta. The carrier keys were renamed to role-named forms during 1.x; verifiers MUST still accept the prior keys for one major version, and the newest canonical form wins when several are present.
| Carrier | Canonical (emit this) | Legacy (still read-accepted) |
|---|---|---|
| Response proof | _meta["org.kya-os/response-proof"] | org.kya-os/proof (1.1 era), bare proof (pre-1.1) |
| Per-request proof | _meta["org.kya-os/request-proof"] with profile id org.kya-os/proof.v1 in the object's prf field | org.kya-os/proof@1 — the earlier draft used this one string as both the carrier key and the prf profile id |
The two proof eras coexist on one server, each under its own key: the legacy session-bound ProofMeta (with sessionId + handshake nonce) and the self-contained org.kya-os/proof.v1.
Distinct keys mean neither verifier ever sees — or rejects — the other's proof.
Legacy discovery filename
The discovery document schema ships as well-known-mcpi.json — the filename keeps the project's pre-rename "MCP-I" name and is importable as @kya-os/mcp/schemas/well-known-mcpi.json.
The endpoint it describes is served at /.well-known/mcp (no .json suffix).
StatusList2021 read-compatibility
Legacy-era (VC 1.0) delegation credentials revoke via W3C StatusList2021; the card era uses its successor, Bitstring Status List v1.0.
Both tracks remain verified on the 1.x line — revocation status is evaluated on every verification, never cached as part of a verdict.
CheqdStatusListResolver (@kya-os/mcp/cheqd) performs on-chain StatusList2021 checks against a cheqd DID-Linked Resource, verifying the status list itself against the issuer's on-chain DID document, fail-closed on every unprovable path.
One migration hazard
Status lists persisted by releases before 1.9.0 are encoded LSB-first and are silently misread by current MSB-first readers — a revoked credential can read as live. Regenerate persisted status lists when upgrading across 1.9.0.
Phased adoption
KYA-OS is additive: an unaware peer ignores the KYA-OS layer entirely, so you can adopt it in phases without breaking existing clients.
| Phase | Action |
|---|---|
| Step 1 | Wrap your MCP server with withKyaOs — every tool response gains a signed proof; nothing else changes |
| Step 2 | Protect sensitive tools with wrapWithDelegation — unauthorized calls return a signed needs_authorization challenge instead of executing |
| Step 3 | Issue delegation credentials from your authorization flow — the consent step of the needs_authorization step-up |
| Step 4 | Adopt the card-era surfaces: publish an Entity Card and verify per-request org.kya-os/proof.v1 proofs |
| Step 5 | Add the audit layer for verifiable records of who did what under whose authority |
OAuth and OIDC alongside KYA-OS
KYA-OS does not replace your authorization server; it rides on it.
- Scope mapping — OAuth scopes granted at consent map onto delegation credential scopes; the authorization service issues a
DelegationCredentialwhen the user grants authorization in theneeds_authorizationresume flow (SPEC.md §9.3) - Not a bearer-token model — completing an OAuth flow is never sufficient by itself: the resulting delegation credential is still verified cryptographically on the retried request (SPEC.md §9.4)
- CIMD on-ramp — for OAuth clients, the
client_idmetadata document bindsclient_id ⇄ did:webandjwks_uri ⇄ DID keys, so validating aprivate_key_jwtclient assertion is a DID-key proof; a DPoP-style tokencnf.jktfuses with the per-request proof's sender constraint - Hardening alignment — the profile aligns with the MCP 2026-07-28 OAuth SEPs: issuer validation on the callback, credential-to-issuer binding, and step-up flows that accumulate scope rather than discard it
This is the compatibility story for JWT/OAuth estates: keep issuing tokens where you do today, and let the delegation credential — not the token — carry the authority KYA-OS verifies.