@opendatalabs/vana-sdk 3.20.1 → 3.22.0-pr.207.0a5d07b

package/README.md

@@ -621,6 +621,70 @@ These helpers require `personal-server-ts` main `d91124d` or later, which is
 where the query-in-the-signed-uri rule, the `nonce` claim, the 404 for an
 unknown id and the full-view `recompute` answer landed.
 
+### Watching a derived scope as the reader
+
+The helpers above are the builder's: every one of them needs a write session,
+which an app holding only a bare read entry on the derived scope cannot open.
+That reader sees `GET /v1/data/<derivedScope>` answer 404 whether the compute
+is running, retrying, or finished failing.
+
+`getDerivativeStatus` is the reader's view of the same question. It
+authenticates like a data read — a live grant covering the derived scope, or
+the owner — and nothing is charged, so a priced grant raises no 402 here.
+
+```typescript
+import {
+  getDerivativeStatus,
+  waitForDerivativeStatus,
+} from "@opendatalabs/vana-sdk";
+
+const status = await getDerivativeStatus({
+  personalServerUrl: "https://ps.example.com",
+  derivedScope: "coach.weekly",
+  grantId,
+  signer,
+});
+// { derivedScope, status, lastComputedAt, derivedVersion,
+//   derivedCollectedAt, errorCode, retryAfterSeconds }
+
+const settled = await waitForDerivativeStatus({
+  personalServerUrl: "https://ps.example.com",
+  derivedScope: "coach.weekly",
+  grantId,
+  signer,
+  timeoutMs: 60_000,
+});
+```
+
+The view is lifecycle only: the question text, the source scopes, the question
+id, the registrar and the server's raw `error` string stay owner-only.
+`errorCode` is a closed vocabulary — `inference_unavailable`,
+`source_missing`, `grant_invalid`, `internal` — and is `null` unless `status`
+is `failed`.
+
+`retryAfterSeconds` is what separates a failure that is still being worked on
+from one that is over: `inference_unavailable` is the one transient class, and
+the Personal Server retries it on its own schedule. `waitForDerivativeStatus`
+returns as soon as the scope is `ready` or has failed with no retry pending,
+keeps waiting through a retrying failure, and takes the server's
+`retryAfterSeconds` as the cadence in place of `pollIntervalMs`, longer or
+shorter — it is when the next compute actually happens, so asking sooner sees
+nothing new and asking later sits on an answer that already exists. Once the
+remaining budget cannot cover the next cadence it raises the timeout rather
+than spending one more request that cannot carry new data. `signal` aborts
+the wait and the request in flight with it. A failed status is returned, not thrown; branch
+on `errorCode`. `isDerivativeStatusSettled` is the same predicate, exported
+for callers that poll on their own.
+
+When several questions write the same derived scope, the most optimistic true
+state answers (`ready`, then `stale`, then `pending`, then `failed`), because
+serving data is registration-agnostic: a duplicate that never wrote anything
+must not report away an answer the scope has.
+
+The status route needs a Personal Server that ships it; an older one answers
+404 for the route itself, which arrives as `DerivativeQuestionNotFoundError`
+— the same error as a covered scope with no question behind it.
+
 ## Networks
 
 | Network        | Chain ID | RPC URL                     |

package/dist/crypto/envelope/job.cjs

