@labacacia/nps-sdk 1.0.0-alpha.5 → 1.0.0-alpha.7

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 (145) hide show
  1. package/CHANGELOG.cn.md +29 -5
  2. package/CHANGELOG.md +29 -5
  3. package/LICENSE +0 -0
  4. package/NOTICE +0 -0
  5. package/README.cn.md +8 -13
  6. package/README.md +8 -13
  7. package/dist/nip/index.d.ts +1 -0
  8. package/dist/nip/index.d.ts.map +1 -1
  9. package/dist/nip/index.js +2 -0
  10. package/dist/nip/index.js.map +1 -1
  11. package/dist/nip/reputation-client.d.ts +116 -0
  12. package/dist/nip/reputation-client.d.ts.map +1 -0
  13. package/dist/nip/reputation-client.js +261 -0
  14. package/dist/nip/reputation-client.js.map +1 -0
  15. package/dist/nip/x509/oids.d.ts +9 -10
  16. package/dist/nip/x509/oids.d.ts.map +1 -1
  17. package/dist/nip/x509/oids.js +3 -4
  18. package/dist/nip/x509/oids.js.map +1 -1
  19. package/dist/nwp/anchor-client.d.ts +109 -0
  20. package/dist/nwp/anchor-client.d.ts.map +1 -0
  21. package/dist/nwp/anchor-client.js +279 -0
  22. package/dist/nwp/anchor-client.js.map +1 -0
  23. package/dist/nwp/index.d.ts +1 -1
  24. package/dist/nwp/index.d.ts.map +1 -1
  25. package/dist/nwp/index.js +1 -1
  26. package/dist/nwp/index.js.map +1 -1
  27. package/doc/nps-sdk.core.cn.md +0 -0
  28. package/doc/nps-sdk.core.md +0 -0
  29. package/doc/nps-sdk.ncp.cn.md +0 -0
  30. package/doc/nps-sdk.ncp.md +0 -0
  31. package/doc/nps-sdk.ndp.cn.md +0 -0
  32. package/doc/nps-sdk.ndp.md +0 -0
  33. package/doc/nps-sdk.nop.cn.md +0 -0
  34. package/doc/nps-sdk.nop.md +0 -0
  35. package/doc/overview.cn.md +0 -0
  36. package/doc/overview.md +0 -0
  37. package/package.json +12 -1
  38. package/CONTRIBUTING.cn.md +0 -35
  39. package/CONTRIBUTING.md +0 -35
  40. package/dist/nwp/error-codes.d.ts +0 -42
  41. package/dist/nwp/error-codes.d.ts.map +0 -1
  42. package/dist/nwp/error-codes.js +0 -53
  43. package/dist/nwp/error-codes.js.map +0 -1
  44. package/nip-ca-server/Dockerfile +0 -27
  45. package/nip-ca-server/README.md +0 -45
  46. package/nip-ca-server/db/001_init.sql +0 -25
  47. package/nip-ca-server/docker-compose.yml +0 -29
  48. package/nip-ca-server/package.json +0 -23
  49. package/nip-ca-server/src/ca.ts +0 -155
  50. package/nip-ca-server/src/db.ts +0 -104
  51. package/nip-ca-server/src/index.ts +0 -157
  52. package/nip-ca-server/tsconfig.json +0 -13
  53. package/src/core/anchor-cache.ts +0 -129
  54. package/src/core/cache.ts +0 -93
  55. package/src/core/canonical-json.ts +0 -50
  56. package/src/core/codec.ts +0 -158
  57. package/src/core/codecs/index.ts +0 -5
  58. package/src/core/codecs/ncp-codec.ts +0 -170
  59. package/src/core/codecs/tier1-json-codec.ts +0 -33
  60. package/src/core/codecs/tier2-msgpack-codec.ts +0 -30
  61. package/src/core/crypto-provider.ts +0 -47
  62. package/src/core/exceptions.ts +0 -57
  63. package/src/core/frame-header.ts +0 -282
  64. package/src/core/frame-registry.ts +0 -91
  65. package/src/core/frames.ts +0 -184
  66. package/src/core/index.ts +0 -42
  67. package/src/core/registry.ts +0 -28
  68. package/src/core/status-codes.ts +0 -47
  69. package/src/index.ts +0 -10
  70. package/src/ncp/frames/anchor-frame.ts +0 -87
  71. package/src/ncp/frames/caps-frame.ts +0 -59
  72. package/src/ncp/frames/diff-frame.ts +0 -69
  73. package/src/ncp/frames/error-frame.ts +0 -26
  74. package/src/ncp/frames/hello-frame.ts +0 -50
  75. package/src/ncp/frames/stream-frame.ts +0 -35
  76. package/src/ncp/frames.ts +0 -251
  77. package/src/ncp/handshake.ts +0 -95
  78. package/src/ncp/index.ts +0 -13
  79. package/src/ncp/ncp-error-codes.ts +0 -36
  80. package/src/ncp/ncp-patch-format.ts +0 -16
  81. package/src/ncp/preamble.ts +0 -79
  82. package/src/ncp/registry.ts +0 -15
  83. package/src/ncp/stream-manager.ts +0 -212
  84. package/src/ndp/dns-txt.ts +0 -86
  85. package/src/ndp/frames.ts +0 -124
  86. package/src/ndp/index.ts +0 -8
  87. package/src/ndp/ndp-registry.ts +0 -116
  88. package/src/ndp/registry.ts +0 -12
  89. package/src/ndp/validator.ts +0 -64
  90. package/src/nip/acme/client.ts +0 -185
  91. package/src/nip/acme/index.ts +0 -8
  92. package/src/nip/acme/jws.ts +0 -109
  93. package/src/nip/acme/messages.ts +0 -85
  94. package/src/nip/acme/server.ts +0 -480
  95. package/src/nip/acme/wire.ts +0 -24
  96. package/src/nip/assurance-level.ts +0 -40
  97. package/src/nip/cert-format.ts +0 -9
  98. package/src/nip/error-codes.ts +0 -38
  99. package/src/nip/frames.ts +0 -138
  100. package/src/nip/identity.ts +0 -113
  101. package/src/nip/index.ts +0 -14
  102. package/src/nip/registry.ts +0 -12
  103. package/src/nip/verifier.ts +0 -122
  104. package/src/nip/x509/builder.ts +0 -91
  105. package/src/nip/x509/index.ts +0 -6
  106. package/src/nip/x509/oids.ts +0 -28
  107. package/src/nip/x509/verifier.ts +0 -214
  108. package/src/nop/client.ts +0 -103
  109. package/src/nop/frames.ts +0 -181
  110. package/src/nop/index.ts +0 -7
  111. package/src/nop/models.ts +0 -79
  112. package/src/nop/nop-types.ts +0 -208
  113. package/src/nop/registry.ts +0 -13
  114. package/src/nwp/client.ts +0 -114
  115. package/src/nwp/error-codes.ts +0 -62
  116. package/src/nwp/frames.ts +0 -116
  117. package/src/nwp/index.ts +0 -7
  118. package/src/nwp/registry.ts +0 -11
  119. package/src/setup.ts +0 -32
  120. package/tests/_rfc0002-keys.ts +0 -57
  121. package/tests/core/anchor-cache.test.ts +0 -242
  122. package/tests/core/codec.test.ts +0 -205
  123. package/tests/core/frame-registry.test.ts +0 -46
  124. package/tests/core.test.ts +0 -327
  125. package/tests/ncp/diff-binary-bitset.test.ts +0 -107
  126. package/tests/ncp/e2e-enc-reject.test.ts +0 -93
  127. package/tests/ncp/err-error-frame.test.ts +0 -152
  128. package/tests/ncp/frames.test.ts +0 -359
  129. package/tests/ncp/framing.test.ts +0 -233
  130. package/tests/ncp/hello-frame.test.ts +0 -122
  131. package/tests/ncp/inline-anchor.test.ts +0 -88
  132. package/tests/ncp/preamble.test.ts +0 -93
  133. package/tests/ncp/security.test.ts +0 -184
  134. package/tests/ncp/stream-window.test.ts +0 -167
  135. package/tests/ncp/stream.test.ts +0 -242
  136. package/tests/ncp/version-negotiation.test.ts +0 -123
  137. package/tests/ndp.test.ts +0 -377
  138. package/tests/nip-acme-agent01.test.ts +0 -192
  139. package/tests/nip-x509.test.ts +0 -280
  140. package/tests/nip.test.ts +0 -184
  141. package/tests/nop.test.ts +0 -344
  142. package/tests/nwp.test.ts +0 -237
  143. package/tsconfig.json +0 -20
  144. package/tsup.config.ts +0 -20
  145. package/vitest.config.ts +0 -10
