Skip to content
Kitsy Docs Open CNOS
Kitsy Docs

Vault Provider Packages

Vault Provider Packages

Remote vault providers are compiled into the application runtime. CNOS never loads provider packages dynamically from .cnos/cnos.yml.

Package names

Official providers use this package shape:

  • @kitsy/cnos-vault-gcp
  • @kitsy/cnos-vault-aws
  • @kitsy/cnos-vault-hashicorp
  • @kitsy/cnos-vault-azure
  • @kitsy/cnos-vault-firebase

Each package must export a factory named create<Vendor>VaultProvider(). The factory returns a SecretVaultProviderFactory whose provider field exactly matches the manifest provider name.

import cnos from '@kitsy/cnos';
import { createGcpSecretManagerVaultProvider } from '@kitsy/cnos-vault-gcp';


cnos.registerSecretVaultProvider(createGcpSecretManagerVaultProvider());
await cnos.ready();

Manifest contract

Provider selection belongs in config:

vaults:
  prod-gcp:
    provider: gcp-secret-manager
    auth:
      method: iam
      config:
        projectId: acme-prod
    fallback:
      - provider: environment
        mapping:
          DB_PASSWORD: db.password

Secret refs should normally inherit from the named vault:

db:
  password:
    vault: prod-gcp
    ref: db.password

Do not set a different provider on a ref that also names a vault. CNOS rejects provider/vault mismatches so Node, Go, and projections all agree.

Runtime contract

Every provider must implement the SecretVaultProvider interface:

  • authenticate(authConfig) resolves credentials supplied by CNOS.
  • batchGet(refs) is the startup and refresh path.
  • get(ref) exists for compatibility and narrow single-ref use, but provider tests must prove startup and refreshSecrets() do not call it.
  • set(ref, value) and delete(ref) may be writable or may reject. Declare the expected capability in testkit setup.
  • list() returns known refs when the backing platform supports listing.
  • healthCheck() is optional for remote providers.

Startup hydration and full refresh are batch-only. Individual application reads use the CNOS in-memory cache and must not perform remote I/O.

Auth and projection safety

Provider auth should prefer platform identity:

  • GCP: Application Default Credentials or attached service account.
  • AWS: IAM role or standard AWS credential chain.
  • Azure: managed identity or default credential chain.
  • HashiCorp Vault: token sources such as env:, file:, or keychain.
  • Firebase: direct provider support plus explicit environment fallback for injected secrets.

Server projections may include safe metadata such as projectId, region, endpoint, address, namespace, or tenant. They must not include raw secrets, private keys, bearer tokens, credential blobs, or client secrets. CNOS sanitizes projected auth.config, but provider authors should design manifest config so credential material is referenced by source (env:NAME, file:PATH, keychain:NAME) rather than stored inline.

Conformance tests

Provider packages should use @kitsy/cnos-vault-testkit:

import {
  defineSecretVaultProviderConformanceSuite,
  defineSecretVaultRuntimeConformanceSuite,
} from '@kitsy/cnos-vault-testkit';


defineSecretVaultProviderConformanceSuite('gcp-secret-manager', () => ({
  factory: createGcpSecretManagerVaultProvider(),
  definition,
  auth,
  refs,
}));


defineSecretVaultRuntimeConformanceSuite('gcp-secret-manager', () => ({
  factory: createGcpSecretManagerVaultProvider(),
  vaultId: 'prod-gcp',
  definition,
  refs,
  processEnv,
}));

The shared suite verifies provider auth, batch reads, missing refs, runtime startup hydration, projection bootstrap, refresh batching, safe projection metadata, and explicit environment fallback behavior.

Google Secret Manager

Install and register the compiled-in provider:

import cnos from '@kitsy/cnos';
import { createGcpSecretManagerVaultProvider } from '@kitsy/cnos-vault-gcp';


cnos.registerSecretVaultProvider(createGcpSecretManagerVaultProvider());
await cnos.ready();

Use auth.method: iam and let the official Google SDK resolve Application Default Credentials or an attached service account:

vaults:
  prod-gcp:
    provider: gcp-secret-manager
    auth:
      method: iam
      config:
        projectId: acme-prod
    mapping:
      db-password: db.password

