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,
  credentialJson,
  fentaris,
  mcp,
  streamableHttp,
} from "@fentaris/core";

const app = fentaris({
  defaults: {
    credentials: {
      "github.token": credentialJson("defaults.github.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_AUTH_KEY="local-encryption-key"
printf '%s' "$GITHUB_TOKEN" | fentaris secrets set github.token --value-stdin --non-interactive

The default-scope CLI command writes defaults.github.token, matching the credentialJson(...) declaration. Use --user <id> or --group <id> only when the TypeScript configuration declares the corresponding user or group credential source.

Manage Client API Keys

Run the guided auth menu from the SDK-only project or one of its subdirectories:

fentaris auth

The CLI uses the same package discovery and fentaris.authDir setting as secrets commands. For automation, provide the user and key source explicitly:

fentaris auth api-key add alice --generate --non-interactive

Fentaris prints a generated key once and stores only its hash.

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/credentials.enc.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