@opendatalabs/vana-sdk 3.15.0 → 3.17.0

package/dist/protocol/lineage.cjs

@@ -0,0 +1,287 @@
+"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 lineage_exports = {};
+__export(lineage_exports, {
+  LineageEntrySchema: () => LineageEntrySchema,
+  LineageGraphSchema: () => LineageGraphSchema,
+  LineageNodeSchema: () => LineageNodeSchema,
+  RedactedLineageNodeSchema: () => RedactedLineageNodeSchema,
+  assertDerivedScopeNaming: () => assertDerivedScopeNaming,
+  deriveDataPointId: () => deriveDataPointId,
+  derivedScopeViolatesNaming: () => derivedScopeViolatesNaming,
+  gatewayLineagePath: () => gatewayLineagePath,
+  getGatewayLineage: () => getGatewayLineage,
+  getLineage: () => getLineage,
+  getPersonalServerLineage: () => getPersonalServerLineage,
+  isDataPointId: () => isDataPointId,
+  isRedactedLineageNode: () => isRedactedLineageNode,
+  personalServerLineagePath: () => personalServerLineagePath,
+  scopeNamespace: () => scopeNamespace
+});
+module.exports = __toCommonJS(lineage_exports);
+var import_viem = require("viem");
+var import_zod = require("zod");
+var import_web3_signed_builder = require("../auth/web3-signed-builder");
+var import_errors = require("../errors");
+var import_personal_server_error_body = require("./personal-server-error-body");
+var import_write_signer = require("./write-signer");
+const DATA_POINT_ID_PATTERN = /^0x[0-9a-fA-F]{64}$/;
+function isDataPointId(value) {
+  return typeof value === "string" && DATA_POINT_ID_PATTERN.test(value);
+}
+function deriveDataPointId(ownerAddress, scope) {
+  if (!(0, import_viem.isAddress)(ownerAddress, { strict: false })) {
+    throw new Error(
+      `ownerAddress is not an EVM address: ${String(ownerAddress)}`
+    );
+  }
+  return (0, import_viem.keccak256)(
+    (0, import_viem.encodeAbiParameters)(
+      [
+        { name: "ownerAddress", type: "address" },
+        { name: "scope", type: "string" }
+      ],
+      [ownerAddress, scope]
+    )
+  );
+}
+const DataPointIdSchema = import_zod.z.string().regex(DATA_POINT_ID_PATTERN).transform((value) => value.toLowerCase());
+const VERSION_PATTERN = /^[1-9]\d*$/;
+const NODE_VERSION_PATTERN = /^(0|[1-9]\d*)$/;
+const VersionSchema = import_zod.z.union([import_zod.z.string(), import_zod.z.number()]).transform(String).refine((value) => NODE_VERSION_PATTERN.test(value), {
+  message: "version must be a decimal integer"
+});
+const ViewVersionSchema = VersionSchema.refine(
+  (value) => VERSION_PATTERN.test(value),
+  { message: "version must be a positive decimal integer" }
+);
+function scopeNamespace(scope) {
+  const dot = scope.indexOf(".");
+  return dot === -1 ? scope : scope.slice(0, dot);
+}
+function derivedScopeViolatesNaming(derivedScope, sourceScope) {
+  return scopeNamespace(derivedScope) === scopeNamespace(sourceScope);
+}
+function assertDerivedScopeNaming(derivedScope, sourceScopes) {
+  for (const sourceScope of sourceScopes) {
+    if (derivedScopeViolatesNaming(derivedScope, sourceScope)) {
+      throw new import_errors.WriteRequestError(
+        `Derived scope ${derivedScope} must not share its first segment with source scope ${sourceScope}; put derivatives in the app's own namespace`,
+        { scope: derivedScope, sourceScope }
+      );
+    }
+  }
+}
+const LineageNodeSchema = import_zod.z.object({
+  dataPointId: DataPointIdSchema,
+  scope: import_zod.z.string(),
+  /**
+   * The node's current version, decimal string; `"0"` for a source that no
+   * longer resolves to a registered data point.
+   */
+  version: VersionSchema,
+  /** The node's tombstone time, or `null` when live. */
+  deletedAt: import_zod.z.string().nullable()
+});
+const RedactedLineageNodeSchema = import_zod.z.object({
+  dataPointId: DataPointIdSchema,
+  redacted: import_zod.z.literal(true)
+});
+const LineageEntrySchema = import_zod.z.union([
+  RedactedLineageNodeSchema,
+  LineageNodeSchema
+]);
+const LineageGraphSchema = import_zod.z.object({
+  dataPointId: DataPointIdSchema,
+  /** The data point owner; every node in the view belongs to it. */
+  ownerAddress: import_zod.z.string().optional(),
+  scope: import_zod.z.string(),
+  /**
+   * The derived record's version whose lineage is shown: the requested one,
+   * else the current one, else (current is a tombstone) the last version
+   * that carried lineage.
+   */
+  version: ViewVersionSchema,
+  deletedAt: import_zod.z.string().nullable(),
+  sources: import_zod.z.array(LineageEntrySchema),
+  derivatives: import_zod.z.array(LineageEntrySchema),
+  /** `true` when `derivatives` was cut at the server's cap (1000). */
+  derivativesTruncated: import_zod.z.boolean().optional()
+});
+function isRedactedLineageNode(entry) {
+  return "redacted" in entry && entry.redacted === true;
+}
+function personalServerLineagePath(scope, version) {
+  return `/v1/data/${encodeURIComponent(scope)}/lineage${version === void 0 ? "" : `/${String(version)}`}`;
+}
+function gatewayLineagePath(dataPointId, version) {
+  return `/v1/data/${dataPointId.toLowerCase()}/lineage${version === void 0 ? "" : `/${String(version)}`}`;
+}
+function normalizeBaseUrl(url) {
+  return url.replace(/\/+$/, "");
+}
+function resolveFetch(fetchFn) {
+  const resolved = fetchFn ?? globalThis.fetch;
+  if (resolved === void 0) {
+    throw new import_errors.LineageReadError("No fetch implementation available");
+  }
+  return resolved;
+}
+function normalizeVersion(version) {
+  if (version === void 0) return void 0;
+  const text = String(version);
+  if (!VERSION_PATTERN.test(text)) {
+    throw new import_errors.LineageReadError(
+      "version must be a positive decimal integer",
+      void 0,
+      "INVALID_VERSION",
+      { version }
+    );
+  }
+  return text;
+}
+async function lineageReadFailure(source, response) {
+  const { errorCode, message, details } = await (0, import_personal_server_error_body.readPersonalServerErrorBody)(response);
+  return new import_errors.LineageReadError(
+    message ?? `${source} lineage read failed: ${response.status} ${response.statusText}`,
+    response.status,
+    errorCode,
+    details
+  );
+}
+async function parseLineageGraph(source, response) {
+  let body;
+  try {
+    body = await response.json();
+  } catch (err) {
+    throw new import_errors.LineageReadError(
+      `${source} lineage response is not JSON`,
+      response.status,
+      null,
+      { cause: err instanceof Error ? err.message : String(err) }
+    );
+  }
+  const envelope = (0, import_personal_server_error_body.isRecord)(body) && (0, import_personal_server_error_body.isRecord)(body.data) ? body : void 0;
+  const parsed = LineageGraphSchema.safeParse(envelope?.data ?? body);
+  if (!parsed.success) {
+    throw new import_errors.LineageReadError(
+      `${source} lineage response is not a lineage view`,
+      response.status,
+      null,
+      { issues: parsed.error.issues }
+    );
+  }
+  const proof = (0, import_personal_server_error_body.isRecord)(envelope?.proof) ? envelope.proof : void 0;
+  return proof === void 0 ? parsed.data : { ...parsed.data, proof };
+}
+async function sendLineageRead(source, fetchFn, url, headers) {
+  let response;
+  try {
+    response = await fetchFn(url, { method: "GET", headers });
+  } catch (err) {
+    throw new import_errors.LineageReadError(
+      `${source} lineage read failed: ${err instanceof Error ? err.message : String(err)}`,
+      void 0,
+      null,
+      { cause: err instanceof Error ? err.message : String(err) }
+    );
+  }
+  if (!response.ok) {
+    throw await lineageReadFailure(source, response);
+  }
+  return parseLineageGraph(source, response);
+}
+async function getPersonalServerLineage(params) {
+  const fetchFn = resolveFetch(params.fetch);
+  const baseUrl = normalizeBaseUrl(params.personalServerUrl);
+  const audience = params.audience ?? baseUrl;
+  const signer = (0, import_write_signer.resolveWriteSigner)(params.signer, { account: params.account });
+  const path = personalServerLineagePath(
+    params.scope,
+    normalizeVersion(params.version)
+  );
+  const headers = new Headers(params.headers);
+  headers.set(
+    "Authorization",
+    await (0, import_web3_signed_builder.buildWeb3SignedHeader)({
+      signMessage: signer.signMessage,
+      aud: audience,
+      method: "GET",
+      uri: path,
+      grantId: params.grantId
+    })
+  );
+  return sendLineageRead(
+    "Personal Server",
+    fetchFn,
+    `${baseUrl}${path}`,
+    headers
+  );
+}
+async function getGatewayLineage(params) {
+  if (!isDataPointId(params.dataPointId)) {
+    throw new import_errors.LineageReadError(
+      "dataPointId must be a 32-byte hex string (see deriveDataPointId)",
+      void 0,
+      "INVALID_DATA_POINT_ID",
+      { dataPointId: params.dataPointId }
+    );
+  }
+  const fetchFn = resolveFetch(params.fetch);
+  const baseUrl = normalizeBaseUrl(params.gatewayUrl);
+  const signer = (0, import_write_signer.resolveWriteSigner)(params.signer, { account: params.account });
+  const uri = gatewayLineagePath(
+    params.dataPointId,
+    normalizeVersion(params.version)
+  );
+  const headers = new Headers(params.headers);
+  headers.set(
+    "Authorization",
+    await (0, import_web3_signed_builder.buildWeb3SignedHeader)({
+      signMessage: signer.signMessage,
+      aud: baseUrl,
+      method: "GET",
+      uri,
+      grantId: params.grantId?.toLowerCase()
+    })
+  );
+  return sendLineageRead("Gateway", fetchFn, `${baseUrl}${uri}`, headers);
+}
+function getLineage(params) {
+  return "personalServerUrl" in params ? getPersonalServerLineage(params) : getGatewayLineage(params);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  LineageEntrySchema,
+  LineageGraphSchema,
+  LineageNodeSchema,
+  RedactedLineageNodeSchema,
+  assertDerivedScopeNaming,
+  deriveDataPointId,
+  derivedScopeViolatesNaming,
+  gatewayLineagePath,
+  getGatewayLineage,
+  getLineage,
+  getPersonalServerLineage,
+  isDataPointId,
+  isRedactedLineageNode,
+  personalServerLineagePath,
+  scopeNamespace
+});
+//# sourceMappingURL=lineage.cjs.map

