Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

01 — Overview

Crate: kinetic-kid Stage: 3 of 10 Reading time: ~5 minutes Depends on: kinetic-types, kinetic-verify

What Is This?

kinetic-kid handles Kinetic Identity Documents (KIDs). It provides the self-sovereign identity layer for the network. In the Kinetic ecosystem, a KID acts as a decentralized identifier (DID) anchored to the .kin network. This crate defines exactly how these identities are created, signed, cryptographically verified, and extended using capability manifests.

Why Kinetic Needs This

Important

In a decentralized network, there is no central database of users. Without this crate, there would be no way to securely prove who owns a specific .kin name or what their keys are authorized to do. By using ML-DSA-65 post-quantum signatures and RFC 8785 JSON Canonicalization, kinetic-kid guarantees that identities are cryptographically tamper-proof across the network.

How It Works

The crate exposes the core types required for identity management. The main entry point is lib.rs (208 lines), which publicly exports the modules.

  • It heavily leverages the JCS (JSON Canonicalization Scheme) to ensure that the byte representation of an identity document is exactly identical across all platforms (Windows, Linux, WASM in browser) before it gets signed.
  • It provides a robust, bounded parsing mechanism to defend against malicious peers sending massive payloads.

Key Pieces (Topic File Breakdown)

This crate is composed of ~981 total lines of code, broken down into the following topics:

  1. 02_document.md — Covers KidDocument and ControllerKey. This is the root identity document structure and signature verification logic.
  2. 03_manifest.md — Covers CapabilityManifest and ServiceEntry. Explains how identities advertise web endpoints securely.
  3. 04_error.md — Covers KidError. The robust 16-variant error taxonomy for the identity layer.
  4. 05_did.md — Covers KineticDid. The strict parsing logic for did:kin:<hash> identifiers.
  5. 06_bounded.md — Covers OOM defense mechanisms (BoundedVecVisitor) to stop network memory-bomb attacks.

How This Connects to the Rest of Kinetic

  • CROSS-CRATE: Relies heavily on the ML-DSA-65 algorithms and structures from kinetic-types and kinetic-verify.
  • FORWARD DEPENDENCY: The DHT/P2P network (kinetic-network) and the database layer (kinetic-storage) will ingest these structs. Specifically, they rely on KidDocument::is_authorized_update to manage key rotations securely across the network.

Quick Reference

  • Total Lines: ~981
  • Signature Algorithm: ML-DSA-65 (Post-Quantum)
  • Canonicalization: JCS (RFC 8785)
  • Bounds: Max 20 controller keys, max 50 services.

Open Questions / Things to Revisit

Warning

The tests module inside lib.rs contains hardcoded key generation for MlDsa65. In a production environment, test fixtures should ideally be isolated to prevent testing dependencies from bleeding into the compiled WASM binary.