cloud_tenant: company-scoped tenants, never instance-admin (#7525)

## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies, and a
single server instance can host many companies.
> - The auth middleware (`server/src/middleware/auth.ts`) supports a
`cloud_tenant` mode where a trusted hosting proxy injects per-request
identity headers, designed originally for one-deployment-per-tenant
setups.
> - In that original setup, granting every cloud tenant the
`instance_admin` role was harmless; on a **shared, multi-tenant pool**
it means any paying tenant is admin of the whole instance and can reach
every other tenant's data.
> - A tenant only needs to own its own company — which it already gets
via the company membership the same code path upserts — so
instance-level admin is never appropriate for `cloud_tenant` actors.
> - This PR removes the `instance_admin` grant from the cloud-tenant
path and pins `isInstanceAdmin: false` on the resolved actor.
> - Greptile review then surfaced a follow-up gap: deployments that ran
the pre-hardening build still have stale `instance_admin` rows in
`instance_user_roles`, which other lookups (BetterAuth session path,
board API keys, and the authorization service's own DB re-check) would
still honor.
> - The follow-up commit closes that gap by purging stale rows at the
cloud-tenant auth boundary and by teaching the authorization service
that `cloud_tenant` actors are never instance admins.
> - The benefit is that shared-pool hosting becomes structurally safe:
tenants are company-scoped owners, never instance admins — including on
deployments upgrading from the older behavior.

## Linked Issues

- Refs #966 — managed SaaS multi-tenant hosting is the deployment shape
this hardening protects.
- Refs #5015 — same problem space: instance-admin-scoped credentials are
too broad for multi-company instances; tenants need company-scoped
access.

Neither issue is fully closed by this PR; it removes the instance-admin
grant from the `cloud_tenant` trusted-header path specifically.

## What Changed

- `server/src/middleware/auth.ts`
- Removed the `instanceUserRoles` insert that granted every cloud tenant
`instance_admin`; `resolveCloudTenantActor` now returns
`isInstanceAdmin: false` (was `true`).
- `resolveCloudTenantActor` now **deletes** any stale `instance_admin`
row for the authenticated tenant user on every trusted-header request,
so grants left behind by pre-hardening deployments are purged at the
source (closes the Greptile P2: stale rows could otherwise re-elevate
the user via the BetterAuth session path, board API keys, or the
authorization service).
  - The function is `export`ed so it can be unit-tested directly.
- `server/src/services/authorization.ts`
- `authorizationService` previously re-checked `instanceUserRoles` from
the DB regardless of the actor flag, which would have elevated even
hardened `cloud_tenant` actors while a stale row lingered. Actors with
`source === "cloud_tenant"` are now never elevated to instance admin;
other board actors keep the existing lookup.
- `server/src/services/authorization.ts` +
`server/src/middleware/auth.ts` (follow-up commit `dc57a71c7`)
- CI on the merge ref surfaced that elevation removal alone strands real
cloud tenant users: board actors only ever reached `issue:read` /
`issue:mutate` through instance-admin elevation (`permissionForAction`
maps both to no grant key). `decide()` now grants `cloud_tenant` actors
with an **active membership in the resource company** the same read
surface as a same-company agent (`agent:read`, `company_scope:read`,
`issue:read`, `project:read`) plus `issue:mutate` for non-viewer members
— cross-company access stays denied (new `allow_company_member` reason).
- `resolveCloudTenantActor` seeds the standard role-default permission
grants (`ensureHumanRoleDefaultGrants`) so granted actions (e.g.
`tasks:assign`, `agents:create` for owners) work without elevation.
- Master-side route tests that stubbed cloud tenant actors with
`isInstanceAdmin: true` now seed a real membership and assert under the
hardened contract (`issue-identifier-routes`,
`multilingual-issues-routes`, `issue-comment-redaction`).
- Tests
- `server/src/middleware/cloud-tenant-actor.test.ts` (new): cloud tenant
is never instance-admin, is scoped to exactly the one company from its
stack, still upserts user/company/membership, purges stale
`instance_admin` rows, returns null without the server token, and maps
non-owner stack roles without elevating.
- `server/src/__tests__/auth-session-route.test.ts`: end-to-end
middleware regression — a user with a stale `instance_admin` row stops
being elevated via the session path once they authenticate through the
cloud-tenant path (with a control assertion showing the pre-purge
elevation).
- `server/src/__tests__/authorization-service.test.ts` (embedded
Postgres): a `cloud_tenant` actor with a stale `instance_admin` row in
the real DB cannot cross company boundaries, while a `session` actor
with the same row still resolves `allow_instance_admin`.

## Verification

Run from the repo root after `pnpm install --frozen-lockfile`:

```bash
cd server
npx vitest run src/middleware/cloud-tenant-actor.test.ts src/__tests__/auth-session-route.test.ts
# 9 tests passed
npx vitest run src/__tests__/authorization-service.test.ts
# 16 tests passed (embedded Postgres)
pnpm typecheck
# clean
```

Also ran the broader auth-related suites locally (`auth-routes`,
`authz-company-access`, `better-auth`, `adapter-routes-authz`,
`express5-auth-wildcard`): 8 files, 58 tests, all passing.

## Risks

- **This touches authentication and authorization paths directly.**
Mistakes here are security bugs in both directions; review accordingly.
- **Behavioral change for existing `cloud_tenant` deployments:** tenants
that previously (incorrectly) had instance-admin lose it — including the
ability to see/manage other companies on the instance. This is the
intended hardening, but any single-tenant deployment that relied on the
cloud-tenant identity for instance administration must provision a
separate admin identity.
- **The purge is destructive by design:** if an operator's
instance-admin identity is *also* provisioned through the cloud-tenant
headers (same user id), its `instance_admin` row will be deleted on the
next trusted-header request. Operators should hold admin through a
non-cloud-tenant identity.
- **Residual gap (documented, not fixed here):** a deployment that ran
the old cloud_tenant build and then *disabled* cloud-tenant mode keeps
stale rows until the affected user re-authenticates through the cloud
path. A data migration was considered and deliberately avoided: there is
no reliable SQL predicate for "cloud-tenant-provisioned user" (no source
column), so a migration risks deleting legitimate admins.
- No schema or migration changes; no UI changes.

## Model Used

- Claude Fable 5 (claude-fable-5, 1M context), extended thinking + tool
use, via Claude Code — this revision; original PR authored in an earlier
Claude Code session.

## 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 (none duplicate this; related issues Refs #966 / #5015 are
linked in the issue section)
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots (no UI changes)
- [x] I have updated relevant documentation to reflect my changes (no
existing docs reference `cloud_tenant` mode)
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

server/src/middleware/auth.ts

@@ -8,6 +8,7 @@ import type { DeploymentMode } from "@paperclipai/shared";
 import type { BetterAuthSessionResult } from "../auth/better-auth.js";
 import { logger } from "./logger.js";
 import { boardAuthService } from "../services/board-auth.js";
+import { ensureHumanRoleDefaultGrants } from "../services/principal-access-compatibility.js";
 
 function hashToken(token: string) {
   return createHash("sha256").update(token).digest("hex");
@@ -199,7 +200,7 @@ export function actorMiddleware(db: Db, opts: ActorMiddlewareOptions): RequestHa
   };
 }
 
