Step 1 · install the base

Passo 1 · instale a base

The contract, the shared core and the factory. No provider yet — that is step 2, and it is a separate distribution so an AWS-only service never pulls a GCP SDK.

O contrato, o core compartilhado e a factory. Nenhum provider ainda — isso é o passo 2, e ele é uma distribuição separada, então um serviço só-AWS nunca baixa um SDK do GCP.

contracts depends on nothing. A consumer that only declares types or catches errors installs that one package alone.

contracts não depende de nada. Quem só declara tipos ou captura erros instala apenas esse pacote.

$ uv add secret-kernel-contracts secret-kernel-core \
    secret-kernel-factory

$ npm install @secret-kernel/contracts @secret-kernel/core \
    @secret-kernel/factory

Omitting always wins over replacing. Passing both omit_projectomitProject and project drops the segment.

Omitir sempre vence substituir. Passar omit_projectomitProject e project juntos derruba o segmento.

Replacing env is never implicit: the client's value applies unless a call says otherwise, in that call alone. It exists for the caller who knows better than the process context — a local run reading the one secret that lives elsewhere.

Substituir o env nunca é implícito: o valor do client vale a menos que uma chamada diga o contrário, e só naquela chamada. Existe para quem chama e sabe mais que o contexto do processo — uma execução local lendo o único segredo que mora em outro lugar.

from secret_kernel.contracts import GetSecretOptions

# /prod/billing/database — the client prefix is left out
await client.get_secret(
    "database", GetSecretOptions(omit_prefix=True)
)

# /prod/shared/api-key — read another project's secret
await client.get_secret(
    "api-key", GetSecretOptions(project="shared")
)

# /staging/billing/database/password — another environment, once
await client.get_secret(
    "database/password", GetSecretOptions(env="staging")
)

# /license-key — belongs to no environment or project
await client.get_secret(
    "license-key",
    GetSecretOptions(omit_env=True, omit_project=True),
)

// /prod/billing/database — the client prefix is left out
await client.getSecret('database', { omitPrefix: true });

// /prod/shared/api-key — read another project's secret
await client.getSecret('api-key', { project: 'shared' });

// /staging/billing/database/password — another environment, once
await client.getSecret('database/password', { env: 'staging' });

// /license-key — belongs to no environment or project
await client.getSecret('license-key', {
  omitEnv: true,
  omitProject: true,
});

Parse modes

Modos de parse

Two modes: JSON and KEY_VALUE. Keys and values are trimmed by default.

Dois modos: JSON e KEY_VALUE. Chaves e valores têm espaços removidos por padrão.

A secret that exists but cannot be parsed raises SecretParseError; parse results are never cached.

Um segredo que existe mas não pode ser parseado levanta SecretParseError; resultados de parse nunca são cacheados.

from secret_kernel.contracts import (
    GetSecretOptions,
    SecretParseMode,
)

# "s3cr3t"
plain = await client.get_secret("database/password")

# {"host": "db.internal", "port": 5432}
config = await client.get_secret(
    "database/config", GetSecretOptions(parse=SecretParseMode.JSON)
)

# {"user": "app", "password": "s3cr3t"}
# from "user=app;password=s3cr3t"
pairs = await client.get_secret(
    "database/credentials",
    GetSecretOptions(parse=SecretParseMode.KEY_VALUE),
)

import { SecretParseMode } from '@secret-kernel/contracts';

// "s3cr3t"
const plain = await client.getSecret('database/password');

// { host: 'db.internal', port: 5432 }
type DbConfig = { host: string; port: number };

const config = await client.getSecret<DbConfig>(
  'database/config',
  { parse: SecretParseMode.Json },
);

// { user: 'app', password: 's3cr3t' }
// from "user=app;password=s3cr3t"
const pairs = await client.getSecret(
  'database/credentials',
  { parse: SecretParseMode.KeyValue },
);

Key-value conventions

Convenções chave-valor

If a project always stores key-value secrets the same way, set the convention once on the client instead of repeating it at every call.

Se um projeto sempre guarda segredos chave-valor do mesmo jeito, defina a convenção uma vez no client em vez de repeti-la em cada chamada.

A per-call parse_optionsparseOptions is merged over the client's field by field, so a call that needs one different separator does not have to restate the others.

