​

Authentication Architecture

​

1. Overview

​

High-level summary

• Identity for GraphQL is established with a short-lived opaque access credential (user_session, 15 minutes) validated on every request. A paired refresh credential (user_refresh, ~30 days) rotates the pair. Both rows share a session_family_id.
• Portal (browser) delivers access + refresh via httpOnly cookies auth_access / auth_refresh (apps/backend/src/utilities/authCookies.ts). Apollo uses credentials: 'include' and does not store session secrets in localStorage.
• Opaque clients (mobile) send Authorization: Bearer <access> to GraphQL; refresh passes both tokens in the GraphQL mutation args. Bearer wins over cookie when both are present (buildBearerAuthMiddleware).
• Platform MCP is a separate HTTP surface (POST /mcp). It authenticates with a dedicated audience=mcp Bearer from MCP OAuth — not a portal cookie and not GraphQL Bearer. See Platform MCP and §9.1.
• GraphQL actor identity comes only from a valid access credential on req.user — never from Passport/express-session.
• Password users verify email before sign-in; passwords are stored with bcrypt via Sequelize model hooks; sign-in uses User.validPassword (bcrypt).
• Google OAuth is optional (env-gated); OAuth hits Express routes under /auth, then returns via a one-time httpOnly auth_exchange cookie (secret) plus a non-secret oauth_exchange=1 marker that tells the portal to call exchangeAuthTokens.
• Multi-tenancy is modeled with organizations and OrganizationMember rows; User.current_membership selects which org context is active for scope checks (see RBAC.md).
• CSRF for browser cookie auth: GraphQL mutations require an Origin/Referer in the allow-list. Missing origin is never allowed in production (apps/backend/src/middleware/csrfOrigin.ts).

​

Technologies and libraries

​

Key architectural decisions (as implemented)

1. Access credential GraphQL auth — buildBearerAuthMiddleware attaches req.user from Bearer or auth_access cookie (Bearer preferred). Middleware chain (isLoggedIn, populateUserWithMemberships, hasScopes) uses that user; super-admin access is scope-based.
2. Hybrid credential store — RDS is source of truth (auth_credentials.token_hash + session_family_id + metadata); Redis hot path via buildCacheHelper (${tokenHash}:auth_token:v2) with per-credential TTL. Redis miss → RDS rehydrate; revoke deletes both.
3. Refresh rotation — refreshAccessToken requires a valid refresh and the paired access token (may be expired) from the same session_family_id. The refresh row is consumed with an atomic UPDATE … WHERE revoked_at IS NULL; only the winner mints a new pair. Credential lookup always re-checks Postgres revoked_at (Redis is not the revocation source of truth).
4. Express session for non-identity cookies — Redis-backed express-session still supports OAuth helper cookies, GDPR consent, and analytics anonymous id. It is not used for GraphQL actor identity. Auth cookies use optional AUTH_COOKIE_DOMAIN (not SESSION_COOKIE_DOMAIN).
5. Email verification gate — canSignInWithPassword rejects users that still have email_validation_token set (apps/backend/src/utilities/auth.ts).
6. OAuth redirect UX — Post-auth browser redirect targets the SPA sign-in route with an optional validated internal redirect query param; the path is carried in a short-lived signed HTTP-only cookie (oauth_post_auth_redirect). Link mode uses GET /auth/google/prepare-link with Bearer or access cookie.

​

How we keep sign-in (and checkout) sane

​

2. Authentication flow

​

2.1 Sign-up flow (password)

• createUser (apps/backend/src/utilities/user.ts) sets email_validated_at to null unless isAlreadyVerified; for password sign-up it calls resetEmailValidation, which sets email_validation_token (hex, 32 random bytes), 24h expiry (getEmailValidationExpiration), and queues verify email when enabled.
• Verification link shape: buildVerifyEmailLink → {frontend}/verify/{token} with optional ?redirect= (apps/backend/src/utilities/redirect.ts).
• If email already exists, resolver returns success: true (and may surface "Email verification required" when a validation token still exists) — intentional obfuscation of enumeration (signUpWithPassword).

​

2.2 Sign-in flow (password)

