@opendatalabs/vana-sdk 3.0.1 → 3.2.0

package/dist/account/personal-server-registration.js

@@ -0,0 +1,240 @@
+import { isAddress } from "viem";
+import {
+  buildPersonalServerRegistrationTypedData,
+  personalServerRegistrationDomain
+} from "../protocol/personal-server-registration.js";
+import { SERVER_REGISTRATION_TYPES } from "../protocol/eip712.js";
+const ACCOUNT_PERSONAL_SERVER_REGISTRATION_INTENT = "personal_server.server_registration.v1";
+class AccountPersonalServerRegistrationError extends Error {
+  status;
+  code;
+  details;
+  constructor(input) {
+    super(input.message);
+    this.name = "AccountPersonalServerRegistrationError";
+    this.status = input.status;
+    this.code = input.code;
+    this.details = input.details;
+  }
+}
+const DEFAULT_ACCOUNT_PS_REGISTRATION_PATH = "/api/v1/intents/personal-server-registration/sign";
+function trimTrailingSlash(value) {
+  return value.replace(/\/+$/, "");
+}
+function assertAddress(value, name) {
+  if (!isAddress(value)) {
+    throw new Error(`${name} must be a valid EVM address`);
+  }
+}
+async function parseAccountResponse(response) {
+  const body = await response.json().catch(() => void 0);
+  if (!response.ok) {
+    throw new AccountPersonalServerRegistrationError({
+      status: response.status,
+      code: accountErrorCode(body),
+      message: accountErrorMessage(response.status, body),
+      details: body
+    });
+  }
+  return body;
+}
+function accountErrorMessage(status, body) {
+  const nestedMessage = nestedAccountErrorField(body, "message");
+  if (nestedMessage) {
+    return nestedMessage;
+  }
+  if (isRecord(body) && typeof body.message === "string") {
+    return body.message;
+  }
+  const code = accountErrorCode(body);
+  if (code) {
+    return `Account PS registration signing failed: ${code}`;
+  }
+  return `Account PS registration signing failed: ${status}`;
+}
+function accountErrorCode(body) {
+  const nestedCode = nestedAccountErrorField(body, "code");
+  if (nestedCode) {
+    return nestedCode;
+  }
+  if (isRecord(body)) {
+    if (typeof body.code === "string") {
+      return body.code;
+    }
+    if (typeof body.error === "string") {
+      return body.error;
+    }
+  }
+  return void 0;
+}
+function nestedAccountErrorField(body, field) {
+  if (!isRecord(body) || !isRecord(body.error)) {
+    return void 0;
+  }
+  const value = body.error[field];
+  return typeof value === "string" ? value : void 0;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function normalizeAccountResponse(response) {
+  return {
+    ...response,
+    status: response.status === "fallback_required" ? "confirmation_required" : response.status,
+    signerAddress: response.signerAddress ?? response.signer?.address,
+    typedData: response.typedData ?? response.typed_data
+  };
+}
+function buildSignedResult(response, request) {
+  assertAddress(response.signerAddress, "signerAddress");
+  if (response.typedData) {
+    assertTypedDataMatchesRequest(
+      response.typedData,
+      request,
+      response.signerAddress
+    );
+  }
+  return {
+    signature: response.signature,
+    signerAddress: response.signerAddress,
+    typedData: response.typedData ?? buildPersonalServerRegistrationTypedData({
+      ownerAddress: response.signerAddress,
+      ...request
+    }),
+    intent: ACCOUNT_PERSONAL_SERVER_REGISTRATION_INTENT
+  };
+}
+function assertTypedDataMatchesRequest(typedData, request, expectedSignerAddress) {
+  assertAddress(
+    typedData.message.ownerAddress,
+    "typedData.message.ownerAddress"
+  );
+  assertAddress(
+    typedData.message.serverAddress,
+    "typedData.message.serverAddress"
+  );
+  if (expectedSignerAddress && !sameAddress(typedData.message.ownerAddress, expectedSignerAddress)) {
+    throw new Error(
+      "Account typedData ownerAddress must match the expected signer address"
+    );
+  }
+  if (!sameAddress(typedData.message.serverAddress, request.serverAddress)) {
+    throw new Error(
+      "Account typedData serverAddress must match the requested serverAddress"
+    );
+  }
+  if (typedData.message.publicKey !== request.serverPublicKey) {
+    throw new Error(
+      "Account typedData publicKey must match the requested serverPublicKey"
+    );
+  }
+  if (typedData.message.serverUrl !== request.serverUrl) {
+    throw new Error(
+      "Account typedData serverUrl must match the requested serverUrl"
+    );
+  }
+  if (typedData.primaryType !== "ServerRegistration") {
+    throw new Error("Account typedData primaryType must be ServerRegistration");
+  }
+  if (JSON.stringify(typedData.types) !== JSON.stringify(SERVER_REGISTRATION_TYPES)) {
+    throw new Error("Account typedData types must be ServerRegistration types");
+  }
+  const expectedDomain = personalServerRegistrationDomain({
+    config: request.config,
+    chainId: request.chainId,
+    verifyingContract: request.verifyingContract
+  });
+  if (!domainsEqual(typedData.domain, expectedDomain)) {
+    throw new Error("Account typedData domain must match the requested domain");
+  }
+}
+function sameAddress(a, b) {
+  return a.toLowerCase() === b.toLowerCase();
+}
+function domainsEqual(a, b) {
+  if (!a || !b) {
+    return false;
+  }
+  return a.name === b.name && a.version === b.version && Number(a.chainId) === Number(b.chainId) && String(a.verifyingContract ?? "").toLowerCase() === String(b.verifyingContract ?? "").toLowerCase() && a.salt === b.salt;
+}
+async function signPersonalServerRegistrationWithAccount(config, request) {
+  assertAddress(request.serverAddress, "serverAddress");
+  const fetchImpl = config.fetchImpl ?? globalThis.fetch.bind(globalThis);
+  const endpoint = new URL(
+    config.endpointPath ?? DEFAULT_ACCOUNT_PS_REGISTRATION_PATH,
+    `${trimTrailingSlash(config.accountOrigin)}/`
+  );
+  const response = await fetchImpl(endpoint, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    credentials: "include",
+    body: JSON.stringify({
+      intent: ACCOUNT_PERSONAL_SERVER_REGISTRATION_INTENT,
+      serverAddress: request.serverAddress,
+      serverPublicKey: request.serverPublicKey,
+      serverUrl: request.serverUrl,
+      config: request.config,
+      chainId: request.chainId,
+      verifyingContract: request.verifyingContract
+    })
+  });
+  const body = normalizeAccountResponse(await parseAccountResponse(response));
+  if (body.status === "signed") {
+    if (!body.signature || !body.signerAddress) {
+      throw new Error(
+        "Account signed response must include signature and signerAddress"
+      );
+    }
+    return {
+      status: "signed",
+      result: buildSignedResult(
+        {
+          signature: body.signature,
+          signerAddress: body.signerAddress,
+          typedData: body.typedData
+        },
+        request
+      )
+    };
+  }
+  if (body.status === "confirmation_required") {
+    if (!body.typedData) {
+      throw new Error(
+        "Account confirmation_required response must include typedData"
+      );
+    }
+    assertTypedDataMatchesRequest(body.typedData, request, body.signerAddress);
+    if (!config.fallbackSigner) {
+      return {
+        status: "confirmation_required",
+        typedData: body.typedData,
+        signerAddress: body.signerAddress
+      };
+    }
+    assertTypedDataMatchesRequest(
+      body.typedData,
+      request,
+      config.fallbackSigner.address
+    );
+    const signature = await config.fallbackSigner.signTypedData(body.typedData);
+    return {
+      status: "fallback_signed",
+      accountStatus: "confirmation_required",
+      result: {
+        signature,
+        signerAddress: config.fallbackSigner.address,
+        typedData: body.typedData,
+        intent: ACCOUNT_PERSONAL_SERVER_REGISTRATION_INTENT
+      }
+    };
+  }
+  throw new Error(
+    `Unsupported Account PS registration signing status: ${String(body.status)}`
+  );
+}
+export {
+  ACCOUNT_PERSONAL_SERVER_REGISTRATION_INTENT,
+  AccountPersonalServerRegistrationError,
+  signPersonalServerRegistrationWithAccount
+};
+//# sourceMappingURL=personal-server-registration.js.map