package/dist/protocol/lineage.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/protocol/lineage.ts"],"sourcesContent":["/**\n * Derivative lineage: which data points a record was derived from, and which\n * records were derived from it.\n *\n * @remarks\n * A data point is addressed by `keccak256(abi.encode(address owner, string\n * scope))` ({@link deriveDataPointId}). A builder writing a derivative names\n * its sources through the `lineage` option of {@link writeData}; the Personal\n * Server stores them under the reserved `$lineage` key and both the Personal\n * Server (`GET /v1/data/:scope/lineage[/:version]`) and the gateway\n * (`GET /v1/data/:dataPointId/lineage[/:version]`) answer the resulting view.\n * Nodes the caller holds no grant for come back as\n * `{ dataPointId, redacted: true }`; a source that no longer resolves comes\n * back with `version: \"0\"`.\n *\n * A derived scope must not share its first dot-segment with any source scope\n * (a grant on `chatgpt.*` must never read a derivative of\n * `chatgpt.conversations`): see {@link assertDerivedScopeNaming}.\n *\n * @category Protocol\n */\n\nimport {\n  encodeAbiParameters,\n  isAddress,\n  keccak256,\n  type Address,\n  type Hex,\n} from \"viem\";\nimport { z } from \"zod\";\nimport { buildWeb3SignedHeader } from \"../auth/web3-signed-builder\";\nimport { LineageReadError, WriteRequestError } from \"../errors\";\nimport {\n  isRecord,\n  readPersonalServerErrorBody,\n} from \"./personal-server-error-body\";\nimport {\n  resolveWriteSigner,\n  type ResolveWriteSignerOptions,\n  type WriteSignerSource,\n} from \"./write-signer\";\n\nconst DATA_POINT_ID_PATTERN = /^0x[0-9a-fA-F]{64}$/;\n\n/** `true` when `value` is a 32-byte hex data point id. */\nexport function isDataPointId(value: unknown): value is Hex {\n  return typeof value === \"string\" && DATA_POINT_ID_PATTERN.test(value);\n}\n\n/**\n * Derive the DataRegistryV2 data point id for an owner and scope:\n * `keccak256(abi.encode(address ownerAddress, string scope))`.\n *\n * @param ownerAddress - The data owner (the Personal Server owner).\n * @param scope - The scope the data point is stored under.\n * @returns The 32-byte id, lowercase hex.\n * @throws Error when `ownerAddress` is not an EVM address.\n */\nexport function deriveDataPointId(ownerAddress: Address, scope: string): Hex {\n  if (!isAddress(ownerAddress, { strict: false })) {\n    throw new Error(\n      `ownerAddress is not an EVM address: ${String(ownerAddress)}`,\n    );\n  }\n  return keccak256(\n    encodeAbiParameters(\n      [\n        { name: \"ownerAddress\", type: \"address\" },\n        { name: \"scope\", type: \"string\" },\n      ],\n      [ownerAddress, scope],\n    ),\n  );\n}\n\nconst DataPointIdSchema = z\n  .string()\n  .regex(DATA_POINT_ID_PATTERN)\n  .transform((value) => value.toLowerCase() as Hex);\n\nconst VERSION_PATTERN = /^[1-9]\\d*$/;\nconst NODE_VERSION_PATTERN = /^(0|[1-9]\\d*)$/;\n\n// Versions are decimal integers, strings on the wire; a numeric value is\n// normalised to the same representation. A node's version may be \"0\": a\n// source that no longer resolves to a registered data point.\nconst VersionSchema = z\n  .union([z.string(), z.number()])\n  .transform(String)\n  .refine((value) => NODE_VERSION_PATTERN.test(value), {\n    message: \"version must be a decimal integer\",\n  });\n// The view's own version is a registered one: always positive.\nconst ViewVersionSchema = VersionSchema.refine(\n  (value) => VERSION_PATTERN.test(value),\n  { message: \"version must be a positive decimal integer\" },\n);\n\n/** First dot-segment of a scope (`chatgpt` for `chatgpt.conversations`). */\nexport function scopeNamespace(scope: string): string {\n  const dot = scope.indexOf(\".\");\n  return dot === -1 ? scope : scope.slice(0, dot);\n}\n\n/**\n * The naming rule: a derived scope and a source scope must not share their\n * first dot-segment, because a `prefix.*` grant would then cover both and\n * leak across the lineage edge. Mirrors the Personal Server's check\n * (`LINEAGE_SCOPE_UNDER_SOURCE_PREFIX`).\n */\nexport function derivedScopeViolatesNaming(\n  derivedScope: string,\n  sourceScope: string,\n): boolean {\n  return scopeNamespace(derivedScope) === scopeNamespace(sourceScope);\n}\n\n/**\n * Throw when `derivedScope` shares its first dot-segment with any source\n * scope (see {@link derivedScopeViolatesNaming}).\n *\n * @throws {WriteRequestError} Naming the offending source scope in `details`.\n */\nexport function assertDerivedScopeNaming(\n  derivedScope: string,\n  sourceScopes: readonly string[],\n): void {\n  for (const sourceScope of sourceScopes) {\n    if (derivedScopeViolatesNaming(derivedScope, sourceScope)) {\n      throw new WriteRequestError(\n        `Derived scope ${derivedScope} must not share its first segment with source scope ${sourceScope}; put derivatives in the app's own namespace`,\n        { scope: derivedScope, sourceScope },\n      );\n    }\n  }\n}\n\nexport const LineageNodeSchema = z.object({\n  dataPointId: DataPointIdSchema,\n  scope: z.string(),\n  /**\n   * The node's current version, decimal string; `\"0\"` for a source that no\n   * longer resolves to a registered data point.\n   */\n  version: VersionSchema,\n  /** The node's tombstone time, or `null` when live. */\n  deletedAt: z.string().nullable(),\n});\n\nexport const RedactedLineageNodeSchema = z.object({\n  dataPointId: DataPointIdSchema,\n  redacted: z.literal(true),\n});\n\nexport const LineageEntrySchema = z.union([\n  RedactedLineageNodeSchema,\n  LineageNodeSchema,\n]);\n\nexport const LineageGraphSchema = z.object({\n  dataPointId: DataPointIdSchema,\n  /** The data point owner; every node in the view belongs to it. */\n  ownerAddress: z.string().optional(),\n  scope: z.string(),\n  /**\n   * The derived record's version whose lineage is shown: the requested one,\n   * else the current one, else (current is a tombstone) the last version\n   * that carried lineage.\n   */\n  version: ViewVersionSchema,\n  deletedAt: z.string().nullable(),\n  sources: z.array(LineageEntrySchema),\n  derivatives: z.array(LineageEntrySchema),\n  /** `true` when `derivatives` was cut at the server's cap (1000). */\n  derivativesTruncated: z.boolean().optional(),\n});\n\n/** A lineage node the caller is allowed to see. */\nexport type LineageNode = z.infer<typeof LineageNodeSchema>;\n\n/** A lineage node the caller holds no grant for: only its id is disclosed. */\nexport type RedactedLineageNode = z.infer<typeof RedactedLineageNodeSchema>;\n\n/** One entry of a lineage graph. Narrow with {@link isRedactedLineageNode}. */\nexport type LineageEntry = z.infer<typeof LineageEntrySchema>;\n\n/** The lineage view of one data point (the `data` of the response). */\nexport type LineageGraph = z.infer<typeof LineageGraphSchema>;\n\n/** A lineage read: the view plus the gateway's attestation over it. */\nexport interface LineageReadResult extends LineageGraph {\n  /**\n   * The gateway `proof` (`GatewayAttestation` over the served view, so a\n   * redacted view verifies on its own). Passed through as received; absent\n   * when the server sent none.\n   */\n  proof?: Record<string, unknown>;\n}\n\n/** `true` when the entry was redacted (the caller holds no grant for it). */\nexport function isRedactedLineageNode(\n  entry: LineageEntry,\n): entry is RedactedLineageNode {\n  return \"redacted\" in entry && entry.redacted === true;\n}\n\n/**\n * The Personal Server lineage path: `/v1/data/:scope/lineage[/:version]`.\n * The version is a path segment (a query string is refused by the server),\n * so the signed `uri` covers the whole request.\n */\nexport function personalServerLineagePath(\n  scope: string,\n  version?: string | number,\n): string {\n  return `/v1/data/${encodeURIComponent(scope)}/lineage${version === undefined ? \"\" : `/${String(version)}`}`;\n}\n\n/**\n * The gateway lineage path: `/v1/data/<id lowercase>/lineage[/:version]`,\n * what the request is signed over and sent to. The grant view is the signed\n * `grantId` claim, never a query parameter.\n */\nexport function gatewayLineagePath(\n  dataPointId: Hex,\n  version?: string | number,\n): string {\n  return `/v1/data/${dataPointId.toLowerCase()}/lineage${version === undefined ? \"\" : `/${String(version)}`}`;\n}\n\ninterface LineageRequestOptions {\n  /**\n   * Read the lineage as of this version (a positive decimal integer);\n   * omitted = the current version, or the last version that carried lineage\n   * when the current one is a tombstone.\n   */\n  version?: string | number;\n  /** `fetch` to use; defaults to `globalThis.fetch`. */\n  fetch?: typeof fetch;\n  /** Extra request headers. */\n  headers?: HeadersInit;\n}\n\n/** Lineage read against the Personal Server holding the record. */\nexport interface PersonalServerLineageParams extends LineageRequestOptions {\n  /** Personal Server origin, e.g. `https://ps.example.com`. */\n  personalServerUrl: string;\n  /** The scope whose lineage to read. */\n  scope: string;\n  /** A grant covering the scope, sent as the signed `grantId` claim. */\n  grantId: string;\n  /** Builder key: a viem `LocalAccount`, `WalletClient`, or `{ signMessage }`. */\n  signer: WriteSignerSource;\n  /** Account for a viem wallet client without a hoisted account. */\n  account?: ResolveWriteSignerOptions[\"account\"];\n  /** Web3Signed audience; defaults to `personalServerUrl`. */\n  audience?: string;\n}\n\n/** Lineage read against the gateway, by data point id. */\nexport interface GatewayLineageParams extends LineageRequestOptions {\n  /** Gateway origin, e.g. `https://dp-rpc.vana.org`. */\n  gatewayUrl: string;\n  /** The data point whose lineage to read (see {@link deriveDataPointId}). */\n  dataPointId: Hex;\n  /**\n   * The key the request is signed with (Web3Signed, audience = the gateway\n   * origin). The signer decides the view: the owner or one of its servers\n   * gets the full view; a registered builder holding a live grant covering\n   * the data point's scope gets that grant's view; anyone else is refused.\n   */\n  signer: WriteSignerSource;\n  /** Account for a viem wallet client without a hoisted account. */\n  account?: ResolveWriteSignerOptions[\"account\"];\n  /**\n   * The grant whose view to read, sent lowercased as the signed `grantId`\n   * claim (never as a query parameter). An owner or server uses it to fetch\n   * the view a builder's grant sees; a builder needs it to see anything.\n   */\n  grantId?: string;\n}\n\nexport type GetLineageParams =\n  | PersonalServerLineageParams\n  | GatewayLineageParams;\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 LineageReadError(\"No fetch implementation available\");\n  }\n  return resolved;\n}\n\nfunction normalizeVersion(\n  version: string | number | undefined,\n): string | undefined {\n  if (version === undefined) return undefined;\n  const text = String(version);\n  if (!VERSION_PATTERN.test(text)) {\n    throw new LineageReadError(\n      \"version must be a positive decimal integer\",\n      undefined,\n      \"INVALID_VERSION\",\n      { version },\n    );\n  }\n  return text;\n}\n\nasync function lineageReadFailure(\n  source: string,\n  response: Response,\n): Promise<LineageReadError> {\n  const { errorCode, message, details } =\n    await readPersonalServerErrorBody(response);\n  return new LineageReadError(\n    message ??\n      `${source} lineage read failed: ${response.status} ${response.statusText}`,\n    response.status,\n    errorCode,\n    details,\n  );\n}\n\nasync function parseLineageGraph(\n  source: string,\n  response: Response,\n): Promise<LineageReadResult> {\n  let body: unknown;\n  try {\n    body = await response.json();\n  } catch (err) {\n    throw new LineageReadError(\n      `${source} lineage response is not JSON`,\n      response.status,\n      null,\n      { cause: err instanceof Error ? err.message : String(err) },\n    );\n  }\n  // Both servers answer the gateway envelope `{ data, proof }`; a bare view\n  // is accepted too.\n  const envelope = isRecord(body) && isRecord(body.data) ? body : undefined;\n  const parsed = LineageGraphSchema.safeParse(envelope?.data ?? body);\n  if (!parsed.success) {\n    throw new LineageReadError(\n      `${source} lineage response is not a lineage view`,\n      response.status,\n      null,\n      { issues: parsed.error.issues },\n    );\n  }\n  const proof = isRecord(envelope?.proof) ? envelope.proof : undefined;\n  return proof === undefined ? parsed.data : { ...parsed.data, proof };\n}\n\nasync function sendLineageRead(\n  source: string,\n  fetchFn: typeof fetch,\n  url: string,\n  headers: Headers,\n): Promise<LineageReadResult> {\n  let response: Response;\n  try {\n    response = await fetchFn(url, { method: \"GET\", headers });\n  } catch (err) {\n    throw new LineageReadError(\n      `${source} lineage read failed: ${err instanceof Error ? err.message : String(err)}`,\n      undefined,\n      null,\n      { cause: err instanceof Error ? err.message : String(err) },\n    );\n  }\n  if (!response.ok) {\n    throw await lineageReadFailure(source, response);\n  }\n  return parseLineageGraph(source, response);\n}\n\n/**\n * Read a scope's lineage from the Personal Server that stores it.\n *\n * @remarks\n * Sends `GET /v1/data/:scope/lineage[/:version]` with a Web3Signed\n * `Authorization` header carrying `grantId`, the same authentication a data\n * read uses; the signed `uri` is the full path, version segment included.\n * The server resolves the data point id, fetches the view the grant sees\n * from the gateway and returns the gateway's `data` + `proof`.\n *\n * @returns The lineage view, with redacted entries for nodes the grant does\n *   not cover, plus the gateway attestation.\n * @throws {LineageReadError} On a non-2xx answer (`errorCode`: read errors,\n *   `INVALID_VERSION`, `NOT_FOUND` when the scope or version is not\n *   registered at the gateway, `LINEAGE_FORBIDDEN`, `LINEAGE_GATEWAY_ERROR`,\n *   `LINEAGE_UNAVAILABLE`), an unreadable body, a bad `version`, or a\n *   transport failure.\n */\nexport async function getPersonalServerLineage(\n  params: PersonalServerLineageParams,\n): Promise<LineageReadResult> {\n  const fetchFn = resolveFetch(params.fetch);\n  const baseUrl = normalizeBaseUrl(params.personalServerUrl);\n  const audience = params.audience ?? baseUrl;\n  const signer = resolveWriteSigner(params.signer, { account: params.account });\n  const path = personalServerLineagePath(\n    params.scope,\n    normalizeVersion(params.version),\n  );\n  const headers = new Headers(params.headers);\n  headers.set(\n    \"Authorization\",\n    await buildWeb3SignedHeader({\n      signMessage: signer.signMessage,\n      aud: audience,\n      method: \"GET\",\n      uri: path,\n      grantId: params.grantId,\n    }),\n  );\n  return sendLineageRead(\n    \"Personal Server\",\n    fetchFn,\n    `${baseUrl}${path}`,\n    headers,\n  );\n}\n\n/**\n * Read a data point's lineage from the gateway.\n *\n * @remarks\n * Sends `GET /v1/data/:dataPointId/lineage[/:version]` with a Web3Signed\n * `Authorization` header: `aud` = the gateway origin, `uri` =\n * {@link gatewayLineagePath} (lowercase id, version segment included),\n * empty-body `bodyHash`, and the lowercased `grantId` claim when given. The\n * gateway answers a uniform 404 for an unknown data point and for a signer\n * it will not serve, so the two cannot be told apart from outside.\n *\n * @returns The lineage view, with redacted entries for nodes the caller's\n *   grant does not cover, plus the gateway attestation.\n * @throws {LineageReadError} On a malformed `dataPointId` or `version`, a\n *   non-2xx answer (400 malformed request, 401 `LINEAGE_SIGNATURE_REQUIRED`\n *   / `LINEAGE_SIGNATURE_INVALID`, 404 unknown or not served), an unreadable\n *   body, or a transport failure.\n */\nexport async function getGatewayLineage(\n  params: GatewayLineageParams,\n): Promise<LineageReadResult> {\n  if (!isDataPointId(params.dataPointId)) {\n    throw new LineageReadError(\n      \"dataPointId must be a 32-byte hex string (see deriveDataPointId)\",\n      undefined,\n      \"INVALID_DATA_POINT_ID\",\n      { dataPointId: params.dataPointId },\n    );\n  }\n  const fetchFn = resolveFetch(params.fetch);\n  const baseUrl = normalizeBaseUrl(params.gatewayUrl);\n  const signer = resolveWriteSigner(params.signer, { account: params.account });\n  const uri = gatewayLineagePath(\n    params.dataPointId,\n    normalizeVersion(params.version),\n  );\n  const headers = new Headers(params.headers);\n  headers.set(\n    \"Authorization\",\n    await buildWeb3SignedHeader({\n      signMessage: signer.signMessage,\n      aud: baseUrl,\n      method: \"GET\",\n      uri,\n      grantId: params.grantId?.toLowerCase(),\n    }),\n  );\n  return sendLineageRead(\"Gateway\", fetchFn, `${baseUrl}${uri}`, headers);\n}\n\n/**\n * Read a lineage view from either the Personal Server (by scope) or the\n * gateway (by data point id), chosen by the params shape.\n *\n * @example\n * ```typescript\n * const fromPs = await getLineage({ personalServerUrl, scope, grantId, signer });\n * const fromGateway = await getLineage({ gatewayUrl, dataPointId, grantId, signer });\n * ```\n */\nexport function getLineage(\n  params: GetLineageParams,\n): Promise<LineageReadResult> {\n  return \"personalServerUrl\" in params\n    ? getPersonalServerLineage(params)\n    : getGatewayLineage(params);\n}\n"],"mappings":"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","names":[]}

