mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 20:12:20 +01:00
## Thinking Path > - Paperclip manages AI agents and the environments where they run. > - SSH environments can reach machines through a company Tailscale connection. > - The initial connector requires a managed OAuth app that Tailscale limits to its own tailnet. > - Customers need to connect their own tailnets without registering an app or supplying a key. > - This pull request uses Tailscale's normal device sign-in for new connections. > - Customers approve the Paperclip device and then select their machines in SSH environments. ## Linked Issues or Issue Description **Problem or motivation** The current Tailscale enrollment path cannot serve independent customer tailnets through the documented self-service OAuth app model. It also requires Cloud broker configuration and pilot admission before a customer can start. **Proposed solution** Start a private Tailscale device in the tenant and open its normal sign-in link. Save its encrypted device state before reporting a successful connection. Retain the existing SSH machine selection and agent account behavior. **Alternatives considered** Auth-key entry would require customers to copy a credential. A public OAuth integration still needs a confirmed registration path. Device sign-in uses a documented Tailscale flow without either requirement. See [device authentication](https://tailscale.com/docs/features/tsnet#device-creation-and-authentication) and [OAuth app limitations](https://tailscale.com/docs/features/oauth-apps). **Related PR search** Searched GitHub PRs for `tailscale` and `device sign-in`, and issues for `tailscale`. This follows the merged network connector in [#20617](https://github.com/paperclipai/paperclip/pull/20617) and preserves the SSH agent-account support in [#21248](https://github.com/paperclipai/paperclip/pull/21248). The open [#15648](https://github.com/paperclipai/paperclip/pull/15648) proposes storing an OAuth client and checking its health; this change instead enrolls a device through interactive sign-in so customers do not need an OAuth app. ## What Changed - New connections use device sign-in. Existing connected devices and pending legacy OAuth callbacks remain supported. - Pending sign-ins are bound to their company and initiating user. They have a fixed ten-minute deadline. Device state uses server-owned vault secrets with trusted version and digest checks. - The active Tailscale CLI waits for consent and device approval. Cancellation, expiry, secret deletion, and stale completion cannot restore a cancelled connection. - The connector stays open during sign-in. It provides a link when popups are blocked and shows device approval separately. Progress checks stop on completion, failure, expiry, or unmount. - Shared response types, OpenAPI contracts, SDK source pins, and the API/setup documentation describe the new flow. No database migration or Cloud provider configuration is required. ## Verification - 109 focused tests cover network processes, the real database and encrypted vault, routes, UI, and legacy connection behavior. - Server and UI typechecks pass. - Follow-up `29cf296a597`: reproduced the missing OpenAPI route failure locally. All 70 OpenAPI and Tailscale route tests and server typecheck pass after synchronizing the API contract. - Follow-up `79de05f38b9`: the transient-recovery regression failed before the fix; all 20 connector UI tests and UI typecheck pass after it. The query-error policy check reports no findings. - The public SDK input registry check passes. - [CI attempt 2](https://github.com/paperclipai/paperclip/actions/runs/43535594257/attempts/2) passed on the final head, `29cf296a597e470d432b84767050bc539caa280e`: 57 successful checks, no failures or pending checks. The interrupted canary, E2E shard, and serialized-suite jobs passed on rerun. Greptile is 5/5 on this head with no unresolved review threads. - `pnpm verify --explain` exits 2 because the documentation change selects broad CI coverage. Focused local checks passed; broad CI passed on `29cf296a597e470d432b84767050bc539caa280e`. - Live local qualification on `29cf296a597e470d432b84767050bc539caa280e`: native device sign-in completed with interactive user approval. An isolated Ubuntu 24.04 ARM64 EC2 machine appeared in discovery and passed SSH pairing and workspace probes. The assigned Claude Code agent used a Paperclip-managed subscription, created `hello_world.txt` containing exactly `Hello, world!` plus a newline, posted a completion comment, and marked the task done. An independent read through the private connector verified the bytes, remote user, and hostname. The remote machine had no stored Claude login and no leftover temporary credential directories. - Restarted the local Paperclip server and verified the same Tailscale device identity, online peer discovery, successful SSH probe, and unchanged file without new consent. Temporary public SSH ingress was removed. - Local qualification covers one user tailnet and the final Core revision. Browser UI acceptance, two unrelated tailnets, a hosted restart, and an agent task on the final staging revision are not yet verified. ## Risks - The enrollment method changes. It must pass the live qualification above before broad rollout claims. - Existing encrypted device state and the vault master key must survive a restart or redeploy. Device expiry or removal still requires reconnecting. - The existing one-serving-process-per-instance constraint remains. Concurrent replicas need durable network ownership. - Pending setup uses bounded progress requests and an event-driven CLI with a deadline. It adds no idle database scan. ## Model Used OpenAI GPT-6 Astra (`gpt-6-astra`) through Codex in T3 Code, with xhigh reasoning. Context window size was not exposed by the runtime. No subagents were used. ## Checklist - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] My branch name describes the change and contains no internal ticket or instance details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation - [x] I have considered and documented the risks - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
72 lines
4.2 KiB
Markdown
72 lines
4.2 KiB
Markdown
---
|
|
title: Tailscale Connections
|
|
summary: Connect a company tailnet and select its machines in SSH environments
|
|
---
|
|
|
|
These endpoints require a board operator with instance-admin rights and access
|
|
to the company. Local implicit board access is also accepted. Agent credentials
|
|
cannot manage a Tailscale connection. Browser mutations require a trusted Origin.
|
|
|
|
| Method | Path | Result |
|
|
|--------|------|--------|
|
|
| GET | `/api/companies/{companyId}/tailscale-connections` | Connection metadata |
|
|
| POST | `/api/companies/{companyId}/tailscale-connections` | Start device sign-in |
|
|
| POST | `/api/companies/{companyId}/tailscale-connections/{connectionId}/device-login` | Resume device sign-in and read progress |
|
|
| GET | `/api/companies/{companyId}/tailscale-connections/{connectionId}/devices` | Available machines |
|
|
| POST | `/api/companies/{companyId}/tailscale-connections/{connectionId}/pairing` | Public SSH pairing command |
|
|
| DELETE | `/api/companies/{companyId}/tailscale-connections/{connectionId}` | Disconnected connection metadata |
|
|
|
|
A connection response contains only `id`, `companyId`, `name`, and `status`.
|
|
Status is `pending`, `authorizing`, `connecting`, `connected`, `disconnected`,
|
|
`expired`, or `error`. Responses do not include enrollment tokens, persisted
|
|
node state, or OAuth state digests.
|
|
|
|
To start device sign-in, POST a JSON object with optional `name` and
|
|
`connectionId`. The name defaults to `My tailnet`. No OAuth app, Cloud broker
|
|
enrollment, or pasted auth key is required. An existing connection ID resumes an
|
|
unexpired sign-in or starts a new attempt. Disconnect a connected network before
|
|
replacing it. Pending sign-in is bound to the initiating user and expires after
|
|
ten minutes; progress requests do not extend that deadline.
|
|
|
|
The `201` response contains `connection` and `expiresAt`, plus `authorizationUrl`
|
|
when the sign-in link is ready. Open that link so the user can approve the
|
|
Paperclip device in their tailnet. `needsApproval: true` means a tailnet
|
|
administrator must approve the device. `expiresAt` is null when no sign-in is
|
|
pending. No Cloud handoff is returned.
|
|
|
|
POST to `/{connectionId}/device-login` under the connections path to resume the
|
|
private client and read progress. This endpoint takes no request body and
|
|
returns the same shape with status `200`. Only the user who started the sign-in
|
|
may continue it, with the same instance-admin and company access checks. Both
|
|
responses use `Cache-Control: no-store` and `Referrer-Policy: no-referrer`.
|
|
Stop progress requests when the connection leaves `authorizing` or the deadline
|
|
passes. DELETE the connection to cancel a pending attempt.
|
|
|
|
Machine discovery returns `id`, `name`, `hostname`, `address`, `os`, and `online`
|
|
for each peer. Use the stable `id` when configuring a Tailscale-backed SSH
|
|
environment. The current address is resolved again for execution.
|
|
|
|
An SSH environment with `network: "tailscale"` requires `tailscaleConnectionId`
|
|
and `tailscaleDeviceId`. Saving binds the connector's current credential identity.
|
|
Raw enrollment keys and credential-only configurations are rejected. Runtime
|
|
access checks the connection again after loading the SSH key and after device
|
|
discovery; a disconnected or replaced connection requires fresh setup.
|
|
|
|
To prepare pairing, POST `{ "deviceId": "<stable-device-id>", "port": 22 }`.
|
|
The port defaults to 22. The response contains `privateKeySecretId`, `publicKey`,
|
|
and `command`. Each preparation generates a fresh key pair. Run the command as
|
|
the target SSH user and configure the environment with the returned secret ID.
|
|
The private key never appears in this response.
|
|
|
|
Pending legacy OAuth flows can still return to
|
|
`GET /api/tools/oauth/tailscale/callback` with required `state` and either
|
|
`claim_id` or an authorization `error`. The callback rechecks the initiating
|
|
operator's company access and consumes state once. On success it returns a
|
|
`303` redirect to the company's connector page with `Cache-Control: no-store`
|
|
and `Referrer-Policy: no-referrer`.
|
|
|
|
Disconnect invalidates both pending consent and callbacks already completing.
|
|
It stops the private network client and keeps the connection record. It does
|
|
not remove the target computer from Tailscale. A later authorization can replace
|
|
the saved connection; older callbacks cannot replace that newer authorization.
|