@opendatalabs/vana-sdk 3.22.0 → 3.23.0-pr.211.341f55d

package/dist/protocol/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/protocol/identity.ts"],"sourcesContent":["/**\n * Enclave identity and consent primitives for Personal Servers.\n *\n * Owner/Web -> Gateway -> Agent(CVM): derive wallet and quote\n * Web verifies evidence; Account authenticates and encrypts the EIP-191 master\n * signature to the enclave key; Gateway relays it blind; Agent decrypts/seals.\n *\n * @category Protocol\n */\n\nimport * as secp256k1 from \"@noble/secp256k1\";\nimport {\n  concat,\n  encodePacked,\n  fromHex,\n  getAddress,\n  isAddressEqual,\n  keccak256,\n  recoverPublicKey,\n  toBytes,\n  toHex,\n  type Address,\n  type Hex,\n} from \"viem\";\nimport { publicKeyToAddress } from \"viem/accounts\";\nimport { serializeECIES, type ECIESProvider } from \"../crypto/ecies/interface\";\nimport { deriveMasterKey, recoverServerOwner } from \"../crypto/keys/derive\";\nimport type { ServerRegistrationMessage } from \"./eip712\";\n\nexport const ENCLAVE_IDENTITY_EVIDENCE_VERSION = 1;\nexport const USER_PS_ID_DOMAIN = \"vana.ps-enclave.v1\";\nexport const ENCLAVE_WALLET_PURPOSE = \"vana.ps-enclave.wallet.v1\";\nexport const MASTER_SIGNATURE_DELIVERY_VERSION = \"vana.ps-enclave.delivery.v1\";\n/** Agent rejects deliveries when `|now - issuedAt|` exceeds this value. */\nexport const MASTER_SIGNATURE_DELIVERY_MAX_AGE_SECONDS = 600;\nexport const SEALED_ENVELOPE_VERSION = 1;\n\nconst VANA_MAINNET_CHAIN_ID = 1480;\nconst MOKSHA_CHAIN_ID = 14800;\nconst KMS_ISSUED_PREFIX = \"dstack-kms-issued\";\nconst PREIMAGE_SEPARATOR = \":\";\nconst UNCOMPRESSED_PUBLIC_KEY_BYTES = 65;\nconst UNCOMPRESSED_PUBLIC_KEY_PREFIX = \"04\";\nconst EMPTY_HEX = \"0x\";\n\n/** `keccak256(encodePacked([string,uint256,address], [USER_PS_ID_DOMAIN,chainId,owner]))`. */\nexport type UserPsId = Hex;\n\n/** Attested identity evidence returned by the enclave agent. */\nexport interface EnclaveIdentityEvidence {\n  v: typeof ENCLAVE_IDENTITY_EVIDENCE_VERSION;\n  userPsId: UserPsId;\n  chainId: number;\n  ownerAddress: Address;\n  /** Path suffix `users/{id}/wallet/ethereum/secp256k1/v{epoch}`. */\n  epoch: number;\n  address: Address;\n  /** 65-byte uncompressed `0x04..`; `publicKeyToAddress(publicKey) == address`. */\n  publicKey: Hex;\n  /** 20-byte dstack `app_id`. */\n  appId: Hex;\n  /** 32-byte compose hash. */\n  composeHash: Hex;\n  /** Omitted when the OS does not expose its image hash. */\n  osImageHash?: Hex;\n  /** Must equal `ENCLAVE_WALLET_PURPOSE`. */\n  purpose: string;\n  /** `[appRoot over link 0, kmsRoot over link 1]`; see `appRootPreimage` and `kmsIssuedPreimage`. */\n  signatureChain: [Hex, Hex];\n  /** Raw TDX quote with report_data `keccak256(userPsId || address)`; not parsed. */\n  quote: Hex;\n  eventLog?: string;\n  /** `keccak256` of the uncompressed KMS root public key. */\n  kmsRootFingerprint: Hex;\n}\n\n/** Identity values the caller expects the evidence to bind. */\nexport interface ExpectedIdentity {\n  ownerAddress: Address;\n  chainId: number;\n  epoch: number;\n}\n\n/** Request for an owner-scoped enclave identity. */\nexport interface IdentityRequest {\n  ownerAddress: Address;\n  chainId: number;\n}\n\n/** Lifecycle state of an enclave identity. */\nexport type IdentityState = \"prepared\" | \"registered\" | \"sealed\" | \"retired\";\n\n/** Gateway response containing enclave identity state and registration data. */\nexport interface IdentityResponse {\n  identity: EnclaveIdentityEvidence;\n  state: IdentityState;\n  created: boolean;\n  /** Exact `ServerRegistration.serverUrl` the owner signs. */\n  serverUrl: string;\n  serverId?: Hex;\n  serverStatus?:\n    | \"pending\"\n    | \"submitting\"\n    | \"confirmed\"\n    | \"finalized\"\n    | \"failed\";\n  sealed: boolean;\n}\n\n/** Versioned server-registration request for an enclave identity. */\nexport type IdentityRegistrationRequest =\n  | { version: \"v2\"; message: ServerRegistrationMessage }\n  | {\n      version: \"v3\";\n      message: ServerRegistrationMessage & { nonce: string; deadline: string };\n    };\n\n/** Accepted identity-registration response. */\nexport interface IdentityRegistrationResponse {\n  serverId: Hex;\n  state: \"registered\";\n  serverStatus: \"pending\";\n}\n\n/** Inner plaintext of the ECIES box. */\nexport interface MasterSignatureDelivery {\n  v: typeof MASTER_SIGNATURE_DELIVERY_VERSION;\n  userPsId: UserPsId;\n  epoch: number;\n  enclaveAddress: Address;\n  ownerAddress: Address;\n  /** 65-byte EIP-191 signature over `MASTER_KEY_MESSAGE`. */\n  masterSignature: Hex;\n  /** Unix seconds; see `MASTER_SIGNATURE_DELIVERY_MAX_AGE_SECONDS`. */\n  issuedAt: number;\n}\n\n/** Enclave-bound ciphertext submitted for sealing. */\nexport interface SealedSecretSubmission {\n  userPsId: UserPsId;\n  epoch: number;\n  enclaveAddress: Address;\n  /** `iv(16) || ephemPub(65) || ct || mac(32)` to `evidence.publicKey`. */\n  ciphertext: Hex;\n}\n\n/** Confirmation that the enclave sealed a submitted secret. */\nexport interface SealedSecretResponse {\n  sealed: true;\n  /** `sha256(ciphertext)`. */\n  secretHash: Hex;\n  sealedAt: string;\n}\n\n/** AES-GCM fields encoded as base64 strings. */\nexport interface AesGcmBox {\n  /** Base64 initialization vector. */\n  iv: string;\n  /** Base64 ciphertext. */\n  ciphertext: string;\n  /** Base64 authentication tag. */\n  tag: string;\n}\n\n/** Persisted enclave envelope; the Gateway treats it as opaque text. */\nexport interface SealedEnvelope extends AesGcmBox {\n  v: typeof SEALED_ENVELOPE_VERSION;\n  wrappedContentKey: AesGcmBox;\n}\n\n/** Fleet-pinned KMS root and allowed dstack application IDs. */\nexport interface EnclaveTrustAnchors {\n  kmsRootPubkey: Hex;\n  appIds: readonly Hex[];\n}\n\nfunction emptyAnchor(): Readonly<EnclaveTrustAnchors> {\n  return Object.freeze({\n    kmsRootPubkey: EMPTY_HEX,\n    appIds: Object.freeze([] as Hex[]),\n  });\n}\n\n/** Fleet-provisioned trust anchors keyed by Vana chain ID. */\nexport const ENCLAVE_TRUST_ANCHORS: Readonly<\n  Record<number, Readonly<EnclaveTrustAnchors>>\n> = Object.freeze({\n  // filled at fleet provisioning; verify fails closed while empty\n  [VANA_MAINNET_CHAIN_ID]: emptyAnchor(),\n  // filled at fleet provisioning; verify fails closed while empty\n  [MOKSHA_CHAIN_ID]: emptyAnchor(),\n});\n\n/**\n * Derives the deterministic Personal Server ID used by enclave paths.\n *\n * @param chainId - Vana chain ID.\n * @param ownerAddress - Checksummed owner address.\n * @returns The path-compatible keccak256 digest.\n */\nexport function userPsId(chainId: number, ownerAddress: Address): UserPsId {\n  const packed = encodePacked(\n    [\"string\", \"uint256\", \"address\"],\n    [USER_PS_ID_DOMAIN, BigInt(chainId), getAddress(ownerAddress)],\n  );\n\n  return keccak256(packed);\n}\n\nfunction compressPublicKey(publicKey: Hex): Uint8Array {\n  return secp256k1.ProjectivePoint.fromHex(\n    fromHex(publicKey, \"bytes\"),\n  ).toRawBytes(true);\n}\n\nfunction sameKey(a: Hex, b: Hex): boolean {\n  return toHex(compressPublicKey(a)) === toHex(compressPublicKey(b));\n}\n\nfunction assertUncompressedKey(publicKey: Hex): void {\n  const hex = publicKey.slice(2);\n  if (\n    hex.length !== UNCOMPRESSED_PUBLIC_KEY_BYTES * 2 ||\n    !hex.startsWith(UNCOMPRESSED_PUBLIC_KEY_PREFIX) ||\n    !/^[0-9a-fA-F]+$/.test(hex)\n  ) {\n    throw new Error(\"Public key must be a 65-byte uncompressed secp256k1 key\");\n  }\n}\n\n/**\n * Builds keccak256(utf8(purpose || \":\" || lowercase hex(compressed pubkey))).\n *\n * Matches `dstack/guest-agent/src/rpc_service.rs:612-628`.\n */\nexport function appRootPreimage(purpose: string, publicKey: Hex): Hex {\n  const keyHex = toHex(compressPublicKey(publicKey)).slice(2);\n  return keccak256(toBytes(`${purpose}${PREIMAGE_SEPARATOR}${keyHex}`));\n}\n\n/**\n * Hashes the KMS prefix, raw app ID bytes, and compressed app-root public key.\n *\n * Matches `dstack/kms/src/crypto.rs:23-40`; there is no separator between the\n * raw 20-byte app ID and the compressed key.\n */\nexport function kmsIssuedPreimage(appId: Hex, appRootPublicKey: Hex): Hex {\n  const prefix = concat([\n    toBytes(`${KMS_ISSUED_PREFIX}${PREIMAGE_SEPARATOR}`),\n    fromHex(appId, \"bytes\"),\n  ]);\n  const compressed = compressPublicKey(appRootPublicKey);\n\n  return keccak256(concat([prefix, compressed]));\n}\n\nasync function recoverChainKey(\n  hash: Hex,\n  signature: Hex,\n  link: number,\n): Promise<Hex> {\n  try {\n    return (await recoverPublicKey({ hash, signature })).toLowerCase() as Hex;\n  } catch {\n    throw new Error(`Invalid enclave signature chain link ${link}`);\n  }\n}\n\n/**\n * Verifies the enclave wallet binding against fleet-provisioned trust anchors.\n *\n * @param evidence - Identity evidence returned by the enclave agent.\n * @param anchors - Pinned KMS root and allowed dstack app IDs.\n * @param expected - Owner, chain, and epoch requested by the caller.\n *\n * @remarks\n * The dstack chain signs only `purpose || publicKey` and `appId || appRootPub`;\n * owner, chain and epoch are bound to the key by the TDX quote report_data\n * (`keccak256(userPsId || address)`), which v1 stores but does not verify\n * (DCAP is step 4). Until then the agent's derivation check is the backstop.\n * @throws When any identity binding or trust check fails.\n */\nexport async function verifyEnclaveIdentityEvidence(\n  evidence: EnclaveIdentityEvidence,\n  anchors: EnclaveTrustAnchors,\n  expected: ExpectedIdentity,\n): Promise<void> {\n  if (evidence.v !== ENCLAVE_IDENTITY_EVIDENCE_VERSION) {\n    throw new Error(\"Unsupported enclave identity evidence version\");\n  }\n\n  if (!Number.isInteger(evidence.epoch) || evidence.epoch < 1) {\n    throw new Error(\"Invalid enclave identity epoch\");\n  }\n\n  if (evidence.chainId !== expected.chainId) {\n    throw new Error(\n      \"Enclave identity chain ID does not match expected chain ID\",\n    );\n  }\n\n  if (!isAddressEqual(evidence.ownerAddress, expected.ownerAddress)) {\n    throw new Error(\"Enclave identity owner does not match expected owner\");\n  }\n\n  if (evidence.epoch !== expected.epoch) {\n    throw new Error(\"Enclave identity epoch does not match expected epoch\");\n  }\n\n  const expectedUserPsId = userPsId(expected.chainId, expected.ownerAddress);\n  if (evidence.userPsId.toLowerCase() !== expectedUserPsId.toLowerCase()) {\n    throw new Error(\"Enclave userPsId does not match expected identity\");\n  }\n\n  if (evidence.purpose !== ENCLAVE_WALLET_PURPOSE) {\n    throw new Error(\"Unexpected enclave wallet purpose\");\n  }\n\n  if (anchors.kmsRootPubkey === EMPTY_HEX) {\n    throw new Error(\"KMS root trust anchor is not provisioned\");\n  }\n\n  assertUncompressedKey(evidence.publicKey);\n  const derivedAddress = publicKeyToAddress(evidence.publicKey);\n\n  if (getAddress(derivedAddress) !== getAddress(evidence.address)) {\n    throw new Error(\"Enclave public key does not match its address\");\n  }\n\n  const appRootPublicKey = await recoverChainKey(\n    appRootPreimage(evidence.purpose, evidence.publicKey),\n    evidence.signatureChain[0],\n    0,\n  );\n  const kmsRootPublicKey = await recoverChainKey(\n    kmsIssuedPreimage(evidence.appId, appRootPublicKey),\n    evidence.signatureChain[1],\n    1,\n  );\n\n  let matchesAnchor: boolean;\n  try {\n    matchesAnchor = sameKey(kmsRootPublicKey, anchors.kmsRootPubkey);\n  } catch {\n    throw new Error(\"KMS root trust anchor is malformed\");\n  }\n\n  if (!matchesAnchor) {\n    throw new Error(\"KMS root public key does not match the trust anchor\");\n  }\n\n  if (\n    keccak256(kmsRootPublicKey) !== evidence.kmsRootFingerprint.toLowerCase()\n  ) {\n    throw new Error(\"KMS root fingerprint does not match the evidence\");\n  }\n\n  const appId = evidence.appId.toLowerCase();\n  if (\n    !anchors.appIds.some((allowedAppId) => allowedAppId.toLowerCase() === appId)\n  ) {\n    throw new Error(\"Enclave app ID is not trusted\");\n  }\n}\n\n/**\n * Builds the authenticated master-signature plaintext delivered to an enclave.\n *\n * @param evidence - Verified enclave identity evidence.\n * @param masterSignature - EIP-191 signature over the master-key message.\n * @param now - Issuance time in Unix seconds.\n * @returns The authenticated plaintext delivery object.\n * @throws When the signature is malformed or does not belong to the owner.\n */\nexport async function buildMasterSignatureDelivery(\n  evidence: EnclaveIdentityEvidence,\n  masterSignature: Hex,\n  now = Math.floor(Date.now() / 1000),\n): Promise<MasterSignatureDelivery> {\n  // Validate signature length and hex encoding before recovery.\n  deriveMasterKey(masterSignature);\n  const signerAddress = await recoverServerOwner(masterSignature);\n\n  if (!isAddressEqual(signerAddress, evidence.ownerAddress)) {\n    throw new Error(\"Master signature signer does not match evidence owner\");\n  }\n\n  return {\n    v: MASTER_SIGNATURE_DELIVERY_VERSION,\n    userPsId: evidence.userPsId,\n    epoch: evidence.epoch,\n    enclaveAddress: evidence.address,\n    ownerAddress: evidence.ownerAddress,\n    masterSignature,\n    issuedAt: now,\n  };\n}\n\n/**\n * Encrypts a master-signature delivery in the SDK's ECIES wire format.\n *\n * @param delivery - Plaintext delivery object.\n * @param publicKey - Enclave 65-byte uncompressed public key.\n * @param ecies - Platform-specific ECIES provider.\n * @returns The 0x-prefixed serialized ciphertext.\n * @throws When the public key is malformed or belongs to another enclave.\n */\nexport async function encryptMasterSignatureDelivery(\n  delivery: MasterSignatureDelivery,\n  publicKey: Hex,\n  ecies: ECIESProvider,\n): Promise<Hex> {\n  assertUncompressedKey(publicKey);\n\n  if (!isAddressEqual(publicKeyToAddress(publicKey), delivery.enclaveAddress)) {\n    throw new Error(\n      \"Public key does not belong to the delivery's enclave address\",\n    );\n  }\n\n  const plaintext = toBytes(JSON.stringify(delivery));\n  const encrypted = await ecies.encrypt(fromHex(publicKey, \"bytes\"), plaintext);\n\n  return `0x${serializeECIES(encrypted)}`;\n}\n"],"mappings":"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","names":[]}

