web-identity-schemas
Version:
TypeScript types and validation schemas for Web Identity and JOSE standards, including:
980 lines • 37 kB
TypeScript
//#region src/types/shared/algorithms.d.ts
/**
* JSON Web Signature algorithms that require cryptographic signatures.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7518}
*/
type JoseSignatureAlgorithm = "HS256" | "HS384" | "HS512" | "RS256" | "RS384" | "RS512" | "ES256" | "ES256K" | "ES384" | "ES512" | "PS256" | "PS384" | "PS512" | "EdDSA";
/**
* Algorithm for Unsecured JWS/JWT.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.1}
*/
type JoseUnsecuredAlgorithm = "none";
/**
* All JOSE signature algorithms including unsecured.
*/
type JoseAlgorithm = JoseSignatureAlgorithm | JoseUnsecuredAlgorithm;
/**
* JSON Web Encryption Content Encryption Algorithms.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7518#section-5.1}
*/
type JweContentEncryptionAlgorithm = "A128GCM" | "A192GCM" | "A256GCM" | "A128CBC-HS256" | "A192CBC-HS384" | "A256CBC-HS512";
/**
* JSON Web Encryption Key Management Algorithms.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7518#section-4.1}
*/
type JweKeyManagementAlgorithm = "RSA1_5" | "RSA-OAEP" | "RSA-OAEP-256" | "A128KW" | "A192KW" | "A256KW" | "dir" | "ECDH-ES" | "ECDH-ES+A128KW" | "ECDH-ES+A192KW" | "ECDH-ES+A256KW" | "A128GCMKW" | "A192GCMKW" | "A256GCMKW" | "PBES2-HS256+A128KW" | "PBES2-HS384+A192KW" | "PBES2-HS512+A256KW";
/**
* JSON Web Signature and Encryption Compression Algorithms.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7518#section-7.3}
*/
type JoseCompressionAlgorithm = "DEF";
//#endregion
//#region src/types/shared/base-64.d.ts
/**
* Base64url encoding type.
* String that contains only characters A-Z, a-z, 0-9, '-', '_'.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7515#section-2}
* @see {@link https://datatracker.ietf.org/doc/html/rfc4648#section-5}
*
* @example
* "SGVsbG8gV29ybGQ" // "Hello World" base64url encoded
* "eyJhbGciOiJIUzI1NiJ9" // JWT header example
*/
type Base64Url = string;
/**
* Base64 encoded string
*/
type Base64 = string;
//#endregion
//#region src/types/shared/curves.d.ts
/**
* Elliptic curves for Elliptic Curve Digital Signature Algorithm (ECDSA).
* @see {@link https://datatracker.ietf.org/doc/html/rfc7518#section-6.2.1.1}
*/
type EllipticCurve = "P-256" | "secp256r1" | "P-256K" | "secp256k1" | "P-384" | "P-521";
/**
* Octet string key pairs curves for EdDSA and ECDH.
* @see {@link https://datatracker.ietf.org/doc/html/rfc8037#section-2}
*/
type OctetKeyPairCurve = "Ed25519" | "Ed448" | "X25519" | "X448";
/**
* All supported cryptographic curves.
*/
type CryptographicCurve = EllipticCurve | OctetKeyPairCurve;
//#endregion
//#region src/types/shared/uri.d.ts
/**
* URI type according to RFC 3986.
* Generic URI with scheme and scheme-specific part.
* @see {@link https://tools.ietf.org/html/rfc3986}
*/
type Uri<TScheme extends string = string, TPath extends string = string> = `${TScheme}:${TPath}`;
//#endregion
//#region src/types/shared/json-ld.d.ts
/**
* JSON-LD context.
* @see {@link https://www.w3.org/TR/json-ld/#contexts}
*/
type JsonLdContext = Uri | Uri[] | Record<string, Uri>;
/**
* JSON-LD DateTimeStamp type.
* Must be a string in ISO 8601 format (YYYY-MM-DDTHH:mm:ss.sssZ).
* @see {@link https://www.w3.org/TR/json-ld/#datatypes}
* @see {@link https://www.w3.org/TR/xmlschema11-2/#dateTime}
*
* @example
* "2023-12-07T10:30:00.000Z"
* "2023-12-07T10:30:00.123Z"
* "2023-12-07T10:30:00+01:00"
*/
type DateTimeStamp = string;
//#endregion
//#region src/types/shared/utils.d.ts
/**
* Array or single element type.
*/
type OneOrMany<T> = T | T[];
/**
* Extendable type that allows additional properties.
*/
type LooseObject<T> = T & Record<string, unknown>;
/**
* Array containing utility type that requires specific elements in order.
*/
type ArrayContaining<T extends readonly unknown[], TRest = unknown> = [...T, ...TRest[]];
//#endregion
//#region src/types/jose/jwk.d.ts
/**
* Intended key use.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7517#section-4.2}
*/
type KeyUse = "sig" | "enc";
/**
* Allowed key operations.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7517#section-4.3}
*/
type KeyOperation = "sign" | "verify" | "encrypt" | "decrypt" | "wrapKey" | "unwrapKey" | "deriveKey" | "deriveBits";
/**
* Base JWK interface with common fields.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7517}
*/
interface BaseJwk {
/** Algorithm intended for use with the key (e.g., "RS256") */
alg?: JoseAlgorithm;
/** Whether the key is extractable (for Web Crypto API) */
ext?: boolean;
/** Key operations permitted (e.g., ["sign", "verify"]) */
key_ops?: KeyOperation[];
/** Key ID (identifier for key) */
kid?: string;
/** Intended key use ("sig" for signature, "enc" for encryption) */
use?: KeyUse;
/**
* X.509 certificate chain (base64-encoded certs - explicitly NOT base64url)
* @see {@link https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.6}
*/
x5c?: Base64[];
/** X.509 certificate SHA-1 thumbprint (base64url-encoded) */
x5t?: Base64Url;
/** X.509 certificate SHA-256 thumbprint (base64url-encoded) */
"x5t#S256"?: Base64Url;
/** URL pointing to X.509 certificate */
x5u?: string;
}
/**
* RSA JWK.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7518#section-6.3}
*/
interface RsaJwk extends BaseJwk {
/** Key type: RSA */
kty: "RSA";
/** RSA modulus (base64url-encoded) */
n: Base64Url;
/** RSA public exponent (base64url-encoded) */
e: Base64Url;
/** RSA private exponent (base64url-encoded) */
d?: Base64Url;
/** First prime factor (base64url-encoded) */
p?: Base64Url;
/** Second prime factor (base64url-encoded) */
q?: Base64Url;
/** First CRT exponent (base64url-encoded) */
dp?: Base64Url;
/** Second CRT exponent (base64url-encoded) */
dq?: Base64Url;
/** First CRT coefficient (base64url-encoded) */
qi?: Base64Url;
/** Other primes info for multi-prime RSA */
oth?: {
/** Additional prime factor (base64url-encoded) */
r: Base64Url;
/** Additional factor CRT exponent (base64url-encoded) */
d: Base64Url;
/** Additional factor CRT coefficient (base64url-encoded) */
t?: Base64Url;
}[];
}
/**
* EC JWK.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7518#section-6.2}
*/
interface EcJwk extends BaseJwk {
/** Key type: Elliptic Curve */
kty: "EC";
/** Curve name (e.g., "P-256", "P-384", "P-521", "secp256k1") */
crv: EllipticCurve;
/** X coordinate of EC public key (base64url-encoded) */
x: Base64Url;
/** Y coordinate of EC public key (base64url-encoded) */
y: Base64Url;
/** EC private key (base64url-encoded) */
d?: Base64Url;
}
/**
* Symmetric (octet) JWK.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7518#section-6.4}
*/
interface OctJwk extends BaseJwk {
/** Key type: symmetric (octet sequence) */
kty: "oct";
/** Symmetric key material (base64url-encoded) */
k: Base64Url;
}
/**
* OKP JWK.
* @see {@link https://datatracker.ietf.org/doc/html/rfc8037}
*/
interface OkpJwk extends BaseJwk {
/** Key type: Octet Key Pair */
kty: "OKP";
/** Curve name (e.g., "Ed25519", "X25519") */
crv: OctetKeyPairCurve;
/** Public key (base64url-encoded) */
x: Base64Url;
/** Private key (base64url-encoded) */
d?: Base64Url;
}
/**
* JSON Web Key - union of all supported key types.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7517}
*/
type JsonWebKey = RsaJwk | EcJwk | OctJwk | OkpJwk;
//#endregion
//#region src/types/jose/jwe.d.ts
/**
* JWE Protected Header.
* Contains algorithm and other cryptographic parameters for JWE.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7516#section-4.1.1}
*/
interface JweProtectedHeader {
/** Algorithm used for key management */
alg: JweKeyManagementAlgorithm;
/** Algorithm used for content encryption */
enc: JweContentEncryptionAlgorithm;
/** Compression algorithm (optional) */
zip?: JoseCompressionAlgorithm;
/** Key ID (optional) */
kid?: string;
/** JSON Web Key Set URL (optional) */
jku?: string;
/** JSON Web Key (optional) */
jwk?: JsonWebKey;
/** X.509 URL (optional) */
x5u?: string;
/** X.509 Certificate Chain (optional) */
x5c?: Base64[];
/** X.509 Certificate SHA-1 Thumbprint (optional) */
x5t?: Base64Url;
/** X.509 Certificate SHA-256 Thumbprint (optional) */
"x5t#S256"?: Base64Url;
/** Type of the token (optional) */
typ?: string;
/** Content type (optional) */
cty?: string;
/** Critical header parameter (optional) */
crit?: string[];
}
/**
* JWE Unprotected Header.
* Contains additional header parameters that are not encrypted.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7516#section-4.1.2}
*/
interface JweUnprotectedHeader {
/** Key ID (optional) */
kid?: string;
/** JSON Web Key Set URL (optional) */
jku?: string;
/** JSON Web Key (optional) */
jwk?: JsonWebKey;
/** X.509 URL (optional) */
x5u?: string;
/** X.509 Certificate Chain (optional) */
x5c?: Base64[];
/** X.509 Certificate SHA-1 Thumbprint (optional) */
x5t?: Base64Url;
/** X.509 Certificate SHA-256 Thumbprint (optional) */
"x5t#S256"?: Base64Url;
/** Critical header parameter (optional) */
crit?: string[];
}
/**
* JWE recipient information.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7516#section-7.2.1}
*/
interface JweRecipient {
/** Unprotected header for this recipient */
header?: JweUnprotectedHeader;
/** Encrypted key for this recipient (base64url-encoded) */
encrypted_key: Base64Url;
}
/**
* JWE General JSON Serialization.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7516#section-7.2.1}
*/
interface JweGeneralJson {
/** Protected header (base64url-encoded) */
protected?: Base64Url;
/** Unprotected header */
unprotected?: JweUnprotectedHeader;
/** Array of recipients */
recipients: JweRecipient[];
/** Initialization vector (base64url-encoded) */
iv: Base64Url;
/** Ciphertext (base64url-encoded) */
ciphertext: Base64Url;
/** Authentication tag (base64url-encoded) */
tag: Base64Url;
/** Additional authenticated data (base64url-encoded, optional) */
aad?: Base64Url;
}
/**
* JWE Flattened JSON Serialization.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7516#section-7.2.2}
*/
interface JweFlattenedJson {
/** Protected header (base64url-encoded) */
protected?: Base64Url;
/** Unprotected header */
unprotected?: JweUnprotectedHeader;
/** Recipient header */
header?: JweUnprotectedHeader;
/** Encrypted key (base64url-encoded) */
encrypted_key: Base64Url;
/** Initialization vector (base64url-encoded) */
iv: Base64Url;
/** Ciphertext (base64url-encoded) */
ciphertext: Base64Url;
/** Authentication tag (base64url-encoded) */
tag: Base64Url;
/** Additional authenticated data (base64url-encoded, optional) */
aad?: Base64Url;
}
/**
* JWE Compact Serialization.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7516#section-7.1}
*/
type JweCompact = string;
/**
* JWE - union of all serialization formats.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7516}
*/
type Jwe = JweCompact | JweFlattenedJson | JweGeneralJson;
//#endregion
//#region src/types/jose/jwks.d.ts
/**
* JSON Web Key Set.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7517#section-5}
*/
interface JsonWebKeySet {
/** Array of JSON Web Keys */
keys: JsonWebKey[];
}
//#endregion
//#region src/types/jose/jws.d.ts
/**
* JWS Protected Header.
* Contains algorithm and other cryptographic parameters for JWS.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.1}
*/
interface JwsProtectedHeader {
/** Algorithm used to sign the JWS */
alg: JoseAlgorithm;
/** Key ID (optional) */
kid?: string;
/** JSON Web Key Set URL (optional) */
jku?: string;
/** JSON Web Key (optional) */
jwk?: JsonWebKey;
/** X.509 URL (optional) */
x5u?: string;
/** X.509 Certificate Chain (optional) */
x5c?: Base64[];
/** X.509 Certificate SHA-1 Thumbprint (optional) */
x5t?: Base64Url;
/** X.509 Certificate SHA-256 Thumbprint (optional) */
"x5t#S256"?: Base64Url;
/** Type of the token (optional) */
typ?: string;
/** Content type (optional) */
cty?: string;
/** Critical header parameter (optional) */
crit?: string[];
}
/**
* JWS Unprotected Header.
* Contains additional header parameters that are not integrity protected.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.2}
*/
interface JwsUnprotectedHeader {
/** Key ID (optional) */
kid?: string;
/** JSON Web Key Set URL (optional) */
jku?: string;
/** JSON Web Key (optional) */
jwk?: JsonWebKey;
/** X.509 URL (optional) */
x5u?: string;
/** X.509 Certificate Chain (optional) */
x5c?: Base64[];
/** X.509 Certificate SHA-1 Thumbprint (optional) */
x5t?: Base64Url;
/** X.509 Certificate SHA-256 Thumbprint (optional) */
"x5t#S256"?: Base64Url;
/** Critical header parameter (optional) */
crit?: string[];
}
/**
* JWS signature.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7515#section-7.2.1}
*/
interface JwsSignature {
/** Protected header (base64url-encoded) */
protected?: Base64Url;
/** Unprotected header */
header?: JwsUnprotectedHeader;
/** Signature (base64url-encoded) */
signature: Base64Url;
}
/**
* JWS General JSON Serialization.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7515#section-7.2.1}
*/
interface JwsGeneralJson {
/** Base64url-encoded payload */
payload: Base64Url;
/** Array of signatures */
signatures: JwsSignature[];
}
/**
* JWS Flattened JSON Serialization.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7515#section-7.2.2}
*/
interface JwsFlattenedJson {
/** Base64url-encoded payload */
payload: Base64Url;
/** Protected header (base64url-encoded) */
protected?: Base64Url;
/** Unprotected header */
header?: JwsUnprotectedHeader;
/** Signature (base64url-encoded) */
signature: Base64Url;
}
/**
* JWS string in compact serialization format.
* Must contain exactly 3 parts separated by periods.
* Format: header.payload.signature
* @see {@link https://datatracker.ietf.org/doc/html/rfc7515#section-7.1}
*/
type JwsString = `${string}.${string}.${string}`;
/**
* JWS Compact Serialization.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7515#section-7.1}
*/
type JwsCompact = string;
/**
* JWS - union of all serialization formats.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7515}
*/
type Jws = JwsCompact | JwsFlattenedJson | JwsGeneralJson;
//#endregion
//#region src/types/jose/jwt-string.d.ts
/**
* JWT string format.
* Must contain exactly 3 parts separated by periods (header.payload.signature).
* Each part must be base64url encoded.
* An unsecured JWT ends with a period and does contain a signature part.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7519#section-3}
*/
type JwtString = string;
/**
* JWT string parts.
* Result of splitting a JWT string into its components.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7519#section-3}
*/
interface JwtStringParts {
/** Base64url-encoded header */
header: Base64Url;
/** Base64url-encoded payload */
payload: Base64Url;
/** Base64url-encoded signature (empty string for unsecured JWTs) */
signature: Base64Url | "";
}
//#endregion
//#region src/types/jose/jwt.d.ts
/**
* Unix timestamp type.
*/
type UnixTimestamp = number;
/**
* Common JWT header fields for all algorithms.
* Contains cryptographic parameters excluding the algorithm.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7519#section-5}
*/
interface JwtHeaderBase {
/** Type of the token (optional, typically "JWT") */
typ?: "JWT";
/** Content type (optional) */
cty?: string;
/** Key ID (optional) */
kid?: string;
/** JSON Web Key Set URL (optional) */
jku?: string;
/** JSON Web Key (optional) */
jwk?: JsonWebKey;
/** X.509 URL (optional) */
x5u?: string;
/** X.509 Certificate Chain (optional) */
x5c?: Base64[];
/** X.509 Certificate SHA-1 Thumbprint (optional) */
x5t?: Base64Url;
/** X.509 Certificate SHA-256 Thumbprint (optional) */
"x5t#S256"?: Base64Url;
/** Critical header parameter (optional) */
crit?: string[];
}
/**
* JWT header for Unsecured JWS/JWT (alg: "none").
* @see {@link https://datatracker.ietf.org/doc/html/rfc7519#section-5}
*/
interface JwtHeaderUnsecured extends JwtHeaderBase {
/** Algorithm used to sign the JWT */
alg: JoseUnsecuredAlgorithm;
}
/**
* JWT header for signed JWS/JWT (all algorithms except "none").
* @see {@link https://datatracker.ietf.org/doc/html/rfc7519#section-5}
*/
interface JwtHeaderSigned extends JwtHeaderBase {
/** Algorithm used to sign the JWT */
alg: JoseSignatureAlgorithm;
}
/**
* JWT header - union of all header types.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7519#section-5}
*/
type JwtHeader = JwtHeaderUnsecured | JwtHeaderSigned;
/**
* JWT payload (claims).
* Contains registered, public, and private claims.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7519#section-4}
*/
interface JwtPayload {
/** Issuer - identifies the principal that issued the JWT */
iss?: string;
/** Subject - identifies the principal that is the subject of the JWT */
sub?: string;
/** Audience - identifies the recipients that the JWT is intended for */
aud?: string | string[];
/** Expiration Time - identifies the expiration time on or after which the JWT must not be accepted */
exp?: UnixTimestamp;
/** Not Before - identifies the time before which the JWT must not be accepted */
nbf?: UnixTimestamp;
/** Issued At - identifies the time at which the JWT was issued */
iat?: UnixTimestamp;
/** JWT ID - provides a unique identifier for the JWT */
jti?: string;
/** Additional claims */
[key: string]: unknown;
}
/**
* JWT object for Unsecured JWS/JWT (alg: "none").
* The signature must be an empty string for Unsecured JWS/JWT.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7519#section-3}
*/
interface JwtObjectUnsecured {
/** JWT header containing algorithm and cryptographic parameters */
header: JwtHeaderUnsecured;
/** JWT payload containing claims about the token */
payload: JwtPayload;
/** JWT signature (empty string for Unsecured JWS/JWT) */
signature: "";
}
/**
* JWT object for signed JWS/JWT (all algorithms except "none").
* The signature must be a valid base64url-encoded string.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7519#section-3}
*/
interface JwtObjectSigned {
/** JWT header containing algorithm and cryptographic parameters */
header: JwtHeaderSigned;
/** JWT payload containing claims about the token */
payload: JwtPayload;
/** JWT signature (base64url encoded) */
signature: Base64Url;
}
/**
* JWT object with separate header, payload, and signature.
* Represents a parsed JWT with its components.
* @see {@link https://datatracker.ietf.org/doc/html/rfc7519#section-3}
*/
type JwtObject = JwtObjectUnsecured | JwtObjectSigned;
//#endregion
//#region src/types/did/did.d.ts
/**
* DID method names. Must follow format rules: lowercase letters and numbers only.
* @see {@link https://www.w3.org/TR/did-core/#method-syntax}
*/
type DidMethod = string;
/**
* DID (Decentralized Identifier) type.
* A DID is a subset of URIs with specific format requirements.
* @see {@link https://www.w3.org/TR/did-core/#did-syntax}
*/
type Did<TMethod extends DidMethod = DidMethod, TIdentifier extends string = string> = Uri<"did", `${TMethod}:${TIdentifier}`>;
/**
* DID URL with optional path, query, and fragment.
* @see {@link https://www.w3.org/TR/did-core/#did-url-syntax}
*/
type DidUrl = Did;
/**
* Outdated verification method types.
* @deprecated use {@link VerificationMethodType} instead
*/
type LegacyVerificationMethodType = "JsonWebKey2020" | "Ed25519VerificationKey2020" | "Ed25519VerificationKey2018" | "X25519KeyAgreementKey2020" | "X25519KeyAgreementKey2019" | "EcdsaSecp256k1VerificationKey2019" | "EcdsaSecp256r1VerificationKey2019" | "RsaVerificationKey2018";
/**
* Verification method type.
* @see {@link https://www.w3.org/2025/credentials/vcdi/vocab/v2/vocabulary.html#verificationMethod}
*/
type VerificationMethodType = "JsonWebKey" | "Multikey";
/**
* Verification method.
* @see {@link https://www.w3.org/TR/did-core/#verification-methods}
*/
interface VerificationMethodBase {
/** A string that conforms to the rules in 3.2 DID URL Syntax. */
id: DidUrl;
/** A string that conforms to the rules in 3.1 DID Syntax. */
controller: Did;
}
interface VerificationMethodJsonWebKey extends VerificationMethodBase {
type: "JsonWebKey";
/** A map representing a JSON Web Key that conforms to [RFC7517]. */
publicKeyJwk: unknown;
}
interface VerificationMethodMultikey extends VerificationMethodBase {
type: "Multikey";
/** A string that conforms to a multibase encoded public key. */
publicKeyMultibase: string;
}
interface VerificationMethodLegacy extends VerificationMethodBase {
type: LegacyVerificationMethodType;
publicKeyMultibase?: string;
publicKeyJwk?: unknown;
/** @deprecated usa {@link publicKeyMultibase} or {@link publicKeyJwk} instead */
publicKeyBase58?: string;
}
/**
* Verification method.
* @see {@link https://www.w3.org/TR/did-core/#verification-methods}
*/
type VerificationMethod = VerificationMethodJsonWebKey | VerificationMethodMultikey | VerificationMethodLegacy;
interface ServiceEndpointMap {
[key: string]: string | string[] | Uri | ServiceEndpointMap;
}
/** A service endpoint is a string that conforms to the rules of [RFC3986] for URIs, a map, or a set composed of a one or more strings that conform to the rules of [RFC3986] for URIs and/or maps. */
type ServiceEndpoint = Uri | ServiceEndpointMap | (Uri | ServiceEndpointMap)[];
/**
* Service endpoint.
* @see {@link https://www.w3.org/TR/did-core/#services}
*/
interface Service {
/** A string that conforms to the rules of [RFC3986] for URIs. */
id: Uri;
/** A string or a set of strings. */
type: string | string[];
/** A string that conforms to the rules of [RFC3986] for URIs, a map, or a set composed of a one or more strings that conform to the rules of [RFC3986] for URIs and/or maps. */
serviceEndpoint: ServiceEndpoint;
}
/**
* DID Document.
* @see {@link https://www.w3.org/TR/did-1.0/#core-properties}
*/
interface DidDocument {
/** JSON-LD context */
"@context": JsonLdContext;
/** A string that conforms to the rules in 3.1 DID Syntax. */
id: Did;
/** A set of strings that conform to the rules of [RFC3986] for URIs. */
alsoKnownAs?: Uri[];
/** A string or a set of strings that conform to the rules in 3.1 DID Syntax. */
controller?: Did | Did[];
/** A set of Verification Method maps that conform to the rules in Verification Method properties. */
verificationMethod?: VerificationMethod[];
/** A set of either Verification Method maps that conform to the rules in Verification Method properties) or strings that conform to the rules in 3.2 DID URL Syntax. */
authentication?: (DidUrl | VerificationMethod)[];
/** Assertion method verification methods */
assertionMethod?: (DidUrl | VerificationMethod)[];
/** Key agreement verification methods */
keyAgreement?: (DidUrl | VerificationMethod)[];
/** Capability invocation verification methods */
capabilityInvocation?: (DidUrl | VerificationMethod)[];
/** Capability delegation verification methods */
capabilityDelegation?: (DidUrl | VerificationMethod)[];
/** A set of Service Endpoint maps that conform to the rules in Service properties. */
service?: Service[];
}
//#endregion
//#region src/types/vc/proof.d.ts
/**
* Proof purpose values.
* @see {@link https://w3c.github.io/vc-data-integrity/#proof-purposes}
*/
type ProofPurpose = "assertionMethod" | "authentication" | "keyAgreement" | "capabilityInvocation" | "capabilityDelegation" | string;
/**
* Data integrity proof
* @see {@link https://w3c.github.io/vc-data-integrity/#proofs}
*/
interface Proof {
/** Proof type */
type: string;
/** Creation timestamp */
created?: DateTimeStamp;
/** Verification method */
verificationMethod: Uri;
/** Proof purpose */
proofPurpose: ProofPurpose;
/** Challenge (for presentations) */
challenge?: string;
/** Domain (for presentations) */
domain?: string | string[];
/** Nonce */
nonce?: string;
/** JWS signature (for JsonWebSignature2020) */
jws?: JwsString;
/** Signature value (for other proof types) */
signatureValue?: string;
/** Proof value (generic) */
proofValue?: string;
}
//#endregion
//#region src/types/vc/core.d.ts
type CredentialType = string | string[];
/**
* Raw credential type value that ensures "VerifiableCredential" is always
* present, as well as any additional types provided. Per the spec: "If more
* than one value is provided, the order does not matter."
* @see {@link https://www.w3.org/TR/vc-data-model/#types}
*/
type RawCredentialType<TBaseType extends string, TAdditionalTypes extends string | string[] = never> = [TAdditionalTypes] extends [never] ? TBaseType | ArrayContaining<[TBaseType], string> : TAdditionalTypes extends string ? ArrayContaining<[TBaseType, TAdditionalTypes], string> : TAdditionalTypes extends string[] ? ArrayContaining<[TBaseType, ...TAdditionalTypes], string> : never;
/**
* Credential type value that ensures "VerifiableCredential" is always present.
* @see {@link https://www.w3.org/TR/vc-data-model/#types}
*/
type VerifiableCredentialType<TAdditionalTypes extends CredentialType = never> = RawCredentialType<"VerifiableCredential", TAdditionalTypes>;
/**
* Credential type value that ensures "VerifiablePresentation" is always present.
* @see {@link https://www.w3.org/TR/vc-data-model/#types}
*/
type VerifiablePresentationType<TAdditionalTypes extends string | string[] = never> = RawCredentialType<"VerifiablePresentation", TAdditionalTypes>;
/**
* Credential status types.
* @see {@link https://www.w3.org/TR/vc-data-model/#status}
*/
type CredentialStatusType = "RevocationList2020Status" | "StatusList2021Entry" | "BitstringStatusListEntry" | string;
/**
* Status purposes for credential status.
*/
type StatusPurpose = "revocation" | "suspension" | string;
/**
* Credential status.
* @see {@link https://www.w3.org/TR/vc-data-model/#status}
*/
interface CredentialStatus {
/** Status entry identifier */
id?: string;
/** Status type */
type: CredentialStatusType;
/** Status list credential */
statusListCredential?: string;
/** Status list index */
statusListIndex?: string | number;
/** Status purpose */
statusPurpose?: StatusPurpose;
}
/**
* Credential schema reference.
* @see {@link https://www.w3.org/TR/vc-data-model/#data-schemas}
*/
interface CredentialSchemaType {
/** Schema identifier */
id: Uri;
/** Schema type */
type: string;
}
/**
* Credential subject with optional ID.
* @see {@link https://www.w3.org/TR/vc-data-model/#credential-subject}
*/
interface CredentialSubject {
/** Subject identifier (optional) */
id?: Uri | string;
/** Additional subject properties */
[key: string]: unknown;
}
/**
* Generic type for ID or object with id property.
* Common pattern in verifiable credentials for issuer, holder, etc.
*/
type IdOrObject<TId extends Uri = Uri> = TId | {
id: TId;
[key: string]: unknown;
};
/**
* Generic resource reference used for evidence, refresh services, and terms of use.
* @see {@link https://www.w3.org/TR/vc-data-model/}
*/
interface GenericResource {
/** Resource identifier (optional) */
id?: Uri | string;
/** Resource type */
type: string | string[];
/** Additional properties */
[key: string]: unknown;
}
/**
* Makes any credential verifiable by ensuring it has a required proof.
* A verifiable record is one that includes cryptographic proof.
*
* @template T - The credential type to make verifiable
*/
type Verifiable<T> = T & {
/** Cryptographic proof that makes the credential verifiable */
proof: Proof | Proof[];
};
/**
* Base W3C Credential without proof (unsigned credential).
* @see {@link https://www.w3.org/TR/vc-data-model/#credentials}
*/
interface BaseCredential<TSubject extends CredentialSubject = CredentialSubject, TType extends CredentialType = CredentialType> extends LooseObject<{
/** JSON-LD context */
"@context": JsonLdContext;
/** Credential identifier (optional) */
id?: Uri;
/** Credential types (must include VerifiableCredential) */
type: VerifiableCredentialType<TType>;
/** Credential issuer */
issuer: IdOrObject;
/** Credential status (optional) */
credentialStatus?: OneOrMany<CredentialStatus>;
/** Credential schema (optional) */
credentialSchema?: OneOrMany<CredentialSchemaType>;
/** Credential subject */
credentialSubject: OneOrMany<TSubject>;
/** Evidence (optional) */
evidence?: OneOrMany<GenericResource>;
/** Refresh service (optional) */
refreshService?: OneOrMany<GenericResource>;
/** Terms of use (optional) */
termsOfUse?: OneOrMany<GenericResource>;
}> {}
/**
* Base Verifiable Presentation properties.
* @see {@link https://www.w3.org/TR/vc-data-model-1.1/#verifiable-presentations}
*/
interface BasePresentation<TCredential extends BaseCredential, TType extends CredentialType = CredentialType> {
/** JSON-LD context (V1) */
"@context": JsonLdContext;
/** Presentation identifier (optional) */
id?: Uri;
/** Presentation types (must include VerifiablePresentation) */
type: VerifiablePresentationType<TType>;
/** Verifiable credentials */
verifiableCredential?: (TCredential | JwtString)[];
/** Presentation holder (optional) */
holder?: IdOrObject;
}
//#endregion
//#region src/types/vc/status/bitstring.d.ts
/**
* BitstringStatusList credential subject.
* @see {@link https://www.w3.org/TR/vc-bitstring-status-list/#bitstringstatuslistcredential}
*/
interface BitstringStatusListCredentialSubject extends CredentialSubject {
/** Type of the credential subject */
type: "BitstringStatusList";
/** Purpose of the status list (revocation or suspension) */
statusPurpose: StatusPurpose;
/** Base64url-encoded status list */
encodedList: Base64Url;
/** Time to live for the status list in seconds (optional) */
ttl?: number;
}
/**
* BitstringStatusList Credential.
* contexts: [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/status/v1"
],
* @see {@link https://www.w3.org/TR/vc-bitstring-status-list/#bitstringstatuslistcredential}
*/
interface BitstringStatusListCredential extends BaseCredential<BitstringStatusListCredentialSubject, "BitstringStatusListCredential"> {
/** Valid from date (V2) */
validFrom?: DateTimeStamp;
/** Valid until date (V2) */
validUntil?: DateTimeStamp;
}
//#endregion
//#region src/types/vc/status/statuslist2021.d.ts
/**
* StatusList2021 credential subject.
* @see {@link https://www.w3.org/TR/vc-status-list/#statuslist2021credential}
*/
interface StatusList2021CredentialSubject extends CredentialSubject {
/** Type of the credential subject */
type: "StatusList2021";
/** Purpose of the status list (revocation or suspension) */
statusPurpose: StatusPurpose;
/** Base64url-encoded status list */
encodedList: Base64Url;
}
/**
* StatusList2021 Credential.
* @see {@link https://www.w3.org/TR/vc-status-list/#statuslist2021credential}
*/
interface StatusList2021Credential extends BaseCredential<StatusList2021CredentialSubject, "StatusList2021Credential"> {
/** Issuance date (V1) */
issuanceDate: DateTimeStamp;
/** Expiration date (V1) */
expirationDate?: DateTimeStamp;
}
//#endregion
//#region src/types/vc/v1.d.ts
/**
* V1 Credential (unsigned).
* @see {@link https://www.w3.org/TR/vc-data-model-1.1/#credentials}
*/
interface CredentialV1<TSubject extends CredentialSubject = CredentialSubject, TType extends CredentialType = CredentialType> extends BaseCredential<TSubject, TType> {
/** Issuance date (V1) */
issuanceDate: DateTimeStamp;
/** Expiration date (V1) */
expirationDate?: DateTimeStamp;
}
/**
* V1 Verifiable Credential (signed).
* @see {@link https://www.w3.org/TR/vc-data-model-1.1/#credentials}
*/
type VerifiableCredentialV1<TSubject extends CredentialSubject = CredentialSubject, TType extends CredentialType = CredentialType> = Verifiable<CredentialV1<TSubject, TType>>;
/**
* V1 Presentation (unsigned)
* @see {@link https://www.w3.org/TR/vc-data-model-1.1/#verifiable-presentations}
*/
interface PresentationV1<TCredential extends VerifiableCredentialV1 = VerifiableCredentialV1, TType extends CredentialType = CredentialType> extends BasePresentation<TCredential, TType> {}
/**
* V1 Verifiable Presentation.
* @see {@link https://www.w3.org/TR/vc-data-model-1.1/#verifiable-presentations}
*/
type VerifiablePresentationV1<TCredential extends VerifiableCredentialV1 = VerifiableCredentialV1, TType extends CredentialType = CredentialType> = Verifiable<PresentationV1<TCredential, TType>>;
//#endregion
//#region src/types/vc/v2.d.ts
/**
* V2 Credential (unsigned).
* @see {@link https://www.w3.org/TR/vc-data-model-2.0/#credentials}
*/
interface CredentialV2<TSubject extends CredentialSubject = CredentialSubject, TType extends CredentialType = CredentialType> extends BaseCredential<TSubject, TType> {
validFrom?: DateTimeStamp;
/** Valid until date (V2) */
validUntil?: DateTimeStamp;
}
/**
* V2 Verifiable Credential (signed).
* @see {@link https://www.w3.org/TR/vc-data-model-2.0/#credentials}
*/
type VerifiableCredentialV2<TSubject extends CredentialSubject = CredentialSubject, TType extends CredentialType = CredentialType> = Verifiable<CredentialV2<TSubject, TType>>;
/**
* V2 Presentation (unsigned)
* @see {@link https://www.w3.org/TR/vc-data-model-2.0/#verifiable-presentations}
*/
interface PresentationV2<TCredential extends VerifiableCredentialV2 = VerifiableCredentialV2, TType extends CredentialType = CredentialType> extends BasePresentation<TCredential, TType> {}
/**
* V2 Verifiable Presentation.
* @see {@link https://www.w3.org/TR/vc-data-model-2.0/#verifiable-presentations}
*/
type VerifiablePresentationV2<TCredential extends VerifiableCredentialV2 = VerifiableCredentialV2, TType extends CredentialType = CredentialType> = Verifiable<PresentationV2<TCredential, TType>>;
//#endregion
//#region src/types/vc/vc.d.ts
type Credential<TSubject extends CredentialSubject = CredentialSubject, TType extends CredentialType = CredentialType> = CredentialV1<TSubject, TType> | CredentialV2<TSubject, TType>;
type VerifiableCredential<TSubject extends CredentialSubject = CredentialSubject, TType extends CredentialType = CredentialType> = Verifiable<Credential<TSubject, TType>>;
type Presentation<TCredential extends VerifiableCredential = VerifiableCredential, TType extends CredentialType = CredentialType> = TCredential extends VerifiableCredentialV1 ? PresentationV1<TCredential, TType> : TCredential extends VerifiableCredentialV2 ? PresentationV2<TCredential, TType> : PresentationV1 | PresentationV2;
type VerifiablePresentation<TCredential extends VerifiableCredential = VerifiableCredential, TType extends CredentialType = CredentialType> = Verifiable<Presentation<TCredential, TType>>;
//#endregion
export { ArrayContaining, Base64, Base64Url, BaseCredential, BaseJwk, BasePresentation, BitstringStatusListCredential, BitstringStatusListCredentialSubject, Credential, CredentialSchemaType, CredentialStatus, CredentialStatusType, CredentialSubject, CredentialType, CredentialV1, CredentialV2, CryptographicCurve, DateTimeStamp, Did, DidDocument, DidMethod, DidUrl, EcJwk, EllipticCurve, GenericResource, IdOrObject, JoseAlgorithm, JoseCompressionAlgorithm, JoseSignatureAlgorithm, JoseUnsecuredAlgorithm, JsonLdContext, JsonWebKey, JsonWebKeySet, Jwe, JweCompact, JweContentEncryptionAlgorithm, JweFlattenedJson, JweGeneralJson, JweKeyManagementAlgorithm, JweProtectedHeader, JweRecipient, JweUnprotectedHeader, Jws, JwsCompact, JwsFlattenedJson, JwsGeneralJson, JwsProtectedHeader, JwsSignature, JwsString, JwsUnprotectedHeader, JwtHeader, JwtHeaderBase, JwtHeaderSigned, JwtHeaderUnsecured, JwtObject, JwtObjectSigned, JwtObjectUnsecured, JwtPayload, JwtString, JwtStringParts, KeyOperation, KeyUse, LegacyVerificationMethodType, LooseObject, OctJwk, OctetKeyPairCurve, OkpJwk, OneOrMany, Presentation, PresentationV1, PresentationV2, Proof, ProofPurpose, RsaJwk, Service, ServiceEndpoint, ServiceEndpointMap, StatusList2021Credential, StatusList2021CredentialSubject, StatusPurpose, UnixTimestamp, Uri, Verifiable, VerifiableCredential, VerifiableCredentialType, VerifiableCredentialV1, VerifiableCredentialV2, VerifiablePresentation, VerifiablePresentationType, VerifiablePresentationV1, VerifiablePresentationV2, VerificationMethod, VerificationMethodJsonWebKey, VerificationMethodLegacy, VerificationMethodMultikey, VerificationMethodType };