Skip to content

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.html
deleted file mode 100644
index 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.pdf
deleted file mode 100644
index 42c604f29..000000000
Binary files a/docs/cloud/t3-code-connect-auth-flow.pdf and /dev/null differ