@@ -1,47 +0,0 @@
1
- // SPDX-License-Identifier: Apache-2.0
2
- // Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
3
- //
4
- // CryptoProvider interface — async crypto abstraction for Node + browser.
5
- // NPS-3 §10 / Q10 resolution in nps-ts-sdk-step7-plan.
6
- //
7
- // Implementations (NodeCryptoProvider, WebCryptoProvider) land at P3
8
- // alongside NIP tests. This file is structural scaffold only.
9
-
10
- /**
11
- * Async crypto operations used across NPS protocols.
12
- * All keys, IVs, and byte payloads are Uint8Array.
13
- */
14
- export interface CryptoProvider {
15
- /** Generate cryptographically secure random bytes. */
16
- randomBytes(n: number): Uint8Array;
17
-
18
- /** Generate an Ed25519 keypair. */
19
- ed25519GenerateKeyPair(): Promise<{ publicKey: Uint8Array; privateKey: Uint8Array }>;
20
-
21
- /** Sign data with an Ed25519 private key. Returns 64-byte signature. */
22
- ed25519Sign(privateKey: Uint8Array, data: Uint8Array): Promise<Uint8Array>;
23
-
24
- /** Verify an Ed25519 signature. */
25
- ed25519Verify(publicKey: Uint8Array, data: Uint8Array, sig: Uint8Array): Promise<boolean>;
26
-
27
- /**
28
- * AES-256-GCM encrypt.
29
- * Returns ciphertext || 16-byte tag (single contiguous buffer, matching
30
- * Web Crypto subtle.encrypt output and Python pycryptodome layout).
31
- */
32
- aesGcmEncrypt(key: Uint8Array, iv: Uint8Array, plaintext: Uint8Array): Promise<Uint8Array>;
33
-
34
- /**
35
- * AES-256-GCM decrypt.
36
- * Input is ciphertext || 16-byte tag (same layout as aesGcmEncrypt output).
37
- */
38
- aesGcmDecrypt(key: Uint8Array, iv: Uint8Array, ciphertextAndTag: Uint8Array): Promise<Uint8Array>;
39
-
40
- /** PBKDF2-SHA256 key derivation. */
41
- pbkdf2Sha256(
42
- passphrase: Uint8Array,
43
- salt: Uint8Array,
44
- iterations: number,
45
- keyLen: number,
46
- ): Promise<Uint8Array>;
47
- }
@@ -1,57 +0,0 @@
1
- // SPDX-License-Identifier: Apache-2.0
2
- // Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
3
- //
4
- // NPS exception hierarchy — ported from nps_sdk/core/exceptions.py
5
- // NPS-1 §6
6
-
7
- /** Base class for all NPS SDK errors. */
8
- export class NpsError extends Error {
9
- constructor(message: string) {
10
- super(message);
11
- this.name = "NpsError";
12
- }
13
- }
14
-
15
- /** Frame parse or structural error. */
16
- export class NpsFrameError extends NpsError {
17
- constructor(message: string) {
18
- super(message);
19
- this.name = "NpsFrameError";
20
- }
21
- }
22
-
23
- /** Encode or decode error. */
24
- export class NpsCodecError extends NpsError {
25
- constructor(message: string) {
26
- super(message);
27
- this.name = "NpsCodecError";
28
- }
29
- }
30
-
31
- /** Anchor cache miss — requested anchor ID not found. */
32
- export class NpsAnchorNotFoundError extends NpsError {
33
- readonly anchorId: string;
34
- constructor(anchorId: string, message?: string) {
35
- super(message ?? `Anchor not found: ${anchorId}`);
36
- this.name = "NpsAnchorNotFoundError";
37
- this.anchorId = anchorId;
38
- }
39
- }
40
-
41
- /** Anchor ID collision — same ID but different schema content. */
42
- export class NpsAnchorPoisonError extends NpsError {
43
- readonly anchorId: string;
44
- constructor(anchorId: string, message?: string) {
45
- super(message ?? `Anchor poison detected: ${anchorId}`);
46
- this.name = "NpsAnchorPoisonError";
47
- this.anchorId = anchorId;
48
- }
49
- }
50
-
51
- /** Stream-level error (sequence gap, unknown stream ID, etc.). */
52
- export class NpsStreamError extends NpsError {
53
- constructor(message: string) {
54
- super(message);
55
- this.name = "NpsStreamError";
56
- }
57
- }
@@ -1,282 +0,0 @@
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
- }
@@ -1,91 +0,0 @@
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
- }
@@ -1,184 +0,0 @@
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
- HELLO = 0x06,
21
-
22
- // NWP 0x10–0x1F
23
- QUERY = 0x10,
24
- ACTION = 0x11,
25
-
26
- // NIP 0x20–0x2F
27
- IDENT = 0x20,
28
- TRUST = 0x21,
29
- REVOKE = 0x22,
30
-
31
- // NDP 0x30–0x3F
32
- ANNOUNCE = 0x30,
33
- RESOLVE = 0x31,
34
- GRAPH = 0x32,
35
-
36
- // NOP 0x40–0x4F
37
- TASK = 0x40,
38
- DELEGATE = 0x41,
39
- SYNC = 0x42,
40
- ALIGN_STREAM = 0x43,
41
-
42
- // Reserved / System 0xF0–0xFF
43
- ERROR = 0xFE,
44
- }
45
-
46
- // ── EncodingTier ─────────────────────────────────────────────────────────────
47
-
48
- /**
49
- * Wire encoding tier, stored in the lower 2 bits of the flags byte (NPS-1 §3.2).
50
- * 0x00 = Tier-1 JSON — human-readable; development / compatibility.
51
- * 0x01 = Tier-2 MsgPack — binary, ~60 % smaller; production default.
52
- */
53
- export enum EncodingTier {
54
- JSON = 0x00,
55
- MSGPACK = 0x01,
56
- }
57
-
58
- // ── FrameFlags ───────────────────────────────────────────────────────────────
59
-
60
- /**
61
- * Flags byte in the NPS frame header (NPS-1 §3.2).
62
- * Bit layout (LSB = bit 0):
63
- * Bits 0–1 (T0,T1) : Encoding tier
64
- * Bit 2 (FINAL) : Last chunk of a StreamFrame; non-stream frames MUST set this
65
- * Bit 3 (ENC) : Payload encrypted
66
- * Bits 4–6 (RSV) : Reserved — sender MUST write 0
67
- * Bit 7 (EXT) : Extended 8-byte header
68
- */
69
- export const FrameFlags = {
70
- NONE: 0x00,
71
- TIER1_JSON: 0x00,
72
- TIER2_MSGPACK: 0x01,
73
- FINAL: 0x04,
74
- ENCRYPTED: 0x08,
75
- EXT: 0x80,
76
- } as const;
77
-
78
- // ── Constants ─────────────────────────────────────────────────────────────────
79
-
80
- export const DEFAULT_HEADER_SIZE = 4;
81
- export const EXTENDED_HEADER_SIZE = 8;
82
- export const DEFAULT_MAX_PAYLOAD = 0xffff; // 65 535 bytes
83
- export const EXTENDED_MAX_PAYLOAD = 0xffffffff; // 4 GiB - 1
84
-
85
- // ── FrameHeader ──────────────────────────────────────────────────────────────
86
-
87
- /**
88
- * NPS frame header, present at the start of every wire message (NPS-1 §3.1).
89
- *
90
- * Default (4 bytes, EXT=0):
91
- * Byte 0 : FrameType
92
- * Byte 1 : Flags
93
- * Byte 2–3 : PayloadLength (big-endian uint16)
94
- *
95
- * Extended (8 bytes, EXT=1):
96
- * Byte 0 : FrameType
97
- * Byte 1 : Flags (bit 7 = 1)
98
- * Byte 2–3 : Reserved (must be 0)
99
- * Byte 4–7 : PayloadLength (big-endian uint32)
100
- */
101
- export class FrameHeader {
102
- constructor(
103
- public readonly frameType: FrameType,
104
- public readonly flags: number,
105
- public readonly payloadLength: number,
106
- ) {}
107
-
108
- get isExtended(): boolean {
109
- return (this.flags & FrameFlags.EXT) !== 0;
110
- }
111
-
112
- get headerSize(): number {
113
- return this.isExtended ? EXTENDED_HEADER_SIZE : DEFAULT_HEADER_SIZE;
114
- }
115
-
116
- get encodingTier(): EncodingTier {
117
- return (this.flags & 0x03) as EncodingTier;
118
- }
119
-
120
- get isFinal(): boolean {
121
- return (this.flags & 0x04) !== 0;
122
- }
123
-
124
- get isEncrypted(): boolean {
125
- return (this.flags & 0x08) !== 0;
126
- }
127
-
128
- // ── Parsing ───────────────────────────────────────────────────────────────
129
-
130
- static parse(buf: Uint8Array): FrameHeader {
131
- if (buf.length < 2) {
132
- throw new NpsFrameError(
133
- `Buffer too small to read frame type and flags: need >= 2 bytes, got ${buf.length}.`,
134
- );
135
- }
136
-
137
- const flags = buf[1]!;
138
- const ext = (flags & FrameFlags.EXT) !== 0;
139
-
140
- if (ext) {
141
- if (buf.length < EXTENDED_HEADER_SIZE) {
142
- throw new NpsFrameError(
143
- `Buffer too small for extended frame header: need ${EXTENDED_HEADER_SIZE} bytes, got ${buf.length}.`,
144
- );
145
- }
146
- const view = new DataView(buf.buffer, buf.byteOffset);
147
- const payloadLength = view.getUint32(4, false); // big-endian
148
- return new FrameHeader(buf[0]! as FrameType, flags, payloadLength);
149
- }
150
-
151
- if (buf.length < DEFAULT_HEADER_SIZE) {
152
- throw new NpsFrameError(
153
- `Buffer too small for frame header: need ${DEFAULT_HEADER_SIZE} bytes, got ${buf.length}.`,
154
- );
155
- }
156
- const view = new DataView(buf.buffer, buf.byteOffset);
157
- const payloadLength = view.getUint16(2, false); // big-endian
158
- return new FrameHeader(buf[0]! as FrameType, flags, payloadLength);
159
- }
160
-
161
- // ── Serialisation ─────────────────────────────────────────────────────────
162
-
163
- toBytes(): Uint8Array {
164
- if (this.isExtended) {
165
- const buf = new Uint8Array(EXTENDED_HEADER_SIZE);
166
- const view = new DataView(buf.buffer);
167
- view.setUint8(0, this.frameType);
168
- view.setUint8(1, this.flags);
169
- view.setUint16(2, 0, false); // reserved
170
- view.setUint32(4, this.payloadLength, false);
171
- return buf;
172
- }
173
- const buf = new Uint8Array(DEFAULT_HEADER_SIZE);
174
- const view = new DataView(buf.buffer);
175
- view.setUint8(0, this.frameType);
176
- view.setUint8(1, this.flags);
177
- view.setUint16(2, this.payloadLength, false);
178
- return buf;
179
- }
180
-
181
- toString(): string {
182
- return `FrameHeader(frameType=0x${this.frameType.toString(16).padStart(2, "0")}, flags=0x${this.flags.toString(16).padStart(2, "0")}, payloadLength=${this.payloadLength})`;
183
- }
184
- }
package/src/core/index.ts DELETED
@@ -1,42 +0,0 @@
1
- // Copyright 2026 INNO LOTUS PTY LTD
2
- // SPDX-License-Identifier: Apache-2.0
3
- //
4
- // @labacacia/nps-sdk/core — public re-exports for NCP wire primitives.
5
- //
6
- // This module exposes the shipped OOP codec API used by NWP / NOP / NIP / NDP
7
- // clients. The parallel functional API under ./codecs/ and ./frame-header.js
8
- // remains importable by direct path but is not re-exported here to avoid
9
- // symbol collisions (both files define FrameType / EncodingTier / FrameHeader).
10
-
11
- // ── Frame primitives (OOP) ────────────────────────────────────────────────────
12
- export {
13
- FrameType,
14
- EncodingTier,
15
- FrameFlags,
16
- FrameHeader,
17
- DEFAULT_HEADER_SIZE,
18
- EXTENDED_HEADER_SIZE,
19
- DEFAULT_MAX_PAYLOAD,
20
- EXTENDED_MAX_PAYLOAD,
21
- } from "./frames.js";
22
-
23
- // ── Codec (OOP) ───────────────────────────────────────────────────────────────
24
- export {
25
- Tier1JsonCodec,
26
- Tier2MsgPackCodec,
27
- NpsFrameCodec,
28
- } from "./codec.js";
29
- export type { NpsFrame } from "./codec.js";
30
-
31
- // ── Registry (OOP) ────────────────────────────────────────────────────────────
32
- export { FrameRegistry } from "./registry.js";
33
- export type { FrameClass } from "./registry.js";
34
-
35
- // ── Anchor cache (OOP) ────────────────────────────────────────────────────────
36
- export { AnchorFrameCache } from "./cache.js";
37
-
38
- // ── Exceptions / Status / Canonical JSON ──────────────────────────────────────
39
- export * from "./exceptions.js";
40
- export * from "./status-codes.js";
41
- export { jcsStringify, sortKeysStringify } from "./canonical-json.js";
42
- export type { CryptoProvider } from "./crypto-provider.js";