@oracle-agent/oracle 0.1.0

package/src/scanner/v2-venue.mjs

@@ -0,0 +1,335 @@
+// Venue-backed capabilities: quote, sellSimulation, prepareUnsignedTx.
+//
+// These are the three capabilities the generic scanner cannot provide, because each
+// one needs a VERIFIED router address for the specific chain. That is not a gap to
+// paper over -- it is the reason the destination allowlist exists.
+//
+// Scope: Uniswap-V2-style routers (getAmountsOut / swapExactTokensForTokens), which
+// covers the large majority of forks across EVM chains. A V3/V4 or custom-quoter
+// venue needs its own adapter; see the notes at the bottom.
+//
+// Custody: prepareUnsignedTx returns an UNSIGNED transaction object. Nothing here
+// holds a key, signs, or broadcasts. The user's wallet does that.
+
+import { rpcCall } from "../data/providers/evm-rpc.mjs";
+import { EVIDENCE, RISK } from "./contract.mjs";
+
+// --- ABI encode/decode, kept dependency-free ---------------------------------
+
+const SEL = {
+  // getAmountsOut(uint256,address[])
+  getAmountsOut: "d06ca61f",
+  // swapExactTokensForTokens(uint256,uint256,address[],address,uint256)
+  swapExactTokensForTokens: "38ed1739",
+  // swapExactETHForTokens(uint256,address[],address,uint256)
+  swapExactETHForTokens: "7ff36ab5",
+};
+
+const word = (v) => BigInt(v).toString(16).padStart(64, "0");
+const addrWord = (a) => a.slice(2).toLowerCase().padStart(64, "0");
+
+function encodeAmountsOut(amountIn, path) {
+  return (
+    `0x${SEL.getAmountsOut}` +
+    word(amountIn) +
+    word(64) + // offset to the array
+    word(path.length) +
+    path.map(addrWord).join("")
+  );
+}
+
+/** Decode a `uint256[]` return. */
+function decodeUintArray(hex) {
+  if (!hex || hex === "0x") return null;
+  const b = hex.slice(2);
+  if (b.length < 128) return null;
+  const n = Number(BigInt(`0x${b.slice(64, 128)}`));
+  if (!Number.isFinite(n) || n < 1 || n > 16) return null;
+  const out = [];
+  for (let i = 0; i < n; i++) {
+    const start = 128 + i * 64;
+    if (b.length < start + 64) return null;
+    out.push(BigInt(`0x${b.slice(start, start + 64)}`));
+  }
+  return out;
+}
+
+function routerOf(scanner, kind = "router") {
+  const v = (scanner?.venues || []).find((x) => x.kind === kind);
+  return v?.address ?? null;
+}
+
+/**
+ * Apply a slippage guard to get minOut.
+ *
+ * The supplied tolerance is a MAXIMUM, not the value to use, and it is capped hard.
+ * A guard that yields under pressure is decoration -- if a route needs more than the
+ * cap, the correct answer is to block and requote, not to widen.
+ */
+const MAX_SLIPPAGE_BPS = 100;
+
+export function applySlippage(amountOut, slippageBps) {
+  const bps = Number(slippageBps);
+  if (!Number.isFinite(bps) || bps < 0) {
+    throw new Error("slippageBps must be a non-negative number");
+  }
+  if (bps > MAX_SLIPPAGE_BPS) {
+    throw new Error(
+      `slippageBps ${bps} exceeds the ${MAX_SLIPPAGE_BPS} bps ceiling. ` +
+        "Block and requote or split the order -- do not widen the guard to force a fill.",
+    );
+  }
+  return (BigInt(amountOut) * BigInt(10_000 - Math.floor(bps))) / 10_000n;
+}
+
+// --- capability implementations ----------------------------------------------
+
+/**
+ * Build the venue-backed capabilities for a chain that has a verified V2 router.
+ *
+ * @param {object} cfg
+ * @param {number} cfg.chainId
+ * @param {string} [cfg.wrappedNative] needed to route native<->token
+ */
+export function v2VenueCapabilities(cfg) {
+  const { chainId, wrappedNative } = cfg;
+
+  async function amountsOut(router, amountIn, path, opts) {
+    const res = await rpcCall(
+      chainId,
+      "eth_call",
+      [{ to: router, data: encodeAmountsOut(amountIn, path) }, "latest"],
+      opts,
+    );
+    return decodeUintArray(res?.result ?? res);
+  }
+
+  return {
+    /**
+     * Price an exact-input route. Read-only; touches no state.
+     */
+    async quote({ tokenIn, tokenOut, amountIn, path }, opts = {}) {
+      const router = routerOf(opts.scanner);
+      if (!router) {
+        return {
+          chainId,
+          evidence: EVIDENCE.UNAVAILABLE,
+          reason:
+            "no verified router configured for this chain; quoting stays fail-closed " +
+            "rather than guessing a venue address",
+        };
+      }
+      const route = path || [tokenIn, tokenOut];
+      if (route.some((a) => !/^0x[0-9a-fA-F]{40}$/.test(a || ""))) {
+        throw new Error("quote requires valid 20-byte addresses");
+      }
+
+      const amounts = await amountsOut(router, amountIn, route, opts);
+      if (!amounts) {
+        return {
+          chainId,
+          router,
+          path: route,
+          evidence: EVIDENCE.UNKNOWN,
+          reason: "router returned no amounts -- no pool for this path, or the call reverted",
+        };
+      }
+
+      return {
+        chainId,
+        router,
+        path: route,
+        amountIn: String(amountIn),
+        amountOut: amounts[amounts.length - 1].toString(),
+        hops: route.length - 1,
+        evidence: EVIDENCE.LIVE,
+        // The price a quote reports is pre-slippage and pre-gas. Saying so prevents
+        // it being read as an expected fill.
+        note: "exact-input quote at current reserves; not a guaranteed fill",
+      };
+    },
+
+    /**
+     * Round-trip check: buy the token, then sell it back.
+     *
+     * This is the single most valuable check on a low-cap venue. Most losses are not
+     * bad entries -- they are tokens that buy cleanly and cannot be sold. A
+     * successful BUY quote proves nothing about the sell side.
+     *
+     * State-free: both legs are eth_call quotes, so nothing is spent to learn this.
+     */
+    async sellSimulation({ token, amountIn, base }, opts = {}) {
+      const router = routerOf(opts.scanner);
+      const quoteBase = base || wrappedNative;
+      if (!router || !quoteBase) {
+        return {
+          chainId,
+          token,
+          verdict: RISK.UNKNOWN,
+          evidence: EVIDENCE.UNAVAILABLE,
+          reason: router
+            ? "no wrappedNative configured for this chain, so no base asset to round-trip against"
+            : "no verified router configured for this chain",
+        };
+      }
+
+      const buy = await amountsOut(router, amountIn, [quoteBase, token], opts);
+      if (!buy) {
+        return {
+          chainId,
+          token,
+          verdict: RISK.FAIL,
+          evidence: EVIDENCE.LIVE,
+          leg: "buy",
+          reason: "buy leg returned no amounts -- no route in",
+        };
+      }
+      const bought = buy[buy.length - 1];
+      if (bought === 0n) {
+        return {
+          chainId,
+          token,
+          verdict: RISK.FAIL,
+          evidence: EVIDENCE.LIVE,
+          leg: "buy",
+          reason: "buy leg quotes zero output",
+        };
+      }
+
+      const sell = await amountsOut(router, bought, [token, quoteBase], opts);
+      if (!sell) {
+        // The honeypot signature: in works, out does not.
+        return {
+          chainId,
+          token,
+          verdict: RISK.FAIL,
+          evidence: EVIDENCE.LIVE,
+          leg: "sell",
+          bought: bought.toString(),
+          reason:
+            "SELL LEG FAILED while the buy leg quoted fine. This is the honeypot " +
+            "signature: do not trade.",
+        };
+      }
+
+      const returned = sell[sell.length - 1];
+      // Retention in bps of the original input. A clean V2 round trip loses roughly
+      // 2x the pool fee plus impact, so ~9940 bps on a deep pool at small size.
+      const retentionBps = Number((returned * 10_000n) / BigInt(amountIn));
+
+      // Thresholds are deliberately loose: this separates "taxed or illiquid" from
+      // "normal", not "good trade" from "bad trade".
+      let verdict = RISK.PASS;
+      let reason = "round trip completes with expected fee/impact loss";
+      if (retentionBps < 5_000) {
+        verdict = RISK.FAIL;
+        reason = `round trip returns only ${(retentionBps / 100).toFixed(2)}% -- punitive tax or no real liquidity`;
+      } else if (retentionBps < 9_000) {
+        verdict = RISK.CAUTION;
+        reason = `round trip returns ${(retentionBps / 100).toFixed(2)}% -- transfer tax or thin liquidity at this size`;
+      }
+
+      return {
+        chainId,
+        token,
+        base: quoteBase,
+        router,
+        verdict,
+        reason,
+        amountIn: String(amountIn),
+        bought: bought.toString(),
+        returned: returned.toString(),
+        retentionBps,
+        evidence: EVIDENCE.LIVE,
+        note: "Quote-level round trip. It does not prove transfer hooks absent at execution time.",
+      };
+    },
+
+    /**
+     * Build an UNSIGNED swap transaction.
+     *
+     * Returns a plain transaction object for the caller's wallet to sign. There is no
+     * signing path in this module by construction.
+     */
+    async prepareUnsignedTx(
+      { tokenIn, tokenOut, amountIn, recipient, slippageBps = 50, deadlineSeconds = 900, path },
+      opts = {},
+    ) {
+      const scanner = opts.scanner;
+      const router = routerOf(scanner);
+      if (!router) {
+        throw new Error(
+          `chain ${chainId} has no verified router; preparing a swap stays fail-closed. ` +
+            "Add a venue with recorded provenance first (see docs/adding-a-chain.md).",
+        );
+      }
+      if (!/^0x[0-9a-fA-F]{40}$/.test(recipient || "")) {
+        throw new Error("prepareUnsignedTx requires a valid recipient address");
+      }
+
+      const route = path || [tokenIn, tokenOut];
+      const q = await this.quote({ tokenIn, tokenOut, amountIn, path: route }, opts);
+      if (q.evidence !== EVIDENCE.LIVE) {
+        throw new Error(
+          `cannot prepare without a live quote (${q.evidence}: ${q.reason ?? "no reason given"})`,
+        );
+      }
+
+      // Guard computed from the live quote, not from a stale number.
+      const minOut = applySlippage(q.amountOut, slippageBps);
+      if (minOut <= 0n) throw new Error("computed minOut is zero -- refusing to prepare");
+
+      const deadline = BigInt(Math.floor(Date.now() / 1000) + Number(deadlineSeconds));
+      const isNativeIn =
+        wrappedNative && route[0].toLowerCase() === wrappedNative.toLowerCase() && opts.useNative;
+
+      const data = isNativeIn
+        ? `0x${SEL.swapExactETHForTokens}` +
+          word(minOut) +
+          word(128) +
+          addrWord(recipient) +
+          word(deadline) +
+          word(route.length) +
+          route.map(addrWord).join("")
+        : `0x${SEL.swapExactTokensForTokens}` +
+          word(amountIn) +
+          word(minOut) +
+          word(160) +
+          addrWord(recipient) +
+          word(deadline) +
+          word(route.length) +
+          route.map(addrWord).join("");
+
+      return {
+        unsigned: true,
+        signedBy: "user-wallet",
+        chainId,
+        tx: {
+          to: router,
+          data,
+          value: isNativeIn ? `0x${BigInt(amountIn).toString(16)}` : "0x0",
+        },
+        guard: {
+          quotedOut: q.amountOut,
+          minOut: minOut.toString(),
+          slippageBps,
+          maxSlippageBps: MAX_SLIPPAGE_BPS,
+          deadline: deadline.toString(),
+        },
+        // An ERC-20 input needs an allowance first. Reporting it as a separate step
+        // keeps "approved" and "swapped" from being collapsed into one claim.
+        requires: isNativeIn
+          ? []
+          : [{ step: "approve", token: route[0], spender: router, amount: String(amountIn) }],
+        note:
+          "UNSIGNED. Re-verify the guard against a fresh quote immediately before " +
+          "signing -- a quote-time minimum is not a minimum at broadcast time.",
+      };
+    },
+  };
+}
+
+// A V3/V4 or custom-quoter venue does NOT fit this adapter: V3 needs a Quoter
+// contract and fee tiers, and some forks require an off-chain signed quote that
+// cannot be forged locally. Write a sibling adapter rather than bending this one --
+// silently mis-encoding a swap is worse than declaring the capability unsupported.

