@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,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.
|