@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.
Files changed (67) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE +31 -0
  3. package/README.md +73 -2
  4. package/bin/moremote-cli.js +34 -0
  5. package/bin/moremote-service.js +7 -0
  6. package/dist/bindings.d.ts +6 -0
  7. package/dist/bindings.js +4 -0
  8. package/dist/cli.d.ts +1 -0
  9. package/dist/cli.js +325 -0
  10. package/dist/cloud-client.d.ts +43 -0
  11. package/dist/cloud-client.js +128 -0
  12. package/dist/config.d.ts +36 -0
  13. package/dist/config.js +68 -0
  14. package/dist/control-transport.d.ts +4 -0
  15. package/dist/control-transport.js +68 -0
  16. package/dist/control.d.ts +3 -0
  17. package/dist/control.js +297 -0
  18. package/dist/controls.d.ts +15 -0
  19. package/dist/controls.js +36 -0
  20. package/dist/crypto.d.ts +23 -0
  21. package/dist/crypto.js +68 -0
  22. package/dist/evidence.d.ts +19 -0
  23. package/dist/evidence.js +4 -0
  24. package/dist/journal.d.ts +104 -0
  25. package/dist/journal.js +132 -0
  26. package/dist/limits.d.ts +21 -0
  27. package/dist/limits.js +8 -0
  28. package/dist/official-client.d.ts +120 -0
  29. package/dist/official-client.js +162 -0
  30. package/dist/operations.d.ts +71 -0
  31. package/dist/operations.js +210 -0
  32. package/dist/pairing.d.ts +19 -0
  33. package/dist/pairing.js +68 -0
  34. package/dist/permission.d.ts +9 -0
  35. package/dist/permission.js +66 -0
  36. package/dist/projection.d.ts +24 -0
  37. package/dist/projection.js +35 -0
  38. package/dist/resources.d.ts +76 -0
  39. package/dist/resources.js +299 -0
  40. package/dist/runtime.d.ts +8 -0
  41. package/dist/runtime.js +375 -0
  42. package/dist/service.d.ts +21 -0
  43. package/dist/service.js +310 -0
  44. package/dist/supervisor.d.ts +15 -0
  45. package/dist/supervisor.js +175 -0
  46. package/dist/update-state.d.ts +30 -0
  47. package/dist/update-state.js +158 -0
  48. package/dist/updater.d.ts +9 -0
  49. package/dist/updater.js +152 -0
  50. package/docs/README.md +23 -0
  51. package/docs/STATE.md +155 -0
  52. package/docs/configuration.md +37 -0
  53. package/docs/conventions.md +9 -0
  54. package/docs/decisions/0001-managed-updates.md +19 -0
  55. package/docs/plans/2026-11-10-managed-updates.md +26 -0
  56. package/docs/plans/2026-11-10-notification-delivery.md +118 -0
  57. package/docs/releasing.md +34 -0
  58. package/docs/specs/01-architecture.md +102 -0
  59. package/docs/specs/02-encrypted-delivery.md +194 -0
  60. package/docs/specs/03-api-contract.md +397 -0
  61. package/docs/specs/04-control-and-receipt-lifecycle.md +175 -0
  62. package/docs/specs/05-endpoint-and-lifecycle.md +57 -0
  63. package/docs/specs/06-managed-updates.md +55 -0
  64. package/licenses/Paseo-0.15.3.txt +211 -0
  65. package/package.json +37 -4
  66. package/vectors/bearer-v1.json +6 -0
  67. package/vectors/envelope-v1.json +24 -0
