<!--
  GENERATED FILE — do not edit.

  Change tools/generate-guides.ts or its typed sources, run `bun run guides`,
  and commit the generator and rendered files together.
-->

# Vault SDK

One scoped contract over platform-direct, managed-agent and external API-key trust paths.

## Install

Exact Deployment binding reads through a managed Agent or signed API credential. The exact-binding Vault client. A tenant application uses its local Agent or an API credential; platform internals use their own scoped storage engine. The one package that ends up in somebody else's production dependency tree, which is why it stays alone and stays small.

```text
bun add @forgezero/vault
```

<a id="provider-git-connect"></a>
## Attach a versioned Git forge to Git Connect

One GitHub App provider is projected into separate OAuth Server and Git Connect method sets. Its shared credential source remains Vault-scoped and installation tokens are minted only when needed.

```text
import {
  createService,
} from '@forgezero/providers';
import {
  defineGitHubProvider,
  gitConnectService,
} from '@forgezero/providers/git';
import {
  createVault,
} from '@forgezero/vault';
import {
  vaultCredentials,
} from '@forgezero/vault/providers';

declare const githubAdapter: Parameters<typeof defineGitHubProvider>[0]['adapter'];
const vault = createVault({ deploymentKey: 'control-plane', environmentKey: 'production' });
const credentials = vaultCredentials(vault, 'github');
const github = defineGitHubProvider({ version: 'github-app:2026-03-10', adapter: githubAdapter });
const git = createService(gitConnectService, {
  beginInstallation: [],
  completeInstallation: [],
  listInstallations: [],
  listRepositories: [{ provider: github, method: 'listRepositories', version: 'github-app:2026-03-10', credentials, priority: 1 }],
  listBranches: [],
  mintCloneCredential: [],
  verifyWebhook: [],
  disconnectInstallation: []
});

const repositories = await git.call('listRepositories', { installationId: '42' });
if (!repositories.ok) throw repositories.error;
```

<a id="vault-read"></a>
## Read a scoped secret

The same client discovers the managed Agent socket or uses an external API-key signer. Deployment and environment remain explicit; only declared binding aliases can be read.

```text
import {
  createVault,
} from '@forgezero/vault';

const vault = createVault({ deploymentKey: 'payments', environmentKey: 'production' });
const token = await vault.get('STRIPE_KEY');
```

## Choose an entry point

Import the capability your application needs. Each package ships TypeScript declarations. Backend-only entries must stay out of browser bundles.

| Import or command | Use it for | Runtime |
|---|---|---|
| @forgezero/vault | Read one exact Deployment binding through a managed Agent socket or a request-signing external API credential. | Portable |
| @forgezero/vault/config | Read `.fz/config.json` — the Deployment, environment, explicit binding aliases and process variable names. | Portable |
| @forgezero/vault/env | Envless: fill `process.env` from the vault at boot, refusing to run during a build. | Portable |
| @forgezero/vault/frameworks | SvelteKit and Next.js wiring, attached at the one place that runs once, on the server, before any request. | Portable |
| @forgezero/vault/providers | Adapters that make Vault a provider-configuration and credential source without coupling the providers package to ForgeZero. | Portable |

## Choose the connection for your application

Supply deploymentKey and environmentKey explicitly. A managed application reads its exact bindings from the Agent’s memory-only Deployment scope. An external application uses its scoped credential over HTTPS. A refused managed read never falls through to another credential.

## Related packages

Add only the packages needed by your application.

| Package | Purpose | Guide |
|---|---|---|
| @forgezero/access | Typed route, principal, factor, RBAC and request-pipeline contracts. | [Read guide](/docs/access) |
| @forgezero/providers | Typed external providers with priority, health and classified fallback. | [Read guide](/docs/providers) |
| @forgezero/runtime | Portable runtime primitives for queries, jobs, events, schemas and finance. | [Read guide](/docs/runtime) |
| @forgezero/agent | Operator CLI and managed-node agent for bootstrap, deploy and lifecycle. | [Read guide](/docs/agent) |

Full rendered documentation: https://www.forgezero.net/docs/vault-package