@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.
- package/CHANGELOG.cn.md +29 -5
- package/CHANGELOG.md +29 -5
- package/LICENSE +0 -0
- package/NOTICE +0 -0
- package/README.cn.md +8 -13
- package/README.md +8 -13
- package/dist/nip/index.d.ts +1 -0
- package/dist/nip/index.d.ts.map +1 -1
- package/dist/nip/index.js +2 -0
- package/dist/nip/index.js.map +1 -1
- package/dist/nip/reputation-client.d.ts +116 -0
- package/dist/nip/reputation-client.d.ts.map +1 -0
- package/dist/nip/reputation-client.js +261 -0
- package/dist/nip/reputation-client.js.map +1 -0
- package/dist/nip/x509/oids.d.ts +9 -10
- package/dist/nip/x509/oids.d.ts.map +1 -1
- package/dist/nip/x509/oids.js +3 -4
- package/dist/nip/x509/oids.js.map +1 -1
- package/dist/nwp/anchor-client.d.ts +109 -0
- package/dist/nwp/anchor-client.d.ts.map +1 -0
- package/dist/nwp/anchor-client.js +279 -0
- package/dist/nwp/anchor-client.js.map +1 -0
- package/dist/nwp/index.d.ts +1 -1
- package/dist/nwp/index.d.ts.map +1 -1
- package/dist/nwp/index.js +1 -1
- package/dist/nwp/index.js.map +1 -1
- package/doc/nps-sdk.core.cn.md +0 -0
- package/doc/nps-sdk.core.md +0 -0
- package/doc/nps-sdk.ncp.cn.md +0 -0
- package/doc/nps-sdk.ncp.md +0 -0
- package/doc/nps-sdk.ndp.cn.md +0 -0
- package/doc/nps-sdk.ndp.md +0 -0
- package/doc/nps-sdk.nop.cn.md +0 -0
- package/doc/nps-sdk.nop.md +0 -0
- package/doc/overview.cn.md +0 -0
- package/doc/overview.md +0 -0
- package/package.json +12 -1
- package/CONTRIBUTING.cn.md +0 -35
- package/CONTRIBUTING.md +0 -35
- package/dist/nwp/error-codes.d.ts +0 -42
- package/dist/nwp/error-codes.d.ts.map +0 -1
- package/dist/nwp/error-codes.js +0 -53
- package/dist/nwp/error-codes.js.map +0 -1
- package/nip-ca-server/Dockerfile +0 -27
- package/nip-ca-server/README.md +0 -45
- package/nip-ca-server/db/001_init.sql +0 -25
- package/nip-ca-server/docker-compose.yml +0 -29
- package/nip-ca-server/package.json +0 -23
- package/nip-ca-server/src/ca.ts +0 -155
- package/nip-ca-server/src/db.ts +0 -104
- package/nip-ca-server/src/index.ts +0 -157
- package/nip-ca-server/tsconfig.json +0 -13
- package/src/core/anchor-cache.ts +0 -129
- package/src/core/cache.ts +0 -93
- package/src/core/canonical-json.ts +0 -50
- package/src/core/codec.ts +0 -158
- package/src/core/codecs/index.ts +0 -5
- package/src/core/codecs/ncp-codec.ts +0 -170
- package/src/core/codecs/tier1-json-codec.ts +0 -33
- package/src/core/codecs/tier2-msgpack-codec.ts +0 -30
- package/src/core/crypto-provider.ts +0 -47
- package/src/core/exceptions.ts +0 -57
- package/src/core/frame-header.ts +0 -282
- package/src/core/frame-registry.ts +0 -91
- package/src/core/frames.ts +0 -184
- package/src/core/index.ts +0 -42
- package/src/core/registry.ts +0 -28
- package/src/core/status-codes.ts +0 -47
- package/src/index.ts +0 -10
- package/src/ncp/frames/anchor-frame.ts +0 -87
- package/src/ncp/frames/caps-frame.ts +0 -59
- package/src/ncp/frames/diff-frame.ts +0 -69
- package/src/ncp/frames/error-frame.ts +0 -26
- package/src/ncp/frames/hello-frame.ts +0 -50
- package/src/ncp/frames/stream-frame.ts +0 -35
- package/src/ncp/frames.ts +0 -251
- package/src/ncp/handshake.ts +0 -95
- package/src/ncp/index.ts +0 -13
- package/src/ncp/ncp-error-codes.ts +0 -36
- package/src/ncp/ncp-patch-format.ts +0 -16
- package/src/ncp/preamble.ts +0 -79
- package/src/ncp/registry.ts +0 -15
- package/src/ncp/stream-manager.ts +0 -212
- package/src/ndp/dns-txt.ts +0 -86
- package/src/ndp/frames.ts +0 -124
- package/src/ndp/index.ts +0 -8
- package/src/ndp/ndp-registry.ts +0 -116
- package/src/ndp/registry.ts +0 -12
- package/src/ndp/validator.ts +0 -64
- package/src/nip/acme/client.ts +0 -185
- package/src/nip/acme/index.ts +0 -8
- package/src/nip/acme/jws.ts +0 -109
- package/src/nip/acme/messages.ts +0 -85
- package/src/nip/acme/server.ts +0 -480
- package/src/nip/acme/wire.ts +0 -24
- package/src/nip/assurance-level.ts +0 -40
- package/src/nip/cert-format.ts +0 -9
- package/src/nip/error-codes.ts +0 -38
- package/src/nip/frames.ts +0 -138
- package/src/nip/identity.ts +0 -113
- package/src/nip/index.ts +0 -14
- package/src/nip/registry.ts +0 -12
- package/src/nip/verifier.ts +0 -122
- package/src/nip/x509/builder.ts +0 -91
- package/src/nip/x509/index.ts +0 -6
- package/src/nip/x509/oids.ts +0 -28
- package/src/nip/x509/verifier.ts +0 -214
- package/src/nop/client.ts +0 -103
- package/src/nop/frames.ts +0 -181
- package/src/nop/index.ts +0 -7
- package/src/nop/models.ts +0 -79
- package/src/nop/nop-types.ts +0 -208
- package/src/nop/registry.ts +0 -13
- package/src/nwp/client.ts +0 -114
- package/src/nwp/error-codes.ts +0 -62
- package/src/nwp/frames.ts +0 -116
- package/src/nwp/index.ts +0 -7
- package/src/nwp/registry.ts +0 -11
- package/src/setup.ts +0 -32
- package/tests/_rfc0002-keys.ts +0 -57
- package/tests/core/anchor-cache.test.ts +0 -242
- package/tests/core/codec.test.ts +0 -205
- package/tests/core/frame-registry.test.ts +0 -46
- package/tests/core.test.ts +0 -327
- package/tests/ncp/diff-binary-bitset.test.ts +0 -107
- package/tests/ncp/e2e-enc-reject.test.ts +0 -93
- package/tests/ncp/err-error-frame.test.ts +0 -152
- package/tests/ncp/frames.test.ts +0 -359
- package/tests/ncp/framing.test.ts +0 -233
- package/tests/ncp/hello-frame.test.ts +0 -122
- package/tests/ncp/inline-anchor.test.ts +0 -88
- package/tests/ncp/preamble.test.ts +0 -93
- package/tests/ncp/security.test.ts +0 -184
- package/tests/ncp/stream-window.test.ts +0 -167
- package/tests/ncp/stream.test.ts +0 -242
- package/tests/ncp/version-negotiation.test.ts +0 -123
- package/tests/ndp.test.ts +0 -377
- package/tests/nip-acme-agent01.test.ts +0 -192
- package/tests/nip-x509.test.ts +0 -280
- package/tests/nip.test.ts +0 -184
- package/tests/nop.test.ts +0 -344
- package/tests/nwp.test.ts +0 -237
- package/tsconfig.json +0 -20
- package/tsup.config.ts +0 -20
- 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
|
-
}
|
package/src/core/exceptions.ts
DELETED
|
@@ -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
|
-
}
|
package/src/core/frame-header.ts
DELETED
|
@@ -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
|
-
}
|
package/src/core/frames.ts
DELETED
|
@@ -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";
|