@boopkit/cap-users 0.1.0

package/dist/user-property-service.d.ts

@@ -0,0 +1,18 @@
+import { createPropertyService, type PropertyService, type PropertyRecord } from '@boopkit/cap-services';
+/** Options for creating a user property service. */
+export interface UserPropertyServiceOptions {
+    onCreated?(record: PropertyRecord): void;
+    onUpdated?(record: PropertyRecord): void;
+    onRemoved?(record: PropertyRecord): void;
+}
+/** The service object returned by createUserPropertyService. */
+export type UserPropertyService = PropertyService;
+/**
+ * Create a property service pre-configured for user properties.
+ *
+ * Thin wrapper over createPropertyService with:
+ *  - parentIdField set to 'userId'
+ *  - sensitiveProperties set to ['credentials']
+ */
+export declare function createUserPropertyService(model: Parameters<typeof createPropertyService>[0], options?: UserPropertyServiceOptions): UserPropertyService;
+//# sourceMappingURL=user-property-service.d.ts.map

package/dist/user-property-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-property-service.d.ts","sourceRoot":"","sources":["../src/user-property-service.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,KAAK,eAAe,EACpB,KAAK,cAAc,EACpB,MAAM,uBAAuB,CAAC;AAE/B,oDAAoD;AACpD,MAAM,WAAW,0BAA0B;IACzC,SAAS,CAAC,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IACzC,SAAS,CAAC,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IACzC,SAAS,CAAC,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;CAC1C;AAED,gEAAgE;AAChE,MAAM,MAAM,mBAAmB,GAAG,eAAe,CAAC;AAElD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAC,CAAC,CAAC,EAClD,OAAO,CAAC,EAAE,0BAA0B,GACnC,mBAAmB,CAMrB"}

package/dist/user-property-service.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createUserPropertyService = createUserPropertyService;
+const cap_services_1 = require("@boopkit/cap-services");
+/**
+ * Create a property service pre-configured for user properties.
+ *
+ * Thin wrapper over createPropertyService with:
+ *  - parentIdField set to 'userId'
+ *  - sensitiveProperties set to ['credentials']
+ */
+function createUserPropertyService(model, options) {
+    return (0, cap_services_1.createPropertyService)(model, {
+        parentIdField: 'userId',
+        sensitiveProperties: ['credentials'],
+        ...options,
+    });
+}
+//# sourceMappingURL=user-property-service.js.map

package/dist/user-property-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-property-service.js","sourceRoot":"","sources":["../src/user-property-service.ts"],"names":[],"mappings":";;AAuBA,8DASC;AAhCD,wDAI+B;AAY/B;;;;;;GAMG;AACH,SAAgB,yBAAyB,CACvC,KAAkD,EAClD,OAAoC;IAEpC,OAAO,IAAA,oCAAqB,EAAC,KAAK,EAAE;QAClC,aAAa,EAAE,QAAQ;QACvB,mBAAmB,EAAE,CAAC,aAAa,CAAC;QACpC,GAAG,OAAO;KACX,CAAC,CAAC;AACL,CAAC"}

package/dist/user-service.d.ts

@@ -0,0 +1,47 @@
+import type { EntityService } from '@boopkit/cap-services';
+import type { BaseUserInfo, User } from './types.js';
+/** Lifecycle callbacks for user mutations. */
+export interface UserServiceOptions<TInfo extends BaseUserInfo> {
+    onCreated?(user: User<TInfo>): void;
+    onUpdated?(user: User<TInfo>): void;
+    onRemoved?(user: User<TInfo>): void;
+}
+/** The service object returned by createUserService. */
+export interface UserService<TInfo extends BaseUserInfo> extends EntityService<TInfo> {
+    findByPublicId(publicId: string): Promise<User<TInfo> | null>;
+}
+/**
+ * Minimal delegate shape — extends the entity ModelDelegate with
+ * support for publicId lookups.
+ */
+interface UserModelDelegate {
+    create(args: {
+        data: Record<string, unknown>;
+    }): Promise<Record<string, unknown>>;
+    findUnique(args: {
+        where: Record<string, unknown>;
+    }): Promise<Record<string, unknown> | null>;
+    findMany(args?: {
+        skip?: number;
+        take?: number;
+    }): Promise<Record<string, unknown>[]>;
+    update(args: {
+        where: {
+            id: number;
+        };
+        data: Record<string, unknown>;
+    }): Promise<Record<string, unknown>>;
+    delete(args: {
+        where: {
+            id: number;
+        };
+    }): Promise<Record<string, unknown>>;
+}
+/**
+ * Create a typed user service composing on top of createEntityService.
+ *
+ * Inherits CRUD from entity-service and adds `findByPublicId`.
+ */
+export declare function createUserService<TInfo extends BaseUserInfo = BaseUserInfo>(model: UserModelDelegate, options?: UserServiceOptions<TInfo>): UserService<TInfo>;
+export {};
+//# sourceMappingURL=user-service.d.ts.map