-async function resolveCloudTenantActor(db: Db, req: Request): Promise<Express.Request["actor"] | null> {
+export async function resolveCloudTenantActor(db: Db, req: Request): Promise<Express.Request["actor"] | null> {
   const expectedToken = process.env.PAPERCLIP_CLOUD_TENANT_SERVER_TOKEN?.trim();
   if (!expectedToken) return null;
 
@@ -237,16 +238,14 @@ async function resolveCloudTenantActor(db: Db, req: Request): Promise<Express.Re
       },
     });
 
+  // Earlier cloud_tenant builds granted every tenant user `instance_admin`.
+  // Stale rows from those deployments would still elevate this user through
+  // the BetterAuth session path, board API keys, and the authorization
+  // service's own instanceUserRoles lookup — so actively purge them on every
+  // trusted-header authentication instead of merely no longer inserting them.
   await db
-    .insert(instanceUserRoles)
-    .values({
-      userId,
-      role: "instance_admin",
-      updatedAt: now,
-    })
-    .onConflictDoNothing({
-      target: [instanceUserRoles.userId, instanceUserRoles.role],
-    });
+    .delete(instanceUserRoles)
+    .where(and(eq(instanceUserRoles.userId, userId), eq(instanceUserRoles.role, "instance_admin")));
 
   await db
     .insert(companies)
@@ -292,6 +291,16 @@ async function resolveCloudTenantActor(db: Db, req: Request): Promise<Express.Re
       status: "active",
     });
 
+  // Without instance-admin elevation, cloud tenant users are authorized purely
+  // through company-scoped permission grants — seed the same role defaults the
+  // regular membership flows create.
+  await ensureHumanRoleDefaultGrants(db, {
+    companyId,
+    principalId: userId,
+    membershipRole: membership.membershipRole,
+    grantedByUserId: null,
+  });
+
   return {
     type: "board",
     userId,
@@ -303,7 +312,7 @@ async function resolveCloudTenantActor(db: Db, req: Request): Promise<Express.Re
       membershipRole: membership.membershipRole,
       status: membership.status,
     }],
-    isInstanceAdmin: true,
+    isInstanceAdmin: false,
     source: "cloud_tenant",
   };
 }

server/src/middleware/cloud-tenant-actor.test.ts

