SKILL: Credentials Vault (Universal Literate Note)

Overview
- Architectural Intent: The Secure Enclave
Implementation

Overview

The Credentials Vault is the high-security enclave for the OpenCortex. It centralizes the management of LLM API keys, OAuth sessions, and browser cookies. By consolidating these into a single vault, we ensure that sensitive tokens are handled with uniform masking, validation, and Merkle-integrated persistence.

Architectural Intent: The Secure Enclave

The vault provides a secure lookup table in RAM, backed by the persistent Memory. Access is restricted to internal kernel requests and explicitly authorized deterministic gates.

The primary goal of the vault is to prevent "Credential Bleed"—the accidental leaking of API keys into logs, terminal history, or neural contexts. It achieves this by providing a unified getter that automatically masks its output for diagnostic use.

Implementation

Package Initialization

(in-package :cl-user)
(defpackage :opencortex.skills.org-skill-credentials-vault
  (:use :cl :opencortex))
(in-package :opencortex.skills.org-skill-credentials-vault)

Vault State

We maintain an in-memory hash table for secrets, which is hydrated from and persisted to the Memory.

(defvar opencortex::*vault-memory* (make-hash-table :test 'equal)
  "In-memory cache of sensitive credentials, preventing constant disk I/O for auth.")

Helper: Secret Masking (vault-mask-string)

Ensures that diagnostic output never contains the full plaintext of a sensitive token. Used by the harness and gateways for transparent but safe logging.

(defun vault-mask-string (str)
  "Returns a masked version of a sensitive string. (e.g. sk-a...3f9)"
  (if (and str (> (length str) 8))
      (format nil "~a...~a" (subseq str 0 4) (subseq str (- (length str) 4)))
      "[REDACTED]"))

Retrieval (vault-get-secret)

The secure getter for all system secrets. It follows a strict priority:

Vault Memory: High-integrity, versioned storage.
Environment Fallback: OS-level variables for bootstrap and legacy compatibility.

(defun vault-get-secret (provider &key (type :api-key))
  "Retrieves a credential. Type can be :api-key or :session."
  (let* ((key (format nil "~a-~a" provider type))
         (val (gethash key opencortex::*vault-memory*)))
    (if (and val (not (string= val "")))
        val
        ;; Fallback to environment mapping
        (let ((env-var (case provider
                         ((:gemini :gemini-api) "GEMINI_API_KEY")
                         (:openai "OPENAI_API_KEY")
                         (:anthropic "ANTHROPIC_API_KEY")
                         (:groq "GROQ_API_KEY")
                         (:openrouter "OPENROUTER_API_KEY")
                         (:telegram "TELEGRAM_BOT_TOKEN")
                         (:signal "SIGNAL_ACCOUNT_NUMBER")
                         (:matrix-homeserver "MATRIX_HOMESERVER")
                         (:matrix-token "MATRIX_ACCESS_TOKEN")
                         (t nil))))
          (when (and env-var (eq type :api-key))
            (uiop:getenv env-var))))))

Persistence (vault-set-secret)

When a secret is updated, we immediately snapshot the Memory to ensure the change is versioned and durable.

(defun vault-set-secret (provider secret &key (type :api-key))
  "Securely stores a secret and triggers a Merkle snapshot for durability."
  (let ((key (format nil "~a-~a" provider type)))
    (setf (gethash key opencortex::*vault-memory*) secret)
    (harness-log "VAULT: Updated ~a for ~a. Snapshotting memory." type provider)
    (snapshot-memory)
    t))

Automated Onboarding Instructions

Provides instructions for the autonomous cookie handshake (retained from legacy components).

(defun vault-onboard-gemini-web ()
  "Displays instructions for the Gemini Web cookie handshake."
  (harness-log "--- GEMINI WEB ONBOARDING ---")
  (harness-log "1. Visit gemini.google.com")
  (harness-log "2. Run the 'Get Gemini Cookies' Bookmarklet.")
  (harness-log "   CODE: javascript:(function(){const c=document.cookie.split('; ').reduce((r,v)=>{const [n,val]=v.split('=');r[n]=val;return r},{});const target=['__Secure-1PSID','__Secure-1PSIDTS'];const out=target.map(n=>({name:n,value:c[n]}));prompt('Copy JSON:',JSON.stringify(out));})();")
  t)

Skill Registration

(defskill :skill-credentials-vault
  :priority 200 ; Foundational Priority
  :trigger (lambda (ctx) (eq (getf (getf ctx :payload) :sensor) :onboarding-request))
  :probabilistic nil
  :deterministic (lambda (action ctx) 
              (declare (ignore ctx))
              (vault-onboard-gemini-web)
              action))

4.7 KiB Raw Blame History