@labacacia/nps-sdk 1.0.0-alpha.2 → 1.0.0-alpha.4

package/dist/nip/x509/verifier.js

@@ -0,0 +1,171 @@
+// Copyright 2026 INNO LOTUS PTY LTD
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Verifies NPS X.509 NID certificate chains per NPS-RFC-0002 §4.
+ *
+ * Stages (RFC §4.6):
+ * 1. Decode chain (base64url DER → @peculiar/x509 X509Certificate).
+ * 2. Leaf EKU check — critical, contains agent-identity OR node-identity OID.
+ * 3. Subject CN / SAN URI match against asserted NID.
+ * 4. Assurance-level extension match against asserted level (if both present).
+ * 5. Chain signature verification — leaf → intermediates → trusted root.
+ */
+import * as x509 from "@peculiar/x509";
+import { AssuranceLevel } from "../assurance-level.js";
+import * as ec from "../error-codes.js";
+import { EKU_AGENT_IDENTITY, EKU_NODE_IDENTITY, NID_ASSURANCE_LEVEL, OID_EXTENDED_KEY_USAGE, } from "./oids.js";
+x509.cryptoProvider.set(globalThis.crypto);
+function ok(leaf) {
+    return { valid: true, leaf };
+}
+function fail(errorCode, message) {
+    return { valid: false, errorCode, message };
+}
+export async function verify(opts) {
+    // Stage 1: decode chain ─────────────────────────────────────────────────
+    if (!opts.certChainBase64UrlDer.length) {
+        return fail(ec.CERT_FORMAT_INVALID, "cert_chain is empty");
+    }
+    let chain;
+    try {
+        chain = opts.certChainBase64UrlDer.map((s) => new x509.X509Certificate(b64uDecode(s).buffer));
+    }
+    catch (e) {
+        return fail(ec.CERT_FORMAT_INVALID, `DER decode failed: ${e.message}`);
+    }
+    const leaf = chain[0];
+    // Stage 2: EKU check ────────────────────────────────────────────────────
+    const ekuResult = checkLeafEku(leaf);
+    if (!ekuResult.valid)
+        return ekuResult;
+    // Stage 3: subject CN / SAN URI match ──────────────────────────────────
+    const subjectResult = checkSubjectNid(leaf, opts.assertedNid);
+    if (!subjectResult.valid)
+        return subjectResult;
+    // Stage 4: assurance-level extension ───────────────────────────────────
+    const assuranceResult = checkAssuranceLevel(leaf, opts.assertedAssuranceLevel);
+    if (!assuranceResult.valid)
+        return assuranceResult;
+    // Stage 5: chain signature verification ────────────────────────────────
+    const chainResult = await checkChainSignature(chain, opts.trustedRootCerts);
+    if (!chainResult.valid)
+        return chainResult;
+    return ok(leaf);
+}
+// ── Stage helpers ──────────────────────────────────────────────────────────
+function checkLeafEku(leaf) {
+    const ekuExt = leaf.extensions.find((e) => e.type === OID_EXTENDED_KEY_USAGE);
+    if (!ekuExt) {
+        return fail(ec.CERT_EKU_MISSING, "leaf has no ExtendedKeyUsage extension");
+    }
+    if (!ekuExt.critical) {
+        return fail(ec.CERT_EKU_MISSING, "ExtendedKeyUsage extension is not marked critical");
+    }
+    const usages = ekuExt.usages;
+    if (!usages.includes(EKU_AGENT_IDENTITY) && !usages.includes(EKU_NODE_IDENTITY)) {
+        return fail(ec.CERT_EKU_MISSING, "ExtendedKeyUsage does not contain agent-identity or node-identity OID");
+    }
+    return ok(leaf);
+}
+function checkSubjectNid(leaf, assertedNid) {
+    // @peculiar/x509 parses the subject DN; iterate to find CN.
+    const cn = extractCn(leaf.subject);
+    if (cn !== assertedNid) {
+        return fail(ec.CERT_SUBJECT_NID_MISMATCH, `leaf subject CN (${cn ?? "<missing>"}) does not match asserted NID (${assertedNid})`);
+    }
+    const sanExt = leaf.getExtension(x509.SubjectAlternativeNameExtension);
+    if (!sanExt) {
+        return fail(ec.CERT_SUBJECT_NID_MISMATCH, "leaf has no Subject Alternative Name extension");
+    }
+    // SubjectAlternativeNameExtension exposes general-name objects with `type: "url"` for URIs.
+    const uris = sanExt.names
+        .toJSON()
+        .filter((n) => n.type === "url")
+        .map((n) => n.value);
+    if (!uris.includes(assertedNid)) {
+        return fail(ec.CERT_SUBJECT_NID_MISMATCH, "no SAN URI matches asserted NID");
+    }
+    return ok(leaf);
+}
+function checkAssuranceLevel(leaf, asserted) {
+    if (asserted === null)
+        return ok(leaf);
+    const ext = leaf.extensions.find((e) => e.type === NID_ASSURANCE_LEVEL);
+    if (!ext) {
+        // Optional in v0.1 — pass silently.
+        return ok(leaf);
+    }
+    const der = new Uint8Array(ext.value);
+    // Decode ASN.1 ENUMERATED: tag=0x0A, len=0x01, content=<rank>.
+    if (der.length !== 3 || der[0] !== 0x0A || der[1] !== 0x01) {
+        return fail(ec.CERT_FORMAT_INVALID, `malformed assurance-level extension: ${Buffer.from(der).toString("hex")}`);
+    }
+    const rank = der[2];
+    let certLevel;
+    try {
+        certLevel = AssuranceLevel.fromRank(rank);
+    }
+    catch {
+        return fail(ec.ASSURANCE_UNKNOWN, `assurance-level extension contains unknown value: ${rank}`);
+    }
+    if (certLevel !== asserted) {
+        return fail(ec.ASSURANCE_MISMATCH, `cert assurance-level (${certLevel.wire}) does not match asserted (${asserted.wire})`);
+    }
+    return ok(leaf);
+}
+async function checkChainSignature(chain, trustedRoots) {
+    if (!trustedRoots.length) {
+        return fail(ec.CERT_FORMAT_INVALID, "no trusted X.509 roots configured");
+    }
+    try {
+        // Walk leaf → intermediates: each must be signed by its successor.
+        for (let i = 0; i < chain.length - 1; i++) {
+            const okStep = await chain[i].verify({ publicKey: await chain[i + 1].publicKey.export(), signatureOnly: true });
+            if (!okStep) {
+                return fail(ec.CERT_FORMAT_INVALID, `chain link ${i} signature did not verify`);
+            }
+        }
+        // The last cert in the chain MUST chain to a trusted root.
+        const last = chain[chain.length - 1];
+        for (const root of trustedRoots) {
+            if (Buffer.from(last.rawData).equals(Buffer.from(root.rawData))) {
+                return ok(chain[0]);
+            }
+            try {
+                const okStep = await last.verify({ publicKey: await root.publicKey.export(), signatureOnly: true });
+                if (okStep)
+                    return ok(chain[0]);
+            }
+            catch {
+                /* try next root */
+            }
+        }
+        return fail(ec.CERT_FORMAT_INVALID, "chain does not anchor to any trusted root");
+    }
+    catch (e) {
+        return fail(ec.CERT_FORMAT_INVALID, `chain signature verification error: ${e.message}`);
+    }
+}
+// ── helpers ────────────────────────────────────────────────────────────────
+function extractCn(dn) {
+    // @peculiar/x509 returns DN strings in RFC 4514 format ("CN=...,O=...").
+    for (const rdn of dn.split(",")) {
+        const trimmed = rdn.trim();
+        if (trimmed.startsWith("CN=")) {
+            let value = trimmed.slice(3);
+            // Strip surrounding quotes if any.
+            if (value.startsWith("\"") && value.endsWith("\"")) {
+                value = value.slice(1, -1);
+            }
+            // Unescape.
+            return value.replace(/\\([",+;<>\\])/g, "$1");
+        }
+    }
+    return null;
+}
+function b64uDecode(s) {
+    const padded = s + "=".repeat((4 - (s.length % 4)) % 4);
+    const std = padded.replace(/-/g, "+").replace(/_/g, "/");
+    return new Uint8Array(Buffer.from(std, "base64"));
+}
+//# sourceMappingURL=verifier.js.map

package/dist/nip/x509/verifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifier.js","sourceRoot":"","sources":["../../../src/nip/x509/verifier.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,sCAAsC;AAEtC;;;;;;;;;GASG;AAEH,OAAO,KAAK,IAAI,MAAM,gBAAgB,CAAC;AAEvC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,MAAM,mBAAmB,CAAC;AACxC,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,WAAW,CAAC;AAEnB,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;AAS3C,SAAS,EAAE,CAAC,IAA0B;IACpC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAC/B,CAAC;AAED,SAAS,IAAI,CAAC,SAAiB,EAAE,OAAe;IAC9C,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;AAC9C,CAAC;AASD,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,IAAmB;IAC9C,0EAA0E;IAC1E,IAAI,CAAC,IAAI,CAAC,qBAAqB,CAAC,MAAM,EAAE,CAAC;QACvC,OAAO,IAAI,CAAC,EAAE,CAAC,mBAAmB,EAAE,qBAAqB,CAAC,CAAC;IAC7D,CAAC;IACD,IAAI,KAA6B,CAAC;IAClC,IAAI,CAAC;QACH,KAAK,GAAG,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,MAAqB,CAAC,CAAC,CAAC;IAC/G,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,IAAI,CAAC,EAAE,CAAC,mBAAmB,EAAE,sBAAuB,CAAW,CAAC,OAAO,EAAE,CAAC,CAAC;IACpF,CAAC;IAED,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IAEtB,0EAA0E;IAC1E,MAAM,SAAS,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACrC,IAAI,CAAC,SAAS,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAEvC,yEAAyE;IACzE,MAAM,aAAa,GAAG,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IAC9D,IAAI,CAAC,aAAa,CAAC,KAAK;QAAE,OAAO,aAAa,CAAC;IAE/C,yEAAyE;IACzE,MAAM,eAAe,GAAG,mBAAmB,CAAC,IAAI,EAAE,IAAI,CAAC,sBAAsB,CAAC,CAAC;IAC/E,IAAI,CAAC,eAAe,CAAC,KAAK;QAAE,OAAO,eAAe,CAAC;IAEnD,yEAAyE;IACzE,MAAM,WAAW,GAAG,MAAM,mBAAmB,CAAC,KAAK,EAAE,IAAI,CAAC,gBAAgB,CAAC,CAAC;IAC5E,IAAI,CAAC,WAAW,CAAC,KAAK;QAAE,OAAO,WAAW,CAAC;IAE3C,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;AAClB,CAAC;AAED,8EAA8E;AAE9E,SAAS,YAAY,CAAC,IAA0B;IAC9C,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,CACjC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,sBAAsB,CACK,CAAC;IAChD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,IAAI,CAAC,EAAE,CAAC,gBAAgB,EAAE,wCAAwC,CAAC,CAAC;IAC7E,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;QACrB,OAAO,IAAI,CAAC,EAAE,CAAC,gBAAgB,EAAE,mDAAmD,CAAC,CAAC;IACxF,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,MAA2B,CAAC;IAClD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC;QAChF,OAAO,IAAI,CAAC,EAAE,CAAC,gBAAgB,EAC7B,uEAAuE,CAAC,CAAC;IAC7E,CAAC;IACD,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;AAClB,CAAC;AAED,SAAS,eAAe,CAAC,IAA0B,EAAE,WAAmB;IACtE,4DAA4D;IAC5D,MAAM,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,EAAE,KAAK,WAAW,EAAE,CAAC;QACvB,OAAO,IAAI,CAAC,EAAE,CAAC,yBAAyB,EACtC,oBAAoB,EAAE,IAAI,WAAW,kCAAkC,WAAW,GAAG,CAAC,CAAC;IAC3F,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,+BAA+B,CAAC,CAAC;IACvE,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,IAAI,CAAC,EAAE,CAAC,yBAAyB,EAAE,gDAAgD,CAAC,CAAC;IAC9F,CAAC;IACD,4FAA4F;IAC5F,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK;SACtB,MAAM,EAAE;SACR,MAAM,CAAC,CAAC,CAAmB,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC;SACjD,GAAG,CAAC,CAAC,CAAoB,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAC1C,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;QAChC,OAAO,IAAI,CAAC,EAAE,CAAC,yBAAyB,EAAE,iCAAiC,CAAC,CAAC;IAC/E,CAAC;IACD,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;AAClB,CAAC;AAED,SAAS,mBAAmB,CAC1B,IAA0B,EAAE,QAA+B;IAE3D,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;IACvC,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,mBAAmB,CAAC,CAAC;IACxE,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,oCAAoC;QACpC,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACtC,+DAA+D;IAC/D,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QAC3D,OAAO,IAAI,CAAC,EAAE,CAAC,mBAAmB,EAChC,wCAAwC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAChF,CAAC;IACD,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;IACpB,IAAI,SAAyB,CAAC;IAC9B,IAAI,CAAC;QACH,SAAS,GAAG,cAAc,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC,EAAE,CAAC,iBAAiB,EAC9B,qDAAqD,IAAI,EAAE,CAAC,CAAC;IACjE,CAAC;IACD,IAAI,SAAS,KAAK,QAAQ,EAAE,CAAC;QAC3B,OAAO,IAAI,CAAC,EAAE,CAAC,kBAAkB,EAC/B,yBAAyB,SAAS,CAAC,IAAI,8BAA8B,QAAQ,CAAC,IAAI,GAAG,CAAC,CAAC;IAC3F,CAAC;IACD,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;AAClB,CAAC;AAED,KAAK,UAAU,mBAAmB,CAChC,KAAsC,EACtC,YAA6C;IAE7C,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC,EAAE,CAAC,mBAAmB,EAAE,mCAAmC,CAAC,CAAC;IAC3E,CAAC;IACD,IAAI,CAAC;QACH,mEAAmE;QACnE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC1C,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;YAChH,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,OAAO,IAAI,CAAC,EAAE,CAAC,mBAAmB,EAAE,cAAc,CAAC,2BAA2B,CAAC,CAAC;YAClF,CAAC;QACH,CAAC;QACD,2DAA2D;QAC3D,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QACrC,KAAK,MAAM,IAAI,IAAI,YAAY,EAAE,CAAC;YAChC,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;gBAChE,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YACtB,CAAC;YACD,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;gBACpG,IAAI,MAAM;oBAAE,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YAClC,CAAC;YAAC,MAAM,CAAC;gBACP,mBAAmB;YACrB,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC,EAAE,CAAC,mBAAmB,EAAE,2CAA2C,CAAC,CAAC;IACnF,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,IAAI,CAAC,EAAE,CAAC,mBAAmB,EAChC,uCAAwC,CAAW,CAAC,OAAO,EAAE,CAAC,CAAC;IACnE,CAAC;AACH,CAAC;AAED,8EAA8E;AAE9E,SAAS,SAAS,CAAC,EAAU;IAC3B,yEAAyE;IACzE,KAAK,MAAM,GAAG,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QAChC,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;QAC3B,IAAI,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;YAC9B,IAAI,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAC7B,mCAAmC;YACnC,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;gBACnD,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YAC7B,CAAC;YACD,YAAY;YACZ,OAAO,KAAK,CAAC,OAAO,CAAC,iBAAiB,EAAE,IAAI,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,UAAU,CAAC,CAAS;IAC3B,MAAM,MAAM,GAAG,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACxD,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACzD,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC;AACpD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@labacacia/nps-sdk",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.4",
   "description": "TypeScript SDK for the Neural Protocol Suite (NPS) — NCP, NWP, NIP, NDP, NOP",
   "type": "module",
   "main": "dist/index.js",
@@ -53,6 +53,7 @@
     "@msgpack/msgpack": "^3.0.0",
     "@noble/ed25519": "^2.1.0",
     "@noble/hashes": "^1.4.0",
+    "@peculiar/x509": "^1.12.0",
     "canonicalize": "^2.0.0",
     "fast-json-patch": "^3.1.1"
   },

package/src/ncp/index.ts

@@ -10,3 +10,4 @@ export * from "./ncp-error-codes.js";
 export * from "./ncp-patch-format.js";
 export * from "./handshake.js";
 export * from "./stream-manager.js";
+export * from "./preamble.js";

package/src/ncp/ncp-error-codes.ts

@@ -12,6 +12,8 @@ export const NCP_ERROR_CODES = {
   // Implementation-only codes (not in spec §6 — see test_results.md spec question 2)
   NCP_FRAME_PARSE_ERROR: "NCP-FRAME-PARSE-ERROR",
   NCP_FRAME_INCOMPLETE: "NCP-FRAME-INCOMPLETE",
+  // NPS-RFC-0001 — native-mode preamble
+  NCP_PREAMBLE_INVALID: "NCP-PREAMBLE-INVALID",
   // Spec-defined codes
   NCP_FRAME_UNKNOWN_TYPE: "NCP-FRAME-UNKNOWN-TYPE",
   NCP_FRAME_PAYLOAD_TOO_LARGE: "NCP-FRAME-PAYLOAD-TOO-LARGE",

package/src/ncp/preamble.ts

@@ -0,0 +1,79 @@
+// Copyright 2026 INNO LOTUS PTY LTD
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * NCP native-mode connection preamble — the 8-byte ASCII constant
+ * `"NPS/1.0\n"` that every native-mode client MUST emit immediately
+ * after the transport handshake and before its first HelloFrame.
+ * Defined by NPS-RFC-0001 and NPS-1 NCP §2.6.1.
+ *
+ * HTTP-mode connections do not use the preamble.
+ */
+
+export const PREAMBLE_LITERAL = "NPS/1.0\n";
+export const PREAMBLE_LENGTH = 8;
+export const PREAMBLE_BYTES: Uint8Array = new TextEncoder().encode(PREAMBLE_LITERAL);
+/** Validation timeout in milliseconds (NPS-RFC-0001 §4.1). */
+export const PREAMBLE_READ_TIMEOUT_MS = 10_000;
+/** Maximum delay before closing after a mismatch, in milliseconds. */
+export const PREAMBLE_CLOSE_DEADLINE_MS = 500;
+
+export const PREAMBLE_ERROR_CODE  = "NCP-PREAMBLE-INVALID";
+export const PREAMBLE_STATUS_CODE = "NPS-PROTO-PREAMBLE-INVALID";
+
+export class NcpPreambleInvalidError extends Error {
+  readonly errorCode  = PREAMBLE_ERROR_CODE;
+  readonly statusCode = PREAMBLE_STATUS_CODE;
+
+  constructor(reason: string) {
+    super(reason);
+    this.name = "NcpPreambleInvalidError";
+  }
+}
+
+/**
+ * Returns `true` iff `buf` starts with the 8-byte NPS/1.0 preamble.
+ * Safe to call with shorter buffers.
+ */
+export function preambleMatches(buf: Uint8Array): boolean {
+  if (buf.length < PREAMBLE_LENGTH) return false;
+  for (let i = 0; i < PREAMBLE_LENGTH; i++) {
+    if (buf[i] !== PREAMBLE_BYTES[i]) return false;
+  }
+  return true;
+}
+
+/**
+ * Validates a presumed-preamble buffer.
+ * Returns `{ valid: true, reason: "" }` on success or `{ valid: false, reason }` on failure.
+ */
+export function tryValidatePreamble(buf: Uint8Array): { valid: boolean; reason: string } {
+  if (buf.length < PREAMBLE_LENGTH) {
+    return { valid: false, reason: `short read (${buf.length}/${PREAMBLE_LENGTH} bytes); peer is not speaking NCP` };
+  }
+  if (!preambleMatches(buf)) {
+    // "NPS/" = 0x4E 0x50 0x53 0x2F
+    const isNps = buf[0] === 0x4e && buf[1] === 0x50 && buf[2] === 0x53 && buf[3] === 0x2f;
+    if (isNps) {
+      return { valid: false, reason: "future-major-version NPS preamble; close with NPS-PREAMBLE-UNSUPPORTED-VERSION diagnostic" };
+    }
+    return { valid: false, reason: "preamble mismatch; peer is not speaking NPS/1.x" };
+  }
+  return { valid: true, reason: "" };
+}
+
+/**
+ * Validates a presumed-preamble buffer, throwing {@link NcpPreambleInvalidError} on mismatch.
+ */
+export function validatePreamble(buf: Uint8Array): void {
+  const { valid, reason } = tryValidatePreamble(buf);
+  if (!valid) throw new NcpPreambleInvalidError(reason);
+}
+
+/**
+ * Writes the preamble bytes to `writer`.
+ * `writer` must expose a `write(buf: Uint8Array): void` method (e.g. Node.js `net.Socket`).
+ */
+export function writePreamble(writer: { write(buf: Uint8Array): void }): void {
+  writer.write(PREAMBLE_BYTES);
+}

package/src/nip/acme/client.ts

@@ -0,0 +1,185 @@
+// Copyright 2026 INNO LOTUS PTY LTD
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * ACME client implementing the `agent-01` challenge type per NPS-RFC-0002 §4.4.
+ *
+ * Flow: newNonce → newAccount → newOrder → fetch authz → sign challenge token →
+ * finalize with CSR → fetch leaf cert.
+ */
+
+import * as ed25519 from "@noble/ed25519";
+import { sha512 } from "@noble/hashes/sha512";
+import * as x509 from "@peculiar/x509";
+
+import * as Jws from "./jws.js";
+import type {
+  Authorization, Challenge, Directory, FinalizePayload,
+  Identifier, NewAccountPayload, NewOrderPayload, Order,
+} from "./messages.js";
+import * as wire from "./wire.js";
+
+ed25519.etc.sha512Sync = (...m) => sha512(ed25519.etc.concatBytes(...m));
+x509.cryptoProvider.set(globalThis.crypto);
+
+export interface AcmeClientOptions {
+  /** ACME directory URL. */
+  directoryUrl: string;
+  /** Account/agent Ed25519 private key (32-byte raw). */
+  privateKey:   Uint8Array;
+  /** Account/agent Ed25519 public key (32-byte raw). */
+  publicKey:    Uint8Array;
+  /** Web Crypto Ed25519 keypair for CSR signing (must match privateKey). */
+  webCryptoKeys: CryptoKeyPair;
+}
+
+export class AcmeClient {
+  private directory:  Directory | null = null;
+  private accountUrl: string    | null = null;
+  private lastNonce:  string    | null = null;
+
+  constructor(public readonly options: AcmeClientOptions) {}
+
+  /** Drive the full agent-01 flow for `nid`. Returns issued PEM cert chain. */
+  async issueAgentCert(nid: string): Promise<string> {
+    await this.ensureDirectory();
+    if (this.accountUrl === null) await this.newAccount();
+    const order = await this.newOrder(nid);
+    const authz = await this.fetchAuthz(order.authorizations[0]);
+    await this.respondAgent01(authz);
+    const finalized = await this.finalizeOrder(order, nid);
+    return this.downloadPem(finalized.certificate!);
+  }
+
+  // ── Stages ───────────────────────────────────────────────────────────────
+
+  private async ensureDirectory(): Promise<void> {
+    if (this.directory !== null) return;
+    const resp = await fetch(this.options.directoryUrl);
+    ensureSuccess(resp);
+    this.directory = await resp.json() as Directory;
+    await this.refreshNonce();
+  }
+
+  private async refreshNonce(): Promise<void> {
+    const resp = await fetch(this.directory!.newNonce, { method: "HEAD" });
+    ensureSuccess(resp);
+    this.lastNonce = resp.headers.get("Replay-Nonce");
+    if (this.lastNonce === null) {
+      throw new Error("server omitted Replay-Nonce");
+    }
+  }
+
+  private async newAccount(): Promise<void> {
+    const jwk = Jws.jwkFromPublicKey(this.options.publicKey);
+    const env = Jws.sign(
+      { alg: Jws.ALG_EDDSA, nonce: this.lastNonce!, url: this.directory!.newAccount, jwk },
+      { termsOfServiceAgreed: true } as NewAccountPayload,
+      this.options.privateKey);
+
+    const resp = await this.post(this.directory!.newAccount, env);
+    ensureSuccess(resp);
+    this.accountUrl = resp.headers.get("Location");
+    if (this.accountUrl === null) throw new Error("server omitted account Location");
+    this.captureNonce(resp);
+  }
+
+  private async newOrder(nid: string): Promise<Order> {
+    const env = Jws.sign(
+      { alg: Jws.ALG_EDDSA, nonce: this.lastNonce!, url: this.directory!.newOrder, kid: this.accountUrl! },
+      {
+        identifiers: [{ type: wire.IDENTIFIER_TYPE_NID, value: nid } as Identifier],
+      } as NewOrderPayload,
+      this.options.privateKey);
+
+    const resp = await this.post(this.directory!.newOrder, env);
+    ensureSuccess(resp);
+    this.captureNonce(resp);
+    return await resp.json() as Order;
+  }
+
+  private async fetchAuthz(url: string): Promise<Authorization> {
+    // POST-as-GET (RFC 8555 §6.3).
+    const env = Jws.sign(
+      { alg: Jws.ALG_EDDSA, nonce: this.lastNonce!, url, kid: this.accountUrl! },
+      null,
+      this.options.privateKey);
+    const resp = await this.post(url, env);
+    ensureSuccess(resp);
+    this.captureNonce(resp);
+    return await resp.json() as Authorization;
+  }
+
+  private async respondAgent01(authz: Authorization): Promise<void> {
+    const challenge = authz.challenges.find((c) => c.type === wire.CHALLENGE_AGENT_01);
+    if (!challenge) throw new Error("authz has no agent-01 challenge");
+
+    // Sign the challenge token with the account/NID private key.
+    const tokenBytes = new TextEncoder().encode(challenge.token);
+    const sig = ed25519.sign(tokenBytes, this.options.privateKey);
+
+    const env = Jws.sign(
+      { alg: Jws.ALG_EDDSA, nonce: this.lastNonce!, url: challenge.url, kid: this.accountUrl! },
+      { agent_signature: Jws.b64uEncode(sig) },
+      this.options.privateKey);
+    const resp = await this.post(challenge.url, env);
+    ensureSuccess(resp);
+    this.captureNonce(resp);
+  }
+
+  private async finalizeOrder(order: Order, nid: string): Promise<Order> {
+    const csrDer = await this.buildCsr(nid);
+    const env = Jws.sign(
+      { alg: Jws.ALG_EDDSA, nonce: this.lastNonce!, url: order.finalize, kid: this.accountUrl! },
+      { csr: Jws.b64uEncode(csrDer) } as FinalizePayload,
+      this.options.privateKey);
+    const resp = await this.post(order.finalize, env);
+    ensureSuccess(resp);
+    this.captureNonce(resp);
+    return await resp.json() as Order;
+  }
+
+  private async downloadPem(certUrl: string): Promise<string> {
+    const env = Jws.sign(
+      { alg: Jws.ALG_EDDSA, nonce: this.lastNonce!, url: certUrl, kid: this.accountUrl! },
+      null,
+      this.options.privateKey);
+    const resp = await this.post(certUrl, env);
+    ensureSuccess(resp);
+    this.captureNonce(resp);
+    return await resp.text();
+  }
+
+  // ── helpers ──────────────────────────────────────────────────────────────
+
+  private async post(url: string, env: Jws.Envelope): Promise<Response> {
+    return await fetch(url, {
+      method:  "POST",
+      headers: { "Content-Type": wire.CONTENT_TYPE_JOSE_JSON },
+      body:    JSON.stringify(env),
+    });
+  }
+
+  private captureNonce(resp: Response): void {
+    const nonce = resp.headers.get("Replay-Nonce");
+    if (nonce !== null) this.lastNonce = nonce;
+  }
+
+  private async buildCsr(nid: string): Promise<Uint8Array> {
+    const csr = await x509.Pkcs10CertificateRequestGenerator.create({
+      name: `CN=${nid.replace(/([",+;<>\\])/g, "\\$1")}`,
+      keys: this.options.webCryptoKeys,
+      signingAlgorithm: { name: "Ed25519" },
+      extensions: [
+        new x509.SubjectAlternativeNameExtension([{ type: "url", value: nid }], false),
+      ],
+    });
+    return new Uint8Array(csr.rawData);
+  }
+}
+
+function ensureSuccess(resp: Response): void {
+  if (!resp.ok) {
+    throw new Error(`ACME ${resp.url} HTTP ${resp.status}`);
+  }
+}

package/src/nip/acme/index.ts

@@ -0,0 +1,8 @@
+// Copyright 2026 INNO LOTUS PTY LTD
+// SPDX-License-Identifier: Apache-2.0
+
+export * from "./client.js";
+export * from "./jws.js";
+export * from "./messages.js";
+export * from "./server.js";
+export * from "./wire.js";