@vess-id/status-list

IETF OAuth Status List implementation for TypeScript/Node.js, supporting both JWT and CWT formats.


Overview

This library implements the IETF OAuth Status List specification for managing credential status information in a privacy-preserving, space-efficient manner.

Key Features:
- ✅ Dual Format Support: JWT and CWT (CBOR Web Token) formats
- ✅ Space Efficient: ZLIB compression reduces storage by 90%+
- ✅ Privacy Preserving: Herd privacy through large status lists
- ✅ Flexible Status Values: Support for 1, 2, 4, or 8-bit status values
- ✅ Full Lifecycle: Create, sign, verify, and query status lists
- ✅ Standards Compliant: Follows IETF draft-ietf-oauth-status-list-14
- ✅ TypeScript Native: Full type safety with comprehensive types
- ✅ Production Ready: Extensive test coverage (86+ tests)

Use Cases

- SD-JWT Verifiable Credentials: Revocation for Selective Disclosure JWTs
- mdoc/mDL: Status management for mobile Driver's Licenses and ISO 18013-5 documents
- W3C Verifiable Credentials: Credential status tracking
- OAuth Token Revocation: Scalable token status lists

Installation

``bash
npm install @vess-id/status-list
`

Requirements:
- Node.js >= 20
- TypeScript >= 5.0 (if using TypeScript)

Quick Start

$3

`typescript
import {
StatusList,
createJWTStatusListPayload,
signStatusListJWT,
StandardStatusValues,
} from '@vess-id/status-list';
import { importPKCS8 } from 'jose';

// 1. Create a status list (1 bit per entry: 0=valid, 1=revoked)
const list = StatusList.create(10000, 1);

// 2. Revoke some credentials
list.setStatus(42, StandardStatusValues.INVALID);
list.setStatus(100, StandardStatusValues.INVALID);

// 3. Create JWT payload
const { payload } = createJWTStatusListPayload({
statusList: list,
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, // 24 hours
ttl: 3600, // Cache for 1 hour
});

// 4. Sign the JWT
const privateKey = await importPKCS8(pemPrivateKey, 'ES256');
const jwt = await signStatusListJWT(payload, privateKey, { alg: 'ES256' });

console.log('Status List JWT:', jwt);
`

$3

`typescript
import {
StatusListTokenHelper,
StandardStatusValues,
} from '@vess-id/status-list';

// Extract status reference from credential
const credentialStatus = {
idx: 42,
uri: 'https://issuer.example.com/status/1',
};

// Fetch and parse status list
const helper = await StatusListTokenHelper.fromStatusReference(credentialStatus);

// Check if expired
if (helper.isExpired()) {
throw new Error('Status list expired');
}

// Check credential status
const status = helper.getStatus(credentialStatus.idx);

if (status === StandardStatusValues.INVALID) {
console.log('❌ Credential is REVOKED');
} else if (status === StandardStatusValues.VALID) {
console.log('✅ Credential is VALID');
} else if (status === StandardStatusValues.SUSPENDED) {
console.log('⏸️ Credential is SUSPENDED');
}
`

$3

`typescript
import {
StatusList,
createCWTStatusListPayload,
encodeCWTPayload,
} from '@vess-id/status-list';

// 1. Create status list
const list = StatusList.create(10000, 2); // 2 bits: supports 4 status values

// 2. Set statuses
list.setStatus(0, 0); // Valid
list.setStatus(1, 1); // Invalid
list.setStatus(2, 2); // Suspended

// 3. Create CWT payload
const payload = createCWTStatusListPayload({
sub: 'https://issuer.example.com/status/1',
iss: 'https://issuer.example.com',
lst: list.compressToBytes(),
bits: 2,
iat: Math.floor(Date.now() / 1000),
exp: Math.floor(Date.now() / 1000) + 86400,
});

// 4. Encode to CBOR
const cwtBytes = encodeCWTPayload(payload);

console.log('CWT Status List:', cwtBytes);
`

API Reference

$3

#### StatusList

Main class for managing bit-packed status arrays.

`typescript
// Create new list
const list = StatusList.create(size: number, bits: BitsPerStatus);

