@happyvertical/smrt-users 0.53.3 → 0.54.0

package/AGENTS.md

@@ -12,7 +12,8 @@ are not prerequisites for unrelated user-package work.
 | `src/services/PermissionResolver.ts` | permission precedence, inherited memberships, guards, RLS, role seeding | [agents/permissions.md](agents/permissions.md) |
 | `src/services/OidcLoginService.ts`, collections and OIDC handlers | identity reconciliation, transaction boundaries, migration readiness | [agents/oidc-provisioning.md](agents/oidc-provisioning.md) |
 | `src/services/MobileAuthService.ts` | mobile handshake, bearer sessions, bootstrap extension boundary | [agents/mobile-auth.md](agents/mobile-auth.md) |
-| `src/services/TerminalAuthService.ts`, `src/collections/CliAuthApproveLimitCollection.ts` | terminal approval concurrency, shared attempt budget, retry-safe database fixtures | [agents/terminal-auth-testing.md](agents/terminal-auth-testing.md) |
+| `src/services/TerminalAuthService.ts`, `src/services/LoginAttemptLimiter.ts`, `src/collections/LoginAttemptCollection.ts` | terminal approval concurrency, shared login budget and lockout (#3273), retry-safe database fixtures | [agents/terminal-auth-testing.md](agents/terminal-auth-testing.md) |
+| `src/services/DeviceCredentialService.ts` | per-person PIN layered on a device session (#3276), verifier seam for other credential kinds | this file, "Security boundaries" |
 | `src/retention.ts` | expired session/token/CLI-auth reaping and retention sweep wiring | [agents/retention.md](agents/retention.md) |
 
 ## Models and authority
@@ -61,11 +62,51 @@ are not prerequisites for unrelated user-package work.
   consumers: null membership can represent inherited authority.
 - Sessions use secure UUIDs; TTL is seconds (default seven days). Access marks
   expired sessions EXPIRED. Magic-link tokens are single use.
+- `Session.authMethod` is server-set at mint time and never read from the
+  client; every mint site in this package sets it. A session with
+  `parentSessionId` is valid only while its parent validates
+  (`loadSessionContext` enforces this; there is no FK cascade by design), may
+  not switch to a tenant other than the parent's, and is revoked with its
+  parent by `destroySession`.
+- Credential sign-ins reserve through `LoginAttemptLimiter` BEFORE credential
+  work and key the subject on the submitted identifier, never a resolved user,
+  so unknown and wrong take the same path. Reservations are fail-closed: keep
+  them on failure, release on success or abort, never skip the reserve.
+  Limiter writes are raw SQL and bypass the change feed; the audit sink is the
+  observability seam, and it must never throw into the sign-in path.
+- `DeviceCredentialService` accepts a person credential only from a
+  first-class session whose `authMethod` is a device-enrollment method
+  (`terminal` by default) and that the host's `assertEnrolledDevice` confirms.
+  A layered or PIN session can never administer PINs regardless of
+  permissions. PIN hashes carry a per-row salt and the configured pepper;
+  treat an unset pepper as a production misconfiguration.
+- A person session carries the PERSON's authority (resolved from their own
+  membership on every load), never the device account's. `Session.data` keys
+  in `SESSION_DATA_KEYS` are server-set controls enforced by the model:
+  `permissionCeiling` only ever intersects (malformed fails closed to none)
+  and suppresses `superAdminBypass`/`systemContext`; `absoluteExpiresAt`
+  bounds `extend()` and `isValid()`; `idleSeconds` overrides the resolving
+  service's TTL policy. Never write them from client input. The ceiling is a
+  sign-in snapshot; `singleOccupant` revokes other children only AFTER a
+  successful mint. A `mustReset` sign-in mints with an empty ceiling and
+  `setPin` ends that session; do not grant it authority another way.
+- A layered session whose tenant differs from its parent's never loads (null
+  is allowed: narrower). Limiter rows carry `retain_until`; retention must
+  not fall back to a process-wide horizon.
+- `Session.parentSessionId` is the parent's bearer: sensitive, never a
+  `list()` filter (raw-SQL id reads, which also keep revocation sweeps free of
+  caller list bounds), never serialized to clients. `users.pin.manage` reaches
+  only people whose every active membership is in the actor's tenant (the PIN
+  is global per person). A sign-in re-checks the verified
+  credential generation AFTER the mint (`stillValid`); keep that ordering.
+  Operation guards deny outside a session's ceiling; `loadPersonSession`
+  re-checks device enrollment.
 - Tenant switching verifies active membership before writing and rotates the
   session ID for non-null targets, revoking the old session. Persist the returned
   `SwitchTenantResult.sessionId`; `switchSessionTenant()` updates the cookie and
   preserves its security settings. Failed switches mutate nothing; null clears
