@buildaureon/sdk 0.1.0 → 0.1.1

package/docs/integration-guide.md

@@ -1,153 +1,195 @@
 # Production Integration Guide
 
-This guide details how to integrate `@buildaureon/sdk` into server-side agents, automated rebalancing scripts, and frontend user interfaces.
+Integrate `@buildaureon/sdk` into server-side agents and automated rebalancing loops against the live AUREON API.
 
----
+**Automation note:** SDK integrations support **Automatic mode only** (`automationMode: "auto"` — the default). Do not build Manual Approve agent loops with the SDK; use the operator utility for Manual workflows.
 
-## 1. End-to-End Integration Plan
+---
 
-Follow this six-step sequence to configure and start the automated rebalancing loop.
+## 1. End-to-end agent loop
 
 ```mermaid
 flowchart TD
-  Client[1. Client Init] --> Auth[2. Sign Handshake]
-  Auth --> Sync[3. Sync Capital Book]
-  Sync --> Deposit[4. Fund Vault]
-  Deposit --> Objective[5. Add Objective]
-  Objective --> Watchdog[6. Run Heartbeat Loop]
-  Watchdog --> Watchdog
+  Init[1_issued_API_key_client] --> Sync[2_sync_Capital_Book]
+  Sync --> Fund[3_fund_vault_if_empty]
+  Fund --> Obj[4_create_Auto_objective]
+  Obj --> Loop[5_watchdog_heartbeat]
+  Loop -->|breach| Plan[6_restore_plan]
+  Plan --> Restore[7_restoreObjective]
+  Restore --> Loop
 ```
 
-### Step 1: Client Construction
-Set up the client, leveraging environment variables for configuration options.
+### Step 1 — Client
 
 ```ts
-import { createAureonClient, createSessionTokenProvider } from "@buildaureon/sdk";
-
-const session = createSessionTokenProvider(
-  typeof localStorage !== "undefined"
-    ? localStorage.getItem("aureon_bearer_token")
-    : process.env.AUREON_TOKEN ?? null
-);
+import { createAureonClient } from "@buildaureon/sdk";
 
 export const aureon = createAureonClient({
   baseUrl: process.env.AUREON_API_URL || "https://api.aureonlabs.network",
-  apiKey: process.env.AUREON_API_KEY ?? null,
-  getAccessToken: session.getAccessToken
+  apiKey: process.env.AUREON_API_KEY!, // issued Developers key
+  timeoutMs: 30_000,
+  maxRetries: 2,
+  retryDelayMs: 500,
 });
+
+const me = await aureon.me();
+console.log("operating as", me.walletAddress);
 ```
 
-### Step 2: EIP-191 Cryptographic Verification
-Authenticate session tokens using cryptographic challenge-response verification.
+Optional Bearer (usually unnecessary with an issued key):
 
 ```ts
-async function authenticate(walletAddress: string, signerFn: (msg: string) => Promise<string>) {
-  // 1. Fetch challenge message
-  const { message } = await aureon.getAuthNonce(walletAddress);
-
-  // 2. Sign EIP-191 personal message locally
-  const signature = await signerFn(message);
-
-  // 3. Post verification payload
-  const { token } = await aureon.verifyWallet({
-    address: walletAddress,
-    message,
-    signature
-  });
-
-  session.setToken(token);
-  return token;
-}
+import { createAureonClient, createSessionTokenProvider } from "@buildaureon/sdk";
+
+const session = createSessionTokenProvider(process.env.AUREON_TOKEN ?? null);
+export const aureon = createAureonClient({
+  baseUrl: process.env.AUREON_API_URL || "https://api.aureonlabs.network",
+  apiKey: process.env.AUREON_API_KEY ?? null,
+  getAccessToken: session.getAccessToken,
+});
 ```
 
-### Step 3: Align the Capital Book
-Populate local assets into the gateway database.
+### Step 2 — Sync Capital Book
 
 ```ts
 const { portfolio, chainId } = await aureon.syncPortfolio();
-console.log(`Portfolios aligned for Chain ID ${chainId}. Total Valuation: $${portfolio.totalNotionalUsd}`);
+console.log({
+  chainId,
+  positions: portfolio.positions.length,
+  totalNotionalUsd: portfolio.totalNotionalUsd,
+});
 ```
 
