@stjoseph/prumo 0.3.0 → 0.4.1

package/dist/features.js

@@ -0,0 +1,234 @@
+import { existsSync } from 'node:fs';
+import { readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { setJsonc } from "./jsonc.js";
+// What a project may leave out. The templates ship with every one of them; a project that answered no receives the
+// template without it: these files deleted, these dependencies removed, and every line or block marked
+// `// prumo:<feature>` cut, READMEs included. A feature a type does not list has nothing to cut there.
+export const FEATURE_NAMES = ['mcp', 'email', 'social', 'google', 'apple'];
+export const SOCIAL_PROVIDERS = ['google', 'apple'];
+export const NONE = {
+    mcp: false,
+    email: false,
+    social: false,
+    google: false,
+    apple: false,
+};
+export function enabledFor(answers) {
+    return {
+        mcp: answers.mcp,
+        email: answers.email,
+        social: answers.social.length > 0,
+        google: answers.social.includes('google'),
+        apple: answers.social.includes('apple'),
+    };
+}
+export const FEATURES = {
+    // The API's MCP is its server and the OAuth authorization server that issues its tokens, with the table that
+    // holds an authorization in a migration of its own, so a project without MCP never creates it.
+    mcp: {
+        files: {
+            api: [
+                'src/infra/mcp',
+                'src/domain/oauth',
+                'src/infra/oauth',
+                'src/infra/di/oauth.di.ts',
+                'src/infra/http/fetch-bridge.ts',
+                'src/infra/http/controllers/mcp.controller.ts',
+                'src/infra/http/controllers/oauth.controller.ts',
+                'src/infra/database/mikroorm/entities/authorization.schema.ts',
+                'src/infra/database/mikroorm/repositories/mikroorm-authorization.repository.ts',
+                'migrations/Migration20261005111547_create_authorization.ts',
+                'test/domain/oauth',
+                'test/infra/oauth',
+                'test/infra/http/controllers/mcp.controller.spec.ts',
+            ],
+            web: ['src/features/oauth', 'src/routes/_authenticated/consent.tsx', 'test/features/oauth'],
+        },
+        dependencies: {
+            api: ['@modelcontextprotocol/client', '@modelcontextprotocol/server'],
+            web: [],
+        },
+    },
+    // Verification and password reset: a code sent through the Mailer port, its table in a migration of its own.
+    email: {
+        files: {
+            api: [
+                'src/domain/auth/entities/email-code.entity.ts',
+                'src/domain/auth/ports/mailer.port.ts',
+                'src/domain/auth/ports/one-time-codes.port.ts',
+                'src/domain/auth/repositories/email-code.repository.ts',
+                'src/domain/auth/errors/email-not-verified.error.ts',
+                'src/domain/auth/errors/invalid-code.error.ts',
+                'src/domain/auth/dto/email-request.dto.ts',
+                'src/domain/auth/dto/verify-email.dto.ts',
+                'src/domain/auth/dto/reset-password.dto.ts',
+                'src/domain/auth/use-cases/issue-email-code.use-case.ts',
+                'src/domain/auth/use-cases/request-email-verification.use-case.ts',
+                'src/domain/auth/use-cases/verify-email.use-case.ts',
+                'src/domain/auth/use-cases/request-password-reset.use-case.ts',
+                'src/domain/auth/use-cases/reset-password.use-case.ts',
+                'src/infra/email',
+                'src/infra/di/email.di.ts',
+                'src/infra/http/controllers/auth-email.controller.ts',
+                'src/infra/database/mikroorm/entities/email-code.schema.ts',
+                'src/infra/database/mikroorm/repositories/mikroorm-email-code.repository.ts',
+                'migrations/Migration20261005111549_create_email_code.ts',
+                'test/domain/auth/use-cases/email.use-case.spec.ts',
+                'test/infra/email',
+                'test/infra/http/controllers/auth-email.controller.spec.ts',
+                'test/support/fakes/fake-mailer.ts',
+                'test/support/fakes/fake-one-time-codes.ts',
+                'test/support/fakes/in-memory-email-code.repository.ts',
+            ],
+            web: [
+                'src/features/auth/verify-email-form.tsx',
+                'src/features/auth/forgot-password-form.tsx',
+                'src/features/auth/reset-password-form.tsx',
+                'src/routes/verify-email.tsx',
+                'src/routes/forgot-password.tsx',
+                'src/routes/reset-password.tsx',
+                'test/features/auth/email-flows.spec.tsx',
+            ],
+            mobile: [
+                'src/features/auth/verify-email-form.tsx',
+                'src/features/auth/forgot-password-form.tsx',
+                'src/features/auth/reset-password-form.tsx',
+                'src/app/(auth)/verify-email.tsx',
+                'src/app/(auth)/forgot-password.tsx',
+                'src/app/(auth)/reset-password.tsx',
+                'test/features/auth/email-flows.spec.tsx',
+            ],
+        },
+        dependencies: {},
+    },
+    // Sign-in with a provider: the OpenID adapter, the trip there and back, and the identities it links, with their
+    // tables in a migration of their own. Google and Apple are cut by their markers alone.
+    social: {
+        files: {
+            api: [
+                'src/domain/auth/entities/identity.entity.ts',
+                'src/domain/auth/entities/social-sign-in.entity.ts',
+                'src/domain/auth/ports/identity-providers.port.ts',
+                'src/domain/auth/repositories/identity.repository.ts',
+                'src/domain/auth/repositories/social-sign-in.repository.ts',
+                'src/domain/auth/errors/provider-not-configured.error.ts',
+                'src/domain/auth/errors/provider-email-unverified.error.ts',
+                'src/domain/auth/errors/social-sign-in-failed.error.ts',
+                'src/domain/auth/use-cases/link-identity.use-case.ts',
+                'src/domain/auth/use-cases/start-social-sign-in.use-case.ts',
+                'src/domain/auth/use-cases/complete-social-sign-in.use-case.ts',
+                'src/domain/auth/use-cases/exchange-social-code.use-case.ts',
+                'src/infra/social',
+                'src/infra/di/social.di.ts',
+                'src/infra/http/controllers/social.controller.ts',
+                'src/infra/database/mikroorm/entities/identity.schema.ts',
+                'src/infra/database/mikroorm/entities/social-sign-in.schema.ts',
+                'src/infra/database/mikroorm/repositories/mikroorm-identity.repository.ts',
+                'src/infra/database/mikroorm/repositories/mikroorm-social-sign-in.repository.ts',
+                'migrations/Migration20261005111550_create_identity_social_sign_in.ts',
+                'test/domain/auth/use-cases/social.use-case.spec.ts',
+                'test/infra/social',
+                'test/infra/http/controllers/social.controller.spec.ts',
+                'test/support/fakes/social-fakes.ts',
+                'test/support/fake-oidc-server.ts',
+            ],
+            web: ['src/features/auth/social-buttons.tsx', 'test/features/auth/social-buttons.spec.tsx'],
+            mobile: [
+                'src/features/auth/social-buttons.tsx',
+                'test/features/auth/social-buttons.spec.tsx',
+            ],
+        },
+        dependencies: { api: ['openid-client'] },
+    },
+    google: { files: {}, dependencies: {} },
+    apple: { files: {}, dependencies: {} },
+};
+export function cutFeature(text, feature, keep, file = 'a file') {
+    // Inside JSX a comment is written {/* … */}, in an env file with #, and in Markdown as <!-- … -->, so a block may
+    // open and close any of these ways.
+    const start = new RegExp(`^\\s*(// prumo:${feature}|\\{/\\* prumo:${feature} \\*/\\}|# prumo:${feature}|<!-- prumo:${feature} -->)$`);
+    const end = new RegExp(`^\\s*(// prumo:end-${feature}|\\{/\\* prumo:end-${feature} \\*/\\}|# prumo:end-${feature}|<!-- prumo:end-${feature} -->)$`);
+    // A marked import keeps its marker as a trailing comment, which the import sorter carries along.
+    const marked = new RegExp(`\\s*(//|#) prumo:${feature}$`);
+    const kept = [];
+    let inBlock = false;
+    for (const line of text.split('\n')) {
+        if (start.test(line)) {
+            if (inBlock) {
+                throw new Error(`${file} opens a prumo:${feature} block inside another`);
+            }
+            inBlock = true;
+        }
+        else if (end.test(line)) {
+            if (!inBlock) {
+                throw new Error(`${file} closes a prumo:${feature} block it never opened`);
+            }
+            inBlock = false;
+        }
+        else if (marked.test(line)) {
+            if (keep) {
+                kept.push(line.replace(marked, ''));
+            }
+        }
+        else if (keep || !inBlock) {
+            kept.push(line);
+        }
+    }
+    if (inBlock) {
+        throw new Error(`${file} leaves a prumo:${feature} block open`);
+    }
+    return kept.join('\n');
+}
+export function cutFeatures(text, enabled, file = 'a file') {
+    return FEATURE_NAMES.reduce((current, feature) => cutFeature(current, feature, enabled[feature], file), text);
+}
+async function sourceFiles(directory) {
+    if (!existsSync(directory)) {
+        return [];
+    }
+    const entries = await readdir(directory, { withFileTypes: true, recursive: true });
+    return entries
+        .filter((entry) => entry.isFile() && /\.tsx?$/.test(entry.name))
+        .map((entry) => join(entry.parentPath, entry.name));
+}
+export async function applyFeatures(app, type, enabled) {
+    const sources = [
+        ...(await sourceFiles(join(app, 'src'))),
+        ...(await sourceFiles(join(app, 'test'))),
+        // The settings a feature needs are cut with it, and so is what the README says about it.
+        join(app, '.env.example'),
+        join(app, 'README.md'),
+    ];
+    const manifest = join(app, 'package.json');
+    let pkg = await readFile(manifest, 'utf8');
+    const dropped = [];
+    for (const feature of FEATURE_NAMES) {
+        if (enabled[feature]) {
+            continue;
+        }
+        for (const file of FEATURES[feature].files[type] ?? []) {
+            await rm(join(app, file), { recursive: true, force: true });
+        }
+        for (const dependency of FEATURES[feature].dependencies[type] ?? []) {
+            dropped.push(dependency);
+            for (const section of ['dependencies', 'devDependencies']) {
+                pkg = setJsonc(pkg, [section, dependency], undefined);
+            }
+        }
+    }
+    await writeFile(manifest, pkg);
+    for (const source of sources) {
+        if (!existsSync(source)) {
+            continue;
+        }
+        const text = await readFile(source, 'utf8');
+        const cut = cutFeatures(text, enabled, source);
+        if (dropped.some((dependency) => cut.includes(`'${dependency}`))) {
+            throw new Error(`${source} still imports a package that was removed, outside its marker`);
+        }
+        if (cut !== text) {
+            await writeFile(source, cut);
+        }
+    }
+}

package/dist/generate.js

@@ -6,8 +6,8 @@ import { join } from 'node:path';
 import { composeWorkspace, copyTemplate } from "./compose.js";
 import { writeContext } from "./context.js";
 import { SHELL } from "./doctor.js";
+import { applyFeatures, enabledFor } from "./features.js";
 import { setJsonc } from "./jsonc.js";
-import { applyMcp } from "./mcp.js";
 import { schemeFor, targetProblem } from "./names.js";
 import { CliError } from "./output.js";
 async function rewrite(path, change) {
@@ -25,6 +25,19 @@ async function nameMobileApp(app, name) {
     });
 }
 const SECRET_LINE = /^JWT_SECRET=.*$/m;
