@labacacia/nps-sdk 1.0.0-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (311) hide show
  1. package/CONTRIBUTING.md +33 -0
  2. package/LICENSE +170 -0
  3. package/NOTICE +7 -0
  4. package/README.md +153 -0
  5. package/dist/codec-CmHeovTV.d.cts +120 -0
  6. package/dist/codec-CmHeovTV.d.ts +120 -0
  7. package/dist/core/anchor-cache.d.ts +42 -0
  8. package/dist/core/anchor-cache.d.ts.map +1 -0
  9. package/dist/core/anchor-cache.js +104 -0
  10. package/dist/core/anchor-cache.js.map +1 -0
  11. package/dist/core/cache.d.ts +14 -0
  12. package/dist/core/cache.d.ts.map +1 -0
  13. package/dist/core/cache.js +80 -0
  14. package/dist/core/cache.js.map +1 -0
  15. package/dist/core/canonical-json.d.ts +12 -0
  16. package/dist/core/canonical-json.d.ts.map +1 -0
  17. package/dist/core/canonical-json.js +44 -0
  18. package/dist/core/canonical-json.js.map +1 -0
  19. package/dist/core/codec.d.ts +32 -0
  20. package/dist/core/codec.d.ts.map +1 -0
  21. package/dist/core/codec.js +119 -0
  22. package/dist/core/codec.js.map +1 -0
  23. package/dist/core/codecs/index.d.ts +4 -0
  24. package/dist/core/codecs/index.d.ts.map +1 -0
  25. package/dist/core/codecs/index.js +6 -0
  26. package/dist/core/codecs/index.js.map +1 -0
  27. package/dist/core/codecs/ncp-codec.d.ts +39 -0
  28. package/dist/core/codecs/ncp-codec.d.ts.map +1 -0
  29. package/dist/core/codecs/ncp-codec.js +93 -0
  30. package/dist/core/codecs/ncp-codec.js.map +1 -0
  31. package/dist/core/codecs/tier1-json-codec.d.ts +10 -0
  32. package/dist/core/codecs/tier1-json-codec.d.ts.map +1 -0
  33. package/dist/core/codecs/tier1-json-codec.js +28 -0
  34. package/dist/core/codecs/tier1-json-codec.js.map +1 -0
  35. package/dist/core/codecs/tier2-msgpack-codec.d.ts +10 -0
  36. package/dist/core/codecs/tier2-msgpack-codec.d.ts.map +1 -0
  37. package/dist/core/codecs/tier2-msgpack-codec.js +26 -0
  38. package/dist/core/codecs/tier2-msgpack-codec.js.map +1 -0
  39. package/dist/core/crypto-provider.d.ts +31 -0
  40. package/dist/core/crypto-provider.d.ts.map +1 -0
  41. package/dist/core/crypto-provider.js +10 -0
  42. package/dist/core/crypto-provider.js.map +1 -0
  43. package/dist/core/exceptions.d.ts +27 -0
  44. package/dist/core/exceptions.d.ts.map +1 -0
  45. package/dist/core/exceptions.js +52 -0
  46. package/dist/core/exceptions.js.map +1 -0
  47. package/dist/core/frame-header.d.ts +87 -0
  48. package/dist/core/frame-header.d.ts.map +1 -0
  49. package/dist/core/frame-header.js +185 -0
  50. package/dist/core/frame-header.js.map +1 -0
  51. package/dist/core/frame-registry.d.ts +35 -0
  52. package/dist/core/frame-registry.d.ts.map +1 -0
  53. package/dist/core/frame-registry.js +63 -0
  54. package/dist/core/frame-registry.js.map +1 -0
  55. package/dist/core/frames.d.ts +80 -0
  56. package/dist/core/frames.d.ts.map +1 -0
  57. package/dist/core/frames.js +153 -0
  58. package/dist/core/frames.js.map +1 -0
  59. package/dist/core/index.cjs +371 -0
  60. package/dist/core/index.cjs.map +1 -0
  61. package/dist/core/index.d.cts +41 -0
  62. package/dist/core/index.d.ts +9 -0
  63. package/dist/core/index.d.ts.map +1 -0
  64. package/dist/core/index.js +10 -0
  65. package/dist/core/index.js.map +1 -0
  66. package/dist/core/registry.d.ts +11 -0
  67. package/dist/core/registry.d.ts.map +1 -0
  68. package/dist/core/registry.js +17 -0
  69. package/dist/core/registry.js.map +1 -0
  70. package/dist/core/status-codes.d.ts +28 -0
  71. package/dist/core/status-codes.d.ts.map +1 -0
  72. package/dist/core/status-codes.js +38 -0
  73. package/dist/core/status-codes.js.map +1 -0
  74. package/dist/frames-B3qLdl_g.d.cts +77 -0
  75. package/dist/frames-Ff7-ZPUl.d.ts +77 -0
  76. package/dist/index.cjs +1556 -0
  77. package/dist/index.cjs.map +1 -0
  78. package/dist/index.d.cts +21 -0
  79. package/dist/index.d.ts +2 -0
  80. package/dist/index.d.ts.map +1 -0
  81. package/dist/index.js +10 -0
  82. package/dist/index.js.map +1 -0
  83. package/dist/ncp/frames/anchor-frame.d.ts +29 -0
  84. package/dist/ncp/frames/anchor-frame.d.ts.map +1 -0
  85. package/dist/ncp/frames/anchor-frame.js +54 -0
  86. package/dist/ncp/frames/anchor-frame.js.map +1 -0
  87. package/dist/ncp/frames/caps-frame.d.ts +29 -0
  88. package/dist/ncp/frames/caps-frame.d.ts.map +1 -0
  89. package/dist/ncp/frames/caps-frame.js +29 -0
  90. package/dist/ncp/frames/caps-frame.js.map +1 -0
  91. package/dist/ncp/frames/diff-frame.d.ts +32 -0
  92. package/dist/ncp/frames/diff-frame.d.ts.map +1 -0
  93. package/dist/ncp/frames/diff-frame.js +37 -0
  94. package/dist/ncp/frames/diff-frame.js.map +1 -0
  95. package/dist/ncp/frames/error-frame.d.ts +16 -0
  96. package/dist/ncp/frames/error-frame.d.ts.map +1 -0
  97. package/dist/ncp/frames/error-frame.js +13 -0
  98. package/dist/ncp/frames/error-frame.js.map +1 -0
  99. package/dist/ncp/frames/hello-frame.d.ts +21 -0
  100. package/dist/ncp/frames/hello-frame.d.ts.map +1 -0
  101. package/dist/ncp/frames/hello-frame.js +25 -0
  102. package/dist/ncp/frames/hello-frame.js.map +1 -0
  103. package/dist/ncp/frames/stream-frame.d.ts +16 -0
  104. package/dist/ncp/frames/stream-frame.d.ts.map +1 -0
  105. package/dist/ncp/frames/stream-frame.js +18 -0
  106. package/dist/ncp/frames/stream-frame.js.map +1 -0
  107. package/dist/ncp/frames.d.ts +76 -0
  108. package/dist/ncp/frames.d.ts.map +1 -0
  109. package/dist/ncp/frames.js +147 -0
  110. package/dist/ncp/frames.js.map +1 -0
  111. package/dist/ncp/handshake.d.ts +30 -0
  112. package/dist/ncp/handshake.d.ts.map +1 -0
  113. package/dist/ncp/handshake.js +80 -0
  114. package/dist/ncp/handshake.js.map +1 -0
  115. package/dist/ncp/index.cjs +188 -0
  116. package/dist/ncp/index.cjs.map +1 -0
  117. package/dist/ncp/index.d.cts +6 -0
  118. package/dist/ncp/index.d.ts +11 -0
  119. package/dist/ncp/index.d.ts.map +1 -0
  120. package/dist/ncp/index.js +13 -0
  121. package/dist/ncp/index.js.map +1 -0
  122. package/dist/ncp/ncp-error-codes.d.ts +22 -0
  123. package/dist/ncp/ncp-error-codes.d.ts.map +1 -0
  124. package/dist/ncp/ncp-error-codes.js +32 -0
  125. package/dist/ncp/ncp-error-codes.js.map +1 -0
  126. package/dist/ncp/ncp-patch-format.d.ts +7 -0
  127. package/dist/ncp/ncp-patch-format.d.ts.map +1 -0
  128. package/dist/ncp/ncp-patch-format.js +13 -0
  129. package/dist/ncp/ncp-patch-format.js.map +1 -0
  130. package/dist/ncp/registry.d.ts +3 -0
  131. package/dist/ncp/registry.d.ts.map +1 -0
  132. package/dist/ncp/registry.js +12 -0
  133. package/dist/ncp/registry.js.map +1 -0
  134. package/dist/ncp/stream-manager.d.ts +57 -0
  135. package/dist/ncp/stream-manager.d.ts.map +1 -0
  136. package/dist/ncp/stream-manager.js +163 -0
  137. package/dist/ncp/stream-manager.js.map +1 -0
  138. package/dist/ndp/frames.d.ts +56 -0
  139. package/dist/ndp/frames.d.ts.map +1 -0
  140. package/dist/ndp/frames.js +87 -0
  141. package/dist/ndp/frames.js.map +1 -0
  142. package/dist/ndp/index.cjs +252 -0
  143. package/dist/ndp/index.cjs.map +1 -0
  144. package/dist/ndp/index.d.cts +86 -0
  145. package/dist/ndp/index.d.ts +5 -0
  146. package/dist/ndp/index.d.ts.map +1 -0
  147. package/dist/ndp/index.js +7 -0
  148. package/dist/ndp/index.js.map +1 -0
  149. package/dist/ndp/ndp-registry.d.ts +11 -0
  150. package/dist/ndp/ndp-registry.d.ts.map +1 -0
  151. package/dist/ndp/ndp-registry.js +79 -0
  152. package/dist/ndp/ndp-registry.js.map +1 -0
  153. package/dist/ndp/registry.d.ts +3 -0
  154. package/dist/ndp/registry.d.ts.map +1 -0
  155. package/dist/ndp/registry.js +10 -0
  156. package/dist/ndp/registry.js.map +1 -0
  157. package/dist/ndp/validator.d.ts +18 -0
  158. package/dist/ndp/validator.d.ts.map +1 -0
  159. package/dist/ndp/validator.js +48 -0
  160. package/dist/ndp/validator.js.map +1 -0
  161. package/dist/nip/frames.d.ts +44 -0
  162. package/dist/nip/frames.d.ts.map +1 -0
  163. package/dist/nip/frames.js +81 -0
  164. package/dist/nip/frames.js.map +1 -0
  165. package/dist/nip/identity.d.ts +18 -0
  166. package/dist/nip/identity.d.ts.map +1 -0
  167. package/dist/nip/identity.js +94 -0
  168. package/dist/nip/identity.js.map +1 -0
  169. package/dist/nip/index.cjs +214 -0
  170. package/dist/nip/index.cjs.map +1 -0
  171. package/dist/nip/index.d.cts +65 -0
  172. package/dist/nip/index.d.ts +4 -0
  173. package/dist/nip/index.d.ts.map +1 -0
  174. package/dist/nip/index.js +6 -0
  175. package/dist/nip/index.js.map +1 -0
  176. package/dist/nip/registry.d.ts +3 -0
  177. package/dist/nip/registry.d.ts.map +1 -0
  178. package/dist/nip/registry.js +10 -0
  179. package/dist/nip/registry.js.map +1 -0
  180. package/dist/nop/client.d.ts +34 -0
  181. package/dist/nop/client.d.ts.map +1 -0
  182. package/dist/nop/client.js +90 -0
  183. package/dist/nop/client.js.map +1 -0
  184. package/dist/nop/frames.d.ts +65 -0
  185. package/dist/nop/frames.d.ts.map +1 -0
  186. package/dist/nop/frames.js +148 -0
  187. package/dist/nop/frames.js.map +1 -0
  188. package/dist/nop/index.cjs +762 -0
  189. package/dist/nop/index.cjs.map +1 -0
  190. package/dist/nop/index.d.cts +155 -0
  191. package/dist/nop/index.d.ts +5 -0
  192. package/dist/nop/index.d.ts.map +1 -0
  193. package/dist/nop/index.js +7 -0
  194. package/dist/nop/index.js.map +1 -0
  195. package/dist/nop/models.d.ts +58 -0
  196. package/dist/nop/models.d.ts.map +1 -0
  197. package/dist/nop/models.js +50 -0
  198. package/dist/nop/models.js.map +1 -0
  199. package/dist/nop/nop-types.d.ts +136 -0
  200. package/dist/nop/nop-types.d.ts.map +1 -0
  201. package/dist/nop/nop-types.js +44 -0
  202. package/dist/nop/nop-types.js.map +1 -0
  203. package/dist/nop/registry.d.ts +3 -0
  204. package/dist/nop/registry.d.ts.map +1 -0
  205. package/dist/nop/registry.js +11 -0
  206. package/dist/nop/registry.js.map +1 -0
  207. package/dist/nwp/client.d.ts +22 -0
  208. package/dist/nwp/client.d.ts.map +1 -0
  209. package/dist/nwp/client.js +101 -0
  210. package/dist/nwp/client.js.map +1 -0
  211. package/dist/nwp/frames.d.ts +46 -0
  212. package/dist/nwp/frames.d.ts.map +1 -0
  213. package/dist/nwp/frames.js +81 -0
  214. package/dist/nwp/frames.js.map +1 -0
  215. package/dist/nwp/index.cjs +658 -0
  216. package/dist/nwp/index.cjs.map +1 -0
  217. package/dist/nwp/index.d.cts +65 -0
  218. package/dist/nwp/index.d.ts +4 -0
  219. package/dist/nwp/index.d.ts.map +1 -0
  220. package/dist/nwp/index.js +6 -0
  221. package/dist/nwp/index.js.map +1 -0
  222. package/dist/nwp/registry.d.ts +3 -0
  223. package/dist/nwp/registry.d.ts.map +1 -0
  224. package/dist/nwp/registry.js +9 -0
  225. package/dist/nwp/registry.js.map +1 -0
  226. package/dist/setup.d.ts +10 -0
  227. package/dist/setup.d.ts.map +1 -0
  228. package/dist/setup.js +29 -0
  229. package/dist/setup.js.map +1 -0
  230. package/nip-ca-server/Dockerfile +27 -0
  231. package/nip-ca-server/README.md +45 -0
  232. package/nip-ca-server/db/001_init.sql +25 -0
  233. package/nip-ca-server/docker-compose.yml +29 -0
  234. package/nip-ca-server/package.json +23 -0
  235. package/nip-ca-server/src/ca.ts +155 -0
  236. package/nip-ca-server/src/db.ts +104 -0
  237. package/nip-ca-server/src/index.ts +157 -0
  238. package/nip-ca-server/tsconfig.json +13 -0
  239. package/package.json +47 -0
  240. package/src/core/anchor-cache.ts +129 -0
  241. package/src/core/cache.ts +93 -0
  242. package/src/core/canonical-json.ts +50 -0
  243. package/src/core/codec.ts +158 -0
  244. package/src/core/codecs/index.ts +5 -0
  245. package/src/core/codecs/ncp-codec.ts +170 -0
  246. package/src/core/codecs/tier1-json-codec.ts +33 -0
  247. package/src/core/codecs/tier2-msgpack-codec.ts +30 -0
  248. package/src/core/crypto-provider.ts +47 -0
  249. package/src/core/exceptions.ts +57 -0
  250. package/src/core/frame-header.ts +282 -0
  251. package/src/core/frame-registry.ts +91 -0
  252. package/src/core/frames.ts +183 -0
  253. package/src/core/index.ts +10 -0
  254. package/src/core/registry.ts +28 -0
  255. package/src/core/status-codes.ts +46 -0
  256. package/src/index.ts +10 -0
  257. package/src/ncp/frames/anchor-frame.ts +87 -0
  258. package/src/ncp/frames/caps-frame.ts +59 -0
  259. package/src/ncp/frames/diff-frame.ts +69 -0
  260. package/src/ncp/frames/error-frame.ts +26 -0
  261. package/src/ncp/frames/hello-frame.ts +50 -0
  262. package/src/ncp/frames/stream-frame.ts +35 -0
  263. package/src/ncp/frames.ts +199 -0
  264. package/src/ncp/handshake.ts +95 -0
  265. package/src/ncp/index.ts +12 -0
  266. package/src/ncp/ncp-error-codes.ts +34 -0
  267. package/src/ncp/ncp-patch-format.ts +16 -0
  268. package/src/ncp/registry.ts +14 -0
  269. package/src/ncp/stream-manager.ts +212 -0
  270. package/src/ndp/frames.ts +124 -0
  271. package/src/ndp/index.ts +7 -0
  272. package/src/ndp/ndp-registry.ts +82 -0
  273. package/src/ndp/registry.ts +12 -0
  274. package/src/ndp/validator.ts +64 -0
  275. package/src/nip/frames.ts +106 -0
  276. package/src/nip/identity.ts +113 -0
  277. package/src/nip/index.ts +6 -0
  278. package/src/nip/registry.ts +12 -0
  279. package/src/nop/client.ts +103 -0
  280. package/src/nop/frames.ts +181 -0
  281. package/src/nop/index.ts +7 -0
  282. package/src/nop/models.ts +79 -0
  283. package/src/nop/nop-types.ts +208 -0
  284. package/src/nop/registry.ts +13 -0
  285. package/src/nwp/client.ts +114 -0
  286. package/src/nwp/frames.ts +116 -0
  287. package/src/nwp/index.ts +6 -0
  288. package/src/nwp/registry.ts +11 -0
  289. package/src/setup.ts +32 -0
  290. package/tests/core/anchor-cache.test.ts +242 -0
  291. package/tests/core/codec.test.ts +205 -0
  292. package/tests/core/frame-registry.test.ts +46 -0
  293. package/tests/core.test.ts +327 -0
  294. package/tests/ncp/diff-binary-bitset.test.ts +107 -0
  295. package/tests/ncp/e2e-enc-reject.test.ts +93 -0
  296. package/tests/ncp/err-error-frame.test.ts +152 -0
  297. package/tests/ncp/frames.test.ts +359 -0
  298. package/tests/ncp/framing.test.ts +233 -0
  299. package/tests/ncp/hello-frame.test.ts +122 -0
  300. package/tests/ncp/inline-anchor.test.ts +88 -0
  301. package/tests/ncp/security.test.ts +184 -0
  302. package/tests/ncp/stream-window.test.ts +167 -0
  303. package/tests/ncp/stream.test.ts +242 -0
  304. package/tests/ncp/version-negotiation.test.ts +123 -0
  305. package/tests/ndp.test.ts +271 -0
  306. package/tests/nip.test.ts +184 -0
  307. package/tests/nop.test.ts +344 -0
  308. package/tests/nwp.test.ts +237 -0
  309. package/tsconfig.json +20 -0
  310. package/tsup.config.ts +20 -0
  311. package/vitest.config.ts +10 -0
