diff --git a/doc/connections/CONNECTOR-PLAYBOOK.md b/doc/connections/CONNECTOR-PLAYBOOK.md index 2c05876145..2c954e7090 100644 --- a/doc/connections/CONNECTOR-PLAYBOOK.md +++ b/doc/connections/CONNECTOR-PLAYBOOK.md @@ -4,6 +4,8 @@ This playbook is the repeatable template for adding a vendor to the Apps catalog Use it when Paperclip acts on an external system through a governed connection: a stored credential, a capability catalog, access profiles and policy rules, and audit. Inbound integrations, such as an external client acting on Paperclip, use gateway or webhook guidance instead. +Every connector built with this playbook is a **plane P2** connection — a resource token in the instance vault, acquired via the connect broker, never a sign-in authenticator. Before writing a connector, read [Identity vs. connections](./README.md#identity-vs-connections) for the P1/P2/P3 boundary and the D7 standing rule (sign-in tokens are never reused as resource tokens; id.paperclip.ing never stores resource tokens; no connections hub on the ID service). + ## Output A complete connector proposal produces: diff --git a/doc/connections/FIRST-30-MATRIX.md b/doc/connections/FIRST-30-MATRIX.md index 886ec8c24c..dd5ffbff70 100644 --- a/doc/connections/FIRST-30-MATRIX.md +++ b/doc/connections/FIRST-30-MATRIX.md @@ -9,6 +9,11 @@ review gates for a provider before writing a connector ticket or playbook entry. Source: harvested from [PAP-2432](/PAP/issues/PAP-2432) and made canonical for the [PAP-13211](/PAP/issues/PAP-13211) Apps v2 unification program. +> Every provider here is a **plane P2** connection: a resource token in the +> instance vault, acquired via the connect broker — never a sign-in method. See +> [Identity vs. connections](./README.md#identity-vs-connections) for the P1/P2/P3 +> boundary and the D7 standing rule. + ## Batch Recommendation First implementation batch after the proof providers: diff --git a/doc/connections/README.md b/doc/connections/README.md index 3415f52e13..ae1c76f051 100644 --- a/doc/connections/README.md +++ b/doc/connections/README.md @@ -69,6 +69,59 @@ The agent should not hold a durable provider credential. It should hold a Paperclip run/session token; the server or broker resolves the connection, checks governance, invokes the provider, and writes audit. +## Identity vs. connections + +Signing a user *in* and connecting a *resource* are different planes with +different owners, different token profiles, and different homes. Do not merge +them. This section is the public, connections-side statement of the identity +model so connector implementers inherit the rule without depending on private +identity-service documentation or re-deriving it. + +| Plane | Question | Lives where | Token profile | +| --- | --- | --- | --- | +| **P1. Sign-in methods** | *Who are you?* | `paperclip-id` (id.paperclip.ing → Account) | Minimal-scope provider tokens (`openid email profile`), used once to authenticate, encrypted at rest, never exported | +| **P2. Connections (Apps)** | *What may your agents touch?* | Paperclip App instances (`tool_connections`), acquired via the **connect broker** for hosted + self-hosted | Rich-scope, long-lived resource tokens in the **instance's** encrypted vault; per-agent grants; ask-first on writes | +| **P3. Login with Paperclip** | *Who may authenticate against us?* | `paperclip-id` OIDC provider + DB-backed client registry | Our ES256 ID/access tokens issued *by* us to registered RPs (instances, the broker, future third parties) | + +Everything in `doc/connections/` — the [First-30 matrix](./FIRST-30-MATRIX.md), +the [connector playbook](./CONNECTOR-PLAYBOOK.md), and the connect-broker work — +lives on **plane P2**. It never acquires, stores, or brokers a P1 sign-in token. + +### The standing rule (D7) + +Adopted as a standing rule (decision D7) with the identity-model plan. State it +verbatim in any P2 design so the app-store work cannot drift into merging the +planes: + +> Sign-in tokens are never reused as resource tokens; id.paperclip.ing never +> stores resource tokens; no connections hub on the ID service. + +P2 tokens flow broker → instance vault as pass-through only; the id.paperclip.ing +Account page therefore must **not** grow a "Connections" hub. The reasons to +hold the planes apart (from the plan §3): + +- **Scope discipline.** Sign-in wants the narrowest grant; connections want + deliberately broad ones. One button that does both is how you grant repo + access just to log in. +- **Blast radius.** id.paperclip.ing holding every customer's Vercel/Slack/GitHub + resource tokens would make it the single juiciest target in the fleet; the + broker is intentionally pass-through. +- **Self-hosted symmetry.** Instances own their vaults, so self-hosters don't + depend on our uptime to *use* their own connections. +- **Legibility.** Sign-in and connections answer different user questions, and + every product we benchmarked (Vercel, Railway, GitHub, Google) keeps them on + separate pages with separate names. + +### Naming alignment + +Use the surface-correct name for each plane; they intentionally differ: + +| Surface | Plane | Name to use | +| --- | --- | --- | +| Paperclip App instances | P2 | **"Connections"** | +| id.paperclip.ing Account | P1 | **"Ways to sign in"** | +| id.paperclip.ing admin | P3 | **"OIDC clients"** (until the app store productizes it) | + ## Packaging Rule Default to a **catalog entry** when an integration can be described as metadata: @@ -85,6 +138,8 @@ not own durable tokens. ## Canonical Docs - [Glossary](./GLOSSARY.md) defines product and internal terms. +- [Identity vs. connections](#identity-vs-connections) is the public statement + of the P1/P2/P3 boundary and the D7 standing rule for connections work. - [Security threat model](./SECURITY-THREAT-MODEL.md) harvests the keeper from [PAP-2359](/PAP/issues/PAP-2359) and maps it onto Apps v2. - [First-30 matrix](./FIRST-30-MATRIX.md) harvests the keeper from