@maestro-js/agent-skills 1.0.0-alpha.2 → 1.0.0-alpha.21

package/skills/maestro-examples/references/cadence/packages/services/src/user/user-use-cases.ts

@@ -0,0 +1,162 @@
+import z from 'zod'
+import crypto from 'node:crypto'
+import { Hash } from '@maestro-js/hash'
+import { Mail } from '@maestro-js/mail'
+import { Log } from '@maestro-js/log'
+import { Permissions } from '@maestro-js/permissions'
+import { CustomErrors } from '@maestro-js/custom-errors'
+import { UserSchemas } from '@cadence/schemas'
+import { userDbProvider } from './user-db-provider.ts'
+import { authDbProvider } from '../auth/auth-db-provider.ts'
+
+const log = Log.channel('user')
+
+const Profile = UserSchemas.profileModel
+
+// ─── Errors ────────────────────────────────────────────────────────────────────
+
+export const EmailAlreadyInUseError = CustomErrors.create({
+  name: 'EmailAlreadyInUse',
+  message: 'A user with this email already exists in the organization',
+  httpStatusCode: 'conflict' as const
+})
+
+export const UserNotFoundError = CustomErrors.create({
+  name: 'UserNotFound',
+  message: 'User not found',
+  httpStatusCode: 'notFound' as const
+})
+
+export const CannotChangeOwnRoleError = CustomErrors.create({
+  name: 'CannotChangeOwnRole',
+  message: 'You cannot change your own role',
+  httpStatusCode: 'forbidden' as const
+})
+
+export const CannotRemoveSelfError = CustomErrors.create({
+  name: 'CannotRemoveSelf',
+  message: 'You cannot remove yourself',
+  httpStatusCode: 'forbidden' as const
+})
+
+export const CannotDemoteLastAdminError = CustomErrors.create({
+  name: 'CannotDemoteLastAdmin',
+  message: 'Cannot demote the last admin of the organization',
+  httpStatusCode: 'forbidden' as const
+})
+
+export const CannotRemoveLastAdminError = CustomErrors.create({
+  name: 'CannotRemoveLastAdmin',
+  message: 'Cannot remove the last admin of the organization',
+  httpStatusCode: 'forbidden' as const
+})
+
+// ─── Helpers ───────────────────────────────────────────────────────────────────
+
+function generateTempPassword(): string {
+  return crypto.randomBytes(16).toString('base64url')
+}
+
+async function countAdminsInOrg(orgId: number): Promise<number> {
+  const users = await userDbProvider.listByOrganizationId(orgId)
+  return users.filter((u) => u.role === 'admin').length
+}
+
+// ─── InviteUser ────────────────────────────────────────────────────────────────
+
+export const InviteUser = z
+  .function({
+    input: [UserSchemas.inviteUserForm, Profile]
+  })
+  .implement(async ({ email: emailRaw, name, role }, profile) => {
+    Permissions.gate(profile, 'user', 'invite')
+
+    const email = emailRaw.toLowerCase().trim()
+
+    const existing = await userDbProvider.getByEmailAndOrgId(email, profile.organizationId)
+    if (existing) throw new EmailAlreadyInUseError()
+
+    const tempPassword = generateTempPassword()
+    const passwordHash = await Hash.provider('bcrypt').hash(tempPassword)
+
+    const userId = await userDbProvider.create({
+      organizationId: profile.organizationId,
+      name,
+      email,
+      passwordHash,
+      role
+    })
+
+    await Mail.queue({
+      to: email,
+      subject: 'You have been invited to Cadence CRM',
+      content: {
+        html: `<p>You have been invited to Cadence CRM.</p><p>Email: <strong>${email}</strong></p><p>Temporary password: <strong>${tempPassword}</strong></p><p>Please log in and change your password.</p>`
+      }
+    })
+
+    log.info('User invited', { action: 'user.invite', invitedBy: profile.userId, userId, email, role })
+
+    return { userId }
+  })
+
+// ─── ListUsers ─────────────────────────────────────────────────────────────────
+
+export const ListUsers = z
+  .function({
+    input: [Profile]
+  })
+  .implement(async (profile) => {
+    Permissions.gate(profile, 'user', 'list')
+
+    return userDbProvider.listByOrganizationId(profile.organizationId)
+  })
+
+// ─── ChangeUserRole ────────────────────────────────────────────────────────────
+
+export const ChangeUserRole = z
+  .function({
+    input: [z.object({ userId: z.number(), role: z.enum(UserSchemas.roleOptions) }), Profile]
+  })
+  .implement(async ({ userId, role }, profile) => {
+    Permissions.gate(profile, 'user', 'changeRole')
+
+    if (userId === profile.userId) throw new CannotChangeOwnRoleError()
+
+    const target = await userDbProvider.getById(userId)
+    if (!target || target.organizationId !== profile.organizationId) throw new UserNotFoundError()
+
+    if (target.role === 'admin' && role !== 'admin') {
+      const adminCount = await countAdminsInOrg(profile.organizationId)
+      if (adminCount <= 1) throw new CannotDemoteLastAdminError()
+    }
+
+    await userDbProvider.updateRole(userId, role)
+
+    log.info('User role changed', { action: 'user.changeRole', changedBy: profile.userId, userId, role })
+  })
+
+// ─── RemoveUser ────────────────────────────────────────────────────────────────
+
+export const RemoveUser = z
+  .function({
+    input: [z.object({ userId: z.number() }), Profile]
+  })
+  .implement(async ({ userId }, profile) => {
+    Permissions.gate(profile, 'user', 'remove')
+
+    if (userId === profile.userId) throw new CannotRemoveSelfError()
+
+    const target = await userDbProvider.getById(userId)
+    if (!target || target.organizationId !== profile.organizationId) throw new UserNotFoundError()
+
+    if (target.role === 'admin') {
+      const adminCount = await countAdminsInOrg(profile.organizationId)
+      if (adminCount <= 1) throw new CannotRemoveLastAdminError()
+    }
+
+    await userDbProvider.softDelete(userId)
+    await authDbProvider.rememberMeToken.revokeByAuthenticatableId(userId)
+
+    log.info('User removed', { action: 'user.remove', removedBy: profile.userId, userId })
+  })

