cubic-auth

3.2.3 verified Fri May 01 auth: no javascript

Simple OAuth2 authentication server for the Cubic framework (v3.2.3). Provides JWT-based access and refresh tokens using RS256 signing by default. Integrates with cubic-api and cubic-core to verify users stored in the auth database. Key differentiators: built specifically for Cubic's ecosystem, supports cookie-based auth for web clients, and manages user logs. Not intended as a standalone auth server outside Cubic.

Common errors

error Error: Cannot find module 'cubic-auth' ↓

cause Package not installed or wrong version.

fix

Run 'npm install cubic-auth' and ensure it's in node_modules.

error TypeError: cubic.use is not a function ↓

cause Cubic instance not created correctly.

fix

Use 'const cubic = new Cubic()' before calling 'cubic.use()'.

error Error: certPrivate option is required in production mode ↓

cause Running outside dev mode without providing RSA keys.

fix

Set 'certPrivate' and 'certPublic' options with valid RSA key strings.

Warnings

breaking cubic-auth v3 requires cubic-api >=3.0.0. Older versions are incompatible. ↓

fix Update cubic-api to v3.0.0 or later.

deprecated The 'certPrivate' and 'certPublic' options must be provided as strings. In dev mode they are auto-generated; in production they are required. ↓

fix Provide valid RSA key strings for 'certPrivate' and 'certPublic' in production.

gotcha Options 'api' and 'core' can override internal nodes but must be objects; misconfiguration can prevent server startup. ↓

fix Ensure 'api' and 'core' options are plain objects with valid sub-options like 'server.port'.

gotcha The 'exp' option uses string format like '1h', not milliseconds. Invalid formats will cause token issuance to fail silently. ↓

fix Use valid ms string (e.g., '1h', '30m') for 'exp'.

Install

npm install cubic-auth

yarn add cubic-auth

pnpm add cubic-auth

Imports

Auth

wrong

const Auth = require('cubic-auth').default

correct

const Auth = require('cubic-auth')

CommonJS only; no ESM support in v3.2.3.

options

wrong

import { Auth } from 'cubic-auth'

correct

const cubic = new Cubic(); cubic.use(new Auth({ exp: '2h', alg: 'RS256' }))

Must be used as a plugin with Cubic instance.

certPrivate

wrong

new Auth({ privateKey: '...' })

correct

new Auth({ certPrivate: '...', certPublic: '...' })

Option key is 'certPrivate' not 'privateKey'.

Quickstart

Initializes a Cubic auth server with custom API and core ports using CommonJS require.

const Cubic = require('cubic')
const Auth = require('cubic-auth')

const cubic = new Cubic()
cubic.use(new Auth({
  api: { server: { port: 3030 } },
  core: { server: { port: 2020 } }
}))

cubic.on('nodestarted', () => {
  console.log('Auth server running on port 3030')
})