@oceanalt/privy
v0.1.0
Published
Guard for Privy server wallets: ask OceanAlt about the real payee (allow / review / decline) before Privy signs a transfer, approval or x402 authorization. Fails closed. No keys, no custody. Not affiliated with Privy.
Maintainers
Readme
@oceanalt/privy
An OceanAlt check for Privy server wallets (@privy-io/node), run before Privy signs. Each check returns one of three results:
| Result | Meaning |
|---|---|
| allow | No blocking findings. It's a screening result over public data, not a guarantee. |
| review | A human has to agree first. OceanAlt returned review or an uncertain verdict, the check couldn't run, or the guard couldn't read what is being signed. |
| decline | Don't sign. |
If a check can't run (network error, timeout, HTTP error, unrecognised answer), the result is review. It is never allow. The package holds no keys and moves no funds. Not affiliated with Privy.
Tested with @privy-io/node 0.35.0 and viem 2.56.9, including a real PrivyClient and createViemAccount() with Privy's HTTP call stubbed out.
Usage
import { PrivyClient } from "@privy-io/node";
import { guardPrivyClient } from "@oceanalt/privy";
const privy = guardPrivyClient(new PrivyClient({ appId, appSecret }), {
onReview: async (result, request) => askAHuman(result, request), // optional; return true only after a human agreed
});
// Checked before Privy signs: the guard reads the USDC transfer calldata and screens the real recipient.
await privy.wallets().ethereum().sendTransaction(walletId, {
caip2: "eip155:8453",
params: { transaction: { to: USDC_ON_BASE, data: transferCalldata } },
});guardPrivyClient changes the client in place and returns it. It replaces privy.wallets().rpc, privy.wallets().rawSign and privy.intents().rpc with checked versions that can't be reassigned. Everything in @privy-io/node that signs through those methods is checked, including createViemAccount(privy, ...) and createX402Client(privy, ...) built on the guarded client.
decline: throwsOceanAltDeclinedError(code: "OCEANALT_DECLINED",resultholds the OceanAlt answer). Privy is not called.review: callsonReview(result, request). Privy is called only if that returns exactlytrue. WithoutonReview, or if it throws or returns anything else, the guard throwsOceanAltReviewRequiredError(code: "OCEANALT_REVIEW_REQUIRED").allow: the original Privy method runs with the same arguments.
What is checked
| Privy RPC method | Helper | What the guard does |
|---|---|---|
| eth_sendTransaction, eth_signTransaction | ethereum().sendTransaction, signTransaction, viem signTransaction | Decodes the call. Native transfer: screens to. ERC-20 transfer / transferFrom: screens the recipient in the calldata. approve / increaseAllowance / permit / setApprovalForAll: screens the spender. |
| eth_signTypedData_v4 | ethereum().signTypedData, viem signTypedData, x402 client | EIP-3009 TransferWithAuthorization / ReceiveWithAuthorization (the x402 exact scheme): screens message.to. EIP-2612 Permit and Permit2: screens the spender. |
| wallet_sendCalls | ethereum().sendCalls | Every call is decoded and screened. One decline blocks the batch. |
| personal_sign | ethereum().signMessage, viem signMessage | review (not decoded). signMessage: "allow" lets messages through. |
| secp256k1_sign, eth_sign7702Authorization, eth_signUserOperation, raw_sign | | Always review. A raw hash, an account delegation or a user operation can't be read. |
| exportPrivateKey, exportSeedPhrase | | Always review. An exported key signs outside this guard. |
| Solana, Tron, Spark and other non-EVM methods | solana(), tron() | review by default (not decoded). nonEvm: "allow" lets them through unchecked. Spark read-only methods pass. |
The amount is sent as amountUsdc only when the token is Circle USDC on a chain the guard knows (Ethereum, Base, Arbitrum, Optimism, Polygon, Avalanche and their testnets). For other tokens and native coins the payee is screened without an amount. The network is sent as eip155:<chainId>, from caip2, the transaction's chain_id, or the typed data's domain.
An unlimited approval that OceanAlt allows is turned into review (reason_code: "approval.unlimited"). A contract call that is not a transfer or approval is review (calldata.unrecognised); with unknownCalls: "screen-target" the contract address is screened instead.
viem accounts
import { createViemAccount } from "@privy-io/node/viem";
import { guardViemAccount } from "@oceanalt/privy";
const account = guardViemAccount(createViemAccount(privy, { walletId, address }), { signMessage: "allow" });This is optional when the client is already guarded. It is useful to set a different policy on one account (for example, allow login messages). When both are guarded, a call checked by the account is not checked again by the client.
Options
onReview(result, request), onResult(result, request) (observer, errors ignored), purpose (sent to OceanAlt), signMessage ("review" | "allow"), unknownCalls ("review" | "screen-target"), nonEvm ("review" | "allow"), plus baseUrl, fetch, apiKey (optional; sent as x-api-key, only to the OceanAlt host), timeoutMs (default 10000), client (an OceanAltClient from @oceanalt/core). request.results holds one result per decoded call, each with a decoded field showing what was read.
checkEndpoint(client, url) and decidePayment(client, { to, amountUsdc, network, purpose }) are exported for checks outside the wallet.
Limits
- Only this
PrivyClientinstance is guarded. AnotherPrivyClient, direct calls to Privy's REST API,wallets()._rpc(an internal method), or keys exported earlier are not checked. payout(),swaps()andearn()call other Privy endpoints and are not checked.- Only EVM requests are decoded. Solana, Tron and other chains are
reviewby default, or unchecked withnonEvm: "allow". - Calldata is read for ERC-20 transfer, transferFrom, approve, increaseAllowance, permit and setApprovalForAll. Calls through routers, multicall contracts or smart-account
executewrappers are not unpacked; they count as unknown contract calls. - Fail closed means an OceanAlt outage stops signing unless your
onReviewlets it through. - Privy policies and key quorums still apply on Privy's side. This guard runs in your process before the request is sent; it doesn't replace them.
- OceanAlt screens the payee address against public data. It doesn't check whether the seller delivers, and an
allowis not a guarantee.
Data sent to OceanAlt
The decoded payee or spender address, and when known, the USDC amount, eip155:<chainId> network and your purpose (cut to 120 characters). Wallet IDs, signatures and Privy credentials are not sent. There's no telemetry.
Requirements
Node 20+, ESM. Peer dependencies: @privy-io/node 0.35+, and optionally viem 2 (only if you use viem accounts; the guard doesn't import it). Depends on @oceanalt/core ^0.2.0.
Tests
npm test runs the unit tests with a mocked fetch (no network), including a real PrivyClient and createViemAccount() with Privy's HTTP call stubbed.
MIT licensed.
