mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-20 09:50:48 +01:00
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>
This commit is contained in:
17 files changed
+3703
-7
No files matched your search
@@ -118,6 +118,7 @@ const apiPrefixes: Record<string, string> = {
|
||||
"tool-gateway.ts": "/api",
|
||||
"user-profiles.ts": "/api",
|
||||
"workspace-preferences.ts": "/api",
|
||||
"workload-identity.ts": "/api",
|
||||
};
|
||||
|
||||
const ROUTE_LITERAL_PATTERN =
|
||||
@@ -213,6 +214,7 @@ function normalizeExpressPath(routePath: string) {
|
||||
|
||||
function resolveMountedPath(file: string, prefix: string, routePath: string) {
|
||||
if (file === "connection-event-wake.ts") return routePath;
|
||||
if (file === "workload-identity.ts" && routePath.startsWith("/oidc/")) return routePath;
|
||||
if (file === "public-mcp.ts" && (routePath.startsWith("/mcp/oauth/") || routePath.startsWith("/.well-known/"))) return routePath;
|
||||
if (
|
||||
(file === "chat-channels.ts" || file === "email.ts") &&
|
||||
|
||||
@@ -0,0 +1,356 @@
|
||||
import { createPublicKey, randomUUID, verify } from "node:crypto";
|
||||
import { mkdtemp, rm } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
import express from "express";
|
||||
import request from "supertest";
|
||||
import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
|
||||
import { and, eq } from "drizzle-orm";
|
||||
import {
|
||||
activityLog,
|
||||
closeRegisteredClients,
|
||||
companies,
|
||||
companyWorkloadIdentityKeys,
|
||||
createDb,
|
||||
toolAccessAuditEvents,
|
||||
toolApplications,
|
||||
toolConnections,
|
||||
type Db,
|
||||
} from "@paperclipai/db";
|
||||
import { generateClientKeyPair } from "../services/tool-access/oauth/client-credentials.js";
|
||||
import { localEncryptedProvider } from "../secrets/local-encrypted-provider.js";
|
||||
import { startEmbeddedPostgresTestDatabase } from "./helpers/embedded-postgres.js";
|
||||
import { resolveExternalTestDatabaseUrl } from "./helpers/external-test-database.js";
|
||||
import { createApp } from "../app.js";
|
||||
import { createLocalDiskStorageProvider } from "../storage/local-disk-provider.js";
|
||||
import { createStorageService } from "../storage/service.js";
|
||||
import { errorHandler } from "../middleware/error-handler.js";
|
||||
import { workloadIdentityPublicRoutes, workloadIdentityRoutes } from "../routes/workload-identity.js";
|
||||
import {
|
||||
resetWorkloadIdentityKeyCacheForTests,
|
||||
setWorkloadIdentityConfiguredPublicOrigin,
|
||||
WORKLOAD_IDENTITY_PUBLISH_BEFORE_USE_MS,
|
||||
WORKLOAD_IDENTITY_RETIRING_GRACE_MS,
|
||||
workloadIdentityIssuerOrigin,
|
||||
workloadIdentityService,
|
||||
} from "../services/workload-identity.js";
|
||||
|
||||
const ORIGIN = "https://acme.paperclip.app";
|
||||
const actor = { actorType: "user" as const, actorId: "board-user" };
|
||||
const externalDatabase = resolveExternalTestDatabaseUrl("PAPERCLIP_WORKLOAD_IDENTITY_TEST_DATABASE_URL");
|
||||
|
||||
function decode(token: string) {
|
||||
const [header, claims, signature] = token.split(".");
|
||||
return {
|
||||
header: JSON.parse(Buffer.from(header!, "base64url").toString("utf8")),
|
||||
claims: JSON.parse(Buffer.from(claims!, "base64url").toString("utf8")),
|
||||
signingInput: `${header}.${claims}`,
|
||||
signature: Buffer.from(signature!, "base64url"),
|
||||
};
|
||||
}
|
||||
|
||||
/** What AWS does: find the key by `kid` in the published set and check the ES256 signature. */
|
||||
function verifiesAgainst(token: string, keys: Array<Record<string, unknown>>): boolean {
|
||||
const { header, signingInput, signature } = decode(token);
|
||||
const jwk = keys.find((key) => key.kid === header.kid);
|
||||
if (!jwk) return false;
|
||||
return verify("sha256", Buffer.from(signingInput),
|
||||
{ key: createPublicKey({ key: jwk as never, format: "jwk" }), dsaEncoding: "ieee-p1363" }, signature);
|
||||
}
|
||||
|
||||
describe("company workload identity issuer", () => {
|
||||
let db: Db;
|
||||
let database: { connectionString: string; cleanup: () => Promise<void> };
|
||||
let directory: string;
|
||||
let clock: Date;
|
||||
const service = () => workloadIdentityService(db, { now: () => clock });
|
||||
|
||||
async function company() {
|
||||
const id = randomUUID();
|
||||
await db.insert(companies).values({
|
||||
id, name: `Identity ${id.slice(0, 6)}`, issuePrefix: `W${id.slice(0, 4).toUpperCase()}`,
|
||||
defaultResponsibleUserId: "workload-identity-owner",
|
||||
});
|
||||
return id;
|
||||
}
|
||||
|
||||
async function connection(companyId: string, state: { status?: "draft" | "active" | "disabled"; enabled?: boolean } = {}) {
|
||||
const [application] = await db.insert(toolApplications).values({
|
||||
companyId, applicationKey: `aws-${randomUUID()}`, name: `AWS ${randomUUID().slice(0, 8)}`, type: "mcp_http", status: "active",
|
||||
}).returning();
|
||||
const [row] = await db.insert(toolConnections).values({
|
||||
companyId, applicationId: application!.id, name: `AWS ${randomUUID().slice(0, 6)}`,
|
||||
uid: `aws-${randomUUID()}`, connectionKind: "managed", ownership: "customer",
|
||||
transport: "mcp_remote", authKind: "oauth", credentialPolicy: "shared",
|
||||
status: state.status ?? "active", enabled: state.enabled ?? true,
|
||||
}).returning();
|
||||
return row!.id;
|
||||
}
|
||||
|
||||
beforeAll(async () => {
|
||||
directory = await mkdtemp(join(tmpdir(), "paperclip-workload-identity-"));
|
||||
vi.stubEnv("PAPERCLIP_HOME", directory);
|
||||
vi.stubEnv("PAPERCLIP_SECRETS_MASTER_KEY", "");
|
||||
vi.stubEnv("PAPERCLIP_SECRETS_MASTER_KEY_FILE", join(directory, "master.key"));
|
||||
vi.stubEnv("PAPERCLIP_PUBLIC_URL", ORIGIN);
|
||||
database = externalDatabase
|
||||
? { connectionString: externalDatabase, cleanup: () => closeRegisteredClients(externalDatabase) }
|
||||
: await startEmbeddedPostgresTestDatabase("paperclip-workload-identity-");
|
||||
db = createDb(database.connectionString);
|
||||
}, 120_000);
|
||||
|
||||
afterAll(async () => {
|
||||
await database?.cleanup();
|
||||
vi.unstubAllEnvs();
|
||||
await rm(directory, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
beforeEach(() => {
|
||||
clock = new Date("2026-11-17T12:00:00.000Z");
|
||||
resetWorkloadIdentityKeyCacheForTests();
|
||||
});
|
||||
|
||||
it("only offers an issuer on a public https address AWS can reach", () => {
|
||||
expect(workloadIdentityIssuerOrigin(ORIGIN)).toEqual({ available: true, origin: ORIGIN });
|
||||
expect(workloadIdentityIssuerOrigin(null)).toEqual({ available: false, reason: "no_public_url" });
|
||||
expect(workloadIdentityIssuerOrigin("http://acme.example.com")).toEqual({ available: false, reason: "not_https" });
|
||||
expect(workloadIdentityIssuerOrigin("https://acme.example.com:8443")).toEqual({ available: false, reason: "has_port" });
|
||||
expect(workloadIdentityIssuerOrigin("https://localhost")).toEqual({ available: false, reason: "loopback" });
|
||||
expect(workloadIdentityIssuerOrigin("https://127.0.0.1")).toEqual({ available: false, reason: "loopback" });
|
||||
});
|
||||
|
||||
it("falls back to the configured auth address when no public URL variable is set", () => {
|
||||
vi.stubEnv("PAPERCLIP_PUBLIC_URL", "");
|
||||
vi.stubEnv("PAPERCLIP_AUTH_PUBLIC_BASE_URL", "");
|
||||
vi.stubEnv("PAPERCLIP_API_URL", "");
|
||||
try {
|
||||
setWorkloadIdentityConfiguredPublicOrigin(null);
|
||||
expect(workloadIdentityIssuerOrigin()).toEqual({ available: false, reason: "no_public_url" });
|
||||
setWorkloadIdentityConfiguredPublicOrigin("https://paperclip.example.com/");
|
||||
expect(workloadIdentityIssuerOrigin()).toEqual({ available: true, origin: "https://paperclip.example.com" });
|
||||
vi.stubEnv("PAPERCLIP_PUBLIC_URL", ORIGIN);
|
||||
expect(workloadIdentityIssuerOrigin()).toEqual({ available: true, origin: ORIGIN });
|
||||
} finally {
|
||||
setWorkloadIdentityConfiguredPublicOrigin(null);
|
||||
vi.stubEnv("PAPERCLIP_PUBLIC_URL", ORIGIN);
|
||||
}
|
||||
});
|
||||
|
||||
it("publishes nothing until a company uses it, then converges on one key", async () => {
|
||||
const companyId = await company();
|
||||
const app = express().use(workloadIdentityPublicRoutes(db));
|
||||
await request(app).get(`/oidc/companies/${companyId}/jwks.json`).expect(404);
|
||||
await request(app).get(`/oidc/companies/${companyId}/.well-known/openid-configuration`).expect(404);
|
||||
await request(app).get("/oidc/companies/not-a-uuid/jwks.json").expect(404);
|
||||
expect(await db.select().from(companyWorkloadIdentityKeys)
|
||||
.where(eq(companyWorkloadIdentityKeys.companyId, companyId))).toHaveLength(0);
|
||||
|
||||
const keys = await Promise.all(Array.from({ length: 6 }, () => service().ensureActiveKey(companyId)));
|
||||
expect(new Set(keys.map((key) => key.keyId)).size).toBe(1);
|
||||
|
||||
const discovery = await request(app).get(`/oidc/companies/${companyId}/.well-known/openid-configuration`).expect(200);
|
||||
const issuer = `${ORIGIN}/oidc/companies/${companyId}`;
|
||||
expect(discovery.body).toMatchObject({
|
||||
issuer, jwks_uri: `${issuer}/jwks.json`, id_token_signing_alg_values_supported: ["ES256"],
|
||||
response_types_supported: ["id_token"], subject_types_supported: ["public"],
|
||||
});
|
||||
expect(discovery.headers["cache-control"]).toBe("public, max-age=300");
|
||||
const jwks = await request(app).get(`/oidc/companies/${companyId}/jwks.json`).expect(200);
|
||||
expect(jwks.body.keys).toHaveLength(1);
|
||||
});
|
||||
|
||||
it("never publishes private key members (AWS rejects the set and the key counts as exposed)", async () => {
|
||||
const companyId = await company();
|
||||
await service().ensureActiveKey(companyId);
|
||||
await service().beginRotation(companyId, actor);
|
||||
const keySet = await service().publicKeySet(companyId);
|
||||
expect(keySet!.keys).toHaveLength(2);
|
||||
for (const key of keySet!.keys) {
|
||||
expect(Object.keys(key).sort()).toEqual(["alg", "crv", "kid", "kty", "use", "x", "y"]);
|
||||
expect(key).toMatchObject({ kty: "EC", crv: "P-256", alg: "ES256", use: "sig" });
|
||||
}
|
||||
const [stored] = await db.select().from(companyWorkloadIdentityKeys)
|
||||
.where(eq(companyWorkloadIdentityKeys.companyId, companyId));
|
||||
expect(JSON.stringify(stored!.publicJwk)).not.toMatch(/"d"/);
|
||||
expect(JSON.stringify(stored!.privateKeyMaterial)).not.toMatch(/BEGIN PRIVATE KEY/);
|
||||
});
|
||||
|
||||
it("signs a 5-minute token naming one connection that verifies against the published key", async () => {
|
||||
const companyId = await company();
|
||||
const connectionId = await connection(companyId);
|
||||
const signed = await service().signConnectionToken({ companyId, connectionId, audience: "sts.amazonaws.com" });
|
||||
const { header, claims } = decode(signed.token);
|
||||
expect(header).toEqual({ alg: "ES256", typ: "JWT", kid: signed.keyId });
|
||||
expect(claims).toMatchObject({
|
||||
iss: `${ORIGIN}/oidc/companies/${companyId}`,
|
||||
sub: `connection:${connectionId}`,
|
||||
aud: "sts.amazonaws.com",
|
||||
});
|
||||
expect(claims.exp - claims.iat).toBe(300);
|
||||
expect(claims.nbf).toBe(claims.iat);
|
||||
expect(verifiesAgainst(signed.token, (await service().publicKeySet(companyId))!.keys)).toBe(true);
|
||||
|
||||
const [audit] = await db.select().from(toolAccessAuditEvents).where(and(
|
||||
eq(toolAccessAuditEvents.companyId, companyId), eq(toolAccessAuditEvents.action, "workload_identity.token_issued"),
|
||||
));
|
||||
expect(audit).toMatchObject({ connectionId, outcome: "success" });
|
||||
expect(JSON.stringify(audit)).not.toContain(signed.token.split(".")[2]!);
|
||||
});
|
||||
|
||||
it("keeps companies and connections apart", async () => {
|
||||
const companyA = await company();
|
||||
const companyB = await company();
|
||||
const connectionB = await connection(companyB);
|
||||
await expect(service().signConnectionToken({ companyId: companyA, connectionId: connectionB, audience: "sts.amazonaws.com" }))
|
||||
.rejects.toMatchObject({ status: 404 });
|
||||
const tokenB = await service().signConnectionToken({ companyId: companyB, connectionId: connectionB, audience: "sts.amazonaws.com" });
|
||||
await service().ensureActiveKey(companyA);
|
||||
expect(verifiesAgainst(tokenB.token, (await service().publicKeySet(companyA))!.keys)).toBe(false);
|
||||
});
|
||||
|
||||
it("refuses to sign without a usable public address or after the address changed", async () => {
|
||||
const companyId = await company();
|
||||
const connectionId = await connection(companyId);
|
||||
await expect(service().signConnectionToken({
|
||||
companyId, connectionId, audience: "sts.amazonaws.com", origin: workloadIdentityIssuerOrigin("http://localhost:3100"),
|
||||
})).rejects.toMatchObject({ status: 422, details: { code: "workload_identity_unavailable", reason: "not_https" } });
|
||||
await expect(service().signConnectionToken({
|
||||
companyId, connectionId, audience: "sts.amazonaws.com", expectedIssuer: `https://old.example.com/oidc/companies/${companyId}`,
|
||||
})).rejects.toMatchObject({ status: 409, details: { code: "workload_identity_issuer_changed" } });
|
||||
await expect(service().signConnectionToken({ companyId, connectionId, audience: "has space" }))
|
||||
.rejects.toMatchObject({ status: 422 });
|
||||
});
|
||||
|
||||
it("rotates in two published steps, and an emergency rotation drops old keys at once", async () => {
|
||||
const companyId = await company();
|
||||
const connectionId = await connection(companyId);
|
||||
const original = await service().ensureActiveKey(companyId);
|
||||
const begun = await service().beginRotation(companyId, actor);
|
||||
expect(begun.created).toBe(true);
|
||||
expect((await service().beginRotation(companyId, actor)).created).toBe(false);
|
||||
await expect(service().completeRotation(companyId, actor))
|
||||
.rejects.toMatchObject({ status: 409, details: { code: "workload_identity_rotation_not_ready" } });
|
||||
expect((await service().signConnectionToken({ companyId, connectionId, audience: "sts.amazonaws.com" })).keyId)
|
||||
.toBe(original.keyId);
|
||||
|
||||
clock = new Date(clock.getTime() + WORKLOAD_IDENTITY_PUBLISH_BEFORE_USE_MS);
|
||||
await service().completeRotation(companyId, actor);
|
||||
const afterSwap = await service().signConnectionToken({ companyId, connectionId, audience: "sts.amazonaws.com" });
|
||||
expect(afterSwap.keyId).toBe(begun.keyId);
|
||||
expect((await service().publicKeySet(companyId))!.keys.map((key) => key.kid).sort())
|
||||
.toEqual([original.keyId, begun.keyId].sort());
|
||||
|
||||
clock = new Date(clock.getTime() + WORKLOAD_IDENTITY_RETIRING_GRACE_MS);
|
||||
expect((await service().publicKeySet(companyId))!.keys.map((key) => key.kid)).toEqual([begun.keyId]);
|
||||
expect((await service().describe(companyId)).keys.map((key) => key.keyId)).toEqual([begun.keyId]);
|
||||
await service().beginRotation(companyId, actor);
|
||||
const [settled] = await db.select().from(companyWorkloadIdentityKeys).where(and(
|
||||
eq(companyWorkloadIdentityKeys.companyId, companyId), eq(companyWorkloadIdentityKeys.keyId, original.keyId),
|
||||
));
|
||||
expect(settled!.status).toBe("retired");
|
||||
|
||||
const emergency = await service().emergencyRotation(companyId, actor);
|
||||
const published = (await service().publicKeySet(companyId))!.keys.map((key) => key.kid);
|
||||
expect(published).toEqual([emergency.keyId]);
|
||||
const next = await service().signConnectionToken({ companyId, connectionId, audience: "sts.amazonaws.com" });
|
||||
expect(next.keyId).toBe(emergency.keyId);
|
||||
expect(verifiesAgainst(afterSwap.token, (await service().publicKeySet(companyId))!.keys)).toBe(false);
|
||||
});
|
||||
|
||||
it("refuses to sign when the stored private key is not the published one", async () => {
|
||||
const companyId = await company();
|
||||
const connectionId = await connection(companyId);
|
||||
const key = await service().ensureActiveKey(companyId);
|
||||
const other = await generateClientKeyPair("ES256");
|
||||
const { material } = await localEncryptedProvider.createSecret({ value: other.privateKeyPem });
|
||||
await db.update(companyWorkloadIdentityKeys).set({ privateKeyMaterial: material })
|
||||
.where(eq(companyWorkloadIdentityKeys.id, key.id));
|
||||
resetWorkloadIdentityKeyCacheForTests();
|
||||
await expect(service().signConnectionToken({ companyId, connectionId, audience: "sts.amazonaws.com" }))
|
||||
.rejects.toThrow(/does not match its published key/);
|
||||
expect(await db.select().from(toolAccessAuditEvents).where(and(
|
||||
eq(toolAccessAuditEvents.companyId, companyId), eq(toolAccessAuditEvents.action, "workload_identity.token_issued"),
|
||||
))).toHaveLength(0);
|
||||
});
|
||||
|
||||
it("stops issuing tokens for a disabled, draft or switched-off connection", async () => {
|
||||
const companyId = await company();
|
||||
for (const state of [{ status: "disabled" as const }, { status: "draft" as const }, { enabled: false }]) {
|
||||
const connectionId = await connection(companyId, state);
|
||||
await expect(service().signConnectionToken({ companyId, connectionId, audience: "sts.amazonaws.com" }))
|
||||
.rejects.toMatchObject({ status: 422, details: { code: "workload_identity_connection_inactive" } });
|
||||
}
|
||||
});
|
||||
|
||||
it("writes a rotation's activity entry only when the key change commits", async () => {
|
||||
const companyId = await company();
|
||||
await expect(service().beginRotation(companyId, actor)).rejects.toMatchObject({ status: 409 });
|
||||
const entries = () => db.select().from(activityLog).where(and(
|
||||
eq(activityLog.companyId, companyId), eq(activityLog.action, "workload_identity.rotation_begin"),
|
||||
));
|
||||
expect(await entries()).toHaveLength(0);
|
||||
await service().ensureActiveKey(companyId);
|
||||
await service().beginRotation(companyId, actor);
|
||||
expect(await entries()).toHaveLength(1);
|
||||
expect((await service().beginRotation(companyId, actor)).created).toBe(false);
|
||||
expect(await entries()).toHaveLength(1);
|
||||
});
|
||||
|
||||
it("answers the public paths anonymously in the assembled app", async () => {
|
||||
const companyId = await company();
|
||||
await service().ensureActiveKey(companyId);
|
||||
const app = await createApp(db, {
|
||||
uiMode: "none", serverPort: 0, bindHost: "127.0.0.1", allowedHostnames: ["127.0.0.1"],
|
||||
deploymentMode: "authenticated", deploymentExposure: "private", authReady: true, companyDeletionEnabled: false,
|
||||
managedPluginAutoInstall: [], storageService: createStorageService(createLocalDiskStorageProvider(join(directory, "storage"))),
|
||||
decisionServiceOptions: { wakeOriginAgent: async () => null },
|
||||
});
|
||||
await app.locals.bundledPluginsStartup;
|
||||
const server = app.listen(0, "127.0.0.1");
|
||||
try {
|
||||
await new Promise<void>((resolve) => server.once("listening", resolve));
|
||||
const address = server.address();
|
||||
if (!address || typeof address === "string") throw new Error("No HTTP test address");
|
||||
const base = `http://127.0.0.1:${address.port}/oidc/companies/${companyId}`;
|
||||
const discovery = await fetch(`${base}/.well-known/openid-configuration`);
|
||||
expect(discovery.status).toBe(200);
|
||||
expect((await discovery.json()).issuer).toBe(base.replace(`http://127.0.0.1:${address.port}`, ORIGIN));
|
||||
const jwks = await fetch(`${base}/jwks.json`);
|
||||
expect(jwks.status).toBe(200);
|
||||
expect((await jwks.json()).keys).toHaveLength(1);
|
||||
expect((await fetch(`http://127.0.0.1:${address.port}/api/companies/${companyId}/workload-identity`)).status)
|
||||
.not.toBe(200);
|
||||
} finally {
|
||||
await app.locals.paperclipShutdown?.();
|
||||
await new Promise<void>((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
|
||||
}
|
||||
}, 120_000);
|
||||
|
||||
it("limits status and rotation to the board and logs each rotation", async () => {
|
||||
const companyId = await company();
|
||||
await service().ensureActiveKey(companyId);
|
||||
const boardApp = express().use(express.json(), (req, _res, next) => {
|
||||
req.actor = {
|
||||
type: "board", userId: "board-user", source: "local_implicit", companyIds: [companyId],
|
||||
memberships: [{ companyId, membershipRole: "owner", status: "active" }], isInstanceAdmin: true,
|
||||
} as Express.Request["actor"];
|
||||
next();
|
||||
}).use("/api", workloadIdentityRoutes(db)).use(errorHandler);
|
||||
const state = await request(boardApp).get(`/api/companies/${companyId}/workload-identity`).expect(200);
|
||||
expect(state.body.issuer).toBe(`${ORIGIN}/oidc/companies/${companyId}`);
|
||||
expect(JSON.stringify(state.body)).not.toMatch(/private|"d"/i);
|
||||
await request(boardApp).post(`/api/companies/${companyId}/workload-identity/rotation`).send({ step: "nope" }).expect(400);
|
||||
await request(boardApp).post(`/api/companies/${companyId}/workload-identity/rotation`).send({ step: "begin" }).expect(200);
|
||||
const [entry] = await db.select().from(activityLog).where(and(
|
||||
eq(activityLog.companyId, companyId), eq(activityLog.action, "workload_identity.rotation_begin"),
|
||||
));
|
||||
expect(entry).toMatchObject({ actorType: "user", actorId: "board-user", entityType: "company" });
|
||||
|
||||
const agentApp = express().use(express.json(), (req, _res, next) => {
|
||||
req.actor = { type: "agent", agentId: randomUUID(), companyId, source: "agent_key" } as Express.Request["actor"];
|
||||
next();
|
||||
}).use("/api", workloadIdentityRoutes(db)).use(errorHandler);
|
||||
await request(agentApp).get(`/api/companies/${companyId}/workload-identity`).expect(403);
|
||||
await request(agentApp).post(`/api/companies/${companyId}/workload-identity/rotation`).send({ step: "emergency" }).expect(403);
|
||||
});
|
||||
});
|
||||
@@ -139,6 +139,8 @@ import { routineRoutes } from "./routes/routines.js";
|
||||
import { routineSuggestionRoutes } from "./routes/routine-suggestions.js";
|
||||
import { environmentRoutes } from "./routes/environments.js";
|
||||
import { tailscaleConnectionRoutes } from "./routes/tailscale-connections.js";
|
||||
import { workloadIdentityPublicRoutes, workloadIdentityRoutes } from "./routes/workload-identity.js";
|
||||
import { setWorkloadIdentityConfiguredPublicOrigin } from "./services/workload-identity.js";
|
||||
import { executionWorkspaceRoutes } from "./routes/execution-workspaces.js";
|
||||
import { goalRoutes } from "./routes/goals.js";
|
||||
import { responsibilityRoutes } from "./routes/responsibilities.js";
|
||||
@@ -618,6 +620,9 @@ export async function createApp(
|
||||
}));
|
||||
app.use(museTransportRoutes(db, opts.authPublicBaseUrl));
|
||||
app.use(publicMcpIngress);
|
||||
// Outside clouds fetch these anonymously to verify connection identity tokens.
|
||||
setWorkloadIdentityConfiguredPublicOrigin(opts.authPublicBaseUrl);
|
||||
app.use(workloadIdentityPublicRoutes(db));
|
||||
// Connection-intent tools carry their own short-lived, run-bound bearer and
|
||||
// must be reachable by remote adapters that intentionally do not receive an
|
||||
// agent API key. Every request revalidates the active heartbeat row.
|
||||
@@ -866,6 +871,7 @@ export async function createApp(
|
||||
}) }));
|
||||
api.use(routineRoutes(db, { pluginWorkerManager: workerManager }));
|
||||
api.use(tailscaleConnectionRoutes(db));
|
||||
api.use(workloadIdentityRoutes(db));
|
||||
api.use(routineSuggestionRoutes(db, { pluginWorkerManager: workerManager }));
|
||||
api.use(
|
||||
environmentRoutes(db, {
|
||||
|
||||
@@ -1424,6 +1424,9 @@ const PUBLIC_OPERATIONS = new Set([
|
||||
"POST /mcp/gateways/{gatewayPublicId}",
|
||||
"GET /api/tool-gateway/gateways/{gatewayId}/mcp",
|
||||
"POST /api/tool-gateway/gateways/{gatewayId}/mcp",
|
||||
// Outside clouds fetch a company's workload identity issuer anonymously (routes/workload-identity.ts).
|
||||
"GET /oidc/companies/{companyId}/.well-known/openid-configuration",
|
||||
"GET /oidc/companies/{companyId}/jwks.json",
|
||||
]);
|
||||
|
||||
const BOARD_ONLY_PREFIXES = [
|
||||
@@ -1467,6 +1470,9 @@ const mcpSkillsBoardOperations = [
|
||||
] as const;
|
||||
|
||||
const BOARD_ONLY_OPERATIONS = new Set([
|
||||
// Workload identity status and key rotation are board-only (assertBoard in routes/workload-identity.ts).
|
||||
"GET /api/companies/{companyId}/workload-identity",
|
||||
"POST /api/companies/{companyId}/workload-identity/rotation",
|
||||
"POST /api/companies/{companyId}/chats/{agentRef}/onboarding",
|
||||
"POST /api/companies/{companyId}/chats/{agentRef}/onboarding/greeting",
|
||||
"PATCH /api/agents/{id}/permission-grants",
|
||||
@@ -9727,6 +9733,57 @@ registry.registerPath({
|
||||
} }, ...tailscaleErrors },
|
||||
});
|
||||
|
||||
const workloadIdentityParams = z.object({ companyId: z.string().uuid() });
|
||||
const workloadIdentityPublicNotFound = { 404: { description: "The company has no published signing key, or this instance has no public HTTPS address" } };
|
||||
const workloadIdentityKeyState = z.object({
|
||||
issuer: z.string().url().nullable(),
|
||||
unavailableReason: z.enum(["no_public_url", "not_https", "has_port", "loopback"]).nullable(),
|
||||
keys: z.array(z.object({
|
||||
keyId: z.string(), status: z.enum(["next", "active", "retiring"]),
|
||||
createdAt: z.string().datetime(), statusChangedAt: z.string().datetime(),
|
||||
}).strict()),
|
||||
}).strict();
|
||||
|
||||
registry.registerPath({
|
||||
method: "get", path: "/oidc/companies/{companyId}/.well-known/openid-configuration", tags: ["workload-identity"],
|
||||
summary: "Company workload identity OIDC discovery document",
|
||||
description: "Unauthenticated. Outside clouds read this to verify tokens that name one of the company's connections. Cacheable for five minutes.",
|
||||
request: { params: workloadIdentityParams },
|
||||
responses: { 200: r.ok(z.object({
|
||||
issuer: z.string().url(), jwks_uri: z.string().url(),
|
||||
response_types_supported: z.array(z.string()), subject_types_supported: z.array(z.string()),
|
||||
id_token_signing_alg_values_supported: z.array(z.string()), claims_supported: z.array(z.string()),
|
||||
}).strict()), ...workloadIdentityPublicNotFound },
|
||||
});
|
||||
|
||||
registry.registerPath({
|
||||
method: "get", path: "/oidc/companies/{companyId}/jwks.json", tags: ["workload-identity"],
|
||||
summary: "Company workload identity public key set",
|
||||
description: "Unauthenticated. Lists only public ES256 keys. Never contains private key members.",
|
||||
request: { params: workloadIdentityParams },
|
||||
responses: { 200: r.ok(z.object({ keys: z.array(z.object({
|
||||
kty: z.literal("EC"), crv: z.string(), x: z.string(), y: z.string(), kid: z.string(), alg: z.literal("ES256"), use: z.literal("sig"),
|
||||
}).strict()) }).strict()), ...workloadIdentityPublicNotFound },
|
||||
});
|
||||
|
||||
registry.registerPath({
|
||||
method: "get", path: "/api/companies/{companyId}/workload-identity", tags: ["workload-identity"],
|
||||
summary: "Company workload identity issuer and key states",
|
||||
description: "Board only. Returns the issuer (or why it is unavailable) and the published keys. No private key material.",
|
||||
request: { params: workloadIdentityParams },
|
||||
responses: { 200: r.ok(workloadIdentityKeyState), 401: r.unauthorized, 403: r.forbidden, 404: r.notFound },
|
||||
});
|
||||
|
||||
registry.registerPath({
|
||||
method: "post", path: "/api/companies/{companyId}/workload-identity/rotation", tags: ["workload-identity"],
|
||||
summary: "Rotate the company workload identity signing key",
|
||||
description: "Board only. begin publishes a next key; complete makes it sign after 24 hours of publication; emergency replaces every key at once. Each step writes its activity entry in the same transaction as the key change.",
|
||||
request: { params: workloadIdentityParams, body: jsonBody(z.object({ step: z.enum(["begin", "complete", "emergency"]) }).strict()) },
|
||||
responses: { 200: r.ok(z.object({
|
||||
step: z.enum(["begin", "complete", "emergency"]), keyId: z.string(), created: z.boolean().optional(), state: workloadIdentityKeyState,
|
||||
}).strict()), 400: r.badRequest, 401: r.unauthorized, 403: r.forbidden, 404: r.notFound, 409: r.conflict },
|
||||
});
|
||||
|
||||
// ─── Environments ─────────────────────────────────────────────────────────────
|
||||
|
||||
registry.registerPath({
|
||||
|
||||
@@ -0,0 +1,70 @@
|
||||
import { Router, type Response } from "express";
|
||||
import type { Db } from "@paperclipai/db";
|
||||
import { z } from "zod";
|
||||
import { validate } from "../middleware/validate.js";
|
||||
import { workloadIdentityService } from "../services/workload-identity.js";
|
||||
import { assertBoard, assertCompanyAccess, getActorInfo } from "./authz.js";
|
||||
|
||||
const companyIdSchema = z.string().uuid();
|
||||
|
||||
function notPublished(res: Response) {
|
||||
res.setHeader("Cache-Control", "public, max-age=60");
|
||||
res.status(404).json({ error: "not_found" });
|
||||
}
|
||||
|
||||
/**
|
||||
* Public OIDC discovery and key set for a company's workload identity issuer.
|
||||
* Outside clouds fetch these anonymously to verify tokens; they expose only
|
||||
* public keys, and answer 404 until the company has created a key.
|
||||
*/
|
||||
export function workloadIdentityPublicRoutes(db: Db) {
|
||||
const router = Router();
|
||||
const service = workloadIdentityService(db);
|
||||
router.get("/oidc/companies/:companyId/.well-known/openid-configuration", async (req, res) => {
|
||||
const companyId = companyIdSchema.safeParse(req.params.companyId);
|
||||
if (!companyId.success) return notPublished(res);
|
||||
const document = await service.discoveryDocument(companyId.data);
|
||||
if (!document) return notPublished(res);
|
||||
res.setHeader("Cache-Control", "public, max-age=300");
|
||||
res.json(document);
|
||||
});
|
||||
router.get("/oidc/companies/:companyId/jwks.json", async (req, res) => {
|
||||
const companyId = companyIdSchema.safeParse(req.params.companyId);
|
||||
if (!companyId.success) return notPublished(res);
|
||||
const keySet = await service.publicKeySet(companyId.data);
|
||||
if (!keySet) return notPublished(res);
|
||||
res.setHeader("Cache-Control", "public, max-age=300");
|
||||
res.json(keySet);
|
||||
});
|
||||
return router;
|
||||
}
|
||||
|
||||
const rotationSchema = z.object({ step: z.enum(["begin", "complete", "emergency"]) }).strict();
|
||||
|
||||
/** Board-only status and key rotation for the company's issuer. */
|
||||
export function workloadIdentityRoutes(db: Db) {
|
||||
const router = Router();
|
||||
const service = workloadIdentityService(db);
|
||||
router.get("/companies/:companyId/workload-identity", async (req, res) => {
|
||||
assertBoard(req);
|
||||
const companyId = companyIdSchema.parse(req.params.companyId);
|
||||
assertCompanyAccess(req, companyId);
|
||||
res.json(await service.describe(companyId));
|
||||
});
|
||||
router.post("/companies/:companyId/workload-identity/rotation", validate(rotationSchema), async (req, res) => {
|
||||
assertBoard(req);
|
||||
const companyId = companyIdSchema.parse(req.params.companyId);
|
||||
assertCompanyAccess(req, companyId);
|
||||
const { step } = req.body as z.infer<typeof rotationSchema>;
|
||||
const { actorType, actorId } = getActorInfo(req);
|
||||
// The service writes the activity entry in the same transaction as the key change.
|
||||
const actor = { actorType, actorId };
|
||||
const result = step === "begin"
|
||||
? await service.beginRotation(companyId, actor)
|
||||
: step === "complete"
|
||||
? await service.completeRotation(companyId, actor)
|
||||
: await service.emergencyRotation(companyId, actor);
|
||||
res.json({ step, ...result, state: await service.describe(companyId) });
|
||||
});
|
||||
return router;
|
||||
}
|
||||
@@ -0,0 +1,384 @@
|
||||
import { createPrivateKey, createPublicKey, randomUUID, sign, type KeyObject } from "node:crypto";
|
||||
import { and, eq, gt, inArray, lte, or } from "drizzle-orm";
|
||||
import {
|
||||
companies,
|
||||
companyWorkloadIdentityKeys,
|
||||
toolAccessAuditEvents,
|
||||
toolConnections,
|
||||
type Db,
|
||||
} from "@paperclipai/db";
|
||||
import { conflict, notFound, unprocessable } from "../errors.js";
|
||||
import { persistActivity, publishActivity, type LogActivityInput } from "./activity-log.js";
|
||||
import { localEncryptedProvider } from "../secrets/local-encrypted-provider.js";
|
||||
import { runtimePublicOrigin } from "./cloud-runtime-identity.js";
|
||||
import { generateClientKeyPair, jwkThumbprint } from "./tool-access/oauth/client-credentials.js";
|
||||
|
||||
/**
|
||||
* Workload identity issuer: each company signs short-lived OIDC tokens that
|
||||
* name one of its connections, and publishes the public keys so an outside
|
||||
* cloud (AWS, GCP, Azure) can verify them without Paperclip storing that
|
||||
* cloud's keys. Only the control plane can sign; agents never see these tokens.
|
||||
*/
|
||||
|
||||
export const WORKLOAD_IDENTITY_ALGORITHM = "ES256";
|
||||
export const WORKLOAD_IDENTITY_TOKEN_LIFETIME_SECONDS = 300;
|
||||
/** A `next` key is published this long before it may sign, so cached key sets pick it up. */
|
||||
export const WORKLOAD_IDENTITY_PUBLISH_BEFORE_USE_MS = 24 * 60 * 60 * 1000;
|
||||
/** A replaced key stays published this long, so tokens it signed still verify. */
|
||||
export const WORKLOAD_IDENTITY_RETIRING_GRACE_MS = 24 * 60 * 60 * 1000;
|
||||
|
||||
type KeyRow = typeof companyWorkloadIdentityKeys.$inferSelect;
|
||||
|
||||
export type WorkloadIdentityIssuerOrigin =
|
||||
| { available: true; origin: string }
|
||||
| { available: false; reason: "no_public_url" | "not_https" | "has_port" | "loopback" };
|
||||
|
||||
let configuredPublicOrigin: string | null = null;
|
||||
|
||||
/**
|
||||
* The instance's configured public address (auth.publicBaseUrl, BETTER_AUTH_URL,
|
||||
* BETTER_AUTH_BASE_URL), set once by createApp. Used after the live Cloud
|
||||
* address and the PAPERCLIP_PUBLIC_URL family, which `runtimePublicOrigin` reads.
|
||||
*/
|
||||
export function setWorkloadIdentityConfiguredPublicOrigin(origin: string | null | undefined) {
|
||||
configuredPublicOrigin = origin?.trim() || null;
|
||||
}
|
||||
|
||||
export function workloadIdentityPublicOrigin(): string | null {
|
||||
return runtimePublicOrigin() ?? configuredPublicOrigin;
|
||||
}
|
||||
|
||||
/** AWS requires an https issuer with no port that it can reach from the internet. */
|
||||
export function workloadIdentityIssuerOrigin(origin: string | null = workloadIdentityPublicOrigin()): WorkloadIdentityIssuerOrigin {
|
||||
if (!origin) return { available: false, reason: "no_public_url" };
|
||||
let url: URL;
|
||||
try {
|
||||
url = new URL(origin);
|
||||
} catch {
|
||||
return { available: false, reason: "no_public_url" };
|
||||
}
|
||||
if (url.protocol !== "https:") return { available: false, reason: "not_https" };
|
||||
if (url.port !== "") return { available: false, reason: "has_port" };
|
||||
const host = url.hostname.toLowerCase();
|
||||
if (host === "localhost" || host.endsWith(".localhost") || host === "[::1]" || /^127\./.test(host)) {
|
||||
return { available: false, reason: "loopback" };
|
||||
}
|
||||
return { available: true, origin: url.origin };
|
||||
}
|
||||
|
||||
export function workloadIdentityIssuer(origin: string, companyId: string): string {
|
||||
return `${origin}/oidc/companies/${companyId}`;
|
||||
}
|
||||
|
||||
export function workloadIdentitySubject(connectionId: string): string {
|
||||
return `connection:${connectionId}`;
|
||||
}
|
||||
|
||||
/** Only public EC members, so private material can never reach the published key set. */
|
||||
function publicJwkFor(row: Pick<KeyRow, "publicJwk" | "keyId">) {
|
||||
const jwk = row.publicJwk;
|
||||
return {
|
||||
kty: "EC",
|
||||
crv: jwk.crv,
|
||||
x: jwk.x,
|
||||
y: jwk.y,
|
||||
kid: row.keyId,
|
||||
alg: WORKLOAD_IDENTITY_ALGORITHM,
|
||||
use: "sig",
|
||||
};
|
||||
}
|
||||
|
||||
/** Only each company's current signing key is held decrypted; a rotated-out key is dropped. */
|
||||
const signingKeyCache = new Map<string, { keyId: string; privateKey: KeyObject }>();
|
||||
|
||||
export function resetWorkloadIdentityKeyCacheForTests() {
|
||||
signingKeyCache.clear();
|
||||
}
|
||||
|
||||
function base64Url(value: Buffer | string): string {
|
||||
return Buffer.from(value).toString("base64url");
|
||||
}
|
||||
|
||||
export function workloadIdentityService(db: Db, options: { now?: () => Date } = {}) {
|
||||
const now = options.now ?? (() => new Date());
|
||||
|
||||
async function newKeyValues(companyId: string, status: "next" | "active") {
|
||||
const generated = await generateClientKeyPair(WORKLOAD_IDENTITY_ALGORITHM, now());
|
||||
const encrypted = await localEncryptedProvider.createSecret({ value: generated.privateKeyPem });
|
||||
const at = now();
|
||||
return {
|
||||
companyId,
|
||||
keyId: generated.publicKey.keyId,
|
||||
algorithm: WORKLOAD_IDENTITY_ALGORITHM as "ES256",
|
||||
publicJwk: generated.publicKey.publicJwk as unknown as Record<string, unknown>,
|
||||
privateKeyMaterial: encrypted.material,
|
||||
status,
|
||||
createdAt: at,
|
||||
statusChangedAt: at,
|
||||
};
|
||||
}
|
||||
|
||||
async function assertCompany(companyId: string) {
|
||||
const [company] = await db.select({ id: companies.id }).from(companies).where(eq(companies.id, companyId));
|
||||
if (!company) throw notFound("Company not found");
|
||||
}
|
||||
|
||||
async function activeKey(companyId: string): Promise<KeyRow | undefined> {
|
||||
const [row] = await db.select().from(companyWorkloadIdentityKeys).where(and(
|
||||
eq(companyWorkloadIdentityKeys.companyId, companyId),
|
||||
eq(companyWorkloadIdentityKeys.status, "active"),
|
||||
));
|
||||
return row;
|
||||
}
|
||||
|
||||
/** The company's signing key, created on first use. Concurrent callers converge on one key. */
|
||||
async function ensureActiveKey(companyId: string): Promise<KeyRow> {
|
||||
const existing = await activeKey(companyId);
|
||||
if (existing) return existing;
|
||||
await assertCompany(companyId);
|
||||
await db.insert(companyWorkloadIdentityKeys).values(await newKeyValues(companyId, "active")).onConflictDoNothing();
|
||||
const created = await activeKey(companyId);
|
||||
if (!created) throw new Error("Workload identity key could not be created");
|
||||
return created;
|
||||
}
|
||||
|
||||
async function privateKeyFor(row: KeyRow): Promise<KeyObject> {
|
||||
const cached = signingKeyCache.get(row.companyId);
|
||||
if (cached?.keyId === row.keyId) return cached.privateKey;
|
||||
const pem = await localEncryptedProvider.resolveVersion({ material: row.privateKeyMaterial, externalRef: null });
|
||||
const privateKey = createPrivateKey(pem);
|
||||
// Fail closed on corruption or a wrong master key; never sign with a key that isn't the published one.
|
||||
if (row.algorithm !== WORKLOAD_IDENTITY_ALGORITHM || privateKey.asymmetricKeyType !== "ec"
|
||||
|| jwkThumbprint(createPublicKey(privateKey).export({ format: "jwk" })) !== row.keyId) {
|
||||
throw new Error("Workload identity private key does not match its published key");
|
||||
}
|
||||
signingKeyCache.set(row.companyId, { keyId: row.keyId, privateKey });
|
||||
return privateKey;
|
||||
}
|
||||
|
||||
/** Published keys only, filtered in SQL so reads stay bounded however many rotations happened. */
|
||||
async function publishedKeyRows(companyId: string): Promise<KeyRow[]> {
|
||||
const graceStart = new Date(now().getTime() - WORKLOAD_IDENTITY_RETIRING_GRACE_MS);
|
||||
return db.select().from(companyWorkloadIdentityKeys).where(and(
|
||||
eq(companyWorkloadIdentityKeys.companyId, companyId),
|
||||
or(
|
||||
inArray(companyWorkloadIdentityKeys.status, ["next", "active"]),
|
||||
and(eq(companyWorkloadIdentityKeys.status, "retiring"),
|
||||
gt(companyWorkloadIdentityKeys.statusChangedAt, graceStart)),
|
||||
),
|
||||
));
|
||||
}
|
||||
|
||||
/** Retiring keys past their grace period become retired, so they leave every view. */
|
||||
async function settleRetiring(tx: Db, companyId: string, at: Date) {
|
||||
await tx.update(companyWorkloadIdentityKeys).set({ status: "retired", statusChangedAt: at }).where(and(
|
||||
eq(companyWorkloadIdentityKeys.companyId, companyId),
|
||||
eq(companyWorkloadIdentityKeys.status, "retiring"),
|
||||
lte(companyWorkloadIdentityKeys.statusChangedAt, new Date(at.getTime() - WORKLOAD_IDENTITY_RETIRING_GRACE_MS)),
|
||||
));
|
||||
}
|
||||
|
||||
type RotationActor = Pick<LogActivityInput, "actorType" | "actorId">;
|
||||
|
||||
/** Runs one rotation step and its activity entry in one transaction; publishes the entry after commit. */
|
||||
async function rotate(
|
||||
companyId: string,
|
||||
actor: RotationActor,
|
||||
step: "begin" | "complete" | "emergency",
|
||||
work: (tx: Db, at: Date) => Promise<{ keyId: string; created?: boolean }>,
|
||||
) {
|
||||
const { result, publication } = await db.transaction(async (rawTx) => {
|
||||
const tx = rawTx as unknown as Db;
|
||||
await lockCompany(tx, companyId);
|
||||
const at = now();
|
||||
await settleRetiring(tx, companyId, at);
|
||||
const result = await work(tx, at);
|
||||
// A repeated "begin" while a rotation is pending changes nothing, so it is not logged.
|
||||
if (result.created === false) return { result, publication: null };
|
||||
const { publication } = await persistActivity(tx, {
|
||||
companyId, ...actor,
|
||||
action: `workload_identity.rotation_${step}`,
|
||||
entityType: "company", entityId: companyId,
|
||||
details: { keyId: result.keyId },
|
||||
});
|
||||
return { result, publication };
|
||||
});
|
||||
if (publication) publishActivity(publication);
|
||||
if (step !== "begin") signingKeyCache.delete(companyId);
|
||||
return result;
|
||||
}
|
||||
|
||||
async function lockCompany(tx: Db, companyId: string) {
|
||||
const [company] = await tx.select({ id: companies.id }).from(companies)
|
||||
.where(eq(companies.id, companyId)).for("update");
|
||||
if (!company) throw notFound("Company not found");
|
||||
}
|
||||
|
||||
return {
|
||||
ensureActiveKey,
|
||||
|
||||
/** Public key set, or null when the company has never created a key (callers answer 404). */
|
||||
async publicKeySet(companyId: string): Promise<{ keys: ReturnType<typeof publicJwkFor>[] } | null> {
|
||||
const keys = (await publishedKeyRows(companyId)).map(publicJwkFor);
|
||||
return keys.length > 0 ? { keys } : null;
|
||||
},
|
||||
|
||||
/** OIDC discovery document, or null when the issuer isn't usable here or the company has no key. */
|
||||
async discoveryDocument(companyId: string, origin = workloadIdentityIssuerOrigin()) {
|
||||
if (!origin.available) return null;
|
||||
if ((await publishedKeyRows(companyId)).length === 0) return null;
|
||||
const issuer = workloadIdentityIssuer(origin.origin, companyId);
|
||||
return {
|
||||
issuer,
|
||||
jwks_uri: `${issuer}/jwks.json`,
|
||||
response_types_supported: ["id_token"],
|
||||
subject_types_supported: ["public"],
|
||||
id_token_signing_alg_values_supported: [WORKLOAD_IDENTITY_ALGORITHM],
|
||||
claims_supported: ["aud", "exp", "iat", "iss", "jti", "nbf", "sub"],
|
||||
};
|
||||
},
|
||||
|
||||
/**
|
||||
* A 5-minute token that names one connection. `sub` and `aud` come from the
|
||||
* connection and its method, never from agent input. The token itself is
|
||||
* never stored or logged.
|
||||
*/
|
||||
async signConnectionToken(input: {
|
||||
companyId: string;
|
||||
connectionId: string;
|
||||
audience: string;
|
||||
/** The issuer recorded when the connection was set up; signing stops if the instance address changed. */
|
||||
expectedIssuer?: string | null;
|
||||
origin?: WorkloadIdentityIssuerOrigin;
|
||||
}) {
|
||||
if (!/^[\x21-\x7e]{1,256}$/.test(input.audience)) {
|
||||
throw unprocessable("Invalid workload identity audience", { code: "workload_identity_audience_invalid" });
|
||||
}
|
||||
const origin = input.origin ?? workloadIdentityIssuerOrigin();
|
||||
if (!origin.available) {
|
||||
throw unprocessable("This Paperclip instance needs a public HTTPS address to sign identity tokens.", {
|
||||
code: "workload_identity_unavailable", reason: origin.reason,
|
||||
});
|
||||
}
|
||||
const issuer = workloadIdentityIssuer(origin.origin, input.companyId);
|
||||
if (input.expectedIssuer && input.expectedIssuer !== issuer) {
|
||||
throw conflict("This Paperclip instance's address changed. Update the identity provider in your cloud account.", {
|
||||
code: "workload_identity_issuer_changed",
|
||||
});
|
||||
}
|
||||
const [connection] = await db.select({ status: toolConnections.status, enabled: toolConnections.enabled })
|
||||
.from(toolConnections).where(and(
|
||||
eq(toolConnections.id, input.connectionId), eq(toolConnections.companyId, input.companyId),
|
||||
));
|
||||
if (!connection) throw notFound("Connection not found");
|
||||
// Disabling a connection must stop new cloud credentials at once.
|
||||
if (!connection.enabled || connection.status !== "active") {
|
||||
throw unprocessable("This connection is not active.", { code: "workload_identity_connection_inactive" });
|
||||
}
|
||||
|
||||
const key = await ensureActiveKey(input.companyId);
|
||||
const privateKey = await privateKeyFor(key);
|
||||
const issuedAt = Math.floor(now().getTime() / 1000);
|
||||
const expiresAt = issuedAt + WORKLOAD_IDENTITY_TOKEN_LIFETIME_SECONDS;
|
||||
const subject = workloadIdentitySubject(input.connectionId);
|
||||
const header = { alg: WORKLOAD_IDENTITY_ALGORITHM, typ: "JWT", kid: key.keyId };
|
||||
const claims = {
|
||||
iss: issuer, sub: subject, aud: input.audience,
|
||||
iat: issuedAt, nbf: issuedAt, exp: expiresAt, jti: randomUUID(),
|
||||
};
|
||||
const signingInput = `${base64Url(JSON.stringify(header))}.${base64Url(JSON.stringify(claims))}`;
|
||||
const signature = sign("sha256", Buffer.from(signingInput), { key: privateKey, dsaEncoding: "ieee-p1363" });
|
||||
await db.insert(toolAccessAuditEvents).values({
|
||||
companyId: input.companyId,
|
||||
connectionId: input.connectionId,
|
||||
actorType: "system",
|
||||
actorId: "workload-identity",
|
||||
action: "workload_identity.token_issued",
|
||||
outcome: "success",
|
||||
details: { keyId: key.keyId, audience: input.audience, expiresAt: new Date(expiresAt * 1000).toISOString() },
|
||||
});
|
||||
return {
|
||||
token: `${signingInput}.${base64Url(signature)}`,
|
||||
issuer,
|
||||
subject,
|
||||
keyId: key.keyId,
|
||||
expiresAt: new Date(expiresAt * 1000),
|
||||
};
|
||||
},
|
||||
|
||||
/** Board view: issuer and the published keys with their states, with no private material. */
|
||||
async describe(companyId: string, origin = workloadIdentityIssuerOrigin()) {
|
||||
await assertCompany(companyId);
|
||||
const rows = await publishedKeyRows(companyId);
|
||||
return {
|
||||
issuer: origin.available ? workloadIdentityIssuer(origin.origin, companyId) : null,
|
||||
unavailableReason: origin.available ? null : origin.reason,
|
||||
keys: rows
|
||||
.sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime())
|
||||
.map((row) => ({
|
||||
keyId: row.keyId,
|
||||
status: row.status,
|
||||
createdAt: row.createdAt.toISOString(),
|
||||
statusChangedAt: row.statusChangedAt.toISOString(),
|
||||
})),
|
||||
};
|
||||
},
|
||||
|
||||
/** Step 1 of a planned rotation: publish a `next` key alongside the active one. */
|
||||
async beginRotation(companyId: string, actor: RotationActor) {
|
||||
return rotate(companyId, actor, "begin", async (tx) => {
|
||||
const rows = await tx.select().from(companyWorkloadIdentityKeys).where(and(
|
||||
eq(companyWorkloadIdentityKeys.companyId, companyId),
|
||||
inArray(companyWorkloadIdentityKeys.status, ["next", "active"]),
|
||||
));
|
||||
if (!rows.some((row) => row.status === "active")) {
|
||||
throw conflict("This company has no signing key to rotate yet.", { code: "workload_identity_no_key" });
|
||||
}
|
||||
const pending = rows.find((row) => row.status === "next");
|
||||
if (pending) return { keyId: pending.keyId, created: false };
|
||||
const [created] = await tx.insert(companyWorkloadIdentityKeys)
|
||||
.values(await newKeyValues(companyId, "next")).returning();
|
||||
return { keyId: created!.keyId, created: true };
|
||||
});
|
||||
},
|
||||
|
||||
/** Step 2: once the `next` key has been published long enough, it signs; the old key stays published for a grace period. */
|
||||
async completeRotation(companyId: string, actor: RotationActor) {
|
||||
return rotate(companyId, actor, "complete", async (tx, at) => {
|
||||
const [next] = await tx.select().from(companyWorkloadIdentityKeys).where(and(
|
||||
eq(companyWorkloadIdentityKeys.companyId, companyId),
|
||||
eq(companyWorkloadIdentityKeys.status, "next"),
|
||||
));
|
||||
if (!next) throw conflict("Start a rotation first.", { code: "workload_identity_no_rotation" });
|
||||
const readyAt = new Date(next.createdAt.getTime() + WORKLOAD_IDENTITY_PUBLISH_BEFORE_USE_MS);
|
||||
if (readyAt > at) {
|
||||
throw conflict("The new key must be published for 24 hours before it can sign.", {
|
||||
code: "workload_identity_rotation_not_ready", readyAt: readyAt.toISOString(),
|
||||
});
|
||||
}
|
||||
await tx.update(companyWorkloadIdentityKeys).set({ status: "retiring", statusChangedAt: at }).where(and(
|
||||
eq(companyWorkloadIdentityKeys.companyId, companyId),
|
||||
eq(companyWorkloadIdentityKeys.status, "active"),
|
||||
));
|
||||
await tx.update(companyWorkloadIdentityKeys).set({ status: "active", statusChangedAt: at })
|
||||
.where(eq(companyWorkloadIdentityKeys.id, next.id));
|
||||
return { keyId: next.keyId };
|
||||
});
|
||||
},
|
||||
|
||||
/** For a key believed exposed: stop publishing every current key and sign with a fresh one immediately. */
|
||||
async emergencyRotation(companyId: string, actor: RotationActor) {
|
||||
return rotate(companyId, actor, "emergency", async (tx, at) => {
|
||||
await tx.update(companyWorkloadIdentityKeys).set({ status: "retired", statusChangedAt: at }).where(and(
|
||||
eq(companyWorkloadIdentityKeys.companyId, companyId),
|
||||
inArray(companyWorkloadIdentityKeys.status, ["next", "active", "retiring"]),
|
||||
));
|
||||
const [created] = await tx.insert(companyWorkloadIdentityKeys)
|
||||
.values(await newKeyValues(companyId, "active")).returning();
|
||||
return { keyId: created!.keyId };
|
||||
});
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
export type WorkloadIdentityService = ReturnType<typeof workloadIdentityService>;
|
||||
Reference in new issue
Block a user