@memberjunction/credentials

Secure credential management engine for MemberJunction. Provides centralized storage, retrieval, validation, and audit logging of credentials with automatic field-level encryption and JSON Schema validation.

Overview

The @memberjunction/credentials package manages the full credential lifecycle: storing encrypted values, resolving credentials by name or ID, validating against JSON Schema constraints, and logging every access for audit compliance.

graph TD
    A["CredentialEngine<br/>(Singleton)"] --> B["Credential Types<br/>(Schema Definitions)"]
    A --> C["Credentials<br/>(Encrypted Values)"]
    A --> D["Credential Categories<br/>(Organization)"]
    A --> E["Audit Log<br/>(Access Tracking)"]
    A --> F["Ajv Validator<br/>(JSON Schema)"]

    G["Consumer Code"] --> A
    G -->|"getCredential()"| H["ResolvedCredential<T>"]
    G -->|"storeCredential()"| C
    G -->|"validateCredential()"| I["ValidationResult"]

    style A fill:#2d6a9f,stroke:#1a4971,color:#fff
    style B fill:#7c5295,stroke:#563a6b,color:#fff
    style C fill:#2d8659,stroke:#1a5c3a,color:#fff
    style D fill:#b8762f,stroke:#8a5722,color:#fff
    style E fill:#b8762f,stroke:#8a5722,color:#fff
    style F fill:#7c5295,stroke:#563a6b,color:#fff
    style H fill:#2d8659,stroke:#1a5c3a,color:#fff
    style I fill:#2d8659,stroke:#1a5c3a,color:#fff

Installation

npm install @memberjunction/credentials

Quick Start

import { CredentialEngine, APIKeyCredentialValues } from '@memberjunction/credentials';

// Initialize at application startup
await CredentialEngine.Instance.Config(false, contextUser);

// Retrieve a credential with typed values
const cred = await CredentialEngine.Instance.getCredential<APIKeyCredentialValues>(
  'OpenAI',
  { contextUser, subsystem: 'AIService' }
);

// Use the decrypted values
console.log(cred.values.apiKey); // Strongly typed as string

Credential Resolution

flowchart TD
    A["getCredential(name, options)"] --> B{directValues<br/>provided?}
    B -->|Yes| C["Return direct values<br/>source: request"]
    B -->|No| D{credentialId<br/>provided?}
    D -->|Yes| E["Lookup by ID"]
    D -->|No| F["Lookup by name"]
    E --> G["Parse & return values<br/>source: database"]
    F --> G
    G --> H["Log access to Audit Log"]
    H --> I["Update LastUsedAt"]

    style A fill:#2d6a9f,stroke:#1a4971,color:#fff
    style C fill:#2d8659,stroke:#1a5c3a,color:#fff
    style G fill:#2d8659,stroke:#1a5c3a,color:#fff
    style H fill:#b8762f,stroke:#8a5722,color:#fff

Resolution priority:

1. Direct values — directValues in options (bypasses database, useful for testing)
2. By ID — credentialId in options (specific credential lookup)
3. By name — The credentialName parameter (most common usage)

Pre-defined Credential Types

Type	Interface	Fields
API Key	APIKeyCredentialValues	apiKey
API Key with Endpoint	APIKeyWithEndpointCredentialValues	apiKey, endpoint
OAuth2 Client Credentials	OAuth2ClientCredentialValues	clientId, clientSecret, tokenUrl, scope
Basic Auth	BasicAuthCredentialValues	username, password
Azure Service Principal	AzureServicePrincipalCredentialValues	tenantId, clientId, clientSecret
AWS IAM	AWSIAMCredentialValues	accessKeyId, secretAccessKey, region
Database Connection	DatabaseConnectionCredentialValues	host, port, database, username, password
Twilio	TwilioCredentialValues	accountSid, authToken

Storing Credentials

const credential = await CredentialEngine.Instance.storeCredential(
  'API Key',                    // Credential type name
  'OpenAI Production',          // Credential name
  { apiKey: 'sk-...' },         // Values (encrypted on save)
  {
    isDefault: true,
    description: 'Production OpenAI API key',
    expiresAt: new Date('2025-12-31')
  },
  contextUser
);

JSON Schema Validation

The engine validates credential values against the FieldSchema defined on each Credential Type using Ajv. Supported constraints include required, const, enum, format, pattern, minLength/maxLength, and minimum/maximum.

Default and const values are auto-populated before validation, and validation errors produce clear, human-readable messages.

Audit Logging

Every credential operation (Decrypt, Create, Update, Validate) is logged to the Audit Logs entity with:

• User who performed the operation
• Subsystem that requested access
• Success or failure status
• Duration in milliseconds

Security

• Encryption at rest — The Values field uses MJ field-level encryption
• Audit trail — All access logged including failed attempts
• Access control — Entity-level permissions enforced via contextUser
• Expiration support — ExpiresAt field enforces credential rotation

Dependencies

Package	Purpose
@memberjunction/core	Base engine, metadata, entity system
@memberjunction/global	Global state management
@memberjunction/core-entities	Credential entity types
ajv	JSON Schema validation
ajv-formats	Format validators (uri, email, date)

License

ISC