cryptofort

Why CryptoFort

Secrets sprawl across .env files, shell history, and plaintext columns — and agents have no safe, structured way to ask for them. CryptoFort seals every secret with authenticated encryption, keeps the key out of the database entirely, and hands agents an MCP interface that returns metadata and nothing else. A conversational agent keeps whatever it is told, so the value itself is reached by a process that runs one operation with it, not by the agent that decided to run it.

Related MCP server: GhostKey

Stack

Getting started

Install

npm install cryptofort
# plus the driver for your backend:
npm install @supabase/supabase-js   # or: better-sqlite3 | postgres
# and, to run the MCP server:
npm install @modelcontextprotocol/sdk

Every driver — and the MCP SDK — is an optional peer dependency, so nothing is pulled in that you do not use. Requires Node 20 or newer.

CryptoFort is also published to GitHub Packages as @bradley-t-t/cryptofort. Point the @bradley-t-t scope at the GitHub registry and authenticate with a token that has read:packages — GitHub Packages requires auth even for public packages:

@bradley-t-t:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

npm install @bradley-t-t/cryptofort

Documentation

The rest of this page is the tour. docs/ is the manual.

Library usage

import { Vault, Crypto, SqliteAdapter } from 'cryptofort';

const adapter = new SqliteAdapter('vault.db');
await adapter.init();

const vault = new Vault({
  adapter,
  crypto: new Crypto({ key: process.env.CRYPTOFORT_MASTER_KEY! }),
});

await vault.put({
  name: 'stripe-secret-key',
  secret: 'sk_live_…',
  provider: 'stripe',
  tags: ['payments'],
});
await vault.search('stripe'); // metadata only — never the secret
await vault.get('stripe-secret-key'); // the decrypted secret

Credentials can be given an expiry, after which they are deleted automatically:

await vault.put({
  name: 'ci-deploy-token',
  secret: 'ghp_…',
  expiresAt: '2026-09-01T00:00:00Z', // ISO 8601; pass null later to clear it
});

await vault.purgeExpired(); // delete every entry whose time has come up

Once expiresAt passes, the credential is dead everywhere at once: get deletes it and returns null, and search/list no longer show it — even before a purge sweep has physically removed the row. purgeExpired() does the physical cleanup; call it on whatever schedule suits your app (the MCP server runs it for you, at startup and hourly).

Generate a master key (base64, 32 bytes):

node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

…or from the library with import { generateKey } from 'cryptofort'.

MCP server

The MCP server needs @modelcontextprotocol/sdk installed alongside CryptoFort. Point any MCP client at the cryptofort-mcp binary:

{
  "mcpServers": {
    "cryptofort": {
      "command": "cryptofort-mcp",
      "env": {
        "CRYPTOFORT_ADAPTER": "supabase",
        "SUPABASE_URL": "https://<ref>.supabase.co",
        "SUPABASE_SERVICE_ROLE_KEY": "<service-role-key>",
        "CRYPTOFORT_MASTER_KEY": "<base64-32-bytes>"
      }
    }
  }
}

The server serves metadata only by default: it can say what the vault holds, and nothing that would tell you a secret. Three flags widen that, and they are separate because they answer different questions.

• "args": ["--allow-secret-read"] exposes credential_get, which returns a decrypted secret to whoever called it. Give it to a process that will use the value and exit — not to an agent whose conversation is written to disk, because a secret handed to one stays in that transcript for as long as the transcript does.

• "args": ["--allow-write"] exposes credential_put and credential_purge_expired. A put can be put again, and a purge only removes what an expiry had already killed.

• "args": ["--allow-delete"] exposes credential_delete. It is separate because it is the one call the vault cannot answer for afterwards: the secret is gone and no copy is kept.

Tools

Expired credentials are also purged automatically: the server sweeps them at startup and every hour after that, and an expired entry is unreadable the moment its time passes. Expiries belong to whoever set them, so the sweep runs whatever the server was started with.

Environment

Backends

Architecture

flowchart TD
    A["Agent / MCP client"] -->|"stdio"| M["cryptofort-mcp — read-only by default"]
    App["Your app"] --> V["Vault"]
    M --> V
    V --> C["Crypto — AES-256-GCM"]
    C -->|"master key from env, never stored"| K["CRYPTOFORT_MASTER_KEY"]
    V --> AD["Adapter"]
    AD --> S[("Supabase")]
    AD --> P[("Postgres")]
    AD --> Q[("SQLite")]

