@opendatalabs/vana-sdk 3.16.0 → 3.18.0

package/dist/protocol/personal-server-write.js

@@ -0,0 +1,601 @@
+import { sha256 } from "@noble/hashes/sha2";
+import { bytesToHex, isAddress } from "viem";
+import { z } from "zod";
+import { buildWeb3SignedHeader } from "../auth/web3-signed-builder.js";
+import {
+  WriteConflictError,
+  WriteForbiddenError,
+  WriteLineageError,
+  WriteRejectedError,
+  WriteRequestError,
+  WriteSessionError,
+  WriteSessionExpiredError,
+  WriteTransportError,
+  WriteUnauthorizedError
+} from "../errors.js";
+import { toBase64 } from "../utils/encoding.js";
+import { IngestResponseSchema } from "./data-file.js";
+import {
+  assertDerivedScopeNaming,
+  deriveDataPointId,
+  isDataPointId
+} from "./lineage.js";
+import {
+  isRecord,
+  readPersonalServerErrorBody
+} from "./personal-server-error-body.js";
+import { scopeMatchesPattern } from "./scopes.js";
+import {
+  resolveWriteSigner
+} from "./write-signer.js";
+const WRITE_SESSION_PATH = "/v1/write/session";
+const WRITE_SIGNATURE_HEADER = "X-Vana-Write-Signature";
+const WRITE_METADATA_HEADER = "X-Vana-Metadata";
+const LINEAGE_FIELD = "lineage";
+const MAX_LINEAGE_SOURCES = 256;
+const WRITE_FILENAME_HEADER = "X-Filename";
+const WRITE_CONTENT_DISPOSITION_HEADER = "Content-Disposition";
+const WRITER_ATTRIBUTION_KEY = "$writtenBy";
+const LINEAGE_KEY = "$lineage";
+const RESERVED_WRITE_KEYS = [
+  WRITER_ATTRIBUTION_KEY,
+  LINEAGE_KEY
+];
+const WriteDataResultSchema = IngestResponseSchema.extend({
+  // Present when the write carried lineage: the validated, lowercased ids.
+  lineage: z.object({ sources: z.array(z.string()) }).optional()
+});
+const WriteSessionResponseSchema = z.object({
+  access_token: z.string().min(1),
+  token_type: z.string(),
+  expires_in: z.number().nonnegative(),
+  scope: z.string()
+});
+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 dataPath(scope) {
+  return `/v1/data/${encodeURIComponent(scope)}`;
+}
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+function finiteOr(value, fallback) {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+const issuedProofIats = /* @__PURE__ */ new Map();
+const issuedProofBuckets = /* @__PURE__ */ new Map();
+let issuedProofIatsPrunedAtSec = 0;
+const WEB3_SIGNED_PROOF_LIFETIME_SECONDS = 300;
+const WEB3_SIGNED_CLOCK_SKEW_SECONDS = 60;
+const PROOF_IAT_RETENTION_SECONDS = WEB3_SIGNED_PROOF_LIFETIME_SECONDS + WEB3_SIGNED_CLOCK_SKEW_SECONDS;
+const PROOF_IAT_MAX_AHEAD_SECONDS = 30;
+function pruneIssuedProofIats(nowSec) {
+  if (issuedProofIatsPrunedAtSec === nowSec) return;
+  issuedProofIatsPrunedAtSec = nowSec;
+  const cutoff = nowSec - PROOF_IAT_RETENTION_SECONDS;
+  for (const [sec, keys] of issuedProofBuckets) {
+    if (sec >= cutoff) continue;
+    for (const key of keys) issuedProofIats.delete(key);
+    issuedProofBuckets.delete(sec);
+  }
+}
+function setIssuedProofIat(key, iat, previous) {
+  if (previous !== void 0) {
+    const bucket2 = issuedProofBuckets.get(previous);
+    bucket2?.delete(key);
+    if (bucket2?.size === 0) issuedProofBuckets.delete(previous);
+  }
+  issuedProofIats.set(key, iat);
+  let bucket = issuedProofBuckets.get(iat);
+  if (bucket === void 0) {
+    bucket = /* @__PURE__ */ new Set();
+    issuedProofBuckets.set(iat, bucket);
+  }
+  bucket.add(key);
+}
+function nextProofIat(proofKey) {
+  const nowSec = Math.floor(Date.now() / 1e3);
+  pruneIssuedProofIats(nowSec);
+  const last = issuedProofIats.get(proofKey);
+  const iat = last === void 0 ? nowSec : Math.max(nowSec, last + 1);
+  setIssuedProofIat(proofKey, iat, last);
+  const waitSec = iat - nowSec - PROOF_IAT_MAX_AHEAD_SECONDS;
+  if (waitSec <= 0) return Promise.resolve(iat);
+  return sleep(waitSec * 1e3).then(() => iat);
+}
+function proofKeyFor(parts) {
+  return bytesToHex(
+    sha256(
+      new TextEncoder().encode(
+        JSON.stringify([
+          parts.aud,
+          parts.method,
+          parts.uri,
+          parts.grantId,
+          parts.signedBytes ? bytesToHex(sha256(parts.signedBytes)) : ""
+        ])
+      )
+    )
+  );
+}
+async function sendWithFreshProof(label, fetchFn, options, proofKey, build) {
+  const attempts = Math.max(1, Math.floor(finiteOr(options?.attempts, 3)));
+  let delayMs = Math.max(0, finiteOr(options?.initialDelayMs, 1e3));
+  let lastError;
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    const { url, init } = await build(await nextProofIat(proofKey));
+    try {
+      return await fetchFn(url, init);
+    } catch (err) {
+      lastError = err;
+    }
+    if (attempt < attempts - 1) {
+      await sleep(delayMs);
+      delayMs *= 2;
+    }
+  }
+  throw new WriteTransportError(
+    `${label} failed after ${attempts} attempt(s): ${errorMessage(lastError)}`,
+    attempts,
+    lastError
+  );
+}
+async function openWriteSession(params) {
+  const fetchFn = resolveFetch(params.fetch);
+  const personalServerUrl = normalizeBaseUrl(params.personalServerUrl);
+  const audience = params.audience ?? personalServerUrl;
+  const signer = resolveWriteSigner(params.signer, { account: params.account });
+  const response = await sendWithFreshProof(
+    "Write session handshake",
+    fetchFn,
+    params.retry,
+    proofKeyFor({
+      aud: audience,
+      method: "POST",
+      uri: WRITE_SESSION_PATH,
+      grantId: params.grantId
+    }),
+    async (iat) => {
+      const headers = new Headers(params.headers);
+      headers.set(
+        "Authorization",
+        await buildWeb3SignedHeader({
+          signMessage: signer.signMessage,
+          aud: audience,
+          method: "POST",
+          uri: WRITE_SESSION_PATH,
+          grantId: params.grantId,
+          iat
+        })
+      );
+      return {
+        url: `${personalServerUrl}${WRITE_SESSION_PATH}`,
+        init: { method: "POST", headers }
+      };
+    }
+  );
+  const mintedAt = Date.now();
+  if (!response.ok) {
+    const { errorCode, message, details } = await readPersonalServerErrorBody(response);
+    throw new WriteSessionError(
+      message ?? `Write session handshake failed: ${response.status} ${response.statusText}`,
+      response.status,
+      errorCode,
+      details
+    );
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch (err) {
+    throw new WriteSessionError(
+      "Write session response is not JSON",
+      response.status,
+      null,
+      { cause: errorMessage(err) }
+    );
+  }
+  const parsed = WriteSessionResponseSchema.safeParse(body);
+  if (!parsed.success) {
+    throw new WriteSessionError(
+      "Write session response is not a session",
+      response.status,
+      null,
+      { issues: parsed.error.issues }
+    );
+  }
+  if (parsed.data.token_type.toLowerCase() !== "bearer") {
+    throw new WriteSessionError(
+      `Write session token type is not Bearer: ${parsed.data.token_type}`,
+      response.status
+    );
+  }
+  return {
+    personalServerUrl,
+    audience,
+    grantId: params.grantId,
+    accessToken: parsed.data.access_token,
+    expiresAt: mintedAt + parsed.data.expires_in * 1e3,
+    writeScopes: parsed.data.scope.split(" ").filter((s) => s.length > 0),
+    signer
+  };
+}
+function isWriteSession(value) {
+  if (!isRecord(value)) return false;
+  const signer = value.signer;
+  return typeof value.personalServerUrl === "string" && typeof value.audience === "string" && typeof value.grantId === "string" && typeof value.accessToken === "string" && value.accessToken.length > 0 && typeof value.expiresAt === "number" && Number.isFinite(value.expiresAt) && Array.isArray(value.writeScopes) && value.writeScopes.every((scope) => typeof scope === "string") && isRecord(signer) && typeof signer.signMessage === "function";
+}
+function sessionCoversScope(session, scope) {
+  if (!isRecord(session) || !Array.isArray(session.writeScopes) || !session.writeScopes.every((pattern) => typeof pattern === "string")) {
+    throw new WriteRequestError("session must come from openWriteSession");
+  }
+  return session.writeScopes.some(
+    (pattern) => scopeMatchesPattern(scope, pattern)
+  );
+}
+function normalizeBinaryMimeType(contentType) {
+  if (!contentType) return "application/octet-stream";
+  return contentType.split(";")[0].trim() || "application/octet-stream";
+}
+function parseWriteMetadataHeader(value) {
+  if (value === null) return void 0;
+  const trimmed = value.trim();
+  if (trimmed === "") return void 0;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return value;
+  }
+}
+function encodeWriteMetadataHeader(metadata) {
+  let json;
+  try {
+    json = JSON.stringify(metadata);
+  } catch (err) {
+    throw new WriteRequestError(
+      `metadata is not JSON-serialisable: ${errorMessage(err)}`
+    );
+  }
+  if (typeof json !== "string") {
+    throw new WriteRequestError("metadata must serialise to JSON");
+  }
+  return json.replace(
+    /[\u007f-\uffff]/g,
+    (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`
+  );
+}
+function binaryWriteSignedBytes(input) {
+  const metadata = parseWriteMetadataHeader(input.metadataHeader ?? null);
+  const record = {
+    $binary: true,
+    mimeType: normalizeBinaryMimeType(input.contentType),
+    ...input.filename ? { filename: input.filename } : {},
+    sizeBytes: input.bytes.length,
+    contentHash: bytesToHex(sha256(input.bytes)),
+    encoding: "base64",
+    content: toBase64(input.bytes),
+    ...metadata !== void 0 ? { metadata } : {}
+  };
+  return new TextEncoder().encode(JSON.stringify(record));
+}
+const PRINTABLE_ASCII = /^[\x20-\x7e]*$/;
+function setFilenameHeader(headers, filename) {
+  if (PRINTABLE_ASCII.test(filename)) {
+    headers.set(WRITE_FILENAME_HEADER, filename);
+    return;
+  }
+  headers.set(
+    WRITE_CONTENT_DISPOSITION_HEADER,
+    `attachment; filename*=UTF-8''${encodeURIComponent(filename)}`
+  );
+}
+function assertNoReservedKeys(value, where) {
+  for (const key of RESERVED_WRITE_KEYS) {
+    if (Object.prototype.hasOwnProperty.call(value, key)) {
+      throw new WriteRequestError(
+        `${where} must not contain the reserved ${key} key; the Personal Server stamps it`,
+        { key }
+      );
+    }
+  }
+}
+function isLineagePair(value) {
+  return isRecord(value) && typeof value.ownerAddress === "string" && typeof value.scope === "string";
+}
+function normalizeLineage(lineage, derivedScope) {
+  if (!Array.isArray(lineage)) {
+    throw new WriteRequestError("lineage must be an array of data point ids");
+  }
+  if (lineage.length > MAX_LINEAGE_SOURCES) {
+    throw new WriteRequestError(
+      `lineage lists ${lineage.length} sources; the maximum is ${MAX_LINEAGE_SOURCES}`,
+      { max: MAX_LINEAGE_SOURCES, count: lineage.length }
+    );
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const sources = [];
+  const sourceScopes = [];
+  const ownIds = /* @__PURE__ */ new Set();
+  for (const entry of lineage) {
+    let id;
+    if (isLineagePair(entry)) {
+      if (!isAddress(entry.ownerAddress, { strict: false })) {
+        throw new WriteRequestError(
+          "lineage source ownerAddress must be an EVM address",
+          { ownerAddress: entry.ownerAddress }
+        );
+      }
+      if (entry.scope.length === 0) {
+        throw new WriteRequestError("lineage source scope is required");
+      }
+      id = deriveDataPointId(entry.ownerAddress, entry.scope);
+      sourceScopes.push(entry.scope);
+      ownIds.add(deriveDataPointId(entry.ownerAddress, derivedScope));
+    } else if (isDataPointId(entry)) {
+      id = entry;
+    } else {
+      throw new WriteRequestError(
+        "lineage entries must be 32-byte hex data point ids or { ownerAddress, scope } pairs",
+        { entry }
+      );
+    }
+    const normalized = id.toLowerCase();
+    if (seen.has(normalized)) {
+      throw new WriteRequestError("lineage must not repeat a data point id", {
+        dataPointId: normalized
+      });
+    }
+    seen.add(normalized);
+    sources.push(normalized);
+  }
+  for (const own of ownIds) {
+    if (seen.has(own)) {
+      throw new WriteRequestError(
+        "lineage must not cite the record's own data point",
+        { dataPointId: own, scope: derivedScope }
+      );
+    }
+  }
+  assertDerivedScopeNaming(derivedScope, sourceScopes);
+  return sources;
+}
+function assertNoLineageField(value, where) {
+  if (Object.prototype.hasOwnProperty.call(value, LINEAGE_FIELD)) {
+    throw new WriteRequestError(
+      `${where}.${LINEAGE_FIELD} is reserved; pass sources through the lineage option`
+    );
+  }
+}
+function buildMetadataHeader(metadata, sources) {
+  if (metadata !== void 0) {
+    if (!isRecord(metadata)) {
+      throw new WriteRequestError("metadata must be a plain object");
+    }
+    assertNoReservedKeys(metadata, "metadata");
+    assertNoLineageField(metadata, "metadata");
+  }
+  if (metadata === void 0 && sources === void 0) return void 0;
+  return encodeWriteMetadataHeader({
+    ...metadata ?? {},
+    ...sources !== void 0 ? { [LINEAGE_FIELD]: sources } : {}
+  });
+}
+function prepareWrite(params) {
+  if (params.binary !== void 0 && params.data !== void 0) {
+    throw new WriteRequestError("Pass either data or binary, not both");
+  }
+  const rawLineage = params.lineage;
+  const sources = rawLineage === void 0 || rawLineage === null ? void 0 : normalizeLineage(rawLineage, params.scope);
+  if (params.binary !== void 0) {
+    const { bytes, contentType, filename } = params.binary;
+    if (!(bytes instanceof Uint8Array)) {
+      throw new WriteRequestError("binary.bytes must be a Uint8Array");
+    }
+    if (typeof contentType !== "string" || contentType.trim() === "") {
+      throw new WriteRequestError("binary.contentType is required");
+    }
+    if (filename !== void 0) {
+      if (typeof filename !== "string") {
+        throw new WriteRequestError("binary.filename must be a string");
+      }
+      if (filename !== filename.trim()) {
+        throw new WriteRequestError(
+          "binary.filename must not have leading or trailing whitespace"
+        );
+      }
+    }
+    const metadataHeader = buildMetadataHeader(params.metadata, sources);
+    return {
+      body: bytes,
+      signedBytes: binaryWriteSignedBytes({
+        bytes,
+        contentType,
+        filename,
+        metadataHeader
+      }),
+      contentType,
+      filename,
+      metadataHeader
+    };
+  }
+  if (params.data === void 0) {
+    throw new WriteRequestError("Pass data (a JSON object) or binary");
+  }
+  if (!isRecord(params.data)) {
+    throw new WriteRequestError("data must be a plain JSON object");
+  }
+  if (params.metadata !== void 0) {
+    throw new WriteRequestError(
+      "metadata applies to binary writes; put fields to store inside data"
+    );
+  }
+  assertNoReservedKeys(params.data, "data");
+  assertNoLineageField(params.data, "data");
+  const record = sources === void 0 ? params.data : { ...params.data, [LINEAGE_FIELD]: sources };
+  let text;
+  try {
+    text = JSON.stringify(record);
+  } catch (err) {
+    throw new WriteRequestError(
+      `data is not JSON-serialisable: ${errorMessage(err)}`
+    );
+  }
+  if (typeof text !== "string" || !text.startsWith("{")) {
+    throw new WriteRequestError("data must serialise to a JSON object");
+  }
+  const body = new TextEncoder().encode(text);
+  return {
+    body,
+    signedBytes: body,
+    contentType: "application/json"
+  };
+}
+async function writeErrorFromResponse(response) {
+  const { errorCode, message, details } = await readPersonalServerErrorBody(response);
+  const text = message ?? `Personal Server write failed: ${response.status} ${response.statusText}`;
+  if (response.status === 422 || errorCode?.startsWith("LINEAGE_")) {
+    return new WriteLineageError(text, response.status, errorCode, details);
+  }
+  switch (response.status) {
+    case 401:
+      return new WriteUnauthorizedError(text, errorCode, details);
+    case 403:
+      return new WriteForbiddenError(text, errorCode, details);
+    case 409:
+      return new WriteConflictError(text, errorCode, details);
+    default:
+      return new WriteRejectedError(text, response.status, errorCode, details);
+  }
+}
+async function writeData(params) {
+  const { session } = params;
+  if (!isWriteSession(session)) {
+    throw new WriteRequestError("session must come from openWriteSession");
+  }
+  const fetchFn = resolveFetch(params.fetch);
+  if (typeof params.scope !== "string" || params.scope.length === 0) {
+    throw new WriteRequestError("scope is required");
+  }
+  const prepared = prepareWrite(params);
+  if (Date.now() >= session.expiresAt) {
+    throw new WriteSessionExpiredError(
+      "Write session has expired; open a new session",
+      { grantId: session.grantId, expiresAt: session.expiresAt }
+    );
+  }
+  const path = dataPath(params.scope);
+  const response = await sendWithFreshProof(
+    `Write to ${params.scope}`,
+    fetchFn,
+    params.retry,
+    proofKeyFor({
+      aud: session.audience,
+      method: "POST",
+      uri: path,
+      grantId: session.grantId,
+      signedBytes: prepared.signedBytes
+    }),
+    async (iat) => {
+      const headers = new Headers(params.headers);
+      headers.set("Content-Type", prepared.contentType);
+      headers.set("Authorization", `Bearer ${session.accessToken}`);
+      if (prepared.filename) {
+        setFilenameHeader(headers, prepared.filename);
+      }
+      if (prepared.metadataHeader !== void 0) {
+        headers.set(WRITE_METADATA_HEADER, prepared.metadataHeader);
+      }
+      headers.set(
+        WRITE_SIGNATURE_HEADER,
+        await buildWeb3SignedHeader({
+          signMessage: session.signer.signMessage,
+          aud: session.audience,
+          method: "POST",
+          uri: path,
+          body: prepared.signedBytes,
+          grantId: session.grantId,
+          iat
+        })
+      );
+      return {
+        url: `${session.personalServerUrl}${path}`,
+        init: {
+          method: "POST",
+          headers,
+          body: prepared.body
+        }
+      };
+    }
+  );
+  if (!response.ok) {
+    throw await writeErrorFromResponse(response);
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch (err) {
+    throw new WriteRejectedError(
+      "Personal Server write response is not JSON",
+      response.status,
+      null,
+      { cause: errorMessage(err) }
+    );
+  }
+  const parsed = WriteDataResultSchema.safeParse(body);
+  if (!parsed.success) {
+    throw new WriteRejectedError(
+      "Personal Server write response is not an ingest result",
+      response.status,
+      null,
+      { issues: parsed.error.issues }
+    );
+  }
+  return parsed.data;
+}
+async function writePersonalServerData(params) {
+  const session = await openWriteSession({
+    personalServerUrl: params.personalServerUrl,
+    signer: params.signer,
+    grantId: params.grantId,
+    account: params.account,
+    audience: params.audience,
+    fetch: params.fetch,
+    headers: params.headers,
+    retry: params.retry
+  });
+  const writeParams = { ...params, session };
+  const result = await writeData(writeParams);
+  return { ...result, session };
+}
+export {
+  LINEAGE_FIELD,
+  LINEAGE_KEY,
+  MAX_LINEAGE_SOURCES,
+  RESERVED_WRITE_KEYS,
+  WRITER_ATTRIBUTION_KEY,
+  WRITE_CONTENT_DISPOSITION_HEADER,
+  WRITE_FILENAME_HEADER,
+  WRITE_METADATA_HEADER,
+  WRITE_SESSION_PATH,
+  WRITE_SIGNATURE_HEADER,
+  binaryWriteSignedBytes,
+  encodeWriteMetadataHeader,
+  normalizeBinaryMimeType,
+  openWriteSession,
+  parseWriteMetadataHeader,
+  sessionCoversScope,
+  writeData,
+  writePersonalServerData
+};
+//# sourceMappingURL=personal-server-write.js.map