@oracle-agent/oracle 0.10.0 → 0.12.0

package/SETUP.md

@@ -1,381 +1,316 @@
-# Setup
+# Oracle setup
 
-## Unified CLI
+Oracle's public CLI is a standalone, prepare-only multichain agent. It can read,
+research, quote, simulate, and build unsigned artifacts. It does not need Hermes,
+it does not accept wallet private keys, and it does not broadcast transactions.
 
-Prefer the root `oracle` command:
+The owner-operated signer/executor is private infrastructure. It is not published
+on npm and is not part of public or holder onboarding.
 
-```bash
-npm i -g @oracle-agent/oracle
-oracle
-oracle init --apply
-oracle doctor
-```
+## Requirements
 
-Full reference: [docs/cli.md](./docs/cli.md). Connectors: [docs/connectors.md](./docs/connectors.md).
+- Node.js `20.19.0` or newer
+- npm
+- A supported model login or API key for chat
+- A user-controlled wallet only when reviewing and signing a prepared artifact
 
+Linux, Windows, and macOS apps are in beta.
 
-Oracle's public surface runs locally against your API accounts and never accepts
-a wallet private key. Prepared actions are signed in the user's wallet.
-
-## Install
+## 1. Install the standalone CLI
 
 ```bash
-npm install @oracle-agent/oracle    # Node >= 20.19.0
+npm view @oracle-agent/oracle version
+npm i -g @oracle-agent/oracle@latest
+oracle --version
 ```
 
-Or from source, if you want to run the suite:
+The npm `latest` tag is the install source of truth. The repository can contain
+an unreleased next version, so do not infer the published version from a branch.
+
+For a project-local library install instead:
 
 ```bash
-git clone https://github.com/demi-hl/oracle.git
-cd oracle
-npm install
-npm test
+npm i @oracle-agent/oracle@latest
 ```
 
-## The one thing to understand first
+The package declares this floor through `engines`; `oracle doctor` treats an
+unsupported Node runtime as blocking. npm may only warn unless the user's npm
+configuration enables strict engine checks, so verify `node --version` yourself.
 
-Oracle has two distribution boundaries and they are separate on purpose:
+## 2. Authenticate a model provider
 
-| Plane | What it does | Needs a key? |
-|---|---|---|
-| **Read / prepare** | Market data, quotes, and *unsigned* transactions or EIP-712 actions | No, mostly |
-| **Owner-local source lane** | Optional companion `@oracle-agent/operator` — keys on YOUR machine | Yes |
+### OAuth
 
-A prepared object is inert. It becomes real only when something signs it. You
-choose whether that something is your browser wallet or separately operated
-owner-local infrastructure.
-
-## Public posture: always prepare-only
-
-The public data facade rejects `hl-exec` even when a signing key exists in the
-environment. The npm artifact excludes the key vault and live signer modules.
-Wallet signing, submission, receipt confirmation, and revocation happen outside
-that public surface.
-
-### Capability is not authorization
-
-The public Oracle profile must report these as separate planes:
-
-| Plane | Default capability |
-|---|---|
-| Public Oracle package | read, quote, simulate, unsigned prepare |
-| Generic `oracle-signer` daemon | six bounded surfaces: `hl`, `poly`, `evm-swap`, `evm-bridge`, `btc`, `sol` (each fails closed on empty allowlists) |
-| Ordinary EVM | unsigned preparation, user-wallet signature |
-| Optional owner-gated EVM executor | one exact bounded action after explicit `arm` |
-
-The optional EVM executor is not bundled into this public package and must never be exposed over LAN or a tailnet. A profile may describe bounded EVM execution as available only after verifying that separate local executor and its owner gate. Otherwise say the current deployment is prepare-only. Do not claim EVM execution is universally impossible.
-
-Action records require explicit fields:
-
-```json
-{
-  "active": true,
-  "actionMode": "alert_only"
-}
+```bash
+oracle auth login claude
+# or
+oracle auth login codex
+oracle auth login grok
 ```
 
-`watch`, `watch this`, and `ping me` always use `alert_only`. `arm` uses `execute` only for one exact owner-authorized action. A legacy `status: armed` field is not execution authority.
+The command opens the provider's authorization flow and selects its default
+model. Use `--no-browser` when the browser must be opened manually.
 
----
-
-## Source-only operator credentials
-
-This section applies only to an owner-local source checkout. These signing
-credentials are not consumed by the public package entrypoints.
-
-## Keys: what each one unlocks
-
-Everything is optional. Oracle degrades to whatever you have configured.
-
-### Hyperliquid — perps, spot, staking
-
-Hyperliquid does not issue API keys. You authorize with an **Ethereum private
-key**, either your account key or (recommended) an **API wallet**.
-
-Create an API wallet at <https://app.hyperliquid.xyz/API>. It can trade your
-account but **cannot withdraw**, which is exactly what you want for an agent.
+### API key
 
 ```bash
