@moxuli/moremote 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/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 +308 -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.d.ts +3 -0
- package/dist/control.js +226 -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 +132 -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 +38 -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 +49 -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,38 @@
|
|
|
1
|
+
# Releasing @moxuli/moremote
|
|
2
|
+
|
|
3
|
+
Repository: public `moxuli/moremote-cli`; package: public `@moxuli/moremote`; executable: `moremote-cli`. No unscoped npm alias is published. This repository contains no publishing credential and workflows do not read NPM_TOKEN/NODE_AUTH_TOKEN secrets.
|
|
4
|
+
|
|
5
|
+
## First publication and trust setup (human prerequisites)
|
|
6
|
+
|
|
7
|
+
The package must exist before its npm package settings can define a trusted publisher. An npm organization owner/package maintainer must establish an authenticated npm account, confirm the `@moxuli` scope/package authority and2FA policy, and explicitly authorize one **first public publication** of the validated0.1.0 tarball from a trusted workstation. This is an external release, not a CI dry run. Do not assume an org token exists, re-use a stale login, create a token automatically or publish merely to test authentication. If npm adds a pre-publication trusted-publisher reservation flow, use its current documented UI rather than guessing that the existing-package settings work for a404 package.
|
|
8
|
+
|
|
9
|
+
After that first package exists, on npmjs.com package Settings → Trusted Publisher, configure:
|
|
10
|
+
|
|
11
|
+
- provider GitHub Actions, organization `moxuli`, repository `moremote-cli`;
|
|
12
|
+
- workflow filename **`release.yml`** (not its full path);
|
|
13
|
+
- environment **`npm-release`**;
|
|
14
|
+
- permit **direct `npm publish`** (current npm defaults may allow staged publish only).
|
|
15
|
+
|
|
16
|
+
Create the matching GitHub environment, restrict it to protected release tags and add required reviewers if desired. Configure tag protection/Rulesets so only authorized maintainers can create release tags. A newly created npm trusted-publisher configuration must complete its first successful publish within the current documented two-day validation window; recreate an expired configuration rather than adding a long-lived secret fallback. For the first OIDC release, bump to a genuinely new version (for example0.1.1); npm versions cannot be overwritten. After successful OIDC publication, require2FA and disallow traditional tokens in npm publishing access, and separately revoke unused automation tokens under owner authorization. Existing organization secrets are not consumed by these workflows.
|
|
17
|
+
|
|
18
|
+
## Normal release
|
|
19
|
+
|
|
20
|
+
1. Keep dependencies pinned and the compatibility tuple unchanged only if storage/wire rollback is genuinely safe. Complete `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` using Node24.13.0. The pack command produces `moxuli-moremote-X.Y.Z.tgz` and `SHA256SUMS` from two byte-identical packs and validates archived identity/required entrypoints. These generated files are release outputs, not source files to commit.
|
|
21
|
+
2. Review public package contents, changelog and external acceptance separately. Update package.json and only the lockfile root versions; do not upgrade dependencies incidentally. Commit through normal review and push the exact stable `vX.Y.Z` tag only after owner release authorization. Prerelease/range/mismatched tags fail closed.
|
|
22
|
+
3. The release workflow revalidates repository/tag/package/lock identity, runs checks/build, packs deterministically, verifies the supported bundled npm version, and publishes that exact tarball with OIDC/public access/provenance. The `npm-release` environment gate applies. GitHub-hosted Ubuntu24.04 and pinned Node24.13.0 are used; no global npm upgrade occurs.
|
|
23
|
+
4. Only after npm publication succeeds does it create the GitHub Release containing the identical tarball and SHA256SUMS. Release concurrency is serialized and never cancels a publishing run. Only this job receives contents:write and id-token:write; ordinary CI has contents:read, checkout credentials are not persisted, and no cache is used in release builds.
|
|
24
|
+
5. If npm publish fails, no successful GitHub Release is created. If npm succeeded but GitHub creation failed, **do not republish/retag** or assume the workflow is transactional across registries. Recover the exact published npm tarball, validate its integrity and identity against the logged build artifact/checksum, and attach those bytes in a separately authorized GitHub Release operation. A rerun will honestly fail npm's immutable-version check; it never substitutes different bytes for the same version.
|
|
25
|
+
|
|
26
|
+
CI also runs portable behavioral checks and an explicit isolated real packaged-upgrade smoke on macOS/Linux/Windows. Native service registration still requires authorized platform acceptance; no CI step installs a real login service. Physical APNs acceptance is independent of npm/release acceptance.
|
|
27
|
+
|
|
28
|
+
## Verified action pins and primary sources
|
|
29
|
+
|
|
30
|
+
Official tag refs were resolved read-only from each official upstream with `git ls-remote`:
|
|
31
|
+
|
|
32
|
+
- [`actions/checkout` v6.0.2](https://github.com/actions/checkout/tree/de0fac2e4500dabe0009e67214ff5f5447ce83dd): `de0fac2e4500dabe0009e67214ff5f5447ce83dd`.
|
|
33
|
+
- [`actions/setup-node` v6.1.0](https://github.com/actions/setup-node/tree/395ad3262231945c25e8478fd5baf05154b1d79f): `395ad3262231945c25e8478fd5baf05154b1d79f`.
|
|
34
|
+
- [npm trusted publishers](https://docs.npmjs.com/trusted-publishers/): npm11.5.1+, supported hosted runners, exact workflow/environment binding, initial configuration expiry, automatic public provenance and token restrictions.
|
|
35
|
+
- [GitHub publishing Node packages](https://docs.github.com/en/actions/tutorials/publish-packages/publish-nodejs-packages): package/repository metadata, scoped public publication and provenance. OIDC follows npm's newer instructions, not GitHub's optional token example.
|
|
36
|
+
- [GitHub OIDC hardening](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect).
|
|
37
|
+
|
|
38
|
+
Do not claim a package/trusted publisher/release exists from checked-in workflow source alone. Current observed public availability/authentication and exercised checks belong in STATE.md, with no private account identifiers or credentials.
|
|
@@ -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.
|