docs: minor improvements

Author: fdiakh

README.md

@@ -1,14 +1,14 @@
 # biscuit-ssh
 
-SSH authorization using Biscuit tokens embedded in SSH certificates.
+SSH authorization using biscuit tokens embedded in SSH certificates.
 
 biscuit-ssh is an OpenSSH `AuthorizedKeysCommand` program that validates SSH certificates containing embedded biscuit tokens. It's inspired by [opkssh](https://github.com/openpubkey/opkssh) but uses biscuit tokens instead of PK tokens for service to service authorization.
 
 Have a look at the [example](example) folder for a demonstration of how this works.
 
 This crate is experimental and has not been tested in production. Use it at your own risk.
 
-## Installation on a Server
+## Installation on a SSH Server
 
 ### 1. Install the binary
 
@@ -19,7 +19,7 @@ cargo build --release
 sudo install -m 0755 target/release/biscuit-ssh /usr/local/bin/
 ```
 
-### 2. Create configuration file
+### 2. Create the configuration file
 
 Store the public key file to validate biscuits in `/etc/biscuit-ssh/keys/default.key`:
 
@@ -73,7 +73,7 @@ biscuit-ssh generate \
 ssh -i ~/.ssh/id_ed25519 alice@server
 ```
 
-## Biscuit Facts
+## Authority facts
 
 The biscuit token **must** provide these facts for authorization to succeed:
 
@@ -88,7 +88,7 @@ The biscuit token **must** provide these facts for authorization to succeed:
   ssh:authorized_key("ssh-ed25519", "AAAAC3NzaC1lZDI1NTE5AAAAIKzPvv...", "comment")
   ```
 
-## Server Facts
+## Authorizer facts
 
 The biscuit-ssh authorizer provides facts that can be used by checks in biscuit blocks:
 
@@ -109,9 +109,10 @@ The biscuit-ssh authorizer provides facts that can be used by checks in biscuit
   time(2025-07-22T22:39:12Z)
   ```
 
-### Using Server Facts for Attenuation
+### Biscuit Attenuation
 
-Biscuits can be attenuated based on server-provided facts:
+The embedded biscuit should be attenuated so that it may only be used for SSH
+connections with the right key pair:
 
 ```datalog
 // Original token authority
@@ -147,7 +148,7 @@ log_level = "info"
 
 ```
 /etc/biscuit-ssh/keys/
-├── default.key    # Default key (no key ID)
+├── default.key   # Default key (no key ID)
 ├── 1.key         # Key ID 1
 ├── 2.key         # Key ID 2
 └── 3.key         # Key ID 3

example/demo.sh

@@ -7,13 +7,23 @@ YELLOW='\033[1;33m'
 BOLD='\033[1m'
 NC='\033[0m'
 
+echo_cmd() {
+    echo "Running: $*" >&2
+    "$@"
+}
+
 echo -e "${BLUE}${BOLD}Step 1: Generating SSH keypair...${NC}"
 if [[ ! -f ~/.ssh/id_ed25519 ]]
 then
     mkdir -p ~/.ssh
-    ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -N "" -C "demo@biscuit-ssh"
+    echo_cmd ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -N "" -C "demo@biscuit-ssh"
+    echo
     echo -e "${GREEN}✓ SSH keypair generated${NC}"
     echo
+else
+    echo
+    echo -e "${GREEN}✓ Re-using existing SSH keypair${NC}"
+    echo
 fi
 
 echo -e "${BLUE}${BOLD}Step 2: Generating biscuit token for demo-user...${NC}"
@@ -28,7 +38,7 @@ check if time(\$time), \$time <= $(date -d 'now 5min' --rfc-3339=seconds| tr -s
 EOF
 
 PRIVATE_KEY=$(cat /shared/biscuit-keys/private.key)
-biscuit-cli generate --private-key $PRIVATE_KEY /tmp/token.datalog > /tmp/token.biscuit
+echo_cmd biscuit-cli generate --private-key $PRIVATE_KEY /tmp/token.datalog > /tmp/token.biscuit
 
 echo -e "${YELLOW}${BOLD}Biscuit token contents:${NC}"
 biscuit-cli inspect /tmp/token.biscuit
@@ -37,18 +47,17 @@ echo -e "${GREEN}✓ Biscuit token generated${NC}"
 echo
 
 echo -e "${BLUE}${BOLD}Step 3: Generating SSH certificate with embedded biscuit...${NC}"
-BISCUIT_SSH_CONFIG=/tmp/biscuit-ssh.conf biscuit-ssh generate \
+echo_cmd biscuit-ssh generate \
     --biscuit /tmp/token.biscuit \
     --identity ~/.ssh/id_ed25519 \
     --output ~/.ssh/id_ed25519-cert.pub
-
 echo
 echo -e "${GREEN}✓ SSH certificate generated${NC}"
 echo
 
 echo -e "${BLUE}${BOLD}Step 4: Connecting to server as demo-user...${NC}"
-ssh -o UserKnownHostsFile=/dev/null \
-    -o StrictHostKeyChecking=no \
-    demo-user@server \
-    'echo Hello I am $USER on $(hostname)'
+echo_cmd ssh -o StrictHostKeyChecking=no \
+             demo-user@server \
+             'echo Hello I am $USER on $(hostname)'
+echo
 echo -e "${GREEN}${BOLD}✓ Demo completed successfully!${NC}"