DOKO

Distributed Ownership & Key Object

The self-sovereign identity certificate for YAKMESH nodes. Your passport in the mesh.

v3.5.10

Overview

A DOKO is a cryptographically signed identity document that proves who you are in the Yakmesh network. Unlike traditional certificates issued by a central authority, a DOKO is self-issued and verified by the mesh through mathematical proofs.

DOKO Types

node-identity
Core node identity — proves a node's existence and public key
domain-claim
Domain ownership — proves a node controls a domain
service-binding
Service binding — links services to node identity

DOKO Structure

Every DOKO contains these core fields, signed with ML-DSA-65 (post-quantum): 

{
  // Version & Type
  "version": "1.0",
  "type": "node-identity",  // or "domain-claim", "service-binding"
  
  // Core Identity
  "nodeId": "node-mobius-rabi-junction-a7f3b2c1",
  "publicKey": "ML-DSA-65 public key (hex)",
  
  // Network Binding
  "networkName": "mobius-rabi-junction",  // From codebase hash
  
  // Temporal
  "issuedAt": 1737200000000,   // Unix timestamp
  "expiresAt": 1768736000000,  // 1 year validity
  
  // Optional Extensions
  "domains": [
    {
      "domain": "example.com",
      "proof": "/.well-known/yakmesh/domain-proof.json",
      "verifiedAt": 1737200000000,
      "quorumNodes": ["node-xxx", "node-yyy", "node-zzz"]
    }
  ],
  
  // TLS Binding (optional, for mTLS)
  "tls": {
    "certFingerprint": "sha256:a1b2c3...",
    "validFrom": 1737200000000,
    "validTo": 1768736000000
  },
  
  // Signature (covers all above fields)
  "signature": "ML-DSA-65 signature (hex)"
}

Creating a DOKO

import { DOKOGenerator, DOKODocument, DOKO_TYPES } from 'yakmesh/security/doko-identity';

// Generate a node identity DOKO — generates an ML-DSA-65 keypair,
// self-signs, and binds the 162T persistent machine identity
const { doko, publicKeyHex, secretKeyHex } = DOKOGenerator.generateNode({
  persistentId: myPersistentId,        // required — survives code upgrades
  nodeId: myNodeId,
  networkName: config.networkName,
  claims: { operator: 'example.org' },
});

console.log('DOKO created:', doko.dokoId);
console.log('Expires:', new Date(doko.expires));
console.log('Extensions:', doko.extensions.persistentId);

// Or build a DOKO on an existing keypair:
// DOKOGenerator.fromKeyPair(publicKey, secretKey, { type: DOKO_TYPES.USER, ... })

Domain Claims

To prove you control a domain, you must pass mesh-based domain verification. This is a quorum-based process that requires multiple independent nodes to verify your claim.

Verification Process

  1. 1 Place a proof file at /.well-known/yakmesh/domain-proof.json
  2. 2 Request domain verification from the mesh
  3. 3 Random verifiers (5+ nodes) check your proof file
  4. 4 Quorum (≥3 agreeing) adds domain to your DOKO

Domain Proof File

// /.well-known/yakmesh/domain-proof.json
{
  "nodeId": "node-mobius-rabi-junction-a7f3b2c1",
  "domain": "example.com",
  "challenge": "random-challenge-from-mesh",
  "timestamp": 1737200000000,
  "signature": "ML-DSA-65 signature of above fields"
}

Trust Levels

DOKOs are assigned trust levels based on their verification state:

DOKO trust levels use the KARMA tier system — Nepali expedition team roles:

SIRDAR (सिरदार) — Expedition Leader
Atomic time + hardware attestation + 30 days + endorsements
SATHI (साथी) — Trusted Companion
GPS + hardware + 14 days + endorsements
PATHIK (पथिक) — Traveler on Path
PTP time + hardware + 7 days presence
YATRI (यात्री) — Pilgrim
NTP time + hardware + 1 day presence
NAYA (नया) — Newcomer
Observer status, building trust

DOKO Hash

Each DOKO has a unique hash that can be used for pinning and verification: 

import { DOKODocument } from 'yakmesh/security/doko-identity';

// dokoId is derived from the public key + DOKO type at creation
const dokoId = DOKODocument.computeDokoId(publicKeyBytes, DOKO_TYPES.NODE);
// Deterministic: same key + type → same dokoId

// The signed payload covers:
// - type, dokoId, publicKey, created, expires, claims, extensions
// - (signature itself is excluded)

DOKO Expiration & Renewal

  • • Default validity: 1 year from issuance
  • • Renewal window: 30 days before expiration
  • • Auto-renewal: Node can re-sign with same key
  • • Key rotation: New DOKO with new key pair

Security Considerations

Identity Protection with iO

Unlike raw cryptocurrency private keys, YAKMESH uses iO — deterministic identity obfuscation (a SHA3-256-to-wordlist derivation, not cryptographic iO) to derive human-readable identities from cryptographic material. Your identity is never a raw hash.

  • • Network Names: qubit-lattice-prism (not 7f3a9b2c...)
  • • Node IDs: pq-EqU8 (human-memorable)
  • • Verification Phrases: Three-word sequences for identity confirmation
import { deriveNetworkName, deriveNetworkId } from './oracle/network-identity.js';

// Never expose raw hashes — always use iO derivation
const name = deriveNetworkName(hash, 3);  // "factor-primitive-bose"
const id = deriveNetworkId(hash);         // "pq-EqU8"

"We learned from Bitcoin's mistakes. Human-readable identities that protect the underlying keys."

Key Storage Best Practices

  • • Your node-key.json contains encrypted key material — back it up securely
  • • Consider hardware security modules (HSM) for production deployments
  • • If compromised, revoke immediately via mesh broadcast using your backup key
  • • Key rotation: Generate a new DOKO and announce the transition to the mesh

Provenance full version history →

Introduced in v2.0.0 — DOKO identity documents (with NAMCHE gateway).

  • v2.2.0 — DOKO revocation + domain transfers

Continue the Journey

← Previous
NAMCHE

Identity gateway
Next →
SHERPA

Peer discovery