@buildaureon/sdk 0.1.0 → 0.1.1

package/docs/auth.md

@@ -1,60 +1,108 @@
-# Cryptographic Authentication Guide
+# Authentication Guide
 
-AUREON combines classic API authentication with Web3 signature verification. This guide provides an in-depth technical explanation of the handshake flow, JWT payloads, and client integrations using standard EVM libraries.
+How `@buildaureon/sdk` authenticates to the hosted AUREON API for agents, scripts, and server integrations.
 
----
+**Automation note:** The SDK path is designed for **Automatic** objectives only (`automationMode: "auto"`). Manual operator Approve flows belong in the utility UI, not in SDK agent loops.
 
-## 1. Authentication Topology
+---
 
-Requests are validated using a dual-token header model. 
+## 1. Authentication topology
 
 ```mermaid
 graph TD
-  Request[Client Request] --> KeyCheck{Has API Key?}
-  KeyCheck -->|No| Reject1[401 Unauthorized: Missing API Key]
-  KeyCheck -->|Yes| RouteCheck{Is Route Public?}
-  RouteCheck -->|Yes| Allow[Process Request]
-  RouteCheck -->|No| BearerCheck{Has Valid Bearer JWT?}
-  BearerCheck -->|No| Reject2[401 Unauthorized: Missing Session Token]
-  BearerCheck -->|Yes| ScopeCheck{Is Token Bound to Target Wallet?}
-  ScopeCheck -->|No| Reject3[403 Forbidden: Wallet Mismatch]
-  ScopeCheck -->|Yes| Process[Process request]
+  Request[Client_request] --> BearerCheck{Valid_Bearer?}
+  BearerCheck -->|Yes| Process[Act_as_session_wallet]
+  BearerCheck -->|No| KeyCheck{API_key_present?}
+  KeyCheck -->|No| Reject1[401_missing_credentials]
+  KeyCheck -->|Yes| IssuedCheck{Issued_developer_key?}
+  IssuedCheck -->|Yes| ProcessKey[Act_as_key_bound_wallet]
+  IssuedCheck -->|No_env_bootstrap| Reject2[401_need_issued_key_or_Bearer]
+```
+
+| Credential | Header | Role |
+| --- | --- | --- |
+| **Issued API key** (Developers console) | `X-Aureon-Api-Key` | Product access **and** wallet identity for control-plane calls |
+| **Env bootstrap key** (`AUREON_API_KEYS` on server) | `X-Aureon-Api-Key` | Product gate only — does **not** identify a wallet |
+| **Wallet Bearer** | `Authorization: Bearer …` | Optional session identity. **Wins** when both Bearer and key are present |
+| **Private key** | (chain only) | Sign/broadcast deposit & withdraw txs — never sent to the API |
+
+Control-plane calls (sync, objectives, health, restore, vault reads, prepare-*) need an **issued** developer key **or** a Bearer session. Moving capital on-chain always needs a local signer.
+
+---
+
+## 2. Recommended path: issued API key
+
+1. Open the operator utility → **Developers**.
+2. Create a key. Copy the plaintext once.
+3. Set env and construct the client:
+
+```ts
+import { createAureonClient } from "@buildaureon/sdk";
+
+const aureon = createAureonClient({
+  baseUrl: "https://api.aureonlabs.network",
+  apiKey: process.env.AUREON_API_KEY!, // issued key from Developers
+});
+
+const me = await aureon.me();
+console.log("wallet", me.walletAddress);
+
+const vault = await aureon.getVaultStatus();
+const objectives = await aureon.listObjectives();
 ```
 
-*   **API Key (`X-Aureon-Api-Key`)**: Sent in the headers to identify your product subscription or server deployment. It is generated in the developer dashboard.
-*   **Bearer JWT (`Authorization: Bearer <token>`)**: Establishes session ownership. It is generated dynamically by signing a server-issued challenge message with your private key.
+No Bearer token is required for this path. The gateway resolves the wallet bound to the issued key.
+
+### Deposit / withdraw still need a private key
+
+```ts
+const prep = await aureon.prepareVaultDeposit({ symbol: "ETH", amount: "0.1" });
+// prep.steps are UNSIGNED — sign and broadcast with viem / ethers / your wallet host
+```
+
+The API key can request prepare steps. It cannot sign chain transactions.
 
 ---
 
-## 2. EIP-191 Cryptographic Handshake
+## 3. Optional Bearer handshake
 
