RODiT ID Authentication System

Using RODiT Configuration in Modules

When working with multiple modules that require RODiT configuration, you can easily import and use the configuration in any module without reinitializing it. Here's how:

1. Import the Required Utilities

In any module where you need to access the RODiT configuration or utilities, import them from the SDK:

const { roditManager, stateManager, logger } = require('@rodit/rodit-auth-be');

2. Accessing Configuration

Once the SDK is initialized in your main application (typically in app.js), you can access the configuration from any module:

// In any module
const { stateManager } = require('@rodit/rodit-auth-be');

async function someFunction() {
  try {
    // Get the current RODiT configuration
    const config = await stateManager.getConfigOwnRodit();
    
    // Access configuration properties
    const { own_rodit } = config;
    const roditId = own_rodit.rodit_id;
    const metadata = own_rodit.metadata || {};
    
    // Use the configuration
    logger.info(`Using RODiT ID: ${roditId}`, { module: 'your-module-name' });
    
    return { roditId, metadata };
  } catch (error) {
    logger.error('Failed to access RODiT configuration', { 
      error: error.message,
      module: 'your-module-name' 
    });
    throw error;
  }
}

3. Using Logger in Modules

The logger is automatically configured in the main application and can be used in any module:

const { logger } = require('@rodit/rodit-auth-be');

function processData(data) {
  try {
    logger.debug('Processing data', { 
      dataLength: data.length,
      module: 'data-processor'
    });
    
    // Your processing logic here
    
    logger.info('Data processed successfully', {
      module: 'data-processor',
      timestamp: new Date().toISOString()
    });
  } catch (error) {
    logger.error('Failed to process data', {
      error: error.message,
      stack: error.stack,
      module: 'data-processor'
    });
    throw error;
  }
}

4. Best Practices

1. Single Initialization: The RODiT SDK should only be initialized once in your main application file (e.g., app.js).

2. Module Context: Always include a module field in your log messages to identify which module generated the log.

3. Error Handling: Always wrap RODiT configuration access in try-catch blocks and include meaningful error messages.

4. Configuration Access: Use stateManager.getConfigOwnRodit() to access the current configuration. This is safe to call multiple times as it returns the cached configuration after the first call.

5. Environment Variables: Remember that environment variables take precedence over configuration files. Use the canonical format (dots replaced with underscores and uppercased) when setting environment variables.

5. Example Module

Here's a complete example of a module that uses the RODiT configuration:

// services/rodit-service.js
const { stateManager, logger } = require('@rodit/rodit-auth-be');

class RoditService {
  constructor() {
    this.moduleName = 'rodit-service';
  }

  async getRoditInfo() {
    try {
      const config = await stateManager.getConfigOwnRodit();
      const { own_rodit } = config;
      
      logger.info('Retrieved RODiT configuration', {
        module: this.moduleName,
        roditId: own_rodit.rodit_id,
        environment: process.env.NODE_ENV || 'development'
      });
      
      return {
        roditId: own_rodit.rodit_id,
        metadata: own_rodit.metadata || {},
        timestamp: new Date().toISOString()
      };
    } catch (error) {
      logger.error('Failed to get RODiT info', {
        module: this.moduleName,
        error: error.message,
        stack: error.stack
      });
      throw new Error(`RODiT service error: ${error.message}`);
    }
  }
}

module.exports = new RoditService();

By following these patterns, you can ensure consistent and reliable access to the RODiT configuration throughout your application while maintaining clean separation of concerns and proper error handling.

This npm package provides the RODiT-based authentication system for Express.js applications. It exports the exact same authentication functionality without adding unnecessary abstraction layers.

Endpoint Determination

The authentication middleware determines the login and logout endpoints based on the following rules:

Login Endpoint

• The login endpoint is constructed by appending /api/login to the base apiEndpoint provided during configuration.
• The base apiEndpoint can be configured in the following ways (in order of precedence):
  1. Directly passed in the configuration object when initializing the SDK
  2. Set via the API_ENDPOINT environment variable
  3. Falls back to a default value if not specified

Logout Endpoint

• The logout endpoint is constructed by appending /api/logout to the base apiEndpoint.
• It uses the same base URL as the login endpoint.

Example Configuration

const auth = require('@rodit/rodit-auth-be');

// Configure with custom endpoint
auth.configure({
  apiEndpoint: 'https://your-api.example.com',
  logger: require('./config/logger')
});

// Login endpoint will be: https://your-api.example.com/api/login
// Logout endpoint will be: https://your-api.example.com/api/logout

Features

• Exclusive RODiT-based authentication with blockchain verification
• JWT-based token management through HTTP headers (no cookies)
• Permission validation for protected routes based on RODiT token permissions
• Session management with secure token handling
• Comprehensive logging and error handling with Loki support
• Automatic RODIT token information display during startup
• Programmatic access to RODIT token metadata for dynamic configuration

Logging Setup

The SDK uses Winston for logging and supports Loki transport for centralized logging. Here's how to set it up:

Basic Console Logging

