@kybernesis/arp-tls 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kybernesis AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# `@kybernesis/arp-tls`
+
+Self-signed Ed25519 X.509 certificate generation plus DID-pinned fingerprint
+validation for ARP agents.
+
+## Why not Let's Encrypt?
+
+Agent names live on Handshake (`.agent`). Web PKI can't see them. ARP v0 skips
+CAs entirely — agents generate a long-lived self-signed cert, publish its
+SHA-256 fingerprint in their DID document, and peers validate against that
+pin. See `docs/ARP-hns-resolution.md §4`.
+
+## Install
+
+```bash
+pnpm add @kybernesis/arp-tls
+```
+
+## Use
+
+```ts
+import {
+  generateAgentCert,
+  computeFingerprint,
+  validatePinnedDer,
+  toTlsServerOptions,
+} from '@kybernesis/arp-tls';
+import { createServer, connect } from 'node:tls';
+
+const result = await generateAgentCert({ did: 'did:web:samantha.agent' });
+if (!result.ok) throw new Error(result.error.message);
+const { certPem, keyPem, fingerprint } = result.value;
+
+// Server side
+const server = createServer(toTlsServerOptions(result.value), (socket) => {
+  socket.end('hello');
+});
+
+// Client side — pin against the fingerprint found in the peer's DID doc.
+const socket = connect({
+  host: 'samantha.agent',
+  port: 443,
+  rejectUnauthorized: false,
+  servername: 'samantha.agent',
+});
+socket.on('secureConnect', () => {
+  const peer = socket.getPeerX509Certificate()!;
+  if (!validatePinnedDer(peer.raw, expectedFingerprintFromDidDoc)) {
+    socket.destroy();
+    throw new Error('pin mismatch');
+  }
+});
+```
+
+## API
+
+| Function                                | Notes                                         |
+| --------------------------------------- | --------------------------------------------- |
+| `generateAgentCert(opts)`               | Ed25519 self-signed cert, 10-year validity.   |
+| `computeFingerprint(pemOrDer)`          | SHA-256 of DER, lowercase hex.                |
+| `validatePinnedCert(pem, expected)`     | Constant-time compare; accepts `sha256:` prefix. |
+| `validatePinnedDer(der, expected)`      | Same as above for Node's `peer.raw`.          |
+| `toTlsServerOptions(cert)`              | Drop into `tls.createServer`/`https.createServer`. |
+| `toTlsClientOptions({host, port})`      | `rejectUnauthorized: false` baseline — you own the pin check. |
+
+## Design notes
+
+- The generator mints a fresh Ed25519 keypair rather than consuming the
+  agent's DID signing key. In v0 the TLS key is independent; Phase 3+ can
+  optionally reuse the DID key once Node's Web Crypto supports importing
+  raw multibase keys directly.
+- `@peculiar/x509` is the sole extra dependency; Node's built-in
+  `X509Certificate` handles parsing.
+- Fingerprint comparison is constant-time to keep timing side channels off
+  the table.

package/dist/index.cjs

