@mostajs/auth 2.1.2 → 2.3.0

package/README.md

@@ -62,3 +62,66 @@ await createAdmin({ email: 'admin@test.com', password: 'Admin123!', firstName: '
 import { usePermissions } from '@mostajs/auth'
 import { PermissionGuard, SessionProvider } from '@mostajs/auth'
 ```
+
+## Environment
+
+```bash
+AUTH_SECRET=your-32-bytes-secret           # required — openssl rand -hex 32
+# or alias for NextAuth compat:
+NEXTAUTH_SECRET=your-32-bytes-secret
+```
+
+### Profile cascade with `MOSTA_ENV` (v2.2+)
+
+Powered by [`@mostajs/config`](https://www.npmjs.com/package/@mostajs/config).
+Keep one `.env` with profile-prefixed overrides à la
+[Spring Boot profiles](https://docs.spring.io/spring-boot/reference/features/profiles.html)
+(`spring.profiles.active=test`) :
+
+```bash
+MOSTA_ENV=TEST
+AUTH_SECRET=dev-secret-fallback
+TEST_AUTH_SECRET=test-specific-secret
+PROD_AUTH_SECRET=${VAULT_AUTH_SECRET}      # injected by orchestrator
+```
+
+**Resolution cascade** (first non-empty value wins) :
+
+1. `${MOSTA_ENV}_AUTH_SECRET` — profile-prefixed override
+2. `AUTH_SECRET` — plain default
+3. `NEXTAUTH_SECRET` — NextAuth-compat alias
+4. `undefined` — NextAuth raises its own configuration error
+
+Missing profile overrides silently fall back to the plain variable — no
+crash if the profiled key is absent. Empty strings (`TEST_AUTH_SECRET=`)
+are treated as "not set" so they don't silently leak a blank value to
+the signer.
+
+### Why this matters for auth
+
+Routing secret resolution through `@mostajs/config` lets you keep **one**
+`.env` file in your repo with non-secret profile defaults (dev/test keys)
+and have the orchestrator (Vault, Scaleway Secrets, Kubernetes Secrets,
+Docker env) inject the real `PROD_AUTH_SECRET` at runtime. No more
+juggling `.env.test` / `.env.development` / `.env.production` and
+forgetting to sync them. Users who already defined `AUTH_SECRET` or
+`NEXTAUTH_SECRET` keep working unchanged — the cascade is fully
+backward-compatible.
+
+## Changelog
+
+### v2.2.0 — 2026-04-21
+
+**Added** : `AUTH_SECRET` / `NEXTAUTH_SECRET` resolution routed through
+[`@mostajs/config`](https://www.npmjs.com/package/@mostajs/config). Users
+who set `MOSTA_ENV=TEST` now get `TEST_AUTH_SECRET` preferred over plain
+`AUTH_SECRET`, with silent fallback to the plain variable when the
+profiled override is absent. Matches Spring Boot profile semantics
+(`spring.profiles.active=test`).
+
+- `lib/auth.ts` : secret resolution via `getEnv()` instead of
+  `process.env.X`
+- `package.json` : add `@mostajs/config ^1.0.0` dependency, bump to
+  `2.2.0`
+- `README` : document the Environment section + profile cascade +
+  changelog

package/dist/lib/auth.js

@@ -3,6 +3,7 @@
 // Phase 3: schemas/repos imported from @mostajs/rbac
 import NextAuth from 'next-auth';
 import CredentialsProvider from 'next-auth/providers/credentials';
+import { getEnv } from '@mostajs/config';
 import { getRbacRepos } from '@mostajs/rbac/lib/repos-factory';
 import { comparePassword } from './password';
 /**
@@ -13,7 +14,7 @@ import { comparePassword } from './password';
  */
 export function createAuthHandlers(rolePermissions, config) {
     const { handlers, auth, signIn, signOut } = NextAuth({
-        secret: process.env.AUTH_SECRET || process.env.NEXTAUTH_SECRET,
+        secret: getEnv('AUTH_SECRET') || getEnv('NEXTAUTH_SECRET'),
         trustHost: true,
         debug: false,
         useSecureCookies: false,

package/dist/lib/check-request.d.ts

@@ -0,0 +1,54 @@
+import type { IDialect } from '@mostajs/orm';
+export type AuthErrorCode = 'UNAUTHORIZED' | 'FORBIDDEN' | 'UNAVAILABLE' | 'AUTH_ERROR';
+export interface CheckRequestParams {
+    /** Dialect of the metadata DB (where api_keys / users / roles tables live). */
+    dialect: IDialect | null | undefined;
+    /** Normalized HTTP-style headers (lowercased keys preferred). */
+    headers?: Record<string, string | string[] | undefined>;
+    /** Query string params. */
+    query?: Record<string, string | string[] | undefined>;
+    /** Pre-resolved client IP (else derived from X-Forwarded-For). */
+    ip?: string;
+    /** Transport identifier — 'rest' | 'graphql' | 'mcp' | 'sse' | etc. */
+    transport: string;
+    /**
+     * (scope, value) checks the apikey must satisfy. The module is fully
+     * generic — it doesn't know what 'projects' or 'transports' mean.
+     * Common pattern :
+     *   [{scope:'projects',value:slug}, {scope:'transports',value:'rest'},
+     *    {scope:'operations',value:'read'|'write'|'admin'}]
+     */
+    checks?: Array<{
+        scope: string;
+        value: string;
+    }>;
+    /** Allow request through without apikey (legacy / public-mode). */
+    openMode?: boolean;
+}
+export interface CheckRequestResult {
+    ok: boolean;
+    /** HTTP status code suggested for the failure response (200 if ok). */
+    status: number;
+    /** Suggested JSON body for the failure response. */
+    body?: any;
+    /** Authorization context built from the resolved apikey (if ok). */
+    ctx?: {
+        transport: string;
+        apiKey?: string;
+        projectName?: string;
+        accountId?: string;
+        apikeyId?: string;
+        subscription?: string;
+        permissions?: Record<string, any>;
+        meta?: Record<string, any>;
+    };
+    /** Resolved apikey row (read-only — sensitive fields like hash are present). */
+    apikey?: any;
+}
+/**
+ * Single-call request authorization.
+ *
+ * Returns a verdict that the consumer maps onto its framework's response
+ * (e.g. `if (!result.ok) reply.code(result.status).send(result.body)`).
+ */
+export declare function checkRequest(params: CheckRequestParams): Promise<CheckRequestResult>;

package/dist/lib/check-request.js

@@ -0,0 +1,112 @@
+// @mostajs/auth — Framework-agnostic request authorization check.
+//
+// Orchestrateur unique pour valider une requête HTTP entrante (toutes
+// frameworks : Fastify, Express, Hono, Next.js route handlers, Cloudflare
+// Workers, Bun.serve, etc.).
+//
+// Combine :
+//   - apikey check (délégué à @mostajs/api-keys → checkApiKey)
+//   - (futur) session check NextAuth
+//   - (futur) RBAC permission check via @mostajs/rbac
+//
+// Le consommateur passe un objet `request` normalisé (headers/query/ip) +
+// les `checks` de scopes — le module retourne un verdict unifié.
+//
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+function pickHeader(h, name) {
+    if (!h)
+        return undefined;
+    const v = h[name] ?? h[name.toLowerCase()];
+    if (v == null)
+        return undefined;
+    return Array.isArray(v) ? v[0] : String(v);
+}
+function pickQuery(q, name) {
+    if (!q)
+        return undefined;
+    const v = q[name];
+    if (v == null)
+        return undefined;
+    return Array.isArray(v) ? v[0] : String(v);
+}
+/**
+ * Single-call request authorization.
+ *
+ * Returns a verdict that the consumer maps onto its framework's response
+ * (e.g. `if (!result.ok) reply.code(result.status).send(result.body)`).
+ */
+export async function checkRequest(params) {
+    const { dialect, headers, query, ip, transport, checks = [], openMode = false } = params;
+    // Extract auth identifiers from the request
+    const apiKey = pickHeader(headers, 'x-api-key') ??
+        (pickHeader(headers, 'authorization')?.replace(/^Bearer\s+/i, '').trim() || undefined) ??
+        pickQuery(query, 'apikey') ??
+        pickQuery(query, 'api_key');
+    const projectName = pickHeader(headers, 'x-project') ??
+        pickQuery(query, 'project');
+    const resolvedIp = ip
+        ?? pickHeader(headers, 'x-forwarded-for')?.split(',')[0]?.trim()
+        ?? pickHeader(headers, 'x-real-ip');
+    const baseCtx = {
+        transport,
+        apiKey,
+        projectName,
+        meta: { ip: resolvedIp },
+    };
+    // No apikey → either openMode passes through, or 401
+    if (!apiKey) {
+        if (openMode)
+            return { ok: true, status: 200, ctx: baseCtx };
+        return {
+            ok: false, status: 401,
+            body: { status: 'error', error: { code: 'UNAUTHORIZED',
+                    message: 'API key required (X-API-Key header, Authorization: Bearer, or ?apikey=)' } },
+        };
+    }
+    // No metadata DB → can't verify
+    if (!dialect) {
+        if (openMode)
+            return { ok: true, status: 200, ctx: baseCtx };
+        return {
+            ok: false, status: 503,
+            body: { status: 'error', error: { code: 'UNAVAILABLE',
+                    message: 'API key validation unavailable (no metadata DB)' } },
+        };
+    }
+    // Delegate to @mostajs/api-keys for the actual cryptographic + scope check
+    try {
+        const { checkApiKey } = await import('@mostajs/api-keys/server');
+        const result = await checkApiKey(dialect, {
+            rawKey: apiKey,
+            checks,
+            ip: resolvedIp,
+        });
+        if (!result.ok) {
+            return {
+                ok: false,
+                status: result.code === 'UNAUTHORIZED' ? 401 : 403,
+                body: { status: 'error', error: { code: result.code, message: result.message } },
+            };
+        }
+        const apikey = result.apikey;
+        return {
+            ok: true,
+            status: 200,
+            apikey,
+            ctx: {
+                ...baseCtx,
+                subscription: apikey?.label || apikey?.id,
+                permissions: apikey?.permissions?.scopes ?? {},
+                accountId: apikey?.account || apikey?.accountId,
+                apikeyId: apikey?.id,
+            },
+        };
+    }
+    catch (e) {
+        return {
+            ok: false, status: 500,
+            body: { status: 'error', error: { code: 'AUTH_ERROR',
+                    message: e?.message || 'auth check failed' } },
+        };
+    }
+}

package/dist/server.d.ts

@@ -3,6 +3,8 @@ export { createAuthChecks } from './lib/auth-check';
 export { createAuthMiddleware } from './middleware/auth-middleware';
 export type { AuthMiddlewareOptions } from './middleware/auth-middleware';
 export { hashPassword, comparePassword } from './lib/password';
+export { checkRequest } from './lib/check-request';
+export type { CheckRequestParams, CheckRequestResult, AuthErrorCode } from './lib/check-request';
 export { getPermissionsForRoleFromDB } from '@mostajs/rbac/lib/permissions-server';
 export { seedRBAC } from '@mostajs/rbac/lib/rbac-seed';
 export type { SeedRBACOptions } from '@mostajs/rbac/lib/rbac-seed';

package/dist/server.js

@@ -7,6 +7,8 @@ export { createAuthChecks } from './lib/auth-check';
 export { createAuthMiddleware } from './middleware/auth-middleware';
 // Password utils
 export { hashPassword, comparePassword } from './lib/password';
+// Framework-agnostic request authorization (apikey + scope checks)
+export { checkRequest } from './lib/check-request';
 // Server-side permission DB lookup (re-export from rbac/server)
 export { getPermissionsForRoleFromDB } from '@mostajs/rbac/lib/permissions-server';
 // RBAC seed (re-export from rbac/server)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mostajs/auth",
-  "version": "2.1.2",
+  "version": "2.3.0",
   "description": "Authentication — NextAuth, password hashing, session management",
   "author": "Dr Hamid MADANI <drmdh@msn.com>",
   "license": "AGPL-3.0-or-later",
@@ -118,8 +118,8 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
+    "@mostajs/config": "^1.0.0",
     "@mostajs/net": "^2.0.0",
-    "@mostajs/orm": "^1.7.0",
     "bcryptjs": "^2.4.3"
   },
   "peerDependencies": {
@@ -129,6 +129,8 @@
     "react": ">=18"
   },
   "devDependencies": {
+    "@mostajs/api-keys": "^0.2.0",
+    "@mostajs/orm": "^1.13.1",
     "@mostajs/rbac": "^2.0.3",
     "@types/bcryptjs": "^2.4.0",
     "@types/node": "^25.3.3",