@@ -0,0 +1,282 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ // Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
3
+ //
4
+ // NCP Frame Header — Binary parse/write for NPS wire format
5
+ // NPS-1 Neural Communication Protocol §3.1, §3.2
6
+
7
+ // ---------------------------------------------------------------------------
8
+ // Enums
9
+ // ---------------------------------------------------------------------------
10
+
11
+ /** Wire encoding tier (NPS-1 §3.2, flags bits 0-1). */
12
+ export enum EncodingTier {
13
+ /** Tier-1: UTF-8 JSON — development & compatibility. */
14
+ Json = 0x00,
15
+ /** Tier-2: MessagePack binary — production (~60% compression). */
16
+ MsgPack = 0x01,
17
+ // 0x02 = Reserved
18
+ // 0x03 = Reserved
19
+ }
20
+
21
+ /** Unified frame type namespace for the full NPS suite (NPS-0 §9). */
22
+ export enum FrameType {
23
+ // NCP 0x01–0x0F
24
+ Anchor = 0x01,
25
+ Diff = 0x02,
26
+ Stream = 0x03,
27
+ Caps = 0x04,
28
+ Align = 0x05, // deprecated — use AlignStream (0x43)
29
+ Hello = 0x06,
30
+ // NWP 0x10–0x1F
31
+ Query = 0x10,
32
+ Action = 0x11,
33
+ Subscribe = 0x12,
34
+ // NIP 0x20–0x2F
35
+ Ident = 0x20,
36
+ Trust = 0x21,
37
+ Revoke = 0x22,
38
+ // NDP 0x30–0x3F
39
+ Announce = 0x30,
40
+ Resolve = 0x31,
41
+ Graph = 0x32,
42
+ // NOP 0x40–0x4F
43
+ Task = 0x40,
44
+ Delegate = 0x41,
45
+ Sync = 0x42,
46
+ AlignStream = 0x43,
47
+ // System 0xF0–0xFF
48
+ Error = 0xfe,
49
+ }
50
+
51
+ // ---------------------------------------------------------------------------
52
+ // Constants
53
+ // ---------------------------------------------------------------------------
54
+
55
+ /** Default (compact) header size in bytes. */
56
+ export const DEFAULT_HEADER_SIZE = 4;
57
+
58
+ /** Extended header size in bytes (EXT=1). */
59
+ export const EXTENDED_HEADER_SIZE = 8;
60
+
61
+ /** Maximum payload in default mode (64 KiB − 1). */
62
+ export const DEFAULT_MAX_PAYLOAD = 0xffff;
63
+
64
+ /** Maximum payload in extended mode (4 GiB − 1). */
65
+ export const EXTENDED_MAX_PAYLOAD = 0xffffffff;
66
+
67
+ // Flag bit positions (NPS-1 §3.2)
68
+ const TIER_MASK = 0x03; // bits 0-1
69
+ const FINAL_BIT = 0x04; // bit 2
70
+ const ENC_BIT = 0x08; // bit 3
71
+ const RESERVED_MASK = 0x70; // bits 4-6
72
+ const EXT_BIT = 0x80; // bit 7
73
+
74
+ // ---------------------------------------------------------------------------
75
+ // Error
76
+ // ---------------------------------------------------------------------------
77
+
78
+ /** NCP protocol error with machine-readable error code. */
79
+ export class NcpError extends Error {
80
+ // `code` accepts NcpErrorCode constants (preferred) as well as NPS status
81
+ // strings that are not NCP-prefixed (e.g. "NPS-CLIENT-CONFLICT") for cases
82
+ // where the spec delegates to NPS-level codes without assigning an NCP code.
83
+ constructor(
84
+ public readonly code: string,
85
+ message: string,
86
+ ) {
87
+ super(message);
88
+ this.name = "NcpError";
89
+ }
90
+ }
91
+
92
+ // ---------------------------------------------------------------------------
93
+ // Parsed header
94
+ // ---------------------------------------------------------------------------
95
+
96
+ /** Parsed frame header. */
97
+ export interface FrameHeader {
98
+ /** Raw frame type byte. */
99
+ frameType: number;
100
+ /** Raw flags byte. */
101
+ flags: number;
102
+ /** Payload length in bytes. */
103
+ payloadLength: number;
104
+ /** Encoding tier extracted from flags bits 0-1. */
105
+ tier: EncodingTier;
106
+ /** True when FINAL flag (bit 2) is set. */
107
+ isFinal: boolean;
108
+ /** True when ENC flag (bit 3) is set. */
109
+ isEncrypted: boolean;
110
+ /** True when EXT flag (bit 7) is set — 8-byte header. */
111
+ isExtended: boolean;
112
+ /** Header size in bytes (4 or 8). */
113
+ headerSize: number;
114
+ }
115
+
116
+ // ---------------------------------------------------------------------------
117
+ // Parse
118
+ // ---------------------------------------------------------------------------
119
+
120
+ /**
121
+ * Parse a frame header from the start of the buffer.
122
+ * Reads 2 bytes first to determine EXT, then reads remaining bytes.
123
+ *
124
+ * @throws {NcpError} NCP-FRAME-FLAGS-INVALID if reserved bits 4-6 are non-zero.
125
+ * @throws {NcpError} NCP-FRAME-PARSE-ERROR if buffer is too small.
126
+ * @throws {NcpError} NCP-FRAME-PAYLOAD-TOO-LARGE if opts.max_frame_payload is set and exceeded.
127
+ */
128
+ export function parseFrameHeader(
129
+ buffer: Uint8Array,
130
+ opts?: { max_frame_payload?: number },
131
+ ): FrameHeader {
132
+ if (buffer.length < 2) {
133
+ throw new NcpError(
134
+ "NCP-FRAME-PARSE-ERROR",
135
+ `Buffer too small to read frame type and flags: need >= 2 bytes, got ${buffer.length}`,
136
+ );
137
+ }
138
+
139
+ const frameType = buffer[0]!;
140
+ const flags = buffer[1]!;
141
+
142
+ // Validate reserved bits (NPS-1 §3.2: bits 4-6 MUST be 0)
143
+ if ((flags & RESERVED_MASK) !== 0) {
144
+ throw new NcpError(
145
+ "NCP-FRAME-FLAGS-INVALID",
146
+ "Reserved flag bits 4-6 must be zero",
147
+ );
148
+ }
149
+
150
+ const isExtended = (flags & EXT_BIT) !== 0;
151
+
152
+ if (isExtended) {
153
+ if (buffer.length < EXTENDED_HEADER_SIZE) {
154
+ throw new NcpError(
155
+ "NCP-FRAME-PARSE-ERROR",
156
+ `Buffer too small for extended header: need ${EXTENDED_HEADER_SIZE} bytes, got ${buffer.length}`,
157
+ );
158
+ }
159
+
160
+ const view = new DataView(
161
+ buffer.buffer,
162
+ buffer.byteOffset,
163
+ buffer.byteLength,
164
+ );
165
+ const payloadLength = view.getUint32(2, false); // big-endian
166
+
167
+ if (
168
+ opts?.max_frame_payload !== undefined &&
169
+ payloadLength > opts.max_frame_payload
170
+ ) {
171
+ throw new NcpError(
172
+ "NCP-FRAME-PAYLOAD-TOO-LARGE",
173
+ `Payload length ${payloadLength} exceeds max_frame_payload ${opts.max_frame_payload}`,
174
+ );
175
+ }
176
+
177
+ return {
178
+ frameType,
179
+ flags,
180
+ payloadLength,
181
+ tier: (flags & TIER_MASK) as EncodingTier,
182
+ isFinal: (flags & FINAL_BIT) !== 0,
183
+ isEncrypted: (flags & ENC_BIT) !== 0,
184
+ isExtended: true,
185
+ headerSize: EXTENDED_HEADER_SIZE,
186
+ };
187
+ }
188
+
189
+ // Default 4-byte header
190
+ if (buffer.length < DEFAULT_HEADER_SIZE) {
191
+ throw new NcpError(
192
+ "NCP-FRAME-PARSE-ERROR",
193
+ `Buffer too small for header: need ${DEFAULT_HEADER_SIZE} bytes, got ${buffer.length}`,
194
+ );
195
+ }
196
+
197
+ const view = new DataView(
198
+ buffer.buffer,
199
+ buffer.byteOffset,
200
+ buffer.byteLength,
201
+ );
202
+ const payloadLength = view.getUint16(2, false); // big-endian
203
+
204
+ if (
205
+ opts?.max_frame_payload !== undefined &&
206
+ payloadLength > opts.max_frame_payload
207
+ ) {
208
+ throw new NcpError(
209
+ "NCP-FRAME-PAYLOAD-TOO-LARGE",
210
+ `Payload length ${payloadLength} exceeds max_frame_payload ${opts.max_frame_payload}`,
211
+ );
212
+ }
213
+
214
+ return {
215
+ frameType,
216
+ flags,
217
+ payloadLength,
218
+ tier: (flags & TIER_MASK) as EncodingTier,
219
+ isFinal: (flags & FINAL_BIT) !== 0,
220
+ isEncrypted: (flags & ENC_BIT) !== 0,
221
+ isExtended: false,
222
+ headerSize: DEFAULT_HEADER_SIZE,
223
+ };
224
+ }
225
+
226
+ // ---------------------------------------------------------------------------
227
+ // Write
228
+ // ---------------------------------------------------------------------------
229
+
230
+ /**
231
+ * Write a frame header into the buffer.
232
+ * @returns Number of bytes written (4 or 8).
233
+ * @throws {Error} if buffer is too small.
234
+ */
235
+ export function writeFrameHeader(
236
+ header: FrameHeader,
237
+ buffer: Uint8Array,
238
+ ): number {
239
+ const size = header.isExtended ? EXTENDED_HEADER_SIZE : DEFAULT_HEADER_SIZE;
240
+ if (buffer.length < size) {
241
+ throw new Error(
242
+ `Destination buffer must be at least ${size} bytes, got ${buffer.length}`,
243
+ );
244
+ }
245
+
246
+ buffer[0] = header.frameType;
247
+ buffer[1] = header.flags;
248
+
249
+ const view = new DataView(
250
+ buffer.buffer,
251
+ buffer.byteOffset,
252
+ buffer.byteLength,
253
+ );
254
+
255
+ if (header.isExtended) {
256
+ view.setUint32(2, header.payloadLength, false); // big-endian
257
+ buffer[6] = 0; // reserved
258
+ buffer[7] = 0; // reserved
259
+ } else {
260
+ view.setUint16(2, header.payloadLength, false); // big-endian
261
+ }
262
+
263
+ return size;
264
+ }
265
+
266
+ // ---------------------------------------------------------------------------
267
+ // Helpers
268
+ // ---------------------------------------------------------------------------
269
+
270
+ /** Build a flags byte from individual options. */
271
+ export function buildFlags(options: {
272
+ tier?: EncodingTier;
273
+ final?: boolean;
274
+ encrypted?: boolean;
275
+ extended?: boolean;
276
+ }): number {
277
+ let flags = (options.tier ?? EncodingTier.Json) & TIER_MASK;
278
+ if (options.final) flags |= FINAL_BIT;
279
+ if (options.encrypted) flags |= ENC_BIT;
280
+ if (options.extended) flags |= EXT_BIT;
281
+ return flags;
282
+ }
@@ -0,0 +1,91 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ // Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
3
+ //
4
+ // NCP Frame Registry — Maps frame type bytes to protocol identifiers
5
+ // NPS-0 §9 Unified frame namespace
6
+
7
+ import { FrameType, NcpError } from "./frame-header.js";
8
+
9
+ // ---------------------------------------------------------------------------
10
+ // Protocol identifier for routing
11
+ // ---------------------------------------------------------------------------
12
+
13
+ export type Protocol = "ncp" | "nwp" | "nip" | "ndp" | "nop" | "system";
14
+
15
+ export interface FrameRegistryEntry {
16
+ /** Frame type byte. */
17
+ frameType: number;
18
+ /** Human-readable name. */
19
+ name: string;
20
+ /** Protocol this frame belongs to. */
21
+ protocol: Protocol;
22
+ }
23
+
24
+ // ---------------------------------------------------------------------------
25
+ // Registry
26
+ // ---------------------------------------------------------------------------
27
+
28
+ /**
29
+ * Maps frame type bytes to metadata.
30
+ * Built once at startup, then read-only.
31
+ */
32
+ export class FrameRegistry {
33
+ private readonly map: Map<number, FrameRegistryEntry>;
34
+
35
+ constructor(entries: FrameRegistryEntry[]) {
36
+ this.map = new Map(entries.map((e) => [e.frameType, e]));
37
+ }
38
+
39
+ /**
40
+ * Resolve a frame type byte to its registry entry.
41
+ * @throws {NcpError} NCP-FRAME-UNKNOWN-TYPE if not registered.
42
+ */
43
+ resolve(frameType: number): FrameRegistryEntry {
44
+ const entry = this.map.get(frameType);
45
+ if (!entry) {
46
+ throw new NcpError(
47
+ "NCP-FRAME-UNKNOWN-TYPE",
48
+ `No entry registered for frame type 0x${frameType.toString(16).padStart(2, "0")}`,
49
+ );
50
+ }
51
+ return entry;
52
+ }
53
+
54
+ /** Check if a frame type is registered. */
55
+ has(frameType: number): boolean {
56
+ return this.map.has(frameType);
57
+ }
58
+
59
+ /**
60
+ * Create a registry pre-populated with all NCP core frames.
61
+ * Upper-layer protocols can extend via the builder.
62
+ */
63
+ static createDefault(): FrameRegistry {
64
+ return new FrameRegistryBuilder()
65
+ .add(FrameType.Anchor, "AnchorFrame", "ncp")
66
+ .add(FrameType.Diff, "DiffFrame", "ncp")
67
+ .add(FrameType.Stream, "StreamFrame", "ncp")
68
+ .add(FrameType.Caps, "CapsFrame", "ncp")
69
+ .add(FrameType.Align, "AlignFrame", "ncp") // deprecated
70
+ .add(FrameType.Hello, "HelloFrame", "ncp")
71
+ .add(FrameType.Error, "ErrorFrame", "system")
72
+ .build();
73
+ }
74
+ }
75
+
76
+ // ---------------------------------------------------------------------------
77
+ // Builder
78
+ // ---------------------------------------------------------------------------
79
+
80
+ export class FrameRegistryBuilder {
81
+ private readonly entries: FrameRegistryEntry[] = [];
82
+
83
+ add(frameType: number, name: string, protocol: Protocol): this {
84
+ this.entries.push({ frameType, name, protocol });
85
+ return this;
86
+ }
87
+
88
+ build(): FrameRegistry {
89
+ return new FrameRegistry(this.entries);
90
+ }
91
+ }
@@ -0,0 +1,183 @@
1
+ // Copyright 2026 INNO LOTUS PTY LTD
2
+ // SPDX-License-Identifier: Apache-2.0
3
+
4
+ /**
5
+ * NPS wire-level frame primitives: FrameType, FrameFlags, EncodingTier, FrameHeader.
6
+ */
7
+
8
+ import { NpsFrameError } from "./exceptions.js";
9
+
10
+ // ── FrameType ────────────────────────────────────────────────────────────────
11
+
12
+ /** Unified frame byte namespace for the full NPS suite (NPS-0 §9). */
13
+ export enum FrameType {
14
+ // NCP 0x01–0x0F
15
+ ANCHOR = 0x01,
16
+ DIFF = 0x02,
17
+ STREAM = 0x03,
18
+ CAPS = 0x04,
19
+ ALIGN = 0x05, // deprecated — use AlignStream (0x43)
20
+
21
+ // NWP 0x10–0x1F
22
+ QUERY = 0x10,
23
+ ACTION = 0x11,
24
+
25
+ // NIP 0x20–0x2F
26
+ IDENT = 0x20,
27
+ TRUST = 0x21,
28
+ REVOKE = 0x22,
29
+
30
+ // NDP 0x30–0x3F
31
+ ANNOUNCE = 0x30,
32
+ RESOLVE = 0x31,
33
+ GRAPH = 0x32,
34
+
35
+ // NOP 0x40–0x4F
36
+ TASK = 0x40,
37
+ DELEGATE = 0x41,
38
+ SYNC = 0x42,
39
+ ALIGN_STREAM = 0x43,
40
+
41
+ // Reserved / System 0xF0–0xFF
42
+ ERROR = 0xFE,
43
+ }
44
+
45
+ // ── EncodingTier ─────────────────────────────────────────────────────────────
46
+
47
+ /**
48
+ * Wire encoding tier, stored in the lower 2 bits of the flags byte (NPS-1 §3.2).
49
+ * 0x00 = Tier-1 JSON — human-readable; development / compatibility.
50
+ * 0x01 = Tier-2 MsgPack — binary, ~60 % smaller; production default.
51
+ */
52
+ export enum EncodingTier {
53
+ JSON = 0x00,
54
+ MSGPACK = 0x01,
55
+ }
56
+
57
+ // ── FrameFlags ───────────────────────────────────────────────────────────────
58
+
59
+ /**
60
+ * Flags byte in the NPS frame header (NPS-1 §3.2).
61
+ * Bit layout (LSB = bit 0):
62
+ * Bits 0–1 (T0,T1) : Encoding tier
63
+ * Bit 2 (FINAL) : Last chunk of a StreamFrame; non-stream frames MUST set this
64
+ * Bit 3 (ENC) : Payload encrypted
65
+ * Bits 4–6 (RSV) : Reserved — sender MUST write 0
66
+ * Bit 7 (EXT) : Extended 8-byte header
67
+ */
68
+ export const FrameFlags = {
69
+ NONE: 0x00,
70
+ TIER1_JSON: 0x00,
71
+ TIER2_MSGPACK: 0x01,
72
+ FINAL: 0x04,
73
+ ENCRYPTED: 0x08,
74
+ EXT: 0x80,
75
+ } as const;
76
+
77
+ // ── Constants ─────────────────────────────────────────────────────────────────
78
+
79
+ export const DEFAULT_HEADER_SIZE = 4;
80
+ export const EXTENDED_HEADER_SIZE = 8;
81
+ export const DEFAULT_MAX_PAYLOAD = 0xffff; // 65 535 bytes
82
+ export const EXTENDED_MAX_PAYLOAD = 0xffffffff; // 4 GiB - 1
83
+
84
+ // ── FrameHeader ──────────────────────────────────────────────────────────────
85
+
86
+ /**
87
+ * NPS frame header, present at the start of every wire message (NPS-1 §3.1).
88
+ *
89
+ * Default (4 bytes, EXT=0):
90
+ * Byte 0 : FrameType
91
+ * Byte 1 : Flags
92
+ * Byte 2–3 : PayloadLength (big-endian uint16)
93
+ *
94
+ * Extended (8 bytes, EXT=1):
95
+ * Byte 0 : FrameType
96
+ * Byte 1 : Flags (bit 7 = 1)
97
+ * Byte 2–3 : Reserved (must be 0)
98
+ * Byte 4–7 : PayloadLength (big-endian uint32)
99
+ */
100
+ export class FrameHeader {
101
+ constructor(
102
+ public readonly frameType: FrameType,
103
+ public readonly flags: number,
104
+ public readonly payloadLength: number,
105
+ ) {}
106
+
107
+ get isExtended(): boolean {
108
+ return (this.flags & FrameFlags.EXT) !== 0;
109
+ }
110
+
111
+ get headerSize(): number {
112
+ return this.isExtended ? EXTENDED_HEADER_SIZE : DEFAULT_HEADER_SIZE;
113
+ }
114
+
115
+ get encodingTier(): EncodingTier {
116
+ return (this.flags & 0x03) as EncodingTier;
117
+ }
118
+
119
+ get isFinal(): boolean {
120
+ return (this.flags & 0x04) !== 0;
121
+ }
122
+
123
+ get isEncrypted(): boolean {
124
+ return (this.flags & 0x08) !== 0;
125
+ }
126
+
127
+ // ── Parsing ───────────────────────────────────────────────────────────────
128
+
129
+ static parse(buf: Uint8Array): FrameHeader {
130
+ if (buf.length < 2) {
131
+ throw new NpsFrameError(
132
+ `Buffer too small to read frame type and flags: need >= 2 bytes, got ${buf.length}.`,
133
+ );
134
+ }
135
+
136
+ const flags = buf[1]!;
137
+ const ext = (flags & FrameFlags.EXT) !== 0;
138
+
139
+ if (ext) {
140
+ if (buf.length < EXTENDED_HEADER_SIZE) {
141
+ throw new NpsFrameError(
142
+ `Buffer too small for extended frame header: need ${EXTENDED_HEADER_SIZE} bytes, got ${buf.length}.`,
143
+ );
144
+ }
145
+ const view = new DataView(buf.buffer, buf.byteOffset);
146
+ const payloadLength = view.getUint32(4, false); // big-endian
147
+ return new FrameHeader(buf[0]! as FrameType, flags, payloadLength);
148
+ }
149
+
150
+ if (buf.length < DEFAULT_HEADER_SIZE) {
151
+ throw new NpsFrameError(
152
+ `Buffer too small for frame header: need ${DEFAULT_HEADER_SIZE} bytes, got ${buf.length}.`,
153
+ );
154
+ }
155
+ const view = new DataView(buf.buffer, buf.byteOffset);
156
+ const payloadLength = view.getUint16(2, false); // big-endian
157
+ return new FrameHeader(buf[0]! as FrameType, flags, payloadLength);
158
+ }
159
+
160
+ // ── Serialisation ─────────────────────────────────────────────────────────
161
+
162
+ toBytes(): Uint8Array {
163
+ if (this.isExtended) {
164
+ const buf = new Uint8Array(EXTENDED_HEADER_SIZE);
165
+ const view = new DataView(buf.buffer);
166
+ view.setUint8(0, this.frameType);
167
+ view.setUint8(1, this.flags);
168
+ view.setUint16(2, 0, false); // reserved
169
+ view.setUint32(4, this.payloadLength, false);
170
+ return buf;
171
+ }
172
+ const buf = new Uint8Array(DEFAULT_HEADER_SIZE);
173
+ const view = new DataView(buf.buffer);
174
+ view.setUint8(0, this.frameType);
175
+ view.setUint8(1, this.flags);
176
+ view.setUint16(2, this.payloadLength, false);
177
+ return buf;
178
+ }
179
+
180
+ toString(): string {
181
+ return `FrameHeader(frameType=0x${this.frameType.toString(16).padStart(2, "0")}, flags=0x${this.flags.toString(16).padStart(2, "0")}, payloadLength=${this.payloadLength})`;
182
+ }
183
+ }
@@ -0,0 +1,10 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ // Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
3
+ export * from "./frame-header.js";
4
+ export * from "./frame-registry.js";
5
+ export * from "./anchor-cache.js";
6
+ export * from "./exceptions.js";
7
+ export * from "./status-codes.js";
8
+ export { jcsStringify, sortKeysStringify } from "./canonical-json.js";
9
+ export type { CryptoProvider } from "./crypto-provider.js";
10
+ export * from "./codecs/index.js";
@@ -0,0 +1,28 @@
1
+ // Copyright 2026 INNO LOTUS PTY LTD
2
+ // SPDX-License-Identifier: Apache-2.0
3
+
4
+ import { NpsFrameError } from "./exceptions.js";
5
+ import { FrameType } from "./frames.js";
6
+ import type { NpsFrame } from "./codec.js";
7
+
8
+ export interface FrameClass {
9
+ fromDict(data: Record<string, unknown>): NpsFrame;
10
+ }
11
+
12
+ export class FrameRegistry {
13
+ private readonly _map = new Map<FrameType, FrameClass>();
14
+
15
+ register(frameType: FrameType, cls: FrameClass): void {
16
+ this._map.set(frameType, cls);
17
+ }
18
+
19
+ resolve(frameType: FrameType): FrameClass {
20
+ const cls = this._map.get(frameType);
21
+ if (cls === undefined) {
22
+ throw new NpsFrameError(
23
+ `No frame class registered for type 0x${frameType.toString(16).padStart(2, "0")}.`,
24
+ );
25
+ }
26
+ return cls;
27
+ }
28
+ }
@@ -0,0 +1,46 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ // Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
3
+ //
4
+ // NPS native status codes — per spec/status-codes.md
5
+
6
+ /** NPS native status code constants. */
7
+ export const NpsStatusCodes = {
8
+ // Success
9
+ NPS_OK: "NPS-OK",
10
+ NPS_OK_ACCEPTED: "NPS-OK-ACCEPTED",
11
+ NPS_OK_NO_CONTENT: "NPS-OK-NO-CONTENT",
12
+
13
+ // Auth
14
+ NPS_AUTH_UNAUTHENTICATED: "NPS-AUTH-UNAUTHENTICATED",
15
+ NPS_AUTH_FORBIDDEN: "NPS-AUTH-FORBIDDEN",
16
+
17
+ // Client errors
18
+ NPS_CLIENT_BAD_FRAME: "NPS-CLIENT-BAD-FRAME",
19
+ NPS_CLIENT_BAD_PARAM: "NPS-CLIENT-BAD-PARAM",
20
+ NPS_CLIENT_NOT_FOUND: "NPS-CLIENT-NOT-FOUND",
21
+ NPS_CLIENT_CONFLICT: "NPS-CLIENT-CONFLICT",
22
+ NPS_CLIENT_GONE: "NPS-CLIENT-GONE",
23
+ NPS_CLIENT_UNPROCESSABLE: "NPS-CLIENT-UNPROCESSABLE",
24
+
25
+ // Server errors
26
+ NPS_SERVER_INTERNAL: "NPS-SERVER-INTERNAL",
27
+ NPS_SERVER_UNAVAILABLE: "NPS-SERVER-UNAVAILABLE",
28
+ NPS_SERVER_TIMEOUT: "NPS-SERVER-TIMEOUT",
29
+ NPS_SERVER_ENCODING_UNSUPPORTED: "NPS-SERVER-ENCODING-UNSUPPORTED",
30
+
31
+ // Stream
32
+ NPS_STREAM_SEQ_GAP: "NPS-STREAM-SEQ-GAP",
33
+ NPS_STREAM_NOT_FOUND: "NPS-STREAM-NOT-FOUND",
34
+ NPS_STREAM_LIMIT: "NPS-STREAM-LIMIT",
35
+
36
+ // Limit
37
+ NPS_LIMIT_RATE: "NPS-LIMIT-RATE",
38
+ NPS_LIMIT_BUDGET: "NPS-LIMIT-BUDGET",
39
+ NPS_LIMIT_PAYLOAD: "NPS-LIMIT-PAYLOAD",
40
+ NPS_LIMIT_EXCEEDED: "NPS-LIMIT-EXCEEDED",
41
+
42
+ // Protocol
43
+ NPS_PROTO_VERSION_INCOMPATIBLE: "NPS-PROTO-VERSION-INCOMPATIBLE",
44
+ } as const;
45
+
46
+ export type NpsStatusCode = (typeof NpsStatusCodes)[keyof typeof NpsStatusCodes];
package/src/index.ts ADDED
@@ -0,0 +1,10 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ // Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
3
+ //
4
+ // @labacacia/nps-sdk — root entry point.
5
+ // Mirrors Python root __init__.py: exports only the SDK version.
6
+ // All protocol APIs are accessed via sub-package imports:
7
+ // import { ... } from "@labacacia/nps-sdk/core"
8
+ // import { ... } from "@labacacia/nps-sdk/ncp"
9
+
10
+ export const VERSION = "0.1.0";