Vault Connectors

The Vault subsystem provides secure storage and management of sensitive information such as API keys, passwords, tokens, and other secrets. It ensures encrypted storage and controlled access to confidential data.

Available Connectors

JSONFileVault

Role: File-based secure vault connector
Summary: Provides encrypted local file storage for secrets using JSON format. Suitable for development environments and single-node deployments requiring basic secret management.

Setting	Type	Required	Default	Description
file	string	No	~/.smyth/vault.json	Path to the vault file
shared	string	No	"default"	Shared team name for cross-team secret access

Example Configuration:

import { SRE } from '@smythos/sre';

SRE.init({
    Vault: {
        Connector: 'JSONFileVault',
        Settings: {
            file: './secrets/vault.json',
            shared: 'production',
        },
    },
});
Copy

vault.json research path: The JSONFileVault connector will search for the vault.json file in the following order:

1. The path specified in the file setting
2. The .smyth/vault.json file
3. The .smyth/vault/vault.json file
4. The .smyth/.sre/vault.json file
5. The ~/.smyth/vault.json file
6. The ~/.smyth/vault/vault.json file
7. The ~/.smyth/.sre/vault.json file

The search paths and the used path are visible in SRE logs in case you need to debug the vault file search.

Use Cases:

• Development and testing environments
• Single-node applications
• Simple secret management requirements
• Local development workflows
• Small teams with basic security needs

Security Notes:

• Vault file is encrypted using AES-256
• Keep encryption key secure and separate from vault file
• Use proper file permissions (600) for vault and key files
• Consider using environment variables for sensitive paths

---

SecretsManager

Role: AWS Secrets Manager connector
Summary: Provides integration with AWS Secrets Manager for enterprise-grade secret storage with automatic rotation, fine-grained access control, and audit logging.

Setting	Type	Required	Default	Description
region	string	Yes	-	AWS region where secrets are stored
awsAccessKeyId	string	No	-	AWS access key ID (can use IAM roles instead)
awsSecretAccessKey	string	No	-	AWS secret access key (can use IAM roles instead)

Example Configuration:

import { SRE } from '@smythos/sre';

SRE.init({
    Vault: {
        Connector: 'SecretsManager',
        Settings: {
            region: 'us-east-1',
            awsAccessKeyId: process.env.AWS_ACCESS_KEY_ID,
            awsSecretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
        },
    },
});
Copy

Use Cases:

• Production environments requiring enterprise security
• Multi-region deployments
• Applications with compliance requirements
• Automatic secret rotation needs
• Integration with AWS ecosystem

Security Features:

• Automatic encryption at rest using AWS KMS
• Fine-grained IAM access control
• Audit logging through CloudTrail
• Automatic secret rotation capabilities
• Cross-region replication support

---

NullVault

Role: No-operation vault connector
Summary: Provides a null implementation that discards all vault operations. Used for testing or when secret management is handled externally.

Setting	Type	Required	Default	Description
No specific settings	any	No	-	NullVault accepts any settings object

Example Configuration:

import { SRE } from '@smythos/sre';

SRE.init({
    Vault: {
        Connector: 'NullVault',
        Settings: {},
    },
});
Copy

Use Cases:

• Testing environments
• Development with external secret management
• Applications using environment variables only
• Debugging vault-related issues

Vault Operations

All vault connectors support these standard operations:

Operation	Description
get(keyId)	Retrieve a secret value
set(keyId, value)	Store a secret value
delete(keyId)	Remove a secret
exists(keyId)	Check if secret exists
list()	List all available secrets

Security Best Practices

General Guidelines

• Never store secrets in code or configuration files
• Use environment variables for connector credentials
• Implement proper access controls and permissions
• Regular audit and rotate secrets
• Use separate vaults for different environments

JSONFileVault Security

• Store vault files outside of version control
• Use strong encryption keys (256-bit minimum)
• Set restrictive file permissions (600)
• Regular backup encrypted vault files
• Consider using hardware security modules for keys

SecretsManager Security

• Use IAM roles instead of access keys when possible
• Implement least-privilege access policies
• Enable CloudTrail for audit logging
• Use KMS customer-managed keys for encryption
• Implement secret rotation policies

Integration Examples

Environment Variable Fallback

import { SRE } from '@smythos/sre';

SRE.init({
    Vault: {
        Connector: 'JSONFileVault',
        Settings: {
            file: process.env.VAULT_PATH || './.smyth/vault.json',
            fileKey: process.env.VAULT_KEY_PATH,
        },
    },
});
Copy

Multi-Environment Setup

import { SRE } from '@smythos/sre';

// Development
SRE.init({
    Vault: {
        Connector: 'JSONFileVault',
        Settings: {
            shared: 'development',
        },
    },
});

// Production
SRE.init({
    Vault: {
        Connector: 'SecretsManager',
        Settings: {
            region: 'us-east-1',
        },
    },
});
Copy