The did:sovrn DID Method

Version: 0.1
Status: Private beta. Registered with the W3C DID Method Registry (https://github.com/w3c/did-extensions/pull/738).
This document: https://schema.sovrn.place/specs/did-sovrn/v0.1/
License: Apache-2.0
Author: Sovrn
Contact: contactus@sovrnplace.com (website: https://sovrn.place)

Abstract §

did:sovrn is a Decentralized Identifier method for jurisdiction-scoped identity across a federation of economic zones. A single method serves three subject classes: AI agents, human citizens, and zones. The subject class is declared in the identifier itself, so a resolver and a verifier can read the class, and the federation and jurisdiction under whose authority the subject operates, before resolving the document. DIDs of this method resolve to DID Documents through a Sovrn-operated registry.

This method is a shared substrate. The human-citizen credential protocol (sovrn-protocol) uses did:sovrn:citizen:*; the agent protocol (sovrn-agent-protocol) uses did:sovrn:agent:*; both reference did:sovrn:zone:* as the jurisdictional anchor. One specification, one registration, covers all three.

1. Introduction §

A Decentralized Identifier (DID) is a globally unique identifier that resolves to a DID Document without a central registration authority, as defined by DID Core. This document specifies the did:sovrn method: its identifier syntax (§2), its Create, Read, Update, and Deactivate operations (§3), its security considerations (§4), and its privacy considerations (§5).

1.1 Scope and rationale §

did:sovrn encodes jurisdictional-resolution semantics in the identifier. The type segment (agent, citizen, or zone) declares the subject class, and the zone-scoped forms declare the federation and jurisdiction under whose authority the subject operates. This is the method's reason to exist: an identifier that carries, on its face, the jurisdictional context a verifier needs to reason about authority in a federation of economic zones. The method scope is narrow and deliberate. It does not aim to be a general-purpose identifier system.

1.2 Subject classes §

did:sovrn is one method with three type segments, not three methods. The three segments share the method, the resolver, and this specification; they differ only in the class of subject they identify.

1.3 Conformance §

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119 and RFC 8174 when, and only when, they appear in all capitals.

This specification conforms to the method-definition requirements of DID Core: method syntax (§2 here), method operations (§3 here), security requirements (§4 here), and privacy requirements (§5 here).

2. Method Syntax §

The method name that identifies this DID method is sovrn. A DID that uses this method MUST begin with the prefix did:sovrn:. That prefix is case-sensitive.

The method-specific identifier is a type segment, a colon, and a type-specific identifier:

sovrn-did         = "did:sovrn:" type-segment ":" type-specific-id

type-segment      = "agent" / "citizen" / "zone"

type-specific-id  = uuid / zone-code
                    ; uuid for the "agent" and "citizen" segments;
                    ; zone-code for the "zone" segment

uuid              = 8hexDigit "-" 4hexDigit "-" 4hexDigit "-"
                    4hexDigit "-" 12hexDigit
                    ; a UUID as defined by RFC 9562, lowercase canonical form

zone-code         = 1*( lc-alpha / DIGIT / "-" )
                    ; a zone slug; opaque in public examples (e.g. zone-a)

hexDigit          = DIGIT / "a" / "b" / "c" / "d" / "e" / "f"
lc-alpha          = %x61-7A   ; a-z
DIGIT             = %x30-39

2.1 Canonical form and comparison §

Identifiers are case-sensitive and are compared by exact string equality. This method defines no case-folding and no other normalization at resolution time. The canonical form is the form under which the DID was provisioned by the registry:

2.2 Examples §

did:sovrn:agent:3f2a1c8e-9b4d-4e21-a7c6-1d0e5f6a2b3c
did:sovrn:citizen:8c1e0a4b-2f37-4d59-b0a2-6e9f1c3d4a5b
did:sovrn:zone:zone-a

Zone codes in these examples are opaque placeholders. Production zone codes are not enumerated in this specification.

2.3 Validation and the resolver's accepted input §

The ABNF above is the normative syntax. A conforming producer MUST mint only identifiers that match it.

A resolver MAY accept a syntactic superset of the normative form as input: the reference resolver admits any did:sovrn:{type-segment}:{id} where the type-specific identifier contains no colon, and then resolves it against the registry. This is a deliberate fail-closed posture, not a widening of the syntax. Resolution of an identifier that is syntactically admitted but was never provisioned in the registry MUST return a not-found result (§3.2). Loose input acceptance therefore never widens trust: an identifier resolves if and only if the registry holds a document for it.

An identifier that lacks a recognized type segment (for example, a bare did:sovrn:{uuid} with no agent/citizen/zone segment) is not a valid did:sovrn identifier and MUST be rejected as malformed (§3.2). Earlier non-segmented identifier forms are out of scope for this method and do not resolve.

3. Operations §

did:sovrn is a registry-backed method. DID Documents are created, resolved, updated, and deactivated through a Sovrn-operated registry, which is the verifiable data registry for the method. The four DID Core operations are specified below. Operations that provision or mutate a document are performed by the registry; resolution is a public read.

3.0 Key material and DID Document shape (common to all classes) §

Every did:sovrn DID is provisioned with an Ed25519 key pair. The public key is placed in the DID Document as a single verification method:

Verification-method identifiers are always full-form ({did}#key-1), not relative fragments.

Private keys are held custodially by the registry operator; the registry signs on the subject's behalf. Agent and citizen private keys are stored in the registry's data store, encrypted under a key-encryption key; authority (zone and oracle) private keys are held as deployment secrets outside the data store and never enter it. This is a deliberate operational model for a managed federation registry, and its consequences are stated in the Security Considerations (§4.1, §4.2).

3.1 Create §

A DID is minted at a specific lifecycle moment for each subject class. In all three cases the registry generates the Ed25519 key pair (§3.0), constructs the DID Document, and records the creation in an append-only ledger. Identifiers are never reassigned: agent and citizen UUIDs are single-use by construction, and a zone code, once bound to a real-world authority, MUST NOT be reassigned to a different one.

3.2 Read (Resolve) §

Resolution is a public HTTP GET against the Sovrn-operated registry. The reference implementation exposes it at /api/dids/{did}, where {did} is percent-encoded. Resolution proceeds as follows:

  1. Syntax check. If the identifier does not match a recognized did:sovrn:{agent|citizen|zone}:{id} shape, the registry returns HTTP 400 (invalidDid). This is the malformed case of §2.3.
  2. Lookup by class. The registry looks the identifier up in the store for its type segment and returns the stored DID Document.
  3. Not found. If no document is returned for the identifier, the registry returns HTTP 404 (notFound). Resolution is hard-fail: the method defines no fallback to any other DID method (§4.4). A separately presented did:web identifier, where a deployment accepts one, is an independent input, never a fallback reached by a failed did:sovrn resolution.

Resolution-integrity contract. A resolved DID Document MUST have an id equal to the exact identifier that was queried. A verifier MUST reject a document whose id does not match the queried DID.

Caching. Resolution responses are served with Cache-Control: public, max-age=60. Consumers that need to observe a rotation, deactivation, or alias change promptly SHOULD account for this window.

Status gating (which documents resolve). Resolvability is gated on the subject's registry status, and the gate differs by class:

3.2.1 Service endpoints in the resolved document §

Discovery runs through the DID Document service property, not through any .well-known-by-DID path. Agent DID Documents advertise a typed Sovrn service entry (sovrn-mcp/1.0) and standard credential endpoints (OID4VCI), with the typed Sovrn endpoint listed before generic ones. Zone DID Documents advertise a trust-establishment endpoint. The service-type registration status and ordering rules are specified by the agent protocol; this method only requires that the service property is where endpoints are advertised.

3.2.2 The .si alias in the resolved document §

A resolved agent or citizen DID Document MAY carry an alsoKnownAs array with a single sovrn:si:{name} URI. This is the DID Core §5.1.2 alias for the subject's human-readable .si name, resolvable through the registry's .si resolver. The alias is a current-state assertion, not a stable identifier: it is set and cleared over the subject's lifetime, and .si names are reusable. The correlation and reuse consequences are stated in the Privacy Considerations (§5.3).

3.3 Update §

DID Documents are immutable after creation except for two sanctioned mutations. No other operation modifies a resolved document.

  1. Authority key rotation. A zone or oracle authority rotates its signing key by incrementing its keyGeneration counter; the registry rebuilds the authority's DID Document with the new public key and the same identifier. Rotation is generation-tracked so that credentials signed under a prior generation stay addressable for the authority-key-generation revocation cascade specified by the agent protocol. In v0.1 this rotation path is defined for the authority (zone/oracle) key material; agent and citizen key rotation is not a v0.1 operation.
  2. .si alias synchronization. Claiming or releasing a .si name sets or clears the alsoKnownAs entry (§3.2.2) on the bound agent or citizen DID Document. This mutation changes only alsoKnownAs and preserves every other field of the document byte-for-byte.

Beyond these two, a resolved DID Document does not change.

3.4 Deactivate §

An agent DID is deactivated by setting its registry status to DEACTIVATED; a zone DID is retired by setting its backing issuer status to a non-ACTIVE value. After deactivation the identifier resolves to HTTP 404, identical to the response for an identifier that was never provisioned. The registry does not emit a tombstone document or deactivated: true resolution metadata.

This diverges, deliberately, from the DID Core convention. DID Core resolution recommends that a deactivated DID resolve to its last DID Document with resolution metadata deactivated: true. did:sovrn does not do this. The divergence is an anti-enumeration design choice, consistent with the fail-closed posture of §2.3: a probe of the registry cannot distinguish a deactivated identifier from one that was never issued, so the registry does not confirm the prior existence of a retired subject or expose a deactivation-history oracle. A consumer that requires proof a specific identifier was once active obtains it from the append-only ledger or from credentials the subject issued, not from the resolver.

The current method defines no citizen deactivation operation; a citizen DID remains resolvable for the life of its key record.

Deactivation at the DID layer is distinct from credential revocation, which operates on issued credentials through their own status mechanisms (the agent protocol's credential status list and delegation revocation) and is not a DID-method operation.

4. Security Considerations §

did:sovrn is a registry-backed method operated by a single party. Several of the considerations below follow directly from that model. They are stated plainly: this section describes what a relying party actually gets from the method as shipped, not an idealized version of it.

4.1 Custodial key management §

The registry holds the private keys of the subjects it provisions. Agent, citizen, and authority key pairs are generated by the registry at Create time (§3.1); the registry operator holds the private halves (§3.0) and signs on the subject's behalf. Subjects do not hold their own key material at v0.1.

This is a real centralization and compromise surface, and it should be evaluated as one:

The operational mitigations are conventional and are named as what they are (risk reduction, not risk elimination): private keys are never stored or transmitted in the clear; the key-encryption key is held apart from the database and backed up off-platform; keys are rotated on suspected exposure; authority keys are generation-tracked (§3.3) so a rotation event is visible to verifiers through the credential-status machinery.

The custodial model is an operational property of the v0.1 registry, chosen for a managed federation deployment. The method syntax and resolution contract do not themselves require custody, but a relying party evaluating did:sovrn today MUST assume it: control of an agent or citizen subject is control of the principal's registry account, control of an authority subject is control of the registry deployment itself, and the registry is a trusted party in every signature attributed to a custodially-held subject.

4.2 Proof of control §

Because keys are custodial, proof of control of a did:sovrn DID is mediated by account authentication: the registry authenticates the principal's account before performing any operation or signature on the subject's behalf. The consequence is stated directly: compromise of the principal's registry account is compromise of the principal's DIDs and of the agents bound to them. Deployments SHOULD treat account-takeover defenses as part of the DID trust surface, not as a separate product concern.

4.3 Resolver integrity: what the registry is trusted for §

The Sovrn-operated registry is a single point of resolution. A relying party trusts it for exactly two things: liveness (returning documents for provisioned identifiers) and current state (the document served reflects the registry's present record, within the §3.2 cache window). Two integrity properties bound that trust:

What the resolver does not guarantee: that a resolvable subject is in good standing (§4.5); that the key in a document was never compromised (§4.1); or that any credential presented alongside the DID is valid. Credential validity has its own verification path in the layers above.

4.4 No downgrade: accepted inputs are never fallbacks §

Resolution failure is hard-fail (§3.2). A verifier MUST NOT respond to a failed did:sovrn resolution by falling back to any other identifier or method for the same subject. Automatic fallback would create a downgrade attack: an adversary who can induce a did:sovrn resolution failure could steer verification onto a weaker, separately-controlled identifier.

Deployments MAY accept a did:web identifier as a separately presented input with its own provenance; that acceptance is an independent decision by the verifier, reached before resolution begins, never a degradation path out of a failed one. Web-anchored inputs carry the DNS-class attack surface (DNS hijacking, BGP hijacking, certificate mis-issuance), which end-to-end DNSSEC validation, below 1% as measured, does little to blunt in practice. Operators of any web-anchored surface in a did:sovrn deployment SHOULD run a DNSSEC-signed zone, and relying parties should weight web-anchored provenance accordingly.

4.5 Resolvability is not standing §

A resolvable DID is not a trust signal. In particular, a suspended agent still resolves (§3.2): suspension is an operational standing flag, and the DID Document remains served so the subject's history and credentials stay independently checkable. A verifier MUST NOT infer good standing, active status, or any level of trust from the fact that resolution returned a document. Standing is checked separately, through the credential-status and reputation surfaces the layers above this method define. Resolution answers "what is this identifier's key material and service surface" and nothing more.

4.6 Signed agent cards §

Where an agent advertises a capability card, the card is JWS-signed with the agent's key from v0.1. The signature binds the card's content to the agent DID, so a card fetched from any location can be checked against the key in the resolved DID Document; a forged or tampered card fails verification. This closes the impersonation class in which unsigned discovery metadata is substituted at a look-alike origin.

The signature authenticates origin, not content quality. A validly signed card can still carry content chosen to manipulate downstream consumers. Consumers feeding card fields into model context or automated decisions SHOULD sanitize them; a card is a capability advertisement, never a trusted instruction.

4.7 On-chain discovery is discoverability, not adversarial resistance §

A did:sovrn subject MAY additionally register in an on-chain agent registry (the agent protocol integrates ERC-8004 as an optional, RECOMMENDED discovery surface). On-chain registration is a discoverability signal only. The registry class carries known open attack surfaces (registration front-running, Sybil registration at negligible cost, unfiltered feedback spam), and a verifier MUST NOT treat the existence of an on-chain registration as evidence of identity assurance, standing, or trust beyond "this entry exists." Trust decisions run through resolution (§3.2) and the credential layers above, not through the on-chain registry. On-chain anchoring of credential hashes is a deployment roadmap item outside the scope of this method.

4.8 Key rotation and the cross-layer cascade: an open problem §

Rotation of a DID's signing key invalidates, in principle, everything signed under the prior key: credentials issued to or by the subject, delegations witnessed by those credentials, and reputation computed from them. This specification does not solve that cascade, and does not claim to. What v0.1 provides is the credential-layer slice: authority keys are generation-tracked (§3.3), and the layers above use the generation counter to flip the status of credentials signed under a rotated-out generation. What remains open is the full chain: historically-correct resolution ("which key was valid at time T"), the stale-resolver false-accept window between a rotation event and its observation (bounded, at the resolver, only by the §3.2 cache window), and the downstream re-issuance of dependent artifacts. Verifiers with high-assurance requirements should treat a recently-rotated authority conservatively until dependent status surfaces have converged.

4.9 DID layer versus credential layer §

This method carries identity and key material only. Credentials, delegations, reputation, and memory are artifacts of the layers above, each with its own integrity and status mechanisms, and this specification references them only at their public interface: opaque status entries, opaque reputation tokens, and hash anchors. Deactivation here (§3.4) does not revoke credentials; credential revocation does not deactivate a DID. A verifier composes the two signals; neither substitutes for the other.

5. Privacy Considerations §

The DID Document of every subject class is deliberately minimal: key material; for agents and zones, service endpoints; for agents and citizens, optionally one .si alias. No name, no personal attribute, no credential payload, and no compliance state appears in any resolved document. The privacy properties below concern what the identifier and the document nonetheless reveal, and what accumulates around them.

5.1 What an identifier and its document reveal §

5.2 Principal–agent linkability and cross-zone correlation §

An agent and its principal are linkable by design: the agent protocol binds each agent to a principal DID, and accountability is the point of the binding. Anyone who observes an agent's credentials learns its principal's citizen DID.

At v0.1, the reference behavior is one principal DID across all zones. A principal operating agents in several zones is therefore correlatable across those zones by the shared principal DID: cross-zone activity aggregates onto one identifier. This is stated as a property of the current version, not defended as ideal: per-zone principal personas (breaking cross-zone correlation at the cost of naive cross-zone aggregation) are named future work in the agent protocol's open design questions, and this method's syntax does not preclude them. Until then, a privacy-sensitive principal should understand that zone-scoped activity under one principal DID composes into a cross-zone profile for any observer who sees enough of it.

5.3 The .si alias: current-state assertion, reusable name §

A .si name resolved from alsoKnownAs (§3.2.2) is a current-state assertion verified against the registry, not a stable identifier. Names are released and re-enter the pool; a name that designated one subject last year may designate a different subject today.

Both directions of this property matter:

5.4 Permanence of citizen identifiers §

The current method defines no deactivation operation for citizen DIDs (§3.4): once minted, a natural or legal person's identifier resolves for the life of its key record. For a human subject class this is a real privacy and erasure concern, and it is stated as one rather than explained away.

What bounds the concern today: the citizen document is the most minimal in the method: key material and at most one releasable alias. No personal attribute is resolvable from the DID. The identifier is pseudonymous, and what a citizen can remove is the linkage that makes it recognizable: release the .si alias (§3.3), and revoke or let expire the credentials that connect the DID to attributes and zones. What a citizen cannot do at v0.1 is retire the identifier itself, and the registry's append-only ledger and hash-anchored artifacts mean history referencing the DID is tamper-evident by design, which is in structural tension with erasure of that history. A deployment's obligations under data-protection law attach to the personal data it holds around the identifier, not to the pseudonymous identifier alone; this specification does not resolve that tension and flags citizen deactivation as expected future work for the method.

5.5 The DID layer is minimal; disclosure decisions live above it §

This method deliberately keeps sensitive attributes out of resolution. Verification status, KYC posture, capabilities, jurisdictional bindings, reputation, and memory all live in credentials and artifacts above the DID layer, where the subject controls disclosure, including selectively via the agent protocol's SD-JWT-VC envelope, which lets a holder reveal individual claims (such as the principal binding) to one verifier and withhold them from another. A resolved DID Document is the same for every resolver and contains nothing to selectively disclose; that is what makes the public resolution endpoint safe. Reputation and memory surface in those upper layers only as opaque tokens, banded values, and hash anchors. Nothing about their underlying computation is resolvable from, or expressible in, this method.

5.6 Resolution traffic is observable by the registry §

As the single resolution endpoint, the registry can observe who resolves which DIDs, when, and how often; this is standard metadata exposure for any hosted resolver. Response caching (§3.2) absorbs some repeat traffic, and resolution requires no authentication, so queries are not bound to a verifier identity; but a relying party with strict query-privacy requirements should assume resolution patterns are visible to the registry operator and mediate its queries accordingly.

This page is the rendered form of the canonical specification. The source markdown is served at /specs/did-sovrn/v0.1/did-sovrn-spec.md.