@opendatalabs/vana-sdk 3.22.0-pr.209.70d3733 → 3.22.0-pr.210.0a5d07b

package/dist/crypto/envelope/job.cjs

@@ -19,6 +19,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var job_exports = {};
 __export(job_exports, {
   JobEnvelopeError: () => JobEnvelopeError,
+  canonicalJobRequestBytes: () => canonicalJobRequestBytes,
   openJobRequest: () => openJobRequest,
   openJobResult: () => openJobResult,
   sealJobRequest: () => sealJobRequest,
@@ -28,6 +29,7 @@ module.exports = __toCommonJS(job_exports);
 var import_sha2 = require("@noble/hashes/sha2");
 var import_viem = require("viem");
 var import_interface = require("../ecies/interface");
+var import_jobs = require("../../protocol/jobs");
 var import_encoding = require("../../utils/encoding");
 const textDecoder = new TextDecoder();
 const textEncoder = new TextEncoder();
@@ -37,25 +39,30 @@ class JobEnvelopeError extends Error {
     this.name = "JobEnvelopeError";
   }
 }
+function sortJsonKeys(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortJsonKeys);
+  }
+  if (value !== null && typeof value === "object") {
+    return Object.fromEntries(
+      Object.keys(value).sort().map((key) => [
+        key,
+        sortJsonKeys(value[key])
+      ])
+    );
+  }
+  return value;
+}
+function canonicalJsonBytes(value) {
+  return textEncoder.encode(JSON.stringify(sortJsonKeys(value)));
+}
+function canonicalJobRequestBytes(request) {
+  validateJobRequest(request);
+  return canonicalJsonBytes(request);
+}
 function requestPlaintext(envelope) {
-  const { request, auth } = envelope;
-  return textEncoder.encode(
-    JSON.stringify({
-      request: {
-        v: request.v,
-        jobId: request.jobId,
-        owner: request.owner,
-        builder: request.builder,
-        builderPublicKey: request.builderPublicKey,
-        grantId: request.grantId,
-        scope: request.scope,
-        operation: request.operation,
-        pinnedVersion: request.pinnedVersion,
-        deadline: request.deadline
-      },
-      auth
-    })
-  );
+  validateRequestEnvelope(envelope);
+  return canonicalJsonBytes(envelope);
 }
 function resultPlaintext(result) {
   return textEncoder.encode(
@@ -87,42 +94,99 @@ function parseObject(plaintext, kind) {
     throw new JobEnvelopeError(`Invalid ${kind}: malformed JSON`);
   }
 }
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object") return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function requirePlainObject(value, field, kind) {
+  if (!isPlainObject(value)) {
+    throw new JobEnvelopeError(`Invalid ${kind}: invalid ${field}`);
+  }
+}
+function requireExactKeys(value, expectedKeys, kind) {
+  for (const key of expectedKeys) {
+    if (!Object.hasOwn(value, key) || value[key] === void 0) {
+      throw new JobEnvelopeError(`Invalid ${kind}: missing ${key}`);
+    }
+  }
+  const expected = new Set(expectedKeys);
+  for (const key of Reflect.ownKeys(value)) {
+    if (!expected.has(key)) {
+      throw new JobEnvelopeError(
+        `Invalid ${kind}: unknown field ${String(key)}`
+      );
+    }
+  }
+}
 function requireString(value, field, kind) {
   if (typeof value !== "string" || value.length === 0) {
     throw new JobEnvelopeError(`Invalid ${kind}: missing ${field}`);
   }
 }