package/dist/account/personal-server-registration.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/account/personal-server-registration.ts"],"sourcesContent":["/**\n * Optional first-party Account integration for Personal Server registration.\n *\n * The protocol helper lives in `protocol/personal-server-registration`.\n * This module is only for callers that want to use an Account deployment's\n * constrained silent-sign endpoint.\n *\n * @category Account\n */\n\nimport { isAddress, type Address, type Hex } from \"viem\";\nimport {\n  buildPersonalServerRegistrationTypedData,\n  type BuildPersonalServerRegistrationTypedDataInput,\n  type PersonalServerRegistrationSignature,\n  type PersonalServerRegistrationSigner,\n  type PersonalServerRegistrationTypedData,\n  personalServerRegistrationDomain,\n} from \"../protocol/personal-server-registration\";\nimport { SERVER_REGISTRATION_TYPES } from \"../protocol/eip712\";\n\nexport const ACCOUNT_PERSONAL_SERVER_REGISTRATION_INTENT =\n  \"personal_server.server_registration.v1\" as const;\n\nexport type AccountPersonalServerRegistrationIntent =\n  typeof ACCOUNT_PERSONAL_SERVER_REGISTRATION_INTENT;\n\nexport type AccountPersonalServerRegistrationStatus =\n  | \"signed\"\n  | \"confirmation_required\"\n  | \"fallback_required\";\n\nexport interface AccountPersonalServerRegistrationRequest extends Omit<\n  BuildPersonalServerRegistrationTypedDataInput,\n  \"ownerAddress\"\n> {}\n\nexport interface AccountPersonalServerRegistrationConfig {\n  /**\n   * Origin for the Account deployment to call, e.g. an app-dev Account origin.\n   * No production origin is assumed by the SDK.\n   */\n  accountOrigin: string;\n  /**\n   * Path for Account's constrained PS registration silent-sign endpoint.\n   */\n  endpointPath?: string;\n  /**\n   * Optional fetch implementation for tests and non-default runtimes.\n   */\n  fetchImpl?: typeof fetch;\n  /**\n   * Optional signer used when Account says user confirmation is required and\n   * returns typed data for the caller to sign interactively.\n   */\n  fallbackSigner?: PersonalServerRegistrationSigner;\n}\n\nexport type AccountPersonalServerRegistrationSignature =\n  PersonalServerRegistrationSignature & {\n    intent: AccountPersonalServerRegistrationIntent;\n  };\n\nexport interface AccountSignedPersonalServerRegistration {\n  status: \"signed\";\n  result: AccountPersonalServerRegistrationSignature;\n}\n\nexport interface AccountConfirmationRequiredPersonalServerRegistration {\n  status: \"confirmation_required\";\n  typedData: PersonalServerRegistrationTypedData;\n  signerAddress?: Address;\n}\n\nexport interface AccountFallbackSignedPersonalServerRegistration {\n  status: \"fallback_signed\";\n  accountStatus: \"confirmation_required\";\n  result: AccountPersonalServerRegistrationSignature;\n}\n\nexport type AccountPersonalServerRegistrationResult =\n  | AccountSignedPersonalServerRegistration\n  | AccountConfirmationRequiredPersonalServerRegistration\n  | AccountFallbackSignedPersonalServerRegistration;\n\nexport class AccountPersonalServerRegistrationError extends Error {\n  status: number;\n  code?: string;\n  details?: unknown;\n\n  constructor(input: {\n    status: number;\n    message: string;\n    code?: string;\n    details?: unknown;\n  }) {\n    super(input.message);\n    this.name = \"AccountPersonalServerRegistrationError\";\n    this.status = input.status;\n    this.code = input.code;\n    this.details = input.details;\n  }\n}\n\ninterface AccountSilentSignResponse {\n  status: AccountPersonalServerRegistrationStatus;\n  signature?: Hex;\n  signerAddress?: Address;\n  signer?: { address?: Address };\n  typedData?: PersonalServerRegistrationTypedData;\n  typed_data?: PersonalServerRegistrationTypedData;\n  error?: unknown;\n}\n\n// Account-owned route policy. Protocol signing primitives deliberately do not\n// define Account intent names or API paths.\nconst DEFAULT_ACCOUNT_PS_REGISTRATION_PATH =\n  \"/api/v1/intents/personal-server-registration/sign\";\n\nfunction trimTrailingSlash(value: string): string {\n  return value.replace(/\\/+$/, \"\");\n}\n\nfunction assertAddress(value: Address, name: string): void {\n  if (!isAddress(value)) {\n    throw new Error(`${name} must be a valid EVM address`);\n  }\n}\n\nasync function parseAccountResponse(\n  response: Response,\n): Promise<AccountSilentSignResponse> {\n  const body = (await response.json().catch(() => undefined)) as unknown;\n\n  if (!response.ok) {\n    throw new AccountPersonalServerRegistrationError({\n      status: response.status,\n      code: accountErrorCode(body),\n      message: accountErrorMessage(response.status, body),\n      details: body,\n    });\n  }\n\n  return body as AccountSilentSignResponse;\n}\n\nfunction accountErrorMessage(status: number, body: unknown): string {\n  const nestedMessage = nestedAccountErrorField(body, \"message\");\n  if (nestedMessage) {\n    return nestedMessage;\n  }\n\n  if (isRecord(body) && typeof body.message === \"string\") {\n    return body.message;\n  }\n\n  const code = accountErrorCode(body);\n  if (code) {\n    return `Account PS registration signing failed: ${code}`;\n  }\n\n  return `Account PS registration signing failed: ${status}`;\n}\n\nfunction accountErrorCode(body: unknown): string | undefined {\n  const nestedCode = nestedAccountErrorField(body, \"code\");\n  if (nestedCode) {\n    return nestedCode;\n  }\n\n  if (isRecord(body)) {\n    if (typeof body.code === \"string\") {\n      return body.code;\n    }\n    if (typeof body.error === \"string\") {\n      return body.error;\n    }\n  }\n\n  return undefined;\n}\n\nfunction nestedAccountErrorField(\n  body: unknown,\n  field: \"code\" | \"message\",\n): string | undefined {\n  if (!isRecord(body) || !isRecord(body.error)) {\n    return undefined;\n  }\n\n  const value = body.error[field];\n  return typeof value === \"string\" ? value : undefined;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null;\n}\n\nfunction normalizeAccountResponse(\n  response: AccountSilentSignResponse,\n): AccountSilentSignResponse {\n  return {\n    ...response,\n    status:\n      response.status === \"fallback_required\"\n        ? \"confirmation_required\"\n        : response.status,\n    signerAddress: response.signerAddress ?? response.signer?.address,\n    typedData: response.typedData ?? response.typed_data,\n  };\n}\n\nfunction buildSignedResult(\n  response: Required<\n    Pick<AccountSilentSignResponse, \"signature\" | \"signerAddress\">\n  > &\n    Pick<AccountSilentSignResponse, \"typedData\">,\n  request: AccountPersonalServerRegistrationRequest,\n): AccountPersonalServerRegistrationSignature {\n  assertAddress(response.signerAddress, \"signerAddress\");\n  if (response.typedData) {\n    assertTypedDataMatchesRequest(\n      response.typedData,\n      request,\n      response.signerAddress,\n    );\n  }\n\n  return {\n    signature: response.signature,\n    signerAddress: response.signerAddress,\n    typedData:\n      response.typedData ??\n      buildPersonalServerRegistrationTypedData({\n        ownerAddress: response.signerAddress,\n        ...request,\n      }),\n    intent: ACCOUNT_PERSONAL_SERVER_REGISTRATION_INTENT,\n  };\n}\n\nfunction assertTypedDataMatchesRequest(\n  typedData: PersonalServerRegistrationTypedData,\n  request: AccountPersonalServerRegistrationRequest,\n  expectedSignerAddress?: Address,\n): void {\n  assertAddress(\n    typedData.message.ownerAddress,\n    \"typedData.message.ownerAddress\",\n  );\n  assertAddress(\n    typedData.message.serverAddress,\n    \"typedData.message.serverAddress\",\n  );\n\n  if (\n    expectedSignerAddress &&\n    !sameAddress(typedData.message.ownerAddress, expectedSignerAddress)\n  ) {\n    throw new Error(\n      \"Account typedData ownerAddress must match the expected signer address\",\n    );\n  }\n\n  if (!sameAddress(typedData.message.serverAddress, request.serverAddress)) {\n    throw new Error(\n      \"Account typedData serverAddress must match the requested serverAddress\",\n    );\n  }\n\n  if (typedData.message.publicKey !== request.serverPublicKey) {\n    throw new Error(\n      \"Account typedData publicKey must match the requested serverPublicKey\",\n    );\n  }\n\n  if (typedData.message.serverUrl !== request.serverUrl) {\n    throw new Error(\n      \"Account typedData serverUrl must match the requested serverUrl\",\n    );\n  }\n\n  if (typedData.primaryType !== \"ServerRegistration\") {\n    throw new Error(\"Account typedData primaryType must be ServerRegistration\");\n  }\n\n  if (\n    JSON.stringify(typedData.types) !==\n    JSON.stringify(SERVER_REGISTRATION_TYPES)\n  ) {\n    throw new Error(\"Account typedData types must be ServerRegistration types\");\n  }\n\n  const expectedDomain = personalServerRegistrationDomain({\n    config: request.config,\n    chainId: request.chainId,\n    verifyingContract: request.verifyingContract,\n  });\n  if (!domainsEqual(typedData.domain, expectedDomain)) {\n    throw new Error(\"Account typedData domain must match the requested domain\");\n  }\n}\n\nfunction sameAddress(a: Address, b: Address): boolean {\n  return a.toLowerCase() === b.toLowerCase();\n}\n\nfunction domainsEqual(\n  a: PersonalServerRegistrationTypedData[\"domain\"],\n  b: PersonalServerRegistrationTypedData[\"domain\"],\n): boolean {\n  if (!a || !b) {\n    return false;\n  }\n\n  return (\n    a.name === b.name &&\n    a.version === b.version &&\n    Number(a.chainId) === Number(b.chainId) &&\n    String(a.verifyingContract ?? \"\").toLowerCase() ===\n      String(b.verifyingContract ?? \"\").toLowerCase() &&\n    a.salt === b.salt\n  );\n}\n\nexport async function signPersonalServerRegistrationWithAccount(\n  config: AccountPersonalServerRegistrationConfig,\n  request: AccountPersonalServerRegistrationRequest,\n): Promise<AccountPersonalServerRegistrationResult> {\n  assertAddress(request.serverAddress, \"serverAddress\");\n\n  const fetchImpl = config.fetchImpl ?? globalThis.fetch.bind(globalThis);\n  const endpoint = new URL(\n    config.endpointPath ?? DEFAULT_ACCOUNT_PS_REGISTRATION_PATH,\n    `${trimTrailingSlash(config.accountOrigin)}/`,\n  );\n\n  const response = await fetchImpl(endpoint, {\n    method: \"POST\",\n    headers: { \"content-type\": \"application/json\" },\n    credentials: \"include\",\n    body: JSON.stringify({\n      intent: ACCOUNT_PERSONAL_SERVER_REGISTRATION_INTENT,\n      serverAddress: request.serverAddress,\n      serverPublicKey: request.serverPublicKey,\n      serverUrl: request.serverUrl,\n      config: request.config,\n      chainId: request.chainId,\n      verifyingContract: request.verifyingContract,\n    }),\n  });\n  const body = normalizeAccountResponse(await parseAccountResponse(response));\n\n  if (body.status === \"signed\") {\n    if (!body.signature || !body.signerAddress) {\n      throw new Error(\n        \"Account signed response must include signature and signerAddress\",\n      );\n    }\n\n    return {\n      status: \"signed\",\n      result: buildSignedResult(\n        {\n          signature: body.signature,\n          signerAddress: body.signerAddress,\n          typedData: body.typedData,\n        },\n        request,\n      ),\n    };\n  }\n\n  if (body.status === \"confirmation_required\") {\n    if (!body.typedData) {\n      throw new Error(\n        \"Account confirmation_required response must include typedData\",\n      );\n    }\n    assertTypedDataMatchesRequest(body.typedData, request, body.signerAddress);\n\n    if (!config.fallbackSigner) {\n      return {\n        status: \"confirmation_required\",\n        typedData: body.typedData,\n        signerAddress: body.signerAddress,\n      };\n    }\n\n    assertTypedDataMatchesRequest(\n      body.typedData,\n      request,\n      config.fallbackSigner.address,\n    );\n    const signature = await config.fallbackSigner.signTypedData(body.typedData);\n\n    return {\n      status: \"fallback_signed\",\n      accountStatus: \"confirmation_required\",\n      result: {\n        signature,\n        signerAddress: config.fallbackSigner.address,\n        typedData: body.typedData,\n        intent: ACCOUNT_PERSONAL_SERVER_REGISTRATION_INTENT,\n      },\n    };\n  }\n\n  throw new Error(\n    `Unsupported Account PS registration signing status: ${String(body.status)}`,\n  );\n}\n"],"mappings":"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","names":[]}

