@classytic/arc 1.1.0 → 2.1.3

package/dist/org/index.mjs

@@ -0,0 +1,513 @@
+import { c as isElevated, i as getOrgRoles, l as isMember, n as PUBLIC_SCOPE, o as hasOrgAccess } from "../types-Beqn1Un7.mjs";
+import fp from "fastify-plugin";
+
+//#region src/org/orgGuard.ts
+/**
+* Create org guard middleware.
+* Reads `request.scope` for org context and roles.
+* Elevated scope always passes.
+*/
+function orgGuard(options = {}) {
+	const { requireOrgContext = true, roles = [] } = options;
+	return async function orgGuardMiddleware(request, reply) {
+		const scope = request.scope ?? PUBLIC_SCOPE;
+		if (isElevated(scope)) return;
+		if (requireOrgContext && !hasOrgAccess(scope)) {
+			reply.code(403).send({
+				success: false,
+				error: "Organization context required",
+				code: "ORG_CONTEXT_REQUIRED",
+				message: "This endpoint requires an organization context. Please specify organization via x-organization-id header."
+			});
+			return;
+		}
+		if (roles.length > 0 && isMember(scope)) {
+			const userOrgRoles = getOrgRoles(scope);
+			if (!roles.some((role) => userOrgRoles.includes(role))) {
+				reply.code(403).send({
+					success: false,
+					error: "Insufficient organization permissions",
+					code: "ORG_ROLE_REQUIRED",
+					message: `This action requires one of these organization roles: ${roles.join(", ")}`,
+					required: roles,
+					current: userOrgRoles
+				});
+				return;
+			}
+		}
+	};
+}
+/**
+* Shorthand for requiring org context
+*/
+function requireOrg() {
+	return orgGuard({ requireOrgContext: true });
+}
+/**
+* Require org context with specific roles
+*/
+function requireOrgRole(...roles) {
+	return orgGuard({
+		requireOrgContext: true,
+		roles
+	});
+}
+
+//#endregion
+//#region src/org/orgMembership.ts
+/**
+* Check if user is member of organization.
+* This is a low-level utility for checking membership from user object data.
+* For request-level checks, use `request.scope` (isMember/isElevated guards).
+*/
+async function orgMembershipCheck(user, orgId, options = {}) {
+	const { userOrgsPath = "organizations", validateFromDb } = options;
+	if (!user || !orgId) return false;
+	if ((user[userOrgsPath] ?? []).some((o) => {
+		return (o.organizationId?.toString() ?? String(o)) === orgId.toString();
+	})) return true;
+	if (validateFromDb) {
+		const userId = (user._id ?? user.id)?.toString();
+		if (userId) return validateFromDb(userId, orgId);
+	}
+	return false;
+}
+/**
+* Get user's role in organization from user object data.
+* For request-level role checks, use `request.scope.orgRoles` (when scope is 'member').
+*/
+function getUserOrgRoles(user, orgId, options = {}) {
+	const { userOrgsPath = "organizations" } = options;
+	if (!user || !orgId) return [];
+	return (user[userOrgsPath] ?? []).find((o) => {
+		return (o.organizationId?.toString() ?? String(o)) === orgId.toString();
+	})?.roles ?? [];
+}
+/**
+* Check if user has specific role in organization from user object data.
+* For request-level role checks, use `requireOrgRole()` permission or `request.scope`.
+*/
+function hasOrgRole(user, orgId, roles, options = {}) {
+	const userOrgRoles = getUserOrgRoles(user, orgId, options);
+	return (Array.isArray(roles) ? roles : [roles]).some((role) => userOrgRoles.includes(role));
+}
+
+//#endregion
+//#region src/org/organizationPlugin.ts
+/**
+* Organization Plugin -- Full org management with REST endpoints
+*
+* Creates these routes:
+* - POST   /api/organizations                          -- Create org
+* - GET    /api/organizations                          -- List user's orgs
+* - GET    /api/organizations/:orgId                   -- Get org
+* - PATCH  /api/organizations/:orgId                   -- Update org
+* - DELETE /api/organizations/:orgId                   -- Delete org
+* - GET    /api/organizations/:orgId/members           -- List members
+* - POST   /api/organizations/:orgId/members           -- Add member
+* - PATCH  /api/organizations/:orgId/members/:userId   -- Update role
+* - DELETE /api/organizations/:orgId/members/:userId   -- Remove member
+*
+* @example
+* import { organizationPlugin } from '@classytic/arc/org';
+*
+* await fastify.register(organizationPlugin, {
+*   adapter: myMongooseOrgAdapter,
+*   basePath: '/api/organizations',
+*   enableInvitations: false,
+* });
+*/
+const DEFAULT_ROLES = [
+	{
+		name: "owner",
+		permissions: [{
+			resource: "*",
+			action: ["*"]
+		}]
+	},
+	{
+		name: "admin",
+		permissions: [{
+			resource: "org",
+			action: ["read", "update"]
+		}, {
+			resource: "members",
+			action: ["*"]
+		}]
+	},
+	{
+		name: "member",
+		permissions: [{
+			resource: "org",
+			action: ["read"]
+		}, {
+			resource: "members",
+			action: ["read"]
+		}]
+	}
+];
+/** Extract a UserBase from the request (set by auth plugin). */
+function getUser(request) {
+	return request.user;
+}
+/** Get user id (supports both `id` and `_id`). */
+function getUserId(user) {
+	const raw = user.id ?? user._id;
+	return raw ? String(raw) : void 0;
+}
+/** Standard JSON error reply. */
+function sendError(reply, statusCode, code, message) {
+	reply.code(statusCode).send({
+		success: false,
+		code,
+		error: message
+	});
+}
+const organizationPlugin = async (fastify, opts) => {
+	const { adapter, roles = DEFAULT_ROLES, basePath = "/api/organizations", enableInvitations = false } = opts;
+	const validRoleNames = new Set(roles.map((r) => r.name));
+	/**
+	* Create a preHandler that:
+	* 1. Ensures the request is authenticated
+	* 2. Looks up the caller's membership in the org identified by `:orgId`
+	* 3. Verifies the caller holds one of the required roles
+	*/
+	fastify.decorate("requireOrgRole", function requireOrgRole(requiredRoles) {
+		return async function requireOrgRoleHandler(request, reply) {
+			const user = getUser(request);
+			if (!user) {
+				sendError(reply, 401, "UNAUTHORIZED", "Authentication required");
+				return;
+			}
+			const userId = getUserId(user);
+			if (!userId) {
+				sendError(reply, 401, "UNAUTHORIZED", "Unable to determine user identity");
+				return;
+			}
+			const { orgId } = request.params;
+			if (!orgId) {
+				sendError(reply, 400, "MISSING_ORG_ID", "Organization ID is required");
+				return;
+			}
+			const member = await adapter.getMember(orgId, userId);
+			if (!member) {
+				sendError(reply, 403, "NOT_A_MEMBER", "You are not a member of this organization");
+				return;
+			}
+			if (!requiredRoles.includes(member.role)) {
+				sendError(reply, 403, "INSUFFICIENT_ROLE", `This action requires one of these roles: ${requiredRoles.join(", ")}`);
+				return;
+			}
+		};
+	});
+	/** Wrap preHandlers so that authenticate is called first (if available). */
+	function withAuth(...extra) {
+		const handlers = [];
+		const inst = fastify;
+		if (typeof inst.authenticate === "function") handlers.push(inst.authenticate);
+		handlers.push(...extra);
+		return handlers;
+	}
+	function generateSlug(name) {
+		return name.toLowerCase().trim().replace(/[^\w\s-]/g, "").replace(/[\s_]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+	}
+	/**
+	* POST / -- Create organization
+	*
+	* Body: { name: string; slug?: string; [key: string]: unknown }
+	* The authenticated user becomes the owner.
+	*/
+	fastify.post(basePath, { preHandler: withAuth() }, async (request, reply) => {
+		const user = getUser(request);
+		if (!user) {
+			sendError(reply, 401, "UNAUTHORIZED", "Authentication required");
+			return;
+		}
+		const userId = getUserId(user);
+		if (!userId) {
+			sendError(reply, 401, "UNAUTHORIZED", "Unable to determine user identity");
+			return;
+		}
+		const body = request.body;
+		if (!body?.name) {
+			sendError(reply, 400, "VALIDATION_ERROR", "Organization name is required");
+			return;
+		}
+		const slug = body.slug ?? generateSlug(body.name);
+		if (await adapter.getOrgBySlug(slug)) {
+			sendError(reply, 409, "SLUG_TAKEN", `An organization with slug '${slug}' already exists`);
+			return;
+		}
+		const org = await adapter.createOrg({
+			...body,
+			name: body.name,
+			slug,
+			ownerId: userId
+		});
+		await adapter.addMember(org.id, userId, "owner");
+		reply.code(201).send({
+			success: true,
+			data: org
+		});
+	});
+	/**
+	* GET / -- List the authenticated user's organizations
+	*/
+	fastify.get(basePath, { preHandler: withAuth() }, async (request, reply) => {
+		const user = getUser(request);
+		if (!user) {
+			sendError(reply, 401, "UNAUTHORIZED", "Authentication required");
+			return;
+		}
+		const userId = getUserId(user);
+		if (!userId) {
+			sendError(reply, 401, "UNAUTHORIZED", "Unable to determine user identity");
+			return;
+		}
+		const orgs = await adapter.listUserOrgs(userId);
+		reply.send({
+			success: true,
+			data: orgs
+		});
+	});
+	/**
+	* GET /:orgId -- Get a single organization
+	*/
+	fastify.get(`${basePath}/:orgId`, { preHandler: withAuth(fastify.requireOrgRole([
+		"owner",
+		"admin",
+		"member"
+	])) }, async (request, reply) => {
+		const { orgId } = request.params;
+		const org = await adapter.getOrg(orgId);
+		if (!org) {
+			sendError(reply, 404, "NOT_FOUND", "Organization not found");
+			return;
+		}
+		reply.send({
+			success: true,
+			data: org
+		});
+	});
+	/**
+	* PATCH /:orgId -- Update organization
+	*/
+	fastify.patch(`${basePath}/:orgId`, { preHandler: withAuth(fastify.requireOrgRole(["owner", "admin"])) }, async (request, reply) => {
+		const { orgId } = request.params;
+		const body = request.body;
+		if (!body || Object.keys(body).length === 0) {
+			sendError(reply, 400, "VALIDATION_ERROR", "Request body must not be empty");
+			return;
+		}
+		const { ownerId: _ownerId, id: _id, ...updates } = body;
+		const org = await adapter.updateOrg(orgId, updates);
+		if (!org) {
+			sendError(reply, 404, "NOT_FOUND", "Organization not found");
+			return;
+		}
+		reply.send({
+			success: true,
+			data: org
+		});
+	});
+	/**
+	* DELETE /:orgId -- Delete organization (owner only)
+	*/
+	fastify.delete(`${basePath}/:orgId`, { preHandler: withAuth(fastify.requireOrgRole(["owner"])) }, async (request, reply) => {
+		const { orgId } = request.params;
+		if (!await adapter.getOrg(orgId)) {
+			sendError(reply, 404, "NOT_FOUND", "Organization not found");
+			return;
+		}
+		await adapter.deleteOrg(orgId);
+		reply.send({
+			success: true,
+			message: "Organization deleted"
+		});
+	});
+	/**
+	* GET /:orgId/members -- List members
+	*/
+	fastify.get(`${basePath}/:orgId/members`, { preHandler: withAuth(fastify.requireOrgRole([
+		"owner",
+		"admin",
+		"member"
+	])) }, async (request, reply) => {
+		const { orgId } = request.params;
+		const members = await adapter.listMembers(orgId);
+		reply.send({
+			success: true,
+			data: members
+		});
+	});
+	/**
+	* POST /:orgId/members -- Add a member
+	*
+	* Body: { userId: string; role: string }
+	*/
+	fastify.post(`${basePath}/:orgId/members`, { preHandler: withAuth(fastify.requireOrgRole(["owner", "admin"])) }, async (request, reply) => {
+		const { orgId } = request.params;
+		const body = request.body;
+		if (!body?.userId || !body.role) {
+			sendError(reply, 400, "VALIDATION_ERROR", "userId and role are required");
+			return;
+		}
+		if (!validRoleNames.has(body.role)) {
+			sendError(reply, 400, "INVALID_ROLE", `Invalid role '${body.role}'. Valid roles: ${[...validRoleNames].join(", ")}`);
+			return;
+		}
+		if (await adapter.getMember(orgId, body.userId)) {
+			sendError(reply, 409, "ALREADY_MEMBER", "User is already a member of this organization");
+			return;
+		}
+		const member = await adapter.addMember(orgId, body.userId, body.role);
+		reply.code(201).send({
+			success: true,
+			data: member
+		});
+	});
+	/**
+	* PATCH /:orgId/members/:userId -- Update a member's role
+	*
+	* Body: { role: string }
+	*/
+	fastify.patch(`${basePath}/:orgId/members/:userId`, { preHandler: withAuth(fastify.requireOrgRole(["owner", "admin"])) }, async (request, reply) => {
+		const { orgId, userId } = request.params;
+		const body = request.body;
+		if (!body?.role) {
+			sendError(reply, 400, "VALIDATION_ERROR", "role is required");
+			return;
+		}
+		if (!validRoleNames.has(body.role)) {
+			sendError(reply, 400, "INVALID_ROLE", `Invalid role '${body.role}'. Valid roles: ${[...validRoleNames].join(", ")}`);
+			return;
+		}
+		const currentMember = await adapter.getMember(orgId, userId);
+		if (!currentMember) {
+			sendError(reply, 404, "NOT_FOUND", "Member not found");
+			return;
+		}
+		if (currentMember.role === "owner" && body.role !== "owner") {
+			if ((await adapter.listMembers(orgId)).filter((m) => m.role === "owner").length <= 1) {
+				sendError(reply, 400, "LAST_OWNER", "Cannot change the role of the last owner. Transfer ownership first.");
+				return;
+			}
+		}
+		const member = await adapter.updateMemberRole(orgId, userId, body.role);
+		if (!member) {
+			sendError(reply, 404, "NOT_FOUND", "Member not found");
+			return;
+		}
+		reply.send({
+			success: true,
+			data: member
+		});
+	});
+	/**
+	* DELETE /:orgId/members/:userId -- Remove a member
+	*/
+	fastify.delete(`${basePath}/:orgId/members/:userId`, { preHandler: withAuth(fastify.requireOrgRole(["owner", "admin"])) }, async (request, reply) => {
+		const { orgId, userId } = request.params;
+		const member = await adapter.getMember(orgId, userId);
+		if (!member) {
+			sendError(reply, 404, "NOT_FOUND", "Member not found");
+			return;
+		}
+		if (member.role === "owner") {
+			if ((await adapter.listMembers(orgId)).filter((m) => m.role === "owner").length <= 1) {
+				sendError(reply, 400, "LAST_OWNER", "Cannot remove the last owner. Transfer ownership or delete the organization.");
+				return;
+			}
+		}
+		await adapter.removeMember(orgId, userId);
+		reply.send({
+			success: true,
+			message: "Member removed"
+		});
+	});
+	if (enableInvitations && adapter.invitations) {
+		const inv = adapter.invitations;
+		/**
+		* POST /:orgId/invitations -- Create invitation
+		*
+		* Body: { email: string; role: string; expiresAt?: string }
+		*/
+		fastify.post(`${basePath}/:orgId/invitations`, { preHandler: withAuth(fastify.requireOrgRole(["owner", "admin"])) }, async (request, reply) => {
+			const user = getUser(request);
+			const userId = user ? getUserId(user) : void 0;
+			if (!userId) {
+				sendError(reply, 401, "UNAUTHORIZED", "Authentication required");
+				return;
+			}
+			const { orgId } = request.params;
+			const body = request.body;
+			if (!body?.email || !body.role) {
+				sendError(reply, 400, "VALIDATION_ERROR", "email and role are required");
+				return;
+			}
+			if (!validRoleNames.has(body.role)) {
+				sendError(reply, 400, "INVALID_ROLE", `Invalid role '${body.role}'. Valid roles: ${[...validRoleNames].join(", ")}`);
+				return;
+			}
+			const defaultExpiry = new Date(Date.now() + 10080 * 60 * 1e3);
+			const expiresAt = body.expiresAt ? new Date(body.expiresAt) : defaultExpiry;
+			const invitation = await inv.create({
+				orgId,
+				email: body.email,
+				role: body.role,
+				invitedBy: userId,
+				status: "pending",
+				expiresAt
+			});
+			reply.code(201).send({
+				success: true,
+				data: invitation
+			});
+		});
+		/**
+		* GET /:orgId/invitations -- List pending invitations
+		*/
+		fastify.get(`${basePath}/:orgId/invitations`, { preHandler: withAuth(fastify.requireOrgRole(["owner", "admin"])) }, async (request, reply) => {
+			const { orgId } = request.params;
+			const invitations = await inv.listPending(orgId);
+			reply.send({
+				success: true,
+				data: invitations
+			});
+		});
+		/**
+		* POST /invitations/:invitationId/accept -- Accept invitation
+		*/
+		fastify.post(`${basePath}/invitations/:invitationId/accept`, { preHandler: withAuth() }, async (request, reply) => {
+			const { invitationId } = request.params;
+			await inv.accept(invitationId);
+			reply.send({
+				success: true,
+				message: "Invitation accepted"
+			});
+		});
+		/**
+		* POST /invitations/:invitationId/reject -- Reject invitation
+		*/
+		fastify.post(`${basePath}/invitations/:invitationId/reject`, { preHandler: withAuth() }, async (request, reply) => {
+			const { invitationId } = request.params;
+			await inv.reject(invitationId);
+			reply.send({
+				success: true,
+				message: "Invitation rejected"
+			});
+		});
+	}
+	fastify.log?.debug?.({
+		basePath,
+		roles: [...validRoleNames],
+		invitations: enableInvitations
+	}, "Organization plugin registered");
+};
+var organizationPlugin_default = fp(organizationPlugin, {
+	name: "arc-organization",
+	fastify: "5.x"
+});
+
+//#endregion
+export { getUserOrgRoles, hasOrgRole, orgGuard, orgMembershipCheck, organizationPlugin_default as organizationPlugin, organizationPlugin as organizationPluginFn, requireOrg, requireOrgRole };

package/dist/org/types.d.mts

@@ -0,0 +1,82 @@
+//#region src/org/types.d.ts
+/**
+ * Organization types -- adapter interfaces for multi-tenant applications.
+ * Arc defines the contract, apps implement it.
+ */
+interface OrgDoc {
+  id: string;
+  name: string;
+  slug: string;
+  ownerId: string;
+  metadata?: Record<string, unknown>;
+  createdAt?: Date;
+  updatedAt?: Date;
+  [key: string]: unknown;
+}
+interface MemberDoc {
+  id: string;
+  orgId: string;
+  userId: string;
+  role: string;
+  createdAt?: Date;
+  updatedAt?: Date;
+  [key: string]: unknown;
+}
+interface InvitationDoc {
+  id: string;
+  orgId: string;
+  email: string;
+  role: string;
+  invitedBy: string;
+  status: 'pending' | 'accepted' | 'rejected' | 'expired';
+  expiresAt: Date;
+  createdAt?: Date;
+}
+/** Core organization adapter -- apps implement this */
+interface OrgAdapter {
+  createOrg(data: {
+    name: string;
+    slug: string;
+    ownerId: string;
+    [key: string]: unknown;
+  }): Promise<OrgDoc>;
+  getOrg(id: string): Promise<OrgDoc | null>;
+  getOrgBySlug(slug: string): Promise<OrgDoc | null>;
+  updateOrg(id: string, data: Partial<OrgDoc>): Promise<OrgDoc | null>;
+  deleteOrg(id: string): Promise<void>;
+  listUserOrgs(userId: string): Promise<OrgDoc[]>;
+  addMember(orgId: string, userId: string, role: string): Promise<MemberDoc>;
+  removeMember(orgId: string, userId: string): Promise<void>;
+  getMember(orgId: string, userId: string): Promise<MemberDoc | null>;
+  listMembers(orgId: string): Promise<MemberDoc[]>;
+  updateMemberRole(orgId: string, userId: string, role: string): Promise<MemberDoc | null>;
+  invitations?: InvitationAdapter;
+}
+interface InvitationAdapter {
+  create(data: Omit<InvitationDoc, 'id' | 'createdAt'>): Promise<InvitationDoc>;
+  getByToken(token: string): Promise<InvitationDoc | null>;
+  accept(id: string): Promise<void>;
+  reject(id: string): Promise<void>;
+  listPending(orgId: string): Promise<InvitationDoc[]>;
+}
+/** Statement-based permission check */
+interface OrgPermissionStatement {
+  resource: string;
+  action: string[];
+}
+/** Role definition with permissions */
+interface OrgRole {
+  name: string;
+  permissions: OrgPermissionStatement[];
+}
+interface OrganizationPluginOptions {
+  adapter: OrgAdapter;
+  /** Built-in roles (default: owner, admin, member) */
+  roles?: OrgRole[];
+  /** Base path for org API routes (default: '/api/organizations') */
+  basePath?: string;
+  /** Enable invitation system */
+  enableInvitations?: boolean;
+}
+//#endregion
+export { InvitationAdapter, InvitationDoc, MemberDoc, OrgAdapter, OrgDoc, OrgPermissionStatement, OrgRole, OrganizationPluginOptions };

package/dist/org/types.mjs

@@ -0,0 +1 @@
+export {  };