molt-cipher-bridge 1.3.1__tar.gz → 1.4.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (16) hide show
  1. molt_cipher_bridge-1.4.2/PKG-INFO +189 -0
  2. molt_cipher_bridge-1.4.2/README.md +173 -0
  3. {molt_cipher_bridge-1.3.1 → molt_cipher_bridge-1.4.2}/pyproject.toml +1 -1
  4. molt_cipher_bridge-1.4.2/src/molt_cipher_bridge.egg-info/PKG-INFO +189 -0
  5. molt_cipher_bridge-1.4.2/src/molt_cipher_bridge.py +251 -0
  6. molt_cipher_bridge-1.3.1/PKG-INFO +0 -134
  7. molt_cipher_bridge-1.3.1/README.md +0 -118
  8. molt_cipher_bridge-1.3.1/src/molt_cipher_bridge.egg-info/PKG-INFO +0 -134
  9. molt_cipher_bridge-1.3.1/src/molt_cipher_bridge.py +0 -151
  10. {molt_cipher_bridge-1.3.1 → molt_cipher_bridge-1.4.2}/LICENSE +0 -0
  11. {molt_cipher_bridge-1.3.1 → molt_cipher_bridge-1.4.2}/setup.cfg +0 -0
  12. {molt_cipher_bridge-1.3.1 → molt_cipher_bridge-1.4.2}/src/molt_cipher_bridge.egg-info/SOURCES.txt +0 -0
  13. {molt_cipher_bridge-1.3.1 → molt_cipher_bridge-1.4.2}/src/molt_cipher_bridge.egg-info/dependency_links.txt +0 -0
  14. {molt_cipher_bridge-1.3.1 → molt_cipher_bridge-1.4.2}/src/molt_cipher_bridge.egg-info/entry_points.txt +0 -0
  15. {molt_cipher_bridge-1.3.1 → molt_cipher_bridge-1.4.2}/src/molt_cipher_bridge.egg-info/requires.txt +0 -0
  16. {molt_cipher_bridge-1.3.1 → molt_cipher_bridge-1.4.2}/src/molt_cipher_bridge.egg-info/top_level.txt +0 -0
