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

package/create-app/src/full.js

@@ -0,0 +1,18 @@
+/** The full template: what `combinations` composes in full, with the features added. */
+import { full, optIns } from "@o3co/auth-provider-scaffold/combinations";
+import { writeDeployment } from "./deployment.js";
+import { namesPackages } from "./project.js";
+export async function generateFull(plan) {
+    const add = plan.add ?? [];
+    namesPackages(add);
+    const modules = full(add);
+    await writeDeployment(plan, modules, {
+        template: "full-readme.md",
+        fill: {
+            optIns: optIns()
+                .filter((name) => !add.includes(name))
+                .map((name) => `- \`${name}\``)
+                .join("\n"),
+        },
+    });
+}

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

@@ -0,0 +1,21 @@
+import { type PatternPlan } from "./pattern.js";
+/** A project assembling the modules named. */
+export interface ModulesPlan {
+    readonly target: string;
+    /** Package names whose `./module` the app assembles, in order; their default wirings and bridges come along. */
+    readonly modules: readonly string[];
+    /** When set, dependencies link to this workspace instead of a registry. */
+    readonly workspace?: string;
+    /** The package whose `./module` contributes the app's log sink. */
+    readonly sink?: string;
+}
+/** A project from the full template: what `combinations` composes in full, with the features added (the pattern `full`). */
+export interface FullPlan {
+    readonly target: string;
+    readonly template: "full";
+    /** Features of the workspace to compose beside the template's, with their wirings and bridges. */
+    readonly add?: readonly string[];
+    readonly workspace?: string;
+}
+export type Plan = ModulesPlan | FullPlan | PatternPlan;
+export declare function generate(given: Plan): Promise<void>;

package/create-app/src/generate.js

@@ -0,0 +1,33 @@
+import { resolve } from "node:path";
+import { completed } from "@o3co/auth-provider-scaffold/combinations";
+import { kernelConfig } from "@o3co/auth-provider-foundation/kernel";
+import { generateFull } from "./full.js";
+import { packagesFor } from "./packages.js";
+import { generatePattern } from "./pattern.js";
+import { fullName } from "./patterns/patterns.js";
+import { mainSource, manifestOf, namesPackages, vacant, withKernel, writeProject, } from "./project.js";
+const defaultSink = "@mod/log-stdout";
+export async function generate(given) {
+    // One path, resolved once, is both checked and written to: `missing/..` must not pass as empty.
+    const plan = { ...given, target: resolve(given.target) };
+    if ("template" in plan) {
+        if (plan.template !== fullName)
+            return generatePattern(plan);
+        if ("axes" in plan || "features" in plan)
+            throw new Error("full takes no axes or groups");
+        return generateFull({ ...plan, template: fullName });
+    }
+    const sink = plan.sink ?? defaultSink;
+    namesPackages([...plan.modules, sink]);
+    await vacant(plan.target);
+    const asked = completed(plan.modules);
+    // Without a sink, the app's log lines would go nowhere.
+    const modules = asked.includes(sink) ? asked : [...asked, sink];
+    const packages = packagesFor(plan);
+    await writeProject(plan.target, {
+        "package.json": manifestOf("node src/main.ts", packages.dependencies(withKernel(modules))),
+        "src/main.ts": await mainSource(modules, packages.importOf),
+        "config/application.conf": `${JSON.stringify(kernelConfig(), null, "\t")}\n`,
+        ".gitignore": "node_modules/\nconfig/local*.conf\n",
+    });
+}

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

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

package/create-app/src/main.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from "./command.js";
+process.exitCode = await run(process.argv.slice(2));

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

@@ -0,0 +1,17 @@
+import { type Fragment } from "./fragments.js";
+/** Where the packages an app assembles come from, and how the app names them. */
+export interface Packages {
+    /** Each name's section example, in the order given; a package without one is skipped. */
+    fragments(names: readonly string[]): Promise<Fragment[]>;
+    /** What the app depends on to have the names. */
+    dependencies(names: readonly string[]): Record<string, string>;
+    /** What the app imports a name's entries under. */
+    importOf(name: string): string;
+}
+/**
+ * The packages as published, from the index, where create-app is built into a bundle and no
+ * workspace is given; else the workspace's, linked when one is given.
+ */
+export declare function packagesFor(plan: {
+    readonly workspace?: string;
+}, index?: string): Packages;

