{"_id":"@4sure-tech/vc-bitstring-status-lists","_rev":"2-d94d5cbce8b7db71fb515afe6f0cc8fc","name":"@4sure-tech/vc-bitstring-status-lists","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0-unstable.1":{"name":"@4sure-tech/vc-bitstring-status-lists","version":"0.1.0-unstable.1","keywords":["verifiable-credentials","bitstring","status-list","w3c","revocation","suspension","typescript"],"author":{"name":"4Sure Technology Solutions"},"license":"Apache-2.0","_id":"@4sure-tech/vc-bitstring-status-lists@0.1.0-unstable.1","maintainers":[{"name":"nklomp78","email":"nklomp@4sure.tech"}],"homepage":"https://4sure.tech","bugs":{"url":"https://github.com/4sure-tech/vc-bitstring-status-lists/issues"},"dist":{"shasum":"421d978dcacc526f56e5b4d2e49fc6f91e605c80","tarball":"https://registry.npmjs.org/@4sure-tech/vc-bitstring-status-lists/-/vc-bitstring-status-lists-0.1.0-unstable.1.tgz","fileCount":18,"integrity":"sha512-IulCugjbxjr5V9A6fNM+PGucr7NYRXXoxzgGo84x8ZTZVW5o10GzfAdhO1mC99KW4IPesozLs1bxVcUnkoy77Q==","signatures":[{"sig":"MEYCIQDXtiRBnd44pAbO+yP1saOG+Dfikjk0Cjappv2oYtZ/ZwIhAJtJO8RnRz7ZQ1rI5vUW0ny6ZK4bOjK21wHnSUOGaBLx","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":201803},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","source":"src/index.ts","exports":{"import":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","require":"./dist/index.cjs"}},"gitHead":"5ea23b450f768033c27684ff474c60f7c50097bd","scripts":{"build":"tsup","test:ci":"vitest"},"_npmUser":{"name":"nklomp78","email":"nklomp@4sure.tech"},"repository":{"url":"git+https://github.com/4sure-tech/vc-bitstring-status-lists.git","type":"git"},"_npmVersion":"10.8.2","description":"TypeScript library for W3C Bitstring Status List v1.0 specification - privacy-preserving credential status management","directories":{},"_nodeVersion":"20.19.3","dependencies":{"pako":"^2.1.0","uint8arrays":"^5.1.0","base64url-universal":"^2.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"pnpm@10.13.1","devDependencies":{"tsup":"^8.5.0","vite":"^7.0.3","turbo":"^2.5.4","vitest":"^3.2.4","typescript":"^5.8.3","@types/node":"^24.0.12","@types/pako":"^2.0.3","vite-tsconfig-paths":"^5.1.4"},"_npmOperationalInternal":{"tmp":"tmp/vc-bitstring-status-lists_0.1.0-unstable.1_1752227992225_0.464844517482935","host":"s3://npm-registry-packages-npm-production"}},"0.1.0":{"name":"@4sure-tech/vc-bitstring-status-lists","version":"0.1.0","description":"TypeScript library for W3C Bitstring Status List v1.0 specification - privacy-preserving credential status management","source":"src/index.ts","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{"import":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","require":"./dist/index.cjs"}},"scripts":{"build":"tsup","test:ci":"vitest"},"keywords":["verifiable-credentials","bitstring","status-list","w3c","revocation","suspension","typescript"],"author":{"name":"4Sure Technology Solutions"},"repository":{"type":"git","url":"git+https://github.com/4sure-tech/vc-bitstring-status-lists.git"},"homepage":"https://4sure.tech","license":"Apache-2.0","packageManager":"pnpm@10.13.1","dependencies":{"base64url-universal":"^2.0.0","pako":"^2.1.0","uint8arrays":"^5.1.0"},"devDependencies":{"@types/node":"^24.0.12","@types/pako":"^2.0.3","tsup":"^8.5.0","turbo":"^2.5.4","typescript":"^5.8.3","vite":"^7.0.3","vite-tsconfig-paths":"^5.1.4","vitest":"^3.2.4"},"_id":"@4sure-tech/vc-bitstring-status-lists@0.1.0","gitHead":"81ce0aa6391e9db8760e60034d902d31c797fa61","bugs":{"url":"https://github.com/4sure-tech/vc-bitstring-status-lists/issues"},"_nodeVersion":"20.19.3","_npmVersion":"10.8.2","dist":{"integrity":"sha512-NtjNuZldPps2AIeiC2Pj5qSH91bDTcRQ0IRduAmbQpf9EZ+b6h7V6rsbo3TZoamVbAio/M5A2/Lvt4hnQ/og7w==","shasum":"b97ca56f8d184da473dffb1a4d4db8e9c140c483","tarball":"https://registry.npmjs.org/@4sure-tech/vc-bitstring-status-lists/-/vc-bitstring-status-lists-0.1.0.tgz","fileCount":18,"unpackedSize":201830,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIG76lDhMpUGl6+YOPw8FUJn8gE9CQwWK2FQ2AWrOAKI9AiEAwrjlhA+JfcSsCcq8GzYiGidYgUMwVYSA2GAkrjBCx7k="}]},"_npmUser":{"name":"nklomp78","email":"nklomp@4sure.tech"},"directories":{},"maintainers":[{"name":"nklomp78","email":"nklomp@4sure.tech"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/vc-bitstring-status-lists_0.1.0_1752229598452_0.4273421504082948"},"_hasShrinkwrap":false}},"time":{"created":"2025-07-11T09:59:52.139Z","modified":"2025-07-11T10:26:38.826Z","0.1.0-unstable.1":"2025-07-11T09:59:52.404Z","0.1.0":"2025-07-11T10:26:38.626Z"},"bugs":{"url":"https://github.com/4sure-tech/vc-bitstring-status-lists/issues"},"author":{"name":"4Sure Technology Solutions"},"license":"Apache-2.0","homepage":"https://4sure.tech","keywords":["verifiable-credentials","bitstring","status-list","w3c","revocation","suspension","typescript"],"repository":{"type":"git","url":"git+https://github.com/4sure-tech/vc-bitstring-status-lists.git"},"description":"TypeScript library for W3C Bitstring Status List v1.0 specification - privacy-preserving credential status management","maintainers":[{"name":"nklomp78","email":"nklomp@4sure.tech"}],"readme":"# vc-bitstring-status-lists\n\nA TypeScript library implementing the [W3C Bitstring Status List v1.0 specification](https://www.w3.org/TR/vc-bitstring-status-list/) for privacy-preserving credential status management in Verifiable Credentials.\n\n## What is Bitstring Status List?\n\nThink of the Bitstring Status List as a privacy-preserving way to check whether a credential has been revoked or suspended. Instead of maintaining a public database of revoked credentials (which would reveal sensitive information), the specification uses a compressed bitstring where each bit represents the status of a credential.\n\nHere's how it works conceptually: imagine you have 100,000 credentials. Rather than listing \"credential #1234 is revoked,\" you create a bitstring where position 1234 contains a bit indicating the status. The entire bitstring is compressed and published, allowing anyone to check a credential's status without revealing which credentials they're checking.\n\n## Key Features\n\nThis library provides a complete implementation of the W3C specification with the following capabilities:\n\n- **Direct credential access** through the `BitManager` class, which handles low-level bit operations without requiring explicit entry creation\n- **Compressed storage** using gzip compression and base64url encoding, meeting the W3C requirement for minimum 16KB bitstrings\n- **Uniform status width** where all credentials in a status list use the same number of bits for their status values\n- **Full W3C compliance** including proper validation, minimum bitstring sizes, and status purpose matching\n- **TypeScript support** with comprehensive type definitions for all specification interfaces\n\n## Installation\n\n```bash\npnpm install @4sure-tech/vc-bitstring-status-lists # or npm / yarn\n```\n\n## Quick Start\n\nLet's walk through creating and using a status list step by step:\n\n### 1. Creating a Status List\n\n```typescript\nimport { BitstreamStatusList, createStatusListCredential } from 'vc-bitstring-status-lists'\n\n// Create a new status list with 1-bit status values (0 = valid, 1 = revoked)\nconst statusList = new BitstreamStatusList({ statusSize: 1 })\n\n// Set credential statuses directly using their indices\nstatusList.setStatus(0, 0) // Credential at index 0 is valid\nstatusList.setStatus(1, 1) // Credential at index 1 is revoked  \nstatusList.setStatus(42, 1) // Credential at index 42 is revoked\n```\n\nThe key insight here is that you don't need to \"add\" entries first. The system automatically handles any credential index you reference, creating the necessary bit positions as needed.\n\n### 2. Publishing the Status List\n\n```typescript\n// Create a verifiable credential containing the status list\nconst statusListCredential:BitstringStatusListCredentialUnsigned = await createStatusListCredential({\n  id: 'https://example.com/status-lists/1',\n  issuer: 'https://example.com/issuer',\n  statusPurpose: 'revocation',\n  statusList: statusList, // Pass your configured status list\n  validFrom: new Date('2025-07-01'),\n  validUntil: new Date('2026-07-01')\n})\n\n// The credential now contains a compressed, encoded bitstring\nconsole.log(statusListCredential.credentialSubject.encodedList)\n// Output: \"u...\" (compressed and base64url-encoded bitstring)\n```\n\n### 3. Checking Credential Status\n\n```typescript\nimport { checkStatus } from 'vc-bitstring-status-lists'\n\n// A credential that references the status list\nconst credential = {\n  '@context': ['https://www.w3.org/ns/credentials/v2'],\n  id: 'https://example.com/credential/456',\n  type: ['VerifiableCredential'],\n  issuer: 'https://example.com/issuer',\n  credentialSubject: {\n    id: 'did:example:123',\n    type: 'Person',\n    name: 'Alice'\n  },\n  credentialStatus: {\n    type: 'BitstringStatusListEntry',\n    statusPurpose: 'revocation',\n    statusListIndex: '1', // This credential is at index 1 in the status list\n    statusSize: 1,\n    statusListCredential: 'https://example.com/status-lists/1'\n  }\n}\n\n// Check the credential's status\nconst result = await checkStatus({\n  credential,\n  getStatusListCredential: async (url) => {\n    // In practice, you'd fetch this from the URL\n    return statusListCredential\n  }\n})\n\nconsole.log(result)\n// Output: { verified: false, status: 1 } (credential is revoked)\n```\n\n## Advanced Usage\n\n### Multi-bit Status Values\n\nThe specification supports more than just binary states. You can use multiple bits per credential to represent complex status information:\n\n```typescript\n// Create a status list with 4 bits per credential (supports values 0-15)\nconst statusList = new BitstreamStatusList({ statusSize: 4 })\n\n// Set complex status values\nstatusList.setStatus(0, 12) // Binary: 1100, could represent multiple flags\nstatusList.setStatus(1, 3)  // Binary: 0011, different status combination\n\n// Retrieve the status\nconst status = statusList.getStatus(0) // Returns: 12\n```\n\nThis approach is particularly useful when you need to track multiple aspects of a credential's status simultaneously, such as revocation status, verification level, and processing state.\n\n### Status Messages\n\nYou can provide human-readable messages for different status values:\n\n```typescript\nconst credential = {\n  // ... other properties\n  credentialStatus: {\n    type: 'BitstringStatusListEntry',\n    statusPurpose: 'revocation',\n    statusListIndex: '0', \n    statusSize: 2, // Required to support status values up to 0x2 \n    statusListCredential: 'https://example.com/status-lists/1',\n    statusMessage: [\n      { id: '0x0', message: 'Credential is valid' },\n      { id: '0x1', message: 'Credential has been revoked' },\n      { id: '0x2', message: 'Credential is under review' }\n    ]\n  }\n}\n```\n\n### Multiple Status Purposes\n\nA single status list can serve multiple purposes:\n\n```typescript\nconst statusListCredential:BitstringStatusListCredentialUnsigned = await createStatusListCredential({\n  statusList: statusList,\n  id: 'https://example.com/status-lists/1',\n  issuer: 'https://example.com/issuer',\n  statusPurpose: ['revocation', 'suspension'] // Multiple purposes\n})\n```\n\n### Working with Existing Status Lists\n\nYou can decode and work with existing status lists:\n\n```typescript\n// Decode a status list from an encoded string\nconst existingStatusList = await BitstreamStatusList.decode({\n  encodedList: 'u...', // The encoded bitstring from a credential\n  statusSize: 1\n})\n\n// Check or modify statuses\nconsole.log(existingStatusList.getStatus(42)) // Get status of credential 42\nexistingStatusList.setStatus(100, 1) // Revoke credential 100\n\n// Re-encode for publishing\nconst updatedEncoded = await existingStatusList.encode()\n```\n\n## Understanding the Architecture\n\nThe library is built around several key components that work together to provide a complete W3C-compliant implementation:\n\n### BitManager Class\n\nThe `BitManager` is the foundation that handles all low-level bit operations. It manages a growing buffer of bytes and provides methods to set and get multi-bit values at specific positions. Think of it as a specialized array where you can efficiently pack multiple small integers.\n\nThe key insight is that it calculates bit positions mathematically: credential index 42 with a 2-bit status size would occupy bits 84-85 in the bitstring. This eliminates the need for explicit entry management.\n\n### BitstreamStatusList Class\n\nThe `BitstreamStatusList` wraps the `BitManager` and adds the W3C-specific requirements like compression, encoding, and minimum size constraints. It ensures that the resulting bitstring meets the specification's 16KB minimum size requirement.\n\nThis class handles the complex process of GZIP compression and multibase encoding that the W3C specification requires, while providing a simple interface for credential status management.\n\n### Verification Functions\n\nThe `checkStatus` function implements the complete verification algorithm, including fetching the status list credential, validating time bounds, checking status purposes, and extracting the actual status value.\n\n## W3C Compliance\n\nThis library implements all requirements from [the W3C Bitstring Status List v1.0 specification.](https://www.w3.org/TR/vc-bitstring-status-list):\n\n- **Minimum bitstring size**: All encoded status lists are padded to at least 16KB (131,072 bits)\n- **Compression**: Uses gzip compression as required by the specification\n- **Base64url encoding**: Proper encoding with the required \"u\" prefix\n- **Status purpose validation**: Ensures that credential entries match the status list's declared purposes\n- **Temporal validation**: Checks `validFrom` and `validUntil` dates on status list credentials\n- **Uniform status size**: All credentials in a status list use the same number of bits for their status\n\n## API Reference\n\n### Core Classes\n\n#### `BitstreamStatusList`\n\nThe main class for creating and managing status lists.\n\n```typescript\nclass BitstreamStatusList {\n  constructor(options?: { buffer?: Uint8Array; statusSize?: number; initialSize?: number })\n  getStatus(credentialIndex: number): number\n  setStatus(credentialIndex: number, status: number): void\n  getStatusSize(): number\n  getLength(): number\n  encode(): Promise<string>\n  static decode(options: { encodedList: string; statusSize?: number }): Promise<BitstreamStatusList>\n  static getStatusListLength(encodedList: string, statusSize: number): number\n}\n```\n\n#### `BitManager`\n\nLow-level bit manipulation class (typically used internally).\n\n```typescript\nclass BitManager {\n  constructor(options: { statusSize?: number; buffer?: Uint8Array; initialSize?: number })\n  getStatus(credentialIndex: number): number\n  setStatus(credentialIndex: number, status: number): void\n  getStatusSize(): number\n  getBufferLength(): number\n  toBuffer(): Uint8Array\n}\n```\n\n### High-Level Functions\n\n#### `createStatusListCredential`\n\nCreates a verifiable credential containing a status list.\n\n```typescript\nfunction createStatusListCredential(options: {\n  id: string\n  issuer: string | IIssuer\n  statusSize?: number\n  statusList?: BitstreamStatusList\n  statusPurpose: string | string[]\n  validFrom?: Date\n  validUntil?: Date\n  ttl?: number\n}): Promise<BitstringStatusListCredentialUnsigned>\n```\n\n#### `checkStatus`\n\nVerifies a credential's status against its referenced status list.\n\n```typescript\nfunction checkStatus(options: {\n  credential: CredentialWithStatus\n  getStatusListCredential: (url: string) => Promise<BitstringStatusListCredentialUnsigned>\n}): Promise<VerificationResult>\n```\n\n## Error Handling\n\nThe library provides comprehensive error handling with descriptive messages:\n\n```typescript\ntry {\n  const result = await checkStatus({ credential, getStatusListCredential })\n  if (!result.verified) {\n    console.log('Verification failed:', result.error?.message)\n    console.log('Status code:', result.status)\n  }\n} catch (error) {\n  console.error('Status check failed:', error)\n}\n```\n\n## Building and Testing\n\nThe project uses modern TypeScript tooling:\n\n```bash\n# Build the library\npnpm run build\n\n# Run tests\npnpm test\n\n# The build outputs both ESM and CommonJS formats\n# - dist/index.js (ESM)\n# - dist/index.cjs (CommonJS)\n# - dist/index.d.ts (TypeScript definitions)\n```\n\n## Contributing\n\nThis library implements a W3C specification, so contributions should maintain strict compliance with the [Bitstring Status List v1.0 specification](https://www.w3.org/TR/vc-bitstring-status-list/). When making changes, ensure that:\n\n1. All existing tests continue to pass\n2. New features include comprehensive test coverage\n3. The implementation remains compatible with the W3C specification\n4. Type definitions are updated for any API changes\n\n## License\n\nLicensed under the Apache License, Version 2.0.\n\n## Related Resources\n\n- [W3C Bitstring Status List v1.0 Specification](https://www.w3.org/TR/vc-bitstring-status-list/)\n- [W3C Verifiable Credentials Data Model](https://www.w3.org/TR/vc-data-model/)\n- [Verifiable Credentials Implementation Guide](https://www.w3.org/TR/vc-imp-guide/)\n","readmeFilename":"README.md"}