package/dist/user-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-service.d.ts","sourceRoot":"","sources":["../src/user-service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,OAAO,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAErD,8CAA8C;AAC9C,MAAM,WAAW,kBAAkB,CAAC,KAAK,SAAS,YAAY;IAC5D,SAAS,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;IACpC,SAAS,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;IACpC,SAAS,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;CACrC;AAED,wDAAwD;AACxD,MAAM,WAAW,WAAW,CAAC,KAAK,SAAS,YAAY,CAAE,SAAQ,aAAa,CAAC,KAAK,CAAC;IACnF,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;CAC/D;AAED;;;GAGG;AACH,UAAU,iBAAiB;IACzB,MAAM,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAClF,UAAU,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;IAC9F,QAAQ,CAAC,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;IACtF,MAAM,CAAC,IAAI,EAAE;QACX,KAAK,EAAE;YAAE,EAAE,EAAE,MAAM,CAAA;SAAE,CAAC;QACtB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC/B,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACrC,MAAM,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE;YAAE,EAAE,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC3E;AAiBD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,SAAS,YAAY,GAAG,YAAY,EACzE,KAAK,EAAE,iBAAiB,EACxB,OAAO,CAAC,EAAE,kBAAkB,CAAC,KAAK,CAAC,GAClC,WAAW,CAAC,KAAK,CAAC,CAepB"}

package/dist/user-service.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createUserService = createUserService;
+const cap_services_1 = require("@boopkit/cap-services");
+/**
+ * Map a raw delegate row to a typed User entity.
+ */
+function toUser(row) {
+    return {
+        id: row.id,
+        publicId: row.publicId,
+        info: row.info,
+        infoSchema: row.infoSchema,
+        revision: row.revision,
+        createdAt: row.createdAt instanceof Date ? row.createdAt : new Date(row.createdAt),
+        updatedAt: row.updatedAt instanceof Date ? row.updatedAt : new Date(row.updatedAt),
+    };
+}
+/**
+ * Create a typed user service composing on top of createEntityService.
+ *
+ * Inherits CRUD from entity-service and adds `findByPublicId`.
+ */
+function createUserService(model, options) {
+    const base = (0, cap_services_1.createEntityService)(model, {
+        infoSchema: 'user-01',
+        onCreated: options?.onCreated,
+        onUpdated: options?.onUpdated,
+        onRemoved: options?.onRemoved,
+    });
+    return {
+        ...base,
+        async findByPublicId(publicId) {
+            const row = await model.findUnique({ where: { publicId } });
+            return row ? toUser(row) : null;
+        },
+    };
+}
+//# sourceMappingURL=user-service.js.map

package/dist/user-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-service.js","sourceRoot":"","sources":["../src/user-service.ts"],"names":[],"mappings":";;AAoDA,8CAkBC;AAtED,wDAA4D;AAgC5D;;GAEG;AACH,SAAS,MAAM,CAA6B,GAA4B;IACtE,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAY;QACpB,QAAQ,EAAE,GAAG,CAAC,QAAkB;QAChC,IAAI,EAAE,GAAG,CAAC,IAAa;QACvB,UAAU,EAAE,GAAG,CAAC,UAAoB;QACpC,QAAQ,EAAE,GAAG,CAAC,QAAkB;QAChC,SAAS,EAAE,GAAG,CAAC,SAAS,YAAY,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,SAAmB,CAAC;QAC5F,SAAS,EAAE,GAAG,CAAC,SAAS,YAAY,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,SAAmB,CAAC;KAC7F,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAgB,iBAAiB,CAC/B,KAAwB,EACxB,OAAmC;IAEnC,MAAM,IAAI,GAAG,IAAA,kCAAmB,EAAQ,KAAY,EAAE;QACpD,UAAU,EAAE,SAAS;QACrB,SAAS,EAAE,OAAO,EAAE,SAAS;QAC7B,SAAS,EAAE,OAAO,EAAE,SAAS;QAC7B,SAAS,EAAE,OAAO,EAAE,SAA0D;KAC/E,CAAC,CAAC;IAEH,OAAO;QACL,GAAG,IAAI;QACP,KAAK,CAAC,cAAc,CAAC,QAAgB;YACnC,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC;YAC5D,OAAO,GAAG,CAAC,CAAC,CAAC,MAAM,CAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACzC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@boopkit/cap-users",
+  "version": "0.1.0",
+  "description": "User data service factories — typed CRUD for users, identities, and user properties",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/",
+    "scaffold/",
+    "capability.json"
+  ],
+  "boopkit": {
+    "capability": true,
+    "scaffoldDir": "scaffold",
+    "manifest": "capability.json"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@boopkit/cap-services": "^0.1.0",
+    "bcryptjs": "^2.4.3"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "ISC"
+}

