Functions

loadConfig

Load and validate the server configuration from environment variables.

Signature:

loadConfig(): { port: number; host: string; nodeEnv: "development" | "production" | "test"; jwtPrivateKey: string; jwtPublicKey: string; authDataDir: string; defaultDomainId: string; accessTokenTTL: number; refreshTokenTTL: number; issuer: string; }

Returns:

{ port: number; host: string; nodeEnv: "development" \| "production" \| "test"; jwtPrivateKey: string; jwtPublicKey: string; authDataDir: string; defaultDomainId: string; accessTokenTTL: number; refreshTokenTTL: number; issuer: string; } - Validated configuration object

createServer

Create and configure the Express application. This function sets up middleware, routes, and error handlers.

Signature:

createServer(configOverride?: Partial<{ port: number; host: string; nodeEnv: "development" | "production" | "test"; jwtPrivateKey: string; jwtPublicKey: string; authDataDir: string; defaultDomainId: string; accessTokenTTL: number; refreshTokenTTL: number; issuer: string; }> | undefined): Promise<express.Express>

Parameters:

Returns:

Promise<express.Express> - Configured Express application instance

startServer

Start the Express server and begin listening for requests.

Signature:

startServer(app: express.Express): Promise<void>

Parameters:

Returns:

Promise<void> -

createRequireAuth

Creates an authentication middleware that validates JWT tokens and API tokens.

JWT tokens are validated using the TokenManager from flowstate-auth-core. API tokens (starting with 'epic_') are validated against bcrypt hashes stored in the database.

Signature:

createRequireAuth(tokenManager: TokenManager, storage: AuthStorageAdapter, domainId: string): (req: Request, res: Response, next: NextFunction) => Promise<void>

Parameters:

Returns:

(req: Request, res: Response, next: NextFunction) => Promise<void> - Express middleware function

Examples:

const authMiddleware = createRequireAuth(tokenManager, storage, 'default')
app.use('/api', authMiddleware)

createAuthRoutes

Creates authentication routes for the Express application.

Endpoints:

• POST /send-code - Send email verification code
• POST /login - Login with email and verification code
• POST /refresh - Refresh access token using refresh token

Signature:

createAuthRoutes(config: AuthRoutesConfig): Router

Parameters:

Returns:

Router - Express Router with auth endpoints

Examples:

const authRouter = createAuthRoutes({
  tokenManager,
  storage,
  mailService,
  defaultDomainId: 'default'
})
app.use('/auth', authRouter)

createOAuthRoutes

Signature:

createOAuthRoutes(oauthService: OAuthService, tokenService: TokenService, storageOrConfig: AuthStorageAdapter | OAuthRouterConfig, maybeConfig?: OAuthRouterConfig | undefined): Router

Parameters:

Returns:

Router -

createTokenRoutes

Creates the token management router.

Signature:

createTokenRoutes(storage: AuthStorageAdapter, logger: Logger): Router

Parameters:

Returns:

Router - Express Router with token endpoints

Examples:

const tokenRoutes = createTokenRoutes(storage, logger)
app.use('/auth', requireAuth, tokenRoutes)

createUserRoutes

Creates the user management router.

Signature:

createUserRoutes(): Router

Returns:

Router - Express Router with user endpoints

Examples:

const userRoutes = createUserRoutes()
app.use('/auth', requireAuth, userRoutes)

createOAuthMetadata

Create the OAuth metadata object for the authorization server. Per RFC 8414, endpoints must be absolute URLs.

Signature:

createOAuthMetadata(issuer: string): OAuthMetadata

Parameters:

Returns:

OAuthMetadata - OAuth authorization server metadata

createWellKnownRoutes

Create a router for well-known endpoints.

Implements RFC 8414 (OAuth 2.0 Authorization Server Metadata) which allows OAuth clients to automatically discover the authorization server's configuration.

Signature:

createWellKnownRoutes(issuer: string): Router

Parameters:

Returns:

Router - Express router handling /.well-known endpoints

Examples:

const wellKnownRouter = createWellKnownRoutes('https://api.flowstate.dev')
app.use('/.well-known', wellKnownRouter)