@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

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

Usage

$3

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

function start() {
new FlinkApp({
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:

$3

- 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

$3

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

`bash
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"}'
`

$3

`bash
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:

`typescript
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

$3

`
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:

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

interface MyContext extends FlinkContext {
// 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

`typescript
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({
plugins: [
managementApiPlugin({
token: process.env.MANAGEMENT_TOKEN!,
jwtSecret: process.env.JWT_SECRET!,
modules: [actionsModule],
}),
],
}).start();
``

License

MIT