trustdex 0.4.1 → 0.4.3

package/README.md

@@ -75,8 +75,8 @@ Requires Node.js 20+.
 Run directly from npm:
 
 ```bash
-npx trustdex@0.4.1 --help
-npx trustdex@0.4.1 inspect ./mcp.json --pack strict --policy ./trustdex.policy.json
+npx trustdex@0.4.3 --help
+npx trustdex@0.4.3 inspect ./mcp.json --pack strict --policy ./trustdex.policy.json
 ```
 
 Or work from a source checkout:
@@ -147,6 +147,8 @@ node ./bin/trustdex.mjs gate-codex ./examples/codex.config.toml \
 
 The gate removes non-approved MCP sections while preserving unrelated TOML sections. TrustDex intentionally parses only the MCP-related TOML constructs it needs; unsupported MCP syntax fails rather than being silently trusted.
 
+See [Using TrustDex with Codex](docs/CODEX.md) for a step-by-step gating workflow and for how this project uses Codex in its own review process.
+
 ## Online provenance observations
 
 Normal inspection remains local-only. These commands perform an explicit network lookup only when invoked:
@@ -292,7 +294,7 @@ The private key should never be committed.
 ```yaml
 - uses: actions/checkout@v4
 
-- uses: grigent/trustdex@v0.4.0
+- uses: grigent/trustdex@v0.4.3
   with:
     config: ./mcp.json
     pack: official-first

package/bin/trustdex.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { readFileSync } from 'node:fs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import process from 'node:process';
@@ -27,7 +28,8 @@ import {
   verifyTrustRecord
 } from '../src/trust-record.mjs';
 
-const VERSION = '0.4.0';
+// Read the version from the package manifest so --version cannot drift from releases.
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 
 function usage() {
   console.log(`TrustDex v${VERSION}

package/docs/CODEX.md

@@ -0,0 +1,73 @@
+# Using TrustDex with Codex
+
+This guide covers two things: gating the MCP servers a Codex client may start, and how TrustDex itself is maintained with Codex.
+
+TrustDex is an independent project. It is not affiliated with, endorsed by, or certified by OpenAI, and an ALLOW decision is not an OpenAI or TrustDex safety certification.
+
+## Gate Codex MCP servers
+
+Codex clients read MCP server definitions from `[mcp_servers.<name>]` tables in `config.toml` (by default under `~/.codex/`). Every entry there can start a local process or connect to a remote endpoint with the credentials you give it.
+
+### 1. Inspect the current configuration
+
+```bash
+npx trustdex@0.4.3 inspect-codex ~/.codex/config.toml --pack strict
+```
+
+This reads the file locally and makes no network request. The output lists each MCP server, its source type, trust signals, and an ALLOW / ASK / BLOCK decision. Environment variable names may appear; their values never do.
+
+Use `--json` for machine-readable output and `--trust-store ./trust-store.json` to attach explicit publisher evidence (see [TRUST_STORE.md](TRUST_STORE.md)).
+
+### 2. Write a gated copy
+
+```bash
+npx trustdex@0.4.3 gate-codex ~/.codex/config.toml \
+  --pack official-first \
+  --trust-store ./trust-store.json \
+  --out ./gated-config.toml
+```
+
+The gated file keeps unrelated TOML sections (models, features, profiles) unchanged and removes every MCP section that is not ALLOW. `ASK` entries stay out unless you pass `--include-ask`, which should only be used when another approval layer exists.
+
+Review the difference before using it:
+
+```bash
+diff ~/.codex/config.toml ./gated-config.toml
+```
+
+TrustDex never edits `config.toml` in place. Replacing the original file, or pointing a Codex installation at the gated copy, is an explicit step you take after review.
+
+### 3. Re-run after every change
+
+MCP entries change when a package version is bumped, a launcher is swapped, or a new environment variable is passed. Re-run `inspect-codex` and `gate-codex` whenever `config.toml` changes; a CI job or a pre-commit hook in a dotfiles repository works well for this.
+
+The signed `snapshot`, `approve`, and `recheck` drift workflow in the [README](../README.md#capability-and-provenance-drift) currently accepts MCP JSON only. Extending it to Codex `config.toml` is tracked in the [roadmap](ROADMAP.md).
+
+### Fail-closed parsing
+
+TrustDex parses only the TOML constructs used by Codex MCP sections. An unsupported MCP key, nested subsection, or syntax is reported as an error instead of being skipped, so a configuration TrustDex cannot fully read never silently becomes ALLOW.
+
+### Skills and plugins
+
+Agent skills and plugin manifests can be inspected the same way:
+
+```bash
+npx trustdex@0.4.3 inspect-skill ./path/to/SKILL.md --pack strict
+npx trustdex@0.4.3 inspect-plugin ./path/to/plugin.json --pack strict
+```
+
+These report observable signals such as piped shell installers, references to sensitive paths, network URLs, and wildcard tool scopes. They do not prove a skill or plugin is safe.
+
+## Gate MCP configuration in CI
+
+Repositories that ship an MCP configuration for agents can gate it on every pull request with the [TrustDex GitHub Action](../README.md#github-action). Pin the action to a reviewed commit SHA.
+
+## How TrustDex is maintained with Codex
+
+TrustDex uses Codex as a reviewer and maintainer assistant, with the same trust boundary it asks users to apply:
+
+- [AGENTS.md](../AGENTS.md) holds the development rules and a **Review guidelines** section that Codex code review applies to TrustDex pull requests. The guidelines turn the project's security invariants (no silent ALLOW, no secret values in output, no provenance override of blocking signals, fail-closed parsing, pinned actions) into explicit review findings.
+- Codex suggestions are treated like any other contribution: they go through a pull request, must pass the cross-platform CI matrix and CodeQL, and are merged only after maintainer review.
+- Codex does not hold release credentials. npm publication uses Trusted Publisher OIDC with Sigstore provenance from `.github/workflows/publish.yml`, triggered by a maintainer.
+
+If you contribute with Codex or another coding agent, the same AGENTS.md rules apply to your changes.

package/docs/ROADMAP.md

@@ -19,6 +19,7 @@ TrustDex is early-stage. This roadmap communicates direction and is not a releas
 
 ## Later: expand interoperability
 
+- extend signed snapshot, approval, and recheck workflows to Codex `config.toml`
 - add adapters for additional agent runtimes and registries
 - publish a compatibility matrix backed by tests
 - define machine-readable decision output for CI and policy tooling
@@ -30,4 +31,4 @@ The project is seeking pilot users willing to share non-sensitive feedback about
 
 ## How to help
 
-Open a focused issue describing the use case and redacted configuration shape. For security-sensitive proposals, include the expected trust boundary and bypass cases.
+If you ran TrustDex on a real configuration, the **Pilot feedback** issue form is the fastest way to report results. Otherwise, open a focused issue describing the use case and redacted configuration shape. For security-sensitive proposals, include the expected trust boundary and bypass cases.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trustdex",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "A local-first trust, provenance, and review gate for AI agent tools, MCP servers, skills, and plugins.",
   "type": "module",
   "bin": {