...

herodb/instructions/age_usage.md

@@ -16,28 +16,34 @@ Note: Database-at-rest encryption flags in the test harness are unrelated to AGE
 
 ## Quick start
 
-Assuming the server is running on localhost on some PORT:
+Assuming the server is running on localhost on some $PORT:
+```bash
+~/code/git.ourworld.tf/herocode/herodb/herodb/build.sh
+~/code/git.ourworld.tf/herocode/herodb/target/release/herodb --dir /tmp/data --debug --$PORT 6381 --encryption-key 1234 --encrypt
+```
+
 
 ```bash
+export PORT=6381
 # Generate an ephemeral keypair and encrypt/decrypt a message (stateless mode)
-redis-cli -p PORT AGE GENENC
+redis-cli -p $PORT AGE GENENC
 # → returns an array: [recipient, identity]
 
-redis-cli -p PORT AGE ENCRYPT <recipient> "hello world"
+redis-cli -p $PORT AGE ENCRYPT <recipient> "hello world"
 # → returns ciphertext (base64 in a bulk string)
 
-redis-cli -p PORT AGE DECRYPT <identity> <ciphertext_b64>
+redis-cli -p $PORT AGE DECRYPT <identity> <ciphertext_b64>
 # → returns "hello world"
 ```
 
 For key‑managed mode, generate a named key once and reference it by name afterwards:
 
 ```bash
-redis-cli -p PORT AGE KEYGEN app1
+redis-cli -p $PORT AGE KEYGEN app1
 # → persists encryption keypair under name "app1"
 
-redis-cli -p PORT AGE ENCRYPTNAME app1 "hello"
-redis-cli -p PORT AGE DECRYPTNAME app1 <ciphertext_b64>
+redis-cli -p $PORT AGE ENCRYPTNAME app1 "hello"
+redis-cli -p $PORT AGE DECRYPTNAME app1 <ciphertext_b64>
 ```
 
 ## Stateless AGE (ephemeral)
@@ -54,18 +60,18 @@ Commands and examples
 
 ```bash
 # Generate an ephemeral encryption keypair 
-redis-cli -p PORT AGE GENENC
+redis-cli -p $PORT AGE GENENC
 # Example output (abridged):
 # 1) "age1qz..."          # recipient (public key) = can be used by others e.g. to verify what I sign
 # 2) "AGE-SECRET-KEY-1..." # identity (secret) = is like my private, cannot lose this one
 
 # Encrypt with the recipient public key
-redis-cli -p PORT AGE ENCRYPT "age1qz..." "hello world"
+redis-cli -p $PORT AGE ENCRYPT "age1qz..." "hello world"
 
 # → returns bulk string payload: base64 ciphertext (encrypted content)
 
 # Decrypt with the identity (secret) in other words your private key
-redis-cli -p PORT AGE DECRYPT "AGE-SECRET-KEY-1..." "<ciphertext_b64>"
+redis-cli -p $PORT AGE DECRYPT "AGE-SECRET-KEY-1..." "<ciphertext_b64>"
 # → "hello world"
 ```
 
@@ -76,17 +82,17 @@ redis-cli -p PORT AGE DECRYPT "AGE-SECRET-KEY-1..." "<ciphertext_b64>"
 ```bash
 
 # Generate an ephemeral signing keypair
-redis-cli -p PORT AGE GENSIGN
+redis-cli -p $PORT AGE GENSIGN
 # Example output:
 # 1) "<verify_pub_b64>"
 # 2) "<sign_secret_b64>"
 
 # Sign a message with the secret
-redis-cli -p PORT AGE SIGN "<sign_secret_b64>" "msg"
+redis-cli -p $PORT AGE SIGN "<sign_secret_b64>" "msg"
 # → returns "<signature_b64>"
 
 # Verify with the public key
-redis-cli -p PORT AGE VERIFY "<verify_pub_b64>" "msg" "<signature_b64>"
+redis-cli -p $PORT AGE VERIFY "<verify_pub_b64>" "msg" "<signature_b64>"
 # → 1 (valid) or 0 (invalid)
 ```
 
@@ -110,15 +116,17 @@ Commands and examples
 
 ```bash
 # Create/persist a named encryption keypair
-redis-cli -p PORT AGE KEYGEN app1
+redis-cli -p $PORT AGE KEYGEN app1
 # → returns [recipient, identity] but also stores them under name "app1"
 
+> TODO: should not return identity (security, but there can be separate function to export it e.g. AGE EXPORTKEY app1)
+
 # Encrypt using the stored public key
-redis-cli -p PORT AGE ENCRYPTNAME app1 "hello"
+redis-cli -p $PORT AGE ENCRYPTNAME app1 "hello"
 # → returns bulk string payload: base64 ciphertext
 
 # Decrypt using the stored secret
-redis-cli -p PORT AGE DECRYPTNAME app1 "<ciphertext_b64>"
+redis-cli -p $PORT AGE DECRYPTNAME app1 "<ciphertext_b64>"
 # → "hello"
 ```
 
@@ -126,22 +134,24 @@ redis-cli -p PORT AGE DECRYPTNAME app1 "<ciphertext_b64>"
 
 ```bash
 # Create/persist a named signing keypair
-redis-cli -p PORT AGE SIGNKEYGEN app1
+redis-cli -p $PORT AGE SIGNKEYGEN app1
 # → returns [verify_pub_b64, sign_secret_b64] and stores under name "app1"
 
+> TODO: should not return sign_secret_b64 (for security, but there can be separate function to export it e.g. AGE EXPORTSIGNKEY app1)
+
 # Sign using the stored secret
-redis-cli -p PORT AGE SIGNNAME app1 "msg"
+redis-cli -p $PORT AGE SIGNNAME app1 "msg"
 # → returns "<signature_b64>"
 
 # Verify using the stored public key
-redis-cli -p PORT AGE VERIFYNAME app1 "msg" "<signature_b64>"
+redis-cli -p $PORT AGE VERIFYNAME app1 "msg" "<signature_b64>"
 # → 1 (valid) or 0 (invalid)
 ```
 
 3) List stored AGE keys
 
 ```bash
-redis-cli -p PORT AGE LIST
+redis-cli -p $PORT AGE LIST
 # Example output includes labels such as "encpub" and your key names (e.g., "app1")
 ```