package/dist/protocol/identity.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/protocol/identity.vector.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/protocol/jobs-client.cjs

@@ -0,0 +1,540 @@
+"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);
+var jobs_client_exports = {};
+__export(jobs_client_exports, {
+  createJobsClient: () => createJobsClient
+});
+module.exports = __toCommonJS(jobs_client_exports);
+var import_node_crypto = require("node:crypto");
+var import_sha2 = require("@noble/hashes/sha2");
+var import_viem = require("viem");
+var import_accounts = require("viem/accounts");
+var import_web3_signed_builder = require("../auth/web3-signed-builder");
+var import_node = require("../crypto/ecies/node");
+var import_job = require("../crypto/envelope/job");
+var import_errors = require("../errors");
+var import_identity = require("./identity");
+var import_jobs = require("./jobs");
+var import_write_signer = require("./write-signer");
+const IDENTITY_PATH = "/v1/identity";
+const JOBS_PATH = "/v1/jobs";
+const JOB_EXECUTE_PATH = "/v1/jobs/execute";
+const AUTHORIZATION_HEADER = "Authorization";
+const CONTENT_TYPE_HEADER = "Content-Type";
+const JSON_CONTENT_TYPE = "application/json";
+const GET_METHOD = "GET";
+const POST_METHOD = "POST";
+const RAW_READ_OPERATION = "raw_read";
+const SEALED_IDENTITY_STATE = "sealed";
+const HTTP_OK = 200;
+const HTTP_ACCEPTED = 202;
+const HTTP_UNAUTHORIZED = 401;
+const HTTP_FORBIDDEN = 403;
+const HTTP_NOT_FOUND = 404;
+const HTTP_CONFLICT = 409;
+const HTTP_PAYLOAD_TOO_LARGE = 413;
+const MILLISECONDS_PER_SECOND = 1e3;
+const DEFAULT_JOB_TIMEOUT_MS = 12e4;
+const DEFAULT_JOB_POLL_MS = import_jobs.CLAIM_POLL_FLOOR_MS;
+const TERMINAL_JOB_STATES = /* @__PURE__ */ new Set([
+  "completed",
+  "failed",
+  "expired",
+  "cancelled"
+]);
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeGateway(gatewayUrl) {
+  try {
+    const url = new URL(gatewayUrl);
+    if (url.pathname !== "/" || url.search !== "" || url.hash !== "") {
+      throw new import_errors.JobRejectedError(
+        "gatewayUrl must be an origin without a path, query, or fragment"
+      );
+    }
+    return {
+      baseUrl: url.origin,
+      audience: url.origin
+    };
+  } catch (error) {
+    if (error instanceof import_errors.JobRejectedError) throw error;
+    throw new import_errors.JobRejectedError(
+      "gatewayUrl must be an absolute URL",
+      void 0,
+      null,
+      {
+        cause: error instanceof Error ? error.message : String(error)
+      }
+    );
+  }
+}
+function resolveFetch(fetchFn) {
+  const resolved = fetchFn ?? globalThis.fetch;
+  if (resolved === void 0) {
+    throw new import_errors.JobRejectedError("No fetch implementation available");
+  }
+  return resolved;
+}
+function sourcePublicKey(source) {
+  if (isRecord(source) && typeof source["publicKey"] === "string") {
+    return source["publicKey"];
+  }
+  return void 0;
+}
+function resolveBuilder(options) {
+  if (options.builderPrivateKey && options.builderAccount) {
+    throw new import_errors.JobRejectedError(
+      "Provide builderPrivateKey or builderAccount, not both"
+    );
+  }
+  let source;
+  try {
+    source = options.builderPrivateKey ? (0, import_accounts.privateKeyToAccount)(options.builderPrivateKey) : options.builderAccount;
+  } catch (error) {
+    throw new import_errors.JobRejectedError("Invalid builder private key", void 0, null, {
+      cause: error instanceof Error ? error.message : String(error)
+    });
+  }
+  if (!source) {
+    throw new import_errors.JobRejectedError(
+      "builderPrivateKey or builderAccount is required"
+    );
+  }
+  let signer;
+  try {
+    signer = (0, import_write_signer.resolveWriteSigner)(source);
+  } catch (error) {
+    throw new import_errors.JobRejectedError("Invalid builder signer", void 0, null, {
+      cause: error instanceof Error ? error.message : String(error)
+    });
+  }
+  const publicKey = sourcePublicKey(source);
+  if (!signer.address || !publicKey) {
+    throw new import_errors.JobRejectedError(
+      "Builder signer must expose both address and publicKey"
+    );
+  }
+  return {
+    builder: {
+      address: signer.address,
+      publicKey,
+      signMessage: signer.signMessage
+    },
+    ...options.builderPrivateKey ? { privateKey: options.builderPrivateKey } : {}
+  };
+}
+function clampInteger(value, fallback, minimum, maximum, field) {
+  const resolved = value ?? fallback;
+  if (!Number.isFinite(resolved)) {
+    throw new import_errors.JobRejectedError(`${field} must be a finite number`);
+  }
+  return Math.min(maximum, Math.max(minimum, Math.trunc(resolved)));
+}
+async function responseBody(response) {
+  try {
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+function gatewayErrorBody(body, fallback) {
+  if (!isRecord(body)) return { code: null, message: fallback };
+  const code = typeof body["code"] === "string" ? body["code"] : null;
+  const message = typeof body["error"] === "string" ? body["error"] : typeof body["message"] === "string" ? body["message"] : fallback;
+  const reason = typeof body["reason"] === "string" ? body["reason"] : void 0;
+  const details = isRecord(body["details"]) ? body["details"] : void 0;
+  return {
+    code,
+    message,
+    ...reason ? { reason } : {},
+    ...details ? { details } : {}
+  };
+}
+async function rejectedResponse(response, fallback) {
+  const parsed = gatewayErrorBody(await responseBody(response), fallback);
+  const details = response.status === HTTP_UNAUTHORIZED && parsed.reason ? { ...parsed.details, reason: parsed.reason } : parsed.details;
+  const message = response.status === HTTP_UNAUTHORIZED && parsed.reason ? `${parsed.message}: ${parsed.reason}` : parsed.message;
+  if (response.status === HTTP_FORBIDDEN) {
+    if (parsed.code === "BUILDER_UNKNOWN") {
+      return new import_errors.BuilderUnknownError(parsed.message, details);
+    }
+    if (parsed.code === "GRANT_INVALID") {
+      return new import_errors.GrantInvalidError(parsed.message, details);
+    }
+    if (parsed.code === "OWNER_NOT_READY") {
+      return new import_errors.OwnerNotReadyError(parsed.message, details);
+    }
+  }
+  if (response.status === HTTP_NOT_FOUND) {
+    return new import_errors.JobNotFoundError(parsed.message, details);
+  }
+  if (response.status === HTTP_CONFLICT && parsed.code === "JOB_ID_TAKEN") {
+    return new import_errors.JobIdTakenError(parsed.message, details);
+  }
+  if (response.status === HTTP_PAYLOAD_TOO_LARGE) {
+    return new import_errors.JobRequestTooLargeError(parsed.message, parsed.code, details);
+  }
+  return new import_errors.JobRejectedError(message, response.status, parsed.code, details);
+}
+function requireStatus(value, status) {
+  if (!isRecord(value) || !isNonEmptyString(value["jobId"]) || typeof value["state"] !== "string" || !import_jobs.JOB_STATES.includes(value["state"]) || !isNonEmptyString(value["owner"]) || !isNonEmptyString(value["grantId"]) || !isNonEmptyString(value["scope"]) || !isNonEmptyString(value["operation"]) || !import_jobs.JOB_OPERATIONS.includes(value["operation"])) {
+    throw new import_errors.JobRejectedError(
+      "Gateway response did not contain a job status",
+      status
+    );
+  }
+  return value;
+}
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.length > 0;
+}
+function hasMatchingIdentityKey(value) {
+  const address = value["address"];
+  const publicKey = value["publicKey"];
+  if (typeof address !== "string" || !(0, import_viem.isAddress)(address) || typeof publicKey !== "string" || !(0, import_viem.isHex)(publicKey)) {
+    return false;
+  }
+  try {
+    return (0, import_accounts.publicKeyToAddress)(publicKey).toLowerCase() === address.toLowerCase();
+  } catch {
+    return false;
+  }
+}
+function hasExpectedIdentity(value, owner, chainId) {
+  const identityOwner = value["ownerAddress"];
+  const identityChainId = value["chainId"];
+  const identityUserPsId = value["userPsId"];
+  if (!hasMatchingIdentityKey(value) || typeof identityOwner !== "string" || !(0, import_viem.isAddress)(identityOwner) || typeof identityChainId !== "number" || typeof identityUserPsId !== "string" || !(0, import_viem.isHex)(identityUserPsId)) {
+    return false;
+  }
+  return (0, import_viem.isAddressEqual)(identityOwner, owner) && identityChainId === chainId && identityUserPsId.toLowerCase() === (0, import_identity.userPsId)(chainId, owner).toLowerCase();
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function requireFiniteDuration(value, field) {
+  if (!Number.isFinite(value)) {
+    throw new import_errors.JobRejectedError(`${field} must be a finite number`);
+  }
+  return Math.max(0, value);
+}
+function createJobsClient(options) {
+  const { baseUrl, audience } = normalizeGateway(options.gatewayUrl);
+  const fetchFn = resolveFetch(options.fetch);
+  const { builder, privateKey } = resolveBuilder(options);
+  const ecies = options.ecies ?? new import_node.NodeECIESUint8Provider();
+  const now = options.now ?? (() => /* @__PURE__ */ new Date());
+  async function request(url, init, description) {
+    try {
+      return await fetchFn(url, init);
+    } catch (error) {
+      throw new import_errors.JobTransportError(
+        `${description} failed: ${error instanceof Error ? error.message : String(error)}`,
+        error
+      );
+    }
+  }
+  async function getIdentity(owner) {
+    const query = new URLSearchParams({
+      owner,
+      chainId: String(options.chainId)
+    });
+    const response = await request(
+      `${baseUrl}${IDENTITY_PATH}?${query.toString()}`,
+      { method: GET_METHOD },
+      "Owner identity lookup"
+    );
+    if (response.status === HTTP_NOT_FOUND) {
+      const parsed = gatewayErrorBody(
+        await responseBody(response),
+        "Owner identity not found"
+      );
+      throw new import_errors.OwnerNotReadyError(parsed.message, parsed.details);
+    }
+    if (!response.ok) {
+      throw await rejectedResponse(response, "Owner identity lookup rejected");
+    }
+    const body = await responseBody(response);
+    if (!isRecord(body) || body["state"] !== SEALED_IDENTITY_STATE || !isRecord(body["identity"])) {
+      throw new import_errors.OwnerNotReadyError("Owner identity is not sealed", {
+        state: isRecord(body) ? body["state"] : void 0
+      });
+    }
+    if (!hasExpectedIdentity(body["identity"], owner, options.chainId)) {
+      throw new import_errors.JobRejectedError(
+        "Gateway returned a malformed or mismatched owner identity",
+        response.status
+      );
+    }
+    return body["identity"];
+  }
+  const client = {
+    async submitRawRead(params) {
+      const identity = await getIdentity(params.owner);
+      const deadlineSeconds = clampInteger(
+        params.deadlineSeconds,
+        import_jobs.DEFAULT_JOB_DEADLINE_SECONDS,
+        1,
+        import_jobs.MAX_JOB_DEADLINE_SECONDS,
+        "deadlineSeconds"
+      );
+      const wait = clampInteger(params.wait, 0, 0, import_jobs.MAX_WAIT_SECONDS, "wait");
+      const jobId = (0, import_node_crypto.randomUUID)();
+      const nowMs = now().getTime();
+      if (!Number.isFinite(nowMs)) {
+        throw new import_errors.JobRejectedError("now must return a valid Date");
+      }
+      const deadline = new Date(
+        nowMs + deadlineSeconds * MILLISECONDS_PER_SECOND
+      ).toISOString();
+      const requestBody = {
+        v: import_jobs.JOB_PROTOCOL_VERSION,
+        jobId,
+        owner: params.owner,
+        builder: builder.address,
+        builderPublicKey: builder.publicKey,
+        grantId: params.grantId,
+        scope: params.scope,
+        operation: RAW_READ_OPERATION,
+        pinnedVersion: params.pinnedVersion ?? null,
+        deadline
+      };
+      const auth = await (0, import_web3_signed_builder.buildWeb3SignedHeader)({
+        signMessage: builder.signMessage,
+        aud: audience,
+        method: POST_METHOD,
+        uri: JOB_EXECUTE_PATH,
+        bodyHash: (0, import_web3_signed_builder.computeBodyHash)((0, import_job.canonicalJobRequestBytes)(requestBody)),
+        nonce: (0, import_node_crypto.randomUUID)()
+      });
+      const requestCiphertext = await (0, import_job.sealJobRequest)(
+        { request: requestBody, auth },
+        identity.publicKey,
+        ecies
+      );
+      const submission = {
+        owner: requestBody.owner,
+        grantId: requestBody.grantId,
+        scope: requestBody.scope,
+        operation: requestBody.operation,
+        idempotencyKey: (0, import_node_crypto.randomUUID)(),
+        jobId,
+        deadline,
+        requestCiphertext
+      };
+      const bodyBytes = new TextEncoder().encode(JSON.stringify(submission));
+      const authorization = await (0, import_web3_signed_builder.buildWeb3SignedHeader)({
+        signMessage: builder.signMessage,
+        aud: audience,
+        method: POST_METHOD,
+        uri: JOBS_PATH,
+        body: bodyBytes,
+        nonce: (0, import_node_crypto.randomUUID)()
+      });
+      const response = await request(
+        `${baseUrl}${JOBS_PATH}?wait=${wait}`,
+        {
+          method: POST_METHOD,
+          headers: {
+            [AUTHORIZATION_HEADER]: authorization,
+            [CONTENT_TYPE_HEADER]: JSON_CONTENT_TYPE
+          },
+          body: bodyBytes
+        },
+        "Job submission"
+      );
+      if (!response.ok) {
+        throw await rejectedResponse(response, "Job submission rejected");
+      }
+      const body = await responseBody(response);
+      if (response.status === HTTP_OK && isRecord(body)) {
+        const job = requireStatus(body["job"], response.status);
+        if (job.jobId !== jobId) {
+          throw new import_errors.JobRejectedError(
+            "Gateway returned a job id that does not match the submission",
+            response.status
+          );
+        }
+        return { jobId, state: job.state, job };
+      }
+      if (response.status === HTTP_ACCEPTED && isRecord(body) && body["jobId"] === jobId && typeof body["state"] === "string" && import_jobs.JOB_STATES.includes(body["state"])) {
+        return { jobId, state: body["state"] };
+      }
+      throw new import_errors.JobRejectedError(
+        "Gateway returned an undocumented job submission response",
+        response.status
+      );
+    },
+    async getJob(jobId) {
+      const path = `${JOBS_PATH}/${encodeURIComponent(jobId)}`;
+      const authorization = await (0, import_web3_signed_builder.buildWeb3SignedHeader)({
+        signMessage: builder.signMessage,
+        aud: audience,
+        method: GET_METHOD,
+        uri: path,
+        nonce: (0, import_node_crypto.randomUUID)()
+      });
+      const response = await request(
+        `${baseUrl}${path}`,
+        {
+          method: GET_METHOD,
+          headers: { [AUTHORIZATION_HEADER]: authorization }
+        },
+        "Job status read"
+      );
+      if (!response.ok) {
+        throw await rejectedResponse(response, "Job status read rejected");
+      }
+      const body = await responseBody(response);
+      return requireStatus(
+        isRecord(body) ? body["job"] : void 0,
+        response.status
+      );
+    },
+    async waitForJob(jobId, waitOptions = {}) {
+      const timeoutMs = requireFiniteDuration(
+        waitOptions.timeoutMs ?? DEFAULT_JOB_TIMEOUT_MS,
+        "timeoutMs"
+      );
+      const pollMs = Math.max(
+        import_jobs.CLAIM_POLL_FLOOR_MS,
+        requireFiniteDuration(
+          waitOptions.pollMs ?? DEFAULT_JOB_POLL_MS,
+          "pollMs"
+        )
+      );
+      const startedAt = Date.now();
+      const callerDeadline = startedAt + timeoutMs;
+      let latest;
+      for (; ; ) {
+        if (Date.now() >= callerDeadline) {
+          throw new import_errors.JobTimeoutError(
+            `Timed out waiting for terminal job ${jobId}`,
+            {
+              jobId,
+              timeoutMs,
+              state: latest?.state
+            }
+          );
+        }
+        latest = await client.getJob(jobId);
+        if (TERMINAL_JOB_STATES.has(latest.state)) return latest;
+        const remaining = callerDeadline - Date.now();
+        if (remaining <= 0) {
+          throw new import_errors.JobTimeoutError(
+            `Timed out waiting for terminal job ${jobId}`,
+            {
+              jobId,
+              timeoutMs,
+              state: latest.state
+            }
+          );
+        }
+        await sleep(Math.min(pollMs, remaining));
+      }
+    },
+    async openResult(handle, openOptions) {
+      if (!privateKey) {
+        throw new import_errors.JobRejectedError(
+          "openResult requires createJobsClient({ builderPrivateKey })"
+        );
+      }
+      const response = await request(
+        handle.url,
+        { method: GET_METHOD },
+        "Job result fetch"
+      );
+      if (!response.ok) {
+        throw await rejectedResponse(response, "Job result fetch rejected");
+      }
+      let bytes;
+      try {
+        bytes = new Uint8Array(await response.arrayBuffer());
+      } catch (error) {
+        throw new import_errors.JobTransportError(
+          `Job result fetch failed: ${error instanceof Error ? error.message : String(error)}`,
+          error
+        );
+      }
+      const actualHash = (0, import_viem.bytesToHex)((0, import_sha2.sha256)(bytes));
+      if (actualHash.toLowerCase() !== handle.hash.toLowerCase()) {
+        throw new import_errors.JobResultIntegrityError(
+          "Fetched job result hash does not match its handle",
+          {
+            objectKey: handle.objectKey,
+            expectedHash: handle.hash,
+            actualHash
+          }
+        );
+      }
+      if (bytes.length !== handle.size) {
+        throw new import_errors.JobResultIntegrityError(
+          "Fetched job result size does not match its handle",
+          {
+            objectKey: handle.objectKey,
+            expectedSize: handle.size,
+            actualSize: bytes.length
+          }
+        );
+      }
+      return (0, import_job.openJobResult)(bytes, privateKey, ecies, openOptions.expect);
+    },
+    async readRaw(params) {
+      const submitted = await client.submitRawRead(params);
+      const job = submitted.job && TERMINAL_JOB_STATES.has(submitted.job.state) ? submitted.job : await client.waitForJob(submitted.jobId, {
+        timeoutMs: params.timeoutMs,
+        pollMs: params.pollMs
+      });
+      if (job.state !== "completed") {
+        throw new import_errors.JobRejectedError(
+          `Job ${job.jobId} ended in state ${job.state}${job.failureReason ? `: ${job.failureReason}` : ""}`,
+          void 0,
+          null,
+          {
+            jobId: job.jobId,
+            state: job.state,
+            ...job.failureReason ? { failureReason: job.failureReason } : {}
+          }
+        );
+      }
+      if (!job.result) {
+        throw new import_errors.JobRejectedError(
+          "Completed job status does not include a result handle",
+          void 0,
+          null,
+          { jobId: job.jobId, state: job.state }
+        );
+      }
+      return client.openResult(job.result, {
+        expect: {
+          jobId: submitted.jobId,
+          scope: params.scope,
+          ...params.pinnedVersion !== void 0 && params.pinnedVersion !== null ? { version: params.pinnedVersion } : {}
+        }
+      });
+    }
+  };
+  return client;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createJobsClient
+});
+//# sourceMappingURL=jobs-client.cjs.map