diff --git a/src/lib/projects/authz.test.ts b/src/lib/projects/authz.test.ts new file mode 100644 index 00000000..11681c59 --- /dev/null +++ b/src/lib/projects/authz.test.ts @@ -0,0 +1,270 @@ +import { describe, expect, it } from "vitest"; +import { + canManageProject, + canUpdateStage, + canUploadEvidence, + canViewProject, + isInternalEmail, + resolveProjectRole, + type AuthzUser, + type ProjectAuthzFacts, + type WorkOrderAuthzFacts, +} from "./authz"; + +const CLIENT_ORG = "11111111-1111-1111-1111-111111111111"; +const CONTRACTOR_ORG = "22222222-2222-2222-2222-222222222222"; +const OTHER_CONTRACTOR_ORG = "33333333-3333-3333-3333-333333333333"; +const UNRELATED_ORG = "44444444-4444-4444-4444-444444444444"; + +function makeUser(overrides: Partial = {}): AuthzUser { + return { + id: 1n, + email: "someone@landlord.example", + organisationIds: [], + ...overrides, + }; +} + +function makeProject(overrides: Partial = {}): ProjectAuthzFacts { + return { + id: 100n, + organisationId: CLIENT_ORG, + domnaAdminAccess: true, + contractorOrganisationIds: [CONTRACTOR_ORG, OTHER_CONTRACTOR_ORG], + ...overrides, + }; +} + +function makeWorkOrder( + overrides: Partial = {}, +): WorkOrderAuthzFacts { + return { + id: 500n, + contractorOrganisationId: CONTRACTOR_ORG, + updateStagesPermission: false, + uploadDocumentsPermission: false, + ...overrides, + }; +} + +const internal = makeUser({ email: "dev@domna.homes" }); +const client = makeUser({ organisationIds: [CLIENT_ORG] }); +const contractor = makeUser({ organisationIds: [CONTRACTOR_ORG] }); +const stranger = makeUser({ organisationIds: [UNRELATED_ORG] }); + +describe("isInternalEmail", () => { + it("recognises the Domna domain regardless of case or surrounding whitespace", () => { + expect(isInternalEmail("dev@domna.homes")).toBe(true); + expect(isInternalEmail(" Dev@Domna.Homes ")).toBe(true); + }); + + it("does not treat a lookalike domain as internal", () => { + expect(isInternalEmail("attacker@evil-domna.homes")).toBe(false); + expect(isInternalEmail("attacker@domna.homes.evil.com")).toBe(false); + expect(isInternalEmail("someone@landlord.example")).toBe(false); + }); +}); + +describe("resolveProjectRole", () => { + it("resolves a Domna user as internal when the project allows admin access", () => { + expect(resolveProjectRole(internal, makeProject())).toBe("internal"); + }); + + it("resolves a member of the owning organisation as client", () => { + expect(resolveProjectRole(client, makeProject())).toBe("client"); + }); + + it("resolves a member of an assigned contractor organisation as contractor", () => { + expect(resolveProjectRole(contractor, makeProject())).toBe("contractor"); + }); + + it("resolves a member of any assigned contractor org, not just the first", () => { + const user = makeUser({ organisationIds: [OTHER_CONTRACTOR_ORG] }); + expect(resolveProjectRole(user, makeProject())).toBe("contractor"); + }); + + it("gives no role to a user with no relevant membership", () => { + expect(resolveProjectRole(stranger, makeProject())).toBeNull(); + }); + + it("gives no role on a project with no contractors assigned yet", () => { + const project = makeProject({ contractorOrganisationIds: [] }); + expect(resolveProjectRole(contractor, project)).toBeNull(); + }); + + it("ranks client above contractor when one org is both owner and contractor", () => { + const project = makeProject({ contractorOrganisationIds: [CLIENT_ORG] }); + expect(resolveProjectRole(client, project)).toBe("client"); + }); + + describe("domna_admin_access = false", () => { + const locked = makeProject({ domnaAdminAccess: false }); + + it("denies a Domna user any role when they have no membership of their own", () => { + expect(resolveProjectRole(internal, locked)).toBeNull(); + }); + + it("still resolves a Domna user as client when they belong to the owning org", () => { + const domnaClient = makeUser({ + email: "dev@domna.homes", + organisationIds: [CLIENT_ORG], + }); + expect(resolveProjectRole(domnaClient, locked)).toBe("client"); + }); + + it("still resolves a Domna user as contractor when they belong to an assigned org", () => { + const domnaContractor = makeUser({ + email: "dev@domna.homes", + organisationIds: [CONTRACTOR_ORG], + }); + expect(resolveProjectRole(domnaContractor, locked)).toBe("contractor"); + }); + + it("does not affect a non-Domna client", () => { + expect(resolveProjectRole(client, locked)).toBe("client"); + }); + }); +}); + +describe("canViewProject", () => { + it("admits every resolved role", () => { + const project = makeProject(); + expect(canViewProject(internal, project)).toBe(true); + expect(canViewProject(client, project)).toBe(true); + expect(canViewProject(contractor, project)).toBe(true); + }); + + it("refuses a user with no role", () => { + expect(canViewProject(stranger, makeProject())).toBe(false); + }); + + it("refuses a Domna user on a project with admin access switched off", () => { + expect(canViewProject(internal, makeProject({ domnaAdminAccess: false }))).toBe( + false, + ); + }); +}); + +describe("canManageProject", () => { + it("admits internal and client", () => { + const project = makeProject(); + expect(canManageProject(internal, project)).toBe(true); + expect(canManageProject(client, project)).toBe(true); + }); + + it("refuses a contractor even though they can view the project", () => { + const project = makeProject(); + expect(canViewProject(contractor, project)).toBe(true); + expect(canManageProject(contractor, project)).toBe(false); + }); + + it("refuses a user with no role", () => { + expect(canManageProject(stranger, makeProject())).toBe(false); + }); + + it("refuses a Domna user on a project with admin access switched off", () => { + expect( + canManageProject(internal, makeProject({ domnaAdminAccess: false })), + ).toBe(false); + }); +}); + +describe("canUpdateStage", () => { + const project = makeProject(); + + it("admits internal and client regardless of the assignment's flags", () => { + const workOrder = makeWorkOrder({ updateStagesPermission: false }); + expect(canUpdateStage(internal, project, workOrder)).toBe(true); + expect(canUpdateStage(client, project, workOrder)).toBe(true); + }); + + it("admits a contractor holding the assignment and the permission", () => { + const workOrder = makeWorkOrder({ updateStagesPermission: true }); + expect(canUpdateStage(contractor, project, workOrder)).toBe(true); + }); + + it("refuses a contractor whose assignment lacks update_stages_permission", () => { + const workOrder = makeWorkOrder({ updateStagesPermission: false }); + expect(canUpdateStage(contractor, project, workOrder)).toBe(false); + }); + + it("refuses a contractor from a different assigned org, even with the flag set", () => { + const other = makeUser({ organisationIds: [OTHER_CONTRACTOR_ORG] }); + const workOrder = makeWorkOrder({ + contractorOrganisationId: CONTRACTOR_ORG, + updateStagesPermission: true, + }); + expect(resolveProjectRole(other, project)).toBe("contractor"); + expect(canUpdateStage(other, project, workOrder)).toBe(false); + }); + + it("refuses a user with no role on the project", () => { + const workOrder = makeWorkOrder({ updateStagesPermission: true }); + expect(canUpdateStage(stranger, project, workOrder)).toBe(false); + }); + + it("refuses a Domna user when admin access is off and they have no membership", () => { + const locked = makeProject({ domnaAdminAccess: false }); + const workOrder = makeWorkOrder({ updateStagesPermission: true }); + expect(canUpdateStage(internal, locked, workOrder)).toBe(false); + }); + + it("ignores upload_documents_permission", () => { + const workOrder = makeWorkOrder({ + updateStagesPermission: false, + uploadDocumentsPermission: true, + }); + expect(canUpdateStage(contractor, project, workOrder)).toBe(false); + }); +}); + +describe("canUploadEvidence", () => { + const project = makeProject(); + + it("admits internal and client regardless of the assignment's flags", () => { + const workOrder = makeWorkOrder({ uploadDocumentsPermission: false }); + expect(canUploadEvidence(internal, project, workOrder)).toBe(true); + expect(canUploadEvidence(client, project, workOrder)).toBe(true); + }); + + it("admits a contractor holding the assignment and the permission", () => { + const workOrder = makeWorkOrder({ uploadDocumentsPermission: true }); + expect(canUploadEvidence(contractor, project, workOrder)).toBe(true); + }); + + it("refuses a contractor whose assignment lacks upload_documents_permission", () => { + const workOrder = makeWorkOrder({ uploadDocumentsPermission: false }); + expect(canUploadEvidence(contractor, project, workOrder)).toBe(false); + }); + + it("refuses a contractor from a different assigned org, even with the flag set", () => { + const other = makeUser({ organisationIds: [OTHER_CONTRACTOR_ORG] }); + const workOrder = makeWorkOrder({ + contractorOrganisationId: CONTRACTOR_ORG, + uploadDocumentsPermission: true, + }); + expect(canUploadEvidence(other, project, workOrder)).toBe(false); + }); + + it("refuses a user with no role on the project", () => { + const workOrder = makeWorkOrder({ uploadDocumentsPermission: true }); + expect(canUploadEvidence(stranger, project, workOrder)).toBe(false); + }); + + it("ignores update_stages_permission", () => { + const workOrder = makeWorkOrder({ + uploadDocumentsPermission: false, + updateStagesPermission: true, + }); + expect(canUploadEvidence(contractor, project, workOrder)).toBe(false); + }); + + it("is independent of canUpdateStage — the two flags grant separately", () => { + const uploadOnly = makeWorkOrder({ + updateStagesPermission: false, + uploadDocumentsPermission: true, + }); + expect(canUpdateStage(contractor, project, uploadOnly)).toBe(false); + expect(canUploadEvidence(contractor, project, uploadOnly)).toBe(true); + }); +}); diff --git a/src/lib/projects/authz.ts b/src/lib/projects/authz.ts new file mode 100644 index 00000000..a65b0588 --- /dev/null +++ b/src/lib/projects/authz.ts @@ -0,0 +1,180 @@ +/** + * Ara Projects authorization — the single source of permission truth for every + * Ara Projects route handler (issue #408). No route may re-implement any of + * this inline. + * + * This module is deliberately **pure**: it imports no database client, so the + * guards unit-test without mocking a connection pool. The DB-backed resolvers + * that produce its inputs live next door in `./authzQueries` — a route handler + * loads facts there, then decides here. + * + * const [user, project] = await Promise.all([ + * loadAuthzUser(userId), + * loadProjectAuthzFacts(projectId), + * ]); + * if (!canViewProject(user, project)) return forbidden(); + * + * Scoping note: Ara Projects are **organisation**-scoped. The existing + * `team_portfolio_permissions` machinery is portfolio-scoped and plays no part + * here — do not reach for it. A user's organisations come from + * `team_members → team → org_id` (see CONTEXT.md, "Ara Projects"). + */ + +/** The email domain that identifies a Domna (internal) user. */ +export const INTERNAL_EMAIL_DOMAIN = "@domna.homes"; + +/** + * A user's standing on one particular Project. + * + * - `internal` — a Domna user, on a project that opts into admin access. + * - `client` — a member of the organisation that owns the project. + * - `contractor` — a member of an organisation assigned to one of the + * project's workstreams. + * + * Absence of a role (`null`) means no access at all, not read-only access. + */ +export type ProjectRole = "internal" | "client" | "contractor"; + +/** The requesting user, with their organisation memberships already resolved. */ +export interface AuthzUser { + id: bigint; + email: string; + /** `organisation.id` values (uuid) reached via team_members → team → org_id. */ + organisationIds: string[]; +} + +/** The permission-relevant facts about one Project. */ +export interface ProjectAuthzFacts { + id: bigint; + /** `project.organisation_id` — the client organisation that owns the project. */ + organisationId: string; + /** `project.domna_admin_access` — see `resolveProjectRole`. */ + domnaAdminAccess: boolean; + /** + * Every organisation assigned as contractor to any of this project's + * workstreams, via `project_workstream_contractor`. + */ + contractorOrganisationIds: string[]; +} + +/** + * The permission-relevant facts about one Work order, flattened from its + * `project_workstream_contractor` assignment. The permission flags belong to + * the *assignment*, not to the organisation globally — the same contractor org + * may hold different permissions on two workstreams of the same project. + */ +export interface WorkOrderAuthzFacts { + id: bigint; + /** `project_workstream_contractor.organisation_id` for this work order. */ + contractorOrganisationId: string; + updateStagesPermission: boolean; + uploadDocumentsPermission: boolean; +} + +/** True when the email sits on the Domna domain (case- and whitespace-tolerant). */ +export function isInternalEmail(email: string): boolean { + return email.trim().toLowerCase().endsWith(INTERNAL_EMAIL_DOMAIN); +} + +/** + * Resolve what a user is to a project, most-privileged first. + * + * `project.domna_admin_access` gates the `internal` role only: when it is + * false, a Domna user gets no elevated standing on that project, but still + * falls through to whatever their organisation memberships earn them — a Domna + * user who is genuinely a member of the client org remains a `client`. + * + * Client outranks contractor: an organisation that both owns the project and + * delivers one of its workstreams is treated as the client. + */ +export function resolveProjectRole( + user: AuthzUser, + project: ProjectAuthzFacts, +): ProjectRole | null { + if (project.domnaAdminAccess && isInternalEmail(user.email)) return "internal"; + + const memberships = new Set(user.organisationIds); + if (memberships.has(project.organisationId)) return "client"; + if (project.contractorOrganisationIds.some((orgId) => memberships.has(orgId))) { + return "contractor"; + } + return null; +} + +/** Any resolved role may read the project. */ +export function canViewProject( + user: AuthzUser, + project: ProjectAuthzFacts, +): boolean { + return resolveProjectRole(user, project) !== null; +} + +/** + * Administering the project — editing it, configuring workstreams, assigning + * contractors. Internal and client only; a contractor never manages. + */ +export function canManageProject( + user: AuthzUser, + project: ProjectAuthzFacts, +): boolean { + const role = resolveProjectRole(user, project); + return role === "internal" || role === "client"; +} + +/** + * Move a Work order along its stage ladder. + * + * Internal and client may always do so. A contractor may only when the work + * order is issued to an organisation they belong to *and* that assignment + * carries `update_stages_permission` — belonging to some *other* assigned org + * on the same project is not enough. + */ +export function canUpdateStage( + user: AuthzUser, + project: ProjectAuthzFacts, + workOrder: WorkOrderAuthzFacts, +): boolean { + return allowsWorkOrderAction( + user, + project, + workOrder, + workOrder.updateStagesPermission, + ); +} + +/** + * Upload Evidence against a Work order. Same shape as `canUpdateStage`, gated + * on the assignment's `upload_documents_permission`. + */ +export function canUploadEvidence( + user: AuthzUser, + project: ProjectAuthzFacts, + workOrder: WorkOrderAuthzFacts, +): boolean { + return allowsWorkOrderAction( + user, + project, + workOrder, + workOrder.uploadDocumentsPermission, + ); +} + +/** + * The shared shape of the two work-order guards: privileged roles pass + * unconditionally, a contractor needs both the assignment and its flag, and + * anyone without a role is refused. + */ +function allowsWorkOrderAction( + user: AuthzUser, + project: ProjectAuthzFacts, + workOrder: WorkOrderAuthzFacts, + permissionFlag: boolean, +): boolean { + const role = resolveProjectRole(user, project); + if (role === "internal" || role === "client") return true; + if (role !== "contractor") return false; + return ( + user.organisationIds.includes(workOrder.contractorOrganisationId) && + permissionFlag + ); +} diff --git a/src/lib/projects/authzQueries.ts b/src/lib/projects/authzQueries.ts new file mode 100644 index 00000000..fea89557 --- /dev/null +++ b/src/lib/projects/authzQueries.ts @@ -0,0 +1,148 @@ +/** + * DB-backed fact loaders feeding the pure guards in `./authz` (issue #408). + * + * Kept separate from the guards so those stay unit-testable without a database. + * Route handlers load facts here, then decide with `authz`. + * + * Every loader is a single round trip; none probes per-row inside a list. + */ +import { db } from "@/app/db/db"; +import { and, eq, inArray } from "drizzle-orm"; +import { team, teamMembers } from "@/app/db/schema/team"; +import { user } from "@/app/db/schema/users"; +import { + project, + projectWorkstream, + projectWorkstreamContractor, + workOrder, +} from "@/app/db/schema/projects/projects"; +import type { + AuthzUser, + ProjectAuthzFacts, + WorkOrderAuthzFacts, +} from "./authz"; + +/** + * The organisations a user belongs to, via `team_members → team → org_id`. + * + * This is the *only* membership path Ara Projects recognises. Each + * organisation has a default team, so contractor and client users alike arrive + * through the existing team structures. Deduplicated: a user on two teams of + * one organisation yields that organisation once. + */ +export async function getUserOrganisations(userId: bigint): Promise { + const rows = await db + .selectDistinct({ orgId: team.orgId }) + .from(teamMembers) + .innerJoin(team, eq(teamMembers.teamId, team.id)) + .where(eq(teamMembers.userId, userId)); + + return rows.map((r) => r.orgId); +} + +/** + * Load a user plus their organisation memberships, ready to hand to a guard. + * Returns null when the user does not exist. + */ +export async function loadAuthzUser(userId: bigint): Promise { + const [[found], organisationIds] = await Promise.all([ + db + .select({ id: user.id, email: user.email }) + .from(user) + .where(eq(user.id, userId)) + .limit(1), + getUserOrganisations(userId), + ]); + + if (!found) return null; + return { id: found.id, email: found.email, organisationIds }; +} + +/** + * Load one project's permission-relevant facts, including every organisation + * assigned as contractor to any of its workstreams. Returns null when the + * project does not exist — callers should treat that as a 404, not a 403. + */ +export async function loadProjectAuthzFacts( + projectId: bigint, +): Promise { + const [[found], contractorRows] = await Promise.all([ + db + .select({ + id: project.id, + organisationId: project.organisationId, + domnaAdminAccess: project.domnaAdminAccess, + }) + .from(project) + .where(eq(project.id, projectId)) + .limit(1), + db + .selectDistinct({ organisationId: projectWorkstreamContractor.organisationId }) + .from(projectWorkstreamContractor) + .innerJoin( + projectWorkstream, + eq(projectWorkstreamContractor.projectWorkstreamId, projectWorkstream.id), + ) + .where(eq(projectWorkstream.projectId, projectId)), + ]); + + if (!found) return null; + return { + ...found, + contractorOrganisationIds: contractorRows.map((r) => r.organisationId), + }; +} + +/** + * Load one work order's contractor assignment facts. Returns null when the + * work order does not exist. + * + * `projectId` narrows the lookup to the project named in the request path, so + * a work-order id belonging to another project cannot be authorized against + * the facts of the project the caller happens to have access to. + */ +export async function loadWorkOrderAuthzFacts( + workOrderId: bigint, + projectId: bigint, +): Promise { + const [found] = await db + .select({ + id: workOrder.id, + contractorOrganisationId: projectWorkstreamContractor.organisationId, + updateStagesPermission: projectWorkstreamContractor.updateStagesPermission, + uploadDocumentsPermission: + projectWorkstreamContractor.uploadDocumentsPermission, + }) + .from(workOrder) + .innerJoin( + projectWorkstreamContractor, + eq(workOrder.projectWorkstreamContractorId, projectWorkstreamContractor.id), + ) + .innerJoin( + projectWorkstream, + eq(projectWorkstreamContractor.projectWorkstreamId, projectWorkstream.id), + ) + .where( + and(eq(workOrder.id, workOrderId), eq(projectWorkstream.projectId, projectId)), + ) + .limit(1); + + return found ?? null; +} + +/** + * The projects a set of organisations own, for list endpoints that must not + * leak projects the caller cannot see. Contractor visibility is resolved + * separately (a contractor sees a project through its workstream assignments), + * so this covers the client side only. + */ +export async function listProjectIdsForOrganisations( + organisationIds: string[], +): Promise { + if (organisationIds.length === 0) return []; + const rows = await db + .select({ id: project.id }) + .from(project) + .where(inArray(project.organisationId, organisationIds)); + return rows.map((r) => r.id); +}