-The signature validation relies on the EIP-191 standard for signing personal messages. The process prevents replay attacks and ensures session integrity.
+Use when you intentionally want a wallet session, or when you only have an env bootstrap key (no issued key).
 
 ```mermaid
 sequenceDiagram
   autonumber
-  participant Client as SDK Client
-  participant Gateway as Aureon Gateway
-  participant Signer as Wallet Signer (EIP-191)
-
-  Client->>Gateway: GET /auth/nonce?address=0x742...
-  Gateway->>Gateway: Generate unique nonce & expiresAt
-  Gateway-->>Client: Challenge (nonce, message, expiresAt)
-  Client->>Signer: Request signature over message
-  Signer->>Signer: Sign message using private key (personal_sign)
-  Signer-->>Client: Cryptographic Signature (65-byte hex string)
-  Client->>Gateway: POST /auth/verify { address, message, signature }
-  Gateway->>Gateway: Recover signer address from signature
-  alt Recovered Address == Input Address and Not Expired
-    Gateway->>Gateway: Generate JWT (Expires in 24 hours)
-    Gateway-->>Client: AuthSessionResponse (token, expiresAt)
-  else Validation Failed
-    Gateway-->>Client: Throw 401 ValidationError
-  end
+  participant Client as SDK_client
+  participant API as Aureon_API
+  participant Signer as Wallet_signer
+
+  Client->>API: GET /auth/nonce?address=0x...
+  API-->>Client: challenge message
+  Client->>Signer: personal_sign(message)
+  Signer-->>Client: signature
+  Client->>API: POST /auth/verify
+  API-->>Client: session token
 ```
 
-### 2.1 The Challenge Message Schema
-The message returned by `/auth/nonce` follows a strict structure:
+```ts
+import { createAureonClient, createSessionTokenProvider } from "@buildaureon/sdk";
+
+const session = createSessionTokenProvider(null);
+const aureon = createAureonClient({
+  baseUrl: "https://api.aureonlabs.network",
+  apiKey: process.env.AUREON_API_KEY,
+  getAccessToken: session.getAccessToken,
+});
+
+const { message } = await aureon.getAuthNonce(address);
+const signature = await wallet.signMessage({ message });
+const login = await aureon.verifyWallet({ address, message, signature });
+session.setToken(login.token);
+
+await aureon.me();
+```
+
+### Challenge message shape
+
 ```text
 AUREON Login Challenge
 Wallet: 0x742d35Cc6634C0532925a3b844Bc454e4438f44e
@@ -64,152 +112,63 @@ Expires: 2026-07-15T22:50:00.000Z
 
 Sign this message to prove ownership of the wallet.
 ```
-*   **Nonce**: A cryptographically secure random string preventing replay attacks.
-*   **Expires**: The timestamp (5-minute TTL) after which the challenge becomes invalid.
 
----
+### Session provider lifecycle
 
