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

package/src/nip/frames.ts

@@ -3,6 +3,7 @@
 
 import { EncodingTier, FrameType } from "../core/frames.js";
 import type { NpsFrame } from "../core/codec.js";
+import { AssuranceLevel } from "./assurance-level.js";
 
 export interface IdentMetadata {
   issuer:       string;
@@ -12,35 +13,66 @@ export interface IdentMetadata {
   scopes?:       readonly string[];
 }
 
+export interface IdentFrameOptions {
+  assuranceLevel?: AssuranceLevel | null;   // RFC-0003
+  certFormat?:     string | null;            // RFC-0002 — null treated as "v1-proprietary"
+  certChain?:      readonly string[] | null; // RFC-0002 — base64url(DER), [leaf, intermediates..., root]
+}
+
 export class IdentFrame implements NpsFrame {
   readonly frameType     = FrameType.IDENT;
   readonly preferredTier = EncodingTier.MSGPACK;
 
+  readonly assuranceLevel: AssuranceLevel | null;
+  readonly certFormat:     string | null;
+  readonly certChain:      readonly string[] | null;
+
   constructor(
     public readonly nid:       string,
     public readonly pubKey:    string,
     public readonly metadata:  IdentMetadata,
     public readonly signature: string,
-  ) {}
+    options:                    IdentFrameOptions = {},
+  ) {
+    this.assuranceLevel = options.assuranceLevel ?? null;
+    this.certFormat     = options.certFormat     ?? null;
+    this.certChain      = options.certChain      ?? null;
+  }
 
   unsignedDict(): Record<string, unknown> {
-    return {
+    const out: Record<string, unknown> = {
       nid:      this.nid,
       pub_key:  this.pubKey,
       metadata: this.metadata,
     };
+    if (this.assuranceLevel !== null) out["assurance_level"] = this.assuranceLevel.wire;
+    // cert_format / cert_chain deliberately excluded from the signed payload —
+    // the v1 Ed25519 signature covers only (nid, pub_key, metadata, [assurance_level]).
+    return out;
   }
 
   toDict(): Record<string, unknown> {
-    return { ...this.unsignedDict(), signature: this.signature };
+    const out: Record<string, unknown> = { ...this.unsignedDict(), signature: this.signature };
+    if (this.certFormat !== null) out["cert_format"] = this.certFormat;
+    if (this.certChain  !== null) out["cert_chain"]  = [...this.certChain];
+    return out;
   }
 
   static fromDict(data: Record<string, unknown>): IdentFrame {
+    const lvl = data["assurance_level"];
+    const assuranceLevel = typeof lvl === "string" ? AssuranceLevel.fromWire(lvl) : null;
+    const chainRaw = data["cert_chain"];
+    const certChain = Array.isArray(chainRaw) ? (chainRaw as string[]) : null;
     return new IdentFrame(
       data["nid"]       as string,
       data["pub_key"]   as string,
       data["metadata"]  as IdentMetadata,
       data["signature"] as string,
+      {
+        assuranceLevel,
+        certFormat: (data["cert_format"] as string | undefined) ?? null,
+        certChain,
+      },
     );
   }
 }

package/src/nip/index.ts

@@ -4,3 +4,11 @@
 export * from "./frames.js";
 export * from "./identity.js";
 export { registerNipFrames } from "./registry.js";
+
+// RFC-0002 / RFC-0003 — X.509 + ACME + dual-trust verifier
+export * from "./assurance-level.js";
+export * from "./cert-format.js";
+export * from "./error-codes.js";
+export * from "./verifier.js";
+export * as x509 from "./x509/index.js";
+export * as acme from "./acme/index.js";

package/src/nip/verifier.ts

@@ -0,0 +1,122 @@
+// Copyright 2026 INNO LOTUS PTY LTD
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * NipIdentVerifier — Phase 1 dual-trust IdentFrame verifier per NPS-RFC-0002 §8.1.
+ *
+ * Steps:
+ *   1.  v1 Ed25519 signature check against the issuer's CA public key.
+ *   2.  Optional minimum assurance level check.
+ *   3b. X.509 chain validation (only if `cert_format === "v2-x509"` AND
+ *       `trustedX509Roots` is configured).
+ */
+
+import * as ed25519 from "@noble/ed25519";
+import { sha512 } from "@noble/hashes/sha512";
+import type { X509Certificate } from "@peculiar/x509";
+
+import { AssuranceLevel } from "./assurance-level.js";
+import * as cf from "./cert-format.js";
+import * as ec from "./error-codes.js";
+import type { IdentFrame } from "./frames.js";
+import { verify as verifyX509 } from "./x509/verifier.js";
+
+// noble/ed25519 needs sha512 wired up.
+ed25519.etc.sha512Sync = (...m) => sha512(ed25519.etc.concatBytes(...m));
+
+export interface NipVerifierOptions {
+  /** Map of issuer NID → CA public key string (`ed25519:<hex>`). */
+  trustedCaPublicKeys?: Readonly<Record<string, string>>;
+  /** X.509 trust anchors. Empty/undefined makes Step 3b reject v2 frames. */
+  trustedX509Roots?:    readonly X509Certificate[];
+  /** Minimum required assurance level (NPS-RFC-0003). */
+  minAssuranceLevel?:   AssuranceLevel;
+}
+
+export interface NipIdentVerifyResult {
+  valid:      boolean;
+  stepFailed: number;       // 0 = none, 1 = sig, 2 = assurance, 3 = X.509
+  errorCode?: string;
+  message?:   string;
+}
+
+function ok(): NipIdentVerifyResult { return { valid: true, stepFailed: 0 }; }
+
+function fail(stepFailed: number, errorCode: string, message: string): NipIdentVerifyResult {
+  return { valid: false, stepFailed, errorCode, message };
+}
+
+export class NipIdentVerifier {
+  constructor(public readonly options: NipVerifierOptions) {}
+
+  async verify(frame: IdentFrame, issuerNid: string): Promise<NipIdentVerifyResult> {
+    // Step 1: v1 Ed25519 signature check ────────────────────────────────
+    const caPubKeyStr = this.options.trustedCaPublicKeys?.[issuerNid];
+    if (caPubKeyStr === undefined) {
+      return fail(1, ec.CERT_UNTRUSTED_ISSUER,
+        `no trusted CA public key for issuer: ${issuerNid}`);
+    }
+    if (!frame.signature?.startsWith("ed25519:")) {
+      return fail(1, ec.CERT_SIGNATURE_INVALID, "missing or malformed signature");
+    }
+    try {
+      const caPubBytes = parsePubKeyString(caPubKeyStr);
+      const sigBytes   = Buffer.from(frame.signature.slice("ed25519:".length), "base64");
+      const canonical  = canonicalJson(frame.unsignedDict());
+      const msg        = new TextEncoder().encode(canonical);
+      if (!ed25519.verify(sigBytes, msg, caPubBytes)) {
+        return fail(1, ec.CERT_SIGNATURE_INVALID,
+          "v1 Ed25519 signature did not verify against issuer CA key");
+      }
+    } catch (e) {
+      return fail(1, ec.CERT_SIGNATURE_INVALID,
+        `v1 signature verification error: ${(e as Error).message}`);
+    }
+
+    // Step 2: minimum assurance level ───────────────────────────────────
+    const minLevel = this.options.minAssuranceLevel;
+    if (minLevel !== undefined) {
+      const got = frame.assuranceLevel ?? AssuranceLevel.ANONYMOUS;
+      if (!got.meetsOrExceeds(minLevel)) {
+        return fail(2, ec.ASSURANCE_MISMATCH,
+          `assurance_level (${got.wire}) below required minimum (${minLevel.wire})`);
+      }
+    }
+
+    // Step 3b: X.509 chain check (only if both opt-ins present) ──────────
+    const trustedRoots = this.options.trustedX509Roots ?? [];
+    const hasV2Trust = trustedRoots.length > 0;
+    const isV2Frame  = frame.certFormat === cf.V2_X509;
+    if (hasV2Trust && isV2Frame) {
+      const x509Result = await verifyX509({
+        certChainBase64UrlDer:  frame.certChain ?? [],
+        assertedNid:            frame.nid,
+        assertedAssuranceLevel: frame.assuranceLevel,
+        trustedRootCerts:       trustedRoots,
+      });
+      if (!x509Result.valid) {
+        return fail(3,
+          x509Result.errorCode ?? ec.CERT_FORMAT_INVALID,
+          x509Result.message   ?? "X.509 chain validation failed");
+      }
+    }
+
+    return ok();
+  }
+}
+
+/**
+ * Canonical JSON matching NipIdentity.sign — top-level keys filtered/ordered
+ * via `Object.keys(payload).sort()` as JSON.stringify replacer.
+ */
+function canonicalJson(payload: Record<string, unknown>): string {
+  return JSON.stringify(payload, Object.keys(payload).sort());
+}
+
+/** Parse `ed25519:<hex>` into a 32-byte Uint8Array public key. */
+function parsePubKeyString(s: string): Uint8Array {
+  if (!s.startsWith("ed25519:")) {
+    throw new Error(`Unsupported public key format: ${s}`);
+  }
+  return new Uint8Array(Buffer.from(s.slice("ed25519:".length), "hex"));
+}

package/src/nip/x509/builder.ts

@@ -0,0 +1,91 @@
+// Copyright 2026 INNO LOTUS PTY LTD
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Issues NPS X.509 NID certificates per NPS-RFC-0002 §4.
+ *
+ * Backed by @peculiar/x509 + Web Crypto Ed25519 (Node 22+).
+ *
+ * Two factory functions:
+ * - {@link issueLeaf} — leaf cert with critical NPS EKU + SAN URI = NID + assurance-level extension.
+ * - {@link issueRoot} — self-signed root for testing / private-CA use.
+ */
+
+import * as x509 from "@peculiar/x509";
+
+import { AssuranceLevel } from "../assurance-level.js";
+import { EKU_AGENT_IDENTITY, EKU_NODE_IDENTITY, NID_ASSURANCE_LEVEL } from "./oids.js";
+
+// Initialize @peculiar/x509 cryptoProvider once on first import. Web Crypto
+// (globalThis.crypto) supports Ed25519 in Node 18+.
+x509.cryptoProvider.set(globalThis.crypto);
+
+export type LeafRole = "agent" | "node";
+
+export interface IssueLeafOptions {
+  subjectNid:         string;
+  subjectPublicKey:   CryptoKey;        // Ed25519 public key (Web Crypto)
+  caKeys:             CryptoKeyPair;    // CA's keypair (we need privateKey to sign)
+  issuerNid:          string;
+  role:               LeafRole;
+  assuranceLevel:     AssuranceLevel;
+  notBefore:          Date;
+  notAfter:           Date;
+  serialNumber:       string;           // hex string, no "0x" prefix
+}
+
+export interface IssueRootOptions {
+  caNid:              string;
+  caKeys:             CryptoKeyPair;
+  notBefore:          Date;
+  notAfter:           Date;
+  serialNumber:       string;
+}
+
+/** Issue a leaf NPS NID certificate (RFC-0002 §4.1). */
+export async function issueLeaf(opts: IssueLeafOptions): Promise<x509.X509Certificate> {
+  const ekuOid = opts.role === "node" ? EKU_NODE_IDENTITY : EKU_AGENT_IDENTITY;
+
+  // ASN.1 ENUMERATED encoding of assurance level: tag=0x0A, len=0x01, value=<rank>.
+  const assuranceDer = new Uint8Array([0x0A, 0x01, opts.assuranceLevel.rank]);
+
+  return x509.X509CertificateGenerator.create({
+    serialNumber: opts.serialNumber,
+    issuer:       `CN=${escapeDn(opts.issuerNid)}`,
+    subject:      `CN=${escapeDn(opts.subjectNid)}`,
+    notBefore:    opts.notBefore,
+    notAfter:     opts.notAfter,
+    publicKey:    opts.subjectPublicKey,
+    signingAlgorithm: { name: "Ed25519" },
+    signingKey:   opts.caKeys.privateKey,
+    extensions: [
+      new x509.BasicConstraintsExtension(false, undefined, true),
+      new x509.KeyUsagesExtension(x509.KeyUsageFlags.digitalSignature, true),
+      new x509.ExtendedKeyUsageExtension([ekuOid], true),
+      new x509.SubjectAlternativeNameExtension([{ type: "url", value: opts.subjectNid }], false),
+      new x509.Extension(NID_ASSURANCE_LEVEL, false, assuranceDer),
+    ],
+  });
+}
+
+/** Issue a self-signed CA root cert (testing / private CA). */
+export async function issueRoot(opts: IssueRootOptions): Promise<x509.X509Certificate> {
+  return x509.X509CertificateGenerator.createSelfSigned({
+    serialNumber: opts.serialNumber,
+    name:         `CN=${escapeDn(opts.caNid)}`,
+    notBefore:    opts.notBefore,
+    notAfter:     opts.notAfter,
+    signingAlgorithm: { name: "Ed25519" },
+    keys:         opts.caKeys,
+    extensions: [
+      new x509.BasicConstraintsExtension(true, undefined, true),
+      new x509.KeyUsagesExtension(
+        x509.KeyUsageFlags.keyCertSign | x509.KeyUsageFlags.cRLSign, true),
+    ],
+  });
+}
+
+function escapeDn(value: string): string {
+  // Escape characters that have special meaning in RFC 4514 DN syntax.
+  return value.replace(/([",+;<>\\])/g, "\\$1");
+}

package/src/nip/x509/index.ts

@@ -0,0 +1,6 @@
+// Copyright 2026 INNO LOTUS PTY LTD
+// SPDX-License-Identifier: Apache-2.0
+
+export * from "./builder.js";
+export * from "./oids.js";
+export * from "./verifier.js";

package/src/nip/x509/oids.ts

@@ -0,0 +1,28 @@
+// Copyright 2026 INNO LOTUS PTY LTD
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * OID constants for NPS X.509 certificates per NPS-RFC-0002 §4.
+ *
+ * The 1.3.6.1.4.1.99999 arc is provisional pending IANA Private Enterprise
+ * Number assignment (RFC-0002 §10 OQ-2). All implementations MUST update
+ * these constants when the official PEN is granted.
+ */
+
+export const LAB_ACACIA_PEN_ARC = "1.3.6.1.4.1.99999";
+export const EKU_ARC            = `${LAB_ACACIA_PEN_ARC}.1`;
+export const EXTENSION_ARC      = `${LAB_ACACIA_PEN_ARC}.2`;
+
+// ── EKUs (NPS-RFC-0002 §4.1) ─────────────────────────────────────────────────
+export const EKU_AGENT_IDENTITY        = `${EKU_ARC}.1`;
+export const EKU_NODE_IDENTITY         = `${EKU_ARC}.2`;
+export const EKU_CA_INTERMEDIATE_AGENT = `${EKU_ARC}.3`;
+
+// ── Custom extensions ────────────────────────────────────────────────────────
+export const NID_ASSURANCE_LEVEL = `${EXTENSION_ARC}.1`;
+
+// ── Ed25519 algorithm OID per RFC 8410 ───────────────────────────────────────
+export const ED25519 = "1.3.101.112";
+
+// ── Standard X.509 OIDs we reference ─────────────────────────────────────────
+export const OID_EXTENDED_KEY_USAGE = "2.5.29.37";

package/src/nip/x509/verifier.ts

@@ -0,0 +1,214 @@
+// 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);
+
+export interface NipX509VerifyResult {
+  valid:       boolean;
+  errorCode?:  string;
+  message?:    string;
+  leaf?:       x509.X509Certificate;
+}
+
+function ok(leaf: x509.X509Certificate): NipX509VerifyResult {
+  return { valid: true, leaf };
+}
+
+function fail(errorCode: string, message: string): NipX509VerifyResult {
+  return { valid: false, errorCode, message };
+}
+
+export interface VerifyOptions {
+  certChainBase64UrlDer:    readonly string[];
+  assertedNid:              string;
+  assertedAssuranceLevel:   AssuranceLevel | null;
+  trustedRootCerts:         readonly x509.X509Certificate[];
+}
+
+export async function verify(opts: VerifyOptions): Promise<NipX509VerifyResult> {
+  // Stage 1: decode chain ─────────────────────────────────────────────────
+  if (!opts.certChainBase64UrlDer.length) {
+    return fail(ec.CERT_FORMAT_INVALID, "cert_chain is empty");
+  }
+  let chain: x509.X509Certificate[];
+  try {
+    chain = opts.certChainBase64UrlDer.map((s) => new x509.X509Certificate(b64uDecode(s).buffer as ArrayBuffer));
+  } catch (e) {
+    return fail(ec.CERT_FORMAT_INVALID, `DER decode failed: ${(e as Error).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: x509.X509Certificate): NipX509VerifyResult {
+  const ekuExt = leaf.extensions.find(
+    (e) => e.type === OID_EXTENDED_KEY_USAGE,
+  ) as x509.ExtendedKeyUsageExtension | undefined;
+  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 as readonly string[];
+  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: x509.X509Certificate, assertedNid: string): NipX509VerifyResult {
+  // @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: { type: string }) => n.type === "url")
+    .map((n: { value: string }) => 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: x509.X509Certificate, asserted: AssuranceLevel | null,
+): NipX509VerifyResult {
+  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: AssuranceLevel;
+  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: readonly x509.X509Certificate[],
+  trustedRoots: readonly x509.X509Certificate[],
+): Promise<NipX509VerifyResult> {
+  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 as Error).message}`);
+  }
+}
+
+// ── helpers ────────────────────────────────────────────────────────────────
+
+function extractCn(dn: string): string | null {
+  // @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: string): Uint8Array {
+  const padded = s + "=".repeat((4 - (s.length % 4)) % 4);
+  const std = padded.replace(/-/g, "+").replace(/_/g, "/");
+  return new Uint8Array(Buffer.from(std, "base64"));
+}

package/tests/_rfc0002-keys.ts

@@ -0,0 +1,57 @@
+// Copyright 2026 INNO LOTUS PTY LTD
+// SPDX-License-Identifier: Apache-2.0
+
+// Shared key-generation helper for RFC-0002 tests. Underscore prefix keeps
+// vitest's `*.test.ts` discovery pattern from picking this up as a suite.
+
+import * as ed25519 from "@noble/ed25519";
+import { sha512 } from "@noble/hashes/sha512";
+
+ed25519.etc.sha512Sync = (...m) => sha512(ed25519.etc.concatBytes(...m));
+
+// PKCS8 / SPKI prefixes for Ed25519 are fixed-length and well-defined
+// (RFC 8410). Concatenating them with raw key bytes lets us shuttle a noble
+// keypair through Web Crypto's importKey for use with @peculiar/x509.
+const PKCS8_PREFIX = new Uint8Array([
+  0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06,
+  0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20,
+]);
+const SPKI_PREFIX = new Uint8Array([
+  0x30, 0x2a, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65,
+  0x70, 0x03, 0x21, 0x00,
+]);
+
+export interface DualKeyPair {
+  privRaw:  Uint8Array;       // 32 bytes — for noble signing
+  pubRaw:   Uint8Array;       // 32 bytes — for IdentFrame.pub_key + JWK
+  webCrypto: CryptoKeyPair;   // for @peculiar/x509 signing / CSR generation
+}
+
+export async function generateDualKeyPair(): Promise<DualKeyPair> {
+  const privRaw = ed25519.utils.randomPrivateKey();
+  const pubRaw  = ed25519.getPublicKey(privRaw);
+
+  const pkcs8 = concat(PKCS8_PREFIX, privRaw);
+  const spki  = concat(SPKI_PREFIX,  pubRaw);
+
+  const subtle = globalThis.crypto.subtle;
+  const privateKey = await subtle.importKey(
+    "pkcs8", pkcs8.buffer as ArrayBuffer, { name: "Ed25519" }, true, ["sign"]);
+  const publicKey  = await subtle.importKey(
+    "spki",  spki.buffer  as ArrayBuffer, { name: "Ed25519" }, true, ["verify"]);
+
+  return { privRaw, pubRaw, webCrypto: { privateKey, publicKey } };
+}
+
+export function randomHexSerial(): string {
+  const buf = new Uint8Array(20);
+  globalThis.crypto.getRandomValues(buf);
+  return Buffer.from(buf).toString("hex");
+}
+
+function concat(a: Uint8Array, b: Uint8Array): Uint8Array {
+  const out = new Uint8Array(a.length + b.length);
+  out.set(a, 0);
+  out.set(b, a.length);
+  return out;
+}