// From existing statuses
const list = StatusList.fromArray(statuses: StatusValue[], bits: BitsPerStatus);

// Decompress from JWT
const list = StatusList.decompressFromBase64URL(compressed: string, bits: BitsPerStatus);

// Decompress from CWT
const list = StatusList.decompressFromBytes(compressed: Uint8Array, bits: BitsPerStatus);

// Get/Set status
const status = list.getStatus(index: number): StatusValue;
list.setStatus(index: number, value: StatusValue): void;

// Compress for JWT
const compressed = list.compressToBase64URL(): string;

// Compress for CWT
const compressed = list.compressToBytes(): Uint8Array;

// Metadata
const size = list.getSize(): number;
const bits = list.getBitsPerStatus(): BitsPerStatus;
`

#### StatusListTokenHelper

High-level helper for working with Status List Tokens.

`typescript
// From token (auto-detects JWT/CWT)
const helper = StatusListTokenHelper.fromToken(token: string | Uint8Array);

// From URI (fetches via HTTP)
const helper = await StatusListTokenHelper.fromStatusReference(
reference: { idx: number; uri: string },
options?: FetchOptions
);

// Query status
const status = helper.getStatus(index: number): StatusValue;

// Check expiration
const expired = helper.isExpired(currentTime?: number): boolean;

// Access metadata
const iss = helper.iss;
const sub = helper.sub;
const iat = helper.iat;
const exp = helper.exp;
const ttl = helper.ttl;
const bits = helper.bits;
const size = helper.size;
const format = helper.tokenFormat; // 'jwt' | 'cwt'
`

$3

#### Creating JWT Status Lists

`typescript
import {
createJWTStatusListPayload,
signStatusListJWT,
type CreateJWTStatusListOptions,
} from '@vess-id/status-list';

// Create payload
const { header, payload } = createJWTStatusListPayload({
statusList: list,
iss: string,
sub: string,
iat?: number, // defaults to now
exp?: number,
ttl?: number,
aggregationUri?: string,
});

// Sign
const jwt = await signStatusListJWT(
payload,
privateKey: KeyLike,
options?: {
alg?: string;
kid?: string;
additionalHeaders?: Record;
}
): Promise;
`

#### Parsing JWT Status Lists

`typescript
import {
parseJWTStatusList,
verifyStatusListJWT,
extractStatusListReference,
} from '@vess-id/status-list';

// Parse (without verification)
const { header, payload, statusList } = parseJWTStatusList(jwt: string);

// Verify signature
const { header, payload } = await verifyStatusListJWT(
jwt: string,
publicKey: KeyLike,
options?: {
issuer?: string;
validateExp?: boolean;
}
);

// Extract reference from credential
const reference = extractStatusListReference(credentialJWT: string);
// Returns: { idx: number, uri: string }
`

$3

#### Creating CWT Status Lists

`typescript
import {
createCWTStatusListPayload,
encodeCWTPayload,
signCWTStatusList,
type COSEKey,
} from '@vess-id/status-list';

// Create payload
const payload = createCWTStatusListPayload({
sub?: string,
iss?: string,
lst: Uint8Array,
bits: BitsPerStatus,
iat?: number,
exp?: number,
ttl?: number,
aggregation_uri?: string,
additionalClaims?: Record,
});

// Encode to CBOR (unsigned)
const cwtBytes = encodeCWTPayload(payload);

// Sign with COSE Sign1 (advanced)
const cwtSigned = signCWTStatusList(
payload,
privateKey: COSEKey,
options?: {
alg?: number;
kid?: Uint8Array;
additionalHeaders?: Map;
}
);
`

#### Parsing CWT Status Lists

`typescript
import {
parseCWTStatusList,
parseCWTStatusListSigned,
extractStatusListReferenceCBOR,
} from '@vess-id/status-list';

// Parse unsigned CWT
const { payload, statusList } = parseCWTStatusList(cwtBytes: Uint8Array);

// Parse and verify signed CWT
const { payload, statusList } = parseCWTStatusListSigned(
cwtBytes: Uint8Array,
publicKey: COSEKey
);

