create-buntubi 0.0.0-stage → 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ibrahima Touré
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/**
+ * `npm create buntubi@latest [folder]`: a Buntubi project run with Docker, with fresh secrets,
+ * ready for `pnpm run setup`. Every question has a flag, so it also runs unattended:
+ *
+ *   --name "Acme"  --slug acme  --url local | https://id.acme.com  --console-url  --portal-url
+ *   --email log | resend  --resend-key re_...  --email-from "Acme <no-reply@acme.com>"  --yes
+ */
+import { randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { generate, SLUG } from './generate.js';
+const here = dirname(fileURLToPath(import.meta.url));
+const own = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8'));
+const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+        name: { type: 'string' },
+        slug: { type: 'string' },
+        url: { type: 'string' },
+        'console-url': { type: 'string' },
+        'portal-url': { type: 'string' },
+        email: { type: 'string' },
+        'resend-key': { type: 'string' },
+        'email-from': { type: 'string' },
+        yes: { type: 'boolean', short: 'y' },
+    },
+});
+const prompt = !values.yes && process.stdin.isTTY ? createInterface({ input: process.stdin, output: process.stdout }) : null;
+async function ask(question, fallback) {
+    if (!prompt)
+        return fallback;
+    return (await prompt.question(`${question} (${fallback}) `)).trim() || fallback;
+}
+const toSlug = (text) => text.normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').replace(/^(\d)/, 'p$1');
+/** An https origin, the only kind a public provider accepts. */
+function origin(text, what) {
+    const url = new URL(text);
+    if (url.protocol !== 'https:')
+        throw new Error(`${what} must be https: ${text}`);
+    return url.origin;
+}
+/** On this machine, or at public addresses: the provider's, then the console's and the portal's beside it. */
+async function chooseAddress() {
+    const answer = values.url ?? (await ask('Public address of the provider, or local?', 'local'));
+    if (answer === 'local')
+        return { local: true };
+    const provider = origin(answer, 'the provider address');
+    const host = new URL(provider).host;
+    const consoleUrl = origin(values['console-url'] ?? (await ask('Address of the console?', `https://console.${host}`)), 'the console address');
+    const portalUrl = origin(values['portal-url'] ?? (await ask('Address of the developer portal?', `https://portal.${host}`)), 'the portal address');
+    return { local: false, provider, console: consoleUrl, portal: portalUrl };
+}
+/** To the log while it runs only here; through Resend once people outside can sign up. */
+async function chooseEmail(isPublic) {
+    const answer = values.email ?? (await ask(isPublic ? 'Email through resend?' : 'Email: log (codes in the log) or resend?', isPublic ? 'resend' : 'log'));
+    if (answer === 'log')
+        return { through: 'log' };
+    if (answer !== 'resend')
+        throw new Error(`--email is log or resend, not ${answer}`);
+    const key = values['resend-key'] ?? (await ask('Resend API key?', ''));
+    const from = values['email-from'] ?? (await ask('Sender, on a domain verified at Resend?', ''));
+    if (!key || !from)
+        throw new Error('Resend needs its API key and a sender');
+    return { through: 'resend', key, from };
+}
+async function main() {
+    const folder = resolve(positionals[0] ?? (await ask('Folder for the project?', 'my-identity')));
+    const name = values.name ?? (await ask('Name on the sign-in pages?', basename(folder)));
+    const slug = values.slug ?? (await ask('Short id?', toSlug(name) || 'identity'));
+    if (!SLUG.test(slug))
+        throw new Error(`"${slug}" must be lowercase letters, digits and hyphens, starting with a letter`);
+    const address = await chooseAddress();
+    const email = await chooseEmail(!address.local);
+    prompt?.close();
+    if (existsSync(folder) && readdirSync(folder).length > 0)
+        throw new Error(`${folder} is not empty`);
+    const files = generate({ name, slug, address, email }, own.version, join(here, '..', 'templates'), () => randomBytes(32).toString('base64url'));
+    for (const [path, content] of files) {
+        mkdirSync(dirname(join(folder, path)), { recursive: true });
+        writeFileSync(join(folder, path), content);
+    }
+    console.log(`\n${name} is ready in ${folder}. Next:\n\n  cd ${folder}\n  pnpm install\n  pnpm run setup\n  pnpm up\n`);
+    return 0;
+}
+main().then((code) => {
+    process.exitCode = code;
+}, (error) => {
+    prompt?.close();
+    console.error(`create-buntubi: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+});

package/dist/generate.d.ts

@@ -0,0 +1,32 @@
+export interface Choices {
+    /** The platform's name, on its sign-in pages. */
+    name: string;
+    /** Lowercase letters, digits and hyphens: the compose project and the package name. */
+    slug: string;
+    /** Where people reach it: on this machine, or at public https addresses. */
+    address: {
+        local: true;
+    } | {
+        local: false;
+        provider: string;
+        console: string;
+        portal: string;
+    };
+    /** How it sends email: to its log (local only), or through Resend. */
+    email: {
+        through: 'log';
+    } | {
+        through: 'resend';
+        key: string;
+        from: string;
+    };
+}
+/** The three addresses the project answers at. */
+export declare const addressesOf: (choices: Choices) => {
+    provider: string;
+    console: string;
+    portal: string;
+};
+export type Files = Map<string, string>;
+export declare const SLUG: RegExp;
+export declare function generate(choices: Choices, version: string, templates: string, secret: () => string): Files;

package/dist/generate.js

@@ -0,0 +1,108 @@
+/**
+ * A new Buntubi project, as files: every path it starts with and its contents. Nothing here
+ * touches the disk, so a project can be checked before it is written.
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+/** The addresses on this machine: the console and the portal share the provider's network. */
+const LOCAL = { provider: 'http://localhost:5010', console: 'http://localhost:3420', portal: 'http://localhost:3410' };
+/** The three addresses the project answers at. */
+export const addressesOf = (choices) => (choices.address.local ? LOCAL : choices.address);
+export const SLUG = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+/** Template files are stored with a leading underscore where npm would drop a dotfile. */
+const DOTFILE = /(^|\/)_(gitignore)$/;
+export function generate(choices, version, templates, secret) {
+    if (!SLUG.test(choices.slug))
+        throw new Error(`"${choices.slug}" must be lowercase letters, digits and hyphens, starting with a letter`);
+    // The provider refuses to start on a public address with email that only goes to its log.
+    if (!choices.address.local && choices.email.through === 'log')
+        throw new Error('a public address needs email that leaves the machine: choose resend');
+    const at = addressesOf(choices);
+    const files = new Map();
+    for (const file of walk(templates)) {
+        const path = relative(templates, file).replace(DOTFILE, '$1.$2');
+        const text = readFileSync(file, 'utf8')
+            .replaceAll('{{name}}', choices.name)
+            .replaceAll('{{slug}}', choices.slug)
+            .replaceAll('{{version}}', version)
+            .replaceAll('{{consoleUrl}}', at.console)
+            .replaceAll('{{portalUrl}}', at.portal);
+        files.set(path, text);
+    }
+    files.set('package.json', `${JSON.stringify({
+        name: choices.slug,
+        private: true,
+        type: 'module',
+        scripts: { setup: 'buntubi setup', build: 'buntubi build', up: 'buntubi up', down: 'buntubi down' },
+        devDependencies: { '@buntubi/sdk': `^${version}` },
+    }, null, 2)}\n`);
+    files.set('pnpm-workspace.yaml', 'packages:\n  - plugins/*/ui\n');
+    // Docker copies plugins/ into the provider's image and mounts ui-plugins/: both must exist.
+    files.set('plugins/.gitkeep', '');
+    files.set('ui-plugins/.gitkeep', '');
+    for (const [file, entries] of envFiles(choices, secret)) {
+        files.set(file, env(entries, true));
+        files.set(`${file}.example`, env(entries, false));
+    }
+    return files;
+}
+function walk(dir) {
+    return readdirSync(dir).flatMap((entry) => {
+        const path = join(dir, entry);
+        return statSync(path).isDirectory() ? walk(path) : [path];
+    });
+}
+function env(entries, withValues) {
+    const secret = /SECRET|PASSWORD|KEY$/;
+    return `${entries.map(([key, value, comment]) => `${comment ? `# ${comment}\n` : ''}${key}=${withValues || !secret.test(key) ? value : ''}`).join('\n')}\n`;
+}
+function envFiles(choices, secret) {
+    const at = addressesOf(choices);
+    const email = choices.email.through === 'log'
+        ? [['IDP_EMAIL_TEST_MODE', 'true', 'Local only: emails, sign-in codes included, go to the log.']]
+        : [
+            ['IDP_EMAIL_TEST_MODE', 'false', ''],
+            ['IDP_RESEND_API_KEY', choices.email.key, 'Email through Resend: the API key from resend.com.'],
+            ['IDP_EMAIL_FROM', choices.email.from, 'The sender, on a domain verified at Resend.'],
+        ];
+    return [
+        ['.env', [['POSTGRES_PASSWORD', secret(), 'Read by docker compose: the database password, shared by postgres and the provider.']]],
+        [
+            'identity.env',
+            [
+                ['IDP_ISSUER', at.provider, "The provider's address; every IDP_* setting is documented in Buntubi."],
+                ['IDP_SECRET_KEY', secret(), 'Never change it: it signs sessions and encrypts authenticator secrets.'],
+                ['IDP_SECURE_COOKIES', 'true', ''],
+                ...email,
+                ['IDP_RATE_LIMIT_STORAGE', 'memory://', 'One provider process; several need a shared store (redis://...).'],
+                ['IDP_BRAND_NAME', choices.name, ''],
+                ['IDP_PLUGINS', '[]', 'The provider plugins turned on, by id, in order; `buntubi add plugin` adds to it.'],
+                ['IDP_GOOGLE_CLIENT_ID', '', 'Sign-in with Google: an OAuth client from Google Cloud, callback <issuer>/signin/google/callback; list google under [social] in platform.toml.'],
+                ['IDP_GOOGLE_CLIENT_SECRET', '', ''],
+                ['IDP_GITHUB_CLIENT_ID', '', 'Sign-in with GitHub: an OAuth App, or a GitHub App with Email addresses read-only; callback <issuer>/signin/github/callback.'],
+                ['IDP_GITHUB_CLIENT_SECRET', '', ''],
+            ],
+        ],
+        [
+            'console.env',
+            [
+                ['IDP_URL', at.provider, ''],
+                ['APP_URL', at.console, ''],
+                ['PORTAL_URL', at.portal, ''],
+                ['CONSOLE_CLIENT_ID', 'owner-console', ''],
+                ['CONSOLE_CLIENT_SECRET', '', 'Written by `pnpm run setup`.'],
+                ['SESSION_SECRET', secret(), 'Encrypts the session cookie: at least 32 characters.'],
+            ],
+        ],
+        [
+            'portal.env',
+            [
+                ['IDP_URL', at.provider, ''],
+                ['APP_URL', at.portal, ''],
+                ['PORTAL_CLIENT_ID', 'developer-portal', ''],
+                ['PORTAL_CLIENT_SECRET', '', 'Written by `pnpm run setup`.'],
+                ['SESSION_SECRET', secret(), 'Encrypts the session cookie: at least 32 characters.'],
+            ],
+        ],
+    ];
+}

package/package.json

@@ -1,6 +1,24 @@
 {
   "name": "create-buntubi",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.7.0",
+  "description": "Start an identity provider on Buntubi, run with Docker",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "create-buntubi": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }

package/templates/README.md

@@ -0,0 +1,17 @@
+# {{name}}
+
+An identity provider on Buntubi, run with Docker.
+
+```sh
+pnpm install
+pnpm run setup  # once: its database, a signing key, the first admin, the apps
+pnpm up         # the provider on :5010, the console on :3420, the portal on :3410
+pnpm down
+```
+
+On public addresses, a reverse proxy sends each one to its port with https: the provider's to
+5010, the console's to 3420, the portal's to 3410.
+
+Its apps are in `platform.toml`, its settings in the `.env` files, written with fresh secrets
+when the project was made. `pnpm exec buntubi add plugin <id>` adds a plugin of its own in
+`plugins/`; `pnpm build` builds the plugins' pages into `ui-plugins/`.

package/templates/_gitignore

@@ -0,0 +1,13 @@
+node_modules/
+dist/
+.env
+*.env
+!*.env.example
+keys/
+ui-plugins/*
+!ui-plugins/.gitkeep
+*.dump
+# Written by the UI plugin build.
+fluixi.d.ts
+*.log
+.DS_Store

package/templates/compose.yaml

@@ -0,0 +1,96 @@
+# {{name}}'s identity provider: Buntubi from its published images, its provider built with this
+# project's plugins (provider.Dockerfile), their UI halves mounted from ui-plugins/.
+#
+# `pnpm run setup` the first time (database, signing key, the first admin, the apps in
+# platform.toml), then `pnpm up` and `pnpm down`. The console and the portal share the
+# provider's network namespace, so http://localhost:5010, :3420 and :3410 mean the same thing to
+# the browser and to the containers.
+#
+# Upgrading: change the version below and in provider.Dockerfile, then `pnpm run setup` again (it
+# only adds what is missing) and `pnpm up`.
+
+name: {{slug}}
+
+services:
+  postgres:
+    image: postgres:17-alpine
+    environment:
+      POSTGRES_USER: idp
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}
+      POSTGRES_DB: idp
+    volumes:
+      - postgres:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD", "pg_isready", "-U", "idp", "-d", "idp"]
+      interval: 5s
+      retries: 10
+
+  provider:
+    build:
+      context: .
+      dockerfile: provider.Dockerfile
+    image: {{slug}}-provider
+    env_file: identity.env
+    environment:
+      IDP_DATABASE_URL: postgresql+psycopg://idp:${POSTGRES_PASSWORD}@postgres:5432/idp
+      IDP_SIGNING_KEYS_DIR: /keys
+    # The issuer is http://localhost:5010, so the provider listens there inside the namespace too.
+    command: ["gunicorn", "--bind", "0.0.0.0:5010", "--access-logfile", "-", "buntubi.app:create_app()"]
+    healthcheck:
+      test: ["CMD", "python", "-c", "import urllib.request,sys; sys.exit(urllib.request.urlopen('http://127.0.0.1:5010/healthz', timeout=4).status != 200)"]
+      interval: 10s
+      start_period: 20s
+    volumes:
+      - ./keys:/keys
+      - &ui-plugins ./ui-plugins:/app/ui-plugins:ro
+    ports:
+      - "5010:5010"
+      - "3420:3420"
+      - "3410:3410"
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    depends_on:
+      postgres:
+        condition: service_healthy
+
+  # Sends organization events to the apps' webhooks.
+  webhooks:
+    image: {{slug}}-provider
+    env_file: identity.env
+    environment:
+      IDP_DATABASE_URL: postgresql+psycopg://idp:${POSTGRES_PASSWORD}@postgres:5432/idp
+      IDP_SIGNING_KEYS_DIR: /keys
+      IDP_PLUGINS_SYNC_ON_START: "false"
+    command: ["flask", "webhooks", "deliver"]
+    # The image checks its web server, which this process does not run.
+    healthcheck:
+      disable: true
+    volumes:
+      - ./keys:/keys
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    restart: unless-stopped
+    depends_on:
+      provider:
+        condition: service_started
+
+  console:
+    image: ghcr.io/buntubi/idp-console:{{version}}
+    env_file: console.env
+    volumes:
+      - *ui-plugins
+    network_mode: service:provider
+    depends_on:
+      - provider
+
+  portal:
+    image: ghcr.io/buntubi/idp-portal:{{version}}
+    env_file: portal.env
+    volumes:
+      - *ui-plugins
+    network_mode: service:provider
+    depends_on:
+      - provider
+
+volumes:
+  postgres:

package/templates/platform.toml

@@ -0,0 +1,36 @@
+# {{name}}'s apps, created by `pnpm run setup`. Running it again only adds what is missing. A
+# confidential app's secret is written into the env file `secret` names, relative to this file,
+# and never printed. Add the apps that sign in through this provider below.
+
+[[apps]]
+client_id = "owner-console"
+name = "Owner console"
+redirect_uris = ["{{consoleUrl}}/auth/callback"]
+post_logout_redirect_uris = ["{{consoleUrl}}/"]
+scope = "openid profile email admin"
+homepage_url = "{{consoleUrl}}/"
+backchannel_logout_uri = "{{consoleUrl}}/auth/backchannel-logout"
+secret = { file = "console.env", key = "CONSOLE_CLIENT_SECRET" }
+
+[[apps]]
+client_id = "developer-portal"
+name = "Developer portal"
+redirect_uris = ["{{portalUrl}}/auth/callback"]
+post_logout_redirect_uris = ["{{portalUrl}}/"]
+scope = "openid profile email developer"
+homepage_url = "{{portalUrl}}/"
+backchannel_logout_uri = "{{portalUrl}}/auth/backchannel-logout"
+secret = { file = "portal.env", key = "PORTAL_CLIENT_SECRET" }
+
+# Social sign-in, once IDP_GOOGLE_* or IDP_GITHUB_* is set in identity.env.
+# [social]
+# providers = ["google", "github"]
+
+# Whether people can make an account; invited addresses always can.
+# [signup]
+# open = true
+# terms_version = "2026-10"     # asks people to accept the terms at IDP_BRAND_TERMS_URL
+
+# The profile fields asked of people: "hidden" (the default), "optional" or "required".
+# [profile]
+# birthdate = "optional"

package/templates/provider.Dockerfile

@@ -0,0 +1,10 @@
+# The provider: Buntubi's published image with this project's provider plugins installed, each
+# one's plugins/<id>/provider package. Without plugins it is the published image as it is.
+FROM ghcr.io/buntubi/idp-provider:{{version}}
+USER root
+COPY plugins /plugins
+RUN for plugin in /plugins/*/provider; do \
+      if [ -f "$plugin/pyproject.toml" ]; then pip install --no-cache-dir "$plugin"; fi; \
+    done \
+ && rm -rf /plugins
+USER idp

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.