# How k-skill Handles Sensitive Data and Credentials: A Tiered Security Architecture

> Discover how k-skill secures sensitive data and credentials with its five-tier architecture. Learn how this strategy protects LLMs by avoiding plaintext exposure, prioritizing agent-hosted vaults.

- Repository: [NomaDamas/k-skill](https://github.com/NomaDamas/k-skill)
- Tags: architecture
- Published: 2026-08-03

---

**k-skill protects secrets through a five-tier resolution strategy that never exposes plaintext values to the LLM, utilizing agent-hosted vaults first and falling back to permission-locked local files only when necessary.**

The open-source **k-skill** framework (available at `NomaDamas/k-skill`) implements a defense-in-depth approach to credential management designed specifically for AI agent runtimes. When building skills that interact with external APIs and sensitive services, understanding how k-skill handles sensitive data and credentials securely ensures your agents operate with minimal attack surface and maximum auditability.

## The Five-Tier Credential Resolution Strategy

The runtime resolves credentials through a strictly ordered hierarchy defined in [`docs/security-and-secrets.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/security-and-secrets.md). This tiered approach ensures the most secure storage option is always attempted before falling back to less privileged alternatives.

**Tier 1: Dolshoi Vault Mode**

When `DOLSHOI_ACTION_BROKER_URL` is defined and the `vault-run` capability is available, k-skill connects directly to the provisioned agent-hosted vault (such as 1Password, Bitwarden, or macOS Keychain). The LLM never receives the plaintext ID, password, or API key; the runtime retrieves values directly from the vault process.

**Tier 2: Interactive Vault Provisioning**

If the vault capability is absent, the runtime invokes the `request_vault_credential` tool. This opens the host machine's native vault UI, allowing the user to supply the secret securely. The system stores the credential in the vault and automatically retries the original action without exposing the plaintext value to the agent.

**Tier 3: Generic Injected Secrets**

In non-Dolshoi environments, k-skill utilizes secrets already injected via environment variables or the host-level vault. These values remain in process memory and are never logged or transmitted to the language model.

**Tier 4: Local Dotenv Fallback**

When no injected secrets exist, the runtime reads from `~/.config/k-skill/secrets.env`. This plain-dotenv file must be created with permissions `0600` (read/write for owner only) and is excluded from version control via `.gitignore`. The framework enforces this permission level to prevent unauthorized access.

**Tier 5: Secure User Prompting**

If no credential source yields a value, k-skill requests the secret through the safest available input surface (such as a secure UI dialog). The system stores the response in either the vault or the dotenv file, ensuring the plaintext is never echoed back to the LLM or logged in conversation history.

## Core Security Guarantees

The implementation enforces strict policies to prevent credential leakage:

*   **Never output plaintext secrets** – All snapshots and tests assert that the model does not ask for, print, or store raw secret values according to the runtime contract.
*   **Least-privilege storage** – The fallback dotenv file at `~/.config/k-skill/secrets.env` requires mode `0600` and explicit exclusion from git repositories.
*   **Explicit secret naming** – Only a curated list of well-known variable names (such as `KSKILL_SRT_ID` and `KSKILL_KOSIS_API_KEY`) is permitted, reducing the attack surface against arbitrary secret injection.
*   **No secret-driven workarounds** – If a required secret is missing, the system never switches to unofficial APIs or hard-coded credentials; it strictly prompts the user for safe provisioning.
*   **Portable fallback compatibility** – Non-Dolshoi runtimes maintain backward compatibility using standard environment-variable conventions while preserving the same security boundaries.

## Runtime Implementation and Auditing

All top-level [`SKILL.md`](https://github.com/NomaDamas/k-skill/blob/main/SKILL.md) files include a **"Runtime contract (required)"** block that codifies these policies. The [`docs/runtime-action-audit.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/runtime-action-audit.md) document verifies that each skill respects the credential flow and contains no unauthorized secret handling patterns.

The `getCredential` function in the runtime package encapsulates the resolution order. Skills import this helper to ensure consistent security behavior:

```typescript
// Resolve credentials for a SRT booking skill
import { getCredential } from "@nomadamas/k-skill-runtime";

/* Attempt Dolshoi vault first, then fall back to env/dotenv */
const srtId = await getCredential("KSKILL_SRT_ID");
const srtPwd = await getCredential("KSKILL_SRT_PASSWORD");

/* 
 * If credentials are missing, the runtime automatically invokes 
 * request_vault_credential and retries without exposing values 
 * to the LLM context.
 */

```

This helper ensures that even if a skill author forgets to check for vault capabilities, the runtime intercepts the request and routes it through the safest available channel.

## Local Development and Fallback Configuration

For development environments without vault capabilities, create the fallback secrets file with strict permissions:

```bash

# Create the config directory

mkdir -p ~/.config/k-skill

# Write secrets with restricted permissions

cat > ~/.config/k-skill/secrets.env <<'EOS'
KSKILL_SRT_ID=my-srt-id
KSKILL_SRT_PASSWORD=my-srt-pwd
KSKILL_KOSIS_API_KEY=my-api-key
EOS

# Enforce owner-only access (required by k-skill)

chmod 600 ~/.config/k-skill/secrets.env

```

The runtime validates these permissions at startup. If the file is readable by group or others, k-skill refuses to load the credentials and exits with a security error.

## Summary

- k-skill implements a **five-tier hierarchy** for credential resolution, prioritizing agent-hosted vaults over local files.
- The **LLM never sees plaintext secrets**; all values resolve through secure channels or user prompts outside the model context.
- **Permission enforcement** ensures fallback files use mode `0600` and remain excluded from version control.
- **Explicit allowlisting** of variable names prevents arbitrary secret exfiltration.
- **Runtime auditing** via [`SKILL.md`](https://github.com/NomaDamas/k-skill/blob/main/SKILL.md) contracts and [`docs/runtime-action-audit.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/runtime-action-audit.md) ensures compliance across all skills.

## Frequently Asked Questions

### Does k-skill ever send my passwords or API keys to the LLM?

No. The framework architecture ensures that raw credential values never enter the LLM context window. When using Dolshoi mode, the runtime retrieves secrets directly from the vault process. In fallback scenarios, the system either reads from environment variables or prompts the user through secure OS-level dialogs, storing results in `~/.config/k-skill/secrets.env` without echoing them back to the conversation.

### What happens if I don't have a password manager installed?

k-skill falls back to environment variables or the local `secrets.env` file. If neither exists, the runtime invokes `request_vault_credential` to open your system's native credential UI. If no vault is available, it prompts for the secret through the safest input method supported by your operating system, then stores it in the local dotenv file with `0600` permissions for future use.

### Why does k-skill require `0600` permissions on the secrets file?

The `0600` permission bit (read/write for owner only) ensures that no other user or process on the system can access your stored credentials. k-skill validates these permissions before loading `~/.config/k-skill/secrets.env`. If the file is group-readable or world-readable, the runtime exits immediately to prevent accidental credential exposure in shared or compromised environments.

### Which specific environment variables does k-skill support?

k-skill uses an explicit allowlist defined in [`docs/security-and-secrets.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/security-and-secrets.md). Common variables include `KSKILL_SRT_ID`, `KSKILL_SRT_PASSWORD`, and `KSKILL_KOSIS_API_KEY`. This restricted naming convention prevents skills from requesting arbitrary secrets outside their intended scope, reducing the risk of credential stuffing attacks or unintended data exfiltration.