web-identity-schemas

v0.2.0

Published

4 months ago

TypeScript types and validation schemas for Web Identity and JOSE standards, including:

Web Identity Schemas

TypeScript types and validation schemas for Web Identity and JOSE standards, including:

Decentralized Identifiers (DID)
Verifiable Credentials (VC) v1.1 and v2.0, with StatusList2021, Bitstring Status List
Verifiable Presentations (VP)
JSON Web Tokens (JWT)
JSON Web Keys (JWK)
JSON Web Signatures (JWS)
See the full list

This library provides both Valibot and Zod (v4) validation implementations with comprehensive type safety.

Installation

npm install web-identity-schemas

Quick Start

Valibot

import * as v from "valibot"
import {
  DidSchema,
  JwkSchema,
  VerifiableCredentialSchema
} from "web-identity-schemas/valibot"

// Validate a DID
const validDid = v.parse(DidSchema, "did:example:123456789abcdefghi")

// Validate a Verifiable Credential
const validVc = v.parse(VerifiableCredentialSchema, {
  "@context": "https://www.w3.org/2018/credentials/v1",
  type: "VerifiableCredential",
  issuer: "did:example:issuer",
  issuanceDate: "2023-01-01T00:00:00Z",
  credentialSubject: {
    id: "did:example:subject",
    degree: "Bachelor of Science"
  }
})

// Validate cryptographic keys
const validKey = v.parse(JsonWebKeySchema, {
  kty: "EC",
  crv: "P-256",
  x: "MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
  y: "4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM"
})

Zod v4

import * as z from "zod"
import {
  DidSchema,
  JwkSchema,
  VerifiableCredentialSchema
} from "web-identity-schemas/zod"

// Validate a DID
const validDid = DidSchema.parse("did:example:123456789abcdefghi")

// Validate a Verifiable Credential
const validVc = VerifiableCredentialSchema.parse({
  "@context": "https://www.w3.org/2018/credentials/v1",
  type: "VerifiableCredential",
  issuer: "did:example:issuer",
  issuanceDate: "2023-01-01T00:00:00Z",
  credentialSubject: {
    id: "did:example:subject",
    degree: "Bachelor of Science"
  }
})

// Validate cryptographic keys
const validKey = JsonWebKeySchema.parse({
  kty: "EC",
  crv: "P-256",
  x: "MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
  y: "4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM"
})

Type Safety

All types are also available as Typescript types at the root of the package, and in each schema export

import type { Did, DidDocument, JwtString } from "web-identity-schemas"
// or from "web-identity-schemas/valibot"
// or from "web-identity-schemas/zod"

const jwt: JwtString = "..."

const did: Did = "did:method:something"
const didWeb: Did<"web"> = "did:web:example.com"

const didDocument: DidDocument = {
  // ...
}

Available Schemas

This library exports comprehensive schemas for Web Identity and JOSE standards. All schemas are available in both Valibot and Zod implementations, with corresponding TypeScript types.

Core Web Identity Schemas

Decentralized Identifiers (DIDs)

DidSchema - Validates DID strings (e.g., did:example:123)
- Types | Valibot | Zod
DidUrlSchema - Validates DID URLs with paths/queries/fragments
- Types | Valibot | Zod
DidDocumentSchema - Validates DID Documents
- Types | Valibot | Zod
VerificationMethodSchema - Validates verification methods in DID Documents
- Types | Valibot | Zod
ServiceSchema - Validates service endpoints in DID Documents
- Types | Valibot | Zod

Verifiable Credentials (VCs)

VerifiableCredentialSchema - Universal VC validator (v1.1 and v2.0)
- Types | Valibot | Zod
VerifiableCredentialV1Schema - Specific v1.1 VC validator
- Types | Valibot | Zod
VerifiableCredentialV2Schema - Specific v2.0 VC validator
- Types | Valibot | Zod
VerifiablePresentationSchema - Validates verifiable presentations
- Types | Valibot | Zod

JSON Web Tokens (JWTs)

JwtObjectSchema - Validates JWT objects (header + payload)
- Types | Valibot | Zod
JwtStringSchema - Validates JWT strings in compact format
- Types | Valibot | Zod
JwtHeaderSignedSchema - Validates JWT headers for signed tokens
- Types | Valibot | Zod
JwtPayloadSchema - Validates JWT payloads
- Types | Valibot | Zod

JSON Web Keys (JWKs)

JsonWebKeySchema - Universal JWK validator (all key types)
- Types | Valibot | Zod
JsonWebKeySetSchema - Validates JWK Sets
- Types | Valibot | Zod

Cryptographic Schemas

Specific JWK Types

RsaJwkSchema - RSA keys (kty: "RSA")
- Types | Valibot | Zod
EcJwkSchema - Elliptic Curve keys (kty: "EC")
- Types | Valibot | Zod
OctJwkSchema - Symmetric keys (kty: "oct")
- Types | Valibot | Zod
OkpJwkSchema - Octet Key Pair keys (kty: "OKP")
- Types | Valibot | Zod

Cryptographic Curves

EllipticCurveSchema - Elliptic curve names (P-256, P-384, etc.)
- Types | Valibot | Zod
OctetKeyPairCurveSchema - OKP curve names (Ed25519, X25519)
- Types | Valibot | Zod

JOSE Specifications

JSON Web Signatures (JWS)

JwsObjectSchema - JWS in object format
- Types | Valibot | Zod
JwsStringSchema - JWS in compact string format
- Types | Valibot | Zod
JwsJsonSerializationSchema - JWS JSON General Serialization
- Types | Valibot | Zod
JwsFlattenedJsonSerializationSchema - JWS JSON Flattened Serialization
- Types | Valibot | Zod

JSON Web Encryption (JWE)

JweObjectSchema - JWE in object format
- Types | Valibot | Zod
JweStringSchema - JWE in compact string format
- Types | Valibot | Zod
JweJsonSerializationSchema - JWE JSON General Serialization
- Types | Valibot | Zod
JweFlattenedJsonSerializationSchema - JWE JSON Flattened Serialization
- Types | Valibot | Zod

JOSE Algorithms

JoseAlgorithmSchema - All JOSE algorithms
- Types | Valibot | Zod
JoseSignatureAlgorithmSchema - Signature algorithms (RS256, ES256, etc.)
- Types | Valibot | Zod
JweContentEncryptionAlgorithmSchema - Content encryption algorithms
- Types | Valibot | Zod
JweKeyManagementAlgorithmSchema - Key management algorithms
- Types | Valibot | Zod

Status and Proof Schemas

Credential Status

StatusList2021CredentialSchema - StatusList2021 credentials
- Types | Valibot | Zod
BitstringStatusListCredentialSchema - Bitstring status credentials
- Types | Valibot | Zod

Proof Systems

ProofSchema - Cryptographic proof objects
- Types | Valibot | Zod

Utility Schemas

Common Formats

UriSchema - URI format validation
- Types | Valibot | Zod
Base64UrlSchema - Base64url encoded strings
- Types | Valibot | Zod
Base64Schema - Base64 encoded strings
- Types | Valibot | Zod
DateTimeStampSchema - ISO 8601 datetime strings
- Types | Valibot | Zod

Contributing

Contributions are welcome.

This library maintains strict type safety and comprehensive test coverage. Both Valibot and Zod implementations must pass identical test suites to ensure consistency.

See CLAUDE.md for detailed development guidelines and schema patterns.