Crescent.js logoCrescent.jsv1.0.3
Guides

Authentication Guide

Add signup, login, and OAuth support to your application.

Overview

Crescent.js provides a built-in authentication system through the crescent.auth namespace, with signup, login, password, and oauth submodules. Store users, validate credentials, and handle OAuth flows without managing sessions manually.

Built-in and secure

Passwords are hashed with a per-user salt before being stored, and the auth system works with the built-in database out of the box.

Signup

signup.js
const signup = crescent.auth.signup();

const result = await signup.register('Alice', 'alice@example.com', 'secure-password-123');

console.log(result.success); // true
console.log(result.user.username); // 'Alice'
console.log(result.user.email); // 'alice@example.com'

What is checked

Usernames and emails must be unique, and the password must pass the built-in strength check. Weak passwords are rejected with a strength reason.

Login

Validate credentials with authenticate(). On success you get the user record, a session token, and a Set-Cookie header.

login.js
const login = crescent.auth.login();

const result = await login.authenticate('alice@example.com', 'secure-password-123');

console.log(result.success); // true
console.log(result.user.username); // 'Alice'
console.log(result.token); // session token
console.log(result.set_cookie); // 'Set-Cookie: ...'

// Later: verify a session token
login.verify_session(result.token);

Password Management

Hash, verify, and check the strength of passwords:

password.js
const password = crescent.auth.password;

// Hash a password (returns a hash and its salt)
const { hash, salt } = password.hash('new-password-456');

// Verify a password against a stored hash and salt
const valid = password.verify('new-password-456', hash, salt); // true

// Check strength before saving
const strength = password.check_strength('weak'); // { score, strength: 'weak' }

Store passwords safely

Always use strong passwords. The auth system handles hashing internally, but you should never log or expose raw passwords.

OAuth

Configure OAuth providers so users can sign in with third-party accounts:

oauth.js
const oauth = crescent.auth.oauth();

oauth.add_provider('google', {
  client_id: 'YOUR_CLIENT_ID',
  client_secret: 'YOUR_CLIENT_SECRET',
  authorize_url: 'https://accounts.google.com/o/oauth2/auth',
  token_url: 'https://oauth2.googleapis.com/token',
  user_info_url: 'https://www.googleapis.com/oauth2/v3/userinfo',
  redirect_uri: 'https://your-app.com/auth/callback'
});

// Build the authorization URL for the browser
const url = oauth.get_authorize_url('google');

Full Example

Here is a complete signup and login flow exposed through API endpoints:

auth-api.js
const api = crescent.api_make({
  api_id: 'main',
  port: 3000
});

// POST /signup - create a new account
api.add_endpoint('POST', '/signup', async function (req, res) {
  const result = await crescent.auth.signup().register(
    req.body.name,
    req.body.email,
    req.body.password
  );
  res.writeHead(result.success ? 200 : 400, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify(result));
});

// POST /login - sign an existing user in
api.add_endpoint('POST', '/login', async function (req, res) {
  const result = await crescent.auth.login().authenticate(
    req.body.email,
    req.body.password
  );
  if (result.success) {
    res.writeHead(200, { 'Content-Type': 'application/json', ...result.set_cookie });
  } else {
    res.writeHead(401, { 'Content-Type': 'application/json' });
  }
  res.end(JSON.stringify(result.user || result));
});

api.start();

Next Steps