@universal-everything/sdk-core-privy 1.0.0-dev.cb4e80f

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2023 LUKSO Blockchain GmbH
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,59 @@
+# @universal-everything/sdk-core-privy
+
+Privy implementations of the `IdentityProvider` and
+`KeyCustodyProvider` interfaces from
+[`@universal-everything/sdk-core`](../sdk-core/). This is what the
+relayer uses in production; your app doesn't normally import this
+package directly — you just hand the relayer a Privy access token and
+the server does the rest.
+
+## Install
+
+```bash
+pnpm add @universal-everything/sdk-core-privy @universal-everything/sdk-core
+```
+
+## Server-side use (inside the relayer)
+
+```ts
+import {
+  PrivyIdentityProvider,
+  PrivyKeyCustodyProvider,
+} from "@universal-everything/sdk-core-privy";
+
+const identity = new PrivyIdentityProvider({
+  appId: process.env.PRIVY_APP_ID!,
+  issuer: "privy.io",
+});
+
+const custody = new PrivyKeyCustodyProvider({
+  appId: process.env.PRIVY_APP_ID!,
+  appSecret: process.env.PRIVY_APP_SECRET!,
+});
+
+// `identity.verify(jwt)` → `{ subject: "did:privy:…", isAdmin }`
+// `custody.signTransaction({ walletId, tx, opContext })` → serialized tx
+```
+
+## What each provider does
+
+- **`PrivyIdentityProvider`** — verifies ES256 JWTs via Privy's JWKS,
+  checks `iss`/`aud` claims, returns a subject identity. No secrets
+  needed (public-key verification only).
+- **`PrivyKeyCustodyProvider`** — calls Privy's REST API
+  (`api.privy.io`) to create / import / sign with user-owned wallets.
+  Requires the Privy app secret. Forwards
+  `privy-authorization-signature` + `privy-request-expiry` headers
+  from the caller's `opContext` so user-owned wallets are signable
+  end-to-end.
+
+## Client-side (browser / React Native)
+
+If you need the per-op authorization signature on the client, use the
+official Privy SDK directly — `@privy-io/react-auth`,
+`@privy-io/expo`, or the platform-native SDK. Feed the result into
+your `WalletKitClient` calls via the `opContext` option.
+
+This package does not re-export client SDKs — the whole point of the
+architecture is that the relayer is the only component that holds the
+Privy app secret.

package/dist/index.d.ts

