@flink-app/management-api-plugin

@flink-app/management-api-plugin

A Flink plugin that provides a secure management API system with built-in user authentication and module registration. This plugin enables other plugins to expose their own management endpoints through a centralized API.

Features

• Built-in user management system with authentication
• JWT-based token authentication
• Module-based architecture for extensibility
• Token or JWT authentication for all endpoints
• Automatic endpoint registration for modules
• MongoDB-backed user storage
• Password hashing with bcrypt

Installation

npm install @flink-app/management-api-plugin

Usage

Basic Setup

import { FlinkApp } from "@flink-app/flink";
import { managementApiPlugin } from "@flink-app/management-api-plugin";

function start() {
  new FlinkApp<AppContext>({
    name: "My app",
    plugins: [
      managementApiPlugin({
        token: "SECRET_TOKEN_USED_TO_COMMUNICATE_WITH_THE_API",
        jwtSecret: "JWT_SECRET_USED_TO_GENERATE_LOGGED_IN_TOKENS",
        modules: [],
        baseUrl: "/managementapi", // optional, defaults to /managementapi
      }),
    ],
  }).start();
}

Configuration Options

• token (required): Master token for initial authentication and user creation
• jwtSecret (required): Secret key for JWT token generation and verification
• modules (required): Array of management API modules to register
• baseUrl (optional): Base URL for all management API endpoints (defaults to /managementapi)

Authentication

The management API supports two authentication methods:

1. Master Token: Use the token specified during plugin initialization
2. JWT Token: Login with a management user to receive a JWT token

All requests (except login) must include one of these tokens in the management-token header.

Built-in User Management

The plugin includes a complete user management system:

Endpoints

• POST /managementapi/managementapiuser - Create new user
• POST /managementapi/managementapiuser/login - Login and receive JWT token
• GET /managementapi/managementapiuser - List all users
• GET /managementapi/managementapiuser/me - Get current user info
• GET /managementapi/managementapiuser/:userid - Get user by ID
• PUT /managementapi/managementapiuser/:userid - Update user
• DELETE /managementapi/managementapiuser/:userid - Delete user

Creating Your First User

To create the initial management user, make a POST request with the master token:

curl 'https://YOUR-API-URL/managementapi/managementapiuser' \
  -H 'management-token: SECRET_TOKEN_USED_TO_COMMUNICATE_WITH_THE_API' \
  -H 'Content-Type: application/json' \
  --data-raw '{"username":"admin","password":"secure_password"}'

Logging In

curl 'https://YOUR-API-URL/managementapi/managementapiuser/login' \
  -H 'Content-Type: application/json' \
  --data-raw '{"username":"admin","password":"secure_password"}'

This returns a JWT token that can be used in the management-token header for subsequent requests.

Creating Management Modules

Other plugins can create management modules that get registered with this plugin:

import { ManagementApiModule, ManagementApiType } from "@flink-app/management-api-plugin";
import { HttpMethod } from "@flink-app/flink";

const myModule: ManagementApiModule = {
  id: "my-module",
  type: ManagementApiType.custom, // or other types
  ui: true,
  uiSettings: {
    title: "My Module",
    icon: "",
    features: [],
  },
  endpoints: [
    {
      handler: myHandler,
      routeProps: {
        method: HttpMethod.get,
        path: "/list",
        docs: "List all items",
      },
    },
  ],
  data: {},
};

// Register with management API plugin
managementApiPlugin({
  token: "...",
  jwtSecret: "...",
  modules: [myModule],
});

Module Types

The plugin supports different module types via ManagementApiType:

• managementUser - User management (built-in)
• action - Action modules (used by management-actions-plugin)
• Custom types can be defined

API Endpoints

Get Management API Info

GET /managementapi

Returns information about all registered modules and their configuration.

TypeScript Support

The plugin includes full TypeScript definitions. To use the plugin context in your application:

import { managementApiPluginContext } from "@flink-app/management-api-plugin";

interface MyContext extends FlinkContext<managementApiPluginContext> {
  // your context
}

Database Requirements

This plugin requires MongoDB to be configured in your Flink app for user management. The plugin automatically creates a ManagementUserRepo repository.

Security Notes

• Always use strong, unique values for token and jwtSecret
• Store secrets in environment variables, never commit them to source control
• The master token provides full access - protect it carefully
• User passwords are automatically hashed using bcrypt
• The login endpoint is the only endpoint that doesn't require authentication

Example Integration with Management Actions Plugin

import { managementApiPlugin } from "@flink-app/management-api-plugin";
import { GetManagementModule } from "@flink-app/management-actions-plugin";

const actionsModule = GetManagementModule({
  ui: true,
  uiSettings: { title: "Actions" },
  actions: [
    // your actions
  ],
});

new FlinkApp<AppContext>({
  plugins: [
    managementApiPlugin({
      token: process.env.MANAGEMENT_TOKEN!,
      jwtSecret: process.env.JWT_SECRET!,
      modules: [actionsModule],
    }),
  ],
}).start();

License

MIT