package/scaffold/prisma/schema/accounts.prisma

@@ -0,0 +1,47 @@
+// @boopkit/cap-users — Account models
+// Scaffolded by boop. Modify freely — this file is developer-owned.
+
+model Account {
+  id         Int      @id @default(autoincrement())
+  publicId   String   @unique @default(uuid()) @map("public_id") @db.VarChar(255)
+  info       Json
+  infoSchema String   @default("account-01") @map("info_schema") @db.VarChar(255)
+  revision   Int      @default(1)
+  createdAt  DateTime @default(now()) @map("created_at") @db.Timestamptz(6)
+  updatedAt  DateTime @updatedAt @map("updated_at") @db.Timestamptz(6)
+
+  accountUsers      AccountUser[]
+  accountProperties AccountProperty[]
+
+  @@map("accounts")
+}
+
+model AccountUser {
+  id         Int      @id @default(autoincrement())
+  accountId  Int      @map("account_id")
+  userId     Int      @map("user_id")
+  info       Json
+  infoSchema String   @default("account-user-01") @map("info_schema") @db.VarChar(255)
+  revision   Int      @default(1)
+  createdAt  DateTime @default(now()) @map("created_at") @db.Timestamptz(6)
+  updatedAt  DateTime @updatedAt @map("updated_at") @db.Timestamptz(6)
+  account    Account  @relation(fields: [accountId], references: [id], onDelete: Cascade)
+  user       User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@unique([accountId, userId], map: "unique_account_user")
+  @@map("account_users")
+}
+
+model AccountProperty {
+  id         Int      @id @default(autoincrement())
+  accountId  Int      @map("account_id")
+  property   String   @db.VarChar(255)
+  info       Json
+  infoSchema String   @map("info_schema") @db.VarChar(255)
+  createdAt  DateTime @default(now()) @map("created_at") @db.Timestamptz(6)
+  updatedAt  DateTime @updatedAt @map("updated_at") @db.Timestamptz(6)
+  account    Account  @relation(fields: [accountId], references: [id], onDelete: Cascade)
+
+  @@unique([accountId, property], map: "unique_account_property")
+  @@map("account_properties")
+}

package/scaffold/prisma/schema/users.prisma

@@ -0,0 +1,47 @@
+// @boopkit/cap-users — User models
+// Scaffolded by boop. Modify freely — this file is developer-owned.
+
+model User {
+  id         Int              @id @default(autoincrement())
+  publicId   String           @unique @default(uuid()) @map("public_id") @db.VarChar(255)
+  info       Json
+  infoSchema String           @map("info_schema") @db.VarChar(255)
+  revision   Int              @default(0)
+  createdAt  DateTime         @default(now()) @map("created_at") @db.Timestamptz(6)
+  updatedAt  DateTime         @updatedAt @map("updated_at") @db.Timestamptz(6)
+
+  identities   UserIdentity[]
+  properties   UserProperty[]
+  accountUsers AccountUser[]
+
+  @@map("users")
+}
+
+model UserIdentity {
+  id        Int       @id @default(autoincrement())
+  userId    Int       @map("user_id")
+  domain    String    @db.VarChar(255)
+  key       String    @db.VarChar(255)
+  endedAt   DateTime? @map("ended_at") @db.Timestamptz(6)
+  createdAt DateTime  @default(now()) @map("created_at") @db.Timestamptz(6)
+  updatedAt DateTime  @updatedAt @map("updated_at") @db.Timestamptz(6)
+  user      User      @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@unique([domain, key], map: "unique_user_identity")
+  @@map("user_identities")
+}
+
+model UserProperty {
+  id         Int      @id @default(autoincrement())
+  userId     Int      @map("user_id")
+  property   String   @db.VarChar(255)
+  info       Json
+  infoSchema String   @map("info_schema") @db.VarChar(255)
+  revision   Int      @default(0)
+  createdAt  DateTime @default(now()) @map("created_at") @db.Timestamptz(6)
+  updatedAt  DateTime @updatedAt @map("updated_at") @db.Timestamptz(6)
+  user       User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@unique([userId, property], map: "unique_user_property")
+  @@map("user_properties")
+}