@@ -0,0 +1,87 @@
+import { IdentityProvider, IdentityError, KeyCustodyProvider, KeyCustodyOpContext, WalletInfo, Hex, ExportedKey, SignTxRequest } from '@universal-everything/sdk-core';
+
+type PrivyIdentityProviderConfig = {
+    /** Privy app id (e.g. `cluvxxx...`). Used as the JWT audience and to derive the JWKS URL. */
+    appId: string;
+    /** Override the issuer; defaults to `privy.io`. */
+    issuer?: string;
+    /** Override the JWKS URL; defaults to `https://auth.privy.io/api/v1/apps/${appId}/jwks.json`. */
+    jwksUrl?: string;
+    /** Clock skew tolerance in seconds. Defaults to 5. */
+    clockToleranceSeconds?: number;
+};
+declare function createPrivyIdentityProvider(config: PrivyIdentityProviderConfig): IdentityProvider;
+/**
+ * Map a jose verification failure to an `IdentityError`, distinguishing
+ * **client** token problems (401 — bad/expired/forged token) from **provider**
+ * outages (503 — Privy/JWKS unreachable or broken). Exported for unit testing.
+ *
+ * The provider bucket is what a Privy-health alert keys on (DEV-16308): a JWKS
+ * fetch that timed out, failed at the transport layer (a non-jose error is only
+ * thrown here by the JWKS fetch), or returned a malformed document is a
+ * dependency outage — it must never be reported to the caller as a 401 that
+ * blames their token.
+ */
+declare function mapJoseError(err: unknown): IdentityError;
+
+type PrivyKeyCustodyProviderConfig = {
+    /** Privy app id; same value as the identity provider config. */
+    appId: string;
+    /** Privy app secret. Required — used to authenticate REST calls. */
+    appSecret: string;
+    /** Privy REST base URL. Defaults to production. */
+    baseUrl?: string;
+    /**
+     * Fetch impl override. Defaults to the global `fetch`. Tests inject a
+     * mock here to assert request shape without hitting the network.
+     */
+    fetch?: typeof fetch;
+    /**
+     * User id to bind to newly-created wallets. When set, wallets created
+     * through this provider are **user-owned** (the owner's passkey
+     * produces the per-op authorization signature). Leave undefined to
+     * create app-owned wallets (the app secret alone authorizes
+     * operations — only use for internal / non-custodial slots).
+     */
+    ownerUserId?: string;
+};
+/**
+ * Privy implementation of KeyCustodyProvider. Talks to the Privy REST
+ * API directly via `fetch`.
+ *
+ * Endpoints used:
+ * - `POST /v1/wallets` — create a (user-owned if `ownerUserId` set) wallet.
+ * - `POST /v1/wallets/{id}/rpc` — signing RPCs (`secp256k1_sign`,
+ *   `personal_sign`, `eth_signTransaction`).
+ *
+ * Auth:
+ * - `Authorization: Basic base64(appId:appSecret)` + `privy-app-id: {appId}`.
+ * - When the caller supplies `opContext.authorizationSignature`, it's
+ *   forwarded as `privy-authorization-signature`. Required for
+ *   user-owned wallet operations; Privy rejects unsigned requests
+ *   against those wallets.
+ *
+ * Not implemented yet (out of scope for this slice):
+ * - `importWallet` — needs Privy's HPKE `/v1/wallets/import/init` flow
+ *   (fetch encryption pubkey, encrypt plaintext client-side under it,
+ *   submit in follow-up call). Tracked under Milestone 10's cryptobox.
+ * - `exportWallet` — Privy's REST surface does not expose plaintext
+ *   export. We surface a clear error so callers don't silently block.
+ */
+declare class PrivyKeyCustodyProvider implements KeyCustodyProvider {
+    #private;
+    constructor(config: PrivyKeyCustodyProviderConfig);
+    createWallet(op?: KeyCustodyOpContext): Promise<WalletInfo>;
+    importWallet(_privateKey: Hex, _op?: KeyCustodyOpContext): Promise<WalletInfo>;
+    exportWallet(_walletId: string, _op?: KeyCustodyOpContext): Promise<ExportedKey>;
+    signDigest(walletId: string, digest32: Uint8Array | Hex, op?: KeyCustodyOpContext): Promise<Hex>;
+    personalSign(walletId: string, message: string | Uint8Array, op?: KeyCustodyOpContext): Promise<Hex>;
+    signTransaction(walletId: string, tx: SignTxRequest, op?: KeyCustodyOpContext): Promise<Hex>;
+}
+/**
+ * Factory. We keep it separate so consumers don't have to reach for the
+ * class directly — mirrors the identity-provider factory pattern.
+ */
+declare function createPrivyKeyCustodyProvider(config: PrivyKeyCustodyProviderConfig): KeyCustodyProvider;
+
+export { type PrivyIdentityProviderConfig, PrivyKeyCustodyProvider, type PrivyKeyCustodyProviderConfig, createPrivyIdentityProvider, createPrivyKeyCustodyProvider, mapJoseError };

package/dist/index.js

