@porulle/core 0.7.0 → 0.9.0

package/src/auth/middleware.ts

@@ -43,10 +43,10 @@ export function authMiddleware(
     // Resolve the default org from config, falling back to deprecated constant
     const defaultOrgId = config.auth?.defaultOrganizationId ?? DEFAULT_ORG_ID;
 
-    // Test-only actor injection: NODE_ENV === "test" honors x-test-actor for
-    // route-level integration tests that bypass the Better Auth session
-    // round-trip. Production/non-test environments ignore this header entirely.
-    if (process.env.NODE_ENV === "test") {
+    // Test-only actor injection: requires NODE_ENV === "test" AND an explicit
+    // config opt-in so staging/preview deployments left as NODE_ENV=test do not
+    // silently become a full auth bypass.
+    if (process.env.NODE_ENV === "test" && config.auth?.allowTestActor) {
       const testActorHeader = c.req.header("x-test-actor");
       if (testActorHeader) {
         try {
@@ -172,10 +172,29 @@ export function authMiddleware(
         if (result?.valid && result.key) {
           const apiKey = result.key as Record<string, unknown>;
 
-          // v1.5+ renamed userId → referenceId on the apikey table.
-          const userId = (apiKey.referenceId ?? "") as string;
           const name = (apiKey.name ?? "API Key") as string;
-          const orgId = (apiKey.organizationId ?? defaultOrgId) as string;
+          // Read the org (and operator identity) from key metadata when present.
+          // POS shift keys carry { organizationId, operatorId } in metadata so the
+          // operator is scoped to their store WITHOUT any org membership/role
+          // (SEC-16 / R-01). Other keys fall back to the key's organizationId.
+          const rawMeta = apiKey.metadata;
+          const meta =
+            rawMeta && typeof rawMeta === "object"
+              ? (rawMeta as Record<string, unknown>)
+              : typeof rawMeta === "string"
+                ? (() => {
+                    try {
+                      return JSON.parse(rawMeta) as Record<string, unknown>;
+                    } catch {
+                      return null;
+                    }
+                  })()
+                : null;
+          const metaOrg = typeof meta?.organizationId === "string" ? meta.organizationId : undefined;
+          const orgId = (metaOrg ?? apiKey.organizationId ?? defaultOrgId) as string;
+          const userId = ((typeof meta?.operatorId === "string" ? meta.operatorId : undefined)
+            ?? apiKey.referenceId
+            ?? "") as string;
 
           // Better Auth stores permissions as Record<string, string[]>
           // (e.g. {"catalog":["read","create"]}).  Flatten to the

package/src/auth/setup.ts

@@ -7,13 +7,13 @@ import type { CommerceConfig } from "../config/types.js";
 import type { DatabaseAdapter } from "../kernel/database/adapter.js";
 import * as authSchema from "./auth-schema.js";
 
-type BetterAuthDbProvider = "pg" | "mysql" | "sqlite";
+type BetterAuthDbProvider = "pg";
 
 function resolveAuthDbProvider(provider: string): BetterAuthDbProvider {
   if (provider === "postgres" || provider === "postgresql" || provider === "pg") return "pg";
-  if (provider === "mysql") return "mysql";
-  if (provider === "sqlite") return "sqlite";
-  throw new Error(`Unsupported auth database provider "${provider}".`);
+  throw new Error(
+    `Unsupported auth database provider "${provider}". Only PostgreSQL is supported.`,
+  );
 }
 
 interface AuthEmailPayload {
@@ -90,6 +90,13 @@ export function createAuth(
             },
           }
         : {}),
+      ...(scope.keyExpiration ? { keyExpiration: scope.keyExpiration } : {}),
+      ...("references" in scope && scope.references
+        ? { references: scope.references as "user" | "organization" }
+        : {}),
+      ...(scope.enableMetadata || scope.references === "organization"
+        ? { enableMetadata: true }
+        : {}),
     }));
     plugins.push(apiKey(apiKeyConfigs));
   } else if (config.auth?.apiKeys?.enabled) {

package/src/config/defaults.ts

@@ -27,9 +27,16 @@ export const defaultConfig: Partial<CommerceConfig> = {
           "inventory:read",
           "inventory:adjust",
           "orders:read",
+          "orders:create",
           "orders:update",
+          "orders:manage",
           "cart:create",
           "cart:update",
+          "cart:manage",
+          "shipping:manage",
+          "tax:manage",
+          "settings:manage",
+          "analytics:read",
           "customers:read:self",
           "customers:update:self",
         ],

package/src/config/types.ts

@@ -4,6 +4,7 @@ import type { BeforeHook, AfterHook } from "../kernel/hooks/types.js";
 import type { PaymentAdapter } from "../modules/payments/adapter.js";
 import type { StorageAdapter } from "../modules/media/adapter.js";
 import type { Kernel } from "../runtime/kernel.js";
+import type { AuthInstance } from "../auth/setup.js";
 import type { DatabaseAdapter } from "../kernel/database/adapter.js";
 import type { TaxAdapter } from "../modules/tax/adapter.js";
 import type { SearchAdapter } from "../modules/search/adapter.js";
@@ -102,6 +103,20 @@ export interface ApiKeyScopeDefinition {
     /** Time window in milliseconds. */
     timeWindow: number;
   };
+  /**
+   * Expiry bounds for keys minted under this scope, in DAYS (Better Auth
+   * semantics; fractions allowed — 1/24 = one hour). Better Auth defaults
+   * minExpiresIn to 1 day, which blocks short-lived credentials like
+   * per-shift POS keys (issue #51).
+   */
+  keyExpiration?: {
+    minExpiresIn?: number;
+    maxExpiresIn?: number;
+  };
+  /** Better Auth ownership model — POS shift keys bind to an organization. */
+  references?: "user" | "organization";
+  /** Allow metadata on keys minted under this scope (e.g. operatorId on POS shift keys). */
+  enableMetadata?: boolean;
 }
 
 export interface AuthConfig {
@@ -203,6 +218,11 @@ export interface AuthConfig {
    * Appended to the core plugin list (organization, bearer, jwt, etc.).
    */
   extraAuthPlugins?: unknown[];
+  /**
+   * When true (and NODE_ENV === "test"), the `x-test-actor` header may inject
+   * a trusted actor for integration tests. Default false.
+   */
+  allowTestActor?: boolean;
 }
 
 export interface CartConfig {
@@ -374,7 +394,12 @@ export interface CommerceConfig {
   hooks?: Record<string, Array<(...args: unknown[]) => unknown>>;
   plugins?: CommercePlugin[];
   middleware?: MiddlewareHandler[];
-  routes?: (app: Hono<any>, kernel: Kernel) => void;
+  /**
+   * Custom route registration. Receives the Better Auth instance as the
+   * third argument so integrations can mint/revoke API keys or call
+   * `auth.api.*` without module-global holder shims.
+   */
+  routes?: (app: Hono<any>, kernel: Kernel, auth?: AuthInstance) => void;
   /** Log level for structured logging. Default: "info". */
   logLevel?: "fatal" | "error" | "warn" | "info" | "debug" | "trace";
   /**

package/src/generated/plugin-capabilities.d.ts

@@ -4,6 +4,7 @@
 export interface PluginCapabilityRegistryShape {
   "appointments": Record<string, unknown>;
   "gift-cards": Record<string, unknown>;
+  "layaway": Record<string, unknown>;
   "loyalty": Record<string, unknown>;
   "marketplace": Record<string, unknown>;
   "notifications": Record<string, unknown>;

package/src/generated/plugin-manifest.ts

@@ -5,6 +5,7 @@
 export const resolvedPluginManifest = [
   { id: "appointments", directory: "plugin-appointments" },
   { id: "gift-cards", directory: "plugin-gift-cards" },
+  { id: "layaway", directory: "plugin-layaway" },
   { id: "loyalty", directory: "plugin-loyalty" },
   { id: "marketplace", directory: "plugin-marketplace" },
   { id: "notifications", directory: "plugin-notifications" },

package/src/generated/plugin-repositories.d.ts

@@ -4,6 +4,7 @@
 export interface PluginRepositoryRegistryShape {
   "appointments": Record<string, unknown>;
   "gift-cards": Record<string, unknown>;
+  "layaway": Record<string, unknown>;
   "loyalty": Record<string, unknown>;
   "marketplace": Record<string, unknown>;
   "notifications": Record<string, unknown>;

package/src/hooks/checkout-completion.ts

@@ -13,14 +13,14 @@ interface InventoryServiceLike {
     quantity: number;
     orderId: string;
     performedBy: string;
-  }): Promise<{ ok: boolean; error?: { message: string } }>;
+  }, actor?: unknown): Promise<{ ok: boolean; error?: { message: string } }>;
   release(input: {
     entityId: string;
     variantId?: string;
     quantity: number;
     orderId: string;
     performedBy: string;
-  }): Promise<unknown>;
+  }, actor?: unknown): Promise<unknown>;
 }
 
 interface PaymentsServiceLike {
@@ -80,13 +80,16 @@ export const reserveInventoryStep: Step<
     const performedBy = ctx.hook.actor?.userId ?? "system";
 
     for (const item of data.lineItems) {
-      const result = await inventory.reserve({
-        entityId: item.entityId,
-        ...(item.variantId != null ? { variantId: item.variantId } : {}),
-        quantity: item.quantity,
-        orderId: data.checkoutId,
-        performedBy,
-      });
+      const result = await inventory.reserve(
+        {
+          entityId: item.entityId,
+          ...(item.variantId != null ? { variantId: item.variantId } : {}),
+          quantity: item.quantity,
+          orderId: data.checkoutId,
+          performedBy,
+        },
+        ctx.hook.actor,
+      );
 
       if (!result.ok) {
         return Err(
@@ -112,13 +115,16 @@ export const reserveInventoryStep: Step<
     const performedBy = ctx.hook.actor?.userId ?? "system";
 
     for (const r of reservations) {
-      await inventory.release({
-        entityId: r.entityId,
-        ...(r.variantId != null ? { variantId: r.variantId } : {}),
-        quantity: r.quantity,
-        orderId: r.orderId,
-        performedBy,
-      });
+      await inventory.release(
+        {
+          entityId: r.entityId,
+          ...(r.variantId != null ? { variantId: r.variantId } : {}),
+          quantity: r.quantity,
+          orderId: r.orderId,
+          performedBy,
+        },
+        ctx.hook.actor,
+      );
     }
   },
 };

package/src/hooks/checkout.ts

@@ -359,28 +359,40 @@ export const calculateTax: BeforeHook<CheckoutData> = async ({
       currency: string;
       customerId?: string;
       shippingAmount: number;
+      orderDiscount?: number;
       fromAddress?: ShippingAddress;
       toAddress?: ShippingAddress;
       lineItems: Array<{
         id: string;
         entityId: string;
+        variantId?: string;
         description: string;
         quantity: number;
         unitPrice: number;
         discount?: number;
       }>;
-    }): Promise<
-      | { ok: true; value: { amountToCollect: number } }
+    }, orgId?: string): Promise<
+      | { ok: true; value: { amountToCollect: number; lines?: Array<{ id: string; taxClass: string | null; taxAmount: number }> } }
       | { ok: false; error: Error }
     >;
   };
 
+  // Cart-level discount not already attributed to lines — pro-rated across
+  // lines before class-based tax (issue #57).
+  const lineDiscounts = data.lineItems.reduce(
+    (sum, lineItem) => sum + (lineItem.discountAmount ?? 0),
+    0,
+  );
+  const orderDiscount = Math.max(0, data.discountTotal - lineDiscounts);
+
   const calculated = await tax.calculate({
     currency: data.currency,
     shippingAmount: data.shippingTotal,
+    orderDiscount,
     lineItems: data.lineItems.map((lineItem) => ({
       id: lineItem.id ?? `${lineItem.entityId}:${lineItem.variantId ?? "_"}`,
       entityId: lineItem.entityId,
+      ...(lineItem.variantId !== undefined ? { variantId: lineItem.variantId } : {}),
       description: lineItem.title ?? lineItem.entityId,
       quantity: lineItem.quantity,
       unitPrice: lineItem.resolvedUnitPrice ?? 0,
@@ -392,7 +404,7 @@ export const calculateTax: BeforeHook<CheckoutData> = async ({
     ...(data.shippingAddress !== undefined
       ? { toAddress: data.shippingAddress }
       : {}),
-  });
+  }, resolveOrgId(context.actor ?? null));
 
   if (!calculated.ok) {
     throw new CommerceValidationError(
@@ -400,6 +412,14 @@ export const calculateTax: BeforeHook<CheckoutData> = async ({
     );
   }
 
+  // Product tax classes return per-line results — store them so the order's
+  // line items carry taxAmount (issue #57). Lines arrive in request order.
+  if (calculated.value.lines) {
+    for (const [i, line] of calculated.value.lines.entries()) {
+      if (data.lineItems[i]) data.lineItems[i]!.taxAmount = line.taxAmount;
+    }
+  }
+
   data.taxTotal = Math.max(0, Math.round(calculated.value.amountToCollect));
   recalculateTotals(data);
   return data;
@@ -421,6 +441,7 @@ export const calculateShipping: BeforeHook<CheckoutData> = async ({
       currency: string;
       address?: ShippingAddress;
       isFreeShipping?: boolean;
+      orgId?: string;
     }): Promise<
       | {
           ok: true;
@@ -441,6 +462,7 @@ export const calculateShipping: BeforeHook<CheckoutData> = async ({
     })),
     subtotalAfterDiscount: Math.max(0, data.subtotal - data.discountTotal),
     currency: data.currency,
+    orgId: resolveOrgId(context.actor ?? null),
     ...(data.shippingAddress !== undefined
       ? { address: data.shippingAddress }
       : {}),
@@ -544,16 +566,19 @@ export const reserveInventory: AfterHook<OrderResult> = async ({ result, context
       quantity: number;
       orderId: string;
       performedBy: string;
-    }): Promise<unknown>;
+    }, actor?: unknown): Promise<unknown>;
   };
   for (const lineItem of result.lineItems ?? []) {
-    await inventory.reserve({
-      entityId: lineItem.entityId,
-      ...(lineItem.variantId != null ? { variantId: lineItem.variantId } : {}),
-      quantity: lineItem.quantity,
-      orderId: result.id,
-      performedBy: context.actor?.userId ?? "system",
-    });
+    await inventory.reserve(
+      {
+        entityId: lineItem.entityId,
+        ...(lineItem.variantId != null ? { variantId: lineItem.variantId } : {}),
+        quantity: lineItem.quantity,
+        orderId: result.id,
+        performedBy: context.actor?.userId ?? "system",
+      },
+      context.actor,
+    );
   }
 };
 

package/src/index.ts

@@ -15,6 +15,7 @@ export type {
 } from "./kernel/plugin/manifest.js";
 
 export { router } from "./interfaces/rest/router.js";
+export { requirePerm } from "./interfaces/rest/utils.js";
 export { webhookRouter, type WebhookRouterResult } from "./interfaces/rest/webhook-router.js";
 export { isPrivateUrl, isPrivateIp } from "./modules/webhooks/ssrf-guard.js";
 export { createServer } from "./runtime/server.js";

package/src/interfaces/rest/index.ts

@@ -4,6 +4,7 @@ import { sql } from "drizzle-orm";
 import type { Kernel } from "../../runtime/kernel.js";
 import type { AppEnv } from "./utils.js";
 import { mapErrorToResponse } from "../../kernel/error-mapper.js";
+import { analyticsRoutes } from "./routes/analytics.js";
 import { catalogRoutes } from "./routes/catalog.js";
 import { inventoryRoutes } from "./routes/inventory.js";
 import { mediaRoutes } from "./routes/media.js";
@@ -19,7 +20,12 @@ import { auditRoutes } from "./routes/audit.js";
 import { adminJobRoutes } from "./routes/admin-jobs.js";
 import { compensationFailureAdminRoutes } from "./routes/admin/compensation-failures.js";
 import { adminPermissionsRoutes } from "./routes/admin/permissions.js";
+import { adminStaffRoutes } from "./routes/admin/staff.js";
 import { customerRoutes } from "./routes/customers.js";
+import { documentRoutes } from "./routes/documents.js";
+import { settingsRoutes } from "./routes/settings.js";
+import { shippingRoutes } from "./routes/shipping.js";
+import { taxRoutes } from "./routes/tax.js";
 export function createRestRoutes(kernel: Kernel) {
   const router = new OpenAPIHono<AppEnv>({
     // Standardize Zod validation error responses across all routes
@@ -72,9 +78,14 @@ export function createRestRoutes(kernel: Kernel) {
   router.route("/carts", cartRoutes(kernel));
   router.route("/checkout", checkoutRoutes(kernel));
   router.route("/orders", orderRoutes(kernel));
+  router.route("/orders", documentRoutes(kernel));
   router.route("/payments", paymentRoutes(kernel));
   router.route("/webhooks", webhookRoutes(kernel));
   router.route("/pricing", pricingRoutes(kernel));
+  router.route("/shipping", shippingRoutes(kernel));
+  router.route("/tax", taxRoutes(kernel));
+  router.route("/settings", settingsRoutes(kernel));
+  router.route("/analytics", analyticsRoutes(kernel));
   router.route("/promotions", promotionRoutes(kernel));
   router.route("/search", searchRoutes(kernel));
   router.route("/customers", customerRoutes(kernel));
@@ -82,6 +93,7 @@ export function createRestRoutes(kernel: Kernel) {
   router.route("/admin", adminJobRoutes(kernel));
   router.route("/admin", compensationFailureAdminRoutes(kernel));
   router.route("/admin", adminPermissionsRoutes(kernel));
+  router.route("/admin", adminStaffRoutes(kernel));
 
   // API Reference (Scalar) — disabled in production unless config.exposeOpenApiSpec is true
   const exposeSpec = kernel.config.exposeOpenApiSpec ?? (process.env.NODE_ENV !== "production");

package/src/interfaces/rest/routes/admin/staff.ts

@@ -0,0 +1,260 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { eq, and } from "drizzle-orm";
+import type { Kernel } from "../../../../runtime/kernel.js";
+import type { CommerceConfig } from "../../../../config/types.js";
+import type { DrizzleDatabase } from "../../../../kernel/database/drizzle-db.js";
+import { member, user, invitation } from "../../../../auth/auth-schema.js";
+import { resolveOrgId } from "../../../../auth/org.js";
+import { makeId } from "../../../../utils/id.js";
+import {
+  listStaffRoute,
+  createStaffRoute,
+  inviteStaffRoute,
+  listStaffInvitationsRoute,
+  listStaffRolesRoute,
+  updateStaffRoleRoute,
+  revokeStaffRoute,
+} from "../../schemas/admin-staff.js";
+import { type AppEnv, requirePerm } from "../../utils.js";
+
+/**
+ * Admin staff / RBAC surface (issue #46).
+ *
+ * Surfaces the Better Auth `member` table as first-class admin REST:
+ * list staff, add an existing user with a role, invite by email, change
+ * role, revoke — plus the role → permission mapping roles resolve to.
+ */
+export function adminStaffRoutes(kernel: Kernel) {
+  const router = new OpenAPIHono<AppEnv>();
+  const db = kernel.database.db as DrizzleDatabase;
+  const config = kernel.config as CommerceConfig;
+
+  router.use("/staff", requirePerm("staff:manage"));
+  router.use("/staff/:id", requirePerm("staff:manage"));
+  router.use("/staff/invitations", requirePerm("staff:manage"));
+  router.use("/staff/roles", requirePerm("staff:manage"));
+
+  function validRoles(): Set<string> {
+    return new Set([
+      ...Object.keys(config.auth?.roles ?? {}),
+      "owner",
+      "admin",
+      "member",
+    ]);
+  }
+
+  function invalidRole(c: { json: (d: unknown, s: number) => unknown }, role: string) {
+    return c.json(
+      {
+        error: {
+          code: "VALIDATION_FAILED",
+          message: `Unknown role "${role}". Valid roles: ${[...validRoles()].join(", ")}.`,
+        },
+      },
+      422,
+    );
+  }
+
+  const BUILTIN_ROLE_RANK: Record<string, number> = {
+    owner: 3,
+    admin: 2,
+  };
+  const CUSTOM_ROLE_RANK = 1;
+
+  function roleRank(role: string): number {
+    return BUILTIN_ROLE_RANK[role] ?? CUSTOM_ROLE_RANK;
+  }
+
+  function canGrantRole(actorRole: string, targetRole: string): boolean {
+    return roleRank(actorRole) >= roleRank(targetRole);
+  }
+
+  function insufficientPrivilege(
+    c: { json: (d: unknown, s: number) => unknown },
+    targetRole: string,
+  ) {
+    return c.json(
+      {
+        error: {
+          code: "FORBIDDEN",
+          message: `Cannot assign role "${targetRole}": your role does not have sufficient privilege.`,
+        },
+      },
+      403,
+    );
+  }
+
+  async function countOwners(orgId: string): Promise<number> {
+    const rows = await db
+      .select({ id: member.id })
+      .from(member)
+      .where(and(eq(member.organizationId, orgId), eq(member.role, "owner")));
+    return rows.length;
+  }
+
+  router.openapi(listStaffRoute, async (c) => {
+    const orgId = resolveOrgId(c.get("actor"));
+    const rows = await db
+      .select({
+        id: member.id,
+        userId: member.userId,
+        role: member.role,
+        createdAt: member.createdAt,
+        email: user.email,
+        name: user.name,
+      })
+      .from(member)
+      .leftJoin(user, eq(member.userId, user.id))
+      .where(eq(member.organizationId, orgId));
+    return c.json({ data: rows });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(createStaffRoute, async (c) => {
+    const body = c.req.valid("json") as { userId: string; role: string };
+    const actor = c.get("actor");
+    const orgId = resolveOrgId(actor);
+
+    if (!validRoles().has(body.role)) return invalidRole(c, body.role);
+    if (!canGrantRole(actor!.role, body.role)) return insufficientPrivilege(c, body.role);
+
+    const users = await db.select().from(user).where(eq(user.id, body.userId));
+    if (users.length === 0) {
+      return c.json({ error: { code: "NOT_FOUND", message: "User not found." } }, 404);
+    }
+
+    const existing = await db
+      .select({ id: member.id })
+      .from(member)
+      .where(and(eq(member.organizationId, orgId), eq(member.userId, body.userId)));
+    if (existing.length > 0) {
+      return c.json(
+        { error: { code: "VALIDATION_FAILED", message: "User is already a member of this organization." } },
+        422,
+      );
+    }
+
+    const rows = await db
+      .insert(member)
+      .values({
+        id: makeId(),
+        organizationId: orgId,
+        userId: body.userId,
+        role: body.role,
+        createdAt: new Date(),
+      })
+      .returning();
+    return c.json({ data: rows[0] }, 201);
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(inviteStaffRoute, async (c) => {
+    const body = c.req.valid("json") as { email: string; role: string };
+    const actor = c.get("actor");
+    const orgId = resolveOrgId(actor);
+
+    if (!validRoles().has(body.role)) return invalidRole(c, body.role);
+
+    const rows = await db
+      .insert(invitation)
+      .values({
+        id: makeId(),
+        organizationId: orgId,
+        email: body.email,
+        role: body.role,
+        status: "pending",
+        expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
+        inviterId: actor!.userId,
+      })
+      .returning();
+    return c.json({ data: rows[0] }, 201);
+  });
+
+  router.openapi(listStaffInvitationsRoute, async (c) => {
+    const orgId = resolveOrgId(c.get("actor"));
+    const rows = await db
+      .select()
+      .from(invitation)
+      .where(and(eq(invitation.organizationId, orgId), eq(invitation.status, "pending")));
+    return c.json({ data: rows });
+  });
+
+  router.openapi(listStaffRolesRoute, async (c) => {
+    const roles = config.auth?.roles ?? {};
+    const data = Object.entries(roles).map(([role, def]) => ({
+      role,
+      permissions: def.permissions,
+    }));
+    return c.json({ data });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(updateStaffRoleRoute, async (c) => {
+    const body = c.req.valid("json") as { role: string };
+    const actor = c.get("actor");
+    const orgId = resolveOrgId(actor);
+    const id = c.req.param("id");
+
+    if (!validRoles().has(body.role)) return invalidRole(c, body.role);
+    if (!canGrantRole(actor!.role, body.role)) return insufficientPrivilege(c, body.role);
+
+    const rows = await db
+      .select()
+      .from(member)
+      .where(and(eq(member.organizationId, orgId), eq(member.id, id)));
+    const target = rows[0];
+    if (!target) {
+      return c.json({ error: { code: "NOT_FOUND", message: "Staff member not found." } }, 404);
+    }
+
+    // SEC-18/R-02: the actor must also outrank (or equal) the target's CURRENT
+    // role, else an admin could demote an owner they do not outrank.
+    if (!canGrantRole(actor!.role, target.role)) return insufficientPrivilege(c, target.role);
+
+    if (target.role === "owner" && body.role !== "owner" && (await countOwners(orgId)) <= 1) {
+      return c.json(
+        { error: { code: "VALIDATION_FAILED", message: "Cannot demote the organization's last owner." } },
+        422,
+      );
+    }
+
+    const updated = await db
+      .update(member)
+      .set({ role: body.role })
+      .where(eq(member.id, id))
+      .returning();
+    return c.json({ data: updated[0] });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(revokeStaffRoute, async (c) => {
+    const actor = c.get("actor");
+    const orgId = resolveOrgId(actor);
+    const id = c.req.param("id");
+
+    const rows = await db
+      .select()
+      .from(member)
+      .where(and(eq(member.organizationId, orgId), eq(member.id, id)));
+    const target = rows[0];
+    if (!target) {
+      return c.json({ error: { code: "NOT_FOUND", message: "Staff member not found." } }, 404);
+    }
+
+    // SEC-18/R-02: the actor must outrank (or equal) the target's current role
+    // to revoke it — an admin cannot revoke an owner.
+    if (!canGrantRole(actor!.role, target.role)) return insufficientPrivilege(c, target.role);
+
+    if (target.role === "owner" && (await countOwners(orgId)) <= 1) {
+      return c.json(
+        { error: { code: "VALIDATION_FAILED", message: "Cannot revoke the organization's last owner." } },
+        422,
+      );
+    }
+
+    await db.delete(member).where(eq(member.id, id));
+    return c.json({ data: { deleted: true } });
+  });
+
+  return router;
+}