Skip to content
DID.is Documentation

Reading the Dossier (4 Progressive Levels)

4. Reading the Identity Dossier: Progressive Disclosure

Section titled “4. Reading the Identity Dossier: Progressive Disclosure”

When an identifier resolves, DID.is presents an Identity Dossier (/[...did]). The dossier is built on Next.js 16 / React 19 and employs a strict Progressive Disclosure architecture across four forensic layers:

┌────────────────────────────────────────────────────────┐
│  LEVEL 1: EXECUTIVE VERDICT & EVIDENCE DIMENSIONS      │
│  Plain-language outcome headline + 7 orthogonal checks │
└──────────────────────────┬─────────────────────────────┘
                           ▼
┌────────────────────────────────────────────────────────┐
│  LEVEL 2: INTERACTIVE FORENSIC EVIDENCE GRAPH          │
│  Directed graph: Verified, Observed, Declared, Failed  │
└──────────────────────────┬─────────────────────────────┘
                           ▼
┌────────────────────────────────────────────────────────┐
│  LEVEL 3: EXECUTION TELEMETRY WATERFALL                │
│  Microsecond-precision monotonic stage timings (SSE)   │
└──────────────────────────┬─────────────────────────────┘
                           ▼
┌────────────────────────────────────────────────────────┐
│  LEVEL 4: SUBSTRATE INSPECTOR & TIME MACHINE DIFF      │
│  Raw JSON, Multikey bytes, TLS certs, Log history diff │
└────────────────────────────────────────────────────────┘

Overview of the Progressive Disclosure Architecture

Section titled “Overview of the Progressive Disclosure Architecture”

