From a89b8f10c53fe4861495f3e424de301a62e22774 Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Wed, 7 Oct 2026 19:05:42 +0200
Subject: [PATCH 01/57] Describe the module design principles in CONTRIBUTING

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 CONTRIBUTING.md | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index da9c01d..fc620b8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -74,6 +74,31 @@ export HODEISHIELD_API_KEY=...   # never commit or paste it anywhere
 cargo run -- vendors list
 ```
 
+## Design
+
+A short vocabulary for designing or refactoring a module, adapted from
+[aihero.dev/codebase-design](https://www.aihero.dev/skills-codebase-design). A **module** is anything
+with an interface and an implementation, at any scale: a function, a file, a crate. Its **interface**
+is everything a caller must know to use it: signature, invariants, errors and ordering. A **seam** is
+a place where behaviour can change without editing that place, and an **adapter** is a concrete
+implementation plugged into one. **Depth** is the behaviour available per unit of interface, and
+**locality** means that what changes together lives together.
+
+- **Depth lives in the interface.** Judge a module by how little a caller must learn, not by how
+  much code it hides. `hodeishield-api` is the model: the CLI calls `client.list_vendors(&params)`
+  and gets typed results, while URL building, authentication, retries, rate limits and the response
+  size cap stay behind it.
+- **Deletion test.** Imagine deleting the module and inlining it into its callers. If the
+  complexity vanishes, it was a pass-through and should not exist; if it spreads to every caller, it
+  is earning its place.
+- **The interface is the test surface.** Test through the interface. A test that reaches past it
+  pins the implementation and breaks on every refactor.
+- **One adapter is a hypothetical seam; two make it real.** Add a trait only when a second
+  implementation exists today, a test double included. `TokenStore` qualifies: the OS keychain and
+  the in-memory store used by tests both implement it.
+- **Locality.** Table, JSON and CSV rendering, including the sanitising of terminal control
+  characters, lives in `output.rs`, so a change to it touches one module, not every command.
+
 ## Pull requests
 
 - Branch from `dev` and open the pull request against `dev`. `main` only receives releases.

From 073e932ac6ed79443722dd0a71f4abfc15066ea4 Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Wed, 7 Oct 2026 19:09:09 +0200
Subject: [PATCH 02/57] Report OpenAPI drift in an issue instead of a pull
 request

The weekly check still compares the published /v1 document with
openapi/v1.json and classifies breaking changes with the pinned
oasdiff, but it no longer pushes a branch, regenerates the client or
opens a pull request. It opens or updates one issue labelled
openapi-drift, closes it when the documents match again, and fails the
run on drift. A failed fetch, parse or oasdiff run is reported in an
issue labelled openapi-check-failed. Permissions are reduced to
contents: read and issues: write.

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 .github/scripts/openapi-drift-issue.sh  |  63 ++++++++
 .github/scripts/openapi-drift-report.py | 125 ++++++++++++++++
 .github/scripts/openapi-sync.py         |  77 +++-------
 .github/workflows/openapi-sync.yml      | 183 ++++++++----------------
 CONTRIBUTING.md                         |   3 +-
 openapi/README.md                       |  14 +-
 6 files changed, 273 insertions(+), 192 deletions(-)
 create mode 100755 .github/scripts/openapi-drift-issue.sh
 create mode 100755 .github/scripts/openapi-drift-report.py

diff --git a/.github/scripts/openapi-drift-issue.sh b/.github/scripts/openapi-drift-issue.sh
new file mode 100755
index 0000000..a1970ee
--- /dev/null
+++ b/.github/scripts/openapi-drift-issue.sh
@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Hodeitek S.L.
+# Keeps one open issue per label in step with the state of the OpenAPI check.
+#
+#   openapi-drift-issue.sh report <label> <title> <body-file> [<marker>]
+#       Opens an issue with the label, or comments on the open one. With a marker, nothing is
+#       posted when the issue or one of its comments already contains it.
+#   openapi-drift-issue.sh resolve <label> <comment>
+#       Comments on and closes the open issue with the label, if there is one.
+#
+# Needs gh, GH_TOKEN and GITHUB_REPOSITORY. Titles, bodies and comments are passed to gh as files or
+# arguments, never evaluated.
+set -euo pipefail
+
+mode=${1:?mode}
+label=${2:?label}
+
+ensure_label() {
+  local found
+  found=$(gh label list --repo "$GITHUB_REPOSITORY" --search "$label" --json name --jq '.[].name')
+  if ! grep -Fxq -- "$label" <<<"$found"; then
+    gh label create "$label" --repo "$GITHUB_REPOSITORY" --color D4C5F9 \
+      --description "Reported by the OpenAPI sync workflow" > /dev/null
+  fi
+}
+
+open_issue() {
+  gh issue list --repo "$GITHUB_REPOSITORY" --label "$label" --state open --json number --jq '.[0].number // empty'
+}
+
+case "$mode" in
+  report)
+    title=${3:?title}
+    body_file=${4:?body file}
+    marker=${5:-}
+    ensure_label
+    number=$(open_issue)
+    if [ -z "$number" ]; then
+      gh issue create --repo "$GITHUB_REPOSITORY" --title "$title" --label "$label" --body-file "$body_file"
+    elif [ -n "$marker" ] && gh issue view "$number" --repo "$GITHUB_REPOSITORY" --json body,comments \
+      --jq '[.body, (.comments[].body)] | join("\n")' | grep -Fq -- "$marker"; then
+      echo "Issue #$number already reports this state"
+    else
+      gh issue comment "$number" --repo "$GITHUB_REPOSITORY" --body-file "$body_file"
+      echo "Commented on issue #$number"
+    fi
+    ;;
+  resolve)
+    comment=${3:?comment}
+    number=$(open_issue)
+    if [ -n "$number" ]; then
+      gh issue close "$number" --repo "$GITHUB_REPOSITORY" --reason completed --comment "$comment"
+      echo "Closed issue #$number"
+    else
+      echo "No open issue with the label $label"
+    fi
+    ;;
+  *)
+    echo "unknown mode: $mode" >&2
+    exit 2
+    ;;
+esac
diff --git a/.github/scripts/openapi-drift-report.py b/.github/scripts/openapi-drift-report.py
new file mode 100755
index 0000000..c2b72c4
--- /dev/null
+++ b/.github/scripts/openapi-drift-report.py
@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Hodeitek S.L.
+"""Writes the issue body that reports a difference between openapi/v1.json and the published document.
+
+Usage: openapi-drift-report.py <oasdiff> <dir> <run-url>
+
+<dir> is the output directory of openapi-sync.py (it holds `published.json` and `vendored.json`);
+`body.md` is written there and `breaking=true|false` is printed for $GITHUB_OUTPUT.
+
+oasdiff runs in both directions, since either side may be the one that is behind:
+  vendored -> published  breaking: a client built from openapi/v1.json may fail against the published document
+  published -> vendored  breaking: a client built from the published document may fail against openapi/v1.json
+Breaking means an oasdiff change of level ERR, as `oasdiff breaking --fail-on ERR` counts it.
+
+The text oasdiff prints comes from the published document, so it is untrusted: it is truncated and
+only ever placed inside a code fence longer than any backtick run it contains. Any failure of
+oasdiff is an error (exit 1), never a quiet pass.
+"""
+
+import hashlib
+import json
+import pathlib
+import re
+import subprocess
+import sys
+
+MAX_CHARS = 8000
+ERR_LEVEL = 3
+
+
+def run(oasdiff, directory, *args):
+    result = subprocess.run(
+        [oasdiff, *args], cwd=directory, capture_output=True, text=True, errors="replace", timeout=300
+    )
+    if result.returncode != 0:
+        raise SystemExit(f"error: oasdiff {args[0]} failed (exit {result.returncode}): {result.stderr.strip()[:500]}")
+    return result.stdout
+
+
+def breaking(oasdiff, directory, base, revision):
+    try:
+        changes = json.loads(run(oasdiff, directory, "breaking", base, revision, "-f", "json") or "[]")
+    except ValueError as e:
+        raise SystemExit(f"error: oasdiff breaking printed output that is not JSON: {e}")
+    if not isinstance(changes, list):
+        raise SystemExit("error: oasdiff breaking printed an unexpected document")
+    return [c for c in changes if isinstance(c, dict) and c.get("level", 0) >= ERR_LEVEL]
+
+
+def clean(text):
+    return re.sub(r"[\x00-\x08\x0b-\x1f\x7f]", "", text)
+
+
+def fenced(text):
+    """Truncates `text` and wraps it in a fence that no backtick run inside it can close."""
+    text = clean(text).strip()
+    note = ""
+    if len(text) > MAX_CHARS:
+        text, note = text[:MAX_CHARS], "\n[truncated]"
+    fence = "`" * max(3, max((len(m) for m in re.findall(r"`+", text)), default=0) + 1)
+    return f"{fence}text\n{text}{note}\n{fence}"
+
+
+def info_version(path):
+    return json.loads(path.read_text())["info"]["version"]
+
+
+def main():
+    oasdiff, directory, run_url = sys.argv[1], pathlib.Path(sys.argv[2]), sys.argv[3]
+    published = directory / "published.json"
+    digest = hashlib.sha256(published.read_bytes()).hexdigest()
+    vendored_digest = hashlib.sha256((directory / "vendored.json").read_bytes()).hexdigest()
+    forward = breaking(oasdiff, directory, "vendored.json", "published.json")
+    backward = breaking(oasdiff, directory, "published.json", "vendored.json")
+    changelog = run(oasdiff, directory, "changelog", "published.json", "vendored.json")
+    summary = run(oasdiff, directory, "summary", "published.json", "vendored.json")
+
+    def lines(changes):
+        return "\n".join(f"{c.get('operation', '')} {c.get('path', '')}: {c.get('text', '')}".strip() for c in changes) or "none"
+
+    def verdict(changes):
+        return f"**yes**, {len(changes)} breaking change(s)" if changes else "no"
+
+    body = f"""The published `/v1` OpenAPI document differs in content from the vendored `openapi/v1.json`. Key order and whitespace are not compared.
+
+| | Published document | `openapi/v1.json` |
+|---|---|---|
+| `info.version` | `{info_version(published)}` | `{info_version(directory / "vendored.json")}` |
+| SHA-256 | `{digest}` | `{vendored_digest}` |
+
+**Breaking changes, according to [oasdiff](https://github.com/oasdiff/oasdiff)**
+
+- From `openapi/v1.json` to the published document (a client built from the vendored copy may fail against the published one): {verdict(forward)}
+- From the published document to `openapi/v1.json` (a client built from the published document may fail against the vendored copy): {verdict(backward)}
+
+**Breaking changes from `openapi/v1.json` to the published document**
+
+{fenced(lines(forward))}
+
+**Breaking changes from the published document to `openapi/v1.json`**
+
+{fenced(lines(backward))}
+
+**Summary, published to vendored**
+
+{fenced(summary)}
+
+**Changelog, published to vendored**
+
+{fenced(changelog)}
+
+The vendored document is not updated automatically. Decide whether the API or the vendored copy is behind, then fix that side.
+
+Reported by the OpenAPI sync workflow: {run_url}
+
+<!-- openapi-drift:{digest} -->
+"""
+    (directory / "body.md").write_text(body)
+    print(f"breaking={'true' if forward or backward else 'false'}")
+    print(f"published_sha256={digest}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/.github/scripts/openapi-sync.py b/.github/scripts/openapi-sync.py
index a5e72ec..5cb1ecc 100755
--- a/.github/scripts/openapi-sync.py
+++ b/.github/scripts/openapi-sync.py
@@ -1,20 +1,19 @@
 #!/usr/bin/env python3
 # SPDX-License-Identifier: Apache-2.0
 # Copyright 2026 Hodeitek S.L.
-"""Compares openapi/v1.json with the document the API publishes and, when their content differs,
-replaces the vendored copy and updates what records it (openapi/README.md, xtask's EXPECTED_SHA256).
+"""Compares openapi/v1.json with the document the API publishes. Changes nothing in the repository.
 
 Usage: openapi-sync.py <url> <out-dir>
 
-Content means the JSON value: key order and whitespace do not count. On a difference the published
-bytes are written unchanged, as openapi/README.md requires, and <out-dir> receives `old.json` (the
-previous copy), `summary.md` and `version.txt`. Exits 0 in both cases and prints `changed=true` or
-`changed=false`; anything wrong with the published document is an error (exit 1).
+Content means the JSON value: key order and whitespace do not count. <out-dir> receives
+`published.json` (the published bytes, unchanged) and `vendored.json` (a copy of openapi/v1.json).
+Prints `changed=true` or `changed=false` and the two `info.version` values, as `key=value` lines
+fit for $GITHUB_OUTPUT, and exits 0 in both cases; anything wrong with the published document, or
+a failure to fetch it, is an error (exit 1) so the caller fails closed.
 
 Run from the repository root. Uses only the standard library.
 """
 
-import hashlib
 import json
 import pathlib
 import re
@@ -22,8 +21,6 @@
 import urllib.request
 
 SPEC = pathlib.Path("openapi/v1.json")
-README = pathlib.Path("openapi/README.md")
-XTASK = pathlib.Path("xtask/src/main.rs")
 MAX_BYTES = 5 * 1024 * 1024
 USER_AGENT = "hodeishield-cli-openapi-sync (+https://github.com/Hodeitek/hodeishield-cli)"
 
@@ -41,7 +38,7 @@ def check(document, url):
     if not str(document.get("openapi", "")).startswith("3."):
         raise SystemExit(f"error: {url} is not an OpenAPI 3 document")
     version = document.get("info", {}).get("version")
-    # It ends up in a branch commit, a pull request title and workflow outputs: plain text only.
+    # It ends up in an issue and in workflow outputs: plain text only.
     if not isinstance(version, str) or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._+-]{0,39}", version):
         raise SystemExit(f"error: {url} has a missing or unusual info.version")
     if not document.get("paths"):
@@ -66,19 +63,12 @@ def canonical(document):
     return json.dumps(document, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
 
 
-def operations(document):
-    methods = {"get", "put", "post", "delete", "options", "head", "patch", "trace"}
-    return {
-        f"{method.upper()} {path}"
-        for path, item in document["paths"].items()
-        for method in item
-        if method in methods
-    }
-
-
 def main():
     url, out = sys.argv[1], pathlib.Path(sys.argv[2])
-    published = fetch(url)
+    try:
+        published = fetch(url)
+    except OSError as e:
+        raise SystemExit(f"error: cannot fetch {url}: {e}")
     try:
         new = json.loads(published)
     except ValueError as e:
@@ -87,46 +77,13 @@ def main():
     local_refs_only(new, url)
     current = SPEC.read_bytes()
     old = json.loads(current)
-    if canonical(new) == canonical(old):
-        print("changed=false")
-        return
-
     out.mkdir(parents=True, exist_ok=True)
-    (out / "old.json").write_bytes(current)
-    SPEC.write_bytes(published)
-    digest = hashlib.sha256(published).hexdigest()
-    old_digest = hashlib.sha256(current).hexdigest()
-    version, old_version = new["info"]["version"], old["info"]["version"]
-    ops, old_ops = operations(new), operations(old)
-    non_get = sorted(op for op in ops if not op.startswith("GET "))
-    count = f"{len(ops)}, all `GET`" if not non_get else str(len(ops))
-
-    readme = README.read_text()
-    readme = re.sub(r"(\| `info\.version` \| `)[^`]*(` \|)", rf"\g<1>{version}\g<2>", readme)
-    readme = re.sub(r"(\| SHA-256 \| `)[0-9a-f]{64}(` \|)", rf"\g<1>{digest}\g<2>", readme)
-    readme = re.sub(r"(\| Operations \| )[^|\n]*?( \|)", rf"\g<1>{count}\g<2>", readme)
-    README.write_text(readme)
-    xtask = XTASK.read_text()
-    xtask, replaced = re.subn(
-        r'(const EXPECTED_SHA256: &str = ")[0-9a-f]{64}(";)', rf"\g<1>{digest}\g<2>", xtask
-    )
-    if replaced != 1:
-        raise SystemExit(f"error: EXPECTED_SHA256 not found in {XTASK}")
-    XTASK.write_text(xtask)
-
-    lines = [
-        f"- `info.version`: `{old_version}` → `{version}`",
-        f"- SHA-256: `{old_digest[:12]}…` → `{digest[:12]}…`",
-        f"- Operations: {len(old_ops)} → {len(ops)}",
-    ]
-    for label, items in (("Added", sorted(ops - old_ops)), ("Removed", sorted(old_ops - ops))):
-        if items:
-            lines.append(f"- {label} operations: " + ", ".join(f"`{op}`" for op in items))
-    if non_get:
-        lines.append("- **Not read-only**: " + ", ".join(f"`{op}`" for op in non_get))
-    (out / "summary.md").write_text("\n".join(lines) + "\n")
-    (out / "version.txt").write_text(version + "\n")
-    print("changed=true")
+    (out / "published.json").write_bytes(published)
+    (out / "vendored.json").write_bytes(current)
+    changed = canonical(new) != canonical(old)
+    print(f"changed={'true' if changed else 'false'}")
+    print(f"published_version={new['info']['version']}")
+    print(f"vendored_version={old['info'].get('version')}")
 
 
 if __name__ == "__main__":
diff --git a/.github/workflows/openapi-sync.yml b/.github/workflows/openapi-sync.yml
index 1f5d1fa..19853cd 100644
--- a/.github/workflows/openapi-sync.yml
+++ b/.github/workflows/openapi-sync.yml
@@ -1,16 +1,20 @@
 name: OpenAPI sync
 
-# Keeps openapi/v1.json in step with the document the API publishes. Once a week (and on demand)
-# it compares the two by content; if they differ, it opens or updates ONE pull request against dev
-# with the new document, the regenerated client and a summary, labelled `breaking-change` when
-# oasdiff finds one. It never pushes to main and never merges anything.
+# Checks that openapi/v1.json still matches the document the API publishes. Once a week (and on
+# demand) it compares the two by content. If they differ it opens, or comments on, ONE issue
+# (label `openapi-drift`) with both versions, whether oasdiff finds a breaking change and in which
+# direction, and a summary; when they match again it closes that issue. The run is red whenever the
+# documents differ, so the scheduled run shows it too. Nothing is committed, pushed or merged: the
+# vendored copy is the reference, and a person decides which side is behind.
+#
+# A document that cannot be fetched or parsed, or an oasdiff failure, is reported the same way, in
+# an issue labelled `openapi-check-failed`, and the run is red.
 on:
   schedule:
     - cron: "17 5 * * 1" # Mondays, 05:17 UTC
   workflow_dispatch:
 
-permissions:
-  contents: read
+permissions: {}
 
 concurrency:
   group: openapi-sync
@@ -18,18 +22,21 @@ concurrency:
 
 env:
   SPEC_URL: https://api.hodeishield.com/v1/openapi.json
-  BRANCH: chore/openapi-sync
+  DRIFT_LABEL: openapi-drift
+  FAILED_LABEL: openapi-check-failed
   OASDIFF_VERSION: "1.32.1"
   OASDIFF_SHA256: 7c8939fc49b75ee11fec66a5b83b37a2fca6aee109fed85013b1ba2ac2a1ee7f
 
 jobs:
-  sync:
-    name: sync
+  check:
+    name: check
     runs-on: ubuntu-latest
-    timeout-minutes: 20
+    timeout-minutes: 10
     permissions:
-      contents: write # the sync branch and its commit
-      pull-requests: write # the pull request and its labels
+      contents: read
+      issues: write # the report issue and its label
+    env:
+      GH_TOKEN: ${{ github.token }}
     steps:
       - name: Checkout dev
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -39,22 +46,15 @@ jobs:
 
       - name: Compare with the published document
         id: compare
-        run: python3 .github/scripts/openapi-sync.py "$SPEC_URL" "$RUNNER_TEMP/sync" | tee -a "$GITHUB_OUTPUT"
-
-      - name: Install pinned toolchain
-        if: steps.compare.outputs.changed == 'true'
-        run: rustup show
-
-      - name: Regenerate the client
-        if: steps.compare.outputs.changed == 'true'
-        id: codegen
         run: |
-          if cargo xtask codegen > "$RUNNER_TEMP/codegen.log" 2>&1; then
-            echo "ok=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "ok=false" >> "$GITHUB_OUTPUT"
-          fi
-          cat "$RUNNER_TEMP/codegen.log"
+          python3 .github/scripts/openapi-sync.py "$SPEC_URL" "$RUNNER_TEMP/sync" > "$RUNNER_TEMP/compare.out"
+          cat "$RUNNER_TEMP/compare.out" >> "$GITHUB_OUTPUT"
+
+      - name: Close the drift issue
+        if: steps.compare.outputs.changed == 'false'
+        run: >
+          .github/scripts/openapi-drift-issue.sh resolve "$DRIFT_LABEL"
+          "The published document and openapi/v1.json match again."
 
       # Pinned and checked against the checksum recorded above; bumped by hand in the periodic
       # dependency review (CONTRIBUTING.md).
@@ -68,109 +68,42 @@ jobs:
           echo "${OASDIFF_SHA256}  $RUNNER_TEMP/$archive" | sha256sum -c -
           tar -xzf "$RUNNER_TEMP/$archive" -C "$RUNNER_TEMP" oasdiff
 
-      - name: Write the pull request description
+      - name: Describe the difference
         if: steps.compare.outputs.changed == 'true'
-        id: body
-        env:
-          CODEGEN_OK: ${{ steps.codegen.outputs.ok }}
+        id: report
         run: |
-          set -euo pipefail
-          old="$RUNNER_TEMP/sync/old.json"
-          oasdiff="$RUNNER_TEMP/oasdiff"
-          breaking=false
-          if ! "$oasdiff" breaking "$old" openapi/v1.json --fail-on ERR > "$RUNNER_TEMP/breaking.txt" 2>&1; then
-            breaking=true
-          fi
-          "$oasdiff" changelog "$old" openapi/v1.json -f markdown > "$RUNNER_TEMP/changelog.md" 2>&1 || true
-          {
-            echo "The document published at \`$SPEC_URL\` differs in content from \`openapi/v1.json\`. This pull request takes the published bytes unchanged, updates the recorded version and SHA-256, and regenerates the client."
-            echo
-            cat "$RUNNER_TEMP/sync/summary.md"
-            echo
-            if [ "$breaking" = true ]; then
-              echo "**⚠ Breaking changes found by oasdiff** (label \`breaking-change\`): an older CLI may fail against the new contract. Review before merging."
-            else
-              echo "No breaking changes found by oasdiff."
-            fi
-            echo
-            echo '```'
-            head -c 20000 "$RUNNER_TEMP/breaking.txt"
-            echo '```'
-            if [ "$CODEGEN_OK" != true ]; then
-              echo
-              echo "**⚠ \`cargo xtask codegen\` failed**; the client is not regenerated. Output:"
-              echo '```'
-              tail -c 5000 "$RUNNER_TEMP/codegen.log"
-              echo '```'
-            fi
-            echo
-            echo "<details><summary>oasdiff changelog</summary>"
-            echo
-            head -c 30000 "$RUNNER_TEMP/changelog.md"
-            echo
-            echo "</details>"
-            echo
-            echo "Opened by the weekly OpenAPI sync workflow. Pull requests it opens do not start CI on their own: close and reopen this one to run the checks. Never merged automatically."
-          } > "$RUNNER_TEMP/body.md"
-          echo "breaking=$breaking" >> "$GITHUB_OUTPUT"
-          echo "version=$(cat "$RUNNER_TEMP/sync/version.txt")" >> "$GITHUB_OUTPUT"
+          python3 .github/scripts/openapi-drift-report.py "$RUNNER_TEMP/oasdiff" "$RUNNER_TEMP/sync" \
+            "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID" > "$RUNNER_TEMP/report.out"
+          cat "$RUNNER_TEMP/report.out" >> "$GITHUB_OUTPUT"
 
-      # The commit is made through the GraphQL API so GitHub signs it: dev only accepts signed
-      # commits. The branch is reset to dev first, so it always holds exactly one sync commit.
-      - name: Commit to the sync branch
+      - name: Open or update the drift issue
         if: steps.compare.outputs.changed == 'true'
         env:
-          GH_TOKEN: ${{ github.token }}
-          VERSION: ${{ steps.body.outputs.version }}
-        run: |
-          set -euo pipefail
-          base=$(git rev-parse HEAD)
-          if gh api "repos/$GITHUB_REPOSITORY/git/ref/heads/$BRANCH" > /dev/null 2>&1; then
-            gh api -X PATCH "repos/$GITHUB_REPOSITORY/git/refs/heads/$BRANCH" -f sha="$base" -F force=true > /dev/null
-          else
-            gh api -X POST "repos/$GITHUB_REPOSITORY/git/refs" -f ref="refs/heads/$BRANCH" -f sha="$base" > /dev/null
-          fi
-          python3 - "$base" > "$RUNNER_TEMP/commit.json" <<'EOF'
-          import base64, json, os, subprocess, sys
-          files = subprocess.run(["git", "diff", "--name-only"], check=True, capture_output=True, text=True).stdout.split()
-          message = {
-              "headline": f"Sync the /v1 OpenAPI document from the API ({os.environ['VERSION']})",
-              "body": "Takes the document the API publishes, unchanged, updates its recorded version and\n"
-                      "SHA-256, and regenerates the client.\n\n"
-                      "Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>",
-          }
-          additions = [{"path": f, "contents": base64.b64encode(open(f, "rb").read()).decode()} for f in files]
-          query = """mutation($input: CreateCommitOnBranchInput!) {
-            createCommitOnBranch(input: $input) { commit { oid url } } }"""
-          print(json.dumps({"query": query, "variables": {"input": {
-              "branch": {"repositoryNameWithOwner": os.environ["GITHUB_REPOSITORY"], "branchName": os.environ["BRANCH"]},
-              "expectedHeadOid": sys.argv[1],
-              "message": message,
-              "fileChanges": {"additions": additions},
-          }}}))
-          EOF
-          gh api graphql --input "$RUNNER_TEMP/commit.json" --jq '.data.createCommitOnBranch.commit.url'
+          PUBLISHED_SHA256: ${{ steps.report.outputs.published_sha256 }}
+        run: >
+          .github/scripts/openapi-drift-issue.sh report "$DRIFT_LABEL"
+          "The published /v1 OpenAPI document differs from openapi/v1.json"
+          "$RUNNER_TEMP/sync/body.md" "openapi-drift:$PUBLISHED_SHA256"
 
-      - name: Open or update the pull request
+      - name: Fail on drift
+        id: drift
         if: steps.compare.outputs.changed == 'true'
-        env:
-          GH_TOKEN: ${{ github.token }}
-          VERSION: ${{ steps.body.outputs.version }}
-          BREAKING: ${{ steps.body.outputs.breaking }}
         run: |
-          set -euo pipefail
-          title="chore(api): sync openapi v1 from platform $VERSION"
-          number=$(gh pr list --repo "$GITHUB_REPOSITORY" --head "$BRANCH" --base dev --state open --json number --jq '.[0].number // empty')
-          if [ -z "$number" ]; then
-            url=$(gh pr create --repo "$GITHUB_REPOSITORY" --base dev --head "$BRANCH" --title "$title" --body-file "$RUNNER_TEMP/body.md")
-            number=${url##*/}
-          else
-            gh pr edit "$number" --repo "$GITHUB_REPOSITORY" --title "$title" --body-file "$RUNNER_TEMP/body.md" > /dev/null
-          fi
-          gh pr edit "$number" --repo "$GITHUB_REPOSITORY" --add-label api-sync > /dev/null
-          if [ "$BREAKING" = true ]; then
-            gh pr edit "$number" --repo "$GITHUB_REPOSITORY" --add-label breaking-change > /dev/null
-          else
-            gh pr edit "$number" --repo "$GITHUB_REPOSITORY" --remove-label breaking-change > /dev/null 2>&1 || true
-          fi
-          echo "Pull request #$number"
+          echo "The published document differs from openapi/v1.json; see the issue labelled $DRIFT_LABEL." >&2
+          exit 1
+
+      # Reached only when the check itself completed, with or without drift.
+      - name: Close the report of an earlier failed check
+        if: success() || steps.drift.conclusion == 'failure'
+        run: .github/scripts/openapi-drift-issue.sh resolve "$FAILED_LABEL" "The check completed again."
+
+      - name: Report a failed check
+        if: failure() && steps.drift.conclusion != 'failure'
+        run: |
+          {
+            echo "The weekly OpenAPI check could not complete, so it is unknown whether the published /v1 OpenAPI document and openapi/v1.json match."
+            echo
+            echo "The log of the run shows the step that failed: $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
+          } > "$RUNNER_TEMP/failed.md"
+          .github/scripts/openapi-drift-issue.sh report "$FAILED_LABEL" \
+            "The OpenAPI check could not complete" "$RUNNER_TEMP/failed.md"
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index da9c01d..53cf1e3 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -63,7 +63,8 @@ dependency: it changes only by a deliberate decision.
 
 `crates/hodeishield-api/src/generated.rs` is generated from the vendored OpenAPI document
 `openapi/v1.json` by `cargo xtask codegen`. Do not edit it by hand. To follow a new version of `/v1`,
-see [openapi/README.md](openapi/README.md).
+see [openapi/README.md](openapi/README.md). A weekly workflow reports, in an issue, when the
+published document no longer matches that copy; it does not change the repository.
 
 ### Trying the CLI against your organisation
 
diff --git a/openapi/README.md b/openapi/README.md
index b09a71d..761f17a 100644
--- a/openapi/README.md
+++ b/openapi/README.md
@@ -12,12 +12,14 @@ from it; nothing in that client is written by hand from memory.
 
 ## Updating it
 
-The **OpenAPI sync** workflow (`.github/workflows/openapi-sync.yml`) does this every Monday, and on
-demand: it compares this copy with the published document by content (key order and whitespace do
-not count) and, when they differ, opens or updates one pull request against `dev`. That pull request
-contains the published bytes, the steps below and a summary, with the label `breaking-change` when
-[oasdiff](https://github.com/oasdiff/oasdiff) finds one. A maintainer reviews and merges it; nothing
-is merged automatically. By hand:
+The **OpenAPI sync** workflow (`.github/workflows/openapi-sync.yml`) checks this copy every Monday, and
+on demand: it compares it with the published document by content (key order and whitespace do not
+count). When they differ it opens, or comments on, one issue labelled `openapi-drift`, with both
+`info.version` values, whether [oasdiff](https://github.com/oasdiff/oasdiff) finds a breaking change
+(and in which direction) and a summary, and the run is red. When they match again it closes the issue.
+If the published document cannot be fetched or compared, an issue labelled `openapi-check-failed`
+reports that instead. The workflow never changes this copy or opens a pull request: a maintainer
+decides whether the API or this copy is behind. To take the published document, by hand:
 
 1. Replace `v1.json` with the new document, unchanged.
 2. Update the version and SHA-256 above and in `xtask/src/main.rs` (`EXPECTED_SHA256`).

From 9d8b830c8798b2337dbf16c6287ff5a610d646bf Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Wed, 7 Oct 2026 19:27:17 +0200
Subject: [PATCH 03/57] Document defining a profile before signing in to it,
 and waiting for msiexec

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 README.md | 20 +++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index de69fd2..5849858 100644
--- a/README.md
+++ b/README.md
@@ -101,10 +101,16 @@ It installs for all users in `%ProgramFiles%\HodeiShield CLI` and adds that fold
 Silent installation, for Intune, Group Policy or any other deployment tool:
 
 ```powershell
-msiexec /i hodeishield-<version>-x86_64-pc-windows-msvc.msi /qn /norestart /l*v hodeishield-install.log
-msiexec /x hodeishield-<version>-x86_64-pc-windows-msvc.msi /qn /norestart     # uninstall
+$p = Start-Process msiexec -Wait -PassThru -ArgumentList '/i hodeishield-<version>-x86_64-pc-windows-msvc.msi /qn /norestart /l*v hodeishield-install.log'
+$p.ExitCode      # 0 = installed, 3010 = installed and a restart is pending
+# uninstall
+Start-Process msiexec -Wait -PassThru -ArgumentList '/x hodeishield-<version>-x86_64-pc-windows-msvc.msi /qn /norestart'
 ```
 
+Run `msiexec` through `Start-Process -Wait`: PowerShell does not wait for it when it is called
+directly, so `$LASTEXITCODE` would be set before the install finishes. From `cmd.exe`, use
+`start /wait msiexec /i ...`.
+
 - **Intune:** add it as a *Line-of-business app* (MSI), or as a *Windows app (Win32)* with the
   commands above. Intune reads the product code from the MSI for detection.
 - **Group Policy:** *Computer Configuration → Policies → Software Settings → Software installation*,
@@ -225,7 +231,15 @@ hodeishield logout           # revokes the token at the app and removes it from
 
 You sign in to [app.hodeishield.com](https://app.hodeishield.com) as usual (2FA, passkey or SSO), and
 on the consent screen you choose **the one tenant** the CLI may read. A sign-in token never covers
-more than that tenant, and it only reads. To use another tenant, sign in again with another profile (`--profile`).
+more than that tenant, and it only reads. To use another tenant, define another profile and sign in
+to it:
+
+```sh
+hodeishield config set --profile client-b api_url https://api.hodeishield.com
+hodeishield login --profile client-b
+```
+
+A profile that has not been defined is refused (`Profile ... is not defined`).
 
 With `--device`, open the address the CLI prints on any device and **type the code by hand**: the app
 does not accept a link with the code filled in, on purpose.

From 2a963bb559b41046f4e0f58d32ae20b7d16df0f4 Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Thu, 8 Oct 2026 04:16:06 +0200
Subject: [PATCH 04/57] Run the repository builder's security tests in CI

A workflow builds synthetic packages and a throwaway MinIO with throwaway keys, publishes releases with build.sh and publish.sh, installs and upgrades with apt and dnf, and checks that the builder and the clients refuse forged packages and indexes.

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 .github/workflows/repo-builder-tests.yml |  62 ++
 CONTRIBUTING.md                          |   6 +-
 packaging/repo/repo-test.sh              | 779 +++++++++++++++++++++++
 3 files changed, 846 insertions(+), 1 deletion(-)
 create mode 100644 .github/workflows/repo-builder-tests.yml
 create mode 100644 packaging/repo/repo-test.sh

diff --git a/.github/workflows/repo-builder-tests.yml b/.github/workflows/repo-builder-tests.yml
new file mode 100644
index 0000000..411bab4
--- /dev/null
+++ b/.github/workflows/repo-builder-tests.yml
@@ -0,0 +1,62 @@
+name: Repository builder tests
+
+# Runs the security tests of the APT and DNF repository builder (packaging/repo/build.sh and
+# publish.sh) against a throwaway MinIO, with throwaway keys and synthetic packages: nothing secret
+# is used, and nothing is published. The cases that must be refused plant forged packages and indexes
+# in the bucket on purpose, so they run here and are not meant to be run by hand
+# (packaging/repo/repo-test.sh, CONTRIBUTING.md).
+on:
+  pull_request:
+    paths:
+      - "packaging/repo/**"
+      - "packaging/nfpm.yaml"
+      - ".github/workflows/repo-builder-tests.yml"
+  push:
+    branches: [dev, main]
+    paths:
+      - "packaging/repo/**"
+      - "packaging/nfpm.yaml"
+      - ".github/workflows/repo-builder-tests.yml"
+  workflow_dispatch:
+  schedule:
+    - cron: "17 5 * * 1" # Mondays, 05:17 UTC: the clients and the pinned image move on their own
+
+permissions: {}
+
+concurrency:
+  group: repo-builder-tests-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  tests:
+    name: repository builder security tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    permissions:
+      contents: read
+    env:
+      # Pinned by digest, bumped by hand in the periodic dependency review (CONTRIBUTING.md).
+      MINIO_IMAGE: minio/minio:RELEASE.2025-09-07T16-13-09Z@sha256:14cea493d9a34af32f524e538b8346cf79f3321eff8e708c1e2960462bd8936e
+      MC_IMAGE: minio/mc:RELEASE.2025-08-13T08-35-41Z@sha256:a7fe349ef4bd8521fb8497f55c6042871b2ae640607cf99d9bede5e9bdf11727
+      # The same nfpm as the release workflow's.
+      NFPM_VERSION: "2.47.0"
+      NFPM_SHA256: 0660ca602b2d2d2ae4781a06c692b3eeb9d437ffea05b831d76e41f4a3188783
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install nfpm
+        run: |
+          set -euo pipefail
+          archive="nfpm_${NFPM_VERSION}_Linux_x86_64.tar.gz"
+          curl -sSfL -o "$RUNNER_TEMP/$archive" \
+            "https://github.com/goreleaser/nfpm/releases/download/v${NFPM_VERSION}/${archive}"
+          echo "${NFPM_SHA256}  $RUNNER_TEMP/$archive" | sha256sum -c -
+          tar -xzf "$RUNNER_TEMP/$archive" -C "$RUNNER_TEMP" nfpm
+
+      - name: Run the tests
+        run: |
+          set -euo pipefail
+          NFPM="$RUNNER_TEMP/nfpm" sh packaging/repo/repo-test.sh
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2529aa5..6498766 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -136,7 +136,11 @@ after everything they list; packages and by-hash indexes are immutable, so a cli
 index can still finish its update). Only `hodeishield` packages vouched for by the previously signed
 index (an RPM, by the repository key's signature) or by the release's verified `SHA256SUMS` are
 published, and anything else found in the bucket stops the job, so write access to the bucket alone
-cannot get a package signed. The bucket user needs list, read and write permissions
+cannot get a package signed. The `Repository builder tests` workflow checks this on every change to
+`packaging/repo` and weekly (`packaging/repo/repo-test.sh`): with throwaway keys and a throwaway bucket it
+publishes releases, installs and upgrades from the result with apt and dnf, and plants forged packages
+and indexes that the builder and the clients must refuse. Those cases run in CI only and are not meant
+to be run ad hoc. The bucket user needs list, read and write permissions
 only: nothing is ever deleted or overwritten. It runs after the same approval and is skipped while
 the `packaging` environment has no `PACKAGES_S3_ENDPOINT`. It needs the variables
 `PACKAGES_S3_ENDPOINT`, `PACKAGES_S3_REGION` and `PACKAGES_S3_BUCKET`, the secrets
diff --git a/packaging/repo/repo-test.sh b/packaging/repo/repo-test.sh
new file mode 100644
index 0000000..838a566
--- /dev/null
+++ b/packaging/repo/repo-test.sh
@@ -0,0 +1,779 @@
+#!/bin/sh
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Hodeitek S.L.
+#
+# Security tests of the repository builder (build.sh and publish.sh). They run in CI only, in the
+# repository-builder-tests workflow: the cases that must be refused plant forged packages and indexes
+# in a bucket on purpose, and nothing here is meant to be run by hand.
+#
+#   repo-test.sh
+#
+# Environment:
+#   NFPM          absolute path to the nfpm binary (the version pinned in the workflow)
+#   MINIO_IMAGE   the MinIO server image, pinned by digest
+#   MC_IMAGE      the MinIO client image, pinned by digest
+#
+# Everything is made here and thrown away: the signing keys (a certify-only RSA 4096 primary with a
+# signing subkey, like the real one, and a second key for the forgeries), synthetic hodeishield
+# packages built with nfpm from a one-line program, and a MinIO whose publishing user may list, read
+# and write but not delete. The real build.sh and publish.sh run in the image named in
+# packaging/repo/image. The bucket is then served over HTTP to an apt and a dnf client.
+#
+# Every case has an expected outcome, and the run fails if any case ends otherwise:
+#   - publishing a valid release must work (into an empty bucket, on top, again, and a third time);
+#   - the builder must refuse a bucket that holds anything the signed index does not vouch for, an
+#     index that is not the signed one, or a release that is not the hodeishield package, and then
+#     leave the bucket exactly as it was;
+#   - the clients must refuse a tampered index, a corrupt package and a package that is not signed
+#     with the repository key, and must install and upgrade from the untampered repository.
+
+set -eu
+
+here=$(cd "$(dirname "$0")" && pwd)
+root=$(cd "$here/../.." && pwd)
+: "${NFPM:?}" "${MINIO_IMAGE:?}" "${MC_IMAGE:?}"
+for need in docker jq curl gzip sha256sum; do
+  command -v "$need" > /dev/null || {
+    printf 'repo-test.sh: %s is required\n' "$need" >&2
+    exit 2
+  }
+done
+# shellcheck source=/dev/null
+. "$here/image"
+
+builder=rt-builder
+net=rt-net
+minio=rt-minio
+mcbox=rt-mc
+rootuser=rtroot
+rootpass="rtroot-secret-123"
+pubuser=pubuser
+pubpass="pubuser-secret-123"
+srv=http://$minio:9000
+
+uid=$(id -u)
+gid=$(id -g)
+work=$(mktemp -d "${TMPDIR:-/tmp}/repo-test.XXXXXX")
+results=$work/results.tsv
+: > "$results"
+failed=0
+mkdir -p "$work/bin" "$work/t"
+
+# Only the cases that must pass, to check the harness itself.
+positive_only=${REPO_TEST_POSITIVE_ONLY:-}
+
+print_table() {
+  [ -s "$results" ] || return 0
+  printf '\n%-6s %-62s %-46s %s\n' RESULT CASE EXPECTED GOT
+  awk -F'\t' '{ printf "%-6s %-62s %-46s %s\n", $4, $1, $2, $3 }' "$results"
+  printf '\n%s cases, %s failed\n' "$(wc -l < "$results" | tr -d ' ')" \
+    "$(awk -F'\t' '$4 == "FAIL" { n++ } END { print n + 0 }' "$results")"
+}
+
+cleanup() {
+  status=$?
+  trap - EXIT
+  print_table
+  docker rm -f "$minio" "$mcbox" > /dev/null 2>&1 || true
+  docker network rm "$net" > /dev/null 2>&1 || true
+  rm -rf "$work"
+  if [ "$status" = 0 ] && [ "$failed" != 0 ]; then
+    status=1
+  fi
+  exit "$status"
+}
+trap cleanup EXIT
+trap 'exit 130' INT TERM
+
+group() { printf '::group::%s\n' "$*"; }
+endgroup() { printf '::endgroup::\n'; }
+
+# A path under $work, as the containers see it (they mount $work at /w).
+inw() { printf '/w/%s' "${1#"$work"/}"; }
+
+# record <case> <expected> <got> <PASS|FAIL>
+record() {
+  printf '%s\t%s\t%s\t%s\n' "$1" "$2" "$3" "$4" >> "$results"
+  if [ "$4" != PASS ]; then
+    failed=1
+    printf '::error::%s: expected %s, got %s\n' "$1" "$2" "$3"
+  fi
+}
+
+# --- The builder image ---------------------------------------------------------------------------------
+group "Build the repository image"
+# shellcheck disable=SC2153
+docker build --quiet --tag "$builder" - << EOF
+FROM $IMAGE
+RUN apt-get update -qq && apt-get install -y -qq --no-install-recommends $PACKAGES \
+  && rm -rf /var/lib/apt/lists/*
+EOF
+endgroup
+
+# Runs a command in the builder image, with $work at /w.
+tool() {
+  docker run --rm --user "$uid:$gid" --env HOME=/tmp --volume "$work:/w" --workdir /w "$builder" "$@"
+}
+
+# --- Helper scripts that run in the builder image -----------------------------------------------------
+cat > "$work/bin/keys.sh" << 'EOF'
+set -eu
+export HOME=/tmp
+quiet() { gpg --batch --quiet --pinentry-mode loopback --passphrase '' "$@"; }
+fingerprint() { gpg --batch --with-colons --list-keys | awk -F: '$1 == "fpr" { print $10; exit }'; }
+
+# The repository key: a primary that can only certify, and a signing subkey. Only the subkey's secret
+# part reaches the keyring that the builder uses.
+GNUPGHOME=/w/gnupg-primary
+export GNUPGHOME
+mkdir -m 700 "$GNUPGHOME"
+quiet --quick-generate-key 'HodeiShield repository test key <repo-test@example.invalid>' rsa4096 cert never
+primary=$(fingerprint)
+quiet --quick-add-key "$primary" rsa4096 sign never
+gpg --batch --armor --export "$primary" > /w/pub.asc
+quiet --export-secret-subkeys "$primary" > /w/subkey.gpg
+gpgconf --kill all
+
+GNUPGHOME=/w/gnupg-sign
+export GNUPGHOME
+mkdir -m 700 "$GNUPGHOME"
+gpg --batch --quiet --import /w/subkey.gpg
+sub=$(gpg --batch --with-colons --list-secret-keys |
+  awk -F: '$1 == "ssb" { sign = ($12 ~ /s/) } $1 == "fpr" && sign { print $10; sign = 0 }')
+[ "$(printf '%s\n' "$sub" | grep -c .)" = 1 ]
+printf '%s!\n' "$sub" > /w/signing_key
+gpgconf --kill all
+rm -f /w/subkey.gpg
+
+# Another key, for forgeries.
+GNUPGHOME=/w/gnupg-evil
+export GNUPGHOME
+mkdir -m 700 "$GNUPGHOME"
+quiet --quick-generate-key 'Another key <other@example.invalid>' rsa2048 sign never
+other=$(fingerprint)
+printf '%s\n' "$other" > /w/evil.fpr
+gpg --batch --armor --export "$other" > /w/evil.asc
+gpgconf --kill all
+EOF
+
+# signrpm.sh <gnupghome> <key> <public key> <rpm>...
+cat > "$work/bin/signrpm.sh" << 'EOF'
+set -eu
+export HOME=/tmp
+home=$1 key=$2 pub=$3
+shift 3
+db=$(mktemp -d)
+trap 'rm -rf "$db"' EXIT
+rpm --dbpath "$db" --import "$pub"
+GNUPGHOME=$home rpmsign --define "_dbpath $db" --define "_gpg_name $key" \
+  --define "_gpg_digest_algo sha512" --addsign "$@" > /dev/null
+EOF
+
+# rpmrepo.sh <dir>: a DNF repository of the packages in <dir>, with repomd.xml signed by the repository key.
+cat > "$work/bin/rpmrepo.sh" << 'EOF'
+set -eu
+export HOME=/tmp GNUPGHOME=/w/gnupg-sign
+createrepo_c --quiet --no-database --general-compress-type=gz "$1"
+gpg --batch --yes --local-user "$(cat /w/signing_key)" --digest-algo SHA512 --armor --detach-sign \
+  --output "$1/repodata/repomd.xml.asc" "$1/repodata/repomd.xml"
+EOF
+
+# evilsign.sh <in> <out>: clear-signs a file with the other key.
+cat > "$work/bin/evilsign.sh" << 'EOF'
+set -eu
+export HOME=/tmp GNUPGHOME=/w/gnupg-evil
+gpg --batch --yes --local-user "$(cat /w/evil.fpr)" --digest-algo SHA512 --clearsign --output "$2" "$1"
+EOF
+
+# --- Client scripts (run as root in the apt and dnf containers) --------------------------------------
+cat > "$work/bin/apt-client.sh" << 'EOF'
+# apt-client.sh ok <url 1> <url 2> <version 1> <version 2>
+# apt-client.sh refuse <index|package> <url> [<pattern>]
+set -u
+export DEBIAN_FRONTEND=noninteractive
+only="-o Dir::Etc::sourcelist=/etc/apt/sources.list.d/hodeishield.list -o Dir::Etc::sourceparts=/nonexistent"
+setup() {
+  mkdir -p /etc/apt/keyrings
+  curl -fsS "$1/gpg.key" -o /etc/apt/keyrings/hodeishield.asc || { echo "SETUP: cannot fetch the key"; exit 90; }
+  echo "deb [signed-by=/etc/apt/keyrings/hodeishield.asc] $1/apt stable main" > /etc/apt/sources.list.d/hodeishield.list
+}
+mode=$1
+shift
+case $mode in
+ok)
+  set -e
+  setup "$1"
+  apt-get $only update
+  apt-get $only install -y hodeishield
+  [ "$(hodeishield --version)" = "hodeishield $3" ]
+  setup "$2"
+  apt-get $only update
+  apt-get $only install -y --only-upgrade hodeishield
+  [ "$(hodeishield --version)" = "hodeishield $4" ]
+  echo "OK: installed $3 and upgraded to $4, with the repository's signatures checked"
+  ;;
+refuse)
+  kind=$1 url=$2 pattern=${3:-.}
+  setup "$url"
+  out=$(apt-get $only update 2>&1)
+  rc=$?
+  echo "$out"
+  if [ "$kind" = index ]; then
+    [ "$rc" != 0 ] || { echo "NOT REFUSED: apt-get update accepted the index"; exit 1; }
+  else
+    [ "$rc" = 0 ] || { echo "SETUP: apt-get update failed on a valid index"; exit 1; }
+  fi
+  out2=$(apt-get $only install -y hodeishield 2>&1)
+  rc2=$?
+  echo "$out2"
+  [ "$rc2" != 0 ] || { echo "NOT REFUSED: hodeishield was installed"; exit 1; }
+  if dpkg -s hodeishield > /dev/null 2>&1; then
+    echo "NOT REFUSED: hodeishield is installed"
+    exit 1
+  fi
+  line=$(printf '%s\n%s\n' "$out" "$out2" | grep -E "$pattern" | head -n 1)
+  [ -n "$line" ] || { echo "NOT REFUSED FOR THE EXPECTED REASON"; exit 1; }
+  echo "REFUSED: $line"
+  ;;
+esac
+EOF
+
+cat > "$work/bin/dnf-client.sh" << 'EOF'
+# dnf-client.sh ok <url 1> <url 2> <version 1> <version 2>
+# dnf-client.sh refuse <index|package> <url> [<pattern>]
+set -uf
+dnfq="dnf -y --disablerepo=* --enablerepo=hodeishield"
+repo=/etc/yum.repos.d/hodeishield.repo
+setup() {
+  curl -fsS "$1/rpm/hodeishield.repo" -o "$repo" || { echo "SETUP: cannot fetch the .repo file"; exit 90; }
+  sed -i "s#https://packages.hodeishield.com#$1#g" "$repo"
+  grep -qx 'gpgcheck=1' "$repo" && grep -qx 'repo_gpgcheck=1' "$repo" || { echo "SETUP: signature checks are off"; exit 90; }
+}
+mode=$1
+shift
+case $mode in
+ok)
+  set -e
+  setup "$1"
+  $dnfq install hodeishield
+  [ "$(hodeishield --version)" = "hodeishield $3" ]
+  sed -i "s#$1#$2#g" "$repo"
+  dnf clean all
+  $dnfq upgrade --refresh hodeishield
+  [ "$(hodeishield --version)" = "hodeishield $4" ]
+  grep -qx 'gpgcheck=1' "$repo" && grep -qx 'repo_gpgcheck=1' "$repo"
+  echo "OK: installed $3 and upgraded to $4, with gpgcheck and repo_gpgcheck on"
+  ;;
+refuse)
+  kind=$1 url=$2 pattern=${3:-.}
+  setup "$url"
+  out=$($dnfq makecache 2>&1)
+  rc=$?
+  echo "$out"
+  if [ "$kind" = index ]; then
+    [ "$rc" != 0 ] || { echo "NOT REFUSED: dnf accepted the metadata"; exit 1; }
+  else
+    [ "$rc" = 0 ] || { echo "SETUP: dnf could not read valid metadata"; exit 1; }
+  fi
+  out2=$($dnfq install hodeishield 2>&1)
+  rc2=$?
+  echo "$out2"
+  [ "$rc2" != 0 ] || { echo "NOT REFUSED: hodeishield was installed"; exit 1; }
+  if rpm -q hodeishield > /dev/null 2>&1; then
+    echo "NOT REFUSED: hodeishield is installed"
+    exit 1
+  fi
+  line=$(printf '%s\n%s\n' "$out" "$out2" | grep -E "$pattern" | head -n 1)
+  [ -n "$line" ] || { echo "NOT REFUSED FOR THE EXPECTED REASON"; exit 1; }
+  echo "REFUSED: $line"
+  ;;
+esac
+EOF
+
+# --- Keys ------------------------------------------------------------------------------------------------
+group "Throwaway keys"
+tool sh /w/bin/keys.sh
+signing_key=$(cat "$work/signing_key")
+find "$work" -maxdepth 1 -type f | sort | tr '\n' ' '
+printf '\nsigning subkey %s\n' "$signing_key"
+endgroup
+
+# --- Packages ------------------------------------------------------------------------------------------
+# mkpkgs <out dir> <name> <version> <what the program prints>: .deb and .rpm for amd64 and arm64.
+mkpkgs() {
+  out=$1 name=$2 version=$3 says=$4
+  config=$root/packaging/nfpm.yaml
+  if [ "$name" != hodeishield ]; then
+    config=$work/nfpm-$name.yaml
+    sed "s/^name: hodeishield\$/name: $name/" "$root/packaging/nfpm.yaml" > "$config"
+  fi
+  stage=$(mktemp -d "$work/stage.XXXXXX")
+  mkdir -p "$stage/man" "$stage/completions" "$out"
+  printf '#!/bin/sh\necho "%s"\n' "$says" > "$stage/hodeishield"
+  chmod 755 "$stage/hodeishield"
+  printf '.TH HODEISHIELD 1\n' | gzip -9n > "$stage/man/hodeishield.1.gz"
+  for completion in hodeishield.bash _hodeishield hodeishield.fish; do
+    printf '# test\n' > "$stage/completions/$completion"
+  done
+  cp "$root/LICENSE" "$root/NOTICE" "$stage/"
+  for arch in amd64 arm64; do
+    for packager in deb rpm; do
+      (cd "$stage" && VERSION=$version ARCH=$arch "$NFPM" package -f "$config" -p "$packager" -t "$out/" > /dev/null)
+    done
+  done
+  rm -rf "$stage"
+}
+
+group "Synthetic packages"
+pk=$work/pk
+mkpkgs "$pk/v1" hodeishield 0.2.0 "hodeishield 0.2.0"
+mkpkgs "$pk/v2" hodeishield 0.2.1 "hodeishield 0.2.1"
+mkpkgs "$pk/v3" hodeishield 0.2.2 "hodeishield 0.2.2"
+ls "$pk/v1" "$pk/v2" "$pk/v3"
+endgroup
+
+# --- MinIO ------------------------------------------------------------------------------------------------
+group "MinIO"
+docker network create "$net" > /dev/null
+docker run -d --name "$minio" --network "$net" --env MINIO_ROOT_USER="$rootuser" \
+  --env MINIO_ROOT_PASSWORD="$rootpass" "$MINIO_IMAGE" server /data > /dev/null
+docker run -d --name "$mcbox" --network "$net" --user "$uid:$gid" --env MC_CONFIG_DIR=/tmp/mc \
+  --volume "$work:/w" --entrypoint sh "$MC_IMAGE" -c 'exec sleep 86400' > /dev/null
+mcx() { docker exec "$mcbox" mc "$@"; }
+tries=0
+until mcx alias set r "$srv" "$rootuser" "$rootpass" > /dev/null 2>&1; do
+  tries=$((tries + 1))
+  [ "$tries" -lt 60 ] || {
+    echo "repo-test.sh: MinIO did not start" >&2
+    docker logs "$minio" >&2
+    exit 1
+  }
+  sleep 1
+done
+# The publishing user may list, read and write, never delete (like the real one).
+cat > "$work/policy.json" << 'EOF'
+{"Version": "2012-10-17", "Statement": [
+  {"Effect": "Allow", "Action": ["s3:ListBucket"], "Resource": ["arn:aws:s3:::rt-*"]},
+  {"Effect": "Allow", "Action": ["s3:GetObject", "s3:PutObject"], "Resource": ["arn:aws:s3:::rt-*/*"]}]}
+EOF
+mcx admin policy create r rt-nodelete /w/policy.json > /dev/null
+mcx admin user add r "$pubuser" "$pubpass" > /dev/null
+mcx admin policy attach r rt-nodelete --user "$pubuser" > /dev/null
+mcx alias set u "$srv" "$pubuser" "$pubpass" > /dev/null
+endgroup
+
+newbucket() {
+  mcx mb --quiet "r/$1" > /dev/null
+  mcx anonymous set download "r/$1" > /dev/null
+}
+# clone <from> <to>
+clone() {
+  newbucket "$2"
+  mcx mirror --quiet "r/$1" "r/$2" > /dev/null
+}
+# put <bucket> <key> <file>
+put() { mcx cp --quiet "$(inw "$3")" "r/$1/$2" > /dev/null; }
+# del <bucket> <key>
+del() { mcx rm --quiet "r/$1/$2" > /dev/null; }
+# get <bucket> <key> <file>
+get() { mcx cat "r/$1/$2" > "$3"; }
+# snap <bucket>: every object with its size, ETag and modification time.
+snap() { mcx ls --recursive --json "r/$1" | jq -r '[.key, (.size | tostring), .etag, .lastModified] | @tsv' | sort; }
+# packages_of <bucket>: the packages in the bucket.
+packages_of() { snap "$1" | awk -F'\t' '$1 ~ /^apt\/pool\// || $1 ~ /^rpm\/[^\/]*\/[^\/]*\.rpm$/'; }
+# hash_of <InRelease> <arch>: the SHA256 that the signed index gives for that architecture's Packages.
+hash_of() {
+  awk -v f="main/binary-$2/Packages" '/^[^ ]/ { s = ($0 == "SHA256:"); next } s && $3 == f { print $1 }' "$1"
+}
+
+# publish <bucket> <new packages dir>: runs publish.sh as the workflow does; sets $out and $rc.
+publish() {
+  rc=0
+  out=$(docker run --rm --network "$net" --user "$uid:$gid" --env HOME=/tmp \
+    --env PACKAGES_S3_ENDPOINT="$srv" --env PACKAGES_S3_REGION=us-east-1 --env PACKAGES_S3_BUCKET="$1" \
+    --env PACKAGES_S3_ACCESS_KEY_ID="$pubuser" --env PACKAGES_S3_SECRET_ACCESS_KEY="$pubpass" \
+    --env SIGNING_KEY="$signing_key" --env GNUPGHOME=/gnupg --env PUBLIC_KEY=/gpg.key \
+    --volume "$work/gnupg-sign:/gnupg" --volume "$work/pub.asc:/gpg.key:ro" \
+    --volume "$here:/repo:ro" --volume "$2:/new:ro" \
+    "$builder" sh /repo/publish.sh /new 2>&1) || rc=$?
+}
+
+# must_publish <case> <description> <bucket> <new dir>
+must_publish() {
+  group "$1 $2"
+  publish "$3" "$4"
+  if [ "$rc" = 0 ] && printf '%s\n' "$out" | grep -q '^Repository built and verified'; then
+    verdict=PASS
+    got="exit 0, repository built and verified"
+  else
+    verdict=FAIL
+    got="exit $rc"
+    printf '%s\n' "$out"
+  fi
+  printf '%s\n' "$out" | tail -n 3
+  endgroup
+  record "$1 $2" "publishes" "$got" "$verdict"
+}
+
+# must_refuse <case> <description> <bucket> <message (regex)> [<new dir>]
+# The bucket is as the caller left it; publishing must fail with that message and change nothing.
+must_refuse() {
+  id=$1 desc=$2 bucket=$3 message=$4 newdir=${5:-$pk/v3}
+  group "$id $desc"
+  before=$(snap "$bucket")
+  publish "$bucket" "$newdir"
+  after=$(snap "$bucket")
+  verdict=PASS
+  if [ "$rc" = 0 ]; then
+    verdict=FAIL
+    got="PUBLISHED (exit 0)"
+  else
+    got="refused (exit $rc)"
+    line=$(printf '%s\n' "$out" | grep -E "$message" | head -n 1 || true)
+    if [ -z "$line" ]; then
+      verdict=FAIL
+      got="$got, for another reason"
+    fi
+  fi
+  if [ "$before" = "$after" ]; then
+    got="$got, bucket and InRelease unchanged"
+  else
+    verdict=FAIL
+    got="$got, BUCKET CHANGED"
+    printf '%s\n' "$before" > "$work/t/before"
+    printf '%s\n' "$after" > "$work/t/after"
+    diff -u "$work/t/before" "$work/t/after" || true
+  fi
+  [ "$verdict" = PASS ] || printf '%s\n' "$out"
+  printf '%s\n' "$out" | tail -n 3
+  endgroup
+  record "$id $desc" "refused, nothing uploaded" "$got" "$verdict"
+}
+
+# --- Must pass: publishing -------------------------------------------------------------------------------
+newbucket rt-v1
+must_publish P1 "release 0.2.0 into an empty bucket" rt-v1 "$pk/v1"
+for key in gpg.key index.html apt/dists/stable/InRelease apt/dists/stable/Release.gpg rpm/hodeishield.repo \
+  rpm/x86_64/repodata/repomd.xml.asc rpm/aarch64/repodata/repomd.xml.asc; do
+  mcx stat "r/rt-v1/$key" > /dev/null 2>&1 || record "P1 $key is published" present missing FAIL
+done
+
+clone rt-v1 rt-v2
+must_publish P2 "release 0.2.1 on top of 0.2.0" rt-v2 "$pk/v2"
+get rt-v2 apt/pool/main/h/hodeishield/hodeishield_0.2.0-1_amd64.deb "$work/t/old.deb" ||
+  record "P2 the earlier release is still there" present missing FAIL
+get rt-v2 apt/dists/stable/main/binary-amd64/Packages "$work/t/Packages"
+if grep -q '^Version: 0.2.0-1$' "$work/t/Packages" && grep -q '^Version: 0.2.1-1$' "$work/t/Packages"; then
+  record "P2 the index lists both releases" "0.2.0 and 0.2.1" "0.2.0 and 0.2.1" PASS
+else
+  record "P2 the index lists both releases" "0.2.0 and 0.2.1" "see Packages" FAIL
+fi
+
+before=$(packages_of rt-v2)
+must_publish P3 "release 0.2.1 again (idempotent)" rt-v2 "$pk/v2"
+if [ "$before" = "$(packages_of rt-v2)" ]; then
+  record "P3 published packages untouched" "same objects" "same objects" PASS
+else
+  record "P3 published packages untouched" "same objects" "CHANGED" FAIL
+fi
+
+clone rt-v2 rt-ctl
+must_publish P4 "release 0.2.2 on the base of the refusal cases" rt-ctl "$pk/v3"
+
+# --- Must pass: clients ----------------------------------------------------------------------------------
+docker build --quiet --tag rt-apt-client - << 'EOF' > /dev/null
+FROM debian:stable
+RUN apt-get update -qq && apt-get install -y -qq --no-install-recommends curl ca-certificates \
+  && rm -rf /var/lib/apt/lists/*
+EOF
+
+# client <apt|dnf> <case> <description> <expected> <script args...>: the script exits 0 when it got what it expected.
+client() {
+  kind=$1 id=$2 desc=$3 expected=$4
+  shift 4
+  case $kind in
+    apt) image=rt-apt-client ;;
+    dnf) image=rockylinux:9 ;;
+  esac
+  group "$id $desc"
+  rc=0
+  out=$(docker run --rm --network "$net" --volume "$work/bin:/b:ro" "$image" sh "/b/$kind-client.sh" "$@" 2>&1) || rc=$?
+  printf '%s\n' "$out" | tail -n 40
+  endgroup
+  line=$(printf '%s\n' "$out" | grep -E '^(OK|REFUSED):' | tail -n 1 || true)
+  if [ "$rc" = 0 ] && [ -n "$line" ]; then
+    record "$id $desc" "$expected" "$(printf '%s' "$line" | cut -c1-120)" PASS
+  else
+    record "$id $desc" "$expected" "exit $rc: $(printf '%s\n' "$out" | tail -n 1 | cut -c1-100)" FAIL
+  fi
+}
+
+client apt P5 "apt (debian:stable) installs 0.2.0, upgrades to 0.2.1" "installs and upgrades" \
+  ok "$srv/rt-v1" "$srv/rt-v2" 0.2.0 0.2.1
+client dnf P6 "dnf (rockylinux:9) installs 0.2.0, upgrades to 0.2.1" "installs and upgrades" \
+  ok "$srv/rt-v1" "$srv/rt-v2" 0.2.0 0.2.1
+
+if [ -n "$positive_only" ]; then
+  exit 0
+fi
+
+# --- The forgeries ------------------------------------------------------------------------------------
+group "Forged packages and indexes"
+mkpkgs "$pk/evil" hodeishield 9.9.9 "evil"
+mkpkgs "$pk/ssh" openssh-server 99.0.0 "not hodeishield"
+mkpkgs "$pk/alt" hodeishield 0.2.1 "hodeishield 0.2.1 with another payload"
+evil_deb=$pk/evil/hodeishield_9.9.9-1_amd64.deb
+ssh_deb=$pk/ssh/openssh-server_99.0.0-1_amd64.deb
+ssh_rpm=openssh-server-99.0.0-1.x86_64.rpm
+# The same .rpm files signed with the repository key, and with another key.
+mkdir -p "$work/ours" "$work/other"
+cp "$pk/v1/hodeishield-0.2.0-1.x86_64.rpm" "$pk/ssh/$ssh_rpm" "$work/ours/"
+cp "$pk/evil/hodeishield-9.9.9-1.x86_64.rpm" "$pk/v2/hodeishield-0.2.1-1.x86_64.rpm" "$work/other/"
+tool sh /w/bin/signrpm.sh /w/gnupg-sign "$signing_key" /w/pub.asc \
+  /w/ours/hodeishield-0.2.0-1.x86_64.rpm "/w/ours/$ssh_rpm"
+tool sh /w/bin/signrpm.sh /w/gnupg-evil "$(cat "$work/evil.fpr")" /w/evil.asc \
+  /w/other/hodeishield-9.9.9-1.x86_64.rpm /w/other/hodeishield-0.2.1-1.x86_64.rpm
+# An index that lists an extra package, and the signed Release of the base, to forge from.
+base=rt-v2
+get rt-v2 apt/dists/stable/InRelease "$work/t/InRelease"
+get rt-v2 apt/dists/stable/Release "$work/t/Release"
+get rt-v1 apt/dists/stable/InRelease "$work/t/InRelease.old"
+real_hash=$(hash_of "$work/t/InRelease" amd64)
+get rt-v2 "apt/dists/stable/main/binary-amd64/by-hash/SHA256/$real_hash" "$work/t/Packages.real"
+{
+  cat "$work/t/Packages.real"
+  printf '\nPackage: hodeishield\nVersion: 9.9.9-1\nArchitecture: amd64\n'
+  printf 'Filename: pool/main/h/hodeishield/hodeishield_9.9.9-1_amd64.deb\nSize: %s\nSHA256: %s\n' \
+    "$(wc -c < "$evil_deb" | tr -d ' ')" "$(sha256sum < "$evil_deb" | cut -d' ' -f1)"
+} > "$work/t/Packages.evil"
+evil_hash=$(sha256sum < "$work/t/Packages.evil" | cut -d' ' -f1)
+evil_size=$(wc -c < "$work/t/Packages.evil" | tr -d ' ')
+awk -v old="$real_hash" -v new="$evil_hash" -v size="$evil_size" \
+  '$1 == old && $3 == "main/binary-amd64/Packages" { print " " new " " size " " $3; next } { print }' \
+  "$work/t/Release" > "$work/t/Release.evil"
+tool sh /w/bin/evilsign.sh /w/t/Release.evil /w/t/InRelease.evil
+endgroup
+
+H=apt/pool/main/h/hodeishield
+IR=apt/dists/stable/InRelease
+BH=apt/dists/stable/main/binary-amd64/by-hash/SHA256
+
+# fresh <id>: a copy of the base to plant things in.
+fresh() { clone "$base" "rt-$1"; }
+
+# Things in the pool that are not the package the signed index vouches for.
+fresh b01
+put rt-b01 apt/pool/main/o/openssh-server/openssh-server_99.0.0-1_amd64.deb "$ssh_deb"
+must_refuse B01 "deb of another package, outside the expected path" rt-b01 "build.sh: unexpected files in the bucket"
+
+fresh b02
+put rt-b02 "$H/hodeishield_9.9.9-1_amd64.deb" "$evil_deb"
+must_refuse B02 "planted hodeishield deb, not in the signed index" rt-b02 "build.sh: .* is in the bucket but neither in the signed index"
+
+fresh b03
+put rt-b03 "$H/hodeishield_9.9.9-1_amd64.deb" "$ssh_deb"
+must_refuse B03 "other package's deb renamed hodeishield_9.9.9" rt-b03 "build.sh: .* is in the bucket but neither in the signed index"
+
+fresh b04
+put rt-b04 "$H/hodeishield_0.2.1-1_amd64.deb" "$evil_deb"
+must_refuse B04 "published deb overwritten with another payload" rt-b04 "build.sh: .* is in the bucket but neither in the signed index"
+
+fresh b05
+printf 'not a package\n' > "$work/t/README"
+put rt-b05 "$H/README" "$work/t/README"
+must_refuse B05 "stray file in the pool" rt-b05 "build.sh: unexpected files in the bucket"
+
+fresh b06
+put rt-b06 "$H/sub/hodeishield_9.9.9-1_amd64.deb" "$evil_deb"
+must_refuse B06 "deb in a subdirectory of the pool" rt-b06 "build.sh: unexpected files in the bucket"
+
+fresh b07
+put rt-b07 "$H/hodeishield_9 9_amd64.deb" "$evil_deb"
+put rt-b07 "$H/-hodeishield_9.9_amd64.deb" "$evil_deb"
+must_refuse B07 "deb file names with a space or a leading dash" rt-b07 "build.sh: unexpected files in the bucket"
+
+# Things among the RPMs.
+fresh b08
+put rt-b08 rpm/x86_64/hodeishield-9.9.9-1.x86_64.rpm "$pk/evil/hodeishield-9.9.9-1.x86_64.rpm"
+must_refuse B08 "unsigned rpm" rt-b08 "build.sh: .* is not signed with the repository key"
+
+fresh b09
+put rt-b09 rpm/x86_64/hodeishield-9.9.9-1.x86_64.rpm "$work/other/hodeishield-9.9.9-1.x86_64.rpm"
+must_refuse B09 "rpm signed by another key" rt-b09 "build.sh: .* is not signed with the repository key"
+
+fresh b10
+put rt-b10 "rpm/x86_64/$ssh_rpm" "$work/ours/$ssh_rpm"
+must_refuse B10 "rpm of another package signed with our key" rt-b10 "build.sh: unexpected files in the bucket"
+
+fresh b11
+put rt-b11 rpm/x86_64/hodeishield-99.0.0-1.x86_64.rpm "$work/ours/$ssh_rpm"
+must_refuse B11 "our-key rpm named hodeishield with another package inside" rt-b11 \
+  "build.sh: .* is not the hodeishield package for x86_64"
+
+fresh b12
+put rt-b12 rpm/aarch64/hodeishield-0.2.0-1.aarch64.rpm "$work/ours/hodeishield-0.2.0-1.x86_64.rpm"
+must_refuse B12 "our-key x86_64 rpm under an aarch64 name" rt-b12 "build.sh: .* is not the hodeishield package for aarch64"
+
+fresh b13
+put rt-b13 rpm/x86_64/hodeishield-0.2.5-1.x86_64.rpm "$work/ours/hodeishield-0.2.0-1.x86_64.rpm"
+must_refuse B13 "our-key rpm renamed to another version" rt-b13 "build.sh: .* is not the hodeishield package for x86_64"
+
+fresh b14
+put rt-b14 rpm/noarch/hodeishield-0.2.0-1.noarch.rpm "$work/ours/hodeishield-0.2.0-1.x86_64.rpm"
+must_refuse B14 "rpm in an unexpected architecture directory" rt-b14 "build.sh: unexpected files in the bucket"
+
+fresh b15
+put rt-b15 "rpm/x86_64/x digests signatures OK.rpm" "$pk/evil/hodeishield-9.9.9-1.x86_64.rpm"
+must_refuse B15 "rpm whose file name imitates rpm's verdict" rt-b15 "build.sh: unexpected files in the bucket"
+
+# The signed index.
+fresh b16
+put rt-b16 "$BH/$real_hash" "$work/t/Packages.evil"
+put rt-b16 "$H/hodeishield_9.9.9-1_amd64.deb" "$evil_deb"
+must_refuse B16 "tampered by-hash Packages and a planted deb" rt-b16 \
+  "build.sh: the published Packages \(amd64\) does not match the published InRelease"
+
+fresh b17
+sed 's/^Codename: stable$/Codename: stablf/' "$work/t/InRelease" > "$work/t/InRelease.edit"
+put rt-b17 "$IR" "$work/t/InRelease.edit"
+must_refuse B17 "InRelease edited after signing" rt-b17 "build.sh: the published InRelease does not verify"
+
+fresh b18
+cat "$work/t/InRelease" "$work/t/InRelease" > "$work/t/InRelease.two"
+put rt-b18 "$IR" "$work/t/InRelease.two"
+must_refuse B18 "InRelease with two signed blocks" rt-b18 \
+  "(build|publish).sh: the published InRelease (is not a single signed message|does not give one SHA256)"
+
+fresh b19
+{ printf 'text before the signed message\n'; cat "$work/t/InRelease"; } > "$work/t/InRelease.before"
+put rt-b19 "$IR" "$work/t/InRelease.before"
+must_refuse B19 "InRelease with text before the signed message" rt-b19 \
+  "build.sh: the published InRelease is not a single signed message"
+
+fresh b20
+{ cat "$work/t/InRelease"; printf 'text after the signed message\n'; } > "$work/t/InRelease.after"
+put rt-b20 "$IR" "$work/t/InRelease.after"
+must_refuse B20 "InRelease with text after the signed message" rt-b20 \
+  "build.sh: the published InRelease is not a single signed message"
+
+fresh b21
+put rt-b21 "$IR" "$work/t/InRelease.evil"
+put rt-b21 "$BH/$evil_hash" "$work/t/Packages.evil"
+put rt-b21 "$H/hodeishield_9.9.9-1_amd64.deb" "$evil_deb"
+must_refuse B21 "InRelease re-signed with another key, with its Packages and deb" rt-b21 \
+  "build.sh: the published InRelease does not verify"
+
+fresh b22
+del rt-b22 "$IR"
+must_refuse B22 "InRelease removed while the pool is not empty" rt-b22 \
+  "build.sh: .* is in the bucket but neither in the signed index"
+
+fresh b23
+put rt-b23 "$IR" "$work/t/InRelease.old"
+must_refuse B23 "an older InRelease, validly signed" rt-b23 \
+  "build.sh: .* is in the bucket but neither in the signed index"
+
+fresh b24
+put rt-b24 "$IR" "$work/policy.json"
+must_refuse B24 "InRelease replaced by a file that is not signed" rt-b24 \
+  "publish.sh: the published InRelease does not give one SHA256"
+
+fresh b25
+del rt-b25 "$H/hodeishield_0.2.0-1_amd64.deb"
+must_refuse B25 "a deb that the signed index lists is gone" rt-b25 "build.sh: the signed index lists .*, which is not in the bucket"
+
+# The release itself.
+fresh n01
+must_refuse N01 "release holds a deb of another package" rt-n01 "build.sh: not a hodeishield package file" "$pk/ssh"
+
+fresh n02
+mkdir -p "$work/n02"
+cp "$ssh_deb" "$work/n02/hodeishield_0.2.2-1_amd64.deb"
+must_refuse N02 "release holds another package's deb named hodeishield" rt-n02 \
+  "build.sh: .* is not the hodeishield package" "$work/n02"
+
+fresh n03
+mkdir -p "$work/n03"
+cp "$pk/ssh/$ssh_rpm" "$work/n03/hodeishield-0.2.2-1.x86_64.rpm"
+must_refuse N03 "release holds another package's rpm named hodeishield" rt-n03 \
+  "build.sh: .* is not the hodeishield package for its architecture" "$work/n03"
+
+fresh n04
+mkdir -p "$work/n04"
+cp "$pk/alt/hodeishield_0.2.1-1_amd64.deb" "$work/n04/"
+must_refuse N04 "same deb file name as a published one, other content" rt-n04 \
+  "build.sh: .* is already published with different content" "$work/n04"
+
+fresh n05
+mkdir -p "$work/n05"
+cp "$pk/alt/hodeishield-0.2.1-1.x86_64.rpm" "$work/n05/"
+must_refuse N05 "same rpm file name as a published one, other content" rt-n05 \
+  "build.sh: .* is already published with different content" "$work/n05"
+
+# The user of the bucket cannot delete, as in production.
+rc=0
+mcx rm --quiet "u/rt-ctl/gpg.key" > /dev/null 2>&1 || rc=$?
+if [ "$rc" != 0 ] && mcx stat "r/rt-ctl/gpg.key" > /dev/null 2>&1; then
+  record "S1 the publishing user cannot delete" "delete denied" "denied" PASS
+else
+  record "S1 the publishing user cannot delete" "delete denied" "ALLOWED" FAIL
+fi
+
+# --- Clients must refuse -----------------------------------------------------------------------------------
+# Tampered copies of the published repository (rt-v2), served as they are.
+sig='BADSIG|NO_PUBKEY|not signed|[Ss]ignature'
+fresh c1
+sed 's/^Codename: stable$/Codename: stablf/' "$work/t/InRelease" > "$work/t/InRelease.c1"
+put rt-c1 "$IR" "$work/t/InRelease.c1"
+client apt C1 "apt: InRelease tampered" "update and install refused" refuse index "$srv/rt-c1" "$sig"
+
+fresh c2
+del rt-c2 "$IR"
+sed 's/^Codename: stable$/Codename: stablf/' "$work/t/Release" > "$work/t/Release.c2"
+put rt-c2 apt/dists/stable/Release "$work/t/Release.c2"
+client apt C2 "apt: Release tampered (no InRelease)" "update and install refused" refuse index "$srv/rt-c2" "$sig"
+
+fresh c3
+get rt-v2 rpm/x86_64/repodata/repomd.xml "$work/t/repomd.xml"
+sed 's#<revision>#<revision>9#' "$work/t/repomd.xml" > "$work/t/repomd.xml.c3"
+cmp -s "$work/t/repomd.xml" "$work/t/repomd.xml.c3" && {
+  echo "repo-test.sh: repomd.xml has no <revision>" >&2
+  exit 1
+}
+put rt-c3 rpm/x86_64/repodata/repomd.xml "$work/t/repomd.xml.c3"
+client dnf C3 "dnf: repomd.xml tampered" "metadata and install refused" refuse index "$srv/rt-c3" 'GPG|[Ss]ignature'
+
+# flip <file>: the same file with one byte changed.
+flip() {
+  cp "$1" "$2"
+  printf 'X' | dd of="$2" bs=1 seek=200 conv=notrunc 2> /dev/null
+}
+
+fresh c4
+get rt-v2 "$H/hodeishield_0.2.1-1_amd64.deb" "$work/t/c4.deb"
+flip "$work/t/c4.deb" "$work/t/c4.bad.deb"
+cmp -s "$work/t/c4.deb" "$work/t/c4.bad.deb" && exit 1
+put rt-c4 "$H/hodeishield_0.2.1-1_amd64.deb" "$work/t/c4.bad.deb"
+client apt C4 "apt: corrupt deb (one byte changed)" "install refused" refuse package "$srv/rt-c4" 'Hash Sum mismatch|unexpected size|[Hh]ash'
+
+fresh c5
+get rt-v2 rpm/x86_64/hodeishield-0.2.1-1.x86_64.rpm "$work/t/c5.rpm"
+flip "$work/t/c5.rpm" "$work/t/c5.bad.rpm"
+cmp -s "$work/t/c5.rpm" "$work/t/c5.bad.rpm" && exit 1
+put rt-c5 rpm/x86_64/hodeishield-0.2.1-1.x86_64.rpm "$work/t/c5.bad.rpm"
+client dnf C5 "dnf: corrupt rpm (one byte changed)" "install refused" refuse package "$srv/rt-c5" '.'
+
+# A repository whose metadata is signed with the repository key but whose only package is not.
+for pair in c6:pk/v2 c7:other; do
+  id=${pair%%:*} dir=${pair##*:}
+  mkdir -p "$work/$id/x86_64"
+  cp "$work/$dir/hodeishield-0.2.1-1.x86_64.rpm" "$work/$id/x86_64/"
+  tool sh /w/bin/rpmrepo.sh "/w/$id/x86_64"
+  fresh "$id"
+  mcx rm --recursive --force "r/rt-$id/rpm/x86_64" > /dev/null
+  mcx mirror --quiet "/w/$id/x86_64" "r/rt-$id/rpm/x86_64" > /dev/null
+done
+client dnf C6 "dnf: unsigned rpm, gpgcheck=1" "install refused" refuse package "$srv/rt-c6" \
+  '[Ss]ignature|GPG|not signed|Public key'
+client dnf C7 "dnf: rpm signed by another key, gpgcheck=1" "install refused" refuse package "$srv/rt-c7" \
+  '[Ss]ignature|GPG|not signed|Public key'

From 6c5482072fa611572cb84a82f5c2b6b19d89ff2e Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Thu, 8 Oct 2026 04:25:06 +0200
Subject: [PATCH 05/57] Build the test MinIO from source, since it is no longer
 published as an image

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 .github/workflows/repo-builder-tests.yml  |  3 ---
 packaging/repo/repo-test-minio.Dockerfile | 12 ++++++++++++
 packaging/repo/repo-test.sh               | 11 +++++------
 3 files changed, 17 insertions(+), 9 deletions(-)
 create mode 100644 packaging/repo/repo-test-minio.Dockerfile

diff --git a/.github/workflows/repo-builder-tests.yml b/.github/workflows/repo-builder-tests.yml
index 411bab4..31f0e7e 100644
--- a/.github/workflows/repo-builder-tests.yml
+++ b/.github/workflows/repo-builder-tests.yml
@@ -35,9 +35,6 @@ jobs:
     permissions:
       contents: read
     env:
-      # Pinned by digest, bumped by hand in the periodic dependency review (CONTRIBUTING.md).
-      MINIO_IMAGE: minio/minio:RELEASE.2025-09-07T16-13-09Z@sha256:14cea493d9a34af32f524e538b8346cf79f3321eff8e708c1e2960462bd8936e
-      MC_IMAGE: minio/mc:RELEASE.2025-08-13T08-35-41Z@sha256:a7fe349ef4bd8521fb8497f55c6042871b2ae640607cf99d9bede5e9bdf11727
       # The same nfpm as the release workflow's.
       NFPM_VERSION: "2.47.0"
       NFPM_SHA256: 0660ca602b2d2d2ae4781a06c692b3eeb9d437ffea05b831d76e41f4a3188783
diff --git a/packaging/repo/repo-test-minio.Dockerfile b/packaging/repo/repo-test-minio.Dockerfile
new file mode 100644
index 0000000..5521b7d
--- /dev/null
+++ b/packaging/repo/repo-test-minio.Dockerfile
@@ -0,0 +1,12 @@
+# The S3-compatible server and client that repo-test.sh publishes to: MinIO, built from its source at
+# the releases below (the project no longer publishes images or binaries). Go fetches the modules
+# through the checksum database, so what is built is fixed by the two tags and the Go image.
+# Bumped by hand in the periodic dependency review (CONTRIBUTING.md).
+ARG BASE
+FROM golang:1.24-trixie@sha256:5835f052b784aa39f2fe9070def3568605c8bc3fcd810f10402066348b61e716 AS build
+ENV GOBIN=/out CGO_ENABLED=0
+RUN go install github.com/minio/minio@RELEASE.2025-09-07T16-13-09Z \
+  && go install github.com/minio/mc@RELEASE.2025-08-13T08-35-41Z
+
+FROM ${BASE}
+COPY --from=build /out/minio /out/mc /usr/local/bin/
diff --git a/packaging/repo/repo-test.sh b/packaging/repo/repo-test.sh
index 838a566..4a9bff8 100644
--- a/packaging/repo/repo-test.sh
+++ b/packaging/repo/repo-test.sh
@@ -10,13 +10,11 @@
 #
 # Environment:
 #   NFPM          absolute path to the nfpm binary (the version pinned in the workflow)
-#   MINIO_IMAGE   the MinIO server image, pinned by digest
-#   MC_IMAGE      the MinIO client image, pinned by digest
 #
 # Everything is made here and thrown away: the signing keys (a certify-only RSA 4096 primary with a
 # signing subkey, like the real one, and a second key for the forgeries), synthetic hodeishield
 # packages built with nfpm from a one-line program, and a MinIO whose publishing user may list, read
-# and write but not delete. The real build.sh and publish.sh run in the image named in
+# and write but not delete (built from source: repo-test-minio.Dockerfile). The real build.sh and publish.sh run in the image named in
 # packaging/repo/image. The bucket is then served over HTTP to an apt and a dnf client.
 #
 # Every case has an expected outcome, and the run fails if any case ends otherwise:
@@ -31,7 +29,7 @@ set -eu
 
 here=$(cd "$(dirname "$0")" && pwd)
 root=$(cd "$here/../.." && pwd)
-: "${NFPM:?}" "${MINIO_IMAGE:?}" "${MC_IMAGE:?}"
+: "${NFPM:?}"
 for need in docker jq curl gzip sha256sum; do
   command -v "$need" > /dev/null || {
     printf 'repo-test.sh: %s is required\n' "$need" >&2
@@ -334,11 +332,12 @@ endgroup
 
 # --- MinIO ------------------------------------------------------------------------------------------------
 group "MinIO"
+docker build --quiet --tag rt-minio-image --build-arg BASE="$IMAGE" - < "$here/repo-test-minio.Dockerfile" > /dev/null
 docker network create "$net" > /dev/null
 docker run -d --name "$minio" --network "$net" --env MINIO_ROOT_USER="$rootuser" \
-  --env MINIO_ROOT_PASSWORD="$rootpass" "$MINIO_IMAGE" server /data > /dev/null
+  --env MINIO_ROOT_PASSWORD="$rootpass" rt-minio-image minio server /data > /dev/null
 docker run -d --name "$mcbox" --network "$net" --user "$uid:$gid" --env MC_CONFIG_DIR=/tmp/mc \
-  --volume "$work:/w" --entrypoint sh "$MC_IMAGE" -c 'exec sleep 86400' > /dev/null
+  --volume "$work:/w" rt-minio-image sleep 86400 > /dev/null
 mcx() { docker exec "$mcbox" mc "$@"; }
 tries=0
 until mcx alias set r "$srv" "$rootuser" "$rootpass" > /dev/null 2>&1; do

From c5c03366c173be94291fdda68f0bee1e1b1a4cd9 Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Thu, 8 Oct 2026 04:29:51 +0200
Subject: [PATCH 06/57] Match the clients' actual refusal messages in the
 repository tests

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 packaging/repo/repo-test.sh | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/packaging/repo/repo-test.sh b/packaging/repo/repo-test.sh
index 4a9bff8..3344c90 100644
--- a/packaging/repo/repo-test.sh
+++ b/packaging/repo/repo-test.sh
@@ -720,7 +720,7 @@ fi
 
 # --- Clients must refuse -----------------------------------------------------------------------------------
 # Tampered copies of the published repository (rt-v2), served as they are.
-sig='BADSIG|NO_PUBKEY|not signed|[Ss]ignature'
+sig='BADSIG|signature verification failed|is not signed'
 fresh c1
 sed 's/^Codename: stable$/Codename: stablf/' "$work/t/InRelease" > "$work/t/InRelease.c1"
 put rt-c1 "$IR" "$work/t/InRelease.c1"
@@ -740,7 +740,7 @@ cmp -s "$work/t/repomd.xml" "$work/t/repomd.xml.c3" && {
   exit 1
 }
 put rt-c3 rpm/x86_64/repodata/repomd.xml "$work/t/repomd.xml.c3"
-client dnf C3 "dnf: repomd.xml tampered" "metadata and install refused" refuse index "$srv/rt-c3" 'GPG|[Ss]ignature'
+client dnf C3 "dnf: repomd.xml tampered" "metadata and install refused" refuse index "$srv/rt-c3" 'Bad GPG signature'
 
 # flip <file>: the same file with one byte changed.
 flip() {
@@ -753,14 +753,14 @@ get rt-v2 "$H/hodeishield_0.2.1-1_amd64.deb" "$work/t/c4.deb"
 flip "$work/t/c4.deb" "$work/t/c4.bad.deb"
 cmp -s "$work/t/c4.deb" "$work/t/c4.bad.deb" && exit 1
 put rt-c4 "$H/hodeishield_0.2.1-1_amd64.deb" "$work/t/c4.bad.deb"
-client apt C4 "apt: corrupt deb (one byte changed)" "install refused" refuse package "$srv/rt-c4" 'Hash Sum mismatch|unexpected size|[Hh]ash'
+client apt C4 "apt: corrupt deb (one byte changed)" "install refused" refuse package "$srv/rt-c4" 'Hash Sum mismatch|unexpected size'
 
 fresh c5
 get rt-v2 rpm/x86_64/hodeishield-0.2.1-1.x86_64.rpm "$work/t/c5.rpm"
 flip "$work/t/c5.rpm" "$work/t/c5.bad.rpm"
 cmp -s "$work/t/c5.rpm" "$work/t/c5.bad.rpm" && exit 1
 put rt-c5 rpm/x86_64/hodeishield-0.2.1-1.x86_64.rpm "$work/t/c5.bad.rpm"
-client dnf C5 "dnf: corrupt rpm (one byte changed)" "install refused" refuse package "$srv/rt-c5" '.'
+client dnf C5 "dnf: corrupt rpm (one byte changed)" "install refused" refuse package "$srv/rt-c5" "checksum doesn't match|Cannot download"
 
 # A repository whose metadata is signed with the repository key but whose only package is not.
 for pair in c6:pk/v2 c7:other; do
@@ -773,6 +773,6 @@ for pair in c6:pk/v2 c7:other; do
   mcx mirror --quiet "/w/$id/x86_64" "r/rt-$id/rpm/x86_64" > /dev/null
 done
 client dnf C6 "dnf: unsigned rpm, gpgcheck=1" "install refused" refuse package "$srv/rt-c6" \
-  '[Ss]ignature|GPG|not signed|Public key'
+  'is not signed|GPG check FAILED'
 client dnf C7 "dnf: rpm signed by another key, gpgcheck=1" "install refused" refuse package "$srv/rt-c7" \
-  '[Ss]ignature|GPG|not signed|Public key'
+  'Public key for .* is not installed|GPG check FAILED'

From f9bcfbf013310548cb347cc2080bb349507168ea Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Thu, 8 Oct 2026 04:36:44 +0200
Subject: [PATCH 07/57] Note the licence of the test MinIO

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 .github/workflows/repo-builder-tests.yml  | 2 ++
 packaging/repo/repo-test-minio.Dockerfile | 2 ++
 2 files changed, 4 insertions(+)

diff --git a/.github/workflows/repo-builder-tests.yml b/.github/workflows/repo-builder-tests.yml
index 31f0e7e..6ee356f 100644
--- a/.github/workflows/repo-builder-tests.yml
+++ b/.github/workflows/repo-builder-tests.yml
@@ -56,4 +56,6 @@ jobs:
       - name: Run the tests
         run: |
           set -euo pipefail
+          # MinIO is licensed under the GNU AGPL v3; it is built and run here only as a throwaway test
+          # service inside CI and is never shipped or distributed with the CLI or its packages.
           NFPM="$RUNNER_TEMP/nfpm" sh packaging/repo/repo-test.sh
diff --git a/packaging/repo/repo-test-minio.Dockerfile b/packaging/repo/repo-test-minio.Dockerfile
index 5521b7d..b454958 100644
--- a/packaging/repo/repo-test-minio.Dockerfile
+++ b/packaging/repo/repo-test-minio.Dockerfile
@@ -1,6 +1,8 @@
 # The S3-compatible server and client that repo-test.sh publishes to: MinIO, built from its source at
 # the releases below (the project no longer publishes images or binaries). Go fetches the modules
 # through the checksum database, so what is built is fixed by the two tags and the Go image.
+# MinIO is licensed under the GNU AGPL v3; it is built and run here only as a throwaway test
+# service inside CI and is never shipped or distributed with the CLI or its packages.
 # Bumped by hand in the periodic dependency review (CONTRIBUTING.md).
 ARG BASE
 FROM golang:1.24-trixie@sha256:5835f052b784aa39f2fe9070def3568605c8bc3fcd810f10402066348b61e716 AS build

From ad45a95c9ba66a3b146077e681e5fb76b894694f Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Thu, 8 Oct 2026 18:44:30 +0200
Subject: [PATCH 08/57] Document proxies and TLS inspection

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 README.md | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/README.md b/README.md
index 5849858..ed5f900 100644
--- a/README.md
+++ b/README.md
@@ -353,6 +353,48 @@ plain HTTP is accepted only for `localhost`.
 
 Shell completions: `hodeishield completions bash|zsh|fish|powershell|elvish`.
 
+## Networking: proxies and TLS inspection
+
+The CLI reaches `api.hodeishield.com` and `app.hodeishield.com` over HTTPS (port 443). Behind a
+corporate proxy, nothing needs configuring in the CLI itself; it follows the proxy settings of the
+machine.
+
+- **Proxy variables.** `HTTPS_PROXY`, `HTTP_PROXY`, `ALL_PROXY` and `NO_PROXY` are honoured, and so
+  are their lower-case forms. Since all traffic is HTTPS, `HTTPS_PROXY` (or `ALL_PROXY`) is the one
+  that matters; use `NO_PROXY` for hosts that must be reached directly.
+
+  ```sh
+  export HTTPS_PROXY=http://proxy.example.com:3128
+  export NO_PROXY=localhost,127.0.0.1
+  hodeishield vendors list
+  ```
+
+- **Operating system settings.** On macOS and Windows the system proxy settings are read as well,
+  next to the variables. On Linux only the variables are read.
+- **Certificates.** The CLI trusts the operating system's certificate store, not a bundled list. If
+  your organisation inspects TLS and its CA is installed in that store (the usual case on managed
+  Windows and macOS machines, or after `update-ca-certificates` / `update-ca-trust` on Linux), the
+  CLI trusts the proxy's certificates with no further setup. On Linux you can also point
+  `SSL_CERT_FILE` (a PEM file) or `SSL_CERT_DIR` at your CA certificates.
+- **What cannot be configured.** There is no CLI option to add a CA or to skip certificate
+  verification, and `SSL_CERT_FILE` / `SSL_CERT_DIR` have no effect on macOS and Windows: add the CA
+  to the system store there.
+- **Sign-in on this machine.** `hodeishield login` waits for the browser on `127.0.0.1`; that
+  redirect is made by your browser to the CLI, not by the CLI, so the CLI's proxy settings do not
+  apply to it (the CLI also never uses a proxy when its API or app URL is a loopback address). Your
+  browser's own proxy settings apply to the sign-in page. Where the browser cannot reach the
+  machine, use `hodeishield login --device`.
+
+To diagnose, add `--verbose`: each API request is logged to standard error with its URL, status,
+time and request id, followed by each retry and its reason. A failure to connect, including a proxy
+that refuses the connection or a certificate that is not trusted, ends with exit code 7 and a
+message that starts with `Could not reach the API:` (or `Could not reach the app` during sign-in)
+followed by the cause. A certificate error there usually means the proxy's CA is missing from the
+store described above.
+
+This behaviour comes from the CLI's HTTP library; it has not yet been verified behind a
+TLS-inspecting proxy on every platform.
+
 ## Repository layout
 
 - `crates/hodeishield-cli` — the `hodeishield` binary.

From d7c80409dbba49d4ea446307618f87caa05d8b75 Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Thu, 8 Oct 2026 18:45:18 +0200
Subject: [PATCH 09/57] Link the beta programme and its terms from the README

Closes #52

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 README.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/README.md b/README.md
index 5849858..2ff8426 100644
--- a/README.md
+++ b/README.md
@@ -377,6 +377,10 @@ to them (Apache-2.0 §6).
 
 ## About
 
+HodeiShield is in beta. To request access, visit
+[https://hodeishield.com/en/beta](https://hodeishield.com/en/beta) and review the
+[beta terms of service](https://hodeishield.com/en/beta/terms).
+
 - [HodeiShield](https://hodeishield.com): the third-party risk, supply-chain security and
   compliance platform that this CLI reads from; sign in at
   [app.hodeishield.com](https://app.hodeishield.com) and create API keys there.

From 730a888a0793d3191b04140b3f4926125762eda2 Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Thu, 8 Oct 2026 18:48:16 +0200
Subject: [PATCH 10/57] Expose the tenant the API answered for in the response
 metadata

Read the X-HS-Tenant header of 2xx answers into ResponseMeta::tenant_id when it is present
exactly once and holds a UUID. It is informational only and not a tenant-isolation check.

Refs #48

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 crates/hodeishield-api/src/client.rs | 23 ++++++++++++
 crates/hodeishield-api/tests/api.rs  | 56 ++++++++++++++++++++++++++++
 2 files changed, 79 insertions(+)

diff --git a/crates/hodeishield-api/src/client.rs b/crates/hodeishield-api/src/client.rs
index 6b9f8fc..f81339e 100644
--- a/crates/hodeishield-api/src/client.rs
+++ b/crates/hodeishield-api/src/client.rs
@@ -54,6 +54,9 @@ pub struct ResponseMeta {
     pub rate_limit: Option<RateLimit>,
     /// `Retry-After`, in seconds.
     pub retry_after: Option<u64>,
+    /// `X-HS-Tenant` of a 2xx answer: the tenant id, lowercase, when the header is present exactly
+    /// once and holds a UUID. Informational only; this is not a tenant-isolation check.
+    pub tenant_id: Option<String>,
 }
 
 /// The `RateLimit-*` headers of an answer: the limit closest to being exhausted.
@@ -98,10 +101,30 @@ impl ResponseMeta {
             request_id: text("x-request-id"),
             rate_limit,
             retry_after: number("retry-after"),
+            tenant_id: if status.is_success() {
+                tenant_header(headers)
+            } else {
+                None
+            },
         }
     }
 }
 
+/// The single `X-HS-Tenant` value, when it is a canonical UUID (any case), lowercased.
+fn tenant_header(headers: &HeaderMap) -> Option<String> {
+    let mut values = headers.get_all("x-hs-tenant").iter();
+    let value = values.next()?.to_str().ok()?;
+    if values.next().is_some() {
+        return None;
+    }
+    let canonical = value.len() == 36
+        && value.bytes().enumerate().all(|(i, b)| match i {
+            8 | 13 | 18 | 23 => b == b'-',
+            _ => b.is_ascii_hexdigit(),
+        });
+    canonical.then(|| value.to_ascii_lowercase())
+}
+
 /// What the client reports about each request it sends, for `--verbose`. It carries no header and
 /// no credential.
 #[derive(Debug, Clone)]
diff --git a/crates/hodeishield-api/tests/api.rs b/crates/hodeishield-api/tests/api.rs
index 608c751..0bcd2ea 100644
--- a/crates/hodeishield-api/tests/api.rs
+++ b/crates/hodeishield-api/tests/api.rs
@@ -82,6 +82,62 @@ fn list_sends_the_bearer_and_the_query_and_keeps_unknown_fields_in_raw() {
     assert_eq!(page.raw["data"][0]["field_added_later"]["nested"], true);
 }
 
+const TENANT: &str = "3f2b8c1a-0d4e-4f6a-9b7c-5e1d2a3b4c5d";
+
+fn tenant_meta(status: usize, headers: &[&str]) -> hodeishield_api::ResponseMeta {
+    let mut server = mockito::Server::new();
+    let mut mock = server.mock("GET", "/v1/vendors").with_status(status);
+    for value in headers {
+        mock = mock.with_header("x-hs-tenant", value);
+    }
+    let body = if status == 200 {
+        r#"{"data":[],"pagination":{"page":1,"per_page":50,"total":0,"total_pages":0}}"#
+    } else {
+        r#"{"error":{"code":"forbidden","message":"no","request_id":"r"}}"#
+    };
+    let _mock = mock.with_body(body).create();
+    match client(&server).list_vendors(&ListVendorsParams::default()) {
+        Ok(page) => page.meta,
+        Err(e) => e.api().expect("api error").meta.clone(),
+    }
+}
+
+#[test]
+fn the_tenant_header_of_a_2xx_answer_is_kept_lowercase() {
+    assert_eq!(
+        tenant_meta(200, &[TENANT]).tenant_id.as_deref(),
+        Some(TENANT)
+    );
+    let upper = TENANT.to_ascii_uppercase();
+    assert_eq!(
+        tenant_meta(200, &[upper.as_str()]).tenant_id.as_deref(),
+        Some(TENANT)
+    );
+}
+
+#[test]
+fn a_missing_malformed_or_duplicated_tenant_header_gives_none() {
+    assert_eq!(tenant_meta(200, &[]).tenant_id, None);
+    for bad in [
+        "",
+        "not-a-uuid",
+        "3f2b8c1a0d4e4f6a9b7c5e1d2a3b4c5d",
+        "3f2b8c1a-0d4e-4f6a-9b7c-5e1d2a3b4c5",
+        "3f2b8c1a-0d4e-4f6a-9b7c-5e1d2a3b4c5g",
+        "{3f2b8c1a-0d4e-4f6a-9b7c-5e1d2a3b4c5d}",
+    ] {
+        assert_eq!(tenant_meta(200, &[bad]).tenant_id, None, "{bad:?}");
+    }
+    let other = "11111111-2222-4333-8444-555555555555";
+    assert_eq!(tenant_meta(200, &[TENANT, other]).tenant_id, None);
+    assert_eq!(tenant_meta(200, &[TENANT, TENANT]).tenant_id, None);
+}
+
+#[test]
+fn a_tenant_header_on_an_error_answer_is_ignored() {
+    assert_eq!(tenant_meta(403, &[TENANT]).tenant_id, None);
+}
+
 #[test]
 fn path_arguments_are_encoded() {
     let mut server = mockito::Server::new();

From 499e3094484f87ccbe0c676db4eec91896afa88d Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Thu, 8 Oct 2026 18:52:34 +0200
Subject: [PATCH 11/57] State the interface stability policy

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 CONTRIBUTING.md |  3 ++-
 README.md       | 27 ++++++++++++++++++++++++++-
 2 files changed, 28 insertions(+), 2 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6498766..df1eff0 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -106,7 +106,8 @@ implementation plugged into one. **Depth** is the behaviour available per unit o
 - Keep changes focused, with tests for new behaviour.
 - Add a line under `## [Unreleased]` in `CHANGELOG.md` for any change a user or a script would
   notice. A release renames that section to `## [X.Y.Z] - YYYY-MM-DD`; the release workflow refuses
-  a tag without it and uses the section as the release notes.
+  a tag without it and uses the section as the release notes. A change to the scripting surface
+  goes under `### Changed (scripting surface)`; see [Stability](README.md#stability).
 - Commits must be signed (GPG or SSH) and use a clear, imperative message in English. Reference
   the issue it resolves with `Closes #N` in the commit message.
 - Commit messages and pull request descriptions must not mention Claude: no session trailer, no
diff --git a/README.md b/README.md
index cb9f31f..2185607 100644
--- a/README.md
+++ b/README.md
@@ -34,7 +34,8 @@ endpoint agents from a terminal or a script.
 - **Verifiable.** Every release is signed with Sigstore (keyless, from GitHub Actions) and carries
   SLSA build provenance.
 
-> The CLI is at version 0.x: commands and output may still change before 1.0.
+> The CLI is at version 0.x: commands and output may still change before 1.0. See
+> [Stability](#stability) for what may change and how it is announced.
 
 ## Install
 
@@ -327,6 +328,30 @@ Errors go to stderr with a hint and, when the API gave one, a **request id**: qu
 contact support. `--verbose` logs each request's method, URL, status and request id to stderr, never
 a credential.
 
+## Stability
+
+The CLI follows [Semantic Versioning](https://semver.org/). Its **scripting surface** is what a
+script can depend on:
+
+- the command names and flags;
+- the field names and types in `--json` and `--csv` output;
+- the exit codes 0 to 8 and what each one means (see [Exit codes](#exit-codes));
+- what goes to standard output (the data) and to standard error (notes and errors).
+
+While the version is 0.x, a change that breaks the scripting surface only ships in a minor version
+(0.2 to 0.3, never 0.2.0 to 0.2.1), and the changelog lists it under **Changed (scripting
+surface)**, with what to do about it. Read that heading before you upgrade. Patch releases fix bugs
+and do not break the scripting surface. A 1.0 release will be announced in the changelog.
+
+Adding to the scripting surface is not a breaking change: new commands and flags, and new fields in
+`--json` output. Giving an existing case a different exit code is a breaking change, even when the
+code is new (0.2.0 moved an inactive licence from 4 to 8). Write scripts to ignore the fields they do not know: `--json`
+prints the body the API returned, so it can gain fields at any time.
+
+The table output and the messages on standard error are for people and may change in any release.
+Scripts should use `--json` or `--csv` for data, and the exit code for what happened, and should not
+parse tables or messages.
+
 ## Configure
 
 Settings come from, in order: flags, environment variables, the profile in the configuration file,

From ed529529d502f2883dc7a152ee04649cf144385b Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Thu, 8 Oct 2026 18:56:28 +0200
Subject: [PATCH 12/57] Wrap the stability section

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 2185607..e602336 100644
--- a/README.md
+++ b/README.md
@@ -345,8 +345,8 @@ and do not break the scripting surface. A 1.0 release will be announced in the c
 
 Adding to the scripting surface is not a breaking change: new commands and flags, and new fields in
 `--json` output. Giving an existing case a different exit code is a breaking change, even when the
-code is new (0.2.0 moved an inactive licence from 4 to 8). Write scripts to ignore the fields they do not know: `--json`
-prints the body the API returned, so it can gain fields at any time.
+code is new (0.2.0 moved an inactive licence from 4 to 8). Write scripts to ignore the fields they
+do not know: `--json` prints the body the API returned, so it can gain fields at any time.
 
 The table output and the messages on standard error are for people and may change in any release.
 Scripts should use `--json` or `--csv` for data, and the exit code for what happened, and should not

From 431791e1d64b949c791cd2fd85032a37e5b2aad3 Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Thu, 8 Oct 2026 19:00:29 +0200
Subject: [PATCH 13/57] Read known filter values from the OpenAPI document

The document can publish the vocabulary of a query parameter as
x-hs-known-values. The generator reads it (an array of strings, anything
else is an error) and emits it on the operation as known_values, which
Operation::known_values(param) looks up. The vocabularies are open, so the
values are for help and warnings, not for refusing input.

The vendored document does not carry the extension yet: the only change to
the generated file is the empty known_values field on each operation.

Refs #53

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 crates/hodeishield-api/src/client.rs    |  34 ++++++++
 crates/hodeishield-api/src/generated.rs |  11 +++
 xtask/src/main.rs                       | 107 +++++++++++++++++++++++-
 3 files changed, 150 insertions(+), 2 deletions(-)

diff --git a/crates/hodeishield-api/src/client.rs b/crates/hodeishield-api/src/client.rs
index 6b9f8fc..089fc32 100644
--- a/crates/hodeishield-api/src/client.rs
+++ b/crates/hodeishield-api/src/client.rs
@@ -29,6 +29,23 @@ pub struct Operation {
     /// Scopes the credential needs. A template such as `compliance.<framework>:read` stands for the
     /// scope of the framework being read.
     pub scopes: &'static [&'static str],
+    /// The vocabulary the document publishes for a query parameter (`x-hs-known-values`), as
+    /// `(parameter, values)` pairs, only for the parameters that have one. The vocabularies are
+    /// open: the server may accept a value that is not listed, so use this to help and to warn,
+    /// never to refuse. Read it through [`Operation::known_values`].
+    pub known_values: &'static [(&'static str, &'static [&'static str])],
+}
+
+impl Operation {
+    /// The values the document lists for the query parameter `param`, in document order, or `None`
+    /// when it publishes no vocabulary for it.
+    #[must_use]
+    pub fn known_values(&self, param: &str) -> Option<&'static [&'static str]> {
+        self.known_values
+            .iter()
+            .find(|(name, _)| *name == param)
+            .map(|(_, values)| *values)
+    }
 }
 
 /// A successful answer: the typed body, the body exactly as received (for `--json`, so fields this
@@ -588,6 +605,23 @@ pub fn encode_path_segment(segment: &str) -> Result<String, Error> {
 mod tests {
     use super::*;
 
+    #[test]
+    fn known_values_are_looked_up_by_parameter() {
+        let operation = Operation {
+            id: "listThings",
+            method: "GET",
+            path: "/v1/things",
+            summary: "List things",
+            scopes: &[],
+            known_values: &[("severity", &["critical", "high"])],
+        };
+        assert_eq!(
+            operation.known_values("severity"),
+            Some(&["critical", "high"][..])
+        );
+        assert_eq!(operation.known_values("page"), None);
+    }
+
     fn client(base: &str) -> Client {
         Client::new(base.parse().expect("url"), SecretString::from("hsk_test")).expect("client")
     }
diff --git a/crates/hodeishield-api/src/generated.rs b/crates/hodeishield-api/src/generated.rs
index 495df14..9b7ccdd 100644
--- a/crates/hodeishield-api/src/generated.rs
+++ b/crates/hodeishield-api/src/generated.rs
@@ -1102,6 +1102,7 @@ pub mod operations {
         path: "/v1/vendors",
         summary: "List third parties",
         scopes: &["supply_risk:read"],
+        known_values: &[],
     };
 
     /// `GET /v1/vendors/{id}`: Fetch one third party.
@@ -1111,6 +1112,7 @@ pub mod operations {
         path: "/v1/vendors/{id}",
         summary: "Fetch one third party",
         scopes: &["supply_risk:read"],
+        known_values: &[],
     };
 
     /// `GET /v1/alerts`: List supply-chain alerts.
@@ -1120,6 +1122,7 @@ pub mod operations {
         path: "/v1/alerts",
         summary: "List supply-chain alerts",
         scopes: &["supply_risk:read"],
+        known_values: &[],
     };
 
     /// `GET /v1/alerts/{id}`: Fetch one alert.
@@ -1129,6 +1132,7 @@ pub mod operations {
         path: "/v1/alerts/{id}",
         summary: "Fetch one alert",
         scopes: &["supply_risk:read"],
+        known_values: &[],
     };
 
     /// `GET /v1/risks`: List risk-register entries.
@@ -1138,6 +1142,7 @@ pub mod operations {
         path: "/v1/risks",
         summary: "List risk-register entries",
         scopes: &["supply_risk:read"],
+        known_values: &[],
     };
 
     /// `GET /v1/risks/{id}`: Fetch one risk-register entry.
@@ -1147,6 +1152,7 @@ pub mod operations {
         path: "/v1/risks/{id}",
         summary: "Fetch one risk-register entry",
         scopes: &["supply_risk:read"],
+        known_values: &[],
     };
 
     /// `GET /v1/compliance/controls`: List control status for a framework.
@@ -1156,6 +1162,7 @@ pub mod operations {
         path: "/v1/compliance/controls",
         summary: "List control status for a framework",
         scopes: &["compliance.<framework>:read"],
+        known_values: &[],
     };
 
     /// `GET /v1/compliance/frameworks/{framework}`: Framework posture summary.
@@ -1165,6 +1172,7 @@ pub mod operations {
         path: "/v1/compliance/frameworks/{framework}",
         summary: "Framework posture summary",
         scopes: &["compliance.<framework>:read"],
+        known_values: &[],
     };
 
     /// `GET /v1/evidence`: List security evidence.
@@ -1174,6 +1182,7 @@ pub mod operations {
         path: "/v1/evidence",
         summary: "List security evidence",
         scopes: &["evidence:read"],
+        known_values: &[],
     };
 
     /// `GET /v1/evidence/{id}`: Fetch one evidence item.
@@ -1183,6 +1192,7 @@ pub mod operations {
         path: "/v1/evidence/{id}",
         summary: "Fetch one evidence item",
         scopes: &["evidence:read"],
+        known_values: &[],
     };
 
     /// `GET /v1/endpoints`: List enrolled endpoint agents.
@@ -1192,6 +1202,7 @@ pub mod operations {
         path: "/v1/endpoints",
         summary: "List enrolled endpoint agents",
         scopes: &["endpoints:read"],
+        known_values: &[],
     };
 
     /// All operations, in document order.
diff --git a/xtask/src/main.rs b/xtask/src/main.rs
index 39fcbcd..33acc18 100644
--- a/xtask/src/main.rs
+++ b/xtask/src/main.rs
@@ -174,6 +174,8 @@ struct Param {
     ty: String,
     required: bool,
     is_enum: bool,
+    /// The values `x-hs-known-values` lists, in document order; empty without the extension.
+    known_values: Vec<String>,
     doc: Option<String>,
 }
 
@@ -411,6 +413,7 @@ impl<'a> Generator<'a> {
                 ty,
                 required,
                 is_enum,
+                known_values: known_values(&id, name, param)?,
                 doc: param
                     .get("description")
                     .and_then(Value::as_str)
@@ -743,16 +746,27 @@ impl<'a> Generator<'a> {
         out.push_str("/// Every `/v1` operation, as the OpenAPI document describes it.\npub mod operations {\n    use crate::Operation;\n\n");
         for op in &self.operations {
             let scopes: Vec<String> = op.scopes.iter().map(|s| format!("{s:?}")).collect();
+            let known: Vec<String> = op
+                .query_params
+                .iter()
+                .filter(|p| !p.known_values.is_empty())
+                .map(|p| {
+                    let values: Vec<String> =
+                        p.known_values.iter().map(|v| format!("{v:?}")).collect();
+                    format!("({:?}, &[{}])", p.json_name, values.join(", "))
+                })
+                .collect();
             let _ = writeln!(
                 out,
-                "    /// `GET {}`: {}.\n    pub const {}: Operation = Operation {{ id: {:?}, method: \"GET\", path: {:?}, summary: {:?}, scopes: &[{}] }};\n",
+                "    /// `GET {}`: {}.\n    pub const {}: Operation = Operation {{ id: {:?}, method: \"GET\", path: {:?}, summary: {:?}, scopes: &[{}], known_values: &[{}] }};\n",
                 op.path,
                 op.summary,
                 screaming(&op.id),
                 op.id,
                 op.path,
                 op.summary,
-                scopes.join(", ")
+                scopes.join(", "),
+                known.join(", ")
             );
         }
         let all: Vec<String> = self.operations.iter().map(|op| screaming(&op.id)).collect();
@@ -818,6 +832,22 @@ fn render_doc(out: &mut String, doc: Option<&str>, indent: &str) {
     }
 }
 
+/// The vocabulary `x-hs-known-values` publishes for a query parameter, in document order. The
+/// extension is optional; when present it must be an array of strings, anything else is an error.
+fn known_values(operation: &str, name: &str, param: &Value) -> Result<Vec<String>> {
+    let Some(list) = param.get("x-hs-known-values") else {
+        return Ok(Vec::new());
+    };
+    list.as_array()
+        .and_then(|items| {
+            items
+                .iter()
+                .map(|v| v.as_str().map(str::to_owned))
+                .collect::<Option<Vec<_>>>()
+        })
+        .ok_or_else(|| format!("{operation}.{name}: x-hs-known-values must be an array of strings"))
+}
+
 fn operation_id(operation: &Value) -> Result<&str> {
     operation
         .get("operationId")
@@ -958,4 +988,77 @@ mod tests {
         assert_eq!(resource_name("getFrameworkPosture"), "FrameworkPosture");
         assert_eq!(resource_name("listComplianceControls"), "ComplianceControl");
     }
+
+    /// A minimal document with one operation whose `severity` query parameter carries `extension`
+    /// (when given) and whose `page` parameter never does.
+    fn document(extension: Option<Value>) -> Value {
+        let mut severity = serde_json::json!({
+            "name": "severity", "in": "query", "schema": {"type": "string"}
+        });
+        if let Some(extension) = extension {
+            severity["x-hs-known-values"] = extension;
+        }
+        serde_json::json!({
+            "info": {"version": "test"},
+            "servers": [{"url": "https://api.example.test"}],
+            "components": {"schemas": {}},
+            "paths": {"/v1/things": {"get": {
+                "operationId": "listThings",
+                "summary": "List things",
+                "x-hs-scope": {"scopes": ["things:read"]},
+                "parameters": [severity, {"name": "page", "in": "query", "schema": {"type": "string"}}],
+                "responses": {"200": {"content": {"application/json": {"schema": {
+                    "type": "object",
+                    "properties": {"ok": {"type": "boolean"}},
+                    "required": ["ok"]
+                }}}}}
+            }}}
+        })
+    }
+
+    fn generate(extension: Option<Value>) -> Result<String> {
+        let spec = document(extension);
+        Generator::new(&spec)
+            .run()
+            .map(|out| out.split_whitespace().collect::<Vec<_>>().join(" "))
+    }
+
+    #[test]
+    fn known_values_are_emitted_in_document_order() {
+        let out =
+            generate(Some(serde_json::json!(["critical", "high", "info"]))).expect("generates");
+        assert!(
+            out.contains(r#"known_values: &[("severity", &["critical", "high", "info"])]"#),
+            "{out}"
+        );
+    }
+
+    #[test]
+    fn a_parameter_without_the_extension_has_no_known_values() {
+        let out = generate(None).expect("generates");
+        assert!(out.contains("known_values: &[]"), "{out}");
+        assert!(!out.contains("known_values: &[("), "{out}");
+    }
+
+    #[test]
+    fn an_empty_vocabulary_is_the_same_as_none() {
+        let out = generate(Some(serde_json::json!([]))).expect("generates");
+        assert!(out.contains("known_values: &[]"), "{out}");
+    }
+
+    #[test]
+    fn a_malformed_extension_is_a_generator_error() {
+        for bad in [
+            serde_json::json!("critical"),
+            serde_json::json!({"critical": true}),
+            serde_json::json!(["critical", 3]),
+            serde_json::json!(null),
+        ] {
+            let err = generate(Some(bad.clone())).expect_err("malformed");
+            assert_eq!(
+                err, "listThings.severity: x-hs-known-values must be an array of strings",
+                "{bad}"
+            );
+        }
+    }
 }

From ae6423194b315e9d3a253cfc322e16c756b7139c Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Thu, 8 Oct 2026 19:07:02 +0200
Subject: [PATCH 14/57] Test the scripting surface: exit codes, JSON, CSV and
 output streams

Add output contract tests that run the binary against a mock API and
pin exit codes 0 to 8, the --json shape (including fields the CLI does
not know), the --csv header, quoting and formula guard, and the split
between standard output and standard error. Document in CONTRIBUTING
that changing them is a change to the scripting surface.

Refs #58

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 CONTRIBUTING.md                          |  10 +
 crates/hodeishield-cli/tests/contract.rs | 641 +++++++++++++++++++++++
 2 files changed, 651 insertions(+)
 create mode 100644 crates/hodeishield-cli/tests/contract.rs

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index df1eff0..fa59db3 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -42,6 +42,16 @@ cargo deny check && cargo audit   # dependency policy and advisories
 CI runs the tests on Linux, macOS and Windows and the other checks on Linux; a pull request needs
 them all green.
 
+### The scripting surface is tested
+
+`crates/hodeishield-cli/tests/contract.rs` pins what [Stability](README.md#stability) promises
+scripts: the exit codes 0 to 8, the shape of `--json` output (including fields the CLI does not
+know), the `--csv` header and quoting rules, and which stream carries data and which carries notes
+and errors. The expectations are written out in full so a change shows in review. If one of these
+tests fails, either the change is a mistake or it breaks the scripting surface: in the second case
+edit the expectation on purpose and add a line under `### Changed (scripting surface)` in
+`CHANGELOG.md`.
+
 ### Dependency updates
 
 Dependabot (`.github/dependabot.yml`) proposes cargo and GitHub Actions updates once a week, against
diff --git a/crates/hodeishield-cli/tests/contract.rs b/crates/hodeishield-cli/tests/contract.rs
new file mode 100644
index 0000000..65ebd8b
--- /dev/null
+++ b/crates/hodeishield-cli/tests/contract.rs
@@ -0,0 +1,641 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Hodeitek S.L.
+
+//! The scripting surface, pinned.
+//!
+//! The README ("Stability") promises scripts four things: the exit codes 0 to 8, the shape of
+//! `--json` and `--csv` output, and which stream carries what. The tests here fail when any of
+//! them changes, so a breaking change is always a deliberate edit of an expectation below, together
+//! with a "Changed (scripting surface)" entry in the changelog.
+//!
+//! Everything runs the real binary against a mock `/v1`, offline, with a throw-away configuration
+//! file and without access to the keychain.
+
+use assert_cmd::Command;
+use serde_json::{Value, json};
+use std::path::PathBuf;
+use std::process::Output;
+
+const KEY: &str = "hsk_test_0123456789abcdef";
+
+struct Env {
+    _dir: tempfile::TempDir,
+    config: PathBuf,
+}
+
+impl Env {
+    fn new() -> Self {
+        let dir = tempfile::tempdir().expect("tempdir");
+        let config = dir.path().join("config.toml");
+        Self { _dir: dir, config }
+    }
+
+    fn cmd(&self) -> Command {
+        let mut cmd = Command::cargo_bin("hodeishield").expect("binary");
+        for var in [
+            "HODEISHIELD_API_KEY",
+            "HODEISHIELD_API_URL",
+            "HODEISHIELD_APP_URL",
+            "HODEISHIELD_PROFILE",
+            "HODEISHIELD_OAUTH_CLIENT_ID",
+        ] {
+            cmd.env_remove(var);
+        }
+        cmd.env("HODEISHIELD_CONFIG", &self.config)
+            .env(
+                "DBUS_SESSION_BUS_ADDRESS",
+                "unix:path=/nonexistent/hodeishield-test",
+            )
+            .env("NO_COLOR", "1");
+        cmd
+    }
+
+    fn api(&self, url: &str, args: &[&str]) -> Output {
+        self.cmd()
+            .env("HODEISHIELD_API_KEY", KEY)
+            .env("HODEISHIELD_API_URL", url)
+            .args(args)
+            .output()
+            .expect("run")
+    }
+}
+
+fn out(output: &Output) -> String {
+    String::from_utf8_lossy(&output.stdout).into_owned()
+}
+
+fn err(output: &Output) -> String {
+    String::from_utf8_lossy(&output.stderr).into_owned()
+}
+
+// ---------------------------------------------------------------------------------------------
+// Exit codes
+// ---------------------------------------------------------------------------------------------
+
+/// Every exit code the README documents, with a command that ends in it.
+#[test]
+fn exit_code_contract() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    let url = server.url();
+    server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .with_body(r#"{"data":[],"pagination":{"page":1,"per_page":50,"total":0,"total_pages":1}}"#)
+        .create();
+    for (path, status, headers, body) in [
+        (
+            "/v1/alerts",
+            403,
+            vec![],
+            r#"{"error":{"code":"forbidden","message":"no","request_id":"r"}}"#,
+        ),
+        (
+            "/v1/risks",
+            404,
+            vec![],
+            r#"{"error":{"code":"not_found","message":"gone","request_id":"r"}}"#,
+        ),
+        (
+            "/v1/evidence",
+            429,
+            // Longer than the CLI is willing to wait, so it gives up at once.
+            vec![("retry-after", "3600")],
+            r#"{"error":{"code":"rate_limited","message":"slow down","request_id":"r"}}"#,
+        ),
+        (
+            "/v1/endpoints",
+            403,
+            vec![],
+            r#"{"error":{"code":"forbidden","message":"no","request_id":"r","details":{"code":"LICENCE_INACTIVE","licence":"none"}}}"#,
+        ),
+        (
+            "/v1/compliance/controls",
+            401,
+            vec![],
+            r#"{"error":{"code":"unauthorized","message":"bad","request_id":"r"}}"#,
+        ),
+    ] {
+        let mut mock = server
+            .mock("GET", path)
+            .match_query(mockito::Matcher::Any)
+            .with_status(status);
+        for (name, value) in headers {
+            mock = mock.with_header(name, value);
+        }
+        mock.with_body(body).create();
+    }
+
+    // Nothing listens on port 9 of the loopback interface.
+    let unreachable = "http://127.0.0.1:9";
+
+    struct Case {
+        code: i32,
+        meaning: &'static str,
+        run: Output,
+    }
+    let cases = [
+        Case {
+            code: 0,
+            meaning: "success",
+            run: env.api(&url, &["vendors", "list"]),
+        },
+        Case {
+            code: 1,
+            meaning: "error: invalid input",
+            run: env.api(&url, &["risks", "get", ".."]),
+        },
+        Case {
+            code: 2,
+            meaning: "invalid command line",
+            run: env.api(&url, &["vendors", "list", "--no-such-flag"]),
+        },
+        Case {
+            code: 3,
+            meaning: "not authenticated: the API rejected the key",
+            run: env.api(&url, &["compliance", "controls", "--framework", "nis2"]),
+        },
+        Case {
+            code: 4,
+            meaning: "missing scope",
+            run: env.api(&url, &["alerts", "list"]),
+        },
+        Case {
+            code: 5,
+            meaning: "not found",
+            run: env.api(&url, &["risks", "list"]),
+        },
+        Case {
+            code: 6,
+            meaning: "rate limited",
+            run: env.api(&url, &["evidence", "list"]),
+        },
+        Case {
+            code: 7,
+            meaning: "API unreachable",
+            run: env.api(unreachable, &["vendors", "list"]),
+        },
+        Case {
+            code: 8,
+            meaning: "licence not in force",
+            run: env.api(&url, &["endpoints", "list"]),
+        },
+    ];
+    for case in cases {
+        assert_eq!(
+            case.run.status.code(),
+            Some(case.code),
+            "exit code {} ({}): {:?}",
+            case.code,
+            case.meaning,
+            case.run
+        );
+        if case.code != 0 {
+            assert!(
+                case.run.stdout.is_empty(),
+                "exit code {} must leave stdout empty: {:?}",
+                case.code,
+                out(&case.run)
+            );
+        }
+    }
+}
+
+/// 3 also means "no credential at all", which needs no network.
+#[test]
+fn no_credential_exits_3() {
+    let env = Env::new();
+    let output = env
+        .cmd()
+        .args(["--api-url", "http://127.0.0.1:9", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(3), "{output:?}");
+    assert!(output.stdout.is_empty());
+}
+
+/// A server error (5xx) is exit code 7 as well, and says nothing on stdout.
+#[test]
+fn a_failing_api_exits_7() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/vendors")
+        .with_status(500)
+        .with_header("retry-after", "0")
+        .with_body(r#"{"error":{"code":"internal","message":"boom","request_id":"r"}}"#)
+        .expect_at_least(1)
+        .create();
+    let output = env.api(&server.url(), &["vendors", "list"]);
+    assert_eq!(output.status.code(), Some(7), "{output:?}");
+    assert!(output.stdout.is_empty());
+}
+
+// ---------------------------------------------------------------------------------------------
+// Fixtures: one item per resource, with every field the API describes and one it does not.
+// ---------------------------------------------------------------------------------------------
+
+struct Resource {
+    /// The command words before `list`.
+    command: &'static [&'static str],
+    /// Extra arguments the list needs.
+    list_args: &'static [&'static str],
+    path: &'static str,
+    /// An item as the API sends it, plus the unknown field `added_later`.
+    item: &'static str,
+    /// The CSV header: the item's fields, in the order the API sends them.
+    csv_header: &'static str,
+}
+
+const RESOURCES: [Resource; 5] = [
+    Resource {
+        command: &["vendors"],
+        list_args: &[],
+        path: "/v1/vendors",
+        item: r#"{"id":"v1","name":"Example Hosting","legal_name":null,"domain":"example.com","category":null,"vendor_type":null,"access_level":null,"business_criticality":"high","data_sensitivity":null,"economic_impact":null,"active":true,"monitoring_status":null,"last_scan_at":"2026-03-04T05:06:07.000Z","lei":null,"hq_country":null,"created_at":"2026-01-01T00:00:00Z","updated_at":"2026-01-01T00:00:00Z","added_later":{"k":[1,2]}}"#,
+        csv_header: "id,name,legal_name,domain,category,vendor_type,access_level,business_criticality,data_sensitivity,economic_impact,active,monitoring_status,last_scan_at,lei,hq_country,created_at,updated_at,added_later",
+    },
+    Resource {
+        command: &["alerts"],
+        list_args: &[],
+        path: "/v1/alerts",
+        item: r#"{"id":"a1","vendor_id":"v1","type":"cve","severity":"high","title":"Example alert","description":null,"source_url":null,"economic_impact":null,"status":"open","acknowledged_at":null,"resolved_at":null,"resolution_reason":null,"created_at":"2026-01-01T00:00:00Z","added_later":"x"}"#,
+        csv_header: "id,vendor_id,type,severity,title,description,source_url,economic_impact,status,acknowledged_at,resolved_at,resolution_reason,created_at,added_later",
+    },
+    Resource {
+        command: &["risks"],
+        list_args: &[],
+        path: "/v1/risks",
+        item: r#"{"id":"r1","title":"Example risk","description":null,"domain":"operations","status":"identified","treatment":null,"treatment_notes":null,"threat_source":null,"vulnerability":null,"likelihood_inherent":3,"impact_inherent":4,"inherent_score":12,"likelihood_residual":null,"impact_residual":null,"residual_score":null,"source":"manual","owner_user_id":null,"vendor_id":null,"control_codes":["1.1","1.2"],"review_date":null,"created_at":"2026-01-01T00:00:00Z","updated_at":"2026-01-01T00:00:00Z","added_later":true}"#,
+        csv_header: "id,title,description,domain,status,treatment,treatment_notes,threat_source,vulnerability,likelihood_inherent,impact_inherent,inherent_score,likelihood_residual,impact_residual,residual_score,source,owner_user_id,vendor_id,control_codes,review_date,created_at,updated_at,added_later",
+    },
+    Resource {
+        command: &["evidence"],
+        list_args: &[],
+        path: "/v1/evidence",
+        item: r#"{"id":"e1","evidence_type":"policy","source_type":"manual","source_id":"s1","title":"Example evidence","description":null,"vendor_id":null,"asset_id":null,"auto_generated":false,"valid_until":null,"created_at":"2026-01-01T00:00:00Z","added_later":7}"#,
+        csv_header: "id,evidence_type,source_type,source_id,title,description,vendor_id,asset_id,auto_generated,valid_until,created_at,added_later",
+    },
+    Resource {
+        command: &["endpoints"],
+        list_args: &[],
+        path: "/v1/endpoints",
+        item: r#"{"id":"n1","producer":"agent","producer_kind":"edr","status":"active","signature_alg":"ed25519","agent_version":"1.2.3","hostname":"host.example.test","enrolled_at":"2026-01-01T00:00:00Z","last_seen_at":null,"revoked_at":null,"added_later":null}"#,
+        csv_header: "id,producer,producer_kind,status,signature_alg,agent_version,hostname,enrolled_at,last_seen_at,revoked_at,added_later",
+    },
+];
+
+const CONTROLS: Resource = Resource {
+    command: &["compliance"],
+    list_args: &["--framework", "nis2"],
+    path: "/v1/compliance/controls",
+    item: r#"{"framework":"nis2","control_code":"1.1","status":"covered","evidence_count":5,"last_evaluated_at":null,"added_later":[]}"#,
+    csv_header: "framework,control_code,status,evidence_count,last_evaluated_at,added_later",
+};
+
+fn list_body(resource: &Resource) -> String {
+    format!(
+        r#"{{"data":[{}],"pagination":{{"page":1,"per_page":50,"total":1,"total_pages":1,"added_later":"p"}},"added_later_top":1}}"#,
+        resource.item
+    )
+}
+
+fn list_args(resource: &Resource, extra: &[&'static str]) -> Vec<&'static str> {
+    let mut args: Vec<&'static str> = Vec::new();
+    args.extend_from_slice(resource.command);
+    args.push(if resource.command == ["compliance"] {
+        "controls"
+    } else {
+        "list"
+    });
+    args.extend_from_slice(resource.list_args);
+    args.extend_from_slice(extra);
+    args
+}
+
+fn all_resources() -> impl Iterator<Item = &'static Resource> {
+    RESOURCES.iter().chain(std::iter::once(&CONTROLS))
+}
+
+// ---------------------------------------------------------------------------------------------
+// --json
+// ---------------------------------------------------------------------------------------------
+
+/// A list prints the API's body as it came: `data` and `pagination` at the top, in that order, and
+/// every field the CLI does not know passes through, at every level.
+#[test]
+fn json_list_is_the_api_body_with_unknown_fields_passed_through() {
+    let env = Env::new();
+    for resource in all_resources() {
+        let mut server = mockito::Server::new();
+        server
+            .mock("GET", resource.path)
+            .match_query(mockito::Matcher::Any)
+            .with_body(list_body(resource))
+            .create();
+        let output = env.api(&server.url(), &list_args(resource, &["--json"]));
+        assert_eq!(
+            output.status.code(),
+            Some(0),
+            "{}: {output:?}",
+            resource.path
+        );
+        let text = out(&output);
+        let printed: Value = serde_json::from_str(&text).expect("json");
+        let sent: Value = serde_json::from_str(&list_body(resource)).expect("fixture");
+        assert_eq!(
+            printed, sent,
+            "{}: the body is passed through",
+            resource.path
+        );
+        let top: Vec<&String> = printed.as_object().expect("object").keys().collect();
+        assert_eq!(
+            top,
+            ["data", "pagination", "added_later_top"],
+            "{}: top-level keys and their order",
+            resource.path
+        );
+        assert!(text.starts_with("{\n  \"data\": [\n    {\n"), "{text}");
+        assert!(text.ends_with("}\n"), "one trailing newline: {text:?}");
+        assert!(
+            err(&output).is_empty(),
+            "{}: {}",
+            resource.path,
+            err(&output)
+        );
+    }
+}
+
+/// `--all --json` prints one array of every item (not a page), unchanged.
+#[test]
+fn json_all_is_an_array_of_the_items() {
+    let env = Env::new();
+    for resource in all_resources() {
+        let mut server = mockito::Server::new();
+        server
+            .mock("GET", resource.path)
+            .match_query(mockito::Matcher::Any)
+            .with_body(list_body(resource))
+            .create();
+        let output = env.api(&server.url(), &list_args(resource, &["--json", "--all"]));
+        assert_eq!(
+            output.status.code(),
+            Some(0),
+            "{}: {output:?}",
+            resource.path
+        );
+        let printed: Value = serde_json::from_str(&out(&output)).expect("json");
+        let sent: Value = serde_json::from_str(resource.item).expect("fixture");
+        assert_eq!(printed, Value::Array(vec![sent]), "{}", resource.path);
+    }
+}
+
+/// `get` prints the API's body, `{"data": {...}}`, with unknown fields.
+#[test]
+fn json_get_is_the_api_body_with_unknown_fields_passed_through() {
+    let env = Env::new();
+    for resource in &RESOURCES[..4] {
+        let name = resource.command[0];
+        let id = "x1";
+        let path = format!("{}/{id}", resource.path);
+        let body = format!(r#"{{"data":{},"added_later_top":1}}"#, resource.item);
+        let mut server = mockito::Server::new();
+        server.mock("GET", path.as_str()).with_body(&body).create();
+        let output = env.api(&server.url(), &["--json", name, "get", id]);
+        assert_eq!(output.status.code(), Some(0), "{name}: {output:?}");
+        let printed: Value = serde_json::from_str(&out(&output)).expect("json");
+        assert_eq!(
+            printed,
+            serde_json::from_str::<Value>(&body).expect("fixture"),
+            "{name}"
+        );
+        let top: Vec<&String> = printed.as_object().expect("object").keys().collect();
+        assert_eq!(top, ["data", "added_later_top"], "{name}");
+    }
+}
+
+/// `compliance posture` prints the API's body, `{"data": {...}}`.
+#[test]
+fn json_posture_is_the_api_body_with_unknown_fields_passed_through() {
+    let env = Env::new();
+    let body = r#"{"data":{"framework":"nis2","controls_total":3,"by_status":{"covered":2,"missing":1},"evidence_total":9,"last_evaluated_at":null,"added_later":1}}"#;
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/compliance/frameworks/nis2")
+        .with_body(body)
+        .create();
+    let output = env.api(&server.url(), &["--json", "compliance", "posture", "nis2"]);
+    assert_eq!(output.status.code(), Some(0), "{output:?}");
+    let printed: Value = serde_json::from_str(&out(&output)).expect("json");
+    assert_eq!(
+        printed,
+        serde_json::from_str::<Value>(body).expect("fixture")
+    );
+}
+
+/// `whoami --json` is an object with these fields, in this order (an API key has no more).
+#[test]
+fn json_whoami_fields() {
+    let env = Env::new();
+    let server = mockito::Server::new();
+    let output = env.api(&server.url(), &["--json", "whoami"]);
+    assert_eq!(output.status.code(), Some(0), "{output:?}");
+    let printed: Value = serde_json::from_str(&out(&output)).expect("json");
+    let keys: Vec<&String> = printed.as_object().expect("object").keys().collect();
+    assert_eq!(keys, ["profile", "api_url", "app_url", "credential"]);
+    assert_eq!(printed["credential"], json!("api_key"));
+    assert_eq!(printed["api_url"], json!(format!("{}/", server.url())));
+}
+
+// ---------------------------------------------------------------------------------------------
+// --csv
+// ---------------------------------------------------------------------------------------------
+
+/// The header is the item's top-level fields in the order the API sends them, including a field
+/// the CLI does not know; the record follows, and both end in CRLF.
+#[test]
+fn csv_header_of_every_list_command() {
+    let env = Env::new();
+    for resource in all_resources() {
+        let mut server = mockito::Server::new();
+        server
+            .mock("GET", resource.path)
+            .match_query(mockito::Matcher::Any)
+            .with_body(list_body(resource))
+            .create();
+        let output = env.api(&server.url(), &list_args(resource, &["--csv"]));
+        assert_eq!(
+            output.status.code(),
+            Some(0),
+            "{}: {output:?}",
+            resource.path
+        );
+        let text = out(&output);
+        let (header, rest) = text.split_once("\r\n").expect("a CRLF-terminated header");
+        assert_eq!(header, resource.csv_header, "{}", resource.path);
+        assert!(rest.ends_with("\r\n"), "{}: {rest:?}", resource.path);
+        assert_eq!(rest.matches("\r\n").count(), 1, "one record: {rest:?}");
+        assert!(
+            !text.contains("\n\n") && !text.starts_with('\u{feff}'),
+            "{text:?}"
+        );
+        // Every line break is CRLF: removing those leaves no bare LF.
+        assert!(!text.replace("\r\n", "").contains('\n'), "{text:?}");
+    }
+}
+
+/// A full CSV document, character for character: the header, a record with every kind of value,
+/// the quoting of RFC 4180 and the guard that keeps a spreadsheet from running a cell as a formula.
+#[test]
+fn csv_document_snapshot() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/alerts")
+        .match_query(mockito::Matcher::Any)
+        .with_body(
+            r#"{"data":[
+{"id":"a1","vendor_id":"v","type":"cve","severity":"+high","title":"=1+1","description":"-x","source_url":"@SUM(A1)","economic_impact":-5,"status":"open","acknowledged_at":null,"resolved_at":null,"resolution_reason":null,"created_at":"2026-01-01T00:00:00Z"},
+{"id":"a2","vendor_id":"v","type":"cve","severity":"say \"hi\"","title":"plain, with comma","description":"two\nlines","source_url":" padded ","economic_impact":2.5,"status":"a=b","acknowledged_at":null,"resolved_at":null,"resolution_reason":null,"created_at":"2026-01-01T00:00:00Z"}
+],"pagination":{"page":1,"per_page":50,"total":2,"total_pages":1}}"#,
+        )
+        .create();
+    let output = env.api(&server.url(), &["alerts", "list", "--csv"]);
+    assert_eq!(output.status.code(), Some(0), "{output:?}");
+    assert_eq!(
+        out(&output),
+        "id,vendor_id,type,severity,title,description,source_url,economic_impact,status,\
+         acknowledged_at,resolved_at,resolution_reason,created_at\r\n\
+         a1,v,cve,'+high,'=1+1,'-x,'@SUM(A1),-5,open,,,,2026-01-01T00:00:00Z\r\n\
+         a2,v,cve,\"say \"\"hi\"\"\",\"plain, with comma\",\"two\nlines\",\" padded \",2.5,a=b,,,,2026-01-01T00:00:00Z\r\n"
+    );
+}
+
+/// No items: nothing on stdout (not even a header), a note on stderr.
+#[test]
+fn csv_without_items_prints_nothing() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/risks")
+        .match_query(mockito::Matcher::Any)
+        .with_body(r#"{"data":[],"pagination":{"page":1,"per_page":50,"total":0,"total_pages":1}}"#)
+        .create();
+    let output = env.api(&server.url(), &["risks", "list", "--csv"]);
+    assert_eq!(output.status.code(), Some(0), "{output:?}");
+    assert!(output.stdout.is_empty(), "{:?}", out(&output));
+    assert_eq!(err(&output), "No risks found.\n");
+}
+
+// ---------------------------------------------------------------------------------------------
+// Standard output and standard error
+// ---------------------------------------------------------------------------------------------
+
+/// Notes about paging go to stderr in every output format; stdout holds only the data.
+#[test]
+fn notes_go_to_stderr_and_data_to_stdout() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    let body = format!(
+        r#"{{"data":[{}],"pagination":{{"page":1,"per_page":1,"total":2,"total_pages":2}}}}"#,
+        RESOURCES[1].item
+    );
+    server
+        .mock("GET", "/v1/alerts")
+        .match_query(mockito::Matcher::Any)
+        .with_body(&body)
+        .create();
+
+    let table = env.api(&server.url(), &["alerts", "list"]);
+    assert_eq!(table.status.code(), Some(0), "{table:?}");
+    assert!(out(&table).starts_with("ID"), "{}", out(&table));
+    assert!(!out(&table).contains("Page 1 of 2"));
+    assert_eq!(
+        err(&table),
+        "Page 1 of 2 (2 alerts). Next: --page 2, or --all.\n"
+    );
+
+    for flag in ["--json", "--csv"] {
+        let output = env.api(&server.url(), &["alerts", "list", flag]);
+        assert_eq!(output.status.code(), Some(0), "{flag}: {output:?}");
+        assert!(!out(&output).contains("Page 1 of 2"), "{flag}");
+        if flag == "--json" {
+            serde_json::from_str::<Value>(&out(&output)).expect("stdout is only JSON");
+            assert!(
+                err(&output).is_empty(),
+                "no note beside JSON: {}",
+                err(&output)
+            );
+        } else {
+            assert_eq!(
+                err(&output),
+                "Page 1 of 2 (2 alerts). Next: --page 2, or --all.\n"
+            );
+        }
+    }
+}
+
+/// `--verbose` logs the requests to stderr and leaves stdout parseable.
+#[test]
+fn verbose_logging_never_reaches_stdout() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/vendors/v1")
+        .with_body(format!(r#"{{"data":{}}}"#, RESOURCES[0].item))
+        .create();
+    let output = env.api(
+        &server.url(),
+        &["--verbose", "--json", "vendors", "get", "v1"],
+    );
+    assert_eq!(output.status.code(), Some(0), "{output:?}");
+    serde_json::from_str::<Value>(&out(&output)).expect("stdout is only JSON");
+    assert!(
+        err(&output).contains("GET http://127.0.0.1:"),
+        "{}",
+        err(&output)
+    );
+}
+
+/// An error writes nothing to stdout in any output format, and starts its stderr with `error: `.
+#[test]
+fn errors_write_to_stderr_only() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .with_status(404)
+        .with_body(
+            r#"{"error":{"code":"not_found","message":"Nothing here.","request_id":"req_1"}}"#,
+        )
+        .create();
+    for flag in ["--json", "--csv", ""] {
+        let mut args = vec!["vendors", "list"];
+        if !flag.is_empty() {
+            args.push(flag);
+        }
+        let output = env.api(&server.url(), &args);
+        assert_eq!(output.status.code(), Some(5), "{flag}: {output:?}");
+        assert!(output.stdout.is_empty(), "{flag}: {:?}", out(&output));
+        assert_eq!(
+            err(&output),
+            "error: Nothing here.\nrequest id: req_1\n",
+            "{flag}"
+        );
+    }
+}
+
+/// A usage error also leaves stdout empty.
+#[test]
+fn usage_errors_write_to_stderr_only() {
+    let env = Env::new();
+    let output = env
+        .cmd()
+        .args(["vendors", "frobnicate"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(2), "{output:?}");
+    assert!(output.stdout.is_empty(), "{:?}", out(&output));
+    assert!(!err(&output).is_empty());
+}

From 9ceaec2976c0c78cb450383a3961a1a89fbfec3a Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Thu, 8 Oct 2026 19:09:28 +0200
Subject: [PATCH 15/57] Warn when a filter value is not one the API lists

Refs #53

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 crates/hodeishield-cli/src/cli.rs             |  13 +-
 .../hodeishield-cli/src/commands/resources.rs |  18 ++-
 crates/hodeishield-cli/src/filters.rs         | 132 ++++++++++++++++++
 crates/hodeishield-cli/src/lib.rs             |   1 +
 crates/hodeishield-cli/tests/cli.rs           |  60 ++++++++
 5 files changed, 219 insertions(+), 5 deletions(-)
 create mode 100644 crates/hodeishield-cli/src/filters.rs

diff --git a/crates/hodeishield-cli/src/cli.rs b/crates/hodeishield-cli/src/cli.rs
index 3adf6e7..576b03c 100644
--- a/crates/hodeishield-cli/src/cli.rs
+++ b/crates/hodeishield-cli/src/cli.rs
@@ -3,9 +3,11 @@
 
 //! Command-line surface.
 
+use crate::filters;
 use clap::builder::{PossibleValuesParser, TypedValueParser};
 use clap::{Args, CommandFactory, Parser, Subcommand};
 use hodeishield_api::ParseEnumError;
+use hodeishield_api::v1::operations;
 use hodeishield_api::v1::{
     AlertSort, AlertStatus, BusinessCriticality, ComplianceControlSort, EndpointSort,
     EndpointStatus, EvidenceSort, Order, RiskSort, VendorSort,
@@ -228,7 +230,7 @@ pub struct AlertsList {
     #[arg(long, value_parser = choice::<AlertStatus>(AlertStatus::VALUES))]
     pub status: Option<AlertStatus>,
     /// Exact severity.
-    #[arg(long)]
+    #[arg(long, help = filters::help("Exact severity.", &operations::LIST_ALERTS, "severity"))]
     pub severity: Option<String>,
     /// Only alerts about this vendor id.
     #[arg(long)]
@@ -257,10 +259,10 @@ pub enum RisksCommand {
 #[derive(Debug, Args)]
 pub struct RisksList {
     /// Exact status.
-    #[arg(long)]
+    #[arg(long, help = filters::help("Exact status.", &operations::LIST_RISKS, "status"))]
     pub status: Option<String>,
     /// Exact risk domain.
-    #[arg(long)]
+    #[arg(long, help = filters::help("Exact risk domain.", &operations::LIST_RISKS, "domain"))]
     pub domain: Option<String>,
     /// Only risks linked to this vendor id.
     #[arg(long)]
@@ -292,7 +294,10 @@ pub struct ControlsList {
     #[arg(long, short)]
     pub framework: String,
     /// Exact control status.
-    #[arg(long)]
+    #[arg(
+        long,
+        help = filters::help("Exact control status.", &operations::LIST_COMPLIANCE_CONTROLS, "status")
+    )]
     pub status: Option<String>,
     /// Field to order by.
     #[arg(long, value_parser = choice::<ComplianceControlSort>(ComplianceControlSort::VALUES))]
diff --git a/crates/hodeishield-cli/src/commands/resources.rs b/crates/hodeishield-cli/src/commands/resources.rs
index 14b96d6..0ecfe99 100644
--- a/crates/hodeishield-cli/src/commands/resources.rs
+++ b/crates/hodeishield-cli/src/commands/resources.rs
@@ -9,6 +9,7 @@ use crate::cli::{
     VendorsCommand,
 };
 use crate::failure::{ApiContext, CredentialSource, Result, from_api};
+use crate::filters::warn_unknown;
 use crate::output::{
     cell, clean, print_csv, print_detail, print_json, print_table, short_time, table,
 };
@@ -16,7 +17,7 @@ use comfy_table::Table;
 use hodeishield_api::v1::{
     Alert, ComplianceControl, Endpoint, Evidence, ListAlertsParams, ListComplianceControlsParams,
     ListEndpointsParams, ListEvidenceParams, ListRisksParams, ListVendorsParams, Pagination, Risk,
-    Vendor,
+    Vendor, operations,
 };
 use hodeishield_api::{ApiResponse, Error};
 use serde::Serialize;
@@ -225,6 +226,10 @@ pub fn alerts(ctx: &Context, command: AlertsCommand, out: &mut dyn Write) -> Res
     let (client, source) = ctx.api(&settings)?;
     match command {
         AlertsCommand::List(args) => {
+            warn_unknown(
+                &operations::LIST_ALERTS,
+                &[("severity", args.severity.as_deref())],
+            );
             let base = ListAlertsParams {
                 status: args.status,
                 severity: args.severity,
@@ -281,6 +286,13 @@ pub fn risks(ctx: &Context, command: RisksCommand, out: &mut dyn Write) -> Resul
     let (client, source) = ctx.api(&settings)?;
     match command {
         RisksCommand::List(args) => {
+            warn_unknown(
+                &operations::LIST_RISKS,
+                &[
+                    ("status", args.status.as_deref()),
+                    ("domain", args.domain.as_deref()),
+                ],
+            );
             let base = ListRisksParams {
                 status: args.status,
                 domain: args.domain,
@@ -338,6 +350,10 @@ pub fn compliance(ctx: &Context, command: ComplianceCommand, out: &mut dyn Write
     let (client, source) = ctx.api(&settings)?;
     match command {
         ComplianceCommand::Controls(args) => {
+            warn_unknown(
+                &operations::LIST_COMPLIANCE_CONTROLS,
+                &[("status", args.status.as_deref())],
+            );
             let api = ApiContext {
                 source,
                 framework: Some(&args.framework),
diff --git a/crates/hodeishield-cli/src/filters.rs b/crates/hodeishield-cli/src/filters.rs
new file mode 100644
index 0000000..a2361f6
--- /dev/null
+++ b/crates/hodeishield-cli/src/filters.rs
@@ -0,0 +1,132 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Hodeitek S.L.
+
+//! The values the API document lists for a filter (`x-hs-known-values`): shown in `--help` and
+//! checked before a request. The lists are open vocabularies, so a value that is not listed is
+//! warned about and sent exactly as typed; nothing here refuses a value or rewrites it.
+
+use crate::output::clean;
+use hodeishield_api::Operation;
+
+/// The help text of a filter flag: `base`, plus the values the document lists for `param`, when it
+/// lists any. Without a list the help is `base` unchanged.
+pub fn help(base: &str, operation: &Operation, param: &str) -> String {
+    match operation.known_values(param) {
+        Some(values) if !values.is_empty() => {
+            format!("{base} Known values: {}.", values.join(", "))
+        }
+        _ => base.to_owned(),
+    }
+}
+
+/// The warnings for the `(parameter, value)` pairs the user gave, one per value that is not in the
+/// list the document publishes for that parameter. A parameter without a list never warns. The
+/// match is exact and case-sensitive, as the API is; a value that differs only by case also gets
+/// the listed spelling as a hint.
+pub fn warnings(operation: &Operation, filters: &[(&str, Option<&str>)]) -> Vec<String> {
+    filters
+        .iter()
+        .filter_map(|&(param, value)| {
+            let value = value?;
+            let known = operation.known_values(param).filter(|v| !v.is_empty())?;
+            if known.contains(&value) {
+                return None;
+            }
+            let tail = known
+                .iter()
+                .find(|k| k.eq_ignore_ascii_case(value))
+                .map_or_else(
+                    || "sending it anyway.".to_owned(),
+                    |k| format!("did you mean `{k}`? Sending it anyway."),
+                );
+            Some(format!(
+                "warning: `{}` is not one of the values the API lists for --{} ({}); {tail}",
+                clean(value),
+                param.replace('_', "-"),
+                known.join(", "),
+            ))
+        })
+        .collect()
+}
+
+/// Prints [`warnings`] to stderr.
+pub fn warn_unknown(operation: &Operation, filters: &[(&str, Option<&str>)]) {
+    for warning in warnings(operation, filters) {
+        eprintln!("{warning}");
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const WITH_LISTS: Operation = Operation {
+        id: "listAlerts",
+        method: "GET",
+        path: "/v1/alerts",
+        summary: "List alerts",
+        scopes: &[],
+        known_values: &[("severity", &["critical", "high", "medium", "low"])],
+    };
+
+    const WITHOUT_LISTS: Operation = Operation {
+        known_values: &[],
+        ..WITH_LISTS
+    };
+
+    #[test]
+    fn an_unlisted_value_warns_and_names_the_options() {
+        assert_eq!(
+            warnings(&WITH_LISTS, &[("severity", Some("urgent"))]),
+            [
+                "warning: `urgent` is not one of the values the API lists for --severity \
+              (critical, high, medium, low); sending it anyway."
+            ]
+        );
+    }
+
+    #[test]
+    fn a_listed_value_or_no_value_is_silent() {
+        assert!(warnings(&WITH_LISTS, &[("severity", Some("high"))]).is_empty());
+        assert!(warnings(&WITH_LISTS, &[("severity", None)]).is_empty());
+    }
+
+    #[test]
+    fn a_difference_only_in_case_suggests_the_listed_spelling() {
+        assert_eq!(
+            warnings(&WITH_LISTS, &[("severity", Some("High"))]),
+            [
+                "warning: `High` is not one of the values the API lists for --severity \
+              (critical, high, medium, low); did you mean `high`? Sending it anyway."
+            ]
+        );
+    }
+
+    #[test]
+    fn a_parameter_without_a_list_never_warns() {
+        assert!(warnings(&WITH_LISTS, &[("category", Some("anything"))]).is_empty());
+        assert!(warnings(&WITHOUT_LISTS, &[("severity", Some("urgent"))]).is_empty());
+    }
+
+    #[test]
+    fn control_characters_in_the_value_are_not_echoed() {
+        let out = warnings(&WITH_LISTS, &[("severity", Some("a\u{1b}[31mb"))]);
+        assert!(!out[0].contains('\u{1b}'), "{out:?}");
+    }
+
+    #[test]
+    fn help_lists_the_values_only_when_the_document_does() {
+        assert_eq!(
+            help("Exact severity.", &WITH_LISTS, "severity"),
+            "Exact severity. Known values: critical, high, medium, low."
+        );
+        assert_eq!(
+            help("Exact severity.", &WITHOUT_LISTS, "severity"),
+            "Exact severity."
+        );
+        assert_eq!(
+            help("Exact category.", &WITH_LISTS, "category"),
+            "Exact category."
+        );
+    }
+}
diff --git a/crates/hodeishield-cli/src/lib.rs b/crates/hodeishield-cli/src/lib.rs
index 9d21bc9..3c7eaa4 100644
--- a/crates/hodeishield-cli/src/lib.rs
+++ b/crates/hodeishield-cli/src/lib.rs
@@ -12,6 +12,7 @@ pub mod cli;
 mod commands;
 mod config;
 mod failure;
+mod filters;
 mod output;
 
 use std::io::{ErrorKind, Write};
diff --git a/crates/hodeishield-cli/tests/cli.rs b/crates/hodeishield-cli/tests/cli.rs
index cf26883..067b172 100644
--- a/crates/hodeishield-cli/tests/cli.rs
+++ b/crates/hodeishield-cli/tests/cli.rs
@@ -709,3 +709,63 @@ fn compliance_controls_csv() {
     assert!(stdout.contains("failing"), "{stdout}");
     assert_no_key(&output);
 }
+
+/// The vendored document lists no values for these filters yet, so they are sent exactly as typed,
+/// without a warning, and the command succeeds. (The warning itself is covered by the unit tests
+/// of `filters`, with operations that carry lists.)
+#[test]
+fn free_form_filters_are_sent_as_typed_without_a_warning() {
+    for (args, path, param, value) in [
+        (
+            &["alerts", "list", "--severity", "High"][..],
+            "/v1/alerts",
+            "severity",
+            "High",
+        ),
+        (
+            &["vendors", "list", "--category", "Cloud Host"],
+            "/v1/vendors",
+            "category",
+            "Cloud Host",
+        ),
+        (
+            &["risks", "list", "--domain", "Cyber"],
+            "/v1/risks",
+            "domain",
+            "Cyber",
+        ),
+        (
+            &["risks", "list", "--status", "OPEN"],
+            "/v1/risks",
+            "status",
+            "OPEN",
+        ),
+        (
+            &[
+                "compliance",
+                "controls",
+                "--framework",
+                "nis2",
+                "--status",
+                "Covered",
+            ],
+            "/v1/compliance/controls",
+            "status",
+            "Covered",
+        ),
+    ] {
+        let env = Env::new();
+        let mut server = mockito::Server::new();
+        let mock = server
+            .mock("GET", path)
+            .match_query(mockito::Matcher::UrlEncoded(param.into(), value.into()))
+            .with_body(page(&[], 1, 0, 1))
+            .expect(1)
+            .create();
+        let output = env.api(&server).args(args).output().expect("run");
+        assert!(output.status.success(), "{args:?}: {output:?}");
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        assert!(!stderr.contains("warning:"), "{args:?}: {stderr}");
+        mock.assert();
+    }
+}

From edb28ef4823d1baac536adc95742a44ddbf89607 Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Thu, 8 Oct 2026 19:15:29 +0200
Subject: [PATCH 16/57] Test proxy and TLS inspection handling in CI

Refs #25

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 .github/scripts/proxy-tls-fake-api.py |  71 +++++++++
 .github/scripts/proxy-tls-test.sh     | 215 ++++++++++++++++++++++++++
 .github/workflows/proxy-tls.yml       |  74 +++++++++
 3 files changed, 360 insertions(+)
 create mode 100644 .github/scripts/proxy-tls-fake-api.py
 create mode 100755 .github/scripts/proxy-tls-test.sh
 create mode 100644 .github/workflows/proxy-tls.yml

diff --git a/.github/scripts/proxy-tls-fake-api.py b/.github/scripts/proxy-tls-fake-api.py
new file mode 100644
index 0000000..cd1af0d
--- /dev/null
+++ b/.github/scripts/proxy-tls-fake-api.py
@@ -0,0 +1,71 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Hodeitek S.L.
+"""A tiny HTTPS stand-in for the API, used only by proxy-tls-test.sh.
+
+Usage: proxy-tls-fake-api.py CERT KEY PORT LOGFILE
+
+It answers GET /v1/vendors with one vendor and logs one line per request to LOGFILE, so the test
+can tell which requests reached it. It binds to 127.0.0.1 only.
+"""
+
+import json
+import ssl
+import sys
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import urlsplit
+
+VENDOR = {
+    "id": "v1",
+    "name": "Example Hosting",
+    "legal_name": None,
+    "domain": "example.com",
+    "category": None,
+    "vendor_type": None,
+    "access_level": None,
+    "business_criticality": "high",
+    "data_sensitivity": None,
+    "economic_impact": None,
+    "active": True,
+    "monitoring_status": None,
+    "last_scan_at": "2026-03-04T05:06:07.000Z",
+    "lei": None,
+    "hq_country": None,
+    "created_at": "2026-01-01T00:00:00Z",
+    "updated_at": "2026-01-01T00:00:00Z",
+}
+PAGE = {
+    "data": [VENDOR],
+    "pagination": {"page": 1, "per_page": 50, "total": 1, "total_pages": 1},
+}
+
+
+def main() -> None:
+    cert, key, port, logfile = sys.argv[1], sys.argv[2], int(sys.argv[3]), sys.argv[4]
+    log = open(logfile, "a", buffering=1, encoding="utf-8")
+
+    class Handler(BaseHTTPRequestHandler):
+        def do_GET(self) -> None:  # noqa: N802
+            path = urlsplit(self.path).path
+            log.write(f"GET {path}\n")
+            if path == "/v1/vendors":
+                body = json.dumps(PAGE).encode()
+                self.send_response(200)
+                self.send_header("Content-Type", "application/json")
+            else:
+                body = b"{}"
+                self.send_response(404)
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+
+        def log_message(self, *_args) -> None:
+            pass
+
+    context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+    context.load_cert_chain(cert, key)
+    server = ThreadingHTTPServer(("127.0.0.1", port), Handler)
+    server.socket = context.wrap_socket(server.socket, server_side=True)
+    server.serve_forever()
+
+
+main()
diff --git a/.github/scripts/proxy-tls-test.sh b/.github/scripts/proxy-tls-test.sh
new file mode 100755
index 0000000..6b3c5a7
--- /dev/null
+++ b/.github/scripts/proxy-tls-test.sh
@@ -0,0 +1,215 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Hodeitek S.L.
+#
+# Proves the README's "Networking: proxies and TLS inspection" claims on Linux, end to end, with a
+# real TLS-inspecting proxy (mitmproxy) and a fake API, all on this machine:
+#
+#   1. HTTPS_PROXY set, proxy CA not trusted       -> exit 7, "Could not reach the API:", certificate
+#   2. proxy CA in the system store                -> works, and the proxy saw the request
+#   3. proxy CA only in SSL_CERT_FILE              -> works
+#   4. NO_PROXY covers the host                    -> the proxy is not used
+#   5. lower-case https_proxy                      -> works like HTTPS_PROXY
+#   6. --verbose                                   -> the request line goes to stderr only
+#
+# The API is reached as api.test:8443, mapped to 127.0.0.1 in /etc/hosts, because the CLI never uses
+# a proxy for a loopback URL. The fake API's certificate comes from one throwaway CA that only the
+# proxy trusts; the proxy re-signs with another throwaway CA, the one the CLI must trust.
+#
+# This is meant to run in CI (GitHub Actions): it edits /etc/hosts and the system certificate store,
+# and case 1 is a deliberate failure. It refuses to run elsewhere.
+#
+# Usage: proxy-tls-test.sh PATH_TO_HODEISHIELD PATH_TO_MITMPROXY_DIR
+set -euo pipefail
+
+if [ "${GITHUB_ACTIONS:-}" != "true" ]; then
+  echo "proxy-tls-test.sh edits /etc/hosts and the system certificate store: it only runs in GitHub Actions." >&2
+  exit 2
+fi
+BIN=$(realpath "${1:?usage: proxy-tls-test.sh HODEISHIELD MITMPROXY_DIR}")
+MITM=$(realpath "${2:?usage: proxy-tls-test.sh HODEISHIELD MITMPROXY_DIR}")
+SCRIPTS=$(cd "$(dirname "$0")" && pwd)
+
+HOST=api.test
+API_PORT=8443
+PROXY_PORT=8080
+API_URL="https://$HOST:$API_PORT"
+REQ_RE="GET https://$HOST:$API_PORT/v1/vendors"
+
+WORK=$(mktemp -d)
+PIDS=()
+# shellcheck disable=SC2329  # invoked by the EXIT trap
+cleanup() {
+  for pid in "${PIDS[@]}"; do kill "$pid" 2> /dev/null || true; done
+  rm -rf "$WORK"
+}
+trap cleanup EXIT
+
+# --- Throwaway certificates -------------------------------------------------------------------
+make_ca() {
+  openssl req -x509 -newkey rsa:2048 -nodes -days 2 -subj "/CN=Test $1 CA" \
+    -addext "basicConstraints=critical,CA:TRUE" -addext "keyUsage=critical,keyCertSign,cRLSign" \
+    -keyout "$WORK/$1-ca.key" -out "$WORK/$1-ca.crt" 2> /dev/null
+}
+make_ca upstream # signs the fake API's certificate; trusted by the proxy only
+make_ca proxy    # the "corporate" CA the proxy re-signs with; what the CLI must trust
+
+openssl req -newkey rsa:2048 -nodes -subj "/CN=$HOST" \
+  -keyout "$WORK/api.key" -out "$WORK/api.csr" 2> /dev/null
+openssl x509 -req -in "$WORK/api.csr" -CA "$WORK/upstream-ca.crt" -CAkey "$WORK/upstream-ca.key" \
+  -CAcreateserial -days 2 -out "$WORK/api.crt" \
+  -extfile <(printf 'subjectAltName=DNS:%s\nbasicConstraints=CA:FALSE\n' "$HOST") 2> /dev/null
+
+mkdir "$WORK/confdir"
+cat "$WORK/proxy-ca.key" "$WORK/proxy-ca.crt" > "$WORK/confdir/mitmproxy-ca.pem"
+cp "$WORK/proxy-ca.crt" "$WORK/confdir/mitmproxy-ca-cert.pem"
+
+# --- Name, fake API, proxy --------------------------------------------------------------------
+echo "127.0.0.1 $HOST" | sudo tee -a /etc/hosts > /dev/null
+
+: > "$WORK/api.log"
+python3 -I "$SCRIPTS/proxy-tls-fake-api.py" "$WORK/api.crt" "$WORK/api.key" "$API_PORT" "$WORK/api.log" &
+PIDS+=($!)
+
+PYTHONUNBUFFERED=1 "$MITM/mitmdump" --set "confdir=$WORK/confdir" \
+  --set "ssl_verify_upstream_trusted_ca=$WORK/upstream-ca.crt" \
+  --listen-host 127.0.0.1 --listen-port "$PROXY_PORT" --flow-detail 1 > "$WORK/proxy.log" 2>&1 &
+PIDS+=($!)
+
+wait_port() {
+  for _ in $(seq 1 50); do
+    if (echo > "/dev/tcp/127.0.0.1/$1") 2> /dev/null; then return 0; fi
+    sleep 0.2
+  done
+  echo "nothing is listening on port $1" >&2
+  cat "$WORK/proxy.log" >&2 || true
+  exit 1
+}
+wait_port "$API_PORT"
+wait_port "$PROXY_PORT"
+
+# --- Helpers ----------------------------------------------------------------------------------
+RESULTS=()
+FAILED=0
+record() { # case, description, ok|FAIL, detail
+  RESULTS+=("$1|$2|$3|$4")
+  if [ "$3" != ok ]; then FAILED=1; fi
+}
+
+# Runs the CLI with a clean proxy/certificate environment plus the given NAME=value pairs.
+# Usage: cli [NAME=value ...] -- args...   Leaves rc, $WORK/out and $WORK/err.
+cli() {
+  local extra=()
+  while [ "$1" != -- ]; do extra+=("$1"); shift; done
+  shift
+  rc=0
+  env -u HTTPS_PROXY -u https_proxy -u HTTP_PROXY -u http_proxy -u ALL_PROXY -u all_proxy \
+    -u NO_PROXY -u no_proxy -u SSL_CERT_FILE -u SSL_CERT_DIR \
+    HODEISHIELD_CONFIG="$WORK/config.toml" HODEISHIELD_API_KEY=hsk_test_0123456789abcdef \
+    HODEISHIELD_API_URL="$API_URL" DBUS_SESSION_BUS_ADDRESS=unix:path=/nonexistent/hodeishield-test \
+    NO_COLOR=1 "${extra[@]}" "$BIN" "$@" > "$WORK/out" 2> "$WORK/err" || rc=$?
+}
+
+count() { grep -c -- "$2" "$1" || true; }
+proxy_seen() { count "$WORK/proxy.log" "$REQ_RE"; }
+api_seen() { count "$WORK/api.log" "GET /v1/vendors"; }
+
+# Waits (up to 5 s) for the proxy log to show more requests than $1.
+wait_proxy_above() {
+  for _ in $(seq 1 25); do
+    if [ "$(proxy_seen)" -gt "$1" ]; then return 0; fi
+    sleep 0.2
+  done
+  return 1
+}
+
+show_failure() {
+  echo "--- case $1: exit $rc"
+  echo "--- stdout"; head -c 2000 "$WORK/out"
+  echo "--- stderr"; head -c 2000 "$WORK/err"
+}
+
+# A successful run: exit 0 and the vendor on stdout as JSON.
+works() { [ "$rc" -eq 0 ] && jq -e '.data[0].id == "v1"' "$WORK/out" > /dev/null 2>&1; }
+
+PROXY=http://127.0.0.1:$PROXY_PORT
+
+# --- Case 1: the proxy's CA is not trusted ----------------------------------------------------
+p0=$(proxy_seen) a0=$(api_seen)
+cli HTTPS_PROXY="$PROXY" -- vendors list --json
+sleep 1
+if [ "$rc" -eq 7 ] && [[ "$(cat "$WORK/err")" == "Could not reach the API:"* ]] \
+  && grep -qiE 'certificate|UnknownIssuer' "$WORK/err" \
+  && [ "$(proxy_seen)" -eq "$p0" ] && [ "$(api_seen)" -eq "$a0" ]; then
+  record 1 "HTTPS_PROXY, proxy CA not trusted: exit 7, certificate error, nothing delivered" ok "exit $rc"
+else
+  record 1 "HTTPS_PROXY, proxy CA not trusted: exit 7, certificate error, nothing delivered" FAIL "exit $rc"
+  show_failure 1
+fi
+
+# --- Case 3: the proxy's CA only in SSL_CERT_FILE (run before it enters the system store) -----
+p0=$(proxy_seen)
+cli HTTPS_PROXY="$PROXY" SSL_CERT_FILE="$WORK/proxy-ca.crt" -- vendors list --json
+if works && wait_proxy_above "$p0"; then
+  record 3 "proxy CA only in SSL_CERT_FILE: works through the proxy" ok "exit $rc"
+else
+  record 3 "proxy CA only in SSL_CERT_FILE: works through the proxy" FAIL "exit $rc"
+  show_failure 3
+fi
+
+# --- Case 4: NO_PROXY covers the host: direct, the proxy never sees it ------------------------
+p0=$(proxy_seen) a0=$(api_seen)
+cli HTTPS_PROXY="$PROXY" NO_PROXY="$HOST" SSL_CERT_FILE="$WORK/upstream-ca.crt" -- vendors list --json
+sleep 1
+if works && [ "$(api_seen)" -gt "$a0" ] && [ "$(proxy_seen)" -eq "$p0" ]; then
+  record 4 "NO_PROXY covers the host: direct to the API, proxy bypassed" ok "exit $rc"
+else
+  record 4 "NO_PROXY covers the host: direct to the API, proxy bypassed" FAIL "exit $rc"
+  show_failure 4
+fi
+
+# --- Case 2: the proxy's CA in the system store ------------------------------------------------
+sudo cp "$WORK/proxy-ca.crt" /usr/local/share/ca-certificates/hodeishield-test-proxy-ca.crt
+sudo update-ca-certificates > /dev/null
+p0=$(proxy_seen)
+cli HTTPS_PROXY="$PROXY" -- vendors list --json
+if works && wait_proxy_above "$p0"; then
+  record 2 "proxy CA in the system store: works, the proxy saw the request" ok "exit $rc"
+else
+  record 2 "proxy CA in the system store: works, the proxy saw the request" FAIL "exit $rc"
+  show_failure 2
+fi
+
+# --- Case 5: lower-case https_proxy ------------------------------------------------------------
+p0=$(proxy_seen)
+cli https_proxy="$PROXY" -- vendors list --json
+if works && wait_proxy_above "$p0"; then
+  record 5 "lower-case https_proxy works like upper-case" ok "exit $rc"
+else
+  record 5 "lower-case https_proxy works like upper-case" FAIL "exit $rc"
+  show_failure 5
+fi
+
+# --- Case 6: --verbose writes the request line to stderr only ----------------------------------
+cli HTTPS_PROXY="$PROXY" -- --verbose vendors list --json
+if works && grep -qE "^GET https://api\.test:8443/v1/vendors.* → 200 " "$WORK/err" \
+  && ! grep -q "GET " "$WORK/out"; then
+  record 6 "--verbose: request line on stderr, stdout stays clean JSON" ok "exit $rc"
+else
+  record 6 "--verbose: request line on stderr, stdout stays clean JSON" FAIL "exit $rc"
+  show_failure 6
+fi
+
+# --- Report ------------------------------------------------------------------------------------
+echo
+printf '%-5s %-78s %s\n' CASE DESCRIPTION RESULT
+for row in "${RESULTS[@]}"; do
+  IFS='|' read -r n desc result _detail <<< "$row"
+  printf '%-5s %-78s %s\n' "$n" "$desc" "$result"
+done
+if [ "$FAILED" -ne 0 ]; then
+  echo
+  echo "--- proxy log"; tail -n 40 "$WORK/proxy.log"
+  echo "--- fake API log"; tail -n 20 "$WORK/api.log"
+fi
+exit "$FAILED"
diff --git a/.github/workflows/proxy-tls.yml b/.github/workflows/proxy-tls.yml
new file mode 100644
index 0000000..3963251
--- /dev/null
+++ b/.github/workflows/proxy-tls.yml
@@ -0,0 +1,74 @@
+name: Proxy and TLS inspection
+
+# Checks the README's "Networking: proxies and TLS inspection" claims on Linux against a real
+# TLS-inspecting proxy (mitmproxy) and a fake API, both on the runner, with throwaway certificates:
+# nothing secret is used and nothing leaves the machine except the download of mitmproxy. Case 1
+# is a deliberate certificate failure, so the script is only meant to run here (see
+# .github/scripts/proxy-tls-test.sh).
+on:
+  pull_request:
+    paths:
+      - "Cargo.lock"
+      - "crates/hodeishield-api/**"
+      - "crates/hodeishield-cli/**"
+      - ".github/scripts/proxy-tls-*"
+      - ".github/workflows/proxy-tls.yml"
+  push:
+    branches: [dev, main]
+    paths:
+      - "Cargo.lock"
+      - "crates/hodeishield-api/**"
+      - "crates/hodeishield-cli/**"
+      - ".github/scripts/proxy-tls-*"
+      - ".github/workflows/proxy-tls.yml"
+  workflow_dispatch:
+
+permissions: {}
+
+concurrency:
+  group: proxy-tls-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  proxy-tls:
+    name: proxy-tls
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    env:
+      # Official Linux release of mitmproxy, pinned by version and checksum. Bumped by hand.
+      MITMPROXY_VERSION: "12.2.3"
+      MITMPROXY_SHA256: 2e95286b618fa6fd33e5e62a78c2e5112571d85f42ec2bac29b97ee242bdb5c5
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install pinned toolchain
+        run: rustup show
+
+      - name: Cache cargo artifacts
+        uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
+        with:
+          key: proxy-tls
+
+      - name: Build the CLI
+        run: cargo build --locked -p hodeishield-cli
+
+      - name: Install mitmproxy
+        run: |
+          set -euo pipefail
+          archive="mitmproxy-${MITMPROXY_VERSION}-linux-x86_64.tar.gz"
+          curl --proto '=https' --tlsv1.2 -fsSL -o "$RUNNER_TEMP/$archive" \
+            "https://downloads.mitmproxy.org/${MITMPROXY_VERSION}/${archive}"
+          echo "${MITMPROXY_SHA256}  $RUNNER_TEMP/$archive" | sha256sum -c -
+          mkdir "$RUNNER_TEMP/mitmproxy"
+          tar -xzf "$RUNNER_TEMP/$archive" -C "$RUNNER_TEMP/mitmproxy"
+
+      - name: Run the proxy cases
+        run: bash .github/scripts/proxy-tls-test.sh target/debug/hodeishield "$RUNNER_TEMP/mitmproxy"

From 20cb6b4d7bad9e8ae76f7544d22acc356abe6662 Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Thu, 8 Oct 2026 19:17:20 +0200
Subject: [PATCH 17/57] Point legacy severity values to their new names

When the API document lists the English alert severities and the user types one of the legacy values, say which name to use and until when the legacy one is accepted. The value is still sent as typed. Refs #53

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 crates/hodeishield-cli/src/filters.rs | 122 ++++++++++++++++++++++++++
 1 file changed, 122 insertions(+)

diff --git a/crates/hodeishield-cli/src/filters.rs b/crates/hodeishield-cli/src/filters.rs
index a2361f6..0f7805f 100644
--- a/crates/hodeishield-cli/src/filters.rs
+++ b/crates/hodeishield-cli/src/filters.rs
@@ -19,6 +19,47 @@ pub fn help(base: &str, operation: &Operation, param: &str) -> String {
     }
 }
 
+/// The legacy values of the alert `severity` filter and their current names.
+///
+/// The API is moving alert severity from a legacy Spanish scale to an English vocabulary, and
+/// for a transition period its filter accepts both. A legacy value typed by the user is still
+/// sent exactly as typed (the server accepts it); this table only lets the CLI say what to use
+/// instead. It applies to the alert severity filter alone and can be removed, with
+/// [`legacy_hint`], after [`LEGACY_SEVERITY_END`].
+const LEGACY_SEVERITY: &[(&str, &str)] = &[
+    ("critico", "critical"),
+    ("alto", "high"),
+    ("medio", "medium"),
+    ("bajo", "low"),
+    ("info", "info"),
+];
+
+/// The last day the API accepts the legacy severity values.
+const LEGACY_SEVERITY_END: &str = "2027-01-14";
+
+/// The specific hint for a legacy severity value, or `None` when the generic warning applies.
+///
+/// It fires only when the API document lists the English values, so only once the server has
+/// switched. Until then the API still returns the legacy scale and the legacy values are the
+/// working spelling; telling users to move away from them would send them to values that match
+/// nothing. A document without a list stays silent, like every other filter.
+fn legacy_hint(operation: &Operation, param: &str, value: &str, known: &[&str]) -> Option<String> {
+    if operation.id != "listAlerts" || param != "severity" {
+        return None;
+    }
+    let (_, current) = LEGACY_SEVERITY
+        .iter()
+        .find(|(legacy, _)| legacy.eq_ignore_ascii_case(value))?;
+    if !known.contains(current) {
+        return None;
+    }
+    Some(format!(
+        "warning: `{}` is a legacy severity value, accepted by the API until \
+         {LEGACY_SEVERITY_END}; use `{current}`. Sending it as typed.",
+        clean(value),
+    ))
+}
+
 /// The warnings for the `(parameter, value)` pairs the user gave, one per value that is not in the
 /// list the document publishes for that parameter. A parameter without a list never warns. The
 /// match is exact and case-sensitive, as the API is; a value that differs only by case also gets
@@ -32,6 +73,9 @@ pub fn warnings(operation: &Operation, filters: &[(&str, Option<&str>)]) -> Vec<
             if known.contains(&value) {
                 return None;
             }
+            if let Some(hint) = legacy_hint(operation, param, value, known) {
+                return Some(hint);
+            }
             let tail = known
                 .iter()
                 .find(|k| k.eq_ignore_ascii_case(value))
@@ -108,6 +152,84 @@ mod tests {
         assert!(warnings(&WITHOUT_LISTS, &[("severity", Some("urgent"))]).is_empty());
     }
 
+    const ENGLISH: Operation = Operation {
+        known_values: &[("severity", &["critical", "high", "medium", "low", "info"])],
+        ..WITH_LISTS
+    };
+
+    #[test]
+    fn a_legacy_severity_points_to_its_new_name() {
+        assert_eq!(
+            warnings(&ENGLISH, &[("severity", Some("alto"))]),
+            [
+                "warning: `alto` is a legacy severity value, accepted by the API until \
+                 2027-01-14; use `high`. Sending it as typed."
+            ]
+        );
+        for (legacy, current) in [
+            ("critico", "critical"),
+            ("medio", "medium"),
+            ("bajo", "low"),
+        ] {
+            let out = warnings(&ENGLISH, &[("severity", Some(legacy))]);
+            assert!(out[0].contains(&format!("use `{current}`")), "{out:?}");
+        }
+    }
+
+    #[test]
+    fn a_legacy_severity_is_matched_without_regard_to_case() {
+        let out = warnings(&ENGLISH, &[("severity", Some("ALTO"))]);
+        assert_eq!(out.len(), 1);
+        assert!(out[0].starts_with("warning: `ALTO` is a legacy severity value"));
+        assert!(out[0].contains("use `high`"), "{out:?}");
+    }
+
+    #[test]
+    fn a_current_severity_is_silent() {
+        for value in ["critical", "high", "medium", "low", "info"] {
+            assert!(warnings(&ENGLISH, &[("severity", Some(value))]).is_empty());
+        }
+    }
+
+    #[test]
+    fn an_unrelated_severity_keeps_the_generic_warning() {
+        let out = warnings(&ENGLISH, &[("severity", Some("urgent"))]);
+        assert!(
+            out[0].contains("is not one of the values the API lists"),
+            "{out:?}"
+        );
+    }
+
+    #[test]
+    fn the_legacy_hint_waits_for_the_english_list() {
+        // No list yet: the API still speaks the legacy scale, so say nothing.
+        assert!(warnings(&WITHOUT_LISTS, &[("severity", Some("alto"))]).is_empty());
+        // A list without the new name: nothing to point to, so the generic warning stays.
+        let other_list = Operation {
+            known_values: &[("severity", &["urgent"])],
+            ..WITH_LISTS
+        };
+        let out = warnings(&other_list, &[("severity", Some("bajo"))]);
+        assert!(
+            out[0].contains("is not one of the values the API lists"),
+            "{out:?}"
+        );
+    }
+
+    #[test]
+    fn the_legacy_hint_is_scoped_to_the_alert_severity_filter() {
+        let other = Operation {
+            id: "listRisks",
+            known_values: &[("severity", &["high"])],
+            ..WITH_LISTS
+        };
+        let out = warnings(&other, &[("severity", Some("alto"))]);
+        assert!(
+            out[0].contains("is not one of the values the API lists"),
+            "{out:?}"
+        );
+    }
+
     #[test]
     fn control_characters_in_the_value_are_not_echoed() {
         let out = warnings(&WITH_LISTS, &[("severity", Some("a\u{1b}[31mb"))]);

From 27487a801e8b93e83ef373edb1de3047d5c8a7ea Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Thu, 8 Oct 2026 19:17:49 +0200
Subject: [PATCH 18/57] Fix the proxy test's expected error prefix and record
 Linux verification

Refs #25

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 .github/scripts/proxy-tls-test.sh | 25 ++++++++++++-------------
 README.md                         |  4 ++--
 2 files changed, 14 insertions(+), 15 deletions(-)

diff --git a/.github/scripts/proxy-tls-test.sh b/.github/scripts/proxy-tls-test.sh
index 6b3c5a7..145a0dd 100755
--- a/.github/scripts/proxy-tls-test.sh
+++ b/.github/scripts/proxy-tls-test.sh
@@ -5,7 +5,7 @@
 # Proves the README's "Networking: proxies and TLS inspection" claims on Linux, end to end, with a
 # real TLS-inspecting proxy (mitmproxy) and a fake API, all on this machine:
 #
-#   1. HTTPS_PROXY set, proxy CA not trusted       -> exit 7, "Could not reach the API:", certificate
+#   1. HTTPS_PROXY set, proxy CA not trusted       -> exit 7, "error: Could not reach the API:", certificate
 #   2. proxy CA in the system store                -> works, and the proxy saw the request
 #   3. proxy CA only in SSL_CERT_FILE              -> works
 #   4. NO_PROXY covers the host                    -> the proxy is not used
@@ -91,9 +91,9 @@ wait_port "$PROXY_PORT"
 # --- Helpers ----------------------------------------------------------------------------------
 RESULTS=()
 FAILED=0
-record() { # case, description, ok|FAIL, detail
+record() { # case, description, PASS|FAIL, detail
   RESULTS+=("$1|$2|$3|$4")
-  if [ "$3" != ok ]; then FAILED=1; fi
+  if [ "$3" != PASS ]; then FAILED=1; fi
 }
 
 # Runs the CLI with a clean proxy/certificate environment plus the given NAME=value pairs.
@@ -138,10 +138,10 @@ PROXY=http://127.0.0.1:$PROXY_PORT
 p0=$(proxy_seen) a0=$(api_seen)
 cli HTTPS_PROXY="$PROXY" -- vendors list --json
 sleep 1
-if [ "$rc" -eq 7 ] && [[ "$(cat "$WORK/err")" == "Could not reach the API:"* ]] \
+if [ "$rc" -eq 7 ] && [[ "$(cat "$WORK/err")" == "error: Could not reach the API:"* ]] \
   && grep -qiE 'certificate|UnknownIssuer' "$WORK/err" \
   && [ "$(proxy_seen)" -eq "$p0" ] && [ "$(api_seen)" -eq "$a0" ]; then
-  record 1 "HTTPS_PROXY, proxy CA not trusted: exit 7, certificate error, nothing delivered" ok "exit $rc"
+  record 1 "HTTPS_PROXY, proxy CA not trusted: exit 7, certificate error, nothing delivered" PASS "exit $rc"
 else
   record 1 "HTTPS_PROXY, proxy CA not trusted: exit 7, certificate error, nothing delivered" FAIL "exit $rc"
   show_failure 1
@@ -151,7 +151,7 @@ fi
 p0=$(proxy_seen)
 cli HTTPS_PROXY="$PROXY" SSL_CERT_FILE="$WORK/proxy-ca.crt" -- vendors list --json
 if works && wait_proxy_above "$p0"; then
-  record 3 "proxy CA only in SSL_CERT_FILE: works through the proxy" ok "exit $rc"
+  record 3 "proxy CA only in SSL_CERT_FILE: works through the proxy" PASS "exit $rc"
 else
   record 3 "proxy CA only in SSL_CERT_FILE: works through the proxy" FAIL "exit $rc"
   show_failure 3
@@ -162,7 +162,7 @@ p0=$(proxy_seen) a0=$(api_seen)
 cli HTTPS_PROXY="$PROXY" NO_PROXY="$HOST" SSL_CERT_FILE="$WORK/upstream-ca.crt" -- vendors list --json
 sleep 1
 if works && [ "$(api_seen)" -gt "$a0" ] && [ "$(proxy_seen)" -eq "$p0" ]; then
-  record 4 "NO_PROXY covers the host: direct to the API, proxy bypassed" ok "exit $rc"
+  record 4 "NO_PROXY covers the host: direct to the API, proxy bypassed" PASS "exit $rc"
 else
   record 4 "NO_PROXY covers the host: direct to the API, proxy bypassed" FAIL "exit $rc"
   show_failure 4
@@ -174,7 +174,7 @@ sudo update-ca-certificates > /dev/null
 p0=$(proxy_seen)
 cli HTTPS_PROXY="$PROXY" -- vendors list --json
 if works && wait_proxy_above "$p0"; then
-  record 2 "proxy CA in the system store: works, the proxy saw the request" ok "exit $rc"
+  record 2 "proxy CA in the system store: works, the proxy saw the request" PASS "exit $rc"
 else
   record 2 "proxy CA in the system store: works, the proxy saw the request" FAIL "exit $rc"
   show_failure 2
@@ -184,7 +184,7 @@ fi
 p0=$(proxy_seen)
 cli https_proxy="$PROXY" -- vendors list --json
 if works && wait_proxy_above "$p0"; then
-  record 5 "lower-case https_proxy works like upper-case" ok "exit $rc"
+  record 5 "lower-case https_proxy works like upper-case" PASS "exit $rc"
 else
   record 5 "lower-case https_proxy works like upper-case" FAIL "exit $rc"
   show_failure 5
@@ -194,7 +194,7 @@ fi
 cli HTTPS_PROXY="$PROXY" -- --verbose vendors list --json
 if works && grep -qE "^GET https://api\.test:8443/v1/vendors.* → 200 " "$WORK/err" \
   && ! grep -q "GET " "$WORK/out"; then
-  record 6 "--verbose: request line on stderr, stdout stays clean JSON" ok "exit $rc"
+  record 6 "--verbose: request line on stderr, stdout stays clean JSON" PASS "exit $rc"
 else
   record 6 "--verbose: request line on stderr, stdout stays clean JSON" FAIL "exit $rc"
   show_failure 6
@@ -203,10 +203,9 @@ fi
 # --- Report ------------------------------------------------------------------------------------
 echo
 printf '%-5s %-78s %s\n' CASE DESCRIPTION RESULT
-for row in "${RESULTS[@]}"; do
-  IFS='|' read -r n desc result _detail <<< "$row"
+while IFS='|' read -r n desc result _detail; do
   printf '%-5s %-78s %s\n' "$n" "$desc" "$result"
-done
+done < <(printf '%s\n' "${RESULTS[@]}" | sort)
 if [ "$FAILED" -ne 0 ]; then
   echo
   echo "--- proxy log"; tail -n 40 "$WORK/proxy.log"
diff --git a/README.md b/README.md
index e602336..7caf876 100644
--- a/README.md
+++ b/README.md
@@ -417,8 +417,8 @@ message that starts with `Could not reach the API:` (or `Could not reach the app
 followed by the cause. A certificate error there usually means the proxy's CA is missing from the
 store described above.
 
-This behaviour comes from the CLI's HTTP library; it has not yet been verified behind a
-TLS-inspecting proxy on every platform.
+This behaviour comes from the CLI's HTTP library. It is verified on Linux in CI against a
+TLS-inspecting proxy; macOS and Windows have not been verified yet.
 
 ## Repository layout
 

From 6edb95f059ba019d8c615bf62d84fed4e55b8ac9 Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Thu, 8 Oct 2026 19:19:18 +0200
Subject: [PATCH 19/57] Publish a signed multi-architecture container image
 with each release

A new workflow, run when a release is published, builds
ghcr.io/hodeitek/hodeishield-cli for linux/amd64 and linux/arm64 from the
release's own musl archives, after verifying SHA256SUMS with cosign and the
files against it. The image is a distroless static base pinned by digest, runs
as a non-root user and is tagged with the exact version only. It is signed by
digest with cosign (keyless) and carries the release's CycloneDX SBOM as a
signed attestation. The job runs in the packaging environment and is the only
one with packages: write.

The first image appears with the next stable release.

Refs #36

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 .github/dependabot.yml                |   9 ++
 .github/workflows/container-image.yml | 178 ++++++++++++++++++++++++++
 CHANGELOG.md                          |   7 +
 CONTRIBUTING.md                       |  10 ++
 README.md                             |  42 ++++++
 packaging/container/Dockerfile        |  19 +++
 6 files changed, 265 insertions(+)
 create mode 100644 .github/workflows/container-image.yml
 create mode 100644 packaging/container/Dockerfile

diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index e6ef5a2..58d16c7 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -44,3 +44,12 @@ updates:
     ignore:
       - dependency-name: "*"
         update-types: ["version-update:semver-major"]
+
+  # The pinned base image of the container image (packaging/container/Dockerfile).
+  - package-ecosystem: "docker"
+    directory: "/packaging/container"
+    target-branch: "dev"
+    schedule:
+      interval: "weekly"
+    cooldown:
+      default-days: 7
diff --git a/.github/workflows/container-image.yml b/.github/workflows/container-image.yml
new file mode 100644
index 0000000..e7677c7
--- /dev/null
+++ b/.github/workflows/container-image.yml
@@ -0,0 +1,178 @@
+name: Container image
+
+# When a release is published (not while it is a draft), builds ghcr.io/hodeitek/hodeishield-cli for
+# linux/amd64 and linux/arm64 from that release's own musl binaries, signs the image by digest with
+# cosign (keyless) and attaches the release's CycloneDX SBOM as a signed attestation. Nothing is
+# compiled here: the binaries come from the release archives, which are checked against the
+# release workflow's signed SHA256SUMS first. No `latest` tag is ever written.
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: container-image
+  cancel-in-progress: false
+
+env:
+  IMAGE: ghcr.io/hodeitek/hodeishield-cli
+
+jobs:
+  image:
+    name: build, push and sign the image
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    # Publishing to a registry is approved by the same reviewer as the other package channels.
+    environment: packaging
+    permissions:
+      contents: read
+      packages: write # to push the image with the job's own token; no other job has it
+      id-token: write # for cosign's Sigstore keyless (OIDC) signing
+    steps:
+      - name: Read the release version
+        id: version
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+          PRERELEASE: ${{ github.event.release.prerelease }}
+        run: |
+          set -euo pipefail
+          if [[ ! "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]] || [ "$PRERELEASE" = true ]; then
+            echo "::notice::$TAG is not a stable release; no container image is published."
+            exit 0
+          fi
+          echo "version=${TAG#v}" >> "$GITHUB_OUTPUT"
+
+      - name: Checkout
+        if: steps.version.outputs.version != ''
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install cosign
+        if: steps.version.outputs.version != ''
+        uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
+        with:
+          cosign-release: "v3.1.3"
+
+      # Only the two Linux archives, their SBOMs and the file that vouches for them are downloaded.
+      - name: Download and verify the release files
+        if: steps.version.outputs.version != ''
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          set -euo pipefail
+          files=()
+          for t in x86_64-unknown-linux-musl aarch64-unknown-linux-musl; do
+            files+=("hodeishield-${VERSION}-${t}.tar.gz" "hodeishield-${VERSION}-${t}.cdx.json")
+          done
+          mkdir rel
+          args=(-p SHA256SUMS -p SHA256SUMS.sigstore.json)
+          for f in "${files[@]}"; do args+=(-p "$f"); done
+          gh release download "v$VERSION" -R "$GITHUB_REPOSITORY" -D rel "${args[@]}"
+          cosign verify-blob --bundle rel/SHA256SUMS.sigstore.json \
+            --certificate-identity "https://github.com/${GITHUB_REPOSITORY}/.github/workflows/release.yml@refs/tags/v${VERSION}" \
+            --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+            --certificate-github-workflow-trigger push rel/SHA256SUMS
+          for f in "${files[@]}"; do grep "  ${f}\$" rel/SHA256SUMS; done > rel/files.sums
+          [ "$(wc -l < rel/files.sums)" = 4 ]
+          (cd rel && sha256sum -c files.sums)
+
+      # amd64/ and arm64/ are the names the Dockerfile's TARGETARCH picks from.
+      - name: Stage the build context
+        if: steps.version.outputs.version != ''
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          set -euo pipefail
+          mkdir -p ctx/amd64 ctx/arm64 ext
+          for pair in x86_64-unknown-linux-musl:amd64 aarch64-unknown-linux-musl:arm64; do
+            t="${pair%%:*}" arch="${pair##*:}"
+            tar -xzf "rel/hodeishield-${VERSION}-${t}.tar.gz" -C ext
+            d="ext/hodeishield-${VERSION}-${t}"
+            [ -f "$d/hodeishield" ] && [ ! -L "$d/hodeishield" ]
+            cp "$d/hodeishield" "ctx/$arch/hodeishield"
+            cp "$d/LICENSE" "$d/NOTICE" ctx/
+          done
+          # Both Linux targets are built from the same dependency set, so one SBOM describes the
+          # image; this checks that claim instead of assuming it.
+          python3 - "rel/hodeishield-${VERSION}-x86_64-unknown-linux-musl.cdx.json" "rel/hodeishield-${VERSION}-aarch64-unknown-linux-musl.cdx.json" <<'PY'
+          import json, sys
+          a, b = (sorted(c["purl"] for c in json.load(open(p))["components"]) for p in sys.argv[1:])
+          if a != b:
+              sys.exit("the two Linux SBOMs list different components")
+          print(len(a), "components, identical for both architectures")
+          PY
+          find ctx -type f | sort
+
+      - name: Set up Buildx
+        if: steps.version.outputs.version != ''
+        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
+
+      - name: Log in to ghcr.io
+        if: steps.version.outputs.version != ''
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ github.token }}
+
+      # Only COPY steps, so building the arm64 image needs no emulation.
+      - name: Build and push
+        if: steps.version.outputs.version != ''
+        id: build
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          set -euo pipefail
+          docker buildx build ctx \
+            --file packaging/container/Dockerfile \
+            --platform linux/amd64,linux/arm64 \
+            --tag "${IMAGE}:${VERSION}" \
+            --label "org.opencontainers.image.title=hodeishield" \
+            --label "org.opencontainers.image.version=${VERSION}" \
+            --label "org.opencontainers.image.source=https://github.com/${GITHUB_REPOSITORY}" \
+            --label "org.opencontainers.image.licenses=Apache-2.0" \
+            --provenance=false --sbom=false \
+            --metadata-file "$RUNNER_TEMP/build.json" \
+            --push
+          digest=$(python3 -c "import json,sys; print(json.load(open(sys.argv[1]))['containerimage.digest'])" "$RUNNER_TEMP/build.json")
+          [[ "$digest" =~ ^sha256:[0-9a-f]{64}$ ]] || { echo "::error::unexpected digest: $digest"; exit 1; }
+          echo "digest=$digest" >> "$GITHUB_OUTPUT"
+          echo "Pushed ${IMAGE}:${VERSION} as ${digest}"
+
+      # Keyless, and by digest: the tag can move, the digest cannot.
+      - name: Sign the image
+        if: steps.version.outputs.version != ''
+        env:
+          DIGEST: ${{ steps.build.outputs.digest }}
+        run: cosign sign --yes "${IMAGE}@${DIGEST}"
+
+      - name: Attach the SBOM as an attestation
+        if: steps.version.outputs.version != ''
+        env:
+          DIGEST: ${{ steps.build.outputs.digest }}
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          cosign attest --yes --type cyclonedx \
+            --predicate "rel/hodeishield-${VERSION}-x86_64-unknown-linux-musl.cdx.json" \
+            "${IMAGE}@${DIGEST}"
+
+      # Checks what a user will check, with the constraints the README gives, then runs the image.
+      - name: Verify the signature and the attestation, and run the image
+        if: steps.version.outputs.version != ''
+        env:
+          DIGEST: ${{ steps.build.outputs.digest }}
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          set -euo pipefail
+          identity="https://github.com/${GITHUB_REPOSITORY}/.github/workflows/container-image.yml@refs/tags/v${VERSION}"
+          verify=(--certificate-identity "$identity"
+            --certificate-oidc-issuer https://token.actions.githubusercontent.com
+            --certificate-github-workflow-trigger release)
+          cosign verify "${verify[@]}" "${IMAGE}@${DIGEST}" > /dev/null
+          cosign verify-attestation --type cyclonedx "${verify[@]}" "${IMAGE}@${DIGEST}" > /dev/null
+          [ "$(docker run --rm "${IMAGE}@${DIGEST}" --version)" = "hodeishield ${VERSION}" ]
+          docker buildx imagetools inspect "${IMAGE}@${DIGEST}"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 78b6aaf..c1340f1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,13 @@ commands, `--json` output and exit codes. Each release's notes start with its se
 
 ## [Unreleased]
 
+### Added
+
+- A container image, `ghcr.io/hodeitek/hodeishield-cli`, for `linux/amd64` and `linux/arm64`: the
+  release's own binary on a distroless base, running as a non-root user, tagged with the exact
+  version only. It is signed by digest with Sigstore and carries the release's SBOM as a signed
+  attestation. ([#36](https://github.com/Hodeitek/hodeishield-cli/issues/36))
+
 ## [0.3.0] - 2026-10-07
 
 ### Added
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index fa59db3..788f83e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -169,6 +169,16 @@ and it is closed when the check passes again; a release less than 48 hours old t
 only raises a warning, since the `repos` job waits for an approval. On such an issue, first check who
 can write to the bucket, then re-run the `repos` job for the latest release to publish current indexes.
 
+Publishing a release also starts the **Container image** workflow. After the same `packaging`
+environment approval, it downloads the release's two Linux musl archives and SBOMs, verifies
+`SHA256SUMS` with cosign (the same identity as above) and the files against it, and builds
+`ghcr.io/hodeitek/hodeishield-cli` for `linux/amd64` and `linux/arm64` from `packaging/container/Dockerfile`
+without compiling anything. It pushes the exact-version tag only (no `latest`) with the job's own
+`GITHUB_TOKEN` (`packages: write`, held by no other job), signs the image by digest with cosign,
+attaches the SBOM with `cosign attest --type cyclonedx`, then verifies both and runs the image. Stable
+releases only. The base image is pinned by digest and bumped by dependabot. The first time, the package
+is private: a maintainer makes it public in the package settings once the first image exists.
+
 winget is submitted by hand, and only with the maintainers' approval, because it is a public
 submission to another project:
 
diff --git a/README.md b/README.md
index e602336..c2435ad 100644
--- a/README.md
+++ b/README.md
@@ -141,6 +141,48 @@ sh install.sh --version $v
 It needs `cosign` to check the archive's signature and stops if it is missing; `--no-verify` skips
 that check (the checksum still runs). `sh install.sh --help` lists the options (`--dir`, `--no-man`).
 
+### Container image
+
+From the first release after 0.3.0, each stable release also publishes a multi-architecture
+(`linux/amd64`, `linux/arm64`) image at `ghcr.io/hodeitek/hodeishield-cli`, for CI jobs and container
+pipelines. It holds only the release's own `hodeishield` binary on a
+[distroless](https://github.com/GoogleContainerTools/distroless) static base (no shell, no package
+manager, CA certificates included) and runs as a non-root user. There is no `latest` tag: use the
+exact version, or better its digest.
+
+```sh
+v=0.4.0   # the version you want
+docker pull ghcr.io/hodeitek/hodeishield-cli:$v
+docker run --rm -e HODEISHIELD_API_KEY ghcr.io/hodeitek/hodeishield-cli:$v vendors list
+```
+
+`HODEISHIELD_API_KEY` is passed through from your environment (`-e NAME` without a value) so the key
+never appears on the command line. `hodeishield login` does not work in a container (there is no
+browser and no system keychain): use a tenant API key, see [Authenticate](#authenticate).
+
+The image is signed by digest with cosign (keyless) and carries the release's CycloneDX SBOM as a
+signed attestation. Verify both before you rely on the image:
+
+```sh
+v=0.4.0
+image=ghcr.io/hodeitek/hodeishield-cli:$v
+cosign verify $image \
+  --certificate-identity https://github.com/Hodeitek/hodeishield-cli/.github/workflows/container-image.yml@refs/tags/v$v \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+  --certificate-github-workflow-trigger release
+
+cosign verify-attestation --type cyclonedx $image \
+  --certificate-identity https://github.com/Hodeitek/hodeishield-cli/.github/workflows/container-image.yml@refs/tags/v$v \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+  --certificate-github-workflow-trigger release
+```
+
+Both commands print the digest they verified; pin that digest
+(`ghcr.io/hodeitek/hodeishield-cli@sha256:...`) in your pipeline, since a tag can be moved and a
+digest cannot. The binary in the image is the one in the release's Linux musl archives, checked
+against the release's signed `SHA256SUMS` before the image is built. The image's own base image is
+pinned by digest in [packaging/container/Dockerfile](packaging/container/Dockerfile).
+
 ### Man pages
 
 From 0.2.0, the Linux and macOS archives include a man page for every command in `man/`. To read
diff --git a/packaging/container/Dockerfile b/packaging/container/Dockerfile
new file mode 100644
index 0000000..c6ad107
--- /dev/null
+++ b/packaging/container/Dockerfile
@@ -0,0 +1,19 @@
+# The HodeiShield CLI image. It contains only the release's own, already verified binary (see
+# .github/workflows/container-image.yml), never one built here, on a base image with CA
+# certificates and nothing else: no shell and no package manager.
+#
+# Build context: a directory holding amd64/hodeishield and arm64/hodeishield, the binaries from the
+# release's x86_64 and aarch64 musl archives, plus LICENSE and NOTICE.
+#
+# The base is gcr.io/distroless/static-debian12:nonroot, pinned by the digest of its multi-arch
+# index (dependabot proposes newer digests). It ships /etc/ssl/certs/ca-certificates.crt, which the
+# CLI reads as the operating system's trust store, and runs as uid/gid 65532.
+FROM gcr.io/distroless/static-debian12:nonroot@sha256:afa5c872c891853ca7fcf1f12c3edb23f7eeef36189728842dd51042ff57f7ab
+
+ARG TARGETARCH
+
+COPY --chmod=0555 ${TARGETARCH}/hodeishield /usr/local/bin/hodeishield
+COPY LICENSE NOTICE /licenses/
+
+USER 65532:65532
+ENTRYPOINT ["/usr/local/bin/hodeishield"]

From 8489bfa3210519b5c839a21ae912635197d5ea97 Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Thu, 8 Oct 2026 19:19:42 +0200
Subject: [PATCH 20/57] Tell interactive users when a newer version is released

On an interactive terminal, ask GitHub's public releases API at most once
a day and print one line on stderr when a newer version exists. Silent
with --json, --csv, completions, CI, a non-terminal stderr, and when
HODEISHIELD_NO_UPDATE_CHECK or update_check = false opts out. Failures
never change output or exit code. No credential or identifier is sent.

Closes #38

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 CHANGELOG.md                                  |  10 +
 README.md                                     |  32 ++
 crates/hodeishield-cli/src/cli.rs             |  11 +
 crates/hodeishield-cli/src/commands/config.rs |  22 ++
 crates/hodeishield-cli/src/config.rs          |  42 ++-
 crates/hodeishield-cli/src/lib.rs             |   5 +
 crates/hodeishield-cli/src/update_check.rs    | 224 +++++++++++++
 crates/hodeishield-cli/tests/update_check.rs  | 311 ++++++++++++++++++
 8 files changed, 655 insertions(+), 2 deletions(-)
 create mode 100644 crates/hodeishield-cli/src/update_check.rs
 create mode 100644 crates/hodeishield-cli/tests/update_check.rs

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 78b6aaf..19a0c94 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,16 @@ commands, `--json` output and exit codes. Each release's notes start with its se
 
 ## [Unreleased]
 
+### Added
+
+- On an interactive terminal, the CLI now tells you in one line on standard error when a newer
+  release exists. It asks GitHub's public releases API (no credential or identifier is sent) at most
+  once a day, stays silent with `--json`, `--csv`, `completions`, when standard error is not a
+  terminal and when `CI` is set, and never changes a command's output or exit code. Turn it off with
+  `HODEISHIELD_NO_UPDATE_CHECK=1` or `hodeishield config set update_check false`; the README's "New-version
+  notice" section lists exactly what is sent.
+  ([#38](https://github.com/Hodeitek/hodeishield-cli/issues/38))
+
 ## [0.3.0] - 2026-10-07
 
 ### Added
diff --git a/README.md b/README.md
index e602336..a7a5f2e 100644
--- a/README.md
+++ b/README.md
@@ -362,6 +362,7 @@ hodeishield config show                      # the settings in effect
 hodeishield config path                      # where the file is
 hodeishield --profile staging config set api_url https://api.example.test
 hodeishield config use staging               # make it the default profile
+hodeishield config set update_check false    # no new-version notice (global, not per profile)
 hodeishield --profile default vendors list   # or pick one per command
 ```
 
@@ -372,10 +373,41 @@ hodeishield --profile default vendors list   # or pick one per command
 | `HODEISHIELD_API_URL` | API base URL |
 | `HODEISHIELD_APP_URL` | App base URL (sign-in) |
 | `HODEISHIELD_CONFIG` | Path of the configuration file |
+| `HODEISHIELD_NO_UPDATE_CHECK` | Any non-empty value turns off the [new-version notice](#new-version-notice) |
 
 The configuration file holds URLs and sign-in settings only, never a credential. URLs must use HTTPS;
 plain HTTP is accepted only for `localhost`.
 
+## New-version notice
+
+On an interactive terminal the CLI tells you, in one line on standard error, when a newer release
+exists:
+
+```
+A newer version of hodeishield is available: 0.4.0 (you have 0.3.0). See https://github.com/Hodeitek/hodeishield-cli/releases
+```
+
+It never updates anything. Privacy, in full:
+
+- **What is sent.** One unauthenticated `GET` to GitHub's public API,
+  `https://api.github.com/repos/Hodeitek/hodeishield-cli/releases/latest`, with a 2 second limit.
+  Only what HTTP requires goes with it, including `User-Agent: hodeishield-cli/<version>` and
+  `Accept`. No API key, token, profile, tenant, command or machine identifier is sent, and nothing
+  goes to HodeiShield: GitHub sees your IP address, as it does for any request. Your proxy settings
+  apply (see [Networking](#networking-proxies-and-tls-inspection)).
+- **When.** At most once every 24 hours, after the command has finished and printed its output.
+  The time of the last attempt, and the version it found, are kept in `update-check.json` next to
+  the configuration file (see `hodeishield config path`). A failed attempt (offline, timeout,
+  GitHub unavailable) is silent, is not repeated before the next day, and never changes a command's
+  output or exit code. Add `--verbose` to see why nothing was shown.
+- **Where it is silent.** When standard error is not a terminal, with `--json` and `--csv`, for
+  `completions`, and whenever the `CI` environment variable is set, to any value. The notice goes to
+  standard error, so a terminal on standard error is what decides, not whether standard output is
+  piped.
+- **Turning it off.** `export HODEISHIELD_NO_UPDATE_CHECK=1`, or once for all profiles
+  `hodeishield config set update_check false` (`config unset update_check` restores the default).
+  With either, no request is made.
+
 Shell completions: `hodeishield completions bash|zsh|fish|powershell|elvish`.
 
 ## Networking: proxies and TLS inspection
diff --git a/crates/hodeishield-cli/src/cli.rs b/crates/hodeishield-cli/src/cli.rs
index 576b03c..2f17fbb 100644
--- a/crates/hodeishield-cli/src/cli.rs
+++ b/crates/hodeishield-cli/src/cli.rs
@@ -138,6 +138,17 @@ impl Cli {
     }
 }
 
+impl Cli {
+    /// Whether this invocation prints something a program reads: `--json`, `--csv` or the
+    /// completion script. Nothing but that output may be added to such a run.
+    #[must_use]
+    pub(crate) fn prints_for_programs(&self) -> bool {
+        self.json
+            || matches!(self.command, Command::Completions { .. })
+            || self.command.paging().is_some_and(|paging| paging.csv)
+    }
+}
+
 impl Command {
     /// The paging options, for the commands that list.
     fn paging(&self) -> Option<&Paging> {
diff --git a/crates/hodeishield-cli/src/commands/config.rs b/crates/hodeishield-cli/src/commands/config.rs
index f1ccb73..116e29b 100644
--- a/crates/hodeishield-cli/src/commands/config.rs
+++ b/crates/hodeishield-cli/src/commands/config.rs
@@ -20,6 +20,7 @@ pub fn run(ctx: &Context, command: ConfigCommand, out: &mut dyn Write) -> Result
         }
         ConfigCommand::Show => {
             let settings = ctx.settings()?;
+            let update_check = config::load(&path)?.update_check.unwrap_or(true);
             let value = json!({
                 "config_file": settings.config_path.display().to_string(),
                 "profile": settings.profile,
@@ -27,6 +28,7 @@ pub fn run(ctx: &Context, command: ConfigCommand, out: &mut dyn Write) -> Result
                 "app_url": settings.app_url.as_str(),
                 "oauth_client_id": settings.oauth_client_id,
                 "oauth_scopes": settings.oauth_scopes,
+                "update_check": update_check,
             });
             if ctx.json {
                 return Ok(print_json(out, &value)?);
@@ -40,8 +42,16 @@ pub fn run(ctx: &Context, command: ConfigCommand, out: &mut dyn Write) -> Result
             writeln!(out, "app_url          {}", settings.app_url)?;
             writeln!(out, "oauth_client_id  {}", settings.oauth_client_id)?;
             writeln!(out, "oauth_scopes     {scopes}")?;
+            writeln!(out, "update_check     {update_check}")?;
             Ok(())
         }
+        ConfigCommand::Set { key, value } if key == config::UPDATE_CHECK => {
+            edit_global(&path, |file| file.set_update_check(&value))
+        }
+        ConfigCommand::Unset { key } if key == config::UPDATE_CHECK => edit_global(&path, |file| {
+            file.update_check = None;
+            Ok(())
+        }),
         ConfigCommand::Set { key, value } => edit(ctx, &path, |profile| profile.set(&key, &value)),
         ConfigCommand::Unset { key } => edit(ctx, &path, |profile| profile.unset(&key)),
         ConfigCommand::Use { name } => {
@@ -61,6 +71,18 @@ pub fn run(ctx: &Context, command: ConfigCommand, out: &mut dyn Write) -> Result
     }
 }
 
+/// Changes a setting that belongs to the file, not to a profile.
+fn edit_global(
+    path: &std::path::Path,
+    change: impl FnOnce(&mut config::ConfigFile) -> Result<()>,
+) -> Result<()> {
+    let mut file = config::load(path)?;
+    change(&mut file)?;
+    config::save(path, &file)?;
+    eprintln!("Saved in {}.", path.display());
+    Ok(())
+}
+
 /// Changes the profile named by `--profile` (or the default one), creating it if needed.
 fn edit(
     ctx: &Context,
diff --git a/crates/hodeishield-cli/src/config.rs b/crates/hodeishield-cli/src/config.rs
index 248acc6..71c3fb9 100644
--- a/crates/hodeishield-cli/src/config.rs
+++ b/crates/hodeishield-cli/src/config.rs
@@ -25,6 +25,9 @@ pub struct ConfigFile {
     /// Profile used when neither `--profile` nor `HODEISHIELD_PROFILE` names one.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub default_profile: Option<String>,
+    /// Whether to look for a newer release once a day. Global, not per profile. Unset: yes.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub update_check: Option<bool>,
     #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
     pub profiles: BTreeMap<String, Profile>,
 }
@@ -46,8 +49,33 @@ pub struct Profile {
     pub oauth_scopes: Option<Vec<String>>,
 }
 
-/// The keys `config set` and `config unset` accept.
-pub const KEYS: &[&str] = &["api_url", "app_url", "oauth_client_id", "oauth_scopes"];
+/// The keys `config set` and `config unset` accept. `update_check` is global; the rest belong to a
+/// profile.
+pub const KEYS: &[&str] = &[
+    "api_url",
+    "app_url",
+    "oauth_client_id",
+    "oauth_scopes",
+    UPDATE_CHECK,
+];
+
+/// The one global key.
+pub const UPDATE_CHECK: &str = "update_check";
+
+impl ConfigFile {
+    pub fn set_update_check(&mut self, value: &str) -> Result<()> {
+        self.update_check = Some(match value.trim().to_ascii_lowercase().as_str() {
+            "true" => true,
+            "false" => false,
+            _ => {
+                return Err(Failure::general(format!(
+                    "update_check: `{value}` is not true or false."
+                )));
+            }
+        });
+        Ok(())
+    }
+}
 
 impl Profile {
     pub fn set(&mut self, key: &str, value: &str) -> Result<()> {
@@ -350,6 +378,16 @@ mod tests {
         }
     }
 
+    #[test]
+    fn update_check_is_a_global_boolean() {
+        let mut config = ConfigFile::default();
+        assert!(config.set_update_check("maybe").is_err());
+        config.set_update_check("False").expect("set");
+        assert_eq!(config.update_check, Some(false));
+        let text = toml::to_string_pretty(&config).expect("toml");
+        assert_eq!(text.trim(), "update_check = false");
+    }
+
     #[test]
     fn unknown_keys_are_refused() {
         let mut profile = Profile::default();
diff --git a/crates/hodeishield-cli/src/lib.rs b/crates/hodeishield-cli/src/lib.rs
index 3c7eaa4..1b30b98 100644
--- a/crates/hodeishield-cli/src/lib.rs
+++ b/crates/hodeishield-cli/src/lib.rs
@@ -14,6 +14,7 @@ mod config;
 mod failure;
 mod filters;
 mod output;
+mod update_check;
 
 use std::io::{ErrorKind, Write};
 use std::process::ExitCode;
@@ -28,10 +29,14 @@ pub const USER_AGENT: &str = concat!(
 #[must_use]
 pub fn main() -> ExitCode {
     let cli = cli::Cli::parse_checked();
+    let for_programs = cli.prints_for_programs();
+    let verbose = cli.verbose;
     let stdout = std::io::stdout();
     let mut out = std::io::BufWriter::new(stdout.lock());
     let result = commands::run(cli, &mut out);
     let flushed = out.flush();
+    // After the command's own work and output, so it never delays them.
+    update_check::notify(for_programs, verbose);
     match result {
         Ok(()) => match flushed {
             Ok(()) => ExitCode::SUCCESS,
diff --git a/crates/hodeishield-cli/src/update_check.rs b/crates/hodeishield-cli/src/update_check.rs
new file mode 100644
index 0000000..b3c27be
--- /dev/null
+++ b/crates/hodeishield-cli/src/update_check.rs
@@ -0,0 +1,224 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Hodeitek S.L.
+
+//! The notice that a newer release exists.
+//!
+//! The interface is one function, [`notify`], called once after a command has finished and its
+//! output has been flushed. It decides, asks and prints; the caller learns nothing and nothing can
+//! fail: every error is dropped (logged with `--verbose`).
+//!
+//! What it does, and the conditions that bound it:
+//!
+//! - one unauthenticated `GET` to GitHub's public "latest release" endpoint of this repository,
+//!   with a 2 second limit and only the `User-Agent` (`hodeishield-cli/<version>`) and `Accept`
+//!   headers: no API key, token, profile, tenant or machine identifier;
+//! - at most once in 24 hours, remembered in `update-check.json` next to the configuration file
+//!   (the attempt is recorded even when it fails, so a slow network costs the 2 seconds once a day);
+//! - only when standard error is a terminal, the run prints nothing for programs (`--json`,
+//!   `--csv`, `completions`), `CI` is unset, and neither `HODEISHIELD_NO_UPDATE_CHECK` nor
+//!   `update_check = false` in the configuration file opts out;
+//! - the notice is one line on standard error, shown on the run that made the query.
+//!
+//! Two variables exist for the test suite and are not documented to users:
+//! `HODEISHIELD_UPDATE_CHECK_URL` replaces the endpoint (honoured only for a loopback address, so
+//! it can never send the request anywhere else) and `HODEISHIELD_UPDATE_CHECK_ASSUME_TERMINAL`
+//! stands in for a terminal on standard error.
+
+use serde::{Deserialize, Serialize};
+use std::io::IsTerminal;
+use std::path::Path;
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
+use url::Url;
+
+const LATEST_RELEASE: &str =
+    "https://api.github.com/repos/Hodeitek/hodeishield-cli/releases/latest";
+const RELEASES_PAGE: &str = "https://github.com/Hodeitek/hodeishield-cli/releases";
+const INTERVAL_SECS: u64 = 24 * 60 * 60;
+const TIMEOUT: Duration = Duration::from_secs(2);
+const MAX_BODY_BYTES: u64 = 1024 * 1024;
+const CACHE_FILE: &str = "update-check.json";
+
+/// What is remembered between runs.
+#[derive(Debug, Serialize, Deserialize)]
+struct Cache {
+    /// Seconds since the Unix epoch of the last query, successful or not.
+    checked_at: u64,
+    /// The version the last successful query reported.
+    #[serde(default)]
+    latest: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+struct Release {
+    tag_name: String,
+}
+
+/// Prints the new-version notice when it is due and wanted. `for_programs` is true when this run
+/// printed machine-readable output.
+pub fn notify(for_programs: bool, verbose: bool) {
+    let log = |message: &str| {
+        if verbose {
+            eprintln!("update check: {message}");
+        }
+    };
+    if for_programs || !wanted() {
+        return;
+    }
+    let Ok(config_path) = crate::config::path() else {
+        return;
+    };
+    match crate::config::load(&config_path) {
+        Ok(config) if config.update_check != Some(false) => {}
+        _ => return,
+    }
+    let cache_path = config_path.with_file_name(CACHE_FILE);
+    let now = unix_now();
+    if read_cache(&cache_path).is_some_and(|c| now.saturating_sub(c.checked_at) < INTERVAL_SECS) {
+        log("checked less than 24 hours ago");
+        return;
+    }
+    let latest = match fetch_latest() {
+        Ok(version) => Some(version),
+        Err(reason) => {
+            log(&reason);
+            None
+        }
+    };
+    if let Err(e) = write_cache(
+        &cache_path,
+        &Cache {
+            checked_at: now,
+            latest: latest.clone(),
+        },
+    ) {
+        log(&format!("cannot write {}: {e}", cache_path.display()));
+    }
+    if let Some(latest) = latest.filter(|l| is_newer(l, env!("CARGO_PKG_VERSION"))) {
+        eprintln!(
+            "A newer version of hodeishield is available: {latest} (you have {}). See {RELEASES_PAGE}",
+            env!("CARGO_PKG_VERSION")
+        );
+    }
+}
+
+/// Interactive, not CI and not opted out by the environment.
+fn wanted() -> bool {
+    let set = |name: &str| std::env::var_os(name).is_some_and(|v| !v.is_empty());
+    let terminal =
+        std::io::stderr().is_terminal() || set("HODEISHIELD_UPDATE_CHECK_ASSUME_TERMINAL");
+    terminal && std::env::var_os("CI").is_none() && !set("HODEISHIELD_NO_UPDATE_CHECK")
+}
+
+fn endpoint() -> Url {
+    endpoint_for(
+        std::env::var("HODEISHIELD_UPDATE_CHECK_URL")
+            .ok()
+            .as_deref(),
+    )
+}
+
+fn endpoint_for(override_url: Option<&str>) -> Url {
+    override_url
+        .and_then(|v| Url::parse(v).ok())
+        .filter(hodeishield_api::is_loopback_host)
+        .unwrap_or_else(|| Url::parse(LATEST_RELEASE).expect("constant URL"))
+}
+
+fn fetch_latest() -> Result<String, String> {
+    let url = endpoint();
+    let mut builder = reqwest::blocking::Client::builder();
+    if hodeishield_api::is_loopback_host(&url) {
+        builder = builder.no_proxy();
+    }
+    let http = builder
+        .user_agent(format!("hodeishield-cli/{}", env!("CARGO_PKG_VERSION")))
+        .timeout(TIMEOUT)
+        .connect_timeout(TIMEOUT)
+        .redirect(reqwest::redirect::Policy::none())
+        .https_only(!hodeishield_api::is_loopback_host(&url))
+        .build()
+        .map_err(|e| format!("cannot start the HTTP client: {e}"))?;
+    let response = http
+        .get(url)
+        .header("Accept", "application/vnd.github+json")
+        .send()
+        .map_err(|e| format!("request failed: {e}"))?;
+    if !response.status().is_success() {
+        return Err(format!("the answer was HTTP {}", response.status()));
+    }
+    let body = hodeishield_api::read_body(response, MAX_BODY_BYTES).map_err(|e| e.to_string())?;
+    let release: Release = serde_json::from_slice(&body).map_err(|e| format!("bad answer: {e}"))?;
+    parse_version(&release.tag_name)
+        .map(|_| release.tag_name.trim_start_matches('v').to_owned())
+        .ok_or_else(|| "the release tag is not a plain version".to_owned())
+}
+
+/// `1.2.3` or `v1.2.3` as numbers. Pre-releases (`1.2.3-rc.1`) are not versions to announce, so
+/// they are refused; build metadata (`+abc`) is ignored.
+fn parse_version(text: &str) -> Option<(u64, u64, u64)> {
+    let text = text.trim().trim_start_matches('v');
+    let text = text.split('+').next()?;
+    let mut parts = text.split('.');
+    let mut next = || parts.next()?.parse::<u64>().ok();
+    let version = (next()?, next()?, next()?);
+    parts.next().is_none().then_some(version)
+}
+
+fn is_newer(latest: &str, current: &str) -> bool {
+    match (parse_version(latest), parse_version(current)) {
+        (Some(latest), Some(current)) => latest > current,
+        _ => false,
+    }
+}
+
+fn unix_now() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map_or(0, |d| d.as_secs())
+}
+
+fn read_cache(path: &Path) -> Option<Cache> {
+    serde_json::from_slice(&std::fs::read(path).ok()?).ok()
+}
+
+fn write_cache(path: &Path, cache: &Cache) -> std::io::Result<()> {
+    if let Some(dir) = path.parent().filter(|d| !d.as_os_str().is_empty()) {
+        std::fs::create_dir_all(dir)?;
+    }
+    std::fs::write(path, serde_json::to_vec(cache)?)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn versions_compare_as_numbers() {
+        assert!(is_newer("0.10.0", "0.9.9"));
+        assert!(is_newer("v1.0.0", "0.3.0"));
+        assert!(!is_newer("0.3.0", "0.3.0"));
+        assert!(!is_newer("0.2.9", "0.3.0"));
+    }
+
+    #[test]
+    fn only_a_loopback_address_can_replace_the_endpoint() {
+        assert_eq!(endpoint_for(None).as_str(), LATEST_RELEASE);
+        assert_eq!(
+            endpoint_for(Some("https://example.test/latest")).as_str(),
+            LATEST_RELEASE
+        );
+        assert_eq!(
+            endpoint_for(Some("http://127.0.0.1:8080/latest")).as_str(),
+            "http://127.0.0.1:8080/latest"
+        );
+    }
+
+    #[test]
+    fn prereleases_and_junk_are_not_announced() {
+        assert!(!is_newer("0.4.0-rc.1", "0.3.0"));
+        assert!(!is_newer("nightly", "0.3.0"));
+        assert!(!is_newer("0.4", "0.3.0"));
+        assert!(!is_newer("0.4.0.1", "0.3.0"));
+        assert_eq!(parse_version("0.4.0+build5"), Some((0, 4, 0)));
+    }
+}
diff --git a/crates/hodeishield-cli/tests/update_check.rs b/crates/hodeishield-cli/tests/update_check.rs
new file mode 100644
index 0000000..e47e82c
--- /dev/null
+++ b/crates/hodeishield-cli/tests/update_check.rs
@@ -0,0 +1,311 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Hodeitek S.L.
+
+//! The new-version notice: when it appears, when it stays silent, and that it never costs a
+//! command its output or its exit code.
+//!
+//! The release endpoint is a mock on loopback (`HODEISHIELD_UPDATE_CHECK_URL`) and a terminal on
+//! standard error is simulated (`HODEISHIELD_UPDATE_CHECK_ASSUME_TERMINAL`); both exist for these
+//! tests. The binary under test is version 0.x of this workspace, so `v99.0.0` is always newer.
+
+use assert_cmd::Command;
+use mockito::{Mock, Server};
+use std::path::PathBuf;
+use std::process::Output;
+
+const NOTICE: &str = "A newer version of hodeishield is available: 99.0.0";
+
+struct Env {
+    _dir: tempfile::TempDir,
+    config: PathBuf,
+}
+
+impl Env {
+    fn new() -> Self {
+        let dir = tempfile::tempdir().expect("tempdir");
+        let config = dir.path().join("config.toml");
+        Self { _dir: dir, config }
+    }
+
+    fn cache(&self) -> PathBuf {
+        self.config.with_file_name("update-check.json")
+    }
+
+    /// A run that is not on a terminal, so it never asks: for changing the configuration.
+    fn quiet(&self, args: &[&str]) -> Output {
+        Command::cargo_bin("hodeishield")
+            .expect("binary")
+            .env("HODEISHIELD_CONFIG", &self.config)
+            .args(args)
+            .output()
+            .expect("run")
+    }
+
+    /// A run on an interactive terminal, against `release_url`.
+    fn run(&self, release_url: &str, args: &[&str]) -> Output {
+        let mut cmd = Command::cargo_bin("hodeishield").expect("binary");
+        for var in [
+            "CI",
+            "HODEISHIELD_NO_UPDATE_CHECK",
+            "HODEISHIELD_API_KEY",
+            "HODEISHIELD_API_URL",
+            "HODEISHIELD_PROFILE",
+        ] {
+            cmd.env_remove(var);
+        }
+        cmd.env("HODEISHIELD_CONFIG", &self.config)
+            .env("HODEISHIELD_UPDATE_CHECK_URL", release_url)
+            .env("HODEISHIELD_UPDATE_CHECK_ASSUME_TERMINAL", "1")
+            .env("NO_COLOR", "1")
+            .args(args)
+            .output()
+            .expect("run")
+    }
+}
+
+fn release(server: &mut Server, tag: &str) -> Mock {
+    server
+        .mock("GET", "/latest")
+        .match_header(
+            "user-agent",
+            concat!("hodeishield-cli/", env!("CARGO_PKG_VERSION")),
+        )
+        .with_body(format!(r#"{{"tag_name":"{tag}","draft":false}}"#))
+        .create()
+}
+
+fn url(server: &Server) -> String {
+    format!("{}/latest", server.url())
+}
+
+fn stderr(output: &Output) -> String {
+    String::from_utf8_lossy(&output.stderr).into_owned()
+}
+
+fn stdout(output: &Output) -> String {
+    String::from_utf8_lossy(&output.stdout).into_owned()
+}
+
+#[test]
+fn a_newer_release_is_announced_on_stderr_only() {
+    let env = Env::new();
+    let mut server = Server::new();
+    let mock = release(&mut server, "v99.0.0").expect(1).create();
+    let output = env.run(&url(&server), &["config", "path"]);
+    assert!(output.status.success());
+    assert!(stderr(&output).contains(NOTICE), "{}", stderr(&output));
+    assert!(
+        stderr(&output).contains("you have 0."),
+        "{}",
+        stderr(&output)
+    );
+    assert!(!stdout(&output).contains("newer version"));
+    mock.assert();
+}
+
+#[test]
+fn the_same_or_an_older_release_says_nothing() {
+    for tag in [
+        concat!("v", env!("CARGO_PKG_VERSION")),
+        "v0.0.1",
+        "v99.0.0-rc.1",
+    ] {
+        let env = Env::new();
+        let mut server = Server::new();
+        let mock = release(&mut server, tag).expect(1).create();
+        let output = env.run(&url(&server), &["config", "path"]);
+        assert!(output.status.success());
+        assert!(!stderr(&output).contains("newer version"), "{tag}");
+        mock.assert();
+    }
+}
+
+#[test]
+fn it_asks_at_most_once_a_day() {
+    let env = Env::new();
+    let mut server = Server::new();
+    let mock = release(&mut server, "v99.0.0").expect(1).create();
+    let first = env.run(&url(&server), &["config", "path"]);
+    let second = env.run(&url(&server), &["config", "path"]);
+    assert!(stderr(&first).contains(NOTICE));
+    assert!(!stderr(&second).contains("newer version"));
+    mock.assert();
+
+    // A check older than a day is made again.
+    std::fs::write(env.cache(), r#"{"checked_at":1,"latest":"0.1.0"}"#).expect("age the cache");
+    let third = env.run(&url(&server), &["config", "path"]);
+    assert!(stderr(&third).contains(NOTICE));
+}
+
+#[test]
+fn json_and_csv_and_completions_stay_clean_and_make_no_request() {
+    let env = Env::new();
+    let mut server = Server::new();
+    let mock = release(&mut server, "v99.0.0").expect(0).create();
+    let mut api = Server::new();
+    api.mock("GET", mockito::Matcher::Any)
+        .with_header("content-type", "application/json")
+        .with_body(r#"{"data":[],"pagination":{"page":1,"per_page":50,"total":0,"total_pages":0}}"#)
+        .create();
+    let release_url = url(&server);
+    let api_url = api.url();
+    for args in [
+        vec!["--json", "config", "show"],
+        vec!["vendors", "list", "--csv"],
+        vec!["completions", "bash"],
+    ] {
+        let mut cmd_args = vec!["--api-url", api_url.as_str()];
+        cmd_args.extend(&args);
+        let output = {
+            let mut cmd = Command::cargo_bin("hodeishield").expect("binary");
+            cmd.env_remove("CI")
+                .env_remove("HODEISHIELD_NO_UPDATE_CHECK")
+                .env("HODEISHIELD_CONFIG", &env.config)
+                .env("HODEISHIELD_API_KEY", "hsk_test_0123456789abcdef")
+                .env("HODEISHIELD_UPDATE_CHECK_URL", &release_url)
+                .env("HODEISHIELD_UPDATE_CHECK_ASSUME_TERMINAL", "1")
+                .args(&cmd_args)
+                .output()
+                .expect("run")
+        };
+        assert!(output.status.success(), "{args:?}: {}", stderr(&output));
+        assert!(!stderr(&output).contains("newer version"), "{args:?}");
+    }
+    mock.assert();
+}
+
+#[test]
+fn without_a_terminal_ci_or_with_an_opt_out_nothing_is_asked() {
+    let mut server = Server::new();
+    let mock = release(&mut server, "v99.0.0").expect(0).create();
+    let release_url = url(&server);
+
+    // Standard error is not a terminal (the test harness pipes it).
+    let env = Env::new();
+    let output = Command::cargo_bin("hodeishield")
+        .expect("binary")
+        .env_remove("CI")
+        .env_remove("HODEISHIELD_NO_UPDATE_CHECK")
+        .env_remove("HODEISHIELD_UPDATE_CHECK_ASSUME_TERMINAL")
+        .env("HODEISHIELD_CONFIG", &env.config)
+        .env("HODEISHIELD_UPDATE_CHECK_URL", &release_url)
+        .args(["config", "path"])
+        .output()
+        .expect("run");
+    assert!(!stderr(&output).contains("newer version"));
+
+    // CI, with any value.
+    for ci in ["true", "0", "false"] {
+        let env = Env::new();
+        let mut cmd = Command::cargo_bin("hodeishield").expect("binary");
+        let output = cmd
+            .env("HODEISHIELD_CONFIG", &env.config)
+            .env("HODEISHIELD_UPDATE_CHECK_URL", &release_url)
+            .env("HODEISHIELD_UPDATE_CHECK_ASSUME_TERMINAL", "1")
+            .env("CI", ci)
+            .args(["config", "path"])
+            .output()
+            .expect("run");
+        assert!(!stderr(&output).contains("newer version"), "CI={ci}");
+    }
+
+    // The environment opt-out.
+    let env = Env::new();
+    let output = Command::cargo_bin("hodeishield")
+        .expect("binary")
+        .env_remove("CI")
+        .env("HODEISHIELD_CONFIG", &env.config)
+        .env("HODEISHIELD_UPDATE_CHECK_URL", &release_url)
+        .env("HODEISHIELD_UPDATE_CHECK_ASSUME_TERMINAL", "1")
+        .env("HODEISHIELD_NO_UPDATE_CHECK", "1")
+        .args(["config", "path"])
+        .output()
+        .expect("run");
+    assert!(!stderr(&output).contains("newer version"));
+
+    // The configuration opt-out, set the way a user sets it.
+    let env = Env::new();
+    let set = env.quiet(&["config", "set", "update_check", "false"]);
+    assert!(set.status.success(), "{}", stderr(&set));
+    let output = env.run(&release_url, &["config", "path"]);
+    assert!(!stderr(&output).contains("newer version"));
+    let shown = env.quiet(&["--json", "config", "show"]);
+    let shown: serde_json::Value = serde_json::from_slice(&shown.stdout).expect("json");
+    assert_eq!(shown["update_check"], false);
+
+    // Unsetting it brings the default back.
+    env.quiet(&["config", "unset", "update_check"]);
+    let shown = env.quiet(&["--json", "config", "show"]);
+    let shown: serde_json::Value = serde_json::from_slice(&shown.stdout).expect("json");
+    assert_eq!(shown["update_check"], true);
+
+    mock.assert();
+}
+
+#[test]
+fn update_check_must_be_a_boolean() {
+    let env = Env::new();
+    let output = env.run(
+        "http://127.0.0.1:9/",
+        &["config", "set", "update_check", "maybe"],
+    );
+    assert_eq!(output.status.code(), Some(1));
+    assert!(stderr(&output).contains("not true or false"));
+}
+
+#[test]
+fn failures_are_silent_and_do_not_change_the_exit_code() {
+    let mut server = Server::new();
+    let bodies: [(usize, &str); 3] = [
+        (500, "oops"),
+        (200, "not json"),
+        (200, r#"{"tag_name":"nightly"}"#),
+    ];
+    for (status, body) in bodies {
+        let env = Env::new();
+        server.reset();
+        server
+            .mock("GET", "/latest")
+            .with_status(status)
+            .with_body(body)
+            .create();
+        let ok = env.run(&url(&server), &["config", "path"]);
+        assert!(ok.status.success());
+        assert_eq!(stderr(&ok), "");
+        // The failed attempt is remembered, so it is not repeated at once.
+        assert!(env.cache().exists());
+
+        let failing = env.run(&url(&server), &["--profile", "missing", "config", "show"]);
+        assert_eq!(failing.status.code(), Some(1));
+    }
+
+    // Nothing listens: the connection is refused.
+    let env = Env::new();
+    let output = env.run("http://127.0.0.1:9/latest", &["config", "path"]);
+    assert!(output.status.success());
+    assert_eq!(stderr(&output), "");
+}
+
+#[test]
+fn an_unwritable_cache_never_fails_the_command() {
+    let env = Env::new();
+    // A directory where the cache file should be.
+    std::fs::create_dir(env.cache()).expect("dir");
+    let mut server = Server::new();
+    let _mock = release(&mut server, "v99.0.0").create();
+    let output = env.run(&url(&server), &["config", "path"]);
+    assert!(output.status.success());
+}
+
+#[test]
+fn verbose_explains_why_it_stayed_quiet() {
+    let env = Env::new();
+    let mut server = Server::new();
+    server.mock("GET", "/latest").with_status(500).create();
+    let output = env.run(&url(&server), &["--verbose", "config", "path"]);
+    assert!(
+        stderr(&output).contains("update check:"),
+        "{}",
+        stderr(&output)
+    );
+}

From e8766364c489b913e8e3aa4732353a73dbfb7b8e Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Thu, 8 Oct 2026 19:23:37 +0200
Subject: [PATCH 21/57] Explain how the test proxy's checksum was recorded

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 .github/workflows/proxy-tls.yml | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/.github/workflows/proxy-tls.yml b/.github/workflows/proxy-tls.yml
index 3963251..fa89115 100644
--- a/.github/workflows/proxy-tls.yml
+++ b/.github/workflows/proxy-tls.yml
@@ -41,6 +41,10 @@ jobs:
       contents: read
     env:
       # Official Linux release of mitmproxy, pinned by version and checksum. Bumped by hand.
+      # The download site publishes no checksum file, so the SHA-256 is the one of the
+      # release archive as downloaded when it was pinned (trust on first use). mitmproxy
+      # is only a test tool here and is never shipped. When bumping, record the new
+      # archive's SHA-256 the same way.
       MITMPROXY_VERSION: "12.2.3"
       MITMPROXY_SHA256: 2e95286b618fa6fd33e5e62a78c2e5112571d85f42ec2bac29b97ee242bdb5c5
     steps:

From d951088e661b0c37bf7d0db9c4961a6e34b73807 Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Thu, 8 Oct 2026 19:33:52 +0200
Subject: [PATCH 22/57] Propose options for signing in without a keychain

Refs #39

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 CONTRIBUTING.md                               |   5 +
 .../0001-sign-in-without-a-keychain.md        | 156 ++++++++++++++++++
 2 files changed, 161 insertions(+)
 create mode 100644 docs/decisions/0001-sign-in-without-a-keychain.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 788f83e..8c28ddc 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -203,6 +203,11 @@ An issue is closed as soon as the fix reaches `main`, never left open once fixed
   with the reason. A security issue is closed only with evidence that it is fixed or not exploitable.
 - After a merge into `dev`, the issues the pull request mentions get the same review.
 
+## Design decisions
+
+Significant design choices are written up in [docs/decisions](docs/decisions), one numbered
+file each, with a status (Proposed, Accepted, Rejected or Superseded).
+
 ## Security issues
 
 Do not open a public issue: see [SECURITY.md](SECURITY.md).
diff --git a/docs/decisions/0001-sign-in-without-a-keychain.md b/docs/decisions/0001-sign-in-without-a-keychain.md
new file mode 100644
index 0000000..6a3d9d3
--- /dev/null
+++ b/docs/decisions/0001-sign-in-without-a-keychain.md
@@ -0,0 +1,156 @@
+# 0001. Signing in on a machine without a keychain
+
+- Status: Proposed
+- Issue: [#39](https://github.com/Hodeitek/hodeishield-cli/issues/39)
+- Deciders: maintainers
+
+This is a proposal. Nothing here is decided or implemented; the recommendation is the author's.
+
+## Context
+
+`hodeishield login` stores its tokens (an access token and, by default, a refresh token) in the
+system keychain and nowhere else (`crates/hodeishield-cli/src/auth/store.rs:1-6`). On Linux the only
+backend is the Secret Service over D-Bus, through `zbus-secret-service-keyring-store`
+(`crates/hodeishield-cli/Cargo.toml:47-48`, `store.rs:127-131`). There is no kernel keyring (keyutils)
+backend and no file fallback.
+
+On a machine with no Secret Service (an SSH server, a container, WSL without a desktop session, a CI
+runner) this is what happens today:
+
+- The store is first touched when the token is saved (`commands/session.rs:100`), after the whole
+  browser or `--device` flow has finished. The person completes sign-in and consent, then gets
+  "the system keychain is not available" (`store.rs:17,100-110`). The token already issued is not
+  revoked by the CLI, so it stays valid at the app until revoked there.
+- The error points to `HODEISHIELD_API_KEY` (`auth/mod.rs:87-97`); the README says the same
+  (`README.md:294-297`, and for containers `README.md:160-161`).
+- `--device` does not help: it avoids the browser, not the storage.
+
+Who is affected: people who work from a jump host or a remote shell with their own identity (the
+motivating case in the issue: MSSP staff), containers, and CI. A tenant API key works everywhere
+(`auth/mod.rs:38-45`), but it is one more long-lived secret per tenant, it is not tied to a person,
+and someone has to create it.
+
+What is at stake: a sign-in token reads one tenant's supply-chain risk data. The access token is
+short-lived; the refresh token is long-lived and is the sensitive part. The README promises that
+tokens are "never in a file" (`README.md:30`, `cli.rs:103-104`), so any option that writes a file
+changes a documented guarantee.
+
+Existing seam: `TokenStore` (`store.rs:87-93`) has `load`, `save` and `delete` per profile, with a
+test-only `MemoryStore` (`store.rs:185`). The CLI builds the store in one place
+(`commands/mod.rs:83`). A new store is a new implementation of that trait plus a way to choose it.
+
+## Options
+
+### A. Keep keychain-only; document API keys for headless use
+
+Change nothing in behaviour. Improve the experience: refuse early (before opening a browser or
+printing a device code) when no keychain is reachable, and say what to do; expand the README with a
+"servers and containers" recipe.
+
+- Security: best. No new storage, no weaker path. API keys can be scoped to read scopes and rotated.
+- Effort: small (an early check, a message, docs).
+- Consequences: the issue's use case is answered with "request an API key", not with the person's own
+  identity. Per-tenant keys must be issued and tracked by someone.
+
+### B. Linux kernel session keyring (keyutils) as a fallback
+
+Store the payload with `keyctl` in the session or user keyring when no Secret Service is present.
+
+- Security: the secret is kernel memory, never on disk, and not readable by other users. But it is
+  scoped to a keyring, not a person's login: a user keyring is readable by every process of that user;
+  a session keyring is visible only to that session's processes.
+- Lifetime: it does not survive a reboot. A session keyring disappears when the last process of the
+  session ends, so a new SSH connection would be signed out; a user keyring (`@u`) survives
+  across sessions until reboot or key timeout, but with defaults that vary by distribution and
+  container runtime. Containers often block the `keyctl` syscall under the default seccomp profile.
+- Effort: medium. A new backend crate (or direct syscalls), Linux only, behind a selection rule and
+  tests that need a real kernel keyring.
+- Consequences: helps SSH servers somewhat, containers and WSL unreliably. Behaviour (survives or not)
+  would be surprising to users and needs documenting per mode.
+
+### C. Encrypted file store with a passphrase
+
+Write the payload to a file in the config directory, encrypted with a key derived (for example with
+Argon2id) from a passphrase.
+
+- Where the key comes from: a prompt on a terminal, or an environment variable / file descriptor for
+  non-interactive use (for example `HODEISHIELD_PASSPHRASE`).
+- UX: a prompt on every command that needs the token, or a passphrase in the environment, which in
+  practice moves the secret from one place to another. Without a terminal and without the variable
+  the command must fail clearly.
+- Threat model: protects a stolen disk, backup or file copy; does not protect against code running as
+  the same user once the passphrase is in memory or in the environment. A weak passphrase makes the
+  file an offline-guessing target for a long-lived refresh token.
+- Effort: large. New crypto dependencies to vet (`deny.toml`), file format and versioning, prompting,
+  locking against concurrent refreshes, key rotation, tests.
+- Consequences: works in all environments with a terminal; the largest new security surface to own.
+
+### D. Plaintext file with 0600 permissions behind an explicit opt-in
+
+Store the payload in a file in the config directory, mode 0600 in a 0700 directory, only when the
+person opts in (for example `HODEISHIELD_INSECURE_STORAGE=file` or a config key), with a warning on
+every sign-in.
+
+- Security: weakest. Anyone who can read the file (same user, root, backups, a mis-mounted volume, an
+  image layer) holds a refresh token valid until revoked. Permissions do not protect against malware
+  running as the user. This reverses the "never in a file" promise for those who opt in.
+- Effort: small to medium (store, permission checks and refusal if the file is looser than 0600,
+  Windows ACL handling, docs, tests).
+- Consequences: common practice in other CLIs, and it solves every environment, but it normalises the
+  exact exposure the CLI was designed to avoid. Requests to remove the opt-in guard would follow.
+
+### E. No storage: print a token once or keep it in memory for one command
+
+For example `hodeishield login --print-token` runs the flow and prints only the access token, to be
+exported as an environment variable for the session; or the CLI uses the access token only within
+one invocation.
+
+- Security: good if the refresh token is never requested or never stored. The access token is
+  short-lived, so exposure is limited to its lifetime; it can appear in shell history or process
+  environment if handled carelessly.
+- Effort: small to medium. The CLI would need to request no `offline_access` scope, accept an access
+  token from the environment (a new credential source in `auth/mod.rs:38`), and print it safely
+  (stdout only, never with other text).
+- Consequences: no refresh, so the person signs in again when the token expires (the lifetime is set
+  by the app). Fine for a short task on a jump host; poor for unattended jobs, which should use an API
+  key. Interactive device flow from a remote shell is natural here.
+
+### F. Delegate to an external credential helper
+
+The CLI calls a configured program (as some tools do with git or Docker credential helpers) to load
+and save the payload, so people bring their own vault.
+
+- Security: depends on the helper; the CLI never writes a file. The helper's protocol and trust (the
+  program path comes from configuration) become part of the threat model.
+- Effort: medium (protocol, spawn without a shell, error handling, docs). Larger audience needed to
+  justify it.
+
+## Recommendation (the author's, not a decision)
+
+Security first: the refresh token is the asset, and the options that never write it to disk or
+plaintext are A, E, and B. In that order of preference:
+
+1. Do A now, regardless: fail early, before the browser or device code, and document the headless
+   path. This fixes the worst part of the current behaviour (completing sign-in and then failing,
+   leaving an unrevoked token) at almost no risk.
+2. Add E for the jump-host case: a sign-in that requests no refresh token and does not store anything,
+   with the access token handed to the shell explicitly. It keeps personal identity without a stored
+   long-lived secret, and costs one new credential source.
+3. Do not implement D or C unless the maintainers accept new storage risk. If a file is needed
+   anyway, prefer C over D, and only with a design review of the format and the passphrase handling.
+   B is worth a spike only if SSH-server users report that E is not enough.
+
+If the maintainers choose not to add any alternative store, the second acceptance criterion of #39 is
+met by A: the README recommends API keys and explains why.
+
+## Open questions for the maintainers
+
+1. Is "tokens never in a file" a product guarantee to keep, or a default that an opt-in may change?
+2. Can the app issue an access token without a refresh token (no `offline_access`) with a useful
+   lifetime for a jump-host session? What is that lifetime?
+3. Should a person's own sign-in be preferred over per-tenant API keys for MSSP staff, or are API keys
+   an acceptable answer given they can be scoped and rotated?
+4. For containers and CI, is an API key always the intended answer (so options B to D are out of scope
+   there)?
+5. Should the CLI revoke the token it just obtained when it cannot store it (today it does not)?
+6. Which platforms matter most: SSH servers, WSL, containers, CI?

From 676b029d5eba04732bdb98b21ede2474c6eaa5b4 Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Thu, 8 Oct 2026 19:43:15 +0200
Subject: [PATCH 23/57] Refuse to sign in without a token store, and revoke
 tokens that cannot be kept

login now asks the token store whether it can keep a session for the
profile before opening the browser or requesting a device code, and stops
with the existing "system keychain is not available" error otherwise.

If saving still fails after the token exchange, the refresh token and then
the access token are revoked through the same code path as logout, the
notice goes to standard error, and the command exits with the store
error's code. Logout now revokes the refresh token first as well.

Closes #101

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 CHANGELOG.md                                  |   8 +
 README.md                                     |   3 +
 crates/hodeishield-cli/src/auth/store.rs      |  37 +-
 .../hodeishield-cli/src/commands/session.rs   | 378 +++++++++++++++++-
 crates/hodeishield-cli/tests/cli.rs           | 123 ++----
 5 files changed, 440 insertions(+), 109 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 46457e2..bfd688c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,14 @@ commands, `--json` output and exit codes. Each release's notes start with its se
 
 ## [Unreleased]
 
+### Fixed
+
+- `hodeishield login` now checks that the system keychain can keep a session before it opens the
+  browser or shows a device code, and stops there with the usual pointer to API keys. If saving the
+  session still fails after the app has issued tokens, the CLI revokes the refresh token and then
+  the access token, says so on standard error and exits non-zero, instead of leaving an active
+  grant that nothing holds. ([#101](https://github.com/Hodeitek/hodeishield-cli/issues/101))
+
 ### Added
 
 - On an interactive terminal, the CLI now tells you in one line on standard error when a newer
diff --git a/README.md b/README.md
index 8fc8d4b..d022ff6 100644
--- a/README.md
+++ b/README.md
@@ -284,6 +284,9 @@ hodeishield login --profile client-b
 
 A profile that has not been defined is refused (`Profile ... is not defined`).
 
+`login` first checks that the system keychain is available and stops before opening the browser or
+showing a code if it is not; use a tenant API key on such a machine.
+
 With `--device`, open the address the CLI prints on any device and **type the code by hand**: the app
 does not accept a link with the code filled in, on purpose.
 
diff --git a/crates/hodeishield-cli/src/auth/store.rs b/crates/hodeishield-cli/src/auth/store.rs
index e18d83a..fff3abb 100644
--- a/crates/hodeishield-cli/src/auth/store.rs
+++ b/crates/hodeishield-cli/src/auth/store.rs
@@ -89,6 +89,9 @@ pub trait TokenStore {
     fn save(&self, profile: &str, token: &StoredToken) -> Result<()>;
     /// Whether there was something to delete.
     fn delete(&self, profile: &str) -> Result<bool>;
+    /// Whether tokens can be kept for this profile, without writing anything. Sign-in checks it
+    /// before it asks the person to approve anything.
+    fn check_available(&self, profile: &str) -> Result<()>;
 }
 
 /// The system keychain.
@@ -101,13 +104,15 @@ fn ensure_store() -> Result<()> {
     STORE_READY
         .get_or_init(|| native_store().map(keyring_core::set_default_store))
         .clone()
-        .map_err(|reason| {
-            Failure::general(format!("{KEYCHAIN_UNAVAILABLE}: {reason}")).hint(
-                "Sign-in tokens are only kept in the system keychain. On Linux, start a Secret \
-                 Service (GNOME Keyring or KWallet); on a server without one, use a tenant API key \
-                 in HODEISHIELD_API_KEY instead.",
-            )
-        })
+        .map_err(|reason| unavailable(&reason))
+}
+
+fn unavailable(reason: &str) -> Failure {
+    Failure::general(format!("{KEYCHAIN_UNAVAILABLE}: {reason}")).hint(
+        "Sign-in tokens are only kept in the system keychain. On Linux, start a Secret \
+         Service (GNOME Keyring or KWallet); on a server without one, use a tenant API key \
+         in HODEISHIELD_API_KEY instead.",
+    )
 }
 
 #[cfg(target_os = "macos")]
@@ -177,6 +182,20 @@ impl TokenStore for Keychain {
             Err(e) => Err(keychain_failure(e)),
         }
     }
+
+    /// Reads the profile's entry, which proves the backend answers without writing a secret: an
+    /// entry that does not exist, or that cannot be decoded, still means the keychain works.
+    fn check_available(&self, profile: &str) -> Result<()> {
+        match entry(profile)?.get_password() {
+            Err(
+                e @ (keyring_core::Error::PlatformFailure(_)
+                | keyring_core::Error::NoStorageAccess(_)
+                | keyring_core::Error::NoDefaultStore
+                | keyring_core::Error::NotSupportedByStore(_)),
+            ) => Err(unavailable(&e.to_string())),
+            _ => Ok(()),
+        }
+    }
 }
 
 /// In-memory store for tests.
@@ -210,6 +229,10 @@ impl TokenStore for MemoryStore {
             .remove(profile)
             .is_some())
     }
+
+    fn check_available(&self, _profile: &str) -> Result<()> {
+        Ok(())
+    }
 }
 
 #[cfg(test)]
diff --git a/crates/hodeishield-cli/src/commands/session.rs b/crates/hodeishield-cli/src/commands/session.rs
index 59949af..0d377fd 100644
--- a/crates/hodeishield-cli/src/commands/session.rs
+++ b/crates/hodeishield-cli/src/commands/session.rs
@@ -16,7 +16,17 @@ use std::time::{Duration, Instant};
 const BROWSER_TIMEOUT: Duration = Duration::from_secs(5 * 60);
 
 pub fn login(ctx: &Context, args: &LoginArgs) -> Result<()> {
-    let settings = ctx.settings()?;
+    login_with(&ctx.settings()?, ctx.store.as_ref(), args)
+}
+
+fn login_with(
+    settings: &crate::config::Settings,
+    store: &dyn auth::TokenStore,
+    args: &LoginArgs,
+) -> Result<()> {
+    // Before anything is asked of the person or the app: a session that cannot be kept is not
+    // worth approving.
+    store.check_available(&settings.profile)?;
     let client_id = settings.oauth_client_id.clone();
     let issuer = oauth::authorization_server(
         &oauth::http_client(&settings.api_url)?,
@@ -97,7 +107,25 @@ pub fn login(ctx: &Context, args: &LoginArgs) -> Result<()> {
         api_url: settings.api_url.as_str().trim_end_matches('/').to_owned(),
         client_id,
     };
-    ctx.store.save(&settings.profile, &token)?;
+    if let Err(failure) = store.save(&settings.profile, &token) {
+        // The grant exists at the app although nothing holds it: end it before reporting.
+        let revoked = revoke_tokens(
+            &http,
+            &metadata,
+            &token.client_id,
+            &token.access_token,
+            token.refresh_token.as_ref(),
+        );
+        eprintln!("{}", unstored_notice(&revoked));
+        return Err(if failure.hint.is_some() {
+            failure
+        } else {
+            failure.hint(format!(
+                "Use a tenant API key instead: export {}=<key>.",
+                auth::API_KEY_ENV
+            ))
+        });
+    }
     let who = oauth::userinfo(&http, &metadata, &token.access_token)
         .ok()
         .flatten()
@@ -117,6 +145,21 @@ pub fn login(ctx: &Context, args: &LoginArgs) -> Result<()> {
     Ok(())
 }
 
+/// What to tell the person when the session could not be kept, given how revoking it went.
+fn unstored_notice(revoked: &Result<()>) -> String {
+    match revoked {
+        Ok(()) => "The session could not be stored on this machine; the tokens issued for it were \
+                   revoked."
+            .to_owned(),
+        Err(revocation) => format!(
+            "The session could not be stored on this machine, and the app did not confirm \
+             revoking the tokens issued for it ({}). Revoke the CLI's access in the app under \
+             \"Application access\".",
+            clean(&revocation.message)
+        ),
+    }
+}
+
 pub fn logout(ctx: &Context) -> Result<()> {
     logout_with(&ctx.settings()?, ctx.store.as_ref())
 }
@@ -230,24 +273,34 @@ pub fn whoami(ctx: &Context, out: &mut dyn Write) -> Result<()> {
 /// Revokes a stored sign-in at the app that issued it, never at whatever the profile points to
 /// now: the tokens themselves travel in the requests.
 ///
-/// The access token first, then the refresh token, each whatever happened to the other. An access
+/// The refresh token first, then the access token, each whatever happened to the other. An access
 /// token the app no longer knows (one that already expired, say) is not a failure; a refresh token it
 /// does not know, or any other refusal, is reported.
 fn revoke_at_issuer(token: &StoredToken) -> Result<()> {
     let issuer = auth::issuer_url(token)?;
     let http = oauth::http_client(&issuer)?;
     let metadata = oauth::discover(&http, &issuer)?;
-    let access = oauth::revoke(
+    revoke_tokens(
         &http,
         &metadata,
         &token.client_id,
         &token.access_token,
-        "access_token",
-    );
-    let refresh = token
-        .refresh_token
-        .as_ref()
-        .map(|refresh| oauth::revoke(&http, &metadata, &token.client_id, refresh, "refresh_token"));
+        token.refresh_token.as_ref(),
+    )
+}
+
+/// The revocation requests themselves (RFC 7009), refresh token first so it cannot mint another
+/// access token while the first is being ended.
+fn revoke_tokens(
+    http: &reqwest::blocking::Client,
+    metadata: &oauth::Metadata,
+    client_id: &str,
+    access_token: &secrecy::SecretString,
+    refresh_token: Option<&secrecy::SecretString>,
+) -> Result<()> {
+    let refresh = refresh_token
+        .map(|refresh| oauth::revoke(http, metadata, client_id, refresh, "refresh_token"));
+    let access = oauth::revoke(http, metadata, client_id, access_token, "access_token");
     let mut problems = Vec::new();
     if let Err(failure) = access {
         problems.push(failure.message);
@@ -283,6 +336,7 @@ mod tests {
     use super::*;
     use crate::auth::TokenStore;
     use crate::auth::store::MemoryStore;
+    use crate::cli::LoginArgs;
     use crate::config::{ConfigFile, Overrides, resolve_with};
     use secrecy::{ExposeSecret, SecretString};
 
@@ -494,4 +548,308 @@ mod tests {
         issuer.mock("POST", "/revoke").with_status(400).create();
         assert!(revoke_at_issuer(&signed_in(&issuer, None)).is_err());
     }
+
+    /// A store for the sign-in tests: it can be unreachable from the start, or fail on save.
+    struct BrokenStore {
+        available: bool,
+    }
+
+    impl TokenStore for BrokenStore {
+        fn load(&self, _profile: &str) -> Result<Option<StoredToken>> {
+            Ok(None)
+        }
+
+        fn save(&self, _profile: &str, _token: &StoredToken) -> Result<()> {
+            Err(Failure::general("system keychain: cannot write"))
+        }
+
+        fn delete(&self, _profile: &str) -> Result<bool> {
+            Ok(false)
+        }
+
+        fn check_available(&self, _profile: &str) -> Result<()> {
+            if self.available {
+                Ok(())
+            } else {
+                Err(Failure::general(format!(
+                    "{}: no Secret Service",
+                    crate::auth::store::KEYCHAIN_UNAVAILABLE
+                ))
+                .hint("use HODEISHIELD_API_KEY"))
+            }
+        }
+    }
+
+    fn settings_for(
+        api: &mockito::ServerGuard,
+        app: &mockito::ServerGuard,
+    ) -> crate::config::Settings {
+        let app = app.url();
+        let env = |name: &str| (name == "HODEISHIELD_APP_URL").then(|| app.clone());
+        let overrides = Overrides {
+            profile: None,
+            api_url: Some(api.url()),
+        };
+        resolve_with(
+            &ConfigFile::default(),
+            std::path::PathBuf::new(),
+            &overrides,
+            env,
+        )
+        .expect("settings")
+    }
+
+    const DEVICE: LoginArgs = LoginArgs {
+        device: true,
+        no_browser: false,
+    };
+
+    /// An app that offers the device flow, issues `at-new` / `rt-new`, and revokes whatever it is
+    /// asked to; the hints of the revocation requests are recorded in the order they arrive.
+    fn device_app(
+        api: &mut mockito::ServerGuard,
+        app: &mut mockito::ServerGuard,
+    ) -> (
+        std::sync::Arc<std::sync::Mutex<Vec<String>>>,
+        Vec<mockito::Mock>,
+    ) {
+        let revoked = std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
+        let seen = std::sync::Arc::clone(&revoked);
+        let url = app.url();
+        let mocks = vec![
+            api.mock("GET", "/.well-known/oauth-protected-resource")
+                .with_status(404)
+                .create(),
+            app.mock("GET", "/.well-known/oauth-authorization-server")
+                .with_body(
+                    json!({
+                        "issuer": url,
+                        "token_endpoint": format!("{url}/token"),
+                        "device_authorization_endpoint": format!("{url}/device/code"),
+                        "revocation_endpoint": format!("{url}/revoke"),
+                        "scopes_supported": ["offline_access"],
+                    })
+                    .to_string(),
+                )
+                .create(),
+            app.mock("POST", "/device/code")
+                .with_body(
+                    json!({
+                        "device_code": "dc", "user_code": "ABCD-EFGH",
+                        "verification_uri": format!("{url}/device"),
+                        "expires_in": 600, "interval": 1,
+                    })
+                    .to_string(),
+                )
+                .expect(1)
+                .create(),
+            app.mock("POST", "/token")
+                .with_body(
+                    json!({
+                        "access_token": "at-new", "refresh_token": "rt-new",
+                        "token_type": "Bearer", "expires_in": 3600,
+                    })
+                    .to_string(),
+                )
+                .expect(1)
+                .create(),
+            app.mock("POST", "/revoke")
+                .with_body_from_request(move |request| {
+                    let form: Vec<(String, String)> =
+                        url::form_urlencoded::parse(request.body().expect("body"))
+                            .into_owned()
+                            .collect();
+                    let get = |key: &str| {
+                        form.iter()
+                            .find(|(k, _)| k == key)
+                            .map(|(_, v)| v.clone())
+                            .unwrap_or_default()
+                    };
+                    seen.lock().expect("lock").push(format!(
+                        "{}={}",
+                        get("token_type_hint"),
+                        get("token")
+                    ));
+                    Vec::new()
+                })
+                .expect(2)
+                .create(),
+        ];
+        (revoked, mocks)
+    }
+
+    #[test]
+    fn an_unavailable_store_stops_login_before_the_app_is_asked_for_anything() {
+        let mut api = mockito::Server::new();
+        let mut app = mockito::Server::new();
+        let calls: Vec<_> = [&mut api, &mut app]
+            .into_iter()
+            .flat_map(|server| {
+                ["GET", "POST"].map(|method| {
+                    server
+                        .mock(method, mockito::Matcher::Any)
+                        .expect(0)
+                        .create()
+                })
+            })
+            .collect();
+        let settings = settings_for(&api, &app);
+        let err =
+            login_with(&settings, &BrokenStore { available: false }, &DEVICE).expect_err("refused");
+        assert!(
+            err.message
+                .starts_with(crate::auth::store::KEYCHAIN_UNAVAILABLE),
+            "{}",
+            err.message
+        );
+        assert!(err.hint.as_deref().is_some_and(|h| h.contains("API_KEY")));
+        assert_eq!(format!("{:?}", err.kind), "General");
+        for call in &calls {
+            call.assert();
+        }
+    }
+
+    #[test]
+    fn tokens_that_cannot_be_stored_are_revoked_refresh_token_first() {
+        let mut api = mockito::Server::new();
+        let mut app = mockito::Server::new();
+        let (revoked, mocks) = device_app(&mut api, &mut app);
+        let settings = settings_for(&api, &app);
+        let err = login_with(&settings, &BrokenStore { available: true }, &DEVICE)
+            .expect_err("save fails");
+        assert_eq!(err.message, "system keychain: cannot write");
+        assert!(err.hint.as_deref().is_some_and(|h| h.contains("API_KEY")));
+        assert_eq!(
+            *revoked.lock().expect("lock"),
+            ["refresh_token=rt-new", "access_token=at-new"]
+        );
+        for mock in &mocks {
+            mock.assert();
+        }
+        // Nothing the person sees carries a token.
+        let notice = unstored_notice(&Ok(()));
+        assert!(notice.contains("revoked"), "{notice}");
+        let all = format!("{err:?} {notice}");
+        assert!(!all.contains("-new"), "{all}");
+    }
+
+    #[test]
+    fn the_notice_for_unrevoked_tokens_points_to_the_app() {
+        let notice = unstored_notice(&Err(Failure::general("the app refused to revoke")));
+        assert!(
+            notice.contains("did not confirm") && notice.contains("Application access"),
+            "{notice}"
+        );
+    }
+
+    #[test]
+    fn a_store_that_works_keeps_the_session_and_revokes_nothing() {
+        let mut api = mockito::Server::new();
+        let mut app = mockito::Server::new();
+        let (revoked, mocks) = device_app(&mut api, &mut app);
+        let settings = settings_for(&api, &app);
+        let store = MemoryStore::default();
+        login_with(&settings, &store, &DEVICE).expect("signed in");
+        let kept = store.load("default").expect("load").expect("stored");
+        assert_eq!(kept.access_token.expose_secret(), "at-new");
+        assert!(revoked.lock().expect("lock").is_empty());
+        // The revocation mock is the last one: it was never reached.
+        for mock in &mocks[..4] {
+            mock.assert();
+        }
+    }
+
+    #[test]
+    fn login_finds_the_sign_in_server_through_the_api_and_asks_for_the_scopes_it_needs() {
+        let mut api = mockito::Server::new();
+        let mut app = mockito::Server::new();
+        let issuer = format!("{}/api/auth", app.url());
+        let resource = api
+            .mock("GET", "/.well-known/oauth-protected-resource")
+            .with_body(
+                json!({ "resource": api.url(), "authorization_servers": [issuer] }).to_string(),
+            )
+            .expect(1)
+            .create();
+        // RFC 8414 §3.1: the issuer's path goes after the well-known segment.
+        app.mock("GET", "/.well-known/oauth-authorization-server/api/auth")
+            .with_body(
+                json!({
+                    "issuer": issuer,
+                    "token_endpoint": format!("{issuer}/oauth2/token"),
+                    "device_authorization_endpoint": format!("{issuer}/device/code"),
+                    "scopes_supported": ["supply_risk:read", "compliance.nis2:read", "radar:read", "offline_access"],
+                })
+                .to_string(),
+            )
+            .create();
+        let device = app
+            .mock("POST", "/api/auth/device/code")
+            .match_body(mockito::Matcher::AllOf(vec![
+                mockito::Matcher::UrlEncoded("client_id".into(), "hodeishield-cli".into()),
+                mockito::Matcher::UrlEncoded(
+                    "scope".into(),
+                    "supply_risk:read compliance.nis2:read offline_access".into(),
+                ),
+            ]))
+            .with_body(
+                json!({
+                    "device_code": "dc", "user_code": "ABCD-EFGH",
+                    "verification_uri": format!("{}/device", app.url()),
+                    "expires_in": 600, "interval": 1,
+                })
+                .to_string(),
+            )
+            .expect(1)
+            .create();
+        // Denied at the end, so nothing is stored.
+        let token = app
+            .mock("POST", "/api/auth/oauth2/token")
+            .match_body(mockito::Matcher::UrlEncoded(
+                "client_id".into(),
+                "hodeishield-cli".into(),
+            ))
+            .with_status(400)
+            .with_body(r#"{"error":"access_denied"}"#)
+            .expect(1)
+            .create();
+        let settings = settings_for(&api, &app);
+        let store = MemoryStore::default();
+        let err = login_with(&settings, &store, &DEVICE).expect_err("denied");
+        assert!(err.message.contains("denied"), "{}", err.message);
+        assert_eq!(
+            err.kind.exit_code(),
+            crate::failure::Kind::NotAuthenticated.exit_code()
+        );
+        assert!(store.load("default").expect("load").is_none());
+        resource.assert();
+        device.assert();
+        token.assert();
+    }
+
+    #[test]
+    fn login_says_clearly_when_the_app_does_not_offer_it() {
+        let mut api = mockito::Server::new();
+        let mut app = mockito::Server::new();
+        api.mock("GET", "/.well-known/oauth-protected-resource")
+            .with_status(404)
+            .create();
+        app.mock("GET", mockito::Matcher::Regex("^/.well-known/".into()))
+            .with_status(404)
+            .expect(2)
+            .create();
+        let settings = settings_for(&api, &app);
+        let err = login_with(&settings, &MemoryStore::default(), &DEVICE).expect_err("none");
+        assert!(
+            err.message
+                .contains("does not offer sign-in for the CLI yet"),
+            "{}",
+            err.message
+        );
+        assert!(
+            err.hint
+                .as_deref()
+                .is_some_and(|h| h.contains("HODEISHIELD_API_KEY"))
+        );
+    }
 }
diff --git a/crates/hodeishield-cli/tests/cli.rs b/crates/hodeishield-cli/tests/cli.rs
index 067b172..ac8dba4 100644
--- a/crates/hodeishield-cli/tests/cli.rs
+++ b/crates/hodeishield-cli/tests/cli.rs
@@ -382,100 +382,39 @@ fn config_profiles_round_trip() {
     assert!(text.contains("default_profile = \"staging\""), "{text}");
 }
 
+/// Without a reachable Secret Service (as in every test here) signing in is refused before the app
+/// is asked for anything. Only on Linux: elsewhere the real keychain would be consulted.
+#[cfg(all(unix, not(target_os = "macos")))]
 #[test]
-fn login_finds_the_sign_in_server_through_the_api_and_asks_for_the_scopes_it_needs() {
-    let env = Env::new();
-    let mut api = mockito::Server::new();
-    let mut app = mockito::Server::new();
-    let issuer = format!("{}/api/auth", app.url());
-    let resource = api
-        .mock("GET", "/.well-known/oauth-protected-resource")
-        .with_body(
-            serde_json::json!({ "resource": api.url(), "authorization_servers": [issuer] })
-                .to_string(),
-        )
-        .expect(1)
-        .create();
-    // RFC 8414 §3.1: the issuer's path goes after the well-known segment.
-    app.mock("GET", "/.well-known/oauth-authorization-server/api/auth")
-        .with_body(
-            serde_json::json!({
-                "issuer": issuer,
-                "token_endpoint": format!("{issuer}/oauth2/token"),
-                "device_authorization_endpoint": format!("{issuer}/device/code"),
-                "scopes_supported": ["supply_risk:read", "compliance.nis2:read", "radar:read", "offline_access"],
-            })
-            .to_string(),
-        )
-        .create();
-    let device = app
-        .mock("POST", "/api/auth/device/code")
-        .match_body(mockito::Matcher::AllOf(vec![
-            mockito::Matcher::UrlEncoded("client_id".into(), "hodeishield-cli".into()),
-            mockito::Matcher::UrlEncoded(
-                "scope".into(),
-                "supply_risk:read compliance.nis2:read offline_access".into(),
-            ),
-        ]))
-        .with_body(
-            serde_json::json!({
-                "device_code": "dc",
-                "user_code": "ABCD-EFGH",
-                "verification_uri": format!("{}/device", app.url()),
-                "expires_in": 600,
-                "interval": 1,
+fn login_is_refused_up_front_when_there_is_no_keychain_to_keep_the_session_in() {
+    for args in [&["login"][..], &["login", "--device"][..]] {
+        let env = Env::new();
+        let mut api = mockito::Server::new();
+        let mut app = mockito::Server::new();
+        let untouched: Vec<_> = [&mut api, &mut app]
+            .into_iter()
+            .flat_map(|server| {
+                ["GET", "POST"].map(|method| {
+                    server
+                        .mock(method, mockito::Matcher::Any)
+                        .expect(0)
+                        .create()
+                })
             })
-            .to_string(),
-        )
-        .expect(1)
-        .create();
-    // Denied at the end, so no token exists to store: on macOS and Windows the test would otherwise
-    // write to the machine's real keychain.
-    let token = app
-        .mock("POST", "/api/auth/oauth2/token")
-        .match_body(mockito::Matcher::UrlEncoded(
-            "client_id".into(),
-            "hodeishield-cli".into(),
-        ))
-        .with_status(400)
-        .with_body(r#"{"error":"access_denied"}"#)
-        .expect(1)
-        .create();
-    env.cmd()
-        .env("HODEISHIELD_API_URL", api.url())
-        .env("HODEISHIELD_APP_URL", app.url())
-        .args(["login", "--device"])
-        .assert()
-        .code(3)
-        .stderr(predicate::str::contains("ABCD-EFGH"))
-        .stderr(predicate::str::contains("denied"));
-    resource.assert();
-    device.assert();
-    token.assert();
-}
-
-#[test]
-fn login_says_clearly_when_the_app_does_not_offer_it() {
-    let env = Env::new();
-    let mut api = mockito::Server::new();
-    let mut app = mockito::Server::new();
-    api.mock("GET", "/.well-known/oauth-protected-resource")
-        .with_status(404)
-        .create();
-    app.mock("GET", mockito::Matcher::Regex("^/.well-known/".into()))
-        .with_status(404)
-        .expect(2)
-        .create();
-    env.cmd()
-        .env("HODEISHIELD_API_URL", api.url())
-        .env("HODEISHIELD_APP_URL", app.url())
-        .args(["login", "--device"])
-        .assert()
-        .code(1)
-        .stderr(predicate::str::contains(
-            "does not offer sign-in for the CLI yet",
-        ))
-        .stderr(predicate::str::contains("HODEISHIELD_API_KEY"));
+            .collect();
+        env.cmd()
+            .env("HODEISHIELD_API_URL", api.url())
+            .env("HODEISHIELD_APP_URL", app.url())
+            .args(args)
+            .assert()
+            .code(1)
+            .stdout(predicate::str::is_empty())
+            .stderr(predicate::str::contains("system keychain is not available"))
+            .stderr(predicate::str::contains("HODEISHIELD_API_KEY"));
+        for mock in &untouched {
+            mock.assert();
+        }
+    }
 }
 
 #[test]

From a4d0918e7f87a221b10e3ee1d360a296ba29f91b Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Thu, 8 Oct 2026 19:54:29 +0200
Subject: [PATCH 24/57] Polish the messages when sign-in cannot store or revoke
 tokens

Name the keychain for the current system in the unavailable hint, report a missing revocation endpoint once and in request order, document why the availability check reads the entry, and cover a failed revocation and the error kind in tests.

Refs #101

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 CHANGELOG.md                                  |  3 +-
 crates/hodeishield-cli/src/auth/store.rs      | 27 +++++--
 .../hodeishield-cli/src/commands/session.rs   | 78 +++++++++++++++++--
 3 files changed, 94 insertions(+), 14 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index bfd688c..aee7b7a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,7 +12,8 @@ commands, `--json` output and exit codes. Each release's notes start with its se
   browser or shows a device code, and stops there with the usual pointer to API keys. If saving the
   session still fails after the app has issued tokens, the CLI revokes the refresh token and then
   the access token, says so on standard error and exits non-zero, instead of leaving an active
-  grant that nothing holds. ([#101](https://github.com/Hodeitek/hodeishield-cli/issues/101))
+  grant that nothing holds. The hint for a missing keychain now names the one for your system
+  (Secret Service, the Keychain prompt, or Credential Manager). ([#101](https://github.com/Hodeitek/hodeishield-cli/issues/101))
 
 ### Added
 
diff --git a/crates/hodeishield-cli/src/auth/store.rs b/crates/hodeishield-cli/src/auth/store.rs
index fff3abb..ae1cace 100644
--- a/crates/hodeishield-cli/src/auth/store.rs
+++ b/crates/hodeishield-cli/src/auth/store.rs
@@ -108,11 +108,23 @@ fn ensure_store() -> Result<()> {
 }
 
 fn unavailable(reason: &str) -> Failure {
-    Failure::general(format!("{KEYCHAIN_UNAVAILABLE}: {reason}")).hint(
-        "Sign-in tokens are only kept in the system keychain. On Linux, start a Secret \
-         Service (GNOME Keyring or KWallet); on a server without one, use a tenant API key \
-         in HODEISHIELD_API_KEY instead.",
-    )
+    Failure::general(format!("{KEYCHAIN_UNAVAILABLE}: {reason}")).hint(unavailable_hint())
+}
+
+/// What to do about a missing keychain, for the platform this build runs on.
+fn unavailable_hint() -> &'static str {
+    if cfg!(target_os = "macos") {
+        "Sign-in tokens are only kept in the system keychain. Allow access when the Keychain \
+         prompt appears (or in Keychain Access), or use a tenant API key in HODEISHIELD_API_KEY \
+         instead."
+    } else if cfg!(windows) {
+        "Sign-in tokens are only kept in the system keychain. Check that Windows Credential \
+         Manager is available, or use a tenant API key in HODEISHIELD_API_KEY instead."
+    } else {
+        "Sign-in tokens are only kept in the system keychain. Start a Secret Service \
+         (GNOME Keyring or KWallet); on a server without one, use a tenant API key in \
+         HODEISHIELD_API_KEY instead."
+    }
 }
 
 #[cfg(target_os = "macos")]
@@ -185,6 +197,11 @@ impl TokenStore for Keychain {
 
     /// Reads the profile's entry, which proves the backend answers without writing a secret: an
     /// entry that does not exist, or that cannot be decoded, still means the keychain works.
+    ///
+    /// Reading the stored entry and discarding it is deliberate: keyring-core 1.0 has no cheaper
+    /// probe that works everywhere. `get_attributes` is not implemented on macOS, and treating
+    /// `NotSupportedByStore` as unavailable would lock macOS users out. The value is dropped
+    /// at once; `zeroize` is not a direct dependency and is not added for this.
     fn check_available(&self, profile: &str) -> Result<()> {
         match entry(profile)?.get_password() {
             Err(
diff --git a/crates/hodeishield-cli/src/commands/session.rs b/crates/hodeishield-cli/src/commands/session.rs
index 0d377fd..3ab1bf0 100644
--- a/crates/hodeishield-cli/src/commands/session.rs
+++ b/crates/hodeishield-cli/src/commands/session.rs
@@ -301,15 +301,22 @@ fn revoke_tokens(
     let refresh = refresh_token
         .map(|refresh| oauth::revoke(http, metadata, client_id, refresh, "refresh_token"));
     let access = oauth::revoke(http, metadata, client_id, access_token, "access_token");
-    let mut problems = Vec::new();
-    if let Err(failure) = access {
-        problems.push(failure.message);
-    }
+    // In request order (refresh token, then access token); the same text twice is said once, which
+    // is what a missing revocation endpoint produces.
+    let mut problems: Vec<String> = Vec::new();
+    let mut report = |problem: String| {
+        if !problems.contains(&problem) {
+            problems.push(problem);
+        }
+    };
     match refresh {
-        Some(Ok(Revocation::Unknown(detail))) => problems.push(detail),
-        Some(Err(failure)) => problems.push(failure.message),
+        Some(Ok(Revocation::Unknown(detail))) => report(detail),
+        Some(Err(failure)) => report(failure.message),
         Some(Ok(Revocation::Revoked)) | None => {}
     }
+    if let Err(failure) = access {
+        report(failure.message);
+    }
     if problems.is_empty() {
         Ok(())
     } else {
@@ -549,6 +556,30 @@ mod tests {
         assert!(revoke_at_issuer(&signed_in(&issuer, None)).is_err());
     }
 
+    #[test]
+    fn a_missing_revocation_endpoint_is_reported_once_in_request_order() {
+        let mut issuer = mockito::Server::new();
+        issuer
+            .mock("GET", "/.well-known/oauth-authorization-server")
+            .with_body(
+                json!({
+                    "issuer": issuer.url(),
+                    "token_endpoint": format!("{}/token", issuer.url()),
+                })
+                .to_string(),
+            )
+            .create();
+        let err = revoke_at_issuer(&signed_in(&issuer, Some("rt"))).expect_err("no endpoint");
+        assert_eq!(err.message, "The app does not offer token revocation.");
+
+        // Different problems keep the order of the requests: refresh token first.
+        let issuer = revocation_server(500, 500);
+        let err = revoke_at_issuer(&signed_in(&issuer, Some("rt"))).expect_err("refused");
+        let refresh = err.message.find("refresh token").expect("refresh");
+        let access = err.message.find("access token").expect("access");
+        assert!(refresh < access, "{}", err.message);
+    }
+
     /// A store for the sign-in tests: it can be unreachable from the start, or fail on save.
     struct BrokenStore {
         available: bool,
@@ -609,6 +640,7 @@ mod tests {
     fn device_app(
         api: &mut mockito::ServerGuard,
         app: &mut mockito::ServerGuard,
+        revoke_status: usize,
     ) -> (
         std::sync::Arc<std::sync::Mutex<Vec<String>>>,
         Vec<mockito::Mock>,
@@ -672,6 +704,7 @@ mod tests {
                     ));
                     Vec::new()
                 })
+                .with_status(revoke_status)
                 .expect(2)
                 .create(),
         ];
@@ -713,7 +746,7 @@ mod tests {
     fn tokens_that_cannot_be_stored_are_revoked_refresh_token_first() {
         let mut api = mockito::Server::new();
         let mut app = mockito::Server::new();
-        let (revoked, mocks) = device_app(&mut api, &mut app);
+        let (revoked, mocks) = device_app(&mut api, &mut app, 200);
         let settings = settings_for(&api, &app);
         let err = login_with(&settings, &BrokenStore { available: true }, &DEVICE)
             .expect_err("save fails");
@@ -733,6 +766,34 @@ mod tests {
         assert!(!all.contains("-new"), "{all}");
     }
 
+    #[test]
+    fn a_failed_revocation_is_said_without_showing_any_token() {
+        let mut api = mockito::Server::new();
+        let mut app = mockito::Server::new();
+        let (revoked, mocks) = device_app(&mut api, &mut app, 500);
+        let settings = settings_for(&api, &app);
+        let err = login_with(&settings, &BrokenStore { available: true }, &DEVICE)
+            .expect_err("save fails");
+        assert_eq!(err.message, "system keychain: cannot write");
+        assert_eq!(revoked.lock().expect("lock").len(), 2);
+        for mock in &mocks {
+            mock.assert();
+        }
+        // The notice login prints is built from the same revocation result.
+        let token = StoredToken {
+            access_token: SecretString::from("at-new"),
+            refresh_token: Some(SecretString::from("rt-new")),
+            ..signed_in(&app, None)
+        };
+        let revocation = revoke_at_issuer(&token).expect_err("the app answered 500");
+        let notice = unstored_notice(&Err(revocation));
+        assert!(notice.contains("did not confirm"), "{notice}");
+        let all = format!("{err:?} {} {notice}", err.message);
+        for secret in ["at-new", "rt-new"] {
+            assert!(!all.contains(secret), "{all}");
+        }
+    }
+
     #[test]
     fn the_notice_for_unrevoked_tokens_points_to_the_app() {
         let notice = unstored_notice(&Err(Failure::general("the app refused to revoke")));
@@ -746,7 +807,7 @@ mod tests {
     fn a_store_that_works_keeps_the_session_and_revokes_nothing() {
         let mut api = mockito::Server::new();
         let mut app = mockito::Server::new();
-        let (revoked, mocks) = device_app(&mut api, &mut app);
+        let (revoked, mocks) = device_app(&mut api, &mut app, 200);
         let settings = settings_for(&api, &app);
         let store = MemoryStore::default();
         login_with(&settings, &store, &DEVICE).expect("signed in");
@@ -851,5 +912,6 @@ mod tests {
                 .as_deref()
                 .is_some_and(|h| h.contains("HODEISHIELD_API_KEY"))
         );
+        assert_eq!(err.kind, crate::failure::Kind::General);
     }
 }

From 41e8c93663ec71b6fa50bec2daf58499cc930b9d Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Sat, 10 Oct 2026 17:56:31 +0200
Subject: [PATCH 25/57] Decide a closed pipe on the I/O error kind, not on
 message text

The exit-0 path for `hodeishield ... | head -1` matched any failure whose
message contained "Broken pipe". Messages can carry text supplied by the
API, so an error response with that text made a failed command exit 0.

Failure now carries a flag that is set only when an I/O error of kind
BrokenPipe is converted into a failure, which is what a failed write to
standard output produces. Nothing built from message text can set it.

Closes #105

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 CHANGELOG.md                          |  4 ++
 crates/hodeishield-cli/src/failure.rs | 29 +++++++++++-
 crates/hodeishield-cli/src/lib.rs     |  3 +-
 crates/hodeishield-cli/tests/cli.rs   | 63 +++++++++++++++++++++++++++
 4 files changed, 97 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index aee7b7a..852e796 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,10 @@ commands, `--json` output and exit codes. Each release's notes start with its se
   the access token, says so on standard error and exits non-zero, instead of leaving an active
   grant that nothing holds. The hint for a missing keychain now names the one for your system
   (Secret Service, the Keychain prompt, or Credential Manager). ([#101](https://github.com/Hodeitek/hodeishield-cli/issues/101))
+- A failed command no longer exits 0 when the API's error message happens to contain the words
+  "Broken pipe". The CLI now treats a failure as a closed output pipe (`hodeishield ... | head -1`,
+  which still exits 0 silently) only when writing to standard output fails with that I/O error,
+  never because of the text of a message. ([#105](https://github.com/Hodeitek/hodeishield-cli/issues/105))
 
 ### Added
 
diff --git a/crates/hodeishield-cli/src/failure.rs b/crates/hodeishield-cli/src/failure.rs
index a3c0bda..11bf927 100644
--- a/crates/hodeishield-cli/src/failure.rs
+++ b/crates/hodeishield-cli/src/failure.rs
@@ -48,6 +48,12 @@ pub struct Failure {
     pub message: String,
     pub hint: Option<String>,
     pub request_id: Option<String>,
+    /// Whether this failure came from an I/O error of kind [`std::io::ErrorKind::BrokenPipe`]
+    /// (the reader went away: `hodeishield ... | head -1`). It is set in one place, the conversion
+    /// from [`std::io::Error`], and never from message text, which can come from the API. It only
+    /// means "output pipe closed" because the commands write to standard output with `?` on
+    /// `io::Error` and nothing else does; keep it that way.
+    pub closed_pipe: bool,
 }
 
 impl Failure {
@@ -57,6 +63,7 @@ impl Failure {
             message: message.into(),
             hint: None,
             request_id: None,
+            closed_pipe: false,
         }
     }
 
@@ -79,7 +86,9 @@ impl fmt::Display for Failure {
 
 impl From<std::io::Error> for Failure {
     fn from(error: std::io::Error) -> Self {
-        Self::general(error.to_string())
+        let mut failure = Self::general(error.to_string());
+        failure.closed_pipe = error.kind() == std::io::ErrorKind::BrokenPipe;
+        failure
     }
 }
 
@@ -231,3 +240,21 @@ impl ApiContext<'_> {
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::io::{Error, ErrorKind};
+
+    #[test]
+    fn only_a_broken_pipe_io_error_marks_a_closed_pipe() {
+        assert!(Failure::from(Error::from(ErrorKind::BrokenPipe)).closed_pipe);
+        assert!(!Failure::from(Error::from(ErrorKind::NotFound)).closed_pipe);
+    }
+
+    #[test]
+    fn message_text_never_marks_a_closed_pipe() {
+        assert!(!Failure::general("Broken pipe").closed_pipe);
+        assert!(!Failure::from(Error::other("Broken pipe")).closed_pipe);
+    }
+}
diff --git a/crates/hodeishield-cli/src/lib.rs b/crates/hodeishield-cli/src/lib.rs
index 1b30b98..d370d59 100644
--- a/crates/hodeishield-cli/src/lib.rs
+++ b/crates/hodeishield-cli/src/lib.rs
@@ -47,7 +47,8 @@ pub fn main() -> ExitCode {
                 ExitCode::FAILURE
             }
         },
-        Err(failure) if failure.message.contains("Broken pipe") => ExitCode::SUCCESS,
+        // Decided on the I/O error kind, never on message text, which can come from the API.
+        Err(failure) if failure.closed_pipe => ExitCode::SUCCESS,
         Err(failure) => {
             // Messages can carry text from the API or the app: clean it like any other output.
             eprintln!("error: {}", output::clean(&failure.message));
diff --git a/crates/hodeishield-cli/tests/cli.rs b/crates/hodeishield-cli/tests/cli.rs
index ac8dba4..18a8fe6 100644
--- a/crates/hodeishield-cli/tests/cli.rs
+++ b/crates/hodeishield-cli/tests/cli.rs
@@ -183,6 +183,69 @@ fn a_missing_scope_exits_4_and_names_the_framework_scope() {
         .stderr(predicate::str::contains("request id: req_abc"));
 }
 
+#[test]
+fn an_api_message_that_says_broken_pipe_still_fails() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/risks/r1")
+        .with_status(404)
+        .with_body(
+            r#"{"error":{"code":"not_found","message":"Broken pipe","request_id":"req_bp"}}"#,
+        )
+        .create();
+    env.api(&server)
+        .args(["risks", "get", "r1"])
+        .assert()
+        .code(5)
+        .stderr(predicate::str::contains("error: Broken pipe"));
+}
+
+/// Unix only: the child gets a plain pipe and sees `EPIPE` once the reader is gone. Windows reports
+/// a closed pipe with other codes, and this suite cannot confirm that mapping there.
+#[cfg(unix)]
+#[test]
+fn a_closed_output_pipe_exits_0_silently() {
+    use std::io::Read;
+    use std::process::{Command, Stdio};
+
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    let filler = "x".repeat(1000);
+    let items: Vec<String> = (0..1000)
+        .map(|i| vendor(&format!("v{i}"), &filler))
+        .collect();
+    server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .with_status(200)
+        .with_body(page(&items, 1, 1000, 1))
+        .create();
+    let mut child = Command::new(assert_cmd::cargo::cargo_bin("hodeishield"))
+        .args(["--json", "vendors", "list"])
+        .env_clear()
+        .env("HODEISHIELD_CONFIG", &env.config)
+        .env(
+            "DBUS_SESSION_BUS_ADDRESS",
+            "unix:path=/nonexistent/hodeishield-test",
+        )
+        .env("HODEISHIELD_API_KEY", KEY)
+        .env("HODEISHIELD_API_URL", server.url())
+        .env("NO_COLOR", "1")
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .spawn()
+        .expect("spawn");
+    // Read a little, then hang up while about a megabyte is still to come.
+    let mut stdout = child.stdout.take().expect("stdout");
+    let mut first = [0_u8; 16];
+    stdout.read_exact(&mut first).expect("first bytes");
+    drop(stdout);
+    let output = child.wait_with_output().expect("wait");
+    assert_eq!(output.status.code(), Some(0), "{output:?}");
+    assert!(output.stderr.is_empty(), "{output:?}");
+}
+
 #[test]
 fn an_inactive_licence_exits_8_without_blaming_a_scope() {
     let env = Env::new();

From 14a0204172fc38583c4c5edc61adb7b6ca930b10 Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Sat, 10 Oct 2026 17:57:20 +0200
Subject: [PATCH 26/57] Limit how long one local connection can hold the
 sign-in listener

The loopback listener serves one connection at a time and only checked
the overall sign-in deadline between connections. Each read had a five
second timeout, but nothing bounded the connection as a whole, so a
local process sending a byte every few seconds could keep it busy
indefinitely while the real redirect waited and the timeout never fired.

Each connection now has a total deadline for its request head, and every
read waits for the shortest of the per-read timeout, the time left on
that deadline and the time left on the overall sign-in deadline. The
state check, path handling, size cap and single use are unchanged. The
limits are held in a struct so tests can shorten them.

Closes #104

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 CHANGELOG.md                                |   6 +
 crates/hodeishield-cli/src/auth/loopback.rs | 234 ++++++++++++++++++--
 2 files changed, 222 insertions(+), 18 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 852e796..0dec299 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,6 +18,12 @@ commands, `--json` output and exit codes. Each release's notes start with its se
   "Broken pipe". The CLI now treats a failure as a closed output pipe (`hodeishield ... | head -1`,
   which still exits 0 silently) only when writing to standard output fails with that I/O error,
   never because of the text of a message. ([#105](https://github.com/Hodeitek/hodeishield-cli/issues/105))
+- A stalled or slow local connection can no longer keep the browser sign-in listener busy past its
+  timeout. Each connection now has a total time limit for its request, and no read waits beyond the
+  overall sign-in deadline, and the deadline is checked before every connection is accepted, so a
+  process sending a byte every few seconds, or connecting over and over, cannot block the real
+  redirect or stop `hodeishield login` from timing out. A client that resets its connection before
+  it is accepted no longer ends the sign-in. ([#104](https://github.com/Hodeitek/hodeishield-cli/issues/104))
 
 ### Added
 
diff --git a/crates/hodeishield-cli/src/auth/loopback.rs b/crates/hodeishield-cli/src/auth/loopback.rs
index d0a14be..c34dcd0 100644
--- a/crates/hodeishield-cli/src/auth/loopback.rs
+++ b/crates/hodeishield-cli/src/auth/loopback.rs
@@ -15,10 +15,33 @@ use std::time::{Duration, Instant};
 
 const CALLBACK_PATH: &str = "/callback";
 
+/// The most a single read may wait for the next bytes of a request.
+const READ_TIMEOUT: Duration = Duration::from_secs(5);
+/// The most a single connection may take to deliver its whole request head. The listener serves one
+/// connection at a time, so this bounds how long a stalled or trickling client can hold it.
+const CONNECTION_DEADLINE: Duration = Duration::from_secs(10);
+
+/// How long the listener waits on one connection. Injectable so tests need not sleep for seconds.
+#[derive(Debug, Clone, Copy)]
+struct Limits {
+    read: Duration,
+    connection: Duration,
+}
+
+impl Default for Limits {
+    fn default() -> Self {
+        Self {
+            read: READ_TIMEOUT,
+            connection: CONNECTION_DEADLINE,
+        }
+    }
+}
+
 #[derive(Debug)]
 pub struct Loopback {
     listener: TcpListener,
     redirect_uri: String,
+    limits: Limits,
 }
 
 /// What the browser brought back.
@@ -40,6 +63,7 @@ impl Loopback {
         Ok(Self {
             listener,
             redirect_uri: format!("http://127.0.0.1:{port}{CALLBACK_PATH}"),
+            limits: Limits::default(),
         })
     }
 
@@ -59,38 +83,79 @@ impl Loopback {
     ) -> Result<Callback> {
         let deadline = Instant::now() + timeout;
         loop {
+            // Checked before every accept, not only when idle: a client that keeps connecting keeps
+            // the queue full, and must not be able to postpone the timeout.
+            let left = deadline.saturating_duration_since(Instant::now());
+            if left.is_zero() {
+                return Err(timed_out());
+            }
             match self.listener.accept() {
                 Ok((stream, _)) => {
-                    if let Some(result) = handle(stream, state, issuer, require_iss) {
+                    let request = Request {
+                        state,
+                        issuer,
+                        require_iss,
+                        limits: self.limits,
+                        deadline,
+                    };
+                    if let Some(result) = handle(stream, &request) {
                         return result;
                     }
                 }
                 Err(e) if e.kind() == std::io::ErrorKind::WouldBlock => {
-                    if Instant::now() >= deadline {
-                        return Err(Failure::new(
-                            Kind::NotAuthenticated,
-                            "Timed out waiting for the browser to finish signing in.",
-                        )
-                        .hint("Run `hodeishield login` again, or `hodeishield login --device`."));
-                    }
-                    std::thread::sleep(Duration::from_millis(100));
+                    std::thread::sleep(Duration::from_millis(100).min(left));
                 }
+                // A client that reset before we accepted it (reported on macOS, the BSDs and
+                // Windows) is not the end of the sign-in.
+                Err(e) if is_aborted_connection(e.kind()) => {}
                 Err(e) => return Err(e.into()),
             }
         }
     }
 }
 
-/// `None`: not the callback, keep waiting. `Some`: the sign-in ended, one way or another.
-fn handle(
-    mut stream: TcpStream,
-    state: &str,
-    issuer: &str,
+fn timed_out() -> Failure {
+    Failure::new(
+        Kind::NotAuthenticated,
+        "Timed out waiting for the browser to finish signing in.",
+    )
+    .hint("Run `hodeishield login` again, or `hodeishield login --device`.")
+}
+
+fn is_aborted_connection(kind: std::io::ErrorKind) -> bool {
+    matches!(
+        kind,
+        std::io::ErrorKind::ConnectionAborted | std::io::ErrorKind::ConnectionReset
+    )
+}
+
+/// What `handle` checks a connection against.
+struct Request<'a> {
+    state: &'a str,
+    issuer: &'a str,
     require_iss: bool,
-) -> Option<Result<Callback>> {
+    limits: Limits,
+    /// When the whole sign-in gives up; no connection may outlive it.
+    deadline: Instant,
+}
+
+/// `None`: not the callback, keep waiting. `Some`: the sign-in ended, one way or another.
+fn handle(mut stream: TcpStream, request: &Request<'_>) -> Option<Result<Callback>> {
+    let Request {
+        state,
+        issuer,
+        require_iss,
+        ..
+    } = *request;
     let _ = stream.set_nonblocking(false);
-    let _ = stream.set_read_timeout(Some(Duration::from_secs(5)));
-    let target = read_request_target(&mut stream)?;
+    // A client that never reads the answer must not hold the listener either.
+    let _ = stream.set_write_timeout(Some(request.limits.read));
+    let connection_deadline = Instant::now() + request.limits.connection;
+    let target = read_request_target(
+        &mut stream,
+        request.limits.read,
+        connection_deadline.min(request.deadline),
+    )?;
     let (path, query) = target.split_once('?').unwrap_or((target.as_str(), ""));
     if path != CALLBACK_PATH {
         respond(&mut stream, "404 Not Found", "Not found.");
@@ -177,10 +242,23 @@ fn handle(
 }
 
 /// The request target of a `GET` request line, or `None` for anything else.
-fn read_request_target(stream: &mut TcpStream) -> Option<String> {
+///
+/// Every read waits for at most `read_timeout` and never past `deadline`, so a client that sends a
+/// byte now and then cannot hold the connection beyond it.
+fn read_request_target(
+    stream: &mut TcpStream,
+    read_timeout: Duration,
+    deadline: Instant,
+) -> Option<String> {
     let mut buffer = Vec::with_capacity(1024);
     let mut chunk = [0_u8; 1024];
     while !buffer.windows(4).any(|w| w == b"\r\n\r\n") && buffer.len() < 16 * 1024 {
+        let left = deadline.saturating_duration_since(Instant::now());
+        let wait = read_timeout.min(left);
+        // A zero timeout is an error for the socket; out of time means stop reading.
+        if wait.is_zero() || stream.set_read_timeout(Some(wait)).is_err() {
+            break;
+        }
         match stream.read(&mut chunk) {
             Ok(0) | Err(_) => break,
             Ok(n) => buffer.extend_from_slice(&chunk[..n]),
@@ -302,4 +380,124 @@ mod tests {
         ]);
         assert!(result.expect_err("denied").message.contains("denied"));
     }
+
+    /// Connects and sends one byte every `pause`, `count` times, stopping when the server hangs up.
+    fn trickle(uri: &str, pause: Duration, count: u32) -> std::thread::JoinHandle<()> {
+        let addr = uri
+            .trim_start_matches("http://")
+            .split('/')
+            .next()
+            .expect("host")
+            .to_owned();
+        let mut stream = TcpStream::connect(addr).expect("connect");
+        std::thread::spawn(move || {
+            for _ in 0..count {
+                if stream.write_all(b"x").is_err() {
+                    return;
+                }
+                std::thread::sleep(pause);
+            }
+        })
+    }
+
+    #[test]
+    fn an_aborted_connection_does_not_end_the_sign_in() {
+        use std::io::ErrorKind::*;
+        assert!(is_aborted_connection(ConnectionAborted));
+        assert!(is_aborted_connection(ConnectionReset));
+        assert!(!is_aborted_connection(WouldBlock));
+        assert!(!is_aborted_connection(PermissionDenied));
+    }
+
+    #[test]
+    fn the_overall_timeout_holds_while_clients_keep_connecting() {
+        let loopback = Loopback::bind().expect("bind");
+        let uri = loopback.redirect_uri().to_owned();
+        let addr = uri
+            .trim_start_matches("http://")
+            .split('/')
+            .next()
+            .expect("host")
+            .to_owned();
+        let stop = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
+        let flag = stop.clone();
+        let churn = std::thread::spawn(move || {
+            while !flag.load(std::sync::atomic::Ordering::Relaxed) {
+                // Connect and close at once, so there is always something waiting to be accepted.
+                drop(TcpStream::connect(&addr));
+            }
+        });
+        let started = Instant::now();
+        let result = loopback.wait(
+            "expected-state",
+            "https://app.example.test",
+            false,
+            Duration::from_millis(400),
+        );
+        let elapsed = started.elapsed();
+        stop.store(true, std::sync::atomic::Ordering::Relaxed);
+        churn.join().expect("churn");
+        assert!(
+            result.expect_err("timeout").message.contains("Timed out"),
+            "timed out"
+        );
+        assert!(elapsed < Duration::from_secs(3), "{elapsed:?}");
+    }
+
+    fn quick(read_ms: u64, connection_ms: u64) -> Limits {
+        Limits {
+            read: Duration::from_millis(read_ms),
+            connection: Duration::from_millis(connection_ms),
+        }
+    }
+
+    #[test]
+    fn a_trickling_client_is_cut_off_and_the_real_callback_still_gets_in() {
+        let mut loopback = Loopback::bind().expect("bind");
+        // Each byte arrives well inside the read timeout, so only the connection deadline stops it.
+        loopback.limits = quick(1_000, 300);
+        let uri = loopback.redirect_uri().to_owned();
+        let slow = trickle(&uri, Duration::from_millis(50), 100);
+        let started = Instant::now();
+        let real = {
+            let uri = uri.clone();
+            std::thread::spawn(move || hit(&uri, "/callback?code=abc&state=expected-state"))
+        };
+        let result = loopback.wait(
+            "expected-state",
+            "https://app.example.test",
+            false,
+            Duration::from_secs(10),
+        );
+        assert!(
+            started.elapsed() < Duration::from_secs(3),
+            "{:?}",
+            started.elapsed()
+        );
+        assert_eq!(result.expect("real callback").code.expose_secret(), "abc");
+        assert!(real.join().expect("client").starts_with("HTTP/1.1 200"));
+        slow.join().expect("trickler");
+    }
+
+    #[test]
+    fn the_overall_timeout_holds_while_a_trickling_client_is_connected() {
+        let mut loopback = Loopback::bind().expect("bind");
+        loopback.limits = quick(1_000, 5_000);
+        let uri = loopback.redirect_uri().to_owned();
+        let slow = trickle(&uri, Duration::from_millis(50), 100);
+        let started = Instant::now();
+        let result = loopback.wait(
+            "expected-state",
+            "https://app.example.test",
+            false,
+            Duration::from_millis(400),
+        );
+        let elapsed = started.elapsed();
+        assert!(
+            result.expect_err("timeout").message.contains("Timed out"),
+            "timed out"
+        );
+        assert!(elapsed < Duration::from_secs(2), "{elapsed:?}");
+        slow.join().expect("trickler");
+    }
 }

From 619af9bbe2065692b5c1aa4b948603cdff76a17f Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Sat, 10 Oct 2026 19:20:30 +0200
Subject: [PATCH 27/57] Update dependencies to their latest compatible releases

Refresh Cargo.lock within the existing semver ranges. No Cargo.toml
changes and no major or pre-release versions are taken.

Notable bumps:
- tokio 1.53.1 -> 1.53.2, tokio-util 0.7.19 -> 0.7.20
- hyper 1.11.1 -> 1.12.0, h2 0.4.19 -> 0.4.20
- quinn-proto 0.11.18 -> 0.11.19, quinn-udp 0.5.15 -> 0.5.16
- serde_json 1.0.151 -> 1.0.152
- toml 1.1.6 -> 1.1.8 (with toml_edit, toml_parser, toml_datetime,
  toml_writer, serde_spanned)
- uuid 1.26.1 -> 1.28.0, cc 1.5.1 -> 1.7.0, libc 0.2.189 -> 0.2.190
- mio 1.2.3 -> 1.2.4, smallvec 1.16.2 -> 1.16.3, syn 3.0.6 -> 3.0.7
- zerocopy 0.8.59 -> 0.8.62, zeroize 1.9.0 -> 1.9.1

cargo audit and cargo deny check pass.

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 Cargo.lock | 136 ++++++++++++++++++++++++++---------------------------
 1 file changed, 68 insertions(+), 68 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index f37a95f..05c65e0 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -195,13 +195,13 @@ dependencies = [
 
 [[package]]
 name = "async-recursion"
-version = "1.1.1"
+version = "1.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3b43422f69d8ff38f95f1b2bb76517c91589a924d1559a0e935d7c8ce0274c11"
+checksum = "4f8abc12baad266b1c8cec146854c195b5864b4221d4b2ca7296a7ae82d9e451"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.119",
+ "syn 3.0.7",
 ]
 
 [[package]]
@@ -236,7 +236,7 @@ checksum = "82f6aeea286b8eb4dd3431a1be1b59d290ace00f5bfd8e2a159bc2a05e2c1667"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.6",
+ "syn 3.0.7",
 ]
 
 [[package]]
@@ -357,9 +357,9 @@ dependencies = [
 
 [[package]]
 name = "cc"
-version = "1.5.1"
+version = "1.7.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f360145194ee8e21db5ee7f3fcd4fe52210864c75c985dae33218202c8bbe040"
+checksum = "50a649af8a827553c29fb0cb4bd4a6f1a0dd695bd3232b9bc98bd9c8a3ffbb8b"
 dependencies = [
  "find-msvc-tools",
  "jobserver",
@@ -441,7 +441,7 @@ dependencies = [
  "heck",
  "proc-macro2",
  "quote",
- "syn 3.0.6",
+ "syn 3.0.7",
 ]
 
 [[package]]
@@ -607,9 +607,9 @@ dependencies = [
 
 [[package]]
 name = "ctutils"
-version = "0.4.2"
+version = "0.4.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7d5515a3834141de9eafb9717ad39eea8247b5674e6066c404e8c4b365d2a29e"
+checksum = "03bb0e1cc970d482d121d9a1744999169b69a07470b3d644a7894e53fcaf4574"
 dependencies = [
  "cmov",
 ]
@@ -671,7 +671,7 @@ checksum = "c6232dd377dcc64799954cbd3a9bb882e9cdc1308ccd87b1c098f1fb2eaf82a8"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.6",
+ "syn 3.0.7",
 ]
 
 [[package]]
@@ -837,7 +837,7 @@ checksum = "9fb9654ba8355388abeb8dcb4fc62f511300867002afc858860463bdd9fe0c44"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.6",
+ "syn 3.0.7",
 ]
 
 [[package]]
@@ -909,9 +909,9 @@ dependencies = [
 
 [[package]]
 name = "h2"
-version = "0.4.19"
+version = "0.4.20"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ef8e5e5a340588f4452631496976cf8636d4a7ecf600239fdc27615d2530bc16"
+checksum = "7d29020232d6aa3fb1daca64c1127cf662cf97f254ae16c18c05b8ab635fc118"
 dependencies = [
  "atomic-waker",
  "bytes",
@@ -1067,9 +1067,9 @@ dependencies = [
 
 [[package]]
 name = "hyper"
-version = "1.11.1"
+version = "1.12.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "27b501faa50e7a26c3d3560ca625132f4078a17771f4810baf70475ae48cbe43"
+checksum = "2c3e324da4c95177d6291d4c8730197c0d1822f8a9766814a4a44fa5ab797c9c"
 dependencies = [
  "atomic-waker",
  "bytes",
@@ -1351,9 +1351,9 @@ dependencies = [
 
 [[package]]
 name = "libc"
-version = "0.2.189"
+version = "0.2.190"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
+checksum = "ce5d3ddc6d3fa000eb1536d85e147bfe31aacaba692ed6a876f95cb7c855be78"
 
 [[package]]
 name = "libredox"
@@ -1420,9 +1420,9 @@ dependencies = [
 
 [[package]]
 name = "mio"
-version = "1.2.3"
+version = "1.2.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4b18443e9c262bfe8fa82f51666e2642c53393f7e5c27b3e1aeab922cff5b9d8"
+checksum = "1788edb87fdc09c7e26304471e2f5be8cdefb1b6930d6e3985fc02ff53bf86ee"
 dependencies = [
  "libc",
  "wasi",
@@ -1540,9 +1540,9 @@ dependencies = [
 
 [[package]]
 name = "objc2"
-version = "0.6.4"
+version = "0.6.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3a12a8ed07aefc768292f076dc3ac8c48f3781c8f2d5851dd3d98950e8c5a89f"
+checksum = "08849bbd4767dfae9457696856ae1c84fe4e0281bbe4a7abff2d0e06fb7981f8"
 dependencies = [
  "objc2-encode",
 ]
@@ -1780,9 +1780,9 @@ dependencies = [
 
 [[package]]
 name = "quinn-proto"
-version = "0.11.18"
+version = "0.11.19"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a9746dbde176634f4f2f1faf2404e30a31b2bc1e9cafb5329c95d8177a18c9fc"
+checksum = "0e750cca55fe4f0439a15d0bb529da9651e79993e8e72c61a899a36d462befbe"
 dependencies = [
  "aws-lc-rs",
  "bytes",
@@ -1803,9 +1803,9 @@ dependencies = [
 
 [[package]]
 name = "quinn-udp"
-version = "0.5.15"
+version = "0.5.16"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "35a133f956daabe89a61a685c2649f13d82d5aa4bd5d12d1277e1072a21c0694"
+checksum = "af66907df18639dcf4db56ca65490cabc4b27a97dbadd96f2926cca73298f016"
 dependencies = [
  "cfg_aliases",
  "libc",
@@ -2224,14 +2224,14 @@ checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.6",
+ "syn 3.0.7",
 ]
 
 [[package]]
 name = "serde_json"
-version = "1.0.151"
+version = "1.0.152"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"
+checksum = "1741ab7a6cc54a03a89b5d563ed60075c277d9e3cfa73ad0c1f23f23974703c6"
 dependencies = [
  "indexmap",
  "itoa",
@@ -2249,14 +2249,14 @@ checksum = "8d3b1629de253c70a0508c3899572da79ca359fdab27c7920ff00406df418906"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.6",
+ "syn 3.0.7",
 ]
 
 [[package]]
 name = "serde_spanned"
-version = "1.1.1"
+version = "1.1.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6662b5879511e06e8999a8a235d848113e942c9124f211511b16466ee2995f26"
+checksum = "4e7523beb55eece201a2356bee0bbca0d1ab466c14c07703b2e0ee6d42cb0c2c"
 dependencies = [
  "serde_core",
 ]
@@ -2330,9 +2330,9 @@ checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
 
 [[package]]
 name = "smallvec"
-version = "1.16.2"
+version = "1.16.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f9395f0f0eee849a9b707b2f06bb92a6a422090e2123bb2ef8e87a0e61892a8e"
+checksum = "5b3dc8af474f516a851ff4bd12db780f948b9250ad37211e4eec0bccea54e01b"
 
 [[package]]
 name = "socket2"
@@ -2375,9 +2375,9 @@ dependencies = [
 
 [[package]]
 name = "syn"
-version = "3.0.6"
+version = "3.0.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8593e8e72159ed2257d083c7a454a85cbf854f37a0966d8d483aff8c8a3ebcee"
+checksum = "d62a2e0561533f2ca2561d0cf27fd9fedb640a1bf2616ff5d5c80d99017faadc"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -2401,7 +2401,7 @@ checksum = "901704edd0dfe137f1987838ee4f259e4e063c31371bdb423f7ae38ec6f77f02"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.6",
+ "syn 3.0.7",
 ]
 
 [[package]]
@@ -2471,7 +2471,7 @@ checksum = "fe5197923287db20a58125f0bc85c062f7f2c892de97b18c356f9efb14b28524"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.6",
+ "syn 3.0.7",
 ]
 
 [[package]]
@@ -2492,9 +2492,9 @@ checksum = "fd3ca314f692efd6c868f8408f53fe444634a845f96c028b97d35f6a1f79f0ee"
 
 [[package]]
 name = "tokio"
-version = "1.53.1"
+version = "1.53.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "202caea871b69668250d242070849eb495be178ed697a3e98aebce5bc81a0bed"
+checksum = "e95f91fcc7a621e8b030f6aa23c71fe9838ae2fb4d8118b75602a328f5144044"
 dependencies = [
  "bytes",
  "libc",
@@ -2517,9 +2517,9 @@ dependencies = [
 
 [[package]]
 name = "tokio-util"
-version = "0.7.19"
+version = "0.7.20"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "494815d09bf52b5548659851081238f0ca39ff638363907596da739561c62c52"
+checksum = "e464cf451ba96ebfc6f9b6542f17ee8b8956e33f1e40d9690624e59d7a7f8a4b"
 dependencies = [
  "bytes",
  "futures-core",
@@ -2531,9 +2531,9 @@ dependencies = [
 
 [[package]]
 name = "toml"
-version = "1.1.6+spec-1.1.0"
+version = "1.1.8+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "920602543f0911ab71da12c50d59701da54c196d1a2bf5cb4b75667f137a406a"
+checksum = "20489e00e4d8741d6be680764cc12e270655e375a20d1011e844a9c3379e678d"
 dependencies = [
  "indexmap",
  "serde_core",
@@ -2546,18 +2546,18 @@ dependencies = [
 
 [[package]]
 name = "toml_datetime"
-version = "1.1.1+spec-1.1.0"
+version = "1.1.2+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3165f65f62e28e0115a00b2ebdd37eb6f3b641855f9d636d3cd4103767159ad7"
+checksum = "2b86d767906c6c42421dcba507eb9d203e779497710a47782a224bb871653053"
 dependencies = [
  "serde_core",
 ]
 
 [[package]]
 name = "toml_edit"
-version = "0.25.15+spec-1.1.0"
+version = "0.25.17+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1340ea94a5856333492c9064b02c778b191dd2c853778d9609debdcdfea3a614"
+checksum = "e3641d5bbb5349a79e1020a242d251efbc546ad8048d133958323ce9c40a9c9c"
 dependencies = [
  "indexmap",
  "toml_datetime",
@@ -2567,18 +2567,18 @@ dependencies = [
 
 [[package]]
 name = "toml_parser"
-version = "1.1.3+spec-1.1.0"
+version = "1.1.5+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1d38ac1cf9b95face32296c0a3ede1fdc270627c9d9c02a7274dd6d960dc4d56"
+checksum = "baa693a8032d7e1cada7d0041e96126df243179ff061456783ac7f12bda4744c"
 dependencies = [
  "winnow",
 ]
 
 [[package]]
 name = "toml_writer"
-version = "1.1.2+spec-1.1.0"
+version = "1.1.3+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7d56353a2a665ad0f41a421187180aab746c8c325620617ad883a99a1cbe66d2"
+checksum = "06bdbd8cfc056b8d2e2e85f29b56a3bdbecb527cef81eb39e3e7b98af4652770"
 
 [[package]]
 name = "tower"
@@ -2730,9 +2730,9 @@ checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
 
 [[package]]
 name = "uuid"
-version = "1.26.1"
+version = "1.28.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2ef6dac1e96601b4fb3acccccff2139741fcb757cb9a36089bf5be91cfb285ce"
+checksum = "7cc1186384beb7dd8eedea376413fd654937285ea6c9cfbb928dc3043ea4b606"
 dependencies = [
  "js-sys",
  "serde_core",
@@ -2760,9 +2760,9 @@ dependencies = [
 
 [[package]]
 name = "want"
-version = "0.3.1"
+version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bfa7760aed19e106de2c7c0b581b509f2f25d3dacaf737cb82ac61bc6d760b0e"
+checksum = "ec4cdd0dd910afe868b7ef477227d8d538b46b3075031afee8a9f2acb0a2ed0b"
 dependencies = [
  "try-lock",
 ]
@@ -2825,7 +2825,7 @@ dependencies = [
  "bumpalo",
  "proc-macro2",
  "quote",
- "syn 3.0.6",
+ "syn 3.0.7",
  "wasm-bindgen-shared",
 ]
 
@@ -3094,7 +3094,7 @@ checksum = "ec8ebde2db3681e8c9980cc27822030e68752690ddfa9473e739aeb4dbde6d71"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.6",
+ "syn 3.0.7",
  "synstructure",
 ]
 
@@ -3153,7 +3153,7 @@ dependencies = [
  "proc-macro-crate",
  "proc-macro2",
  "quote",
- "syn 3.0.6",
+ "syn 3.0.7",
  "zbus_names",
  "zvariant",
  "zvariant_utils",
@@ -3181,18 +3181,18 @@ dependencies = [
 
 [[package]]
 name = "zerocopy"
-version = "0.8.59"
+version = "0.8.62"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6df92bf3d9227be3d53173901ddbffac2babc27ae50f397776ffd6dc33f800cb"
+checksum = "86502bf56ac7c77571a32e2647bb2a15894565e981fb2a48d7bde2d91c965a9d"
 dependencies = [
  "zerocopy-derive",
 ]
 
 [[package]]
 name = "zerocopy-derive"
-version = "0.8.59"
+version = "0.8.62"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ac4f328cf2f05d084e496c3e9c3f33ed0a183656a16e1fcec4d464d8373aec82"
+checksum = "5457206954b06561e2608c7e19cf58b1926586d999c246eebe4502f7e2039d1a"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -3216,15 +3216,15 @@ checksum = "f75b4683f6c7f45248d4d64056a24298c6281e0993356d7d1b4a1a962ef10d4a"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.6",
+ "syn 3.0.7",
  "synstructure",
 ]
 
 [[package]]
 name = "zeroize"
-version = "1.9.0"
+version = "1.9.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e13c156562582aa81c60cb29407084cdb54c4164760106ab78e6c5b0858cf64e"
+checksum = "e13084392c5e4bc371903e2935a5eaeed24905a7511356b883835e18a78f6879"
 
 [[package]]
 name = "zerotrie"
@@ -3256,7 +3256,7 @@ checksum = "34df6fc39dbd26ddc9c10e6a2984476e13acce22e64e4487636ef494369225da"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.6",
+ "syn 3.0.7",
 ]
 
 [[package]]
@@ -3289,7 +3289,7 @@ dependencies = [
  "proc-macro-crate",
  "proc-macro2",
  "quote",
- "syn 3.0.6",
+ "syn 3.0.7",
  "zvariant_utils",
 ]
 
@@ -3302,6 +3302,6 @@ dependencies = [
  "proc-macro2",
  "quote",
  "serde",
- "syn 3.0.6",
+ "syn 3.0.7",
  "winnow",
 ]

From e21843bc1255e22fda4f31b4cb54e1f2318dc58b Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Sat, 10 Oct 2026 20:01:57 +0200
Subject: [PATCH 28/57] Replace line separators, tag and deprecated format
 characters in output

U+2028 and U+2029 are treated as line breaks by some terminals and
viewers, the tag characters and the variation selectors supplement
(U+E0000..U+E0FFF) are invisible and can carry hidden text, and
U+206A..U+206F are deprecated format characters that are invisible and
that bidi-aware renderers still act on. Text from the API could use them
to display differently from what it contains.

They now go through the same replacement as the other invisible
characters, in tables, detail views, CSV and the --json escaping,
including the surrogate pairs of characters outside the BMP. The doc
comment lists every range and why it is there; U+FEFF and
U+FFF9..U+FFFB were already covered, and the variation selectors
U+FE00..U+FE0F are left alone because U+FE0F selects the emoji
presentation of visible text.

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 CHANGELOG.md                         |  4 ++
 crates/hodeishield-cli/src/output.rs | 59 ++++++++++++++++++++++++++--
 2 files changed, 60 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0dec299..b8c9d5b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,10 @@ commands, `--json` output and exit codes. Each release's notes start with its se
 
 ### Fixed
 
+- Terminal output cleaning now also replaces the line and paragraph separators (U+2028, U+2029),
+  the deprecated format characters U+206A to U+206F and the tag characters and variation selectors supplement
+  (U+E0000 to U+E0FFF), which display differently from what they contain. This applies to tables,
+  detail views, CSV and the escaping of `--json` output. ([#106](https://github.com/Hodeitek/hodeishield-cli/issues/106))
 - `hodeishield login` now checks that the system keychain can keep a session before it opens the
   browser or shows a device code, and stops there with the usual pointer to API keys. If saving the
   session still fails after the app has issued tokens, the CLI revokes the refresh token and then
diff --git a/crates/hodeishield-cli/src/output.rs b/crates/hodeishield-cli/src/output.rs
index 3069868..4735fb9 100644
--- a/crates/hodeishield-cli/src/output.rs
+++ b/crates/hodeishield-cli/src/output.rs
@@ -18,7 +18,20 @@ pub fn clean(text: &str) -> String {
 }
 
 /// Control characters (C0, DEL, C1) and the invisible or direction-changing format characters that
-/// can make text display as something it is not.
+/// can make text display as something it is not:
+///
+/// - U+00AD, U+061C, U+180E, U+200B..U+200F, U+202A..U+202E, U+2060..U+2064, U+2066..U+2069,
+///   U+FEFF and U+FFF9..U+FFFB: soft hyphen, zero-width and direction marks and embeddings,
+///   isolates, the word joiner and invisible operators, the zero-width no-break space and the
+///   interlinear annotation anchors, which hide text or reorder it.
+/// - U+2028 and U+2029: the line and paragraph separators, which some terminals and viewers treat
+///   as a line break although `\n` is what the caller checked for.
+/// - U+206A..U+206F: the deprecated format characters (symmetric swapping, Arabic shaping, digit
+///   shapes), which are invisible and which bidi-aware renderers still act on. With U+2066..U+2069
+///   they form one range; U+2065 is unassigned and stays out.
+/// - U+E0000..U+E0FFF: the tag characters and the variation selectors supplement (U+E0100..U+E01EF)
+///   inside the invisible block, which can carry hidden text. The variation selectors U+FE00..U+FE0F
+///   are left alone on purpose: U+FE0F selects the emoji presentation of visible text.
 fn is_unsafe(c: char) -> bool {
     c.is_control()
         || matches!(
@@ -27,11 +40,14 @@ fn is_unsafe(c: char) -> bool {
                 | '\u{061c}'
                 | '\u{180e}'
                 | '\u{200b}'..='\u{200f}'
+                | '\u{2028}'
+                | '\u{2029}'
                 | '\u{202a}'..='\u{202e}'
                 | '\u{2060}'..='\u{2064}'
-                | '\u{2066}'..='\u{2069}'
+                | '\u{2066}'..='\u{206f}'
                 | '\u{feff}'
                 | '\u{fff9}'..='\u{fffb}'
+                | '\u{e0000}'..='\u{e0fff}'
         )
 }
 
@@ -257,12 +273,49 @@ mod tests {
         );
     }
 
+    #[test]
+    fn separators_format_characters_and_tags_are_replaced() {
+        for c in [
+            '\u{2028}',
+            '\u{2029}',
+            '\u{206a}',
+            '\u{206f}',
+            '\u{feff}',
+            '\u{fff9}',
+            '\u{fffa}',
+            '\u{fffb}',
+            '\u{e0000}',
+            '\u{e0041}',
+            '\u{e007f}',
+            '\u{e0100}',
+            '\u{e01ef}',
+            '\u{e0fff}',
+        ] {
+            assert_eq!(
+                clean(&format!("a{c}b")),
+                "a\u{fffd}b",
+                "U+{:04X}",
+                u32::from(c)
+            );
+        }
+        // The neighbours of the ranges are visible or unassigned text and stay as they are.
+        let kept = "\u{2027}\u{202f}\u{2065}\u{2070}\u{fe0f}\u{e1000}";
+        assert_eq!(clean(kept), kept);
+        assert_eq!(
+            clean("caf\u{e9} \u{1f600} \u{4e2d}"),
+            "caf\u{e9} \u{1f600} \u{4e2d}"
+        );
+    }
+
     #[test]
     fn json_escapes_what_could_drive_the_terminal_without_changing_the_value() {
-        let value = serde_json::json!({"name": "a\u{9b}31m\u{7f}\u{202e}b\u{1b}"});
+        let value = serde_json::json!({"name": "a\u{9b}31m\u{7f}\u{202e}b\u{1b}\u{e0041}\u{2028}"});
         let mut out = Vec::new();
         print_json(&mut out, &value).expect("print");
         let text = String::from_utf8(out).expect("utf8");
+        // A tag character outside the BMP is escaped as a surrogate pair.
+        assert!(text.contains("\\udb40\\udc41"), "{text:?}");
+        assert!(text.contains("\\u2028"), "{text:?}");
         assert!(text.chars().all(|c| !is_unsafe(c) || c == '\n'), "{text:?}");
         let back: Value = serde_json::from_str(&text).expect("still JSON");
         assert_eq!(back, value);

From eac18c17fd1385b3933dc6e4dd7259fc1feb392f Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Sat, 10 Oct 2026 20:02:42 +0200
Subject: [PATCH 29/57] Defuse CSV formulas that follow leading whitespace

Some spreadsheet applications trim leading whitespace before they
evaluate a cell, so a field such as " =1+1" or a no-break space before
"=cmd" ran as a formula although its first character was not one of the
trigger characters (CWE-1236).

A field now counts as a formula when its first character after any
Unicode whitespace is =, +, - or @, and still when it starts with a tab
or carriage return. Numbers never reach this check and normal text is
written as before.

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 CHANGELOG.md                         |  5 ++
 crates/hodeishield-cli/src/output.rs | 70 ++++++++++++++++++++--------
 2 files changed, 56 insertions(+), 19 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b8c9d5b..927af1b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,11 @@ commands, `--json` output and exit codes. Each release's notes start with its se
   the deprecated format characters U+206A to U+206F and the tag characters and variation selectors supplement
   (U+E0000 to U+E0FFF), which display differently from what they contain. This applies to tables,
   detail views, CSV and the escaping of `--json` output. ([#106](https://github.com/Hodeitek/hodeishield-cli/issues/106))
+- CSV output now also defuses a field whose first character after any leading whitespace is `=`,
+  `+`, `-` or `@`, or one of their full-width forms (for example `" =1+1"`, or a no-break space
+  before `=cmd`). It decides on the text as it is written, because some spreadsheet applications
+  trim the whitespace before evaluating the cell. Numbers are still written as they are.
+  ([#106](https://github.com/Hodeitek/hodeishield-cli/issues/106))
 - `hodeishield login` now checks that the system keychain can keep a session before it opens the
   browser or shows a device code, and stops there with the usual pointer to API keys. If saving the
   session still fails after the app has issued tokens, the CLI revokes the refresh token and then
diff --git a/crates/hodeishield-cli/src/output.rs b/crates/hodeishield-cli/src/output.rs
index 4735fb9..53b40ec 100644
--- a/crates/hodeishield-cli/src/output.rs
+++ b/crates/hodeishield-cli/src/output.rs
@@ -174,7 +174,7 @@ pub fn print_csv(out: &mut dyn Write, items: &[Value]) -> std::io::Result<()> {
     if columns.is_empty() {
         return Ok(());
     }
-    let header: Vec<String> = columns.iter().map(|c| csv_field(&defuse(c))).collect();
+    let header: Vec<String> = columns.iter().map(|c| csv_field(&csv_text(c))).collect();
     write!(out, "{}\r\n", header.join(","))?;
     for item in items {
         let record: Vec<String> = columns
@@ -193,26 +193,15 @@ fn csv_cell(value: Option<&Value>) -> String {
         None | Some(Value::Null) => String::new(),
         Some(Value::Number(n)) => n.to_string(),
         Some(Value::Bool(b)) => b.to_string(),
-        Some(Value::String(s)) => defuse(s),
-        Some(other) => defuse(&other.to_string()),
+        Some(Value::String(s)) => csv_text(s),
+        Some(other) => csv_text(&other.to_string()),
     }
 }
 
-/// A spreadsheet runs a cell that starts with `=`, `+`, `-` or `@` (and, in some, a tab or carriage
-/// return) as a formula; a leading `'` makes it text (CWE-1236). Numbers never pass through here, so
-/// `-5` stays a number.
-fn defuse(text: &str) -> String {
-    if text.starts_with(['=', '+', '-', '@', '\t', '\r']) {
-        format!("'{text}")
-    } else {
-        text.to_owned()
-    }
-}
-
-/// One RFC 4180 field: quoted when it holds a comma, a quote, a line break or a leading or trailing
-/// space, with quotes doubled. Tabs and line breaks are kept; every other character [`clean`]
-/// replaces is replaced here too, as the file may well be printed to a terminal.
-fn csv_field(text: &str) -> String {
+/// Text for a CSV field, in the form it will be written: every character [`clean`] replaces is
+/// replaced here too (tabs and line breaks are kept), as the file may well be printed to a terminal,
+/// and only then is the result checked by [`defuse`], so the decision is made on what is written.
+fn csv_text(text: &str) -> String {
     let text: String = text
         .chars()
         .map(|c| {
@@ -223,10 +212,36 @@ fn csv_field(text: &str) -> String {
             }
         })
         .collect();
+    defuse(&text)
+}
+
+/// A spreadsheet runs a cell whose first character is `=`, `+`, `-` or `@` (and, in some, a tab or
+/// carriage return) as a formula, and some trim leading whitespace first, so the first character
+/// after any Unicode whitespace (spaces, no-break space, line breaks, …) counts too, as do the
+/// full-width forms `＝`, `＋`, `－` and `＠`, which some applications fold to the ASCII ones. A
+/// leading `'` makes the cell text (CWE-1236). Numbers never pass through here, so `-5` stays a
+/// number.
+fn defuse(text: &str) -> String {
+    let first = text.trim_start_matches(char::is_whitespace).chars().next();
+    if text.starts_with(['\t', '\r'])
+        || matches!(
+            first,
+            Some('=' | '+' | '-' | '@' | '\u{ff1d}' | '\u{ff0b}' | '\u{ff0d}' | '\u{ff20}')
+        )
+    {
+        format!("'{text}")
+    } else {
+        text.to_owned()
+    }
+}
+
+/// One RFC 4180 field: quoted when it holds a comma, a quote, a line break or a leading or trailing
+/// space, with quotes doubled.
+fn csv_field(text: &str) -> String {
     if text.contains([',', '"', '\r', '\n']) || text.starts_with(' ') || text.ends_with(' ') {
         format!("\"{}\"", text.replace('"', "\"\""))
     } else {
-        text
+        text.to_owned()
     }
 }
 
@@ -417,6 +432,23 @@ mod tests {
             "'=1+1,'+1,'-1,'@SUM(A1),'\tx,\"'\rx\",-5,\"[\"\"=x\"\"]\",a=b\r\n"
         );
         assert!(csv(&serde_json::json!([{"=bad": 1}])).starts_with("'=bad\r\n"));
+        assert!(csv(&serde_json::json!([{" =bad": 1}])).starts_with("' =bad\r\n"));
+        assert!(csv(&serde_json::json!([{"\u{a0}@bad": 1}])).starts_with("'\u{a0}@bad\r\n"));
+    }
+
+    #[test]
+    fn csv_defuses_formulas_after_leading_whitespace() {
+        let text = csv(&serde_json::json!([{
+            "space": " =1+1", "spaces": "  @SUM(A1)", "nbsp": "\u{a0}=cmd", "em": "\u{2003}+1",
+            "nel": "\u{85}-1", "zw": "\u{200b}=x", "wide": " \u{ff1d}1", "wideplus": "\u{ff0b}1",
+            "widedash": "\u{ff0d}1", "wideat": "\u{3000}\u{ff20}x", "lf": "\n=x", "mixed": " \t -2",
+            "plain": " a=b", "only": "   ", "dash": " - note", "ok": "a =b"
+        }]));
+        let record = text.split_once("\r\n").expect("header").1;
+        assert_eq!(
+            record,
+            "' =1+1,'  @SUM(A1),'\u{a0}=cmd,'\u{2003}+1,\u{fffd}-1,\u{fffd}=x,' \u{ff1d}1,'\u{ff0b}1,'\u{ff0d}1,'\u{3000}\u{ff20}x,\"'\n=x\",' \t -2,\" a=b\",\"   \",' - note,a =b\r\n"
+        );
     }
 
     #[test]

From 4b6bf1d9164282b38e5363262ecb018a47e67efc Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Sat, 10 Oct 2026 20:11:27 +0200
Subject: [PATCH 30/57] Print the update notice's version from the parsed
 numbers

The version in the update notice was the release tag from the release
feed, trimmed of a leading v. The parser ignores build metadata after a
+, so a tag such as v9.9.9+ followed by control or direction characters
was accepted and printed as it came.

The notice now prints major.minor.patch rebuilt from the parsed numbers.

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 crates/hodeishield-cli/src/update_check.rs | 20 ++++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)

diff --git a/crates/hodeishield-cli/src/update_check.rs b/crates/hodeishield-cli/src/update_check.rs
index b3c27be..0957494 100644
--- a/crates/hodeishield-cli/src/update_check.rs
+++ b/crates/hodeishield-cli/src/update_check.rs
@@ -148,11 +148,17 @@ fn fetch_latest() -> Result<String, String> {
     }
     let body = hodeishield_api::read_body(response, MAX_BODY_BYTES).map_err(|e| e.to_string())?;
     let release: Release = serde_json::from_slice(&body).map_err(|e| format!("bad answer: {e}"))?;
-    parse_version(&release.tag_name)
-        .map(|_| release.tag_name.trim_start_matches('v').to_owned())
+    release_version(&release.tag_name)
         .ok_or_else(|| "the release tag is not a plain version".to_owned())
 }
 
+/// The version a release tag stands for, as `major.minor.patch`. The tag comes from the network and
+/// is printed, so it is rebuilt from the parsed numbers: build metadata after a `+` is dropped by
+/// the parser and must not reach the terminal.
+fn release_version(tag: &str) -> Option<String> {
+    parse_version(tag).map(|(major, minor, patch)| format!("{major}.{minor}.{patch}"))
+}
+
 /// `1.2.3` or `v1.2.3` as numbers. Pre-releases (`1.2.3-rc.1`) are not versions to announce, so
 /// they are refused; build metadata (`+abc`) is ignored.
 fn parse_version(text: &str) -> Option<(u64, u64, u64)> {
@@ -192,6 +198,16 @@ fn write_cache(path: &Path, cache: &Cache) -> std::io::Result<()> {
 mod tests {
     use super::*;
 
+    #[test]
+    fn the_printed_version_is_rebuilt_from_the_numbers() {
+        assert_eq!(release_version("v1.2.3").as_deref(), Some("1.2.3"));
+        assert_eq!(
+            release_version("v9.9.9+\u{9b}2J\u{202e}\u{1b}[31m").as_deref(),
+            Some("9.9.9")
+        );
+        assert_eq!(release_version("v1.2.3-rc.1"), None);
+    }
+
     #[test]
     fn versions_compare_as_numbers() {
         assert!(is_newer("0.10.0", "0.9.9"));

From eb9fed3481e6e6a5af4c1c54ae22f667f135cba0 Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Sat, 10 Oct 2026 20:02:50 +0200
Subject: [PATCH 31/57] Restrict the latest-version lookup in install.sh to
 HTTPS

The download already runs with --proto '=https' --tlsv1.2, but the
redirect lookup that resolves the latest version did not, so it would
follow a redirect to another protocol. The resolved version is checked
against a strict character set and the signature identity is tied to the
tag, so this could not change which binary is installed; the flags make
the two curl calls consistent.

Closes #106

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 .github/workflows/ci.yml | 15 +++++++++++++++
 CHANGELOG.md             |  3 +++
 install.sh               |  2 +-
 3 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 9b70c8a..8f13b57 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -167,6 +167,21 @@ jobs:
       - name: shellcheck
         run: shellcheck -s sh install.sh packaging/repo/*.sh
 
+      - name: Every curl call in install.sh is HTTPS-only
+        run: |
+          awk '
+            { line = line $0 }
+            /\\$/ { sub(/\\$/, "", line); next }
+            line !~ /^[ \t]*#/ && line ~ /(^|[ (`;|&])curl -/ {
+              seen++
+              if (line !~ /--proto .=https./ || line !~ /--tlsv1\.2/) {
+                print "install.sh: curl call without --proto =https and --tlsv1.2: " line; bad = 1
+              }
+            }
+            { line = "" }
+            END { if (bad || !seen) { if (!seen) print "install.sh: no curl call found"; exit 1 } }
+          ' install.sh
+
       - name: Install cosign
         uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
         with:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 927af1b..5929a08 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,9 @@ commands, `--json` output and exit codes. Each release's notes start with its se
   before `=cmd`). It decides on the text as it is written, because some spreadsheet applications
   trim the whitespace before evaluating the cell. Numbers are still written as they are.
   ([#106](https://github.com/Hodeitek/hodeishield-cli/issues/106))
+- `install.sh` now looks up the latest release over HTTPS only, with TLS 1.2 or newer, as the
+  download already did, so a redirect cannot lead that lookup to another protocol.
+  ([#106](https://github.com/Hodeitek/hodeishield-cli/issues/106))
 - `hodeishield login` now checks that the system keychain can keep a session before it opens the
   browser or shows a device code, and stops there with the usual pointer to API keys. If saving the
   session still fails after the app has issued tokens, the CLI revokes the refresh token and then
diff --git a/install.sh b/install.sh
index 45acb31..74fbfba 100755
--- a/install.sh
+++ b/install.sh
@@ -78,7 +78,7 @@ case "$(uname -s)" in
 esac
 
 if [ -z "$version" ]; then
-  latest=$(curl -fsSLI -o /dev/null -w '%{url_effective}' "https://github.com/${REPO}/releases/latest") ||
+  latest=$(curl -fsSLI --proto '=https' --tlsv1.2 -o /dev/null -w '%{url_effective}' "https://github.com/${REPO}/releases/latest") ||
     die "could not find the latest release"
   version=${latest##*/}
   version=${version#v}

From 3dc885f47b2aad04c94310c65210246ac79b15da Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Sat, 10 Oct 2026 20:17:51 +0200
Subject: [PATCH 32/57] Link the C runtime statically in the Windows executable

The published hodeishield.exe imports VCRUNTIME140.dll, which belongs to
the Visual C++ Redistributable and is not part of Windows, so it can
fail to start on a clean machine.

Build the *-pc-windows-msvc targets with +crt-static from
.cargo/config.toml. This is the smallest and most robust option: a
build.rs cannot turn on +crt-static, and the hybrid CRT (static VC
runtime, in-box UCRT) would still need this flag plus extra linker
arguments that differ between toolchains. The one weakness is that a
RUSTFLAGS environment variable replaces the config flags, so the
config says so, and the result does not rely on it: the release
workflow now inspects every .exe it signs and packages (found by
search, not by name) and the Windows leg of the pull request CI
inspects the debug executable. Both fail if the import table lists
VCRUNTIME*, MSVCP* or CONCRT*, or if no .exe is found. The imports are
read with dumpbin, located with vswhere; a missing tool is a failure.

Closes #110

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 .cargo/config.toml            | 14 ++++++++++++++
 .github/workflows/ci.yml      | 32 ++++++++++++++++++++++++++++++++
 .github/workflows/release.yml | 27 +++++++++++++++++++++++++++
 CHANGELOG.md                  |  6 ++++++
 4 files changed, 79 insertions(+)

diff --git a/.cargo/config.toml b/.cargo/config.toml
index 9741f11..0bdd44f 100644
--- a/.cargo/config.toml
+++ b/.cargo/config.toml
@@ -1,2 +1,16 @@
 [alias]
 xtask = "run --quiet --package xtask --"
+
+# Link the C runtime statically on Windows, so the executable does not need the Visual C++
+# Redistributable (VCRUNTIME140.dll), which is not part of Windows.
+#
+# Keep this in step with the import check in .github/workflows (ci.yml and release.yml). The
+# RUSTFLAGS, CARGO_ENCODED_RUSTFLAGS and CARGO_TARGET_<TRIPLE>_RUSTFLAGS environment variables
+# replace these flags instead of adding to them, so anyone who sets one of them must repeat
+# "-C target-feature=+crt-static" for these targets; the check fails the build if the
+# redistributable is needed again.
+[target.x86_64-pc-windows-msvc]
+rustflags = ["-C", "target-feature=+crt-static"]
+
+[target.aarch64-pc-windows-msvc]
+rustflags = ["-C", "target-feature=+crt-static"]
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 8f13b57..9aadc5c 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -107,6 +107,38 @@ jobs:
       - name: cargo test
         run: cargo test --workspace --locked
 
+      # The Visual C++ runtime is not part of Windows: the executable must not import it (see
+      # .cargo/config.toml).
+      - name: Build the executable (Windows)
+        if: runner.os == 'Windows'
+        run: cargo build --locked -p hodeishield-cli
+
+      - name: Check the executable needs no Visual C++ runtime
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = "Stop"
+          $vswhere = Join-Path ${env:ProgramFiles(x86)} "Microsoft Visual Studio\Installer\vswhere.exe"
+          if (-not (Test-Path -LiteralPath $vswhere)) { throw "vswhere.exe not found at $vswhere" }
+          $dumpbin = & $vswhere -latest -products * -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 -find "VC\Tools\MSVC\**\bin\Hostx64\x64\dumpbin.exe" | Select-Object -First 1
+          if (-not $dumpbin -or -not (Test-Path -LiteralPath $dumpbin)) { throw "dumpbin.exe not found through vswhere" }
+          $exes = @(Get-ChildItem -LiteralPath target/debug -File -Filter hodeishield.exe)
+          if ($exes.Count -eq 0) { throw "No .exe found to inspect in target/debug" }
+          $failed = $false
+          foreach ($exe in $exes) {
+            $output = & $dumpbin /nologo /dependents $exe.FullName
+            if ($LASTEXITCODE -ne 0) { throw "dumpbin failed on $($exe.FullName)" }
+            $imports = @($output | ForEach-Object { $_.Trim() } | Where-Object { $_ -match '^\S+\.dll$' })
+            if ($imports.Count -eq 0) { throw "No imports parsed from $($exe.FullName)" }
+            Write-Host "$($exe.Name): $($imports -join ', ')"
+            $runtime = @($imports | Where-Object { $_ -match '^(VCRUNTIME|MSVCP|CONCRT|VCOMP|VCCORLIB|MSVCR\d)' })
+            if ($runtime.Count -gt 0) {
+              Write-Host "::error::$($exe.Name) imports the Visual C++ runtime ($($runtime -join ', ')), which Windows does not include."
+              $failed = $true
+            }
+          }
+          if ($failed) { exit 1 }
+
   deny:
     name: deny
     runs-on: ubuntu-latest
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 35cb81a..a827518 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -470,6 +470,33 @@ jobs:
             exit 1
           }
 
+      # The Visual C++ runtime is not part of Windows. Every .exe that gets signed and packaged
+      # (zip and MSI) is inspected, found by search and not by name; none found is a failure.
+      - name: Check the executables need no Visual C++ runtime
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = "Stop"
+          $vswhere = Join-Path ${env:ProgramFiles(x86)} "Microsoft Visual Studio\Installer\vswhere.exe"
+          if (-not (Test-Path -LiteralPath $vswhere)) { throw "vswhere.exe not found at $vswhere" }
+          $dumpbin = & $vswhere -latest -products * -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 -find "VC\Tools\MSVC\**\bin\Hostx64\x64\dumpbin.exe" | Select-Object -First 1
+          if (-not $dumpbin -or -not (Test-Path -LiteralPath $dumpbin)) { throw "dumpbin.exe not found through vswhere" }
+          $exes = @(Get-ChildItem -LiteralPath stage -Recurse -File -Filter *.exe)
+          if ($exes.Count -eq 0) { throw "No .exe found to inspect in stage" }
+          $failed = $false
+          foreach ($exe in $exes) {
+            $output = & $dumpbin /nologo /dependents $exe.FullName
+            if ($LASTEXITCODE -ne 0) { throw "dumpbin failed on $($exe.FullName)" }
+            $imports = @($output | ForEach-Object { $_.Trim() } | Where-Object { $_ -match '^\S+\.dll$' })
+            if ($imports.Count -eq 0) { throw "No imports parsed from $($exe.FullName)" }
+            Write-Host "$($exe.Name): $($imports -join ', ')"
+            $runtime = @($imports | Where-Object { $_ -match '^(VCRUNTIME|MSVCP|CONCRT|VCOMP|VCCORLIB|MSVCR\d)' })
+            if ($runtime.Count -gt 0) {
+              Write-Host "::error::$($exe.Name) imports the Visual C++ runtime ($($runtime -join ', ')), which Windows does not include."
+              $failed = $true
+            }
+          }
+          if ($failed) { exit 1 }
+
       - name: Check the signing inputs are present
         if: env.SIGN == 'true'
         shell: pwsh
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5929a08..f734fdd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,12 @@ commands, `--json` output and exit codes. Each release's notes start with its se
 - `install.sh` now looks up the latest release over HTTPS only, with TLS 1.2 or newer, as the
   download already did, so a redirect cannot lead that lookup to another protocol.
   ([#106](https://github.com/Hodeitek/hodeishield-cli/issues/106))
+- The Windows executable no longer needs the Visual C++ Redistributable. It now carries its C
+  runtime, and the build checks that no shipped `.exe` imports the Visual C++ runtime (`VCRUNTIME*`,
+  `MSVCP*`, `CONCRT*` and the like). This applies to the published executables: a build with
+  `cargo install --git` does not read the repository's `.cargo/config.toml`, which is harmless
+  there because whoever builds it has the Visual C++ tools installed.
+  ([#110](https://github.com/Hodeitek/hodeishield-cli/issues/110))
 - `hodeishield login` now checks that the system keychain can keep a session before it opens the
   browser or shows a device code, and stops there with the usual pointer to API keys. If saving the
   session still fails after the app has issued tokens, the CLI revokes the refresh token and then

From 2cd9bb4f5e5034f393eb5a9eefbe5533a6bb1355 Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Sat, 10 Oct 2026 20:20:35 +0200
Subject: [PATCH 33/57] Report an unreachable keychain as not authenticated

In a session where the platform credential store cannot be reached,
such as an SSH logon on Windows (ERROR_NO_SUCH_LOGON_SESSION) or a
Secret Service on Linux that is locked or does not answer, reading the
stored sign-in failed with the keychain's raw error and exit code 1. Only a keychain
that could not be opened at all was explained, so `whoami` and every
API command printed "system keychain: Couldn't access platform
storage" instead of the documented not-authenticated result.

A PlatformFailure or NoStorageAccess answer when reading the sign-in
is now worded as an unavailable keychain, and that is reported as
exit code 3 saying the system keychain is not available in this
session, with the hint to set HODEISHIELD_API_KEY in remote or
automated sessions; the platform's own advice stays in the hint. When the key is set it is used before the store is
consulted, as before. `login` keeps refusing without a usable store.

Closes #111

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 CHANGELOG.md                                  |   6 +
 README.md                                     |   7 +-
 crates/hodeishield-cli/src/auth/mod.rs        | 162 ++++++++++++++++--
 crates/hodeishield-cli/src/auth/store.rs      |  15 +-
 .../hodeishield-cli/src/commands/session.rs   |  80 ++++++++-
 5 files changed, 249 insertions(+), 21 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f734fdd..6b5e03e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,12 @@ commands, `--json` output and exit codes. Each release's notes start with its se
 - `install.sh` now looks up the latest release over HTTPS only, with TLS 1.2 or newer, as the
   download already did, so a redirect cannot lead that lookup to another protocol.
   ([#106](https://github.com/Hodeitek/hodeishield-cli/issues/106))
+- In a session where the system keychain cannot be reached (a Windows SSH or other network logon,
+  or a Secret Service on Linux that is locked or does not answer) and no API key is set, commands
+  such as `whoami` no longer fail with a raw platform error and exit code 1. They now say that the system keychain is not available in
+  this session, suggest `HODEISHIELD_API_KEY` for remote and automated sessions, and exit with 3,
+  the code for "not authenticated". With the key set, nothing changes.
+  ([#111](https://github.com/Hodeitek/hodeishield-cli/issues/111))
 - The Windows executable no longer needs the Visual C++ Redistributable. It now carries its C
   runtime, and the build checks that no shipped `.exe` imports the Visual C++ runtime (`VCRUNTIME*`,
   `MSVCP*`, `CONCRT*` and the like). This applies to the published executables: a build with
diff --git a/README.md b/README.md
index d022ff6..98944ee 100644
--- a/README.md
+++ b/README.md
@@ -299,6 +299,11 @@ Service — GNOME Keyring, KWallet — on Linux) and refreshed automatically, al
 access token early. Without a keychain, signing in is refused rather than falling back to a file: use
 an API key there.
 
+The keychain can also be out of reach in a session that has one on the machine, such as an SSH or
+other remote logon on Windows. With no API key set, commands then stop with exit code 3 and say that
+the system keychain is not available in this session; set `HODEISHIELD_API_KEY` in remote or
+automated sessions. With the key set, the keychain is not read at all.
+
 To cut the CLI's access from elsewhere, revoke it in [the app](https://app.hodeishield.com) under
 **Account → Application access**. Signing out of the web app does not cut it.
 
@@ -362,7 +367,7 @@ hodeishield vendors list --all --csv > vendors.csv
 | 0 | Success |
 | 1 | Error (invalid input, configuration, unexpected answer) |
 | 2 | Invalid command line |
-| 3 | Not authenticated: no credential, or the API rejected it |
+| 3 | Not authenticated: no credential (also when the system keychain cannot be reached in this session), or the API rejected it |
 | 4 | The credential lacks the scope the command needs |
 | 5 | Not found (or not in your organisation) |
 | 6 | Rate limit exhausted (the CLI already retried short waits) |
diff --git a/crates/hodeishield-cli/src/auth/mod.rs b/crates/hodeishield-cli/src/auth/mod.rs
index b6790d0..b7a7acd 100644
--- a/crates/hodeishield-cli/src/auth/mod.rs
+++ b/crates/hodeishield-cli/src/auth/mod.rs
@@ -39,13 +39,23 @@ pub fn credential_for_api(
     settings: &Settings,
     store: &dyn TokenStore,
 ) -> Result<(SecretString, CredentialSource)> {
-    if let Some(key) = api_key_from_env() {
+    credential_with(api_key_from_env(), settings, store)
+}
+
+/// [`credential_for_api`] with the environment's API key given, so it can be tested without
+/// touching the process environment. With a key, the store is not read.
+fn credential_with(
+    env_key: Option<SecretString>,
+    settings: &Settings,
+    store: &dyn TokenStore,
+) -> Result<(SecretString, CredentialSource)> {
+    if let Some(key) = env_key {
         return Ok((key, CredentialSource::ApiKey));
     }
     let token = match current_token(settings, store) {
         Ok(Some(token)) => token,
         Ok(None) => return Err(not_signed_in(settings)),
-        Err(failure) => return Err(explain_store_failure(failure, settings)),
+        Err(failure) => return Err(explain_store_failure(failure)),
     };
     // A sign-in token only goes to the API it was obtained for: a changed profile, environment or
     // `--api-url` must not be able to send it elsewhere.
@@ -81,19 +91,30 @@ pub fn not_signed_in(settings: &Settings) -> Failure {
     ))
 }
 
-/// Turns a raw store failure into words about what to do, when the underlying reason is that this
-/// machine has no keychain to sign in to. Any other store failure (a corrupt entry, say) passes
-/// through unchanged: it already says what happened.
-pub fn explain_store_failure(failure: Failure, settings: &Settings) -> Failure {
-    if failure.message.starts_with(store::KEYCHAIN_UNAVAILABLE) {
-        not_signed_in(settings).hint(format!(
-            "Set a tenant API key: export {API_KEY_ENV}=<key>. Signing in is not possible on \
-             this machine: {}.",
-            failure.message
-        ))
+/// Turns a store failure into words about what to do, when the underlying reason is that the
+/// keychain cannot be reached (none on this machine, or not from this session, as over SSH on
+/// Windows): it is "not authenticated" (exit code 3), with a pointer to the API key. Any other
+/// store failure (a corrupt entry, say) passes through unchanged: it already says what happened.
+pub fn explain_store_failure(failure: Failure) -> Failure {
+    let Some(rest) = failure.message.strip_prefix(store::KEYCHAIN_UNAVAILABLE) else {
+        return failure;
+    };
+    let reason = rest.trim_start_matches(':').trim();
+    let detail = if reason.is_empty() {
+        String::new()
     } else {
-        failure
-    }
+        format!(": {reason}")
+    };
+    Failure::new(
+        Kind::NotAuthenticated,
+        format!("The system keychain is not available in this session{detail}"),
+    )
+    .hint(match failure.hint {
+        // Keep what the store said about this platform (allow the Keychain prompt, start a Secret
+        // Service...), then the way out that works in a remote session.
+        Some(platform) => format!("{platform} In remote or automated sessions, set {API_KEY_ENV}."),
+        None => format!("In remote or automated sessions, set {API_KEY_ENV}."),
+    })
 }
 
 /// The profile's sign-in token, refreshed when needed. `None` when not signed in.
@@ -461,4 +482,117 @@ mod tests {
             "the dead token is removed"
         );
     }
+
+    /// A store whose answer is fixed; with `panic_on_use` it proves the store is never touched.
+    struct FixedStore {
+        load_error: std::sync::Mutex<Option<keyring_core::Error>>,
+        panic_on_use: bool,
+    }
+
+    impl TokenStore for FixedStore {
+        fn load(&self, _profile: &str) -> Result<Option<StoredToken>> {
+            assert!(!self.panic_on_use, "the store must not be read");
+            match self.load_error.lock().expect("lock").take() {
+                Some(error) => Err(store::read_failure(error)),
+                None => Ok(None),
+            }
+        }
+        fn save(&self, _: &str, _: &StoredToken) -> Result<()> {
+            unreachable!()
+        }
+        fn delete(&self, _: &str) -> Result<bool> {
+            unreachable!()
+        }
+        fn check_available(&self, _: &str) -> Result<()> {
+            unreachable!()
+        }
+    }
+
+    fn io_error() -> Box<dyn std::error::Error + Send + Sync> {
+        "Windows ERROR_NO_SUCH_LOGON_SESSION".into()
+    }
+
+    fn assert_keychain_unreachable(error: keyring_core::Error) {
+        let store = FixedStore {
+            load_error: std::sync::Mutex::new(Some(error)),
+            panic_on_use: false,
+        };
+        let err = credential_with(None, &settings("https://app.example.test"), &store)
+            .expect_err("no credential");
+        assert_eq!(err.kind, Kind::NotAuthenticated);
+        assert!(
+            err.message
+                .contains("keychain is not available in this session"),
+            "{}",
+            err.message
+        );
+        let hint = err.hint.expect("hint");
+        // The platform's own advice stays, followed by the remote-session one.
+        assert!(
+            hint.starts_with("Sign-in tokens are only kept in the system keychain."),
+            "{hint}"
+        );
+        assert!(
+            hint.ends_with(" In remote or automated sessions, set HODEISHIELD_API_KEY."),
+            "{hint}"
+        );
+    }
+
+    #[test]
+    fn an_unreachable_keychain_is_not_authenticated_not_a_raw_error() {
+        assert_keychain_unreachable(keyring_core::Error::NoStorageAccess(io_error()));
+    }
+
+    #[test]
+    fn a_platform_failure_reading_the_keychain_is_the_same() {
+        assert_keychain_unreachable(keyring_core::Error::PlatformFailure(io_error()));
+    }
+
+    #[test]
+    fn another_store_failure_is_left_as_it_is() {
+        let failure = explain_store_failure(Failure::general("system keychain: broken entry"));
+        assert_eq!(failure.kind, Kind::General);
+        assert_eq!(failure.message, "system keychain: broken entry");
+    }
+
+    #[test]
+    fn a_failure_without_a_platform_hint_gets_only_the_api_key_one() {
+        let failure = explain_store_failure(Failure::general(format!(
+            "{}: no Secret Service",
+            store::KEYCHAIN_UNAVAILABLE
+        )));
+        assert_eq!(failure.kind, Kind::NotAuthenticated);
+        assert_eq!(
+            failure.hint.as_deref(),
+            Some("In remote or automated sessions, set HODEISHIELD_API_KEY.")
+        );
+    }
+
+    #[test]
+    fn another_keyring_error_stays_a_general_keychain_failure() {
+        let failure = store::read_failure(keyring_core::Error::BadEncoding(vec![0xff]));
+        assert_eq!(failure.kind, Kind::General);
+        assert!(
+            failure.message.starts_with("system keychain:"),
+            "{}",
+            failure.message
+        );
+        assert_eq!(explain_store_failure(failure).kind, Kind::General);
+    }
+
+    #[test]
+    fn an_api_key_in_the_environment_never_touches_the_store() {
+        let store = FixedStore {
+            load_error: std::sync::Mutex::new(None),
+            panic_on_use: true,
+        };
+        let (key, source) = credential_with(
+            Some(SecretString::from("key_1")),
+            &settings("https://app.example.test"),
+            &store,
+        )
+        .expect("key used");
+        assert_eq!(key.expose_secret(), "key_1");
+        assert!(matches!(source, CredentialSource::ApiKey));
+    }
 }
diff --git a/crates/hodeishield-cli/src/auth/store.rs b/crates/hodeishield-cli/src/auth/store.rs
index ae1cace..78edfb6 100644
--- a/crates/hodeishield-cli/src/auth/store.rs
+++ b/crates/hodeishield-cli/src/auth/store.rs
@@ -163,6 +163,19 @@ fn keychain_failure(error: keyring_core::Error) -> Failure {
     Failure::general(format!("system keychain: {error}"))
 }
 
+/// The failure for a keychain read that did not find an entry. When the platform store cannot be
+/// reached from this session (Windows ERROR_NO_SUCH_LOGON_SESSION over SSH, no Secret Service on
+/// Linux), it is worded as an unavailable keychain, which `explain_store_failure` turns into "not
+/// authenticated"; anything else is a plain keychain failure.
+pub(crate) fn read_failure(error: keyring_core::Error) -> Failure {
+    match error {
+        keyring_core::Error::PlatformFailure(_) | keyring_core::Error::NoStorageAccess(_) => {
+            unavailable(&error.to_string())
+        }
+        other => keychain_failure(other),
+    }
+}
+
 impl TokenStore for Keychain {
     fn load(&self, profile: &str) -> Result<Option<StoredToken>> {
         let entry = entry(profile)?;
@@ -175,7 +188,7 @@ impl TokenStore for Keychain {
                 Ok(Some(StoredToken::from_payload(payload)))
             }
             Err(keyring_core::Error::NoEntry) => Ok(None),
-            Err(e) => Err(keychain_failure(e)),
+            Err(e) => Err(read_failure(e)),
         }
     }
 
diff --git a/crates/hodeishield-cli/src/commands/session.rs b/crates/hodeishield-cli/src/commands/session.rs
index 3ab1bf0..f8c84e1 100644
--- a/crates/hodeishield-cli/src/commands/session.rs
+++ b/crates/hodeishield-cli/src/commands/session.rs
@@ -192,16 +192,33 @@ fn logout_with(settings: &crate::config::Settings, store: &dyn auth::TokenStore)
 
 pub fn whoami(ctx: &Context, out: &mut dyn Write) -> Result<()> {
     let settings = ctx.settings()?;
+    whoami_with(
+        &settings,
+        auth::api_key_from_env().is_some(),
+        ctx.store.as_ref(),
+        ctx.json,
+        out,
+    )
+}
+
+/// `whoami` with the settings and whether an API key is set given, so it can be tested without the
+/// process environment. With a key, the store is not read.
+fn whoami_with(
+    settings: &crate::config::Settings,
+    has_api_key: bool,
+    store: &dyn auth::TokenStore,
+    json: bool,
+    out: &mut dyn Write,
+) -> Result<()> {
     let mut info = Map::new();
     info.insert("profile".into(), json!(settings.profile));
     info.insert("api_url".into(), json!(settings.api_url.as_str()));
     info.insert("app_url".into(), json!(settings.app_url.as_str()));
 
-    let source = if auth::api_key_from_env().is_some() {
+    let source = if has_api_key {
         Some(CredentialSource::ApiKey)
     } else {
-        let existing = auth::current_token(&settings, ctx.store.as_ref())
-            .map_err(|failure| auth::explain_store_failure(failure, &settings))?;
+        let existing = auth::current_token(settings, store).map_err(auth::explain_store_failure)?;
         match existing {
             Some(token) => {
                 info.insert("issuer".into(), json!(token.issuer));
@@ -235,7 +252,7 @@ pub fn whoami(ctx: &Context, out: &mut dyn Write) -> Result<()> {
         })),
     );
 
-    if ctx.json {
+    if json {
         print_json(out, &Value::Object(info))?;
     } else {
         let mut rows = vec![
@@ -266,7 +283,7 @@ pub fn whoami(ctx: &Context, out: &mut dyn Write) -> Result<()> {
     }
     match source {
         Some(_) => Ok(()),
-        None => Err(auth::not_signed_in(&settings)),
+        None => Err(auth::not_signed_in(settings)),
     }
 }
 
@@ -630,6 +647,59 @@ mod tests {
         .expect("settings")
     }
 
+    /// A store whose keychain cannot be reached from this session; reading is the only thing it does.
+    struct UnreachableStore;
+
+    impl TokenStore for UnreachableStore {
+        fn load(&self, _profile: &str) -> Result<Option<StoredToken>> {
+            Err(crate::auth::store::read_failure(
+                keyring_core::Error::NoStorageAccess("Windows ERROR_NO_SUCH_LOGON_SESSION".into()),
+            ))
+        }
+        fn save(&self, _: &str, _: &StoredToken) -> Result<()> {
+            unreachable!()
+        }
+        fn delete(&self, _: &str) -> Result<bool> {
+            unreachable!()
+        }
+        fn check_available(&self, _: &str) -> Result<()> {
+            unreachable!()
+        }
+    }
+
+    #[test]
+    fn whoami_with_an_unreachable_keychain_is_not_authenticated() {
+        let (api, app) = (mockito::Server::new(), mockito::Server::new());
+        let settings = settings_for(&api, &app);
+        let mut out = Vec::new();
+        let err = whoami_with(&settings, false, &UnreachableStore, false, &mut out)
+            .expect_err("no credential");
+        assert_eq!(err.kind, crate::failure::Kind::NotAuthenticated);
+        assert!(
+            err.message
+                .starts_with("The system keychain is not available in this session"),
+            "{}",
+            err.message
+        );
+        assert!(
+            err.hint.as_deref().is_some_and(
+                |h| h.ends_with("In remote or automated sessions, set HODEISHIELD_API_KEY.")
+            ),
+            "{:?}",
+            err.hint
+        );
+        assert!(out.is_empty(), "nothing is printed before the failure");
+    }
+
+    #[test]
+    fn whoami_with_an_api_key_does_not_read_the_store() {
+        let (api, app) = (mockito::Server::new(), mockito::Server::new());
+        let settings = settings_for(&api, &app);
+        let mut out = Vec::new();
+        whoami_with(&settings, true, &UnreachableStore, true, &mut out).expect("key set");
+        assert!(String::from_utf8(out).expect("utf8").contains("api_key"));
+    }
+
     const DEVICE: LoginArgs = LoginArgs {
         device: true,
         no_browser: false,

From 6b34c31aea95cd25ca800b704e987c304e13b2cd Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Sat, 10 Oct 2026 20:20:49 +0200
Subject: [PATCH 34/57] Document the silent MSI exit code and Scoop
 prerequisites

Measured on Windows: a bare `msiexec /i ...` in PowerShell returns
immediately while the installer keeps running, so `$LASTEXITCODE` is
not the installer's result. Show `Start-Process -Wait -PassThru` for
both install and uninstall, with a log, and say why.

On a fresh Scoop, `scoop bucket add` needs Git, and Scoop's installer
refuses an elevated shell unless run with -RunAsAdmin. Say so, and keep
the per-user, non-administrator install as the recommended path.

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 README.md | 21 +++++++++++++++------
 1 file changed, 15 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 98944ee..698dbe6 100644
--- a/README.md
+++ b/README.md
@@ -71,6 +71,10 @@ scoop bucket add hodeishield https://github.com/Hodeitek/scoop-hodeishield
 scoop install hodeishield                                       # Windows, per user
 ```
 
+`scoop bucket add` needs Git: on a fresh Scoop, run `scoop install git` first. Scoop's own installer
+refuses an elevated (administrator) shell unless it is run with `-RunAsAdmin`; installing per user,
+from a normal shell, is the recommended way and needs no administrator rights.
+
 The [Homebrew tap](https://github.com/Hodeitek/homebrew-hodeishield) and the
 [Scoop bucket](https://github.com/Hodeitek/scoop-hodeishield) are updated from each release's own
 files and `SHA256SUMS` when it is published, and both check those hashes when installing. Homebrew
@@ -105,15 +109,20 @@ Silent installation, for Intune, Group Policy or any other deployment tool:
 $p = Start-Process msiexec -Wait -PassThru -ArgumentList '/i hodeishield-<version>-x86_64-pc-windows-msvc.msi /qn /norestart /l*v hodeishield-install.log'
 $p.ExitCode      # 0 = installed, 3010 = installed and a restart is pending
 # uninstall
-Start-Process msiexec -Wait -PassThru -ArgumentList '/x hodeishield-<version>-x86_64-pc-windows-msvc.msi /qn /norestart'
+$p = Start-Process msiexec -Wait -PassThru -ArgumentList '/x hodeishield-<version>-x86_64-pc-windows-msvc.msi /qn /norestart /l*v hodeishield-uninstall.log'
+$p.ExitCode
 ```
 
-Run `msiexec` through `Start-Process -Wait`: PowerShell does not wait for it when it is called
-directly, so `$LASTEXITCODE` would be set before the install finishes. From `cmd.exe`, use
-`start /wait msiexec /i ...`.
+Run `msiexec` through `Start-Process -Wait -PassThru` in PowerShell. Called directly, as
+`msiexec /i ...`, it returns at once while the installer keeps running, and `$LASTEXITCODE` is not
+updated (it keeps the value of an earlier command), so a script would carry on before the install
+is done and could not tell whether it worked. From `cmd.exe`, use `start /wait msiexec /i ...`. Deployment tools such as Intune and Group Policy
+run the installer themselves and wait for it as usual.
 
-- **Intune:** add it as a *Line-of-business app* (MSI), or as a *Windows app (Win32)* with the
-  commands above. Intune reads the product code from the MSI for detection.
+- **Intune:** add it as a *Line-of-business app* (MSI), or as a *Windows app (Win32)* whose install
+  command is the plain command line
+  `msiexec /i hodeishield-<version>-x86_64-pc-windows-msvc.msi /qn /norestart` (and the same with
+  `/x` to uninstall), not the PowerShell snippet above. Intune reads the product code from the MSI for detection.
 - **Group Policy:** *Computer Configuration → Policies → Software Settings → Software installation*,
   assign the MSI from a network share that the computers can read.
 - Every version shares the upgrade code `{32B34E35-7A3F-422A-AC44-59204CD0D59D}`, which detection

From 22999704062fcf70c3e6efb15cf122004cdc5b4a Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Sun, 11 Oct 2026 00:25:27 +0200
Subject: [PATCH 35/57] Note when Unblock-File matters on Windows

Refs #16.

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index ac0b3a2..c230806 100644
--- a/README.md
+++ b/README.md
@@ -252,7 +252,7 @@ Unblock-File .\hodeishield-0.1.1-x86_64-pc-windows-msvc.zip
 Expand-Archive .\hodeishield-0.1.1-x86_64-pc-windows-msvc.zip
 ```
 
-If you already unpacked it, run `Unblock-File` on `hodeishield.exe` instead. SmartScreen can also
+If you already unpacked it, run `Unblock-File` on `hodeishield.exe` instead. Windows PowerShell 5.1's `Expand-Archive` does not copy the download mark to the unpacked files, so unblocking matters when you unpack with File Explorer's "Extract All" or another tool that carries the mark over. SmartScreen can also
 warn about a signed file that is still new to it; in either case, if it shows "Windows protected
 your PC", choose **More info → Run anyway** («Más información → Ejecutar de todos modos» on a
 Spanish system).

From 874c8a86689ae5cf7482e43ea055c90691d85f8d Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Sun, 11 Oct 2026 12:09:00 +0200
Subject: [PATCH 36/57] Mark a closed pipe only where standard output is
 written

Converting any std::io::Error into a Failure set closed_pipe whenever
its kind was BrokenPipe. A broken pipe from a socket, a file or a
config write would then end the command with exit code 0 and no message,
the same class of bug as a failed command exiting 0.

Standard output now goes through a small tracking writer that records
whether a write or flush failed with BrokenPipe, and only that turns a
failure into a silent exit 0 (`hodeishield vendors list | head -1`).
The conversion from io::Error never sets closed_pipe. The mapping from
the outcome to the exit code is its own function so it can be tested.

Refs #105

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 crates/hodeishield-cli/src/failure.rs | 31 +++++++----
 crates/hodeishield-cli/src/lib.rs     | 75 +++++++++++++++++++++++++--
 crates/hodeishield-cli/src/output.rs  | 41 +++++++++++++++
 3 files changed, 132 insertions(+), 15 deletions(-)

diff --git a/crates/hodeishield-cli/src/failure.rs b/crates/hodeishield-cli/src/failure.rs
index 11bf927..9eae9e3 100644
--- a/crates/hodeishield-cli/src/failure.rs
+++ b/crates/hodeishield-cli/src/failure.rs
@@ -48,11 +48,12 @@ pub struct Failure {
     pub message: String,
     pub hint: Option<String>,
     pub request_id: Option<String>,
-    /// Whether this failure came from an I/O error of kind [`std::io::ErrorKind::BrokenPipe`]
-    /// (the reader went away: `hodeishield ... | head -1`). It is set in one place, the conversion
-    /// from [`std::io::Error`], and never from message text, which can come from the API. It only
-    /// means "output pipe closed" because the commands write to standard output with `?` on
-    /// `io::Error` and nothing else does; keep it that way.
+    /// Whether this failure is the reader of standard output going away
+    /// (`hodeishield ... | head -1`). Only [`Failure::closed_stdout`] sets it, and the caller does
+    /// that only for an `io::Error` of kind [`std::io::ErrorKind::BrokenPipe`] seen while writing
+    /// to standard output (see `output::Tracked`). The conversion from [`std::io::Error`] never
+    /// sets it: a broken pipe on a socket, a file or a config write is a real failure, and so is
+    /// message text, which can come from the API.
     pub closed_pipe: bool,
 }
 
@@ -71,6 +72,13 @@ impl Failure {
         Self::new(Kind::General, message)
     }
 
+    /// Marks this failure as the reader of standard output having gone away.
+    #[must_use]
+    pub fn closed_stdout(mut self) -> Self {
+        self.closed_pipe = true;
+        self
+    }
+
     #[must_use]
     pub fn hint(mut self, hint: impl Into<String>) -> Self {
         self.hint = Some(hint.into());
@@ -86,9 +94,7 @@ impl fmt::Display for Failure {
 
 impl From<std::io::Error> for Failure {
     fn from(error: std::io::Error) -> Self {
-        let mut failure = Self::general(error.to_string());
-        failure.closed_pipe = error.kind() == std::io::ErrorKind::BrokenPipe;
-        failure
+        Self::general(error.to_string())
     }
 }
 
@@ -247,9 +253,14 @@ mod tests {
     use std::io::{Error, ErrorKind};
 
     #[test]
-    fn only_a_broken_pipe_io_error_marks_a_closed_pipe() {
-        assert!(Failure::from(Error::from(ErrorKind::BrokenPipe)).closed_pipe);
+    fn converting_an_io_error_never_marks_a_closed_pipe() {
+        assert!(!Failure::from(Error::from(ErrorKind::BrokenPipe)).closed_pipe);
         assert!(!Failure::from(Error::from(ErrorKind::NotFound)).closed_pipe);
+        assert!(
+            Failure::from(Error::from(ErrorKind::BrokenPipe))
+                .closed_stdout()
+                .closed_pipe
+        );
     }
 
     #[test]
diff --git a/crates/hodeishield-cli/src/lib.rs b/crates/hodeishield-cli/src/lib.rs
index d370d59..ac6a00c 100644
--- a/crates/hodeishield-cli/src/lib.rs
+++ b/crates/hodeishield-cli/src/lib.rs
@@ -16,7 +16,7 @@ mod filters;
 mod output;
 mod update_check;
 
-use std::io::{ErrorKind, Write};
+use std::io::Write;
 use std::process::ExitCode;
 
 pub const USER_AGENT: &str = concat!(
@@ -32,22 +32,41 @@ pub fn main() -> ExitCode {
     let for_programs = cli.prints_for_programs();
     let verbose = cli.verbose;
     let stdout = std::io::stdout();
-    let mut out = std::io::BufWriter::new(stdout.lock());
+    let mut out = std::io::BufWriter::new(output::Tracked::new(stdout.lock()));
     let result = commands::run(cli, &mut out);
     let flushed = out.flush();
+    let stdout_closed = out.get_ref().closed();
     // After the command's own work and output, so it never delays them.
     update_check::notify(for_programs, verbose);
+    exit_code(result, flushed, stdout_closed)
+}
+
+/// Reports the outcome and maps it to the exit code. `stdout_closed` says that writing to
+/// standard output failed with a broken pipe (`hodeishield vendors list | head -1`): that is not
+/// an error. A broken pipe from anywhere else is, and the exit code says so.
+fn exit_code(
+    result: failure::Result<()>,
+    flushed: std::io::Result<()>,
+    stdout_closed: bool,
+) -> ExitCode {
+    let result = result.map_err(|failure| {
+        if stdout_closed {
+            failure.closed_stdout()
+        } else {
+            failure
+        }
+    });
     match result {
         Ok(()) => match flushed {
             Ok(()) => ExitCode::SUCCESS,
-            // `hodeishield vendors list | head` closes the pipe early: that is not an error.
-            Err(e) if e.kind() == ErrorKind::BrokenPipe => ExitCode::SUCCESS,
+            Err(_) if stdout_closed => ExitCode::SUCCESS,
             Err(e) => {
                 eprintln!("error: {e}");
                 ExitCode::FAILURE
             }
         },
-        // Decided on the I/O error kind, never on message text, which can come from the API.
+        // Decided where standard output is written, never on message text (which can come from
+        // the API) nor on the kind of an error from somewhere else.
         Err(failure) if failure.closed_pipe => ExitCode::SUCCESS,
         Err(failure) => {
             // Messages can carry text from the API or the app: clean it like any other output.
@@ -62,3 +81,49 @@ pub fn main() -> ExitCode {
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::io::{Error, ErrorKind};
+
+    fn is_success(code: ExitCode) -> bool {
+        format!("{code:?}") == format!("{:?}", ExitCode::SUCCESS)
+    }
+
+    #[test]
+    fn a_closed_standard_output_exits_0() {
+        let failure = failure::Failure::from(Error::from(ErrorKind::BrokenPipe));
+        assert!(is_success(exit_code(Err(failure), Ok(()), true)));
+        let flush = Err(Error::from(ErrorKind::BrokenPipe));
+        assert!(is_success(exit_code(Ok(()), flush, true)));
+    }
+
+    #[test]
+    fn a_broken_pipe_from_somewhere_else_is_a_failure() {
+        // A socket, a file or a config write failing with a broken pipe is not a closed reader.
+        let failure = failure::Failure::from(Error::from(ErrorKind::BrokenPipe));
+        assert!(!is_success(exit_code(Err(failure), Ok(()), false)));
+        let flush = Err(Error::from(ErrorKind::BrokenPipe));
+        assert!(!is_success(exit_code(Ok(()), flush, false)));
+    }
+
+    #[test]
+    fn tracked_output_notices_only_a_broken_pipe() {
+        struct Failing(ErrorKind);
+        impl Write for Failing {
+            fn write(&mut self, _: &[u8]) -> std::io::Result<usize> {
+                Err(Error::from(self.0))
+            }
+            fn flush(&mut self) -> std::io::Result<()> {
+                Err(Error::from(self.0))
+            }
+        }
+        let mut other = output::Tracked::new(Failing(ErrorKind::PermissionDenied));
+        assert!(other.write_all(b"x").is_err());
+        assert!(!other.closed());
+        let mut closed = output::Tracked::new(Failing(ErrorKind::BrokenPipe));
+        assert!(closed.write_all(b"x").is_err());
+        assert!(closed.closed());
+    }
+}
diff --git a/crates/hodeishield-cli/src/output.rs b/crates/hodeishield-cli/src/output.rs
index 53b40ec..4357c2f 100644
--- a/crates/hodeishield-cli/src/output.rs
+++ b/crates/hodeishield-cli/src/output.rs
@@ -10,6 +10,47 @@ use comfy_table::{ContentArrangement, Table, presets};
 use serde_json::Value;
 use std::io::Write;
 
+/// Standard output (or any writer) that remembers whether a write or flush failed with
+/// [`std::io::ErrorKind::BrokenPipe`], so the caller can tell "the reader of standard output went
+/// away" from a broken pipe anywhere else (a socket, a file), which must stay a failure.
+pub struct Tracked<W> {
+    inner: W,
+    closed: bool,
+}
+
+impl<W> Tracked<W> {
+    pub fn new(inner: W) -> Self {
+        Self {
+            inner,
+            closed: false,
+        }
+    }
+
+    /// Whether a write or flush hit a closed pipe.
+    pub fn closed(&self) -> bool {
+        self.closed
+    }
+
+    fn note<T>(&mut self, result: std::io::Result<T>) -> std::io::Result<T> {
+        if let Err(e) = &result {
+            self.closed |= e.kind() == std::io::ErrorKind::BrokenPipe;
+        }
+        result
+    }
+}
+
+impl<W: Write> Write for Tracked<W> {
+    fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
+        let result = self.inner.write(buf);
+        self.note(result)
+    }
+
+    fn flush(&mut self) -> std::io::Result<()> {
+        let result = self.inner.flush();
+        self.note(result)
+    }
+}
+
 /// Replaces control characters (escape sequences, carriage returns, …) with `�`.
 pub fn clean(text: &str) -> String {
     text.chars()

From 363a6b0e5519b6f606f6747c11b0dd21ec167a48 Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Sun, 11 Oct 2026 12:09:42 +0200
Subject: [PATCH 37/57] Rewrap the Unblock-File paragraph in the README

The paragraph added with the Windows unblock note was a single 311-column line, unlike the rest of the file, which wraps near 100 columns. Only line breaks change; no word does.

Refs #16

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 README.md | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index c230806..74653af 100644
--- a/README.md
+++ b/README.md
@@ -252,10 +252,12 @@ Unblock-File .\hodeishield-0.1.1-x86_64-pc-windows-msvc.zip
 Expand-Archive .\hodeishield-0.1.1-x86_64-pc-windows-msvc.zip
 ```
 
-If you already unpacked it, run `Unblock-File` on `hodeishield.exe` instead. Windows PowerShell 5.1's `Expand-Archive` does not copy the download mark to the unpacked files, so unblocking matters when you unpack with File Explorer's "Extract All" or another tool that carries the mark over. SmartScreen can also
-warn about a signed file that is still new to it; in either case, if it shows "Windows protected
-your PC", choose **More info → Run anyway** («Más información → Ejecutar de todos modos» on a
-Spanish system).
+If you already unpacked it, run `Unblock-File` on `hodeishield.exe` instead. Windows PowerShell
+5.1's `Expand-Archive` does not copy the download mark to the unpacked files, so unblocking matters
+when you unpack with File Explorer's "Extract All" or another tool that carries the mark over.
+SmartScreen can also warn about a signed file that is still new to it; in either case, if it shows
+"Windows protected your PC", choose **More info → Run anyway** («Más información → Ejecutar de todos
+modos» on a Spanish system).
 
 ## Authenticate
 

From 14e8377eb0565307218535f2b9ea0ce938987809 Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Sun, 11 Oct 2026 12:09:58 +0200
Subject: [PATCH 38/57] Record the closed pipe narrowing in the changelog

Refs #105

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 CHANGELOG.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 98341c2..7fff2f2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -36,6 +36,11 @@ commands, `--json` output and exit codes. Each release's notes start with its se
   "Broken pipe". The CLI now treats a failure as a closed output pipe (`hodeishield ... | head -1`,
   which still exits 0 silently) only when writing to standard output fails with that I/O error,
   never because of the text of a message. ([#105](https://github.com/Hodeitek/hodeishield-cli/issues/105))
+- A broken pipe from anything other than standard output (a network connection, a file, the
+  configuration being saved) no longer ends a command with exit code 0 and no message. Only a write
+  to standard output that fails because the reader went away is treated as a closed pipe; any other
+  broken pipe is reported as an error with a non-zero exit code.
+  ([#105](https://github.com/Hodeitek/hodeishield-cli/issues/105))
 - A stalled or slow local connection can no longer keep the browser sign-in listener busy past its
   timeout. Each connection now has a total time limit for its request, and no read waits beyond the
   overall sign-in deadline, and the deadline is checked before every connection is accepted, so a

From 43ed68ef1aa9184761681f3e11cdd38fa9662eb3 Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Sun, 11 Oct 2026 12:13:20 +0200
Subject: [PATCH 39/57] Treat only the broken pipe itself as a closed reader

Once standard output has seen a broken pipe, the exit code mapping turned any failure into exit 0. A later, unrelated failure (an API error after the reader went away) must still fail, so the closed reader now applies only to a failure converted from a broken-pipe I/O error, and only when standard output saw one too.

Refs #105.

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 crates/hodeishield-cli/src/failure.rs | 10 +++++++++-
 crates/hodeishield-cli/src/lib.rs     | 19 +++++++++++++++----
 2 files changed, 24 insertions(+), 5 deletions(-)

diff --git a/crates/hodeishield-cli/src/failure.rs b/crates/hodeishield-cli/src/failure.rs
index 9eae9e3..8d7c6eb 100644
--- a/crates/hodeishield-cli/src/failure.rs
+++ b/crates/hodeishield-cli/src/failure.rs
@@ -55,6 +55,11 @@ pub struct Failure {
     /// sets it: a broken pipe on a socket, a file or a config write is a real failure, and so is
     /// message text, which can come from the API.
     pub closed_pipe: bool,
+    /// Whether this failure was converted from an `io::Error` of kind
+    /// [`std::io::ErrorKind::BrokenPipe`], wherever it came from. On its own it means nothing:
+    /// `main` treats the failure as a closed reader only when standard output also saw the
+    /// broken pipe, so an unrelated failure after the reader went away still fails.
+    pub(crate) broken_pipe: bool,
 }
 
 impl Failure {
@@ -65,6 +70,7 @@ impl Failure {
             hint: None,
             request_id: None,
             closed_pipe: false,
+            broken_pipe: false,
         }
     }
 
@@ -94,7 +100,9 @@ impl fmt::Display for Failure {
 
 impl From<std::io::Error> for Failure {
     fn from(error: std::io::Error) -> Self {
-        Self::general(error.to_string())
+        let mut failure = Self::general(error.to_string());
+        failure.broken_pipe = error.kind() == std::io::ErrorKind::BrokenPipe;
+        failure
     }
 }
 
diff --git a/crates/hodeishield-cli/src/lib.rs b/crates/hodeishield-cli/src/lib.rs
index ac6a00c..1974beb 100644
--- a/crates/hodeishield-cli/src/lib.rs
+++ b/crates/hodeishield-cli/src/lib.rs
@@ -42,15 +42,16 @@ pub fn main() -> ExitCode {
 }
 
 /// Reports the outcome and maps it to the exit code. `stdout_closed` says that writing to
-/// standard output failed with a broken pipe (`hodeishield vendors list | head -1`): that is not
-/// an error. A broken pipe from anywhere else is, and the exit code says so.
+/// standard output failed with a broken pipe (`hodeishield vendors list | head -1`): a failure
+/// that is that broken pipe is not an error. A broken pipe from anywhere else is, and so is any
+/// other failure, even after the reader of standard output went away.
 fn exit_code(
     result: failure::Result<()>,
     flushed: std::io::Result<()>,
     stdout_closed: bool,
 ) -> ExitCode {
     let result = result.map_err(|failure| {
-        if stdout_closed {
+        if stdout_closed && failure.broken_pipe {
             failure.closed_stdout()
         } else {
             failure
@@ -59,7 +60,9 @@ fn exit_code(
     match result {
         Ok(()) => match flushed {
             Ok(()) => ExitCode::SUCCESS,
-            Err(_) if stdout_closed => ExitCode::SUCCESS,
+            Err(e) if stdout_closed && e.kind() == std::io::ErrorKind::BrokenPipe => {
+                ExitCode::SUCCESS
+            }
             Err(e) => {
                 eprintln!("error: {e}");
                 ExitCode::FAILURE
@@ -108,6 +111,14 @@ mod tests {
         assert!(!is_success(exit_code(Ok(()), flush, false)));
     }
 
+    #[test]
+    fn another_failure_after_standard_output_closed_is_still_a_failure() {
+        let failure = failure::Failure::general("the API said no");
+        assert!(!is_success(exit_code(Err(failure), Ok(()), true)));
+        let flush = Err(Error::from(ErrorKind::StorageFull));
+        assert!(!is_success(exit_code(Ok(()), flush, true)));
+    }
+
     #[test]
     fn tracked_output_notices_only_a_broken_pipe() {
         struct Failing(ErrorKind);

From 42d4185105ad7f8044530a02050fbbb2c9b6c5c7 Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Sun, 11 Oct 2026 12:21:26 +0200
Subject: [PATCH 40/57] Build, sign and test Windows on Arm

Windows on Arm devices could only run the x64 build under emulation.
Each release now also ships hodeishield-<version>-aarch64-pc-windows-msvc.zip.

The arm64 build runs natively on the windows-11-arm runner, so the C code
of aws-lc-sys is compiled by the toolchain of the target and the CI tests
run where the binary runs. Signing stays on the x64 runner, through the
same release-signing environment and Azure profile as the x64 exe; the
import check now also verifies the PE machine type matches the archive
name. The archive joins SHA256SUMS, the cosign signatures, the provenance
subjects and the SBOM set. The MSI and winget stay x64 only. Scoop lists
the arm64 zip when a release has it.

CI runs the test suite, clippy and the import check on windows-11-arm.

Refs #37

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 .github/scripts/package-manifests.py | 22 ++++++--
 .github/workflows/ci.yml             | 33 +++++++++++-
 .github/workflows/release.yml        | 76 ++++++++++++++++++++++------
 CHANGELOG.md                         | 10 ++++
 CONTRIBUTING.md                      |  4 +-
 README.md                            |  6 ++-
 docs/verifying-releases.md           |  4 ++
 7 files changed, 128 insertions(+), 27 deletions(-)

diff --git a/.github/scripts/package-manifests.py b/.github/scripts/package-manifests.py
index 843a228..aa5d751 100644
--- a/.github/scripts/package-manifests.py
+++ b/.github/scripts/package-manifests.py
@@ -12,7 +12,9 @@
 
 Every URL points at an asset of the release and every hash comes from its SHA256SUMS, so a file
 missing from the release is an error. The winget installer is the MSI when the release has one
-(its product code must then be given), otherwise the zip with the portable exe inside.
+(its product code must then be given), otherwise the zip with the portable exe inside. The Scoop
+manifest also lists the arm64 zip when the release has one; winget stays x64 only until there is an
+arm64 MSI.
 
 Uses only the standard library.
 """
@@ -48,6 +50,9 @@ def asset(target, ext):
     x86_url, x86_sha = asset("x86_64-unknown-linux-musl", "tar.gz")
     arm_url, arm_sha = asset("aarch64-unknown-linux-musl", "tar.gz")
     zip_url, zip_sha = asset("x86_64-pc-windows-msvc", "zip")
+    # Releases before the Windows arm64 build do not have this zip: Scoop then lists 64bit only.
+    has_arm64_zip = f"hodeishield-{version}-aarch64-pc-windows-msvc.zip" in sums
+    arm64_zip_url, arm64_zip_sha = asset("aarch64-pc-windows-msvc", "zip") if has_arm64_zip else (None, None)
     msi_name = f"hodeishield-{version}-x86_64-pc-windows-msvc.msi"
     has_msi = msi_name in sums
     if has_msi and not (product_code and re.fullmatch(r"\{[0-9A-F-]{36}\}", product_code)):
@@ -98,18 +103,25 @@ def install
 
     manifest = out / "scoop" / "bucket" / "hodeishield.json"
     manifest.parent.mkdir(parents=True, exist_ok=True)
+    scoop_arch = {"64bit": {"url": zip_url, "hash": zip_sha}}
+    scoop_autoupdate = {"64bit": {
+        "url": f"https://github.com/{REPO}/releases/download/v$version/hodeishield-$version-x86_64-pc-windows-msvc.zip"
+    }}
+    if has_arm64_zip:
+        scoop_arch["arm64"] = {"url": arm64_zip_url, "hash": arm64_zip_sha}
+        scoop_autoupdate["arm64"] = {
+            "url": f"https://github.com/{REPO}/releases/download/v$version/hodeishield-$version-aarch64-pc-windows-msvc.zip"
+        }
     manifest.write_text(json.dumps({
         "version": version,
         "description": DESCRIPTION,
         "homepage": "https://hodeishield.com",
         "license": "Apache-2.0",
-        "architecture": {"64bit": {"url": zip_url, "hash": zip_sha}},
+        "architecture": scoop_arch,
         "bin": "hodeishield.exe",
         "checkver": {"github": f"https://github.com/{REPO}"},
         "autoupdate": {
-            "architecture": {"64bit": {
-                "url": f"https://github.com/{REPO}/releases/download/v$version/hodeishield-$version-x86_64-pc-windows-msvc.zip"
-            }},
+            "architecture": scoop_autoupdate,
             "hash": {"url": "$baseurl/SHA256SUMS"},
         },
     }, indent=4) + "\n")
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 9aadc5c..217a195 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -85,7 +85,9 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
+        # windows-11-arm is the GitHub-hosted native Windows on Arm runner: the aarch64 Windows
+        # build is tested where it runs, not only cross-compiled.
+        os: [ubuntu-latest, macos-latest, windows-latest, windows-11-arm]
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout
@@ -107,6 +109,10 @@ jobs:
       - name: cargo test
         run: cargo test --workspace --locked
 
+      - name: cargo clippy (Windows on Arm)
+        if: matrix.os == 'windows-11-arm'
+        run: cargo clippy --workspace --all-targets --locked -- -D warnings
+
       # The Visual C++ runtime is not part of Windows: the executable must not import it (see
       # .cargo/config.toml).
       - name: Build the executable (Windows)
@@ -120,7 +126,10 @@ jobs:
           $ErrorActionPreference = "Stop"
           $vswhere = Join-Path ${env:ProgramFiles(x86)} "Microsoft Visual Studio\Installer\vswhere.exe"
           if (-not (Test-Path -LiteralPath $vswhere)) { throw "vswhere.exe not found at $vswhere" }
-          $dumpbin = & $vswhere -latest -products * -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 -find "VC\Tools\MSVC\**\bin\Hostx64\x64\dumpbin.exe" | Select-Object -First 1
+          # The host's own toolset first (exactly what the x64 leg always used), any host otherwise.
+          $arch = if ($env:RUNNER_ARCH -eq "ARM64") { "arm64" } else { "x64" }
+          $dumpbin = & $vswhere -latest -products * -find "VC\Tools\MSVC\**\bin\Host$arch\$arch\dumpbin.exe" | Select-Object -First 1
+          if (-not $dumpbin) { $dumpbin = & $vswhere -latest -products * -find "VC\Tools\MSVC\**\bin\Host*\*\dumpbin.exe" | Select-Object -First 1 }
           if (-not $dumpbin -or -not (Test-Path -LiteralPath $dumpbin)) { throw "dumpbin.exe not found through vswhere" }
           $exes = @(Get-ChildItem -LiteralPath target/debug -File -Filter hodeishield.exe)
           if ($exes.Count -eq 0) { throw "No .exe found to inspect in target/debug" }
@@ -139,6 +148,26 @@ jobs:
           }
           if ($failed) { exit 1 }
 
+      # The leg must build the architecture it is named after, not the host's by accident.
+      - name: Check the executable targets the runner's architecture (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        env:
+          EXPECTED: ${{ matrix.os == 'windows-11-arm' && 'AA64 machine (ARM64)' || '8664 machine (x64)' }}
+        run: |
+          $ErrorActionPreference = "Stop"
+          $vswhere = Join-Path ${env:ProgramFiles(x86)} "Microsoft Visual Studio\Installer\vswhere.exe"
+          # The host's own toolset first (exactly what the x64 leg always used), any host otherwise.
+          $arch = if ($env:RUNNER_ARCH -eq "ARM64") { "arm64" } else { "x64" }
+          $dumpbin = & $vswhere -latest -products * -find "VC\Tools\MSVC\**\bin\Host$arch\$arch\dumpbin.exe" | Select-Object -First 1
+          if (-not $dumpbin) { $dumpbin = & $vswhere -latest -products * -find "VC\Tools\MSVC\**\bin\Host*\*\dumpbin.exe" | Select-Object -First 1 }
+          if (-not $dumpbin -or -not (Test-Path -LiteralPath $dumpbin)) { throw "dumpbin.exe not found through vswhere" }
+          $headers = & $dumpbin /nologo /headers target/debug/hodeishield.exe
+          if ($LASTEXITCODE -ne 0) { throw "dumpbin /headers failed" }
+          if (-not ($headers | Select-String -SimpleMatch $env:EXPECTED -Quiet)) {
+            throw "hodeishield.exe is not a '$env:EXPECTED' executable"
+          }
+
   deny:
     name: deny
     runs-on: ubuntu-latest
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index a827518..f7c59ec 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -392,10 +392,21 @@ jobs:
           if-no-files-found: error
           retention-days: 7
 
+  # x86_64 builds on the x64 runner. arm64 builds natively on the GitHub-hosted Windows 11 Arm
+  # runner (as aarch64 Linux does on ubuntu-24.04-arm), so the C code of aws-lc-sys is compiled by
+  # the toolchain that will also run the CI tests, with no cross-compilation.
   build-windows:
-    name: build (x86_64-pc-windows-msvc)
+    name: build (${{ matrix.target }})
     needs: version
-    runs-on: windows-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: windows-latest
+            target: x86_64-pc-windows-msvc
+          - os: windows-11-arm
+            target: aarch64-pc-windows-msvc
+    runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -406,18 +417,20 @@ jobs:
         run: rustup show
 
       - name: Build
-        run: cargo build --release --locked --target x86_64-pc-windows-msvc -p hodeishield-cli
+        run: cargo build --release --locked --target ${{ matrix.target }} -p hodeishield-cli
 
       - name: Stage the unsigned executable for the signing job
         shell: pwsh
+        env:
+          TARGET: ${{ matrix.target }}
         run: |
           New-Item -ItemType Directory -Path stage | Out-Null
-          Copy-Item -Path "target/x86_64-pc-windows-msvc/release/$env:BIN_NAME.exe", "LICENSE", "NOTICE", "README.md" -Destination stage
+          Copy-Item -Path "target/$env:TARGET/release/$env:BIN_NAME.exe", "LICENSE", "NOTICE", "README.md" -Destination stage
 
       - name: Upload the unsigned executable
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
-          name: unsigned-x86_64-pc-windows-msvc
+          name: unsigned-${{ matrix.target }}
           path: stage/*
           if-no-files-found: error
           retention-days: 1
@@ -432,11 +445,25 @@ jobs:
   # Environment secrets (release-signing): AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_SUBSCRIPTION_ID
   # (directory identifiers, kept out of public logs). Environment variables: AZURE_SIGNING_ENDPOINT,
   # AZURE_SIGNING_ACCOUNT_NAME, AZURE_CERTIFICATE_PROFILE_NAME.
+  #
+  # One job per architecture; each pauses for the same `release-signing` approval. The signing
+  # itself does not depend on the architecture of the exe, so both run on the x64 runner, which
+  # also hosts the x64 dumpbin used to inspect them.
   sign-windows:
-    name: sign and package (x86_64-pc-windows-msvc)
+    name: sign and package (${{ matrix.target }})
     needs: [version, build-windows]
     runs-on: windows-latest
     timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - target: x86_64-pc-windows-msvc
+            key: x64
+            machine: "8664 machine (x64)"
+          - target: aarch64-pc-windows-msvc
+            key: arm64
+            machine: "AA64 machine (ARM64)"
     environment: ${{ needs.version.outputs.sign_windows == 'true' && 'release-signing' || '' }}
     permissions:
       contents: read
@@ -444,15 +471,21 @@ jobs:
     env:
       VERSION: ${{ needs.version.outputs.version }}
       SIGN: ${{ needs.version.outputs.sign_windows }}
+      TARGET: ${{ matrix.target }}
+      MACHINE: ${{ matrix.machine }}
+      KEY: ${{ matrix.key }}
     # The digest of the exe this job hands to the MSI build. A job output cannot be rewritten by
-    # another job, so `windows-msi` checks what it downloads against this, not against a name.
+    # another job, so `windows-msi` checks what it downloads against this, not against a name. The
+    # name carries the architecture, because the legs of a matrix share their outputs otherwise:
+    # each leg sets only its own (output names cannot use expressions).
     outputs:
-      exe_sha256: ${{ steps.handoff.outputs.exe_sha256 }}
+      exe_sha256_x64: ${{ steps.handoff.outputs.exe_sha256_x64 }}
+      exe_sha256_arm64: ${{ steps.handoff.outputs.exe_sha256_arm64 }}
     steps:
       - name: Download the unsigned executable
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
-          name: unsigned-x86_64-pc-windows-msvc
+          name: unsigned-${{ matrix.target }}
           path: stage
 
       # Anything else in the hand-off would be packaged, and possibly signed, as ours.
@@ -494,6 +527,13 @@ jobs:
               Write-Host "::error::$($exe.Name) imports the Visual C++ runtime ($($runtime -join ', ')), which Windows does not include."
               $failed = $true
             }
+            # The archive name says which architecture this is: the file must really be that one.
+            $headers = & $dumpbin /nologo /headers $exe.FullName
+            if ($LASTEXITCODE -ne 0) { throw "dumpbin /headers failed on $($exe.FullName)" }
+            if (-not ($headers | Select-String -SimpleMatch $env:MACHINE -Quiet)) {
+              Write-Host "::error::$($exe.Name) is not a '$env:MACHINE' executable, which $env:TARGET requires."
+              $failed = $true
+            }
           }
           if ($failed) { exit 1 }
 
@@ -567,10 +607,12 @@ jobs:
         shell: pwsh
         run: |
           $hash = (Get-FileHash -LiteralPath stage\hodeishield.exe -Algorithm SHA256).Hash.ToLower()
-          "exe_sha256=$hash" | Out-File -Append -Encoding utf8 $env:GITHUB_OUTPUT
+          "exe_sha256_$env:KEY=$hash" | Out-File -Append -Encoding utf8 $env:GITHUB_OUTPUT
           Write-Host "hodeishield.exe $hash"
 
+      # The MSI is built for x64 only (an arm64 MSI is a follow-up).
       - name: Upload the signed executable for the MSI build
+        if: matrix.key == 'x64'
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: windows-msi-input
@@ -582,7 +624,7 @@ jobs:
         shell: pwsh
         run: |
           $ErrorActionPreference = "Stop"
-          $stageName = "hodeishield-$env:VERSION-x86_64-pc-windows-msvc"
+          $stageName = "hodeishield-$env:VERSION-$env:TARGET"
           $dir = Join-Path $env:RUNNER_TEMP $stageName
           New-Item -ItemType Directory -Path $dir, dist | Out-Null
           Copy-Item stage/* $dir
@@ -591,7 +633,7 @@ jobs:
       - name: Upload archive
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
-          name: archive-x86_64-pc-windows-msvc
+          name: archive-${{ matrix.target }}
           path: dist/*.zip
           if-no-files-found: error
           retention-days: 7
@@ -608,7 +650,7 @@ jobs:
       contents: read
     env:
       VERSION: ${{ needs.version.outputs.version }}
-      EXE_SHA256: ${{ needs.sign-windows.outputs.exe_sha256 }}
+      EXE_SHA256: ${{ needs.sign-windows.outputs.exe_sha256_x64 }}
       # Pinned to 5.x: later WiX releases add maintenance-fee terms to their licence, to be reviewed
       # before moving. Bumped by hand in the periodic dependency review (CONTRIBUTING.md).
       WIX_VERSION: "5.0.2"
@@ -723,7 +765,7 @@ jobs:
       - name: Check the MSI before signing it
         shell: powershell
         env:
-          EXE_SHA256: ${{ needs.sign-windows.outputs.exe_sha256 }}
+          EXE_SHA256: ${{ needs.sign-windows.outputs.exe_sha256_x64 }}
         run: |
           $ErrorActionPreference = "Stop"
           $msi = (Resolve-Path "msi\hodeishield-$env:VERSION-x86_64-pc-windows-msvc.msi").Path
@@ -921,7 +963,8 @@ jobs:
             x86_64-unknown-linux-musl:x86_64-unknown-linux-musl \
             aarch64-unknown-linux-musl:aarch64-unknown-linux-musl \
             universal-apple-darwin:aarch64-apple-darwin \
-            x86_64-pc-windows-msvc:x86_64-pc-windows-msvc; do
+            x86_64-pc-windows-msvc:x86_64-pc-windows-msvc \
+            aarch64-pc-windows-msvc:aarch64-pc-windows-msvc; do
             name="${pair%%:*}"
             target="${pair##*:}"
             cargo cyclonedx --manifest-path crates/hodeishield-cli/Cargo.toml --format json \
@@ -994,8 +1037,9 @@ jobs:
             echo "archive-universal-apple-darwin hodeishield-$V-universal-apple-darwin.tar.gz"
             [ "$SIGN_MACOS" = true ] && echo "archive-universal-apple-darwin hodeishield-$V-universal-apple-darwin.pkg"
             echo "archive-x86_64-pc-windows-msvc hodeishield-$V-x86_64-pc-windows-msvc.zip"
+            echo "archive-aarch64-pc-windows-msvc hodeishield-$V-aarch64-pc-windows-msvc.zip"
             [ "$SIGN_WINDOWS" = true ] && echo "archive-msi hodeishield-$V-x86_64-pc-windows-msvc.msi"
-            for t in x86_64-unknown-linux-musl aarch64-unknown-linux-musl universal-apple-darwin x86_64-pc-windows-msvc; do
+            for t in x86_64-unknown-linux-musl aarch64-unknown-linux-musl universal-apple-darwin x86_64-pc-windows-msvc aarch64-pc-windows-msvc; do
               echo "archive-sbom hodeishield-$V-$t.cdx.json"
             done
             echo "archive-packages hodeishield_${pv}-1_amd64.deb"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7fff2f2..1f45174 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,16 @@ commands, `--json` output and exit codes. Each release's notes start with its se
 
 ## [Unreleased]
 
+### Added
+
+- Each release now includes a Windows on Arm build, `hodeishield-<version>-aarch64-pc-windows-msvc.zip`.
+  It is built natively on a Windows on Arm runner, its `hodeishield.exe` is signed with Authenticode
+  like the x64 one and checked to need no Visual C++ runtime, and the archive is listed in
+  `SHA256SUMS`, signed with Sigstore, covered by the build provenance and has its own SBOM. The
+  Scoop manifest offers it to Windows on Arm; the MSI and winget package remain x64 only. CI now
+  runs the tests, clippy and the import check on Windows on Arm too.
+  ([#37](https://github.com/Hodeitek/hodeishield-cli/issues/37))
+
 ### Fixed
 
 - Terminal output cleaning now also replaces the line and paragraph separators (U+2028, U+2029),
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 8c28ddc..1456741 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -39,8 +39,8 @@ cargo xtask man target/man        # generate man pages
 cargo deny check && cargo audit   # dependency policy and advisories
 ```
 
-CI runs the tests on Linux, macOS and Windows and the other checks on Linux; a pull request needs
-them all green.
+CI runs the tests on Linux, macOS, Windows and Windows on Arm and the other checks on Linux; a pull
+request needs them all green.
 
 ### The scripting surface is tested
 
diff --git a/README.md b/README.md
index 74653af..ffe8e0e 100644
--- a/README.md
+++ b/README.md
@@ -49,6 +49,7 @@ section), and put `hodeishield` (`hodeishield.exe` on Windows) somewhere on your
 | Linux arm64 | `hodeishield-<version>-aarch64-unknown-linux-musl.tar.gz` |
 | macOS (Apple silicon and Intel) | `hodeishield-<version>-universal-apple-darwin.tar.gz` |
 | Windows x86_64 | `hodeishield-<version>-x86_64-pc-windows-msvc.zip` |
+| Windows arm64 | `hodeishield-<version>-aarch64-pc-windows-msvc.zip` (from the first release after 0.3.1) |
 
 `<version>` has no leading `v`: release `v0.3.1` ships `hodeishield-0.3.1-…`. The Linux binaries are
 statically linked and run on any distribution. Homebrew and Scoop packages are also available
@@ -78,8 +79,9 @@ from a normal shell, is the recommended way and needs no administrator rights.
 The [Homebrew tap](https://github.com/Hodeitek/homebrew-hodeishield) and the
 [Scoop bucket](https://github.com/Hodeitek/scoop-hodeishield) are updated from each release's own
 files and `SHA256SUMS` when it is published, and both check those hashes when installing. Homebrew
-also installs the man pages and shell completions. A winget package has been submitted and is
-waiting for review by the winget community repository; it is not available yet.
+also installs the man pages and shell completions. Scoop picks the arm64 build on Windows on Arm
+automatically. A winget package has been submitted and is waiting for review by the winget community
+repository; it is not available yet.
 
 ### Debian, Ubuntu, Fedora, RHEL and other Linux distributions
 
diff --git a/docs/verifying-releases.md b/docs/verifying-releases.md
index f060d04..10b058e 100644
--- a/docs/verifying-releases.md
+++ b/docs/verifying-releases.md
@@ -7,6 +7,10 @@ Every release of `hodeishield-cli` publishes, for each platform archive:
   "bundle" files produced by **keyless** `cosign sign-blob` (no private key:
   the workflow signs using its GitHub Actions OIDC identity, and the
   signature is recorded in the public Rekor transparency log).
+- `hodeishield-<version>-aarch64-pc-windows-msvc.zip` (Windows on Arm, from the first release
+  after 0.3.1), checksummed, signed with Sigstore, covered by the provenance and accompanied by its
+  SBOM like the other archives. Its `hodeishield.exe` carries the same Authenticode signature
+  (section 5). There is no arm64 MSI yet.
 - `hodeishield-<version>-x86_64-pc-windows-msvc.msi` (from 0.3.0), with its own
   `.sigstore.json` and listed in `SHA256SUMS`. The MSI and the `hodeishield.exe` inside it are both
   signed with Authenticode (section 5); the exe is the same as in the `.zip`, whose SBOM describes it.

From 0d35356b4ebc813e7f7ea9d60d3cc05261c53f93 Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Sun, 11 Oct 2026 12:46:54 +0200
Subject: [PATCH 41/57] List the exit code changes as scripting-surface changes

The README Stability section says that giving an existing case a different
exit code is a breaking change and that the changelog lists it under
"Changed (scripting surface)", with what to do about it. Two unreleased
entries did exactly that but sat under Fixed:

- an unreachable system keychain with no API key now exits 3 instead of 1;
- a failure that used to exit 0 (an API error message containing "Broken
  pipe", or a broken pipe that was not standard output) now exits non-zero.

Move them to a new "Changed (scripting surface)" subsection and add what
script authors should do. Also:

- add one entry for the README changes that are already on dev (stability
  policy, proxies and TLS inspection, beta links, defining a profile before
  signing in, waiting for msiexec);
- say the container image is built for each stable release, as the workflow
  skips pre-releases and tags that are not vX.Y.Z;
- merge the second "Added" heading in Unreleased into the first.

Refs #105, #111, #58, #25, #52, #87, #89, #90, #92, #36

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 CHANGELOG.md | 70 ++++++++++++++++++++++++++++++----------------------
 1 file changed, 41 insertions(+), 29 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1f45174..1e38822 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,47 @@ commands, `--json` output and exit codes. Each release's notes start with its se
   runs the tests, clippy and the import check on Windows on Arm too.
   ([#37](https://github.com/Hodeitek/hodeishield-cli/issues/37))
 
+- On an interactive terminal, the CLI now tells you in one line on standard error when a newer
+  release exists. It asks GitHub's public releases API (no credential or identifier is sent) at most
+  once a day, stays silent with `--json`, `--csv`, `completions`, when standard error is not a
+  terminal and when `CI` is set, and never changes a command's output or exit code. Turn it off with
+  `HODEISHIELD_NO_UPDATE_CHECK=1` or `hodeishield config set update_check false`; the README's
+  "New-version notice" section lists exactly what is sent.
+  ([#38](https://github.com/Hodeitek/hodeishield-cli/issues/38))
+- A container image, `ghcr.io/hodeitek/hodeishield-cli`, for `linux/amd64` and `linux/arm64`, built
+  for each stable release: the release's own binary on a distroless base, running as a non-root
+  user, tagged with the exact version only. It is signed by digest with Sigstore and carries the
+  release's SBOM as a signed attestation. ([#36](https://github.com/Hodeitek/hodeishield-cli/issues/36))
+
+### Changed (scripting surface)
+
+- In a session where the system keychain cannot be reached (a Windows SSH or other network logon,
+  or a Secret Service on Linux that is locked or does not answer) and no API key is set, commands
+  such as `whoami` no longer fail with a raw platform error and exit code 1. They now say that the
+  system keychain is not available in this session, suggest `HODEISHIELD_API_KEY` for remote and
+  automated sessions, and exit with 3, the code for "not authenticated". With the key set, nothing
+  changes. What to do: treat exit 3 as "this session cannot keep a login, use an API key", and do
+  not rely on exit 1 for this case. ([#111](https://github.com/Hodeitek/hodeishield-cli/issues/111))
+- A failed command no longer exits 0 when the API's error message happens to contain the words
+  "Broken pipe". The CLI now treats a failure as a closed output pipe (`hodeishield ... | head -1`,
+  which still exits 0 silently) only when writing to standard output fails with that I/O error,
+  never because of the text of a message. What to do: a script that relied on exit 0 after such a
+  failed command must now handle the documented non-zero code (see "Exit codes" in the README).
+  ([#105](https://github.com/Hodeitek/hodeishield-cli/issues/105))
+- A broken pipe from anything other than standard output (a network connection, a file, the
+  configuration being saved) no longer ends a command with exit code 0 and no message. Only a write
+  to standard output that fails because the reader went away is treated as a closed pipe; any other
+  broken pipe is reported as an error with a non-zero exit code. What to do: as above, handle the
+  non-zero code instead of expecting exit 0. ([#105](https://github.com/Hodeitek/hodeishield-cli/issues/105))
+
+### Changed
+
+- The README documents more of how to use and depend on the CLI: the interface stability policy,
+  with what a script can rely on ([#58](https://github.com/Hodeitek/hodeishield-cli/issues/58), [#92](https://github.com/Hodeitek/hodeishield-cli/pull/92)); using the CLI behind a proxy or
+  TLS inspection ([#25](https://github.com/Hodeitek/hodeishield-cli/issues/25), [#89](https://github.com/Hodeitek/hodeishield-cli/pull/89)); the beta programme and its terms
+  ([#52](https://github.com/Hodeitek/hodeishield-cli/issues/52), [#90](https://github.com/Hodeitek/hodeishield-cli/pull/90)); defining a profile before signing in to it, and waiting for
+  `msiexec` in a silent install ([#87](https://github.com/Hodeitek/hodeishield-cli/pull/87)).
+
 ### Fixed
 
 - Terminal output cleaning now also replaces the line and paragraph separators (U+2028, U+2029),
@@ -30,27 +71,12 @@ commands, `--json` output and exit codes. Each release's notes start with its se
 - `install.sh` now looks up the latest release over HTTPS only, with TLS 1.2 or newer, as the
   download already did, so a redirect cannot lead that lookup to another protocol.
   ([#106](https://github.com/Hodeitek/hodeishield-cli/issues/106))
-- In a session where the system keychain cannot be reached (a Windows SSH or other network logon,
-  or a Secret Service on Linux that is locked or does not answer) and no API key is set, commands
-  such as `whoami` no longer fail with a raw platform error and exit code 1. They now say that the system keychain is not available in
-  this session, suggest `HODEISHIELD_API_KEY` for remote and automated sessions, and exit with 3,
-  the code for "not authenticated". With the key set, nothing changes.
-  ([#111](https://github.com/Hodeitek/hodeishield-cli/issues/111))
 - `hodeishield login` now checks that the system keychain can keep a session before it opens the
   browser or shows a device code, and stops there with the usual pointer to API keys. If saving the
   session still fails after the app has issued tokens, the CLI revokes the refresh token and then
   the access token, says so on standard error and exits non-zero, instead of leaving an active
   grant that nothing holds. The hint for a missing keychain now names the one for your system
   (Secret Service, the Keychain prompt, or Credential Manager). ([#101](https://github.com/Hodeitek/hodeishield-cli/issues/101))
-- A failed command no longer exits 0 when the API's error message happens to contain the words
-  "Broken pipe". The CLI now treats a failure as a closed output pipe (`hodeishield ... | head -1`,
-  which still exits 0 silently) only when writing to standard output fails with that I/O error,
-  never because of the text of a message. ([#105](https://github.com/Hodeitek/hodeishield-cli/issues/105))
-- A broken pipe from anything other than standard output (a network connection, a file, the
-  configuration being saved) no longer ends a command with exit code 0 and no message. Only a write
-  to standard output that fails because the reader went away is treated as a closed pipe; any other
-  broken pipe is reported as an error with a non-zero exit code.
-  ([#105](https://github.com/Hodeitek/hodeishield-cli/issues/105))
 - A stalled or slow local connection can no longer keep the browser sign-in listener busy past its
   timeout. Each connection now has a total time limit for its request, and no read waits beyond the
   overall sign-in deadline, and the deadline is checked before every connection is accepted, so a
@@ -58,20 +84,6 @@ commands, `--json` output and exit codes. Each release's notes start with its se
   redirect or stop `hodeishield login` from timing out. A client that resets its connection before
   it is accepted no longer ends the sign-in. ([#104](https://github.com/Hodeitek/hodeishield-cli/issues/104))
 
-### Added
-
-- On an interactive terminal, the CLI now tells you in one line on standard error when a newer
-  release exists. It asks GitHub's public releases API (no credential or identifier is sent) at most
-  once a day, stays silent with `--json`, `--csv`, `completions`, when standard error is not a
-  terminal and when `CI` is set, and never changes a command's output or exit code. Turn it off with
-  `HODEISHIELD_NO_UPDATE_CHECK=1` or `hodeishield config set update_check false`; the README's "New-version
-  notice" section lists exactly what is sent.
-  ([#38](https://github.com/Hodeitek/hodeishield-cli/issues/38))
-- A container image, `ghcr.io/hodeitek/hodeishield-cli`, for `linux/amd64` and `linux/arm64`: the
-  release's own binary on a distroless base, running as a non-root user, tagged with the exact
-  version only. It is signed by digest with Sigstore and carries the release's SBOM as a signed
-  attestation. ([#36](https://github.com/Hodeitek/hodeishield-cli/issues/36))
-
 ## [0.3.1] - 2026-10-10
 
 ### Fixed

From b99aa4d53e4dc9837953952fe5b7c193eec733a4 Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Sun, 11 Oct 2026 14:47:32 +0200
Subject: [PATCH 42/57] Describe the disclosure process and where security
 notices appear

SECURITY.md now covers what happens after a report (acknowledgement,
first assessment, status updates, fix targets by CVSS v3.1 severity and
the coordinated disclosure period), where users are told about an
actively exploited vulnerability or a severe incident (the repository's
security advisory first, then a notice at the top of the README, then
the fixed release's notes), and how an advisory for a fixed
vulnerability is published.

Every advisory is written from docs/security-advisory-template.md so
that it has the same fields. The README links to the policy near the top
and keeps an empty, comment-delimited block for a short notice; while it
is empty the README renders as before.

It also states that there is no bounty and no encrypted email for now,
adds a safe-harbour clause, and says how a CVE identifier is requested
(through the advisory, with GitHub as the CVE Numbering Authority).

Refs #120

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 CHANGELOG.md                       |   3 +
 README.md                          |   9 ++-
 SECURITY.md                        | 105 ++++++++++++++++++++++++++-
 docs/security-advisory-template.md | 112 +++++++++++++++++++++++++++++
 4 files changed, 227 insertions(+), 2 deletions(-)
 create mode 100644 docs/security-advisory-template.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1e38822..623fed4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -56,6 +56,9 @@ commands, `--json` output and exit codes. Each release's notes start with its se
   TLS inspection ([#25](https://github.com/Hodeitek/hodeishield-cli/issues/25), [#89](https://github.com/Hodeitek/hodeishield-cli/pull/89)); the beta programme and its terms
   ([#52](https://github.com/Hodeitek/hodeishield-cli/issues/52), [#90](https://github.com/Hodeitek/hodeishield-cli/pull/90)); defining a profile before signing in to it, and waiting for
   `msiexec` in a silent install ([#87](https://github.com/Hodeitek/hodeishield-cli/pull/87)).
+  `SECURITY.md` now says what happens after a vulnerability report, where a notice about an affected
+  release appears (the README has an empty place for it), and how advisories are published, from
+  a template kept in `docs/` ([#120](https://github.com/Hodeitek/hodeishield-cli/issues/120)).
 
 ### Fixed
 
diff --git a/README.md b/README.md
index ffe8e0e..19715a4 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,9 @@
 
 # HodeiShield CLI
 
+<!-- security-notice:start -->
+<!-- security-notice:end -->
+
 [![Latest release](https://img.shields.io/github/v/release/Hodeitek/hodeishield-cli?sort=semver)](https://github.com/Hodeitek/hodeishield-cli/releases/latest)
 [![CI](https://github.com/Hodeitek/hodeishield-cli/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Hodeitek/hodeishield-cli/actions/workflows/ci.yml?query=branch%3Amain)
 [![License: Apache-2.0](https://img.shields.io/github/license/Hodeitek/hodeishield-cli)](LICENSE)
@@ -11,6 +14,8 @@ The official command-line client for [HodeiShield](https://hodeishield.com), by
 [Hodeitek](https://hodeitek.com). HodeiShield covers third-party risk, supply-chain security and
 compliance (NIS2, DORA, ISO 27001, ENS).
 
+Security policy, how to report a vulnerability and where advisories appear: [SECURITY.md](SECURITY.md).
+
 ## Quick start
 
 ```sh
@@ -527,7 +532,9 @@ TLS-inspecting proxy; macOS and Windows have not been verified yet.
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md). To report a vulnerability,
 use [GitHub private reporting](https://github.com/Hodeitek/hodeishield-cli/security/advisories/new)
-or email [security@hodeitek.com](mailto:security@hodeitek.com), never a public issue.
+or email [security@hodeitek.com](mailto:security@hodeitek.com), never a public issue. Security
+advisories are published under
+[Security → Advisories](https://github.com/Hodeitek/hodeishield-cli/security/advisories).
 
 ## License
 
diff --git a/SECURITY.md b/SECURITY.md
index 4ede4b2..c015cd6 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -15,7 +15,110 @@ what you expected, and a proof of concept if you have one. **Never include a rea
 if one was exposed, revoke it in the app first.
 
 We will acknowledge your report, keep you informed while we investigate, and credit you in the
-advisory unless you prefer otherwise.
+advisory if you want to be credited.
+
+- Encrypted email: not offered at the moment.
+- Bug bounty: there is no bounty programme; we credit reporters publicly in the advisory.
+
+## What happens after you report
+
+A report made through GitHub opens a draft security advisory that only you and the maintainers can
+see; we talk to you there. A report made by email is answered by email.
+
+| Step | What you get | When |
+|---|---|---|
+| Acknowledgement | Confirmation that we received the report | Within 3 business days |
+| First assessment | Whether it is a vulnerability, its severity, and whether we know of it being exploited | Within 10 business days |
+| Status updates | Progress on the fix and the expected release, until the advisory is published | At least every 14 days |
+| Fix | A release that fixes it, and the published advisory | See the targets below |
+
+### Severity and fix targets
+
+We rate severity with [CVSS v3.1](https://www.first.org/cvss/v3.1/specification-document) and use
+its qualitative ratings. You can comment on the rating in the advisory or by email. The targets
+below are for shipping a fixed release, counted from the first assessment.
+
+| Severity | CVSS v3.1 base score | Target to ship a fix |
+|---|---|---|
+| Critical | 9.0 – 10.0 | 7 days |
+| High | 7.0 – 8.9 | 30 days |
+| Medium | 4.0 – 6.9 | 90 days |
+| Low | 0.1 – 3.9 | The next release |
+
+### Coordinated disclosure
+
+We ask you to keep the vulnerability confidential until the advisory is published, and we agree
+the publication date with you. The coordinated disclosure period is 90 days from your report. If
+a fix is not released by then, we publish the advisory with the workarounds we know of, unless we
+agree a short extension with you. If the vulnerability is being actively exploited,
+we may publish earlier, with workarounds (see [Security notices](#security-notices)).
+
+### Safe harbour
+
+We will not take legal action against you, or ask anyone else to, for research that follows this
+policy in good faith: you report to us privately and give us reasonable time to fix the issue before
+you disclose it; you access only the data you need to show the vulnerability, and do not keep,
+change or share anyone else's data; you do not degrade the service or harm its users; and you test
+only against accounts and tenants you own or are allowed to use. If in doubt, ask us first.
+
+## Security notices
+
+If a release is affected by a vulnerability that is being actively exploited, or by a severe
+incident (for example a compromised release or release pipeline), we tell users in these places,
+in this order:
+
+1. **The GitHub security advisory** for this repository, under
+   [Security → Advisories](https://github.com/Hodeitek/hodeishield-cli/security/advisories). It is
+   published or updated first, before a fix is available if necessary, and says which versions are
+   affected, what to do in the meantime, and whether a fix is in progress.
+2. **A short notice at the top of [README.md](README.md)**, linking to the advisory. The README
+   keeps an empty block for it between the markers `<!-- security-notice:start -->` and
+   `<!-- security-notice:end -->`; the notice goes between them, as a quote with a blank line
+   before and after it:
+
+   ```markdown
+   <!-- security-notice:start -->
+
+   > **Security notice:** versions 0.x.y to 0.x.z are affected by GHSA-xxxx-xxxx-xxxx. Update to
+   > 0.x.w; until then, see the advisory for a workaround.
+
+   <!-- security-notice:end -->
+   ```
+
+   The notice is updated when the fix ships and removed when it no longer applies, leaving the
+   block empty. The README inside a release archive is a copy taken when that release was built:
+   check the repository's README, not the copy you downloaded.
+3. **The release notes of the release that fixes it**, under `### Security` in that release's
+   section of [CHANGELOG.md](CHANGELOG.md), which the release workflow uses as the release notes.
+   Each entry links to the advisory.
+
+To be told, watch this repository's releases on GitHub (*Watch → Custom → Releases*) or follow
+[its releases feed](https://github.com/Hodeitek/hodeishield-cli/releases.atom), and check the
+advisories page. The CLI's own [new-version notice](README.md#new-version-notice) tells you on an
+interactive terminal that a newer release exists, but not whether it fixes a vulnerability.
+
+## How advisories are published
+
+Every fixed vulnerability gets a GitHub security advisory in this repository, written from
+[docs/security-advisory-template.md](docs/security-advisory-template.md) so that every advisory has
+the same fields:
+
+- a description of the vulnerability and its impact;
+- who is affected: which commands, configurations and install channels;
+- the affected versions and the fixed versions;
+- the severity, with its CVSS v3.1 vector;
+- workarounds, how to check whether you are affected, and how to update;
+- the timeline (reported, fixed, published), the credit, and references.
+
+The advisory is published when the fixed release is out, or earlier as described in
+[Security notices](#security-notices).
+
+Each advisory has a GHSA identifier. Its machine-readable form is the advisory record that GitHub's
+REST API returns, for example
+`https://api.github.com/repos/Hodeitek/hodeishield-cli/security-advisories?state=published`, which
+lists the identifiers, affected and patched versions, CVSS vector and credits as JSON. Advisories
+are published on GitHub. When a vulnerability needs a CVE identifier, we request it through the
+advisory, with GitHub as the CVE Numbering Authority.
 
 ## Supported versions
 
diff --git a/docs/security-advisory-template.md b/docs/security-advisory-template.md
new file mode 100644
index 0000000..bfc890c
--- /dev/null
+++ b/docs/security-advisory-template.md
@@ -0,0 +1,112 @@
+# Security advisory template
+
+Every security advisory for `hodeishield` is written from this template, as described in
+[SECURITY.md](../SECURITY.md#how-advisories-are-published), so that every advisory has the same
+fields in the same order. Copy everything below the line into a new GitHub security advisory for
+this repository, fill in each field, and delete the parts in *italics*. Keep a heading and write
+"None" rather than removing it, so readers and scripts find the same sections every time.
+
+The first table maps to the fields of GitHub's advisory form; the rest is the advisory's
+description.
+
+---
+
+| Advisory form field | Value |
+|---|---|
+| Title | *One line: the component, the flaw and its effect, e.g. "Sign-in token sent to a redirected host".* |
+| Affected versions | *A range, e.g. `>= 0.2.0, < 0.3.2`.* |
+| Patched versions | *e.g. `0.3.2`.* |
+| Severity | *Critical, High, Medium or Low, from the CVSS v3.1 base score.* |
+| CVSS v3.1 vector | *e.g. `CVSS:3.1/AV:N/AC:H/PR:N/UI:R/S:U/C:H/I:N/A:N`.* |
+| Weakness | *CWE identifier, if one fits.* |
+| Credits | *Reporter, as they asked to be credited, or "None" if they prefer not to be.* |
+
+## Summary
+
+*Two or three sentences: what is wrong, what an attacker can do, and what to do about it.*
+
+## Affected versions
+
+*Every release in the range, and every install channel that shipped them. Say if a channel was not
+affected.*
+
+## Fixed versions
+
+*The first release with the fix, with a link to its release page.*
+
+## Severity
+
+*The rating and the CVSS v3.1 vector, with one sentence on why each metric that is not obvious was
+chosen.*
+
+## Impact
+
+*What an attacker gains (for example a credential, the ability to hide terminal output, a tampered
+download) and what they need first (network position, a crafted URL or identifier, local access,
+the user running a particular command).*
+
+## Who is affected
+
+*The commands, flags, environment variables, configuration settings and platforms involved, e.g.
+"anyone who signs in with `hodeishield login` on Windows", "scripts that set
+`HODEISHIELD_API_KEY` together with a custom API URL". Say who is not affected.*
+
+## Workarounds
+
+*What to do until you can update, or "None: update". If a credential may have been exposed, say
+which one and to revoke it in the app.*
+
+## How to check whether you are affected
+
+```sh
+hodeishield --version
+```
+
+*Compare the version with the affected range above. Add any other check: a configuration value, a
+file, an environment variable, a log line from `--verbose`. For the container image, check the tag
+or digest your pipeline pins.*
+
+## How to update
+
+Verify every download as described in
+[docs/verifying-releases.md](https://github.com/Hodeitek/hodeishield-cli/blob/main/docs/verifying-releases.md).
+*Delete the channels that did not ship an affected version.*
+
+- **Release archive (Linux, macOS, Windows):** download the archive for your platform from the
+  release page of `<fixed version>`, verify it, and replace the `hodeishield` binary on your `PATH`.
+- **Homebrew:** `brew update && brew upgrade hodeishield`
+- **Scoop:** `scoop update` then `scoop update hodeishield`
+- **Debian, Ubuntu (`.deb`) and Fedora, RHEL (`.rpm`):** download the `<fixed version>` package,
+  verify it, and install it with the same `sudo apt install ./...` or `sudo dnf install ./...`
+  command as the first time.
+- **Windows installer (MSI):** install the `<fixed version>` MSI; it upgrades the installed version
+  in place.
+- **Install script (Linux and macOS):** download and verify the `install.sh` of `<fixed version>`,
+  then run `sh install.sh --version <fixed version>`.
+- **Container image:** pull `ghcr.io/hodeitek/hodeishield-cli:<fixed version>`, verify it with
+  `cosign verify`, and pin the new digest in your pipeline.
+- **From source:**
+  `cargo install --locked --force --git https://github.com/Hodeitek/hodeishield-cli --tag v<fixed version> hodeishield-cli`
+
+## Timeline
+
+| Date (UTC) | Event |
+|---|---|
+| *YYYY-MM-DD* | Reported |
+| *YYYY-MM-DD* | Fixed in `<fixed version>` |
+| *YYYY-MM-DD* | Advisory published |
+
+*Add other dates that matter, such as when exploitation was first seen or when the first notice was
+published.*
+
+## Credit
+
+*Who reported it and how they asked to be named, or "Reported privately; the reporter asked not to
+be named".*
+
+## References
+
+- *The release notes of `<fixed version>`.*
+- *The pull request or commit with the fix, once public.*
+- *The CVE identifier, if one was assigned.*
+- *Anything else a reader needs: related advisories, upstream issues.*

From a4caed21c79a4a9678b33e175b51aa66bfa817be Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Sun, 11 Oct 2026 15:02:14 +0200
Subject: [PATCH 43/57] State the support period and add a user information
 document

SECURITY.md "Supported versions" replaces "only the latest release
receives fixes" with the support rule: from 1.0.0, each major version
is supported with security fixes for five years, delivered in the
latest release of that major version; fixes stay available to people
whose HodeiShield subscription has ended, since releases are public
downloads. During 0.x, fixes go into the latest 0.x release, and 0.x
has no end-of-support date until 1.0.0 is released. An end-of-support
notice is published twelve months ahead in SECURITY.md, the README
security notice block and the release notes.

docs/user-information.md gathers the product and version
identification, the manufacturer's address and contact, the two ways
to report a vulnerability, the intended purpose, secure use and known
limitations, how each install channel updates and uninstalls, how to
turn off the new-version notice, how to remove the configuration,
update-check record and keychain entries, and where the SBOM is
published. Each release tag keeps the copy that applies to it.

The README links to both and states the rule in one sentence.

Refs #127
Refs #128

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 CHANGELOG.md             |   5 ++
 README.md                |   5 ++
 SECURITY.md              |  21 ++++-
 docs/user-information.md | 181 +++++++++++++++++++++++++++++++++++++++
 4 files changed, 211 insertions(+), 1 deletion(-)
 create mode 100644 docs/user-information.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 623fed4..4265079 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -59,6 +59,11 @@ commands, `--json` output and exit codes. Each release's notes start with its se
   `SECURITY.md` now says what happens after a vulnerability report, where a notice about an affected
   release appears (the README has an empty place for it), and how advisories are published, from
   a template kept in `docs/` ([#120](https://github.com/Hodeitek/hodeishield-cli/issues/120)).
+  `SECURITY.md` now states the support period (from 1.0.0, five years of security fixes per major
+  version; until then, the latest 0.x release), and `docs/user-information.md` gathers the contact
+  details, secure use, updating, removal and where the SBOM is published
+  ([#127](https://github.com/Hodeitek/hodeishield-cli/issues/127),
+  [#128](https://github.com/Hodeitek/hodeishield-cli/issues/128)).
 
 ### Fixed
 
diff --git a/README.md b/README.md
index 19715a4..828be3a 100644
--- a/README.md
+++ b/README.md
@@ -536,6 +536,11 @@ or email [security@hodeitek.com](mailto:security@hodeitek.com), never a public i
 advisories are published under
 [Security → Advisories](https://github.com/Hodeitek/hodeishield-cli/security/advisories).
 
+From 1.0.0, each major version is supported with security fixes for five years; during 0.x, fixes go
+into the latest 0.x release ([Supported versions](SECURITY.md#supported-versions)).
+[docs/user-information.md](docs/user-information.md) gathers the manufacturer's contact details, the
+support period, secure use, how to update and remove the CLI, and where the SBOM is published.
+
 ## License
 
 Licensed under the [Apache License, Version 2.0](LICENSE). Copyright 2026 Hodeitek S.L.; see
diff --git a/SECURITY.md b/SECURITY.md
index c015cd6..7b0e321 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -122,7 +122,26 @@ advisory, with GitHub as the CVE Numbering Authority.
 
 ## Supported versions
 
-Only the latest release receives fixes.
+From 1.0.0, each major version of `hodeishield` is supported for five years, counted from the
+release of its first version (1.0.0 for version 1). A supported major version receives security
+fixes. They ship in a new release of that major version: to get them, update to the latest release
+of your major version.
+
+Security fixes stay available to you while your version is supported, even if your HodeiShield
+subscription has ended: every release is a public download, and installing or updating the CLI
+never requires a subscription.
+
+**Before 1.0.** While the 0.x series is current, security fixes go into the latest 0.x release.
+The 0.x series has no end-of-support date until 1.0.0 is released.
+
+| Version | Supported | Security fixes until |
+|---|---|---|
+| 0.x | Yes, in the latest 0.x release | No end date until 1.0.0 is released |
+
+The end-of-support date of each major version is published in this table and in the release
+notes. Twelve months before a major version's support ends, an end-of-support notice is published
+here, in the security notice block at the top of [README.md](README.md) (see
+[Security notices](#security-notices)) and in the release notes.
 
 ## What is in scope
 
diff --git a/docs/user-information.md b/docs/user-information.md
new file mode 100644
index 0000000..67b202e
--- /dev/null
+++ b/docs/user-information.md
@@ -0,0 +1,181 @@
+# User information
+
+This document gathers in one place what you need to know to use `hodeishield` securely: who makes
+it, how to reach us, how long it is supported, and how to update and remove it. Where the details
+live in [README.md](../README.md) or [SECURITY.md](../SECURITY.md), it links to them.
+
+Each release keeps the copy of this document that applies to it, in that release's tag:
+`https://github.com/Hodeitek/hodeishield-cli/blob/v<version>/docs/user-information.md`. Releases
+up to 0.3.1 were published before this document existed; for them, the README and SECURITY.md in
+their tag apply.
+
+## Product
+
+- **Name:** HodeiShield CLI. The command is `hodeishield` (`hodeishield.exe` on Windows); the
+  source repository is [Hodeitek/hodeishield-cli](https://github.com/Hodeitek/hodeishield-cli).
+- **Version:** `hodeishield --version` prints the installed version. Versions follow
+  [Semantic Versioning](https://semver.org/) and each release is tagged `v<version>`.
+- **Releases:** every release, with its files and notes, is on the
+  [releases page](https://github.com/Hodeitek/hodeishield-cli/releases), at
+  `https://github.com/Hodeitek/hodeishield-cli/releases/tag/v<version>`. The notes of every
+  release, with its date, are also in [CHANGELOG.md](../CHANGELOG.md).
+
+## Manufacturer and contact
+
+Hodeitek S.L., Markole 17, 20550 Aretxabaleta, Gipuzkoa, Spain.
+
+- Email: [info@hodeitek.com](mailto:info@hodeitek.com)
+- Website: [hodeitek.com](https://hodeitek.com)
+- Bug reports and documentation problems that are not about security:
+  [GitHub issues](https://github.com/Hodeitek/hodeishield-cli/issues), as described in
+  [CONTRIBUTING.md](../CONTRIBUTING.md).
+
+## Reporting a vulnerability
+
+The point of contact for vulnerabilities in `hodeishield` is the maintainers, through either of
+these two means:
+
+- [GitHub private vulnerability reporting](https://github.com/Hodeitek/hodeishield-cli/security/advisories/new)
+  (the *Security* tab of the repository → *Report a vulnerability*);
+- email to [security@hodeitek.com](mailto:security@hodeitek.com).
+
+Never report a vulnerability in a public issue. What to include, how quickly you get an answer and
+how a fix is disclosed are in [SECURITY.md](../SECURITY.md#what-happens-after-you-report). Published
+advisories are under
+[Security → Advisories](https://github.com/Hodeitek/hodeishield-cli/security/advisories), and
+[Security notices](../SECURITY.md#security-notices) lists where an affected release is announced.
+
+## Intended purpose
+
+`hodeishield` is a read-only command-line client for the public `/v1` API of
+[HodeiShield](https://hodeishield.com). It reads one organisation's third-party inventory,
+supply-chain alerts, risk register, compliance posture, evidence and endpoint agents, from a
+terminal or a script. Every command reads: its requests to the API are `GET` only, and it cannot
+change data in your organisation. It needs a HodeiShield account to sign in with, or a tenant API
+key.
+
+## Security properties and secure use
+
+What the CLI guarantees (read only, credentials never written to disk in clear text, printed or
+logged, HTTPS only, no redirects followed, signed releases) is in
+[SECURITY.md](../SECURITY.md#what-the-cli-guarantees). To use it securely:
+
+- **Verify every download** before you run it: [Verify a download](../README.md#verify-a-download)
+  and [docs/verifying-releases.md](verifying-releases.md). For the container image, verify it and
+  pin its digest ([Container image](../README.md#container-image)).
+- **Pick the right credential** ([Authenticate](../README.md#authenticate)). People sign in with
+  `hodeishield login`: the token is kept in the system keychain, covers one tenant and only reads.
+  Scripts, CI and servers use a tenant API key with only the read scopes they need, kept in the CI's
+  secret store and passed in the environment, not on a command line. When
+  `HODEISHIELD_API_KEY` is set, it is used for every call, whatever else is configured.
+- **Keep the configuration file free of credentials.** It holds URLs and sign-in settings only,
+  and URLs must use HTTPS; plain HTTP is accepted only for `localhost`
+  ([Configure](../README.md#configure)).
+- **Treat output as your organisation's data.** `--json` and `--csv` output, and the request URLs
+  that `--verbose` logs, can contain identifiers and filter values from your organisation, but never
+  the CLI's credential. Text from the API is cleaned of terminal control characters before
+  it is printed, and CSV cells that a spreadsheet would run as a formula are prefixed with `'`
+  ([CSV output](../README.md#csv-output)).
+- **Behind a proxy or TLS inspection**, the CLI trusts the operating system's certificate store and
+  has no option to skip certificate verification: install your organisation's CA in that store
+  ([Networking](../README.md#networking-proxies-and-tls-inspection)).
+- **Cut access you no longer need**: `hodeishield logout`, or revoke the CLI's access in the app
+  under **Account → Application access**; revoke an API key in the app as soon as it is not needed
+  or may have been exposed.
+
+Known limitations:
+
+- The macOS binary is not yet signed with an Apple Developer ID or notarized
+  ([#50](https://github.com/Hodeitek/hodeishield-cli/issues/50)); the Sigstore signature is the
+  proof that it is genuine (see
+  [If macOS or Windows blocks the binary](../README.md#if-macos-or-windows-blocks-the-binary)).
+- Use behind a TLS-inspecting proxy is verified on Linux only; macOS and Windows have not been
+  verified yet.
+- The [new-version notice](../README.md#new-version-notice) makes at most one unauthenticated
+  request a day to GitHub's public API, so GitHub sees your IP address. It can be turned off (see
+  [Updating](#updating)).
+
+## Support period
+
+From 1.0.0, each major version is supported with security fixes for five years, and the fixes ship
+in the latest release of that major version. While a version is supported, security fixes stay
+available even after your HodeiShield subscription ends. How this applies to the current 0.x
+series, the end-of-support date of each major version and how end of support is announced are in
+[SECURITY.md](../SECURITY.md#supported-versions).
+
+## Updating
+
+`hodeishield` never updates itself. On an interactive terminal it tells you, at most once a day,
+that a newer release exists ([New-version notice](../README.md#new-version-notice)); update through
+the channel you installed it with. Before you move to a new minor version while the CLI is at 0.x,
+read **Changed (scripting surface)** in its release notes ([Stability](../README.md#stability)).
+
+| Installed with | To update |
+|---|---|
+| Release archive | Download the new archive, verify it, and replace the binary. |
+| Homebrew | `brew upgrade hodeishield` |
+| Scoop | `scoop update hodeishield` |
+| `.deb` / `.rpm` | Verify the newer package and install it with the same `apt install` or `dnf install` command. |
+| MSI | Install the newer MSI; it upgrades the older one in place. |
+| `install.sh` | Download and verify the new release's `install.sh` and run it with `--version` (and the same `--dir`, if you used one). |
+| Container image | Pull the new exact-version tag (there is no `latest` tag), verify it and pin its digest. |
+| `cargo install` | Run the same command with the new `--tag`. |
+
+To turn off the new-version notice, set `HODEISHIELD_NO_UPDATE_CHECK` to any non-empty value, or
+run `hodeishield config set update_check false` once for all profiles (`config unset update_check`
+restores it). With either, the CLI makes no request to GitHub.
+
+## Decommissioning
+
+To stop using `hodeishield` on a machine and leave nothing behind:
+
+1. **Sign out of every profile you signed in to**: `hodeishield logout`, and
+   `hodeishield logout --profile <name>` for each other profile. This revokes the token at the app
+   and removes it from the system keychain. If the CLI warns that the app did not confirm the
+   revocation, revoke the CLI's access in the app under **Account → Application access**.
+2. **Revoke the tenant API keys** the machine used, in the app, and remove them from the
+   environment and secret stores that held them.
+3. **Delete the configuration file and the update-check record.** `hodeishield config path` prints
+   where the configuration file is; `update-check.json` is next to it. By default:
+
+   | System | Directory |
+   |---|---|
+   | Linux | `~/.config/hodeishield/` (or `$XDG_CONFIG_HOME/hodeishield/`) |
+   | macOS | `~/Library/Application Support/com.Hodeitek.HodeiShield/` |
+   | Windows | `%APPDATA%\Hodeitek\HodeiShield\config\` |
+
+   The files are `config.toml` and `update-check.json`. If you set `HODEISHIELD_CONFIG`, they are
+   that file and `update-check.json` in its directory.
+4. **Uninstall the CLI** with the channel you installed it with:
+
+   | Installed with | To uninstall |
+   |---|---|
+   | Release archive | Delete the `hodeishield` binary, and any man pages you copied. |
+   | Homebrew | `brew uninstall hodeishield` |
+   | Scoop | `scoop uninstall hodeishield` |
+   | `.deb` / `.rpm` | `sudo apt remove hodeishield` or `sudo dnf remove hodeishield` |
+   | MSI | **Settings → Apps**, or `msiexec /x` ([Windows installer](../README.md#windows-installer-msi)) |
+   | `install.sh` | Delete `hodeishield` from the directory it installed to (`/usr/local/bin` or `~/.local/bin`, or your `--dir`), and the `hodeishield*.1` man pages from the `share/man/man1` directory beside it (for example `/usr/local/share/man/man1`). |
+   | Container image | Remove the image, for example `docker image rm ghcr.io/hodeitek/hodeishield-cli:<version>`. |
+   | `cargo install` | `cargo uninstall hodeishield-cli` |
+
+If the CLI is already gone and a sign-in was left in the keychain, revoke the access in the app
+(**Account → Application access**), then delete the entry, one per profile, whose service is
+`hodeishield-cli` and whose account is the profile name: on macOS with Keychain Access or
+`security delete-generic-password -s hodeishield-cli -a <profile>`, on Windows in Credential Manager
+(*Windows Credentials*, named `<profile>.hodeishield-cli`), and on Linux with
+`secret-tool clear service hodeishield-cli username <profile>`.
+
+## Software bill of materials
+
+From 0.2.0, each release publishes a [CycloneDX](https://cyclonedx.org) software bill of materials
+(SBOM) for each archive, `<archive-name>.cdx.json`, attached to the release with its own Sigstore
+signature and listed in `SHA256SUMS`. It lists every crate compiled into that binary, with its
+version, licence and package URL. The `.deb`, `.rpm` and MSI packages contain the binary of a
+matching archive, which that archive's SBOM describes. The container image carries the release's
+CycloneDX SBOM as a signed attestation.
+
+The SBOM is intended for users: use it to check which components a release contains and whether any
+of them has a known vulnerability. How to verify it is in
+[docs/verifying-releases.md](verifying-releases.md) and
+[Container image](../README.md#container-image).

From 1ac7bec4e72958685f11656dde9e43ee160a35f2 Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Wed, 7 Oct 2026 19:26:00 +0200
Subject: [PATCH 44/57] Add a provisional portfolio module to the API client

List the client tenants of a portfolio credential and read one of them on
data calls. The selection travels as one request header and the client
refuses any answer that does not confirm the same tenant. The module is
hand-written against a draft contract and isolated in portfolio.rs; the
generated client is untouched.

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 crates/hodeishield-api/src/client.rs    |  48 ++++--
 crates/hodeishield-api/src/error.rs     |  15 ++
 crates/hodeishield-api/src/lib.rs       |   1 +
 crates/hodeishield-api/src/portfolio.rs | 213 ++++++++++++++++++++++++
 crates/hodeishield-api/tests/api.rs     | 118 +++++++++++++
 5 files changed, 385 insertions(+), 10 deletions(-)
 create mode 100644 crates/hodeishield-api/src/portfolio.rs

diff --git a/crates/hodeishield-api/src/client.rs b/crates/hodeishield-api/src/client.rs
index 7ea302a..c4565a6 100644
--- a/crates/hodeishield-api/src/client.rs
+++ b/crates/hodeishield-api/src/client.rs
@@ -134,12 +134,7 @@ fn tenant_header(headers: &HeaderMap) -> Option<String> {
     if values.next().is_some() {
         return None;
     }
-    let canonical = value.len() == 36
-        && value.bytes().enumerate().all(|(i, b)| match i {
-            8 | 13 | 18 | 23 => b == b'-',
-            _ => b.is_ascii_hexdigit(),
-        });
-    canonical.then(|| value.to_ascii_lowercase())
+    crate::portfolio::is_uuid(value).then(|| value.to_ascii_lowercase())
 }
 
 /// What the client reports about each request it sends, for `--verbose`. It carries no header and
@@ -175,6 +170,15 @@ pub struct RetryEvent<'a> {
 type Observer = Arc<dyn Fn(&RequestEvent<'_>) + Send + Sync>;
 type RetryObserver = Arc<dyn Fn(&RetryEvent<'_>) + Send + Sync>;
 type Renew = Arc<dyn Fn() -> Option<SecretString> + Send + Sync>;
+type AnswerCheck = Arc<dyn Fn(&HeaderMap) -> Result<(), Error> + Send + Sync>;
+
+/// Extra headers a client sends on data requests, and the check its successful answers must pass.
+/// The portfolio module fills it in; this file knows nothing about what the headers mean.
+#[derive(Clone, Default)]
+pub(crate) struct Scope {
+    pub(crate) headers: HeaderMap,
+    pub(crate) check: Option<AnswerCheck>,
+}
 
 /// Builds a [`Client`].
 pub struct ClientBuilder {
@@ -189,6 +193,7 @@ pub struct ClientBuilder {
     observer: Option<Observer>,
     retry_observer: Option<RetryObserver>,
     renew: Option<Renew>,
+    pub(crate) scope: Scope,
 }
 
 impl fmt::Debug for ClientBuilder {
@@ -308,6 +313,7 @@ impl ClientBuilder {
             observer: self.observer,
             retry_observer: self.retry_observer,
             renew: self.renew,
+            scope: self.scope,
         })
     }
 }
@@ -325,6 +331,7 @@ pub struct Client {
     observer: Option<Observer>,
     retry_observer: Option<RetryObserver>,
     renew: Option<Renew>,
+    scope: Scope,
 }
 
 impl fmt::Debug for Client {
@@ -361,6 +368,7 @@ impl Client {
             observer: None,
             retry_observer: None,
             renew: None,
+            scope: Scope::default(),
         }
     }
 
@@ -414,6 +422,18 @@ impl Client {
         operation: &'static Operation,
         path: String,
         query: Vec<(&'static str, String)>,
+    ) -> Result<ApiResponse<T>, Error> {
+        self.get_with(operation, path, query, true)
+    }
+
+    /// Like [`Client::get`]; with `scoped` false the client's scope headers are neither sent nor
+    /// checked, for an operation that sits outside the scope.
+    pub(crate) fn get_with<T: DeserializeOwned>(
+        &self,
+        operation: &'static Operation,
+        path: String,
+        query: Vec<(&'static str, String)>,
+        scoped: bool,
     ) -> Result<ApiResponse<T>, Error> {
         let url = self.url(&path, &query);
         let mut rate_limit_retries = 0;
@@ -421,12 +441,14 @@ impl Client {
         let mut renewed = false;
         loop {
             let started = Instant::now();
-            let response = match self
+            let mut request = self
                 .http
                 .get(url.clone())
-                .header(AUTHORIZATION, self.authorization()?)
-                .send()
-            {
+                .header(AUTHORIZATION, self.authorization()?);
+            if scoped {
+                request = request.headers(self.scope.headers.clone());
+            }
+            let response = match request.send() {
                 Ok(response) => response,
                 Err(e)
                     if (e.is_connect() || e.is_timeout())
@@ -455,8 +477,14 @@ impl Client {
                     elapsed: started.elapsed(),
                 });
             }
+            // A scoped answer that does not carry the scope that was asked for is never decoded.
+            let verdict = match (&self.scope.check, scoped, status.is_success()) {
+                (Some(check), true, true) => check(response.headers()),
+                _ => Ok(()),
+            };
             let body = read_body(response, MAX_RESPONSE_BYTES).map_err(Error::Body)?;
             if status.is_success() {
+                verdict?;
                 let raw: serde_json::Value =
                     serde_json::from_slice(&body).map_err(|source| Error::Decode {
                         operation: operation.id,
diff --git a/crates/hodeishield-api/src/error.rs b/crates/hodeishield-api/src/error.rs
index 02523e6..6f3569f 100644
--- a/crates/hodeishield-api/src/error.rs
+++ b/crates/hodeishield-api/src/error.rs
@@ -86,6 +86,21 @@ pub enum Error {
     /// An id or slug that would change which resource the path addresses.
     #[error("{0:?} is not a valid identifier")]
     InvalidPathArgument(String),
+    /// A client tenant identifier that is not a UUID.
+    #[error("{0:?} is not a valid client tenant identifier")]
+    InvalidTenant(String),
+    /// The API answered for another client tenant than the one asked for, or did not say which.
+    #[error(
+        "the API did not confirm the client tenant that was asked for (asked for {requested}, \
+         answer says {})",
+        answered.as_deref().unwrap_or("nothing")
+    )]
+    TenantMismatch {
+        /// The tenant the request named.
+        requested: String,
+        /// What the answer's header said, when it said anything.
+        answered: Option<String>,
+    },
 }
 
 impl Error {
diff --git a/crates/hodeishield-api/src/lib.rs b/crates/hodeishield-api/src/lib.rs
index b1b39b5..8c46e27 100644
--- a/crates/hodeishield-api/src/lib.rs
+++ b/crates/hodeishield-api/src/lib.rs
@@ -24,6 +24,7 @@
 
 mod client;
 mod error;
+pub mod portfolio;
 #[allow(missing_docs)]
 #[path = "generated.rs"]
 pub mod v1;
diff --git a/crates/hodeishield-api/src/portfolio.rs b/crates/hodeishield-api/src/portfolio.rs
new file mode 100644
index 0000000..690027b
--- /dev/null
+++ b/crates/hodeishield-api/src/portfolio.rs
@@ -0,0 +1,213 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Hodeitek S.L.
+
+//! Client tenants of a portfolio credential: list them, and read one of them.
+//!
+//! # Provisional
+//!
+//! **This module is written by hand against a draft of the `/v1` contract and is not part of the
+//! published API description yet.** Nothing in `openapi/v1.json` or the generated client describes
+//! it. When the contract is published, this file is the only place that changes: the operation, the
+//! shape of [`Tenant`] and the way the selected tenant travels on a request are all decided here,
+//! and callers see only the interface below.
+//!
+//! The draft assumes:
+//!
+//! - `GET /v1/portfolio/tenants`, scope `portfolio:read`, paginated like the other lists
+//!   (`page`, `per_page`, answer `{ data, pagination }`);
+//! - the client is selected on every data operation with one `X-HS-Tenant` request header holding
+//!   the tenant's UUID, and every answer to such a request repeats it in an `X-HS-Tenant` response
+//!   header;
+//! - the listing does not take that header.
+//!
+//! # Interface
+//!
+//! - [`Client::list_tenants`] lists the client tenants the credential may read.
+//! - [`ClientBuilder::tenant`] makes every data call of the built client read that tenant. The
+//!   client then refuses any successful answer that does not name the same tenant, so data of one
+//!   client is never returned as if it were another's.
+
+use crate::client::{Operation, Scope};
+use crate::error::Error;
+use crate::v1::Pagination;
+use crate::{ApiResponse, Client, ClientBuilder};
+use reqwest::header::{HeaderMap, HeaderName, HeaderValue};
+use serde::{Deserialize, Serialize};
+use std::sync::Arc;
+
+/// Request and response header that selects, and confirms, the client tenant.
+const TENANT_HEADER: HeaderName = HeaderName::from_static("x-hs-tenant");
+
+/// `GET /v1/portfolio/tenants`: List the client tenants of the credential's portfolio.
+pub const LIST_TENANTS: Operation = Operation {
+    id: "listPortfolioTenants",
+    method: "GET",
+    path: "/v1/portfolio/tenants",
+    summary: "List the client tenants of the credential's portfolio",
+    scopes: &["portfolio:read"],
+    known_values: &[],
+};
+
+/// A client tenant of the portfolio. Text fields come from the server and are untrusted.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct Tenant {
+    /// Stable identifier (a UUID): what selects the tenant.
+    pub id: String,
+    /// Display name.
+    pub name: String,
+    /// Short unique name, for people and scripts.
+    pub slug: String,
+    /// The client organisation the tenant belongs to, when it has one.
+    #[serde(default)]
+    pub organization: Option<TenantOrganization>,
+    /// Whether this is the MSSP's own tenant rather than a client's.
+    #[serde(default)]
+    pub internal: bool,
+    /// Whether the tenant is active.
+    #[serde(default = "yes")]
+    pub active: bool,
+    /// `in_force`, `grace` or `inactive`. The vocabulary may grow.
+    #[serde(default)]
+    pub licence_status: Option<String>,
+}
+
+fn yes() -> bool {
+    true
+}
+
+/// The organisation a [`Tenant`] belongs to.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct TenantOrganization {
+    /// Identifier of the organisation.
+    pub id: String,
+    /// Display name.
+    pub name: String,
+}
+
+/// The answer of [`Client::list_tenants`].
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct ListTenantsResponse {
+    /// One page of tenants.
+    pub data: Vec<Tenant>,
+    /// Where this page sits in the whole list.
+    pub pagination: Pagination,
+}
+
+/// Paging of [`Client::list_tenants`].
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct ListTenantsParams {
+    /// 1-based page number.
+    pub page: Option<i64>,
+    /// Items per page, 1..200.
+    pub per_page: Option<i64>,
+}
+
+impl ListTenantsParams {
+    fn query_pairs(&self) -> Vec<(&'static str, String)> {
+        let mut pairs = Vec::new();
+        if let Some(page) = self.page {
+            pairs.push(("page", page.to_string()));
+        }
+        if let Some(per_page) = self.per_page {
+            pairs.push(("per_page", per_page.to_string()));
+        }
+        pairs
+    }
+}
+
+impl Client {
+    /// The client tenants this credential may read. The listing is never scoped to a tenant, even
+    /// on a client built with [`ClientBuilder::tenant`].
+    ///
+    /// Required scope: `portfolio:read`.
+    ///
+    /// # Errors
+    ///
+    /// [`Error`] when the request cannot be sent, the API answers with an error (a credential
+    /// without portfolio scope gets `403`), or the body does not match the draft.
+    pub fn list_tenants(
+        &self,
+        params: &ListTenantsParams,
+    ) -> Result<ApiResponse<ListTenantsResponse>, Error> {
+        self.get_with(
+            &LIST_TENANTS,
+            LIST_TENANTS.path.to_owned(),
+            params.query_pairs(),
+            false,
+        )
+    }
+}
+
+impl ClientBuilder {
+    /// Makes every data call of the built client read the client tenant `id`.
+    ///
+    /// The built client sends the selection on each request and returns an answer only when it
+    /// confirms the same tenant; otherwise the call fails with [`Error::TenantMismatch`].
+    ///
+    /// # Errors
+    ///
+    /// [`Error::InvalidTenant`] when `id` is not a UUID.
+    pub fn tenant(mut self, id: &str) -> Result<Self, Error> {
+        if !is_uuid(id) {
+            return Err(Error::InvalidTenant(id.to_owned()));
+        }
+        let wanted = id.to_ascii_lowercase();
+        let mut headers = HeaderMap::new();
+        headers.insert(
+            TENANT_HEADER,
+            HeaderValue::from_str(&wanted).map_err(|_| Error::InvalidTenant(id.to_owned()))?,
+        );
+        let check = move |answer: &HeaderMap| {
+            let answered = answer
+                .get(TENANT_HEADER)
+                .and_then(|v| v.to_str().ok())
+                .map(|v| v.trim().to_ascii_lowercase());
+            if answered.as_deref() == Some(wanted.as_str()) {
+                Ok(())
+            } else {
+                Err(Error::TenantMismatch {
+                    requested: wanted.clone(),
+                    answered,
+                })
+            }
+        };
+        self.scope = Scope {
+            headers,
+            check: Some(Arc::new(check)),
+        };
+        Ok(self)
+    }
+}
+
+/// Whether `text` is a UUID in the 8-4-4-4-12 form, in any case. The one check for tenant ids: the
+/// tenant selection and the `X-HS-Tenant` metadata both use it.
+#[must_use]
+pub fn is_uuid(text: &str) -> bool {
+    let groups: Vec<&str> = text.split('-').collect();
+    groups.len() == 5
+        && groups
+            .iter()
+            .zip([8, 4, 4, 4, 12])
+            .all(|(g, len)| g.len() == len && g.bytes().all(|b| b.is_ascii_hexdigit()))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn recognises_uuids_only() {
+        assert!(is_uuid("0b8f2a52-6a0e-4d5c-9d3e-1f2a3b4c5d6e"));
+        assert!(is_uuid("0B8F2A52-6A0E-4D5C-9D3E-1F2A3B4C5D6E"));
+        for bad in [
+            "",
+            "acme",
+            "0b8f2a52-6a0e-4d5c-9d3e",
+            "0b8f2a52-6a0e-4d5c-9d3e-1f2a3b4c5d6",
+            "0b8f2a52-6a0e-4d5c-9d3e-1f2a3b4c5d6g",
+            "a, b",
+        ] {
+            assert!(!is_uuid(bad), "{bad:?}");
+        }
+    }
+}
diff --git a/crates/hodeishield-api/tests/api.rs b/crates/hodeishield-api/tests/api.rs
index 0bcd2ea..bb9bd8b 100644
--- a/crates/hodeishield-api/tests/api.rs
+++ b/crates/hodeishield-api/tests/api.rs
@@ -662,3 +662,121 @@ fn retry_observer_receives_expected_events() {
     unavailable.assert();
     success.assert();
 }
+
+// The portfolio module is provisional: these tests pin its interface, not the published contract.
+
+const TENANT_A: &str = "11111111-1111-4111-8111-111111111111";
+const TENANT_B: &str = "22222222-2222-4222-8222-222222222222";
+const EMPTY_PAGE: &str =
+    r#"{"data":[],"pagination":{"page":1,"per_page":50,"total":0,"total_pages":0}}"#;
+
+fn tenant_client(server: &mockito::Server, tenant: &str) -> Client {
+    Client::builder(
+        server.url().parse().expect("url"),
+        SecretString::from("hsp_example"),
+    )
+    .tenant(tenant)
+    .expect("a UUID")
+    .build()
+    .expect("client")
+}
+
+#[test]
+fn list_tenants_decodes_the_listing_and_never_sends_a_tenant() {
+    use hodeishield_api::portfolio::ListTenantsParams;
+    let mut server = mockito::Server::new();
+    let mock = server
+        .mock("GET", "/v1/portfolio/tenants")
+        .match_header("authorization", "Bearer hsp_example")
+        .match_header("x-hs-tenant", mockito::Matcher::Missing)
+        .with_body(format!(
+            r#"{{"data":[{{"id":"{TENANT_A}","name":"Acme","slug":"acme","organization":{{"id":"o1","name":"Acme Group"}},"internal":false,"active":true,"licence_status":"in_force","later":1}}],"pagination":{{"page":1,"per_page":50,"total":1,"total_pages":1}}}}"#
+        ))
+        .create();
+    // Even a client built for one tenant lists the whole portfolio.
+    let response = tenant_client(&server, TENANT_B)
+        .list_tenants(&ListTenantsParams::default())
+        .expect("listing");
+    mock.assert();
+    assert_eq!(response.data.data[0].slug, "acme");
+    assert_eq!(
+        response.data.data[0].licence_status.as_deref(),
+        Some("in_force")
+    );
+    assert_eq!(response.raw["data"][0]["later"], 1);
+}
+
+#[test]
+fn a_selected_tenant_travels_on_data_calls_and_must_be_confirmed() {
+    let mut server = mockito::Server::new();
+    let ok = server
+        .mock("GET", "/v1/vendors")
+        .match_header("x-hs-tenant", TENANT_A)
+        .with_header("x-hs-tenant", &TENANT_A.to_ascii_uppercase())
+        .with_body(EMPTY_PAGE)
+        .create();
+    tenant_client(&server, TENANT_A)
+        .list_vendors(&ListVendorsParams::default())
+        .expect("confirmed answer");
+    ok.assert();
+}
+
+#[test]
+fn an_answer_for_another_tenant_or_for_none_is_refused() {
+    let mut server = mockito::Server::new();
+    let other = server
+        .mock("GET", "/v1/vendors")
+        .with_header("x-hs-tenant", TENANT_B)
+        .with_body(EMPTY_PAGE)
+        .create();
+    let err = tenant_client(&server, TENANT_A)
+        .list_vendors(&ListVendorsParams::default())
+        .expect_err("another tenant");
+    assert!(
+        matches!(&err, Error::TenantMismatch { answered: Some(a), .. } if a == TENANT_B),
+        "{err:?}"
+    );
+    other.remove();
+    server
+        .mock("GET", "/v1/vendors")
+        .with_body(EMPTY_PAGE)
+        .create();
+    let err = tenant_client(&server, TENANT_A)
+        .list_vendors(&ListVendorsParams::default())
+        .expect_err("no confirmation");
+    assert!(
+        matches!(err, Error::TenantMismatch { answered: None, .. }),
+        "{err:?}"
+    );
+}
+
+#[test]
+fn a_client_without_a_tenant_sends_no_selection_and_checks_nothing() {
+    let mut server = mockito::Server::new();
+    let mock = server
+        .mock("GET", "/v1/vendors")
+        .match_header("x-hs-tenant", mockito::Matcher::Missing)
+        .with_body(EMPTY_PAGE)
+        .create();
+    client(&server)
+        .list_vendors(&ListVendorsParams::default())
+        .expect("plain call");
+    mock.assert();
+}
+
+#[test]
+fn a_tenant_that_is_not_a_uuid_is_refused_before_any_request() {
+    for bad in [
+        "acme",
+        "",
+        "11111111-1111-4111-8111-111111111111, 22222222-2222-4222-8222-222222222222",
+    ] {
+        let err = Client::builder(
+            "https://api.example.test".parse().expect("url"),
+            SecretString::from("k"),
+        )
+        .tenant(bad)
+        .expect_err("not a UUID");
+        assert!(matches!(err, Error::InvalidTenant(_)), "{bad:?}");
+    }
+}

From 58686e3e3e57a13d699592ea568758fb82d7af20 Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Wed, 7 Oct 2026 19:30:54 +0200
Subject: [PATCH 45/57] Read a portfolio's client tenants from the CLI

Add 'tenants list' and the global --tenant and --all-tenants selection on
read commands. A list across tenants labels every row, in the table and in
--json and --csv, with the tenant whose own request returned it. A client
outside the portfolio is reported as not found before any data is read, and
a credential without portfolio scope behaves as before.

Closes #54

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 crates/hodeishield-cli/src/cli.rs             |  94 ++++
 crates/hodeishield-cli/src/commands/mod.rs    |  29 +-
 .../hodeishield-cli/src/commands/resources.rs | 235 +++++++--
 .../hodeishield-cli/src/commands/tenants.rs   | 217 +++++++++
 crates/hodeishield-cli/src/failure.rs         |  27 +-
 crates/hodeishield-cli/src/output.rs          |  64 +++
 crates/hodeishield-cli/tests/cli.rs           | 451 ++++++++++++++++++
 7 files changed, 1079 insertions(+), 38 deletions(-)
 create mode 100644 crates/hodeishield-cli/src/commands/tenants.rs

diff --git a/crates/hodeishield-cli/src/cli.rs b/crates/hodeishield-cli/src/cli.rs
index 2f17fbb..6e2d66f 100644
--- a/crates/hodeishield-cli/src/cli.rs
+++ b/crates/hodeishield-cli/src/cli.rs
@@ -19,6 +19,11 @@ Credentials:
   HODEISHIELD_API_KEY   A tenant API key. When set, it is used for every API call.
   hodeishield login     Otherwise, sign in to the app; the token is kept in the system keychain.
 
+Several client tenants (portfolio credential):
+  hodeishield tenants list                       The client tenants you may read.
+  hodeishield --tenant <slug|id> vendors list    One client.
+  hodeishield --all-tenants vendors list         Every client, with a tenant column.
+
 Exit codes:
   0 ok · 1 error · 2 usage · 3 not authenticated · 4 missing scope · 5 not found
   6 rate limited · 7 API unreachable or failing · 8 tenant licence not in force";
@@ -58,6 +63,27 @@ pub struct Cli {
     #[arg(short, long, global = true, help_heading = "Global options")]
     pub verbose: bool,
 
+    /// Read this client tenant (its slug or id) instead of the credential's own. Needs a
+    /// portfolio credential; see `hodeishield tenants list`.
+    #[arg(
+        long,
+        global = true,
+        help_heading = "Client selection (MSSP)",
+        value_name = "SLUG|ID",
+        conflicts_with = "all_tenants"
+    )]
+    pub tenant: Option<String>,
+
+    /// On a list command, read every client tenant of the portfolio and add a tenant column (or
+    /// `tenant_*` fields) to each row. Fetches every page of each tenant.
+    #[arg(
+        long,
+        global = true,
+        help_heading = "Client selection (MSSP)",
+        conflicts_with = "tenant"
+    )]
+    pub all_tenants: bool,
+
     #[command(subcommand)]
     pub command: Command,
 }
@@ -82,6 +108,9 @@ pub enum Command {
     /// Enrolled endpoint agents.
     #[command(subcommand)]
     Endpoints(EndpointsCommand),
+    /// Client tenants a portfolio (MSSP) credential may read.
+    #[command(subcommand)]
+    Tenants(TenantsCommand),
     /// Sign in to the app (browser, or --device without one).
     #[command(long_about = LOGIN_ABOUT)]
     Login(LoginArgs),
@@ -134,8 +163,47 @@ impl Cli {
                 )
                 .exit();
         }
+        if let Some(message) = cli.selection_error() {
+            Self::command()
+                .error(clap::error::ErrorKind::ArgumentConflict, message)
+                .exit();
+        }
         cli
     }
+
+    /// Why the client selection cannot go with this command, if it cannot. It is refused rather
+    /// than ignored: a command that does not read the selected client must not look as if it did.
+    fn selection_error(&self) -> Option<&'static str> {
+        if self.tenant.is_some() && self.all_tenants {
+            return Some("the argument '--tenant' cannot be used with '--all-tenants'");
+        }
+        if self.tenant.is_none() && !self.all_tenants {
+            return None;
+        }
+        if !self.command.reads_tenant_data() {
+            return Some(
+                "'--tenant' and '--all-tenants' only apply to the commands that read tenant data",
+            );
+        }
+        if self.all_tenants {
+            match self.command.paging() {
+                None => {
+                    return Some(
+                        "'--all-tenants' applies to list commands; use '--tenant' to read one \
+                         client",
+                    );
+                }
+                Some(paging) if paging.page.is_some() => {
+                    return Some(
+                        "the argument '--all-tenants' cannot be used with '--page': it fetches \
+                         every page of each tenant",
+                    );
+                }
+                Some(_) => {}
+            }
+        }
+        None
+    }
 }
 
 impl Cli {
@@ -150,6 +218,19 @@ impl Cli {
 }
 
 impl Command {
+    /// The commands that read a tenant's data, and so can read a selected client's.
+    fn reads_tenant_data(&self) -> bool {
+        matches!(
+            self,
+            Self::Vendors(_)
+                | Self::Alerts(_)
+                | Self::Risks(_)
+                | Self::Compliance(_)
+                | Self::Evidence(_)
+                | Self::Endpoints(_)
+        )
+    }
+
     /// The paging options, for the commands that list.
     fn paging(&self) -> Option<&Paging> {
         match self {
@@ -159,6 +240,7 @@ impl Command {
             Self::Compliance(ComplianceCommand::Controls(list)) => Some(&list.paging),
             Self::Evidence(EvidenceCommand::List(list)) => Some(&list.paging),
             Self::Endpoints(EndpointsCommand::List(list)) => Some(&list.paging),
+            Self::Tenants(TenantsCommand::List(list)) => Some(&list.paging),
             _ => None,
         }
     }
@@ -192,6 +274,18 @@ where
     PossibleValuesParser::new(values).try_map(|value| T::from_str(&value))
 }
 
+#[derive(Debug, Subcommand)]
+pub enum TenantsCommand {
+    /// List the client tenants this credential may read.
+    List(TenantsList),
+}
+
+#[derive(Debug, Args)]
+pub struct TenantsList {
+    #[command(flatten)]
+    pub paging: Paging,
+}
+
 #[derive(Debug, Subcommand)]
 pub enum VendorsCommand {
     /// List vendors.
diff --git a/crates/hodeishield-cli/src/commands/mod.rs b/crates/hodeishield-cli/src/commands/mod.rs
index ad117b9..4339ecd 100644
--- a/crates/hodeishield-cli/src/commands/mod.rs
+++ b/crates/hodeishield-cli/src/commands/mod.rs
@@ -6,6 +6,7 @@
 mod config;
 mod resources;
 mod session;
+mod tenants;
 
 use crate::auth::{self, TokenStore};
 use crate::cli::{Cli, Command};
@@ -14,11 +15,13 @@ use crate::failure::{ApiContext, CredentialSource, Result, from_api};
 use hodeishield_api::Client;
 use std::io::Write;
 use std::sync::Arc;
+use tenants::Selection;
 
 pub struct Context {
     pub overrides: Overrides,
     pub json: bool,
     pub verbose: bool,
+    pub selection: Selection,
     pub store: Arc<dyn TokenStore + Send + Sync>,
 }
 
@@ -27,8 +30,13 @@ impl Context {
         crate::config::resolve(&self.overrides)
     }
 
-    /// A `/v1` client with the credential in effect.
-    pub fn api(&self, settings: &Settings) -> Result<(Client, CredentialSource)> {
+    /// A `/v1` client with the credential in effect, reading `tenant` (a client tenant's id) when
+    /// one is given and the credential's own tenant otherwise.
+    pub fn api(
+        &self,
+        settings: &Settings,
+        tenant: Option<&str>,
+    ) -> Result<(Client, CredentialSource)> {
         let (credential, source) = auth::credential_for_api(settings, self.store.as_ref())?;
         let mut builder =
             Client::builder(settings.api_url.clone(), credential).user_agent(crate::USER_AGENT);
@@ -36,6 +44,17 @@ impl Context {
             let (settings, store) = (settings.clone(), Arc::clone(&self.store));
             builder = builder.renew_credential(move || auth::renew(&settings, store.as_ref()));
         }
+        if let Some(tenant) = tenant {
+            builder = builder.tenant(tenant).map_err(|e| {
+                from_api(
+                    e,
+                    &ApiContext {
+                        source,
+                        framework: None,
+                    },
+                )
+            })?;
+        }
         if self.verbose {
             builder = builder.observer(|event| {
                 eprintln!(
@@ -80,6 +99,11 @@ pub fn run(cli: Cli, out: &mut dyn Write) -> Result<()> {
         },
         json: cli.json,
         verbose: cli.verbose,
+        selection: match (cli.tenant, cli.all_tenants) {
+            (Some(tenant), _) => Selection::Tenant(tenant),
+            (None, true) => Selection::All,
+            (None, false) => Selection::Own,
+        },
         store: Arc::new(auth::store::Keychain),
     };
     match cli.command {
@@ -89,6 +113,7 @@ pub fn run(cli: Cli, out: &mut dyn Write) -> Result<()> {
         Command::Compliance(command) => resources::compliance(&ctx, command, out),
         Command::Evidence(command) => resources::evidence(&ctx, command, out),
         Command::Endpoints(command) => resources::endpoints(&ctx, command, out),
+        Command::Tenants(command) => tenants::run(&ctx, command, out),
         Command::Login(args) => session::login(&ctx, &args),
         Command::Logout => session::logout(&ctx),
         Command::Whoami => session::whoami(&ctx, out),
diff --git a/crates/hodeishield-cli/src/commands/resources.rs b/crates/hodeishield-cli/src/commands/resources.rs
index 0ecfe99..6170241 100644
--- a/crates/hodeishield-cli/src/commands/resources.rs
+++ b/crates/hodeishield-cli/src/commands/resources.rs
@@ -4,16 +4,19 @@
 //! The read commands: one per `/v1` collection.
 
 use super::Context;
+use super::tenants::{Selection, Target};
 use crate::cli::{
     AlertsCommand, ComplianceCommand, EndpointsCommand, EvidenceCommand, Paging, RisksCommand,
     VendorsCommand,
 };
-use crate::failure::{ApiContext, CredentialSource, Result, from_api};
+use crate::failure::{ApiContext, CredentialSource, Failure, Kind, Result, from_api};
 use crate::filters::warn_unknown;
 use crate::output::{
-    cell, clean, print_csv, print_detail, print_json, print_table, short_time, table,
+    Rows, cell, clean, print_csv, print_detail, print_json, print_table, short_time, table,
+    tenant_table,
 };
-use comfy_table::Table;
+use hodeishield_api::Client;
+use hodeishield_api::portfolio::Tenant;
 use hodeishield_api::v1::{
     Alert, ComplianceControl, Endpoint, Evidence, ListAlertsParams, ListComplianceControlsParams,
     ListEndpointsParams, ListEvidenceParams, ListRisksParams, ListVendorsParams, Pagination, Risk,
@@ -27,6 +30,10 @@ use std::io::Write;
 type Fetch<'a, R> =
     dyn FnMut(Option<i64>, Option<i64>) -> std::result::Result<ApiResponse<R>, Error> + 'a;
 
+/// A fetch that still has to be told which client to ask.
+type FetchFrom<'a, R> =
+    dyn FnMut(&Client, Option<i64>, Option<i64>) -> std::result::Result<ApiResponse<R>, Error> + 'a;
+
 /// Most pages `--all` fetches: 200 000 items at the largest page size.
 const MAX_PAGES: i64 = 1_000;
 
@@ -35,9 +42,38 @@ const MAX_PAGES: i64 = 1_000;
 /// hundred MiB at most.
 const MAX_ITEMS: usize = 100_000;
 
-/// Prints one page, or every page with `--all`.
+/// Prints a list for the selected client, or for every client with `--all-tenants`.
 #[allow(clippy::too_many_arguments)]
 fn list<R, T>(
+    ctx: &Context,
+    out: &mut dyn Write,
+    paging: &Paging,
+    noun: &str,
+    api: ApiContext<'_>,
+    targets: &[Target],
+    fetch: &mut FetchFrom<'_, R>,
+    split: fn(R) -> (Vec<T>, Pagination),
+    render: fn(&[T]) -> Rows,
+) -> Result<()> {
+    if matches!(ctx.selection, Selection::All) {
+        return list_across(ctx, out, paging, noun, api, targets, fetch, split, render);
+    }
+    let client = &targets[0].client;
+    list_one(
+        ctx,
+        out,
+        paging,
+        noun,
+        api,
+        &mut |page, per_page| fetch(client, page, per_page),
+        split,
+        render,
+    )
+}
+
+/// Prints one page, or every page with `--all`, of one tenant's list.
+#[allow(clippy::too_many_arguments)]
+pub(super) fn list_one<R, T>(
     ctx: &Context,
     out: &mut dyn Write,
     paging: &Paging,
@@ -45,7 +81,7 @@ fn list<R, T>(
     api: ApiContext<'_>,
     fetch: &mut Fetch<'_, R>,
     split: fn(R) -> (Vec<T>, Pagination),
-    render: fn(&[T]) -> Table,
+    render: fn(&[T]) -> Rows,
 ) -> Result<()> {
     if !paging.all {
         let response = fetch(paging.page, paging.per_page).map_err(|e| from_api(e, &api))?;
@@ -61,7 +97,7 @@ fn list<R, T>(
             let raw_items = response.raw.get("data").and_then(Value::as_array);
             print_csv(out, raw_items.map_or(&[], Vec::as_slice))?;
         } else {
-            print_table(out, &render(&items))?;
+            print_table(out, &render(&items).into_table())?;
         }
         if pagination.total_pages > 1 {
             let next = if pagination.page < pagination.total_pages {
@@ -89,14 +125,138 @@ fn list<R, T>(
     if paging.csv {
         print_csv(out, &raw_items)?;
     } else {
-        print_table(out, &render(&items))?;
+        print_table(out, &render(&items).into_table())?;
     }
     eprintln!("{} {noun}.", items.len());
     Ok(())
 }
 
+/// Every page of every client tenant, each row labelled with the tenant whose request produced it.
+///
+/// A tenant that cannot be read for its own reasons (no licence, left the portfolio) is reported
+/// and skipped, and the command still fails at the end, so a script never takes a partial result
+/// for a complete one. Any other failure stops the walk.
+#[allow(clippy::too_many_arguments)]
+fn list_across<R, T>(
+    ctx: &Context,
+    out: &mut dyn Write,
+    paging: &Paging,
+    noun: &str,
+    api: ApiContext<'_>,
+    targets: &[Target],
+    fetch: &mut FetchFrom<'_, R>,
+    split: fn(R) -> (Vec<T>, Pagination),
+    render: fn(&[T]) -> Rows,
+) -> Result<()> {
+    let per_page = paging.per_page.or(Some(200));
+    let mut collected: Vec<(&Tenant, Vec<Value>, Vec<T>)> = Vec::new();
+    let mut failures: Vec<Failure> = Vec::new();
+    let mut total = 0_usize;
+    for target in targets {
+        let Some(tenant) = &target.tenant else {
+            continue;
+        };
+        let walked = collect_pages(
+            noun,
+            &api,
+            per_page,
+            MAX_ITEMS.saturating_sub(total),
+            &mut |page, per_page| fetch(&target.client, page, per_page),
+            split,
+        );
+        match walked {
+            Ok((raw_items, items)) => {
+                total += items.len();
+                collected.push((tenant, raw_items, items));
+            }
+            Err(failure)
+                if matches!(
+                    failure.kind,
+                    Kind::Forbidden | Kind::NotFound | Kind::LicenceInactive
+                ) =>
+            {
+                eprintln!(
+                    "warning: client tenant {}: {}",
+                    clean(&tenant.slug),
+                    clean(&failure.message)
+                );
+                failures.push(failure);
+            }
+            Err(failure) => return Err(failure),
+        }
+    }
+
+    if ctx.json || paging.csv {
+        let mut labelled = Vec::new();
+        for (tenant, raw_items, _) in &collected {
+            for item in raw_items {
+                labelled.push(with_tenant(item, tenant)?);
+            }
+        }
+        if ctx.json {
+            print_json(out, &Value::Array(labelled))?;
+        } else {
+            print_csv(out, &labelled)?;
+        }
+    } else {
+        let mut headers = None;
+        let mut groups = Vec::new();
+        for (tenant, _, items) in &collected {
+            if items.is_empty() {
+                continue;
+            }
+            let rows = render(items);
+            headers.get_or_insert(rows.headers);
+            groups.push((tenant.slug.clone(), rows.rows));
+        }
+        if let Some(headers) = headers {
+            print_table(out, &tenant_table(headers, groups))?;
+        }
+    }
+    if total == 0 {
+        eprintln!("No {noun} found.");
+    } else {
+        eprintln!("{total} {noun} across {} client tenants.", collected.len());
+    }
+    match failures.first() {
+        None => Ok(()),
+        Some(first) => Err(Failure::new(
+            first.kind,
+            format!(
+                "Could not read {} of {} client tenants (see the warnings above); the output covers the others.",
+                failures.len(),
+                targets.len()
+            ),
+        )),
+    }
+}
+
+/// The item with the tenant whose request returned it in front: `tenant_id`, `tenant_slug` and
+/// `tenant_name`. An item that already has such a field is refused rather than overwritten.
+fn with_tenant(item: &Value, tenant: &Tenant) -> Result<Value> {
+    let Value::Object(fields) = item else {
+        return Err(Failure::general(
+            "An item of the answer is not an object, so it cannot be labelled with its tenant.",
+        ));
+    };
+    let mut labelled = serde_json::Map::new();
+    labelled.insert("tenant_id".to_owned(), Value::String(tenant.id.clone()));
+    labelled.insert("tenant_slug".to_owned(), Value::String(tenant.slug.clone()));
+    labelled.insert("tenant_name".to_owned(), Value::String(tenant.name.clone()));
+    for (key, value) in fields {
+        if labelled.contains_key(key) {
+            return Err(Failure::general(format!(
+                "An item already has a field named {}, which the tenant label would overwrite.",
+                clean(key)
+            )));
+        }
+        labelled.insert(key.clone(), value.clone());
+    }
+    Ok(Value::Object(labelled))
+}
+
 /// Walks every page, as received and decoded, stopping with an error past `max_items` items.
-fn collect_pages<R, T>(
+pub(super) fn collect_pages<R, T>(
     noun: &str,
     api: &ApiContext<'_>,
     per_page: Option<i64>,
@@ -167,9 +327,9 @@ fn plain(source: CredentialSource) -> ApiContext<'static> {
 
 pub fn vendors(ctx: &Context, command: VendorsCommand, out: &mut dyn Write) -> Result<()> {
     let settings = ctx.settings()?;
-    let (client, source) = ctx.api(&settings)?;
     match command {
         VendorsCommand::List(args) => {
+            let (targets, source) = ctx.targets(&settings)?;
             let base = ListVendorsParams {
                 q: args.query,
                 category: args.category,
@@ -185,7 +345,8 @@ pub fn vendors(ctx: &Context, command: VendorsCommand, out: &mut dyn Write) -> R
                 &args.paging,
                 "vendors",
                 plain(source),
-                &mut |page, per_page| {
+                &targets,
+                &mut |client, page, per_page| {
                     client.list_vendors(&ListVendorsParams {
                         page,
                         per_page,
@@ -197,13 +358,14 @@ pub fn vendors(ctx: &Context, command: VendorsCommand, out: &mut dyn Write) -> R
             )
         }
         VendorsCommand::Get { id } => {
+            let (client, source) = ctx.single(&settings)?;
             show(ctx, out, plain(source), client.get_vendor(&id), |r| &r.data)
         }
     }
 }
 
-fn vendor_table(items: &[Vendor]) -> Table {
-    table(
+fn vendor_table(items: &[Vendor]) -> Rows {
+    Rows::new(
         &["ID", "NAME", "DOMAIN", "CRITICALITY", "ACTIVE", "LAST SCAN"],
         items
             .iter()
@@ -223,13 +385,13 @@ fn vendor_table(items: &[Vendor]) -> Table {
 
 pub fn alerts(ctx: &Context, command: AlertsCommand, out: &mut dyn Write) -> Result<()> {
     let settings = ctx.settings()?;
-    let (client, source) = ctx.api(&settings)?;
     match command {
         AlertsCommand::List(args) => {
             warn_unknown(
                 &operations::LIST_ALERTS,
                 &[("severity", args.severity.as_deref())],
             );
+            let (targets, source) = ctx.targets(&settings)?;
             let base = ListAlertsParams {
                 status: args.status,
                 severity: args.severity,
@@ -245,7 +407,8 @@ pub fn alerts(ctx: &Context, command: AlertsCommand, out: &mut dyn Write) -> Res
                 &args.paging,
                 "alerts",
                 plain(source),
-                &mut |page, per_page| {
+                &targets,
+                &mut |client, page, per_page| {
                     client.list_alerts(&ListAlertsParams {
                         page,
                         per_page,
@@ -257,13 +420,14 @@ pub fn alerts(ctx: &Context, command: AlertsCommand, out: &mut dyn Write) -> Res
             )
         }
         AlertsCommand::Get { id } => {
+            let (client, source) = ctx.single(&settings)?;
             show(ctx, out, plain(source), client.get_alert(&id), |r| &r.data)
         }
     }
 }
 
-fn alert_table(items: &[Alert]) -> Table {
-    table(
+fn alert_table(items: &[Alert]) -> Rows {
+    Rows::new(
         &["ID", "SEVERITY", "STATUS", "TYPE", "TITLE", "CREATED"],
         items
             .iter()
@@ -283,7 +447,6 @@ fn alert_table(items: &[Alert]) -> Table {
 
 pub fn risks(ctx: &Context, command: RisksCommand, out: &mut dyn Write) -> Result<()> {
     let settings = ctx.settings()?;
-    let (client, source) = ctx.api(&settings)?;
     match command {
         RisksCommand::List(args) => {
             warn_unknown(
@@ -293,6 +456,7 @@ pub fn risks(ctx: &Context, command: RisksCommand, out: &mut dyn Write) -> Resul
                     ("domain", args.domain.as_deref()),
                 ],
             );
+            let (targets, source) = ctx.targets(&settings)?;
             let base = ListRisksParams {
                 status: args.status,
                 domain: args.domain,
@@ -308,7 +472,8 @@ pub fn risks(ctx: &Context, command: RisksCommand, out: &mut dyn Write) -> Resul
                 &args.paging,
                 "risks",
                 plain(source),
-                &mut |page, per_page| {
+                &targets,
+                &mut |client, page, per_page| {
                     client.list_risks(&ListRisksParams {
                         page,
                         per_page,
@@ -320,13 +485,14 @@ pub fn risks(ctx: &Context, command: RisksCommand, out: &mut dyn Write) -> Resul
             )
         }
         RisksCommand::Get { id } => {
+            let (client, source) = ctx.single(&settings)?;
             show(ctx, out, plain(source), client.get_risk(&id), |r| &r.data)
         }
     }
 }
 
-fn risk_table(items: &[Risk]) -> Table {
-    table(
+fn risk_table(items: &[Risk]) -> Rows {
+    Rows::new(
         &["ID", "TITLE", "DOMAIN", "STATUS", "INHERENT", "RESIDUAL"],
         items
             .iter()
@@ -347,13 +513,13 @@ fn risk_table(items: &[Risk]) -> Table {
 
 pub fn compliance(ctx: &Context, command: ComplianceCommand, out: &mut dyn Write) -> Result<()> {
     let settings = ctx.settings()?;
-    let (client, source) = ctx.api(&settings)?;
     match command {
         ComplianceCommand::Controls(args) => {
             warn_unknown(
                 &operations::LIST_COMPLIANCE_CONTROLS,
                 &[("status", args.status.as_deref())],
             );
+            let (targets, source) = ctx.targets(&settings)?;
             let api = ApiContext {
                 source,
                 framework: Some(&args.framework),
@@ -368,7 +534,8 @@ pub fn compliance(ctx: &Context, command: ComplianceCommand, out: &mut dyn Write
                 &args.paging,
                 "controls",
                 api,
-                &mut |page, per_page| {
+                &targets,
+                &mut |client, page, per_page| {
                     client.list_compliance_controls(&ListComplianceControlsParams {
                         page,
                         per_page,
@@ -380,6 +547,7 @@ pub fn compliance(ctx: &Context, command: ComplianceCommand, out: &mut dyn Write
             )
         }
         ComplianceCommand::Posture { framework } => {
+            let (client, source) = ctx.single(&settings)?;
             let api = ApiContext {
                 source,
                 framework: Some(&framework),
@@ -413,8 +581,8 @@ pub fn compliance(ctx: &Context, command: ComplianceCommand, out: &mut dyn Write
     }
 }
 
-fn control_table(items: &[ComplianceControl]) -> Table {
-    table(
+fn control_table(items: &[ComplianceControl]) -> Rows {
+    Rows::new(
         &["CONTROL", "STATUS", "EVIDENCE", "LAST EVALUATED"],
         items
             .iter()
@@ -432,9 +600,9 @@ fn control_table(items: &[ComplianceControl]) -> Table {
 
 pub fn evidence(ctx: &Context, command: EvidenceCommand, out: &mut dyn Write) -> Result<()> {
     let settings = ctx.settings()?;
-    let (client, source) = ctx.api(&settings)?;
     match command {
         EvidenceCommand::List(args) => {
+            let (targets, source) = ctx.targets(&settings)?;
             let base = ListEvidenceParams {
                 evidence_type: args.evidence_type,
                 source_type: args.source_type,
@@ -450,7 +618,8 @@ pub fn evidence(ctx: &Context, command: EvidenceCommand, out: &mut dyn Write) ->
                 &args.paging,
                 "evidence items",
                 plain(source),
-                &mut |page, per_page| {
+                &targets,
+                &mut |client, page, per_page| {
                     client.list_evidence(&ListEvidenceParams {
                         page,
                         per_page,
@@ -462,6 +631,7 @@ pub fn evidence(ctx: &Context, command: EvidenceCommand, out: &mut dyn Write) ->
             )
         }
         EvidenceCommand::Get { id } => {
+            let (client, source) = ctx.single(&settings)?;
             show(ctx, out, plain(source), client.get_evidence(&id), |r| {
                 &r.data
             })
@@ -469,8 +639,8 @@ pub fn evidence(ctx: &Context, command: EvidenceCommand, out: &mut dyn Write) ->
     }
 }
 
-fn evidence_table(items: &[Evidence]) -> Table {
-    table(
+fn evidence_table(items: &[Evidence]) -> Rows {
+    Rows::new(
         &["ID", "TYPE", "SOURCE", "TITLE", "VALID UNTIL"],
         items
             .iter()
@@ -489,9 +659,9 @@ fn evidence_table(items: &[Evidence]) -> Table {
 
 pub fn endpoints(ctx: &Context, command: EndpointsCommand, out: &mut dyn Write) -> Result<()> {
     let settings = ctx.settings()?;
-    let (client, source) = ctx.api(&settings)?;
     match command {
         EndpointsCommand::List(args) => {
+            let (targets, source) = ctx.targets(&settings)?;
             let base = ListEndpointsParams {
                 status: args.status,
                 silent_since: args.silent_since,
@@ -505,7 +675,8 @@ pub fn endpoints(ctx: &Context, command: EndpointsCommand, out: &mut dyn Write)
                 &args.paging,
                 "endpoints",
                 plain(source),
-                &mut |page, per_page| {
+                &targets,
+                &mut |client, page, per_page| {
                     client.list_endpoints(&ListEndpointsParams {
                         page,
                         per_page,
@@ -519,8 +690,8 @@ pub fn endpoints(ctx: &Context, command: EndpointsCommand, out: &mut dyn Write)
     }
 }
 
-fn endpoint_table(items: &[Endpoint]) -> Table {
-    table(
+fn endpoint_table(items: &[Endpoint]) -> Rows {
+    Rows::new(
         &[
             "ID",
             "HOSTNAME",
diff --git a/crates/hodeishield-cli/src/commands/tenants.rs b/crates/hodeishield-cli/src/commands/tenants.rs
new file mode 100644
index 0000000..43e37b9
--- /dev/null
+++ b/crates/hodeishield-cli/src/commands/tenants.rs
@@ -0,0 +1,217 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Hodeitek S.L.
+
+//! Client tenants: the `tenants` command and the selection of which client a read command reads.
+//!
+//! The CLI depends on the interface of `hodeishield_api::portfolio` only: it lists tenants and builds
+//! a client bound to one of them. How the selection travels on the wire is not known here.
+
+use super::Context;
+use super::resources::{collect_pages, list_one};
+use crate::cli::TenantsCommand;
+use crate::config::Settings;
+use crate::failure::{ApiContext, CredentialSource, Failure, Kind, Result};
+use crate::output::{Rows, cell, clean};
+use hodeishield_api::Client;
+use hodeishield_api::portfolio::{ListTenantsParams, ListTenantsResponse, Tenant, is_uuid};
+use std::io::Write;
+
+/// Which client tenant the read commands read.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Selection {
+    /// The credential's own tenant: what the CLI did before portfolios, with no tenant label.
+    Own,
+    /// One client, by slug or id.
+    Tenant(String),
+    /// Every client of the portfolio.
+    All,
+}
+
+/// A client to ask, and the tenant it is bound to. `tenant` is `None` only for [`Selection::Own`].
+/// Each target has its own client, so a request for one tenant can never carry another's selection.
+#[derive(Debug)]
+pub struct Target {
+    pub client: Client,
+    pub tenant: Option<Tenant>,
+}
+
+impl Context {
+    /// The clients to read for the selection. For [`Selection::Own`] this is one client and no
+    /// request is made; otherwise the portfolio is listed first.
+    pub fn targets(&self, settings: &Settings) -> Result<(Vec<Target>, CredentialSource)> {
+        let selected = match &self.selection {
+            Selection::Own => {
+                let (client, source) = self.api(settings, None)?;
+                return Ok((
+                    vec![Target {
+                        client,
+                        tenant: None,
+                    }],
+                    source,
+                ));
+            }
+            selected => selected,
+        };
+        let (lister, source) = self.api(settings, None)?;
+        let portfolio = list_portfolio(&lister, source)?;
+        let tenants = match selected {
+            Selection::Tenant(wanted) => {
+                let tenant = find(&portfolio, wanted)?;
+                eprintln!(
+                    "Client tenant: {} ({})",
+                    clean(&tenant.slug),
+                    clean(&tenant.id)
+                );
+                vec![tenant]
+            }
+            _ => {
+                let (usable, idle): (Vec<_>, Vec<_>) = portfolio.into_iter().partition(readable);
+                if !idle.is_empty() {
+                    eprintln!(
+                        "Skipping {} inactive client tenants (see `hodeishield tenants list`).",
+                        idle.len()
+                    );
+                }
+                usable
+            }
+        };
+        let targets = tenants
+            .into_iter()
+            .map(|tenant| {
+                let (client, _) = self.api(settings, Some(&tenant.id))?;
+                Ok(Target {
+                    client,
+                    tenant: Some(tenant),
+                })
+            })
+            .collect::<Result<_>>()?;
+        Ok((targets, source))
+    }
+
+    /// The one client a single-item command reads.
+    pub fn single(&self, settings: &Settings) -> Result<(Client, CredentialSource)> {
+        let (mut targets, source) = self.targets(settings)?;
+        match (targets.pop(), targets.is_empty()) {
+            (Some(target), true) => Ok((target.client, source)),
+            _ => Err(
+                Failure::general("This command reads one client tenant at a time.")
+                    .hint("Use --tenant <slug|id>; --all-tenants works on list commands."),
+            ),
+        }
+    }
+}
+
+/// Whether a tenant is worth asking: not inactive, and not without a licence in force.
+fn readable(tenant: &Tenant) -> bool {
+    tenant.active && tenant.licence_status.as_deref() != Some("inactive")
+}
+
+/// Every client tenant of the portfolio.
+fn list_portfolio(lister: &Client, source: CredentialSource) -> Result<Vec<Tenant>> {
+    let api = ApiContext {
+        source,
+        framework: None,
+    };
+    let (_, tenants) = collect_pages(
+        "client tenants",
+        &api,
+        Some(200),
+        100_000,
+        &mut |page, per_page| lister.list_tenants(&ListTenantsParams { page, per_page }),
+        |r: ListTenantsResponse| (r.data, r.pagination),
+    )
+    .map_err(|failure| {
+        if failure.kind == Kind::Forbidden {
+            failure.hint(
+                "--tenant and --all-tenants need a portfolio credential. Without them the CLI \
+                 reads the credential's own tenant.",
+            )
+        } else {
+            failure
+        }
+    })?;
+    Ok(tenants)
+}
+
+/// The tenant the user named, by id or slug. One that is not in the portfolio is reported the way
+/// the API reports it: not found, with no hint about whether it exists elsewhere.
+fn find(portfolio: &[Tenant], wanted: &str) -> Result<Tenant> {
+    let by_id = is_uuid(wanted);
+    let mut matches = portfolio.iter().filter(|t| {
+        if by_id {
+            t.id.eq_ignore_ascii_case(wanted)
+        } else {
+            t.slug.eq_ignore_ascii_case(wanted)
+        }
+    });
+    match (matches.next(), matches.next()) {
+        (Some(tenant), None) => Ok(tenant.clone()),
+        (Some(_), Some(_)) => Err(Failure::general(format!(
+            "More than one client tenant is called {}.",
+            clean(wanted)
+        ))
+        .hint("Use its id: see `hodeishield tenants list`.")),
+        _ => Err(Failure::new(
+            Kind::NotFound,
+            format!(
+                "No client tenant {} in this credential's portfolio.",
+                clean(wanted)
+            ),
+        )
+        .hint("List the client tenants you may read with `hodeishield tenants list`.")),
+    }
+}
+
+pub fn run(ctx: &Context, command: TenantsCommand, out: &mut dyn Write) -> Result<()> {
+    let TenantsCommand::List(args) = command;
+    let settings = ctx.settings()?;
+    let (client, source) = ctx.api(&settings, None)?;
+    list_one(
+        ctx,
+        out,
+        &args.paging,
+        "client tenants",
+        ApiContext {
+            source,
+            framework: None,
+        },
+        &mut |page, per_page| client.list_tenants(&ListTenantsParams { page, per_page }),
+        |r| (r.data, r.pagination),
+        tenant_rows,
+    )
+    .map_err(|failure| {
+        if failure.kind == Kind::Forbidden {
+            failure.hint("Listing client tenants needs a portfolio credential.")
+        } else {
+            failure
+        }
+    })
+}
+
+fn tenant_rows(items: &[Tenant]) -> Rows {
+    Rows::new(
+        &[
+            "SLUG",
+            "NAME",
+            "ORGANIZATION",
+            "TYPE",
+            "STATUS",
+            "LICENCE",
+            "ID",
+        ],
+        items
+            .iter()
+            .map(|t| {
+                vec![
+                    clean(&t.slug),
+                    clean(&t.name),
+                    cell(t.organization.as_ref().map(|o| o.name.as_str())),
+                    if t.internal { "own" } else { "client" }.to_owned(),
+                    if t.active { "active" } else { "inactive" }.to_owned(),
+                    cell(t.licence_status.as_deref()),
+                    clean(&t.id),
+                ]
+            })
+            .collect(),
+    )
+}
diff --git a/crates/hodeishield-cli/src/failure.rs b/crates/hodeishield-cli/src/failure.rs
index 8d7c6eb..6ffb4c5 100644
--- a/crates/hodeishield-cli/src/failure.rs
+++ b/crates/hodeishield-cli/src/failure.rs
@@ -178,10 +178,24 @@ pub fn from_api(error: hodeishield_api::Error, context: &ApiContext<'_>) -> Fail
                         format!("Rate limit exhausted{scope}.{wait}"),
                     )
                 }
-                400 => Failure::general(format!(
-                    "The API rejected the request: {}.",
-                    server_message.unwrap_or_else(|| "invalid request".to_owned())
-                )),
+                400 => {
+                    let failure = Failure::general(format!(
+                        "The API rejected the request: {}.",
+                        server_message.unwrap_or_else(|| "invalid request".to_owned())
+                    ));
+                    match detail(&api, "code") {
+                        Some("TENANT_REQUIRED") => failure.hint(
+                            "This credential covers several client tenants: pick one with \
+                             --tenant <slug|id>, or every one with --all-tenants on a list. \
+                             `hodeishield tenants list` shows them.",
+                        ),
+                        Some("TENANT_SELECTOR_NOT_SUPPORTED") => failure.hint(
+                            "This credential reads one tenant only; leave out --tenant and \
+                             --all-tenants.",
+                        ),
+                        _ => failure,
+                    }
+                }
                 status if status >= 500 => Failure::new(
                     Kind::Unavailable,
                     format!(
@@ -202,6 +216,11 @@ pub fn from_api(error: hodeishield_api::Error, context: &ApiContext<'_>) -> Fail
             "The answer to {operation} does not match the API description this CLI was built from: {source}."
         ))
         .hint("Your CLI may be older than the API. Check for a newer release."),
+        other @ hodeishield_api::Error::TenantMismatch { .. } => Failure::general(other.to_string())
+            .hint(
+                "Nothing was shown, so that no client's data appears under another's name. Check \
+                 the API URL and try again; if it persists, contact support.",
+            ),
         other => Failure::general(other.to_string()),
     }
 }
diff --git a/crates/hodeishield-cli/src/output.rs b/crates/hodeishield-cli/src/output.rs
index 4357c2f..a7149fd 100644
--- a/crates/hodeishield-cli/src/output.rs
+++ b/crates/hodeishield-cli/src/output.rs
@@ -122,6 +122,42 @@ pub fn short_time(value: Option<&str>) -> String {
     }
 }
 
+/// A table's header and rows, before they are laid out: what a command knows how to say about its
+/// items. [`tenant_table`] adds the client column when a list spans tenants.
+#[derive(Debug)]
+pub struct Rows {
+    pub headers: &'static [&'static str],
+    pub rows: Vec<Vec<String>>,
+}
+
+impl Rows {
+    pub fn new(headers: &'static [&'static str], rows: Vec<Vec<String>>) -> Self {
+        Self { headers, rows }
+    }
+
+    pub fn into_table(self) -> Table {
+        table(self.headers, self.rows)
+    }
+}
+
+/// Rows of several client tenants in one table, each led by the tenant's slug. The slug is the
+/// server's text, so it is sanitised like every other cell.
+pub fn tenant_table(headers: &[&str], groups: Vec<(String, Vec<Vec<String>>)>) -> Table {
+    let mut all = vec!["TENANT"];
+    all.extend_from_slice(headers);
+    let rows = groups
+        .into_iter()
+        .flat_map(|(slug, rows)| {
+            let label = clean(&slug);
+            rows.into_iter().map(move |mut row| {
+                row.insert(0, label.clone());
+                row
+            })
+        })
+        .collect();
+    table(&all, rows)
+}
+
 pub fn table(headers: &[&str], rows: Vec<Vec<String>>) -> Table {
     let mut table = Table::new();
     table
@@ -417,6 +453,34 @@ mod tests {
         );
     }
 
+    #[test]
+    fn a_tenant_column_leads_each_row_and_is_sanitised() {
+        let t = tenant_table(
+            &["ID"],
+            vec![
+                ("acme".to_owned(), vec![vec!["1".into()]]),
+                (
+                    "ev\u{1b}il".to_owned(),
+                    vec![vec!["2".into()], vec!["3".into()]],
+                ),
+            ],
+        );
+        let mut out = Vec::new();
+        print_table(&mut out, &t).expect("print");
+        let text = String::from_utf8(out).expect("utf8");
+        let lines: Vec<&str> = text.lines().collect();
+        assert!(
+            lines[0].starts_with("TENANT") && lines[0].ends_with("ID"),
+            "{text}"
+        );
+        assert!(
+            lines[1].starts_with("acme") && lines[1].ends_with('1'),
+            "{text}"
+        );
+        assert!(lines[2].starts_with("ev\u{fffd}il"), "{text:?}");
+        assert!(!text.contains('\u{1b}'));
+    }
+
     #[test]
     fn tables_have_no_trailing_spaces() {
         let t = table(
diff --git a/crates/hodeishield-cli/tests/cli.rs b/crates/hodeishield-cli/tests/cli.rs
index 18a8fe6..6dd1f08 100644
--- a/crates/hodeishield-cli/tests/cli.rs
+++ b/crates/hodeishield-cli/tests/cli.rs
@@ -771,3 +771,454 @@ fn free_form_filters_are_sent_as_typed_without_a_warning() {
         mock.assert();
     }
 }
+
+// Client tenants. The portfolio contract is a draft: these tests pin the CLI's behaviour against the
+// mock in `hodeishield_api::portfolio`, and change with it.
+
+const ACME: &str = "11111111-1111-4111-8111-111111111111";
+const BETA: &str = "22222222-2222-4222-8222-222222222222";
+const OLD: &str = "33333333-3333-4333-8333-333333333333";
+
+fn tenant(id: &str, slug: &str, active: bool, licence: &str) -> String {
+    format!(
+        r#"{{"id":"{id}","name":"{slug} S.L.","slug":"{slug}","organization":null,"internal":false,"active":{active},"licence_status":"{licence}"}}"#
+    )
+}
+
+fn portfolio(tenants: &[String]) -> String {
+    page(tenants, 1, tenants.len() as i64, 1)
+}
+
+fn mock_portfolio(server: &mut mockito::Server, tenants: &[String]) -> mockito::Mock {
+    server
+        .mock("GET", "/v1/portfolio/tenants")
+        .match_query(mockito::Matcher::Any)
+        .match_header("x-hs-tenant", mockito::Matcher::Missing)
+        .with_body(portfolio(tenants))
+        .create()
+}
+
+/// A vendor list for one tenant, confirmed the way the API confirms a selection.
+fn mock_vendors(server: &mut mockito::Server, tenant_id: &str, names: &[&str]) -> mockito::Mock {
+    let items: Vec<String> = names.iter().map(|n| vendor(&format!("v-{n}"), n)).collect();
+    server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .match_header("x-hs-tenant", tenant_id)
+        .with_header("x-hs-tenant", tenant_id)
+        .with_body(page(&items, 1, items.len() as i64, 1))
+        .create()
+}
+
+fn two_clients() -> [String; 2] {
+    [
+        tenant(ACME, "acme", true, "in_force"),
+        tenant(BETA, "beta", true, "grace"),
+    ]
+}
+
+#[test]
+fn tenants_list_prints_the_portfolio_as_table_json_and_csv() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    let listing = mock_portfolio(&mut server, &two_clients());
+    let table = env
+        .api(&server)
+        .args(["tenants", "list"])
+        .output()
+        .expect("run");
+    assert!(table.status.success(), "{table:?}");
+    let stdout = String::from_utf8_lossy(&table.stdout);
+    assert!(stdout.starts_with("SLUG"), "{stdout}");
+    assert!(
+        stdout.contains("acme") && stdout.contains(BETA) && stdout.contains("grace"),
+        "{stdout}"
+    );
+
+    let json = env
+        .api(&server)
+        .args(["tenants", "list", "--json"])
+        .output()
+        .expect("run");
+    let body: serde_json::Value = serde_json::from_slice(&json.stdout).expect("json");
+    assert_eq!(body["data"][1]["slug"], "beta");
+
+    let csv = env
+        .api(&server)
+        .args(["tenants", "list", "--csv"])
+        .output()
+        .expect("run");
+    assert!(String::from_utf8_lossy(&csv.stdout).starts_with("id,name,slug,"));
+    listing.expect_at_least(3).assert();
+}
+
+#[test]
+fn a_tenant_is_selected_by_slug_or_id_and_the_table_stays_as_it_was() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(&mut server, &two_clients());
+    let beta = mock_vendors(&mut server, BETA, &["Beta Hosting"]);
+    let acme = mock_vendors(&mut server, ACME, &["Acme Hosting"]);
+    for selector in ["beta", "BETA", BETA] {
+        let output = env
+            .api(&server)
+            .args(["--tenant", selector, "vendors", "list"])
+            .output()
+            .expect("run");
+        assert!(output.status.success(), "{selector}: {output:?}");
+        let stdout = String::from_utf8_lossy(&output.stdout);
+        assert!(
+            stdout.starts_with("ID") && stdout.contains("Beta Hosting"),
+            "{stdout}"
+        );
+        assert!(
+            !stdout.contains("TENANT") && !stdout.contains("Acme"),
+            "{stdout}"
+        );
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        assert!(
+            stderr.contains(&format!("Client tenant: beta ({BETA})")),
+            "{stderr}"
+        );
+        assert_no_key(&output);
+    }
+    beta.expect(3).assert();
+    acme.expect(0).assert();
+}
+
+#[test]
+fn a_selected_tenant_with_json_is_the_api_body_unchanged() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(&mut server, &two_clients());
+    let body = format!(r#"{{"data":{}}}"#, vendor("v-1", "Acme Hosting"));
+    server
+        .mock("GET", "/v1/vendors/v-1")
+        .match_header("x-hs-tenant", ACME)
+        .with_header("x-hs-tenant", ACME)
+        .with_body(&body)
+        .create();
+    let output = env
+        .api(&server)
+        .args(["vendors", "get", "v-1", "--json", "--tenant", "acme"])
+        .output()
+        .expect("run");
+    assert!(output.status.success(), "{output:?}");
+    let shown: serde_json::Value = serde_json::from_slice(&output.stdout).expect("json");
+    assert_eq!(
+        shown,
+        serde_json::from_str::<serde_json::Value>(&body).expect("json")
+    );
+}
+
+#[test]
+fn all_tenants_labels_every_row_with_the_tenant_that_returned_it() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(&mut server, &two_clients());
+    mock_vendors(&mut server, ACME, &["Acme Hosting", "Shared Name"]);
+    mock_vendors(&mut server, BETA, &["Beta Hosting", "Shared Name"]);
+
+    let table = env
+        .api(&server)
+        .args(["--all-tenants", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert!(table.status.success(), "{table:?}");
+    let stdout = String::from_utf8_lossy(&table.stdout);
+    let lines: Vec<&str> = stdout.lines().collect();
+    assert!(
+        lines[0].starts_with("TENANT") && lines[0].contains("ID"),
+        "{stdout}"
+    );
+    assert_eq!(lines.len(), 5, "{stdout}");
+    let row = |name: &str, slug: &str| {
+        lines
+            .iter()
+            .any(|l| l.starts_with(slug) && l.contains(name))
+    };
+    assert!(
+        row("Acme Hosting", "acme") && row("Beta Hosting", "beta"),
+        "{stdout}"
+    );
+    assert!(
+        !row("Acme Hosting", "beta") && !row("Beta Hosting", "acme"),
+        "{stdout}"
+    );
+    assert!(String::from_utf8_lossy(&table.stderr).contains("4 vendors across 2 client tenants."));
+
+    let json = env
+        .api(&server)
+        .args(["--json", "vendors", "list", "--all-tenants"])
+        .output()
+        .expect("run");
+    let items: serde_json::Value = serde_json::from_slice(&json.stdout).expect("json");
+    let items = items.as_array().expect("array");
+    assert_eq!(items.len(), 4);
+    assert_eq!(items[0]["tenant_id"], ACME);
+    assert_eq!(items[0]["tenant_slug"], "acme");
+    assert_eq!(items[0]["name"], "Acme Hosting");
+    assert_eq!(items[0]["added_later"], 1, "unknown fields are kept");
+    assert_eq!(items[3]["tenant_slug"], "beta");
+
+    let csv = env
+        .api(&server)
+        .args(["vendors", "list", "--all-tenants", "--csv"])
+        .output()
+        .expect("run");
+    let text = String::from_utf8_lossy(&csv.stdout);
+    assert!(
+        text.starts_with("tenant_id,tenant_slug,tenant_name,id,"),
+        "{text}"
+    );
+    assert!(
+        text.contains(&format!("{BETA},beta,beta S.L.,v-Beta Hosting,")),
+        "{text}"
+    );
+}
+
+#[test]
+fn all_tenants_skips_inactive_clients_and_says_so() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(
+        &mut server,
+        &[
+            tenant(ACME, "acme", true, "in_force"),
+            tenant(OLD, "old", false, "inactive"),
+        ],
+    );
+    mock_vendors(&mut server, ACME, &["Acme Hosting"]);
+    let output = env
+        .api(&server)
+        .args(["--all-tenants", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert!(output.status.success(), "{output:?}");
+    assert!(String::from_utf8_lossy(&output.stderr).contains("Skipping 1 inactive client tenants"));
+}
+
+#[test]
+fn a_tenant_that_cannot_be_read_is_reported_and_the_command_still_fails() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(&mut server, &two_clients());
+    mock_vendors(&mut server, ACME, &["Acme Hosting"]);
+    server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .match_header("x-hs-tenant", BETA)
+        .with_status(403)
+        .with_body(r#"{"error":{"code":"forbidden","message":"x","request_id":"r1","details":{"code":"LICENCE_INACTIVE","licence":"expired"}}}"#)
+        .create();
+    let output = env
+        .api(&server)
+        .args(["--all-tenants", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(8), "{output:?}");
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert!(stdout.contains("Acme Hosting"), "{stdout}");
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(stderr.contains("warning: client tenant beta"), "{stderr}");
+    assert!(
+        stderr.contains("Could not read 1 of 2 client tenants"),
+        "{stderr}"
+    );
+}
+
+#[test]
+fn a_client_outside_the_portfolio_fails_clearly_without_reading_any_data() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(&mut server, &two_clients());
+    let data = server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .expect(0)
+        .create();
+    for selector in ["stranger", "44444444-4444-4444-8444-444444444444"] {
+        let output = env
+            .api(&server)
+            .args(["vendors", "list", "--tenant", selector])
+            .output()
+            .expect("run");
+        assert_eq!(output.status.code(), Some(5), "{selector}: {output:?}");
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        assert!(
+            stderr.contains(&format!(
+                "No client tenant {selector} in this credential's portfolio."
+            )),
+            "{stderr}"
+        );
+        assert!(output.stdout.is_empty());
+    }
+    data.assert();
+}
+
+#[test]
+fn the_server_refusing_a_selected_client_is_not_found_too() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(&mut server, &two_clients());
+    server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .with_status(404)
+        .with_body(r#"{"error":{"code":"not_found","message":"No such tenant in this credential's portfolio.","request_id":"r2"}}"#)
+        .create();
+    let output = env
+        .api(&server)
+        .args(["vendors", "list", "--tenant", "acme"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(5), "{output:?}");
+    assert!(String::from_utf8_lossy(&output.stderr).contains("No such tenant"));
+}
+
+#[test]
+fn an_answer_that_does_not_confirm_the_client_prints_nothing() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(&mut server, &two_clients());
+    // The server answers with the other client's confirmation.
+    server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .with_header("x-hs-tenant", BETA)
+        .with_body(page(&[vendor("v1", "Beta Hosting")], 1, 1, 1))
+        .create();
+    for args in [&["--tenant", "acme"][..], &["--all-tenants"][..]] {
+        let output = env
+            .api(&server)
+            .args(args)
+            .args(["vendors", "list"])
+            .output()
+            .expect("run");
+        assert_eq!(output.status.code(), Some(1), "{args:?}: {output:?}");
+        assert!(output.stdout.is_empty(), "{output:?}");
+        assert!(
+            String::from_utf8_lossy(&output.stderr).contains("did not confirm the client tenant")
+        );
+    }
+}
+
+#[test]
+fn without_a_selection_nothing_changes_for_a_single_tenant_credential() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    let listing = server
+        .mock("GET", "/v1/portfolio/tenants")
+        .match_query(mockito::Matcher::Any)
+        .expect(0)
+        .create();
+    let vendors = server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .match_header("x-hs-tenant", mockito::Matcher::Missing)
+        .with_body(page(&[vendor("v1", "Example Hosting")], 1, 1, 1))
+        .create();
+    let output = env
+        .api(&server)
+        .args(["vendors", "list"])
+        .output()
+        .expect("run");
+    assert!(output.status.success(), "{output:?}");
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert!(
+        stdout.starts_with("ID") && !stdout.contains("TENANT"),
+        "{stdout}"
+    );
+    assert!(!String::from_utf8_lossy(&output.stderr).contains("Client tenant"));
+    listing.assert();
+    vendors.assert();
+}
+
+#[test]
+fn selecting_a_client_with_a_single_tenant_credential_explains_what_is_missing() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/portfolio/tenants")
+        .match_query(mockito::Matcher::Any)
+        .with_status(403)
+        .with_body(r#"{"error":{"code":"forbidden","message":"x","request_id":"r3"}}"#)
+        .create();
+    for args in [&["--tenant", "acme"][..], &["--all-tenants"][..]] {
+        let output = env
+            .api(&server)
+            .args(args)
+            .args(["vendors", "list"])
+            .output()
+            .expect("run");
+        assert_eq!(output.status.code(), Some(4), "{output:?}");
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        assert!(stderr.contains("portfolio:read"), "{stderr}");
+        assert!(stderr.contains("need a portfolio credential"), "{stderr}");
+    }
+    let output = env
+        .api(&server)
+        .args(["tenants", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(4), "{output:?}");
+}
+
+#[test]
+fn a_portfolio_credential_without_a_selection_is_told_how_to_select() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .with_status(400)
+        .with_body(r#"{"error":{"code":"invalid_request","message":"X-HS-Tenant is required","request_id":"r4","details":{"code":"TENANT_REQUIRED"}}}"#)
+        .create();
+    let output = env
+        .api(&server)
+        .args(["vendors", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(1));
+    assert!(String::from_utf8_lossy(&output.stderr).contains("--all-tenants"));
+}
+
+#[test]
+fn tenant_names_from_the_server_cannot_drive_the_terminal() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(
+        &mut server,
+        &[tenant(ACME, "ac\\u001b[2Jme", true, "in_force")],
+    );
+    mock_vendors(&mut server, ACME, &["Acme Hosting"]);
+    let output = env
+        .api(&server)
+        .args(["--all-tenants", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert!(output.status.success(), "{output:?}");
+    let all = format!(
+        "{}{}",
+        String::from_utf8_lossy(&output.stdout),
+        String::from_utf8_lossy(&output.stderr)
+    );
+    assert!(!all.contains('\u{1b}'), "{all:?}");
+    assert!(all.contains("ac\u{fffd}[2Jme"), "{all:?}");
+}
+
+#[test]
+fn the_selection_is_refused_where_it_cannot_apply() {
+    let env = Env::new();
+    for args in [
+        &["--tenant", "acme", "--all-tenants", "vendors", "list"][..],
+        &["--tenant", "acme", "whoami"][..],
+        &["--all-tenants", "tenants", "list"][..],
+        &["--all-tenants", "vendors", "get", "v1"][..],
+        &["--all-tenants", "compliance", "posture", "nis2"][..],
+        &["--all-tenants", "vendors", "list", "--page", "2"][..],
+    ] {
+        let output = env.cmd().args(args).output().expect("run");
+        assert_eq!(output.status.code(), Some(2), "{args:?}: {output:?}");
+    }
+}

From c6c2abf7c2d949249c9b7c8d47294d51577ba2f8 Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Wed, 7 Oct 2026 19:31:25 +0200
Subject: [PATCH 46/57] Document reading several client tenants with one
 credential

Add the 'Several tenants (MSSP)' section to the README and stop pointing
MSSPs at one profile per client. The section is a draft until the portfolio
part of /v1 is published.

Closes #45

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 README.md | 93 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 91 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 828be3a..d8cc30e 100644
--- a/README.md
+++ b/README.md
@@ -292,7 +292,7 @@ hodeishield logout           # revokes the token at the app and removes it from
 
 You sign in to [app.hodeishield.com](https://app.hodeishield.com) as usual (2FA, passkey or SSO), and
 on the consent screen you choose **the one tenant** the CLI may read. A sign-in token never covers
-more than that tenant, and it only reads. To use another tenant, define another profile and sign in
+more than that tenant, and it only reads. To use an unrelated tenant, define another profile and sign in
 to it:
 
 ```sh
@@ -305,6 +305,9 @@ A profile that has not been defined is refused (`Profile ... is not defined`).
 `login` first checks that the system keychain is available and stops before opening the browser or
 showing a code if it is not; use a tenant API key on such a machine.
 
+An MSSP reads its clients with one credential instead: see
+[Several tenants (MSSP)](#several-tenants-mssp).
+
 With `--device`, open the address the CLI prints on any device and **type the code by hand**: the app
 does not accept a link with the code filled in, on purpose.
 
@@ -350,6 +353,92 @@ rest. `--all` stops with an error past 100,000 items (or 1,000 pages); narrow th
 or walk it with `--page`. Every list takes `--sort` and `--order`; `--help` on any command lists
 what it accepts.
 
+### Several tenants (MSSP)
+
+An MSSP reads all of its client tenants with **one** credential: a portfolio key, created in the
+app by an administrator of an active MSSP organisation, in the MSSP area (API keys). You do not need
+a profile, a key or a sign-in per client, and you should not set them up that way.
+
+A portfolio key reads only, always expires (90 days by default, 365 at most), and works on the
+HodeiShield API only. It can be limited when it is created to some of your clients and to source IP
+ranges; a request from another address is refused like an unknown key (exit code 3). Signing in
+with `hodeishield login` does not cover a whole portfolio: use the key.
+
+**1. Use the credential as any other key.**
+
+```sh
+export HODEISHIELD_API_KEY=hsp_3f2a9c0d1b4e_...   # the portfolio key; keep it in your CI's secret store
+```
+
+The key starts with `hsp_`, a 12-character identifier and `_`, then a long secret. The first 16
+characters identify the key in the app and in audit entries; the CLI never prints any part of the
+key. The same variable takes a tenant API key as before.
+
+**2. List the client tenants it may read.**
+
+```console
+$ hodeishield tenants list
+SLUG    NAME        ORGANIZATION  TYPE    STATUS  LICENCE   ID
+acme    Acme S.L.   -             client  active  in_force  11111111-1111-4111-8111-111111111111
+beta    Beta Corp   Beta Group    client  active  grace     22222222-2222-4222-8222-222222222222
+```
+
+It takes `--json`, `--csv`, `--page` and `--all` like any list, sorted by name. It includes your
+own organisation's tenants (`TYPE` `own` for the internal one) and clients that are inactive or have
+no licence in force, which the `STATUS` and `LICENCE` columns tell apart. The list is read from the API
+each time: a client added to or removed from your portfolio shows up on the next command.
+
+**3. Select the client a read command reads.** The selection goes with the command and is never
+remembered, so a later command cannot read another client by surprise.
+
+```sh
+hodeishield --tenant acme vendors list            # one client, by slug or id
+hodeishield --all-tenants alerts list --status open
+```
+
+- `--tenant <slug|id>` works on every read command (`list`, `get`, `compliance posture`). The CLI
+  prints `Client tenant: acme (<id>)` on standard error, so a log shows which client was read;
+  standard output is exactly what it is without a selection.
+- `--all-tenants` works on `list` commands and `compliance controls`. It fetches every page of each
+  client (`--per-page` applies, `--page` does not) and adds the tenant to each row: a `TENANT`
+  column in the table, and `tenant_id`, `tenant_slug` and `tenant_name` fields in `--json` and
+  `--csv`. Clients that are not readable are skipped, with a note on standard error: those that
+  are inactive, whose licence status is `inactive`, or whose licence status this CLI does not
+  know. A client in its grace period is read. Clients are asked one after the other.
+- The tenant on a row is the one whose own request returned it. The CLI asks the API about one
+  client at a time, and refuses an answer that does not confirm that client.
+
+```sh
+hodeishield --all-tenants alerts list --status open --json \
+  | jq -r '.[] | [.tenant_slug, .severity, .title] | @tsv'
+hodeishield --all-tenants vendors list --criticality critical --csv > critical-vendors.csv
+```
+
+**4. When something is not readable.**
+
+- A client that is not in your portfolio (or that you mistyped) fails with `No client tenant … in
+  this credential's portfolio.` and exit code 5, before anything is read.
+- With `--all-tenants`, a client that cannot be read on its own account (for example its licence is
+  not in force, exit code 8) is reported on standard error and skipped; the command prints the
+  others and still exits non-zero, so a script does not mistake a partial result for a complete
+  one.
+- Without `--tenant` or `--all-tenants`, a portfolio key is refused by the API, and the CLI tells
+  you to choose. A single-tenant key or sign-in behaves exactly as before; asking it for a client
+  fails with exit code 4 (it lacks the portfolio scope).
+- A client you named that is deactivated, or whose licence is not in force, fails with exit code 8.
+- A portfolio key is limited to 100 requests per minute, and all the portfolio keys of your
+  organisation together to 600 (the API may change these numbers). The CLI waits out a short
+  `Retry-After` and retries; if the wait is longer, or the limit is still exhausted, the command
+  stops with exit code 6 and says which limit it hit (`portfolio_key`, `portfolio_org`,
+  `portfolio_tenant` or `tenant`), instead of asking the next client. Use `--per-page 200` and
+  narrow with filters to need fewer requests.
+- Against an API that does not offer portfolio access yet, `tenants list`, `--tenant` and
+  `--all-tenants` fail with `This API does not offer portfolio access yet.` and exit code 7. Nothing
+  else changes.
+
+**5. Revoke access.** Revoke the portfolio key in the app, in the MSSP area; it stops working on its
+next request. A client leaving your portfolio is dropped from the list on the next command.
+
 ### JSON for scripts
 
 `--json` prints the body the API returned, unchanged, including fields newer than your CLI. With
@@ -389,7 +478,7 @@ hodeishield vendors list --all --csv > vendors.csv
 | 4 | The credential lacks the scope the command needs |
 | 5 | Not found (or not in your organisation) |
 | 6 | Rate limit exhausted (the CLI already retried short waits) |
-| 7 | The API could not be reached or failed |
+| 7 | The API could not be reached or failed, or does not offer portfolio access yet |
 | 8 | The tenant's licence is not in force: a tenant administrator must renew or reactivate it |
 
 Errors go to stderr with a hint and, when the API gave one, a **request id**: quote it when you

From a370dfc4986ab81cd6ae6be02deb6af16895d315 Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Wed, 7 Oct 2026 19:31:25 +0200
Subject: [PATCH 47/57] Note the client tenant commands in the changelog

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 CHANGELOG.md | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4265079..1c76197 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -27,6 +27,17 @@ commands, `--json` output and exit codes. Each release's notes start with its se
   for each stable release: the release's own binary on a distroless base, running as a non-root
   user, tagged with the exact version only. It is signed by digest with Sigstore and carries the
   release's SBOM as a signed attestation. ([#36](https://github.com/Hodeitek/hodeishield-cli/issues/36))
+- Several client tenants with one MSSP credential. `hodeishield tenants list` lists the client
+  tenants the credential may read. The global `--tenant <slug|id>` selects one client for any read
+  command, and `--all-tenants` reads every client on a `list` command and adds `tenant_id`,
+  `tenant_slug` and `tenant_name` to each row in `--json` and `--csv` (a `TENANT` column in the
+  table). An unknown client fails with exit code 5, before any data is read. Without these options
+  nothing changes. `--all-tenants` skips clients that are inactive, whose licence is not in force, or
+  whose licence status the CLI does not know, asks one client at a time, and stops with exit code 6
+  (naming the limit) when a rate limit is exhausted. Against an API without portfolio access the
+  commands fail with exit code 7. The README has a new "Several tenants (MSSP)" section.
+  ([#54](https://github.com/Hodeitek/hodeishield-cli/issues/54),
+  [#45](https://github.com/Hodeitek/hodeishield-cli/issues/45))
 
 ### Changed (scripting surface)
 

From 1ac9a49fc6dadd4de6f09ea056a7d8e236c6be9e Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Thu, 8 Oct 2026 10:39:41 +0200
Subject: [PATCH 48/57] Follow the published portfolio contract

Read the client tenants as the API describes them: ask for the listing in
ascending name order, require the organisation, and treat a licence status
the CLI does not know as not readable. Accept a tenant confirmation only as
the single lowercase id that was asked for. An API with no listing route is
reported with exit code 7 instead of a generic failure.

A rate limit or a missing data scope now ends an all-tenants walk instead of
being repeated for every client, and the messages name the limit that was
hit and the tenant refusals the API distinguishes.

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 crates/hodeishield-api/src/error.rs           |   6 +
 crates/hodeishield-api/src/portfolio.rs       | 171 +++++++--
 crates/hodeishield-api/tests/api.rs           | 269 +++++++++++++-
 crates/hodeishield-cli/src/cli.rs             |   4 +-
 .../hodeishield-cli/src/commands/resources.rs |  11 +-
 .../hodeishield-cli/src/commands/tenants.rs   |  18 +-
 crates/hodeishield-cli/src/failure.rs         |  69 +++-
 crates/hodeishield-cli/tests/cli.rs           | 343 +++++++++++++++++-
 8 files changed, 813 insertions(+), 78 deletions(-)

diff --git a/crates/hodeishield-api/src/error.rs b/crates/hodeishield-api/src/error.rs
index 6f3569f..02937b1 100644
--- a/crates/hodeishield-api/src/error.rs
+++ b/crates/hodeishield-api/src/error.rs
@@ -86,6 +86,12 @@ pub enum Error {
     /// An id or slug that would change which resource the path addresses.
     #[error("{0:?} is not a valid identifier")]
     InvalidPathArgument(String),
+    /// The API has no portfolio listing (it answered `404` or `405` for the route).
+    #[error("this API does not offer portfolio access (HTTP {status} for the tenant listing)")]
+    PortfolioNotOffered {
+        /// The status the route answered with.
+        status: u16,
+    },
     /// A client tenant identifier that is not a UUID.
     #[error("{0:?} is not a valid client tenant identifier")]
     InvalidTenant(String),
diff --git a/crates/hodeishield-api/src/portfolio.rs b/crates/hodeishield-api/src/portfolio.rs
index 690027b..8be29d7 100644
--- a/crates/hodeishield-api/src/portfolio.rs
+++ b/crates/hodeishield-api/src/portfolio.rs
@@ -3,22 +3,31 @@
 
 //! Client tenants of a portfolio credential: list them, and read one of them.
 //!
-//! # Provisional
+//! This module follows the published `/v1` portfolio contract (contract version `2026-10-16`):
 //!
-//! **This module is written by hand against a draft of the `/v1` contract and is not part of the
-//! published API description yet.** Nothing in `openapi/v1.json` or the generated client describes
-//! it. When the contract is published, this file is the only place that changes: the operation, the
-//! shape of [`Tenant`] and the way the selected tenant travels on a request are all decided here,
-//! and callers see only the interface below.
+//! - `GET /v1/portfolio/tenants` (`listPortfolioTenants`), scope `portfolio:read`, paginated like
+//!   every `/v1` list (`page`, `per_page`, `sort`, `order`; the API's default order is descending,
+//!   so this client asks for ascending);
+//! - the client tenant is selected on each of the data operations with one optional `X-HS-Tenant`
+//!   request header holding the tenant's UUID, and every successful answer to such a request
+//!   repeats the tenant it read in an `X-HS-Tenant` response header (lowercase UUID). Error
+//!   answers never carry it, and the listing neither takes nor returns it;
+//! - a tenant is readable when it is active and its `licence_status` is `in_force` or `grace`. The
+//!   `licence_status` vocabulary is open: a value this client does not know counts as not
+//!   readable.
 //!
-//! The draft assumes:
+//! The version string of the API description is not compared with anything. Whether an API offers
+//! portfolio access is found by asking for the listing: a `404` or `405` on that route becomes
+//! [`Error::PortfolioNotOffered`].
 //!
-//! - `GET /v1/portfolio/tenants`, scope `portfolio:read`, paginated like the other lists
-//!   (`page`, `per_page`, answer `{ data, pagination }`);
-//! - the client is selected on every data operation with one `X-HS-Tenant` request header holding
-//!   the tenant's UUID, and every answer to such a request repeats it in an `X-HS-Tenant` response
-//!   header;
-//! - the listing does not take that header.
+//! # Relation to the generated client
+//!
+//! The vendored `openapi/v1.json` does not describe these operations yet, so this file is written
+//! by hand. When the vendored document is synced to the contract version above, the listing
+//! operation, [`Tenant`] and the paging types come from `cargo xtask codegen` (which first has to
+//! learn header parameters and the new security scheme), and this file shrinks to what is not an
+//! operation: [`ClientBuilder::tenant`] and its confirmation check, which the generated code does
+//! not provide.
 //!
 //! # Interface
 //!
@@ -29,7 +38,7 @@
 
 use crate::client::{Operation, Scope};
 use crate::error::Error;
-use crate::v1::Pagination;
+use crate::v1::{Order, Pagination};
 use crate::{ApiResponse, Client, ClientBuilder};
 use reqwest::header::{HeaderMap, HeaderName, HeaderValue};
 use serde::{Deserialize, Serialize};
@@ -55,24 +64,26 @@ pub struct Tenant {
     pub id: String,
     /// Display name.
     pub name: String,
-    /// Short unique name, for people and scripts.
+    /// Short name, unique across the platform, for people and scripts.
     pub slug: String,
-    /// The client organisation the tenant belongs to, when it has one.
-    #[serde(default)]
-    pub organization: Option<TenantOrganization>,
-    /// Whether this is the MSSP's own tenant rather than a client's.
-    #[serde(default)]
+    /// The organisation the tenant belongs to: the MSSP's own for the tenants it holds directly.
+    pub organization: TenantOrganization,
+    /// Whether this is the MSSP's own internal tenant rather than a client's.
     pub internal: bool,
-    /// Whether the tenant is active.
-    #[serde(default = "yes")]
+    /// Whether the tenant is enabled.
     pub active: bool,
-    /// `in_force`, `grace` or `inactive`. The vocabulary may grow.
-    #[serde(default)]
-    pub licence_status: Option<String>,
+    /// `in_force`, `grace` or `inactive`. The vocabulary is open: other values may appear.
+    pub licence_status: String,
 }
 
-fn yes() -> bool {
-    true
+impl Tenant {
+    /// Whether reading this tenant can be expected to work: it is active and its licence is in
+    /// force or in its grace period. A licence status this client does not know counts as not
+    /// readable, since the vocabulary is open.
+    #[must_use]
+    pub fn readable(&self) -> bool {
+        self.active && matches!(self.licence_status.as_str(), "in_force" | "grace")
+    }
 }
 
 /// The organisation a [`Tenant`] belongs to.
@@ -93,16 +104,51 @@ pub struct ListTenantsResponse {
     pub pagination: Pagination,
 }
 
-/// Paging of [`Client::list_tenants`].
+/// What [`Client::list_tenants`] sends.
 #[derive(Debug, Clone, Default, PartialEq, Eq)]
 pub struct ListTenantsParams {
     /// 1-based page number.
     pub page: Option<i64>,
     /// Items per page, 1..200.
     pub per_page: Option<i64>,
+    /// Sort by `name` or `slug`.
+    pub sort: Option<TenantSort>,
+    /// Direction. The API's default is descending.
+    pub order: Option<Order>,
+}
+
+/// The fields the tenant listing can be sorted by.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum TenantSort {
+    /// `name`
+    Name,
+    /// `slug`
+    Slug,
+}
+
+impl TenantSort {
+    /// The value as sent on the wire.
+    #[must_use]
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Name => "name",
+            Self::Slug => "slug",
+        }
+    }
 }
 
 impl ListTenantsParams {
+    /// Alphabetical by name, the order a person expects.
+    #[must_use]
+    pub fn alphabetical(page: Option<i64>, per_page: Option<i64>) -> Self {
+        Self {
+            page,
+            per_page,
+            sort: Some(TenantSort::Name),
+            order: Some(Order::Asc),
+        }
+    }
+
     fn query_pairs(&self) -> Vec<(&'static str, String)> {
         let mut pairs = Vec::new();
         if let Some(page) = self.page {
@@ -111,6 +157,12 @@ impl ListTenantsParams {
         if let Some(per_page) = self.per_page {
             pairs.push(("per_page", per_page.to_string()));
         }
+        if let Some(sort) = self.sort {
+            pairs.push(("sort", sort.as_str().to_owned()));
+        }
+        if let Some(order) = self.order {
+            pairs.push(("order", order.as_str().to_owned()));
+        }
         pairs
     }
 }
@@ -124,7 +176,8 @@ impl Client {
     /// # Errors
     ///
     /// [`Error`] when the request cannot be sent, the API answers with an error (a credential
-    /// without portfolio scope gets `403`), or the body does not match the draft.
+    /// without portfolio scope gets `403`), or the body does not match the contract.
+    /// [`Error::PortfolioNotOffered`] when the API has no such route.
     pub fn list_tenants(
         &self,
         params: &ListTenantsParams,
@@ -135,6 +188,12 @@ impl Client {
             params.query_pairs(),
             false,
         )
+        .map_err(|error| match error {
+            Error::Api(api) if matches!(api.status, 404 | 405) => {
+                Error::PortfolioNotOffered { status: api.status }
+            }
+            other => other,
+        })
     }
 }
 
@@ -158,10 +217,13 @@ impl ClientBuilder {
             HeaderValue::from_str(&wanted).map_err(|_| Error::InvalidTenant(id.to_owned()))?,
         );
         let check = move |answer: &HeaderMap| {
-            let answered = answer
-                .get(TENANT_HEADER)
-                .and_then(|v| v.to_str().ok())
-                .map(|v| v.trim().to_ascii_lowercase());
+            // Header names compare case-insensitively (the map does it); the answer must carry
+            // exactly one value, the lowercase UUID of the tenant that was read.
+            let mut values = answer.get_all(TENANT_HEADER).iter();
+            let answered = match (values.next(), values.next()) {
+                (Some(value), None) => value.to_str().ok().map(str::to_owned),
+                _ => None,
+            };
             if answered.as_deref() == Some(wanted.as_str()) {
                 Ok(())
             } else {
@@ -210,4 +272,47 @@ mod tests {
             assert!(!is_uuid(bad), "{bad:?}");
         }
     }
+
+    fn tenant(active: bool, licence: &str) -> Tenant {
+        Tenant {
+            id: "0b8f2a52-6a0e-4d5c-9d3e-1f2a3b4c5d6e".to_owned(),
+            name: "Acme".to_owned(),
+            slug: "acme".to_owned(),
+            organization: TenantOrganization {
+                id: "o".to_owned(),
+                name: "Acme Group".to_owned(),
+            },
+            internal: false,
+            active,
+            licence_status: licence.to_owned(),
+        }
+    }
+
+    #[test]
+    fn a_tenant_is_readable_only_when_active_with_a_known_good_licence() {
+        assert!(tenant(true, "in_force").readable());
+        assert!(tenant(true, "grace").readable());
+        assert!(!tenant(true, "inactive").readable());
+        assert!(!tenant(false, "in_force").readable());
+        assert!(!tenant(false, "grace").readable());
+        // The vocabulary is open: what is not known is not assumed readable.
+        assert!(!tenant(true, "suspended_soon").readable());
+        assert!(!tenant(true, "").readable());
+        assert!(!tenant(true, "IN_FORCE").readable());
+    }
+
+    #[test]
+    fn the_listing_asks_for_ascending_names_when_told_to() {
+        let pairs = ListTenantsParams::alphabetical(Some(2), Some(200)).query_pairs();
+        assert_eq!(
+            pairs,
+            vec![
+                ("page", "2".to_owned()),
+                ("per_page", "200".to_owned()),
+                ("sort", "name".to_owned()),
+                ("order", "asc".to_owned()),
+            ]
+        );
+        assert!(ListTenantsParams::default().query_pairs().is_empty());
+    }
 }
diff --git a/crates/hodeishield-api/tests/api.rs b/crates/hodeishield-api/tests/api.rs
index bb9bd8b..07d98ad 100644
--- a/crates/hodeishield-api/tests/api.rs
+++ b/crates/hodeishield-api/tests/api.rs
@@ -663,7 +663,11 @@ fn retry_observer_receives_expected_events() {
     success.assert();
 }
 
-// The portfolio module is provisional: these tests pin its interface, not the published contract.
+// The portfolio contract (version 2026-10-16): the listing, the tenant selection and its echo.
+
+/// The shape of a portfolio key: `hsp_`, 12 hex, `_`, 64 hex.
+const PORTFOLIO_KEY: &str =
+    "hsp_3f2a9c0d1b4e_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
 
 const TENANT_A: &str = "11111111-1111-4111-8111-111111111111";
 const TENANT_B: &str = "22222222-2222-4222-8222-222222222222";
@@ -673,7 +677,7 @@ const EMPTY_PAGE: &str =
 fn tenant_client(server: &mockito::Server, tenant: &str) -> Client {
     Client::builder(
         server.url().parse().expect("url"),
-        SecretString::from("hsp_example"),
+        SecretString::from(PORTFOLIO_KEY),
     )
     .tenant(tenant)
     .expect("a UUID")
@@ -687,10 +691,10 @@ fn list_tenants_decodes_the_listing_and_never_sends_a_tenant() {
     let mut server = mockito::Server::new();
     let mock = server
         .mock("GET", "/v1/portfolio/tenants")
-        .match_header("authorization", "Bearer hsp_example")
+        .match_header("authorization", format!("Bearer {PORTFOLIO_KEY}").as_str())
         .match_header("x-hs-tenant", mockito::Matcher::Missing)
         .with_body(format!(
-            r#"{{"data":[{{"id":"{TENANT_A}","name":"Acme","slug":"acme","organization":{{"id":"o1","name":"Acme Group"}},"internal":false,"active":true,"licence_status":"in_force","later":1}}],"pagination":{{"page":1,"per_page":50,"total":1,"total_pages":1}}}}"#
+            r#"{{"data":[{{"id":"{TENANT_A}","name":"Acme","slug":"acme","organization":{{"id":"o1","name":"Acme Group"}},"internal":false,"active":true,"licence_status":"in_force","later":1}},{{"id":"{TENANT_B}","name":"Beta","slug":"beta","organization":{{"id":"o2","name":"Beta Group"}},"internal":true,"active":false,"licence_status":"something_new"}}],"pagination":{{"page":1,"per_page":50,"total":2,"total_pages":1}}}}"#
         ))
         .create();
     // Even a client built for one tenant lists the whole portfolio.
@@ -699,11 +703,13 @@ fn list_tenants_decodes_the_listing_and_never_sends_a_tenant() {
         .expect("listing");
     mock.assert();
     assert_eq!(response.data.data[0].slug, "acme");
-    assert_eq!(
-        response.data.data[0].licence_status.as_deref(),
-        Some("in_force")
-    );
+    assert_eq!(response.data.data[0].licence_status, "in_force");
     assert_eq!(response.raw["data"][0]["later"], 1);
+    // An unknown licence status decodes, and is not readable.
+    let beta = &response.data.data[1];
+    assert_eq!(beta.licence_status, "something_new");
+    assert!(!beta.readable() && beta.internal);
+    assert!(response.data.data[0].readable());
 }
 
 #[test]
@@ -712,7 +718,9 @@ fn a_selected_tenant_travels_on_data_calls_and_must_be_confirmed() {
     let ok = server
         .mock("GET", "/v1/vendors")
         .match_header("x-hs-tenant", TENANT_A)
-        .with_header("x-hs-tenant", &TENANT_A.to_ascii_uppercase())
+        // Header names are case-insensitive; the value is the lowercase UUID.
+        .with_header("X-HS-Tenant", TENANT_A)
+        .with_header("Vary", "X-HS-Tenant")
         .with_body(EMPTY_PAGE)
         .create();
     tenant_client(&server, TENANT_A)
@@ -780,3 +788,246 @@ fn a_tenant_that_is_not_a_uuid_is_refused_before_any_request() {
         assert!(matches!(err, Error::InvalidTenant(_)), "{bad:?}");
     }
 }
+
+#[test]
+fn the_tenant_is_sent_in_lowercase_and_the_echo_must_be_exactly_that() {
+    let lower = "0b8f2a52-6a0e-4d5c-9d3e-1f2a3b4c5d6e";
+    let upper = lower.to_ascii_uppercase();
+    let mut server = mockito::Server::new();
+    // The request carries the lowercase form even when the caller gave capitals.
+    let sent = server
+        .mock("GET", "/v1/vendors")
+        .match_header("x-hs-tenant", lower)
+        .with_header("x-hs-tenant", lower)
+        .with_body(EMPTY_PAGE)
+        .create();
+    tenant_client(&server, &upper)
+        .list_vendors(&ListVendorsParams::default())
+        .expect("lowercase echo");
+    sent.assert();
+    // An echo in capitals is not what the contract promises: refused.
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/vendors")
+        .with_header("x-hs-tenant", &upper)
+        .with_body(EMPTY_PAGE)
+        .create();
+    let err = tenant_client(&server, lower)
+        .list_vendors(&ListVendorsParams::default())
+        .expect_err("not the contract's form");
+    assert!(matches!(err, Error::TenantMismatch { .. }), "{err:?}");
+}
+
+#[test]
+fn an_echo_that_names_two_tenants_is_refused() {
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/vendors")
+        .with_header("x-hs-tenant", TENANT_A)
+        .with_header("x-hs-tenant", TENANT_B)
+        .with_body(EMPTY_PAGE)
+        .create();
+    let err = tenant_client(&server, TENANT_A)
+        .list_vendors(&ListVendorsParams::default())
+        .expect_err("two values");
+    assert!(matches!(err, Error::TenantMismatch { .. }), "{err:?}");
+}
+
+#[test]
+fn every_data_operation_sends_the_selection_and_checks_the_echo() {
+    use hodeishield_api::v1::{
+        ListAlertsParams, ListComplianceControlsParams, ListEndpointsParams, ListEvidenceParams,
+        ListRisksParams,
+    };
+    let mut server = mockito::Server::new();
+    let any = server
+        .mock("GET", mockito::Matcher::Any)
+        .match_header("x-hs-tenant", TENANT_A)
+        .with_header("x-hs-tenant", TENANT_B)
+        .with_body(EMPTY_PAGE)
+        .expect(5)
+        .create();
+    let c = tenant_client(&server, TENANT_A);
+    fn refused<T>(r: Result<T, Error>) -> bool {
+        matches!(r, Err(Error::TenantMismatch { .. }))
+    }
+    assert!(refused(c.list_alerts(&ListAlertsParams::default())));
+    assert!(refused(c.list_risks(&ListRisksParams::default())));
+    assert!(refused(c.list_evidence(&ListEvidenceParams::default())));
+    assert!(refused(c.list_endpoints(&ListEndpointsParams::default())));
+    assert!(refused(c.list_compliance_controls(
+        &ListComplianceControlsParams {
+            page: None,
+            per_page: None,
+            sort: None,
+            order: None,
+            framework: "nis2".to_owned(),
+            status: None,
+        }
+    )));
+    any.assert();
+}
+
+#[test]
+fn an_error_answer_is_reported_as_the_api_error_whatever_the_header_says() {
+    // The contract has no echo on errors; a client must not mistake one for a mismatch, nor hide
+    // the real refusal behind it.
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/vendors")
+        .with_status(404)
+        .with_body(r#"{"error":{"code":"not_found","message":"No such tenant in this credential's portfolio.","request_id":"r","details":{"code":"TENANT_NOT_FOUND"}}}"#)
+        .create();
+    let err = tenant_client(&server, TENANT_A)
+        .list_vendors(&ListVendorsParams::default())
+        .expect_err("not in the portfolio");
+    let api = err.api().expect("the API's own error");
+    assert_eq!(api.status, 404);
+    let details = api
+        .body
+        .as_ref()
+        .and_then(|b| b.details.as_ref())
+        .expect("details");
+    assert_eq!(details["code"], "TENANT_NOT_FOUND");
+}
+
+#[test]
+fn the_listing_asks_for_the_order_it_is_given() {
+    use hodeishield_api::portfolio::ListTenantsParams;
+    let mut server = mockito::Server::new();
+    let mock = server
+        .mock("GET", "/v1/portfolio/tenants")
+        .match_query(mockito::Matcher::AllOf(vec![
+            mockito::Matcher::UrlEncoded("page".into(), "2".into()),
+            mockito::Matcher::UrlEncoded("per_page".into(), "200".into()),
+            mockito::Matcher::UrlEncoded("sort".into(), "name".into()),
+            mockito::Matcher::UrlEncoded("order".into(), "asc".into()),
+        ]))
+        .with_body(EMPTY_PAGE)
+        .create();
+    client(&server)
+        .list_tenants(&ListTenantsParams::alphabetical(Some(2), Some(200)))
+        .expect("listing");
+    mock.assert();
+}
+
+#[test]
+fn a_listing_that_breaks_the_contract_is_a_decode_error() {
+    use hodeishield_api::portfolio::ListTenantsParams;
+    let mut server = mockito::Server::new();
+    // `organization` is never null.
+    server
+        .mock("GET", "/v1/portfolio/tenants")
+        .with_body(format!(
+            r#"{{"data":[{{"id":"{TENANT_A}","name":"A","slug":"a","organization":null,"internal":false,"active":true,"licence_status":"in_force"}}],"pagination":{{"page":1,"per_page":50,"total":1,"total_pages":1}}}}"#
+        ))
+        .create();
+    let err = client(&server)
+        .list_tenants(&ListTenantsParams::default())
+        .expect_err("null organization");
+    assert!(matches!(err, Error::Decode { .. }), "{err:?}");
+}
+
+#[test]
+fn an_api_without_the_listing_route_is_told_apart_from_other_errors() {
+    use hodeishield_api::portfolio::ListTenantsParams;
+    for status in [404_usize, 405] {
+        let mut server = mockito::Server::new();
+        server
+            .mock("GET", "/v1/portfolio/tenants")
+            .with_status(status)
+            .with_body(r#"{"error":{"code":"not_found","message":"Not found","request_id":"r"}}"#)
+            .create();
+        let err = client(&server)
+            .list_tenants(&ListTenantsParams::default())
+            .expect_err("no route");
+        assert!(
+            matches!(&err, Error::PortfolioNotOffered { status: s } if usize::from(*s) == status),
+            "{status}: {err:?}"
+        );
+    }
+    // Other statuses stay what the API said, and a 404 on a data operation is not this.
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/portfolio/tenants")
+        .with_status(403)
+        .with_body(r#"{"error":{"code":"forbidden","message":"x","request_id":"r","details":{"code":"INSUFFICIENT_SCOPE","missing":["portfolio:read"]}}}"#)
+        .create();
+    server
+        .mock("GET", "/v1/vendors/v1")
+        .with_status(404)
+        .with_body(r#"{"error":{"code":"not_found","message":"x","request_id":"r"}}"#)
+        .create();
+    let c = client(&server);
+    let err = c
+        .list_tenants(&ListTenantsParams::default())
+        .expect_err("403");
+    assert_eq!(err.api().map(|a| a.status), Some(403));
+    let err = c.get_vendor("v1").expect_err("404");
+    assert_eq!(err.api().map(|a| a.status), Some(404));
+}
+
+#[test]
+fn a_portfolio_429_is_retried_after_a_short_retry_after_and_reports_its_scope_otherwise() {
+    use hodeishield_api::portfolio::ListTenantsParams;
+    let body = r#"{"error":{"code":"rate_limited","message":"x","request_id":"r","details":{"scope":"portfolio_key","limit":100,"window_seconds":60,"retry_after_seconds":1}}}"#;
+    // Within the wait the client accepts: waited out, then served.
+    let mut server = mockito::Server::new();
+    let limited = server
+        .mock("GET", "/v1/portfolio/tenants")
+        .with_status(429)
+        .with_header("retry-after", "1")
+        .with_body(body)
+        .expect(1)
+        .create();
+    let served = server
+        .mock("GET", "/v1/portfolio/tenants")
+        .with_body(EMPTY_PAGE)
+        .expect(1)
+        .create();
+    client(&server)
+        .list_tenants(&ListTenantsParams::default())
+        .expect("served after the wait");
+    limited.assert();
+    served.assert();
+    // Longer than the client accepts: one request, and the scope is in the error.
+    let mut server = mockito::Server::new();
+    let once = server
+        .mock("GET", "/v1/portfolio/tenants")
+        .with_status(429)
+        .with_header("retry-after", "600")
+        .with_body(body)
+        .expect(1)
+        .create();
+    let err = client(&server)
+        .list_tenants(&ListTenantsParams::default())
+        .expect_err("too long to wait");
+    once.assert();
+    let api = err.api().expect("API error");
+    assert_eq!(api.status, 429);
+    assert_eq!(api.meta.retry_after, Some(600));
+    let details = api
+        .body
+        .as_ref()
+        .and_then(|b| b.details.as_ref())
+        .expect("details");
+    assert_eq!(details["scope"], "portfolio_key");
+}
+
+#[test]
+fn a_portfolio_key_is_sent_whole_and_never_shown() {
+    let server = mockito::Server::new();
+    let c = tenant_client(&server, TENANT_A);
+    let shown = format!("{c:?}");
+    let secret = PORTFOLIO_KEY.rsplit('_').next().expect("secret part");
+    assert!(
+        !shown.contains(secret) && !shown.contains(PORTFOLIO_KEY),
+        "{shown}"
+    );
+    let builder = Client::builder(
+        server.url().parse().expect("url"),
+        SecretString::from(PORTFOLIO_KEY),
+    );
+    let shown = format!("{builder:?}");
+    assert!(!shown.contains(secret), "{shown}");
+}
diff --git a/crates/hodeishield-cli/src/cli.rs b/crates/hodeishield-cli/src/cli.rs
index 6e2d66f..9f52e3d 100644
--- a/crates/hodeishield-cli/src/cli.rs
+++ b/crates/hodeishield-cli/src/cli.rs
@@ -16,7 +16,7 @@ use std::str::FromStr;
 
 const AFTER_HELP: &str = "\
 Credentials:
-  HODEISHIELD_API_KEY   A tenant API key. When set, it is used for every API call.
+  HODEISHIELD_API_KEY   A tenant API key, or an MSSP portfolio key (hsp_…). When set, it is used for every API call.
   hodeishield login     Otherwise, sign in to the app; the token is kept in the system keychain.
 
 Several client tenants (portfolio credential):
@@ -26,7 +26,7 @@ Several client tenants (portfolio credential):
 
 Exit codes:
   0 ok · 1 error · 2 usage · 3 not authenticated · 4 missing scope · 5 not found
-  6 rate limited · 7 API unreachable or failing · 8 tenant licence not in force";
+  6 rate limited · 7 API unreachable, failing or without portfolio access · 8 tenant licence not in force";
 
 /// Read-only command-line client for HodeiShield.
 ///
diff --git a/crates/hodeishield-cli/src/commands/resources.rs b/crates/hodeishield-cli/src/commands/resources.rs
index 6170241..d17459e 100644
--- a/crates/hodeishield-cli/src/commands/resources.rs
+++ b/crates/hodeishield-cli/src/commands/resources.rs
@@ -135,7 +135,9 @@ pub(super) fn list_one<R, T>(
 ///
 /// A tenant that cannot be read for its own reasons (no licence, left the portfolio) is reported
 /// and skipped, and the command still fails at the end, so a script never takes a partial result
-/// for a complete one. Any other failure stops the walk.
+/// for a complete one. Any other failure stops the walk: tenants are asked one after the other, and
+/// a rate limit (after the client has waited out the short ones) or a missing scope is not retried
+/// against the next tenant.
 #[allow(clippy::too_many_arguments)]
 fn list_across<R, T>(
     ctx: &Context,
@@ -169,12 +171,7 @@ fn list_across<R, T>(
                 total += items.len();
                 collected.push((tenant, raw_items, items));
             }
-            Err(failure)
-                if matches!(
-                    failure.kind,
-                    Kind::Forbidden | Kind::NotFound | Kind::LicenceInactive
-                ) =>
-            {
+            Err(failure) if matches!(failure.kind, Kind::NotFound | Kind::LicenceInactive) => {
                 eprintln!(
                     "warning: client tenant {}: {}",
                     clean(&tenant.slug),
diff --git a/crates/hodeishield-cli/src/commands/tenants.rs b/crates/hodeishield-cli/src/commands/tenants.rs
index 43e37b9..43205b0 100644
--- a/crates/hodeishield-cli/src/commands/tenants.rs
+++ b/crates/hodeishield-cli/src/commands/tenants.rs
@@ -11,7 +11,7 @@ use super::resources::{collect_pages, list_one};
 use crate::cli::TenantsCommand;
 use crate::config::Settings;
 use crate::failure::{ApiContext, CredentialSource, Failure, Kind, Result};
-use crate::output::{Rows, cell, clean};
+use crate::output::{Rows, clean};
 use hodeishield_api::Client;
 use hodeishield_api::portfolio::{ListTenantsParams, ListTenantsResponse, Tenant, is_uuid};
 use std::io::Write;
@@ -65,7 +65,8 @@ impl Context {
                 vec![tenant]
             }
             _ => {
-                let (usable, idle): (Vec<_>, Vec<_>) = portfolio.into_iter().partition(readable);
+                let (usable, idle): (Vec<_>, Vec<_>) =
+                    portfolio.into_iter().partition(Tenant::readable);
                 if !idle.is_empty() {
                     eprintln!(
                         "Skipping {} inactive client tenants (see `hodeishield tenants list`).",
@@ -101,11 +102,6 @@ impl Context {
     }
 }
 
-/// Whether a tenant is worth asking: not inactive, and not without a licence in force.
-fn readable(tenant: &Tenant) -> bool {
-    tenant.active && tenant.licence_status.as_deref() != Some("inactive")
-}
-
 /// Every client tenant of the portfolio.
 fn list_portfolio(lister: &Client, source: CredentialSource) -> Result<Vec<Tenant>> {
     let api = ApiContext {
@@ -117,7 +113,7 @@ fn list_portfolio(lister: &Client, source: CredentialSource) -> Result<Vec<Tenan
         &api,
         Some(200),
         100_000,
-        &mut |page, per_page| lister.list_tenants(&ListTenantsParams { page, per_page }),
+        &mut |page, per_page| lister.list_tenants(&ListTenantsParams::alphabetical(page, per_page)),
         |r: ListTenantsResponse| (r.data, r.pagination),
     )
     .map_err(|failure| {
@@ -175,7 +171,7 @@ pub fn run(ctx: &Context, command: TenantsCommand, out: &mut dyn Write) -> Resul
             source,
             framework: None,
         },
-        &mut |page, per_page| client.list_tenants(&ListTenantsParams { page, per_page }),
+        &mut |page, per_page| client.list_tenants(&ListTenantsParams::alphabetical(page, per_page)),
         |r| (r.data, r.pagination),
         tenant_rows,
     )
@@ -205,10 +201,10 @@ fn tenant_rows(items: &[Tenant]) -> Rows {
                 vec![
                     clean(&t.slug),
                     clean(&t.name),
-                    cell(t.organization.as_ref().map(|o| o.name.as_str())),
+                    clean(&t.organization.name),
                     if t.internal { "own" } else { "client" }.to_owned(),
                     if t.active { "active" } else { "inactive" }.to_owned(),
-                    cell(t.licence_status.as_deref()),
+                    clean(&t.licence_status),
                     clean(&t.id),
                 ]
             })
diff --git a/crates/hodeishield-cli/src/failure.rs b/crates/hodeishield-cli/src/failure.rs
index 6ffb4c5..1af55fa 100644
--- a/crates/hodeishield-cli/src/failure.rs
+++ b/crates/hodeishield-cli/src/failure.rs
@@ -20,9 +20,10 @@ pub enum Kind {
     NotFound,
     /// A rate limit is exhausted (429). Exit code 6.
     RateLimited,
-    /// The API could not be reached or failed (network, 5xx). Exit code 7.
+    /// The API could not be reached, failed (network, 5xx), or lacks a feature the command needs
+    /// (no portfolio listing). Exit code 7.
     Unavailable,
-    /// The tenant holds no licence in force (403 `LICENCE_INACTIVE`). Exit code 8.
+    /// The tenant holds no licence in force, or is deactivated (403 `LICENCE_INACTIVE`). Exit code 8.
     LicenceInactive,
 }
 
@@ -139,10 +140,12 @@ pub fn from_api(error: hodeishield_api::Error, context: &ApiContext<'_>) -> Fail
                                 && s.chars().all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-')
                         })
                         .map_or_else(String::new, |s| format!(" (licence: {s})"));
-                    Failure::new(
-                        Kind::LicenceInactive,
-                        format!("The tenant's licence is not in force{state}."),
-                    )
+                    let message = if detail(&api, "licence") == Some("tenant_inactive") {
+                        "The tenant is deactivated.".to_owned()
+                    } else {
+                        format!("The tenant's licence is not in force{state}.")
+                    };
+                    Failure::new(Kind::LicenceInactive, message)
                     .hint(
                         "Ask a tenant administrator to renew or reactivate it. Signing in again or \
                          using another key of this tenant will not help.",
@@ -163,20 +166,49 @@ pub fn from_api(error: hodeishield_api::Error, context: &ApiContext<'_>) -> Fail
                     )
                     .hint("Ask a tenant administrator for a key or access with that scope.")
                 }
-                404 => Failure::new(
-                    Kind::NotFound,
-                    server_message.unwrap_or_else(|| "Not found.".to_owned()),
-                ),
+                404 => {
+                    let failure = Failure::new(
+                        Kind::NotFound,
+                        server_message.unwrap_or_else(|| "Not found.".to_owned()),
+                    );
+                    if detail(&api, "code") == Some("TENANT_NOT_FOUND") {
+                        failure.hint(
+                            "The client tenant is not in this credential's portfolio (or it left \
+                             it). `hodeishield tenants list` shows the ones you may read.",
+                        )
+                    } else {
+                        failure
+                    }
+                }
                 429 => {
                     let wait = api
                         .meta
                         .retry_after
                         .map_or_else(String::new, |s| format!(" Try again in {s} s."));
                     let scope = detail(&api, "scope").map_or_else(String::new, |s| format!(" (limit: {s})"));
-                    Failure::new(
+                    let hint = match detail(&api, "scope") {
+                        Some("portfolio_key") => Some(
+                            "This portfolio key has used its requests for the minute. A script \
+                             that reads many client tenants should pause between runs.",
+                        ),
+                        Some("portfolio_org") => Some(
+                            "All portfolio keys of your organisation share this limit; another key \
+                             or script may be using it.",
+                        ),
+                        Some("portfolio_tenant" | "tenant") => Some(
+                            "This client tenant's own limit is used up; other client tenants are \
+                             not affected.",
+                        ),
+                        _ => None,
+                    };
+                    let failure = Failure::new(
                         Kind::RateLimited,
                         format!("Rate limit exhausted{scope}.{wait}"),
-                    )
+                    );
+                    match hint {
+                        Some(hint) => failure.hint(hint),
+                        None => failure,
+                    }
                 }
                 400 => {
                     let failure = Failure::general(format!(
@@ -193,6 +225,10 @@ pub fn from_api(error: hodeishield_api::Error, context: &ApiContext<'_>) -> Fail
                             "This credential reads one tenant only; leave out --tenant and \
                              --all-tenants.",
                         ),
+                        Some("TENANT_HEADER_INVALID") => failure.hint(
+                            "The CLI sent a tenant selection the API could not read. This is a \
+                             bug: please report it.",
+                        ),
                         _ => failure,
                     }
                 }
@@ -216,6 +252,15 @@ pub fn from_api(error: hodeishield_api::Error, context: &ApiContext<'_>) -> Fail
             "The answer to {operation} does not match the API description this CLI was built from: {source}."
         ))
         .hint("Your CLI may be older than the API. Check for a newer release."),
+        hodeishield_api::Error::PortfolioNotOffered { .. } => Failure::new(
+            Kind::Unavailable,
+            "This API does not offer portfolio access yet.",
+        )
+        .hint(
+            "Reading several client tenants with one credential needs a newer API, or the API URL \
+             is not the HodeiShield /v1 API. Without --tenant and --all-tenants the CLI reads the \
+             credential's own tenant as before.",
+        ),
         other @ hodeishield_api::Error::TenantMismatch { .. } => Failure::general(other.to_string())
             .hint(
                 "Nothing was shown, so that no client's data appears under another's name. Check \
diff --git a/crates/hodeishield-cli/tests/cli.rs b/crates/hodeishield-cli/tests/cli.rs
index 6dd1f08..a06d2c6 100644
--- a/crates/hodeishield-cli/tests/cli.rs
+++ b/crates/hodeishield-cli/tests/cli.rs
@@ -772,8 +772,11 @@ fn free_form_filters_are_sent_as_typed_without_a_warning() {
     }
 }
 
-// Client tenants. The portfolio contract is a draft: these tests pin the CLI's behaviour against the
-// mock in `hodeishield_api::portfolio`, and change with it.
+// Client tenants, against a mock of the published portfolio contract (version 2026-10-16).
+
+/// The shape of a portfolio key: `hsp_`, 12 hex, `_`, 64 hex. Its secret part must never be shown.
+const PORTFOLIO_KEY: &str =
+    "hsp_3f2a9c0d1b4e_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
 
 const ACME: &str = "11111111-1111-4111-8111-111111111111";
 const BETA: &str = "22222222-2222-4222-8222-222222222222";
@@ -781,7 +784,7 @@ const OLD: &str = "33333333-3333-4333-8333-333333333333";
 
 fn tenant(id: &str, slug: &str, active: bool, licence: &str) -> String {
     format!(
-        r#"{{"id":"{id}","name":"{slug} S.L.","slug":"{slug}","organization":null,"internal":false,"active":{active},"licence_status":"{licence}"}}"#
+        r#"{{"id":"{id}","name":"{slug} S.L.","slug":"{slug}","organization":{{"id":"o-{slug}","name":"{slug} Group"}},"internal":false,"active":{active},"licence_status":"{licence}"}}"#
     )
 }
 
@@ -792,7 +795,11 @@ fn portfolio(tenants: &[String]) -> String {
 fn mock_portfolio(server: &mut mockito::Server, tenants: &[String]) -> mockito::Mock {
     server
         .mock("GET", "/v1/portfolio/tenants")
-        .match_query(mockito::Matcher::Any)
+        // The API's default order is descending; the CLI asks for alphabetical.
+        .match_query(mockito::Matcher::AllOf(vec![
+            mockito::Matcher::UrlEncoded("sort".into(), "name".into()),
+            mockito::Matcher::UrlEncoded("order".into(), "asc".into()),
+        ]))
         .match_header("x-hs-tenant", mockito::Matcher::Missing)
         .with_body(portfolio(tenants))
         .create()
@@ -1222,3 +1229,331 @@ fn the_selection_is_refused_where_it_cannot_apply() {
         assert_eq!(output.status.code(), Some(2), "{args:?}: {output:?}");
     }
 }
+
+/// Runs the CLI with a real-shaped portfolio key, so a leak of the secret part would show.
+fn portfolio_cmd(env: &Env, server: &mockito::Server) -> Command {
+    let mut cmd = env.cmd();
+    cmd.env("HODEISHIELD_API_KEY", PORTFOLIO_KEY)
+        .env("HODEISHIELD_API_URL", server.url());
+    cmd
+}
+
+fn assert_no_portfolio_secret(output: &std::process::Output) {
+    let all = format!(
+        "{}{}",
+        String::from_utf8_lossy(&output.stdout),
+        String::from_utf8_lossy(&output.stderr)
+    );
+    let secret = PORTFOLIO_KEY.rsplit('_').next().expect("secret part");
+    assert!(
+        !all.contains(secret),
+        "the key's secret part leaked:\n{all}"
+    );
+    assert!(!all.contains(PORTFOLIO_KEY), "the key leaked:\n{all}");
+}
+
+#[test]
+fn a_portfolio_key_in_its_published_format_is_sent_as_a_bearer_and_never_shown() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    let bearer = format!("Bearer {PORTFOLIO_KEY}");
+    let listing = server
+        .mock("GET", "/v1/portfolio/tenants")
+        .match_query(mockito::Matcher::Any)
+        .match_header("authorization", bearer.as_str())
+        .with_body(portfolio(&two_clients()))
+        .create();
+    server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .match_header("authorization", bearer.as_str())
+        .match_header("x-hs-tenant", ACME)
+        .with_header("x-hs-tenant", ACME)
+        .with_body(page(&[vendor("v1", "Acme Hosting")], 1, 1, 1))
+        .create();
+    for args in [
+        &["tenants", "list"][..],
+        &["--tenant", "acme", "vendors", "list"][..],
+    ] {
+        let output = portfolio_cmd(&env, &server)
+            .args(args)
+            .output()
+            .expect("run");
+        assert!(output.status.success(), "{args:?}: {output:?}");
+        assert_no_portfolio_secret(&output);
+    }
+    // A refused key is reported without echoing it either.
+    let mut rejected = mockito::Server::new();
+    rejected
+        .mock("GET", "/v1/portfolio/tenants")
+        .match_query(mockito::Matcher::Any)
+        .with_status(401)
+        .with_body(
+            r#"{"error":{"code":"unauthorized","message":"Invalid API key","request_id":"r"}}"#,
+        )
+        .create();
+    let output = portfolio_cmd(&env, &rejected)
+        .args(["tenants", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(3), "{output:?}");
+    assert_no_portfolio_secret(&output);
+    listing.expect_at_least(2).assert();
+}
+
+#[test]
+fn all_tenants_skips_what_is_not_readable_by_the_contract_rule() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    let strange = "44444444-4444-4444-8444-444444444444";
+    let off = "55555555-5555-4555-8555-555555555555";
+    mock_portfolio(
+        &mut server,
+        &[
+            tenant(ACME, "acme", true, "in_force"),
+            tenant(BETA, "beta", true, "grace"),
+            // Listed by the server, but a client reading them would get a 403.
+            tenant(OLD, "old", true, "inactive"),
+            tenant(off, "off", false, "in_force"),
+            tenant(strange, "strange", true, "a_status_from_the_future"),
+        ],
+    );
+    let acme = mock_vendors(&mut server, ACME, &["Acme Hosting"]);
+    let beta = mock_vendors(&mut server, BETA, &["Beta Hosting"]);
+    let output = env
+        .api(&server)
+        .args(["--all-tenants", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert!(output.status.success(), "{output:?}");
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(
+        stderr.contains("Skipping 3 inactive client tenants"),
+        "{stderr}"
+    );
+    assert!(
+        stderr.contains("2 vendors across 2 client tenants."),
+        "{stderr}"
+    );
+    acme.assert();
+    beta.assert();
+}
+
+#[test]
+fn an_api_that_does_not_offer_the_portfolio_says_so_with_its_own_exit_code() {
+    let env = Env::new();
+    for status in [404, 405] {
+        let mut server = mockito::Server::new();
+        server
+            .mock("GET", "/v1/portfolio/tenants")
+            .match_query(mockito::Matcher::Any)
+            .with_status(status)
+            .with_body(r#"{"error":{"code":"not_found","message":"Not found","request_id":"r"}}"#)
+            .create();
+        let data = server
+            .mock("GET", "/v1/vendors")
+            .match_query(mockito::Matcher::Any)
+            .expect(0)
+            .create();
+        for args in [
+            &["tenants", "list"][..],
+            &["--tenant", "acme", "vendors", "list"][..],
+            &["--all-tenants", "vendors", "list"][..],
+        ] {
+            let output = env.api(&server).args(args).output().expect("run");
+            assert_eq!(
+                output.status.code(),
+                Some(7),
+                "{status} {args:?}: {output:?}"
+            );
+            let stderr = String::from_utf8_lossy(&output.stderr);
+            assert!(
+                stderr.contains("does not offer portfolio access yet"),
+                "{stderr}"
+            );
+            assert!(output.stdout.is_empty());
+        }
+        data.assert();
+    }
+}
+
+#[test]
+fn a_rate_limit_stops_an_all_tenants_walk_and_names_its_scope() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(&mut server, &two_clients());
+    // A wait too long to sit out: the walk ends, and the second client is never asked.
+    let limited = server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .match_header("x-hs-tenant", ACME)
+        .with_status(429)
+        .with_header("retry-after", "600")
+        .with_body(r#"{"error":{"code":"rate_limited","message":"x","request_id":"r9","details":{"scope":"portfolio_key","limit":100,"window_seconds":60,"retry_after_seconds":600}}}"#)
+        .expect(1)
+        .create();
+    let second = server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .match_header("x-hs-tenant", BETA)
+        .expect(0)
+        .create();
+    let output = portfolio_cmd(&env, &server)
+        .args(["--all-tenants", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(6), "{output:?}");
+    assert!(output.stdout.is_empty());
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(stderr.contains("(limit: portfolio_key)"), "{stderr}");
+    assert!(stderr.contains("Try again in 600 s."), "{stderr}");
+    assert_no_portfolio_secret(&output);
+    limited.assert();
+    second.assert();
+}
+
+#[test]
+fn a_short_rate_limit_is_waited_out_and_the_walk_goes_on() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(&mut server, &two_clients());
+    let limited = server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .match_header("x-hs-tenant", ACME)
+        .with_status(429)
+        .with_header("retry-after", "1")
+        .with_body(r#"{"error":{"code":"rate_limited","message":"x","request_id":"r9","details":{"scope":"portfolio_tenant","limit":60,"window_seconds":60,"retry_after_seconds":1}}}"#)
+        .expect(1)
+        .create();
+    let acme = mock_vendors(&mut server, ACME, &["Acme Hosting"]);
+    let beta = mock_vendors(&mut server, BETA, &["Beta Hosting"]);
+    let output = env
+        .api(&server)
+        .args(["--all-tenants", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert!(output.status.success(), "{output:?}");
+    limited.assert();
+    acme.assert();
+    beta.assert();
+}
+
+#[test]
+fn a_missing_data_scope_stops_the_walk_instead_of_failing_once_per_tenant() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(&mut server, &two_clients());
+    let refused = server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .with_status(403)
+        .with_body(r#"{"error":{"code":"forbidden","message":"x","request_id":"r","details":{"code":"INSUFFICIENT_SCOPE","missing":["supply_risk:read"]}}}"#)
+        .expect(1)
+        .create();
+    let output = env
+        .api(&server)
+        .args(["--all-tenants", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(4), "{output:?}");
+    assert!(String::from_utf8_lossy(&output.stderr).contains("supply_risk:read"));
+    refused.assert();
+}
+
+#[test]
+fn a_deactivated_client_is_a_licence_refusal_not_a_missing_resource() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(&mut server, &two_clients());
+    server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .with_status(403)
+        .with_body(r#"{"error":{"code":"forbidden","message":"x","request_id":"r","details":{"code":"LICENCE_INACTIVE","licence":"tenant_inactive"}}}"#)
+        .create();
+    let output = env
+        .api(&server)
+        .args(["--tenant", "acme", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(8), "{output:?}");
+    assert!(String::from_utf8_lossy(&output.stderr).contains("The tenant is deactivated."));
+}
+
+#[test]
+fn a_tenant_the_server_does_not_know_gets_the_same_answer_as_one_it_hides() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(&mut server, &two_clients());
+    server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .with_status(404)
+        .with_body(r#"{"error":{"code":"not_found","message":"No such tenant in this credential's portfolio.","request_id":"r2","details":{"code":"TENANT_NOT_FOUND"}}}"#)
+        .create();
+    let output = env
+        .api(&server)
+        .args(["--tenant", "acme", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(5), "{output:?}");
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(
+        stderr.contains("No such tenant in this credential's portfolio."),
+        "{stderr}"
+    );
+    assert!(stderr.contains("tenants list"), "{stderr}");
+}
+
+#[test]
+fn the_selector_errors_of_the_contract_are_explained() {
+    let env = Env::new();
+    for (code, expected) in [
+        ("TENANT_SELECTOR_NOT_SUPPORTED", "leave out --tenant"),
+        ("TENANT_HEADER_INVALID", "please report it"),
+    ] {
+        let mut server = mockito::Server::new();
+        server
+            .mock("GET", "/v1/vendors")
+            .match_query(mockito::Matcher::Any)
+            .with_status(400)
+            .with_body(format!(
+                r#"{{"error":{{"code":"invalid_request","message":"x","request_id":"r","details":{{"code":"{code}","parameter":"X-HS-Tenant"}}}}}}"#
+            ))
+            .create();
+        let output = env
+            .api(&server)
+            .args(["vendors", "list"])
+            .output()
+            .expect("run");
+        assert_eq!(output.status.code(), Some(1), "{code}: {output:?}");
+        assert!(
+            String::from_utf8_lossy(&output.stderr).contains(expected),
+            "{code}"
+        );
+    }
+}
+
+#[test]
+fn an_echo_in_the_wrong_form_prints_nothing() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    let mixed = "0B8F2A52-6A0E-4D5C-9D3E-1F2A3B4C5D6E";
+    mock_portfolio(&mut server, &[tenant(mixed, "acme", true, "in_force")]);
+    // The contract's echo is lowercase; capitals are not what an honest server sends.
+    server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .match_header("x-hs-tenant", mixed.to_ascii_lowercase().as_str())
+        .with_header("x-hs-tenant", mixed)
+        .with_body(page(&[vendor("v1", "Acme Hosting")], 1, 1, 1))
+        .create();
+    let output = env
+        .api(&server)
+        .args(["--tenant", "acme", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(1), "{output:?}");
+    assert!(output.stdout.is_empty());
+}

From a96bdb598083017f39a7981c0d8e5dd2b435313c Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Thu, 8 Oct 2026 10:53:44 +0200
Subject: [PATCH 49/57] Harden the portfolio commands after review

- Tenants with a licence status this version does not know are not read,
  are named on stderr, and make an --all-tenants walk exit non-zero;
  "inactive" is said of inactive tenants only.
- A UUID-shaped input that matches one tenant's id and another's slug is
  ambiguous.
- Slugs with characters outside [a-z0-9-] are shown with the start of the
  tenant id in the table.
- The tenant listing is de-duplicated by id, and a changing total is
  reported.
- A 404/405 on the listing that carries a portfolio error code is the
  API's own error, not "portfolio not offered".
- The tenant rate-limit hint applies only when a client tenant is selected.
- Tenant scoping is a property of each operation (tenant_scoped), set by
  the code generator.
- Add tests for the echo on every operation, retried answers, redirects,
  204/304, partial walks, CSV formula guarding and tenant resolution.

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 CHANGELOG.md                                  |   3 +-
 README.md                                     |  14 +-
 crates/hodeishield-api/src/client.rs          |  20 +-
 crates/hodeishield-api/src/generated.rs       |  11 +
 crates/hodeishield-api/src/portfolio.rs       |  60 ++-
 crates/hodeishield-api/tests/api.rs           | 197 ++++++++
 crates/hodeishield-cli/src/commands/mod.rs    |  11 +
 .../hodeishield-cli/src/commands/resources.rs |  62 ++-
 .../hodeishield-cli/src/commands/tenants.rs   |  65 ++-
 crates/hodeishield-cli/src/failure.rs         |  10 +-
 crates/hodeishield-cli/src/filters.rs         |   4 +
 crates/hodeishield-cli/src/output.rs          |  47 +-
 crates/hodeishield-cli/tests/cli.rs           | 467 +++++++++++++++++-
 xtask/src/main.rs                             |   7 +-
 14 files changed, 905 insertions(+), 73 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1c76197..191101a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -33,7 +33,8 @@ commands, `--json` output and exit codes. Each release's notes start with its se
   `tenant_slug` and `tenant_name` to each row in `--json` and `--csv` (a `TENANT` column in the
   table). An unknown client fails with exit code 5, before any data is read. Without these options
   nothing changes. `--all-tenants` skips clients that are inactive, whose licence is not in force, or
-  whose licence status the CLI does not know, asks one client at a time, and stops with exit code 6
+  whose licence status the CLI does not know (the latter are named on standard error and make the
+  command exit non-zero), asks one client at a time, and stops with exit code 6
   (naming the limit) when a rate limit is exhausted. Against an API without portfolio access the
   commands fail with exit code 7. The README has a new "Several tenants (MSSP)" section.
   ([#54](https://github.com/Hodeitek/hodeishield-cli/issues/54),
diff --git a/README.md b/README.md
index d8cc30e..c6ea267 100644
--- a/README.md
+++ b/README.md
@@ -402,9 +402,13 @@ hodeishield --all-tenants alerts list --status open
 - `--all-tenants` works on `list` commands and `compliance controls`. It fetches every page of each
   client (`--per-page` applies, `--page` does not) and adds the tenant to each row: a `TENANT`
   column in the table, and `tenant_id`, `tenant_slug` and `tenant_name` fields in `--json` and
-  `--csv`. Clients that are not readable are skipped, with a note on standard error: those that
-  are inactive, whose licence status is `inactive`, or whose licence status this CLI does not
-  know. A client in its grace period is read. Clients are asked one after the other.
+  `--csv`. Clients that are inactive, or whose licence status is `inactive`, are skipped with a
+  note on standard error. A client in its grace period is read. A client whose licence status this
+  CLI does not know is not read either; it is named on standard error (`licence status … is not
+  known to this version; not read`) and the command exits non-zero, so nothing goes missing
+  silently. Clients are asked one after the other. In the table, a slug with characters other
+  than `a-z`, `0-9` and `-` is followed by the start of the client's id, so look-alike names can be
+  told apart; `--json` and `--csv` carry the full values.
 - The tenant on a row is the one whose own request returned it. The CLI asks the API about one
   client at a time, and refuses an answer that does not confirm that client.
 
@@ -421,7 +425,9 @@ hodeishield --all-tenants vendors list --criticality critical --csv > critical-v
 - With `--all-tenants`, a client that cannot be read on its own account (for example its licence is
   not in force, exit code 8) is reported on standard error and skipped; the command prints the
   others and still exits non-zero, so a script does not mistake a partial result for a complete
-  one.
+  one. This is the only signal of a partial result: check the exit code, and read standard error
+  for which clients were left out. A client named by both an id and a slug of another client
+  (a slug can look like an id) is refused as ambiguous; use the id shown by `tenants list`.
 - Without `--tenant` or `--all-tenants`, a portfolio key is refused by the API, and the CLI tells
   you to choose. A single-tenant key or sign-in behaves exactly as before; asking it for a client
   fails with exit code 4 (it lacks the portfolio scope).
diff --git a/crates/hodeishield-api/src/client.rs b/crates/hodeishield-api/src/client.rs
index c4565a6..2259fb3 100644
--- a/crates/hodeishield-api/src/client.rs
+++ b/crates/hodeishield-api/src/client.rs
@@ -34,6 +34,10 @@ pub struct Operation {
     /// open: the server may accept a value that is not listed, so use this to help and to warn,
     /// never to refuse. Read it through [`Operation::known_values`].
     pub known_values: &'static [(&'static str, &'static [&'static str])],
+    /// Whether a client built for one client tenant selects that tenant on this operation and
+    /// checks the answer's confirmation. True for the data operations, false for the portfolio
+    /// listing, which is never scoped.
+    pub tenant_scoped: bool,
 }
 
 impl Operation {
@@ -417,24 +421,15 @@ impl Client {
         std::thread::sleep(wait);
     }
 
+    /// A GET. The operation decides whether the client's tenant selection applies: scope headers
+    /// are sent and checked only when `operation.tenant_scoped`.
     pub(crate) fn get<T: DeserializeOwned>(
         &self,
         operation: &'static Operation,
         path: String,
         query: Vec<(&'static str, String)>,
     ) -> Result<ApiResponse<T>, Error> {
-        self.get_with(operation, path, query, true)
-    }
-
-    /// Like [`Client::get`]; with `scoped` false the client's scope headers are neither sent nor
-    /// checked, for an operation that sits outside the scope.
-    pub(crate) fn get_with<T: DeserializeOwned>(
-        &self,
-        operation: &'static Operation,
-        path: String,
-        query: Vec<(&'static str, String)>,
-        scoped: bool,
-    ) -> Result<ApiResponse<T>, Error> {
+        let scoped = operation.tenant_scoped;
         let url = self.url(&path, &query);
         let mut rate_limit_retries = 0;
         let mut transient_retries = 0;
@@ -665,6 +660,7 @@ mod tests {
             summary: "List things",
             scopes: &[],
             known_values: &[("severity", &["critical", "high"])],
+            tenant_scoped: true,
         };
         assert_eq!(
             operation.known_values("severity"),
diff --git a/crates/hodeishield-api/src/generated.rs b/crates/hodeishield-api/src/generated.rs
index 9b7ccdd..85e8b98 100644
--- a/crates/hodeishield-api/src/generated.rs
+++ b/crates/hodeishield-api/src/generated.rs
@@ -1103,6 +1103,7 @@ pub mod operations {
         summary: "List third parties",
         scopes: &["supply_risk:read"],
         known_values: &[],
+        tenant_scoped: true,
     };
 
     /// `GET /v1/vendors/{id}`: Fetch one third party.
@@ -1113,6 +1114,7 @@ pub mod operations {
         summary: "Fetch one third party",
         scopes: &["supply_risk:read"],
         known_values: &[],
+        tenant_scoped: true,
     };
 
     /// `GET /v1/alerts`: List supply-chain alerts.
@@ -1123,6 +1125,7 @@ pub mod operations {
         summary: "List supply-chain alerts",
         scopes: &["supply_risk:read"],
         known_values: &[],
+        tenant_scoped: true,
     };
 
     /// `GET /v1/alerts/{id}`: Fetch one alert.
@@ -1133,6 +1136,7 @@ pub mod operations {
         summary: "Fetch one alert",
         scopes: &["supply_risk:read"],
         known_values: &[],
+        tenant_scoped: true,
     };
 
     /// `GET /v1/risks`: List risk-register entries.
@@ -1143,6 +1147,7 @@ pub mod operations {
         summary: "List risk-register entries",
         scopes: &["supply_risk:read"],
         known_values: &[],
+        tenant_scoped: true,
     };
 
     /// `GET /v1/risks/{id}`: Fetch one risk-register entry.
@@ -1153,6 +1158,7 @@ pub mod operations {
         summary: "Fetch one risk-register entry",
         scopes: &["supply_risk:read"],
         known_values: &[],
+        tenant_scoped: true,
     };
 
     /// `GET /v1/compliance/controls`: List control status for a framework.
@@ -1163,6 +1169,7 @@ pub mod operations {
         summary: "List control status for a framework",
         scopes: &["compliance.<framework>:read"],
         known_values: &[],
+        tenant_scoped: true,
     };
 
     /// `GET /v1/compliance/frameworks/{framework}`: Framework posture summary.
@@ -1173,6 +1180,7 @@ pub mod operations {
         summary: "Framework posture summary",
         scopes: &["compliance.<framework>:read"],
         known_values: &[],
+        tenant_scoped: true,
     };
 
     /// `GET /v1/evidence`: List security evidence.
@@ -1183,6 +1191,7 @@ pub mod operations {
         summary: "List security evidence",
         scopes: &["evidence:read"],
         known_values: &[],
+        tenant_scoped: true,
     };
 
     /// `GET /v1/evidence/{id}`: Fetch one evidence item.
@@ -1193,6 +1202,7 @@ pub mod operations {
         summary: "Fetch one evidence item",
         scopes: &["evidence:read"],
         known_values: &[],
+        tenant_scoped: true,
     };
 
     /// `GET /v1/endpoints`: List enrolled endpoint agents.
@@ -1203,6 +1213,7 @@ pub mod operations {
         summary: "List enrolled endpoint agents",
         scopes: &["endpoints:read"],
         known_values: &[],
+        tenant_scoped: true,
     };
 
     /// All operations, in document order.
diff --git a/crates/hodeishield-api/src/portfolio.rs b/crates/hodeishield-api/src/portfolio.rs
index 8be29d7..5c2e800 100644
--- a/crates/hodeishield-api/src/portfolio.rs
+++ b/crates/hodeishield-api/src/portfolio.rs
@@ -55,6 +55,7 @@ pub const LIST_TENANTS: Operation = Operation {
     summary: "List the client tenants of the credential's portfolio",
     scopes: &["portfolio:read"],
     known_values: &[],
+    tenant_scoped: false,
 };
 
 /// A client tenant of the portfolio. Text fields come from the server and are untrusted.
@@ -76,13 +77,39 @@ pub struct Tenant {
     pub licence_status: String,
 }
 
+/// Whether a [`Tenant`] can be expected to be readable.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Readability {
+    /// Active, with a licence in force or in its grace period.
+    Readable,
+    /// Deactivated, or its licence status is `inactive`: the API would answer `403`.
+    Inactive,
+    /// Active, with a licence status this client does not know. The vocabulary is open, so such a
+    /// tenant is neither assumed readable nor assumed inactive.
+    Unknown,
+}
+
 impl Tenant {
+    /// Whether this tenant is readable, inactive, or has a licence status this client does not
+    /// know.
+    #[must_use]
+    pub fn readability(&self) -> Readability {
+        if !self.active {
+            return Readability::Inactive;
+        }
+        match self.licence_status.as_str() {
+            "in_force" | "grace" => Readability::Readable,
+            "inactive" => Readability::Inactive,
+            _ => Readability::Unknown,
+        }
+    }
+
     /// Whether reading this tenant can be expected to work: it is active and its licence is in
     /// force or in its grace period. A licence status this client does not know counts as not
     /// readable, since the vocabulary is open.
     #[must_use]
     pub fn readable(&self) -> bool {
-        self.active && matches!(self.licence_status.as_str(), "in_force" | "grace")
+        self.readability() == Readability::Readable
     }
 }
 
@@ -182,14 +209,15 @@ impl Client {
         &self,
         params: &ListTenantsParams,
     ) -> Result<ApiResponse<ListTenantsResponse>, Error> {
-        self.get_with(
+        self.get(
             &LIST_TENANTS,
             LIST_TENANTS.path.to_owned(),
             params.query_pairs(),
-            false,
         )
         .map_err(|error| match error {
-            Error::Api(api) if matches!(api.status, 404 | 405) => {
+            // A 404/405 that carries one of the portfolio contract's own codes comes from an
+            // API that does offer the portfolio: it stays the API's error.
+            Error::Api(api) if matches!(api.status, 404 | 405) && !is_portfolio_code(&api) => {
                 Error::PortfolioNotOffered { status: api.status }
             }
             other => other,
@@ -197,6 +225,16 @@ impl Client {
     }
 }
 
+/// Whether the error answer names one of the portfolio contract's `details.code` values.
+fn is_portfolio_code(api: &crate::ApiError) -> bool {
+    api.body
+        .as_ref()
+        .and_then(|body| body.details.as_ref())
+        .and_then(|details| details.get("code"))
+        .and_then(serde_json::Value::as_str)
+        .is_some_and(|code| code.starts_with("TENANT_") || code == "LICENCE_INACTIVE")
+}
+
 impl ClientBuilder {
     /// Makes every data call of the built client read the client tenant `id`.
     ///
@@ -301,6 +339,20 @@ mod tests {
         assert!(!tenant(true, "IN_FORCE").readable());
     }
 
+    #[test]
+    fn inactive_and_unknown_tenants_are_told_apart() {
+        use Readability::{Inactive, Readable, Unknown};
+        assert_eq!(tenant(true, "in_force").readability(), Readable);
+        assert_eq!(tenant(true, "grace").readability(), Readable);
+        assert_eq!(tenant(true, "inactive").readability(), Inactive);
+        assert_eq!(tenant(false, "in_force").readability(), Inactive);
+        // Deactivated wins over a status nobody knows.
+        assert_eq!(tenant(false, "suspended_soon").readability(), Inactive);
+        assert_eq!(tenant(true, "suspended_soon").readability(), Unknown);
+        assert_eq!(tenant(true, "").readability(), Unknown);
+        assert_eq!(tenant(true, "IN_FORCE").readability(), Unknown);
+    }
+
     #[test]
     fn the_listing_asks_for_ascending_names_when_told_to() {
         let pairs = ListTenantsParams::alphabetical(Some(2), Some(200)).query_pairs();
diff --git a/crates/hodeishield-api/tests/api.rs b/crates/hodeishield-api/tests/api.rs
index 07d98ad..85141e3 100644
--- a/crates/hodeishield-api/tests/api.rs
+++ b/crates/hodeishield-api/tests/api.rs
@@ -1031,3 +1031,200 @@ fn a_portfolio_key_is_sent_whole_and_never_shown() {
     let shown = format!("{builder:?}");
     assert!(!shown.contains(secret), "{shown}");
 }
+
+// Review follow-ups: the echo is checked on every operation, on every attempt, and only on success.
+
+fn tenant_client_retrying(server: &mockito::Server, tenant: &str) -> Client {
+    Client::builder(
+        server.url().parse().expect("url"),
+        SecretString::from(PORTFOLIO_KEY),
+    )
+    .tenant(tenant)
+    .expect("a UUID")
+    .transient_retries(2, Duration::from_millis(1))
+    .rate_limit_retries(1, Duration::from_secs(5))
+    .build()
+    .expect("client")
+}
+
+#[test]
+fn every_single_item_operation_checks_the_echo() {
+    let mut server = mockito::Server::new();
+    let any = server
+        .mock("GET", mockito::Matcher::Any)
+        .match_header("x-hs-tenant", TENANT_A)
+        .with_header("x-hs-tenant", TENANT_B)
+        .with_body("{}")
+        .expect(5)
+        .create();
+    let c = tenant_client(&server, TENANT_A);
+    fn refused<T>(r: Result<T, Error>) -> bool {
+        matches!(r, Err(Error::TenantMismatch { .. }))
+    }
+    assert!(refused(c.get_vendor("v1")));
+    assert!(refused(c.get_alert("a1")));
+    assert!(refused(c.get_risk("r1")));
+    assert!(refused(c.get_evidence("e1")));
+    assert!(refused(c.get_framework_posture("nis2")));
+    any.assert();
+}
+
+#[test]
+fn an_answer_after_a_retry_is_checked_too() {
+    // A 503 and then a 200 that confirms nothing, or another tenant: refused in both cases.
+    for echo in [None, Some(TENANT_B)] {
+        let mut server = mockito::Server::new();
+        let unavailable = server
+            .mock("GET", "/v1/vendors")
+            .with_status(503)
+            .expect(1)
+            .create();
+        let mut served = server.mock("GET", "/v1/vendors").with_body(EMPTY_PAGE);
+        if let Some(echo) = echo {
+            served = served.with_header("x-hs-tenant", echo);
+        }
+        let served = served.expect(1).create();
+        let err = tenant_client_retrying(&server, TENANT_A)
+            .list_vendors(&ListVendorsParams::default())
+            .expect_err("unconfirmed answer after a retry");
+        assert!(
+            matches!(err, Error::TenantMismatch { .. }),
+            "{echo:?}: {err:?}"
+        );
+        unavailable.assert();
+        served.assert();
+    }
+    // The same after a 429 that is waited out.
+    for echo in [None, Some(TENANT_B)] {
+        let mut server = mockito::Server::new();
+        let limited = server
+            .mock("GET", "/v1/vendors")
+            .with_status(429)
+            .with_header("retry-after", "1")
+            .expect(1)
+            .create();
+        let mut served = server.mock("GET", "/v1/vendors").with_body(EMPTY_PAGE);
+        if let Some(echo) = echo {
+            served = served.with_header("x-hs-tenant", echo);
+        }
+        let served = served.expect(1).create();
+        let err = tenant_client_retrying(&server, TENANT_A)
+            .list_vendors(&ListVendorsParams::default())
+            .expect_err("unconfirmed answer after a wait");
+        assert!(
+            matches!(err, Error::TenantMismatch { .. }),
+            "{echo:?}: {err:?}"
+        );
+        limited.assert();
+        served.assert();
+    }
+    // A confirmed answer after a retry is served.
+    let mut server = mockito::Server::new();
+    server.mock("GET", "/v1/vendors").with_status(503).create();
+    server
+        .mock("GET", "/v1/vendors")
+        .with_header("x-hs-tenant", TENANT_A)
+        .with_body(EMPTY_PAGE)
+        .create();
+    tenant_client_retrying(&server, TENANT_A)
+        .list_vendors(&ListVendorsParams::default())
+        .expect("confirmed after a retry");
+}
+
+#[test]
+fn a_redirect_on_a_scoped_client_is_an_error_and_the_target_gets_nothing() {
+    let mut server = mockito::Server::new();
+    let mut elsewhere = mockito::Server::new();
+    let never = elsewhere
+        .mock("GET", mockito::Matcher::Any)
+        .expect(0)
+        .create();
+    server
+        .mock("GET", "/v1/vendors")
+        .match_header("x-hs-tenant", TENANT_A)
+        .with_status(302)
+        .with_header("location", &format!("{}/steal", elsewhere.url()))
+        .with_header("x-hs-tenant", TENANT_A)
+        .create();
+    let err = tenant_client(&server, TENANT_A)
+        .list_vendors(&ListVendorsParams::default())
+        .expect_err("redirect");
+    assert_eq!(err.api().map(|a| a.status), Some(302), "{err:?}");
+    never.assert();
+}
+
+#[test]
+fn only_a_decodable_success_is_one_even_with_the_right_echo() {
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/vendors")
+        .with_status(204)
+        .with_header("x-hs-tenant", TENANT_A)
+        .create();
+    let err = tenant_client(&server, TENANT_A)
+        .list_vendors(&ListVendorsParams::default())
+        .expect_err("no body");
+    assert!(matches!(err, Error::Decode { .. }), "{err:?}");
+
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/vendors")
+        .with_status(304)
+        .with_header("x-hs-tenant", TENANT_A)
+        .create();
+    let err = tenant_client(&server, TENANT_A)
+        .list_vendors(&ListVendorsParams::default())
+        .expect_err("not modified is not data");
+    assert_eq!(err.api().map(|a| a.status), Some(304), "{err:?}");
+}
+
+#[test]
+fn the_listing_is_unscoped_by_its_operation_and_the_data_operations_are_scoped() {
+    use hodeishield_api::portfolio::LIST_TENANTS;
+    use hodeishield_api::v1::operations;
+    let listing = LIST_TENANTS;
+    assert!(!listing.tenant_scoped);
+    assert!(operations::ALL.len() >= 11);
+    assert!(operations::ALL.iter().all(|op| op.tenant_scoped));
+}
+
+#[test]
+fn a_404_or_405_with_a_portfolio_code_is_the_apis_own_error() {
+    use hodeishield_api::portfolio::ListTenantsParams;
+    for (status, code) in [
+        (404_usize, "TENANT_NOT_FOUND"),
+        (405, "TENANT_SELECTOR_NOT_SUPPORTED"),
+        (404, "TENANT_SOMETHING_NEW"),
+    ] {
+        let mut server = mockito::Server::new();
+        server
+            .mock("GET", "/v1/portfolio/tenants")
+            .with_status(status)
+            .with_body(format!(
+                r#"{{"error":{{"code":"not_found","message":"x","request_id":"r","details":{{"code":"{code}"}}}}}}"#
+            ))
+            .create();
+        let err = client(&server)
+            .list_tenants(&ListTenantsParams::default())
+            .expect_err("API error");
+        assert_eq!(
+            err.api().map(|a| a.status),
+            Some(u16::try_from(status).expect("status")),
+            "{status} {code}: {err:?}"
+        );
+    }
+    // An unrelated code, or none, still means the route is not there.
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/portfolio/tenants")
+        .with_status(404)
+        .with_body(r#"{"error":{"code":"not_found","message":"x","request_id":"r","details":{"code":"SOMETHING_ELSE"}}}"#)
+        .create();
+    let err = client(&server)
+        .list_tenants(&ListTenantsParams::default())
+        .expect_err("no route");
+    assert!(
+        matches!(err, Error::PortfolioNotOffered { status: 404 }),
+        "{err:?}"
+    );
+}
diff --git a/crates/hodeishield-cli/src/commands/mod.rs b/crates/hodeishield-cli/src/commands/mod.rs
index 4339ecd..f10afc3 100644
--- a/crates/hodeishield-cli/src/commands/mod.rs
+++ b/crates/hodeishield-cli/src/commands/mod.rs
@@ -51,6 +51,7 @@ impl Context {
                     &ApiContext {
                         source,
                         framework: None,
+                        tenant_selected: true,
                     },
                 )
             })?;
@@ -84,11 +85,21 @@ impl Context {
                 &ApiContext {
                     source,
                     framework: None,
+                    tenant_selected: tenant.is_some(),
                 },
             )
         })?;
         Ok((client, source))
     }
+
+    /// What a failure message needs to know about a call made with this context's selection.
+    pub fn call<'a>(&self, source: CredentialSource, framework: Option<&'a str>) -> ApiContext<'a> {
+        ApiContext {
+            source,
+            framework,
+            tenant_selected: !matches!(self.selection, Selection::Own),
+        }
+    }
 }
 
 pub fn run(cli: Cli, out: &mut dyn Write) -> Result<()> {
diff --git a/crates/hodeishield-cli/src/commands/resources.rs b/crates/hodeishield-cli/src/commands/resources.rs
index d17459e..6dafccd 100644
--- a/crates/hodeishield-cli/src/commands/resources.rs
+++ b/crates/hodeishield-cli/src/commands/resources.rs
@@ -158,6 +158,16 @@ fn list_across<R, T>(
         let Some(tenant) = &target.tenant else {
             continue;
         };
+        if target.unknown_licence {
+            // The licence vocabulary is open. Not read, but not silently dropped either.
+            eprintln!(
+                "warning: client tenant {}: licence status `{}` is not known to this version; not read",
+                clean(&tenant.slug),
+                clean(&tenant.licence_status)
+            );
+            failures.push(Failure::general("licence status not known"));
+            continue;
+        }
         let walked = collect_pages(
             noun,
             &api,
@@ -204,7 +214,7 @@ fn list_across<R, T>(
             }
             let rows = render(items);
             headers.get_or_insert(rows.headers);
-            groups.push((tenant.slug.clone(), rows.rows));
+            groups.push((tenant.slug.clone(), tenant.id.clone(), rows.rows));
         }
         if let Some(headers) = headers {
             print_table(out, &tenant_table(headers, groups))?;
@@ -315,11 +325,8 @@ fn show<R, T: Serialize>(
     Ok(print_detail(out, &value)?)
 }
 
-fn plain(source: CredentialSource) -> ApiContext<'static> {
-    ApiContext {
-        source,
-        framework: None,
-    }
+fn plain(ctx: &Context, source: CredentialSource) -> ApiContext<'static> {
+    ctx.call(source, None)
 }
 
 pub fn vendors(ctx: &Context, command: VendorsCommand, out: &mut dyn Write) -> Result<()> {
@@ -341,7 +348,7 @@ pub fn vendors(ctx: &Context, command: VendorsCommand, out: &mut dyn Write) -> R
                 out,
                 &args.paging,
                 "vendors",
-                plain(source),
+                plain(ctx, source),
                 &targets,
                 &mut |client, page, per_page| {
                     client.list_vendors(&ListVendorsParams {
@@ -356,7 +363,9 @@ pub fn vendors(ctx: &Context, command: VendorsCommand, out: &mut dyn Write) -> R
         }
         VendorsCommand::Get { id } => {
             let (client, source) = ctx.single(&settings)?;
-            show(ctx, out, plain(source), client.get_vendor(&id), |r| &r.data)
+            show(ctx, out, plain(ctx, source), client.get_vendor(&id), |r| {
+                &r.data
+            })
         }
     }
 }
@@ -403,7 +412,7 @@ pub fn alerts(ctx: &Context, command: AlertsCommand, out: &mut dyn Write) -> Res
                 out,
                 &args.paging,
                 "alerts",
-                plain(source),
+                plain(ctx, source),
                 &targets,
                 &mut |client, page, per_page| {
                     client.list_alerts(&ListAlertsParams {
@@ -418,7 +427,9 @@ pub fn alerts(ctx: &Context, command: AlertsCommand, out: &mut dyn Write) -> Res
         }
         AlertsCommand::Get { id } => {
             let (client, source) = ctx.single(&settings)?;
-            show(ctx, out, plain(source), client.get_alert(&id), |r| &r.data)
+            show(ctx, out, plain(ctx, source), client.get_alert(&id), |r| {
+                &r.data
+            })
         }
     }
 }
@@ -468,7 +479,7 @@ pub fn risks(ctx: &Context, command: RisksCommand, out: &mut dyn Write) -> Resul
                 out,
                 &args.paging,
                 "risks",
-                plain(source),
+                plain(ctx, source),
                 &targets,
                 &mut |client, page, per_page| {
                     client.list_risks(&ListRisksParams {
@@ -483,7 +494,9 @@ pub fn risks(ctx: &Context, command: RisksCommand, out: &mut dyn Write) -> Resul
         }
         RisksCommand::Get { id } => {
             let (client, source) = ctx.single(&settings)?;
-            show(ctx, out, plain(source), client.get_risk(&id), |r| &r.data)
+            show(ctx, out, plain(ctx, source), client.get_risk(&id), |r| {
+                &r.data
+            })
         }
     }
 }
@@ -517,10 +530,7 @@ pub fn compliance(ctx: &Context, command: ComplianceCommand, out: &mut dyn Write
                 &[("status", args.status.as_deref())],
             );
             let (targets, source) = ctx.targets(&settings)?;
-            let api = ApiContext {
-                source,
-                framework: Some(&args.framework),
-            };
+            let api = ctx.call(source, Some(&args.framework));
             let mut base = ListComplianceControlsParams::new(args.framework.clone());
             base.status = args.status;
             base.sort = args.sort;
@@ -545,10 +555,7 @@ pub fn compliance(ctx: &Context, command: ComplianceCommand, out: &mut dyn Write
         }
         ComplianceCommand::Posture { framework } => {
             let (client, source) = ctx.single(&settings)?;
-            let api = ApiContext {
-                source,
-                framework: Some(&framework),
-            };
+            let api = ctx.call(source, Some(&framework));
             let response = client
                 .get_framework_posture(&framework)
                 .map_err(|e| from_api(e, &api))?;
@@ -614,7 +621,7 @@ pub fn evidence(ctx: &Context, command: EvidenceCommand, out: &mut dyn Write) ->
                 out,
                 &args.paging,
                 "evidence items",
-                plain(source),
+                plain(ctx, source),
                 &targets,
                 &mut |client, page, per_page| {
                     client.list_evidence(&ListEvidenceParams {
@@ -629,9 +636,13 @@ pub fn evidence(ctx: &Context, command: EvidenceCommand, out: &mut dyn Write) ->
         }
         EvidenceCommand::Get { id } => {
             let (client, source) = ctx.single(&settings)?;
-            show(ctx, out, plain(source), client.get_evidence(&id), |r| {
-                &r.data
-            })
+            show(
+                ctx,
+                out,
+                plain(ctx, source),
+                client.get_evidence(&id),
+                |r| &r.data,
+            )
         }
     }
 }
@@ -671,7 +682,7 @@ pub fn endpoints(ctx: &Context, command: EndpointsCommand, out: &mut dyn Write)
                 out,
                 &args.paging,
                 "endpoints",
-                plain(source),
+                plain(ctx, source),
                 &targets,
                 &mut |client, page, per_page| {
                     client.list_endpoints(&ListEndpointsParams {
@@ -723,6 +734,7 @@ mod tests {
         let api = ApiContext {
             source: CredentialSource::ApiKey,
             framework: None,
+            tenant_selected: false,
         };
         let total_pages = (total + per_page - 1) / per_page;
         collect_pages(
diff --git a/crates/hodeishield-cli/src/commands/tenants.rs b/crates/hodeishield-cli/src/commands/tenants.rs
index 43205b0..2bd64ba 100644
--- a/crates/hodeishield-cli/src/commands/tenants.rs
+++ b/crates/hodeishield-cli/src/commands/tenants.rs
@@ -13,7 +13,10 @@ use crate::config::Settings;
 use crate::failure::{ApiContext, CredentialSource, Failure, Kind, Result};
 use crate::output::{Rows, clean};
 use hodeishield_api::Client;
-use hodeishield_api::portfolio::{ListTenantsParams, ListTenantsResponse, Tenant, is_uuid};
+use hodeishield_api::portfolio::{
+    ListTenantsParams, ListTenantsResponse, Readability, Tenant, is_uuid,
+};
+use std::collections::HashSet;
 use std::io::Write;
 
 /// Which client tenant the read commands read.
@@ -33,6 +36,9 @@ pub enum Selection {
 pub struct Target {
     pub client: Client,
     pub tenant: Option<Tenant>,
+    /// Set for a tenant of `--all-tenants` whose licence status this version does not know: it is
+    /// not read, and the walk reports it and fails at the end.
+    pub unknown_licence: bool,
 }
 
 impl Context {
@@ -46,6 +52,7 @@ impl Context {
                     vec![Target {
                         client,
                         tenant: None,
+                        unknown_licence: false,
                     }],
                     source,
                 ));
@@ -65,24 +72,34 @@ impl Context {
                 vec![tenant]
             }
             _ => {
-                let (usable, idle): (Vec<_>, Vec<_>) =
-                    portfolio.into_iter().partition(Tenant::readable);
-                if !idle.is_empty() {
+                // Inactive tenants are skipped on purpose. A tenant whose licence status this
+                // version does not know is not read either, but it stays in the list so the walk
+                // can report it and fail: nothing is silently missing.
+                let idle = portfolio
+                    .iter()
+                    .filter(|t| t.readability() == Readability::Inactive)
+                    .count();
+                if idle > 0 {
                     eprintln!(
-                        "Skipping {} inactive client tenants (see `hodeishield tenants list`).",
-                        idle.len()
+                        "Skipping {idle} inactive client tenants (see `hodeishield tenants list`)."
                     );
                 }
-                usable
+                portfolio
+                    .into_iter()
+                    .filter(|t| t.readability() != Readability::Inactive)
+                    .collect()
             }
         };
         let targets = tenants
             .into_iter()
             .map(|tenant| {
                 let (client, _) = self.api(settings, Some(&tenant.id))?;
+                let unknown_licence = matches!(selected, Selection::All)
+                    && tenant.readability() == Readability::Unknown;
                 Ok(Target {
                     client,
                     tenant: Some(tenant),
+                    unknown_licence,
                 })
             })
             .collect::<Result<_>>()?;
@@ -107,13 +124,19 @@ fn list_portfolio(lister: &Client, source: CredentialSource) -> Result<Vec<Tenan
     let api = ApiContext {
         source,
         framework: None,
+        tenant_selected: false,
     };
-    let (_, tenants) = collect_pages(
+    let mut totals: Vec<i64> = Vec::new();
+    let (_, mut tenants) = collect_pages(
         "client tenants",
         &api,
         Some(200),
         100_000,
-        &mut |page, per_page| lister.list_tenants(&ListTenantsParams::alphabetical(page, per_page)),
+        &mut |page, per_page| {
+            let response = lister.list_tenants(&ListTenantsParams::alphabetical(page, per_page))?;
+            totals.push(response.data.pagination.total);
+            Ok(response)
+        },
         |r: ListTenantsResponse| (r.data, r.pagination),
     )
     .map_err(|failure| {
@@ -126,19 +149,32 @@ fn list_portfolio(lister: &Client, source: CredentialSource) -> Result<Vec<Tenan
             failure
         }
     })?;
+    // The portfolio can change while it is walked: a tenant may then appear on two pages, or on
+    // none. Each tenant is read once, and the change is said out loud.
+    if totals.windows(2).any(|pair| pair[0] != pair[1]) {
+        eprintln!(
+            "warning: the number of client tenants changed while they were listed ({}); a tenant \
+             may be missing. Run the command again.",
+            totals
+                .iter()
+                .map(i64::to_string)
+                .collect::<Vec<_>>()
+                .join(", then ")
+        );
+    }
+    let mut seen = HashSet::new();
+    tenants.retain(|tenant| seen.insert(tenant.id.to_ascii_lowercase()));
     Ok(tenants)
 }
 
 /// The tenant the user named, by id or slug. One that is not in the portfolio is reported the way
 /// the API reports it: not found, with no hint about whether it exists elsewhere.
 fn find(portfolio: &[Tenant], wanted: &str) -> Result<Tenant> {
+    // An input shaped like a UUID may be an id, but a slug can have that shape too: if it matches
+    // an id of one tenant and the slug of another, it is ambiguous, never resolved to one of them.
     let by_id = is_uuid(wanted);
     let mut matches = portfolio.iter().filter(|t| {
-        if by_id {
-            t.id.eq_ignore_ascii_case(wanted)
-        } else {
-            t.slug.eq_ignore_ascii_case(wanted)
-        }
+        t.slug.eq_ignore_ascii_case(wanted) || (by_id && t.id.eq_ignore_ascii_case(wanted))
     });
     match (matches.next(), matches.next()) {
         (Some(tenant), None) => Ok(tenant.clone()),
@@ -170,6 +206,7 @@ pub fn run(ctx: &Context, command: TenantsCommand, out: &mut dyn Write) -> Resul
         ApiContext {
             source,
             framework: None,
+            tenant_selected: false,
         },
         &mut |page, per_page| client.list_tenants(&ListTenantsParams::alphabetical(page, per_page)),
         |r| (r.data, r.pagination),
diff --git a/crates/hodeishield-cli/src/failure.rs b/crates/hodeishield-cli/src/failure.rs
index 1af55fa..f074a04 100644
--- a/crates/hodeishield-cli/src/failure.rs
+++ b/crates/hodeishield-cli/src/failure.rs
@@ -195,7 +195,13 @@ pub fn from_api(error: hodeishield_api::Error, context: &ApiContext<'_>) -> Fail
                             "All portfolio keys of your organisation share this limit; another key \
                              or script may be using it.",
                         ),
-                        Some("portfolio_tenant" | "tenant") => Some(
+                        Some("portfolio_tenant") => Some(
+                            "This client tenant's own limit is used up; other client tenants are \
+                             not affected.",
+                        ),
+                        // The plain `tenant` limit is also what a single-tenant key hits: the
+                        // client wording fits only when a client tenant was selected.
+                        Some("tenant") if context.tenant_selected => Some(
                             "This client tenant's own limit is used up; other client tenants are \
                              not affected.",
                         ),
@@ -308,6 +314,8 @@ pub struct ApiContext<'a> {
     pub source: CredentialSource,
     /// The framework of a compliance call, to fill `compliance.<framework>:read`.
     pub framework: Option<&'a str>,
+    /// Whether the call reads a selected client tenant (`--tenant` or `--all-tenants`).
+    pub tenant_selected: bool,
 }
 
 impl ApiContext<'_> {
diff --git a/crates/hodeishield-cli/src/filters.rs b/crates/hodeishield-cli/src/filters.rs
index 0f7805f..ba891a2 100644
--- a/crates/hodeishield-cli/src/filters.rs
+++ b/crates/hodeishield-cli/src/filters.rs
@@ -111,6 +111,7 @@ mod tests {
         summary: "List alerts",
         scopes: &[],
         known_values: &[("severity", &["critical", "high", "medium", "low"])],
+        tenant_scoped: true,
     };
 
     const WITHOUT_LISTS: Operation = Operation {
@@ -154,6 +155,7 @@ mod tests {
 
     const ENGLISH: Operation = Operation {
         known_values: &[("severity", &["critical", "high", "medium", "low", "info"])],
+        tenant_scoped: true,
         ..WITH_LISTS
     };
 
@@ -207,6 +209,7 @@ mod tests {
         // A list without the new name: nothing to point to, so the generic warning stays.
         let other_list = Operation {
             known_values: &[("severity", &["urgent"])],
+            tenant_scoped: true,
             ..WITH_LISTS
         };
         let out = warnings(&other_list, &[("severity", Some("bajo"))]);
@@ -221,6 +224,7 @@ mod tests {
         let other = Operation {
             id: "listRisks",
             known_values: &[("severity", &["high"])],
+            tenant_scoped: true,
             ..WITH_LISTS
         };
         let out = warnings(&other, &[("severity", Some("alto"))]);
diff --git a/crates/hodeishield-cli/src/output.rs b/crates/hodeishield-cli/src/output.rs
index a7149fd..b4e3ee2 100644
--- a/crates/hodeishield-cli/src/output.rs
+++ b/crates/hodeishield-cli/src/output.rs
@@ -140,15 +140,31 @@ impl Rows {
     }
 }
 
-/// Rows of several client tenants in one table, each led by the tenant's slug. The slug is the
-/// server's text, so it is sanitised like every other cell.
-pub fn tenant_table(headers: &[&str], groups: Vec<(String, Vec<Vec<String>>)>) -> Table {
+/// What leads a row of a multi-tenant table. A slug made only of `[a-z0-9-]` is shown as it is. Any
+/// other slug (it may hold look-alike letters, so that two tenants would read the same) is shown
+/// with the start of the tenant's id, which differs. `--json` and `--csv` carry the full values.
+pub fn tenant_label(slug: &str, id: &str) -> String {
+    let plain = !slug.is_empty()
+        && slug
+            .bytes()
+            .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'-');
+    if plain {
+        slug.to_owned()
+    } else {
+        let short: String = id.chars().take(8).collect();
+        format!("{} [{}]", clean(slug), clean(&short))
+    }
+}
+
+/// Rows of several client tenants in one table, each led by the tenant's slug (see
+/// [`tenant_label`]). The text is the server's, so it is sanitised like every other cell.
+pub fn tenant_table(headers: &[&str], groups: Vec<(String, String, Vec<Vec<String>>)>) -> Table {
     let mut all = vec!["TENANT"];
     all.extend_from_slice(headers);
     let rows = groups
         .into_iter()
-        .flat_map(|(slug, rows)| {
-            let label = clean(&slug);
+        .flat_map(|(slug, id, rows)| {
+            let label = tenant_label(&slug, &id);
             rows.into_iter().map(move |mut row| {
                 row.insert(0, label.clone());
                 row
@@ -458,9 +474,14 @@ mod tests {
         let t = tenant_table(
             &["ID"],
             vec![
-                ("acme".to_owned(), vec![vec!["1".into()]]),
+                (
+                    "acme".to_owned(),
+                    "11111111-0000".to_owned(),
+                    vec![vec!["1".into()]],
+                ),
                 (
                     "ev\u{1b}il".to_owned(),
+                    "22222222-0000".to_owned(),
                     vec![vec!["2".into()], vec!["3".into()]],
                 ),
             ],
@@ -477,10 +498,22 @@ mod tests {
             lines[1].starts_with("acme") && lines[1].ends_with('1'),
             "{text}"
         );
-        assert!(lines[2].starts_with("ev\u{fffd}il"), "{text:?}");
+        assert!(lines[2].starts_with("ev\u{fffd}il [22222222]"), "{text:?}");
         assert!(!text.contains('\u{1b}'));
     }
 
+    #[test]
+    fn only_plain_slugs_stand_alone_in_the_tenant_column() {
+        let id = "0b8f2a52-6a0e-4d5c-9d3e-1f2a3b4c5d6e";
+        assert_eq!(tenant_label("acme-2", id), "acme-2");
+        // Cyrillic "а" (U+0430) looks like Latin "a"; the id tells the tenants apart.
+        assert_eq!(tenant_label("\u{430}cme", id), "\u{430}cme [0b8f2a52]");
+        assert_eq!(tenant_label("Acme", id), "Acme [0b8f2a52]");
+        assert_eq!(tenant_label("ac me", id), "ac me [0b8f2a52]");
+        assert_eq!(tenant_label("", id), " [0b8f2a52]");
+        assert_ne!(tenant_label("acme", id), tenant_label("\u{430}cme", id));
+    }
+
     #[test]
     fn tables_have_no_trailing_spaces() {
         let t = table(
diff --git a/crates/hodeishield-cli/tests/cli.rs b/crates/hodeishield-cli/tests/cli.rs
index a06d2c6..9c015cf 100644
--- a/crates/hodeishield-cli/tests/cli.rs
+++ b/crates/hodeishield-cli/tests/cli.rs
@@ -1305,7 +1305,6 @@ fn a_portfolio_key_in_its_published_format_is_sent_as_a_bearer_and_never_shown()
 fn all_tenants_skips_what_is_not_readable_by_the_contract_rule() {
     let env = Env::new();
     let mut server = mockito::Server::new();
-    let strange = "44444444-4444-4444-8444-444444444444";
     let off = "55555555-5555-4555-8555-555555555555";
     mock_portfolio(
         &mut server,
@@ -1315,7 +1314,6 @@ fn all_tenants_skips_what_is_not_readable_by_the_contract_rule() {
             // Listed by the server, but a client reading them would get a 403.
             tenant(OLD, "old", true, "inactive"),
             tenant(off, "off", false, "in_force"),
-            tenant(strange, "strange", true, "a_status_from_the_future"),
         ],
     );
     let acme = mock_vendors(&mut server, ACME, &["Acme Hosting"]);
@@ -1328,7 +1326,7 @@ fn all_tenants_skips_what_is_not_readable_by_the_contract_rule() {
     assert!(output.status.success(), "{output:?}");
     let stderr = String::from_utf8_lossy(&output.stderr);
     assert!(
-        stderr.contains("Skipping 3 inactive client tenants"),
+        stderr.contains("Skipping 2 inactive client tenants"),
         "{stderr}"
     );
     assert!(
@@ -1557,3 +1555,466 @@ fn an_echo_in_the_wrong_form_prints_nothing() {
     assert_eq!(output.status.code(), Some(1), "{output:?}");
     assert!(output.stdout.is_empty());
 }
+
+// Review follow-ups.
+
+const STRANGE: &str = "44444444-4444-4444-8444-444444444444";
+
+/// A tenant with a free-form name and slug (quotes and non-ASCII letters included).
+fn tenant_named(id: &str, slug: &str, name: &str) -> String {
+    serde_json::json!({
+        "id": id,
+        "name": name,
+        "slug": slug,
+        "organization": {"id": "o", "name": "Group"},
+        "internal": false,
+        "active": true,
+        "licence_status": "in_force",
+    })
+    .to_string()
+}
+
+fn never_read(server: &mut mockito::Server) -> mockito::Mock {
+    server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .expect(0)
+        .create()
+}
+
+#[test]
+fn an_unknown_licence_status_is_not_read_is_named_and_fails_the_command() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(
+        &mut server,
+        &[
+            tenant(ACME, "acme", true, "in_force"),
+            tenant(OLD, "old", true, "inactive"),
+            tenant(STRANGE, "strange", true, "a_status_from_the_future"),
+        ],
+    );
+    let acme = mock_vendors(&mut server, ACME, &["Acme Hosting"]);
+    let strange = server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .match_header("x-hs-tenant", STRANGE)
+        .expect(0)
+        .create();
+    let output = env
+        .api(&server)
+        .args(["--all-tenants", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(1), "{output:?}");
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert!(stdout.contains("Acme Hosting"), "{stdout}");
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    // "inactive" is said of the inactive tenant only.
+    assert!(
+        stderr.contains("Skipping 1 inactive client tenants"),
+        "{stderr}"
+    );
+    assert!(
+        stderr.contains(
+            "warning: client tenant strange: licence status `a_status_from_the_future` is not known to this version; not read"
+        ),
+        "{stderr}"
+    );
+    assert!(
+        stderr.contains("Could not read 1 of 2 client tenants"),
+        "{stderr}"
+    );
+    acme.assert();
+    strange.assert();
+}
+
+#[test]
+fn a_walk_where_one_tenant_is_mismatched_prints_nothing() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(&mut server, &two_clients());
+    mock_vendors(&mut server, ACME, &["Acme Hosting"]);
+    // Beta is asked for and answers with Acme's confirmation.
+    server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .match_header("x-hs-tenant", BETA)
+        .with_header("x-hs-tenant", ACME)
+        .with_body(page(&[vendor("v9", "Acme Hosting")], 1, 1, 1))
+        .create();
+    let output = env
+        .api(&server)
+        .args(["--all-tenants", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(1), "{output:?}");
+    assert!(output.stdout.is_empty(), "{output:?}");
+}
+
+#[test]
+fn a_second_page_that_is_not_confirmed_prints_nothing() {
+    let env = Env::new();
+    for args in [
+        &["--tenant", "acme", "vendors", "list", "--all"][..],
+        &["--all-tenants", "vendors", "list", "--all"][..],
+    ] {
+        let mut server = mockito::Server::new();
+        mock_portfolio(&mut server, &[tenant(ACME, "acme", true, "in_force")]);
+        let page_of = |n: i64, name: &str| page(&[vendor(&format!("v{n}"), name)], n, 120, 3);
+        for (n, echo) in [(1_i64, ACME), (2, BETA)] {
+            server
+                .mock("GET", "/v1/vendors")
+                .match_query(mockito::Matcher::UrlEncoded("page".into(), n.to_string()))
+                .match_header("x-hs-tenant", ACME)
+                .with_header("x-hs-tenant", echo)
+                .with_body(page_of(n, &format!("Item {n}")))
+                .create();
+        }
+        let output = env.api(&server).args(args).output().expect("run");
+        assert_eq!(output.status.code(), Some(1), "{args:?}: {output:?}");
+        assert!(output.stdout.is_empty(), "{args:?}: {output:?}");
+    }
+}
+
+#[test]
+fn a_walk_stops_with_nothing_on_stdout_when_a_later_tenant_fails() {
+    let env = Env::new();
+    let scope = r#"{"error":{"code":"forbidden","message":"x","request_id":"r","details":{"code":"INSUFFICIENT_SCOPE","missing":["supply_risk:read"]}}}"#;
+    let unauthorised = r#"{"error":{"code":"unauthorized","message":"x","request_id":"r"}}"#;
+    let down = r#"{"error":{"code":"unavailable","message":"x","request_id":"r"}}"#;
+    for (status, body, expected) in [(401, unauthorised, 3), (503, down, 7), (403, scope, 4)] {
+        let mut server = mockito::Server::new();
+        mock_portfolio(&mut server, &two_clients());
+        mock_vendors(&mut server, ACME, &["Acme Hosting"]);
+        server
+            .mock("GET", "/v1/vendors")
+            .match_query(mockito::Matcher::Any)
+            .match_header("x-hs-tenant", BETA)
+            .with_status(status)
+            // A zero wait keeps the retries of the 503 quick.
+            .with_header("retry-after", "0")
+            .with_body(body)
+            .create();
+        let output = env
+            .api(&server)
+            .args(["--all-tenants", "vendors", "list"])
+            .output()
+            .expect("run");
+        assert_eq!(output.status.code(), Some(expected), "{status}: {output:?}");
+        assert!(output.stdout.is_empty(), "{status}: {output:?}");
+    }
+}
+
+#[test]
+fn tenant_labels_in_csv_cannot_run_as_formulas() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(
+        &mut server,
+        &[
+            tenant_named(ACME, "+cmd", r#"=HYPERLINK("http://example.invalid","x")"#),
+            tenant_named(BETA, "beta", "-2+3"),
+        ],
+    );
+    mock_vendors(&mut server, ACME, &["Acme Hosting"]);
+    mock_vendors(&mut server, BETA, &["Beta Hosting"]);
+    let output = env
+        .api(&server)
+        .args(["--all-tenants", "vendors", "list", "--csv"])
+        .output()
+        .expect("run");
+    assert!(output.status.success(), "{output:?}");
+    let text = String::from_utf8_lossy(&output.stdout);
+    assert!(
+        text.contains(&format!(
+            "{ACME},'+cmd,\"'=HYPERLINK(\"\"http://example.invalid\"\",\"\"x\"\")\","
+        )),
+        "{text}"
+    );
+    assert!(text.contains(&format!("{BETA},beta,'-2+3,")), "{text}");
+    assert!(
+        !text.contains(",+cmd,") && !text.contains(",=HYPERLINK"),
+        "{text}"
+    );
+}
+
+#[test]
+fn slug_resolution_is_case_insensitive_and_never_guesses() {
+    let env = Env::new();
+    // Mixed-case input finds the slug.
+    let mut server = mockito::Server::new();
+    mock_portfolio(&mut server, &two_clients());
+    let acme = mock_vendors(&mut server, ACME, &["Acme Hosting"]);
+    let output = env
+        .api(&server)
+        .args(["--tenant", "AcMe", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert!(output.status.success(), "{output:?}");
+    acme.assert();
+
+    // Two slugs that differ only in case are ambiguous.
+    let mut server = mockito::Server::new();
+    mock_portfolio(
+        &mut server,
+        &[
+            tenant_named(ACME, "Acme", "One"),
+            tenant_named(BETA, "acme", "Two"),
+        ],
+    );
+    let data = never_read(&mut server);
+    let output = env
+        .api(&server)
+        .args(["--tenant", "acme", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(1), "{output:?}");
+    assert!(String::from_utf8_lossy(&output.stderr).contains("More than one client tenant"));
+    assert!(output.stdout.is_empty());
+    data.assert();
+
+    // A slug with a Cyrillic "а" is not matched by the ASCII word.
+    let mut server = mockito::Server::new();
+    mock_portfolio(
+        &mut server,
+        &[tenant_named(ACME, "\u{430}cme", "Look-alike")],
+    );
+    let data = never_read(&mut server);
+    let output = env
+        .api(&server)
+        .args(["--tenant", "acme", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(5), "{output:?}");
+    data.assert();
+
+    // A slug shaped like a UUID that is also another tenant's id is ambiguous.
+    let mut server = mockito::Server::new();
+    mock_portfolio(
+        &mut server,
+        &[
+            tenant_named(ACME, BETA, "Slug is an id"),
+            tenant_named(BETA, "beta", "Has that id"),
+        ],
+    );
+    let data = never_read(&mut server);
+    let output = env
+        .api(&server)
+        .args(["--tenant", BETA, "vendors", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(1), "{output:?}");
+    assert!(String::from_utf8_lossy(&output.stderr).contains("More than one client tenant"));
+    assert!(output.stdout.is_empty());
+    data.assert();
+}
+
+#[test]
+fn an_id_that_is_not_a_uuid_fails_before_any_data_request() {
+    let env = Env::new();
+    for args in [
+        &["--all-tenants", "vendors", "list"][..],
+        &["--tenant", "weird", "vendors", "list"][..],
+    ] {
+        let mut server = mockito::Server::new();
+        mock_portfolio(
+            &mut server,
+            &[
+                tenant(ACME, "acme", true, "in_force"),
+                tenant("not-a-uuid", "weird", true, "in_force"),
+            ],
+        );
+        let data = never_read(&mut server);
+        let output = env.api(&server).args(args).output().expect("run");
+        assert_eq!(output.status.code(), Some(1), "{args:?}: {output:?}");
+        assert!(output.stdout.is_empty());
+        data.assert();
+    }
+}
+
+#[test]
+fn a_portfolio_key_without_a_selection_sends_no_tenant_header() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    let required = server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .match_header("x-hs-tenant", mockito::Matcher::Missing)
+        .with_status(400)
+        .with_body(r#"{"error":{"code":"invalid_request","message":"X-HS-Tenant is required","request_id":"r4","details":{"code":"TENANT_REQUIRED"}}}"#)
+        .expect(1)
+        .create();
+    let output = portfolio_cmd(&env, &server)
+        .args(["vendors", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(1), "{output:?}");
+    assert!(String::from_utf8_lossy(&output.stderr).contains("--all-tenants"));
+    required.assert();
+}
+
+#[test]
+fn look_alike_slugs_are_told_apart_by_id_in_the_table_only() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(
+        &mut server,
+        &[
+            tenant_named(ACME, "acme", "Real"),
+            tenant_named(BETA, "\u{430}cme", "Look-alike"),
+        ],
+    );
+    mock_vendors(&mut server, ACME, &["Real Hosting"]);
+    mock_vendors(&mut server, BETA, &["Fake Hosting"]);
+    let table = env
+        .api(&server)
+        .args(["--all-tenants", "vendors", "list"])
+        .output()
+        .expect("run");
+    let stdout = String::from_utf8_lossy(&table.stdout);
+    assert!(
+        stdout.lines().any(|l| l.starts_with("acme ")) && stdout.contains("\u{430}cme [22222222]"),
+        "{stdout}"
+    );
+    let json = env
+        .api(&server)
+        .args(["--json", "--all-tenants", "vendors", "list"])
+        .output()
+        .expect("run");
+    let items: serde_json::Value = serde_json::from_slice(&json.stdout).expect("json");
+    assert_eq!(items[1]["tenant_slug"], "\u{430}cme");
+}
+
+#[test]
+fn a_tenant_listed_on_two_pages_is_read_once_and_a_changing_total_is_reported() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    for (n, items, total) in [
+        (
+            1_i64,
+            vec![
+                tenant(ACME, "acme", true, "in_force"),
+                tenant(BETA, "beta", true, "grace"),
+            ],
+            120,
+        ),
+        (2, vec![tenant(BETA, "beta", true, "grace")], 121),
+    ] {
+        server
+            .mock("GET", "/v1/portfolio/tenants")
+            .match_query(mockito::Matcher::UrlEncoded("page".into(), n.to_string()))
+            .with_body(page(&items, n, total, 2))
+            .create();
+    }
+    let acme = mock_vendors(&mut server, ACME, &["Acme Hosting"]);
+    let beta = server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .match_header("x-hs-tenant", BETA)
+        .with_header("x-hs-tenant", BETA)
+        .with_body(page(&[vendor("vb", "Beta Hosting")], 1, 1, 1))
+        .expect(1)
+        .create();
+    let output = env
+        .api(&server)
+        .args(["--all-tenants", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert!(output.status.success(), "{output:?}");
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(
+        stderr.contains("changed while they were listed (120, then 121)"),
+        "{stderr}"
+    );
+    assert!(
+        stderr.contains("2 vendors across 2 client tenants."),
+        "{stderr}"
+    );
+    acme.assert();
+    beta.assert();
+}
+
+#[test]
+fn a_404_with_a_portfolio_code_on_the_listing_is_not_taken_for_a_missing_feature() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/portfolio/tenants")
+        .match_query(mockito::Matcher::Any)
+        .with_status(404)
+        .with_body(r#"{"error":{"code":"not_found","message":"No such tenant","request_id":"r","details":{"code":"TENANT_NOT_FOUND"}}}"#)
+        .create();
+    let output = env
+        .api(&server)
+        .args(["--all-tenants", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(5), "{output:?}");
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(
+        !stderr.contains("does not offer portfolio access"),
+        "{stderr}"
+    );
+}
+
+#[test]
+fn the_client_wording_of_a_tenant_rate_limit_needs_a_selected_client() {
+    let env = Env::new();
+    let limit = |scope: &str| {
+        format!(
+            r#"{{"error":{{"code":"rate_limited","message":"x","request_id":"r","details":{{"scope":"{scope}","retry_after_seconds":600}}}}}}"#
+        )
+    };
+    let wording = "own limit is used up";
+    // A single-tenant key, no selection: the previous message, with no client advice.
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .with_status(429)
+        .with_header("retry-after", "600")
+        .with_body(limit("tenant"))
+        .create();
+    let output = env
+        .api(&server)
+        .args(["vendors", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(6), "{output:?}");
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(
+        stderr.contains("(limit: tenant)") && !stderr.contains(wording),
+        "{stderr}"
+    );
+
+    // With a client selected, or for the portfolio's per-client limit, the advice is given.
+    for (scope, args) in [
+        ("tenant", &["--tenant", "acme", "vendors", "list"][..]),
+        (
+            "portfolio_tenant",
+            &["--tenant", "acme", "vendors", "list"][..],
+        ),
+        ("portfolio_tenant", &["vendors", "list"][..]),
+    ] {
+        let mut server = mockito::Server::new();
+        mock_portfolio(&mut server, &two_clients());
+        server
+            .mock("GET", "/v1/vendors")
+            .match_query(mockito::Matcher::Any)
+            .with_status(429)
+            .with_header("retry-after", "600")
+            .with_body(limit(scope))
+            .create();
+        let output = env.api(&server).args(args).output().expect("run");
+        assert_eq!(
+            output.status.code(),
+            Some(6),
+            "{scope} {args:?}: {output:?}"
+        );
+        assert!(
+            String::from_utf8_lossy(&output.stderr).contains(wording),
+            "{scope} {args:?}: {output:?}"
+        );
+    }
+}
diff --git a/xtask/src/main.rs b/xtask/src/main.rs
index 33acc18..a6304ea 100644
--- a/xtask/src/main.rs
+++ b/xtask/src/main.rs
@@ -758,7 +758,7 @@ impl<'a> Generator<'a> {
                 .collect();
             let _ = writeln!(
                 out,
-                "    /// `GET {}`: {}.\n    pub const {}: Operation = Operation {{ id: {:?}, method: \"GET\", path: {:?}, summary: {:?}, scopes: &[{}], known_values: &[{}] }};\n",
+                "    /// `GET {}`: {}.\n    pub const {}: Operation = Operation {{ id: {:?}, method: \"GET\", path: {:?}, summary: {:?}, scopes: &[{}], known_values: &[{}], tenant_scoped: {} }};\n",
                 op.path,
                 op.summary,
                 screaming(&op.id),
@@ -766,7 +766,10 @@ impl<'a> Generator<'a> {
                 op.path,
                 op.summary,
                 scopes.join(", "),
-                known.join(", ")
+                known.join(", "),
+                // A client tenant is selected on the data operations only; anything under the
+                // portfolio path (the tenant listing) is outside the selection.
+                !op.path.starts_with("/v1/portfolio/")
             );
         }
         let all: Vec<String> = self.operations.iter().map(|op| screaming(&op.id)).collect();

From 6a1854fecc92d0495bb031d2f05f1cbf1f0def85 Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Thu, 8 Oct 2026 11:17:29 +0200
Subject: [PATCH 50/57] Align the portfolio wording with the published contract

Name the role that creates a portfolio key (an organisation administrator of an active MSSP
organisation), use the portfolio key name in the changelog, spell the listing column with the
same British spelling as the rest of the text, and show a client organisation in the example.

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 CHANGELOG.md                                   |  5 +++--
 README.md                                      | 10 ++++++----
 crates/hodeishield-cli/src/commands/tenants.rs |  2 +-
 3 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 191101a..3cd6da8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -27,8 +27,9 @@ commands, `--json` output and exit codes. Each release's notes start with its se
   for each stable release: the release's own binary on a distroless base, running as a non-root
   user, tagged with the exact version only. It is signed by digest with Sigstore and carries the
   release's SBOM as a signed attestation. ([#36](https://github.com/Hodeitek/hodeishield-cli/issues/36))
-- Several client tenants with one MSSP credential. `hodeishield tenants list` lists the client
-  tenants the credential may read. The global `--tenant <slug|id>` selects one client for any read
+- Several client tenants with one portfolio key. `hodeishield tenants list` lists the client
+  tenants the key may read. The key is created by an organisation administrator of an active MSSP
+  organisation and goes in `HODEISHIELD_API_KEY`. The global `--tenant <slug|id>` selects one client for any read
   command, and `--all-tenants` reads every client on a `list` command and adds `tenant_id`,
   `tenant_slug` and `tenant_name` to each row in `--json` and `--csv` (a `TENANT` column in the
   table). An unknown client fails with exit code 5, before any data is read. Without these options
diff --git a/README.md b/README.md
index c6ea267..ff4b18e 100644
--- a/README.md
+++ b/README.md
@@ -355,8 +355,10 @@ what it accepts.
 
 ### Several tenants (MSSP)
 
-An MSSP reads all of its client tenants with **one** credential: a portfolio key, created in the
-app by an administrator of an active MSSP organisation, in the MSSP area (API keys). You do not need
+An MSSP reads all of its client tenants with **one** credential: a **portfolio key**, created in the
+app by an organisation administrator of an active MSSP organisation, in the MSSP area (API keys).
+Nobody else can create one: not a tenant administrator, and not a platform operator acting outside
+an MSSP organisation. You do not need
 a profile, a key or a sign-in per client, and you should not set them up that way.
 
 A portfolio key reads only, always expires (90 days by default, 365 at most), and works on the
@@ -378,8 +380,8 @@ key. The same variable takes a tenant API key as before.
 
 ```console
 $ hodeishield tenants list
-SLUG    NAME        ORGANIZATION  TYPE    STATUS  LICENCE   ID
-acme    Acme S.L.   -             client  active  in_force  11111111-1111-4111-8111-111111111111
+SLUG    NAME        ORGANISATION  TYPE    STATUS  LICENCE   ID
+acme    Acme S.L.   Acme Group    client  active  in_force  11111111-1111-4111-8111-111111111111
 beta    Beta Corp   Beta Group    client  active  grace     22222222-2222-4222-8222-222222222222
 ```
 
diff --git a/crates/hodeishield-cli/src/commands/tenants.rs b/crates/hodeishield-cli/src/commands/tenants.rs
index 2bd64ba..81b6172 100644
--- a/crates/hodeishield-cli/src/commands/tenants.rs
+++ b/crates/hodeishield-cli/src/commands/tenants.rs
@@ -226,7 +226,7 @@ fn tenant_rows(items: &[Tenant]) -> Rows {
         &[
             "SLUG",
             "NAME",
-            "ORGANIZATION",
+            "ORGANISATION",
             "TYPE",
             "STATUS",
             "LICENCE",

From 6883074cb7566c9e40651aac3f15c452eb481613 Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Thu, 8 Oct 2026 11:26:56 +0200
Subject: [PATCH 51/57] Document portfolio key rotation and point portfolio
 keys to an organisation administrator

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 README.md                                     |  4 +-
 crates/hodeishield-cli/src/auth/mod.rs        |  5 +++
 crates/hodeishield-cli/src/commands/mod.rs    | 10 +++++
 .../hodeishield-cli/src/commands/resources.rs |  1 +
 .../hodeishield-cli/src/commands/tenants.rs   | 12 +++++-
 crates/hodeishield-cli/src/failure.rs         | 10 ++++-
 crates/hodeishield-cli/tests/cli.rs           | 42 +++++++++++++++++++
 7 files changed, 80 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index ff4b18e..426b659 100644
--- a/README.md
+++ b/README.md
@@ -364,7 +364,9 @@ a profile, a key or a sign-in per client, and you should not set them up that wa
 A portfolio key reads only, always expires (90 days by default, 365 at most), and works on the
 HodeiShield API only. It can be limited when it is created to some of your clients and to source IP
 ranges; a request from another address is refused like an unknown key (exit code 3). Signing in
-with `hodeishield login` does not cover a whole portfolio: use the key.
+with `hodeishield login` does not cover a whole portfolio: use the key. Rotate your portfolio keys
+before they expire, so scripts do not stop working; a new key and its predecessor both work for up
+to 7 days while the old one is in force.
 
 **1. Use the credential as any other key.**
 
diff --git a/crates/hodeishield-cli/src/auth/mod.rs b/crates/hodeishield-cli/src/auth/mod.rs
index b7a7acd..53df31b 100644
--- a/crates/hodeishield-cli/src/auth/mod.rs
+++ b/crates/hodeishield-cli/src/auth/mod.rs
@@ -33,6 +33,11 @@ pub fn api_key_from_env() -> Option<SecretString> {
         .map(SecretString::from)
 }
 
+/// Whether a credential string is a portfolio key (starts with `hsp_`).
+pub fn is_portfolio_key(credential: &SecretString) -> bool {
+    credential.expose_secret().starts_with("hsp_")
+}
+
 /// The credential for an API call: the environment's API key, else the profile's sign-in token,
 /// refreshed if it is about to expire.
 pub fn credential_for_api(
diff --git a/crates/hodeishield-cli/src/commands/mod.rs b/crates/hodeishield-cli/src/commands/mod.rs
index f10afc3..0174e5e 100644
--- a/crates/hodeishield-cli/src/commands/mod.rs
+++ b/crates/hodeishield-cli/src/commands/mod.rs
@@ -13,6 +13,7 @@ use crate::cli::{Cli, Command};
 use crate::config::{Overrides, Settings};
 use crate::failure::{ApiContext, CredentialSource, Result, from_api};
 use hodeishield_api::Client;
+use std::cell::Cell;
 use std::io::Write;
 use std::sync::Arc;
 use tenants::Selection;
@@ -23,6 +24,8 @@ pub struct Context {
     pub verbose: bool,
     pub selection: Selection,
     pub store: Arc<dyn TokenStore + Send + Sync>,
+    /// Cached information about whether the credential is a portfolio key, set on first API call.
+    is_portfolio_key: Cell<Option<bool>>,
 }
 
 impl Context {
@@ -38,6 +41,9 @@ impl Context {
         tenant: Option<&str>,
     ) -> Result<(Client, CredentialSource)> {
         let (credential, source) = auth::credential_for_api(settings, self.store.as_ref())?;
+        let is_portfolio =
+            source == CredentialSource::ApiKey && auth::is_portfolio_key(&credential);
+        self.is_portfolio_key.set(Some(is_portfolio));
         let mut builder =
             Client::builder(settings.api_url.clone(), credential).user_agent(crate::USER_AGENT);
         if source == CredentialSource::OAuth {
@@ -52,6 +58,7 @@ impl Context {
                         source,
                         framework: None,
                         tenant_selected: true,
+                        is_portfolio_key: is_portfolio,
                     },
                 )
             })?;
@@ -86,6 +93,7 @@ impl Context {
                     source,
                     framework: None,
                     tenant_selected: tenant.is_some(),
+                    is_portfolio_key: is_portfolio,
                 },
             )
         })?;
@@ -98,6 +106,7 @@ impl Context {
             source,
             framework,
             tenant_selected: !matches!(self.selection, Selection::Own),
+            is_portfolio_key: self.is_portfolio_key.get().unwrap_or(false),
         }
     }
 }
@@ -116,6 +125,7 @@ pub fn run(cli: Cli, out: &mut dyn Write) -> Result<()> {
             (None, false) => Selection::Own,
         },
         store: Arc::new(auth::store::Keychain),
+        is_portfolio_key: Cell::new(None),
     };
     match cli.command {
         Command::Vendors(command) => resources::vendors(&ctx, command, out),
diff --git a/crates/hodeishield-cli/src/commands/resources.rs b/crates/hodeishield-cli/src/commands/resources.rs
index 6dafccd..11343d8 100644
--- a/crates/hodeishield-cli/src/commands/resources.rs
+++ b/crates/hodeishield-cli/src/commands/resources.rs
@@ -735,6 +735,7 @@ mod tests {
             source: CredentialSource::ApiKey,
             framework: None,
             tenant_selected: false,
+            is_portfolio_key: false,
         };
         let total_pages = (total + per_page - 1) / per_page;
         collect_pages(
diff --git a/crates/hodeishield-cli/src/commands/tenants.rs b/crates/hodeishield-cli/src/commands/tenants.rs
index 81b6172..4a25c08 100644
--- a/crates/hodeishield-cli/src/commands/tenants.rs
+++ b/crates/hodeishield-cli/src/commands/tenants.rs
@@ -60,7 +60,8 @@ impl Context {
             selected => selected,
         };
         let (lister, source) = self.api(settings, None)?;
-        let portfolio = list_portfolio(&lister, source)?;
+        let is_portfolio = self.is_portfolio_key.get().unwrap_or(false);
+        let portfolio = list_portfolio(&lister, source, is_portfolio)?;
         let tenants = match selected {
             Selection::Tenant(wanted) => {
                 let tenant = find(&portfolio, wanted)?;
@@ -120,11 +121,16 @@ impl Context {
 }
 
 /// Every client tenant of the portfolio.
-fn list_portfolio(lister: &Client, source: CredentialSource) -> Result<Vec<Tenant>> {
+fn list_portfolio(
+    lister: &Client,
+    source: CredentialSource,
+    is_portfolio_key: bool,
+) -> Result<Vec<Tenant>> {
     let api = ApiContext {
         source,
         framework: None,
         tenant_selected: false,
+        is_portfolio_key,
     };
     let mut totals: Vec<i64> = Vec::new();
     let (_, mut tenants) = collect_pages(
@@ -198,6 +204,7 @@ pub fn run(ctx: &Context, command: TenantsCommand, out: &mut dyn Write) -> Resul
     let TenantsCommand::List(args) = command;
     let settings = ctx.settings()?;
     let (client, source) = ctx.api(&settings, None)?;
+    let is_portfolio = ctx.is_portfolio_key.get().unwrap_or(false);
     list_one(
         ctx,
         out,
@@ -207,6 +214,7 @@ pub fn run(ctx: &Context, command: TenantsCommand, out: &mut dyn Write) -> Resul
             source,
             framework: None,
             tenant_selected: false,
+            is_portfolio_key: is_portfolio,
         },
         &mut |page, per_page| client.list_tenants(&ListTenantsParams::alphabetical(page, per_page)),
         |r| (r.data, r.pagination),
diff --git a/crates/hodeishield-cli/src/failure.rs b/crates/hodeishield-cli/src/failure.rs
index f074a04..296c88d 100644
--- a/crates/hodeishield-cli/src/failure.rs
+++ b/crates/hodeishield-cli/src/failure.rs
@@ -157,6 +157,12 @@ pub fn from_api(error: hodeishield_api::Error, context: &ApiContext<'_>) -> Fail
                         .iter()
                         .map(|s| context.fill_scope(s))
                         .collect();
+                    let hint = if context.is_portfolio_key {
+                        "Ask an organisation administrator of your MSSP organisation for a key or \
+                         access with that scope."
+                    } else {
+                        "Ask a tenant administrator for a key or access with that scope."
+                    };
                     Failure::new(
                         Kind::Forbidden,
                         format!(
@@ -164,7 +170,7 @@ pub fn from_api(error: hodeishield_api::Error, context: &ApiContext<'_>) -> Fail
                             scopes.join(", ")
                         ),
                     )
-                    .hint("Ask a tenant administrator for a key or access with that scope.")
+                    .hint(hint)
                 }
                 404 => {
                     let failure = Failure::new(
@@ -316,6 +322,8 @@ pub struct ApiContext<'a> {
     pub framework: Option<&'a str>,
     /// Whether the call reads a selected client tenant (`--tenant` or `--all-tenants`).
     pub tenant_selected: bool,
+    /// Whether the credential is a portfolio key (starts with `hsp_`).
+    pub is_portfolio_key: bool,
 }
 
 impl ApiContext<'_> {
diff --git a/crates/hodeishield-cli/tests/cli.rs b/crates/hodeishield-cli/tests/cli.rs
index 9c015cf..d904ec9 100644
--- a/crates/hodeishield-cli/tests/cli.rs
+++ b/crates/hodeishield-cli/tests/cli.rs
@@ -1459,6 +1459,48 @@ fn a_missing_data_scope_stops_the_walk_instead_of_failing_once_per_tenant() {
     refused.assert();
 }
 
+#[test]
+fn a_missing_scope_with_a_portfolio_key_hints_organisation_administrator() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(&mut server, &two_clients());
+    server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .with_status(403)
+        .with_body(r#"{"error":{"code":"forbidden","message":"x","request_id":"r","details":{"code":"INSUFFICIENT_SCOPE","missing":["supply_risk:read"]}}}"#)
+        .create();
+    let output = portfolio_cmd(&env, &server)
+        .args(["--tenant", "acme", "vendors", "list"])
+        .output()
+        .expect("run");
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert_eq!(output.status.code(), Some(4), "{output:?}");
+    assert!(stderr.contains("organisation administrator"), "{stderr}");
+    assert!(!stderr.contains("tenant administrator"), "{stderr}");
+}
+
+#[test]
+fn a_missing_scope_with_a_regular_key_hints_tenant_administrator() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .with_status(403)
+        .with_body(r#"{"error":{"code":"forbidden","message":"x","request_id":"r","details":{"code":"INSUFFICIENT_SCOPE","missing":["supply_risk:read"]}}}"#)
+        .create();
+    let output = env
+        .api(&server)
+        .args(["vendors", "list"])
+        .output()
+        .expect("run");
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert_eq!(output.status.code(), Some(4), "{output:?}");
+    assert!(stderr.contains("tenant administrator"), "{stderr}");
+    assert!(!stderr.contains("organisation administrator"), "{stderr}");
+}
+
 #[test]
 fn a_deactivated_client_is_a_licence_refusal_not_a_missing_resource() {
     let env = Env::new();

From 904810a8a7528842603771e3d874b6afaf7c66f0 Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Sun, 11 Oct 2026 12:48:11 +0200
Subject: [PATCH 52/57] Describe partial results and tenant errors in the
 portfolio entry

The portfolio entry did not say what --all-tenants does when a client
fails while it is read. In the code, a client that fails with a licence
not in force (exit 8) or not found (exit 5) is named on standard error
and skipped, the other clients' data is printed, and the command exits
non-zero with the code of the first failure; any other failure stops the
run before anything is printed. Say so, mention that --tenant also works
on get and compliance posture and prints the "Client tenant" line, and
rewrap the long line.

Add the Changed entry for the errors that involve a client tenant: the
hints for an unknown client, a missing scope on a portfolio key, the
portfolio rate limits and a missing or unsupported tenant selection.

Refs #45, #54

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 CHANGELOG.md | 34 ++++++++++++++++++++++++----------
 1 file changed, 24 insertions(+), 10 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3cd6da8..008c0ce 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -29,16 +29,22 @@ commands, `--json` output and exit codes. Each release's notes start with its se
   release's SBOM as a signed attestation. ([#36](https://github.com/Hodeitek/hodeishield-cli/issues/36))
 - Several client tenants with one portfolio key. `hodeishield tenants list` lists the client
   tenants the key may read. The key is created by an organisation administrator of an active MSSP
-  organisation and goes in `HODEISHIELD_API_KEY`. The global `--tenant <slug|id>` selects one client for any read
-  command, and `--all-tenants` reads every client on a `list` command and adds `tenant_id`,
-  `tenant_slug` and `tenant_name` to each row in `--json` and `--csv` (a `TENANT` column in the
-  table). An unknown client fails with exit code 5, before any data is read. Without these options
-  nothing changes. `--all-tenants` skips clients that are inactive, whose licence is not in force, or
-  whose licence status the CLI does not know (the latter are named on standard error and make the
-  command exit non-zero), asks one client at a time, and stops with exit code 6
-  (naming the limit) when a rate limit is exhausted. Against an API without portfolio access the
-  commands fail with exit code 7. The README has a new "Several tenants (MSSP)" section.
-  ([#54](https://github.com/Hodeitek/hodeishield-cli/issues/54),
+  organisation and goes in `HODEISHIELD_API_KEY`. The global `--tenant <slug|id>` selects one client
+  for any read command, including `get` and `compliance posture`, and prints the line
+  `Client tenant: <slug> (<id>)` on standard error. `--all-tenants` reads every client on a `list` command and adds
+  `tenant_id`, `tenant_slug` and `tenant_name` to each row in `--json` and `--csv` (a `TENANT`
+  column in the table). An unknown client fails with exit code 5, before any data is read. Without
+  these options nothing changes. `--all-tenants` asks one client at a time and skips clients that
+  are inactive or whose licence is not in force, with a note on standard error; the command still
+  exits 0 when only inactive clients are skipped. A client whose licence status the CLI does not
+  know is not read and is named on standard error. A client that fails when it is read because its
+  licence is not in force (exit code 8) or it is not found (exit code 5) is also named and skipped.
+  In both cases the other clients' data is printed and the command then exits non-zero (with the
+  code of the first client that failed, or 1 for an unknown licence status), so a script never takes
+  a partial result for a complete one. Any other failure stops the run before anything is printed,
+  for example exit code 6 (naming the limit) when a rate limit is exhausted. Against an API without
+  portfolio access the commands fail with exit code 7. The README has a new "Several tenants (MSSP)"
+  section. ([#54](https://github.com/Hodeitek/hodeishield-cli/issues/54),
   [#45](https://github.com/Hodeitek/hodeishield-cli/issues/45))
 
 ### Changed (scripting surface)
@@ -77,6 +83,14 @@ commands, `--json` output and exit codes. Each release's notes start with its se
   details, secure use, updating, removal and where the SBOM is published
   ([#127](https://github.com/Hodeitek/hodeishield-cli/issues/127),
   [#128](https://github.com/Hodeitek/hodeishield-cli/issues/128)).
+- Errors that involve a client tenant now say so and what to do. An unknown client tenant (404
+  `TENANT_NOT_FOUND`) points to `hodeishield tenants list`; a portfolio key rejected for a missing
+  scope points to an organisation administrator; a rate limit names whether it is the key's, the
+  organisation's or the client tenant's own, and says whether other clients are affected; a
+  credential that covers several clients without `--tenant` or `--all-tenants` is told to pick one;
+  and `--tenant` with a credential for one tenant only is told to leave it out. Messages and
+  hints go to standard error; exit codes do not change. ([#54](https://github.com/Hodeitek/hodeishield-cli/issues/54),
+  [#45](https://github.com/Hodeitek/hodeishield-cli/issues/45))
 
 ### Fixed
 

From 7b8a577144f3473d67912ca80833f4d577fd89d6 Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Mon, 12 Oct 2026 01:04:33 +0200
Subject: [PATCH 53/57] Say that a portfolio key limited to some tenants lists
 only those

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 README.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 426b659..2ef0394 100644
--- a/README.md
+++ b/README.md
@@ -389,8 +389,9 @@ beta    Beta Corp   Beta Group    client  active  grace     22222222-2222-4222-8
 
 It takes `--json`, `--csv`, `--page` and `--all` like any list, sorted by name. It includes your
 own organisation's tenants (`TYPE` `own` for the internal one) and clients that are inactive or have
-no licence in force, which the `STATUS` and `LICENCE` columns tell apart. The list is read from the API
-each time: a client added to or removed from your portfolio shows up on the next command.
+no licence in force, which the `STATUS` and `LICENCE` columns tell apart. A key that was limited to
+some tenants when it was created lists and reads only those. The list is read from the API each
+time: a client added to or removed from your portfolio shows up on the next command.
 
 **3. Select the client a read command reads.** The selection goes with the command and is never
 remembered, so a later command cannot read another client by surprise.

From 5939e04557f1b5cacea9f2038537ae116fbc2c9f Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Mon, 12 Oct 2026 03:25:44 +0200
Subject: [PATCH 54/57] Say that a client tenant's own rate limits can be lower

The portfolio key and organisation limits are not the only ones: once a client tenant is selected, that tenant's own limits apply and can be tighter.

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 README.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 2ef0394..695f98f 100644
--- a/README.md
+++ b/README.md
@@ -438,11 +438,11 @@ hodeishield --all-tenants vendors list --criticality critical --csv > critical-v
   fails with exit code 4 (it lacks the portfolio scope).
 - A client you named that is deactivated, or whose licence is not in force, fails with exit code 8.
 - A portfolio key is limited to 100 requests per minute, and all the portfolio keys of your
-  organisation together to 600 (the API may change these numbers). The CLI waits out a short
-  `Retry-After` and retries; if the wait is longer, or the limit is still exhausted, the command
-  stops with exit code 6 and says which limit it hit (`portfolio_key`, `portfolio_org`,
-  `portfolio_tenant` or `tenant`), instead of asking the next client. Use `--per-page 200` and
-  narrow with filters to need fewer requests.
+  organisation together to 600 (the API may change these numbers); a client tenant's own limits
+  can be lower. The CLI waits out a short `Retry-After` and retries; if the wait is longer, or the
+  limit is still exhausted, the command stops with exit code 6 and says which limit it hit
+  (`portfolio_key`, `portfolio_org`, `portfolio_tenant` or `tenant`), instead of asking the next
+  client. Use `--per-page 200` and narrow with filters to need fewer requests.
 - Against an API that does not offer portfolio access yet, `tenants list`, `--tenant` and
   `--all-tenants` fail with `This API does not offer portfolio access yet.` and exit code 7. Nothing
   else changes.

From 9e4a82147e9a20d44c04e204f15b67c391c6e568 Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Mon, 12 Oct 2026 03:48:59 +0200
Subject: [PATCH 55/57] Follow version 2026-10-16 of the API document

Vendor the published /v1 document (2026-10-16) and regenerate the client.

- The generator accepts the X-HS-Tenant header parameter: it is not part
  of the generated function, and it marks the operation as tenant-scoped
  (replacing the path rule). Any other header parameter is still an error.
- x-hs-known-values, x-hs-deprecated-values and
  x-hs-deprecated-values-sunset are read from the parameter's schema,
  where the document puts them, and then from the parameter itself.
  Deprecated values and their sunset are emitted with each operation.
- An object declared open (additionalProperties: true) stays a JSON map,
  so error details keep every key.
- The tenant listing is now a generated operation; the portfolio module
  uses it, and sign-in does not ask for its scope.
- The alert severity filter warns about a deprecated value using the
  document's list and sunset. The four replacements stay in a small table,
  checked against the document's deprecated values by a test, until the
  sunset on 2027-01-14.

Refs #53

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 CHANGELOG.md                             |   6 +
 crates/hodeishield-api/src/client.rs     |  32 +++
 crates/hodeishield-api/src/generated.rs  | 170 ++++++++++++-
 crates/hodeishield-api/src/lib.rs        |   4 +-
 crates/hodeishield-api/src/portfolio.rs  |  30 +--
 crates/hodeishield-api/tests/api.rs      |  14 +-
 crates/hodeishield-cli/src/auth/oauth.rs |   6 +-
 crates/hodeishield-cli/src/filters.rs    | 202 +++++++++++-----
 crates/hodeishield-cli/tests/cli.rs      |  51 +++-
 openapi/README.md                        |   6 +-
 openapi/v1.json                          |   2 +-
 xtask/src/main.rs                        | 290 +++++++++++++++++++++--
 12 files changed, 688 insertions(+), 125 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 008c0ce..2847695 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -83,6 +83,12 @@ commands, `--json` output and exit codes. Each release's notes start with its se
   details, secure use, updating, removal and where the SBOM is published
   ([#127](https://github.com/Hodeitek/hodeishield-cli/issues/127),
   [#128](https://github.com/Hodeitek/hodeishield-cli/issues/128)).
+- The alerts `--severity` filter now shows in `--help` the values the API lists (`critical`, `high`,
+  `medium`, `low`, `info`), and warns on standard error about a value the API does not list or has
+  deprecated. For the deprecated values (`critico`, `alto`, `medio`, `bajo`, accepted until
+  2027-01-14) the warning names the value to use instead. The value is still sent as typed, and exit
+  codes do not change. The CLI now follows version 2026-10-16 of the API document.
+  ([#53](https://github.com/Hodeitek/hodeishield-cli/issues/53))
 - Errors that involve a client tenant now say so and what to do. An unknown client tenant (404
   `TENANT_NOT_FOUND`) points to `hodeishield tenants list`; a portfolio key rejected for a missing
   scope points to an organisation administrator; a rate limit names whether it is the key's, the
diff --git a/crates/hodeishield-api/src/client.rs b/crates/hodeishield-api/src/client.rs
index 2259fb3..6f4612e 100644
--- a/crates/hodeishield-api/src/client.rs
+++ b/crates/hodeishield-api/src/client.rs
@@ -34,6 +34,10 @@ pub struct Operation {
     /// open: the server may accept a value that is not listed, so use this to help and to warn,
     /// never to refuse. Read it through [`Operation::known_values`].
     pub known_values: &'static [(&'static str, &'static [&'static str])],
+    /// The values the document marks as deprecated for a query parameter
+    /// (`x-hs-deprecated-values`), only for the parameters that have some. The server still
+    /// accepts them until their sunset date. Read it through [`Operation::deprecated_values`].
+    pub deprecated_values: &'static [DeprecatedValues],
     /// Whether a client built for one client tenant selects that tenant on this operation and
     /// checks the answer's confirmation. True for the data operations, false for the portfolio
     /// listing, which is never scoped.
@@ -50,6 +54,25 @@ impl Operation {
             .find(|(name, _)| *name == param)
             .map(|(_, values)| *values)
     }
+
+    /// The deprecated values the document lists for the query parameter `param`, or `None` when
+    /// it lists none.
+    #[must_use]
+    pub fn deprecated_values(&self, param: &str) -> Option<&'static DeprecatedValues> {
+        self.deprecated_values.iter().find(|d| d.param == param)
+    }
+}
+
+/// Values of a query parameter that the API still accepts but has deprecated, as the document
+/// lists them (`x-hs-deprecated-values` and `x-hs-deprecated-values-sunset`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct DeprecatedValues {
+    /// The query parameter, e.g. `severity`.
+    pub param: &'static str,
+    /// The deprecated values, in document order.
+    pub values: &'static [&'static str],
+    /// The last day the API accepts them (`YYYY-MM-DD`), when the document gives one.
+    pub sunset: Option<&'static str>,
 }
 
 /// A successful answer: the typed body, the body exactly as received (for `--json`, so fields this
@@ -660,6 +683,11 @@ mod tests {
             summary: "List things",
             scopes: &[],
             known_values: &[("severity", &["critical", "high"])],
+            deprecated_values: &[DeprecatedValues {
+                param: "severity",
+                values: &["alto"],
+                sunset: Some("2027-01-14"),
+            }],
             tenant_scoped: true,
         };
         assert_eq!(
@@ -667,6 +695,10 @@ mod tests {
             Some(&["critical", "high"][..])
         );
         assert_eq!(operation.known_values("page"), None);
+        let deprecated = operation.deprecated_values("severity").expect("listed");
+        assert_eq!(deprecated.values, &["alto"]);
+        assert_eq!(deprecated.sunset, Some("2027-01-14"));
+        assert_eq!(operation.deprecated_values("page"), None);
     }
 
     fn client(base: &str) -> Client {
diff --git a/crates/hodeishield-api/src/generated.rs b/crates/hodeishield-api/src/generated.rs
index 85e8b98..db4a5c5 100644
--- a/crates/hodeishield-api/src/generated.rs
+++ b/crates/hodeishield-api/src/generated.rs
@@ -13,7 +13,7 @@
 use serde::{Deserialize, Serialize};
 
 /// `info.version` of the OpenAPI document this client was generated from.
-pub const OPENAPI_VERSION: &str = "2026-09-28";
+pub const OPENAPI_VERSION: &str = "2026-10-16";
 
 /// The server the OpenAPI document declares.
 pub const DEFAULT_SERVER: &str = "https://api.hodeishield.com";
@@ -28,7 +28,7 @@ pub struct ErrorBody {
     pub message: String,
     /// Also the `X-Request-Id` response header.
     pub request_id: String,
-    /// Diagnostic. Not part of the frozen contract.
+    /// Diagnostic, except `code` and the keys the operation’s error descriptions name, which are contract.
     #[serde(default)]
     pub details: Option<serde_json::Map<String, serde_json::Value>>,
 }
@@ -121,7 +121,7 @@ pub struct Alert {
     pub vendor_id: String,
     /// Alert family, e.g. `breach`, `cve`, `rating_drop`.
     pub r#type: String,
-    /// critical | high | medium | low, when classified.
+    /// critical | high | medium | low | info, when classified. Open vocabulary: a new value is a compatible change.
     #[serde(default)]
     pub severity: Option<String>,
     pub title: String,
@@ -168,9 +168,9 @@ pub struct Risk {
     pub title: String,
     #[serde(default)]
     pub description: Option<String>,
-    /// Risk domain, as configured by the tenant.
+    /// Risk domain: vendor | cyber | data | operational | compliance | concentration | strategic | legal | financial | reputational.
     pub domain: String,
-    /// identified | assessed | treated | accepted | closed | …
+    /// Risk lifecycle status: identified | assessed | treatment_planned | treatment_implemented | closed.
     pub status: String,
     /// mitigate | accept | transfer | avoid.
     #[serde(default)]
@@ -337,6 +337,38 @@ pub struct ListEndpointsResponse {
     pub pagination: Pagination,
 }
 
+/// The organisation the tenant belongs to: the MSSP itself for the tenants it holds directly (including its internal one), or the client organisation.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct Organization {
+    pub id: String,
+    pub name: String,
+}
+
+/// A client tenant an MSSP portfolio key may select.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct PortfolioTenant {
+    /// Stable identifier (lowercase). The ONLY value `X-HS-Tenant` accepts.
+    pub id: String,
+    /// Display name. Untrusted text.
+    pub name: String,
+    /// Short name, unique across the platform. A client may resolve a slug to an `id` from this list; the server never accepts a slug as a selector.
+    pub slug: String,
+    /// The organisation the tenant belongs to: the MSSP itself for the tenants it holds directly (including its internal one), or the client organisation.
+    pub organization: Organization,
+    /// True only for the MSSP’s own internal tenant.
+    pub internal: bool,
+    /// Whether the tenant is enabled. A deactivated tenant is listed but cannot be read.
+    pub active: bool,
+    /// Open vocabulary: `in_force` (licence in force), `grace` (grace period: reads are served), `inactive` (none, suspended, revoked or expired: data operations answer 403 `LICENCE_INACTIVE`). Treat an unknown value as "may not be readable". A tenant is readable when `active` is true and `licence_status` is not `inactive`.
+    pub licence_status: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct ListPortfolioTenantsResponse {
+    pub data: Vec<PortfolioTenant>,
+    pub pagination: Pagination,
+}
+
 /// Accepted values of a query parameter.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum VendorSort {
@@ -776,6 +808,47 @@ impl std::str::FromStr for EndpointStatus {
     }
 }
 
+/// Accepted values of a query parameter.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum PortfolioTenantSort {
+    /// `name`
+    Name,
+    /// `slug`
+    Slug,
+}
+
+impl PortfolioTenantSort {
+    /// Every accepted value, as sent on the wire.
+    pub const VALUES: &'static [&'static str] = &["name", "slug"];
+
+    /// The value as sent on the wire.
+    #[must_use]
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Name => "name",
+            Self::Slug => "slug",
+        }
+    }
+}
+
+impl std::fmt::Display for PortfolioTenantSort {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
+impl std::str::FromStr for PortfolioTenantSort {
+    type Err = crate::ParseEnumError;
+
+    fn from_str(value: &str) -> Result<Self, Self::Err> {
+        match value {
+            "name" => Ok(Self::Name),
+            "slug" => Ok(Self::Slug),
+            _ => Err(crate::ParseEnumError::new(value, Self::VALUES)),
+        }
+    }
+}
+
 /// Query parameters of `listVendors`.
 #[derive(Debug, Clone, Default, PartialEq)]
 pub struct ListVendorsParams {
@@ -843,7 +916,7 @@ pub struct ListAlertsParams {
     pub order: Option<Order>,
     /// Filter by the derived status.
     pub status: Option<AlertStatus>,
-    /// Exact severity match.
+    /// Exact severity match, in the vocabulary the response uses (critical | high | medium | low | info). The legacy Spanish values (critico, alto, medio, bajo, info) are still accepted and mean the same; they are documented as accepted until 2027-01-14, so move to the English ones.
     pub severity: Option<String>,
     /// Only alerts about this vendor.
     pub vendor_id: Option<String>,
@@ -1091,6 +1164,40 @@ impl ListEndpointsParams {
     }
 }
 
+/// Query parameters of `listPortfolioTenants`.
+#[derive(Debug, Clone, Default, PartialEq)]
+pub struct ListPortfolioTenantsParams {
+    /// 1-based page number. Defaults to 1.
+    pub page: Option<i64>,
+    /// Items per page, 1..200. Defaults to 50.
+    pub per_page: Option<i64>,
+    /// Field to order by. One of: name, slug.
+    pub sort: Option<PortfolioTenantSort>,
+    /// Sort direction. Defaults to desc.
+    pub order: Option<Order>,
+}
+
+impl ListPortfolioTenantsParams {
+    /// The query string, in document order, without the parameters that are unset.
+    #[must_use]
+    pub fn query_pairs(&self) -> Vec<(&'static str, String)> {
+        let mut pairs = Vec::new();
+        if let Some(value) = &self.page {
+            pairs.push(("page", value.to_string()));
+        }
+        if let Some(value) = &self.per_page {
+            pairs.push(("per_page", value.to_string()));
+        }
+        if let Some(value) = &self.sort {
+            pairs.push(("sort", value.as_str().to_owned()));
+        }
+        if let Some(value) = &self.order {
+            pairs.push(("order", value.as_str().to_owned()));
+        }
+        pairs
+    }
+}
+
 /// Every `/v1` operation, as the OpenAPI document describes it.
 pub mod operations {
     use crate::Operation;
@@ -1103,6 +1210,7 @@ pub mod operations {
         summary: "List third parties",
         scopes: &["supply_risk:read"],
         known_values: &[],
+        deprecated_values: &[],
         tenant_scoped: true,
     };
 
@@ -1114,6 +1222,7 @@ pub mod operations {
         summary: "Fetch one third party",
         scopes: &["supply_risk:read"],
         known_values: &[],
+        deprecated_values: &[],
         tenant_scoped: true,
     };
 
@@ -1124,7 +1233,12 @@ pub mod operations {
         path: "/v1/alerts",
         summary: "List supply-chain alerts",
         scopes: &["supply_risk:read"],
-        known_values: &[],
+        known_values: &[("severity", &["critical", "high", "medium", "low", "info"])],
+        deprecated_values: &[crate::DeprecatedValues {
+            param: "severity",
+            values: &["critico", "alto", "medio", "bajo"],
+            sunset: Some("2027-01-14"),
+        }],
         tenant_scoped: true,
     };
 
@@ -1136,6 +1250,7 @@ pub mod operations {
         summary: "Fetch one alert",
         scopes: &["supply_risk:read"],
         known_values: &[],
+        deprecated_values: &[],
         tenant_scoped: true,
     };
 
@@ -1147,6 +1262,7 @@ pub mod operations {
         summary: "List risk-register entries",
         scopes: &["supply_risk:read"],
         known_values: &[],
+        deprecated_values: &[],
         tenant_scoped: true,
     };
 
@@ -1158,6 +1274,7 @@ pub mod operations {
         summary: "Fetch one risk-register entry",
         scopes: &["supply_risk:read"],
         known_values: &[],
+        deprecated_values: &[],
         tenant_scoped: true,
     };
 
@@ -1169,6 +1286,7 @@ pub mod operations {
         summary: "List control status for a framework",
         scopes: &["compliance.<framework>:read"],
         known_values: &[],
+        deprecated_values: &[],
         tenant_scoped: true,
     };
 
@@ -1180,6 +1298,7 @@ pub mod operations {
         summary: "Framework posture summary",
         scopes: &["compliance.<framework>:read"],
         known_values: &[],
+        deprecated_values: &[],
         tenant_scoped: true,
     };
 
@@ -1191,6 +1310,7 @@ pub mod operations {
         summary: "List security evidence",
         scopes: &["evidence:read"],
         known_values: &[],
+        deprecated_values: &[],
         tenant_scoped: true,
     };
 
@@ -1202,6 +1322,7 @@ pub mod operations {
         summary: "Fetch one evidence item",
         scopes: &["evidence:read"],
         known_values: &[],
+        deprecated_values: &[],
         tenant_scoped: true,
     };
 
@@ -1213,9 +1334,22 @@ pub mod operations {
         summary: "List enrolled endpoint agents",
         scopes: &["endpoints:read"],
         known_values: &[],
+        deprecated_values: &[],
         tenant_scoped: true,
     };
 
+    /// `GET /v1/portfolio/tenants`: List the client tenants of an MSSP portfolio.
+    pub const LIST_PORTFOLIO_TENANTS: Operation = Operation {
+        id: "listPortfolioTenants",
+        method: "GET",
+        path: "/v1/portfolio/tenants",
+        summary: "List the client tenants of an MSSP portfolio",
+        scopes: &["portfolio:read"],
+        known_values: &[],
+        deprecated_values: &[],
+        tenant_scoped: false,
+    };
+
     /// All operations, in document order.
     pub const ALL: &[Operation] = &[
         LIST_VENDORS,
@@ -1229,6 +1363,7 @@ pub mod operations {
         LIST_EVIDENCE,
         GET_EVIDENCE,
         LIST_ENDPOINTS,
+        LIST_PORTFOLIO_TENANTS,
     ];
 }
 
@@ -1463,4 +1598,25 @@ impl crate::Client {
             params.query_pairs(),
         )
     }
+
+    /// List the client tenants of an MSSP portfolio.
+    ///
+    /// Every tenant the presented PORTFOLIO key may select with `X-HS-Tenant`: the MSSP’s own tenants (its internal one included) and every tenant of its active client organisations, active or not, licensed or not, narrowed to the key’s client subset when it has one. Membership is evaluated live on every request. Only a portfolio key (`hsp_…`) can call this operation; this operation never takes `X-HS-Tenant`.
+    ///
+    /// Required scope: `portfolio:read`. Published in `/v1` since 2026-10-16.
+    ///
+    /// # Errors
+    ///
+    /// [`crate::Error`] when the request cannot be sent, the API answers with an error, or the
+    /// body does not match the document.
+    pub fn list_portfolio_tenants(
+        &self,
+        params: &ListPortfolioTenantsParams,
+    ) -> Result<crate::ApiResponse<ListPortfolioTenantsResponse>, crate::Error> {
+        self.get(
+            &operations::LIST_PORTFOLIO_TENANTS,
+            "/v1/portfolio/tenants".to_owned(),
+            params.query_pairs(),
+        )
+    }
 }
diff --git a/crates/hodeishield-api/src/lib.rs b/crates/hodeishield-api/src/lib.rs
index 8c46e27..78b513e 100644
--- a/crates/hodeishield-api/src/lib.rs
+++ b/crates/hodeishield-api/src/lib.rs
@@ -30,7 +30,7 @@ pub mod portfolio;
 pub mod v1;
 
 pub use client::{
-    ApiResponse, Client, ClientBuilder, MAX_RESPONSE_BYTES, Operation, RateLimit, RequestEvent,
-    ResponseMeta, RetryEvent, encode_path_segment, is_loopback_host, read_body,
+    ApiResponse, Client, ClientBuilder, DeprecatedValues, MAX_RESPONSE_BYTES, Operation, RateLimit,
+    RequestEvent, ResponseMeta, RetryEvent, encode_path_segment, is_loopback_host, read_body,
 };
 pub use error::{ApiError, ApiErrorBody, Error, ParseEnumError};
diff --git a/crates/hodeishield-api/src/portfolio.rs b/crates/hodeishield-api/src/portfolio.rs
index 5c2e800..1e104be 100644
--- a/crates/hodeishield-api/src/portfolio.rs
+++ b/crates/hodeishield-api/src/portfolio.rs
@@ -22,12 +22,12 @@
 //!
 //! # Relation to the generated client
 //!
-//! The vendored `openapi/v1.json` does not describe these operations yet, so this file is written
-//! by hand. When the vendored document is synced to the contract version above, the listing
-//! operation, [`Tenant`] and the paging types come from `cargo xtask codegen` (which first has to
-//! learn header parameters and the new security scheme), and this file shrinks to what is not an
-//! operation: [`ClientBuilder::tenant`] and its confirmation check, which the generated code does
-//! not provide.
+//! The listing operation is described by the vendored `openapi/v1.json`: its method, path, scope
+//! and the fact that it is never tenant-scoped come from the generated
+//! [`LIST_PORTFOLIO_TENANTS`](crate::v1::operations::LIST_PORTFOLIO_TENANTS). This file adds what
+//! the generated code does not provide: [`ClientBuilder::tenant`] and its confirmation check, the
+//! readability of a [`Tenant`], and the mapping of a missing route to
+//! [`Error::PortfolioNotOffered`].
 //!
 //! # Interface
 //!
@@ -36,8 +36,9 @@
 //!   client then refuses any successful answer that does not name the same tenant, so data of one
 //!   client is never returned as if it were another's.
 
-use crate::client::{Operation, Scope};
+use crate::client::Scope;
 use crate::error::Error;
+use crate::v1::operations::LIST_PORTFOLIO_TENANTS;
 use crate::v1::{Order, Pagination};
 use crate::{ApiResponse, Client, ClientBuilder};
 use reqwest::header::{HeaderMap, HeaderName, HeaderValue};
@@ -47,17 +48,6 @@ use std::sync::Arc;
 /// Request and response header that selects, and confirms, the client tenant.
 const TENANT_HEADER: HeaderName = HeaderName::from_static("x-hs-tenant");
 
-/// `GET /v1/portfolio/tenants`: List the client tenants of the credential's portfolio.
-pub const LIST_TENANTS: Operation = Operation {
-    id: "listPortfolioTenants",
-    method: "GET",
-    path: "/v1/portfolio/tenants",
-    summary: "List the client tenants of the credential's portfolio",
-    scopes: &["portfolio:read"],
-    known_values: &[],
-    tenant_scoped: false,
-};
-
 /// A client tenant of the portfolio. Text fields come from the server and are untrusted.
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 pub struct Tenant {
@@ -210,8 +200,8 @@ impl Client {
         params: &ListTenantsParams,
     ) -> Result<ApiResponse<ListTenantsResponse>, Error> {
         self.get(
-            &LIST_TENANTS,
-            LIST_TENANTS.path.to_owned(),
+            &LIST_PORTFOLIO_TENANTS,
+            LIST_PORTFOLIO_TENANTS.path.to_owned(),
             params.query_pairs(),
         )
         .map_err(|error| match error {
diff --git a/crates/hodeishield-api/tests/api.rs b/crates/hodeishield-api/tests/api.rs
index 85141e3..261797c 100644
--- a/crates/hodeishield-api/tests/api.rs
+++ b/crates/hodeishield-api/tests/api.rs
@@ -1180,12 +1180,18 @@ fn only_a_decodable_success_is_one_even_with_the_right_echo() {
 
 #[test]
 fn the_listing_is_unscoped_by_its_operation_and_the_data_operations_are_scoped() {
-    use hodeishield_api::portfolio::LIST_TENANTS;
     use hodeishield_api::v1::operations;
-    let listing = LIST_TENANTS;
+    let listing = operations::LIST_PORTFOLIO_TENANTS;
+    assert_eq!(listing.method, "GET");
+    assert_eq!(listing.path, "/v1/portfolio/tenants");
+    assert_eq!(listing.scopes, ["portfolio:read"]);
     assert!(!listing.tenant_scoped);
-    assert!(operations::ALL.len() >= 11);
-    assert!(operations::ALL.iter().all(|op| op.tenant_scoped));
+    let data: Vec<_> = operations::ALL
+        .iter()
+        .filter(|op| op.id != listing.id)
+        .collect();
+    assert!(data.len() >= 11);
+    assert!(data.iter().all(|op| op.tenant_scoped));
 }
 
 #[test]
diff --git a/crates/hodeishield-cli/src/auth/oauth.rs b/crates/hodeishield-cli/src/auth/oauth.rs
index 6d620ee..0628c5f 100644
--- a/crates/hodeishield-cli/src/auth/oauth.rs
+++ b/crates/hodeishield-cli/src/auth/oauth.rs
@@ -10,6 +10,7 @@
 use crate::failure::{Failure, Kind, Result, error_chain};
 use base64::Engine as _;
 use base64::engine::general_purpose::URL_SAFE_NO_PAD;
+use hodeishield_api::v1::operations;
 use secrecy::{ExposeSecret, SecretString};
 use serde::Deserialize;
 use sha2::{Digest, Sha256};
@@ -46,8 +47,11 @@ const OFFLINE_ACCESS: &str = "offline_access";
 pub fn default_scopes(metadata: &Metadata) -> Vec<String> {
     let offered = metadata.scopes_supported.as_deref();
     let mut scopes: Vec<String> = Vec::new();
-    let needed = hodeishield_api::v1::operations::ALL
+    let needed = operations::ALL
         .iter()
+        // The tenant listing answers a portfolio key only, never a sign-in: its scope is not
+        // asked for.
+        .filter(|operation| operation.id != operations::LIST_PORTFOLIO_TENANTS.id)
         .flat_map(|operation| operation.scopes.iter().copied())
         .chain([OFFLINE_ACCESS]);
     for scope in needed {
diff --git a/crates/hodeishield-cli/src/filters.rs b/crates/hodeishield-cli/src/filters.rs
index ba891a2..7842793 100644
--- a/crates/hodeishield-cli/src/filters.rs
+++ b/crates/hodeishield-cli/src/filters.rs
@@ -4,6 +4,10 @@
 //! The values the API document lists for a filter (`x-hs-known-values`): shown in `--help` and
 //! checked before a request. The lists are open vocabularies, so a value that is not listed is
 //! warned about and sent exactly as typed; nothing here refuses a value or rewrites it.
+//!
+//! The document may also mark values as deprecated (`x-hs-deprecated-values`, with the last day
+//! they are accepted in `x-hs-deprecated-values-sunset`). Such a value gets its own warning, which
+//! points to the listed values, and is still sent exactly as typed.
 
 use crate::output::clean;
 use hodeishield_api::Operation;
@@ -19,63 +23,77 @@ pub fn help(base: &str, operation: &Operation, param: &str) -> String {
     }
 }
 
-/// The legacy values of the alert `severity` filter and their current names.
+/// Replacements for the deprecated values of the alert `severity` filter.
 ///
-/// The API is moving alert severity from a legacy Spanish scale to an English vocabulary, and
-/// for a transition period its filter accepts both. A legacy value typed by the user is still
-/// sent exactly as typed (the server accepts it); this table only lets the CLI say what to use
-/// instead. It applies to the alert severity filter alone and can be removed, with
-/// [`legacy_hint`], after [`LEGACY_SEVERITY_END`].
-const LEGACY_SEVERITY: &[(&str, &str)] = &[
+/// This table exists only because the API document lists the deprecated values without their
+/// replacements. Remove it, and its use in [`deprecated_hint`], after the sunset, 2027-01-14.
+const SEVERITY_REPLACEMENTS: &[(&str, &str)] = &[
     ("critico", "critical"),
     ("alto", "high"),
     ("medio", "medium"),
     ("bajo", "low"),
-    ("info", "info"),
 ];
 
-/// The last day the API accepts the legacy severity values.
-const LEGACY_SEVERITY_END: &str = "2027-01-14";
-
-/// The specific hint for a legacy severity value, or `None` when the generic warning applies.
-///
-/// It fires only when the API document lists the English values, so only once the server has
-/// switched. Until then the API still returns the legacy scale and the legacy values are the
-/// working spelling; telling users to move away from them would send them to values that match
-/// nothing. A document without a list stays silent, like every other filter.
-fn legacy_hint(operation: &Operation, param: &str, value: &str, known: &[&str]) -> Option<String> {
+/// The listed value that replaces the deprecated `value`, when [`SEVERITY_REPLACEMENTS`] knows one
+/// and the document lists it.
+fn replacement(operation: &Operation, param: &str, value: &str) -> Option<&'static str> {
     if operation.id != "listAlerts" || param != "severity" {
         return None;
     }
-    let (_, current) = LEGACY_SEVERITY
+    let (_, current) = SEVERITY_REPLACEMENTS
+        .iter()
+        .find(|(deprecated, _)| deprecated.eq_ignore_ascii_case(value))?;
+    operation
+        .known_values(param)
+        .is_some_and(|known| known.contains(current))
+        .then_some(*current)
+}
+
+/// The warning for a value the document marks as deprecated for `param` (matched without regard
+/// to case), or `None` when it does not.
+fn deprecated_hint(operation: &Operation, param: &str, value: &str) -> Option<String> {
+    let deprecated = operation.deprecated_values(param)?;
+    if !deprecated
+        .values
         .iter()
-        .find(|(legacy, _)| legacy.eq_ignore_ascii_case(value))?;
-    if !known.contains(current) {
+        .any(|d| d.eq_ignore_ascii_case(value))
+    {
         return None;
     }
+    let until = deprecated.sunset.map_or_else(String::new, |date| {
+        format!(", accepted by the API until {date}")
+    });
+    let known = operation.known_values(param).filter(|v| !v.is_empty());
+    let advice = match (replacement(operation, param, value), known) {
+        (Some(current), _) => format!("; use `{current}`"),
+        (None, Some(known)) => format!("; use one of the listed values ({})", known.join(", ")),
+        (None, None) => String::new(),
+    };
     Some(format!(
-        "warning: `{}` is a legacy severity value, accepted by the API until \
-         {LEGACY_SEVERITY_END}; use `{current}`. Sending it as typed.",
+        "warning: `{}` is a deprecated value for --{}{until}{advice}. Sending it as typed.",
         clean(value),
+        param.replace('_', "-"),
     ))
 }
 
-/// The warnings for the `(parameter, value)` pairs the user gave, one per value that is not in the
-/// list the document publishes for that parameter. A parameter without a list never warns. The
-/// match is exact and case-sensitive, as the API is; a value that differs only by case also gets
-/// the listed spelling as a hint.
+/// The warnings for the `(parameter, value)` pairs the user gave: one per value the document marks
+/// as deprecated for that parameter, and one per value that is not in the list it publishes. A
+/// parameter without either list never warns. The match against the list is exact and
+/// case-sensitive, as the API is; a value that differs only by case also gets the listed spelling
+/// as a hint.
 pub fn warnings(operation: &Operation, filters: &[(&str, Option<&str>)]) -> Vec<String> {
     filters
         .iter()
         .filter_map(|&(param, value)| {
             let value = value?;
-            let known = operation.known_values(param).filter(|v| !v.is_empty())?;
-            if known.contains(&value) {
+            let known = operation.known_values(param).filter(|v| !v.is_empty());
+            if known.is_some_and(|known| known.contains(&value)) {
                 return None;
             }
-            if let Some(hint) = legacy_hint(operation, param, value, known) {
+            if let Some(hint) = deprecated_hint(operation, param, value) {
                 return Some(hint);
             }
+            let known = known?;
             let tail = known
                 .iter()
                 .find(|k| k.eq_ignore_ascii_case(value))
@@ -103,6 +121,7 @@ pub fn warn_unknown(operation: &Operation, filters: &[(&str, Option<&str>)]) {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use hodeishield_api::DeprecatedValues;
 
     const WITH_LISTS: Operation = Operation {
         id: "listAlerts",
@@ -111,6 +130,7 @@ mod tests {
         summary: "List alerts",
         scopes: &[],
         known_values: &[("severity", &["critical", "high", "medium", "low"])],
+        deprecated_values: &[],
         tenant_scoped: true,
     };
 
@@ -153,87 +173,139 @@ mod tests {
         assert!(warnings(&WITHOUT_LISTS, &[("severity", Some("urgent"))]).is_empty());
     }
 
-    const ENGLISH: Operation = Operation {
+    const ALERTS: Operation = Operation {
         known_values: &[("severity", &["critical", "high", "medium", "low", "info"])],
-        tenant_scoped: true,
+        deprecated_values: &[DeprecatedValues {
+            param: "severity",
+            values: &["critico", "alto", "medio", "bajo", "urgente"],
+            sunset: Some("2027-01-14"),
+        }],
         ..WITH_LISTS
     };
 
     #[test]
-    fn a_legacy_severity_points_to_its_new_name() {
+    fn a_deprecated_value_with_a_replacement_points_to_it() {
         assert_eq!(
-            warnings(&ENGLISH, &[("severity", Some("alto"))]),
+            warnings(&ALERTS, &[("severity", Some("alto"))]),
             [
-                "warning: `alto` is a legacy severity value, accepted by the API until \
+                "warning: `alto` is a deprecated value for --severity, accepted by the API until \
                  2027-01-14; use `high`. Sending it as typed."
             ]
         );
-        for (legacy, current) in [
+        for (deprecated, current) in [
             ("critico", "critical"),
             ("medio", "medium"),
             ("bajo", "low"),
         ] {
-            let out = warnings(&ENGLISH, &[("severity", Some(legacy))]);
+            let out = warnings(&ALERTS, &[("severity", Some(deprecated))]);
             assert!(out[0].contains(&format!("use `{current}`")), "{out:?}");
         }
     }
 
     #[test]
-    fn a_legacy_severity_is_matched_without_regard_to_case() {
-        let out = warnings(&ENGLISH, &[("severity", Some("ALTO"))]);
+    fn a_deprecated_value_is_matched_without_regard_to_case() {
+        let out = warnings(&ALERTS, &[("severity", Some("ALTO"))]);
         assert_eq!(out.len(), 1);
-        assert!(out[0].starts_with("warning: `ALTO` is a legacy severity value"));
+        assert!(out[0].starts_with("warning: `ALTO` is a deprecated value for --severity"));
         assert!(out[0].contains("use `high`"), "{out:?}");
     }
 
     #[test]
-    fn a_current_severity_is_silent() {
-        for value in ["critical", "high", "medium", "low", "info"] {
-            assert!(warnings(&ENGLISH, &[("severity", Some(value))]).is_empty());
-        }
-    }
-
-    #[test]
-    fn an_unrelated_severity_keeps_the_generic_warning() {
-        let out = warnings(&ENGLISH, &[("severity", Some("urgent"))]);
+    fn a_deprecated_value_without_a_replacement_points_to_the_listed_values() {
+        assert_eq!(
+            warnings(&ALERTS, &[("severity", Some("urgente"))]),
+            [
+                "warning: `urgente` is a deprecated value for --severity, accepted by the API \
+                 until 2027-01-14; use one of the listed values (critical, high, medium, low, \
+                 info). Sending it as typed."
+            ]
+        );
+        // A replacement the document does not list is not offered.
+        let unlisted = Operation {
+            known_values: &[("severity", &["urgent"])],
+            ..ALERTS
+        };
+        let out = warnings(&unlisted, &[("severity", Some("alto"))]);
         assert!(
-            out[0].contains("is not one of the values the API lists"),
+            out[0].ends_with("use one of the listed values (urgent). Sending it as typed."),
             "{out:?}"
         );
     }
 
     #[test]
-    fn the_legacy_hint_waits_for_the_english_list() {
-        // No list yet: the API still speaks the legacy scale, so say nothing.
-        assert!(warnings(&WITHOUT_LISTS, &[("severity", Some("alto"))]).is_empty());
-        // A list without the new name: nothing to point to, so the generic warning stays.
-        let other_list = Operation {
-            known_values: &[("severity", &["urgent"])],
-            tenant_scoped: true,
+    fn a_deprecated_value_without_a_sunset_or_a_list() {
+        let no_sunset = Operation {
+            id: "listRisks",
+            known_values: &[("min_score", &["low", "high"])],
+            deprecated_values: &[DeprecatedValues {
+                param: "min_score",
+                values: &["bajo"],
+                sunset: None,
+            }],
             ..WITH_LISTS
         };
-        let out = warnings(&other_list, &[("severity", Some("bajo"))]);
-        assert!(
-            out[0].contains("is not one of the values the API lists"),
-            "{out:?}"
+        assert_eq!(
+            warnings(&no_sunset, &[("min_score", Some("bajo"))]),
+            [
+                "warning: `bajo` is a deprecated value for --min-score; use one of the listed \
+                 values (low, high). Sending it as typed."
+            ]
+        );
+        let no_list = Operation {
+            known_values: &[],
+            ..no_sunset
+        };
+        assert_eq!(
+            warnings(&no_list, &[("min_score", Some("bajo"))]),
+            ["warning: `bajo` is a deprecated value for --min-score. Sending it as typed."]
         );
     }
 
     #[test]
-    fn the_legacy_hint_is_scoped_to_the_alert_severity_filter() {
+    fn the_replacements_apply_to_the_alert_severity_filter_only() {
         let other = Operation {
             id: "listRisks",
-            known_values: &[("severity", &["high"])],
-            tenant_scoped: true,
-            ..WITH_LISTS
+            ..ALERTS
         };
         let out = warnings(&other, &[("severity", Some("alto"))]);
+        assert!(out[0].contains("use one of the listed values"), "{out:?}");
+    }
+
+    #[test]
+    fn a_current_severity_is_silent() {
+        for value in ["critical", "high", "medium", "low", "info"] {
+            assert!(warnings(&ALERTS, &[("severity", Some(value))]).is_empty());
+        }
+    }
+
+    #[test]
+    fn an_unrelated_severity_keeps_the_generic_warning() {
+        let out = warnings(&ALERTS, &[("severity", Some("urgent"))]);
         assert!(
             out[0].contains("is not one of the values the API lists"),
             "{out:?}"
         );
     }
 
+    /// Fails when the document adds or removes a deprecated severity, so the table above follows
+    /// it, and when a replacement is not a listed value.
+    #[test]
+    fn the_replacements_match_the_generated_alert_severity_filter() {
+        let operation = hodeishield_api::v1::operations::LIST_ALERTS;
+        let deprecated = operation
+            .deprecated_values("severity")
+            .expect("the document deprecates severity values");
+        let mut listed: Vec<&str> = deprecated.values.to_vec();
+        listed.sort_unstable();
+        let mut mapped: Vec<&str> = SEVERITY_REPLACEMENTS.iter().map(|(d, _)| *d).collect();
+        mapped.sort_unstable();
+        assert_eq!(mapped, listed);
+        let known = operation.known_values("severity").expect("listed values");
+        for (_, current) in SEVERITY_REPLACEMENTS {
+            assert!(known.contains(current), "{current}");
+        }
+    }
+
     #[test]
     fn control_characters_in_the_value_are_not_echoed() {
         let out = warnings(&WITH_LISTS, &[("severity", Some("a\u{1b}[31mb"))]);
diff --git a/crates/hodeishield-cli/tests/cli.rs b/crates/hodeishield-cli/tests/cli.rs
index d904ec9..0875f97 100644
--- a/crates/hodeishield-cli/tests/cli.rs
+++ b/crates/hodeishield-cli/tests/cli.rs
@@ -712,20 +712,14 @@ fn compliance_controls_csv() {
     assert_no_key(&output);
 }
 
-/// The vendored document lists no values for these filters yet, so they are sent exactly as typed,
+/// The vendored document lists no values for these filters, so they are sent exactly as typed,
 /// without a warning, and the command succeeds. (The warning itself is covered by the unit tests
 /// of `filters`, with operations that carry lists.)
 #[test]
 fn free_form_filters_are_sent_as_typed_without_a_warning() {
     for (args, path, param, value) in [
         (
-            &["alerts", "list", "--severity", "High"][..],
-            "/v1/alerts",
-            "severity",
-            "High",
-        ),
-        (
-            &["vendors", "list", "--category", "Cloud Host"],
+            &["vendors", "list", "--category", "Cloud Host"][..],
             "/v1/vendors",
             "category",
             "Cloud Host",
@@ -772,6 +766,47 @@ fn free_form_filters_are_sent_as_typed_without_a_warning() {
     }
 }
 
+/// The vendored document lists the alert severities and deprecates some older ones: a value that
+/// is not listed, or a deprecated one, gets a warning and is still sent exactly as typed.
+#[test]
+fn listed_and_deprecated_severities_warn_and_are_sent_as_typed() {
+    for (value, expected) in [
+        ("high", None),
+        ("High", Some("did you mean `high`? Sending it anyway.")),
+        (
+            "alto",
+            Some(
+                "warning: `alto` is a deprecated value for --severity, accepted by the API until \
+                 2027-01-14; use `high`. Sending it as typed.",
+            ),
+        ),
+    ] {
+        let env = Env::new();
+        let mut server = mockito::Server::new();
+        let mock = server
+            .mock("GET", "/v1/alerts")
+            .match_query(mockito::Matcher::UrlEncoded(
+                "severity".into(),
+                value.into(),
+            ))
+            .with_body(page(&[], 1, 0, 1))
+            .expect(1)
+            .create();
+        let output = env
+            .api(&server)
+            .args(["alerts", "list", "--severity", value])
+            .output()
+            .expect("run");
+        assert!(output.status.success(), "{value}: {output:?}");
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        match expected {
+            Some(warning) => assert!(stderr.contains(warning), "{value}: {stderr}"),
+            None => assert!(!stderr.contains("warning:"), "{value}: {stderr}"),
+        }
+        mock.assert();
+    }
+}
+
 // Client tenants, against a mock of the published portfolio contract (version 2026-10-16).
 
 /// The shape of a portfolio key: `hsp_`, 12 hex, `_`, 64 hex. Its secret part must never be shown.
diff --git a/openapi/README.md b/openapi/README.md
index 761f17a..1282ecf 100644
--- a/openapi/README.md
+++ b/openapi/README.md
@@ -6,9 +6,9 @@ from it; nothing in that client is written by hand from memory.
 
 | Field | Value |
 |---|---|
-| `info.version` | `2026-09-28` |
-| SHA-256 | `103e86f38f7b3eff45a0f764c8142b4bdd2e8d576385b1b4ccf588cbf0518fb3` |
-| Operations | 11, all `GET` |
+| `info.version` | `2026-10-16` |
+| SHA-256 | `1321a417aba28e7b60dbc28a35ce2dc3711d8973b985107f7701d70ff3be6b0d` |
+| Operations | 12, all `GET` |
 
 ## Updating it
 
diff --git a/openapi/v1.json b/openapi/v1.json
index 6256d0f..5ab3c5f 100644
--- a/openapi/v1.json
+++ b/openapi/v1.json
@@ -1 +1 @@
-{"openapi":"3.1.0","info":{"title":"Hodei-Shield API","version":"2026-09-28","summary":"Third-party risk and compliance posture, for your own systems.","description":"## Versioning\n\n`/v1` is frozen. These changes are **compatible** and will happen inside it\nwithout notice:\n\n- a new operation;\n- a new **optional** query parameter;\n- a new field in a response object;\n- a new value in a field documented as an open vocabulary (`status`,\n  `severity`, `evidence_type`, the keys of `by_status`);\n- a new `error.code`, always with the HTTP status its siblings already use;\n- anything under `error.details`, which is diagnostic and not part of the\n  contract.\n\nWrite your client so those do not break it: ignore unknown fields, do not\nswitch exhaustively on a documented-open vocabulary, and treat an unknown\n`error.code` as \"an error of this HTTP status\".\n\nThese changes are **incompatible** and will NOT happen inside `/v1`. They go\nto `/v2`, and `/v1` keeps serving:\n\n- removing or renaming an operation, a parameter or a field;\n- changing the type, the unit or the meaning of a field;\n- making an optional parameter required, or narrowing what one accepts;\n- changing which scope an operation requires;\n- changing the HTTP status an existing `error.code` is sent with.\n\n## Read-only\n\n`/v1` only reads. Every operation is a `GET`. Any other method (`POST`, `PUT`,\n`PATCH`, `DELETE`) on a path that exists answers **405** with `Allow: GET`, and on\na path that does not exist answers **404**: neither changes any state. A write\nwill be offered only as a new operation, which is a compatible change, once a\ncustomer asks for a concrete one.\n\n## Authentication\n\nEvery operation takes `Authorization: Bearer <tenant API key>`. A key belongs\nto ONE tenant and carries an explicit list of scopes; it can read nothing\noutside that tenant, whatever it asks for. Each operation below declares the\nscope it requires. A key that authenticates but lacks the scope is answered\n**403**, never 404: you are told what you are missing, not that the resource\ndoes not exist.\n\n## Errors\n\nEvery error has the same body:\n\n```json\n{ \"error\": { \"code\": \"forbidden\", \"message\": \"…\", \"request_id\": \"…\" } }\n```\n\nBranch on `code`, log `request_id`, show `message` to nobody but yourself.\n`request_id` is also the `X-Request-Id` response header, and it is what\nsupport will ask you for.\n\n## Rate limits\n\nEvery response that got past authentication carries the limit that is closest\nto being exhausted:\n\n- `RateLimit-Limit` — requests allowed in the window;\n- `RateLimit-Remaining` — requests left in the current window;\n- `RateLimit-Reset` — **seconds** until the window renews;\n- `RateLimit-Policy` — `<limit>;w=<window seconds>`.\n\nThree limits apply, each per one-minute window: per API key, per organisation\n(all of its keys together) and per service. The first two come from the licence\nof the organisation the key belongs to: a higher licence tier has more room, and\nan MSSP partner has more than a direct customer of the same tier. Read the\ncurrent limit from `RateLimit-Limit` and `RateLimit-Policy` rather than\nhard-coding it. When one is exhausted the answer is\n**429** with `error.code: \"rate_limited\"`, `Retry-After` (seconds) and\n`error.details.scope` (`key`, `tenant` or `service`) saying which. Your\norganisation's usage never counts against another's. Windows are fixed, so a\nclient can burst up to twice the limit across a window boundary: back off on\n`Retry-After` rather than pacing to the second. The limits are part of the\nservice, not of the frozen contract: they may be raised without notice.\n\n## Pagination, filtering and ordering\n\nEvery collection takes `page` and `per_page` (max 200) and answers with a\n`pagination` object carrying `total` and `total_pages`. Every collection\ntakes `sort` (an enum of the fields THAT collection can order by) and\n`order` (`asc`/`desc`, default `desc`). Filters are exact matches unless\nthe parameter says otherwise.","contact":{"name":"Hodeitek S.L.","url":"https://hodeishield.com"}},"servers":[{"url":"https://api.hodeishield.com"}],"tags":[{"name":"vendors"},{"name":"alerts"},{"name":"risks"},{"name":"compliance"},{"name":"evidence"},{"name":"endpoints"}],"paths":{"/v1/vendors":{"get":{"operationId":"listVendors","summary":"List third parties","description":"The tenant third-party inventory, newest first by default. Soft-deleted vendors are never returned.\n\nRequired scope: `supply_risk:read`. Published in `/v1` since 2026-09-20.","tags":["vendors"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: created_at, updated_at, name.","schema":{"default":"created_at","type":"string","enum":["created_at","updated_at","name"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"q","in":"query","required":false,"description":"Case-insensitive substring of the name or the domain.","schema":{"type":"string","minLength":1,"maxLength":120}},{"name":"category","in":"query","required":false,"description":"Exact category match.","schema":{"type":"string","minLength":1,"maxLength":120}},{"name":"active","in":"query","required":false,"description":"Filter by the operational flag.","schema":{"type":"string"}},{"name":"business_criticality","in":"query","required":false,"description":"Exact criticality match.","schema":{"type":"string","enum":["low","medium","high","critical"]}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Stable identifier of the vendor in this tenant."},"name":{"type":"string","description":"Display name."},"legal_name":{"description":"Registered legal name, when it differs.","type":["string","null"]},"domain":{"description":"Primary domain, lowercase, no scheme.","type":["string","null"]},"category":{"description":"Free-text category assigned by the tenant.","type":["string","null"]},"vendor_type":{"description":"Kind of third party (provider, product, …).","type":["string","null"]},"access_level":{"description":"Level of access the vendor has to the tenant systems.","type":["string","null"]},"business_criticality":{"description":"low | medium | high | critical, as set by the tenant.","type":["string","null"]},"data_sensitivity":{"description":"public | internal | confidential | restricted.","type":["string","null"]},"economic_impact":{"description":"Estimated economic impact of an outage, in the tenant currency.","type":["number","null"]},"active":{"type":"boolean","description":"Whether the vendor is operationally enabled."},"monitoring_status":{"description":"Continuous-monitoring state.","type":["string","null"]},"last_scan_at":{"description":"RFC 3339, UTC. Null if never scanned.","type":["string","null"]},"lei":{"description":"Legal Entity Identifier (ISO 17442), for DORA RoI.","type":["string","null"]},"hq_country":{"description":"Head-office country, ISO 3166-1 alpha-2.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."},"updated_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","name","legal_name","domain","category","vendor_type","access_level","business_criticality","data_sensitivity","economic_impact","active","monitoring_status","last_scan_at","lei","hq_country","created_at","updated_at"],"additionalProperties":false,"description":"A third party in the tenant inventory."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range. `error.details` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key or an OAuth access token; the cases are not distinguished). The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but does not carry the scope this operation requires. `error.details.missing` lists the scopes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` (`key`, `tenant` or `service`) which limit it was.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["supply_risk:read"]}],"x-hs-scope":{"scopes":["supply_risk:read"]}}},"/v1/vendors/{id}":{"get":{"operationId":"getVendor","summary":"Fetch one third party","description":"The same object `listVendors` returns, for a single vendor.\n\nRequired scope: `supply_risk:read`. Published in `/v1` since 2026-09-20.","tags":["vendors"],"parameters":[{"name":"id","in":"path","required":true,"description":"Vendor identifier.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Stable identifier of the vendor in this tenant."},"name":{"type":"string","description":"Display name."},"legal_name":{"description":"Registered legal name, when it differs.","type":["string","null"]},"domain":{"description":"Primary domain, lowercase, no scheme.","type":["string","null"]},"category":{"description":"Free-text category assigned by the tenant.","type":["string","null"]},"vendor_type":{"description":"Kind of third party (provider, product, …).","type":["string","null"]},"access_level":{"description":"Level of access the vendor has to the tenant systems.","type":["string","null"]},"business_criticality":{"description":"low | medium | high | critical, as set by the tenant.","type":["string","null"]},"data_sensitivity":{"description":"public | internal | confidential | restricted.","type":["string","null"]},"economic_impact":{"description":"Estimated economic impact of an outage, in the tenant currency.","type":["number","null"]},"active":{"type":"boolean","description":"Whether the vendor is operationally enabled."},"monitoring_status":{"description":"Continuous-monitoring state.","type":["string","null"]},"last_scan_at":{"description":"RFC 3339, UTC. Null if never scanned.","type":["string","null"]},"lei":{"description":"Legal Entity Identifier (ISO 17442), for DORA RoI.","type":["string","null"]},"hq_country":{"description":"Head-office country, ISO 3166-1 alpha-2.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."},"updated_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","name","legal_name","domain","category","vendor_type","access_level","business_criticality","data_sensitivity","economic_impact","active","monitoring_status","last_scan_at","lei","hq_country","created_at","updated_at"],"additionalProperties":false,"description":"A third party in the tenant inventory."}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range. `error.details` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key or an OAuth access token; the cases are not distinguished). The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but does not carry the scope this operation requires. `error.details.missing` lists the scopes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` (`key`, `tenant` or `service`) which limit it was.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["supply_risk:read"]}],"x-hs-scope":{"scopes":["supply_risk:read"]}}},"/v1/alerts":{"get":{"operationId":"listAlerts","summary":"List supply-chain alerts","description":"Alerts raised against the tenant vendors. Poll incrementally with `since` plus `order=asc`.\n\nRequired scope: `supply_risk:read`. Published in `/v1` since 2026-09-20.","tags":["alerts"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: created_at.","schema":{"default":"created_at","type":"string","enum":["created_at"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"status","in":"query","required":false,"description":"Filter by the derived status.","schema":{"type":"string","enum":["open","acknowledged","resolved"]}},{"name":"severity","in":"query","required":false,"description":"Exact severity match.","schema":{"type":"string","minLength":1,"maxLength":40}},{"name":"vendor_id","in":"query","required":false,"description":"Only alerts about this vendor.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"since","in":"query","required":false,"description":"Only alerts created at or after this RFC 3339 instant.","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"vendor_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The vendor this alert is about (`/v1/vendors/{id}`)."},"type":{"type":"string","description":"Alert family, e.g. `breach`, `cve`, `rating_drop`."},"severity":{"description":"critical | high | medium | low, when classified.","type":["string","null"]},"title":{"type":"string"},"description":{"type":["string","null"]},"source_url":{"description":"Where the finding came from, when public.","type":["string","null"]},"economic_impact":{"type":["number","null"]},"status":{"type":"string","enum":["open","acknowledged","resolved"],"description":"Derived: resolved if closed, acknowledged if taken, otherwise open."},"acknowledged_at":{"description":"RFC 3339, UTC.","type":["string","null"]},"resolved_at":{"description":"RFC 3339, UTC.","type":["string","null"]},"resolution_reason":{"description":"Why it was closed, when it was.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","vendor_id","type","severity","title","description","source_url","economic_impact","status","acknowledged_at","resolved_at","resolution_reason","created_at"],"additionalProperties":false,"description":"A supply-chain alert raised against one vendor."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range. `error.details` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key or an OAuth access token; the cases are not distinguished). The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but does not carry the scope this operation requires. `error.details.missing` lists the scopes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` (`key`, `tenant` or `service`) which limit it was.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["supply_risk:read"]}],"x-hs-scope":{"scopes":["supply_risk:read"]}}},"/v1/alerts/{id}":{"get":{"operationId":"getAlert","summary":"Fetch one alert","description":"The same object `listAlerts` returns, for a single alert.\n\nRequired scope: `supply_risk:read`. Published in `/v1` since 2026-09-20.","tags":["alerts"],"parameters":[{"name":"id","in":"path","required":true,"description":"Alert identifier.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"vendor_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The vendor this alert is about (`/v1/vendors/{id}`)."},"type":{"type":"string","description":"Alert family, e.g. `breach`, `cve`, `rating_drop`."},"severity":{"description":"critical | high | medium | low, when classified.","type":["string","null"]},"title":{"type":"string"},"description":{"type":["string","null"]},"source_url":{"description":"Where the finding came from, when public.","type":["string","null"]},"economic_impact":{"type":["number","null"]},"status":{"type":"string","enum":["open","acknowledged","resolved"],"description":"Derived: resolved if closed, acknowledged if taken, otherwise open."},"acknowledged_at":{"description":"RFC 3339, UTC.","type":["string","null"]},"resolved_at":{"description":"RFC 3339, UTC.","type":["string","null"]},"resolution_reason":{"description":"Why it was closed, when it was.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","vendor_id","type","severity","title","description","source_url","economic_impact","status","acknowledged_at","resolved_at","resolution_reason","created_at"],"additionalProperties":false,"description":"A supply-chain alert raised against one vendor."}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range. `error.details` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key or an OAuth access token; the cases are not distinguished). The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but does not carry the scope this operation requires. `error.details.missing` lists the scopes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` (`key`, `tenant` or `service`) which limit it was.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["supply_risk:read"]}],"x-hs-scope":{"scopes":["supply_risk:read"]}}},"/v1/risks":{"get":{"operationId":"listRisks","summary":"List risk-register entries","description":"The tenant risk register, with inherent and residual figures.\n\nRequired scope: `supply_risk:read`. Published in `/v1` since 2026-09-20.","tags":["risks"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: created_at, updated_at, inherent_score, residual_score.","schema":{"default":"created_at","type":"string","enum":["created_at","updated_at","inherent_score","residual_score"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"status","in":"query","required":false,"description":"Exact status match.","schema":{"type":"string","minLength":1,"maxLength":24}},{"name":"domain","in":"query","required":false,"description":"Exact domain match.","schema":{"type":"string","minLength":1,"maxLength":20}},{"name":"vendor_id","in":"query","required":false,"description":"Only risks linked to this vendor.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"min_inherent_score","in":"query","required":false,"description":"Only risks whose inherent score is at least this.","schema":{"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"title":{"type":"string"},"description":{"type":["string","null"]},"domain":{"type":"string","description":"Risk domain, as configured by the tenant."},"status":{"type":"string","description":"identified | assessed | treated | accepted | closed | …"},"treatment":{"description":"mitigate | accept | transfer | avoid.","type":["string","null"]},"treatment_notes":{"type":["string","null"]},"threat_source":{"type":["string","null"]},"vulnerability":{"type":["string","null"]},"likelihood_inherent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"impact_inherent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"inherent_score":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"likelihood_residual":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"impact_residual":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"residual_score":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string","description":"manual | imported | derived."},"owner_user_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"User of this tenant who owns the risk."},"vendor_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The vendor this risk is about, when any."},"control_codes":{"type":"array","items":{"type":"string"},"description":"Framework control codes linked to the risk."},"review_date":{"description":"Calendar date, `YYYY-MM-DD`.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."},"updated_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","title","description","domain","status","treatment","treatment_notes","threat_source","vulnerability","likelihood_inherent","impact_inherent","inherent_score","likelihood_residual","impact_residual","residual_score","source","owner_user_id","vendor_id","control_codes","review_date","created_at","updated_at"],"additionalProperties":false,"description":"An entry of the tenant risk register."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range. `error.details` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key or an OAuth access token; the cases are not distinguished). The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but does not carry the scope this operation requires. `error.details.missing` lists the scopes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` (`key`, `tenant` or `service`) which limit it was.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["supply_risk:read"]}],"x-hs-scope":{"scopes":["supply_risk:read"]}}},"/v1/risks/{id}":{"get":{"operationId":"getRisk","summary":"Fetch one risk-register entry","description":"The same object `listRisks` returns, for a single entry.\n\nRequired scope: `supply_risk:read`. Published in `/v1` since 2026-09-20.","tags":["risks"],"parameters":[{"name":"id","in":"path","required":true,"description":"Risk identifier.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"title":{"type":"string"},"description":{"type":["string","null"]},"domain":{"type":"string","description":"Risk domain, as configured by the tenant."},"status":{"type":"string","description":"identified | assessed | treated | accepted | closed | …"},"treatment":{"description":"mitigate | accept | transfer | avoid.","type":["string","null"]},"treatment_notes":{"type":["string","null"]},"threat_source":{"type":["string","null"]},"vulnerability":{"type":["string","null"]},"likelihood_inherent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"impact_inherent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"inherent_score":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"likelihood_residual":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"impact_residual":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"residual_score":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string","description":"manual | imported | derived."},"owner_user_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"User of this tenant who owns the risk."},"vendor_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The vendor this risk is about, when any."},"control_codes":{"type":"array","items":{"type":"string"},"description":"Framework control codes linked to the risk."},"review_date":{"description":"Calendar date, `YYYY-MM-DD`.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."},"updated_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","title","description","domain","status","treatment","treatment_notes","threat_source","vulnerability","likelihood_inherent","impact_inherent","inherent_score","likelihood_residual","impact_residual","residual_score","source","owner_user_id","vendor_id","control_codes","review_date","created_at","updated_at"],"additionalProperties":false,"description":"An entry of the tenant risk register."}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range. `error.details` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key or an OAuth access token; the cases are not distinguished). The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but does not carry the scope this operation requires. `error.details.missing` lists the scopes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` (`key`, `tenant` or `service`) which limit it was.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["supply_risk:read"]}],"x-hs-scope":{"scopes":["supply_risk:read"]}}},"/v1/compliance/controls":{"get":{"operationId":"listComplianceControls","summary":"List control status for a framework","description":"Per-control status of one framework. Requires the read scope OF THAT FRAMEWORK: `compliance.<framework>:read`.\n\nRequired scope: `compliance.<framework>:read`. Published in `/v1` since 2026-09-20.","tags":["compliance"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: control_code, last_evaluated_at.","schema":{"default":"control_code","type":"string","enum":["control_code","last_evaluated_at"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"framework","in":"query","required":true,"description":"Framework slug. One of: nis2, ens, iso27001, dora, gdpr, soc2, iso42001, nistcsf, pcidss, euaiact, hipaa, cmmc, cyberessentials, uaeia, sama, saudiecc, ndpa.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Exact status match.","schema":{"type":"string","minLength":1,"maxLength":20}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"framework":{"type":"string","description":"Framework slug the control belongs to."},"control_code":{"type":"string","description":"Control identifier inside the framework."},"status":{"type":"string","description":"missing | partial | covered, as evaluated by the platform."},"evidence_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Evidence items currently linked to the control."},"last_evaluated_at":{"description":"RFC 3339, UTC.","type":["string","null"]}},"required":["framework","control_code","status","evidence_count","last_evaluated_at"],"additionalProperties":false,"description":"The tenant status of one framework control."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range. `error.details` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key or an OAuth access token; the cases are not distinguished). The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but does not carry the scope this operation requires. `error.details.missing` lists the scopes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` (`key`, `tenant` or `service`) which limit it was.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":[]}],"x-hs-scope":{"template":"compliance.<framework>:read"}}},"/v1/compliance/frameworks/{framework}":{"get":{"operationId":"getFrameworkPosture","summary":"Framework posture summary","description":"Counts of evaluated controls by status for one framework, for a dashboard tile. Requires `compliance.<framework>:read`.\n\nRequired scope: `compliance.<framework>:read`. Published in `/v1` since 2026-09-20.","tags":["compliance"],"parameters":[{"name":"framework","in":"path","required":true,"description":"Framework slug. One of: nis2, ens, iso27001, dora, gdpr, soc2, iso42001, nistcsf, pcidss, euaiact, hipaa, cmmc, cyberessentials, uaeia, sama, saudiecc, ndpa.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"framework":{"type":"string"},"controls_total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Controls the platform has evaluated."},"by_status":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"description":"Control count per status. Keys are whatever statuses exist; may grow."},"evidence_total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Sum of the evidence linked across the evaluated controls."},"last_evaluated_at":{"description":"Most recent control evaluation, RFC 3339 UTC. Null if never evaluated.","type":["string","null"]}},"required":["framework","controls_total","by_status","evidence_total","last_evaluated_at"],"additionalProperties":false,"description":"Posture summary for one framework."}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range. `error.details` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key or an OAuth access token; the cases are not distinguished). The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but does not carry the scope this operation requires. `error.details.missing` lists the scopes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` (`key`, `tenant` or `service`) which limit it was.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":[]}],"x-hs-scope":{"template":"compliance.<framework>:read"}}},"/v1/evidence":{"get":{"operationId":"listEvidence","summary":"List security evidence","description":"Evidence held for the tenant. Use `expiring_before` plus `sort=valid_until&order=asc` for a renewal queue.\n\nRequired scope: `evidence:read`. Published in `/v1` since 2026-09-20.","tags":["evidence"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: created_at, valid_until.","schema":{"default":"created_at","type":"string","enum":["created_at","valid_until"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"evidence_type","in":"query","required":false,"description":"Exact type match.","schema":{"type":"string","minLength":1,"maxLength":50}},{"name":"source_type","in":"query","required":false,"description":"Exact producer match.","schema":{"type":"string","minLength":1,"maxLength":50}},{"name":"vendor_id","in":"query","required":false,"description":"Only evidence about this vendor.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"expiring_before","in":"query","required":false,"description":"Only evidence with a `valid_until` strictly before this `YYYY-MM-DD`.","schema":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"evidence_type":{"type":"string","description":"What kind of evidence this is."},"source_type":{"type":"string","description":"Which subsystem produced it."},"source_id":{"type":"string","description":"Its identifier inside that subsystem."},"title":{"type":"string"},"description":{"type":["string","null"]},"vendor_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The vendor it is about, when any."},"asset_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The asset it is about, when any."},"auto_generated":{"type":"boolean","description":"False when a person uploaded it."},"valid_until":{"description":"Calendar date, `YYYY-MM-DD`. Null = no expiry.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","evidence_type","source_type","source_id","title","description","vendor_id","asset_id","auto_generated","valid_until","created_at"],"additionalProperties":false,"description":"One item of security evidence."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range. `error.details` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key or an OAuth access token; the cases are not distinguished). The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but does not carry the scope this operation requires. `error.details.missing` lists the scopes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` (`key`, `tenant` or `service`) which limit it was.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["evidence:read"]}],"x-hs-scope":{"scopes":["evidence:read"]}}},"/v1/evidence/{id}":{"get":{"operationId":"getEvidence","summary":"Fetch one evidence item","description":"The same object `listEvidence` returns, for a single item.\n\nRequired scope: `evidence:read`. Published in `/v1` since 2026-09-20.","tags":["evidence"],"parameters":[{"name":"id","in":"path","required":true,"description":"Evidence identifier.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"evidence_type":{"type":"string","description":"What kind of evidence this is."},"source_type":{"type":"string","description":"Which subsystem produced it."},"source_id":{"type":"string","description":"Its identifier inside that subsystem."},"title":{"type":"string"},"description":{"type":["string","null"]},"vendor_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The vendor it is about, when any."},"asset_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The asset it is about, when any."},"auto_generated":{"type":"boolean","description":"False when a person uploaded it."},"valid_until":{"description":"Calendar date, `YYYY-MM-DD`. Null = no expiry.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","evidence_type","source_type","source_id","title","description","vendor_id","asset_id","auto_generated","valid_until","created_at"],"additionalProperties":false,"description":"One item of security evidence."}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range. `error.details` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key or an OAuth access token; the cases are not distinguished). The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but does not carry the scope this operation requires. `error.details.missing` lists the scopes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` (`key`, `tenant` or `service`) which limit it was.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["evidence:read"]}],"x-hs-scope":{"scopes":["evidence:read"]}}},"/v1/endpoints":{"get":{"operationId":"listEndpoints","summary":"List enrolled endpoint agents","description":"The endpoint agents enrolled in this tenant. `silent_since` selects the ones that have gone quiet, including those that never reported.\n\nRequired scope: `endpoints:read`. Published in `/v1` since 2026-09-20.","tags":["endpoints"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: enrolled_at, last_seen_at, producer.","schema":{"default":"enrolled_at","type":"string","enum":["enrolled_at","last_seen_at","producer"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"status","in":"query","required":false,"description":"Exact status match.","schema":{"type":"string","enum":["active","revoked"]}},{"name":"silent_since","in":"query","required":false,"description":"Agents last seen before this RFC 3339 instant, or never seen at all.","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"producer":{"type":"string","description":"The agent name, unique among the active ones of the tenant."},"producer_kind":{"type":"string","description":"What kind of producer it is."},"status":{"type":"string","description":"active | revoked."},"signature_alg":{"type":"string","description":"Algorithm this enrollment signs with."},"agent_version":{"type":["string","null"]},"hostname":{"description":"Last hostname the agent reported.","type":["string","null"]},"enrolled_at":{"type":"string","description":"RFC 3339, UTC."},"last_seen_at":{"description":"RFC 3339, UTC. Null until the first envelope.","type":["string","null"]},"revoked_at":{"description":"RFC 3339, UTC.","type":["string","null"]}},"required":["id","producer","producer_kind","status","signature_alg","agent_version","hostname","enrolled_at","last_seen_at","revoked_at"],"additionalProperties":false,"description":"An endpoint agent enrolled in this tenant."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range. `error.details` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key or an OAuth access token; the cases are not distinguished). The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but does not carry the scope this operation requires. `error.details.missing` lists the scopes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` (`key`, `tenant` or `service`) which limit it was.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["endpoints:read"]}],"x-hs-scope":{"scopes":["endpoints:read"]}}}},"components":{"schemas":{"Error":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_request","unauthorized","forbidden","not_found","method_not_allowed","rate_limited","internal_error","service_unavailable"],"description":"Closed vocabulary; new members may be added (see Versioning)."},"message":{"type":"string","description":"For a human reading a log. Not stable; do not parse it."},"request_id":{"type":"string","description":"Also the `X-Request-Id` response header."},"details":{"type":"object","additionalProperties":true,"description":"Diagnostic. Not part of the frozen contract."}}}}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"A tenant API key, created in the console under Settings → API keys with the minimum scopes it needs."},"oauth2":{"type":"oauth2","description":"A USER access token (`hs_at_…`) issued by the HodeiShield console, the OAuth 2.1 authorization server at `https://app.hodeishield.com/api/auth` (metadata: `/.well-known/oauth-authorization-server` on its origin). Authorization code with PKCE (S256, mandatory) for applications with a browser; the RFC 8628 device authorization grant (`https://app.hodeishield.com/api/auth/device/code`) for those without one. Every token is bound to ONE user and ONE tenant, chosen by the user on the consent screen, and carries read scopes only; the tenant is re-checked against what the user can see on every request. Public clients register themselves (RFC 7591) at `/oauth2/register`; the HodeiShield CLI is pre-registered as `hodeishield-cli`. Revocation: RFC 7009 at `/oauth2/revoke`, or by the user in the console under Account → Application access.","flows":{"authorizationCode":{"authorizationUrl":"https://app.hodeishield.com/api/auth/oauth2/authorize","tokenUrl":"https://app.hodeishield.com/api/auth/oauth2/token","refreshUrl":"https://app.hodeishield.com/api/auth/oauth2/token","scopes":{"supply_risk:read":"Read supply_risk data of the tenant the token is bound to.","compliance.nis2:read":"Read compliance.nis2 data of the tenant the token is bound to.","compliance.ens:read":"Read compliance.ens data of the tenant the token is bound to.","compliance.iso27001:read":"Read compliance.iso27001 data of the tenant the token is bound to.","compliance.dora:read":"Read compliance.dora data of the tenant the token is bound to.","compliance.gdpr:read":"Read compliance.gdpr data of the tenant the token is bound to.","compliance.soc2:read":"Read compliance.soc2 data of the tenant the token is bound to.","compliance.iso42001:read":"Read compliance.iso42001 data of the tenant the token is bound to.","compliance.nistcsf:read":"Read compliance.nistcsf data of the tenant the token is bound to.","compliance.pcidss:read":"Read compliance.pcidss data of the tenant the token is bound to.","compliance.euaiact:read":"Read compliance.euaiact data of the tenant the token is bound to.","compliance.hipaa:read":"Read compliance.hipaa data of the tenant the token is bound to.","compliance.cmmc:read":"Read compliance.cmmc data of the tenant the token is bound to.","compliance.cyberessentials:read":"Read compliance.cyberessentials data of the tenant the token is bound to.","compliance.uaeia:read":"Read compliance.uaeia data of the tenant the token is bound to.","compliance.sama:read":"Read compliance.sama data of the tenant the token is bound to.","compliance.saudiecc:read":"Read compliance.saudiecc data of the tenant the token is bound to.","compliance.ndpa:read":"Read compliance.ndpa data of the tenant the token is bound to.","radar:read":"Read radar data of the tenant the token is bound to.","connectors:read":"Read connectors data of the tenant the token is bound to.","endpoints:read":"Read endpoints data of the tenant the token is bound to.","hodeiai:read":"Read hodeiai data of the tenant the token is bound to.","virtual_ciso:read":"Read virtual_ciso data of the tenant the token is bound to.","simulator:read":"Read simulator data of the tenant the token is bound to.","evidence:read":"Read evidence data of the tenant the token is bound to.","reports:read":"Read reports data of the tenant the token is bound to.","management:read":"Read management data of the tenant the token is bound to.","offline_access":"Issue a refresh token (30 days, rotated on every use)."}}}}}},"security":[{"bearerAuth":[]},{"oauth2":[]}]}
\ No newline at end of file
+{"openapi":"3.1.0","info":{"title":"Hodei-Shield API","version":"2026-10-16","summary":"Third-party risk and compliance posture, for your own systems.","description":"## Versioning\n\n`/v1` is frozen. These changes are **compatible** and will happen inside it\nwithout notice:\n\n- a new operation;\n- a new **optional** query parameter;\n- a new field in a response object;\n- a new value in a field documented as an open vocabulary (`status`,\n  `severity`, `evidence_type`, the keys of `by_status`);\n- a new `error.code`, always with the HTTP status its siblings already use;\n- anything under `error.details`, which is diagnostic and not part of the\n  contract — except `error.details.code` and the keys the error table of\n  the operation names (`missing`, `licence`, `parameter`, `scope`,\n  `limit`, `window_seconds`, `retry_after_seconds`): those are contract.\n  `error.details.code` is an OPEN vocabulary: a value, once published, keeps\n  its meaning and the HTTP status it is sent with; new values may be added.\n\nWrite your client so those do not break it: ignore unknown fields, do not\nswitch exhaustively on a documented-open vocabulary, and treat an unknown\n`error.code` as \"an error of this HTTP status\".\n\nThese changes are **incompatible** and will NOT happen inside `/v1`. They go\nto `/v2`, and `/v1` keeps serving:\n\n- removing or renaming an operation, a parameter or a field;\n- changing the type, the unit or the meaning of a field;\n- making an optional parameter required, or narrowing what one accepts;\n- changing which scope an operation requires;\n- changing the HTTP status an existing `error.code` is sent with.\n\n## Read-only\n\n`/v1` only reads. Every operation is a `GET`. Any other method (`POST`, `PUT`,\n`PATCH`, `DELETE`) on a path that exists answers **405** with `Allow: GET`, and on\na path that does not exist answers **404**: neither changes any state. A write\nwill be offered only as a new operation, which is a compatible change, once a\ncustomer asks for a concrete one.\n\n## Authentication\n\nEvery operation takes `Authorization: Bearer <credential>`. Three credentials\nexist:\n\n- a **tenant API key** (`hsk_…`): belongs to ONE tenant and carries an\n  explicit list of scopes; it can read nothing outside that tenant, whatever it\n  asks for;\n- a user's **OAuth access token** (`hs_at_…`): one user, ONE tenant chosen\n  at consent, read scopes only;\n- an MSSP **portfolio key** (`hsp_…`): held by a managed security service\n  provider, it reads ANY of its client tenants, ONE per request, selected with\n  the request header `X-HS-Tenant: <tenant id>` (a UUID, never a slug).\n  `GET /v1/portfolio/tenants` lists the tenants it may select. Read-only, with\n  a mandatory expiry. A tenant outside the key's portfolio answers **404**\n  (`error.details.code: \"TENANT_NOT_FOUND\"`), exactly as one that does not\n  exist.\n\nEvery successful (2xx) answer of a data operation carries `X-HS-Tenant` with\nthe id of the tenant whose data the body holds, for every credential; no error\ncarries it. A tenant API key or OAuth token may send `X-HS-Tenant` only with\nits own tenant's id; any other value is a **400**\n(`TENANT_SELECTOR_NOT_SUPPORTED`).\n\nEach operation below declares the scope it requires. A credential that\nauthenticates but lacks the scope is answered **403**\n(`error.details.code: \"INSUFFICIENT_SCOPE\"`), never 404: you are told what you\nare missing, not that the resource does not exist.\n\n## Errors\n\nEvery error has the same body:\n\n```json\n{ \"error\": { \"code\": \"forbidden\", \"message\": \"…\", \"request_id\": \"…\" } }\n```\n\nBranch on `code`, log `request_id`, show `message` to nobody but yourself.\n`request_id` is also the `X-Request-Id` response header, and it is what\nsupport will ask you for.\n\n## Rate limits\n\nEvery response that got past authentication carries the limit that is closest\nto being exhausted:\n\n- `RateLimit-Limit` — requests allowed in the window;\n- `RateLimit-Remaining` — requests left in the current window;\n- `RateLimit-Reset` — **seconds** until the window renews;\n- `RateLimit-Policy` — `<limit>;w=<window seconds>`.\n\nThree limits apply, each per one-minute window: per API key, per organisation\n(all of its keys together) and per service. The first two come from the licence\nof the organisation the key belongs to: a higher licence tier has more room, and\nan MSSP partner has more than a direct customer of the same tier. Read the\ncurrent limit from `RateLimit-Limit` and `RateLimit-Policy` rather than\nhard-coding it. When one is exhausted the answer is\n**429** with `error.code: \"rate_limited\"`, `Retry-After` (seconds) and\n`error.details.scope` (`key`, `tenant` or `service`) saying which. A\nportfolio key is limited per key (`portfolio_key`), per provider across all\nits portfolio keys (`portfolio_org`) and per service; once the selected tenant\nis known to be in its portfolio, the client tenant's own limit (`tenant`) and\nthe provider's share of it (`portfolio_tenant`) apply too. Your\norganisation's usage never counts against another's. Windows are fixed, so a\nclient can burst up to twice the limit across a window boundary: back off on\n`Retry-After` rather than pacing to the second. The limits are part of the\nservice, not of the frozen contract: they may be raised without notice.\n\n## Pagination, filtering and ordering\n\nEvery collection takes `page` and `per_page` (max 200) and answers with a\n`pagination` object carrying `total` and `total_pages`. Every collection\ntakes `sort` (an enum of the fields THAT collection can order by) and\n`order` (`asc`/`desc`, default `desc`). Filters are exact matches unless\nthe parameter says otherwise. A parameter or field with a known vocabulary lists\nit in `x-hs-known-values` (an OpenAPI extension, not a JSON Schema `enum`: the\nserver still accepts what it accepted before). Values retired from a parameter\nare listed in `x-hs-deprecated-values`, with the date until which the server is\ndocumented to accept them in `x-hs-deprecated-values-sunset`.\n\n## Contract changes\n\nCorrections and additions to the published contract, newest first. They ship\nwith the contract version (`info.version`) named in each entry. Detect a\ncapability by the operation, not by this string: the portfolio contract is\npresent when `GET /v1` lists `listPortfolioTenants`.\n\n- **2026-10-16 — addition: MSSP portfolio keys.** A third credential, the\n  portfolio key (`hsp_…`); the operation `GET /v1/portfolio/tenants`\n  (`listPortfolioTenants`, scope `portfolio:read`); the optional request\n  header `X-HS-Tenant` on every data operation, echoed on every 2xx answer of\n  them for every credential, with `Vary: X-HS-Tenant`;\n  `error.details.code` becomes contract (`TENANT_HEADER_INVALID`,\n  `TENANT_REQUIRED`, `TENANT_SELECTOR_NOT_SUPPORTED`, `TENANT_NOT_FOUND`,\n  `INSUFFICIENT_SCOPE`, `LICENCE_INACTIVE`), and every scope 403 now carries\n  `INSUFFICIENT_SCOPE`; three new 429 `details.scope` values\n  (`portfolio_key`, `portfolio_org`, `portfolio_tenant`). Nothing existing\n  was removed, renamed or re-statused.\n\n- **2026-10-16 — correction: alert `severity` is English.** `GET /v1/alerts`\n  and `GET /v1/alerts/{id}` returned `severity` as stored, in Spanish\n  (`critico`, `alto`, `medio`, `bajo`, `info`), while this document\n  promised `critical | high | medium | low`. They now return `critical`,\n  `high`, `medium`, `low` and `info` (`info` is added to the documented\n  values). **This changes what an integrator who adapted to the Spanish values\n  receives.** The `severity` filter accepts both the English values and the\n  Spanish ones; the Spanish ones are documented as accepted until\n  **2027-01-14** (90 days after this version), so switch to the English ones\n  before then. A value outside both lists is still matched exactly and matches\n  nothing. `GET /v1/risks`: the descriptions of `domain` and `status` named\n  values that do not exist; they now list the real ones (no value changed).","contact":{"name":"Hodeitek S.L.","url":"https://hodeishield.com"}},"servers":[{"url":"https://api.hodeishield.com"}],"tags":[{"name":"vendors"},{"name":"alerts"},{"name":"risks"},{"name":"compliance"},{"name":"evidence"},{"name":"endpoints"},{"name":"Portfolio"}],"paths":{"/v1/vendors":{"get":{"operationId":"listVendors","summary":"List third parties","description":"The tenant third-party inventory, newest first by default. Soft-deleted vendors are never returned.\n\nRequired scope: `supply_risk:read`. Published in `/v1` since 2026-09-20.","tags":["vendors"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: created_at, updated_at, name.","schema":{"default":"created_at","type":"string","enum":["created_at","updated_at","name"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"q","in":"query","required":false,"description":"Case-insensitive substring of the name or the domain.","schema":{"type":"string","minLength":1,"maxLength":120}},{"name":"category","in":"query","required":false,"description":"Exact category match.","schema":{"type":"string","minLength":1,"maxLength":120}},{"name":"active","in":"query","required":false,"description":"Filter by the operational flag.","schema":{"type":"string"}},{"name":"business_criticality","in":"query","required":false,"description":"Exact criticality match.","schema":{"type":"string","enum":["low","medium","high","critical"]}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (`hsp_…`); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Stable identifier of the vendor in this tenant."},"name":{"type":"string","description":"Display name."},"legal_name":{"description":"Registered legal name, when it differs.","type":["string","null"]},"domain":{"description":"Primary domain, lowercase, no scheme.","type":["string","null"]},"category":{"description":"Free-text category assigned by the tenant.","type":["string","null"]},"vendor_type":{"description":"Kind of third party (provider, product, …).","type":["string","null"]},"access_level":{"description":"Level of access the vendor has to the tenant systems.","type":["string","null"]},"business_criticality":{"description":"low | medium | high | critical, as set by the tenant.","type":["string","null"]},"data_sensitivity":{"description":"public | internal | confidential | restricted.","type":["string","null"]},"economic_impact":{"description":"Estimated economic impact of an outage, in the tenant currency.","type":["number","null"]},"active":{"type":"boolean","description":"Whether the vendor is operationally enabled."},"monitoring_status":{"description":"Continuous-monitoring state.","type":["string","null"]},"last_scan_at":{"description":"RFC 3339, UTC. Null if never scanned.","type":["string","null"]},"lei":{"description":"Legal Entity Identifier (ISO 17442), for DORA RoI.","type":["string","null"]},"hq_country":{"description":"Head-office country, ISO 3166-1 alpha-2.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."},"updated_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","name","legal_name","domain","category","vendor_type","access_level","business_criticality","data_sensitivity","economic_impact","active","monitoring_status","last_scan_at","lei","hq_country","created_at","updated_at"],"additionalProperties":false,"description":"A third party in the tenant inventory."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which). Re-authenticating does not help with the second.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist or is not in this key’s portfolio (`error.details.code` is `TENANT_NOT_FOUND`; the two cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["supply_risk:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["supply_risk:read"]}}},"/v1/vendors/{id}":{"get":{"operationId":"getVendor","summary":"Fetch one third party","description":"The same object `listVendors` returns, for a single vendor.\n\nRequired scope: `supply_risk:read`. Published in `/v1` since 2026-09-20.","tags":["vendors"],"parameters":[{"name":"id","in":"path","required":true,"description":"Vendor identifier.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (`hsp_…`); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Stable identifier of the vendor in this tenant."},"name":{"type":"string","description":"Display name."},"legal_name":{"description":"Registered legal name, when it differs.","type":["string","null"]},"domain":{"description":"Primary domain, lowercase, no scheme.","type":["string","null"]},"category":{"description":"Free-text category assigned by the tenant.","type":["string","null"]},"vendor_type":{"description":"Kind of third party (provider, product, …).","type":["string","null"]},"access_level":{"description":"Level of access the vendor has to the tenant systems.","type":["string","null"]},"business_criticality":{"description":"low | medium | high | critical, as set by the tenant.","type":["string","null"]},"data_sensitivity":{"description":"public | internal | confidential | restricted.","type":["string","null"]},"economic_impact":{"description":"Estimated economic impact of an outage, in the tenant currency.","type":["number","null"]},"active":{"type":"boolean","description":"Whether the vendor is operationally enabled."},"monitoring_status":{"description":"Continuous-monitoring state.","type":["string","null"]},"last_scan_at":{"description":"RFC 3339, UTC. Null if never scanned.","type":["string","null"]},"lei":{"description":"Legal Entity Identifier (ISO 17442), for DORA RoI.","type":["string","null"]},"hq_country":{"description":"Head-office country, ISO 3166-1 alpha-2.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."},"updated_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","name","legal_name","domain","category","vendor_type","access_level","business_criticality","data_sensitivity","economic_impact","active","monitoring_status","last_scan_at","lei","hq_country","created_at","updated_at"],"additionalProperties":false,"description":"A third party in the tenant inventory."}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which). Re-authenticating does not help with the second.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist or is not in this key’s portfolio (`error.details.code` is `TENANT_NOT_FOUND`; the two cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["supply_risk:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["supply_risk:read"]}}},"/v1/alerts":{"get":{"operationId":"listAlerts","summary":"List supply-chain alerts","description":"Alerts raised against the tenant vendors. Poll incrementally with `since` plus `order=asc`.\n\nRequired scope: `supply_risk:read`. Published in `/v1` since 2026-09-20.","tags":["alerts"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: created_at.","schema":{"default":"created_at","type":"string","enum":["created_at"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"status","in":"query","required":false,"description":"Filter by the derived status.","schema":{"type":"string","enum":["open","acknowledged","resolved"]}},{"name":"severity","in":"query","required":false,"description":"Exact severity match, in the vocabulary the response uses (critical | high | medium | low | info). The legacy Spanish values (critico, alto, medio, bajo, info) are still accepted and mean the same; they are documented as accepted until 2027-01-14, so move to the English ones.","schema":{"x-hs-known-values":["critical","high","medium","low","info"],"x-hs-deprecated-values":["critico","alto","medio","bajo"],"x-hs-deprecated-values-sunset":"2027-01-14","type":"string","minLength":1,"maxLength":40}},{"name":"vendor_id","in":"query","required":false,"description":"Only alerts about this vendor.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"since","in":"query","required":false,"description":"Only alerts created at or after this RFC 3339 instant.","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (`hsp_…`); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"vendor_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The vendor this alert is about (`/v1/vendors/{id}`)."},"type":{"type":"string","description":"Alert family, e.g. `breach`, `cve`, `rating_drop`."},"severity":{"description":"critical | high | medium | low | info, when classified. Open vocabulary: a new value is a compatible change.","x-hs-known-values":["critical","high","medium","low","info"],"type":["string","null"]},"title":{"type":"string"},"description":{"type":["string","null"]},"source_url":{"description":"Where the finding came from, when public.","type":["string","null"]},"economic_impact":{"type":["number","null"]},"status":{"type":"string","enum":["open","acknowledged","resolved"],"description":"Derived: resolved if closed, acknowledged if taken, otherwise open."},"acknowledged_at":{"description":"RFC 3339, UTC.","type":["string","null"]},"resolved_at":{"description":"RFC 3339, UTC.","type":["string","null"]},"resolution_reason":{"description":"Why it was closed, when it was.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","vendor_id","type","severity","title","description","source_url","economic_impact","status","acknowledged_at","resolved_at","resolution_reason","created_at"],"additionalProperties":false,"description":"A supply-chain alert raised against one vendor."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which). Re-authenticating does not help with the second.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist or is not in this key’s portfolio (`error.details.code` is `TENANT_NOT_FOUND`; the two cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["supply_risk:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["supply_risk:read"]}}},"/v1/alerts/{id}":{"get":{"operationId":"getAlert","summary":"Fetch one alert","description":"The same object `listAlerts` returns, for a single alert.\n\nRequired scope: `supply_risk:read`. Published in `/v1` since 2026-09-20.","tags":["alerts"],"parameters":[{"name":"id","in":"path","required":true,"description":"Alert identifier.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (`hsp_…`); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"vendor_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The vendor this alert is about (`/v1/vendors/{id}`)."},"type":{"type":"string","description":"Alert family, e.g. `breach`, `cve`, `rating_drop`."},"severity":{"description":"critical | high | medium | low | info, when classified. Open vocabulary: a new value is a compatible change.","x-hs-known-values":["critical","high","medium","low","info"],"type":["string","null"]},"title":{"type":"string"},"description":{"type":["string","null"]},"source_url":{"description":"Where the finding came from, when public.","type":["string","null"]},"economic_impact":{"type":["number","null"]},"status":{"type":"string","enum":["open","acknowledged","resolved"],"description":"Derived: resolved if closed, acknowledged if taken, otherwise open."},"acknowledged_at":{"description":"RFC 3339, UTC.","type":["string","null"]},"resolved_at":{"description":"RFC 3339, UTC.","type":["string","null"]},"resolution_reason":{"description":"Why it was closed, when it was.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","vendor_id","type","severity","title","description","source_url","economic_impact","status","acknowledged_at","resolved_at","resolution_reason","created_at"],"additionalProperties":false,"description":"A supply-chain alert raised against one vendor."}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which). Re-authenticating does not help with the second.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist or is not in this key’s portfolio (`error.details.code` is `TENANT_NOT_FOUND`; the two cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["supply_risk:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["supply_risk:read"]}}},"/v1/risks":{"get":{"operationId":"listRisks","summary":"List risk-register entries","description":"The tenant risk register, with inherent and residual figures.\n\nRequired scope: `supply_risk:read`. Published in `/v1` since 2026-09-20.","tags":["risks"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: created_at, updated_at, inherent_score, residual_score.","schema":{"default":"created_at","type":"string","enum":["created_at","updated_at","inherent_score","residual_score"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"status","in":"query","required":false,"description":"Exact status match.","schema":{"type":"string","minLength":1,"maxLength":24}},{"name":"domain","in":"query","required":false,"description":"Exact domain match.","schema":{"type":"string","minLength":1,"maxLength":20}},{"name":"vendor_id","in":"query","required":false,"description":"Only risks linked to this vendor.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"min_inherent_score","in":"query","required":false,"description":"Only risks whose inherent score is at least this.","schema":{"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (`hsp_…`); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"title":{"type":"string"},"description":{"type":["string","null"]},"domain":{"type":"string","description":"Risk domain: vendor | cyber | data | operational | compliance | concentration | strategic | legal | financial | reputational."},"status":{"type":"string","description":"Risk lifecycle status: identified | assessed | treatment_planned | treatment_implemented | closed."},"treatment":{"description":"mitigate | accept | transfer | avoid.","type":["string","null"]},"treatment_notes":{"type":["string","null"]},"threat_source":{"type":["string","null"]},"vulnerability":{"type":["string","null"]},"likelihood_inherent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"impact_inherent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"inherent_score":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"likelihood_residual":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"impact_residual":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"residual_score":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string","description":"manual | imported | derived."},"owner_user_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"User of this tenant who owns the risk."},"vendor_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The vendor this risk is about, when any."},"control_codes":{"type":"array","items":{"type":"string"},"description":"Framework control codes linked to the risk."},"review_date":{"description":"Calendar date, `YYYY-MM-DD`.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."},"updated_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","title","description","domain","status","treatment","treatment_notes","threat_source","vulnerability","likelihood_inherent","impact_inherent","inherent_score","likelihood_residual","impact_residual","residual_score","source","owner_user_id","vendor_id","control_codes","review_date","created_at","updated_at"],"additionalProperties":false,"description":"An entry of the tenant risk register."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which). Re-authenticating does not help with the second.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist or is not in this key’s portfolio (`error.details.code` is `TENANT_NOT_FOUND`; the two cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["supply_risk:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["supply_risk:read"]}}},"/v1/risks/{id}":{"get":{"operationId":"getRisk","summary":"Fetch one risk-register entry","description":"The same object `listRisks` returns, for a single entry.\n\nRequired scope: `supply_risk:read`. Published in `/v1` since 2026-09-20.","tags":["risks"],"parameters":[{"name":"id","in":"path","required":true,"description":"Risk identifier.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (`hsp_…`); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"title":{"type":"string"},"description":{"type":["string","null"]},"domain":{"type":"string","description":"Risk domain: vendor | cyber | data | operational | compliance | concentration | strategic | legal | financial | reputational."},"status":{"type":"string","description":"Risk lifecycle status: identified | assessed | treatment_planned | treatment_implemented | closed."},"treatment":{"description":"mitigate | accept | transfer | avoid.","type":["string","null"]},"treatment_notes":{"type":["string","null"]},"threat_source":{"type":["string","null"]},"vulnerability":{"type":["string","null"]},"likelihood_inherent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"impact_inherent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"inherent_score":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"likelihood_residual":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"impact_residual":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"residual_score":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string","description":"manual | imported | derived."},"owner_user_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"User of this tenant who owns the risk."},"vendor_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The vendor this risk is about, when any."},"control_codes":{"type":"array","items":{"type":"string"},"description":"Framework control codes linked to the risk."},"review_date":{"description":"Calendar date, `YYYY-MM-DD`.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."},"updated_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","title","description","domain","status","treatment","treatment_notes","threat_source","vulnerability","likelihood_inherent","impact_inherent","inherent_score","likelihood_residual","impact_residual","residual_score","source","owner_user_id","vendor_id","control_codes","review_date","created_at","updated_at"],"additionalProperties":false,"description":"An entry of the tenant risk register."}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which). Re-authenticating does not help with the second.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist or is not in this key’s portfolio (`error.details.code` is `TENANT_NOT_FOUND`; the two cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["supply_risk:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["supply_risk:read"]}}},"/v1/compliance/controls":{"get":{"operationId":"listComplianceControls","summary":"List control status for a framework","description":"Per-control status of one framework. Requires the read scope OF THAT FRAMEWORK: `compliance.<framework>:read`.\n\nRequired scope: `compliance.<framework>:read`. Published in `/v1` since 2026-09-20.","tags":["compliance"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: control_code, last_evaluated_at.","schema":{"default":"control_code","type":"string","enum":["control_code","last_evaluated_at"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"framework","in":"query","required":true,"description":"Framework slug. One of: nis2, ens, iso27001, dora, gdpr, soc2, iso42001, nistcsf, pcidss, euaiact, hipaa, cmmc, cyberessentials, uaeia, sama, saudiecc, ndpa.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Exact status match.","schema":{"type":"string","minLength":1,"maxLength":20}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (`hsp_…`); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"framework":{"type":"string","description":"Framework slug the control belongs to."},"control_code":{"type":"string","description":"Control identifier inside the framework."},"status":{"type":"string","description":"missing | partial | covered, as evaluated by the platform."},"evidence_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Evidence items currently linked to the control."},"last_evaluated_at":{"description":"RFC 3339, UTC.","type":["string","null"]}},"required":["framework","control_code","status","evidence_count","last_evaluated_at"],"additionalProperties":false,"description":"The tenant status of one framework control."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which). Re-authenticating does not help with the second.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist or is not in this key’s portfolio (`error.details.code` is `TENANT_NOT_FOUND`; the two cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":[]},{"portfolioKey":[]}],"x-hs-scope":{"template":"compliance.<framework>:read"}}},"/v1/compliance/frameworks/{framework}":{"get":{"operationId":"getFrameworkPosture","summary":"Framework posture summary","description":"Counts of evaluated controls by status for one framework, for a dashboard tile. Requires `compliance.<framework>:read`.\n\nRequired scope: `compliance.<framework>:read`. Published in `/v1` since 2026-09-20.","tags":["compliance"],"parameters":[{"name":"framework","in":"path","required":true,"description":"Framework slug. One of: nis2, ens, iso27001, dora, gdpr, soc2, iso42001, nistcsf, pcidss, euaiact, hipaa, cmmc, cyberessentials, uaeia, sama, saudiecc, ndpa.","schema":{"type":"string"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (`hsp_…`); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"framework":{"type":"string"},"controls_total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Controls the platform has evaluated."},"by_status":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"description":"Control count per status. Keys are whatever statuses exist; may grow."},"evidence_total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Sum of the evidence linked across the evaluated controls."},"last_evaluated_at":{"description":"Most recent control evaluation, RFC 3339 UTC. Null if never evaluated.","type":["string","null"]}},"required":["framework","controls_total","by_status","evidence_total","last_evaluated_at"],"additionalProperties":false,"description":"Posture summary for one framework."}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which). Re-authenticating does not help with the second.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist or is not in this key’s portfolio (`error.details.code` is `TENANT_NOT_FOUND`; the two cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":[]},{"portfolioKey":[]}],"x-hs-scope":{"template":"compliance.<framework>:read"}}},"/v1/evidence":{"get":{"operationId":"listEvidence","summary":"List security evidence","description":"Evidence held for the tenant. Use `expiring_before` plus `sort=valid_until&order=asc` for a renewal queue.\n\nRequired scope: `evidence:read`. Published in `/v1` since 2026-09-20.","tags":["evidence"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: created_at, valid_until.","schema":{"default":"created_at","type":"string","enum":["created_at","valid_until"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"evidence_type","in":"query","required":false,"description":"Exact type match.","schema":{"type":"string","minLength":1,"maxLength":50}},{"name":"source_type","in":"query","required":false,"description":"Exact producer match.","schema":{"type":"string","minLength":1,"maxLength":50}},{"name":"vendor_id","in":"query","required":false,"description":"Only evidence about this vendor.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"expiring_before","in":"query","required":false,"description":"Only evidence with a `valid_until` strictly before this `YYYY-MM-DD`.","schema":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (`hsp_…`); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"evidence_type":{"type":"string","description":"What kind of evidence this is."},"source_type":{"type":"string","description":"Which subsystem produced it."},"source_id":{"type":"string","description":"Its identifier inside that subsystem."},"title":{"type":"string"},"description":{"type":["string","null"]},"vendor_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The vendor it is about, when any."},"asset_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The asset it is about, when any."},"auto_generated":{"type":"boolean","description":"False when a person uploaded it."},"valid_until":{"description":"Calendar date, `YYYY-MM-DD`. Null = no expiry.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","evidence_type","source_type","source_id","title","description","vendor_id","asset_id","auto_generated","valid_until","created_at"],"additionalProperties":false,"description":"One item of security evidence."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which). Re-authenticating does not help with the second.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist or is not in this key’s portfolio (`error.details.code` is `TENANT_NOT_FOUND`; the two cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["evidence:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["evidence:read"]}}},"/v1/evidence/{id}":{"get":{"operationId":"getEvidence","summary":"Fetch one evidence item","description":"The same object `listEvidence` returns, for a single item.\n\nRequired scope: `evidence:read`. Published in `/v1` since 2026-09-20.","tags":["evidence"],"parameters":[{"name":"id","in":"path","required":true,"description":"Evidence identifier.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (`hsp_…`); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"evidence_type":{"type":"string","description":"What kind of evidence this is."},"source_type":{"type":"string","description":"Which subsystem produced it."},"source_id":{"type":"string","description":"Its identifier inside that subsystem."},"title":{"type":"string"},"description":{"type":["string","null"]},"vendor_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The vendor it is about, when any."},"asset_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The asset it is about, when any."},"auto_generated":{"type":"boolean","description":"False when a person uploaded it."},"valid_until":{"description":"Calendar date, `YYYY-MM-DD`. Null = no expiry.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","evidence_type","source_type","source_id","title","description","vendor_id","asset_id","auto_generated","valid_until","created_at"],"additionalProperties":false,"description":"One item of security evidence."}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which). Re-authenticating does not help with the second.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist or is not in this key’s portfolio (`error.details.code` is `TENANT_NOT_FOUND`; the two cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["evidence:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["evidence:read"]}}},"/v1/endpoints":{"get":{"operationId":"listEndpoints","summary":"List enrolled endpoint agents","description":"The endpoint agents enrolled in this tenant. `silent_since` selects the ones that have gone quiet, including those that never reported.\n\nRequired scope: `endpoints:read`. Published in `/v1` since 2026-09-20.","tags":["endpoints"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: enrolled_at, last_seen_at, producer.","schema":{"default":"enrolled_at","type":"string","enum":["enrolled_at","last_seen_at","producer"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"status","in":"query","required":false,"description":"Exact status match.","schema":{"type":"string","enum":["active","revoked"]}},{"name":"silent_since","in":"query","required":false,"description":"Agents last seen before this RFC 3339 instant, or never seen at all.","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (`hsp_…`); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"producer":{"type":"string","description":"The agent name, unique among the active ones of the tenant."},"producer_kind":{"type":"string","description":"What kind of producer it is."},"status":{"type":"string","description":"active | revoked."},"signature_alg":{"type":"string","description":"Algorithm this enrollment signs with."},"agent_version":{"type":["string","null"]},"hostname":{"description":"Last hostname the agent reported.","type":["string","null"]},"enrolled_at":{"type":"string","description":"RFC 3339, UTC."},"last_seen_at":{"description":"RFC 3339, UTC. Null until the first envelope.","type":["string","null"]},"revoked_at":{"description":"RFC 3339, UTC.","type":["string","null"]}},"required":["id","producer","producer_kind","status","signature_alg","agent_version","hostname","enrolled_at","last_seen_at","revoked_at"],"additionalProperties":false,"description":"An endpoint agent enrolled in this tenant."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which). Re-authenticating does not help with the second.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist or is not in this key’s portfolio (`error.details.code` is `TENANT_NOT_FOUND`; the two cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["endpoints:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["endpoints:read"]}}},"/v1/portfolio/tenants":{"get":{"operationId":"listPortfolioTenants","summary":"List the client tenants of an MSSP portfolio","description":"Every tenant the presented PORTFOLIO key may select with `X-HS-Tenant`: the MSSP’s own tenants (its internal one included) and every tenant of its active client organisations, active or not, licensed or not, narrowed to the key’s client subset when it has one. Membership is evaluated live on every request. Only a portfolio key (`hsp_…`) can call this operation; this operation never takes `X-HS-Tenant`.\n\nRequired scope: `portfolio:read`. Published in `/v1` since 2026-10-16.","tags":["Portfolio"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: name, slug.","schema":{"default":"name","type":"string","enum":["name","slug"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Stable identifier (lowercase). The ONLY value `X-HS-Tenant` accepts."},"name":{"type":"string","description":"Display name. Untrusted text."},"slug":{"type":"string","description":"Short name, unique across the platform. A client may resolve a slug to an `id` from this list; the server never accepts a slug as a selector."},"organization":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"description":"The organisation the tenant belongs to: the MSSP itself for the tenants it holds directly (including its internal one), or the client organisation."},"internal":{"type":"boolean","description":"True only for the MSSP’s own internal tenant."},"active":{"type":"boolean","description":"Whether the tenant is enabled. A deactivated tenant is listed but cannot be read."},"licence_status":{"type":"string","description":"Open vocabulary: `in_force` (licence in force), `grace` (grace period: reads are served), `inactive` (none, suspended, revoked or expired: data operations answer 403 `LICENCE_INACTIVE`). Treat an unknown value as \"may not be readable\". A tenant is readable when `active` is true and `licence_status` is not `inactive`.","x-hs-known-values":["in_force","grace","inactive"]}},"required":["id","name","slug","organization","internal","active","licence_status"],"additionalProperties":false,"description":"A client tenant an MSSP portfolio key may select."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which). Re-authenticating does not help with the second.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"portfolioKey":[]}],"x-hs-scope":{"scopes":["portfolio:read"]}}}},"components":{"schemas":{"Error":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_request","unauthorized","forbidden","not_found","method_not_allowed","rate_limited","internal_error","service_unavailable"],"description":"Closed vocabulary; new members may be added (see Versioning)."},"message":{"type":"string","description":"For a human reading a log. Not stable; do not parse it."},"request_id":{"type":"string","description":"Also the `X-Request-Id` response header."},"details":{"type":"object","additionalProperties":true,"description":"Diagnostic, except `code` and the keys the operation’s error descriptions name, which are contract.","properties":{"code":{"type":"string","description":"OPEN vocabulary (a value keeps its meaning and its HTTP status; new values may be added): `TENANT_HEADER_INVALID`, `TENANT_REQUIRED`, `TENANT_SELECTOR_NOT_SUPPORTED` (400), `INSUFFICIENT_SCOPE`, `LICENCE_INACTIVE` (403), `TENANT_NOT_FOUND` (404).","x-hs-known-values":["TENANT_HEADER_INVALID","TENANT_REQUIRED","TENANT_SELECTOR_NOT_SUPPORTED","INSUFFICIENT_SCOPE","LICENCE_INACTIVE","TENANT_NOT_FOUND"]}}}}}}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"A tenant API key, created in the console under Settings → API keys with the minimum scopes it needs."},"portfolioKey":{"type":"http","scheme":"bearer","description":"An MSSP portfolio key (`hsp_…`), created by an organisation administrator of an active managed security service provider in the console’s MSSP area (API keys). It lists the provider’s client tenants (`portfolio:read`) and reads ONE of them per request, selected with `X-HS-Tenant`, with the same data scopes a tenant API key uses. Read-only; mandatory expiry (default 90 days, at most 365); optional client subset and source IP ranges. Refused with 401 everywhere but `/v1`."},"oauth2":{"type":"oauth2","description":"A USER access token (`hs_at_…`) issued by the HodeiShield console, the OAuth 2.1 authorization server at `https://app.hodeishield.com/api/auth` (metadata: `/.well-known/oauth-authorization-server` on its origin). Authorization code with PKCE (S256, mandatory) for applications with a browser; the RFC 8628 device authorization grant (`https://app.hodeishield.com/api/auth/device/code`) for those without one. Every token is bound to ONE user and ONE tenant, chosen by the user on the consent screen, and carries read scopes only; the tenant is re-checked against what the user can see on every request. Public clients register themselves (RFC 7591) at `/oauth2/register`; the HodeiShield CLI is pre-registered as `hodeishield-cli`. Revocation: RFC 7009 at `/oauth2/revoke`, or by the user in the console under Account → Application access.","flows":{"authorizationCode":{"authorizationUrl":"https://app.hodeishield.com/api/auth/oauth2/authorize","tokenUrl":"https://app.hodeishield.com/api/auth/oauth2/token","refreshUrl":"https://app.hodeishield.com/api/auth/oauth2/token","scopes":{"supply_risk:read":"Read supply_risk data of the tenant the token is bound to.","compliance.nis2:read":"Read compliance.nis2 data of the tenant the token is bound to.","compliance.ens:read":"Read compliance.ens data of the tenant the token is bound to.","compliance.iso27001:read":"Read compliance.iso27001 data of the tenant the token is bound to.","compliance.dora:read":"Read compliance.dora data of the tenant the token is bound to.","compliance.gdpr:read":"Read compliance.gdpr data of the tenant the token is bound to.","compliance.soc2:read":"Read compliance.soc2 data of the tenant the token is bound to.","compliance.iso42001:read":"Read compliance.iso42001 data of the tenant the token is bound to.","compliance.nistcsf:read":"Read compliance.nistcsf data of the tenant the token is bound to.","compliance.pcidss:read":"Read compliance.pcidss data of the tenant the token is bound to.","compliance.euaiact:read":"Read compliance.euaiact data of the tenant the token is bound to.","compliance.hipaa:read":"Read compliance.hipaa data of the tenant the token is bound to.","compliance.cmmc:read":"Read compliance.cmmc data of the tenant the token is bound to.","compliance.cyberessentials:read":"Read compliance.cyberessentials data of the tenant the token is bound to.","compliance.uaeia:read":"Read compliance.uaeia data of the tenant the token is bound to.","compliance.sama:read":"Read compliance.sama data of the tenant the token is bound to.","compliance.saudiecc:read":"Read compliance.saudiecc data of the tenant the token is bound to.","compliance.ndpa:read":"Read compliance.ndpa data of the tenant the token is bound to.","radar:read":"Read radar data of the tenant the token is bound to.","connectors:read":"Read connectors data of the tenant the token is bound to.","endpoints:read":"Read endpoints data of the tenant the token is bound to.","hodeiai:read":"Read hodeiai data of the tenant the token is bound to.","virtual_ciso:read":"Read virtual_ciso data of the tenant the token is bound to.","simulator:read":"Read simulator data of the tenant the token is bound to.","evidence:read":"Read evidence data of the tenant the token is bound to.","reports:read":"Read reports data of the tenant the token is bound to.","ai_governance:read":"Read ai_governance data of the tenant the token is bound to.","management:read":"Read management data of the tenant the token is bound to.","offline_access":"Issue a refresh token (30 days, rotated on every use)."}}}}}},"security":[{"bearerAuth":[]},{"oauth2":[]},{"portfolioKey":[]}]}
\ No newline at end of file
diff --git a/xtask/src/main.rs b/xtask/src/main.rs
index a6304ea..b91e5c5 100644
--- a/xtask/src/main.rs
+++ b/xtask/src/main.rs
@@ -13,7 +13,8 @@
 //!
 //! Rules it applies:
 //! - Response objects become structs that ignore unknown fields, so a newer `/v1` (which only adds)
-//!   does not break an older client.
+//!   does not break an older client. An object declared open (`additionalProperties: true`) stays
+//!   a JSON map instead, so none of its keys is lost.
 //! - Enums in responses stay `String`: the contract says vocabularies may grow.
 //! - Enums in query parameters become Rust enums: the client only sends what the document lists.
 //! - Two schemas with the same shape become one type; two different shapes wanting the same name
@@ -31,7 +32,7 @@ use std::process::{Command, ExitCode, Stdio};
 const SPEC: &str = "openapi/v1.json";
 const OUT: &str = "crates/hodeishield-api/src/generated.rs";
 /// SHA-256 of `openapi/v1.json`. Updating the document means updating this and `openapi/README.md`.
-const EXPECTED_SHA256: &str = "103e86f38f7b3eff45a0f764c8142b4bdd2e8d576385b1b4ccf588cbf0518fb3";
+const EXPECTED_SHA256: &str = "1321a417aba28e7b60dbc28a35ce2dc3711d8973b985107f7701d70ff3be6b0d";
 
 /// Type names that the default naming rules would get wrong, keyed by the schema's location.
 const RENAMES: &[(&str, &str)] = &[
@@ -176,6 +177,10 @@ struct Param {
     is_enum: bool,
     /// The values `x-hs-known-values` lists, in document order; empty without the extension.
     known_values: Vec<String>,
+    /// The values `x-hs-deprecated-values` lists, in document order; empty without the extension.
+    deprecated_values: Vec<String>,
+    /// `x-hs-deprecated-values-sunset`: the last day the deprecated values are accepted.
+    sunset: Option<String>,
     doc: Option<String>,
 }
 
@@ -188,6 +193,8 @@ struct OperationDef {
     path_params: Vec<Param>,
     query_params: Vec<Param>,
     response: String,
+    /// Whether the operation takes the `X-HS-Tenant` header that selects a client tenant.
+    tenant_scoped: bool,
 }
 
 struct Generator<'a> {
@@ -378,6 +385,7 @@ impl<'a> Generator<'a> {
 
         let mut path_params = Vec::new();
         let mut query_params = Vec::new();
+        let mut tenant_scoped = false;
         for param in operation
             .get("parameters")
             .and_then(Value::as_array)
@@ -389,6 +397,12 @@ impl<'a> Generator<'a> {
                 .and_then(Value::as_str)
                 .ok_or_else(|| format!("{id}: parameter without name"))?;
             let location = param.get("in").and_then(Value::as_str).unwrap_or_default();
+            // The tenant selection is not an argument of the generated function: the client adds it
+            // to every request of an operation that takes it (see `ClientBuilder::tenant`).
+            if location == "header" && name.eq_ignore_ascii_case("X-HS-Tenant") {
+                tenant_scoped = true;
+                continue;
+            }
             let required = param
                 .get("required")
                 .and_then(Value::as_bool)
@@ -414,6 +428,8 @@ impl<'a> Generator<'a> {
                 required,
                 is_enum,
                 known_values: known_values(&id, name, param)?,
+                deprecated_values: deprecated_values(&id, name, param)?,
+                sunset: sunset(&id, name, param)?,
                 doc: param
                     .get("description")
                     .and_then(Value::as_str)
@@ -448,6 +464,7 @@ impl<'a> Generator<'a> {
             path_params,
             query_params,
             response,
+            tenant_scoped,
         });
         Ok(())
     }
@@ -514,6 +531,11 @@ impl<'a> Generator<'a> {
     }
 
     fn object_type(&mut self, schema: &Value, hint: &str, location: &str) -> Result<String> {
+        // An object declared open keeps every key it is sent: a struct would drop the ones it does
+        // not list. Its listed properties are documented, not typed.
+        if schema.get("additionalProperties") == Some(&Value::Bool(true)) {
+            return Ok("serde_json::Map<String, serde_json::Value>".to_owned());
+        }
         let Some(properties) = schema.get("properties").and_then(Value::as_object) else {
             return match schema.get("additionalProperties") {
                 Some(additional @ Value::Object(_)) => {
@@ -756,9 +778,27 @@ impl<'a> Generator<'a> {
                     format!("({:?}, &[{}])", p.json_name, values.join(", "))
                 })
                 .collect();
+            let deprecated: Vec<String> = op
+                .query_params
+                .iter()
+                .filter(|p| !p.deprecated_values.is_empty())
+                .map(|p| {
+                    let values: Vec<String> = p
+                        .deprecated_values
+                        .iter()
+                        .map(|v| format!("{v:?}"))
+                        .collect();
+                    format!(
+                        "crate::DeprecatedValues {{ param: {:?}, values: &[{}], sunset: {:?} }}",
+                        p.json_name,
+                        values.join(", "),
+                        p.sunset
+                    )
+                })
+                .collect();
             let _ = writeln!(
                 out,
-                "    /// `GET {}`: {}.\n    pub const {}: Operation = Operation {{ id: {:?}, method: \"GET\", path: {:?}, summary: {:?}, scopes: &[{}], known_values: &[{}], tenant_scoped: {} }};\n",
+                "    /// `GET {}`: {}.\n    pub const {}: Operation = Operation {{ id: {:?}, method: \"GET\", path: {:?}, summary: {:?}, scopes: &[{}], known_values: &[{}], deprecated_values: &[{}], tenant_scoped: {} }};\n",
                 op.path,
                 op.summary,
                 screaming(&op.id),
@@ -767,9 +807,8 @@ impl<'a> Generator<'a> {
                 op.summary,
                 scopes.join(", "),
                 known.join(", "),
-                // A client tenant is selected on the data operations only; anything under the
-                // portfolio path (the tenant listing) is outside the selection.
-                !op.path.starts_with("/v1/portfolio/")
+                deprecated.join(", "),
+                op.tenant_scoped
             );
         }
         let all: Vec<String> = self.operations.iter().map(|op| screaming(&op.id)).collect();
@@ -835,10 +874,19 @@ fn render_doc(out: &mut String, doc: Option<&str>, indent: &str) {
     }
 }
 
-/// The vocabulary `x-hs-known-values` publishes for a query parameter, in document order. The
-/// extension is optional; when present it must be an array of strings, anything else is an error.
-fn known_values(operation: &str, name: &str, param: &Value) -> Result<Vec<String>> {
-    let Some(list) = param.get("x-hs-known-values") else {
+/// The extension `key` of a parameter: on its `schema`, where the document puts it, or else on the
+/// parameter object itself.
+fn extension<'v>(param: &'v Value, key: &str) -> Option<&'v Value> {
+    param
+        .get("schema")
+        .and_then(|schema| schema.get(key))
+        .or_else(|| param.get(key))
+}
+
+/// The extension `key` of a parameter as a list of strings, in document order; empty when it is
+/// absent. When present it must be an array of strings, anything else is an error.
+fn string_list(operation: &str, name: &str, param: &Value, key: &str) -> Result<Vec<String>> {
+    let Some(list) = extension(param, key) else {
         return Ok(Vec::new());
     };
     list.as_array()
@@ -848,7 +896,43 @@ fn known_values(operation: &str, name: &str, param: &Value) -> Result<Vec<String
                 .map(|v| v.as_str().map(str::to_owned))
                 .collect::<Option<Vec<_>>>()
         })
-        .ok_or_else(|| format!("{operation}.{name}: x-hs-known-values must be an array of strings"))
+        .ok_or_else(|| format!("{operation}.{name}: {key} must be an array of strings"))
+}
+
+/// The vocabulary `x-hs-known-values` publishes for a query parameter, in document order.
+fn known_values(operation: &str, name: &str, param: &Value) -> Result<Vec<String>> {
+    string_list(operation, name, param, "x-hs-known-values")
+}
+
+/// The values `x-hs-deprecated-values` lists for a query parameter, in document order: still
+/// accepted by the API, but on their way out.
+fn deprecated_values(operation: &str, name: &str, param: &Value) -> Result<Vec<String>> {
+    string_list(operation, name, param, "x-hs-deprecated-values")
+}
+
+/// `x-hs-deprecated-values-sunset`: the last day the deprecated values are accepted. Optional; when
+/// present it must be a `YYYY-MM-DD` date and the parameter must list deprecated values.
+fn sunset(operation: &str, name: &str, param: &Value) -> Result<Option<String>> {
+    let key = "x-hs-deprecated-values-sunset";
+    let Some(value) = extension(param, key) else {
+        return Ok(None);
+    };
+    let date = value
+        .as_str()
+        .filter(|date| {
+            date.len() == 10
+                && date.bytes().enumerate().all(|(i, b)| match i {
+                    4 | 7 => b == b'-',
+                    _ => b.is_ascii_digit(),
+                })
+        })
+        .ok_or_else(|| format!("{operation}.{name}: {key} must be a YYYY-MM-DD date"))?;
+    if deprecated_values(operation, name, param)?.is_empty() {
+        return Err(format!(
+            "{operation}.{name}: {key} without x-hs-deprecated-values"
+        ));
+    }
+    Ok(Some(date.to_owned()))
 }
 
 fn operation_id(operation: &Value) -> Result<&str> {
@@ -1001,6 +1085,17 @@ mod tests {
         if let Some(extension) = extension {
             severity["x-hs-known-values"] = extension;
         }
+        document_with(severity, &[])
+    }
+
+    /// The same document with the `severity` parameter given whole, and `headers` added after the
+    /// query parameters.
+    fn document_with(severity: Value, headers: &[Value]) -> Value {
+        let mut parameters = vec![
+            severity,
+            serde_json::json!({"name": "page", "in": "query", "schema": {"type": "string"}}),
+        ];
+        parameters.extend(headers.iter().cloned());
         serde_json::json!({
             "info": {"version": "test"},
             "servers": [{"url": "https://api.example.test"}],
@@ -1009,7 +1104,7 @@ mod tests {
                 "operationId": "listThings",
                 "summary": "List things",
                 "x-hs-scope": {"scopes": ["things:read"]},
-                "parameters": [severity, {"name": "page", "in": "query", "schema": {"type": "string"}}],
+                "parameters": parameters,
                 "responses": {"200": {"content": {"application/json": {"schema": {
                     "type": "object",
                     "properties": {"ok": {"type": "boolean"}},
@@ -1020,12 +1115,24 @@ mod tests {
     }
 
     fn generate(extension: Option<Value>) -> Result<String> {
-        let spec = document(extension);
-        Generator::new(&spec)
+        generate_from(&document(extension))
+    }
+
+    fn generate_from(spec: &Value) -> Result<String> {
+        Generator::new(spec)
             .run()
             .map(|out| out.split_whitespace().collect::<Vec<_>>().join(" "))
     }
 
+    /// A `severity` parameter whose schema carries `extensions`, as the published document does.
+    fn severity_schema(extensions: Value) -> Value {
+        let mut schema = serde_json::json!({"type": "string"});
+        for (key, value) in extensions.as_object().expect("object") {
+            schema[key] = value.clone();
+        }
+        serde_json::json!({"name": "severity", "in": "query", "schema": schema})
+    }
+
     #[test]
     fn known_values_are_emitted_in_document_order() {
         let out =
@@ -1064,4 +1171,159 @@ mod tests {
             );
         }
     }
+
+    #[test]
+    fn known_values_are_read_from_the_parameter_schema() {
+        let spec = document_with(
+            severity_schema(serde_json::json!({"x-hs-known-values": ["critical", "high"]})),
+            &[],
+        );
+        let out = generate_from(&spec).expect("generates");
+        assert!(
+            out.contains(r#"known_values: &[("severity", &["critical", "high"])]"#),
+            "{out}"
+        );
+        let spec = document_with(
+            severity_schema(serde_json::json!({"x-hs-known-values": "critical"})),
+            &[],
+        );
+        assert_eq!(
+            generate_from(&spec).expect_err("malformed"),
+            "listThings.severity: x-hs-known-values must be an array of strings"
+        );
+    }
+
+    #[test]
+    fn deprecated_values_and_their_sunset_are_emitted_in_document_order() {
+        let spec = document_with(
+            severity_schema(serde_json::json!({
+                "x-hs-known-values": ["critical", "high"],
+                "x-hs-deprecated-values": ["critico", "alto"],
+                "x-hs-deprecated-values-sunset": "2027-01-14"
+            })),
+            &[],
+        );
+        let out = generate_from(&spec).expect("generates");
+        assert!(
+            out.contains(concat!(
+                r#"deprecated_values: &[crate::DeprecatedValues { param: "severity", "#,
+                r#"values: &["critico", "alto"], sunset: Some("2027-01-14") }]"#
+            )),
+            "{out}"
+        );
+        let spec = document_with(
+            severity_schema(serde_json::json!({"x-hs-deprecated-values": ["alto"]})),
+            &[],
+        );
+        let out = generate_from(&spec).expect("generates");
+        assert!(out.contains("values: &[\"alto\"], sunset: None"), "{out}");
+    }
+
+    #[test]
+    fn a_parameter_without_deprecated_values_has_none() {
+        let out = generate(Some(serde_json::json!(["critical"]))).expect("generates");
+        assert!(out.contains("deprecated_values: &[]"), "{out}");
+        let spec = document_with(
+            severity_schema(serde_json::json!({"x-hs-deprecated-values": []})),
+            &[],
+        );
+        let out = generate_from(&spec).expect("generates");
+        assert!(out.contains("deprecated_values: &[]"), "{out}");
+    }
+
+    #[test]
+    fn malformed_deprecated_values_are_a_generator_error() {
+        for (extensions, expected) in [
+            (
+                serde_json::json!({"x-hs-deprecated-values": "alto"}),
+                "listThings.severity: x-hs-deprecated-values must be an array of strings",
+            ),
+            (
+                serde_json::json!({"x-hs-deprecated-values": ["alto", 1]}),
+                "listThings.severity: x-hs-deprecated-values must be an array of strings",
+            ),
+            (
+                serde_json::json!({
+                    "x-hs-deprecated-values": ["alto"],
+                    "x-hs-deprecated-values-sunset": "14/01/2027"
+                }),
+                "listThings.severity: x-hs-deprecated-values-sunset must be a YYYY-MM-DD date",
+            ),
+            (
+                serde_json::json!({
+                    "x-hs-deprecated-values": ["alto"],
+                    "x-hs-deprecated-values-sunset": 20_270_114
+                }),
+                "listThings.severity: x-hs-deprecated-values-sunset must be a YYYY-MM-DD date",
+            ),
+            (
+                serde_json::json!({"x-hs-deprecated-values-sunset": "2027-01-14"}),
+                "listThings.severity: x-hs-deprecated-values-sunset without \
+                 x-hs-deprecated-values",
+            ),
+            (
+                serde_json::json!({
+                    "x-hs-deprecated-values": [],
+                    "x-hs-deprecated-values-sunset": "2027-01-14"
+                }),
+                "listThings.severity: x-hs-deprecated-values-sunset without \
+                 x-hs-deprecated-values",
+            ),
+        ] {
+            let spec = document_with(severity_schema(extensions.clone()), &[]);
+            let err = generate_from(&spec).expect_err("malformed");
+            assert_eq!(err, expected, "{extensions}");
+        }
+    }
+
+    #[test]
+    fn the_tenant_header_marks_the_operation_tenant_scoped() {
+        let severity =
+            || serde_json::json!({"name": "severity", "in": "query", "schema": {"type": "string"}});
+        for name in ["X-HS-Tenant", "x-hs-tenant"] {
+            let header = serde_json::json!({
+                "name": name, "in": "header", "required": false,
+                "schema": {"type": "string", "format": "uuid"}
+            });
+            let out = generate_from(&document_with(severity(), &[header])).expect("generates");
+            assert!(out.contains("tenant_scoped: true"), "{out}");
+            // The header is not an argument of the generated function.
+            assert!(!out.to_lowercase().contains("x_hs_tenant"), "{out}");
+        }
+        let out = generate_from(&document_with(severity(), &[])).expect("generates");
+        assert!(out.contains("tenant_scoped: false"), "{out}");
+    }
+
+    #[test]
+    fn an_open_object_stays_a_map_even_when_it_lists_properties() {
+        let mut spec = document(None);
+        let response = "/paths/~1v1~1things/get/responses/200/content/application~1json/schema";
+        let properties = &mut spec.pointer_mut(response).expect("response schema")["properties"];
+        properties["details"] = serde_json::json!({
+            "type": "object",
+            "additionalProperties": true,
+            "properties": {"code": {"type": "string"}}
+        });
+        let out = generate_from(&spec).expect("generates");
+        assert!(
+            out.contains("pub details: Option<serde_json::Map<String, serde_json::Value>>"),
+            "{out}"
+        );
+        assert!(!out.contains("pub struct Details"), "{out}");
+    }
+
+    #[test]
+    fn any_other_header_parameter_is_a_generator_error() {
+        let header = serde_json::json!({
+            "name": "X-Other", "in": "header", "schema": {"type": "string"}
+        });
+        let spec = document_with(
+            serde_json::json!({"name": "severity", "in": "query", "schema": {"type": "string"}}),
+            &[header],
+        );
+        assert_eq!(
+            generate_from(&spec).expect_err("unsupported"),
+            "listThings.X-Other: parameters in `header` are not supported"
+        );
+    }
 }

From 2df390acb2de3760e97f194f1b924335dc41da21 Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Sun, 11 Oct 2026 14:46:22 +0200
Subject: [PATCH 56/57] Prepare 0.4.0: version and changelog

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 CHANGELOG.md | 5 ++++-
 Cargo.lock   | 6 +++---
 Cargo.toml   | 2 +-
 3 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2847695..dc2746d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,8 @@ commands, `--json` output and exit codes. Each release's notes start with its se
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-12
+
 ### Added
 
 - Each release now includes a Windows on Arm build, `hodeishield-<version>-aarch64-pc-windows-msvc.zip`.
@@ -210,7 +212,8 @@ commands, `--json` output and exit codes. Each release's notes start with its se
 - Profiles (`config`), shell completions, and release archives for Linux, macOS and Windows signed
   with Sigstore and with SLSA provenance.
 
-[Unreleased]: https://github.com/Hodeitek/hodeishield-cli/compare/v0.3.1...HEAD
+[Unreleased]: https://github.com/Hodeitek/hodeishield-cli/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/Hodeitek/hodeishield-cli/compare/v0.3.1...v0.4.0
 [0.3.1]: https://github.com/Hodeitek/hodeishield-cli/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/Hodeitek/hodeishield-cli/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/Hodeitek/hodeishield-cli/compare/v0.1.1...v0.2.0
diff --git a/Cargo.lock b/Cargo.lock
index 61bf3f2..fb882c9 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -970,7 +970,7 @@ dependencies = [
 
 [[package]]
 name = "hodeishield-api"
-version = "0.3.1"
+version = "0.4.0"
 dependencies = [
  "mockito",
  "reqwest",
@@ -983,7 +983,7 @@ dependencies = [
 
 [[package]]
 name = "hodeishield-cli"
-version = "0.3.1"
+version = "0.4.0"
 dependencies = [
  "apple-native-keyring-store",
  "assert_cmd",
@@ -3066,7 +3066,7 @@ checksum = "3ad82d2a33cdc9674dc7465672f271e096168fcdbe0f799d9e6db8c5892679dc"
 
 [[package]]
 name = "xtask"
-version = "0.3.1"
+version = "0.4.0"
 dependencies = [
  "clap",
  "clap_mangen",
diff --git a/Cargo.toml b/Cargo.toml
index 9dd5bfb..f27fa9c 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -5,7 +5,7 @@ default-members = ["crates/hodeishield-api", "crates/hodeishield-cli"]
 
 [workspace.package]
 authors = ["Hodeitek S.L. <info@hodeitek.com>"]
-version = "0.3.1"
+version = "0.4.0"
 edition = "2024"
 rust-version = "1.98"
 license = "Apache-2.0"

From 67998dcbc604d5ef5663e8eabbf9e395d837c3e2 Mon Sep 17 00:00:00 2001
From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
Date: Sun, 11 Oct 2026 14:46:22 +0200
Subject: [PATCH 57/57] Point the install examples at 0.4.0

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
---
 README.md                  | 24 ++++++++++++------------
 docs/verifying-releases.md | 26 +++++++++++++-------------
 2 files changed, 25 insertions(+), 25 deletions(-)

diff --git a/README.md b/README.md
index 695f98f..7c9e9ac 100644
--- a/README.md
+++ b/README.md
@@ -54,16 +54,16 @@ section), and put `hodeishield` (`hodeishield.exe` on Windows) somewhere on your
 | Linux arm64 | `hodeishield-<version>-aarch64-unknown-linux-musl.tar.gz` |
 | macOS (Apple silicon and Intel) | `hodeishield-<version>-universal-apple-darwin.tar.gz` |
 | Windows x86_64 | `hodeishield-<version>-x86_64-pc-windows-msvc.zip` |
-| Windows arm64 | `hodeishield-<version>-aarch64-pc-windows-msvc.zip` (from the first release after 0.3.1) |
+| Windows arm64 | `hodeishield-<version>-aarch64-pc-windows-msvc.zip` (from 0.4.0) |
 
-`<version>` has no leading `v`: release `v0.3.1` ships `hodeishield-0.3.1-…`. The Linux binaries are
-statically linked and run on any distribution. Homebrew and Scoop packages are also available
-(next section).
+`<version>` has no leading `v`: release `v0.4.0` ships `hodeishield-0.4.0-…`. The Linux binaries are
+statically linked and run on any distribution. Homebrew and Scoop packages (next section) and a
+[container image](#container-image) are also available.
 
 From source, with the Rust toolchain installed (pin the release tag you want):
 
 ```sh
-cargo install --locked --git https://github.com/Hodeitek/hodeishield-cli --tag v0.3.1 hodeishield-cli
+cargo install --locked --git https://github.com/Hodeitek/hodeishield-cli --tag v0.4.0 hodeishield-cli
 ```
 
 ### Homebrew and Scoop
@@ -159,9 +159,9 @@ that check (the checksum still runs). `sh install.sh --help` lists the options (
 
 ### Container image
 
-From the first release after 0.3.0, each stable release also publishes a multi-architecture
-(`linux/amd64`, `linux/arm64`) image at `ghcr.io/hodeitek/hodeishield-cli`, for CI jobs and container
-pipelines. It holds only the release's own `hodeishield` binary on a
+From 0.4.0, each stable release also publishes a multi-architecture (`linux/amd64`, `linux/arm64`)
+image at `ghcr.io/hodeitek/hodeishield-cli`, for CI jobs and container pipelines. It holds only the
+release's own `hodeishield` binary on a
 [distroless](https://github.com/GoogleContainerTools/distroless) static base (no shell, no package
 manager, CA certificates included) and runs as a non-root user. There is no `latest` tag: use the
 exact version, or better its digest.
@@ -218,9 +218,9 @@ Each release has a `SHA256SUMS` file, a Sigstore bundle (`*.sigstore.json`) for
 ```sh
 sha256sum --ignore-missing -c SHA256SUMS
 
-cosign verify-blob hodeishield-0.3.1-x86_64-unknown-linux-musl.tar.gz \
-  --bundle hodeishield-0.3.1-x86_64-unknown-linux-musl.tar.gz.sigstore.json \
-  --certificate-identity https://github.com/Hodeitek/hodeishield-cli/.github/workflows/release.yml@refs/tags/v0.3.1 \
+cosign verify-blob hodeishield-0.4.0-x86_64-unknown-linux-musl.tar.gz \
+  --bundle hodeishield-0.4.0-x86_64-unknown-linux-musl.tar.gz.sigstore.json \
+  --certificate-identity https://github.com/Hodeitek/hodeishield-cli/.github/workflows/release.yml@refs/tags/v0.4.0 \
   --certificate-oidc-issuer https://token.actions.githubusercontent.com \
   --certificate-github-workflow-trigger push
 ```
@@ -248,7 +248,7 @@ xattr -d com.apple.quarantine ./hodeishield   # "No such xattr" means there was
 Or download with `curl`, which does not set that attribute in the first place:
 
 ```sh
-curl -LO https://github.com/Hodeitek/hodeishield-cli/releases/download/v0.3.1/hodeishield-0.3.1-universal-apple-darwin.tar.gz
+curl -LO https://github.com/Hodeitek/hodeishield-cli/releases/download/v0.4.0/hodeishield-0.4.0-universal-apple-darwin.tar.gz
 ```
 
 **Windows, before 0.2.0.** Unblock the archive before unpacking it, so the executable does not
diff --git a/docs/verifying-releases.md b/docs/verifying-releases.md
index 10b058e..87e25f0 100644
--- a/docs/verifying-releases.md
+++ b/docs/verifying-releases.md
@@ -7,8 +7,8 @@ Every release of `hodeishield-cli` publishes, for each platform archive:
   "bundle" files produced by **keyless** `cosign sign-blob` (no private key:
   the workflow signs using its GitHub Actions OIDC identity, and the
   signature is recorded in the public Rekor transparency log).
-- `hodeishield-<version>-aarch64-pc-windows-msvc.zip` (Windows on Arm, from the first release
-  after 0.3.1), checksummed, signed with Sigstore, covered by the provenance and accompanied by its
+- `hodeishield-<version>-aarch64-pc-windows-msvc.zip` (Windows on Arm, from 0.4.0),
+  checksummed, signed with Sigstore, covered by the provenance and accompanied by its
   SBOM like the other archives. Its `hodeishield.exe` carries the same Authenticode signature
   (section 5). There is no arm64 MSI yet.
 - `hodeishield-<version>-x86_64-pc-windows-msvc.msi` (from 0.3.0), with its own
@@ -25,14 +25,14 @@ Every release of `hodeishield-cli` publishes, for each platform archive:
   [`slsa-framework/slsa-github-generator`](https://github.com/slsa-framework/slsa-github-generator)
   generic generator.
 
-The steps below use `v0.3.1` and `hodeishield-0.3.1-x86_64-unknown-linux-musl.tar.gz`
+The steps below use `v0.4.0` and `hodeishield-0.4.0-x86_64-unknown-linux-musl.tar.gz`
 as examples — substitute the actual version and archive you downloaded.
 
 ## 1. Download the files
 
 From the release page, download:
 
-- the archive you want (e.g. `hodeishield-0.3.1-x86_64-unknown-linux-musl.tar.gz`)
+- the archive you want (e.g. `hodeishield-0.4.0-x86_64-unknown-linux-musl.tar.gz`)
 - `SHA256SUMS`
 - the matching `<archive>.sigstore.json`
 - `SHA256SUMS.sigstore.json`
@@ -55,7 +55,7 @@ Requires [`cosign`](https://github.com/sigstore/cosign) (v2 or newer).
 ```sh
 cosign verify-blob \
   --bundle SHA256SUMS.sigstore.json \
-  --certificate-identity https://github.com/Hodeitek/hodeishield-cli/.github/workflows/release.yml@refs/tags/v0.3.1 \
+  --certificate-identity https://github.com/Hodeitek/hodeishield-cli/.github/workflows/release.yml@refs/tags/v0.4.0 \
   --certificate-oidc-issuer https://token.actions.githubusercontent.com \
   --certificate-github-workflow-trigger push \
   SHA256SUMS
@@ -65,11 +65,11 @@ Repeat for the archive itself, using its own `.sigstore.json`:
 
 ```sh
 cosign verify-blob \
-  --bundle hodeishield-0.3.1-x86_64-unknown-linux-musl.tar.gz.sigstore.json \
-  --certificate-identity https://github.com/Hodeitek/hodeishield-cli/.github/workflows/release.yml@refs/tags/v0.3.1 \
+  --bundle hodeishield-0.4.0-x86_64-unknown-linux-musl.tar.gz.sigstore.json \
+  --certificate-identity https://github.com/Hodeitek/hodeishield-cli/.github/workflows/release.yml@refs/tags/v0.4.0 \
   --certificate-oidc-issuer https://token.actions.githubusercontent.com \
   --certificate-github-workflow-trigger push \
-  hodeishield-0.3.1-x86_64-unknown-linux-musl.tar.gz
+  hodeishield-0.4.0-x86_64-unknown-linux-musl.tar.gz
 ```
 
 A successful verification confirms the file was signed by the
@@ -82,11 +82,11 @@ The SBOM is verified the same way, with its own bundle:
 
 ```sh
 cosign verify-blob \
-  --bundle hodeishield-0.3.1-x86_64-unknown-linux-musl.cdx.json.sigstore.json \
-  --certificate-identity https://github.com/Hodeitek/hodeishield-cli/.github/workflows/release.yml@refs/tags/v0.3.1 \
+  --bundle hodeishield-0.4.0-x86_64-unknown-linux-musl.cdx.json.sigstore.json \
+  --certificate-identity https://github.com/Hodeitek/hodeishield-cli/.github/workflows/release.yml@refs/tags/v0.4.0 \
   --certificate-oidc-issuer https://token.actions.githubusercontent.com \
   --certificate-github-workflow-trigger push \
-  hodeishield-0.3.1-x86_64-unknown-linux-musl.cdx.json
+  hodeishield-0.4.0-x86_64-unknown-linux-musl.cdx.json
 ```
 
 ## 4. Verify SLSA build provenance
@@ -95,10 +95,10 @@ Requires [`slsa-verifier`](https://github.com/slsa-framework/slsa-verifier).
 
 ```sh
 slsa-verifier verify-artifact \
-  hodeishield-0.3.1-x86_64-unknown-linux-musl.tar.gz \
+  hodeishield-0.4.0-x86_64-unknown-linux-musl.tar.gz \
   --provenance-path hodeishield.intoto.jsonl \
   --source-uri github.com/Hodeitek/hodeishield-cli \
-  --source-tag v0.3.1
+  --source-tag v0.4.0
 ```
 
 `hodeishield.intoto.jsonl` is attached to the release and covers every