@stjoseph/prumo 0.2.0 → 0.4.0

package/.prumo-templates/mobile/storage.md

@@ -2,14 +2,15 @@
 
 ## Rule
 
-Put in `expo-secure-store` anything that **grants access if stolen**: the session cookie and any token.
+Put in `expo-secure-store` anything that **grants access if stolen**: the access and refresh tokens, and any
+other token.
 Put everything else in MMKV.
 
 Do not use MMKV's own encryption.
 
 Persist the TanStack Query cache to MMKV with a maximum age.
 
-On logout, clear the session, the persisted cache, and every MMKV key holding that user's data. Leave
+On logout, clear the tokens, the persisted cache, and every MMKV key holding that user's data. Leave
 device preferences (theme, language) untouched.
 
 Decide when writing each key whether it belongs to the user or to the device.
@@ -33,7 +34,7 @@ from one that opens blank with a spinner, which is what happens every time someb
 maximum age exists because a cache without one presents months-old data as current with no way for the
 user to tell.
 
-That persistence is also why logout must clear more than the session: switching users on one device would
+That persistence is also why logout must clear more than the tokens: switching users on one device would
 otherwise show the previous user's data. Wiping MMKV wholesale instead would take theme and language with
 it, so the same person returning finds the app as if it were new; security that punishes the common case
 gets switched off by somebody.
@@ -47,7 +48,7 @@ Every write to persistent storage, and the logout path.
 Choosing a store:
 
 ```
-✅  SecureStore: the session cookie
+✅  SecureStore: the access and refresh tokens
     MMKV:        theme, last opened tab, cached responses
 ❌  MMKV:        the session token        // works perfectly, protects nothing
 ```
@@ -62,8 +63,8 @@ Opening MMKV (version 4):
 Logout:
 
 ```
-✅  clear session + query cache + user-scoped MMKV keys, kept as one list the logout walks
-❌  clear session only
+✅  clear tokens + query cache + user-scoped MMKV keys, kept as one list the logout walks
+❌  clear tokens only
 ❌  MMKV.clearAll()          // takes theme and language too
 ```
 

package/.prumo-templates/monorepo/layout.md

@@ -30,9 +30,9 @@ Dockerfile.
 The integration package exists because the rest of the sharing was already refused: contract types are
 hand-written rather than generated, validation differs on each side, and shadcn copies components rather
 than sharing them. What genuinely repeats across clients is how a URL is built, how an error body becomes
