feat(auth): abuse-control primitives for app-owned org admission policy (#889)

* feat(auth): abuse-control primitives for org admission policy (#862)

Levers in, policy out (per #857 — admission policy stays app-owned):

- RateLimiter service: in-memory fixed-window, per-caller keyed,
  enforce(operation, subject) -> Effect<void, RateLimitExceeded>; no-op
  when no rule is configured
- abuseControl.rateLimits per operation (createOrganization,
  createOnboardingCode, redeemOnboardingCode) in auth variables; off by
  default — no default policy ships
- RATE_LIMITED declared on the three routes (every-plugin errors shape:
  retryAfterSeconds + limitType), failures flow through the existing
  mapDomainError seam
- gate signals documented for app-side admission: user.isAnonymous,
  emailVerified, account age, NEAR linkage

Multi-instance hosts share no counters — documented limitation; the
enforce-shaped interface admits a shared-store adapter later.

Issue: #862

* review(auth): 862 fixes — rotate guard, RATE_LIMITED declarations, limiter hygiene

- rotateStandingOnboardingCode enforces the same limit as create; both it
  and createOnboardingCode now declare RATE_LIMITED (previously the
  declaration lived only on rotate while the guard lived only on create)
- rate-limit.ts: prune expired buckets once the map exceeds 256 entries
  (per-caller keys never went away), export RateLimiterService instead of
  indexed RateLimiter["Service"] access, drop the dead RateDecision shape
- every-plugin runtime: drop the inline comment duplicating the method
  doc; trim the doc to two lines
- tests: the no-config no-op case asserts enforce resolves undefined
  instead of expect(true).toBe(true)

Self-review of the series; behavior change: rotate is now rate-limited.

Author: elliotBraem

packages/every-plugin/src/runtime/index.ts

@@ -187,12 +187,6 @@ export class PluginRuntime<R = RegisteredPlugins> {
       }
     }
 
-    // Create client factory that accepts request context. The plugin's
-    // Effect context is injected so `.effect()` handlers resolve services
-    // on in-process (server-side / SSR) calls. In development, a context
-    // missing keys the plugin declares as required warns at construction —
-    // the footgun this guards against is failing deep inside the first route
-    // call, far from the factory call that dropped the credentials.
     const createClient = (context?: any) => {
       if (process.env.NODE_ENV !== "production") {
         this.warnOnMissingRequiredContext(initialized, context);
@@ -214,10 +208,9 @@ export class PluginRuntime<R = RegisteredPlugins> {
   }
 
   /**
-   * Warns once per (plugin, missing-keys) combination when a client is
-   * created without context keys the plugin's declared context schema marks
-   * required. Development-only: the runtime stays auth-agnostic — this reads
-   * the schema, never the semantics of any particular key.
+   * Warns once per (plugin, missing-keys) when a client is created without
+   * context keys the plugin's declared context schema marks required.
+   * Development-only and schema-driven — the runtime stays auth-agnostic.
    */
   private warnOnMissingRequiredContext(
     initialized: InitializedPlugin<AnyPlugin>,

plugins/auth/src/auth-config.ts

@@ -4,6 +4,7 @@ import type {
   SessionGasKeyDualNetworkConfig,
   SubAccountConfig,
 } from "better-near-auth";
+import type { RateRules } from "./services/rate-limit";
 
 export type AuthNetwork = "mainnet" | "testnet";
 
@@ -83,6 +84,7 @@ export interface AuthConfig {
   baseUrl: string;
   network?: AuthNetwork;
   organizationMembershipLimit?: number;
+  abuseControl?: { rateLimits?: RateRules };
   trustedOrigins?: string[];
   isProduction?: boolean;
   rateLimit?: AuthRateLimitConfig;

plugins/auth/src/config-schemas.ts

@@ -95,6 +95,23 @@ export const authVariablesSchema = z.object({
   trustedOrigins: z.array(z.string()).optional(),
   apiKeyHeaders: z.array(z.string()).default(["x-api-key"]),
   organizationMembershipLimit: z.number().int().positive().optional(),
+  abuseControl: z
+    .object({
+      rateLimits: z
+        .object({
+          createOrganization: z
+            .object({ window: z.number().int().positive(), max: z.number().int().positive() })
+            .optional(),
+          createOnboardingCode: z
+            .object({ window: z.number().int().positive(), max: z.number().int().positive() })
+            .optional(),
+          redeemOnboardingCode: z
+            .object({ window: z.number().int().positive(), max: z.number().int().positive() })
+            .optional(),
+        })
+        .optional(),
+    })
+    .optional(),
   socialProviders: z
     .object({
       github: z

plugins/auth/src/contract/errors.ts

@@ -3,6 +3,7 @@ import {
   BAD_REQUEST,
   FORBIDDEN,
   NOT_FOUND,
+  RATE_LIMITED,
   SERVICE_UNAVAILABLE,
   UNAUTHORIZED,
 } from "every-plugin/errors";
@@ -73,3 +74,8 @@ export const InvitationErrors = {
   ...Errors,
   ALREADY_MEMBER,
 } as const;
+
+export const OnboardingRateLimitedErrors = {
+  ...OnboardingErrors,
+  RATE_LIMITED,
+} as const;

plugins/auth/src/contract/onboarding.contract.ts

@@ -1,7 +1,8 @@
 import "@orpc/openapi/extensions/route";
 import { oc } from "@orpc/contract";
 import { z } from "zod";
-import { OnboardingErrors } from "./errors";
+import { OnboardingErrors, OnboardingRateLimitedErrors } from "./errors";
+
 import { onboardingCodeSummarySchema, onboardingStatsSchema } from "./schemas";
 
 export const onboardingRoutes = {
@@ -34,7 +35,7 @@ export const onboardingRoutes = {
     .route({ method: "POST", path: "/v1/auth/onboarding/codes/standing/rotate" })
     .input(z.object({ organizationId: z.string().optional(), eventId: z.string().optional() }))
     .output(onboardingCodeSummarySchema.extend({ code: z.string() }))
-    .errors(OnboardingErrors),
+    .errors(OnboardingRateLimitedErrors),
 
   getStandingOnboardingCode: oc
     .route({ method: "GET", path: "/v1/auth/onboarding/codes/standing" })
@@ -130,5 +131,5 @@ export const onboardingRoutes = {
         eventName: z.string().nullable(),
       }),
     )
-    .errors(OnboardingErrors),
+    .errors(OnboardingRateLimitedErrors),
 };

plugins/auth/src/handlers/onboarding.ts

@@ -1,6 +1,7 @@
 import type { Implementer } from "@orpc/server";
 import type { ContractType } from "../contract";
 import type { AuthHandlerContext, RequireAuthMiddleware } from "../middleware";
+import { RateLimiterTag } from "../service-types";
 import { mapDomainError } from "../services/domain-errors";
 import { OnboardingService } from "../services/onboarding";
 
@@ -13,6 +14,8 @@ export function createOnboardingHandlers(
       input,
       context,
     }) {
+      const limiter = yield* RateLimiterTag;
+      yield* mapDomainError(limiter.enforce("createOnboardingCode", context.userId));
       const onboarding = yield* OnboardingService;
       return yield* mapDomainError(onboarding.createOnboardingCode(context, input));
     }),
@@ -75,6 +78,8 @@ export function createOnboardingHandlers(
     rotateStandingOnboardingCode: builder.rotateStandingOnboardingCode
       .use(requireAuth)
       .effect(function* ({ input, context }) {
+        const limiter = yield* RateLimiterTag;
+        yield* mapDomainError(limiter.enforce("createOnboardingCode", context.userId));
         const onboarding = yield* OnboardingService;
         return yield* mapDomainError(onboarding.rotateStandingOnboardingCode(context, input));
       }),
@@ -90,6 +95,8 @@ export function createOnboardingHandlers(
       input,
       context,
     }) {
+      const limiter = yield* RateLimiterTag;
+      yield* mapDomainError(limiter.enforce("redeemOnboardingCode", context.userId));
       const onboarding = yield* OnboardingService;
       return yield* mapDomainError(onboarding.redeemOnboardingCode(context, input.code));
     }),

plugins/auth/src/handlers/organizations.ts

@@ -6,6 +6,7 @@ import type {
   AuthHandlerContext,
   RequireAuthMiddleware,
 } from "../middleware";
+import { RateLimiterTag } from "../service-types";
 import { mapDomainError } from "../services/domain-errors";
 import { OrganizationsService } from "../services/organizations";
 import { createHeaders } from "../utils";
@@ -65,6 +66,8 @@ export function createOrganizationHandlers(
       input,
       context,
     }) {
+      const limiter = yield* RateLimiterTag;
+      yield* mapDomainError(limiter.enforce("createOrganization", context.userId));
       const organizations = yield* OrganizationsService;
       return yield* mapDomainError(
         organizations.createOrganization(createHeaders(context.reqHeaders), input),

plugins/auth/src/index.ts

@@ -28,6 +28,7 @@ import { createOrganizationMembershipPolicy } from "./organization-membership-po
 import { OrphanSweepLive } from "./orphan-sweep";
 import { AuthServicesTag } from "./service-types";
 import { buildAuthServicesLayer } from "./service-wiring";
+import { createRateLimiter } from "./services/rate-limit";
 import { toError } from "./utils";
 import { cookieDomainWarnings, socialProviderWarnings } from "./warnings";
 
@@ -60,6 +61,7 @@ export default createPlugin.withPlugins<PluginsClient>()({
         authConfig.organizationMembershipLimit,
       );
       const onboardingCodeCipher = createOnboardingCodeCipher(authConfig.secret);
+      const rateLimiter = createRateLimiter(config.variables.abuseControl?.rateLimits);
       const permissionRegistry = {
         statements: authConfig.siwn.permissions.statements,
         roleGrants: authConfig.siwn.permissions.roles,
@@ -86,6 +88,7 @@ export default createPlugin.withPlugins<PluginsClient>()({
           membershipPolicy,
           onboardingCodeCipher,
           permissionRegistry,
+          rateLimiter,
         }),
         OrphanSweepLive(db),
       );

plugins/auth/src/middleware.ts

@@ -10,6 +10,7 @@ import {
   type MembershipPolicyTag,
   type OnboardingCodeCipherTag,
   type PluginServices,
+  type RateLimiterTag,
 } from "./service-types";
 import type { AdminOrganizationsService } from "./services/admin-organizations";
 import type { AdminUsersService } from "./services/admin-users";
@@ -42,6 +43,7 @@ export type AuthEffectServices =
   | OnboardingService
   | PasskeysService
   | PermissionsService
+  | RateLimiterTag
   | NearService
   | SessionService;
 

plugins/auth/src/service-types.ts

@@ -3,6 +3,11 @@ import type { Auth as ConfiguredAuth } from "./auth-instance";
 import type { Database } from "./db/layer";
 import type { OnboardingCodeCipher } from "./onboarding-code-cipher";
 import type { OrganizationMembershipPolicy } from "./organization-membership-policy";
+import type { RateLimiterService } from "./services/rate-limit";
+
+export class RateLimiterTag extends Context.Service<RateLimiterTag, RateLimiterService>()(
+  "auth/RateLimiter",
+) {}
 
 export type PermissionRegistry = {
   statements: Record<string, string[]>;
@@ -17,6 +22,7 @@ export type PluginServices = {
   membershipPolicy: OrganizationMembershipPolicy;
   onboardingCodeCipher: OnboardingCodeCipher;
   permissionRegistry: PermissionRegistry;
+  rateLimiter: RateLimiterService;
 };
 
 export class AuthApiTag extends Context.Service<