package/create-app/src/packages.js

@@ -0,0 +1,40 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fragmentsIn, fragmentsOf } from "./fragments.js";
+import { dependenciesOf, workspacePackages } from "./project.js";
+/** The index distribution writes at the root of the bundle create-app is built into. */
+const bundleIndex = join(import.meta.dirname, "..", "..", "index.json");
+/** The workspace this package lies in, where `combinations` reads the modules it composes. */
+const ownWorkspace = join(import.meta.dirname, "..", "..", "..", "..");
+/**
+ * The packages as published, from the index, where create-app is built into a bundle and no
+ * workspace is given; else the workspace's, linked when one is given.
+ */
+export function packagesFor(plan, index = bundleIndex) {
+    if (plan.workspace === undefined && existsSync(index)) {
+        return publishedIn(JSON.parse(readFileSync(index, "utf8")));
+    }
+    const dirs = workspacePackages(resolve(plan.workspace ?? ownWorkspace));
+    return {
+        fragments: (names) => fragmentsIn(names.flatMap((name) => dirs.get(name) ?? [])),
+        dependencies: (names) => dependenciesOf(names, plan.workspace ? dirs : undefined),
+        importOf: (name) => name,
+    };
+}
+function publishedIn(index) {
+    const byName = new Map(index.packages.map((entry) => [entry.name, entry]));
+    const found = (name) => {
+        const entry = byName.get(name);
+        if (!entry)
+            throw new Error(`${name} is no published package`);
+        return entry;
+    };
+    return {
+        fragments: async (names) => fragmentsOf(names.flatMap((name) => {
+            const { fragment } = found(name);
+            return fragment === undefined ? [] : [{ from: name, text: fragment }];
+        })),
+        dependencies: (names) => Object.fromEntries(names.map((name) => [found(name).package, index.version])),
+        importOf: (name) => found(name).entry,
+    };
+}

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

@@ -0,0 +1,9 @@
+import { type Choice, type Pattern } from "./patterns/pattern.js";
+export interface PatternPlan extends Choice {
+    readonly target: string;
+    /** The pattern's name. */
+    readonly template: string;
+    readonly workspace?: string;
+}
+/** Generates the pattern the plan names, or the one given (a test's). */
+export declare function generatePattern(plan: PatternPlan, pattern?: Pattern): Promise<void>;

package/create-app/src/pattern.js

@@ -0,0 +1,31 @@
+/** A pattern's project: what `combinations` composes from the pattern's selection and the operator's choice. */
+import { composed } from "@o3co/auth-provider-scaffold/combinations";
+import { writeDeployment } from "./deployment.js";
+import { chosenLines } from "./patterns/chosen.js";
+import { oneInstance, selectionOf } from "./patterns/pattern.js";
+import { cardOf, patternNamed } from "./patterns/patterns.js";
+import { namesPackages } from "./project.js";
+/** Generates the pattern the plan names, or the one given (a test's). */
+export async function generatePattern(plan, pattern = patternNamed(plan.template)) {
+    const selection = selectionOf(pattern, plan);
+    namesPackages([
+        ...Object.values(selection.features).flat(),
+        ...Object.entries(selection.axes ?? {}).flat(),
+        ...(selection.add ?? []),
+    ]);
+    const modules = composed(selection);
+    const deployment = oneInstance(selection)
+        ? "`single`: the store is kept in this process, so the deployment runs as one instance."
+        : "`single` for one instance, `multi` for several.";
+    const card = await cardOf(pattern.name);
+    await writeDeployment(plan, modules, {
+        template: "pattern-readme.md",
+        fill: {
+            name: pattern.name,
+            use: pattern.use,
+            card,
+            chosen: chosenLines(modules).join("\n"),
+            deployment,
+        },
+    });
+}

package/create-app/src/patterns/README.md

