@stjoseph/prumo 0.3.0 → 0.4.0

package/.prumo-templates/api/auth.md

@@ -52,8 +52,9 @@ one in a body. A cookie is also sent by the browser whoever wrote the page, whic
 answers: a request leaning on a cookie must come from the web app. A native app has no cookie jar and no
 Origin, so it carries a bearer and passes.
 
-**What this costs:** the security of sign-in is this code's. There is no upstream fix to wait for, and no
-reset of a password, verification of an email or social sign-in until one is written.
+**What this costs:** the security of sign-in is this code's. There is no upstream fix to wait for. Email
+verification, password reset and social sign-in are questions `prumo new` asks; a project that answered no to
+them has none of them until they are written.
 
 ## Applies to
 

package/.prumo-templates/core/testing.md

@@ -55,10 +55,11 @@ been published since January 2024. Every other rule here (placement, no database
 behaviour) holds unchanged. **What it costs:** two runners in one workspace with near-identical APIs, so `vi.fn`
 written in a mobile test is a mistake an assistant will make.
 
-**Two things a mobile test meets, verified with Expo SDK 57:** `render` from `@testing-library/react-native` 14
-is **asynchronous** and its matchers need no setup. And `expo-secure-store` needs the native Keychain or Keystore,
+**Three things a mobile test meets, verified with Expo SDK 57:** `render` from `@testing-library/react-native` 14
+is **asynchronous** and its matchers need no setup. `expo-secure-store` needs the native Keychain or Keystore,
 which Jest does not have, so a test builds the auth client with an in-memory token store, which is why a form
-asks only for the auth methods it calls.
+asks only for the auth methods it calls. And `jest-expo` leaves the app manifest empty, so `expo-linking` cannot
+know the app's scheme: a test that reaches `Linking.createURL` mocks it with the scheme it expects.
 
 A coverage threshold turns a proxy into a target. Whoever is below writes tests to raise the number rather
 than to check anything; whoever is above stops thinking. With no database mocks a test costs more to write,

package/.prumo-templates/email/codes.md

@@ -0,0 +1,62 @@
+# Email codes
+
+## Rule
+
+Confirm an email address and reset a password with a **6-digit code** sent by mail, never a link. One flow
+serves the web and the mobile app alike.
+
+Keep one live code per user and purpose (`verify-email`, `reset-password`) in `email_code`. A code lives
+**15 minutes** and allows **5 attempts**; the fifth wrong one kills it. Sending another replaces it, and the old
+one stops working. Store only its HMAC-SHA256, keyed with `JWT_SECRET`.
+
+Open no session at sign-up: answer `201 { verificationRequired: true }` and send the code. Refuse sign-in to an
+unconfirmed account with **403** and `code: 'email_not_verified'`, and only after the password matched. Sign
+the user in when the code is confirmed.
+
+On a password reset, set the new password, mark the email confirmed, and revoke every session of the user before
+starting a new one.
+
+Answer `/email/verification` and `/password/forgot` with 204 whether or not the email has an account, and a
+wrong code, a dead one and an unknown email with the same `422 invalid_code`.
+
+Read the outcome of a sign-up and of a refused sign-in in the client: `verificationRequired` and
+`email_not_verified` both lead to the code screen, which offers to send a new code.
+
+## Rationale
+
+A link needs a page to open: easy on the web, and a deep link with universal links on mobile. A code is typed
+the same way everywhere, so there is one flow, one set of screens and one set of tests.
+
+Six digits are a million possibilities, which is why the attempts are counted and the lifetime short: five
+guesses against a million cannot succeed by luck. The hash is keyed because a million codes hash in a moment,
+so an unkeyed digest in a database copy would give every live code away.
+
+Every answer that could say whether an email has an account says the same thing instead, so these routes cannot
+be used to find out who signed up. Asking for confirmation only after the password matched keeps that true at
+sign-in too.
+
+A reset revokes every session because whoever knew the old password may have opened one, and the reset is often
+the reaction to exactly that.
+
+## Applies to
+
+`src/domain/auth/` for the codes, `auth-email.controller.ts`, and the code, forgot-password and reset-password
+screens on the web and mobile.
+
+## Examples
+
+```
+✅  POST /api/auth/password/forgot  → 204 for any email
+❌  POST /api/auth/password/forgot  → 404 "no account with this email"
+
+✅  sign-in with the right password, unconfirmed → 403 email_not_verified
+❌  sign-in, unconfirmed, before checking the password → 403        // tells anyone the account exists
+```
+
+## Enforcement
+
+**Tests.** `email.use-case.spec.ts` covers the dead code after five guesses, the replaced code, the unknown email
+and the reset revoking sessions. `auth-email.controller.spec.ts` covers the HTTP answers, and the clients'
+`email-flows.spec.tsx` the screens.
+
+**Review only.** That a new mail with a code goes through `IssueEmailCodeUseCase`, so it keeps the same limits.

