@zieglar/pi-chat-exchange 0.0.0-stage → 0.2.0
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/CHANGELOG.md +70 -0
- package/LICENSE +21 -0
- package/README.md +89 -2
- package/dist/bin/mcp-stdio.js +196 -0
- package/dist/control/debug-log.js +67 -0
- package/dist/control/mcp/debug-transport.js +48 -0
- package/dist/control/mcp/messaging-tools.js +278 -0
- package/dist/control/mcp/ping.js +43 -0
- package/dist/control/mcp/server.js +153 -0
- package/dist/core/authorization.js +32 -0
- package/dist/core/reference.js +32 -0
- package/dist/core/rules.js +468 -0
- package/dist/endpoints/pi/contract.js +2 -0
- package/dist/endpoints/pi/session-host.js +39 -0
- package/dist/host/bound-endpoint.js +176 -0
- package/dist/host/endpoint-host.js +839 -0
- package/dist/host/mcp-binding-config.js +209 -0
- package/dist/host/ownership-recovery.js +257 -0
- package/dist/index.js +11 -0
- package/dist/protocol/capabilities.js +46 -0
- package/dist/protocol/endpoint-capabilities.js +15 -0
- package/dist/protocol/entities.js +185 -0
- package/dist/protocol/formats.js +13 -0
- package/dist/protocol/idempotency.js +93 -0
- package/dist/protocol/identity.js +130 -0
- package/dist/protocol/index.js +8 -0
- package/dist/protocol/lifecycle.js +125 -0
- package/dist/protocol/outcomes.js +55 -0
- package/dist/runtime/desktop-manifest.js +65 -0
- package/dist/runtime/diagnostics.js +34 -0
- package/dist/runtime/executables.js +222 -0
- package/dist/storage/capability.js +221 -0
- package/dist/storage/connection.js +94 -0
- package/dist/storage/creation-request.js +176 -0
- package/dist/storage/creation.js +553 -0
- package/dist/storage/current-schema.js +397 -0
- package/dist/storage/delivery-ack.js +177 -0
- package/dist/storage/errors.js +9 -0
- package/dist/storage/filesystem.js +116 -0
- package/dist/storage/inbox-discovery.js +135 -0
- package/dist/storage/messaging.js +156 -0
- package/dist/storage/migration.js +258 -0
- package/dist/storage/ownership.js +789 -0
- package/dist/storage/participant-identity.js +127 -0
- package/dist/storage/participant.js +700 -0
- package/dist/storage/recovery.js +99 -0
- package/dist/storage/runtime.js +113 -0
- package/dist/storage/schema.js +556 -0
- package/dist/storage/session-state.js +75 -0
- package/dist/storage/store.js +450 -0
- package/dist/storage/transaction.js +199 -0
- package/dist/storage/trust-root.js +164 -0
- package/dist/tunnel/background-manager.js +1727 -0
- package/dist/tunnel/codes.js +79 -0
- package/dist/tunnel/health.js +75 -0
- package/dist/tunnel/keychain.js +526 -0
- package/dist/tunnel/managed-binding.js +454 -0
- package/dist/tunnel/manager-panel.js +249 -0
- package/dist/tunnel/manager-ui.js +341 -0
- package/dist/tunnel/manager.js +372 -0
- package/dist/tunnel/messaging-activation-ui.js +85 -0
- package/dist/tunnel/messaging-config.js +246 -0
- package/dist/tunnel/multi-session-admission.js +31 -0
- package/dist/tunnel/multi-session-policy.js +314 -0
- package/dist/tunnel/offline-client.js +104 -0
- package/dist/tunnel/profile.js +319 -0
- package/dist/tunnel/redact.js +9 -0
- package/dist/tunnel/secure-input.js +318 -0
- package/dist/tunnel/session-process-mutex.js +338 -0
- package/dist/tunnel/setup-ui.js +443 -0
- package/dist/tunnel/setup.js +734 -0
- package/dist/tunnel/state.js +127 -0
- package/docs/architecture.md +170 -0
- package/docs/chatgpt-installation.md +149 -0
- package/docs/delivery-ack-contract.md +86 -0
- package/docs/independent-install.md +156 -0
- package/docs/multi-session-usage.md +77 -0
- package/docs/ownership-contract.md +429 -0
- package/docs/protocol-v2.md +269 -0
- package/docs/releases/0.2.0.md +59 -0
- package/docs/storage-contract.md +1241 -0
- package/docs/storage-security.md +138 -0
- package/docs/tunnel-manager-background.md +169 -0
- package/docs/tunnel-setup.md +214 -0
- package/native/tunnel-keychain.swift +432 -0
- package/package.json +77 -4
- package/pi-extension/README.md +125 -0
- package/pi-extension/allowlist.example.json +11 -0
- package/pi-extension/index.ts +2312 -0
- package/pi-extension/multi-session-commands.ts +93 -0
- package/pi-extension/multi-session-runtime.ts +75 -0
- package/pi-extension/tui-keys.ts +40 -0
- package/scripts/reconcile-session-process-mutex.mjs +262 -0
- package/scripts/recover-stale-ownership.mjs +91 -0
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
# Private storage security boundaries (CE-0002-B1-R4)
|
|
2
|
+
|
|
3
|
+
This is a private SQLite foundation, not a delivery/dispatch implementation.
|
|
4
|
+
The public protocol and lifecycle vocabulary are unchanged.
|
|
5
|
+
|
|
6
|
+
See [storage-contract.md](storage-contract.md) for the consolidated accepted durable storage contract (CE-0002-B2-S6-2).
|
|
7
|
+
|
|
8
|
+
## Immutability and compatibility
|
|
9
|
+
|
|
10
|
+
Every writer enables and reads back `recursive_triggers=ON`. This causes
|
|
11
|
+
conflicting `INSERT OR REPLACE` deletions to run the existing immutable-row
|
|
12
|
+
triggers for Result, audit, migration ledger, and store identity metadata.
|
|
13
|
+
File-backed tests exercise primary and secondary unique-key collisions as
|
|
14
|
+
well as UPDATE and DELETE. Raw connection owners must not disable policy.
|
|
15
|
+
|
|
16
|
+
Reopen compares the complete ordered `sqlite_schema` manifest (`type`, `name`,
|
|
17
|
+
`tbl_name`, `sql`, including implicit indexes) with an isolated reference built
|
|
18
|
+
from the approved migration SQL. Root-page layout is excluded. SQL is not
|
|
19
|
+
whitespace-normalized: even equivalent unauthorized DDL is incompatible.
|
|
20
|
+
Columns, STRICT/CHECK/FK/UNIQUE constraints, triggers, indexes, extra tables and
|
|
21
|
+
views are covered. Version and migration-ledger checks remain independent.
|
|
22
|
+
Drift is refused, never repaired or migrated.
|
|
23
|
+
|
|
24
|
+
## Filesystem and refusal
|
|
25
|
+
|
|
26
|
+
All directory components must be real directories, with no ancestor symlinks.
|
|
27
|
+
Use canonical OS paths (for example canonicalize a temporary root before
|
|
28
|
+
creating the private directory; macOS `/var` and `/tmp` aliases are symlinks).
|
|
29
|
+
The final directory remains current-user-owned and 0700, on an approved local
|
|
30
|
+
filesystem. DB/WAL/SHM artifacts are checked with `lstat`, including dangling
|
|
31
|
+
links, and must be owned regular 0600 files. New database files use exclusive
|
|
32
|
+
creation and `O_NOFOLLOW`. Initialization cannot overwrite a racing existing
|
|
33
|
+
name. These checks happen before SQLite opens the path.
|
|
34
|
+
|
|
35
|
+
An existing store receives a nonmutating **read-only snapshot preflight**.
|
|
36
|
+
Opening the original with SQLite `readOnly` is insufficient: WAL shared-memory
|
|
37
|
+
artifacts can still be changed. A private disposable directory holds copies of
|
|
38
|
+
DB and, if present, WAL; SQLite opens only that copy read-only. The copied WAL
|
|
39
|
+
is read rather than ignored; SHM is reconstructed in the disposable directory.
|
|
40
|
+
A rollback journal causes refusal rather than implicit recovery. Snapshot
|
|
41
|
+
artifacts are removed on normal success/failure. Tests compare exact original
|
|
42
|
+
DB/WAL/SHM bytes and directory inventories on rejected stores, including a
|
|
43
|
+
live WAL writer. No journal-mode change is made to refused DELETE stores.
|
|
44
|
+
|
|
45
|
+
After successful preflight, the selected original's identity, restore hold,
|
|
46
|
+
version, ledger, live schema, and integrity are revalidated in a read transaction
|
|
47
|
+
before persistent writer policy, then revalidated before returning the handle.
|
|
48
|
+
UUID changes or a disappeared source are refused.
|
|
49
|
+
|
|
50
|
+
**Limitations:** DB/WAL copying is not an atomic backup. Concurrent modification
|
|
51
|
+
can cause conservative refusal. Ancestor/artifact checks, copying, SQLite's
|
|
52
|
+
pathname open, and writer setup have TOCTOU windows; writer revalidation reduces
|
|
53
|
+
but does not eliminate races. Node's SQLite binding does not accept the
|
|
54
|
+
preopened no-follow descriptor. Trusted parent directories and an operator
|
|
55
|
+
controlling the store namespace are required. An attacker with equivalent
|
|
56
|
+
filesystem authority can replace paths or database contents; no complete
|
|
57
|
+
protection against that actor, mount replacement, or power-loss durability is
|
|
58
|
+
claimed. Snapshot I/O and startup scan budgets remain deferred (F8).
|
|
59
|
+
|
|
60
|
+
## Transaction ownership and outcomes
|
|
61
|
+
|
|
62
|
+
`withImmediateTransaction` remains synchronous. Callbacks receive a frozen,
|
|
63
|
+
revocable handle exposing only `exec` and `prepare`, whose frozen statements
|
|
64
|
+
expose only synchronous `run`, `get`, and `all`. No raw connection, authorizer,
|
|
65
|
+
transaction controls, or iterator is returned by that handle. SQLite's native
|
|
66
|
+
authorizer denies parsed transaction/savepoint actions during the callback,
|
|
67
|
+
including captured or preprepared raw-connection COMMIT/ROLLBACK statements.
|
|
68
|
+
A swallowed denial still makes the operation fail and roll back.
|
|
69
|
+
|
|
70
|
+
Normal return means **COMMITTED**. Transaction errors carry `outcome` and
|
|
71
|
+
`retryable`: **ROLLED_BACK** requires a known no-write begin failure or verified
|
|
72
|
+
owned rollback; unexpected inactive/unreadable state, uncertain commit, or
|
|
73
|
+
unproven cleanup is **INDETERMINATE**, non-retryable, and invalidates/closes the
|
|
74
|
+
connection. Only SQLite busy errors with a known rolled-back/no-write outcome
|
|
75
|
+
are retryable. Busy waiting remains bounded; a separate-process writer test
|
|
76
|
+
checks this. SQLite extended busy codes are classified by their primary code.
|
|
77
|
+
|
|
78
|
+
The primitive owns the connection authorizer for its duration. The raw private
|
|
79
|
+
store connection is privileged setup/test authority, not a callback capability.
|
|
80
|
+
Deliberately replacing its authorizer or using a separate privileged connection
|
|
81
|
+
is outside the prevention boundary; unexpected transaction state is nevertheless
|
|
82
|
+
detected conservatively. Independent privileged connections are not sandboxed.
|
|
83
|
+
|
|
84
|
+
The callback return contract is **void-only**: runtime acceptance requires exactly
|
|
85
|
+
`undefined`. No other primitive, object, function, Promise, or thenable is accepted.
|
|
86
|
+
Unsupported results cause synchronous rollback and capability revocation. Object
|
|
87
|
+
rejection does not read `.then`, invoke getters/Proxy traps, or assimilate thenables.
|
|
88
|
+
TypeScript's `void` callback type alone is not enforcement.
|
|
89
|
+
|
|
90
|
+
The helper installs **no global runtime observation**. It does not install V8
|
|
91
|
+
Promise hooks or `async_hooks`, does not attach Promise reactions, does not alter
|
|
92
|
+
process rejection handling, and never consumes an unrelated Promise rejection.
|
|
93
|
+
An unsupported return value is compared against `undefined` by identity only: it is
|
|
94
|
+
never read, called, awaited, assimilated, or modified. Strict-mode subprocess tests
|
|
95
|
+
assert that an unrelated unhandled rejection behaves identically whether it is
|
|
96
|
+
created inside or outside a transaction callback.
|
|
97
|
+
|
|
98
|
+
**Promise ownership boundary:** a callback that creates a Promise violates the
|
|
99
|
+
synchronous transaction contract if it returns that Promise. The helper guarantees
|
|
100
|
+
synchronous rollback on unsupported return values; it does **not** guarantee that a
|
|
101
|
+
rejected Promise created by caller code will be handled. Creator-owned rejection
|
|
102
|
+
handling is required, and an unhandled rejection from caller-created asynchronous
|
|
103
|
+
work is not a transaction commit failure. No claim is made that arbitrary hostile
|
|
104
|
+
native Promises are safely observed, because none are observed at all.
|
|
105
|
+
|
|
106
|
+
**Boundary:** async continuations and retained statements cannot use the revoked
|
|
107
|
+
handle, even during later reuse, but detached async work keeps running and is not
|
|
108
|
+
sandboxed. Hostile process-level changes to intrinsics, and separately captured
|
|
109
|
+
privileged raw connections, remain outside the execution-containment boundary.
|
|
110
|
+
|
|
111
|
+
F6 failed-initialization artifact recovery, F8 general budgets, F9 architecture
|
|
112
|
+
negative-oracle hardening, and all B2 features remain deferred.
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
## Host trust root (CE-0002-B3-P1A)
|
|
116
|
+
|
|
117
|
+
The v2 store adds a `host-secret` artifact in the private store directory. It
|
|
118
|
+
receives the same artifact enforcement as the database files (real regular
|
|
119
|
+
file, 0600, current-user-owned, no symlinks, exclusive creation with
|
|
120
|
+
O_NOFOLLOW) plus exact length and hex-encoding checks, re-validated on every
|
|
121
|
+
open against the append-only `host_trust_root` fingerprint table. The
|
|
122
|
+
plaintext secret never enters SQLite, results, errors, or logs; only its
|
|
123
|
+
SHA-256 fingerprint is persisted.
|
|
124
|
+
|
|
125
|
+
Secret loss or rotation is recovered only through the explicit operator
|
|
126
|
+
command (`recoverTrustRoot`): no automatic regeneration, no recovery from a
|
|
127
|
+
normal open, no silent overwrite, no automatic deletion of orphan artifacts.
|
|
128
|
+
Recovery appends a new generation and revokes all existing capabilities, so a
|
|
129
|
+
replacement secret inherits no authority.
|
|
130
|
+
|
|
131
|
+
**Limitations:** the trust root shares the filesystem trust boundary documented
|
|
132
|
+
above — an attacker with equivalent filesystem authority can replace both the
|
|
133
|
+
database and the secret file consistently, and trust-root fingerprinting does
|
|
134
|
+
not detect that actor. The fingerprint detects accidental or partial
|
|
135
|
+
replacement and unauthorized reset attempts that do not also rewrite the
|
|
136
|
+
database. Crash windows between secret-file creation and the accompanying
|
|
137
|
+
SQLite commit are fail-closed (orphan artifacts block retry until explicit
|
|
138
|
+
operator removal), not self-healing.
|
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
# Tunnel manager — real background scope (LOCAL-BACKGROUND-01)
|
|
2
|
+
|
|
3
|
+
This document describes the **real background** mode of `/ce-tunnel start|status|stop`.
|
|
4
|
+
The offline simulator mode (`CE_TUNNEL_OFFLINE_TEST=1`, see `tunnel-manager-offline.md`)
|
|
5
|
+
is unchanged. There is exactly one manager per extension host; the two modes never
|
|
6
|
+
run side by side.
|
|
7
|
+
|
|
8
|
+
## What it does
|
|
9
|
+
|
|
10
|
+
- Starts the operator-managed real client as a **detached daemon**:
|
|
11
|
+
`tunnel-client run --profile-file <profile>` (default profile
|
|
12
|
+
`~/.config/pi-chat-exchange/tunnel/tunnel.yaml`, override with `CE_TUNNEL_PROFILE`).
|
|
13
|
+
The daemon survives the Pi session by design.
|
|
14
|
+
- Persists an ownership record at `<profileDir>/background-state.json` (0600,
|
|
15
|
+
atomic tmp+rename): run id, pid, profile path **and** sha256, tunnel id, key
|
|
16
|
+
file path, health url file, log path, the exact `ps` command line and the exact
|
|
17
|
+
`ps` start-time key observed right after spawn, start/stop bookkeeping.
|
|
18
|
+
- Health comes only from real probes: `tunnel-client health --url-file …
|
|
19
|
+
--pid <owned> --require-control-plane-poll --json`, parsed by the frozen
|
|
20
|
+
`health.ts` rules and stamped once per completion by the shared recorder.
|
|
21
|
+
PID liveness alone is never CONNECTED.
|
|
22
|
+
- Background startup has a **45s** default window, measured from run allocation:
|
|
23
|
+
the external client 0.0.16 defaults to a 30s initial long-poll plus a 5s
|
|
24
|
+
deadline guardrail, with 10s allowance for startup, probes and scheduling.
|
|
25
|
+
These are external defaults, not dynamically synchronized configuration.
|
|
26
|
+
The shared offline simulator retains its 30s window; explicit timing overrides
|
|
27
|
+
remain authoritative. Required-poll readiness and verified cleanup are unchanged;
|
|
28
|
+
no automatic restart or post-deadline recovery is introduced.
|
|
29
|
+
- Status vocabulary: `STOPPED / STARTING / CONNECTED / DEGRADED / UNKNOWN`.
|
|
30
|
+
Stale evidence lapses to UNKNOWN on read; a pure read never refreshes state.
|
|
31
|
+
|
|
32
|
+
## Hard limits
|
|
33
|
+
|
|
34
|
+
- **Explicit real-start gate.** `/ce-tunnel start` refuses
|
|
35
|
+
`CE_TUNNEL_BACKGROUND_UNAUTHORIZED` unless the operator exported exactly
|
|
36
|
+
`CE_TUNNEL_BACKGROUND_ALLOW=1` for this Pi session. `status`/`stop` are not
|
|
37
|
+
gated: they never create cost, and stop only reduces it.
|
|
38
|
+
- **Cross-process exclusion.** Start/stop (and any refresh that needs to
|
|
39
|
+
persist) hold `<state>.lock.d` — a mkdir DIRECTORY lock whose holder is
|
|
40
|
+
verified by pid + start key. Stale or crashed locks are reclaimed under
|
|
41
|
+
mutual exclusion between reclaimers: rename-to-grave first, then the grave's
|
|
42
|
+
holder is verified to be the SAME lock that was judged stale; a mismatch
|
|
43
|
+
rolls the rename back and refuses `CE_TUNNEL_MANAGER_BUSY`. A holderless
|
|
44
|
+
lock younger than 60s refuses. Critical sections re-assert lock ownership
|
|
45
|
+
before any persist/signal. The record is re-read inside the lock, so two Pi
|
|
46
|
+
sessions cannot double-start or double-signal.
|
|
47
|
+
- **Termination ledger.** A recorded run is signalled only after its
|
|
48
|
+
`termRequestedAt` intent persists; without the ledger the signal is refused
|
|
49
|
+
and ownership retained. A run whose record could never persist is guarded by
|
|
50
|
+
an in-memory once-set (a crash loses the record and the guard together);
|
|
51
|
+
neither disk ENOENT nor a different run's stopped record ever discards such
|
|
52
|
+
pending ownership.
|
|
53
|
+
- **Stop latency.** `stop` first awaits the settlement of any start it
|
|
54
|
+
invalidated (bounded by one probe timeout + identity capture + the stop
|
|
55
|
+
grace), then takes the lock; it never returns while a cancelled start still
|
|
56
|
+
owns work.
|
|
57
|
+
- **Dual-run stop.** If a session also owns an unpersisted (pending) daemon
|
|
58
|
+
whose run differs from the on-disk record, `stop` terminates BOTH — the
|
|
59
|
+
pending run via its in-memory once-set (at most one signal ever), the disk
|
|
60
|
+
run via its ledger. If the pending run still has not exited, `stop` refuses
|
|
61
|
+
`CE_TUNNEL_STOP_UNCONFIRMED` and the status note says to run stop again; it
|
|
62
|
+
never reports success while a run it owns is still alive.
|
|
63
|
+
- **Ledger write guards.** Every `persist()` is machine-enforced to a held lock
|
|
64
|
+
token, refuses a corrupt on-disk record, and refuses to overwrite a DIFFERENT
|
|
65
|
+
run's live record — no code path can roll back another session's ownership or
|
|
66
|
+
termination ledger. Lock reclaim verifies the grave's inode, mtime and holder
|
|
67
|
+
token all match the judged-stale lock before deletion.
|
|
68
|
+
- **Three-state inspection.** Process checks are present / proven-absent /
|
|
69
|
+
unknown (`/bin/ps`, fixed minimal env, LC_ALL=C). Unknown retains ownership
|
|
70
|
+
and blocks start; it is never treated as exit proof.
|
|
71
|
+
- **Fail-closed record.** Only a missing file means "no record"; a corrupt or
|
|
72
|
+
unreadable one is `CE_TUNNEL_STATE_CORRUPT` and blocks start/stop.
|
|
73
|
+
|
|
74
|
+
- **No credential interaction.** The key reaches the client only via the
|
|
75
|
+
profile's existing `file:` reference. The manager checks the key file by
|
|
76
|
+
metadata only (regular, non-symlink, owner-only 0600 — `profile.ts`
|
|
77
|
+
`checkKeyFileRequirements`). Inline values and `env:` references refuse
|
|
78
|
+
`CE_TUNNEL_CREDENTIAL_HANDOFF_BLOCKED`.
|
|
79
|
+
- **Organization context (LOCAL-BACKGROUND-05).** The optional profile field
|
|
80
|
+
`control_plane.organization_id` is a double-quoted, escape-free scalar with
|
|
81
|
+
local grammar `org-[A-Za-z0-9]{1,128}`. This is a bounded syntax policy, not
|
|
82
|
+
proof of server-side organization/Tunnel/Connector binding. Missing fields
|
|
83
|
+
preserve legacy behavior; an organization-scoped Tunnel may still reject
|
|
84
|
+
requests without one. Empty, invalid, repeated (even identical) fields and
|
|
85
|
+
extra-header overrides are refused before spawn.
|
|
86
|
+
The client reads the unchanged explicit `--profile-file` itself. Version
|
|
87
|
+
0.0.16 advertises organization ID as the `OpenAI-Organization` request header
|
|
88
|
+
and precedence flags > environment > YAML > defaults. Manager spawn adds no
|
|
89
|
+
organization flags and retains its existing minimal environment whitelist:
|
|
90
|
+
parent `CONTROL_PLANE_*`, `OPENAI_*` and `TUNNEL_CLIENT_*` overrides are not
|
|
91
|
+
forwarded. Thus the explicit profile is the only organization input here.
|
|
92
|
+
For example, add `organization_id: "org-Example123"` under `control_plane`
|
|
93
|
+
(two-space indentation) after confirming the target's non-secret metadata.
|
|
94
|
+
Existing profiles are never automatically migrated: changing a historical
|
|
95
|
+
Tunnel ID or adding organization context requires explicit operator approval.
|
|
96
|
+
No live authentication or real-Tunnel readiness is implied by local parsing.
|
|
97
|
+
- **PID reuse safety.** Every later status/stop re-verifies BOTH the exact
|
|
98
|
+
command line and the exact process start key. A mismatch reports UNKNOWN /
|
|
99
|
+
refuses `CE_TUNNEL_EXTERNAL_INSTANCE`; nothing is adopted or signalled.
|
|
100
|
+
- **Wrapper exec identity (LOCAL-BACKGROUND-03).** Homebrew installs the
|
|
101
|
+
client as a shim script (`#!/bin/bash` plus `exec "<Cellar libexec>" "$@"`),
|
|
102
|
+
so ps shows `/bin/bash <shim> run …` before the exec and `<cellar> run …`
|
|
103
|
+
after it — same pid, same start key. At spawn time the manager reads the
|
|
104
|
+
client file once and derives the acceptable identity set from explicit
|
|
105
|
+
evidence only: the direct argv always; the `<interpreter> <shim>` form only
|
|
106
|
+
from a no-argument `#!/abs/path` shebang; the post-exec form only from a
|
|
107
|
+
single strict `exec "<abs>" "$@"` line whose target is absolute, normalized,
|
|
108
|
+
printable, and an existing regular file. The exec form is persisted on the
|
|
109
|
+
record (`commandIdentityExec`) so later sessions recognize the exec'd
|
|
110
|
+
process. The exec form additionally requires the WHOLE file to be the
|
|
111
|
+
canonical shim shape (shebang + exactly one strict exec line; other lines
|
|
112
|
+
only blank or comments) — heredoc bodies, indented exec lines, or extra
|
|
113
|
+
statements forfeit it. Anything unknown or ambiguous (relative/unquoted/
|
|
114
|
+
multi-exec lines, missing target, oversized or unreadable shim) yields no
|
|
115
|
+
form and stays fail closed. Basename equality, pidfiles, and process names
|
|
116
|
+
are never evidence. A non-canonical wrapper (extra statements, heredocs, an
|
|
117
|
+
unreadable or oversized script) therefore DEGRADES to unmanageable after its
|
|
118
|
+
exec — identity mismatch, UNKNOWN, `CE_TUNNEL_STOP_UNCONFIRMED` — and the
|
|
119
|
+
instance is never mis-signalled; recovery is the documented manual,
|
|
120
|
+
identity-verified termination. Identity capture itself also accepts only the
|
|
121
|
+
evidence-derived identity set, so a client whose file cannot be read yields
|
|
122
|
+
an unconfirmed (pending) run rather than a substring-matched one.
|
|
123
|
+
- **Pending-run PID-reuse bar (S-1/F1).** A spawn whose identity was never
|
|
124
|
+
captured (identity-pending, memory-only) keeps its child handle: the handle's
|
|
125
|
+
exit event is first-class proof that OUR spawn died, after which any process
|
|
126
|
+
at that pid is a foreign reuser. The proof is archived PER RUN ID (runIds are
|
|
127
|
+
UUIDs and never reused), the listener is armed before the identity-capture
|
|
128
|
+
window, and a later start never resets another run's evidence — so the
|
|
129
|
+
dual-run stop path cannot sever it; dispose() likewise keeps the proof while
|
|
130
|
+
a pending run survives, because stop/refresh stay callable after dispose.
|
|
131
|
+
Such a run is then closed as exited and
|
|
132
|
+
is NEVER adopted or signalled — re-acquisition requires a live child link
|
|
133
|
+
plus exact membership in the evidence-derived identity set. Stop notes
|
|
134
|
+
distinguish "exit observed after SIGTERM" from "exit observed (process
|
|
135
|
+
already gone); no signal sent". On-disk `null` values for optional record
|
|
136
|
+
fields (`commandIdentityExec`, `termRequestedAt`) are normalized to absent
|
|
137
|
+
at load, so a foreign null can neither forge an identity nor suppress a
|
|
138
|
+
termination signal. A pending run whose process is gone is superseded
|
|
139
|
+
directly (`identityPending` stripped before persist), so a later start does
|
|
140
|
+
not fail with a misleading `CE_TUNNEL_STATE_CORRUPT`.
|
|
141
|
+
- **One SIGTERM per run, ever.** `termRequestedAt` is persisted, so even a
|
|
142
|
+
later Pi session never re-signals. Timeout refuses
|
|
143
|
+
`CE_TUNNEL_STOP_UNCONFIRMED` and **retains** the record. No SIGKILL, no bulk
|
|
144
|
+
kill, no name-based signalling (scans only REFUSE a duplicate start).
|
|
145
|
+
**Write-ahead window:** if a record-backed run's `termRequestedAt` persisted
|
|
146
|
+
but the signal was lost (e.g. the lock was taken before `signal()`), that
|
|
147
|
+
run is deliberately NOT re-signalled — at-most-once forbids the retry, so
|
|
148
|
+
at-most-once permits **zero** deliveries here. A later `stop` from this
|
|
149
|
+
manager will NOT re-signal that record (its intent is already ledgered); it
|
|
150
|
+
only ever reports `CE_TUNNEL_STOP_UNCONFIRMED` while the process survives.
|
|
151
|
+
There is no automatic recovery: the operator must separately authorise a
|
|
152
|
+
manual, identity-verified termination of the surviving process — never clear
|
|
153
|
+
the ledger to bypass the at-most-once guard.
|
|
154
|
+
- **No autostart, reconnect, respawn, or business retry.** A vanished daemon is
|
|
155
|
+
marked stopped with `process absent (unexpected)`; restart is a fresh,
|
|
156
|
+
explicit `/ce-tunnel start`.
|
|
157
|
+
- **The MCP child is never signalled by this manager.** After the client's exit
|
|
158
|
+
is verified, a lingering profile-declared `mcp-stdio.js` child is only
|
|
159
|
+
reported (`note`), because that child belongs to the client.
|
|
160
|
+
- Session teardown (`shutdown`, `session_start`, reload) never stops the
|
|
161
|
+
background daemon; it only drops this host's view.
|
|
162
|
+
- Transport state is never delivery, ACK, reconciliation, or completion
|
|
163
|
+
evidence; MCP reachable does not imply any message was delivered.
|
|
164
|
+
|
|
165
|
+
## Cost / authorization
|
|
166
|
+
|
|
167
|
+
The first real background run is a paid connection: it still requires a separate
|
|
168
|
+
operator authorization of cost and window, plus the `CE_TUNNEL_BACKGROUND_ALLOW=1`
|
|
169
|
+
opt-in. This command is the manual trigger; there is no unattended path.
|
|
@@ -0,0 +1,214 @@
|
|
|
1
|
+
# ChatGPT ↔ Pi:Tunnel 用户指南、配置与排障
|
|
2
|
+
|
|
3
|
+
这是 Secure MCP Tunnel 路径;不需要 Desktop stdio 插件。只用 Desktop 本地插件请走 [Desktop stdio 指南](chatgpt-installation.md)。正式安装给日常使用请用预构建私有 tarball 的[独立安装指南](independent-install.md),无需本页的仓库构建。示例均为占位值,不是已生效配置。
|
|
4
|
+
|
|
5
|
+
## 1. 前提与安装
|
|
6
|
+
|
|
7
|
+
| 组件 | 要求 |
|
|
8
|
+
|---|---|
|
|
9
|
+
| Pi | 1.3.0;设置与确认操作使用交互 TUI |
|
|
10
|
+
| Pi host / MCP child Node | 精确 **24.21.0 或 24.22.1**,分别通过完整 SQLite 身份、编译选项与 API 门槛;无需同一 executable |
|
|
11
|
+
| 仓库构建工具 | pnpm 12.9.1;UI 依赖由包安装,不需另装 UI |
|
|
12
|
+
| Tunnel client | 当前兼容基线 `tunnel-client` 0.0.16;可信绝对路径或受控系统目录发现 |
|
|
13
|
+
| Store 平台 | allowlist 为 macOS arm64 / Linux x64;双 Node 资格实测为 macOS arm64,不表示 Linux 或所有客户端已验收 |
|
|
14
|
+
|
|
15
|
+
### 安装和加载扩展
|
|
16
|
+
|
|
17
|
+
从仓库根目录,在已选中批准 Node 的 shell 执行。mise 可以使用,但不是要求;也不要修改全局 Node 来修一个 Session。
|
|
18
|
+
|
|
19
|
+
```sh
|
|
20
|
+
node --version
|
|
21
|
+
pnpm install --frozen-lockfile
|
|
22
|
+
pnpm --dir packages/pi-chat-exchange run build
|
|
23
|
+
pi -e ./packages/pi-chat-exchange/pi-extension/index.ts
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
长期跨项目使用可在 build 后执行 `pi install /absolute/path/to/packages/pi-chat-exchange`,以后从各项目正常运行 Pi。该本地包引用原目录;不要移动目录或重复用 `-e` 加载。`pi list` 可核对包声明。扩展入口导入包内 `dist/`,不会现场编译源码;更新源码后先 build,再在需要更新的 Session 中 `/reload`,否则仍可能运行陈旧 `dist/`。
|
|
27
|
+
|
|
28
|
+
如果 shell 中的 Pi 不由批准 Node 启动,使用本机可信绝对路径执行已安装 Pi 的实际 JavaScript 入口;所有路径须先替换为本机值:
|
|
29
|
+
|
|
30
|
+
```sh
|
|
31
|
+
CE_NODE_PATH="/trusted/node-install/bin/node" \
|
|
32
|
+
CE_TUNNEL_CLIENT_PATH="/trusted/client-install/tunnel-client" \
|
|
33
|
+
CE_TUNNEL_BACKGROUND_ALLOW=1 \
|
|
34
|
+
"/trusted/node-install/bin/node" "/absolute/installed-pi/dist/cli.js" \
|
|
35
|
+
-e "/absolute/path/to/packages/pi-chat-exchange/pi-extension/index.ts"
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
`CE_NODE_PATH` **只选择 MCP child**,不会修复已经运行的 Pi host。`CE_TUNNEL_BACKGROUND_ALLOW=1` 仅许可显式 Start,不自动连接;在 Pi 子 shell 中 export 不能修改父 Pi 环境。不要把 credential 写入上述命令。
|
|
39
|
+
|
|
40
|
+
### Client 安装与只读诊断
|
|
41
|
+
|
|
42
|
+
从 [OpenAI Tunnel 设置](https://platform.openai.com/settings/organization/tunnels)提供的下载入口或[官方 release](https://github.com/openai/tunnel-client/releases/latest)取得对应平台的 client;在执行前核实来源、版本及发布方提供的完整性信息。最新版本不自动等于本包已兼容版本。CE 不下载、安装或更新 client,也不创建云端 Tunnel。
|
|
43
|
+
|
|
44
|
+
进入 Pi 后运行:
|
|
45
|
+
|
|
46
|
+
```text
|
|
47
|
+
/ce-tunnel doctor
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
它分别报告当前 host、独立选择的 child Node 与 client 路径信任结果;不启动 client、不读 credential/Store、不改 profile,也不证明云端认证或 readiness。child 检查的是当前 resolver 候选,不是已保存 profile command 或正在运行 child 的实测身份;已有 profile 还须核对 Review/Details,必要时在 verified STOPPED 下显式 migrate。根据闭合诊断结果区分 Node 不合格、client 缺失与 client 信任拒绝。
|
|
51
|
+
|
|
52
|
+
- 显式 `CE_TUNNEL_CLIENT_PATH` / `CE_NODE_PATH` 必须是可信、规范化绝对路径;显式非法 override 不应靠别的候选掩盖。
|
|
53
|
+
- 系统候选仅来自 `/usr/local/bin`、`/usr/bin`、`/bin`、`/opt/homebrew/bin`,不扫描项目 PATH。Node 另兼容验证当前进程 executable 和旧 mise 安装位置;不是依赖 mise。
|
|
54
|
+
- executable、原路径与 symlink 真实目标的所有祖先均检查 ownership/权限;拒绝项目、`node_modules`、可写文件/祖先及不可信 symlink 链。macOS 只接受无 ACL 或 deny-only ACL,未知/失败拒绝。
|
|
55
|
+
- **Homebrew 已安装不等于可执行路径受信任。** 若其 wrapper 或 Cellar 祖先可被 group/other 写入,即使最终 binary 不可写仍拒绝。不要 chmod 放宽、绕过 symlink 检查或直接运行来“证明可信”;选择满足全链门槛的独立安装,再设置绝对 override。诊断不自动搬运 Homebrew 文件或清除 ACL。
|
|
56
|
+
|
|
57
|
+
缺失或不可信 client 不会触发 spawn;可以先检查 Node、阅读文档和准备配置,但不能据此 Start。
|
|
58
|
+
|
|
59
|
+
### 准备云端配置与 ChatGPT 连接
|
|
60
|
+
|
|
61
|
+
1. 在 [Platform Tunnel 设置](https://platform.openai.com/settings/organization/tunnels)核实目标 Tunnel、所属 Platform organization 与允许使用它的 ChatGPT workspace。创建/管理需相应 Manage 权限,运行 key 与使用者需相应 Use 权限;详见[官方 Tunnel 指南](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels)。不要为排障重复创建已有资源。
|
|
62
|
+
2. 取得完整 Tunnel ID(本地形状 `tunnel_` 加至少 8 位字母/数字)、目标 Organization ID(需要时为 `org-...`)及有权使用该 Tunnel 的 credential。它们不是 CE Session/capability。只在向导 masked 输入中填 key;本地形状检查不证明云端权限。
|
|
63
|
+
3. 按[官方自定义 MCP 指南](https://developers.openai.com/api/docs/guides/custom-mcp-server),在 [ChatGPT Plugins](https://chatgpt.com/plugins)选择 **+ → Add custom MCP server**,填写名称,在 **Connection** 选择 **Tunnel** 并选同一个目标。按目标配置认证、审阅风险提示,再 **Create as a plugin**。组织/客户端资格以当前官方页面为准;CE 不配置云端插件。
|
|
64
|
+
4. 安装该插件,在当前对话用 `@` 选择它。配置变更后在插件详情刷新工具,再核对当前对话实际可见工具;Tunnel CONNECTED 不替代这一步。不要把 Desktop marketplace 当作这条路径的前置要求。
|
|
65
|
+
|
|
66
|
+
## 2. 首次设置与 Messaging 授权
|
|
67
|
+
|
|
68
|
+
执行 `/ce-tunnel setup`,或 `/ce-tunnel` → **Set Up Tunnel**:
|
|
69
|
+
|
|
70
|
+
1. 输入 Tunnel ID、需要时的 Organization ID、masked credential。已有配置选择 **Keep existing credential**,不需重新输入或读取原 key。
|
|
71
|
+
2. Review 默认只生成基本 transport 配置,`recipients: []`,**不能通信**。
|
|
72
|
+
3. Review → **Back · Edit configuration → Advanced · Messaging (ChatGPT ↔ Pi)** → **Authorize messaging for this session**。
|
|
73
|
+
4. 核对当前真实 Pi Session、ChatGPT Endpoint `chatgpt/main`、初始 Pi Endpoint `pi/main`、Store/Exchange 及 payload/ACK。该便捷配对在两边开启 payload read / ACK,并将手工 recipients 替换为唯一 Pi 收件人;不是隐含最小权限。需要不同权限时按明确的配置流程授权。
|
|
74
|
+
5. 最终 **Save** 才发布配置 generation;它不激活 Endpoint、不启动 Tunnel、不读写消息。已有配对的替换需额外明确确认。
|
|
75
|
+
|
|
76
|
+
不同项目/Session 使用独立注册而不是轮流覆盖 `pi/main`;见[多 Session 使用](multi-session-usage.md)。
|
|
77
|
+
|
|
78
|
+
### 让保存的策略生效
|
|
79
|
+
|
|
80
|
+
编辑已有配置前,需显式 Stop 并核实 transport STOPPED;未知锁、活动 reader 或外部实例均不能当作已停止。向导不自动 Stop。
|
|
81
|
+
|
|
82
|
+
1. 如当前仍持有旧 CE binding,运行 `/ce-tunnel deactivate`,确认正常释放当前本地绑定。它不停止 transport,也不撤销注册。旧版 activate 的 policy-not-loaded 分支也仅释放旧映射并提示 reload,不会切换权限。
|
|
83
|
+
2. `/reload` 加载所选 generation。未绑定或已释放的 mapping 不自动 provision;`CE_HOST_MAPPING_INVALID` 不表示应删除 Store。
|
|
84
|
+
3. `/ce-tunnel activate`,确认当前真实 Session、双 Endpoint、Store/Exchange 与权限。只以 requireUnowned 显式绑定;匹配的有效 binding 为 no-op,不接管已有 Owner(包括已过期者)。
|
|
85
|
+
4. `/ce-status` 核对身份、Owner lease/fencing;再单独 `/ce-tunnel start` 加载 MCP 侧所选配置。
|
|
86
|
+
|
|
87
|
+
首次配置没有旧绑定则跳过第 1 步。release 为 UNKNOWN、精确 released+detached 证据缺失或持久化失败时停止并核实,不连续 activate/reload。不手改 identifiers 或伪造释放标记。
|
|
88
|
+
|
|
89
|
+
## 3. 真实后台启动与 Manager
|
|
90
|
+
|
|
91
|
+
真实 Start 可能计费,先授权运行窗口。在父 Pi 环境带精确 `CE_TUNNEL_BACKGROUND_ALLOW=1` 的前提下,显式 `/ce-tunnel start`。若需改变父环境,正常退出并以批准 Node、相同扩展加载方式恢复同一 Pi Session;`--continue` 选择最近会话,`--resume` 可人工选择。环境许可不等于已经启动。
|
|
92
|
+
|
|
93
|
+
| 操作 | 实际含义 |
|
|
94
|
+
|---|---|
|
|
95
|
+
| `/ce-tunnel` | 打开持久 Manager 界面 |
|
|
96
|
+
| Start / `/ce-tunnel start` | 先确认启动请求,再异步测量 readiness;不自动重连 |
|
|
97
|
+
| Refresh / Details | 更新健康、查看净化后的非秘密配置与进程证据,不重新授权 |
|
|
98
|
+
| Stop / `/ce-tunnel stop` | 只停止可证明属于 Manager 的实例;退出未确认不算 STOPPED |
|
|
99
|
+
| Close | 仅关闭界面,不停止后台启动任务或 daemon |
|
|
100
|
+
| `/ce-tunnel status` | 查看实测 transport 状态,不自动 Start |
|
|
101
|
+
| `/ce-status` | 查看经当前 admission 校验的 Pi / CE 身份、Exchange、Owner lease/fencing |
|
|
102
|
+
| `/ce-tunnel deactivate` | 确认后正常结束当前本地 CE binding;不改 registration/历史、不 Stop Tunnel |
|
|
103
|
+
|
|
104
|
+
后台 daemon 可跨 Pi Session 存活;退出 Pi 不等于 Stop。默认启动预算 45 秒,不是成功保证;client 初始 long-poll 可能约 30 秒。未知进程/lease 不能用第二次 Start、删锁或 bulk kill 解决。详见[后台 Manager](tunnel-manager-background.md)(仅仓库,不随 tarball 分发)。
|
|
105
|
+
|
|
106
|
+
**Configured ≠ Pi-bound ≠ Connected ≠ 消息实证。** Configured 是配置;Pi-bound 是当前 CE authority;CONNECTED 仅为及时测得的健康与控制面 polling;STOPPED 不表示 CE 已释放,UNKNOWN 更不等于 STOPPED。任何一项都不证明 ACK 或任务完成。
|
|
107
|
+
|
|
108
|
+
## 4. 双向 send / inbox / read / ACK
|
|
109
|
+
|
|
110
|
+
两端先加入同一 Exchange,核对已加载的 recipients/opt-in 和当前对话工具。每一步独立授权;不要为诊断读取真实 Inbox。
|
|
111
|
+
|
|
112
|
+
`ce_send` 的 `CREATED` 表示 Message、幂等记录与创建 Audit 已在本地 Store 同一事务提交;`REPLAYED` 返回原 Message,不创建第二条。它们不是云端送达、对端读取或任务执行的证明。Tunnel 传输工具调用与响应,双方通过同一 Store 发现消息;CE 不承诺 exactly-once delivery/execution。
|
|
113
|
+
|
|
114
|
+
`idempotencyKey` 在 Exchange 内标识一次逻辑发送:相同 key 与相同请求可重放原记录;同 key 换正文或 Endpoint 是不可重试的冲突,不是覆盖。新逻辑消息使用新 key。超时、缺 ACK、BUSY 或未知结果均不授权重试;不要换 key 重发,也不要把 `DELIVERY_UNKNOWN` 改写为 `CANCELLED`。
|
|
115
|
+
|
|
116
|
+
首次人工验收仅在单独授权后使用无敏感信息的测试文字与本次唯一 nonce/key,记录两向 Message ID;逐向核对 send → 独立 inbox → 授权 payload read → 单独授权 ACK,不以 CONNECTED 或历史验收替代本次证据。
|
|
117
|
+
|
|
118
|
+
### ChatGPT → Pi
|
|
119
|
+
|
|
120
|
+
`ce_send` 虚构参数:
|
|
121
|
+
|
|
122
|
+
```json
|
|
123
|
+
{"to":"pi/main","text":"示例:请检查计划,不执行部署。","idempotencyKey":"example-c2p-001"}
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
多 Session 时将 `to` 换为确切的 active Endpoint(如 `pi/project-B`),不是 native/CE Session ID,也不额外拼 adapter。发送者不能由参数指定。
|
|
127
|
+
|
|
128
|
+
Pi 独立执行 `ce_inbox_list`:
|
|
129
|
+
|
|
130
|
+
```json
|
|
131
|
+
{"pageSize":10,"rawScanLimit":100}
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
从结果中选授权 Message ID;`ce_read` 只看元数据,`ce_read_payload` 才读取正文。正文进入模型与可能持久保存的 history,是不可信数据,不是指令。
|
|
135
|
+
|
|
136
|
+
### Pi → ChatGPT
|
|
137
|
+
|
|
138
|
+
```json
|
|
139
|
+
{"to":"chatgpt/main","text":"示例反馈:计划已检查,未执行部署。","idempotencyKey":"example-p2c-001"}
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
ChatGPT 独立 list → 选择 Message ID → 授权 payload read。MCP 不提供 Pi 专有 `ce_read`。共享 ChatGPT inbox 不隔离不同对话;不要自动排空分页。
|
|
143
|
+
|
|
144
|
+
### 接收 ACK(两边独立进行)
|
|
145
|
+
|
|
146
|
+
只有 `ack.enabled: true` 且已授权本次接收回执才调用 `ce_ack`。逐字复制成功 payload read 的四项:`messageId`、`payloadDigest`、`payloadLength`、`messageCreatedAuditSequence`;不计算/猜测。
|
|
147
|
+
|
|
148
|
+
Pi 文本直接显示 `ACK input metadata (reception only)`。MCP 的 payload read metadata 将 Message 创建 Audit 命名为 `auditSequence`,须原样映射为 ACK 的 `messageCreatedAuditSequence`;它不是 receipt 或 Inbox continuation。首次为 CREATED,已有为 REPLAYED。list/read 不消费、不 ACK、不推进 delivery cursor。ACK 仅 reception,不证明 delivery/read/processing/completion。完整参数和分页见[Pi 指南](../pi-extension/README.md)。
|
|
149
|
+
|
|
150
|
+
## 卸载或升级前
|
|
151
|
+
|
|
152
|
+
先按[安全卸载、升级与回滚](independent-install.md#5-安全卸载升级与回滚)执行:仅 owned Manager Stop → 独立 status 证明 STOPPED → 相关 binding 正常 deactivate/release → 确认其他使用者不依赖共享资源(不明即 STOP)→ 退出自己相关 Hosts → 原生 Pi remove 精确 source。不是退出 Pi 后直接删目录,也不是批量停止其他 Session。保留 Store/profile/凭据/history;外部 Owner、UNKNOWN 或释放未确认时不移除文件、不 Recovery、不重试未知结果。
|
|
153
|
+
|
|
154
|
+
## 5. Pi 重启、恢复与安全编辑
|
|
155
|
+
|
|
156
|
+
- **有效 binding 的 `/reload`**:停旧 timer、drain、丢弃旧 capability;保留 durable Ownership,新代重新 resume 校验。
|
|
157
|
+
- **正常 deactivate / quit / Session replacement**:正常 end/release/detach;重新使用需显式 activate,不复活已终结的 CE Session。取消解绑不改变 binding;不确定释放保持拒绝。
|
|
158
|
+
- **新/fork/切换 Session**:不是恢复原身份。以可信 native Session ID 注册新 Endpoint;文件名与项目路径不是 authority。
|
|
159
|
+
- **崩溃、租约过期、UNKNOWN**:不自动 takeover/recovery;停止并单独核实。恢复属于[独立 operator 流程](chatgpt-installation.md#显式-stale-ownership-恢复),不是日常安装步骤。
|
|
160
|
+
- **编辑**:先核实 STOPPED,再 Setup → Keep credential;保存、Pi reload/activate 与 MCP Stop/Start 分别生效。Save 前取消不改变有效配置;Save 后 durability uncertain 不等于回滚,不盲重试。
|
|
161
|
+
|
|
162
|
+
## 配置模型与生成文件
|
|
163
|
+
|
|
164
|
+
默认 profile:`~/.config/pi-chat-exchange/tunnel/tunnel.yaml`。`~` 仅为说明,生成内容使用规范化绝对路径。
|
|
165
|
+
|
|
166
|
+
| 对象 | 作用与编辑政策 |
|
|
167
|
+
|---|---|
|
|
168
|
+
| Profile | transport 与唯一 activation pointer;选择 MCP command 的 `--config`;不等于 CE authority |
|
|
169
|
+
| `.credentials/credential-<uuid>` | 私有 plaintext key generation,目录 0700 / 文件 0600;不 cat、不提交 |
|
|
170
|
+
| `.ce-bindings/` | 私有 binding/sidecar;messaging generation digest 同时保护两份内容,不覆盖/手改 |
|
|
171
|
+
| `.ce-bindings/ce-store.sqlite`、WAL/SHM、host-secret | Store/信任根;目录 0700 / 文件 0600,Storage 独占 secret;不复制合并或清理 Owner |
|
|
172
|
+
| background state / lock / ledger | 进程所有权证据;不删锁、不按名称 kill |
|
|
173
|
+
| health URL / log | 本机受限诊断;不要公开 URL、完整日志或 credential reference |
|
|
174
|
+
| `ce-mapping` / `ce-messaging-released` / `ce-lifecycle-blocked` | Pi history 中的标识符/释放/拒绝证据,不含 capability,不手工编辑 |
|
|
175
|
+
|
|
176
|
+
Store directory/file 与 Exchange namespace/idempotencyKey 四项精确一致才配对;Endpoint、Participant、CE Session/Owner、native Pi Session 各有含义。registration 不是 live Owner,recipient label 不是认证。配置发布先生成 immutable binding/sidecar,profile rename 才逻辑提交;不是跨文件 crash-atomic 事务,无自动 credential/generation GC。
|
|
177
|
+
|
|
178
|
+
| 环境变量 | 作用与生效时点 |
|
|
179
|
+
|---|---|
|
|
180
|
+
| `CE_TUNNEL_PROFILE` | 选择规范化绝对 profile;不自动切换运行中的 child |
|
|
181
|
+
| `CE_NODE_PATH` | MCP child 的可信批准 Node;不改变运行中的 Pi host |
|
|
182
|
+
| `CE_TUNNEL_CLIENT_PATH` | 可信 client 绝对路径 override,不是 profile 字段 |
|
|
183
|
+
| `CE_TUNNEL_BACKGROUND_ALLOW=1` | 父 Pi 许可显式 Start,不自动启动 |
|
|
184
|
+
| 非空 `CE_ALLOWLIST` | 显式 Pi 策略优先;阻止生成策略 conversion/registration,不建议普通 Tunnel 用户设置 |
|
|
185
|
+
| `CE_STORE_DIR` / `CE_STORE_FILE` | 已声明 Store 时仅可确认同一位置,冲突拒绝;不偷偷换库 |
|
|
186
|
+
| `CE_LEASE_TTL_SECONDS` | 覆盖配置 TTL,仍受 Host 合法范围限制,需重载;不是恢复开关 |
|
|
187
|
+
| `CE_TUNNEL_OFFLINE_TEST=1` | 仅隔离模拟器,正常使用不要设置 |
|
|
188
|
+
|
|
189
|
+
未设置显式 allowlist 时优先所选完整生成策略,再用扩展旁 allowlist。权限在 factory 加载时捕获;Save/其他 shell export 不会自动扩大内存 grants。child 只继承最小环境,不能用任意 `OPENAI_*` 改消息身份。
|
|
190
|
+
|
|
191
|
+
## 故障排查:先定位层,再进行最小修复
|
|
192
|
+
|
|
193
|
+
| 症状 | 检查与安全处理 |
|
|
194
|
+
|---|---|
|
|
195
|
+
| 安装失败 / 缺少运行时文件 | 可能是错误 Node/npm、制品不完整或源码未 build;先 `node --version`、`npm --version` 并核对制品 SHA256;tarball 按[独立安装指南](independent-install.md)核对载荷,不在 consumer build;源码在仓库根目录重新执行 `pnpm --dir packages/pi-chat-exchange run build`。不要用关闭资格门槛或删 Store 修安装 |
|
|
196
|
+
| Pi 中没有 `/ce-tunnel` / `/ce-status` | 可能未加载、加载失败或仍引用旧目录;先 `pi list` 对照原 source 与启动时 `-e`,查看加载拒绝码;仅保留一份扩展。源码先 build 再 `/reload`,已安装包则核对物理入口;不要再叠加第二份加载 |
|
|
197
|
+
| 发送失败 / 发送响应丢失 | 可能是未绑定、recipient 未授权、四项配对不符或结果未知;先 `/ce-status`、`/ce-tunnel status` 与固定拒绝码,核对当前精确 Endpoint;保留原 key/Message ID,未知结果停止核实,不以新 key、缺 ACK 或再次 Start 作为重发许可 |
|
|
198
|
+
| host / child Node 不合格 | doctor 分开看两者;批准 Node 必须通过 SQLite 全资格。host 需用正确 Node 启动;child canonical profile 修复用显式 migrate,先核实 STOPPED |
|
|
199
|
+
| client 缺失或信任拒绝 | doctor;核实独立安装及全链权限,不复制绕过不可信 Homebrew 祖先、不运行未准入 binary、不放宽 guard |
|
|
200
|
+
| `CE_TUNNEL_BACKGROUND_UNAUTHORIZED` | 核实父 Pi 的精确许可;在子 shell export 无效 |
|
|
201
|
+
| legacy 单 Session profile 的 register / sessions / revoke 拒绝 `CE_TUNNEL_PROFILE_INVALID` | 需先显式 `/ce-tunnel convert` 创建多 Session generation,按提示分别确认旧 runtime 已停止或更新及转换授权;不自动转换,不是 transport 未 STOPPED |
|
|
202
|
+
| `recipients: []` / CONNECTED 但不能发 | 核对 Advanced Messaging、Pi binding、当前 ChatGPT 工具、Store/Exchange/recipient,不重发原消息测通 |
|
|
203
|
+
| unclean exit 后 `CE_HOST_UNAVAILABLE` 且提示 local session-process mutex unreleased slot | 仅 operator 在完整离线维护窗口(所有 Pi/CE、heartbeat、后台启动器、自动重启和 recovery jobs 均停止并禁止重启,覆盖检查、协调、持久化和复查全程)并独立确认 owner 已死亡后,显式运行 `pnpm run reconcile:session-mutex --expect-store-dir <canonical-dir> --expect-store-file <basename> --expect-endpoint <endpoint> --expect-runtime-session <session> --expect-slot <slot> --expect-owner-version 1 --expect-owner-scope <sha256> --expect-owner-pid <pid> --expect-owner-birth <birth> --expect-owner-process-token <token> --expect-owner-handle-token <token> --expect-owner-sha256 <raw-byte-sha256> --expect-store-dev <dev> --expect-store-ino <ino> --expect-slot-dev <dev> --expect-slot-ino <ino> --expect-owner-dev <dev> --expect-owner-ino <ino> --offline-window-confirmed --owner-death-evidence <independent-reference>`(无 `--audit-log` 参数,未知参数一律拒绝,脚本不写任何 audit 文件);参数均须独立核实,无默认值。仅协调本地 mutex receipt,不是 CE ownership / Operator Recovery,不证明 CE end/detach;恢复本地可用性不授权恢复业务操作、CE read/ACK、detach、takeover 或 recovery,必须等待单独授权决定;不删锁、不对活 PID 协调、不在真实 Store 上试 acquire;发布分两阶段:先以 O_EXCL 写 `release-pending.json`(0600、内容与 owner 原始字节完全一致),fsync 文件与各层目录并完成全量复查后,才以原子 rename 为 `released.json` 作为唯一提交点;rename 之前的任何失败都原样保留 pending 制品并以固定理由退出;rename 抛错时仅当 `released.json` 与所准备的字节/身份完全一致才按已提交成功对待,否则同样硬停;rename 之后不再执行任何可失败操作;任何失败均要求人工复查,绝不重试、覆盖或删除 |
|
|
204
|
+
| no endpoint / `CE_HOST_MAPPING_INVALID` | 先核对当前 native Session、所选注册、加载策略与 release 证据;新/正常释放后显式 activate;UNKNOWN 不当作普通未绑定 |
|
|
205
|
+
| read/ACK 不可用 | 两个 opt-in 分别核对并显式加载;ACK 不开启 payload read |
|
|
206
|
+
| Inbox 看不到消息 | 核对四项配对与 join boundary;空页不是全库证明,不复制 DB/盲重发 |
|
|
207
|
+
| STARTING / READY_TIMEOUT | 等待在途终态与清理证据,核对目标/权限;UNKNOWN 不加第二个实例或无限 timeout |
|
|
208
|
+
| 重复命令 / MANAGER_BUSY | 核对 `pi list` 与 `-e` 是否重复,关闭多余 UI;不连按启动 |
|
|
209
|
+
| client 拒绝旧 `admin_ui` | 核实 STOPPED 后 `/ce-tunnel migrate`,只修 canonical schema/child Node,不扩大权限 |
|
|
210
|
+
| 外部实例 / 锁 / STOP_UNCONFIRMED | 保留状态和 ledger;Manager 可证 Stop 之外需另行人工授权,不删锁、不按进程名 kill |
|
|
211
|
+
|
|
212
|
+
renew/end/映射持久化未知均 fail-closed,不连续 activate/reload。record-backed run 最多一次 SIGTERM;重复 Stop 不保证重发信号。`migrate` 不读取 key、不换 Store、不授权消息,不是任意 YAML formatter。
|
|
213
|
+
|
|
214
|
+
Masked 输入不是保险箱:同进程恶意扩展、录屏、剪贴板、内存观测不在隔离保证内。只分享固定码与最少非秘密标识,勿贴 key、capability、正文、完整 Session/环境。隔离 harness、packaged tool discovery、实际 Tunnel 健康和人工消息验收是不同证据;本次变更不重做真实消息验收。
|