-function validateRequestEnvelope(value) {
-  const request = value.request;
-  if (request === null || typeof request !== "object" || Array.isArray(request)) {
-    throw new JobEnvelopeError("Invalid job request envelope: missing request");
-  }
-  const fields = request;
-  if (fields.v !== 1) {
+function validateJobRequest(value) {
+  requirePlainObject(value, "request", "job request");
+  requireExactKeys(
+    value,
+    [
+      "v",
+      "jobId",
+      "owner",
+      "builder",
+      "builderPublicKey",
+      "grantId",
+      "scope",
+      "operation",
+      "pinnedVersion",
+      "deadline"
+    ],
+    "job request"
+  );
+  if (value.v !== import_jobs.JOB_PROTOCOL_VERSION) {
     throw new JobEnvelopeError(
-      `Unsupported job request version: ${String(fields.v)}`
+      `Unsupported job request version: ${String(value.v)}`
     );
   }
-  for (const field of [
-    "jobId",
-    "owner",
-    "builder",
-    "builderPublicKey",
-    "grantId",
-    "scope",
-    "operation",
-    "deadline"
-  ]) {
-    requireString(fields[field], field, "job request");
-  }
-  if (fields.pinnedVersion !== null && typeof fields.pinnedVersion !== "string") {
+  requireString(value.jobId, "jobId", "job request");
+  if (typeof value.owner !== "string" || !(0, import_viem.isAddress)(value.owner)) {
+    throw new JobEnvelopeError("Invalid job request: invalid owner");
+  }
+  if (typeof value.builder !== "string" || !(0, import_viem.isAddress)(value.builder)) {
+    throw new JobEnvelopeError("Invalid job request: invalid builder");
+  }
+  if (typeof value.builderPublicKey !== "string" || !(0, import_viem.isHex)(value.builderPublicKey)) {
+    throw new JobEnvelopeError("Invalid job request: invalid builderPublicKey");
+  }
+  if (typeof value.grantId !== "string" || !(0, import_viem.isHex)(value.grantId)) {
+    throw new JobEnvelopeError("Invalid job request: invalid grantId");
+  }
+  requireString(value.scope, "scope", "job request");
+  if (!import_jobs.JOB_OPERATIONS.includes(value.operation)) {
+    throw new JobEnvelopeError("Invalid job request: invalid operation");
+  }
+  if (value.pinnedVersion !== null && typeof value.pinnedVersion !== "string") {
     throw new JobEnvelopeError("Invalid job request: missing pinnedVersion");
   }
+  if (typeof value.deadline !== "string" || !Number.isFinite(Date.parse(value.deadline))) {
+    throw new JobEnvelopeError("Invalid job request: invalid deadline");
+  }
+  return value;
+}
+function validateRequestEnvelope(value) {
+  requirePlainObject(value, "envelope", "job request envelope");
+  requireExactKeys(value, ["request", "auth"], "job request envelope");
+  validateJobRequest(value.request);
   requireString(value.auth, "auth", "job request envelope");
   return value;
 }
 function validateResult(value) {
-  if (value.v !== 1) {
+  requirePlainObject(value, "result", "job result");
+  requireExactKeys(
+    value,
+    ["v", "jobId", "scope", "version", "contentType", "body"],
+    "job result"
+  );
+  if (value.v !== import_jobs.JOB_PROTOCOL_VERSION) {
     throw new JobEnvelopeError(
       `Unsupported job result version: ${String(value.v)}`
     );
@@ -138,10 +202,10 @@ function validateResult(value) {
   }
   return value;
 }
-async function sealJobRequest(e, enclavePublicKey, ecies) {
+async function sealJobRequest(envelope, enclavePublicKey, ecies) {
   const encrypted = await ecies.encrypt(
     (0, import_viem.fromHex)(enclavePublicKey, "bytes"),
-    requestPlaintext(e)
+    requestPlaintext(envelope)
   );
   return encryptedBytesToBase64(encrypted);
 }
@@ -154,10 +218,11 @@ async function openJobRequest(ciphertext, privateKey, ecies) {
     parseObject(plaintext, "job request envelope")
   );
 }
-async function sealJobResult(r, builderPublicKey, ecies) {
+async function sealJobResult(result, builderPublicKey, ecies) {
+  validateResult(result);
   const encrypted = await ecies.encrypt(
     (0, import_viem.fromHex)(builderPublicKey, "bytes"),
-    resultPlaintext(r)
+    resultPlaintext(result)
   );
   const ciphertext = encryptedBytesToBase64(encrypted);
   const bytes = (0, import_encoding.fromBase64)(ciphertext);
@@ -189,6 +254,7 @@ async function openJobResult(ciphertext, builderPrivateKey, ecies, expect) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   JobEnvelopeError,
+  canonicalJobRequestBytes,
   openJobRequest,
   openJobResult,
   sealJobRequest,

package/dist/crypto/envelope/job.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/crypto/envelope/job.ts"],"sourcesContent":["/**\n * ECIES envelopes for encrypted job requests and results.\n *\n * Plaintext is the UTF-8 encoding of `JSON.stringify(value)`, with properties\n * emitted in the order declared by the corresponding interface. The wire\n * ciphertext is base64 of `iv || ephemPub || ct || mac`, as specified by the\n * ECIES provider interface. This ordering is canonical enough for a plaintext\n * hash, although the Gateway hashes the raw ciphertext bytes, not plaintext.\n * Per the jobs flow in contract section 1, the builder verifies the decrypted\n * result's job ID, scope, and version bindings.\n *\n * @category Cryptography\n */\n\nimport { sha256 } from \"@noble/hashes/sha2\";\nimport { bytesToHex, fromHex, toHex, type Hex } from \"viem\";\nimport {\n  deserializeECIES,\n  serializeECIES,\n  type ECIESProvider,\n} from \"../ecies/interface\";\nimport type { JobRequestEnvelope, JobResult } from \"../../protocol/jobs\";\nimport { fromBase64, toBase64 } from \"../../utils/encoding\";\n\nconst textDecoder = new TextDecoder();\nconst textEncoder = new TextEncoder();\n\n/** A decrypted job envelope did not match the jobs protocol. */\nexport class JobEnvelopeError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"JobEnvelopeError\";\n  }\n}\n\nfunction requestPlaintext(envelope: JobRequestEnvelope): Uint8Array {\n  const { request, auth } = envelope;\n  return textEncoder.encode(\n    JSON.stringify({\n      request: {\n        v: request.v,\n        jobId: request.jobId,\n        owner: request.owner,\n        builder: request.builder,\n        builderPublicKey: request.builderPublicKey,\n        grantId: request.grantId,\n        scope: request.scope,\n        operation: request.operation,\n        pinnedVersion: request.pinnedVersion,\n        deadline: request.deadline,\n      },\n      auth,\n    }),\n  );\n}\n\nfunction resultPlaintext(result: JobResult): Uint8Array {\n  return textEncoder.encode(\n    JSON.stringify({\n      v: result.v,\n      jobId: result.jobId,\n      scope: result.scope,\n      version: result.version,\n      contentType: result.contentType,\n      body: result.body,\n    }),\n  );\n}\n\nfunction encryptedBytesToBase64(\n  encrypted: Awaited<ReturnType<ECIESProvider[\"encrypt\"]>>,\n): string {\n  return toBase64(fromHex(`0x${serializeECIES(encrypted)}`, \"bytes\"));\n}\n\nfunction base64ToEncrypted(ciphertext: string) {\n  return deserializeECIES(toHex(fromBase64(ciphertext)));\n}\n\nfunction parseObject(\n  plaintext: Uint8Array,\n  kind: string,\n): Record<string, unknown> {\n  try {\n    const value: unknown = JSON.parse(textDecoder.decode(plaintext));\n    if (value === null || typeof value !== \"object\" || Array.isArray(value)) {\n      throw new JobEnvelopeError(`Invalid ${kind}: expected an object`);\n    }\n    return value as Record<string, unknown>;\n  } catch (error) {\n    if (error instanceof JobEnvelopeError) throw error;\n    throw new JobEnvelopeError(`Invalid ${kind}: malformed JSON`);\n  }\n}\n\nfunction requireString(\n  value: unknown,\n  field: string,\n  kind: string,\n): asserts value is string {\n  if (typeof value !== \"string\" || value.length === 0) {\n    throw new JobEnvelopeError(`Invalid ${kind}: missing ${field}`);\n  }\n}\n\nfunction validateRequestEnvelope(\n  value: Record<string, unknown>,\n): JobRequestEnvelope {\n  const request = value.request;\n  if (\n    request === null ||\n    typeof request !== \"object\" ||\n    Array.isArray(request)\n  ) {\n    throw new JobEnvelopeError(\"Invalid job request envelope: missing request\");\n  }\n  const fields = request as Record<string, unknown>;\n  if (fields.v !== 1) {\n    throw new JobEnvelopeError(\n      `Unsupported job request version: ${String(fields.v)}`,\n    );\n  }\n  for (const field of [\n    \"jobId\",\n    \"owner\",\n    \"builder\",\n    \"builderPublicKey\",\n    \"grantId\",\n    \"scope\",\n    \"operation\",\n    \"deadline\",\n  ]) {\n    requireString(fields[field], field, \"job request\");\n  }\n  if (\n    fields.pinnedVersion !== null &&\n    typeof fields.pinnedVersion !== \"string\"\n  ) {\n    throw new JobEnvelopeError(\"Invalid job request: missing pinnedVersion\");\n  }\n  requireString(value.auth, \"auth\", \"job request envelope\");\n  return value as unknown as JobRequestEnvelope;\n}\n\nfunction validateResult(value: Record<string, unknown>): JobResult {\n  if (value.v !== 1) {\n    throw new JobEnvelopeError(\n      `Unsupported job result version: ${String(value.v)}`,\n    );\n  }\n  for (const field of [\"jobId\", \"scope\", \"contentType\"]) {\n    requireString(value[field], field, \"job result\");\n  }\n  if (typeof value.body !== \"string\") {\n    throw new JobEnvelopeError(\"Invalid job result: missing body\");\n  }\n  if (value.version !== null && typeof value.version !== \"string\") {\n    throw new JobEnvelopeError(\"Invalid job result: missing version\");\n  }\n  return value as unknown as JobResult;\n}\n\nexport async function sealJobRequest(\n  e: JobRequestEnvelope,\n  enclavePublicKey: Hex,\n  ecies: ECIESProvider,\n): Promise<string> {\n  const encrypted = await ecies.encrypt(\n    fromHex(enclavePublicKey, \"bytes\"),\n    requestPlaintext(e),\n  );\n  return encryptedBytesToBase64(encrypted);\n}\n\nexport async function openJobRequest(\n  ciphertext: string,\n  privateKey: Uint8Array,\n  ecies: ECIESProvider,\n): Promise<JobRequestEnvelope> {\n  const plaintext = await ecies.decrypt(\n    privateKey,\n    base64ToEncrypted(ciphertext),\n  );\n  return validateRequestEnvelope(\n    parseObject(plaintext, \"job request envelope\"),\n  );\n}\n\nexport async function sealJobResult(\n  r: JobResult,\n  builderPublicKey: Hex,\n  ecies: ECIESProvider,\n): Promise<{ ciphertext: string; hash: Hex; size: number }> {\n  const encrypted = await ecies.encrypt(\n    fromHex(builderPublicKey, \"bytes\"),\n    resultPlaintext(r),\n  );\n  const ciphertext = encryptedBytesToBase64(encrypted);\n  const bytes = fromBase64(ciphertext);\n  return { ciphertext, hash: bytesToHex(sha256(bytes)), size: bytes.length };\n}\n\nexport async function openJobResult(\n  ciphertext: string,\n  builderPrivateKey: Hex,\n  ecies: ECIESProvider,\n  expect: { jobId: string; scope?: string; version?: string | null },\n): Promise<JobResult> {\n  const plaintext = await ecies.decrypt(\n    fromHex(builderPrivateKey, \"bytes\"),\n    base64ToEncrypted(ciphertext),\n  );\n  const result = validateResult(parseObject(plaintext, \"job result\"));\n  if (result.jobId !== expect.jobId) {\n    throw new JobEnvelopeError(\n      `Job result ID ${result.jobId} does not match expected job ID ${expect.jobId}`,\n    );\n  }\n  if (expect.scope !== undefined && result.scope !== expect.scope) {\n    throw new JobEnvelopeError(\n      `Job result scope ${result.scope} does not match expected scope ${expect.scope}`,\n    );\n  }\n  if (expect.version !== undefined && result.version !== expect.version) {\n    throw new JobEnvelopeError(\n      `Job result version ${String(result.version)} does not match expected version ${String(expect.version)}`,\n    );\n  }\n  return result;\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../../src/crypto/envelope/job.ts"],"sourcesContent":["/**\n * ECIES envelopes for encrypted job requests and results.\n *\n * Request plaintext is UTF-8 JSON with object keys sorted recursively and\n * array order preserved. Result properties follow their interface order. The\n * wire ciphertext is base64 of `iv || ephemPub || ct || mac`, as specified by\n * the ECIES provider interface. The Gateway hashes raw ciphertext bytes, not\n * plaintext.\n * The builder verifies the decrypted result's job ID, scope, and version\n * bindings. The PS worker verifies\n * `auth.bodyHash === sha256(canonicalJobRequestBytes(request))`; the Gateway\n * never sees the plaintext. Flow: personal-server-ts\n * `docs/260903-jobs-contract.md`, section 1.\n *\n * @category Cryptography\n */\n\nimport { sha256 } from \"@noble/hashes/sha2\";\nimport { bytesToHex, fromHex, isAddress, isHex, toHex, type Hex } from \"viem\";\nimport {\n  deserializeECIES,\n  serializeECIES,\n  type ECIESProvider,\n} from \"../ecies/interface\";\nimport {\n  JOB_OPERATIONS,\n  JOB_PROTOCOL_VERSION,\n  type JobOperation,\n  type JobRequest,\n  type JobRequestEnvelope,\n  type JobResult,\n} from \"../../protocol/jobs\";\nimport { fromBase64, toBase64 } from \"../../utils/encoding\";\n\nconst textDecoder = new TextDecoder();\nconst textEncoder = new TextEncoder();\n\n/** A job envelope or result did not match the jobs protocol. */\nexport class JobEnvelopeError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"JobEnvelopeError\";\n  }\n}\n\nfunction sortJsonKeys(value: unknown): unknown {\n  if (Array.isArray(value)) {\n    return value.map(sortJsonKeys);\n  }\n  if (value !== null && typeof value === \"object\") {\n    return Object.fromEntries(\n      Object.keys(value)\n        .sort()\n        .map((key) => [\n          key,\n          sortJsonKeys((value as Record<string, unknown>)[key]),\n        ]),\n    );\n  }\n  return value;\n}\n\nfunction canonicalJsonBytes(value: unknown): Uint8Array {\n  return textEncoder.encode(JSON.stringify(sortJsonKeys(value)));\n}\n\n/**\n * Returns the canonical UTF-8 JSON bytes committed to by the auth body hash.\n *\n * @param request - Job request to validate and serialize canonically.\n * @returns Recursively key-sorted, whitespace-free UTF-8 JSON bytes.\n * @throws {JobEnvelopeError} If the request does not match the protocol schema.\n */\nexport function canonicalJobRequestBytes(request: JobRequest): Uint8Array {\n  validateJobRequest(request);\n  return canonicalJsonBytes(request);\n}\n\nfunction requestPlaintext(envelope: JobRequestEnvelope): Uint8Array {\n  validateRequestEnvelope(envelope);\n  return canonicalJsonBytes(envelope);\n}\n\nfunction resultPlaintext(result: JobResult): Uint8Array {\n  return textEncoder.encode(\n    JSON.stringify({\n      v: result.v,\n      jobId: result.jobId,\n      scope: result.scope,\n      version: result.version,\n      contentType: result.contentType,\n      body: result.body,\n    }),\n  );\n}\n\nfunction encryptedBytesToBase64(\n  encrypted: Awaited<ReturnType<ECIESProvider[\"encrypt\"]>>,\n): string {\n  return toBase64(fromHex(`0x${serializeECIES(encrypted)}`, \"bytes\"));\n}\n\nfunction base64ToEncrypted(ciphertext: string) {\n  return deserializeECIES(toHex(fromBase64(ciphertext)));\n}\n\nfunction parseObject(\n  plaintext: Uint8Array,\n  kind: string,\n): Record<string, unknown> {\n  try {\n    const value: unknown = JSON.parse(textDecoder.decode(plaintext));\n    if (value === null || typeof value !== \"object\" || Array.isArray(value)) {\n      throw new JobEnvelopeError(`Invalid ${kind}: expected an object`);\n    }\n    return value as Record<string, unknown>;\n  } catch (error) {\n    if (error instanceof JobEnvelopeError) throw error;\n    throw new JobEnvelopeError(`Invalid ${kind}: malformed JSON`);\n  }\n}\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  if (value === null || typeof value !== \"object\") return false;\n  const prototype = Object.getPrototypeOf(value);\n  return prototype === Object.prototype || prototype === null;\n}\n\nfunction requirePlainObject(\n  value: unknown,\n  field: string,\n  kind: string,\n): asserts value is Record<string, unknown> {\n  if (!isPlainObject(value)) {\n    throw new JobEnvelopeError(`Invalid ${kind}: invalid ${field}`);\n  }\n}\n\nfunction requireExactKeys(\n  value: Record<string, unknown>,\n  expectedKeys: readonly string[],\n  kind: string,\n): void {\n  for (const key of expectedKeys) {\n    if (!Object.hasOwn(value, key) || value[key] === undefined) {\n      throw new JobEnvelopeError(`Invalid ${kind}: missing ${key}`);\n    }\n  }\n  const expected = new Set<PropertyKey>(expectedKeys);\n  for (const key of Reflect.ownKeys(value)) {\n    if (!expected.has(key)) {\n      throw new JobEnvelopeError(\n        `Invalid ${kind}: unknown field ${String(key)}`,\n      );\n    }\n  }\n}\n\nfunction requireString(\n  value: unknown,\n  field: string,\n  kind: string,\n): asserts value is string {\n  if (typeof value !== \"string\" || value.length === 0) {\n    throw new JobEnvelopeError(`Invalid ${kind}: missing ${field}`);\n  }\n}\n\nfunction validateJobRequest(value: unknown): JobRequest {\n  requirePlainObject(value, \"request\", \"job request\");\n  requireExactKeys(\n    value,\n    [\n      \"v\",\n      \"jobId\",\n      \"owner\",\n      \"builder\",\n      \"builderPublicKey\",\n      \"grantId\",\n      \"scope\",\n      \"operation\",\n      \"pinnedVersion\",\n      \"deadline\",\n    ],\n    \"job request\",\n  );\n  if (value.v !== JOB_PROTOCOL_VERSION) {\n    throw new JobEnvelopeError(\n      `Unsupported job request version: ${String(value.v)}`,\n    );\n  }\n  requireString(value.jobId, \"jobId\", \"job request\");\n  if (typeof value.owner !== \"string\" || !isAddress(value.owner)) {\n    throw new JobEnvelopeError(\"Invalid job request: invalid owner\");\n  }\n  if (typeof value.builder !== \"string\" || !isAddress(value.builder)) {\n    throw new JobEnvelopeError(\"Invalid job request: invalid builder\");\n  }\n  if (\n    typeof value.builderPublicKey !== \"string\" ||\n    !isHex(value.builderPublicKey)\n  ) {\n    throw new JobEnvelopeError(\"Invalid job request: invalid builderPublicKey\");\n  }\n  if (typeof value.grantId !== \"string\" || !isHex(value.grantId)) {\n    throw new JobEnvelopeError(\"Invalid job request: invalid grantId\");\n  }\n  requireString(value.scope, \"scope\", \"job request\");\n  if (!JOB_OPERATIONS.includes(value.operation as JobOperation)) {\n    throw new JobEnvelopeError(\"Invalid job request: invalid operation\");\n  }\n  if (value.pinnedVersion !== null && typeof value.pinnedVersion !== \"string\") {\n    throw new JobEnvelopeError(\"Invalid job request: missing pinnedVersion\");\n  }\n  if (\n    typeof value.deadline !== \"string\" ||\n    !Number.isFinite(Date.parse(value.deadline))\n  ) {\n    throw new JobEnvelopeError(\"Invalid job request: invalid deadline\");\n  }\n  return value as unknown as JobRequest;\n}\n\nfunction validateRequestEnvelope(value: unknown): JobRequestEnvelope {\n  requirePlainObject(value, \"envelope\", \"job request envelope\");\n  requireExactKeys(value, [\"request\", \"auth\"], \"job request envelope\");\n  validateJobRequest(value.request);\n  requireString(value.auth, \"auth\", \"job request envelope\");\n  return value as unknown as JobRequestEnvelope;\n}\n\nfunction validateResult(value: unknown): JobResult {\n  requirePlainObject(value, \"result\", \"job result\");\n  requireExactKeys(\n    value,\n    [\"v\", \"jobId\", \"scope\", \"version\", \"contentType\", \"body\"],\n    \"job result\",\n  );\n  if (value.v !== JOB_PROTOCOL_VERSION) {\n    throw new JobEnvelopeError(\n      `Unsupported job result version: ${String(value.v)}`,\n    );\n  }\n  for (const field of [\"jobId\", \"scope\", \"contentType\"]) {\n    requireString(value[field], field, \"job result\");\n  }\n  if (typeof value.body !== \"string\") {\n    throw new JobEnvelopeError(\"Invalid job result: missing body\");\n  }\n  if (value.version !== null && typeof value.version !== \"string\") {\n    throw new JobEnvelopeError(\"Invalid job result: missing version\");\n  }\n  return value as unknown as JobResult;\n}\n\n/**\n * Encrypts a validated job request envelope for a Personal Server enclave.\n *\n * The PS worker verifies\n * `auth.bodyHash === sha256(canonicalJobRequestBytes(request))`; the Gateway\n * never sees the plaintext.\n *\n * @param envelope - Request and builder Web3Signed authorization to encrypt.\n * @param enclavePublicKey - Public key returned by `GET /v1/identity?owner=`.\n * @param ecies - Injected ECIES implementation.\n * @returns Base64 ciphertext encoded as `iv || ephemPub || ct || mac`.\n * @throws {JobEnvelopeError} If the envelope or request is invalid.\n * @throws If ECIES encryption fails or the enclave public key is invalid.\n *\n * @example\n * ```ts\n * const identity = await fetch(`/v1/identity?owner=${owner}`).then((response) =>\n *   response.json(),\n * );\n * const requestCiphertext = await sealJobRequest(\n *   requestEnvelope,\n *   identity.publicKey,\n *   ecies,\n * );\n * await fetch(\"/v1/jobs\", {\n *   method: \"POST\",\n *   body: JSON.stringify({ ...submission, requestCiphertext }),\n * });\n * ```\n */\nexport async function sealJobRequest(\n  envelope: JobRequestEnvelope,\n  enclavePublicKey: Hex,\n  ecies: ECIESProvider,\n): Promise<string> {\n  const encrypted = await ecies.encrypt(\n    fromHex(enclavePublicKey, \"bytes\"),\n    requestPlaintext(envelope),\n  );\n  return encryptedBytesToBase64(encrypted);\n}\n\n/**\n * Decrypts and validates a job request envelope inside the enclave.\n *\n * @param ciphertext - Base64 `iv || ephemPub || ct || mac` ciphertext.\n * @param privateKey - Enclave key bytes, supplied as `Uint8Array` so the agent can zero them after use.\n * @param ecies - Injected ECIES implementation.\n * @returns The validated request envelope exactly as parsed from plaintext.\n * @throws {JobEnvelopeError} If plaintext is malformed or fails schema validation.\n * @throws If ciphertext decoding or ECIES decryption fails.\n */\nexport async function openJobRequest(\n  ciphertext: string,\n  privateKey: Uint8Array,\n  ecies: ECIESProvider,\n): Promise<JobRequestEnvelope> {\n  const plaintext = await ecies.decrypt(\n    privateKey,\n    base64ToEncrypted(ciphertext),\n  );\n  return validateRequestEnvelope(\n    parseObject(plaintext, \"job request envelope\"),\n  );\n}\n\n/**\n * Encrypts a validated job result for its builder and describes the ciphertext.\n *\n * `hash` is lowercase `0x` SHA-256 of decoded ciphertext bytes, not the\n * `sha256:` prefix used by Web3Signed `bodyHash`. `size` is that decoded byte\n * length. They equal the Gateway's `resultHash` and `resultSize`.\n *\n * @param result - Job result to validate and encrypt.\n * @param builderPublicKey - Builder wallet public key recorded in the request.\n * @param ecies - Injected ECIES implementation.\n * @returns Base64 ciphertext plus its Gateway-compatible hash and size.\n * @throws {JobEnvelopeError} If the result does not match the protocol schema.\n * @throws If ECIES encryption fails or the builder public key is invalid.\n */\nexport async function sealJobResult(\n  result: JobResult,\n  builderPublicKey: Hex,\n  ecies: ECIESProvider,\n): Promise<{ ciphertext: string; hash: Hex; size: number }> {\n  validateResult(result);\n  const encrypted = await ecies.encrypt(\n    fromHex(builderPublicKey, \"bytes\"),\n    resultPlaintext(result),\n  );\n  const ciphertext = encryptedBytesToBase64(encrypted);\n  const bytes = fromBase64(ciphertext);\n  return { ciphertext, hash: bytesToHex(sha256(bytes)), size: bytes.length };\n}\n\n/**\n * Decrypts a job result and verifies its builder-visible protocol bindings.\n *\n * The builder private key is a `Hex` wallet key. For `expect.version`,\n * `undefined` skips the check while `null` requires a null result version.\n *\n * @param ciphertext - Base64 `iv || ephemPub || ct || mac` ciphertext.\n * @param builderPrivateKey - Builder's wallet private key as hex.\n * @param ecies - Injected ECIES implementation.\n * @param expect - Required job ID and optional scope and version bindings.\n * @returns The validated result when every supplied binding matches.\n * @throws {JobEnvelopeError} If plaintext is malformed, invalid, or a binding differs.\n * @throws If ciphertext decoding or ECIES decryption fails.\n *\n * @example\n * ```ts\n * const result = await openJobResult(\n *   status.resultCiphertext,\n *   key,\n *   ecies,\n *   { jobId, scope },\n * );\n * const body = fromBase64(result.body);\n * ```\n */\nexport async function openJobResult(\n  ciphertext: string,\n  builderPrivateKey: Hex,\n  ecies: ECIESProvider,\n  expect: { jobId: string; scope?: string; version?: string | null },\n): Promise<JobResult> {\n  const plaintext = await ecies.decrypt(\n    fromHex(builderPrivateKey, \"bytes\"),\n    base64ToEncrypted(ciphertext),\n  );\n  const result = validateResult(parseObject(plaintext, \"job result\"));\n  if (result.jobId !== expect.jobId) {\n    throw new JobEnvelopeError(\n      `Job result ID ${result.jobId} does not match expected job ID ${expect.jobId}`,\n    );\n  }\n  if (expect.scope !== undefined && result.scope !== expect.scope) {\n    throw new JobEnvelopeError(\n      `Job result scope ${result.scope} does not match expected scope ${expect.scope}`,\n    );\n  }\n  if (expect.version !== undefined && result.version !== expect.version) {\n    throw new JobEnvelopeError(\n      `Job result version ${String(result.version)} does not match expected version ${String(expect.version)}`,\n    );\n  }\n  return result;\n}\n"],"mappings":"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","names":[]}

package/dist/crypto/envelope/job.d.ts

@@ -1,30 +1,120 @@
 /**
  * ECIES envelopes for encrypted job requests and results.
  *
- * Plaintext is the UTF-8 encoding of `JSON.stringify(value)`, with properties
- * emitted in the order declared by the corresponding interface. The wire
- * ciphertext is base64 of `iv || ephemPub || ct || mac`, as specified by the
- * ECIES provider interface. This ordering is canonical enough for a plaintext
- * hash, although the Gateway hashes the raw ciphertext bytes, not plaintext.
- * Per the jobs flow in contract section 1, the builder verifies the decrypted
- * result's job ID, scope, and version bindings.
+ * Request plaintext is UTF-8 JSON with object keys sorted recursively and
+ * array order preserved. Result properties follow their interface order. The
+ * wire ciphertext is base64 of `iv || ephemPub || ct || mac`, as specified by
+ * the ECIES provider interface. The Gateway hashes raw ciphertext bytes, not
+ * plaintext.
+ * The builder verifies the decrypted result's job ID, scope, and version
+ * bindings. The PS worker verifies
+ * `auth.bodyHash === sha256(canonicalJobRequestBytes(request))`; the Gateway
+ * never sees the plaintext. Flow: personal-server-ts
+ * `docs/260903-jobs-contract.md`, section 1.
  *
  * @category Cryptography
  */
 import { type Hex } from "viem";
 import { type ECIESProvider } from "../ecies/interface.js";
-import type { JobRequestEnvelope, JobResult } from "../../protocol/jobs.js";
-/** A decrypted job envelope did not match the jobs protocol. */
+import { type JobRequest, type JobRequestEnvelope, type JobResult } from "../../protocol/jobs.js";
+/** A job envelope or result did not match the jobs protocol. */
 export declare class JobEnvelopeError extends Error {
     constructor(message: string);
 }
-export declare function sealJobRequest(e: JobRequestEnvelope, enclavePublicKey: Hex, ecies: ECIESProvider): Promise<string>;
+/**
+ * Returns the canonical UTF-8 JSON bytes committed to by the auth body hash.
+ *
+ * @param request - Job request to validate and serialize canonically.
+ * @returns Recursively key-sorted, whitespace-free UTF-8 JSON bytes.
+ * @throws {JobEnvelopeError} If the request does not match the protocol schema.
+ */
+export declare function canonicalJobRequestBytes(request: JobRequest): Uint8Array;
+/**
+ * Encrypts a validated job request envelope for a Personal Server enclave.
+ *
+ * The PS worker verifies
+ * `auth.bodyHash === sha256(canonicalJobRequestBytes(request))`; the Gateway
+ * never sees the plaintext.
+ *
+ * @param envelope - Request and builder Web3Signed authorization to encrypt.
+ * @param enclavePublicKey - Public key returned by `GET /v1/identity?owner=`.
+ * @param ecies - Injected ECIES implementation.
+ * @returns Base64 ciphertext encoded as `iv || ephemPub || ct || mac`.
+ * @throws {JobEnvelopeError} If the envelope or request is invalid.
+ * @throws If ECIES encryption fails or the enclave public key is invalid.
+ *
+ * @example
+ * ```ts
+ * const identity = await fetch(`/v1/identity?owner=${owner}`).then((response) =>
+ *   response.json(),
+ * );
+ * const requestCiphertext = await sealJobRequest(
+ *   requestEnvelope,
+ *   identity.publicKey,
+ *   ecies,
+ * );
+ * await fetch("/v1/jobs", {
+ *   method: "POST",
+ *   body: JSON.stringify({ ...submission, requestCiphertext }),
+ * });
+ * ```
+ */
+export declare function sealJobRequest(envelope: JobRequestEnvelope, enclavePublicKey: Hex, ecies: ECIESProvider): Promise<string>;
+/**
+ * Decrypts and validates a job request envelope inside the enclave.
+ *
+ * @param ciphertext - Base64 `iv || ephemPub || ct || mac` ciphertext.
+ * @param privateKey - Enclave key bytes, supplied as `Uint8Array` so the agent can zero them after use.
+ * @param ecies - Injected ECIES implementation.
+ * @returns The validated request envelope exactly as parsed from plaintext.
+ * @throws {JobEnvelopeError} If plaintext is malformed or fails schema validation.
+ * @throws If ciphertext decoding or ECIES decryption fails.
+ */
 export declare function openJobRequest(ciphertext: string, privateKey: Uint8Array, ecies: ECIESProvider): Promise<JobRequestEnvelope>;
-export declare function sealJobResult(r: JobResult, builderPublicKey: Hex, ecies: ECIESProvider): Promise<{
+/**
+ * Encrypts a validated job result for its builder and describes the ciphertext.
+ *
+ * `hash` is lowercase `0x` SHA-256 of decoded ciphertext bytes, not the
+ * `sha256:` prefix used by Web3Signed `bodyHash`. `size` is that decoded byte
+ * length. They equal the Gateway's `resultHash` and `resultSize`.
+ *
+ * @param result - Job result to validate and encrypt.
+ * @param builderPublicKey - Builder wallet public key recorded in the request.
+ * @param ecies - Injected ECIES implementation.
+ * @returns Base64 ciphertext plus its Gateway-compatible hash and size.
+ * @throws {JobEnvelopeError} If the result does not match the protocol schema.
+ * @throws If ECIES encryption fails or the builder public key is invalid.
+ */
+export declare function sealJobResult(result: JobResult, builderPublicKey: Hex, ecies: ECIESProvider): Promise<{
     ciphertext: string;
     hash: Hex;
     size: number;
 }>;
+/**
+ * Decrypts a job result and verifies its builder-visible protocol bindings.
+ *
+ * The builder private key is a `Hex` wallet key. For `expect.version`,
+ * `undefined` skips the check while `null` requires a null result version.
+ *
+ * @param ciphertext - Base64 `iv || ephemPub || ct || mac` ciphertext.
+ * @param builderPrivateKey - Builder's wallet private key as hex.
+ * @param ecies - Injected ECIES implementation.
+ * @param expect - Required job ID and optional scope and version bindings.
+ * @returns The validated result when every supplied binding matches.
+ * @throws {JobEnvelopeError} If plaintext is malformed, invalid, or a binding differs.
+ * @throws If ciphertext decoding or ECIES decryption fails.
+ *
+ * @example
+ * ```ts
+ * const result = await openJobResult(
+ *   status.resultCiphertext,
+ *   key,
+ *   ecies,
+ *   { jobId, scope },
+ * );
+ * const body = fromBase64(result.body);
+ * ```
+ */
 export declare function openJobResult(ciphertext: string, builderPrivateKey: Hex, ecies: ECIESProvider, expect: {
     jobId: string;
     scope?: string;

package/dist/crypto/envelope/job.js

@@ -1,9 +1,13 @@
 import { sha256 } from "@noble/hashes/sha2";
-import { bytesToHex, fromHex, toHex } from "viem";
+import { bytesToHex, fromHex, isAddress, isHex, toHex } from "viem";
 import {
   deserializeECIES,
   serializeECIES
 } from "../ecies/interface.js";
+import {
+  JOB_OPERATIONS,
+  JOB_PROTOCOL_VERSION
+} from "../../protocol/jobs.js";
 import { fromBase64, toBase64 } from "../../utils/encoding.js";
 const textDecoder = new TextDecoder();
 const textEncoder = new TextEncoder();
@@ -13,25 +17,30 @@ class JobEnvelopeError extends Error {
     this.name = "JobEnvelopeError";
   }
 }
+function sortJsonKeys(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortJsonKeys);
+  }
+  if (value !== null && typeof value === "object") {
+    return Object.fromEntries(
+      Object.keys(value).sort().map((key) => [
+        key,
+        sortJsonKeys(value[key])
+      ])
+    );
+  }
+  return value;
+}
+function canonicalJsonBytes(value) {
+  return textEncoder.encode(JSON.stringify(sortJsonKeys(value)));
+}
+function canonicalJobRequestBytes(request) {
+  validateJobRequest(request);
+  return canonicalJsonBytes(request);
+}
 function requestPlaintext(envelope) {
-  const { request, auth } = envelope;
-  return textEncoder.encode(
-    JSON.stringify({
-      request: {
-        v: request.v,
-        jobId: request.jobId,
-        owner: request.owner,
-        builder: request.builder,
-        builderPublicKey: request.builderPublicKey,
-        grantId: request.grantId,
-        scope: request.scope,
-        operation: request.operation,
-        pinnedVersion: request.pinnedVersion,
-        deadline: request.deadline
-      },
-      auth
-    })
-  );
+  validateRequestEnvelope(envelope);
+  return canonicalJsonBytes(envelope);
 }
 function resultPlaintext(result) {
   return textEncoder.encode(
@@ -63,42 +72,99 @@ function parseObject(plaintext, kind) {
     throw new JobEnvelopeError(`Invalid ${kind}: malformed JSON`);
   }
 }
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object") return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function requirePlainObject(value, field, kind) {
+  if (!isPlainObject(value)) {
+    throw new JobEnvelopeError(`Invalid ${kind}: invalid ${field}`);
+  }
+}
+function requireExactKeys(value, expectedKeys, kind) {
+  for (const key of expectedKeys) {
+    if (!Object.hasOwn(value, key) || value[key] === void 0) {
+      throw new JobEnvelopeError(`Invalid ${kind}: missing ${key}`);
+    }
+  }
+  const expected = new Set(expectedKeys);
+  for (const key of Reflect.ownKeys(value)) {
+    if (!expected.has(key)) {
+      throw new JobEnvelopeError(
+        `Invalid ${kind}: unknown field ${String(key)}`
+      );
+    }
+  }
+}
 function requireString(value, field, kind) {
   if (typeof value !== "string" || value.length === 0) {
     throw new JobEnvelopeError(`Invalid ${kind}: missing ${field}`);
   }
 }
-function validateRequestEnvelope(value) {
-  const request = value.request;
-  if (request === null || typeof request !== "object" || Array.isArray(request)) {
-    throw new JobEnvelopeError("Invalid job request envelope: missing request");
-  }
-  const fields = request;
-  if (fields.v !== 1) {
+function validateJobRequest(value) {
+  requirePlainObject(value, "request", "job request");
+  requireExactKeys(
+    value,
+    [
+      "v",
+      "jobId",
+      "owner",
+      "builder",
+      "builderPublicKey",
+      "grantId",
+      "scope",
+      "operation",
+      "pinnedVersion",
+      "deadline"
+    ],
+    "job request"
+  );
+  if (value.v !== JOB_PROTOCOL_VERSION) {
     throw new JobEnvelopeError(
-      `Unsupported job request version: ${String(fields.v)}`
+      `Unsupported job request version: ${String(value.v)}`
     );
   }
-  for (const field of [
-    "jobId",
-    "owner",
-    "builder",
-    "builderPublicKey",
-    "grantId",
-    "scope",
-    "operation",
-    "deadline"
-  ]) {
-    requireString(fields[field], field, "job request");
-  }
-  if (fields.pinnedVersion !== null && typeof fields.pinnedVersion !== "string") {
+  requireString(value.jobId, "jobId", "job request");
+  if (typeof value.owner !== "string" || !isAddress(value.owner)) {
+    throw new JobEnvelopeError("Invalid job request: invalid owner");
+  }
+  if (typeof value.builder !== "string" || !isAddress(value.builder)) {
+    throw new JobEnvelopeError("Invalid job request: invalid builder");
+  }
+  if (typeof value.builderPublicKey !== "string" || !isHex(value.builderPublicKey)) {
+    throw new JobEnvelopeError("Invalid job request: invalid builderPublicKey");
+  }
+  if (typeof value.grantId !== "string" || !isHex(value.grantId)) {
+    throw new JobEnvelopeError("Invalid job request: invalid grantId");
+  }
+  requireString(value.scope, "scope", "job request");
+  if (!JOB_OPERATIONS.includes(value.operation)) {
+    throw new JobEnvelopeError("Invalid job request: invalid operation");
+  }
+  if (value.pinnedVersion !== null && typeof value.pinnedVersion !== "string") {
     throw new JobEnvelopeError("Invalid job request: missing pinnedVersion");
   }
+  if (typeof value.deadline !== "string" || !Number.isFinite(Date.parse(value.deadline))) {
+    throw new JobEnvelopeError("Invalid job request: invalid deadline");
+  }
+  return value;
+}
+function validateRequestEnvelope(value) {
+  requirePlainObject(value, "envelope", "job request envelope");
+  requireExactKeys(value, ["request", "auth"], "job request envelope");
+  validateJobRequest(value.request);
   requireString(value.auth, "auth", "job request envelope");
   return value;
 }
 function validateResult(value) {
-  if (value.v !== 1) {
+  requirePlainObject(value, "result", "job result");
+  requireExactKeys(
+    value,
+    ["v", "jobId", "scope", "version", "contentType", "body"],
+    "job result"
+  );
+  if (value.v !== JOB_PROTOCOL_VERSION) {
     throw new JobEnvelopeError(
       `Unsupported job result version: ${String(value.v)}`
     );
@@ -114,10 +180,10 @@ function validateResult(value) {
   }
   return value;
 }
-async function sealJobRequest(e, enclavePublicKey, ecies) {
+async function sealJobRequest(envelope, enclavePublicKey, ecies) {
   const encrypted = await ecies.encrypt(
     fromHex(enclavePublicKey, "bytes"),
-    requestPlaintext(e)
+    requestPlaintext(envelope)
   );
   return encryptedBytesToBase64(encrypted);
 }
@@ -130,10 +196,11 @@ async function openJobRequest(ciphertext, privateKey, ecies) {
     parseObject(plaintext, "job request envelope")
   );
 }
-async function sealJobResult(r, builderPublicKey, ecies) {
+async function sealJobResult(result, builderPublicKey, ecies) {
+  validateResult(result);
   const encrypted = await ecies.encrypt(
     fromHex(builderPublicKey, "bytes"),
-    resultPlaintext(r)
+    resultPlaintext(result)
   );
   const ciphertext = encryptedBytesToBase64(encrypted);
   const bytes = fromBase64(ciphertext);
@@ -164,6 +231,7 @@ async function openJobResult(ciphertext, builderPrivateKey, ecies, expect) {
 }
 export {
   JobEnvelopeError,
+  canonicalJobRequestBytes,
   openJobRequest,
   openJobResult,
   sealJobRequest,