@@ -0,0 +1,26 @@
+# patterns
+
+## Responsibilities
+- Holds the patterns: each a deployment's use and the selection that composes it, in one file (`<name>.ts`) with a card of at most 10 lines (`<name>.md`).
+- Merges the operator's choice into a pattern's selection, and says when its store keeps the deployment to one instance.
+
+## Not here
+- What a selection composes (needs, axes, wirings, bridges) and checking its names and kinds: `combinations`.
+- The files generated and their configuration: `create-app`'s.
+- Running the conformance areas against a pattern's app: the conformance base.
+
+## Offers
+- `patterns()`: each pattern's name, use, conformance areas and the features conformance adds for its run alone (a small reviewed list, so its core is under test), `full` last (the full template itself, with no file here).
+- The pattern of a name, and its card without the title. A name not known is refused, naming those that are.
+- `selectionOf(pattern, choice)`: the features every pattern composes, the pattern's groups with the operator's in their place, the pattern's axes under the operator's, and the features added.
+- The groups: `login`, `second-factor`, `grants`, `client-auth`, `binding`.
+
+## Invariants
+- A pattern names only the features that decide its use; the foundations come with what needs them.
+- A pattern writes no configuration value: its card names the keys the deployment provides for its use; what the store, users, audit and mail chosen ask is told from the modules composed (`chosen`), whatever the pattern's default.
+- A group the operator names that is not one of the groups is refused, naming it.
+- The memory store (`store` chosen as its own axis) means one instance.
+- Module names are written here and in the operator's flags only.
+
+## Depends on
+- `combinations` (the selection's shape).

package/create-app/src/patterns/a2a.d.ts

@@ -0,0 +1,2 @@
+import type { Pattern } from "./pattern.js";
+export declare const a2a: Pattern;

package/create-app/src/patterns/a2a.js

@@ -0,0 +1,18 @@
+export const a2a = {
+    name: "a2a",
+    use: "Tokens between services, with no user and no login: clients authenticate by a signed " +
+        "assertion or a secret, take client credentials or a JWT bearer grant from a trusted issuer, " +
+        "and may bind their tokens to a certificate (mTLS) or a key (DPoP).",
+    axes: {
+        "@mod/store": "@mod/store",
+        "@mod/audit": "@mod/audit",
+        "@mod/mail": "@mod/mail",
+    },
+    features: {
+        grants: ["@mod/jwt-bearer"],
+        "client-auth": ["@mod/client-assertion"],
+        binding: ["@mod/mtls", "@mod/dpop"],
+    },
+    areas: ["keys", "oauth", "mtls", "ops"],
+    conformanceAdd: ["@mod/token-exchange"],
+};

package/create-app/src/patterns/a2a.md

@@ -0,0 +1,7 @@
+# a2a
+
+- Use: services only; no user, session or login. Client credentials and the JWT bearer grant (`jwt-bearer.issuers`), clients by `private_key_jwt` or a secret, tokens bound by mTLS or DPoP.
+- The deployment provides the proxy that forwards client certificates (`http.client-certificate`), and lets the issuers' and clients' key sets be fetched (`outbound.allow`).
+- `--add @mod/token-exchange` also brings refresh, session, session tokens and the code grant; `--add @mod/clients-cimd` brings authorization, consent, acr, the code grant, login gates, session and CSRF, and needs `authorize.login-page`.
+- Either brings users, from an outside ledger unless `--axis @mod/users=@mod/users` keeps them in the configuration.
+- Federation grants need a login: `--login @mod/login-password --grants @mod/jwt-bearer,@mod/federation-grants` (a group flag replaces the pattern's group).

package/create-app/src/patterns/chosen.d.ts

@@ -0,0 +1,2 @@
+/** One line for each choice the composed modules show. */
+export declare function chosenLines(modules: readonly string[]): string[];

package/create-app/src/patterns/chosen.js

@@ -0,0 +1,35 @@
+/** What each axis's choice asks of the deployment, told from the modules composed, not the pattern's default. */
+const told = [
+    [
+        "@mod/store",
+        "Store in memory: one instance only (`kernel.deployment = single`), the memory store accepted (`store.accept-volatile = true`).",
+    ],
+    ["@mod/redis", "Store in Redis (`redis.url`, `redis.replication`)."],
+    [
+        "@mod/users-http",
+        "Users from an outside ledger (`users-http.verify-url`, `users-http.credential`).",
+    ],
+    [
+        "@mod/audit-http",
+        "Audit events posted to a receiver (`audit-http.url`, `audit.receivers = [http]`).",
+    ],
+    [
+        "@mod/mail-smtp",
+        "Mail through an SMTP relay (`mail-smtp.host`, `mail-smtp.from`; `mail-smtp.user` and `mail-smtp.password` in the local layer when it asks).",
+    ],
+    ["@mod/mail", "No mail is sent (`mail.accept-unsent = true`)."],
+];
+/** Said when the owner is composed and no adapter of it is. */
+const ownerOnly = [
+    ["@mod/users", "@mod/users-http", "Users in the configuration (`users.registered`)."],
+    ["@mod/audit", "@mod/audit-http", "Audit events to the log (`audit.receivers = [log]`)."],
+];
+/** One line for each choice the composed modules show. */
+export function chosenLines(modules) {
+    return [
+        ...told.filter(([name]) => modules.includes(name)).map(([, line]) => `- ${line}`),
+        ...ownerOnly
+            .filter(([owner, adapter]) => modules.includes(owner) && !modules.includes(adapter))
+            .map(([, , line]) => `- ${line}`),
+    ];
+}

package/create-app/src/patterns/device.d.ts

@@ -0,0 +1,2 @@
+import type { Pattern } from "./pattern.js";
+export declare const device: Pattern;

package/create-app/src/patterns/device.js

@@ -0,0 +1,14 @@
+import { simpleWeb } from "./simple-web.js";
+export const device = {
+    name: "device",
+    use: "Simple-web with the device authorization grant, for devices without a browser or a keyboard: " +
+        "the user reads a code on the device and approves it after logging in on another screen. " +
+        "It needs no outside system.",
+    axes: simpleWeb.axes,
+    features: {
+        ...simpleWeb.features,
+        grants: [...(simpleWeb.features.grants ?? []), "@mod/device-grant"],
+    },
+    areas: ["keys", "identity", "code", "oauth", "device", "ops"],
+    conformanceAdd: [],
+};

package/create-app/src/patterns/device.md

@@ -0,0 +1,6 @@
+# device
+
+- Use: devices without a browser or a keyboard; the user approves a code on another screen. Also the code flow with refresh, and client credentials.
+- Composes: simple-web's login and code flow (userinfo included), and the device authorization grant with its approval page.
+- The deployment serves the login page (`authorize.login-page`), the consent page (`consent.page`) only for clients that are not first-party, and names where users enter the code (`device-grant.verification-uri`).
+- No outside system. A client's back-channel logout goes only to the hosts in `outbound.allow`.

package/create-app/src/patterns/mfa-web.d.ts

@@ -0,0 +1,2 @@
+import type { Pattern } from "./pattern.js";
+export declare const mfaWeb: Pattern;

package/create-app/src/patterns/mfa-web.js

@@ -0,0 +1,25 @@
+import { simpleWeb } from "./simple-web.js";
+export const mfaWeb = {
+    name: "mfa-web",
+    use: "Simple-web with a second factor: a one-time password app (TOTP), a code by email, and " +
+        "recovery codes. Its store is in Redis, since losing it loses the factors users have " +
+        "registered; mail goes through an SMTP relay.",
+    axes: {
+        ...simpleWeb.axes,
+        "@mod/store": "@mod/redis",
+        "@mod/mail": "@mod/mail-smtp",
+    },
+    features: {
+        ...simpleWeb.features,
+        "second-factor": [
+            "@mod/mfa",
+            "@mod/mfa-flows",
+            "@mod/mfa-acr",
+            "@mod/mfa-totp",
+            "@mod/mfa-email",
+            "@mod/mfa-recovery",
+        ],
+    },
+    areas: ["keys", "identity", "code", "oauth", "second-factor", "ops"],
+    conformanceAdd: [],
+};

package/create-app/src/patterns/mfa-web.md

@@ -0,0 +1,8 @@
+# mfa-web
+
+- Use: a web login by password with a second factor (TOTP, a code by email, recovery codes); the code flow with refresh, and client credentials.
+- Composes: simple-web's login and code flow (userinfo included), the second factor and its flows (enrolment, login, reset, lock release), and the acr it meets.
+- Its store is in Redis: losing it loses the registered factors.
+- Factors are sealed with `seal.keys`.
+- Whether a second factor is required: `mfa.mode`.
+- The deployment serves the login page (`authorize.login-page`), the page that raises authentication (`authorize.step-up-page`), and the consent page (`consent.page`) only for clients that are not first-party.

package/create-app/src/patterns/native-app.d.ts

@@ -0,0 +1,2 @@
+import type { Pattern } from "./pattern.js";
+export declare const nativeApp: Pattern;

package/create-app/src/patterns/native-app.js

@@ -0,0 +1,11 @@
+import { simpleWeb } from "./simple-web.js";
+export const nativeApp = {
+    name: "native-app",
+    use: "A login for native and single-page apps: public clients use the authorization code flow " +
+        "with PKCE and refresh, and may bind their tokens to a key they hold (DPoP). It needs no " +
+        "outside system.",
+    axes: simpleWeb.axes,
+    features: { ...simpleWeb.features, binding: ["@mod/dpop"] },
+    areas: ["keys", "identity", "code", "oauth", "ops"],
+    conformanceAdd: [],
+};

package/create-app/src/patterns/native-app.md

@@ -0,0 +1,6 @@
+# native-app
+
+- Use: native and single-page apps as public clients (no secret), by the code flow with PKCE and refresh.
+- Composes: simple-web's login and code flow (userinfo included), and DPoP, so a client may bind its tokens to a key it holds.
+- The deployment serves the login page (`authorize.login-page`), and the consent page (`consent.page`) only for clients that are not first-party.
+- No outside system. A client's back-channel logout goes only to the hosts in `outbound.allow`.

package/create-app/src/patterns/pattern.d.ts

@@ -0,0 +1,28 @@
+import type { Selection } from "@o3co/auth-provider-scaffold/combinations";
+/** The groups a pattern's features fall in, each overridden whole by the operator's flag of that name. */
+export declare const groups: readonly ["login", "second-factor", "grants", "client-auth", "binding"];
+export type Group = (typeof groups)[number];
+/** A deployment's use, and the selection that composes it. */
+export interface Pattern {
+    readonly name: string;
+    /** One paragraph: the generated guide opens with it. */
+    readonly use: string;
+    /** Axis owner → its adapter, or the owner itself; an axis left out keeps full's default. */
+    readonly axes: Readonly<Record<string, string>>;
+    /** The features that decide the use; what they need comes with them. */
+    readonly features: Readonly<Partial<Record<Group, readonly string[]>>>;
+    /** The conformance areas run against the pattern's app. */
+    readonly areas: readonly string[];
+    /** Features conformance adds for the pattern's run alone, so its core is under test; reviewed, kept small. */
+    readonly conformanceAdd: readonly string[];
+}
+/** What the operator changes: axes over the pattern's, groups in place of its, features added. */
+export interface Choice {
+    readonly axes?: Readonly<Record<string, string>>;
+    readonly features?: Readonly<Record<string, readonly string[]>>;
+    readonly add?: readonly string[];
+}
+/** The pattern's selection with the operator's choice; a group not known is refused, naming it. */
+export declare function selectionOf(pattern: Pattern, choice?: Choice): Selection;
+/** Whether the selection's store lives in the process, so the deployment runs as one instance. */
+export declare const oneInstance: (selection: Selection) => boolean;

package/create-app/src/patterns/pattern.js

@@ -0,0 +1,31 @@
+/** The groups a pattern's features fall in, each overridden whole by the operator's flag of that name. */
+export const groups = ["login", "second-factor", "grants", "client-auth", "binding"];
+const isGroup = (name) => groups.includes(name);
+/** The features every pattern composes; the foundations come with what needs them. */
+const common = [
+    "@mod/issuer",
+    "@mod/discovery",
+    "@mod/tokens",
+    "@mod/sender-binding",
+    "@mod/token-endpoint",
+    "@mod/token-control",
+    "@mod/clients",
+    "@mod/subject-revocation",
+    "@mod/subject-tokens",
+];
+/** The store kept in this process: safe on one instance only. */
+const memoryStore = "@mod/store";
+/** The pattern's selection with the operator's choice; a group not known is refused, naming it. */
+export function selectionOf(pattern, choice = {}) {
+    const unknown = Object.keys(choice.features ?? {}).filter((group) => !isGroup(group));
+    if (unknown.length > 0) {
+        throw new Error(`${unknown.join(", ")}: not a group (${groups.join(", ")})`);
+    }
+    return {
+        features: { common, ...pattern.features, ...choice.features },
+        axes: { ...pattern.axes, ...choice.axes },
+        add: choice.add ?? [],
+    };
+}
+/** Whether the selection's store lives in the process, so the deployment runs as one instance. */
+export const oneInstance = (selection) => selection.axes?.[memoryStore] === memoryStore;

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

@@ -0,0 +1,15 @@
+import type { Pattern } from "./pattern.js";
+export declare const fullName = "full";
+/** A pattern's name, its use and the conformance areas run against its app. */
+export interface PatternSummary {
+    readonly name: string;
+    readonly use: string;
+    readonly areas: readonly string[];
+    /** What conformance adds for the pattern's run; none when left out. */
+    readonly conformanceAdd?: readonly string[];
+}
+export declare function patterns(): PatternSummary[];
+/** The pattern of this name; one not known is refused, naming those that are. */
+export declare function patternNamed(name: string): Pattern;
+/** The pattern's card without its title: what it composes, and what the deployment provides. */
+export declare function cardOf(name: string): Promise<string>;

package/create-app/src/patterns/patterns.js

@@ -0,0 +1,49 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { a2a } from "./a2a.js";
+import { device } from "./device.js";
+import { mfaWeb } from "./mfa-web.js";
+import { nativeApp } from "./native-app.js";
+import { simpleWeb } from "./simple-web.js";
+import { ssoFederated } from "./sso-federated.js";
+/** The patterns besides full, which is `combinations`' full template itself. */
+const known = [simpleWeb, mfaWeb, device, nativeApp, a2a, ssoFederated];
+export const fullName = "full";
+const fullSummary = {
+    name: fullName,
+    use: "Every feature that does not opt in, as the previous release composed by default, with its " +
+        "store in Redis, users from an outside ledger and audit events posted to a receiver.",
+    areas: [
+        "keys",
+        "identity",
+        "code",
+        "oauth",
+        "second-factor",
+        "device",
+        "mtls",
+        "passkey",
+        "exchange",
+        "ops",
+    ],
+    conformanceAdd: [],
+};
+export function patterns() {
+    return [
+        ...known.map(({ name, use, areas, conformanceAdd }) => ({ name, use, areas, conformanceAdd })),
+        fullSummary,
+    ];
+}
+/** The pattern of this name; one not known is refused, naming those that are. */
+export function patternNamed(name) {
+    const found = known.find((p) => p.name === name);
+    if (!found) {
+        const names = patterns().map((p) => p.name);
+        throw new Error(`${name}: no such pattern (${names.join(", ")})`);
+    }
+    return found;
+}
+/** The pattern's card without its title: what it composes, and what the deployment provides. */
+export async function cardOf(name) {
+    const card = await readFile(join(import.meta.dirname, `${name}.md`), "utf8");
+    return card.split("\n").slice(1).join("\n").trim();
+}

package/create-app/src/patterns/simple-web.d.ts

@@ -0,0 +1,2 @@
+import type { Pattern } from "./pattern.js";
+export declare const simpleWeb: Pattern;

package/create-app/src/patterns/simple-web.js

@@ -0,0 +1,34 @@
+export const simpleWeb = {
+    name: "simple-web",
+    use: "A web login by password for clients that use the authorization code flow with refresh, and " +
+        "for services that use client credentials. It needs no outside system: the store is kept in " +
+        "memory, users are listed in the configuration, and audit events go to the log.",
+    axes: {
+        "@mod/store": "@mod/store",
+        "@mod/users": "@mod/users",
+        "@mod/audit": "@mod/audit",
+        "@mod/mail": "@mod/mail",
+    },
+    features: {
+        login: [
+            "@mod/login-password",
+            "@mod/login-gates",
+            "@mod/csrf",
+            "@mod/session",
+            "@mod/logout",
+            "@mod/rp-logout",
+        ],
+        grants: [
+            "@mod/authorize",
+            "@mod/code-grant",
+            "@mod/consent",
+            "@mod/oidc",
+            "@mod/acr",
+            "@mod/session-tokens",
+            "@mod/refresh",
+            "@mod/userinfo",
+        ],
+    },
+    areas: ["keys", "identity", "code", "oauth", "ops"],
+    conformanceAdd: [],
+};

package/create-app/src/patterns/simple-web.md

@@ -0,0 +1,6 @@
+# simple-web
+
+- Use: a web login by password; clients use the code flow with refresh, services client credentials.
+- Composes: the login and its session, logout (a client's too), authorization, consent, OpenID Connect with its userinfo, refresh, and the token endpoint with introspection and revocation.
+- The deployment serves the login page (`authorize.login-page`), and the consent page (`consent.page`) only for clients that are not first-party.
+- No outside system. A client's back-channel logout goes only to the hosts in `outbound.allow`.

package/create-app/src/patterns/sso-federated.d.ts

@@ -0,0 +1,2 @@
+import type { Pattern } from "./pattern.js";
+export declare const ssoFederated: Pattern;

package/create-app/src/patterns/sso-federated.js

@@ -0,0 +1,23 @@
+import { simpleWeb } from "./simple-web.js";
+export const ssoFederated = {
+    name: "sso-federated",
+    use: "Single sign-on through upstream identity providers (OpenID Connect, Google, GitHub, Apple), " +
+        "with no password of its own: clients use the authorization code flow with refresh, and " +
+        "services client credentials. Users come from an outside ledger.",
+    axes: { ...simpleWeb.axes, "@mod/users": "@mod/users-http" },
+    features: {
+        login: [
+            "@mod/upstreams",
+            "@mod/idp-oidc",
+            "@mod/idp-google",
+            "@mod/idp-github",
+            "@mod/idp-apple",
+            "@mod/federation-tokens",
+            "@mod/logout",
+            "@mod/rp-logout",
+        ],
+        grants: simpleWeb.features.grants ?? [],
+    },
+    areas: ["keys", "identity", "code", "oauth", "ops"],
+    conformanceAdd: ["@mod/login-password"],
+};

package/create-app/src/patterns/sso-federated.md

@@ -0,0 +1,6 @@
+# sso-federated
+
+- Use: single sign-on through upstream identity providers, with no password of its own; the code flow with refresh, and client credentials.
+- Composes: federation with OpenID Connect, Google, GitHub and Apple, its upstream tokens, logout (a client's too, sent on upstream), authorization, consent, OpenID Connect with its userinfo, and refresh.
+- The providers are named in `federation.idps`. Users come from an outside ledger; `--axis @mod/users=@mod/users` lists them in the configuration instead. A password login is not composed: `--login` replaces this group, so it lists the federation modules with `@mod/login-password`.
+- The deployment serves the login page that offers the providers (`authorize.login-page`), and the consent page (`consent.page`) only for clients that are not first-party; the providers and the ledger are reached through `outbound.allow`.

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

@@ -0,0 +1,19 @@
+export declare const kernel = "@mod/kernel";
+/** Refuses, before anything is written, a name the app could not import or depend on. */
+export declare function namesPackages(names: readonly string[]): void;
+/** A reading's catch: a missing file or directory reads as `absent`, and any other failure is thrown on. */
+export declare const missingAs: <T>(absent: T) => (error: NodeJS.ErrnoException) => T;
+/** A target that is missing or empty; one that holds anything is refused, never overwritten. */
+export declare function vacant(target: string): Promise<void>;
+/** Package directories by name, as the workspace definition places them. */
+export declare function workspacePackages(root: string): Map<string, string>;
+/** Each name's dependency: a link to its workspace directory when given a workspace, else any version. */
+export declare function dependenciesOf(names: readonly string[], known: ReadonlyMap<string, string> | undefined): Record<string, string>;
+export declare const manifestOf: (start: string, dependencies: Record<string, string>) => string;
+/** Fills a file of `templates/` by its `{{name}}` marks; a mark with no value stays as written. */
+export declare function filled(template: string, fill: Readonly<Record<string, string>>): Promise<string>;
+/** The app's entry, importing each module under what `importOf` names it (the workspace's name, unless published). */
+export declare const mainSource: (modules: readonly string[], importOf?: (name: string) => string) => Promise<string>;
+export declare const withKernel: (modules: readonly string[]) => string[];
+/** Writes every file, by its path in the project, once all are made: nothing is written for a project that fails. */
+export declare function writeProject(target: string, files: Readonly<Record<string, string>>): Promise<void>;