@buildaureon/sdk 0.1.1 → 0.1.2

package/docs/security.md

@@ -1,120 +1,120 @@
-# Security Model and Practices
-
-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
-
-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] -->|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 -.->|owner_deposit_withdraw| Vault
-```
-
-### 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
-
-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. 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.
-
----
-
-## 3. Smart vault access control
-
-- **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.
-
----
-
-## 4. Settlement honesty
-
-Every execution receipt includes `settlement`:
-
-| 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.”
-
----
-
-## 5. Transport and logging hygiene
-
-- 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)).
-
----
-
-## 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 |
-
----
-
-## 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))
-
----
-
-## 8. Related docs
-
-- [Auth](./auth.md)
-- [Architecture](./architecture.md)
-- [Integration guide](./integration-guide.md)
-- [Error model](./error-model.md)
+# Security Model and Practices
+
+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
+
+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] -->|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 -.->|owner_deposit_withdraw| Vault
+```
+
+### 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
+
+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. 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.
+
+---
+
+## 3. Smart vault access control
+
+- **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.
+
+---
+
+## 4. Settlement honesty
+
+Every execution receipt includes `settlement`:
+
+| 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.”
+
+---
+
+## 5. Transport and logging hygiene
+
+- 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)).
+
+---
+
+## 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 |
+
+---
+
+## 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))
+
+---
+
+## 8. Related docs
+
+- [Auth](./auth.md)
+- [Architecture](./architecture.md)
+- [Integration guide](./integration-guide.md)
+- [Error model](./error-model.md)

package/docs/transport.md