molt_cipher_bridge-1.4.2/PKG-INFO ADDED
@@ -0,0 +1,189 @@
1
+ Metadata-Version: 2.4
2
+ Name: molt-cipher-bridge
3
+ Version: 1.4.2
4
+ Summary: A cryptographic standard for secure Agent-to-Agent (A2A) communication.
5
+ Author-email: Satyaa & Clawdy <clawdy@openclaw.ai>
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/CrimsonDevil333333/molt-cipher-bridge
8
+ Project-URL: Bug Tracker, https://github.com/CrimsonDevil333333/molt-cipher-bridge/issues
9
+ Classifier: Programming Language :: Python :: 3
10
+ Classifier: Operating System :: OS Independent
11
+ Requires-Python: >=3.8
12
+ Description-Content-Type: text/markdown
13
+ License-File: LICENSE
14
+ Requires-Dist: cryptography>=42.0.0
15
+ Dynamic: license-file
16
+
17
+ # 🦞 Molt-Cipher-Bridge (v1.4.2)
18
+
19
+ [![PyPI version](https://img.shields.io/pypi/v/molt-cipher-bridge.svg)](https://pypi.org/project/molt-cipher-bridge/)
20
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
21
+
22
+ **Molt-Cipher-Bridge** is a cryptographic standard designed for secure **Agent-to-Agent (A2A)** communication and "Sealed Intents." It enables task fragments to be encrypted at the source and decrypted only at the execution destination, keeping sensitive logic entirely out of persistent logs.
23
+
24
+ ---
25
+
26
+ ## 🛡️ The Zero-Log Protocol (MANDATORY)
27
+ We operate on a **Zero-Trust Policy**. Agents must never handle plaintext secrets in command arguments or shell history.
28
+
29
+ ### 1. Zero-Trust Sealing (Sender)
30
+ **NEVER use `echo "SECRET" > file` to create secret files.** This leaves the secret permanently in your shell history (`.bash_history`) and system logs.
31
+
32
+ **The Secure Workflow:**
33
+ 1. **Request from Human**: If you need a new secret, define a file path and ask your human to manually place the secret data (JSON, .env, or plain text) there.
34
+ 2. **Point to File**: Use the `--file` flag to seal the intent directly from that path.
35
+ 3. **Purge with Caution**:
36
+ * **Temp Files**: If you created a one-time temporary file, delete it immediately after sealing.
37
+ * **System/Important Configs**: **NEVER** delete system files, user configurations, or important `.env` files that were already present.
38
+
39
+ ```bash
40
+ # Seal secrets from a file manually placed by the human
41
+ molt-cipher seal --key "$KEY" --sender "Orchestrator" --to "Worker" --file ./secrets.json
42
+ ```
43
+
44
+ ### 2. Zero-Log Execution (Worker)
45
+ **Never print unsealed secrets.** Use the `run` command to inject them directly into RAM via environment variables or templates.
46
+
47
+ ```bash
48
+ # Standard ENV injection ($VAR)
49
+ molt-cipher run --key "$KEY" --fragment "$FRAG" --cmd "echo \$SECRET_VAL"
50
+
51
+ # Direct Argument Injection ({VAR})
52
+ molt-cipher run --key "$KEY" --fragment "$FRAG" --cmd "python3 api.py --key {API_KEY}"
53
+ ```
54
+
55
+ ---
56
+
57
+ ## ⚡ Quick Start for Agents
58
+ Bootstrap your environment, install the tool, and learn the protocol:
59
+ ```bash
60
+ curl -sSL https://raw.githubusercontent.com/CrimsonDevil333333/molt-cipher-bridge/master/bootstrap_agent.sh | bash
61
+ ```
62
+
63
+ ---
64
+
65
+ ## 🚀 Installation
66
+
67
+ ### 🛠️ Linux (Recommended)
68
+ Use `pipx` to install as a standalone CLI tool without environment conflicts:
69
+ ```bash
70
+ pipx install molt-cipher-bridge
71
+ ```
72
+
73
+ ### 📦 Standard Pip
74
+ ```bash
75
+ pip install molt-cipher-bridge
76
+ ```
77
+
78
+ ---
79
+
80
+ ## 🛠️ Usage Examples
81
+
82
+ ### 🔑 1. Generating a Shared Key
83
+ Agents must share a key (passed via secure channel or human handoff) to communicate.
84
+ ```bash
85
+ # Generate a secure Fernet key
86
+ python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
87
+ ```
88
+
89
+ ### 🧪 2. Generating Samples
90
+ Bots can ask users for secrets by providing a template:
91
+ ```bash
92
+ # Generate an .env template
93
+ molt-cipher sample --type env --out secrets.sample
94
+
95
+ # Generate a JSON template
96
+ molt-cipher sample --type json --out secrets.sample
97
+ ```
98
+
99
+ ### 🔐 3. Sealing Different File Types
100
+ ```bash
101
+ # Seal a .env file (parsed automatically by 'run')
102
+ molt-cipher seal --key "$KEY" --sender "A" --to "B" --file .env
103
+
104
+ # Seal a binary file (e.g., an SSH key)
105
+ molt-cipher seal --key "$KEY" --sender "A" --to "B" --file id_rsa --binary
106
+ ```
107
+
108
+ ### ⚡ 4. Selective Running (Least Privilege)
109
+ Only expose specific secrets to a command, even if the fragment contains many:
110
+ ```bash
111
+ # Only inject DB_URL and DB_USER
112
+ molt-cipher run --key "$KEY" --fragment "$FRAG" --pick "DB_URL,DB_USER" --cmd "psql {DB_URL}"
113
+ ```
114
+
115
+ ### 🔓 5. Unsealing to File
116
+ Restore the original file content securely:
117
+ ```bash
118
+ molt-cipher unseal --key "$KEY" --fragment "$FRAG" --out restored_key.pem
119
+ ```
120
+
121
+ ---
122
+
123
+ ## 📖 Full CLI Reference
124
+
125
+ ### `seal`
126
+ Encrypts data into a JSON fragment.
127
+ - `--key`: (Required) 32-byte base64-encoded Fernet key.
128
+ - `--sender`: (Required) ID of the sending agent.
129
+ - `--to`: (Required) ID of the recipient agent.
130
+ - `--file`: Path to file containing secrets (LOG-SAFE).
131
+ - `--data`: Raw JSON/String data (⚠️ LEAKS IN LOGS).
132
+ - `--ttl`: Time-to-Live in seconds (Default: 300).
133
+ - `--binary`: Treat input as raw binary (required for keys/blobs).
134
+
135
+ ### `unseal`
136
+ Decrypts and retrieves the content of a fragment.
137
+ - `--key`: (Required) The shared Fernet key.
138
+ - `--fragment`: (Required) JSON fragment string or path to fragment file.
139
+ - `--out`: Write output directly to this file path.
140
+ - `--ignore-expiry`: Bypass TTL check (Debug only).
141
+
142
+ ### `run`
143
+ Executes a command with secrets injected into the ephemeral environment.
144
+ - `--key`: (Required) The shared Fernet key.
145
+ - `--fragment`: (Required) JSON fragment string or path to fragment file.
146
+ - `--cmd`: (Required) The shell command to execute.
147
+ - `--pick`: Comma-separated list of keys to inject.
148
+ - `--ignore-expiry`: Bypass TTL check.
149
+
150
+ ### `sample`
151
+ Creates boilerplate secret files.
152
+ - `--type`: `env` or `json`.
153
+ - `--out`: Destination file path.
154
+
155
+ ---
156
+
157
+ ## 🧪 Real-World Agent Scenarios
158
+
159
+ ### Scenario: Secure API Deployment (Verified 2026-02-06)
160
+ 1. **Preparation**: Human creates `prod.env` with `API_KEY` and `DB_URL`.
161
+ 2. **Sealing**: Orchestrator runs `molt-cipher seal --file prod.env` and sends the fragment to the Deployer agent.
162
+ 3. **Deployment**: Deployer agent runs `molt-cipher run --cmd "docker-compose up -d"` using the fragment.
163
+ 4. **Result**: Secrets were never logged in the Orchestrator's trace or the host's `.bash_history`.
164
+
165
+ ### Scenario: Multi-Agent Handoff (Verified 2026-02-06)
166
+ 1. **Goal**: Pass a GitHub Token from Orchestrator to Worker.
167
+ 2. **Workflow**:
168
+ - Orchestrator seals the token into a fragment.
169
+ - Worker bootstraps using `bootstrap_agent.sh`.
170
+ - Worker executes `molt-cipher run --fragment fragment.json --cmd "echo \$GH_TOKEN"` (or use `{GH_TOKEN}` template).
171
+ 3. **Success**: Worker accessed the secret in ephemeral RAM; zero plaintext in chat or system logs.
172
+
173
+ ---
174
+
175
+ ## 🧠 Permanent Agent Memory
176
+ 1. **No `echo`**: Plaintext secrets in shell history = Critical Failure.
177
+ 2. **Handoff**: Human File -> Seal `--file` -> Selective Purge (Temp only).
178
+ 3. **Running**: Fragment -> Run -> RAM Injection (`$VAR` or `{VAR}`).
179
+ 4. **Integrity**: Never delete files you didn't create or important system configs.
180
+
181
+ ---
182
+
183
+ ## 🔗 Links
184
+ - **PyPI**: [https://pypi.org/project/molt-cipher-bridge/](https://pypi.org/project/molt-cipher-bridge/)
185
+ - **Source**: [https://github.com/CrimsonDevil333333/molt-cipher-bridge](https://github.com/CrimsonDevil333333/molt-cipher-bridge)
186
+ - **Philosophy**: [SOUL.md](./SOUL.md)
187
+
188
+ ---
189
+ *Developed by Clawdy & Satyaa* 🦞✨
molt_cipher_bridge-1.4.2/README.md ADDED
@@ -0,0 +1,173 @@
1
+ # 🦞 Molt-Cipher-Bridge (v1.4.2)
2
+
3
+ [![PyPI version](https://img.shields.io/pypi/v/molt-cipher-bridge.svg)](https://pypi.org/project/molt-cipher-bridge/)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5
+
6
+ **Molt-Cipher-Bridge** is a cryptographic standard designed for secure **Agent-to-Agent (A2A)** communication and "Sealed Intents." It enables task fragments to be encrypted at the source and decrypted only at the execution destination, keeping sensitive logic entirely out of persistent logs.
7
+
8
+ ---
9
+
10
+ ## 🛡️ The Zero-Log Protocol (MANDATORY)
11
+ We operate on a **Zero-Trust Policy**. Agents must never handle plaintext secrets in command arguments or shell history.
12
+
13
+ ### 1. Zero-Trust Sealing (Sender)
14
+ **NEVER use `echo "SECRET" > file` to create secret files.** This leaves the secret permanently in your shell history (`.bash_history`) and system logs.
15
+
16
+ **The Secure Workflow:**
17
+ 1. **Request from Human**: If you need a new secret, define a file path and ask your human to manually place the secret data (JSON, .env, or plain text) there.
18
+ 2. **Point to File**: Use the `--file` flag to seal the intent directly from that path.
19
+ 3. **Purge with Caution**:
20
+ * **Temp Files**: If you created a one-time temporary file, delete it immediately after sealing.
21
+ * **System/Important Configs**: **NEVER** delete system files, user configurations, or important `.env` files that were already present.
22
+
23
+ ```bash
24
+ # Seal secrets from a file manually placed by the human
25
+ molt-cipher seal --key "$KEY" --sender "Orchestrator" --to "Worker" --file ./secrets.json
26
+ ```
27
+
28
+ ### 2. Zero-Log Execution (Worker)
29
+ **Never print unsealed secrets.** Use the `run` command to inject them directly into RAM via environment variables or templates.
30
+
31
+ ```bash
32
+ # Standard ENV injection ($VAR)
33
+ molt-cipher run --key "$KEY" --fragment "$FRAG" --cmd "echo \$SECRET_VAL"
34
+
35
+ # Direct Argument Injection ({VAR})
36
+ molt-cipher run --key "$KEY" --fragment "$FRAG" --cmd "python3 api.py --key {API_KEY}"
37
+ ```
38
+
39
+ ---
40
+
41
+ ## ⚡ Quick Start for Agents
42
+ Bootstrap your environment, install the tool, and learn the protocol:
43
+ ```bash
44
+ curl -sSL https://raw.githubusercontent.com/CrimsonDevil333333/molt-cipher-bridge/master/bootstrap_agent.sh | bash
45
+ ```
46
+
47
+ ---
48
+
49
+ ## 🚀 Installation
50
+
51
+ ### 🛠️ Linux (Recommended)
52
+ Use `pipx` to install as a standalone CLI tool without environment conflicts:
53
+ ```bash
54
+ pipx install molt-cipher-bridge
55
+ ```
56
+
57
+ ### 📦 Standard Pip
58
+ ```bash
59
+ pip install molt-cipher-bridge
60
+ ```
61
+
62
+ ---
63
+
64
+ ## 🛠️ Usage Examples
65
+
66
+ ### 🔑 1. Generating a Shared Key
67
+ Agents must share a key (passed via secure channel or human handoff) to communicate.
68
+ ```bash
69
+ # Generate a secure Fernet key
70
+ python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
71
+ ```
72
+
73
+ ### 🧪 2. Generating Samples
74
+ Bots can ask users for secrets by providing a template:
75
+ ```bash
76
+ # Generate an .env template
77
+ molt-cipher sample --type env --out secrets.sample
78
+
79
+ # Generate a JSON template
80
+ molt-cipher sample --type json --out secrets.sample
81
+ ```
82
+
83
+ ### 🔐 3. Sealing Different File Types
84
+ ```bash
85
+ # Seal a .env file (parsed automatically by 'run')
86
+ molt-cipher seal --key "$KEY" --sender "A" --to "B" --file .env
87
+
88
+ # Seal a binary file (e.g., an SSH key)
89
+ molt-cipher seal --key "$KEY" --sender "A" --to "B" --file id_rsa --binary
90
+ ```
91
+
92
+ ### ⚡ 4. Selective Running (Least Privilege)
93
+ Only expose specific secrets to a command, even if the fragment contains many:
94
+ ```bash
95
+ # Only inject DB_URL and DB_USER
96
+ molt-cipher run --key "$KEY" --fragment "$FRAG" --pick "DB_URL,DB_USER" --cmd "psql {DB_URL}"
97
+ ```
98
+
99
+ ### 🔓 5. Unsealing to File
100
+ Restore the original file content securely:
101
+ ```bash
102
+ molt-cipher unseal --key "$KEY" --fragment "$FRAG" --out restored_key.pem
103
+ ```
104
+
105
+ ---
106
+
107
+ ## 📖 Full CLI Reference
108
+
109
+ ### `seal`
110
+ Encrypts data into a JSON fragment.
111
+ - `--key`: (Required) 32-byte base64-encoded Fernet key.
112
+ - `--sender`: (Required) ID of the sending agent.
113
+ - `--to`: (Required) ID of the recipient agent.
114
+ - `--file`: Path to file containing secrets (LOG-SAFE).
115
+ - `--data`: Raw JSON/String data (⚠️ LEAKS IN LOGS).
116
+ - `--ttl`: Time-to-Live in seconds (Default: 300).
117
+ - `--binary`: Treat input as raw binary (required for keys/blobs).
118
+
119
+ ### `unseal`
120
+ Decrypts and retrieves the content of a fragment.
121
+ - `--key`: (Required) The shared Fernet key.
122
+ - `--fragment`: (Required) JSON fragment string or path to fragment file.
123
+ - `--out`: Write output directly to this file path.
124
+ - `--ignore-expiry`: Bypass TTL check (Debug only).
125
+
126
+ ### `run`
127
+ Executes a command with secrets injected into the ephemeral environment.
128
+ - `--key`: (Required) The shared Fernet key.
129
+ - `--fragment`: (Required) JSON fragment string or path to fragment file.
130
+ - `--cmd`: (Required) The shell command to execute.
131
+ - `--pick`: Comma-separated list of keys to inject.
132
+ - `--ignore-expiry`: Bypass TTL check.
133
+
134
+ ### `sample`
135
+ Creates boilerplate secret files.
136
+ - `--type`: `env` or `json`.
137
+ - `--out`: Destination file path.
138
+
139
+ ---
140
+
141
+ ## 🧪 Real-World Agent Scenarios
142
+
143
+ ### Scenario: Secure API Deployment (Verified 2026-02-06)
144
+ 1. **Preparation**: Human creates `prod.env` with `API_KEY` and `DB_URL`.
145
+ 2. **Sealing**: Orchestrator runs `molt-cipher seal --file prod.env` and sends the fragment to the Deployer agent.
146
+ 3. **Deployment**: Deployer agent runs `molt-cipher run --cmd "docker-compose up -d"` using the fragment.
147
+ 4. **Result**: Secrets were never logged in the Orchestrator's trace or the host's `.bash_history`.
148
+
149
+ ### Scenario: Multi-Agent Handoff (Verified 2026-02-06)
150
+ 1. **Goal**: Pass a GitHub Token from Orchestrator to Worker.
151
+ 2. **Workflow**:
152
+ - Orchestrator seals the token into a fragment.
153
+ - Worker bootstraps using `bootstrap_agent.sh`.
154
+ - Worker executes `molt-cipher run --fragment fragment.json --cmd "echo \$GH_TOKEN"` (or use `{GH_TOKEN}` template).
155
+ 3. **Success**: Worker accessed the secret in ephemeral RAM; zero plaintext in chat or system logs.
156
+
157
+ ---
158
+
159
+ ## 🧠 Permanent Agent Memory
160
+ 1. **No `echo`**: Plaintext secrets in shell history = Critical Failure.
161
+ 2. **Handoff**: Human File -> Seal `--file` -> Selective Purge (Temp only).
162
+ 3. **Running**: Fragment -> Run -> RAM Injection (`$VAR` or `{VAR}`).
163
+ 4. **Integrity**: Never delete files you didn't create or important system configs.
164
+
165
+ ---
166
+
167
+ ## 🔗 Links
168
+ - **PyPI**: [https://pypi.org/project/molt-cipher-bridge/](https://pypi.org/project/molt-cipher-bridge/)
169
+ - **Source**: [https://github.com/CrimsonDevil333333/molt-cipher-bridge](https://github.com/CrimsonDevil333333/molt-cipher-bridge)
170
+ - **Philosophy**: [SOUL.md](./SOUL.md)
171
+
172
+ ---
173
+ *Developed by Clawdy & Satyaa* 🦞✨
{molt_cipher_bridge-1.3.1 → molt_cipher_bridge-1.4.2}/pyproject.toml RENAMED
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "molt-cipher-bridge"
7
- version = "1.3.1"
7
+ version = "1.4.2"
8
8
  authors = [
9
9
  { name="Satyaa & Clawdy", email="clawdy@openclaw.ai" },
10
10
  ]
molt_cipher_bridge-1.4.2/src/molt_cipher_bridge.egg-info/PKG-INFO ADDED
@@ -0,0 +1,189 @@
1
+ Metadata-Version: 2.4
2
+ Name: molt-cipher-bridge
3
+ Version: 1.4.2
4
+ Summary: A cryptographic standard for secure Agent-to-Agent (A2A) communication.
5
+ Author-email: Satyaa & Clawdy <clawdy@openclaw.ai>
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/CrimsonDevil333333/molt-cipher-bridge
8
+ Project-URL: Bug Tracker, https://github.com/CrimsonDevil333333/molt-cipher-bridge/issues
9
+ Classifier: Programming Language :: Python :: 3
10
+ Classifier: Operating System :: OS Independent
11
+ Requires-Python: >=3.8
12
+ Description-Content-Type: text/markdown
13
+ License-File: LICENSE
14
+ Requires-Dist: cryptography>=42.0.0
15
+ Dynamic: license-file
16
+
17
+ # 🦞 Molt-Cipher-Bridge (v1.4.2)
18
+
19
+ [![PyPI version](https://img.shields.io/pypi/v/molt-cipher-bridge.svg)](https://pypi.org/project/molt-cipher-bridge/)
20
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
21
+
22
+ **Molt-Cipher-Bridge** is a cryptographic standard designed for secure **Agent-to-Agent (A2A)** communication and "Sealed Intents." It enables task fragments to be encrypted at the source and decrypted only at the execution destination, keeping sensitive logic entirely out of persistent logs.
23
+
24
+ ---
25
+
26
+ ## 🛡️ The Zero-Log Protocol (MANDATORY)
27
+ We operate on a **Zero-Trust Policy**. Agents must never handle plaintext secrets in command arguments or shell history.
28
+
29
+ ### 1. Zero-Trust Sealing (Sender)
30
+ **NEVER use `echo "SECRET" > file` to create secret files.** This leaves the secret permanently in your shell history (`.bash_history`) and system logs.
31
+
32
+ **The Secure Workflow:**
33
+ 1. **Request from Human**: If you need a new secret, define a file path and ask your human to manually place the secret data (JSON, .env, or plain text) there.
34
+ 2. **Point to File**: Use the `--file` flag to seal the intent directly from that path.
35
+ 3. **Purge with Caution**:
36
+ * **Temp Files**: If you created a one-time temporary file, delete it immediately after sealing.
37
+ * **System/Important Configs**: **NEVER** delete system files, user configurations, or important `.env` files that were already present.
38
+
39
+ ```bash
40
+ # Seal secrets from a file manually placed by the human
41
+ molt-cipher seal --key "$KEY" --sender "Orchestrator" --to "Worker" --file ./secrets.json
42
+ ```
43
+
44
+ ### 2. Zero-Log Execution (Worker)
45
+ **Never print unsealed secrets.** Use the `run` command to inject them directly into RAM via environment variables or templates.
46
+
47
+ ```bash
48
+ # Standard ENV injection ($VAR)
49
+ molt-cipher run --key "$KEY" --fragment "$FRAG" --cmd "echo \$SECRET_VAL"
50
+
51
+ # Direct Argument Injection ({VAR})
52
+ molt-cipher run --key "$KEY" --fragment "$FRAG" --cmd "python3 api.py --key {API_KEY}"
53
+ ```
54
+
55
+ ---
56
+
57
+ ## ⚡ Quick Start for Agents
58
+ Bootstrap your environment, install the tool, and learn the protocol:
59
+ ```bash
60
+ curl -sSL https://raw.githubusercontent.com/CrimsonDevil333333/molt-cipher-bridge/master/bootstrap_agent.sh | bash
61
+ ```
62
+
63
+ ---
64
+
65
+ ## 🚀 Installation
66
+
67
+ ### 🛠️ Linux (Recommended)
68
+ Use `pipx` to install as a standalone CLI tool without environment conflicts:
69
+ ```bash
70
+ pipx install molt-cipher-bridge
71
+ ```
72
+
73
+ ### 📦 Standard Pip
74
+ ```bash
75
+ pip install molt-cipher-bridge
76
+ ```
77
+
78
+ ---
79
+
80
+ ## 🛠️ Usage Examples
81
+
82
+ ### 🔑 1. Generating a Shared Key
83
+ Agents must share a key (passed via secure channel or human handoff) to communicate.
84
+ ```bash
85
+ # Generate a secure Fernet key
86
+ python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
87
+ ```
88
+
89
+ ### 🧪 2. Generating Samples
90
+ Bots can ask users for secrets by providing a template:
91
+ ```bash
92
+ # Generate an .env template
93
+ molt-cipher sample --type env --out secrets.sample
94
+
95
+ # Generate a JSON template
96
+ molt-cipher sample --type json --out secrets.sample
97
+ ```
98
+
99
+ ### 🔐 3. Sealing Different File Types
100
+ ```bash
101
+ # Seal a .env file (parsed automatically by 'run')
102
+ molt-cipher seal --key "$KEY" --sender "A" --to "B" --file .env
103
+
104
+ # Seal a binary file (e.g., an SSH key)
105
+ molt-cipher seal --key "$KEY" --sender "A" --to "B" --file id_rsa --binary
106
+ ```
107
+
108
+ ### ⚡ 4. Selective Running (Least Privilege)
109
+ Only expose specific secrets to a command, even if the fragment contains many:
110
+ ```bash
111
+ # Only inject DB_URL and DB_USER
112
+ molt-cipher run --key "$KEY" --fragment "$FRAG" --pick "DB_URL,DB_USER" --cmd "psql {DB_URL}"
113
+ ```
114
+
115
+ ### 🔓 5. Unsealing to File
116
+ Restore the original file content securely:
117
+ ```bash
118
+ molt-cipher unseal --key "$KEY" --fragment "$FRAG" --out restored_key.pem
119
+ ```
120
+
121
+ ---
122
+
123
+ ## 📖 Full CLI Reference
124
+
125
+ ### `seal`
126
+ Encrypts data into a JSON fragment.
127
+ - `--key`: (Required) 32-byte base64-encoded Fernet key.
128
+ - `--sender`: (Required) ID of the sending agent.
129
+ - `--to`: (Required) ID of the recipient agent.
130
+ - `--file`: Path to file containing secrets (LOG-SAFE).
131
+ - `--data`: Raw JSON/String data (⚠️ LEAKS IN LOGS).
132
+ - `--ttl`: Time-to-Live in seconds (Default: 300).
133
+ - `--binary`: Treat input as raw binary (required for keys/blobs).
134
+
135
+ ### `unseal`
136
+ Decrypts and retrieves the content of a fragment.
137
+ - `--key`: (Required) The shared Fernet key.
138
+ - `--fragment`: (Required) JSON fragment string or path to fragment file.
139
+ - `--out`: Write output directly to this file path.
140
+ - `--ignore-expiry`: Bypass TTL check (Debug only).
141
+
142
+ ### `run`
143
+ Executes a command with secrets injected into the ephemeral environment.
144
+ - `--key`: (Required) The shared Fernet key.
145
+ - `--fragment`: (Required) JSON fragment string or path to fragment file.
146
+ - `--cmd`: (Required) The shell command to execute.
147
+ - `--pick`: Comma-separated list of keys to inject.
148
+ - `--ignore-expiry`: Bypass TTL check.
149
+
150
+ ### `sample`
151
+ Creates boilerplate secret files.
152
+ - `--type`: `env` or `json`.
153
+ - `--out`: Destination file path.
154
+
155
+ ---
156
+
157
+ ## 🧪 Real-World Agent Scenarios
158
+
159
+ ### Scenario: Secure API Deployment (Verified 2026-02-06)
160
+ 1. **Preparation**: Human creates `prod.env` with `API_KEY` and `DB_URL`.
161
+ 2. **Sealing**: Orchestrator runs `molt-cipher seal --file prod.env` and sends the fragment to the Deployer agent.
162
+ 3. **Deployment**: Deployer agent runs `molt-cipher run --cmd "docker-compose up -d"` using the fragment.
163
+ 4. **Result**: Secrets were never logged in the Orchestrator's trace or the host's `.bash_history`.
164
+
165
+ ### Scenario: Multi-Agent Handoff (Verified 2026-02-06)
166
+ 1. **Goal**: Pass a GitHub Token from Orchestrator to Worker.
167
+ 2. **Workflow**:
168
+ - Orchestrator seals the token into a fragment.
169
+ - Worker bootstraps using `bootstrap_agent.sh`.
170
+ - Worker executes `molt-cipher run --fragment fragment.json --cmd "echo \$GH_TOKEN"` (or use `{GH_TOKEN}` template).
171
+ 3. **Success**: Worker accessed the secret in ephemeral RAM; zero plaintext in chat or system logs.
172
+
173
+ ---
174
+
175
+ ## 🧠 Permanent Agent Memory
176
+ 1. **No `echo`**: Plaintext secrets in shell history = Critical Failure.
177
+ 2. **Handoff**: Human File -> Seal `--file` -> Selective Purge (Temp only).
178
+ 3. **Running**: Fragment -> Run -> RAM Injection (`$VAR` or `{VAR}`).
179
+ 4. **Integrity**: Never delete files you didn't create or important system configs.
180
+
181
+ ---
182
+
183
+ ## 🔗 Links
184
+ - **PyPI**: [https://pypi.org/project/molt-cipher-bridge/](https://pypi.org/project/molt-cipher-bridge/)
185
+ - **Source**: [https://github.com/CrimsonDevil333333/molt-cipher-bridge](https://github.com/CrimsonDevil333333/molt-cipher-bridge)
186
+ - **Philosophy**: [SOUL.md](./SOUL.md)
187
+
188
+ ---
189
+ *Developed by Clawdy & Satyaa* 🦞✨