Files
PaperClipAI/doc
11a0ff0205 feat(connections): per-company workload identity issuer with public signing keys (#22083)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents use outside services through connections. The control plane
holds each connection's credentials and makes the calls.
> - Some clouds, such as AWS, do not need stored keys. They trust a
signed token from an identity provider that they can verify against its
public keys.
> - Paperclip has no signing key whose public half it can publish. Agent
identity keys are Ed25519, which AWS does not accept, and the agent's
run receives the private key. Agent run tokens use a shared secret.
> - This pull request gives each company its own signing key and
publishes the public half as a standard OIDC issuer.
> - The benefit is that a connection, such as the planned AWS connector,
can get its own short-lived cloud credentials with no stored cloud keys.
The connection's role in the customer's account sets its permissions.

## Linked Issues or Issue Description

Refs #19414 and #10411. Those pull requests add OIDC *sign-in* to
Paperclip. This pull request is the other direction: Paperclip *issues*
tokens that outside clouds verify.

**Subsystem affected**
Connections (tool access) and the database.

**Problem or motivation**
An AWS connector should not store a long-lived AWS access key. AWS
supports OIDC federation (`AssumeRoleWithWebIdentity`). AWS fetches the
issuer's public keys over HTTPS and checks each token. Paperclip has no
key that it can publish for this, so this method is not available.

**Proposed solution**
Each company gets an ES256 key that Paperclip creates on first use. The
vault master key encrypts the private half. The issuer is
`https://{instance}/oidc/companies/{companyId}`. Paperclip publishes a
discovery document and a JWKS there. Tokens last 5 minutes and have `sub
= connection:{id}`. Only the control plane signs them. The board can see
key state and run planned rotation or emergency rotation. The design is
in `doc/plans/2026-11-17-workload-identity-issuer.md`. The AWS connector
plan that uses it is in
`doc/plans/2026-11-17-aws-connector-and-minted-credentials.md`.

**Alternatives considered**
- Reuse agent identity keys. Rejected: AWS does not accept Ed25519, and
the agent's run receives the private key.
- Derive the key from the master key, with no table. Rejected: the
master key alone would then sign as production. Worktree environments
copy the master key on purpose. A master key rotation would also change
the signing key and break every customer trust.
- Use one issuer for the instance. Rejected: if a customer's role checks
the issuer but not `sub`, any company on a shared instance could assume
that role.

## What Changed

- `packages/db`: new table `company_workload_identity_keys` and
migration `0498`. The migration only creates a new table, so the
previous release keeps working. Partial unique indexes allow one
`active` key and one `next` key per company.
- `server/src/services/workload-identity.ts`: lazy key creation with
concurrent convergence, a private-key cache with a fail-closed key match
check, the discovery document, the JWKS, `signConnectionToken`, and
rotation steps. A key that is no longer active stays published for 24
hours. Paperclip calculates this when it reads the keys, so no
background job is necessary.
- `server/src/routes/workload-identity.ts`: public `GET
/oidc/companies/{companyId}/.well-known/openid-configuration` and `GET
/oidc/companies/{companyId}/jwks.json` (404 until a key exists). Board
`GET /api/companies/{companyId}/workload-identity` and `POST
.../workload-identity/rotation`, with an activity log entry for each
rotation.
- Token issuance writes a tool-access audit event. The event never
contains the token.
- `cli`: worktree seeds exclude the new table in the minimal mode and
the full mode. This is the same as for `agent_identity_keys`, so a
development copy never holds production's signing key.
- Docs: `docs/api/workload-identity.md`, an entry in the API overview,
and the two plan docs.
- No connector uses `signConnectionToken` yet. The AWS connector pull
request will use it.

## Verification

- `cd server && npx vitest run src/__tests__/workload-identity.test.ts`:
8 tests pass. The tests cover these items:
  - The issuer requires https with no port and no loopback host.
  - The endpoints return 404 before a key exists.
  - Six concurrent first uses create one key.
  - The JWKS contains only `kty crv x y kid alg use`.
- A token verifies against the published key and has the expected
claims.
- A company cannot sign for another company's connection, and its keys
do not verify that company's tokens.
  - Signing stops when the public address is not usable or has changed.
  - Two-step rotation and emergency rotation work.
- Board-only access is enforced, and each rotation writes an activity
log entry.
- Red/green: I put back a JWK that leaks `d` and removed the company
check on the connection. Three tests failed. I restored the code, and
all 8 tests passed.
- `cd cli && npx vitest run src/__tests__/worktree.test.ts`: 63 tests
pass.
- `npx tsc --noEmit` passes for `packages/db`, `server` and `cli`.
- I started this branch on a real dev server. Before a key existed, the
public routes returned JSON 404 (not the UI page). After an emergency
rotation from the board route, the JWKS returned one public P-256 key.
On the http dev instance, discovery stayed 404 and the board route
reported `not_https`.
- `pnpm verify` exited 2 because of the migration. The required CI gates
supply the broad coverage.
- Not run: a real AWS `AssumeRoleWithWebIdentity` call. That needs a
public HTTPS instance. It is the first step of the AWS connector work
and will run against staging.

## Risks

- The migration is low risk. It creates a new table with no backfill,
and the compatibility checker classifies it as compatible with the
running release.
- The public routes are unauthenticated. They show only public keys,
return 404 for companies without a key, and use random company UUIDs.
Each request is one small indexed read.
- The issuer URL shape is permanent after customers trust it. A change
to the instance's public address breaks those trusts until the customer
updates the identity provider. `signConnectionToken` stops on that
mismatch when the caller supplies the recorded issuer.
- Anyone who holds the production database and the master key could sign
for that instance's companies. That is the same exposure as every other
vault secret.
- Edge routing on Paperclip Cloud must pass `/oidc/...` to the stack. I
will confirm this on staging with the AWS connector work.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, file edits, web fetch of AWS documentation, a local dev server).

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived 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 to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-11-17 23:33:47 -06:00
..
2026-02-16 14:25:00 -06:00