Description of did-jwt library. May add exploration and comparison of UCANs and did-jwt-vc to this thread.

[bshambaugh]

DID you know that I've been working to amend the did-jwt (https://github.com/decentralized-identity/did-jwt/) library to include support for the secp256r1 curve? This was spawned by my work with js-ceramic (https://github.com/ceramicnetwork/js-ceramic). Here are some interpretations of the library I chose to JOT down:

• folder signers ts files : signs an arbitrary data payload with a private key, both formatted as Uint8Arrays . returns a string of some sort.

• folder blockchains ts files: coverts public keys to Bitcoin. Cosmos, and Ethereum URIs following bip122, cosmos (bech32 encoding of ripemd hash of sha256 hashed compressed public key), and eip155.

• Digest.ts: exports sha256 hasher, keccak 256 hasher, public key to Ethereum address creator, concatKDF function that produces a key encryption key for ECDH-1PU-XC20KW (although the function is generic. ECDH-ES-A256KW is mentioned in linked documentation and exploration to
  modify the library to do this is here: JWE for P-256 decentralized-identity/did-jwt#225)

• ECDH.ts: Described as: "A wrapper around mySecretKey that can compute a shared secret using theirPublicKey. The promise should resolve to a Uint8Array containing the raw shared secret." "Wraps an X25519 secret key into an ECDH method that can be used to compute a shared secret with a public key."

• JWE.ts: Functions for Json Web Encryption, Decrytion, and Validation in the abstract. Representation as JSON object apparently following https://datatracker.ietf.org/doc/html/rfc7516#section-7.2.1 .

• JWT.ts: (utilizes Signer and Verifier Alg)

  • decodeJWT returns a JSON object representing the payload
  • createJWS takes a JSON object representing a payload, a signer of type Signer, a header JSON string that may contain typ: 'JWT' and alg properties plus and additional key-value pairs, plus optional canonicalization to string. If no alg is specified the default alg "ES256K"
    is used. Returns a JSON Web Signature. Utilizes SignerAlgorithm.ts
  • createJWT takes a payload, JWTOptions JSON object containing issuer, signer, and optional expiresIn, alg, and canonicalize options, and a header JSON string that may contain typ: 'JWT' and alg properties plus and additional key-value pairs, plus optional canonicalization to string. If no alg is specified the default alg "ES256K"
    is used. Returns a JSON Web Signature. Utilizes createJWS.
  • verifyJWS "Verifies given JWS. If the JWS is valid, returns the public key that was used to sign the JWS, or throws an Error if none of the pubKeys match." Uses function verifyJWSDecoded that uses VerifierAlgorithm.ts . Checks to see that the JWS has the
    syntactic form header.data.signature . The verificationMethod interface is followed where id,type, and controller string properties are a MUST, a publicKey in the specified formats is optional, and a blockchainAccountId and ethereumAddress are also optional.
    However if a public key not specified either a blockChainAccountId or ethereumAddress should be specified. If none of these are specified, it's no bueno.
  • verifyJWT takes a JWT string and a number of verification options through the JWTVerifyOptions interface. From the resolver property-value pair specified in the JWTVerifyOptions interface MUST be specified. The JWT string MUST contain a value for the iss property. If it doesn't, the JWT has no did and an error is thrown. The iss property
    can match two const values specific to the library for self-issuance. For the JWTOptions, allow for either the auth or proofPurpose properties to be used, but prefer proofPurpose. What happens if both auth and proofPurpose are both undefined? Check this. The function works without error. This function, verifyJWT, depends on resolveAuthenticator. didJWT must have a timestamp that falls into the correct window with an offset.Check that the JWT is valid for the specified time with a small offset and the aud or audience is specified and it maches the did or callbackUrl.
    resolveAuthenticator verifies that the authenticator is in the proper form from a resolveable did document. The authenticator is used for verifying the json web signature. If the signer for the jwt is valid, investigate properties in the payload. If these properties do not match, throw an error that there is not a verification Method that matches the signature.
  • resolveAuthenticator: This is used by verifyJWT. Note that this does not do fancy math to recover the public key from the signature and a message for the case of ECDSA, but instead looks in the DID document to find the verificatioMethod which may point to the public key. Check that the JWT is valid for the spefic time with a small offset and the aud or audience is specified and it maches the did or callbackUrl.
    resolveAuthenticator returns an object matching the didAuthenticator interface which could contain a publicKey from a did document if it exists from a specified issuer did if it exists using interface VerificationMethod from interface DIDResolutionResult, otherwise it returns an error message using the interface DIDResolutionMetadata.
    For the verificationMethod interface, return non-null property-value pairs. For a legacy did document return from the publicKey property.
    Grab the verificationMethod id when a ProofPurposeTypes is matched, else ruturn null.
    Throw an error if a supported public key type matching the alg parameter is not in a did document.

• SignerAlgorithm.ts : returns a function SignerAlg that takes alg definition according to RFC7518 or an alg definition with a recovery parameter that checks for a recovery parameter and returns a base64url formatted string with a recovery bit at the end of the
  signature if a recovery parameter specified (for the correct alg when the promise in the function is resolved), else returns a signature (for the correct alg when the promise is resolved). Function returned uses Signers type definition utilized in folder signers.

• VerifierAlgorithm.ts : (checks valid signature?? and returns??) returns a function VerifierAlgorithm that matched the interface VerificationMethod that takes an alg definition according to RFC7518 or an alg definition with a recovery parameter which in turn takes data, a signature, and authenticators defined
  by a VerificationMethod interface that requires an id, type, and controller, and optionally includes a public key encoded as base58, Base64, Hex, as a JsonWebKey, or with Multibase, in addition to a blockChainAccountId and EthereumAddress.
  If blockChainAccountId and EthereumAddress are specified and there is no public key specified trigger a recovery function generate a public key from the data and signature and covert this to an Ethereum address and return invalid signature if the EthereumAddress
  is not matched else return the function VerifierAlgorithm. VerifierAlgorithm returns the publicKey in interface VerificationMethod corresponding to the signature and data if exists, error if otherwise.

• xc20Encryption.ts : (JWE stuff that utilizes JWE.ts)

• util.ts: (utils used elsewhere) Convert bytes to and from base64url, base64, base58, hex. Convert UTF8 string to bytes. Add left padding zeros to a string. Convert a JSON blob in the form { r, s, v } where r is the r part of the signature, s is the s part of the signature, and v is the recovery flag bit.
  to and from base64url. Concatenate a base64 representation of ciphertext and a tag and convert to bytes.

Internal Interdependencies:

• folder signers includes + EdDSASigner.ts which utilizes { Signer } type from JWT.ts and { bytesToBase64url, stringToBytes } functions from util.ts,
  + EllipticSigner.ts which utilizes { Signer } type from JWT.ts and ES256KSigner function from ES256KSigner.ts ,
  + ES256KSigner.ts which utilizes { leftpad, toJose } functions from util.ts and { Signer } type from JWT.ts,
  + ES256Signer.ts which utilizes { leftpad, toJose } functions from util.ts and { Signer } type from JWT.ts, , [ actually, I have to revert this PR to match form in EdDSASigner.ts since it is standard to use secp256k1 not secp256r1 in Ethereum address creation. Therefore, likely no recovery of secp256r1 public keys universally from Ethereum Address].
  + NaclSigner.ts which utilizes { EdDSASigner } function from EdDSASigner.ts and { Signer } type from JWT.ts,
  + and SimpleSigner.ts which utilizes { fromJose, hexToBytes } functions from util.ts and ES256KSigner function from ES256KSigner.ts .

• folder blockchains includes + bip122.ts which utilizes { bytesToBase58, base58ToBytes } functions from util.ts and { sha256 } function from Digest.ts and { Ripemd160 } from ripemd160.ts,
  + cosmos.ts which utilizes { sha256 } function from Digest.ts and { Ripemd160 } from ripemd160.ts,
  + index.ts which utilizes { publicKeyToAddress as bip122 } const function from bip122.ts and { publicKeyToAddress as cosmos } const function from comsmos.ts and { toEthereumAddress } function from Digest.ts,
  + and folder utils which contains ripemd160.ts (copy of: https://github.com/crypto-browserify/ripemd160/blob/master/index.js) .

• JWE,ts utilizes { base64ToBytes, bytesToBase64url, decodeBase64url, toSealed } functions from util.ts

• JWT.ts utilizes SignerAlg function from SignerAlgorithm.ts and VerifierAlgorithm from VerifierAlgorithm.ts

• SignerAlgorithm.ts utilizes { Signer, SignerAlgorithm } types from JWT.ts, { EcdsaSignature } interface and {fromJose, toJose } function from util.ts

• VerifierAlgorithm.ts utilizes { sha256, toEthereumAddress } functions from Digest.ts, { hexToBytes, base58ToBytes, base64ToBytes, bytesToHex, stringToBytes } functions and { EcdsaSignature } interface from util.ts and { verifyBlockchainAccountId } function in index.ts from 'blockchains' folder

• xc20Encryption.ts utilizes { concatKDF } function from Digest.ts, { bytesToBase64url, base58ToBytes, encodeBase64url, toSealed, base64ToBytes } functions from util.ts, { Recipient, EncryptionResult, Encrypter, Decrypter } interfaces and {ProtectedHeader } type
  from JWE.ts, and { ECDH } type function that returns a Promise as Uint8Array from ECDH.ts

[bshambaugh]

TODO: Compare this to https://github.com/ucan-wg/ts-ucan and https://github.com/decentralized-identity/did-jwt-vc . Look at https://nft.storage/docs/how-to/ucan/ because it gives a nice high-level overview and application of UCAN structure.