-export HL_PRIVATE_KEY=0xabc...          # the API wallet's key
-# or, better, keep it in a file:
-export HL_KEY_FILE=~/.config/oracle/keys/hl.key
+oracle auth api-key openrouter
+# also supported: openai, xai, deepseek, gemini, custom
 ```
 
-Reads (prices, funding, order books, your positions) need **no key at all**.
-
-### Polymarket — prediction markets
-
-Two different credentials, for two different things:
+Interactive API-key entry is hidden. Do not put a key directly in the command
+line, shell history, a screenshot, or Oracle chat. For controlled automation,
+pipe the secret over stdin instead of passing it as an argument:
 
 ```bash
-# 1. L2 API credentials — read your orders, post orders to the CLOB
-export POLYMARKET_API_KEY=...
-export POLYMARKET_API_SECRET=...
-export POLYMARKET_API_PASSPHRASE=...
-
-# 2. The Polygon key that actually owns the funds
-export POLYMARKET_PRIVATE_KEY=0x...
+printf '%s\n' "$OPENROUTER_API_KEY" | oracle auth api-key openrouter --stdin
 ```
 
-Derive the L2 credentials from your wallet at <https://polymarket.com> under
-API access, or via the CLOB `create-api-key` endpoint. Public market data,
-prices, and order books need **no credentials**.
+Check configuration without revealing credentials:
 
-### Everything else
+```bash
+oracle auth status
+oracle model --show
+```
 
-| Variable | Unlocks | Without it |
-|---|---|---|
-| `OPENSEA_API_KEY` | NFT collections, listings, offers | Heavily rate limited |
-| `MAGICEDEN_API_KEY` | Solana NFT buy/list/mint intents | Floor and listing reads still work |
-| `SATFLOW_API_KEY` | Bitcoin ordinals + runes marketplace | Esplora reads still work |
-| `ZEROX_API_KEY` | 0x swap routing | Other routers still quote |
-| `ONEINCH_API_KEY` | 1inch routing | Other routers still quote |
-| `UNISAT_API_KEY` | Ordinals/BRC-20 indexing | Tip and UTXOs still work |
-| `ORACLE_ROUTE_ATTESTATION_SECRET` | HMAC-signs route and slippage guards | **Required for swap sign/broadcast.** Read/quote/prepare still work. Fresh installs: `oracle-init --apply` writes one to `~/.config/oracle/exec.env`. Unsigned guards are refused at the signer boundary. |
+OAuth credentials and stored API keys use the OS credential store when
+available, with a private `0600` local fallback.
 
-Chain RPCs default to public endpoints. Override any of them:
+## 3. Open Oracle
 
 ```bash
-export ETH_RPC_URL=https://...
-export BASE_RPC_URL=https://...
-export SOLANA_RPC_URL=https://...
+oracle
 ```
 
-`/balance` and plain `balance` need only public addresses. Set any families the
-wallet uses, then start `oracle-data` from the same environment:
+Useful first commands:
 
 ```bash
-export ORACLE_EVM_ADDRESS=0x...
-export ORACLE_SOLANA_ADDRESS=...
-export ORACLE_BITCOIN_ADDRESS=bc1...
-export ORACLE_HYPERLIQUID_ADDRESS=0x...  # optional, defaults to EVM address
-npx oracle-data
+oracle chain list
+oracle chain use hyperliquid
+oracle chain show
+oracle doctor
 ```
 
-Missing address families are reported as `not-configured`, failed providers as
-`unavailable`, and unsupported chain families as `unsupported`. They are never
-reported as zero. EVM native balances cover every configured EVM chain. Solana
-adds SPL and Token-2022 accounts, Bitcoin adds Runes and inscriptions when an
-address indexer is configured, Hyperliquid adds spot and perp account state, and
-NFT inventory adds OpenSea-supported EVM/Solana collections plus Bitcoin
-inscriptions where owner indexers are available.
+Inside chat:
 
-Every `portfolio_snapshot` call appends one compact observation to
-`$HERMES_HOME/state/oracle/portfolio-history.jsonl` with mode `0600`. It stores a
-public-address fingerprint, coverage, value breakdown, and warnings, not keys,
-prepared transactions, or raw NFT metadata. Override the internal location only
-when needed:
+- `/chain` lists or selects the active chain.
+- `/model` changes the model without changing the Oracle persona.
+- `/setup` opens optional messaging setup.
 
-```bash
-export ORACLE_PORTFOLIO_HISTORY_FILE="$HOME/.local/state/oracle/portfolio-history.jsonl"
-```
+A model response is not authorization, a prepared object is not a transaction,
+and a submitted transaction is not a confirmed receipt.
+
+## Public capability boundary
 
-`portfolio_history` reads those observations. `portfolio_value_graph` returns an
-SVG chart of known priced value and omits unavailable observations instead of
-plotting them as zero.
+| Surface | Available to a public install | Custody |
+|---|---:|---|
+| Chat, research, market data | yes | none |
+| Quotes and simulations | yes | none |
+| Unsigned transaction / typed-data preparation | yes | user's wallet reviews and signs |
+| Signing, submission, broadcast | no | private owner-operated boundary only |
+| Automatic trading | no | not a public capability |
 
----
+Never paste a seed phrase, private key, hardware-wallet recovery phrase, vault
+passphrase, signer token, bot token, or provider credential into chat.
 
-## Where keys are stored
+## Optional Hermes integration
 
-**Oracle never transmits your keys anywhere except the venue they authenticate
-to.** Provider endpoints are pinned: if something redirects a provider's
-`baseUrl` to another host, the credential is dropped rather than forwarded.
-A plaintext `http://` downgrade also drops it.
+Hermes is optional. Add it only if you want specialist profiles, messaging
+channels, durable sessions, or the MCP-based local read plane:
 