// Extract reference from mdoc credential
const reference = extractStatusListReferenceCBOR(credentialCBOR: Uint8Array);
// Returns: { idx: number, uri: string }
`

$3

`typescript
import {
validateJWTPayload,
validateCWTPayload,
validateExpiry,
validateTTLBounds,
isExpired,
} from '@vess-id/status-list';

// Validate payload structure
const result = validateJWTPayload(payload);
if (!result.valid) {
console.error('Errors:', result.errors);
}

// Check expiration
const expiryResult = validateExpiry(exp, iat, ttl);
if (!expiryResult.valid) {
console.error('Token expired');
}

// Validate TTL bounds (DoS prevention)
const ttlResult = validateTTLBounds(ttl);
if (!ttlResult.valid) {
console.warn('TTL outside recommended bounds:', ttlResult.errors);
}

// Simple expiration check
if (isExpired(exp, iat, ttl)) {
throw new Error('Token expired');
}
`

$3

`typescript
import {
fetchStatusListToken,
isValidStatusListUri,
type FetchOptions,
} from '@vess-id/status-list';

// Fetch status list (auto-detects JWT/CWT)
const token = await fetchStatusListToken(
uri: string,
options?: {
timeout?: number; // default: 10000ms
headers?: Record;
maxRedirects?: number; // default: 3
fetchImpl?: typeof fetch;
}
);

// Validate URI
if (!isValidStatusListUri(uri)) {
throw new Error('Invalid status list URI');
}
`

Types

$3

`typescript
type BitsPerStatus = 1 | 2 | 4 | 8;
type StatusValue = number; // 0-255 depending on bits

enum StandardStatusValues {
VALID = 0x00,
INVALID = 0x01,
SUSPENDED = 0x02,
APPLICATION_SPECIFIC = 0x03,
}
`

$3

`typescript
type StatusFormat = 'jwt' | 'cwt';

interface StatusListReference {
idx: number;
uri: string;
}
`

Advanced Examples

$3

`typescript
import { StatusList, StandardStatusValues } from '@vess-id/status-list';

// Create list for 100,000 credentials
const list = StatusList.create(100000, 1);

// Revoke every 1000th credential
for (let i = 0; i < 100000; i += 1000) {
list.setStatus(i, StandardStatusValues.INVALID);
}

// Compress
const compressed = list.compressToBase64URL();
console.log('Compressed size:', compressed.length, 'characters');
// Expected: ~4-5KB (90%+ compression)

// Original size: 100,000 bits = 12,500 bytes
// Compressed: ~5,000 bytes (~60% compression for sparse data)
`

$3

`typescript
import { StatusList } from '@vess-id/status-list';

const STATUS = {
ACTIVE: 0,
REVOKED: 1,
SUSPENDED: 2,
EXPIRED: 3,
};

// 2 bits per status = 4 possible values
const list = StatusList.create(1000, 2);

list.setStatus(0, STATUS.ACTIVE);
list.setStatus(1, STATUS.REVOKED);
list.setStatus(2, STATUS.SUSPENDED);
list.setStatus(3, STATUS.EXPIRED);

const status = list.getStatus(1);
console.log(status === STATUS.REVOKED); // true
`

$3

`typescript
import {
StatusListTokenHelper,
validateExpiry,
validateTTLBounds,
} from '@vess-id/status-list';

async function validateCredentialStatus(reference: { idx: number; uri: string }) {
// Fetch status list
const helper = await StatusListTokenHelper.fromStatusReference(reference);

// Validate expiry
const expiryResult = validateExpiry(helper.exp, helper.iat, helper.ttl);
if (!expiryResult.valid) {
throw new Error(Status list expired: ${expiryResult.errors.join(', ')});
}

// Validate TTL bounds
const ttlResult = validateTTLBounds(helper.ttl);
if (!ttlResult.valid) {
console.warn(TTL warning: ${ttlResult.errors.join(', ')});
}

// Check status
const status = helper.getStatus(reference.idx);
return {
valid: status === 0,
status,
issuer: helper.iss,
expiresAt: helper.exp,
};
}
`

$3

`typescript
import { createJWTStatusListPayload, signStatusListJWT } from '@vess-id/status-list';

