From 03395d00659921949dc88266e038df982a9e6719 Mon Sep 17 00:00:00 2001 From: Beon de Nood Date: Fri, 26 Dec 2025 22:46:36 -0500 Subject: [PATCH 1/2] docs: fix CLI command documentation to match actual implementation - Fix badge issue flags: level is 1-3 (DV/OV/EV), not 0-4 - Fix badge verify flags: use --offline not --accept-self-signed, remove non-existent --json - Fix key subcommand: 'gen' not 'generate', add actual flags - Add trust command documentation (add/list/remove) - Add badge keep command documentation - Remove '(includes scores)' from JSON output description - Add proper examples with correct flag syntax --- README.md | 6 +-- docs/index.md | 4 +- docs/reference/commands.md | 85 +++++++++++++++++++++++++++++--------- 3 files changed, 71 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 745207b..09da7df 100644 --- a/README.md +++ b/README.md @@ -31,10 +31,10 @@ capiscio validate ./agent-card.json capiscio validate https://my-agent.example.com --json # Issue a self-signed badge (development) -capiscio badge issue --self-sign +capiscio badge issue --self-sign --sub did:web:example.com:agents:my-agent -# Verify a badge -capiscio badge verify "eyJhbGciOiJFZERTQSJ9..." --accept-self-signed +# Verify a badge (offline mode) +capiscio badge verify "eyJhbGciOiJFZERTQSJ9..." --offline # Check version capiscio --version diff --git a/docs/index.md b/docs/index.md index a174293..b6a7790 100644 --- a/docs/index.md +++ b/docs/index.md @@ -39,11 +39,11 @@ npm install -g capiscio # Validate an agent card capiscio validate ./agent-card.json -# Validate with JSON output (includes scores) +# Validate with JSON output capiscio validate ./agent-card.json --json # Issue a self-signed badge (development) -capiscio badge issue --self-sign +capiscio badge issue --self-sign --sub did:web:example.com:agents:my-agent # Check core version capiscio --version diff --git a/docs/reference/commands.md b/docs/reference/commands.md index 4d6f232..988603b 100644 --- a/docs/reference/commands.md +++ b/docs/reference/commands.md @@ -78,24 +78,26 @@ capiscio badge issue [flags] | Flag | Description | |------|-------------| -| `--self-sign` | Issue self-signed badge (Level 0, did:key) | -| `--level <0-4>` | Trust level (0=SS, 1=DV, 2=OV, 3=EV, 4=CV) | -| `--sub ` | Subject DID | +| `--self-sign` | Issue self-signed badge for development | +| `--level <1-3>` | Trust level (1=DV, 2=OV, 3=EV) | +| `--sub ` | Subject DID (did:web format) | | `--aud ` | Audience (comma-separated URLs) | | `--exp ` | Expiration duration (default: 5m) | | `--key ` | Path to private key file | +| `--domain ` | Agent domain | +| `--iss ` | Issuer URL | **Examples:** ```bash # Self-signed badge for development -capiscio badge issue --self-sign +capiscio badge issue --self-sign --sub did:web:example.com:agents:my-agent -# With custom expiration -capiscio badge issue --self-sign --exp 1h +# With specific trust level +capiscio badge issue --self-sign --level 2 --domain example.com # With audience restriction -capiscio badge issue --self-sign --aud "https://api.example.com" +capiscio badge issue --self-sign --aud "https://api.example.com,https://backup.example.com" ``` #### badge verify @@ -110,24 +112,45 @@ capiscio badge verify [flags] | Flag | Description | |------|-------------| -| `--accept-self-signed` | Accept self-signed badges (Level 0) | -| `--audience ` | Verify audience claim | -| `--skip-revocation` | Skip revocation check | -| `--json` | Output as JSON | +| `--key ` | Path to public key file (JWK) | +| `--offline` | Offline mode (uses trust store) | +| `--audience ` | Verifier's identity for audience validation | +| `--skip-revocation` | Skip revocation check (testing only) | +| `--skip-agent-status` | Skip agent status check (testing only) | +| `--trusted-issuers ` | Comma-separated list of trusted issuer URLs | **Examples:** ```bash -# Verify badge (rejects self-signed by default) -capiscio badge verify "eyJhbGciOiJFZERTQSJ9..." +# Verify badge with CA public key +capiscio badge verify "eyJhbGciOiJFZERTQSJ9..." --key ca-public.jwk -# Accept self-signed for development -capiscio badge verify "eyJhbGciOiJFZERTQSJ9..." --accept-self-signed +# Offline verification (uses local trust store) +capiscio badge verify "eyJhbGciOiJFZERTQSJ9..." --offline -# JSON output -capiscio badge verify "eyJhbGciOiJFZERTQSJ9..." --json +# With audience validation +capiscio badge verify "eyJhbGciOiJFZERTQSJ9..." --key ca.jwk --audience https://api.example.com ``` +#### badge keep + +Run a daemon that automatically renews badges before expiry. + +```bash +capiscio badge keep [flags] +``` + +**Flags:** + +| Flag | Description | +|------|-------------| +| `--self-sign` | Self-sign instead of requesting from CA | +| `--key ` | Path to private key file (required for self-sign) | +| `--out ` | Output file path (default: badge.jwt) | +| `--exp ` | Expiration duration (default: 5m) | +| `--renew-before ` | Time before expiry to renew (default: 1m) | +| `--check-interval ` | Interval to check for renewal (default: 30s) | + --- ### key @@ -140,8 +163,32 @@ capiscio key [command] **Subcommands:** -- `generate` - Generate a new key pair -- `list` - List stored keys +- `gen` - Generate a new Ed25519 key pair + +**Example:** + +```bash +# Generate a new key pair +capiscio key gen --out-priv private.jwk --out-pub public.jwk +``` + +--- + +### trust + +Manage the local trust store for offline badge verification. + +```bash +capiscio trust [command] +``` + +**Subcommands:** + +- `add` - Add a CA public key to the trust store +- `list` - List trusted CA keys +- `remove` - Remove a CA key from the trust store + +**Location:** `~/.capiscio/trust/` (or `$CAPISCIO_TRUST_PATH`) --- From ccb6736483db5afa5483a2f16087109b841e4c37 Mon Sep 17 00:00:00 2001 From: Beon de Nood Date: Sat, 27 Dec 2025 15:19:51 -0500 Subject: [PATCH 2/2] docs: address copilot review feedback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Clarify --audience flag description - Add examples for badge keep command - Add examples for trust command (add, list, remove) - Fix inconsistent ca.jwk → ca-public.jwk filename - Expand trust level abbreviations (DV, OV, EV) - Fix misleading --self-sign + --level example --- docs/reference/commands.md | 36 +++++++++++++++++++++++++++++++----- 1 file changed, 31 insertions(+), 5 deletions(-) diff --git a/docs/reference/commands.md b/docs/reference/commands.md index 988603b..80beba2 100644 --- a/docs/reference/commands.md +++ b/docs/reference/commands.md @@ -79,7 +79,7 @@ capiscio badge issue [flags] | Flag | Description | |------|-------------| | `--self-sign` | Issue self-signed badge for development | -| `--level <1-3>` | Trust level (1=DV, 2=OV, 3=EV) | +| `--level <1-3>` | Trust level (1=Domain Validation, 2=Organization Validation, 3=Extended Validation) | | `--sub ` | Subject DID (did:web format) | | `--aud ` | Audience (comma-separated URLs) | | `--exp ` | Expiration duration (default: 5m) | @@ -93,8 +93,8 @@ capiscio badge issue [flags] # Self-signed badge for development capiscio badge issue --self-sign --sub did:web:example.com:agents:my-agent -# With specific trust level -capiscio badge issue --self-sign --level 2 --domain example.com +# CA-issued badge with specific trust level +capiscio badge issue --level 2 --domain example.com --key ca-private.jwk # With audience restriction capiscio badge issue --self-sign --aud "https://api.example.com,https://backup.example.com" @@ -114,7 +114,7 @@ capiscio badge verify [flags] |------|-------------| | `--key ` | Path to public key file (JWK) | | `--offline` | Offline mode (uses trust store) | -| `--audience ` | Verifier's identity for audience validation | +| `--audience ` | Expected audience claim value (verifies the badge is intended for this URL) | | `--skip-revocation` | Skip revocation check (testing only) | | `--skip-agent-status` | Skip agent status check (testing only) | | `--trusted-issuers ` | Comma-separated list of trusted issuer URLs | @@ -129,7 +129,7 @@ capiscio badge verify "eyJhbGciOiJFZERTQSJ9..." --key ca-public.jwk capiscio badge verify "eyJhbGciOiJFZERTQSJ9..." --offline # With audience validation -capiscio badge verify "eyJhbGciOiJFZERTQSJ9..." --key ca.jwk --audience https://api.example.com +capiscio badge verify "eyJhbGciOiJFZERTQSJ9..." --key ca-public.jwk --audience https://api.example.com ``` #### badge keep @@ -151,6 +151,19 @@ capiscio badge keep [flags] | `--renew-before ` | Time before expiry to renew (default: 1m) | | `--check-interval ` | Interval to check for renewal (default: 30s) | +**Examples:** + +```bash +# Run daemon with self-signed badges +capiscio badge keep --self-sign --key private.jwk --out badge.jwt + +# Custom renewal timing (renew 2 minutes before expiry, check every 10s) +capiscio badge keep --self-sign --key private.jwk --renew-before 2m --check-interval 10s + +# With custom expiration +capiscio badge keep --self-sign --key private.jwk --exp 1h --out /var/run/badge.jwt +``` + --- ### key @@ -190,6 +203,19 @@ capiscio trust [command] **Location:** `~/.capiscio/trust/` (or `$CAPISCIO_TRUST_PATH`) +**Examples:** + +```bash +# Add a CA public key to the trust store +capiscio trust add ca-public.jwk + +# List all trusted CA keys +capiscio trust list + +# Remove a CA key by fingerprint +capiscio trust remove abc123def456 +``` + --- ### gateway