@kya-os/contracts 1.3.5 → 1.5.1

package/dist/vc/statuslist.d.ts

@@ -0,0 +1,493 @@
+/**
+ * StatusList2021 Types and Schemas
+ *
+ * Implementation of the W3C StatusList2021 specification for credential status.
+ * Provides types for status list credentials and helpers for bitstring operations.
+ *
+ * Related Spec: W3C StatusList2021
+ * Python Reference: Credential-Documentation.md (StatusList2021 section)
+ */
+import { z } from 'zod';
+/**
+ * Status Purpose
+ *
+ * Indicates the purpose of the status list
+ */
+export type StatusPurpose = 'revocation' | 'suspension';
+/**
+ * Status List Credential Subject Schema
+ *
+ * The credential subject of a StatusList2021Credential
+ */
+export declare const StatusList2021CredentialSubjectSchema: z.ZodObject<{
+    /** Optional identifier for the status list */
+    id: z.ZodOptional<z.ZodString>;
+    /** Type MUST be StatusList2021 */
+    type: z.ZodLiteral<"StatusList2021">;
+    /** Purpose of the status list */
+    statusPurpose: z.ZodEnum<["revocation", "suspension"]>;
+    /**
+     * Encoded bitstring
+     *
+     * Base64url-encoded and GZIP-compressed bitstring.
+     * Each bit represents the status of a credential:
+     * - 0: Not revoked/suspended
+     * - 1: Revoked/suspended
+     */
+    encodedList: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "StatusList2021";
+    statusPurpose: "revocation" | "suspension";
+    encodedList: string;
+    id?: string | undefined;
+}, {
+    type: "StatusList2021";
+    statusPurpose: "revocation" | "suspension";
+    encodedList: string;
+    id?: string | undefined;
+}>;
+/**
+ * StatusList2021 Credential Schema
+ *
+ * A credential that contains a status list for checking revocation/suspension
+ * of other credentials.
+ */
+export declare const StatusList2021CredentialSchema: z.ZodObject<{
+    /** JSON-LD context */
+    '@context': z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodAny>]>, "atleastone">, [string | Record<string, any>, ...(string | Record<string, any>)[]], [string | Record<string, any>, ...(string | Record<string, any>)[]]>, [string | Record<string, any>, ...(string | Record<string, any>)[]], [string | Record<string, any>, ...(string | Record<string, any>)[]]>;
+    /** Unique identifier for the status list credential */
+    id: z.ZodString;
+    /** Type MUST include VerifiableCredential and StatusList2021Credential */
+    type: z.ZodUnion<[z.ZodTuple<[z.ZodLiteral<"VerifiableCredential">, z.ZodLiteral<"StatusList2021Credential">], null>, z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>]>;
+    /** Issuer of the status list credential */
+    issuer: z.ZodUnion<[z.ZodString, z.ZodObject<{
+        id: z.ZodString;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        id: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        id: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">>]>;
+    /** Issuance date in ISO 8601 format */
+    issuanceDate: z.ZodString;
+    /** The status list credential subject */
+    credentialSubject: z.ZodObject<{
+        /** Optional identifier for the status list */
+        id: z.ZodOptional<z.ZodString>;
+        /** Type MUST be StatusList2021 */
+        type: z.ZodLiteral<"StatusList2021">;
+        /** Purpose of the status list */
+        statusPurpose: z.ZodEnum<["revocation", "suspension"]>;
+        /**
+         * Encoded bitstring
+         *
+         * Base64url-encoded and GZIP-compressed bitstring.
+         * Each bit represents the status of a credential:
+         * - 0: Not revoked/suspended
+         * - 1: Revoked/suspended
+         */
+        encodedList: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "StatusList2021";
+        statusPurpose: "revocation" | "suspension";
+        encodedList: string;
+        id?: string | undefined;
+    }, {
+        type: "StatusList2021";
+        statusPurpose: "revocation" | "suspension";
+        encodedList: string;
+        id?: string | undefined;
+    }>;
+    /** Cryptographic proof (optional) */
+    proof: z.ZodOptional<z.ZodObject<{
+        type: z.ZodString;
+        created: z.ZodOptional<z.ZodString>;
+        verificationMethod: z.ZodOptional<z.ZodString>;
+        proofPurpose: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        type: z.ZodString;
+        created: z.ZodOptional<z.ZodString>;
+        verificationMethod: z.ZodOptional<z.ZodString>;
+        proofPurpose: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        type: z.ZodString;
+        created: z.ZodOptional<z.ZodString>;
+        verificationMethod: z.ZodOptional<z.ZodString>;
+        proofPurpose: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    /** JSON-LD context */
+    '@context': z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodAny>]>, "atleastone">, [string | Record<string, any>, ...(string | Record<string, any>)[]], [string | Record<string, any>, ...(string | Record<string, any>)[]]>, [string | Record<string, any>, ...(string | Record<string, any>)[]], [string | Record<string, any>, ...(string | Record<string, any>)[]]>;
+    /** Unique identifier for the status list credential */
+    id: z.ZodString;
+    /** Type MUST include VerifiableCredential and StatusList2021Credential */
+    type: z.ZodUnion<[z.ZodTuple<[z.ZodLiteral<"VerifiableCredential">, z.ZodLiteral<"StatusList2021Credential">], null>, z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>]>;
+    /** Issuer of the status list credential */
+    issuer: z.ZodUnion<[z.ZodString, z.ZodObject<{
+        id: z.ZodString;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        id: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        id: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">>]>;
+    /** Issuance date in ISO 8601 format */
+    issuanceDate: z.ZodString;
+    /** The status list credential subject */
+    credentialSubject: z.ZodObject<{
+        /** Optional identifier for the status list */
+        id: z.ZodOptional<z.ZodString>;
+        /** Type MUST be StatusList2021 */
+        type: z.ZodLiteral<"StatusList2021">;
+        /** Purpose of the status list */
+        statusPurpose: z.ZodEnum<["revocation", "suspension"]>;
+        /**
+         * Encoded bitstring
+         *
+         * Base64url-encoded and GZIP-compressed bitstring.
+         * Each bit represents the status of a credential:
+         * - 0: Not revoked/suspended
+         * - 1: Revoked/suspended
+         */
+        encodedList: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "StatusList2021";
+        statusPurpose: "revocation" | "suspension";
+        encodedList: string;
+        id?: string | undefined;
+    }, {
+        type: "StatusList2021";
+        statusPurpose: "revocation" | "suspension";
+        encodedList: string;
+        id?: string | undefined;
+    }>;
+    /** Cryptographic proof (optional) */
+    proof: z.ZodOptional<z.ZodObject<{
+        type: z.ZodString;
+        created: z.ZodOptional<z.ZodString>;
+        verificationMethod: z.ZodOptional<z.ZodString>;
+        proofPurpose: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        type: z.ZodString;
+        created: z.ZodOptional<z.ZodString>;
+        verificationMethod: z.ZodOptional<z.ZodString>;
+        proofPurpose: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        type: z.ZodString;
+        created: z.ZodOptional<z.ZodString>;
+        verificationMethod: z.ZodOptional<z.ZodString>;
+        proofPurpose: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    /** JSON-LD context */
+    '@context': z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodAny>]>, "atleastone">, [string | Record<string, any>, ...(string | Record<string, any>)[]], [string | Record<string, any>, ...(string | Record<string, any>)[]]>, [string | Record<string, any>, ...(string | Record<string, any>)[]], [string | Record<string, any>, ...(string | Record<string, any>)[]]>;
+    /** Unique identifier for the status list credential */
+    id: z.ZodString;
+    /** Type MUST include VerifiableCredential and StatusList2021Credential */
+    type: z.ZodUnion<[z.ZodTuple<[z.ZodLiteral<"VerifiableCredential">, z.ZodLiteral<"StatusList2021Credential">], null>, z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>]>;
+    /** Issuer of the status list credential */
+    issuer: z.ZodUnion<[z.ZodString, z.ZodObject<{
+        id: z.ZodString;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        id: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        id: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">>]>;
+    /** Issuance date in ISO 8601 format */
+    issuanceDate: z.ZodString;
+    /** The status list credential subject */
+    credentialSubject: z.ZodObject<{
+        /** Optional identifier for the status list */
+        id: z.ZodOptional<z.ZodString>;
+        /** Type MUST be StatusList2021 */
+        type: z.ZodLiteral<"StatusList2021">;
+        /** Purpose of the status list */
+        statusPurpose: z.ZodEnum<["revocation", "suspension"]>;
+        /**
+         * Encoded bitstring
+         *
+         * Base64url-encoded and GZIP-compressed bitstring.
+         * Each bit represents the status of a credential:
+         * - 0: Not revoked/suspended
+         * - 1: Revoked/suspended
+         */
+        encodedList: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "StatusList2021";
+        statusPurpose: "revocation" | "suspension";
+        encodedList: string;
+        id?: string | undefined;
+    }, {
+        type: "StatusList2021";
+        statusPurpose: "revocation" | "suspension";
+        encodedList: string;
+        id?: string | undefined;
+    }>;
+    /** Cryptographic proof (optional) */
+    proof: z.ZodOptional<z.ZodObject<{
+        type: z.ZodString;
+        created: z.ZodOptional<z.ZodString>;
+        verificationMethod: z.ZodOptional<z.ZodString>;
+        proofPurpose: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        type: z.ZodString;
+        created: z.ZodOptional<z.ZodString>;
+        verificationMethod: z.ZodOptional<z.ZodString>;
+        proofPurpose: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        type: z.ZodString;
+        created: z.ZodOptional<z.ZodString>;
+        verificationMethod: z.ZodOptional<z.ZodString>;
+        proofPurpose: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>>;
+}, z.ZodTypeAny, "passthrough">>;
+/**
+ * Type exports
+ */
+export type StatusList2021CredentialSubject = z.infer<typeof StatusList2021CredentialSubjectSchema>;
+export type StatusList2021Credential = z.infer<typeof StatusList2021CredentialSchema>;
+/**
+ * StatusList2021 Credential Type (traditional TypeScript interface)
+ *
+ * For use when not using Zod validation
+ */
+export interface StatusList2021CredentialInterface {
+    '@context': (string | Record<string, any>)[];
+    id: string;
+    type: ['VerifiableCredential', 'StatusList2021Credential'];
+    issuer: string | {
+        id: string;
+    };
+    issuanceDate: string;
+    credentialSubject: {
+        id?: string;
+        type: 'StatusList2021';
+        statusPurpose: 'revocation' | 'suspension';
+        encodedList: string;
+    };
+    proof?: Record<string, any>;
+}
+/**
+ * Validation Helpers
+ */
+/**
+ * Validate a StatusList2021 credential
+ *
+ * @param credential - The credential to validate
+ * @returns Validation result with parsed credential or errors
+ */
+export declare function validateStatusList2021Credential(credential: unknown): z.SafeParseReturnType<z.objectInputType<{
+    /** JSON-LD context */
+    '@context': z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodAny>]>, "atleastone">, [string | Record<string, any>, ...(string | Record<string, any>)[]], [string | Record<string, any>, ...(string | Record<string, any>)[]]>, [string | Record<string, any>, ...(string | Record<string, any>)[]], [string | Record<string, any>, ...(string | Record<string, any>)[]]>;
+    /** Unique identifier for the status list credential */
+    id: z.ZodString;
+    /** Type MUST include VerifiableCredential and StatusList2021Credential */
+    type: z.ZodUnion<[z.ZodTuple<[z.ZodLiteral<"VerifiableCredential">, z.ZodLiteral<"StatusList2021Credential">], null>, z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>]>;
+    /** Issuer of the status list credential */
+    issuer: z.ZodUnion<[z.ZodString, z.ZodObject<{
+        id: z.ZodString;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        id: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        id: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">>]>;
+    /** Issuance date in ISO 8601 format */
+    issuanceDate: z.ZodString;
+    /** The status list credential subject */
+    credentialSubject: z.ZodObject<{
+        /** Optional identifier for the status list */
+        id: z.ZodOptional<z.ZodString>;
+        /** Type MUST be StatusList2021 */
+        type: z.ZodLiteral<"StatusList2021">;
+        /** Purpose of the status list */
+        statusPurpose: z.ZodEnum<["revocation", "suspension"]>;
+        /**
+         * Encoded bitstring
+         *
+         * Base64url-encoded and GZIP-compressed bitstring.
+         * Each bit represents the status of a credential:
+         * - 0: Not revoked/suspended
+         * - 1: Revoked/suspended
+         */
+        encodedList: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "StatusList2021";
+        statusPurpose: "revocation" | "suspension";
+        encodedList: string;
+        id?: string | undefined;
+    }, {
+        type: "StatusList2021";
+        statusPurpose: "revocation" | "suspension";
+        encodedList: string;
+        id?: string | undefined;
+    }>;
+    /** Cryptographic proof (optional) */
+    proof: z.ZodOptional<z.ZodObject<{
+        type: z.ZodString;
+        created: z.ZodOptional<z.ZodString>;
+        verificationMethod: z.ZodOptional<z.ZodString>;
+        proofPurpose: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        type: z.ZodString;
+        created: z.ZodOptional<z.ZodString>;
+        verificationMethod: z.ZodOptional<z.ZodString>;
+        proofPurpose: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        type: z.ZodString;
+        created: z.ZodOptional<z.ZodString>;
+        verificationMethod: z.ZodOptional<z.ZodString>;
+        proofPurpose: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>>;
+}, z.ZodTypeAny, "passthrough">, z.objectOutputType<{
+    /** JSON-LD context */
+    '@context': z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodAny>]>, "atleastone">, [string | Record<string, any>, ...(string | Record<string, any>)[]], [string | Record<string, any>, ...(string | Record<string, any>)[]]>, [string | Record<string, any>, ...(string | Record<string, any>)[]], [string | Record<string, any>, ...(string | Record<string, any>)[]]>;
+    /** Unique identifier for the status list credential */
+    id: z.ZodString;
+    /** Type MUST include VerifiableCredential and StatusList2021Credential */
+    type: z.ZodUnion<[z.ZodTuple<[z.ZodLiteral<"VerifiableCredential">, z.ZodLiteral<"StatusList2021Credential">], null>, z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>]>;
+    /** Issuer of the status list credential */
+    issuer: z.ZodUnion<[z.ZodString, z.ZodObject<{
+        id: z.ZodString;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        id: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        id: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">>]>;
+    /** Issuance date in ISO 8601 format */
+    issuanceDate: z.ZodString;
+    /** The status list credential subject */
+    credentialSubject: z.ZodObject<{
+        /** Optional identifier for the status list */
+        id: z.ZodOptional<z.ZodString>;
+        /** Type MUST be StatusList2021 */
+        type: z.ZodLiteral<"StatusList2021">;
+        /** Purpose of the status list */
+        statusPurpose: z.ZodEnum<["revocation", "suspension"]>;
+        /**
+         * Encoded bitstring
+         *
+         * Base64url-encoded and GZIP-compressed bitstring.
+         * Each bit represents the status of a credential:
+         * - 0: Not revoked/suspended
+         * - 1: Revoked/suspended
+         */
+        encodedList: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "StatusList2021";
+        statusPurpose: "revocation" | "suspension";
+        encodedList: string;
+        id?: string | undefined;
+    }, {
+        type: "StatusList2021";
+        statusPurpose: "revocation" | "suspension";
+        encodedList: string;
+        id?: string | undefined;
+    }>;
+    /** Cryptographic proof (optional) */
+    proof: z.ZodOptional<z.ZodObject<{
+        type: z.ZodString;
+        created: z.ZodOptional<z.ZodString>;
+        verificationMethod: z.ZodOptional<z.ZodString>;
+        proofPurpose: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        type: z.ZodString;
+        created: z.ZodOptional<z.ZodString>;
+        verificationMethod: z.ZodOptional<z.ZodString>;
+        proofPurpose: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        type: z.ZodString;
+        created: z.ZodOptional<z.ZodString>;
+        verificationMethod: z.ZodOptional<z.ZodString>;
+        proofPurpose: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>>;
+}, z.ZodTypeAny, "passthrough">>;
+/**
+ * Helper Types for Bitstring Operations
+ *
+ * These types define the interface for bitstring encode/decode operations.
+ * Actual implementation would be in a separate utility module.
+ */
+/**
+ * Bitstring encoding options
+ */
+export interface BitStringEncodeOptions {
+    /** Total size of the bitstring (number of bits) */
+    size: number;
+    /** Positions to set to 1 (revoked/suspended) */
+    setBits?: number[];
+}
+/**
+ * Bitstring decoding result
+ */
+export interface BitStringDecodeResult {
+    /** Total size of the bitstring */
+    size: number;
+    /** Positions that are set to 1 */
+    setBits: number[];
+    /** Check if a specific index is set */
+    isSet: (index: number) => boolean;
+}
+/**
+ * Cache entry for StatusList2021 credentials
+ *
+ * Used for efficient caching of status list credentials with ETag support
+ */
+export interface StatusListCacheEntry {
+    /** The cached status list credential */
+    credential: StatusList2021Credential;
+    /** ETag from the HTTP response (if applicable) */
+    etag?: string;
+    /** Timestamp when cached (milliseconds since epoch) */
+    cachedAt: number;
+    /** TTL in seconds */
+    ttlSec: number;
+    /** Expires at timestamp (milliseconds since epoch) */
+    expiresAt: number;
+}
+/**
+ * Status checking result
+ */
+export interface StatusCheckResult {
+    /** Whether the credential is valid (not revoked/suspended) */
+    valid: boolean;
+    /** The status (active, revoked, suspended) */
+    status: 'active' | 'revoked' | 'suspended';
+    /** Optional reason for status */
+    reason?: string;
+    /** Timestamp when checked */
+    checkedAt: number;
+    /** Whether result came from cache */
+    fromCache?: boolean;
+}
+/**
+ * Helper to create a minimal status list credential structure
+ *
+ * This is a type-safe helper, actual credential creation requires
+ * proper signing and encoding implementation.
+ *
+ * @param config - Configuration for the status list credential
+ * @returns Partial credential structure (needs proof to be complete)
+ */
+export declare function createStatusListCredentialStructure(config: {
+    id: string;
+    issuer: string | {
+        id: string;
+    };
+    statusPurpose: StatusPurpose;
+    encodedList: string;
+}): Omit<StatusList2021Credential, 'proof'>;
+/**
+ * Constants
+ */
+/**
+ * Default cache TTL for status list credentials (in seconds)
+ * As per spec recommendation
+ */
+export declare const DEFAULT_STATUSLIST_CACHE_TTL_SEC = 60;
+/**
+ * Maximum reasonable bitstring size
+ * Used for validation to prevent memory exhaustion
+ */
+export declare const MAX_STATUSLIST_SIZE = 1000000;
+/**
+ * StatusList2021 context URL
+ */
+export declare const STATUSLIST_2021_CONTEXT = "https://w3id.org/vc/status-list/2021/v1";

package/dist/vc/statuslist.js

@@ -0,0 +1,132 @@
+"use strict";
+/**
+ * StatusList2021 Types and Schemas
+ *
+ * Implementation of the W3C StatusList2021 specification for credential status.
+ * Provides types for status list credentials and helpers for bitstring operations.
+ *
+ * Related Spec: W3C StatusList2021
+ * Python Reference: Credential-Documentation.md (StatusList2021 section)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STATUSLIST_2021_CONTEXT = exports.MAX_STATUSLIST_SIZE = exports.DEFAULT_STATUSLIST_CACHE_TTL_SEC = exports.StatusList2021CredentialSchema = exports.StatusList2021CredentialSubjectSchema = void 0;
+exports.validateStatusList2021Credential = validateStatusList2021Credential;
+exports.createStatusListCredentialStructure = createStatusListCredentialStructure;
+const zod_1 = require("zod");
+const schemas_js_1 = require("./schemas.js");
+/**
+ * Status List Credential Subject Schema
+ *
+ * The credential subject of a StatusList2021Credential
+ */
+exports.StatusList2021CredentialSubjectSchema = zod_1.z.object({
+    /** Optional identifier for the status list */
+    id: zod_1.z.string().optional(),
+    /** Type MUST be StatusList2021 */
+    type: zod_1.z.literal('StatusList2021'),
+    /** Purpose of the status list */
+    statusPurpose: zod_1.z.enum(['revocation', 'suspension']),
+    /**
+     * Encoded bitstring
+     *
+     * Base64url-encoded and GZIP-compressed bitstring.
+     * Each bit represents the status of a credential:
+     * - 0: Not revoked/suspended
+     * - 1: Revoked/suspended
+     */
+    encodedList: zod_1.z.string().regex(/^[A-Za-z0-9_-]+$/, {
+        message: 'encodedList must be base64url encoded',
+    }),
+});
+/**
+ * StatusList2021 Credential Schema
+ *
+ * A credential that contains a status list for checking revocation/suspension
+ * of other credentials.
+ */
+exports.StatusList2021CredentialSchema = zod_1.z.object({
+    /** JSON-LD context */
+    '@context': schemas_js_1.ContextSchema.refine((contexts) => {
+        // Must include both base VC context and StatusList context
+        return (contexts.length >= 2 &&
+            typeof contexts[0] === 'string' &&
+            contexts[0] === 'https://www.w3.org/2018/credentials/v1' &&
+            (contexts.includes('https://w3id.org/vc/status-list/2021/v1') ||
+                contexts.some((ctx) => typeof ctx === 'object' &&
+                    ctx['StatusList2021Credential'] !== undefined)));
+    }, {
+        message: '@context must include VC context and StatusList2021 context',
+    }),
+    /** Unique identifier for the status list credential */
+    id: zod_1.z.string().url(),
+    /** Type MUST include VerifiableCredential and StatusList2021Credential */
+    type: zod_1.z
+        .tuple([zod_1.z.literal('VerifiableCredential'), zod_1.z.literal('StatusList2021Credential')])
+        .or(zod_1.z.array(zod_1.z.string()).refine((types) => types.includes('VerifiableCredential') &&
+        types.includes('StatusList2021Credential'), {
+        message: 'type must include "VerifiableCredential" and "StatusList2021Credential"',
+    })),
+    /** Issuer of the status list credential */
+    issuer: schemas_js_1.IssuerSchema,
+    /** Issuance date in ISO 8601 format */
+    issuanceDate: zod_1.z.string().datetime(),
+    /** The status list credential subject */
+    credentialSubject: exports.StatusList2021CredentialSubjectSchema,
+    /** Cryptographic proof (optional) */
+    proof: schemas_js_1.ProofSchema.optional(),
+}).passthrough();
+/**
+ * Validation Helpers
+ */
+/**
+ * Validate a StatusList2021 credential
+ *
+ * @param credential - The credential to validate
+ * @returns Validation result with parsed credential or errors
+ */
+function validateStatusList2021Credential(credential) {
+    return exports.StatusList2021CredentialSchema.safeParse(credential);
+}
+/**
+ * Helper to create a minimal status list credential structure
+ *
+ * This is a type-safe helper, actual credential creation requires
+ * proper signing and encoding implementation.
+ *
+ * @param config - Configuration for the status list credential
+ * @returns Partial credential structure (needs proof to be complete)
+ */
+function createStatusListCredentialStructure(config) {
+    return {
+        '@context': [
+            'https://www.w3.org/2018/credentials/v1',
+            'https://w3id.org/vc/status-list/2021/v1',
+        ],
+        id: config.id,
+        type: ['VerifiableCredential', 'StatusList2021Credential'],
+        issuer: config.issuer,
+        issuanceDate: new Date().toISOString(),
+        credentialSubject: {
+            type: 'StatusList2021',
+            statusPurpose: config.statusPurpose,
+            encodedList: config.encodedList,
+        },
+    };
+}
+/**
+ * Constants
+ */
+/**
+ * Default cache TTL for status list credentials (in seconds)
+ * As per spec recommendation
+ */
+exports.DEFAULT_STATUSLIST_CACHE_TTL_SEC = 60;
+/**
+ * Maximum reasonable bitstring size
+ * Used for validation to prevent memory exhaustion
+ */
+exports.MAX_STATUSLIST_SIZE = 1000000; // 1 million entries
+/**
+ * StatusList2021 context URL
+ */
+exports.STATUSLIST_2021_CONTEXT = 'https://w3id.org/vc/status-list/2021/v1';

package/dist/verifier.d.ts

@@ -1,4 +1,7 @@
 import { z } from "zod";
+/**
+ * Verifier middleware schemas and headers
+ */
 export declare const AgentContextSchema: z.ZodObject<{
     did: z.ZodString;
     kid: z.ZodString;

package/dist/verifier.js

@@ -2,6 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ERROR_HTTP_STATUS = exports.VERIFIER_ERROR_CODES = exports.AGENT_HEADERS = exports.StructuredErrorSchema = exports.VerifierResultSchema = exports.AgentContextSchema = void 0;
 const zod_1 = require("zod");
+/**
+ * Verifier middleware schemas and headers
+ */
 exports.AgentContextSchema = zod_1.z.object({
     did: zod_1.z.string().min(1),
     kid: zod_1.z.string().min(1),
@@ -39,6 +42,7 @@ exports.StructuredErrorSchema = zod_1.z.object({
     })
         .optional(),
 });
+// Header constants (frozen names)
 exports.AGENT_HEADERS = {
     DID: "X-Agent-DID",
     KEY_ID: "X-Agent-KeyId",
@@ -50,6 +54,7 @@ exports.AGENT_HEADERS = {
     REGISTRY: "X-Agent-Registry",
     VERIFIED_AT: "X-Agent-Verified-At",
 };
+// Verifier-specific error codes
 exports.VERIFIER_ERROR_CODES = {
     PROOF_INVALID_TS: "XMCP_I_PROOF_INVALID_TS",
     PROOF_FUTURE_TS: "XMCP_I_PROOF_FUTURE_TS",
@@ -58,6 +63,7 @@ exports.VERIFIER_ERROR_CODES = {
     SESSION_IDLE_EXPIRED: "XMCP_I_SESSION_IDLE_EXPIRED",
     SERVER_TIME_INVALID: "XMCP_I_SERVER_TIME_INVALID",
 };
+// HTTP status mappings
 exports.ERROR_HTTP_STATUS = {
     XMCP_I_EBADPROOF: 403,
     XMCP_I_ENOIDENTITY: 500,
@@ -67,6 +73,7 @@ exports.ERROR_HTTP_STATUS = {
     XMCP_I_ECLAIM: 400,
     XMCP_I_ECONFIG: 500,
     XMCP_I_ERUNTIME: 500,
+    // Verifier-specific codes
     [exports.VERIFIER_ERROR_CODES.PROOF_INVALID_TS]: 403,
     [exports.VERIFIER_ERROR_CODES.PROOF_FUTURE_TS]: 403,
     [exports.VERIFIER_ERROR_CODES.PROOF_TOO_OLD]: 403,