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

package/dist/contexts/TeamContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TeamContext.d.ts","sourceRoot":"","sources":["../../src/contexts/TeamContext.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAwE,SAAS,EAAE,MAAM,OAAO,CAAA;AAGvG,OAAO,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAM7D,UAAU,gBAAgB;IACxB,WAAW,EAAE,IAAI,GAAG,IAAI,CAAA;IACxB,SAAS,EAAE,kBAAkB,EAAE,CAAA;IAC/B,SAAS,EAAE,OAAO,CAAA;IAClB,WAAW,EAAE,OAAO,CAAA;IACpB,wBAAwB,EAAE,OAAO,CAAA;IACjC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7C,YAAY,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAClC;AAKD,eAAO,MAAM,eAAe,yBAA0B,CAAA;AAGtD,wBAAsB,cAAc,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAwBpE;AAED,wBAAgB,YAAY,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,2CAuNjE;AAED,wBAAgB,cAAc,qBAM7B"}
+{"version":3,"file":"TeamContext.d.ts","sourceRoot":"","sources":["../../src/contexts/TeamContext.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAwE,SAAS,EAAE,MAAM,OAAO,CAAA;AAGvG,OAAO,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAM7D,UAAU,gBAAgB;IACxB,WAAW,EAAE,IAAI,GAAG,IAAI,CAAA;IACxB,SAAS,EAAE,kBAAkB,EAAE,CAAA;IAC/B,SAAS,EAAE,OAAO,CAAA;IAClB,WAAW,EAAE,OAAO,CAAA;IACpB,wBAAwB,EAAE,OAAO,CAAA;IACjC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7C,YAAY,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAClC;AAKD,eAAO,MAAM,eAAe,yBAA0B,CAAA;AAGtD,wBAAsB,cAAc,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAwBpE;AAED,wBAAgB,YAAY,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,2CAqOjE;AAED,wBAAgB,cAAc,qBAM7B;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,IAAI,gBAAgB,GAAG,SAAS,CAErE"}

package/dist/contexts/TeamContext.js

@@ -82,7 +82,10 @@ function TeamProvider({ children }) {
     if (currentTeam && userTeams.some((t) => t.team.id === currentTeam.id)) return;
     const storedTeamId = typeof window !== "undefined" ? localStorage.getItem("activeTeamId") : null;
     const storedTeam = storedTeamId ? userTeams.find((t) => t.team.id === storedTeamId) : null;
-    const activeTeam = storedTeam || userTeams[0];
+    const defaultTeam = storedTeam ? void 0 : [...userTeams].sort(
+      (a, b) => new Date(a.joinedAt).getTime() - new Date(b.joinedAt).getTime()
+    )[0];
+    const activeTeam = storedTeam || defaultTeam;
     if (activeTeam) {
       setCurrentTeam(activeTeam.team);
       if (typeof window !== "undefined") {
@@ -181,9 +184,13 @@ function useTeamContext() {
   }
   return context;
 }
+function useOptionalTeamContext() {
+  return useContext(TeamContext);
+}
 export {
   TEAMS_QUERY_KEY,
   TeamProvider,
   fetchUserTeams,
+  useOptionalTeamContext,
   useTeamContext
 };

package/dist/emails/otp-verification.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"otp-verification.d.ts","sourceRoot":"","sources":["../../src/emails/otp-verification.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAKjF,wBAA8B,eAAe,CAC3C,IAAI,EAAE,wBAAwB,EAC9B,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,YAAY,CAAC,CAkEvB"}
+{"version":3,"file":"otp-verification.d.ts","sourceRoot":"","sources":["../../src/emails/otp-verification.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAKjF,wBAA8B,eAAe,CAC3C,IAAI,EAAE,wBAAwB,EAC9B,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,YAAY,CAAC,CAmEvB"}

package/dist/emails/reset-password.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reset-password.d.ts","sourceRoot":"","sources":["../../src/emails/reset-password.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAI/E,wBAA8B,aAAa,CACzC,IAAI,EAAE,sBAAsB,EAC5B,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,YAAY,CAAC,CA0FvB"}
+{"version":3,"file":"reset-password.d.ts","sourceRoot":"","sources":["../../src/emails/reset-password.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAI/E,wBAA8B,aAAa,CACzC,IAAI,EAAE,sBAAsB,EAC5B,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,YAAY,CAAC,CA2FvB"}

package/dist/emails/team-invitation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"team-invitation.d.ts","sourceRoot":"","sources":["../../src/emails/team-invitation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAIhF,wBAA8B,cAAc,CAC1C,IAAI,EAAE,uBAAuB,EAC7B,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,YAAY,CAAC,CAwFvB"}
+{"version":3,"file":"team-invitation.d.ts","sourceRoot":"","sources":["../../src/emails/team-invitation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAKhF,wBAA8B,cAAc,CAC1C,IAAI,EAAE,uBAAuB,EAC7B,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,YAAY,CAAC,CAyFvB"}

package/dist/emails/team-invitation.js

@@ -1,4 +1,5 @@
 import { getTranslations } from "next-intl/server";
+import { escapeHtml } from "../lib/auth/security-notifications/templates/shared.js";
 const APP_NAME_FALLBACK = process.env.NEXT_PUBLIC_APP_NAME || "Your App";
 async function teamInvitation(data, locale) {
   const t = await getTranslations({ locale, namespace: "email.teamInvitation" });
@@ -32,7 +33,7 @@ async function teamInvitation(data, locale) {
                       <h2 style="color: #333333; font-size: 24px; margin: 0 0 20px 0; font-weight: 600;">${t("title")}</h2>
 
                       <p style="color: #666666; font-size: 16px; line-height: 1.6; margin: 0 0 20px 0;">
-                        ${t("bodyIntro", { inviterName: data.inviterName, teamName: data.teamName, role: data.role })}
+                        ${t("bodyIntro", { inviterName: escapeHtml(data.inviterName), teamName: escapeHtml(data.teamName), role: data.role })}
                       </p>
 
                       <p style="color: #666666; font-size: 16px; line-height: 1.6; margin: 0 0 30px 0;">
@@ -74,7 +75,7 @@ async function teamInvitation(data, locale) {
                         ${t("copyright", { year, appName })}
                       </p>
                       <p style="color: #999999; font-size: 12px; margin: 0;">
-                        ${t("footerSentTo", { inviteeEmail: data.inviteeEmail })}<br>
+                        ${t("footerSentTo", { inviteeEmail: escapeHtml(data.inviteeEmail) })}<br>
                         ${t("footerUnexpected")}
                       </p>
                     </td>

package/dist/emails/verify-email.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify-email.d.ts","sourceRoot":"","sources":["../../src/emails/verify-email.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAI9E,wBAA8B,WAAW,CACvC,IAAI,EAAE,qBAAqB,EAC3B,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,YAAY,CAAC,CA+EvB"}
+{"version":3,"file":"verify-email.d.ts","sourceRoot":"","sources":["../../src/emails/verify-email.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAI9E,wBAA8B,WAAW,CACvC,IAAI,EAAE,qBAAqB,EAC3B,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,YAAY,CAAC,CAgFvB"}

package/dist/hooks/index.d.ts

@@ -17,6 +17,7 @@ export * from './useFeature';
 export * from './useInvoice';
 export * from './useInvoices';
 export * from './useLastAuthMethod';
+export * from './useSessionCookieRefresh';
 export * from './useLocale';
 export * from './useMedia';
 export * from './useMediaUpload';

package/dist/hooks/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAGA,cAAc,4BAA4B,CAAA;AAC1C,cAAc,WAAW,CAAA;AACzB,cAAc,yBAAyB,CAAA;AACvC,cAAc,yBAAyB,CAAA;AACvC,cAAc,+BAA+B,CAAA;AAC7C,cAAc,eAAe,CAAA;AAC7B,cAAc,sBAAsB,CAAA;AACpC,cAAc,yBAAyB,CAAA;AACvC,cAAc,aAAa,CAAA;AAC3B,cAAc,mBAAmB,CAAA;AACjC,cAAc,sBAAsB,CAAA;AACpC,cAAc,kBAAkB,CAAA;AAChC,cAAc,mBAAmB,CAAA;AACjC,cAAc,yBAAyB,CAAA;AACvC,cAAc,qBAAqB,CAAA;AACnC,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,eAAe,CAAA;AAC7B,cAAc,qBAAqB,CAAA;AACnC,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,kBAAkB,CAAA;AAChC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,aAAa,CAAA;AAC3B,cAAc,oBAAoB,CAAA;AAClC,cAAc,0BAA0B,CAAA;AACxC,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,mBAAmB,CAAA;AACjC,cAAc,mBAAmB,CAAA;AACjC,cAAc,WAAW,CAAA;AACzB,cAAc,sBAAsB,CAAA;AACpC,cAAc,kBAAkB,CAAA;AAChC,cAAc,YAAY,CAAA;AAC1B,cAAc,kBAAkB,CAAA;AAChC,cAAc,YAAY,CAAA;AAC1B,cAAc,yBAAyB,CAAA;AACvC,cAAc,qBAAqB,CAAA;AACnC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,kBAAkB,CAAA;AAChC,cAAc,mBAAmB,CAAA;AACjC,cAAc,wBAAwB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAGA,cAAc,4BAA4B,CAAA;AAC1C,cAAc,WAAW,CAAA;AACzB,cAAc,yBAAyB,CAAA;AACvC,cAAc,yBAAyB,CAAA;AACvC,cAAc,+BAA+B,CAAA;AAC7C,cAAc,eAAe,CAAA;AAC7B,cAAc,sBAAsB,CAAA;AACpC,cAAc,yBAAyB,CAAA;AACvC,cAAc,aAAa,CAAA;AAC3B,cAAc,mBAAmB,CAAA;AACjC,cAAc,sBAAsB,CAAA;AACpC,cAAc,kBAAkB,CAAA;AAChC,cAAc,mBAAmB,CAAA;AACjC,cAAc,yBAAyB,CAAA;AACvC,cAAc,qBAAqB,CAAA;AACnC,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,eAAe,CAAA;AAC7B,cAAc,qBAAqB,CAAA;AACnC,cAAc,2BAA2B,CAAA;AACzC,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,kBAAkB,CAAA;AAChC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,aAAa,CAAA;AAC3B,cAAc,oBAAoB,CAAA;AAClC,cAAc,0BAA0B,CAAA;AACxC,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,mBAAmB,CAAA;AACjC,cAAc,mBAAmB,CAAA;AACjC,cAAc,WAAW,CAAA;AACzB,cAAc,sBAAsB,CAAA;AACpC,cAAc,kBAAkB,CAAA;AAChC,cAAc,YAAY,CAAA;AAC1B,cAAc,kBAAkB,CAAA;AAChC,cAAc,YAAY,CAAA;AAC1B,cAAc,yBAAyB,CAAA;AACvC,cAAc,qBAAqB,CAAA;AACnC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,kBAAkB,CAAA;AAChC,cAAc,mBAAmB,CAAA;AACjC,cAAc,wBAAwB,CAAA"}

package/dist/hooks/index.js

@@ -17,6 +17,7 @@ export * from "./useFeature.js";
 export * from "./useInvoice.js";
 export * from "./useInvoices.js";
 export * from "./useLastAuthMethod.js";
+export * from "./useSessionCookieRefresh.js";
 export * from "./useLocale.js";
 export * from "./useMedia.js";
 export * from "./useMediaUpload.js";

package/dist/hooks/useAuth.d.ts

@@ -102,6 +102,35 @@ export declare function useAuth(): {
     })>;
     signOut: () => Promise<void>;
     googleSignIn: (redirectTo?: string) => Promise<void>;
+    sendOtp: (email: string) => Promise<{
+        success: boolean;
+    }>;
+    signInWithOtp: ({ email, otp, redirectTo }: {
+        email: string;
+        otp: string;
+        redirectTo?: string;
+    }) => Promise<Omit<{
+        token: string;
+        user: {
+            id: string;
+            createdAt: Date;
+            updatedAt: Date;
+            email: string;
+            emailVerified: boolean;
+            name: string;
+            image?: string | null | undefined;
+        };
+    }, "user"> & {
+        user: import("better-auth").StripEmptyObjects<{
+            id: string;
+            createdAt: Date;
+            updatedAt: Date;
+            emailVerified: boolean;
+            name: string;
+            email?: string;
+            image?: string;
+        } & {} & {}>;
+    }>;
     resetPassword: (email: string) => Promise<{
         success: boolean;
         data: any;

package/dist/hooks/useAuth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useAuth.d.ts","sourceRoot":"","sources":["../../src/hooks/useAuth.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAS9C,wBAAgB,OAAO;UAuMS,WAAW,GAAG,IAAI;;;;;;;;;;;;;;;;;;;;;;;8CAjMa;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE;;;;;;;;;;;;;;;;;;;;;;;;+DAmBvC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gCAkC1H,MAAM;2BAYX,MAAM;;;;;;;;;;;;kCA6BC,MAAM,UAAU,MAAM;;;;;;;;;;;sCAwClB,MAAM,eAAe,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qCA8B5B,MAAM;;;;;;;;;;;;;;;EA6C3D"}
+{"version":3,"file":"useAuth.d.ts","sourceRoot":"","sources":["../../src/hooks/useAuth.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAS9C,wBAAgB,OAAO;UA4OS,WAAW,GAAG,IAAI;;;;;;;;;;;;;;;;;;;;;;;8CAtOa;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE;;;;;;;;;;;;;;;;;;;;;;;;+DAmBvC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gCAuE1H,MAAM;qBAhCjB,MAAM;;;gDAgBiB;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE;;;;;;;;;iBA8Kyf,CAAC;;;;;;;;;;;;;2BAlJ9jB,MAAM;;;;;;;;;;;;kCA6BC,MAAM,UAAU,MAAM;;;;;;;;;;;sCAwClB,MAAM,eAAe,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qCA8B5B,MAAM;;;;;;;;;;;;;;;EA+C3D"}

package/dist/hooks/useAuth.js

@@ -29,6 +29,7 @@ function useAuth() {
         email,
         password,
         name: `${firstName || ""} ${lastName || ""}`.trim() || email.split("@")[0],
+        // @ts-expect-error — pre-existing type error, tracked in https://github.com/NextSpark-js/nextspark/issues/131
         firstName,
         lastName
       },
@@ -48,6 +49,27 @@ function useAuth() {
     await authClient.signOut();
     router.push("/login");
   };
+  const handleSendOtp = async (email) => {
+    const { data, error } = await authClient.emailOtp.sendVerificationOtp({
+      email,
+      type: "sign-in"
+    });
+    if (error) {
+      throw new Error(error.message || "Failed to send the sign-in code");
+    }
+    return data;
+  };
+  const handleOtpSignIn = async ({ email, otp, redirectTo }) => {
+    const { data, error } = await authClient.signIn.emailOtp({ email, otp });
+    if (error) {
+      throw new Error(error.message || "Invalid or expired code");
+    }
+    if (data) {
+      saveAuthMethod("email");
+      router.push(redirectTo || "/dashboard");
+    }
+    return data;
+  };
   const handleGoogleSignIn = async (redirectTo) => {
     const callbackURL = redirectTo ? `${redirectTo}${redirectTo.includes("?") ? "&" : "?"}auth_method=google` : "/dashboard?auth_method=google";
     await authClient.signIn.social({
@@ -174,6 +196,8 @@ function useAuth() {
     signUp: handleSignUp,
     signOut: handleSignOut,
     googleSignIn: handleGoogleSignIn,
+    sendOtp: handleSendOtp,
+    signInWithOtp: handleOtpSignIn,
     resetPassword: handleResetPassword,
     updatePassword: handleUpdatePassword,
     changePassword: handleChangePassword,

package/dist/hooks/useEnsureUserMetadata.d.ts

@@ -1,6 +1,28 @@
+interface UserMetadata {
+    uiPreferences?: {
+        theme?: string;
+        sidebarCollapsed?: boolean;
+    };
+    securityPreferences?: {
+        loginAlertsEnabled?: boolean;
+    };
+    notificationsPreferences?: Record<string, boolean>;
+}
+/**
+ * Returns the default blocks (uiPreferences, securityPreferences,
+ * notificationsPreferences) that are still missing from the user's meta.
+ *
+ * Each block is checked independently: other flows (onboarding progress, tours,
+ * active team pointer, ...) write their own keys into `meta` early, so an
+ * "is meta empty?" guard would almost never fire for real users (see #119).
+ * Only the missing blocks are returned so existing preferences are never
+ * overwritten.
+ */
+export declare function getMissingMetadataDefaults(meta: UserMetadata | null | undefined): Partial<UserMetadata>;
 /**
  * Hook to ensure user has default metadata
  * Uses TanStack Query for proper caching and deduplication
  */
 export declare function useEnsureUserMetadata(): void;
+export {};
 //# sourceMappingURL=useEnsureUserMetadata.d.ts.map

package/dist/hooks/useEnsureUserMetadata.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useEnsureUserMetadata.d.ts","sourceRoot":"","sources":["../../src/hooks/useEnsureUserMetadata.ts"],"names":[],"mappings":"AAsDA;;;GAGG;AACH,wBAAgB,qBAAqB,SA+DpC"}
+{"version":3,"file":"useEnsureUserMetadata.d.ts","sourceRoot":"","sources":["../../src/hooks/useEnsureUserMetadata.ts"],"names":[],"mappings":"AAOA,UAAU,YAAY;IACpB,aAAa,CAAC,EAAE;QACd,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,gBAAgB,CAAC,EAAE,OAAO,CAAA;KAC3B,CAAA;IACD,mBAAmB,CAAC,EAAE;QACpB,kBAAkB,CAAC,EAAE,OAAO,CAAA;KAC7B,CAAA;IACD,wBAAwB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnD;AA0CD;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,GACpC,OAAO,CAAC,YAAY,CAAC,CASvB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,SAgEpC"}

package/dist/hooks/useEnsureUserMetadata.js

@@ -33,6 +33,17 @@ const DEFAULT_METADATA = {
     featureAnnouncementsPush: false
   }
 };
+const METADATA_BLOCKS = Object.keys(DEFAULT_METADATA);
+function getMissingMetadataDefaults(meta) {
+  const missing = {};
+  for (const block of METADATA_BLOCKS) {
+    const current = meta == null ? void 0 : meta[block];
+    if (current === null || current === void 0) {
+      missing[block] = DEFAULT_METADATA[block];
+    }
+  }
+  return missing;
+}
 function useEnsureUserMetadata() {
   var _a, _b;
   const session = authClient.useSession();
@@ -57,7 +68,7 @@ function useEnsureUserMetadata() {
     // 30 minutes cache
   });
   const createMetadataMutation = useMutation({
-    mutationFn: async () => {
+    mutationFn: async (metadata) => {
       const response = await fetch("/api/internal/user-metadata", {
         method: "POST",
         headers: {
@@ -65,7 +76,7 @@ function useEnsureUserMetadata() {
         },
         body: JSON.stringify({
           userId,
-          metadata: DEFAULT_METADATA
+          metadata
         })
       });
       if (!response.ok) {
@@ -82,14 +93,16 @@ function useEnsureUserMetadata() {
   });
   useEffect(() => {
     if (!isFetched || !userData || hasCreatedMetadata.current) return;
-    const needsMetadata = !userData.meta || Object.keys(userData.meta).length === 0;
+    const missingDefaults = getMissingMetadataDefaults(userData.meta);
+    const needsMetadata = Object.keys(missingDefaults).length > 0;
     if (needsMetadata && !createMetadataMutation.isPending) {
       hasCreatedMetadata.current = true;
-      console.log("Creating default metadata for user:", userId);
-      createMetadataMutation.mutate();
+      console.log("Creating default metadata for user:", userId, Object.keys(missingDefaults));
+      createMetadataMutation.mutate(missingDefaults);
     }
   }, [isFetched, userData, userId, createMetadataMutation]);
 }
 export {
+  getMissingMetadataDefaults,
   useEnsureUserMetadata
 };

package/dist/hooks/useSessionCookieRefresh.d.ts

@@ -0,0 +1,35 @@
+export interface UseSessionCookieRefreshOptions {
+    /**
+     * Minimum time between two refresh calls, in milliseconds. Every trigger
+     * inside this window is ignored. Default: 5 minutes (matches the default
+     * session cookie cache, so at most one extra DB read per 5 minutes).
+     */
+    minIntervalMs?: number;
+    /**
+     * Also refresh once right after mount — i.e. every time the app is opened
+     * (PWA cold start, full reload). Default: true.
+     */
+    refreshOnMount?: boolean;
+    /** Set to false to turn the hook off (e.g. on public/auth pages). Default: true. */
+    enabled?: boolean;
+}
+export declare const DEFAULT_SESSION_REFRESH_INTERVAL_MS: number;
+/**
+ * Keep the session cookie alive for installed PWAs / long-lived tabs.
+ *
+ * Server Component renders read the session with `disableRefresh`, so they
+ * never renew the cookie (Next.js cannot write cookies during render). This
+ * hook triggers the real renewal through Better Auth's `get-session` Route
+ * Handler — where `Set-Cookie` works — whenever the app is (re)opened:
+ *
+ * - on mount (app open / reload), unless `refreshOnMount: false`
+ * - when the document becomes visible again (`visibilitychange`, `focus`,
+ *   `pageshow` for bfcache restores)
+ * - when connectivity comes back (`online`)
+ *
+ * Calls are throttled by `minIntervalMs`; a failed call (offline, server
+ * down) does not count towards the throttle, so the next trigger retries.
+ * Anonymous visitors just get a cheap `null` session response.
+ */
+export declare function useSessionCookieRefresh(options?: UseSessionCookieRefreshOptions): void;
+//# sourceMappingURL=useSessionCookieRefresh.d.ts.map

package/dist/hooks/useSessionCookieRefresh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSessionCookieRefresh.d.ts","sourceRoot":"","sources":["../../src/hooks/useSessionCookieRefresh.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,8BAA8B;IAC7C;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,oFAAoF;IACpF,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,eAAO,MAAM,mCAAmC,QAAgB,CAAA;AAEhE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,8BAAmC,QAmDnF"}

package/dist/hooks/useSessionCookieRefresh.js

@@ -0,0 +1,49 @@
+"use client";
+import { useEffect, useRef } from "react";
+import { refreshSessionCookie } from "../lib/auth-client.js";
+const DEFAULT_SESSION_REFRESH_INTERVAL_MS = 5 * 60 * 1e3;
+function useSessionCookieRefresh(options = {}) {
+  const {
+    minIntervalMs = DEFAULT_SESSION_REFRESH_INTERVAL_MS,
+    refreshOnMount = true,
+    enabled = true
+  } = options;
+  const lastRefreshAtRef = useRef(0);
+  const inFlightRef = useRef(false);
+  useEffect(() => {
+    if (!enabled || typeof window === "undefined") return;
+    const refresh = async () => {
+      if (inFlightRef.current) return;
+      const now = Date.now();
+      if (now - lastRefreshAtRef.current < minIntervalMs) return;
+      inFlightRef.current = true;
+      lastRefreshAtRef.current = now;
+      try {
+        await refreshSessionCookie();
+      } catch {
+        lastRefreshAtRef.current = 0;
+      } finally {
+        inFlightRef.current = false;
+      }
+    };
+    const onVisibilityChange = () => {
+      if (document.visibilityState === "visible") void refresh();
+    };
+    const onWake = () => void refresh();
+    document.addEventListener("visibilitychange", onVisibilityChange);
+    window.addEventListener("focus", onWake);
+    window.addEventListener("pageshow", onWake);
+    window.addEventListener("online", onWake);
+    if (refreshOnMount) void refresh();
+    return () => {
+      document.removeEventListener("visibilitychange", onVisibilityChange);
+      window.removeEventListener("focus", onWake);
+      window.removeEventListener("pageshow", onWake);
+      window.removeEventListener("online", onWake);
+    };
+  }, [enabled, minIntervalMs, refreshOnMount]);
+}
+export {
+  DEFAULT_SESSION_REFRESH_INTERVAL_MS,
+  useSessionCookieRefresh
+};

package/dist/lib/api/api-error.d.ts

@@ -7,8 +7,10 @@
 export declare const API_ERROR_CODES: {
     /** Role-based permission check failed (checkPermission) */
     readonly PERMISSION_DENIED: "PERMISSION_DENIED";
-    /** API key scope check failed (hasRequiredScope) */
+    /** API key lacks the scope the route declared (authenticateRequest / hasRequiredScope) */
     readonly INSUFFICIENT_SCOPE: "INSUFFICIENT_SCOPE";
+    /** Route declared no required API key scope, so API keys are rejected (fail closed, #93) */
+    readonly SCOPE_NOT_DECLARED: "SCOPE_NOT_DECLARED";
 };
 export type ApiErrorCode = typeof API_ERROR_CODES[keyof typeof API_ERROR_CODES];
 /**

package/dist/lib/api/api-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-error.d.ts","sourceRoot":"","sources":["../../../src/lib/api/api-error.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,eAAe;IAC1B,2DAA2D;;IAE3D,oDAAoD;;CAE5C,CAAA;AAEV,MAAM,MAAM,YAAY,GAAG,OAAO,eAAe,CAAC,MAAM,OAAO,eAAe,CAAC,CAAA;AAE/E;;;;;GAKG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,OAAO,CAAA;gBAEL,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE;IAa5F;;OAEG;IACH,kBAAkB,IAAI,OAAO;IAI7B;;;;;OAKG;WACU,YAAY,CAAC,QAAQ,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;CAqC1F"}
+{"version":3,"file":"api-error.d.ts","sourceRoot":"","sources":["../../../src/lib/api/api-error.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,eAAe;IAC1B,2DAA2D;;IAE3D,0FAA0F;;IAE1F,4FAA4F;;CAEpF,CAAA;AAEV,MAAM,MAAM,YAAY,GAAG,OAAO,eAAe,CAAC,MAAM,OAAO,eAAe,CAAC,CAAA;AAE/E;;;;;GAKG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,OAAO,CAAA;gBAEL,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE;IAa5F;;OAEG;IACH,kBAAkB,IAAI,OAAO;IAI7B;;;;;OAKG;WACU,YAAY,CAAC,QAAQ,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;CAqC1F"}

package/dist/lib/api/api-error.js

@@ -1,8 +1,10 @@
 const API_ERROR_CODES = {
   /** Role-based permission check failed (checkPermission) */
   PERMISSION_DENIED: "PERMISSION_DENIED",
-  /** API key scope check failed (hasRequiredScope) */
-  INSUFFICIENT_SCOPE: "INSUFFICIENT_SCOPE"
+  /** API key lacks the scope the route declared (authenticateRequest / hasRequiredScope) */
+  INSUFFICIENT_SCOPE: "INSUFFICIENT_SCOPE",
+  /** Route declared no required API key scope, so API keys are rejected (fail closed, #93) */
+  SCOPE_NOT_DECLARED: "SCOPE_NOT_DECLARED"
 };
 class ApiError extends Error {
   code;

package/dist/lib/api/auth/dual-auth.d.ts

@@ -5,6 +5,8 @@
  * Used by the unified /api/v1/ endpoints.
  */
 import { NextRequest, NextResponse } from 'next/server';
+import { type AuthenticateOptions, type DualAuthFailure } from './scope-policy';
+export type { AuthenticateOptions, DualAuthFailure, DualAuthFailureCode } from './scope-policy';
 /**
  * System Admin Team - Members can bypass team context validation
  * This team is created in core/migrations/090_sample_data.sql
@@ -33,23 +35,48 @@ export interface DualAuthUser {
 }
 export interface DualAuthResult {
     success: boolean;
+    /**
+     * How the caller authenticated. On a failed result, `'api-key'` means a
+     * valid key WAS presented but rejected by scope enforcement (see `error`);
+     * `'none'` means no usable credential was found.
+     */
     type: 'api-key' | 'session' | 'none';
     user: DualAuthUser | null;
     scopes?: string[];
+    /** `api_key.id` of the key that authenticated the request (type 'api-key' only). Used for audit logging (#105). */
+    keyId?: string;
     rateLimitResponse?: Response;
     /** Set when a dev-only x-act-as-user override replaced the real caller. */
     actingAs?: {
         originalUserId: string;
         originalRole: string;
     };
+    /** Why the request was rejected. Only present when `success` is false. */
+    error?: DualAuthFailure;
 }
 /**
- * Try to authenticate request using either API Key or Session
+ * Try to authenticate request using either API Key or Session.
+ *
+ * API-key scope enforcement happens HERE and fails closed (#93): a route
+ * declares the scope it needs via `options.requiredScope`, or explicitly
+ * accepts any valid key via `options.allowAnyScope`. A key hitting a route
+ * that declared neither is rejected (403 `SCOPE_NOT_DECLARED`) and the route
+ * is named in the log, so a forgotten declaration is visible instead of a
+ * silently over-privileged credential. Session auth is unaffected.
+ *
+ * @example
+ * const authResult = await authenticateRequest(request, { requiredScope: 'users:read' })
+ * if (!authResult.success || !authResult.user) return createAuthFailureResponse(authResult)
  */
-export declare function authenticateRequest(request: NextRequest): Promise<DualAuthResult>;
+export declare function authenticateRequest(request: NextRequest, options?: AuthenticateOptions): Promise<DualAuthResult>;
 /**
  * Check if user has required scope (for API Key auth)
  *
+ * Since #93 the entry point already enforces the route's declared scope;
+ * this remains for routes that branch on a *second*, finer scope after
+ * authenticating (e.g. read-vs-write within one handler). An array is
+ * satisfied by any one of its scopes; an empty array by none.
+ *
  * `admin:all` was previously accepted as an implicit full-access scope here,
  * but it was never in `API_SCOPES`, never mintable via `validateScopesForUser`,
  * and undocumented — a full-access string nothing legitimately produced.
@@ -57,7 +84,7 @@ export declare function authenticateRequest(request: NextRequest): Promise<DualA
  * superadmin, see `validateScopesForUser`) already covers the "this key has
  * full access" case in a documented, auditable way.
  */
-export declare function hasRequiredScope(authResult: DualAuthResult, requiredScope: string): boolean;
+export declare function hasRequiredScope(authResult: DualAuthResult, requiredScope: string | string[]): boolean;
 /**
  * Resolve and validate team context from request.
  *
@@ -92,4 +119,12 @@ export declare function createAuthError(message?: string, status?: number): Next
     error: string;
     code: string;
 }>;
+/**
+ * Turn a failed `authenticateRequest` result into the right HTTP response:
+ * 401 `AUTHENTICATION_FAILED` when nothing usable was presented, 403
+ * `INSUFFICIENT_SCOPE` / `SCOPE_NOT_DECLARED` when a valid API key was
+ * rejected by scope enforcement. Use it in the `!authResult.success` branch
+ * instead of a hand-written 401, so scope rejections are not mislabeled.
+ */
+export declare function createAuthFailureResponse(authResult: DualAuthResult): NextResponse;
 //# sourceMappingURL=dual-auth.d.ts.map

package/dist/lib/api/auth/dual-auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dual-auth.d.ts","sourceRoot":"","sources":["../../../../src/lib/api/auth/dual-auth.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAUvD;;;GAGG;AACH,eAAO,MAAM,oBAAoB,uBAAuB,CAAA;AAExD;;GAEG;AACH,eAAO,MAAM,mBAAmB,mBAAmB,CAAA;AACnD,eAAO,MAAM,kBAAkB,8BAA8B,CAAA;AAE7D;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,kBAAkB,CAAA;AAOjD,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,CAAA;IACpC,IAAI,EAAE,YAAY,GAAG,IAAI,CAAA;IACzB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,iBAAiB,CAAC,EAAE,QAAQ,CAAA;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,EAAE;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAA;CAC5D;AAqBD;;GAEG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CAkBvF;AAqKD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAW3F;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,WAAW,EACpB,UAAU,EAAE,cAAc,GACzB,OAAO,CAAC,MAAM,GAAG,YAAY,CAAC,CAsChC;AAMD;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,cAAc,EAC1B,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,OAAO,CAAC,CAkBlB;AAkBD;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,MAAkC,EAAE,MAAM,GAAE,MAAY;;;;GAShG"}
+{"version":3,"file":"dual-auth.d.ts","sourceRoot":"","sources":["../../../../src/lib/api/auth/dual-auth.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAMvD,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,eAAe,EAKrB,MAAM,gBAAgB,CAAA;AAEvB,YAAY,EAAE,mBAAmB,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAA;AAK/F;;;GAGG;AACH,eAAO,MAAM,oBAAoB,uBAAuB,CAAA;AAExD;;GAEG;AACH,eAAO,MAAM,mBAAmB,mBAAmB,CAAA;AACnD,eAAO,MAAM,kBAAkB,8BAA8B,CAAA;AAE7D;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,kBAAkB,CAAA;AAOjD,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAA;IAChB;;;;OAIG;IACH,IAAI,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,CAAA;IACpC,IAAI,EAAE,YAAY,GAAG,IAAI,CAAA;IACzB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,mHAAmH;IACnH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,iBAAiB,CAAC,EAAE,QAAQ,CAAA;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,EAAE;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAA;IAC3D,0EAA0E;IAC1E,KAAK,CAAC,EAAE,eAAe,CAAA;CACxB;AAqBD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,WAAW,EACpB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,cAAc,CAAC,CAsCzB;AAuKD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAUtG;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,WAAW,EACpB,UAAU,EAAE,cAAc,GACzB,OAAO,CAAC,MAAM,GAAG,YAAY,CAAC,CAsChC;AAMD;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,cAAc,EAC1B,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,OAAO,CAAC,CAkBlB;AA2BD;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,MAAkC,EAAE,MAAM,GAAE,MAAY;;;;GAShG;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,cAAc,GAAG,YAAY,CAUlF"}

package/dist/lib/api/auth/dual-auth.js

@@ -4,6 +4,12 @@ import { validateApiKey } from "../auth.js";
 import { queryOne } from "../../db.js";
 import { TeamMemberService } from "../../services/team-member.service.js";
 import { TeamService } from "../../services/team.service.js";
+import {
+  authenticationFailed,
+  describeRoute,
+  resolveApiKeyScopeFailure,
+  scopesSatisfy
+} from "./scope-policy.js";
 const SYSTEM_ADMIN_TEAM_ID = "team-nextspark-001";
 const ADMIN_BYPASS_HEADER = "x-admin-bypass";
 const ADMIN_BYPASS_VALUE = "confirm-cross-team-access";
@@ -24,9 +30,20 @@ async function getUserDefaultTeamId(userId) {
     return void 0;
   }
 }
-async function authenticateRequest(request) {
+async function authenticateRequest(request, options = {}) {
   const apiKeyResult = await tryApiKeyAuth(request);
   if (apiKeyResult.success) {
+    const failure = resolveApiKeyScopeFailure(apiKeyResult.scopes, options, describeRoute(request));
+    if (failure) {
+      return {
+        success: false,
+        type: "api-key",
+        user: apiKeyResult.user,
+        scopes: apiKeyResult.scopes,
+        keyId: apiKeyResult.keyId,
+        error: failure
+      };
+    }
     return applyActAsOverride(request, apiKeyResult);
   }
   const sessionResult = await trySessionAuth(request);
@@ -36,7 +53,8 @@ async function authenticateRequest(request) {
   return {
     success: false,
     type: "none",
-    user: null
+    user: null,
+    error: authenticationFailed()
   };
 }
 function isProductionRuntime() {
@@ -104,7 +122,8 @@ async function tryApiKeyAuth(request) {
         name: userInfo == null ? void 0 : userInfo.name,
         defaultTeamId
       },
-      scopes: apiAuth.scopes || []
+      scopes: apiAuth.scopes || [],
+      keyId: apiAuth.keyId
     };
   } catch (error) {
     console.error("API Key auth failed:", error);
@@ -128,6 +147,7 @@ async function trySessionAuth(request) {
       user: {
         id: session.user.id,
         email: session.user.email,
+        // @ts-expect-error — pre-existing type error, tracked in https://github.com/NextSpark-js/nextspark/issues/131
         role: session.user.role || "user",
         name: session.user.name,
         defaultTeamId
@@ -144,8 +164,8 @@ function hasRequiredScope(authResult, requiredScope) {
   if (authResult.type === "session") {
     return true;
   }
-  if (authResult.type === "api-key" && authResult.scopes) {
-    return authResult.scopes.includes(requiredScope) || authResult.scopes.includes("*");
+  if (authResult.type === "api-key") {
+    return scopesSatisfy(authResult.scopes, requiredScope);
   }
   return false;
 }
@@ -191,8 +211,11 @@ async function canBypassTeamContext(authResult, request) {
 async function checkSystemAdminMembership(userId) {
   try {
     const member = await queryOne(
-      'SELECT id FROM "team_members" WHERE "teamId" = $1 AND "userId" = $2',
-      [SYSTEM_ADMIN_TEAM_ID, userId]
+      `SELECT tm.id FROM "team_members" tm
+       JOIN "teams" t ON t.id = tm."teamId"
+       WHERE tm."userId" = $1 AND (t.metadata->>'systemAdmin')::boolean IS TRUE
+       LIMIT 1`,
+      [userId]
     );
     return !!member;
   } catch (error) {
@@ -210,6 +233,17 @@ function createAuthError(message = "Authentication required", status = 401) {
     { status }
   );
 }
+function createAuthFailureResponse(authResult) {
+  const failure = authResult.error ?? authenticationFailed();
+  return NextResponse.json(
+    {
+      success: false,
+      error: failure.message,
+      code: failure.code
+    },
+    { status: failure.status }
+  );
+}
 export {
   ACT_AS_USER_HEADER,
   ADMIN_BYPASS_HEADER,
@@ -218,6 +252,7 @@ export {
   authenticateRequest,
   canBypassTeamContext,
   createAuthError,
+  createAuthFailureResponse,
   hasRequiredScope,
   resolveTeamContext
 };

package/dist/lib/api/auth/permissions.d.ts

@@ -17,9 +17,14 @@ export declare function isSuperAdmin(authResult: DualAuthResult): boolean;
  * Verifica si el usuario tiene permisos para operaciones administrativas
  * Combina validacion de superadmin + scopes de API key
  *
+ * Fail closed for API keys (#93): a key is only granted admin access when the
+ * caller names the scope the operation needs and the key holds it. Omitting
+ * `requiredScope` used to hand a narrowly-scoped key its superadmin owner's
+ * full permissions; now it denies the key instead. Sessions are unaffected.
+ *
  * @param authResult - Resultado de autenticacion
- * @param requiredScope - Scope requerido para API keys (opcional)
+ * @param requiredScope - Scope requerido para API keys (obligatorio para que una API key pase)
  * @returns true si tiene permisos de admin
  */
-export declare function hasAdminPermission(authResult: DualAuthResult, requiredScope?: string): boolean;
+export declare function hasAdminPermission(authResult: DualAuthResult, requiredScope?: string | string[]): boolean;
 //# sourceMappingURL=permissions.d.ts.map

package/dist/lib/api/auth/permissions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../../../src/lib/api/auth/permissions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAGjD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,cAAc,GAAG,OAAO,CAOhE;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,cAAc,EAC1B,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAYT"}
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../../../src/lib/api/auth/permissions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAGjD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,cAAc,GAAG,OAAO,CAOhE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,cAAc,EAC1B,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAChC,OAAO,CAYT"}