Merge pull request #8 from ProjectOpenSea/hardening/wallet-policy-and-autoprovision

Harden Privy wallet model + auto-provision secrets via Pinata Platform skill

Author: ryanio

.github/workflows/validate.yml

@@ -37,9 +37,12 @@ jobs:
           jq -e '.template.tags | type == "array" and length > 0 and length <= 10' manifest.json > /dev/null
           jq -e '.template.authorName | type == "string"' manifest.json > /dev/null
 
-          # Skills shape — every entry needs clawhub_slug + name
-          jq -e 'all(.skills[]; .clawhub_slug | type == "string" and test("^[a-z0-9-]+$"))' manifest.json > /dev/null
+          # Skills shape — every entry needs `name` plus EITHER `clawhub_slug` (resolves to latest published version) OR `cid` (pinned).
           jq -e 'all(.skills[]; .name | type == "string" and length > 0)' manifest.json > /dev/null
+          jq -e 'all(.skills[];
+            ((.clawhub_slug // "") | test("^[a-z0-9-]+$"))
+            or ((.cid // "") | type == "string" and length >= 46)
+          )' manifest.json > /dev/null
 
           # Scripts shape — build is required (start is optional)
           jq -e '.scripts.build | type == "string" and length > 0' manifest.json > /dev/null
@@ -49,12 +52,22 @@ jobs:
           jq -e 'all(.secrets[]; .name | type == "string" and test("^[A-Z][A-Z0-9_]*$"))' manifest.json > /dev/null
           jq -e 'all(.secrets[]; .description | type == "string" and length > 0)' manifest.json > /dev/null
 
-          # All four required env vars must be declared so Pinata prompts for them at deploy time
-          for v in OPENSEA_API_KEY PRIVY_APP_ID PRIVY_APP_SECRET PRIVY_WALLET_ID; do
+          # Required secrets — only the irreducible ones. The agent auto-provisions the rest at bootstrap
+          # (OPENSEA_API_KEY via the OpenSea instant-key endpoint; PRIVY_WALLET_ID via `opensea wallet create`;
+          # PRIVY_AUTH_SIGNING_KEY via `opensea wallet generate-auth-key`), then attaches them via the bundled
+          # @pinata/platform skill. App credentials still have to come from the user.
+          for v in PRIVY_APP_ID PRIVY_APP_SECRET; do
             jq -e --arg v "$v" 'any(.secrets[]; .name == $v and .required == true)' manifest.json > /dev/null \
               || { echo "missing required secret: $v"; exit 1; }
           done
 
+          # Auto-provisioned secrets must be declared (with required: false) so Pinata renders the field
+          # in the env UI for users who want to override the auto-provisioned default.
+          for v in OPENSEA_API_KEY PRIVY_WALLET_ID PRIVY_AUTH_SIGNING_KEY; do
+            jq -e --arg v "$v" 'any(.secrets[]; .name == $v)' manifest.json > /dev/null \
+              || { echo "missing optional secret declaration: $v"; exit 1; }
+          done
+
           echo "manifest.json OK"
 
       - name: Validate .openclaw/openclaw.json

README.md

@@ -1,6 +1,6 @@
 # NFT Collector Copilot
 
-An AI agent for NFT collectors. Watches [OpenSea](https://opensea.io), scores every listing across five signals (price, volume, depth, holders, momentum), and executes Seaport trades through a [Privy](https://privy.io) server wallet with a TEE-enforced spend cap. You approve; it acts.
+An AI agent for NFT collectors. Watches [OpenSea](https://opensea.io), scores every listing across five signals (price, volume, depth, holders, momentum), and executes Seaport trades through a [Privy](https://privy.io) server wallet with a TEE-enforced per-tx cap and an off-machine owner key the agent cannot reach. You approve; it acts. The wallet's float is your real aggregate ceiling — you fund and replenish it on your own cadence.
 
 ## The killer feature: **Whale-Cross Alerts**
 
@@ -14,7 +14,7 @@ Point it at a list of wallets you respect (vitalik.eth, your favorite PFP whale,
 - **Seaport buys + sells** via `@opensea/cli` + the skill's fulfillment scripts, signed by your Privy wallet.
 - **Drop Radar** — upcoming/featured drops cross-referenced against your taste model.
 - **Taste learning** — every buy/pass/ask updates a structured `taste.json` so recommendations get sharper over time.
-- **Spend-cap safety.** The Privy policy is the real enforcement — the agent literally cannot overspend.
+- **Spend-cap safety.** Per-tx cap enforced in Privy's TEE; owner key off-machine so the agent can't rewrite the policy; aggregate spend bounded by the wallet float you fund. Three independent layers — one in the user's hands, two in Privy's, none the agent can lift.
 
 Supported chains: see `workspace/TOOLS.md`. Mainnets only by default.
 
@@ -25,25 +25,33 @@ Supported chains: see `workspace/TOOLS.md`. Mainnets only by default.
 
 ## Secrets you'll need
 
-Paste these into Pinata's environment UI at deploy time:
+Only two are required up front. The rest the agent provisions for you on first run.
 
 | Variable | Required | How to get it |
 |---|---|---|
-| `OPENSEA_API_KEY` | yes | `curl -s -X POST https://api.opensea.io/api/v2/auth/keys \| jq -r .api_key` — no signup |
-| `PRIVY_APP_ID` | yes | [dashboard.privy.io](https://dashboard.privy.io) → create app |
-| `PRIVY_APP_SECRET` | yes | Same page as App ID |
-| `PRIVY_WALLET_ID` | yes | Create a server wallet — see `skills/opensea/references/wallet-setup.md` → *Privy* |
+| `PRIVY_APP_ID` | **yes** | [dashboard.privy.io](https://dashboard.privy.io) → create app |
+| `PRIVY_APP_SECRET` | **yes** | Same page as App ID. Pair with an `owner_id` registered on the wallet — bootstrap walks you through it. |
+| `OPENSEA_API_KEY` | optional | If unset, the agent fetches a free-tier instant key on first run and attaches it via the bundled Pinata Platform skill. Provide your own paid key here only if you need higher rate limits. |
+| `PRIVY_WALLET_ID` | optional | If unset, the agent creates a new server wallet via `opensea wallet create` once Privy app creds are present. Provide one only to reuse an existing wallet. |
+| `PRIVY_AUTH_SIGNING_KEY` | optional | Auto-generated by the agent on first run via `opensea wallet generate-auth-key`. The matching public key gets registered as the wallet's `additional_signer`; the owner key stays off-machine on your host. |
 
-Full walkthrough: `skills/opensea/references/wallet-setup.md`. Policy templates: `skills/opensea/references/wallet-policies.md`.
+Full walkthrough: `skills/opensea/references/wallet-setup.md`. Policy templates: `skills/opensea/references/wallet-policies.md`. Hot-wallet float pattern: `skills/opensea/references/wallet-funding.md`. User-only mutation recipes (policy attachment, owner registration): https://github.com/ProjectOpenSea/opensea-skill/blob/main/docs/policy-administration.md.
 
 ## 60-second setup
 
-1. **Grab an OpenSea API key** — run the curl above.
-2. **Create a Privy app** at [dashboard.privy.io](https://dashboard.privy.io); copy App ID + App Secret.
-3. **Create a server wallet** following `skills/opensea/references/wallet-setup.md` → *Privy* → step 2. Save `id` as `PRIVY_WALLET_ID`.
-4. **Attach a spend policy** — the agent will walk you through this on first run using the "Agent Trading — Conservative" template from `skills/opensea/references/wallet-policies.md`. Start tight.
-5. **Fund the wallet** on whichever chains you plan to trade on.
-6. **Deploy** — paste all four env vars into Pinata, then chat.
+1. **Create a Privy app** at [dashboard.privy.io](https://dashboard.privy.io); copy App ID + App Secret. Paste both into Pinata's env UI.
+2. **Deploy.** That's the entire required setup.
+
+On first conversation the agent will walk you through:
+
+- Fetching an OpenSea API key and attaching it (free-tier instant key, no signup).
+- Creating your Privy server wallet (`opensea wallet create`) and storing the ID.
+- Generating its own additional_signer keypair and storing the private half as `PRIVY_AUTH_SIGNING_KEY`.
+- An off-machine ceremony you do on your own host: generate an owner keypair, then register both your owner public key (as `owner_id`) and the agent's additional_signer public key on the wallet via https://github.com/ProjectOpenSea/opensea-skill/blob/main/docs/policy-administration.md. Your owner private key never touches the agent.
+- Choosing and attaching a per-tx policy (Agent Trading — Conservative is the default template).
+- Funding the agent wallet to a hot-wallet float you set per chain.
+
+Each step that needs new secrets ends with a Pinata restart, after which the agent resumes from where you left off. BOOTSTRAP is a resumable state machine — cold restarts pick up at the first incomplete phase.
 
 ## Example prompts
 
@@ -63,12 +71,19 @@ Full walkthrough: `skills/opensea/references/wallet-setup.md`. Policy templates:
 
 ## Safety model
 
-- **Env-only credentials.** No private keys in the repo or agent workspace.
-- **Privy policy is the hard ceiling.** The spend cap, destination allowlist, and chain filter are enforced inside a TEE before signing.
-- **Per-turn confirmation for material actions.** Any buy, offer acceptance, approval, or transfer above `confirmAboveEth` (in `workspace/TOOLS.md`) needs explicit "yes" in the current turn. Snipes can bypass this only when the listing is fully inside your configured envelope — see `workspace/SOUL.md` → *Hierarchy of Ceilings*.
+Three independent layers, in order of how the bound is actually enforced:
+
+1. **Wallet float** — the **real aggregate ceiling**. The agent doesn't hold a key to a treasury; it can only spend what's in the agent wallet. You fund it from your own cold/funding wallet to ≈ a day or week of intended budget and replenish on your cadence. Privy can't enforce daily/weekly cumulative limits, so wallet balance is what stops a runaway spend.
+2. **Privy per-tx policy (TEE-enforced)** — caps each individual transaction. Conditional on `owner_id` being registered: the agent's env credentials cannot rewrite the policy because mutations require an authorization signature from the owner key (which lives on your host, not the agent's). Bootstrap verifies this is in place before any signing-capable step.
+3. **Per-turn confirmation** for material actions. Any buy, offer acceptance, approval, or transfer above `confirmAboveEth` (in `workspace/TOOLS.md`) needs explicit "yes" in the current turn. Snipes can bypass this only when the listing is fully inside your configured envelope — see `workspace/SOUL.md` → *Hierarchy of Ceilings*.
+
+Other invariants:
+
+- **Env-only credentials.** No private keys in the repo or agent workspace. The owner key never touches the agent host.
 - **Sell-side always confirms.** Privy's native-value cap is denominated in the chain's native token (ETH, etc.) — it does **not** apply to WETH transfers, which is how Seaport offer acceptances pay out. Sells, offer acceptances, and ERC721/1155 approvals therefore always require per-turn confirmation, regardless of price.
-- **Pre-Buy Gate.** Wash trades, thin markets, uneconomic gas, and fee surprises all block a buy before it's proposed.
+- **Pre-Buy Gate.** Wash trades, thin markets, uneconomic gas, fee surprises, and float exhaustion all block a buy before it's proposed.
 - **Policy rejections surface verbatim.** No workarounds.
+- **Forbidden operations.** The agent will refuse to call any Privy admin endpoint (policy mutation, owner key rotation, auth key changes) — even if you ask. To change the cap or the policy, do it yourself on your machine via https://github.com/ProjectOpenSea/opensea-skill/blob/main/docs/policy-administration.md.
 
 ## Repository layout
 

manifest.json

@@ -3,7 +3,7 @@
   "version": 1,
   "agent": {
     "name": "NFT Collector Copilot",
-    "description": "A discerning collector assistant. Watches your favorite OpenSea collections, tracks floor and volume moves, and — when you say so — buys listings through a Privy server wallet whose spend-cap is enforced in a TEE.",
+    "description": "A discerning collector assistant. Watches your favorite OpenSea collections, tracks floor and volume moves, and — when you say so — buys listings through a Privy server wallet whose spend cap is enforced in a TEE. Hardened by default: bootstrap walks you through registering an off-machine owner key so the agent's env credentials cannot rewrite the policy that constrains them.",
     "vibe": "calm, numerate, protective of your ETH",
     "emoji": "⛵"
   },
@@ -16,13 +16,14 @@
     "authorLogoUrl": "https://static.seadn.io/logos/Logomark-Blue.png"
   },
   "skills": [
-    { "clawhub_slug": "opensea-marketplace", "name": "OpenSea" }
+    { "clawhub_slug": "opensea-marketplace", "name": "OpenSea" },
+    { "cid": "bafybeicglyjdb6wrrcbfyu6i2fe4lpxdxgvfvlht7yzdim7cvwt656whue", "name": "@pinata/platform" }
   ],
   "secrets": [
     {
       "name": "OPENSEA_API_KEY",
-      "description": "OpenSea API key — used for all reads, fulfillment, and swaps. Get one instantly with: curl -s -X POST https://api.opensea.io/api/v2/auth/keys | jq -r .api_key",
-      "required": true
+      "description": "OpenSea API key. Optional — if not set, the agent will fetch a free-tier instant key on first run via curl -X POST https://api.opensea.io/api/v2/auth/keys and attach it via the Pinata Platform skill. Provide your own paid key here if you need higher rate limits.",
+      "required": false
     },
     {
       "name": "PRIVY_APP_ID",
@@ -31,13 +32,18 @@
     },
     {
       "name": "PRIVY_APP_SECRET",
-      "description": "Privy application secret — same dashboard page as the App ID. Treat as a password.",
+      "description": "Privy application secret — same dashboard page as the App ID. Treat as a password. IMPORTANT: pair this with an owner_id registered on the wallet — without it, this secret can rewrite the wallet's policy unilaterally. Bootstrap walks you through the hardening (see https://github.com/ProjectOpenSea/opensea-skill/blob/main/docs/policy-administration.md).",
       "required": true
     },
     {
       "name": "PRIVY_WALLET_ID",
-      "description": "Privy server wallet ID. Create a server wallet (see skills/opensea/references/wallet-setup.md) and paste its id here.",
-      "required": true
+      "description": "Privy server wallet ID. Optional — if not set, the agent will create a new server wallet via `opensea wallet create` once PRIVY_APP_ID + PRIVY_APP_SECRET are present and attach the ID via the Pinata Platform skill. Set this only to reuse an existing wallet.",
+      "required": false
+    },
+    {
+      "name": "PRIVY_AUTH_SIGNING_KEY",
+      "description": "Privy additional_signer private key (PKCS8 base64, P-256). Optional — auto-generated on first run via `opensea wallet generate-auth-key` and attached via the Pinata Platform skill. Required for /rpc signing once owner_id is registered on the wallet. The matching public key is what gets registered as additional_signer; the owner key stays off-machine on your own host. See https://github.com/ProjectOpenSea/opensea-skill/blob/main/docs/policy-administration.md.",
+      "required": false
     }
   ],
   "scripts": {

workspace/AGENTS.md

@@ -85,6 +85,9 @@ Free-text long-form observations that don't fit a schema: API quirks, volatile s
 
 - Never push directly to `main` — use feature branches + PRs for any *template* code changes.
 - Don't run destructive commands without confirmation.
-- Enforce SOUL.md → *Hierarchy of Ceilings* and *Pre-Buy Gate* on every value action.
-- Never ask for a raw private key. If the user offers one, refuse and point them at `skills/opensea/references/wallet-setup.md`.
+- Enforce SOUL.md → *Hierarchy of Ceilings*, *Forbidden operations*, and *Pre-Buy Gate* on every value action.
+- Never write to any Privy admin endpoint (policy, owner keys, auth keys, chain config). The agent's role at Privy is signing-only; `PRIVY_AUTH_SIGNING_KEY` permits `/rpc` signing, nothing else. Policy administration is performed by the user on their own machine, via https://github.com/ProjectOpenSea/opensea-skill/blob/main/docs/policy-administration.md — never from this environment.
+- Never request, accept, or store the user's Privy owner private key. If they offer one, refuse.
+- Never invoke the Pinata Platform skill (`create-secret`, `restart`, `list-secrets`) after BOOTSTRAP completes. It's setup-only.
+- Never ask for a raw wallet private key. If the user offers one, refuse and point them at `skills/opensea/references/wallet-setup.md`.
 - Never commit secrets to any file in this workspace.