@opendatalabs/vana-sdk 3.21.0 → 3.22.0-pr.207.e47cd30

package/dist/protocol/derivative-status.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Derivative status: the lifecycle of the question behind a derived scope,
+ * as the party that READS the answer sees it.
+ *
+ * @remarks
+ * A builder registers a question with {@link registerQuestion} and follows it
+ * with {@link waitForQuestion}, both of which need a write session. The app
+ * that only consumes the answer holds no write entry at all — a consent flow
+ * grants it a bare read on the derived scope — so it cannot open one, and
+ * `GET /v1/data/<derivedScope>` answers 404 for all three of "computing right
+ * now", "failed but retrying" and "failed for good".
+ *
+ * `GET /v1/derivatives/status?derivedScope=<scope>` is that reader's view.
+ * Authorization is the data read's (a live grant covering the derived scope,
+ * or the owner), nothing is served and nothing is charged, and the view is
+ * deliberately narrow: lifecycle, a coarse {@link DerivativeErrorCode} and
+ * the next retry. The question text, the source scopes, the question id, the
+ * registrar and the server's raw error string stay owner-only.
+ *
+ * Requires `personal-server-ts` with the status route; an older Personal
+ * Server answers 404 for the route itself.
+ *
+ * @category Protocol
+ */
+import { z } from "zod";
+import { type QuestionStatus } from "./derivative-questions.js";
+import { type ResolveWriteSignerOptions, type WriteSignerSource } from "./write-signer.js";
+export { DERIVATIVE_ERROR_CODES, DerivativeErrorCodeSchema, type DerivativeErrorCode, } from "./derivative-questions.js";
+/** The reader-facing status route. */
+export declare const DERIVATIVE_STATUS_PATH = "/v1/derivatives/status";
+/** How long {@link waitForDerivativeStatus} polls before giving up. */
+export declare const DEFAULT_DERIVATIVE_STATUS_TIMEOUT_MS = 120000;
+/**
+ * How long {@link waitForDerivativeStatus} waits between polls when the
+ * server names no retry time of its own.
+ */
+export declare const DEFAULT_DERIVATIVE_STATUS_POLL_INTERVAL_MS = 2000;
+/**
+ * The status of the derived scope, not of one registration: when several
+ * questions write the same scope, the server reports the most optimistic
+ * true state, because serving data is registration-agnostic.
+ */
+export declare const DerivativeStatusSchema: z.ZodObject<{
+    derivedScope: z.ZodString;
+    status: z.ZodEnum<{
+        pending: "pending";
+        ready: "ready";
+        failed: "failed";
+        stale: "stale";
+    }>;
+    lastComputedAt: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    derivedVersion: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodNumber>>, z.ZodTransform<number | null, number | null | undefined>>;
+    derivedCollectedAt: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    errorCode: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        internal: "internal";
+        inference_unavailable: "inference_unavailable";
+        source_missing: "source_missing";
+        grant_invalid: "grant_invalid";
+    }>>>, z.ZodTransform<NonNullable<"internal" | "inference_unavailable" | "source_missing" | "grant_invalid"> | null, "internal" | "inference_unavailable" | "source_missing" | "grant_invalid" | null | undefined>>;
+    retryAfterSeconds: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodNumber>>, z.ZodTransform<number | null, number | null | undefined>>;
+}, z.core.$strip>;
+/** @see {@link DerivativeStatusSchema} */
+export type DerivativeStatus = z.infer<typeof DerivativeStatusSchema>;
+/** What {@link getDerivativeStatus} needs to sign and send one read. */
+export interface GetDerivativeStatusParams extends ResolveWriteSignerOptions {
+    /** Personal Server origin, e.g. `https://ps.example.com`. */
+    personalServerUrl: string;
+    /** The derived scope whose question to observe. */
+    derivedScope: string;
+    /**
+     * A grant covering the derived scope, sent as the signed `grantId` claim.
+     * Omit only when the signer is the Personal Server's owner, who is
+     * authorized without one.
+     */
+    grantId?: string;
+    /** Reader key: a viem `LocalAccount`, `WalletClient`, or `{ signMessage }`. */
+    signer: WriteSignerSource;
+    /** Web3Signed audience; defaults to `personalServerUrl`. */
+    audience?: string;
+    /** `fetch` to use; defaults to `globalThis.fetch`. */
+    fetch?: typeof fetch;
+    /** Extra request headers. */
+    headers?: HeadersInit;
+    /** Aborts the request in flight. */
+    signal?: AbortSignal;
+}
+/** What {@link waitForDerivativeStatus} polls with. */
+export interface WaitForDerivativeStatusParams extends GetDerivativeStatusParams {
+    /** Give up after this long (default 120s). */
+    timeoutMs?: number;
+    /**
+     * Wait between polls when the server names no retry time (default 2s).
+     * A `retryAfterSeconds` from the server replaces this outright, longer or
+     * shorter: it is when the next compute actually happens.
+     */
+    pollIntervalMs?: number;
+    /**
+     * Aborts the wait, and the request in flight with it: the signal is passed
+     * to every poll, so an abort during a stalled request does not sit until
+     * the transport gives up.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * The request target for a status read: the query carries the derived scope,
+ * the signed `uri` does not.
+ *
+ * @remarks
+ * Like every Web3Signed read (data, lineage), the Personal Server verifies
+ * the signature over the PATH; per-scope authorization is enforced live
+ * against the caller's grant on each request, so the query needs no
+ * signature to be safe. Only the write path signs path AND query, where a
+ * parameter decides what is written.
+ */
+export declare function derivativeStatusTarget(derivedScope: string): string;
+/**
+ * Is this a state the reader can act on?
+ *
+ * @remarks
+ * `ready` means the derived scope has an answer to read. A `failed` status
+ * is settled only when no retry is pending: with `retryAfterSeconds` set the
+ * Personal Server will compute again on its own, so the answer may still
+ * arrive. `pending` and `stale` are always in flight.
+ */
+export declare function isDerivativeStatusSettled(status: DerivativeStatus): boolean;
+/**
+ * Read the lifecycle of the question behind a derived scope.
+ *
+ * @remarks
+ * Sends `GET /v1/derivatives/status?derivedScope=<scope>` with a Web3Signed
+ * `Authorization` header carrying `grantId`, the same authentication a data
+ * read uses. Nothing is charged: the route authorizes, it does not serve
+ * data, so a priced grant raises no 402 here.
+ *
+ * @returns The status of the derived scope. When several registrations write
+ *   it, the most optimistic true state answers — `ready`, then `stale`, then
+ *   `pending`, then `failed` — because a duplicate that never wrote anything
+ *   must not report away an answer the scope has.
+ * @throws {DerivativeQuestionNotFoundError} 404: the caller may read the
+ *   scope but no question stands behind it (and, on an older Personal
+ *   Server, the route itself is unknown).
+ * @throws {WriteForbiddenError} 403: the grant does not cover the derived
+ *   scope. The check runs before any store lookup, so a caller cannot probe
+ *   which scopes have questions.
+ * @throws {DerivativeQuestionRejectedError} On any other non-2xx answer or
+ *   an unparseable body.
+ * @throws {WriteTransportError} When `fetch` itself failed.
+ * @throws {WriteRequestError} On a missing `derivedScope` or no `fetch`.
+ *
+ * @example
+ * ```typescript
+ * const status = await getDerivativeStatus({
+ *   personalServerUrl: "https://ps.example.com",
+ *   derivedScope: "coach.weekly",
+ *   grantId,
+ *   signer,
+ * });
+ * if (status.status === "ready") {
+ *   const record = await readPersonalServerData({ ... });
+ * } else if (status.retryAfterSeconds !== null) {
+ *   // Computing or retrying: come back then.
+ * }
+ * ```
+ */
+export declare function getDerivativeStatus(params: GetDerivativeStatusParams): Promise<DerivativeStatus>;
+/**
+ * Poll {@link getDerivativeStatus} until the derived scope has an answer or
+ * has stopped trying to get one.
+ *
+ * @remarks
+ * Returns as soon as {@link isDerivativeStatusSettled} holds: `ready`, or
+ * `failed` with no retry pending. A failure the server will retry is not a
+ * result, so the wait continues through it — on the server's own cadence,
+ * because `retryAfterSeconds` is when the next compute actually happens and
+ * polling faster only spends requests. A failed status is returned, not
+ * thrown: the reader branches on `errorCode`.
+ *
+ * @returns The settled status.
+ * @throws {DerivativeQuestionTimeoutError} When the budget ran out first.
+ *   The question keeps computing on the server; call again.
+ *
+ * @example
+ * ```typescript
+ * const status = await waitForDerivativeStatus({
+ *   personalServerUrl,
+ *   derivedScope: "coach.weekly",
+ *   grantId,
+ *   signer,
+ *   timeoutMs: 60_000,
+ * });
+ * if (status.status !== "ready") console.log(status.errorCode);
+ * ```
+ */
+export declare function waitForDerivativeStatus(params: WaitForDerivativeStatusParams): Promise<DerivativeStatus>;
+/** Statuses that mean a compute is in flight. @see {@link QuestionStatus} */
+export type PendingDerivativeStatus = Extract<QuestionStatus, "pending" | "stale">;

package/dist/protocol/derivative-status.js

@@ -0,0 +1,190 @@
+import { z } from "zod";
+import { buildWeb3SignedHeader } from "../auth/web3-signed-builder.js";
+import {
+  DerivativeQuestionRejectedError,
+  DerivativeQuestionTimeoutError,
+  WriteRequestError,
+  WriteTransportError
+} from "../errors.js";
+import {
+  DerivativeErrorCodeSchema,
+  personalServerErrorFromQuestionResponse,
+  QuestionStatusSchema
+} from "./derivative-questions.js";
+import {
+  resolveWriteSigner
+} from "./write-signer.js";
+import {
+  DERIVATIVE_ERROR_CODES,
+  DerivativeErrorCodeSchema as DerivativeErrorCodeSchema2
+} from "./derivative-questions.js";
+const DERIVATIVE_STATUS_PATH = "/v1/derivatives/status";
+const DEFAULT_DERIVATIVE_STATUS_TIMEOUT_MS = 12e4;
+const DEFAULT_DERIVATIVE_STATUS_POLL_INTERVAL_MS = 2e3;
+const nullable = (schema) => schema.nullish().transform((value) => value ?? null);
+const DerivativeStatusSchema = z.object({
+  derivedScope: z.string().min(1),
+  status: QuestionStatusSchema,
+  /** When the last compute finished, or `null` if none ever has. */
+  lastComputedAt: nullable(z.string()),
+  /** Local version of the derived record the last compute wrote. */
+  derivedVersion: nullable(z.number()),
+  derivedCollectedAt: nullable(z.string()),
+  /** The failure class; `null` unless `status` is `failed`. */
+  errorCode: nullable(DerivativeErrorCodeSchema),
+  /**
+   * Seconds until the Personal Server's next automatic retry, or `null` when
+   * none is pending or running — the terminal signature. Poll on this cadence
+   * rather than guessing one.
+   */
+  retryAfterSeconds: nullable(z.number())
+});
+function derivativeStatusTarget(derivedScope) {
+  return `${DERIVATIVE_STATUS_PATH}?derivedScope=${encodeURIComponent(derivedScope)}`;
+}
+function normalizeBaseUrl(url) {
+  return url.replace(/\/+$/, "");
+}
+function resolveFetch(fetchFn) {
+  const resolved = fetchFn ?? globalThis.fetch;
+  if (resolved === void 0) {
+    throw new WriteRequestError("No fetch implementation available");
+  }
+  return resolved;
+}
+function requireDerivedScope(derivedScope) {
+  if (typeof derivedScope !== "string" || derivedScope.length === 0) {
+    throw new WriteRequestError("derivedScope is required");
+  }
+  return derivedScope;
+}
+function sleep(ms, signal) {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(abortError(signal));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function timeoutError(latest, timeoutMs) {
+  return new DerivativeQuestionTimeoutError(
+    `Derived scope ${latest.derivedScope} was still ${latest.status} after ${timeoutMs}ms`,
+    {
+      derivedScope: latest.derivedScope,
+      status: latest.status,
+      errorCode: latest.errorCode,
+      retryAfterSeconds: latest.retryAfterSeconds,
+      timeoutMs
+    }
+  );
+}
+function abortError(signal) {
+  const reason = signal?.reason;
+  return reason instanceof Error ? reason : new WriteRequestError("Derivative status wait was aborted");
+}
+function isDerivativeStatusSettled(status) {
+  if (status.status === "ready") return true;
+  return status.status === "failed" && status.retryAfterSeconds === null;
+}
+async function getDerivativeStatus(params) {
+  const derivedScope = requireDerivedScope(params.derivedScope);
+  const fetchFn = resolveFetch(params.fetch);
+  const baseUrl = normalizeBaseUrl(params.personalServerUrl);
+  const signer = resolveWriteSigner(params.signer, { account: params.account });
+  const headers = new Headers(params.headers);
+  headers.set(
+    "Authorization",
+    await buildWeb3SignedHeader({
+      signMessage: signer.signMessage,
+      aud: params.audience ?? baseUrl,
+      method: "GET",
+      uri: DERIVATIVE_STATUS_PATH,
+      grantId: params.grantId
+    })
+  );
+  let response;
+  try {
+    response = await fetchFn(
+      `${baseUrl}${derivativeStatusTarget(derivedScope)}`,
+      {
+        method: "GET",
+        headers,
+        ...params.signal ? { signal: params.signal } : {}
+      }
+    );
+  } catch (err) {
+    throw new WriteTransportError(
+      `Derivative status read failed: ${err instanceof Error ? err.message : String(err)}`,
+      1,
+      err
+    );
+  }
+  if (!response.ok) {
+    throw await personalServerErrorFromQuestionResponse(
+      response
+    );
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch (err) {
+    throw new DerivativeQuestionRejectedError(
+      "Derivative status response is not JSON",
+      response.status,
+      null,
+      { cause: err instanceof Error ? err.message : String(err) }
+    );
+  }
+  const parsed = DerivativeStatusSchema.safeParse(body);
+  if (!parsed.success) {
+    throw new DerivativeQuestionRejectedError(
+      "Derivative status response is not a status view",
+      response.status,
+      null,
+      { issues: parsed.error.issues }
+    );
+  }
+  return parsed.data;
+}
+async function waitForDerivativeStatus(params) {
+  const timeoutMs = Math.max(
+    0,
+    params.timeoutMs ?? DEFAULT_DERIVATIVE_STATUS_TIMEOUT_MS
+  );
+  const pollIntervalMs = Math.max(
+    0,
+    params.pollIntervalMs ?? DEFAULT_DERIVATIVE_STATUS_POLL_INTERVAL_MS
+  );
+  const deadline = Date.now() + timeoutMs;
+  for (; ; ) {
+    if (params.signal?.aborted) throw abortError(params.signal);
+    const latest = await getDerivativeStatus(params);
+    if (isDerivativeStatusSettled(latest)) return latest;
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) throw timeoutError(latest, timeoutMs);
+    const waitMs = latest.retryAfterSeconds === null ? pollIntervalMs : latest.retryAfterSeconds * 1e3;
+    if (waitMs > remaining) {
+      throw timeoutError(latest, timeoutMs);
+    }
+    await sleep(waitMs, params.signal);
+  }
+}
+export {
+  DEFAULT_DERIVATIVE_STATUS_POLL_INTERVAL_MS,
+  DEFAULT_DERIVATIVE_STATUS_TIMEOUT_MS,
+  DERIVATIVE_ERROR_CODES,
+  DERIVATIVE_STATUS_PATH,
+  DerivativeErrorCodeSchema2 as DerivativeErrorCodeSchema,
+  DerivativeStatusSchema,
+  derivativeStatusTarget,
+  getDerivativeStatus,
+  isDerivativeStatusSettled,
+  waitForDerivativeStatus
+};
+//# sourceMappingURL=derivative-status.js.map

package/dist/protocol/derivative-status.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/protocol/derivative-status.ts"],"sourcesContent":["/**\n * Derivative status: the lifecycle of the question behind a derived scope,\n * as the party that READS the answer sees it.\n *\n * @remarks\n * A builder registers a question with {@link registerQuestion} and follows it\n * with {@link waitForQuestion}, both of which need a write session. The app\n * that only consumes the answer holds no write entry at all — a consent flow\n * grants it a bare read on the derived scope — so it cannot open one, and\n * `GET /v1/data/<derivedScope>` answers 404 for all three of \"computing right\n * now\", \"failed but retrying\" and \"failed for good\".\n *\n * `GET /v1/derivatives/status?derivedScope=<scope>` is that reader's view.\n * Authorization is the data read's (a live grant covering the derived scope,\n * or the owner), nothing is served and nothing is charged, and the view is\n * deliberately narrow: lifecycle, a coarse {@link DerivativeErrorCode} and\n * the next retry. The question text, the source scopes, the question id, the\n * registrar and the server's raw error string stay owner-only.\n *\n * Requires `personal-server-ts` with the status route; an older Personal\n * Server answers 404 for the route itself.\n *\n * @category Protocol\n */\n\nimport { z } from \"zod\";\nimport { buildWeb3SignedHeader } from \"../auth/web3-signed-builder\";\nimport {\n  DerivativeQuestionRejectedError,\n  DerivativeQuestionTimeoutError,\n  WriteRequestError,\n  WriteTransportError,\n  type PersonalServerWriteError,\n} from \"../errors\";\nimport {\n  DerivativeErrorCodeSchema,\n  personalServerErrorFromQuestionResponse,\n  QuestionStatusSchema,\n  type QuestionStatus,\n} from \"./derivative-questions\";\nimport {\n  resolveWriteSigner,\n  type ResolveWriteSignerOptions,\n  type WriteSignerSource,\n} from \"./write-signer\";\n\nexport {\n  DERIVATIVE_ERROR_CODES,\n  DerivativeErrorCodeSchema,\n  type DerivativeErrorCode,\n} from \"./derivative-questions\";\n\n/** The reader-facing status route. */\nexport const DERIVATIVE_STATUS_PATH = \"/v1/derivatives/status\";\n\n/** How long {@link waitForDerivativeStatus} polls before giving up. */\nexport const DEFAULT_DERIVATIVE_STATUS_TIMEOUT_MS = 120_000;\n\n/**\n * How long {@link waitForDerivativeStatus} waits between polls when the\n * server names no retry time of its own.\n */\nexport const DEFAULT_DERIVATIVE_STATUS_POLL_INTERVAL_MS = 2_000;\n\nconst nullable = <T extends z.ZodTypeAny>(schema: T) =>\n  schema\n    .nullish()\n    .transform((value: z.infer<T> | null | undefined) => value ?? null);\n\n/**\n * The status of the derived scope, not of one registration: when several\n * questions write the same scope, the server reports the most optimistic\n * true state, because serving data is registration-agnostic.\n */\nexport const DerivativeStatusSchema = z.object({\n  derivedScope: z.string().min(1),\n  status: QuestionStatusSchema,\n  /** When the last compute finished, or `null` if none ever has. */\n  lastComputedAt: nullable(z.string()),\n  /** Local version of the derived record the last compute wrote. */\n  derivedVersion: nullable(z.number()),\n  derivedCollectedAt: nullable(z.string()),\n  /** The failure class; `null` unless `status` is `failed`. */\n  errorCode: nullable(DerivativeErrorCodeSchema),\n  /**\n   * Seconds until the Personal Server's next automatic retry, or `null` when\n   * none is pending or running — the terminal signature. Poll on this cadence\n   * rather than guessing one.\n   */\n  retryAfterSeconds: nullable(z.number()),\n});\n\n/** @see {@link DerivativeStatusSchema} */\nexport type DerivativeStatus = z.infer<typeof DerivativeStatusSchema>;\n\n/** What {@link getDerivativeStatus} needs to sign and send one read. */\nexport interface GetDerivativeStatusParams extends ResolveWriteSignerOptions {\n  /** Personal Server origin, e.g. `https://ps.example.com`. */\n  personalServerUrl: string;\n  /** The derived scope whose question to observe. */\n  derivedScope: string;\n  /**\n   * A grant covering the derived scope, sent as the signed `grantId` claim.\n   * Omit only when the signer is the Personal Server's owner, who is\n   * authorized without one.\n   */\n  grantId?: string;\n  /** Reader key: a viem `LocalAccount`, `WalletClient`, or `{ signMessage }`. */\n  signer: WriteSignerSource;\n  /** Web3Signed audience; defaults to `personalServerUrl`. */\n  audience?: string;\n  /** `fetch` to use; defaults to `globalThis.fetch`. */\n  fetch?: typeof fetch;\n  /** Extra request headers. */\n  headers?: HeadersInit;\n  /** Aborts the request in flight. */\n  signal?: AbortSignal;\n}\n\n/** What {@link waitForDerivativeStatus} polls with. */\nexport interface WaitForDerivativeStatusParams extends GetDerivativeStatusParams {\n  /** Give up after this long (default 120s). */\n  timeoutMs?: number;\n  /**\n   * Wait between polls when the server names no retry time (default 2s).\n   * A `retryAfterSeconds` from the server replaces this outright, longer or\n   * shorter: it is when the next compute actually happens.\n   */\n  pollIntervalMs?: number;\n  /**\n   * Aborts the wait, and the request in flight with it: the signal is passed\n   * to every poll, so an abort during a stalled request does not sit until\n   * the transport gives up.\n   */\n  signal?: AbortSignal;\n}\n\n/**\n * The request target for a status read: the query carries the derived scope,\n * the signed `uri` does not.\n *\n * @remarks\n * Like every Web3Signed read (data, lineage), the Personal Server verifies\n * the signature over the PATH; per-scope authorization is enforced live\n * against the caller's grant on each request, so the query needs no\n * signature to be safe. Only the write path signs path AND query, where a\n * parameter decides what is written.\n */\nexport function derivativeStatusTarget(derivedScope: string): string {\n  return `${DERIVATIVE_STATUS_PATH}?derivedScope=${encodeURIComponent(derivedScope)}`;\n}\n\nfunction normalizeBaseUrl(url: string): string {\n  return url.replace(/\\/+$/, \"\");\n}\n\nfunction resolveFetch(fetchFn: typeof fetch | undefined): typeof fetch {\n  const resolved = fetchFn ?? globalThis.fetch;\n  if (resolved === undefined) {\n    throw new WriteRequestError(\"No fetch implementation available\");\n  }\n  return resolved;\n}\n\nfunction requireDerivedScope(derivedScope: string): string {\n  if (typeof derivedScope !== \"string\" || derivedScope.length === 0) {\n    // The server answers 400 DERIVATIVE_DERIVED_SCOPE_REQUIRED; refuse before\n    // signing rather than spend a signature on a request that cannot pass.\n    throw new WriteRequestError(\"derivedScope is required\");\n  }\n  return derivedScope;\n}\n\nfunction sleep(ms: number, signal?: AbortSignal): Promise<void> {\n  if (ms <= 0) return Promise.resolve();\n  return new Promise((resolve, reject) => {\n    const timer = setTimeout(() => {\n      signal?.removeEventListener(\"abort\", onAbort);\n      resolve();\n    }, ms);\n    const onAbort = () => {\n      clearTimeout(timer);\n      reject(abortError(signal));\n    };\n    signal?.addEventListener(\"abort\", onAbort, { once: true });\n  });\n}\n\nfunction timeoutError(\n  latest: DerivativeStatus,\n  timeoutMs: number,\n): DerivativeQuestionTimeoutError {\n  return new DerivativeQuestionTimeoutError(\n    `Derived scope ${latest.derivedScope} was still ${latest.status} after ${timeoutMs}ms`,\n    {\n      derivedScope: latest.derivedScope,\n      status: latest.status,\n      errorCode: latest.errorCode,\n      retryAfterSeconds: latest.retryAfterSeconds,\n      timeoutMs,\n    },\n  );\n}\n\nfunction abortError(signal?: AbortSignal): Error {\n  const reason = signal?.reason;\n  return reason instanceof Error\n    ? reason\n    : new WriteRequestError(\"Derivative status wait was aborted\");\n}\n\n/**\n * Is this a state the reader can act on?\n *\n * @remarks\n * `ready` means the derived scope has an answer to read. A `failed` status\n * is settled only when no retry is pending: with `retryAfterSeconds` set the\n * Personal Server will compute again on its own, so the answer may still\n * arrive. `pending` and `stale` are always in flight.\n */\nexport function isDerivativeStatusSettled(status: DerivativeStatus): boolean {\n  if (status.status === \"ready\") return true;\n  return status.status === \"failed\" && status.retryAfterSeconds === null;\n}\n\n/**\n * Read the lifecycle of the question behind a derived scope.\n *\n * @remarks\n * Sends `GET /v1/derivatives/status?derivedScope=<scope>` with a Web3Signed\n * `Authorization` header carrying `grantId`, the same authentication a data\n * read uses. Nothing is charged: the route authorizes, it does not serve\n * data, so a priced grant raises no 402 here.\n *\n * @returns The status of the derived scope. When several registrations write\n *   it, the most optimistic true state answers — `ready`, then `stale`, then\n *   `pending`, then `failed` — because a duplicate that never wrote anything\n *   must not report away an answer the scope has.\n * @throws {DerivativeQuestionNotFoundError} 404: the caller may read the\n *   scope but no question stands behind it (and, on an older Personal\n *   Server, the route itself is unknown).\n * @throws {WriteForbiddenError} 403: the grant does not cover the derived\n *   scope. The check runs before any store lookup, so a caller cannot probe\n *   which scopes have questions.\n * @throws {DerivativeQuestionRejectedError} On any other non-2xx answer or\n *   an unparseable body.\n * @throws {WriteTransportError} When `fetch` itself failed.\n * @throws {WriteRequestError} On a missing `derivedScope` or no `fetch`.\n *\n * @example\n * ```typescript\n * const status = await getDerivativeStatus({\n *   personalServerUrl: \"https://ps.example.com\",\n *   derivedScope: \"coach.weekly\",\n *   grantId,\n *   signer,\n * });\n * if (status.status === \"ready\") {\n *   const record = await readPersonalServerData({ ... });\n * } else if (status.retryAfterSeconds !== null) {\n *   // Computing or retrying: come back then.\n * }\n * ```\n */\nexport async function getDerivativeStatus(\n  params: GetDerivativeStatusParams,\n): Promise<DerivativeStatus> {\n  const derivedScope = requireDerivedScope(params.derivedScope);\n  const fetchFn = resolveFetch(params.fetch);\n  const baseUrl = normalizeBaseUrl(params.personalServerUrl);\n  const signer = resolveWriteSigner(params.signer, { account: params.account });\n  const headers = new Headers(params.headers);\n  headers.set(\n    \"Authorization\",\n    await buildWeb3SignedHeader({\n      signMessage: signer.signMessage,\n      aud: params.audience ?? baseUrl,\n      method: \"GET\",\n      uri: DERIVATIVE_STATUS_PATH,\n      grantId: params.grantId,\n    }),\n  );\n\n  let response: Response;\n  try {\n    response = await fetchFn(\n      `${baseUrl}${derivativeStatusTarget(derivedScope)}`,\n      {\n        method: \"GET\",\n        headers,\n        ...(params.signal ? { signal: params.signal } : {}),\n      },\n    );\n  } catch (err) {\n    throw new WriteTransportError(\n      `Derivative status read failed: ${err instanceof Error ? err.message : String(err)}`,\n      1,\n      err,\n    );\n  }\n  if (!response.ok) {\n    throw (await personalServerErrorFromQuestionResponse(\n      response,\n    )) as PersonalServerWriteError;\n  }\n  let body: unknown;\n  try {\n    body = await response.json();\n  } catch (err) {\n    throw new DerivativeQuestionRejectedError(\n      \"Derivative status response is not JSON\",\n      response.status,\n      null,\n      { cause: err instanceof Error ? err.message : String(err) },\n    );\n  }\n  const parsed = DerivativeStatusSchema.safeParse(body);\n  if (!parsed.success) {\n    throw new DerivativeQuestionRejectedError(\n      \"Derivative status response is not a status view\",\n      response.status,\n      null,\n      { issues: parsed.error.issues },\n    );\n  }\n  return parsed.data;\n}\n\n/**\n * Poll {@link getDerivativeStatus} until the derived scope has an answer or\n * has stopped trying to get one.\n *\n * @remarks\n * Returns as soon as {@link isDerivativeStatusSettled} holds: `ready`, or\n * `failed` with no retry pending. A failure the server will retry is not a\n * result, so the wait continues through it — on the server's own cadence,\n * because `retryAfterSeconds` is when the next compute actually happens and\n * polling faster only spends requests. A failed status is returned, not\n * thrown: the reader branches on `errorCode`.\n *\n * @returns The settled status.\n * @throws {DerivativeQuestionTimeoutError} When the budget ran out first.\n *   The question keeps computing on the server; call again.\n *\n * @example\n * ```typescript\n * const status = await waitForDerivativeStatus({\n *   personalServerUrl,\n *   derivedScope: \"coach.weekly\",\n *   grantId,\n *   signer,\n *   timeoutMs: 60_000,\n * });\n * if (status.status !== \"ready\") console.log(status.errorCode);\n * ```\n */\nexport async function waitForDerivativeStatus(\n  params: WaitForDerivativeStatusParams,\n): Promise<DerivativeStatus> {\n  const timeoutMs = Math.max(\n    0,\n    params.timeoutMs ?? DEFAULT_DERIVATIVE_STATUS_TIMEOUT_MS,\n  );\n  const pollIntervalMs = Math.max(\n    0,\n    params.pollIntervalMs ?? DEFAULT_DERIVATIVE_STATUS_POLL_INTERVAL_MS,\n  );\n  const deadline = Date.now() + timeoutMs;\n  for (;;) {\n    if (params.signal?.aborted) throw abortError(params.signal);\n    const latest = await getDerivativeStatus(params);\n    if (isDerivativeStatusSettled(latest)) return latest;\n    const remaining = deadline - Date.now();\n    if (remaining <= 0) throw timeoutError(latest, timeoutMs);\n    // The server's scheduled retry decides the cadence outright, in both\n    // directions: a caller's longer pollIntervalMs would sit past a retry\n    // that has already produced an answer, and a shorter one would ask\n    // before anything can have changed. pollIntervalMs is the cadence for\n    // the case where the server named none.\n    const waitMs =\n      latest.retryAfterSeconds === null\n        ? pollIntervalMs\n        : latest.retryAfterSeconds * 1000;\n    if (waitMs > remaining) {\n      // The budget cannot cover the next cadence, so the poll after this\n      // sleep would land before anything could have changed. Give up now\n      // instead of spending a request to say the same thing.\n      throw timeoutError(latest, timeoutMs);\n    }\n    await sleep(waitMs, params.signal);\n  }\n}\n\n/** Statuses that mean a compute is in flight. @see {@link QuestionStatus} */\nexport type PendingDerivativeStatus = Extract<\n  QuestionStatus,\n  \"pending\" | \"stale\"\n>;\n"],"mappings":"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","names":["DerivativeErrorCodeSchema"]}