package/.prumo-templates/email/mailer.md

@@ -0,0 +1,47 @@
+# Mailer
+
+## Rule
+
+Send every email through the `Mailer` port in `src/domain/auth/ports/mailer.port.ts`. A use case composes the
+`Mail` (`to`, `subject`, `text`) and hands it over; nothing else in the domain knows how mail travels.
+
+Keep `LogMailer`, which writes each mail to the API's log, as the adapter until the project sends real mail.
+Read a code during development from that log.
+
+To send real mail, write a second adapter under `src/infra/email/` and register it in `email.di.ts` in place of
+`LogMailer`, for production only. Either speak SMTP, with `nodemailer` and an `SMTP_URL` any provider accepts, or
+call a provider's HTTP API. Validate the new variable in `env.ts`.
+
+In a test, register a `FakeMailer` and read the code from it, as `test/support/test-app.ts` does.
+
+## Rationale
+
+Sending mail needs an account with somebody, and choosing one is a commercial decision the project's owner
+makes, not the template. So the template ships the port and an adapter that needs nothing, and the flows that
+depend on mail work end to end from the first `pnpm dev`: the code is in the terminal.
+
+The port is the whole contract on purpose. SES, Postmark, Resend, Mailgun and a company relay all accept the
+same three fields, so changing provider is one new adapter and one line in the container.
+
+**What this costs:** until an adapter is written, a deployed API sends nothing, and a user waiting for a code
+never receives it. Nothing warns about that but this document.
+
+## Applies to
+
+Every email the API sends, now and later: codes, invitations, receipts.
+
+## Examples
+
+```
+✅  await this.mailer.send({ to, subject, text })
+❌  await fetch('https://api.provider.example/send', …)     // inside a use case
+
+✅  container.register(MAILER, { useValue: new SmtpMailer(env) })   // production adapter
+❌  if (env.NODE_ENV === 'production') { … }               // inside LogMailer
+```
+
+## Enforcement
+
+**Tests.** The suite reads every code through `FakeMailer`, so a flow that stops sending mail fails.
+
+**Review only.** That production registers a real adapter. `LogMailer` in production loses mail silently.

package/.prumo-templates/mcp/server.md

