fix(auth): admin member management works without the admin's own membership (#881)

adminAddMember forwarded the caller's headers into Better Auth's addMember,
which checks the caller's ORGANIZATION permissions — a platform admin who was
not a member of the target organization (the whole point of an admin route)
got FORBIDDEN. The mutation is now a direct write like the rest of
AdminOrganizationsService: membership-limit policy enforced, duplicate
memberships refused. Tests now cover adding a member to an organization the
admin does not belong to — the case the old fixtures masked by creating every
organization owned by the admin.

- adminUpdateMemberRole refuses to demote an organization's only owner,
  matching adminRemoveMember's last-owner guard
- getOrganizationForAdmin uses the standard requireAdmin middleware
- crossSubDomainCookies gains config-time warnings for the two silent
  browser failures: a cookie domain that does not cover the baseUrl host,
  and localhost/loopback base URLs
- README documents the full multi-app session recipe: shared cookie domain +
  shared BETTER_AUTH_SECRET + shared postgres:// AUTH_DATABASE_URL (ADR 0027)

Author: elliotBraem

.changeset/auth-admin-organization-member-direct.md

@@ -0,0 +1,27 @@
+---
+"everything-dev": patch
+---
+
+auth: admin member management no longer depends on the admin's own organization membership (#876 follow-up)
+
+`adminAddMember` forwarded the caller's headers into Better Auth's `addMember`, which checks the
+caller's **organization** permissions — so a platform admin who was not a member of the target
+organization (the whole point of an admin route) got FORBIDDEN. The mutation is now a direct write,
+like every other mutation in `AdminOrganizationsService`: it enforces the organization membership
+limit through the plugin's membership policy and refuses duplicate memberships. The integration
+suite now covers adding a member to an organization the admin does not belong to — the case the
+previous tests masked by creating every fixture organization owned by the admin.
+
+Two smaller consistency fixes ride along:
+
+- `adminUpdateMemberRole` refuses to demote an organization's **only owner** to a non-owner role,
+  matching `adminRemoveMember`'s existing last-owner guard.
+- `getOrganizationForAdmin` guards with the standard `requireAdmin` middleware instead of a
+  hand-rolled role check, matching the admin routes' pattern.
+
+`crossSubDomainCookies` (#668) also gained config-time warnings for the two ways a shared cookie
+domain fails silently at the browser: a `domain` that does not cover the app's own `baseUrl` host
+(browsers drop the cookie outright, breaking sign-in) and localhost/loopback base URLs (browsers
+refuse `Domain` attributes there). The auth plugin README now documents the full multi-app recipe —
+shared cookie domain + shared `BETTER_AUTH_SECRET` + shared `postgres://` `AUTH_DATABASE_URL` —
+mirroring the ADR 0027 decomposition.

plugins/auth/README.md

@@ -65,7 +65,15 @@ It runs inside the **everything-plugin** framework (oRPC + Effect) and is design
 
 `onboard` hrefs must be app paths (`/…`) or `https://` URLs. `links.next`, `links.home` and `community.url` replace `{organizationId}` with the joined organization's ID. A failed or invalid `community.url` response shows nothing extra.
 
-`crossSubDomainCookies` scopes the session cookie to a shared registrable domain so sibling subdomains (e.g. `app.example.com` and `api.example.com`) share one session. Every app on that domain must run the **same `BETTER_AUTH_SECRET`** — the cookie is sealed with it — and each app should list its siblings' origins in `trustedOrigins`. Absent or disabled config keeps cookies host-scoped.
+`crossSubDomainCookies` scopes the session cookie to a shared registrable domain so sibling subdomains (e.g. `app.example.com` and `api.example.com`) share one session. Absent or disabled config keeps cookies host-scoped.
+
+**Multi-app session sharing** — a family of apps whose sessions roam a shared registrable domain needs all three legs together; the cookie alone is not enough:
+
+1. **Shared cookie** — each app sets `crossSubDomainCookies: { enabled: true, domain: ".example.com" }` where `example.com` covers every app's host. A cookie whose `Domain` does not cover the app's own host is dropped by the browser, which breaks sign-in on that app (the boot warnings flag this, along with localhost hosts, which can never carry a `Domain` attribute).
+2. **Shared secret** — every app on the domain must run the **same `BETTER_AUTH_SECRET`**: the cookie is sealed with it, so a sibling that runs a different secret sees every incoming session as invalid and signs the user out.
+3. **Shared database** — every app's `AUTH_DATABASE_URL` must point at the **same `postgres://` database**. Auth tables live un-namespaced in that database (`namespace: false` — Better Auth's schema owns the public tables), so the shared cookie resolves the same session row everywhere. Without it, the cookie resolves to a session row the sibling cannot see and the request still reads as signed-out. The pglite default is per-identity and dev-only; cross-app session sharing is a `postgres://` setup.
+
+Each app should also cross-list its siblings' origins in `trustedOrigins`. The everything.dev family recipe this configuration mirrors is documented in `docs/adr/0027-apps-decomposition-every-app.md`.
 
 ### Plugin Secrets
 