package/skills/maestro-examples/references/cadence/packages/services/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "module": "es2022",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true
+  },
+  "include": ["./src", "./environment.d.ts"]
+}

package/skills/maestro-examples/references/cadence/scripts/foreign-key-delete-behavior.ts

@@ -0,0 +1,106 @@
+import { Db } from '@maestro-js/db'
+
+Db.Provider.register(
+  'default',
+  Db.Provider.create({
+    driver: Db.drivers.mysql({
+      user: process.env.DB_USER!,
+      password: process.env.DB_PASSWORD!,
+      host: process.env.DB_HOST!,
+      database: process.env.DB_DATABASE!,
+      port: Number(process.env.DB_PORT!)
+    })
+  })
+)
+
+const FKS = {
+  fk_users_organizationId: 'CASCADE',
+  fk_contacts_organizationId: 'CASCADE',
+  fk_interactions_contactId: 'CASCADE',
+  fk_interactions_userId: 'CASCADE',
+  fk_rememberMeTokens_userId: 'CASCADE',
+  fk_passwordResetTokens_userId: 'CASCADE'
+}
+
+type ForeignKey = {
+  TABLE_NAME: string
+  COLUMN_NAME: string
+  REFERENCED_TABLE_NAME: string
+  REFERENCED_COLUMN_NAME: string
+  CONSTRAINT_NAME: string
+}
+
+const foreignKeys = await Db.select<ForeignKey>(
+  `SELECT
+    TABLE_NAME,
+    COLUMN_NAME,
+    REFERENCED_TABLE_NAME,
+    REFERENCED_COLUMN_NAME,
+    CONSTRAINT_NAME
+  FROM information_schema.KEY_COLUMN_USAGE
+  WHERE TABLE_SCHEMA = ?
+    AND REFERENCED_TABLE_NAME IS NOT NULL
+  ORDER BY TABLE_NAME, COLUMN_NAME`,
+  [process.env.DB_DATABASE!]
+)
+
+const dbFkNames = new Set(foreignKeys.map((fk) => fk.CONSTRAINT_NAME))
+const localFkNames = new Set(Object.keys(FKS))
+
+const missingFromLocal = [...dbFkNames].filter((name) => !localFkNames.has(name))
+const extraInLocal = [...localFkNames].filter((name) => !dbFkNames.has(name))
+
+if (missingFromLocal.length > 0) {
+  console.error('Foreign keys in database but missing from FKS:', missingFromLocal)
+}
+if (extraInLocal.length > 0) {
+  console.error('Foreign keys in FKS but not in database:', extraInLocal)
+}
+if (missingFromLocal.length > 0 || extraInLocal.length > 0) {
+  process.exit(1)
+}
+
+console.log('FKS matches database foreign keys')
+
+async function applyOnDeleteRestrict() {
+  for (const constraintName of Object.keys(FKS)) {
+    const fk = foreignKeys.find((f) => f.CONSTRAINT_NAME === constraintName)!
+    await Db.statement(`ALTER TABLE ${fk.TABLE_NAME} DROP FOREIGN KEY ${constraintName}`)
+    await Db.statement(
+      `ALTER TABLE ${fk.TABLE_NAME}
+        ADD CONSTRAINT ${constraintName}
+        FOREIGN KEY (${fk.COLUMN_NAME})
+        REFERENCES ${fk.REFERENCED_TABLE_NAME}(${fk.REFERENCED_COLUMN_NAME})
+        ON DELETE RESTRICT`
+    )
+    console.log(`${constraintName}: ON DELETE RESTRICT applied`)
+  }
+}
+
+async function applyOnDeleteCascade() {
+  for (const [constraintName, behavior] of Object.entries(FKS)) {
+    const fk = foreignKeys.find((f) => f.CONSTRAINT_NAME === constraintName)!
+    await Db.statement(`ALTER TABLE ${fk.TABLE_NAME} DROP FOREIGN KEY ${constraintName}`)
+    await Db.statement(
+      `ALTER TABLE ${fk.TABLE_NAME}
+        ADD CONSTRAINT ${constraintName}
+        FOREIGN KEY (${fk.COLUMN_NAME})
+        REFERENCES ${fk.REFERENCED_TABLE_NAME}(${fk.REFERENCED_COLUMN_NAME})
+        ON DELETE ${behavior}`
+    )
+    console.log(`${constraintName}: ON DELETE ${behavior} applied`)
+  }
+}
+
+const action = process.argv[2]
+
+if (action === 'cascade') {
+  await applyOnDeleteCascade()
+} else if (action === 'restrict') {
+  await applyOnDeleteRestrict()
+} else {
+  console.error('Usage: foreign-key-delete-behavior <cascade|restrict>')
+  process.exit(1)
+}
+
+process.exit(0)