@@ -11,8 +11,10 @@ Build the server per request in `src/infra/mcp/mcp.server.ts` with `createMcpHan
 `@modelcontextprotocol/server`, `legacy: 'reject'`. The user is the token's `sub`, passed through
 `authInfo.extra.userId`.
 
-Write a module's tools in `src/infra/mcp/tools/<module>.tool.ts`. A tool resolves a use case and calls
-`execute()`, exactly as a route handler does. Take its input schema from the module's `dto/`, and pass its
+Write a module's tools in `src/infra/mcp/tools/<module>.tool.ts`, with the scope each one needs beside it:
+`<module>:read` to read the module's data, `<module>:write` to change it. Add the module's two scopes to
+`SCOPES` in `mcp.scopes.ts`, worded for a person, and its tools to `TOOL_SCOPES`. A tool resolves a use case and
+calls `execute()`, exactly as a route handler does. Take its input schema from the module's `dto/`, and pass its
 result through the module's output schema with `.parse()` before returning it.
 
 Keep the authorization server in the `oauth` module and `oauth.controller.ts`, following MCP's 2026-07-28
@@ -28,6 +30,11 @@ authorization profile:
 - Return the code with `iss` (RFC 9207), and spend it once: a code presented twice revokes the session its
   first exchange started.
 - Rotate refresh tokens, and accept one only from the client it was issued to.
+- Grant the scopes the client asked for, all of `SCOPES` when it asked for none, and refuse an unknown one with
+  `invalid_scope`. Carry them in the session, its access token and every refresh. Advertise them in both metadata
+  documents and in the 401.
+- Refuse a `tools/call` the token's scopes do not cover before the server runs it: 403 with
+  `WWW-Authenticate: Bearer error="insufficient_scope", scope="…"`, every scope the call needs in one challenge.
 - Fetch a metadata document over https only, at most 5 KB and 5 seconds, following no redirect, and never from
   a private, loopback or link-local address, checked at the connection's own lookup.
 
@@ -49,8 +56,13 @@ without the address check, a client could make the API read its own network. The
 connection's lookup, so a name that resolves differently a second time cannot slip past it, and a literal
 address is checked before connecting because no lookup happens for one.
 
-**What this costs:** no scopes. A tool acts with everything the user may do, and adding scopes is a change to
-this module and to the consent page.
+Scopes are per module and per kind of access because a client that only reads should not be able to change
+anything, and because a list worded per tool would grow past what a consent page can make readable. The call is
+refused at the HTTP edge, with the scopes it needs, because that is the answer MCP's step-up flow reads: the
+client asks the user for more and comes back.
+
+**What this costs:** a new module's tools need their scopes written in two places, the tool file and
+`mcp.scopes.ts`.
 
 ## Applies to
 
@@ -72,7 +84,9 @@ web app's `/consent` route.
 
 ## Enforcement
 
-**Tests.** `mcp.controller.spec.ts` walks discovery from the 401, the authorization, consent and the token, then
+**Tests.** `mcp.controller.spec.ts` fails when a tool the server lists has no scope in `TOOL_SCOPES`, lets a
+read-only token read and refuses its write with `insufficient_scope`,
+keeps the scope through a refresh, and refuses an unknown scope. It also walks discovery from the 401, the authorization, consent and the token, then
 connects the SDK's own client and asserts a tool returns only the public fields. It also refuses an unknown
 client without redirecting, a missing or plain PKCE, another resource, a wrong verifier, a code spent twice,
 another client's refresh token, and each token where the other belongs. `https-client-metadata.adapter.spec.ts`

package/.prumo-templates/social/sign-in.md

@@ -0,0 +1,77 @@
+# Social sign-in
+
+## Rule
+
+Sign in with a provider through the API, never from a client: the client opens
+`/api/auth/social/<provider>?client=web|mobile`, the API runs OpenID Connect with `openid-client` behind the
+`IdentityProviders` port, and the client comes back signed in. Add a provider in the adapter's `settings()`, its
+variables in `env.ts`, and its button on each client.
+
+Store each trip in `social_sign_in`: its id is OAuth's `state`, and the browser that started it holds a secret
+in the `social_sign_in` cookie that the callback must present. Use PKCE wherever the provider's metadata announces
+it, and a nonce always. Turn Apple's `form_post` callback into a redirect to the same address, so the cookie
+comes with it.
+
+Return the web to the path it asked for, only a path on the web app, with session cookies. Return a mobile app
+to `MOBILE_APP_SCHEME://social` with a one-time code it exchanges at `/api/auth/social/exchange` for its tokens,
+within two minutes. A mobile app opens the trip with `expo-web-browser`'s `openAuthSessionAsync`.
+
+Recognise a returning user by the provider's subject, kept in `identity`. For a first sign-in, link by email
+only when the provider says `email_verified`:
+
+- an account whose email was confirmed is the same person: link it;
+- an account whose email was never confirmed loses its password and every session, then is linked: the
+  provider's proof wins over whoever chose that password;
+- no account: create one, confirmed and without a password, with its profile.
+
+Refuse a provider email that is not verified.
+
+When the project has a mobile app and offers Google, offer Apple too before publishing on iOS.
+
+## Rationale
+
+The API keeps the client secret and validates the ID token, so neither a browser nor an app ever holds a
+provider's secret or decides what an ID token says.
+
+The cookie binds the trip to one browser. Without it, someone could start a sign-in with their own provider
+account and get a victim to open the callback, signing the victim into the attacker's account, which then
+records whatever the victim does. The mobile code exists so that tokens never travel in a URL, where logs and
+history keep them.
+
+The linking rules close a known attack: register a password account with somebody's email before they arrive,
+then wait for them to sign in with a provider. A library this project once used shipped exactly that hole. An
+account nobody confirmed belongs to whoever proves the inbox, and that proof is what the provider gives.
+
+The App Store asks an app offering a third-party login for its primary account to offer an equivalent
+privacy-preserving login too (App Review Guideline 4.8); Sign in with Apple is one.
+
+**What this costs:** the trip leaves the app for the system browser and comes back, rather than a native sheet.
+In a project that does not verify emails, no password account is ever confirmed, so the first time its owner
+signs in with a provider for that email, the password goes: the owner keeps the account through the provider,
+and cannot tell them apart from whoever registered the email first.
+And a provider without its variables in `.env` answers that it is not configured, until someone registers the
+application with it.
+
+## Applies to
+
+`src/domain/auth/` for identities and trips, `social.controller.ts`, `src/infra/social/`, and the social buttons on
+the web and mobile.
+
+## Examples
+
+```
+✅  a href={auth.socialSignInUrl('google', 'web', redirect)}
+❌  window.location = 'https://accounts.google.com/o/oauth2/v2/auth?client_id=…'   // the client talks to Google
+
+✅  link only when email_verified, and void an unconfirmed account's password
+❌  link whenever the emails match
+```
+
+## Enforcement
+
+**Tests.** `social.use-case.spec.ts` covers each linking rule and refuses a callback from another browser, a
+second use and another provider. `openid-identity-providers.adapter.spec.ts` runs the real adapter against a
+local OpenID provider: PKCE, state, nonce, a forged code, and Apple's client secret signed with the `.p8` key.
+`social.controller.spec.ts` covers both clients over HTTP.
+
+**Review only.** That a new provider's ID token is validated by `openid-client` before anything reads it.