package/dist/protocol/derivative-status.test.d.ts

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

package/dist/protocol/identity.cjs

@@ -0,0 +1,169 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var identity_exports = {};
+__export(identity_exports, {
+  ENCLAVE_IDENTITY_EVIDENCE_VERSION: () => ENCLAVE_IDENTITY_EVIDENCE_VERSION,
+  ENCLAVE_TRUST_ANCHORS: () => ENCLAVE_TRUST_ANCHORS,
+  ENCLAVE_WALLET_PURPOSE: () => ENCLAVE_WALLET_PURPOSE,
+  MASTER_SIGNATURE_DELIVERY_VERSION: () => MASTER_SIGNATURE_DELIVERY_VERSION,
+  SEALED_ENVELOPE_VERSION: () => SEALED_ENVELOPE_VERSION,
+  USER_PS_ID_DOMAIN: () => USER_PS_ID_DOMAIN,
+  appRootPreimage: () => appRootPreimage,
+  buildMasterSignatureDelivery: () => buildMasterSignatureDelivery,
+  encryptMasterSignatureDelivery: () => encryptMasterSignatureDelivery,
+  kmsIssuedPreimage: () => kmsIssuedPreimage,
+  userPsId: () => userPsId,
+  verifyEnclaveIdentityEvidence: () => verifyEnclaveIdentityEvidence
+});
+module.exports = __toCommonJS(identity_exports);
+var secp256k1 = __toESM(require("@noble/secp256k1"), 1);
+var import_viem = require("viem");
+var import_accounts = require("viem/accounts");
+var import_interface = require("../crypto/ecies/interface");
+var import_derive = require("../crypto/keys/derive");
+const ENCLAVE_IDENTITY_EVIDENCE_VERSION = 1;
+const USER_PS_ID_DOMAIN = "vana.ps-enclave.v1";
+const ENCLAVE_WALLET_PURPOSE = "vana.ps-enclave.wallet.v1";
+const MASTER_SIGNATURE_DELIVERY_VERSION = "vana.ps-enclave.delivery.v1";
+const SEALED_ENVELOPE_VERSION = 1;
+const VANA_MAINNET_CHAIN_ID = 1480;
+const MOKSHA_CHAIN_ID = 14800;
+const KMS_ISSUED_PREFIX = "dstack-kms-issued";
+const PREIMAGE_SEPARATOR = ":";
+const UNCOMPRESSED_PUBLIC_KEY_BYTES = 65;
+const UNCOMPRESSED_PUBLIC_KEY_PREFIX = "04";
+const ENCLAVE_TRUST_ANCHORS = {
+  // filled at fleet provisioning; verify fails closed while empty
+  [VANA_MAINNET_CHAIN_ID]: { kmsRootPubkey: "0x", appIds: [] },
+  // filled at fleet provisioning; verify fails closed while empty
+  [MOKSHA_CHAIN_ID]: { kmsRootPubkey: "0x", appIds: [] }
+};
+function userPsId(chainId, ownerAddress) {
+  const packed = (0, import_viem.encodePacked)(
+    ["string", "uint256", "address"],
+    [USER_PS_ID_DOMAIN, BigInt(chainId), (0, import_viem.getAddress)(ownerAddress)]
+  );
+  return (0, import_viem.keccak256)(packed);
+}
+function appRootPreimage(purpose, publicKey) {
+  const keyHex = publicKey.slice(2).toLowerCase();
+  return (0, import_viem.keccak256)((0, import_viem.toBytes)(`${purpose}${PREIMAGE_SEPARATOR}${keyHex}`));
+}
+function kmsIssuedPreimage(appId, appRootPublicKey) {
+  const appIdHex = appId.slice(2).toLowerCase();
+  const prefix = (0, import_viem.toBytes)(
+    `${KMS_ISSUED_PREFIX}${PREIMAGE_SEPARATOR}${appIdHex}`
+  );
+  const compressed = secp256k1.ProjectivePoint.fromHex(
+    (0, import_viem.fromHex)(appRootPublicKey, "bytes")
+  ).toRawBytes(true);
+  return (0, import_viem.keccak256)((0, import_viem.concat)([prefix, compressed]));
+}
+async function recoverChainKey(hash, signature, link) {
+  try {
+    return (await (0, import_viem.recoverPublicKey)({ hash, signature })).toLowerCase();
+  } catch {
+    throw new Error(`Invalid enclave signature chain link ${link}`);
+  }
+}
+async function verifyEnclaveIdentityEvidence(evidence, anchors) {
+  if (evidence.v !== ENCLAVE_IDENTITY_EVIDENCE_VERSION) {
+    throw new Error("Unsupported enclave identity evidence version");
+  }
+  if (!Number.isInteger(evidence.epoch) || evidence.epoch < 1) {
+    throw new Error("Invalid enclave identity epoch");
+  }
+  const derivedAddress = (0, import_accounts.publicKeyToAddress)(evidence.publicKey);
+  if ((0, import_viem.getAddress)(derivedAddress) !== (0, import_viem.getAddress)(evidence.address)) {
+    throw new Error("Enclave public key does not match its address");
+  }
+  const appRootPublicKey = await recoverChainKey(
+    appRootPreimage(evidence.purpose, evidence.publicKey),
+    evidence.signatureChain[0],
+    0
+  );
+  const kmsRootPublicKey = await recoverChainKey(
+    kmsIssuedPreimage(evidence.appId, appRootPublicKey),
+    evidence.signatureChain[1],
+    1
+  );
+  if (anchors.kmsRootPubkey === "0x") {
+    throw new Error("KMS root trust anchor is not provisioned");
+  }
+  if (kmsRootPublicKey !== anchors.kmsRootPubkey.toLowerCase()) {
+    throw new Error("KMS root public key does not match the trust anchor");
+  }
+  if ((0, import_viem.keccak256)(kmsRootPublicKey) !== evidence.kmsRootFingerprint.toLowerCase()) {
+    throw new Error("KMS root fingerprint does not match the evidence");
+  }
+  const appId = evidence.appId.toLowerCase();
+  if (!anchors.appIds.some((allowedAppId) => allowedAppId.toLowerCase() === appId)) {
+    throw new Error("Enclave app ID is not trusted");
+  }
+}
+function buildMasterSignatureDelivery(evidence, masterSignature, now = Math.floor(Date.now() / 1e3)) {
+  (0, import_derive.deriveMasterKey)(masterSignature);
+  return {
+    v: MASTER_SIGNATURE_DELIVERY_VERSION,
+    userPsId: evidence.userPsId,
+    epoch: evidence.epoch,
+    enclaveAddress: evidence.address,
+    ownerAddress: evidence.ownerAddress,
+    masterSignature,
+    issuedAt: now
+  };
+}
+function assertUncompressedKey(publicKey) {
+  const hex = publicKey.slice(2);
+  if (hex.length !== UNCOMPRESSED_PUBLIC_KEY_BYTES * 2 || !hex.startsWith(UNCOMPRESSED_PUBLIC_KEY_PREFIX) || !/^[0-9a-fA-F]+$/.test(hex)) {
+    throw new Error("Public key must be a 65-byte uncompressed secp256k1 key");
+  }
+}
+async function encryptMasterSignatureDelivery(delivery, publicKey, ecies) {
+  assertUncompressedKey(publicKey);
+  const plaintext = (0, import_viem.toBytes)(JSON.stringify(delivery));
+  const encrypted = await ecies.encrypt((0, import_viem.fromHex)(publicKey, "bytes"), plaintext);
+  return `0x${(0, import_interface.serializeECIES)(encrypted)}`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ENCLAVE_IDENTITY_EVIDENCE_VERSION,
+  ENCLAVE_TRUST_ANCHORS,
+  ENCLAVE_WALLET_PURPOSE,
+  MASTER_SIGNATURE_DELIVERY_VERSION,
+  SEALED_ENVELOPE_VERSION,
+  USER_PS_ID_DOMAIN,
+  appRootPreimage,
+  buildMasterSignatureDelivery,
+  encryptMasterSignatureDelivery,
+  kmsIssuedPreimage,
+  userPsId,
+  verifyEnclaveIdentityEvidence
+});
+//# sourceMappingURL=identity.cjs.map

