@boopkit/cap-users 0.5.0 → 0.7.0

package/scaffold/src/controllers/auth.ts

@@ -1,15 +1,11 @@
-import type { Response } from 'express';
+import type { Request, Response } from 'express';
 import type { AuthService } from '@boopkit/cap-users';
 import { AuthValidationError } from '@boopkit/cap-users';
-
-/** Extended Express Request with auth fields set by resolveVisitor middleware. */
-interface AuthRequest {
-  body: Record<string, any>;
-  query: Record<string, any>;
-  cookies?: Record<string, string>;
-  user?: { id: number; [key: string]: any };
-  sessionToken?: string;
-}
+// Side-effect import: brings in the Express request augmentation that types
+// req.user / req.sessionToken / req.visitorToken / req.authStrategy. A generated
+// project also picks these up automatically via its tsconfig `include`, so this
+// line is only needed to type-check the controller in isolation.
+import '../types/express';
 
 const ONE_YEAR_MS = 365 * 24 * 60 * 60 * 1000;
 const COOKIE_NAME = 'auth_id';
@@ -97,7 +93,7 @@ export function createAuthController(deps: AuthControllerDeps) {
 
   // ---- Login ----
 
-  async function showLogin(req: AuthRequest, res: Response): Promise<void> {
+  async function showLogin(req: Request, 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;
@@ -118,7 +114,7 @@ export function createAuthController(deps: AuthControllerDeps) {
     });
   }
 
-  async function handleLogin(req: AuthRequest, res: Response): Promise<void> {
+  async function handleLogin(req: Request, 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;
@@ -149,7 +145,7 @@ export function createAuthController(deps: AuthControllerDeps) {
 
   // ---- Signup ----
 
-  async function showSignup(req: AuthRequest, res: Response): Promise<void> {
+  async function showSignup(req: Request, 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;
@@ -166,7 +162,7 @@ export function createAuthController(deps: AuthControllerDeps) {
     });
   }
 
-  async function handleSignup(req: AuthRequest, res: Response): Promise<void> {
+  async function handleSignup(req: Request, res: Response): Promise<void> {
     const { email, password, passwordConfirmation } = req.body;
     const next = req.body.next || req.query.next as string | undefined;
 
@@ -209,14 +205,14 @@ export function createAuthController(deps: AuthControllerDeps) {
 
   // ---- Logout ----
 
-  async function handleLogout(req: AuthRequest, res: Response): Promise<void> {
+  async function handleLogout(req: Request, 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> {
+  async function handleForgetDevice(req: Request, res: Response): Promise<void> {
     if (req.user && req.sessionToken) {
       await authService.forgetDevice(req.user.id, req.sessionToken);
     }

package/scaffold/src/middleware/auth.ts

@@ -6,15 +6,24 @@ import createAuthRouter from '../routes/auth';
 
 const { authService, identityService, userService } = UserService;
 
-const { resolveVisitor, resolveBearer, getOrCreateUser, addAuthContext, requireAuth } = createAuthMiddleware(
-  { authService, identityService, userService },
-  {
-    cookieName: 'auth_id',
-    loginPath: '/login',
-  },
-);
+const { resolveVisitor, resolveBearer, getOrCreateUser, addAuthContext, requireAuth, requireApiKey } =
+  createAuthMiddleware(
+    { authService, identityService, userService },
+    {
+      cookieName: 'auth_id',
+      loginPath: '/login',
+    },
+  );
 
 /** Pre-built auth routes (signup, login, logout). Ready to mount with app.use(). */
 const authRoutes = createAuthRouter({ authService });
 
-export { resolveVisitor, resolveBearer, getOrCreateUser, addAuthContext, requireAuth, authRoutes };
+export {
+  resolveVisitor,
+  resolveBearer,
+  getOrCreateUser,
+  addAuthContext,
+  requireAuth,
+  requireApiKey,
+  authRoutes,
+};

package/scaffold/src/scripts/migrate-credentials.ts

@@ -0,0 +1,69 @@
+// @boopkit/cap-users template — Rehash cleartext credentials stored in property
+// tables (boop-j8xc credential-hashing epic).
+//
+// Some property payloads once stored a raw, redeemable bearer credential beside
+// its correctly-hashed twin: session tokens and API keys in the `authorization`
+// user-property (and, once cap-users ships it, invitation tokens in the
+// `team_invitations` account-property). The upgraded services store the hash and
+// read tolerantly, but existing rows keep the raw value until they are rewritten.
+// This script rehashes them IN PLACE, so no user is logged out and no pending
+// invitation is voided.
+//
+// Usage:
+//   npm run credentials:migrate            # REPORT ONLY — counts what would change, writes nothing
+//   npm run credentials:migrate -- --run   # apply the rehash
+//
+// ⚠️  ONE-WAY, NO ROLLBACK. Hashing is irreversible — once a row is rewritten the
+//     raw value is gone for good. TAKE A DATABASE BACKUP before running --run.
+//
+// Safe to re-run: idempotency is decided by value shape (a SHA-256 digest is left
+// untouched), so a value is never double-hashed. Provider access/refresh tokens
+// in the `authentication` property are never touched — they are replayed to
+// Google/Microsoft and must stay raw.
+
+import { migrateCredentialStore, authorizationStore, teamInvitationsStore, type CredentialStore, type MigrationDelegate } from '@boopkit/cap-users';
+import db from '../db';
+
+const run = process.argv.includes('--run');
+
+// The stores this deployment migrates — the same runner drives every one:
+//   - `authorization` user-property: raw session tokens and API keys (boop-j8xc.2)
+//   - `team_invitations` account-property: raw invitation tokens (boop-j8xc.3)
+const targets: { model: MigrationDelegate; store: CredentialStore }[] = [
+  { model: db.userProperty as unknown as MigrationDelegate, store: authorizationStore },
+  { model: db.accountProperty as unknown as MigrationDelegate, store: teamInvitationsStore },
+];
+
+async function main() {
+  if (!run) {
+    console.log('=== REPORT ONLY (no writes) — pass --run to apply ===\n');
+  } else {
+    console.log('=== APPLYING migration (--run) ===\n');
+  }
+
+  let totalPending = 0;
+  for (const { model, store } of targets) {
+    const report = await migrateCredentialStore(model, store, { run });
+    totalPending += report.needsMigration;
+    const action = run ? `rehashed ${report.migrated}` : `${report.needsMigration} would be rehashed`;
+    console.log(
+      `${store.label}: scanned ${report.scanned}, ${action} ` +
+        `(${report.scanned - report.needsMigration} already migrated)`,
+    );
+  }
+
+  if (!run && totalPending > 0) {
+    console.log(`\n${totalPending} row(s) hold a raw credential. Back up your database, then re-run with --run.`);
+  } else if (run) {
+    console.log('\nDone. All targeted rows are hashed and tagged.');
+  } else {
+    console.log('\nNothing to migrate — every targeted row is already hashed.');
+  }
+}
+
+main()
+  .catch((err) => {
+    console.error('Migration failed:', err);
+    process.exitCode = 1;
+  })
+  .finally(() => db.$disconnect());

package/scaffold/src/types/express.ts

@@ -0,0 +1,77 @@
+/**
+ * Express request augmentation for the auth principal (cap-users).
+ *
+ * cap-users' middleware writes four fields onto the Express request —
+ * `req.user`, `req.sessionToken`, `req.visitorToken` and `req.authStrategy` —
+ * but the library sets them through `(req as any)` casts and declares none of
+ * them to TypeScript. Without this file every consumer has to invent its own
+ * typing: the scaffolded auth controller used to hand-roll an `AuthRequest`
+ * interface that restated `body`, `query` and `cookies` purely to stand in for
+ * `Request`, and typed `user` as `{ id: number; [key: string]: any }`, losing
+ * the real `User` shape. Declaring the fields once here types every consumer —
+ * this controller, your own route handlers, anything that reads `req.user`.
+ *
+ * This file is a global ambient augmentation. In a generated project your
+ * tsconfig's `include` already compiles everything under `src/`, so these
+ * declarations apply project-wide with no import needed; the side-effect
+ * `import './types/express'` in the auth controller is only there so the
+ * controller still type-checks when compiled outside a full project (for
+ * example inside boop's own test suite).
+ *
+ * WHY THE USER SHAPE HANGS OFF `Express.User`, NOT `Request.user` DIRECTLY.
+ * `@types/passport` — pulled in the moment you add oauth-client — augments the
+ * global `Express` namespace with an empty `interface User {}` and types
+ * `Request['user']` as that `Express.User`. If cap-users declared
+ * `Request.user` with a *different* type (say `User<BaseUserInfo>`), the two
+ * declarations would merge and collide: TypeScript reports TS2717, "subsequent
+ * property declarations must have the same type", and every auth handler stops
+ * matching `RequestHandler`. Extending `Express.User` instead means both
+ * capabilities describe `Request.user` with the *same* type (`Express.User`),
+ * so their declarations merge cleanly and passport's empty interface simply
+ * picks up the real `User` members. This is the shape that stays correct
+ * whether or not passport is present. (See boop-lrse for the failure this
+ * avoids.)
+ */
+import type { BaseUserInfo, User } from '@boopkit/cap-users';
+
+declare global {
+  namespace Express {
+    /**
+     * The authenticated principal's shape. Extending here rather than typing
+     * `Request.user` directly is what lets cap-users and `@types/passport`
+     * agree on a single `Request.user` type instead of colliding.
+     */
+    interface User extends UserPrincipal {}
+
+    interface Request {
+      /** Set by resolveVisitor (session cookie) or resolveBearer (API key). */
+      user?: User;
+      /**
+       * The identity_key for this request's credential — the session-cookie
+       * token on the browser path, the raw API key on the bearer path.
+       * requireAuth hands it to authService.isAuthorized.
+       */
+      sessionToken?: string;
+      /** Anonymous visitor tracking token, from the visitor_id cookie. */
+      visitorToken?: string;
+      /**
+       * Which door this request's principal came through, set only by the
+       * resolver that actually resolved it. Absent when req.user arrived from
+       * the session cookie via resolveVisitor. A gate that must accept only one
+       * kind of credential (requireApiKey) reads this — req.user alone cannot
+       * tell a key principal from a cookie one.
+       */
+      authStrategy?: 'api-key';
+    }
+  }
+}
+
+/**
+ * The concrete user shape, kept out of the `Express` namespace so the
+ * `interface User extends …` line above reads cleanly. It is exactly the
+ * `User<BaseUserInfo>` the services return, so `req.user` carries the real
+ * entity (`id`, `publicId`, `info`, timestamps) rather than a stand-in.
+ */
+type UserPrincipal = User<BaseUserInfo>;
+
+export {};