@@ -0,0 +1,263 @@
+"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 job_exports = {};
+__export(job_exports, {
+  JobEnvelopeError: () => JobEnvelopeError,
+  canonicalJobRequestBytes: () => canonicalJobRequestBytes,
+  openJobRequest: () => openJobRequest,
+  openJobResult: () => openJobResult,
+  sealJobRequest: () => sealJobRequest,
+  sealJobResult: () => sealJobResult
+});
+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();
+class JobEnvelopeError extends Error {
+  constructor(message) {
+    super(message);
+    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) {
+  validateRequestEnvelope(envelope);
+  return canonicalJsonBytes(envelope);
+}
+function resultPlaintext(result) {
+  return textEncoder.encode(
+    JSON.stringify({
+      v: result.v,
+      jobId: result.jobId,
+      scope: result.scope,
+      version: result.version,
+      contentType: result.contentType,
+      body: result.body
+    })
+  );
+}
+function encryptedBytesToBase64(encrypted) {
+  return (0, import_encoding.toBase64)((0, import_viem.fromHex)(`0x${(0, import_interface.serializeECIES)(encrypted)}`, "bytes"));
+}
+function base64ToEncrypted(ciphertext) {
+  return (0, import_interface.deserializeECIES)((0, import_viem.toHex)((0, import_encoding.fromBase64)(ciphertext)));
+}
+function parseObject(plaintext, kind) {
+  try {
+    const value = JSON.parse(textDecoder.decode(plaintext));
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+      throw new JobEnvelopeError(`Invalid ${kind}: expected an object`);
+    }
+    return value;
+  } catch (error) {
+    if (error instanceof JobEnvelopeError) throw error;
+    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 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(value.v)}`
+    );
+  }
+  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) {
+  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)}`
+    );
+  }
+  for (const field of ["jobId", "scope", "contentType"]) {
+    requireString(value[field], field, "job result");
+  }
+  if (typeof value.body !== "string") {
+    throw new JobEnvelopeError("Invalid job result: missing body");
+  }
+  if (value.version !== null && typeof value.version !== "string") {
+    throw new JobEnvelopeError("Invalid job result: missing version");
+  }
+  return value;
+}
+async function sealJobRequest(envelope, enclavePublicKey, ecies) {
+  const encrypted = await ecies.encrypt(
+    (0, import_viem.fromHex)(enclavePublicKey, "bytes"),
+    requestPlaintext(envelope)
+  );
+  return encryptedBytesToBase64(encrypted);
+}
+async function openJobRequest(ciphertext, privateKey, ecies) {
+  const plaintext = await ecies.decrypt(
+    privateKey,
+    base64ToEncrypted(ciphertext)
+  );
+  return validateRequestEnvelope(
+    parseObject(plaintext, "job request envelope")
+  );
+}
+async function sealJobResult(result, builderPublicKey, ecies) {
+  validateResult(result);
+  const encrypted = await ecies.encrypt(
+    (0, import_viem.fromHex)(builderPublicKey, "bytes"),
+    resultPlaintext(result)
+  );
+  const ciphertext = encryptedBytesToBase64(encrypted);
+  const bytes = (0, import_encoding.fromBase64)(ciphertext);
+  return { ciphertext, hash: (0, import_viem.bytesToHex)((0, import_sha2.sha256)(bytes)), size: bytes.length };
+}
+async function openJobResult(ciphertext, builderPrivateKey, ecies, expect) {
+  const plaintext = await ecies.decrypt(
+    (0, import_viem.fromHex)(builderPrivateKey, "bytes"),
+    base64ToEncrypted(ciphertext)
+  );
+  const result = validateResult(parseObject(plaintext, "job result"));
+  if (result.jobId !== expect.jobId) {
+    throw new JobEnvelopeError(
+      `Job result ID ${result.jobId} does not match expected job ID ${expect.jobId}`
+    );
+  }
+  if (expect.scope !== void 0 && result.scope !== expect.scope) {
+    throw new JobEnvelopeError(
+      `Job result scope ${result.scope} does not match expected scope ${expect.scope}`
+    );
+  }
+  if (expect.version !== void 0 && result.version !== expect.version) {
+    throw new JobEnvelopeError(
+      `Job result version ${String(result.version)} does not match expected version ${String(expect.version)}`
+    );
+  }
+  return result;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  JobEnvelopeError,
+  canonicalJobRequestBytes,
+  openJobRequest,
+  openJobResult,
+  sealJobRequest,
+  sealJobResult
+});
+//# sourceMappingURL=job.cjs.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,122 @@
+/**
+ * ECIES envelopes for encrypted job requests and results.
+ *
+ * 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 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);
+}
+/**
+ * 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>;
+/**
+ * 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;
+    version?: string | null;
+}): Promise<JobResult>;