@tinycloud/sdk-services 3.7.0-beta.3 → 3.7.0-beta.4

package/dist/encryption/named-keys.cjs

@@ -0,0 +1,1077 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/encryption/namedKeys.ts
+var namedKeys_exports = {};
+__export(namedKeys_exports, {
+  KEY_ADMIN_FACT_TYPE: () => KEY_ADMIN_FACT_TYPE,
+  KEY_DESCRIBE_FACT_TYPE: () => KEY_DESCRIBE_FACT_TYPE,
+  NAMED_KEY_ENVELOPE_VERSION: () => NAMED_KEY_ENVELOPE_VERSION,
+  NamedKeyClient: () => NamedKeyClient,
+  NamedKeyError: () => NamedKeyError,
+  buildKeyAdminFacts: () => buildKeyAdminFacts,
+  buildKeyDescribeFacts: () => buildKeyDescribeFacts,
+  mapNodeKeyError: () => mapNodeKeyError,
+  requireKeyTarget: () => requireKeyTarget,
+  safeEcho: () => safeEcho
+});
+module.exports = __toCommonJS(namedKeys_exports);
+
+// src/encryption/canonical.ts
+function canonicalize(value) {
+  if (value === void 0) {
+    return "";
+  }
+  return stringify(value);
+}
+function stringify(value) {
+  if (value === null) return "null";
+  switch (typeof value) {
+    case "boolean":
+    case "number":
+      return JSON.stringify(value);
+    case "string":
+      return JSON.stringify(value);
+    case "object": {
+      if (Array.isArray(value)) {
+        return `[${value.map(stringify).join(",")}]`;
+      }
+      const keys = Object.keys(value).sort();
+      const parts = [];
+      for (const k of keys) {
+        const v = value[k];
+        if (v === void 0) continue;
+        parts.push(`${JSON.stringify(k)}:${stringify(v)}`);
+      }
+      return `{${parts.join(",")}}`;
+    }
+    default:
+      throw new TypeError(
+        `canonicalize: unsupported value type ${typeof value}`
+      );
+  }
+}
+var HEX = "0123456789abcdef";
+function hexEncode(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes.length; i++) {
+    const b = bytes[i];
+    out += HEX[b >> 4 & 15] + HEX[b & 15];
+  }
+  return out;
+}
+function base64Encode(bytes) {
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const b0 = bytes[i];
+    const b1 = i + 1 < bytes.length ? bytes[i + 1] : 0;
+    const b2 = i + 2 < bytes.length ? bytes[i + 2] : 0;
+    out += chars[b0 >> 2 & 63];
+    out += chars[(b0 << 4 | b1 >> 4) & 63];
+    out += i + 1 < bytes.length ? chars[(b1 << 2 | b2 >> 6) & 63] : "=";
+    out += i + 2 < bytes.length ? chars[b2 & 63] : "=";
+  }
+  return out;
+}
+function base64Decode(s) {
+  const clean = s.replace(/[^A-Za-z0-9+/=]/g, "");
+  const len = clean.length;
+  if (len % 4 !== 0) {
+    throw new Error("invalid base64 input");
+  }
+  const padding = clean.endsWith("==") ? 2 : clean.endsWith("=") ? 1 : 0;
+  const outLen = len / 4 * 3 - padding;
+  const out = new Uint8Array(outLen);
+  const lookup = {};
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+  for (let i = 0; i < chars.length; i++) lookup[chars[i]] = i;
+  let outIdx = 0;
+  for (let i = 0; i < len; i += 4) {
+    const v0 = lookup[clean[i]] ?? 0;
+    const v1 = lookup[clean[i + 1]] ?? 0;
+    const v2 = clean[i + 2] === "=" ? 0 : lookup[clean[i + 2]] ?? 0;
+    const v3 = clean[i + 3] === "=" ? 0 : lookup[clean[i + 3]] ?? 0;
+    const b0 = v0 << 2 | v1 >> 4;
+    const b1 = (v1 & 15) << 4 | v2 >> 2;
+    const b2 = (v2 & 3) << 6 | v3;
+    if (outIdx < outLen) out[outIdx++] = b0;
+    if (outIdx < outLen) out[outIdx++] = b1;
+    if (outIdx < outLen) out[outIdx++] = b2;
+  }
+  return out;
+}
+function utf8Encode(s) {
+  return new TextEncoder().encode(s);
+}
+function canonicalHashHex(sha256, value) {
+  const canonical = canonicalize(value);
+  return hexEncode(sha256(utf8Encode(canonical)));
+}
+
+// src/encryption/networkId.ts
+var URN_PREFIX = "urn:tinycloud:encryption:";
+var NETWORK_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+var NetworkIdError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "NetworkIdError";
+  }
+};
+function parseNetworkId(networkId) {
+  if (typeof networkId !== "string" || networkId.length === 0) {
+    throw new NetworkIdError("networkId must be a non-empty string");
+  }
+  if (!networkId.startsWith(URN_PREFIX)) {
+    throw new NetworkIdError(
+      `networkId must start with ${URN_PREFIX} (got ${JSON.stringify(networkId)})`
+    );
+  }
+  const body = networkId.slice(URN_PREFIX.length);
+  const lastColon = body.lastIndexOf(":");
+  if (lastColon <= 0 || lastColon === body.length - 1) {
+    throw new NetworkIdError(
+      `networkId missing ownerDid or name segment (got ${JSON.stringify(networkId)})`
+    );
+  }
+  const ownerDid = body.slice(0, lastColon);
+  const name = body.slice(lastColon + 1);
+  if (!ownerDid.startsWith("did:")) {
+    throw new NetworkIdError(
+      `networkId ownerDid must be a DID (got ${JSON.stringify(ownerDid)})`
+    );
+  }
+  const didParts = ownerDid.split(":");
+  if (didParts.length < 3 || didParts.some((p) => p.length === 0)) {
+    throw new NetworkIdError(
+      `networkId ownerDid is not a well-formed DID (got ${JSON.stringify(ownerDid)})`
+    );
+  }
+  if (!NETWORK_NAME_RE.test(name)) {
+    throw new NetworkIdError(
+      `networkId name ${JSON.stringify(name)} must match ${NETWORK_NAME_RE.source}`
+    );
+  }
+  return { networkId, ownerDid, name };
+}
+var ENCRYPTION_NETWORK_URN_PREFIX = URN_PREFIX;
+
+// src/encryption/receiverKey.ts
+function generateRandomReceiverKey(input) {
+  const seed = input.crypto.randomBytes(32);
+  return input.crypto.x25519FromSeed(seed);
+}
+
+// src/encryption/types.ts
+var DEFAULT_ENCRYPTION_ALG = "x25519-aes256gcm/v1";
+var DECRYPT_FACT_TYPE = "tinycloud.encryption.decrypt/v1";
+var DECRYPT_RESULT_TYPE = "tinycloud.encryption.decrypt-result/v1";
+var DECRYPT_ACTION = "tinycloud.encryption/decrypt";
+function defaultEncryptionMessage(input) {
+  switch (input.code) {
+    case "NETWORK_NOT_FOUND":
+      return input.message ?? `Network not found: ${input.networkId ?? input.name ?? "<unknown>"}`;
+    case "NETWORK_NOT_ACTIVE":
+      return input.message ?? `Network not active (state=${input.state})`;
+    case "INVALID_NETWORK_ID":
+      return input.message;
+    case "INVALID_ENVELOPE":
+      return input.message;
+    case "DECRYPT_DENIED":
+      return input.message;
+    case "INVALID_RESPONSE":
+      return input.message;
+    case "RESPONSE_SIGNATURE_INVALID":
+      return input.message ?? "Node response signature failed to verify";
+    case "RESPONSE_BINDING_MISMATCH":
+      return input.message ?? `Node response binding mismatch on field ${JSON.stringify(input.field)}`;
+    case "TRANSPORT_ERROR":
+      return input.message ?? input.cause.message;
+    case "INVALID_INPUT":
+      return input.message;
+  }
+}
+function encryptionError(input) {
+  return {
+    ...input,
+    service: "encryption",
+    message: defaultEncryptionMessage(input)
+  };
+}
+
+// src/encryption/response.ts
+function canonicalSignedResponse(response) {
+  const { nodeSignature: _drop, ...rest } = response;
+  return canonicalize(rest);
+}
+function verifyDecryptResponse(input) {
+  const { crypto, request, facts, invocationCid, requestBodyHash, response } = input;
+  if (response.type !== DECRYPT_RESULT_TYPE) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "INVALID_RESPONSE",
+        message: `response.type must be ${DECRYPT_RESULT_TYPE}`
+      })
+    };
+  }
+  if (response.targetNode !== request.targetNode) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "RESPONSE_BINDING_MISMATCH",
+        field: "targetNode"
+      })
+    };
+  }
+  if (response.networkId !== request.networkId) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "RESPONSE_BINDING_MISMATCH",
+        field: "networkId"
+      })
+    };
+  }
+  if (response.nodeId !== request.targetNode) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "RESPONSE_BINDING_MISMATCH",
+        field: "nodeId"
+      })
+    };
+  }
+  if (response.alg !== request.alg) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "RESPONSE_BINDING_MISMATCH",
+        field: "alg"
+      })
+    };
+  }
+  if (response.keyVersion !== request.keyVersion) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "RESPONSE_BINDING_MISMATCH",
+        field: "keyVersion"
+      })
+    };
+  }
+  if (response.encryptedSymmetricKeyHash !== request.encryptedSymmetricKeyHash) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "RESPONSE_BINDING_MISMATCH",
+        field: "encryptedSymmetricKeyHash"
+      })
+    };
+  }
+  if (response.receiverPublicKeyHash !== request.receiverPublicKeyHash) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "RESPONSE_BINDING_MISMATCH",
+        field: "receiverPublicKeyHash"
+      })
+    };
+  }
+  if (response.invocationCid !== invocationCid) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "RESPONSE_BINDING_MISMATCH",
+        field: "invocationCid"
+      })
+    };
+  }
+  const expectedRequestHash = hexEncode(
+    crypto.sha256(utf8Encode(`${invocationCid}${requestBodyHash}`))
+  );
+  if (response.requestHash !== expectedRequestHash) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "RESPONSE_BINDING_MISMATCH",
+        field: "requestHash"
+      })
+    };
+  }
+  if (facts.encryptedSymmetricKeyHash !== response.encryptedSymmetricKeyHash || facts.receiverPublicKeyHash !== response.receiverPublicKeyHash || facts.networkId !== response.networkId || facts.targetNode !== response.targetNode || facts.alg !== response.alg || facts.keyVersion !== response.keyVersion) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "RESPONSE_BINDING_MISMATCH",
+        field: "facts"
+      })
+    };
+  }
+  const signedBytes = new TextEncoder().encode(
+    canonicalSignedResponse(response)
+  );
+  const signatureBytes = base64Decode(response.nodeSignature);
+  if (!crypto.verifyNodeSignature(response.nodeId, signedBytes, signatureBytes)) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "RESPONSE_SIGNATURE_INVALID"
+      })
+    };
+  }
+  return { ok: true, data: response };
+}
+function openWrappedKey(crypto, receiverPrivateKey, response) {
+  const wrapped = base64Decode(response.wrappedKey);
+  return crypto.openWithReceiverKey(receiverPrivateKey, wrapped);
+}
+
+// src/encryption/resource.ts
+var import_bootstrap = require("@tinycloud/bootstrap");
+var SEGMENT_SOURCE = "[a-z0-9][a-z0-9._-]{0,63}";
+var PATH_SOURCE = `${SEGMENT_SOURCE}(?:/${SEGMENT_SOURCE}){0,7}`;
+var KEY_PATH_RE = new RegExp(`^${PATH_SOURCE}$`);
+var KEY_NETWORK_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+var RESOURCE_RE = /^(did:[a-z0-9]+:[A-Za-z0-9._:-]+):([^:/]+)(?:\/(.*))?$/s;
+var MAX_PATH_BYTES = 255;
+var PKH_EIP155_PREFIX = "did:pkh:eip155:";
+var MAX_U64 = 18446744073709551615n;
+var KEY_CREATE_ABILITY = "tinycloud.encryption/key.create";
+var KEY_BLOCK_ABILITY = "tinycloud.encryption/key.block";
+var KEY_UNBLOCK_ABILITY = "tinycloud.encryption/key.unblock";
+var DELEGABLE_KEY_ABILITIES = Object.freeze([
+  DECRYPT_ACTION,
+  KEY_CREATE_ABILITY,
+  KEY_BLOCK_ABILITY,
+  KEY_UNBLOCK_ABILITY
+]);
+var NAMED_KEYS_FEATURE = "encryption-named-keys-v1";
+var EncryptionResourceError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "EncryptionResourceError";
+    this.code = code;
+  }
+};
+function canonicalOwner(ownerDid) {
+  if (!ownerDid.startsWith(PKH_EIP155_PREFIX)) return ownerDid;
+  const rest = ownerDid.slice(PKH_EIP155_PREFIX.length);
+  const colon = rest.indexOf(":");
+  const chain = colon === -1 ? "" : rest.slice(0, colon);
+  const address = colon === -1 ? "" : rest.slice(colon + 1);
+  if (!/^\d+$/.test(chain) || !/^0x[a-fA-F0-9]{40}$/.test(address)) {
+    throw new EncryptionResourceError(
+      "bad_owner",
+      `owner DID is not a valid did:pkh:eip155 (got ${JSON.stringify(ownerDid)})`
+    );
+  }
+  const chainId = BigInt(chain);
+  if (chainId === 0n || chainId > MAX_U64) {
+    throw new EncryptionResourceError(
+      "bad_owner",
+      `did:pkh:eip155 chain id must be a positive u64 (got ${JSON.stringify(chain)})`
+    );
+  }
+  const checksummed = (0, import_bootstrap.pkhDid)(address, 1).slice(PKH_EIP155_PREFIX.length + 2);
+  return `${PKH_EIP155_PREFIX}${chainId}:${checksummed}`;
+}
+function assertCanonicalOwner(ownerDid) {
+  const canonical = canonicalOwner(ownerDid);
+  if (canonical !== ownerDid) {
+    throw new EncryptionResourceError(
+      "non_canonical_owner",
+      `owner DID is not canonical (expected ${canonical})`
+    );
+  }
+}
+function assertPath(path, what) {
+  if (path.length === 0) {
+    throw new EncryptionResourceError("empty_path", `${what} must not be empty`);
+  }
+  if (new TextEncoder().encode(path).length > MAX_PATH_BYTES) {
+    throw new EncryptionResourceError(
+      "path_too_long",
+      `${what} exceeds ${MAX_PATH_BYTES} bytes`
+    );
+  }
+  if (!KEY_PATH_RE.test(path)) {
+    throw new EncryptionResourceError(
+      "bad_path",
+      `${what} ${JSON.stringify(path)} must match ${KEY_PATH_RE.source}`
+    );
+  }
+  const segments = path.split("/");
+  if (segments[0] === "apps" && segments.length < (what === "key path" ? 3 : 2)) {
+    throw new EncryptionResourceError(
+      "bad_path",
+      `${what} ${JSON.stringify(path)} under apps/ needs ${what === "key path" ? "apps/<id>/<name>" : "apps/<id>/"}`
+    );
+  }
+}
+function parseEncryptionResource(uri) {
+  if (typeof uri !== "string" || !uri.startsWith(ENCRYPTION_NETWORK_URN_PREFIX)) {
+    throw new EncryptionResourceError(
+      "not_encryption_urn",
+      `resource must start with ${ENCRYPTION_NETWORK_URN_PREFIX}`
+    );
+  }
+  const body = uri.slice(ENCRYPTION_NETWORK_URN_PREFIX.length);
+  const match = RESOURCE_RE.exec(body);
+  if (match === null) {
+    throw new EncryptionResourceError(
+      "malformed",
+      `resource is not <ownerDid>:<network>[/<path>] (got ${JSON.stringify(uri)})`
+    );
+  }
+  const ownerDid = match[1];
+  const network = match[2];
+  const rawPath = match[3];
+  if (rawPath === void 0) {
+    const canonicalOwnerDid = canonicalOwner(ownerDid);
+    const bareId = `${ENCRYPTION_NETWORK_URN_PREFIX}${canonicalOwnerDid}:${network}`;
+    try {
+      parseNetworkId(bareId);
+    } catch (error) {
+      if (error instanceof NetworkIdError) {
+        throw new EncryptionResourceError("bad_network", error.message);
+      }
+      throw error;
+    }
+    return { kind: "network", ownerDid: canonicalOwnerDid, network, networkId: bareId };
+  }
+  if (!KEY_NETWORK_RE.test(network)) {
+    throw new EncryptionResourceError(
+      "bad_network",
+      `network ${JSON.stringify(network)} must match ${KEY_NETWORK_RE.source}`
+    );
+  }
+  assertCanonicalOwner(ownerDid);
+  const networkId = `${ENCRYPTION_NETWORK_URN_PREFIX}${ownerDid}:${network}`;
+  if (rawPath.endsWith("/")) {
+    const prefix = rawPath.slice(0, -1);
+    assertPath(prefix, "prefix");
+    return { kind: "prefix", ownerDid, network, networkId, prefix };
+  }
+  assertPath(rawPath, "key path");
+  return { kind: "key", ownerDid, network, networkId, path: rawPath };
+}
+function canonicalNetworkId(networkId) {
+  let parsed;
+  try {
+    parsed = parseNetworkId(networkId);
+  } catch (error) {
+    if (error instanceof NetworkIdError) {
+      throw new EncryptionResourceError("bad_network", error.message);
+    }
+    throw error;
+  }
+  assertCanonicalOwner(parsed.ownerDid);
+  return parsed.networkId;
+}
+function parseBuilt(resource, networkId) {
+  if (parseEncryptionResource(resource).networkId !== networkId) {
+    throw new EncryptionResourceError(
+      "malformed",
+      `built resource does not round-trip (got ${JSON.stringify(resource)})`
+    );
+  }
+}
+function formatKeyResource(networkId, path) {
+  const id = canonicalNetworkId(networkId);
+  assertPath(path, "key path");
+  const resource = `${id}/${path}`;
+  parseBuilt(resource, id);
+  return resource;
+}
+function nodeSupportsNamedKeys(info) {
+  const features = info?.features;
+  return Array.isArray(features) && features.includes(NAMED_KEYS_FEATURE);
+}
+
+// src/encryption/namedKeys.ts
+var KEY_ADMIN_FACT_TYPE = "tinycloud.encryption.key-admin/v1";
+var KEY_DESCRIBE_FACT_TYPE = "tinycloud.encryption.key-describe/v1";
+var NAMED_KEY_ENVELOPE_VERSION = 2;
+var MAX_ECHO_CHARS = 120;
+function escapeNonPrintable(value) {
+  let out = "";
+  for (const ch of value) {
+    const cp = ch.codePointAt(0);
+    out += cp >= 32 && cp <= 126 ? ch : `\\u{${cp.toString(16).toUpperCase().padStart(4, "0")}}`;
+  }
+  return out;
+}
+function safeEcho(value) {
+  const text = typeof value === "string" ? value : String(value);
+  const chars = Array.from(text);
+  const clipped = chars.length > MAX_ECHO_CHARS ? `${chars.slice(0, MAX_ECHO_CHARS).join("")}...` : text;
+  return escapeNonPrintable(clipped);
+}
+var NamedKeyError = class extends Error {
+  constructor(code, message, init = {}) {
+    super(escapeNonPrintable(message), init.cause === void 0 ? void 0 : { cause: init.cause });
+    this.name = "NamedKeyError";
+    this.code = code;
+    if (init.status !== void 0) this.status = init.status;
+    if (init.nodeCode !== void 0) this.nodeCode = init.nodeCode;
+    if (init.detail !== void 0) this.detail = init.detail;
+    if (init.rawState !== void 0) this.rawState = init.rawState;
+    if (init.kind !== void 0) this.kind = init.kind;
+    if (init.input !== void 0) this.input = init.input;
+  }
+};
+var NODE_CODE_MAP = Object.assign(
+  /* @__PURE__ */ Object.create(null),
+  {
+    key_blocked: "KEY_BLOCKED",
+    key_not_found: "KEY_NOT_FOUND",
+    key_exists: "KEY_EXISTS",
+    network_not_found: "NETWORK_NOT_FOUND",
+    network_not_active: "NETWORK_NOT_ACTIVE",
+    key_limit_exceeded: "KEY_LIMIT_EXCEEDED",
+    deletable_unavailable: "DELETABLE_UNAVAILABLE",
+    key_not_deletable: "KEY_NOT_DELETABLE",
+    key_path_invalid: "KEY_PATH_INVALID",
+    key_unwrap_failed: "KEY_UNWRAP_FAILED",
+    receiver_key_invalid: "RECEIVER_KEY_INVALID"
+  }
+);
+var UNAVAILABLE_NODE_CODES = Object.assign(
+  /* @__PURE__ */ Object.create(null),
+  { key_deleted: true }
+);
+var NODE_ERROR_RE = /^([a-z][a-z0-9_]*):\s?([\s\S]*)$/;
+var MAX_NODE_CODE_CHARS = 64;
+function mapNodeKeyError(status, text, context) {
+  const match = NODE_ERROR_RE.exec(text.trim());
+  const nodeCode = match?.[1]?.slice(0, MAX_NODE_CODE_CHARS);
+  const detail = match?.[2]?.trim();
+  const base = {
+    status,
+    ...nodeCode === void 0 ? {} : { nodeCode },
+    ...detail === void 0 || detail.length === 0 ? {} : { detail }
+  };
+  if (nodeCode !== void 0) {
+    const mapped = NODE_CODE_MAP[nodeCode];
+    if (mapped !== void 0) {
+      return new NamedKeyError(mapped, `${context}: ${nodeCode}`, base);
+    }
+    if (UNAVAILABLE_NODE_CODES[nodeCode] === true) {
+      return new NamedKeyError("KEY_UNAVAILABLE", `${context}: key unavailable (${nodeCode})`, {
+        ...base,
+        rawState: nodeCode
+      });
+    }
+  }
+  return new NamedKeyError("NODE_ERROR", `${context}: node responded ${status}`, base);
+}
+function requireKeyTarget(resource) {
+  let parsed;
+  try {
+    parsed = parseEncryptionResource(resource);
+  } catch (error) {
+    throw new NamedKeyError(
+      "INVALID_KEY_TARGET",
+      `not a valid encryption key resource: ${safeEcho(error instanceof Error ? error.message : error)}`,
+      { cause: error, input: resource }
+    );
+  }
+  if (parsed.kind !== "key") {
+    throw new NamedKeyError(
+      "INVALID_KEY_TARGET",
+      `a ${parsed.kind} resource cannot be an invocation target; an exact key is required`,
+      { input: resource }
+    );
+  }
+  return parsed;
+}
+function buildKeyAdminFacts(input) {
+  const key = requireKeyTarget(input.keyResource);
+  return {
+    type: KEY_ADMIN_FACT_TYPE,
+    targetNode: input.targetNode,
+    networkId: key.networkId,
+    keyPath: key.path,
+    action: input.action,
+    bodyHash: canonicalHashHex(input.crypto.sha256, input.body)
+  };
+}
+function buildKeyDescribeFacts(input) {
+  const key = requireKeyTarget(input.keyResource);
+  return {
+    type: KEY_DESCRIBE_FACT_TYPE,
+    targetNode: input.targetNode,
+    networkId: key.networkId,
+    keyPath: key.path
+  };
+}
+var DESCRIBE_ABILITIES = {
+  [DECRYPT_ACTION]: true,
+  [KEY_CREATE_ABILITY]: true,
+  [KEY_BLOCK_ABILITY]: true,
+  [KEY_UNBLOCK_ABILITY]: true
+};
+function invalidResponse(what) {
+  return new NamedKeyError("INVALID_RESPONSE", `node returned an invalid ${what}`);
+}
+function parsePublicDescriptor(raw, networkId, keyPath) {
+  const value = typeof raw === "object" && raw !== null ? raw : {};
+  if (typeof value.alg !== "string" || typeof value.keyVersion !== "number" || !Number.isInteger(value.keyVersion) || typeof value.publicEncryptionKey !== "string" || value.publicEncryptionKey.length === 0) {
+    throw invalidResponse("key descriptor");
+  }
+  if (value.networkId !== networkId || value.keyPath !== keyPath) {
+    throw new NamedKeyError(
+      "INVALID_RESPONSE",
+      "node returned a descriptor for a different network or key"
+    );
+  }
+  return {
+    networkId,
+    keyPath,
+    alg: value.alg,
+    keyVersion: value.keyVersion,
+    publicEncryptionKey: value.publicEncryptionKey
+  };
+}
+function parseFullDescriptor(value, networkId, keyPath) {
+  const base = parsePublicDescriptor(value, networkId, keyPath);
+  const record = value;
+  if (typeof record.state !== "string" || typeof record.kind !== "string") {
+    throw invalidResponse("key descriptor (state/kind missing)");
+  }
+  return {
+    ...base,
+    state: record.state,
+    kind: record.kind,
+    ...typeof record.createdAt === "string" ? { createdAt: record.createdAt } : {},
+    ...typeof record.updatedAt === "string" ? { updatedAt: record.updatedAt } : {}
+  };
+}
+function assertEnsuredDescriptor(descriptor, expectedKind) {
+  if (descriptor.state === "blocked") {
+    throw new NamedKeyError("KEY_BLOCKED", `key ${safeEcho(descriptor.keyPath)} is blocked`, {
+      rawState: descriptor.state
+    });
+  }
+  if (descriptor.state !== "active") {
+    throw new NamedKeyError(
+      "KEY_UNAVAILABLE",
+      `key ${safeEcho(descriptor.keyPath)} is unavailable (state ${safeEcho(descriptor.state)})`,
+      { rawState: descriptor.state }
+    );
+  }
+  if (descriptor.kind !== expectedKind) {
+    throw new NamedKeyError(
+      "KEY_KIND_MISMATCH",
+      `key ${safeEcho(descriptor.keyPath)} exists with kind ${safeEcho(descriptor.kind)}, not ${expectedKind}`,
+      { kind: descriptor.kind }
+    );
+  }
+  return descriptor;
+}
+function isAppKeyPath(path) {
+  return path.startsWith("apps/");
+}
+var REQUIRED_ENVELOPE_STRINGS = [
+  "alg",
+  "encryptedSymmetricKey",
+  "encryptedSymmetricKeyHash",
+  "ciphertext"
+];
+var NamedKeyClient = class {
+  constructor(config) {
+    this.config = config;
+  }
+  networkFor(options) {
+    return options?.networkId ?? this.config.defaultNetworkId();
+  }
+  keyUrn(networkId, path) {
+    try {
+      return formatKeyResource(networkId, path);
+    } catch (error) {
+      throw new NamedKeyError(
+        "INVALID_KEY_TARGET",
+        safeEcho(error instanceof Error ? error.message : error),
+        { cause: error, input: `${networkId}/${path}` }
+      );
+    }
+  }
+  /**
+   * Require the named-keys feature and return the node DID. The first call
+   * reads `/info`; a positive answer is cached for the life of this client, so
+   * later calls make no `/info` request. A node without the feature is NOT
+   * cached: the typed `NAMED_KEYS_UNSUPPORTED` error is thrown and the next
+   * call re-reads (so a retry sees an upgraded node). No key request is made
+   * before the gate passes.
+   */
+  requireNode() {
+    if (this.nodeId === void 0) {
+      const pending = this.readNodeInfo();
+      this.nodeId = pending;
+      pending.catch(() => {
+        if (this.nodeId === pending) this.nodeId = void 0;
+      });
+    }
+    return this.nodeId;
+  }
+  /** Clear the cached `/info` answer; the next call reads it again. */
+  refreshNodeInfo() {
+    this.nodeId = void 0;
+  }
+  async readNodeInfo() {
+    const response = await this.config.fetch(`${this.config.host}/info`);
+    if (!response.ok) {
+      throw mapNodeKeyError(response.status, await safeText(response), "failed to read node info");
+    }
+    const info = await response.json();
+    if (!nodeSupportsNamedKeys(info)) {
+      throw new NamedKeyError(
+        "NAMED_KEYS_UNSUPPORTED",
+        "this node does not support named encryption keys"
+      );
+    }
+    if (typeof info.nodeId !== "string" || info.nodeId.length === 0) {
+      throw invalidResponse("/info response (nodeId missing)");
+    }
+    return info.nodeId;
+  }
+  keysUrl(networkId, path) {
+    return `${this.config.host}/encryption/networks/${networkId}/keys/${path}`;
+  }
+  /** Public GET: the key's public key. Derive-only (no 404) outside `apps/`; under `apps/` the node answers 404. */
+  async getPublicKey(path, options) {
+    const networkId = this.networkFor(options);
+    this.keyUrn(networkId, path);
+    await this.requireNode();
+    const response = await this.config.fetch(this.keysUrl(networkId, path), { method: "GET" });
+    if (!response.ok) {
+      throw mapNodeKeyError(response.status, await safeText(response), "failed to read key");
+    }
+    return parsePublicDescriptor(await response.json(), networkId, path);
+  }
+  /**
+   * Authenticated GET: the full descriptor, or `null` on `key_not_found`.
+   * `ability` is the one capability the invocation carries (default decrypt).
+   */
+  async describeKey(path, options) {
+    const networkId = this.networkFor(options);
+    const body = await this.describeBody(path, options);
+    return body === null ? null : parseFullDescriptor(body, networkId, path);
+  }
+  /** Public fields of an authenticated describe (decrypt ability); `key_not_found` throws. */
+  async describePublic(path, options) {
+    const networkId = this.networkFor(options);
+    const body = await this.describeBody(path, options);
+    if (body === null) {
+      throw new NamedKeyError("KEY_NOT_FOUND", `key ${safeEcho(path)} does not exist`, { status: 404 });
+    }
+    return parsePublicDescriptor(body, networkId, path);
+  }
+  /** The authenticated GET response body, or `null` on `key_not_found`. */
+  async describeBody(path, options) {
+    const networkId = this.networkFor(options);
+    const keyResource = this.keyUrn(networkId, path);
+    const ability = options?.ability ?? DECRYPT_ACTION;
+    if (DESCRIBE_ABILITIES[ability] !== true) {
+      throw new NamedKeyError("INVALID_KEY_TARGET", `${safeEcho(ability)} cannot describe a key`, { input: ability });
+    }
+    const targetNode = await this.requireNode();
+    const signed = await this.config.signInvocation({
+      targetNode,
+      resource: keyResource,
+      action: ability,
+      facts: buildKeyDescribeFacts({ targetNode, keyResource })
+    });
+    const response = await this.config.fetch(this.keysUrl(networkId, path), {
+      method: "GET",
+      headers: { Authorization: signed.authorization }
+    });
+    if (response.status === 404) {
+      const error = mapNodeKeyError(404, await safeText(response), "failed to describe key");
+      if (error.code === "KEY_NOT_FOUND") return null;
+      throw error;
+    }
+    if (!response.ok) {
+      throw mapNodeKeyError(response.status, await safeText(response), "failed to describe key");
+    }
+    return response.json();
+  }
+  async admin(route, action, path, options) {
+    const networkId = this.networkFor(options);
+    const keyResource = this.keyUrn(networkId, path);
+    const body = route === "keys" ? { keyPath: path, deletable: isAppKeyPath(path) } : { keyPath: path };
+    const targetNode = await this.requireNode();
+    const signed = await this.config.signInvocation({
+      targetNode,
+      resource: keyResource,
+      action,
+      facts: buildKeyAdminFacts({
+        crypto: this.config.crypto,
+        targetNode,
+        keyResource,
+        action,
+        body
+      })
+    });
+    const response = await this.config.fetch(
+      `${this.config.host}/encryption/networks/${networkId}/${route}`,
+      {
+        method: "POST",
+        headers: {
+          Authorization: signed.authorization,
+          "Content-Type": "application/json"
+        },
+        body: canonicalize(body)
+      }
+    );
+    if (!response.ok) {
+      throw mapNodeKeyError(response.status, await safeText(response), `failed to ${action}`);
+    }
+    return parseFullDescriptor(unwrapDescriptor(await response.json()), networkId, path);
+  }
+  /** `key.create`: `deletable` is `true` exactly under `apps/`, else a deterministic key. */
+  createKey(path, options) {
+    return this.admin("keys", KEY_CREATE_ABILITY, path, options);
+  }
+  blockKey(path, options) {
+    return this.admin("key-actions/block", KEY_BLOCK_ABILITY, path, options);
+  }
+  unblockKey(path, options) {
+    return this.admin("key-actions/unblock", KEY_UNBLOCK_ABILITY, path, options);
+  }
+  /**
+   * Make sure a key exists and is usable: authenticated GET; on
+   * `key_not_found` create it; on 409 `key_exists` read it again. Succeeds only
+   * for `state: "active"` and the kind the path implies: `deletable` under
+   * `apps/`, `deterministic` elsewhere.
+   */
+  async ensureKey(path, options) {
+    const describe = () => this.describeKey(path, { ...options, ability: KEY_CREATE_ABILITY });
+    let descriptor = await describe();
+    if (descriptor === null) {
+      try {
+        descriptor = await this.createKey(path, options);
+      } catch (error) {
+        if (!(error instanceof NamedKeyError) || error.code !== "KEY_EXISTS") throw error;
+        descriptor = await describe();
+        if (descriptor === null) {
+          throw new NamedKeyError(
+            "KEY_NOT_FOUND",
+            `key ${safeEcho(path)} reported as existing but could not be read back`
+          );
+        }
+      }
+    }
+    return assertEnsuredDescriptor(descriptor, isAppKeyPath(path) ? "deletable" : "deterministic");
+  }
+  /** Encrypt to a named key: envelope v2, symmetric key wrapped to the key's public key. */
+  async encrypt(path, plaintext, options) {
+    const descriptor = isAppKeyPath(path) ? await this.describePublic(path, options) : await this.getPublicKey(path, options);
+    const { crypto } = this.config;
+    const symmetricKey = crypto.randomBytes(32);
+    const ciphertext = crypto.authEncrypt(symmetricKey, plaintext, options?.aad);
+    const wrapped = crypto.sealToNetworkKey(
+      base64Decode(descriptor.publicEncryptionKey),
+      symmetricKey
+    );
+    const encryptedSymmetricKey = base64Encode(wrapped);
+    return {
+      v: NAMED_KEY_ENVELOPE_VERSION,
+      networkId: descriptor.networkId,
+      keyPath: descriptor.keyPath,
+      alg: descriptor.alg ?? DEFAULT_ENCRYPTION_ALG,
+      keyVersion: descriptor.keyVersion,
+      encryptedSymmetricKey,
+      encryptedSymmetricKeyHash: canonicalHashHex(crypto.sha256, encryptedSymmetricKey),
+      ciphertext: base64Encode(ciphertext),
+      ...options?.aad !== void 0 ? { aad: base64Encode(options.aad) } : {},
+      ...options?.metadata !== void 0 ? { metadata: options.metadata } : {}
+    };
+  }
+  /**
+   * Decrypt one envelope. v1 (no `keyPath`) uses the root-key path exactly as
+   * before; v2 uses one decrypt capability on the exact key via `/invoke`.
+   */
+  async decrypt(envelope) {
+    const candidate = typeof envelope === "object" && envelope !== null ? envelope : {};
+    if (candidate.v === 1 && candidate.keyPath === void 0) {
+      return this.decryptRoot(candidate);
+    }
+    if (candidate.v === NAMED_KEY_ENVELOPE_VERSION && typeof candidate.keyPath === "string") {
+      return this.decryptKey(this.validateKeyEnvelope(candidate));
+    }
+    throw new NamedKeyError(
+      "INVALID_ENVELOPE",
+      "envelope must be v1 without keyPath or v2 with keyPath"
+    );
+  }
+  /**
+   * Decrypt a batch. Each envelope is its own invocation with its own single
+   * capability, so v1 and v2 (or two different keys) are never combined.
+   */
+  async decryptMany(envelopes) {
+    const results = [];
+    for (const envelope of envelopes) {
+      try {
+        results.push({ ok: true, data: await this.decrypt(envelope) });
+      } catch (error) {
+        results.push({
+          ok: false,
+          error: error instanceof NamedKeyError ? error : new NamedKeyError("DECRYPT_FAILED", "decrypt failed", { cause: error })
+        });
+      }
+    }
+    return results;
+  }
+  async decryptRoot(envelope) {
+    if (this.config.decryptRoot === void 0) {
+      throw new NamedKeyError("DECRYPT_FAILED", "no root-key decrypt path is configured");
+    }
+    const result = await this.config.decryptRoot(envelope);
+    if (!result.ok) {
+      throw new NamedKeyError("DECRYPT_FAILED", safeEcho(result.error.message), { cause: result.error });
+    }
+    return result.data;
+  }
+  validateKeyEnvelope(e) {
+    for (const field of REQUIRED_ENVELOPE_STRINGS) {
+      if (typeof e[field] !== "string" || e[field].length === 0) {
+        throw new NamedKeyError("INVALID_ENVELOPE", `envelope.${field} must be a non-empty string`);
+      }
+    }
+    if (typeof e.keyVersion !== "number" || !Number.isInteger(e.keyVersion)) {
+      throw new NamedKeyError("INVALID_ENVELOPE", "envelope.keyVersion must be an integer");
+    }
+    if (typeof e.networkId !== "string") {
+      throw new NamedKeyError("INVALID_ENVELOPE", "envelope.networkId must be a string");
+    }
+    try {
+      parseNetworkId(e.networkId);
+    } catch (error) {
+      throw new NamedKeyError("INVALID_ENVELOPE", "envelope.networkId is malformed", { cause: error });
+    }
+    const expectedHash = canonicalHashHex(
+      this.config.crypto.sha256,
+      e.encryptedSymmetricKey
+    );
+    if (expectedHash !== e.encryptedSymmetricKeyHash) {
+      throw new NamedKeyError(
+        "INVALID_ENVELOPE",
+        "envelope.encryptedSymmetricKeyHash does not match encryptedSymmetricKey"
+      );
+    }
+    return e;
+  }
+  async decryptKey(envelope) {
+    const { crypto } = this.config;
+    const keyResource = this.keyUrn(envelope.networkId, envelope.keyPath);
+    const targetNode = await this.requireNode();
+    const receiverKey = generateRandomReceiverKey({ crypto });
+    const receiverPublicKey = base64Encode(receiverKey.publicKey);
+    const receiverPublicKeyHash = canonicalHashHex(crypto.sha256, receiverPublicKey);
+    const body = {
+      type: DECRYPT_FACT_TYPE,
+      targetNode,
+      networkId: envelope.networkId,
+      keyPath: envelope.keyPath,
+      alg: envelope.alg,
+      keyVersion: envelope.keyVersion,
+      encryptedSymmetricKey: envelope.encryptedSymmetricKey,
+      encryptedSymmetricKeyHash: envelope.encryptedSymmetricKeyHash,
+      receiverPublicKey,
+      receiverPublicKeyHash
+    };
+    const canonicalBody = canonicalize(body);
+    const facts = {
+      type: DECRYPT_FACT_TYPE,
+      targetNode,
+      networkId: envelope.networkId,
+      keyPath: envelope.keyPath,
+      bodyHash: canonicalHashHex(crypto.sha256, body),
+      encryptedSymmetricKeyHash: envelope.encryptedSymmetricKeyHash,
+      receiverPublicKeyHash,
+      alg: envelope.alg,
+      keyVersion: envelope.keyVersion
+    };
+    const signed = await this.config.signInvocation({
+      targetNode,
+      resource: keyResource,
+      action: DECRYPT_ACTION,
+      facts
+    });
+    const response = await this.config.fetch(`${this.config.host}/invoke`, {
+      method: "POST",
+      headers: {
+        Authorization: signed.authorization,
+        "Content-Type": "application/json"
+      },
+      body: canonicalBody
+    });
+    if (!response.ok) {
+      throw mapNodeKeyError(response.status, await safeText(response), "failed to decrypt");
+    }
+    const verified = verifyDecryptResponse({
+      crypto,
+      request: body,
+      facts,
+      invocationCid: signed.invocationCid,
+      requestBodyHash: facts.bodyHash,
+      response: await response.json()
+    });
+    if (!verified.ok) {
+      throw new NamedKeyError("INVALID_RESPONSE", safeEcho(verified.error.message), { cause: verified.error });
+    }
+    const symmetricKey = openWrappedKey(crypto, receiverKey.privateKey, verified.data);
+    try {
+      return crypto.authDecrypt(
+        symmetricKey,
+        base64Decode(envelope.ciphertext),
+        envelope.aad !== void 0 ? base64Decode(envelope.aad) : void 0
+      );
+    } catch (error) {
+      throw new NamedKeyError("DECRYPT_FAILED", "local decryption failed", { cause: error });
+    }
+  }
+};
+function unwrapDescriptor(body) {
+  const outer = typeof body === "object" && body !== null ? body : {};
+  return typeof outer.descriptor === "object" && outer.descriptor !== null ? outer.descriptor : body;
+}
+async function safeText(response) {
+  try {
+    return await response.text();
+  } catch {
+    return "";
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  KEY_ADMIN_FACT_TYPE,
+  KEY_DESCRIBE_FACT_TYPE,
+  NAMED_KEY_ENVELOPE_VERSION,
+  NamedKeyClient,
+  NamedKeyError,
+  buildKeyAdminFacts,
+  buildKeyDescribeFacts,
+  mapNodeKeyError,
+  requireKeyTarget,
+  safeEcho
+});
+//# sourceMappingURL=named-keys.cjs.map