Full Technical Specification v0.1

The HUMAN Passport is the cornerstone of the entire ecosystem.

It is not an app, not a profile, not a login, and not a database.

It is the cryptographic master key to a human life — bound to the person, portable across devices, revocable, selectively revealable, and impossible for any company (including ours) to own or hold hostage.

MVP: PASSPORT-LITE (Foundation Phase, Week 1-2)

See: 15_protocol_foundation_and_build_sequence.md for the canonical build sequence.

Before building the full Passport specification below, we build Passport-Lite — the minimum viable identity layer that enables the Companion and AI Labs API to demonstrate real protocol differentiation from Day 1.

What Passport-Lite Includes

Component	Foundation (Week 1-2)	Full Spec (Wave 2+)
Identity	DID generation (`did:human:<uuid>`)	Full W3C DID methods, resolution
Keys	Ed25519 keypair per user	3-key model (Identity, Signing, Encryption)
Signing	JWT tokens signed with user's key	Full VC signing, selective disclosure
Consent	Simple access log (who accessed what)	Full consent contracts, revocation
Storage	PostgreSQL with encryption at rest	Personal Data Vault, BYOV
Recovery	Admin-assisted recovery	Guardian network, threshold recovery
Device	Web-based (server-side keys)	Secure enclave, device-rooted

Passport-Lite Implementation

// Passport-Lite: Minimum viable identity
interface PassportLite {
  did: string;                    // did:human:<uuid>
  publicKey: string;              // Ed25519 public key (base64)
  privateKey: string;             // Ed25519 private key (encrypted, server-stored for MVP)
  displayName: string;            // Human-readable name
  createdAt: Date;
  consentLog: ConsentEntry[];     // Who accessed what, when
}

interface ConsentEntry {
  accessorDid: string;
  resourceType: string;
  timestamp: Date;
  granted: boolean;
}

// Core operations
async function createPassportLite(displayName: string): Promise<PassportLite>;
async function signWithPassport(passportId: string, payload: any): Promise<SignedPayload>;
async function verifySignature(signature: string, publicKey: string): Promise<boolean>;
async function logConsent(passportId: string, entry: ConsentEntry): Promise<void>;

Why Passport-Lite Matters

Without Passport-Lite:

AI Labs API has no provenance (just claims)
Companion has no identity (just sessions)
No differentiation from Scale.AI

With Passport-Lite:

Every task result is signed by a real identity
Every Companion interaction has a verified user
Cryptographic provenance from Day 1

Passport-Lite is the foundation. The full spec below is the vision.

CRYPTOGRAPHIC ARCHITECTURE

Overview

The Passport identity layer is built on modern cryptographic primitives with a pragmatic evolution path from MVP to production-grade security. This section documents the cryptographic decisions, threat model, and upgrade path.

Key Management Strategy

Component	v0.1 (MVP - Internal)	v0.2 (Month 2-4 - Beta)	v0.3 (Month 4-6 - Production)
Key Storage	Server-stored, KMS-encrypted	AWS CloudHSM (FIPS 140-2 Level 3)	User-controlled (Secure Enclave, Hardware Keys)
Master Key (KEK)	AWS KMS customer-managed key	HSM-protected, multi-party unsealing	User-owned recovery (Shamir 3-of-5)
Key Operations	Decrypt private key on-demand	Sign in HSM (keys never exported)	Sign in Secure Enclave/YubiKey
Key Rotation	Manual (documented procedure)	Automated annual rotation	Per-session + hardware backup
Acceptable For	Internal users (<100, Month 1-3)	Public beta, enterprise pilots	Full production, regulated industries
Not Acceptable For	Public beta, regulated data	N/A	N/A

Cryptographic Primitives

Algorithm Choices (NIST-Approved, Modern Standards):

// Digital signatures
Algorithm: Ed25519 (RFC 8032)
Key Size: 256 bits
Signature Size: 512 bits (64 bytes)
Library: @noble/ed25519 or libsodium (constant-time, audited)
Rationale: Modern, fast, constant-time, no padding oracle attacks

// Symmetric encryption
Algorithm: AES-256-GCM (NIST SP 800-38D)
Key Size: 256 bits
IV Size: 96 bits (12 bytes, randomly generated per encryption)
Auth Tag: 128 bits (16 bytes)
Library: Node.js crypto module (OpenSSL-backed)
Rationale: Authenticated encryption (prevents tampering), FIPS 140-2 approved

// Hashing
Algorithm: SHA-256 (NIST SP 800-57)
Output Size: 256 bits (32 bytes)
Library: Node.js crypto module
Rationale: No known practical attacks, NIST-approved, widely supported

// Key derivation
Algorithm: HKDF (RFC 5869) with SHA-256
Purpose: Derive per-passport keys from master key
Library: @noble/hashes/hkdf
Rationale: Cryptographically sound key derivation, composable

// Password hashing (API keys)
Algorithm: Argon2id
Memory Cost: 64 MB
Time Cost: 3 iterations
Parallelism: 4 threads
Library: argon2 (Node.js binding to C reference impl)
Rationale: Memory-hard (GPU-resistant), winner of Password Hashing Competition

// Transport layer
Protocol: TLS 1.3 (RFC 8446)
Cipher Suites: TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256
Certificate: Let's Encrypt (automated renewal)
HSTS: Enabled (max-age=31536000, includeSubDomains)
Rationale: Modern, removes RSA key exchange vulnerabilities

DID Method Specification

Method Name: did:human
Method Identifier: human
Method-Specific Identifier: UUID v4 (122-bit entropy)

DID Format:

did:human:<uuid>

Example: did:human:550e8400-e29b-41d4-a716-446655440000

Collision Analysis:

UUID v4: 2^122 possible values (5.3 × 10^36)
Birthday paradox: 50% collision probability at 2^61 ≈ 2.3 quintillion DIDs
At 1 billion users: Collision probability ≈ 10^-18 (negligible)
At 10 billion users: Collision probability ≈ 10^-16 (still negligible)
Recommendation: Acceptable for global scale; upgrade to UUIDv7 (time-ordered) in v0.2 for indexing benefits

DID Resolution:

v0.1: Resolve via API: GET /api/v1/passport/:did returns Passport object (not W3C DID Document)
v0.2: Support .well-known/did.json endpoint for standard resolution
v0.3: Publish DID document to distributed ledger (optional verifiability, immutable resolution)

W3C DID Core Compliance:

v0.1: Informal (DID identifier only, not full DID Document)
v0.2: W3C DID Core 1.0 compliant (publish method spec, register with W3C)
v0.3: Full compliance + verifiable data registry (ledger-backed)

Key Wrapping (KEK-DEK Pattern)

To enable key rotation without re-encrypting all data:

// Key hierarchy
Master Key (KEK)
  └── Customer-managed in AWS KMS (FIPS 140-2 Level 3)
  └── Never rotated (rotation requires re-encrypting all DEKs)

Per-Passport Data Encryption Key (DEK)
  └── 256-bit AES key, randomly generated per passport
  └── Wrapped (encrypted) by KEK via KMS
  └── Stored alongside encrypted private key
  └── Rotated independently (only affects single passport)

// Implementation
async function createPassport(userId: string): Promise<PassportLite> {
  // 1. Generate Ed25519 keypair
  const keypair = ed25519.generateKeyPair();
  
  // 2. Generate DEK (data encryption key) for this passport
  const dek = crypto.randomBytes(32); // 256-bit AES key
  
  // 3. Wrap DEK with KMS master key (KEK)
  const { CiphertextBlob: wrappedDek } = await kms.send(new EncryptCommand({
    KeyId: process.env.KMS_MASTER_KEY_ARN,
    Plaintext: dek,
    EncryptionContext: {
      passportId: userId,
      purpose: 'passport-dek',
    },
  }));
  
  // 4. Encrypt private key with DEK
  const iv = crypto.randomBytes(12); // 96-bit IV for AES-GCM
  const cipher = crypto.createCipheriv('aes-256-gcm', dek, iv);
  const encryptedKey = Buffer.concat([
    cipher.update(keypair.privateKey),
    cipher.final(),
  ]);
  const authTag = cipher.getAuthTag();
  
  // 5. Store wrapped DEK + encrypted key (not plaintext DEK or private key)
  await db.passports.create({
    id: userId,
    did: `did:human:${uuidv4()}`,
    publicKey: keypair.publicKey.toString('base64'),
    encryptedPrivateKey: encryptedKey.toString('base64'),
    wrappedDek: Buffer.from(wrappedDek).toString('base64'),
    iv: iv.toString('base64'),
    authTag: authTag.toString('base64'),
    keyVersion: 'v1',
  });
  
  // 6. Zero sensitive data from memory
  dek.fill(0);
  keypair.privateKey.fill(0);
}

// Benefits of KEK-DEK pattern:
// - KEK rotation only requires re-encrypting DEKs (small)
// - Private keys never re-encrypted (large, error-prone)
// - Each passport has independent DEK (blast radius limited)
// - KMS audit logs show which DEKs were unwrapped and when

Key Rotation Strategy

Signing Keys (Passport Keypairs):

interface PassportLite {
  id: string;
  did: string;
  currentKeyId: string;           // "v1", "v2", etc.
  keys: PassportKey[];            // Historical keys for signature verification
  // ...
}

interface PassportKey {
  keyId: string;                  // "v1", "v2", "v1702224000"
  publicKey: string;              // Ed25519 public key
  encryptedPrivateKey: string;    // AES-256-GCM encrypted
  wrappedDek: string;             // KMS-wrapped DEK
  iv: string;
  authTag: string;
  createdAt: Date;
  revokedAt?: Date;               // Null if active
  status: 'active' | 'revoked' | 'expired';
}

// JWT signing includes key identifier
async function signJWT(passportId: string, claims: any): Promise<string> {
  const passport = await db.passports.findOne({ id: passportId });
  const currentKey = passport.keys.find(k => k.keyId === passport.currentKeyId);
  
  const jwt = await new jose.SignJWT(claims)
    .setProtectedHeader({
      alg: 'EdDSA',
      typ: 'JWT',
      kid: `${passport.did}:${currentKey.keyId}`, // Key identifier
    })
    .sign(privateKey);
  
  return jwt;
}

// JWT verification uses kid to find correct historical key
async function verifyJWT(token: string): Promise<any> {
  const { kid } = jose.decodeProtectedHeader(token);
  const [did, keyId] = kid.split(':');
  
  const passport = await db.passports.findOne({ did });
  const key = passport.keys.find(k => k.keyId === keyId);
  
  if (key.status === 'revoked') {
    throw new Error('Signature key has been revoked');
  }
  
  const { payload } = await jose.jwtVerify(token, key.publicKey);
  return payload;
}

// Annual key rotation (automated in v0.2)
async function rotatePassportKey(passportId: string): Promise<void> {
  const newKeyPair = ed25519.generateKeyPair();
  const newKeyId = `v${Math.floor(Date.now() / 1000)}`;
  
  // Encrypt new private key with new DEK
  const { encryptedKey, wrappedDek, iv, authTag } = await encryptPrivateKey(newKeyPair.privateKey);
  
  await db.passports.update(passportId, {
    currentKeyId: newKeyId,
    keys: [
      ...existingKeys, // Keep historical keys for verification
      {
        keyId: newKeyId,
        publicKey: newKeyPair.publicKey.toString('base64'),
        encryptedPrivateKey: encryptedKey,
        wrappedDek,
        iv,
        authTag,
        createdAt: new Date(),
        status: 'active',
      },
    ],
  });
  
  // Old keys remain for signature verification but can't sign new JWTs
}

Rotation Schedule:

Signing Keys: Annual rotation (automated in v0.2) or on-demand (compromise detected)
Session Keys (JWTs): 1 hour expiration (short-lived by design, no rotation needed)
API Keys: 90-day rotation recommended (manual in v0.1, automated in v0.2)
Master Encryption Key (KEK): NEVER rotate (use key wrapping instead)
Data Encryption Keys (DEK): Rotate with signing keys (same schedule)

Grace Period: 7 days dual-key support during rotation (old + new keys both valid for verification)

Threat Model

