Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.
rm test artifacts
Julius Marminge3a0623f1cd78
diff --git a/docs/cloud/t3-code-connect-auth-flow-3-page.html b/docs/cloud/t3-code-connect-auth-flow-3-page.htmldeleted file mode 100644index 9fe7bd590..000000000--- a/docs/cloud/t3-code-connect-auth-flow-3-page.html+++ /dev/null@@ -1,592 +0,0 @@-<!doctype html>-<html lang="en">- <head>- <meta charset="utf-8" />- <meta name="viewport" content="width=device-width, initial-scale=1" />- <title>T3 Connect Architecture Brief</title>- <style>- :root {- --ink: #171717;- --muted: #62646b;- --line: #d8d8dd;- --paper: #f5f5f2;- --blue: #1457d9;- --green: #1d7d4d;- --amber: #a65f00;- }- * {- box-sizing: border-box;- }- @page {- size: Letter;- margin: 0;- }- body {- margin: 0;- color: var(--ink);- background: #ddd;- font-family:- ui-sans-serif,- -apple-system,- BlinkMacSystemFont,- "Segoe UI",- sans-serif;- line-height: 1.34;- }- .page {- position: relative;- width: 8.5in;- height: 11in;- margin: 20px auto;- padding: 0.47in 0.52in 0.42in;- overflow: hidden;- background:- linear-gradient(90deg, rgba(0, 0, 0, 0.028) 1px, transparent 1px),- linear-gradient(rgba(0, 0, 0, 0.028) 1px, transparent 1px), var(--paper);- background-size: 25px 25px;- break-after: page;- }- .page:last-child {- break-after: auto;- }- .eyebrow {- color: var(--blue);- font-size: 9px;- font-weight: 800;- letter-spacing: 0.1em;- text-transform: uppercase;- }- h1 {- max-width: 6.9in;- margin: 7px 0 10px;- font-size: 35px;- line-height: 0.98;- }- h2 {- margin: 0 0 8px;- font-size: 19px;- line-height: 1.08;- }- h3 {- margin: 0 0 4px;- font-size: 12px;- }- p {- margin: 0 0 7px;- }- ul {- margin: 5px 0 0;- padding-left: 17px;- }- li + li {- margin-top: 3px;- }- code {- border-radius: 3px;- background: #ecece8;- padding: 1px 3px;- font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;- font-size: 0.9em;- }- .lede {- max-width: 7.1in;- color: var(--muted);- font-size: 12px;- }- .rule {- height: 2px;- margin: 14px 0;- background: var(--ink);- }- .grid {- display: grid;- grid-template-columns: repeat(12, 1fr);- gap: 10px;- }- .panel {- grid-column: span 12;- border: 1px solid var(--line);- border-radius: 7px;- background: rgba(255, 255, 255, 0.94);- padding: 12px;- font-size: 10px;- }- .half {- grid-column: span 6;- }- .third {- grid-column: span 4;- }- .callout {- margin-top: 8px;- border-left: 4px solid var(--blue);- background: #eef4ff;- padding: 8px 9px;- font-size: 10px;- }- .warning {- border-left-color: var(--amber);- background: #fff6e6;- }- .topology {- display: grid;- grid-template-columns: 1.1fr 34px 1.1fr 34px 1.1fr;- align-items: center;- gap: 5px;- margin-top: 8px;- }- .node {- min-height: 58px;- border: 1px solid var(--line);- border-top: 4px solid var(--blue);- border-radius: 6px;- background: white;- padding: 8px;- text-align: center;- font-size: 9px;- }- .node.green {- border-top-color: var(--green);- }- .arrow {- color: var(--muted);- text-align: center;- font-size: 22px;- }- .flow {- display: grid;- grid-template-columns: repeat(4, 1fr);- gap: 7px;- margin-top: 8px;- }- .step {- position: relative;- min-height: 80px;- border: 1px solid var(--line);- border-left: 4px solid var(--green);- border-radius: 6px;- background: white;- padding: 8px;- font-size: 9px;- }- .step b {- display: block;- margin-bottom: 3px;- font-size: 10px;- }- table {- width: 100%;- border-collapse: collapse;- font-size: 8.7px;- }- th,- td {- border-bottom: 1px solid var(--line);- padding: 5px 6px;- text-align: left;- vertical-align: top;- }- th {- color: var(--muted);- font-size: 8px;- letter-spacing: 0.05em;- text-transform: uppercase;- }- .footer {- position: absolute;- right: 0.52in;- bottom: 0.18in;- color: var(--muted);- font-size: 8px;- }- @media print {- body {- background: none;- }- .page {- margin: 0;- }- }- </style>- </head>- <body>- <section class="page">- <div class="eyebrow">Architecture brief · page 1 of 3</div>- <h1>T3 Connect Control Plane and Managed Endpoint Flow</h1>- <p class="lede">- T3 Connect links a locally authorized T3 environment to a signed-in cloud user, provisions a- managed HTTPS/WSS endpoint, and brokers proof-bound remote connections. The environment- remains the access authority; the relay coordinates identity, endpoint lifecycle, and- notifications.- </p>- <div class="rule"></div>-- <div class="grid">- <article class="panel half">- <h2>Security Invariant</h2>- <p>Cloud identity alone is not an environment login. Remote access requires:</p>- <ul>- <li>a Clerk-authenticated T3 Connect user;</li>- <li>an active user/environment relay link;</li>- <li>a DPoP private key held by the remote client;</li>- <li>a relay-signed mint request accepted locally; and</li>- <li>an environment token bound to the client's DPoP key.</li>- </ul>- <div class="callout">- The relay cannot mint an environment access token by itself. The local environment- issues the bootstrap credential and final access token.- </div>- </article>- <article class="panel half">- <h2>Trust Boundaries</h2>- <ul>- <li><b>Clerk:</b> user identity and OAuth/PKCE.</li>- <li><b>Relay Worker:</b> links, endpoint allocations, proofs, and notifications.</li>- <li><b>Environment:</b> local sessions, signing keys, and access tokens.</li>- <li><b>Relay client:</b> exposes only the validated loopback HTTP server.</li>- <li><b>Remote client:</b> retains the DPoP private key and environment token.</li>- </ul>- <div class="callout warning">- The relay remains a trusted mint broker because it holds the cloud-mint signing key.- DPoP limits credential reuse but does not neutralize compromise of that authority.- </div>- </article>-- <article class="panel">- <h2>Current Topology</h2>- <div class="topology">- <div class="node">- <h3>Clients</h3>- Desktop web UI<br />Mobile app<br />Headless CLI<br /><br />- <b>Clerk bearer / relay DPoP</b>- </div>- <div class="arrow">→</div>- <div class="node">- <h3>T3 Code Relay</h3>- Cloudflare Worker<br />Hyperdrive + Postgres<br />Tunnel/DNS APIs<br />APNs queue- </div>- <div class="arrow">→</div>- <div class="node green">- <h3>Linked Environment</h3>- Managed HTTPS/WSS endpoint<br />Relay client<br />Loopback server<br />Local secrets- </div>- </div>- <div class="callout">- Steady-state HTTP and WebSocket traffic goes directly from the remote client through the- managed endpoint. The relay handles sparse health and bootstrap requests, not the active- session data path.- </div>- </article>-- <article class="panel">- <h2>Authentication Boundaries</h2>- <table>- <thead>- <tr>- <th>Boundary</th>- <th>Authentication</th>- <th>Purpose</th>- </tr>- </thead>- <tbody>- <tr>- <td>Client → relay link management</td>- <td>Clerk bearer / CLI OAuth</td>- <td>Create, list, or remove links.</td>- </tr>- <tr>- <td>Client → protected relay APIs</td>- <td>Relay DPoP token + proof</td>- <td>Status, connect, and mobile registration.</td>- </tr>- <tr>- <td>Relay → environment</td>- <td>Short-lived relay-signed JWT</td>- <td>Signed health and credential-mint requests.</td>- </tr>- <tr>- <td>Client → environment</td>- <td>Environment token + DPoP</td>- <td>Normal HTTPS APIs and WSS ticket issuance.</td>- </tr>- <tr>- <td>Environment → relay</td>- <td>Environment bearer + signed proof</td>- <td>Publish redacted agent activity.</td>- </tr>- </tbody>- </table>- </article>- </div>- <div class="footer">T3 Connect Architecture Brief · 1</div>- </section>-- <section class="page">- <div class="eyebrow">Core workflows · page 2 of 3</div>- <h1>Link, Bootstrap, and Operate</h1>- <p class="lede">- Every workflow preserves local authority while making cloud coordination retry-safe and- suitable for desktop, mobile, and headless use.- </p>- <div class="rule"></div>-- <div class="grid">- <article class="panel">- <h2>1. Link a Local Environment</h2>- <div class="flow">- <div class="step">- <b>Authenticate</b>Desktop/mobile uses a Clerk bearer. CLI uses browser PKCE and- persists desired link state.- </div>- <div class="step">- <b>Prove locally</b>Relay issues a short-lived challenge. The local environment- validates loopback origin and signs it.- </div>- <div class="step">- <b>Reconcile</b>Relay verifies proof and capabilities, then creates or reuses the- tunnel, ingress, and CNAME.- </div>- <div class="step">- <b>Activate</b>Relay returns endpoint config and connector token. Environment persists- config and starts the relay client.- </div>- </div>- <div class="callout">- The local proof endpoint requires <code>relay:write</code>, rejects forwarded authority- headers, and atomically persists the environment key pair.- </div>- </article>-- <article class="panel">- <h2>2. Remote Connection Bootstrap</h2>- <div class="flow">- <div class="step">- <b>Proof key</b>Client creates a DPoP key and exchanges its Clerk JWT for a relay DPoP- access token.- </div>- <div class="step">- <b>Mint request</b>Client calls connect. Relay sends an audience-bound, short-lived- signed proof to the managed endpoint.- </div>- <div class="step">- <b>Local issue</b>Environment validates user, scope, lifetime, nonce, and DPoP- thumbprint, then returns a signed bootstrap credential.- </div>- <div class="step">- <b>Direct session</b>Client redeems locally for an environment token, gets a one-time- WSS ticket, and opens the WebSocket.- </div>- </div>- <div class="callout">- The relay validates the environment response signature, nonce, endpoint, and DPoP- binding before returning bootstrap data to the client.- </div>- </article>-- <article class="panel half">- <h2>Managed Endpoint Lifecycle</h2>- <ol>- <li>- Reserve deterministic hostname and tunnel name for- <code>(userId, environmentId)</code>.- </li>- <li>- Reuse or create the named tunnel; rewrite ingress to the validated loopback origin.- </li>- <li>- Reconcile CNAME records and remove duplicates; recover safely from create conflicts.- </li>- <li>Mark ready only after resource IDs and namespace checks are persisted.</li>- </ol>- </article>- <article class="panel half">- <h2>Unlink Cleanup</h2>- <ul>- <li>Delete managed DNS and tunnel resources.</li>- <li>Remove the allocation and revoke the user link.</li>- <li>Revoke publication credentials after the final active link disappears.</li>- <li>Stop the local relay client and clear persisted relay configuration.</li>- <li>Retain checkpoints when teardown fails so cleanup can be retried.</li>- </ul>- </article>-- <article class="panel">- <h2>3. Agent Activity Notifications</h2>- <div class="flow">- <div class="step">- <b>Project</b>Environment creates a narrow publishable thread state and redacts/caps- failure details.- </div>- <div class="step">- <b>Sign</b>Environment posts with its bearer credential and a per-state signed proof.- </div>- <div class="step">- <b>Persist</b>Relay checks credential, signature, scope, expiry, and nonce, then- stores current state.- </div>- <div class="step">- <b>Deliver</b>Queue workers send push notifications or Live Activity updates through- APNs.- </div>- </div>- </article>- </div>- <div class="footer">T3 Connect Architecture Brief · 2</div>- </section>-- <section class="page">- <div class="eyebrow">Controls and operations · page 3 of 3</div>- <h1>Hardening and Deployment Contract</h1>- <p class="lede">- The design constrains tunnel origins, proof audiences, egress destinations, redirects,- credential exposure, and teardown behavior.- </p>- <div class="rule"></div>-- <div class="grid">- <article class="panel">- <h2>SSRF and Tunnel Controls</h2>- <table>- <thead>- <tr>- <th>Risk</th>- <th>Implemented control</th>- </tr>- </thead>- <tbody>- <tr>- <td>Arbitrary tunnel upstream</td>- <td>Both sides accept managed origins only for loopback hosts and valid ports.</td>- </tr>- <tr>- <td>Forwarded-origin confusion</td>- <td>- Link proof requires the exact loopback URL and rejects forwarded host/protocol- headers.- </td>- </tr>- <tr>- <td>Stored endpoint replacement</td>- <td>- Status/connect resolve ready allocations from Postgres and require the managed DNS- namespace.- </td>- </tr>- <tr>- <td>Redirected relay egress</td>- <td>Relay health and mint requests use manual redirect handling.</td>- </tr>- <tr>- <td>Impersonated tunnel backend</td>- <td>Relay verifies signed environment responses, nonce, and request binding.</td>- </tr>- <tr>- <td>Stolen access token replay</td>- <td>Relay and environment tokens require DPoP proofs and replay guards.</td>- </tr>- <tr>- <td>Connector token exposure</td>- <td>- Relay client is spawned without a shell and receives the token in- <code>TUNNEL_TOKEN</code>.- </td>- </tr>- </tbody>- </table>- </article>-- <article class="panel half">- <h2>Credential Ownership</h2>- <ul>- <li>Environment Ed25519 private key stays local.</li>- <li>- Cloud-mint private key stays in hosted relay config; only its public key is installed- locally.- </li>- <li>- Relay environment bearer is hashed in Postgres and stored plaintext only locally.- </li>- <li>Remote DPoP private keys and environment access tokens remain client-side.</li>- <li>WebSocket tickets are short-lived and one-time.</li>- </ul>- </article>- <article class="panel half">- <h2>Operational Profile</h2>- <ul>- <li>One named tunnel and DNS record per active user/environment allocation.</li>- <li>HTTPS request/response and WSS only; no arbitrary TCP exposure.</li>- <li>Relay traffic is limited to health and bootstrap control calls.</li>- <li>- Active sessions are interactive and WebSocket-heavy; inactive links are nearly idle.- </li>- <li>- Dedicated registrable tunnel domain and Public Suffix List entry are required before- broad untrusted use.- </li>- </ul>- </article>-- <article class="panel">- <h2>Deployment and Runtime</h2>- <table>- <thead>- <tr>- <th>Layer</th>- <th>Contract</th>- </tr>- </thead>- <tbody>- <tr>- <td>Relay</td>- <td>- Cloudflare Worker, tunnel/DNS bindings, Hyperdrive, PlanetScale Postgres, APNs- queue + DLQ, replay-row pruning cron, and Axiom OTLP traces.- </td>- </tr>- <tr>- <td>Environment</td>- <td>- Loopback server, atomic secret store, relay-client lifecycle, signed health/mint- responses, OAuth exchange, and WebSocket tickets.- </td>- </tr>- <tr>- <td>Clients</td>- <td>- Secure relay URL, Clerk configuration, DPoP key management, environment token- storage, and direct managed-endpoint traffic.- </td>- </tr>- </tbody>- </table>- </article>-- <article class="panel">- <h2>Release Gate</h2>- <div class="grid">- <div class="third">- <h3>Identity</h3>- Keep private signing keys in their owning trust domain. Validate issuer, audience,- scope, expiry, nonce, and proof-key binding.- </div>- <div class="third">- <h3>Network</h3>- Permit loopback tunnel origins only. Resolve relay egress from ready allocations and- disable redirects.- </div>- <div class="third">- <h3>Lifecycle</h3>- Make provisioning idempotent, preserve failed-cleanup checkpoints, and revoke shared- credentials only after the final link disappears.- </div>- </div>- <div class="callout warning">- Standards basis: RFC 8252 for native-app OAuth, RFC 8693 for token exchange, and RFC- 9449 for DPoP proof of possession.- </div>- </article>- </div>- <div class="footer">T3 Connect Architecture Brief · 3</div>- </section>- </body>-</html>diff --git a/docs/cloud/t3-code-connect-auth-flow.pdf b/docs/cloud/t3-code-connect-auth-flow.pdfdeleted file mode 100644index 42c604f29..000000000Binary files a/docs/cloud/t3-code-connect-auth-flow.pdf and /dev/null differ