mirror of
https://github.com/paperclipai/paperclip
synced 2026-04-27 10:07:22 +02:00
145 lines
4.7 KiB
Markdown
145 lines
4.7 KiB
Markdown
# Deployment Modes
|
|
|
|
Status: Canonical deployment and auth mode model
|
|
Date: 2026-02-23
|
|
|
|
## 1. Purpose
|
|
|
|
Paperclip supports two runtime modes:
|
|
|
|
1. `local_trusted`
|
|
2. `authenticated`
|
|
|
|
`authenticated` supports two exposure policies:
|
|
|
|
1. `private`
|
|
2. `public`
|
|
|
|
This keeps one authenticated auth stack while still separating low-friction private-network defaults from internet-facing hardening requirements.
|
|
|
|
Paperclip now treats **bind** as a separate concern from auth:
|
|
|
|
- auth model: `local_trusted` vs `authenticated`, plus `private/public`
|
|
- reachability model: `server.bind = loopback | lan | tailnet | custom`
|
|
|
|
## 2. Canonical Model
|
|
|
|
| Runtime Mode | Exposure | Human auth | Primary use |
|
|
|---|---|---|---|
|
|
| `local_trusted` | n/a | No login required | Single-operator local machine workflow |
|
|
| `authenticated` | `private` | Login required | Private-network access (for example Tailscale/VPN/LAN) |
|
|
| `authenticated` | `public` | Login required | Internet-facing/cloud deployment |
|
|
|
|
## Reachability Model
|
|
|
|
| Bind | Meaning | Typical use |
|
|
|---|---|---|
|
|
| `loopback` | Listen on localhost only | default local usage, reverse-proxy deployments |
|
|
| `lan` | Listen on all interfaces (`0.0.0.0`) | LAN/VPN/private-network access |
|
|
| `tailnet` | Listen on a detected Tailscale IP | Tailscale-only access |
|
|
| `custom` | Listen on an explicit host/IP | advanced interface-specific setups |
|
|
|
|
## 3. Security Policy
|
|
|
|
## `local_trusted`
|
|
|
|
- loopback-only host binding
|
|
- no human login flow
|
|
- optimized for fastest local startup
|
|
|
|
## `authenticated + private`
|
|
|
|
- login required
|
|
- low-friction URL handling (`auto` base URL mode)
|
|
- private-host trust policy required
|
|
- bind can be `loopback`, `lan`, `tailnet`, or `custom`
|
|
|
|
## `authenticated + public`
|
|
|
|
- login required
|
|
- explicit public URL required
|
|
- stricter deployment checks and failures in doctor
|
|
- recommended bind is `loopback` behind a reverse proxy; direct `lan/custom` is advanced
|
|
|
|
## 4. Onboarding UX Contract
|
|
|
|
Default onboarding remains interactive and flagless:
|
|
|
|
```sh
|
|
pnpm paperclipai onboard
|
|
```
|
|
|
|
Server prompt behavior:
|
|
|
|
1. quickstart `--yes` defaults to `server.bind=loopback` and therefore `local_trusted/private`
|
|
2. advanced server setup asks reachability first:
|
|
- `Trusted local` → `bind=loopback`, `local_trusted/private`
|
|
- `Private network` → `bind=lan`, `authenticated/private`
|
|
- `Tailnet` → `bind=tailnet`, `authenticated/private`
|
|
- `Custom` → manual mode/exposure/host entry
|
|
3. raw host entry is only required for the `Custom` path
|
|
4. explicit public URL is only required for `authenticated + public`
|
|
|
|
Examples:
|
|
|
|
```sh
|
|
pnpm paperclipai onboard --yes
|
|
pnpm paperclipai onboard --yes --bind lan
|
|
pnpm paperclipai run --bind tailnet
|
|
```
|
|
|
|
`configure --section server` follows the same interactive behavior.
|
|
|
|
## 5. Doctor UX Contract
|
|
|
|
Default doctor remains flagless:
|
|
|
|
```sh
|
|
pnpm paperclipai doctor
|
|
```
|
|
|
|
Doctor reads configured mode/exposure and applies mode-aware checks. Optional override flags are secondary.
|
|
|
|
## 6. Board/User Integration Contract
|
|
|
|
Board identity must be represented by a real DB user principal for user-based features to work consistently.
|
|
|
|
Required integration points:
|
|
|
|
- real user row in `authUsers` for Board identity
|
|
- `instance_user_roles` entry for Board admin authority
|
|
- `company_memberships` integration for user-level task assignment and access
|
|
|
|
This is required because user assignment paths validate active membership for `assigneeUserId`.
|
|
|
|
## 7. Local Trusted -> Authenticated Claim Flow
|
|
|
|
When running `authenticated` mode, if the only instance admin is `local-board`, Paperclip emits a startup warning with a one-time high-entropy claim URL.
|
|
|
|
- URL format: `/board-claim/<token>?code=<code>`
|
|
- intended use: signed-in human claims board ownership
|
|
- claim action:
|
|
- promotes current signed-in user to `instance_admin`
|
|
- demotes `local-board` admin role
|
|
- ensures active owner membership for the claiming user across existing companies
|
|
|
|
This prevents lockout when a user migrates from long-running local trusted usage to authenticated mode.
|
|
|
|
## 8. Current Code Reality (As Of 2026-02-23)
|
|
|
|
- runtime values are `local_trusted | authenticated`
|
|
- `authenticated` uses Better Auth sessions and bootstrap invite flow
|
|
- `local_trusted` ensures a real local Board user principal in `authUsers` with `instance_user_roles` admin access
|
|
- company creation ensures creator membership in `company_memberships` so user assignment/access flows remain consistent
|
|
|
|
## 9. Naming and Compatibility Policy
|
|
|
|
- canonical naming is `local_trusted` and `authenticated` with `private/public` exposure
|
|
- no long-term compatibility alias layer for discarded naming variants
|
|
|
|
## 10. Relationship to Other Docs
|
|
|
|
- implementation plan: `doc/plans/deployment-auth-mode-consolidation.md`
|
|
- V1 contract: `doc/SPEC-implementation.md`
|
|
- operator workflows: `doc/DEVELOPING.md` and `doc/CLI.md`
|