@moxuli/moremote 0.0.0-stage → 0.1.1
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/LICENSE +202 -0
- package/NOTICE +31 -0
- package/README.md +73 -2
- package/bin/moremote-cli.js +34 -0
- package/bin/moremote-service.js +7 -0
- package/dist/bindings.d.ts +6 -0
- package/dist/bindings.js +4 -0
- package/dist/cli.d.ts +1 -0
- package/dist/cli.js +325 -0
- package/dist/cloud-client.d.ts +43 -0
- package/dist/cloud-client.js +128 -0
- package/dist/config.d.ts +36 -0
- package/dist/config.js +68 -0
- package/dist/control-transport.d.ts +4 -0
- package/dist/control-transport.js +68 -0
- package/dist/control.d.ts +3 -0
- package/dist/control.js +297 -0
- package/dist/controls.d.ts +15 -0
- package/dist/controls.js +36 -0
- package/dist/crypto.d.ts +23 -0
- package/dist/crypto.js +68 -0
- package/dist/evidence.d.ts +19 -0
- package/dist/evidence.js +4 -0
- package/dist/journal.d.ts +104 -0
- package/dist/journal.js +132 -0
- package/dist/limits.d.ts +21 -0
- package/dist/limits.js +8 -0
- package/dist/official-client.d.ts +120 -0
- package/dist/official-client.js +162 -0
- package/dist/operations.d.ts +71 -0
- package/dist/operations.js +210 -0
- package/dist/pairing.d.ts +19 -0
- package/dist/pairing.js +68 -0
- package/dist/permission.d.ts +9 -0
- package/dist/permission.js +66 -0
- package/dist/projection.d.ts +24 -0
- package/dist/projection.js +35 -0
- package/dist/resources.d.ts +76 -0
- package/dist/resources.js +299 -0
- package/dist/runtime.d.ts +8 -0
- package/dist/runtime.js +375 -0
- package/dist/service.d.ts +21 -0
- package/dist/service.js +310 -0
- package/dist/supervisor.d.ts +15 -0
- package/dist/supervisor.js +175 -0
- package/dist/update-state.d.ts +30 -0
- package/dist/update-state.js +158 -0
- package/dist/updater.d.ts +9 -0
- package/dist/updater.js +152 -0
- package/docs/README.md +23 -0
- package/docs/STATE.md +155 -0
- package/docs/configuration.md +37 -0
- package/docs/conventions.md +9 -0
- package/docs/decisions/0001-managed-updates.md +19 -0
- package/docs/plans/2026-11-10-managed-updates.md +26 -0
- package/docs/plans/2026-11-10-notification-delivery.md +118 -0
- package/docs/releasing.md +34 -0
- package/docs/specs/01-architecture.md +102 -0
- package/docs/specs/02-encrypted-delivery.md +194 -0
- package/docs/specs/03-api-contract.md +397 -0
- package/docs/specs/04-control-and-receipt-lifecycle.md +175 -0
- package/docs/specs/05-endpoint-and-lifecycle.md +57 -0
- package/docs/specs/06-managed-updates.md +55 -0
- package/licenses/Paseo-0.15.3.txt +211 -0
- package/package.json +37 -4
- package/vectors/bearer-v1.json +6 -0
- package/vectors/envelope-v1.json +24 -0
|
@@ -0,0 +1,397 @@
|
|
|
1
|
+
# 03 — Relay HTTP API, version 1
|
|
2
|
+
|
|
3
|
+
**Status:** implementation detail of the owner-approved first notification/scoped-delivery iteration; review against the accepted architecture before coding
|
|
4
|
+
|
|
5
|
+
## Common rules
|
|
6
|
+
|
|
7
|
+
Base path is `/v1`. JSON is UTF-8 with bounded body parsing (128 KiB). Responses
|
|
8
|
+
use `{ok:true,...}` or `{ok:false,error:{code,message}}`; errors contain concise
|
|
9
|
+
codes, never raw private payloads. TLS is required except explicit loopback dev.
|
|
10
|
+
UUID identifiers are lowercase canonical strings. Timestamps are integer epoch
|
|
11
|
+
milliseconds. See [[02-encrypted-delivery]] for exact envelopes.
|
|
12
|
+
|
|
13
|
+
Bearers are independent32-byte random canonical unpadded-base64url capabilities.
|
|
14
|
+
Persist only SHA256 over the UTF-8 bytes of that canonical bearer TEXT, not the
|
|
15
|
+
decoded random bytes; serialize hashes as lowercase64-character hex. Compare
|
|
16
|
+
fixed-length hashes without early exit. Host, enrollment and phone roles are distinct. Companion-host authentication
|
|
17
|
+
is not an official daemon credential. Unauthenticated enrollment creation is
|
|
18
|
+
bounded by configured per-origin/IP rate and record limits; an arbitrary ID is
|
|
19
|
+
never read authority. No permissive CORS or browser-cookie authentication.
|
|
20
|
+
|
|
21
|
+
An API origin is operator/application configuration, never derived from a signed
|
|
22
|
+
host's human-readable name. Loopback plaintext requires explicit development
|
|
23
|
+
configuration at both endpoints; ordinary enrollment rejects plaintext URLs.
|
|
24
|
+
|
|
25
|
+
Public enrollment is quota-bound, not invitation-authenticated. The deployment
|
|
26
|
+
can fail closed with503 while disabled/misconfigured, or429 when normal/recovery
|
|
27
|
+
route allowance is exhausted. Daily quota `Retry-After` refers to the original
|
|
28
|
+
UTC-day reset; clients honor it without resealing envelopes, extending authority
|
|
29
|
+
or replaying an uncertain mutation. All routes use normal allowance first.
|
|
30
|
+
Only after normal exhaustion can fixed-method/path-eligible routes fall back to
|
|
31
|
+
the bounded recovery reserve; a caller priority header cannot select it. Cached
|
|
32
|
+
normal exhaustion must not block eligible fallback. A quota/routing
|
|
33
|
+
acknowledgement is not endpoint execution evidence. These guards reduce bounded
|
|
34
|
+
downstream work; incoming/rejected requests remain potentially billable and no
|
|
35
|
+
account-level money ceiling is implied.
|
|
36
|
+
|
|
37
|
+
## Enrollment
|
|
38
|
+
|
|
39
|
+
### POST /pairs
|
|
40
|
+
|
|
41
|
+
Companion creates local UUID `pairId`, root key and host/enrollment capabilities.
|
|
42
|
+
Body: `{pairId,hostTokenHash,enrollmentTokenHash,expiresAt}`. Hashes are lowercase
|
|
43
|
+
64-character SHA256 hex; expiry is at most ten minutes from now. Creation is
|
|
44
|
+
atomic and rejects a conflicting identity, including after revocation. Exact
|
|
45
|
+
same-configuration retry returns the same enrollment state without allocating
|
|
46
|
+
another record. No endpoint key is transmitted. Host bearer proves subsequent
|
|
47
|
+
ownership. Server refuses an already expired offer.
|
|
48
|
+
The internal admission catalog binds the original create parameters before
|
|
49
|
+
forwarding to PairObject. A retained UUID is not permission to replace credentials
|
|
50
|
+
or extend offer expiry when the PairObject is missing/purged. Exact original
|
|
51
|
+
retries can finish a missing create only within the original live offer interval;
|
|
52
|
+
they never allocate a second catalog reservation. Legacy unbound catalog rows
|
|
53
|
+
reject create retries fail-closed without removing authenticated routing access.
|
|
54
|
+
The internal fingerprint contains only a digest of existing public offer fields,
|
|
55
|
+
never endpoint secrets, and adds no public request fields.
|
|
56
|
+
|
|
57
|
+
### POST /pairs/{pairId}/claim
|
|
58
|
+
|
|
59
|
+
Enrollment bearer. Body: `{claimId,phoneTokenHash,proof}`. Phone generates and
|
|
60
|
+
retains its token and claim ID before the first request. `proof` is an enrollment
|
|
61
|
+
channel envelope with ID `claimId`; encrypted JSON is
|
|
62
|
+
`{type:"phoneHello",claimId,phoneTokenHash}`. One claim wins atomically. Exact
|
|
63
|
+
retry by the same claim/token/proof succeeds; changed bytes or another claimant
|
|
64
|
+
conflict. The server records only a pending phone, not execution authority.
|
|
65
|
+
Proof issuedAt/expiresAt must be within the original offer interval (no earlier
|
|
66
|
+
than expiresAt minus600seconds and no later than the original offer expiresAt).
|
|
67
|
+
|
|
68
|
+
### GET /pairs/{pairId}
|
|
69
|
+
|
|
70
|
+
Host or phone bearer. Returns role-appropriate bounded pairing state. Host sees
|
|
71
|
+
pending claim ID/token hash/proof. Phone sees pending/active/revoked and the
|
|
72
|
+
activation proof, not host credentials. Enrollment bearer cannot read this API.
|
|
73
|
+
The companion verifies the phone proof under its endpoint key and confirms that
|
|
74
|
+
the decrypted token hash matches this exact pending claim.
|
|
75
|
+
|
|
76
|
+
### POST /pairs/{pairId}/activate
|
|
77
|
+
|
|
78
|
+
Host bearer. Body `{claimId,proof}`. Activation envelope ID equals `claimId`,
|
|
79
|
+
channel `activation`. Encrypted JSON contains `{type:"companionHello",claimId,
|
|
80
|
+
phoneTokenHash,daemonServerId,hostName}`. An exact active retry is idempotent.
|
|
81
|
+
Changed claim/proof conflicts. Companion locally persists its accepted phone
|
|
82
|
+
before any official mutation; phone independently decrypts/validates the proof
|
|
83
|
+
before trusting cloud active state. App associates only an exact authenticated
|
|
84
|
+
saved host identity, not a name match.
|
|
85
|
+
Activation must complete before the original offer expiry and its proof must be
|
|
86
|
+
inside that original interval. A completed exact retry is audit only, never an
|
|
87
|
+
expiry extension. Endpoint proof validation applies the same original deadline.
|
|
88
|
+
|
|
89
|
+
### DELETE /pairs/{pairId}
|
|
90
|
+
|
|
91
|
+
Host or phone bearer. Revokes relay authority for the exact pairing and queued
|
|
92
|
+
operations. Returns `{ok:true,status:"revoked",authority:"relay"}`, never endpoint
|
|
93
|
+
confirmation. Other pairings remain unchanged; dispatched official writes cannot
|
|
94
|
+
be undone. Remove device, viewing lease, snapshot and user-message ciphertext
|
|
95
|
+
immediately, but preserve minimal encrypted receipts and narrow original-role
|
|
96
|
+
control/outcome access through retention. The phone first sends the encrypted
|
|
97
|
+
revoke control described in04 and waits for its exact authenticated companion
|
|
98
|
+
controlReceipt before reporting computer-confirmed revocation. Offline or withheld
|
|
99
|
+
controls remain waiting/unknown. Host stop/uninstall can stop local execution
|
|
100
|
+
without contacting cloud.
|
|
101
|
+
|
|
102
|
+
## State and attention
|
|
103
|
+
|
|
104
|
+
### PUT /pairs/{pairId}/state; GET /pairs/{pairId}/state
|
|
105
|
+
|
|
106
|
+
Host writes, phone reads. Body/response contains `{envelope}` with `state` channel.
|
|
107
|
+
Only the latest nonexpired snapshot keeps ciphertext, monotonic by issuedAt then
|
|
108
|
+
immutable ID. Each state ID/digest remains a conflict guard through its own
|
|
109
|
+
original envelope expiry, including after supersession; no additional24hour
|
|
110
|
+
state audit retention applies. Exact retries do not refresh authority or expiry;
|
|
111
|
+
conflicting IDs/older snapshots never replace newer state. After expiry, a retry
|
|
112
|
+
cannot be admitted as new live state. Supersession clears only the previous
|
|
113
|
+
payload-bearing state, never rewrites older null tombstones. Operation, control,
|
|
114
|
+
attention and minimal authenticated outcome retention is unchanged.
|
|
115
|
+
Encrypted state is a versioned object with verified daemon
|
|
116
|
+
identity, host name, measured timestamp and bounded actual tasks/available usage.
|
|
117
|
+
No complete chat, code files or credentials.
|
|
118
|
+
|
|
119
|
+
### PUT /pairs/{pairId}/device
|
|
120
|
+
|
|
121
|
+
Phone bearer, active pairing. Body `{token,environment,locale}`; token is bounded
|
|
122
|
+
nonempty hex, environment `sandbox|production`, locale `zh-Hans|en`. The service
|
|
123
|
+
binds to the configured app topic, not an arbitrary caller-controlled bundle.
|
|
124
|
+
Device replacement invalidates only the former exact token/environment. Registration
|
|
125
|
+
never requests notification permission from the server side.
|
|
126
|
+
Keep one current registration per active pair without age-based expiry: a phone
|
|
127
|
+
staying background24hours does not invalidate an APNs token. Replacement, exact
|
|
128
|
+
authoritative provider invalidation or pair disable/revoke removes it. An internal
|
|
129
|
+
unique registration identity prevents stale retirement even when token/environment
|
|
130
|
+
and millisecond registration timestamps are equal.
|
|
131
|
+
|
|
132
|
+
### PUT /pairs/{pairId}/presence; DELETE /pairs/{pairId}/presence
|
|
133
|
+
|
|
134
|
+
Phone bearer. Put `{topic,expiresAt}` where topic is a keyed opaque conversation
|
|
135
|
+
tag and lease lasts at most60seconds. Clear on scene inactivity or route exit;
|
|
136
|
+
refresh only while genuinely viewing the exact conversation. Topic is base64url
|
|
137
|
+
HMAC-SHA256 using a separately HKDF-derived `presence` key over UTF-8 agentId;
|
|
138
|
+
HKDF info is compact `[1,pairId,"presence"]`. Companion computes the same tag.
|
|
139
|
+
No official heartbeat/read acknowledgement is sent by the companion.
|
|
140
|
+
|
|
141
|
+
### POST /pairs/{pairId}/attention; GET /pairs/{pairId}/attention/{eventId}
|
|
142
|
+
|
|
143
|
+
Host writes, phone reads exact event. Body `{id,kind,topic,envelope}`; kind is
|
|
144
|
+
`finished|question|permission|error`, envelope channel `attention` and ID `id`.
|
|
145
|
+
Encrypted content contains `{agentId,requestId?,requestBinding?,kind,timestamp}`;
|
|
146
|
+
question/permission attention includes the exact companion-issued requestBinding.
|
|
147
|
+
Event identity is stable across reconnect/retry. Exact retry does not send another
|
|
148
|
+
push; conflicting bytes are rejected. Only currently valid events get attempts.
|
|
149
|
+
Suppress this app's push if a genuine unexpired matching presence lease exists.
|
|
150
|
+
No inference from the official shouldNotify flag. APNs copy is generic/localized.
|
|
151
|
+
|
|
152
|
+
Persist notification attempt state before I/O. A lost APNs response is uncertain,
|
|
153
|
+
not proof of failure; retries reuse the same apns-id/collapse identity with bounded
|
|
154
|
+
backoff/expiry and do not promise exactly-once display. Retire a token only if it
|
|
155
|
+
still equals the exact failed registration and APNs result is authoritative.
|
|
156
|
+
|
|
157
|
+
Logical event outcome is separate from the latest attempt result and retry
|
|
158
|
+
eligibility. Persist an unresolved-attempt marker before provider I/O. A later
|
|
159
|
+
definite rejection, unavailable configuration/registration, presence suppression,
|
|
160
|
+
retry-budget limit or payload expiry cannot disprove an earlier request whose
|
|
161
|
+
response was lost: retain logical `uncertain` and stop scheduling independently.
|
|
162
|
+
An actual provider acceptance can establish `accepted`; explicit resolve/revoke
|
|
163
|
+
remain lifecycle transitions and do not claim to retract earlier notifications.
|
|
164
|
+
Known first-attempt failures stay known failures, not blanket uncertainty.
|
|
165
|
+
`delivery.reason` describes the latest observed attempt, not proof that an
|
|
166
|
+
earlier uncertain attempt was rejected. Expired ciphertext is still removed on
|
|
167
|
+
schedule while the bounded delivery outcome identity remains.
|
|
168
|
+
|
|
169
|
+
## Scoped commands
|
|
170
|
+
|
|
171
|
+
### POST /pairs/{pairId}/commands
|
|
172
|
+
|
|
173
|
+
Phone bearer, active pairing. Body `{envelope}` with `command` channel. Plaintext
|
|
174
|
+
is `{type:"send",agentId,text,messageId}` or
|
|
175
|
+
`{type:"permission",agentId,requestId,requestBinding,response}`. For send, `messageId` equals
|
|
176
|
+
envelope ID. Permission response is the verified upstream response shape, with
|
|
177
|
+
current-request/action validation on the companion; no arbitrary RPC escape.
|
|
178
|
+
The recipient rejects unknown types/fields and content outside supported bounds.
|
|
179
|
+
The binding identifies the exact observed request occurrence, original input and
|
|
180
|
+
actual actions, not merely requestId. Question replies use the current question's
|
|
181
|
+
permission response and original-header answer mapping defined in04, not a new
|
|
182
|
+
send or arbitrary reply RPC. Endpoint validation retires changed/replaced bindings.
|
|
183
|
+
|
|
184
|
+
Accept an exact immutable retry idempotently. A same-ID different-envelope retry
|
|
185
|
+
is409. New work cannot override terminal records. Admission is not execution.
|
|
186
|
+
|
|
187
|
+
### GET /pairs/{pairId}/commands
|
|
188
|
+
|
|
189
|
+
Host bearer. Returns a bounded page of available valid operations and pending
|
|
190
|
+
state; it does not create user presence or imply execution. Expired operations
|
|
191
|
+
are ineligible before response. Polling uses bounded backoff; no busy loop.
|
|
192
|
+
|
|
193
|
+
### POST /pairs/{pairId}/commands/{operationId}/dispatch
|
|
194
|
+
|
|
195
|
+
Host bearer. Atomically acquires the irrevocable execution boundary if operation
|
|
196
|
+
is active, nonexpired and not revoked/cancelled. Returns `dispatchAllowed:true`
|
|
197
|
+
only on the first successful transition. Repeated calls return the existing state
|
|
198
|
+
with `dispatchAllowed:false`. A crash after the boundary never reauthorizes a
|
|
199
|
+
second official write. The companion writes its local dispatch journal before
|
|
200
|
+
requesting this transition and never writes the daemon if the response is lost.
|
|
201
|
+
Unknown outcome is reconciled rather than resent.
|
|
202
|
+
|
|
203
|
+
### DELETE /pairs/{pairId}/commands/{operationId}
|
|
204
|
+
|
|
205
|
+
Phone bearer. Cancels only relay work not dispatched. Returns explicit cancelled
|
|
206
|
+
or too-late plus `authority:"relay"`; it never confirms endpoint cancellation or
|
|
207
|
+
undo. The phone first posts an authenticated encrypted cancel control and trusts
|
|
208
|
+
only the companion's exact sealed controlReceipt for computer-confirmed state.
|
|
209
|
+
Revocation blocks future relay dispatch but preserves minimal outcome evidence.
|
|
210
|
+
|
|
211
|
+
### POST /pairs/{pairId}/commands/{operationId}/receipt
|
|
212
|
+
|
|
213
|
+
Original host bearer, including narrow post-revoke reconciliation. Body
|
|
214
|
+
`{state,revision,envelope}`; state is `accepted|resolved|rejected|unknown`, revision
|
|
215
|
+
is a positive safe integer. Receipt-channel envelope ID equals operationId and
|
|
216
|
+
decrypted plaintext is `{operationId,state,revision,code?}`. Visible revision must
|
|
217
|
+
match encrypted revision at endpoints. Cloud rejects lower revisions and same-
|
|
218
|
+
revision conflicting bytes; exact retries are harmless. Admission accepted is not
|
|
219
|
+
agent completion. Allowed transitions: dispatched→accepted/resolved/rejected/unknown;
|
|
220
|
+
accepted→resolved/rejected; unknown→accepted/resolved/rejected after positive
|
|
221
|
+
reconciliation. Resolved/rejected are terminal. Never regress accepted to unknown.
|
|
222
|
+
The phone validates an authenticated persisted revision watermark and trusts the
|
|
223
|
+
minimal encrypted receipt, not cloud state. Details and question resolution rules
|
|
224
|
+
are in04.
|
|
225
|
+
|
|
226
|
+
This receipt POST accepts a first upload or unchanged retry after the receipt's
|
|
227
|
+
own header expiry while the original retained operation still exists before its
|
|
228
|
+
fixed expiry+24h deadline. It admits read-only historical attestation, never a new
|
|
229
|
+
action. Preserve the original sealed bytes; do not reseal to refresh transport.
|
|
230
|
+
All role, framing,8KiB size, at-most600s header interval, future-issue skew,
|
|
231
|
+
revision and state-transition checks still apply. A purged parent stays404; no
|
|
232
|
+
payload authority or retention is renewed. See04 for the shared historical rule.
|
|
233
|
+
|
|
234
|
+
### GET /pairs/{pairId}/commands/{operationId}
|
|
235
|
+
|
|
236
|
+
Original phone or host bearer, including narrow post-revoke outcome access.
|
|
237
|
+
Returns original envelope while live, transport state, revision and retained
|
|
238
|
+
minimal encrypted receipt. Command ciphertext expires at original TTL; receipt
|
|
239
|
+
ciphertext survives until original command expiry+24hours, independently of its
|
|
240
|
+
own600second header interval. Historical authentication is read-only. After
|
|
241
|
+
retention the record is404/unavailable, never an unverifiable cloud-only success.
|
|
242
|
+
|
|
243
|
+
## Retention, restart and testing
|
|
244
|
+
|
|
245
|
+
All authoritative transitions persist transactionally in SQLite-backed Durable
|
|
246
|
+
Objects. In-memory maps alone cannot establish dedupe, claim or revocation.
|
|
247
|
+
Payload TTL is not extended by read/retry. Expired payloads and device/presence
|
|
248
|
+
state are actively cleaned; bounded terminal/tombstone retention is24hours after
|
|
249
|
+
expiry. Keep no private body in HTTP logs or diagnostics. Limit per-pair operation
|
|
250
|
+
and attention counts; errors are explicit rather than silent eviction of live work.
|
|
251
|
+
|
|
252
|
+
Wire vectors and conformance tests are copied as versioned public protocol data
|
|
253
|
+
into independent endpoint repos; runtime imports must not reach sibling projects.
|
|
254
|
+
Local checks exercise actual Worker storage semantics, endpoints and companion
|
|
255
|
+
crypto/action transitions. No assertion that a local emulator is a production
|
|
256
|
+
APNs connection or real device delivery is permitted.
|
|
257
|
+
|
|
258
|
+
## Exact response names and notification routing
|
|
259
|
+
|
|
260
|
+
Successful responses carry `ok:true`. First pair creation returns
|
|
261
|
+
`{ok:true,pairId,status:"pending"}` (`201`). An exact existing retry is200 with
|
|
262
|
+
status `pending|active`; revoked/expired offers conflict409, never succeed with
|
|
263
|
+
those statuses. Claim returns `{ok:true,status:"pending"|"active",claimId}`;
|
|
264
|
+
there is no `claimed` status. Activation returns `{ok:true,status:"active"}`.
|
|
265
|
+
Revocation returns `{ok:true,status:"revoked",authority:"relay"}`.
|
|
266
|
+
`GET /pairs/{pairId}` returns:
|
|
267
|
+
|
|
268
|
+
```json
|
|
269
|
+
{"ok":true,"pair":{"pairId":"11111111-1111-4111-8111-111111111111","state":"pending","pendingClaim":null,"activationProof":null}}
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
Pair `state` is `pending|active|revoked|expired`. Only the host sees a non-null
|
|
273
|
+
`pendingClaim:{claimId,phoneTokenHash,proof}`. Phone reads always receive null for
|
|
274
|
+
that field. Both authorized roles see `activationProof:Envelope|null`, bounded by
|
|
275
|
+
its original expiry. Neither response includes host/enrollment bearer material.
|
|
276
|
+
The QR/raw JSON offer encoding is specified in02 and is never a cloud payload.
|
|
277
|
+
|
|
278
|
+
Command POST and exact GET return flattened fields
|
|
279
|
+
`{ok:true,operationId,state,digest,envelope,receipt,revision,expiresAt}`. Both encrypted
|
|
280
|
+
fields are `Envelope|null`; `digest` is a lowercase SHA256 hex digest of the
|
|
281
|
+
immutable accepted JSON body. Transport `state` is
|
|
282
|
+
`queued|dispatched|cancelled|expired|revoked|accepted|resolved|rejected|unknown`.
|
|
283
|
+
GET commands returns `{ok:true,commands:[<same command fields without ok>],
|
|
284
|
+
hasMore:boolean}`; the first32 available operations are ordered by expiry then
|
|
285
|
+
ID. After processing that page, polling exposes remaining queued operations.
|
|
286
|
+
Dispatch adds `dispatchAllowed:boolean` to the exact-command response. Cancel
|
|
287
|
+
adds `outcome:"cancelled"|"too-late"`. Receipt POST takes
|
|
288
|
+
`{state:"accepted"|"resolved"|"rejected"|"unknown",revision,envelope:<receipt>}`
|
|
289
|
+
and returns the exact-command response. A late positive reconciliation may update
|
|
290
|
+
minimal authenticated receipt/state after payload expiry/revocation, but never
|
|
291
|
+
restore user ciphertext or extend retention. Both DELETE responses explicitly
|
|
292
|
+
carry `authority:"relay"`; endpoint confirmation requires the04 control receipt.
|
|
293
|
+
|
|
294
|
+
State PUT/GET returns `{ok:true,envelope:Envelope|null}`; device PUT returns
|
|
295
|
+
`{ok:true,registered:true}`; presence PUT returns `{ok:true,expiresAt}`, and DELETE
|
|
296
|
+
returns `{ok:true,cleared:true}`. Attention POST/GET returns
|
|
297
|
+
`{ok:true,id,kind,topic,envelope,digest,resolvedAt,delivery:{state,attempts,reason?}}`.
|
|
298
|
+
Delivery states are `queued|inflight|retry|uncertain|accepted|rejected|unavailable|
|
|
299
|
+
suppressed|expired|revoked|resolved`; they never assert display or acknowledgement.
|
|
300
|
+
Missing configuration is `unavailable`, not provider acceptance.
|
|
301
|
+
|
|
302
|
+
APNs custom data is exactly `pairId,eventId,kind,route`, beside generic localized
|
|
303
|
+
`aps`. `route` is the original attention envelope, never a plaintext conversation
|
|
304
|
+
identifier. Attention ingestion rejects any event whose complete alert payload
|
|
305
|
+
would exceed4,096 UTF-8 bytes in either supported locale (`413`,
|
|
306
|
+
`apns_payload_too_large`), even before a device registers. No route is silently
|
|
307
|
+
omitted. The phone may authenticate/decrypt this envelope through an explicitly
|
|
308
|
+
read-only navigation path after expiry, to open an already-verified saved host
|
|
309
|
+
and conversation without a live cloud lookup. This never authorizes a mutation
|
|
310
|
+
or bypasses expiry/current-request checks on an action.
|
|
311
|
+
|
|
312
|
+
## Bounded identity non-resurrection policy
|
|
313
|
+
|
|
314
|
+
Revocation immediately removes device/presence and user-message/snapshot payloads.
|
|
315
|
+
Minimal authenticated receipt ciphertext remains separate. It retains
|
|
316
|
+
pair authentication hashes and operation outcome identities until at least
|
|
317
|
+
24hours after revocation and each retained child's original expiry. Terminal
|
|
318
|
+
records are then purged by alarms; this is not an eternal global UUID blacklist.
|
|
319
|
+
An identical old create request cannot recreate authority after purge: its
|
|
320
|
+
original ten-minute offer expiry is past and creation returns400. Old claim and
|
|
321
|
+
activation proofs are independently expired, and an old QR is never a fresh
|
|
322
|
+
enrollment instruction. Endpoints always generate new pair IDs, independent root
|
|
323
|
+
keys and capabilities for explicit re-pairing, and demand the fresh authenticated
|
|
324
|
+
handshake. An operator cannot claim perpetual global UUID non-reuse after the
|
|
325
|
+
bounded metadata has been deleted.
|
|
326
|
+
|
|
327
|
+
## Endpoint controls and invalidation routes
|
|
328
|
+
|
|
329
|
+
[04](04-control-and-receipt-lifecycle.md) specifies authenticated control semantics
|
|
330
|
+
and exact encrypted plaintext. HTTP responses are:
|
|
331
|
+
|
|
332
|
+
- `POST /pairs/{pairId}/controls`, phone `{envelope}`: `201` first, `200` exact
|
|
333
|
+
retry; `{ok:true,control:{controlId,envelope,receipt,expiresAt}}`.
|
|
334
|
+
- `GET /pairs/{pairId}/controls`, original host:
|
|
335
|
+
`{ok:true,controls:[{controlId,envelope,receipt,expiresAt}]}`, at most32 live
|
|
336
|
+
unacknowledged controls, ordered expiry thenID.
|
|
337
|
+
- `POST /pairs/{pairId}/controls/{controlId}/receipt`, original host `{envelope}`:
|
|
338
|
+
`{ok:true,control:{controlId,envelope,receipt,expiresAt}}`; exact retry succeeds,
|
|
339
|
+
different bytes409. A controlReceipt is one final encrypted revision1 result.
|
|
340
|
+
- `GET /pairs/{pairId}/controls/{controlId}`, original phone: same wrapped control.
|
|
341
|
+
|
|
342
|
+
Control envelopes have at most300seconds authority. Minimal receipt envelopes
|
|
343
|
+
have at most600seconds header interval, current attestation issuedAt and8KiB
|
|
344
|
+
serialized maximum. They remain available for historical verification until the
|
|
345
|
+
original control expiresAt+24hours. Original host/phone capabilities retain only
|
|
346
|
+
these surfaces, pairing status and exact command outcome/receipt reconciliation
|
|
347
|
+
after relay revocation; no new normal command or positive dispatch is admitted.
|
|
348
|
+
|
|
349
|
+
The controlReceipt POST has the same historical first-upload allowance: an
|
|
350
|
+
immutable sealed final receipt can arrive after its own header expires only while
|
|
351
|
+
the original control audit record remains retained. It cannot recreate a purged
|
|
352
|
+
control, change final bytes or extend original expiry+24h. Normal control POST,
|
|
353
|
+
command/enrollment admission and action dispatch retain strict live checks.
|
|
354
|
+
|
|
355
|
+
`POST /pairs/{pairId}/attention/{eventId}/resolve`, host `{resolvedAt}`, returns the
|
|
356
|
+
same attention view with the first persisted `resolvedAt` and
|
|
357
|
+
`delivery.state:"resolved"`. It stops future queued/retry selection transactionally.
|
|
358
|
+
An existing APNs request cannot be retracted. Already displayed notifications
|
|
359
|
+
still require current requestBinding validation before any action.
|
|
360
|
+
|
|
361
|
+
Generic alerts set `aps.category` to `moremote.enhancement.<kind>`, exactly one of
|
|
362
|
+
`finished|question|permission|error`. Permission actions open foreground review
|
|
363
|
+
only. Question text replies require the actual supported single-question form
|
|
364
|
+
and exact binding; unsupported forms open original review. Categories grant no
|
|
365
|
+
authority beyond explicit user action and strict endpoint validation.
|
|
366
|
+
|
|
367
|
+
## Public admission and interoperability bounds
|
|
368
|
+
|
|
369
|
+
All pair routing first consults a bounded admitted-ID catalog; an arbitrary UUID
|
|
370
|
+
read must not instantiate a new pair Durable Object. Only create admission can
|
|
371
|
+
reserve a new identity. The current centralized policy allows30 create attempts
|
|
372
|
+
(including exact-ID retries) per origin/trusted-IP hash per one-hour window,
|
|
373
|
+
10,000 admitted routable pair IDs, and10,000 concurrent source counters. Active
|
|
374
|
+
pairs remain catalogued; fixed internal retention probes retire expired records.
|
|
375
|
+
This is not a public arbitrary-target proxy and does not imply a complete
|
|
376
|
+
provider traffic/billing ceiling. Production ingress abuse/budget policy and
|
|
377
|
+
trusted client-IP propagation through Pages are explicit operator gates.
|
|
378
|
+
|
|
379
|
+
The public synthetic bearer framing vector uses43 literal `A` characters:
|
|
380
|
+
`AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA`. SHA256 of its UTF-8 text is
|
|
381
|
+
`0f007385b6f9d4b7eeb2748605afe1a984a0a3bfa3f014d09e2a784ce9e5cd1a`.
|
|
382
|
+
SHA256 of the decoded32zero bytes would be
|
|
383
|
+
`66687aadf862bd776c8fc18b8e9f8e20089714856ee233b3902a591d0d5f2925`,
|
|
384
|
+
which is explicitly the wrong framing. Versioned fixture
|
|
385
|
+
`tests/vectors/bearer-v1.json` was generated independently with Node:crypto.
|
|
386
|
+
This fixed public value is never a usable production credential.
|
|
387
|
+
|
|
388
|
+
## Response byte budget
|
|
389
|
+
|
|
390
|
+
The128KiB bound applies to JSON requests, not responses. Every complete JSON
|
|
391
|
+
response is at most5MiB (5,242,880 UTF-8 bytes), enforced by the service and
|
|
392
|
+
independently bounded by clients before parsing. Commands/control lists have at
|
|
393
|
+
most32 entries;32 near-maximum envelopes can approach4MiB. Exact command reads
|
|
394
|
+
may contain both original128KiB-bounded payload and a separate8KiB receipt; a
|
|
395
|
+
host pairing response may contain two bounded proofs. A128KiB response reader
|
|
396
|
+
would permanently reject valid work and is nonconforming. This larger response
|
|
397
|
+
budget never raises the128KiB request or64KiB decrypted command-content limits.
|
|
@@ -0,0 +1,175 @@
|
|
|
1
|
+
# 04 — Endpoint revocation, request instances and verifiable receipts
|
|
2
|
+
|
|
3
|
+
**Status:** required implementation corrections from independent specification review
|
|
4
|
+
**Date:** 2026-11-10
|
|
5
|
+
|
|
6
|
+
This capability refines02/03; implementations must apply these requirements before
|
|
7
|
+
claiming the first delivery complete. A relay acknowledgement is never endpoint
|
|
8
|
+
execution or endpoint revocation proof.
|
|
9
|
+
|
|
10
|
+
## Endpoint-authenticated control
|
|
11
|
+
|
|
12
|
+
Add independently derived envelope channels `control` and `controlReceipt` using
|
|
13
|
+
the exact existing v1 HKDF/AAD framing. A control has a fresh UUID, at most300s
|
|
14
|
+
expiry, and encrypted payload `{type:"cancel",operationId}` or `{type:"revoke"}`.
|
|
15
|
+
|
|
16
|
+
- `POST /pairs/{pairId}/controls`: phone bearer, `{envelope}`. Accept while active
|
|
17
|
+
or during that pairing's retained revocation state. Exact-ID/bytes retries are
|
|
18
|
+
idempotent; conflicting bytes reject. Persist before replying.
|
|
19
|
+
- `GET /pairs/{pairId}/controls`: original host bearer, bounded valid controls.
|
|
20
|
+
Original credentials retain this narrow read/ack surface after relay revocation,
|
|
21
|
+
not permission to admit/dispatch another normal command.
|
|
22
|
+
- `POST /pairs/{pairId}/controls/{controlId}/receipt`: original host bearer,
|
|
23
|
+
`{envelope}` with channel controlReceipt and ID controlId. Encrypted receipt is
|
|
24
|
+
`{controlId,type,operationId?,state,revision}`; state cancelled|revoked|tooLate,
|
|
25
|
+
revision is1. This is one immutable final sealed result: persist before ack;
|
|
26
|
+
exact retry succeeds, different bytes return409. No visible revision is required.
|
|
27
|
+
- `GET /pairs/{pairId}/controls/{controlId}`: original phone bearer, returns
|
|
28
|
+
`{ok:true,control:{controlId,envelope,receipt,expiresAt}}` while retained.
|
|
29
|
+
- List response is `{ok:true,controls:[{controlId,envelope,receipt,expiresAt}]}`.
|
|
30
|
+
|
|
31
|
+
Phone sends encrypted control before issuing existing cloud DELETE (the latter
|
|
32
|
+
stops honest relay dispatch immediately). Cloud DELETE alone returns relay
|
|
33
|
+
revocation/cancellation facts only. The phone reports endpoint-confirmed state
|
|
34
|
+
only after verifying the exact companion controlReceipt. When the computer is
|
|
35
|
+
offline or the relay withholds a control, show waiting/unknown rather than claim
|
|
36
|
+
instant endpoint revocation. An already dispatched action returns tooLate; it
|
|
37
|
+
cannot be undone. These physical limitations do not justify a false success.
|
|
38
|
+
|
|
39
|
+
Companion processes controls before ordinary dispatch in each acquisition cycle,
|
|
40
|
+
and persists pair/operation tombstones before producing authenticated receipts.
|
|
41
|
+
Recheck local tombstones immediately before daemon I/O. Pair revocation disables
|
|
42
|
+
all subsequent local dispatch, independent of any later cloud active flag. A
|
|
43
|
+
crash after local revocation cannot restore execution. Persist the sealed control
|
|
44
|
+
receipt so it can be retransmitted without retaining executable authority.
|
|
45
|
+
|
|
46
|
+
Revoked pair records keep original hashed role credentials only for narrow control
|
|
47
|
+
receipt and minimal outcome reads, for the documented24h retention. Remove device
|
|
48
|
+
registration, viewing leases, snapshots and user-message ciphertext immediately.
|
|
49
|
+
Do not erase the only outcome evidence while claiming durable verifiability.
|
|
50
|
+
Endpoint key material needed for read-only final verification remains protected
|
|
51
|
+
until acknowledgement/retention cleanup; no automatic re-enrollment.
|
|
52
|
+
|
|
53
|
+
## Exact permission/request-instance binding
|
|
54
|
+
|
|
55
|
+
Every pending request offered for enhanced question/approval use has an opaque
|
|
56
|
+
`requestBinding` (canonical base64url32bytes) created by the companion. Include it
|
|
57
|
+
inside authenticated attention/state. Permission command plaintext becomes
|
|
58
|
+
`{type:"permission",agentId,requestId,requestBinding,response}`.
|
|
59
|
+
|
|
60
|
+
Binding represents the exact observed request occurrence, kind, original input,
|
|
61
|
+
advertised actions and suggestions. The companion stores an occurrence identity
|
|
62
|
+
and canonical source fingerprint, and derives an authenticated pairing-specific
|
|
63
|
+
binding. The phone echoes it unchanged, not recomputes or chooses an occurrence.
|
|
64
|
+
|
|
65
|
+
On connection-generation change, resolution/removal or any canonical source
|
|
66
|
+
change, retire the old occurrence/binding. If continuity cannot be established,
|
|
67
|
+
require fresh state and a new user decision; an old notification still navigates
|
|
68
|
+
read-only but cannot approve a replacement. Before dispatch, refresh the actual
|
|
69
|
+
pending request, match its binding/source and validate the selected actual action.
|
|
70
|
+
Do not depend on requestId never being reused.
|
|
71
|
+
|
|
72
|
+
Reject response fields outside the real upstream response shape. Any remembered
|
|
73
|
+
permissions must be an actual offered suggestion explicitly selected by the user;
|
|
74
|
+
never accept an arbitrary new grant or silently set remember. Edited input is
|
|
75
|
+
limited to existing editable string fields plus supported question answers.
|
|
76
|
+
|
|
77
|
+
### Question response wire mapping
|
|
78
|
+
|
|
79
|
+
Question replies use the same permission command, not a new send and not an
|
|
80
|
+
unknown `reply` operation. The exact target's kind must be `question`. The native
|
|
81
|
+
codec's upstream response is `{behavior:"allow",selectedActionId?,updatedInput}`,
|
|
82
|
+
where updatedInput preserves the original input and adds
|
|
83
|
+
`answers:{[originalQuestionHeader]:answerString}`. Use a currently advertised allow
|
|
84
|
+
action. All required questions must have valid answers; choices/multi-choice and
|
|
85
|
+
allow-other/allow-empty follow the original typed form, not an invented codec.
|
|
86
|
+
|
|
87
|
+
A notification text reply may answer a single supported question only if its
|
|
88
|
+
actual form permits that text. Multiple/unsupported structured questions open the
|
|
89
|
+
native original request form; do not duplicate the same text into several answers
|
|
90
|
+
or map it to a newer request. The companion validates the original question schema
|
|
91
|
+
again before sending the real official permission response. Explicit deny uses
|
|
92
|
+
its actual offered action and original request binding.
|
|
93
|
+
|
|
94
|
+
## Enrollment expiry
|
|
95
|
+
|
|
96
|
+
Claim, companion activation and both endpoint proof validation are bounded by
|
|
97
|
+
the original offer expiresAt, not a renewed proof TTL. Proof issuedAt/expiresAt
|
|
98
|
+
must fall within that offer's interval. A claim made just before expiry cannot
|
|
99
|
+
be activated after expiry. Retry never extends enrollment authority. An already
|
|
100
|
+
completed activation can be read/audited later without re-executing enrollment.
|
|
101
|
+
|
|
102
|
+
## Monotonic minimal receipts
|
|
103
|
+
|
|
104
|
+
Every encrypted operation receipt adds positive integer `revision`, persisted by
|
|
105
|
+
the companion before transmission and monotonically increasing per operation.
|
|
106
|
+
POST receipt also carries matching visible revision; it is not execution proof.
|
|
107
|
+
The cloud rejects a lower revision and conflicting same-revision bytes. The phone
|
|
108
|
+
persists its authenticated revision watermark and rejects older/replayed outcomes.
|
|
109
|
+
Exact duplicate same revision is harmless.
|
|
110
|
+
|
|
111
|
+
Receipt and controlReceipt envelopes use issuedAt=current attestation time and
|
|
112
|
+
expiresAt no later than issuedAt+600000ms, independently of original execution
|
|
113
|
+
TTL. Their serialized envelope maximum is8KiB (normal requests remain128KiB).
|
|
114
|
+
Retention is always anchored to original operation/control expiresAt+24hours;
|
|
115
|
+
fresh reconciliation never renews payload authority or that retention deadline.
|
|
116
|
+
|
|
117
|
+
Receipt/controlReceipt POST is read-only attestation admission, not action
|
|
118
|
+
admission. An immutable sealed receipt may be uploaded for the first time, or
|
|
119
|
+
retried unchanged, after its own header expires while its original operation/
|
|
120
|
+
control record remains inside the original expiry+24h audit window, including
|
|
121
|
+
after pairing revocation. Do not reseal or refresh bytes merely because an upload
|
|
122
|
+
was lost. An expired header alone is not a rejection reason on these two receipt
|
|
123
|
+
POST surfaces. Exact ID/pair/channel/version/field schema,8KiB size, at-most600s
|
|
124
|
+
header interval, future issuedAt skew, original role, operation revision/state
|
|
125
|
+
progression and fixed parent-retention checks remain mandatory. A final
|
|
126
|
+
controlReceipt remains one immutable revision1 result. At or after the original
|
|
127
|
+
retention deadline, an absent/purged parent is unavailable and cannot be recreated
|
|
128
|
+
by a receipt upload. Command/control/enrollment admission and actual action
|
|
129
|
+
dispatch still enforce live authority; historical receipt acceptance never
|
|
130
|
+
executes, renews, restores user ciphertext or extends any retention deadline.
|
|
131
|
+
|
|
132
|
+
A positive official admission fact cannot regress to unknown. For sends, accepted
|
|
133
|
+
means confirmed admission only; task completion is separate attention/state.
|
|
134
|
+
Unknown may become accepted/resolved/rejected only from positive reconciliation.
|
|
135
|
+
Accepted never becomes unknown merely because a later task wait/socket fails.
|
|
136
|
+
Resolved/rejected remain terminal. Permission resolution requires matching
|
|
137
|
+
current-instance authoritative resolution, not a changed pending-set guess.
|
|
138
|
+
|
|
139
|
+
Minimal receipt ciphertext contains only operation/control identity, revision,
|
|
140
|
+
state and bounded error code; no prompt, full request, file or history. Retain it
|
|
141
|
+
24h after the operation/control's original expiry, independently from short-lived
|
|
142
|
+
command ciphertext. The original phone may read and authenticate it after revoke.
|
|
143
|
+
Historical receipt authentication permits read-only audit past its action expiry;
|
|
144
|
+
never dispatch an expired operation because an audit decrypt succeeded. After
|
|
145
|
+
retention expires, report unavailable/unverifiable, never trust a naked cloud
|
|
146
|
+
success state as proof. Keep last positively verified local facts with their
|
|
147
|
+
original timestamps and no renewed authority.
|
|
148
|
+
|
|
149
|
+
## Attention invalidation
|
|
150
|
+
|
|
151
|
+
Add `POST /pairs/{pairId}/attention/{eventId}/resolve`, host bearer, with bounded
|
|
152
|
+
`{resolvedAt}`. It is idempotent and stops queued/retry attempts for the exact
|
|
153
|
+
known attention event. Companion invokes it on matching request resolution,
|
|
154
|
+
replacement or authoritative no-longer-requires-attention facts. Never clear
|
|
155
|
+
real official attention just to acknowledge our relay event.
|
|
156
|
+
|
|
157
|
+
Resolution competes transactionally with retry selection. An APNs request already
|
|
158
|
+
in flight cannot be retracted; old notifications must revalidate binding before
|
|
159
|
+
acting, and may still navigate read-only to the original conversation. Do not
|
|
160
|
+
claim a local resolve API erases a notification already displayed by iOS.
|
|
161
|
+
|
|
162
|
+
## Required regression cases
|
|
163
|
+
|
|
164
|
+
- Lost/withheld revoke reaches cloud but not companion: no endpoint-confirmed UI.
|
|
165
|
+
- Revoke/cancel persisted locally survives restart and blocks later dispatch;
|
|
166
|
+
already-dispatched cancellation is tooLate, not falsely cancelled.
|
|
167
|
+
- Same requestId with changed action/input or a new connection occurrence rejects
|
|
168
|
+
the former requestBinding; genuine same instance maps exact question answers.
|
|
169
|
+
- Claim at offer deadline minus1ms, activation after deadline is rejected at both
|
|
170
|
+
endpoints even if an independently timestamped proof looks fresh.
|
|
171
|
+
- Accepted revision2 followed by unknown revision1 never loses admission proof.
|
|
172
|
+
- APNs transient failure then matching resolution before retry sends no stale retry.
|
|
173
|
+
- Phone returns after message TTL but before minimal-receipt TTL: verifies the
|
|
174
|
+
endpoint-authenticated result, including after revoke; after retention, reports
|
|
175
|
+
explicitly unverifiable outcome instead of trusting cloud state.
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
# 05 — Endpoint and lifecycle behavior
|
|
2
|
+
|
|
3
|
+
## Enrollment QR v1
|
|
4
|
+
|
|
5
|
+
Canonical offer is compact UTF-8 JSON with exactly {version:1,apiOrigin,pairId,enrollmentToken,rootKey,expiresAt}. pairId is a lowercase UUID; token/rootKey are independently random canonical unpadded-base64url32-byte values. The ten-minute original expiry bounds claim, both proofs and activation; a claim just before the deadline does not extend it. Default QR/link is moremote://enhance# plus unpadded-base64url of those exact JSON bytes. --json emits raw JSON. The fragment never reaches an HTTP origin. Consumers reject extras, unsupported versions, expired/noncanonical offers and origin changes; HTTPS except explicit loopback development. The secret QR is explicit output, never diagnostics.
|
|
6
|
+
|
|
7
|
+
The companion persists its root/host/enrollment capabilities before POST pairs, sending only identity, expiry and SHA256 hashes of the canonical bearer UTF-8 text (not decoded bytes). It verifies the pending phoneHello claim/token hash exactly, saves the accepted phone and immutable companionHello proof before activation, and enables actions only after confirmation within the original deadline. The phone independently verifies proof and exact saved daemon identity. Every phone is a separate pairing/key. Cloud credentials cannot satisfy this endpoint proof.
|
|
8
|
+
|
|
9
|
+
## Official compatibility and observation
|
|
10
|
+
|
|
11
|
+
Pin client/protocol0.15.3. createHostClient from client/node and exported internal/daemon-client types are the inspected API. Use clientType cli and a distinct companion clientId. Missing explicitEventSubscriptions fails closed. Subscribe only agent_attention_required, agent_permission_request, agent_permission_resolved, status.server_info with official remote notifications disabled. Never call client_heartbeat, clear_agent_attention, workspace read acknowledgement or register_push_token. Inspected SDK automatic liveness uses bare protocol ping (10s), not visible-user presence. Actual synthetic WebSocket consumers exercise the real adapter/SDK, await that liveness interval, verify wire traffic, then lose send/permission acknowledgements and reconnect without a second mutation.
|
|
12
|
+
|
|
13
|
+
Observation is negotiated by the SDK, not an exact wire-array promise: when the daemon does not advertise ownedSubscriptions, SDK0.15.3's LegacySubscriptions filters status.server_info from its whitelist. Server identity still hydrates from the hello bootstrap before connect resolves. With ownedSubscriptions, the status interest remains on the wire. Real-wire tests exercise both negotiated modes, consume actual identity and attention events, and verify narrow interests, explicit reconnect and no mutation replay instead of equating adapter arguments with transmitted subscriptions.
|
|
14
|
+
|
|
15
|
+
Only selected paseo.pid and local-credential files are read, with bounded I/O and the official CLI’s target normalization/password/local-token precedence. No discovery scan, daemon launch, official writes, heartbeat/read/Expo ownership change or model prompt occurs during read-only checks.
|
|
16
|
+
|
|
17
|
+
## Bounded encrypted state and attention
|
|
18
|
+
|
|
19
|
+
State plaintext is exactly {version:1,daemonServerId,hostName,measuredAt,tasks:[{agentId,title,status,updatedAt,requiresAttention,attentionReason,pendingRequests:[{requestId,requestBinding,request:<complete original official request JSON>}]}],usage,tasksTruncated}. At most100 recent noninternal/nonarchived tasks,10 requests/task,16 provider summaries and8 windows/balances/provider. A raw request over8KiB is omitted from enhanced actions, not silently truncated into another authority. Whole trailing tasks are omitted to keep serialized state under60000bytes; tasksTruncated is explicit. Unavailable usage is null/unavailable, never zero. No full conversation or files are projected. Measurement time survives immutable state retries.
|
|
20
|
+
|
|
21
|
+
Attention plaintext is exactly {agentId,requestId?,requestBinding?,kind,timestamp}. No form or prompt is in the push route. For question/approval actions the app must find the exact matching authenticated raw request and binding in state or open the original form; it cannot paste the same reply into unsupported/multiple questions. Own notification policy uses genuine short viewing leases, never official shouldNotify. Stable semantic attention identity is independent of reconnect-generated authority tokens: reconnect may retire an old action binding without replaying historical attention as a new push. Source change/resolution/current no-longer-requires-attention facts persist exact event invalidation and POST its resolve endpoint, stopping future relay retries without changing official read state. An already in-flight/displayed push cannot be retracted.
|
|
22
|
+
|
|
23
|
+
## Exact request authority
|
|
24
|
+
|
|
25
|
+
The journal retains a canonical full-source fingerprint and random occurrence identity for every observed current request. A connection-generation change, source change, resolution or removal retires it. Binding is base64url HMAC-SHA256 using HKDF-SHA256 with the normal salt and info [1,pairId,"requestBinding"], over compact JSON [1,daemonServerId,agentId,requestId,occurrenceId,fingerprint]. This is companion-created opaque authority; the phone echoes it, never derives an occurrence. Input/action/suggestion source changes or same-ID replacements cannot inherit it.
|
|
26
|
+
|
|
27
|
+
Real upstream kinds are tool|plan|question|mode|other. Enhanced allow/deny requires an actually advertised action with matching behavior. Question codec copies every original input field and adds answers keyed by original question header. It validates choices, ordered multi-choice, allowOther/allowEmpty, completeness and exact preserved noneditable fields. Other edits may change only original string-valued inputs. Remembered grants must match actual current suggestions explicitly chosen by the user. Unknown fields/kinds of operation or an arbitrary new grant are rejected. Expired/stale notifications still navigate read-only, never acquire replacement authority.
|
|
28
|
+
|
|
29
|
+
## Dispatch, controls and receipts
|
|
30
|
+
|
|
31
|
+
Every mutation goes through a FULL-sync SQLite journal, immutable identity/digest and first-only cloud dispatch claim. The local dispatched commit precedes the cloud transition. Lost transition responses or crashes never authorize replay, even with a stable messageId. Actual current request/source/binding and command expiry are rechecked after dispatch, immediately before SDK I/O. SDK automatic reconnect is off; inspected sendAgentMessage/respondToPermissionAndWait use skipQueue:true. Recovery is read-only only.
|
|
32
|
+
|
|
33
|
+
Process authenticated control envelopes before normal command acquisition, even if the official daemon is unavailable. Persist cancel/revoke tombstones before sealing a controlReceipt. Recheck tombstones immediately before official I/O; revoked pairings can never reactivate from a cloud active flag. A dispatched action is tooLate to cancel, not undone. A relay DELETE acknowledgement alone proves no endpoint revocation. A phone receives endpoint-confirmed facts only from its exact authenticated immutable controlReceipt. A crash/retry retransmits the same sealed acknowledgement, never new authority. Keys remain protected for narrow final control/outcome audit; explicit purge can remove them.
|
|
34
|
+
|
|
35
|
+
Operation receipts carry positive monotonically increasing revision and exactly {operationId,state,revision,code?}; states accepted/resolved/rejected/unknown. Accepted is confirmed admission, not task completion/read, and never regresses to unknown because a later wait/receipt upload failed. Permission resolved needs matching current-instance authoritative resolution. Unknown can improve only through positive source evidence. Minimal evidence stores target identities and exact-content/response digests, never the original prompt or full request. It enables bounded canonical timeline/recorded resolution reconciliation after payload expiry/revoke without re-dispatch. Absence from a bounded timeline proves nothing.
|
|
36
|
+
|
|
37
|
+
Receipt/controlReceipt envelopes are at most8KiB. issuedAt is current attestation time, expiresAt at most600000ms later, independent of action TTL. Persist sealed bytes before upload. Retention remains the original operation/control expiry plus24h, never extended by a later receipt. Short-lived command/attention payloads are cleared on running cleanup and before restart recovery; a stopped process cannot run cleanup, but expiry is still enforced before any dispatch. Minimal encrypted receipts remain independently available for historical read-only audit, including after revoke. No public/cloud state substitutes for missing authenticated proof after retention.
|
|
38
|
+
|
|
39
|
+
Revoked-key retirement uses the latest immutable known child deadline: maximum of first revokedAt+24h and each durable operation/control/attention original expiresAt+24h. Authenticated late controls advance this high-watermark durably before acknowledgement/cleanup; unsent sealed acknowledgements remain retransmittable through their own original deadline, never forever or renewed by retry/attestation. Attention payload expiry is unchanged; its retained invalidation metadata has the original attention expiry+24h deadline. Never-observed cloud controls are not endpoint acknowledgements. Remove credentials durably before their expired tombstone; interrupted cleanup must leave revocation protection, not credentials without it.
|
|
40
|
+
|
|
41
|
+
## Portable lifecycle and ownership
|
|
42
|
+
|
|
43
|
+
Foreground run requires no installed service and owns an authenticated local IPC stop/status endpoint. PID locks never authorize signalling another process. Native stop first stops/unloads the owned login registration to avoid restart, then stops foreground transport. POSIX data directory/file modes0700/0600 and a companion ownership marker prevent adopting/purging nonempty foreign directories. Windows uses its user-profile ACL. Never point companion data at official data; a foreign directory is rejected, not overwritten.
|
|
44
|
+
|
|
45
|
+
Explicit service-install/update/uninstall use --yes. macOS LaunchAgent, Linux systemd user unit (XDG_CONFIG_HOME respected), and Windows least-privilege current-user logon task are separate optional platform adapters. Windows ownership probing requires built-in PowerShell; no administrator Windows Service is claimed. Files/registrations bind to the companion data-directory hash; mismatched ownership or unavailable managers fail honestly. Only companion-owned resources are removable. No official service, daemon data, history or credentials are altered.
|
|
46
|
+
|
|
47
|
+
Owned filenames alone are insufficient: reject symlinks, hardlinks, wrong resource types, foreign owner/modes, unmarked control records and foreign SQLite application identity before mutation. A stale socket is removable only through matching owned runtime provenance and inode identity. Service-path symlinks are rejected before no-follow/exclusive replacement. Manager inspection still runs when the registration file is absent; unavailable/ambiguous manager state is unknown, never a successful stopped/absent claim.
|
|
48
|
+
|
|
49
|
+
Cloud-disable durably stops local execution and attempts relay revocation, reporting unreachable relay revocation separately. Per-phone unpair affects only that pairing. Protected keys/journal are retained for final audit and no old pairing is automatically reused. Uninstall retains keys/journal unless --purge explicitly deletes companion state; neither operation undoes official actions or removes unreachable cloud data.
|
|
50
|
+
|
|
51
|
+
Managed update selection and retained-supervisor activation are specified in [06](06-managed-updates.md). Exact `@moxuli/moremote` installs use immutable verified private prefixes, no lifecycle scripts, persisted six-hour checks/opt-out, declared storage/wire compatibility and full-cycle drain before automatic activation. A failed update retains and actually restarts the last-known-good runtime. No global package, Node or official daemon update. Recovery never dispatches prepared records or manufactures execution receipts; request/occurrence authority and original audit deadlines survive restart unchanged.
|
|
52
|
+
|
|
53
|
+
Request attention carries the same internal occurrence witness across binding/envelope/topic cryptography. Check that witness synchronously before durable queue insertion, so resolution during an await cannot insert a new unresolved stale notification after the original invalidation.
|
|
54
|
+
|
|
55
|
+
## Contract provenance and evidence
|
|
56
|
+
|
|
57
|
+
02/03/04 are independently carried version1 contract copies dated2026-11-10; runtime imports never cross repository boundaries. vectors/envelope-v1.json was generated independently with Node hkdfSync/createCipheriv; implementation uses WebCrypto HKDF/AES-GCM. vectors/bearer-v1.json fixes bearer hash framing. Tests cover actual CLI, wire liveness/subscriptions/no-presence, send/current question/permission and lost acknowledgements, crypto/timing, control/dispatch crashes, source occurrence, revocation, monotonic receipts and retention. They are acceptance instructions, not a claim this worker ran them. See STATE for frozen checks and real external gates.
|