SDK-Only Secrets

Use local Fentaris secrets commands without a generated Fentaris project.

SDK-only projects can use @fentaris/core and the local fentaris auth and fentaris secrets commands without creating fentaris.json. The CLI discovers the nearest package.json that depends on @fentaris/core.

Quick Start

Install the core package and CLI:

pnpm add @fentaris/core
pnpm add -D @fentaris/cli

Add Fentaris metadata to package.json:

{
  "dependencies": {
    "@fentaris/core": "^2.0.0"
  },
  "fentaris": {
    "entrypoint": "src/server.ts",
    "authDir": ".fentaris"
  }
}

Declare the credential reference and its encrypted local source in the entrypoint:

import {
  bearer,
  credential,
  credentialVault,
  fentaris,
  mcp,
  streamableHttp,
} from "@fentaris/core";

const app = fentaris({
  defaults: {
    credentials: {
      "github.token": credentialVault("github.work.token"),
    },
  },
  servers: [
    mcp("github", {
      transport: streamableHttp({ url: "https://github.example/mcp" }),
      auth: bearer(credential("github.token")),
    }),
  ],
});

await app.start({ port: 4000, path: "/mcp" });

Generate the committed manifest:

fentaris secrets manifest --entrypoint src/server.ts

Store local values without putting them in shell history:

export FENTARIS_VAULT_KEY="<explicit-vault-unlock-key>"
printf '%s' "$GITHUB_TOKEN" | fentaris secrets set github.work.token --stdin --non-interactive

The reference explicitly resolves through the project vault. On macOS, Keychain normally supplies its unlock key; other platforms/CI require an explicit unlock mechanism. Source bindings can use the existing environment without copying values. Read Project vault and client keys for isolation, sources, and recovery.

Manage Client API Keys

Configure identity: { strategy: projectVaultIdentityStrategy({root: process.cwd()}), required: true } and retain your existing policy and incoming user declarations. Then create and inspect named keys:

fentaris auth
fentaris auth keys create --user alice --name workstation --non-interactive
fentaris auth keys list --user alice --json
fentaris auth keys revoke <key-id> --non-interactive

Creation delivers a sensitive raw value once. Only a verifier hash is stored. Revoked/expired keys fail authentication. Incoming user IDs remain distinct from upstream account aliases.

What To Commit

Commit the manifest and the package metadata:

package.json
.fentaris/secrets.manifest.json

Do not commit the encrypted local credential store:

.fentaris/vault.json

.fentaris/secrets.manifest.json contains reference names and scopes only. It is the schema teammates and CI need; it does not contain secret values.

Validate In CI

Use manifest check mode to catch stale credential declarations:

fentaris secrets manifest --entrypoint src/server.ts --check

Run fentaris secrets doctor locally when a teammate cannot start the proxy because a required credential is missing.

Related Documentation

• Config file
• CLI Usage
• Governance auth
• Security