@zieglar/pi-chat-exchange 0.2.1 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -2,136 +2,68 @@
2
2
 
3
3
  English | [简体中文](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/README.zh-CN.md)
4
4
 
5
- Pi Chat Exchange (CE) lets ChatGPT and Pi exchange durable messages through explicit tools. It stores messages, provides an authorized inbox, separates metadata from payload access, and records reception receipts (ACKs). Sending a message does not authorize its execution or prove task completion.
5
+ Pi Chat Exchange (CE) lets ChatGPT and Pi exchange durable messages through explicit tools. Use it to pass a question, plan or result between the two applications while choosing which messages each side may read. Sending a message does not authorize a task or prove completion.
6
6
 
7
7
  <a id="当前能力与典型用法"></a>
8
8
 
9
9
  ## Features
10
10
 
11
- - SQLite-backed messages with scoped idempotency keys and audit evidence.
12
- - Independent permissions for sending, discovering messages, reading payloads and recording ACKs.
13
- - Stable endpoints for individual Pi sessions, with explicit registration, activation, deactivation and revocation.
14
- - Secure MCP Tunnel management, plus a separate Desktop stdio plugin path.
15
- - Rust Native SQLite is the only default persistence driver; `node:sqlite` remains only as an explicitly selected, non-production compatibility driver.
16
-
17
- CE does not provide automatic task scheduling, inbox draining or exactly-once delivery/execution. `DELIVERY_UNKNOWN != CANCELLED`; a missing ACK does not justify retrying an operation.
11
+ - SQLite-backed messages, scoped idempotency keys and audit evidence.
12
+ - Authorized inbox discovery, separate metadata/payload access, and optional reception receipts (ACKs).
13
+ - Explicit Pi Session binding and multi-session registration.
14
+ - Secure MCP Tunnel management and a separate ChatGPT Desktop stdio connection.
15
+ - Rust Native SQLite with pinned trust and explicit installation/readiness commands.
18
16
 
19
17
  ## Requirements and support
20
18
 
21
- Version **0.2.1** includes Native as the default persistence driver, readiness checks and explicit driver management. It requires Node **`>=22.19.0`**, matching Pi 1.3.0's `engines.node`. Local Node 22 / Pi 1.3.0 first-run and persistence checks passed. Linux x64 hosted checks passed **227/227** on both Node **22.19.0** and **24.22.2**; these results do not qualify cloud transport.
22
-
23
- The historical npm **0.2.0** distribution qualification covers **Node 24.21.0 / Pi 1.3.0 / macOS arm64**, with cloud transport **NOT_VERIFIED**. The 0.2.1 results do not change that historical scope.
19
+ Use **Pi 1.3.0**, **Node >=22.19.0** and a Store-supported platform: **macOS arm64 or Linux x64 GNU**. Filesystem, ownership and runtime admission checks still apply. Other Native artifacts do not establish Store support; Windows Native is unsupported and WSL2 integration remains unverified.
24
20
 
25
- Pi 1.3.0's installed manifest declares **Node >=22.19.0**. Native uses its bundled SQLite and requires Node-API >=8, rather than the built-in SQLite version. Tested versions are not a compatibility promise for every subsequent release. The explicit compatibility `node:sqlite` path retains its own candidate-version and known-defect restrictions. See [runtime evidence](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/runtime-support.md) for the matrix and limits.
21
+ Version **0.2.1** is published on npm. An actual Registry installation passed isolated Pi 1.3.0 / Node 22.19.0 loading and persistence checks on macOS arm64. Linux x64 Native checks passed 227/227 on Node 22.19.0 and 24.22.2. **Real Cloud transport and the complete ChatGPT ↔ Pi exchange remain unverified.** See [runtime support](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/runtime-support.md) for the tested matrix and limits; the engine range is not exhaustive qualification.
26
22
 
27
- | Platform | Current Native evidence | Scope |
28
- |---|---|---|
29
- | macOS arm64 | Artifact/conformance and Store integration | Does not certify every client or cloud workflow |
30
- | Linux x64 GNU | Artifact/conformance, Store integration and hosted checks | 227/227 on Node 22.19.0 and 24.22.2; cloud unverified |
31
- | macOS x64 | Artifact/conformance only | Store integration not established |
32
- | Linux arm64 GNU | Artifact/conformance only | Store integration not established |
23
+ This working tree prepares local candidate **0.2.2**. Explicit `CE_TUNNEL_CLIENT_PATH` delegates trust to a user-managed client installation, including group-writable Homebrew ancestors; automatic discovery stays strict. Installation writers may replace a program that can run as you and read Tunnel credentials. Install the candidate tarball with npm into a dedicated prefix, then register the installed package directory with Pi; see Getting started. This is not a Registry installation. The npm command below still selects published 0.2.1 and its old admission rules.
33
24
 
