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

package/dist/protocol/identity.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Enclave identity and consent primitives for Personal Servers.
+ *
+ * Owner/Web -> Gateway -> Agent(CVM): derive wallet and quote
+ * Web verifies evidence; Account authenticates and encrypts the EIP-191 master
+ * signature to the enclave key; Gateway relays it blind; Agent decrypts/seals.
+ *
+ * @category Protocol
+ */
+import { type Address, type Hex } from "viem";
+import { type ECIESProvider } from "../crypto/ecies/interface.js";
+import type { ServerRegistrationMessage } from "./eip712.js";
+export declare const ENCLAVE_IDENTITY_EVIDENCE_VERSION = 1;
+export declare const USER_PS_ID_DOMAIN = "vana.ps-enclave.v1";
+export declare const ENCLAVE_WALLET_PURPOSE = "vana.ps-enclave.wallet.v1";
+export declare const MASTER_SIGNATURE_DELIVERY_VERSION = "vana.ps-enclave.delivery.v1";
+export declare const SEALED_ENVELOPE_VERSION = 1;
+export type UserPsId = Hex;
+export interface EnclaveIdentityEvidence {
+    v: typeof ENCLAVE_IDENTITY_EVIDENCE_VERSION;
+    userPsId: UserPsId;
+    chainId: number;
+    ownerAddress: Address;
+    epoch: number;
+    address: Address;
+    publicKey: Hex;
+    appId: Hex;
+    composeHash: Hex;
+    osImageHash?: Hex;
+    purpose: string;
+    signatureChain: [Hex, Hex];
+    quote: Hex;
+    eventLog?: string;
+    kmsRootFingerprint: Hex;
+}
+export interface ExpectedIdentity {
+    ownerAddress: Address;
+    chainId: number;
+    epoch: number;
+}
+export interface IdentityRequest {
+    ownerAddress: Address;
+    chainId: number;
+}
+export type IdentityState = "prepared" | "registered" | "sealed" | "retired";
+export interface IdentityResponse {
+    identity: EnclaveIdentityEvidence;
+    state: IdentityState;
+    created: boolean;
+    serverUrl: string;
+    serverId?: Hex;
+    serverStatus?: "pending" | "submitting" | "confirmed" | "finalized" | "failed";
+    sealed: boolean;
+}
+export type IdentityRegistrationRequest = {
+    version: "v2";
+    message: ServerRegistrationMessage;
+} | {
+    version: "v3";
+    message: ServerRegistrationMessage & {
+        nonce: string;
+        deadline: string;
+    };
+};
+export interface IdentityRegistrationResponse {
+    serverId: Hex;
+    state: "registered";
+    serverStatus: "pending";
+}
+/** Inner plaintext of the ECIES box. */
+export interface MasterSignatureDelivery {
+    v: typeof MASTER_SIGNATURE_DELIVERY_VERSION;
+    userPsId: UserPsId;
+    epoch: number;
+    enclaveAddress: Address;
+    ownerAddress: Address;
+    masterSignature: Hex;
+    issuedAt: number;
+}
+export interface SealedSecretSubmission {
+    userPsId: UserPsId;
+    epoch: number;
+    enclaveAddress: Address;
+    ciphertext: Hex;
+}
+export interface SealedSecretResponse {
+    sealed: true;
+    secretHash: Hex;
+    sealedAt: string;
+}
+export interface AesGcmBox {
+    iv: string;
+    ciphertext: string;
+    tag: string;
+}
+/** Persisted enclave envelope; the Gateway treats it as opaque text. */
+export interface SealedEnvelope extends AesGcmBox {
+    v: typeof SEALED_ENVELOPE_VERSION;
+    wrappedContentKey: AesGcmBox;
+}
+export interface EnclaveTrustAnchors {
+    kmsRootPubkey: Hex;
+    appIds: Hex[];
+}
+/** Fleet-provisioned trust anchors keyed by Vana chain ID. */
+export declare const ENCLAVE_TRUST_ANCHORS: Record<number, EnclaveTrustAnchors>;
+/**
+ * Derives the deterministic Personal Server ID used by enclave paths.
+ *
+ * @param chainId - Vana chain ID.
+ * @param ownerAddress - Checksummed owner address.
+ * @returns The path-compatible keccak256 digest.
+ */
+export declare function userPsId(chainId: number, ownerAddress: Address): UserPsId;
+/**
+ * Builds keccak256(utf8(purpose || ":" || lowercase hex(compressed pubkey))).
+ *
+ * Matches `dstack/guest-agent/src/rpc_service.rs:612-628`.
+ */
+export declare function appRootPreimage(purpose: string, publicKey: Hex): Hex;
+/**
+ * Hashes the KMS prefix, raw app ID bytes, and compressed app-root public key.
+ *
+ * Matches `dstack/kms/src/crypto.rs:23-40`; there is no separator between the
+ * raw 20-byte app ID and the compressed key.
+ */
+export declare function kmsIssuedPreimage(appId: Hex, appRootPublicKey: Hex): Hex;
+/**
+ * Verifies the enclave wallet binding against fleet-provisioned trust anchors.
+ *
+ * @param evidence - Identity evidence returned by the enclave agent.
+ * @param anchors - Pinned KMS root and allowed dstack app IDs.
+ * @param expected - Owner, chain, and epoch requested by the caller.
+ *
+ * @remarks
+ * The dstack chain signs only `purpose || publicKey` and `appId || appRootPub`;
+ * owner, chain and epoch are bound to the key by the TDX quote report_data
+ * (`keccak256(userPsId || address)`), which v1 stores but does not verify
+ * (DCAP is step 4). Until then the agent's derivation check is the backstop.
+ * @throws When any identity binding or trust check fails.
+ */
+export declare function verifyEnclaveIdentityEvidence(evidence: EnclaveIdentityEvidence, anchors: EnclaveTrustAnchors, expected: ExpectedIdentity): Promise<void>;
+/**
+ * Builds the authenticated master-signature plaintext delivered to an enclave.
+ *
+ * @param evidence - Verified enclave identity evidence.
+ * @param masterSignature - EIP-191 signature over the master-key message.
+ * @param now - Issuance time in Unix seconds.
+ * @returns The authenticated plaintext delivery object.
+ * @throws When the signature is malformed or does not belong to the owner.
+ */
+export declare function buildMasterSignatureDelivery(evidence: EnclaveIdentityEvidence, masterSignature: Hex, now?: number): Promise<MasterSignatureDelivery>;
+/**
+ * Encrypts a master-signature delivery in the SDK's ECIES wire format.
+ *
+ * @param delivery - Plaintext delivery object.
+ * @param publicKey - Enclave 65-byte uncompressed public key.
+ * @param ecies - Platform-specific ECIES provider.
+ * @returns The 0x-prefixed serialized ciphertext.
+ */
+export declare function encryptMasterSignatureDelivery(delivery: MasterSignatureDelivery, publicKey: Hex, ecies: ECIESProvider): Promise<Hex>;

