@moxuli/moremote 0.1.2 → 0.1.5

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.
Files changed (41) hide show
  1. package/README.md +69 -50
  2. package/bin/moremote-cli.js +11 -4
  3. package/dist/cli.js +33 -7
  4. package/dist/cloud-client.d.ts +2 -9
  5. package/dist/cloud-client.js +3 -8
  6. package/dist/config.d.ts +7 -0
  7. package/dist/config.js +23 -4
  8. package/dist/enrollment-files.d.ts +37 -0
  9. package/dist/enrollment-files.js +225 -0
  10. package/dist/enrollment-protocol.d.ts +50 -0
  11. package/dist/enrollment-protocol.js +44 -0
  12. package/dist/local-enrollment.d.ts +25 -0
  13. package/dist/local-enrollment.js +160 -0
  14. package/dist/notification-state.d.ts +10 -0
  15. package/dist/notification-state.js +36 -0
  16. package/dist/official-client.d.ts +25 -65
  17. package/dist/official-client.js +83 -35
  18. package/dist/operations.d.ts +1 -0
  19. package/dist/operations.js +24 -4
  20. package/dist/projection.d.ts +3 -15
  21. package/dist/projection.js +11 -21
  22. package/dist/resources.d.ts +2 -1
  23. package/dist/resources.js +67 -31
  24. package/dist/runtime.d.ts +10 -1
  25. package/dist/runtime.js +81 -59
  26. package/dist/setup-upgrade.d.ts +2 -0
  27. package/dist/setup-upgrade.js +65 -0
  28. package/dist/setup.d.ts +12 -0
  29. package/dist/setup.js +38 -0
  30. package/docs/STATE.md +197 -13
  31. package/docs/configuration.md +70 -49
  32. package/docs/native-enrollment-acceptance.md +21 -0
  33. package/docs/specs/01-architecture.md +14 -1
  34. package/docs/specs/02-encrypted-delivery.md +4 -4
  35. package/docs/specs/03-api-contract.md +18 -123
  36. package/docs/specs/04-control-and-receipt-lifecycle.md +12 -0
  37. package/docs/specs/05-endpoint-and-lifecycle.md +126 -2
  38. package/docs/specs/06-managed-updates.md +25 -0
  39. package/package.json +29 -6
  40. package/dist/activity.d.ts +0 -77
  41. package/dist/activity.js +0 -193
@@ -8,6 +8,66 @@ Each pairing retains its explicit API origin through retirement. Local revokedAt
8
8
 
9
9
  MOREMOTE_CLI_HOME or --data-dir overrides platform state defaults: ~/Library/Application Support/MoRemoteCLI on macOS, LOCALAPPDATA/MoRemoteCLI on Windows, XDG_STATE_HOME/moremote-cli (fallback ~/.local/state/moremote-cli) on Linux. PASEO_HOME selects the official read-only home, PASEO_PASSWORD matches official CLI password precedence. Only paseo.pid and local-credential are read under the official home, only at an explicit connection. No credential discovery scans or official writes. The unpublished former moremote-companion identity has no command/env aliases or automatic state adoption.
10
10
 