The Identity Dossier layout in apps/web/src/components/identity/IdentityDossier.tsx includes:

  • Sticky Table of Contents (Desktop Sidebar): Direct anchor navigation between Verdict (#verdict), Evidence graph (#graph), Telemetry (#telemetry), Substrate (#substrate), Time machine (#history), and Put it to work (#next).
  • Header Facts Bar: Displays the check breakdown (X confirmed · Y need attention · Z not confirmed), DID method (did:...), controller (itself or external DID), observation timestamp, and cache status.
  • Direct Action Toolbar:
    • Re-resolve live: Connects to the real-time SSE stream with animated spinner and live scanline.
    • Permalink: Copies the canonical URL to the clipboard.
    • W3C document: Opens the raw W3C DID document in a new tab.
    • Evidence JSON: Opens the comprehensive DID.is API evidence envelope in a new tab.

Level 1: Executive Verdict & Summary

Section titled “Level 1: Executive Verdict & Summary”

Level 1 provides decision-makers with an immediate, plain-language assessment:

  1. Outcome Badge:
    • RESOLVED: Identifier resolved cleanly; all structural and method requirements passed.
    • RESOLVED_WITH_WARNINGS: Identifier resolved, but non-fatal structural issues were detected (e.g., undeclared JSON-LD contexts, missing reciprocal service IDs).
    • DEACTIVATED: The identity has been authoritatively terminated (returns HTTP 410 Gone with deactivated: true).
  2. Verdict Headline: A synthesized, single-sentence forensic summary (e.g., “Cryptographically controlled via Ed25519, origin-bound to identity.foundation.”).
  3. Verdict Statements: Supporting bullet points explaining specific capabilities confirmed during resolution.
  4. Summary Grouping Section: Summarizes findings across three clear categories.

Plain-Language Findings: Confirmed, Needs Attention, Not Confirmed

Section titled “Plain-Language Findings: Confirmed, Needs Attention, Not Confirmed”

To ensure accessibility for compliance officers, business stakeholders, and non-cryptographers, Level 1 groups all dimensional findings into three human-readable categories without engineering jargon:

┌────────────────────────────────────────────────────────────────────────────────────────┐
│                          PLAIN-LANGUAGE FINDINGS OVERVIEW                              │
├────────────────────┬──────────────────────────────────┬────────────────────────────────┤
│ Category           │ Human Meaning                    │ Technical Condition            │
├────────────────────┼──────────────────────────────────┼────────────────────────────────┤
│ Confirmed          │ We verified the math or checked  │ State is ESTABLISHED or        │
│ (Green Tag)        │ the certificate directly; it     │ SELF_CERTIFYING.               │
│                    │ passed completely.               │                                │
├────────────────────┼──────────────────────────────────┼────────────────────────────────┤
│ Needs attention    │ Something is broken, expired, or │ State is FAILED or             │
│ (Amber / Red Tag)  │ non-conformant; review before    │ INDETERMINATE.                 │
│                    │ placing trust in this identity.  │                                │
├────────────────────┼──────────────────────────────────┼────────────────────────────────┤
│ Not confirmed      │ Property is absent or cannot be  │ State is NOT_ESTABLISHED       │
│ (Slate Neutral Tag)│ proved; no cryptographic proof   │ (or NOT_APPLICABLE).           │
│                    │ exists for this dimension.       │                                │
└────────────────────┴──────────────────────────────────┴────────────────────────────────┘

1. Confirmed (Green Mark)

Section titled “1. Confirmed (Green Mark)”
  • Plain Language Meaning: “This check passed active cryptographic or protocol verification.”
  • What it tells you: The public keys actually exist on mathematically sound elliptic curves, the signatures checked out against the data, or the HTTPS certificate is currently trusted by Mozilla’s root authority. You can rely on this technical property.
  • Applicable States: ESTABLISHED or SELF_CERTIFYING.

2. Needs attention (Amber / Red Mark)

Section titled “2. Needs attention (Amber / Red Mark)”
  • Plain Language Meaning: “Something failed or has an active warning that requires your attention.”
  • What it tells you: An attempted check did not succeed. This could mean a cryptographic signature did not match the document, a revocation status list timed out, a security certificate has expired, or the document contains malformed JSON-LD syntax. You should inspect the specific evidence before relying on this identity.
  • Applicable States: FAILED or INDETERMINATE.

3. Not confirmed (Slate Neutral Mark)

Section titled “3. Not confirmed (Slate Neutral Mark)”
  • Plain Language Meaning: “This property is either absent, not claimed, or not provable by this identifier type.”
  • What it tells you: This does not mean the identity is malicious or broken. Rather, it means that no cryptographic evidence exists for this specific test. For example:
    • An independent website does not prove corporate registry incorporation (organization: NOT_ESTABLISHED).
    • A standard did:web identifier is controlled by web hosting and does not use cryptographic update keys (control: NOT_ESTABLISHED).
    • A domain that does not publish a DIF DID Configuration credential has no verified bidirectional link (origin: NOT_ESTABLISHED).
  • Applicable States: NOT_ESTABLISHED (or NOT_APPLICABLE for checks that do not apply to the method).

The Seven Evidence Dimensions

Section titled “The Seven Evidence Dimensions”

Every resolution independently evaluates seven orthogonal dimensions:

┌───────────────────────────────────────────────────────────────────────────────────────────────┐
│                                 THE SEVEN EVIDENCE DIMENSIONS                                 │
├──────────────┬───────────────────┬──────────────────────────────────┬─────────────────────────┤
│ Dimension    │ Label             │ What It Proves                   │ What It Does NOT Prove  │
├──────────────┼───────────────────┼──────────────────────────────────┼─────────────────────────┤
│ integrity    │ Document Integrity│ Document matches identifier hash │ Control of underlying   │
│              │                   │ chain or self-certifying data.   │ web servers or hosting. │
├──────────────┼───────────────────┼──────────────────────────────────┼─────────────────────────┤
│ keys         │ Key Material      │ Published keys are well-formed   │ Real identity or holder │
│              │                   │ and lie on valid curve points.   │ legal authorization.    │
├──────────────┼───────────────────┼──────────────────────────────────┼─────────────────────────┤
│ control      │ Update Authority  │ Updates require cryptographic    │ Web host security on    │
│              │                   │ signatures (e.g. did:webvh).     │ did:web identities.     │
├──────────────┼───────────────────┼──────────────────────────────────┼─────────────────────────┤
│ origin       │ Origin Binding    │ Web domain signed a valid DIF    │ Corporate registration  │
│              │                   │ configuration binding this DID.  │ or trademark rights.    │
├──────────────┼───────────────────┼──────────────────────────────────┼─────────────────────────┤
│ transport    │ Transport Security│ Leaf TLS cert validity, SAN,     │ Key ownership or host   │
│              │                   │ and trusted WebPKI chain.        │ internal security.      │
├──────────────┼───────────────────┼──────────────────────────────────┼─────────────────────────┤
│ history      │ Verifiable History│ Immutable, hash-chained log of   │ Real-world conduct of   │
│              │                   │ all document versions (webvh).   │ the identifier subject. │
├──────────────┼───────────────────┼──────────────────────────────────┼─────────────────────────┤
│ organization │ Real-World Identity│ Fixed: Always NOT_ESTABLISHED.   │ Any corporate identity, │
│              │                   │ DID.is never checks registries.  │ KYC, or legal standing. │
└──────────────┴───────────────────┴──────────────────────────────────┴─────────────────────────┘

Dimension States & Severity Tones

Section titled “Dimension States & Severity Tones”

Dimensions transition deterministically between six normative states:

Dimension State Semantic Meaning Visual Tone Hex / Token
ESTABLISHED Passed an active cryptographic or procedural check. ok (Green) var(--ok)
SELF_CERTIFYING Inherently verified by identifier math (did:key, did:jwk, SCID). self (Accent Purple) var(--accent)
NOT_ESTABLISHED Property is absent or cannot be verified (e.g., no domain linkage). neutral (Muted Slate) var(--neutral)
FAILED Check was attempted and explicitly failed (invalid signature, bad hash). fail (Red) var(--fail)
INDETERMINATE Check could not finish conclusively (network timeout, unreachable list). warn (Amber) var(--warn)
NOT_APPLICABLE Property does not apply to this method (e.g., TLS on did:key). na (Subtle Sunken) var(--ink-3)

Level 3: Microsecond Execution Telemetry & SSE

Section titled “Level 3: Microsecond Execution Telemetry & SSE”

DID.is records microsecond-precision monotonic clocks for every execution phase:

Stage                   Status    Start Offset     Duration    Detail
─────────────────────────────────────────────────────────────────────────────────────────────
syntax.parse            PASS             12 µs        48 µs    did:web:identity.foundation
dns.resolve             PASS             84 µs     1,420 µs    Pinned to 104.21.48.12
tls.handshake           PASS          1,540 µs    18,200 µs    TLS 1.3, Let's Encrypt
web.fetch               PASS         19,800 µs     3,100 µs    HTTP 200 (1,482 bytes)
crypto.validate_keys    PASS         23,010 µs       180 µs    2 Multikeys validated
linkage.fetch           PASS         23,250 µs    12,400 µs    /.well-known/did-configuration.json
linkage.verify_proof    PASS         35,700 µs       320 µs    Data Integrity eddsa-jcs-2022 PASS

Visual Waterfall & Monotonic Clocks

Section titled “Visual Waterfall & Monotonic Clocks”

The desktop view of the Telemetry panel renders a visual waterfall bar chart (Telemetry.tsx) showing relative start offsets, durations, and timeline percentage ticks alongside the exact duration in milliseconds or microseconds.

Live Streaming via Server-Sent Events (SSE)

Section titled “Live Streaming via Server-Sent Events (SSE)”

Clicking Re-resolve live triggers GET /v1/stream/{did}. The client connects to an SSE stream that emits stages in real-time as they finish, rendering an animated scanline and progressively rising rows:

event: stage
data: {"stage":"syntax.parse","label":"Parse DID syntax","status":"PASS","startedUs":12,"durationUs":48,"detail":"did:web:identity.foundation"}


event: stage
data: {"stage":"web.fetch","label":"Fetch DID document","status":"PASS","startedUs":140,"durationUs":21200,"detail":"https://identity.foundation/.well-known/did.json"}


event: result
data: { ... EnrichedResolution JSON ... }


event: done
data: {}

Level 4: Substrate Inspector & Time Machine Diff

Section titled “Level 4: Substrate Inspector & Time Machine Diff”

Level 4 exposes the foundational bytes and historical observations across dedicated tabs:

  1. DID Document Tab: Interactive JSON tree of the published document alongside @context catalog analysis (confirming offline recognition and flagging uncataloged URIs with visual status marks). Displays any structural syntax warnings.
  2. Metadata Tab: Retrieval facts (HTTPS vs. local derivation, URL, HTTP status code, content length in bytes, pinned server IP, redirect audit trail max 2 hops, and SHA-256 digest) alongside W3C didResolutionMetadata and didDocumentMetadata JSON trees.
  3. Keys Tab (Multikey Anatomy): Deconstructs Multikey byte structures into raw hexadecimal segments: 
    [ z ] [ 0xed ] [ e7 2b 4a 99 12 ... 32 bytes ]
    Base58  Codec    Public Key Bytes (Ed25519)
    Displays RFC 7638 JWK thumbprint with copy button, key status, verification relationships (authentication, assertionMethod, capabilityDelegation), and derived publicKeyJwk.
  4. TLS Tab: Certificate chain validity, issuer Org/CN, validity window with days until expiry countdown, Host in SAN verification, Subject Alternative Names (DNS), serial number, leaf SHA-256 fingerprint, rustls Mozilla WebPKI validator, and protocol version (TLS 1.3 / TLS 1.2).
  5. Domain Linkage Tab: Origin, configuration URL, HTTP status, SHA-256 digest, and a structured ledger table of all linkage credentials (format, issuer, origin, proof suite, and verification status).
  6. Verifiable Log Tab (did:webvh): SCID, selected version, log URL, log SHA-256, pre-rotation status, portability, witness threshold, and entry hash chain table with individual hash chain and signature checks.
  7. Reproduce Tab (API Snippets): Interactive language switch showing reproduction snippets for cURL, TypeScript SDK (@didis/client), and Python SDK (didis).

Time Machine & Semantic Diff (#history)

Section titled “Time Machine & Semantic Diff (#history)”

Queries /v1/diff/{did}?from=<hash>&to=<hash> to compare observations recorded over time:

  • Detects rotated, added, or revoked signing keys.
  • Detects modified verification relationships (authentication, assertionMethod, capabilityDelegation).
  • Detects changes in service endpoints, controllers, and domain linkage configurations.

Putting Identity to Work: Control Claims & Next Steps

Section titled “Putting Identity to Work: Control Claims & Next Steps”

Section 6 of the Dossier (#next) bridges resolution into operational workflows:

  1. Control Claims (Claims): Shows whether an entity has established control of the identifier on DID.is. Control can be claimed for free via:
    • Key Signature: Sign an ephemeral challenge using a key authorized under authentication.
    • HTTPS File: Host the challenge token at /.well-known/did-is-claim.txt.
    • DNS TXT Record: Publish the challenge as a _didis-claim DNS TXT record.
  2. Next Steps:
    • Monitor changes: Set up hourly continuous monitoring watches and HMAC-signed webhook delivery.
    • Resolve from your app: Generate a scoped API key for private, idempotent, metered resolutions.
    • Read the API: Open the public W3C and DID.is API documentation.