Library API

envpkt is available as a TypeScript library with a functional programming API built on functype. All functions return Either<Error, Result> or Option<T> — no thrown exceptions.

import { boot, loadConfig, computeAudit, scanFleet } from "envpkt"

Boot API

High-level API that loads config, resolves catalog, audits, and optionally injects secrets.

boot(options)

const result = boot({ configPath: "envpkt.toml", inject: true })
console.log(result.audit.status) // "healthy" | "degraded" | "critical"

Throws EnvpktBootError on failure.

bootSafe(options)

const safe = bootSafe({ configPath: "envpkt.toml" })
safe.fold(
  (err) => console.error("Boot failed:", err._tag),
  (result) => console.log(`${result.injected.length} secrets injected`),
)

Returns Either<BootError, BootResult>.

BootOptions

type BootOptions = {
  readonly configPath?: string
  readonly profile?: string
  readonly inject?: boolean
  readonly failOnExpired?: boolean
  readonly warnOnly?: boolean
}

BootResult

type BootResult = {
  readonly audit: AuditResult
  readonly injected: ReadonlyArray<string>
  readonly skipped: ReadonlyArray<string>
  readonly secrets: Readonly<Record<string, string>>
  readonly warnings: ReadonlyArray<string>
  readonly configPath: string
  readonly configSource: ConfigSource
}

ConfigSource

type ConfigSource = "flag" | "env" | "cwd" | "search"

Indicates how the config was resolved: explicit --config flag, ENVPKT_CONFIG env var, current working directory, or the discovery search chain.

Config Operations

loadConfig(path)

Load and validate an envpkt.toml file. Returns Either<ConfigError, EnvpktConfig>.

const config = loadConfig("envpkt.toml")
config.fold(
  (err) => console.error("Failed:", err._tag),
  (config) => console.log(config),
)

resolveConfigPath(flagPath?, envVar?, cwd?)

Resolve config path via priority chain: explicit flag → ENVPKT_CONFIG env var → CWD + discovery chain. Returns Either<ConfigError, ResolvedPath>.

type ResolvedPath = { readonly path: string; readonly source: ConfigSource }

discoverConfig(cwd?)

Discover config by checking CWD, then ENVPKT_SEARCH_PATH, then built-in candidate paths (~/.envpkt/, cloud storage, etc.). Returns Option<{ path: string; source: "cwd" | "search" }>.

loadConfigFromCwd(cwd?)

Load config from CWD or discovery chain. Returns Either<ConfigError, { path: string; source: string; config: EnvpktConfig }>.

findConfigPath(dir)

Check for envpkt.toml in a specific directory. Returns Option<string>.

parseToml(content)

Parse raw TOML string. Returns Either<ConfigError, unknown>.

validateConfig(data)

Validate parsed data against the schema. Returns Either<ConfigError, EnvpktConfig>.

Catalog Resolution

resolveConfig(config, baseDir)

Resolve catalog references. Returns Either<CatalogError, ResolveResult>.

import { loadConfig, resolveConfig } from "envpkt"
import { dirname } from "node:path"

const configPath = "agents/pipeline/envpkt.toml"
loadConfig(configPath).fold(
  (err) => console.error(err),
  (config) => {
    resolveConfig(config, dirname(configPath)).fold(
      (err) => console.error("Catalog error:", err._tag),
      (result) => {
        console.log("Resolved keys:", result.merged)
        console.log("Overridden:", result.overridden)
      },
    )
  },
)

ResolveResult

type ResolveResult = {
  readonly config: EnvpktConfig
  readonly catalogPath?: string
  readonly merged: ReadonlyArray<string>
  readonly overridden: ReadonlyArray<string>
  readonly warnings: ReadonlyArray<string>
}

Audit Engine

computeAudit(config)

Compute audit results for a config. Returns AuditResult.

const audit = computeAudit(config)
console.log(audit.status) // "healthy" | "degraded" | "critical"
audit.secrets.forEach((s) => {
  console.log(`${s.key}: ${s.status}`)
})

computeEnvAudit(config)

Compute drift results for [env.*] entries. Returns EnvAuditResult.