-Three options, worst to best:
+```bash
+oracle bootstrap
+oracle init                 # dry run
+oracle init --apply
+oracle data serve
+oracle doctor
+```
 
-### 1. Environment variables
+`oracle bootstrap` installs an isolated Hermes compatibility runtime under
+Oracle's config directory and never modifies system Python. `oracle init
+--apply` writes profiles and a local HMAC attestation secret; it does not write a
+wallet key.
 
-Fine for a laptop. Visible in `ps`, inherited by child processes, and easy to
-leak into a shell history or a log.
+The data service binds to `127.0.0.1:8787`. Keep it on loopback.
 
-### 2. A key file
+## Optional public HTTP plane
 
 ```bash
-mkdir -p ~/.config/oracle/keys && chmod 700 ~/.config/oracle/keys
-printf '%s' "0xYOUR_KEY" > ~/.config/oracle/keys/hl.key
-chmod 600 ~/.config/oracle/keys/hl.key
-export HL_KEY_FILE=~/.config/oracle/keys/hl.key
+oracle public serve --port 8799
 ```
 
-Keeps the secret out of the process environment.
+The public plane binds to `127.0.0.1` and exposes read, connect, grant,
+portfolio, approval, prepare, Buzz-auth, and audit contracts. It has no signer,
+key, send, execute, or broadcast route.
 
-### 3. An encrypted vault (recommended)
+The service is rate limited but unauthenticated. It is **not** a Locals-holder
+gate and must not be exposed directly to the internet, LAN, or tailnet. A hosted
+deployment needs a controlled reverse proxy, TLS, edge limits, and the
+server-side holder gate described in
+[holder-beta.md](docs/holder-beta.md).
 
-Install the companion and use its CLI (not shipped in this package):
+Verify liveness only after starting it:
 
 ```bash
-npm i -g @oracle-agent/operator   # or npm i -D in your project
-oracle-vault encrypt ~/.config/oracle/keys/hl.key
-# writes  hl.key.vault.json          (scrypt N=2^17 + AES-256-GCM)
-# moves   hl.key -> hl.key.plaintext.bak
+curl -fsS http://127.0.0.1:8799/public/health
+curl -fsS http://127.0.0.1:8799/public/buzz
+```
+
+A static Oracle website does not imply that this API is running.
 
-export ORACLE_VAULT_PASSPHRASE="..."         # or be prompted
-export HL_KEY_FILE=~/.config/oracle/keys/hl.key.vault.json
+## Optional messaging
 
-# verify it unlocks, THEN destroy the plaintext backup
-oracle-vault inspect ~/.config/oracle/keys/hl.key.vault.json
-shred -u ~/.config/oracle/keys/hl.key.plaintext.bak
+```bash
+oracle setup
+oracle setup telegram --allowed-users <telegram-user-id>
+oracle setup status
+oracle setup gateway start
 ```
 
-The operator vault decrypts in memory only. The key is never written back to
-disk, never logged, and never included in any returned object.
+Interactive bot-token entry is hidden. Do not use `--token` in a normal shell;
+arguments can be retained in history or visible to other local processes. For a
+holder beta, do not run one shared messaging bot without a separate holder
+admission layer and per-user session isolation.
+
+## Public wallet addresses and portfolio reads
 
-**What the vault does and does not protect.** It defends against a key file read
-by something that is not you: a synced backup, a stolen laptop at rest, an
-overly-broad `chmod`, a leaked tarball. It does **not** defend against malware
-running as your user while the vault is unlocked. Nothing file-based does. If
-you need that, use a hardware wallet and the prepare-only path.
+Portfolio and approval reads use public addresses only:
 
 ```bash
