@boopkit/cap-users 0.4.3 → 0.4.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boopkit/cap-users",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "description": "User accounts, authentication, and session management via Prisma",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

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

@@ -49,7 +49,7 @@ Links a user to an auth mechanism via `(domain, key)` compound unique key:
 | `email` | email address | `alice@example.com` |
 | `cookie` | session token | `base64url-token` |
 | `api-key` | hashed key | `hashed-base64url` |
-| OAuth provider | external ID | `google-user-id` |
+| OAuth provider, bare — `google`, `microsoft` | provider's stable subject id | `google-sub-id-12345` |
 
 Soft-deleted via `endedAt` — revoked identities remain queryable with `includeEnded: true`.
 
@@ -143,23 +143,55 @@ 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.
+When a user logs in via Google or Microsoft, the app is an OAuth *client*. The provider proves identity; the app stores the result.
+
+These rows are what the `oauth-client` capability writes. It writes them through the services below and adds no user model of its own, so everything on this page still describes the whole truth about a user after you install it — and once installed, its own [`oauth-client.ref.md`](oauth-client.ref.md) covers the sign-in routes, the provider registry, and token refresh in depth.
 
 | 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 |
+| **Authentication** | `{ strategy: "oauth-google", accepted: true, access_token: "at_...", refresh_token: "rt_...", access_token_expires_at: 1756..., oauth_profile: {...} }` — 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.
+**The identity key is the provider's stable subject identifier** — Google's `sub`, Microsoft's directory object id.
+It is never the email address or the UPN, because both are reassignable and keying on one hands a recycled address the previous holder's account.
+
+**The bare identity domain and the prefixed strategy are deliberate, not an oversight.**
+The identity domain is `google` — bare, like `cookie`, `email`, and `api-key`.
+The authentication strategy is `oauth-google` — prefixed, like `local` and `api-key`, where the prefix is what marks a delegated method rather than a locally verified one.
+The two pairs that ship are `google` / `oauth-google` and `microsoft` / `oauth-microsoft`.
+The domain answers *whose account this is*; the strategy answers *how the user authenticates*.
+Those are different questions, and each vocabulary is consistent within itself.
+Do not normalize one to the other. The bare domain is also what lets an app that already stores `(domain: provider_name, key: profile.id)` adopt the `oauth-client` capability without rewriting a single identity row.
+
+**OAuth login flow:** `GET /auth/:provider` mints a random nonce and stores it, the PKCE verifier, and the validated return path in a short-lived httpOnly cookie → provider callback with auth code → the nonce is compared to the cookie in constant time, failing closed → exchange the code for tokens → reconcile the provider identity, the email identity, and the anonymous cookie user to a single user, creating one if none exists → store tokens in the authentication entry with an absolute expiry from the provider's `expires_in` → rotate session → create per-device grant.
+
+Two of those steps refuse rather than resolve. A provider account and an email address owned by two different users leaves both accounts untouched for a person to sort out, and an unverified provider email may not claim an existing account.
+
+A third withholds rather than refuses, and it is the one that shapes what is in the identity table.
+When the provider reports an address it has not verified and *nobody owns it yet*, the sign-in proceeds on the provider identity alone: no `email` identity row is written, and only the profile keeps the claim, labelled unverified.
+The identity row — not the profile — is what resolves a user on a later sign-in, so writing one from an unverified claim would let someone squat an address and be handed the victim when the victim's genuinely verified sign-in matched it.
+The address is not stranded: when the same provider account later reports it verified, the email identity is attached then.
+
+Provider tokens are stored **unencrypted**, like everything else in the `authentication` property. They are bearer credentials the app must replay verbatim to the provider, so they cannot be hashed the way cookies and API keys are. They are protected by database access control, and by never being logged, rendered, or returned in a response body.
 
 ### 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.
 
+### Telling the user why a sign-in did not happen
+
+`views/login.hbs` renders one error slot, `{{#if errorMessage}}`, and two paths fill it.
+
+A failed password POST fills it directly from `handleLogin`'s catch, with one message for both a wrong password and an unknown address — the no-enumeration rule.
+
+A **redirect** fills it by carrying a reason code in `?error=`, which `showLogin` turns into copy through `LOGIN_ERROR_MESSAGES` in `src/controllers/auth.ts`. The query value is never rendered: a code the map does not know falls back to `DEFAULT_LOGIN_ERROR_MESSAGE`, so the page cannot reflect a caller's string and a reason the map has not learned yet still says something rather than rendering a silent page. Only an absent or empty `?error=` leaves the slot closed.
+
+Shipped codes are `session_expired`, `auth_required`, and `signin_failed`. Add a row to the map to teach the page a new one — including the ones a capability's own failure redirect uses. `OAUTH_SIGNIN_FAILURE_PATH` defaults to `/login`, so every OAuth refusal lands on this slot.
+
 ---
 
 ## Logout vs. Forget

package/scaffold/src/controllers/auth.ts

@@ -21,6 +21,73 @@ const FIELD_ERROR_MAP: Record<string, string> = {
   passwordConfirmation: 'password_mismatch',
 };
 