package/scaffold/reference/user-auth.ref.md

@@ -0,0 +1,237 @@
+# User & Authentication Infrastructure
+
+How this project models users, links identities, manages credentials, and tracks session trust.
+
+**Related capabilities**: database, services
+
+---
+
+## Four-Layer Model
+
+Authentication is built on four independent layers. Keeping them separate prevents bugs — logout shouldn't modify which methods are accepted, disabling a method shouldn't revoke existing sessions, and changing a password shouldn't touch authorization grants.
+
+| Layer | Question | Keyed by | Storage |
+|-------|----------|----------|---------|
+| **Identity** | Who is this? | domain + key | UserIdentity table (end-dated, never deleted) |
+| **Authentication** | What methods can they use? | strategy | UserProperty `authentication` |
+| **Credentials** | What are the secrets? | strategy | UserProperty `credentials` (sensitive) |
+| **Authorization** | What can this device/key do? | identity_key | UserProperty `authorization` |
+
+**Identity** maps an incoming credential (cookie, email, API key, OAuth provider ID) to a user. A user has many identities. Identities are never deleted — they're end-dated, preserving history for audit.
+
+**Authentication** declares which login methods are accepted. Disabling a method sets `accepted: false`, which the login flow checks before verifying credentials.
+
+**Credentials** are the secrets (bcrypt hashes, TOTP seeds). Stored separately from authentication because they're sensitive and have a different lifecycle.
+
+**Authorization** is the active permission grant, scoped **per-device**: each browser and each API key has its own trust level. Logging out on your phone doesn't affect your laptop.
+
+---
+
+## Data Model
+
+Three tables, all following the standard boop entity shape (`id`, `publicId`, `info`, `infoSchema`, `revision`, timestamps):
+
+```
+User ──< UserIdentity    (one user, many auth mechanisms)
+User ──< UserProperty    (one user, many typed properties)
+```
+
+### User
+
+The core record. Domain data lives in the `info` JSON column, typed via `BaseUserInfo` (extensible with generics).
+
+### UserIdentity
+
+Links a user to an auth mechanism via `(domain, key)` compound unique key:
+
+| Domain | Key | Example |
+|--------|-----|---------|
+| `email` | email address | `alice@example.com` |
+| `cookie` | session token | `base64url-token` |
+| `api-key` | hashed key | `hashed-base64url` |
+| OAuth provider | external ID | `google-user-id` |
+
+Soft-deleted via `endedAt` — revoked identities remain queryable with `includeEnded: true`.
+
+### UserProperty
+
+Key-value storage scoped to a user via `(userId, property)` compound key. Well-known properties:
+
+| Property | Contains | Sensitive? |
+|----------|----------|-----------|
+| `profile` | name, email (address + verified flag) | No |
+| `credentials` | Array of `{ strategy, secret }` — bcrypt-hashed | **Yes** |
+| `authentication` | Array of accepted auth methods with OAuth tokens | No |
+| `authorization` | Array of per-device/per-key grants with trust tiers | No |
+
+---
+
+## Trust Model
+
+Authorization grants track per-device trust with three graduated tiers — a user isn't simply "logged in" or "logged out":
+
+| Tier | Meaning | How granted | Example use |
+|------|---------|-------------|-------------|
+| `recognized` | We think we know who this is | Default after expiry or logout | "Welcome back, Alice" — show name, preferences |
+| `authenticated` | They proved identity recently | `login()` or `setTrust()` | Normal session — CRUD, purchases, account access |
+| `verified` | Extra proof on an authenticated session | `setTrust()` after TOTP/email/biometric | Change email, delete account, manage API keys |
+
+Grants have `expires_at` — expired grants downgrade to `recognized`. Standing grants (`expires_at = 0`) never expire (used for API keys).
+
+---
+
+## Session Rotation Rules
+
+**Rotate the session** (new cookie) when the *authentication source* changes — login, re-authentication, switching users. This prevents session fixation: an attacker who knew the pre-auth token can't ride the post-auth session.
+
+**Upgrade the existing grant** (same cookie) when the user proves *additional* identity strength on an already-authenticated session — TOTP, biometric, password re-entry for sensitive ops. Rotating would break their session for no security benefit.
+
+*New credential source → rotate. Stronger proof on same session → upgrade.*
+
+---
+
+## Auth Flows
+
+### Password (local auth)
+
+All four layers participate:
+
+| Layer | What happens |
+|-------|-------------|
+| **Identity** | `domain: "email", key: "alice@example.com"` — lookup for login |
+| **Authentication** | `{ strategy: "local", accepted: true }` — user can log in with password |
+| **Credentials** | `{ strategy: "local", secret: "$2b$..." }` — bcrypt hash |
+| **Authorization** | Created on login, tied to the session cookie |
+
+**Signup:** create user → create email identity → set credentials (hash password) → add local auth method → mint session cookie → create per-device grant at `authenticated`.
+
+**Login:** look up email identity → check `isMethodAccepted("local")` → verify bcrypt hash → rotate session (new cookie) → create per-device grant at `authenticated`.
+
+### Cookie (session)
+
+A cookie is an identity — `domain: "cookie", key: "a8f3...hex"`. One per browser. Each cookie has its own authorization grant:
+
+```
+Browser A: cookie aaa..., grant trust=authenticated
+Browser B: cookie bbb..., grant trust=verified (just did TOTP)
+Browser C: cookie ccc..., grant trust=recognized (session expired)
+```
+
+**Session rotation:** on login (privilege-level change), the old cookie is end-dated and a new one minted. The old grant is removed, the new cookie gets a fresh grant.
+
+**Session expiry:** when a grant's `expires_at` passes, that device's trust falls to `recognized`. The cookie still resolves the user, but they can't perform authenticated actions until they re-login.
+
+### API Key
+
+An API key is simultaneously an identity, a credential, and a bearer token. All four layers participate:
+
+| Layer | What happens |
+|-------|-------------|
+| **Identity** | `domain: "api-key", key: "47ZHJY-..."` — lookup on each request |
+| **Authentication** | `{ strategy: "api-key", accepted: true }` — user can use API keys |
+| **Credentials** | `{ strategy: "api-key", secret: "$2b$..." }` — bcrypt hash of the key |
+| **Authorization** | `{ identity_key: "47ZHJY-...", strategy: "api-key", trust: "authenticated", expires_at: 0 }` — standing per-key grant |
+
+**Three independent levers to control access:**
+1. **Revoke the key** — end-date the identity. Immediate.
+2. **Disable API key auth** — set `accepted: false` on the authentication entry. All API keys stop working, but keys still exist.
+3. **Expire the grant** — set `expires_at` on the per-key grant. Can be re-enabled without rotating the key.
+
+**Validation flow:** identity lookup → `isMethodAccepted("api-key")` → bcrypt compare → check per-key grant → return user.
+
+The plaintext key is returned exactly once at creation. Only the hash is stored.
+
+### OAuth (as client)
+
+When a user logs in via Google (or other provider), the app is an OAuth *client*. The provider proves identity; boop stores the result.
+
+| Layer | What happens |
+|-------|-------------|
+| **Identity** | `domain: "google", key: "google-sub-id-12345"` — maps provider ID to user |
+| **Authentication** | `{ strategy: "oauth-google", accepted: true, refresh_token: "rt_...", access_token: "at_...", ... }` — delegated credentials stored |
+| **Credentials** | None — OAuth credentials are delegated, stored in the authentication entry |
+| **Authorization** | Created on login, tied to the session cookie — same as password login |
+
+OAuth tokens (`refresh_token`, `access_token`) are **delegated credentials** — tokens held from the provider to act on the user's behalf. They are NOT how the app recognizes the user on subsequent requests. Users are recognized via cookies, same as password login.
+
+**OAuth login flow:** provider callback with auth code → exchange for tokens → look up or create identity (`domain: "google"`) → store tokens in authentication entry → rotate session → create per-device grant.
+
+### TOTP / Second Factor
+
+TOTP upgrades trust on the current device. It does NOT rotate the session — the user already proved identity at login (which rotated the session). TOTP is additional proof on the same session, not a new authentication source.
+
+---
+
+## Logout vs. Forget
+
+| User action | Function | Cookie | Grant | Other devices |
+|-------------|----------|--------|-------|---------------|
+| "Log out" | `logout(userId, token)` | Survives | trust → `recognized` | Unaffected |
+| "Log out everywhere" | `logoutAll(userId)` | Survive | All session grants → `recognized` | All downgraded |
+| "Forget me" | `forgetDevice(userId, token)` | End-dated | Removed | Unaffected |
+| "Sign out everywhere" | `forgetAllDevices(userId)` | All end-dated | All session grants removed | All forgotten |
+
+API key grants are not affected by any of these — managed separately via `revokeApiKey`.
+
+---
+
+## Services
+
+All services compose from `@boopkit/cap-services` primitives:
+
+| Service | Factory | Purpose |
+|---------|---------|---------|
+| `userService` | `createUserService<TInfo>()` | CRUD on User with typed `info` |
+| `identityService` | `createIdentityService()` | Link/unlink auth mechanisms |
+| `userPropertyService` | `createUserPropertyService()` | Read/write user properties (credentials gated) |
+| `authService` | `createAuthService(deps, opts)` | Orchestrates signup, login, sessions, API keys |
+
+### AuthService key operations
+
+**Signup**: `signup({ email, password, name })` — creates user, email identity, profile, credentials, auth method, session token, and authorization grant in one call. Each step is also available individually for graduated control.
+
+**Login**: `login(email, password, currentSessionToken?)` — validates credentials, rotates session (ends old token if provided), grants `authenticated` trust.
+
+**Session management**:
+- `logout(userId, token)` — downgrades trust to `recognized` (device remembers user but loses auth)
+- `forgetDevice(userId, token)` — end-dates cookie identity and removes grant (irreversible)
+- `logoutAll` / `forgetAllDevices` — bulk variants
+
+**API keys**: `createApiKey(userId)` / `validateApiKey(key)` / `revokeApiKey` / `rotateApiKey` — standing grants that never expire.
+
+**Trust queries**: `getTrustTier(userId, identityKey)`, `isAuthorized(userId, identityKey, requiredTrust?)`.
+
+---
+
+## Extension
+
+Define project-specific user data via generics:
+
+```typescript
+interface MyUserInfo extends BaseUserInfo {
+  department: string;
+  role: 'admin' | 'member';
+}
+
+const userService = createUserService<MyUserInfo>(db.user);
+```
+
+The type propagates through all service operations.
+
+---
+
+## Environment
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `SESSION_DURATION` | `604800` (7 days) | Session token lifetime in seconds |
+
+---
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `prisma/users.prisma` | User, UserIdentity, UserProperty table definitions |
+| `src/services/users.service.ts` | Service wiring — instantiates all user services |
+| `@boopkit/cap-users` | Service factories (user, identity, property, auth) |