-## 3. JWT Payload Structure
-
-Upon successful signature recovery, the gateway issues a JSON Web Token containing the session metadata:
-
-```json
-{
-  "sub": "0x742d35cc6634c0532925a3b844bc454e4438f44e",
-  "iss": "aureon-auth-service",
-  "iat": 1784155500,
-  "exp": 1784241900,
-  "sid": "sess_01h8v12x8p8p3z2v1q45r3m2e1",
-  "scope": "operator"
-}
+```ts
+session.setToken(login.token); // after verify
+await aureon.logout();
+session.clear();
 ```
 
-*   **`sub` (Subject)**: The lowercase Ethereum address of the authenticated wallet.
-*   **`exp` (Expiration)**: Unix timestamp set exactly 24 hours after token issuance.
-*   **`scope`**: Defines operational permissions (e.g. `operator`, `read-only`).
+`createSessionTokenProvider` keeps the client free of global mutable auth state. Prefer `getAccessToken` over a static `authToken` when sessions can rotate.
 
 ---
 
-## 4. Multi-Framework Integration Examples
+## 4. Precedence and edge cases
 
-### 4.1 Integration via Viem (TypeScript / Node.js)
-Ideal for background cron daemons, keepers, and automated scripts.
+| Situation | Result |
+| --- | --- |
+| Issued key only | Act as key-bound wallet |
+| Bearer only | Act as session wallet |
+| Bearer + any key | Bearer wins (key validated if sent) |
+| Env bootstrap key only | 401 — cannot identify a wallet |
+| Invalid / paused / revoked issued key | 401 |
+| `devLogin()` | Local preview APIs only — not production |
 
-```ts
-import { createAureonClient, createSessionTokenProvider } from "@buildaureon/sdk";
-import { createWalletClient, http } from "viem";
-import { privateKeyToAccount } from "viem/accounts";
-import { mainnet } from "viem/chains";
-
-async function authenticateAgent() {
-  const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
-  const wallet = createWalletClient({
-    account,
-    chain: mainnet,
-    transport: http()
-  });
-
-  const session = createSessionTokenProvider(null);
-  const aureon = createAureonClient({
-    apiKey: process.env.AUREON_API_KEY,
-    getAccessToken: session.getAccessToken
-  });
-
-  // 1. Get nonce
-  const { message } = await aureon.getAuthNonce(account.address);
-
-  // 2. Sign EIP-191 message
-  const signature = await wallet.signMessage({ message });
-
-  // 3. Verify on server
-  const login = await aureon.verifyWallet({
-    address: account.address,
-    message,
-    signature
-  });
-
-  session.setToken(login.token);
-  return aureon;
-}
-```
+---
 
-### 4.2 Integration via Ethers.js v6
-Useful for traditional Node.js servers or scripts using Ethers.
+## 5. Environment variables
 
-```ts
-import { createAureonClient, createSessionTokenProvider } from "@buildaureon/sdk";
-import { Wallet } from "ethers";
-
-async function authenticateEthers() {
-  const wallet = new Wallet(process.env.PRIVATE_KEY!);
-  const session = createSessionTokenProvider(null);
-  const aureon = createAureonClient({
-    apiKey: process.env.AUREON_API_KEY,
-    getAccessToken: session.getAccessToken
-  });
-
-  const { message } = await aureon.getAuthNonce(wallet.address);
-  const signature = await wallet.signMessage(message);
-
-  const login = await aureon.verifyWallet({
-    address: wallet.address,
-    message,
-    signature
-  });
-
-  session.setToken(login.token);
-  return aureon;
-}
+| Variable | Required | Description |
+| --- | --- | --- |
+| `AUREON_API_KEY` | Recommended | Issued developer key |
+| `AUREON_API_URL` | No | Defaults to `https://api.aureonlabs.network` |
+| `AUREON_TOKEN` | No | Optional Bearer for CLI / scripts |
+
+CLI example:
+
+```bash
+export AUREON_API_KEY=aureon_....
+pnpm --filter @buildaureon/sdk cli me
+pnpm --filter @buildaureon/sdk cli sync
+pnpm --filter @buildaureon/sdk cli objectives
 ```
 
-### 4.3 Integration in Browser Frontends (window.ethereum)
-Suitable for operator portals and user-facing dashboards.
+---
 
-```ts
-import { createAureonClient, createSessionTokenProvider } from "@buildaureon/sdk";
+## 6. Security rules
 
-async function loginBrowser() {
-  if (!window.ethereum) throw new Error("No provider found");
-
-  const [address] = await window.ethereum.request({ method: "eth_requestAccounts" });
-  const session = createSessionTokenProvider(localStorage.getItem("aureon_token"));
-  
-  const aureon = createAureonClient({
-    apiKey: process.env.AUREON_API_KEY,
-    getAccessToken: session.getAccessToken
-  });
-
-  try {
-    // Validate current token
-    await aureon.me();
-  } catch (err) {
-    // Fetch new challenge
-    const { message } = await aureon.getAuthNonce(address);
-
-    // Sign using browser extension wallet
-    const signature = await window.ethereum.request({
-      method: "personal_sign",
-      params: [message, address]
-    });
-
-    const login = await aureon.verifyWallet({ address, message, signature });
-    session.setToken(login.token);
-    localStorage.setItem("aureon_token", login.token);
-  }
-
-  return aureon;
-}
-```
+- Treat issued keys like passwords: pause, revoke, rotate in Developers.
+- Never commit keys or Bearer tokens.
+- Never put private keys in SDK env for “convenience.”
+- Do not log `Authorization` or `X-Aureon-Api-Key` headers.
 
 ---
 
-## 5. Token Lifecycle and Recovery
+## 7. Related docs
 
-*   **Handling Token Expirations**: When a session token expires, the gateway returns a `401 UNAUTHORIZED` error. Integrators should register a callback in their request loops to renew the token automatically.
-*   **Multi-Wallet Routing**: If your application manages multiple vaults, instantiate separate `AureonClient` instances for each session token provider. Portfolios are partitioned by wallet address.
-*   **Logout Mechanics**: Invoking `aureon.logout()` invalidates the JWT on the gateway. The local cache should be cleared immediately:
-    ```ts
-    await aureon.logout();
-    session.clear();
-    localStorage.removeItem("aureon_token");
-    ```
+- [Integration guide](./integration-guide.md)
+- [Security](./security.md)
+- [Client API](./client-api.md)
+- [Error model](./error-model.md)

