hub-seeder is a one-shot command-line tool for bootstrapping preview and test environments of the FLAME Hub (PrivateAIM) — a privacy-preserving analytics infrastructure that runs distributed computations across institutional boundaries without moving the underlying data. It talks to the Hub and Authup APIs to idempotently create nodes and projects, provision a node's OAuth client, generate its key pair, and write the values.yaml / private_key.pem files consumed by the flame-node Helm chart.

It is published both as a library (seedNodeCommand / seedProjectCommand) and as the hub-seeder executable.

Features

• 🌱 Idempotent seeding — every step is "create if missing", and existing credentials are kept rather than replaced, so the seeder is safe to re-run against the same environment.
• 🧩 Deferred-failure step runner — runs every step, collects errors with full request/response detail, and reports a complete diagnostic in a single run.
• 🔑 Credential provisioning — generates an ECDH P-256 key pair and rotates the node's Authup OAuth client secret & redirect URI.
• 📄 Chart-ready output — writes values.yaml and private_key.pem for the flame-node Helm chart.
• 📦 Library or CLI — drive it programmatically, from the shell, or as a Docker image.

Quick Start

Prerequisites

• Node.js 22+
• A reachable Hub and Authup instance, plus confidential client credentials (CLIENT_ID / CLIENT_SECRET).

Install

npm install @privateaim/hub-seeder

Or run it ad-hoc, without installing:

npx @privateaim/hub-seeder seed-node --node-name my-node

Commands

All configuration is provided via environment variables (see Configuration); the only CLI flag is --node-name.

| Command | Description | |---------|-------------| | seed-node 🌐 | Provision a node on the Hub and write credential files for the flame-node chart | | seed-project 📁 | Create a project on the Hub (if missing) |

seed-node

Creates the node (if missing), assigns the default registry, ensures the node has an ECDH P-256 key pair and an Authup OAuth client (secret + redirect URI derived from NODE_URL), optionally assigns it to a project, and — only if every step succeeded — writes values.yaml, clientSecret and private_key.pem to OUTPUT_DIR.

Credentials are kept across runs. A node that already has a public key keeps its key pair, and the OAuth client secret is read back from Authup and reused. The seeder can therefore be re-run against a provisioned node without invalidating the credentials the node is running with. Two consequences follow:

• private_key.pem is written only when this run generated the key pair. Its absence means "the node keeps the key it already holds" — callers must not treat that as an empty key.
• If Authup stores the client secret hashed or encrypted it cannot be read back, so a new secret is set and the node has to pick up the rotated credential.

Set ROTATE_CREDENTIALS=true to replace both instead. This is the recovery path when the credentials on the node side were lost: the Hub only ever stores the public half of the key pair, so a lost private key cannot be recovered — only replaced.

HUB_URL=https://hub.example AUTHUP_URL=https://authup.example \
CLIENT_ID=seeder CLIENT_SECRET=*** \
NODE_TYPE=default NODE_URL=https://my-node.example OUTPUT_DIR=./out \
  hub-seeder seed-node --node-name my-node

seed-project

Creates a project on the Hub (if missing).

HUB_URL=https://hub.example AUTHUP_URL=https://authup.example \
CLIENT_ID=seeder CLIENT_SECRET=*** \
PROJECT_NAME=my-project \
  hub-seeder seed-project

Configuration

| Variable | Used by | Description | |----------|---------|-------------| | HUB_URL | both | Hub API base URL | | AUTHUP_URL | both | Authup API base URL | | REALM | both | Authup realm for the client-credentials token (default master) | | CLIENT_ID | both (required) | Confidential client id used to authenticate | | CLIENT_SECRET | both (required) | Confidential client secret | | NODE_NAME | seed-node | Node name to create/find (overridden by --node-name) | | NODE_TYPE | seed-node | default or aggregator (default default) | | NODE_URL | seed-node | Node base URL; used to derive the OAuth redirect URI (<url>/**) | | OUTPUT_DIR | seed-node | Directory for values.yaml / clientSecret / private_key.pem (default .) | | ROTATE_CREDENTIALS | seed-node | Replace the node key pair and OAuth client secret instead of keeping them (default false) | | PROJECT_NAME | seed-project (required), seed-node (optional) | Project to create / to assign the node to | | PROJECT_DISPLAY_NAME | seed-project | Project display name (defaults to PROJECT_NAME) |

[!WARNING] For self-signed preview/test environments the CLI disables TLS certificate verification (NODE_TLS_REJECT_UNAUTHORIZED=0). This is intentional for that use case — do not rely on it in production contexts.

Programmatic Usage

The core commands are decoupled from the CLI and accept typed options:

import { seedNodeCommand, seedProjectCommand } from '@privateaim/hub-seeder';

await seedNodeCommand({ nodeName: 'my-node', outputDir: './out' });

await seedProjectCommand({ projectName: 'my-project' });

Environment variables (HUB_URL, AUTHUP_URL, CLIENT_ID, …) are read the same way as for the CLI.

Docker

The CLI ships as a Docker image with the binary as its entrypoint — append the subcommand and provide the environment:

docker run --env-file .env <image> seed-node

Built With

hub-seeder builds on open-source libraries from the FLAME / PrivateAIM ecosystem: Authup (identity & access), citty (CLI framework), and the @privateaim/* kits (Hub clients, crypto & server utilities).

Contributing

Before starting to work on a pull request, it is important to review the guidelines for contributing and the code of conduct. These guidelines will help to ensure that contributions are made effectively and are accepted.

License

Made with 💚

Published under MIT License.