package/dist/protocol/identity.js

@@ -0,0 +1,159 @@
+import * as secp256k1 from "@noble/secp256k1";
+import {
+  concat,
+  encodePacked,
+  fromHex,
+  getAddress,
+  isAddressEqual,
+  keccak256,
+  recoverPublicKey,
+  toBytes,
+  toHex
+} from "viem";
+import { publicKeyToAddress } from "viem/accounts";
+import { serializeECIES } from "../crypto/ecies/interface.js";
+import { deriveMasterKey, recoverServerOwner } from "../crypto/keys/derive.js";
+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 = encodePacked(
+    ["string", "uint256", "address"],
+    [USER_PS_ID_DOMAIN, BigInt(chainId), getAddress(ownerAddress)]
+  );
+  return keccak256(packed);
+}
+function compressPublicKey(publicKey) {
+  return secp256k1.ProjectivePoint.fromHex(
+    fromHex(publicKey, "bytes")
+  ).toRawBytes(true);
+}
+function appRootPreimage(purpose, publicKey) {
+  const keyHex = toHex(compressPublicKey(publicKey)).slice(2);
+  return keccak256(toBytes(`${purpose}${PREIMAGE_SEPARATOR}${keyHex}`));
+}
+function kmsIssuedPreimage(appId, appRootPublicKey) {
+  const prefix = concat([
+    toBytes(`${KMS_ISSUED_PREFIX}${PREIMAGE_SEPARATOR}`),
+    fromHex(appId, "bytes")
+  ]);
+  const compressed = compressPublicKey(appRootPublicKey);
+  return keccak256(concat([prefix, compressed]));
+}
+async function recoverChainKey(hash, signature, link) {
+  try {
+    return (await recoverPublicKey({ hash, signature })).toLowerCase();
+  } catch {
+    throw new Error(`Invalid enclave signature chain link ${link}`);
+  }
+}
+async function verifyEnclaveIdentityEvidence(evidence, anchors, expected) {
+  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");
+  }
+  if (evidence.chainId !== expected.chainId) {
+    throw new Error(
+      "Enclave identity chain ID does not match expected chain ID"
+    );
+  }
+  if (!isAddressEqual(evidence.ownerAddress, expected.ownerAddress)) {
+    throw new Error("Enclave identity owner does not match expected owner");
+  }
+  if (evidence.epoch !== expected.epoch) {
+    throw new Error("Enclave identity epoch does not match expected epoch");
+  }
+  const expectedUserPsId = userPsId(expected.chainId, expected.ownerAddress);
+  if (evidence.userPsId.toLowerCase() !== expectedUserPsId.toLowerCase()) {
+    throw new Error("Enclave userPsId does not match expected identity");
+  }
+  if (evidence.purpose !== ENCLAVE_WALLET_PURPOSE) {
+    throw new Error("Unexpected enclave wallet purpose");
+  }
+  const derivedAddress = publicKeyToAddress(evidence.publicKey);
+  if (getAddress(derivedAddress) !== 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 (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");
+  }
+}
+async function buildMasterSignatureDelivery(evidence, masterSignature, now = Math.floor(Date.now() / 1e3)) {
+  deriveMasterKey(masterSignature);
+  const signerAddress = await recoverServerOwner(masterSignature);
+  if (!isAddressEqual(signerAddress, evidence.ownerAddress)) {
+    throw new Error("Master signature signer does not match evidence owner");
+  }
+  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 = toBytes(JSON.stringify(delivery));
+  const encrypted = await ecies.encrypt(fromHex(publicKey, "bytes"), plaintext);
+  return `0x${serializeECIES(encrypted)}`;
+}
+export {
+  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.js.map

package/dist/protocol/identity.js.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 authenticates and encrypts the EIP-191 master\n * signature to the enclave key; Gateway relays it blind; Agent decrypts/seals.\n *\n * @category Protocol\n */\n\nimport * as secp256k1 from \"@noble/secp256k1\";\nimport {\n  concat,\n  encodePacked,\n  fromHex,\n  getAddress,\n  isAddressEqual,\n  keccak256,\n  recoverPublicKey,\n  toBytes,\n  toHex,\n  type Address,\n  type Hex,\n} from \"viem\";\nimport { publicKeyToAddress } from \"viem/accounts\";\nimport { serializeECIES, type ECIESProvider } from \"../crypto/ecies/interface\";\nimport { deriveMasterKey, recoverServerOwner } 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 ExpectedIdentity {\n  ownerAddress: Address;\n  chainId: number;\n  epoch: number;\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\nfunction compressPublicKey(publicKey: Hex): Uint8Array {\n  return secp256k1.ProjectivePoint.fromHex(\n    fromHex(publicKey, \"bytes\"),\n  ).toRawBytes(true);\n}\n\n/**\n * Builds keccak256(utf8(purpose || \":\" || lowercase hex(compressed pubkey))).\n *\n * Matches `dstack/guest-agent/src/rpc_service.rs:612-628`.\n */\nexport function appRootPreimage(purpose: string, publicKey: Hex): Hex {\n  const keyHex = toHex(compressPublicKey(publicKey)).slice(2);\n  return keccak256(toBytes(`${purpose}${PREIMAGE_SEPARATOR}${keyHex}`));\n}\n\n/**\n * Hashes the KMS prefix, raw app ID bytes, and compressed app-root public key.\n *\n * Matches `dstack/kms/src/crypto.rs:23-40`; there is no separator between the\n * raw 20-byte app ID and the compressed key.\n */\nexport function kmsIssuedPreimage(appId: Hex, appRootPublicKey: Hex): Hex {\n  const prefix = concat([\n    toBytes(`${KMS_ISSUED_PREFIX}${PREIMAGE_SEPARATOR}`),\n    fromHex(appId, \"bytes\"),\n  ]);\n  const compressed = compressPublicKey(appRootPublicKey);\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 * @param expected - Owner, chain, and epoch requested by the caller.\n *\n * @remarks\n * The dstack chain signs only `purpose || publicKey` and `appId || appRootPub`;\n * owner, chain and epoch are bound to the key by the TDX quote report_data\n * (`keccak256(userPsId || address)`), which v1 stores but does not verify\n * (DCAP is step 4). Until then the agent's derivation check is the backstop.\n * @throws When any identity binding or trust check fails.\n */\nexport async function verifyEnclaveIdentityEvidence(\n  evidence: EnclaveIdentityEvidence,\n  anchors: EnclaveTrustAnchors,\n  expected: ExpectedIdentity,\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  if (evidence.chainId !== expected.chainId) {\n    throw new Error(\n      \"Enclave identity chain ID does not match expected chain ID\",\n    );\n  }\n\n  if (!isAddressEqual(evidence.ownerAddress, expected.ownerAddress)) {\n    throw new Error(\"Enclave identity owner does not match expected owner\");\n  }\n\n  if (evidence.epoch !== expected.epoch) {\n    throw new Error(\"Enclave identity epoch does not match expected epoch\");\n  }\n\n  const expectedUserPsId = userPsId(expected.chainId, expected.ownerAddress);\n  if (evidence.userPsId.toLowerCase() !== expectedUserPsId.toLowerCase()) {\n    throw new Error(\"Enclave userPsId does not match expected identity\");\n  }\n\n  if (evidence.purpose !== ENCLAVE_WALLET_PURPOSE) {\n    throw new Error(\"Unexpected enclave wallet purpose\");\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 authenticated plaintext delivery object.\n * @throws When the signature is malformed or does not belong to the owner.\n */\nexport async function buildMasterSignatureDelivery(\n  evidence: EnclaveIdentityEvidence,\n  masterSignature: Hex,\n  now = Math.floor(Date.now() / 1000),\n): Promise<MasterSignatureDelivery> {\n  deriveMasterKey(masterSignature);\n  const signerAddress = await recoverServerOwner(masterSignature);\n\n  if (!isAddressEqual(signerAddress, evidence.ownerAddress)) {\n    throw new Error(\"Master signature signer does not match evidence owner\");\n  }\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":[]}

