@o3co/auth-provider-scaffold 0.0.0 → 0.18.0-rc.1

package/create-app/src/project.js

@@ -0,0 +1,76 @@
+/** What every generated project shares: the target's check, the workspace's packages and the app's entry. */
+import { execFileSync } from "node:child_process";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+export const kernel = "@mod/kernel";
+/** An npm package name, scoped or not: what the app's imports and dependencies can name. */
+const packageName = /^(@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
+/** Refuses, before anything is written, a name the app could not import or depend on. */
+export function namesPackages(names) {
+    for (const name of names) {
+        if (!packageName.test(name) || name.length > 214) {
+            throw new Error(`${name} is not a package name`);
+        }
+    }
+}
+/** A reading's catch: a missing file or directory reads as `absent`, and any other failure is thrown on. */
+export const missingAs = (absent) => (error) => {
+    if (error.code === "ENOENT")
+        return absent;
+    throw error;
+};
+/** A target that is missing or empty; one that holds anything is refused, never overwritten. */
+export async function vacant(target) {
+    const held = await readdir(target).catch(missingAs([]));
+    if (held.length > 0)
+        throw new Error(`${target} is not empty`);
+}
+/** Package directories by name, as the workspace definition places them. */
+export function workspacePackages(root) {
+    const listed = JSON.parse(execFileSync("pnpm", ["ls", "-r", "--json", "--depth", "-1"], { cwd: root, encoding: "utf8" }));
+    return new Map(listed.map((entry) => [entry.name, entry.path]));
+}
+/** Each name's dependency: a link to its workspace directory when given a workspace, else any version. */
+export function dependenciesOf(names, known) {
+    const dependencies = {};
+    for (const name of names) {
+        const dir = known?.get(name);
+        if (known && !dir)
+            throw new Error(`${name} is not in the workspace`);
+        dependencies[name] = dir ? `link:${dir}` : "*";
+    }
+    return dependencies;
+}
+/** The project's manifest, starting the app with `start`. */
+/** The pnpm the workspace builds with, so the lockfile reads alike in the image. */
+const pnpm = "pnpm@11.3.0";
+export const manifestOf = (start, dependencies) => `${JSON.stringify({
+    name: "auth-provider-app",
+    private: true,
+    type: "module",
+    packageManager: pnpm,
+    scripts: { start },
+    dependencies,
+}, null, "\t")}\n`;
+/** Fills a file of `templates/` by its `{{name}}` marks; a mark with no value stays as written. */
+export async function filled(template, fill) {
+    const text = await readFile(join(import.meta.dirname, "..", "templates", template), "utf8");
+    return text.replace(/\{\{(\w+)\}\}/g, (all, key) => fill[key] ?? all);
+}
+/** The app's entry, importing each module under what `importOf` names it (the workspace's name, unless published). */
+export const mainSource = (modules, importOf = (name) => name) => filled("main.ts.template", {
+    kernel: importOf(kernel),
+    imports: modules.map((name, i) => `import m${i} from "${importOf(name)}/module";`).join("\n"),
+    modules: modules.map((_, i) => `m${i}`).join(", "),
+});
+export const withKernel = (modules) => [
+    kernel,
+    ...modules.filter((name) => name !== kernel),
+];
+/** Writes every file, by its path in the project, once all are made: nothing is written for a project that fails. */
+export async function writeProject(target, files) {
+    for (const [path, text] of Object.entries(files)) {
+        await mkdir(dirname(join(target, path)), { recursive: true });
+        await writeFile(join(target, path), text);
+    }
+}

package/create-app/src/trial.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Trial settings for the app generated in `target`, by the modules its entry imports: the
+ * environment, and a local layer to put before the generated configuration. Keys are made fresh.
+ * The sections in `leave` get neither a variable nor a block, so the caller's own layer decides them.
+ */
+export declare function trialSettings(target: string, settings: {
+    readonly redisUrl: string;
+    readonly port?: number;
+    readonly deployment?: "single" | "multi";
+    readonly leave?: readonly string[];
+    /** Hosts the caller's own layer needs reached, merged into the trial's one outbound block. */
+    readonly allow?: readonly string[];
+    readonly plainLoopback?: readonly string[];
+}): Promise<{
+    readonly env: Record<string, string>;
+    readonly local: string;
+}>;

package/create-app/src/trial.js

@@ -0,0 +1,93 @@
+/** Trial settings for a generated app: values that boot it for a test or a conformance run, never for a deployment. */
+import { generateKeyPairSync, randomBytes } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { envName } from "./fragments.js";
+/** Every key an app may read from its variable, by section, with a trial value; one the app does not read is left unread. */
+function trialValues(redisUrl) {
+    const { privateKey } = generateKeyPairSync("ed25519");
+    return [
+        ["issuer", "url", "https://login.example.invalid"],
+        ["keys", "signing.kid", "signing-1"],
+        ["keys", "signing.alg", "EdDSA"],
+        ["keys", "signing.private-key", privateKey.export({ type: "pkcs8", format: "pem" }).toString()],
+        ["tokens", "revocation", "denylist"],
+        ["audit-http", "url", "https://audit.example.invalid/events"],
+        ["redis", "url", redisUrl],
+        ["redis", "replication", "none"],
+        ["store", "accept-volatile", "true"],
+        ["mail", "accept-unsent", "true"],
+        ["device-grant", "verification-uri", "https://login.example.invalid/device"],
+        ["mtls", "mode", "self-signed"],
+        ["mail-smtp", "host", "smtp.example.invalid"],
+        ["mail-smtp", "from", "auth@example.invalid"],
+    ];
+}
+/** The local layer's blocks, by section: each kept where the app composes the module it is for. */
+function trialBlocks(modules, deployment, port, added) {
+    const has = (name) => modules.includes(name);
+    const hosts = [
+        ...(has("users-http") ? ["ledger.example.invalid"] : []),
+        ...(has("audit-http") ? ["audit.example.invalid"] : []),
+        ...added.allow,
+    ];
+    const loopback = added.plainLoopback.length > 0
+        ? `, plain-loopback = [${added.plainLoopback.map((h) => JSON.stringify(h)).join(", ")}]`
+        : "";
+    const blocks = [
+        [true, "kernel", `kernel { deployment = ${deployment} }`],
+        [true, "audit", `audit { receivers = [${has("audit-http") ? "http" : "log"}] }`],
+        [
+            has("authorize"),
+            "authorize",
+            `authorize { login-page = "https://login.example.invalid/login" }`,
+        ],
+        [
+            has("users-http"),
+            "users-http",
+            `users-http { verify-url = "https://ledger.example.invalid/verify" }`,
+        ],
+        [
+            has("http"),
+            "http",
+            `http { public-origin = "https://login.example.invalid"${port ? `, port = ${port}` : ""} }`,
+        ],
+        [has("mtls"), "http", `http { client-certificate { dialect = pem, header = x-client-cert } }`],
+        [
+            has("outbound") && (hosts.length > 0 || loopback !== ""),
+            "outbound",
+            `outbound { allow = [${hosts.join(", ")}]${loopback} }`,
+        ],
+        // The trial's alone: a scene that proves no factor would stop at enrolment under required.
+        [has("mfa"), "mfa", "mfa { mode = optional }"],
+        // The relying party is the trial's public origin, where passkeys are composed.
+        [
+            has("webauthn"),
+            "webauthn",
+            'webauthn { rp-id = login.example.invalid, rp-name = "Trial", origins = ["https://login.example.invalid"] }',
+        ],
+        [
+            has("seal"),
+            "seal",
+            `seal { keys = [{ id = seal-1, key = "${randomBytes(32).toString("base64")}" }] }`,
+        ],
+    ];
+    return blocks.flatMap(([kept, section, block]) => (kept ? [{ section, block }] : []));
+}
+/**
+ * Trial settings for the app generated in `target`, by the modules its entry imports: the
+ * environment, and a local layer to put before the generated configuration. Keys are made fresh.
+ * The sections in `leave` get neither a variable nor a block, so the caller's own layer decides them.
+ */
+export async function trialSettings(target, settings) {
+    // The modules the entry imports, by their directory's name, as the workspace or a bundle names them.
+    const entry = await readFile(join(target, "src", "main.ts"), "utf8");
+    const modules = [...entry.matchAll(/from "(?:[^"]*\/)?([a-z0-9-]+)\/module"/g)].map((found) => found[1]);
+    const kept = (section) => !(settings.leave ?? []).includes(section);
+    const env = Object.fromEntries(trialValues(settings.redisUrl)
+        .filter(([section]) => kept(section))
+        .map(([section, key, value]) => [envName(`${section}.${key}`), value]));
+    const added = { allow: settings.allow ?? [], plainLoopback: settings.plainLoopback ?? [] };
+    const blocks = trialBlocks(modules, settings.deployment ?? "single", settings.port, added).filter((b) => kept(b.section));
+    return { env, local: `${blocks.map((b) => b.block).join("\n")}\n` };
+}

package/create-app/src/write-configuration.d.ts

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

package/create-app/src/write-configuration.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/** Writes the generated references, configuration and audit events, into the workspace this package lies in. */
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { auditReferenceFile, auditReferenceOf, declarationsIn } from "./audit-events.js";
+import { referenceFile, referenceOf, sectionsIn } from "./configuration.js";
+const root = join(import.meta.dirname, "..", "..", "..", "..");
+await mkdir(dirname(referenceFile(root)), { recursive: true });
+await writeFile(referenceFile(root), referenceOf(await sectionsIn(root)));
+await writeFile(auditReferenceFile(root), auditReferenceOf(await declarationsIn(root)));

package/create-app/templates/full-readme.md

@@ -0,0 +1,67 @@
+# Auth provider
+
+Generated by `create-app` from the full template. The modules' sections are configured from two places, both outside git:
+
+- the environment (`.env`): every key `{{application}}` reads;
+- the local layer (`{{local}}`): lists, values that span sections, and the keys no module's example holds (listed below).
+
+Each key not written keeps its module's default.
+
+## Start
+
+1. `pnpm install`
+2. Copy `.env.example` to `.env`, uncomment each line and replace its placeholder.
+3. Copy `{{localExample}}` to `{{local}}`, uncomment each key and replace its placeholders, and add the keys this guide names that neither file holds.
+4. `APP_CONFIG={{local}},{{application}} pnpm start`
+
+Both examples hold every value in a comment: a copy left as it is sets nothing, and boot refuses each key still needed.
+A secret's placeholder begins `REPLACE-`; uncommented as it is, boot refuses it. Delete the line of an optional key left unset.
+
+Until every key the modules need is written, the app writes each refusal on standard error, one per line, and exits 78.
+SIGTERM or SIGINT stops it, draining what is under way, within `kernel.stop-seconds` (30 by default); give an orchestrator a grace period longer than `kernel.stop-seconds`.
+
+## Docker
+
+1. `docker build -t auth-provider .`
+2. `docker run --env-file .env -e APP_CONFIG={{local}},{{application}} -v "$PWD/{{local}}:/app/{{local}}:ro" -p {{port}}:{{port}} auth-provider`
+
+Docker reads one line per variable from an env file: write a value of several lines, such as a PEM key, in the local layer instead.
+The image runs as a user other than root and installs the locked production dependencies only. `tini` runs as process 1, so `docker stop` reaches the app and it stops cleanly.
+Its health check asks `/_healthcheck`, which answers while the process runs; `/readyz` answers readiness, for a load balancer.
+
+## Keys read from the environment
+
+`{{application}}` reads each of these from its variable and holds no value.
+
+| Key | Variable | Placeholder |
+|---|---|---|
+{{settings}}
+
+## Keys written in the local layer
+
+{{written}}
+
+## Keys no example holds
+
+No module's example holds these: write them in the local layer when the deployment needs them.
+
+- `authorize.step-up-page`: the page that raises authentication (optional).
+- `http.trusted-proxies`: the proxies in front, whose forwarded addresses are believed.
+- `http.client-certificate`: where a proxy forwards client certificates, when a feature needs them.
+- `users.registered`: leave unset while the user ledger is composed; boot refuses both.
+- `users-http.credential`: the ledger's bearer token, when the ledger asks for one.
+- `mail-smtp.user`: the SMTP account, when the relay asks for one.
+- `mail-smtp.password`: the SMTP account's password.
+- `clients.registered`: a confidential client carries `sections.client-secret.hash`, a bcrypt or scrypt hash of its secret, never the secret itself.
+
+Write secrets in `.env` or the local layer only; neither goes into git or the image.
+
+## Adding a feature
+
+Generate again with `create-app <target> --add <feature>`, with one `--add` for each feature, and carry the configuration over.
+The feature comes with its wirings and bridges.
+Boot names what the added feature needs, and what cannot be composed.
+
+The template leaves these features out:
+
+{{optIns}}

package/create-app/templates/main.ts.template

@@ -0,0 +1,28 @@
+import { assemble, BootRefused, loadConfig } from "{{kernel}}";
+{{imports}}
+
+/** A refused boot: each refusal on its own line of standard error, then exit 78. */
+const refused = (error: unknown): never => {
+	if (!(error instanceof BootRefused)) throw error;
+	for (const refusal of error.refusals) {
+		process.stderr.write(`refused ${refusal.where}: ${refusal.reason}\n`);
+	}
+	process.exit(78);
+};
+
+const files = (process.env.APP_CONFIG ?? "config/application.conf").split(",");
+const app = await loadConfig({ files, env: process.env })
+	.then((config) => assemble({ modules: [{{modules}}], config }))
+	.catch(refused);
+// Taken before starting, so a signal while starting stops once started instead of killing.
+let started: Promise<void> = Promise.resolve();
+const stop = async () => {
+	await started.catch(() => undefined);
+	// Within the kernel's `stop-seconds`.
+	await app.stop();
+	process.exit(0);
+};
+process.once("SIGTERM", stop);
+process.once("SIGINT", stop);
+started = app.start();
+await started;

package/create-app/templates/pattern-readme.md

@@ -0,0 +1,70 @@
+# Auth provider: {{name}}
+
+{{use}}
+
+Generated by `create-app` from the pattern `{{name}}`. The modules' sections are configured from two places, both outside git:
+
+- the environment (`.env`): every key `{{application}}` reads;
+- the local layer (`{{local}}`): lists, values that span sections, and keys no module's example holds.
+
+Each key not written keeps its module's default.
+
+## This pattern
+
+{{card}}
+
+## Store, users, audit and mail
+
+{{chosen}}
+
+## Start
+
+1. `pnpm install`
+2. Copy `.env.example` to `.env`, uncomment each line and replace its placeholder.
+3. Copy `{{localExample}}` to `{{local}}`, uncomment each key and replace its placeholders, and add the keys this guide names that neither file holds.
+4. `APP_CONFIG={{local}},{{application}} pnpm start`
+
+Both examples hold every value in a comment: a copy left as it is sets nothing, and boot refuses each key still needed.
+A secret's placeholder begins `REPLACE-`; uncommented as it is, boot refuses it. Delete the line of an optional key left unset.
+
+Until every key the modules need is written, the app writes each refusal on standard error, one per line, and exits 78.
+SIGTERM or SIGINT stops it, draining what is under way, within `kernel.stop-seconds` (30 by default); give an orchestrator a grace period longer than `kernel.stop-seconds`.
+
+## Docker
+
+1. `docker build -t auth-provider .`
+2. `docker run --env-file .env -e APP_CONFIG={{local}},{{application}} -v "$PWD/{{local}}:/app/{{local}}:ro" -p {{port}}:{{port}} auth-provider`
+
+Docker reads one line per variable from an env file: write a value of several lines, such as a PEM key, in the local layer instead.
+The image runs as a user other than root and installs the locked production dependencies only. `tini` runs as process 1, so `docker stop` reaches the app and it stops cleanly.
+Its health check asks `/_healthcheck`, which answers while the process runs; `/readyz` answers readiness, for a load balancer.
+
+## Keys read from the environment
+
+`{{application}}` reads each of these from its variable and holds no value.
+
+| Key | Variable | Placeholder |
+|---|---|---|
+{{settings}}
+
+## Keys written in the local layer
+
+{{written}}
+
+## Values the operator decides
+
+- `kernel.deployment`: {{deployment}}
+- `tokens.revocation`: `denylist`, or `unsupported` to answer revocation as unsupported.
+- `audit.receivers`: the names of the audit receivers composed; `log` writes events to the log.
+
+Write secrets, such as the signing key, in `.env` or the local layer only; neither goes into git or the image.
+
+## Changing the pattern
+
+Generate again and carry the configuration over:
+
+- `create-app <target> --pattern {{name}} --add <feature>` adds a feature, with what it needs, its wirings and bridges.
+- `--axis <owner>=<adapter>` chooses an axis's adapter, or the owner itself.
+- `--login`, `--second-factor`, `--grants`, `--client-auth` and `--binding` each replace that group of features with the comma-separated list given.
+
+Boot names what a change needs, and what cannot be composed.