-an `ApiError`, and what the contract's shapes are. Only transport differs (the web sends its cookie
-automatically, mobile attaches it from secure storage, a site's server calls anonymously), so transport
-comes from outside.
+an `ApiError`, what the contract's shapes are, and how an expired access token is refreshed. Only transport
+differs (the web sends its cookies automatically, mobile hands the auth client a store over secure storage, a
+site's server calls anonymously), so transport comes from outside.
 
 **This is also what recovers most of what hand-written types gave up.** That decision accepted, as its
 cost, that a renamed field leaves each client compiling against its own copy. One copy instead of three
@@ -65,7 +65,7 @@ The package's boundary:
 
 ```
 ✅  createClient({ fetch: myTransport })
-❌  the package calling fetch and reading a cookie itself
+❌  the package calling fetch and reading secure storage itself
 ```
 
 ## Enforcement

package/.prumo-templates/multi-tenancy/client.md

@@ -17,7 +17,7 @@ Never read the tenant from local storage or from a cached response to decide wha
 
 The query-key rule already says a key includes everything that changes the result, and the tenant changes
 the result. **But the tenant is invisible to whoever writes the query:** the server derives it from the
-session, so the client never sends it, never passes it as a filter, and never sees it in the calling code.
+access token, so the client never sends it, never passes it as a filter, and never sees it in the calling code.
 Nobody remembers to put it in a key, because nothing in the file suggests it exists. Adding it everywhere
 would be correct when remembered and silent when not; clearing once, in one place, does not depend on
 memory.
@@ -45,10 +45,10 @@ Every client of a multi-tenant project: `web`, `mobile` and `site` alike.
 Switching:
 
 ```
-✅  await organization.setActive({ organizationId })
+✅  await switchTenant(organizationId)                // the API re-issues the access token
     queryClient.clear()
     router.navigate({ to: '/' })
-❌  await organization.setActive({ organizationId })   // cache and route untouched
+❌  await switchTenant(organizationId)                // cache and route untouched
 ```
 
 Query keys:
@@ -78,6 +78,6 @@ client may choose.
 That the active tenant is on screen. Its absence breaks nothing and costs somebody a wrong action in the
 wrong account.
 
-**Known limit:** if the session's tenant changes without this app knowing (another tab switching), the
-cache is not cleared. That follows from the active organization living in the session, and is the cost that
-decision accepted.
+**Known limit:** if the session's tenant changes without this app knowing (another tab switching), this tab
+keeps its access token, and its tenant, until the next refresh, and then its cache is not cleared. That follows
+from the active organization living in the session, and is the cost that decision accepted.

package/.prumo-templates/multi-tenancy/isolation.md

@@ -5,14 +5,16 @@
 Derive the active tenant from the session. **Never from anything the client sends**: not a header, not a
 path parameter, not the `Host`.
 
-Use Better Auth's `organization` plugin with `activeOrganizationId` **persisted in the session**. Do not
-manage the active organization client-side.
+Keep organizations in the `auth` module: an `Organization` entity, and a `Membership` joining a user to one.
+Store the active tenant on the `Session` row, as `active_organization_id`, and copy it into the access token as
+a claim each time one is issued or refreshed. Switch tenants through one route that checks the membership,
+updates the session and issues a new access token. Do not manage the active organization client-side.
 
 Give every tenant-scoped table a `tenant_id` that is `NOT NULL` and carries a foreign key into
 `organization`, with `ON DELETE RESTRICT`.
 
 Register the MikroORM filter with `default: true` and set its parameter once per request, from the
-session.
+verified access token's claim.
 
 **Never accept `tenant_id` as a method argument.** Read it where the filter's parameter is read.
 
@@ -22,7 +24,8 @@ a comment saying it was checked.
 Declare a route that has no tenant. **Treat an absent filter parameter as an error**, never as "no
 filter".
 
-Run Better Auth's migrations before ours.
+When a membership ends, revoke that user's sessions with it, or the departed member keeps the tenant until the
+access token expires.
 
 ## Rationale
 
@@ -32,9 +35,13 @@ forgetting is invisible, because the route works perfectly for someone entitled
 someone who is not. A subdomain is input too: it arrives in a header a client controls and that proxies
 rewrite, so the defence would rest on infrastructure configuration.
 
-Better Auth's own documentation offers managing the active organization client-side, for multiple tabs. For
-a multi-tenant system that means the **tab** decides isolation, so it is refused here by name: somebody
-will find that sentence.
+Keeping the active organization in the client, per tab, is a common suggestion for working in two tenants at
+once. For a multi-tenant system that means the **tab** decides isolation, so it is refused here by name:
+somebody will find that suggestion.
+
+The claim is read from a token whose signature was just verified, so no request touches the database to learn
+its tenant. The cost is the token's lifetime: a membership removed now still reads for up to fifteen minutes,
+unless the sessions go with it, which is why the rule asks for both.
 
 The filter is an application-level guard, and its own documentation says a raw query or a forgotten
 `filters` option reads past it. It leaves three holes and they get different answers, because the problems
@@ -48,8 +55,8 @@ did not load, middleware in the wrong order) into a query that returns the whole
 
 The foreign key exists because without it a `tenant_id` pointing nowhere inserts cleanly and passes tests,
 leaving a row invisible to every filtered query. `RESTRICT` means deleting an organization with business
-data fails, which is wanted: the application should decide what happens to that data rather than a library
-CLI cascading it away.
+data fails, which is wanted: the application should decide what happens to that data rather than a cascade
+deciding for it.
 
 ## Applies to
 
@@ -64,7 +71,7 @@ decision rather than configuration.
 Where the tenant comes from:
 
 ```
-✅  const tenantId = session.activeOrganizationId
+✅  const tenantId = claims.organizationId          // from the verified access token
 ❌  const tenantId = req.headers['x-tenant-id']
 ❌  const tenantId = subdomainOf(req.headers.host)
 ```

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
@@ -88,9 +90,9 @@ is asked, and the exit code is 0 only when `ok` is true.
 
 | Type | What you get |
 |---|---|