+const SCHEME_LINES = /^# The mobile app's scheme.*\nMOBILE_APP_SCHEME=.*\n/m;
+// Social sign-in sends a mobile app back by its scheme, the one app.json was given. Without a mobile app the setting
+// names nothing, so it goes. Without social sign-in its marker already took it.
+async function settleMobileScheme(api, scheme) {
+    for (const file of ['.env.example', '.env']) {
+        const path = join(api, file);
+        if (existsSync(path)) {
+            await rewrite(path, (text) => scheme === null
+                ? text.replace(SCHEME_LINES, '')
+                : text.replace(/^MOBILE_APP_SCHEME=.*$/m, `MOBILE_APP_SCHEME=${scheme}`));
+        }
+    }
+}
 // `.env` stays out of git, so the example is the committed truth and a fresh project gets a copy it can start with.
 // Only the secret differs: a sample value is public, so every generated API draws its own.
 async function writeLocalEnv(app, type) {
@@ -115,7 +128,7 @@ async function write({ templates, knowledge, target, answers, install, childOutp
     const [only] = answers.types;
     if (answers.architecture === 'alone' && only !== undefined) {
         await copyTemplate(join(templates, only), target);
-        await applyMcp(target, only, answers.mcp);
+        await applyFeatures(target, only, enabledFor(answers));
         await nameProject(target, answers.name);
         await writeLocalEnv(target, only);
         if (only === 'api') {
@@ -130,7 +143,7 @@ async function write({ templates, knowledge, target, answers, install, childOutp
             templates,
             target,
             types: answers.types,
-            mcp: answers.mcp,
+            features: enabledFor(answers),
         });
         await nameProject(target, answers.name);
         for (const type of answers.types) {
@@ -138,6 +151,7 @@ async function write({ templates, knowledge, target, answers, install, childOutp
         }
         if (answers.types.includes('api')) {
             await nameCompose(join(target, 'apps', 'api'), answers.name);
+            await settleMobileScheme(join(target, 'apps', 'api'), answers.types.includes('mobile') ? schemeFor(answers.name) : null);
         }
         if (answers.types.includes('mobile')) {
             await nameMobileApp(join(target, 'apps', 'mobile'), answers.name);

package/dist/next-steps.js

@@ -0,0 +1,24 @@
+import { relative } from 'node:path';
+// What to type after `prumo new`, built from the scripts the templates ship rather than written per case. Every app
+// and every workspace root answers to `pnpm dev`; an API's `dev` first offers to create the database, and a mobile
+// app opens only in a development build, which its `ios` and `android` scripts make.
+export function nextSteps({ target, cwd, types, architecture, installed, }) {
+    const steps = [];
+    const directory = relative(cwd, target);
+    if (directory !== '') {
+        steps.push([`cd ${/\s/.test(directory) ? `"${directory}"` : directory}`]);
+    }
+    if (!installed) {
+        steps.push(['pnpm install']);
+    }
+    if (types.includes('mobile')) {
+        const run = architecture === 'alone' ? 'pnpm' : 'pnpm --filter mobile';
+        steps.push([`${run} ios`, 'or android: the development build the mobile app opens in']);
+    }
+    steps.push([
+        'pnpm dev',
+        types.includes('api') ? 'offers to create the database first' : undefined,
+    ]);
+    const width = Math.max(...steps.map(([command]) => command.length));
+    return steps.map(([command, why]) => why === undefined ? command : `${command.padEnd(width)}  # ${why}`);
+}

package/dist/questions.js

@@ -1,3 +1,4 @@
+import { SOCIAL_PROVIDERS } from "./features.js";
 import { projectAt, targetProblem, validateProjectName } from "./names.js";
 import { CliError } from "./output.js";
 const TYPES = ['api', 'web', 'mobile', 'site'];
@@ -19,6 +20,17 @@ function parseTypes(value) {
     }
     return [...new Set(types)];
 }
+function parseProviders(value) {
+    const providers = value
+        .split(',')
+        .map((provider) => provider.trim())
+        .filter((provider) => provider !== '');
+    const unknown = providers.filter((provider) => !SOCIAL_PROVIDERS.includes(provider));
+    if (providers.length === 0 || unknown.length > 0) {
+        throw new CliError('invalid_input', `Unknown provider: ${unknown.join(', ') || '(none)'}. Choose from ${SOCIAL_PROVIDERS.join(', ')}, or pass --no-social.`);
+    }
+    return [...new Set(providers)];
+}
 export async function resolveAnswers(flags, asker, cwd = process.cwd()) {
     if (flags.alone && flags.monorepo) {
         throw new CliError('invalid_input', 'Choose --alone or --monorepo, not both.');
@@ -26,6 +38,12 @@ export async function resolveAnswers(flags, asker, cwd = process.cwd()) {
     if (flags.mcp && flags.noMcp) {
         throw new CliError('invalid_input', 'Choose --mcp or --no-mcp, not both.');
     }
+    if (flags.email && flags.noEmail) {
+        throw new CliError('invalid_input', 'Choose --email or --no-email, not both.');
+    }
+    if (flags.social !== undefined && flags.noSocial) {
+        throw new CliError('invalid_input', 'Choose --social or --no-social, not both.');
+    }
     if (flags.multiTenant && flags.singleTenant) {
         throw new CliError('invalid_input', 'Choose --multi-tenant or --single-tenant, not both.');
     }
@@ -96,5 +114,50 @@ export async function resolveAnswers(flags, asker, cwd = process.cwd()) {
     else {
         missing('--mcp or --no-mcp');
     }
-    return { name, types, architecture, multiTenant, mcp, target };
+    // Verification and password reset are the API's; every client of it then shows their screens.
+    let email = false;
+    if (!types.includes('api')) {
+        if (flags.email) {
+            throw new CliError('invalid_input', '--email needs api in --types.');
+        }
+    }
+    else if (flags.email || flags.noEmail) {
+        email = flags.email;
+    }
+    else if (asker !== undefined) {
+        email = await asker.email();
+    }
+    else {
+        missing('--email or --no-email');
+    }
+    // A provider sends the user back to a screen, so social sign-in needs a client beside the API.
+    const socialCapable = types.includes('api') && (types.includes('web') || types.includes('mobile'));
+    let social = [];
+    if (!socialCapable) {
+        if (flags.social !== undefined) {
+            throw new CliError('invalid_input', '--social needs api, and web or mobile, in --types.');
+        }
+    }
+    else if (flags.social !== undefined) {
+        social = parseProviders(flags.social);
+    }
+    else if (flags.noSocial) {
+        social = [];
+    }
+    else if (asker !== undefined) {
+        social = await asker.social();
+    }
+    else {
+        missing('--social <providers> or --no-social');
+    }
+    const warnings = [];
+    if (types.includes('mobile') && social.includes('google') && !social.includes('apple')) {
+        warnings.push('The App Store asks an app offering Google sign-in to offer an equivalent privacy-preserving login too ' +
+            '(App Review Guideline 4.8); Sign in with Apple is one. Add apple to --social before publishing on iOS.');
+    }
+    if (social.length > 0 && !email) {
+        warnings.push('Without --email no password account is ever confirmed, so the first sign-in with a provider for an existing ' +
+            "account's email removes its password: the owner keeps the account through the provider. --email avoids it.");
+    }
+    return { name, types, architecture, multiTenant, mcp, email, social, target, warnings };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stjoseph/prumo",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Scaffolds a TypeScript project and ships it the conventions it follows, in a .prumo/ folder any AI assistant reads.",
   "keywords": [
     "scaffolding",

package/templates/api/.env.example

@@ -11,3 +11,21 @@ POSTGRES_PORT=5432
 JWT_SECRET=replace-this-with-at-least-32-characters
 API_URL=http://localhost:3000
 WEB_ORIGIN=http://localhost:5173
+# prumo:social
+# The mobile app's scheme, as in app.json: where it is sent back after signing in with a provider.
+MOBILE_APP_SCHEME=app
+# prumo:end-social
+# prumo:google
+# From a Google Cloud OAuth client of type "Web application", with this redirect URI authorised:
+# http://localhost:3000/api/auth/social/google/callback
+# GOOGLE_CLIENT_ID=
+# GOOGLE_CLIENT_SECRET=
+# prumo:end-google
+# prumo:apple
+# From an Apple Services ID with Sign in with Apple and a key for it. Register this return URL on the Services ID,
+# with the address Apple can reach your API at: <API_URL>/api/auth/social/apple/callback
+# APPLE_CLIENT_ID=
+# APPLE_TEAM_ID=
+# APPLE_KEY_ID=
+# APPLE_PRIVATE_KEY=
+# prumo:end-apple

package/templates/api/README.md

@@ -32,6 +32,25 @@ it spawned, stops them, and frees the port. Anything it did not start is named a
 
 Authentication is the API's own: `/api/auth/sign-up`, `sign-in`, `refresh`, `sign-out` and `session`. The web
 receives httpOnly cookies; a native client sends `X-Auth-Transport: bearer` and receives the tokens in the body.
+<!-- prumo:email -->
+
+An account must confirm its email before it can sign in. `/api/auth/email/verification` and `/api/auth/email/verify`
+send and check the 6-digit code, and `/api/auth/password/forgot` and `/api/auth/password/reset` do the same for a new
+password. No mail is sent yet: the `Mailer` port's only adapter, `LogMailer`, writes each mail to this API's log, in
+a line starting `[mail] to`, so read the code there. Sending real mail is another adapter behind the same port; see
+`.prumo/email/mailer.md`.
+<!-- prumo:end-email -->
+<!-- prumo:social -->
+
+Sign-in with a provider starts at `/api/auth/social/<provider>` and comes back to its `callback`. Until a provider's
+settings are filled in `.env`, it answers `provider_not_configured`; `.env.example` lists them and says where each
+one comes from.
+<!-- prumo:end-social -->
+<!-- prumo:mcp -->
+
+The MCP server answers at `/api/mcp`. This API is also the OAuth authorization server that issues its tokens: an MCP
+client finds it through `/.well-known/oauth-protected-resource`, and the user signs in and consents on the web app.
+<!-- prumo:end-mcp -->
 
 ## Everyday commands
 

package/templates/api/migrations/{Migration20261002210629_create_user_profile_session.ts → Migration20261005111545_create_user_profile_session.ts}

@@ -1,14 +1,14 @@
 import { Migration } from '@mikro-orm/migrations';
 
-export class Migration20261002210629_create_user_profile_session extends Migration {
+export class Migration20261005111545_create_user_profile_session extends Migration {
 
-  override name = 'Migration20261002210629_create_user_profile_session';
+  override name = 'Migration20261005111545_create_user_profile_session';
 
   override up(): void | Promise<void> {
-    this.addSql(`create table "user" ("id" uuid not null default uuidv7(), "email" text not null, "password_hash" text not null, "created_at" timestamptz not null default now(), "updated_at" timestamptz not null default now(), primary key ("id"));`);
+    this.addSql(`create table "user" ("id" uuid not null default uuidv7(), "email" text not null, "password_hash" text null, "email_verified_at" timestamptz null, "created_at" timestamptz not null default now(), "updated_at" timestamptz not null default now(), primary key ("id"));`);
     this.addSql(`alter table "user" add constraint "user_email_unique" unique ("email");`);
 
-    this.addSql(`create table "session" ("id" uuid not null default uuidv7(), "user_id" uuid not null, "token_hash" text not null, "client_id" text null, "resource" text null, "previous_token_hash" text null, "rotated_at" timestamptz null, "expires_at" timestamptz not null, "revoked_at" timestamptz null, "created_at" timestamptz not null default now(), "updated_at" timestamptz not null default now(), primary key ("id"));`);
+    this.addSql(`create table "session" ("id" uuid not null default uuidv7(), "user_id" uuid not null, "token_hash" text not null, "client_id" text null, "resource" text null, "scope" text null, "previous_token_hash" text null, "rotated_at" timestamptz null, "expires_at" timestamptz not null, "revoked_at" timestamptz null, "created_at" timestamptz not null default now(), "updated_at" timestamptz not null default now(), primary key ("id"));`);
     this.addSql(`create index "session_user_id_index" on "session" ("user_id");`);
 
     this.addSql(`create table "profile" ("id" uuid not null default uuidv7(), "user_id" uuid not null, "display_name" text not null, "locale" text not null default 'en', "timezone" text not null default 'UTC', "created_at" timestamptz not null default now(), "updated_at" timestamptz not null default now(), primary key ("id"));`);

package/templates/api/migrations/{Migration20261002210631_create_authorization.ts → Migration20261005111547_create_authorization.ts}

@@ -1,11 +1,11 @@
 import { Migration } from '@mikro-orm/migrations';
 
-export class Migration20261002210631_create_authorization extends Migration {
+export class Migration20261005111547_create_authorization extends Migration {
 
-  override name = 'Migration20261002210631_create_authorization';
+  override name = 'Migration20261005111547_create_authorization';
 
   override up(): void | Promise<void> {
-    this.addSql(`create table "authorization" ("id" uuid not null default uuidv7(), "client_id" text not null, "client_name" text not null, "redirect_uri" text not null, "code_challenge" text not null, "client_state" text null, "resource" text not null, "status" text not null, "user_id" uuid null, "code_hash" text null, "session_id" uuid null, "expires_at" timestamptz not null, "created_at" timestamptz not null default now(), "updated_at" timestamptz not null default now(), primary key ("id"));`);
+    this.addSql(`create table "authorization" ("id" uuid not null default uuidv7(), "client_id" text not null, "client_name" text not null, "redirect_uri" text not null, "code_challenge" text not null, "client_state" text null, "resource" text not null, "scope" text not null, "status" text not null, "user_id" uuid null, "code_hash" text null, "session_id" uuid null, "expires_at" timestamptz not null, "created_at" timestamptz not null default now(), "updated_at" timestamptz not null default now(), primary key ("id"));`);
     this.addSql(`create index "authorization_user_id_index" on "authorization" ("user_id");`);
 
     this.addSql(`alter table "authorization" add constraint "authorization_user_id_foreign" foreign key ("user_id") references "user" ("id") on delete cascade;`);

package/templates/api/migrations/Migration20261005111549_create_email_code.ts

@@ -0,0 +1,18 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20261005111549_create_email_code extends Migration {
+
+  override name = 'Migration20261005111549_create_email_code';
+
+  override up(): void | Promise<void> {
+    this.addSql(`create table "email_code" ("id" uuid not null default uuidv7(), "user_id" uuid not null, "purpose" text not null, "code_hash" text not null, "attempts_left" int not null, "expires_at" timestamptz not null, "created_at" timestamptz not null default now(), "updated_at" timestamptz not null default now(), primary key ("id"));`);
+    this.addSql(`alter table "email_code" add constraint "email_code_user_id_purpose_unique" unique ("user_id", "purpose");`);
+
+    this.addSql(`alter table "email_code" add constraint "email_code_user_id_foreign" foreign key ("user_id") references "user" ("id") on delete cascade;`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`drop table if exists "email_code" cascade;`);
+  }
+
+}

package/templates/api/migrations/Migration20261005111550_create_identity_social_sign_in.ts

@@ -0,0 +1,25 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20261005111550_create_identity_social_sign_in extends Migration {
+
+  override name = 'Migration20261005111550_create_identity_social_sign_in';
+
+  override up(): void | Promise<void> {
+    this.addSql(`create table "social_sign_in" ("id" uuid not null default uuidv7(), "provider" text not null, "client" text not null, "return_to" text not null, "browser_hash" text not null, "code_verifier" text null, "nonce" text not null, "status" text not null, "user_id" uuid null, "exchange_hash" text null, "expires_at" timestamptz not null, "created_at" timestamptz not null default now(), "updated_at" timestamptz not null default now(), primary key ("id"));`);
+    this.addSql(`create index "social_sign_in_user_id_index" on "social_sign_in" ("user_id");`);
+
+    this.addSql(`create table "identity" ("id" uuid not null default uuidv7(), "user_id" uuid not null, "provider" text not null, "subject" text not null, "created_at" timestamptz not null default now(), "updated_at" timestamptz not null default now(), primary key ("id"));`);
+    this.addSql(`create index "identity_user_id_index" on "identity" ("user_id");`);
+    this.addSql(`alter table "identity" add constraint "identity_provider_subject_unique" unique ("provider", "subject");`);
+
+    this.addSql(`alter table "social_sign_in" add constraint "social_sign_in_user_id_foreign" foreign key ("user_id") references "user" ("id") on delete cascade;`);
+
+    this.addSql(`alter table "identity" add constraint "identity_user_id_foreign" foreign key ("user_id") references "user" ("id") on delete cascade;`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`drop table if exists "social_sign_in" cascade;`);
+    this.addSql(`drop table if exists "identity" cascade;`);
+  }
+
+}

package/templates/api/package.json

@@ -31,6 +31,7 @@
     "fastify": "5.12.5",
     "fastify-type-provider-zod": "7.0.0",
     "jose": "6.2.12",
+    "openid-client": "6.8.8",
     "reflect-metadata": "0.2.2",
     "tsyringe": "4.10.0",
     "zod": "4.6.4"

package/templates/api/src/domain/auth/dto/email-request.dto.ts

@@ -0,0 +1,5 @@
+import { z } from 'zod'
+
+export const emailRequestSchema = z.strictObject({ email: z.email().max(254) })
+
+export type EmailRequestDto = z.infer<typeof emailRequestSchema>

package/templates/api/src/domain/auth/dto/reset-password.dto.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod'
+
+export const resetPasswordSchema = z.strictObject({
+  email: z.email().max(254),
+  code: z.string().regex(/^\d{6}$/),
+  password: z.string().min(8).max(128),
+})
+
+export type ResetPasswordDto = z.infer<typeof resetPasswordSchema>

package/templates/api/src/domain/auth/dto/verify-email.dto.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod'
+
+export const verifyEmailSchema = z.strictObject({
+  email: z.email().max(254),
+  code: z.string().regex(/^\d{6}$/),
+})
+
+export type VerifyEmailDto = z.infer<typeof verifyEmailSchema>

package/templates/api/src/domain/auth/entities/email-code.entity.ts

@@ -0,0 +1,46 @@
+// Short enough that guessing is a race against the clock, long enough to switch to the mail app and back.
+export const EMAIL_CODE_LIFETIME_MS = 15 * 60 * 1000
+export const EMAIL_CODE_ATTEMPTS = 5
+
+export type EmailCodePurpose = 'verify-email' | 'reset-password'
+
+export type CodeOutcome = 'valid' | 'wrong' | 'expired'
+
+// One live code per user and purpose: sending another replaces it, and the old one stops working.
+export class EmailCode {
+  id: string
+  userId: string
+  purpose: EmailCodePurpose
+  codeHash: string
+  attemptsLeft: number
+  expiresAt: Date
+  createdAt: Date
+  updatedAt: Date
+
+  constructor(userId: string, purpose: EmailCodePurpose, codeHash: string, now: Date) {
+    this.userId = userId
+    this.purpose = purpose
+    this.renew(codeHash, now)
+  }
+
+  renew(codeHash: string, now: Date): void {
+    this.codeHash = codeHash
+    this.attemptsLeft = EMAIL_CODE_ATTEMPTS
+    this.expiresAt = new Date(now.getTime() + EMAIL_CODE_LIFETIME_MS)
+  }
+
+  // Five wrong guesses out of a million leave nothing to brute-force: the code dies, and a new one must be sent.
+  check(codeHash: string, now: Date): CodeOutcome {
+    if (this.attemptsLeft <= 0 || this.expiresAt <= now) {
+      return 'expired'
+    }
+
+    if (codeHash === this.codeHash) {
+      this.attemptsLeft = 0
+      return 'valid'
+    }
+
+    this.attemptsLeft -= 1
+    return this.attemptsLeft === 0 ? 'expired' : 'wrong'
+  }
+}

package/templates/api/src/domain/auth/entities/identity.entity.ts

@@ -0,0 +1,18 @@
+import type { ProviderName } from '@/domain/auth/ports/identity-providers.port'
+
+// A user as a provider knows them. The provider's subject, not the email, is what recognises them next time: an
+// email can change at the provider, a subject cannot.
+export class Identity {
+  id: string
+  userId: string
+  provider: ProviderName
+  subject: string
+  createdAt: Date
+  updatedAt: Date
+
+  constructor(userId: string, provider: ProviderName, subject: string) {
+    this.userId = userId
+    this.provider = provider
+    this.subject = subject
+  }
+}