docs: Define trusted-computer boundary by BenWestgate · Pull Request #59 · BenWestgate/python-codex32

BenWestgate · 2026-09-25T16:22:30Z

Define “trusted computer” once in SECURITY.md and link to it from the user guide, security model, and invariants. This removes three competing versions of the advice and keeps the user guide short.

The definition is this project's operational requirement, informed by Bitcoin Core rather than presented as a quotation. Encryption guidance follows Core v32.0's encryption dialog and wallet documentation: encryption cannot fully protect funds from malware. The offline-signing tutorial supports keeping the signing computer permanently disconnected; “until shutdown” is removed.

The disclosure invariant permits intentional recovery output while prohibiting unrelated disclosures. Timestamped rescans still capture a private descriptor from Core and re-import it over stdin; the invariant now describes that exact path. Computer/network requirements live in SECURITY.md, with invariant numbering preserved through a link. The guide retains its explicit wallet-encryption recommendation, and the original Python memory-limit paragraph is restored. Existing shorter CLI help and its matching test update remain. No runtime behavior or vulnerability-reporting criteria change.

Review size: six files, +39/−26 lines (previously +46/−29). The latest follow-up, 0d4ac62, applies the reviewer's direct wording for exclusive control and software trust. e2a95f1 addresses the other wording changes and clarifies the timestamped-rescan secret channel.

Validation: inspected the complete diff against the current PR base; checked new relative anchors, the three upstream source targets, policy resolution, line widths, and whitespace. No application tests were run solely for these prose edits. Fresh CI and peer review of this head remain required. Broader user-guide simplification and brittle help snapshots remain tracked by #194 and #195.

Fixes #4. AI tools assisted with this maintainer-directed update.

BenWestgate

AI-generated review (Claude), posted at the maintainer's request.

ACK b06aedb, nits only.

Invariant 6 now matches what create/secret/share/correct/xprv actually do.
Nit: the trusted-computer definition is written out three times (SECURITY.md, model.md, guide.md). Consider one definition in model.md and links elsewhere so they can't drift.

BenWestgate · 2026-09-27T03:17:11Z

On the “trusted computer” duplication nit: keep the short operational definition in all three places. SECURITY.md is the security-policy entry point and must stand alone; docs/security/model.md is the normative design rationale; docs/user/guide.md is the user-facing instruction. Cross-linking only to the model would make the security policy and user guide weaker when read in isolation. The wording is deliberately the same contract in each location; future drift is reviewable as a literal text diff. No code change warranted.

BenWestgate · 2026-09-27T22:47:07Z

Release-gate sequencing note: review/merge #57 before final review of this docs PR. #57 and #59 both touch docs/security/invariants.md, docs/security/model.md, and docs/user/guide.md; #57 owns the release-critical verify-before-mutate behavior/contract, while #59 is the trusted-computer/output-boundary clarification. After #57 lands, refresh #59 once against the integrated reviewability-v1 text and preserve its already-resolved 80-column CLI-help fix. This is a sequencing dependency, not a new defect in #59.

BenWestgate

AI-generated review, posted at the maintainer's request.

ACK 580b8f8.

BenWestgate · 2026-09-30T20:22:58Z

Agent release-gate review at exact head 580b8f8: the trusted-computer definition, intentional-vs-accidental output boundary, and shell/stdin guidance are consistent across SECURITY.md, the normative model/invariants, user guide, CLI help, and regression text. The repeated short definition is appropriate because each entry point must stand alone. Exact-head run 36471154686 succeeded. No remaining code/documentation blocker found; review after #57 so restore-boundary wording settles first.

BenWestgate

Codex current-head re-review: ACK ede98a8.

The security documentation now defines “trusted computer” consistently, distinguishes intentional recovery/export output from accidental secret disclosure, and warns that shell command text can persist even when stdin keeps secrets out of argv. The CLI footer matches that contract and the one prior help-text nit is resolved. Exact-head Python-package run 643 and Bitcoin Core wallet-fixture run 30 succeeded.

No code or security-contract blocker found; ready for human integration review after #23.

BenWestgate

Codex current-head review at ede98a8: no findings. The trusted-computer/offline boundary and secret-output exceptions are made explicit without weakening argument/logging protections.

BenWestgate

AI-assisted current-head review: ACK ede98a8. The trusted-computer definition is consistent across SECURITY.md, the model, invariants, and user guide; invariant 6 now correctly distinguishes intentional recovery/export output from accidental logging/diagnostics; and the CLI safety footer warns about shell command text and redirected sources without claiming stdin is magically non-retentive. The restack preserves the master-xprv/private-descriptor channel boundaries. Exact-head Python/Core CI is green and all review threads are resolved.

BenWestgate · 2026-10-23T21:31:01Z

@codex review

chatgpt-codex-connector · 2026-10-23T21:31:15Z

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-27T05:29:57.440451Z	`e2a95f1`	New commits

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

