Secrets Management
The secrets module provides a unified interface for retrieving sensitive values (credentials, API keys, tokens) from external backends and injecting them into the framework configuration at runtime. This keeps secrets out of source control and .env files in shared environments.
What It Does
- Resolves secrets from multiple provider backends (AWS, Vault, OpenBao, GitLab, Azure, env-file)
- Injects fetched secrets into
FrameworkConfigvia dot-notation key mappings - Caches all fetched secrets for the entire test runner invocation
- Enforces configurable fetch timeouts per provider
- Falls back to local
.envfile provider when no external backend is configured
Architecture
SecretsManager (orchestrator)
├── Registers one or more SecretsProvider implementations
├── Resolves which provider to use from config
├── Fetches secrets with timeout enforcement
├── Caches results (singleton per test run)
└── Injects values into FrameworkConfig via keyMappings
Providers:
├── aws — AWS Secrets Manager
├── vault — HashiCorp Vault (KV v1/v2)
├── openbao — OpenBao (KV v1/v2), shares the Vault implementation
├── gitlab — GitLab CI/CD Variables API
├── azure — Azure Key Vault
└── env-file — Local .env file fallbackConfiguration
environments.json
{
"environments": {
"dev": {
"database": {
"type": "postgresql",
"host": "db.example.com",
"port": 5432,
"database": "myapp",
"username": "",
"password": ""
},
"secrets": {
"provider": "aws",
"options": {
"region": "us-east-1",
"secretPrefix": "myapp/dev/"
},
"keyMappings": {
"db-username": "database.username",
"db-password": "database.password",
"api-key": "openapi.baseUrl"
},
"timeout": 10000
}
}
}
}playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
projects: [
{
name: 'integration',
testMatch: '**/integration/**/*.spec.ts',
use: {
secrets: {
provider: 'vault',
options: {
url: 'https://vault.example.com',
mountPath: 'secret/data/playwright',
},
keyMappings: {
'db-password': 'database.password',
'redis-password': 'redis.password',
},
timeout: 15000,
},
},
},
],
});Configuration Options
| Option | Type | Default | Description |
|---|---|---|---|
provider | string | — | Provider backend name: aws, vault, openbao, gitlab, azure, env-file |
options | object | — | Provider-specific options (see each provider below) |
keyMappings | Record<string, string> | — | Maps secret key → config field path (dot-notation) |
timeout | number | 10000 | Fetch timeout in ms for all secret operations |
Key Mappings
Key mappings define which secrets to fetch and where to inject them in the framework config. The key is the secret identifier in the backend, and the value is the dot-notation path in FrameworkConfig.
{
"keyMappings": {
"db-password": "database.password",
"db-username": "database.username",
"kafka-sasl-password": "kafka.sasl.password",
"redis-auth": "redis.password",
"api-token": "graphql.authToken"
}
}The target field must exist in the config object. If the path is invalid, a SecretsError with operation mapping is thrown.
Providers
AWS Secrets Manager
Retrieves secrets from AWS Secrets Manager using the AWS SDK.
Prerequisites
npm install @aws-sdk/client-secrets-managerAuthentication
Uses the standard AWS credential chain (environment variables, shared credentials file, IAM role, etc.):
| Method | Variables |
|---|---|
| Environment | AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN |
| Shared credentials | ~/.aws/credentials with profile |
| IAM Role | Automatic on EC2/ECS/Lambda |
| SSO | aws sso login then use profile |
Options
| Option | Type | Required | Description |
|---|---|---|---|
region | string | Yes | AWS region (e.g., us-east-1, eu-west-1) |
secretPrefix | string | No | Prefix prepended to all secret keys when fetching |
Configuration Example
{
"secrets": {
"provider": "aws",
"options": {
"region": "us-east-1",
"secretPrefix": "myapp/prod/"
},
"keyMappings": {
"db-credentials": "database.password"
}
}
}With secretPrefix: "myapp/prod/", a key mapping of "db-credentials" fetches the secret named myapp/prod/db-credentials from AWS.
Notes
- Only string secrets are supported (binary secrets throw an error)
- Secrets are fetched individually (no native batch API for arbitrary names)
- The SDK is loaded dynamically — the provider throws a clear error if the package is missing
HashiCorp Vault
Retrieves secrets from HashiCorp Vault via the HTTP API. Supports KV v1 and KV v2 secrets engines.
Prerequisites
A running Vault instance accessible over HTTPS. No additional npm packages required (uses native fetch, or node:https when TLS options are set).
Authentication
| Method | Configuration | Environment Variables |
|---|---|---|
| Token | options.token | VAULT_TOKEN |
| AppRole | options.roleId + options.secretId | VAULT_ROLE_ID + VAULT_SECRET_ID |
| Kubernetes | authMethod: "kubernetes" + role (JWT read from the pod's service-account token) | VAULT_AUTH_METHOD, VAULT_AUTH_ROLE, VAULT_JWT_PATH |
| JWT / OIDC | role + jwt or jwtPath | VAULT_AUTH_ROLE, VAULT_JWT / VAULT_JWT_PATH |
When authMethod is omitted it is inferred: a token wins, then AppRole (role_id + secret_id), then JWT (if a JWT or JWT path is set). Kubernetes must be selected explicitly. Auth methods mounted somewhere other than their default path (approle, kubernetes, jwt) need authMount.
AppRole, Kubernetes or JWT are recommended for CI/CD pipelines. Token-based auth is suitable for local development.
Options
Every option except kvVersion's default can also come from an environment variable; explicit options always win.
| Option | Type | Required | Env fallback | Description |
|---|---|---|---|---|
url | string | Yes | VAULT_ADDR | Server URL (e.g., https://vault.example.com) |
mountPath | string | Yes | VAULT_MOUNT_PATH | Path prefix after /v1/. For KV v2 include data (e.g., secret/data/playwright) |
kvVersion | 1 | 2 | No | VAULT_KV_VERSION | KV secrets engine version (default: 2) |
namespace | string | No | VAULT_NAMESPACE | Namespace, sent as X-Vault-Namespace |
authMethod | token | approle | kubernetes | jwt | No | VAULT_AUTH_METHOD | Auth method (inferred when omitted) |
authMount | string | No | VAULT_AUTH_MOUNT | Auth mount path, if not the default |
token | string | No | VAULT_TOKEN | Client token |
roleId | string | No | VAULT_ROLE_ID | AppRole role_id |
secretId | string | No | VAULT_SECRET_ID | AppRole secret_id |
role | string | No | VAULT_AUTH_ROLE | Role for Kubernetes / JWT login |
jwt | string | No | VAULT_JWT | JWT for Kubernetes / JWT login |
jwtPath | string | No | VAULT_JWT_PATH | File holding the JWT (Kubernetes default: /var/run/secrets/kubernetes.io/serviceaccount/token) |
caCert | string | No | VAULT_CACERT | PEM CA bundle file used to verify the server |
caPath | string | No | VAULT_CAPATH | Directory of PEM CA certificates (ignored if caCert is set) |
clientCert | string | No | VAULT_CLIENT_CERT | PEM client certificate for mutual TLS |
clientKey | string | No | VAULT_CLIENT_KEY | Unencrypted PEM client key for mutual TLS |
tlsServerName | string | No | VAULT_TLS_SERVER_NAME | SNI server name |
skipVerify | boolean | No | VAULT_SKIP_VERIFY | Disable certificate verification (local only, never in shared environments) |
Configuration Example
{
"secrets": {
"provider": "vault",
"options": {
"url": "https://vault.example.com",
"mountPath": "secret/data/playwright",
"namespace": "admin/team-qa",
"kvVersion": 2
},
"keyMappings": {
"db-password": "database.password",
"redis-password": "redis.password"
}
}
}Secret Resolution Logic
Each key is appended to mountPath (nested keys such as team/db-password keep their slashes). The provider then looks for the value in this order:
- A
valuefield in the secret data - A field matching the key name
- The first value in the data object
Notes
- Supports namespaces via the
X-Vault-Namespaceheader - Login (AppRole, Kubernetes, JWT) is performed lazily on first secret fetch, once per provider instance; concurrent fetches share the same login
- The token is cached for the lifetime of the provider instance (it is not renewed)
- Tokens, secret_ids, JWTs and client keys are never included in
SecretsErrordetails, and are replaced with[REDACTED]if the server echoes them back
OpenBao
Retrieves secrets from OpenBao, the Linux Foundation's open-source fork of HashiCorp Vault.
OpenBao's HTTP API is wire-compatible with Vault's for everything this provider uses: /v1 KV v1/v2 reads, the X-Vault-Token and X-Vault-Namespace headers, and the AppRole, Kubernetes and JWT login endpoints. The openbao provider therefore shares the Vault implementation, and every option, auth method, TLS setting and note in the HashiCorp Vault section applies unchanged. Only the provider name and the environment variables differ.
Environment Variables
Each option falls back to environment variables in this order, highest precedence first:
PW_OPENBAO_<NAME> → BAO_<NAME> → VAULT_<NAME>The framework's own PW_OPENBAO_* variables win over the bao CLI's BAO_* variables, which win over the VAULT_* names that OpenBao also accepts. Explicit options in environments.json or playwright.config.ts always win over all of them.
| Option | Environment variables |
|---|---|
url | PW_OPENBAO_ADDR, BAO_ADDR, VAULT_ADDR |
token | PW_OPENBAO_TOKEN, BAO_TOKEN, VAULT_TOKEN |
namespace | PW_OPENBAO_NAMESPACE, BAO_NAMESPACE, VAULT_NAMESPACE |
mountPath | PW_OPENBAO_MOUNT_PATH, BAO_MOUNT_PATH, VAULT_MOUNT_PATH |
kvVersion | PW_OPENBAO_KV_VERSION, BAO_KV_VERSION, VAULT_KV_VERSION |
authMethod / authMount | PW_OPENBAO_AUTH_METHOD, PW_OPENBAO_AUTH_MOUNT (+ BAO_* / VAULT_*) |
roleId / secretId | PW_OPENBAO_ROLE_ID, PW_OPENBAO_SECRET_ID (+ BAO_* / VAULT_*) |
role / jwt / jwtPath | PW_OPENBAO_AUTH_ROLE, PW_OPENBAO_JWT, PW_OPENBAO_JWT_PATH (+ BAO_* / VAULT_*) |
caCert / caPath | PW_OPENBAO_CACERT, PW_OPENBAO_CAPATH, BAO_CACERT, BAO_CAPATH (+ VAULT_*) |
clientCert / clientKey | PW_OPENBAO_CLIENT_CERT, PW_OPENBAO_CLIENT_KEY, BAO_CLIENT_CERT, BAO_CLIENT_KEY (+ VAULT_*) |
tlsServerName | PW_OPENBAO_TLS_SERVER_NAME, BAO_TLS_SERVER_NAME, VAULT_TLS_SERVER_NAME |
skipVerify | PW_OPENBAO_SKIP_VERIFY, BAO_SKIP_VERIFY, VAULT_SKIP_VERIFY |
Because the server URL can come from BAO_ADDR, url is optional for openbao; the provider raises a SecretsError naming the variables above if no URL or mount path is found.
Configuration Example
{
"secrets": {
"provider": "openbao",
"options": {
"url": "https://bao.example.com",
"mountPath": "secret/data/playwright",
"namespace": "team-qa"
},
"keyMappings": {
"db-password": "database.password",
"redis-password": "redis.password"
}
}
}With BAO_ADDR and BAO_TOKEN already exported (as for the bao CLI), only mountPath needs to be in options.
Kubernetes Example
{
"secrets": {
"provider": "openbao",
"options": {
"url": "https://bao.internal:8200",
"mountPath": "secret/data/playwright",
"authMethod": "kubernetes",
"role": "playwright-ci",
"caCert": "/etc/openbao/ca.pem"
},
"keyMappings": { "db-password": "database.password" }
}
}Notes
mountPathis the full path prefix after/v1/, so KV v2 needs thedatasegment (secret/data/...), as thebao kvCLI adds for you. A KV v2 response withoutdata.dataraises aSecretsErrorthat points atmountPath- Namespaces are sent with the
X-Vault-Namespaceheader, which OpenBao uses unchanged - OpenBao does not guarantee backwards compatibility of its API yet, even under
/v1; pin the server version in shared test environments
GitLab CI/CD Variables
Retrieves secrets from GitLab project CI/CD variables via the GitLab REST API.
Prerequisites
- A GitLab project with CI/CD variables configured
- A private token or
CI_JOB_TOKEN(automatically available in GitLab CI pipelines)
Authentication
| Method | Configuration | Environment Variables |
|---|---|---|
| Private Token | options.token | — |
| Job Token | — | CI_JOB_TOKEN (auto-set in GitLab CI) |
In GitLab CI pipelines, CI_JOB_TOKEN is automatically available and used as the fallback.
Options
| Option | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | GitLab project ID (numeric) or URL-encoded path |
apiUrl | string | Yes | GitLab API base URL (e.g., https://gitlab.com/api/v4) |
token | string | No | Private token. Falls back to CI_JOB_TOKEN env var |
Configuration Example
{
"secrets": {
"provider": "gitlab",
"options": {
"projectId": "12345678",
"apiUrl": "https://gitlab.com/api/v4",
"token": ""
},
"keyMappings": {
"DB_PASSWORD": "database.password",
"REDIS_PASSWORD": "redis.password"
}
}
}Notes
- Secret keys must match the exact CI/CD variable key name in GitLab
- Variables are fetched individually via the GitLab API
- Protected and masked variables are supported
- For self-hosted GitLab, update
apiUrlto your instance URL
Azure Key Vault
Retrieves secrets from Azure Key Vault using the Azure SDK with DefaultAzureCredential.
Prerequisites
npm install @azure/keyvault-secrets @azure/identityAuthentication
Uses DefaultAzureCredential from @azure/identity, which tries these methods in order:
| Method | Environment Variables |
|---|---|
| Environment | AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET |
| Managed Identity | Automatic on Azure VMs, App Service, Functions |
| Azure CLI | az login (local development) |
| Visual Studio Code | Azure Account extension |
Options
| Option | Type | Required | Description |
|---|---|---|---|
vaultUrl | string | Yes | Key Vault URL (e.g., https://my-vault.vault.azure.net) |
Configuration Example
{
"secrets": {
"provider": "azure",
"options": {
"vaultUrl": "https://my-vault.vault.azure.net"
},
"keyMappings": {
"db-password": "database.password",
"api-key": "openapi.baseUrl"
}
}
}Notes
- Only string secrets are supported (empty values throw an error)
- The SDK is loaded dynamically — the provider throws a clear error if packages are missing
- Secret names in Azure Key Vault use hyphens (not underscores):
my-secret-name
Env File (Local Fallback)
Reads secrets from local .env.{environment} files. This is the default provider when no external backend is configured. Intended for local development only.
Prerequisites
None — uses the built-in EnvLoader.
Options
| Option | Type | Required | Description |
|---|---|---|---|
projectRoot | string | No | Directory containing .env files (default: process.cwd()) |
environment | string | No | Environment name to load (default: local) |
Configuration Example
{
"secrets": {
"provider": "env-file",
"options": {
"environment": "dev"
},
"keyMappings": {
"PW_DB_PASSWORD": "database.password",
"PW_REDIS_PASSWORD": "redis.password"
}
}
}This reads from .env.dev and maps the specified keys into the framework config.
.env.dev Example
PW_DB_PASSWORD=my-local-password
PW_REDIS_PASSWORD=redis-secret
PW_API_KEY=sk-test-12345Notes
- The env file is loaded once and cached for the test run
- Keys must exist in the file — missing keys throw a
SecretsError - This provider is automatically used when no other provider is configured
Programmatic Usage
You can use the SecretsManager directly in custom fixtures or setup scripts:
import { SecretsManager, AwsSecretsProvider } from '@inluxc/propmaster';
const manager = new SecretsManager();
// Register a provider
manager.registerProvider(new AwsSecretsProvider({ region: 'us-east-1' }));
// Fetch a single secret
const password = await manager.getSecret('db-password', 'aws');
// Fetch multiple secrets
const secrets = await manager.getSecrets(
['db-password', 'api-key', 'redis-auth'],
'aws',
15000 // timeout in ms
);
// Resolve and inject into config
const resolvedConfig = await manager.resolve(frameworkConfig);Error Handling
All secrets errors use the SecretsError class with structured context:
| Operation | When |
|---|---|
resolve | Provider not registered or not found |
fetch | Secret retrieval failed (network, auth, missing key) |
timeout | Fetch exceeded the configured timeout |
mapping | Key mapping path is invalid (field doesn't exist in config) |
// Provider not found:
// SecretsError: aws/resolve — reason: Provider "aws" is not registered
// Fetch failure:
// SecretsError: vault/fetch [db-password] — reason: API returned 403: permission denied
// Timeout:
// SecretsError: aws/timeout [db-password] — timeoutMs: 10000
// Invalid mapping:
// SecretsError: aws/mapping [db-password] — invalidField: database.nonexistent, reason: Field "nonexistent" does not existProvider Comparison
| Provider | Auth Method | Best For | Dependencies |
|---|---|---|---|
aws | IAM / env credentials | AWS-hosted infrastructure | @aws-sdk/client-secrets-manager |
vault | Token / AppRole / Kubernetes / JWT | Multi-cloud, on-prem | None (native fetch) |
openbao | Token / AppRole / Kubernetes / JWT | Open-source Vault alternative, on-prem | None (native fetch) |
gitlab | Private token / Job token | GitLab CI/CD pipelines | None (native fetch) |
azure | DefaultAzureCredential | Azure-hosted infrastructure | @azure/keyvault-secrets, @azure/identity |
env-file | File system | Local development | None (built-in) |
Recommended Setup by Environment
| Environment | Provider | Notes |
|---|---|---|
| Local | env-file | Use .env.local with dummy/dev credentials |
| CI/CD (GitLab) | gitlab | Leverages CI_JOB_TOKEN automatically |
| CI/CD (GitHub) | env-file, vault or openbao | Map GitHub secrets to env vars, or use Vault/OpenBao JWT auth with the GitHub OIDC token |
| Staging/Prod (AWS) | aws | Use IAM roles for zero-config auth |
| Staging/Prod (Azure) | azure | Use Managed Identity for zero-config auth |
| Multi-cloud | vault or openbao | Central secrets management across providers |
Security Best Practices
- Never commit secrets — Use
.gitignoreto exclude.env.*files (already configured in this template) - Use key mappings — Let the framework inject secrets rather than reading them in test code
- Prefer IAM/Managed Identity — Avoid long-lived tokens when running in cloud environments
- Set timeouts — Prevent test hangs if a secrets backend is unreachable
- Use secret prefixes — Namespace secrets per application/environment (e.g.,
myapp/prod/db-password) - Rotate regularly — The caching layer means secrets are fetched once per test run, so rotations take effect on next run
- Limit scope — Use protected/masked variables in GitLab, or scoped policies in Vault/OpenBao
Custom Provider
You can implement the SecretsProvider interface to add support for any backend:
import { SecretsProvider } from '@inluxc/propmaster';
export class MyCustomProvider implements SecretsProvider {
readonly name = 'my-provider';
async getSecret(key: string): Promise<string> {
// Fetch from your backend
const value = await myBackend.fetch(key);
return value;
}
async getSecrets(keys: string[]): Promise<Map<string, string>> {
const results = new Map<string, string>();
for (const key of keys) {
results.set(key, await this.getSecret(key));
}
return results;
}
}Register it with the SecretsManager:
import { SecretsManager } from '@inluxc/propmaster';
import { MyCustomProvider } from './my-custom-provider';
const manager = new SecretsManager();
manager.registerProvider(new MyCustomProvider());