@vess-id/status-list 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,1634 @@
+import { KeyLike } from 'jose';
+
+/**
+ * Number of bits used per status entry in the status list.
+ * Must be one of: 1, 2, 4, or 8 bits per status.
+ *
+ * - 1 bit: 2 possible states (e.g., valid/invalid)
+ * - 2 bits: 4 possible states (e.g., valid/invalid/suspended/custom)
+ * - 4 bits: 16 possible states
+ * - 8 bits: 256 possible states
+ */
+type BitsPerStatus = 1 | 2 | 4 | 8;
+/**
+ * Status value for a credential.
+ * Valid range: 0 to (2^bitsPerStatus - 1)
+ *
+ * For 1-bit: 0-1
+ * For 2-bit: 0-3
+ * For 4-bit: 0-15
+ * For 8-bit: 0-255
+ */
+type StatusValue = number;
+/**
+ * Standard status values defined by the IETF OAuth Status List specification.
+ *
+ * @see https://www.ietf.org/archive/id/draft-ietf-oauth-status-list-14.html#section-7
+ */
+declare enum StandardStatusValues {
+    /**
+     * 0x00: The status of the Referenced Token is VALID, CORRECT, or NOT_REVOKED.
+     */
+    VALID = 0,
+    /**
+     * 0x01: The status of the Referenced Token is INVALID, REVOKED, ANNULLED, RECALLED, or CANCELLED.
+     */
+    INVALID = 1,
+    /**
+     * 0x02: The status of the Referenced Token is SUSPENDED.
+     * The Issuer may decide to set this status temporarily to investigate
+     * or respond to specific situations (e.g., fraud investigation).
+     */
+    SUSPENDED = 2,
+    /**
+     * 0x03: Application-specific status value.
+     */
+    APPLICATION_SPECIFIC = 3
+}
+/**
+ * Format of the status list token.
+ */
+type StatusFormat = 'jwt' | 'cwt';
+/**
+ * Configuration for creating a status list.
+ */
+interface StatusListConfig {
+    /**
+     * Number of entries in the status list.
+     */
+    size: number;
+    /**
+     * Number of bits per status entry.
+     */
+    bitsPerStatus: BitsPerStatus;
+    /**
+     * Optional URI for status list aggregation.
+     */
+    aggregationUri?: string;
+}
+
+/**
+ * Represents a Status List containing credential statuses in a compressed bit array.
+ *
+ * The StatusList class manages a byte array where each status entry uses a configurable
+ * number of bits (1, 2, 4, or 8). This allows efficient storage of credential status
+ * information for thousands or millions of credentials.
+ *
+ * @example
+ * ```typescript
+ * // Create a status list with 1000 entries (all valid)
+ * const list = StatusList.fromArray(new Array(1000).fill(0), 1);
+ *
+ * // Revoke a credential at index 42
+ * list.setStatus(42, 1);
+ *
+ * // Compress for JWT
+ * const compressed = list.compressToBase64URL();
+ * ```
+ */
+declare class StatusList {
+    private readonly statusArray;
+    private readonly bitsPerStatus;
+    /**
+     * Creates a StatusList from a byte array.
+     *
+     * @param statusArray - Byte array containing packed status values
+     * @param bitsPerStatus - Number of bits per status entry
+     *
+     * @private Use static factory methods instead: fromArray(), decompressFromBase64URL(), decompressFromBytes()
+     */
+    constructor(statusArray: Uint8Array, bitsPerStatus: BitsPerStatus);
+    /**
+     * Gets the status value at a specific index.
+     *
+     * @param index - Index of the status entry (0-based)
+     * @returns Status value at the given index
+     * @throws {IndexOutOfBoundsError} If index is out of bounds
+     *
+     * @example
+     * ```typescript
+     * const status = list.getStatus(42);
+     * if (status === StandardStatusValues.INVALID) {
+     *   console.log('Credential is revoked');
+     * }
+     * ```
+     */
+    getStatus(index: number): StatusValue;
+    /**
+     * Sets the status value at a specific index.
+     *
+     * Note: This modifies the status list in place. After modifying statuses,
+     * you'll need to recompress and re-sign the status list token.
+     *
+     * @param index - Index of the status entry (0-based)
+     * @param value - New status value
+     * @throws {IndexOutOfBoundsError} If index is out of bounds
+     * @throws {InvalidStatusValueError} If value exceeds the maximum for the bit size
+     *
+     * @example
+     * ```typescript
+     * // Revoke credential at index 42
+     * list.setStatus(42, StandardStatusValues.INVALID);
+     *
+     * // Suspend credential at index 100
+     * list.setStatus(100, StandardStatusValues.SUSPENDED);
+     * ```
+     */
+    setStatus(index: number, value: StatusValue): void;
+    /**
+     * Gets the number of bits used per status entry.
+     *
+     * @returns Number of bits per status (1, 2, 4, or 8)
+     */
+    getBitsPerStatus(): BitsPerStatus;
+    /**
+     * Gets the total number of status entries in this list.
+     *
+     * @returns Total capacity of the status list
+     */
+    getSize(): number;
+    /**
+     * Gets the raw byte array (for internal use).
+     *
+     * @returns The underlying byte array
+     */
+    getBytes(): Uint8Array;
+    /**
+     * Compresses the status list to base64url format (for JWT).
+     *
+     * @returns Base64URL-encoded compressed status list
+     *
+     * @example
+     * ```typescript
+     * const lst = list.compressToBase64URL();
+     * // Use in JWT payload: { status_list: { bits: 1, lst } }
+     * ```
+     */
+    compressToBase64URL(): string;
+    /**
+     * Compresses the status list to raw bytes (for CWT).
+     *
+     * @returns Compressed status list as bytes
+     *
+     * @example
+     * ```typescript
+     * const lst = list.compressToBytes();
+     * // Use in CWT payload: { 65533: { bits: 1, lst } }
+     * ```
+     */
+    compressToBytes(): Uint8Array;
+    /**
+     * Creates a StatusList from an array of status values.
+     *
+     * @param statuses - Array of status values
+     * @param bitsPerStatus - Number of bits per status entry (1, 2, 4, or 8)
+     * @returns New StatusList instance
+     * @throws {InvalidBitSizeError} If bitsPerStatus is not 1, 2, 4, or 8
+     * @throws {InvalidStatusValueError} If any status value exceeds the maximum for the bit size
+     *
+     * @example
+     * ```typescript
+     * // Create list with 1-bit statuses (valid/invalid)
+     * const statuses = new Array(10000).fill(0); // All valid
+     * statuses[42] = 1; // Revoke one credential
+     * const list = StatusList.fromArray(statuses, 1);
+     *
+     * // Create list with 2-bit statuses (valid/invalid/suspended/custom)
+     * const statuses2 = [0, 1, 2, 0, 1, 3];
+     * const list2 = StatusList.fromArray(statuses2, 2);
+     * ```
+     */
+    static fromArray(statuses: StatusValue[], bitsPerStatus: BitsPerStatus): StatusList;
+    /**
+     * Creates a StatusList by decompressing a base64url-encoded string (from JWT).
+     *
+     * @param compressed - Base64URL-encoded compressed status list
+     * @param bitsPerStatus - Number of bits per status entry
+     * @returns New StatusList instance
+     * @throws {CompressionError} If decompression fails
+     *
+     * @example
+     * ```typescript
+     * // From JWT payload
+     * const payload = parseJWT(token);
+     * const list = StatusList.decompressFromBase64URL(
+     *   payload.status_list.lst,
+     *   payload.status_list.bits
+     * );
+     * ```
+     */
+    static decompressFromBase64URL(compressed: string, bitsPerStatus: BitsPerStatus): StatusList;
+    /**
+     * Creates a StatusList by decompressing raw bytes (from CWT).
+     *
+     * @param compressed - Compressed status list as bytes
+     * @param bitsPerStatus - Number of bits per status entry
+     * @returns New StatusList instance
+     * @throws {CompressionError} If decompression fails
+     *
+     * @example
+     * ```typescript
+     * // From CWT payload
+     * const payload = parseCWT(token);
+     * const statusListData = payload[65533]; // status_list claim
+     * const list = StatusList.decompressFromBytes(
+     *   statusListData.lst,
+     *   statusListData.bits
+     * );
+     * ```
+     */
+    static decompressFromBytes(compressed: Uint8Array, bitsPerStatus: BitsPerStatus): StatusList;
+    /**
+     * Creates an empty StatusList with a specified capacity.
+     *
+     * All status entries are initialized to 0 (VALID).
+     *
+     * @param capacity - Number of status entries
+     * @param bitsPerStatus - Number of bits per status entry (1, 2, 4, or 8)
+     * @returns New StatusList instance
+     *
+     * @example
+     * ```typescript
+     * // Create empty list for 100,000 credentials
+     * const list = StatusList.create(100000, 1);
+     * ```
+     */
+    static create(capacity: number, bitsPerStatus: BitsPerStatus): StatusList;
+    /**
+     * Converts the status list to an array of status values (for debugging/testing).
+     *
+     * Warning: For large status lists, this can be memory-intensive.
+     *
+     * @returns Array of all status values
+     */
+    toArray(): StatusValue[];
+}
+
+/**
+ * Compresses data using ZLIB/DEFLATE compression with maximum compression level.
+ *
+ * Uses the DEFLATE algorithm with ZLIB wrapper (as required by the IETF specification).
+ * Maximum compression level (9) is used as recommended by the spec for optimal size reduction.
+ *
+ * @param data - Uncompressed data to compress
+ * @returns Compressed data with ZLIB header
+ * @throws {CompressionError} If compression fails
+ *
+ * @see https://www.ietf.org/archive/id/draft-ietf-oauth-status-list-14.html#section-4.1
+ */
+declare function compress(data: Uint8Array): Uint8Array;
+/**
+ * Decompresses ZLIB/DEFLATE compressed data.
+ *
+ * @param compressed - Compressed data with ZLIB header
+ * @returns Decompressed data
+ * @throws {CompressionError} If decompression fails
+ */
+declare function decompress(compressed: Uint8Array): Uint8Array;
+/**
+ * Compresses data and returns it as a base64url-encoded string (for JWT format).
+ *
+ * @param data - Uncompressed data
+ * @returns Base64URL-encoded compressed data
+ * @throws {CompressionError} If compression fails
+ */
+declare function compressToBase64URL(data: Uint8Array): string;
+/**
+ * Decompresses base64url-encoded data (from JWT format).
+ *
+ * @param base64url - Base64URL-encoded compressed data
+ * @returns Decompressed data
+ * @throws {CompressionError} If decoding or decompression fails
+ */
+declare function decompressFromBase64URL(base64url: string): Uint8Array;
+
+/**
+ * Packs an array of status values into a byte array using the specified bits per status.
+ *
+ * Bits are packed LSB-first within each byte (Least Significant Bit first).
+ * Example for 1-bit status with values [1,0,0,1,1,1,0,1]:
+ * - Byte 0: bits 0-7 → 1101 1001 = 0xD9 (LSB first)
+ *
+ * @param statuses - Array of status values
+ * @param bitsPerStatus - Number of bits per status (1, 2, 4, or 8)
+ * @returns Byte array containing packed status values
+ *
+ * @example
+ * ```typescript
+ * // 1-bit status: [1, 0, 0, 1, 1, 1, 0, 1]
+ * const bytes = packBits([1, 0, 0, 1, 1, 1, 0, 1], 1);
+ * // bytes[0] === 0xD9 (binary: 11011001, LSB first)
+ * ```
+ */
+declare function packBits(statuses: StatusValue[], bitsPerStatus: BitsPerStatus): Uint8Array;
+/**
+ * Unpacks a byte array into an array of status values.
+ *
+ * @param bytes - Byte array containing packed status values
+ * @param bitsPerStatus - Number of bits per status (1, 2, 4, or 8)
+ * @returns Array of status values
+ *
+ * @example
+ * ```typescript
+ * const bytes = new Uint8Array([0xD9]); // binary: 11011001
+ * const statuses = unpackBits(bytes, 1); // [1, 0, 0, 1, 1, 1, 0, 1]
+ * ```
+ */
+declare function unpackBits(bytes: Uint8Array, bitsPerStatus: BitsPerStatus): StatusValue[];
+/**
+ * Gets the status value at a specific index in the byte array.
+ *
+ * Implementation based on Python reference:
+ * ```python
+ * jump = self.bits * position          # Bit offset
+ * mask = (1 << self.bits) - 1          # n-bit mask
+ * status = (self.status_list[jump // 8] >> (jump % 8)) & mask
+ * ```
+ *
+ * @param bytes - Byte array containing packed status values
+ * @param index - Index of the status to retrieve
+ * @param bitsPerStatus - Number of bits per status
+ * @param mask - Optional pre-calculated mask (for performance)
+ * @returns Status value at the given index
+ * @throws {IndexOutOfBoundsError} If index is out of bounds
+ */
+declare function getBitValue(bytes: Uint8Array, index: number, bitsPerStatus: BitsPerStatus, mask?: number): StatusValue;
+/**
+ * Sets the status value at a specific index in the byte array.
+ *
+ * @param bytes - Byte array containing packed status values (modified in place)
+ * @param index - Index of the status to set
+ * @param value - New status value
+ * @param bitsPerStatus - Number of bits per status
+ * @throws {IndexOutOfBoundsError} If index is out of bounds
+ * @throws {InvalidStatusValueError} If value exceeds the maximum for the bit size
+ */
+declare function setBitValue(bytes: Uint8Array, index: number, value: StatusValue, bitsPerStatus: BitsPerStatus): void;
+/**
+ * Calculates the total number of status entries that can be stored in a byte array.
+ *
+ * @param byteLength - Length of the byte array
+ * @param bitsPerStatus - Number of bits per status
+ * @returns Total number of status entries
+ */
+declare function calculateCapacity(byteLength: number, bitsPerStatus: BitsPerStatus): number;
+
+/**
+ * Base error class for all status list errors.
+ */
+declare class StatusListError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when attempting to access a status at an index that is out of bounds.
+ */
+declare class IndexOutOfBoundsError extends StatusListError {
+    constructor(index: number, maxIndex: number);
+}
+/**
+ * Error thrown when an invalid bit size is provided.
+ * Valid bit sizes are: 1, 2, 4, or 8.
+ */
+declare class InvalidBitSizeError extends StatusListError {
+    constructor(bits: number);
+}
+/**
+ * Error thrown when a status value exceeds the maximum allowed for the given bit size.
+ */
+declare class InvalidStatusValueError extends StatusListError {
+    constructor(value: number, maxValue: number, bitsPerStatus: number);
+}
+/**
+ * Error thrown when a token has an invalid format or cannot be parsed.
+ */
+declare class InvalidTokenFormatError extends StatusListError {
+    constructor(message: string);
+}
+/**
+ * Error thrown when a status list token has expired.
+ */
+declare class StatusListExpiredError extends StatusListError {
+    constructor(exp: number, currentTime: number);
+}
+/**
+ * Error thrown when fetching a status list from a remote URI fails.
+ */
+declare class FetchError extends StatusListError {
+    constructor(message: string);
+}
+/**
+ * Error thrown when a status list URI is missing or invalid.
+ */
+declare class MissingStatusListUriError extends StatusListError {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when compression or decompression fails.
+ */
+declare class CompressionError extends StatusListError {
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Error thrown when validation of a status list token fails.
+ */
+declare class ValidationError extends StatusListError {
+    readonly errors: string[];
+    constructor(errors: string[]);
+}
+
+/**
+ * JWT header for a Status List Token.
+ *
+ * @see https://www.ietf.org/archive/id/draft-ietf-oauth-status-list-14.html#section-5.1
+ */
+interface StatusListJWTHeader {
+    /**
+     * REQUIRED: Type header parameter.
+     * Must be "statuslist+jwt" for Status List Tokens.
+     */
+    typ: 'statuslist+jwt';
+    /**
+     * REQUIRED: Algorithm used for signing.
+     * Common values: "ES256", "ES384", "ES512", "RS256", etc.
+     */
+    alg: string;
+    /**
+     * OPTIONAL: Key ID.
+     * Indicates which key was used to sign the JWT.
+     */
+    kid?: string;
+    /**
+     * Allow additional header parameters.
+     */
+    [key: string]: unknown;
+}
+/**
+ * Status List structure within the JWT payload.
+ */
+interface StatusListClaim {
+    /**
+     * REQUIRED: Number of bits per status entry.
+     * Must be 1, 2, 4, or 8.
+     */
+    bits: BitsPerStatus;
+    /**
+     * REQUIRED: Base64URL-encoded compressed status list.
+     * The status list is compressed using DEFLATE/ZLIB before encoding.
+     */
+    lst: string;
+    /**
+     * OPTIONAL: URI for status list aggregation.
+     * Points to a resource that aggregates multiple status lists.
+     */
+    aggregation_uri?: string;
+}
+/**
+ * JWT payload for a Status List Token.
+ *
+ * @see https://www.ietf.org/archive/id/draft-ietf-oauth-status-list-14.html#section-5.1.1
+ */
+interface StatusListJWTPayload {
+    /**
+     * REQUIRED: Issuer of the status list token.
+     * Identifies the principal that issued the JWT.
+     */
+    iss: string;
+    /**
+     * REQUIRED: Subject of the status list token.
+     * URI that identifies this specific status list.
+     * Must match the "uri" field in referenced tokens.
+     */
+    sub: string;
+    /**
+     * REQUIRED: Issued at time.
+     * Timestamp (seconds since epoch) when the status list was created.
+     */
+    iat: number;
+    /**
+     * RECOMMENDED: Expiration time.
+     * Timestamp (seconds since epoch) after which the status list is no longer valid.
+     */
+    exp?: number;
+    /**
+     * RECOMMENDED: Time to live (in seconds).
+     * Indicates how long the status list should be cached.
+     */
+    ttl?: number;
+    /**
+     * REQUIRED: The status list.
+     */
+    status_list: StatusListClaim;
+    /**
+     * Allow additional claims.
+     */
+    [key: string]: unknown;
+}
+/**
+ * Status list reference within a credential/token.
+ *
+ * This appears in the "status" claim of a referenced token (credential).
+ *
+ * @see https://www.ietf.org/archive/id/draft-ietf-oauth-status-list-14.html#section-6
+ */
+interface StatusListReference {
+    /**
+     * REQUIRED: Index of this credential in the status list.
+     * Non-negative integer that identifies the position.
+     */
+    idx: number;
+    /**
+     * REQUIRED: URI of the Status List Token.
+     * Must match the "sub" claim of the Status List Token.
+     */
+    uri: string;
+}
+/**
+ * Status claim structure in a referenced token.
+ */
+interface TokenStatusClaim {
+    /**
+     * Status list reference.
+     */
+    status_list: StatusListReference;
+    /**
+     * Allow additional status mechanisms.
+     */
+    [key: string]: unknown;
+}
+/**
+ * Options for creating a JWT Status List Token payload.
+ */
+interface CreateJWTStatusListOptions {
+    /**
+     * REQUIRED: Issuer identifier.
+     */
+    iss: string;
+    /**
+     * REQUIRED: Status list identifier (URI).
+     */
+    sub: string;
+    /**
+     * REQUIRED: Compressed status list (base64url-encoded).
+     */
+    lst: string;
+    /**
+     * REQUIRED: Number of bits per status.
+     */
+    bits: BitsPerStatus;
+    /**
+     * OPTIONAL: Issued at timestamp.
+     * Defaults to current time if not provided.
+     */
+    iat?: number;
+    /**
+     * OPTIONAL: Expiration timestamp.
+     */
+    exp?: number;
+    /**
+     * OPTIONAL: Time to live in seconds.
+     */
+    ttl?: number;
+    /**
+     * OPTIONAL: Aggregation URI.
+     */
+    aggregation_uri?: string;
+    /**
+     * OPTIONAL: Additional claims to include in the payload.
+     */
+    additionalClaims?: Record<string, unknown>;
+}
+/**
+ * Options for signing a Status List JWT.
+ */
+interface SignJWTOptions {
+    /**
+     * OPTIONAL: Algorithm to use for signing.
+     * Defaults to the algorithm specified in the key.
+     */
+    alg?: string;
+    /**
+     * OPTIONAL: Key ID to include in the header.
+     */
+    kid?: string;
+    /**
+     * OPTIONAL: Additional header parameters.
+     */
+    additionalHeaders?: Record<string, unknown>;
+}
+/**
+ * Result of parsing a JWT Status List Token.
+ */
+interface ParsedJWTStatusList {
+    /**
+     * JWT header.
+     */
+    header: StatusListJWTHeader;
+    /**
+     * JWT payload.
+     */
+    payload: StatusListJWTPayload;
+    /**
+     * Raw JWT string.
+     */
+    jwt: string;
+}
+
+/**
+ * Creates a JWT Status List payload (without signing).
+ *
+ * This function creates the header and payload objects for a Status List JWT.
+ * The actual signing should be done using the `jose` library or similar.
+ *
+ * @param options - Configuration for creating the status list payload
+ * @returns Object containing header and payload ready for signing
+ *
+ * @example
+ * ```typescript
+ * import { StatusList } from '@vess-id/status-list';
+ * import { createJWTStatusListPayload } from '@vess-id/status-list/formats/jwt';
+ * import { SignJWT } from 'jose';
+ *
+ * const list = StatusList.create(1000, 1);
+ * const lst = list.compressToBase64URL();
+ *
+ * const { header, payload } = createJWTStatusListPayload({
+ *   iss: 'https://issuer.example.com',
+ *   sub: 'https://issuer.example.com/status/1',
+ *   lst,
+ *   bits: 1,
+ *   iat: Math.floor(Date.now() / 1000),
+ *   exp: Math.floor(Date.now() / 1000) + 86400,
+ *   ttl: 3600,
+ * });
+ *
+ * // Sign with jose
+ * const jwt = await new SignJWT(payload)
+ *   .setProtectedHeader(header)
+ *   .sign(privateKey);
+ * ```
+ */
+declare function createJWTStatusListPayload(options: CreateJWTStatusListOptions): {
+    header: StatusListJWTHeader;
+    payload: StatusListJWTPayload;
+};
+/**
+ * Parses a JWT Status List Token (without verifying the signature).
+ *
+ * This function decodes and validates the structure of a Status List JWT.
+ * Signature verification should be done separately using `jose` or similar.
+ *
+ * @param jwt - JWT string to parse
+ * @returns Parsed header, payload, and decompressed status list
+ * @throws {InvalidTokenFormatError} If the JWT format is invalid
+ *
+ * @example
+ * ```typescript
+ * import { parseJWTStatusList } from '@vess-id/status-list/formats/jwt';
+ * import { jwtVerify } from 'jose';
+ *
+ * // First verify the signature
+ * const { payload } = await jwtVerify(jwt, publicKey);
+ *
+ * // Then parse and decompress
+ * const { header, payload: parsed, statusList } = parseJWTStatusList(jwt);
+ *
+ * // Check credential status
+ * const status = statusList.getStatus(42);
+ * ```
+ */
+declare function parseJWTStatusList(jwt: string): ParsedJWTStatusList & {
+    statusList: StatusList;
+};
+/**
+ * Extracts the status list reference from a credential JWT.
+ *
+ * @param credentialJWT - Credential JWT containing a status claim
+ * @returns Status list reference (idx and uri)
+ * @throws {InvalidTokenFormatError} If the status claim is missing or invalid
+ *
+ * @example
+ * ```typescript
+ * import { extractStatusListReference } from '@vess-id/status-list/formats/jwt';
+ *
+ * const credential = 'eyJ...'; // Credential JWT
+ * const { idx, uri } = extractStatusListReference(credential);
+ *
+ * // Fetch status list from uri and check status at idx
+ * ```
+ */
+declare function extractStatusListReference(credentialJWT: string): StatusListReference;
+
+/**
+ * Signs a Status List JWT using the provided private key.
+ *
+ * This function uses the `jose` library to create a signed JWT from a Status List payload.
+ *
+ * @param payload - Status List JWT payload
+ * @param privateKey - Private key for signing (KeyLike from jose)
+ * @param options - Optional signing options (algorithm, kid, additional headers)
+ * @returns Signed JWT string
+ *
+ * @example
+ * ```typescript
+ * import { signStatusListJWT } from '@vess-id/status-list/formats/jwt';
+ * import { StatusList } from '@vess-id/status-list';
+ * import { importPKCS8 } from 'jose';
+ *
+ * // Create status list
+ * const list = StatusList.create(1000, 1);
+ * const lst = list.compressToBase64URL();
+ *
+ * // Create payload
+ * const payload = {
+ *   iss: 'https://issuer.example.com',
+ *   sub: 'https://issuer.example.com/status/1',
+ *   iat: Math.floor(Date.now() / 1000),
+ *   exp: Math.floor(Date.now() / 1000) + 86400,
+ *   ttl: 3600,
+ *   status_list: { bits: 1, lst },
+ * };
+ *
+ * // Import private key
+ * const privateKey = await importPKCS8(pemPrivateKey, 'ES256');
+ *
+ * // Sign
+ * const jwt = await signStatusListJWT(payload, privateKey, {
+ *   alg: 'ES256',
+ *   kid: 'key-123',
+ * });
+ * ```
+ */
+declare function signStatusListJWT(payload: StatusListJWTPayload, privateKey: KeyLike, options?: SignJWTOptions): Promise<string>;
+
+/**
+ * Options for verifying a Status List JWT.
+ */
+interface VerifyJWTOptions {
+    /**
+     * Expected issuer (iss claim).
+     * If provided, verification will fail if the token's iss doesn't match.
+     */
+    issuer?: string;
+    /**
+     * Expected subject (sub claim).
+     * If provided, verification will fail if the token's sub doesn't match.
+     */
+    subject?: string;
+    /**
+     * Current time for validation (in seconds since epoch).
+     * Defaults to current time if not provided.
+     */
+    currentTime?: number;
+    /**
+     * Clock tolerance in seconds.
+     * Allows for small clock differences between issuer and verifier.
+     * Default: 0
+     */
+    clockTolerance?: number;
+}
+/**
+ * Result of verifying a Status List JWT.
+ */
+interface VerifiedStatusListJWT {
+    /**
+     * Verified JWT header.
+     */
+    header: StatusListJWTHeader;
+    /**
+     * Verified JWT payload.
+     */
+    payload: StatusListJWTPayload;
+}
+/**
+ * Verifies the signature and validates a Status List JWT.
+ *
+ * This function:
+ * 1. Verifies the JWT signature using the provided public key
+ * 2. Validates the JWT structure and claims
+ * 3. Checks expiration (if exp is present)
+ * 4. Optionally validates issuer and subject
+ *
+ * @param jwt - JWT string to verify
+ * @param publicKey - Public key for verification (KeyLike from jose)
+ * @param options - Optional verification options
+ * @returns Verified header and payload
+ * @throws {InvalidTokenFormatError} If verification fails
+ *
+ * @example
+ * ```typescript
+ * import { verifyStatusListJWT } from '@vess-id/status-list/formats/jwt';
+ * import { importSPKI } from 'jose';
+ *
+ * // Import public key
+ * const publicKey = await importSPKI(pemPublicKey, 'ES256');
+ *
+ * try {
+ *   const { header, payload } = await verifyStatusListJWT(jwt, publicKey, {
+ *     issuer: 'https://issuer.example.com',
+ *     subject: 'https://issuer.example.com/status/1',
+ *   });
+ *
+ *   console.log('JWT is valid');
+ *   console.log('Issued at:', new Date(payload.iat * 1000));
+ *   console.log('Expires at:', payload.exp ? new Date(payload.exp * 1000) : 'Never');
+ * } catch (error) {
+ *   console.error('Verification failed:', error.message);
+ * }
+ * ```
+ */
+declare function verifyStatusListJWT(jwt: string, publicKey: KeyLike, options?: VerifyJWTOptions): Promise<VerifiedStatusListJWT>;
+/**
+ * Verifies only the signature of a Status List JWT without validating claims.
+ *
+ * Useful when you want to verify the signature but handle claim validation separately.
+ *
+ * @param jwt - JWT string to verify
+ * @param publicKey - Public key for verification
+ * @returns Verified header and payload
+ * @throws {InvalidTokenFormatError} If signature verification fails
+ */
+declare function verifySignatureOnly(jwt: string, publicKey: KeyLike): Promise<VerifiedStatusListJWT>;
+
+/**
+ * CBOR Web Token (CWT) claim keys as defined in RFC 8392.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc8392.html#section-3.1
+ * @see https://www.ietf.org/archive/id/draft-ietf-oauth-status-list-14.html#section-5.2
+ */
+declare const CWT_CLAIMS: {
+    /** Issuer (iss) - Claim key 1 */
+    readonly ISS: 1;
+    /** Subject (sub) - Claim key 2 */
+    readonly SUB: 2;
+    /** Expiration Time (exp) - Claim key 4 */
+    readonly EXP: 4;
+    /** Issued At (iat) - Claim key 6 */
+    readonly IAT: 6;
+    /** Time to Live (ttl) - Claim key 65534 (custom) */
+    readonly TTL: 65534;
+    /** Status List - Claim key 65533 (custom) */
+    readonly STATUS_LIST: 65533;
+};
+/**
+ * COSE header parameters.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc8152.html#section-3.1
+ */
+declare const COSE_HEADERS: {
+    /** Algorithm - Header parameter 1 */
+    readonly ALG: 1;
+    /** Content Type - Header parameter 16 */
+    readonly CONTENT_TYPE: 16;
+    /** Key ID - Header parameter 4 */
+    readonly KID: 4;
+};
+/**
+ * COSE algorithms.
+ *
+ * @see https://www.iana.org/assignments/cose/cose.xhtml#algorithms
+ */
+declare const COSE_ALGORITHMS: {
+    /** ES256 - ECDSA with SHA-256 */
+    readonly ES256: -7;
+    /** ES384 - ECDSA with SHA-384 */
+    readonly ES384: -35;
+    /** ES512 - ECDSA with SHA-512 */
+    readonly ES512: -36;
+    /** EdDSA */
+    readonly EdDSA: -8;
+};
+/**
+ * Status List structure in CBOR format.
+ */
+interface StatusListCWTClaim {
+    /**
+     * REQUIRED: Number of bits per status entry.
+     * Must be 1, 2, 4, or 8.
+     */
+    bits: BitsPerStatus;
+    /**
+     * REQUIRED: Compressed status list as raw bytes.
+     * Unlike JWT, this is NOT base64url-encoded.
+     */
+    lst: Uint8Array;
+    /**
+     * OPTIONAL: URI for status list aggregation.
+     */
+    aggregation_uri?: string;
+}
+/**
+ * CWT payload for a Status List Token.
+ *
+ * Uses numeric claim keys as defined in RFC 8392 and the IETF spec.
+ *
+ * @see https://www.ietf.org/archive/id/draft-ietf-oauth-status-list-14.html#section-5.2
+ */
+interface StatusListCWTPayload {
+    /**
+     * OPTIONAL: Issuer (claim key 1).
+     */
+    [CWT_CLAIMS.ISS]?: string;
+    /**
+     * REQUIRED: Subject (claim key 2).
+     * URI that identifies this specific status list.
+     */
+    [CWT_CLAIMS.SUB]?: string;
+    /**
+     * OPTIONAL: Expiration time (claim key 4).
+     * Timestamp (seconds since epoch).
+     */
+    [CWT_CLAIMS.EXP]?: number;
+    /**
+     * REQUIRED: Issued at time (claim key 6).
+     * Timestamp (seconds since epoch).
+     */
+    [CWT_CLAIMS.IAT]?: number;
+    /**
+     * OPTIONAL: Time to live in seconds (claim key 65534).
+     */
+    [CWT_CLAIMS.TTL]?: number;
+    /**
+     * REQUIRED: The status list (claim key 65533).
+     */
+    [CWT_CLAIMS.STATUS_LIST]: StatusListCWTClaim;
+    /**
+     * Allow additional claims.
+     */
+    [key: number]: unknown;
+}
+/**
+ * COSE key in JWK-like format for elliptic curve keys.
+ */
+interface EC2Key {
+    /**
+     * Key type: EC2 for Elliptic Curve keys with x and y coordinates.
+     */
+    kty: 'EC2';
+    /**
+     * Curve: P-256, P-384, or P-521.
+     */
+    crv: 'P-256' | 'P-384' | 'P-521';
+    /**
+     * X coordinate (public key component).
+     */
+    x: Uint8Array;
+    /**
+     * Y coordinate (public key component).
+     */
+    y: Uint8Array;
+    /**
+     * Private key (d parameter).
+     * Only present for private keys.
+     */
+    d?: Uint8Array;
+    /**
+     * Key ID.
+     */
+    kid?: Uint8Array;
+}
+/**
+ * COSE key for OKP (Octet Key Pair) keys like Ed25519.
+ */
+interface OKPKey {
+    /**
+     * Key type: OKP for Octet Key Pair.
+     */
+    kty: 'OKP';
+    /**
+     * Curve: Ed25519 or Ed448.
+     */
+    crv: 'Ed25519' | 'Ed448';
+    /**
+     * Public key.
+     */
+    x: Uint8Array;
+    /**
+     * Private key.
+     * Only present for private keys.
+     */
+    d?: Uint8Array;
+    /**
+     * Key ID.
+     */
+    kid?: Uint8Array;
+}
+/**
+ * COSE key (either EC2 or OKP).
+ */
+type COSEKey = EC2Key | OKPKey;
+/**
+ * Options for creating a CWT Status List.
+ */
+interface CreateCWTStatusListOptions {
+    /**
+     * OPTIONAL: Issuer identifier.
+     */
+    iss?: string;
+    /**
+     * OPTIONAL: Status list identifier (URI).
+     */
+    sub?: string;
+    /**
+     * REQUIRED: Compressed status list (raw bytes).
+     */
+    lst: Uint8Array;
+    /**
+     * REQUIRED: Number of bits per status.
+     */
+    bits: BitsPerStatus;
+    /**
+     * OPTIONAL: Issued at timestamp.
+     * Defaults to current time if not provided.
+     */
+    iat?: number;
+    /**
+     * OPTIONAL: Expiration timestamp.
+     */
+    exp?: number;
+    /**
+     * OPTIONAL: Time to live in seconds.
+     */
+    ttl?: number;
+    /**
+     * OPTIONAL: Aggregation URI.
+     */
+    aggregation_uri?: string;
+    /**
+     * OPTIONAL: Additional claims (with numeric keys).
+     */
+    additionalClaims?: Record<number, unknown>;
+}
+/**
+ * Options for signing a CWT with COSE Sign1.
+ */
+interface SignCWTOptions {
+    /**
+     * OPTIONAL: Algorithm to use for signing.
+     * Defaults to ES256 (-7).
+     */
+    alg?: number;
+    /**
+     * OPTIONAL: Key ID to include in the protected header.
+     */
+    kid?: Uint8Array;
+    /**
+     * OPTIONAL: Additional protected header parameters.
+     */
+    additionalHeaders?: Map<number, unknown>;
+}
+/**
+ * Result of parsing a CWT Status List Token.
+ */
+interface ParsedCWTStatusList {
+    /**
+     * Protected header.
+     */
+    protectedHeader: Map<number, unknown>;
+    /**
+     * Unprotected header.
+     */
+    unprotectedHeader: Map<number, unknown>;
+    /**
+     * CWT payload.
+     */
+    payload: StatusListCWTPayload;
+    /**
+     * Raw CWT bytes.
+     */
+    cwt: Uint8Array;
+}
+/**
+ * Status list reference in CBOR format (for mdoc).
+ */
+interface StatusListReferenceCBOR {
+    /**
+     * Index of this credential in the status list.
+     */
+    idx: number;
+    /**
+     * URI of the Status List Token.
+     */
+    uri: string;
+}
+
+/**
+ * Creates a CWT Status List payload (CBOR map).
+ *
+ * This function creates the payload for a Status List CWT using numeric claim keys.
+ * The payload can be signed separately using COSE Sign1.
+ *
+ * @param options - Configuration for creating the status list payload
+ * @returns CBOR-encodable payload object
+ *
+ * @example
+ * ```typescript
+ * import { StatusList } from '@vess-id/status-list';
+ * import { createCWTStatusListPayload } from '@vess-id/status-list/formats/cwt';
+ *
+ * const list = StatusList.create(1000, 1);
+ * const lst = list.compressToBytes();
+ *
+ * const payload = createCWTStatusListPayload({
+ *   sub: 'https://issuer.example.com/status/1',
+ *   lst,
+ *   bits: 1,
+ *   iat: Math.floor(Date.now() / 1000),
+ *   exp: Math.floor(Date.now() / 1000) + 86400,
+ *   ttl: 3600,
+ * });
+ * ```
+ */
+declare function createCWTStatusListPayload(options: CreateCWTStatusListOptions): StatusListCWTPayload;
+/**
+ * Encodes a CWT Status List payload to CBOR format (without signing).
+ *
+ * @param payload - CWT payload
+ * @returns CBOR-encoded payload
+ *
+ * @example
+ * ```typescript
+ * const payload = createCWTStatusListPayload({ ... });
+ * const cbor = encodeCWTPayload(payload);
+ * ```
+ */
+declare function encodeCWTPayload(payload: StatusListCWTPayload): Uint8Array;
+/**
+ * Parses a CWT Status List (CBOR-encoded, unsigned).
+ *
+ * This function decodes and validates the structure of an unsigned Status List CWT.
+ * For signed CWTs (COSE Sign1), use `parseCWTStatusListSigned()` instead.
+ *
+ * @param cwtBytes - CBOR-encoded CWT bytes
+ * @returns Parsed payload and decompressed status list
+ * @throws {InvalidTokenFormatError} If the CWT format is invalid
+ *
+ * @example
+ * ```typescript
+ * import { parseCWTStatusList } from '@vess-id/status-list/formats/cwt';
+ *
+ * const { payload, statusList } = parseCWTStatusList(cwtBytes);
+ *
+ * // Check credential status
+ * const status = statusList.getStatus(42);
+ * ```
+ */
+declare function parseCWTStatusList(cwtBytes: Uint8Array): ParsedCWTStatusList & {
+    statusList: StatusList;
+};
+/**
+ * Parses a signed CWT Status List (COSE Sign1).
+ *
+ * This function verifies the COSE Sign1 signature and extracts the payload.
+ *
+ * @param cwtBytes - CBOR-encoded COSE Sign1 structure
+ * @param publicKey - Public key for verification
+ * @returns Parsed payload and decompressed status list
+ * @throws {InvalidTokenFormatError} If verification fails
+ *
+ * @example
+ * ```typescript
+ * const publicKey = { kty: 'EC2', crv: 'P-256', x: ..., y: ... };
+ * const { payload, statusList } = parseCWTStatusListSigned(cwtBytes, publicKey);
+ * ```
+ */
+declare function parseCWTStatusListSigned(cwtBytes: Uint8Array, publicKey: COSEKey): ParsedCWTStatusList & {
+    statusList: StatusList;
+};
+/**
+ * Signs a CWT Status List using COSE Sign1.
+ *
+ * Note: This is a basic implementation. For production use with real cryptographic
+ * keys, consider using a dedicated COSE library like `@transmute/cose`.
+ *
+ * @param payload - CWT payload
+ * @param privateKey - COSE private key
+ * @param options - Signing options
+ * @returns CBOR-encoded COSE Sign1 structure
+ *
+ * @example
+ * ```typescript
+ * const payload = createCWTStatusListPayload({ ... });
+ * const privateKey = { kty: 'EC2', crv: 'P-256', x: ..., y: ..., d: ... };
+ *
+ * const cwt = signCWTStatusList(payload, privateKey, {
+ *   alg: -7, // ES256
+ *   kid: new TextEncoder().encode('key-123'),
+ * });
+ * ```
+ */
+declare function signCWTStatusList(payload: StatusListCWTPayload, privateKey: COSEKey, options?: SignCWTOptions): Uint8Array;
+/**
+ * Extracts the status list reference from an mdoc or CBOR-encoded credential.
+ *
+ * @param credentialCBOR - CBOR-encoded credential containing a status claim
+ * @returns Status list reference (idx and uri)
+ * @throws {InvalidTokenFormatError} If the status claim is missing or invalid
+ */
+declare function extractStatusListReferenceCBOR(credentialCBOR: Uint8Array): StatusListReferenceCBOR;
+
+/**
+ * Creates a COSE Sign1 signature structure.
+ *
+ * COSE_Sign1 = [
+ *   protected: bstr,        // Serialized protected header
+ *   unprotected: {},        // Unprotected header map
+ *   payload: bstr,          // The payload
+ *   signature: bstr         // The signature
+ * ]
+ *
+ * @param payload - Payload to sign (CBOR-encoded)
+ * @param protectedHeader - Protected header parameters
+ * @param privateKey - COSE private key
+ * @returns CBOR-encoded COSE Sign1 structure with tag
+ */
+declare function signCOSE(payload: Uint8Array, protectedHeader: Map<number, unknown>, privateKey: COSEKey): Uint8Array;
+/**
+ * Verifies a COSE Sign1 signature.
+ *
+ * @param coseSign1 - CBOR-encoded COSE Sign1 structure
+ * @param publicKey - COSE public key
+ * @returns Verified payload
+ * @throws {InvalidTokenFormatError} If verification fails
+ */
+declare function verifyCOSE(coseSign1: Uint8Array, publicKey: COSEKey): Uint8Array;
+
+/**
+ * Options for fetching a Status List Token.
+ */
+interface FetchOptions {
+    /**
+     * Request timeout in milliseconds.
+     * Default: 10000 (10 seconds)
+     */
+    timeout?: number;
+    /**
+     * Additional HTTP headers to include in the request.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Maximum number of redirects to follow.
+     * Per IETF spec Section 11.4, limit redirects to prevent DoS attacks.
+     * Default: 3
+     */
+    maxRedirects?: number;
+    /**
+     * Custom fetch implementation.
+     * Useful for testing or custom environments.
+     * Default: global fetch
+     */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Fetches a Status List Token from a URI via HTTP GET.
+ *
+ * Automatically detects JWT vs CWT format based on Content-Type header.
+ * Follows IETF spec security recommendations:
+ * - Enforces timeout to prevent DoS
+ * - Limits redirects (default: 3)
+ * - Validates Content-Type header
+ *
+ * @param uri - URI of the Status List Token
+ * @param options - Fetch options
+ * @returns JWT as string or CWT as Uint8Array
+ * @throws {MissingStatusListUriError} If URI is missing or invalid
+ * @throws {FetchError} If HTTP request fails
+ *
+ * @example
+ * ```typescript
+ * // Fetch JWT Status List
+ * const jwt = await fetchStatusListToken('https://issuer.example.com/status/1');
+ * console.log(typeof jwt); // 'string'
+ *
+ * // Fetch CWT Status List
+ * const cwt = await fetchStatusListToken('https://issuer.example.com/status/2');
+ * console.log(cwt instanceof Uint8Array); // true
+ * ```
+ */
+declare function fetchStatusListToken(uri: string, options?: FetchOptions): Promise<string | Uint8Array>;
+/**
+ * Validates a status list URI.
+ *
+ * Checks:
+ * - URI is not empty
+ * - URI is a valid URL
+ * - Protocol is HTTP or HTTPS
+ *
+ * @param uri - URI to validate
+ * @returns True if valid
+ *
+ * @example
+ * ```typescript
+ * if (!isValidStatusListUri(uri)) {
+ *   throw new Error('Invalid status list URI');
+ * }
+ * ```
+ */
+declare function isValidStatusListUri(uri: string): boolean;
+
+/**
+ * High-level helper for working with Status List Tokens.
+ *
+ * Provides a unified interface for both JWT and CWT formats.
+ * Similar to the Python implementation's StatusListTokenHelper.
+ *
+ * @example
+ * ```typescript
+ * // From a credential's status reference
+ * const reference = { idx: 42, uri: 'https://issuer.example.com/status/1' };
+ * const helper = await StatusListTokenHelper.fromStatusReference(reference);
+ *
+ * // Check credential status
+ * if (helper.isExpired()) {
+ *   throw new Error('Status list expired');
+ * }
+ *
+ * const status = helper.getStatus(reference.idx);
+ * if (status === StandardStatusValues.INVALID) {
+ *   console.log('Credential is revoked');
+ * }
+ * ```
+ */
+declare class StatusListTokenHelper {
+    private readonly header;
+    private readonly payload;
+    private readonly statusList;
+    private readonly format;
+    private constructor();
+    /**
+     * Creates a helper from a Status List Token (JWT or CWT).
+     *
+     * Automatically detects the format:
+     * - JWT: starts with "eyJ" (base64url-encoded header)
+     * - CWT: CBOR binary format
+     *
+     * @param token - JWT string or CWT Uint8Array
+     * @returns StatusListTokenHelper instance
+     * @throws {InvalidTokenFormatError} If token format is invalid
+     *
+     * @example
+     * ```typescript
+     * // From JWT
+     * const helper = StatusListTokenHelper.fromToken(jwtString);
+     *
+     * // From CWT
+     * const helper = StatusListTokenHelper.fromToken(cwtBytes);
+     * ```
+     */
+    static fromToken(token: string | Uint8Array): StatusListTokenHelper;
+    /**
+     * Creates a helper by fetching a Status List Token from a URI.
+     *
+     * Fetches the token via HTTP GET and automatically detects the format.
+     *
+     * @param reference - Status reference containing idx and uri
+     * @param options - Fetch options
+     * @returns StatusListTokenHelper instance
+     * @throws {FetchError} If HTTP request fails
+     * @throws {InvalidTokenFormatError} If token format is invalid
+     *
+     * @example
+     * ```typescript
+     * const reference = {
+     *   idx: 42,
+     *   uri: 'https://issuer.example.com/status/1'
+     * };
+     *
+     * const helper = await StatusListTokenHelper.fromStatusReference(reference);
+     * const status = helper.getStatus(reference.idx);
+     * ```
+     */
+    static fromStatusReference(reference: StatusListReference, options?: FetchOptions): Promise<StatusListTokenHelper>;
+    /**
+     * Gets the status value at a specific index.
+     *
+     * @param index - Index in the status list
+     * @returns Status value (0-255 depending on bits per status)
+     * @throws {IndexOutOfBoundsError} If index is out of bounds
+     *
+     * @example
+     * ```typescript
+     * const status = helper.getStatus(42);
+     * if (status === StandardStatusValues.INVALID) {
+     *   console.log('Credential 42 is revoked');
+     * }
+     * ```
+     */
+    getStatus(index: number): StatusValue;
+    /**
+     * Checks if the status list token is expired.
+     *
+     * A token is expired if:
+     * - exp is set and is in the past, OR
+     * - ttl is set and iat + ttl is in the past
+     *
+     * @param currentTime - Current time (seconds since epoch). Defaults to now.
+     * @returns True if expired
+     *
+     * @example
+     * ```typescript
+     * if (helper.isExpired()) {
+     *   throw new Error('Status list expired - fetch a new one');
+     * }
+     * ```
+     */
+    isExpired(currentTime?: number): boolean;
+    /**
+     * Gets the issuer identifier (iss claim).
+     *
+     * @returns Issuer string or undefined if not set
+     */
+    get iss(): string | undefined;
+    /**
+     * Gets the subject identifier (sub claim).
+     *
+     * @returns Subject string or undefined if not set
+     */
+    get sub(): string | undefined;
+    /**
+     * Gets the issued at time (iat claim).
+     *
+     * @returns Timestamp in seconds since epoch, or undefined if not set
+     */
+    get iat(): number | undefined;
+    /**
+     * Gets the expiration time (exp claim).
+     *
+     * @returns Timestamp in seconds since epoch, or undefined if not set
+     */
+    get exp(): number | undefined;
+    /**
+     * Gets the time to live (ttl claim).
+     *
+     * @returns TTL in seconds, or undefined if not set
+     */
+    get ttl(): number | undefined;
+    /**
+     * Gets the number of bits per status entry.
+     *
+     * @returns Bits per status (1, 2, 4, or 8)
+     */
+    get bits(): BitsPerStatus;
+    /**
+     * Gets the aggregation URI if set.
+     *
+     * @returns Aggregation URI or undefined if not set
+     */
+    get aggregationUri(): string | undefined;
+    /**
+     * Gets the format of the token.
+     *
+     * @returns 'jwt' or 'cwt'
+     */
+    get tokenFormat(): 'jwt' | 'cwt';
+    /**
+     * Gets the size of the status list.
+     *
+     * @returns Number of status entries
+     */
+    get size(): number;
+    /**
+     * Gets the raw header.
+     *
+     * @returns Header as object (JWT) or Map (CWT)
+     */
+    getHeader(): Record<string, unknown> | Map<number, unknown>;
+    /**
+     * Gets the raw payload.
+     *
+     * @returns Payload object
+     */
+    getPayload(): StatusListJWTPayload | StatusListCWTPayload;
+    /**
+     * Gets the underlying StatusList instance.
+     *
+     * @returns StatusList instance
+     */
+    getStatusList(): StatusList;
+}
+
+/**
+ * Validation result with detailed error messages.
+ */
+interface ValidationResult {
+    /**
+     * Whether the validation passed.
+     */
+    valid: boolean;
+    /**
+     * List of validation error messages.
+     * Empty if valid is true.
+     */
+    errors: string[];
+}
+/**
+ * Validates a JWT Status List payload.
+ *
+ * Checks:
+ * - Required claims (iss, sub, iat, status_list)
+ * - status_list structure (bits, lst)
+ * - bits value (must be 1, 2, 4, or 8)
+ * - lst format (must be a non-empty string)
+ * - Optional claims format (exp, ttl)
+ *
+ * @param payload - JWT payload to validate
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * const result = validateJWTPayload(payload);
+ * if (!result.valid) {
+ *   console.error('Validation errors:', result.errors);
+ * }
+ * ```
+ */
+declare function validateJWTPayload(payload: StatusListJWTPayload): ValidationResult;
+/**
+ * Validates a CWT Status List payload.
+ *
+ * Checks:
+ * - Required claims (status_list with numeric key 65533)
+ * - status_list structure (bits, lst)
+ * - bits value (must be 1, 2, 4, or 8)
+ * - lst format (must be a Uint8Array)
+ * - Optional claims format (iss, sub, iat, exp, ttl)
+ *
+ * @param payload - CWT payload to validate
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * const result = validateCWTPayload(payload);
+ * if (!result.valid) {
+ *   console.error('Validation errors:', result.errors);
+ * }
+ * ```
+ */
+declare function validateCWTPayload(payload: StatusListCWTPayload): ValidationResult;
+/**
+ * Validates expiration and freshness of a status list token.
+ *
+ * Checks:
+ * - If exp is set, validates it's not in the past
+ * - If ttl is set, validates freshness based on iat + ttl
+ * - Ensures iat is not in the future
+ *
+ * @param exp - Expiration time (seconds since epoch)
+ * @param iat - Issued at time (seconds since epoch)
+ * @param ttl - Time to live in seconds
+ * @param currentTime - Current time (seconds since epoch). Defaults to now.
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * const result = validateExpiry(payload.exp, payload.iat, payload.ttl);
+ * if (!result.valid) {
+ *   console.error('Token expired or not yet valid');
+ * }
+ * ```
+ */
+declare function validateExpiry(exp?: number, iat?: number, ttl?: number, currentTime?: number): ValidationResult;
+/**
+ * Validates TTL value is within recommended bounds.
+ *
+ * Per IETF spec Section 11.5, excessively large TTL values can be used
+ * for DoS attacks by causing verifiers to cache stale status lists.
+ *
+ * Recommended bounds:
+ * - Minimum: 60 seconds (1 minute)
+ * - Maximum: 31536000 seconds (1 year)
+ *
+ * @param ttl - Time to live in seconds
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * const result = validateTTLBounds(payload.ttl);
+ * if (!result.valid) {
+ *   console.warn('TTL outside recommended bounds:', result.errors);
+ * }
+ * ```
+ */
+declare function validateTTLBounds(ttl?: number): ValidationResult;
+/**
+ * Checks if a status list token is expired.
+ *
+ * A token is considered expired if:
+ * - exp is set and is in the past, OR
+ * - ttl is set and iat + ttl is in the past
+ *
+ * @param exp - Expiration time (seconds since epoch)
+ * @param iat - Issued at time (seconds since epoch)
+ * @param ttl - Time to live in seconds
+ * @param currentTime - Current time (seconds since epoch). Defaults to now.
+ * @returns True if expired
+ *
+ * @example
+ * ```typescript
+ * if (isExpired(payload.exp, payload.iat, payload.ttl)) {
+ *   throw new Error('Status list expired');
+ * }
+ * ```
+ */
+declare function isExpired(exp?: number, iat?: number, ttl?: number, currentTime?: number): boolean;
+
+export { type BitsPerStatus, type COSEKey, COSE_ALGORITHMS, COSE_HEADERS, CWT_CLAIMS, CompressionError, type CreateCWTStatusListOptions, type CreateJWTStatusListOptions, type EC2Key, FetchError, type FetchOptions, IndexOutOfBoundsError, InvalidBitSizeError, InvalidStatusValueError, InvalidTokenFormatError, MissingStatusListUriError, type OKPKey, type ParsedCWTStatusList, type ParsedJWTStatusList, type SignCWTOptions, type SignJWTOptions, StandardStatusValues, type StatusFormat, StatusList, type StatusListCWTClaim, type StatusListCWTPayload, type StatusListClaim, type StatusListConfig, StatusListError, StatusListExpiredError, type StatusListJWTHeader, type StatusListJWTPayload, type StatusListReference, type StatusListReferenceCBOR, StatusListTokenHelper, type StatusValue, type TokenStatusClaim, ValidationError, type ValidationResult, type VerifiedStatusListJWT, type VerifyJWTOptions, calculateCapacity, compress, compressToBase64URL, createCWTStatusListPayload, createJWTStatusListPayload, decompress, decompressFromBase64URL, encodeCWTPayload, extractStatusListReference, extractStatusListReferenceCBOR, fetchStatusListToken, getBitValue, isExpired, isValidStatusListUri, packBits, parseCWTStatusList, parseCWTStatusListSigned, parseJWTStatusList, setBitValue, signCOSE, signCWTStatusList, signStatusListJWT, unpackBits, validateCWTPayload, validateExpiry, validateJWTPayload, validateTTLBounds, verifyCOSE, verifySignatureOnly, verifyStatusListJWT };