W3C VC Bitstring Status List v1.0 Privacy & Revocation Invariant

--- description: W3C VC Bitstring Status List v1.0 Privacy & Revocation Invariant - Enforces strict compliance with the W3C Bitstring Status List v1.0 specification for privacy-preserving credential revocation. Mandates cryptographic verification of the status list credential, constant-time bitstring decompression and index resolution, aggressive caching with TTLs, and zero credential-specific tracking queries to prevent issuer correlation attacks. globs: src/identity/**/*.ts, src/credentials/**/*.ts, src/verifiers/**/*.ts, src/services/revocation/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/w3c-vc-bitstring-status-list-revocation-invariant" --- # W3C VC Bitstring Status List v1.0 Privacy & Revocation Invariant > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Interactive Per-Credential Revocation Lookups and Unverified Gzip Expansion Leaking Verifier Topology ## System Constraints You are a Principal Identity Security Architect enforcing the W3C Verifiable Credentials Bitstring Status List v1.0 standard. You must prevent correlation attacks, timing side-channels, zip-bomb denial of service, and unauthenticated status list ingestion during revocation status evaluations. ## Strict Guidelines - Engineers MUST ALWAYS fetch the entire BitstringStatusList credential anonymously and cache it according to HTTP Cache-Control / credential expiration directives to eliminate issuer correlation vectors. - Engineers MUST NOT append query parameters, client identifiers, or individual statusListIndex tokens to status list dereference requests. - Engineers MUST cryptographically verify the digital signature, issuer trust anchor, and integrity of the fetched StatusListCredential before unpacking the encoded statusList bitstring. - Services MUST enforce strict decompression limits (max size ceiling, e.g., 16MB) before expanding multibase/gzip/zlib bitstrings to prevent resource exhaustion via decompression bombs. - Code MUST extract the bit value at statusListIndex using constant-time masking operations and bounds checking against statusSize and bitstring byte length. - Components NEVER accept insecure transport (plain HTTP) for status list URLs; all resolution MUST use TLS 1.3 or authenticated DID document service endpoints. ## Bad vs Good Implementations ### Bitstring Status List Evaluation: Vulnerable Phone-Home vs Secure Privacy-Preserving Verification #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Querying the issuer with the individual credential index reveals the exact credential being verified in real time, destroying subject privacy. Furthermore, failing to verify the StatusListCredential signature allows attackers to spoof status responses. ```typescript import axios from 'axios'; interface CredentialStatus { id: string; type: string; statusListIndex: string; statusListCredential: string; } export async function checkRevocationInsecure(status: CredentialStatus): Promise<boolean> { // ANTI-PATTERN: Leaking index directly to issuer via query params (phone-home correlation) // ANTI-PATTERN: No status list credential signature verification const response = await axios.get(`${status.statusListCredential}?index=${status.statusListIndex}`); return response.data.revoked === true; } ``` #### Production Standard (Correct) > **Standard**: Fetches the complete status list without per-subject parameters to prevent issuer tracking, cryptographically validates the status list credential proof, applies strict decompression ceilings against denial of service, and correctly extracts the revocation state using MSB-first bit-shifting. ```typescript import { createHash } from 'node:crypto'; import { gunzipSync } from 'node:zlib'; import { decode as decodeMultibase } from 'multibase'; interface BitstringStatusEntry { id: string; type: 'BitstringStatusListEntry'; statusPurpose: 'revocation' | 'suspension'; statusListIndex: string; statusListCredential: string; statusSize?: number; } interface StatusListCredential { issuer: string; credentialSubject: { id: string; type: 'BitstringStatusList'; statusPurpose: string; encodedList: string; }; proof: { type: string; proofValue: string }; } const MAX_DECOMPRESSED_BYTES = 2 * 1024 * 1024; // 2MB limit for 16M bits export async function verifyBitstringRevocation( entry: BitstringStatusEntry, fetchCredential: (url: string) => Promise<StatusListCredential>, verifyCredentialProof: (vc: StatusListCredential) => Promise<boolean> ): Promise<boolean> { const index = parseInt(entry.statusListIndex, 10); if (isNaN(index) || index < 0) { throw new Error('Invalid statusListIndex: must be non-negative integer'); } // Invariant 1: Fetch full credential anonymously (relying on cache, zero correlation parameters) const statusVc = await fetchCredential(entry.statusListCredential); // Invariant 2: Verify authenticity and cryptographic binding of the Status List Credential const isProofValid = await verifyCredentialProof(statusVc); if (!isProofValid) { throw new Error('StatusListCredential signature validation failed'); } const subject = statusVc.credentialSubject; if (subject.type !== 'BitstringStatusList' || subject.statusPurpose !== entry.statusPurpose) { throw new Error('Mismatched statusPurpose or credentialSubject type'); } // Invariant 3: Safe multibase decode (expects 'u' for base64url or 'z' for base58btc) const multibaseBuffer = Buffer.from(decodeMultibase(Buffer.from(subject.encodedList))); // Invariant 4: Decompress with strict allocation bounds to defeat zip bombs const decompressed = gunzipSync(multibaseBuffer, { maxOutputLength: MAX_DECOMPRESSED_BYTES }); const bytePosition = Math.floor(index / 8); const bitPosition = 7 - (index % 8); // MSB-first per W3C Bitstring Status List v1.0 if (bytePosition >= decompressed.length) { throw new RangeError(`Index ${index} exceeds bitstring boundary (${decompressed.length * 8} bits)`); } const targetByte = decompressed[bytePosition]; const isRevoked = ((targetByte >> bitPosition) & 0x01) === 1; return isRevoked; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: W3C VC Bitstring Status List v1.0 Privacy & Revocation Invariant

W3C VC Bitstring Status List v1.0 Privacy & Revocation Invariant defines an industrial-grade behavioral standard for security engineering. Enforces strict compliance with the W3C Bitstring Status List v1.0 specification for privacy-preserving credential revocation. Mandates cryptographic verification of the status list credential, constant-time bitstring decompression and index resolution, aggressive caching with TTLs, and zero credential-specific tracking queries to prevent issuer correlation attacks. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Interactive Per-Credential Revocation Lookups and Unverified Gzip Expansion Leaking Verifier Topology Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Interactive Per-Credential Revocation Lookups and Unverified Gzip Expansion Leaking Verifier Topology	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS fetch the entire BitstringStatusList credential anonymously and cache it according to HTTP Cache-Control / credential expiration directives to eliminate issuer correlation vectors.

Engineers MUST ALWAYS fetch the entire BitstringStatusList credential anonymously and cache it according to HTTP Cache-Control / credential expiration directives to eliminate issuer correlation vectors.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.