package/scaffold/src/controllers/auth.ts

@@ -0,0 +1,158 @@
+import type { Response } from 'express';
+import type { AuthService } from '@boopkit/cap-users';
+import { AuthValidationError } from '@boopkit/cap-users';
+
+/** Extended Express Request with auth fields set by ensureVisitor middleware. */
+interface AuthRequest {
+  body: Record<string, any>;
+  query: Record<string, any>;
+  cookies?: Record<string, string>;
+  user?: { id: number; [key: string]: any };
+  sessionToken?: string;
+}
+
+const ONE_YEAR_MS = 365 * 24 * 60 * 60 * 1000;
+const COOKIE_NAME = 'auth_id';
+
+/** Map AuthValidationError field names to view-friendly error keys. */
+const FIELD_ERROR_MAP: Record<string, string> = {
+  email: 'email_invalid',
+  password: 'password_weak',
+  passwordConfirmation: 'password_mismatch',
+};
+
+export interface AuthControllerDeps {
+  authService: AuthService;
+}
+
+export function createAuthController(deps: AuthControllerDeps) {
+  const { authService } = deps;
+
+  // ---- Login ----
+
+  async function showLogin(req: AuthRequest, res: Response): Promise<void> {
+    // Already authenticated? Redirect away.
+    if (res.locals.auth?.trustTier === 'authenticated' || res.locals.auth?.trustTier === 'verified') {
+      const next = req.query.next as string | undefined;
+      const redirectTo = (typeof next === 'string' && next.startsWith('/')) ? next : '/';
+      res.redirect(redirectTo);
+      return;
+    }
+
+    const next = req.query.next as string | undefined;
+    res.render('login', {
+      layout: 'main',
+      action: '/login',
+      next,
+      error: req.query.error as string | undefined,
+    });
+  }
+
+  async function handleLogin(req: AuthRequest, res: Response): Promise<void> {
+    const { email, password } = req.body;
+    const next = req.body.next || req.query.next as string | undefined;
+    const currentSessionToken = req.cookies?.[COOKIE_NAME] as string | undefined;
+
+    try {
+      const result = await authService.login(email, password, currentSessionToken);
+
+      // Set rotated session cookie
+      res.cookie(COOKIE_NAME, result.sessionToken, {
+        httpOnly: true,
+        maxAge: ONE_YEAR_MS,
+      });
+
+      // Redirect to ?next= or home
+      const redirectTo = (typeof next === 'string' && next.startsWith('/')) ? next : '/';
+      res.redirect(redirectTo);
+    } catch {
+      // Generic error — same message for invalid password and nonexistent email (no enumeration)
+      res.render('login', {
+        layout: 'main',
+        action: '/login',
+        next,
+        email,
+        errorMessage: 'Invalid email or password',
+      });
+    }
+  }
+
+  // ---- Signup ----
+
+  async function showSignup(req: AuthRequest, res: Response): Promise<void> {
+    // Already authenticated? Redirect away.
+    if (res.locals.auth?.trustTier === 'authenticated' || res.locals.auth?.trustTier === 'verified') {
+      const next = req.query.next as string | undefined;
+      const redirectTo = (typeof next === 'string' && next.startsWith('/')) ? next : '/';
+      res.redirect(redirectTo);
+      return;
+    }
+
+    const next = req.query.next as string | undefined;
+    res.render('signup', {
+      layout: 'main',
+      action: '/signup',
+      next,
+    });
+  }
+
+  async function handleSignup(req: AuthRequest, res: Response): Promise<void> {
+    const { email, password, passwordConfirmation } = req.body;
+    const next = req.body.next || req.query.next as string | undefined;
+
+    try {
+      const result = await authService.signup({ email, password, passwordConfirmation });
+
+      // Set session cookie
+      res.cookie(COOKIE_NAME, result.sessionToken, {
+        httpOnly: true,
+        maxAge: ONE_YEAR_MS,
+      });
+
+      // Redirect to ?next= or home
+      const redirectTo = (typeof next === 'string' && next.startsWith('/')) ? next : '/';
+      res.redirect(redirectTo);
+    } catch (err) {
+      // Build per-field error flags for the view
+      const errors: Record<string, boolean> = {};
+      let errorMessage = 'Signup failed';
+
+      if (err instanceof AuthValidationError) {
+        const key = FIELD_ERROR_MAP[err.field] ?? err.field;
+        errors[key] = true;
+        errorMessage = err.message;
+      } else if (err instanceof Error && err.message.includes('Unique constraint')) {
+        errors.user_exists = true;
+        errorMessage = 'An account with this email already exists';
+      }
+
+      res.render('signup', {
+        layout: 'main',
+        action: '/signup',
+        next,
+        email,
+        errors,
+        errorMessage,
+      });
+    }
+  }
+
+  // ---- Logout ----
+
+  async function handleLogout(req: AuthRequest, res: Response): Promise<void> {
+    if (req.user && req.sessionToken) {
+      await authService.logout(req.user.id, req.sessionToken);
+    }
+    res.redirect('/');
+  }
+
+  async function handleForgetDevice(req: AuthRequest, res: Response): Promise<void> {
+    if (req.user && req.sessionToken) {
+      await authService.forgetDevice(req.user.id, req.sessionToken);
+    }
+    res.clearCookie(COOKIE_NAME);
+    res.redirect('/');
+  }
+
+  return { showLogin, handleLogin, showSignup, handleSignup, handleLogout, handleForgetDevice };
+}