CNOS resolves secret.db.password from projects/acme-prod/secrets/db-password/versions/latest. Set auth.config.version to read a pinned version, or auth.config.location for regional Secret Manager resources. A full ref such as projects/acme-prod/secrets/db-password/versions/5 is also accepted.

Firebase Secrets

Install and register the compiled-in provider:

import cnos from '@kitsy/cnos';
import { createFirebaseSecretsVaultProvider } from '@kitsy/cnos-vault-firebase';


cnos.registerSecretVaultProvider(createFirebaseSecretsVaultProvider());
await cnos.ready();

Firebase Secrets are backed by Google Secret Manager. Use auth.method: iam and let the official Google SDK resolve Application Default Credentials or an attached service account:

vaults:
  prod-firebase:
    provider: firebase-secrets
    auth:
      method: iam
      config:
        projectId: acme-prod
    mapping:
      DB_PASSWORD: db.password
    fallback:
      - provider: environment
        mapping:
          DB_PASSWORD: db.password

CNOS resolves secret.db.password from projects/acme-prod/secrets/DB_PASSWORD/versions/latest. Set auth.config.version to read a pinned version, or auth.config.location for regional Secret Manager resources. A full ref such as projects/acme-prod/secrets/DB_PASSWORD/versions/5 is also accepted.

Firebase and Google Cloud Functions can inject secrets as environment variables. Model that as an explicit environment fallback in the vault definition; CNOS never silently falls back to env when a remote provider fails.

AWS Secrets Manager

Install and register the compiled-in provider:

import cnos from '@kitsy/cnos';
import { createAwsSecretsManagerVaultProvider } from '@kitsy/cnos-vault-aws';


cnos.registerSecretVaultProvider(createAwsSecretsManagerVaultProvider());
await cnos.ready();

Use auth.method: iam and let AWS SDK v3 resolve credentials from IAM roles, web identity, environment credentials, or the standard AWS provider chain:

vaults:
  prod-aws:
    provider: aws-secrets-manager
    auth:
      method: iam
      config:
        region: us-east-1
    mapping:
      db/password: db.password

CNOS resolves secret.db.password from the AWS secret ID db/password. Set auth.config.versionId or auth.config.versionStage for pinned or staged reads. Secret refs may also be direct AWS secret names or ARNs when no mapping is required.

HashiCorp Vault

Install and register the compiled-in provider:

import cnos from '@kitsy/cnos';
import { createHashicorpVaultProvider } from '@kitsy/cnos-vault-hashicorp';


cnos.registerSecretVaultProvider(createHashicorpVaultProvider());
await cnos.ready();

Use auth.method: token and source the Vault token from env, file, or keychain. CNOS resolves the token and passes it to Vault as X-Vault-Token:

vaults:
  prod-vault:
    provider: hashicorp-vault
    auth:
      method: token
      token:
        from:
          - env:VAULT_TOKEN
      config:
        address: https://vault.example.com
        mount: secret
        namespace: admin/team-a
        version: 2
    mapping:
      db/password#password: db.password

For KV v2, CNOS reads secret.data.db/password and extracts the password field. Use path#field refs or mapping keys to select fields from a Vault secret object. Set auth.config.version: 1 for KV v1 mounts, and auth.config.path to apply a shared path prefix.

Azure Key Vault

Install and register the compiled-in provider:

import cnos from '@kitsy/cnos';
import { createAzureKeyVaultProvider } from '@kitsy/cnos-vault-azure';


cnos.registerSecretVaultProvider(createAzureKeyVaultProvider());
await cnos.ready();

Use auth.method: iam and let Azure Identity resolve credentials from managed identity, workload identity, environment credentials, or the standard DefaultAzureCredential chain:

vaults:
  prod-azure:
    provider: azure-key-vault
    auth:
      method: iam
      config:
        vaultUrl: https://acme-prod.vault.azure.net
        tenantId: 00000000-0000-0000-0000-000000000000
    mapping:
      db-password: db.password

CNOS resolves secret.db.password from the Azure secret name db-password. Set auth.config.version for a pinned version, or use a full Azure secret URL such as https://acme-prod.vault.azure.net/secrets/db-password/version-id as the ref when no mapping is required.