Nexus.Reader/.agents/skills/nexus-identity-saas.md

name, description

name	description
nexus-identity-saas	Standards for Identity, Authentication, and SaaS feature implementations

Identity & SaaS Integration

• Core Identity Model:

  • Extend IdentityUser to create a custom NexusUser model containing SaaS-specific properties (e.g., AITokenLimit, AITokensUsed, TenantId, CurrentPlan).
  • Place core domain models in the core project layer (e.g., NexusArchitect.Core or NexusReader.Domain).
  • Configure ApplicationDbContext to inherit from IdentityDbContext<NexusUser> and map custom fields and relationships correctly.

• Authentication Endpoints & Providers:

  • Use native ASP.NET Core Identity API endpoints (/register, /login, /refresh) or scaffolded Razor components in Blazor (Components/Account/Pages).
  • Integrate OAuth2 providers (like Google, Facebook, Microsoft) natively via ASP.NET Core's external login providers.
  • Utilize SignInManager<TUser> and UserManager<TUser> for custom login logic and user management.

• Service Configuration & Policies:

  • Register Identity using builder.Services.AddDefaultIdentity<NexusUser>() or AddIdentity<NexusUser, IdentityRole>() followed by .AddEntityFrameworkStores<ApplicationDbContext>().
  • Configure IdentityOptions in Program.cs to enforce strict security standards:
    • Password: RequireDigit, RequireLowercase, RequireUppercase, RequireNonAlphanumeric, RequiredLength (min 8).
    • Lockout: Set MaxFailedAccessAttempts and DefaultLockoutTimeSpan to prevent brute-force attacks.
    • User: Enforce RequireUniqueEmail = true.

• Authorization & Policies:

  • Implement Roles and Claims-based authorization.
  • Create robust Policies (e.g., ProUser) and use custom Requirement handlers for specific business logic like checking if AITokensUsed < AITokenLimit.

• Mobile / Blazor Hybrid Auth State:

  • Ensure authentication state persists securely within the MAUI container.
  • Store JWT tokens and sensitive session data in SecureStorage.
  • Provide a seamless mechanism to restore the AuthenticationStateProvider on app launch if the token is valid.

• SaaS Features & Webhooks:

  • Integrate third-party payment/subscription providers (e.g., Stripe) using secure webhooks.
  • Sync external subscription status with internal user claims and limits (e.g., upgrade AITokenLimit upon a webhook success event for a "Pro" plan).

• Verification:

  • Write unit tests for custom authorization handlers and token limit logic.
  • Ensure the UI handles unauthorized and out-of-tokens states gracefully and points users to subscription management.