[Content] Concepts: Issuance and Verification

.cspell/custom.txt

@@ -0,0 +1,3 @@
+CBOR
+COSE
+unlinkability

docs/concepts/issuance.md

@@ -1,8 +1,121 @@
 ---
 sidebar_position: 4
-title: "Issuance"
+title: "Credential Issuance"
 ---
 
-:::note
+Issuance is the process by which a trusted authority creates a verifiable digital credential and provides it to a holder.
+It is one of the three core operations in the credential lifecycle, alongside presentation and [verification](/docs/concepts/verification).
 
-Coming Soon
+In the [three-party model](/docs/concepts/three-party-model), the **issuer** is the entity that asserts claims about a subject and produces a cryptographically signed credential attesting to those claims.
+An issuer might be a government agency issuing a mobile driving license, a university issuing a digital diploma, or an employer issuing a proof of employment.
+
+## What happens during issuance
+
+Issuance involves several steps that together produce a credential the holder can store and later present to verifiers.
+The specific implementation varies across ecosystems, but the general shape is consistent.
+
+### Claim verification
+
+Before issuing a credential, the issuer establishes that the claims it will attest to are accurate.
+How this happens depends on the type of credential.
+A government agency might verify identity through an in-person visit or an existing identity proofing process.
+A university confirms that a student has completed a degree program.
+An employer checks employment records.
+The rigor of this step directly affects the trustworthiness of the resulting credential.
+
+### Credential construction
+
+The issuer assembles the credential data, the claims about the subject, metadata such as expiration dates and credential type, and any information needed for later status checks. 
+The structure and encoding of this data depend on the [credential format](/docs/concepts/credential-formats) in use.
+
+### Cryptographic signing
+
+The issuer signs the assembled credential using its private key.
+This signature serves two purposes: it binds the credential to the issuer's identity, and it protects the integrity of the credential data.
+Any modification to the credential after signing will invalidate the signature, allowing verifiers to detect tampering.
+
+Different credential formats use different signature schemes.
+Some use JSON Web Signatures, others use schemes designed for selective disclosure such as BBS signatures, and others use the CBOR Object Signing and Encryption (COSE) framework. The choice of signature scheme affects what privacy features the credential can support.
+
+### Delivery to the holder
+
+Once signed, the credential is delivered to the holder for storage in their credential manager.
+The delivery mechanism varies: it might happen over a direct protocol exchange in the credential manager, through a web browser ("Save to my wallet"), or even via a emailed download link.
+What matters is that the holder ends up with a copy of the credential that they control and can present independently of the issuer.
+
+## The role of the issuer
+
+An issuer is any entity that is authoritative for a set of claims and is willing to attest to them in the form of a signed credential.
+In practice, issuers are typically organizations: government agencies, educational institutions, healthcare providers, employers, or financial institutions.
+
+### Responsibilities
+
+The issuer has several key responsibilities in the credential ecosystem.
+
+**Ensure claim accuracy.**
+The issuer is responsible for verifying that the claims in a credential are correct at the time of issuance.
+A credential is only as trustworthy as the process the issuer uses to validate the underlying data.
+An issuer that rubber-stamps claims without verification undermines the entire trust model.
+
+**Protect signing keys.**
+The issuer's private key is the root of trust for every credential it issues.
+If the key is compromised, an attacker could forge credentials that appear legitimate.
+Issuers must use appropriate key management practices — hardware security modules, key rotation policies, and access controls — commensurate with the sensitivity of the credentials they issue.
+
+**Publish verification material.**
+For verifiers to validate a credential's signature, they need access to the issuer's public key or verification method.
+Issuers are responsible for making this material available, whether through a well-known endpoint, a DID document, a registry, or another discovery mechanism.
+Without it, verifiers cannot confirm that a credential is genuine.
+
+**Manage credential status.**
+Credentials sometimes need to be revoked or suspended after issuance — a license may be suspended, an employee may leave an organization, or a credential may have been issued in error.
+The issuer is responsible for maintaining a mechanism that allows verifiers to check whether a credential is still valid.
+Common approaches include status lists and revocation registries.
+
+**Define credential terms.**
+The issuer determines the structure, claims, and validity period of the credentials it issues.
+These decisions shape what verifiers can rely on and what holders can present.
+Clear, well-documented credential schemas help verifiers understand what a credential contains and how to interpret it.
+
+### What an issuer is not
+
+An issuer does not control how or when a holder uses a credential after issuance.
+Once the credential is delivered to the holder's credential manager, the holder decides which verifiers to present it to and under what circumstances.
+The issuer also does not participate in the presentation or verification process: the credential is designed to be verifiable without contacting the issuer in real time.
+
+This separation is a key design principle.
+It protects holder privacy by preventing the issuer from tracking where and when credentials are used, and it allows the system to function even when the issuer is offline.
+
+## Trust and issuer authority
+
+A credential's value depends on whether verifiers trust the entity that issued it.
+A cryptographically valid credential from an unrecognized issuer is technically sound but practically useless.
+
+**Authoritative issuers.**
+In most ecosystems, certain entities are recognized as authoritative for specific types of claims.
+A government is authoritative for identity documents. A university is authoritative for academic degrees.
+Trust is rooted in the real-world authority of the issuing organization, not just in cryptographic validity.
+
+**Trust registries.** Some ecosystems maintain registries that list recognized issuers and the credential types they are authorized to issue.
+Verifiers consult these registries to determine whether to accept a credential.
+This creates a structured trust framework that scales beyond bilateral relationships.
+
+**Decentralized trust.**
+In other models, trust is established through reputation, peer endorsement, or direct relationships between issuers and verifiers.
+These models are more flexible but may be harder for verifiers to evaluate, especially when encountering an issuer for the first time.
+
+## Privacy considerations
+
+Issuance decisions have downstream privacy implications for holders.
+
+**Minimal disclosure by design.**
+Issuers should consider what claims are truly necessary in a credential.
+Including more data than needed increases the holder's exposure when presenting the credential, especially in formats that do not support selective disclosure.
+
+**Selective disclosure support.**
+Credential formats that support selective disclosure allow holders to reveal only specific claims from a credential during presentation.
+Issuers that choose formats and signature schemes supporting this capability give holders more control over their personal data.
+
+**Issuer unlinkability.**
+The issuance process should not create mechanisms that allow the issuer to track the holder's subsequent use of the credential.
+This means avoiding callback URLs, phone-home mechanisms, or unique identifiers that the issuer could use to correlate presentations.