How it works

• Only the secret is ciphertext. name, description, provider, and tags stay plaintext, so search and listing work without ever decrypting.

• Each secret is sealed with AES-256-GCM — authenticated encryption, so any tampering is caught on read.

• The master key never touches the database. It lives only in CRYPTOFORT_MASTER_KEY; a stolen dump reveals nothing without it.

• The MCP server registers a tool only when the permission covering it was given, so a caller cannot reach credential_get, credential_put, or credential_delete at all rather than being trusted to respect a refusal. A default server can describe the vault and change nothing in it.

• Credentials with an expiresAt die on schedule: reads treat an expired entry as gone immediately, and purge sweeps (hourly in the MCP server, or vault.purgeExpired() in your own code) delete the rows themselves.

Schema

CryptoFort creates its schema automatically on first connect — one table, one ciphertext column, the rest plaintext metadata for search. There is no migration to run by hand.

• SQLite and Postgres: adapter.init() issues create table if not exists (plus indexes on Postgres), so pointing CryptoFort at an empty database is enough.

• Supabase: the client speaks PostgREST, which cannot run DDL. init() probes for the table and, when it is missing, creates it through a direct Postgres connection given in CRYPTOFORT_SUPABASE_DB_URL. If the table already exists the probe is a no-op; if it is missing and no DB URL is set, init() fails with a clear message instead of silently.

The canonical column definitions live in src/adapters/schema.ts.

Project structure

cryptofort/
├── assets/cryptofort-hero.png
├── src/
│   ├── index.ts               Public surface — Vault, Crypto, the three adapters, types
│   ├── vault.ts               put / get / search / list / remove / purgeExpired over an adapter
│   ├── crypto.ts              AES-256-GCM seal/open, generateKey
│   ├── types.ts               Credential and search types, DEFAULT_NAMESPACE
│   ├── adapters/
│   │   ├── types.ts           The CredentialStore contract
│   │   ├── schema.ts          Canonical column definitions
│   │   ├── supabase.ts        PostgREST, with optional direct-Postgres provisioning
│   │   ├── postgres.ts        `postgres` driver
│   │   └── sqlite.ts          better-sqlite3
│   └── mcp/
│       ├── bin.ts             The `cryptofort-mcp` executable and its permission flags
│       ├── server.ts          Tool definitions, exported as `cryptofort/mcp`
│       ├── config.ts          Crypto and adapter construction from the environment
│       └── env.ts             Reading and refusing environment values
├── test/                      crypto, vault, mcp, env, and one suite per adapter
├── docs/                      Getting started, configuration, API, MCP, backends, security, troubleshooting
├── CONTRIBUTING.md            Setup, the checks CI runs, and the branch flow
├── SECURITY.md                Reporting a vulnerability, and the threat model
└── tsup.config.ts

Development

npm install
npm run build      # bundle with tsup
npm test           # run the vitest suite

Backend drivers are optional peer dependencies — install only the one you use. They are dev dependencies here, so a full install gives you everything the test suite needs, and no database has to be running: the adapter suites drive fakes.

Contributing

Contributions are welcome — bug reports, documentation corrections, and patches alike. CONTRIBUTING.md covers local setup, the checks CI runs, the develop → main branch flow, and the conventions this codebase follows, including how to add a backend adapter or an MCP tool.

The short version: branch off develop, open your pull request against develop, and make sure these pass first.

npm ci
npm run format:check && npm run lint && npm run typecheck && npm test && npm run build

Everyone taking part is expected to follow the Code of Conduct.

Security

CryptoFort stores credentials, so a flaw in it is a flaw in whatever it holds.

Please do not report a vulnerability in a public issue. Open a private security advisory instead — SECURITY.md has the process, the response times, and an explicit account of what CryptoFort protects and what it deliberately does not.

Two things are worth knowing before you store anything:

• Only the secret is encrypted. name, description, provider, tags, and metadata are plaintext so search can work without decrypting. Never put a secret in one of them.

• The master key is the whole of the vault's security. Keep it in a secret manager, use a different one per environment, and never commit it or store it in the database it unlocks.

License

Released under the MIT License.