-| `api` | Fastify with a domain/infra structure, tsyringe, Zod, MikroORM on PostgreSQL, Better Auth in a schema of its own, Swagger UI, Vitest with Testcontainers |
+| `api` | Fastify with a domain/infra structure, tsyringe, Zod, MikroORM on PostgreSQL, its own JWT authentication, Swagger UI, Vitest with Testcontainers |
 | `web` | Vite, React, TanStack Router and Query, Tailwind, shadcn/ui, forms validated with Zod |
-| `mobile` | Expo with Expo Router, NativeWind, MMKV, and the session kept in `expo-secure-store` |
+| `mobile` | Expo with Expo Router, NativeWind, MMKV, and the tokens kept in `expo-secure-store` |
 | `site` | Next on the App Router, static by default, for pages that have to be indexed |
 
 One type produces that project on its own. Several produce a pnpm workspace: each application under
@@ -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/clean.js

@@ -10,7 +10,7 @@ export const API_DEV_PREFIX = 'node scripts/database.mjs --check && ';
 export const ROOT_DEV_PREFIX = 'node apps/api/scripts/database.mjs --check && ';
 export const SETUP_SCRIPT = 'node scripts/database.mjs';
 export const EXAMPLE_BLOCK = '# MISSING until `pnpm db:setup` creates a database; `pnpm dev` offers to run it.\n' +
-    'DATABASE_URL=MISSING\nAUTH_DATABASE_URL=MISSING\n';
+    'DATABASE_URL=MISSING\n';
 export const README_PARAGRAPH = '`DATABASE_URL` starts as `MISSING`. While it is, `pnpm dev` offers to create the database first: it asks for a name,\n' +
     'starts Postgres from `docker-compose.yml` on port 5432 or the next free one (kept in `POSTGRES_PORT`), writes the URL\n' +
     'into `.env`, and migrates. `pnpm db:setup` does the same at any time. Without a terminal every answer comes from a\n' +
@@ -51,7 +51,7 @@ function rulesFor(root, api, templates) {
     const rules = [
         devRule('api-dev-check', at('package.json'), API_DEV_PREFIX),
         scriptRule('api-db-setup', at('package.json'), 'Remove the `db:setup` script', 'db:setup', (value) => value === SETUP_SCRIPT ? { status: 'pending' } : { status: 'modified', next: value }),
-        textRule('api-env-example', at('.env.example'), 'Put a sample database URL back in `.env.example`', EXAMPLE_BLOCK, `DATABASE_URL=${SAMPLE_URL}\nAUTH_DATABASE_URL=${SAMPLE_URL}\n`, '=MISSING'),
+        textRule('api-env-example', at('.env.example'), 'Put a sample database URL back in `.env.example`', EXAMPLE_BLOCK, `DATABASE_URL=${SAMPLE_URL}\n`, '=MISSING'),
         textRule('api-readme-setup', at('README.md'), 'Replace the README paragraph about `MISSING`', README_PARAGRAPH, README_REPLACEMENT, 'db:setup'),
         textRule('api-readme-row', at('README.md'), 'Remove `db:setup` from the README', README_ROW, '', '`pnpm db:setup`'),
     ];

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, mobileScheme = 'app', 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));
@@ -199,14 +199,6 @@ export async function composeWorkspace({ templates, target, types, mobileScheme
     else {
         await rm(join(target, 'packages'), { recursive: true, force: true });
     }
-    if (types.includes('api') && types.includes('mobile')) {
-        await rewriteText(join(target, 'apps', 'api', '.env.example'), (text) => {
-            if (!text.includes('# MOBILE_APP_SCHEME=app\n')) {
-                throw new Error('apps/api/.env.example no longer carries the commented MOBILE_APP_SCHEME line');
-            }
-            return text.replace('# MOBILE_APP_SCHEME=app\n', `MOBILE_APP_SCHEME=${mobileScheme}\n`);
-        });
-    }
     // One command for everything and one per app. Each app answers to `dev`, so the root never needs to know how.
     // The database and the ports are the exception: both may ask a question, which the interleaved output of a
     // parallel run would bury, so the root asks first and each app's own check then finds nothing to do.

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`);