trooth 0.4.4 → 0.5.0

package/README.md

@@ -2,13 +2,13 @@
 
 The Trooth Network from your terminal. Published on npm as **`trooth`**.
 
-Trooth operates the Trooth Network: one public, signed, machine-readable record per company, carrying its identity, products and demos, commercial terms, domain and marketing links, people, documents, security and privacy posture, AI practices, procurement terms and relationships. It is Trooth's only product and it is free.
+Trooth operates the Trooth Network: one public, machine-readable record per company, carrying its identity, products and demos, commercial terms, domain and marketing links, people, documents, security and privacy posture, AI practices, procurement terms and relationships. It is Trooth's only product and it is free. Trooth signs one object in that record, the witness statement for a reading Trooth took of the company's public surface. The rest of the profile, including what the company declares about itself, is not signed.
 
 DNS says where a company is. A TLS certificate says the connection is authentic. The Trooth Network says who the company is and what it does with your data.
 
 This CLI is the terminal interface to that record. It does two things:
 
-- `trooth check <domain>` reads a company's published record from the public Network. No key, no account, and nothing about you is sent beyond what any web request carries (your IP address and a `trooth-cli/<version>` user-agent).
+- `trooth check <domain>` reads a company's published record from the public Network. No key and no account. It sends one request to `api.trooth.co` with **the domain you ask about in the request URL**, plus what every web request carries: your IP address and a `trooth-cli/<version>` user agent. Trooth's servers can therefore see which domain you looked up; [trooth.co/privacy](https://trooth.co/privacy) and the [retention schedule](https://trooth.co/retention) say what is kept and for how long. Nothing else about you or your machine is sent.
 - `trooth lint [path]` reads what your own infrastructure declares and prints those declarations as facts. Entirely local: it opens files and opens no sockets.
 
 **Trooth witnesses and dates facts. It does not grade, rate or rank anyone.** The CLI prints counts, reported apart, and never adds them into one number.
@@ -24,20 +24,20 @@ npm install -g trooth
 trooth --version
 ```
 
-Node 18 or newer, because the binary uses the built-in `fetch`. Zero dependencies.
+Node 18 or newer, because the binary uses the built-in `fetch`. One dependency, pinned to an exact version and locked in `npm-shrinkwrap.json`: [`yaml`](https://www.npmjs.com/package/yaml), the maintained YAML parser, which itself has none. It is there so Kubernetes files are parsed rather than pattern-matched. Install with `--ignore-scripts` if you like; neither package has an install script.
 
 ## Commands
 
 | Command | What it does |
 |---|---|
-| `trooth check <domain>` | Reads a company's record from the live Network and prints whether it is listed, when it was last witnessed and first published, the live-probe and self-attestation counts, the badge id, the id of the key that signed the record, and the three newest events in its ledger, newest first. `--json` adds the signature itself and every event the feed returns. |
-| `trooth lint [path]` | Reads the infrastructure the given directory declares and prints those declarations plus a canonical SHA-256 digest of them. Local and offline. `path` defaults to `.`. |
+| `trooth check <domain>` | Reads a company's record from the live Network and prints its listing and evidence state, the date of the witnessed reading and of first publication, the live-probe and self-attestation counts, the badge id, the id of the signing key, and the three newest events in its ledger, newest first. `--json` adds the signature itself and every event the feed returns. It does not check the signature. |
+| `trooth lint [path]` | Reads the infrastructure the given directory declares and prints those declarations, a coverage report and an aggregate digest of the counts. Local and offline. `path` defaults to `.`. |
 | `trooth --help` | Help. Also `-h` and `help`. |
 | `trooth --version` | Version. Also `-v` and `version`. |
 
 ## Flags
 
-`--json` is the only flag `check` and `lint` take. With it, stdout carries exactly one JSON document and nothing else, and every diagnostic goes to stderr. On an error the document is `{"ok": false, "error": "...", "exit": N}`; a non-2xx response adds `http_status`, and `lint` with nothing to read adds `files_opened`. `--help` and `--version` print plain text whether or not `--json` is given.
+`--json` is the flag both commands take; `lint` also takes `--allow-incomplete`. With `--json`, stdout carries exactly one JSON document and nothing else, and every diagnostic goes to stderr. On an error the document is `{"ok": false, "error": "...", "exit": N}`; a non-2xx response adds `http_status`, and `lint` with nothing to read adds `files_opened`. `--help` and `--version` print plain text whether or not `--json` is given.
 
 Any other flag is a usage error. The message names the flag, and for a `--` flag given to `check` or `lint` it also lists the ones that exist.
 
@@ -45,12 +45,14 @@ Any other flag is a usage error. The message names the flag, and for a `--` flag
 
 | Code | Meaning |
 |---|---|
-| 0 | The company is listed, or `lint` read at least one declaration, or you asked for help or the version. |
-| 1 | The company is not listed, or `lint` found nothing to read. |
-| 2 | Usage error: a missing argument, an unknown flag or command, or a path that does not exist. |
-| 3 | Trooth could not be read: unreachable, a non-2xx response, or a response that is not JSON. An unexpected failure inside the CLI also exits 3. |
+| 0 | `check`: listed, and the record carries a dated reading Trooth witnessed. `lint`: a complete read of at least one declaration. Help and version also exit 0. |
+| 1 | `check`: not listed, or revoked. `lint`: nothing to read. |
+| 2 | Usage error: a missing argument, an unknown flag or command, input that is not one domain, or a path that does not exist. |
+| 3 | Service or contract error: Trooth unreachable or slower than 15 seconds, a status other than 2xx or the documented not-listed 404, a body over 1 MiB, a body that is not JSON, or a record for a different domain. Never an answer about a company. An unexpected failure inside the CLI also exits 3. |
+| 4 | `lint`: the read was incomplete. A selected file was over the size limit, did not parse or could not be read, or the walk stopped at its file limit. `--allow-incomplete` reports the same and exits 0 (or 1 when nothing was read). New in 0.5.0. |
+| 5 | `check`: the company is listed, but its record carries no reading this CLI can confirm Trooth witnessed. New in 0.5.0. |
 
-A company with no record and a Network that could not be read are different answers, so they exit differently. A pipeline can tell them apart without parsing prose, and a Trooth outage never reads as a company with no record.
+A company with no record, a listed company without a witnessed reading, and a Network that could not be read are different answers, so they exit differently. A pipeline can tell them apart without parsing prose, and a Trooth outage never reads as a company with no record.
 
 ## `trooth check`
 
@@ -61,30 +63,47 @@ trooth check trooth.co
 Example output. The values are illustrative; the shape is what the binary prints.
 
 ```
-Trooth Network // public · signed · read-only //
+Trooth Network // public record · read-only //
 Trooth, LLC   trooth.co
-Listing state: listed and witnessed   last witnessed 2026-08-30   first published 2026-08-01
+Listing state: listed; Trooth witnessed a reading   reading dated 2026-09-26   first published 2026-08-01
 
-Live probes: 65 read; 64 as expected
+Live probes: 65 read; 63 as expected
 Self-attestations: 35 asked; 27 attested
 Live probes are readings Trooth took itself, from the company's public surface.
 Self-attestations are what the company attested about itself; Trooth records them
 and did not witness them. The two are reported apart and never added into one number.
-Badge rw_...   Key ed25519-2026-01
+Badge rw_...   Key trooth-master-2026-09
 
 Latest ledger events, newest first
-  • 2026-08-30  record published to the Trooth Network
-  • 2026-08-30  reading completed
+  • 2026-09-26  live probes re-read
+  • 2026-09-26  reading completed
   • 2026-08-01  record published to the Trooth Network
   --json carries the whole ledger, with the feed's own wording for each event.
 
+This command did not check the record's signature. The signature covers the
+reading, not every fact on the company's profile. To check it yourself: https://trooth.co/docs/verifiable-evidence
 A dated, point-in-time record. Trooth issues no verdict and no single number.
 Full record: https://trooth.co/network/trooth.co   ·   Signing keys: https://api.trooth.co/public/keys
 ```
 
-The line that begins `Listing state:` gives the listing state. For a listed company it reads `listed and witnessed`, then the date of the most recent published reading (`last witnessed`) and the date the record was first published. The two counts use the same form as the record page on trooth.co: live probes (how many were read at the last reading, and how many of those returned the expected result) and self-attestations (how many the company was asked for, and how many it attested). Live probes are readings Trooth took itself; self-attestations are the company's statements about itself, which Trooth records and does not witness.
+The line that begins `Listing state:` gives the listing and evidence state, decided from the record's own fields and never from a matching name:
 
-The events section prints the three newest entries in the record's ledger, newest first, by timestamp; entries with the same timestamp keep the feed's order, the later entry first. Known event types get a plain label: `scan_completed` prints as "reading completed", `standing_published` as "record published to the Trooth Network" and `rewitnessed` as "live probes re-read". A type the CLI does not know prints with its underscores turned into spaces. The human view leaves out each event's detail text. `--json` carries every event the feed returns, with its type and detail exactly as the feed has them.
+| `state` in `--json` | Printed | Exit | Meaning |
+|---|---|---|---|
+| `listed_witnessed` | listed; Trooth witnessed a reading | 0 | The record carries a dated reading with at least one live probe read. |
+| `listed_not_witnessed` | listed; no reading witnessed | 5 | The record says it was not witnessed, or its reading read no probe. |
+| `listed_evidence_unknown` | listed; the reading could not be read from this record | 5 | Listed, with no reading this CLI can interpret. |
+| `revoked` | revoked | 1 | The record says it was revoked or withdrawn. |
+| `not_listed` | not listed in the Trooth Network's public feed | 1 | The documented not-listed answer: a JSON 404 whose body says `listed: false`. |
+| `service_error` | (an error on stderr) | 3 | Anything else. Never read as an answer about the company. |
+
+The two counts use the same form as the record page on trooth.co: live probes (how many were read at the last reading, and how many of those returned the expected result) and self-attestations (how many the company was asked for, and how many it attested). Live probes are readings Trooth took itself; self-attestations are the company's statements about itself, which Trooth records and does not witness. The counts come from the directory record; they are the counts of the signed reading, and not any other total a page may show.
+
+The events section prints the three newest entries in the record's ledger, newest first, by timestamp; entries with the same timestamp keep the feed's order, the later entry first. Known event types get a plain label: `scan_completed` prints as "reading completed", `standing_published` as "record published to the Trooth Network" and `rewitnessed` as "live probes re-read". A type the CLI does not know prints with its underscores turned into spaces. `--json` carries every event the feed returns, with its type and detail exactly as the feed has them.
+
+**What `check` accepts.** A bare domain or a URL. It is parsed with the standard URL parser, so case, a trailing dot, the default port (80 or 443), a path and an internationalized name (converted to its ASCII form) normalize to one domain, and a leading `www.` is dropped: `https://Trooth.co:443/path` reads `trooth.co`. A URL with a user name or password, a non-default port, an IP address, a scheme other than http or https, or a name with no dot is a usage error (exit 2) rather than a guess.
+
+**How `check` asks.** One `GET /directory/api/vendors/<domain>`, with a 15-second deadline (`TROOTH_TIMEOUT_MS` changes it), a 1 MiB limit on the body, redirects refused, a JSON content type required, and at most one retry, only after a connection failure or a 502, 503 or 504. Up to 0.4.4, a plain-text 404 made the CLI download the whole directory list and search it; the single-record route has been served since 2026-09-26, and 0.5.0 has no fallback, so an unexpected answer is a service error, never "not listed".
 
 For scripting:
 
@@ -96,6 +115,7 @@ trooth check trooth.co --json
 {
   "domain": "trooth.co",
   "listed": true,
+  "state": "listed_witnessed",
   "company_name": "Trooth, LLC",
   "witnessed_at": "2026-08-30T00:00:00Z",
   "first_published_at": "2026-08-01T00:00:00Z",
@@ -109,19 +129,21 @@ trooth check trooth.co --json
     { "type": "standing_published", "at": "2026-08-30T00:00:00Z", "detail": "point-in-time · published to the Trooth Network" }
   ],
   "receipt_signature": "...",
-  "authority_key_id": "ed25519-2026-01",
+  "authority_key_id": "trooth-master-2026-09",
+  "signature_checked": false,
   "verify_keys": "https://api.trooth.co/public/keys",
+  "verify_how": "https://trooth.co/docs/verifiable-evidence",
   "record_url": "https://trooth.co/network/trooth.co"
 }
 ```
 
-In `probes`, `total` is how many live probes were read at the last reading and `passed` (the API's field name) is how many returned the expected result. In `attested`, `total` is how many declarations were asked for and `passed` is how many the company attested. `witnessed_at` is the date of the most recent published reading. `events` is the whole ledger, oldest first, in the feed's order. Each event's `detail` is written when the event is stored and is not rewritten afterward, so older and newer events of the same type can be worded differently.
+In `probes`, `total` is how many live probes were read at the last reading and `passed` (the API's field name) is how many returned the expected result. In `attested`, `total` is how many declarations were asked for and `passed` is how many the company attested. `witnessed_at` is the date of the witnessed reading, and is `null` unless `state` is `listed_witnessed`; it is never a profile edit time. `events` is the whole ledger, oldest first, in the feed's order. Each event's `detail` is written when the event is stored and is not rewritten afterward, so older and newer events of the same type can be worded differently.
 
 `category` and `description` are added when the record carries them. Those are the only fields `check --json` emits: anything else the feed happens to carry is dropped on the way out, so a script written against this shape keeps working. A field whose name contains `score`, `tier`, `grade`, `rank`, `rating`, `level` or `percent`, or is `rate`, is dropped no matter what the feed sends.
 
-A company with no record exits 1 and emits `{"domain": "...", "listed": false, "record_url": "..."}`. That is not a judgment. It means the Network's public feed carries no record for that domain. A company gets a record at [trooth.co/get-started](https://trooth.co/get-started), free.
+A company with no record exits 1 and emits `{"domain": "...", "listed": false, "state": "not_listed", "record_url": "..."}`. That is not a judgment. It means the Network's public feed carries no record for that domain. A company gets a record at [trooth.co/get-started](https://trooth.co/get-started), free.
 
-`receipt_signature` is Trooth's Ed25519 signature and `authority_key_id` names the key that made it; the public keys are listed at [trooth.co/verify/keys](https://trooth.co/verify/keys). You cannot re-run that signature check from this output yet: the exact bytes the signature covers are not published, and this JSON does not carry every field that goes into them. [`trooth-signatures`](https://github.com/troothllc/trooth-signatures) states that gap and what will close it.
+`receipt_signature` is Trooth's Ed25519 signature over the directory receipt and `authority_key_id` names the key that made it; the public keys are listed at [trooth.co/verify/keys](https://trooth.co/verify/keys). `signature_checked` is always `false`: this CLI does not check any signature, and nothing it prints should be read as a checked signature. The object whose exact signed bytes Trooth publishes is the reading's witness statement, which is not part of this feed; [trooth.co/docs/verifiable-evidence](https://trooth.co/docs/verifiable-evidence) shows how to fetch and check it offline. That signature covers the reading. It does not cover the company's own declarations, which are not signed by anyone.
 
 ## `trooth lint`
 
@@ -131,7 +153,7 @@ A company with no record exits 1 and emits `{"domain": "...", "listed": false, "
 trooth lint ./infra
 ```
 
-Output for the small fixture in this repository (`trooth lint tests/fixtures/infra`, trooth 0.4.3):
+Output for the small fixture in this repository (`trooth lint tests/fixtures/infra`, trooth 0.5.0):
 
 ```
 trooth lint // local · offline · declarations only //
@@ -141,7 +163,10 @@ terraform 1 · kubernetes 1
 Declared
   Regions and zones                        us-east-1
   Storage declarations                     1
-    of those declaring encryption          1
+    declaring encryption                   1
+    declaring encryption off               0
+    declaring nothing about encryption     0
+    set by an unresolved expression        0
   Logging declarations                     0
   Identity declarations                    0
   Open to any address (0.0.0.0/0, ::/0)    1
@@ -152,17 +177,20 @@ Most declared resource types
      1  aws_s3_bucket
      1  aws_s3_bucket_server_side_encryption_configuration
      1  aws_security_group_rule
+     1  Deployment
 
-Digest  sha256:a40bf6cf27dfd0b9079ac48a326fb2d1423b076c96b405451dde1ed2d7848944
-A SHA-256 over the facts above, in canonical form, with the timestamp excluded.
-The same tree read by the same trooth version produces the same digest, so you can
-record it as evidence that a state was observed without publishing the tree.
+Coverage  complete
+  2 selected: 2 read, 0 not declarations, 0 excluded, 0 skipped, 0 invalid, 0 unreadable.
+
+Facts digest  sha256:2ba1da28be9e97e1e8be1f7e41641288bc632192c062ba1fbd563350448fd5a8
+A SHA-256 over the counts above, in canonical form. It is an aggregate: two different
+trees with the same counts share it. It does not identify your files, your repository
+or a deployment.
 
 How this was read
-  A pattern reader, not a Terraform evaluator: variables and modules are not resolved.
-  .tf by pattern, one resource block at a time. .tf.json and plan JSON parsed, one
-  resource at a time. Kubernetes YAML by pattern, one document at a time, by kind.
-  Dockerfiles for regions, open addresses, public markers and credential literals only.
+  Every file is parsed; a file that does not parse is reported as invalid, not read.
+  Comments count for nothing. Nothing is evaluated: a setting that depends on a variable,
+  a local, a module or a function is reported as unresolved. Dockerfiles: ENV and ARG only.
 
 Counts of what the files declare. Not a judgment: a public load balancer is
 supposed to be public. Trooth issues no verdict here and checks nothing against
@@ -172,11 +200,35 @@ Publish what you choose on your record at https://trooth.co/dashboard.
 
 The bucket's encryption configuration is a setting on the bucket, not a second store, so the fixture has one storage declaration, and that one declares encryption.
 
-It reads `.tf`, `.tf.json`, Kubernetes YAML (anything carrying both `apiVersion` and `kind`), `terraform show -json` plan files and Dockerfiles. It is a pattern reader, not a Terraform evaluator: variables, modules and `for_each` are never resolved, so a count can differ from what Terraform itself would plan. `.tf` files are read by pattern, one resource block at a time. `.tf.json` and plan files are parsed as JSON, one resource at a time. Kubernetes YAML is read by pattern, one document at a time, and classified by its `kind`. Dockerfiles are read for regions, open addresses, public markers and credential literals only. Storage, logging and identity are counted by a resource's type or a document's kind, never by the words around it. The output states this under "How this was read".
+**How each source is read.** Every file is parsed, and a file that does not parse is reported as invalid, never as read.
+
+| Source | Parsed with | Unit |
+|---|---|---|
+| `.tf` | The HCL reader in `bin/lib/hcl.mjs` (comments dropped, heredocs and templates understood) | One `resource` block, at any indentation |
+| `.tf.json` | `JSON.parse` | One resource |
+| `terraform show -json` plan | `JSON.parse` | One planned managed resource; data sources are skipped |
+| Kubernetes YAML (`apiVersion` and `kind`) | The `yaml` package, strict mode | One document, classified by `kind` |
+| Dockerfile | `ENV` and `ARG` instructions only | The file |
+
+Nothing is evaluated. A setting that depends on a variable, a local, a module output or a function is reported as unresolved and is never counted as declared. Storage, logging and identity are counted by a resource's type or a document's kind, never by the words around it. Counts are of parsed values, not lines: two credential literals on one minified line are two.
+
+**Encryption, per store.** Each storage declaration is counted in exactly one of five states:
 
-Nothing leaves the machine. No file name, no line, no code and no value is printed or transmitted, only the path you gave it, counts, resource type names and region strings. The credential count is a count: the literal it found is never shown.
+| Field | State |
+|---|---|
+| `storage_declaring_encryption` | An explicit `true`, a named key (a literal or a reference to a key resource such as `aws_kms_key.main.arn`), or an encryption block, in the store or in a setting resource that refers to it |
+| `storage_declaring_encryption_off` | An explicit `false`. It wins over any other signal |
+| `storage_encryption_not_declared` | Nothing about encryption. A commented-out setting is nothing |
+| `storage_encryption_unresolved` | Decided by a variable, a local or another expression lint does not evaluate |
+| `storage_encryption_unsupported` | A value lint does not interpret, such as a number where a switch belongs |
+
+A declaration is what a file says, not what a cloud account does: a provider default, an account-wide setting or a module can encrypt a store whose file declares nothing, and lint cannot see any of those.
+
+**Coverage.** Every file the walk selects (`.tf`, `.tf.json`, `.json`, `.yaml`, `.yml`, Dockerfiles) ends in exactly one bucket: read; not applicable (a JSON or YAML file that is not a plan or a manifest); excluded by a stated rule (a templated manifest containing `{{ }}`, which has to be rendered first); skipped (over 4 MiB); invalid (did not parse); or unreadable (a permission or I/O error). The walk visits directories depth first with entries sorted by name, skips `node_modules`, `.git`, `.terraform` and the other build and dependency directories listed in the source, and stops at 5,000 selected files. A read with anything skipped, invalid or unreadable, or a truncated walk, is **incomplete**: the output says so, `--json` carries a `coverage` object with each count and a `coverage_details` object listing up to 50 paths per bucket with the reason (never file contents), and the exit code is 4 unless you pass `--allow-incomplete`.
+
+Nothing leaves the machine. No line, no code and no value is printed or transmitted, only the path you gave it, counts, resource type names, region strings and, for files that could not be read, their paths and the reason. The credential count is a count: the literal it found is never shown.
 
-The digest is a SHA-256 over the `facts` object in canonical form. The timestamp, the path and the CLI version are outside it, so the same tree read by the same trooth version produces the same digest. A release that changes how something is counted changes the digest of the same tree: the fixture above digests differently under 0.4.2 and 0.4.3. Record the digest in CI, or on your own record, as evidence that a given state was observed, without publishing the tree it came from.
+**The facts digest** (`facts_digest`, also emitted as `digest` until 0.6) is a SHA-256 over the `facts` object in canonical form. It is an aggregate: two different trees with the same counts produce the same digest, and a release that changes how something is counted changes the digest of the same tree. It does not identify file contents, a repository, a commit or a deployment, and it is not an attestation of any of them. It is useful for noticing that the counts changed between two runs of the same version.
 
 ```bash
 # Keep the fact document as a build artifact.
@@ -188,11 +240,13 @@ trooth lint --json > trooth-lint.json
 The same `lint`, as a step, is [`troothllc/trooth-action`](https://github.com/troothllc/trooth-action). It is advisory by default: it writes what your infrastructure declares to the job summary and does not fail your workflow over anything it read unless you opt in to one of two gates. It does fail the step when it could not read at all: a path that does not exist, or a CLI it could not install or start.
 
 ```yaml
-- uses: troothllc/trooth-action@v1
+- uses: troothllc/trooth-action@<full commit SHA>  # v1
   with:
     path: ./infra
 ```
 
+Pin the action by its full commit SHA. A tag can be moved; a commit cannot. The action installs one exact `trooth` version with install scripts disabled and refuses a version input that is a range, a tag or a URL.
+
 That repository's README documents the inputs and outputs.
 
 ## Environment
@@ -200,6 +254,8 @@ That repository's README documents the inputs and outputs.
 | Variable | Effect |
 |---|---|
 | `TROOTH_API` | Base URL for `check`. Defaults to `https://api.trooth.co`. `lint` ignores it, because `lint` makes no requests. |
+| `TROOTH_TIMEOUT_MS` | The deadline for each `check` request. Defaults to 15000; the minimum is 1000. |
+| `TROOTH_LINT_MAX_FILES` | The number of selected files after which `lint` stops walking and reports the read as truncated. Defaults to 5000. |
 | `NO_COLOR` | Disables ANSI color. Color is already off when stdout is not a TTY. |
 
 There is no API key. The binary asks for no credential of any kind and has no write path.
@@ -214,9 +270,19 @@ https://api.trooth.co/public/mcp
 
 Four read-only tools, public data, no key. The pattern is written up at [trooth.co/docs/agents](https://trooth.co/docs/agents).
 
+## Changed in 0.5.0
+
+Breaking where the old behavior overstated what was read.
+
+- `lint` parses every format instead of matching patterns. `encrypted = false` on one line, `false` followed by a comment, a commented-out setting and a setting that depends on a variable no longer count as declaring encryption; each store is counted in one of five encryption states. Comments count for nothing, indentation no longer changes a count, and a minified JSON file counts the same as a pretty one.
+- `lint` reports coverage and exits 4 on an incomplete read: a malformed file, a file over the size limit, an unreadable file or a truncated walk. 0.4.4 read a malformed file as a success and an oversized one as "nothing to read".
+- The digest is renamed `facts_digest` and described as what it is, an aggregate of the counts. `digest` carries the same value until 0.6.
+- `check` decides the evidence state from the record's fields: a listed record is no longer printed as witnessed unless it carries a witnessed reading, and exit 5 means listed but not witnessed. The full-list fallback is gone, so an unexpected answer is a service error, never "not listed". Requests have a deadline, a body limit, a content-type check and one bounded retry. Input is normalized with the URL parser.
+- `check` says that it did not check the signature, and the help and this README say that `check` sends the domain you ask about.
+
 ## Changed in 0.4.4
 
-- `check` asks the Trooth Network for the one record it needs (`/directory/api/vendors/<domain>`) instead of downloading the whole directory list and searching it. When the API does not serve that path yet, it reads the list as 0.4.3 did. The printed output, `check --json` and the exit codes are unchanged.
+- `check` asked the Trooth Network for the one record it needs (`/directory/api/vendors/<domain>`) instead of downloading the whole directory list, and fell back to the list when the API did not serve that path. 0.5.0 removes the fallback.
 
 ## Changed in 0.4.3
 
@@ -238,7 +304,7 @@ The Trooth Network is Trooth's only product. This CLI, the public API and the MC
 
 ## Security
 
-Report a vulnerability through the [Vulnerability Disclosure Policy](https://trooth.co/security/vulnerability-disclosure-policy). Nothing in this CLI takes a credential, so there is no key to leak from it.
+Report a vulnerability through the [Vulnerability Disclosure Policy](https://trooth.co/security/vulnerability-disclosure-policy). Nothing in this CLI takes a credential, so there is no key to leak from it. Reproduce the published tarball with `npm pack` at the tagged commit and compare its SHA-512 with the `integrity` value `npm view trooth@<version> dist.integrity` prints.
 
 ## Links
 

package/bin/lib/declarations.mjs

@@ -0,0 +1,306 @@
+// What a declaration file says, read from its parsed tree.
+// Copyright 2025-2026 Trooth, LLC. Apache-2.0.
+//
+// Every supported format is parsed first (HCL by ./hcl.mjs, JSON by
+// JSON.parse, YAML by the maintained `yaml` package) and then read here from
+// the tree, so a comment can never count, indentation cannot change a count,
+// a minified file counts the same as a pretty one, and a file that does not
+// parse is reported as invalid instead of being read.
+//
+// An unresolved expression ({ $expr: "..." }) is never promoted to a value.
+// Where it decides a fact, the fact is reported as UNRESOLVED.
+
+import { parseHcl, bodyToTree, HclParseError } from './hcl.mjs';
+import { parseAllDocuments } from 'yaml';
+
+export { HclParseError };
+
+export const isExpr = (v) => !!v && typeof v === 'object' && !Array.isArray(v) && typeof v.$expr === 'string';
+
+/* ------------------------------------------------------------ parsing ---- */
+
+export class InvalidDeclaration extends Error {
+  constructor(message) { super(message); this.name = 'InvalidDeclaration'; }
+}
+
+/** A string in Terraform's JSON syntax that holds a template is an expression. */
+function tfJsonValue(v) {
+  if (typeof v === 'string') {
+    if (/[$%]\{/.test(v)) return { $expr: v };
+    return v;
+  }
+  if (Array.isArray(v)) return v.map(tfJsonValue);
+  if (v && typeof v === 'object') {
+    const o = {};
+    for (const [k, x] of Object.entries(v)) o[k] = tfJsonValue(x);
+    return o;
+  }
+  return v;
+}
+
+const each = (v, fn) => { if (Array.isArray(v)) v.forEach((x) => each(x, fn)); else if (v && typeof v === 'object') fn(v); };
+
+/**
+ * One file's units. Each unit: { type, name, address, tree, typed }.
+ * `type` is a resource type or Kubernetes kind (null for everything else in the
+ * file), `tree` is the parsed value, `address` is how other resources refer to
+ * it. Throws InvalidDeclaration when the file does not parse.
+ */
+export function unitsOf(kind, text) {
+  if (kind === 'terraform') {
+    let items;
+    try { items = parseHcl(text); } catch (e) { throw new InvalidDeclaration(e.message); }
+    const units = [];
+    const rest = [];
+    for (const it of items) {
+      if (it.kind === 'block' && it.type === 'resource') {
+        if (it.labels.length !== 2) throw new InvalidDeclaration(`line ${it.line}: a resource block needs a type and a name`);
+        const [type, name] = it.labels;
+        units.push({ type, name, address: `${type}.${name}`, tree: bodyToTree(it.body), typed: true });
+      } else rest.push(it);
+    }
+    if (rest.length) units.push({ type: null, name: null, address: null, tree: bodyToTree(rest), typed: false });
+    return units;
+  }
+  if (kind === 'terraform-json') {
+    let doc;
+    try { doc = JSON.parse(text); } catch (e) { throw new InvalidDeclaration(`not valid JSON: ${e.message}`); }
+    if (!doc || typeof doc !== 'object') throw new InvalidDeclaration('a .tf.json file must hold a JSON object');
+    const units = [];
+    each(doc, (top) => each(top.resource, (byType) => {
+      for (const [type, byName] of Object.entries(byType)) {
+        if (!/^[a-z0-9_]+$/.test(type)) continue;
+        each(byName, (names) => {
+          for (const [name, body] of Object.entries(names)) {
+            each(body, (b) => units.push({ type, name, address: `${type}.${name}`, tree: tfJsonValue(b), typed: true }));
+          }
+        });
+      }
+    }));
+    if (!Array.isArray(doc)) {
+      const rest = { ...doc }; delete rest.resource;
+      if (Object.keys(rest).length) units.push({ type: null, name: null, address: null, tree: tfJsonValue(rest), typed: false });
+    }
+    return units;
+  }
+  if (kind === 'terraform-plan') {
+    let doc;
+    try { doc = JSON.parse(text); } catch (e) { throw new InvalidDeclaration(`not valid JSON: ${e.message}`); }
+    const units = [];
+    const walkModule = (m) => {
+      if (!m || typeof m !== 'object') return;
+      for (const r of Array.isArray(m.resources) ? m.resources : []) {
+        if (r && r.mode !== 'data' && typeof r.type === 'string') {
+          units.push({ type: r.type, name: String(r.name ?? ''), address: r.address || `${r.type}.${r.name}`, tree: r.values ?? {}, typed: true, plan: true });
+        }
+      }
+      for (const c of Array.isArray(m.child_modules) ? m.child_modules : []) walkModule(c);
+    };
+    if (doc && doc.planned_values && doc.planned_values.root_module) walkModule(doc.planned_values.root_module);
+    else {
+      for (const rc of Array.isArray(doc && doc.resource_changes) ? doc.resource_changes : []) {
+        const after = rc && rc.change ? rc.change.after : null;
+        if (rc && rc.mode !== 'data' && typeof rc.type === 'string' && after) {
+          units.push({ type: rc.type, name: String(rc.name ?? ''), address: rc.address || `${rc.type}.${rc.name}`, tree: after, typed: true, plan: true });
+        }
+      }
+    }
+    return units;
+  }
+  if (kind === 'kubernetes') {
+    const docs = parseAllDocuments(text, { strict: true, uniqueKeys: true, prettyErrors: false });
+    const list = Array.isArray(docs) ? docs : [docs];
+    const units = [];
+    for (const d of list) {
+      if (d.errors && d.errors.length) throw new InvalidDeclaration(`not valid YAML: ${d.errors[0].message.split('\n')[0]}`);
+      const v = d.toJS({ maxAliasCount: 100 });
+      if (v === null || v === undefined) continue;
+      if (typeof v !== 'object' || Array.isArray(v)) throw new InvalidDeclaration('a Kubernetes document must be a mapping');
+      const k = typeof v.kind === 'string' && /^[A-Za-z][A-Za-z0-9]*$/.test(v.kind) ? v.kind : null;
+      if (!k || typeof v.apiVersion !== 'string') throw new InvalidDeclaration('a document in a Kubernetes file has no apiVersion and kind');
+      units.push({ type: k, name: v.metadata && v.metadata.name ? String(v.metadata.name) : null, address: null, tree: v, typed: true });
+    }
+    return units;
+  }
+  if (kind === 'container') {
+    return [{ type: null, name: null, address: null, tree: dockerfileTree(text), typed: false }];
+  }
+  throw new Error(`unknown kind ${kind}`);
+}
+
+/** A Dockerfile's ENV and ARG settings as a tree. Comment lines and line
+ *  continuations are handled; every other instruction declares nothing lint
+ *  counts. A value that uses $ is unresolved. */
+function dockerfileTree(text) {
+  const tree = {};
+  const logical = [];
+  let cur = '';
+  for (const raw of text.split(/\r?\n/)) {
+    if (/^\s*#/.test(raw) && !cur) continue;
+    if (/\\\s*$/.test(raw)) { cur += raw.replace(/\\\s*$/, ' '); continue; }
+    logical.push(cur + raw); cur = '';
+  }
+  if (cur) logical.push(cur);
+  const val = (s) => {
+    let v = s;
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) v = v.slice(1, -1);
+    return /\$/.test(v) ? { $expr: v } : v;
+  };
+  for (const l of logical) {
+    const m = /^\s*(ENV|ARG)\s+(.*)$/i.exec(l);
+    if (!m) continue;
+    const rest = m[2].trim();
+    const pairs = rest.match(/[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|\S*)/g);
+    if (pairs && pairs.join(' ').length >= rest.replace(/\s+/g, ' ').length - pairs.length) {
+      for (const p of pairs) { const i = p.indexOf('='); tree[p.slice(0, i)] = val(p.slice(i + 1)); }
+    } else {
+      const sp = /^([A-Za-z_][A-Za-z0-9_]*)(?:\s+(.*))?$/.exec(rest);
+      if (sp) tree[sp[1]] = sp[2] !== undefined ? val(sp[2].trim()) : { $expr: `ARG ${sp[1]}` };
+    }
+  }
+  return tree;
+}
+
+/* ----------------------------------------------------------- reading ---- */
+
+/** Every (key, value) pair in a tree, depth first. */
+function* pairs(tree, parent = null) {
+  if (Array.isArray(tree)) { for (const x of tree) yield* pairs(x, parent); return; }
+  if (!tree || typeof tree !== 'object' || isExpr(tree)) return;
+  for (const [k, v] of Object.entries(tree)) {
+    yield [k, v, parent];
+    yield* pairs(v, k);
+  }
+}
+
+/** Every string (literal or expression source) in a tree. */
+function* strings(tree) {
+  if (typeof tree === 'string') { yield tree; return; }
+  if (isExpr(tree)) { yield tree.$expr; return; }
+  if (Array.isArray(tree)) { for (const x of tree) yield* strings(x); return; }
+  if (tree && typeof tree === 'object') for (const v of Object.values(tree)) yield* strings(v);
+}
+
+const REGION_KEY = /^(region|location|availability_zone|aws_region|aws_default_region|zone)$/i;
+const REGION_VALUE = /^[A-Za-z0-9][A-Za-z0-9._-]{2,40}$/;
+const SECRET_KEY = /(password|passwd|secret|api[_-]?key|access[_-]?key|token|private[_-]?key)/i;
+const OPEN_CIDRS = new Set(['0.0.0.0/0', '::/0']);
+
+export function regionsIn(tree) {
+  const found = [];
+  for (const [k, v] of pairs(tree)) if (REGION_KEY.test(k) && typeof v === 'string' && REGION_VALUE.test(v)) found.push(v);
+  return found;
+}
+
+/** A credential literal: a secret-named key holding a literal string of at
+ *  least eight characters. One count per key, wherever it sits in the file. */
+export function credentialLiterals(tree) {
+  let n = 0;
+  for (const [k, v] of pairs(tree)) {
+    if (!SECRET_KEY.test(k)) continue;
+    if (typeof v === 'string' && v.length >= 8 && !/[$%]\{/.test(v)) n++;
+  }
+  return n;
+}
+
+export function opensToAnyAddress(tree) {
+  for (const s of strings(tree)) if (OPEN_CIDRS.has(s.trim())) return true;
+  return false;
+}
+
+export function markedPublic(tree) {
+  for (const [k, v] of pairs(tree)) {
+    if ((k === 'publicly_accessible' || k === 'public_network_access_enabled' || k === 'associate_public_ip_address') && (v === true || v === 'true')) return true;
+    if (k === 'acl' && typeof v === 'string' && /^public-read/.test(v)) return true;
+    if (k === 'type' && (v === 'LoadBalancer' || v === 'NodePort')) return true;
+  }
+  return false;
+}
+
+/* -------------------------------------------------------- encryption ---- */
+
+// Keys whose value is the encryption switch itself.
+const BOOL_KEY = /^(encrypted|storage_encrypted|encrypt_at_rest|encryption_enabled|enable_encryption|encrypted_at_rest|at_rest_encryption_enabled|encryption_at_rest_enabled)$/i;
+// Keys that name the key or algorithm a store is encrypted with.
+const KEY_KEY = /^(kms_key_id|kms_key_arn|kms_key_name|kms_key|kms_master_key_id|kms_key_self_link|encryption_key|encryption_key_name|disk_encryption_set_id|key_vault_key_id|sse_algorithm|default_kms_key_name)$/i;
+// Blocks whose presence configures encryption, unless they switch it off.
+const BLOCK_KEY = /^(server_side_encryption_configuration|server_side_encryption|encryption_configuration|encryption_config|encryption|encryption_at_rest|apply_server_side_encryption_by_default|disk_encryption|customer_managed_key)$/i;
+// An expression that refers to a managed resource (aws_kms_key.main.arn) or a
+// data source names a key that exists in the configuration; a variable, a
+// local or anything else is unresolved.
+const RESOURCE_REF = /^\$?\{?\s*(?:data\.)?[a-z][a-z0-9]*_[a-z0-9_]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_]+\s*\}?$/;
+
+export const ENCRYPTION = Object.freeze({
+  TRUE: 'declared',
+  FALSE: 'declared_off',
+  ABSENT: 'not_declared',
+  UNRESOLVED: 'unresolved',
+  UNSUPPORTED: 'unsupported',
+});
+
+function boolState(v) {
+  if (v === true || v === 'true') return ENCRYPTION.TRUE;
+  if (v === false || v === 'false') return ENCRYPTION.FALSE;
+  if (isExpr(v)) return ENCRYPTION.UNRESOLVED;
+  if (v === null) return ENCRYPTION.ABSENT;
+  return ENCRYPTION.UNSUPPORTED;
+}
+
+function keyState(v) {
+  if (v === null || v === '' || v === false) return ENCRYPTION.ABSENT;
+  if (typeof v === 'string') return ENCRYPTION.TRUE;
+  if (isExpr(v)) {
+    const s = v.$expr.replace(/^"\$\{|\}"$/g, '').trim();
+    return RESOURCE_REF.test(s) ? ENCRYPTION.TRUE : ENCRYPTION.UNRESOLVED;
+  }
+  return ENCRYPTION.UNSUPPORTED;
+}
+
+function blockState(v) {
+  const blocks = Array.isArray(v) ? v : [v];
+  let state = ENCRYPTION.ABSENT;
+  for (const b of blocks) {
+    if (!b || typeof b !== 'object' || isExpr(b)) { if (isExpr(b)) state = state === ENCRYPTION.TRUE ? state : ENCRYPTION.UNRESOLVED; continue; }
+    if ('enabled' in b) {
+      const s = boolState(b.enabled);
+      if (s === ENCRYPTION.FALSE) return ENCRYPTION.FALSE;
+      if (s === ENCRYPTION.UNRESOLVED) { state = ENCRYPTION.UNRESOLVED; continue; }
+    }
+    if (state !== ENCRYPTION.UNRESOLVED) state = ENCRYPTION.TRUE;
+  }
+  return state;
+}
+
+/**
+ * What one store's tree declares about encryption at rest:
+ *   declared      an explicit true, a key, or an encryption block
+ *   declared_off  an explicit false (it wins over any other signal)
+ *   not_declared  nothing about encryption (a comment is nothing)
+ *   unresolved    decided by a variable, local or other expression
+ *   unsupported   a value lint does not interpret (a number for a switch)
+ * An explicit switch decides; keys and blocks decide only when no switch is set.
+ */
+export function encryptionState(tree) {
+  const sw = [], other = [];
+  for (const [k, v] of pairs(tree)) {
+    if (BOOL_KEY.test(k)) sw.push(boolState(v));
+    else if (KEY_KEY.test(k)) other.push(keyState(v));
+    else if (BLOCK_KEY.test(k) && v && typeof v === 'object') other.push(blockState(v));
+  }
+  const decide = (list) => {
+    if (list.includes(ENCRYPTION.FALSE)) return ENCRYPTION.FALSE;
+    if (list.includes(ENCRYPTION.UNRESOLVED)) return ENCRYPTION.UNRESOLVED;
+    if (list.includes(ENCRYPTION.UNSUPPORTED)) return ENCRYPTION.UNSUPPORTED;
+    if (list.includes(ENCRYPTION.TRUE)) return ENCRYPTION.TRUE;
+    return ENCRYPTION.ABSENT;
+  };
+  const s = decide(sw);
+  if (s !== ENCRYPTION.ABSENT) return s;
+  return decide(other);
+}
+
+/** Every string and expression source in a tree, joined, for finding a
+ *  reference to another resource's address. */
+export function referenceText(tree) {
+  return [...strings(tree)].join('\n');
+}