package/README.md

@@ -58,7 +58,7 @@ terminal a missing answer is an error rather than a default, so nothing importan
 silence:
 
 ```sh
-npx @stjoseph/prumo new my-app --types api,web --single-tenant --no-mcp
+npx @stjoseph/prumo new my-app --types api,web --single-tenant --no-mcp --email --no-social
 ```
 
 | Flag | What it answers |
@@ -67,6 +67,8 @@ npx @stjoseph/prumo new my-app --types api,web --single-tenant --no-mcp
 | `--alone` or `--monorepo` | How a single type is laid out |
 | `--multi-tenant` or `--single-tenant` | Whether the application serves several tenants. Multi-tenant ships the `multi-tenancy` conventions; the generated code itself is not tenant-aware yet |
 | `--mcp` or `--no-mcp` | With an api and a web: whether AI assistants reach the API through MCP, signed in as the user |
+| `--email` or `--no-email` | With an api: email verification and password reset, by a 6-digit code sent through the `Mailer` port, which writes to the log until you give it a provider |
+| `--social google,apple` or `--no-social` | With an api and a web or mobile: sign-in with Google, Apple, or both |
 | `--skip-install` | Stops after writing the files |
 
 ## Commands
@@ -106,13 +108,13 @@ a month apart are the same project.
 
 | File | What it is |
 |---|---|
-| `.prumo/` | The conventions, in ten areas. Only the areas the answers call for are copied |
+| `.prumo/` | The conventions, in twelve areas. Only the areas the answers call for are copied |
 | `.prumo/INDEX.md` | One line per document. Generated by the tool, and safe to regenerate |
 | `AGENTS.md` | The pointer into `.prumo/`, read by Codex, Cursor, Copilot, Gemini CLI and others |
 | `CLAUDE.md` | An `@AGENTS.md` import, for Claude Code |
 
-The ten areas are `core`, `api`, `database`, `client`, `web`, `mobile`, `site`, `monorepo`,
-`multi-tenancy` and `mcp`. Only `core` ships unconditionally, because everything in it is true of every type;
+The twelve areas are `core`, `api`, `database`, `client`, `web`, `mobile`, `site`, `monorepo`,
+`multi-tenancy`, `mcp`, `email` and `social`. Only `core` ships unconditionally, because everything in it is true of every type;
 the rest follow the answers, since advice about a platform the project does not have is worse than
 no advice at all.
 

package/dist/asker.js

@@ -1,4 +1,5 @@
 import * as prompt from '@clack/prompts';
+import { SOCIAL_PROVIDERS } from "./features.js";
 const TYPES = ['api', 'web', 'mobile', 'site'];
 function answered(value) {
     if (prompt.isCancel(value)) {
@@ -28,5 +29,17 @@ export function terminalAsker(validateName) {
             message: 'Let AI assistants use the API through MCP, signed in as the user?',
             initialValue: false,
         })),
+        email: async () => answered(await prompt.confirm({
+            message: 'Verify emails and let users reset their password?',
+            initialValue: false,
+        })),
+        social: async () => answered(await prompt.multiselect({
+            message: 'Social sign-in? Leave all unselected for none',
+            options: SOCIAL_PROVIDERS.map((provider) => ({
+                value: provider,
+                label: provider === 'google' ? 'Google' : 'Apple',
+            })),
+            required: false,
+        })),
     };
 }

package/dist/cli.js

@@ -34,6 +34,10 @@ async function runNew(args, json) {
             'single-tenant': { type: 'boolean', default: false },
             mcp: { type: 'boolean', default: false },
             'no-mcp': { type: 'boolean', default: false },
+            email: { type: 'boolean', default: false },
+            'no-email': { type: 'boolean', default: false },
+            social: { type: 'string' },
+            'no-social': { type: 'boolean', default: false },
             'skip-install': { type: 'boolean', default: false },
             json: { type: 'boolean', default: false },
         },
