auth:
  providers:
    - id: google
      type: GoogleProvider
      properties:
        clientId:
          _secret: GOOGLE_CLIENT_ID
        clientSecret:
          _secret: GOOGLE_CLIENT_SECRET

  adapter:
    type: MongoDBAdapter
    properties:
      connectionString:
        _secret: MONGODB_URI

  callbacks:
    session:
      - _function:
          __session.user.roles: __token.roles
    jwt:
      - _function:
          __token.roles: __user.roles

  pages:
    protected: [dashboard, settings]
    public: [home, about]
    roles:
      admin: [admin-panel]

  authPages:
    signIn: /login
    error: /auth/error

  session:
    strategy: jwt
    maxAge: 2592000

function buildAuth({ components, context }) {
  const configured = !type.isNone(components.auth);
  components.auth.configured = configured;

  validateAuthConfig({ components });
  buildApiAuth({ components }); // API endpoint protection
  buildPageAuth({ components }); // Page protection
  buildAuthPlugins({ components, context });

  return components;
}

function buildPageAuth({ components }) {
  const protectedPages = getProtectedPages({ components });
  const pageRoles = getPageRoles({ components });

  components.pages.forEach((page) => {
    if (pageRoles[page.id]) {
      page.auth = { public: false, roles: pageRoles[page.id] };
    } else if (protectedPages.includes(page.id)) {
      page.auth = { public: false };
    } else {
      page.auth = { public: true };
    }
  });
}

function buildApiAuth({ components }) {
  const protectedEndpoints = getProtectedApi({ components });
  const apiRoles = getApiRoles({ components });

  components.api.forEach((endpoint) => {
    if (apiRoles[endpoint.id]) {
      endpoint.auth = { public: false, roles: apiRoles[endpoint.id] };
    } else if (protectedEndpoints.includes(endpoint.id)) {
      endpoint.auth = { public: false };
    } else {
      endpoint.auth = { public: true };
    }
  });
}

function getNextAuthConfig({ authJson, logger, plugins, secrets }) {
  // Parse operators (_secret support)
  const operatorsParser = new ServerParser({
    operators: { _secret },
    secrets,
  });

  const { output: authConfig } = operatorsParser.parse({
    input: authJson,
    location: 'auth',
  });

  // Build NextAuth options
  return {
    adapter: createAdapter({ authConfig, plugins }),
    callbacks: createCallbacks({ authConfig, plugins }),
    events: createEvents({ authConfig, plugins }),
    providers: createProviders({ authConfig, plugins }),
    pages: authConfig.authPages,
    session: authConfig.session,
    theme: authConfig.theme,
    cookies: authConfig?.advanced?.cookies,
    debug: authConfig.debug,
  };
}

function createProviders({ authConfig, plugins }) {
  return authConfig.providers.map((providerConfig) =>
    plugins.providers[providerConfig.type]({
      ...providerConfig.properties,
      id: providerConfig.id,
    })
  );
}

async function jwtCallback({ token, user, account, profile, isNewUser }) {
  // Extract OIDC claims
  if (profile) {
    token = {
      id,
      sub,
      name,
      given_name,
      family_name,
      email,
      email_verified,
      picture,
      ...token,
    };
  }

  // Add custom userFields
  if (authConfig.userFields) {
    addUserFieldsToToken({ authConfig, account, profile, token, user });
  }

  // Execute custom callback plugins
  for (const plugin of jwtCallbackPlugins) {
    token = await plugin.fn({ account, profile, token, user });
  }

  return token;
}

async function sessionCallback({ session, token, user }) {
  // Map token to session.user
  session.user = {
    id, sub, name, given_name, family_name,
    email, picture, ...
  };

  // Add custom userFields
  if (authConfig.userFields) {
    addUserFieldsToSession({ authConfig, session, token, user });
  }

  // Execute custom plugins
  for (const plugin of sessionCallbackPlugins) {
    session = await plugin.fn({ session, token, user });
  }

  // Validate roles after all sources have written to the session.
  // Throws ConfigError if roles is present but not an array of strings.
  validateSessionRoles({ session });

  // Create anonymized hash for analytics
  session.hashed_id = crypto.createHash('sha256')
    .update(identifier ?? '')
    .digest('base64');

  return session;
}

async function signInCallback({ account, credentials, email, profile, user }) {
  let allowSignIn = true;

  for (const plugin of signInCallbackPlugins) {
    allowSignIn = await plugin.fn({
      account,
      credentials,
      email,
      profile,
      user,
    });
    if (allowSignIn === false) break;
  }

  return allowSignIn;
}

# Configuration
auth:
  userFields:
    company: 'profile.company'
    department: 'profile.department'
    roles: 'profile.roles'

// Implementation
function addUserFieldsToToken({ authConfig, account, profile, token, user }) {
  Object.entries(authConfig.userFields).forEach(([fieldName, providerField]) => {
    const value = get({ account, profile, user }, providerField);
    set(token, fieldName, value);
  });
}

