@jezweb/oauth-token-manager 0.1.0

package/README.md

@@ -0,0 +1,184 @@
+# @jezweb/oauth-token-manager
+
+OAuth token management for Cloudflare Workers. Store, refresh, and retrieve tokens for downstream API access.
+
+## The Problem
+
+When your application needs to call APIs on behalf of users (Google Calendar, GitHub, Xero, etc.), you need to:
+
+1. **Store** OAuth tokens securely (encrypted at rest)
+2. **Refresh** expired tokens automatically
+3. **Retrieve** valid tokens for API calls
+4. **Handle** errors gracefully (expired, revoked, insufficient scopes)
+
+Most auth libraries focus on **identity** ("who is this user?") not **API access** ("act on their behalf"). This package fills that gap.
+
+## Installation
+
+```bash
+npm install @jezweb/oauth-token-manager
+```
+
+## Quick Start
+
+```typescript
+import { TokenManager, KVStorage } from '@jezweb/oauth-token-manager';
+
+// Initialize
+const tokens = new TokenManager({
+  storage: new KVStorage({
+    namespace: env.TOKEN_KV,
+    encryptionKey: env.TOKEN_ENCRYPTION_KEY,
+  }),
+  providers: {
+    google: {
+      clientId: env.GOOGLE_CLIENT_ID,
+      clientSecret: env.GOOGLE_CLIENT_SECRET,
+    },
+  },
+});
+
+// Store token after OAuth callback
+await tokens.store({
+  userId: 'user-123',
+  provider: 'google',
+  accessToken: 'ya29.xxx',
+  refreshToken: '1//xxx',
+  expiresAt: Date.now() + 3600000,
+  scopes: ['https://www.googleapis.com/auth/calendar'],
+});
+
+// Get valid token (auto-refreshes if expired)
+const { accessToken } = await tokens.get({
+  userId: 'user-123',
+  provider: 'google',
+});
+
+// Use token for API call
+const response = await fetch('https://www.googleapis.com/calendar/v3/calendars', {
+  headers: { Authorization: `Bearer ${accessToken}` },
+});
+```
+
+## Features
+
+- **Encrypted storage** - Tokens encrypted at rest using AES-256-GCM
+- **Automatic refresh** - Tokens refreshed before expiry (5 min buffer by default)
+- **Scope validation** - Verify required scopes before returning tokens
+- **Built-in providers** - Google, Microsoft, GitHub out of the box
+- **Cloudflare-native** - Built specifically for Workers + KV
+- **Clear errors** - Typed errors guide recovery actions
+
+## API
+
+### `TokenManager`
+
+Main class for token management.
+
+```typescript
+const tokens = new TokenManager({
+  storage: TokenStorage,        // KVStorage or custom (handles encryption)
+  providers: {                  // Provider configs for refresh
+    google?: ProviderConfig,
+    microsoft?: ProviderConfig,
+    github?: ProviderConfig,
+  },
+  defaultRefreshBuffer?: number, // ms before expiry to refresh (default: 5 min)
+});
+```
+
+#### Methods
+
+| Method | Description |
+|--------|-------------|
+| `store(options)` | Store a new token or update existing |
+| `get(options)` | Get valid token (auto-refreshes) |
+| `list(options)` | List connected providers for a user |
+| `revoke(options)` | Delete a token |
+| `has(userId, provider)` | Check if token exists |
+
+### Error Types
+
+| Error | Meaning | Recovery |
+|-------|---------|----------|
+| `TokenNotFoundError` | No token for user/provider | Redirect to OAuth |
+| `TokenExpiredError` | Token expired, refresh failed | Redirect to OAuth |
+| `InsufficientScopesError` | Missing required scopes | Redirect to OAuth with incremental consent |
+| `ProviderNotConfiguredError` | Provider not in config | Add provider config |
+
+## Supported Providers
+
+| Provider | Refresh Support | Token Lifetime | Notes |
+|----------|-----------------|----------------|-------|
+| Google | ✅ Yes | ~1 hour | Requires `access_type=offline` |
+| Microsoft | ✅ Yes | ~1 hour | Token rotation by default |
+| GitHub | ❌ No | Never expires | Tokens valid until revoked |
+
+## Storage Adapters
+
+### KV Storage (Recommended)
+
+```typescript
+import { KVStorage } from '@jezweb/oauth-token-manager/storage/kv';
+
+const storage = new KVStorage({
+  namespace: env.TOKEN_KV,
+  encryptionKey: env.TOKEN_ENCRYPTION_KEY,
+  keyPrefix: 'tokens', // optional, default: 'tokens'
+});
+```
+
+### D1 Storage (Coming Soon)
+
+D1 adapter for stronger consistency and complex queries.
+
+## Wrangler Setup
+
+```toml
+# wrangler.toml
+kv_namespaces = [
+  { binding = "TOKEN_KV", id = "your-kv-id" }
+]
+
+[vars]
+# Store encryption key as secret, not here!
+```
+
+```bash
+# Set encryption key (generate with: openssl rand -base64 32)
+echo "your-32-byte-key" | wrangler secret put TOKEN_ENCRYPTION_KEY
+```
+
+## Use Cases
+
+- **MCP Servers** - Call Google Calendar, GitHub, etc. on behalf of users
+- **CRM integrations** - Sync with external calendars, email
+- **Social media tools** - Post to Twitter, LinkedIn
+- **Accounting apps** - Connect to Xero, QuickBooks
+
+## Architecture
+
+This package handles **outbound** OAuth (your app calling external APIs).
+
+For **inbound** OAuth (clients authenticating to your app), use:
+- [`@cloudflare/workers-oauth-provider`](https://github.com/cloudflare/workers-oauth-provider)
+- [better-auth](https://better-auth.com)
+
+```
+┌─────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│ MCP Client  │────▶│   Your App      │────▶│  External API   │
+│ (Claude.ai) │     │                 │     │ (Google, etc)   │
+└─────────────┘     └─────────────────┘     └─────────────────┘
+       │                    │                       │
+       ▼                    ▼                       ▼
+  Inbound auth         Token Manager           External OAuth
+  (who is client?)     (this package)          (act on behalf)
+```
+
+## Security
+
+See [SECURITY.md](./SECURITY.md) for security considerations.
+
+## License
+
+MIT © [Jezweb](https://jezweb.com.au)

package/SECURITY.md

@@ -0,0 +1,162 @@
+# Security Considerations
+
+This document describes the security model of `@jezweb/oauth-token-manager`.
+
+## Token Encryption
+
+### Algorithm
+
+- **Encryption**: AES-256-GCM (Galois/Counter Mode)
+- **Key Derivation**: PBKDF2 with SHA-256, 100,000 iterations
+- **IV**: Random 12 bytes per encryption
+- **Salt**: Random 16 bytes per encryption
+
+### What's Encrypted
+
+| Field | Encrypted | Reason |
+|-------|-----------|--------|
+| `accessToken` | ✅ Yes | Sensitive credential |
+| `refreshToken` | ✅ Yes | Sensitive credential |
+| `userId` | ❌ No | Needed for lookup |
+| `provider` | ❌ No | Needed for lookup |
+| `scopes` | ❌ No | Not sensitive |
+| `expiresAt` | ❌ No | Useful for auditing |
+| `createdAt` | ❌ No | Useful for auditing |
+| `updatedAt` | ❌ No | Useful for auditing |
+
+### Security Properties
+
+1. **Confidentiality**: Tokens cannot be read without the encryption key
+2. **Integrity**: GCM authentication tag detects tampering
+3. **Forward secrecy**: Each encryption uses a unique salt + IV
+4. **No key exposure**: Encryption key never stored, only used
+
+## Encryption Key Management
+
+### Requirements
+
+- **Length**: 32+ bytes recommended (256 bits)
+- **Randomness**: Use cryptographically secure random generation
+- **Storage**: Store as Wrangler secret, never in code or env vars
+
+### Generating a Key
+
+```bash
+# Generate a secure key
+openssl rand -base64 32
+
+# Store as Wrangler secret
+echo "your-key" | wrangler secret put TOKEN_ENCRYPTION_KEY
+```
+
+### Key Rotation
+
+Key rotation is NOT currently supported. If you need to rotate:
+
+1. Deploy new version with new key
+2. Users must re-authenticate to get new tokens
+3. Old tokens become unreadable
+
+Future versions may support key rotation with re-encryption.
+
+## Storage Security
+
+### KV Storage
+
+- Tokens stored with user-specific keys: `tokens:{userId}:{provider}`
+- Index stored separately: `token-index:{userId}`
+- No cross-user data access possible with correct key structure
+
+### Access Control
+
+- Your Worker has full access to the KV namespace
+- Implement authorization in your Worker to control which users can access which tokens
+- Never expose TokenManager methods directly to untrusted input
+
+## Provider Credentials
+
+### Storage
+
+- Provider `clientId` and `clientSecret` should be stored as Wrangler secrets
+- Never hardcode credentials in source code
+- Use environment variables via Wrangler bindings
+
+### Exposure Risk
+
+If provider credentials are compromised:
+
+1. Attacker could refresh tokens (if they also have refresh tokens)
+2. Attacker could NOT decrypt stored tokens without encryption key
+3. Revoke compromised credentials immediately in provider console
+
+## Attack Vectors
+
+### Storage Breach
+
+If KV storage is compromised:
+
+| Data Exposed | Risk | Mitigation |
+|--------------|------|------------|
+| Encrypted tokens | Low | Cannot decrypt without key |
+| User IDs | Medium | Consider hashing user IDs |
+| Scopes | Low | Not sensitive |
+| Timestamps | Low | Audit trail only |
+
+### Encryption Key Breach
+
+If encryption key is compromised:
+
+| Risk | Impact |
+|------|--------|
+| Decrypt all tokens | High - full API access |
+| Impersonate users | High - act as any user |
+
+**Mitigation**: Rotate key immediately, invalidate all tokens.
+
+### Provider Token Theft
+
+If decrypted tokens are stolen:
+
+| Token Type | Risk | Mitigation |
+|------------|------|------------|
+| Access token | Time-limited (~1h) | Short expiry |
+| Refresh token | Long-lived | Revoke at provider |
+
+## Best Practices
+
+### Do
+
+- ✅ Use strong encryption keys (32+ bytes, random)
+- ✅ Store encryption key as Wrangler secret
+- ✅ Store provider credentials as secrets
+- ✅ Validate user authorization before token access
+- ✅ Log token access for audit (without logging tokens)
+- ✅ Monitor for unusual access patterns
+
+### Don't
+
+- ❌ Log tokens or encryption keys
+- ❌ Include tokens in error messages
+- ❌ Store encryption key in source code
+- ❌ Use predictable encryption keys
+- ❌ Skip user authorization checks
+
+## Reporting Vulnerabilities
+
+If you discover a security vulnerability:
+
+1. **Do not** open a public GitHub issue
+2. Email security concerns to jeremy@jezweb.net
+3. Include steps to reproduce
+4. Allow 90 days for fix before disclosure
+
+## Compliance
+
+This package:
+
+- Uses industry-standard encryption (AES-256-GCM)
+- Does not transmit tokens to third parties
+- Does not store encryption keys
+- Provides audit trail via timestamps
+
+For specific compliance requirements (GDPR, SOC2, etc.), consult your compliance team about overall system architecture.

package/dist/crypto.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Cryptographic utilities for token encryption at rest
+ *
+ * Uses Web Crypto API (available in Cloudflare Workers, browsers, Node 18+)
+ * Algorithm: AES-256-GCM (authenticated encryption)
+ *
+ * Security properties:
+ * - Confidentiality: Tokens are encrypted and unreadable without the key
+ * - Integrity: Tampering with ciphertext is detected (GCM auth tag)
+ * - Key derivation: PBKDF2 derives strong key from your secret
+ * - Random IVs: Same plaintext produces different ciphertext each time
+ */
+/**
+ * Encrypt plaintext using AES-256-GCM
+ *
+ * Output format: base64(salt + iv + ciphertext + authTag)
+ * - salt: 16 bytes (for key derivation)
+ * - iv: 12 bytes (initialization vector)
+ * - ciphertext: variable length
+ * - authTag: 16 bytes (included in ciphertext by Web Crypto)
+ *
+ * @param plaintext - Data to encrypt
+ * @param encryptionKey - Secret key/password for encryption
+ * @returns Base64-encoded encrypted data
+ */
+export declare function encrypt(plaintext: string, encryptionKey: string): Promise<string>;
+/**
+ * Decrypt data encrypted with encrypt()
+ *
+ * @param encryptedData - Base64-encoded encrypted data
+ * @param encryptionKey - Secret key/password used for encryption
+ * @returns Decrypted plaintext
+ */
+export declare function decrypt(encryptedData: string, encryptionKey: string): Promise<string>;
+/**
+ * Encrypt an object as JSON
+ */
+export declare function encryptObject<T>(obj: T, encryptionKey: string): Promise<string>;
+/**
+ * Decrypt JSON back to an object
+ */
+export declare function decryptObject<T>(encryptedData: string, encryptionKey: string): Promise<T>;
+//# sourceMappingURL=crypto.d.ts.map

package/dist/crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA0CH;;;;;;;;;;;;GAYG;AACH,wBAAsB,OAAO,CAC3B,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,MAAM,CAAC,CA8BjB;AAED;;;;;;GAMG;AACH,wBAAsB,OAAO,CAC3B,aAAa,EAAE,MAAM,EACrB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,MAAM,CAAC,CA0BjB;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,GAAG,EAAE,CAAC,EACN,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,MAAM,CAAC,CAEjB;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,aAAa,EAAE,MAAM,EACrB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,CAAC,CAAC,CAGZ"}

package/dist/crypto.js

@@ -0,0 +1,107 @@
+/**
+ * Cryptographic utilities for token encryption at rest
+ *
+ * Uses Web Crypto API (available in Cloudflare Workers, browsers, Node 18+)
+ * Algorithm: AES-256-GCM (authenticated encryption)
+ *
+ * Security properties:
+ * - Confidentiality: Tokens are encrypted and unreadable without the key
+ * - Integrity: Tampering with ciphertext is detected (GCM auth tag)
+ * - Key derivation: PBKDF2 derives strong key from your secret
+ * - Random IVs: Same plaintext produces different ciphertext each time
+ */
+import { CryptoError } from './errors';
+// AES-GCM parameters
+const ALGORITHM = 'AES-GCM';
+const KEY_LENGTH = 256; // bits
+const IV_LENGTH = 12; // bytes (96 bits, recommended for GCM)
+const SALT_LENGTH = 16; // bytes
+const PBKDF2_ITERATIONS = 100000;
+/**
+ * Derive a cryptographic key from a password/secret using PBKDF2
+ */
+async function deriveKey(secret, salt) {
+    // Import the secret as a key for PBKDF2
+    const keyMaterial = await crypto.subtle.importKey('raw', new TextEncoder().encode(secret), 'PBKDF2', false, ['deriveKey']);
+    // Derive AES key using PBKDF2
+    return crypto.subtle.deriveKey({
+        name: 'PBKDF2',
+        salt,
+        iterations: PBKDF2_ITERATIONS,
+        hash: 'SHA-256',
+    }, keyMaterial, { name: ALGORITHM, length: KEY_LENGTH }, false, ['encrypt', 'decrypt']);
+}
+/**
+ * Encrypt plaintext using AES-256-GCM
+ *
+ * Output format: base64(salt + iv + ciphertext + authTag)
+ * - salt: 16 bytes (for key derivation)
+ * - iv: 12 bytes (initialization vector)
+ * - ciphertext: variable length
+ * - authTag: 16 bytes (included in ciphertext by Web Crypto)
+ *
+ * @param plaintext - Data to encrypt
+ * @param encryptionKey - Secret key/password for encryption
+ * @returns Base64-encoded encrypted data
+ */
+export async function encrypt(plaintext, encryptionKey) {
+    try {
+        // Generate random salt and IV
+        const salt = crypto.getRandomValues(new Uint8Array(SALT_LENGTH));
+        const iv = crypto.getRandomValues(new Uint8Array(IV_LENGTH));
+        // Derive key from secret
+        const key = await deriveKey(encryptionKey, salt);
+        // Encrypt the data
+        const encoded = new TextEncoder().encode(plaintext);
+        const ciphertext = await crypto.subtle.encrypt({ name: ALGORITHM, iv }, key, encoded);
+        // Combine salt + iv + ciphertext into single buffer
+        const combined = new Uint8Array(salt.length + iv.length + ciphertext.byteLength);
+        combined.set(salt, 0);
+        combined.set(iv, salt.length);
+        combined.set(new Uint8Array(ciphertext), salt.length + iv.length);
+        // Return as base64
+        return btoa(String.fromCharCode(...combined));
+    }
+    catch (error) {
+        throw new CryptoError('encrypt', error instanceof Error ? error : undefined);
+    }
+}
+/**
+ * Decrypt data encrypted with encrypt()
+ *
+ * @param encryptedData - Base64-encoded encrypted data
+ * @param encryptionKey - Secret key/password used for encryption
+ * @returns Decrypted plaintext
+ */
+export async function decrypt(encryptedData, encryptionKey) {
+    try {
+        // Decode base64
+        const combined = Uint8Array.from(atob(encryptedData), (c) => c.charCodeAt(0));
+        // Extract salt, iv, and ciphertext
+        const salt = combined.slice(0, SALT_LENGTH);
+        const iv = combined.slice(SALT_LENGTH, SALT_LENGTH + IV_LENGTH);
+        const ciphertext = combined.slice(SALT_LENGTH + IV_LENGTH);
+        // Derive key from secret
+        const key = await deriveKey(encryptionKey, salt);
+        // Decrypt the data
+        const decrypted = await crypto.subtle.decrypt({ name: ALGORITHM, iv }, key, ciphertext);
+        return new TextDecoder().decode(decrypted);
+    }
+    catch (error) {
+        throw new CryptoError('decrypt', error instanceof Error ? error : undefined);
+    }
+}
+/**
+ * Encrypt an object as JSON
+ */
+export async function encryptObject(obj, encryptionKey) {
+    return encrypt(JSON.stringify(obj), encryptionKey);
+}
+/**
+ * Decrypt JSON back to an object
+ */
+export async function decryptObject(encryptedData, encryptionKey) {
+    const json = await decrypt(encryptedData, encryptionKey);
+    return JSON.parse(json);
+}
+//# sourceMappingURL=crypto.js.map

package/dist/crypto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.js","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Custom error types for OAuth Token Manager
+ *
+ * These errors provide clear, actionable information about what went wrong
+ * and what the application should do to recover.
+ */
+/**
+ * Base error class for all token manager errors
+ */
+export declare class TokenManagerError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/**
+ * Token not found for the given user and provider
+ *
+ * Recovery: Redirect user to OAuth flow to connect this provider
+ */
+export declare class TokenNotFoundError extends TokenManagerError {
+    readonly userId: string;
+    readonly provider: string;
+    constructor(userId: string, provider: string);
+}
+/**
+ * Token has expired and refresh failed or no refresh token available
+ *
+ * Recovery: Redirect user to OAuth flow to re-authenticate
+ */
+export declare class TokenExpiredError extends TokenManagerError {
+    readonly userId: string;
+    readonly provider: string;
+    readonly reason: 'no_refresh_token' | 'refresh_failed' | 'refresh_token_expired';
+    constructor(userId: string, provider: string, reason: 'no_refresh_token' | 'refresh_failed' | 'refresh_token_expired');
+}
+/**
+ * Token exists but doesn't have the required scopes
+ *
+ * Recovery: Redirect user to OAuth flow with incremental consent for missing scopes
+ */
+export declare class InsufficientScopesError extends TokenManagerError {
+    readonly userId: string;
+    readonly provider: string;
+    readonly requiredScopes: string[];
+    readonly grantedScopes: string[];
+    constructor(userId: string, provider: string, requiredScopes: string[], grantedScopes: string[]);
+    get missingScopes(): string[];
+}
+/**
+ * Provider is not configured in the token manager
+ *
+ * Recovery: Add provider configuration to TokenManager constructor
+ */
+export declare class ProviderNotConfiguredError extends TokenManagerError {
+    readonly provider: string;
+    constructor(provider: string);
+}
+/**
+ * Encryption/decryption failed
+ *
+ * Recovery: Check encryption key is correct and hasn't changed
+ */
+export declare class CryptoError extends TokenManagerError {
+    readonly cause?: Error | undefined;
+    constructor(operation: 'encrypt' | 'decrypt', cause?: Error | undefined);
+}
+/**
+ * Storage operation failed
+ *
+ * Recovery: Check storage backend (KV/D1) is available and configured correctly
+ */
+export declare class StorageError extends TokenManagerError {
+    readonly cause?: Error | undefined;
+    constructor(operation: 'get' | 'set' | 'delete' | 'list', cause?: Error | undefined);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;aAGxB,IAAI,EAAE,MAAM;gBAD5B,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM;CAK/B;AAED;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,iBAAiB;aAErC,MAAM,EAAE,MAAM;aACd,QAAQ,EAAE,MAAM;gBADhB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM;CAQnC;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,iBAAiB;aAEpC,MAAM,EAAE,MAAM;aACd,QAAQ,EAAE,MAAM;aAChB,MAAM,EAAE,kBAAkB,GAAG,gBAAgB,GAAG,uBAAuB;gBAFvE,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,kBAAkB,GAAG,gBAAgB,GAAG,uBAAuB;CAa1F;AAED;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,iBAAiB;aAE1C,MAAM,EAAE,MAAM;aACd,QAAQ,EAAE,MAAM;aAChB,cAAc,EAAE,MAAM,EAAE;aACxB,aAAa,EAAE,MAAM,EAAE;gBAHvB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,EAAE,EACxB,aAAa,EAAE,MAAM,EAAE;IAUzC,IAAI,aAAa,IAAI,MAAM,EAAE,CAE5B;CACF;AAED;;;;GAIG;AACH,qBAAa,0BAA2B,SAAQ,iBAAiB;aACnC,QAAQ,EAAE,MAAM;gBAAhB,QAAQ,EAAE,MAAM;CAO7C;AAED;;;;GAIG;AACH,qBAAa,WAAY,SAAQ,iBAAiB;aAG9B,KAAK,CAAC,EAAE,KAAK;gBAD7B,SAAS,EAAE,SAAS,GAAG,SAAS,EAChB,KAAK,CAAC,EAAE,KAAK,YAAA;CAQhC;AAED;;;;GAIG;AACH,qBAAa,YAAa,SAAQ,iBAAiB;aAG/B,KAAK,CAAC,EAAE,KAAK;gBAD7B,SAAS,EAAE,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,EAC5B,KAAK,CAAC,EAAE,KAAK,YAAA;CAQhC"}