@opengeni/sdk 3.1.2 → 3.2.2

package/dist/external-vault-receiver.js

@@ -0,0 +1,564 @@
+import {
+  OPENGENI_SIGNATURE_HEADER,
+  signOpenGeniPayload,
+  verifyOpenGeniSignature
+} from "./chunk-KGEABAID.js";
+
+// src/external-vault-receiver.ts
+import {
+  VAULT_PROVIDER_WIRE_LIMITS,
+  VAULT_PROVIDER_WIRE_RESPONSE_SIGNATURE_HEADER,
+  VAULT_PROVIDER_WIRE_VERSION,
+  VaultProviderWireFreshness,
+  VaultProviderWireRequest,
+  VaultProviderWireResults,
+  isVaultProviderWireMutation,
+  vaultProviderWireNameKey,
+  vaultProviderWireResponseKey,
+  vaultProviderWireUtf8Bytes
+} from "@opengeni/contracts/vault-provider-wire";
+import {
+  VAULT_PROVIDER_WIRE_ERROR_CODES,
+  VAULT_PROVIDER_WIRE_LIMITS as VAULT_PROVIDER_WIRE_LIMITS2,
+  VAULT_PROVIDER_WIRE_RESPONSE_SIGNATURE_HEADER as VAULT_PROVIDER_WIRE_RESPONSE_SIGNATURE_HEADER2,
+  VAULT_PROVIDER_WIRE_VERSION as VAULT_PROVIDER_WIRE_VERSION2,
+  vaultProviderWireResponseKey as vaultProviderWireResponseKey2
+} from "@opengeni/contracts/vault-provider-wire";
+var ExternalVaultReceiverError = class extends Error {
+  code;
+  retryAfterMs;
+  freshness;
+  constructor(code, options = {}) {
+    super(options.message ?? code);
+    this.name = "ExternalVaultReceiverError";
+    this.code = code;
+    this.retryAfterMs = options.retryAfterMs === void 0 ? null : Math.min(Math.max(Math.trunc(options.retryAfterMs), 0), 864e5);
+    this.freshness = options.freshness ?? null;
+  }
+};
+var JSON_HEADERS = { "content-type": "application/json", "cache-control": "no-store" };
+var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function plain(status, error) {
+  return { status, headers: { ...JSON_HEADERS }, body: JSON.stringify({ error }) };
+}
+function headerValue(headers, name) {
+  if (headers instanceof Headers) return headers.get(name);
+  const wanted = name.toLowerCase();
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === wanted) {
+      return Array.isArray(value) ? value.length === 1 ? value[0] ?? null : null : value ?? null;
+    }
+  }
+  return null;
+}
+function canonicalJson(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  const entries = Object.entries(value).filter(([, entry]) => entry !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+  return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`).join(",")}}`;
+}
+async function hmacHex(key, message) {
+  const encoder = new TextEncoder();
+  const cryptoKey = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(key),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const mac = new Uint8Array(await crypto.subtle.sign("HMAC", cryptoKey, encoder.encode(message)));
+  return Array.from(mac, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+async function externalVaultMutationDigest(input) {
+  const { request } = input;
+  const { idempotencyKey: _ignored, ...operation } = request.operation;
+  return hmacHex(
+    `${input.signingSecret}\0${VAULT_PROVIDER_WIRE_VERSION}.idempotency`,
+    canonicalJson({
+      connectionId: request.connectionId.toLowerCase(),
+      provider: request.provider,
+      accountId: request.authority.accountId,
+      workspaceId: request.authority.workspaceId,
+      subjectId: request.authority.subjectId,
+      connectionWorkspaceId: request.authority.connectionWorkspaceId,
+      operation
+    })
+  );
+}
+function pick(value, keys) {
+  const out = {};
+  for (const key of keys) if (value[key] !== void 0) out[key] = value[key];
+  return out;
+}
+function project(op, raw) {
+  if (!raw || typeof raw !== "object") return raw;
+  const result = raw;
+  const field = (f) => f && typeof f === "object" ? pick(f, ["externalFieldId", "name", "kind"]) : f;
+  const item = (i) => i && typeof i === "object" ? {
+    ...pick(i, ["externalItemId", "name", "type", "websites", "version", "updatedAt"]),
+    fields: Array.isArray(i.fields) ? i.fields.map(field) : i.fields
+  } : i;
+  const vault = (v) => v && typeof v === "object" ? pick(v, [
+    "externalVaultId",
+    "name",
+    "contentVersion",
+    "itemCount",
+    "writeAccess",
+    "operations"
+  ]) : v;
+  switch (op) {
+    case "describe":
+      return pick(result, [
+        "accountId",
+        "accountName",
+        "operations",
+        "capabilities",
+        "inventoryScope"
+      ]);
+    case "refresh":
+      return pick(result, ["refreshed"]);
+    case "list_vaults":
+    case "list_items":
+      return {
+        ...pick(result, ["nextCursor", "snapshot"]),
+        items: Array.isArray(result.items) ? result.items.map(op === "list_vaults" ? vault : item) : result.items
+      };
+    case "read_fields":
+      return {
+        fields: Array.isArray(result.fields) ? result.fields.map(
+          (f) => f && typeof f === "object" ? pick(f, ["externalFieldId", "value"]) : f
+        ) : result.fields
+      };
+    case "write_item":
+      return { item: item(result.item) };
+    case "archive_item":
+      return pick(result, ["archived"]);
+  }
+}
+function safeExternalVaultName(raw, fallback = "Untitled") {
+  const forbidden = /[/{}#\\\u0000-\u001f\u007f-\u009f]/g;
+  const clean = (value) => [...value.replace(forbidden, "-").trim()].slice(0, 120).join("").trim();
+  let name = clean(typeof raw === "string" ? raw : "");
+  if (!name) name = clean(fallback) || "Untitled";
+  if (/^id:/i.test(name)) name = `id-${name.slice(3)}`;
+  return name;
+}
+function uniqueExternalVaultFieldName(raw, taken, fallback = "field") {
+  let base = safeExternalVaultName(raw, fallback);
+  if (vaultProviderWireNameKey(base) === "otp") base = "otp-code";
+  let candidate = base;
+  for (let n = 2; taken.has(vaultProviderWireNameKey(candidate)); n += 1) {
+    const suffix = ` (${n})`;
+    candidate = `${[...base].slice(0, 120 - suffix.length).join("")}${suffix}`;
+  }
+  taken.add(vaultProviderWireNameKey(candidate));
+  return candidate;
+}
+function createInMemoryExternalVaultReceiverStore(options = {}) {
+  const maxEntries = options.maxEntries ?? 1e4;
+  const now = options.now ?? (() => Date.now());
+  const requests = /* @__PURE__ */ new Map();
+  const mutations = /* @__PURE__ */ new Map();
+  const prune = () => {
+    const t = now();
+    for (const [key, expiresAt] of requests) if (expiresAt <= t) requests.delete(key);
+    for (const [key, entry] of mutations) if (entry.expiresAt <= t) mutations.delete(key);
+  };
+  const full = () => requests.size + mutations.size >= maxEntries;
+  return {
+    size: () => requests.size + mutations.size,
+    async rememberRequest({ connectionId, requestId, expiresAt }) {
+      prune();
+      const key = `${connectionId}\0${requestId}`;
+      if (requests.has(key)) return false;
+      if (full()) throw new ExternalVaultReceiverError("provider_rate_limited");
+      requests.set(key, expiresAt.getTime());
+      return true;
+    },
+    async claimMutation({ connectionId, idempotencyKey, digest, expiresAt }) {
+      prune();
+      const key = `${connectionId}\0${idempotencyKey}`;
+      const existing = mutations.get(key);
+      if (existing) {
+        if (existing.digest !== digest) return { state: "mismatch" };
+        return existing.state === "completed" ? { state: "completed", result: structuredClone(existing.result) } : { state: "pending" };
+      }
+      if (full()) throw new ExternalVaultReceiverError("provider_rate_limited");
+      mutations.set(key, { digest, expiresAt: expiresAt.getTime(), state: "pending" });
+      return { state: "claimed" };
+    },
+    async completeMutation({ connectionId, idempotencyKey, digest, result }) {
+      const entry = mutations.get(`${connectionId}\0${idempotencyKey}`);
+      if (!entry || entry.digest !== digest) throw new Error("mutation claim missing");
+      entry.state = "completed";
+      entry.result = structuredClone(result);
+    },
+    async releaseMutation({ connectionId, idempotencyKey, digest }) {
+      const key = `${connectionId}\0${idempotencyKey}`;
+      if (mutations.get(key)?.digest === digest) mutations.delete(key);
+    }
+  };
+}
+function operationTarget(operation) {
+  return {
+    op: operation.op,
+    ..."externalVaultId" in operation ? { externalVaultId: operation.externalVaultId } : {},
+    ..."externalItemId" in operation ? { externalItemId: operation.externalItemId } : {},
+    ...operation.op === "write_item" && operation.item.externalItemId ? { externalItemId: operation.item.externalItemId } : {}
+  };
+}
+function createExternalVaultReceiver(options) {
+  const now = options.now ?? (() => Date.now());
+  const tolerance = VAULT_PROVIDER_WIRE_LIMITS.signatureToleranceSeconds;
+  const retentionMs = Math.max(options.mutationRetentionMs ?? 864e5, tolerance * 2e3);
+  const report = (stage, op, connectionId, error) => {
+    try {
+      options.onError?.({ stage, op, connectionId, error });
+    } catch {
+    }
+  };
+  async function signed(secret, response) {
+    const body = JSON.stringify(response);
+    const signature = await signOpenGeniPayload(
+      vaultProviderWireResponseKey(secret),
+      body,
+      Math.floor(now() / 1e3)
+    );
+    return {
+      status: 200,
+      headers: { ...JSON_HEADERS, [VAULT_PROVIDER_WIRE_RESPONSE_SIGNATURE_HEADER]: signature },
+      body
+    };
+  }
+  async function handle(request) {
+    if (typeof request.body !== "string") return plain(400, "invalid_request");
+    if (vaultProviderWireUtf8Bytes(request.body) > VAULT_PROVIDER_WIRE_LIMITS.maxRequestBytes) {
+      return plain(413, "request_too_large");
+    }
+    const signature = headerValue(request.headers, OPENGENI_SIGNATURE_HEADER);
+    if (!signature) return plain(401, "unauthorized");
+    let raw;
+    try {
+      raw = JSON.parse(request.body);
+    } catch {
+      return plain(400, "invalid_request");
+    }
+    const claimedConnectionId = raw && typeof raw === "object" ? raw.connectionId : void 0;
+    if (typeof claimedConnectionId !== "string" || !UUID.test(claimedConnectionId)) {
+      return plain(401, "unauthorized");
+    }
+    const connectionId = claimedConnectionId.toLowerCase();
+    let connection;
+    try {
+      connection = await options.resolveConnection(connectionId);
+    } catch (error) {
+      report("store", "describe", connectionId, error);
+      return plain(503, "unavailable");
+    }
+    if (!connection || connection.signingSecrets.length === 0) return plain(401, "unauthorized");
+    let secret = null;
+    for (const candidate of connection.signingSecrets.slice(0, 4)) {
+      if (await verifyOpenGeniSignature({
+        secret: candidate,
+        body: request.body,
+        signature,
+        toleranceSeconds: tolerance,
+        nowSeconds: Math.floor(now() / 1e3)
+      })) {
+        secret = candidate;
+        break;
+      }
+    }
+    if (!secret) return plain(401, "unauthorized");
+    const parsed = VaultProviderWireRequest.safeParse(raw);
+    if (!parsed.success) return plain(400, "invalid_request");
+    const wire = parsed.data;
+    const op = wire.operation.op;
+    const sentAt = Date.parse(wire.sentAt);
+    if (!Number.isFinite(sentAt) || Math.abs(now() - sentAt) > tolerance * 1e3) {
+      return plain(401, "unauthorized");
+    }
+    const failure = (code, extra = {}) => signed(secret, {
+      version: VAULT_PROVIDER_WIRE_VERSION,
+      type: "response",
+      requestId: wire.requestId,
+      ok: false,
+      op,
+      error: { code, retryAfterMs: extra.retryAfterMs ?? null },
+      // Host-supplied freshness is validated like handler output; invalid is dropped.
+      freshness: extra.freshness == null ? null : VaultProviderWireFreshness.safeParse(extra.freshness).data ?? null
+    });
+    try {
+      const fresh = await options.store.rememberRequest({
+        connectionId,
+        requestId: wire.requestId,
+        expiresAt: new Date(now() + tolerance * 2e3)
+      });
+      if (!fresh) return plain(409, "replayed_request");
+    } catch (error) {
+      report("store", op, connectionId, error);
+      if (error instanceof ExternalVaultReceiverError) return failure(error.code);
+      return failure("provider_unavailable");
+    }
+    if (wire.provider !== connection.provider || connection.accountId !== void 0 && wire.authority.accountId !== connection.accountId || connection.connectionWorkspaceId !== void 0 && wire.authority.connectionWorkspaceId !== connection.connectionWorkspaceId) {
+      return failure("provider_permission_denied");
+    }
+    let principal;
+    try {
+      principal = await options.authorize({
+        connectionId,
+        connection: connection.context,
+        authority: wire.authority,
+        operation: operationTarget(wire.operation),
+        requestId: wire.requestId
+      });
+    } catch (error) {
+      report("authorize", op, connectionId, error);
+      if (error instanceof ExternalVaultReceiverError) return failure(error.code);
+      return failure("provider_unavailable");
+    }
+    if (principal === null || principal === void 0) {
+      return failure("provider_permission_denied");
+    }
+    const inventory = {
+      connectionId,
+      connection: connection.context,
+      requestId: wire.requestId,
+      ...request.signal ? { signal: request.signal } : {}
+    };
+    const call = {
+      ...inventory,
+      principal,
+      authority: wire.authority
+    };
+    const respond = async (output2) => {
+      const projected = project(op, output2?.result);
+      const result = VaultProviderWireResults[op].safeParse(projected);
+      const freshness = output2?.freshness == null ? null : VaultProviderWireFreshness.safeParse(output2.freshness);
+      if (!result.success || freshness && !freshness.success) {
+        report("output", op, connectionId, result.error ?? freshness?.error);
+        return { ok: false, code: "provider_unavailable" };
+      }
+      const consistency = checkConsistency(wire.operation, result.data);
+      if (consistency) return { ok: false, code: consistency };
+      return {
+        ok: true,
+        result: result.data,
+        response: await signed(secret, {
+          version: VAULT_PROVIDER_WIRE_VERSION,
+          type: "response",
+          requestId: wire.requestId,
+          ok: true,
+          op,
+          result: result.data,
+          freshness: freshness ? freshness.data : null
+        })
+      };
+    };
+    if (!isVaultProviderWireMutation(op)) {
+      try {
+        const output2 = await runRead(wire.operation, inventory, call);
+        if (!output2) return failure("provider_permission_denied");
+        const outcome2 = await respond(output2);
+        return outcome2.ok ? outcome2.response : failure(outcome2.code);
+      } catch (error) {
+        if (error instanceof ExternalVaultReceiverError) {
+          return failure(error.code, {
+            retryAfterMs: error.retryAfterMs,
+            freshness: error.freshness
+          });
+        }
+        report("handler", op, connectionId, error);
+        return failure("provider_unavailable");
+      }
+    }
+    const mutation = wire.operation;
+    const handler = mutation.op === "write_item" ? options.handlers.writeItem : options.handlers.archiveItem;
+    if (!handler) return failure("provider_permission_denied");
+    const digest = await externalVaultMutationDigest({ signingSecret: secret, request: wire });
+    const key = { connectionId, idempotencyKey: mutation.idempotencyKey, digest };
+    let claim;
+    try {
+      claim = await options.store.claimMutation({
+        ...key,
+        expiresAt: new Date(now() + retentionMs)
+      });
+    } catch (error) {
+      report("store", op, connectionId, error);
+      return failure(
+        error instanceof ExternalVaultReceiverError ? error.code : "provider_unavailable"
+      );
+    }
+    if (claim.state === "mismatch") return failure("provider_conflict");
+    if (claim.state === "pending") return failure("provider_outcome_unknown");
+    if (claim.state === "completed") {
+      const outcome2 = await respond({ result: claim.result });
+      return outcome2.ok ? outcome2.response : failure("provider_outcome_unknown");
+    }
+    let output;
+    try {
+      output = mutation.op === "write_item" ? await options.handlers.writeItem(call, {
+        externalVaultId: mutation.externalVaultId,
+        item: mutation.item,
+        idempotencyKey: mutation.idempotencyKey
+      }) : await options.handlers.archiveItem(call, {
+        externalVaultId: mutation.externalVaultId,
+        externalItemId: mutation.externalItemId,
+        idempotencyKey: mutation.idempotencyKey
+      });
+    } catch (error) {
+      if (error instanceof ExternalVaultReceiverError && error.code !== "provider_outcome_unknown") {
+        try {
+          await options.store.releaseMutation(key);
+        } catch (storeError) {
+          report("store", op, connectionId, storeError);
+        }
+        return failure(error.code, {
+          retryAfterMs: error.retryAfterMs,
+          freshness: error.freshness
+        });
+      }
+      report("handler", op, connectionId, error);
+      return failure("provider_outcome_unknown");
+    }
+    const outcome = await respond(output);
+    if (!outcome.ok) return failure("provider_outcome_unknown");
+    try {
+      await options.store.completeMutation({ ...key, result: outcome.result });
+    } catch (error) {
+      report("store", op, connectionId, error);
+    }
+    return outcome.response;
+  }
+  async function runRead(operation, inventory, call) {
+    const handlers = options.handlers;
+    switch (operation.op) {
+      case "describe":
+        return handlers.describe(inventory);
+      case "refresh":
+        return handlers.refresh ? handlers.refresh(inventory) : null;
+      case "list_vaults":
+        return handlers.listVaults(inventory, {
+          page: operation.page,
+          forceRefresh: operation.forceRefresh,
+          cacheEpoch: operation.cacheEpoch
+        });
+      case "list_items":
+        return handlers.listItems(inventory, {
+          externalVaultId: operation.externalVaultId,
+          page: operation.page,
+          forceRefresh: operation.forceRefresh,
+          cacheEpoch: operation.cacheEpoch
+        });
+      case "read_fields":
+        return handlers.readFields(call, {
+          externalVaultId: operation.externalVaultId,
+          externalItemId: operation.externalItemId,
+          externalFieldIds: operation.externalFieldIds,
+          forceRefresh: operation.forceRefresh,
+          cacheEpoch: operation.cacheEpoch
+        });
+      default:
+        return null;
+    }
+  }
+  return {
+    handle,
+    async fetch(request) {
+      if (request.method !== "POST") {
+        return new Response(JSON.stringify({ error: "method_not_allowed" }), {
+          status: 405,
+          headers: { ...JSON_HEADERS, allow: "POST" }
+        });
+      }
+      const max = VAULT_PROVIDER_WIRE_LIMITS.maxRequestBytes;
+      const declared = Number(request.headers.get("content-length") ?? "0");
+      if (Number.isFinite(declared) && declared > max) {
+        await request.body?.cancel().catch(() => {
+        });
+        const response2 = plain(413, "request_too_large");
+        return new Response(response2.body, { status: response2.status, headers: response2.headers });
+      }
+      const chunks = [];
+      let total = 0;
+      const reader = request.body?.getReader();
+      if (reader) {
+        for (; ; ) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          total += value.byteLength;
+          if (total > max) {
+            await reader.cancel().catch(() => {
+            });
+            const response2 = plain(413, "request_too_large");
+            return new Response(response2.body, {
+              status: response2.status,
+              headers: response2.headers
+            });
+          }
+          chunks.push(value);
+        }
+      }
+      const bytes = new Uint8Array(total);
+      let offset = 0;
+      for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+      }
+      let body;
+      try {
+        body = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+      } catch {
+        const response2 = plain(400, "invalid_request");
+        return new Response(response2.body, { status: response2.status, headers: response2.headers });
+      }
+      const response = await handle({ body, headers: request.headers, signal: request.signal });
+      return new Response(response.body, { status: response.status, headers: response.headers });
+    }
+  };
+}
+function checkConsistency(operation, result) {
+  switch (operation.op) {
+    case "list_vaults":
+    case "list_items": {
+      const page = result;
+      if (page.items.length > operation.page.limit) return "provider_unavailable";
+      const ids = /* @__PURE__ */ new Set();
+      for (const entry of page.items) {
+        const id = entry.externalVaultId ?? entry.externalItemId ?? "";
+        if (ids.has(id)) return "provider_unavailable";
+        ids.add(id);
+      }
+      return null;
+    }
+    case "read_fields": {
+      const fields = result.fields;
+      const requested = new Set(operation.externalFieldIds);
+      if (fields.some((field) => !requested.has(field.externalFieldId))) {
+        return "provider_unavailable";
+      }
+      return fields.length === requested.size ? null : "provider_not_found";
+    }
+    case "write_item": {
+      const item = result.item;
+      const expected = operation.item.externalItemId;
+      return expected !== void 0 && item.externalItemId !== expected ? "provider_outcome_unknown" : null;
+    }
+    default:
+      return null;
+  }
+}
+export {
+  ExternalVaultReceiverError,
+  VAULT_PROVIDER_WIRE_ERROR_CODES,
+  VAULT_PROVIDER_WIRE_LIMITS2 as VAULT_PROVIDER_WIRE_LIMITS,
+  VAULT_PROVIDER_WIRE_RESPONSE_SIGNATURE_HEADER2 as VAULT_PROVIDER_WIRE_RESPONSE_SIGNATURE_HEADER,
+  VAULT_PROVIDER_WIRE_VERSION2 as VAULT_PROVIDER_WIRE_VERSION,
+  createExternalVaultReceiver,
+  createInMemoryExternalVaultReceiverStore,
+  externalVaultMutationDigest,
+  safeExternalVaultName,
+  uniqueExternalVaultFieldName,
+  vaultProviderWireResponseKey2 as vaultProviderWireResponseKey
+};
+//# sourceMappingURL=external-vault-receiver.js.map