function createAuthorize({ session }) {
  const authenticated = !!session;
  const roles = session?.user?.roles ?? [];

  // Defense-in-depth: throw if roles bypassed session callback validation.
  // A string would cause silent authorization bypass via substring matching.
  if (!Array.isArray(roles)) {
    throw new ConfigError('session.user.roles must be an array of strings.', {
      received: roles,
    });
  }

  function authorize({ auth }) {
    if (auth.public === true) return true;

    if (auth.public === false) {
      if (auth.roles) {
        // Role-based: user must have one of the required roles
        return authenticated && auth.roles.some((role) => roles.includes(role));
      }
      // Auth-only: user must be authenticated
      return authenticated;
    }

    throw new ConfigError('auth.public must be true or false.', {
      received: auth.public,
      configKey: config['~k'],
    });
  }

  return authorize;
}

async function getPageConfig({ authorize, readConfigFile }, { pageId }) {
  const pageConfig = await readConfigFile(`pages/${pageId}/${pageId}.json`);

  if (pageConfig && authorize(pageConfig)) {
    const { auth, ...rest } = pageConfig; // Remove auth metadata
    return { ...rest };
  }

  return null; // 404 for unauthorized
}

function authorizeApiEndpoint({ authorize }, { endpointConfig }) {
  if (!authorize(endpointConfig)) {
    throw new ConfigurationError('Not authorized');
  }
}

function serverSidePropsWrapper(handler) {
  return async function wrappedHandler(nextContext) {
    const context = { ... };

    // Initialize auth options
    context.authOptions = getAuthOptions(context);

    // Fetch server session
    context.session = await getServerSession(context);

    // Create API context with authorization
    createApiContext(context);

    return handler({ context, nextContext });
  };
}

function AuthConfigured({ authConfig, children, serverSession }) {
  const auth = { authConfig, getSession, signIn, signOut };

  return (
    <SessionProvider session={serverSession} basePath={basePath}>
      <Session>
        {(session) => {
          auth.session = session;
          return children(auth);
        }}
      </Session>
    </SessionProvider>
  );
}

function _user({ arrayIndices, location, params, user }) {
  return getFromObject({
    arrayIndices,
    location,
    object: user,
    operator: '_user',
    params,
  });
}

# In block properties
content:
  _string:
    - 'Welcome, '
    - _user: session.user.name

# In request authorization
visible:
  _eq:
    - _user: session.user.role
    - admin

async function handler({ context, req, res }) {
  if (authJson.configured !== true) {
    return res.status(404).json({ message: 'Auth not configured' });
  }

  // Corporate email link check
  if (req.method === 'HEAD') {
    return res.status(200).end();
  }

  return NextAuth(req, res, context.authOptions);
}

const events = {
  createUser, // First login - user created
  linkAccount, // Account linked to user
  signIn, // User signed in
  signOut, // User signed out
  updateUser, // Profile updated
  session, // Session events
};

lowdefy.yaml
    ↓
buildAuth() [BUILD TIME]
    ├→ validateAuthConfig()
    ├→ buildPageAuth() → page.auth = { public, roles }
    ├→ buildApiAuth() → endpoint.auth = { public, roles }
    └→ buildAuthPlugins()
    ↓
auth.json
    ↓
[RUNTIME - PAGE REQUEST]
    ↓
serverSidePropsWrapper()
    ├→ getAuthOptions() → getNextAuthConfig()
    │   ├→ createProviders()
    │   ├→ createCallbacks()
    │   ├→ createEvents()
    │   └→ createAdapter()
    │
    ├→ getServerSession()
    │
    └→ createApiContext() → createAuthorize(session)
    ↓
Page Handler
    └→ getPageConfig() → authorize(pageConfig)
    ↓
_app.js [CLIENT]
    ↓
Auth Component (SessionProvider)
    ↓
Page Component
    ├→ auth.session
    ├→ _user operator
    └→ auth.signIn/signOut

LOWDEFY_DEV_USER='{"sub":"test-user","email":"[email protected]","roles":["admin"]}'

auth:
  providers:
    - id: credentials
      type: CredentialsProvider
      # ...
  dev:
    mockUser:
      sub: test-user
      email: [email protected]
      roles:
        - admin

async function getMockSession() {
  // 1. Check env var first (takes precedence)
  const mockUserJson = process.env.LOWDEFY_DEV_USER;
  let mockUser = mockUserJson ? JSON.parse(mockUserJson) : authJson.dev?.mockUser;

  if (!mockUser) return undefined;

  // 2. Validate auth is configured
  if (authJson.configured !== true) {
    throw new Error('Mock user configured but auth is not configured');
  }

  // 3. Transform through session callback (userFields, custom callbacks apply)
  const sessionCallback = createSessionCallback({ authConfig: authJson, plugins: { callbacks } });
  const session = await sessionCallback({
    session: { user: {} },
    token: mockUser,
    user: mockUser,
  });

  return session;
}

function e2eNotSupported() {
  throw new Error('Sign-in and sign-out are not supported in e2e testing.');
}

if (authJson.configured && !session) {
  const loginPage = authJson.pages?.public?.[0] ?? '404';
  return { redirect: { destination: `/${loginPage}`, permanent: false } };
}