@kya-os/mcp-i-core 1.2.3-canary.6 → 1.3.0

package/docs/STATUSLIST2021_GUIDE.md

@@ -0,0 +1,696 @@
+# StatusList2021 Revocation Guide
+
+## Overview
+
+StatusList2021 is a W3C standard for efficient, privacy-preserving credential revocation. It uses bitstring compression to enable scalable revocation checking with minimal bandwidth and storage requirements.
+
+**Key Benefits:**
+- **Efficient**: 131,072 credentials in ~16KB compressed bitstring
+- **Privacy-Preserving**: Correlates less than individual revocation lists
+- **Scalable**: Single HTTP request to check any credential status
+- **Batch Updates**: Update multiple credential statuses atomically
+
+## How It Works
+
+### Bitstring Compression
+
+StatusList2021 uses a compressed bitstring where each credential gets assigned an index:
+
+```
+Bit Position:  0  1  2  3  4  5  6  7  ...  131071
+Status:        0  1  0  0  1  0  0  0  ...  1
+               ↑  ↑  ↑  ↑  ↑
+               OK REV OK OK REV
+```
+
+- **0** = Credential is valid
+- **1** = Credential is revoked
+
+The bitstring is GZIP-compressed and encoded as base64, reducing ~16KB uncompressed to ~2-4KB compressed.
+
+### Performance Characteristics
+
+| Credential Count | Uncompressed Size | Compressed Size | HTTP Transfer |
+|-----------------|-------------------|-----------------|---------------|
+| 10,000          | ~1.2 KB           | ~400 bytes      | <1ms          |
+| 100,000         | ~12 KB            | ~2 KB           | ~5ms          |
+| 131,072 (max)   | ~16 KB            | ~4 KB           | ~10ms         |
+
+**Comparison to Individual Revocation Lists:**
+- Individual lists: N credentials = N HTTP requests
+- StatusList2021: N credentials = 1 HTTP request
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Issuer System                             │
+├─────────────────────────────────────────────────────────────┤
+│                                                               │
+│  ┌──────────────┐         ┌─────────────────┐               │
+│  │ Delegation   │────────▶│ StatusList2021  │               │
+│  │ Credential   │         │ Manager         │               │
+│  └──────────────┘         └─────────────────┘               │
+│         │                          │                         │
+│         │                          ▼                         │
+│         │                  ┌──────────────┐                  │
+│         │                  │ Bitstring    │                  │
+│         │                  │ Storage      │                  │
+│         │                  │ (Redis/DB)   │                  │
+│         │                  └──────────────┘                  │
+│         │                          │                         │
+│         │                          ▼                         │
+│         │                  ┌──────────────┐                  │
+│         │                  │ Status List  │                  │
+│         │                  │ VC Document  │                  │
+│         │                  └──────────────┘                  │
+│         │                          │                         │
+│         └──────────────────────────┼─────────────────────────┘
+│                                    │
+│                                    ▼
+│                            [Public HTTPS URL]
+│                      https://issuer.com/status/1
+│                                    │
+├────────────────────────────────────┼─────────────────────────┐
+│                                    │                          │
+│              Verifier System       │                          │
+│                                    ▼                          │
+│                         ┌──────────────────┐                 │
+│                         │ StatusList2021   │                 │
+│                         │ Verifier         │                 │
+│                         └──────────────────┘                 │
+│                                    │                          │
+│                                    ▼                          │
+│                            [Check Status]                     │
+│                         Valid ✓ or Revoked ✗                 │
+└───────────────────────────────────────────────────────────────┘
+```
+
+## Basic Usage
+
+### 1. Creating a Status List
+
+```typescript
+import { StatusList2021Manager } from '@kya-os/mcp-i-core';
+
+// Initialize manager
+const statusListManager = new StatusList2021Manager({
+  issuerDid: 'did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK',
+  statusListUrl: 'https://issuer.example.com/status/1',
+  storage: myStorageProvider, // Redis, DynamoDB, etc.
+});
+
+// Create a new status list
+const statusListVC = await statusListManager.createStatusList({
+  id: 'https://issuer.example.com/status/1',
+  purpose: 'revocation',
+});
+
+console.log(statusListVC);
+```
+
+**Output:**
+```json
+{
+  "@context": [
+    "https://www.w3.org/2018/credentials/v1",
+    "https://w3id.org/vc/status-list/2021/v1"
+  ],
+  "id": "https://issuer.example.com/status/1",
+  "type": ["VerifiableCredential", "StatusList2021Credential"],
+  "issuer": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
+  "issuanceDate": "2025-10-17T12:00:00Z",
+  "credentialSubject": {
+    "id": "https://issuer.example.com/status/1#list",
+    "type": "StatusList2021",
+    "statusPurpose": "revocation",
+    "encodedList": "H4sIAAAAAAAAA+3BMQEAAADCoPVPbQwfoAAAAAAAAAAAAAAAAAAAAIC3AYbSVKsAQAAA"
+  },
+  "proof": {
+    "type": "Ed25519Signature2020",
+    "created": "2025-10-17T12:00:00Z",
+    "verificationMethod": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK#z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
+    "proofPurpose": "assertionMethod",
+    "proofValue": "z58DAdFfa9SkqZMVPxAQpic7ndSayn1PzZs6ZjWp1CktyGesjuTSwRdoWhAfGFCF5bppETSTojQCrfFPP2oumHKtz"
+  }
+}
+```
+
+### 2. Issuing Credentials with Status
+
+```typescript
+import { DelegationIssuer } from '@kya-os/mcp-i-core';
+
+const issuer = new DelegationIssuer({
+  issuerDid: 'did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK',
+  privateKeyJwk: issuerPrivateKey,
+});
+
+// Allocate a status list index for this credential
+const statusListIndex = await statusListManager.allocateIndex();
+
+const delegation = await issuer.issue({
+  subjectDid: 'did:key:z6MkrWXJPkxPCuQF7RqeKZFdZqBXz3oCG7PUty5dXLKGzELj',
+  constraints: {
+    scope: {
+      allowedTools: ['read_file', 'list_directory'],
+      allowedResources: ['/documents/*'],
+    },
+    time: {
+      notBefore: new Date().toISOString(),
+      notAfter: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
+    },
+  },
+  credentialStatus: {
+    id: `https://issuer.example.com/status/1#${statusListIndex}`,
+    type: 'StatusList2021Entry',
+    statusPurpose: 'revocation',
+    statusListIndex: statusListIndex.toString(),
+    statusListCredential: 'https://issuer.example.com/status/1',
+  },
+});
+
+console.log('Issued delegation with status index:', statusListIndex);
+```
+
+### 3. Revoking a Credential
+
+```typescript
+// Revoke a credential by its status list index
+await statusListManager.revokeCredential(statusListIndex);
+
+console.log(`Credential at index ${statusListIndex} has been revoked`);
+
+// The status list VC is automatically updated and republished
+```
+
+### 4. Checking Credential Status
+
+```typescript
+import { verifyDelegation } from '@kya-os/mcp-i-core';
+
+const result = await verifyDelegation({
+  credential: delegation,
+  expectedAudience: 'https://api.example.com',
+  checkStatus: true, // Enable status checking
+});
+
+if (!result.verified) {
+  console.error('Verification failed:', result.error);
+  if (result.statusRevoked) {
+    console.error('Credential has been revoked!');
+  }
+}
+```
+
+## Integration with Delegation Credentials
+
+### Credential Structure
+
+When a delegation credential includes status checking, it has a `credentialStatus` field:
+
+```typescript
+{
+  "@context": [
+    "https://www.w3.org/2018/credentials/v1",
+    "https://w3id.org/security/suites/ed25519-2020/v1",
+    "https://w3id.org/vc/status-list/2021/v1",
+    "https://schemas.kya-os.ai/delegation/v1"
+  ],
+  "id": "urn:uuid:12345678-1234-1234-1234-123456789abc",
+  "type": ["VerifiableCredential", "DelegationCredential"],
+  "issuer": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
+  "issuanceDate": "2025-10-17T12:00:00Z",
+  "credentialSubject": {
+    "id": "did:key:z6MkrWXJPkxPCuQF7RqeKZFdZqBXz3oCG7PUty5dXLKGzELj",
+    "constraints": {
+      "scope": {
+        "allowedTools": ["read_file"],
+        "allowedResources": ["/documents/*"]
+      }
+    }
+  },
+  "credentialStatus": {
+    "id": "https://issuer.example.com/status/1#42",
+    "type": "StatusList2021Entry",
+    "statusPurpose": "revocation",
+    "statusListIndex": "42",
+    "statusListCredential": "https://issuer.example.com/status/1"
+  },
+  "proof": { ... }
+}
+```
+
+### Verification Flow
+
+```
+┌──────────────┐
+│ Verifier     │
+│ receives     │
+│ delegation   │
+└──────┬───────┘
+       │
+       ▼
+┌─────────────────────┐
+│ Parse credential    │
+│ status field        │
+└─────────┬───────────┘
+          │
+          ▼
+┌─────────────────────────────┐
+│ Fetch StatusList2021        │
+│ from statusListCredential   │
+└─────────┬───────────────────┘
+          │
+          ▼
+┌─────────────────────────────┐
+│ Decompress encodedList      │
+└─────────┬───────────────────┘
+          │
+          ▼
+┌─────────────────────────────┐
+│ Check bit at                │
+│ statusListIndex             │
+└─────────┬───────────────────┘
+          │
+          ├──────────┐
+          │          │
+          ▼          ▼
+      ┌─────┐    ┌─────────┐
+      │ 0   │    │ 1       │
+      │ ✓   │    │ ✗       │
+      └─────┘    └─────────┘
+      Valid      Revoked
+```
+
+## Cascading Revocation
+
+When you revoke a parent delegation, all child delegations should also be revoked. The framework handles this automatically:
+
+```typescript
+import { DelegationGraph } from '@kya-os/mcp-i-core';
+
+// Build delegation graph
+const graph = new DelegationGraph();
+await graph.addDelegation(parentDelegation);
+await graph.addDelegation(childDelegation1);
+await graph.addDelegation(childDelegation2);
+
+// Revoke parent and all children
+await graph.revokeDelegation(
+  parentDelegation.id,
+  statusListManager,
+  { cascade: true }
+);
+
+console.log('Parent and all children revoked');
+```
+
+**Revocation Process:**
+```
+Parent (index: 42)
+├─ Child 1 (index: 100)
+│  └─ Grandchild (index: 200)
+└─ Child 2 (index: 150)
+
+Revoke parent → cascade = true
+→ Set bit 42 to 1
+→ Set bit 100 to 1
+→ Set bit 200 to 1
+→ Set bit 150 to 1
+```
+
+## Storage Providers
+
+### In-Memory Storage (Development)
+
+```typescript
+import { InMemoryStatusListStorage } from '@kya-os/mcp-i-core';
+
+const storage = new InMemoryStatusListStorage();
+
+const manager = new StatusList2021Manager({
+  issuerDid: myDid,
+  statusListUrl: 'https://issuer.example.com/status/1',
+  storage,
+});
+```
+
+### Redis Storage (Production)
+
+```typescript
+import { RedisStatusListStorage } from '@kya-os/mcp-i-core';
+import Redis from 'ioredis';
+
+const redis = new Redis(process.env.REDIS_URL);
+
+const storage = new RedisStatusListStorage({
+  client: redis,
+  keyPrefix: 'statuslist:',
+});
+
+const manager = new StatusList2021Manager({
+  issuerDid: myDid,
+  statusListUrl: 'https://issuer.example.com/status/1',
+  storage,
+});
+```
+
+### DynamoDB Storage (AWS)
+
+```typescript
+import { DynamoDBStatusListStorage } from '@kya-os/mcp-i-core';
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+
+const dynamodb = new DynamoDBClient({ region: 'us-east-1' });
+
+const storage = new DynamoDBStatusListStorage({
+  client: dynamodb,
+  tableName: 'StatusLists',
+});
+
+const manager = new StatusList2021Manager({
+  issuerDid: myDid,
+  statusListUrl: 'https://issuer.example.com/status/1',
+  storage,
+});
+```
+
+## Privacy Considerations
+
+### Correlation Attacks
+
+**Problem:** If each credential has its own revocation endpoint, tracking which endpoints are checked reveals which credentials are being verified.
+
+**Solution:** StatusList2021 groups many credentials into a single list. Verifiers fetch the entire list, making it harder to correlate checks with specific credentials.
+
+```
+Bad (Individual Lists):
+- Verifier checks https://issuer.com/revoke/alice-credential
+  → Issuer knows Alice's credential is being used
+
+Good (StatusList2021):
+- Verifier checks https://issuer.com/status/1
+  → Issuer knows someone is using a credential from this list (could be any of 100k+)
+```
+
+### Herd Privacy
+
+The larger the status list, the better the privacy:
+
+| List Size | Privacy Level              |
+|-----------|----------------------------|
+| 100       | Low (1% of list)           |
+| 1,000     | Medium (0.1% of list)      |
+| 10,000    | Good (0.01% of list)       |
+| 100,000+  | Excellent (0.001% of list) |
+
+**Best Practice:** Use large status lists (50k-100k credentials per list) to maximize herd privacy.
+
+## Advanced Patterns
+
+### Multiple Status Lists
+
+For different purposes or to manage scale:
+
+```typescript
+// Separate lists by purpose
+const revocationList = await manager.createStatusList({
+  id: 'https://issuer.example.com/status/revocation/1',
+  purpose: 'revocation',
+});
+
+const suspensionList = await manager.createStatusList({
+  id: 'https://issuer.example.com/status/suspension/1',
+  purpose: 'suspension',
+});
+
+// Separate lists by tenant
+const tenantAList = await manager.createStatusList({
+  id: 'https://issuer.example.com/status/tenant-a/1',
+  purpose: 'revocation',
+});
+
+const tenantBList = await manager.createStatusList({
+  id: 'https://issuer.example.com/status/tenant-b/1',
+  purpose: 'revocation',
+});
+```
+
+### Batch Revocation
+
+Revoke multiple credentials atomically:
+
+```typescript
+await statusListManager.batchRevoke([
+  42,   // credential 1
+  100,  // credential 2
+  250,  // credential 3
+  1337, // credential 4
+]);
+
+console.log('4 credentials revoked in single atomic update');
+```
+
+### Caching Status Lists
+
+Verifiers should cache status lists with appropriate TTLs:
+
+```typescript
+import { CachedStatusListVerifier } from '@kya-os/mcp-i-core';
+
+const verifier = new CachedStatusListVerifier({
+  cache: {
+    ttl: 300, // 5 minutes
+    maxSize: 100, // Cache up to 100 status lists
+  },
+  httpClient: fetch,
+});
+
+// First check: fetches from network
+await verifier.checkStatus(credential1);
+
+// Second check within TTL: uses cache
+await verifier.checkStatus(credential2);
+```
+
+### Status List Rotation
+
+Rotate status lists periodically to limit size:
+
+```typescript
+// Create new status list
+const newList = await manager.createStatusList({
+  id: 'https://issuer.example.com/status/2',
+  purpose: 'revocation',
+});
+
+// Migrate new credentials to new list
+const newIndex = await newListManager.allocateIndex();
+
+// Archive old list (keep accessible for verification)
+await manager.archiveStatusList('https://issuer.example.com/status/1');
+```
+
+## Best Practices
+
+### 1. Index Allocation
+
+Always allocate indexes sequentially to maximize compression:
+
+```typescript
+// Good: Sequential allocation
+const index1 = await manager.allocateIndex(); // 0
+const index2 = await manager.allocateIndex(); // 1
+const index3 = await manager.allocateIndex(); // 2
+
+// Bad: Random allocation
+const index = Math.floor(Math.random() * 131072); // Sparse bitstring, poor compression
+```
+
+### 2. Status List Size
+
+Choose appropriate status list sizes:
+
+```typescript
+// Small issuer (<10k credentials): Single list
+const singleList = {
+  id: 'https://issuer.example.com/status/1',
+  purpose: 'revocation',
+};
+
+// Medium issuer (10k-100k): List per purpose
+const revocationList = {
+  id: 'https://issuer.example.com/status/revocation/1',
+  purpose: 'revocation',
+};
+
+// Large issuer (>100k): Sharded lists
+const lists = [
+  'https://issuer.example.com/status/1',
+  'https://issuer.example.com/status/2',
+  'https://issuer.example.com/status/3',
+];
+```
+
+### 3. Verification Caching
+
+Cache status list fetches to reduce network overhead:
+
+```typescript
+const verifier = new CachedStatusListVerifier({
+  cache: {
+    ttl: 300, // 5 min for high-security
+    // ttl: 3600, // 1 hour for lower-security
+    maxSize: 100,
+  },
+});
+```
+
+### 4. Error Handling
+
+Handle status checking failures gracefully:
+
+```typescript
+try {
+  const result = await verifyDelegation({
+    credential: delegation,
+    checkStatus: true,
+  });
+
+  if (!result.verified) {
+    if (result.statusRevoked) {
+      throw new Error('Credential revoked');
+    }
+    throw new Error(`Verification failed: ${result.error}`);
+  }
+} catch (error) {
+  if (error.code === 'STATUS_LIST_UNAVAILABLE') {
+    // Status list endpoint down
+    // Decision: Accept credential or reject?
+    logger.warn('Status list unavailable, allowing credential');
+  } else {
+    throw error;
+  }
+}
+```
+
+### 5. Monitoring
+
+Monitor status list health:
+
+```typescript
+const metrics = await manager.getMetrics();
+
+console.log({
+  totalCredentials: metrics.allocatedIndexes,
+  revokedCredentials: metrics.revokedCount,
+  revocationRate: metrics.revokedCount / metrics.allocatedIndexes,
+  listSizeBytes: metrics.compressedSize,
+  compressionRatio: metrics.uncompressedSize / metrics.compressedSize,
+});
+
+// Alert if revocation rate is suspiciously high
+if (metrics.revocationRate > 0.5) {
+  logger.alert('High revocation rate detected!');
+}
+```
+
+## Complete Working Example
+
+```typescript
+import {
+  StatusList2021Manager,
+  InMemoryStatusListStorage,
+  DelegationIssuer,
+  verifyDelegation,
+} from '@kya-os/mcp-i-core';
+
+async function main() {
+  // 1. Setup issuer
+  const issuerDid = 'did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK';
+  const statusListUrl = 'https://issuer.example.com/status/1';
+
+  // 2. Create status list manager
+  const storage = new InMemoryStatusListStorage();
+  const statusListManager = new StatusList2021Manager({
+    issuerDid,
+    statusListUrl,
+    storage,
+  });
+
+  // 3. Create status list
+  const statusListVC = await statusListManager.createStatusList({
+    id: statusListUrl,
+    purpose: 'revocation',
+  });
+  console.log('✓ Status list created');
+
+  // 4. Setup delegation issuer
+  const issuer = new DelegationIssuer({
+    issuerDid,
+    privateKeyJwk: issuerPrivateKey,
+  });
+
+  // 5. Issue delegation with status
+  const statusListIndex = await statusListManager.allocateIndex();
+  const delegation = await issuer.issue({
+    subjectDid: 'did:key:z6MkrWXJPkxPCuQF7RqeKZFdZqBXz3oCG7PUty5dXLKGzELj',
+    constraints: {
+      scope: {
+        allowedTools: ['read_file'],
+        allowedResources: ['/documents/*'],
+      },
+    },
+    credentialStatus: {
+      id: `${statusListUrl}#${statusListIndex}`,
+      type: 'StatusList2021Entry',
+      statusPurpose: 'revocation',
+      statusListIndex: statusListIndex.toString(),
+      statusListCredential: statusListUrl,
+    },
+  });
+  console.log('✓ Delegation issued with status index:', statusListIndex);
+
+  // 6. Verify delegation (should pass)
+  let result = await verifyDelegation({
+    credential: delegation,
+    checkStatus: true,
+    statusListFetcher: async (url) => {
+      // In production, this would be an HTTP fetch
+      return statusListVC;
+    },
+  });
+  console.log('✓ Verification passed:', result.verified);
+
+  // 7. Revoke credential
+  await statusListManager.revokeCredential(statusListIndex);
+  console.log('✓ Credential revoked');
+
+  // 8. Verify again (should fail)
+  result = await verifyDelegation({
+    credential: delegation,
+    checkStatus: true,
+    statusListFetcher: async (url) => {
+      return await statusListManager.getStatusList(statusListUrl);
+    },
+  });
+  console.log('✗ Verification failed (revoked):', !result.verified);
+  console.log('  Status revoked:', result.statusRevoked);
+}
+
+main().catch(console.error);
+```
+
+## References
+
+- [W3C StatusList2021 Specification](https://www.w3.org/TR/vc-status-list-2021/)
+- [Verifiable Credentials Data Model](https://www.w3.org/TR/vc-data-model/)
+- [Privacy Considerations for StatusList2021](https://www.w3.org/TR/vc-status-list-2021/#privacy-considerations)
+- [MCP-I Delegation Guide](./W3C_VC_DELEGATION_GUIDE.md)
+
+## Next Steps
+
+1. Read the [W3C VC Delegation Guide](./W3C_VC_DELEGATION_GUIDE.md) to understand delegation credentials
+2. Review the [Compliance Matrix](./COMPLIANCE_MATRIX.md) for schema validation
+3. Explore the [API Reference](./API_REFERENCE.md) for detailed API documentation