-### Step 4: Fund the Smart Vault
-Automated objectives rebalance tokens held in your Smart Vault on the Robinhood Chain. Allocate capital into the vault before creating rules.
+Prefer `syncPortfolio()` over hand-seeded books in production. Use `setPortfolio` only for controlled rehearsals.
+
+### Step 3 — Fund vault when needed
+
+Automatic restores require vault capital. Prepare returns **unsigned** steps — your host signs and broadcasts.
 
 ```ts
-async function ensureVaultFunded(symbol: string, amount: string, executeTx: (step: any) => Promise<string>) {
+import type { VaultPrepareResult } from "@buildaureon/sdk";
+
+async function ensureVaultFunded(
+  symbol: string,
+  amount: string,
+  broadcast: (step: VaultPrepareResult["steps"][number]) => Promise<string>
+) {
   const status = await aureon.getVaultStatus();
-  if (status.empty) {
-    const prep = await aureon.prepareVaultDeposit({ symbol, amount });
-    for (const step of prep.steps) {
-      console.log(`Executing step: ${step.label}`);
-      const txHash = await executeTx(step);
-      console.log(`Step complete. Hash: ${txHash}`);
-    }
+  if (!status.empty && status.canRestore) return status;
+
+  const prep = await aureon.prepareVaultDeposit({ symbol, amount });
+  for (const step of prep.steps) {
+    const hash = await broadcast(step);
+    console.log(step.label, hash);
   }
+
+  return aureon.getVaultStatus();
 }
 ```
 
-### Step 5: Register the Objective
-Create the objective. SDK integrations default to `automationMode: "auto"`.
+Typical broadcast (viem sketch):
+
+```ts
+// host-owned — not part of the SDK
+await walletClient.sendTransaction({
+  to: step.to,
+  data: step.data,
+  value: step.value ? BigInt(step.value) : 0n,
+});
+```
+
+### Step 4 — Create an Automatic objective
 
 ```ts
 const objective = await aureon.createObjective({
-  name: "Liquid Stable Reserves",
-  kind: "stable_allocation",
-  targetWeight: 0.30,
-  tolerance: 0.03
+  name: "Maintain 20% WETH",
+  kind: "balanced_portfolio",
+  targetWeight: 0.2,
+  tolerance: 0.03,
+  targetSymbol: "WETH",
+  // automationMode defaults to "auto" — keep it that way for SDK agents
+  priority: "medium",
 });
-console.log(`Objective ${objective.name} registered. Status: ${objective.status}`);
 ```
 
-### Step 6: Execute the Watchdog Loop
-Poll the gateway regularly to check policy health and execute restorations.
+**Locks:** `targetSymbol` and `automationMode` cannot change after create. Recreate the objective to change token or mode.
+
+### Step 5 — Watchdog heartbeat
 
 ```ts
-async function watchdogHeartbeat() {
-  try {
-    const result = await aureon.refreshWatchdog();
-    console.log(`Watchdog completed at ${result.refreshedAt}. System state: ${result.breaches.length} breaches.`);
-
-    for (const breach of result.breaches) {
-      const plan = await aureon.getRestorePlan(breach.objectiveId);
-      if (plan.kind === "vault_swap") {
-        const receipt = await aureon.restoreObjective(breach.objectiveId);
-        console.log(`Rebalance executed. Settlement: ${receipt.settlement}, Hash: ${receipt.transactionHash}`);
-      }
-    }
-  } catch (error) {
-    console.error("Watchdog heartbeat failed:", error);
+async function heartbeat() {
+  const refreshed = await aureon.refreshWatchdog();
+  console.log("breaches", refreshed.breaches.length);
+
+  for (const breach of refreshed.breaches) {
+    const plan = await aureon.getRestorePlan(breach.objectiveId);
+    console.log("plan", plan.kind, plan);
+
+    const receipt = await aureon.restoreObjective(breach.objectiveId);
+    console.log({
+      settlement: receipt.settlement, // "vault" | "staged"
+      status: receipt.status,
+      tx: receipt.transactionHash,
+    });
   }
+
+  const health = await aureon.getHealth();
+  return health;
 }
 ```
 
+### Step 6 — Verify
+
+```ts
+await aureon.getHealth(objective.id);
+await aureon.getTimeline(objective.id);
+await aureon.listExecutions(objective.id);
+```
+
+Always branch UI/agent copy on `receipt.settlement`.
+
 ---
 
-## 2. Advanced Scripting Guidelines
+## 2. Recommended objective kinds for agents
 
