signalk-p2p-plugin 0.0.0-stage → 0.4.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.
Files changed (174) hide show
  1. package/CHANGELOG.md +91 -0
  2. package/LICENSE +201 -0
  3. package/README.md +128 -2
  4. package/deploy/README.md +101 -0
  5. package/deploy/peer.example.json +9 -0
  6. package/deploy/policy.json +30 -0
  7. package/deploy/signalk-p2p-peer.service +23 -0
  8. package/dist/admin-page.d.ts +7 -0
  9. package/dist/admin-page.d.ts.map +1 -0
  10. package/dist/admin-page.js +8 -0
  11. package/dist/admin-page.js.map +1 -0
  12. package/dist/advanced-config.d.ts +11 -0
  13. package/dist/advanced-config.d.ts.map +1 -0
  14. package/dist/advanced-config.js +40 -0
  15. package/dist/advanced-config.js.map +1 -0
  16. package/dist/ais/publish.d.ts +7 -0
  17. package/dist/ais/publish.d.ts.map +1 -0
  18. package/dist/ais/publish.js +41 -0
  19. package/dist/ais/publish.js.map +1 -0
  20. package/dist/ais/store.d.ts +41 -0
  21. package/dist/ais/store.d.ts.map +1 -0
  22. package/dist/ais/store.js +140 -0
  23. package/dist/ais/store.js.map +1 -0
  24. package/dist/api.d.ts +68 -0
  25. package/dist/api.d.ts.map +1 -0
  26. package/dist/api.js +142 -0
  27. package/dist/api.js.map +1 -0
  28. package/dist/config.d.ts +166 -0
  29. package/dist/config.d.ts.map +1 -0
  30. package/dist/config.js +221 -0
  31. package/dist/config.js.map +1 -0
  32. package/dist/data/ais.d.ts +27 -0
  33. package/dist/data/ais.d.ts.map +1 -0
  34. package/dist/data/ais.js +192 -0
  35. package/dist/data/ais.js.map +1 -0
  36. package/dist/data/codec.d.ts +16 -0
  37. package/dist/data/codec.d.ts.map +1 -0
  38. package/dist/data/codec.js +56 -0
  39. package/dist/data/codec.js.map +1 -0
  40. package/dist/data/envelope.d.ts +10 -0
  41. package/dist/data/envelope.d.ts.map +1 -0
  42. package/dist/data/envelope.js +53 -0
  43. package/dist/data/envelope.js.map +1 -0
  44. package/dist/data/inject.d.ts +12 -0
  45. package/dist/data/inject.d.ts.map +1 -0
  46. package/dist/data/inject.js +226 -0
  47. package/dist/data/inject.js.map +1 -0
  48. package/dist/data/merge.d.ts +36 -0
  49. package/dist/data/merge.d.ts.map +1 -0
  50. package/dist/data/merge.js +72 -0
  51. package/dist/data/merge.js.map +1 -0
  52. package/dist/data/snapshot.d.ts +10 -0
  53. package/dist/data/snapshot.d.ts.map +1 -0
  54. package/dist/data/snapshot.js +273 -0
  55. package/dist/data/snapshot.js.map +1 -0
  56. package/dist/data/static.d.ts +5 -0
  57. package/dist/data/static.d.ts.map +1 -0
  58. package/dist/data/static.js +148 -0
  59. package/dist/data/static.js.map +1 -0
  60. package/dist/data/types.d.ts +76 -0
  61. package/dist/data/types.d.ts.map +1 -0
  62. package/dist/data/types.js +34 -0
  63. package/dist/data/types.js.map +1 -0
  64. package/dist/data/values.d.ts +5 -0
  65. package/dist/data/values.d.ts.map +1 -0
  66. package/dist/data/values.js +15 -0
  67. package/dist/data/values.js.map +1 -0
  68. package/dist/groups/control.d.ts +61 -0
  69. package/dist/groups/control.d.ts.map +1 -0
  70. package/dist/groups/control.js +191 -0
  71. package/dist/groups/control.js.map +1 -0
  72. package/dist/groups/crypto.d.ts +9 -0
  73. package/dist/groups/crypto.d.ts.map +1 -0
  74. package/dist/groups/crypto.js +55 -0
  75. package/dist/groups/crypto.js.map +1 -0
  76. package/dist/groups/manager.d.ts +86 -0
  77. package/dist/groups/manager.d.ts.map +1 -0
  78. package/dist/groups/manager.js +717 -0
  79. package/dist/groups/manager.js.map +1 -0
  80. package/dist/groups/types.d.ts +134 -0
  81. package/dist/groups/types.d.ts.map +1 -0
  82. package/dist/groups/types.js +107 -0
  83. package/dist/groups/types.js.map +1 -0
  84. package/dist/identity.d.ts +26 -0
  85. package/dist/identity.d.ts.map +1 -0
  86. package/dist/identity.js +91 -0
  87. package/dist/identity.js.map +1 -0
  88. package/dist/index.d.ts +22 -0
  89. package/dist/index.d.ts.map +1 -0
  90. package/dist/index.js +22 -0
  91. package/dist/index.js.map +1 -0
  92. package/dist/live/capability.d.ts +22 -0
  93. package/dist/live/capability.d.ts.map +1 -0
  94. package/dist/live/capability.js +83 -0
  95. package/dist/live/capability.js.map +1 -0
  96. package/dist/live/client.d.ts +71 -0
  97. package/dist/live/client.d.ts.map +1 -0
  98. package/dist/live/client.js +304 -0
  99. package/dist/live/client.js.map +1 -0
  100. package/dist/live/directory.d.ts +35 -0
  101. package/dist/live/directory.d.ts.map +1 -0
  102. package/dist/live/directory.js +83 -0
  103. package/dist/live/directory.js.map +1 -0
  104. package/dist/live/message.d.ts +28 -0
  105. package/dist/live/message.d.ts.map +1 -0
  106. package/dist/live/message.js +143 -0
  107. package/dist/live/message.js.map +1 -0
  108. package/dist/live/protocol.d.ts +16 -0
  109. package/dist/live/protocol.d.ts.map +1 -0
  110. package/dist/live/protocol.js +39 -0
  111. package/dist/live/protocol.js.map +1 -0
  112. package/dist/live/publisher.d.ts +54 -0
  113. package/dist/live/publisher.d.ts.map +1 -0
  114. package/dist/live/publisher.js +379 -0
  115. package/dist/live/publisher.js.map +1 -0
  116. package/dist/live/relay.d.ts +106 -0
  117. package/dist/live/relay.d.ts.map +1 -0
  118. package/dist/live/relay.js +344 -0
  119. package/dist/live/relay.js.map +1 -0
  120. package/dist/live/topic.d.ts +5 -0
  121. package/dist/live/topic.d.ts.map +1 -0
  122. package/dist/live/topic.js +8 -0
  123. package/dist/live/topic.js.map +1 -0
  124. package/dist/peer/cli.d.ts +3 -0
  125. package/dist/peer/cli.d.ts.map +1 -0
  126. package/dist/peer/cli.js +159 -0
  127. package/dist/peer/cli.js.map +1 -0
  128. package/dist/peer/config.d.ts +33 -0
  129. package/dist/peer/config.d.ts.map +1 -0
  130. package/dist/peer/config.js +75 -0
  131. package/dist/peer/config.js.map +1 -0
  132. package/dist/plugin.d.ts +6 -0
  133. package/dist/plugin.d.ts.map +1 -0
  134. package/dist/plugin.js +909 -0
  135. package/dist/plugin.js.map +1 -0
  136. package/dist/policy/operator.d.ts +13 -0
  137. package/dist/policy/operator.d.ts.map +1 -0
  138. package/dist/policy/operator.js +53 -0
  139. package/dist/policy/operator.js.map +1 -0
  140. package/dist/policy/policy.d.ts +49 -0
  141. package/dist/policy/policy.d.ts.map +1 -0
  142. package/dist/policy/policy.js +147 -0
  143. package/dist/policy/policy.js.map +1 -0
  144. package/dist/security/attestor.d.ts +10 -0
  145. package/dist/security/attestor.d.ts.map +1 -0
  146. package/dist/security/attestor.js +24 -0
  147. package/dist/security/attestor.js.map +1 -0
  148. package/dist/security/claim.d.ts +25 -0
  149. package/dist/security/claim.d.ts.map +1 -0
  150. package/dist/security/claim.js +159 -0
  151. package/dist/security/claim.js.map +1 -0
  152. package/dist/security/control.d.ts +38 -0
  153. package/dist/security/control.d.ts.map +1 -0
  154. package/dist/security/control.js +117 -0
  155. package/dist/security/control.js.map +1 -0
  156. package/dist/security/registry.d.ts +70 -0
  157. package/dist/security/registry.d.ts.map +1 -0
  158. package/dist/security/registry.js +315 -0
  159. package/dist/security/registry.js.map +1 -0
  160. package/docs/plans/README.md +73 -0
  161. package/docs/plans/architecture.md +243 -0
  162. package/docs/plans/data-and-injection.md +392 -0
  163. package/docs/plans/networks.md +483 -0
  164. package/docs/plans/peer-node.md +226 -0
  165. package/docs/plans/security.md +364 -0
  166. package/docs/plans/shared-data.md +476 -0
  167. package/docs/plans/spike-findings.md +148 -0
  168. package/docs/plans/v1-design.md +304 -0
  169. package/icon.svg +24 -0
  170. package/package.json +108 -4
  171. package/policy/default.json +30 -0
  172. package/policy/operator.pub +2 -0
  173. package/public/icon.svg +24 -0
  174. package/public/index.html +818 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,91 @@
