Authentication and Identity

Relevant source files

The following files were used as context for generating this wiki page:

• apps/admin/README.md
• apps/storefront/README.md
• apps/storefront/src/auth/auth.config.test.ts
• CONTEXT.md
• packages/db/src/lib/doc-to-shape.test.ts
• apps/admin/src/app/(app)/page.test.tsx/page.test.tsx)

Authentication and Identity in the Nordcom Commerce project provide a dual-layered security model tailored for different application surfaces. The system distinguishes between Operators (merchants/shop owners) who manage shops through the Admin dashboard and Buyers (customers) who interact with the multi-tenant Storefront.

The architecture leverages Clerk for operator authentication in the Admin app and NextAuth v5 for buyer and session management in the Storefront. Identity data is persisted and synchronized within a Convex-backed data layer, ensuring that user roles, shop associations, and collaborative permissions remain consistent across the platform.
Sources: apps/admin/README.md, apps/storefront/README.md, CONTEXT.md

Authentication Architecture

The project employs distinct authentication providers and strategies depending on the application context and the type of user being authenticated.

Operator Authentication (Admin App)

Operators use Clerk (@clerk/nextjs) to sign in to the Admin dashboard. Upon successful sign-in, the server mints a Convex token using Clerk's JWT template, allowing the user to interact with the Convex backend as an authenticated operator.
Sources: apps/admin/README.md:12-13, apps/admin/src/app/(app)/page.test.tsx:94-98

Buyer and Storefront Auth

The Storefront uses NextAuth v5 (@auth/core) to manage customer sessions. For Shopify-integrated shops, it utilizes the Shopify OAuth flow, persisting access tokens within the JWT and session objects to facilitate authenticated commerce operations.
Sources: apps/storefront/README.md:14, apps/storefront/src/auth/auth.config.test.ts:98-115

Data Flow for Operator Login

The following diagram illustrates the authentication flow for an administrator/operator accessing the dashboard.

This flow ensures that operator sessions are verified by Clerk before being granted access to the multi-tenant shop data in Convex.
Sources: apps/admin/README.md:12-13, apps/admin/src/app/(app)/page.test.tsx:94-105

Identity and Session Management

Identities are managed through the @nordcom/commerce-db package, which provides a typed service layer over Convex for users, sessions, and identities.

Identity Types

• Collaborator: A user with specific permissions[] granted for a specific Shop. The CMS mirrors this list to ensure consistent access predicates.
• Buyer Identity: Represents the checkout identity (email, phone, country code) of a storefront user. This is distinct from a Collaborator and exists even for guest users.
• User Document: The persisted record in Convex containing profiles, verified emails, and linked identities (e.g., GitHub, Shopify).
  Sources: CONTEXT.md:287-320, packages/db/src/lib/doc-to-shape.test.ts:98-115

Auth Session Configuration

The project uses specific cookie naming and security configurations based on the environment to protect session tokens.

Configuration	Development	Production
Cookie Name	NordcomCommerceSession	__Secure-NordcomCommerceSession
Secure Flag	false	true
SameSite	lax	lax
Domain Scope	Omitted (localhost)	Scoped to parent (e.g., .example.com)
Sources: apps/storefront/src/auth/auth.config.test.ts:38-70

Security and Permission Logic

Access control is enforced at multiple levels to prevent unauthorized data exposure, particularly in multi-tenant scenarios.

Sensitive Data Projection

The Shop and User models in @nordcom/commerce-db automatically project out sensitive fields such as collaborators and provider tokens. Developers must explicitly opt-in using { sensitiveData: true } on the server-side only.
Sources: apps/admin/README.md:113-116, packages/db/src/lib/doc-to-shape.test.ts:133-155

Multi-tenant Isolation

Authentication is tightly coupled with tenant resolution. In the Storefront, the proxy.ts middleware resolves the tenant by hostname before authentication context is established, ensuring users are authenticated within the correct shop's scope.
Sources: apps/storefront/README.md:32-42, CONTEXT.md:13-25

The middleware acts as the primary gatekeeper, ensuring that authentication logic is always aware of the specific tenant context.
Sources: apps/storefront/README.md:32-42, CONTEXT.md:434-440

JWT and Session Callbacks

In Shopify-integrated storefronts, authentication state is enhanced with provider-specific tokens to allow seamless API interaction.

// From auth.config.test.ts:101-115
// Persists Shopify access_token onto the JWT
const token = await jwt({
    token: {},
    account: {
        provider: 'shopify',
        access_token: 'shopify-access-token-123',
    },
});

// Exposes the token on session.user
const session = await sessionCb({
    session: baseSession,
    token: { shopifyAccessToken: 'shopify-access-token-123' },
});

Sources: apps/storefront/src/auth/auth.config.test.ts:98-142

Summary

The Authentication and Identity system provides a robust framework for managing both platform operators and storefront customers. By leveraging industry standards like Clerk and NextAuth v5, and strictly enforcing multi-tenant isolation through Convex-backed identity documents, the architecture ensures that sensitive merchant data remains secure while providing a seamless login experience for end users.
Sources: apps/admin/README.md, apps/storefront/README.md, CONTEXT.md