@meridianjs/auth 0.1.5 → 0.1.8

package/README.md

@@ -0,0 +1,131 @@
+# @meridianjs/auth
+
+Authentication module for MeridianJS. Provides JWT-based register/login flows, Google OAuth support, Express middleware for token verification, and RBAC guards.
+
+Auto-loaded by `@meridianjs/meridian` — you do not need to add this to `modules[]` yourself.
+
+## Service: `authModuleService`
+
+```typescript
+const svc = req.scope.resolve("authModuleService") as any
+```
+
+### Methods
+
+```typescript
+// Register a new user — returns { user, token }
+const { user, token } = await svc.register({
+  email: "alice@example.com",
+  password: "password123",
+  first_name: "Alice",
+  last_name: "Smith",
+  role: "member",       // optional: "super-admin" | "admin" | "moderator" | "member"
+})
+
+// Login — returns { user, token }
+const { user, token } = await svc.login({
+  email: "alice@example.com",
+  password: "password123",
+})
+
+// Verify and decode a JWT
+const payload = await svc.verifyToken(token)
+// payload: { sub, workspaceId, roles, permissions, jti }
+```
+
+## Middleware
+
+### `authenticateJWT`
+
+Verifies the `Authorization: Bearer <token>` header and attaches `req.user`. Returns `401` if the token is missing or invalid.
+
+```typescript
+import { authenticateJWT } from "@meridianjs/auth"
+
+// Applied globally in middlewares.ts:
+export default {
+  routes: [
+    { matcher: "/admin", middlewares: [authenticateJWT] },
+  ],
+}
+
+// Or inline in a route:
+export const GET = [authenticateJWT, async (req: any, res: Response) => {
+  res.json({ userId: req.user.id })
+}]
+```
+
+### `requireRoles`
+
+Guard a route or handler to specific roles. Returns `403` if the user's roles don't match.
+
+```typescript
+import { requireRoles } from "@meridianjs/auth"
+
+export const DELETE = [
+  authenticateJWT,
+  requireRoles("admin", "super-admin"),
+  async (req: any, res: Response) => {
+    // Only admins reach here
+  },
+]
+```
+
+### `requirePermission`
+
+Guard based on a specific permission string from a custom AppRole:
+
+```typescript
+import { requirePermission } from "@meridianjs/auth"
+
+export const POST = [
+  authenticateJWT,
+  requirePermission("issues:create"),
+  async (req: any, res: Response) => { /* ... */ },
+]
+```
+
+## JWT Payload
+
+```typescript
+interface JwtPayload {
+  sub: string           // User ID
+  workspaceId: string   // Active workspace ID (null until workspace selected)
+  roles: string[]       // e.g. ["admin"] or ["member"]
+  permissions: string[] // Custom AppRole permissions (e.g. ["issues:create", "issues:delete"])
+  jti: string           // Unique token ID (for revocation)
+  iat: number
+  exp: number
+}
+```
+
+Tokens expire after **7 days** by default. Configure in `projectConfig`:
+
+```typescript
+projectConfig: {
+  jwtSecret: process.env.JWT_SECRET!,
+  jwtExpiresIn: "30d",  // optional
+}
+```
+
+## Google OAuth
+
+When `@meridianjs/google-oauth` is configured, the auth module exposes:
+
+```
+GET /auth/google           → Redirects to Google consent screen
+GET /auth/google/callback  → Handles OAuth code, returns JWT
+```
+
+## API Routes
+
+| Method | Path | Description |
+|---|---|---|
+| `POST` | `/auth/register` | Register, return `{ user, token }` |
+| `POST` | `/auth/login` | Login, return `{ user, token }` |
+| `GET` | `/auth/invite/:token` | Validate an invitation token |
+| `POST` | `/auth/invite/:token` | Accept invitation (register or login) |
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -32,6 +32,20 @@ interface JwtPayload {
     iat?: number;
     exp?: number;
 }