Um parse_optionsparseOptions por chamada é mesclado sobre o do client campo por campo, então uma chamada que precisa de um separador diferente não precisa repetir os outros.

Empty pairs are ignored, empty values are kept as "", an empty key raises, and a repeated key keeps the last value.

Pares vazios são ignorados, valores vazios são mantidos como "", uma chave vazia levanta erro, e uma chave repetida mantém o último valor.

from secret_kernel.contracts import KeyValueParseOptions

client = create_secret_client(
    CreateSecretClientConfig(
        provider="aws-parameter-store",
        env="prod",
        parse_options=KeyValueParseOptions(
            pair_separator="|",
            key_value_separator=":",
        ),
        options=AwsParameterStoreProviderOptions(
            region="us-east-1",
        ),
    )
)

# only the pair separator differs here; ":" is inherited
await client.get_secret(
    "legacy",
    GetSecretOptions(
        parse=SecretParseMode.KEY_VALUE,
        parse_options=KeyValueParseOptions(pair_separator=";"),
    ),
)

const client = await createSecretClient({
  provider: SecretProvider.AwsParameterStore,
  env: 'prod',
  parseOptions: { pairSeparator: '|', keyValueSeparator: ':' },
  options: { region: 'us-east-1' },
});

// only the pair separator differs here; ':' is inherited
await client.getSecret('legacy', {
  parse: SecretParseMode.KeyValue,
  parseOptions: { pairSeparator: ';' },
});

Credentials

Credenciais

Credentials are explicit when you pass them, and fall back to the cloud SDK's own chain when you do not. Explicit credentials take precedence.

As credenciais são explícitas quando você as passa, e caem para a própria cadeia do SDK da nuvem quando você não passa. Credenciais explícitas têm precedência.

Injecting a client keeps the SDK client under your lifecycle — the kernel closes only what it created.

Injetar um client mantém o client do SDK sob o seu ciclo de vida — o kernel fecha apenas o que ele mesmo criou.

Providers that cannot store / flatten the resolved name with a separator: AWS accepts /, _ and - and defaults to /; GCP accepts _ and - and defaults to _.

Providers que não conseguem guardar / achatam o nome resolvido com um separador: a AWS aceita /, _ e - e usa / como padrão; o GCP aceita _ e - e usa _.

from secret_kernel.provider_gcp_secret_manager import (
    GcpSecretManagerProviderOptions,
)

client = create_secret_client(
    CreateSecretClientConfig(
        provider="gcp-secret-manager",
        env="prod",
        project="billing",
        options=GcpSecretManagerProviderOptions(
            project_id="my-gcp-project",
            physical_name_separator="_",
        ),
    )
)

# reads projects/my-gcp-project/secrets/
#   prod_billing_database_password/versions/latest

const client = await createSecretClient({
  provider: SecretProvider.GcpSecretManager,
  env: 'prod',
  project: 'billing',
  options: {
    projectId: 'my-gcp-project',
    physicalNameSeparator: '_',
  },
});

// reads projects/my-gcp-project/secrets/
//   prod_billing_database_password/versions/latest

The cache stores the decrypted string keyed by the resolved name, before any parsing, so the same secret read as JSON and as text costs one provider call.

O cache guarda a string descriptografada chaveada pelo nome resolvido, antes de qualquer parse, então o mesmo segredo lido como JSON e como texto custa uma chamada ao provider.

A value served from cache reports no version and no metadata: the cache stores the string only.

Um valor servido do cache não reporta version nem metadata: o cache guarda apenas a string.

Failures are never cached. A missing secret that appears later is found on the next read.

Falhas nunca são cacheadas. Um segredo ausente que aparece depois é encontrado na leitura seguinte.

Encryption in memory

Criptografia em memória

For a process that holds secrets in memory for a long time, cached values can be encrypted with AES-256-GCM. Without an encryption_keyencryptionKey the client generates one and keeps it in memory only.

Para um processo que mantém segredos em memória por muito tempo, os valores cacheados podem ser criptografados com AES-256-GCM. Sem uma encryption_keyencryptionKey, o client gera uma e a mantém apenas em memória.

What it protects against: a heap snapshot, or an accidental object dump. What it does not: code running inside the same process.

