DOCS: Systematic overhaul of Literate source (Granularity & Technical Reasoning)
Some checks failed
Deploy-Agent-V15-Stdin / JOB-V15-STDIN (push) Failing after 2s
Some checks failed
Deploy-Agent-V15-Stdin / JOB-V15-STDIN (push) Failing after 2s
This commit is contained in:
@@ -1,67 +1,24 @@
|
||||
:PROPERTIES:
|
||||
:ID: credentials-vault-skill
|
||||
:CREATED: [2026-04-09 Thu]
|
||||
:END:
|
||||
#+TITLE: SKILL: Credentials Vault (Universal Literate Note)
|
||||
#+STARTUP: content
|
||||
#+AUTHOR: Amr
|
||||
#+FILETAGS: :auth:security:infrastructure:autonomy:
|
||||
#+DEPENDS_ON: id:state-persistence-skill
|
||||
#+STARTUP: content
|
||||
|
||||
* 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.
|
||||
|
||||
* Phase A: Demand (PRD)
|
||||
:PROPERTIES:
|
||||
:STATUS: SIGNED
|
||||
:END:
|
||||
|
||||
** 1. Purpose
|
||||
Securely manage all authentication tokens required for the opencortex to operate.
|
||||
|
||||
** 2. User Needs
|
||||
- *Unified Storage:* Single interface for API keys and Session Cookies.
|
||||
- *Masked Logging:* Ensure credentials never appear in plaintext in `harness-log`.
|
||||
- *Guided Onboarding:* Retain and improve the Google/Gemini cookie handshake.
|
||||
- *Persistence:* Securely save credentials to the Memory via Merkle-Tree snapshots.
|
||||
|
||||
* Phase B: Blueprint (PROTOCOL)
|
||||
:PROPERTIES:
|
||||
:STATUS: SIGNED
|
||||
:END:
|
||||
|
||||
** 1. Architectural Intent
|
||||
** 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.
|
||||
|
||||
** 2. Semantic Interfaces
|
||||
#+begin_src lisp
|
||||
(defun vault-get-secret (provider &key type)
|
||||
"Retrieves a secret (api-key or session) for a provider.")
|
||||
|
||||
(defun vault-set-secret (provider secret &key type)
|
||||
"Securely stores a secret and triggers a Merkle snapshot.")
|
||||
#+end_src
|
||||
|
||||
* Phase C: Success (QUALITY)
|
||||
:PROPERTIES:
|
||||
:STATUS: SIGNED
|
||||
:END:
|
||||
|
||||
** 1. Success Criteria
|
||||
- [ ] *No Plaintext Leaks:* Log output must use `[REDACTED]` for sensitive values.
|
||||
- [ ] *Merkle Integration:* Setting a secret must increment the Memory version.
|
||||
- [ ] *Dual-Path Auth:* Support both `:api-key` and `:session-cookies`.
|
||||
- [ ] *Onboarding Verification:* The cookie handshake successfully hydrates the vault.
|
||||
|
||||
** 2. TDD Plan
|
||||
Tests in `tests/vault-tests.lisp` will verify:
|
||||
1. Retrieval of keys from both `.env` (fallback) and Vault (primary).
|
||||
2. Redaction of keys in log strings.
|
||||
3. Successful version increment in the Memory after `vault-set-secret`.
|
||||
|
||||
* Phase D: Build (Implementation)
|
||||
|
||||
** Package Context
|
||||
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
|
||||
#+begin_src lisp
|
||||
(in-package :cl-user)
|
||||
(defpackage :opencortex.skills.org-skill-credentials-vault
|
||||
(:use :cl :opencortex))
|
||||
(in-package :opencortex.skills.org-skill-credentials-vault)
|
||||
#+end_src
|
||||
|
||||
** Vault State
|
||||
@@ -69,31 +26,33 @@ We maintain an in-memory hash table for secrets, which is hydrated from and pers
|
||||
|
||||
#+begin_src lisp
|
||||
(defvar opencortex::*vault-memory* (make-hash-table :test 'equal)
|
||||
"In-memory cache of sensitive credentials.")
|
||||
"In-memory cache of sensitive credentials, preventing constant disk I/O for auth.")
|
||||
#+end_src
|
||||
|
||||
** Helper: Secret Masking
|
||||
The `vault-mask-string` function ensures that diagnostic output never contains the full plaintext of a sensitive token.
|
||||
** 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.
|
||||
|
||||
#+begin_src lisp
|
||||
(defun vault-mask-string (str)
|
||||
"Returns a masked version of a sensitive string."
|
||||
"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]"))
|
||||
#+end_src
|
||||
|
||||
** Retrieval (vault-get-secret)
|
||||
This function is the secure getter for all system secrets. It prioritizes the Vault (Memory) and falls back to environment variables for legacy compatibility.
|
||||
The secure getter for all system secrets. It follows a strict priority:
|
||||
1. **Vault Memory:** High-integrity, versioned storage.
|
||||
2. **Environment Fallback:** OS-level variables for bootstrap and legacy compatibility.
|
||||
|
||||
#+begin_src lisp
|
||||
(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 val
|
||||
(if (and val (not (string= val "")))
|
||||
val
|
||||
;; Fallback to environment
|
||||
;; Fallback to environment mapping
|
||||
(let ((env-var (case provider
|
||||
((:gemini :gemini-api) "GEMINI_API_KEY")
|
||||
(:openai "OPENAI_API_KEY")
|
||||
@@ -110,73 +69,39 @@ This function is the secure getter for all system secrets. It prioritizes the Va
|
||||
#+end_src
|
||||
|
||||
** Persistence (vault-set-secret)
|
||||
When a secret is updated, we immediately snapshot the Memory to ensure the credential change is versioned and durable.
|
||||
When a secret is updated, we immediately snapshot the Memory to ensure the change is versioned and durable.
|
||||
|
||||
#+begin_src lisp
|
||||
(defun vault-set-secret (provider secret &key (type :api-key))
|
||||
"Securely stores a secret and triggers a Merkle snapshot."
|
||||
"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. Triggering Merkle snapshot..." type provider)
|
||||
(harness-log "VAULT: Updated ~a for ~a. Snapshotting memory." type provider)
|
||||
(snapshot-memory)
|
||||
t))
|
||||
#+end_src
|
||||
|
||||
** Onboarding Logic
|
||||
Retained from the legacy Google skill, this provides the instructions for the autonomous cookie handshake.
|
||||
** Automated Onboarding Instructions
|
||||
Provides instructions for the autonomous cookie handshake (retained from legacy components).
|
||||
|
||||
#+begin_src lisp
|
||||
(defun vault-onboard-gemini-web ()
|
||||
"Instructions for the Autonomous Cookie Handshake."
|
||||
"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));})();")
|
||||
(harness-log "PLATFORM GUIDE: Chrome/Firefox/Safari all support Bookmarklets via 'Add Page' or 'New Bookmark'.")
|
||||
t)
|
||||
#+end_src
|
||||
|
||||
** Registration
|
||||
** Skill Registration
|
||||
#+begin_src lisp
|
||||
(progn
|
||||
(defskill :skill-credentials-vault
|
||||
:priority 200 ; High priority, foundational
|
||||
:trigger (lambda (ctx) (eq (getf (getf ctx :payload) :sensor) :onboarding-request))
|
||||
:probabilistic nil
|
||||
:deterministic (lambda (action ctx)
|
||||
(vault-onboard-gemini-web)
|
||||
action)))
|
||||
(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))
|
||||
#+end_src
|
||||
|
||||
* Phase E: Chaos (Verification)
|
||||
|
||||
Note: Tests disabled in jail load.
|
||||
|
||||
** 1. Unit Tests (FiveAM)
|
||||
#+begin_src lisp
|
||||
#|
|
||||
(defpackage :opencortex-vault-tests
|
||||
(:use :cl :fiveam :opencortex))
|
||||
(in-package :opencortex-vault-tests)
|
||||
|
||||
(def-suite vault-suite :description "Tests for the Credentials Vault.")
|
||||
(in-suite vault-suite)
|
||||
|
||||
(test test-masking
|
||||
(is (equal "sk-t...-key" (opencortex::vault-mask-string "sk-test-key")))
|
||||
(is (equal "[REDACTED]" (opencortex::vault-mask-string "short"))))
|
||||
|
||||
(test test-vault-persistence
|
||||
"Verify that setting a secret triggers a snapshot (mock check)."
|
||||
(let ((old-version (opencortex::org-object-version (gethash "root" *memory*))))
|
||||
(opencortex:vault-set-secret :test "secret-val")
|
||||
(is (> (opencortex::org-object-version (gethash "root" *memory*)) old-version))))
|
||||
|#
|
||||
#+end_src
|
||||
|
||||
** 2. Chaos Scenarios
|
||||
- *Scenario A (Vault Poisoning):* Inject a malformed session string and verify the `llm-gateway` detects the invalid format and returns a standardized error instead of crashing.
|
||||
- *Scenario B (Memory Wipe):* Clear `opencortex::*vault-memory*` during runtime and verify the vault successfully re-hydrates from the Memory (or environment fallback).
|
||||
|
||||
* Phase F: Memory (RCA)
|
||||
- *[2026-04-09 Thu]:* Consolidated `auth-api-key` and `auth-google-oauth` into this vault. Introduced mandatory masking for all credential-related logging.
|
||||
|
||||
Reference in New Issue
Block a user