@@ -0,0 +1,105 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import type { Request } from "express";
+import type { Db } from "@paperclipai/db";
+import { authUsers, companies, companyMemberships, instanceUserRoles } from "@paperclipai/db";
+import { resolveCloudTenantActor } from "./auth.js";
+
+// Minimal fake Drizzle Db: records every table passed to .insert() / .delete() and
+// supports the chained call shapes used by resolveCloudTenantActor (values /
+// onConflictDo* / returning().then() / delete().where()). The chain is awaitable so
+// directly-awaited statements resolve.
+function createFakeDb(membershipRow = { companyId: "company-x", membershipRole: "owner", status: "active" }) {
+  const insertedTables: unknown[] = [];
+  const deletedTables: unknown[] = [];
+  const chain: Record<string, unknown> = {};
+  chain.values = () => chain;
+  chain.onConflictDoUpdate = () => chain;
+  chain.onConflictDoNothing = () => chain;
+  chain.where = () => chain;
+  chain.returning = async () => [membershipRow];
+  chain.then = (resolve: (v: unknown) => unknown) => Promise.resolve(undefined).then(resolve);
+  const db = {
+    insert: (table: unknown) => {
+      insertedTables.push(table);
+      return chain;
+    },
+    delete: (table: unknown) => {
+      deletedTables.push(table);
+      return chain;
+    },
+  } as unknown as Db;
+  return { db, insertedTables, deletedTables };
+}
+
+function fakeReq(headers: Record<string, string>): Request {
+  const lower: Record<string, string> = {};
+  for (const [k, v] of Object.entries(headers)) lower[k.toLowerCase()] = v;
+  return { header: (name: string) => lower[name.toLowerCase()] } as unknown as Request;
+}
+
+const VALID_HEADERS = {
+  "x-paperclip-cloud-tenant-token": "test-server-token",
+  "x-paperclip-cloud-user-id": "user-123",
+  "x-paperclip-cloud-user-email": "Owner@Example.com",
+  "x-paperclip-cloud-stack-id": "stack-abc",
+  "x-paperclip-cloud-stack-role": "owner",
+};
+
+describe("resolveCloudTenantActor (shared-pool hardening)", () => {
+  beforeEach(() => {
+    process.env.PAPERCLIP_CLOUD_TENANT_SERVER_TOKEN = "test-server-token";
+  });
+  afterEach(() => {
+    delete process.env.PAPERCLIP_CLOUD_TENANT_SERVER_TOKEN;
+  });
+
+  it("never grants instance admin", async () => {
+    const { db, insertedTables } = createFakeDb();
+    const actor = await resolveCloudTenantActor(db, fakeReq(VALID_HEADERS));
+    expect(actor).not.toBeNull();
+    expect(actor!.isInstanceAdmin).toBe(false);
+    expect(insertedTables).not.toContain(instanceUserRoles);
+  });
+
+  it("is scoped to exactly the one company from its stack", async () => {
+    const { db } = createFakeDb();
+    const actor = await resolveCloudTenantActor(db, fakeReq(VALID_HEADERS));
+    expect(actor!.companyIds).toHaveLength(1);
+    expect(actor!.memberships).toHaveLength(1);
+    expect(actor?.memberships?.[0]?.companyId).toBe(actor?.companyIds?.[0]);
+    expect(actor?.memberships?.[0]?.membershipRole).toBe("owner");
+    expect(actor!.source).toBe("cloud_tenant");
+  });
+
+  it("purges stale instance_admin rows left by pre-hardening deployments", async () => {
+    const { db, deletedTables } = createFakeDb();
+    const actor = await resolveCloudTenantActor(db, fakeReq(VALID_HEADERS));
+    expect(actor).not.toBeNull();
+    expect(deletedTables).toContain(instanceUserRoles);
+  });
+
+  it("still upserts the user, company, and membership", async () => {
+    const { db, insertedTables } = createFakeDb();
+    await resolveCloudTenantActor(db, fakeReq(VALID_HEADERS));
+    expect(insertedTables).toContain(authUsers);
+    expect(insertedTables).toContain(companies);
+    expect(insertedTables).toContain(companyMemberships);
+  });
+
+  it("returns null when the server token is unset", async () => {
+    delete process.env.PAPERCLIP_CLOUD_TENANT_SERVER_TOKEN;
+    const { db } = createFakeDb();
+    const actor = await resolveCloudTenantActor(db, fakeReq(VALID_HEADERS));
+    expect(actor).toBeNull();
+  });
+
+  it("maps a non-owner stack role through to the membership without elevating", async () => {
+    const { db } = createFakeDb({ companyId: "company-y", membershipRole: "member", status: "active" });
+    const actor = await resolveCloudTenantActor(
+      db,
+      fakeReq({ ...VALID_HEADERS, "x-paperclip-cloud-stack-role": "member" }),
+    );
+    expect(actor!.isInstanceAdmin).toBe(false);
+    expect(actor?.memberships?.[0]?.membershipRole).toBe("member");
+  });
+});