// 1. Issue credential with status claim
const credential = {
iss: 'https://issuer.example.com',
sub: 'user@example.com',
iat: Math.floor(Date.now() / 1000),
exp: Math.floor(Date.now() / 1000) + 31536000, // 1 year
vc: {
type: ['VerifiableCredential', 'UniversityDegree'],
credentialSubject: {
name: 'Alice Smith',
degree: 'Bachelor of Science',
},
},
status: {
idx: 42,
uri: 'https://issuer.example.com/status/1',
},
};

// 2. Create status list
const list = StatusList.create(10000, 1);
const { payload } = createJWTStatusListPayload({
statusList: list,
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,
});

// 3. Sign status list
const statusListJWT = await signStatusListJWT(payload, privateKey);

// 4. Verifier checks status
const helper = await StatusListTokenHelper.fromStatusReference(credential.status);
const status = helper.getStatus(credential.status.idx);

if (status === 1) {
throw new Error('Credential has been revoked');
}
`

Security Considerations

This library follows the security recommendations from the IETF specification:

$3


`typescript
// Default limits prevent DoS attacks
const MAX_TTL = 31536000; // 1 year
const MIN_TTL = 60; // 1 minute

// Validate TTL
const result = validateTTLBounds(ttl);
if (!result.valid) {
console.warn('TTL outside recommended bounds');
}
`

$3


`typescript
// Default maximum: 3 redirects
const token = await fetchStatusListToken(uri, {
maxRedirects: 3,
});
`

$3

`typescript
// Default timeout: 10 seconds
const token = await fetchStatusListToken(uri, {
timeout: 10000,
});
`

$3

`typescript
// Always verify signatures in production
const verified = await verifyStatusListJWT(jwt, publicKey);
`

$3

`typescript
// Use large lists for privacy (recommended: 10,000+ entries)
const list = StatusList.create(100000, 1);
// Even with few revoked credentials, observers cannot correlate
`

Performance

$3

| Entries | Bits | Uncompressed | Compressed | Ratio |
|---------|------|--------------|------------|-------|
| 10,000 | 1 | 1.22 KB | ~500 B | 60% |
| 100,000 | 1 | 12.2 KB | ~5 KB | 60% |
| 10,000 | 2 | 2.44 KB | ~1 KB | 60% |
| 100,000 | 8 | 97.7 KB | ~20 KB | 80% |

Compression ratio depends on data entropy. Sparse lists compress better.

$3

`typescript
// Minimal memory footprint
const list = StatusList.create(100000, 1);
// Memory: ~12.5 KB (uncompressed in memory)
// Network: ~5 KB (compressed over wire)
`

Testing

`bash


Run all tests

npm test

Run tests in watch mode

npm run test:watch

Run tests with coverage

npm run test:coverage

Build

npm run build

Lint

npm run lint

Format

npm run format
`

$3

`
Test Files: 5 passed (5)
Tests: 86 passed (86)
- Core (bitpack, compression, StatusList): 58 tests
- JWT integration: 10 tests
- CWT integration: 18 tests
``

Compatibility

$3

- ✅ Node.js 20+
- ✅ Node.js 22+

$3

- ✅ ESM (import)
- ✅ CommonJS (require)

$3

- ✅ TypeScript 5.0+
- ✅ Full type definitions included
- ✅ Strict mode compatible

IETF Specification Compliance

This library implements draft-ietf-oauth-status-list-14:

- ✅ Section 3: Status List Structure
- ✅ Section 4: Bit Packing (LSB-first)
- ✅ Section 5: JWT Status List
- ✅ Section 5.2: CWT Status List
- ✅ Section 6: Status Reference
- ✅ Section 11: Security Considerations

Related Projects

- EUDI Wallet IT (Python) - Reference implementation
- @sd-jwt/jwt-status-list - SD-JWT TypeScript implementation

Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch
3. Write tests for new features
4. Ensure all tests pass
5. Submit a pull request

License

Apache License 2.0

Copyright (c) 2024 VESS Project

See LICENSE file for details.

Support

- Issues: GitHub Issues
- Documentation: API Reference
- Specification: IETF Draft

---

Made with ❤️ for the Verifiable Credentials ecosystem