package/docs/client-api.md

@@ -45,8 +45,8 @@ const aureon = createAureonClient({
 | Option | Required | Default | Description |
 |--------|----------|---------|-------------|
 | `baseUrl` | no | `https://api.aureonlabs.network` | Absolute `http://` or `https://` URL. |
-| `apiKey` | SDK / CLI | N/A | Sent as `X-Aureon-Api-Key`. Utility uses wallet Bearer only. |
-| `getAccessToken` | no | N/A | Sync/async getter before every request. Preferred for Bearer. |
+| `apiKey` | SDK / CLI | N/A | Sent as `X-Aureon-Api-Key`. Issued developer keys also identify the bound wallet (no Bearer required). Env bootstrap keys are product-gate only. Utility uses wallet Bearer only. |
+| `getAccessToken` | no | N/A | Optional Bearer getter. Wins over API-key identity when present. |
 | `authToken` | no | N/A | Static Bearer string when `getAccessToken` is omitted. |
 | `timeoutMs` | no | `30000` | Per-attempt abort timeout. |
 | `maxRetries` | no | `0` | Extra attempts after first failure for retryable errors. |
@@ -202,10 +202,10 @@ async createObjective(input: CreateObjectiveInput): Promise<Objective>
 | Auth | Required |
 | HTTP | `POST /objectives` |
 | Client validation | Name ≥ 3 chars; kind; `targetWeight` ∈ [0,1]; `tolerance` ∈ [0,0.5]; priority if set |
-| Automation | Defaults **`automationMode: "auto"`** (Automatic restore). Omit `automationMode` in SDK/agent integrations. |
+| Automation | SDK supports **Automatic only**. Defaults **`automationMode: "auto"`**. Omit the field in agent integrations. |
 | `targetSymbol` | Required when `kind === "balanced_portfolio"` (uppercased on normalize). |
 
-Manual Approve (`automationMode: "manual"`) is **operator-utility only**, and is not the recommended SDK create path.
+**SDK policy:** Automatic mode only. Manual Approve belongs in the operator utility — do not build Manual agent loops with this package.
 
 ```ts
 const objective = await aureon.createObjective({
@@ -262,6 +262,7 @@ async updateObjective(id: string, input: UpdateObjectiveInput): Promise<Objectiv
 | Auth | Required |
 | HTTP | `PATCH /objectives/:id` |
 | Body | Partial: name, priority, targetWeight, tolerance, maxRiskScore, reinvestRatio |
+| Locked at create | `targetSymbol`, `automationMode` — recreate the objective to change either |
 
 ### `pauseObjective(id)` / `resumeObjective(id)`
 

package/docs/data-contracts.md

@@ -65,13 +65,16 @@ export type ObjectivePriority = "low" | "medium" | "high" | "critical";
 ### ObjectiveAutomationMode
 
 Determines how policy violations are corrected:
-*   `auto`: Fully automated restore loops. The system generates execution receipts immediately upon detecting a violation (SDK default).
-*   `manual`: The operator utility flags the violation, requiring an explicit approval step in the UI.
+
+* `auto` — Automatic restore coordination (SDK **only** supported mode; default).
+* `manual` — Operator utility Approve flow. Not used for SDK agent integrations.
 
 ```ts
 export type ObjectiveAutomationMode = "manual" | "auto";
 ```
 
+For `@buildaureon/sdk`, always omit `automationMode` or pass `"auto"`.
+
 ### ObjectivePolicy
 
 Specifies the mathematical parameters governing target bounds:
@@ -149,7 +152,7 @@ Passed to `createObjective` to register a new rule:
 *   `automationMode` (Optional): Defaults to `auto` in the SDK.
 
 #### `UpdateObjectiveInput`
-Passed to `updateObjective` for partial updates. Note that `automationMode` is fixed at creation and cannot be updated.
+Passed to `updateObjective` for partial updates. `targetSymbol` and `automationMode` are fixed at creation and cannot be updated.
 
 ```ts
 export interface UpdateObjectiveInput {
@@ -159,7 +162,7 @@ export interface UpdateObjectiveInput {
   tolerance?: number;
   maxRiskScore?: number;
   reinvestRatio?: number;
-  targetSymbol?: string | null;
+  targetSymbol?: never; // Disallowed on updates
   automationMode?: never; // Disallowed on updates
 }
 ```