@@ -1,142 +1,142 @@
-# Transport Layer Reference
-
-HTTP transport for `@buildaureon/sdk` (`src/transport/http.ts`): headers, timeouts, retries, URL helpers, and logging.
-
----
-
-## 1. Request lifecycle
-
-```mermaid
-flowchart TD
-  Call[Client_method] --> Prep[Join_URL_and_headers]
-  Prep --> Auth[Resolve_API_key_and_Bearer]
-  Auth --> Abort[AbortController_timeout]
-  Abort --> Fetch[fetch_implementation]
-  Fetch --> Ok{HTTP_OK?}
-  Ok -->|Yes| Parse[Parse_JSON]
-  Ok -->|No| Map[Map_to_AureonError]
-  Map --> Retry{Retryable_and_budget?}
-  Retry -->|Yes| Sleep[retryDelayMs]
-  Sleep --> Fetch
-  Retry -->|No| Throw[Throw]
-```
-
-1. Join `baseUrl` + path; attach query string when needed.
-2. Resolve `X-Aureon-Api-Key` from `apiKey` / `getApiKey`.
-3. Resolve `Authorization: Bearer …` from `getAccessToken` / `authToken` (optional).
-4. Apply timeout via `AbortController` (default 30s).
-5. On failure, map status → typed error; retry only if configured and retryable.
-
----
-
-## 2. Headers
-
-| Header | When | Purpose |
-| --- | --- | --- |
-| `Accept` | Always | `application/json` |
-| `Content-Type` | Body present | `application/json` |
-| `X-Aureon-SDK` | Always | Package identity / version |
-| `X-Aureon-Api-Key` | Key configured | Product access + issued-key identity |
-| `Authorization` | Token configured | Optional Bearer session |
-| Custom `headers` | If set on client | Merged into every request |
-
-Issued developer keys in `X-Aureon-Api-Key` are enough for control-plane identity on the live API. Bearer is optional and wins when both are present.
-
----
-
-## 3. Client transport options
-
-```ts
-createAureonClient({
-  baseUrl: "https://api.aureonlabs.network",
-  apiKey: process.env.AUREON_API_KEY!,
-  timeoutMs: 30_000,   // per attempt
-  maxRetries: 2,        // extra attempts after first failure
-  retryDelayMs: 500,    // fixed delay between attempts
-  fetch: customFetch,   // optional
-  headers: { "X-Debug": "1" },
-  logger: myLogger,
-});
-```
-
-| Option | Default | Notes |
-| --- | --- | --- |
-| `timeoutMs` | `30000` | Must be positive finite |
-| `maxRetries` | `0` | Extra tries after the first failure |
-| `retryDelayMs` | `250` | Fixed sleep between tries |
-| `fetch` | `globalThis.fetch` | Inject for tests / unusual runtimes |
-
----
-
-## 4. Retry policy
-
-**Retryable:** network failures, timeouts, HTTP 429, HTTP 5xx (when mapped as retryable).
-
-**Not retryable:** 400 validation, 401/403 auth, 404, most 409 conflicts (operator must change state).
-
-Total attempts = `1 + maxRetries`.
-
----
-
-## 5. URL helpers
-
-### `joinUrl`
-
-Prevents double slashes when combining base + path.
-
-### `withQuery`
-
-Serializes defined query params with `encodeURIComponent`. Omits `null` / `undefined`.
-
----
-
-## 6. Timeouts and aborts
-
-```ts
-const controller = new AbortController();
-const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
-try {
-  return await fetchImpl(url, { ...init, signal: controller.signal });
-} catch (error) {
-  if (error instanceof Error && error.name === "AbortError") {
-    throw /* AureonTimeoutError */;
-  }
-  throw /* AureonNetworkError */;
-} finally {
-  clearTimeout(timeoutId);
-}
-```
-
-For agent loops that call restore + sync, prefer slightly higher `timeoutMs` under load rather than disabling timeouts.
-
----
-
-## 7. Logger interface
-
-```ts
-interface AureonLogger {
-  debug(message: string, context?: Record<string, unknown>): void;
-  info(message: string, context?: Record<string, unknown>): void;
-  warn(message: string, context?: Record<string, unknown>): void;
-  error(message: string, context?: Record<string, unknown>): void;
-}
-```
-
-Helpers may include console / silent adapters depending on package exports. Never log secrets from context.
-
----
-
-## 8. Testing transport
-
-- Inject a fake `fetch` that returns controlled status/body.
-- Assert header presence of `X-Aureon-Api-Key` for SDK clients.
-- Assert retries by counting fetch invocations with `maxRetries > 0` and 503 responses.
-
----
-
-## 9. Related docs
-
-- [Error model](./error-model.md)
-- [Auth](./auth.md)
-- [Client API](./client-api.md)
-- [Security](./security.md)
+# Transport Layer Reference
+
+HTTP transport for `@buildaureon/sdk` (`src/transport/http.ts`): headers, timeouts, retries, URL helpers, and logging.
+
+---
+
+## 1. Request lifecycle
+
+```mermaid
+flowchart TD
+  Call[Client_method] --> Prep[Join_URL_and_headers]
+  Prep --> Auth[Resolve_API_key_and_Bearer]
+  Auth --> Abort[AbortController_timeout]
+  Abort --> Fetch[fetch_implementation]
+  Fetch --> Ok{HTTP_OK?}
+  Ok -->|Yes| Parse[Parse_JSON]
+  Ok -->|No| Map[Map_to_AureonError]
+  Map --> Retry{Retryable_and_budget?}
+  Retry -->|Yes| Sleep[retryDelayMs]
+  Sleep --> Fetch
+  Retry -->|No| Throw[Throw]
+```
+
+1. Join `baseUrl` + path; attach query string when needed.
+2. Resolve `X-Aureon-Api-Key` from `apiKey` / `getApiKey`.
+3. Resolve `Authorization: Bearer …` from `getAccessToken` / `authToken` (optional).
+4. Apply timeout via `AbortController` (default 30s).
+5. On failure, map status → typed error; retry only if configured and retryable.
+
+---
+
+## 2. Headers
+
+| Header | When | Purpose |
+| --- | --- | --- |
+| `Accept` | Always | `application/json` |
+| `Content-Type` | Body present | `application/json` |
+| `X-Aureon-SDK` | Always | Package identity / version |
+| `X-Aureon-Api-Key` | Key configured | Product access + issued-key identity |
+| `Authorization` | Token configured | Optional Bearer session |
+| Custom `headers` | If set on client | Merged into every request |
+
+Issued developer keys in `X-Aureon-Api-Key` are enough for control-plane identity on the live API. Bearer is optional and wins when both are present.
+
+---
+
+## 3. Client transport options
+
+```ts
+createAureonClient({
+  baseUrl: "https://api.aureonlabs.network",
+  apiKey: process.env.AUREON_API_KEY!,
+  timeoutMs: 30_000,   // per attempt
+  maxRetries: 2,        // extra attempts after first failure
+  retryDelayMs: 500,    // fixed delay between attempts
+  fetch: customFetch,   // optional
+  headers: { "X-Debug": "1" },
+  logger: myLogger,
+});
+```
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `timeoutMs` | `30000` | Must be positive finite |
+| `maxRetries` | `0` | Extra tries after the first failure |
+| `retryDelayMs` | `250` | Fixed sleep between tries |
+| `fetch` | `globalThis.fetch` | Inject for tests / unusual runtimes |
+
+---
+
+## 4. Retry policy
+
+**Retryable:** network failures, timeouts, HTTP 429, HTTP 5xx (when mapped as retryable).
+
+**Not retryable:** 400 validation, 401/403 auth, 404, most 409 conflicts (operator must change state).
+
+Total attempts = `1 + maxRetries`.
+
+---
+
+## 5. URL helpers
+
+### `joinUrl`
+
+Prevents double slashes when combining base + path.
+
+### `withQuery`
+
+Serializes defined query params with `encodeURIComponent`. Omits `null` / `undefined`.
+
+---
+
+## 6. Timeouts and aborts
+
+```ts
+const controller = new AbortController();
+const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+try {
+  return await fetchImpl(url, { ...init, signal: controller.signal });
+} catch (error) {
+  if (error instanceof Error && error.name === "AbortError") {
+    throw /* AureonTimeoutError */;
+  }
+  throw /* AureonNetworkError */;
+} finally {
+  clearTimeout(timeoutId);
+}
+```
+
+For agent loops that call restore + sync, prefer slightly higher `timeoutMs` under load rather than disabling timeouts.
+
+---
+
+## 7. Logger interface
+
+```ts
+interface AureonLogger {
+  debug(message: string, context?: Record<string, unknown>): void;
+  info(message: string, context?: Record<string, unknown>): void;
+  warn(message: string, context?: Record<string, unknown>): void;
+  error(message: string, context?: Record<string, unknown>): void;
+}
+```
+
+Helpers may include console / silent adapters depending on package exports. Never log secrets from context.
+
+---
+
+## 8. Testing transport
+
+- Inject a fake `fetch` that returns controlled status/body.
+- Assert header presence of `X-Aureon-Api-Key` for SDK clients.
+- Assert retries by counting fetch invocations with `maxRetries > 0` and 503 responses.
+
+---
+
+## 9. Related docs
+
+- [Error model](./error-model.md)
+- [Auth](./auth.md)
+- [Client API](./client-api.md)
+- [Security](./security.md)