package/skills/maestro-examples/references/cadence/specs/app.md

@@ -0,0 +1,72 @@
+# App Requirements
+
+A multi-tenant CRM for managing contacts and communication. Teams organize people into contacts, log emails and notes, and use tags and filters to stay on top of relationships. Each organization has its own isolated workspace with role-based access.
+
+## Organizations
+
+An organization is the top-level tenant — all data is scoped to one org.
+
+- An org has a name (required) and a slug (required, unique, URL-safe, immutable)
+- An org contains users and contacts
+- Data is fully isolated between orgs — no cross-org access
+- An org can be deleted by an admin (soft delete)
+
+## Users
+
+A user is a person who logs into the app and belongs to one organization.
+
+- A user has a name (required) and email (required, unique within the org)
+- A user has one role: **admin**, **member**, or **viewer**
+  - **Admin** — full access: manage users, delete the org, and all member capabilities
+  - **Member** — create, edit, and delete contacts and interactions
+  - **Viewer** — read-only access to contacts and interactions
+- An admin can invite new users by email and assign their role
+- An admin can change a user's role or remove them from the org
+- Authentication uses username and password. The login page has three fields: org slug, email, and password. The org slug scopes the login to the correct organization. Passwords are hashed and stored per user.
+
+## Contacts
+
+A contact is an individual person the team communicates with.
+
+- A contact has a first name (required), last name (optional), and email (optional)
+- A contact can have a phone number and a job title
+- A contact can have zero or more tags
+- A contact has a created date
+- A contact can be archived — archived contacts are hidden from default views but not deleted
+- A contact can be deleted
+- Contacts are listed in a table view with sorting and filtering by name, tag, and last-contacted date
+
+## Interactions
+
+An interaction is a logged communication with a contact. This is the core activity record.
+
+- An interaction belongs to one contact (required)
+- An interaction has a type: **email** or **note**
+- An interaction has a subject (optional) and a body (required, rich text)
+- An interaction has a date — defaults to now but can be backdated
+- An interaction records which user logged it
+- An interaction can be edited or deleted by the user who created it, or by an admin
+- Interactions appear on the contact detail page in reverse chronological order
+- **Email**: represents a sent or received email
+- **Note**: a freeform record of a conversation, meeting, or observation — no direction
+
+## Tags
+
+Tags are free-form strings attached to contacts for flexible categorization.
+
+- When tagging a contact, existing tag strings within the org are auto-suggested, and typing a new name adds it directly
+- Tags appear as chips on contact rows
+
+## Views
+
+The app provides several built-in views:
+
+- **Contacts** — all active contacts in a sortable, filterable table. Default landing page.
+- **Recent Activity** — a feed of interactions across all contacts, reverse chronological. Filterable by interaction type and user.
+- **Archive** — archived contacts with the option to restore them
+
+## Filtering and Sorting
+
+- The contacts table supports multi-column sorting
+- Filters can be combined: e.g. contacts tagged "Lead" with last contact older than 30 days
+- Active filters are shown as removable chips above the table