package/src/scanner/v3-venue.mjs

@@ -0,0 +1,290 @@
+// Uniswap V3 venue adapter.
+//
+// The V2 adapter cannot be bent to cover V3: V3 has no getAmountsOut, prices through
+// a separate Quoter contract, and requires an explicit fee tier per hop. Encoding a
+// V3 swap with V2 assumptions produces a transaction that looks plausible and
+// reverts -- or worse, routes through the wrong pool. So this is a sibling adapter,
+// as docs/adding-a-chain.md prescribes.
+//
+// Custody is unchanged: quotes are eth_call, prepare returns an UNSIGNED tx, and
+// nothing in this module can sign or broadcast.
+
+import { rpcCall } from "../data/providers/evm-rpc.mjs";
+import { EVIDENCE, RISK } from "./contract.mjs";
+
+// Standard V3 fee tiers, cheapest first. 100 (0.01%) exists mainly for stable pairs.
+export const FEE_TIERS = [100, 500, 3000, 10000];
+
+const SEL = {
+  // QuoterV2.quoteExactInputSingle((address,address,uint256,uint24,uint160))
+  quoteExactInputSingle: "c6a5026a",
+  // SwapRouter02.exactInputSingle((address,address,uint24,address,uint256,uint256,uint160))
+  exactInputSingle: "04e45aaf",
+};
+
+const word = (v) => BigInt(v).toString(16).padStart(64, "0");
+const addrWord = (a) => a.slice(2).toLowerCase().padStart(64, "0");
+const ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+
+const MAX_SLIPPAGE_BPS = 100;
+
+export function applySlippage(amountOut, slippageBps) {
+  const bps = Number(slippageBps);
+  if (!Number.isFinite(bps) || bps < 0) {
+    throw new Error("slippageBps must be a non-negative number");
+  }
+  if (bps > MAX_SLIPPAGE_BPS) {
+    throw new Error(
+      `slippageBps ${bps} exceeds the ${MAX_SLIPPAGE_BPS} bps ceiling. ` +
+        "Block and requote or split the order -- do not widen the guard to force a fill.",
+    );
+  }
+  return (BigInt(amountOut) * BigInt(10_000 - Math.floor(bps))) / 10_000n;
+}
+
+function venueOf(scanner, kind) {
+  return (scanner?.venues || []).find((v) => v.kind === kind)?.address ?? null;
+}
+
+/**
+ * Build V3 capabilities for a chain with a verified quoter + router.
+ *
+ * @param {object} cfg
+ * @param {number} cfg.chainId
+ * @param {string} [cfg.wrappedNative]
+ */
+export function v3VenueCapabilities(cfg) {
+  const { chainId, wrappedNative } = cfg;
+
+  /** Quote one fee tier. Returns null when that tier has no usable pool. */
+  async function quoteTier({ quoter, tokenIn, tokenOut, amountIn, fee }, opts) {
+    const data =
+      `0x${SEL.quoteExactInputSingle}` +
+      addrWord(tokenIn) +
+      addrWord(tokenOut) +
+      word(amountIn) +
+      word(fee) +
+      word(0); // sqrtPriceLimitX96 = 0, no limit
+
+    const r = await rpcCall(chainId, "eth_call", [{ to: quoter, data }, "latest"], opts).catch(
+      () => null,
+    );
+    const raw = r?.result ?? r;
+    if (!raw || raw === "0x" || raw.length < 66) return null;
+    const out = BigInt(`0x${raw.slice(2, 66)}`);
+    return out > 0n ? out : null;
+  }
+
+  /**
+   * Try every fee tier and keep the best.
+   *
+   * Necessary rather than a nicety: liquidity for a given pair concentrates in one
+   * tier, and which tier varies by pair and chain. Guessing 0.3% because it is the
+   * common default silently misprices stable pairs and exotic pairs alike.
+   */
+  async function bestQuote({ quoter, tokenIn, tokenOut, amountIn }, opts) {
+    const tried = [];
+    let best = null;
+
+    for (const fee of FEE_TIERS) {
+      const out = await quoteTier({ quoter, tokenIn, tokenOut, amountIn, fee }, opts);
+      tried.push({ fee, amountOut: out ? out.toString() : null });
+      if (out && (!best || out > best.amountOut)) best = { fee, amountOut: out };
+    }
+    return { best, tried };
+  }
+
+  return {
+    async quote({ tokenIn, tokenOut, amountIn }, opts = {}) {
+      const quoter = venueOf(opts.scanner, "quoter");
+      if (!quoter) {
+        return {
+          chainId,
+          evidence: EVIDENCE.UNAVAILABLE,
+          reason:
+            "no verified quoter configured for this chain; quoting stays fail-closed " +
+            "rather than guessing a venue address",
+        };
+      }
+      for (const a of [tokenIn, tokenOut]) {
+        if (!ADDRESS_RE.test(a || "")) throw new Error("quote requires valid 20-byte addresses");
+      }
+
+      const { best, tried } = await bestQuote({ quoter, tokenIn, tokenOut, amountIn }, opts);
+      if (!best) {
+        return {
+          chainId,
+          quoter,
+          tokenIn,
+          tokenOut,
+          triedFeeTiers: tried,
+          evidence: EVIDENCE.UNKNOWN,
+          reason: "no fee tier returned a quote -- no V3 pool for this pair, or no liquidity",
+        };
+      }
+
+      return {
+        chainId,
+        venue: "uniswap-v3",
+        quoter,
+        tokenIn,
+        tokenOut,
+        amountIn: String(amountIn),
+        amountOut: best.amountOut.toString(),
+        fee: best.fee,
+        triedFeeTiers: tried,
+        evidence: EVIDENCE.LIVE,
+        note: "exact-input single-hop quote at current tick; not a guaranteed fill",
+      };
+    },
+
+    /**
+     * Round trip: buy the token with the base asset, then sell it back.
+     *
+     * Same reasoning as the V2 adapter -- a clean buy quote proves nothing about the
+     * exit, and a token you cannot sell is the most expensive kind of mistake.
+     */
+    async sellSimulation({ token, amountIn, base }, opts = {}) {
+      const quoter = venueOf(opts.scanner, "quoter");
+      const quoteBase = base || wrappedNative;
+      if (!quoter || !quoteBase) {
+        return {
+          chainId,
+          token,
+          verdict: RISK.UNKNOWN,
+          evidence: EVIDENCE.UNAVAILABLE,
+          reason: quoter
+            ? "no wrappedNative configured, so there is no base asset to round-trip against"
+            : "no verified quoter configured for this chain",
+        };
+      }
+
+      const buy = await bestQuote(
+        { quoter, tokenIn: quoteBase, tokenOut: token, amountIn },
+        opts,
+      );
+      if (!buy.best) {
+        return {
+          chainId,
+          token,
+          verdict: RISK.FAIL,
+          evidence: EVIDENCE.LIVE,
+          leg: "buy",
+          reason: "no V3 pool priced the buy leg on any fee tier",
+        };
+      }
+
+      const sell = await bestQuote(
+        { quoter, tokenIn: token, tokenOut: quoteBase, amountIn: buy.best.amountOut },
+        opts,
+      );
+      if (!sell.best) {
+        return {
+          chainId,
+          token,
+          verdict: RISK.FAIL,
+          evidence: EVIDENCE.LIVE,
+          leg: "sell",
+          bought: buy.best.amountOut.toString(),
+          reason:
+            "SELL LEG FAILED while the buy leg quoted fine. This is the honeypot " +
+            "signature: do not trade.",
+        };
+      }
+
+      const returned = sell.best.amountOut;
+      const retentionBps = Number((returned * 10_000n) / BigInt(amountIn));
+
+      let verdict = RISK.PASS;
+      let reason = "round trip completes with expected fee/impact loss";
+      if (retentionBps < 5_000) {
+        verdict = RISK.FAIL;
+        reason = `round trip returns only ${(retentionBps / 100).toFixed(2)}% -- punitive tax or no real liquidity`;
+      } else if (retentionBps < 9_000) {
+        verdict = RISK.CAUTION;
+        reason = `round trip returns ${(retentionBps / 100).toFixed(2)}% -- transfer tax or thin liquidity at this size`;
+      }
+
+      return {
+        chainId,
+        venue: "uniswap-v3",
+        token,
+        base: quoteBase,
+        verdict,
+        reason,
+        amountIn: String(amountIn),
+        bought: buy.best.amountOut.toString(),
+        returned: returned.toString(),
+        retentionBps,
+        buyFee: buy.best.fee,
+        sellFee: sell.best.fee,
+        evidence: EVIDENCE.LIVE,
+        note: "Quote-level round trip. It does not prove transfer hooks absent at execution time.",
+      };
+    },
+
+    /**
+     * Build an UNSIGNED exactInputSingle swap.
+     *
+     * The fee tier comes from the live quote rather than a default, so the prepared
+     * transaction routes through the same pool that produced the price.
+     */
+    async prepareUnsignedTx(
+      { tokenIn, tokenOut, amountIn, recipient, slippageBps = 50, fee },
+      opts = {},
+    ) {
+      const router = venueOf(opts.scanner, "router");
+      if (!router) {
+        throw new Error(
+          `chain ${chainId} has no verified V3 router; preparing a swap stays fail-closed. ` +
+            "Add a venue with recorded provenance first (see docs/adding-a-chain.md).",
+        );
+      }
+      if (!ADDRESS_RE.test(recipient || "")) {
+        throw new Error("prepareUnsignedTx requires a valid recipient address");
+      }
+
+      const q = await this.quote({ tokenIn, tokenOut, amountIn }, opts);
+      if (q.evidence !== EVIDENCE.LIVE) {
+        throw new Error(
+          `cannot prepare without a live quote (${q.evidence}: ${q.reason ?? "no reason given"})`,
+        );
+      }
+
+      const useFee = fee ?? q.fee;
+      const minOut = applySlippage(q.amountOut, slippageBps);
+      if (minOut <= 0n) throw new Error("computed minOut is zero -- refusing to prepare");
+
+      const data =
+        `0x${SEL.exactInputSingle}` +
+        addrWord(tokenIn) +
+        addrWord(tokenOut) +
+        word(useFee) +
+        addrWord(recipient) +
+        word(amountIn) +
+        word(minOut) +
+        word(0); // sqrtPriceLimitX96
+
+      return {
+        unsigned: true,
+        signedBy: "user-wallet",
+        chainId,
+        venue: "uniswap-v3",
+        tx: { to: router, data, value: "0x0" },
+        guard: {
+          quotedOut: q.amountOut,
+          minOut: minOut.toString(),
+          slippageBps,
+          maxSlippageBps: MAX_SLIPPAGE_BPS,
+          fee: useFee,
+        },
+        requires: [
+          { step: "approve", token: tokenIn, spender: router, amount: String(amountIn) },
+        ],
+        note:
+          "UNSIGNED. Re-verify the guard against a fresh quote immediately before " +
+          "signing -- a quote-time minimum is not a minimum at broadcast time.",
+      };
+    },
+  };
+}