-### 2.1 Implementing daemon runners
-For long-running processes, wrap the heartbeat logic in daemon controllers like PM2 or run them as systemd services.
+| Kind | Typical use |
+| --- | --- |
+| `balanced_portfolio` | Hold `targetSymbol` near a weight band |
+| `stable_allocation` | Keep a stable sleeve near a weight |
+| `risk_ceiling` | Cap portfolio risk score |
+| `reward_reinvestment` | Sweep rewards into a sleeve |
+
+Start with one Automatic `balanced_portfolio` objective and a funded vault before adding more policies.
+
+---
+
+## 3. Daemon runners
+
+### PM2
 
-#### PM2 Configuration (`ecosystem.config.js`)
 ```js
 module.exports = {
-  apps: [{
-    name: "aureon-agent-loop",
-    script: "./dist/index.js",
-    instances: 1,
-    autorestart: true,
-    watch: false,
-    env: {
-      NODE_ENV: "production",
-      AUREON_API_URL: "https://api.aureonlabs.network"
-    }
-  }]
+  apps: [
+    {
+      name: "aureon-agent-loop",
+      script: "./dist/index.js",
+      instances: 1,
+      autorestart: true,
+      env: {
+        NODE_ENV: "production",
+        AUREON_API_URL: "https://api.aureonlabs.network",
+        // AUREON_API_KEY from secret store / PM2 ecosystem secrets
+      },
+    },
+  ],
 };
 ```
 
-#### Systemd Service (`/etc/systemd/system/aureon.service`)
+### systemd
+
 ```ini
 [Unit]
-Description=Aureon Rebalance Watchdog Daemon
+Description=AUREON Automatic restore agent
 After=network.target
 
 [Service]
@@ -163,34 +205,53 @@ Environment=NODE_ENV=production
 WantedBy=multi-user.target
 ```
 
-### 2.2 Server-Side Logger Configuration (Pino / Winston)
-Log JSON payloads to persistent logging collectors.
+### Logging
 
 ```ts
-import winston from "winston";
 import { createAureonClient } from "@buildaureon/sdk";
 
-const logger = winston.createLogger({
-  level: "info",
-  format: winston.format.json(),
-  transports: [new winston.transports.File({ filename: "aureon-combined.log" })]
-});
-
 const aureon = createAureonClient({
-  apiKey: process.env.AUREON_API_KEY,
+  apiKey: process.env.AUREON_API_KEY!,
   logger: {
-    debug: (msg, ctx) => logger.debug(msg, ctx),
-    info: (msg, ctx) => logger.info(msg, ctx),
-    warn: (msg, ctx) => logger.warn(msg, ctx),
-    error: (msg, ctx) => logger.error(msg, ctx)
-  }
+    debug: (msg, ctx) => console.debug(msg, ctx),
+    info: (msg, ctx) => console.info(msg, ctx),
+    warn: (msg, ctx) => console.warn(msg, ctx),
+    error: (msg, ctx) => console.error(msg, ctx),
+  },
 });
 ```
 
+Never log API keys, Bearer tokens, or private keys.
+
+---
+
+## 4. Frontend / SPA notes
+
+- Do not ship issued API keys in public browser bundles.
+- Prefer a backend proxy for agent credentials.
+- Keep `refreshWatchdog` / `restoreObjective` loops on the server.
+- Browser operator UX is the utility app (wallet session), not the SDK agent path.
+
+---
+
+## 5. Troubleshooting
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| 401 invalid key | Wrong / paused / revoked key | Rotate in Developers |
+| 401 need issued key | Env bootstrap key alone | Use an issued Developers key |
+| Vault empty / cannot restore | No vault capital | `prepareVaultDeposit` → broadcast → sync |
+| Update rejects symbol/mode | Locked at create | Recreate objective |
+| Restore receipt `staged` | Ledger-local path | Do not claim on-chain |
+| Health still violated after restore | Prices / sizing / liquidity | Re-read plan, vault balances, timeline |
+| Network / timeout | RPC or API latency | Raise `timeoutMs`, set `maxRetries` |
+
 ---
 
-## 3. Frontend Deployment (SPA/Vite Environments)
+## 6. Related docs
 
-*   **Credential Leakage Prevention**: Never commit `AUREON_API_KEY` to public repositories. Deploy client credentials via backend server API proxy routes.
-*   **CORS Configurations**: The production gateway allows request origins matching allowlisted domains configured in the Developer console. For local development, localhost calls are permitted.
-*   **Decoupled loop execution**: Frontend interfaces should only allow users to manage objectives and inspect histories. Keep the active rebalancing loops (`refreshWatchdog` and `restoreObjective`) on secure server-side cron loops.
+- [Auth](./auth.md)
+- [Architecture](./architecture.md)
+- [Client API](./client-api.md)
+- [Error model](./error-model.md)
+- [Security](./security.md)