plugins/auth/src/handlers/admin-organizations.ts

@@ -8,7 +8,6 @@ import type {
 } from "../middleware";
 import { AdminOrganizationsService } from "../services/admin-organizations";
 import { mapDomainError } from "../services/domain-errors";
-import { createHeaders } from "../utils";
 
 export function createAdminOrganizationHandlers(
   builder: Implementer<ContractType, AuthHandlerContext>,
@@ -59,9 +58,9 @@ export function createAdminOrganizationHandlers(
     adminAddMember: builder.adminAddMember
       .use(requireAuth)
       .use(requireAdmin)
-      .effect(function* ({ input, context }) {
+      .effect(function* ({ input }) {
         const admin = yield* AdminOrganizationsService;
-        return yield* mapDomainError(admin.addMember(createHeaders(context.reqHeaders), input));
+        return yield* mapDomainError(admin.addMember(input));
       }),
 
     adminRemoveMember: builder.adminRemoveMember

plugins/auth/src/handlers/organizations.ts

@@ -1,7 +1,11 @@
 import type { Implementer } from "@orpc/server";
-import { Effect } from "effect";
+import { createAuthMiddleware } from "everything-dev/api";
 import type { ContractType } from "../contract";
-import type { AuthHandlerContext, RequireAuthMiddleware } from "../middleware";
+import type {
+  AuthHandlerAuthedContext,
+  AuthHandlerContext,
+  RequireAuthMiddleware,
+} from "../middleware";
 import { mapDomainError } from "../services/domain-errors";
 import { OrganizationsService } from "../services/organizations";
 import { createHeaders } from "../utils";
@@ -10,6 +14,7 @@ export function createOrganizationHandlers(
   builder: Implementer<ContractType, AuthHandlerContext>,
   requireAuth: RequireAuthMiddleware,
 ) {
+  const { requireAdmin } = createAuthMiddleware<AuthHandlerAuthedContext>(builder);
   return {
     listOrganizations: builder.listOrganizations.use(requireAuth).effect(function* ({ context }) {
       const organizations = yield* OrganizationsService;
@@ -35,19 +40,13 @@ export function createOrganizationHandlers(
       );
     }),
 
-    getOrganizationForAdmin: builder.getOrganizationForAdmin.use(requireAuth).effect(function* ({
-      input,
-      context,
-      errors,
-    }) {
-      const organizations = yield* OrganizationsService;
-      if (context.user.role !== "admin") {
-        return yield* Effect.fail(
-          errors.FORBIDDEN({ message: "Admin access required", data: { action: "admin-access" } }),
-        );
-      }
-      return yield* mapDomainError(organizations.getOrganizationById(input.organizationId));
-    }),
+    getOrganizationForAdmin: builder.getOrganizationForAdmin
+      .use(requireAuth)
+      .use(requireAdmin)
+      .effect(function* ({ input }) {
+        const organizations = yield* OrganizationsService;
+        return yield* mapDomainError(organizations.getOrganizationById(input.organizationId));
+      }),
 
     createOrganization: builder.createOrganization.use(requireAuth).effect(function* ({
       input,

plugins/auth/src/index.ts

@@ -29,7 +29,7 @@ import { OrphanSweepLive } from "./orphan-sweep";
 import { AuthServicesTag } from "./service-types";
 import { buildAuthServicesLayer } from "./service-wiring";
 import { toError } from "./utils";
-import { socialProviderWarnings } from "./warnings";
+import { cookieDomainWarnings, socialProviderWarnings } from "./warnings";
 
 export default createPlugin.withPlugins<PluginsClient>()({
   variables: authVariablesSchema,
@@ -44,7 +44,7 @@ export default createPlugin.withPlugins<PluginsClient>()({
 
   servicesTag: AuthServicesTag,
 
-  warnings: socialProviderWarnings,
+  warnings: (config) => [...socialProviderWarnings(config), ...cookieDomainWarnings(config)],
 
   initialize: (config) =>
     Effect.gen(function* () {

plugins/auth/src/service-wiring.ts

@@ -89,6 +89,7 @@ export function buildAuthServicesLayer(services: PluginServices) {
       buildAdminOrganizationsService({
         auth: services.auth,
         db: services.db,
+        membershipPolicy: services.membershipPolicy,
         registry: services.permissionRegistry,
       }),
     ),

plugins/auth/src/services/admin-organizations.ts

@@ -3,6 +3,7 @@ import { Context, Effect } from "effect";
 import { attemptAuth, attemptDb } from "../attempts";
 import type { InferInput, InferOutput } from "../contract";
 import * as schema from "../db/schema";
+import type { OrganizationMembershipPolicy } from "../organization-membership-policy";
 import { toDate, toInvitation, toOrganizationInfo, toTeam } from "../serializers";
 import type { PermissionRegistry, PluginServices } from "../service-types";
 import { parseMemberRoles } from "../utils";
@@ -42,7 +43,6 @@ export class AdminOrganizationsService extends Context.Service<
       organizationId: string,
     ) => Effect.Effect<{ success: boolean }, AuthFailure>;
     addMember: (
-      headers: Headers,
       input: InferInput<"adminAddMember">,
     ) => Effect.Effect<InferOutput<"adminAddMember">, AuthFailure>;
     removeMember: (
@@ -70,10 +70,12 @@ export class AdminOrganizationsService extends Context.Service<
 export const buildAdminOrganizationsService = ({
   auth,
   db,
+  membershipPolicy,
   registry,
 }: {
   auth: Auth;
   db: Db;
+  membershipPolicy: OrganizationMembershipPolicy;
   registry: PermissionRegistry;
 }) => {
   const notFound = (organizationId: string) =>
@@ -357,25 +359,82 @@ export const buildAdminOrganizationsService = ({
       return { success: true };
     }),
 
-    addMember: (headers, input) =>
-      attemptAuth(() =>
-        auth.api.addMember({
-          headers,
-          body: {
+    addMember: Effect.fn("AdminOrganizationsService.addMember")(function* (
+      input: InferInput<"adminAddMember">,
+    ) {
+      const organization = yield* attemptDb(() =>
+        db.query.organization.findFirst({
+          where: eq(schema.organization.id, input.organizationId),
+        }),
+      );
+      if (!organization) {
+        return yield* notFound(input.organizationId);
+      }
+
+      const user = yield* attemptDb(() =>
+        db.query.user.findFirst({ where: eq(schema.user.id, input.userId) }),
+      );
+      if (!user) {
+        return yield* new UserNotFound({
+          message: `User not found: ${input.userId}`,
+          userId: input.userId,
+        });
+      }
+
+      const existing = yield* attemptDb(() =>
+        db.query.member.findFirst({
+          where: and(
+            eq(schema.member.organizationId, input.organizationId),
+            eq(schema.member.userId, input.userId),
+          ),
+        }),
+      );
+      if (existing) {
+        return yield* new AuthApiError({
+          code: "BAD_REQUEST",
+          data: {},
+          message: "User is already a member of this organization",
+        });
+      }
+
+      const [{ memberCount } = { memberCount: 0 }] = yield* attemptDb(() =>
+        db
+          .select({ memberCount: sql<number>`count(*)::int` })
+          .from(schema.member)
+          .where(eq(schema.member.organizationId, input.organizationId)),
+      );
+      if (!membershipPolicy.hasCapacity(memberCount)) {
+        return yield* new AuthApiError({
+          code: "BAD_REQUEST",
+          data: {},
+          message: "This organization is full, so no more members can join",
+        });
+      }
+
+      const now = new Date();
+      const [member] = yield* attemptDb(() =>
+        db
+          .insert(schema.member)
+          .values({
+            id: crypto.randomUUID(),
+            organizationId: input.organizationId,
             userId: input.userId,
             role: input.role,
-            organizationId: input.organizationId,
-          },
-        }),
-      ).pipe(
-        Effect.map((member: any) => ({
-          id: member.id,
-          userId: member.userId,
-          organizationId: member.organizationId,
-          role: member.role,
-          createdAt: toDate(member.createdAt),
-        })),
-      ),
+            createdAt: now,
+          })
+          .returning(),
+      );
+      if (!member) {
+        return yield* new MemberNotFound({ message: "Member creation failed" });
+      }
+      return {
+        id: member.id,
+        userId: member.userId,
+        organizationId: member.organizationId,
+        role: member.role,
+        createdAt: toDate(member.createdAt),
+      };
+    }),
 
     removeMember: Effect.fn("AdminOrganizationsService.removeMember")(function* (
       input: InferInput<"adminRemoveMember">,
@@ -478,6 +537,26 @@ export const buildAdminOrganizationsService = ({
         return yield* new MemberNotFound({ message: "Member not found" });
       }
 
+      const demotingOnlyOwner =
+        parseMemberRoles(member.role).includes("owner") &&
+        !parseMemberRoles(input.role).includes("owner");
+      if (demotingOnlyOwner) {
+        const members = yield* attemptDb(() =>
+          db.query.member.findMany({
+            where: eq(schema.member.organizationId, input.organizationId),
+            columns: { role: true },
+          }),
+        );
+        const owners = members.filter((row) => parseMemberRoles(row.role).includes("owner"));
+        if (owners.length <= 1) {
+          return yield* new AuthApiError({
+            code: "BAD_REQUEST",
+            data: {},
+            message: "Cannot demote the only owner of an organization",
+          });
+        }
+      }
+
       const [updated] = yield* attemptDb(() =>
         db
           .update(schema.member)

plugins/auth/src/warnings.ts

@@ -58,3 +58,55 @@ export function socialProviderWarnings(config: {
     }),
   ].filter((warning): warning is PluginWarningInfo => warning !== null);
 }
+
+function authBaseUrlHost(baseUrl: string | undefined): string | null {
+  if (!baseUrl) return null;
+  const candidate = /^https?:\/\//i.test(baseUrl) ? baseUrl : `https://${baseUrl}`;
+  try {
+    return new URL(candidate).hostname.toLowerCase();
+  } catch {
+    return null;
+  }
+}
+
+function isLoopbackHost(host: string): boolean {
+  return (
+    host === "localhost" || host === "127.0.0.1" || host === "::1" || host.endsWith(".localhost")
+  );
+}
+
+/**
+ * crossSubDomainCookies (#668) fails silently at the browser: a Set-Cookie
+ * whose Domain does not cover the app's own host is dropped outright (sign-in
+ * stops working), and localhost hosts can never carry a Domain attribute.
+ * Both misconfigurations are caught at config time here instead.
+ */
+export function cookieDomainWarnings(config: {
+  variables: AuthPluginVariables;
+}): PluginWarningInfo[] {
+  const cookies = config.variables.crossSubDomainCookies;
+  if (!cookies?.enabled) return [];
+  const host = authBaseUrlHost(config.variables.baseUrl);
+  if (!host) return [];
+  const warnings: PluginWarningInfo[] = [];
+  if (isLoopbackHost(host)) {
+    warnings.push({
+      pluginKey: "auth",
+      message:
+        "crossSubDomainCookies is enabled but the auth baseUrl is a localhost host — browsers refuse Domain cookies for local hosts, so sessions stay host-scoped in this environment",
+      hint: "Exercise cross-domain session sharing on a staging deployment whose hosts share the configured registrable domain instead",
+    });
+  }
+  if (cookies.domain) {
+    const domain = cookies.domain.toLowerCase().replace(/^\./, "");
+    const coversHost = host === domain || host.endsWith(`.${domain}`);
+    if (!coversHost) {
+      warnings.push({
+        pluginKey: "auth",
+        message: `crossSubDomainCookies.domain "${cookies.domain}" does not cover the auth baseUrl host "${host}" — browsers drop cookies scoped to a foreign domain, which breaks sign-in on this app`,
+        hint: `Use a dot-prefixed registrable domain that is a suffix of "${host}" (e.g. ".${host.split(".").slice(-2).join(".")}")`,
+      });
+    }
+  }
+  return warnings;
+}