@oracle-agent/oracle 0.23.1 → 0.24.0

package/README.md

@@ -45,10 +45,13 @@ Oracle can run standalone model auth directly with API keys or Claude, Codex,
 and Grok OAuth. OAuth credentials use the OS keychain when available, with a
 private `0600` local fallback when keychain storage is unavailable.
 
-This package is **prepare-only**: it never takes a private key and never
-broadcasts. The owner-operated signer/executor is private infrastructure, is
-not published on npm, and is not part of public onboarding. Never paste a seed,
-private key, vault passphrase, or signer token into Oracle chat.
+Oracle is **prepare-only by default and on hosted surfaces**. A self-hoster may
+explicitly initialize the optional encrypted local vault and run a short-lived,
+loopback-only signer. Every normal action requires exact one-use human
+confirmation and policy checks; autonomous trading additionally requires
+`ORACLE_AUTONOMOUS_TRADING=1`. Never paste a seed, key, passphrase, or signer
+token into Oracle chat or argv. The private `@oracle-agent/agent` admin package
+remains separate and is not included here.
 
 ---
 
@@ -203,7 +206,7 @@ known answer. This matters: the canonical QuoterV2 address also has bytecode on
 Base, but does not price that chain's pairs. A codesize check would have
 allowlisted the wrong contract.
 
-**72 provider modules** in the read/quote catalog, covering **219 unique
+**73 provider modules** in the read/quote catalog, covering **219 unique
 protocols/venues** across EVM, Solana, and Bitcoin (115 EVM + cross-chain, 98
 Solana venues backed by 101 verified Jupiter program IDs, 6 Bitcoin surfaces).
 One module can cover many protocols: the Jupiter module alone routes 98 Solana
@@ -389,20 +392,20 @@ oracle chain use hyperliquid
 oracle setup           # telegram / discord / slack messaging
 ```
 
-Terminal and configured messaging channels are transports into the same Hermes
-`oracle` profile. Both interfaces are read/prepare-only in this package. They
-can return the same unsigned artifact for review, but neither can discover or
-invoke a signer, vault, control MCP, or broadcaster. Signing stays in the user
-wallet or separately installed private owner infrastructure.
+Terminal and configured messaging channels are untrusted proposers into the
+same Hermes `oracle` profile. They cannot self-confirm or directly invoke the
+optional signer. Signing stays in the user wallet or in the explicitly enabled,
+loopback-only public local signer after independent local confirmation and
+sealed-policy checks. Private Administrator execution remains separate.
 
 Lanes: `oracle` (router), `polymarket-agent`, `hyperliquid-agent`,
 `robinhood-agent`, `solana-agent`, `bitcoin-agent`, `stable-agent`,
 `protocol-builder`, plus `_template` for your own. Details in
 [`docs/profiles.md`](docs/profiles.md).
 
-Every lane installs **DISARMED**. No lane requests a broadcast or signing action —
-only read, simulate, and prepare — and a test enforces that so widening custody
-can't pass review quietly. An existing `SOUL.md` is never overwritten without
+Every model lane remains unable to authorize signing. It may only read,
+simulate, and prepare; local key initialization arms user-initiated actions,
+while Disarm is globally dominant. An existing `SOUL.md` is never overwritten without
 `--force`, and `--force` writes a timestamped backup first.
 
 Oracle does not issue its own model credential. Standalone chat uses the OAuth

package/SECURITY.md

@@ -44,9 +44,9 @@ model is treated as an untrusted proposer.
 
 Consequences of that assumption, which are the invariants worth attacking:
 
-1. **The public package never holds a key.** Signing happens in the user's
-   wallet. Source-only operator modules are excluded from public entrypoints and
-   the npm artifact.
+1. **Hosted/default operation never holds a key.** An explicit self-host setup
+   may hold one only in the encrypted local vault. Private Administrator modules
+   are excluded from public entrypoints and the npm artifact.
 2. **Model output is not authorization.** A grant is authorization, and a grant
    is signed by the owner, scoped, and expiring.
 3. **Destinations are allowlisted per chain and fail closed.** An empty allowlist
@@ -77,11 +77,12 @@ A security claim that isn't enforced by a test is just a comment.
 These are not public-package custody holes. They are operator constraints that
 still apply after the public boundary hardening:
 
-1. **Owner-local signer modules live in private operator infrastructure.** The
-   operator package is not published on npm and is not part of public or holder
-   onboarding. Those modules and credentials must not be restored into this
-   prepare-only package or its npm artifact. CI fails if a pack of *this* repo
-   includes signer or vault paths.
+1. **Public self-host custody is local and explicit.** The optional signer uses
+   an scrypt/AES-GCM encrypted local vault and short-lived loopback daemon.
+   Hosted/default operation remains prepare-only. This cannot protect against
+   malware in an unlocked signer process; use hardware custody for that threat.
+   The private `@oracle-agent/agent` admin package remains separate and must not
+   appear in this package or its publish artifact.
 2. **Prepare helpers that validate executable routes require an attestation
    secret** (`requireSigned`) so they cannot be used as a softer pre-broadcast
    gate than `enforceTxPolicy`.

package/SETUP.md

@@ -1,18 +1,45 @@
 # Oracle setup
 
-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.
-
-The owner-operated signer/executor is private infrastructure. It is not published
-on npm and is not part of public onboarding.
+Oracle's public CLI is prepare-only unless a user deliberately enables its
+self-hosted signer. The optional signer uses an AES-256-GCM/scrypt encrypted
+vault on the user's machine, listens only on loopback, and signs only exact
+confirmed artifacts within configured policy. Hosted Oracle remains
+prepare-only. The private `@oracle-agent/agent` admin package is not imported.
 
 ## Requirements
 
 - 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
+- A user-controlled wallet, external or in the optional encrypted local vault
+
+## Local self-hosted signer
+
+Never paste a key or passphrase into Oracle, chat, or argv. Use a hidden TTY or
+owner-only (`0600`) files:
+
+```bash
+oracle sign init
+oracle sign import --key-file /protected/key --passphrase-file /protected/passphrase
+oracle sign policy --policy-file /protected/policy.json
+oracle sign doctor
+oracle signer --credential-service oracle-local-signer --session-seconds 120
+# protected-file fallback, and the required Windows behavior:
+oracle signer --passphrase-file /protected/passphrase --session-seconds 120
+oracle sign lock
+```
+
+Configure and HMAC-seal `~/.config/oracle/signer/signer-policy.json` with non-empty surface, action, chain,
+destination, selector, spender, and owner allowlists plus explicit value,
+approval, gas/fee, slippage, expiry, and RPC bounds. Empty allowlists fail
+closed. Exact one-use confirmation binds the final gas-populated artifact, which
+is checked again immediately before broadcast. Lock/disarm always wins.
+
+Service templates ship under `public/service/` for Linux systemd, macOS
+launchd, and Windows Task Scheduler/PowerShell. Linux/macOS can retrieve the
+passphrase from the logged-in user's keyring; Windows currently requires an
+ACL-protected file. Installation is deliberately not automatic. Never put a
+passphrase in service argv or an inherited environment.
 
 Linux, Windows, and macOS apps are in beta.
 
@@ -113,8 +140,8 @@ and a submitted transaction is not a confirmed receipt.
 | 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 |
+| Signing, submission, broadcast | optional self-host only | encrypted local vault, sealed policy, exact local confirmation |
+| Automatic trading | explicit self-host only | exact env `1`, autonomous policy mode, and verified trigger attestation |
 
 Never paste a seed phrase, private key, hardware-wallet recovery phrase, vault
 passphrase, signer token, bot token, or provider credential into chat.