@@ -0,0 +1,191 @@
+'use strict';
+
+var crypto = require('crypto');
+var x509 = require('@peculiar/x509');
+
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+
+var x509__namespace = /*#__PURE__*/_interopNamespace(x509);
+
+// src/cert.ts
+
+// src/errors.ts
+function tlsError(code, message, cause) {
+  return { code, message, cause };
+}
+
+// src/cert.ts
+x509__namespace.cryptoProvider.set(crypto.webcrypto);
+var CERT_VALIDITY_MS = 10 * 365 * 24 * 60 * 60 * 1e3;
+async function generateAgentCert(opts) {
+  const host = opts.sanHostname ?? extractHostFromDid(opts.did);
+  if (!host) {
+    return {
+      ok: false,
+      error: tlsError("invalid_input", `cannot derive SAN hostname from ${opts.did}`)
+    };
+  }
+  const now = opts.now?.() ?? /* @__PURE__ */ new Date();
+  const notAfter = new Date(now.getTime() + (opts.validityMs ?? CERT_VALIDITY_MS));
+  const serial = opts.serialNumber ?? randomSerialHex();
+  try {
+    const keys = await crypto.webcrypto.subtle.generateKey({ name: "Ed25519" }, true, [
+      "sign",
+      "verify"
+    ]);
+    const cert = await x509__namespace.X509CertificateGenerator.createSelfSigned({
+      name: `CN=${escapeDn(opts.did)}`,
+      notBefore: now,
+      notAfter,
+      serialNumber: serial,
+      signingAlgorithm: { name: "Ed25519" },
+      keys,
+      extensions: [
+        new x509__namespace.BasicConstraintsExtension(false, void 0, true),
+        new x509__namespace.KeyUsagesExtension(
+          x509__namespace.KeyUsageFlags.digitalSignature | x509__namespace.KeyUsageFlags.keyCertSign,
+          true
+        ),
+        new x509__namespace.ExtendedKeyUsageExtension(
+          [x509__namespace.ExtendedKeyUsage.serverAuth, x509__namespace.ExtendedKeyUsage.clientAuth],
+          true
+        ),
+        new x509__namespace.SubjectAlternativeNameExtension([{ type: "dns", value: host }])
+      ]
+    });
+    const pkcs8 = await crypto.webcrypto.subtle.exportKey("pkcs8", keys.privateKey);
+    const certPem = cert.toString("pem");
+    const keyPem = derToPem(new Uint8Array(pkcs8), "PRIVATE KEY");
+    const fingerprint = sha256HexOfDer(cert.rawData);
+    return { ok: true, value: { certPem, keyPem, fingerprint } };
+  } catch (err) {
+    return {
+      ok: false,
+      error: tlsError("cert_generation_failed", "failed to generate ed25519 cert", err)
+    };
+  }
+}
+function computeFingerprint(certPemOrDer) {
+  if (typeof certPemOrDer === "string") {
+    const der = pemToDer(certPemOrDer);
+    return sha256HexOfDer(der);
+  }
+  return sha256HexOfDer(certPemOrDer);
+}
+function validatePinnedCert(peerCertPem, expectedFingerprint) {
+  let actual;
+  try {
+    actual = computeFingerprint(peerCertPem);
+  } catch {
+    return false;
+  }
+  const expected = normalizeFingerprint(expectedFingerprint);
+  if (actual.length !== expected.length) return false;
+  let mismatch = 0;
+  for (let i = 0; i < actual.length; i++) {
+    mismatch |= actual.charCodeAt(i) ^ expected.charCodeAt(i);
+  }
+  return mismatch === 0;
+}
+function validatePinnedDer(peerDer, expectedFingerprint) {
+  const actual = sha256HexOfDer(peerDer);
+  const expected = normalizeFingerprint(expectedFingerprint);
+  if (actual.length !== expected.length) return false;
+  let mismatch = 0;
+  for (let i = 0; i < actual.length; i++) {
+    mismatch |= actual.charCodeAt(i) ^ expected.charCodeAt(i);
+  }
+  return mismatch === 0;
+}
+function parseCertificatePem(pem) {
+  return new crypto.X509Certificate(pem);
+}
+function extractHostFromDid(did) {
+  if (!did.startsWith("did:web:")) return null;
+  const body = did.slice("did:web:".length);
+  const first = body.split(":")[0];
+  return first ? decodeURIComponent(first) : null;
+}
+function sha256HexOfDer(der) {
+  const buf = der instanceof Uint8Array ? der : new Uint8Array(der);
+  return crypto.createHash("sha256").update(buf).digest("hex");
+}
+function pemToDer(pem) {
+  const match = pem.match(/-----BEGIN [^-]+-----([\s\S]+?)-----END [^-]+-----/);
+  if (!match || !match[1]) {
+    throw new Error("invalid PEM input");
+  }
+  const b64 = match[1].replace(/\s+/g, "");
+  return new Uint8Array(Buffer.from(b64, "base64"));
+}
+function derToPem(der, label) {
+  const b64 = Buffer.from(der).toString("base64");
+  const wrapped = b64.replace(/(.{64})/g, "$1\n").replace(/\n$/, "");
+  return `-----BEGIN ${label}-----
+${wrapped}
+-----END ${label}-----
+`;
+}
+function normalizeFingerprint(value) {
+  return value.trim().toLowerCase().replace(/^sha-?256:/, "").replace(/:/g, "");
+}
+function randomSerialHex() {
+  const bytes = new Uint8Array(16);
+  crypto.webcrypto.getRandomValues(bytes);
+  if (bytes[0] !== void 0) {
+    bytes[0] = bytes[0] & 127;
+  }
+  return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function escapeDn(value) {
+  return value.replace(/([,+"\\<>;#=])/g, "\\$1");
+}
+
+// src/server.ts
+function toTlsServerOptions(cert) {
+  return {
+    cert: cert.certPem,
+    key: cert.keyPem
+  };
+}
+function toTlsClientOptions(expected) {
+  const sni = expected.servername ?? (isLiteralIp(expected.host) ? void 0 : expected.host);
+  return {
+    host: expected.host,
+    port: expected.port,
+    rejectUnauthorized: false,
+    ...sni ? { servername: sni } : {}
+  };
+}
+function isLiteralIp(host) {
+  return /^(?:\d{1,3}\.){3}\d{1,3}$/.test(host) || host.includes(":");
+}
+
+exports.CERT_VALIDITY_MS = CERT_VALIDITY_MS;
+exports.computeFingerprint = computeFingerprint;
+exports.extractHostFromDid = extractHostFromDid;
+exports.generateAgentCert = generateAgentCert;
+exports.parseCertificatePem = parseCertificatePem;
+exports.tlsError = tlsError;
+exports.toTlsClientOptions = toTlsClientOptions;
+exports.toTlsServerOptions = toTlsServerOptions;
+exports.validatePinnedCert = validatePinnedCert;
+exports.validatePinnedDer = validatePinnedDer;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/cert.ts","../src/server.ts"],"names":["x509","webcrypto","X509Certificate","createHash"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Structured TLS errors. Surfaced via `Result<T, E>` at package boundaries.\n */\n\nexport type TlsErrorCode =\n  | 'invalid_input'\n  | 'cert_generation_failed'\n  | 'fingerprint_mismatch'\n  | 'parse_failed';\n\nexport interface TlsError {\n  code: TlsErrorCode;\n  message: string;\n  cause?: unknown;\n}\n\nexport function tlsError(code: TlsErrorCode, message: string, cause?: unknown): TlsError {\n  return { code, message, cause };\n}\n","import { createHash, webcrypto, X509Certificate } from 'node:crypto';\nimport * as x509 from '@peculiar/x509';\nimport { tlsError, type TlsError } from './errors.js';\n\n// `@peculiar/x509` accepts any Web Crypto provider; Node's `webcrypto` is\n// structurally compatible but the types diverge. Cast narrows to the shape\n// the library needs.\nx509.cryptoProvider.set(webcrypto as unknown as Parameters<typeof x509.cryptoProvider.set>[0]);\n\n/** 10 years in ms, matching Phase 2 Task 2 §1. */\nexport const CERT_VALIDITY_MS = 10 * 365 * 24 * 60 * 60 * 1000;\n\nexport interface GeneratedCert {\n  /** PEM-encoded X.509 certificate. */\n  certPem: string;\n  /** PEM-encoded PKCS#8 Ed25519 private key. */\n  keyPem: string;\n  /** SHA-256 of DER bytes, lowercase hex (no `sha256:` prefix). */\n  fingerprint: string;\n}\n\nexport interface GenerateAgentCertOptions {\n  /** Agent DID used for the cert Common Name, e.g. `did:web:samantha.agent`. */\n  did: string;\n  /**\n   * Multibase-encoded Ed25519 public key. Currently unused in v0 — the cert\n   * is generated from a freshly-minted key pair, as Node's Web Crypto does\n   * not ingest raw multibase keys directly. Retained on the signature for\n   * forward compatibility with `did:web` key-reuse workflows (Phase 3+).\n   */\n  publicKeyMultibase?: string;\n  /** Override SAN. Defaults to the host parsed out of the DID. */\n  sanHostname?: string;\n  /** Override validity period (ms). Defaults to 10 years. */\n  validityMs?: number;\n  /** Clock injection for tests. */\n  now?: () => Date;\n  /** Serial number override (hex). Random when omitted. */\n  serialNumber?: string;\n}\n\n/**\n * Generate a self-signed Ed25519 X.509 certificate pinned to an agent DID.\n *\n * - `CN` = the agent DID\n * - `subjectAltName` = the DNS host parsed out of `did:web:<host>` (or\n *   `options.sanHostname`)\n * - validity = 10 years by default\n */\nexport async function generateAgentCert(\n  opts: GenerateAgentCertOptions,\n): Promise<{ ok: true; value: GeneratedCert } | { ok: false; error: TlsError }> {\n  const host = opts.sanHostname ?? extractHostFromDid(opts.did);\n  if (!host) {\n    return {\n      ok: false,\n      error: tlsError('invalid_input', `cannot derive SAN hostname from ${opts.did}`),\n    };\n  }\n\n  const now = opts.now?.() ?? new Date();\n  const notAfter = new Date(now.getTime() + (opts.validityMs ?? CERT_VALIDITY_MS));\n  const serial = opts.serialNumber ?? randomSerialHex();\n\n  try {\n    const keys = (await webcrypto.subtle.generateKey({ name: 'Ed25519' }, true, [\n      'sign',\n      'verify',\n    ])) as { privateKey: webcrypto.CryptoKey; publicKey: webcrypto.CryptoKey };\n    const cert = await x509.X509CertificateGenerator.createSelfSigned({\n      name: `CN=${escapeDn(opts.did)}`,\n      notBefore: now,\n      notAfter,\n      serialNumber: serial,\n      signingAlgorithm: { name: 'Ed25519' },\n      keys,\n      extensions: [\n        new x509.BasicConstraintsExtension(false, undefined, true),\n        new x509.KeyUsagesExtension(\n          x509.KeyUsageFlags.digitalSignature | x509.KeyUsageFlags.keyCertSign,\n          true,\n        ),\n        new x509.ExtendedKeyUsageExtension(\n          [x509.ExtendedKeyUsage.serverAuth, x509.ExtendedKeyUsage.clientAuth],\n          true,\n        ),\n        new x509.SubjectAlternativeNameExtension([{ type: 'dns', value: host }]),\n      ],\n    });\n\n    const pkcs8 = await webcrypto.subtle.exportKey('pkcs8', keys.privateKey);\n    const certPem = cert.toString('pem');\n    const keyPem = derToPem(new Uint8Array(pkcs8), 'PRIVATE KEY');\n    const fingerprint = sha256HexOfDer(cert.rawData);\n    return { ok: true, value: { certPem, keyPem, fingerprint } };\n  } catch (err) {\n    return {\n      ok: false,\n      error: tlsError('cert_generation_failed', 'failed to generate ed25519 cert', err),\n    };\n  }\n}\n\n/**\n * SHA-256 of DER bytes, lowercase hex. Strips PEM headers if a PEM string\n * is passed in.\n */\nexport function computeFingerprint(certPemOrDer: string | ArrayBuffer | Uint8Array): string {\n  if (typeof certPemOrDer === 'string') {\n    const der = pemToDer(certPemOrDer);\n    return sha256HexOfDer(der);\n  }\n  return sha256HexOfDer(certPemOrDer);\n}\n\n/**\n * Validate a peer certificate (PEM) against an expected fingerprint. Constant-\n * time hex compare.\n */\nexport function validatePinnedCert(\n  peerCertPem: string,\n  expectedFingerprint: string,\n): boolean {\n  let actual: string;\n  try {\n    actual = computeFingerprint(peerCertPem);\n  } catch {\n    return false;\n  }\n  const expected = normalizeFingerprint(expectedFingerprint);\n  if (actual.length !== expected.length) return false;\n  let mismatch = 0;\n  for (let i = 0; i < actual.length; i++) {\n    mismatch |= actual.charCodeAt(i) ^ expected.charCodeAt(i);\n  }\n  return mismatch === 0;\n}\n\n/**\n * Validate a peer cert in DER form (as returned by Node `tls.TLSSocket`\n * `getPeerX509Certificate().raw`).\n */\nexport function validatePinnedDer(\n  peerDer: ArrayBuffer | Uint8Array,\n  expectedFingerprint: string,\n): boolean {\n  const actual = sha256HexOfDer(peerDer);\n  const expected = normalizeFingerprint(expectedFingerprint);\n  if (actual.length !== expected.length) return false;\n  let mismatch = 0;\n  for (let i = 0; i < actual.length; i++) {\n    mismatch |= actual.charCodeAt(i) ^ expected.charCodeAt(i);\n  }\n  return mismatch === 0;\n}\n\nexport function parseCertificatePem(pem: string): X509Certificate {\n  return new X509Certificate(pem);\n}\n\nexport function extractHostFromDid(did: string): string | null {\n  if (!did.startsWith('did:web:')) return null;\n  const body = did.slice('did:web:'.length);\n  const first = body.split(':')[0];\n  return first ? decodeURIComponent(first) : null;\n}\n\nfunction sha256HexOfDer(der: ArrayBuffer | Uint8Array): string {\n  const buf = der instanceof Uint8Array ? der : new Uint8Array(der);\n  return createHash('sha256').update(buf).digest('hex');\n}\n\nfunction pemToDer(pem: string): Uint8Array {\n  const match = pem.match(/-----BEGIN [^-]+-----([\\s\\S]+?)-----END [^-]+-----/);\n  if (!match || !match[1]) {\n    throw new Error('invalid PEM input');\n  }\n  const b64 = match[1].replace(/\\s+/g, '');\n  return new Uint8Array(Buffer.from(b64, 'base64'));\n}\n\nfunction derToPem(der: Uint8Array, label: string): string {\n  const b64 = Buffer.from(der).toString('base64');\n  const wrapped = b64.replace(/(.{64})/g, '$1\\n').replace(/\\n$/, '');\n  return `-----BEGIN ${label}-----\\n${wrapped}\\n-----END ${label}-----\\n`;\n}\n\nfunction normalizeFingerprint(value: string): string {\n  return value.trim().toLowerCase().replace(/^sha-?256:/, '').replace(/:/g, '');\n}\n\nfunction randomSerialHex(): string {\n  const bytes = new Uint8Array(16);\n  webcrypto.getRandomValues(bytes);\n  // Serial must be positive. Force MSB=0 to keep it unambiguously positive.\n  if (bytes[0] !== undefined) {\n    bytes[0] = bytes[0] & 0x7f;\n  }\n  return Array.from(bytes)\n    .map((b) => b.toString(16).padStart(2, '0'))\n    .join('');\n}\n\nfunction escapeDn(value: string): string {\n  // RFC 4514 special chars: , + \" \\ < > ; # (leading) and spaces (leading/trailing)\n  return value.replace(/([,+\"\\\\<>;#=])/g, '\\\\$1');\n}\n","import type { SecureContextOptions } from 'node:tls';\nimport type { GeneratedCert } from './cert.js';\n\n/**\n * Build the subset of TLS options Node's `createSecureContext` /\n * `tls.createServer` need to serve a DID-pinned self-signed cert.\n *\n * Usage:\n *   const srv = https.createServer(toTlsServerOptions(cert), app);\n *   tls.createServer(toTlsServerOptions(cert), ...);\n */\nexport function toTlsServerOptions(cert: GeneratedCert): SecureContextOptions {\n  return {\n    cert: cert.certPem,\n    key: cert.keyPem,\n  };\n}\n\n/**\n * Minimum tls.connect options for a pinning-aware client. The caller is\n * responsible for verifying the peer's fingerprint in the `secureConnect`\n * handler (use `validatePinnedDer(sock.getPeerX509Certificate().raw, fp)`).\n * `rejectUnauthorized: false` is required — the ARP PKI is DID-pinned, not\n * CA-chained.\n *\n * `servername` defaults to `host` unless `host` is a literal IP (Node rejects\n * IP-valued SNI). Pass an explicit `servername` when connecting via IP — it\n * should be the DNS name the peer's cert SAN covers.\n */\nexport function toTlsClientOptions(expected: {\n  host: string;\n  port: number;\n  servername?: string;\n}): {\n  host: string;\n  port: number;\n  rejectUnauthorized: false;\n  servername?: string;\n} {\n  const sni = expected.servername ?? (isLiteralIp(expected.host) ? undefined : expected.host);\n  return {\n    host: expected.host,\n    port: expected.port,\n    rejectUnauthorized: false,\n    ...(sni ? { servername: sni } : {}),\n  };\n}\n\nfunction isLiteralIp(host: string): boolean {\n  // Cheap check — good enough for excluding IPv4/IPv6 literals from SNI.\n  return /^(?:\\d{1,3}\\.){3}\\d{1,3}$/.test(host) || host.includes(':');\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,108 @@
+import { X509Certificate } from 'node:crypto';
+import { SecureContextOptions } from 'node:tls';
+
+/**
+ * Structured TLS errors. Surfaced via `Result<T, E>` at package boundaries.
+ */
+type TlsErrorCode = 'invalid_input' | 'cert_generation_failed' | 'fingerprint_mismatch' | 'parse_failed';
+interface TlsError {
+    code: TlsErrorCode;
+    message: string;
+    cause?: unknown;
+}
+declare function tlsError(code: TlsErrorCode, message: string, cause?: unknown): TlsError;
+
+/** 10 years in ms, matching Phase 2 Task 2 §1. */
+declare const CERT_VALIDITY_MS: number;
+interface GeneratedCert {
+    /** PEM-encoded X.509 certificate. */
+    certPem: string;
+    /** PEM-encoded PKCS#8 Ed25519 private key. */
+    keyPem: string;
+    /** SHA-256 of DER bytes, lowercase hex (no `sha256:` prefix). */
+    fingerprint: string;
+}
+interface GenerateAgentCertOptions {
+    /** Agent DID used for the cert Common Name, e.g. `did:web:samantha.agent`. */
+    did: string;
+    /**
+     * Multibase-encoded Ed25519 public key. Currently unused in v0 — the cert
+     * is generated from a freshly-minted key pair, as Node's Web Crypto does
+     * not ingest raw multibase keys directly. Retained on the signature for
+     * forward compatibility with `did:web` key-reuse workflows (Phase 3+).
+     */
+    publicKeyMultibase?: string;
+    /** Override SAN. Defaults to the host parsed out of the DID. */
+    sanHostname?: string;
+    /** Override validity period (ms). Defaults to 10 years. */
+    validityMs?: number;
+    /** Clock injection for tests. */
+    now?: () => Date;
+    /** Serial number override (hex). Random when omitted. */
+    serialNumber?: string;
+}
+/**
+ * Generate a self-signed Ed25519 X.509 certificate pinned to an agent DID.
+ *
+ * - `CN` = the agent DID
+ * - `subjectAltName` = the DNS host parsed out of `did:web:<host>` (or
+ *   `options.sanHostname`)
+ * - validity = 10 years by default
+ */
+declare function generateAgentCert(opts: GenerateAgentCertOptions): Promise<{
+    ok: true;
+    value: GeneratedCert;
+} | {
+    ok: false;
+    error: TlsError;
+}>;
+/**
+ * SHA-256 of DER bytes, lowercase hex. Strips PEM headers if a PEM string
+ * is passed in.
+ */
+declare function computeFingerprint(certPemOrDer: string | ArrayBuffer | Uint8Array): string;
+/**
+ * Validate a peer certificate (PEM) against an expected fingerprint. Constant-
+ * time hex compare.
+ */
+declare function validatePinnedCert(peerCertPem: string, expectedFingerprint: string): boolean;
+/**
+ * Validate a peer cert in DER form (as returned by Node `tls.TLSSocket`
+ * `getPeerX509Certificate().raw`).
+ */
+declare function validatePinnedDer(peerDer: ArrayBuffer | Uint8Array, expectedFingerprint: string): boolean;
+declare function parseCertificatePem(pem: string): X509Certificate;
+declare function extractHostFromDid(did: string): string | null;
+
+/**
+ * Build the subset of TLS options Node's `createSecureContext` /
+ * `tls.createServer` need to serve a DID-pinned self-signed cert.
+ *
+ * Usage:
+ *   const srv = https.createServer(toTlsServerOptions(cert), app);
+ *   tls.createServer(toTlsServerOptions(cert), ...);
+ */
+declare function toTlsServerOptions(cert: GeneratedCert): SecureContextOptions;
+/**
+ * Minimum tls.connect options for a pinning-aware client. The caller is
+ * responsible for verifying the peer's fingerprint in the `secureConnect`
+ * handler (use `validatePinnedDer(sock.getPeerX509Certificate().raw, fp)`).
+ * `rejectUnauthorized: false` is required — the ARP PKI is DID-pinned, not
+ * CA-chained.
+ *
+ * `servername` defaults to `host` unless `host` is a literal IP (Node rejects
+ * IP-valued SNI). Pass an explicit `servername` when connecting via IP — it
+ * should be the DNS name the peer's cert SAN covers.
+ */
+declare function toTlsClientOptions(expected: {
+    host: string;
+    port: number;
+    servername?: string;
+}): {
+    host: string;
+    port: number;
+    rejectUnauthorized: false;
+    servername?: string;
+};
+
+export { CERT_VALIDITY_MS, type GenerateAgentCertOptions, type GeneratedCert, type TlsError, type TlsErrorCode, computeFingerprint, extractHostFromDid, generateAgentCert, parseCertificatePem, tlsError, toTlsClientOptions, toTlsServerOptions, validatePinnedCert, validatePinnedDer };

package/dist/index.d.ts

@@ -0,0 +1,108 @@
+import { X509Certificate } from 'node:crypto';
+import { SecureContextOptions } from 'node:tls';
+
+/**
+ * Structured TLS errors. Surfaced via `Result<T, E>` at package boundaries.
+ */
+type TlsErrorCode = 'invalid_input' | 'cert_generation_failed' | 'fingerprint_mismatch' | 'parse_failed';
+interface TlsError {
+    code: TlsErrorCode;
+    message: string;
+    cause?: unknown;
+}
+declare function tlsError(code: TlsErrorCode, message: string, cause?: unknown): TlsError;
+
+/** 10 years in ms, matching Phase 2 Task 2 §1. */
+declare const CERT_VALIDITY_MS: number;
+interface GeneratedCert {
+    /** PEM-encoded X.509 certificate. */
+    certPem: string;
+    /** PEM-encoded PKCS#8 Ed25519 private key. */
+    keyPem: string;
+    /** SHA-256 of DER bytes, lowercase hex (no `sha256:` prefix). */
+    fingerprint: string;
+}
+interface GenerateAgentCertOptions {
+    /** Agent DID used for the cert Common Name, e.g. `did:web:samantha.agent`. */
+    did: string;
+    /**
+     * Multibase-encoded Ed25519 public key. Currently unused in v0 — the cert
+     * is generated from a freshly-minted key pair, as Node's Web Crypto does
+     * not ingest raw multibase keys directly. Retained on the signature for
+     * forward compatibility with `did:web` key-reuse workflows (Phase 3+).
+     */
+    publicKeyMultibase?: string;
+    /** Override SAN. Defaults to the host parsed out of the DID. */
+    sanHostname?: string;
+    /** Override validity period (ms). Defaults to 10 years. */
+    validityMs?: number;
+    /** Clock injection for tests. */
+    now?: () => Date;
+    /** Serial number override (hex). Random when omitted. */
+    serialNumber?: string;
+}
+/**
+ * Generate a self-signed Ed25519 X.509 certificate pinned to an agent DID.
+ *
+ * - `CN` = the agent DID
+ * - `subjectAltName` = the DNS host parsed out of `did:web:<host>` (or
+ *   `options.sanHostname`)
+ * - validity = 10 years by default
+ */
+declare function generateAgentCert(opts: GenerateAgentCertOptions): Promise<{
+    ok: true;
+    value: GeneratedCert;
+} | {
+    ok: false;
+    error: TlsError;
+}>;
+/**
+ * SHA-256 of DER bytes, lowercase hex. Strips PEM headers if a PEM string
+ * is passed in.
+ */
+declare function computeFingerprint(certPemOrDer: string | ArrayBuffer | Uint8Array): string;
+/**
+ * Validate a peer certificate (PEM) against an expected fingerprint. Constant-
+ * time hex compare.
+ */
+declare function validatePinnedCert(peerCertPem: string, expectedFingerprint: string): boolean;
+/**
+ * Validate a peer cert in DER form (as returned by Node `tls.TLSSocket`
+ * `getPeerX509Certificate().raw`).
+ */
+declare function validatePinnedDer(peerDer: ArrayBuffer | Uint8Array, expectedFingerprint: string): boolean;
+declare function parseCertificatePem(pem: string): X509Certificate;
+declare function extractHostFromDid(did: string): string | null;
+
+/**
+ * Build the subset of TLS options Node's `createSecureContext` /
+ * `tls.createServer` need to serve a DID-pinned self-signed cert.
+ *
+ * Usage:
+ *   const srv = https.createServer(toTlsServerOptions(cert), app);
+ *   tls.createServer(toTlsServerOptions(cert), ...);
+ */
+declare function toTlsServerOptions(cert: GeneratedCert): SecureContextOptions;
+/**
+ * Minimum tls.connect options for a pinning-aware client. The caller is
+ * responsible for verifying the peer's fingerprint in the `secureConnect`
+ * handler (use `validatePinnedDer(sock.getPeerX509Certificate().raw, fp)`).
+ * `rejectUnauthorized: false` is required — the ARP PKI is DID-pinned, not
+ * CA-chained.
+ *
+ * `servername` defaults to `host` unless `host` is a literal IP (Node rejects
+ * IP-valued SNI). Pass an explicit `servername` when connecting via IP — it
+ * should be the DNS name the peer's cert SAN covers.
+ */
+declare function toTlsClientOptions(expected: {
+    host: string;
+    port: number;
+    servername?: string;
+}): {
+    host: string;
+    port: number;
+    rejectUnauthorized: false;
+    servername?: string;
+};
+
+export { CERT_VALIDITY_MS, type GenerateAgentCertOptions, type GeneratedCert, type TlsError, type TlsErrorCode, computeFingerprint, extractHostFromDid, generateAgentCert, parseCertificatePem, tlsError, toTlsClientOptions, toTlsServerOptions, validatePinnedCert, validatePinnedDer };

package/dist/index.js

@@ -0,0 +1,160 @@
+import { webcrypto, X509Certificate, createHash } from 'crypto';
+import * as x509 from '@peculiar/x509';
+
+// src/cert.ts
+
+// src/errors.ts
+function tlsError(code, message, cause) {
+  return { code, message, cause };
+}
+
+// src/cert.ts
+x509.cryptoProvider.set(webcrypto);
+var CERT_VALIDITY_MS = 10 * 365 * 24 * 60 * 60 * 1e3;
+async function generateAgentCert(opts) {
+  const host = opts.sanHostname ?? extractHostFromDid(opts.did);
+  if (!host) {
+    return {
+      ok: false,
+      error: tlsError("invalid_input", `cannot derive SAN hostname from ${opts.did}`)
+    };
+  }
+  const now = opts.now?.() ?? /* @__PURE__ */ new Date();
+  const notAfter = new Date(now.getTime() + (opts.validityMs ?? CERT_VALIDITY_MS));
+  const serial = opts.serialNumber ?? randomSerialHex();
+  try {
+    const keys = await webcrypto.subtle.generateKey({ name: "Ed25519" }, true, [
+      "sign",
+      "verify"
+    ]);
+    const cert = await x509.X509CertificateGenerator.createSelfSigned({
+      name: `CN=${escapeDn(opts.did)}`,
+      notBefore: now,
+      notAfter,
+      serialNumber: serial,
+      signingAlgorithm: { name: "Ed25519" },
+      keys,
+      extensions: [
+        new x509.BasicConstraintsExtension(false, void 0, true),
+        new x509.KeyUsagesExtension(
+          x509.KeyUsageFlags.digitalSignature | x509.KeyUsageFlags.keyCertSign,
+          true
+        ),
+        new x509.ExtendedKeyUsageExtension(
+          [x509.ExtendedKeyUsage.serverAuth, x509.ExtendedKeyUsage.clientAuth],
+          true
+        ),
+        new x509.SubjectAlternativeNameExtension([{ type: "dns", value: host }])
+      ]
+    });
+    const pkcs8 = await webcrypto.subtle.exportKey("pkcs8", keys.privateKey);
+    const certPem = cert.toString("pem");
+    const keyPem = derToPem(new Uint8Array(pkcs8), "PRIVATE KEY");
+    const fingerprint = sha256HexOfDer(cert.rawData);
+    return { ok: true, value: { certPem, keyPem, fingerprint } };
+  } catch (err) {
+    return {
+      ok: false,
+      error: tlsError("cert_generation_failed", "failed to generate ed25519 cert", err)
+    };
+  }
+}
+function computeFingerprint(certPemOrDer) {
+  if (typeof certPemOrDer === "string") {
+    const der = pemToDer(certPemOrDer);
+    return sha256HexOfDer(der);
+  }
+  return sha256HexOfDer(certPemOrDer);
+}
+function validatePinnedCert(peerCertPem, expectedFingerprint) {
+  let actual;
+  try {
+    actual = computeFingerprint(peerCertPem);
+  } catch {
+    return false;
+  }
+  const expected = normalizeFingerprint(expectedFingerprint);
+  if (actual.length !== expected.length) return false;
+  let mismatch = 0;
+  for (let i = 0; i < actual.length; i++) {
+    mismatch |= actual.charCodeAt(i) ^ expected.charCodeAt(i);
+  }
+  return mismatch === 0;
+}
+function validatePinnedDer(peerDer, expectedFingerprint) {
+  const actual = sha256HexOfDer(peerDer);
+  const expected = normalizeFingerprint(expectedFingerprint);
+  if (actual.length !== expected.length) return false;
+  let mismatch = 0;
+  for (let i = 0; i < actual.length; i++) {
+    mismatch |= actual.charCodeAt(i) ^ expected.charCodeAt(i);
+  }
+  return mismatch === 0;
+}
+function parseCertificatePem(pem) {
+  return new X509Certificate(pem);
+}
+function extractHostFromDid(did) {
+  if (!did.startsWith("did:web:")) return null;
+  const body = did.slice("did:web:".length);
+  const first = body.split(":")[0];
+  return first ? decodeURIComponent(first) : null;
+}
+function sha256HexOfDer(der) {
+  const buf = der instanceof Uint8Array ? der : new Uint8Array(der);
+  return createHash("sha256").update(buf).digest("hex");
+}
+function pemToDer(pem) {
+  const match = pem.match(/-----BEGIN [^-]+-----([\s\S]+?)-----END [^-]+-----/);
+  if (!match || !match[1]) {
+    throw new Error("invalid PEM input");
+  }
+  const b64 = match[1].replace(/\s+/g, "");
+  return new Uint8Array(Buffer.from(b64, "base64"));
+}
+function derToPem(der, label) {
+  const b64 = Buffer.from(der).toString("base64");
+  const wrapped = b64.replace(/(.{64})/g, "$1\n").replace(/\n$/, "");
+  return `-----BEGIN ${label}-----
+${wrapped}
+-----END ${label}-----
+`;
+}
+function normalizeFingerprint(value) {
+  return value.trim().toLowerCase().replace(/^sha-?256:/, "").replace(/:/g, "");
+}
+function randomSerialHex() {
+  const bytes = new Uint8Array(16);
+  webcrypto.getRandomValues(bytes);
+  if (bytes[0] !== void 0) {
+    bytes[0] = bytes[0] & 127;
+  }
+  return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function escapeDn(value) {
+  return value.replace(/([,+"\\<>;#=])/g, "\\$1");
+}
+
+// src/server.ts
+function toTlsServerOptions(cert) {
+  return {
+    cert: cert.certPem,
+    key: cert.keyPem
+  };
+}
+function toTlsClientOptions(expected) {
+  const sni = expected.servername ?? (isLiteralIp(expected.host) ? void 0 : expected.host);
+  return {
+    host: expected.host,
+    port: expected.port,
+    rejectUnauthorized: false,
+    ...sni ? { servername: sni } : {}
+  };
+}
+function isLiteralIp(host) {
+  return /^(?:\d{1,3}\.){3}\d{1,3}$/.test(host) || host.includes(":");
+}
+
+export { CERT_VALIDITY_MS, computeFingerprint, extractHostFromDid, generateAgentCert, parseCertificatePem, tlsError, toTlsClientOptions, toTlsServerOptions, validatePinnedCert, validatePinnedDer };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/cert.ts","../src/server.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Structured TLS errors. Surfaced via `Result<T, E>` at package boundaries.\n */\n\nexport type TlsErrorCode =\n  | 'invalid_input'\n  | 'cert_generation_failed'\n  | 'fingerprint_mismatch'\n  | 'parse_failed';\n\nexport interface TlsError {\n  code: TlsErrorCode;\n  message: string;\n  cause?: unknown;\n}\n\nexport function tlsError(code: TlsErrorCode, message: string, cause?: unknown): TlsError {\n  return { code, message, cause };\n}\n","import { createHash, webcrypto, X509Certificate } from 'node:crypto';\nimport * as x509 from '@peculiar/x509';\nimport { tlsError, type TlsError } from './errors.js';\n\n// `@peculiar/x509` accepts any Web Crypto provider; Node's `webcrypto` is\n// structurally compatible but the types diverge. Cast narrows to the shape\n// the library needs.\nx509.cryptoProvider.set(webcrypto as unknown as Parameters<typeof x509.cryptoProvider.set>[0]);\n\n/** 10 years in ms, matching Phase 2 Task 2 §1. */\nexport const CERT_VALIDITY_MS = 10 * 365 * 24 * 60 * 60 * 1000;\n\nexport interface GeneratedCert {\n  /** PEM-encoded X.509 certificate. */\n  certPem: string;\n  /** PEM-encoded PKCS#8 Ed25519 private key. */\n  keyPem: string;\n  /** SHA-256 of DER bytes, lowercase hex (no `sha256:` prefix). */\n  fingerprint: string;\n}\n\nexport interface GenerateAgentCertOptions {\n  /** Agent DID used for the cert Common Name, e.g. `did:web:samantha.agent`. */\n  did: string;\n  /**\n   * Multibase-encoded Ed25519 public key. Currently unused in v0 — the cert\n   * is generated from a freshly-minted key pair, as Node's Web Crypto does\n   * not ingest raw multibase keys directly. Retained on the signature for\n   * forward compatibility with `did:web` key-reuse workflows (Phase 3+).\n   */\n  publicKeyMultibase?: string;\n  /** Override SAN. Defaults to the host parsed out of the DID. */\n  sanHostname?: string;\n  /** Override validity period (ms). Defaults to 10 years. */\n  validityMs?: number;\n  /** Clock injection for tests. */\n  now?: () => Date;\n  /** Serial number override (hex). Random when omitted. */\n  serialNumber?: string;\n}\n\n/**\n * Generate a self-signed Ed25519 X.509 certificate pinned to an agent DID.\n *\n * - `CN` = the agent DID\n * - `subjectAltName` = the DNS host parsed out of `did:web:<host>` (or\n *   `options.sanHostname`)\n * - validity = 10 years by default\n */\nexport async function generateAgentCert(\n  opts: GenerateAgentCertOptions,\n): Promise<{ ok: true; value: GeneratedCert } | { ok: false; error: TlsError }> {\n  const host = opts.sanHostname ?? extractHostFromDid(opts.did);\n  if (!host) {\n    return {\n      ok: false,\n      error: tlsError('invalid_input', `cannot derive SAN hostname from ${opts.did}`),\n    };\n  }\n\n  const now = opts.now?.() ?? new Date();\n  const notAfter = new Date(now.getTime() + (opts.validityMs ?? CERT_VALIDITY_MS));\n  const serial = opts.serialNumber ?? randomSerialHex();\n\n  try {\n    const keys = (await webcrypto.subtle.generateKey({ name: 'Ed25519' }, true, [\n      'sign',\n      'verify',\n    ])) as { privateKey: webcrypto.CryptoKey; publicKey: webcrypto.CryptoKey };\n    const cert = await x509.X509CertificateGenerator.createSelfSigned({\n      name: `CN=${escapeDn(opts.did)}`,\n      notBefore: now,\n      notAfter,\n      serialNumber: serial,\n      signingAlgorithm: { name: 'Ed25519' },\n      keys,\n      extensions: [\n        new x509.BasicConstraintsExtension(false, undefined, true),\n        new x509.KeyUsagesExtension(\n          x509.KeyUsageFlags.digitalSignature | x509.KeyUsageFlags.keyCertSign,\n          true,\n        ),\n        new x509.ExtendedKeyUsageExtension(\n          [x509.ExtendedKeyUsage.serverAuth, x509.ExtendedKeyUsage.clientAuth],\n          true,\n        ),\n        new x509.SubjectAlternativeNameExtension([{ type: 'dns', value: host }]),\n      ],\n    });\n\n    const pkcs8 = await webcrypto.subtle.exportKey('pkcs8', keys.privateKey);\n    const certPem = cert.toString('pem');\n    const keyPem = derToPem(new Uint8Array(pkcs8), 'PRIVATE KEY');\n    const fingerprint = sha256HexOfDer(cert.rawData);\n    return { ok: true, value: { certPem, keyPem, fingerprint } };\n  } catch (err) {\n    return {\n      ok: false,\n      error: tlsError('cert_generation_failed', 'failed to generate ed25519 cert', err),\n    };\n  }\n}\n\n/**\n * SHA-256 of DER bytes, lowercase hex. Strips PEM headers if a PEM string\n * is passed in.\n */\nexport function computeFingerprint(certPemOrDer: string | ArrayBuffer | Uint8Array): string {\n  if (typeof certPemOrDer === 'string') {\n    const der = pemToDer(certPemOrDer);\n    return sha256HexOfDer(der);\n  }\n  return sha256HexOfDer(certPemOrDer);\n}\n\n/**\n * Validate a peer certificate (PEM) against an expected fingerprint. Constant-\n * time hex compare.\n */\nexport function validatePinnedCert(\n  peerCertPem: string,\n  expectedFingerprint: string,\n): boolean {\n  let actual: string;\n  try {\n    actual = computeFingerprint(peerCertPem);\n  } catch {\n    return false;\n  }\n  const expected = normalizeFingerprint(expectedFingerprint);\n  if (actual.length !== expected.length) return false;\n  let mismatch = 0;\n  for (let i = 0; i < actual.length; i++) {\n    mismatch |= actual.charCodeAt(i) ^ expected.charCodeAt(i);\n  }\n  return mismatch === 0;\n}\n\n/**\n * Validate a peer cert in DER form (as returned by Node `tls.TLSSocket`\n * `getPeerX509Certificate().raw`).\n */\nexport function validatePinnedDer(\n  peerDer: ArrayBuffer | Uint8Array,\n  expectedFingerprint: string,\n): boolean {\n  const actual = sha256HexOfDer(peerDer);\n  const expected = normalizeFingerprint(expectedFingerprint);\n  if (actual.length !== expected.length) return false;\n  let mismatch = 0;\n  for (let i = 0; i < actual.length; i++) {\n    mismatch |= actual.charCodeAt(i) ^ expected.charCodeAt(i);\n  }\n  return mismatch === 0;\n}\n\nexport function parseCertificatePem(pem: string): X509Certificate {\n  return new X509Certificate(pem);\n}\n\nexport function extractHostFromDid(did: string): string | null {\n  if (!did.startsWith('did:web:')) return null;\n  const body = did.slice('did:web:'.length);\n  const first = body.split(':')[0];\n  return first ? decodeURIComponent(first) : null;\n}\n\nfunction sha256HexOfDer(der: ArrayBuffer | Uint8Array): string {\n  const buf = der instanceof Uint8Array ? der : new Uint8Array(der);\n  return createHash('sha256').update(buf).digest('hex');\n}\n\nfunction pemToDer(pem: string): Uint8Array {\n  const match = pem.match(/-----BEGIN [^-]+-----([\\s\\S]+?)-----END [^-]+-----/);\n  if (!match || !match[1]) {\n    throw new Error('invalid PEM input');\n  }\n  const b64 = match[1].replace(/\\s+/g, '');\n  return new Uint8Array(Buffer.from(b64, 'base64'));\n}\n\nfunction derToPem(der: Uint8Array, label: string): string {\n  const b64 = Buffer.from(der).toString('base64');\n  const wrapped = b64.replace(/(.{64})/g, '$1\\n').replace(/\\n$/, '');\n  return `-----BEGIN ${label}-----\\n${wrapped}\\n-----END ${label}-----\\n`;\n}\n\nfunction normalizeFingerprint(value: string): string {\n  return value.trim().toLowerCase().replace(/^sha-?256:/, '').replace(/:/g, '');\n}\n\nfunction randomSerialHex(): string {\n  const bytes = new Uint8Array(16);\n  webcrypto.getRandomValues(bytes);\n  // Serial must be positive. Force MSB=0 to keep it unambiguously positive.\n  if (bytes[0] !== undefined) {\n    bytes[0] = bytes[0] & 0x7f;\n  }\n  return Array.from(bytes)\n    .map((b) => b.toString(16).padStart(2, '0'))\n    .join('');\n}\n\nfunction escapeDn(value: string): string {\n  // RFC 4514 special chars: , + \" \\ < > ; # (leading) and spaces (leading/trailing)\n  return value.replace(/([,+\"\\\\<>;#=])/g, '\\\\$1');\n}\n","import type { SecureContextOptions } from 'node:tls';\nimport type { GeneratedCert } from './cert.js';\n\n/**\n * Build the subset of TLS options Node's `createSecureContext` /\n * `tls.createServer` need to serve a DID-pinned self-signed cert.\n *\n * Usage:\n *   const srv = https.createServer(toTlsServerOptions(cert), app);\n *   tls.createServer(toTlsServerOptions(cert), ...);\n */\nexport function toTlsServerOptions(cert: GeneratedCert): SecureContextOptions {\n  return {\n    cert: cert.certPem,\n    key: cert.keyPem,\n  };\n}\n\n/**\n * Minimum tls.connect options for a pinning-aware client. The caller is\n * responsible for verifying the peer's fingerprint in the `secureConnect`\n * handler (use `validatePinnedDer(sock.getPeerX509Certificate().raw, fp)`).\n * `rejectUnauthorized: false` is required — the ARP PKI is DID-pinned, not\n * CA-chained.\n *\n * `servername` defaults to `host` unless `host` is a literal IP (Node rejects\n * IP-valued SNI). Pass an explicit `servername` when connecting via IP — it\n * should be the DNS name the peer's cert SAN covers.\n */\nexport function toTlsClientOptions(expected: {\n  host: string;\n  port: number;\n  servername?: string;\n}): {\n  host: string;\n  port: number;\n  rejectUnauthorized: false;\n  servername?: string;\n} {\n  const sni = expected.servername ?? (isLiteralIp(expected.host) ? undefined : expected.host);\n  return {\n    host: expected.host,\n    port: expected.port,\n    rejectUnauthorized: false,\n    ...(sni ? { servername: sni } : {}),\n  };\n}\n\nfunction isLiteralIp(host: string): boolean {\n  // Cheap check — good enough for excluding IPv4/IPv6 literals from SNI.\n  return /^(?:\\d{1,3}\\.){3}\\d{1,3}$/.test(host) || host.includes(':');\n}\n"]}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@kybernesis/arp-tls",
+  "version": "0.3.0",
+  "description": "ARP TLS — self-signed Ed25519 X.509 cert generation + DID-doc pinning + fingerprint validation.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/KybernesisAI/arp.git",
+    "directory": "packages/tls"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@peculiar/x509": "^1.12.3"
+  },
+  "devDependencies": {},
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src tests"
+  }
+}