docs/concepts/verification.md

@@ -1,8 +1,122 @@
 ---
 sidebar_position: 3
-title: "Verification"
+title: "Credential Verification"
 ---
 
-:::note
+Verification is the process by which a party determines whether a verifiable digital credential is authentic, unaltered, and suitable for a given use.
+It is one of the three core operations in the credential lifecycle, alongside [issuance](/docs/concepts/issuance), and presentation.
 
-Coming Soon
+In the [three-party model](/docs/concepts/three-party-model), the **verifier** is the entity that receives a credential presentation and evaluates it.
+A verifier might be a website checking a user's age, an employer confirming a professional license, or a store requesting a loyalty card.
+
+## What happens during verification
+
+When a holder presents a credential, the verifier performs a series of checks to determine whether the presentation is trustworthy.
+At a high level, these checks fall into a few categories.
+
+### Authenticity
+
+The verifier confirms that the credential was issued by a known, trusted issuer and that the cryptographic signature over the credential is valid.
+This ensures the credential has not been fabricated by an unauthorized party.
+
+### Integrity
+
+The verifier checks that the credential data has not been modified since the issuer signed it.
+Verifiable digital credentials use cryptographic signatures that are invalidated by any change to the signed content, no matter how small.
+If a single field has been altered, the signature check fails.
+
+### Currency
+
+The verifier evaluates whether the credential is still valid at the time of presentation.
+This may involve checking expiration dates embedded in the credential, and depending on the ecosystem, querying an external service to determine if the credential has been revoked or suspended by the issuer.
+
+### Holder binding
+
+The verifier confirms that the entity presenting the credential is the same entity the credential was issued to.
+This is typically accomplished through a cryptographic proof: the holder demonstrates control of a private key that is bound to the credential.
+Without this step, a stolen or forwarded credential could be used by someone other than the intended subject.
+
+## The role of the verifier
+
+A verifier is any entity that needs to confirm a claim about a person or organization.
+In practice, verifiers are typically applications or services: a website, a point-of-sale terminal, a mobile app, or a backend system.
+
+### Responsibilities
+
+The verifier has several key responsibilities in the verifiable digital credentials ecosystem.
+
+**Define what credentials are acceptable.**
+Before requesting a presentation, the verifier determines which types of credentials satisfy its requirements and which issuers it trusts.
+For example, an age-restricted service might accept a mobile driving license from any government issuer but not a self-issued credential.
+
+**Request only what is needed.**
+A well-behaved verifier requests the minimum set of claims necessary for the transaction at hand.
+If the verifier only needs to confirm that a user is over 18, it should not request the user's full name, address, or even date of birth.
+[Credential formats](/docs/concepts/credential-formats) that support selective disclosure make this possible at a technical level, but it remains the verifier's responsibility to limit its requests.
+
+**Validate the presentation.**
+Once the verifier receives a presentation, it performs the authenticity, integrity, currency, and holder binding checks described above.
+These checks are largely mechanical and are typically handled by a verification library or service rather than implemented from scratch.
+
+**Make a trust decision.**
+Verification tells the verifier whether a credential is technically valid: that the signatures check out, the credential hasn't expired, and so on.
+But the verifier must still decide whether it *trusts* the result.
+This is a policy decision.
+A credential might be cryptographically valid but issued by an entity the verifier doesn't recognize or doesn't consider authoritative for the claims in question.
+
+### What a verifier is not
+
+A verifier does not issue credentials.
+It does not store credentials on behalf of the holder.
+And in most architectures, the verifier does not need to contact the issuer at the time of verification, the credential itself contains everything needed to validate the issuer's signature.
+This is a key difference from federated identity models, where the relying party typically calls back to the identity provider in real time.
+
+## Verification and the Digital Credentials API
+
+When verification happens on the web, the [Digital Credentials API](https://www.w3.org/TR/digital-credentials/) provides a standardized way for a website (the verifier) to request a credential presentation from the user's credential manager through the OS and browser.
+
+The API handles the interaction between the verifier's web application and the user's credential manager (via the operating system).
+The verifier constructs a request describing what credential data it needs, the browser and OS mediates the interaction with the user and their credential manager, and the credential manager returns a presentation that the verifier can then validate.
+
+This flow keeps the verifier from interacting directly with the credential manager application, preserving user privacy and giving the operating system and browser a role in ensuring informed consent.
+
+## Trust models
+
+Verification doesn't happen in a vacuum. For a verifier to accept a credential, it needs to trust the issuer that created it.
+How that trust is established varies across ecosystems.
+
+**Issuer registries.**
+Some ecosystems maintain public lists of trusted issuers.
+A verifier checks the credential's issuer identifier against a registry to determine whether the issuer is recognized and authorized to issue that type of credential.
+
+**Certificate chains.**
+In some architectures, issuer keys are certified by a higher-level authority, similar to how TLS certificates work.
+The verifier traces the chain of trust from the credential's signing key up to a root authority it already trusts.
+
+**Direct configuration.**
+In simpler deployments, the verifier might be configured with a static list of trusted issuer keys or identifiers.
+This is common in closed ecosystems where the set of issuers is small and stable.
+
+Regardless of the trust model, the verifier is ultimately responsible for deciding which issuers it accepts.
+This is a business and policy decision, not a purely technical one.
+
+## Privacy considerations
+
+Verification has direct privacy implications for the credential holder.
+A few principles guide responsible verifier behavior.
+
+**Data minimization.**
+Verifiers should request only the claims they need.
+Requesting a full credential when a single attribute would suffice exposes the holder to unnecessary data collection.
+
+**Selective disclosure.**
+Credential formats and protocols that support selective disclosure allow the holder (or their credential manager) to reveal only the requested claims from a credential, rather than the entire document.
+Verifiers should prefer protocols that support this capability.
+
+**Unlinkability.**
+In some protocols, repeated presentations of the same credential to different verifiers (or to the same verifier over time) can be correlated.
+Verifiers should be aware of whether the protocols they use allow or prevent such tracking.
+
+**No phone-home.**
+The verification process should not require the verifier to contact the issuer in real time, as this would reveal to the issuer when and where the holder is using the credential.
+Status checks (such as revocation lookups) should use privacy-preserving mechanisms where possible, such as status lists that can be fetched without identifying the specific credential being checked.