-oracle-vault rekey <vault>     # rotate the passphrase
-oracle-vault inspect <vault>   # show KDF params, no secret
+export ORACLE_EVM_ADDRESS=0x...
+export ORACLE_SOLANA_ADDRESS=...
+export ORACLE_BITCOIN_ADDRESS=bc1...
+export ORACLE_HYPERLIQUID_ADDRESS=0x...  # optional; EVM address is the fallback
+oracle data serve
 ```
 
----
+Missing address families are reported as `not-configured`, provider failures as
+`unavailable`, and unsupported families as `unsupported`. They are never
+reported as zero. Portfolio history is stored profile-locally with mode `0600`
+and contains public-address fingerprints and value observations, not wallet
+keys or prepared transactions.
 
-## Two ways to trade
+## Preparing an action
 
-### A. Non-custodial — Oracle never sees a key
-
-Oracle prepares, your wallet signs:
+Preparation requires the real wallet that will sign. Placeholder and burn
+addresses are rejected.
 
 ```js
-import { data } from "./src/index.mjs";
+import { data } from "@oracle-agent/oracle";
 
-const order = await data.call("hl-perps", "prepareOrder", {
-  coin: "BTC", side: "buy", type: "limit", price: "60000", size: "0.01",
+const prepared = await data.call("hl-perps", "prepareOrder", {
+  /* exact market, side, size, limits, and owner wallet */
 });
-
-// order.action + order.signingReady === false
-// Hand order.action to the user's wallet. Oracle is done.
 ```
 
-### B. Owner-local execution
+Review the chain, destination, calldata or typed data, amount, minimum output,
+expiry, approvals, and fees in the user's wallet. Oracle's public package stops
+before signing. Report success only after a real transaction hash, successful
+receipt, and expected balance or state change.
 
-The public `data.call()` facade refuses `hl-exec`. Operator signing lives in
-[`@oracle-agent/operator`](https://github.com/demi-hl/oracle-operator) on your
-machine with your key. Import `hlSignAndSubmit` from that package — never from
-this one. Do not expose it on a public HTTP port.
+## Locals-only holder beta
 
-The public prepare path hard-caps slippage at 100 bps, bounds leverage by the
-asset maximum, rounds sizes and prices to venue precision, and makes brackets
-reduce-only. Any separately operated executor must enforce those controls again
-at its signing and broadcast boundaries.
+Current release status is **HOLD for a holder-gated hosted launch**. The package
+is safe to distribute for local read/research/prepare use, but this repository
+does not contain an integrated Locals ownership gate. UI hiding, a wallet text
+field, or possession of a URL is not access control.
 
----
+Do not invite holders to a hosted surface until every required gate in
+[holder-beta.md](docs/holder-beta.md) passes.
 
-## Model providers: use anything, but Hermes is better here
+## Buzz integration
 
-Oracle is a library — it does not care what drives it. Point Claude, GPT,
-Gemini, Grok, a local Llama, or your own script at it. The tools are plain
-functions and an MCP server.
+Oracle includes a public, unsigned Buzz HTTP contract. It does not embed the
+private executor and it does not turn Buzz into a custody surface. Setup,
+endpoints, and deployment status rules are documented in
+[buzz-integration.md](docs/buzz-integration.md).
+
+## Doctor output
 
 ```bash
-npx oracle-data         # local read plane on 127.0.0.1:8787
-npx oracle-data-mcp     # MCP stdio server, works with any MCP client (needs oracle-data up)
+oracle doctor --json
 ```
 
-**Why [Hermes](https://claude-code.nousresearch.com/docs) is the better host: per-profile routing.**
+A clean standalone install can legitimately show warnings for:
 
-A trading stack is not one workload, it is several with opposite requirements,
-and a single model config is wrong for all of them at once:
+- `data_server` when `oracle data serve` is not running;
+- `agent_runtime` when optional Hermes is not installed;
+- `hermes_lanes` before optional `oracle init --apply`.
 
-- **Research** — wide context, cheap, tolerant of latency. A big cheap model.
-- **Execution** — fast and deterministic. Latency is money; a slow model turns
-  a limit order into a market order.
-- **Risk review** — the strongest model available, because this is the one that
-  says no.
-- **Alerts and crons** — small and cheap, running unattended all day.
+A Node-version failure is blocking. Signing warnings are irrelevant to the
+public holder path because signing is not installed there.
 
-Hermes gives each of those its own **profile**: its own model, its own tools,
-its own memory, its own key scope. The research profile can hold no signing key
-at all. The execution profile can hold one but run a fast model. The risk
-profile can be the expensive model that reviews what the others propose.
+## Upgrade
 
-That last point is the real argument. **Different model lineages have different
-blind spots.** Oracle's own pre-release audit ran four — Grok 4.5, Opus 5,
-Fable 5, and GPT-5.6 — and each found a critical issue the others missed:
+```bash
+npm i -g @oracle-agent/oracle@latest
+oracle --version
+oracle doctor
+```
 
-- a credential leak in an HTTP dedupe cache
-- a `Number()` truncation that made a signing UI display a different amount
-  than the one being signed
-- a spending guard that authorized any amount when both limit fields were
-  omitted
-- a cap passed as a JS number above 2^53 that silently rounded **upward**
+Review release notes before upgrading a machine that also runs private
+owner-operated infrastructure.
 
-One model reviewing its own work would have shipped three of those. Per-profile
-routing is what makes running several practical instead of theoretical.
+## Uninstall
 
-Everything still works fine with a single provider. It is just better with a
-router that knows which brain to use for which job.
+```bash
+npm rm -g @oracle-agent/oracle
+```
 
-### Operator hardening (0.4+)
+The CLI does not silently delete local configuration or credentials. Remove
+those separately only after confirming they are no longer needed.
 
-Prefer the local signer daemon so the agent never sees the vault passphrase:
+## Build and test from source
 
 ```bash
-npx oracle-signer   # reads the passphrase from the OS credential store
-# agent: ORACLE_SIGNER_URL + ORACLE_SIGNER_TOKEN only
+git clone https://github.com/demi-hl/oracle.git
+cd oracle
+npm ci --no-audit --no-fund
+npm run gate:release
+npm run test:boundary
+npm test
+npm run typecheck
+npm run build
+npm run scan:secrets
 ```
 
-See [oracle-operator SETUP](https://github.com/demi-hl/oracle-operator/blob/main/SETUP.md).
+The repository may be private or ahead of npm while a release is being staged.
+The npm artifact remains the public installation source.
 
-## Local HIP-3 / HIP-4 / Polymarket (no VPS)
+## Troubleshooting
 
-### Hyperliquid HIP-3 (builder perps)
-```js
-const prep = await data.call("hl-perps", "prepareOrder", {
-  coin: "xyz:TSLA", side: "buy", type: "limit", price: "250", size: "1",
-});
-await hlSignAndSubmit(prep, { keyFile, userInitiated: true });
-// or signViaDaemon({ surface: "hl", prepared: prep, userInitiated: true })
-```
+### `oracle` says no provider is configured
 
-### Hyperliquid HIP-4 (outcomes)
-```js
-const prep = await data.call("hl-outcome", "prepareOrder", {
-  outcome: 969, side: "yes", // or coin: "#9690"
-  side: "buy", type: "limit", price: "0.42", size: "20",
-});
-await hlSignAndSubmit(prep, { keyFile, userInitiated: true });
-```
+Run `oracle auth login <provider>` or `oracle auth api-key <provider>`, then
+confirm with `oracle auth status`.
 
-### Polymarket (local CLOB)
-```js
-const prep = await data.call("poly-clob", "prepareOrder", {
-  tokenId, side: "BUY", price: 0.45, size: 10,
-  maker: eoa, signer: eoa, tickSize: "0.01",
-});
-// signer process needs POLYMARKET_API_KEY/SECRET/PASSPHRASE + key
-await polySignAndSubmit(prep, { keyFile, userInitiated: true });
-// or signViaDaemon({ surface: "poly", prepared: prep, userInitiated: true })
-```
+### `oracle setup` says the local runtime is missing
 
-## Protocol templates (builder)
+Messaging uses optional Hermes. Run `oracle bootstrap`, then retry setup.
+Standalone chat, chain selection, and public read/prepare commands do not require
+Hermes.
 
-Gated Foundry templates under `protocols/templates/`.
+### `oracle doctor` says the data server is down
 
-```bash
-# requires Foundry (forge)
-cd protocols/templates/safe-erc20 && forge install && forge test
-npm run protocol:gate -- safe-erc20
-```
+Start it in another terminal with `oracle data serve`. Do not expose port `8787`
+off-host.
 
-`prepareTemplateDeploy` will not stamp an unsigned deploy unless `forge test` passes.
-**Not a paid security-firm audit** — see each template `SECURITY.md`.
+### The public API or Buzz endpoint is unreachable
 
+Start `oracle public serve --port 8799` and verify `/public/health`. Do not claim
+the API is live based on the static site or source code alone.
 
-## Optional keyed prepare stamps (hardening)
+### A prepared action cannot be signed
 
-Integrity hash is always on. For a shared HMAC between prepare process and signer:
+That is expected in the public package. Hand the reviewed artifact to a
+user-controlled wallet. Do not install or request private owner infrastructure
+as a workaround.
 
-```bash
-# same secret on prepare host and signer host (not in the agent chat)
-export ORACLE_STAMP_HMAC_SECRET='long-random-secret'
-# signer-only: refuse envelopes without MAC
-export ORACLE_STAMP_REQUIRE_MAC=1
-```
+## References
 
-Default remains hash-only (public GO path). HMAC is opt-in hardening.
+- [CLI reference](docs/cli.md)
+- [Public API and environment surface](docs/public-surface.md)
+- [Locals-holder beta launch gate](docs/holder-beta.md)
+- [Buzz integration](docs/buzz-integration.md)
+- [Architecture](docs/architecture.md)
+- [Security policy](SECURITY.md)

package/dist/action-receipts.mjs

@@ -0,0 +1 @@
+import{createHash as m}from"node:crypto";import{wordlists as g}from"ethers";var A=1,E=new Set(["privatekey","privkey","secretkey","seedphrase","seed","mnemonic","passphrase","password","keystore","keymaterial","wif","xprv","xpriv","bearer","authorization","signature","apikey","credential"]),x=[/\b[5KL][1-9A-HJ-NP-Za-km-z]{50,51}\b/,/\bxprv[0-9A-Za-z]{50,}\b/],$=new Set([12,15,18,21,24]);function S(e){let t=String(e).trim().toLowerCase().split(/\s+/).filter(Boolean);return $.has(t.length)&&t.every(r=>g.en.getWordIndex(r)>=0)}var H=/^\s*(?:0x)?[0-9a-fA-F]{64}\s*$/,O=/(hash|digest|root|salt|nonce|proof|commitment|sig|id)(?:e?s)?$/i,j=new Set(["calldata","data","publickey","pubkey","message","payload","input","extradata"]);function T(e){let t=b(e);return j.has(t)||O.test(t)}var f=class extends Error{constructor(t){super(`action receipt refused: secret-bearing field at ${t}`),this.name="ActionReceiptSecretError",this.code="ACTION_RECEIPT_SECRET"}};function b(e){return String(e).replace(/[^a-z0-9]/gi,"").toLowerCase()}function C(e){let t=b(e);return[...E].some(r=>t.includes(r))}function _(e,t,r){if(typeof t=="string"){if(x.some(o=>o.test(t))||S(t))throw new f(r);if(H.test(t)&&!T(e))throw new f(r)}}function a(e,t="$",r=""){if(e==null||typeof e=="boolean")return e;if(typeof e=="string")return _(r,e,t),e;if(typeof e=="number"){if(!Number.isFinite(e))throw new TypeError(`action receipt: non-finite number at ${t}`);return e}if(typeof e=="bigint")return e.toString();if(Array.isArray(e))return e.map((n,i)=>a(n,`${t}[${i}]`,r));if(typeof e!="object"||Object.getPrototypeOf(e)!==Object.prototype)throw new TypeError(`action receipt: JSON-like value required at ${t}`);let o={};for(let n of Object.keys(e).sort()){let i=`${t}.${n}`;if(C(n))throw new f(i);e[n]!==void 0&&(o[n]=a(e[n],i,n))}return o}function L(e){return a(e)}function d(e){return e===null||typeof e!="object"?JSON.stringify(e):Array.isArray(e)?`[${e.map(d).join(",")}]`:`{${Object.keys(e).map(t=>`${JSON.stringify(t)}:${d(e[t])}`).join(",")}}`}function R(e){return d(a(e))}function k(e){if(!e||typeof e!="object"||Array.isArray(e))throw new TypeError("action receipt: object required");let{receiptId:t,summary:r,...o}=e;return m("sha256").update(R(o)).digest("hex")}function c(e,...t){for(let r of t)if(e[r]!==void 0)return e[r]}function s(e,t,r){let o=c(e,...t);if(o==null)throw new TypeError(`action receipt: ${r} required`);return o}function I(e){let t=c(e,"balances","balanceChanges"),r=c(e,"beforeBalances","balancesBefore","before"),o=c(e,"afterBalances","balancesAfter","after");return t!==void 0?{balances:t}:r===void 0&&o===void 0?{}:{balances:{...r===void 0?{}:{before:r},...o===void 0?{}:{after:o}}}}function N(e={}){if(!e||typeof e!="object"||Array.isArray(e))throw new TypeError("action receipt: input object required");a(e);let t=c(e,"txHash","transactionHash"),r=c(e,"phase","stage","resultType")??(t==null?"prepare":"execute");if(r!=="prepare"&&r!=="execute")throw new TypeError('action receipt: phase must be "prepare" or "execute"');let o={receiptVersion:A,phase:r,intent:s(e,["intent"],"intent"),route:s(e,["route"],"route"),decodedAction:s(e,["decodedAction","action"],"decodedAction"),policyChecks:s(e,["policyChecks","checks"],"policyChecks"),allowlistHits:s(e,["allowlistHits","allowlistMatches"],"allowlistHits"),prepareHash:s(e,["prepareHash"],"prepareHash"),...t==null?{}:{txHash:t},...I(e)},n=a(o);return Object.freeze({...n,receiptId:k(n)})}var q=N;function u(e,t=[]){if(typeof e=="string"||typeof e=="number")return String(e);for(let r of t)if(e?.[r]!=null)return String(e[r]);return"recorded"}function y(e){if(typeof e=="boolean")return e;if(e&&typeof e=="object"){if(typeof e.ok=="boolean")return e.ok;if(typeof e.allowed=="boolean")return e.allowed;if(typeof e.passed=="boolean")return e.passed}return null}function z(e){if(!e||typeof e!="object")throw new TypeError("action receipt: object required");let t=u(e.decodedAction,["type","action","method","name"]),r=u(e.route,["name","provider","venue","id"]),o=Array.isArray(e.policyChecks)?e.policyChecks:Object.values(e.policyChecks||{}),n=o.filter(l=>y(l)===!0).length,i=o.filter(l=>y(l)===!1).length,p=Array.isArray(e.allowlistHits)?e.allowlistHits.length:Object.keys(e.allowlistHits||{}).length,h=e.txHash==null?"no transaction hash":`tx ${e.txHash}`,w=e.balances==null?"balances not provided":"before/after balances recorded";return`${e.phase} ${t} via ${r}; policy ${n} passed, ${i} failed; ${p} allowlist hit${p===1?"":"s"}; ${h}; ${w}; receipt ${e.receiptId}`}var F=z;export{A as ACTION_RECEIPT_VERSION,f as ActionReceiptSecretError,L as assertNoReceiptSecrets,R as canonicalReceiptJson,k as computeReceiptId,q as createActionReceipt,F as formatActionReceipt,N as normalizeActionReceipt,z as summarizeActionReceipt};

package/dist/action-semantics.mjs

@@ -0,0 +1 @@
+var o=Object.freeze({ALERT_ONLY:"alert_only",EXECUTE:"execute"}),i=new Set(["watch","watch this","ping","ping me","alert","notify"]),r=new Set(["watching","armed"]);function a(t){if(typeof t!="string"||!t.trim())throw new TypeError("explicit action verb required");let e=t.trim().toLowerCase().replace(/\s+/g," ");if(i.has(e))return o.ALERT_ONLY;if(e==="arm")return o.EXECUTE;throw new TypeError(`unsupported action verb: ${e}`)}function c(t={}){let{verb:e,...n}=t;return{...n,active:!0,actionMode:a(e)}}function u(t){if(!t||typeof t!="object"||typeof t.active!="boolean")throw new TypeError("active must be boolean");if(!Object.values(o).includes(t.actionMode))throw new TypeError("actionMode must be alert_only or execute");return t}function E(t){return t?.active===!0&&t?.actionMode===o.ALERT_ONLY}function s(t){return t?.active===!0&&t?.actionMode===o.EXECUTE}function p(t={}){if(t.actionMode!==void 0&&t.actionMode!==o.ALERT_ONLY)throw new TypeError("non-alert record cannot enter alert-only watch migration");let e=typeof t.active=="boolean"?t.active:r.has(String(t.status||"").toLowerCase());return{...t,active:e,actionMode:o.ALERT_ONLY}}export{o as ACTION_MODES,a as actionModeForVerb,u as assertActionRecord,c as createActionRecord,E as isActiveAlert,s as isActiveExecution,p as migrateLegacyWatchRecord};

package/dist/address-book.mjs

@@ -0,0 +1,2 @@
+import c from"node:fs";import d from"node:path";import{homedir as b}from"node:os";import{join as h}from"node:path";var w=h(b(),".config","oracle"),z=h(b(),".config","mad-desk");function m(e,r,t=""){let o=process.env[e];if(o!=null&&String(o).trim()!=="")return o;let n=r?process.env[r]:void 0;return n!=null&&String(n).trim()!==""?n:t}var g=/^0x[0-9a-fA-F]{40}$/,_=new Set(["privatekey","private_key","secret","seed","mnemonic","passphrase","signature","keystore"]),D=["privatekey","privkey","secretkey","secret","seedphrase","seed","mnemonic","passphrase","password","keystore","keymaterial","signature","wif","xprv","xpriv","apikey","bearer","credential"],O=[/\b[5KL][1-9A-HJ-NP-Za-km-z]{50,51}\b/,/\bxprv[0-9A-Za-z]{50,}\b/,/\b(?:[a-z]{3,8}\s+){11,}[a-z]{3,8}\b/i],y=/^\s*(?:0x)?[0-9a-fA-F]{64}\s*$/;function I(e){return String(e).toLowerCase().replace(/[^a-z0-9]/g,"")}function L(e,r){let t=I(e);if(_.has(String(e).toLowerCase())||D.some(o=>t.includes(o)))throw new Error(`address-book: ${r} is forbidden; the book stores labels, never key material`)}function N(e,r){if(typeof e=="string"&&(O.some(t=>t.test(e))||y.test(e)))throw new Error(`address-book: ${r} looks like key material; the book stores labels, never key material`)}function E(){let e=m("ORACLE_ADDRESS_BOOK","MAD_ADDRESS_BOOK","");if(e)return d.resolve(e);let r=m("ORACLE_CONFIG_DIR","MAD_CONFIG_DIR",w);return d.join(r,"address-book.json")}function p(e,r="field"){if(Array.isArray(e)){e.forEach((t,o)=>p(t,`${r}[${o}]`));return}if(!e||typeof e!="object"){N(e,r);return}for(let[t,o]of Object.entries(e))L(t,t),p(o,t)}function S(e){let r=String(e||"").trim();if(!g.test(r))throw new Error("address-book: address must be 0x + 40 hex characters");return r.toLowerCase()}function a(e,r){return e==null||e===""?null:String(e).slice(0,r)}function k(){return{version:1,updatedAt:null,entries:[]}}function x(e){return{address:String(e.address).toLowerCase(),label:a(e.label,80)||"unknown",who:a(e.who,120),role:a(e.role,40),chainIds:Array.isArray(e.chainIds)?e.chainIds.map(Number).filter(Number.isFinite):[],notes:a(e.notes,500),source:a(e.source,80),firstSeenAt:e.firstSeenAt||null,lastSeenAt:e.lastSeenAt||null}}function l(){try{let e=JSON.parse(c.readFileSync(E(),"utf8"));if(!e||typeof e!="object")return k();let r=Array.isArray(e.entries)?e.entries:[];return{version:1,updatedAt:e.updatedAt||null,entries:r.filter(t=>t&&typeof t=="object"&&g.test(String(t.address||""))).map(x)}}catch{return k()}}function v(e){let r=E();c.mkdirSync(d.dirname(r),{recursive:!0,mode:448});let t={...e,version:1,updatedAt:new Date().toISOString()},o=d.join(d.dirname(r),`.address-book.${process.pid}.tmp`);c.writeFileSync(o,`${JSON.stringify(t,null,2)}
+`,{mode:384}),c.renameSync(o,r);try{c.chmodSync(r,384)}catch{}return t}function G(e={}){let r=l(),t=r.entries;if(e.role&&(t=t.filter(o=>o.role===String(e.role))),e.who){let o=String(e.who).toLowerCase();t=t.filter(n=>(n.who||"").toLowerCase().includes(o)||(n.label||"").toLowerCase().includes(o))}if(e.q){let o=String(e.q).toLowerCase();t=t.filter(n=>n.address.includes(o)||(n.label||"").toLowerCase().includes(o)||(n.who||"").toLowerCase().includes(o)||(n.notes||"").toLowerCase().includes(o))}return{updatedAt:r.updatedAt,count:t.length,entries:t}}function P(e){let r=S(e),t=l().entries.filter(o=>o.address===r);return{address:r,found:t.length>0,entries:t}}function q(e={}){p(e);let r=S(e.address),t=a(e.label??e.role,80)||"wallet",o=new Date().toISOString(),n=l(),i=n.entries.findIndex(s=>s.address===r&&s.label===t),u=x({address:r,label:t,who:e.who,role:e.role,chainIds:e.chainIds,notes:e.notes,source:e.source||"agent",firstSeenAt:i>=0&&n.entries[i].firstSeenAt||o,lastSeenAt:o});i>=0?n.entries[i]=u:n.entries.push(u);let A=s=>s==="agent"?0:s==="owner"?1:2;n.entries.sort((s,f)=>A(s.role)-A(f.role)||s.label.localeCompare(f.label)||s.address.localeCompare(f.address));let C=v(n);return{ok:!0,entry:u,count:C.entries.length}}function Y(e,r=null){let t=S(e),o=l(),n=o.entries.length;return o.entries=o.entries.filter(i=>i.address!==t?!0:r==null?!1:i.label!==String(r)),v(o),{ok:!0,removed:n-o.entries.length,count:o.entries.length}}export{E as addressBookPath,Y as forgetAddress,G as listAddresses,P as lookupAddress,l as readAddressBook,q as rememberAddress};