package/src/scopes.mjs

@@ -0,0 +1,44 @@
+// Delegation scopes — mirrors the RH agent's Agent Connect model so a user's
+// scoped key can only ever authorize actions on THEIR OWN wallet.
+
+export const ALLOWED_SCOPES = new Set([
+  "read:markets",
+  "read:nfts",
+  "read:positions",
+  "watch:contracts",
+  "prepare:trade",
+  "prepare:mint",
+  // Build verb. `prepare:build` produces a non-executable proposal describing
+  // what would be created. `build:factory` authorizes actually calling an
+  // ALLOWLISTED factory — never arbitrary bytecode. See public-control/build-registry.mjs
+  "prepare:build",
+  "build:factory",
+  "agent:shadow",
+  "agent:execute",
+]);
+
+export const EXECUTE_SCOPE = "agent:execute";
+/** Authorizes a real factory call. Gated separately from agent:execute so that
+ *  arming trading never implicitly arms contract creation. */
+export const BUILD_SCOPE = "build:factory";
+
+// Safe default: everything EXCEPT live execution and live building.
+export const DEFAULT_SCOPES = [
+  "read:markets",
+  "read:nfts",
+  "read:positions",
+  "watch:contracts",
+  "prepare:trade",
+  "prepare:mint",
+  "prepare:build",
+  "agent:shadow",
+];
+
+/** Validate + dedupe requested scopes; empty falls back to DEFAULT_SCOPES. */
+export function normalizeScopes(scopes) {
+  const requested = Array.isArray(scopes) && scopes.length ? scopes : DEFAULT_SCOPES;
+  const normalized = [...new Set(requested.map((s) => String(s).trim()).filter(Boolean))];
+  const invalid = normalized.filter((s) => !ALLOWED_SCOPES.has(s));
+  if (invalid.length) throw new Error(`Invalid scope: ${invalid.join(", ")}`);
+  return normalized;
+}