+interface GoogleAuthInput {
+    googleId: string;
+    email: string;
+    firstName: string | null;
+    lastName: string | null;
+    picture: string | null;
+    inviteRecord?: {
+        id: string;
+        email: string | null;
+        role: string;
+        workspace_id: string;
+        app_role_id: string | null;
+    } | null;
+}
 declare const AuthModuleService_base: new (container: MeridianContainer) => _meridianjs_types.IModuleService;
 declare class AuthModuleService extends AuthModuleService_base {
     private readonly container;
@@ -40,6 +54,13 @@ declare class AuthModuleService extends AuthModuleService_base {
     register(input: RegisterInput): Promise<AuthResult>;
     /** Authenticate with email + password and return a signed JWT. */
     login(input: LoginInput): Promise<AuthResult>;
+    /**
+     * Sign in or register a user via Google OAuth.
+     * 1. Look up by google_id — existing SSO user
+     * 2. Look up by email — link google_id to existing account
+     * 3. Create new user
+     */
+    loginOrRegisterWithGoogle(input: GoogleAuthInput): Promise<AuthResult>;
     /** Verify a JWT and return its decoded payload. Throws if invalid or expired. */
     verifyToken(token: string, secret: string): JwtPayload;
     /** Resolve permissions for a given app_role_id — gracefully degrades if module not loaded. */
@@ -93,4 +114,4 @@ declare function requireWorkspace(req: any, res: Response, next: NextFunction):
 declare const AUTH_MODULE = "authModuleService";
 declare const _default: _meridianjs_types.ModuleDefinition;
 
-export { AUTH_MODULE, AuthModuleService, type AuthResult, type JwtPayload, type LoginInput, type RegisterInput, authenticateJWT, _default as default, requirePermission, requireRoles, requireWorkspace };
+export { AUTH_MODULE, AuthModuleService, type AuthResult, type GoogleAuthInput, type JwtPayload, type LoginInput, type RegisterInput, authenticateJWT, _default as default, requirePermission, requireRoles, requireWorkspace };

package/dist/index.d.ts

@@ -32,6 +32,20 @@ interface JwtPayload {
     iat?: number;
     exp?: number;
 }
+interface GoogleAuthInput {
+    googleId: string;
+    email: string;
+    firstName: string | null;
+    lastName: string | null;
+    picture: string | null;
+    inviteRecord?: {
+        id: string;
+        email: string | null;
+        role: string;
+        workspace_id: string;
+        app_role_id: string | null;
+    } | null;
+}
 declare const AuthModuleService_base: new (container: MeridianContainer) => _meridianjs_types.IModuleService;
 declare class AuthModuleService extends AuthModuleService_base {
     private readonly container;
@@ -40,6 +54,13 @@ declare class AuthModuleService extends AuthModuleService_base {
     register(input: RegisterInput): Promise<AuthResult>;
     /** Authenticate with email + password and return a signed JWT. */
     login(input: LoginInput): Promise<AuthResult>;
+    /**
+     * Sign in or register a user via Google OAuth.
+     * 1. Look up by google_id — existing SSO user
+     * 2. Look up by email — link google_id to existing account
+     * 3. Create new user
+     */
+    loginOrRegisterWithGoogle(input: GoogleAuthInput): Promise<AuthResult>;
     /** Verify a JWT and return its decoded payload. Throws if invalid or expired. */
     verifyToken(token: string, secret: string): JwtPayload;
     /** Resolve permissions for a given app_role_id — gracefully degrades if module not loaded. */
@@ -93,4 +114,4 @@ declare function requireWorkspace(req: any, res: Response, next: NextFunction):
 declare const AUTH_MODULE = "authModuleService";
 declare const _default: _meridianjs_types.ModuleDefinition;
 
-export { AUTH_MODULE, AuthModuleService, type AuthResult, type JwtPayload, type LoginInput, type RegisterInput, authenticateJWT, _default as default, requirePermission, requireRoles, requireWorkspace };
+export { AUTH_MODULE, AuthModuleService, type AuthResult, type GoogleAuthInput, type JwtPayload, type LoginInput, type RegisterInput, authenticateJWT, _default as default, requirePermission, requireRoles, requireWorkspace };

package/dist/index.js

@@ -122,6 +122,85 @@ var AuthModuleService = class extends (0, import_framework_utils.MeridianService
       token
     };
   }
+  /**
+   * Sign in or register a user via Google OAuth.
+   * 1. Look up by google_id — existing SSO user
+   * 2. Look up by email — link google_id to existing account
+   * 3. Create new user
+   */
+  async loginOrRegisterWithGoogle(input) {
+    const userService = this.container.resolve("userModuleService");
+    const config = this.container.resolve("config");
+    let user = await userService.retrieveUserByGoogleId(input.googleId);
+    if (!user) {
+      const existingByEmail = await userService.retrieveUserByEmail(input.email.toLowerCase().trim());
+      if (existingByEmail) {
+        throw Object.assign(
+          new Error(
+            "An account with this email already exists. Please sign in with your password. You can link Google sign-in from your account settings afterwards."
+          ),
+          { status: 409 }
+        );
+      }
+    }
+    if (user) {
+      if (!user.is_active) {
+        throw Object.assign(new Error("Account deactivated"), { status: 403 });
+      }
+      await userService.recordLogin(user.id).catch(() => {
+      });
+      const permissions2 = await this.resolvePermissions(user.app_role_id);
+      const { token: token2, jti: jti2, expiresAt: expiresAt2 } = this.signToken(user.id, null, [user.role ?? "member"], permissions2, config.projectConfig.jwtSecret);
+      await userService.createSession(jti2, user.id, expiresAt2).catch(() => {
+      });
+      return {
+        user: { id: user.id, email: user.email, first_name: user.first_name ?? null, last_name: user.last_name ?? null },
+        token: token2
+      };
+    }
+    const invite = input.inviteRecord;
+    let role = "member";
+    if (invite) {
+      role = invite.role ?? "member";
+    } else {
+      const [, userCount] = await userService.listAndCountUsers({}, { limit: 1 });
+      if (userCount === 0) {
+        role = "super-admin";
+      } else {
+        throw Object.assign(
+          new Error("You are not authorized to access this application. Contact an admin for an invitation."),
+          { status: 403 }
+        );
+      }
+    }
+    const password_hash = await import_bcrypt.default.hash((0, import_crypto.randomUUID)(), 1);
+    const newUser = await userService.createUser({
+      email: input.email.toLowerCase().trim(),
+      password_hash,
+      first_name: input.firstName ?? null,
+      last_name: input.lastName ?? null,
+      role,
+      is_active: true,
+      google_id: input.googleId,
+      ...invite?.app_role_id ? { app_role_id: invite.app_role_id } : {}
+    });
+    if (invite) {
+      try {
+        const workspaceMemberService = this.container.resolve("workspaceMemberModuleService");
+        const wsRole = invite.role === "member" ? "member" : "admin";
+        await workspaceMemberService.ensureMember(invite.workspace_id, newUser.id, wsRole);
+      } catch {
+      }
+    }
+    const permissions = await this.resolvePermissions(newUser.app_role_id);
+    const { token, jti, expiresAt } = this.signToken(newUser.id, null, [newUser.role], permissions, config.projectConfig.jwtSecret);
+    await userService.createSession(jti, newUser.id, expiresAt).catch(() => {
+    });
+    return {
+      user: { id: newUser.id, email: newUser.email, first_name: newUser.first_name ?? null, last_name: newUser.last_name ?? null },
+      token
+    };
+  }
   /** Verify a JWT and return its decoded payload. Throws if invalid or expired. */
   verifyToken(token, secret) {
     return import_jsonwebtoken.default.verify(token, secret, { algorithms: ["HS256"] });

package/dist/index.mjs

@@ -82,6 +82,85 @@ var AuthModuleService = class extends MeridianService({}) {
       token
     };
   }
+  /**
+   * Sign in or register a user via Google OAuth.
+   * 1. Look up by google_id — existing SSO user
+   * 2. Look up by email — link google_id to existing account
+   * 3. Create new user
+   */
+  async loginOrRegisterWithGoogle(input) {
+    const userService = this.container.resolve("userModuleService");
+    const config = this.container.resolve("config");
+    let user = await userService.retrieveUserByGoogleId(input.googleId);
+    if (!user) {
+      const existingByEmail = await userService.retrieveUserByEmail(input.email.toLowerCase().trim());
+      if (existingByEmail) {
+        throw Object.assign(
+          new Error(
+            "An account with this email already exists. Please sign in with your password. You can link Google sign-in from your account settings afterwards."
+          ),
+          { status: 409 }
+        );
+      }
+    }
+    if (user) {
+      if (!user.is_active) {
+        throw Object.assign(new Error("Account deactivated"), { status: 403 });
+      }
+      await userService.recordLogin(user.id).catch(() => {
+      });
+      const permissions2 = await this.resolvePermissions(user.app_role_id);
+      const { token: token2, jti: jti2, expiresAt: expiresAt2 } = this.signToken(user.id, null, [user.role ?? "member"], permissions2, config.projectConfig.jwtSecret);
+      await userService.createSession(jti2, user.id, expiresAt2).catch(() => {
+      });
+      return {
+        user: { id: user.id, email: user.email, first_name: user.first_name ?? null, last_name: user.last_name ?? null },
+        token: token2
+      };
+    }
+    const invite = input.inviteRecord;
+    let role = "member";
+    if (invite) {
+      role = invite.role ?? "member";
+    } else {
+      const [, userCount] = await userService.listAndCountUsers({}, { limit: 1 });
+      if (userCount === 0) {
+        role = "super-admin";
+      } else {
+        throw Object.assign(
+          new Error("You are not authorized to access this application. Contact an admin for an invitation."),
+          { status: 403 }
+        );
+      }
+    }
+    const password_hash = await bcrypt.hash(randomUUID(), 1);
+    const newUser = await userService.createUser({
+      email: input.email.toLowerCase().trim(),
+      password_hash,
+      first_name: input.firstName ?? null,
+      last_name: input.lastName ?? null,
+      role,
+      is_active: true,
+      google_id: input.googleId,
+      ...invite?.app_role_id ? { app_role_id: invite.app_role_id } : {}
+    });
+    if (invite) {
+      try {
+        const workspaceMemberService = this.container.resolve("workspaceMemberModuleService");
+        const wsRole = invite.role === "member" ? "member" : "admin";
+        await workspaceMemberService.ensureMember(invite.workspace_id, newUser.id, wsRole);
+      } catch {
+      }
+    }
+    const permissions = await this.resolvePermissions(newUser.app_role_id);
+    const { token, jti, expiresAt } = this.signToken(newUser.id, null, [newUser.role], permissions, config.projectConfig.jwtSecret);
+    await userService.createSession(jti, newUser.id, expiresAt).catch(() => {
+    });
+    return {
+      user: { id: newUser.id, email: newUser.email, first_name: newUser.first_name ?? null, last_name: newUser.last_name ?? null },
+      token
+    };
+  }
   /** Verify a JWT and return its decoded payload. Throws if invalid or expired. */
   verifyToken(token, secret) {
     return jwt.verify(token, secret, { algorithms: ["HS256"] });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meridianjs/auth",
-  "version": "0.1.5",
+  "version": "0.1.8",
   "description": "Meridian auth module — JWT authentication and middleware",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",