@@ -0,0 +1,303 @@
+// src/identity.ts
+import {
+  IdentityError
+} from "@universal-everything/sdk-core";
+import {
+  createRemoteJWKSet,
+  errors as joseErrors,
+  jwtVerify
+} from "jose";
+var DEFAULT_ISSUER = "privy.io";
+function createPrivyIdentityProvider(config) {
+  const issuer = config.issuer ?? DEFAULT_ISSUER;
+  const jwksUrl = new URL(
+    config.jwksUrl ?? `https://auth.privy.io/api/v1/apps/${config.appId}/jwks.json`
+  );
+  const jwks = createRemoteJWKSet(jwksUrl);
+  const tolerance = config.clockToleranceSeconds ?? 5;
+  return {
+    async verifyToken(token, opts) {
+      const verifyOpts = {
+        issuer,
+        // Privy bakes the appId into `aud`; respect a caller override if present.
+        audience: opts?.audience ?? config.appId,
+        clockTolerance: tolerance
+      };
+      let payload;
+      try {
+        ({ payload } = await jwtVerify(token, jwks, verifyOpts));
+      } catch (err) {
+        throw mapJoseError(err);
+      }
+      const subject = payload.sub;
+      if (!subject || typeof subject !== "string") {
+        throw new IdentityError("missing_subject", "token has no `sub` claim");
+      }
+      if (opts?.authorizedParties && opts.authorizedParties.length > 0) {
+        const azp = payload.azp;
+        if (typeof azp !== "string" || !opts.authorizedParties.includes(azp)) {
+          throw new IdentityError(
+            "azp_mismatch",
+            `token azp ${JSON.stringify(azp)} not in authorized parties`
+          );
+        }
+      }
+      return { subject, claims: payload };
+    }
+  };
+}
+function mapJoseError(err) {
+  if (err instanceof joseErrors.JWTExpired) {
+    return new IdentityError("expired_token", err.message);
+  }
+  if (err instanceof joseErrors.JWTClaimValidationFailed) {
+    if (err.claim === "iss")
+      return new IdentityError("issuer_mismatch", err.message);
+    if (err.claim === "aud")
+      return new IdentityError("audience_mismatch", err.message);
+    return new IdentityError("invalid_token", err.message);
+  }
+  if (err instanceof joseErrors.JWKSNoMatchingKey) {
+    return new IdentityError("jwks_unavailable", err.message);
+  }
+  if (err instanceof joseErrors.JWKSTimeout || err instanceof joseErrors.JWKSInvalid || !(err instanceof joseErrors.JOSEError)) {
+    return new IdentityError(
+      "provider_unavailable",
+      err instanceof Error ? err.message : String(err)
+    );
+  }
+  return new IdentityError("invalid_token", err.message);
+}
+
+// src/key-custody.ts
+import {
+  KeyCustodyError
+} from "@universal-everything/sdk-core";
+var DEFAULT_BASE_URL = "https://api.privy.io";
+var PrivyKeyCustodyProvider = class {
+  #appId;
+  #authHeader;
+  #baseUrl;
+  #fetch;
+  #ownerUserId;
+  constructor(config) {
+    if (!config.appId)
+      throw new Error("PrivyKeyCustodyProvider: appId required");
+    if (!config.appSecret)
+      throw new Error("PrivyKeyCustodyProvider: appSecret required");
+    this.#appId = config.appId;
+    this.#authHeader = `Basic ${Buffer.from(`${config.appId}:${config.appSecret}`).toString("base64")}`;
+    this.#baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.#fetch = config.fetch ?? fetch;
+    this.#ownerUserId = config.ownerUserId;
+  }
+  async createWallet(op) {
+    const body = { chain_type: "ethereum" };
+    if (this.#ownerUserId) {
+      body.owner = { user_id: this.#ownerUserId };
+    }
+    const res = await this.#request("POST", "/v1/wallets", body, op);
+    const parsed = ensureObject(res, "create_wallet");
+    const walletId = ensureString(parsed.id, "id", "create_wallet");
+    const address = ensureHexAddress(parsed.address, "create_wallet");
+    return { walletId, address };
+  }
+  async importWallet(_privateKey, _op) {
+    throw new KeyCustodyError(
+      "provider_unavailable",
+      "PrivyKeyCustodyProvider.importWallet is not yet implemented \u2014 Privy requires an HPKE-encrypted two-step flow via /v1/wallets/import/init. Tracked under Milestone 10."
+    );
+  }
+  async exportWallet(_walletId, _op) {
+    throw new KeyCustodyError(
+      "provider_unavailable",
+      "PrivyKeyCustodyProvider.exportWallet is not supported \u2014 Privy's REST surface does not expose plaintext export by design. See Milestone 10 for the cryptobox export design that ships plaintext sealed to a client-ephemeral pubkey."
+    );
+  }
+  async signDigest(walletId, digest32, op) {
+    const hash = typeof digest32 === "string" ? digest32 : bytesToHex(digest32);
+    if (!/^0x[0-9a-fA-F]{64}$/.test(hash)) {
+      throw new KeyCustodyError(
+        "invalid_digest",
+        "digest must be exactly 32 bytes"
+      );
+    }
+    const data = await this.#rpc(
+      walletId,
+      { method: "secp256k1_sign", params: { hash } },
+      op
+    );
+    return ensureHexSignature(data.signature, "secp256k1_sign");
+  }
+  async personalSign(walletId, message, op) {
+    const payload = typeof message === "string" ? { message, encoding: "utf-8" } : { message: bytesToHex(message), encoding: "hex" };
+    const data = await this.#rpc(
+      walletId,
+      { method: "personal_sign", params: payload },
+      op
+    );
+    return ensureHexSignature(data.signature, "personal_sign");
+  }
+  async signTransaction(walletId, tx, op) {
+    const transaction = {
+      chain_id: tx.chainId,
+      type: txTypeToNumber(tx.type ?? "eip1559")
+    };
+    if (tx.to !== void 0) transaction.to = tx.to;
+    if (tx.data !== void 0) transaction.data = tx.data;
+    if (tx.value !== void 0) transaction.value = bigintToQuantity(tx.value);
+    if (tx.gas !== void 0) transaction.gas_limit = bigintToQuantity(tx.gas);
+    if (tx.maxFeePerGas !== void 0) {
+      transaction.max_fee_per_gas = bigintToQuantity(tx.maxFeePerGas);
+    }
+    if (tx.maxPriorityFeePerGas !== void 0) {
+      transaction.max_priority_fee_per_gas = bigintToQuantity(
+        tx.maxPriorityFeePerGas
+      );
+    }
+    if (tx.nonce !== void 0) transaction.nonce = tx.nonce;
+    const data = await this.#rpc(
+      walletId,
+      { method: "eth_signTransaction", params: { transaction } },
+      op
+    );
+    return ensureHexSignature(data.signed_transaction, "eth_signTransaction");
+  }
+  async #rpc(walletId, body, op) {
+    const res = await this.#request(
+      "POST",
+      `/v1/wallets/${encodeURIComponent(walletId)}/rpc`,
+      body,
+      op
+    );
+    const parsed = ensureObject(res, body.method);
+    const data = parsed.data;
+    if (typeof data !== "object" || data === null) {
+      throw new KeyCustodyError(
+        "provider_unavailable",
+        `Privy ${body.method} response missing data object`
+      );
+    }
+    return data;
+  }
+  async #request(method, path, body, op) {
+    const headers = {
+      Authorization: this.#authHeader,
+      "Content-Type": "application/json",
+      "privy-app-id": this.#appId
+    };
+    if (op?.authorizationSignature) {
+      headers["privy-authorization-signature"] = op.authorizationSignature;
+    }
+    if (op?.requestExpiry !== void 0) {
+      headers["privy-request-expiry"] = String(op.requestExpiry);
+    }
+    let response;
+    try {
+      response = await this.#fetch(`${this.#baseUrl}${path}`, {
+        method,
+        headers,
+        body: JSON.stringify(body)
+      });
+    } catch (err) {
+      throw new KeyCustodyError(
+        "provider_unavailable",
+        `Privy ${method} ${path} failed at transport layer: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    if (response.ok) {
+      return await response.json();
+    }
+    const raw = await response.text();
+    let parsed = {};
+    try {
+      parsed = raw ? JSON.parse(raw) : {};
+    } catch {
+    }
+    throw mapPrivyError(response.status, parsed, raw);
+  }
+};
+function createPrivyKeyCustodyProvider(config) {
+  return new PrivyKeyCustodyProvider(config);
+}
+function mapPrivyError(status, body, raw) {
+  const messageParts = [
+    `Privy returned ${status}`,
+    body.error_code ? `code=${body.error_code}` : void 0,
+    body.error ?? body.message ?? (raw || void 0),
+    body.cause ? `cause=${body.cause}` : void 0
+  ].filter(Boolean);
+  const message = messageParts.join(" ");
+  if (status === 404) return new KeyCustodyError("wallet_not_found", message);
+  if (status === 401 || status === 403) {
+    return new KeyCustodyError("invalid_signature", message);
+  }
+  if (status === 429) return new KeyCustodyError("rate_limited", message);
+  if (status === 400) {
+    return new KeyCustodyError(
+      body.error_code === "invalid_hash" || body.error_code === "invalid_private_key" ? "invalid_digest" : "invalid_signature",
+      message
+    );
+  }
+  return new KeyCustodyError("provider_unavailable", message);
+}
+function ensureObject(value, op) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new KeyCustodyError(
+      "provider_unavailable",
+      `Privy ${op} response was not a JSON object`
+    );
+  }
+  return value;
+}
+function ensureString(value, field, op) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new KeyCustodyError(
+      "provider_unavailable",
+      `Privy ${op} response missing string field ${field}`
+    );
+  }
+  return value;
+}
+function ensureHexAddress(value, op) {
+  if (typeof value !== "string" || !/^0x[0-9a-fA-F]{40}$/.test(value)) {
+    throw new KeyCustodyError(
+      "provider_unavailable",
+      `Privy ${op} response missing valid 20-byte hex address`
+    );
+  }
+  return value;
+}
+function ensureHexSignature(value, op) {
+  if (typeof value !== "string" || !/^0x[0-9a-fA-F]+$/.test(value)) {
+    throw new KeyCustodyError(
+      "provider_unavailable",
+      `Privy ${op} response missing valid hex signature`
+    );
+  }
+  return value;
+}
+function bytesToHex(bytes) {
+  let s = "0x";
+  for (const b of bytes) s += b.toString(16).padStart(2, "0");
+  return s;
+}
+function bigintToQuantity(n) {
+  return `0x${n.toString(16)}`;
+}
+function txTypeToNumber(type) {
+  switch (type) {
+    case "legacy":
+      return 0;
+    case "eip2930":
+      return 1;
+    case "eip1559":
+      return 2;
+  }
+}
+export {
+  PrivyKeyCustodyProvider,
+  createPrivyIdentityProvider,
+  createPrivyKeyCustodyProvider,
+  mapJoseError
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@universal-everything/sdk-core-privy",
+  "version": "1.0.0-dev.cb4e80f",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/universal-everything/universal-relayer.git",
+    "directory": "packages/sdk-core-privy"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "jose": "^6.2.2",
+    "@universal-everything/sdk-core": "1.0.0-dev.cb4e80f"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.10",
+    "tsup": "^8.5.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "build": "tsup"
+  }
+}