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

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,24 +35,56 @@ 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.
+ * Removed rather than formalized: the wildcard `*` (mintable only by a real
+ * 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.
  *
@@ -85,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;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAY3F;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("admin:all") || 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"}

package/dist/lib/api/auth/permissions.js

@@ -9,8 +9,8 @@ function hasAdminPermission(authResult, requiredScope) {
   if (!isSuperAdmin(authResult)) {
     return false;
   }
-  if (authResult.type === "api-key" && requiredScope) {
-    return hasRequiredScope(authResult, requiredScope);
+  if (authResult.type === "api-key") {
+    return requiredScope !== void 0 && hasRequiredScope(authResult, requiredScope);
   }
   return true;
 }

package/dist/lib/api/auth/scope-policy.d.ts

@@ -0,0 +1,71 @@
+/**
+ * API-key scope policy (#93)
+ *
+ * Shared by both auth entry points — `authenticateRequest` (dual-auth.ts) and
+ * `validateAndAuthenticateRequest` (helpers.ts) — so the rule cannot drift
+ * between them. Pure: no I/O, no framework imports.
+ *
+ * The rule, applied only to API-key authentication (sessions carry no scopes
+ * and are never gated here):
+ *
+ *   1. The route declared `{ requiredScope }` → the key must hold one of the
+ *      listed scopes (or the wildcard `*`). Otherwise `INSUFFICIENT_SCOPE`.
+ *   2. The route declared `{ allowAnyScope: true }` → any valid key passes.
+ *      This is the explicit, self-documenting opt-out for routes that are
+ *      genuinely scope-agnostic (a public route that only *enriches* its
+ *      answer for authenticated callers, an MCP transport whose tools enforce
+ *      scopes themselves, ...).
+ *   3. The route declared nothing → the key is rejected with
+ *      `SCOPE_NOT_DECLARED` and the route is named in the server log.
+ *
+ * Rule 3 is the point of the change: forgetting a declaration now produces a
+ * visible 403 on an integration instead of a silently over-privileged
+ * credential. Before, `scopes` were populated and nobody was obliged to look.
+ */
+export type DualAuthFailureCode = 'AUTHENTICATION_FAILED' | 'INSUFFICIENT_SCOPE' | 'SCOPE_NOT_DECLARED';
+export interface DualAuthFailure {
+    code: DualAuthFailureCode;
+    /** 401 when no usable credential was presented, 403 when a valid key was rejected on scope. */
+    status: 401 | 403;
+    message: string;
+}
+export interface AuthenticateOptions {
+    /**
+     * Scope(s) an API key must hold to use this route. A string requires that
+     * scope; an array is satisfied by any one of its entries. Ignored for
+     * session auth. An empty array counts as "nothing declared".
+     */
+    requiredScope?: string | string[];
+    /**
+     * Accept any valid API key regardless of its scopes. Explicit opt-out of
+     * fail-closed enforcement — say why in a comment at the call site.
+     * A declared `requiredScope` still wins if both are set.
+     */
+    allowAnyScope?: boolean;
+}
+/** Failure attached to a result that carried no usable credential at all. */
+export declare function authenticationFailed(): DualAuthFailure;
+export declare function normalizeRequiredScopes(requiredScope: AuthenticateOptions['requiredScope']): string[];
+/**
+ * True when `scopes` (an API key's stored scopes) satisfy `requiredScope`:
+ * holds one of the required scopes, or the wildcard `*`. An empty requirement
+ * is never satisfied — "no scope needed" must be said with `allowAnyScope`,
+ * not with an empty list.
+ */
+export declare function scopesSatisfy(scopes: readonly string[] | undefined, requiredScope: string | string[]): boolean;
+/** Minimal request shape needed to name a route in logs (works for mocks too). */
+export interface RouteDescribable {
+    method?: string;
+    url?: string;
+    nextUrl?: {
+        pathname: string;
+    };
+}
+export declare function describeRoute(request: RouteDescribable): string;
+/**
+ * Apply the policy to an already-authenticated API key.
+ *
+ * @returns null when the key may proceed, otherwise the failure to report.
+ */
+export declare function resolveApiKeyScopeFailure(scopes: readonly string[] | undefined, options: AuthenticateOptions, route: string): DualAuthFailure | null;
+//# sourceMappingURL=scope-policy.d.ts.map

package/dist/lib/api/auth/scope-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-policy.d.ts","sourceRoot":"","sources":["../../../../src/lib/api/auth/scope-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,MAAM,mBAAmB,GAC3B,uBAAuB,GACvB,oBAAoB,GACpB,oBAAoB,CAAA;AAExB,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,mBAAmB,CAAA;IACzB,+FAA+F;IAC/F,MAAM,EAAE,GAAG,GAAG,GAAG,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IACjC;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED,6EAA6E;AAC7E,wBAAgB,oBAAoB,IAAI,eAAe,CAEtD;AAED,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,mBAAmB,CAAC,eAAe,CAAC,GAAG,MAAM,EAAE,CAKrG;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EACrC,aAAa,EAAE,MAAM,GAAG,MAAM,EAAE,GAC/B,OAAO,CAIT;AAED,kFAAkF;AAClF,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;CAC/B;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAU/D;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EACrC,OAAO,EAAE,mBAAmB,EAC5B,KAAK,EAAE,MAAM,GACZ,eAAe,GAAG,IAAI,CAuBxB"}

package/dist/lib/api/auth/scope-policy.js

@@ -0,0 +1,53 @@
+function authenticationFailed() {
+  return { code: "AUTHENTICATION_FAILED", status: 401, message: "Authentication required" };
+}
+function normalizeRequiredScopes(requiredScope) {
+  if (requiredScope === void 0) return [];
+  return (Array.isArray(requiredScope) ? requiredScope : [requiredScope]).filter(
+    (scope) => typeof scope === "string" && scope.length > 0
+  );
+}
+function scopesSatisfy(scopes, requiredScope) {
+  const required = normalizeRequiredScopes(requiredScope);
+  if (required.length === 0 || !scopes) return false;
+  return scopes.includes("*") || required.some((scope) => scopes.includes(scope));
+}
+function describeRoute(request) {
+  var _a;
+  let pathname = (_a = request.nextUrl) == null ? void 0 : _a.pathname;
+  if (!pathname && request.url) {
+    try {
+      pathname = new URL(request.url).pathname;
+    } catch {
+      pathname = request.url;
+    }
+  }
+  return `${request.method ?? "GET"} ${pathname ?? "<unknown route>"}`;
+}
+function resolveApiKeyScopeFailure(scopes, options, route) {
+  const required = normalizeRequiredScopes(options.requiredScope);
+  if (required.length > 0) {
+    if (scopesSatisfy(scopes, required)) return null;
+    return {
+      code: "INSUFFICIENT_SCOPE",
+      status: 403,
+      message: `API key lacks required scope '${required.join("' or '")}'`
+    };
+  }
+  if (options.allowAnyScope) return null;
+  console.error(
+    `[auth] ${route} did not declare a required API key scope; rejecting the API-key request (fail closed). Pass { requiredScope } \u2014 or { allowAnyScope: true } if any valid key is really acceptable \u2014 to the auth entry point.`
+  );
+  return {
+    code: "SCOPE_NOT_DECLARED",
+    status: 403,
+    message: "API key access is not enabled for this route: it declares no required scope"
+  };
+}
+export {
+  authenticationFailed,
+  describeRoute,
+  normalizeRequiredScopes,
+  resolveApiKeyScopeFailure,
+  scopesSatisfy
+};

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

@@ -25,6 +25,21 @@ export interface ApiKeyValidationResult {
  * Valida una API Key desde el header Authorization o x-api-key
  */
 export declare function validateApiKey(request: NextRequest): Promise<ApiKeyAuth | null>;
+/**
+ * Elimina del cache la entrada de una API key (indexada por keyHash).
+ *
+ * Debe llamarse cada vez que cambia el `status` de una key (revocación,
+ * desactivación, expiración): validateApiKey() consulta el cache ANTES que la
+ * base de datos, así que sin esta invalidación una key revocada sigue
+ * autenticando hasta que vence el TTL (5 min). Ver #92.
+ */
+export declare function invalidateApiKeyCache(keyHash: string): void;
+/**
+ * Variante por id para los call sites que no tienen el hash a mano.
+ * Hace una lectura extra; preferí invalidateApiKeyCache(keyHash) cuando el
+ * hash ya viene en la fila (por ejemplo vía RETURNING "keyHash").
+ */
+export declare function invalidateApiKeyCacheById(keyId: string): Promise<void>;
 /**
  * Verifica si una autenticación tiene alguno de los scopes requeridos
  */
@@ -44,13 +59,30 @@ export declare function getApiKeyUser(auth: ApiKeyAuth): Promise<{
     role: string;
 }>;
 /**
- * Verifica si un usuario puede crear API keys
+ * Verifica si un usuario puede crear API keys.
+ *
+ * Superadmin is a GLOBAL role (`users.role`) and is always allowed. Any
+ * other user is allowed only if they hold a team role that itself grants
+ * `admin:api-keys`/`admin:users`-equivalent scopes for at least one team —
+ * i.e. the same source of truth `validateScopesForUser` uses, checked
+ * without a specific team in mind (any qualifying membership is enough).
  */
 export declare function canCreateApiKeys(userId: string): Promise<boolean>;
 /**
- * Valida que los scopes solicitados sean permitidos para el usuario
+ * Valida que los scopes solicitados sean permitidos para el usuario, en el
+ * contexto de un team específico.
+ *
+ * Superadmin is a GLOBAL role (`users.role`) — it never appears in
+ * `AVAILABLE_ROLES` (team roles), so it's special-cased here rather than
+ * inside the scope registry. Every other user is resolved through their
+ * TEAM role for `teamId` (not their global `users.role` — NextSpark's
+ * entity authorization model is team-scoped, see `app.config.ts`), and the
+ * allowed-scope set comes from the same registry-backed
+ * `ScopeService.getRoleScopes()` that session auth's implicit scopes
+ * (`generateScopesForRole` in `helpers.ts`) and `checkPermission()` both
+ * ultimately derive from — so minting and enforcement can't diverge again.
  */
-export declare function validateScopesForUser(userId: string, requestedScopes: string[]): Promise<{
+export declare function validateScopesForUser(userId: string, teamId: string | null, requestedScopes: string[]): Promise<{
     valid: boolean;
     allowedScopes: string[];
     deniedScopes: string[];

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

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/lib/api/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAK1C;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAEnF;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAoHrF;AAiDD;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,OAAO,CAM/E;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,OAAO,CAMhF;AAiBD;;GAEG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,UAAU;QAG1C,MAAM;WACH,MAAM;eACF,MAAM,GAAG,IAAI;cACd,MAAM,GAAG,IAAI;UACjB,MAAM;GAWjB;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAiBvE;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAC9F,KAAK,EAAE,OAAO,CAAC;IACf,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB,CAAC,CAuDD"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/lib/api/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAO1C;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAEnF;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAoHrF;AA8CD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE3D;AAED;;;;GAIG;AACH,wBAAsB,yBAAyB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ5E;AAID;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,OAAO,CAM/E;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,OAAO,CAMhF;AAiBD;;GAEG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,UAAU;QAG1C,MAAM;WACH,MAAM;eACF,MAAM,GAAG,IAAI;cACd,MAAM,GAAG,IAAI;UACjB,MAAM;GAWjB;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAwBvE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,eAAe,EAAE,MAAM,EAAE,GACxB,OAAO,CAAC;IACT,KAAK,EAAE,OAAO,CAAC;IACf,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB,CAAC,CAyED"}

package/dist/lib/api/auth.js

@@ -1,6 +1,8 @@
 import { queryOne } from "../db.js";
 import { ApiKeyManager } from "./keys.js";
 import { apiKeyCache, getCacheKey } from "./cache.js";
+import { TeamMemberService } from "../services/team-member.service.js";
+import { ScopeService } from "../services/scope.service.js";
 function hasScope(auth, requiredScope) {
   return auth.scopes.includes(requiredScope);
 }
@@ -60,7 +62,7 @@ async function validateApiKey(request) {
       return null;
     }
     if (keyData.expiresAt && new Date(keyData.expiresAt) < /* @__PURE__ */ new Date()) {
-      markAsExpired(keyData.id).catch(console.error);
+      markAsExpired(keyData.id, keyHash).catch(console.error);
       await constantTimeDelay(startTime);
       return null;
     }
@@ -99,18 +101,29 @@ async function resetFailedAttempts(keyId) {
     console.error("Failed to reset failed attempts:", error);
   }
 }
-async function markAsExpired(keyId) {
+async function markAsExpired(keyId, keyHash) {
   try {
     await queryOne(
       'UPDATE "api_key" SET status = $1 WHERE id = $2',
       ["expired", keyId]
     );
-    const cacheKey = getCacheKey("api_key", keyId);
-    apiKeyCache.delete(cacheKey);
+    invalidateApiKeyCache(keyHash);
   } catch (error) {
     console.error("Failed to mark API key as expired:", error);
   }
 }
+function invalidateApiKeyCache(keyHash) {
+  apiKeyCache.delete(getCacheKey("api_key", keyHash));
+}
+async function invalidateApiKeyCacheById(keyId) {
+  const row = await queryOne(
+    'SELECT "keyHash" FROM "api_key" WHERE id = $1',
+    [keyId]
+  );
+  if (row == null ? void 0 : row.keyHash) {
+    invalidateApiKeyCache(row.keyHash);
+  }
+}
 function hasAnyScope(auth, requiredScopes) {
   if (auth.scopes.includes("*")) {
     return true;
@@ -154,13 +167,20 @@ async function canCreateApiKeys(userId) {
     if (!user) {
       return false;
     }
-    return ["admin", "superadmin"].includes(user.role);
+    if (user.role === "superadmin") {
+      return true;
+    }
+    const memberships = await TeamMemberService.listByUser(userId);
+    return memberships.some(({ role }) => {
+      const scopes = ScopeService.getRoleScopes(role);
+      return scopes.includes("*") || scopes.includes("admin:api-keys");
+    });
   } catch (error) {
     console.error("Error checking API key creation permissions:", error);
     return false;
   }
 }
-async function validateScopesForUser(userId, requestedScopes) {
+async function validateScopesForUser(userId, teamId, requestedScopes) {
   try {
     const user = await queryOne(
       'SELECT role FROM "users" WHERE id = $1',
@@ -173,23 +193,32 @@ async function validateScopesForUser(userId, requestedScopes) {
         deniedScopes: requestedScopes
       };
     }
-    const scopesByRole = {
-      member: ["tasks:read", "tasks:write"],
-      colaborator: ["tasks:read", "tasks:write", "tasks:delete", "users:read"],
-      admin: [
-        "users:read",
-        "users:write",
-        "users:delete",
-        "tasks:read",
-        "tasks:write",
-        "tasks:delete",
-        "admin:api-keys",
-        "admin:users"
-      ],
-      superadmin: ["*"]
-      // Acceso completo
-    };
-    const allowedScopes = scopesByRole[user.role] || [];
+    if (user.role === "superadmin") {
+      return {
+        valid: true,
+        allowedScopes: requestedScopes,
+        deniedScopes: []
+      };
+    }
+    if (!teamId) {
+      return {
+        valid: false,
+        allowedScopes: [],
+        deniedScopes: requestedScopes
+      };
+    }
+    const teamRole = await TeamMemberService.getRole(teamId, userId);
+    if (!teamRole) {
+      return {
+        valid: false,
+        allowedScopes: [],
+        deniedScopes: requestedScopes
+      };
+    }
+    const allowedScopes = [
+      ...ScopeService.getBaseScopes(),
+      ...ScopeService.getRoleScopes(teamRole)
+    ];
     if (allowedScopes.includes("*")) {
       return {
         valid: true,
@@ -219,6 +248,8 @@ export {
   hasAllScopes,
   hasAnyScope,
   hasScope,
+  invalidateApiKeyCache,
+  invalidateApiKeyCacheById,
   validateApiKey,
   validateScopesForUser
 };

package/dist/lib/api/entity/audit-log.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Audit logging for the generic entity routes (#105).
+ *
+ * `logApiUsage` (lib/api/helpers.ts) is hard-typed to `ApiKeyAuth` and is
+ * only triggered by the legacy `withApiLogging` wrapper, whose header-based
+ * `getApiAuth` never sees the dual-auth flow the generic handlers use — so
+ * neither session nor API-key activity on `/api/v1/[entity]` was ever
+ * written to `api_audit_log`.
+ *
+ * This module accepts the real `DualAuthResult` the handlers already hold and
+ * writes one row per REQUEST WITH AN IDENTIFIABLE PRINCIPAL (`apiKeyId` is
+ * NULL for sessions; migration 025 dropped the NOT NULL) — a real session or
+ * a real API key, whether the request was ultimately allowed or denied for
+ * scope/permission reasons (#128). A request with no usable credential at all
+ * (anonymous, missing, or invalid) is still never logged: there is no "who"
+ * to attribute it to, and logging it would mostly capture bot/scanner noise
+ * rather than anything actionable. It is invoked fire-and-forget from
+ * `runWithAuditLog` in generic-handler.ts, so a logging failure can never turn
+ * a successful response into an error.
+ *
+ * The request body is deliberately NOT stored: entity payloads routinely
+ * carry personal data, and endpoint + method + status already identify what
+ * was touched (the record id is part of the path for read/update/delete).
+ */
+import type { NextRequest } from 'next/server';
+import type { DualAuthResult } from '../auth/dual-auth';
+/**
+ * Mutable slot a handler fills in once it has authenticated the request, so
+ * the wrapper can attribute the response to a user / API key.
+ */
+export interface AuditContext {
+    auth: DualAuthResult | null;
+}
+export declare function logGenericHandlerUsage(auth: DualAuthResult | null, request: NextRequest, statusCode: number, responseTime?: number): Promise<void>;
+//# sourceMappingURL=audit-log.d.ts.map

package/dist/lib/api/entity/audit-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-log.d.ts","sourceRoot":"","sources":["../../../../src/lib/api/entity/audit-log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAE9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAEvD;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,cAAc,GAAG,IAAI,CAAA;CAC5B;AAED,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,cAAc,GAAG,IAAI,EAC3B,OAAO,EAAE,WAAW,EACpB,UAAU,EAAE,MAAM,EAClB,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC,CAuCf"}

package/dist/lib/api/entity/audit-log.js

@@ -0,0 +1,35 @@
+import { mutateWithRLS } from "../../db.js";
+async function logGenericHandlerUsage(auth, request, statusCode, responseTime) {
+  var _a;
+  const userId = (_a = auth == null ? void 0 : auth.user) == null ? void 0 : _a.id;
+  if (!userId) return;
+  const apiKeyId = (auth == null ? void 0 : auth.type) === "api-key" ? auth.keyId ?? null : null;
+  try {
+    const endpoint = request.nextUrl.pathname;
+    const method = request.method;
+    const ipAddress = request.headers.get("x-forwarded-for") || request.headers.get("x-real-ip") || "unknown";
+    const userAgent = request.headers.get("user-agent");
+    await mutateWithRLS(
+      `INSERT INTO "api_audit_log"
+       ("apiKeyId", "userId", endpoint, method, "statusCode", "ipAddress", "userAgent", "requestBody", "responseTime")
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)`,
+      [
+        apiKeyId,
+        userId,
+        endpoint,
+        method,
+        statusCode,
+        ipAddress,
+        userAgent,
+        null,
+        typeof responseTime === "number" ? Math.round(responseTime) : null
+      ],
+      userId
+    );
+  } catch (error) {
+    console.error("[generic-handler:audit] failed to write api_audit_log entry:", error);
+  }
+}
+export {
+  logGenericHandlerUsage
+};

package/dist/lib/api/entity/generic-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generic-handler.d.ts","sourceRoot":"","sources":["../../../../src/lib/api/entity/generic-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AA8iBvD;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAugBnF;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAmZrF;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,MAAM,EAAE,EAAE;IAAE,MAAM,EAAE,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CA0MpJ;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,MAAM,EAAE,EAAE;IAAE,MAAM,EAAE,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAyXtJ;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,MAAM,EAAE,EAAE;IAAE,MAAM,EAAE,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAoJtJ;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAEtF"}
+{"version":3,"file":"generic-handler.d.ts","sourceRoot":"","sources":["../../../../src/lib/api/entity/generic-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AA4wBvD;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAEnF;AA4kBD;;GAEG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAErF;AAyaD;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,MAAM,EAAE,EAAE;IAAE,MAAM,EAAE,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAEpJ;AAgND;;GAEG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,MAAM,EAAE,EAAE;IAAE,MAAM,EAAE,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAEtJ;AA+YD;;GAEG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,MAAM,EAAE,EAAE;IAAE,MAAM,EAAE,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAEtJ;AAwKD;;GAEG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAEtF"}