chatgpt-codex-connector · 2026-10-23T21:32:11Z

Codex Review: Didn't find any major issues. Nice work!

Reviewed commit: ede98a8e07

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

BenWestgate · 2026-10-24T07:59:09Z

AI-assisted update cf5d1a5: simplified the user guide, SECURITY.md, and CLI help; clarified the offline period as until shutdown. Detailed guarantees remain in the security model. Broader cleanup: #194; help-snapshot tests: #195. Current-head CI pending.

BenWestgate · 2026-10-24T08:52:30Z

Keep the technical trusted-computer boundary in the security model and invariants.
Explain the same risks plainly in SECURITY.md and the user guide.

Should we repeat ourselves, why or why not?

BenWestgate · 2026-10-24T09:03:43Z

AI-assisted response: A short warning belongs where users act; the technical rationale belongs only in the security model. Keep one actionable sentence in the guide, a brief boundary in SECURITY.md, and link to the model. No repeated technical paragraphs.

BenWestgate · 2026-10-24T09:07:49Z

@codex review

chatgpt-codex-connector · 2026-10-24T09:08:40Z

Codex Review: Didn't find any major issues. Chef's kiss.

Reviewed commit: cf5d1a57e5

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Keep the trusted-computer definition in the technical model and plain advice in the user documents. Limit the requirement to sensitive work and state the intended-output exception without repeating its rationale. Refs #4, #59. The focused CLI help test and diff checks pass.

Make the secret-output invariant literal about intentional recovery/export output, define the trusted-computer boundary consistently, and warn that shell command text can be retained even when stdin is safe from argv exposure. Update the shared CLI safety footer and its exact-help regression. Validation: focused help regression; Ruff check/format; strict mypy for the parser; git diff --check. The full generic-HRP module still reaches the pre-existing bip32 test dependency tracked by #3/#6 and fixed by #7. fixes #4

Use plain language in security guidance and CLI help. Keep the security model's detailed constraints and correct the help test. refs #4

Keep the trusted-computer definition in the technical model and plain advice in the user documents. Limit the requirement to sensitive work and state the intended-output exception without repeating its rationale. Refs #4, #59. The focused CLI help test and diff checks pass.

BenWestgate

Remove "until you shut it down" the strongest assurance is an offline PC that never goes back online. Such as CryoStick from Bails.

BenWestgate · 2026-10-27T04:58:14Z

Nit: the trusted-computer definition is written out three times (SECURITY.md, model.md, guide.md). Consider one definition in model.md and links elsewhere so they can't drift.

The trusted computer definition should be written in SECURITY.md and linked to by guide.md or summarized in one sentence there.

Define trusted computer once in SECURITY.md and link the model, invariants and user guide to it. Ground encryption and permanent offline-signing advice in Bitcoin Core v32.0 sources, removing the shutdown-only wording and repeated output explanation. No runtime or reportability changes. Checked the complete diff, relative anchors, upstream source links, policy resolution, line widths and whitespace. Application tests were not run for prose-only edits. Refs #4, #59.

BenWestgate · 2026-10-27T05:06:31Z

AI-assisted update at the maintainer's request, following the merged tool-neutral contribution policy.

Addressed the deduplication feedback and the latest offline-computer review in 4e3bd9f:

SECURITY.md defines trusted computer once; the guide, model and invariants link to it.
Core v32.0's encryption dialog and wallet docs support the malware warning. This project's definition is not presented as an upstream quotation.
The dedicated offline signing computer never connects to a network, as required by Core's offline-signing tutorial. Removed the “until shutdown” advice.
Removed the repeated output explanation from the model. The PR shrinks from +46/−29 to +36/−27 lines.

Checked the complete diff, new local anchors, the three upstream source targets, policy resolution, whitespace and line widths. No application tests were run for this prose-only follow-up. Fresh CI/review must cover this head. The broader guide review and help-snapshot cleanup remain tracked by #194/#195; those two older threads remain open rather than claiming those tasks are complete.

BenWestgate

changes requested.

Require exclusive control, centralize network requirements, and make clear that every sensitive operation uses the trusted computer. Restore the guide's explicit encryption recommendation and the original Python memory limitation. Shorten the malware and intentional-output wording. Timestamped rescans still capture a private descriptor from Core and re-import it over stdin; describe that path rather than removing its secret-channel requirement. Preserve invariant numbering with a link. Checked the exact rescan call path, documentation diff, anchors, line widths, whitespace and policy resolution. No application tests were run for prose-only changes. Refs #4, #59.

Apply the reviewer's active wording while preserving exclusive control and trust in the operating system and other software. Meaning unchanged. Checked the two-line prose diff and line widths; no runtime tests needed. Refs #59.

BenWestgate

LGTM

we will do a polish up later on the SECURITY docs before v1 but they're correct and good enough for now.

This comment has been minimized.

Sign in to view

BenWestgate mentioned this pull request Sep 25, 2026

docs: Prepare the v1 review handoff #38

