KeyVaultService
katanakit-js / KeyVaultService
Class: KeyVaultService
Section titled “Class: KeyVaultService”Defined in: core/services/keyvault.service.ts:48
KeyVaultService — Singleton facade for API key record lifecycle.
Applies the Singleton pattern (one shared instance via
KeyVaultService.getInstance) and the Facade pattern: every public
method returns the { data, error, ok } union from SafeResult (or a
plain value when it cannot fail) and never throws.
The methods are pure: they take records and vault payloads as values and
return new ones. Persistence and encryption live in
src/infrastructure/vault/vault.store.ts, so this service stays free of
runtime I/O per CONTRIBUTING.md and is trivially testable.
Security posture: a secret is only ever returned in full by an explicit
reveal call site (the CLI’s keys reveal). Everything else — lists, logs,
config previews — goes through KeyVaultService.useMaskSecret.
Example
Section titled “Example”import { useCreateKeyRecord, useMaskSecret } from "katanakit-js";
const result = useCreateKeyRecord({ provider: "openai", label: "ci", secret: "sk-…",});if (result.ok) console.log(useMaskSecret(result.data.secret)); // sk-••••••••••••1234Methods
Section titled “Methods”useAddKey()
Section titled “useAddKey()”useAddKey(data, record): { createdAt: string; keys: { createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string; }[]; mcpServers: { command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; }[]; updatedAt: string; version: 1;};Defined in: core/services/keyvault.service.ts:195
Appends a record to the vault payload, touching updatedAt.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
data |
{ createdAt: string; keys: { createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string; }[]; mcpServers: { command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; }[]; updatedAt: string; version: 1; } |
The current vault payload. |
data.createdAt? |
string |
- |
data.keys? |
{ createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string; }[] |
- |
data.mcpServers? |
{ command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; }[] |
- |
data.updatedAt? |
string |
- |
data.version? |
1 |
- |
record |
{ createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string; } |
The record to append. |
record.createdAt? |
string |
- |
record.id? |
string |
- |
record.label? |
string |
- |
record.note? |
string |
- |
record.provider? |
string |
- |
record.secret? |
string |
- |
record.status? |
"active" | "revoked" |
- |
record.updatedAt? |
string |
- |
Returns
Section titled “Returns”{ createdAt: string; keys: { createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string; }[]; mcpServers: { command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; }[]; updatedAt: string; version: 1;}The updated payload.
createdAt
Section titled “createdAt”createdAt: string;keys: { createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string;}[];Type Declaration
Section titled “Type Declaration”mcpServers
Section titled “mcpServers”mcpServers: { command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string;}[];Type Declaration
Section titled “Type Declaration”updatedAt
Section titled “updatedAt”updatedAt: string;version
Section titled “version”version: 1;useCreateKeyRecord()
Section titled “useCreateKeyRecord()”useCreateKeyRecord(input): SafeResult<{ createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string;}>;Defined in: core/services/keyvault.service.ts:68
Creates a validated key record with a fresh id and timestamps.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
input |
KeyRecordInput |
Provider, label and secret (plus an optional note). |
Returns
Section titled “Returns”SafeResult<{
createdAt: string;
id: string;
label: string;
note?: string;
provider: string;
secret: string;
status: "active" | "revoked";
updatedAt: string;
}>
{ data, error, ok } — error.status = 400 on validation failure.
useEmptyVault()
Section titled “useEmptyVault()”useEmptyVault(): { createdAt: string; keys: { createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string; }[]; mcpServers: { command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; }[]; updatedAt: string; version: 1;};Defined in: core/services/keyvault.service.ts:219
Returns an empty, schema-valid vault payload.
Returns
Section titled “Returns”{ createdAt: string; keys: { createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string; }[]; mcpServers: { command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; }[]; updatedAt: string; version: 1;}A fresh vault payload.
createdAt
Section titled “createdAt”createdAt: string;keys: { createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string;}[];Type Declaration
Section titled “Type Declaration”mcpServers
Section titled “mcpServers”mcpServers: { command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string;}[];Type Declaration
Section titled “Type Declaration”updatedAt
Section titled “updatedAt”updatedAt: string;version
Section titled “version”version: 1;useFindKey()
Section titled “useFindKey()”useFindKey(data, id): | { createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string;} | undefined;Defined in: core/services/keyvault.service.ts:170
Finds a key record by id.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
data |
{ createdAt: string; keys: { createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string; }[]; mcpServers: { command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; }[]; updatedAt: string; version: 1; } |
The vault payload to search. |
data.createdAt? |
string |
- |
data.keys? |
{ createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string; }[] |
- |
data.mcpServers? |
{ command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; }[] |
- |
data.updatedAt? |
string |
- |
data.version? |
1 |
- |
id |
string |
The record id. |
Returns
Section titled “Returns”| {
createdAt: string;
id: string;
label: string;
note?: string;
provider: string;
secret: string;
status: "active" | "revoked";
updatedAt: string;
}
| undefined
The record, or undefined.
useListKeys()
Section titled “useListKeys()”useListKeys(data, options?): { createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string;}[];Defined in: core/services/keyvault.service.ts:181
Lists key records, newest first.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
data |
{ createdAt: string; keys: { createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string; }[]; mcpServers: { command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; }[]; updatedAt: string; version: 1; } |
The vault payload. |
data.createdAt? |
string |
- |
data.keys? |
{ createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string; }[] |
- |
data.mcpServers? |
{ command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; }[] |
- |
data.updatedAt? |
string |
- |
data.version? |
1 |
- |
options? |
{ includeRevoked?: boolean; } |
includeRevoked also returns revoked records. |
options.includeRevoked? |
boolean |
- |
Returns
Section titled “Returns”{
createdAt: string;
id: string;
label: string;
note?: string;
provider: string;
secret: string;
status: "active" | "revoked";
updatedAt: string;
}[]
The matching records.
useMaskSecret()
Section titled “useMaskSecret()”useMaskSecret(secret): string;Defined in: core/services/keyvault.service.ts:156
Masks a secret for display: the first 8 and last 4 characters survive on
long secrets (matching the freellma••••••••••a8e9 style), short secrets
become bullets only. A mask must never leak enough to brute-force.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
secret |
string |
The secret to mask. |
Returns
Section titled “Returns”string
The masked form.
useProviderEnvName()
Section titled “useProviderEnvName()”useProviderEnvName(provider): string;Defined in: core/services/keyvault.service.ts:238
Resolves the conventional environment variable name for a provider, e.g.
openai → OPENAI_API_KEY. Unknown providers get a stable
KATANAKIT_KEY_<PROVIDER> name so generated configs stay predictable.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
provider |
string |
The provider slug. |
Returns
Section titled “Returns”string
The environment variable name.
useReplaceKey()
Section titled “useReplaceKey()”useReplaceKey(data, record): { createdAt: string; keys: { createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string; }[]; mcpServers: { command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; }[]; updatedAt: string; version: 1;};Defined in: core/services/keyvault.service.ts:207
Replaces the record with the same id (or appends it when absent), touching
updatedAt.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
data |
{ createdAt: string; keys: { createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string; }[]; mcpServers: { command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; }[]; updatedAt: string; version: 1; } |
The current vault payload. |
data.createdAt? |
string |
- |
data.keys? |
{ createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string; }[] |
- |
data.mcpServers? |
{ command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; }[] |
- |
data.updatedAt? |
string |
- |
data.version? |
1 |
- |
record |
{ createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string; } |
The replacement record. |
record.createdAt? |
string |
- |
record.id? |
string |
- |
record.label? |
string |
- |
record.note? |
string |
- |
record.provider? |
string |
- |
record.secret? |
string |
- |
record.status? |
"active" | "revoked" |
- |
record.updatedAt? |
string |
- |
Returns
Section titled “Returns”{ createdAt: string; keys: { createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string; }[]; mcpServers: { command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; }[]; updatedAt: string; version: 1;}The updated payload.
createdAt
Section titled “createdAt”createdAt: string;keys: { createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string;}[];Type Declaration
Section titled “Type Declaration”mcpServers
Section titled “mcpServers”mcpServers: { command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string;}[];Type Declaration
Section titled “Type Declaration”updatedAt
Section titled “updatedAt”updatedAt: string;version
Section titled “version”version: 1;useRevokeKey()
Section titled “useRevokeKey()”useRevokeKey(record): { createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string;};Defined in: core/services/keyvault.service.ts:144
Marks a key as revoked. The record is kept for audit; revoking is idempotent and cannot fail.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
record |
{ createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string; } |
The record to revoke. |
record.createdAt? |
string |
- |
record.id? |
string |
- |
record.label? |
string |
- |
record.note? |
string |
- |
record.provider? |
string |
- |
record.secret? |
string |
- |
record.status? |
"active" | "revoked" |
- |
record.updatedAt? |
string |
- |
Returns
Section titled “Returns”{ createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string;}The revoked record.
createdAt
Section titled “createdAt”createdAt: string;id: string;label: string;note?: string;provider
Section titled “provider”provider: string = KeyProviderSchema;secret
Section titled “secret”secret: string;status
Section titled “status”status: "active" | "revoked" = KeyStatusSchema;updatedAt
Section titled “updatedAt”updatedAt: string;useRotateKeySecret()
Section titled “useRotateKeySecret()”useRotateKeySecret(record, secret): SafeResult<{ createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string;}>;Defined in: core/services/keyvault.service.ts:105
Rotates a key’s secret, keeping the record (and its id) stable so every config that references it stays valid. Revoked keys cannot rotate: the caller must create a new record instead.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
record |
{ createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string; } |
The record to rotate. |
record.createdAt? |
string |
- |
record.id? |
string |
- |
record.label? |
string |
- |
record.note? |
string |
- |
record.provider? |
string |
- |
record.secret? |
string |
- |
record.status? |
"active" | "revoked" |
- |
record.updatedAt? |
string |
- |
secret |
string |
The replacement secret. |
Returns
Section titled “Returns”SafeResult<{
createdAt: string;
id: string;
label: string;
note?: string;
provider: string;
secret: string;
status: "active" | "revoked";
updatedAt: string;
}>
{ data, error, ok } — error.status = 409 when revoked.
getInstance()
Section titled “getInstance()”static getInstance(): KeyVaultService;Defined in: core/services/keyvault.service.ts:55
Returns the shared instance (Singleton).
Returns
Section titled “Returns”KeyVaultService