@boopkit/cap-users 0.1.0 → 0.3.0

package/README.md

@@ -0,0 +1,142 @@
+# @boopkit/cap-users
+
+**Part of [Boop](https://www.npmjs.com/package/@boopkit/cli)** — a bootstrap platform for AI-first builders. `boop init` scaffolds a running Node/TypeScript web app from composable **capabilities**, each one bundling the code, dependencies, middleware wiring, and agent skills needed for a feature. You pick the capabilities; `boop add` handles the rest.
+
+`cap-users` is the accounts-and-auth layer. It gives your app users, identities, accounts, properties, and cookie-based session authentication — backed by Prisma models, factory-built services, and Express middleware that resolves the current user on every request. Signup, login, and logout work out of the box; you get a trust-tier model (`recognized` / `authenticated` / `verified`) and a `requireAuth()` gate you can drop in front of any route.
+
+## What You Get
+
+### Scaffold files
+
+Copied into your project on install:
+
+- `prisma/schema/users.prisma` — `User`, `UserIdentity`, `UserProperty` models
+- `prisma/schema/accounts.prisma` — `Account`, `AccountUser`, `AccountProperty` models
+- `src/services/users.service.ts` — wires `userService`, `identityService`, `userPropertyService`, `authService` to Prisma
+- `src/services/accounts.service.ts` — wires `accountService`, `accountPropertyService`, `accountManagementService`, `teamInvitationService`
+- `src/middleware/auth.ts` — `ensureVisitor`, `addAuthContext`, `requireAuth` middleware instances
+- `src/controllers/auth.ts` — signup, login, logout, forget-device controllers
+- `src/routes/auth.ts` — Express router mounting `/signup`, `/login`, `/logout`, `/logout/forget`
+- `views/signup.hbs`, `views/login.hbs`, `views/partials/auth-nav.hbs` — auth views and nav partial
+- `styles/auth.css` — semantic styles for the auth views
+- `reference/user-auth.ref.md` — reference doc explaining the four-layer auth model
+
+### Server hooks
+
+Wired into `src/server.ts` at install time:
+
+```ts
+import cookieParser from 'cookie-parser';
+import { ensureVisitor, addAuthContext, authRoutes } from './middleware/auth';
+import AccountService from './services/accounts.service';
+
+// ...
+
+app.use(cookieParser());   // order 14
+app.use(ensureVisitor);    // order 15 — resolve session from auth_id cookie
+app.use(addAuthContext);   // order 16 — populate res.locals.auth for views
+app.use(authRoutes);       // order 52 — mount /signup, /login, /logout
+```
+
+`middleware/auth.ts` imports `UserService` transitively and builds the middleware + router from it, so the wiring stays in one place. `ensureVisitor` runs on every request; if the `auth_id` cookie is missing or stale it creates an anonymous `User` with a fresh session — every visitor has an identity from their first request, whether they've signed up or not. Login upgrades the trust tier on the same underlying user.
+
+### Skills installed
+
+Copied into `skills/` on install:
+
+- `design.user-data-modeling.skill.md` — teaches agents where user-related data belongs: when to use `User.info` vs. `UserProperty`, why `User` / `Account` / `AccountUser` are distinct, and how to spot misplaced fields in review. Pairs with `reference/user-auth.ref.md`.
+
+### Post-install
+
+1. Run the database migration: `npm run db:migrate -- --name add-users-and-accounts`
+2. Generate the Prisma client: `npm run db:generate`
+3. Add `{{> auth-nav}}` inside `<body>` in your `views/layouts/main.hbs`, before your main content.
+
+`boop status` reminds you of these steps.
+
+## Requirements
+
+**Other capabilities:**
+
+- `cap-database` — Prisma schema merging and migration tooling
+- `cap-services` — service factory pattern and boot-time `loadServices()` auto-discovery
+- `cap-web` — Handlebars view engine (the `/signup` and `/login` pages render as server-side views)
+
+**npm dependencies added to your project:**
+
+- `bcryptjs` — password hashing
+- `cookie-parser` — parse the `auth_id` session cookie
+- `@boopkit/cap-users` — this package (exported services, middleware factories, and types)
+
+**External services:**
+
+- **PostgreSQL** — required by the `cap-database` capability. The user and account tables are created by `npm run db:migrate`.
+
+**Environment variables:**
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `SESSION_DURATION` | Optional | `604800` (7 days) | Session token lifetime in **seconds** |
+| `INVITATION_TTL` | Optional | `604800000` (7 days) | Team invitation expiry in **milliseconds** |
+
+No secrets required — session tokens are generated with `crypto.randomBytes` and stored hashed.
+
+## Usage
+
+The middleware, routes, and views give you working signup and login immediately. Here's how to protect a page behind authentication and read the current user.
+
+**1.** Protect a route with `requireAuth()`:
+
+```ts
+// src/routes/pages.ts
+import { Router } from 'express';
+import { requireAuth } from '../middleware/auth';
+import * as pages from '../controllers/pages';
+
+const router = Router();
+
+router.get('/', pages.home);
+router.get('/dashboard', requireAuth(), pages.dashboard);   // authenticated required
+router.get('/account', requireAuth('verified'), pages.account); // verified (2FA-style) required
+
+export default router;
+```
+
+Unauthenticated web requests are redirected to `/login?next=<original-url>`. API requests (paths under `/api/`) get a `401 { error: 'Unauthorized' }` response instead.
+
+**2.** Read the current user in a controller:
+
+```ts
+// src/controllers/pages.ts
+import type { Request, Response } from 'express';
+import type { User, BaseUserInfo } from '@boopkit/cap-users';
+
+export function dashboard(req: Request, res: Response): void {
+  const user = (req as Request & { user: User<BaseUserInfo> }).user;
+  res.render('dashboard', { email: user.info.email });
+}
+```
+
+`req.user` is set by `ensureVisitor` on every request. For views, `res.locals.auth` is populated by `addAuthContext` with `trustTier`, `userName`, `userEmail`, and `userInitial` — the `auth-nav` partial uses these to show the right sign-in / sign-out affordances.
+
+### Extending the user shape
+
+User and account domain data live in JSON `info` columns typed by `BaseUserInfo` / `BaseAccountInfo`. To add project-specific fields, declare your own interface and pass it as a type parameter:
+
+```ts
+// src/services/users.service.ts
+interface MyUserInfo extends BaseUserInfo {
+  department: string;
+  role: 'admin' | 'member';
+}
+
+const userService = createUserService<MyUserInfo>(db.user);
+```
+
+No migration needed — the JSON column holds any shape. See `reference/user-auth.ref.md` for the full four-layer model (Identity / Authentication / Credentials / Authorization) and the trust-tier semantics.
+
+## Added by
+
+```bash
+boop add users-and-accounts
+```

package/capability.json

@@ -20,17 +20,15 @@
     "styles/auth.css",
     "reference/user-auth.ref.md"
   ],
