amr/passepartout
1
0
Fork 0
Code Issues 15 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: finalize verbose Harness Protocol revamp and modernized diagram

Browse Source
This commit is contained in:
Amr Gharbeia
2026-04-12 19:14:33 -04:00
parent 8018d59fe3
commit a59f7c6472
2 changed files with 38 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
src/protocol.lisp
View File

@@ -4,16 +4,16 @@
"Global registry mapping target keywords to their physical actuator functions.")
(defun register-actuator (name fn)
"Registers an actuator function. Actuators receive two arguments: (ACTION CONTEXT)."
"Registers an actuator function. Actuators receive: (ACTION CONTEXT)."
(setf (gethash name *actuator-registry*) fn))
(defun frame-message (msg-string)
"Prefix MSG-STRING with a 6-character hex length (lowercase).
If HARNESS_PROTOCOL_ENFORCE_HMAC is true, it prefixes a 64-char HMAC signature."
"Prefixes MSG-STRING with a 6-character hex length.
If security is enabled, prefixes a 64-char HMAC-SHA256 signature."
(let ((len (length msg-string))
(enforce-hmac (uiop:getenv "HARNESS_PROTOCOL_ENFORCE_HMAC")))
(if (and enforce-hmac (string-equal enforce-hmac "true"))
(let* ((secret (or (uiop:getenv "HARNESS_PROTOCOL_HMAC_SECRET") "default-insecure-secret"))
(let* ((secret (or (uiop:getenv "HARNESS_PROTOCOL_HMAC_SECRET") "default-insecure-key"))
(key (ironclad:ascii-string-to-byte-array secret))
(hmac (ironclad:make-mac :hmac key :sha256))
(payload-bytes (ironclad:ascii-string-to-byte-array msg-string)))
@@ -23,14 +23,14 @@
(format nil "~(~6,'0x~)~a" len msg-string))))
(defun parse-message (framed-string)
"Extract and parse the S-expression from a framed string, securely preventing reader macro injection."
"Extracts and parses the S-expression from a framed string securely."
(when (< (length framed-string) 6)
(error "Framed string too short"))
(let* ((enforce-hmac (uiop:getenv "HARNESS_PROTOCOL_ENFORCE_HMAC"))
(use-hmac (and enforce-hmac (string-equal enforce-hmac "true")))
(prefix-len (if use-hmac 70 6)))
(when (< (length framed-string) prefix-len)
(error "Framed string too short for Harness Protocol signature/length"))
(error "Framed string too short for Harness Protocol prefix"))
(let* ((len-str (subseq framed-string 0 6))
(signature (when use-hmac (subseq framed-string 6 70)))
@@ -41,25 +41,24 @@
(unless (= expected-len (length actual-msg))
(error "Message length mismatch. Expected ~a, got ~a" expected-len (length actual-msg)))
;; HMAC Validation Foundation
(when use-hmac
(let* ((secret (or (uiop:getenv "HARNESS_PROTOCOL_HMAC_SECRET") "default-insecure-secret"))
(let* ((secret (or (uiop:getenv "HARNESS_PROTOCOL_HMAC_SECRET") "default-insecure-key"))
(key (ironclad:ascii-string-to-byte-array secret))
(hmac (ironclad:make-mac :hmac key :sha256))
(payload-bytes (ironclad:ascii-string-to-byte-array actual-msg)))
(ironclad:update-mac hmac payload-bytes)
(let ((expected-signature (ironclad:byte-array-to-hex-string (ironclad:produce-mac hmac))))
(unless (string-equal signature expected-signature)
(error "Harness Protocol Integrity Failure: HMAC signature mismatch")))))
(error "Harness Protocol Integrity Failure: HMAC mismatch")))))
;; SECURITY: Prevent Reader Macro Injection (e.g. #. ) during deserialization
;; SECURITY: Disable the reader's ability to execute code during parsing
(let ((*read-eval* nil))
(let ((msg (read-from-string actual-msg)))
(validate-harness-protocol-schema msg)
msg)))))
(defun make-hello-message (version)
"Construct the standard HELLO handshake message."
"Constructs the standard HELLO handshake message."
(list :type :EVENT
:payload (list :action :handshake
:version version