package/dist/protocol/identity.test.d.ts

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

package/dist/protocol/identity.vector.test.d.ts

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

package/dist/server.cjs

@@ -55,7 +55,8 @@ __export(server_exports, {
   scopeMatchesPattern: () => import_scopes.scopeMatchesPattern,
   toDirectFeeBreakdown: () => import_escrow_payment.toDirectFeeBreakdown,
   toDirectPaymentReceipt: () => import_escrow_payment.toDirectPaymentReceipt,
-  tryGrantPermissions: () => import_scope_actions.tryGrantPermissions
+  tryGrantPermissions: () => import_scope_actions.tryGrantPermissions,
+  validateAccessRequestQuestions: () => import_access_request_client.validateAccessRequestQuestions
 });
 module.exports = __toCommonJS(server_exports);
 var import_controller = require("./direct/controller");
@@ -106,6 +107,7 @@ var import_types = require("./direct/types");
   scopeMatchesPattern,
   toDirectFeeBreakdown,
   toDirectPaymentReceipt,
-  tryGrantPermissions
+  tryGrantPermissions,
+  validateAccessRequestQuestions
 });
 //# sourceMappingURL=server.cjs.map

package/dist/server.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/server.ts"],"sourcesContent":["/**\n * Server entry point for the Vana SDK direct Data Portability flow.\n *\n * @remarks\n * Exposes {@link createDirectDataController} and its supporting types/errors.\n * This is a Node/server entry point — it owns the app private key and must never\n * be imported into browser code.\n *\n * @example\n * ```typescript\n * import { createDirectDataController } from \"@opendatalabs/vana-sdk/server\";\n *\n * export const vana = createDirectDataController({\n *   env: process.env.VANA_ENV === \"dev\" ? \"dev\" : \"production\",\n *   appPrivateKey: process.env.VANA_APP_PRIVATE_KEY!,\n *   app: { id: \"notes-lens\", name: \"Notes Lens\", homepageUrl: process.env.VANA_APP_URL! },\n *   source: \"icloud_notes\",\n *   scopes: [\"icloud_notes.notes\"],\n * });\n * ```\n *\n * @category Direct\n * @module server\n */\n\nexport {\n  createDirectDataController,\n  type DirectDataController,\n  type DirectDataControllerConfig,\n  type DirectEscrowConfig,\n} from \"./direct/controller\";\n\n// Lower-level building blocks (advanced use / custom transports).\nexport {\n  createDefaultAccessRequestClient,\n  buildApprovalUrl,\n  type DefaultAccessRequestClientOptions,\n  type FetchLike,\n} from \"./direct/access-request-client\";\nexport {\n  buildPersonalServerDataReadRequest,\n  readPersonalServerData,\n  parsePersonalServerPaymentRequired,\n  dataPathForScope,\n  type PersonalServerDataReadRequest,\n  type PersonalServerReadResult,\n  type PersonalServerFetch,\n  type PersonalServerTransportRetryOptions,\n  type FetchResponseLike,\n} from \"./direct/personal-server-read\";\n// Escrow-backed payment (built on protocol/escrow).\nexport {\n  authorizeEscrowPayment,\n  authorizeGrantPayment,\n  buildEscrowPaymentHeader,\n  buildGrantPaymentHeader,\n  paymentResponseMetadataFromHeader,\n  toDirectPaymentReceipt,\n  toDirectFeeBreakdown,\n  createDefaultNonceSource,\n  DATA_ACCESS_OP_TYPE,\n  GRANT_OP_TYPE,\n  type EscrowPaymentConfig,\n  type EscrowPaymentHeaderConfig,\n  type SignTypedDataFn,\n  type PaymentNonceSource,\n} from \"./direct/escrow-payment\";\nexport {\n  getDirectEndpoints,\n  PRODUCTION_ENDPOINTS,\n  DEV_ENDPOINTS,\n} from \"./direct/endpoints\";\n// Grant scope entries: the `[operation:]scope` vocabulary the controller's\n// `scopes` are written in, so a backend can build and read them without\n// reaching for a platform entry point.\nexport {\n  ScopeSchema,\n  parseScope,\n  scopeMatchesPattern,\n  scopeCoveredByGrant,\n  type Scope,\n  type ParsedScope,\n} from \"./protocol/scopes\";\nexport {\n  SCOPE_ACTIONS,\n  InvalidScopeEntryError,\n  parseScopeEntry,\n  formatScopeEntry,\n  grantPermissions,\n  permissionsToScopes,\n  tryGrantPermissions,\n  hasAction,\n  type ScopeAction,\n  type ParsedScopeEntry,\n  type GrantPermission,\n} from \"./protocol/scope-actions\";\n\n// Errors\nexport {\n  DirectConfigError,\n  AccessNotApprovedError,\n  ScopeNotApprovedError,\n  PersonalServerReadError,\n  PaymentRequiredError,\n} from \"./direct/errors\";\n\n// Shared types\nexport type {\n  DirectEnv,\n  DirectNetwork,\n  DirectAppConfig,\n  ForegroundDelivery,\n  AppIdentity,\n  DirectServiceEndpoints,\n  AccessRequest,\n  AccessRequestStatus,\n  AccessRequestStatusValue,\n  ApprovedDataResult,\n  MultiScopeDataResult,\n  AccessRequestClient,\n  DirectOpTypeValue,\n  PersonalServerDataAccessPaymentOperation,\n  PersonalServerGrantPaymentOperation,\n  PersonalServerPaymentOperation,\n  PersonalServerPaymentRequired,\n  DirectPaymentReceipt,\n  DirectPaymentResponseMetadata,\n  DirectFeeBreakdown,\n} from \"./direct/types\";\n\n// Op-type vocabulary constant.\nexport { DirectOpType } from \"./direct/types\";\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAyBA,wBAKO;AAGP,mCAKO;AACP,kCAUO;AAEP,4BAeO;AACP,uBAIO;AAIP,oBAOO;AACP,2BAYO;AAGP,oBAMO;AA2BP,mBAA6B;","names":[]}
+{"version":3,"sources":["../src/server.ts"],"sourcesContent":["/**\n * Server entry point for the Vana SDK direct Data Portability flow.\n *\n * @remarks\n * Exposes {@link createDirectDataController} and its supporting types/errors.\n * This is a Node/server entry point — it owns the app private key and must never\n * be imported into browser code.\n *\n * @example\n * ```typescript\n * import { createDirectDataController } from \"@opendatalabs/vana-sdk/server\";\n *\n * export const vana = createDirectDataController({\n *   env: process.env.VANA_ENV === \"dev\" ? \"dev\" : \"production\",\n *   appPrivateKey: process.env.VANA_APP_PRIVATE_KEY!,\n *   app: { id: \"notes-lens\", name: \"Notes Lens\", homepageUrl: process.env.VANA_APP_URL! },\n *   source: \"icloud_notes\",\n *   scopes: [\"icloud_notes.notes\"],\n * });\n * ```\n *\n * @category Direct\n * @module server\n */\n\nexport {\n  createDirectDataController,\n  type DirectDataController,\n  type DirectDataControllerConfig,\n  type DirectEscrowConfig,\n} from \"./direct/controller\";\n\n// Lower-level building blocks (advanced use / custom transports).\nexport {\n  createDefaultAccessRequestClient,\n  buildApprovalUrl,\n  validateAccessRequestQuestions,\n  type DefaultAccessRequestClientOptions,\n  type FetchLike,\n} from \"./direct/access-request-client\";\nexport {\n  buildPersonalServerDataReadRequest,\n  readPersonalServerData,\n  parsePersonalServerPaymentRequired,\n  dataPathForScope,\n  type PersonalServerDataReadRequest,\n  type PersonalServerReadResult,\n  type PersonalServerFetch,\n  type PersonalServerTransportRetryOptions,\n  type FetchResponseLike,\n} from \"./direct/personal-server-read\";\n// Escrow-backed payment (built on protocol/escrow).\nexport {\n  authorizeEscrowPayment,\n  authorizeGrantPayment,\n  buildEscrowPaymentHeader,\n  buildGrantPaymentHeader,\n  paymentResponseMetadataFromHeader,\n  toDirectPaymentReceipt,\n  toDirectFeeBreakdown,\n  createDefaultNonceSource,\n  DATA_ACCESS_OP_TYPE,\n  GRANT_OP_TYPE,\n  type EscrowPaymentConfig,\n  type EscrowPaymentHeaderConfig,\n  type SignTypedDataFn,\n  type PaymentNonceSource,\n} from \"./direct/escrow-payment\";\nexport {\n  getDirectEndpoints,\n  PRODUCTION_ENDPOINTS,\n  DEV_ENDPOINTS,\n} from \"./direct/endpoints\";\n// Grant scope entries: the `[operation:]scope` vocabulary the controller's\n// `scopes` are written in, so a backend can build and read them without\n// reaching for a platform entry point.\nexport {\n  ScopeSchema,\n  parseScope,\n  scopeMatchesPattern,\n  scopeCoveredByGrant,\n  type Scope,\n  type ParsedScope,\n} from \"./protocol/scopes\";\nexport {\n  SCOPE_ACTIONS,\n  InvalidScopeEntryError,\n  parseScopeEntry,\n  formatScopeEntry,\n  grantPermissions,\n  permissionsToScopes,\n  tryGrantPermissions,\n  hasAction,\n  type ScopeAction,\n  type ParsedScopeEntry,\n  type GrantPermission,\n} from \"./protocol/scope-actions\";\n\n// Errors\nexport {\n  DirectConfigError,\n  AccessNotApprovedError,\n  ScopeNotApprovedError,\n  PersonalServerReadError,\n  PaymentRequiredError,\n} from \"./direct/errors\";\n\n// Shared types\nexport type {\n  DirectEnv,\n  DirectNetwork,\n  DirectAppConfig,\n  ForegroundDelivery,\n  AppIdentity,\n  DirectServiceEndpoints,\n  AccessRequest,\n  AccessRequestQuestion,\n  AccessRequestStatus,\n  AccessRequestStatusValue,\n  ApprovedDataResult,\n  MultiScopeDataResult,\n  AccessRequestClient,\n  DirectOpTypeValue,\n  PersonalServerDataAccessPaymentOperation,\n  PersonalServerGrantPaymentOperation,\n  PersonalServerPaymentOperation,\n  PersonalServerPaymentRequired,\n  DirectPaymentReceipt,\n  DirectPaymentResponseMetadata,\n  DirectFeeBreakdown,\n} from \"./direct/types\";\n\n// Op-type vocabulary constant.\nexport { DirectOpType } from \"./direct/types\";\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAyBA,wBAKO;AAGP,mCAMO;AACP,kCAUO;AAEP,4BAeO;AACP,uBAIO;AAIP,oBAOO;AACP,2BAYO;AAGP,oBAMO;AA4BP,mBAA6B;","names":[]}

package/dist/server.d.ts

@@ -23,12 +23,12 @@
  * @module server
  */
 export { createDirectDataController, type DirectDataController, type DirectDataControllerConfig, type DirectEscrowConfig, } from "./direct/controller.js";
-export { createDefaultAccessRequestClient, buildApprovalUrl, type DefaultAccessRequestClientOptions, type FetchLike, } from "./direct/access-request-client.js";
+export { createDefaultAccessRequestClient, buildApprovalUrl, validateAccessRequestQuestions, type DefaultAccessRequestClientOptions, type FetchLike, } from "./direct/access-request-client.js";
 export { buildPersonalServerDataReadRequest, readPersonalServerData, parsePersonalServerPaymentRequired, dataPathForScope, type PersonalServerDataReadRequest, type PersonalServerReadResult, type PersonalServerFetch, type PersonalServerTransportRetryOptions, type FetchResponseLike, } from "./direct/personal-server-read.js";
 export { authorizeEscrowPayment, authorizeGrantPayment, buildEscrowPaymentHeader, buildGrantPaymentHeader, paymentResponseMetadataFromHeader, toDirectPaymentReceipt, toDirectFeeBreakdown, createDefaultNonceSource, DATA_ACCESS_OP_TYPE, GRANT_OP_TYPE, type EscrowPaymentConfig, type EscrowPaymentHeaderConfig, type SignTypedDataFn, type PaymentNonceSource, } from "./direct/escrow-payment.js";
 export { getDirectEndpoints, PRODUCTION_ENDPOINTS, DEV_ENDPOINTS, } from "./direct/endpoints.js";
 export { ScopeSchema, parseScope, scopeMatchesPattern, scopeCoveredByGrant, type Scope, type ParsedScope, } from "./protocol/scopes.js";
 export { SCOPE_ACTIONS, InvalidScopeEntryError, parseScopeEntry, formatScopeEntry, grantPermissions, permissionsToScopes, tryGrantPermissions, hasAction, type ScopeAction, type ParsedScopeEntry, type GrantPermission, } from "./protocol/scope-actions.js";
 export { DirectConfigError, AccessNotApprovedError, ScopeNotApprovedError, PersonalServerReadError, PaymentRequiredError, } from "./direct/errors.js";
-export type { DirectEnv, DirectNetwork, DirectAppConfig, ForegroundDelivery, AppIdentity, DirectServiceEndpoints, AccessRequest, AccessRequestStatus, AccessRequestStatusValue, ApprovedDataResult, MultiScopeDataResult, AccessRequestClient, DirectOpTypeValue, PersonalServerDataAccessPaymentOperation, PersonalServerGrantPaymentOperation, PersonalServerPaymentOperation, PersonalServerPaymentRequired, DirectPaymentReceipt, DirectPaymentResponseMetadata, DirectFeeBreakdown, } from "./direct/types.js";
+export type { DirectEnv, DirectNetwork, DirectAppConfig, ForegroundDelivery, AppIdentity, DirectServiceEndpoints, AccessRequest, AccessRequestQuestion, AccessRequestStatus, AccessRequestStatusValue, ApprovedDataResult, MultiScopeDataResult, AccessRequestClient, DirectOpTypeValue, PersonalServerDataAccessPaymentOperation, PersonalServerGrantPaymentOperation, PersonalServerPaymentOperation, PersonalServerPaymentRequired, DirectPaymentReceipt, DirectPaymentResponseMetadata, DirectFeeBreakdown, } from "./direct/types.js";
 export { DirectOpType } from "./direct/types.js";

package/dist/server.js

@@ -3,7 +3,8 @@ import {
 } from "./direct/controller.js";
 import {
   createDefaultAccessRequestClient,
-  buildApprovalUrl
+  buildApprovalUrl,
+  validateAccessRequestQuestions
 } from "./direct/access-request-client.js";
 import {
   buildPersonalServerDataReadRequest,
@@ -90,6 +91,7 @@ export {
   scopeMatchesPattern,
   toDirectFeeBreakdown,
   toDirectPaymentReceipt,
-  tryGrantPermissions
+  tryGrantPermissions,
+  validateAccessRequestQuestions
 };
 //# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/server.ts"],"sourcesContent":["/**\n * Server entry point for the Vana SDK direct Data Portability flow.\n *\n * @remarks\n * Exposes {@link createDirectDataController} and its supporting types/errors.\n * This is a Node/server entry point — it owns the app private key and must never\n * be imported into browser code.\n *\n * @example\n * ```typescript\n * import { createDirectDataController } from \"@opendatalabs/vana-sdk/server\";\n *\n * export const vana = createDirectDataController({\n *   env: process.env.VANA_ENV === \"dev\" ? \"dev\" : \"production\",\n *   appPrivateKey: process.env.VANA_APP_PRIVATE_KEY!,\n *   app: { id: \"notes-lens\", name: \"Notes Lens\", homepageUrl: process.env.VANA_APP_URL! },\n *   source: \"icloud_notes\",\n *   scopes: [\"icloud_notes.notes\"],\n * });\n * ```\n *\n * @category Direct\n * @module server\n */\n\nexport {\n  createDirectDataController,\n  type DirectDataController,\n  type DirectDataControllerConfig,\n  type DirectEscrowConfig,\n} from \"./direct/controller\";\n\n// Lower-level building blocks (advanced use / custom transports).\nexport {\n  createDefaultAccessRequestClient,\n  buildApprovalUrl,\n  type DefaultAccessRequestClientOptions,\n  type FetchLike,\n} from \"./direct/access-request-client\";\nexport {\n  buildPersonalServerDataReadRequest,\n  readPersonalServerData,\n  parsePersonalServerPaymentRequired,\n  dataPathForScope,\n  type PersonalServerDataReadRequest,\n  type PersonalServerReadResult,\n  type PersonalServerFetch,\n  type PersonalServerTransportRetryOptions,\n  type FetchResponseLike,\n} from \"./direct/personal-server-read\";\n// Escrow-backed payment (built on protocol/escrow).\nexport {\n  authorizeEscrowPayment,\n  authorizeGrantPayment,\n  buildEscrowPaymentHeader,\n  buildGrantPaymentHeader,\n  paymentResponseMetadataFromHeader,\n  toDirectPaymentReceipt,\n  toDirectFeeBreakdown,\n  createDefaultNonceSource,\n  DATA_ACCESS_OP_TYPE,\n  GRANT_OP_TYPE,\n  type EscrowPaymentConfig,\n  type EscrowPaymentHeaderConfig,\n  type SignTypedDataFn,\n  type PaymentNonceSource,\n} from \"./direct/escrow-payment\";\nexport {\n  getDirectEndpoints,\n  PRODUCTION_ENDPOINTS,\n  DEV_ENDPOINTS,\n} from \"./direct/endpoints\";\n// Grant scope entries: the `[operation:]scope` vocabulary the controller's\n// `scopes` are written in, so a backend can build and read them without\n// reaching for a platform entry point.\nexport {\n  ScopeSchema,\n  parseScope,\n  scopeMatchesPattern,\n  scopeCoveredByGrant,\n  type Scope,\n  type ParsedScope,\n} from \"./protocol/scopes\";\nexport {\n  SCOPE_ACTIONS,\n  InvalidScopeEntryError,\n  parseScopeEntry,\n  formatScopeEntry,\n  grantPermissions,\n  permissionsToScopes,\n  tryGrantPermissions,\n  hasAction,\n  type ScopeAction,\n  type ParsedScopeEntry,\n  type GrantPermission,\n} from \"./protocol/scope-actions\";\n\n// Errors\nexport {\n  DirectConfigError,\n  AccessNotApprovedError,\n  ScopeNotApprovedError,\n  PersonalServerReadError,\n  PaymentRequiredError,\n} from \"./direct/errors\";\n\n// Shared types\nexport type {\n  DirectEnv,\n  DirectNetwork,\n  DirectAppConfig,\n  ForegroundDelivery,\n  AppIdentity,\n  DirectServiceEndpoints,\n  AccessRequest,\n  AccessRequestStatus,\n  AccessRequestStatusValue,\n  ApprovedDataResult,\n  MultiScopeDataResult,\n  AccessRequestClient,\n  DirectOpTypeValue,\n  PersonalServerDataAccessPaymentOperation,\n  PersonalServerGrantPaymentOperation,\n  PersonalServerPaymentOperation,\n  PersonalServerPaymentRequired,\n  DirectPaymentReceipt,\n  DirectPaymentResponseMetadata,\n  DirectFeeBreakdown,\n} from \"./direct/types\";\n\n// Op-type vocabulary constant.\nexport { DirectOpType } from \"./direct/types\";\n"],"mappings":"AAyBA;AAAA,EACE;AAAA,OAIK;AAGP;AAAA,EACE;AAAA,EACA;AAAA,OAGK;AACP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAMK;AAEP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAKK;AACP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAIP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAGK;AACP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAIK;AAGP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AA2BP,SAAS,oBAAoB;","names":[]}
+{"version":3,"sources":["../src/server.ts"],"sourcesContent":["/**\n * Server entry point for the Vana SDK direct Data Portability flow.\n *\n * @remarks\n * Exposes {@link createDirectDataController} and its supporting types/errors.\n * This is a Node/server entry point — it owns the app private key and must never\n * be imported into browser code.\n *\n * @example\n * ```typescript\n * import { createDirectDataController } from \"@opendatalabs/vana-sdk/server\";\n *\n * export const vana = createDirectDataController({\n *   env: process.env.VANA_ENV === \"dev\" ? \"dev\" : \"production\",\n *   appPrivateKey: process.env.VANA_APP_PRIVATE_KEY!,\n *   app: { id: \"notes-lens\", name: \"Notes Lens\", homepageUrl: process.env.VANA_APP_URL! },\n *   source: \"icloud_notes\",\n *   scopes: [\"icloud_notes.notes\"],\n * });\n * ```\n *\n * @category Direct\n * @module server\n */\n\nexport {\n  createDirectDataController,\n  type DirectDataController,\n  type DirectDataControllerConfig,\n  type DirectEscrowConfig,\n} from \"./direct/controller\";\n\n// Lower-level building blocks (advanced use / custom transports).\nexport {\n  createDefaultAccessRequestClient,\n  buildApprovalUrl,\n  validateAccessRequestQuestions,\n  type DefaultAccessRequestClientOptions,\n  type FetchLike,\n} from \"./direct/access-request-client\";\nexport {\n  buildPersonalServerDataReadRequest,\n  readPersonalServerData,\n  parsePersonalServerPaymentRequired,\n  dataPathForScope,\n  type PersonalServerDataReadRequest,\n  type PersonalServerReadResult,\n  type PersonalServerFetch,\n  type PersonalServerTransportRetryOptions,\n  type FetchResponseLike,\n} from \"./direct/personal-server-read\";\n// Escrow-backed payment (built on protocol/escrow).\nexport {\n  authorizeEscrowPayment,\n  authorizeGrantPayment,\n  buildEscrowPaymentHeader,\n  buildGrantPaymentHeader,\n  paymentResponseMetadataFromHeader,\n  toDirectPaymentReceipt,\n  toDirectFeeBreakdown,\n  createDefaultNonceSource,\n  DATA_ACCESS_OP_TYPE,\n  GRANT_OP_TYPE,\n  type EscrowPaymentConfig,\n  type EscrowPaymentHeaderConfig,\n  type SignTypedDataFn,\n  type PaymentNonceSource,\n} from \"./direct/escrow-payment\";\nexport {\n  getDirectEndpoints,\n  PRODUCTION_ENDPOINTS,\n  DEV_ENDPOINTS,\n} from \"./direct/endpoints\";\n// Grant scope entries: the `[operation:]scope` vocabulary the controller's\n// `scopes` are written in, so a backend can build and read them without\n// reaching for a platform entry point.\nexport {\n  ScopeSchema,\n  parseScope,\n  scopeMatchesPattern,\n  scopeCoveredByGrant,\n  type Scope,\n  type ParsedScope,\n} from \"./protocol/scopes\";\nexport {\n  SCOPE_ACTIONS,\n  InvalidScopeEntryError,\n  parseScopeEntry,\n  formatScopeEntry,\n  grantPermissions,\n  permissionsToScopes,\n  tryGrantPermissions,\n  hasAction,\n  type ScopeAction,\n  type ParsedScopeEntry,\n  type GrantPermission,\n} from \"./protocol/scope-actions\";\n\n// Errors\nexport {\n  DirectConfigError,\n  AccessNotApprovedError,\n  ScopeNotApprovedError,\n  PersonalServerReadError,\n  PaymentRequiredError,\n} from \"./direct/errors\";\n\n// Shared types\nexport type {\n  DirectEnv,\n  DirectNetwork,\n  DirectAppConfig,\n  ForegroundDelivery,\n  AppIdentity,\n  DirectServiceEndpoints,\n  AccessRequest,\n  AccessRequestQuestion,\n  AccessRequestStatus,\n  AccessRequestStatusValue,\n  ApprovedDataResult,\n  MultiScopeDataResult,\n  AccessRequestClient,\n  DirectOpTypeValue,\n  PersonalServerDataAccessPaymentOperation,\n  PersonalServerGrantPaymentOperation,\n  PersonalServerPaymentOperation,\n  PersonalServerPaymentRequired,\n  DirectPaymentReceipt,\n  DirectPaymentResponseMetadata,\n  DirectFeeBreakdown,\n} from \"./direct/types\";\n\n// Op-type vocabulary constant.\nexport { DirectOpType } from \"./direct/types\";\n"],"mappings":"AAyBA;AAAA,EACE;AAAA,OAIK;AAGP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OAGK;AACP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAMK;AAEP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAKK;AACP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAIP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAGK;AACP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAIK;AAGP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AA4BP,SAAS,oBAAoB;","names":[]}

package/dist/tests/mock-personal-server.d.ts

@@ -84,6 +84,13 @@ export interface MockQuestion {
     };
     status: "pending" | "ready" | "failed" | "stale";
     error: string | null;
+    /** The coarse failure class the status route serves; null unless failed. */
+    errorCode: "inference_unavailable" | "source_missing" | "grant_invalid" | "internal" | null;
+    /**
+     * What the status route reports as the next automatic retry. The mock has
+     * no scheduler, so a test sets it through `settleQuestion`.
+     */
+    retryAfterSeconds: number | null;
     createdAt: string;
     updatedAt: string;
     lastComputedAt: string | null;
@@ -126,6 +133,8 @@ export interface MockPersonalServer {
     } | {
         status: "failed";
         error: string;
+        errorCode?: MockQuestion["errorCode"];
+        retryAfterSeconds?: number | null;
     } | {
         status: "stale" | "pending";
     }): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendatalabs/vana-sdk",
-  "version": "3.20.1",
+  "version": "3.22.0-pr.207.0dbb052",
   "description": "A TypeScript library for interacting with Vana Network smart contracts.",
   "publishConfig": {
     "access": "public"