1
+ # Changelog
2
+
3
+ ## 0.4.0 — 2026-11-06
4
+
5
+ - Add a signed, versioned network policy for sharding, election windows, public
6
+ publish-rate caps, AIS caps and protocol compatibility. A signed default ships
7
+ with the package; newer signed policies received over the mesh override it and
8
+ are cached. Clients cannot override topology/rate limits locally.
9
+ - Add the network-operator key tooling and a pinned default operator public key;
10
+ the standalone peer can verify and republish a signed policy file.
11
+ - Safer defaults: public network is receive-only, AIS is receive-only/private,
12
+ and new installs must opt in before transmitting.
13
+ - Add a per-data-set sharing matrix in the webapp: Public plus every active group
14
+ as columns, with checkboxes and no manual group IDs.
15
+ - Add group publish-rate caps set by group admins, with per-member rates inside
16
+ the cap (supports 1–2 Hz small groups).
17
+ - Move advanced/sharing/security/topology settings into a plugin-owned
18
+ `advanced.json` so the simplified Signal K config form cannot drop them; the
19
+ form now exposes only relay and received-vessel toggles.
20
+ - Hide identity, claims and mesh details behind an Advanced disclosure in the
21
+ webapp, and hide empty join-request/proposal sections.
22
+
23
+ ## 0.3.0 — 2026-11-06
24
+
25
+ - Add a Public network card to the webapp with status, peers/elected relay and
26
+ per-data-set public sharing toggles. Toggles persist to the plugin
27
+ configuration and apply live.
28
+
29
+ ## 0.2.2 — 2026-11-06
30
+
31
+ - Render the identity/status panel as readable fields instead of a JSON blob.
32
+ - Report the package version at runtime; the status was hard-coded to 0.1.0.
33
+
34
+ ## 0.2.1 — 2026-11-06
35
+
36
+ - Fix the webapp API base to the actual plugin route
37
+ (`/plugins/signalk-p2p-plugin`), which was returning HTTP 404.
38
+
39
+ ## 0.2.0 — 2026-11-02
40
+
41
+ - The admin interface is now a Signal K webapp, listed under Webapps while the
42
+ plugin is enabled. The admin-gated `/plugins/signalk-p2p-plugin/admin` route remains.
43
+
44
+ ## 0.1.1 — 2026-11-02
45
+
46
+ Fix the Windows path assertion in the peer config test; no runtime changes.
47
+
48
+ ## 0.1.0 — 2026-11-02
49
+
50
+ First public release. Validated over WAN through a VPS peer; not yet validated
51
+ on real boats or Starlink links.
52
+
53
+ - Design plans under `docs/plans/`.
54
+ - Repository scaffold: TypeScript ESM plugin, identity, configuration schema,
55
+ snapshot/static codecs, and merge rules.
56
+ - Spike harness for payload size and Hypercore replication measurements.
57
+ - Standalone Node.js peer (`signalk-p2p-peer`) with Hyperswarm discovery,
58
+ Protomux live channel, batching, history replay and a systemd deployment.
59
+ - Live path in the plugin: self snapshots/static/depth publishing, LiveMessage
60
+ batching, and injection of remote vessels with loop prevention.
61
+ - Ed25519-signed LiveMessages with receiver verification; unsigned and tampered
62
+ messages are rejected.
63
+ - Public claim registry: persisted `selfId → key` claims, attestor-signed
64
+ attestations/revocations, TOFU fallback, and receiver authorization.
65
+ - Admin attestor API (`/identity`, `/claims`, `/claims/attest`,
66
+ `/claims/revoke`) and a configurable attestation threshold.
67
+ - Peer election: signed capability advertisements, weighted rendezvous epochs,
68
+ relay advertisement, status reporting and a WAN smoke test.
69
+ - Routing enforcement: clients target the elected aggregator, only it forwards,
70
+ with deduplication and a full-mesh fallback.
71
+ - Private groups: X25519 box keys, signed roster snapshots, invite tokens, join
72
+ requests and admin approval with selfId/MMSI uniqueness, AES-256-GCM group data,
73
+ and removal with epoch rekey. Admin group API and a network smoke test.
74
+ - Standalone peer group relay via `--group-invite`: joins the roster, forwards
75
+ encrypted group data and follows rekeys.
76
+ - AIS sharing: collects locally heard targets only, supports the four modes,
77
+ caps to the nearest targets, publishes observation records, and drops AIS
78
+ observations in favour of fresh self records.
79
+ - Roster/attestor hardening: attestation signatures are persisted and revalidated,
80
+ expired or retired attestors no longer count, group invites are single-use, and
81
+ viewers cannot publish.
82
+ - Multi-admin quorum: multi-signature roster proposals, approval and threshold
83
+ APIs, and serialized group persistence.
84
+ - Roster catch-up requests and a minimal admin page for claims, groups,
85
+ join requests and proposals.
86
+ - Extended shared data: magnetic course/heading, variation, attitude, rate of
87
+ turn, speed through water and GNSS DOP/satellites in the snapshot; environment,
88
+ tanks, destination, anchor, propulsion and systems in a change-triggered Values
89
+ record.
90
+ - WAN validation through a VPS peer, plus `smoke:client` and `smoke:plugin`
91
+ scripts.
package/LICENSE ADDED
@@ -0,0 +1,201 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work
38
+ (an example is provided in the Appendix below).
39
+
40
+ "Derivative Works" shall mean any work, whether in Source or Object
41
+ form, that is based on (or derived from) the Work and for which the
42
+ editorial revisions, annotations, elaborations, or other modifications
43
+ represent, as a whole, an original work of authorship. For the purposes
44
+ of this License, Derivative Works shall not include works that remain
45
+ separable from, or merely link (or bind by name) to the interfaces of,
46
+ the Work and Derivative Works thereof.
47
+
48
+ "Contribution" shall mean any work of authorship, including
49
+ the original version of the Work and any modifications or additions
50
+ to that Work or Derivative Works thereof, that is intentionally
51
+ submitted to Licensor for inclusion in the Work by the copyright owner
52
+ or by an individual or Legal Entity authorized to submit on behalf of
53
+ the copyright owner. For the purposes of this definition, "submitted"
54
+ means any form of electronic, verbal, or written communication sent
55
+ to the Licensor or its representatives, including but not limited to
56
+ communication on electronic mailing lists, source code control systems,
57
+ and issue tracking systems that are managed by, or on behalf of, the
58
+ Licensor for the purpose of discussing and improving the Work, but
59
+ excluding communication that is conspicuously marked or otherwise
60
+ designated in writing by the copyright owner as "Not a Contribution."
61
+
62
+ "Contributor" shall mean Licensor and any individual or Legal Entity
63
+ on behalf of whom a Contribution has been received by Licensor and
64
+ subsequently incorporated within the Work.
65
+
66
+ 2. Grant of Copyright License. Subject to the terms and conditions of
67
+ this License, each Contributor hereby grants to You a perpetual,
68
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69
+ copyright license to reproduce, prepare Derivative Works of,
70
+ publicly display, publicly perform, sublicense, and distribute the
71
+ Work and such Derivative Works in Source or Object form.
72
+
73
+ 3. Grant of Patent License. Subject to the terms and conditions of
74
+ this License, each Contributor hereby grants to You a perpetual,
75
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76
+ (except as stated in this section) patent license to make, have made,
77
+ use, offer to sell, sell, import, and otherwise transfer the Work,
78
+ where such license applies only to those patent claims licensable
79
+ by such Contributor that are necessarily infringed by their
80
+ Contribution(s) alone or by combination of their Contribution(s)
81
+ with the Work to which such Contribution(s) was submitted. If You
82
+ institute patent litigation against any entity (including a
83
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
84
+ or a Contribution incorporated within the Work constitutes direct
85
+ or contributory patent infringement, then any patent licenses
86
+ granted to You under this License for that Work shall terminate
87
+ as of the date such litigation is filed.
88
+
89
+ 4. Redistribution. You may reproduce and distribute copies of the
90
+ Work or Derivative Works thereof in any medium, with or without
91
+ modifications, and in Source or Object form, provided that You
92
+ meet the following conditions:
93
+
94
+ (a) You must give any other recipients of the Work or
95
+ Derivative Works a copy of this License; and
96
+
97
+ (b) You must cause any modified files to carry prominent notices
98
+ stating that You changed the files; and
99
+
100
+ (c) You must retain, in the Source form of any Derivative Works
101
+ that You distribute, all copyright, patent, trademark, and
102
+ attribution notices from the Source form of the Work,
103
+ excluding those notices that do not pertain to any part of
104
+ the Derivative Works; and
105
+
106
+ (d) If the Work includes a "NOTICE" text file as part of its
107
+ distribution, then any Derivative Works that You distribute must
108
+ include a readable copy of the attribution notices contained
109
+ within such NOTICE file, excluding those notices that do not
110
+ pertain to any part of the Derivative Works, in at least one
111
+ of the following places: within a NOTICE text file distributed
112
+ as part of the Derivative Works; within the Source form or
113
+ documentation, if provided along with the Derivative Works; or,
114
+ within a display generated by the Derivative Works, if and
115
+ wherever such third-party notices normally appear. The contents
116
+ of the NOTICE file are for informational purposes only and
117
+ do not modify the License. You may add Your own attribution
118
+ notices within Derivative Works that You distribute, alongside
119
+ or as an addendum to the NOTICE text from the Work, provided
120
+ that such additional attribution notices cannot be construed
121
+ as modifying the License.
122
+
123
+ You may add Your own copyright statement to Your modifications and
124
+ may provide additional or different license terms and conditions
125
+ for use, reproduction, or distribution of Your modifications, or
126
+ for any such Derivative Works as a whole, provided Your use,
127
+ reproduction, and distribution of the Work otherwise complies with
128
+ the conditions stated in this License.
129
+
130
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
131
+ any Contribution intentionally submitted for inclusion in the Work
132
+ by You to the Licensor shall be under the terms and conditions of
133
+ this License, without any additional terms or conditions.
134
+ Notwithstanding the above, nothing herein shall supersede or modify
135
+ the terms of any separate license agreement you may have executed
136
+ with Licensor regarding such Contributions.
137
+
138
+ 6. Trademarks. This License does not grant permission to use the trade
139
+ names, trademarks, service marks, or product names of the Licensor,
140
+ except as required for reasonable and customary use in describing the
141
+ origin of the Work and reproducing the content of the NOTICE file.
142
+
143
+ 7. Disclaimer of Warranty. Unless required by applicable law or
144
+ agreed to in writing, Licensor provides the Work (and each
145
+ Contributor provides its Contributions) on an "AS IS" BASIS,
146
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147
+ implied, including, without limitation, any warranties or conditions
148
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149
+ PARTICULAR PURPOSE. You are solely responsible for determining the
150
+ appropriateness of using or redistributing the Work and assume any
151
+ risks associated with Your exercise of permissions under this License.
152
+
153
+ 8. Limitation of Liability. In no event and under no legal theory,
154
+ whether in tort (including negligence), contract, or otherwise,
155
+ unless required by applicable law (such as deliberate and grossly
156
+ negligent acts) or agreed to in writing, shall any Contributor be
157
+ liable to You for damages, including any direct, indirect, special,
158
+ incidental, or consequential damages of any character arising as a
159
+ result of this License or out of the use or inability to use the
160
+ Work (including but not limited to damages for loss of goodwill,
161
+ work stoppage, computer failure or malfunction, or any and all
162
+ other commercial damages or losses), even if such Contributor
163
+ has been advised of the possibility of such damages.
164
+
165
+ 9. Accepting Warranty or Additional Liability. While redistributing
166
+ the Work or Derivative Works thereof, You may choose to offer,
167
+ and charge a fee for, acceptance of support, warranty, indemnity,
168
+ or other liability obligations and/or rights consistent with this
169
+ License. However, in accepting such obligations, You may act only
170
+ on Your own behalf and on Your sole responsibility, not on behalf
171
+ of any other Contributor, and only if You agree to indemnify,
172
+ defend, and hold each Contributor harmless for any liability
173
+ incurred by, or claims asserted against, such Contributor by reason
174
+ of your accepting any such warranty or additional liability.
175
+
176
+ END OF TERMS AND CONDITIONS
177
+
178
+ APPENDIX: How to apply the Apache License to your work.
179
+
180
+ To apply the Apache License to your work, attach the following
181
+ boilerplate notice, with the fields enclosed by brackets "[]"
182
+ replaced with your own identifying information. (Don't include
183
+ the brackets!) The text should be enclosed in the appropriate
184
+ comment syntax for the file format. We also recommend that a
185
+ file or class name and description of purpose be included on the
186
+ same "printed page" as the copyright notice for easier
187
+ identification within third-party archives.
188
+
189
+ Copyright [yyyy] [name of copyright owner]
190
+
191
+ Licensed under the Apache License, Version 2.0 (the "License");
192
+ you may not use this file except in compliance with the License.
193
+ You may obtain a copy of the License at
194
+
195
+ http://www.apache.org/licenses/LICENSE-2.0
196
+
197
+ Unless required by applicable law or agreed to in writing, software
198
+ distributed under the License is distributed on an "AS IS" BASIS,
199
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200
+ See the License for the specific language governing permissions and
201
+ limitations under the License.
package/README.md CHANGED
@@ -1,3 +1,129 @@
1
- # Temporary Holding Version
1
+ # Signal K P2P
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ **Peer-to-peer vessel data between Signal K instances.** One global public mesh,
4
+ joined by default, plus any number of private, encrypted groups.
5
+
6
+ > **Status: v0.4.0.** The core path
7
+ > (publish → relay → inject) and the security, election, group and AIS features
8
+ > are implemented and validated over WAN through a VPS peer. It has not yet been
9
+ > validated on real boats or Starlink links; treat this release as a field-test
10
+ > candidate.
11
+
12
+ ## Features
13
+
14
+ - Share position, navigation (including magnetic course/heading, attitude, rate of
15
+ turn, speed through water and GNSS DOP/satellites), depth, environment, tanks,
16
+ destination, anchor, propulsion and systems, per network.
17
+ - Join the global `all-vessels` network automatically, but transmit only after
18
+ opting in (receive-only by default; four consent modes).
19
+ - Create private groups with encrypted data, invite links, roles, admin-approved
20
+ MMSIs, member removal and key rotation.
21
+ - Carry other vessels you hear over AIS into a shared map, with four AIS modes and
22
+ nearest-target caps; AIS observations are never re-published.
23
+ - Signed messages, claim/attestation authorization, and one authorized writer per
24
+ vessel context, so a peer can never overwrite another vessel's data.
25
+ - Central, signed **network policy** for sharding, election windows, publish
26
+ rate caps and AIS caps. Individual clients cannot override topology tuning.
27
+ - Relay through elected peers with no fixed relays, plus an optional standalone
28
+ Node.js peer for a VPS bootstrap when most boats are behind CGNAT.
29
+ - An admin webapp with a per-data-set sharing matrix: Public and each active
30
+ group are columns, so there is no typing of group IDs. Group admins set a
31
+ publish-rate cap; members choose their own rate within it.
32
+ - The webapp appears under **Webapps** while the plugin is enabled, and is also
33
+ served at `/plugins/signalk-p2p-plugin/admin` (admin login required).
34
+
35
+ ## Install
36
+
37
+ From the Signal K App Store: search for **Signal K P2P**, install, restart the
38
+ server, then enable the plugin. Or install into the server's configuration
39
+ directory:
40
+
41
+ ```bash
42
+ cd ~/.signalk
43
+ npm install signalk-p2p-plugin
44
+ ```
45
+
46
+ Requires Node `>=22.5` (a Signal K server on Node 22.5 or newer).
47
+
48
+ After enabling the plugin, open **Signal K P2P** from the Webapps menu. The UI
49
+ calls the admin-gated API, so you must be signed in as an administrator.
50
+
51
+ Default sharing is conservative: the public network is **receive-only**, so no
52
+ vessel data is transmitted until you choose a sharing mode in the webapp. AIS is
53
+ receive-only/private by default. Identity, position, navigation and depth are
54
+ pre-selected when you opt in; environment, tanks, destination, anchor,
55
+ propulsion and systems stay off until enabled. See
56
+ [`shared-data.md`](docs/plans/shared-data.md).
57
+
58
+ ## Standalone peer
59
+
60
+ Run a relay on a VPS or always-on host when most boats are behind CGNAT:
61
+
62
+ ```bash
63
+ npm install -g signalk-p2p-plugin
64
+ signalk-p2p-peer --help
65
+ ```
66
+
67
+ See [`deploy/README.md`](deploy/README.md) for the systemd unit, an example
68
+ configuration, and how to publish a signed network policy.
69
+
70
+ ## Admin and network policy
71
+
72
+ The Signal K plugin config form intentionally exposes only two safe toggles:
73
+ **Help relay nearby vessels** and **Show vessels received from the network**.
74
+ Everything else lives in the plugin-owned `advanced.json` (in the plugin data
75
+ directory), including sharing, consent, AIS, security and topology settings.
76
+ This keeps the form simple and prevents a form save from dropping advanced
77
+ settings.
78
+
79
+ Network-wide settings are not user-editable. A **network policy** is signed by
80
+ the network operator and distributed as:
81
+
82
+ - a signed default policy shipped in the package, and
83
+ - newer signed policies received over the mesh (live wins).
84
+
85
+ The operator key public key is
86
+ `b393c24608f23cdb389cfb0cbc8c9de619345fa110cdddcb14ab6afdb494db09`
87
+ (fingerprint `254375e336e45f93bb5691e49fdb4e758fefed7981940d98dc9773b8b23390bf`).
88
+ The private key is stored outside the repository at
89
+ `~/.config/signalk-p2p/operator/operator.json` (mode 0600); distribute the public
90
+ key and signed policy files, never the private key. Use
91
+ `scripts/sign-policy.ts` to sign a new policy.
92
+
93
+ ## Design
94
+
95
+ | Document | Contents |
96
+ | ----------------------------------------------------------- | ----------------------------------------------- |
97
+ | [`architecture.md`](docs/plans/architecture.md) | Stack, live/durable split, identity, invariants |
98
+ | [`shared-data.md`](docs/plans/shared-data.md) | Data sets, defaults, rates, AIS modes |
99
+ | [`networks.md`](docs/plans/networks.md) | Public mesh, adaptive sharding, groups |
100
+ | [`security.md`](docs/plans/security.md) | Write authorization, claims, MMSI verification |
101
+ | [`data-and-injection.md`](docs/plans/data-and-injection.md) | Wire records, merge, injection |
102
+ | [`v1-design.md`](docs/plans/v1-design.md) | Build order, spike, risks |
103
+ | [`spike-findings.md`](docs/plans/spike-findings.md) | Measured payload and replication costs |
104
+ | [`peer-node.md`](docs/plans/peer-node.md) | Standalone Node.js peer / VPS relay |
105
+
106
+ ## Development
107
+
108
+ ```bash
109
+ npm install
110
+ npm run build # TypeScript -> dist/
111
+ npm test # vitest
112
+ npm run peer # standalone peer/relay (dev)
113
+ npm run peer:start # compiled standalone peer
114
+ npm run smoke:client # connect to a running peer (-- --listen to observe)
115
+ npm run smoke:plugin # two mock Signal K instances through the live path
116
+ npm run smoke:election # collect capabilities and print the elected relay
117
+ npm run smoke:group # full group lifecycle over the network
118
+ npm run spike # payload + replication measurements
119
+ npm run spike:swarm # Hyperswarm idle/payload measurement
120
+ npm run format
121
+ npm run lint
122
+ ```
123
+
124
+ To deploy the standalone peer on a VPS, see
125
+ [`deploy/README.md`](deploy/README.md).
126
+
127
+ ## License
128
+
129
+ Licensed under the [Apache License, Version 2.0](LICENSE).
@@ -0,0 +1,101 @@
1
+ # Deploying a standalone peer
2
+
3
+ A peer is an ordinary Hyperswarm peer. It is useful on an always-on, reachable
4
+ host (a VPS, a marina server, a club box) so boats behind CGNAT can reach the
5
+ mesh. It is not a central authority and can be replaced by an elected peer.
6
+
7
+ Tested on Fedora 44 with Node 22.23.1.
8
+
9
+ ## 1. Install Node
10
+
11
+ Node `>=22.5` is required. On Fedora:
12
+
13
+ ```bash
14
+ dnf -y install nodejs npm
15
+ node --version
16
+ ```
17
+
18
+ ## 2. Install the package
19
+
20
+ From a checkout, build a tarball and install it into `/opt`:
21
+
22
+ ```bash
23
+ npm pack
24
+ scp signalk-p2p-plugin-*.tgz root@your-host:/tmp/
25
+ ```
26
+
27
+ On the host:
28
+
29
+ ```bash
30
+ id -u signalk-p2p >/dev/null 2>&1 || \
31
+ useradd --system --home-dir /var/lib/signalk-p2p --shell /sbin/nologin signalk-p2p
32
+ install -d -o signalk-p2p -g signalk-p2p /opt/signalk-p2p /var/lib/signalk-p2p
33
+ install -d /etc/signalk-p2p
34
+ cd /opt/signalk-p2p
35
+ npm init -y
36
+ npm install --omit=dev /tmp/signalk-p2p-plugin-*.tgz
37
+ chown -R signalk-p2p:signalk-p2p /opt/signalk-p2p /var/lib/signalk-p2p
38
+ ```
39
+
40
+ ## 3. Configure and run
41
+
42
+ ```bash
43
+ cp deploy/peer.example.json /etc/signalk-p2p/peer.json
44
+ cp deploy/signalk-p2p-peer.service /etc/systemd/system/
45
+ systemctl daemon-reload
46
+ systemctl enable --now signalk-p2p-peer
47
+ journalctl -u signalk-p2p-peer -f
48
+ ```
49
+
50
+ The peer prints its identity fingerprint and the topic it joined. The Ed25519
51
+ identity is created in `/var/lib/signalk-p2p/identity/ed25519.pem` (mode 0600).
52
+
53
+ ## 4. Publish the network policy (optional)
54
+
55
+ A peer can distribute the signed public-network policy. It verifies the
56
+ signature with the pinned operator key and republishes it every five minutes; it
57
+ never needs the operator private key.
58
+
59
+ ```bash
60
+ cp deploy/policy.json /etc/signalk-p2p/policy.json
61
+ # add this key to /etc/signalk-p2p/peer.json:
62
+ # "policyFile": "/etc/signalk-p2p/policy.json"
63
+ systemctl restart signalk-p2p-peer
64
+ journalctl -u signalk-p2p-peer -n 20 | grep policy
65
+ ```
66
+
67
+ Sign a new policy with `scripts/sign-policy.ts` from a checkout, then copy the
68
+ signed file and restart the peer. Clients keep the newest valid policy they have
69
+ seen, so they continue to use it if the publisher is offline.
70
+
71
+ ## 5. Firewall
72
+
73
+ Hyperswarm uses UDP. If you set `"port": 49737`, allow UDP 49737 inbound so other
74
+ peers can dial it:
75
+
76
+ ```bash
77
+ firewall-cmd --permanent --add-port=49737/udp
78
+ firewall-cmd --reload
79
+ ```
80
+
81
+ Without a fixed port the DHT uses an ephemeral UDP port; outbound UDP must still
82
+ be allowed. No TCP is required.
83
+
84
+ ## 6. Private group relay
85
+
86
+ Add `"groupInvites": ["<token>"]` to the config (or pass `--group-invite <token>`)
87
+ to join and relay a private group. The peer sends a join request from its
88
+ synthetic selfId; an admin must approve it (a `viewer` role is enough, because a
89
+ relay does not publish vessel data).
90
+
91
+ ## 7. Verify
92
+
93
+ From another machine on a different network:
94
+
95
+ ```bash
96
+ npm run smoke:client -- --listen # in one terminal
97
+ npm run smoke:client # in another
98
+ ```
99
+
100
+ The listener should print the sender's `smoke-…` batch. This exercises public DHT
101
+ discovery, NAT traversal, the Protomux live channel, and relay forwarding.
@@ -0,0 +1,9 @@
1
+ {
2
+ "dataDir": "/var/lib/signalk-p2p",
3
+ "topic": "signalk-p2p/all-vessels/v1",
4
+ "batchIntervalMs": 2000,
5
+ "maxBatchBytes": 65536,
6
+ "historyBatches": 10,
7
+ "port": 49737,
8
+ "groupInvites": []
9
+ }
@@ -0,0 +1,30 @@
1
+ {
2
+ "policy": {
3
+ "version": 2,
4
+ "topic": "signalk-p2p/all-vessels/v1",
5
+ "protocol": 1,
6
+ "issuedAt": 1794023623,
7
+ "sharding": {
8
+ "maxVesselsPerShard": 500,
9
+ "maxVesselsPerInstance": 1000,
10
+ "lookAheadKm": 50,
11
+ "splitSettleMinutes": 10,
12
+ "mergeSettleMinutes": 60,
13
+ "mergeBelowRatio": 0.25,
14
+ "boundaryHysteresisMeters": 1000
15
+ },
16
+ "election": {
17
+ "epochMinutes": 10,
18
+ "minUptimeMinutes": 10
19
+ },
20
+ "rates": {
21
+ "maxSnapshotHzUnderway": 0.05,
22
+ "maxSnapshotHzMoored": 0.01
23
+ },
24
+ "ais": {
25
+ "maxTargets": 100,
26
+ "maxRateHz": 0.02
27
+ }
28
+ },
29
+ "signature": "VKtZkIvKsyt3RwQWwvF1K6GP8Oh/tODyERYMAVWPMjH8UgN0TztN8LOhY/KpGpfBo3OTO0ktQf04zVPZhuUcDw=="
30
+ }
@@ -0,0 +1,23 @@
1
+ [Unit]
2
+ Description=Signal K P2P peer
3
+ After=network-online.target
4
+ Wants=network-online.target
5
+
6
+ [Service]
7
+ Type=simple
8
+ User=signalk-p2p
9
+ Group=signalk-p2p
10
+ WorkingDirectory=/var/lib/signalk-p2p
11
+ ExecStart=/opt/signalk-p2p/node_modules/.bin/signalk-p2p-peer --config /etc/signalk-p2p/peer.json
12
+ Restart=always
13
+ RestartSec=5
14
+ # Remove DEBUG in production; keep it while validating peer connections.
15
+ Environment=DEBUG=1
16
+ NoNewPrivileges=true
17
+ ProtectSystem=strict
18
+ ProtectHome=true
19
+ ReadWritePaths=/var/lib/signalk-p2p
20
+ LimitNOFILE=65536
21
+
22
+ [Install]
23
+ WantedBy=multi-user.target
@@ -0,0 +1,7 @@
1
+ /**
2
+ * The admin UI is served both by the admin-gated plugin router at
3
+ * `/plugins/signalk-p2p-plugin/admin` and as the Signal K webapp at
4
+ * `/signalk-p2p-plugin/`. `public/index.html` is the single source.
5
+ */
6
+ export declare const ADMIN_PAGE: string;
7
+ //# sourceMappingURL=admin-page.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"admin-page.d.ts","sourceRoot":"","sources":["../src/admin-page.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,eAAO,MAAM,UAAU,QAGtB,CAAC"}
@@ -0,0 +1,8 @@
1
+ import { readFileSync } from "node:fs";
2
+ /**
3
+ * The admin UI is served both by the admin-gated plugin router at
4
+ * `/plugins/signalk-p2p-plugin/admin` and as the Signal K webapp at
5
+ * `/signalk-p2p-plugin/`. `public/index.html` is the single source.
6
+ */
7
+ export const ADMIN_PAGE = readFileSync(new URL("../public/index.html", import.meta.url), "utf8");
8
+ //# sourceMappingURL=admin-page.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"admin-page.js","sourceRoot":"","sources":["../src/admin-page.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,YAAY,CACpC,IAAI,GAAG,CAAC,sBAAsB,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,EAChD,MAAM,CACP,CAAC"}
@@ -0,0 +1,11 @@
1
+ import type { Config } from "./config.js";
2
+ export declare const ADVANCED_CONFIG_FILE = "advanced.json";
3
+ /**
4
+ * Advanced settings live outside the Signal K plugin configuration form so a
5
+ * form save cannot drop them. The form owns only the simple relay/injection
6
+ * toggles; sharing, network consent, AIS, security and topology stay here.
7
+ */
8
+ export declare function loadAdvancedConfig(dataDir: string, legacy: Partial<Config>): Partial<Config>;
9
+ export declare function mergeSimpleConfig(advanced: Partial<Config>, simple: Partial<Config>): Partial<Config>;
10
+ export declare function saveAdvancedConfig(dataDir: string, config: Config): void;
11
+ //# sourceMappingURL=advanced-config.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"advanced-config.d.ts","sourceRoot":"","sources":["../src/advanced-config.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AAEpD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,GACtB,OAAO,CAAC,MAAM,CAAC,CAgBjB;AAED,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,EACzB,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,GACtB,OAAO,CAAC,MAAM,CAAC,CAYjB;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAOxE"}