34
- The Store allowlist remains macOS arm64 / Linux x64. Runtime admission also checks SQLite behavior, filesystem safety and ownership. See [Native SQLite](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/native-sqlite.md) and [runtime qualification](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/runtime-support.md).
25
+ Candidate evidence: [compatibility matrix](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/compatibility/README.md). Client 0.0.19 has source-matched macOS arm64 legacy-identity manual bidirectional Cloud E2E; Linux x64 CI covers synthetic local lifecycle. Historical 0.0.16 evidence is runtime-scoped; 0.0.18 and real namespaced Cloud remain NOT_VERIFIED. Independent latest monitoring and actual same-run publication integration remain NOT_VERIFIED. Managed profiles explicitly set `MCP_STDIO_FAILURE_POLICY=exit`: on 0.0.19 child failure the client exits, with no automatic respawn or recovery; inspect ownership and recover explicitly before restarting.
35
26
 
36
27
  <a id="安装-pi-扩展"></a>
28
+ <a id="选择连接方式"></a>
37
29
 
38
- ## Installation and upgrades
30
+ ## Quick start
39
31
 
40
- Use an approved Node executable to run Pi **1.3.0**, then install the exact version:
32
+ With Pi already installed, run in your **system terminal**:
41
33
 
42
34
  ```sh
43
- node --version
44
35
  pi install npm:@zieglar/pi-chat-exchange@0.2.1
45
36
  pi list
37
+ pi
46
38
  ```
47
39
 
48
- This is Pi's managed npm source syntax; it is not a standalone `ce` command. Extensions run with your user permissions. Review the package and its source before installation. Registry publication proves availability, not successful cloud setup on your machine.
49
-
50
- For a prebuilt tarball or a dedicated host prefix, follow [independent installation](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/independent-install.md). Before upgrading, stop the owned Tunnel, confirm `STOPPED`, deactivate affected bindings, and exit affected Pi hosts. Preserve the Store and credentials; check schema compatibility before rollback. Never delete ownership or lock files to force an upgrade.
51
-
52
- <a id="选择连接方式"></a>
53
-
54
- ## Quick start
55
-
56
- Start Pi under the approved Node runtime. Run `/ce-native status`; if the trusted driver is missing, run `/ce-native install`, then exit and restart Pi before setup or messaging. CE does not download Native automatically. In the restarted interactive session:
57
-
58
- ```text
59
- /ce-tunnel doctor
60
- /ce-tunnel setup
61
- /reload
62
- /ce-tunnel activate
63
- /ce-status
64
- ```
65
-
66
- Setup must explicitly grant messaging to the current session under Advanced · Messaging. Saving transport settings alone does not authorize messaging. A first reload can refuse a missing mapping; explicitly activate after setup. Activation does not start transport.
67
-
68
- A real Tunnel needs a separately trusted client, a configured ChatGPT connection, the parent process opt-in `CE_TUNNEL_BACKGROUND_ALLOW=1`, and an explicit `/ce-tunnel start`. Follow [getting started](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/getting-started.md) and [Tunnel setup](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/tunnel-setup.md). The Desktop stdio route has separate [installation steps](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/chatgpt-installation.md).
40
+ In the **Pi TUI**, run `/ce-native status`. If the trusted driver is missing, run `/ce-native install`, then exit and restart Pi. Check `/ce-native verify` reports `READY` before messaging. Native binaries are not bundled in npm; CE never downloads them automatically or falls back to `node:sqlite`.
69
41
 
70
- ## Configuration
42
+ Continue with **[Getting started: installation to your first exchange](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/getting-started.md)**. It covers the separately trusted Tunnel client, parent environment, explicit Setup messaging grants, `/reload` → activate → Start, exact recipient labels, payload reads and safe Stop. Setup Save alone does not authorize messaging; activation does not start transport. The [Desktop stdio guide](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/chatgpt-installation.md) describes the separate local connection.
71
43
 
72
- Use the setup UI to write private configuration. `CE_TUNNEL_PROFILE` selects an absolute profile **file** path, `CE_NODE_PATH` selects the MCP child's qualified Node executable, and `CE_TUNNEL_CLIENT_PATH` selects a trusted absolute client executable. Neither child selection nor a version label qualifies the already running Pi host.
73
-
74
- Payload reads and ACKs require separate grants. Keep credentials in the operator-owned credential files; do not place them in messages, screenshots or issue reports. See [configuration and commands](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/getting-started.md) and the [Pi extension reference](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/pi-extension/README.md).
44
+ Before upgrading an existing installation, stop the owned Tunnel and verify `STOPPED`, release affected local bindings, then exit affected Pi hosts. Preserve the Store and credentials; do not delete ownership or lock files to force an upgrade.
75
45
 
76
46
  <a id="多项目多-session"></a>