package/docs/security.md

@@ -1,74 +1,120 @@
 # Security Model and Practices
 
-This document outlines the security architecture of `@buildaureon/sdk`, its integration with Smart Vault smart contracts, and practices for secure production environments.
+Security architecture for `@buildaureon/sdk`: trust boundaries, credentials, vault signing, and production checklist.
+
+**Automation note:** SDK agents should run **Automatic** objectives only. Manual Approve flows are utility concerns, not SDK security surface.
 
 ---
 
-## 1. Gateway Trust Boundaries
+## 1. Gateway trust boundaries
 
-AUREON operates on a non-custodial gateway model. The API acts as an analytical policy engine, price indexer, and coordinator, but does not control asset custody.
+AUREON is non-custodial. The API is a policy engine, price indexer, and coordinator. It does not hold private keys and does not broadcast owner withdrawals for you.
 
 ```mermaid
 flowchart TD
-  Host[Host Application Boundary] -->|1. Request Calldata| Gateway[Aureon API Gateway]
-  Gateway -->|2. Generate Unsigned Steps| Host
-  Host -->|3. Sign Locally| Wallet[Private Key / HSM / KMS]
-  Wallet -->|4. Broadcast Tx| Chain[Robinhood Chain RPC]
-
-  subgraph OnChain [Smart Contract Controls]
-    Vault[Smart Vault Contract]
-    DX[Decentralized Exchanges]
-    Vault -->|Only allowlisted actions| DX
+  Host[Host_application] -->|1_request_calldata| Gateway[Aureon_API]
+  Gateway -->|2_unsigned_steps| Host
+  Host -->|3_sign_locally| Wallet[Private_key_or_KMS]
+  Wallet -->|4_broadcast| Chain[Robinhood_Chain_RPC]
+
+  subgraph OnChain [Smart_contract_controls]
+    Vault[Smart_Vault]
+    DX[Allowlisted_DEX_routes]
+    Vault -->|keeper_swaps_only| DX
   end
-  Wallet -.->|Call deposit / withdraw| Vault
+  Wallet -.->|owner_deposit_withdraw| Vault
 ```
 
-### 1.1 Private Key Isolation
-The SDK provides no features for loading or storing private keys or mnemonics. The host application handles transaction signing locally using EIP-191 signatures or raw transaction serializers. Because private keys are never transmitted to the AUREON API, a gateway breach cannot compromise user keys.
+### 1.1 Private key isolation
+
+The SDK never loads, stores, or transmits private keys or mnemonics. Signing stays in the host (viem, ethers, HSM, KMS). A gateway breach cannot drain vaults by itself.
+
+### 1.2 Issued API keys are wallet credentials
+
+An **issued** developer key identifies the bound wallet for control-plane operations (sync, objectives, health, restore, prepare). Treat it like a password:
+
+- Create in utility **Developers**
+- Store in env / secret manager
+- Pause or revoke on leak
+- Prefer one key per agent host
 
-### 1.2 Unsigned Calldata Generation
-Endpoints like `prepareVaultDeposit` and `prepareVaultWithdraw` return structured calldata. You can decode and verify this data against open-source contract ABIs before signing and broadcasting.
+Env bootstrap keys on the server unlock product access only. They do **not** identify a wallet and must not be used as agent identity.
+
+### 1.3 Unsigned calldata
+
+`prepareVaultDeposit` / `prepareVaultWithdraw` return structured steps. Decode against published ABIs before signing. Broadcast is always host-side.
 
 ---
 
-## 2. Smart Contract Access Control
+## 2. What a compromised API key can and cannot do
+
+| Can | Cannot |
+| --- | --- |
+| Read portfolio, vault, health, timeline | Sign owner deposit/withdraw txs |
+| Create / update / pause Auto objectives | Withdraw vault funds to arbitrary addresses |
+| Request restore plans and trigger Automatic restore coordination | Bypass vault keeper allowlists |
+| Create additional developer keys under the same wallet | Recover a private key |
+
+Keeper-driven Automatic restores execute allowlisted vault swaps. Keepers cannot send vault assets to arbitrary third parties.
 
-The AUREON Smart Vault contracts on the Robinhood Chain enforce strict permission boundaries:
+---
+
+## 3. Smart vault access control
 
