@aroha-sdk/core 1.0.0

package/src/identity/web-did.ts

@@ -0,0 +1,427 @@
+/**
+ * Aroha Web-Native Identity — did:aroha-web:
+ *
+ * A DNS-anchored DID method that requires NO central Aroha registry.
+ * Identity is verified by TWO independent channels simultaneously:
+ *
+ *   1. HTTPS — DID Document served at:
+ *      https://{domain}/.well-known/aroha/agents/{path}/did.json
+ *
+ *   2. DNS TXT — Key-commitment record at:
+ *      _aroha.{domain} IN TXT "v=aroha1; path={path}; keyhash={sha256 of pubkey}"
+ *
+ * Both channels must agree. Domain hijacking via HTTPS alone is insufficient —
+ * the attacker would also need to control DNS to forge the key-commitment.
+ * This is a meaningful security upgrade over single-channel HTTPS identity
+ * (did:wba, did:web).
+ *
+ * Key rotation:
+ *   Rotations are cryptographically chained — the new key is signed by the old
+ *   key and a 24-hour cool-down window is enforced before the new key is trusted.
+ *   The rotation record is embedded in the DID Document under `keyHistory`.
+ *
+ * DID format:
+ *   did:aroha-web:{domain}[:{path}]
+ *   e.g. did:aroha-web:stripe.com:payments-agent
+ *        did:aroha-web:internal.example.corp:invoicing
+ *
+ * Resolution produces the same DIDDocument format as did:aroha: — full
+ * interoperability with the rest of the Aroha stack.
+ */
+
+import * as ed from "@noble/ed25519";
+import { sha256 } from "@noble/hashes/sha256";
+import { sha512 } from "@noble/hashes/sha512";
+import { bytesToHex, randomBytes } from "@noble/hashes/utils";
+import {
+  type DIDDocument,
+  type AgentKeyPair,
+  type VerificationMethod,
+  type KeyRotationRecord,
+  toMultibase,
+  fromMultibase,
+} from "./did.js";
+
+ed.etc.sha512Sync = (...m: Parameters<typeof sha512>) => sha512(...m);
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface WebDIDDocument extends DIDDocument {
+  /** Two-factor verification metadata. */
+  arohaWeb: {
+    domain: string;
+    path: string;
+    /** SHA-256 hex of the active public key — must match DNS TXT. */
+    keyCommitmentHash: string;
+    /** Rotation chain (newest-first). Null if this is the genesis key. */
+    keyHistory: KeyRotationRecord[];
+  };
+}
+
+export { type KeyRotationRecord } from "./did.js";
+
+export interface WebAgentKeyPair extends AgentKeyPair {
+  /** The DNS TXT record value to publish at _aroha.{domain}. */
+  dnsTXTRecord: string;
+  /** The URL where the DID Document should be served. */
+  wellKnownUrl: string;
+  /** The full typed document (superset of DIDDocument). */
+  webDocument: WebDIDDocument;
+}
+
+export interface WebDIDResolutionResult {
+  document: WebDIDDocument;
+  /** True if DNS TXT key-commitment matched the document. */
+  dnsVerified: boolean;
+  /** True if the active key's cool-down window has passed. */
+  keyTrusted: boolean;
+  /** Reason if keyTrusted is false. */
+  trustReason?: string;
+}
+
+// ─── DID parsing ──────────────────────────────────────────────────────────────
+
+/** Parse `did:aroha-web:domain[:path]` into its components. */
+export function parseWebDID(did: string): { domain: string; path: string } {
+  const prefix = "did:aroha-web:";
+  if (!did.startsWith(prefix)) {
+    throw new Error(`Not a did:aroha-web: identifier: ${did}`);
+  }
+  const rest = did.slice(prefix.length);
+  const colonIdx = rest.indexOf(":");
+  if (colonIdx === -1) {
+    return { domain: rest, path: "agent" };
+  }
+  return {
+    domain: rest.slice(0, colonIdx),
+    path:   rest.slice(colonIdx + 1).replace(/:/g, "/"),
+  };
+}
+
+export function buildWebDID(domain: string, path: string): string {
+  const normalised = path.replace(/\//g, ":");
+  return `did:aroha-web:${domain}:${normalised}`;
+}
+
+export function isWebDID(did: string): boolean {
+  return did.startsWith("did:aroha-web:");
+}
+
+// ─── Well-known path ──────────────────────────────────────────────────────────
+
+/**
+ * The HTTP path at which the DID Document should be served.
+ * e.g. `did:aroha-web:stripe.com:payments` → `/.well-known/aroha/agents/payments/did.json`
+ */
+export function wellKnownPath(did: string): string {
+  const { path } = parseWebDID(did);
+  return `/.well-known/aroha/agents/${path}/did.json`;
+}
+
+/**
+ * The full HTTPS URL for a given did:aroha-web: identifier.
+ */
+export function wellKnownUrl(did: string): string {
+  const { domain, path } = parseWebDID(did);
+  return `https://${domain}/.well-known/aroha/agents/${path}/did.json`;
+}
+
+// ─── DNS TXT record ───────────────────────────────────────────────────────────
+
+/**
+ * Returns the DNS TXT record VALUE (not the full DNS record) for the
+ * key-commitment. Publish at: `_aroha.{domain} IN TXT "{this value}"`
+ *
+ * Format: `v=aroha1; path={path}; keyhash={sha256hex}`
+ */
+export function dnsTXTValue(did: string, publicKey: Uint8Array): string {
+  const { path } = parseWebDID(did);
+  const keyhash  = bytesToHex(sha256(publicKey));
+  return `v=aroha1; path=${path}; keyhash=${keyhash}`;
+}
+
+/** Parse a DNS TXT value back to its fields. Returns null if invalid. */
+export function parseDNSTXT(txt: string): { path: string; keyhash: string } | null {
+  if (!txt.includes("v=aroha1")) return null;
+  const fields: Record<string, string> = {};
+  for (const part of txt.split(";")) {
+    const eq = part.indexOf("=");
+    if (eq === -1) continue;
+    fields[part.slice(0, eq).trim()] = part.slice(eq + 1).trim();
+  }
+  if (!fields.path || !fields.keyhash) return null;
+  return { path: fields.path, keyhash: fields.keyhash };
+}
+
+// ─── Key commitment hash ──────────────────────────────────────────────────────
+
+export function keyCommitmentHash(publicKey: Uint8Array): string {
+  return bytesToHex(sha256(publicKey));
+}
+
+// ─── Generate ─────────────────────────────────────────────────────────────────
+
+/**
+ * Generate a new did:aroha-web: identity.
+ *
+ * Returns the key pair, the DID Document to serve at the well-known path,
+ * the DNS TXT value to publish, and the well-known URL.
+ *
+ * @param domain    The company domain (e.g. "stripe.com")
+ * @param path      Agent identifier within the domain (e.g. "payments-agent")
+ * @param endpoint  The Aroha HTTP endpoint URL (e.g. "https://agents.stripe.com/aroha/v1")
+ */
+export async function generateWebAgent(
+  domain: string,
+  path: string,
+  endpoint?: string
+): Promise<WebAgentKeyPair> {
+  const privateKey = ed.utils.randomPrivateKey();
+  const publicKey  = await ed.getPublicKeyAsync(privateKey);
+
+  const did    = buildWebDID(domain, path);
+  const keyId  = `${did}#key-1`;
+  const now    = new Date().toISOString();
+  const agentEndpoint = endpoint ?? `https://${domain}/aroha/v1`;
+
+  const webDoc: WebDIDDocument = {
+    "@context": [
+      "https://www.w3.org/ns/did/v1",
+      "https://w3id.org/security/suites/ed25519-2020/v1",
+      "https://aroha-labs.com/contexts/aroha-web/v1",
+    ],
+    id: did,
+    verificationMethod: [
+      {
+        id:                 keyId,
+        type:               "Ed25519VerificationKey2020",
+        controller:         did,
+        publicKeyMultibase: toMultibase(publicKey),
+      },
+    ],
+    authentication:   [keyId],
+    assertionMethod:  [keyId],
+    keyAgreement:     [keyId],
+    service: [
+      {
+        id:              `${did}#aroha`,
+        type:            "ArohaEndpoint",
+        serviceEndpoint: agentEndpoint,
+      },
+    ],
+    created: now,
+    updated: now,
+    arohaWeb: {
+      domain,
+      path,
+      keyCommitmentHash: keyCommitmentHash(publicKey),
+      keyHistory: [],
+    },
+  };
+
+  const txt = dnsTXTValue(did, publicKey);
+  const url = wellKnownUrl(did);
+
+  return {
+    did,
+    privateKey,
+    publicKey,
+    document:      webDoc,
+    webDocument:   webDoc,
+    dnsTXTRecord:  txt,
+    wellKnownUrl:  url,
+  };
+}
+
+// ─── Key rotation ──────────────────────────────────────────────────────────────
+
+/**
+ * Rotate to a new key pair. The old key signs a rotation record that is
+ * embedded in the new DID Document. The new key is not trusted until
+ * `coolDownHours` (default 24h) after the rotation is announced.
+ *
+ * Publish the returned `webDocument` at the well-known URL and update the
+ * DNS TXT record with `dnsTXTRecord` to complete the rotation.
+ */
+export async function rotateKey(
+  current: WebAgentKeyPair,
+  coolDownHours = 24
+): Promise<WebAgentKeyPair> {
+  const newPrivateKey = ed.utils.randomPrivateKey();
+  const newPublicKey  = await ed.getPublicKeyAsync(newPrivateKey);
+
+  const oldPubKeyMultibase = toMultibase(current.publicKey);
+  const now       = new Date();
+  const trustAfter = new Date(now.getTime() + coolDownHours * 3_600_000);
+
+  // Rotation payload: predecessorKey ∥ newKeyHash ∥ rotatedAt
+  const newKeyHash = keyCommitmentHash(newPublicKey);
+  const payload = new TextEncoder().encode(
+    oldPubKeyMultibase + newKeyHash + now.toISOString()
+  );
+  const sig = await ed.signAsync(payload, current.privateKey);
+
+  const rotation: KeyRotationRecord = {
+    rotatedAt:            now.toISOString(),
+    trustAfter:           trustAfter.toISOString(),
+    predecessorKey:       oldPubKeyMultibase,
+    newKeyHash,
+    predecessorSignature: Buffer.from(sig).toString("base64url"),
+  };
+
+  const { domain, path } = current.webDocument.arohaWeb;
+  const did   = buildWebDID(domain, path);
+  const keyId = `${did}#key-1`;
+  const ts    = now.toISOString();
+
+  const newDoc: WebDIDDocument = {
+    ...current.webDocument,
+    verificationMethod: [
+      {
+        id:                 keyId,
+        type:               "Ed25519VerificationKey2020",
+        controller:         did,
+        publicKeyMultibase: toMultibase(newPublicKey),
+      },
+    ],
+    updated: ts,
+    arohaWeb: {
+      ...current.webDocument.arohaWeb,
+      keyCommitmentHash: keyCommitmentHash(newPublicKey),
+      keyHistory:        [rotation, ...current.webDocument.arohaWeb.keyHistory],
+    },
+  };
+
+  return {
+    did,
+    privateKey:   newPrivateKey,
+    publicKey:    newPublicKey,
+    document:     newDoc,
+    webDocument:  newDoc,
+    dnsTXTRecord: dnsTXTValue(did, newPublicKey),
+    wellKnownUrl: wellKnownUrl(did),
+  };
+}
+
+// ─── Resolve ──────────────────────────────────────────────────────────────────
+
+/**
+ * Resolve a did:aroha-web: identifier.
+ *
+ * Fetches the DID Document over HTTPS and, if `verifyDNS` is true,
+ * also verifies the DNS TXT key-commitment. Both must match for full
+ * two-factor verification.
+ *
+ * In Node.js server environments, pass a custom `dnsResolver` to perform
+ * the DNS TXT lookup. In browser or edge environments, set `verifyDNS: false`
+ * (single-channel HTTPS-only, same security as did:wba).
+ *
+ * @param did          The did:aroha-web: identifier to resolve
+ * @param verifyDNS    Whether to check the DNS TXT record (default: true)
+ * @param dnsResolver  Optional custom DNS TXT resolver
+ */
+export async function resolveWebDID(
+  did: string,
+  verifyDNS = true,
+  dnsResolver?: (domain: string) => Promise<string[]>,
+  fetchTimeoutMs = 10_000
+): Promise<WebDIDResolutionResult> {
+  const url = wellKnownUrl(did);
+
+  // ── Step 1: Fetch DID Document over HTTPS ─────────────────────────────────
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), fetchTimeoutMs);
+  let res: Response;
+  try {
+    res = await fetch(url, {
+      headers: { Accept: "application/json" },
+      signal: ctrl.signal,
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+  if (!res.ok) {
+    throw new Error(`Failed to resolve ${did}: HTTP ${res.status} from ${url}`);
+  }
+  const doc = await res.json() as WebDIDDocument;
+
+  if (doc.id !== did) {
+    throw new Error(`DID mismatch: document claims ${doc.id}, expected ${did}`);
+  }
+
+  const activeKey = fromMultibase(doc.verificationMethod[0].publicKeyMultibase);
+
+  // ── Step 2: Verify all rotation records in keyHistory ────────────────────
+  if (doc.arohaWeb?.keyHistory?.length > 0) {
+    for (const rotation of doc.arohaWeb.keyHistory) {
+      const rotationValid = await verifyKeyRotation(rotation);
+      if (!rotationValid) {
+        throw new Error(
+          `DID ${did}: key rotation record (rotatedAt ${rotation.rotatedAt}) has invalid predecessor signature`
+        );
+      }
+    }
+  }
+
+  // ── Step 4: Check key rotation cool-down ─────────────────────────────────
+  let keyTrusted = true;
+  let trustReason: string | undefined;
+  if (doc.arohaWeb?.keyHistory?.length > 0) {
+    const latestRotation = doc.arohaWeb.keyHistory[0];
+    const trustAfter = new Date(latestRotation.trustAfter);
+    if (new Date() < trustAfter) {
+      keyTrusted = false;
+      trustReason = `Key rotation cool-down active until ${latestRotation.trustAfter}`;
+    }
+  }
+
+  // ── Step 5: DNS TXT key-commitment verification ────────────────────────────
+  let dnsVerified = false;
+  if (verifyDNS) {
+    const { domain, path } = parseWebDID(did);
+    let txtRecords: string[] = [];
+    if (dnsResolver) {
+      txtRecords = await dnsResolver(domain).catch(() => []);
+    } else if (typeof (globalThis as Record<string, unknown>)["Deno"] !== "undefined") {
+      // Deno DNS API
+      try {
+        const denoGlobal = (globalThis as unknown as { Deno: { resolveDns(n: string, t: string): Promise<string[][]> } }).Deno;
+        const records = await denoGlobal
+          .resolveDns(`_aroha.${domain}`, "TXT");
+        txtRecords = records.flat();
+      } catch { /* DNS unavailable — fall back to HTTPS-only */ }
+    }
+    // Node.js: caller must pass dnsResolver (avoids bundling dns module in core)
+
+    for (const txt of txtRecords) {
+      const parsed = parseDNSTXT(txt);
+      if (!parsed) continue;
+      if (parsed.path !== path) continue;
+      const expectedHash = keyCommitmentHash(activeKey);
+      if (parsed.keyhash === expectedHash) {
+        dnsVerified = true;
+        break;
+      }
+    }
+  }
+
+  return { document: doc, dnsVerified, keyTrusted, trustReason };
+}
+
+/**
+ * Verify a key rotation record — confirms the predecessor key signed the
+ * rotation event voluntarily (prevents unauthorized key replacement).
+ */
+export async function verifyKeyRotation(rotation: KeyRotationRecord): Promise<boolean> {
+  try {
+    const predKey = fromMultibase(rotation.predecessorKey);
+    const newHash = rotation.newKeyHash;
+    const payload = new TextEncoder().encode(
+      rotation.predecessorKey + newHash + rotation.rotatedAt
+    );
+    const sig = Buffer.from(rotation.predecessorSignature, "base64url");
+    return await ed.verifyAsync(sig, payload, predKey);
+  } catch {
+    return false;
+  }
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+/**
+ * @aroha-sdk/core — Aroha Protocol Layers 0–3
+ *
+ * Layer 0: Transport  → ArohaServer, ArohaClient
+ * Layer 1: Identity   → generateDID, DIDDocument, issueCredential, verifyCredential
+ *          Auth       → issueCredential, verifyCredential, ArohaRole, RbacPolicy, checkPermission
+ * Layer 3: Messaging  → buildEnvelope, validateEnvelope, ArohaEnvelope, all message types
+ * Crypto:             → signMessage, verifyMessageSignature, encryptBody, decryptBody
+ */
+
+export * from "./identity/index.js";
+export * from "./crypto/index.js";
+export * from "./messages/index.js";
+export * from "./transport/index.js";