package/skills/maestro-examples/references/cadence/specs/data-models.md

@@ -0,0 +1,80 @@
+# Data Models
+
+Zod schemas for the multi-tenant CRM. Each section defines a zod model. Note: zod models are not necessarily one-to-one with database tables.
+
+## Organizations
+
+An organization is the top-level tenant. All data is scoped to one org.
+
+```ts
+const organizationModel = z.object({
+  id: z.number(),
+  name: z.string(),
+  slug: z.string(),
+  deletedDate: isoZ.instant().nullable(),
+  createdDate: isoZ.instant(),
+  lastModifiedDate: isoZ.instant()
+})
+```
+
+## Users
+
+A user belongs to one organization and authenticates with email and password scoped to the org slug.
+
+```ts
+const roleOptions = ['admin', 'member', 'viewer'] as const
+
+const userModel = z.object({
+  id: z.number(),
+  organizationId: z.number(),
+  name: z.string(),
+  email: z.string(),
+  passwordHash: z.string(),
+  role: z.enum(roleOptions),
+  deletedDate: isoZ.instant().nullable(),
+  createdDate: isoZ.instant(),
+  lastModifiedDate: isoZ.instant()
+})
+```
+
+## Contacts
+
+A contact is an individual person the team communicates with. Archiving hides the contact from default views without deleting it. Tags are free-form strings for flexible categorization.
+
+```ts
+const contactModel = z.object({
+  id: z.number(),
+  organizationId: z.number(),
+  firstName: z.string(),
+  lastName: z.string().nullable(),
+  email: z.string().nullable(),
+  phone: z.string().nullable(),
+  jobTitle: z.string().nullable(),
+  tags: z.array(z.string()),
+  archivedDate: isoZ.instant().nullable(),
+  deletedDate: isoZ.instant().nullable(),
+  createdDate: isoZ.instant(),
+  lastModifiedDate: isoZ.instant()
+})
+```
+
+## Interactions
+
+An interaction is a logged communication with a contact.
+
+```ts
+const interactionTypeOptions = ['email', 'note'] as const
+
+const interactionModel = z.object({
+  id: z.number(),
+  contactId: z.number(),
+  userId: z.number(),
+  type: z.enum(interactionTypeOptions),
+  subject: z.string().nullable(),
+  body: z.string(),
+  date: isoZ.instant(),
+  deletedDate: isoZ.instant().nullable(),
+  createdDate: isoZ.instant(),
+  lastModifiedDate: isoZ.instant()
+})
+```

