@oceanalt/crossmint 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OceanAlt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# @oceanalt/crossmint
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An OceanAlt check for [Crossmint](https://www.crossmint.com) wallets (`@crossmint/wallets-sdk`, EVM chains), run before Crossmint creates or approves a transfer or signature. 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 Crossmint.
+
+Tested with `@crossmint/wallets-sdk` 1.20.0 and viem 2.56.9, including a real `EVMWallet` built on a stubbed API client.
+
+## Usage
+
+```ts
+import { createCrossmint, CrossmintWallets, EVMWallet } from "@crossmint/wallets-sdk";
+import { guardCrossmintWallet } from "@oceanalt/crossmint";
+
+const wallets = CrossmintWallets.from(createCrossmint({ apiKey }));
+const wallet = guardCrossmintWallet(EVMWallet.from(await wallets.getWallet(walletLocator, { chain: "base" })), {
+  onReview: async (result, request) => askAHuman(result, request), // optional; return true only after a human agreed
+});
+
+await wallet.send(payeeAddress, "usdc", "2.50");   // payee and amount are screened first
+```
+
+`guardCrossmintWallet` changes the wallet object in place and returns it. The checked methods can't be reassigned.
+
+- `decline`: throws `OceanAltDeclinedError` (`code: "OCEANALT_DECLINED"`, `result` holds the OceanAlt answer). Crossmint is not called.
+- `review`: calls `onReview(result, request)`. Crossmint is called only if that returns exactly `true`. Without `onReview`, or if it throws or returns anything else, the guard throws `OceanAltReviewRequiredError` (`code: "OCEANALT_REVIEW_REQUIRED"`).
+- `allow`: the original method runs with the same arguments.
+
+## What is checked
+
+| Method | What the guard does |
+|---|---|
+| `send(to, token, amount, options?)` | Screens `to`. The amount is sent as `amountUsdc` when `token` is `"usdc"`, `"<chain>:usdc"` or the USDC contract on the wallet's chain. A user locator (email, phone, userId, social handle) can't be screened, so it is `review`. |
+| `sendTransaction({ to, data \| abi + functionName + args, value })` | Decodes the call. Native transfer: screens `to`. ERC-20 `transfer` / `transferFrom`: screens the recipient in the calldata. `approve` / `increaseAllowance` / `permit` / `setApprovalForAll`: screens the spender. |
+| `sendTransaction({ transaction })` | Parses the serialized transaction with viem, then decodes it as above. |
+| `signTypedData({ domain, types, primaryType, message, chain })` | EIP-3009 `TransferWithAuthorization` / `ReceiveWithAuthorization` (the x402 `exact` scheme): screens `message.to`. EIP-2612 `Permit` and Permit2: screens the spender. A domain `chainId` that differs from `chain` is `review`. |
+| `signMessage` | `review` by default (not decoded). `signMessage: "allow"` lets it through. |
+| `addSigner`, `addRecoveryMethod` | Always `review`. Another signer gets control of the wallet. |
+| `approve`, `approveTransaction` | Pass only for a `transactionId` / `signatureId` that this guard prepared (`prepareOnly`) after checking it. Any other id is `review`. |
+
+The network is sent as `eip155:<chainId>`, from the wallet's chain name (see `CHAIN_IDS`; pass `chainId` for a chain not listed). 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.
+
+## Options
+
+`onReview(result, request)`, `onResult(result, request)` (observer, errors ignored), `purpose` (sent to OceanAlt), `chainId`, `signMessage` (`"review"` | `"allow"`), `unknownCalls` (`"review"` | `"screen-target"`), 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.
+
+`guardViemAccount(account, opts)` is also exported, for a viem signer you use next to the Crossmint wallet. `checkEndpoint(client, url)` and `decidePayment(client, { to, amountUsdc, network, purpose })` are exported for checks outside the wallet.
+
+## Limits
+
+- Only the wallet object you pass is guarded. `EVMWallet.from(wallet)`, `getWallet()` and `createWallet()` return new, unguarded objects, so guard the one you hand to your agent.
+- Crossmint's REST API, the dashboard, other SDK instances, and operations created outside this guard are not checked. Approving them through the guarded wallet is `review`.
+- EVM wallets only. Solana and Stellar wallets are rejected with a `TypeError`.
+- `"usdxm"` (Crossmint's test token) and other tokens are screened without an amount.
+- Calldata is read for ERC-20 transfer, transferFrom, approve, increaseAllowance, permit and setApprovalForAll. Calls through routers or multicall contracts are not unpacked; they count as unknown contract calls.
+- Fail closed means an OceanAlt outage stops payments unless your `onReview` lets them through.
+- Crossmint signer scopes and policies still apply on Crossmint's side. This guard runs in your process before the request is sent; it doesn't replace them.
+- The allow path was tested against a real `EVMWallet` with `prepareOnly` and a stubbed API client. A full send with a live signer was not run.
+- OceanAlt screens the payee address against public data. It doesn't check whether the seller delivers, and an `allow` is 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 locators, user locators, signatures and Crossmint API keys are not sent. There's no telemetry.
+
+## Requirements
+
+Node 20+, ESM. Peer dependencies: `@crossmint/wallets-sdk` 1.20+ and `viem` 2 (used for ABI-encoded and serialized transactions). Depends on `@oceanalt/core` ^0.2.0.
+
+## Tests
+
+`npm test` runs the unit tests with a mocked fetch (no network), including a real `EVMWallet` on a stubbed API client.
+
+MIT licensed.

package/index.d.ts

@@ -0,0 +1,41 @@
+import type { WalletGuardOptions, SigningRequest } from "./lib/wallet-guard.mjs";
+
+export { createClient, decidePayment, checkEndpoint, parseUsdc, DECISION, OceanAltDeclinedError, OceanAltReviewRequiredError } from "./lib/decide.mjs";
+export type { Decision, ClientOptions, PaymentIntent, PayeeResult, EndpointResult } from "./lib/decide.mjs";
+export { decodeTransaction, decodeTypedData } from "./lib/evm.mjs";
+export type { Decoded, DecodedKind } from "./lib/evm.mjs";
+export type { WalletGuardOptions, SigningRequest } from "./lib/wallet-guard.mjs";
+
+export declare const CHAIN_IDS: Readonly<Record<string, number>>;
+
+export type CrossmintGuardOptions = Omit<WalletGuardOptions, "nonEvm"> & {
+  /** Chain id to use when the wallet's chain name is not in CHAIN_IDS. */
+  chainId?: number | string;
+};
+
+/** The part of a Crossmint Wallet / EVMWallet the guard touches. */
+export type CrossmintWalletLike = {
+  chain: string;
+  address: string;
+  send(...args: any[]): Promise<any>;
+  sendTransaction?(params: any): Promise<any>;
+  signTypedData?(params: any): Promise<any>;
+  signMessage?(params: any): Promise<any>;
+  approve?(params: any): Promise<any>;
+  approveTransaction?(params: any): Promise<any>;
+  addSigner?(...args: any[]): Promise<any>;
+  addRecoveryMethod?(...args: any[]): Promise<any>;
+};
+
+/**
+ * Guard one Crossmint Wallet or EVMWallet (EVM chains only) in place and return it. send, sendTransaction,
+ * signTypedData, signMessage, addSigner and addRecoveryMethod are checked before Crossmint is called; approve and
+ * approveTransaction pass only for ids prepared through this guard.
+ */
+export declare function guardCrossmintWallet<W extends CrossmintWalletLike>(wallet: W, opts?: CrossmintGuardOptions): W;
+export declare function isGuarded(wallet: unknown): boolean;
+export declare function isUsdcToken(token: string, chainId: number | null | undefined): boolean;
+/** Turn a Crossmint wallet call into the request the guard checks. */
+export declare function crossmintRequest(method: string, args: unknown[], chainId: number | null): Promise<SigningRequest>;
+/** Guard a viem LocalAccount. Returns a new account; the original stays unguarded. */
+export declare function guardViemAccount<A extends { address: string }>(account: A, opts?: WalletGuardOptions): A;

package/index.mjs

@@ -0,0 +1,123 @@
+// @oceanalt/crossmint: OceanAlt pre-payment checks for Crossmint wallets (@crossmint/wallets-sdk, EVM).
+//
+//   guardCrossmintWallet(wallet, opts)   checks send / sendTransaction / signTypedData / signMessage / approve on one
+//                                        Wallet or EVMWallet instance before Crossmint creates or approves the operation
+//
+// Fail closed: a network error, timeout, HTTP error, unrecognised answer, `uncertain` verdict, or a request this
+// guard can't decode is "review", never "allow". Not affiliated with or endorsed by Crossmint.
+import { createGate, defineGuarded, guardViemAccount as guardAccount } from "./lib/wallet-guard.mjs";
+import { isAddress, isUsdc, calldataOf, parseSerialized, chainIdOf } from "./lib/evm.mjs";
+
+export { createClient, decidePayment, checkEndpoint, parseUsdc, DECISION, OceanAltDeclinedError, OceanAltReviewRequiredError } from "./lib/decide.mjs";
+export { decodeTransaction, decodeTypedData } from "./lib/evm.mjs";
+
+const UA = "oceanalt-crossmint/0.1.0";
+const GUARDED = Symbol.for("oceanalt.crossmint.guarded");
+
+/** Crossmint EVM chain names → chain ids (the ones OceanAlt screens, plus common testnets). Others: pass opts.chainId. */
+export const CHAIN_IDS = Object.freeze({
+  ethereum: 1, "ethereum-sepolia": 11155111, base: 8453, "base-sepolia": 84532, polygon: 137, "polygon-amoy": 80002,
+  arbitrum: 42161, "arbitrum-sepolia": 421614, optimism: 10, "optimism-sepolia": 11155420, avalanche: 43114,
+  "avalanche-fuji": 43113, bsc: 56, arc: 5042, "arc-testnet": 5042002,
+});
+
+const lc = (v) => (typeof v === "string" ? v.toLowerCase() : v);
+
+/** Is the token argument of wallet.send() Circle USDC? Accepts "usdc", "<chain>:usdc", or the USDC address on that chain. */
+export function isUsdcToken(token, chainId) {
+  const t = lc(String(token || ""));
+  if (t === "usdc" || t.endsWith(":usdc")) return true;
+  const addr = t.includes(":") ? t.split(":").pop() : t;
+  return isAddress(addr) && isUsdc(chainId, addr);
+}
+
+/** Turn a Crossmint wallet call into the request the guard checks. */
+export async function crossmintRequest(method, args, chainId) {
+  const base = { provider: "crossmint", method, chainId, input: args };
+  switch (method) {
+    case "send": {
+      const [to, token, amount] = args;
+      if (typeof to !== "string" || !isAddress(to)) {
+        return { ...base, kind: "payment", payment: { to: null }, detail: "send() to a user locator (email, phone, userId, social handle) can't be screened; only 0x addresses can." };
+      }
+      return { ...base, kind: "payment", payment: { to, amountUsdc: isUsdcToken(token, chainId) ? amount : undefined } };
+    }
+    case "sendTransaction": {
+      const p = args[0] || {};
+      if (typeof p.transaction === "string") {
+        const r = await parseSerialized(p.transaction);
+        if (r.error) return { ...base, kind: "raw", reason_code: "calldata.undecodable", detail: `Could not decode the serialized transaction: ${r.error}.` };
+        return { ...base, kind: "transaction", chainId: r.tx.chainId ?? chainId, calls: [r.tx] };
+      }
+      const c = await calldataOf(p);
+      if (c.error) return { ...base, kind: "raw", reason_code: "calldata.undecodable", detail: c.error };
+      return { ...base, kind: "transaction", calls: [{ to: p.to, data: c.data, value: p.value }] };
+    }
+    case "signTypedData": {
+      const p = args[0] || {};
+      return { ...base, kind: "typed-data", chainId: CHAIN_IDS[p.chain] ?? chainId, typedData: { domain: p.domain, types: p.types, primaryType: p.primaryType, message: p.message } };
+    }
+    case "signMessage":
+      return { ...base, kind: "message" };
+    case "addSigner":
+    case "addRecoveryMethod":
+      return { ...base, kind: "raw", reason_code: "wallet.add_signer", detail: `${method}() gives another key control over this wallet.` };
+    default:
+      return { ...base, kind: "raw", reason_code: "method.unsupported", detail: `${method} is not decoded.` };
+  }
+}
+
+/**
+ * Guard one Crossmint Wallet or EVMWallet instance in place and return it.
+ * Checked: send(to, token, amount), sendTransaction({ to, data | abi+functionName+args, value } | { transaction }),
+ * signTypedData, signMessage, addSigner, addRecoveryMethod; approve / approveTransaction only pass for ids this guard
+ * prepared (prepareOnly) and checked itself.
+ * Options: { onReview?, onResult?, purpose?, chainId?, signMessage?: "review"|"allow", unknownCalls?: "review"|"screen-target",
+ *            client?, baseUrl?, fetch?, apiKey?, timeoutMs? }
+ */
+export function guardCrossmintWallet(wallet, opts = {}) {
+  if (!wallet || typeof wallet !== "object" || typeof wallet.send !== "function") throw new TypeError("guardCrossmintWallet(): expected a Wallet or EVMWallet from @crossmint/wallets-sdk");
+  if (wallet[GUARDED]) return wallet;
+  if (!isAddress(wallet.address) || wallet.chain === "solana" || wallet.chain === "stellar") {
+    throw new TypeError(`guardCrossmintWallet(): only EVM wallets are supported (chain '${wallet.chain}')`);
+  }
+  const chainId = chainIdOf(opts.chainId) ?? CHAIN_IDS[wallet.chain] ?? null;
+  const gate = createGate(opts, { userAgent: opts.userAgent || UA });
+  const prepared = new Set(); // transaction / signature ids created by a checked prepareOnly call
+  const remember = (out) => {
+    for (const id of [out?.transactionId, out?.signatureId]) if (typeof id === "string" && id) prepared.add(id);
+    return out;
+  };
+
+  const m = {};
+  for (const name of ["send", "sendTransaction", "signTypedData", "signMessage", "addSigner", "addRecoveryMethod"]) {
+    if (typeof wallet[name] !== "function") continue;
+    const orig = wallet[name].bind(wallet);
+    m[name] = async (...args) => {
+      await gate.check(await crossmintRequest(name, args, chainId));
+      return remember(await orig(...args));
+    };
+  }
+  for (const name of ["approve", "approveTransaction"]) {
+    if (typeof wallet[name] !== "function") continue;
+    const orig = wallet[name].bind(wallet);
+    m[name] = async (params = {}, ...rest) => {
+      const id = params?.transactionId ?? params?.signatureId;
+      const req = prepared.has(id)
+        ? { provider: "crossmint", method: name, chainId, input: params, kind: "pass" }
+        : { provider: "crossmint", method: name, chainId, input: params, kind: "raw", reason_code: "approval.unknown_id", detail: `Approving ${id ? `'${id}'` : "an operation"} that was not prepared and checked through this guard.` };
+      await gate.check(req);
+      return orig(params, ...rest);
+    };
+  }
+  defineGuarded(wallet, m);
+  Object.defineProperty(wallet, GUARDED, { value: { client: gate.client, chainId }, enumerable: false });
+  return wallet;
+}
+
+export function isGuarded(w) { return !!w?.[GUARDED]; }
+
+/** Guard a viem account. Crossmint wallets are smart wallets, so this is for viem signers you use next to them. */
+export function guardViemAccount(account, opts = {}) {
+  return guardAccount(account, { provider: "crossmint", userAgent: UA, ...opts });
+}

package/lib/decide.d.mts

@@ -0,0 +1,74 @@
+import type { OceanAltClient } from "@oceanalt/core";
+
+export type Decision = "allow" | "review" | "decline";
+export declare const DECISION: Readonly<{ ALLOW: "allow"; REVIEW: "review"; DECLINE: "decline" }>;
+export declare const DEFAULT_TIMEOUT_MS: number;
+
+export type ClientOptions = {
+  baseUrl?: string;
+  fetch?: typeof fetch;
+  /** Optional. Sent as x-api-key, only to the OceanAlt host. The free endpoints work without it. */
+  apiKey?: string | null;
+  /** Per-request timeout. Default 10000. A timeout counts as "review". */
+  timeoutMs?: number;
+  userAgent?: string;
+  onRecord?: (r: unknown) => void;
+};
+
+/** What getPayment(args) returns: the payment the wrapped tool is about to make. */
+export type PaymentIntent = { to: string; amountUsdc?: number | string; amount?: number | string; network?: string; purpose?: string };
+
+export type PayeeResult = {
+  decision: Decision;
+  /** true only when decision is "allow". */
+  allow: boolean;
+  instruction: string;
+  detail: string;
+  to?: string;
+  verdict?: string | null;
+  reason_code: string | null;
+  retry?: unknown;
+  advice?: unknown;
+  signal_keys?: string[];
+  evidence?: unknown;
+  /** true when OceanAlt gave no usable answer (error, timeout, missing input, unrecognised or uncertain answer). */
+  failClosed?: boolean;
+};
+
+export type EndpointResult = {
+  decision: Decision;
+  allow: boolean;
+  instruction: string;
+  detail: string;
+  url?: string;
+  verdict?: string | null;
+  reason_code: string | null;
+  signals?: unknown;
+  failClosed?: boolean;
+};
+
+export declare function createClient(opts?: ClientOptions): OceanAltClient;
+export declare function parseUsdc(v: unknown): number | undefined;
+export declare function decidePayment(client: OceanAltClient, input: Partial<PaymentIntent>): Promise<PayeeResult>;
+export declare function checkEndpoint(client: OceanAltClient, url: string): Promise<EndpointResult>;
+
+export declare class OceanAltDeclinedError extends Error {
+  readonly code: "OCEANALT_DECLINED";
+  readonly result: PayeeResult;
+}
+export declare class OceanAltReviewRequiredError extends Error {
+  readonly code: "OCEANALT_REVIEW_REQUIRED";
+  readonly result: PayeeResult;
+}
+
+export type GuardOptions<A = any> = {
+  /** Return the payee and amount of the payment the wrapped tool is about to make, from its arguments. */
+  getPayment: (args: A) => PaymentIntent | null | undefined | Promise<PaymentIntent | null | undefined>;
+  /** Called on "review". Return exactly true (after a human agreed) to run the tool anyway. Default: refuse. */
+  onReview?: (result: PayeeResult, args: A) => boolean | Promise<boolean>;
+  /** Observer for every decision. Errors thrown here are ignored. */
+  onResult?: (result: PayeeResult, args: A) => void;
+};
+
+export declare function guardedRun<A, R>(opts: GuardOptions<A> & { client: OceanAltClient }, args: A, run: () => R | Promise<R>): Promise<R>;
+export declare function assertGuardOptions(opts: unknown, who: string): void;

package/lib/decide.mjs

@@ -0,0 +1,149 @@
+// Framework-free OceanAlt calls and the guard logic shared by @oceanalt/vercel-ai and @oceanalt/langchain
+// (identical copies; keep in sync).
+// Outcome vocabulary is OceanAlt's own: allow | review | decline. Fail closed: a network error, an HTTP error,
+// a timeout, an unrecognised answer or an `uncertain` verdict is "review", never "allow".
+import { OceanAltClient } from "@oceanalt/core";
+
+export const DECISION = Object.freeze({ ALLOW: "allow", REVIEW: "review", DECLINE: "decline" });
+export const DEFAULT_TIMEOUT_MS = 10_000;
+
+/**
+ * An OceanAltClient whose fetch has a timeout and, when apiKey is set, sends x-api-key to the OceanAlt host only.
+ * Options: { baseUrl?, fetch?, apiKey?, timeoutMs?, userAgent?, onRecord? }
+ */
+export function createClient({ baseUrl, fetch: f, apiKey, timeoutMs = DEFAULT_TIMEOUT_MS, userAgent, onRecord } = {}) {
+  const raw = f || globalThis.fetch;
+  const host = new URL(baseUrl || "https://oceanalt.com").host;
+  const wrapped = (url, init = {}) => {
+    let same = false; try { same = new URL(String(url)).host === host; } catch { same = false; }
+    const headers = apiKey && same ? { ...(init.headers || {}), "x-api-key": apiKey } : init.headers;
+    const signal = init.signal || (timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : undefined);
+    return raw(url, { ...init, ...(headers ? { headers } : {}), ...(signal ? { signal } : {}) });
+  };
+  return new OceanAltClient({ baseUrl, fetch: wrapped, onRecord, userAgent: userAgent || "oceanalt-adapter/0.1.0" });
+}
+
+/** Parse a human USDC amount ("2.5", 2.5, "$2.50", "3 USDC"). undefined when absent, NaN when present but invalid. */
+export function parseUsdc(v) {
+  if (v == null || v === "") return undefined;
+  const n = typeof v === "number" ? v : Number(String(v).replace(/^\s*\$/, "").replace(/\s*usdc\s*$/i, "").trim());
+  return Number.isFinite(n) && n >= 0 ? n : NaN;
+}
+
+const INSTRUCTION = {
+  allow: "No blocking findings. This is a screening result over public data, not a guarantee.",
+  review: "Do not pay yet. Ask a human to confirm, and show them the reason.",
+  decline: "Do not pay.",
+};
+
+function result(decision, fields) {
+  return { decision, allow: decision === DECISION.ALLOW, instruction: INSTRUCTION[decision], ...fields };
+}
+
+/**
+ * POST /api/decide {to, amountUsdc, purpose, network} and normalise the answer.
+ * allow only when decision === "allow", allow !== false and verdict !== "uncertain". decline only on "decline".
+ * Everything else, including errors, is review (failClosed: true when OceanAlt did not give a usable answer).
+ */
+export async function decidePayment(client, input = {}) {
+  const to = typeof input.to === "string" ? input.to.trim() : "";
+  if (!to) return result(DECISION.REVIEW, { reason_code: "input.missing_payee", detail: "No payee address given, so nothing was screened.", failClosed: true });
+  const amountUsdc = parseUsdc(input.amountUsdc ?? input.amount);
+  if (Number.isNaN(amountUsdc)) return result(DECISION.REVIEW, { to, reason_code: "input.invalid_amount", detail: `Amount '${input.amountUsdc ?? input.amount}' is not a USDC number.`, failClosed: true });
+  const body = {
+    to,
+    amountUsdc: amountUsdc,
+    purpose: input.purpose ? String(input.purpose).slice(0, 120) : undefined,
+    network: input.network || undefined,
+  };
+  let r;
+  try {
+    r = await client._json("/api/decide", { method: "POST", body: JSON.stringify(body) });
+  } catch (e) {
+    return result(DECISION.REVIEW, { to, reason_code: "oceanalt.unavailable", detail: `OceanAlt could not be reached or returned an error (${e?.message || e}). Not treated as safe.`, failClosed: true });
+  }
+  const fields = {
+    to,
+    verdict: r?.verdict ?? null,
+    reason_code: r?.reason_code ?? null,
+    retry: r?.retry ?? null,
+    advice: r?.advice ?? null,
+    signal_keys: Array.isArray(r?.signal_keys) ? r.signal_keys : [],
+    evidence: r?.evidence ?? null,
+  };
+  const d = r?.decision;
+  if (d === DECISION.DECLINE) return result(DECISION.DECLINE, { ...fields, detail: `OceanAlt declined ${to}.` });
+  if (d === DECISION.ALLOW && r?.allow !== false && r?.verdict !== "uncertain") return result(DECISION.ALLOW, { ...fields, detail: `OceanAlt allowed ${to}.` });
+  const why = d === DECISION.ALLOW ? `decision 'allow' with verdict '${r?.verdict}' and allow=${r?.allow}` : `decision '${d ?? "nothing"}'`;
+  return result(DECISION.REVIEW, { ...fields, reason_code: fields.reason_code || `decide.${d || "unknown"}`, detail: `OceanAlt returned ${why} for ${to}; a human should look.`, failClosed: d !== DECISION.REVIEW });
+}
+
+/** GET /api/endpoint?url=. risky → decline, clear → allow, anything else or an error → review. */
+export async function checkEndpoint(client, url) {
+  if (!url || typeof url !== "string") return result(DECISION.REVIEW, { reason_code: "input.missing_url", detail: "No URL given.", failClosed: true });
+  let r;
+  try {
+    r = await client.endpoint(url);
+  } catch (e) {
+    return result(DECISION.REVIEW, { url, verdict: null, reason_code: "oceanalt.unavailable", signals: [], detail: `Endpoint screening could not run (${e?.message || e}). Not treated as safe.`, failClosed: true });
+  }
+  const fields = { url, verdict: r?.verdict ?? null, reason_code: r?.reason_code ?? null, signals: r?.signals ?? [] };
+  if (r?.verdict === "risky") return result(DECISION.DECLINE, { ...fields, detail: `${url} is listed as risky.` });
+  if (r?.verdict === "clear") return result(DECISION.ALLOW, { ...fields, detail: "Endpoint not on OceanAlt's lists. Absence from a list is not proof of safety." });
+  return result(DECISION.REVIEW, { ...fields, reason_code: fields.reason_code || `endpoint.${r?.verdict || "unknown"}`, detail: `Endpoint screening returned '${r?.verdict ?? "nothing"}'.`, failClosed: true });
+}
+
+export class OceanAltDeclinedError extends Error {
+  constructor(res) {
+    super(`OceanAlt declined this payment (${res.reason_code || "decline"}). The payment tool was not run.`);
+    this.name = "OceanAltDeclinedError";
+    this.code = "OCEANALT_DECLINED";
+    this.result = res;
+  }
+}
+
+export class OceanAltReviewRequiredError extends Error {
+  constructor(res) {
+    super(`OceanAlt returned review for this payment (${res.reason_code || "review"}). A human has to approve it first. The payment tool was not run.`);
+    this.name = "OceanAltReviewRequiredError";
+    this.code = "OCEANALT_REVIEW_REQUIRED";
+    this.result = res;
+  }
+}
+
+/**
+ * The guard. Runs `run()` only when OceanAlt allows the payment, or when onReview returns exactly true on review.
+ * getPayment(args) must return { to, amountUsdc?|amount?, network?, purpose? }. If it throws or returns no `to`,
+ * the result is review (fail closed).
+ * opts: { client, getPayment, onReview?, onResult? }
+ */
+export async function guardedRun(opts, args, run) {
+  let payment = null;
+  let extractError = "";
+  try {
+    payment = await opts.getPayment(args);
+  } catch (e) {
+    extractError = e?.message || String(e);
+  }
+  let res;
+  if (!payment || typeof payment !== "object" || !payment.to) {
+    res = result(DECISION.REVIEW, { reason_code: "input.payment_not_extracted", detail: `getPayment() did not return a payee${extractError ? ` (${extractError})` : ""}.`, failClosed: true });
+  } else {
+    res = await decidePayment(opts.client, payment);
+  }
+  try { opts.onResult?.(res, args); } catch { /* observer only */ }
+  if (res.decision === DECISION.DECLINE) throw new OceanAltDeclinedError(res);
+  if (res.decision === DECISION.REVIEW) {
+    let approved = false;
+    if (typeof opts.onReview === "function") {
+      try { approved = (await opts.onReview(res, args)) === true; } catch { approved = false; }
+    }
+    if (!approved) throw new OceanAltReviewRequiredError(res);
+  }
+  return run();
+}
+
+export function assertGuardOptions(opts, who) {
+  if (!opts || typeof opts.getPayment !== "function") throw new TypeError(`${who}: opts.getPayment(args) is required. It must return { to, amountUsdc?, network?, purpose? } for the payment the tool is about to make.`);
+  if (opts.onReview != null && typeof opts.onReview !== "function") throw new TypeError(`${who}: opts.onReview must be a function`);
+}

package/lib/evm.d.mts

@@ -0,0 +1,36 @@
+export declare const USDC: Readonly<Record<number, string>>;
+export declare function isAddress(v: unknown): v is `0x${string}`;
+export declare function big(v: unknown): bigint | null;
+export declare function chainIdOf(v: unknown): number | null;
+export declare function networkOf(chainId: number | null | undefined): string | undefined;
+export declare function isUsdc(chainId: number | null | undefined, token: string | null | undefined): boolean;
+export declare function usdcString(atomic: unknown): string | undefined;
+
+export type DecodedKind =
+  | "native-transfer" | "erc20-transfer" | "erc20-transferFrom" | "erc20-approve" | "erc20-increaseAllowance"
+  | "erc20-permit" | "setApprovalForAll" | "contract-call"
+  | "eip3009" | "permit" | "permit2-allowance" | "permit2-transfer"
+  | "unknown";
+
+/** What a transaction or signature authorizes. Amounts are atomic units as decimal strings. */
+export type Decoded = {
+  kind: DecodedKind;
+  payment?: boolean;
+  approval?: boolean;
+  payee?: string | null;
+  spender?: string | null;
+  amount?: string | null;
+  unlimited?: boolean;
+  token?: string | null;
+  contract?: string;
+  selector?: string;
+  primaryType?: string;
+  domainChainId?: number | null;
+  reason?: string;
+  [k: string]: unknown;
+};
+
+export declare function decodeTypedData(typedData: unknown): Decoded;
+export declare function decodeTransaction(tx: { to?: string | null; data?: string; value?: unknown } | null | undefined): Decoded;
+export declare function calldataOf(tx: { to?: string; data?: string; abi?: unknown; functionName?: string; args?: unknown[] }): Promise<{ data: string } | { error: string }>;
+export declare function parseSerialized(serialized: string): Promise<{ tx: { to: string | null; data: string; value: bigint; chainId: number | null } } | { error: string }>;

package/lib/evm.mjs

@@ -0,0 +1,176 @@
+// EVM decoding shared by @oceanalt/privy, @oceanalt/turnkey and @oceanalt/crossmint (identical copies; keep in sync).
+// decodeTransaction / decodeTypedData are adapted from @oceanalt/goat-plugin lib/guard.mjs.
+//
+// Pure functions, no network. They read what a signature or transaction actually authorizes (the real recipient
+// and amount inside ERC-20 calldata or an EIP-3009 authorization), not what the caller says it is for.
+
+const ADDR = /^0x[0-9a-fA-F]{40}$/;
+const UNLIMITED_FLOOR = 1n << 255n; // an approval this large is treated as unlimited
+
+// Circle USDC (6 decimals). Only for these is an amount sent to OceanAlt as amountUsdc.
+export const USDC = Object.freeze({
+  1: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
+  8453: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+  84532: "0x036cbd53842c5426634e7929541ec2318f3dcf7e",
+  42161: "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
+  421614: "0x75faf114eafb1bdbe2f0316df893fd58ce46aa4d",
+  10: "0x0b2c639c533813f4aa9d7837caf62653d097ff85",
+  11155420: "0x5fd84259d66cd46123540766be93dfe6d43130d7",
+  137: "0x3c499c542cef5e3811e1192ce70d8cc03d5c3359",
+  80002: "0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582",
+  43114: "0xb97ef9ef8734c71904d8002f8b6bc66dd9c48a6e",
+  11155111: "0x1c7d4b196cb0c7b01d743fbc6116a902379c7238",
+});
+
+const lc = (v) => (typeof v === "string" ? v.toLowerCase() : v);
+export const isAddress = (v) => typeof v === "string" && ADDR.test(v);
+
+/** BigInt from a number, decimal string or 0x hex string. null when absent or invalid. */
+export function big(v) {
+  if (v == null || v === "") return null;
+  try {
+    if (typeof v === "bigint") return v;
+    if (typeof v === "number") return Number.isSafeInteger(v) ? BigInt(v) : null;
+    return BigInt(String(v));
+  } catch { return null; }
+}
+
+/** chain id from a number, "0x2105", "8453" or "eip155:8453". null otherwise. */
+export function chainIdOf(v) {
+  if (v == null || v === "") return null;
+  const s = String(v);
+  const m = /^eip155:(\d+)$/i.exec(s);
+  const n = m ? Number(m[1]) : Number(big(s));
+  return Number.isSafeInteger(n) && n > 0 ? n : null;
+}
+
+export const networkOf = (chainId) => (chainId ? `eip155:${chainId}` : undefined);
+export const isUsdc = (chainId, token) => !!chainId && !!token && USDC[chainId] === lc(token);
+
+/** Exact atomic USDC (6 decimals) to a decimal string, e.g. 2500000n → "2.5". */
+export function usdcString(atomic) {
+  const a = big(atomic);
+  if (a == null || a < 0n) return undefined;
+  const whole = a / 1_000_000n;
+  const frac = (a % 1_000_000n).toString().padStart(6, "0").replace(/0+$/, "");
+  return frac ? `${whole}.${frac}` : `${whole}`;
+}
+
+/**
+ * Decode EIP-712 typed data. Accepts viem's shape (primaryType) and Privy's (primary_type), as an object or JSON string.
+ * kinds: eip3009 (TransferWithAuthorization / ReceiveWithAuthorization, the x402 "exact" EVM scheme), permit (EIP-2612),
+ *        permit2-allowance, permit2-transfer, unknown.
+ */
+export function decodeTypedData(typedData) {
+  let td = typedData;
+  if (typeof td === "string") { try { td = JSON.parse(td); } catch { return { kind: "unknown", reason: "typed data is not valid JSON" }; } }
+  if (!td || typeof td !== "object") return { kind: "unknown", reason: "typed data is empty" };
+  const pt = String(td.primaryType ?? td.primary_type ?? "");
+  const m = td.message && typeof td.message === "object" ? td.message : {};
+  const d = td.domain && typeof td.domain === "object" ? td.domain : {};
+  const base = { primaryType: pt, token: lc(d.verifyingContract) || null, domainChainId: chainIdOf(d.chainId) };
+
+  if (pt === "TransferWithAuthorization" || pt === "ReceiveWithAuthorization") {
+    if (!isAddress(m.to)) return { ...base, kind: "unknown", reason: `${pt} without a valid 'to'` };
+    return { ...base, kind: "eip3009", payment: true, approval: false, payee: lc(m.to), from: lc(m.from), amount: big(m.value)?.toString() ?? null };
+  }
+  if (pt === "Permit" && m.spender) {
+    const v = big(m.value);
+    return { ...base, kind: "permit", payment: false, approval: true, spender: lc(m.spender), amount: v?.toString() ?? null, unlimited: v != null && v >= UNLIMITED_FLOOR };
+  }
+  if (pt === "PermitSingle" || pt === "PermitBatch") {
+    const details = Array.isArray(m.details) ? m.details : [m.details || {}];
+    const amounts = details.map((x) => big(x?.amount));
+    return { ...base, kind: "permit2-allowance", payment: false, approval: true, spender: lc(m.spender), token: lc(details[0]?.token) || base.token, amount: amounts[0]?.toString() ?? null, unlimited: amounts.some((a) => a != null && a >= (1n << 159n)) };
+  }
+  if (pt === "PermitTransferFrom" || pt === "PermitWitnessTransferFrom" || pt === "PermitBatchTransferFrom" || pt === "PermitBatchWitnessTransferFrom") {
+    const perm = Array.isArray(m.permitted) ? m.permitted[0] : m.permitted;
+    return { ...base, kind: "permit2-transfer", payment: false, approval: true, spender: lc(m.spender), token: lc(perm?.token) || base.token, amount: big(perm?.amount)?.toString() ?? null, unlimited: false };
+  }
+  return { ...base, kind: "unknown", reason: pt ? `unrecognised primaryType '${pt}'` : "no primaryType" };
+}
+
+const SEL = {
+  a9059cbb: "transfer", "23b872dd": "transferFrom", "095ea7b3": "approve", "39509351": "increaseAllowance",
+  a22cb465: "setApprovalForAll", d505accf: "permit",
+};
+const word = (hex, i) => hex.slice(8 + i * 64, 8 + (i + 1) * 64);
+const wordAddr = (hex, i) => { const w = word(hex, i); return w.length === 64 ? "0x" + w.slice(24) : null; };
+const wordInt = (hex, i) => { const w = word(hex, i); return w.length === 64 ? BigInt("0x" + w) : null; };
+
+/** Decode an EVM call {to, data, value}: native transfer, ERC-20 transfer / transferFrom / approve / permit, or an opaque contract call. */
+export function decodeTransaction(tx) {
+  const to = lc(tx?.to);
+  if (!isAddress(to)) return { kind: "unknown", reason: "transaction has no valid 'to' (contract creation or malformed)" };
+  const data = String(tx?.data || "0x");
+  if (!/^0x[0-9a-fA-F]*$/.test(data)) return { kind: "unknown", reason: "calldata is not hex" };
+  const value = big(tx?.value) ?? 0n;
+  if (data === "0x") return { kind: "native-transfer", payment: true, approval: false, payee: to, amount: value.toString(), token: null };
+  const hex = data.slice(2);
+  const name = SEL[hex.slice(0, 8).toLowerCase()];
+  const out = { token: to, value: value.toString() };
+  const bad = (k) => ({ ...out, kind: "unknown", reason: `${k} calldata is truncated` });
+  switch (name) {
+    case "transfer": { const p = wordAddr(hex, 0), a = wordInt(hex, 1); return p && a != null ? { ...out, kind: "erc20-transfer", payment: true, approval: false, payee: p, amount: a.toString() } : bad(name); }
+    case "transferFrom": { const p = wordAddr(hex, 1), a = wordInt(hex, 2); return p && a != null ? { ...out, kind: "erc20-transferFrom", payment: true, approval: false, payee: p, amount: a.toString() } : bad(name); }
+    case "approve":
+    case "increaseAllowance": { const s = wordAddr(hex, 0), a = wordInt(hex, 1); return s && a != null ? { ...out, kind: `erc20-${name}`, payment: false, approval: true, spender: s, amount: a.toString(), unlimited: a >= UNLIMITED_FLOOR } : bad(name); }
+    case "setApprovalForAll": { const s = wordAddr(hex, 0), on = wordInt(hex, 1); return s && on != null ? { ...out, kind: "setApprovalForAll", payment: false, approval: on === 1n, spender: s, unlimited: on === 1n } : bad(name); }
+    case "permit": { const s = wordAddr(hex, 1), a = wordInt(hex, 2); return s && a != null ? { ...out, kind: "erc20-permit", payment: false, approval: true, spender: s, amount: a.toString(), unlimited: a >= UNLIMITED_FLOOR } : bad(name); }
+    default: return { ...out, kind: "contract-call", payment: false, approval: false, contract: to, selector: "0x" + hex.slice(0, 8) };
+  }
+}
+
+// Known ERC-20 functions, so { abi, functionName, args } calls are encoded without viem.
+const KNOWN = {
+  "transfer(address,uint256)": "a9059cbb",
+  "approve(address,uint256)": "095ea7b3",
+  "transferFrom(address,address,uint256)": "23b872dd",
+  "increaseAllowance(address,uint256)": "39509351",
+};
+const pad = (hex) => hex.padStart(64, "0");
+function encodeArg(type, v) {
+  if (type === "address") { if (!isAddress(String(v || ""))) throw new Error("bad address"); return pad(String(v).slice(2).toLowerCase()); }
+  if (type === "uint256") { const n = BigInt(v); if (n < 0n || n >= 1n << 256n) throw new Error("uint256 out of range"); return pad(n.toString(16)); }
+  throw new Error(`unsupported type ${type}`);
+}
+
+/**
+ * Hex calldata for { to, data } or { to, abi, functionName, args }. Returns { data } or { error }.
+ * Never guesses: an ABI call that can't be encoded is reported, not treated as a plain transfer.
+ */
+export async function calldataOf(tx) {
+  if (!tx?.abi) return { data: tx?.data || "0x" };
+  if (!tx.functionName) return { error: "ABI given without functionName" };
+  const fns = (Array.isArray(tx.abi) ? tx.abi : []).filter((x) => x?.type === "function" && x?.name === tx.functionName);
+  if (fns.length === 1) {
+    const sig = `${tx.functionName}(${(fns[0].inputs || []).map((i) => i.type).join(",")})`;
+    const sel = KNOWN[sig];
+    if (sel) {
+      try { return { data: "0x" + sel + (fns[0].inputs || []).map((inp, i) => encodeArg(inp.type, tx.args?.[i])).join("") }; }
+      catch (e) { return { error: `could not encode ${sig}: ${e.message}` }; }
+    }
+  }
+  try {
+    const viem = await import("viem");
+    return { data: viem.encodeFunctionData({ abi: tx.abi, functionName: tx.functionName, args: tx.args || [] }) };
+  } catch (e) {
+    return { error: `could not encode ${tx.functionName} (${e?.message || e})` };
+  }
+}
+
+/** Parse a serialized (RLP) unsigned transaction with viem. Returns { tx: { to, data, value, chainId } } or { error }. */
+export async function parseSerialized(serialized) {
+  const s = String(serialized || "");
+  const hex = s.startsWith("0x") ? s : `0x${s}`;
+  if (!/^0x[0-9a-fA-F]+$/.test(hex)) return { error: "serialized transaction is not hex" };
+  let viem;
+  try { viem = await import("viem"); } catch { return { error: "viem is not installed, so the serialized transaction could not be decoded" }; }
+  try {
+    const t = viem.parseTransaction(hex);
+    if (t.authorizationList?.length) return { error: "EIP-7702 transaction with an authorization list" };
+    return { tx: { to: t.to ?? null, data: t.data ?? "0x", value: t.value ?? 0n, chainId: t.chainId ?? null } };
+  } catch (e) {
+    return { error: `could not parse the serialized transaction (${e?.shortMessage || e?.message || e})` };
+  }
+}

package/lib/wallet-guard.d.mts

@@ -0,0 +1,59 @@
+import type { OceanAltClient } from "@oceanalt/core";
+import type { ClientOptions, PayeeResult, PaymentIntent } from "./decide.mjs";
+import type { Decoded } from "./evm.mjs";
+
+export type RequestKind = "transaction" | "typed-data" | "payment" | "message" | "non-evm" | "raw" | "batch" | "pass";
+
+/** One signing call, as the guard sees it. Passed to onReview / onResult. */
+export type SigningRequest = {
+  provider: string;
+  method: string;
+  kind: RequestKind;
+  chainId?: number | string | null;
+  calls?: Array<{ to?: string | null; data?: string; value?: unknown }>;
+  typedData?: unknown;
+  parts?: SigningRequest[];
+  reason_code?: string;
+  detail?: string;
+  /** The original arguments of the guarded method. */
+  input?: unknown;
+  /** Set on the copy passed to callbacks: one result per decoded call or signature. */
+  results?: Array<PayeeResult & { decoded: Decoded | null }>;
+  [k: string]: unknown;
+};
+
+export type WalletGuardOptions = ClientOptions & {
+  client?: OceanAltClient;
+  /** Called on "review". Return exactly true (after a human agreed) to sign anyway. Default: refuse. */
+  onReview?: (result: PayeeResult & { decoded: Decoded | null }, request: SigningRequest) => boolean | Promise<boolean>;
+  /** Observer for every decision. Errors thrown here are ignored. */
+  onResult?: (result: PayeeResult & { decoded: Decoded | null }, request: SigningRequest) => void;
+  /** Sent to OceanAlt as `purpose` (cut to 120 characters). */
+  purpose?: string;
+  /** personal_sign / signMessage. Default "review": messages are not decoded. */
+  signMessage?: "review" | "allow";
+  /** Contract calls that are not a transfer or approval. "screen-target" screens the contract address. Default "review". */
+  unknownCalls?: "review" | "screen-target";
+  /** Requests for non-EVM chains (Solana, Tron, Spark, ...). Default "review": they are not decoded. */
+  nonEvm?: "review" | "allow";
+};
+
+export declare const POLICY_DEFAULTS: Readonly<{ signMessage: "review"; unknownCalls: "review"; nonEvm: "review" }>;
+export declare function localReview(reason_code: string, detail: string, extra?: object): PayeeResult;
+export declare function alreadyChecked(): boolean;
+export declare function runChecked<T>(fn: () => T): T;
+export declare function itemFromDecoded(decoded: Decoded, chainId: number | null | undefined, opts?: WalletGuardOptions): {
+  decoded: Decoded;
+  payment?: PaymentIntent;
+  result?: PayeeResult;
+  unlimited?: boolean;
+  skip?: true;
+};
+export declare function createGate(opts?: WalletGuardOptions, defaults?: { userAgent?: string }): {
+  client: OceanAltClient;
+  /** Resolves when the request may be signed; throws OceanAltDeclinedError or OceanAltReviewRequiredError otherwise. */
+  check(request: SigningRequest): Promise<PayeeResult | null>;
+};
+export declare function defineGuarded(target: object, methods: Record<string, Function>): void;
+export declare function guardViemAccount<A extends { address: string }>(account: A, opts?: WalletGuardOptions & { provider?: string }): A;
+export declare function isGuardedAccount(account: unknown): boolean;

package/lib/wallet-guard.mjs

@@ -0,0 +1,202 @@
+// Wallet-level signing gate shared by @oceanalt/privy, @oceanalt/turnkey and @oceanalt/crossmint (identical copies; keep in sync).
+//
+// A provider adapter turns each signing call into a request:
+//   { provider, method, kind, chainId?, calls?, typedData?, parts?, reason_code?, detail?, input? }
+//   kind: "transaction" (one or more calls {to, data, value}) | "typed-data" | "payment" | "message" | "non-evm" | "raw" | "batch" | "pass"
+// The gate decodes it (real recipient and amount from ERC-20 calldata or EIP-3009 typed data), asks OceanAlt
+// POST /api/decide for each payee, and then:
+//   decline → throws OceanAltDeclinedError, nothing is signed
+//   review  → onReview(result, request) must return exactly true, otherwise throws OceanAltReviewRequiredError
+//   allow   → the original method runs
+// Anything it can't decode (raw hashes, EIP-7702 authorizations, user operations, unknown contract calls, other chains)
+// is review, never allow, unless an explicit policy option says otherwise.
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createClient, decidePayment, DECISION, OceanAltDeclinedError, OceanAltReviewRequiredError } from "./decide.mjs";
+import { decodeTransaction, decodeTypedData, isUsdc, usdcString, networkOf, chainIdOf, isAddress } from "./evm.mjs";
+
+const INSTRUCTION = {
+  allow: "No blocking findings. This is a screening result over public data, not a guarantee.",
+  review: "Do not pay yet. Ask a human to confirm, and show them the reason.",
+  decline: "Do not pay.",
+};
+const local = (decision, fields) => ({ decision, allow: decision === DECISION.ALLOW, instruction: INSTRUCTION[decision], ...fields });
+export const localReview = (reason_code, detail, extra = {}) => local(DECISION.REVIEW, { reason_code, detail, failClosed: true, ...extra });
+
+// One store per process, shared by every copy of this file. When an outer guard (a guarded viem account) has already
+// checked a call, the provider-level guard underneath (e.g. Turnkey signRawPayload) lets it through instead of asking twice.
+const ALS_KEY = Symbol.for("oceanalt.wallet-guard.checked");
+const als = (globalThis[ALS_KEY] ||= new AsyncLocalStorage());
+const CHECKED = Symbol.for("oceanalt.wallet-guard.checked.marker");
+export const alreadyChecked = () => als.getStore() === CHECKED;
+export const runChecked = (fn) => als.run(CHECKED, fn);
+
+export const POLICY_DEFAULTS = Object.freeze({ signMessage: "review", unknownCalls: "review", nonEvm: "review" });
+
+function policyError(opts) {
+  const ok = { signMessage: ["review", "allow"], unknownCalls: ["review", "screen-target"], nonEvm: ["review", "allow"] };
+  for (const [k, vals] of Object.entries(ok)) {
+    if (opts[k] != null && !vals.includes(opts[k])) return `opts.${k} must be one of ${vals.map((v) => `"${v}"`).join(", ")}`;
+  }
+  if (opts.onReview != null && typeof opts.onReview !== "function") return "opts.onReview must be a function";
+  if (opts.onResult != null && typeof opts.onResult !== "function") return "opts.onResult must be a function";
+  return "";
+}
+
+/** One decoded call or signature → what to send to OceanAlt, or a local result. */
+export function itemFromDecoded(decoded, chainId, opts = {}) {
+  const purpose = opts.purpose ? String(opts.purpose) : undefined;
+  if (decoded.kind === "unknown") return { decoded, result: localReview("calldata.undecodable", `Could not decode what this signs: ${decoded.reason}.`) };
+  if (decoded.domainChainId && chainId && decoded.domainChainId !== chainId) {
+    return { decoded, result: localReview("typed_data.chain_mismatch", `Typed data is for chain ${decoded.domainChainId} but the request names chain ${chainId}.`) };
+  }
+  const chain = decoded.domainChainId || chainId || null;
+  const network = networkOf(chain);
+  if (decoded.kind === "contract-call") {
+    if (opts.unknownCalls !== "screen-target") return { decoded, result: localReview("calldata.unrecognised", `Contract call ${decoded.selector} to ${decoded.contract} is not a transfer or approval this guard can read.`) };
+    return { decoded, payment: { to: decoded.contract, network, purpose } };
+  }
+  if (decoded.kind === "setApprovalForAll" && !decoded.approval) return { decoded, skip: true }; // a revocation
+  const to = decoded.payment ? decoded.payee : decoded.spender;
+  if (!isAddress(to)) return { decoded, result: localReview("calldata.undecodable", "Decoded call has no valid recipient or spender.") };
+  const amountUsdc = decoded.kind !== "native-transfer" && !decoded.unlimited && decoded.amount != null && isUsdc(chain, decoded.token) ? usdcString(decoded.amount) : undefined;
+  return { decoded, payment: { to, amountUsdc, network, purpose }, unlimited: !!decoded.unlimited };
+}
+
+function itemsOf(req, opts) {
+  switch (req.kind) {
+    case "pass": return [];
+    case "transaction": {
+      const calls = Array.isArray(req.calls) ? req.calls : [];
+      if (!calls.length) return [{ result: localReview("input.no_calls", "The request has no calls to check.") }];
+      return calls.map((c) => itemFromDecoded(decodeTransaction(c), chainIdOf(req.chainId), opts));
+    }
+    case "typed-data": return [itemFromDecoded(decodeTypedData(req.typedData), chainIdOf(req.chainId), opts)];
+    case "message":
+      return opts.signMessage === "allow" ? [] : [{ result: localReview("sign.message_not_decoded", "Message signatures are not decoded. A signed message can authorize things this guard can't see.") }];
+    case "non-evm":
+      return opts.nonEvm === "allow" ? [] : [{ result: localReview("chain.not_supported", req.detail || "Only EVM requests are decoded. This one was not checked.") }];
+    case "batch": return (req.parts || []).flatMap((p) => itemsOf(p, opts));
+    case "payment": { // a high-level transfer whose payee and amount the provider SDK states directly
+      const p = req.payment || {};
+      if (!isAddress(p.to)) return [{ result: localReview("payee.not_an_address", req.detail || "The payee is not an EVM address, so it can't be screened.") }];
+      return [{ decoded: req.decoded ?? null, payment: { to: p.to, amountUsdc: p.amountUsdc, network: networkOf(chainIdOf(req.chainId)) || p.network, purpose: opts.purpose ? String(opts.purpose) : undefined } }];
+    }
+    default: return [{ result: localReview(req.reason_code || "sign.not_decoded", req.detail || "This signing method is not decoded, so it was not checked.") }];
+  }
+}
+
+const RANK = { allow: 0, review: 1, decline: 2 };
+
+// Same error classes as the tool adapters; only the last sentence is about signing instead of a tool.
+function signingError(e) {
+  e.message = e.message.replace("The payment tool was not run.", "Nothing was signed.");
+  return e;
+}
+
+/**
+ * Build the gate. opts: { client?, baseUrl?, fetch?, apiKey?, timeoutMs?, onReview?, onResult?, purpose?,
+ * signMessage?, unknownCalls?, nonEvm? }. Returns { client, check(request) }.
+ */
+export function createGate(opts = {}, { userAgent } = {}) {
+  const err = policyError(opts);
+  if (err) throw new TypeError(err);
+  const client = opts.client || createClient({ baseUrl: opts.baseUrl, fetch: opts.fetch, apiKey: opts.apiKey, timeoutMs: opts.timeoutMs, userAgent });
+
+  async function check(request) {
+    if (alreadyChecked()) return null;
+    let items;
+    try { items = itemsOf(request, opts); } catch (e) { items = [{ result: localReview("input.unreadable", `Could not read the request (${e?.message || e}).`) }]; }
+    const results = [];
+    for (const it of items) {
+      let r;
+      if (it.result) r = it.result;
+      else if (it.skip) r = local(DECISION.ALLOW, { reason_code: "local.revocation", detail: "Revoking an approval; nothing to screen." });
+      else {
+        r = await decidePayment(client, it.payment);
+        if (it.unlimited && r.decision === DECISION.ALLOW) {
+          r = { ...r, decision: DECISION.REVIEW, allow: false, instruction: INSTRUCTION.review, reason_code: "approval.unlimited", detail: `OceanAlt allowed ${it.payment.to}, but this is an unlimited approval, so a human should confirm.` };
+        }
+      }
+      results.push({ ...r, decoded: it.decoded ?? null });
+    }
+    if (!results.length) return null; // nothing to check under the chosen policy
+    const worst = results.reduce((w, x) => (RANK[x.decision] > RANK[w.decision] ? x : w), results[0]);
+    const req = { ...request, results };
+    try { opts.onResult?.(worst, req); } catch { /* observer only */ }
+    if (worst.decision === DECISION.DECLINE) throw signingError(new OceanAltDeclinedError(worst));
+    if (worst.decision === DECISION.REVIEW) {
+      let approved = false;
+      if (typeof opts.onReview === "function") {
+        try { approved = (await opts.onReview(worst, req)) === true; } catch { approved = false; }
+      }
+      if (!approved) throw signingError(new OceanAltReviewRequiredError(worst));
+    }
+    return worst;
+  }
+  return { client, check };
+}
+
+/** Replace methods on an object in place with non-writable guarded versions. */
+export function defineGuarded(target, methods) {
+  for (const [name, fn] of Object.entries(methods)) {
+    Object.defineProperty(target, name, { value: fn, writable: false, configurable: false, enumerable: false });
+  }
+}
+
+const VIEM_GUARDED = Symbol.for("oceanalt.viem-account.guarded");
+
+/**
+ * Wrap a viem LocalAccount (e.g. Privy createViemAccount, Turnkey createAccount, privateKeyToAccount).
+ * Returns a new account object; the original stays unguarded.
+ *   signTransaction  decoded (native / ERC-20 transfer, approve, permit; other calls per unknownCalls)
+ *   signTypedData    decoded (EIP-3009 TransferWithAuthorization for x402, EIP-2612 Permit, Permit2)
+ *   signMessage      per opts.signMessage (default review)
+ *   sign, signAuthorization  always review (raw hash / EIP-7702 delegation)
+ */
+export function guardViemAccount(account, opts = {}) {
+  if (!account || typeof account !== "object" || !isAddress(account.address)) throw new TypeError("guardViemAccount(): expected a viem account with an address");
+  if (account.type && account.type !== "local") throw new TypeError(`guardViemAccount(): only local accounts are supported (got type '${account.type}')`);
+  if (account[VIEM_GUARDED]) return account;
+  const gate = createGate(opts, { userAgent: opts.userAgent || "oceanalt-viem-account/0.1.0" });
+  const provider = opts.provider || "viem";
+  const out = { ...account };
+  const m = {};
+  if (typeof account.signTransaction === "function") {
+    m.signTransaction = async (tx, o) => {
+      const req = tx?.authorizationList?.length
+        ? { provider, method: "signTransaction", kind: "raw", reason_code: "eip7702.authorization", detail: "Transaction carries an EIP-7702 authorization list (account delegation).", input: tx }
+        : { provider, method: "signTransaction", kind: "transaction", chainId: tx?.chainId, calls: [{ to: tx?.to, data: tx?.data ?? tx?.input ?? "0x", value: tx?.value }], input: tx };
+      await gate.check(req);
+      return runChecked(() => account.signTransaction(tx, o));
+    };
+  }
+  if (typeof account.signTypedData === "function") {
+    m.signTypedData = async (td) => {
+      await gate.check({ provider, method: "signTypedData", kind: "typed-data", typedData: td, input: td });
+      return runChecked(() => account.signTypedData(td));
+    };
+  }
+  if (typeof account.signMessage === "function") {
+    m.signMessage = async (p) => {
+      await gate.check({ provider, method: "signMessage", kind: "message", input: p });
+      return runChecked(() => account.signMessage(p));
+    };
+  }
+  if (typeof account.sign === "function") {
+    m.sign = async (p) => {
+      await gate.check({ provider, method: "sign", kind: "raw", reason_code: "sign.raw_hash", detail: "Signing a raw hash. What it authorizes can't be read.", input: p });
+      return runChecked(() => account.sign(p));
+    };
+  }
+  if (typeof account.signAuthorization === "function") {
+    m.signAuthorization = async (p) => {
+      await gate.check({ provider, method: "signAuthorization", kind: "raw", reason_code: "eip7702.authorization", detail: "EIP-7702 authorization: delegates this account to contract code.", input: p });
+      return runChecked(() => account.signAuthorization(p));
+    };
+  }
+  defineGuarded(out, m);
+  Object.defineProperty(out, VIEM_GUARDED, { value: { client: gate.client }, enumerable: false });
+  return out;
+}
+
+export const isGuardedAccount = (a) => !!a?.[VIEM_GUARDED];

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "@oceanalt/crossmint",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Guard for Crossmint wallets: ask OceanAlt about the real payee (allow / review / decline) before a Crossmint EVM wallet sends, signs an x402 authorization or approves. Fails closed. No keys, no custody. Not affiliated with Crossmint.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./index.mjs",
+  "types": "./index.d.ts",
+  "exports": { ".": { "types": "./index.d.ts", "import": "./index.mjs", "default": "./index.mjs" } },
+  "files": ["index.mjs", "index.d.ts", "lib/decide.mjs", "lib/decide.d.mts", "lib/evm.mjs", "lib/evm.d.mts", "lib/wallet-guard.mjs", "lib/wallet-guard.d.mts", "README.md", "LICENSE"],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "engines": { "node": ">=20" },
+  "dependencies": {
+    "@oceanalt/core": "^0.2.0"
+  },
+  "peerDependencies": {
+    "@crossmint/wallets-sdk": ">=1.20.0 <2.0.0",
+    "viem": "^2.0.0"
+  },
+  "devDependencies": {
+    "@crossmint/wallets-sdk": "^1.20.0",
+    "viem": "^2.56.9"
+  },
+  "homepage": "https://oceanalt.com/en/api-docs",
+  "bugs": { "email": "business@oceanalt.com" },
+  "keywords": ["crossmint", "agent-wallets", "smart-wallets", "x402", "eip-3009", "agent-payments", "pre-signing", "aml"]
+}