> For the complete documentation index, see [llms.txt](https://nytshift.gitbook.io/nytshift-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://nytshift.gitbook.io/nytshift-docs/engineering-guide/03-trust-and-authority.md).

# Trust and authority

[← Architecture](/nytshift-docs/engineering-guide/02-architecture-and-data-flow.md) · [Documentation home](/nytshift-docs/start-here/readme.md) · Next: [Market data →](/nytshift-docs/engineering-guide/04-market-data-and-charting.md)

The security model assumes browsers, model output, provider payloads, wallet extensions, network responses and upstream acknowledgements are untrusted. Trust is constructed from exact identity, freshness, scope, durable state and independent checks.

## Non-negotiable invariants

1. AI may emit typed analysis or a `TradeProposal`; it never signs, submits, retries or cancels.
2. Browser code never contains exchange keys, wallet keys, signer tokens or unrestricted internal capabilities.
3. Execution defaults to `disabled`; mainnet defaults to `false` in every environment example and release gate.
4. Mock data is structurally labeled and rejected by production.
5. Asset identity requires chain ID plus canonical contract or reviewed venue metadata; symbols are insufficient.
6. Unknown execution outcomes are reconciled before any new attempt.
7. Security/risk tests are never weakened to make a release pass.
8. Login, wallet connection, entitlement, policy and execution authority remain separate capabilities.

## Trust-boundary map

```mermaid
flowchart LR
    M[Model/provider subscription] -->|untrusted proposal| MCP[MCP/API boundary]
    U[User browser] -->|session + CSRF + typed JSON| BFF[Web BFF]
    W[Injected wallet] -->|address/chain evidence only| U
    V[Venue/RPC] -->|untrusted external JSON| AD[Strict adapters]
    AD --> BFF
    MCP --> BFF
    BFF -->|normalized evidence| A[AEGIS]
    A -->|verdict, never signature| BFF
    BFF -->|loopback auth + one-use scope| S[Signer]
    S -->|signed exact request| V
    V -->|ACK/events/reads| S
    S -->|durable reconciliation| BFF
```

## Secret placement

| Secret or capability       | Allowed location                                         | Forbidden locations                                                         |
| -------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------- |
| Hyperliquid API-wallet key | Dedicated regular file outside repo; signer process only | Browser, Next.js process, `.env` committed to Git, inline environment value |
| Arcus Ed25519 private key  | Dedicated PEM outside repo; Arcus signer only            | Browser, web process, localStorage, repository                              |
| Signer internal token      | Private service environment on loopback                  | Public config, browser, logs, health DTOs                                   |
| Confirmation secret        | Web/signer private environment                           | Browser source, cookies readable by JS, persisted tickets                   |
| Privy app secret/JWT key   | Server environment                                       | `NEXT_PUBLIC_*`, browser bundle, public health                              |
| MCP one-time credential    | Returned once; digest-only at rest                       | Logs, screenshots, prompt history, public telemetry                         |
| Operator session           | Short-lived HttpOnly SameSite-Strict cookie              | Model tool input, localStorage, signer API                                  |

Repository `.env` files are ignored and never release inputs. The public release builder scrubs secrets and forces disabled execution.

## Browser boundary

* Every page request receives a fresh CSP nonce.
* Scripts use `strict-dynamic`; external fonts are self-hosted.
* Inline handlers, objects and frames are blocked.
* Public venue connect origins are explicit.
* Wallet discovery is EIP-6963/EIP-1193 read-only until the user explicitly requests a chain switch.
* A connected wallet does not grant order, funding, signer or withdrawal authority.

## Customer and operator identity

Customer identity uses Privy access-token verification plus an independent ID-token binding for durable preferences. Operator control uses a separate 15-minute session, same-origin JSON, per-session CSRF and abuse budgets. Neither identity can be inferred from the other.

Production readiness for customer identity additionally requires bounded rehearsal evidence tied to the exact app ID and production origins. Configuration alone is not a ready claim.

## Agent identity

MCP connections and Pro credentials are expiring, revocable and exact-scope. Plaintext tokens are shown once and stored only as server-keyed digests. Every call rechecks durable authorization; the MCP transport session itself is not identity.

Remote MCP remains disabled without independent OAuth 2.1/PKCE, TLS, audience, rotation, abuse and release evidence. Provider access tokens are not collected or passed through.

## Capital boundary

```mermaid
stateDiagram-v2
    [*] --> ReadOnly
    ReadOnly --> Proposed: typed proposal
    Proposed --> Reviewed: fresh evidence + AEGIS allow
    Reviewed --> Confirmed: human or durable testnet policy
    Confirmed --> Attempted: signer consumes one-use claim
    Attempted --> Final: authoritative venue evidence
    Attempted --> Unknown: ambiguous transport/result
    Unknown --> Final: reconcile exact CLOID/client ID
    Unknown --> Blocked: evidence window exhausted
    Final --> [*]
    Blocked --> [*]
```

The `Unknown` state has no retry edge. Any new economic action requires reconciliation or an explicit terminal failure that proves no attempt.

## Review checklist

Before accepting a new capability, ask:

* Who supplies identity?
* What exact resource and account does it bind?
* What is the maximum lifetime?
* Where is plaintext present?
* What survives restart?
* Which upstream evidence can be stale, partial or ambiguous?
* Can a browser/model field influence signing material?
* What proves at-most-once behavior?
* What is the reconciliation identity?
* How is revocation tested?
* What independent evidence keeps mainnet locked?

Normative sources: [threat model](/nytshift-docs/normative-design/threat-model.md), [ADR-001](/nytshift-docs/architecture-decisions/001-ai-cannot-execute.md), [ADR-002](/nytshift-docs/architecture-decisions/002-python-execution-boundary.md) and [ADR-003](/nytshift-docs/architecture-decisions/003-event-reconciliation.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://nytshift.gitbook.io/nytshift-docs/engineering-guide/03-trust-and-authority.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.