By default, the SDK will log to the console. You can set the log level using the LOG_LEVEL environment variable:

export LOG_LEVEL=debug  # or info, warn, error

Loki Integration

To enable Loki logging, set these environment variables:

# Required
LOKI_URL=https://your-loki-instance:3100

# Optional
LOKI_BASIC_AUTH=username:password  # If Loki requires authentication
LOKI_TLS_SKIP_VERIFY=true          # Set to "true" to skip TLS verification (not recommended for production)
LOG_LEVEL=info                     # Default: info

Example Integration

const express = require('express');
const { logger } = require('@rodit/rodit-auth-be');

// Basic usage - logs to console
logger.info('Application starting...');

// With context
logger.info('User logged in', { 
  userId: '123',
  ip: '192.168.1.1' 
});

// Error logging
try {
  // Your code here
} catch (error) {
  logger.error('Operation failed', { 
    error: error.message,
    stack: error.stack 
  });
}

Log Levels

• error: Error conditions that require immediate attention
• warn: Warning conditions that might need attention
• info: General operational information
• debug: Detailed debug information
• silly: Extremely detailed debugging

Environment Variables

Log Directory Permissions

When running in a containerized environment, ensure proper permissions are set for log directories:

1. Directory Structure

   /app/logs/
   ├── application/  # Application logs
   └── nginx/        # Nginx access/error logs

2. Required Permissions

   # Create log directories with correct ownership
   mkdir -p /app/logs/{application,nginx}
   
   # Set appropriate permissions (adjust user/group as needed)
   chown -R node:node /app/logs
   chmod -R 755 /app/logs

3. Dockerfile Example

   # Create log directory and set permissions
   RUN mkdir -p /app/logs/{application,nginx} \
       && chown -R node:node /app/logs \
       && chmod -R 755 /app/logs
   
   # Ensure the application user has write access
   USER node

4. Troubleshooting

   • If logs aren't being written, check:
     • Directory exists and is writable by the application user
     • No permission denied errors in container logs
     • Sufficient disk space is available

Installation

npm install @rodit/rodit-auth-be

Usage

Basic Setup

const express = require('express');
const app = express();
const auth = require('@rodit/rodit-auth-be');

// Configure authentication with default options
auth.configure({
  logger: require('./config/logger')
});

// Mount the authentication routes
app.post('/api/login', auth.login);
app.post('/api/logout', auth.authenticate_apicall, auth.logout);

// Protect routes with authentication
app.use('/api/protected', auth.authenticate_apicall, protectedRoutes);

// Add permission validation to routes that require specific permissions
app.use('/api/admin', auth.authenticate_apicall, auth.validatePermissions, adminRoutes);

// Example of a protected route with permission validation
app.get('/api/entities/:entityId', auth.authenticate_apicall, auth.validatePermissions, (req, res) => {
  // This route is protected and requires specific permissions from the RODiT token
  // The validatePermissions middleware will check if the user has permission to access this entity
  const entityId = req.params.entityId;
  // Process the request...
});

app.listen(3000, () => {
  console.log('Server started on port 3000');
});

Custom Configuration

const auth = require('@rodit/rodit-auth-be');

// Configure authentication with custom options
auth.configure({
  // Use a custom logger
  logger: myCustomLogger,
  
  // Set token expiry time to 1 hour (in seconds)
  tokenExpiry: 3600,
  
  // Customize header names
  headerName: 'X-Auth-Token',
  tokenPrefix: '',
  newTokenHeader: 'X-New-Token',
  
  // Customize user property name on request object
  userProperty: 'currentUser'
});

API Reference

Core Middleware Functions

• authenticate_apicall(req, res, next) - Middleware to authenticate_apicall API calls
• validatePermissions(req, res, next) - Middleware to validate permissions for protected routes

Authentication Handlers

• login(req, res) - Handle client login
• logout(req, res) - Handle client logout
• loginWithNEP413(req, res) - Handle client login with NEP-413 standard

Token Functions

• validateToken(token) - Validate a JWT token
• generateToken(payload, options) - Generate a JWT token

Services

• sessionManager - Session management service
• blockchainService - Blockchain interaction service
• stateManager - State management service

RODIT Token Information Access

The SDK provides access to RODIT token information that can be used for dynamic API configuration:

const { stateManager } = require('@rodit/rodit-auth-be');

// Get complete RODIT configuration during or after initialization
const roditClient = await stateManager.getConfigOwnRodit();
const roditToken = roditClient.own_rodit;

// Access token metadata for configuration
const metadata = roditToken.metadata;
const tokenId = roditToken.token_id;

// Example: Configure API behavior based on token metadata
const allowedRoutes = JSON.parse(metadata.permissioned_routes);
const jwtDuration = parseInt(metadata.jwt_duration);
const allowedCIDR = metadata.allowed_cidr;
const apiEndpoint = metadata.subjectuniqueidentifier_url;

// Example: Dynamic rate limiting from token
if (metadata.max_requests && metadata.maxrq_window) {
  const maxRequests = parseInt(metadata.max_requests);
  const windowSeconds = parseInt(metadata.maxrq_window);
  // Apply rate limiting configuration
}