-*   **Owner Gate**: Only the address that deployed the vault (or was assigned ownership) can execute direct withdrawals.
-*   **Allowlisted Keepers**: Swap routes can only be executed by registered keeper addresses. The keeper cannot withdraw tokens to external third-party addresses; they are restricted to swapping allowlisted assets within the vault.
-*   **Limits and Slippage**: The contracts enforce maximum slippage tolerances on swaps to prevent sandwich attacks and price manipulation.
+- **Owner path:** deposits and withdrawals require owner-signed txs from prepare steps.
+- **Keeper path:** Automatic restores use registered keepers on allowlisted routes only.
+- **Slippage / limits:** vault and planner enforce execution bounds to reduce bad fills.
 
 ---
 
-## 3. Credentials and API Keys Management
+## 4. Settlement honesty
+
+Every execution receipt includes `settlement`:
 
-*   **Zero Commits**: Never check API keys into git repositories. Load keys from environment variables or secure stores (e.g. AWS Secrets Manager, HashiCorp Vault).
-*   **CI/CD Configuration**: If you run tests in automated pipelines (e.g., GitHub Actions, GitLab CI), store credentials as encrypted secrets.
-*   **Frontend Mitigation**: Frontends should query an intermediate backend service instead of exposing API keys directly to the client bundle.
-*   **Key Rotation**: Generate replacement credentials and deprecate compromised tokens in the developer console immediately if a breach is suspected.
+| Value | Meaning | UI rule |
+| --- | --- | --- |
+| `vault` | On-chain vault / keeper settlement with verifiable hash | May show as on-chain |
+| `staged` | Ledger-local / rehearsal — not a chain settlement | Must **not** be labeled as on-chain |
+
+Never collapse staged into “confirmed on Robinhood Chain.”
 
 ---
 
-## 4. Understanding Staged Settlement
+## 5. Transport and logging hygiene
 
-AUREON receipts contain a `settlement` field:
+- Prefer HTTPS production base URL `https://api.aureonlabs.network`.
+- Do not log raw `Authorization` or `X-Aureon-Api-Key`.
+- Redact prepare step calldata in public logs if it includes sensitive amounts in your threat model.
+- Set `timeoutMs` / `maxRetries` deliberately for agent loops (see [transport.md](./transport.md)).
 
-*   **Vault Settlement (`vault`)**: Transactions are settled on-chain on the Robinhood Chain. These have a real transaction hash and are verifiable via explorer.
-*   **Staged Settlement (`staged`)**: Simulated rebalances that update gateway database states without broadcasting transactions. This is used during rehearsals and testing.
+---
 
-> [!WARNING]
-> Do not display staged rebalances as completed on-chain transactions in your dashboards. Always check the `settlement` attribute before presenting transaction confirmations to operators.
+## 6. Frontend vs agent hosts
+
+| Host | Guidance |
+| --- | --- |
+| Server agent / cron | Issued API key in secret store; private key in KMS if broadcasting deposits |
+| Browser SPA | Do **not** embed issued API keys in public bundles; proxy through your backend |
+| Operator utility | Wallet Bearer only — separate from SDK agent auth |
 
 ---
 
-## 5. Production Checklist
+## 7. Production checklist
+
+- [ ] Issued developer key (not a shared env bootstrap key) in secrets
+- [ ] Private keys isolated from the API key and never logged
+- [ ] Deposit/withdraw broadcast path reviewed and ABI-checked
+- [ ] Automatic objectives only in SDK loops
+- [ ] UI / agent summaries honor `settlement: vault | staged`
+- [ ] Gas reserve on the signing wallet for owner txs
+- [ ] Key rotation plan (pause/revoke in Developers)
+- [ ] Error handling branches on `error.code` (see [error-model.md](./error-model.md))
+
+---
 
-Review this security checklist before deploying your rebalancing daemon to production:
+## 8. Related docs
 
-- [ ] **Private Key Isolation**: Confirm that private keys are stored in environment variables or KMS, and are never logged or exposed.
-- [ ] **EIP-191 Handshake**: Ensure all user logins use the cryptographic challenge-response flow (`verifyWallet`).
-- [ ] **Scope Checks**: Verify that the API Key has the minimum permissions needed to run the target agent.
-- [ ] **Gas Auditing**: Maintain a gas reserve on the signing wallet to cover deposit and withdrawal transactions on the Robinhood Chain.
-- [ ] **Staged Handling**: Confirm your user interface clearly distinguishes between staged and vault settlements.
-- [ ] **Slippage Bounds**: Configure appropriate slippage tolerances on objectives to prevent execution failure during market volatility.
+- [Auth](./auth.md)
+- [Architecture](./architecture.md)
+- [Integration guide](./integration-guide.md)
+- [Error model](./error-model.md)