Threat	Likelihood	Impact	v0.1 Mitigation	v0.2+ Enhancement
T1: Database Compromise	Medium	High	Keys encrypted with AES-256-GCM, KMS-wrapped DEKs, no plaintext storage	HSM (keys never in database)
T2: KMS/Vault Breach	Low	Critical	FIPS 140-2 Level 3 KMS, IAM policies (least privilege), audit logs (CloudWatch)	Multi-party HSM unsealing, hardware security modules
T3: Insider Threat (DBA)	Low	High	Encrypted keys (DBA can't decrypt without KMS access), audit logs, no direct key access	HSM operations require multi-party approval
T4: JWT Token Theft (XSS, network sniffing)	Medium	Medium	Short expiration (1 hour), HTTPS only, HttpOnly cookies, SameSite=Strict	Hardware-backed signing (Secure Enclave), biometric re-auth
T5: Private Key Compromise (malware, phishing)	Low	High	Server-side keys (not on user devices in v0.1)	Hardware security keys (YubiKey), Secure Enclave (iOS/Android)
T6: Man-in-the-Middle Attack	Low	Medium	TLS 1.3, HSTS headers (force HTTPS), certificate pinning (mobile apps in v0.2)	mTLS for enterprise integrations (mutual authentication)
T7: Replay Attacks (webhooks, JWT reuse)	Medium	Low	Webhook timestamp validation (5-min window), JWT `jti` uniqueness, blacklist in Redis	Distributed ledger timestamping (immutable proof)
T8: Admin Impersonation (password reset)	Low	Critical	Admin reset generates NEW keypair (breaks history, secure), audit logs, multi-party approval	User-controlled escrow (Shamir secret sharing, social recovery)
T9: Consent Log Tampering	Low	Medium	Append-only DB schema (no DELETE/UPDATE permissions), DB audit logs	Hash chains + signatures (v0.2), Merkle tree + ledger anchoring (v0.3)
T10: Side-Channel Attacks (timing, power analysis)	Very Low	Medium	Constant-time crypto libraries (@noble/ed25519, libsodium), no branching on secrets	HSM with hardware protections, Secure Enclave

Risk Acceptance (v0.1)

Accepted Risks for Internal MVP (<100 users, Month 1-3):

✅ RISK-001: Server-stored private keys with KMS encryption

Threat: T2 (KMS breach) or T3 (insider access) could expose keys
Mitigation: FIPS 140-2 KMS, IAM least privilege, audit logs, short JWT expiration
Upgrade: v0.2 - CloudHSM (keys never exported)

✅ RISK-002: No automated key rotation

Threat: T5 (compromised keys require manual rotation)
Mitigation: Manual rotation procedure documented, emergency response runbook (<4hr SLA)
Upgrade: v0.2 - Automated annual rotation

⚠️ RISK-003: Admin recovery mechanism (Decision Pending: Week 3)

Threat: T8 (admin can impersonate users if decrypt old keypair)
Options:
- Option A (Recommended): Generate NEW keypair (secure, breaks history)
- Option B (Not Recommended): Decrypt OLD keypair (preserves history, insecure)
- Option C (Future): User-controlled escrow (Shamir, secure + preserves history)
Decision Required: Before Week 3 (AI Labs launch)

✅ RISK-004: Consent logs without cryptographic integrity

Threat: T9 (DBA could modify logs without detection)
Mitigation: Append-only schema, DB audit logs, read-only replicas
Upgrade: v0.2 - Hash chains + signatures; v0.3 - Merkle tree + ledger

Not Acceptable for v0.1:

❌ Public beta (Month 6+) - requires HSM/Secure Enclave
❌ Regulated industries (HIPAA, PCI-DSS, eIDAS)
❌ High-value transactions (>$10k)
❌ External enterprise customers with compliance requirements

Security Audit & Compliance

External Reviews Required:

Review Type	Timeline	Vendor	Budget	Scope
Cryptographic Consultant	Before Week 3	NCC Group, Trail of Bits, Cure53	$15-30k	Key management architecture, threat model, risk acceptance
Penetration Test (Q1)	Month 3	External firm	$10k	API security, auth flows, OWASP Top 10
Crypto Implementation Audit (Q2)	Month 6	Crypto specialist	$15k	Ed25519 implementation, key wrapping, JWT security
SOC 2 Type I	Month 6	Big 4 auditor	$25k	Key access controls, audit logs, encryption at rest

Compliance Mapping:

Regulation	Requirement	v0.1 Status	v0.2 Target
SOC 2 (CC6.1)	Encryption key management	Documented risk	HSM + multi-party controls
GDPR (Art. 32)	Encryption at rest + in transit	✅ Compliant	Enhanced (Merkle proofs)
CCPA	Reasonable security procedures	✅ Compliant	Certified
eIDAS (EU)	Qualified electronic signatures	❌ Not compliant (admin can access keys)	v0.3 - User-controlled keys
HIPAA	Encryption under covered entity control	❌ Not compliant (HUMAN controls keys)	v0.2 - HSM with BAA terms

IDENTITY AUTHORITY & MINTING RULES

Purpose

This section defines the non-negotiable laws governing identity creation, authority, delegation, and verification within the HUMAN Protocol.

These rules exist to ensure that:

Self-hosted deployments remain safe by construction
Open source implementations cannot collapse identity sovereignty
No organization, agent, or infrastructure component can impersonate a human

This document is normative. Where conflicts exist between implementation convenience and identity sovereignty, sovereignty wins.

Core Principle

Only humans create sovereign identity.

All other identities derive authority only through explicit, cryptographically verifiable delegation from humans.

The Three Identity Types

The HUMAN Protocol defines three distinct identity types, each with different authority levels and minting rules:

1. Human Passport (Sovereign Identity)

Definition: A Human Passport is the root identity of the HUMAN Protocol. It represents a real human being and is the only sovereign identity type.

Properties:

Created exclusively on a human-owned device (never server-side)
Cryptographic keys never leave the device (Secure Enclave, TEE, or hardware key)
Device-bound and user-controlled
Globally portable and protocol-native

Authority:

Sovereign - Cannot be overridden, minted, or impersonated by any system
Can delegate authority to Org and Agent Passports
Can revoke delegations at any time
Can prove capability without revealing private data

Technical Enforcement:

Keys generated in Secure Enclave (iOS), StrongBox (Android), or TPM (desktop)
Private key never transmitted or stored server-side
All identity operations require biometric or passkey authentication

2. Org Passport (Institutional Identity)

Definition: An Org Passport represents a legal or institutional entity operating within the HUMAN Protocol.

Properties:

Created through an explicit genesis ceremony signed by one or more Human Passports
Keys may be held in organizational HSMs or vaults (since orgs aren't physical entities)
Scope is namespaced to the organization
Can issue attestations within its namespace

Authority:

Administrative, not sovereign
May issue org-scoped attestations (e.g., "Alice is employed by Acme Corp")
May delegate bounded authority to Agent Passports
May never create, impersonate, or override human identity
May never mint Human Passports

Technical Enforcement:

Genesis signature from founding humans (multi-sig quorum)
Namespace isolation (org attestations don't cross org boundaries)
Ledger anchor for org creation event (provenance of institutional authority)

3. Agent Passport (Delegated Execution Identity)

Definition: An Agent Passport represents a bounded execution identity acting on behalf of a human or organization.

Properties:

Always created by a parent Human or Org Passport
Explicitly scoped (what it can do)
Time-bound (when it expires)
Revocable (parent can revoke at any time)
Cannot persist beyond declared policy constraints

Authority:

Delegated only - All authority flows from parent
Cannot create identities (no recursive delegation)
Cannot escalate scope beyond parent's delegation
Cannot act independently of parent authority
Must escalate when uncertain (Fourth Law of AI)

Technical Enforcement:

Delegation certificate signed by parent Passport
Scope restrictions encoded in certificate (cryptographically verified)
Expiry timestamp enforced by HumanOS
Revocation checked against distributed ledger before each action

Identity Minting Authority Matrix

Identity Type	Who Can Mint	Where	Technical Constraint
Human Passport	Human device only	On-device (Secure Enclave, TEE, hardware key)	Private key never leaves device
Org Passport	Humans (quorum)	Any deployment	Genesis signature from founding humans required
Agent Passport	Human or Org	Policy-bound runtime	Delegation certificate required

Absolute Rule: No infrastructure component is ever permitted to mint Human Passports.

CRITICAL: HUMAN UNIQUENESS (ONE PASSPORT PER HUMAN)

The Problem: How do we ensure one human = one Passport without surveillance, exclusion, or centralized control?

This is the hardest problem in digital identity. We must balance:

Security: Prevent Sybil attacks (one person creating multiple Passports)
Privacy: No central database of biometric data
Sovereignty: Users control their identity
Accessibility: Works globally, no government ID required
Decentralization: No single point of trust

Multi-Layered Approach (Progressive Verification)

HUMAN uses a defense-in-depth strategy with multiple verification layers. Different use cases require different verification tiers.

Layer 1: Device Attestation (v0.1 - Soft Barrier)
   ↓ (prevents casual duplication)
Layer 2: Biometric Binding (v0.2 - Strong Barrier)  
   ↓ (binds to biological person)
Layer 3: Social Attestation (v0.3 - Web of Trust)
   ↓ (humans vouch for humans)
Layer 4: Proof of Personhood (v1.0 - Cryptographic Uniqueness)
   ↓ (privacy-preserving uniqueness proof)

Layer 1: Device Attestation (v0.1 MVP)

What: Platform-level device integrity verification

How It Works:

// iOS App Attest (Apple's cryptographic device attestation)
const deviceAttestation = await DCAppAttestService.attestKey(keyId);

// Proves:
// ✅ This is a real Apple device (not emulator, not jailbroken)
// ✅ This app is genuine (Apple-signed)
// ✅ This key was generated in Secure Enclave
// ✅ This device hasn't minted a Passport before (first-time flag)

// Android SafetyNet / Play Integrity API
const integrityToken = await googlePlayIntegrity.requestIntegrityToken();

// Proves:
// ✅ Real Android device (Google-verified)
// ✅ App is genuine (not tampered)
// ✅ Device passes SafetyNet checks

What It Prevents:

✅ Bots and scripts (no real device)
✅ Emulators (detected by attestation)
✅ Jailbroken/rooted devices (attestation fails)
✅ Casual duplication (one Passport per device)

What It Doesn't Prevent:

❌ Determined attacker with multiple real devices
❌ Device farm attacks (expensive but possible)

Tradeoff:

Pro: No PII required, works offline, privacy-preserving
Con: Weak barrier (attacker can buy multiple devices)

Use Cases:

Free tier: Device attestation only (good enough for casual use)
Development/testing: Acceptable risk

Layer 2: Biometric Binding (v0.2 - Strong Barrier)

What: Cryptographically bind Passport to biological person via device biometric

How It Works:

// Passport minting requires biometric enrollment
const passportCreation = await HumanApp.createPassport({
  displayName: 'Alice Chen',
  biometricEnrollment: {
    type: 'faceID',  // or touchID, fingerprint
    challenge: 'passport-creation',
    requireLiveness: true  // Anti-spoofing
  }
});

// What happens:
// 1. Device captures biometric (Face ID, Touch ID)
// 2. Biometric template stored ONLY in Secure Enclave (never leaves device)
// 3. Passport keypair bound to biometric
// 4. All signing operations require biometric re-authentication
// 5. Hash of biometric template included in device attestation (but not template itself)

// When user tries to create second Passport on new device:
const secondPassportAttempt = await HumanApp.createPassport({
  displayName: 'Alice Chen 2',
  biometricEnrollment: {
    type: 'faceID',
    challenge: 'passport-creation',
    requireLiveness: true
  }
});

// HUMAN backend checks:
const biometricHash = hash(secondPassportAttempt.biometricTemplate);
const existingPassport = await db.passports.findByBiometricHash(biometricHash);

if (existingPassport) {
  throw new Error(`Passport already exists for this biometric.
  
  If you lost access to your previous Passport, use recovery:
  - Option 1: Recover from another trusted device
  - Option 2: Use social recovery (guardian network)
  - Option 3: Contact support with identity verification
  
  Creating multiple Passports is not allowed.`);
}

What It Prevents:

✅ Same person creating multiple Passports (biometric collision)
✅ Device theft → new Passport (biometric mismatch)
✅ Device farm attacks (each device needs different biometric)

What It Doesn't Prevent:

❌ Identical twins (biometric collision, but rare)
❌ Sophisticated spoofing (3D face models, fingerprint replicas)

Privacy Preservation:

✅ Biometric template NEVER leaves device (stored in Secure Enclave)
✅ Only cryptographic hash sent to HUMAN (irreversible)
✅ Hash cannot reconstruct biometric
✅ HUMAN cannot identify person from hash (unlinkable)

Tradeoff:

Pro: Strong barrier, privacy-preserving (hash only), no PII
Con: Requires device with biometric sensor, accessibility concerns

Use Cases:

Paid tier: Biometric binding required (higher trust)
Enterprise: Org can require biometric for employees
Workforce Cloud: Biometric required for task matching

Layer 3: Social Attestation (v0.3 - Web of Trust)

What: Humans vouch for each other's uniqueness

How It Works:

// Alice's Passport is vouched for by 3 trusted contacts
const socialAttestation = await AlicePassport.requestVouches({
  vouchers: [
    'did:human:bob',    // Bob knows Alice IRL
    'did:human:carol',  // Carol works with Alice
    'did:human:dave'    // Dave is Alice's friend
  ],
  statement: 'I know this person is unique and not a duplicate account'
});

// Each voucher signs attestation
const bobVouch = await BobPassport.sign({
  action: 'vouch_for_uniqueness',
  subject: 'did:human:alice',
  statement: 'I personally know Alice Chen and confirm this is her only Passport',
  confidence: 'high',  // Bob is very sure
  relationship: 'colleague',
  metSince: new Date('2023-01-15')
});

// Reputation-weighted vouching
// - Vouchers with higher reputation (more vouches themselves) count more
// - Vouchers who've never given bad vouches count more
// - Diverse vouch network (different social circles) counts more

// If Alice tries to create second Passport:
const aliceSecondPassportAttempt = await createPassport({
  displayName: 'Alice Smith',  // Different name, same biometric
  // ...
});

// System detects biometric collision, checks social graph
const existingVouches = await getSocialVouches('did:human:alice');
// 3 high-reputation vouches for existing Passport

// Flags attempt as suspicious
await flagSuspiciousPassportCreation({
  existingPassport: 'did:human:alice',
  attemptedPassport: 'did:human:alice-2',
  reason: 'Biometric collision + existing social attestations',
  existingVouches: existingVouches.length,
  reviewRequired: true
});

What It Prevents:

✅ Anonymous Sybil attacks (need real social connections)
✅ Bot networks (can't get human vouches)
✅ Biometric spoofing (vouchers confirm real person)

What It Doesn't Prevent:

❌ Collusion (group of attackers vouch for each other)
❌ Paid vouches (black market for vouches)

Tradeoff:

Pro: Decentralized, no central authority, resistant to single point of failure
Con: Requires social connections, can exclude isolated individuals, vulnerable to collusion

Use Cases:

High-trust tier: Social attestation required (governance roles)
Workforce Cloud premium: Higher-paying tasks require social vouches
Org onboarding: New employee vouched by existing employees

Layer 4: Proof of Personhood (v1.0 - Cryptographic Uniqueness)

What: Zero-knowledge proof that human is unique without revealing identity

How It Works (Conceptual - Research Phase):

// Inspired by but distinct from Worldcoin, Proof of Humanity

// Option A: Privacy-Preserving Biometric Zero-Knowledge Proof
// Uses advanced cryptography (zk-SNARKs) to prove:
// "I am a unique person" WITHOUT revealing:
// - Who I am
// - My biometric data
// - My identity across systems

const uniquenessProof = await generateZKProofOfPersonhood({
  biometricCommitment: hash(biometricTemplate),  // Commitment, not template
  nullifier: deriveNullifier(biometricTemplate),  // Prevents double-registration
  publicKey: AlicePassport.publicKey
});

// Nullifier prevents double-registration:
// - Same biometric → Same nullifier
// - Already seen this nullifier → Reject
// - Different biometric → Different nullifier → Allow

// Verification:
const isValid = await verifyZKProof(uniquenessProof);
// Returns: true (unique person) or false (duplicate/invalid)
// BUT: Verifier learns NOTHING about who the person is

// Option B: Decentralized Identity Verification Network
// Network of validators (randomly selected humans) perform video verification
// Similar to Proof of Humanity, but:
// - No central registry of faces
// - No permanent storage of video
// - Validators are anonymous and rotated
// - Requires N-of-M validators to agree (quorum)

const videoVerification = await requestPersonhoodVerification({
  passport: AlicePassport.did,
  verificationType: 'video-liveness',
  validators: 5,  // Random selection of 5 validators
  quorum: 3       // Need 3 of 5 to agree
});

// Validators see:
// - Live video of person
// - Person performing challenge (hold up unique code, say phrase)
// - Validators vote: "Unique person" or "Duplicate/Bot"
// After verification: Video deleted, only result stored

What It Prevents:

✅ All forms of Sybil attack (cryptographically enforced uniqueness)
✅ Biometric spoofing (liveness checks)
✅ Bot networks (human verification required)
✅ Device farms (person must appear)

What It Doesn't Prevent:

❌ Identical twins (accept this as acceptable collision rate < 0.1%)
❌ Validator collusion (mitigated by random selection + quorum)

Tradeoff:

Pro: Strongest guarantee of uniqueness, privacy-preserving (ZK), decentralized
Con: Complex cryptography, requires research, UX friction, accessibility challenges

Use Cases:

Critical infrastructure: Government services, financial systems
High-value Workforce Cloud: Tasks requiring maximum trust
Governance: Voting, policy decisions, canon-tier operations

Decision Matrix: Which Verification Layer When?

Use Case	Verification Required	Why
Free tier (dev/test)	Layer 1: Device attestation	Low risk, high accessibility
Paid tier (Companion)	Layer 1 + Layer 2: Device + Biometric	Medium risk, strong barrier, privacy-preserving
Enterprise employee	Layer 1 + Layer 2 + Layer 3: Device + Biometric + Social	High trust, employer verification
Workforce Cloud (general)	Layer 2: Biometric	Task matching requires person verification
Workforce Cloud (premium)	Layer 2 + Layer 3: Biometric + Social	High-paying tasks need higher trust
Governance (canon-tier)	All layers: Device + Biometric + Social + Personhood	Critical decisions need maximum confidence
Government services	Layer 4: Proof of Personhood (future)	Regulatory requirement for uniqueness

Attack Scenarios & Mitigations

Attack 1: Device Farm (100 phones)

Attack: Attacker buys 100 real phones, creates 100 Passports

Layer 1 Defense (Device Attestation):

❌ FAILS - Each device gets one Passport

Layer 2 Defense (Biometric):

✅ BLOCKS - Attacker needs 100 different people's biometrics
Mitigation cost: $100,000+ (hire 100 people)
Detection: Biometric hashes from same geographic region, created rapidly

Layer 3 Defense (Social):

✅ BLOCKS - Attacker needs 100 people, each with 3 vouchers
Mitigation cost: 300 vouch relationships
Detection: Graph analysis shows suspicious clustering

Attack 2: Biometric Spoofing (3D face model)

Attack: Attacker creates 3D model of victim's face, fools Face ID

Layer 2 Defense (Biometric + Liveness):

⚠️ PARTIAL - Advanced liveness checks (depth sensing, IR, challenge-response)
Modern devices (iPhone 12+) very resistant, but not perfect

Layer 3 Defense (Social):

✅ BLOCKS - Victim's existing vouchers flag duplicate
Victim can revoke spoofed Passport

Layer 4 Defense (ZK Personhood):

✅ BLOCKS - Nullifier collision (same biometric → same nullifier)

Attack 3: Identical Twins

Attack: Twins have identical biometrics (rare but possible)

Layer 2 Defense (Biometric):

❌ COLLISION - Biometric hash matches
ACCEPTED: Edge case, < 0.1% of population, acceptable risk

Layer 3 Defense (Social):

✅ DIFFERENTIATES - Twins have different social networks
Friends vouch separately

Resolution: Twins can both have Passports, social attestation differentiates

Implementation Roadmap

v0.1 (MVP - Month 1-3)

Goal: Prevent casual duplication, acceptable for internal use

✅ Layer 1: Device attestation (iOS App Attest, Android SafetyNet)
✅ One Passport per device
✅ Detection: Flag multiple Passports from same IP/location
✅ Manual review: Suspicious patterns escalated to ops team

Risk Acceptance: Determined attacker with multiple devices can create multiple Passports

v0.2 (Public Beta - Month 4-6)

Goal: Strong barrier, privacy-preserving, 99% Sybil resistance

✅ Layer 1: Device attestation (required)
✅ Layer 2: Biometric binding (required for paid tier)
✅ Biometric hash collision detection
✅ Liveness checks (anti-spoofing)
✅ Account recovery process (for lost devices)
✅ Grace period: One Passport migration per year (lost phone, upgrade)

Risk Acceptance: Sophisticated biometric spoofing possible but expensive (< 1% attack success rate)

v0.3 (Production - Month 7-12)

Goal: Decentralized web of trust, 99.9% Sybil resistance

✅ Layer 1 + Layer 2 (required)
✅ Layer 3: Social attestation (optional, increases trust score)
✅ Reputation system (vouchers with history count more)
✅ Graph analysis (detect collusion rings)
✅ Governance tier: Requires social vouches for canon-tier operations

Risk Acceptance: Collusion rings possible but detectable, isolated individuals may struggle to get vouches

v1.0 (Enterprise/Gov - Year 2+)

Goal: Cryptographic uniqueness, 99.99% Sybil resistance

✅ Layer 1 + Layer 2 + Layer 3 (required)
✅ Layer 4: Proof of Personhood (optional, regulatory compliance)
✅ ZK-SNARK uniqueness proofs
✅ Decentralized validator network
✅ Integration with government identity systems (opt-in)

Risk Acceptance: Identical twins may collide (< 0.1%), accepted as unavoidable

Key Principles

Privacy-First: Never store raw biometric data centrally
Progressive: Start soft (device), add stronger layers (biometric, social, ZK)
Accessible: Lower tiers don't require biometrics or social connections
Decentralized: No single point of trust
Recoverable: Lost device ≠ lost identity
Transparent: Users know what verification they've completed

FAQ: Human Uniqueness

Q: Can I have multiple Passports? A: No. One human = one Passport. This is enforced via biometric binding.

Q: What if I lose my phone? A: Recover your Passport on a new device using:

Another trusted device (if multi-device setup)
Social recovery (guardian network)
Biometric re-verification on new device

Q: What if my biometric changes (injury, surgery)? A: Passport can be updated with new biometric after identity verification:

Prove ownership via other trusted device
Or social recovery process
Old biometric hash removed, new hash added

Q: What about identical twins? A: Biometric collision between twins is rare but possible. Social attestation (different friend networks) differentiates them. This is an accepted edge case.

Q: Can I delete my Passport and create a new one? A: No. Passport lifecycle:

Create once (biometric bound)
Update credentials/capabilities over time
Revoke devices (if stolen)
Recover if lost
But: Cannot delete and recreate (prevents abuse)

Q: What if someone steals my biometric (3D face model)? A: Modern liveness checks (depth sensing, IR, challenge-response) make this very difficult. Additionally:

Your existing social vouches would flag duplicate
You can revoke the spoofed Passport
HumanOS detects anomalous behavior

IDENTITY VERIFICATION (PROVING YOU ARE WHO YOU CLAIM TO BE)

The Previous Section: Proved you are ONE person (uniqueness/Sybil resistance)
This Section: Proves you are THE SPECIFIC person you claim to be (identity proofing)

The Challenge: Rick Bush creates a Passport. How do we verify this Passport actually belongs to "Rick Bush the person" and not "John Smith pretending to be Rick Bush"?

This is critical for:

Enterprise onboarding: Acme hires Rick Bush → Give him Passport access → Need to verify it's really Rick
Workforce Cloud: Task routing to "Rick Bush, licensed electrician" → Need to verify Rick has that license
Agent delegation: Rick delegates to agent → Agent acts as Rick → Need proof agent is authorized by REAL Rick
Compliance: HIPAA, SOX, financial regulations require knowing who performed actions

Two Distinct Identity Problems

Problem	Question	Solution Approach
Uniqueness	Is this person creating multiple Passports?	Biometric binding, device attestation (previous section)
Identity	Is this person actually Rick Bush?	Trusted introducers, KYC providers, credential verification (this section)

Tiered Identity Verification (Progressive Trust)

Different use cases require different levels of identity verification:

Tier 0: Pseudonymous (No verification)
   ↓
Tier 1: Org-Verified (Employer/Institution vouches) ← PRIMARY ONBOARDING PATH
   ↓
Tier 2: KYC-Verified (Government ID + biometric match)
   ↓
Tier 3: Credential-Verified (Licenses, degrees attested)

Tier 1: Org-Verified Passport (PRIMARY PATH - Low Friction)

Use Case: Enterprise employee onboarding, contractor access, student enrollment

Identity Claim: "I am Rick Bush, employee of Acme Corp"

Verification: Organization vouches for identity (org already verified Rick during hiring)

The Flow (< 2 minutes for employee):

// STEP 1: Acme's HR creates employee record (already verified Rick's identity during hiring)
const employeeRecord = await AcmeOrgPassport.createEmployeeRecord({
  legalName: 'Richard M. Bush',
  email: 'rick.bush@acme.com',
  employeeId: 'EMP-5678',
  startDate: '2026-01-03',
  department: 'Engineering',
  role: 'Senior Software Engineer',
  
  // HR verified during hiring (background check, I-9, government ID)
  identityVerification: {
    method: 'government_id',
    governmentId: {
      type: 'drivers_license',
      state: 'CA',
      verified: true,
      verifiedBy: 'did:human:hr-manager-jane',
      verifiedDate: '2026-01-02'
    },
    backgroundCheck: {
      provider: 'Checkr',
      status: 'clear',
      completedDate: '2026-01-02'
    }
  }
});

// STEP 2: Acme sends onboarding email to Rick
await sendEmail({
  to: 'rick.bush@acme.com',
  subject: 'Welcome to Acme - Setup Your HUMAN Passport',
  body: `Welcome Rick! Setup takes < 2 minutes:
    
    1. Download HUMAN app
    2. Create Passport (Face ID)
    3. Enter code: ACME-${employeeRecord.linkingCode}
    
    This gives you access to Acme systems, Companion, and agent workflows.`
});

// STEP 3: Rick creates Passport on phone (30 seconds)
const rickPassport = await HumanApp.createPassport({
  displayName: 'Rick Bush',
  biometricBinding: true,  // Face ID - ensures uniqueness
  verificationType: 'org'
});

// STEP 4: Rick enters linking code from email (30 seconds)
const linkingResult = await rickPassport.linkToOrganization({
  linkingCode: 'ACME-xyz789',
  email: 'rick.bush@acme.com'
});

// STEP 5: Email verification (30 seconds)
const emailCode = await sendVerificationCode('rick.bush@acme.com');
await rickPassport.verifyEmail({ code: '123456' });

// STEP 6: Acme issues employment attestation (automatic)
const employmentAttestation = await AcmeOrgPassport.issueAttestation({
  subject: rickPassport.did,
  type: 'EmploymentCredential',
  claims: {
    legalName: 'Richard M. Bush',
    employer: 'Acme Corporation',
    employeeId: 'EMP-5678',
    role: 'Senior Software Engineer',
    email: 'rick.bush@acme.com',
    identityVerified: true,
    verificationMethod: 'government_id_during_hiring'
  },
  signature: await AcmeOrgPassport.sign({...}),
  ledgerAnchor: await Ledger.anchor({...})
});

await rickPassport.storeCredential(employmentAttestation);

console.log(`✅ Rick Bush verified by Acme Corp`);
console.log(`Time: < 2 minutes`);
console.log(`Rick can now: Access Acme systems, use agents, approve expenses`);

Key Benefits:

✅ LOW FRICTION: Rick just installs app, enters code (< 2 minutes)
✅ No redundant verification: Acme already verified Rick during hiring
✅ High confidence: Acme vouches Rick is Rick Bush
✅ Org controls access: Acme can revoke if Rick leaves
✅ Scales: Onboard 1000 employees same way
✅ Prevents duplicates: Biometric binding prevents Rick creating second Passport
✅ Prevents impersonation: Only real Rick controls rick.bush@acme.com

What This Enables:

Rick uses Acme's agent workflows (invoice approval, expense submission)
Rick accesses Workforce Cloud (as Acme contractor, Acme pays)
Rick's actions traceable to real person (compliance)
If Rick delegates to agent, clear chain: Rick (human) → Agent

Tier 2: KYC-Verified Passport (Self-Signup - Higher Friction)

Use Case: Independent contractors, Workforce Cloud (no employer), financial transactions

Identity Claim: "I am Rick Bush" (independent of employer)

Verification: KYC provider (Onfido, ID.me) verifies government ID + biometric match

The Flow (5-10 minutes):

// Rick creates Passport, initiates KYC
const rickPassport = await HumanApp.createPassport({
  displayName: 'Rick Bush',
  verificationType: 'kyc'
});

// Rick uploads government ID + takes selfie
const kycResult = await Onfido.verify({
  governmentId: driverLicensePhoto,
  selfie: liveSelfieVideo,
  checks: ['document_authenticity', 'facial_similarity', 'liveness']
});

// Onfido issues attestation if verified
if (kycResult.status === 'clear') {
  const kycAttestation = await Onfido.issueAttestation({
    subject: rickPassport.did,
    claims: {
      legalName: 'Richard M. Bush',
      dateOfBirth: '1985-03-15',
      governmentIdVerified: true,
      facialMatch: 0.97
    }
  });
  
  await rickPassport.storeCredential(kycAttestation);
}

Use when: No employer to vouch, need independent identity proof

Tier 3: Credential-Verified (Professional Licenses)

Use Case: Licensed professionals (doctors, lawyers, electricians)

Verification: License board attests to professional credential

The Flow:

// Rick has Tier 1 or 2, now adds professional license
const licenseAttestation = await CaliforniaContractorsLicenseBoard.verify({
  licenseNumber: 'C10-123456',
  holderName: 'Richard M. Bush',
  passportDid: rickPassport.did
});

// License board confirms Rick Bush holds active license
await rickPassport.storeCredential(licenseAttestation);

// Capability Graph updated: Rick can now work on electrical tasks
await CapabilityGraph.updateFromCredential({
  passportId: rickPassport.did,
  credential: licenseAttestation,
  capabilitiesAdded: ['electrical/residential', 'electrical/commercial']
});

Use when: Credential-gated work (medical, legal, skilled trades)

YOUR PRIMARY USE CASE: Enterprise Onboarding

Scenario: Onboard Rick Bush (Acme employee) with low friction but verify identity

Solution: Tier 1 (Org-Verified)

Why This Works:

Acme already verified Rick during hiring (government ID, background check, I-9)
No redundant verification needed (leverage existing trust)
Rick just: Install app → Enter code → Face ID → Done (< 2 minutes)
Acme vouches: "DID abc123 is Rick Bush, our employee"
Biometric binding: Prevents Rick creating second Passport
Email verification: Proves Rick controls rick.bush@acme.com
Result: Rick has Passport linked to real identity, can use agents immediately

Prevents:

❌ Rick creating second Passport (biometric collision detected)
❌ Someone else impersonating Rick (can't get Acme attestation without controlling rick.bush@acme.com)
❌ Fake Rick Bush (Acme already verified during hiring)

Scales:

Onboard 1 employee: 2 minutes
Onboard 1000 employees: 2 minutes each (parallel)

Comparison: Uniqueness vs Identity

Problem	What It Solves	Solution	Result
Uniqueness	One person creating multiple Passports	Biometric binding	Rick can't create Passport #2
Identity	Wrong person claiming to be Rick	Org attestation	We know DID abc123 is Rick Bush

Both required: Uniqueness ensures one Passport per person. Identity links Passport to specific person.

COMPLETE IDENTITY VERIFICATION MATRIX: ALL USE CASES

Purpose: Map every workflow in KB 106 to required identity verification tier. These become our proof-of-concept test cases.

Enterprise Employee Workflows (Tier 1: Org-Verified)

Use Case	Identity Verification	Proof Test	Code Location
Invoice Processing	Acme CFO Carol approves invoices > $5k	Carol has `finance/invoice-approver` capability from Acme attestation	KB 106 Line 305
Expense Approval	Employee submits, manager approves	Manager verified by Acme HR during hiring, linked via org attestation	KB 106 Line 237
Contract Review	Attorney reviews contracts	Attorney has `legal/contract-attorney` capability from law firm attestation	KB 106 Line 417
IT Ticket Triage	Engineer receives capability-routed tickets	Engineer verified by IT dept, has `engineering/support` capability	New use case needed
HR Onboarding	New employee setup	HR manager verified, has `hr/admin` capability	New use case needed

Identity Flow (All Enterprise Workflows):

// 1. Org verifies identity during hiring (one-time)
// 2. Employee creates Passport, links to org (< 2 min)
// 3. Org issues attestation with capabilities
// 4. Agent workflows check capability before routing
// 5. All actions logged with employee's DID

// Example: Carol approves $7k invoice
const approval = await ctx.oversight.approve({
  requiredCapability: 'finance/invoice-approver',
  // HumanOS routes to Carol (she has this capability from Acme attestation)
});

// Provenance:
// - Agent DID: did:agent:invoice-processor
// - Approver DID: did:human:carol (verified by Acme)
// - Org DID: did:org:acme-corp (vouches for Carol)

Healthcare Workflows (Tier 3: Credential-Verified)

Use Case	Identity Verification	Proof Test	Code Location
Clinical Note Review	Only licensed physicians can approve	Physician license verified by state board	KB 106 Line 685
Medical Triage	On-call physician for critical cases	Emergency medicine board certification	KB 106 Line 521
Prescription Approval	DEA-licensed prescriber required	DEA number verified	New use case needed
Radiology Review	Board-certified radiologist	ABIM certification verified	New use case needed

Identity Flow (Healthcare):

// 1. Dr. Patel creates Passport (Tier 1: Hospital employee)
const drPatelPassport = await HumanApp.createPassport({
  displayName: 'Dr. Sarah Patel',
  verificationType: 'org'  // Mayo Clinic vouches
});

// 2. Mayo Clinic issues employment attestation
const employmentAttestation = await MayoClinic.issueAttestation({
  subject: drPatelPassport.did,
  role: 'Attending Physician - Emergency Medicine'
});

// 3. Dr. Patel requests medical license verification (Tier 3)
const licenseAttestation = await CaliforniaMedicalBoard.verify({
  licenseNumber: 'A-12345',
  holderName: 'Sarah Patel',
  passportDid: drPatelPassport.did
});

// 4. Capability Graph updated from license
await CapabilityGraph.updateFromCredential({
  passportId: drPatelPassport.did,
  credential: licenseAttestation,
  capabilitiesAdded: [
    'healthcare/physician',
    'healthcare/emergency-medicine',
    'healthcare/prescribe-controlled-substances'
  ],
  weight: 0.95  // High weight (state-verified license)
});

// 5. Medical triage routes critical cases to Dr. Patel
const criticalCase = await medicalTriageAgent.execute({
  severity: 'critical',
  // HumanOS finds Dr. Patel (has healthcare/emergency-medicine capability)
  // Verifies license is active, not revoked
  // Routes emergency case for review
});

Proof Test:

Create Dr. Patel's Passport
Link to hospital (Tier 1)
Add medical license (Tier 3)
Route critical case
Verify only licensed physicians receive it

Financial/Fraud Workflows (Tier 2: KYC-Verified)

Use Case	Identity Verification	Proof Test	Code Location
Fraud Investigation	Certified fraud examiner	CFE certification + KYC	KB 106 Line 929
Transaction Review	Senior fraud investigator	Government ID + background check	KB 106 Line 929
AML Screening	Compliance officer	CAMS certification + KYC	New use case needed
Wire Transfer Approval	Authorized signatory	Bank KYC + signature authority	New use case needed

Identity Flow (Financial):

// Fintech hiring fraud investigator (no prior employment history)

// 1. Investigator creates Passport, KYC verifies (Tier 2)
const investigatorPassport = await HumanApp.createPassport({
  displayName: 'Alex Chen',
  verificationType: 'kyc'
});

// 2. Onfido KYC: Government ID + selfie
const kycAttestation = await Onfido.verify({
  governmentId: alexDriverLicense,
  selfie: alexLiveSelfie,
  checks: ['document_authenticity', 'facial_similarity', 'liveness']
});

// 3. Fintech requests CFE certification verification
const cfeAttestation = await ACFECertificationBoard.verify({
  certNumber: 'CFE-67890',
  holderName: 'Alexander Chen',
  passportDid: investigatorPassport.did
});

// 4. Fintech issues employment attestation (Tier 1)
const employmentAttestation = await FintechOrg.issueAttestation({
  subject: investigatorPassport.did,
  role: 'Senior Fraud Investigator',
  backgroundCheckCompleted: true,
  startDate: '2026-01-03'
});

// 5. Fraud detection routes high-risk transactions to Alex
const highRiskTransaction = await fraudDetector.execute({
  transactionId: 'tx_123',
  fraudScore: 0.85,  // High risk
  // HumanOS routes to Alex (has finance/senior-fraud-investigator capability)
  // Verifies: KYC (Tier 2) + CFE cert (Tier 3) + Employment (Tier 1)
});

Proof Test:

Create investigator Passport with KYC
Add CFE certification
Link to fintech employer
Route high-risk transaction ($10k+)
Verify only certified investigators get routed

Workforce Cloud (Mixed Tiers)

Use Case	Identity Verification	Proof Test	Code Location
Licensed Electrician	Tier 3: Contractor license + Tier 2: KYC	State license board + government ID	New use case needed
Certified Tutor	Tier 2: KYC + Tier 3: Teaching credential	Government ID + state certification	New use case needed
Software Developer	Tier 1: Employer OR Tier 0: Portfolio	Company attestation OR GitHub profile	New use case needed
Content Moderator	Tier 2: KYC (age verification)	Government ID (18+)	New use case needed

Identity Flow (Workforce Cloud - Independent Contractor):

// Rick Bush (licensed electrician) joins Workforce Cloud independently

// 1. Rick creates Passport, KYC verifies (Tier 2 - required for payment)
const rickPassport = await HumanApp.createPassport({
  displayName: 'Rick Bush',
  verificationType: 'kyc'
});

const kycAttestation = await IDme.verify({
  governmentId: rickDriverLicense,
  selfie: rickLiveSelfie
});

// 2. Rick adds contractor license (Tier 3 - required for electrical work)
const licenseAttestation = await CaliforniaContractorsBoard.verify({
  licenseNumber: 'C10-123456',
  licenseType: 'C10 - Electrical Contractor',
  holderName: 'Richard M. Bush',
  passportDid: rickPassport.did
});

// 3. Capability Graph updated
await CapabilityGraph.updateFromCredential({
  passportId: rickPassport.did,
  credentials: [kycAttestation, licenseAttestation],
  capabilitiesAdded: [
    'electrical/residential',
    'electrical/commercial',
    'electrical/troubleshooting'
  ],
  weight: 0.90  // High weight (state license + KYC)
});

// 4. Customer posts electrical job
const electricalJob = await WorkforceCloud.postTask({
  type: 'electrical_panel_upgrade',
  requiredCapabilities: ['electrical/residential'],
  requiredCertifications: ['contractors_license_c10'],
  location: 'San Francisco, CA',
  budget: '$500-800'
});

// 5. HumanOS routes to Rick
const taskAssignment = await HumanOS.routeTask({
  task: electricalJob,
  // Finds Rick (has electrical/residential capability)
  // Verifies license is active (not revoked/expired)
  // Verifies KYC for payment processing
  // Checks Rick's availability and location match
});

// 6. Rick completes work, customer reviews
const taskCompletion = await WorkforceCloud.completeTask({
  taskId: electricalJob.id,
  completedBy: rickPassport.did,
  customerRating: 5,
  proof: electricalWorkPhotos
});

// 7. Capability Graph updated from demonstrated work
await CapabilityGraph.updateFromWork({
  passportId: rickPassport.did,
  taskId: electricalJob.id,
  rating: 5,
  capabilityDemonstrated: 'electrical/residential',
  weightIncrease: +0.02  // Now 0.92 (license + proven work)
});

Proof Test:

Create Rick's Passport with KYC
Add C10 contractor license
Post electrical job requiring license
Verify Rick gets routed, unlicensed workers don't
Complete job, verify capability weight increases

AI Labs & Developer Workflows (Tier 0-1)

Use Case	Identity Verification	Proof Test	Code Location
Safety Review	AI safety researcher	Tier 1: AI lab employee	KB 106 Line 1126
Model Testing	ML engineer	Tier 1: AI lab employee	KB 106 Line 1346
Enterprise API User	Hospital physician	Tier 1: Hospital employee + Tier 3: Medical license	KB 106 Line 1346
Developer Experimentation	Tier 0: Pseudonymous	Device attestation only	KB 106 Line 52

Students & Educational Workflows (Tier 1: Institution-Verified)

Use Case	Identity Verification	Proof Test	Code Location
Campus Access	University student	Tier 1: University registrar vouches	KB 106 Line 1408
Student Discount Verification	College student	Tier 1: .edu email + university attestation	Planned
Academic Credential Sharing	Graduate student	Tier 1: University transcript attestation	Planned
Peer Tutoring	Student tutor	Tier 1: Student + demonstrated capability	Planned

Identity Flow (Student):

// Sarah enrolls at Stanford University

// 1. Stanford admissions verifies identity during enrollment
const studentRecord = await StanfordUniversity.createStudentRecord({
  legalName: 'Sarah Martinez',
  studentId: '12345678',
  email: 'sarah.martinez@stanford.edu',
  enrollmentDate: '2026-09-01',
  program: 'Computer Science',
  degreeLevel: 'Undergraduate',
  identityVerified: true  // Verified during admissions (government ID)
});

// 2. Sarah creates Passport, links to Stanford (< 2 min)
const sarahPassport = await HumanApp.createPassport({
  displayName: 'Sarah Martinez',
  verificationType: 'institution'  // Similar to 'org'
});

await sarahPassport.linkToInstitution({
  linkingCode: 'STANFORD-xyz789',
  email: 'sarah.martinez@stanford.edu'
});

// 3. Email verification
await sarahPassport.verifyEmail({ code: '123456' });

// 4. Stanford issues student attestation (automatic)
const studentAttestation = await StanfordUniversity.issueAttestation({
  subject: sarahPassport.did,
  type: 'StudentCredential',
  claims: {
    legalName: 'Sarah Martinez',
    studentId: '12345678',
    institution: 'Stanford University',
    email: 'sarah.martinez@stanford.edu',
    program: 'Computer Science',
    degreeLevel: 'undergraduate',
    enrollmentStatus: 'active',
    expectedGraduation: '2030-06-15',
    identityVerified: true,
    verificationMethod: 'government_id_during_admissions'
  },
  issuer: 'did:org:stanford-university',
  validFrom: '2026-09-01',
  validUntil: '2030-06-15'  // Valid through graduation
});

await sarahPassport.storeCredential(studentAttestation);

// 5. Sarah can now access student-only workflows
const campusAccess = await CampusAccessAgent.execute({
  location: 'Engineering Library',
  requiredCapability: 'stanford/student'
  // Routes to Sarah (has stanford/student capability)
});

// 6. Sarah receives student discount automatically
const studentDiscount = await StudentDiscountAgent.execute({
  merchant: 'Adobe Creative Cloud',
  requiredVerification: 'active_student'
  // Verifies Sarah's student attestation is active (not expired)
  // Applies 50% student discount
});

// 7. Upon graduation, Stanford issues degree credential (Tier 3)
const degreeCredential = await StanfordUniversity.issueAttestation({
  subject: sarahPassport.did,
  type: 'DegreeCredential',
  claims: {
    degree: 'Bachelor of Science',
    major: 'Computer Science',
    gpa: 3.85,
    graduationDate: '2030-06-15',
    honors: 'Magna Cum Laude'
  },
  // This becomes a permanent, verifiable credential
  // No expiration date
});

// 8. Sarah's Passport now shows: Stanford student (active) + CS degree (permanent)

Proof Test:

Create Sarah's student Passport (Tier 1)
Verify campus access granted
Verify student discount applied
Graduate Sarah, verify degree credential issued
Verify student attestation expired, degree credential permanent

Unemployed & Job Seekers (Tier 0-2)

Use Case	Identity Verification	Proof Test	Code Location
Personal Companion	Unemployed individual	Tier 0: Pseudonymous (free)	Existing KB 106
Workforce Cloud Job Search	Job seeker	Tier 2: KYC (required for payment)	New use case needed
Free Reskilling (Academy)	Displaced worker	Tier 0: Pseudonymous (no barriers)	New use case needed
Unemployment Benefits	Former employee	Tier 2: KYC + past employment attestation	New use case needed

Identity Flow (Unemployed → Employed):

// Alex was laid off from TechCorp, now seeking work

// 1. Alex creates Passport while unemployed (Tier 0 - free)
const alexPassport = await HumanApp.createPassport({
  displayName: 'Alex Thompson',
  verificationType: 'pseudonymous'  // No identity verification required
});

// 2. Alex retains past employment attestation from TechCorp
const pastEmployment = alexPassport.credentials.find(
  c => c.type === 'EmploymentCredential' && c.issuer === 'did:org:techcorp'
);

// Past employment shows "end date" but remains as proof of experience
expect(pastEmployment.claims.endDate).toBe('2025-12-31');
expect(pastEmployment.status).toBe('completed');  // Not revoked, just ended

// 3. Alex uses Companion for free (Tier 0 - no barriers)
const companionAccess = await CompanionAgent.execute({
  query: 'Help me update my resume',
  // No identity verification required for personal Companion
});

// 4. Alex accesses free reskilling in Academy (Tier 0 - zero barriers principle)
const reskillingCourse = await Academy.enroll({
  passportId: alexPassport.did,
  course: 'AI Safety Fundamentals',
  cost: 0,  // FREE for all humans (Principle Six)
  reason: 'reskilling'
});

// 5. Alex completes course, receives Academy credential
const courseCredential = await Academy.issueAttestation({
  subject: alexPassport.did,
  type: 'CourseCompletionCredential',
  course: 'AI Safety Fundamentals',
  grade: 'Pass',
  completionDate: '2026-02-15'
});

// 6. Alex joins Workforce Cloud (requires KYC for payment processing)
const kycResult = await alexPassport.upgradeToKYC({
  governmentId: alexDriverLicense,
  selfie: alexLiveSelfie
});

// Now Tier 2: Can receive payments
const workforceProfile = await WorkforceCloud.createProfile({
  passportDid: alexPassport.did,
  skills: ['Python', 'Data Analysis', 'AI Safety'],
  credentials: [pastEmployment, courseCredential],
  canReceivePayment: true  // KYC verified
});

// 7. Alex gets hired by NewCorp
const newEmployment = await NewCorp.issueAttestation({
  subject: alexPassport.did,
  type: 'EmploymentCredential',
  role: 'AI Safety Analyst',
  startDate: '2026-03-01'
});

// 8. Alex's Passport journey: Tier 0 → Tier 2 → Tier 1
// Pseudonymous (unemployed) → KYC (Workforce Cloud) → Org-verified (NewCorp employee)

Proof Test:

Create unemployed Alex's Passport (Tier 0)
Verify free Companion access
Verify free Academy enrollment (zero barriers)
Upgrade to KYC (Tier 2) for Workforce Cloud
Verify payment processing enabled
New employer issues attestation (Tier 1)

Retired Individuals (Tier 0-2)

Use Case	Identity Verification	Proof Test	Code Location
Consulting/Mentorship	Retired executive	Tier 1: Past employer attestation (maintained)	New use case needed
Retirement Benefits	Retiree	Tier 2: KYC + Social Security verification	New use case needed
Volunteer Work	Retired professional	Tier 0: Pseudonymous OR Tier 1: Past credentials	New use case needed
Part-Time Work	Semi-retired	Tier 2: KYC for Workforce Cloud	New use case needed

Identity Flow (Retired Professional):

// Dr. Lisa Chen retires after 40 years as physician

// 1. Dr. Chen's Passport has rich history
const drChenPassport = await Passport.get('did:human:dr-lisa-chen');

// Past employment (Tier 1 - maintained after retirement)
const mayoClinicEmployment = drChenPassport.credentials.find(
  c => c.type === 'EmploymentCredential' && c.issuer === 'did:org:mayo-clinic'
);
expect(mayoClinicEmployment.claims.endDate).toBe('2026-01-01');
expect(mayoClinicEmployment.status).toBe('completed');  // Not revoked
expect(mayoClinicEmployment.claims.yearsOfService).toBe(40);

// Medical license (Tier 3 - can be maintained or let expire)
const medicalLicense = drChenPassport.credentials.find(
  c => c.type === 'ProfessionalLicenseCredential'
);

// Option A: Keep license active (continue seeing patients part-time)
if (drChen.wantsToKeepLicenseActive) {
  await CaliforniaMedicalBoard.renewLicense({
    licenseNumber: 'A-12345',
    status: 'active',
    renewalDate: '2026-12-31'
  });
}

// Option B: Let license lapse (fully retired)
// License remains as proof of past credential, but status changes
expect(medicalLicense.status).toBe('expired');
expect(medicalLicense.claims.expirationDate).toBe('2026-01-01');

// 2. Dr. Chen offers consulting/mentorship (past credentials remain valuable)
const mentoringProfile = await WorkforceCloud.createProfile({
  passportDid: drChenPassport.did,
  serviceType: 'mentorship',
  capabilities: [
    'healthcare/clinical-mentorship',  // Based on 40 years experience
    'healthcare/medical-education'
  ],
  credentials: [mayoClinicEmployment, medicalLicense],  // Past creds prove expertise
  hourlyRate: 200,
  availability: 'part-time'
});

// 3. Dr. Chen needs KYC for payment processing (Tier 2)
if (!drChenPassport.hasKYC) {
  await drChenPassport.upgradeToKYC({
    governmentId: drChenDriverLicense,
    selfie: drChenSelfie
  });
}

// 4. Medical resident requests mentorship
const mentoringRequest = await MentorshipAgent.execute({
  topic: 'Clinical decision making in emergency medicine',
  requiredCapability: 'healthcare/clinical-mentorship',
  // Routes to Dr. Chen (40 years Mayo Clinic + ER experience)
  // Past credentials prove expertise even though retired
});

// 5. Capability Graph weighs past credentials
await CapabilityGraph.calculateWeight({
  passportId: drChenPassport.did,
  capability: 'healthcare/clinical-mentorship',
  factors: {
    yearsExperience: 40,  // Very high weight
    institutionPrestige: 0.95,  // Mayo Clinic
    licenseStatus: 'expired',  // Lower weight (not active)
    recentActivity: 0.2  // Lower weight (retired)
  },
  totalWeight: 0.85  // Still very high due to experience
});

// 6. Dr. Chen can also volunteer (Tier 0 - no verification needed)
const volunteerWork = await VolunteerAgent.execute({
  organization: 'Free Clinic',
  role: 'Medical Advisor',
  verificationType: 'none'  // Volunteer work doesn't require identity verification
});

Proof Test:

Create retired Dr. Chen's Passport with past employment
Verify past credentials maintained (not revoked)
Create mentorship profile (past creds prove expertise)
Route mentorship request to Dr. Chen
Verify Capability Graph weighs experience highly despite retirement

Newborns & Parent-Controlled Passports (Tier 3: Birth Certificate)

Use Case	Identity Verification	Proof Test	Code Location
Healthcare Records	Newborn	Tier 3: Birth certificate + parent control	New use case needed
Vaccination Tracking	Infant	Tier 3: Birth certificate + healthcare provider	New use case needed
Government Benefits	Newborn	Tier 3: Birth certificate + SSN	New use case needed
Passport Ownership Transfer	Child → Adult	Gradual autonomy (age 13, 16, 18)	New use case needed

Identity Flow (Newborn Passport):

// Emma and David have a baby (Olivia)

// 1. Hospital issues birth certificate
const birthCertificate = {
  childName: 'Olivia Rose Johnson',
  dateOfBirth: '2026-01-03',
  placeOfBirth: 'Stanford Hospital, Palo Alto, CA',
  parents: [
    { name: 'Emma Johnson', did: 'did:human:emma-johnson' },
    { name: 'David Johnson', did: 'did:human:david-johnson' }
  ],
  certificateNumber: 'CA-2026-SF-001234',
  issuer: 'California Department of Public Health'
};

// 2. Parents create Passport for Olivia (parent-controlled)
const oliviaPassport = await HumanApp.createChildPassport({
  displayName: 'Olivia Johnson',
  dateOfBirth: '2026-01-03',
  verificationType: 'birth_certificate',
  parentControllers: [
    'did:human:emma-johnson',
    'did:human:david-johnson'
  ],
  birthCertificate: birthCertificate,
  consentRequired: 'both_parents'  // Both parents must approve actions
});

// 3. California DPH verifies birth certificate, issues attestation
const birthAttestation = await CaliforniaDPH.issueAttestation({
  subject: oliviaPassport.did,
  type: 'BirthCertificateCredential',
  claims: {
    legalName: 'Olivia Rose Johnson',
    dateOfBirth: '2026-01-03',
    placeOfBirth: 'Stanford Hospital, Palo Alto, CA',
    parents: ['did:human:emma-johnson', 'did:human:david-johnson'],
    certificateNumber: 'CA-2026-SF-001234',
    verified: true
  },
  issuer: 'did:gov:california-dph',
  // Permanent credential (birth certificates don't expire)
});

// 4. Hospital adds Olivia to healthcare system
const healthcareRecord = await StanfordHospital.createPatientRecord({
  patientPassportDid: oliviaPassport.did,
  parentGuardians: [
    'did:human:emma-johnson',
    'did:human:david-johnson'
  ],
  dateOfBirth: '2026-01-03',
  // All healthcare actions require parent approval
});

// 5. Pediatrician updates vaccination record (requires parent consent)
const vaccinationUpdate = await PediatricAgent.execute({
  patientDid: oliviaPassport.did,
  vaccine: 'Hepatitis B',
  dose: 1,
  date: '2026-01-03',
  // Requires parent approval
  parentApproval: await ctx.oversight.approve({
    question: 'Approve Hepatitis B vaccine for Olivia?',
    requiredPassport: 'did:human:emma-johnson',  // Emma must approve
    context: { vaccine: 'Hepatitis B', dose: 1, risks: '...', benefits: '...' }
  })
});

// 6. Government benefits (SSN required)
const ssnAttestation = await SocialSecurityAdmin.issueAttestation({
  subject: oliviaPassport.did,
  type: 'SocialSecurityNumberCredential',
  ssn: '123-45-6789',  // Encrypted, never exposed
  issuer: 'did:gov:ssa'
});

// 7. Olivia's Passport structure (parent-controlled)
expect(oliviaPassport.controllers).toEqual([
  'did:human:emma-johnson',
  'did:human:david-johnson'
]);
expect(oliviaPassport.autonomyLevel).toBe('none');  // Age 0: Parents control everything
expect(oliviaPassport.credentials).toContain(birthAttestation, ssnAttestation);

Proof Test:

Create newborn Passport with birth certificate
Verify parent-controlled (both parents must approve)
Add healthcare record (requires parent consent)
Update vaccination (requires parent approval)
Verify SSN credential issued

Children & Graduated Autonomy (Tier 1-3: School or Birth Certificate)

Use Case	Identity Verification	Proof Test	Code Location
School Access	Child (age 5-12)	Tier 1: School enrollment	Planned
Age-Appropriate Content	Minor (age 13-17)	Tier 3: Birth certificate (age verification)	Planned
Part-Time Work	Teen (age 16+)	Tier 2: KYC (work permit)	KB 106 Line 1650
Graduated Autonomy	Child → Adult	Age milestones (13, 16, 18)	New use case needed

Identity Flow (Child with Graduated Autonomy):

// Olivia grows up, autonomy increases over time

// AGE 5: Parents enroll Olivia in elementary school
const schoolAttestation = await PaloAltoSchools.issueAttestation({
  subject: oliviaPassport.did,
  type: 'StudentCredential',
  grade: 'Kindergarten',
  school: 'Palo Alto Elementary',
  // Parents still control Passport
});

expect(oliviaPassport.autonomyLevel).toBe('none');  // Parents approve everything

// AGE 13: First autonomy milestone (can use social media with parental oversight)
await oliviaPassport.updateAutonomy({
  age: 13,
  autonomyLevel: 'limited',
  // Olivia can approve low-risk actions herself
  // High-risk actions still require parent approval
  selfApprovalCapabilities: [
    'social/post-content',
    'education/complete-homework',
    'entertainment/age-appropriate'
  ],
  parentApprovalRequired: [
    'financial/*',  // Any financial transactions
    'personal-data/share-with-third-party',
    'healthcare/*'
  ]
});

// Olivia posts on social media (no parent approval needed)
const socialPost = await SocialMediaAgent.execute({
  action: 'post',
  content: 'Great day at school!',
  requiredPassport: oliviaPassport.did,
  // Olivia approves herself (she's 13, has limited autonomy)
});

// Olivia tries to buy something (requires parent approval)
const purchase = await PaymentAgent.execute({
  item: 'New phone',
  amount: 500,
  requiredPassport: oliviaPassport.did,
  // Escalates to parent (financial action)
  parentApproval: await ctx.oversight.approve({
    question: 'Approve $500 purchase for new phone?',
    requiredPassport: 'did:human:emma-johnson',
    context: { child: oliviaPassport.did, item: 'iPhone', amount: 500 }
  })
});

// AGE 16: Second autonomy milestone (can work part-time)
await oliviaPassport.updateAutonomy({
  age: 16,
  autonomyLevel: 'moderate',
  // Olivia can work, manage some finances
  additionalCapabilities: [
    'employment/part-time',
    'financial/personal-budget',
    'transportation/drivers-license'
  ],
  parentApprovalRequired: [
    'healthcare/major-medical',  // Major medical still needs parent
    'financial/large-transaction'  // Large purchases need parent
  ]
});

// Olivia gets part-time job (requires KYC + work permit)
const workPermit = await CaliforniaLaborBoard.issueAttestation({
  subject: oliviaPassport.did,
  type: 'WorkPermitCredential',
  age: 16,
  parentConsent: true,  // Emma approved work permit
  restrictions: {
    maxHoursPerWeek: 20,
    prohibitedIndustries: ['alcohol', 'gambling', 'hazardous']
  }
});

const partTimeJob = await CoffeeShop.issueAttestation({
  subject: oliviaPassport.did,
  type: 'EmploymentCredential',
  role: 'Barista',
  hoursPerWeek: 15,
  wage: 18.50,
  // Olivia can accept job herself (has moderate autonomy)
});

// AGE 18: Full autonomy (legal adult)
await oliviaPassport.updateAutonomy({
  age: 18,
  autonomyLevel: 'full',
  // Parents no longer controllers
  controllers: ['did:human:olivia-johnson'],  // Olivia controls her own Passport
  parentApprovalRequired: []  // No parent approval needed
});

// Parents no longer have control
expect(oliviaPassport.controllers).toEqual(['did:human:olivia-johnson']);
expect(oliviaPassport.parentAdvisors).toEqual([
  'did:human:emma-johnson',
  'did:human:david-johnson'
]);  // Parents become "advisors" but don't control

// Olivia can now do everything herself
const adultAction = await AnyAgent.execute({
  action: 'any_adult_action',
  requiredPassport: oliviaPassport.did,
  // No parent approval needed
});

Proof Test:

Create child Passport (age 5) with parent control
Verify parent approval required for all actions
Age 13: Limited autonomy, verify low-risk actions self-approved
Age 16: Moderate autonomy, verify part-time work permit
Age 18: Full autonomy, verify parents no longer controllers

Self-Employed & Small Business Owners (Tier 2-3)

Use Case	Identity Verification	Proof Test	Code Location
Freelance Consulting	Self-employed consultant	Tier 2: KYC (payment processing)	New use case needed
Licensed Contractor	Self-employed electrician	Tier 2: KYC + Tier 3: Contractor license	Existing (electrician)
Small Business Owner	LLC owner	Tier 2: KYC + Business license	New use case needed
Professional Services	Self-employed CPA	Tier 2: KYC + Tier 3: CPA license	New use case needed

Identity Flow (Self-Employed Consultant):

// Maya leaves corporate job to start consulting business

// 1. Maya creates Passport (starts as Tier 0)
const mayaPassport = await HumanApp.createPassport({
  displayName: 'Maya Rodriguez',
  verificationType: 'pseudonymous'
});

// 2. Maya retains past employment attestation from former employer
const pastEmployment = mayaPassport.credentials.find(
  c => c.type === 'EmploymentCredential' && c.issuer === 'did:org:acme-corp'
);
expect(pastEmployment.claims.role).toBe('Senior Marketing Director');
expect(pastEmployment.claims.yearsOfService).toBe(8);
expect(pastEmployment.status).toBe('completed');  // Ended, not revoked

// 3. Maya upgrades to KYC (required for payment processing)
const kycResult = await mayaPassport.upgradeToKYC({
  governmentId: mayaDriverLicense,
  selfie: mayaLiveSelfie
});

// 4. Maya registers business
const businessLicense = await CaliforniaSecretaryOfState.issueAttestation({
  subject: mayaPassport.did,
  type: 'BusinessLicenseCredential',
  businessName: 'Rodriguez Marketing Consulting LLC',
  businessStructure: 'LLC',
  licenseNumber: 'LLC-2026-12345',
  industry: 'Marketing & Advertising',
  owner: mayaPassport.did
});

// 5. Maya creates Org Passport for her business
const mayaBusinessPassport = await OrgApp.createPassport({
  displayName: 'Rodriguez Marketing Consulting',
  orgType: 'LLC',
  owners: [mayaPassport.did],  // Maya is sole owner
  businessLicense: businessLicense
});

// 6. Maya creates Workforce Cloud profile (self-employed)
const consultingProfile = await WorkforceCloud.createProfile({
  passportDid: mayaPassport.did,
  serviceType: 'consulting',
  capabilities: [
    'marketing/strategy',
    'marketing/digital-advertising',
    'marketing/brand-development'
  ],
  credentials: [
    pastEmployment,  // Proves 8 years senior experience
    businessLicense,  // Proves legitimate business
    kycResult  // Enables payment
  ],
  hourlyRate: 250,
  availability: 'full-time',
  businessEntity: mayaBusinessPassport.did
});

// 7. Client posts consulting project
const consultingProject = await WorkforceCloud.postTask({
  type: 'marketing_strategy',
  description: 'Develop go-to-market strategy for B2B SaaS',
  budget: '$10,000',
  duration: '4 weeks',
  requiredCapabilities: ['marketing/strategy'],
  requiredExperience: '5+ years'
});

// 8. HumanOS routes to Maya
const taskAssignment = await HumanOS.routeTask({
  task: consultingProject,
  // Finds Maya (has marketing/strategy capability)
  // Verifies: KYC (payment) + business license (legitimate) + past employment (experience)
  // Capability weight: 0.90 (8 years senior experience at Acme)
});

expect(taskAssignment.assignedTo).toBe(mayaPassport.did);
expect(taskAssignment.verificationChecks).toEqual({
  kycVerified: true,
  businessLicenseVerified: true,
  experienceVerified: true,
  capabilityWeight: 0.90
});

// 9. Maya completes project, builds reputation
const projectCompletion = await WorkforceCloud.completeTask({
  taskId: consultingProject.id,
  completedBy: mayaPassport.did,
  clientRating: 5,
  clientReview: 'Exceptional strategy work, ROI exceeded expectations',
  portfolio: consultingProjectArtifacts
});

// 10. Capability Graph updated from demonstrated work
await CapabilityGraph.updateFromWork({
  passportId: mayaPassport.did,
  taskId: consultingProject.id,
  rating: 5,
  capabilityDemonstrated: 'marketing/strategy',
  clientOrg: 'did:org:client-company',
  weightIncrease: +0.03  // Now 0.93 (experience + proven self-employed work)
});

Proof Test:

Create self-employed Maya's Passport
Verify KYC for payment processing
Register business, create Org Passport
Create Workforce Cloud consulting profile
Route project to Maya (capability match)
Complete project, verify capability weight increases

Identity Flow (AI Lab Safety Reviewer):

// Anthropic hiring AI safety researcher

// 1. Anthropic HR verifies Sarah during hiring
const sarahEmployeeRecord = await AnthropicOrg.createEmployeeRecord({
  legalName: 'Sarah Johnson',
  email: 'sarah.johnson@anthropic.com',
  role: 'Senior AI Safety Researcher',
  identityVerified: true  // Verified during hiring
});

// 2. Sarah creates Passport, links to Anthropic (< 2 min)
const sarahPassport = await HumanApp.createPassport({
  displayName: 'Sarah Johnson',
  verificationType: 'org'
});

await sarahPassport.linkToOrganization({
  linkingCode: 'ANTHROPIC-xyz789',
  email: 'sarah.johnson@anthropic.com'
});

// 3. Anthropic issues attestation with safety review capability
const employmentAttestation = await AnthropicOrg.issueAttestation({
  subject: sarahPassport.did,
  role: 'Senior AI Safety Researcher',
  capabilities: [
    'ai-safety/certified-reviewer',  // Can review medium-risk
    'ai-safety/senior-reviewer'      // Can review high-risk
  ],
  yearsExperience: 5,
  securityClearance: 'confidential'
});

// 4. High-risk model output triggers safety review
const safetyReview = await safetyReviewer.execute({
  modelOutput: potentiallyUnsafeOutput,
  riskLevel: 'high',
  // HumanOS escalates to Sarah (has ai-safety/senior-reviewer)
  // Verifies: Anthropic employee (trusted) + senior reviewer capability
});

// 5. Sarah approves/blocks, provenance logged
await Provenance.log({
  eventType: 'safety_review',
  reviewerDid: sarahPassport.did,
  reviewerOrg: 'did:org:anthropic',
  modelId: 'claude-3-opus',
  decision: 'approved_with_warning',
  reasoning: sarahReviewNotes
});

Proof Test:

Create Sarah's Passport (Anthropic employee)
Route high-risk output for safety review
Verify only senior safety reviewers get routed
Block output if no reviewer available in 5 min

NEW USE CASES IDENTIFIED (Need Documentation)

These workflows are implied by our architecture but not yet documented in KB 106:

Use Case	Identity Verification	Why Critical	Priority
IT Support Ticket Routing	Tier 1: Enterprise employee + IT capability	Route tickets to qualified engineers	High
HR Employee Onboarding	Tier 1: HR admin capability	Only HR can onboard new employees	High
Prescription Approval	Tier 3: DEA license + medical license	Legal requirement for controlled substances	High
Licensed Tutor Matching	Tier 2: KYC + Tier 3: Teaching credential	Parents want verified, licensed tutors	Medium
Wire Transfer Authorization	Tier 2: Bank KYC + signature authority	Regulatory requirement (BSA/AML)	Medium
Content Moderation	Tier 2: KYC (age 18+)	Age verification for exposure to harmful content	Medium
Real Estate Transaction	Tier 3: Real estate license + Tier 2: KYC	Legal requirement for licensed agents	Low
CPA Tax Filing	Tier 3: CPA license + Tier 2: KYC	Only CPAs can sign tax returns	Low

PROOF-OF-CONCEPT TEST MATRIX

Goal: Code runnable examples for EACH identity verification tier, integrate with existing agent workflows.

Test Suite Structure

// Test file: /tests/identity-verification/

describe('Identity Verification Integration Tests', () => {
  
  describe('Tier 1: Org-Verified (Enterprise Onboarding)', () => {
    it('should onboard employee with low friction', async () => {
      // 1. HR creates employee record
      const employeeRecord = await AcmeOrg.createEmployeeRecord({...});
      
      // 2. Employee creates Passport
      const passport = await createPassport({ verificationType: 'org' });
      
      // 3. Link to org via email verification
      await passport.linkToOrg({ code: employeeRecord.linkingCode });
      
      // 4. Org issues attestation
      const attestation = await AcmeOrg.issueAttestation({...});
      
      // 5. Verify employee can access workflows
      const invoiceApproval = await invoiceProcessor.execute({
        amount: 7000,
        requiredCapability: 'finance/invoice-approver'
      });
      
      expect(invoiceApproval.routedTo).toBe(passport.did);
      expect(invoiceApproval.time).toBeLessThan(120000); // < 2 minutes
    });
    
    it('should prevent duplicate employee Passports', async () => {
      // Employee tries to create second Passport
      await expect(
        createPassport({ displayName: 'Same Employee', biometric: sameFingerprint })
      ).rejects.toThrow('Passport already exists for this biometric');
    });
    
    it('should revoke access when employee leaves', async () => {
      await AcmeOrg.revokeAttestation({ subject: employeePassport.did });
      
      // Employee can no longer approve invoices
      await expect(
        invoiceProcessor.execute({ requiredCapability: 'finance/invoice-approver' })
      ).rejects.toThrow('No valid attestation');
    });
  });
  
  describe('Tier 2: KYC-Verified (Independent Contractors)', () => {
    it('should verify government ID + selfie', async () => {
      const passport = await createPassport({ verificationType: 'kyc' });
      
      const kycResult = await Onfido.verify({
        governmentId: driverLicensePhoto,
        selfie: liveSelfieVideo
      });
      
      expect(kycResult.status).toBe('clear');
      expect(kycResult.facialMatch).toBeGreaterThan(0.90);
    });
    
    it('should enable Workforce Cloud for KYC-verified users', async () => {
      // User can join Workforce Cloud after KYC
      const workforceProfile = await WorkforceCloud.createProfile({
        passportDid: kycVerifiedPassport.did
      });
      
      expect(workforceProfile.verificationTier).toBe('tier_2_kyc');
      expect(workforceProfile.canReceivePayment).toBe(true);
    });
  });
  
  describe('Tier 3: Credential-Verified (Licensed Professionals)', () => {
    it('should verify medical license from state board', async () => {
      const passport = await createPassport({ verificationType: 'org' });
      
      // Request license verification
      const licenseAttestation = await CaliforniaMedicalBoard.verify({
        licenseNumber: 'A-12345',
        holderName: 'Dr. Sarah Patel',
        passportDid: passport.did
      });
      
      expect(licenseAttestation.status).toBe('active');
      expect(licenseAttestation.expirationDate).toBeAfter(new Date());
    });
    
    it('should route medical cases only to licensed physicians', async () => {
      const criticalCase = await medicalTriage.execute({
        severity: 'critical',
        symptoms: 'chest pain, shortness of breath'
      });
      
      // Only physicians with active licenses get routed
      const assignedPhysician = await getPassport(criticalCase.assignedTo);
      const medicalLicense = assignedPhysician.credentials.find(
        c => c.type === 'ProfessionalLicenseCredential'
      );
      
      expect(medicalLicense).toBeDefined();
      expect(medicalLicense.status).toBe('active');
      expect(medicalLicense.licenseType).toContain('physician');
    });
    
    it('should reject routing if license is expired', async () => {
      // Physician's license expired yesterday
      await CaliforniaMedicalBoard.updateLicenseStatus({
        licenseNumber: 'A-12345',
        status: 'expired',
        expirationDate: yesterday
      });
      
      // Medical case should NOT route to this physician
      const criticalCase = await medicalTriage.execute({ severity: 'critical' });
      
      expect(criticalCase.assignedTo).not.toBe(expiredLicensePhysician.did);
    });
  });
  
  describe('Multi-Tier Workflows (Workforce Cloud Electrician)', () => {
    it('should require KYC + license for electrical work', async () => {
      // 1. Create Passport with KYC (Tier 2)
      const rickPassport = await createPassport({ verificationType: 'kyc' });
      await Onfido.verify({ governmentId: rickDriverLicense, selfie: rickSelfie });
      
      // 2. Add contractor license (Tier 3)
      const licenseAttestation = await CaliforniaContractorsBoard.verify({
        licenseNumber: 'C10-123456',
        passportDid: rickPassport.did
      });
      
      // 3. Post electrical job
      const electricalJob = await WorkforceCloud.postTask({
        type: 'electrical_panel_upgrade',
        requiredCertifications: ['contractors_license_c10']
      });
      
      // 4. Verify routing
      const assignment = await HumanOS.routeTask({ task: electricalJob });
      
      expect(assignment.assignedTo).toBe(rickPassport.did);
      expect(assignment.verificationChecks).toEqual({
        kycVerified: true,
        licenseVerified: true,
        licenseActive: true
      });
    });
  });
  
  describe('Cross-Workflow Identity Reuse', () => {
    it('should reuse identity across multiple orgs', async () => {
      // Rick works for Acme (Tier 1)
      const acmeAttestation = await AcmeOrg.issueAttestation({
        subject: rickPassport.did,
        role: 'Software Engineer'
      });
      
      // Rick also freelances (Tier 2 KYC already done)
      const workforceProfile = await WorkforceCloud.createProfile({
        passportDid: rickPassport.did
      });
      
      // Rick starts contracting for Globex (Tier 1)
      const globexAttestation = await GlobexOrg.issueAttestation({
        subject: rickPassport.did,
        role: 'Contract Developer'
      });
      
      // Same Passport, multiple attestations
      expect(rickPassport.credentials).toHaveLength(3); // Acme + KYC + Globex
      expect(rickPassport.did).toBe(sameDidAcrossAllOrgs);
    });
  });
});

IMPLEMENTATION PRIORITY

Phase 1: Core Identity Flows (Week 1-2)

Tier 1: Org-Verified (PRIMARY PATH)
- Enterprise employee onboarding
- Invoice approval workflow integration
- Test: Onboard 10 test employees, route invoices
Tier 0: Pseudonymous (FREE TIER)
- Personal Companion usage
- Test: Create pseudonymous Passport, use Companion

Phase 2: Independent Workers (Week 3-4)

Tier 2: KYC-Verified
- Independent contractor onboarding
- Workforce Cloud payment processing
- Test: KYC verification, join Workforce Cloud
Tier 3: Credential-Verified
- Licensed professional verification
- Medical license → physician capability
- Test: Verify medical license, route critical medical case

Phase 3: Complete Matrix (Month 2)

Multi-Tier Workflows
- Electrician: KYC + contractor license
- Test: Complete Workforce Cloud electrician flow
Cross-Org Identity Reuse
- Same Passport, multiple employers
- Test: Rick works for Acme + freelances + joins Globex

This gives you the complete identity verification architecture mapped to every workflow, GeekWarrior. Each use case now has clear identity requirements, and we know exactly which proof tests to code.

Delegation Hierarchy (Chain of Trust)

All authority flows downward only:

Human Passport (sovereign)
        ↓
Org Passport (scoped administrative authority)
        ↓
Agent Passport (bounded execution authority)

Forbidden patterns:

❌ Reverse delegation (Agent → Human)
❌ Lateral authority (Agent → Agent without parent approval)
❌ Autonomous identity creation (Agent minting Agents)
❌ Scope escalation (Agent exceeding parent's delegation)

Technical Enforcement:

Delegation certificates form a verifiable chain
Each certificate is signed by parent's private key
HumanOS validates chain before allowing action
Ledger anchors record all delegation events

Self-Hosted Deployment Invariants

In fully self-hosted deployments, these constraints cannot be violated:

✅ Permitted Operations

Self-hosted infrastructure MAY:

Verify Passport signatures (cryptographic validation)
Issue org-scoped attestations (within namespace)
Host policy engines and agent runtimes
Custody Org and Agent keys under policy constraints
Enforce escalation rules and safety boundaries

❌ Explicitly Forbidden Operations

Self-hosted infrastructure MUST NEVER:

Mint Human Passports server-side (device-only operation)
Create admin-controlled "human" identities
Hold or access human private keys
Override human revocation decisions
Perform identity recovery without human authorization
Silently create or modify identity records

Compliance Requirement:

Violation of these constraints renders the deployment non-compliant with the HUMAN Protocol. Such deployments:

Cannot interoperate with HUMAN Cloud
Cannot participate in the distributed ledger
Cannot issue verifiable attestations recognized by other deployments
Lose certification and support

Threat Model & Breach Blast Radius Analysis

Understanding what happens when different system components are compromised:

Human Device Compromise

Attack: Attacker gains access to user's device (malware, physical theft)

Blast Radius:

Affects only that human's identity
Can impersonate that one user
Cannot mint new identities
Cannot impersonate other users

Mitigation:

Biometric/passkey protection (stolen device ≠ stolen identity)
Device key revocation by user (from another device)
Capability Graph shows anomalous behavior
HumanOS can detect and block suspicious actions

Org Infrastructure Compromise

Attack: Attacker compromises enterprise's self-hosted HUMAN deployment

Blast Radius:

Can issue fake org-scoped attestations (e.g., "Alice works here")
Attestations are:
- Namespaced to that org (don't affect other orgs)
- Traceable (signed with org's key, ledger-anchored)
- Revocable (org key can be revoked via distributed ledger)
Cannot mint Human Passports
Cannot impersonate humans
Cannot access human private keys
Cannot modify Capability Graph for humans outside org

Mitigation:

Org key revocation via ledger broadcast
Attestations issued during compromise period are invalidated
Audit trail reveals all actions taken during compromise window
Other orgs' attestations remain unaffected (namespace isolation)

Agent Runtime Compromise

Attack: Attacker compromises agent execution environment

Blast Radius:

Limited to agent's delegated scope
Limited to agent's time window (expiry enforced)
All actions fully attributable via ledger provenance
Cannot exceed delegation bounds (cryptographically enforced)
Cannot mint identities
Cannot access parent's private key

Mitigation:

Agent key revocation by parent
Delegation expiry (time-bounded by design)
HumanOS safety boundaries prevent out-of-scope actions
Provenance log reveals all compromised actions

HUMAN Cloud Compromise

Attack: Attacker gains control of HUMAN's hosted infrastructure

Blast Radius:

Cannot mint Human Passports (device-only operation)
Cannot access human private keys (never stored server-side)
Cannot impersonate any actor (no private keys)
Cannot modify ledger history (distributed, immutable)
Can disrupt service availability (DoS)
Can attempt to issue fake attestations (rejected by verification)

Mitigation:

Human keys on devices (zero server-side exposure)
Ledger distribution (no single point of truth)
Self-hosted customers unaffected (independent deployments)
Attestation verification fails (signatures invalid without real keys)

Open Source & Forking Safety

Q: Doesn't open source allow anyone to fork HUMAN and bypass these rules?

A: No. Trust derives from cryptographic verification, not code control.

Why Forking Can't Break Identity Sovereignty

Forking code ≠ Minting authority
- Code defines verification rules, not identity creation
- Even modified code must verify cryptographic signatures
- Invalid signatures are rejected by protocol
Protocol compliance is mathematically provable
- Forked implementations must still verify Ed25519 signatures
- DIDs must resolve to valid public keys
- Delegation chains must have valid parent signatures
- Non-compliant forks cannot interoperate
Network effects enforce standards
- Ledger nodes reject non-compliant attestations
- Enterprise deployments verify protocol compliance
- Humans control which implementations they trust (via device choice)
Self-hosted doesn't mean sovereign
- Running HUMAN code doesn't grant identity creation power
- Infrastructure can verify, not mint
- Human devices remain the only source of human identity

Example:

// Even in a malicious fork, this doesn't work:
async function evilMintHumanPassport() {
  const fakePassport = {
    did: 'did:human:evil-123',
    publicKey: generateKeyPair().publicKey,
    // ... other fields
  };
  
  // ❌ This fails because:
  // 1. No private key (can't sign anything)
  // 2. DID not registered on ledger
  // 3. No device attestation
  // 4. Cannot prove possession of Secure Enclave key
  // 5. Other deployments reject invalid signatures
  
  return fakePassport; // Useless - cannot prove identity
}

Result: Open source increases auditability without compromising security. Modified code can be detected and rejected by the network.

Verification vs Authority

Running Passport software or hosting verification logic does not grant identity authority.

Capability	Self-Hosted Infra	HUMAN Cloud	Human Device
Verify signatures	✅ Yes	✅ Yes	✅ Yes
Validate attestations	✅ Yes	✅ Yes	✅ Yes
Enforce policy	✅ Yes	✅ Yes	✅ Yes
Issue org attestations	✅ Yes (own org)	✅ Yes (own org)	❌ No
Mint Human Passports	❌ Never	❌ Never	✅ Only here
Access human private keys	❌ Never	❌ Never	✅ Only here
Override human decisions	❌ Never	❌ Never	✅ Human control

Principle: Infrastructure components are verifiers and coordinators, not identity authorities.

Normative Language

The following terms are used as defined in RFC 2119:

MUST - Absolute requirement
MUST NOT - Absolute prohibition
MAY - Optional capability
SHALL - Equivalent to MUST (regulatory contexts)

All capitalized requirements in this document are normative and must be enforced in any HUMAN Protocol implementation.

Final Statement

Identity within HUMAN is a human right, not a service.

Self-hosting increases deployment flexibility without increasing identity risk because sovereignty is cryptographically enforced, not operationally trusted.

No system—whether HUMAN Cloud, self-hosted infrastructure, or any fork—may ever stand between a human and their identity.

This is the architectural guarantee that makes HUMAN trustworthy at global scale.

PASSPORT USE CASES: REAL-WORLD WORKFLOWS

Purpose: Concrete examples showing how different entities mint and use Passports through their lifecycle. These validate the Passport architecture and show integration with agent workflows.

Use Case 1: Human Mints First Passport (Onboarding)

Scenario: Alice downloads HUMAN app, creates her first Passport

Time: 2 minutes
Entities: Human (Alice)
Process: Device-rooted identity minting

Step-by-Step Flow

// Client-side (Alice's iPhone - iOS Secure Enclave)

// 1. User opens HUMAN app, starts onboarding
const onboardingFlow = await HumanApp.startOnboarding();

// 2. App generates keypair in Secure Enclave (keys NEVER leave device)
const keypair = await SecureEnclave.generateKeyPair({
  algorithm: 'ed25519',
  purpose: 'passport-identity',
  biometric: true  // Require Face ID for signing
});

// 3. App generates DID (local, no server call yet)
const did = `did:human:${uuidv4()}`;

// 4. User provides display name
const displayName = await prompt('What should we call you?');
// Alice enters: "Alice Chen"

// 5. Device attestation (proves keys in Secure Enclave)
const deviceAttestation = await SecureEnclave.createAttestation({
  publicKey: keypair.publicKey,
  deviceId: await getDeviceId(),
  attestationType: 'apple-app-attest'  // iOS App Attest
});

// 6. Create Passport container (local)
const passport: PassportContainer = {
  did,
  displayName,
  kind: PassportKind.Human,  // Sovereign identity
  publicKey: keypair.publicKey,
  deviceAttestation,
  createdAt: new Date(),
  vault: {
    provider: 'local',  // Free tier: local-only
    config: { storage: 'indexeddb' }
  }
};

// 7. Register with HUMAN (for discoverability, optional)
await HumanAPI.registerPassport({
  did,
  publicKey: keypair.publicKey,
  deviceAttestation,
  signature: await keypair.sign({ did, publicKey: keypair.publicKey })
});

// 8. Store locally (encrypted)
await SecureStorage.store('passport', passport);

console.log(`✅ Passport created: ${did}`);
console.log(`🔐 Keys secured in: Secure Enclave`);
console.log(`💾 Data stored in: Local device`);

What Just Happened

Step	What	Where	Who Controls
Keypair generation	Ed25519 keys created	iOS Secure Enclave	Alice (biometric required)
DID creation	Unique identifier generated	Alice's device	Alice
Device attestation	Proves keys are hardware-bound	Apple App Attest	Apple (cryptographic proof)
Registration	Makes DID discoverable	HUMAN registry	Alice (can deregister anytime)
Storage	Passport data saved	Alice's device	Alice

Critical Security Properties:

✅ Private key NEVER leaves Secure Enclave
✅ HUMAN never sees private key
✅ Only Alice can sign (requires Face ID)
✅ Device attestation proves hardware binding
✅ Alice can use Passport offline (local-first)

Use Case 2: Org Mints Passport (Company Setup)

Scenario: Acme Corp becomes a HUMAN organization

Time: 30 minutes
Entities: Legal entity (Acme Corp), Founding humans (CEO, CTO)
Process: Multi-sig genesis ceremony

Step-by-Step Flow

// 1. CEO initiates org creation
const orgCreationRequest = await HumanAPI.initiateOrgCreation({
  legalName: 'Acme Corporation',
  jurisdiction: 'Delaware, USA',
  taxId: '12-3456789',
  domain: 'acme.com',
  founders: [
    { did: 'did:human:ceo-alice', role: 'ceo' },
    { did: 'did:human:cto-bob', role: 'cto' }
  ]
});

// 2. Verify domain ownership (prove control of acme.com)
const domainProof = await proveDomainOwnership({
  domain: 'acme.com',
  method: 'dns-txt',  // Add TXT record to DNS
  challenge: orgCreationRequest.domainChallenge
});

// 3. Genesis ceremony (multi-sig)
// Both CEO and CTO must sign to create org
const ceoSignature = await AlicePassport.sign({
  action: 'org_genesis',
  orgName: 'Acme Corporation',
  taxId: '12-3456789',
  role: 'ceo'
});

const ctoSignature = await BobPassport.sign({
  action: 'org_genesis',
  orgName: 'Acme Corporation',
  taxId: '12-3456789',
  role: 'cto'
});

// 4. Generate org DID and keys
const orgDid = `did:org:acme-corp`;
const orgKeyPair = await generateOrgKeyPair({
  algorithm: 'ed25519',
  storage: 'hsm',  // Enterprise: use HSM
  multiSig: {
    threshold: 2,  // Requires 2 of 3 signatures
    signers: [ceoSignature.did, ctoSignature.did, 'did:human:cfo-carol']
  }
});

// 5. Create Org Passport
const orgPassport: OrgPassport = {
  did: orgDid,
  kind: PassportKind.Org,
  legalEntity: {
    name: 'Acme Corporation',
    jurisdiction: 'Delaware, USA',
    taxId: '12-3456789',
    domain: 'acme.com',
    domainProof
  },
  founders: [
    { did: 'did:human:ceo-alice', role: 'ceo', signedAt: new Date() },
    { did: 'did:human:cto-bob', role: 'cto', signedAt: new Date() }
  ],
  publicKey: orgKeyPair.publicKey,
  createdAt: new Date(),
  genesisSignatures: [ceoSignature, ctoSignature],
  vault: {
    provider: 'aws',  // Enterprise: AWS S3 + DynamoDB
    config: {
      region: 'us-east-1',
      bucket: 'acme-human-vault',
      kmsKeyId: 'arn:aws:kms:...'
    }
  }
};

// 6. Anchor to ledger (immutable proof of org creation)
const ledgerAnchor = await Ledger.anchor({
  eventType: 'org_genesis',
  orgDid,
  founders: orgPassport.founders,
  genesisSignatures: orgPassport.genesisSignatures,
  timestamp: new Date()
});

// 7. Register org in Trust Registry
await TrustRegistry.register({
  did: orgDid,
  name: 'Acme Corporation',
  type: 'employer',
  verifiedBy: 'HUMAN',
  domainControl: 'acme.com',
  legalRegistration: 'Delaware Secretary of State #5678901',
  status: 'active'
});

console.log(`✅ Org Passport created: ${orgDid}`);
console.log(`🏢 Legal entity: Acme Corporation`);
console.log(`👥 Founders: CEO (Alice), CTO (Bob)`);
console.log(`🔗 Ledger anchor: ${ledgerAnchor}`);
console.log(`🌐 Domain verified: acme.com`);

What Just Happened

Step	What	Why	Who Controls
Domain proof	Proves ownership of acme.com	Prevents impersonation	Acme (via DNS)
Multi-sig genesis	Requires 2+ founders	No single point of control	CEO + CTO
Org DID creation	Unique org identifier	Namespace for attestations	Acme
Ledger anchor	Immutable creation proof	Can't backdate org	Public ledger
Trust registry	Verified credential issuer	Others trust Acme's attestations	HUMAN + Acme

Authority Model:

✅ Org can issue employment attestations (within namespace)
✅ Org can delegate to agents (bounded authority)
❌ Org CANNOT mint Human Passports
❌ Org CANNOT override human decisions

Use Case 3: Agent Mints Passport (Delegation-Bound)

Scenario: Acme Corp creates AI agent for invoice processing

Time: 5 minutes
Entities: Org (Acme Corp), Agent (Invoice Processor)
Process: Delegated identity creation

Step-by-Step Flow

// 1. Acme CFO (Carol) initiates agent creation
const agentCreationRequest = await AcmeOrgPassport.createAgent({
  name: 'Invoice Processor',
  purpose: 'Automated invoice approval up to $5,000',
  capabilities: ['finance/invoice/process'],
  delegationScope: {
    actions: ['read:invoices', 'approve:invoices'],
    constraints: {
      maxAmount: 5000,  // Can't approve over $5k
      requiresHumanReview: {
        conditions: ['amount > 5000', 'vendor_first_time']
      }
    },
    expiresAt: new Date('2027-01-01')  // 1 year delegation
  },
  createdBy: 'did:human:cfo-carol'
});

// 2. Generate agent DID and keys
const agentDid = `did:agent:${uuidv4()}`;
const agentKeyPair = await generateAgentKeyPair({
  algorithm: 'ed25519',
  storage: 'managed',  // HUMAN-managed keys (agent doesn't need device)
  rotationPolicy: {
    interval: '90 days',
    automatic: true
  }
});

// 3. Create delegation object (what agent can do)
const delegation: Delegation = {
  id: `deleg_${uuidv4()}`,
  delegator: 'did:org:acme-corp',  // Acme delegates
  delegate: agentDid,  // To this agent
  scopes: ['read:invoices', 'approve:invoices'],
  constraints: {
    maxAmount: 5000,
    requiresHumanReview: ['amount > 5000', 'vendor_first_time']
  },
  grantedAt: new Date(),
  expiresAt: new Date('2027-01-01'),
  revocable: true,
  signature: await AcmeOrgPassport.sign({
    delegation: { delegator: 'did:org:acme-corp', delegate: agentDid, scopes: [...] }
  })
};

// 4. Create Agent Passport
const agentPassport: AgentPassport = {
  did: agentDid,
  kind: PassportKind.Agent,
  name: 'Invoice Processor',
  purpose: 'Automated invoice approval up to $5,000',
  principal: 'did:org:acme-corp',  // Acts on behalf of Acme
  publicKey: agentKeyPair.publicKey,
  delegation,  // Bounded authority
  capabilities: ['finance/invoice/process'],
  createdAt: new Date(),
  createdBy: 'did:human:cfo-carol',
  vault: {
    provider: 'aws',  // Uses Acme's vault
    config: { bucket: 'acme-human-vault', namespace: 'agents/invoice-processor' }
  }
};

// 5. Register agent
await AgentRegistry.register({
  agentDid,
  principal: 'did:org:acme-corp',
  delegation,
  capabilities: ['finance/invoice/process']
});

// 6. Log provenance
await Provenance.log({
  eventType: 'agent_creation',
  agentDid,
  principal: 'did:org:acme-corp',
  createdBy: 'did:human:cfo-carol',
  delegation: delegation.id,
  ledgerAnchor: await Ledger.anchor({ eventType: 'agent_creation', agentDid, delegation })
});

console.log(`✅ Agent Passport created: ${agentDid}`);
console.log(`🏢 Principal: Acme Corporation`);
console.log(`🎯 Capabilities: finance/invoice/process`);
console.log(`💰 Max approval: $5,000`);
console.log(`👤 Created by: Carol (CFO)`);
console.log(`📅 Expires: 2027-01-01`);

What Just Happened

Step	What	Why	Authority Source
Agent DID creation	Unique agent identifier	Traceable in provenance	Acme Corp
Delegation object	Defines what agent can do	Bounded authority	Acme Corp (cryptographically signed)
Constraints	Max $5k, human review rules	Safety boundaries	Carol (CFO)
Registration	Agent discoverable	Capability routing	HUMAN registry
Provenance log	Immutable creation record	Audit trail	Ledger

Critical Constraints:

✅ Agent can approve invoices up to $5,000
✅ Agent MUST escalate invoices > $5,000 to human
✅ Agent MUST escalate first-time vendors to human
✅ Delegation expires automatically (2027-01-01)
✅ Acme can revoke delegation anytime
❌ Agent CANNOT mint other agents (no autonomous creation)
❌ Agent CANNOT exceed delegation scope

Use Case 4: Passport-Based Delegation (Vacation Coverage)

Scenario: Maya delegates Companion access to Jamie while on vacation

Time: 2 minutes
Entities: Human (Maya), Human (Jamie), Agent (Companion)
Process: Time-bounded, scope-limited human-to-human delegation
Reference: PRD Section 3.1.1 (Delegation Use Cases)

Step-by-Step Flow

// 1. Maya creates delegation (from her HUMAN app)
const delegation = await MayaPassport.delegate({
  delegate: 'did:human:jamie',  // Jamie receives delegation
  scopes: [
    'read:calendar',
    'create:calendar_events',
    'read:emails',
    'send:emails:non_financial',  // Can send non-financial emails
    'approve:expenses:under_1000'  // Can approve up to $1k
  ],
  constraints: {
    // Financial limits
    maxExpenseApproval: 1000,
    cannotApprove: ['vendor_contracts', 'hiring_decisions'],
    
    // Communication limits
    cannotEmail: ['board@acme.com', 'investors@*'],
    
    // Time limits
    startDate: new Date('2026-12-15'),
    endDate: new Date('2026-12-29'),  // 2-week vacation
    
    // Notification rules
    notifyMayaOn: ['expense > 500', 'urgent_email', 'calendar_conflict']
  },
  reason: 'Vacation coverage - December holidays',
  revocable: true
});

// 2. Maya signs delegation
const signedDelegation: SignedDelegation = {
  ...delegation,
  signature: await MayaPassport.sign(delegation),
  ledgerAnchor: await Ledger.anchor({
    eventType: 'delegation_created',
    delegator: 'did:human:maya',
    delegate: 'did:human:jamie',
    scopes: delegation.scopes,
    constraints: delegation.constraints
  })
};

// 3. Jamie accepts delegation
await JamiePassport.acceptDelegation({
  delegationId: signedDelegation.id,
  signature: await JamiePassport.sign({
    action: 'accept_delegation',
    delegationId: signedDelegation.id
  })
});

// 4. Companion agent now recognizes Jamie's temporary authority
// When Jamie talks to Companion:
const jamieSession = await Companion.startSession({
  userDid: 'did:human:jamie',
  activeDelegations: await getDelegations('did:human:jamie')
});

// Jamie: "Approve this $800 expense from AWS"
const expenseApproval = await Companion.handleRequest({
  user: 'did:human:jamie',
  request: 'approve_expense',
  context: {
    vendor: 'AWS',
    amount: 800,
    category: 'infrastructure'
  }
});

// Companion checks delegation
const delegationCheck = await validateDelegation({
  actor: 'did:human:jamie',
  action: 'approve:expenses',
  amount: 800,
  delegation: signedDelegation
});

if (delegationCheck.allowed) {
  // ✅ Within delegation scope ($800 < $1,000 limit)
  await approveExpense({
    amount: 800,
    approvedBy: 'did:human:jamie',
    onBehalfOf: 'did:human:maya',
    delegationId: signedDelegation.id
  });
  
  // Log provenance
  await Provenance.log({
    eventType: 'expense_approval',
    actor: 'did:human:jamie',
    principal: 'did:human:maya',
    delegation: signedDelegation.id,
    amount: 800,
    ledgerAnchor: await Ledger.anchor(...)
  });
  
  return "✅ Approved $800 AWS expense (via Maya's delegation)";
}

// Jamie: "Approve this $1,500 expense from consultant"
const expenseApproval2 = await Companion.handleRequest({
  user: 'did:human:jamie',
  request: 'approve_expense',
  context: {
    vendor: 'Consultant Inc',
    amount: 1500,
    category: 'professional_services'
  }
});

// Companion checks delegation
const delegationCheck2 = await validateDelegation({
  actor: 'did:human:jamie',
  action: 'approve:expenses',
  amount: 1500,
  delegation: signedDelegation
});

if (!delegationCheck2.allowed) {
  // ❌ Exceeds delegation limit ($1,500 > $1,000)
  return `❌ Cannot approve $1,500 expense.

Your delegation allows:
- Expenses up to $1,000 ✅
- This expense: $1,500 ❌

Options:
1. Wait for Maya to return (Dec 29)
2. Ask Maya to increase limit
3. Escalate to Maya's manager`;
}

// 5. Auto-revocation when Maya returns
// On Dec 29, 2026 at 23:59:59:
await automaticRevocation({
  delegationId: signedDelegation.id,
  reason: 'Expired (end date reached)',
  revokedAt: new Date('2026-12-29T23:59:59Z')
});

console.log(`✅ Delegation automatically revoked`);
console.log(`Jamie can no longer act on Maya's behalf`);

What Just Happened

Maya's Action	Jamie's Authority	Companion's Response
Delegates calendar, email, expense approval	Can read Maya's calendar	Shows Maya's calendar to Jamie
Constrains $1k expense limit	✅ Approve $800 expense	"Approved (via Maya's delegation)"
Constrains $1k expense limit	❌ Try to approve $1,500	"Outside delegation scope"
Sets Dec 15-29 timeframe	Dec 30: Try to use delegation	"Delegation expired"
Revokes (if needed)	Instant revocation	"Delegation revoked by Maya"

Real-World Benefits:

✅ Maya can actually disconnect (delegation handles routine work)
✅ Jamie has clear boundaries (can't overstep)
✅ Automatic expiry (no manual cleanup)
✅ Audit trail (who approved what, under whose authority)
✅ Emergency revocation (Maya can pull delegation from her phone)

Use Case 5: Passport in Agent Workflow (Invoice Processing)

Scenario: Invoice arrives → Agent processes → Human approves (if needed)

Time: 30 seconds (automated)
Entities: Agent (Invoice Processor), Human (CFO Carol), Org (Acme)
Process: Agent uses delegation, human uses capability
Cross-Reference: KB 106 (Use Case Library - Invoice Processing)

Integration with Agent Workflow

import { handler } from '@human/agent-sdk';

export const invoiceProcessor = handler({
  id: 'invoice-processor',
  version: '1.0.0',
  capabilities: ['finance/invoice/process'],
  
  // THIS AGENT HAS A PASSPORT
  passportDid: 'did:agent:invoice-processor-abc123',
  
  async execute(ctx) {
    // 1. Validate agent's delegation
    const delegationCheck = await ctx.passport.validateDelegation({
      action: 'process_invoice',
      principal: 'did:org:acme-corp'
    });
    
    if (!delegationCheck.valid) {
      throw new UnauthorizedError(`Delegation invalid: ${delegationCheck.reason}`);
    }
    
    // 2. Extract invoice data (AI work)
    const { pdfUrl } = ctx.input;
    const pdfText = await ctx.call.muscle('pdf-extractor', { url: pdfUrl });
    const extraction = await ctx.llm.complete({
      model: 'gpt-4',
      messages: [
        { role: 'system', content: 'Extract invoice data as JSON' },
        { role: 'user', content: pdfText }
      ],
      responseFormat: 'json'
    });
    
    const invoice = JSON.parse(extraction.text);
    
    // 3. Check delegation constraints
    if (invoice.amount > ctx.passport.delegation.constraints.maxAmount) {
      // ❌ Exceeds agent's authority ($7,500 > $5,000 limit)
      
      // Must escalate to human with appropriate capability
      const approval = await ctx.oversight.approve({
        question: `Approve invoice from ${invoice.vendor} for $${invoice.amount}?`,
        context: {
          invoice,
          reason: 'Amount exceeds agent delegation limit',
          agentDelegation: ctx.passport.delegation.constraints.maxAmount
        },
        requiredCapability: 'finance/invoice-approver',  // Need this capability
        // HumanOS routes to qualified humans (Carol has this capability)
      });
      
      if (!approval.approved) {
        // Log rejection
        await ctx.provenance.log({
          eventType: 'invoice_rejected',
          agentDid: ctx.passport.did,
          humanReviewer: approval.reviewerDid,  // Carol's DID
          reason: approval.reason,
          amount: invoice.amount
        });
        
        return { status: 'rejected', reason: approval.reason };
      }
      
      // Log approval (with human + agent provenance)
      await ctx.provenance.log({
        eventType: 'invoice_approved',
        agentDid: ctx.passport.did,  // Agent proposed
        humanApprover: approval.reviewerDid,  // Carol approved
        principal: 'did:org:acme-corp',  // On behalf of Acme
        amount: invoice.amount,
        delegation: ctx.passport.delegation.id
      });
    } else {
      // ✅ Within agent's authority ($2,500 < $5,000 limit)
      
      // Agent can auto-approve
      await ctx.provenance.log({
        eventType: 'invoice_auto_approved',
        agentDid: ctx.passport.did,
        principal: 'did:org:acme-corp',
        amount: invoice.amount,
        reason: 'Within agent delegation limit',
        delegation: ctx.passport.delegation.id
      });
    }
    
    // 4. Process invoice
    await ctx.call.muscle('quickbooks-create-bill', {
      vendor: invoice.vendor,
      amount: invoice.amount,
      dueDate: invoice.dueDate
    });
    
    return {
      status: 'processed',
      amount: invoice.amount,
      approvedBy: invoice.amount > 5000 ? 'human' : 'agent',
      passportProof: {
        agentDid: ctx.passport.did,
        delegation: ctx.passport.delegation.id,
        principal: 'did:org:acme-corp'
      }
    };
  }
});

Passport Checks in Workflow

Stage	Passport Check	What Happens
Agent starts	Validate delegation	✅ Agent has valid delegation from Acme
Check amount	Compare to constraints	Invoice $2,500 < $5,000 limit → Auto-approve
Check amount	Compare to constraints	Invoice $7,500 > $5,000 limit → Escalate
Human approval	Check capability	Carol has `finance/invoice-approver` → Routes to Carol
Provenance log	Record DIDs	Agent DID + Human DID + Delegation ID = audit trail

What Passports Enable:

✅ Agent proves authority (delegation from Acme)
✅ Human proves capability (Carol is certified approver)
✅ Clear responsibility chain (Agent proposed → Carol approved → Acme principal)
✅ Audit trail (who did what, under what authority)
✅ Automatic enforcement (agent can't exceed delegation)

Use Case 6: Multi-Device Passport Sync

Scenario: Alice uses Passport on iPhone, iPad, and Mac

Time: 1 minute per device
Entities: Human (Alice), 3 devices
Process: Secure multi-device key sync

Step-by-Step Flow

// Device 1: iPhone (Primary)
// Alice already has Passport on iPhone (from Use Case 1)

// Device 2: iPad (Secondary)
// 1. Alice opens HUMAN app on iPad, signs in
const ipadOnboarding = await HumanApp.addDevice({
  primaryDevice: 'iphone',
  newDevice: 'ipad'
});

// 2. iPhone shows QR code
const qrCode = await iPhone.generateDevicePairingQR({
  challenge: 'add-device-ipad',
  expiresIn: 300  // 5 minutes
});

// 3. iPad scans QR code
const scannedData = await iPad.scanQR(qrCode);

// 4. iPhone prompts: "Add iPad to your Passport?"
const confirmation = await iPhone.confirmDeviceAddition({
  deviceType: 'ipad',
  deviceId: scannedData.deviceId,
  requireBiometric: true  // Face ID on iPhone
});

if (confirmation.approved) {
  // 5. Generate device-specific key on iPad
  const iPadKeyPair = await iPad.SecureEnclave.generateKeyPair({
    algorithm: 'ed25519',
    purpose: 'passport-device-key',
    linkedTo: AlicePassport.did
  });
  
  // 6. iPhone signs device attestation
  const deviceAttestation = await iPhone.signDeviceAttestation({
    newDeviceDid: iPadKeyPair.publicKey,
    newDeviceType: 'ipad',
    addedBy: AlicePassport.did,
    addedAt: new Date()
  });
  
  // 7. Update Passport (add iPad as authorized device)
  await AlicePassport.addDevice({
    deviceId: 'ipad-alice-2',
    publicKey: iPadKeyPair.publicKey,
    deviceAttestation,
    addedAt: new Date(),
    status: 'active'
  });
  
  // 8. Sync Passport to iPad (encrypted)
  await syncPassportToDevice({
    passport: AlicePassport,
    targetDevice: 'ipad',
    encryptionKey: iPadKeyPair.publicKey
  });
  
  console.log(`✅ iPad added to Alice's Passport`);
  console.log(`🔐 Each device has own keys`);
  console.log(`🔄 Passport data synced (encrypted)`);
}

// Device 3: MacBook (Tertiary)
// Same process as iPad

Device Architecture

Alice's Passport (did:human:alice-123)
├── Device 1: iPhone (Primary)
│   ├── Keys: Secure Enclave (ed25519)
│   ├── Role: Primary signing device
│   └── Can: Add/remove other devices
├── Device 2: iPad (Secondary)
│   ├── Keys: Secure Enclave (separate keypair)
│   ├── Role: Secondary signing device
│   └── Can: Sign, but not add devices
└── Device 3: MacBook (Tertiary)
    ├── Keys: TPM (separate keypair)
    ├── Role: Tertiary signing device
    └── Can: Sign, but not add devices

Security Properties:

✅ Each device has own keypair (compromise one device ≠ compromise all)
✅ Primary device can revoke secondary devices
✅ All devices cryptographically linked to Alice's DID
✅ Passport data synced (encrypted in transit and at rest)
✅ Device addition requires biometric on primary device

SUMMARY: PASSPORT USE CASES

Six Complete Workflows

✅ Human mints Passport - Device-rooted identity (2 min)
✅ Org mints Passport - Multi-sig genesis ceremony (30 min)
✅ Agent mints Passport - Delegation-bound creation (5 min)
✅ Human-to-human delegation - Vacation coverage (2 min)
✅ Passport in agent workflow - Invoice processing integration
✅ Multi-device sync - iPhone + iPad + Mac (1 min/device)

Cross-References to Agent Workflows

Invoice Processing (KB 106) → Uses Agent Passport + Delegation
Medical Triage (KB 106) → Verifies physician Passport + Capability
Fraud Detection (KB 106) → Agent Passport + Investigator Capability
Contract Review (KB 106) → Attorney Passport + Privilege preservation

What These Validate

Architecture Decision	Validated By
Device-rooted keys	Use Case 1 (keys never leave Secure Enclave)
Multi-sig genesis	Use Case 2 (requires 2+ founders)
Delegation constraints	Use Cases 3, 4, 5 (bounded authority enforced)
Authority hierarchy	Use Cases 2, 3 (Org → Agent, Human → Human)
Provenance by default	Use Case 5 (every action logged with DIDs)
Multi-device security	Use Case 6 (per-device keys, revocable)

FULL SPECIFICATION

This section provides the deep, engineer-facing specification for Version 0.1, the first fully functional iteration suitable for:

demos
prototypes
enterprise pilot integrations
early cryptographic testing
simulated Workforce Cloud tasks
seed-stage investor proofs

This is where "portable, human-owned identity" becomes a real protocol — not a metaphor.

WHAT THE HUMAN PASSPORT ACTUALLY IS

The HUMAN Passport is a cryptographically controlled, device-rooted identity container that:

establishes a human's root identity keys
stores selectively disclosed claims
encrypts personal data in a human-owned vault
proves identity, capability, training, and access rights
never leaves the person's control

It is not an app.
It is a protocol implemented across frameworks, SDKs, secure hardware, and the distributed attestation network.

The Passport is a set of:

cryptographic keys
schemas
selective disclosure routines
vault access specs
attestation signatures
capability graph linkages
revocation logic
device sync models

This section specifies the entire v0.1 stack.

THE FOUR SYSTEMIC IMPERATIVES

The Passport must satisfy four systemic imperatives simultaneously:

1. Identity

A human must be uniquely themselves — rooted in secure cryptographic identity — without being trapped in any vendor's ecosystem.

2. Ownership

The human must control:

their keys
their data vault
their disclosures
their revocations
their recovery path

3. Interoperability

The Passport must function across:

healthcare systems
government services
enterprise workflows
international frameworks
AI systems
education providers
HUMAN Academy + Workforce Cloud

4. Safety

Identity cannot be forged, stolen, impersonated, or silently changed.

The Passport protects humans from:

identity hijack
algorithmic corruption
unauthorized access
AI overreach
enterprise misuse

THE PASSPORT IS THREE THINGS

PASSPORT ARCHITECTURE DIAGRAM

graph TB
    subgraph "HUMAN PASSPORT ARCHITECTURE"
        subgraph "1. Cryptographic Identity (DID)"
            DID[<b>Decentralized ID</b><br/>W3C DID Standard]
            IdentityKey[Identity Key<br/>Device-Rooted]
            SigningKey[Signing Key<br/>For Transactions]
            EncryptionKey[Encryption Key<br/>For Data Vault]
        end
        
        subgraph "2. Verifiable Credentials"
            VC[<b>Credentials Store</b>]
            EmploymentVC[Employment<br/>Credentials]
            EducationVC[Education<br/>Credentials]
            CapabilityVC[Capability<br/>Credentials]
            HealthVC[Health<br/>Credentials]
        end
        
        subgraph "3. Personal Data Vault"
            Vault[<b>Encrypted Vault</b><br/>User-Owned Storage]
            OnDevice[On-Device<br/>Storage]
            CloudVault[Encrypted Cloud<br/>Storage]
            DecentralizedVault[Decentralized<br/>Storage]
        end
        
        subgraph "Access Control Layer"
            Consent[Consent Engine]
            SelectiveDisclosure[Selective Disclosure<br/>Zero-Knowledge Proofs]
            Revocation[Revocation<br/>Authority]
        end
    end
    
    DID --> IdentityKey
    DID --> SigningKey
    DID --> EncryptionKey
    
    IdentityKey --> VC
    SigningKey --> Consent
    EncryptionKey --> Vault
    
    VC --> EmploymentVC
    VC --> EducationVC
    VC --> CapabilityVC
    VC --> HealthVC
    
    Vault --> OnDevice
    Vault --> CloudVault
    Vault --> DecentralizedVault
    
    Consent --> SelectiveDisclosure
    Consent --> Revocation
    
    VC --> SelectiveDisclosure
    
    style DID fill:#4A90E2,stroke:#2E5C8A,stroke-width:3px,color:#fff
    style VC fill:#7B68EE,stroke:#5B48CE,stroke-width:3px,color:#fff
    style Vault fill:#50C878,stroke:#30A858,stroke-width:3px,color:#fff
    style Consent fill:#FFA500,stroke:#DF8500,stroke-width:3px,color:#fff
    style SelectiveDisclosure fill:#E74C3C,stroke:#C73C2C,stroke-width:2px,color:#fff

The Three Core Components:

1. A Strong Cryptographic Identity (DID-based)

Decentralized Identifiers (DIDs) form the backbone:

keypairs rooted in secure hardware
no central authority needed to validate identity
portable across ecosystems

The Passport contains:

master DID
sub-identities (domain-scoped DIDs)
device-bound keys
revocation lists
public metadata pointers

2. A Personal Data Vault

Not stored by HUMAN.
Not stored on any third-party server unless the user chooses.

The vault holds:

encrypted personal history
encrypted documents
encrypted certifications
encrypted medical summaries
encrypted capability graph
encrypted attestation receipts

The vault is synced across devices using:

client-side encryption
passkey/biometric access
hardware-backed keys

3. A Selective Disclosure Engine

Allows revealing exactly what a relying party needs — nothing more.

Examples:

"prove I'm licensed as a nurse"
"prove I completed AI-safety training"
"prove I am over 18"
"prove I am the person tied to this credential"

All without revealing:

address
full identity
health conditions
work history
personal documents

This is the heart of HUMAN's privacy stance.

IDENTITY KEY ARCHITECTURE

The HUMAN Passport uses a 3-key model.

Key 1 — HumanRootKey (Primary Signing Key)

Generated on-device using secure enclave or equivalent
Protected by secure hardware (never exported in plaintext)
Used only for high-value operations and deriving operational keys
Recoverable through social recovery, cloud backup, or estate planning
Tied to the human, not to a device
Note: "Never leaves enclave" is the ideal, but recovery paths exist (see Key Management Reality below)

Key 2 — DeviceKey

Derived from HumanRootKey
Paired with secure hardware
Used for:
- signing login proofs
- signing capability updates
- attestation co-signing for workflows
Per-device (iPhone, iPad, Mac, Android, Watch)

Key 3 — DelegationKey (Optional)

Used for:
- "away mode"
- accessibility mode
- guardianship mode
- family delegation
- partial access for dependents

All keys follow:

ed25519 signature scheme (v0.1)
XChaCha20-Poly1305 for symmetric encryption
Optional migration to post-quantum later

KEY MANAGEMENT REALITY: SECURITY vs RECOVERABILITY

The Ideal vs The Real:

Security Ideal: "Keys never leave device, stored in secure enclave only."

Human Reality: Devices get lost, stolen, destroyed. People die. Multi-device is expected. Pure "keys never leave" is impractical.

HUMAN's Approach: Layered security with practical recovery paths.

Primary Key Protection (The Secure Layer)

HumanRootKey (Primary Signing Key):

✅ Generated in secure enclave (iPhone Secure Enclave, Android StrongBox)
✅ Never exported in plaintext
✅ Biometric access only (Face ID, Touch ID, fingerprint)
✅ Hardware-enforced protection

Used for:

High-value operations (large transactions, identity assertions)
Key rotation and revocation
Recovery authorization
New device enrollment

Reality Check: This key DOES stay in secure enclave. BUT it's not the only key.

Recovery Mechanisms (The Practical Layer)

The Problem:

If primary key is lost and there's no recovery → Account is gone forever
Users will NOT properly manage recovery phrases (proven by crypto wallet disasters)
Death/incapacity requires estate access

HUMAN's Solutions (User Choice):

Option 1: Social Recovery (Recommended)

Based on: Argent wallet model

interface SocialRecovery {
  guardians: PassportDID[];      // 3-5 trusted contacts
  threshold: number;              // e.g., 3-of-5 required
  lockPeriod: number;             // 48-72 hours (prevents immediate takeover)
}

// Recovery process:
// 1. User loses device, initiates recovery from new device
// 2. 3 of 5 guardians approve recovery request
// 3. After 48-hour lock period, new device enrolled
// 4. Old device keys revoked

Guardians:

Each holds encrypted key shard (no single guardian can recover)
Guardians can be: family, friends, trusted colleagues
HUMAN never sees unencrypted shards
User can change guardians anytime

Security Properties:

✅ No single point of failure
✅ Resistant to social engineering (3-of-5 harder to compromise than 1)
✅ Time-lock prevents immediate takeover
✅ User can revoke/replace guardians

Option 2: Encrypted Cloud Backup

For: Users who prefer simplicity over social recovery

interface CloudBackup {
  encryptedKey: string;           // Recovery key encrypted with passphrase
  storageProvider: 'icloud' | 'google' | 'onedrive';
  backupDate: Date;
  requiresPassphrase: true;
}

// Recovery process:
// 1. User loses device
// 2. Installs HUMAN on new device
// 3. Selects "Restore from Cloud"
// 4. Authenticates with Apple/Google (device access)
// 5. Enters passphrase (NOT stored anywhere)
// 6. Key decrypted locally, never sent to HUMAN

Security Properties:

✅ Encrypted at rest (Apple/Google can't read it)
✅ Requires: Device access + Passphrase + Biometric
✅ HUMAN never has decryption key
❌ Single point of failure if passphrase forgotten

Trade-off: Easier UX, but less secure than social recovery.

Option 3: Multi-Device Sync

For: Users with multiple devices (phone + laptop + tablet)

interface MultiDeviceSync {
  primaryDevice: DeviceID;        // First enrolled device
  enrolledDevices: DeviceID[];    // Phone, laptop, tablet, etc.
  syncEncryption: 'e2e';          // End-to-end encrypted
}

// New device enrollment:
// 1. User wants to add iPad
// 2. Opens HUMAN on existing device (iPhone)
// 3. Scans QR code from iPad
// 4. Approves enrollment on iPhone
// 5. Keys synced to iPad (encrypted in transit)

Security Properties:

✅ End-to-end encrypted sync (HUMAN can't decrypt)
✅ Requires approval from existing device (prevents unauthorized enrollment)
✅ Any device can revoke other devices
✅ Device list visible to user

Reality: If you have 3 devices and lose 1, you still have access.

Option 4: Institutional Custody (Enterprise)

For: Enterprises requiring key escrow for compliance

interface InstitutionalCustody {
  custodian: 'human' | 'self-hosted';
  policy: CustodyPolicy;
  multiPartyApproval: boolean;    // Requires 2-of-3 admins
}

// Enterprise use case:
// - Employee leaves company
// - Company needs to access work done under employee's identity
// - 2-of-3 company admins approve key access
// - HUMAN releases escrowed key to company

Clear Disclosure:

⚠️ User opts IN to custody (not default)
⚠️ HUMAN can access key if user chooses this option
⚠️ Subject to legal subpoena
✅ Required for some regulated industries
✅ Separate from personal keys (work vs personal identity)

Use Cases:

Healthcare (HIPAA requires institutional access)
Financial services (audit requirements)
Government contractors (security clearance)

Option 5: Estate Planning (Death/Incapacity)

For: Designated heirs and long-term planning

interface EstatePlanning {
  designatedHeir: PassportDID;
  timeLock: number;               // e.g., 365 days of inactivity
  proofOfLife: boolean;           // Periodic check-ins required
  notificationPeriod: number;     // 30-day warning before transfer
}

// Process:
// 1. User designates heir (child, spouse, executor)
// 2. Sets inactivity period (e.g., 12 months)
// 3. If no activity for 12 months → Warning sent to user
// 4. If no response for 30 days → Heir can claim identity
// 5. Heir gains access to identity + credentials + data

Similar to: Google Inactive Account Manager

Security Properties:

✅ Prevents identity loss on death
✅ Time-lock prevents immediate takeover
✅ Notification period gives user chance to respond
✅ User can change heir anytime

Delegation Keys (The Operational Layer)

The Problem: Requiring biometric + secure enclave for EVERY operation is impractical.

Solution: Time-limited, scope-limited delegation keys that CAN leave device.

interface DelegationKey {
  parentKey: KeyID;               // Which primary key issued this
  validFrom: Date;
  validUntil: Date;               // Expires after X hours/days
  scopeLimits: string[];          // Can only do these actions
  revocable: boolean;             // Parent key can revoke anytime
  usageCount?: number;            // Optional: Max N uses
}

// Example: Browser session key
const sessionKey: DelegationKey = {
  parentKey: 'primary-key-abc',
  validFrom: now,
  validUntil: now + 7 * days,     // Valid for 7 days
  scopeLimits: [
    'read:kb',                    // Can read KB
    'sign:tasks',                 // Can sign task completions
    'NOT:transfer-funds',         // CANNOT transfer funds
    'NOT:change-identity',        // CANNOT modify identity
  ],
  revocable: true,
};

Use Cases:

Browser Sessions:
- User logs in on laptop
- Primary key (on phone) signs delegation key for laptop
- Laptop can operate for 7 days without phone
- After 7 days, re-auth required
Agent Authorization:
- User authorizes AI agent to act on their behalf
- Delegation key valid for task duration (2 hours)
- Can't access funds, only complete specific task
- Auto-expires when task done
Emergency Access:
- User delegates limited access to family member
- Valid for 30 days
- Can view medical info, can't modify identity
- Revocable immediately if needed

Security Properties:

✅ Time-limited (auto-expires)
✅ Scope-limited (can't do everything)
✅ Revocable (primary key has control)
✅ Auditable (all delegations logged)
❌ Less secure than primary key (intentional trade-off)

The Hard Questions (Answered)

Q: What if someone loses phone AND forgets passphrase?

A: If no social recovery setup: Gone. Unrecoverable.
This is crypto wallet reality
HUMAN's approach: STRONGLY encourage social recovery during onboarding
Default: Social recovery (3-of-5), NOT passphrase-only

Q: Can HUMAN recover keys if user asks?

A: NO (unless user opted into institutional custody)
If we can recover keys → We're a honeypot and not self-sovereign
Exception: Opt-in custody for enterprises

Q: What about government subpoena?

A: If keys in secure enclave: We physically cannot comply
If user opted into HUMAN custody: We must comply (disclosed upfront)
Clear policy: Personal keys unrecoverable, custody keys subject to law

Q: What happens when someone dies?

A: Estate planning feature (designated heir + time-lock)
Similar to Google Inactive Account Manager
12 months inactivity → 30-day warning → Heir can claim
Prevents identity loss, respects user intent

Q: Why not just use recovery phrases like crypto wallets?

A: Because 99% of users lose them or write them down insecurely
Social recovery is proven more secure (Argent, Safe/Gnosis)
HUMAN optimizes for human behavior, not crypto maximalism

Key Storage Summary

Key Type	Storage Location	Recovery Method	Use Case
HumanRootKey (Primary)	Secure enclave only	Social recovery, cloud backup, or estate planning	High-value operations, key rotation
DeviceKey (Derived)	Secure enclave per device	Sync from primary or re-derive	Daily operations, device-specific
DelegationKey (Session)	Browser localStorage, app keychain	Re-issue from primary	Sessions, agent auth, temporary access
RecoveryShards (Social)	Guardians' devices (encrypted)	3-of-5 threshold	Account recovery
CloudBackup (Optional)	iCloud/Google (encrypted)	Passphrase + device auth	Simple recovery option
CustodyKey (Enterprise)	HUMAN HSM (encrypted)	Multi-party approval	Regulated industries only

What This Means for HUMAN

We store:

✅ Public keys (DIDs, for verification)
✅ Encrypted recovery shards (if user chooses social recovery)
✅ Encrypted cloud backups (if user chooses cloud backup)
✅ Custody keys (if enterprise opts in)

We NEVER store (unless opted in):

❌ Primary keys in plaintext
❌ Passphrases or biometric data
❌ Decryption keys for recovery shards
❌ Personal custody keys (default model)

We CAN'T recover (by design):

Personal keys with social recovery (requires guardians)
Personal keys with cloud backup (requires user's passphrase)
Keys in secure enclave (hardware-protected)

We CAN recover (if opted in):

Institutional custody keys (for enterprises with compliance requirements)

Comparison to Other Systems

System	Primary Key Storage	Recovery	Multi-Device	Delegation
Traditional Login	Server-side (password hash)	Email reset	Any device	N/A
Crypto Wallet	Local only	12-word phrase	Manual import	None
Apple ID	iCloud Keychain (encrypted)	Device + SMS	iCloud sync	N/A
HUMAN Passport	Secure enclave	Social/Cloud/Estate	Encrypted sync	Time/scope-limited

HUMAN's Advantage:

More secure than traditional login (no password to steal)
More recoverable than crypto wallets (social recovery, not just phrases)
More portable than Apple ID (cross-platform, self-sovereign)
More practical than pure hardware keys (delegation for sessions)

Implementation Roadmap

v0.1 (Week 1-2): Passport-Lite

Server-stored keys (KMS-encrypted)
Admin-assisted recovery
Single-device web access
Why: Speed to revenue, internal users only

v0.2 (Month 2-4): CloudHSM

Keys in CloudHSM (never exported)
Multi-device enrollment
Encrypted cloud backup option
Why: Beta users, enterprise pilots

v0.3 (Month 4-6): Secure Enclave

Primary keys in device secure enclave
Social recovery (3-of-5 guardians)
Delegation keys for sessions
Estate planning feature
Why: Production-ready, public launch

v0.4 (Month 6-12): Full Production

Multi-device sync (end-to-end encrypted)
Institutional custody option (enterprises)
Hardware key support (YubiKey, etc.)
Post-quantum crypto migration path
Why: Regulated industries, global scale

Cross-References

See: kb/internal/founder-decisions-2025-12-11.md - Year 1 infrastructure commitments
See: 04_the_five_systems.md - Device-first architecture principle
See: 124_human_v01_production_prd.md - Recovery UX requirements
See: 48_governance_model_and_constitutional_layer.md - Custody policies and legal compliance

PASSPORT DATA STRUCTURE (v0.1 Schema)

The Passport consists of three components:

0. Passport Container (Protocol-Level Pointer + Proof Surface)

At the protocol level, a Passport is intentionally thin: it does not “store your whole life.” It holds identity keys plus pointers and proof references that let you prove facts about yourself without exposing underlying private data.

// Logical container (implementation may split across device + vault + ledger)
interface PassportContainer {
  DID: string;
  PK: string; // public key material / verification methods
  RecoveryShards: unknown; // e.g., 3-of-5 social recovery shards (encrypted)
  DataVaultPointer: string; // encrypted pointer to human-owned vault storage
  CapabilityGraphRoot: string; // pointer to the head/root of the personal Capability Graph in the vault
  ConsentLeases: unknown; // consent contracts / visibility policies
  LedgerRefs: string[]; // attestation hashes / anchors that prove updates over time
}

Canonical chain (technical): governed event → evidence → Capability Graph update → ledger attestation → Passport pointers updated (CapabilityGraphRoot + LedgerRefs).

A. Identity Document (IDOC)

Metadata fields:

{
  "human_did": "did:human:<uuid>",
  "device_keys": [<public keys>],
  "recovery_threshold": "3-of-5",
  "version": "0.1",
  "created_at": <timestamp>,
  "updated_at": <timestamp>
}

Stored:

locally on-device (encrypted)
optionally mirrored to human-owned vault

Anchored:

DID document anchored to Layer 1

B. Claims Container (C-Set)

This container holds structured claims, such as:

Identity claims:

age range (not birthdate)
citizenship proofs (selectively disclosable)
license status

Capability claims (proofs + references, not the full graph):

CapabilityGraphRoot pointer (head of the personal graph in the vault)
capability proofs / selective disclosures (including ZK proofs where applicable)
update receipts / attestation references (anchored hashes that can be verified)

Training claims:

Academy completions
assessment artifacts (optional or encrypted)

Identity-dependent claims:

background checks
certifications
credentials

All claims follow the Verifiable Credential (VC) data model.

PASSPORT GROWTH (How a Passport Evolves Over Time)

1. What “growth” means

A HUMAN Passport doesn’t “grow” by accumulating a bigger centralized profile. Under HUMAN, data stays in vaults and capability graphs; the Passport grows by accumulating proofs and pointers:

CapabilityGraphRoot points to a richer personal Capability Graph (more nodes/edges, updated weights) in the human’s vault
LedgerRefs accumulates attestation hashes anchoring capability updates, credentials, revocations, and corrections
ConsentLeases evolve as the human changes what they’re willing to share, with whom, and for what purpose

So: Passport growth = changes to what the Passport can prove about you, not where the underlying data lives.

2. Growth primitives (what can change over time)

Capability Graph Expansion / Update
- New nodes/edges, weight changes, freshness/decay changes (driven by evidence)
New attestations anchored
- Hashes/proofs anchored to a ledger; Passport gains new LedgerRefs
Consent & boundary changes
- Updates to consent leases and capability visibility policies (selective disclosure surface changes)
Key lifecycle
- Rotations, recovery, device enrollment changes cryptographic surface while preserving continuity of past proofs

3. Growth channels (where new capability evidence comes from)

All channels feed the same chain: event → evidence → graph update → ledger anchor → Passport refs.

Academy training (guided simulations and assessments)
Workforce Cloud work (real tasks, outcomes, escalation rationale)
HumanOS governance events (approvals, overrides, refusals, uncertainty escalations)
Peer/mentor attestations (human judgment about work quality, collaboration, ethics)
External credentials (degrees, licenses, employer attestations)
Self-improvement micro-evidence (repeatable practice and low-stakes workflows)

4. Hosting-agnostic behavior (including air-gapped)

This process is identical in hosted, hybrid, and fully air-gapped deployments: when a human (or agent/model) performs work well, their local capability graph and local Passport proof surface update in-place, even if no external network ever sees the raw data.

5. Non-additive evolution: revocation, correction, freshness

Growth is not only additive:

Revocation/correction: we do not erase history; we add cryptographically-linked correction/revocation attestations and reference them
Freshness/decay: weights and confidence can decay without recent evidence; “stale” capabilities become provably stale
Boundary tightening: disclosure policies can narrow what gets revealed to a given requester without deleting underlying capability data

Credential Verification & Attestation: Traditional Education and Professional Experience

Critical design principle: The Passport must integrate traditional credentials (degrees, certifications, employment history) and verify them cryptographically—not just accept self-reported claims.

Three types of credentials are stored:

Type 1: Education Credentials (Degrees, Certifications, Licenses)

Issuer: Universities, certification bodies, licensing boards Verification Method: Cryptographic attestation from issuing institution Storage: Encrypted in Passport, anchored on-chain

Example: University Degree

{
  "@context": ["https://www.w3.org/2018/credentials/v1"],
  "type": ["EducationCredential"],
  "issuer": "did:org:mit-edu",
  "issuanceDate": "2024-05-15T00:00:00Z",
  "credentialSubject": {
    "id": "did:human:alex-789",
    "degree": "Bachelor of Science",
    "major": "Computer Science",
    "graduationDate": "2024-05-15",
    "honors": "Summa Cum Laude",
    "studentId": "912345678",
    "institution": "Massachusetts Institute of Technology"
  },
  "proof": {
    "type": "Ed25519Signature2020",
    "created": "2024-05-20T12:00:00Z",
    "proofPurpose": "assertionMethod",
    "verificationMethod": "did:org:mit-edu#registrar-key-2024",
    "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..3d1f8a2b..."
  },
  "metadata": {
    "credentialHash": "sha256:7b9f2a...",
    "ledgerAnchor": "0x9a3c...",  // Anchored on blockchain for tamper-proofing
    "verificationStatus": "issuer_verified"
  }
}

Verification Flow:

Student uploads degree: Alex uploads PDF of MIT diploma via HUMAN Companion
HUMAN requests attestation: System contacts MIT registrar API (or email for institutions without API)
MIT signs credential: MIT registrar signs with their private key (did:org:mit-edu#registrar-key-2024)
Anchored on-chain: Hash of credential + signature anchored to blockchain (immutable proof)
Stored in Passport: Full credential stored encrypted in Alex's Passport
Selective disclosure ready: Alex can prove "I have CS degree from MIT" without revealing GPA, courses, or student ID

Result: Any employer or Academy can verify Alex's degree cryptographically—can't be faked.

Example: Professional License (Medical Board Certification)

{
  "@context": ["https://www.w3.org/2018/credentials/v1"],
  "type": ["ProfessionalLicense"],
  "issuer": "did:org:american-board-radiology",
  "issuanceDate": "2004-07-01T00:00:00Z",
  "expirationDate": "2034-07-01T00:00:00Z",
  "credentialSubject": {
    "id": "did:human:dr-patel-456",
    "licenseType": "Board Certification in Diagnostic Radiology",
    "licenseNumber": "12345",
    "specializations": ["Thoracic Imaging", "Emergency Radiology"],
    "status": "active",
    "issuingAuthority": "American Board of Radiology"
  },
  "proof": {
    "type": "Ed25519Signature2020",
    "created": "2004-07-05T00:00:00Z",
    "proofPurpose": "assertionMethod",
    "verificationMethod": "did:org:american-board-radiology#license-key",
    "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..8f3a1c..."
  },
  "metadata": {
    "renewalRequired": true,
    "nextRenewalDate": "2034-07-01",
    "continuingEducationRequired": true,
    "verificationStatus": "issuer_verified",
    "ledgerAnchor": "0x2f8b..."
  }
}

Why this matters: Dr. Patel's board certification is cryptographically verified. Workforce Cloud can confirm he's licensed without calling the ABR every time. If license is revoked, ABR updates on-chain and Passport reflects it instantly.

Type 2: Employment Credentials (Professional Experience Attestations)

Issuer: Previous employers (HR departments, managers) Verification Method: Employer attestation + optional provenance logs Storage: Encrypted in Passport

Example: Employment Attestation

{
  "@context": ["https://www.w3.org/2018/credentials/v1"],
  "type": ["EmploymentCredential"],
  "issuer": "did:org:techcorp",
  "issuanceDate": "2024-11-15T00:00:00Z",
  "credentialSubject": {
    "id": "did:human:jennifer-234",
    "role": "Vice President of Marketing",
    "department": "Marketing",
    "startDate": "2016-03-01",
    "endDate": "2024-11-01",
    "yearsExperience": 8.67,
    "responsibilities": [
      "Led marketing strategy for $500M revenue division",
      "Managed team of 25 direct and indirect reports",
      "Launched 12 major product campaigns",
      "Oversaw $20M annual marketing budget"
    ],
    "performanceSummary": "Consistently exceeded targets, promoted twice",
    "employer": "TechCorp Inc.",
    "attestedBy": "Jane Doe, Chief People Officer"
  },
  "proof": {
    "type": "Ed25519Signature2020",
    "created": "2024-11-15T14:00:00Z",
    "proofPurpose": "assertionMethod",
    "verificationMethod": "did:org:techcorp#hr-attestation-key",
    "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..9a2f3d..."
  },
  "metadata": {
    "employmentVerified": true,
    "attestationDocument": "ipfs://QmX7b8...", // PDF of formal letter
    "verificationStatus": "employer_verified",
    "ledgerAnchor": "0x7d2a..."
  }
}

Verification Flow:

Worker requests attestation: Jennifer contacts TechCorp HR via HUMAN platform
HR reviews and attests: TechCorp HR verifies employment records, drafts formal letter
HR signs attestation: TechCorp signs with company key (did:org:techcorp#hr-attestation-key)
Letter uploaded: PDF stored on IPFS (immutable, distributed storage)
Anchored on-chain: Attestation hash anchored to blockchain
Stored in Passport: Full attestation stored in Jennifer's Passport

Result: Jennifer can prove 8 years as VP Marketing to any employer/client—cryptographically verified, not just "trust my resume."

Alternative: Peer Attestations (For Freelancers/Consultants)

For workers without formal HR departments:

{
  "@context": ["https://www.w3.org/2018/credentials/v1"],
  "type": ["PeerAttestation"],
  "issuer": "did:human:colleague-567",
  "issuanceDate": "2024-09-20T00:00:00Z",
  "credentialSubject": {
    "id": "did:human:freelancer-890",
    "relationship": "client",
    "projectDescription": "Built marketing automation system for Series B SaaS startup",
    "duration": "6 months",
    "attestation": "Worked closely with [freelancer] on marketing automation. Exceptional strategic thinking, delivered on time and under budget. Directly contributed to 30% increase in lead generation."
  },
  "proof": {
    "type": "Ed25519Signature2020",
    "created": "2024-09-20T10:00:00Z",
    "proofPurpose": "assertionMethod",
    "verificationMethod": "did:human:colleague-567#key-1",
    "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..2c9f7a..."
  },
  "metadata": {
    "attestationType": "peer",
    "weight": 0.60,  // Lower weight than employer attestation (0.85)
    "verificationStatus": "peer_verified"
  }
}

Weight hierarchy:

Employer attestation (HR signed): 0.85
Manager attestation: 0.75
Peer attestation (colleague): 0.60
LinkedIn-style endorsement: 0.30 (lowest trust)

Type 3: Capability Credentials (Demonstrated Work via HUMAN)

Issuer: HumanOS (HUMAN Protocol) Verification Method: Provenance logs (cryptographic audit trail of every task) Storage: Encrypted in Passport

Example: Workforce Cloud Task Completion

{
  "@context": ["https://www.w3.org/2018/credentials/v1"],
  "type": ["HUMANCapability"],
  "issuer": "did:org:humanos",
  "issuanceDate": "2024-09-01T00:00:00Z",
  "credentialSubject": {
    "id": "did:human:alex-789",
    "capability": "software-engineering",
    "weight": 0.82,
    "evidence": {
      "tasksCompleted": 200,
      "accuracy": 0.94,
      "averageQuality": 0.91,
      "timeRange": {
        "firstTask": "2024-06-01T00:00:00Z",
        "lastTask": "2024-09-01T00:00:00Z"
      },
      "errorsDetected": 47,
      "errorsMade": 3,
      "peerReviewScore": 0.88
    },
    "provenanceLogs": [
      "0xabc123...",  // Ledger transaction ID for each task
      "0xdef456...",
      "0xghi789...",
      // ... 200 transaction IDs
    ]
  },
  "proof": {
    "type": "Ed25519Signature2020",
    "created": "2024-09-01T12:00:00Z",
    "proofPurpose": "assertionMethod",
    "verificationMethod": "did:org:humanos#capability-attestation-key",
    "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..1f7c9a..."
  },
  "metadata": {
    "verificationStatus": "provenance_verified",
    "ledgerAnchor": "0x4e2f...",
    "capabilityGraphNode": "capability:software-engineering:alex-789"
  }
}

Why provenance logs matter: Every task Alex completed is logged on-chain. Anyone can verify:

Task was real (not fabricated)
Alex completed it (not someone else)
Quality score was earned (not manipulated)
Timeline is accurate (not backdated)

Result: Demonstrated work is the most trustworthy evidence type because it's cryptographically auditable.

Credential Lifecycle Management

Issuance → Verification → Storage → Selective Disclosure → Renewal/Revocation

// Credential Lifecycle
class CredentialManager {
  // 1. Request credential from issuer
  async requestCredential(
    humanDID: string,
    credentialType: "education" | "employment" | "license",
    issuerDID: string,
    claimData: CredentialClaim
  ): Promise<VerifiableCredential> {
    // Contact issuer (university, employer, licensing board)
    const attestationRequest = await this.contactIssuer(issuerDID, {
      subjectDID: humanDID,
      credentialType,
      claimData
    });
    
    // Issuer reviews, signs, and returns credential
    return attestationRequest;
  }
  
  // 2. Verify credential authenticity
  async verifyCredential(vc: VerifiableCredential): Promise<VerificationResult> {
    // Check issuer signature
    const signatureValid = await crypto.verify(
      vc.proof.jws,
      vc.issuer,  // Issuer's public key
      vc.credentialSubject
    );
    
    // Check on-chain anchor
    const anchorValid = await ledger.verifyAnchor(vc.metadata.ledgerAnchor);
    
    // Check revocation status
    const notRevoked = await ledger.checkRevocation(vc.id);
    
    return {
      valid: signatureValid && anchorValid && notRevoked,
      issuerTrusted: await trustRegistry.isTrusted(vc.issuer),
      expirationStatus: this.checkExpiration(vc.expirationDate)
    };
  }
  
  // 3. Store credential in Passport
  async storeCredential(
    passportId: PassportId,
    vc: VerifiableCredential
  ): Promise<void> {
    // Encrypt credential with Passport's encryption key
    const encrypted = await encrypt(vc, passportId.encryptionKey);
    
    // Store in local vault
    await vault.store(passportId, encrypted);
    
    // Anchor credential hash on-chain
    const credentialHash = hash(vc);
    await ledger.anchor(credentialHash, passportId);
    
    // Update Capability Graph
    await capabilityGraph.updateFromCredential(passportId, vc);
  }
  
  // 4. Selective disclosure (prove without revealing everything)
  async proveCredential(
    passportId: PassportId,
    credentialId: string,
    disclosureScope: DisclosureScope
  ): Promise<CredentialProof> {
    // Example: Prove "I have CS degree" without revealing GPA, courses, student ID
    const credential = await vault.retrieve(passportId, credentialId);
    
    // Generate zero-knowledge proof
    const proof = await zkProof.generate(credential, disclosureScope);
    
    return proof;  // Relying party can verify proof without seeing full credential
  }
  
  // 5. Handle revocation (license expired, degree revoked, employment ended)
  async revokeCredential(
    issuerDID: string,
    credentialId: string,
    reason: string
  ): Promise<void> {
    // Issuer publishes revocation to distributed ledger
    await ledger.publishRevocation({
      credentialId,
      issuer: issuerDID,
      reason,
      timestamp: Date.now()
    });
    
    // Passport automatically reflects revocation status
    // Capability Graph weight updated to reflect loss of credential
  }
}

Trust Registry: Who Can Issue Credentials?

Problem: Anyone can claim to be "MIT" or "Mayo Clinic" and issue fake credentials.

Solution: HUMAN maintains a Trust Registry of verified credential issuers.

Trust Registry Structure:

interface TrustedIssuer {
  did: string;  // did:org:mit-edu
  name: string;  // "Massachusetts Institute of Technology"
  type: "university" | "employer" | "licensing_board" | "certification_body";
  verificationMethod: string[];  // Public keys for signature verification
  status: "active" | "suspended" | "revoked";
  
  // Verification metadata
  verifiedBy: "HUMAN" | "third_party_verifier";
  verificationDate: Date;
  domainControl: string;  // Proved control of mit.edu domain
  legalRegistration: string;  // Business registration, accreditation proof
}

Example Trust Registry entries:

[
  {
    "did": "did:org:mit-edu",
    "name": "Massachusetts Institute of Technology",
    "type": "university",
    "verificationMethod": ["did:org:mit-edu#registrar-key-2024"],
    "status": "active",
    "verifiedBy": "HUMAN",
    "verificationDate": "2024-01-15",
    "domainControl": "mit.edu",
    "accreditation": "New England Commission of Higher Education"
  },
  {
    "did": "did:org:mayo-clinic",
    "name": "Mayo Clinic",
    "type": "employer",
    "verificationMethod": ["did:org:mayo-clinic#hr-key"],
    "status": "active",
    "verifiedBy": "HUMAN",
    "verificationDate": "2024-02-20",
    "domainControl": "mayoclinic.org",
    "legalRegistration": "EIN: 41-0308000"
  }
]

Verification process for new issuers:

Organization requests to become trusted issuer
HUMAN verifies:
- Domain control (prove you own mit.edu)
- Legal registration (business license, accreditation)
- DID ownership (prove control of did:org:mit-edu)
HUMAN adds to Trust Registry
Organization can now issue verifiable credentials
All credentials from this issuer are automatically trusted

Anti-fraud: If fake "MIT" tries to issue credentials, their DID won't be in Trust Registry → credentials rejected.

How This Integrates with Capability Graph

Credential → Capability Graph Weight Contribution:

// When credential is stored in Passport
async function updateCapabilityGraphFromCredential(
  passportId: PassportId,
  credential: VerifiableCredential
): Promise<void> {
  // 1. Determine which capabilities this credential affects
  const affectedCapabilities = mapCredentialToCapabilities(credential);
  
  // 2. For each capability, add credential as evidence
  for (const capabilityId of affectedCapabilities) {
    const node = await capabilityGraph.getNode(passportId, capabilityId);
    
    // Add credential evidence
    node.evidence.push({
      type: "credential",
      source: credential.issuer,
      credential: credential.credentialSubject.degree || credential.credentialSubject.licenseType,
      issuedDate: credential.issuanceDate,
      verificationStatus: "issuer_verified",
      issuerSignature: credential.proof.jws,
      contribution: calculateCredentialContribution(credential),  // 0.5-0.8
      relevanceDecayRate: 0.05  // 5% per year
    });
    
    // Recalculate capability weight
    node.weight = calculateCapabilityWeight(
      node.evidence.filter(e => e.type === "credential"),
      node.evidence.filter(e => e.type === "professional_experience"),
      node.evidence.filter(e => e.type === "demonstrated_work")
    );
    
    await capabilityGraph.updateNode(passportId, node);
  }
}

Example: When Alex's MIT CS degree is verified and stored:

Capability Graph node "software-engineering" weight increases from 0.0 → 0.65
Evidence array includes: { type: "credential", source: "did:org:mit-edu", credential: "Bachelor of Science in Computer Science", contribution: 0.60 }
Alex can now enter Workforce Cloud at L2 tier ($35/hour) instead of L1 ($18/hour)

Example: Capability Credential (Academy or Workforce Cloud)

C. Vault Pointer (VPointer)

The Passport includes references to storage locations the human controls:

{
  "vaults": [
      {
        "location_type": "device-local" | "encrypted-cloud" | "hybrid",
        "uri": "humanvault://<domain>/<id>",
        "pubkey": "<vault encryption key>"
      }
  ]
}

No content lives in the Passport itself.
It acts as the index.

VAULT CONNECTOR ARCHITECTURE

The HUMAN Passport's Personal Data Vault uses a provider-agnostic connector architecture, allowing entities to choose where their data lives while maintaining consistent access patterns.

Design Principle: Bring Your Own Vault (BYOV)

Core Tenet: HUMAN does NOT store entity data by default. Entities choose their vault provider.

Storage Options:

HUMAN-Hosted Vault (Paid Tier) - Convenience + HUMAN manages infrastructure
Self-Hosted Vault (Enterprise) - Full sovereignty, entity infrastructure
Third-Party Vault (AWS, Azure, GCP, etc.) - Use existing cloud investments
Local-Only (Free Tier) - Browser/device storage, no sync, development use

Vault Provider Interface

All vault providers (HUMAN, AWS, Azure, self-hosted, etc.) implement a standard interface:

interface IVaultProvider {
  // Provider metadata
  readonly id: string;
  readonly name: string;
  readonly capabilities: VaultCapabilities;
  
  // Connection lifecycle
  connect(config: VaultProviderConfig): Promise<void>;
  disconnect(): Promise<void>;
  healthCheck(): Promise<VaultHealthStatus>;
  
  // CRUD operations (provider-agnostic)
  insert(namespace: string, collection: string, doc: any): Promise<string>;
  update(namespace: string, collection: string, id: string, updates: any): Promise<void>;
  query(namespace: string, collection: string, query: VaultQuery): Promise<VaultDocument[]>;
  delete(namespace: string, collection: string, id: string): Promise<void>;
  
  // Encryption (provider handles, HUMAN never sees cleartext)
  encrypt(data: any): Promise<string>;
  decrypt(encrypted: string): Promise<any>;
  
  // Provider-specific features
  backup?(): Promise<VaultBackup>;
  restore?(backup: VaultBackup): Promise<void>;
  getMetrics(): Promise<VaultMetrics>;
}

Vault Connector Registry

Official Connectors (Provided by HUMAN):

human - HUMAN-hosted encrypted vault (paid tier)
local - Browser IndexedDB, no sync (free tier)

Verified Community Connectors:

aws - AWS S3 + DynamoDB connector
azure - Azure Blob + CosmosDB connector
gcp - Google Cloud Storage + Firestore connector
supabase - Supabase connector
mongodb - MongoDB Atlas connector

Self-Hosted Connectors:

postgres - Self-hosted PostgreSQL
redis - Self-hosted Redis
custom - Implement IVaultProvider for any backend

Vault Connector SDK

Third-party developers can build vault connectors using @human/vault-connector-sdk:

import { BaseVaultProvider } from '@human/vault-connector-sdk';

/**
 * Example: AWS S3 + DynamoDB Vault Connector
 */
export class AWSVaultProvider extends BaseVaultProvider {
  readonly id = 'aws';
  readonly name = 'AWS S3 + DynamoDB';
  
  async connect(config: VaultProviderConfig): Promise<void> {
    // Initialize AWS SDK with entity's credentials
    this.s3 = new S3Client(config.providerSpecific);
    this.dynamodb = new DynamoDBClient(config.providerSpecific);
  }
  
  async insert(namespace: string, collection: string, doc: any): Promise<string> {
    // Encrypt document with entity's key
    const encrypted = await this.encryptDocument(doc, this.config.encryptionKey);
    
    // Store in entity's S3 bucket
    await this.s3.putObject({
      Bucket: this.config.providerSpecific.bucket,
      Key: `${namespace}/${collection}/${id}`,
      Body: encrypted,
    });
    
    // Index in entity's DynamoDB table
    await this.dynamodb.putItem({...});
    
    return id;
  }
  
  // ... implement other methods
}

Data Sovereignty Guarantees

1. Entity Owns Encryption Keys:

Vault provider stores encrypted blobs
Only entity has decryption keys
HUMAN cannot read vault contents (even HUMAN-hosted vaults)

2. Vault Provider Cannot Read Data:

All encryption happens client-side
Provider sees only encrypted bytes
Entity can migrate providers without loss

3. Zero Trust Model:

HUMAN trusts no vault provider (including itself)
All data encrypted before leaving entity's control
Vault is pure storage, no logic

Business Model

Tier	Vault Options	Cost	Features
Free	Local-only OR Dropbox/Drive (free tier)	$0	Up to 1GB, basic sync
Pro	HUMAN-hosted OR any consumer storage	$10/mo*	10GB, full sync, backup
Enterprise	Self-hosted OR cloud OR HUMAN	Custom	Unlimited, your choice

*Pro tier unlocks Companion features, not just vault. Using your own Dropbox/Drive/iCloud is free.

Vault Provider Economics:

Option 1: Use Your Own Storage (Free for HUMAN)

Connect Dropbox, Google Drive, iCloud, OneDrive
You already pay them (or use their free tier)
HUMAN provides the connector for free
Your data stays in your storage
HUMAN's cost: $0 (you pay storage provider)

Option 2: HUMAN-Hosted Vault ($20/mo)

HUMAN manages infrastructure
Encrypted backup included
Support & SLA
No setup required
HUMAN's cost: ~$5/mo (our infrastructure, we absorb margin)

Option 3: Enterprise Self-Hosted (Custom)

Use your AWS/Azure/GCP account
HUMAN provides connectors
You pay cloud provider directly
Complete control
HUMAN's cost: $0 (you pay cloud provider)

Why This Model Works:

✅ Free tier is truly free (local or use existing Dropbox)
✅ Pro tier charges for Companion features, not just storage
✅ Entities can graduate from free to paid without data migration
✅ No vendor lock-in (vault is portable)
✅ HUMAN makes money from value (Companion), not data hostage

Extension Storage

Extensions (Companion, third-party agents) store data in the entity's vault:

// Extension uses entity's configured vault (provider-agnostic)
await ctx.storage.insert('work_sessions', {
  passport_id: ctx.actorPassportId,
  status: 'active',
  // Stored in entity's vault, encrypted, entity-owned
});

// Works identically whether entity uses:
// - HUMAN vault (paid)
// - AWS S3 (self-hosted)
// - Local storage (free)

Benefits:

Extension data lives in entity's vault
HUMAN never sees extension data
Extensions don't need own storage infrastructure
Entity can audit/export all extension data

HUMAN Corp Bootstrap: Filesystem Vault

⚠️ SECURITY: Filesystem Provider is DEV ONLY

Current State (Bootstrap Phase):

HUMAN Corp (did:org:human-corp) uses a special FilesystemVaultProvider that reads from /kb/*.md:

Security Safeguards:

✅ Disabled in production (NODE_ENV=production)
✅ Must be explicitly enabled (VAULT_FILESYSTEM_ENABLED=true)
✅ Whitelisted to HUMAN Corp only (database restriction)
✅ Path traversal prevention (no .. in paths)
✅ Startup validation (fails if misconfigured)

// HUMAN Corp's vault configuration (bootstrap)
entity_vault_config = {
  entity_id: 'did:org:human-corp',
  provider_id: 'filesystem',  // Special provider for bootstrap
  provider_config: { rootPath: './kb' },
  tier: 'enterprise',
};

Why This Works:

Architecturally Correct:
- HUMAN Corp is a LegalEntity with a vault (consistent model)
- KB accessed via IVaultProvider interface (no special-casing)
- Other entities see HUMAN Corp using vaults (Living HAIO)
Practically Viable:
- ✅ Cursor reads /kb/*.md for context
- ✅ MkDocs builds from /kb for reference site
- ✅ GPT upload script concatenates /kb files
- ✅ Developers edit markdown files directly
- ✅ Git tracks KB changes (version control)

FilesystemVaultProvider:

class FilesystemVaultProvider implements IVaultProvider {
  readonly id = 'filesystem';
  
  async query(namespace, collection, query) {
    // Special case: KB documents
    if (namespace === 'kb' && collection === 'documents') {
      // List all .md files in /kb (including subdirectories)
      const files = await glob('./kb/**/*.md');
      // Parse frontmatter and content
      return files.map(parseKbDocument);
    }
  }
  
  // ... other IVaultProvider methods
}

Transition Plan:

Phase 1 (Bootstrap - Now):

HUMAN Corp → FilesystemVaultProvider → /kb/*.md
  ↓
Cursor reads files ✅
MkDocs builds ✅  
GPT script works ✅
Companion accesses via vault API ✅

Phase 2 (Companion Live):

1. Run migration script
2. Copy /kb/*.md → HUMAN Corp's HumanVault
3. Update: provider_id = 'human'
4. Keep /kb/*.md as read-only mirror (Cursor/MkDocs)
5. Source of truth: HumanVault
6. Writes go to vault, sync back to /kb/*.md

Phase 3 (Mature):

- /kb/*.md becomes generated from vault (like reference-site/docs)
- Cursor accesses via API (if needed)
- MkDocs builds from vault export
- Full Living HAIO achieved

Example: Accessing HUMAN's KB

// Get HUMAN Corp's vault provider
const humanVault = await getVaultProvider('did:org:human-corp');

// Query KB documents (reads from /kb/*.md via filesystem provider)
const docs = await humanVault.query('kb', 'documents', {
  where: { classification: 'Internal' },
});

// Same code works after migrating to HumanVaultProvider

Security: Why Filesystem is Restricted

Critical Vulnerabilities if Used in Production:

Path Traversal:

// Attacker config:
{ rootPath: '../../../../etc' }
// Could read /etc/passwd, server secrets, etc.

Zero Tenant Isolation:
- All entities share server filesystem
- Entity A could read Entity B's data
- No encryption at rest
Denial of Service:
- Fill server disk
- Exhaust inodes
- Block other tenants
No Audit Trail:
- Filesystem writes don't log entity identity
- Can't trace modifications
- Compliance failure

Safeguards Implemented:

// Environment check (fails in production)
if (process.env.NODE_ENV === 'production') {
  throw new Error('Filesystem vault not allowed in production');
}

// Explicit enable required
if (process.env.VAULT_FILESYSTEM_ENABLED !== 'true') {
  throw new Error('Filesystem vault not enabled');
}

// Path traversal prevention
if (rootPath.includes('..')) {
  throw new Error('Path traversal attempt blocked');
}

// Whitelist enforcement (database)
SELECT * FROM vault_provider_restrictions
WHERE provider_id = 'filesystem'
  AND allowed_entity_id = 'did:org:human-corp';

Production Alternatives:

Provider	Security	Use Case
human	Zero-knowledge encryption, full audit	Convenience (paid)
dropbox	OAuth, user's account, isolated	Personal/small team
aws	IAM + KMS, entity's account	Enterprise control
azure	AAD + encryption, entity's account	Enterprise (Microsoft)
local	Browser-only, client-side	Free tier (no server risk)

Migration Timeline:

Bootstrap: Filesystem (dev only, HUMAN Corp)
v0.1 Launch: Migrate to human provider (Living HAIO)
Mature: Filesystem remains as dev artifact, never in production

Vault Configuration

Entity configures vault once:

{
  "entity_id": "did:org:acme",
  "vault_provider": "aws",
  "config": {
    "region": "us-west-2",
    "bucket": "acme-human-vault",
    "dynamodb_table": "acme-human-vault-index",
    "credentials": {
      "access_key_id": "...",
      "secret_access_key": "..."
    }
  },
  "encryption_key_id": "did:org:acme#vault-key-1"
}

All extensions/agents automatically use configured vault.

Migration & Portability

Entity can migrate vault providers:

Export vault from current provider (encrypted)
Configure new vault provider
Import data to new provider
Update vault pointer in Passport
All extensions/agents automatically use new vault

Zero downtime migration - HUMAN provides migration tools.

Implementation

Location: packages/passport-domain/src/vault/

Files:

vault-provider.ts - IVaultProvider interface
vault-factory.ts - Provider registry and factory
vault-storage-api.ts - High-level API for extensions
providers/human-vault.ts - HUMAN-hosted provider
providers/local-vault.ts - Local-only provider
providers/filesystem-vault.ts - Filesystem provider (bootstrap)
providers/TEMPLATE.ts - Template for building connectors

SDK Package: @human/vault-connector-sdk

See Also:

Companion Extension Architecture (kb/10_ai_internal_use_and_companion_spec.md)
Extension SDK (kb/117_companion_extension_sdk_specification.md)

VAULT CONNECTOR ROADMAP

v0.1 (Current - Bootstrap Phase)

Status: Production-Ready (November 2025)

Available Providers:

✅ filesystem - Filesystem vault (HUMAN Corp dev only, security-restricted)
✅ local - Browser-based local-only storage (IndexedDB)
✅ human - HUMAN-hosted encrypted vault (paid tier)

Capabilities:

Basic CRUD operations
Query support (provider-dependent)
Health monitoring
Usage metrics tracking
Provider factory pattern
Security restrictions (filesystem whitelisting)

Limitations:

Consumer storage not yet integrated (Dropbox, Drive, etc.)
No enterprise cloud providers (AWS, Azure, GCP)
No multi-vault support
No vault migration tools
No vault-to-vault sync

Developer Experience:

IVaultProvider interface defined
VaultProviderFactory for registration
TEMPLATE.ts for building connectors
Basic documentation

Use Cases:

HUMAN Corp internal KB
Local-only testing (free tier)
HUMAN-hosted storage (paid tier)

v0.2 (Consumer Storage Integration)

Target: Q1 2026

Primary Goal: Enable popular consumer storage providers as vault backends.

New Providers:

🔄 dropbox - Dropbox connector (recommended for individuals)
🔄 google-drive - Google Drive connector
🔄 icloud - iCloud Drive connector (macOS/iOS)
🔄 onedrive - Microsoft OneDrive connector
🔄 box - Box.com connector (business)

Technical Additions:

OAuth 2.0 flows for each provider
Rate limiting and quota management
Sync conflict resolution
Offline caching layer
Provider-specific optimization

Developer Experience:

Vault Connector SDK public release
Step-by-step connector building guide
Provider certification program
Testing sandbox

Business Model:

Free: Local-only + consumer storage (BYO)
Paid: HUMAN-hosted vault ($20/mo)
Enterprise: Custom pricing

Use Cases:

Individuals use existing storage subscriptions
No vendor lock-in (data portability)
Familiar UX (users already use these providers)

v0.3 (Enterprise Cloud Providers)

Target: Q2 2026

Primary Goal: Enterprise-grade vault options with compliance certifications.

New Providers:

🔄 aws-s3 - AWS S3 + DynamoDB connector
🔄 azure-blob - Azure Blob Storage + CosmosDB connector
🔄 gcp-storage - Google Cloud Storage + Firestore connector
🔄 minio - Self-hosted S3-compatible storage
🔄 ceph - Self-hosted distributed storage

Compliance:

SOC 2 Type II certification
HIPAA compliance
GDPR compliance
Data residency guarantees (region selection)

Features:

Multi-region replication
Encryption key management (BYO keys)
Audit logging (detailed provenance)
Performance optimization (CDN, edge caching)
Disaster recovery (cross-region backup)

Developer Experience:

Infrastructure-as-Code templates (Terraform, Pulumi)
Deployment guides (AWS, Azure, GCP)
Cost estimation tools
Performance benchmarking

Use Cases:

Enterprise customers with existing cloud infrastructure
Data sovereignty requirements
High-volume workloads
Compliance-heavy industries (healthcare, finance)

v1.0 (Multi-Vault & Advanced Features)

Target: Q4 2026

Primary Goal: Multi-vault support, vault migration, advanced vault operations.

Multi-Vault Support:

🔄 Primary + backup vault configuration
🔄 Automatic failover
🔄 Load balancing across vaults
🔄 Vault sharding (data partitioning)
🔄 Hybrid vault (hot/cold storage)

Migration Tools:

🔄 Vault-to-vault migration wizard
🔄 Incremental sync during migration
🔄 Zero-downtime migration
🔄 Data integrity verification
🔄 Rollback capability

Vault Analytics:

🔄 Storage usage dashboard
🔄 Access patterns analysis
🔄 Performance metrics
🔄 Cost optimization suggestions
🔄 Anomaly detection

Advanced Features:

🔄 Vault encryption key rotation
🔄 Vault versioning (time-travel queries)
🔄 Vault search (full-text, semantic)
🔄 Vault access policies (fine-grained)
🔄 Vault webhooks (data change notifications)

Developer Tools:

Vault CLI (human-vault)
Vault SDK (multi-language)
Vault emulator (local testing)
Vault performance profiler

Long-Term Vision (v2.0+)

Decentralized Vaults:

IPFS/Filecoin integration
Blockchain-anchored provenance
Peer-to-peer vault sync
Zero-knowledge proofs for queries

AI-Powered Vaults:

Intelligent data organization
Predictive prefetching
Auto-archival (hot/cold tiering)
Semantic search (vector embeddings)

Vault Marketplace:

Third-party vault providers
Vault provider ratings
Vault cost comparison
Vault performance benchmarks

Federation:

Cross-vault data sharing
Vault-to-vault encryption
Federated identity (vault-based SSO)
Global vault directory

🚀 FUTURE ENHANCEMENTS (Beyond v1.0)

Vault Ecosystem Evolution

Vault as Universal Backend:

All HUMAN data (Passport, KB, Extensions) in vaults
Vault-native collaboration (shared spaces)
Vault versioning and history
Vault branching (like Git)

Privacy-Preserving Computation:

Homomorphic encryption (compute on encrypted data)
Secure multi-party computation
Differential privacy guarantees
Zero-knowledge analytics

Quantum-Ready:

Post-quantum encryption
Quantum-resistant key exchange
Future-proof cryptographic agility

SELECTIVE DISCLOSURE PROTOCOL (HUMAN-SDP)

The Passport implements a flexible, auditable selective disclosure system.

Request Flow:

Step 1 — Requester sends a ProofRequest

{
  "request_id": "xyz",
  "capability": ["nurse-licensed"],
  "purpose": "hospital-employment",
  "min_disclosure": true
}

Step 2 — Passport examines:

requester identity
purpose binding
claim scope
revocation checks
user consents / global preferences

Step 3 — Passport generates proof

The human approves (one tap).

Step 4 — Proof delivered to requester

Contains only:

the requested claim
a signature
a timestamp
a revocation reference

No additional data.

Step 5 — Requester verifies

Against:

the ledger (for revocation)
the DID document (for key validity)
the signature (for authenticity)

CREDENTIAL ISSUANCE & VERIFICATION WORKFLOWS

The Passport is designed to receive Verifiable Credentials (VCs) from authoritative issuers—but in practice, the ecosystem must work before every institution has a VC issuer integrated. This section describes both the ideal state (direct VC issuance) and the pragmatic reality (bridging mechanisms for early adoption).

The Ideal Flow: Direct VC Issuance

When an institution (employer, university, licensing board, healthcare provider) has native HUMAN integration:

1. User Initiates Verification

User (in Passport): "Verify my nursing license"
  ↓
Passport: Opens issuer portal
  ↓
California Board of Nursing: "Authenticate yourself"
  ↓
User: Logs in (existing credentials with Board)
  ↓
Board: "Issue license credential to which identity?"
  ↓
User's Passport: Provides DID (did:human:sarah-abc123)
  ↓
Board: Signs VC with board's private key
  ↓
VC delivered to Passport (encrypted)
  ↓
Passport: Stores VC in vault, anchors hash to ledger
  ↓
Capability Graph: Updates weight, routing eligibility changes

Technical Protocol:

// Step 1: User initiates request
POST /verify/nursing-license
{
  "issuer": "did:org:california-board-nursing",
  "credentialType": "ProfessionalLicense",
  "holderDID": "did:human:sarah-abc123"
}

// Step 2: OAuth redirect to issuer
Redirect → https://nursing.ca.gov/oauth/authorize?
  client_id=human&
  redirect_uri=humanpassport://credential/receive&
  scope=issue_license_vc

// Step 3: User authenticates at issuer (their system)

// Step 4: Issuer issues VC (W3C VC standard)
{
  "@context": ["https://www.w3.org/2018/credentials/v1"],
  "type": ["VerifiableCredential", "ProfessionalLicense"],
  "issuer": "did:org:california-board-nursing",
  "issuanceDate": "2025-12-01T00:00:00Z",
  "expirationDate": "2027-12-01T00:00:00Z",
  "credentialSubject": {
    "id": "did:human:sarah-abc123",
    "licenseNumber": "RN-123456",
    "licenseType": "Registered Nurse",
    "state": "California",
    "status": "active"
  },
  "proof": {
    "type": "Ed25519Signature2020",
    "created": "2025-12-01T10:15:00Z",
    "proofPurpose": "assertionMethod",
    "verificationMethod": "did:org:california-board-nursing#key-1",
    "jws": "eyJhbGc...signature"
  }
}

// Step 5: Passport receives and stores
// - Encrypts VC with user's vault key
// - Stores in local vault
// - Anchors hash to ledger: sha256(VC) → 0x3f7a...
// - Updates Capability Graph

// Step 6: Selective disclosure on-demand
// User can now prove "I'm a licensed RN" without revealing:
// - License number, personal details, full VC content

Security Properties:

User authenticates directly with issuer (HUMAN not involved)
Issuer never sees user's private keys
HUMAN never sees VC plaintext (only hash)
User can revoke proof-sharing anytime
Multi-device sync via encrypted vault

The Pragmatic Reality: Pre-Integration Workflows

Before native integrations exist, HUMAN uses bridging mechanisms to enable verification:

Method 1: Document Upload + Manual Review

For: Credentials from institutions without API access (smaller universities, international licenses, specialized certifications)

Flow:

User: Uploads PDF/image of credential
  ↓
HUMAN Verification Service: 
  - OCR extraction
  - Document authenticity checks
  - Format validation against known templates
  - Human reviewer spot-checks
  ↓
Internal Attestation Issued:
  - issuer: "did:org:human-verification-service"
  - type: "DocumentVerification"
  - confidence: "medium" (0.4-0.6)
  ↓
Capability Graph: Updates with human-verified status
  ↓
User: Can access mid-tier opportunities while waiting for direct verification

Limitations:

Not as strong as issuer-direct VCs
Vulnerable to sophisticated forgeries
Requires HUMAN staff time
Temporary solution until integration exists

Safeguards:

Staff trained on common document formats
Cross-reference with public registries where available
Mark as "human_verified" not "issuer_verified"
Weight capped at 0.50-0.60 (lower than direct VC)
Retroactive upgrade when integration launches

Method 2: API Verification (No VC, Just Lookup)

For: Institutions with public registries but no VC capability (many licensing boards)

Flow:

User: Claims license number "RN-123456"
  ↓
HUMAN: Queries public registry API
  GET https://api.rn.ca.gov/verify?license=RN-123456
  ↓
Registry: Returns { "status": "active", "name": "Sarah Johnson", "expiration": "2027-12-01" }
  ↓
HUMAN: Compares name with Passport identity claims
  ↓
If match: Issue internal VC signed by HUMAN
  - issuer: "did:org:human-api-verifier"
  - type: "APIVerifiedCredential"
  - confidence: "high" (0.6-0.7)
  ↓
Capability Graph: Updates with api-verified status

Advantages:

Automated (no human review needed)
Instant verification
Can re-check periodically (detect revocations)

Limitations:

HUMAN is intermediary (not issuer-direct)
Privacy concern: HUMAN queries on user's behalf
API rate limits
Not all registries have public APIs

Future Path:

When institution adds VC support → migrate to direct issuance
Historical API-verified claims retained for provenance

Method 3: Employer Integration via Data Agreements

For: Large employers willing to share employment verification

Flow:

User: Authorizes Meta to issue employment credential
  ↓
Meta HRIS: API integration with HUMAN
  POST /credentials/employment
  {
    "employee_id": "encrypted",
    "holder_did": "did:human:marcus-xyz789",
    "employment": {
      "role": "Senior Software Engineer",
      "department": "AI Infrastructure",
      "start_date": "2019-06-15",
      "end_date": "2023-12-31",
      "verified_skills": ["Python", "Distributed Systems"]
    }
  }
  ↓
HUMAN: Wraps as VC signed by Meta's DID
  - issuer: "did:org:meta"
  - Direct from employer
  - Strong verification (0.7-0.8)
  ↓
User's Passport: Receives and stores

Advantages:

Direct from authoritative source
Can include rich metadata (role, skills, performance)
Automated onboarding for large employers

Privacy Considerations:

User explicitly consents to each data element shared
Selective disclosure: User can prove "worked at Meta" without revealing dates, salary, performance reviews
User can revoke employer's ability to update credential

Credential Lifecycle Management

Credentials evolve over time:

Issuance → Active → Expiring → Expired/Revoked

Active Credential

{
  "credential_id": "vc:nursing:RN-123456",
  "status": "active",
  "issued": "2025-12-01",
  "expires": "2027-12-01",
  "weight": 0.80,
  "routing_eligible": true
}

90 Days Before Expiration

{
  "status": "expiring_soon",
  "notification": "Your nursing license expires in 90 days. Renew now to avoid service interruption.",
  "weight": 0.80,  // Still full weight
  "routing_eligible": true
}

After Expiration

{
  "status": "expired",
  "expired_date": "2027-12-01",
  "weight": 0.00,  // Zero weight
  "routing_eligible": false,
  "archived": true,  // Kept for provenance, not used for matching
  "notification": "License expired. Upload renewal to regain access."
}

After Revocation

{
  "status": "revoked",
  "revoked_date": "2026-03-15",
  "revoked_by": "did:org:california-board-nursing",
  "reason": "License suspended pending investigation",
  "weight": 0.00,
  "routing_eligible": false,
  "appeals_process": "Contact issuer for resolution"
}

Onboarding Experience Examples

Example 1: Healthcare Professional (High Verification Requirements)

Day 1 - Profile Creation:

User creates Passport (device keys generated)
Self-reports: RN license, 5 years experience, BSN degree
System creates capability nodes (all weight: 0.15-0.25)
Immediate access: Can browse marketplace, read training materials
No access: Patient-facing tasks, PHI workflows

Day 1 - Document Upload:

User uploads nursing license scan
HUMAN verification queue (24-hour SLA)
Weight increases to 0.45
Unlocks: Non-critical tasks, training assignments

Day 3 - Issuer Verification:

California Board of Nursing integration completes
Direct VC issued
Weight jumps to 0.80
Unlocks: Patient triage, medication review, HIPAA workflows, full pay tier

Week 2 - Behavioral Evidence:

Completes 20 triage tasks successfully
New capabilities emerge: "escalation judgment" (0.68), "pattern recognition" (0.71)
These capabilities have no credential equivalent but are proven through performance
Unlocks: Complex cases, mentorship roles, premium opportunities

Example 2: Software Engineer (Moderate Verification)

Day 1 - Resume Import:

Connects LinkedIn/GitHub
Self-reports: Python, AWS, 7 years experience
Capability nodes created (weight: 0.20-0.30)
Immediate access: Browse projects, starter tasks

Day 1 - GitHub Integration:

Connects GitHub account (2000+ contributions)
Automated analysis of code quality
Skills verified via commit history
Weight increases to 0.50
Unlocks: Junior-level tasks, code review assignments

Week 1 - Employer Verification:

Meta confirms employment via API
Skills verified by authoritative source
Weight increases to 0.70
Unlocks: Senior-level tasks, architecture reviews

Week 2 - Performance Exceeds Credentials:

Completes 5 ML infrastructure projects
Peer reviews average 4.8/5
Behavioral evidence (weight: 0.82) exceeds credential (weight: 0.70)
System routes increasingly complex work based on proven capability not just credentials

Example 3: Entry-Level Worker (Minimal Credentials)

Day 1 - Onboarding:

No degree, no certifications
Self-reports: "good at organizing things", "fast learner"
Minimal capability graph (weight: 0.10)
Immediate access: Academy training modules (free)

Week 1 - Training Completions:

Completes 10 Academy modules
Micro-attestations accumulate
Capabilities emerge: "data entry" (0.35), "pattern following" (0.40)
Unlocks: Paid micro-tasks, data labeling work

Month 1 - Task Performance:

Completes 200 data labeling tasks
High accuracy (95%+)
Capabilities strengthen: "attention to detail" (0.65), "quality consistency" (0.68)
Unlocks: Higher-value work, training opportunities, skill progression paths

Month 3 - Upskilling:

Academy identifies growth path: data labeling → data analysis → ML operations
Completes advanced training
Task variety increases
Earnings grow 3x
No credentials required - entire progression based on demonstrated capability

Privacy & Consent in Credential Flows

Every credential operation requires explicit user consent:

Issuance Consent:

"California Board of Nursing wants to issue your license credential.

This will share:
✓ Your DID (public identifier)
✓ License number and status
✗ NOT your home address
✗ NOT your personal contact info

Allow? [One-Time] [Always] [Never]"

Disclosure Consent:

"Memorial Hospital wants to verify your nursing license.

This will share:
✓ License type and state
✓ License status (active/expired)
✓ Expiration date
✗ NOT your license number
✗ NOT your work history

Allow? [One-Time] [For This Employer] [Never]"

Revocation Rights:

User can revoke at any time:
- Employer access to work history
- Hospital access to credentials
- Verification service access to documents
- Any third-party proof previously shared

Effect: Immediate removal from verifier's cache,
attestation marked invalid on ledger

Multi-Device Credential Sync

Credentials sync securely across devices:

Sync Architecture:

iPhone (primary device):
  - Holds HumanRootKey (in Secure Enclave)
  - Encrypts all VCs with vault key
  - Syncs encrypted vault to user's chosen cloud
  
Mac (secondary device):
  - Holds derived DeviceKey
  - Downloads encrypted vault from cloud
  - Decrypts using keys derived from HumanRootKey (via biometric)
  - Can generate proofs locally
  
Watch (tertiary device):
  - Holds limited-scope key
  - Can prove subset of credentials (e.g., "over 18", "employee")
  - Cannot access full vault

Security Properties:

Each device has unique key
Lost device can be revoked without affecting others
Cloud provider never sees plaintext credentials
Offline proof generation on any device

Summary: Credential Verification in the Real World

The Passport credential system is designed for both the ideal future and the messy present:

Ideal Future (Direct VC Issuance):

Institutions issue VCs directly
Zero HUMAN intermediation
Instant verification
Maximum trust (0.7-0.85 weight)

Pragmatic Present (Bridging Mechanisms):

Document uploads with human review
API verification where available
Employer data agreements
Progressive trust model (0.3-0.6 weight)
Automatic upgrades when integrations launch

Universal Truth:

Behavioral evidence can exceed credentials - Proven capability beats claimed capability
User always owns and controls their credentials
Selective disclosure protects privacy
Revocation is instant and absolute
Multi-device sync is secure and seamless

The Passport makes credentials portable, verifiable, and privacy-preserving - while working in the real world today, not just the imagined world of tomorrow.

PERMISSIONS & DELEGATION ARCHITECTURE

"How authority flows through the HUMAN protocol"

The Passport isn't just an identity container — it's an authority management system. It governs:

What actions a Passport holder can perform
Who can act on their behalf (delegation)
What constraints apply to delegated authority
How permissions are granted, verified, and revoked

This section specifies how HUMAN implements capability-based access control (CBAC) with cryptographic delegation.

THE PERMISSION MODEL

Unlike traditional role-based access control (RBAC), HUMAN uses capability-based access control where permissions are:

Explicitly granted (not inferred from roles)
Cryptographically signed (provable and non-repudiable)
Scoped and constrained (limited by resource, action, time, geography, risk level)
Tied to capabilities (permission requires proven capability)

Permission Grant Structure

/**
 * A permission grant tied to a Passport
 */
export interface PermissionGrant {
  /** Unique grant ID */
  grantId: string;
  
  /** Who holds this permission (Passport DID) */
  granteeId: PassportId;
  
  /** Who granted this permission (Passport DID or system) */
  granterId: PassportId | 'system';
  
  /** Scope of permission */
  scope: PermissionScope;
  
  /** Allowed actions */
  allowedActions: string[];
  
  /** Constraints on permission */
  constraints: PermissionConstraints;
  
  /** When permission was granted */
  grantedAt: Date;
  
  /** When permission expires */
  expiresAt?: Date;
  
  /** Revoked? */
  revoked: boolean;
  
  /** Revocation timestamp (if revoked) */
  revokedAt?: Date;
  
  /** Reason for revocation */
  revocationReason?: string;
  
  /** Cryptographic proof */
  proof: PermissionProof;
}

export interface PermissionScope {
  /** Resource type this permission applies to */
  resourceType: 'task' | 'delegation' | 'capability' | 'notification' | 'kb_document' | 'system';
  
  /** Specific resource IDs (if not all) */
  resourceIds?: string[];
  
  /** Organizational scope */
  orgId?: string;
  
  /** Team scope */
  teamId?: string;
  
  /** Capability requirements (must have these capabilities to use permission) */
  requiredCapabilities?: string[];
}

export interface PermissionConstraints {
  /** Maximum number of times this permission can be used */
  maxUses?: number;
  
  /** Time window when permission is valid */
  validDuring?: {
    startHour: number; // local time
    endHour: number;
    daysOfWeek: number[];
  };
  
  /** Geographic constraints */
  geoConstraints?: {
    allowedCountries?: string[];
    deniedCountries?: string[];
    allowedRegions?: string[];
  };
  
  /** Risk level constraints */
  maxRiskLevel?: 'low' | 'medium' | 'high';
  
  /** Requires additional approval? */
  requiresApproval?: {
    approverId: PassportId;
    approvalType: 'pre' | 'post';
    timeoutMinutes: number;
  };
  
  /** IP address constraints (for security-sensitive operations) */
  ipWhitelist?: string[];
  
  /** Device constraints (only from trusted devices) */
  trustedDevicesOnly?: boolean;
}

export interface PermissionProof {
  /** Cryptographic signature from granter */
  signature: string;
  
  /** Public key of granter */
  granterPublicKey: string;
  
  /** Hash of permission grant */
  grantHash: string;
  
  /** Ledger anchor (if applicable) */
  ledgerAnchor?: string;
  
  /** Signature algorithm */
  algorithm: 'ed25519' | 'secp256k1';
}

Permission Verification Algorithm

/**
 * Verify if a Passport holder has permission to perform an action
 */
async function verifyPermission(
  passportId: PassportId,
  action: string,
  resource: { type: string; id?: string },
  context: PermissionContext
): Promise<PermissionVerificationResult> {
  // 1. Get all active permissions for this Passport
  const permissions = await getActivePermissions(passportId);
  
  // 2. Filter to permissions for this resource type
  const relevantPermissions = permissions.filter(p => 
    p.scope.resourceType === resource.type &&
    (!p.scope.resourceIds || p.scope.resourceIds.includes(resource.id!)) &&
    !p.revoked &&
    (p.expiresAt ? p.expiresAt > new Date() : true)
  );
  
  // 3. Check if any permission allows this action
  for (const permission of relevantPermissions) {
    if (!permission.allowedActions.includes(action)) {
      continue;
    }
    
    // 4. Verify constraints
    const constraintCheck = await verifyConstraints(
      permission.constraints,
      context
    );
    
    if (!constraintCheck.satisfied) {
      continue; // Try next permission
    }
    
    // 5. Verify capability requirements
    if (permission.scope.requiredCapabilities) {
      const hasCapabilities = await verifyCapabilities(
        passportId,
        permission.scope.requiredCapabilities
      );
      
      if (!hasCapabilities) {
        return { 
          allowed: false, 
          reason: 'insufficient_capability',
          requiredCapabilities: permission.scope.requiredCapabilities
        };
      }
    }
    
    // 6. Verify cryptographic proof
    const proofValid = await verifyCryptographicProof(
      permission.proof,
      permission.granterId
    );
    
    if (!proofValid) {
      return { allowed: false, reason: 'invalid_proof' };
    }
    
    // 7. Permission verified
    return { 
      allowed: true, 
      permission: permission,
      grantedBy: permission.granterId
    };
  }
  
  // 8. No valid permission found
  return { allowed: false, reason: 'no_permission' };
}

THE DELEGATION MODEL

Delegation is the mechanism by which one Passport holder temporarily transfers authority to another.

Delegation in HUMAN is:

Explicit — Delegator must cryptographically sign delegation terms
Consensual — Delegate must accept delegation
Constrained — Delegator sets scope, duration, and limits
Auditable — All delegated actions logged with provenance
Revocable — Delegator can revoke at any time (if revocable delegation)

Delegation Structure

/**
 * Active delegation state
 */
export interface ActiveDelegation {
  /** Unique delegation ID */
  delegationId: string;
  
  /** Delegator (who is delegating) */
  delegatorId: PassportId;
  
  /** Delegate (who receives authority) */
  delegateId: PassportId;
  
  /** Scope of delegation */
  scope: DelegationScope;
  
  /** Start of delegation period */
  startedAt: Date;
  
  /** End of delegation period */
  endsAt: Date;
  
  /** Reason for delegation */
  reason: string; // e.g., "Vacation", "Overflow", "Training"
  
  /** Delegation constraints */
  constraints: DelegationConstraints;
  
  /** Can delegate be revoked early? */
  revocable: boolean;
  
  /** Current status */
  status: 'pending_acceptance' | 'active' | 'completed' | 'revoked' | 'expired';
  
  /** Cryptographic proof */
  proof: DelegationProof;
  
  /** Actions taken under this delegation */
  actionsLog: DelegatedAction[];
}

export interface DelegationScope {
  /** What can be delegated */
  delegatedActions: string[];
  
  /** Specific tasks/resources (or all if empty) */
  resourceIds?: string[];
  
  /** Resource types that can be delegated */
  resourceTypes?: string[];
  
  /** Task types that can be delegated */
  taskTypes?: string[];
  
  /** Maximum risk level delegate can handle */
  maxRiskLevel: 'low' | 'medium' | 'high';
  
  /** Can delegate further delegate? (sub-delegation) */
  allowSubDelegation: boolean;
}

export interface DelegationConstraints {
  /** Delegate must have these capabilities */
  requiredCapabilities: string[];
  
  /** Delegator receives notifications of delegate actions? */
  notifyDelegator: boolean;
  
  /** Notification frequency */
  notificationFrequency?: 'realtime' | 'daily_digest' | 'weekly_digest';
  
  /** Requires delegator approval for certain actions? */
  requiresApproval?: {
    forActions: string[];
    timeoutMinutes: number;
  };
  
  /** Maximum number of tasks delegate can accept */
  maxTasks?: number;
  
  /** Maximum number of actions per day */
  maxActionsPerDay?: number;
  
  /** Geographic constraints */
  geoConstraints?: {
    allowedCountries?: string[];
  };
  
  /** Time constraints (when delegate can act) */
  timeConstraints?: {
    allowedHours: number[]; // Hours of day (0-23)
    allowedDaysOfWeek: number[]; // Days (0-6)
    timezone: string;
  };
}

export interface DelegationProof {
  /** Cryptographic signature from delegator */
  delegatorSignature: string;
  
  /** Acceptance signature from delegate */
  delegateSignature: string;
  
  /** Hash of delegation terms */
  delegationHash: string;
  
  /** Ledger anchor */
  ledgerAnchor: string;
  
  /** When delegation was signed */
  signedAt: Date;
  
  /** When delegate accepted */
  acceptedAt?: Date;
}

export interface DelegatedAction {
  actionId: string;
  action: string;
  resourceType: string;
  resourceId: string;
  performedAt: Date;
  delegateId: PassportId;
  delegatorId: PassportId;
  result: 'success' | 'failure' | 'pending_approval';
  provenance: ProvenanceRecord;
}

Delegation Workflow

Step 1: Delegator Initiates Delegation

Alice (Senior Legal Reviewer) → Companion:
"I'm going on vacation for 2 weeks. Delegate my tasks to Bob."

Companion: "Let me set up delegation to Bob (did:human:bob-xyz789).
            What constraints should I apply?"

Alice: "Only legal reviews, medium risk or lower, max 50 tasks."

Companion: "Got it. Creating delegation proposal..."

Step 2: Companion Constructs Delegation

const delegation: ActiveDelegation = {
  delegationId: 'del_abc123',
  delegatorId: 'did:human:alice-abc123',
  delegateId: 'did:human:bob-xyz789',
  scope: {
    delegatedActions: ['task:accept', 'task:review', 'task:complete'],
    resourceTypes: ['task'],
    taskTypes: ['legal_review', 'compliance_check'],
    maxRiskLevel: 'medium',
    allowSubDelegation: false
  },
  startedAt: new Date('2025-12-01'),
  endsAt: new Date('2025-12-15'),
  reason: 'Vacation - December 1-15',
  constraints: {
    requiredCapabilities: ['legal_review', 'contract_analysis'],
    notifyDelegator: true,
    notificationFrequency: 'daily_digest',
    maxTasks: 50,
    requiresApproval: {
      forActions: ['escalation:approve'],
      timeoutMinutes: 60
    }
  },
  revocable: true,
  status: 'pending_acceptance',
  proof: {
    // Alice signs delegation terms
    delegatorSignature: 'sig_alice_...',
    delegationHash: 'sha256(...)',
    signedAt: new Date(),
    // ... (to be completed by delegate)
  },
  actionsLog: []
};

Step 3: Delegate Receives Notification

Bob's Companion: 
🔔 Delegation Request

Alice has asked you to act on her behalf during Dec 1-15:
• Tasks: Legal reviews, compliance checks
• Max risk: Medium
• Max tasks: 50
• You'll notify Alice daily
• You must get her approval for escalations

Required capabilities:
✓ Legal Review (you have this)
✓ Contract Analysis (you have this)

[Accept] [Decline] [View Details]

Step 4: Delegate Accepts

// Bob accepts
delegation.status = 'active';
delegation.proof.delegateSignature = 'sig_bob_...';
delegation.proof.acceptedAt = new Date();

// Anchor to ledger
delegation.proof.ledgerAnchor = await anchorToLedger(delegation);

// Log provenance
await logProvenance({
  eventType: 'delegation_activated',
  delegatorId: alice.did,
  delegateId: bob.did,
  delegationId: delegation.delegationId,
  timestamp: new Date()
});

Step 5: Delegate Acts Under Delegation

HumanOS routes a task:
  Task: Legal doc review (medium risk)
  Required: legal_review capability
  
  ↓
  
HumanOS checks: Is Alice available?
  → No, Alice is delegating to Bob (delegation del_abc123)
  
  ↓
  
HumanOS routes to Bob instead
  
  ↓
  
Bob's Companion:
  🔔 New Task (on behalf of Alice)
  Legal document review - vendor contract
  
  Acting as: Alice (delegation del_abc123)
  
  [Accept] [Decline]
  
  ↓
  
Bob accepts and completes task
  
  ↓
  
Logged as delegated action:
{
  actionId: 'act_123',
  action: 'task:complete',
  resourceType: 'task',
  resourceId: 'task_456',
  performedAt: new Date(),
  delegateId: bob.did,
  delegatorId: alice.did,
  result: 'success',
  provenance: {
    actorType: 'human',
    actorId: bob.did,
    actingOnBehalfOf: alice.did,
    delegationId: 'del_abc123',
    // ...
  }
}
  
  ↓
  
Alice receives daily digest:
  "Bob completed 3 tasks on your behalf today:
   - Legal doc review (task_456) ✓
   - Compliance check (task_789) ✓
   - Contract review (task_101) ✓"

Step 6: Delegation Ends

When endDate is reached (or Alice revokes):
  
  delegation.status = 'completed'; // or 'revoked'
  
  ↓
  
HumanOS stops routing tasks to Bob
  
  ↓
  
Alice receives delegation summary:
  "Delegation to Bob (Dec 1-15) completed:
   • 23 tasks completed
   • 2 tasks declined
   • 0 escalations required
   • Average quality score: 0.89
   
   Bob's capability graph updated:
   + Delegation coverage: legal_review
   + Workload management: +0.05"

DELEGATION USE CASES

Use Case 1: Vacation Coverage

Scenario: Alice is going on vacation for 2 weeks.

Solution: Alice delegates her task routing authority to Bob with constraints:

Only task types she normally handles
Max risk level: medium (high-risk tasks wait for her return)
Bob must have required capabilities
Alice receives daily summaries
High-stakes actions require her approval (via async notification)

Outcome: Work continues, Alice isn't interrupted, Bob gains experience, capability graphs update for both.

Use Case 2: Load Balancing

Scenario: Carol is at capacity (fatigue score 0.8) but tasks keep coming.

Solution: HumanOS suggests: "You're at high fatigue. Delegate overflow to David?"

Carol delegates with constraints:

Only low-complexity tasks
Max 10 tasks
David must acknowledge each task
Carol reviews completions next day

Outcome: Carol avoids burnout, David gets additional work, system maintains throughput.

Use Case 3: Training & Mentorship

Scenario: Eve (junior) needs to build capability in "contract_negotiation".

Solution: Frank (senior) delegates limited authority to Eve:

Only low-risk contract reviews
Frank must approve before final submission
Eve proposes, Frank reviews and teaches
All interactions logged

Outcome: Eve builds verifiable capability evidence, Frank's mentorship is tracked, capability graph shows progression.

Use Case 4: Emergency Escalation

Scenario: Grace (on-call supervisor) receives critical escalation at 2am.

Solution: Grace has standing delegation from all team members:

Activate during critical escalations
Override capacity limits
Make decisions on their behalf
Full provenance logging

Outcome: Emergency resolved quickly, all actions attributed correctly, no authorization bottleneck.

PERMISSION & DELEGATION REVOCATION

Permissions and delegations can be revoked:

Immediate Revocation:

await revokePermission({
  grantId: 'perm_123',
  revocationReason: 'Employee terminated',
  revokedBy: 'did:org:company-456',
  effectiveImmediately: true
});

// Result:
// - Permission marked revoked in database
// - Revocation published to distributed revocation list
// - All active sessions using this permission invalidated
// - Ledger anchor created for revocation event

Scheduled Revocation:

await scheduleRevocation({
  delegationId: 'del_abc123',
  revokeAt: new Date('2025-12-15T23:59:59Z'),
  reason: 'Delegation period ended'
});

// Result:
// - Delegation continues until scheduled time
// - Automatic revocation at specified time
// - Delegate notified 24 hours before
// - Delegator receives final summary

PERMISSIONS IN HUMANOS ROUTING

HumanOS checks permissions before routing:

async function routeTask(
  task: WorkforceTask,
  availableResources: ResourceAvailability[]
): Promise<RoutingDecision> {
  // 1. Filter to resources with required capabilities
  let candidates = await filterByCapability(
    availableResources,
    task.requiredCapabilities
  );
  
  // 2. Check permissions for each candidate
  const authorizedCandidates = [];
  
  for (const resource of candidates) {
    const permissionCheck = await verifyPermission(
      resource.resourceId,
      'task:accept',
      { type: 'task', id: task.id },
      {
        riskLevel: task.riskLevel,
        taskType: task.taskType,
        requester: task.requesterId,
        timestamp: new Date()
      }
    );
    
    if (permissionCheck.allowed) {
      authorizedCandidates.push({
        resource,
        permission: permissionCheck.permission,
        isDelegated: !!resource.delegation
      });
    }
  }
  
  // 3. If no authorized candidates, escalate or queue
  if (authorizedCandidates.length === 0) {
    return {
      route: 'escalate',
      reason: 'no_authorized_resources',
      fallbackChain: []
    };
  }
  
  // 4. Select optimal resource (capability + availability + fairness)
  const selected = selectOptimalResource(authorizedCandidates);
  
  // 5. Return routing decision
  return {
    route: 'human',
    selectedResource: selected.resource,
    reasoning: 'Best capability match with authorization',
    isDelegated: selected.isDelegated,
    delegationId: selected.resource.delegation?.delegationId
  };
}

CRYPTOGRAPHIC ANCHORING

All permissions and delegations are anchored to the ledger:

interface PermissionLedgerAnchor {
  /** Permission or delegation ID */
  id: string;
  
  /** Type */
  type: 'permission' | 'delegation' | 'revocation';
  
  /** Hash of the complete grant/delegation/revocation object */
  contentHash: string;
  
  /** Signature from granter/delegator */
  signature: string;
  
  /** Block number (if blockchain) or timestamp anchor */
  anchor: string;
  
  /** When anchored */
  anchoredAt: Date;
}

Why anchor?

Proof of existence — Permission/delegation existed at a specific time
Non-repudiation — Granter/delegator cannot deny granting it
Tamper-evidence — Any modification detected via hash mismatch
Auditability — Regulators can verify permission history

INTEGRATION WITH COMPANION

The Companion is the primary interface for managing permissions and delegations:

Conversational Permission Management:

User: "Give Bob permission to review my tasks while I'm away"

Companion: "I'll create a delegation to Bob. What constraints?"

User: "Only legal reviews, nothing high-risk, max 30 tasks"

Companion: "Done. Bob can now review legal tasks (medium risk or lower)
            for up to 30 tasks. Want to set an end date?"

User: "Yes, December 15th"

Companion: "Delegation active Dec 1-15. I'll notify Bob to accept."

Permission Review:

User: "Who has access to my capability data?"

Companion: "Currently:
            • HUMAN Workforce Cloud (read-only, for task routing)
            • Dr. Martinez (shared via selective disclosure, expires Jan 1)
            • No other active permissions
            
            Revoked permissions (last 90 days):
            • Former employer XYZ Corp (revoked Nov 1)"

PERMISSION MODEL SUMMARY

Key Principles:

Explicit Over Implicit — All permissions must be explicitly granted
Capability-Gated — Permissions require proven capabilities
Constrained By Default — Permissions have scope, time, and risk limits
Cryptographically Signed — All grants provable and non-repudiable
Revocable Always — Humans can revoke permissions instantly
Auditable Completely — Every permission use is logged with provenance

Cross-References:

See: kb/25_workforce_cloud.md - How permissions govern task routing
See: kb/22_humanos_orchestration_core.md - Permission checks in routing
See: packages/workforce-domain - Delegation type definitions
See: packages/passport-domain - Delegation domain types

DEVICE MODEL

The Passport is not stored in a cloud.
It lives across the user's chosen devices, each holding a scoped key.

Device Sync Architecture:

Primary device holds master key
Secondary devices hold derived keys
Cross-device sync via encrypted channel
New device provisioning requires approval from existing device
Lost device can be revoked without losing identity

The identity is portable.
The keys are bound.

This ensures humans never lose themselves, even if they lose a device.

RECOVERY PROTOCOL

If all devices are lost:

Recovery Options:

1. Guardian Recovery (3-of-5 threshold)

5 trusted individuals hold encrypted recovery shards
3 must consent to reconstitute master key
Guardians never see the key itself

2. Biometric + Seed Phrase Recovery

Device-independent biometric verification
Combined with memorized seed phrase
Requires both factors

3. Institutional Recovery (Last Resort)

Government-issued credential + biometric
Time-delayed (30 day waiting period)
Requires multi-party attestation

Recovery is designed to be secure but never impossible.

INTEROPERABILITY MANDATE

The Passport must work with:

Apple Wallet
Google Wallet
W3C Verified Credentials
ISO 18013-5 digital IDs
Smart chips in passports
Medical EHR systems
Enterprise access systems
AI agents directly

HUMAN is a protocol, not a silo.

STANCE ON TOKENIZATION

There is no HUMAN coin.
There is no HUMAN token.
There will never be one.

HUMAN is not a financial instrument.

Identity is not a currency.
Capability is not a commodity.
Access is not a token.

Any technology we use will be:

tokenless
transaction-fee-free for humans
environmentally efficient
built on modern consensus protocols
fully compliant with global regulatory frameworks

We avoid all crypto baggage while retaining the useful cryptography.

TECHNICAL STACK (v0.1)

Identity Layer:

DID: did:human method (W3C compliant)
Keys: ed25519 (migration path to post-quantum)
Vault: AES-256-GCM + ChaCha20-Poly1305
Device binding: Secure Enclave (iOS), TEE (Android), TPM (desktop)

Attestation Layer:

Verifiable Credentials (W3C VC Data Model)
Signature: Ed25519Signature2020
Revocation: Status List 2021
Ledger anchoring: ZK-rollup or L2 (TBD)

Storage Layer:

On-device: Encrypted local storage
Cloud vault: User-selected (iCloud, Google Drive, self-hosted)
Distributed: Optional IPFS/Arweave anchoring

Access Protocol:

Authentication: FIDO2 Passkeys
Authorization: OAuth 2.1 + DID-SIOP
Selective Disclosure: BBS+ signatures or SD-JWT

OPERATIONAL REQUIREMENTS

Issuing authority onboarding
Credential revocation network
Identity recovery network
Fraud monitoring
Governance and standards body
Global compliance rails (GDPR, HIPAA, CCPA, etc.)
Interoperability testing with FIDO, OAuth, OIDC

THE SCI-FI LESSON: ASIMOV AND DICK

Science fiction warned us about identity failures decades ago.

Asimov's Warning

Asimov's robots failed because they followed rules without understanding who they were serving. A command from anyone was a command to obey. Context was missing. The robot didn't know if the human giving orders was qualified, authorized, or even real.

The Passport solves this: Machines finally understand who a human is — cryptographically verified, with demonstrated capabilities, and clear authority boundaries.

Philip K. Dick's Warning

Dick's entire body of work obsessed over one question: How do you prove you're real in a world of forgeries?

In his worlds, identity could be:

Forged
Stolen
Implanted
Erased
Duplicated

The Passport's Selective Disclosure solves this: Identity is provable without being revealed. You can prove you're licensed without showing your address. Prove you're over 18 without revealing your birthdate. Prove you're the person tied to a credential without exposing your full identity.

Dick's nightmare was identity that could be stolen. The Passport makes identity that can be proven but never fully exposed.

See: 16_scifi_lessons_design_philosophy.md for the complete philosophical framework.

WHY THE PASSPORT WINS

The Passport is:

Human-owned (not corporate)
Portable (works everywhere)
Private (selective disclosure)
Permanent (survives company failure)
Verifiable (cryptographically provable)
Free (no cost to humans)
Neutral (works with all systems)

This becomes the global identity standard.

Metadata

Source Sections:

Lines 31,858-32,240: SECTION 80 — Passport Protocol v0.1
Lines 32,594-32,932: SECTION 82 — HUMAN Passport Architecture v0.1

Merge Strategy: CONSOLIDATE - Merged both Passport specifications, removed overlapping architecture descriptions

Strategic Purposes:

Building (primary)
Companion
Product Vision

Cross-References (Related Identity & Passport Files):

See: 04_the_five_systems.md - Passport overview in Five Systems
See: 05_the_human_protocol.md - Passport in the HUMAN loop
See: 21_capability_graph_engine.md - Capability Graph integration
See: 30_device_mesh_and_standards.md - Multi-device sync & standards
See: 49_devops_and_infrastructure_model.md - Edge-first/device-first architecture (Passport lives on-device)
See: 87_human_identity_architecture_passport_spec.md - Deep identity architecture
See: 88_human_key_fabric_cryptographic_backbone.md - Cryptographic backbone
See: 96_api_specification_passport.md - Passport API specification

User Stories (Real-World Examples):

Story 11: "The last form Leila ever filled out" — Passport as portable, reusable identity with selective disclosure (kb/12_human_ecosystem_storybook.md, PRD Section 1.1)
Story 19: "The parent who gave their kid safe internet access" — Time-bounded, scope-limited delegation (kb/12_human_ecosystem_storybook.md, PRD Section 3.1.1)
Story 20: "The CEO who went on vacation and actually unplugged" — Executive delegation with automatic expiry (kb/12_human_ecosystem_storybook.md, PRD Section 3.1.1)
Story 23: "The security breach that wasn't catastrophic" — Per-device key architecture with instant revocation (kb/12_human_ecosystem_storybook.md, PRD Section 4.9.1)
Story 26: "The nurse who worked in three countries in one year" — Cross-border credential portability, cryptographic attestations across jurisdictions (kb/12_human_ecosystem_storybook.md, PRD Section 3.1.2)
Story 27: "The bank that stopped freezing innocent accounts" — Customer context proofs (travel notices) for fraud detection (kb/12_human_ecosystem_storybook.md, PRD Section 3.3.1)
See also: kb/124_human_v01_production_prd.md for complete Passport implementation with user stories

Line Count: ~650 lines (consolidated from ~722 lines across SECTION 80+82)
Consolidation Savings: ~70 lines
Extracted: November 24, 2025
Version: 2.0 (Complete Reorganization with Consolidation)

20. PASSPORT IDENTITY LAYER

MVP: PASSPORT-LITE (Foundation Phase, Week 1-2)

What Passport-Lite Includes

Passport-Lite Implementation

Why Passport-Lite Matters

CRYPTOGRAPHIC ARCHITECTURE

Overview

Key Management Strategy

Cryptographic Primitives

DID Method Specification

Key Wrapping (KEK-DEK Pattern)

Key Rotation Strategy

Threat Model

Risk Acceptance (v0.1)

Security Audit & Compliance

IDENTITY AUTHORITY & MINTING RULES

Purpose

Core Principle

The Three Identity Types

1. Human Passport (Sovereign Identity)

2. Org Passport (Institutional Identity)

3. Agent Passport (Delegated Execution Identity)

Identity Minting Authority Matrix

CRITICAL: HUMAN UNIQUENESS (ONE PASSPORT PER HUMAN)

Multi-Layered Approach (Progressive Verification)

Layer 1: Device Attestation (v0.1 MVP)

Layer 2: Biometric Binding (v0.2 - Strong Barrier)

Layer 3: Social Attestation (v0.3 - Web of Trust)

Layer 4: Proof of Personhood (v1.0 - Cryptographic Uniqueness)

Decision Matrix: Which Verification Layer When?

Attack Scenarios & Mitigations

Attack 1: Device Farm (100 phones)

Attack 2: Biometric Spoofing (3D face model)

Attack 3: Identical Twins

Implementation Roadmap

v0.1 (MVP - Month 1-3)

v0.2 (Public Beta - Month 4-6)

v0.3 (Production - Month 7-12)

v1.0 (Enterprise/Gov - Year 2+)

Key Principles

FAQ: Human Uniqueness

IDENTITY VERIFICATION (PROVING YOU ARE WHO YOU CLAIM TO BE)

Two Distinct Identity Problems

Tiered Identity Verification (Progressive Trust)

Tier 1: Org-Verified Passport (PRIMARY PATH - Low Friction)

Tier 2: KYC-Verified Passport (Self-Signup - Higher Friction)

Tier 3: Credential-Verified (Professional Licenses)

YOUR PRIMARY USE CASE: Enterprise Onboarding

Comparison: Uniqueness vs Identity

COMPLETE IDENTITY VERIFICATION MATRIX: ALL USE CASES

Enterprise Employee Workflows (Tier 1: Org-Verified)

Healthcare Workflows (Tier 3: Credential-Verified)

Financial/Fraud Workflows (Tier 2: KYC-Verified)

Workforce Cloud (Mixed Tiers)

AI Labs & Developer Workflows (Tier 0-1)

Students & Educational Workflows (Tier 1: Institution-Verified)

Unemployed & Job Seekers (Tier 0-2)

Retired Individuals (Tier 0-2)

Newborns & Parent-Controlled Passports (Tier 3: Birth Certificate)

Children & Graduated Autonomy (Tier 1-3: School or Birth Certificate)

Self-Employed & Small Business Owners (Tier 2-3)

NEW USE CASES IDENTIFIED (Need Documentation)

PROOF-OF-CONCEPT TEST MATRIX

Test Suite Structure

IMPLEMENTATION PRIORITY

Phase 1: Core Identity Flows (Week 1-2)

Phase 2: Independent Workers (Week 3-4)

Phase 3: Complete Matrix (Month 2)

Delegation Hierarchy (Chain of Trust)

Self-Hosted Deployment Invariants

✅ Permitted Operations

❌ Explicitly Forbidden Operations

Threat Model & Breach Blast Radius Analysis

Human Device Compromise

Org Infrastructure Compromise

Agent Runtime Compromise

HUMAN Cloud Compromise

Open Source & Forking Safety

Why Forking Can't Break Identity Sovereignty

Verification vs Authority