const envAudit = computeEnvAudit(config)
console.log(`${envAudit.total} env defaults, ${envAudit.defaults_applied} using default`)
envAudit.entries.forEach((e) => {
  console.log(`${e.key}: ${e.status}`) // "default" | "overridden" | "not_set"
})

EnvAuditResult

type EnvAuditResult = {
  readonly entries: ReadonlyArray<EnvDriftEntry>
  readonly total: number
  readonly defaults_applied: number
  readonly overridden: number
  readonly not_set: number
}

EnvMeta

type EnvMeta = {
  readonly value: string
  readonly purpose?: string
  readonly comment?: string
  readonly tags?: Record<string, string>
}

Fleet Scanner

scanFleet(dir, options?)

Scan a directory tree for envpkt.toml files. Returns FleetHealth.

const fleet = scanFleet("/opt/agents", { maxDepth: 3 })
console.log(`${fleet.total_agents} agents, ${fleet.total_secrets} secrets`)

Environment Scanning

envScan(env)

Scan an environment object for credentials. Returns ScanResult.

const scan = envScan(process.env)
console.log(`Found ${scan.discovered.size} credentials`)

envCheck(config, env)

Bidirectional drift detection. Returns CheckResult.

const check = envCheck(config, process.env)
if (!check.is_clean) {
  console.log(`${check.missing_from_env} missing, ${check.untracked_credentials} untracked`)
}

generateTomlFromScan(matches)

Generate TOML [secret.*] blocks from scan results.

matchEnvVar(name, value)

Match a single env var against all patterns. Returns Option<MatchResult>.

matchEnvVar("OPENAI_API_KEY", "sk-test123").fold(
  () => console.log("Not a credential"),
  (m) => console.log(`Matched: ${m.confidence} confidence`),
)

Packet Formatting

formatPacket(resolveResult, options?)

Produce a human-readable text summary of a resolved config.

import { formatPacket } from "envpkt"

// Without secrets
const text = formatPacket(resolveResult)

// With masked secrets
const masked = formatPacket(resolveResult, {
  secrets: { DATABASE_URL: "postgres://user:pass@host/db" },
})

// With plaintext secrets
const plain = formatPacket(resolveResult, {
  secrets: { DATABASE_URL: "postgres://user:pass@host/db" },
  secretDisplay: "plaintext",
})

maskValue(value)

Mask a secret value for display (e.g., postgres://user:pass@host/db → pos•••••t/db).

Keygen API

resolveKeyPath()

Resolve the age identity file path: -o flag > ENVPKT_AGE_KEY_FILE env var > ~/.envpkt/age-key.txt. Returns string.

resolveInlineKey()

Check for inline age key in ENVPKT_AGE_KEY env var (for CI). Returns Option<string>.

generateKeypair(options?)

Generate an age keypair and write to disk. Returns Either<KeygenError, KeygenResult>.

import { generateKeypair } from "envpkt"

const result = generateKeypair({ outputPath: "~/.envpkt/age-key.txt" })
result.fold(
  (err) => console.error(`Keygen failed: ${err._tag}`),
  (res) => console.log(`Recipient: ${res.recipient}`),
)

Options: { force?: boolean; outputPath?: string }

updateConfigRecipient(configPath, recipient)

Update identity.recipient in an envpkt.toml file, preserving TOML structure. Creates [identity] section if missing. Returns Either<KeygenError, true>.

KeygenResult

type KeygenResult = {
  readonly recipient: string
  readonly identityPath: string
  readonly configUpdated: boolean
}

fnox Integration

detectFnox() / fnoxAvailable()

Check for fnox availability.

readFnoxConfig(path) / extractFnoxKeys(config)

Read and parse fnox configuration.

compareFnoxAndEnvpkt(fnoxConfig, envpktConfig)

Compare keys between fnox and envpkt for orphan detection.

fnoxGet(key, profile?) / fnoxExport(keys, profile?)

Retrieve secret values from fnox.

ageAvailable() / unwrapAgentKey(identityPath)

Check for age encryption support and decrypt agent keys.

MCP Server

createServer() / startServer()

Create and start the MCP server programmatically.

toolDefinitions / callTool(name, args, config, audit)

MCP tool definitions and invocation.

resourceDefinitions / readResource(uri, config, audit)

MCP resource definitions and reading.