@nextsparkjs/core 0.1.0-beta.185 → 0.1.0-beta.186

package/dist/migrations/026_login_events.sql

@@ -0,0 +1,91 @@
+-- Migration: 026_login_events.sql
+-- Description: login_events — per-user device/login history for built-in
+--              security email notifications (new-device login alerts).
+-- Date: 2026-09-01
+-- Issue: #75
+--
+-- Why 026 (and not 022 as the issue text proposed, nor 025):
+--   The issue was written when the migration sequence ended earlier. By the
+--   time this branch was authored the sequence already went through
+--   024_teams_soft_delete.sql (022 and 023 are taken by rls_runtime_roles and
+--   the invitations index), so this migration was originally 025. It was
+--   renumbered to 026 when merging to main, because 025 had in the meantime
+--   been taken by 025_api_audit_log_nullable_api_key.sql (issue #105).
+--
+-- What this backs:
+--   The security-notifications dispatcher records one row per successful sign-in
+--   with a device fingerprint = sha256(normalizedUA | ip/24). A sign-in whose
+--   (userId, deviceFingerprint) pair has never been seen is flagged isNew=true
+--   and triggers a "new device" email via the auth:security-notification
+--   scheduled action. Known fingerprints are still logged (isNew=false) but send
+--   no email. The table is also the substrate for a future login-history UI
+--   (out of scope here — see issue #75 "Out of scope").
+--
+-- Append-only: rows are never updated, so there is no "updatedAt"/set_updated_at
+-- trigger (unlike mutable entity tables). city/country are nullable for a future
+-- geolocation enhancement (also out of scope).
+
+-- ============================================
+-- TABLE
+-- ============================================
+DROP TABLE IF EXISTS public."login_events" CASCADE;
+
+CREATE TABLE IF NOT EXISTS public."login_events" (
+  -- Primary Key (TEXT not UUID — Better Auth convention)
+  id                  TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
+
+  -- Relational Fields
+  "userId"            TEXT NOT NULL REFERENCES public."users"(id) ON DELETE CASCADE,
+
+  -- Entity-specific fields
+  "ipAddress"         TEXT,
+  "userAgent"         TEXT,
+  "deviceFingerprint" TEXT NOT NULL,
+  city                TEXT,
+  country             TEXT,
+  "isNew"             BOOLEAN NOT NULL DEFAULT false,
+
+  -- System fields (append-only: created only, never updated)
+  "createdAt"         TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+COMMENT ON TABLE  public."login_events"                     IS 'Per-user login/device history backing built-in new-device security email notifications (issue #75).';
+COMMENT ON COLUMN public."login_events"."userId"            IS 'Owner of the login event.';
+COMMENT ON COLUMN public."login_events"."ipAddress"         IS 'Best-effort client IP captured at sign-in (may be a proxy address).';
+COMMENT ON COLUMN public."login_events"."userAgent"         IS 'Raw User-Agent header captured at sign-in.';
+COMMENT ON COLUMN public."login_events"."deviceFingerprint" IS 'sha256(normalizedUA | ip/24). Stable across patch-version UA churn and within a /24 network so routine re-logins from the same device do not re-alert.';
+COMMENT ON COLUMN public."login_events".city                IS 'Reserved for future geolocation enrichment (nullable, unused today).';
+COMMENT ON COLUMN public."login_events".country             IS 'Reserved for future geolocation enrichment (nullable, unused today).';
+COMMENT ON COLUMN public."login_events"."isNew"             IS 'True when this (userId, deviceFingerprint) pair had not been seen before this row → a new-device email was queued.';
+
+-- ============================================
+-- INDEXES
+-- ============================================
+-- Most-recent-first history lookups per user (login-history UI, TTL checks).
+CREATE INDEX IF NOT EXISTS idx_login_events_user_created
+  ON public."login_events" ("userId", "createdAt" DESC);
+
+-- "Have we seen this fingerprint for this user?" — the new-device decision.
+CREATE INDEX IF NOT EXISTS idx_login_events_user_fingerprint
+  ON public."login_events" ("userId", "deviceFingerprint");
+
+-- ============================================
+-- RLS
+-- ============================================
+-- A user may read ONLY their own login events; superadmin/developer bypass via
+-- can_bypass_rls() (defined in 001). Writes are service-only: the dispatcher
+-- inserts with no user GUC (service/bypass pool), matching how session/account
+-- rows are written in 002. Mirrors the "self read + service write" pattern.
+ALTER TABLE public."login_events" ENABLE ROW LEVEL SECURITY;
+
+DROP POLICY IF EXISTS "Login events self read"      ON public."login_events";
+DROP POLICY IF EXISTS "Login events service write"  ON public."login_events";
+
+CREATE POLICY "Login events self read" ON public."login_events"
+FOR SELECT TO authenticated
+USING (public.can_bypass_rls() OR "userId" = public.get_auth_user_id());
+
+CREATE POLICY "Login events service write" ON public."login_events"
+FOR ALL TO authenticated
+USING (public.can_bypass_rls())
+WITH CHECK (public.can_bypass_rls());

package/dist/migrations/027_rls_bypass_developer_and_system_admin_team.sql

@@ -0,0 +1,197 @@
+-- Migration: 027_rls_bypass_developer_and_system_admin_team.sql
+-- Description: Resolve the System Admin Team by a metadata flag instead of a
+--              hardcoded team id, auto-enroll/unenroll developer/superadmin
+--              users via a trigger, and fix 4 RLS policies that hardcoded
+--              their own role check instead of calling can_bypass_rls().
+-- Date: 2026-09-03
+-- Issues: #108, #102
+--
+-- Why both issues in one migration: #102's fix (make a policy call
+-- can_bypass_rls()) only makes 'developer' bypass actually reachable in a
+-- real (non-seeded) deployment once #108's enrollment mechanism exists —
+-- fixing one without the other leaves the combination still broken.
+--
+-- #108 — System Admin Team enrollment:
+--   can_bypass_rls() grants 'developer' a conditional bypass: membership in
+--   the System Admin Team. Nothing ever enrolled anyone into it outside of
+--   090_sample_data.sql's explicit INSERTs, and the team id was a literal
+--   ('team-nextspark-001') duplicated in this function AND in
+--   dual-auth.ts's SYSTEM_ADMIN_TEAM_ID constant. This migration:
+--     1. Resolves the System Admin Team by `teams.metadata.systemAdmin =
+--        true` instead of a literal id — 090_sample_data.sql's team already
+--        carries this flag, so seeded deployments keep working unchanged;
+--        a real deployment flags its own team, no code change needed.
+--     2. Adds a trigger on users(role) that auto-enrolls a user into that
+--        team (as 'owner' for superadmin, 'admin' for developer) when their
+--        role becomes bypass-eligible, and removes the membership when it
+--        stops being eligible. Framework-level (a Postgres trigger fires
+--        regardless of which application code performed the UPDATE) rather
+--        than an app-level hook, because no Server Action in core actually
+--        assigns users.role today — the only code that does lives in
+--        apps/dev, reimplementable by any consumer of this framework.
+--     3. Backfills existing developer/superadmin users into the team, for
+--        deployments that already have such users predating this trigger.
+--   Deliberately NOT included here (separate, larger concern — see #108):
+--   POST /api/v1/users creating a "half" user (no account/team/subscription
+--   row). That depends on patterns from the not-yet-approved #98 MCP work.
+--
+-- #102 (+ 3 more found while auditing the same pattern) — RLS policies that
+-- hardcoded `role IN ('admin','superadmin')` or `role = 'superadmin'`
+-- instead of calling can_bypass_rls() have drifted from it in both
+-- directions. 'admin' is NOT a valid users.role value (see check_users_role
+-- in 002_auth_tables.sql: only 'member' | 'superadmin' | 'developer'), so
+-- that branch never matched any real row — removing it changes nothing for
+-- existing behavior. All four also silently excluded 'developer', who
+-- can_bypass_rls() already grants conditional bypass everywhere else.
+-- Switching to can_bypass_rls() is a pure widening for 'developer' and an
+-- exact match for 'superadmin' — no regression, only fixes a gap:
+--   - users_metas_owner_or_admin_all   (003_user_metas.sql)
+--   - "API key owner or admin can do all" (004_api_key.sql)
+--   - "API logs superadmin can select"     (005_api_audit_log.sql)
+--   - "Plans superadmin write"             (012_billing_plans.sql)
+
+-- ============================================
+-- #108.1 — can_bypass_rls(): resolve System Admin Team by metadata flag
+-- ============================================
+
+CREATE OR REPLACE FUNCTION public.can_bypass_rls()
+RETURNS BOOLEAN AS $$
+DECLARE
+  current_user_id TEXT;
+  user_role TEXT;
+  admin_team_id TEXT;
+  is_system_admin_member BOOLEAN;
+BEGIN
+  current_user_id := public.get_auth_user_id();
+
+  SELECT role INTO user_role
+  FROM public."users"
+  WHERE id = current_user_id;
+
+  IF user_role = 'superadmin' THEN
+    RETURN TRUE;
+  END IF;
+
+  IF user_role = 'developer' THEN
+    -- The System Admin Team is whichever team has metadata.systemAdmin =
+    -- true, not a hardcoded id — each deployment can flag its own team.
+    SELECT id INTO admin_team_id
+    FROM public."teams"
+    WHERE (metadata->>'systemAdmin')::boolean IS TRUE
+    LIMIT 1;
+
+    IF admin_team_id IS NULL THEN
+      RETURN FALSE;
+    END IF;
+
+    SELECT EXISTS(
+      SELECT 1 FROM public."team_members"
+      WHERE "userId" = current_user_id
+        AND "teamId" = admin_team_id
+    ) INTO is_system_admin_member;
+
+    RETURN is_system_admin_member;
+  END IF;
+
+  RETURN FALSE;
+END;
+$$ LANGUAGE plpgsql STABLE SECURITY DEFINER SET search_path = public;
+
+-- ============================================
+-- #108.2 — auto-enroll/unenroll on role change
+-- ============================================
+
+CREATE OR REPLACE FUNCTION public.sync_system_admin_team_membership()
+RETURNS TRIGGER
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+DECLARE
+  admin_team_id TEXT;
+  new_team_role TEXT;
+BEGIN
+  SELECT id INTO admin_team_id
+  FROM public."teams"
+  WHERE (metadata->>'systemAdmin')::boolean IS TRUE
+  LIMIT 1;
+
+  -- No team flagged as the System Admin Team in this deployment yet —
+  -- nothing to enroll into. Not an error: same as no bypass being possible.
+  IF admin_team_id IS NULL THEN
+    RETURN NEW;
+  END IF;
+
+  IF NEW.role IN ('developer', 'superadmin') THEN
+    new_team_role := CASE WHEN NEW.role = 'superadmin' THEN 'owner' ELSE 'admin' END;
+
+    INSERT INTO public."team_members" ("teamId", "userId", role)
+    VALUES (admin_team_id, NEW.id, new_team_role)
+    ON CONFLICT ("teamId", "userId") DO UPDATE SET role = EXCLUDED.role;
+
+  ELSIF TG_OP = 'UPDATE' AND OLD.role IN ('developer', 'superadmin') THEN
+    -- Role changed away from a bypass-eligible tier: revoke membership.
+    DELETE FROM public."team_members"
+    WHERE "teamId" = admin_team_id AND "userId" = NEW.id;
+  END IF;
+
+  RETURN NEW;
+END;
+$$;
+
+DROP TRIGGER IF EXISTS trg_sync_system_admin_team_membership ON public."users";
+CREATE TRIGGER trg_sync_system_admin_team_membership
+AFTER INSERT OR UPDATE OF role ON public."users"
+FOR EACH ROW
+EXECUTE FUNCTION public.sync_system_admin_team_membership();
+
+-- ============================================
+-- #108.3 — backfill existing developer/superadmin users
+-- ============================================
+
+DO $$
+DECLARE
+  admin_team_id TEXT;
+BEGIN
+  SELECT id INTO admin_team_id
+  FROM public."teams"
+  WHERE (metadata->>'systemAdmin')::boolean IS TRUE
+  LIMIT 1;
+
+  IF admin_team_id IS NOT NULL THEN
+    INSERT INTO public."team_members" ("teamId", "userId", role)
+    SELECT admin_team_id, u.id, CASE WHEN u.role = 'superadmin' THEN 'owner' ELSE 'admin' END
+    FROM public."users" u
+    WHERE u.role IN ('developer', 'superadmin')
+    ON CONFLICT ("teamId", "userId") DO UPDATE SET role = EXCLUDED.role;
+  END IF;
+END $$;
+
+-- ============================================
+-- #102 + siblings — switch drifted policies to can_bypass_rls()
+-- ============================================
+
+DROP POLICY IF EXISTS "users_metas_owner_or_admin_all" ON "users_metas";
+CREATE POLICY "users_metas_owner_or_admin_all" ON "users_metas"
+  FOR ALL
+  TO authenticated
+  USING ("userId" = public.get_auth_user_id() OR public.can_bypass_rls())
+  WITH CHECK ("userId" = public.get_auth_user_id() OR public.can_bypass_rls());
+
+DROP POLICY IF EXISTS "API key owner or admin can do all" ON "api_key";
+CREATE POLICY "API key owner or admin can do all" ON "api_key"
+  FOR ALL TO authenticated
+  USING ("userId" = public.get_auth_user_id() OR public.can_bypass_rls())
+  WITH CHECK ("userId" = public.get_auth_user_id() OR public.can_bypass_rls());
+
+DROP POLICY IF EXISTS "API logs superadmin can select" ON "api_audit_log";
+CREATE POLICY "API logs superadmin can select" ON "api_audit_log"
+  FOR SELECT TO authenticated
+  USING (public.can_bypass_rls());
+
+DROP POLICY IF EXISTS "Plans superadmin write" ON public."plans";
+CREATE POLICY "Plans superadmin write"
+ON public."plans"
+FOR ALL TO authenticated
+USING (public.can_bypass_rls())
+WITH CHECK (public.can_bypass_rls());

package/dist/providers/DashboardProviders.d.ts

@@ -1,8 +1,17 @@
 /**
- * DashboardProviders — Client providers needed only for authenticated routes.
+ * DashboardProviders — Client providers needed by authenticated routes.
  *
- * These were moved out of the root layout to avoid loading ~500KB of unused JS
- * (TanStack Query, team context, billing hooks) on public landing pages.
+ * Since #115 the generated root layout mounts QueryProvider, TeamProvider,
+ * SubscriptionProvider and Toaster itself (matching layout.ppr.tsx) so the
+ * activeTeamId cookie is synced from any route, not only from the dashboard.
+ * When a TeamProvider is already mounted above, this component renders its
+ * children as-is: nesting a second TeamProvider would duplicate the teams
+ * fetch, the cookie sync and the TeamSwitchModal, and a second Toaster would
+ * show every toast twice.
+ *
+ * The full provider stack is kept as a fallback for apps whose generated root
+ * layout predates that change (it originally lived here to keep ~500KB of
+ * client JS off public landing pages).
  *
  * Used by: dashboard/layout.tsx, superadmin/layout.tsx, devtools/layout.tsx
  */

package/dist/providers/DashboardProviders.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DashboardProviders.d.ts","sourceRoot":"","sources":["../../src/providers/DashboardProviders.tsx"],"names":[],"mappings":"AAQA;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAAE,2CAW7E"}
+{"version":3,"file":"DashboardProviders.d.ts","sourceRoot":"","sources":["../../src/providers/DashboardProviders.tsx"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAAE,2CAiB7E"}

package/dist/providers/DashboardProviders.js

@@ -1,11 +1,15 @@
 "use client";
-import { jsx, jsxs } from "react/jsx-runtime";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { Suspense } from "react";
 import { QueryProvider } from "./query-provider.js";
-import { TeamProvider } from "../contexts/TeamContext.js";
+import { TeamProvider, useOptionalTeamContext } from "../contexts/TeamContext.js";
 import { SubscriptionProvider } from "../contexts/SubscriptionContext.js";
 import { Toaster } from "../components/ui/sonner.js";
 function DashboardProviders({ children }) {
+  const rootTeamContext = useOptionalTeamContext();
+  if (rootTeamContext) {
+    return /* @__PURE__ */ jsx(Fragment, { children });
+  }
   return /* @__PURE__ */ jsx(QueryProvider, { children: /* @__PURE__ */ jsx(TeamProvider, { children: /* @__PURE__ */ jsxs(SubscriptionProvider, { children: [
     children,
     /* @__PURE__ */ jsx(Suspense, { children: /* @__PURE__ */ jsx(Toaster, { position: "bottom-left" }) })

package/dist/providers/theme-provider.d.ts

@@ -1,3 +1,20 @@
-import { type ThemeProviderProps } from "next-themes";
-export declare function ThemeProvider({ children, ...props }: ThemeProviderProps): import("react/jsx-runtime").JSX.Element;
+import { type ThemeProviderProps as NextThemesProviderProps } from "next-themes";
+import { type ForcedThemeRoutes } from "../lib/theme/forced-theme";
+export interface ThemeProviderProps extends NextThemesProviderProps {
+    /**
+     * Routes whose theme is forced regardless of user/system preference
+     * (`theme.config.ts` → `forcedThemeRoutes`).
+     *
+     * Resolved here, on the client, against `usePathname()` instead of once in
+     * the root layout from request headers: the root layout does not re-render
+     * on client-side navigations, so a server-computed value would go stale as
+     * soon as the user navigated into or out of a forced route. On the initial
+     * request this component is still server-rendered, so next-themes' blocking
+     * script receives the forced value and there is no flash.
+     *
+     * Takes precedence over the plain `forcedTheme` prop.
+     */
+    forcedThemeRoutes?: ForcedThemeRoutes;
+}
+export declare function ThemeProvider({ children, forcedThemeRoutes, forcedTheme, ...props }: ThemeProviderProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=theme-provider.d.ts.map

package/dist/providers/theme-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"theme-provider.d.ts","sourceRoot":"","sources":["../../src/providers/theme-provider.tsx"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAErD,wBAAgB,aAAa,CAAC,EAAE,QAAQ,EAAE,GAAG,KAAK,EAAE,EAAE,kBAAkB,2CAEvE"}
+{"version":3,"file":"theme-provider.d.ts","sourceRoot":"","sources":["../../src/providers/theme-provider.tsx"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,kBAAkB,IAAI,uBAAuB,EAAE,MAAM,aAAa,CAAA;AAChF,OAAO,EAAsB,KAAK,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAEtF,MAAM,WAAW,kBAAmB,SAAQ,uBAAuB;IACjE;;;;;;;;;;;;OAYG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAA;CACtC;AAED,wBAAgB,aAAa,CAAC,EAAE,QAAQ,EAAE,iBAAiB,EAAE,WAAW,EAAE,GAAG,KAAK,EAAE,EAAE,kBAAkB,2CASvG"}

package/dist/providers/theme-provider.js

@@ -1,8 +1,12 @@
 "use client";
 import { jsx } from "react/jsx-runtime";
+import { usePathname } from "next/navigation";
 import { ThemeProvider as NextThemesProvider } from "next-themes";
-function ThemeProvider({ children, ...props }) {
-  return /* @__PURE__ */ jsx(NextThemesProvider, { ...props, children });
+import { resolveForcedTheme } from "../lib/theme/forced-theme.js";
+function ThemeProvider({ children, forcedThemeRoutes, forcedTheme, ...props }) {
+  const pathname = usePathname();
+  const routeForcedTheme = resolveForcedTheme(pathname, forcedThemeRoutes);
+  return /* @__PURE__ */ jsx(NextThemesProvider, { ...props, forcedTheme: routeForcedTheme ?? forcedTheme, children });
 }
 export {
   ThemeProvider

package/dist/templates/app/(auth)/signup/page.tsx

@@ -4,6 +4,7 @@ import { redirect } from 'next/navigation'
 import { SignupForm } from '@nextsparkjs/core/components/auth/forms/SignupForm'
 import { getTemplateOrDefault, getMetadataOrDefault } from '@nextsparkjs/core/lib/template-resolver'
 import { AUTH_CONFIG } from '@nextsparkjs/core/lib/config'
+import { resolveAuthMethods } from '@nextsparkjs/core/lib/auth/auth-methods'
 import { TeamService } from '@nextsparkjs/core/lib/services'
 
 // This page reads DB state (TeamService.hasGlobal) and redirect()s during render,
@@ -23,6 +24,13 @@ export const metadata: Metadata = getMetadataOrDefault(
 async function SignupPageContent() {
   const registrationMode = AUTH_CONFIG?.registration?.mode ?? 'open'
 
+  // Passwordless preset (no 'email-password' in auth.methods): the account is
+  // created by the first one-time-code sign-in, so there is no password signup
+  // form to show — send people to /login instead.
+  if (!resolveAuthMethods(AUTH_CONFIG).includes('email-password')) {
+    redirect('/login')
+  }
+
   // In invitation-only mode, allow the first user to register
   // (when no global team exists yet). Subsequent users need invitations.
   if (registrationMode === 'invitation-only') {

package/dist/templates/app/(public)/[...slug]/page.tsx

@@ -13,7 +13,6 @@
  * 2. Falls back to default PageRenderer if no template
  */
 
-import { Suspense } from 'react'
 import { notFound } from 'next/navigation'
 import { query } from '@nextsparkjs/core/lib/db'
 import { PageRenderer } from '@nextsparkjs/core/components/public/pageBuilder'
@@ -249,9 +248,16 @@ export async function generateMetadata({
 }
 
 /**
- * Main catch-all page content (async, wrapped in Suspense by parent)
+ * Main catch-all page component
+ *
+ * Not wrapped in Suspense: this route's entire content depends on whether the
+ * slug resolves to a published item, so notFound() must be able to run before
+ * any part of the response commits to a 200. A Suspense boundary here would
+ * let Next.js flush the (null) fallback with a 200 status ahead of the
+ * DB-backed lookup, so a later notFound() inside the boundary could no longer
+ * change the status code — see #129.
  */
-async function DynamicPublicPageContent({
+export default async function DynamicPublicPage({
   params,
   searchParams,
 }: PageProps) {
@@ -378,14 +384,3 @@ async function DynamicPublicPageContent({
   // No match found
   notFound()
 }
-
-/**
- * Main catch-all page component — wraps async content in Suspense for PPR compatibility
- */
-export default function DynamicPublicPage(props: PageProps) {
-  return (
-    <Suspense fallback={null}>
-      <DynamicPublicPageContent {...props} />
-    </Suspense>
-  )
-}

package/dist/templates/app/api/auth/[...all]/route.ts

@@ -9,6 +9,7 @@ import { TeamService } from "@nextsparkjs/core/lib/services";
 import { wrapAuthHandlerWithCors, handleCorsPreflightRequest, addCorsHeaders } from "@nextsparkjs/core/lib/api/helpers";
 import { checkDistributedRateLimit } from "@nextsparkjs/core/lib/api/rate-limit";
 import { withSignupContext } from "@nextsparkjs/core/lib/auth-context";
+import { dispatchSecurityNotificationsForRequest } from "@nextsparkjs/core/lib/auth/security-notifications";
 
 const handlers = toNextJsHandler(auth);
 
@@ -181,11 +182,32 @@ export async function POST(req: NextRequest) {
       ? (req.cookies.get('signup-intent')?.value || undefined)
       : undefined;
 
+  // Clone the request BEFORE the handler consumes its body. The
+  // security-notifications dispatcher (below) needs the original request's
+  // headers (UA/IP) and, for change-email, its body (newEmail) — but
+  // handlers.POST(req) reads req's body exactly once.
+  const securityReq = req.clone() as NextRequest;
+
   // Wrap with CORS headers for cross-origin requests (mobile apps, etc.)
-  return wrapAuthHandlerWithCors(
+  const response = await wrapAuthHandlerWithCors(
     signupIntent
       ? () => withSignupContext({ signupIntent }, () => handlers.POST(req))
       : () => handlers.POST(req),
     req
   );
+
+  // Built-in security email notifications (issue #75): after a successful
+  // sign-in / change-password / change-email, queue the matching security
+  // email. Guarded by AUTH_CONFIG.securityNotifications.enabled and wrapped in
+  // try/catch — a notification failure must NEVER change the auth response
+  // status (the dispatcher is itself best-effort, this is defense in depth).
+  if (AUTH_CONFIG.securityNotifications?.enabled) {
+    try {
+      await dispatchSecurityNotificationsForRequest(securityReq, response);
+    } catch (error) {
+      console.error("[auth] security-notifications dispatch error:", error);
+    }
+  }
+
+  return response;
 }

package/dist/templates/app/api/health/route.ts

@@ -24,8 +24,10 @@ export const GET = withRateLimitTier(async (request: NextRequest) => {
     timestamp: new Date().toISOString(),
   };
 
-  // Check if caller is authenticated for detailed info
-  const authResult = await authenticateRequest(request);
+  // Check if caller is authenticated for detailed info. Public endpoint: any
+  // valid API key (whatever its scopes) may see the detailed status, so the
+  // scope-agnostic opt-out is explicit here (#93).
+  const authResult = await authenticateRequest(request, { allowAnyScope: true });
   const isAuthenticated = authResult.success && authResult.user;
 
   if (!isAuthenticated) {

package/dist/templates/app/api/internal/user-metadata/route.ts

@@ -1,14 +1,16 @@
 import { NextRequest, NextResponse } from 'next/server'
 import { MetaService } from '@nextsparkjs/core/lib/services/meta.service'
 import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
-import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { authenticateRequest, createAuthFailureResponse } from '@nextsparkjs/core/lib/api/auth/dual-auth'
 
 // Endpoint interno para crear metadata default después del signup
 export const POST = withRateLimitTier(async (req: NextRequest) => {
   try {
-    const authResult = await authenticateRequest(req)
+    // The API-key scope is declared at the entry point, which fails closed
+    // for keys that lack it (#93).
+    const authResult = await authenticateRequest(req, { requiredScope: 'users:write' })
     if (!authResult.success || !authResult.user) {
-      return NextResponse.json({ error: 'Authentication required' }, { status: 401 })
+      return createAuthFailureResponse(authResult)
     }
 
     const body = await req.json()

package/dist/templates/app/api/mcp/route.ts

@@ -106,7 +106,10 @@ async function handleMcpPost(request: NextRequest): Promise<NextResponse> {
     return jsonRpcError(403, -32000, 'Origin not allowed')
   }
 
-  const authResult = await authenticateRequest(request)
+  // Transport-level auth only: per-tool scopes (`<entity>:read/write/delete`)
+  // are enforced by the generic entity handlers the executor invokes for each
+  // tool call, so this entry point accepts any valid key explicitly (#93).
+  const authResult = await authenticateRequest(request, { allowAnyScope: true })
   if (!authResult.success || authResult.type !== 'api-key' || !authResult.user) {
     return jsonRpcError(401, -32001, API_KEY_HELP)
   }

package/dist/templates/app/api/superadmin/subscriptions/route.ts

@@ -230,6 +230,7 @@ export const GET = withRateLimitTier(async (request: NextRequest) => {
     const totalPages = Math.ceil(total / limit);
 
     // Format subscriptions
+    const billingGateway = await getBillingGateway()
     const subscriptions = subscriptionsResult.map(sub => ({
       id: sub.id,
       team: {
@@ -257,7 +258,7 @@ export const GET = withRateLimitTier(async (request: NextRequest) => {
       cancelAtPeriodEnd: sub.cancelAtPeriodEnd,
       externalSubscriptionId: sub.externalSubscriptionId,
       paymentProvider: sub.paymentProvider,
-      providerDashboardUrl: getBillingGateway().getSubscriptionDashboardUrl(sub.externalSubscriptionId),
+      providerDashboardUrl: billingGateway.getSubscriptionDashboardUrl(sub.externalSubscriptionId),
       createdAt: sub.createdAt
     }));
 

package/dist/templates/app/api/superadmin/teams/[teamId]/route.ts

@@ -204,6 +204,7 @@ export const GET = withRateLimitTier(async (
     const subscription = subscriptionResult[0] || null;
 
     // Prepare response data
+    const billingGateway = subscription ? await getBillingGateway() : null
     const responseData = {
       team: {
         id: team.id,
@@ -225,7 +226,7 @@ export const GET = withRateLimitTier(async (
         role: member.role,
         joinedAt: member.joinedAt
       })),
-      subscription: subscription ? {
+      subscription: subscription && billingGateway ? {
         id: subscription.id,
         plan: {
           id: subscription.planId,
@@ -246,8 +247,8 @@ export const GET = withRateLimitTier(async (
         externalSubscriptionId: subscription.externalSubscriptionId,
         externalCustomerId: subscription.externalCustomerId,
         paymentProvider: subscription.paymentProvider,
-        providerName: getBillingGateway().getProviderName(),
-        providerDashboardUrl: getBillingGateway().getSubscriptionDashboardUrl(subscription.externalSubscriptionId),
+        providerName: billingGateway.getProviderName(),
+        providerDashboardUrl: billingGateway.getSubscriptionDashboardUrl(subscription.externalSubscriptionId),
         createdAt: subscription.createdAt
       } : null,
       billingHistory: billingEventsResult.map((event) => ({

package/dist/templates/app/api/superadmin/users/[userId]/route.ts

@@ -129,11 +129,18 @@ export const GET = withRateLimitTier(async (request: NextRequest, { params }: Ro
       ORDER BY "metaKey"
     `;
 
-    // Execute all queries in parallel
+    // Execute all queries in parallel.
+    //
+    // The team_members queries run on the service (RLS-bypass) pool: team_members
+    // has no superadmin/developer bypass policy, so with the acting admin's own
+    // id as RLS context the SELECT policy silently ANDs "teams the actor belongs
+    // to" on top of WHERE "userId" = $1 and under-reports multi-team users.
+    // Authorization is already enforced above (superadmin/developer role check)
+    // and the WHERE clause scopes the rows to the subject user.
     const [userResults, teamsResults, countsResults, metasResults] = await Promise.all([
       queryWithRLS(userQuery, [userId], session.user.id) as Promise<UserResult[]>,
-      queryWithRLS(teamsQuery, [userId], session.user.id) as Promise<TeamMembershipResult[]>,
-      queryWithRLS(countsQuery, [userId], session.user.id) as Promise<{
+      queryWithRLS(teamsQuery, [userId], session.user.id, { service: true }) as Promise<TeamMembershipResult[]>,
+      queryWithRLS(countsQuery, [userId], session.user.id, { service: true }) as Promise<{
         totalTeams: number;
         ownedTeams: number;
       }[]>,