package/dist/account/personal-server-registration.test.d.ts

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

package/dist/auth/errors.js

@@ -1,4 +1,4 @@
-import { VanaError } from "../errors";
+import { VanaError } from "../errors.js";
 class MissingAuthError extends VanaError {
   constructor(message = "Missing authentication", details) {
     super(message, "MISSING_AUTH");

package/dist/auth/oauth-client.cjs

@@ -0,0 +1,250 @@
+"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 oauth_client_exports = {};
+__export(oauth_client_exports, {
+  OAuthClient: () => OAuthClient
+});
+module.exports = __toCommonJS(oauth_client_exports);
+var import_pkce = require("./pkce");
+var import_token_store = require("./token-store");
+const VERIFIER_TTL_SECONDS = 600;
+const RESERVED_AUTHORIZE_PARAMS = /* @__PURE__ */ new Set([
+  "response_type",
+  "client_id",
+  "redirect_uri",
+  "scope",
+  "state",
+  "code_challenge",
+  "code_challenge_method"
+]);
+class OAuthClient {
+  #config;
+  constructor(config) {
+    const fetchImpl = config.fetchImpl ?? globalThis.fetch;
+    if (typeof fetchImpl !== "function") {
+      throw new TypeError(
+        "OAuthClient requires a global `fetch` or an explicit `fetchImpl`"
+      );
+    }
+    this.#config = {
+      authorizationEndpoint: config.authorizationEndpoint,
+      tokenEndpoint: config.tokenEndpoint,
+      clientId: config.clientId,
+      redirectUri: config.redirectUri,
+      scope: config.scope,
+      tokenStore: config.tokenStore ?? new import_token_store.InMemoryTokenStore(),
+      fetchImpl,
+      generateState: config.generateState ?? defaultGenerateState
+    };
+  }
+  /** Build the authorize URL and persist the PKCE verifier keyed by `state`. */
+  async buildAuthorizationUrl(opts = {}) {
+    const state = opts.state ?? this.#config.generateState();
+    const scope = opts.scope ?? this.#config.scope;
+    const verifier = (0, import_pkce.generatePkceVerifier)();
+    const challenge = await (0, import_pkce.computePkceChallenge)(verifier);
+    await this.#config.tokenStore.set(this.#verifierKey(state), {
+      token: verifier,
+      expiresAt: Math.floor(Date.now() / 1e3) + VERIFIER_TTL_SECONDS
+    });
+    const params = new URLSearchParams();
+    params.set("response_type", "code");
+    params.set("client_id", this.#config.clientId);
+    params.set("redirect_uri", this.#config.redirectUri);
+    if (scope !== void 0 && scope.length > 0) {
+      params.set("scope", scope);
+    }
+    params.set("state", state);
+    params.set("code_challenge", challenge);
+    params.set("code_challenge_method", "S256");
+    if (opts.extraParams !== void 0) {
+      for (const k of Object.keys(opts.extraParams)) {
+        if (RESERVED_AUTHORIZE_PARAMS.has(k)) {
+          throw new Error(
+            `extraParams may not override the reserved OAuth/PKCE parameter "${k}"`
+          );
+        }
+      }
+      for (const [k, v] of Object.entries(opts.extraParams)) {
+        params.set(k, v);
+      }
+    }
+    const sep = this.#config.authorizationEndpoint.includes("?") ? "&" : "?";
+    const url = `${this.#config.authorizationEndpoint}${sep}${params.toString()}`;
+    return { url, state };
+  }
+  /**
+   * Handle the redirect-callback URL. Validates `state`, retrieves the saved
+   * verifier, exchanges the authorization code + verifier for tokens, and
+   * persists them. Returns the access {@link TokenRecord}.
+   */
+  async handleCallback(callbackUrl) {
+    const parsed = new URL(callbackUrl);
+    const params = parsed.searchParams;
+    const errorCode = params.get("error");
+    if (errorCode !== null) {
+      throw new Error(
+        formatOAuthError({
+          error: errorCode,
+          error_description: params.get("error_description") ?? void 0
+        })
+      );
+    }
+    const code = params.get("code");
+    const state = params.get("state");
+    if (code === null || state === null) {
+      throw new Error("OAuth callback is missing `code` or `state`");
+    }
+    const verifierRecord = await this.#config.tokenStore.get(
+      this.#verifierKey(state)
+    );
+    if (verifierRecord === null) {
+      throw new Error(
+        "OAuth callback state does not match any in-flight verifier (possible CSRF or expired flow)"
+      );
+    }
+    const body = new URLSearchParams();
+    body.set("grant_type", "authorization_code");
+    body.set("code", code);
+    body.set("redirect_uri", this.#config.redirectUri);
+    body.set("client_id", this.#config.clientId);
+    body.set("code_verifier", verifierRecord.token);
+    let tokens;
+    try {
+      tokens = await this.#tokenRequest(body);
+    } finally {
+      await this.#config.tokenStore.delete(this.#verifierKey(state));
+    }
+    return this.#persistTokens(tokens);
+  }
+  /**
+   * Exchange a stored refresh token for a fresh access token. Throws if no
+   * refresh token is available.
+   */
+  async refresh() {
+    const refreshRecord = await this.#config.tokenStore.get(this.#refreshKey());
+    if (refreshRecord === null) {
+      throw new Error("OAuth refresh failed: no refresh token stored");
+    }
+    const body = new URLSearchParams();
+    body.set("grant_type", "refresh_token");
+    body.set("refresh_token", refreshRecord.token);
+    body.set("client_id", this.#config.clientId);
+    const tokens = await this.#tokenRequest(body);
+    return this.#persistTokens(tokens, refreshRecord.token);
+  }
+  /**
+   * Get the current access token if valid (refreshing first if expired and a
+   * refresh token is available). Returns `null` when no usable token exists.
+   */
+  async getAccessToken() {
+    const stored = await this.#config.tokenStore.get(this.#accessKey());
+    if (stored !== null) return stored.token;
+    const refresh = await this.#config.tokenStore.get(this.#refreshKey());
+    if (refresh === null) return null;
+    try {
+      const refreshed = await this.refresh();
+      return refreshed.token;
+    } catch {
+      return null;
+    }
+  }
+  /** Forget tokens (logout). Does NOT call any remote revocation endpoint. */
+  async signOut() {
+    await this.#config.tokenStore.delete(this.#accessKey());
+    await this.#config.tokenStore.delete(this.#refreshKey());
+  }
+  #accessKey() {
+    return `oauth:tokens:${this.#config.clientId}`;
+  }
+  #refreshKey() {
+    return `oauth:refresh:${this.#config.clientId}`;
+  }
+  #verifierKey(state) {
+    return `oauth:verifier:${state}`;
+  }
+  async #tokenRequest(body) {
+    const response = await this.#config.fetchImpl(this.#config.tokenEndpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json"
+      },
+      body: body.toString()
+    });
+    const text = await response.text();
+    const parsed = parseJsonBody(text);
+    if (!response.ok) {
+      throw new Error(formatOAuthError(parsed ?? {}, response.status));
+    }
+    if (parsed === null || typeof parsed !== "object" || typeof parsed.access_token !== "string") {
+      throw new Error(
+        "OAuth token endpoint returned a response without an `access_token` string"
+      );
+    }
+    return parsed;
+  }
+  async #persistTokens(tokens, previousRefreshToken) {
+    const record = { token: tokens.access_token };
+    if (typeof tokens.expires_in === "number" && tokens.expires_in > 0) {
+      record.expiresAt = Math.floor(Date.now() / 1e3) + tokens.expires_in;
+    }
+    await this.#config.tokenStore.set(this.#accessKey(), record);
+    const newRefresh = tokens.refresh_token ?? previousRefreshToken;
+    if (newRefresh !== void 0) {
+      await this.#config.tokenStore.set(this.#refreshKey(), {
+        token: newRefresh
+      });
+    }
+    return record;
+  }
+}
+function defaultGenerateState() {
+  const bytes = new Uint8Array(24);
+  crypto.getRandomValues(bytes);
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function parseJsonBody(text) {
+  if (text.length === 0) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+function formatOAuthError(body, status) {
+  const parts = ["OAuth token request failed"];
+  if (status !== void 0) parts.push(`(HTTP ${String(status)})`);
+  if (body.error !== void 0 && body.error.length > 0) {
+    parts.push(`: ${body.error}`);
+    if (body.error_description !== void 0 && body.error_description.length > 0) {
+      parts.push(`- ${body.error_description}`);
+    }
+  }
+  return parts.join(" ").replace(" : ", ": ").replace(" - ", " - ");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  OAuthClient
+});
+//# sourceMappingURL=oauth-client.cjs.map

package/dist/auth/oauth-client.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/auth/oauth-client.ts"],"sourcesContent":["/**\n * OAuth 2.0 Authorization Code + PKCE client orchestration.\n *\n * @remarks\n * Drives the full authorize → callback → token-exchange → refresh dance on top\n * of the {@link TokenStore} and PKCE primitives that ship with this package.\n * Implements RFC 6749 §4.1 with the RFC 7636 PKCE extension (S256 only).\n *\n * @category Auth\n * @module auth/oauth-client\n */\n\nimport { computePkceChallenge, generatePkceVerifier } from \"./pkce\";\nimport {\n  InMemoryTokenStore,\n  type TokenRecord,\n  type TokenStore,\n} from \"./token-store\";\n\n/**\n * Constructor options for {@link OAuthClient}.\n */\nexport interface OAuthClientConfig {\n  /** Authorization endpoint, e.g. `https://account.vana.org/oauth/authorize`. */\n  authorizationEndpoint: string;\n  /** Token endpoint, e.g. `https://account.vana.org/oauth/token`. */\n  tokenEndpoint: string;\n  /** OAuth `client_id` (public; PKCE protects the flow). */\n  clientId: string;\n  /** Redirect URI registered with the authorization server. */\n  redirectUri: string;\n  /** Default scope; can be overridden per call. */\n  scope?: string;\n  /**\n   * Where to persist access + refresh tokens and the in-flight code verifier\n   * between `authorize` → `callback`. Defaults to a fresh\n   * {@link InMemoryTokenStore}. Use IndexedDB/localStorage-backed\n   * implementations for browser apps where the user navigates away during the\n   * dance.\n   */\n  tokenStore?: TokenStore;\n  /** Override the global `fetch` (e.g. for tests). Defaults to `globalThis.fetch`. */\n  fetchImpl?: typeof fetch;\n  /**\n   * Override the random-state generator (mostly for tests). Must return a\n   * URL-safe string of >= 16 bytes of entropy.\n   */\n  generateState?: () => string;\n}\n\n/**\n * Result of {@link OAuthClient.buildAuthorizationUrl}.\n */\nexport interface AuthorizationUrlResult {\n  /** The full authorize URL to redirect / `window.open` to. */\n  url: string;\n  /** The `state` value the auth server will echo back; used for CSRF check. */\n  state: string;\n}\n\n/** TTL for the in-flight verifier record (seconds). */\nconst VERIFIER_TTL_SECONDS = 600;\n\n/** RFC 6749 spec-compliant OAuth error payload shape. */\ninterface OAuthErrorBody {\n  error?: string;\n  error_description?: string;\n  error_uri?: string;\n}\n\n/** Successful token-endpoint response shape (RFC 6749 §5.1). */\ninterface TokenEndpointResponse {\n  access_token: string;\n  token_type?: string;\n  expires_in?: number;\n  refresh_token?: string;\n  scope?: string;\n}\n\n/**\n * Authorize-URL parameters the client owns. Callers may NOT supply these\n * via `extraParams` — otherwise PKCE/CSRF protection can be silently\n * bypassed (e.g. `extraParams: { state: \"x\" }` would store the verifier\n * under the generated state but send `x` on the wire, breaking the\n * callback CSRF check; `code_challenge_method` could downgrade S256).\n */\nconst RESERVED_AUTHORIZE_PARAMS = new Set([\n  \"response_type\",\n  \"client_id\",\n  \"redirect_uri\",\n  \"scope\",\n  \"state\",\n  \"code_challenge\",\n  \"code_challenge_method\",\n]);\n\n/**\n * OAuth 2.0 Authorization Code + PKCE client.\n *\n * @remarks\n * Storage layout under the supplied {@link TokenStore} (all keys namespaced):\n * - `oauth:tokens:{clientId}`  → access token record\n * - `oauth:refresh:{clientId}` → refresh token record (no expiry)\n * - `oauth:verifier:{state}`   → in-flight PKCE verifier (10 min TTL)\n *\n * @category Auth\n */\nexport class OAuthClient {\n  readonly #config: Required<\n    Omit<\n      OAuthClientConfig,\n      \"scope\" | \"tokenStore\" | \"fetchImpl\" | \"generateState\"\n    >\n  > & {\n    scope?: string;\n    tokenStore: TokenStore;\n    fetchImpl: typeof fetch;\n    generateState: () => string;\n  };\n\n  public constructor(config: OAuthClientConfig) {\n    const fetchImpl = config.fetchImpl ?? globalThis.fetch;\n    if (typeof fetchImpl !== \"function\") {\n      throw new TypeError(\n        \"OAuthClient requires a global `fetch` or an explicit `fetchImpl`\",\n      );\n    }\n\n    this.#config = {\n      authorizationEndpoint: config.authorizationEndpoint,\n      tokenEndpoint: config.tokenEndpoint,\n      clientId: config.clientId,\n      redirectUri: config.redirectUri,\n      scope: config.scope,\n      tokenStore: config.tokenStore ?? new InMemoryTokenStore(),\n      fetchImpl,\n      generateState: config.generateState ?? defaultGenerateState,\n    };\n  }\n\n  /** Build the authorize URL and persist the PKCE verifier keyed by `state`. */\n  public async buildAuthorizationUrl(\n    opts: {\n      state?: string;\n      scope?: string;\n      extraParams?: Record<string, string>;\n    } = {},\n  ): Promise<AuthorizationUrlResult> {\n    const state = opts.state ?? this.#config.generateState();\n    const scope = opts.scope ?? this.#config.scope;\n\n    const verifier = generatePkceVerifier();\n    const challenge = await computePkceChallenge(verifier);\n\n    await this.#config.tokenStore.set(this.#verifierKey(state), {\n      token: verifier,\n      expiresAt: Math.floor(Date.now() / 1000) + VERIFIER_TTL_SECONDS,\n    });\n\n    const params = new URLSearchParams();\n    params.set(\"response_type\", \"code\");\n    params.set(\"client_id\", this.#config.clientId);\n    params.set(\"redirect_uri\", this.#config.redirectUri);\n    if (scope !== undefined && scope.length > 0) {\n      params.set(\"scope\", scope);\n    }\n    params.set(\"state\", state);\n    params.set(\"code_challenge\", challenge);\n    params.set(\"code_challenge_method\", \"S256\");\n    if (opts.extraParams !== undefined) {\n      for (const k of Object.keys(opts.extraParams)) {\n        if (RESERVED_AUTHORIZE_PARAMS.has(k)) {\n          throw new Error(\n            `extraParams may not override the reserved OAuth/PKCE parameter \"${k}\"`,\n          );\n        }\n      }\n      for (const [k, v] of Object.entries(opts.extraParams)) {\n        params.set(k, v);\n      }\n    }\n\n    const sep = this.#config.authorizationEndpoint.includes(\"?\") ? \"&\" : \"?\";\n    const url = `${this.#config.authorizationEndpoint}${sep}${params.toString()}`;\n\n    return { url, state };\n  }\n\n  /**\n   * Handle the redirect-callback URL. Validates `state`, retrieves the saved\n   * verifier, exchanges the authorization code + verifier for tokens, and\n   * persists them. Returns the access {@link TokenRecord}.\n   */\n  public async handleCallback(callbackUrl: string): Promise<TokenRecord> {\n    const parsed = new URL(callbackUrl);\n    const params = parsed.searchParams;\n\n    const errorCode = params.get(\"error\");\n    if (errorCode !== null) {\n      throw new Error(\n        formatOAuthError({\n          error: errorCode,\n          error_description: params.get(\"error_description\") ?? undefined,\n        }),\n      );\n    }\n\n    const code = params.get(\"code\");\n    const state = params.get(\"state\");\n    if (code === null || state === null) {\n      throw new Error(\"OAuth callback is missing `code` or `state`\");\n    }\n\n    const verifierRecord = await this.#config.tokenStore.get(\n      this.#verifierKey(state),\n    );\n    if (verifierRecord === null) {\n      throw new Error(\n        \"OAuth callback state does not match any in-flight verifier (possible CSRF or expired flow)\",\n      );\n    }\n\n    const body = new URLSearchParams();\n    body.set(\"grant_type\", \"authorization_code\");\n    body.set(\"code\", code);\n    body.set(\"redirect_uri\", this.#config.redirectUri);\n    body.set(\"client_id\", this.#config.clientId);\n    body.set(\"code_verifier\", verifierRecord.token);\n\n    let tokens: TokenEndpointResponse;\n    try {\n      tokens = await this.#tokenRequest(body);\n    } finally {\n      // Always clear the one-shot verifier, even on a failed exchange.\n      await this.#config.tokenStore.delete(this.#verifierKey(state));\n    }\n\n    return this.#persistTokens(tokens);\n  }\n\n  /**\n   * Exchange a stored refresh token for a fresh access token. Throws if no\n   * refresh token is available.\n   */\n  public async refresh(): Promise<TokenRecord> {\n    const refreshRecord = await this.#config.tokenStore.get(this.#refreshKey());\n    if (refreshRecord === null) {\n      throw new Error(\"OAuth refresh failed: no refresh token stored\");\n    }\n\n    const body = new URLSearchParams();\n    body.set(\"grant_type\", \"refresh_token\");\n    body.set(\"refresh_token\", refreshRecord.token);\n    body.set(\"client_id\", this.#config.clientId);\n\n    const tokens = await this.#tokenRequest(body);\n    return this.#persistTokens(tokens, refreshRecord.token);\n  }\n\n  /**\n   * Get the current access token if valid (refreshing first if expired and a\n   * refresh token is available). Returns `null` when no usable token exists.\n   */\n  public async getAccessToken(): Promise<string | null> {\n    const stored = await this.#config.tokenStore.get(this.#accessKey());\n    if (stored !== null) return stored.token;\n\n    // Stored access token is missing or already evicted by the store's TTL.\n    const refresh = await this.#config.tokenStore.get(this.#refreshKey());\n    if (refresh === null) return null;\n\n    try {\n      const refreshed = await this.refresh();\n      return refreshed.token;\n    } catch {\n      return null;\n    }\n  }\n\n  /** Forget tokens (logout). Does NOT call any remote revocation endpoint. */\n  public async signOut(): Promise<void> {\n    await this.#config.tokenStore.delete(this.#accessKey());\n    await this.#config.tokenStore.delete(this.#refreshKey());\n  }\n\n  #accessKey(): string {\n    return `oauth:tokens:${this.#config.clientId}`;\n  }\n\n  #refreshKey(): string {\n    return `oauth:refresh:${this.#config.clientId}`;\n  }\n\n  #verifierKey(state: string): string {\n    return `oauth:verifier:${state}`;\n  }\n\n  async #tokenRequest(body: URLSearchParams): Promise<TokenEndpointResponse> {\n    const response = await this.#config.fetchImpl(this.#config.tokenEndpoint, {\n      method: \"POST\",\n      headers: {\n        \"Content-Type\": \"application/x-www-form-urlencoded\",\n        Accept: \"application/json\",\n      },\n      body: body.toString(),\n    });\n\n    const text = await response.text();\n    const parsed = parseJsonBody(text);\n\n    if (!response.ok) {\n      throw new Error(formatOAuthError(parsed ?? {}, response.status));\n    }\n\n    if (\n      parsed === null ||\n      typeof parsed !== \"object\" ||\n      typeof (parsed as { access_token?: unknown }).access_token !== \"string\"\n    ) {\n      throw new Error(\n        \"OAuth token endpoint returned a response without an `access_token` string\",\n      );\n    }\n\n    return parsed as TokenEndpointResponse;\n  }\n\n  async #persistTokens(\n    tokens: TokenEndpointResponse,\n    previousRefreshToken?: string,\n  ): Promise<TokenRecord> {\n    const record: TokenRecord = { token: tokens.access_token };\n    if (typeof tokens.expires_in === \"number\" && tokens.expires_in > 0) {\n      record.expiresAt = Math.floor(Date.now() / 1000) + tokens.expires_in;\n    }\n    await this.#config.tokenStore.set(this.#accessKey(), record);\n\n    const newRefresh = tokens.refresh_token ?? previousRefreshToken;\n    if (newRefresh !== undefined) {\n      await this.#config.tokenStore.set(this.#refreshKey(), {\n        token: newRefresh,\n      });\n    }\n\n    return record;\n  }\n}\n\nfunction defaultGenerateState(): string {\n  const bytes = new Uint8Array(24);\n  crypto.getRandomValues(bytes);\n  let binary = \"\";\n  for (let i = 0; i < bytes.length; i++) {\n    binary += String.fromCharCode(bytes[i] as number);\n  }\n  return btoa(binary)\n    .replace(/\\+/g, \"-\")\n    .replace(/\\//g, \"_\")\n    .replace(/=+$/, \"\");\n}\n\nfunction parseJsonBody(text: string): unknown {\n  if (text.length === 0) return null;\n  try {\n    return JSON.parse(text) as unknown;\n  } catch {\n    return null;\n  }\n}\n\nfunction formatOAuthError(body: OAuthErrorBody, status?: number): string {\n  const parts: string[] = [\"OAuth token request failed\"];\n  if (status !== undefined) parts.push(`(HTTP ${String(status)})`);\n  if (body.error !== undefined && body.error.length > 0) {\n    parts.push(`: ${body.error}`);\n    if (\n      body.error_description !== undefined &&\n      body.error_description.length > 0\n    ) {\n      parts.push(`- ${body.error_description}`);\n    }\n  }\n  return parts.join(\" \").replace(\" : \", \": \").replace(\" - \", \" - \");\n}\n"],"mappings":"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","names":[]}