@@ -0,0 +1,118 @@
1
+ # First notification and scoped-delivery implementation
2
+
3
+ **Goal:** a usable optional computer enhancement layer over an unmodified
4
+ Paseo0.15.3 interface, with transparent lifecycle and encrypted short-lived actions.
5
+ **Architecture:** Node24/TypeScript, official SDK adapter, standard endpoint
6
+ crypto, persistent operation journal and separately authenticated cloud client.
7
+ **Global constraints:** Apache-2.0; no private workspace/runtime dependency; no
8
+ production session mutation, public publication, automatic installation/update,
9
+ official file edits, fake presence/read/Expo registration, blind mutation replay,
10
+ plaintext endpoint secrets in logs or false execution acknowledgements.
11
+
12
+ ## File responsibilities and interfaces
13
+
14
+ - `src/cli.ts`: portable actual command parser and user-facing entry points.
15
+ - `src/config.ts`: bounded validated private per-user configuration and explicit
16
+ API/official-target settings, no hardcoded developer path/account.
17
+ - `src/crypto.ts`: standard AES-GCM/HKDF envelope implementation and exact public
18
+ conformance vectors; no cloud-encryption-key upload.
19
+ - `src/cloud-client.ts`: exact versioned HTTP API, immutable retries and pairing.
20
+ - `src/official-client.ts`: narrow real SDK authentication/subscription/snapshot/
21
+ send/permission boundary; no SDK queued replay after ambiguous mutation.
22
+ - `src/journal.ts`: durable operation identity, dispatch/restart and receipt truth.
23
+ - `src/operations.ts`: typed payload/current-request validation and one-dispatch
24
+ execution; unknown outcome is not automatic retry permission.
25
+ - `src/runtime.ts`: bounded observation/attention/state and paired command loop.
26
+ - `src/service.ts`: independently owned per-user service check/install/stop/remove
27
+ adapters and explicit update execution; preserve official resources.
28
+ - `tests/`: consumer-visible crypto, ownership, timing, persistence, protocol and
29
+ actual CLI tests. No tests of copied text, incidental defaults or mock echoes.
30
+
31
+ ## Contract
32
+
33
+ Carry a standalone reviewed copy of the relay v1 contract in `docs/specs/`.
34
+ App/companion/cloud are independently distributed; no sibling imports, symlinks
35
+ or private shared packages. Match the published contract bytes, operation IDs,
36
+ expiry/revocation and receipt states exactly. Host credentials stay local.
37
+
38
+ Core interfaces are `sealEnvelope(rootKey,metadata,payload)` /
39
+ `openEnvelope(rootKey,envelope,now)`, `CloudClient`, an `OfficialClient` adapter,
40
+ and an `OperationJournal` that persists irrevocable dispatch before official I/O.
41
+ Exact signatures belong with their implementation and consumer tests; modules
42
+ must not bypass that journal for retry convenience.
43
+
44
+ ## Steps and verification
45
+
46
+ 1. Write contract tests first for vectors, wrong-key/metadata rejection,
47
+ enrollment binding, expiry, same-ID conflicting bytes, crash recovery and
48
+ current permission authority. Have the integration owner run the initial RED
49
+ selection before implementing; do not run builds/tests concurrently in workers.
50
+ 2. Implement cohesive modules against real SDK declarations and official docs.
51
+ Preserve original Unicode content and request/action IDs. Reconnect observes
52
+ fresh state without clearing attention or replaying uncertain writes.
53
+ 3. Add complete check/configure/pair/run/status/cloud-disable/update/stop/uninstall
54
+ commands. Install/update actions are explicit, fail honestly and change only
55
+ companion-owned resources. Foreground runtime remains a first-class route.
56
+ 4. Add README, docs index/STATE/specs/ADRs/conventions, CONTRIBUTING/PR guidance,
57
+ Apache license/upstream notices and an independent local check entry. Remote
58
+ issue/CI surfaces may remain a recorded substrate gap until a repository exists.
59
+ 5. Freeze source. Run focused checks and fresh-terminal help/check plus the local
60
+ cloud/companion journey, and read-only isolated official status/subscription.
61
+ Do not contact real work sessions or claim other-OS/service-install acceptance.
62
+ 6. Independent spec review, then quality/security review; close and re-review
63
+ findings. Record evidence/limits, update current docs and commit locally.
64
+
65
+ ## Acceptance boundaries
66
+
67
+ All implemented commands must be real, not stubs or silent success fallbacks.
68
+ Cloud deployment, Apple push configuration, physical push delivery, public package
69
+ publication and installation into the everyday host are external gates, not
70
+ prerequisites to pretend local tests passed. Remaining native system integrations
71
+ are separate app delivery units, not unfinished companion implementations.
72
+
73
+ ## Verification journal — 2026-11-10
74
+
75
+ - Integration-owner combined check:900second timeout; both real SDK-wire modes
76
+ failed after approximately13seconds each, and fixture resource leaks prevented
77
+ clean exit/stack reporting. Build was not reached.
78
+ - Repair: official startSeq/endSeq timeline framing and full response schema
79
+ validation; required release subscriptionId; independently owned, cancellable,
80
+ bounded teardown of SDKs/sockets/server/journals/timers. No behavioral assertion
81
+ was removed and production contracts were unchanged.
82
+ - Integration-owner focused command
83
+ `node --import tsx --test tests/official-wire.test.ts`:2/2 passed in26.7seconds,
84
+ without a hang. This covers both legacy and owned subscription modes only.
85
+ - Typecheck and all other behavior selections have passing results after removing
86
+ an incidental exact-stderr assertion that rejected Node's SQLite warning. The
87
+ privacy invariant still rejects leaked synthetic child paths; its focused
88
+ regression passed1/1. Build and actual compiled help/version succeeded.
89
+ - Actual native Kit/CryptoKit→Pages→Worker→SQLite enrollment verified the exact
90
+ isolated official0.15.3 daemon identity. Foreground runtime, immutable command
91
+ retry/rejection, endpoint-authenticated revocation and post-revoke bounded
92
+ outcome audit passed without real agent creation or session mutation.
93
+ - Scoped independent reviews are closed. Local implementation/acceptance is
94
+ complete; service installation, public publication and production/Apple/device
95
+ activation remain separate operator gates. Exact run chronology is in STATE.
96
+
97
+ ## Subsequent owner-approved CLI identity cutover — 2026-11-10
98
+
99
+ Canonical product: **MoRemote CLI**; repository/command: `moremote-cli`; current public npm identity: `@moxuli/moremote`;
100
+ entry: `bin/moremote-cli.js`; state override: `MOREMOTE_CLI_HOME`.
101
+ macOS/Windows state is `MoRemoteCLI`; Linux state is `moremote-cli`. Services
102
+ are `com.moremote.cli`, `moremote-cli.service` and Windows logon task `MoRemoteCLI`.
103
+ CLI-owned runtime/client/managed-package identities move together. There is no
104
+ released package or installed service to migrate; use no compatibility alias or
105
+ automatic old-state adoption. Preserve foreign-resource protections, protocol
106
+ role `companionHello`, crypto salt/schema, APNs categories and app/Keychain IDs.
107
+
108
+ The implementation and root move are complete. Fresh source, compiled-command,
109
+ isolated-state and package checks pass; independent identity/quality review
110
+ findings are closed. STATE records exact full-suite and later focused-delta
111
+ evidence separately. Earlier verification used `moremote-companion`; keep its
112
+ historical transcript and this plan filename stable.
113
+
114
+ Proceeding toward cloud/Apple activation is also owner-approved, with exact
115
+ resource/key/permission/billing mutations requiring point-of-risk interactive
116
+ confirmation. No deployment, Apple activation, physical delivery, public
117
+ publication or everyday-host service installation is claimed by this update.
118
+
@@ -0,0 +1,34 @@
1
+ # Releasing @moxuli/moremote
2
+
3
+ Repository: public `moxuli/moremote-cli`; package: public `@moxuli/moremote`; executable: `moremote-cli`. No unscoped alias is published. Credentials never belong in this repository, release assets or package contents.
4
+
5
+ ## Existing publishing authority
6
+
7
+ The owner already provisioned organization secret `NPM_TOKEN`, restricted to this selected public CLI repository. Reuse that configuration. Do not create another token, require a new login, or block release on a web-only trusted-publisher migration. The workstation's protected publishing credential is separately loaded at point of use; do not echo it or commit an authenticated npm configuration.
8
+
9
+ The release job uses environment `npm-release`. Only its publish step receives the existing secret as `NODE_AUTH_TOKEN`; checks, dependency installation, builds and package scripts do not receive it. The temporary npm configuration contains the literal environment placeholder, pins both default and `@moxuli` registries to npmjs, has private permissions and is removed after publishing. No authentication file is packaged. Token authority/expiry and required interactive provider checks still apply; never bypass them or claim acceptance from a valid identity read alone.
10
+
11
+ Configure the release environment to accept authorized `v*` tags. Branch/tag protection and required reviewers remain owner-governed settings. Token replacement/revocation is a separate account action. npm trusted publishing remains an optional future migration, not an additional prerequisite for the current owner's existing setup.
12
+
13
+ ## Normal release
14
+
15
+ 1. Keep dependencies pinned. Preserve the compatibility tuple only when storage/wire rollback is genuinely safe. On Node24.13.0 run `npm ci --ignore-scripts`, `npm run check`, `npm run smoke:upgrade`, `node scripts/release.mjs validate vX.Y.Z` and `node scripts/release.mjs pack vX.Y.Z`.
16
+ 2. Review public contents and changelog. Update package.json and only lockfile root versions, commit through review, then push the exact owner-authorized stable `vX.Y.Z` tag. Prerelease/range/mismatched tags fail closed. Generated tarballs/SHA256SUMS are release outputs, not tracked source.
17
+ 3. The GitHub-hosted Ubuntu24.04 job validates repository/tag/package/lock identity, checks/builds and produces two byte-identical packs. It publishes the exact tested tarball with the existing scoped secret, public access and GitHub provenance. Node24.13.0 is pinned; no global toolchain upgrade occurs.
18
+ 4. Only after npm accepts publication does the job create a GitHub Release with the identical tarball and SHA256SUMS. Release concurrency is serialized and never cancels an in-flight publish. Only this job receives contents:write/id-token:write for release/provenance; ordinary CI is contents:read. Checkout credentials are not persisted and release builds use no cache.
19
+ 5. If npm fails, no successful GitHub Release is created. If npm accepted but GitHub creation failed, **do not republish or retag**: recover the exact published bytes, validate integrity against the accepted build artifact/checksum, and recover the GitHub Release under the owner's release authorization. npm versions are immutable.
20
+ 6. npm can acknowledge submission while processing a new package. Require an independent anonymous registry read and installation of the public exact version before claiming availability. Do not repeatedly republish while processing. Record the receiver result in STATE.
21
+
22
+ The first workstation bootstrap publication is0.1.0. Subsequent automated releases must use a genuinely new version; neither workflow reruns nor corrected documentation can replace published0.1.0 bytes.
23
+
24
+ CI also runs portable behavior and isolated real packaged-upgrade smoke on macOS/Linux/Windows. It never installs a real login service. Native platform managers and physical APNs are separate acceptance gates.
25
+
26
+ ## Verified action pins and primary sources
27
+
28
+ - [`actions/checkout` v6.0.2](https://github.com/actions/checkout/tree/de0fac2e4500dabe0009e67214ff5f5447ce83dd): resolved official tag.
29
+ - [`actions/setup-node` v6.1.0](https://github.com/actions/setup-node/tree/395ad3262231945c25e8478fd5baf05154b1d79f): resolved official tag.
30
+ - [GitHub publishing Node packages](https://docs.github.com/en/actions/tutorials/publish-packages/publish-nodejs-packages): scoped public publishing, token use and provenance.
31
+ - [npm provenance](https://docs.npmjs.com/generating-provenance-statements): hosted build identity is separate from npm publishing authority.
32
+ - [npm trusted publishers](https://docs.npmjs.com/trusted-publishers/): optional future short-lived authentication migration.
33
+
34
+ Never infer a registry package, hosted workflow result, release or protection setting from checked-in YAML alone. Record only exercised facts, without private accounts or credential values.
@@ -0,0 +1,102 @@
1
+ # 01 — MoRemote CLI architecture
2
+
3
+ **Status:** owner-approved notification/scoped-delivery iteration; implementation source pending independent verification
4
+ **Date:** 2026-11-10
5
+
6
+ ## Purpose and boundaries
7
+
8
+ MoRemote CLI (`moremote-cli`) is the optional open-source enhancement layer for MoRemote.
9
+ It consumes official Paseo interfaces. It never patches, forks, replaces or
10
+ silently updates Paseo. The official daemon continues owning agents, sessions,
11
+ tools and approvals. Baseline MoRemote works without this companion.
12
+
13
+ This repository must build and run independently of the app repository, any
14
+ private automation workspace or a developer's personal machine configuration.
15
+ Documentation uses synthetic identifiers and credentials only.
16
+
17
+ The owner approved the full identity cutover on 2026-11-10. Repository, npm
18
+ package, executable, client/runtime ownership and managed-package identities
19
+ move together; no legacy alias or old-state adoption is provided. Configuration
20
+ and service names are listed in the configuration registry. Protocol role
21
+ `companionHello`, cryptographic salt/envelope schema, APNs categories and the
22
+ app/Keychain identities are deliberately preserved. Earlier local acceptance
23
+ predates the rename; STATE records fresh renamed-tree verification separately.
24
+
25
+ ## Runtime
26
+
27
+ Use TypeScript on the supported Node 24 line, matching official upstream client
28
+ interfaces and avoiding a second host-protocol implementation where the SDK is
29
+ usable. Pin dependencies and test the explicit upstream compatibility range.
30
+ Support macOS, Windows and Linux through one program with platform adapters for
31
+ background-service registration; no separately maintained shell/batch products.
32
+
33
+ Foreground `run` is a first-class entry point. Installation and service enablement
34
+ are explicit, reversible operations; building or testing cannot register a service.
35
+ The program remains inspectable and never needs administrator access for ordinary
36
+ per-user operation.
37
+
38
+ ## Components
39
+
40
+ - **Official adapter:** authenticated local daemon connection, bounded snapshot
41
+ and authoritative event subscriptions; no fake user focus/read acknowledgements.
42
+ - **Attention projection:** completion, pending question/approval and supported
43
+ errors from typed evidence; no prose classifiers or fabricated progress/usage.
44
+ - **Cloud transport:** separately authenticated registration, bounded retry and
45
+ encrypted short-lived operations. Official access credentials never leave host.
46
+ - **Action executor:** explicit allowlisted message/question/approval actions,
47
+ checked against current authoritative target before execution.
48
+ - **Durable local receipts:** operation identity and execution outcomes survive
49
+ process restarts. An uncertain daemon write is never blindly resent.
50
+ - **Lifecycle/diagnostics:** check, configure, run, status, stop, update, uninstall;
51
+ only companion-owned resources may be changed or removed.
52
+
53
+ ## Pairing and privacy
54
+
55
+ Pair the phone through an expiring one-use offer that pins a separate per-phone
56
+ endpoint key out of band. The existing official pairing credential
57
+ is not a cloud login or companion enrollment token. Each paired phone has a
58
+ separate identity and can be revoked without replacing official credentials.
59
+
60
+ End-to-end encryption keys remain at endpoints. The service can route ciphertext,
61
+ not decrypt messages or authorize arbitrary commands. Pairing/transport details
62
+ and byte-level cryptographic vectors belong in the reviewed shared protocol
63
+ contract; no homemade cryptographic primitive is permitted.
64
+
65
+ Never log complete pairing links, user prompts, tool output, filesystem paths,
66
+ model credentials or private keys. A redacted diagnostic is explicit and includes
67
+ versions, capabilities, connection stages and error codes, not hidden user data.
68
+
69
+ ## Action semantics
70
+
71
+ A command targets one paired computer, one official conversation and, for a
72
+ reply/approval, one currently pending request. Identity, expiry and exact content
73
+ are immutable across transport retries. Receipts distinguish cloud acceptance,
74
+ companion delivery, official acceptance, failure, expiry, cancellation and unknown
75
+ outcome. Do not promise exactly-once execution if the upstream interface cannot
76
+ establish it. No arbitrary shell, generic RPC or background approval automation.
77
+
78
+ Revocation prevents new execution when observed before the irrevocable execution
79
+ boundary; it cannot roll back an already accepted official action. Restart,
80
+ network loss and reconnect preserve identities and do not replay historical
81
+ attention as fresh notifications.
82
+
83
+ ## User transparency
84
+
85
+ Users can inspect what runs at login, cloud destination, enabled features,
86
+ registered phones and data egress. Disabling cloud stops its transport without
87
+ breaking the official daemon. Stop/uninstall do not remove chat history, official
88
+ configuration, model credentials or unrelated services. Update offers state the
89
+ source/version and require an explicit action.
90
+
91
+ ## Verification and release boundary
92
+
93
+ Core parsing, attention, crypto contracts and action/receipt transitions are
94
+ behavior-tested before implementation. Integration uses isolated official test
95
+ daemons and synthetic sessions, never a user's existing work conversation.
96
+
97
+ Real push requires a separately deployed service and Apple configuration. Local
98
+ protocol acceptance is not APNs delivery, physical battery behavior or a tested
99
+ background-service installer on another OS. No package publication, public Git
100
+ repository, automatic installer execution or production service registration is
101
+ implied by implementation approval. The owner selected Apache-2.0; public
102
+ publication remains separately authorized.
@@ -0,0 +1,194 @@
1
+ # 02 — Scoped encrypted delivery contract
2
+
3
+ **Status:** owner-approved first notification/scoped-delivery contract; local implementation pending integration verification
4
+ **Date:** 2026-11-10
5
+
6
+ ## Scope and endpoint authority
7
+
8
+ One pairing joins one companion installation and one phone. A host can own
9
+ several independent pairings. Cloud authentication credentials grant access to
10
+ bounded relay records only, not official Paseo access. End-to-end authentication
11
+ is independent of those cloud credentials.
12
+
13
+ Use AES-256-GCM and HKDF-SHA256, implemented by standard platform cryptographic
14
+ libraries. The companion generates a random 32-byte per-pair root key locally;
15
+ only the QR-enrolled phone receives it. The service never receives that root key.
16
+ Separate direction/purpose keys are derived with versioned protocol, pairing and
17
+ channel context. Use a fresh cryptographically random 12-byte nonce per envelope;
18
+ never derive it from clocks, operation IDs or retry counters. Retransmission
19
+ reuses the original immutable envelope rather than re-encrypting an operation.
20
+
21
+ This is an authenticated paired-device channel, not a claim of forward secrecy,
22
+ ratcheting or authenticated cloud metadata. A cloud compromise can observe
23
+ routing/timing, delay or drop work, but cannot manufacture an accepted encrypted
24
+ command. Endpoint compromise is outside that guarantee. Re-pairing creates a new
25
+ root key and identities; revocation does not rotate unrelated phones' keys.
26
+
27
+ ## Enrollment
28
+
29
+ The companion requests a bounded enrollment record and receives separately
30
+ scoped host and one-use enrollment credentials. The locally rendered QR contains
31
+ the HTTPS API origin, enrollment/pairing identity, enrollment credential, root key,
32
+ protocol version and expiry. It contains no official host password or model key.
33
+ The proposed offer lifetime is ten minutes.
34
+
35
+ A phone claim is atomic, expiring and tied to a stable phone-generated claim ID;
36
+ a retry of the same claim cannot create another phone. Claiming alone does not
37
+ grant execution authority. The companion must verify an encrypted challenge /
38
+ phone-acceptance handshake under the QR root key before activating commands.
39
+ The phone verifies the companion's matching authenticated response. A service
40
+ that knows its own enrollment/authentication tokens cannot complete this proof
41
+ without the endpoint key. Unsupported/expired/claimed-by-another offers do not
42
+ replace an existing pairing.
43
+
44
+ Transport uses HTTPS, except explicit loopback development. QR origin changes,
45
+ new host associations, key replacement and public network destinations remain
46
+ visible user decisions. A mobile host identifier is resolved through its existing
47
+ verified identity, never guessed from its display name.
48
+
49
+ The canonical version-1 enrollment offer is compact JSON
50
+ `{version:1,apiOrigin,pairId,enrollmentToken,rootKey,expiresAt}`. Both secret values
51
+ are canonical unpadded-base64url encodings of independent 32-byte random values.
52
+ The companion's JSON output uses that exact object; the QR/link wraps its UTF-8
53
+ bytes as `moremote://enhance#<unpadded-base64url(JSON)>`. The phone can also accept
54
+ explicit raw-JSON paste. The offer/root key is never uploaded. Activation binds
55
+ only an existing verified daemon server identity, never a host-name match.
56
+
57
+
58
+
59
+ ### Byte-level version 1
60
+
61
+ Envelope fields are `version: 1`, lowercase UUID `pairId`, lowercase UUID `id`,
62
+ `channel`, integer `issuedAt`, integer `expiresAt`, `nonce`, and `ciphertext`.
63
+ Milliseconds are nonnegative safe integers. Channels are `enrollment`,
64
+ `activation`, `command`, `receipt`, `state`, `attention`, `control` and
65
+ `controlReceipt`, with independent HKDF purpose separation.
66
+
67
+ HKDF input is the 32-byte endpoint root key. Salt is UTF-8 `MoRemote pairing v1`;
68
+ info is the compact UTF-8 JSON array `[1,pairId,channel]`, with quoted strings and
69
+ no whitespace. Derive 32 bytes with HKDF-SHA256. GCM additional authenticated data
70
+ is compact UTF-8 JSON `[1,pairId,id,channel,issuedAt,expiresAt]`. The restricted
71
+ ASCII identifiers and channels eliminate platform-dependent escaping. Nonce and
72
+ ciphertext use canonical unpadded base64url. Ciphertext is encrypted bytes followed
73
+ by the 16-byte authentication tag. GCM nonce is exactly 12 bytes.
74
+
75
+ The maximum envelope JSON request is 128 KiB; decrypted command content is at
76
+ most 64 KiB. Reject oversized input, invalid/canonical-encoding mismatches,
77
+ unknown fields/version/channel, invalid UUIDs and invalid integer/time intervals.
78
+ Command/control TTL is300seconds; enrollment/state/attention TTL is600seconds.
79
+ Both endpoint enrollment proofs are additionally bounded by the original offer
80
+ interval. Receipt/controlReceipt headers attest at current time, with at most
81
+ 600seconds between issuedAt and expiresAt; serialized minimal envelopes are at
82
+ most8KiB. Their ciphertext is retained until the original operation/control expiry
83
+ plus24hours for historical authenticated read-only audit, even after revocation.
84
+ This does not extend an operation's authority or its original payload TTL.
85
+ Clock tolerance is120seconds for future issue times, never expired execution
86
+ grace. Recipients check expiry immediately before dispatch. All limits are
87
+ centralized documented constants. [04](04-control-and-receipt-lifecycle.md)
88
+ specifies control/receipt lifecycle and authenticated revision watermarks.
89
+ ## Envelope
90
+
91
+ Every envelope has a protocol version, pairing ID, opaque record/operation ID,
92
+ channel, issued-at and expiry milliseconds, nonce and ciphertext including GCM
93
+ authentication tag. The bounded fixed-order metadata tuple is authenticated as
94
+ additional data. Specify its exact UTF-8 JSON-array representation, base64url
95
+ encoding and integer bounds in shared known-answer vectors before code. Never
96
+ rely on arbitrary object key iteration or a platform's JSON pretty-printer.
97
+
98
+ Channels are independently keyed: phone command, companion receipt, companion
99
+ state and pairing proof. Unknown version/channel is rejected, not downgraded.
100
+ Recipient validates metadata and decrypted identifiers before dispatch. Payload
101
+ bounds and TTL checks apply before unbounded parsing or storage.
102
+
103
+ Plaintext command data contains the exact official conversation ID, action,
104
+ request identity where needed and original user content. No arbitrary RPC,
105
+ shell script, filesystem action or executable native bridge is accepted.
106
+
107
+ ## Operations
108
+
109
+ Supported meanings are message send, pending-question response and approval
110
+ response. Question/approval content follows the verified upstream schema and is
111
+ revalidated against the current request. Transport identity is not an official
112
+ permission request ID. Do not infer a request by title/text.
113
+
114
+ The maximum operation lifetime is five minutes, with a documented
115
+ bounded clock-skew allowance. An expired operation cannot become live after a
116
+ restart or reconnect. Longer user tasks do not extend a short command's authority.
117
+
118
+ Cloud acceptance atomically records immutable operation ID and envelope bytes.
119
+ An exact retry returns the existing outcome; the same ID with different bytes is
120
+ a conflict. Claim/delivery does not mean execution. Relay cancellation/revocation
121
+ and relay dispatch serialize on the authoritative record; a cloud DELETE only
122
+ confirms that relay boundary, not computer revocation. Independently encrypted
123
+ controls and companion-persisted tombstones/receipts establish endpoint facts
124
+ as specified in04. Dispatched work is too late to undo; a dispatched-but-
125
+ unconfirmed operation never becomes executable again through lease expiry.
126
+
127
+ The companion durably records its execution boundary before sending an official
128
+ mutation. It must not use an SDK's automatic reconnect queue to replay an
129
+ uncertain send. On transport loss it reconciles canonical source facts and
130
+ reports unknown if acceptance cannot be established. A matching provider message
131
+ identity is evidence only when exact target/content and upstream meaning match;
132
+ absence from a bounded timeline is not proof the action was never accepted.
133
+
134
+ ## Receipts and state
135
+
136
+ Receipts distinguish relay accepted, delivered, official admission accepted,
137
+ request resolved, rejected, expired, revoked and outcome unknown. Agent task
138
+ completion is a different event; a message admission receipt never claims the
139
+ agent finished or that the user read its answer.
140
+
141
+ Cloud-visible transport state is not authoritative execution proof. The phone
142
+ accepts execution facts only from the companion's authenticated encrypted receipt
143
+ for its exact immutable operation. A receipt cannot be copied to another pairing,
144
+ operation or request. Terminal receipts do not regress to queued after restart.
145
+
146
+ Minimal operation receipts carry a persisted positive revision; the phone retains
147
+ an authenticated monotonic watermark. Confirmed admission never regresses to
148
+ unknown. Only minimal outcome attestations (identity/revision/state/bounded code)
149
+ survive payload TTL for24hours after original expiry, including after revoke.
150
+ Historical decoding is read-only and cannot extend command authority. After
151
+ retention, the outcome is unavailable/unverifiable, not a cloud-only success.
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
157
+ outcome audit: only the latest nonexpired snapshot keeps ciphertext, while each
158
+ immutable state ID/digest survives supersession only through that envelope's
159
+ original expiry. Exact retries do not renew it; expired snapshots cannot be newly
160
+ admitted. State does not inherit the operation/control/attention expiry+24hour
161
+ audit window. Those records and minimal authenticated outcomes keep their
162
+ original retention unchanged.
163
+
164
+ ## Notifications
165
+
166
+ Cloud event ingestion accepts only paired companion credentials and bounded
167
+ attention kinds/identities, with immutable event dedupe. Push copy is generic by
168
+ default. APNs custom data contains only routing/opaque identities and necessary
169
+ bounded encrypted state; full prompts/history are never required for an alert.
170
+
171
+ Own genuine foreground viewing leases may suppress own notifications. A stale
172
+ lease expires; companion observation alone never counts as user presence. APNs
173
+ sandbox and production registrations are distinct. Invalid-token retirement,
174
+ bounded transient retry and ActivityKit update lifecycle use actual Apple results.
175
+ No APNs provider private key reaches endpoints or repository files.
176
+
177
+ APNs custom data includes `pairId`, `eventId`, `kind`, and the full encrypted
178
+ attention envelope as `route`. Total serialized UTF-8 payload, including generic
179
+ localized `aps`, must fit 4,096 bytes; oversized events are explicitly rejected,
180
+ never sent with an omitted route. This allows authenticated read-only navigation
181
+ to an already-saved exact host/conversation while offline or after the route's
182
+ expiry. Endpoints expose this as a separate authenticated navigation decoder;
183
+ it does not execute or renew an expired command, question or approval. The normal
184
+ command decoder and recipient pre-dispatch expiry checks remain strict.
185
+
186
+
187
+ ## Required evidence
188
+
189
+ Cross-runtime vectors cover exact encryption/decryption and authenticated metadata;
190
+ wrong keys, modified routing, expired envelopes and unsupported versions fail.
191
+ State-machine tests cover conflicting reuse, restart at each execution boundary,
192
+ revocation races, stale requests and uncertain official acceptance. An isolated
193
+ real daemon must confirm adapter event/receipt meanings; local transport tests
194
+ cannot prove production APNs HTTP/2 or device delivery.