SD-JWT issuance: Creating SD-JWTs from claims sets.

This module provides functions for creating SD-JWTs on the issuer side. It handles marking claims as selectively disclosable, creating disclosures, computing digests, and building the final signed JWT.

Nested Structures

This module supports nested structures (RFC 9901 Sections 6.2 and 6.3) using JSON Pointer syntax (RFC 6901) for specifying nested claim paths.

JSON Pointer Syntax

Nested paths use forward slash (/) as a separator. Paths can refer to both object properties and array elements:

-- Object properties
["address/street_address", "address/locality"]

This marks street_address and locality within the address object as selectively disclosable.

-- Array elements
["nationalities/0", "nationalities/2"]

This marks elements at indices 0 and 2 in the nationalities array as selectively disclosable.

-- Mixed object and array paths
["address/street_address", "nationalities/1"]

Ambiguity Resolution

Paths with numeric segments (e.g., ["x/22"]) are ambiguous: they could refer to an array element at index 22, or an object property with key "22". The library resolves this ambiguity by checking the actual claim type at runtime:

• If x is an array → ["x/22"] refers to array element at index 22
• If x is an object → ["x/22"] refers to object property "22"

This follows JSON Pointer semantics (RFC 6901) where the path alone doesn't determine the type.

Escaping Special Characters

JSON Pointer provides escaping for keys containing special characters:

• ~1 represents a literal forward slash /
• ~0 represents a literal tilde ~

Examples:

• ["contact~1email"] → marks the literal key "contact/email" as selectively disclosable
• ["user~0name"] → marks the literal key "user~name" as selectively disclosable
• ["address/email"] → marks email within address object as selectively disclosable

Nested Structure Patterns

The module supports two patterns for nested structures:

1. Structured SD-JWT (Section 6.2): Parent object stays in payload with _sd array containing digests for sub-claims.
2. Recursive Disclosures (Section 6.3): Parent is selectively disclosable, and its disclosure contains an _sd array with digests for sub-claims.

The pattern is automatically detected based on whether the parent claim is also in the selective claims list.

Examples

Structured SD-JWT (Section 6.2):

buildSDJWTPayload SHA256 ["address/street_address", "address/locality"] claims

This creates a payload where address object contains an _sd array.

Recursive Disclosures (Section 6.3):

buildSDJWTPayload SHA256 ["address", "address/street_address", "address/locality"] claims

This creates a payload where address digest is in top-level _sd, and the address disclosure contains an _sd array with sub-claim digests.

Array Elements:

buildSDJWTPayload SHA256 ["nationalities/0", "nationalities/2"] claims

This marks array elements at indices 0 and 2 as selectively disclosable.

Nested Arrays:

buildSDJWTPayload SHA256 ["nested_array/0/0", "nested_array/0/1", "nested_array/1/0"] claims

This marks nested array elements. The path ["nested_array/0/0"] refers to element at index 0 of the array at index 0 of nested_array.

Mixed Object and Array Paths:

buildSDJWTPayload SHA256 ["address/street_address", "nationalities/1"] claims

This marks both an object property and an array element as selectively disclosable.

Decoy Digests

Decoy digests are optional random digests added to _sd arrays to obscure the actual number of selectively disclosable claims. This is useful for privacy-preserving applications where you want to hide how many claims are selectively disclosable.

To use decoy digests:

1. Build the SD-JWT payload using buildSDJWTPayload
2. Generate decoy digests using addDecoyDigest
3. Manually add them to the _sd array in the payload
4. Sign the modified payload

Example:

-- Build the initial payload
(payload, disclosures) <- buildSDJWTPayload SHA256 ["given_name", "email"] claims

-- Generate decoy digests
decoy1 <- addDecoyDigest SHA256
decoy2 <- addDecoyDigest SHA256

-- Add decoy digests to the _sd array
case payloadValue payload of
  Aeson.Object obj -> do
    case KeyMap.lookup "_sd" obj of
      Just (Aeson.Array sdArray) -> do
        let decoyDigests = [Aeson.String (unDigest decoy1), Aeson.String (unDigest decoy2)]
        let updatedSDArray = sdArray <> V.fromList decoyDigests
        let updatedObj = KeyMap.insert "_sd" (Aeson.Array updatedSDArray) obj
        -- Sign the updated payload...
      _ -> -- Handle error
  _ -> -- Handle error

During verification, decoy digests that don't match any disclosure are automatically ignored, so they don't affect verification.