Contra o que protege: um snapshot de heap, ou um dump acidental de objeto. Contra o que não protege: código rodando dentro do mesmo processo.

from secret_kernel.contracts import SecretCacheOptions

client = create_secret_client(
    CreateSecretClientConfig(
        provider="aws-secrets-manager",
        env="prod",
        cache=SecretCacheOptions(
            enabled=True,
            ttl_ms=300_000,
            max_entries=100,
            encrypt_in_memory=True,
        ),
        options=AwsSecretsManagerProviderOptions(
            region="us-east-1",
        ),
    )
)

const client = await createSecretClient({
  provider: SecretProvider.AwsSecretsManager,
  env: 'prod',
  cache: {
    enabled: true,
    ttlMs: 300_000,
    maxEntries: 100,
    encryptInMemory: true,
  },
  options: { region: 'us-east-1' },
});

Only not-found and permission are normalized. Every other failure keeps the message the SDK produced and gains provider, ref and code, with the original exception in cause.

Só não-encontrado e permissão são normalizados. Toda outra falha preserva a mensagem que o SDK produziu e ganha provider, ref e code, com a exceção original em cause.

This is why a missing secret raises SecretNotFoundError whichever provider is behind the contract — and why a provider-specific failure still tells you which SDK produced it.

É por isso que um segredo ausente levanta SecretNotFoundError qualquer que seja o provider por trás do contrato — e por isso que uma falha específica de provider ainda diz qual SDK a produziu.

from secret_kernel.contracts import (
    SecretNotFoundError,
    SecretParseError,
)

try:
    secret = await client.get_secret(
        "database/config",
        GetSecretOptions(parse=SecretParseMode.JSON),
    )
except SecretNotFoundError as error:
    logger.warning("missing %s on %s", error.ref, error.provider)
    raise
except SecretParseError as error:
    logger.error(
        "unparseable %s", error.ref, exc_info=error.__cause__
    )
    raise

import {
  SecretNotFoundError, SecretParseError,
} from '@secret-kernel/contracts';

try {
  const secret = await client.getSecret('database/config', {
    parse: SecretParseMode.Json,
  });
} catch (error) {
  if (error instanceof SecretNotFoundError) {
    logger.warn(`missing ${error.ref} on ${error.provider}`);
  } else if (error instanceof SecretParseError) {
    logger.error(`unparseable ${error.ref}`, {
      cause: error.cause,
    });
  }
  throw error;
}

Lifecycle events

Eventos de ciclo de vida

Pass a logger to receive lifecycle events, or debug to send them to the console. Without either, the client is silent.

Passe um logger para receber eventos de ciclo de vida, ou debug para mandá-los ao console. Sem nenhum dos dois, o client fica silencioso.

Bring your own provider

Traga seu próprio provider

The factory accepts a provider class directly, so a store this package has never heard of is used through the same contract. The factory asserts the class declares the requested provider_nameproviderName.

A factory aceita uma classe de provider diretamente, então um cofre que este pacote nunca viu é usado pelo mesmo contrato. A factory verifica que a classe declara o provider_nameproviderName pedido.

The shared contract suite in the testing package runs every portable guarantee against it — decrypted reads, prefix composition, both parse modes, and SecretNotFoundError on a missing secret.

A suíte de contrato compartilhada no pacote de testing roda todas as garantias portáveis contra ele — leituras descriptografadas, composição de prefix, os dois modos de parse, e SecretNotFoundError num segredo ausente.

client = create_secret_client(
    CreateSecretClientConfig(
        provider="gcp-secret-manager",
        env="prod",
        logger=my_logger,   # .debug(message, context)
        options=GcpSecretManagerProviderOptions(
            project_id="my-project",
        ),
    )
)

const client = await createSecretClient({
  provider: SecretProvider.GcpSecretManager,
  env: 'prod',
  logger: {
    debug: (message, context) => myLogger.debug(message, context),
  },
  options: { projectId: 'my-project' },
});

create_secret_client(
    CreateSecretClientConfig(
        provider="my-vault",
        provider_class=MyVaultClient,
    )
)

await createSecretClient({
  provider: 'my-vault',
  providerClass: MyVaultClient,
});