11
+ Unreleased single-pairing onboarding uses explicit `setup --yes`: stop only the
12
+ owned CLI runtime/service, reload its latest configuration, authenticate the
13
+ existing official daemon and preserve its exact identity, then enable cloud and
14
+ local enrollment before installing/starting the existing owned service.
15
+ Configured custom HTTPS origin/target, existing active/revoked phones and update
16
+ policy are preserved. An absent origin selects
17
+ `https://moremote-cloud-ingress.pages.dev`. Source checkout without managed state
18
+ binds its own current frontend and stays manual-update. Installed packages and
19
+ retained managed state use capability-aware setup: if selected code predates
20
+ enrollment, explicit setup installs/verifies the exact current version before
21
+ enabling the feature, then moves active/bootstrap while retaining previous
22
+ packages, pairs/custom origin and the independent auto-update opt-out.
23
+ `SETUP_CURRENT_PACKAGE_UNAVAILABLE`/`SETUP_CAPABILITY_REQUIRED` are failures,
24
+ never enabled success or an older-package fallback. Nothing patches/upgrades
25
+ official Paseo or global tools. This capability requires CLI0.1.4 or later.
26
+
27
+ Optional schema-1 fields are `localEnrollment:{home:<absolute user home>}` and
28
+ at most16 `enrollmentRequests`. Only explicit setup supplies that home; ordinary
29
+ `run`/tests with legacy configuration never create discovery in the real HOME.
30
+ Each durable record stores the exact request bytes, SHA256 fingerprint, parsed
31
+ request, original pair/offer, exact cloud-create JSON bytes and confirmed-create
32
+ flag. Per-pair `automaticClientId` and `automaticRequestId` retain app/request
33
+ identity without replacing an old pair. Runtime-cycle ownership serializes all enrollment/config changes;
34
+ there is no second config writer or background watcher.
35
+
36
+ Config reads, owned-resource validation and atomic writes share a524288-byte
37
+ bound, including the serialized trailing newline. This accommodates16 maximum
38
+ 4096-byte requests even when literal tab/newline bytes expand during JSON
39
+ serialization. Oversize writes fail before replacing any config. Fresh `run`
40
+ initializes config only after acquiring runtime ownership; duplicate `run`
41
+ refuses without rewriting a live enrollment snapshot.
42
+
43
+ The private tree is `<home>/.moremote-cli-connect/<sha256(UTF8 daemonServerId)>/`;
44
+ its parent/host/request/response directories have owned markers and POSIX0700.
45
+ Descriptor and secret responses are0600; official-created requests may be0644
46
+ inside the private request directory. Reject links, foreign markers/owners,
47
+ collisions and competing runtime locks before cloud creation. Windows relies on
48
+ the user-profile ACL. Only this owned local tree is written, not official files.
49
+ The app gets the real home via official directory suggestions, never a guessed
50
+ path. Descriptor includes the configured/default validated HTTPS `apiOrigin`,
51
+ which pins the original canonical offer's origin.
52
+
53
+ Unchanged request bytes resume the same endpoint and idempotent create bytes
54
+ through lost acknowledgements/restarts; changed bytes/client/daemon/expiry fail
55
+ closed. No more than16 request files are consumed per cycle and no more than16
56
+ pairs exist. At most one optional cloud-create attempt runs per cycle with its
57
+ own3s abort deadline; existing phones retain ordinary controls/command handling.
58
+ Descriptor lifetime90s/renewal30s; request/offer lifetime at most600s.
59
+ Activation/expiry removes private responses, expiry removes durable request
60
+ records. An old exact request remains disabled after revocation; only the app's
61
+ explicit fresh Enable request may create a new endpoint after prior retirement.
62
+ Full schemas and ownership behavior:
63
+ [single-pairing contract](specs/05-endpoint-and-lifecycle.md#single-pairing-local-enrollment-v1-unreleased).
64
+
65
+ Loading config, `check` and `status` do not create discovery, enable cloud,
66
+ select an origin, enroll or install a service; `check --connect` is read-only.
67
+ Manual `pair` remains expert-only and installs no service. Published0.1.2 lacks
68
+ `setup` and still requires explicit origin/cloud configuration before manual
69
+ pairing; this source delta is not published.
70
+
11
71
  ## Central limits (src/limits.ts)
12
72
 
13
73
  Envelope request128KiB; decrypted content64KiB; send text60000 UTF-8 bytes; command/control TTL300s; enrollment/state/attention maximum600s; receipt/controlReceipt maximum8KiB serialized envelope with600s attestation interval; future clock tolerance120s (never expiry grace). User payloads expire at original TTL, minimal encrypted receipts/evidence remain24h after original operation/control expiry. Receipt revision is persisted before I/O; control ack revision1 is immutable. At most1000 operations,1000 controls and1000 attention records per pairing,100 tasks/snapshot,10 pending requests/task,16 providers,8 windows/balances/provider. Raw enhanced request limit8KiB; whole state limit60000bytes. State refresh30s, polling3s backing off to30s, HTTP timeout20s, official connection/read15s, SDK mutation timeout per pinned upstream. Capacity errors never silently evict live authority.
@@ -32,55 +92,16 @@ snapshots/receipt revisions are not retransmitted each poll. Relay disappearance
32
92
  or retirement fences execution but is not authenticated endpoint revocation.
33
93
  Retired recovery ends at original child audit deadlines without extending them.
34
94
 
35
- ## Optional activity and widget surfaces (unreleased)
36
-
37
- Published `@moxuli/moremote` remains0.1.1; these are local source changes,
38
- not a new release or a reason to alter service/runtime identities. There is no
39
- new CLI enable flag or separate activity-device command. Existing cloud opt-in,
40
- active pairing and a compatible phone/relay are prerequisites; official-only
41
- use remains independent. No deployment or device acceptance is implied.
42
-
43
- | Surface | Bound / behavior |
44
- | --- | --- |
45
- | Activity interests | Phone-selected, encrypted and pinned to pair/subscription/daemon/task; at most8 live interests per pair, original lifetime at most8h. |
46
- | Optional host work | Interest discovery no faster than30s; one owned2s cancellation-bounded lane, at most8 exact SDK fallback reads, each bounded250ms. Commands/controls do not await it; drain/stop cancels and joins before closing SDK/journal. |
47
- | Activity state | At most600s, capped by interest expiry; serialized encrypted envelope at most3000bytes, title160/hostName80 characters. APNs body at most4096bytes with512bytes reserved for static attributes. |
48
- | Activity renewal | Only acknowledged nonterminal state renews from a fresh official measurement with120s remaining (about8min). Unknown admissions retry identical bytes until expiry; semantic transitions can supersede progress. Missing tasks do not imply completion. |
49
- | Widget registration | One current WidgetKit token per pair;24h expiry, native foreground renewal around12h with a fresh registration ID. Not the alert/activity token. |
50
- | Widget reload | Pair-keyed meaningful-change fingerprint on existing state PUT; clocks alone do not trigger reloads. One coalesced signal per changed fingerprint/current registration; legacy envelope-only uploads do not queue pushes. |
51
-
52
- The phone registers/deletes tokens and encrypted interests; the CLI never
53
- registers an official daemon push token or downloads full chat/timeline for
54
- these surfaces. The relay sees token/environment, IDs, opaque topic/fingerprint,
55
- envelope times/sizes and ciphertext. Only paired endpoints decrypt task/title,
56
- host/project and genuine usage values. Apple receives encrypted activity state
57
- in `ContentState.payload`, or exactly `{aps:{"content-changed":true}}` for widgets.
58
- Activity/widget pushes do not depend on alert admission or presence suppression.
59
-
60
- Terminal recovery uses cached authenticated unexpired interests and fresh
61
- snapshot facts before optional normal discovery; it needs no normal GET/state
62
- upload. Only end/delete routes are recovery-eligible, not ordinary updates,
63
- interest reads or registration. A404/409 publication rejection invalidates that
64
- cached target; it does not authorize a replacement or a blind replay. Conflicting
65
- same-registration bytes are409; replacement needs a fresh registration ID.
66
- Relay retired-identity guards share a1000-entry cap and fail closed rather than
67
- evicting live protection; guards last through original8h activity/24h widget
68
- expiry. Delayed registration PUTs cannot roll back replacements; identity-exact
69
- widget DELETEs and stale provider results cannot retire newer registrations.
70
- Activity DELETE targets the subscription itself. Expiry never renews through
71
- retry; stale/offline is not success.
72
-
73
- The relay needs explicit `APNS_WIDGET_TOPIC` for the widget extension plus
74
- `.push-type.widgets`; Live Activity topic is main `APNS_TOPIC` plus
75
- `.push-type.liveactivity`. Environments must match configured APNs sending.
76
- These are relay settings, not CLI configuration keys. Default-off, global
77
- budgets, kill deadline and existing receipt priority remain unchanged.
78
- Provider signing is inside the original10s attempt deadline; after signing,
79
- the durable caller rechecks enabled state, active pair, exact current
80
- registration/publication and expiry immediately before transport.
81
- APNs200 is provider admission, never display/delivery proof. Physical Live
82
- Activity, widget reload/freshness/offline behavior and live cloud/APNs acceptance
83
- for this delta remain pending. Exact routes/crypto: [[specs/03-api-contract]].
95
+ ## Notification-only cloud use
96
+
97
+ Cloud opt-in owns native notifications, replies and approvals only. Pending forms
98
+ are encrypted with exact request-instance bindings; no titles, usage or general
99
+ task directory leave through `/state`. Current empty state is cleared once and
100
+ is not renewed. Nonempty hydration renews with120seconds remaining of600seconds.
101
+ Unknown publication retries retain their original envelope until expiry; this
102
+ never grants authority to replay an uncertain user action. WidgetKit, ActivityKit
103
+ and ordinary app/extension sends are independent official Paseo clients. No
104
+ activity/widget provider registration or discovery command remains.
84
105
 
85
106
  ## Service resources
86
107
 
@@ -0,0 +1,21 @@
1
+ # Native enrollment and request delivery acceptance
2
+
3
+ Date: 2026-11-13. Scope: unpublished source candidate with an unmodified official Paseo0.15.4 development daemon and its built-in mock provider, an isolated computer home, production cloud transport and a physical iPad. No paid model or ordinary user conversation was exercised.
4
+
5
+ ## Observed results
6
+
7
+ - The native app retains its existing official host connection. An installed companion exchanges the per-phone offer over official authenticated file APIs and activates the production endpoint without another QR code or pasted invitation. An explicitly disabled previous endpoint still requires deliberate re-enablement; disabled history is not silently overwritten.
8
+ - A pending endpoint initially receives409 from active-only control routes. Runtime must validate official identity and original enrollment authority, activate in an activation-only cycle, and acquire fresh controls on the next cycle before commands or state publication. The production continuation activates the original pending offer after this correction.
9
+ - Official request snapshots can retain an older completion attention timestamp/reason while containing a new pending approval. Request notification authority therefore uses the persisted current occurrence, independently of that global completion hint. Unchanged occurrences retain their original clock and immutable notification bytes; resolution/replacement must not renew old authority.
10
+ - A real production permission notification opens the exact native request-review surface. Approve and deny are exercised on two distinct, still-pending official mock requests. Each produces one official resolution, no remaining pending request, and a resolved companion operation with revision1 acknowledged to cloud. Notification invalidation is acknowledged once for each occurrence.
11
+ - Production task tracking creates a subscription; a genuine terminal APNs activity update renders on the iPad and opens the exact task. Foreground terminal cleanup removes the subscription.
12
+
13
+ ## Focused local proof
14
+
15
+ The stricter pending-endpoint fixture reproduces the activation deadlock before repair. The focused enrollment selection passes22 tests; the existing runtime quota-pause consumer also passes with the controls-first fence. Three real SDK request-notification wire consumers reproduce stale completion hints, absent attention flags and stale permission clocks. The final selected notification/attention/official-wire set passes14 tests, typecheck and build. These are scoped results, not a claim that all later concurrent release-candidate changes were checked here.
16
+
17
+ ## Deliberately incomplete claims
18
+
19
+ An unlocked Notification Center text reply is submitted once, but native status remains unknown and no corresponding companion execution is observed. It is not replayed or reported as delivered. A hardware lock command has no conclusive lock-state evidence; this is not locked-reply acceptance. Full foreground/background/terminated delivery, cancellation, ActivityKit token rotation, widget remote token lifecycle, Siri, physical Action Button and interrupted file-share coverage remain separate gates. The test iPad has no physical Action Button.
20
+
21
+ Keep real task/host identifiers, endpoint tokens, device exports and raw receipts outside this public repository. Production deployment and cost limits are unchanged. No npm, TestFlight or cloud release is established by this document.
@@ -37,7 +37,7 @@ per-user operation.
37
37
 
38
38
  ## Components
39
39
 
40
- - **Official adapter:** authenticated local daemon connection, bounded snapshot
40
+ - **Official adapter:** authenticated local daemon connection, bounded local notification discovery
41
41
  and authoritative event subscriptions; no fake user focus/read acknowledgements.
42
42
  - **Attention projection:** completion, pending question/approval and supported
43
43
  errors from typed evidence; no prose classifiers or fabricated progress/usage.
@@ -100,3 +100,16 @@ background-service installer on another OS. No package publication, public Git
100
100
  repository, automatic installer execution or production service registration is
101
101
  implied by implementation approval. The owner selected Apache-2.0; public
102
102
  publication remains separately authorized.
103
+
104
+ ## Notification-only cloud boundary — November 14
105
+
106
+ The optional companion publishes only current question/approval forms and their
107
+ exact occurrence bindings. It does not request provider usage or upload task
108
+ titles, host/project labels or a conversation directory. Accepted source reads
109
+ retain pending requests outside the bounded recent discovery page; stale reads
110
+ and resolved/replaced occurrences cannot restore them. Publication changes are
111
+ deduplicated; only pending hydration renews near expiry, and one empty publication
112
+ clears the last resolved request. Unknown acknowledgements retain immutable bytes.
113
+ No activity interests, WidgetKit registrations or dedicated surface APNs calls
114
+ remain. Notification control, explicit reply/approval execution, immutable action
115
+ journals and outcome reconciliation retain their original safeguards.
@@ -150,10 +150,10 @@ survive payload TTL for24hours after original expiry, including after revoke.
150
150
  Historical decoding is read-only and cannot extend command authority. After
151
151
  retention, the outcome is unavailable/unverifiable, not a cloud-only success.
152
152
 
153
- State snapshots are encrypted, size-bounded and timestamped. They contain useful
154
- current task/attention/real available-usage summaries, not the full conversation.
155
- The phone can preserve a stale snapshot with its original timestamp, never show
156
- it as a freshly measured host state. State is display-only, not an operation
153
+ State is encrypted, size-bounded notification hydration: verified daemon identity
154
+ and exact current request forms/bindings only. Directory, titles and usage are
155
+ excluded. A stale form is never execution authority; the host must validate the
156
+ current occurrence again before an explicit notification response. State is display-only, not an operation
157
157
  outcome audit: only the latest nonexpired snapshot keeps ciphertext, while each
158
158
  immutable state ID/digest survives supersession only through that envelope's
159
159
  original expiry. Exact retries do not renew it; expired snapshots cannot be newly
@@ -103,9 +103,7 @@ without contacting cloud.
103
103
 
104
104
  ### PUT /pairs/{pairId}/state; GET /pairs/{pairId}/state
105
105
 
106
- Host writes, phone reads. PUT accepts strict `{envelope}` or additive
107
- `{envelope,widgetFingerprint}`; GET returns the envelope only, as specified below.
108
- Envelope channel is `state`.
106
+ Host writes, phone reads. Body/response contains exactly `{envelope}` with the `state` channel.
109
107
  Only the latest nonexpired snapshot keeps ciphertext, monotonic by issuedAt then
110
108
  immutable ID. Each state ID/digest remains a conflict guard through its own
111
109
  original envelope expiry, including after supersession; no additional24hour
@@ -114,9 +112,14 @@ conflicting IDs/older snapshots never replace newer state. After expiry, a retry
114
112
  cannot be admitted as new live state. Supersession clears only the previous
115
113
  payload-bearing state, never rewrites older null tombstones. Operation, control,
116
114
  attention and minimal authenticated outcome retention is unchanged.
117
- Encrypted state is a versioned object with verified daemon
118
- identity, host name, measured timestamp and bounded actual tasks/available usage.
119
- No complete chat, code files or credentials.
115
+ Encrypted state is limited to `{version:1,daemonServerId,tasks}`. Each task
116
+ contains only `{agentId,pendingRequests}`; each pending request retains its exact
117
+ `requestId`, occurrence-bound `requestBinding` and original supported request.
118
+ This hydrates notification replies and approvals only. It contains no conversation
119
+ titles, directory, host labels, timestamps or usage report. Empty tasks are omitted.
120
+ Writers publish semantic changes, clear resolved requests once, and renew only
121
+ still-pending hydration near its original expiry. Immutable unknown retries keep
122
+ the same ID and bytes. Current-source validation remains mandatory at execution.
120
123
 
121
124
  ### PUT /pairs/{pairId}/device
122
125
 
@@ -398,120 +401,12 @@ host pairing response may contain two bounded proofs. A128KiB response reader
398
401
  would permanently reject valid work and is nonconforming. This larger response
399
402
  budget never raises the128KiB request or64KiB decrypted command-content limits.
400
403
 
401
- ## Opt-in task activities and widget reloads
402
-
403
- These additive routes do not change command, receipt, alert, pairing, service,
404
- or managed-update identities. Cloud remains disabled by default. Every route
405
- uses the existing pair bearer; subscription IDs and registration IDs are
406
- lowercase canonical UUIDs. No pair-level activity-device registration exists.
407
-
408
- | Route (under `/v1/pairs/{pairId}`) | Role | Exact JSON body | Admission |
409
- | --- | --- | --- | --- |
410
- | `PUT /activities/{subscriptionId}` | phone | `{registrationId,token,environment,topic,interest}` | normal |
411
- | `DELETE /activities/{subscriptionId}` | phone | none | recovery |
412
- | `GET /activities` | host | none | normal |
413
- | `PUT /activities/{subscriptionId}/state` | host | `{registrationId,topic,event:"update",envelope}` | normal |
414
- | `PUT /activities/{subscriptionId}/end` | host | `{registrationId,topic,event:"end",envelope}` | recovery |
415
- | `PUT /widget-device` | phone | `{registrationId,token,environment}` | normal |
416
- | `DELETE /widget-device/{registrationId}` | phone | none | recovery |
417
-
418
- Tokens are even-length hex,1–256 bytes, normalized lowercase. Environment is
419
- `sandbox|production`; provider configuration must match. The activity `topic`
420
- is the existing pair-key HMAC `presenceTopic(rootKey,pairId,agentId)` (32 bytes,
421
- base64url), not an APNs topic or plaintext agent identity. At most8 live
422
- subscriptions are admitted per pair. GET returns
423
- `{ok:true,subscriptions:[{id,registrationId,topic,interest,expiresAt}]}`.
424
- PUT registration returns the same single row as `{ok:true,subscription:...}`.
425
- Registration replacement uses a fresh registrationId; different bytes under
426
- the same registrationId conflict. Native renewal must preserve the ActivityKit
427
- activity's original8-hour ceiling. DELETE removes queued state immediately.
428
- Retired subscription/registration IDs share a bounded1000-entry token-free guard
429
- pool with widget registrations. Delayed registration PUTs cannot resurrect or
430
- roll back retired identities. Widget DELETE is registration-exact; activity DELETE targets the subscription.
431
- Activity guards retain the original8h ceiling and widget guards the original24h
432
- expiry, without retry extension. Unknown DELETEs also reserve bounded guards;
433
- capacity exhaustion fails closed, never evicts live protection.
434
-
435
- The encrypted `interest` uses additive channel `activityInterest`, envelope.id
436
- equal to subscriptionId, lifetime at most8h. Exact plaintext:
437
- `{version:1,subscriptionId,daemonServerId,agentId}`. The companion authenticates
438
- the envelope, pinned daemon, exact subscription and derived topic before any
439
- read-only task lookup. This plaintext cannot authorize commands. No timeline
440
- or chat download is required. Existing snapshot cadence (at least30s) admits
441
- one bounded interest pass, at most8 exact fallback reads outside the recent list.
442
- The owned optional lane has a2s deadline,250ms SDK reads and request cancellation.
443
- Commands/control never await it; drain aborts/joins before SDK/journal close. Missing tasks never imply finish.
444
-
445
- Activity state uses additive channel `activityState`, fresh envelope UUID and
446
- at most600s lifetime, capped by subscription expiry. Exact plaintext:
447
- `{version:1,subscriptionId,daemonServerId,agentId,title,hostName,phase,startedAt,measuredAt,expiresAt,requiresAttention,isTerminal}`.
448
- Title/hostName are limited to160/80 characters. Phase is
449
- `running|waiting|finished|error|idle`; permission attention maps to waiting;
450
- official closed/error or current terminal attention maps to end. A running
451
- turn supersedes an old terminal attention flag. startedAt is nullable, from
452
- official activeTurn.startedAt or lastUserMessageAt, never a measurement
453
- substitute. measuredAt/expiresAt exactly match envelope headers in milliseconds.
454
- Existing encrypted snapshots also include optional lastUserMessageAt,
455
- activeTurnStartedAt and bounded cwd per task. Encrypted usage adds genuine
456
- provider displayName and window/balance label (at most128 characters each),
457
- preserving absent values as unavailable. No full chats, invented labels or
458
- synthetic percentages are added.
459
-
460
- HKDF salt, AES-GCM nonce/tag framing, metadata AAD and existing channels remain
461
- byte-compatible. Only the new channel name changes HKDF info. Activity state
462
- serialized envelope is at most3000 UTF-8 bytes. Native ContentState has default
463
- Codable field `payload`, a canonical JSON string of that envelope (key order
464
- version,pairId,id,channel,issuedAt,expiresAt,nonce,ciphertext).
465
- Updates derive directly from real semantic task transitions, independently of
466
- alert admission/presence suppression. Unchanged measurements normally do not push.
467
- Acknowledged nonterminal state renews from fresh samples every8minutes (120s before600s expiry).
468
- Unknown admissions retain identical ciphertext until expiry; semantic changes can supersede progress. Disconnected state expires.
469
-
470
- Live authenticated interests are cached against the current pair key/daemon. Terminal work precedes optional normal discovery, once per fresh
471
- snapshot, without GET/state admission; authenticated404/409 invalidates its cache.
472
- Only exact429 `daily_work_limit`, `x-moremote-budget:normal` and consistent future
473
- `x-moremote-reset`/Retry-After pauses normal work alone. Missing/malformed hints,
474
- outages, disable or recovery exhaustion preserve origin-wide pause/cycle fences.
475
- Recovery still requires server admission; hints never grant operation authority.
476
-
477
- APNs uses `apns-push-type:liveactivity`, configured main topic plus
478
- `.push-type.liveactivity`, priority5 update/10 end, collapse-id subscriptionId,
479
- apns-id envelope.id, expiration floor(expiresAt/1000). Body is
480
- `{aps:{timestamp,event,"content-state":{payload},"stale-date"}}`; all APNs dates
481
- are epoch seconds. End additionally sets dismissal-date. There is no apns-event
482
- header. A512-byte static-attributes reserve and the complete4096-byte provider
483
- payload limit both apply. End and invalid-token retirement compare the exact
484
- current registration identity; stale provider failures never remove replacement
485
- tokens. Provider admission is not proof of rendering.
486
-
487
- Existing `PUT /state` accepts strict legacy `{envelope}` or additive
488
- `{envelope,widgetFingerprint}`. GET state remains unchanged. The new fingerprint
489
- is a pair-keyed HMAC using the presence domain over JSON
490
- `["widgetSnapshot",meaningfulProjection]`. Projection includes bounded sorted
491
- task identity/title/status/attention/latest turn/project plus usage values;
492
- measurement and usage fetchedAt clocks are excluded. Only a changed opaque
493
- fingerprint for the current widget registration queues a coalesced push.
494
- Legacy envelope-only publications do not cause widget pushes.
495
-
496
- Widget registration expires after24h and requires foreground/token renewal
497
- (native renewal around12h uses a fresh registration ID).
498
- Native uses the WidgetKit token, not an alert or activity token. Explicit
499
- `APNS_WIDGET_TOPIC` is the widget extension bundle ID plus `.push-type.widgets`;
500
- it is never derived from the main app topic. APNs uses push-type widgets,
501
- priority5 and `{aps:{"content-changed":true}}`, no private identifiers.
502
- WidgetKit automatically reloads timelines opportunistically on receipt;
503
- WidgetPushHandler observes token/configuration updates. Timeline providers use
504
- the existing sealed snapshot and its expiry; reload is not realtime delivery.
505
- See Apple's [WidgetKit push documentation](https://developer.apple.com/documentation/widgetkit/updating-widgets-with-widgetkit-push-notifications).
506
-
507
- Activity/widget work shares bounded provider attempts and background batches
508
- with alerts; no recursive requests, unbounded retries, recovery-budget borrowing
509
- for progress or changes to endpoint retirement/receipt/updater lifecycle.
510
-
511
- Every APNs sender requires a synchronous `BeforeSend = () => boolean` fence
512
- after asynchronous JWT signing and immediately before transport. The durable
513
- caller rechecks service enabled, active pair, exact current registration and
514
- publication, and expiry. Signing shares the original10s attempt deadline;
515
- late signing cannot start transport. Global budgets and kill deadline are unchanged.
516
- Physical Live Activity/widget behavior and live APNs/cloud delivery for this
517
- delta remain pending; provider200 never establishes device delivery.
404
+ ### Retired system-surface routes
405
+
406
+ Authenticated `/pairs/{pairId}/activities` and descendants, and
407
+ `/pairs/{pairId}/widget-device` and descendants, return `410 surface_removed`.
408
+ No registrations, tokens, interests, states, replay guards or provider queues for
409
+ these features remain. Durable Object initialization purges legacy surface rows;
410
+ notification device, attention, operation and control records remain intact.
411
+ Widgets and local ActivityKit read/update through the official Paseo path and
412
+ shared device state, independently of this notification service.
@@ -69,6 +69,18 @@ read-only but cannot approve a replacement. Before dispatch, refresh the actual
69
69
  pending request, match its binding/source and validate the selected actual action.
70
70
  Do not depend on requestId never being reused.
71
71
 
72
+ Request notifications use the exact current occurrence's first-observed clock,
73
+ independent of a task's older completion or global attention timestamp. Keep that
74
+ clock stable across repeated observations. A request/resolution event or a newer
75
+ accepted observation fences older in-flight reads of that agent before journal
76
+ synchronization or notification; delayed responses cannot recreate a retired
77
+ occurrence, replace newer authority or supply a fresh notification clock.
78
+ The official adapter owns synchronization into its exact journal; binding callers
79
+ do not observe the returned request array again. They match its generation/source
80
+ fingerprint and recheck currentness after binding. Queued internal request events
81
+ capture their occurrence when observed, so delayed draining cannot attach an old
82
+ event's clock to a replacement occurrence or consume its notification identity.
83
+
72
84
  Reject response fields outside the real upstream response shape. Any remembered
73
85
  permissions must be an actual offered suggestion explicitly selected by the user;
74
86
  never accept an arbitrary new grant or silently set remember. Edited input is
@@ -1,11 +1,135 @@
1
1
  # 05 — Endpoint and lifecycle behavior
2
2
 
3
- ## Enrollment QR v1
3
+ ## Single-pairing local enrollment v1 — unreleased
4
+
5
+ Normal users pair only official Paseo. Explicit `setup --yes` authenticates the
6
+ existing official daemon, enables automatic enrollment/cloud and installs/starts
7
+ only the existing owned CLI per-user service. Stop/reload only owned CLI state;
8
+ preserve custom origin/target, active/revoked pairs and update preference. An
9
+ absent API origin selects the built-in production HTTPS endpoint. Source checkout
10
+ without managed state binds its current frontend and manual-update policy;
11
+ installed packages/retained managed state use capability-aware exact-current
12
+ setup migration before enabling enrollment, retaining prior packages and update
13
+ opt-out while selecting an enrollment-capable active/bootstrap. Unavailable or
14
+ incapable current packages fail explicitly without cloud opt-in. Manifest
15
+ `localEnrollment:1` and `configBytes:524288` declare that capability.
16
+ `check`, `status` and config reads remain passive. Manual `pair` is expert-only.
17
+ No official modifications, new listener, hidden terminal/workspace, model prompt,
18
+ new relay, global upgrade or package publication is part of this protocol.
19
+
20
+ Discovery tree:
21
+
22
+ ```text
23
+ <home>/.moremote-cli-connect/<sha256(UTF8 daemonServerId)>/
24
+ descriptor.json
25
+ requests/<request UUID>.json
26
+ responses/<request UUID>.json
27
+ ```
28
+
29
+ Parent, daemon and request/response directories carry owned markers and are
30
+ ordinary owned POSIX0700 directories. Descriptor/responses are0600. Requests
31
+ created by the official file API may be0644 inside their private parent.
32
+ Windows relies on the user profile ACL. Reject symlinks, hardlinks, foreign
33
+ markers/users/types, response collisions and competing runtime ownership.
34
+ One marked daemon directory binds to the exact CLI state directory. Its own
35
+ exclusive PID/instance lock can be reclaimed only after the recorded process
36
+ is dead; this lock never authorizes signalling another process. No new socket
37
+ is created. Existing runtime ownership serializes config/cycle work.
38
+
39
+ The app obtains the actual home through official `directory_suggestions_request`
40
+ with query `~/././.`, preserving Windows path joining. A <=4096-byte descriptor is
41
+ exactly:
42
+
43
+ ```text
44
+ {version:1,daemonServerId,instanceId,apiOrigin,enabled,measuredAt,expiresAt}
45
+ ```
46
+
47
+ `instanceId` is a lowercase UUID. Times are safe integer Unix milliseconds.
48
+ `apiOrigin` is the configured/default validated canonical HTTPS origin, pinned
49
+ over the already authenticated official file channel. Descriptor lifetime is90s,
50
+ renewed no faster than30s; disablement can remove resources or publish disabled
51
+ without granting a new enabled lease. This is not a cloud heartbeat.
52
+
53
+ After validating the original authenticated host/session/generation and fresh
54
+ descriptor, the app durably retains one exact immutable UTF-8 request before
55
+ official create/read-revision/write. Empty files are unfinished creates, not
56
+ admissions. Unknown outcomes read the same exact path and never mint another
57
+ request identity. Request <=4096bytes:
58
+
59
+ ```text
60
+ {version:1,id,clientId,daemonServerId,issuedAt,expiresAt}
61
+ ```
62
+
63
+ IDs/client IDs are lowercase UUIDs; lifetime is at most600000ms, with no future
64
+ issuance or expiry grace. At most16 files are consumed per cycle with a rotating
65
+ cursor, and the existing16-pair ceiling remains. A durable record saves exact
66
+ bytes/fingerprint, original pair/canonical offer and exact cloud-create JSON
67
+ before I/O. Lost creation acknowledgements retry those identical bytes through
68
+ the unchanged relay's exact-offer-digest idempotency. A confirmed creation is
69
+ saved before any secret response. Changed bytes/client/daemon/expiry cannot
70
+ replace authority. A client with a current live endpoint cannot manufacture
71
+ another by changing its request ID. Old exact revoked/retired requests remain
72
+ disabled; an explicit fresh app Enable request can create a new independent
73
+ endpoint after retirement. Existing pairs are never reused or revived.
74
+
75
+ At most one cloud-create attempt runs per serialized cycle, independently aborted
76
+ after3s; no optional admission may accumulate sixteen20s cloud waits ahead of an
77
+ existing phone's commands. Requests retain original authority across that abort.
78
+
79
+ Response <=8192bytes:
80
+
81
+ ```text
82
+ {version:1,id,clientId,daemonServerId,expiresAt,status,offer?,code?}
83
+ ```
84
+
85
+ Status vocabulary is `pending|offer|active|disabled|error`. Only `offer` carries
86
+ the original canonical version1 offer defined below. Its origin must exactly
87
+ match the authenticated descriptor pin. Response expiry never exceeds either
88
+ original request or offer expiry. Pending/unknown cloud creation has no secret
89
+ response. Invalid/conflicting/foreign files fail closed without overwriting
90
+ them; the normal runtime reports only a redacted cycle failure. Disabled/retired
91
+ admitted requests can receive a nonsecret disabled response. The app stages and
92
+ claims automatically, without an offer-review screen, using the unchanged
93
+ phoneHello/companionHello proof and independently verified daemon identity.
94
+
95
+ Activation removes the owned request/private response. Expiry removes them and
96
+ their durable enrollment record; existing pair/audit retirement is unchanged.
97
+ Stop removes only owned responses/descriptor/lock, retaining exact request/pair
98
+ authority for restart until original expiry. Explicit cloud-off removes secret
99
+ responses and never creates another pair. Automatic observation is bounded by
100
+ the app to10 response reads over at most30s; a later foreground refresh retains
101
+ the same exact request. No forever polling, recursive requests or cloud pairing
102
+ on each launch.
103
+
104
+ Implementation APIs are `LocalEnrollment.cleanup/cycle/close`,
105
+ `EnrollmentFiles`/`discoveryDirectory`, `setupEnrollment`, and the explicit
106
+ `EnrollmentRequest`, `EnrollmentOffer`, `EnrollmentRecord`,
107
+ `EnrollmentDescriptor`, `EnrollmentResponse` types. All test homes/storage and
108
+ service lifecycle I/O are injectable; tests never create discovery in real HOME
109
+ or implicitly register a real service. Focused isolated consumers live in
110
+ `tests/local-enrollment.test.ts` and `tests/setup-command.test.ts`; they are
111
+ verification instructions, not a claim of execution.
112
+
113
+ Config/resource readers and atomic writers use the same524288-byte serialized
114
+ bound, preserving full original request bytes. Oversize writes reject before
115
+ replacement. Only acquired runtime ownership initializes fresh config; duplicate
116
+ `run` never writes an old loaded config over live enrollment.
117
+
118
+ ## Expert-only manual enrollment offer v1
4
119
 
5
120
  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
121
 
7
122
  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
123
 
124
+ Unreleased source onboarding: invoking `pair` is explicit cloud consent. If
125
+ `apiOrigin` is absent, select the built-in
126
+ `https://moremote-cloud-ingress.pages.dev`; otherwise preserve and validate the
127
+ configured origin. Existing target, local official discovery and daemon pin
128
+ remain authoritative. Persist cloud-enabled configuration and the new offer
129
+ only after the official connection succeeds, before relay creation. Retained
130
+ pair keys, origins and revocation are never changed by a new enrollment.
131
+ Passive config loads/check/status do not opt in, and pairing installs no service.
132
+
9
133
  ## Official compatibility and observation
10
134
 
11
135
  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.
@@ -16,7 +140,7 @@ Only selected paseo.pid and local-credential files are read, with bounded I/O an
16
140
 
17
141
  ## Bounded encrypted state and attention
18
142
 
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.
143
+ State plaintext is exactly {version:1,daemonServerId,hostName,measuredAt,tasks:[{agentId,provider,title,status,createdAt,updatedAt,lastUserMessageAt,activeTurnStartedAt,cwd,requiresAttention,attentionReason,pendingRequests:[{requestId,requestBinding,request:<complete original official request JSON>}]}],usage,tasksTruncated}. Provider and creation time are additive unreleased source fields; older snapshots may omit them. Preserve genuine official provider and ISO-8601 createdAt/lastUserMessageAt facts; a missing last-user time stays null, never replaced by assistant-driven updatedAt. Consumers order recents by lastUserMessageAt, then creation time only when absent, then stable identity for ties. 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
144
 
21
145
  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
146
 
@@ -32,6 +32,31 @@ Automatic discovery requests bounded latest metadata once per six hours, persist
32
32
 
33
33
  `auto-update --disable` writes a separate durable marked private opt-out even while another writer is staging/draining. Readers immediately report disabled. No queued candidate activates while disabled, including an explicit manual candidate; `auto-update --enable` resumes eligible queued work. An automatic pending candidate is cancelled when the writer is available; a concurrent installation may finish staging but cannot activate. Enabling never resets discovery deadlines or failed-version suppression. `status` distinguishes package bootstrap required, source-checkout manual mode, and the managed active/pending/previous/error/check facts.
34
34
 
35
+ ## Explicit setup capability migration — CLI0.1.4 and later
36
+
37
+ `setup --yes` authorizes a specific owned CLI migration, not a global package,
38
+ Node or official daemon upgrade and not a change to automatic-update policy.
39
+ The current frontend recognizes its `localEnrollment:1` capability and routes
40
+ setup to selected code only when that selected package supports the same
41
+ enrollment/config-bound capability. A retained public0.1.2 handler cannot swallow
42
+ the command as unknown before the new handler runs.
43
+
44
+ After stopping only the owned runtime/service and authenticating official
45
+ identity, setup stages/verifies its exact current version when necessary.
46
+ Unavailable current packages or missing capability fail before feature/cloud
47
+ enablement; no old npm fallback is accepted. Then active/bootstrap move to the
48
+ capable package, previous/immutable packages and pair/custom-origin state remain,
49
+ and the independent update opt-out still wins for future automatic updates.
50
+ Source checkout without managed state instead binds its current own frontend.
51
+ Actual publication and installation receipts are recorded in docs/STATE.md.
52
+
53
+ All current config readers/resource validators/writers share524288bytes and
54
+ reject an oversized serialized replacement before publication. Original request
55
+ bytes are retained even when JSON control-character escaping expands them.
56
+ This explicit capability migration does not assert that a directly invoked old
57
+ 128KiB config reader can consume larger state. Retained public frontends route
58
+ subsequent commands to selected capable code rather than invoking old handlers.
59
+
35
60
  ## Compatibility and activation
36
61
 
37
62
  Every publish declares `moremote: {updateProtocol:1,journalSchema:1,wireProtocol:1}`. Both staging selection and the retained supervisor independently check this exact compatibility tuple. Missing/different compatibility remains pending with manualRequired and `UPDATE_MANUAL_COMPATIBILITY_REQUIRED`; it never drains or executes. Automatic-release validation also rejects another tuple. A compatible release MUST preserve all older retained versions' ability to read/write the same config/journal, mutation tombstones and wire lifecycle. A mere startup survival window cannot prove this property. Breaking storage/wire changes require a separately designed, owner-approved migration/release process; do not relabel an incompatible schema as1 or promise arbitrary downgrade safety. The existing FULL-sync journal, occurrence, revoke and no-replay contracts are unchanged.
package/package.json CHANGED
@@ -1,15 +1,38 @@
1
1
  {
2
2
  "name": "@moxuli/moremote",
3
- "version": "0.1.2",
3
+ "version": "0.1.5",
4
4
  "description": "Optional encrypted notification and scoped-action companion for Paseo",
5
5
  "license": "Apache-2.0",
6
6
  "type": "module",
7
- "repository": {"type": "git", "url": "git+https://github.com/moxuli/moremote-cli.git"},
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/moxuli/moremote-cli.git"
10
+ },
8
11
  "homepage": "https://github.com/moxuli/moremote-cli#readme",
9
- "bugs": {"url": "https://github.com/moxuli/moremote-cli/issues"},
10
- "publishConfig": {"access": "public", "registry": "https://registry.npmjs.org"},
11
- "moremote": {"updateProtocol": 1, "journalSchema": 1, "wireProtocol": 1},
12
- "files": ["bin", "dist", "docs", "vectors", "licenses", "LICENSE", "NOTICE", "README.md"],
12
+ "bugs": {
13
+ "url": "https://github.com/moxuli/moremote-cli/issues"
14
+ },
15
+ "publishConfig": {
16
+ "access": "public",
17
+ "registry": "https://registry.npmjs.org"
18
+ },
19
+ "moremote": {
20
+ "updateProtocol": 1,
21
+ "journalSchema": 1,
22
+ "wireProtocol": 1,
23
+ "localEnrollment": 1,
24
+ "configBytes": 524288
25
+ },
26
+ "files": [
27
+ "bin",
28
+ "dist",
29
+ "docs",
30
+ "vectors",
31
+ "licenses",
32
+ "LICENSE",
33
+ "NOTICE",
34
+ "README.md"
35
+ ],
13
36
  "engines": {
14
37
  "node": ">=24.13.0 <25"
15
38
  },