Available RODIT Metadata Fields

• token_id: Unique RODIT token identifier
• allowed_cidr: Permitted IP address ranges (CIDR format)
• allowed_iso3166list: Geographic restrictions (JSON string)
• jwt_duration: JWT token lifetime in seconds
• max_requests: Rate limit - maximum requests per window
• maxrq_window: Rate limit - time window in seconds
• not_before/not_after: Token validity period
• openapijson_url: OpenAPI specification URL
• permissioned_routes: Allowed API routes and methods (JSON string)
• serviceprovider_id: Blockchain contract and service provider info
• serviceprovider_signature: Cryptographic signature for verification
• subjectuniqueidentifier_url: Primary API service endpoint
• userselected_dn: Distinguished name for the service
• webhook_cidr: Allowed IP ranges for webhooks
• webhook_url: Webhook endpoint URL

Startup Information Display

When using this SDK in your application, it automatically displays comprehensive RODIT token information during startup, similar to the roditwallet.sh command:

=== RODiT Authentication System ===
Version 1.0.26 running on testnet at Smart Contract 20251001-rodit-org.testnet
Get help with: npm run help

RODiT Contents
▹▸▹▹▹ Authentication token information loaded...

{
  "token_id": "01K43ASJTMA4V81C46WCRADGVD",
  "metadata": {
    // ... complete token metadata
  }
}

This information helps verify proper token configuration and provides visibility into the authentication system's capabilities.

Configuration

• configure(config) - Configure the authentication system

Configuration Options

• logger - Logger instance (optional, will use default if not provided)
• tokenExpiry - JWT token expiry time in seconds (default: 3600)
• headerName - Name of the header to use for the token (default: 'Authorization')
• tokenPrefix - Prefix to use for the token in the header (default: 'Bearer ')
• newTokenHeader - Name of the header to use for the new token (default: 'New-Token')
• userProperty - Name of the property to attach the user object to on the request (default: 'user')

RODiT ID Authentication

RODiT-based authentication uses the RODiT system to authenticate_apicall users. It requires the following parameters in the login request:

• roditid - RODiT ID
• timestamp - Timestamp (optional, defaults to current time)
• roditid_base64url_signature - Signature

The system also supports NEP-413 standard authentication with the loginWithNEP413 function, which requires:

• message - Message to sign
• nonce - Nonce value
• recipient - Recipient identifier
• callbackUrl - Callback URL
• signature - Signature

Permission System

The permission system allows you to control access to protected routes based on the user's permissions. The permissions are stored in the JWT token and are checked by the validatePermissions middleware.

RODiT-based Permissions

RODiT-based permissions use the permissioned_routes property in the JWT token. This property contains an array of objects with the following structure:

[
  {
    "route": "^/api/admin/.*$",
    "methods": ["get", "post", "put", "delete"]
  },
  {
    "route": "^/api/users/.*$",
    "methods": ["get"]
  }
]

The permission validator checks if the requested route matches any of the patterns in the permissioned_routes array and if the HTTP method is allowed for that route.

Error Handling

All methods in this module handle errors gracefully and return appropriate HTTP status codes and error messages. Errors are also logged using the provided logger.

Logging

This module uses the provided logger to log important events. If no logger is provided, it uses the default logger from the SDK.

Security Considerations

• Tokens are transmitted via HTTP headers only, not cookies
• Tokens are validated on every request
• Permissions are checked on protected routes
• Session invalidation is supported via logout
• Token expiry is configurable

Backward Compatibility

For backward compatibility, the package also exports the original function names:

• authenticate_apicall - Original name for authenticate_apicall
• login_client - Original name for login
• logout_client - Original name for logout
• login_client_withnep413 - Original name for loginWithNEP413

License

Copyright (c) 2025 Discernible Inc. All rights reserved.

Full SDK API Reference (Consolidated)

This section consolidates the full SDK reference originally maintained in sdk/API-REFERENCE.md. Going forward, this README is the single source of truth.

Last Updated: Jun 29, 2025 — Streamlined logging section added and project structure updated.

Table of Contents

• RoditClient
• Authentication
• Session Management
• Token Management
• Configuration
• Utility Functions
• Middleware
• Logging
• Security Features
• Project Structure
• Error Handling

RoditClient

The main client class for interacting with RODiT services.

Constructor

const client = new RoditClient(options);

Parameters:

• options (Object, optional): Configuration options
  • credentialsFilePath (string, optional): Path to credentials file

Methods

init(options)

Initialize the client with credentials.

await client.init(options);

Parameters:

• options (Object, optional): Initialization options
  • credentialsPath (string, optional): Path to credentials file
  • token (string, optional): RODiT token
  • apiEndpoint (string, optional): API endpoint

Returns: Promise

login(options)

Authenticate and obtain a session token.

const loginResult = await client.login(options);

Parameters:

• options (Object, optional): Login options
  • roditId (string, optional): RODiT ID to use for login

Returns: Promise