package/dist/protocol/lineage.d.ts

@@ -0,0 +1,228 @@
+/**
+ * Derivative lineage: which data points a record was derived from, and which
+ * records were derived from it.
+ *
+ * @remarks
+ * A data point is addressed by `keccak256(abi.encode(address owner, string
+ * scope))` ({@link deriveDataPointId}). A builder writing a derivative names
+ * its sources through the `lineage` option of {@link writeData}; the Personal
+ * Server stores them under the reserved `$lineage` key and both the Personal
+ * Server (`GET /v1/data/:scope/lineage[/:version]`) and the gateway
+ * (`GET /v1/data/:dataPointId/lineage[/:version]`) answer the resulting view.
+ * Nodes the caller holds no grant for come back as
+ * `{ dataPointId, redacted: true }`; a source that no longer resolves comes
+ * back with `version: "0"`.
+ *
+ * A derived scope must not share its first dot-segment with any source scope
+ * (a grant on `chatgpt.*` must never read a derivative of
+ * `chatgpt.conversations`): see {@link assertDerivedScopeNaming}.
+ *
+ * @category Protocol
+ */
+import { type Address, type Hex } from "viem";
+import { z } from "zod";
+import { type ResolveWriteSignerOptions, type WriteSignerSource } from "./write-signer.js";
+/** `true` when `value` is a 32-byte hex data point id. */
+export declare function isDataPointId(value: unknown): value is Hex;
+/**
+ * Derive the DataRegistryV2 data point id for an owner and scope:
+ * `keccak256(abi.encode(address ownerAddress, string scope))`.
+ *
+ * @param ownerAddress - The data owner (the Personal Server owner).
+ * @param scope - The scope the data point is stored under.
+ * @returns The 32-byte id, lowercase hex.
+ * @throws Error when `ownerAddress` is not an EVM address.
+ */
+export declare function deriveDataPointId(ownerAddress: Address, scope: string): Hex;
+/** First dot-segment of a scope (`chatgpt` for `chatgpt.conversations`). */
+export declare function scopeNamespace(scope: string): string;
+/**
+ * The naming rule: a derived scope and a source scope must not share their
+ * first dot-segment, because a `prefix.*` grant would then cover both and
+ * leak across the lineage edge. Mirrors the Personal Server's check
+ * (`LINEAGE_SCOPE_UNDER_SOURCE_PREFIX`).
+ */
+export declare function derivedScopeViolatesNaming(derivedScope: string, sourceScope: string): boolean;
+/**
+ * Throw when `derivedScope` shares its first dot-segment with any source
+ * scope (see {@link derivedScopeViolatesNaming}).
+ *
+ * @throws {WriteRequestError} Naming the offending source scope in `details`.
+ */
+export declare function assertDerivedScopeNaming(derivedScope: string, sourceScopes: readonly string[]): void;
+export declare const LineageNodeSchema: z.ZodObject<{
+    dataPointId: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+    scope: z.ZodString;
+    version: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    deletedAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export declare const RedactedLineageNodeSchema: z.ZodObject<{
+    dataPointId: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+    redacted: z.ZodLiteral<true>;
+}, z.core.$strip>;
+export declare const LineageEntrySchema: z.ZodUnion<readonly [z.ZodObject<{
+    dataPointId: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+    redacted: z.ZodLiteral<true>;
+}, z.core.$strip>, z.ZodObject<{
+    dataPointId: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+    scope: z.ZodString;
+    version: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    deletedAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>]>;
+export declare const LineageGraphSchema: z.ZodObject<{
+    dataPointId: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+    ownerAddress: z.ZodOptional<z.ZodString>;
+    scope: z.ZodString;
+    version: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    deletedAt: z.ZodNullable<z.ZodString>;
+    sources: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        dataPointId: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+        redacted: z.ZodLiteral<true>;
+    }, z.core.$strip>, z.ZodObject<{
+        dataPointId: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+        scope: z.ZodString;
+        version: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+        deletedAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>]>>;
+    derivatives: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        dataPointId: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+        redacted: z.ZodLiteral<true>;
+    }, z.core.$strip>, z.ZodObject<{
+        dataPointId: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+        scope: z.ZodString;
+        version: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+        deletedAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>]>>;
+    derivativesTruncated: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/** A lineage node the caller is allowed to see. */
+export type LineageNode = z.infer<typeof LineageNodeSchema>;
+/** A lineage node the caller holds no grant for: only its id is disclosed. */
+export type RedactedLineageNode = z.infer<typeof RedactedLineageNodeSchema>;
+/** One entry of a lineage graph. Narrow with {@link isRedactedLineageNode}. */
+export type LineageEntry = z.infer<typeof LineageEntrySchema>;
+/** The lineage view of one data point (the `data` of the response). */
+export type LineageGraph = z.infer<typeof LineageGraphSchema>;
+/** A lineage read: the view plus the gateway's attestation over it. */
+export interface LineageReadResult extends LineageGraph {
+    /**
+     * The gateway `proof` (`GatewayAttestation` over the served view, so a
+     * redacted view verifies on its own). Passed through as received; absent
+     * when the server sent none.
+     */
+    proof?: Record<string, unknown>;
+}
+/** `true` when the entry was redacted (the caller holds no grant for it). */
+export declare function isRedactedLineageNode(entry: LineageEntry): entry is RedactedLineageNode;
+/**
+ * The Personal Server lineage path: `/v1/data/:scope/lineage[/:version]`.
+ * The version is a path segment (a query string is refused by the server),
+ * so the signed `uri` covers the whole request.
+ */
+export declare function personalServerLineagePath(scope: string, version?: string | number): string;
+/**
+ * The gateway lineage path: `/v1/data/<id lowercase>/lineage[/:version]`,
+ * what the request is signed over and sent to. The grant view is the signed
+ * `grantId` claim, never a query parameter.
+ */
+export declare function gatewayLineagePath(dataPointId: Hex, version?: string | number): string;
+interface LineageRequestOptions {
+    /**
+     * Read the lineage as of this version (a positive decimal integer);
+     * omitted = the current version, or the last version that carried lineage
+     * when the current one is a tombstone.
+     */
+    version?: string | number;
+    /** `fetch` to use; defaults to `globalThis.fetch`. */
+    fetch?: typeof fetch;
+    /** Extra request headers. */
+    headers?: HeadersInit;
+}
+/** Lineage read against the Personal Server holding the record. */
+export interface PersonalServerLineageParams extends LineageRequestOptions {
+    /** Personal Server origin, e.g. `https://ps.example.com`. */
+    personalServerUrl: string;
+    /** The scope whose lineage to read. */
+    scope: string;
+    /** A grant covering the scope, sent as the signed `grantId` claim. */
+    grantId: string;
+    /** Builder key: a viem `LocalAccount`, `WalletClient`, or `{ signMessage }`. */
+    signer: WriteSignerSource;
+    /** Account for a viem wallet client without a hoisted account. */
+    account?: ResolveWriteSignerOptions["account"];
+    /** Web3Signed audience; defaults to `personalServerUrl`. */
+    audience?: string;
+}
+/** Lineage read against the gateway, by data point id. */
+export interface GatewayLineageParams extends LineageRequestOptions {
+    /** Gateway origin, e.g. `https://dp-rpc.vana.org`. */
+    gatewayUrl: string;
+    /** The data point whose lineage to read (see {@link deriveDataPointId}). */
+    dataPointId: Hex;
+    /**
+     * The key the request is signed with (Web3Signed, audience = the gateway
+     * origin). The signer decides the view: the owner or one of its servers
+     * gets the full view; a registered builder holding a live grant covering
+     * the data point's scope gets that grant's view; anyone else is refused.
+     */
+    signer: WriteSignerSource;
+    /** Account for a viem wallet client without a hoisted account. */
+    account?: ResolveWriteSignerOptions["account"];
+    /**
+     * The grant whose view to read, sent lowercased as the signed `grantId`
+     * claim (never as a query parameter). An owner or server uses it to fetch
+     * the view a builder's grant sees; a builder needs it to see anything.
+     */
+    grantId?: string;
+}
+export type GetLineageParams = PersonalServerLineageParams | GatewayLineageParams;
+/**
+ * Read a scope's lineage from the Personal Server that stores it.
+ *
+ * @remarks
+ * Sends `GET /v1/data/:scope/lineage[/:version]` with a Web3Signed
+ * `Authorization` header carrying `grantId`, the same authentication a data
+ * read uses; the signed `uri` is the full path, version segment included.
+ * The server resolves the data point id, fetches the view the grant sees
+ * from the gateway and returns the gateway's `data` + `proof`.
+ *
+ * @returns The lineage view, with redacted entries for nodes the grant does
+ *   not cover, plus the gateway attestation.
+ * @throws {LineageReadError} On a non-2xx answer (`errorCode`: read errors,
+ *   `INVALID_VERSION`, `NOT_FOUND` when the scope or version is not
+ *   registered at the gateway, `LINEAGE_FORBIDDEN`, `LINEAGE_GATEWAY_ERROR`,
+ *   `LINEAGE_UNAVAILABLE`), an unreadable body, a bad `version`, or a
+ *   transport failure.
+ */
+export declare function getPersonalServerLineage(params: PersonalServerLineageParams): Promise<LineageReadResult>;
+/**
+ * Read a data point's lineage from the gateway.
+ *
+ * @remarks
+ * Sends `GET /v1/data/:dataPointId/lineage[/:version]` with a Web3Signed
+ * `Authorization` header: `aud` = the gateway origin, `uri` =
+ * {@link gatewayLineagePath} (lowercase id, version segment included),
+ * empty-body `bodyHash`, and the lowercased `grantId` claim when given. The
+ * gateway answers a uniform 404 for an unknown data point and for a signer
+ * it will not serve, so the two cannot be told apart from outside.
+ *
+ * @returns The lineage view, with redacted entries for nodes the caller's
+ *   grant does not cover, plus the gateway attestation.
+ * @throws {LineageReadError} On a malformed `dataPointId` or `version`, a
+ *   non-2xx answer (400 malformed request, 401 `LINEAGE_SIGNATURE_REQUIRED`
+ *   / `LINEAGE_SIGNATURE_INVALID`, 404 unknown or not served), an unreadable
+ *   body, or a transport failure.
+ */
+export declare function getGatewayLineage(params: GatewayLineageParams): Promise<LineageReadResult>;
+/**
+ * Read a lineage view from either the Personal Server (by scope) or the
+ * gateway (by data point id), chosen by the params shape.
+ *
+ * @example
+ * ```typescript
+ * const fromPs = await getLineage({ personalServerUrl, scope, grantId, signer });
+ * const fromGateway = await getLineage({ gatewayUrl, dataPointId, grantId, signer });
+ * ```
+ */
+export declare function getLineage(params: GetLineageParams): Promise<LineageReadResult>;
+export {};