77
-
78
- ## Commands and message workflow
79
-
80
- | Command/tool | Purpose |
81
- |---|---|
82
- | `/ce-status` | Inspect the current Pi/CE identity and ownership state |
83
- | `/ce-tunnel doctor` | Inspect installation/runtime qualification without starting transport |
84
- | `/ce-tunnel start`, `/ce-tunnel stop`, `/ce-tunnel status` | Explicitly manage and inspect the owned transport |
85
- | `/ce-tunnel sessions`, `register`, `convert`, `revoke` | Manage session registration under the documented policy |
86
- | `/ce-tunnel activate`, `/ce-tunnel deactivate` | Bind or normally release the current session |
87
- | `ce_send`, `ce_inbox_list`, `ce_read` | Send, discover and inspect message metadata |
88
- | `ce_read_payload`, `ce_ack` | Separately authorized payload access and reception receipt |
89
-
90
- For a received message, discover its ID, read metadata, request payload access only when needed, and record an ACK only under its separate grant. A reply is a new Message. ACK means reception receipt; it does not establish delivery, read, processing or completion. See [multi-session usage](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/multi-session-usage.md) and the [ACK contract](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/delivery-ack-contract.md).
91
-
92
- ## Architecture and responsibilities
93
-
94
- Task governance, policy, recovery and completion decisions stay with the external workflow or operator that uses CE. CE owns message delivery/lifecycle rules, durable evidence and reconciliation. Pi owns sessions, runtime and provider transport. CE's adapters use the same Host/Storage authority; tool labels and model claims cannot grant permissions.
95
-
96
- Recovery markers are not locks or fencing tokens. Changing models must not replay a task that has already produced effects. See [architecture](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/architecture.md) for component responsibilities and the distinction between implemented messaging tools and the broader protocol model.
97
-
98
- ## SQLite Native driver
99
-
100
- The independent immutable Native Release is [**`ce-sqlite-v0.1.0`**](https://github.com/zieglar/pi-packages/releases/tag/ce-sqlite-v0.1.0), with ABI **1**, bundled SQLite **3.54.1**, and source SHA **`a8386aafd657c84825b2905847f34a43d5b91e1e`**. Version 0.2.1 uses this same independent Native release; its binaries are not bundled in npm.
101
-
102
- In 0.2.1, the default is Native, including when no selection file exists. `node:sqlite` is loaded lazily only after an explicit selection; Native trust, load or initialization failure is closed and never falls back. Production `NATIVE_COMPAT` pins now trust immutable Release `427441708`: four platform SHA-256 values verified against `SHA256SUMS`, with seven attestation subjects bound to that source. Version 0.2.1 includes these fixed trust pins.
103
-
104
- ## Native readiness and management (0.2.1)
105
-
106
- Run `/ce-native status` or `/ce-native verify` to inspect Native without downloads or selection changes. Explicit `/ce-native install` installs only the trusted default version and verifies it before changing selection; restart Pi afterward. `/ce-native repair confirm` is explicit repair. `/ce-native check-updates` reads GitHub Release metadata only: `latest` never becomes trusted or changes selection. CE never automatically downloads, repairs or upgrades Native.
107
-
108
- Extension load is read-only: it never downloads, creates a Store or starts Tunnel. Pi and management commands remain available when Native is not ready; Store, Tunnel start and messaging fail closed. `/ce-tunnel start` revalidates Native and Store admission before manager/profile/process effects; refusal includes a `CE_NATIVE_*` code and `/ce-native` hint. Status reports `native=<STATE> (code)` separately from transport and never infers `STOPPED`; stop remains available for cleanup.
109
-
110
- Windows Native is unsupported (`CE_NATIVE_TARGET_UNSUPPORTED`); no Windows binary exists and CE never tries a Linux binary there. Run Linux Node.js, Pi and CE inside WSL2 to select the real Linux x64/arm64 asset. Keep an active SQLite Store on the Linux filesystem rather than `/mnt/c` or other Windows mounts. WSL2 is recommended but integration testing here has not verified it; platform tests cover target mapping and Windows refusal only. Existing Store filesystem rules still apply. See [Native management](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/native-management.md) for the warning, commands and recovery limits.
111
-
112
47
  <a id="边界与验证"></a>
113
48
 
114
- ## Security and troubleshooting
115
-
116
- Configured, Pi-bound, connected and demonstrated message exchange are different states. Transport health does not prove message authority. Unknown outcomes remain unknown until evidence resolves them; do not retry blindly, take over an owner or delete the Store.
117
-
118
- Start with [operations and troubleshooting](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/operations.md). Share error codes and redacted metadata, never payloads, credentials, capabilities or full raw logs. Detailed boundaries are in [protocol v2](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/protocol-v2.md), [ownership](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/ownership-contract.md), [storage](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/storage-contract.md) and [storage security](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/storage-security.md).
49
+ ## Limits and safe operation
119
50
 
120
- <a id="阅读导航"></a>
51
+ CE does not automatically schedule tasks or drain inboxes. A shared ChatGPT endpoint does not isolate conversations. Payload reads and ACKs require their own grants; payload text is untrusted data and may enter model history.
121
52
 
122
- ## Development and contribution
53
+ ACK records reception only, not delivery, reading, processing or task completion. CE provides no exactly-once delivery/execution guarantee. `DELIVERY_UNKNOWN != CANCELLED`; missing ACK or timeout does not authorize blind retry or a new-key resend. Keep the original Message ID/key and inspect evidence first.
123
54
 
124
- From the repository root, with the qualified Node runtime and pnpm **12.9.1**:
55
+ Closing Manager or exiting Pi does not stop the detached Tunnel client. Use `/ce-tunnel stop`, then `/ce-tunnel status` to verify `STOPPED`. Keep credentials and capabilities out of messages, screenshots and reports.
125
56
 
126
- ```sh
127
- pnpm install --frozen-lockfile --ignore-scripts
128
- pnpm --dir packages/pi-chat-exchange run verify
129
- pi -e ./packages/pi-chat-exchange/pi-extension/index.ts
130
- ```
57
+ <a id="阅读导航"></a>
131
58
 
132
- The extension imports `dist/`. Rebuild after source edits; `/reload` does not compile TypeScript. Optional client and real-host tests need their documented prerequisites and are separate from default tests. Follow [development and release operations](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/operations.md) and the [bilingual documentation guide](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/documentation.md).
59
+ ## Documentation
133
60
 
134
- The npm package contains the prebuilt extension and runtime files. Detailed operating guides are linked on GitHub; the npm tarball does not include `docs/`.
61
+ - [Native management](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/native-management.md) and [Native SQLite](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/native-sqlite.md).
62
+ - [Tunnel setup and troubleshooting](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/tunnel-setup.md).
63
+ - [Multiple Sessions](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/multi-session-usage.md), [Pi tools](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/pi-extension/README.md) and [ACK contract](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/delivery-ack-contract.md).
64
+ - [Operations / source development](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/operations.md). The prebuilt npm install needs no repository or compiler.
65
+ - [Independent Host / tarball installation](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/independent-install.md), with current0.2.1 alternatives and a separate historical0.2.0 record.
66
+ - [Architecture](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/architecture.md), [storage security](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/storage-security.md) and [bilingual documentation index](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/documentation.md).
135
67
 
136
68
  ## License
137
69
 
@@ -23,7 +23,7 @@ import { observeTransport } from "./debug-transport.js";
23
23
  import { PING_TOOL_NAME, PingArgsSchema, PingResultSchema, defaultHostLabel, ping } from "./ping.js";
24
24
  import { callMessagingTool, CE_ACK_TOOL, isAckToolName, isMessagingToolName, MESSAGING_TOOLS, } from "./messaging-tools.js";
25
25
  export const SERVER_NAME = "pi-chat-exchange";
26
- export const SERVER_VERSION = "0.2.1";
26
+ export const SERVER_VERSION = "0.2.2";
27
27
  const PING_TOOL = {
28
28
  name: PING_TOOL_NAME,
29
29
  description: "Read-only liveness probe for the pi-chat-exchange service. " +
@@ -9,6 +9,7 @@
9
9
  * structural field path).
10
10
  */
11
11
  import { isAbsolute, normalize } from "node:path";
12
+ import { TUNNEL_ID_PATTERN as MANAGED_TUNNEL_ID } from "../tunnel/tunnel-id.js";
12
13
  import { LEASE_MAX_TTL_SECONDS, LEASE_MIN_TTL_SECONDS } from "../storage/ownership.js";
13
14
  export const MCP_BINDING_CONFIG_VERSION = 1;
14
15
  export const MCP_DEFAULT_LEASE_TTL_SECONDS = 120;
@@ -138,7 +139,6 @@ function debugExecutionGuardPolicy(value) {
138
139
  throw new McpBindingConfigError("debugExecutionGuard.enabled");
139
140
  return Object.freeze({ enabled: fields.enabled });
140
141
  }
141
- const MANAGED_TUNNEL_ID = /^tunnel_[A-Za-z0-9]{8,}$/;
142
142
  const MANAGED_ORGANIZATION_ID = /^org-[A-Za-z0-9]{1,128}$/;
143
143
  /** Managed provenance is validated with the same label discipline as every
144
144
  * other field: strict identity shapes, no credential-shaped strings. */
@@ -22,7 +22,7 @@ export function diagnoseInstallation(options = {}) {
22
22
  export function installationDiagnosticMessage(result) {
23
23
  return `ce-tunnel doctor: Pi host=${result.host} (in-memory SQLite/runtime check); MCP child=${result.child}; client=${result.client}. ` +
24
24
  "Client trust is metadata only, not compatibility or connectivity. No client executed; no profile/Store/transport changes. " +
25
- "For a missing client, install separately; for rejected trust, repair the private installation and its ancestors/ACLs or select a trusted absolute CE_TUNNEL_CLIENT_PATH outside projects. Never use PATH fallback or relax trust. " +
25
+ "For a missing client, install separately. CE_TUNNEL_CLIENT_PATH explicitly trusts a user-managed client and permits group-writable ancestors; automatic discovery stays strict. Check the normalized absolute path, executable file, owner, world-write, ACL and project restrictions. Do not change Homebrew permissions/ACLs or bypass Gatekeeper for CE; no PATH fallback. " +
26
26
  "Select an independently qualified MCP child with CE_NODE_PATH. " + hostRuntimeRepairMessage() +
27
27
  ". Installation checks are not transport, delivery, ACK or completion evidence.";
28
28
  }
@@ -6,6 +6,7 @@ import { MISE_DISCOVERY_NODE_VERSIONS, probeSqliteCapabilities, assertRuntimeEli
6
6
  import { resolveSqliteDriver } from "../storage/sqlite-driver-selection.js";
7
7
  import { createNodeSqliteDriver } from "../storage/sqlite-driver-node.js";
8
8
  import { createRustNativeDriver } from "../storage/sqlite-driver-rust.js";
9
+ import { resolveWrapperIdentityEvidence } from "./wrapper-identity.js";
9
10
  /** These are locations, not PATH search. Every discovered file still needs admission. */
10
11
  const SYSTEM_DIRECTORIES = ["/usr/local/bin", "/usr/bin", "/bin", "/opt/homebrew/bin"];
11
12
  export class ExecutableRefusal extends Error {
@@ -56,7 +57,7 @@ function assertDarwinAclSafe(path) {
56
57
  }
57
58
  /** Admission is deliberately before probing. Same-account filesystem mutation is
58
59
  * outside this boundary; a private installation is required, not a signature claim. */
59
- function admitPath(path, options, kind) {
60
+ function admitPath(path, options, kind, explicitClient = false) {
60
61
  try {
61
62
  if (!isAbsolute(path) || normalize(path) !== path || /[\x00-\x1f\x7f]/.test(path))
62
63
  untrusted();
@@ -78,7 +79,11 @@ function admitPath(path, options, kind) {
78
79
  assertDarwinAclSafe(candidate);
79
80
  // OS-owned sticky temp roots protect independently owned private children.
80
81
  const stickyRoot = stat.isDirectory() && stat.uid === 0 && (stat.mode & 0o1000) !== 0;
81
- if ((stat.mode & 0o022) !== 0 && !stickyRoot)
82
+ // Explicit client selection delegates ancestor group writers to the user.
83
+ // File writes, world writes, owner and ACL checks remain strict; Node and
84
+ // Native callers never receive this client-only directory exception.
85
+ const unsafeWrites = explicitClient && stat.isDirectory() ? 0o002 : 0o022;
86
+ if ((stat.mode & unsafeWrites) !== 0 && !stickyRoot)
82
87
  untrusted();
83
88
  }
84
89
  const parent = dirname(candidate);
@@ -166,6 +171,13 @@ export function resolveApprovedNode(options = {}) {
166
171
  }
167
172
  return undefined;
168
173
  }
174
+ function admitExplicitTunnelClient(path, options) {
175
+ const canonical = admitPath(path, options, "executable", true);
176
+ resolveWrapperIdentityEvidence(canonical, target => {
177
+ admitPath(target, options, "executable", true);
178
+ });
179
+ return canonical;
180
+ }
169
181
  /** Diagnostic-only closed outcome. Same runtime admission, retaining discovery
170
182
  * refusals instead of laundering rejected installations as absent. Explicit
171
183
  * overrides are authoritative: even an absent override is a refusal. */
@@ -173,7 +185,7 @@ export function diagnoseTunnelClient(options = {}) {
173
185
  const env = options.env ?? {};
174
186
  if (env.CE_TUNNEL_CLIENT_PATH !== undefined) {
175
187
  try {
176
- admitExecutable(env.CE_TUNNEL_CLIENT_PATH, options);
188
+ admitExplicitTunnelClient(env.CE_TUNNEL_CLIENT_PATH, options);
177
189
  return "TRUSTED_METADATA_ONLY";
178
190
  }
179
191
  catch {
@@ -205,7 +217,7 @@ export function diagnoseTunnelClient(options = {}) {
205
217
  export function resolveTunnelClient(options = {}) {
206
218
  const env = options.env ?? {};
207
219
  if (env.CE_TUNNEL_CLIENT_PATH !== undefined)
208
- return admitExecutable(env.CE_TUNNEL_CLIENT_PATH, options);
220
+ return admitExplicitTunnelClient(env.CE_TUNNEL_CLIENT_PATH, options);
209
221
  for (const directory of options.systemDirectories ?? SYSTEM_DIRECTORIES) {
210
222
  try {
211
223
  return admitExecutable(join(directory, "tunnel-client"), options);
@@ -0,0 +1,53 @@
1
+ import { readFileSync, statSync } from "node:fs";
2
+ import { normalize } from "node:path";
3
+ const MAX_WRAPPER_BYTES = 4096;
4
+ const SHEBANG_RE = /^#!(\/[^\s\u0000]+)$/;
5
+ // Double quotes still expand dollars and backticks; those are not literal paths.
6
+ const WRAPPER_EXEC_RE = /^exec "(\/[^"\\\r\n\u0000$`]+)" "\$@"$/;
7
+ export function resolveWrapperIdentityEvidence(clientPath, validateExecTarget) {
8
+ let text;
9
+ try {
10
+ const stat = statSync(clientPath);
11
+ if (!stat.isFile() || stat.size === 0 || stat.size > MAX_WRAPPER_BYTES)
12
+ return undefined;
13
+ text = readFileSync(clientPath, "utf8");
14
+ }
15
+ catch {
16
+ return undefined;
17
+ }
18
+ if (!text.startsWith("#!"))
19
+ return {};
20
+ const lines = text.split("\n");
21
+ const shebang = SHEBANG_RE.exec((lines[0] ?? "").replace(/\r$/, ""));
22
+ const shellPrefix = shebang !== null && /^[ -~]+$/.test(shebang[1]) && normalize(shebang[1]) === shebang[1]
23
+ ? shebang[1]
24
+ : undefined;
25
+ const evidence = shellPrefix === undefined ? {} : { shellPrefix };
26
+ // The entire body must be one strict exec line, with only comments/blanks
27
+ // alongside it. Heredocs, extra statements and ambiguous argv yield no target.
28
+ const meaningful = lines.slice(1).filter((line) => {
29
+ const trimmed = line.trim();
30
+ return trimmed !== "" && !trimmed.startsWith("#");
31
+ });
32
+ if (meaningful.length !== 1)
33
+ return evidence;
34
+ const execMatch = WRAPPER_EXEC_RE.exec(meaningful[0]);
35
+ if (execMatch === null)
36
+ return evidence;
37
+ const target = execMatch[1];
38
+ if (!/^[ -~]+$/.test(target) || normalize(target) !== target)
39
+ return evidence;
40
+ // Admission must reject an invalid literal target before the identity-only
41
+ // parser can omit it. Do not replace the argv spelling with its canonical path.
42
+ validateExecTarget?.(target);
43
+ try {
44
+ if (!statSync(target).isFile())
45
+ return evidence;
46
+ }
47
+ catch {
48
+ return evidence;
49
+ }
50
+ evidence.execTarget = target;
51
+ return evidence;
52
+ }
53
+ //# sourceMappingURL=wrapper-identity.js.map
@@ -165,7 +165,9 @@ import { chmodSync, closeSync, fstatSync, lstatSync, mkdirSync, openSync, readdi
165
165
  import { homedir } from "node:os";
166
166
  import { dirname, isAbsolute, join, normalize } from "node:path";
167
167
  import { TunnelRefusal } from "./codes.js";
168
+ import { TUNNEL_ID_PATTERN } from "./tunnel-id.js";
168
169
  import { resolveTunnelClient } from "../runtime/executables.js";
170
+ import { resolveWrapperIdentityEvidence } from "../runtime/wrapper-identity.js";
169
171
  import { createHealthCompletionRecorder } from "./health.js";
170
172
  import { checkKeyFileRequirements, childEnvironment } from "./profile.js";
171
173
  import { DEFAULT_TUNNEL_TIMING, initialTunnelState, nextTunnelState, } from "./state.js";
@@ -329,7 +331,7 @@ export function parseTunnelProfile(text) {
329
331
  default: throw new TunnelRefusal("CE_TUNNEL_PROFILE_INVALID", tag);
330
332
  }
331
333
  }
332
- if (found.tunnelId === undefined || !/^tunnel_[A-Za-z0-9]{8,}$/.test(found.tunnelId)) {
334
+ if (found.tunnelId === undefined || !TUNNEL_ID_PATTERN.test(found.tunnelId)) {
333
335
  throw new TunnelRefusal("CE_TUNNEL_PROFILE_INVALID", "control_plane.tunnel_id");
334
336
  }
335
337
  if (found.apiKey === undefined) {
@@ -464,57 +466,8 @@ function defaultSpawnDaemon(logPath) {
464
466
  }
465
467
  };
466
468
  }
467
- const MAX_WRAPPER_BYTES = 4096;
468
- const SHEBANG_RE = /^#!(\/[^\s\u0000]+)$/;
469
- const WRAPPER_EXEC_RE = /^exec "(\/[^"\\\r\n\u0000]+)" "\$@"$/;
470
- export function resolveWrapperIdentityEvidence(clientPath) {
471
- let text;
472
- try {
473
- const stat = statSync(clientPath); // follows the brew bin symlink
474
- if (!stat.isFile() || stat.size === 0 || stat.size > MAX_WRAPPER_BYTES)
475
- return undefined;
476
- text = readFileSync(clientPath, "utf8");
477
- }
478
- catch {
479
- return undefined;
480
- }
481
- if (!text.startsWith("#!"))
482
- return {}; // direct binary: no wrapper forms
483
- const lines = text.split("\n");
484
- const shebang = SHEBANG_RE.exec((lines[0] ?? "").replace(/\r$/, ""));
485
- const shellPrefix = shebang !== null && /^[ -~]+$/.test(shebang[1]) && normalize(shebang[1]) === shebang[1]
486
- ? shebang[1]
487
- : undefined;
488
- const evidence = shellPrefix === undefined ? {} : { shellPrefix };
489
- // C-1 (Lane C): the exec form is accepted only when the ENTIRE file is the
490
- // canonical shim shape — shebang, then exactly ONE strict exec line, with
491
- // every other line blank or a comment. Anything else (heredocs, indented or
492
- // argument-carrying exec, conditionals, extra statements) means the file's
493
- // execution semantics are not fully understood here, so NO exec evidence is
494
- // produced (fail closed). The shell-prefix form rests on the shebang alone,
495
- // which the kernel honors regardless of the script body.
496
- const meaningful = lines.slice(1).filter((line) => {
497
- const trimmed = line.trim();
498
- return trimmed !== "" && !trimmed.startsWith("#");
499
- });
500
- if (meaningful.length !== 1)
501
- return evidence;
502
- const execMatch = WRAPPER_EXEC_RE.exec(meaningful[0]); // column-0, strict
503
- if (execMatch === null)
504
- return evidence;
505
- const target = execMatch[1];
506
- if (!/^[ -~]+$/.test(target) || normalize(target) !== target)
507
- return evidence;
508
- try {
509
- if (!statSync(target).isFile())
510
- return evidence;
511
- }
512
- catch {
513
- return evidence;
514
- }
515
- evidence.execTarget = target;
516
- return evidence;
517
- }
469
+ // Keep the existing manager export; selection and ownership share one parser.
470
+ export { resolveWrapperIdentityEvidence } from "../runtime/wrapper-identity.js";
518
471
  // ---------------------------------------------------------------------------
519
472
  // Ownership record (S7/S8): strict load, random-name O_EXCL temp, 0700 dir.
520
473
  // ---------------------------------------------------------------------------
@@ -35,6 +35,7 @@ import { tmpdir } from "node:os";
35
35
  import { join } from "node:path";
36
36
  import { fileURLToPath } from "node:url";
37
37
  import { TunnelRefusal } from "./codes.js";
38
+ import { TUNNEL_ID_PATTERN } from "./tunnel-id.js";
38
39
  /** Fixed service for every B1.1 item. Never derived from input. */
39
40
  export const TUNNEL_KEYCHAIN_SERVICE = "pi-chat-exchange-tunnel";
40
41
  /** Native `errSecItemNotFound`. Documented here to contrast with CLI exit 44. */
@@ -48,7 +49,6 @@ export const OFFLINE_SYNTHETIC_SCOPE = Object.freeze({
48
49
  origin: "https://offline-b11.invalid",
49
50
  tunnelId: "tunnel_b11offline",
50
51
  });
51
- const TUNNEL_ID_PATTERN = /^tunnel_[A-Za-z0-9]{8,}$/;
52
52
  const ORIGIN_PATTERN = /^https:\/\/[A-Za-z0-9.-]+(:\d{1,5})?$/;
53
53
  const ACCOUNT_PATTERN = /^v1:[0-9a-f]{64}$/;
54
54
  const SECRET_PATTERN = /^[\x21-\x7e]{1,4096}$/;
@@ -24,10 +24,10 @@ import fs from "node:fs";
24
24
  import { createHash, randomUUID } from "node:crypto";
25
25
  import { dirname, isAbsolute, join, normalize } from "node:path";
26
26
  import { TunnelRefusal } from "./codes.js";
27
+ import { TUNNEL_ID_PATTERN as TUNNEL_ID } from "./tunnel-id.js";
27
28
  import { MCP_BINDING_CONFIG_MAX_BYTES, MCP_BINDING_CONFIG_VERSION, parseMcpBindingConfig } from "../host/mcp-binding-config.js";
28
29
  /** Fixed managed directory for CE-generated bindings, beside the tunnel profile. */
29
30
  export const MANAGED_BINDING_DIRNAME = ".ce-bindings";
30
- const TUNNEL_ID = /^tunnel_[A-Za-z0-9]{8,}$/;
31
31
  const ORG_ID = /^org-[A-Za-z0-9]{1,128}$/;
32
32
  const ADAPTER = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
33
33
  function invalid(field) {
@@ -22,7 +22,7 @@ const EVIDENCE = ["none", "process-identity", "health-probe", "offline-simulated
22
22
  function readProjection(projection) {
23
23
  const state = STATES.includes(projection.state) ? projection.state : "UNKNOWN";
24
24
  // A caller accidentally passing an unmasked ID cannot disclose it here.
25
- const tunnel = typeof projection.tunnelIdAlreadyMasked === "string" && /^tunnel_[A-Za-z0-9]{6}…$/.test(projection.tunnelIdAlreadyMasked)
25
+ const tunnel = typeof projection.tunnelIdAlreadyMasked === "string" && /^tunnel_(?:[A-Za-z0-9]{6}|[a-z0-9]{4}_[a-z0-9])…$/.test(projection.tunnelIdAlreadyMasked)
26
26
  ? projection.tunnelIdAlreadyMasked : "Not configured";
27
27
  const binding = projection.binding === "configured" ? "Configured"
28
28
  : projection.binding === "invalid" ? "Invalid" : "Not configured";
@@ -18,6 +18,7 @@
18
18
  */
19
19
  import { isAbsolute, join, normalize } from "node:path";
20
20
  import { TunnelRefusal } from "./codes.js";
21
+ import { TUNNEL_ID_PATTERN } from "./tunnel-id.js";
21
22
  import { APPROVED_NODE_VERSION } from "../storage/runtime.js";
22
23
  /** Configuration-shaped refusal for profile construction. */
23
24
  export class TunnelConfigError extends TunnelRefusal {
@@ -26,7 +27,6 @@ export class TunnelConfigError extends TunnelRefusal {
26
27
  this.name = "TunnelConfigError";
27
28
  }
28
29
  }
29
- const TUNNEL_ID_PATTERN = /^tunnel_[A-Za-z0-9]{8,}$/;
30
30
  const CREDENTIAL_SHAPED = /(sk-[A-Za-z0-9_-]{8,})|(cap_[0-9a-f]{16,})|(BEGIN [A-Z ]*PRIVATE KEY)/i;
31
31
  // Exact CE stdio argv, single-space separators, narrow ASCII paths. Space-
32
32
  // bearing paths use single quotes; expansions, metacharacters and escapes are
@@ -188,7 +188,9 @@ export function serializeTunnelProfile(profile) {
188
188
  */
189
189
  const ALLOWED_ENV_PATTERN = /^(PATH|HOME|TMPDIR|LANG|LC_[A-Z_]+|TZ|TERM|SSL_CERT_FILE|SSL_CERT_DIR)$/;
190
190
  export function childEnvironment(source) {
191
- const env = {};
191
+ // Keep recovery explicit: 0.0.19 otherwise restarts the MCP child internally.
192
+ // Older clients ignore this env setting; new YAML/flags would break rollback.
193
+ const env = { MCP_STDIO_FAILURE_POLICY: "exit" };
192
194
  for (const [name, value] of Object.entries(source)) {
193
195
  if (ALLOWED_ENV_PATTERN.test(name))
194
196
  env[name] = value;
@@ -13,6 +13,7 @@
13
13
  */
14
14
  import { defineMenu, runMenu, sanitizeTerminalText } from "@narumitw/pi-tui-kit";
15
15
  import { isTunnelRefusalCode, TunnelRefusal } from "./codes.js";
16
+ import { TUNNEL_ID_PATTERN as TUNNEL } from "./tunnel-id.js";
16
17
  import { captureTunnelSecret } from "./secure-input.js";
17
18
  import { formatRecipientList, parseRecipientList } from "./managed-binding.js";
18
19
  /** MESSAGING-INTEGRATION-01: the single explicitly-confirmed endpoint pair.
@@ -22,7 +23,6 @@ const PI_ENDPOINT_ID = "pi/main";
22
23
  /** Render untrusted identity/storage text as one terminal line. This projection
23
24
  * never normalizes the raw values later passed to the authorized transaction. */
24
25
  const terminalLine = (value) => sanitizeTerminalText(value).replace(/[\r\n\x00-\x1F\x7F]/g, " ");
25
- const TUNNEL = /^tunnel_[A-Za-z0-9]{8,}$/;
26
26
  const ORGANIZATION = /^org-[A-Za-z0-9]{1,128}$/;
27
27
  const cancelled = () => ({ status: "cancelled" });
28
28
  const failed = () => ({ status: "refused", code: "CE_TUNNEL_SETUP_FAILED" });
@@ -93,7 +93,7 @@ export async function runSetupWizard(ctx, options) {
93
93
  const STEPS = 4;
94
94
  /** Per-field help: what is required, in what format, and what empty means. */
95
95
  const HELP = Object.freeze({
96
- tunnel: "Required · tunnel_ followed by at least 8 alphanumeric characters",
96
+ tunnel: "Required · tunnel_ followed by at least 8 alphanumeric characters, or a 4-character namespace and 32-character ID",
97
97
  organization: "Optional · org- followed by 1-128 alphanumeric characters · leave empty if not required",
98
98
  recipients: "Optional · adapter:endpointId, comma-separated · empty keeps the CE-managed default",
99
99
  credential: "Existing credential configured · Replace opens a masked input",
@@ -427,7 +427,7 @@ export async function presentTunnelStatus(ctx, view, options = {}) {
427
427
  const configurationState = closed(view.configurationState, /^[A-Z_]{1,32}$/);
428
428
  const lines = [
429
429
  `Profile: ${sanitizeTerminalText(view.profilePath)}`,
430
- `Tunnel: ${view.maskedTunnel === undefined ? "Not configured" : closed(view.maskedTunnel, /^tunnel_[A-Za-z0-9]{1,16}\u2026?$/)}`,
430
+ `Tunnel: ${view.maskedTunnel === undefined ? "Not configured" : closed(view.maskedTunnel, /^tunnel_(?:[A-Za-z0-9]{1,16}|[a-z0-9]{4}_[a-z0-9]{1,11})…?$/)}`,
431
431
  `Organization: ${view.organization}`, `MCP binding: ${view.binding}`, `Credential: ${view.credential}`,
432
432
  `Configuration State: ${configurationState}`, `Runtime state: ${closed(view.runtimeState, /^[A-Z_]{1,32}$/)}`,
433
433
  `Evidence: ${sanitizeTerminalText(view.evidence).slice(0, 120)}`,
@@ -0,0 +1,4 @@
1
+ // Preserve CE's existing legacy IDs and the official namespaced form verbatim.
2
+ // The final assertion requires the actual end, unlike `$` before a trailing newline.
3
+ export const TUNNEL_ID_PATTERN = /^tunnel_(?:[A-Za-z0-9]{8,}|[a-z0-9]{4}_[a-z0-9]{32})(?![\s\S])/;
4
+ //# sourceMappingURL=tunnel-id.js.map
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zieglar/pi-chat-exchange",
3
- "version": "0.2.1",
3
+ "version": "0.2.2",
4
4
  "license": "MIT",
5
5
  "publishConfig": {
6
6
  "access": "public",