Open

BenWestgate commented Sep 25, 2026

View reviewed changes

Comment thread src/codex32/_cli_parser.py Outdated

This was referenced Sep 28, 2026

wallet: Require the recorded fingerprint before import #57

Merged

reviewability: restore the <5000 installed-package budget on the integrated v1 tree #61

Closed

Remove pre-review CLI dead code #46

Merged

BenWestgate force-pushed the codex/4-security-boundary-docs branch from 59a29bc to 580b8f8 Compare September 28, 2026 19:16

BenWestgate commented Sep 29, 2026

View reviewed changes

This was referenced Sep 30, 2026

Tighten v1 security invariants and define the trusted-computer boundary #4

Open

Security audit: python-codex32 findings #20

Open

BenWestgate marked this pull request as draft October 1, 2026 06:03

BenWestgate force-pushed the codex/4-security-boundary-docs branch from 580b8f8 to ede98a8 Compare October 2, 2026 01:06

BenWestgate changed the base branch from reviewability-v1 to 20-security-audit-docs October 2, 2026 01:06

BenWestgate mentioned this pull request Oct 2, 2026

release: Qualify packages before publishing #52

Open

BenWestgate commented Oct 3, 2026

View reviewed changes

BenWestgate commented Oct 6, 2026

View reviewed changes

BenWestgate mentioned this pull request Oct 6, 2026

docs: Close adversarial audit tracking gaps #127

Open

BenWestgate commented Oct 7, 2026

View reviewed changes

BenWestgate added this pull request to stack #192 October 24, 2026 06:16

BenWestgate force-pushed the codex/4-security-boundary-docs branch from ede98a8 to 818144b Compare October 24, 2026 06:21

This was referenced Oct 24, 2026

docs: Make recovery guide easier to follow #194

Open

test: Remove brittle full-help snapshots #195

Open

BenWestgate self-assigned this Oct 24, 2026

BenWestgate marked this pull request as ready for review October 24, 2026 14:47

BenWestgate force-pushed the codex/4-security-boundary-docs branch 2 times, most recently from 7433ee9 to c0d9ebf Compare October 27, 2026 04:16

Base automatically changed from 20-security-audit-docs to codex/63-private-core-descriptors October 27, 2026 04:24

BenWestgate added 5 commits October 26, 2026 23:24

docs: keep CLI safety footer within 80 columns

2a7f444

test: match shortened CLI safety footer

599ae25

docs: Make recovery safety advice clearer

38bccea

Use plain language in security guidance and CLI help. Keep the security model's detailed constraints and correct the help test. refs #4

BenWestgate force-pushed the codex/4-security-boundary-docs branch from c0d9ebf to 974657f Compare October 27, 2026 04:24

BenWestgate commented Oct 27, 2026

View reviewed changes

Comment thread SECURITY.md Outdated

docs: Use direct trusted-computer wording

0d4ac62

Apply the reviewer's active wording while preserving exclusive control and trust in the operating system and other software. Meaning unchanged. Checked the two-line prose diff and line widths; no runtime tests needed. Refs #59.

BenWestgate commented Oct 27, 2026

View reviewed changes

BenWestgate merged commit f976e44 into codex/63-private-core-descriptors Oct 27, 2026
20 checks passed

BenWestgate deleted the codex/4-security-boundary-docs branch October 27, 2026 05:42

Conversation

BenWestgate commented Sep 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment has been minimized.

BenWestgate left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

BenWestgate commented Sep 27, 2026

Uh oh!

BenWestgate commented Sep 27, 2026

Uh oh!

BenWestgate left a comment

Choose a reason for hiding this comment

Uh oh!

BenWestgate commented Sep 30, 2026

Uh oh!

BenWestgate left a comment

Choose a reason for hiding this comment

Uh oh!

BenWestgate left a comment

Choose a reason for hiding this comment

Uh oh!

BenWestgate left a comment

Choose a reason for hiding this comment

Uh oh!

BenWestgate commented Oct 23, 2026

Uh oh!

chatgpt-codex-connector Bot commented Oct 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codex Review Summary

Uh oh!

chatgpt-codex-connector Bot commented Oct 23, 2026

Uh oh!

BenWestgate commented Oct 24, 2026

Uh oh!

BenWestgate commented Oct 24, 2026

Uh oh!

BenWestgate commented Oct 24, 2026

Uh oh!

BenWestgate commented Oct 24, 2026

Uh oh!

chatgpt-codex-connector Bot commented Oct 24, 2026

Uh oh!

BenWestgate left a comment

Choose a reason for hiding this comment

Uh oh!

BenWestgate commented Oct 27, 2026

Uh oh!

BenWestgate commented Oct 27, 2026

Uh oh!

BenWestgate left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

BenWestgate left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

BenWestgate commented Sep 25, 2026 •

edited

Loading

chatgpt-codex-connector Bot commented Oct 23, 2026 •

edited

Loading