-  "skills": [],
+  "skills": ["design.user-data-modeling.skill.md"],
   "hooks": [
     { "phase": "imports", "code": "import cookieParser from 'cookie-parser';", "description": "cookie parsing for session tokens" },
-    { "phase": "imports", "code": "import UserService from './services/users.service';", "description": "user service wiring" },
-    { "phase": "imports", "code": "import { ensureVisitor, addAuthContext } from './middleware/auth';", "description": "auth middleware — session resolution and trust context" },
-    { "phase": "imports", "code": "import authRoutes from './routes/auth';", "description": "auth route definitions" },
+    { "phase": "imports", "code": "import { ensureVisitor, addAuthContext, authRoutes } from './middleware/auth';", "description": "auth middleware and routes — session resolution, trust context, signup/login/logout" },
     { "phase": "imports", "code": "import AccountService from './services/accounts.service';", "description": "account service wiring" },
     { "phase": "preRoutes", "order": 14, "code": "app.use(cookieParser());", "description": "parse cookies (required for auth session resolution)" },
     { "phase": "preRoutes", "order": 15, "code": "app.use(ensureVisitor);", "description": "resolve visitor identity from auth_id cookie" },
     { "phase": "preRoutes", "order": 16, "code": "app.use(addAuthContext);", "description": "populate res.locals.auth for view templates" },
-    { "phase": "preRoutes", "order": 52, "code": "app.use(authRoutes({ authService: UserService.authService }));", "description": "mount auth routes (signup, login, logout)" }
+    { "phase": "preRoutes", "order": 52, "code": "app.use(authRoutes);", "description": "mount auth routes (signup, login, logout)" }
   ],
   "env": [
     { "name": "SESSION_DURATION", "description": "Session token lifetime in seconds (default: 7 days)", "default": "604800", "required": "runtime" },

package/package.json

@@ -1,24 +1,26 @@
 {
   "name": "@boopkit/cap-users",
-  "version": "0.1.0",
-  "description": "User data service factories — typed CRUD for users, identities, and user properties",
+  "version": "0.3.0",
+  "description": "User accounts, authentication, and session management via Prisma",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist/",
     "scaffold/",
+    "skills/",
     "capability.json"
   ],
   "boopkit": {
     "capability": true,
     "scaffoldDir": "scaffold",
+    "skillsDir": "skills",
     "manifest": "capability.json"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json"
   },
   "dependencies": {
-    "@boopkit/cap-services": "^0.1.0",
+    "@boopkit/cap-services": "^0.3.0",
     "bcryptjs": "^2.4.3"
   },
   "devDependencies": {

package/scaffold/src/middleware/auth.ts

@@ -1,10 +1,8 @@
-/** @boopkit/cap-users Auth middleware — session resolution + trust checking. */
+/** @boopkit/cap-users — Auth middleware and routes, pre-wired from UserService. */
 
-import type { Express } from 'express';
 import { createAuthMiddleware } from '@boopkit/cap-users';
-
-// Import user services — adjust path if your service wiring is elsewhere
 import UserService from '../services/users.service';
+import createAuthRouter from '../routes/auth';
 
 const { authService, identityService, userService } = UserService;
 
@@ -16,13 +14,7 @@ const { ensureVisitor, addAuthContext, requireAuth } = createAuthMiddleware(
   },
 );
 
-/**
- * Wire auth middleware into the Express app.
- * Call at preRoutes order 15 (after requestId, before routes).
- */
-export function setupAuth(app: Express): void {
-  app.use(ensureVisitor);
-  app.use(addAuthContext);
-}
+/** Pre-built auth routes (signup, login, logout). Ready to mount with app.use(). */
+const authRoutes = createAuthRouter({ authService });
 
-export { ensureVisitor, addAuthContext, requireAuth };
+export { ensureVisitor, addAuthContext, requireAuth, authRoutes };

package/skills/design.user-data-modeling.skill.md

@@ -0,0 +1,73 @@
+# User Data Modeling
+When you need to add, store, or query a field related to users, identities, or accounts in a boop project, decide *where* the field belongs before writing the schema or service.
+
+## Goal
+**`User.info` and `UserProperty` aren't "common vs. sparse" — they're "denormalized quick-access" vs. "named independent concerns."**
+
+`User.info` is a single JSON column returned with every basic user query. It holds the handful of core fields you want to travel with the user every time — display name, user type, email-verified flag. One `infoSchema` governs the whole blob. One `revision` tracks any update, so every write to `.info` contends with every other.
+
+`UserProperty` is one row per named concern (`(userId, property)`). Each property has its own `info`, its own `infoSchema`, and its own `revision`. You only load a property when a feature needs it; writes to one property don't contend with writes to `.info` or other properties.
+
+Most new user data belongs in a property. The question is not "does every user have it" — plenty of properties apply to every user (notification prefs, onboarding state). The question is "does this evolve alone, or does it move with the rest of the user's core identity?"
+
+The rest of the cap-users model — `Account`, `AccountUser`, `UserIdentity` — follows the same logic: distinct concerns get distinct tables so they can evolve, scale, and be secured independently.
+
+## Decision tree
+
+Before adding a field, work through these in order. The first "yes" wins.
+
+**1. Is this how the user logs in?** (email, OAuth `provider+id`, magic-link token)
+→ `UserIdentity`. One row per identity. Never put credentials or login identifiers on `User.info` — a human can have many identities, and changing one shouldn't touch the user record.
+
+**2. Is this about the org, not the person?** (company name, plan tier, billing address)
+→ `Account.info` for denormalized account-level identity, or `AccountProperty` for standalone account-scoped concerns. Same denormalized-vs-independent split as User.
+
+**3. Is this about how the user participates in a specific account?** (role, invited_by, joined_at)
+→ `AccountUser.info`. A user in two accounts can hold different roles in each — this field varies per membership, not per user.
+
+**4. Is this part of the user's core identity, loaded with the user every time?** (display name, user type, email-verified flag, timezone)
+→ `User.info`. Shape is governed by `infoSchema`; bump it when you add, remove, or change a field.
+
+**5. Is this a standalone concern with its own lifecycle?** (notification prefs, onboarding state, billing address, API keys, 2FA config, locale settings)
+→ `UserProperty`. Separate schema, separate revision, loaded only when queried. Updates don't contend with `.info` or with other properties.
+
+### When the choice between `info` and property isn't obvious
+
+Default to property. `User.info` should stay small — fields that essentially every feature touches. Reach for `UserProperty` when *any* of these apply:
+
+- **It has its own schema evolution** — you can picture revving its schema without touching `user.info`'s.
+- **Concurrent updates matter** — this feature might update while another updates `.info` or a different property.
+- **Loading the user shouldn't always load this** — sensitive values, large blobs, or data only some features care about.
+- **It may be absent for some users** — not everyone has completed onboarding, not everyone has enabled 2FA, not everyone has a billing address yet.
+
+`User.info` stays reserved for "who the user is to the system." Everything else is a property.
+
+## Red flags
+
+- **Standalone concerns accreting in `User.info`** — notification prefs, onboarding progress, feature flags, 2FA config, billing details. Each is a separately-evolving concern with its own write cadence. Promote each to a property.
+- **Large or sensitive values in `User.info`** — credentials, API tokens, long biographical text, encryption keys. These belong in properties, where `sensitiveProperties` can gate access and where loads stay cheap.
+- **Two features writing to `User.info`** — if email verification and onboarding step both update `.info`, they contend on the row's `revision`. Move one of them to a property.
+- **Email used as the user's primary key in queries** — conflates User with UserIdentity. Look up the identity (`identityService.findByDomainAndKey('email', ...)`), then fetch the user.
+- **Team/org fields on `User.info`** — `role`, `company_id`, `invited_by`. These describe membership, not identity; they belong on `AccountUser.info`.
+- **Account-level fields on `User.info`** — `company_name`, `plan`, `subscription_status`. Move to `Account.info` or `AccountProperty`.
+- **Changing `User.info` shape without bumping `infoSchema`** — migrations use `infoSchema` to decide which rows to backfill. Silent shape changes leave old rows stale forever.
+- **Adding a SQL column to the `users` table for a new field** — `.info` is the migration-free extension point. Only add SQL columns when you need to index or join on the value.
+- **Putting credentials on a generic `UserProperty`** — credentials belong on `UserIdentity`, or on a property explicitly gated via `sensitiveProperties` in `createPropertyService`. Don't leak them via generic property listings.
+
+## When to rev `infoSchema`
+
+Bump `user-01` → `user-02` (same pattern for Account, AccountUser, and each UserProperty) when you:
+- add a required field to `info`
+- change the type of an existing field
+- rename or remove a field that existing code still reads
+
+Don't bump for:
+- optional additions (`field?: X`) — old rows simply won't have the key
+- changes scoped to a different `UserProperty` — each property has its own `infoSchema`
+
+After bumping, write a migration that reads rows with the old schema name, transforms the `info`, writes back with the new name, and increments the revision. Rows the migration can't interpret should surface as errors at read time, not silently serve stale data.
+
+## See also
+
+- `../reference/user-auth.ref.md` — the what/how of the four-layer auth model (Identity / Authentication / Credentials / Authorization) and trust-tier semantics
+- `design.services.skill.md` (from cap-services) — general entity-info-vs-property patterns and the `createEntityService` / `createPropertyService` factories