package/skills/maestro-examples/references/cadence/specs/multi-tenant-security.md

@@ -0,0 +1,239 @@
+# Multi-Tenant Security
+
+How authentication, authorization, and tenant isolation work in Cadence CRM. Every organization is a fully isolated tenant identified by its slug. The login flow requires the org slug upfront — similar to how AWS requires an account ID before credentials.
+
+## Login Flow
+
+The login screen has three fields: **org slug**, **email**, and **password**. The org slug acts as the account identifier and must be entered first.
+
+### Step-by-step
+
+1. User enters the org slug
+2. User enters their email and password
+3. The server resolves the org by slug — if not found (or soft-deleted), return a generic "invalid credentials" error
+4. The server looks up the user by email scoped to that org — if not found (or soft-deleted), return the same generic error
+5. `Password.verifyCredentials()` compares the submitted password against the stored hash
+6. If valid, `Auth.login()` creates a session and optionally sets a remember-me cookie
+7. The session stores the user ID and the auth provider name — the org is derived from the user record
+
+The generic error in steps 3 and 4 is intentional. Never reveal whether the org slug or email was the invalid part — this prevents enumeration of valid org slugs and user emails.
+
+### Password Service Configuration
+
+`@maestro-js/password` handles credential verification. The config wires it to the user table scoped by org:
+
+```ts
+Password.Provider.register(
+  'default',
+  Password.Provider.create({
+    getAuthenticatableByCredentials: async ({ orgSlug, email }) => {
+      // JOIN users ON organizations WHERE slug = orgSlug AND email = email AND deletedDate IS NULL
+      // Returns { id, passwordHash, credentialsInvalidBefore } or null
+    },
+    updatePasswordHash: async (userId, passwordHash) => {
+      // UPDATE users SET passwordHash = ? WHERE id = ?
+    },
+    updateCredentialsInvalidBefore: async (userId, date) => {
+      // UPDATE users SET credentialsInvalidBefore = ? WHERE id = ?
+    },
+    hash: Hash.provider('bcrypt')
+  })
+)
+```
+
+The credentials type is `{ orgSlug: string, email: string, password: string }`. The `orgSlug` + `email` pair identifies the user. The password field is handled internally by the Password service — `getAuthenticatableByCredentials` receives everything except `password`.
+
+### Auth Service Configuration
+
+`@maestro-js/auth` manages sessions and remember-me tokens. It delegates credential verification to the Password service:
+
+```ts
+Auth.Provider.register(
+  'default',
+  Auth.Provider.create({
+    name: 'user',
+    verifyCredentials: async (credentials) => {
+      const result = await Password.verifyCredentials(credentials)
+      if (!result) return null
+      // Return full authenticatable: { id, credentialsInvalidBefore }
+    },
+    getAuthenticatableById: async (id) => {
+      // SELECT id, credentialsInvalidBefore FROM users WHERE id = ? AND deletedDate IS NULL
+    },
+    updateCredentialsInvalidBefore: async (id, date) => {
+      // UPDATE users SET credentialsInvalidBefore = ? WHERE id = ?
+    },
+    hash: Hash.provider('sha256'),
+    crypt: Crypt.provider('default'),
+    rememberMeOptions: {
+      maxRememberMeSeconds: 60 * 60 * 24 * 30, // 30 days
+      // remember-me token CRUD backed by a database table
+      create: async (record) => { /* INSERT INTO rememberMeTokens ... */ },
+      getBySelector: async (selector) => { /* SELECT ... WHERE selector = ? */ },
+      rotateBySelector: async (selector, token) => { /* UPDATE ... */ },
+      revokeBySelector: async (selector) => { /* DELETE ... WHERE selector = ? */ },
+      revokeByAuthenticatableId: async (id) => { /* DELETE ... WHERE userId = ? */ }
+    }
+  })
+)
+```
+
+### Session Contents
+
+After login, the session contains:
+
+| Key                            | Value                           |
+| ------------------------------ | ------------------------------- |
+| `_auth_id`                     | User ID                         |
+| `_auth_provider_name`          | `"user"`                        |
+| `_auth_session_created_date`   | ISO instant of session creation |
+
+The org is not stored in the session directly. It is derived by loading the user record and reading `organizationId`. This keeps the session minimal and avoids stale org data.
+
+### Returning Visitors
+
+On subsequent requests, `Auth.authenticate()` checks the session:
+
+1. Read `_auth_id` from the session
+2. Load the user via `getAuthenticatableById`
+3. Compare `_auth_session_created_date` against `credentialsInvalidBefore` — if the session predates a credential change, reject it
+4. If the session is missing but a remember-me cookie exists, validate the token and create a new session
+
+## Tenant Isolation
+
+Tenant isolation is enforced at two layers: the database query layer and the use case layer. There is no row-level security in MySQL, so the application is responsible for scoping every query.
+
+### The Profile Object
+
+Every authenticated request produces a **profile** — a lightweight object derived from the session user that is passed into every use case and permission check:
+
+```ts
+const profile = z.object({
+  userId: z.number(),
+  organizationId: z.number(),
+  role: z.enum(['admin', 'member', 'viewer'])
+})
+```
+
+The profile is built once per request after `Auth.authenticate()` succeeds. It is the single source of truth for "who is this user and what org do they belong to."
+
+### Scoping Queries by Organization
+
+Every database query that reads or writes tenant data must include `WHERE organizationId = ?` using `profile.organizationId`. This applies to:
+
+- Contacts: `SELECT ... FROM contacts WHERE organizationId = ?`
+- Users: `SELECT ... FROM users WHERE organizationId = ?`
+- Interactions: joined through contacts — `JOIN contacts ON interactions.contactId = contacts.id WHERE contacts.organizationId = ?`
+
+There are no exceptions. A query that touches tenant data without filtering by `organizationId` is a bug.
+
+### Cross-Tenant Protection in Use Cases
+
+Use cases receive the profile as their second parameter. The profile's `organizationId` is used to scope all operations — never trust an org ID from the request body or URL params for data access. The URL may contain an org slug for routing purposes, but the actual data scoping always comes from the authenticated profile.
+
+Example — editing a contact:
+
+```ts
+const editContact = z.function(
+  z.tuple([editContactInput, profile]),
+  async (input, profile) => {
+    Permissions.gate(profile, 'Contact', 'update')
+    // The WHERE clause uses profile.organizationId, not a request param
+    await db.query(`UPDATE contacts SET ... WHERE id = ? AND organizationId = ?`, [
+      input.contactId,
+      profile.organizationId
+    ])
+  }
+)
+```
+
+Even if an attacker manipulates the contact ID to reference a contact in another org, the `AND organizationId = ?` clause ensures no rows are affected.
+
+## Authorization
+
+`@maestro-js/permissions` enforces role-based access using CASL's declarative rule model. Rules are computed from the profile on every check — no persisted permission records.
+
+### Action Map
+
+```ts
+type ActionMap = {
+  Organization: ['read', 'update', 'delete']
+  User: ['list', 'invite', 'changeRole', 'remove']
+  Contact: ['list', 'read', 'create', 'update', 'archive', 'restore', 'delete']
+  Interaction: ['list', 'create', 'update', 'delete']
+}
+```
+
+### Permission Rules
+
+```ts
+const permissionsDriver = Permissions.drivers.static<ActionMap, Profile>((profile, allow, forbid) => {
+  // All authenticated users (viewer, member, admin)
+  allow('Organization', 'read')
+  allow('Contact', ['list', 'read'])
+  allow('Interaction', 'list')
+  allow('User', 'list')
+
+  // Members and admins
+  if (profile.role === 'member' || profile.role === 'admin') {
+    allow('Contact', ['create', 'update', 'archive', 'restore', 'delete'])
+    allow('Interaction', ['create', 'update', 'delete'])
+  }
+
+  // Admins only
+  if (profile.role === 'admin') {
+    allow('Organization', ['update', 'delete'])
+    allow('User', ['invite', 'changeRole', 'remove'])
+  }
+})
+```
+
+### Interaction Ownership
+
+Members can only edit or delete their own interactions. Admins can edit or delete any interaction. This is enforced in the use case layer, not the permission rules, because it requires checking the interaction's `userId` against the profile:
+
+```ts
+const deleteInteraction = z.function(
+  z.tuple([deleteInteractionInput, profile]),
+  async (input, profile) => {
+    Permissions.gate(profile, 'Interaction', 'delete')
+    const interaction = await getInteraction(input.interactionId, profile.organizationId)
+    if (interaction.userId !== profile.userId && profile.role !== 'admin') {
+      throw new ForbiddenError('You can only delete your own interactions')
+    }
+    // proceed with delete
+  }
+)
+```
+
+## Password Reset
+
+`@maestro-js/password` provides token-based password reset. The flow is scoped to the org:
+
+1. User submits org slug + email on the reset form
+2. Server looks up the user by org slug + email
+3. `Password.createPasswordResetToken(userId)` generates a selector-verifier token pair, hashes the verifier, and stores the record
+4. The token is sent to the user's email (via `@maestro-js/mail`)
+5. User clicks the link and submits a new password
+6. `Password.resetPassword({ token, newPassword })` validates the token, updates the hash, and sets `credentialsInvalidBefore` to now — invalidating all existing sessions
+
+Built-in protections:
+- **Throttling** — A new reset token cannot be generated within 60 seconds of the previous one
+- **Expiration** — Tokens expire after 60 minutes
+- **Single use** — The token record is deleted after successful reset
+- **Session invalidation** — Setting `credentialsInvalidBefore` forces all existing sessions to re-authenticate
+
+## Security Summary
+
+| Concern                | How it's handled                                                                 |
+| ---------------------- | -------------------------------------------------------------------------------- |
+| Tenant isolation       | Every query includes `WHERE organizationId = ?` from the authenticated profile   |
+| Credential enumeration | Generic error for bad slug, email, or password                                   |
+| Password storage       | Bcrypt hashing via `@maestro-js/hash` with automatic rehashing                   |
+| Session fixation       | Session is regenerated on login                                                  |
+| Stale sessions         | `credentialsInvalidBefore` timestamp invalidates sessions after password changes  |
+| Remember-me tokens     | Selector-verifier pattern, hashed verifier, per-device revocation                |
+| Reset token abuse      | Throttled, time-limited, single-use, hashed verifier                             |
+| Role enforcement       | CASL-based permission checks via `Permissions.gate()` in every use case          |
+| Ownership enforcement  | Use case logic checks `interaction.userId` against `profile.userId`              |
+| Cross-tenant requests  | Profile `organizationId` is from session, never from request input               |