+/**
+ * Plain-language copy for the `?error=` reason codes a redirect can carry to
+ * `GET /login`.
+ *
+ * A redirect can only hand the login page a short machine token — a session
+ * that expired, a gate that turned the visitor away, a provider sign-in that
+ * was refused. This map is where that token becomes a sentence a person can
+ * act on, and it is the only thing `showLogin` will put in the error slot.
+ *
+ * Codes are never echoed. An unrecognised value renders
+ * `DEFAULT_LOGIN_ERROR_MESSAGE` instead, so the page cannot be turned into a
+ * reflection point for whatever a caller puts in the query string, and a
+ * redirect whose code this map has not learned yet still says *something*
+ * rather than landing the visitor on a silent page.
+ *
+ * Add a row here to teach the page a new reason; the fallback keeps working
+ * until you do.
+ */
+export const LOGIN_ERROR_MESSAGES: Record<string, string> = {
+  session_expired: 'Your session has expired. Please log in again.',
+  auth_required: 'Please log in to continue.',
+  signin_failed: 'We could not complete that sign-in. Please try again.',
+};
+
+/**
+ * Teach the login page a reason code it does not ship with.
+ *
+ * `LOGIN_ERROR_MESSAGES` above is deliberately extensible — a redirect that
+ * carries a reason is not always one cap-users itself issued. A capability that
+ * turns visitors away at its own door (a provider sign-in refused for a reason
+ * only it can name) registers its copy here at boot, rather than each such
+ * capability inventing a second error slot on the page.
+ *
+ * Additive and idempotent: registering the same code twice keeps the last
+ * writer's copy, and a blank or non-string message is ignored so a misconfigured
+ * override cannot blank out a message the page needs to show. Nothing here can
+ * *remove* a shipped code.
+ */
+export function registerLoginErrorMessages(messages: Record<string, string>): void {
+  for (const [code, message] of Object.entries(messages)) {
+    if (typeof message === 'string' && message.trim() !== '') {
+      LOGIN_ERROR_MESSAGES[code] = message.trim();
+    }
+  }
+}
+
+/** Shown for a reason code this page does not recognise. */
+export const DEFAULT_LOGIN_ERROR_MESSAGE =
+  'We could not complete that sign-in. Please try again.';
+
+/**
+ * Turn a `?error=` query value into copy, or into nothing at all.
+ *
+ * Only an absent or empty value closes the view's `{{#if errorMessage}}` slot.
+ * Anything else — an unknown code, or the array Express hands back for a
+ * repeated parameter — renders the generic message, because the presence of
+ * the parameter is itself the signal that something went wrong, and a page
+ * that stays silent about it is the defect this function exists to close.
+ *
+ * The caller's own string is never returned, whatever it contains.
+ */
+export function loginErrorMessage(code: unknown): string | undefined {
+  if (code === undefined || code === null || code === '') return undefined;
+  if (typeof code !== 'string') return DEFAULT_LOGIN_ERROR_MESSAGE;
+  return LOGIN_ERROR_MESSAGES[code] ?? DEFAULT_LOGIN_ERROR_MESSAGE;
+}
+
 export interface AuthControllerDeps {
   authService: AuthService;
 }
@@ -44,7 +111,10 @@ export function createAuthController(deps: AuthControllerDeps) {
       layout: 'main',
       action: '/login',
       next,
-      error: req.query.error as string | undefined,
+      // `errorMessage` is the name login.hbs reads. Anything else renders
+      // nothing, which is how a redirect-carrying-a-reason ends up on a silent
+      // page (boop-94l).
+      errorMessage: loginErrorMessage(req.query.error),
     });
   }
 

package/scaffold/views/login.hbs

@@ -21,8 +21,12 @@
       <button class="auth-submit" type="submit">Log In</button>
     </form>
 
+    {{!-- The return path goes into a query string here, so it needs cap-web's
+         `urlencode`: Handlebars escapes for HTML, and an unencoded `&` in the
+         path would end the parameter. The hidden field above is a form value,
+         not a URL — HTML escaping is the right and only encoding there. --}}
     <div class="auth-alt">
-      Don't have an account? <a href="/signup{{#if next}}?next={{next}}{{/if}}">Sign up</a>
+      Don't have an account? <a href="/signup{{#if next}}?next={{urlencode next}}{{/if}}">Sign up</a>
     </div>
   </section>
 </div>

package/scaffold/views/signup.hbs

@@ -22,8 +22,12 @@
       <button class="auth-submit" type="submit">Sign Up</button>
     </form>
 
+    {{!-- The return path goes into a query string here, so it needs cap-web's
+         `urlencode`: Handlebars escapes for HTML, and an unencoded `&` in the
+         path would end the parameter. The hidden field above is a form value,
+         not a URL — HTML escaping is the right and only encoding there. --}}
     <div class="auth-alt">
-      Already have an account? <a href="/login{{#if next}}?next={{next}}{{/if}}">Log in</a>
+      Already have an account? <a href="/login{{#if next}}?next={{urlencode next}}{{/if}}">Log in</a>
     </div>
   </section>
 </div>