@@ -62,11 +66,21 @@ async function runNew(args, json) {
         singleTenant: values['single-tenant'],
         mcp: values.mcp,
         noMcp: values['no-mcp'],
+        email: values.email,
+        noEmail: values['no-email'],
+        social: values.social,
+        noSocial: values['no-social'],
     }, interactive ? terminalAsker((input) => projectProblem(input, cwd)) : undefined, cwd);
     if (!json && answers.types.length > 1) {
         prompt.log.info(`${answers.types.length} types make a workspace: apps/ and packages/ under one root.`);
     }
-    const { target, ...chosen } = answers;
+    const { target, warnings, ...chosen } = answers;
+    // Without --json a person is reading; with it, the warnings travel in the result instead.
+    if (!json) {
+        for (const warning of warnings) {
+            prompt.log.warn(warning);
+        }
+    }
     await generate({
         ...requireAssets(assetsFor(import.meta.dirname)),
         target,
@@ -77,7 +91,7 @@ async function runNew(args, json) {
     if (!json) {
         prompt.outro(`Created ${answers.name}.`);
     }
-    return { data: { ...chosen, target, installed: install }, text: '' };
+    return { data: { ...chosen, target, installed: install, warnings }, text: '' };
 }
 async function runClean(args, json) {
     const { values } = parseArgs({

package/dist/commands.js

@@ -18,6 +18,13 @@ export const COMMANDS = [
             { flag: '--single-tenant', description: 'No multi-tenancy conventions' },
             { flag: '--mcp', description: 'An MCP server on the api, authorized through the web' },
             { flag: '--no-mcp', description: 'No MCP server' },
+            {
+                flag: '--email',
+                description: 'Email verification and password reset, by a code sent through the Mailer port',
+            },
+            { flag: '--no-email', description: 'Neither' },
+            { flag: '--social <list>', description: 'Comma-separated: google, apple' },
+            { flag: '--no-social', description: 'No social sign-in' },
             { flag: '--skip-install', description: 'Do not run pnpm install' },
             JSON_OPTION,
         ],

package/dist/compose.js

@@ -1,8 +1,8 @@
 import { existsSync } from 'node:fs';
 import { cp, mkdir, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { join, relative, sep } from 'node:path';
+import { applyFeatures, NONE } from "./features.js";
 import { prependProperty, readJsonc, removeWhatBaseDeclares, setJsonc } from "./jsonc.js";
-import { applyMcp } from "./mcp.js";
 const CLIENTS = ['web', 'mobile'];
 // One exception to one-version-per-dependency: stable NativeWind needs Tailwind 3.
 const NAMED_CATALOGS = [{ name: 'tailwind3', dependency: 'tailwindcss', major: '3' }];
@@ -182,14 +182,14 @@ async function assertCatalogCovers(target, catalog) {
         }
     }
 }
-export async function composeWorkspace({ templates, target, types, mcp = false, }) {
+export async function composeWorkspace({ templates, target, types, features = NONE, }) {
     await mkdir(target, { recursive: true });
     await copyTemplate(join(templates, 'workspace'), target);
     const apps = [];
     for (const type of types) {
         const app = await copyApp(templates, target, type);
         // Before the catalog is collected, so a dependency that leaves never reaches it.
-        await applyMcp(app, type, mcp);
+        await applyFeatures(app, type, features);
         apps.push(app);
     }
     const clients = CLIENTS.filter((client) => types.includes(client));

package/dist/context.js

@@ -12,6 +12,8 @@ export function areasFor(answers) {
         ...(answers.architecture === 'monorepo' ? ['monorepo'] : []),
         ...(answers.multiTenant ? ['multi-tenancy'] : []),
         ...(answers.mcp ? ['mcp'] : []),
+        ...(answers.email ? ['email'] : []),
+        ...(answers.social.length > 0 ? ['social'] : []),
     ];
 }
 async function titleOf(path) {
@@ -36,6 +38,8 @@ export async function writeContext(knowledge, root, answers) {
         architecture: answers.architecture,
         multiTenant: answers.multiTenant,
         mcp: answers.mcp,
+        email: answers.email,
+        social: answers.social,
     };
     await writeFile(join(prumo, 'config.json'), `${JSON.stringify(config, null, 2)}\n`);
     await writeFile(join(root, 'AGENTS.md'), `# ${answers.name}\n\nThis project's conventions live in \`.prumo/\`. Read [\`.prumo/INDEX.md\`](.prumo/INDEX.md) before changing how something is done.\n`);