package/dist/auth/oauth-client.d.ts

@@ -0,0 +1,90 @@
+/**
+ * OAuth 2.0 Authorization Code + PKCE client orchestration.
+ *
+ * @remarks
+ * Drives the full authorize → callback → token-exchange → refresh dance on top
+ * of the {@link TokenStore} and PKCE primitives that ship with this package.
+ * Implements RFC 6749 §4.1 with the RFC 7636 PKCE extension (S256 only).
+ *
+ * @category Auth
+ * @module auth/oauth-client
+ */
+import { type TokenRecord, type TokenStore } from "./token-store";
+/**
+ * Constructor options for {@link OAuthClient}.
+ */
+export interface OAuthClientConfig {
+    /** Authorization endpoint, e.g. `https://account.vana.org/oauth/authorize`. */
+    authorizationEndpoint: string;
+    /** Token endpoint, e.g. `https://account.vana.org/oauth/token`. */
+    tokenEndpoint: string;
+    /** OAuth `client_id` (public; PKCE protects the flow). */
+    clientId: string;
+    /** Redirect URI registered with the authorization server. */
+    redirectUri: string;
+    /** Default scope; can be overridden per call. */
+    scope?: string;
+    /**
+     * Where to persist access + refresh tokens and the in-flight code verifier
+     * between `authorize` → `callback`. Defaults to a fresh
+     * {@link InMemoryTokenStore}. Use IndexedDB/localStorage-backed
+     * implementations for browser apps where the user navigates away during the
+     * dance.
+     */
+    tokenStore?: TokenStore;
+    /** Override the global `fetch` (e.g. for tests). Defaults to `globalThis.fetch`. */
+    fetchImpl?: typeof fetch;
+    /**
+     * Override the random-state generator (mostly for tests). Must return a
+     * URL-safe string of >= 16 bytes of entropy.
+     */
+    generateState?: () => string;
+}
+/**
+ * Result of {@link OAuthClient.buildAuthorizationUrl}.
+ */
+export interface AuthorizationUrlResult {
+    /** The full authorize URL to redirect / `window.open` to. */
+    url: string;
+    /** The `state` value the auth server will echo back; used for CSRF check. */
+    state: string;
+}
+/**
+ * OAuth 2.0 Authorization Code + PKCE client.
+ *
+ * @remarks
+ * Storage layout under the supplied {@link TokenStore} (all keys namespaced):
+ * - `oauth:tokens:{clientId}`  → access token record
+ * - `oauth:refresh:{clientId}` → refresh token record (no expiry)
+ * - `oauth:verifier:{state}`   → in-flight PKCE verifier (10 min TTL)
+ *
+ * @category Auth
+ */
+export declare class OAuthClient {
+    #private;
+    constructor(config: OAuthClientConfig);
+    /** Build the authorize URL and persist the PKCE verifier keyed by `state`. */
+    buildAuthorizationUrl(opts?: {
+        state?: string;
+        scope?: string;
+        extraParams?: Record<string, string>;
+    }): Promise<AuthorizationUrlResult>;
+    /**
+     * Handle the redirect-callback URL. Validates `state`, retrieves the saved
+     * verifier, exchanges the authorization code + verifier for tokens, and
+     * persists them. Returns the access {@link TokenRecord}.
+     */
+    handleCallback(callbackUrl: string): Promise<TokenRecord>;
+    /**
+     * Exchange a stored refresh token for a fresh access token. Throws if no
+     * refresh token is available.
+     */
+    refresh(): Promise<TokenRecord>;
+    /**
+     * Get the current access token if valid (refreshing first if expired and a
+     * refresh token is available). Returns `null` when no usable token exists.
+     */
+    getAccessToken(): Promise<string | null>;
+    /** Forget tokens (logout). Does NOT call any remote revocation endpoint. */
+    signOut(): Promise<void>;
+}