package/examples/market-event/main.ts

@@ -1,65 +1,65 @@
-/**
- * @fileoverview Controlled market-event rehearsal against the live AUREON API.
- *
- * Env:
- *   AUREON_API_KEY  issued developer key (required)
- *   AUREON_API_URL  optional (default https://api.aureonlabs.network)
- *
- *   pnpm --filter @buildaureon/sdk example:market
- */
-
-import {
-  createAureonClient,
-  DEFAULT_API_BASE_URL,
-  isAureonError,
-} from "../../src/index.js";
-
-async function main(): Promise<void> {
-  const apiKey = process.env.AUREON_API_KEY?.trim();
-  if (!apiKey) {
-    throw new Error("Set AUREON_API_KEY to an issued developer key.");
-  }
-
-  const aureon = createAureonClient({
-    baseUrl: process.env.AUREON_API_URL?.trim() || DEFAULT_API_BASE_URL,
-    apiKey,
-  });
-
-  const objective = await aureon.createObjective({
-    name: "Maintain 20% Stable Assets",
-    kind: "stable_allocation",
-    targetWeight: 0.2,
-    tolerance: 0.02,
-  });
-
-  const result = await aureon.applyMarketEvent({
-    name: "NVDA Stock Token Rally",
-    description: "Controlled mark appreciation on NVIDIA Stock Token",
-    symbol: "NVDA",
-    priceChangeRatio: 0.45,
-    autoRestore: true,
-  });
-
-  console.log(
-    JSON.stringify(
-      {
-        objectiveId: objective.id,
-        eventId: result.event.id,
-        executions: result.executions.length,
-        settlement: result.executions[0]?.settlement ?? null,
-        health: result.health.find((h) => h.objectiveId === objective.id)?.state,
-      },
-      null,
-      2
-    )
-  );
-}
-
-main().catch((error) => {
-  if (isAureonError(error)) {
-    console.error(`${error.code}: ${error.message}`);
-  } else {
-    console.error(error);
-  }
-  process.exitCode = 1;
-});
+/**
+ * @fileoverview Controlled market-event rehearsal against the live AUREON API.
+ *
+ * Env:
+ *   AUREON_API_KEY  issued developer key (required)
+ *   AUREON_API_URL  optional (default https://api.aureonlabs.network)
+ *
+ *   pnpm --filter @buildaureon/sdk example:market
+ */
+
+import {
+  createAureonClient,
+  DEFAULT_API_BASE_URL,
+  isAureonError,
+} from "../../src/index.js";
+
+async function main(): Promise<void> {
+  const apiKey = process.env.AUREON_API_KEY?.trim();
+  if (!apiKey) {
+    throw new Error("Set AUREON_API_KEY to an issued developer key.");
+  }
+
+  const aureon = createAureonClient({
+    baseUrl: process.env.AUREON_API_URL?.trim() || DEFAULT_API_BASE_URL,
+    apiKey,
+  });
+
+  const objective = await aureon.createObjective({
+    name: "Maintain 20% Stable Assets",
+    kind: "stable_allocation",
+    targetWeight: 0.2,
+    tolerance: 0.02,
+  });
+
+  const result = await aureon.applyMarketEvent({
+    name: "NVDA Stock Token Rally",
+    description: "Controlled mark appreciation on NVIDIA Stock Token",
+    symbol: "NVDA",
+    priceChangeRatio: 0.45,
+    autoRestore: true,
+  });
+
+  console.log(
+    JSON.stringify(
+      {
+        objectiveId: objective.id,
+        eventId: result.event.id,
+        executions: result.executions.length,
+        settlement: result.executions[0]?.settlement ?? null,
+        health: result.health.find((h) => h.objectiveId === objective.id)?.state,
+      },
+      null,
+      2
+    )
+  );
+}
+
+main().catch((error) => {
+  if (isAureonError(error)) {
+    console.error(`${error.code}: ${error.message}`);
+  } else {
+    console.error(error);
+  }
+  process.exitCode = 1;
+});