Skip to content

KeyVaultService

katanakit-js / 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.

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-••••••••••••1234
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.

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 -
{
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: 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;

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.

Parameter Type Description
input KeyRecordInput Provider, label and secret (plus an optional note).

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(): {
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.

{
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: 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;

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.

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.

| { createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string; } | undefined

The record, or undefined.


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.

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 -

{ createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string; }[]

The matching records.


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.

Parameter Type Description
secret string The secret to mask.

string

The masked form.


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.

Parameter Type Description
provider string The provider slug.

string

The environment variable name.


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.

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 -
{
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: 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;

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.

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 -
{
createdAt: string;
id: string;
label: string;
note?: string;
provider: string;
secret: string;
status: "active" | "revoked";
updatedAt: string;
}

The revoked record.

createdAt: string;
id: string;
label: string;
note?: string;
provider: string = KeyProviderSchema;
secret: string;
status: "active" | "revoked" = KeyStatusSchema;
updatedAt: string;

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.

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.

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.


static getInstance(): KeyVaultService;

Defined in: core/services/keyvault.service.ts:55

Returns the shared instance (Singleton).

KeyVaultService