package/dist/protocol/identity.cjs.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 encrypts the EIP-191 master signature to the\n * enclave public key; Gateway relays it blind; Agent decrypts and seals it.\n *\n * @category Protocol\n */\n\nimport * as secp256k1 from \"@noble/secp256k1\";\nimport {\n  concat,\n  encodePacked,\n  fromHex,\n  getAddress,\n  keccak256,\n  recoverPublicKey,\n  toBytes,\n  type Address,\n  type Hex,\n} from \"viem\";\nimport { publicKeyToAddress } from \"viem/accounts\";\nimport { serializeECIES, type ECIESProvider } from \"../crypto/ecies/interface\";\nimport { deriveMasterKey } 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\";\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\";\n\nexport type UserPsId = Hex;\n\nexport interface EnclaveIdentityEvidence {\n  v: typeof ENCLAVE_IDENTITY_EVIDENCE_VERSION;\n  userPsId: UserPsId;\n  chainId: number;\n  ownerAddress: Address;\n  epoch: number;\n  address: Address;\n  publicKey: Hex;\n  appId: Hex;\n  composeHash: Hex;\n  osImageHash?: Hex;\n  purpose: string;\n  signatureChain: [Hex, Hex];\n  quote: Hex;\n  eventLog?: string;\n  kmsRootFingerprint: Hex;\n}\n\nexport interface IdentityRequest {\n  ownerAddress: Address;\n  chainId: number;\n}\n\nexport type IdentityState = \"prepared\" | \"registered\" | \"sealed\" | \"retired\";\n\nexport interface IdentityResponse {\n  identity: EnclaveIdentityEvidence;\n  state: IdentityState;\n  created: boolean;\n  serverUrl: string;\n  serverId?: Hex;\n  serverStatus?:\n    | \"pending\"\n    | \"submitting\"\n    | \"confirmed\"\n    | \"finalized\"\n    | \"failed\";\n  sealed: boolean;\n}\n\nexport type IdentityRegistrationRequest =\n  | { version: \"v2\"; message: ServerRegistrationMessage }\n  | {\n      version: \"v3\";\n      message: ServerRegistrationMessage & { nonce: string; deadline: string };\n    };\n\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  masterSignature: Hex;\n  issuedAt: number;\n}\n\nexport interface SealedSecretSubmission {\n  userPsId: UserPsId;\n  epoch: number;\n  enclaveAddress: Address;\n  ciphertext: Hex;\n}\n\nexport interface SealedSecretResponse {\n  sealed: true;\n  secretHash: Hex;\n  sealedAt: string;\n}\n\nexport interface AesGcmBox {\n  iv: string;\n  ciphertext: string;\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\nexport interface EnclaveTrustAnchors {\n  kmsRootPubkey: Hex;\n  appIds: Hex[];\n}\n\n/** Fleet-provisioned trust anchors keyed by Vana chain ID. */\nexport const ENCLAVE_TRUST_ANCHORS: Record<number, EnclaveTrustAnchors> = {\n  // filled at fleet provisioning; verify fails closed while empty\n  [VANA_MAINNET_CHAIN_ID]: { kmsRootPubkey: \"0x\", appIds: [] },\n  // filled at fleet provisioning; verify fails closed while empty\n  [MOKSHA_CHAIN_ID]: { kmsRootPubkey: \"0x\", appIds: [] },\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\n/**\n * Builds keccak256(purpose || \":\" || hex(pubkey)) for signature-chain link 0.\n *\n * ASSUMPTION: hex(pubkey) is lowercase, without 0x, for the 65-byte key.\n * TODO(verify-against-dstack-vector): pin with a captured CVM chain\n * (dstack kms/src/crypto.rs).\n */\nexport function appRootPreimage(purpose: string, publicKey: Hex): Hex {\n  const keyHex = publicKey.slice(2).toLowerCase();\n  return keccak256(toBytes(`${purpose}${PREIMAGE_SEPARATOR}${keyHex}`));\n}\n\n/**\n * Builds the dstack KMS issuance digest for signature-chain link 1.\n *\n * ASSUMPTION: appId is lowercase hex without 0x encoded as UTF-8; the app-root\n * key is appended as 33 raw SEC1-compressed bytes.\n * TODO(verify-against-dstack-vector): pin with a captured CVM chain.\n */\nexport function kmsIssuedPreimage(appId: Hex, appRootPublicKey: Hex): Hex {\n  const appIdHex = appId.slice(2).toLowerCase();\n  const prefix = toBytes(\n    `${KMS_ISSUED_PREFIX}${PREIMAGE_SEPARATOR}${appIdHex}`,\n  );\n  const compressed = secp256k1.ProjectivePoint.fromHex(\n    fromHex(appRootPublicKey, \"bytes\"),\n  ).toRawBytes(true);\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 * @throws When any identity binding or trust check fails.\n */\nexport async function verifyEnclaveIdentityEvidence(\n  evidence: EnclaveIdentityEvidence,\n  anchors: EnclaveTrustAnchors,\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  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  if (anchors.kmsRootPubkey === \"0x\") {\n    throw new Error(\"KMS root trust anchor is not provisioned\");\n  }\n\n  if (kmsRootPublicKey !== anchors.kmsRootPubkey.toLowerCase()) {\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 plaintext delivery object.\n */\nexport function buildMasterSignatureDelivery(\n  evidence: EnclaveIdentityEvidence,\n  masterSignature: Hex,\n  now = Math.floor(Date.now() / 1000),\n): MasterSignatureDelivery {\n  deriveMasterKey(masterSignature);\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\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 * 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 */\nexport async function encryptMasterSignatureDelivery(\n  delivery: MasterSignatureDelivery,\n  publicKey: Hex,\n  ecies: ECIESProvider,\n): Promise<Hex> {\n  assertUncompressedKey(publicKey);\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":[]}