-  do not rotate. `SessionCollection.setSessionTenant()` is unguarded and must
+  do not rotate, and layered sessions never rotate (a replacement would escape
+  the revocation sweeps they depend on). Layers do not nest. `SessionCollection.setSessionTenant()` is unguarded and must
   never receive an untrusted tenant ID.
 - OIDC provisioning is atomic and fail-closed. Preserve exact issuer/subject
   identifiers, claim-source email verification, unique global Person ownership,

package/README.md

@@ -600,6 +600,181 @@ With `enterTenantContext: true`, the same request also enters
 `@happyvertical/smrt-tenancy` context so regular collection access is scoped to
 the current tenant in application code.
 
+### Login rate limiting and lockout
+
+Every credential-based sign-in (terminal approval, device PIN, and any
+password or passkey flow an app adds) draws from one shared budget,
+`LoginAttemptLimiter` (#3273). The budget lives in `users_login_attempts`, so it
+holds across every replica on Postgres; keys are hashed, so the table never
+becomes an index of emails or IPs.
+
+```ts
+import {
+  InvalidCredentialsError,
+  LoginAttemptLimiter,
+  LoginRateLimitError,
+} from '@happyvertical/smrt-users';
+
+const limiter = await LoginAttemptLimiter.create({
+  db,
+  maxAttempts: 5,          // per key, per window
+  windowSeconds: 300,
+  lockout: { baseSeconds: 60, factor: 2, maxSeconds: 3600 },
+  keyPepper: process.env.LOGIN_KEY_PEPPER,
+});
+
+const lease = await limiter.reserve({
+  kind: 'password',
+  subject: submittedEmailKey, // what the client typed — NOT a resolved user
+  source: clientIp,           // or a device/station id
+});
+if (!lease.allowed) throw new LoginRateLimitError(lease); // 429 + Retry-After
+
+try {
+  // Always do the same work for an unknown account as for a wrong password.
+  const ok = await verifyPassword(user?.passwordHash ?? DUMMY_HASH, password);
+  if (!ok || !user) {
+    await lease.fail();
+    throw new InvalidCredentialsError();
+  }
+  await lease.succeed();
+} catch (error) {
+  if (!(error instanceof InvalidCredentialsError)) await lease.release();
+  throw error;
+}
+```
+
+Subject and source are independent budgets; either one exhausted refuses the
+attempt, and a refusal on the source hands the subject reservation back so one
+noisy address cannot burn every account. The failure that exhausts a window —
+or that completes another `maxAttempts` consecutive failures, however they
+were paced across windows — locks the key for `base × factor^n` seconds, where
+`n` counts consecutive exhausted budgets. A success resets the subject's
+streak only; a shared source (a tablet, an office address) keeps its history,
+so one valid credential cannot clear the backoff on guessing at others.
+Instead a source sheds one failure per `sourceStreakDecaySeconds` (default:
+twice the window) since its last failure: mistakes spaced further apart than
+that never add up to locking everyone behind the source, while a burst of
+guesses leaves no time to decay and still escalates. Either streak is forgiven
+outright after `streakResetSeconds` without a failure. Every decision is
+reported to a `LoginAuditSink` — by default a durable `UsersLoginAuditEvent`
+row (pruned after 90 days by the retention sweep), or pass `audit` to forward
+into the host's own log, or `audit: false`. `TerminalAuthService` uses this
+limiter for approvals, keyed on the approving user only under its own subject
+prefix, so that budget never pools with the same person's PIN or password
+budget; pass `loginLimiter` to share one instance and audit sink.
+
+### Per-person PIN on an enrolled device
+
+A shared tablet enrolled through the terminal device-code grant holds a
+device-account bearer session. `DeviceCredentialService` (#3276) lets a person
+sign in **on that device only** with a short credential and mints a session
+*layered on* the device session: it carries `authMethod: 'pin'` and
+`parentSessionId`, is valid only while the device session is, never widens
+tenant scope, and signs out independently.
+
+```ts
+import { createDeviceCredentialHandlers } from '@happyvertical/smrt-users/sveltekit';
+
+export const deviceAuth = createDeviceCredentialHandlers({
+  db,
+  pin: { pepper: process.env.PIN_PEPPER },      // required in production
+  personIdleSeconds: 15 * 60,                   // sliding; default 8 hours
+  personMaxSeconds: 10 * 60 * 60,               // absolute; default none
+  // Optional: the most anyone may do on this device. Default: no ceiling.
+  deviceCeiling: async (device) => devices.permissionCeilingFor(device.user.id),
+  // smrt-users does not own a Device object: say whether this device
+  // account is still an enrolled, active device.
+  assertEnrolledDevice: async (device) =>
+    (await devices.findActiveByUserId(device.user.id)) !== null,
+});
+// POST /api/device/pin/sign-in  → deviceAuth.pinSignIn   (device bearer + { userId, pin })
+// POST /api/device/sign-out     → deviceAuth.signOut     (person bearer)
+// PUT  /api/device/pin          → deviceAuth.setPin      (self with currentPin, or admin)
+// POST /api/device/pin/reset    → deviceAuth.resetPin    (admin; forces a new PIN)
+// DELETE /api/device/pin        → deviceAuth.clearPin
+```
+
+The tablet swaps its `Authorization` bearer to the returned `sessionId` for
+person-attributed work; `loadSessionContext()` resolves it with `parent` set,
+so host gates can tell a person-on-device session from a browser session via
+`authMethod`/`parent` (also on `event.locals.authMethod` and
+`event.locals.sessionParent`). Any bearer that is not a first-class
+device-enrolled session — a browser cookie, a mobile session, another person's
+layered session — is refused with the same 401 as a wrong PIN. Lockout is per
+person **and** per device through the login limiter. Administering PINs needs
+`users.pin.manage` from a non-PIN session; a PIN session can only change its
+own PIN with the current one. An admin reset revokes the person's live PIN
+sessions and flags `mustReset`; signing in with the temporary PIN then yields a
+restricted session that resolves to no permissions and can only call `setPin`,
+which ends it — the person signs in again with the new PIN.
+
+**Whose authority.** The device session authenticates the tablet; the person's
+session authorizes the work. Its `permissions` are resolved on every load from
+the *person's* own membership in the device tenant (role plus per-membership
+overrides) — never the device account's — so a welder and a foreman on the
+same tablet get different permission sets. Both identities are on the resolved
+context: `user` is the person and `parent` (`event.locals.sessionParent`, and
+`session.parent` on the request permission context) is the device session and
+its account, so a consumer can record "this person, at this tablet".
+
+**Device ceiling.** `deviceCeiling(device)` may return permission slugs that
+cap every person on that device. A non-null result is snapshotted into the
+person's session at sign-in (`data.permissionCeiling`) and intersected with
+their resolved permissions on every load; it only removes slugs, and `[]`
+leaves none. A ceilinged session never receives `superAdminBypass` or
+`systemContext` from `withSessionPermissionContext`, and
+`assertOperationPermission` / `checkOperationPermission` called inside that
+session deny anything outside the ceiling. Returning `null` (or
+omitting the hook) means no ceiling. Because it is a snapshot, **a ceiling
+change applies at each person's next sign-in**; a throwing hook refuses the
+sign-in.
+
+**Switching people.** `signOut` ends only the person's session. With
+`singleOccupant` (default `true`) a successful sign-in also ends every other
+person's session on that device session, so signing in as the next person is
+the hand-over; a failed sign-in leaves the current person signed in. (Two
+sign-ins that overlap on one device can end each other — both are refused and
+the person signs in again.) Set
+`singleOccupant: false` for devices several people stay signed in on.
+`personIdleSeconds` is a sliding idle timeout stored on the session
+(`data.idleSeconds`), so it slides by that value whichever `SessionService`
+resolves the bearer and is independent of the device session's long life.
+`personMaxSeconds` adds an absolute lifetime (`data.absoluteExpiresAt`) that
+activity cannot extend. `permissionCeiling`, `idleSeconds`, and
+`absoluteExpiresAt` are reserved `Session.data` keys (`SESSION_DATA_KEYS`):
+server-set at mint, never to be written from client input.
+
+**Operational contracts.** `parent.sessionId` is the device's bearer
+credential: keep `SessionContext.parent` / `locals.sessionParent` server-side
+and give clients `parent.userId` as the device identity
+(`Session.parentSessionId` is a sensitive field and never appears in public
+serialization). Resolve person bearers with `service.loadPersonSession(token)`:
+it re-checks `assertEnrolledDevice` on every call and revokes the person
+session of a device that fails it (the PIN management handlers resolve person
+bearers the same way). A host that resolves them through its own
+`SessionService` must instead revoke the device's bearer session when it
+un-enrols the device. `assertEnrolledDevice` returning `false` is un-enrolment
+(the person session is revoked); a throw only refuses that request. The PIN is
+one per person across tenants, so PIN administration (`users.pin.manage`)
+reaches only people whose every active membership is in the administrator's
+session tenant; people who belong to several tenants manage their own PIN from
+a first-class session. `users.pin.manage` is impersonation-equivalent on
+enrolled devices — whoever sets a person's PIN can sign in as them there, and
+the membership rule is checked when the PIN is written, not when the person
+later joins another tenant — so grant it like an owner-level permission; every
+administrative change is audited with the actor's id. Any PIN change ends the sessions minted under the old
+PIN (a person changing their own keeps the session they changed it from).
+
+Existing installations need `smrt db:migrate` for the additive
+`sessions.auth_method` / `sessions.parent_session_id` columns and the
+`users_login_attempts`, `users_login_audit_events`, and
+`users_pin_credentials` tables.
+
+Other credential kinds (a fob or badge reader, say) implement
+`DeviceCredentialVerifier` and go through `service.signIn(verifier, input)`;
+`PinVerifier` is the reference implementation.
+
 ### Request-scoped database access
 
 Generated SvelteKit helpers and custom server code can read the current
@@ -833,7 +1008,9 @@ TenantService supports three modes: `flexible` (no auto-create), `personal` (aut
 | `Tenant` | Organizational boundary. STI. Hierarchical via `parentTenantId`/`hierarchyPath`. |
 | `Role` | Permission template. `tenantId = null` for system roles. `isSystem` blocks deletion. |
 | `Permission` | Named capability. Slug format: `resource.action`. |
-| `Session` | Server-side session. Secure UUID. TTL in seconds. |
+| `Session` | Server-side session. Secure UUID. TTL in seconds. `authMethod` records the channel; `parentSessionId` makes it a layered session valid only while its parent is. Reserved `data` keys (`SESSION_DATA_KEYS`) carry a permission ceiling, sliding idle timeout, and absolute expiry. |
+| `UsersLoginAttempt`, `UsersLoginAuditEvent` | Hashed-key login budget rows and durable sign-in audit events (#3273). Closed generated surface. |
+| `UsersPinCredential` | Per-person scrypt PIN hash for enrolled-device sign-in (#3276). Closed generated surface. |
 | `Group` | Team within a tenant. Gains permissions via GroupRole. |
 | `Membership` | User + Tenant + Role junction. UNIQUE(userId, tenantId). |
 | `MembershipOverride` | Per-user permission grant/deny on a membership. |
@@ -851,6 +1028,7 @@ TenantService supports three modes: `flexible` (no auto-create), `personal` (aut
 | `MembershipOverrideCollection`, `TenantPermissionOverrideCollection` | Override management at membership and tenant levels |
 | `GroupCollection`, `GroupMemberCollection`, `GroupRoleCollection`, `RolePermissionCollection` | Group and role-permission junction management |
 | `AccessRequestCollection` | AccessRequest queries: `findByEmail()`, `findOpenByEmail()`, `findByStatus()`, `findOpen()` |
+| `UsersLoginAttemptCollection`, `UsersLoginAuditEventCollection`, `UsersPinCredentialCollection` | Atomic limiter primitives, audit storage, and PIN credential rows behind the services below |
 
 ### Services
 
@@ -861,7 +1039,9 @@ TenantService supports three modes: `flexible` (no auto-create), `personal` (aut
 | `PermissionCatalogService`, `syncPermissionCatalog()` | Discovers manifest/config/runtime permissions and upserts them into `Permission` rows. |
 | `registerPermissionDefinitions()` | Register app or integration permissions at runtime and receive an unregister cleanup function. |
 | `generatePostgresPermissionSql()`, `applyPostgresPermissionPolicies()` | Preview or apply Postgres RLS helper functions and table policies. |
-| `SessionService` | High-level session management. `createSession()`, `loadSessionContext()`, `destroySession()`; tenant contexts include direct or inherited membership provenance. |
+| `SessionService` | High-level session management. `createSession()`, `loadSessionContext()`, `destroySession()`; tenant contexts include direct or inherited membership provenance, `authMethod`, and `parent` for layered sessions. |
+| `LoginAttemptLimiter` | Shared sign-in budget with exponential lockout and audit (#3273): `reserve()` → lease `.fail()`/`.succeed()`/`.release()`. `LoginRateLimitError`, `InvalidCredentialsError`, `LoginAuditSink`, `DurableLoginAuditSink`. |
+| `DeviceCredentialService` | Per-person sign-in layered on an enrolled device session (#3276): `signInWithPin()`, `signIn(verifier, input)`, `signOut()`, `setPin()`, `resetPin()`, `clearPin()`. Person authority with optional `deviceCeiling`, `singleOccupant` hand-over, `personIdleSeconds` / `personMaxSeconds`. `PinVerifier`, `DeviceCredentialVerifier`. |
 | `OidcLoginService` | Generic OIDC authorization-code login with PKCE for Kanidm, Dex, and other standards-compliant providers. |
 | `backfillLegacyUserProfiles` | Transactionally create and link canonical global Person Profiles for legacy Users; never creates OIDC identities or infers ownership. |
 | `backfillUserEmailKeys` | Idempotently populate durable normalized-email keys after migrating legacy Users; fails closed on duplicates. |
@@ -886,6 +1066,7 @@ TenantService supports three modes: `flexible` (no auto-create), `personal` (aut
 | `beginOidcLogin`, `completeOidcLogin` | Low-level SvelteKit helpers for custom OIDC login routes |
 | `createOidcLoginHandler`, `createOidcCallbackHandler` | Ready-to-use SvelteKit route handlers for OIDC login and callback |
 | `createMobileAuthHandlers` | Mountable `/api/mobile` PKCE, bearer session, bootstrap, logout, and route-guard handlers |
+| `createDeviceCredentialHandlers` | Mountable PIN sign-in, sign-out, and PIN management handlers for enrolled devices |
 | `resolveMobileUploadDedupKey` | Resolves `clientCaptureId` with `Idempotency-Key` fallback for app-owned multipart routes |
 | `SessionLocals` | Type for `event.locals` (extend in `app.d.ts`) |
 
@@ -906,6 +1087,8 @@ for authentication, deduplication, and status semantics.
 | `ACCESS_REQUEST_CAPABILITIES`, `AccessRequestError` | Operator capability slugs; typed domain error (`error.code`) |
 | `DEFAULT_ROLE_SLUGS`, `DEFAULT_ROLES`, `DEFAULT_TENANT_POLICY` | System role slugs, role configs, default tenant policy |
 | `DEFAULT_SESSION_TTL`, `MAX_TENANT_HIERARCHY_DEPTH` | 604800 (7 days in seconds), 10 |
+| `DEFAULT_LOGIN_MAX_ATTEMPTS`, `DEFAULT_LOGIN_ATTEMPT_WINDOW_SECONDS`, `DEFAULT_LOGIN_LOCKOUT_*` | 5 attempts per 300 s window; lockout 60 s × 2ⁿ, capped at 3600 s |
+| `DEFAULT_PIN_MANAGE_PERMISSION`, `PIN_LOGIN_KIND` | `users.pin.manage`, `pin` |
 | `TenantHierarchyError` | Thrown on a missing parent, a cycle, or exceeding the hierarchy depth limit (`code`) |
 | `TenantHierarchyMaterializationError` | Thrown by `materializeTenantHierarchy` when any tenant's parent chain is broken; lists `problems` |
 

package/agents/retention.md

@@ -24,15 +24,22 @@ reap them.
   optionally for exactly that reason. Registering is not scheduling: nothing is
   deleted until something runs a sweep.
 - **Task names** are `users-sessions`, `users-magic-link-tokens`,
-  `users-cli-auth-requests` — prefixed with the package's short name because
-  the retention registry is one process-global namespace. Opt one out with
+  `users-cli-auth-requests`, `users-login-attempts`, `users-login-audit-events`
+  — prefixed with the package's short name because the retention registry is
+  one process-global namespace. Opt one out with
   `runRetentionSweep(db, { tasks: { 'users-sessions': false } })` or
   `smrt db:prune --skip users-sessions`; `unregisterUserRetentionTasks()`
-  removes all three.
-- **There is no retention window to configure.** An expired credential has
-  nothing worth retaining, so each task deletes only already-expired rows. An
-  application that keeps expired sessions for audit should opt the task out and
-  archive them itself.
+  removes all of them.
+- **The credential tasks have no retention window to configure.** An expired
+  credential has nothing worth retaining, so each deletes only already-expired
+  rows. An application that keeps expired sessions for audit should opt the
+  task out and archive them itself. The two #3273 tasks differ: limiter rows
+  are pruned once past their own `retain_until` — written by the limiter from
+  its configured window and streak-forgiveness horizon, so a custom-configured
+  limiter is never swept early — and never while a lockout is live; audit
+  events are pruned after
+  `DEFAULT_LOGIN_AUDIT_RETENTION_DAYS` (90). A host that needs longer audit
+  retention opts `users-login-audit-events` out and archives.
 - **All three are a single counted DELETE**, not a hydrate-and-delete loop.
   They now run unattended on a timer, and a per-row delete that throws part-way
   leaves the rest of the expired rows un-reaped — the #1400 reasoning that