export const canSignInWithPassword = async (
  email: string,
  password: string,
  tools: ToolsType,
): CanSignInWithPasswordResult => {
  const rds = tools.rds;
  const logger = tools.logger;
  const defaultError = 'Invalid email or password';

  try {
    const user = await rds.models.User.findOne({
      where: {
        email,
      },
    });

    if (!user) {
      logger.warn('Sign in attempted with non-existent email', { email });
      return { success: false, result: defaultError };
    }

    if ((await user.validPassword(password)) === false) {
      logger.warn('Invalid password provided for user', { email });
      return { success: false, result: defaultError };
    }

    // Check if email is verified
    if (user.email_validation_token) {
      return {
        success: false,
        result: 'Please verify your email before signing in',
      };
    }

    return { success: true, result: user };
  } catch (error) {

​

2.3 Sign-in flow (Google OAuth)

​

2.4 Session management

const SESSION_MAX_AGE_MS = 1000 * 60 * 60 * 24 * 30;

const initSession = (app: Express, tools: ToolsType) => {
  const sessionCookieDomain = process.env.SESSION_COOKIE_DOMAIN;

  app.use(
    session({
      secret: process.env.SESSION_SECRET,
      resave: false,
      saveUninitialized: false,
      store: new RedisStore({
        client: tools.cache.client,
        prefix: 'session:',
      }),
      cookie: {
        maxAge: SESSION_MAX_AGE_MS,
        httpOnly: true,
        sameSite: 'lax',
        path: '/',
        secure: process.env.NODE_ENV === 'production',
        ...(sessionCookieDomain ? { domain: sessionCookieDomain } : {}),
      },
    }),
  );

  app.use(passport.initialize());
  app.use(passport.session());

  app.use(cookieParser());

  // Configure passport strategies
  configurePassport(tools);
};

  passport.serializeUser((user: User, done) => {
    done(null, user.id);
  });

  passport.deserializeUser(async (id: string, done) => {
    try {
      const user = await tools.rds.models.User.findByPk(id);
      done(null, user || { id });
    } catch (error) {
      tools.logger.error(error, {
        message: 'Failed to deserialize user',
        user_id: id,
      });
      done(error);
    }
  });

​

2.5 Sign-out flow

​

3. Token & session architecture

​

4. Password handling

​

Hashing strategy

• Algorithm: bcrypt (apps/backend/src/tools/rds/sequelize/models/user/index.ts).
• Salt rounds: Number(process.env.SALT_ROUNDS) in beforeCreate / beforeUpdate when password changes.
• Verification: User.validPassword uses bcrypt.compare.

  static buildHooks = () => {
    User.beforeCreate(async (instance: User) => {
      if (instance.password) {
        const salt = await bcrypt.genSalt(Number(process.env.SALT_ROUNDS));
        instance.salt = salt;
        instance.password = await bcrypt.hash(instance.password, salt);
      }
    });

    User.beforeUpdate(async (instance: User) => {
      if (instance.changed('password')) {
        const salt = await bcrypt.genSalt(Number(process.env.SALT_ROUNDS));
        instance.salt = salt;
        instance.password = await bcrypt.hash(instance.password, salt);
      }
    });
  };

​

Passport vs password login

​

Password strength

• 8–40 chars, at least one upper, lower, digit, and one of @.#$!%*?&.

​

Password reset flow

• Mailer template type AvailableTemplates.PASSWORD_RESET and queue consumer (apps/backend/src/tools/mailer/emails/index.ts, apps/backend/src/tools/queue/consumers/mailer/passwordReset.ts).
• Template builder apps/backend/src/tools/mailer/emails/passwordReset.ts.

​

Email verification / reset token behavior

• validateEmail mutation calls validateEmailToken (apps/backend/src/gql/mutations/validateEmail.ts).
• Expired validation tokens can trigger resend logic with cooldown (1 hour — TOKEN_RESEND_COOLDOWN_HOURS in apps/backend/src/utilities/user.ts).

​

5. Team invites

​

How invites are generated

• inviteMember (apps/backend/src/gql/mutations/inviteMember.ts) uses createInvitation → resetInvitation (apps/backend/src/utilities/organization.ts).
• Token: crypto.randomUUID() (generateInvitationToken).
• Expiry: INVITATION_EXPIRY_DAYS = 7 → getInvitationExpiration.

export const INVITATION_EXPIRY_DAYS = 7;

export const getInvitationExpiration = () => {
  return new Date(Date.now() + 1000 * 60 * 60 * 24 * INVITATION_EXPIRY_DAYS);
};

export const isInvitationExpired = (invitation: OrganizationMember) => {
  return invitation.invitation_expires_at && invitation.invitation_expires_at < new Date();
};

export const generateInvitationToken = () => {
  return crypto.randomUUID();
};

• Email link: {frontend}/invitation/{invitation_token} (queued in resetInvitation).

​

Accept flow (logged-in user)

1. getOpenInvitationByToken requires invitation_token, matching user_id, invitation_expires_at > now, invitation_accepted_at null.
2. clearInvitation sets token/expiry null and invitation_accepted_at to now.
3. Updates user.current_membership to the accepted membership id.

​

Invite preview query (pre-login)

​

Completing profile for invited users

​

When an invite expires

​

6. Relationship to RBAC

• PublicRoles / Roles and User.is_super_admin
• hasScopes, isAdmin, isAdminOrSuperAdmin, isSuperAdmin
• AllScopes, Redis caching, ProductRoleScope

​

7. Multi-tenancy

​

Isolation model

• Organization is the tenant boundary (Organization model).
• Membership links user_id + organization_id with role (OrganizationMember).
• Active tenant for the session user is User.current_membership pointing at one OrganizationMember id.

​

How tenant context flows

1. buildBearerAuthMiddleware loads User from the access token; GraphQL middlewares often reload with memberships included (populateUserWithMemberships, hasScopes, isAdmin, etc.).
2. getCurrentMembership(user) picks the membership matching current_membership.
3. switchOrganization (apps/backend/src/gql/mutations/switchOrganization.ts) validates the user belongs to the target org, updates current_membership, and reissues Bearer tokens so org snapshot metadata stays honest.

​

RBAC + multi-tenancy

• Scopes are computed for organizationMember + active subscription’s product (getScopesForOrganizationMembership in apps/backend/src/utilities/rbac.ts).
• Wrong or missing current_membership → getCurrentMembership returns null → middleware typically throws 403 or 500 depending on handler.

​

8. Middleware & guards

​

GraphQL middleware modules

​

How to protect a GraphQL resolver

  return resolveWithMiddlewares(_parent, _form, context, [
    isLoggedIn,
    populateUserWithMemberships,
    async (_parent, form, context: ContextWithUser) => {

// Pattern from inviteMember — see apps/backend/src/gql/mutations/inviteMember.ts
return resolveWithMiddlewares(_parent, params, context, [
  isLoggedIn,
  hasScopes([AllScopes.MEMBERS_INVITE], ScopeMatchMode.EVERY),
  async (_parent, params, context: ContextWithUser) => { /* ... */ },
]);

​

How to protect an Express route

• OAuth routes — passport.authenticate (often { session: false }) plus token mint / exchange handoff (apps/backend/src/routers/auth/).
• Webhooks — e.g. Stripe uses Stripe signature verification, not Bearer (apps/backend/src/routers/api/stripe.ts).
• Access-protected helpers — e.g. GET /auth/google/prepare-link validates Bearer or access cookie before setting the link cookie.

​

9. Extending the auth system

​

Add a new auth provider (OAuth / SSO)

1. Add a Passport strategy module under apps/backend/src/auth/strategies/.
2. Register it inside configurePassport (apps/backend/src/auth/passport.ts) with appropriate env guards (mirror GOOGLE_CLIENT_ID pattern).
3. Mount routes under buildAuthRouter (apps/backend/src/routers/auth/index.ts) or a new router registered in buildRouters (apps/backend/src/routers/index.ts).
4. Ensure callback URLs match how the SPA proxies to the backend (apps/portal/vite.config.ts for dev).
5. Decide user provisioning rules (see googleStrategyCallback for create/link user + default org) (apps/backend/src/auth/strategies/google.ts).

​

Add a new role or permission

​

Customize the invite flow

• GraphQL: inviteMember, acceptInvitation, invitation, completeInvitedProfile.
• Utilities: createInvitation, resetInvitation, clearInvitation, getInvitationExpiration (apps/backend/src/utilities/organization.ts).
• Mail template: ORGANIZATION_INVITATION payload includes invitationLink (resetInvitation).

​

9.1 Credential types: human sessions vs later machine keys

​

9.1.1 Platform MCP OAuth redirect policy (client integrations)

​

Decisions

​

Single source of truth

mcp: {
  enabled: resolveMcpEnabledFromEnv(),
  allowList: {
    // omit → loopback only for non-loopback clients
    cursor: {
      label: 'Cursor',
      redirectUris: [
        'cursor://anysphere.cursor-mcp/oauth/callback',
        'https://www.cursor.com/agents/mcp/oauth/callback',
      ],
    },
  },
}

# Quick shutoff of the whole MCP surface (routes unmounted)
MCP_ENABLED=false

​

Enabling Cursor (non-dev)

1. Add a cursor entry under mcp.allowList in the target env config module (exact callback URIs only).
2. Restart backend (ensure MCP_ENABLED is not false).
3. Point Cursor MCP at {APP_URL}/mcp with OAuth (never paste a portal Bearer).
4. Complete authorize as a super admin. If you are signed out, authorize 302s to /signin?redirect=/auth/mcp/continue/:requestId; after sign-in the portal full-document-navigates to that path (Caddy → backend consent HTML). SPA navigate would 404 on the portal.
5. After OAuth, Cursor uses Streamable HTTP JSON-RPC on POST /mcp (ALA-263). Authenticated tools/list includes mcp_whoami when the actor has mcp:whoami.

​

Adding another harness later

​

9.2 Session governance (super admin)

​

10. Common pitfalls

1. httpOnly cookies — Portal JS cannot read auth_access / auth_refresh. Refresh uses cookie fallback (optional mutation args for opaque clients). Apollo must send credentials: 'include'.
2. Anonymous gate probes — FetchMe on /signin / /signup (and other public auth routes) returns GraphQL 401 when logged out. Apollo’s error link still attempts refresh; on failure completeClientLogout clears client artifacts but must not set window.location.href while already on a public auth path (that reload looped forever).
3. OAuth auth_exchange race — After Google OAuth, the callback stores a short-lived exchange payload, sets an httpOnly auth_exchange cookie, and redirects to /signin?oauth_exchange=1 without minting DB credentials or putting the secret in the URL. The portal must skip FetchMe and gate-page refresh until exchangeAuthTokens finishes minting + setting cookies; otherwise an in-flight refresh can rotate the brand-new pair (even with cookies flushed). If a different user is already signed in, the mutation burns the code and does not swap accounts.
4. CSRF — Cookie-authenticated mutations need a valid Origin/Referer; production never allows missing origin.
5. Email verification state — Sign-in checks email_validation_token truthiness, not only email_validated_at (canSignInWithPassword). Keep those fields consistent when seeding users.
6. invitation query typing — Resolver uses ContextWithUser in its signature but does not run isLoggedIn; it is effectively public for invite landing pages (apps/backend/src/gql/queries/invitation.ts).
7. Cookie domains — Optional AUTH_COOKIE_DOMAIN for auth cookies and SESSION_COOKIE_DOMAIN for express-session; omit in local dev for host-only cookies.
8. Google OAuth deserialize — Passport still serializes for OAuth adapter flows; GraphQL actor identity comes from access credential lookup, not deserializeUser.
9. No password reset API — Do not point users at reset URLs until GraphQL + persistence exist (§4).
10. Subscription required for scopes — After login, RBAC may still deny everything if the org has no active subscription (RBAC.md).

​

Quick reference: key files

​

What’s next?

• RBAC — how roles and scopes gate feature access once a user is authenticated.
• Billing — Stripe subscriptions, checkout, and how subscription state drives RBAC.
• Architecture overview — the full system map and layer summary.