@memberjunction/encryption 3.2.0 → 3.3.0

package/README.md

@@ -316,6 +316,93 @@ if (engine.IsEncrypted(someValue)) {
 engine.ClearCaches();
 ```
 
+## API Key Management
+
+The `EncryptionEngine` provides secure API key management for authentication scenarios like MCP servers, external integrations, and programmatic access.
+
+### Creating API Keys
+
+```typescript
+import { EncryptionEngine } from '@memberjunction/encryption';
+
+const result = await EncryptionEngine.Instance.CreateAPIKey({
+    userId: 'user-guid-here',
+    label: 'MCP Server Integration',
+    description: 'Used for Claude Desktop MCP connections',
+    expiresAt: new Date('2025-12-31') // Optional - omit for non-expiring keys
+}, contextUser);
+
+if (result.success) {
+    // CRITICAL: Save this key immediately - it cannot be recovered!
+    console.log('Your API Key:', result.rawKey);
+    console.log('API Key ID:', result.apiKeyId);
+} else {
+    console.error('Failed to create API key:', result.error);
+}
+```
+
+**Key Format**: `mj_sk_[64 hex characters]` (70 characters total)
+
+**Security**: Only the SHA-256 hash is stored in the database. The raw key is returned exactly once at creation time and cannot be recovered.
+
+### Validating API Keys
+
+```typescript
+const validation = await EncryptionEngine.Instance.ValidateAPIKey(
+    request.headers['x-api-key'],
+    systemUser
+);
+
+if (validation.isValid) {
+    // Use validation.user for authorized operations
+    console.log('Authenticated user:', validation.user.Name);
+    console.log('API Key ID:', validation.apiKeyId);
+} else {
+    throw new Error(validation.error);
+}
+```
+
+The validation method:
+- Checks key format
+- Looks up the hash in the CredentialEngine cache (fast!)
+- Verifies the key is active and not expired
+- Loads the associated user from the database
+- Updates `LastUsedAt` and logs usage
+
+### Other API Key Methods
+
+```typescript
+// Generate a key without storing it (for custom storage scenarios)
+const { raw, hash } = EncryptionEngine.Instance.GenerateAPIKey();
+
+// Hash a key for manual comparison
+const keyHash = EncryptionEngine.Instance.HashAPIKey(rawKey);
+
+// Validate key format before processing
+if (!EncryptionEngine.Instance.IsValidAPIKeyFormat(key)) {
+    throw new Error('Invalid API key format');
+}
+
+// Revoke an API key (permanently disables it)
+const revoked = await EncryptionEngine.Instance.RevokeAPIKey(apiKeyId, contextUser);
+```
+
+### API Key Database Schema
+
+The API key system uses these tables (part of MemberJunction core):
+
+**MJ: API Keys**
+- `ID` - Unique identifier
+- `Hash` - SHA-256 hash of the raw key
+- `UserID` - Associated user (operations execute with this user's permissions)
+- `Label` - Friendly name
+- `Status` - `Active` or `Revoked`
+- `ExpiresAt` - Optional expiration date
+- `LastUsedAt` - Automatically updated on each use
+
+**MJ: API Key Usage Logs**
+- Tracks API key usage for analytics and security monitoring
+
 ## Encrypted Value Format
 
 Encrypted values are stored as self-describing strings:

package/dist/index.d.ts

@@ -51,6 +51,11 @@
  * - Random IVs for each encryption operation
  * - Cached key material has configurable TTL
  *
+ * ## API Key Management
+ *
+ * API key functionality has been moved to the `@memberjunction/api-keys` package.
+ * Use that package for API key generation, validation, and scope-based authorization.
+ *
  * @module @memberjunction/encryption
  * @packageDocumentation
  */

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAGH,OAAO,EACH,yBAAyB,EACzB,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,2BAA2B,EAC3B,2BAA2B,EAC9B,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAGpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGtD,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAGtE,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAG5E,OAAO,EAAE,yBAAyB,EAAE,MAAM,qCAAqC,CAAC;AAChF,OAAO,EAAE,2BAA2B,EAAE,MAAM,uCAAuC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAGH,OAAO,EACH,yBAAyB,EACzB,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,2BAA2B,EAC3B,2BAA2B,EAC9B,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAGpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGtD,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAGtE,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAG5E,OAAO,EAAE,yBAAyB,EAAE,MAAM,qCAAqC,CAAC;AAChF,OAAO,EAAE,2BAA2B,EAAE,MAAM,uCAAuC,CAAC"}

package/dist/index.js

@@ -52,6 +52,11 @@
  * - Random IVs for each encryption operation
  * - Cached key material has configurable TTL
  *
+ * ## API Key Management
+ *
+ * API key functionality has been moved to the `@memberjunction/api-keys` package.
+ * Use that package for API key generation, validation, and scope-based authorization.
+ *
  * @module @memberjunction/encryption
  * @packageDocumentation
  */

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;;;AAaH,sCAAsC;AACtC,qEAAoE;AAA3D,kIAAA,uBAAuB,OAAA;AAEhC,yBAAyB;AACzB,uDAAsD;AAA7C,oHAAA,gBAAgB,OAAA;AAEzB,gCAAgC;AAChC,+DAA8D;AAArD,kHAAA,eAAe,OAAA;AACxB,uEAAsE;AAA7D,0HAAA,mBAAmB,OAAA;AAE5B,6DAA6D;AAC7D,+DAA8D;AAArD,kHAAA,eAAe,OAAA;AACxB,6EAA4E;AAAnE,gIAAA,sBAAsB,OAAA;AAE/B,gDAAgD;AAChD,iFAAgF;AAAvE,sIAAA,yBAAyB,OAAA;AAClC,qFAAoF;AAA3E,0IAAA,2BAA2B,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;;;AAaH,sCAAsC;AACtC,qEAAoE;AAA3D,kIAAA,uBAAuB,OAAA;AAEhC,yBAAyB;AACzB,uDAAsD;AAA7C,oHAAA,gBAAgB,OAAA;AAEzB,gCAAgC;AAChC,+DAA8D;AAArD,kHAAA,eAAe,OAAA;AACxB,uEAAsE;AAA7D,0HAAA,mBAAmB,OAAA;AAE5B,6DAA6D;AAC7D,+DAA8D;AAArD,kHAAA,eAAe,OAAA;AACxB,6EAA4E;AAAnE,gIAAA,sBAAsB,OAAA;AAE/B,gDAAgD;AAChD,iFAAgF;AAAvE,sIAAA,yBAAyB,OAAA;AAClC,qFAAoF;AAA3E,0IAAA,2BAA2B,OAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memberjunction/encryption",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "MemberJunction: Field-level encryption engine with pluggable key sources. Server-side only - provides AES-256-GCM/CBC encryption with environment variable, config file, AWS KMS, and Azure Key Vault key sources.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -23,10 +23,11 @@
     "typescript": "^5.4.5"
   },
   "dependencies": {
-    "@memberjunction/global": "3.2.0",
-    "@memberjunction/core": "3.2.0",
-    "@memberjunction/core-entities": "3.2.0",
-    "@memberjunction/actions-base": "3.2.0",
+    "@memberjunction/global": "3.3.0",
+    "@memberjunction/core": "3.3.0",
+    "@memberjunction/core-entities": "3.3.0",
+    "@memberjunction/credentials": "3.3.0",
+    "@memberjunction/actions-base": "3.3.0",
     "cosmiconfig": "^9.0.0"
   },
   "optionalDependencies": {