@nauticana/sail 0.8.3 → 0.9.0

package/README.md

@@ -279,7 +279,7 @@ interface SailGuiConfig {
 | `GET /api/billing/invoices` | Invoice history |
 | `GET /api/billing/payment-methods` | Saved payment methods |
 
-Device registration happens within `/public/2fa/verify` when `trustDevice=true`.
+Device registration happens within `/public/2fa/verify` when `trustDevice=true`. Since **keel v0.9 / sail v0.9.0**, the trusted-device credential is a server-minted `keel_td` cookie (HttpOnly + Secure + SameSite=Strict) — not a client-supplied fingerprint. sail sets `withCredentials: true` on the login and 2FA-verify calls so the cookie round-trips; see [Enabling 2FA → Cross-origin cookie requirement](#cross-origin-cookie-requirement) below.
 
 ## Enabling 2FA in your project
 
@@ -297,6 +297,22 @@ import { TwoFactorVerifyComponent, TwoFactorSetupComponent, TrustedDevicesCompon
 
 The login flow handles 2FA automatically: when the backend returns `twoFactorRequired: true`, sail redirects to `/login/2fa`. No other code changes needed.
 
+### Cross-origin cookie requirement
+
+The "trust this device" feature (keel v0.9+) is backed by a server-set HttpOnly cookie named `keel_td`. The lifecycle is entirely server-driven:
+
+1. On `POST /public/2fa/verify` with `trustDevice: true`, keel mints a 32-byte secret, stores its SHA-256, and returns the raw secret to the browser **only** as a `Set-Cookie: keel_td=…` header (never in the JSON body).
+2. On the next `POST /public/login/local` (or `/public/login/gmail`), the browser sends the `keel_td` cookie back, keel hashes it, finds the matching row, and **skips the 2FA prompt**.
+
+For the browser to store and resend that cookie, the requests must be credentialed. sail already sets `withCredentials: true` on `login()`, `loginWithGoogle()`, `verify2FALogin()`, and `verifyBackupCode()` — **you do not add this in your app code**. But the keel backend must permit credentialed CORS, or the browser drops the cookie and every login re-prompts for 2FA:
+
+- **Same-origin** deployments (SPA served from the same host as the API) work with no extra config — credentialed same-origin requests are always allowed.
+- **Cross-origin** deployments (SPA on a different host/port than the API) require the keel `HttpBackend` to set:
+  - `AllowCredentials: true` → emits `Access-Control-Allow-Credentials: true`
+  - `Origin` = the **exact** SPA origin (e.g. `https://app.example.com`). A wildcard `*` is rejected by the browser for credentialed responses — keel's CORS layer enforces this.
+
+If "trust this device" appears to do nothing (user is 2FA-prompted on every login despite checking the box), the cause is almost always a missing `AllowCredentials` / wildcard-origin on the backend — open devtools and confirm the `keel_td` cookie is actually set after a successful verify.
+
 ## Billing
 
 sail ships a shared `BillingService` and three billing components backed by keel's payment endpoints (see [keel/SHARED_PAYMENT.md](https://github.com/nauticana/keel/blob/main/SHARED_PAYMENT.md) for the provider contract — Stripe by default, pluggable).
@@ -532,6 +548,81 @@ Under the hood, the component calls `BaseAuthService.loginSocial(provider, idTok
 
 For backward compatibility, the older OAuth-code flow `BaseAuthService.loginWithGoogle(code)` (hits `/public/login/google`) is still supported; prefer `loginSocial` for new code.
 
+## Adding a new domain table
+
+When your project owns a table that isn't part of basis (e.g. `favorite_location`, `support_ticket`, `vehicle`), follow the pattern below so the row plays nicely with keel's generic CRUD endpoints and the sail `<table-edit>` / `<table-list>` components.
+
+### 1. Backend: register the route
+
+Add a `rest_api_header` seed row so keel mounts the CRUD endpoints at boot:
+
+```sql
+INSERT INTO rest_api_header (id, master_table)
+VALUES ('favorite_location', 'favorite_location');
+```
+
+This exposes `GET/POST /api/v1/favorite_location/list,get,post,delete`. The binary reads `rest_api_header` once at startup, so restart `httpsrv` after seeding.
+
+### 2. Frontend: model class extends `SiudAction`
+
+Every row submitted through keel's bulk-POST endpoint is dispatched by an `op_code` field — `I` insert, `U` update, `D` delete, `R` recurse-children, `S` select-only (no-op). Rows without `op_code` are **silently skipped**: the handler still returns 201, but no SQL runs. The way to stay safe is to extend `SiudAction` (which carries `op_code: OpCodeValue` defaulted to `'S'`) rather than declaring a plain interface.
+
+```ts
+import { SiudAction } from '@nauticana/sail';
+
+export class FavoriteLocation extends SiudAction {
+  Id?: number;
+  UserId?: number;
+  Label?: string;
+  Address?: string;
+  Lat?: number;
+  Lng?: number;
+  SortOrder?: number;
+}
+```
+
+Field names are **PascalCase** — keel marshals SQL columns to `column.pascal_name` (i.e. `user_id` → `UserId`) for the wire format, and the `<table-edit>` component generator follows the same convention. Snake_case fields will round-trip in some paths but break others (e.g. `<table-edit>` form binding); pick PascalCase up front.
+
+### 3. Frontend: flip op_code before save
+
+When the row leaves the UI, set `op_code` to the operation you actually want:
+
+```ts
+import { OpCode } from '@nauticana/sail';
+import { BackendService } from 'service/rest_service';
+import { FavoriteLocation } from 'model/tripdb';
+
+const backend = inject(BackendService);
+
+const row = new FavoriteLocation();
+row.op_code = existing?.Id ? OpCode.Update : OpCode.Insert;
+row.Id = existing?.Id;
+row.Label = 'Home';
+row.Address = '...';
+
+backend.post<FavoriteLocation>('v1/favorite_location', [row]).subscribe();
+```
+
+The `<table-edit>` and `<table-list>` components handle this automatically — they tag fetched rows `'S'`, flip to `'U'` on dirty-edit, `'I'` for new rows, and `'D'` when the user deletes. You only need to set `op_code` manually when bypassing those components (custom save flows, bulk imports, etc.).
+
+### 4. Backend permissions
+
+Grant `TABLE SELECT/INSERT/UPDATE/DELETE` to the relevant roles in `authorization_role_permission`. For owner-scoped tables (rows have a `user_id` FK to `user_account`), keel auto-detects `UserSpecific` from the FK + column-name combination and pins the session's user id on insert + filters list/get to the owner automatically — no extra wiring needed.
+
+```sql
+INSERT INTO authorization_role_permission (role_id, authorization_object_id, action, low_limit) VALUES
+  ('RIDER', 'TABLE', 'INSERT', 'favorite_location'),
+  ('RIDER', 'TABLE', 'UPDATE', 'favorite_location'),
+  ('RIDER', 'TABLE', 'DELETE', 'favorite_location');
+-- SELECT is granted via the wildcard ('RIDER', 'TABLE', 'SELECT', '*') if you have one.
+```
+
+### Footguns
+
+- **Plain interfaces instead of `extends SiudAction`** — `op_code` field never exists, every row in a bulk POST is silently skipped, handler returns 201, table stays empty. Symptom: "saving says success but the list comes back empty."
+- **Snake_case fields** — keel marshals PascalCase, so a snake_case `address` field on the wire serializes as `Address` from keel but your client TS expects `address`. Mixed payloads break in subtle ways (read paths show data, write paths look like no-ops).
+- **Forgetting to restart httpsrv after seeding `rest_api_header`** — the route table is built once at startup. New rows = 404 until restart.
+
 ## Account deletion / logout everywhere / push tokens
 
 These are App Store / Play Store compliance primitives from keel. All are opt-in.
@@ -632,7 +723,7 @@ npm update @nauticana/sail
 Or to install a specific version:
 
 ```bash
-npm install @nauticana/sail@0.5.0
+npm install @nauticana/sail@0.9.0
 ```
 
 ## Migrating to v0.5.0
@@ -1102,6 +1193,127 @@ Expected errors after the upgrade:
 
 v0.8.1 targets **keel v0.8.3**. The shared keel API surface didn't grow in this release; the version pin tracks keel's matching v0.8.x line. See [keel/README.md → Migration Guide](https://github.com/nauticana/keel/blob/main/README.md) for the matching backend changes.
 
+## Migrating to v0.8.2 — server-driven OTP resend cooldown
+
+Additive change. v0.8.1 consumers keep compiling.
+
+### What changed
+
+`OtpResponse` (model/auth.ts) gained an optional `resendCountdownSec?: number` field. keel v0.8.4 populates it from `--otp_ttl_seconds` so the resend timer in `OtpInputComponent` can match the OTP code's actual server-side lifetime instead of relying on the client-side fallback (still 30s for back-compat with older keel deployments / dev mocks that don't return the field).
+
+```ts
+export interface OtpResponse {
+  otpToken: string;
+  resendCountdownSec?: number;   // NEW — present when keel >= v0.8.4
+}
+```
+
+`OtpInputComponent.resendCountdownSec` (input, default 30) is **unchanged**. The recommended pattern is for the page that calls `sendOtp` to capture `res.resendCountdownSec` from the response and pass it to the input so the timer reflects server intent.
+
+### Adoption
+
+Two-step plumbing on the page that owns the OTP screen:
+
+1. **Capture from the send response.** After `auth.sendOtp({...}).subscribe(...)`, store `res.resendCountdownSec` in component state and forward it via router state when navigating to the confirm screen.
+
+   ```ts
+   this.auth.sendOtp({ contact, contactType, purpose: 'login' }).subscribe({
+     next: (res) => {
+       this.router.navigate(['/login/confirm'], {
+         state: {
+           otpToken: res.otpToken,
+           contact,
+           resendCountdownSec: res.resendCountdownSec,   // forward server value
+         },
+       });
+     },
+   });
+   ```
+
+2. **Read on the confirm screen + bind to the input.** Default a local signal to 30 (the legacy fallback) so older keels and the dev OTP mock keep working, then overwrite from router state and from `onResend` responses.
+
+   ```ts
+   readonly resendCountdownSec = signal(30);
+
+   constructor() {
+     const state = this.router.getCurrentNavigation()?.extras.state;
+     if (state && typeof state['resendCountdownSec'] === 'number') {
+       this.resendCountdownSec.set(state['resendCountdownSec']);
+     }
+   }
+
+   onResend() {
+     this.auth.sendOtp({...}).subscribe({
+       next: (res) => {
+         if (typeof res.resendCountdownSec === 'number') {
+           this.resendCountdownSec.set(res.resendCountdownSec);
+         }
+       },
+     });
+   }
+   ```
+
+   ```html
+   <sail-otp-input
+     [contact]="contact()"
+     [resendCountdownSec]="resendCountdownSec()"
+     (codeComplete)="verifyOtp($event)"
+     (resend)="onResend()" />
+   ```
+
+### Backend alignment
+
+v0.8.2 targets **keel v0.8.4**. The new `resendCountdownSec` response field is documented in [keel/README.md → Migration Guide (v0.8.4)](https://github.com/nauticana/keel/blob/main/README.md). Sail will tolerate older keels that don't return the field — the input falls back to its 30s default.
+
+## Migrating to v0.9.0 — server-set trusted-device cookie
+
+**Breaking change.** v0.9.0 adopts keel's v0.9 trusted-device model: the "trust this device" credential moves from a client-supplied `deviceFingerprint` string to a server-minted, HttpOnly `keel_td` cookie. This closes two weaknesses in the old scheme — the client picked the fingerprint value (so a malicious client could replay a known fingerprint across users), and keel stored it in plaintext (so a DB leak handed an attacker direct 2FA-bypass material). The new secret is server-generated, returned only via `Set-Cookie`, and stored as a SHA-256 hash.
+
+This release targets **keel v0.9** (the "bdsmail upstream" trusted-device rework). It will **not** interoperate correctly with keel < v0.9 — older keels expect the `deviceFingerprint` field that sail no longer sends, so "trust this device" silently fails. Upgrade the backend in lockstep.
+
+### What changed in the public API
+
+| Symbol | Before (v0.8.x) | After (v0.9.0) |
+|---|---|---|
+| `BaseAuthService.login()` | `login(username, password, deviceFingerprint?)` | `login(username, password)` |
+| `BaseAuthService.verify2FALogin()` | `verify2FALogin(code, trustDevice?, deviceFingerprint?, deviceName?)` | `verify2FALogin(code, trustDevice?, deviceName?)` |
+| `TwoFactorVerifyRequest` (model) | had `deviceFingerprint?: string` | field removed |
+| `TrustedDevice` (model) | had `fingerprint: string` | field removed (keel no longer returns it — it was the bypass credential) |
+
+`trustDevice` and `deviceName` are unchanged — `deviceName` is still a real field keel records as the human-readable label in the trusted-device list.
+
+### Migration steps
+
+Most consumers use sail's bundled `LoginComponent` / `TwoFactorVerifyComponent` and **need no code changes** — those components were updated internally. Steps below apply only if you call the auth API directly or wrap these components.
+
+1. **Drop the `deviceFingerprint` argument** from any direct call to `login()` or `verify2FALogin()`:
+
+   ```diff
+   - this.auth.login(username, password, this.getDeviceFingerprint());
+   + this.auth.login(username, password);
+
+   - this.auth.verify2FALogin(code, trustDevice, this.getDeviceFingerprint(), deviceName);
+   + this.auth.verify2FALogin(code, trustDevice, deviceName);
+   ```
+
+2. **Delete any client-side fingerprint generation.** The old `crypto.randomUUID()` → `localStorage['deviceFingerprint']` pattern is dead — the server owns the credential now. You can also clear the stale key:
+
+   ```ts
+   localStorage.removeItem('deviceFingerprint');
+   ```
+
+3. **Stop reading `TrustedDevice.fingerprint`.** It no longer exists on the type. If you rendered a "this device" badge by comparing it to a stored fingerprint, **remove that** — the credential is an HttpOnly cookie, so JavaScript cannot read it and the current device is no longer identifiable client-side. sail removed the badge from its own `TrustedDevicesComponent`.
+
+4. **Confirm credentialed CORS on the backend.** This is the one operational step that is easy to miss. The `keel_td` cookie only round-trips on credentialed requests. sail sends `withCredentials: true` automatically, but the keel `HttpBackend` must cooperate — see [Enabling 2FA → Cross-origin cookie requirement](#cross-origin-cookie-requirement). Same-origin deployments need nothing; cross-origin deployments need `AllowCredentials: true` and an exact (non-wildcard) `Origin`.
+
+### Existing trusted-device rows
+
+No data migration needed. Rows written under the old plaintext-fingerprint scheme will never match the new hashed lookup and expire naturally via their 30-day `expires_at`. Affected users are prompted for 2FA on their next login and can re-opt into "trust this device". (Backends that want to clean up early: `DELETE FROM user_trusted_device WHERE LENGTH(device_fingerprint) <> 64` — new hashes are exactly 64 hex chars.)
+
+### Backend alignment
+
+v0.9.0 targets **keel v0.9**. The full backend contract is documented in [keel/README.md → Trusted-device model (v0.9) and Migration from v0.8 trusted-device API](https://github.com/nauticana/keel/blob/main/README.md). Verify your backend sets `AllowCredentials` (cross-origin only) before rolling out.
+
 ## Modernization items
 
 When you extend sail in your own app, apply the same patterns sail itself follows. Downstream projects that copied templates or scaffolding from earlier sail versions will benefit from the same sweep. This list is a checklist — none are sail-specific.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nauticana/sail",
-  "version": "0.8.3",
+  "version": "0.9.0",
   "description": "Metadata-driven Angular component library for CRUD admin frontends backed by the keel Go backend. Tables, forms, navigation, OTP/2FA/social auth, billing, payout onboarding.",
   "main": "src/index.ts",
   "files": [

package/src/component/login/otp_input.ts

@@ -24,7 +24,13 @@ export class OtpInputComponent implements OnInit {
 
   readonly length = input(6);
   readonly contact = input('');
-  readonly resendCountdownSec = input(30);
+  // Fallback only. Consumers should pass the value returned by
+  // /public/otp/send in `resendCountdownSec` on the response — that is
+  // the authoritative value (sourced from the keel server's
+  // --otp_token_ttl_seconds flag and matches the lifetime of the OTP
+  // code itself). 300s is the legacy default, kept so existing callers
+  // without the new field don't break.
+  readonly resendCountdownSec = input(300);
   readonly disabled = input(false);
 
   readonly codeComplete = output<string>();

package/src/component/security/trusted_devices.html

@@ -24,9 +24,6 @@
             <tr>
               <td>
                 {{ device.name }}
-                @if (isCurrentDevice(device)) {
-                  <span class="current-device-badge">(this device)</span>
-                }
               </td>
               <td>{{ formatDate(device.last_used_at) }}</td>
               <td>{{ formatDate(device.created_at) }}</td>

package/src/component/security/trusted_devices.ts

@@ -80,11 +80,6 @@ export class TrustedDevicesComponent extends BaseAsync implements OnInit {
     );
   }
 
-  isCurrentDevice(device: TrustedDevice): boolean {
-    const fp = localStorage.getItem('deviceFingerprint');
-    return !!fp && device.fingerprint === fp;
-  }
-
   formatDate(dateStr: string): string {
     if (!dateStr) return '';
     return dateStr.slice(0, 16).replace('T', ' ');

package/src/component/security/twofactor_verify.ts

@@ -67,21 +67,11 @@ export class TwoFactorVerifyComponent extends BaseAsync {
       this.auth.verify2FALogin(
         code!,
         trustDevice ?? false,
-        this.getDeviceFingerprint(),
         this.getDeviceName(),
       );
     }
   }
 
-  private getDeviceFingerprint(): string {
-    let fp = localStorage.getItem('deviceFingerprint');
-    if (!fp) {
-      fp = crypto.randomUUID();
-      localStorage.setItem('deviceFingerprint', fp);
-    }
-    return fp;
-  }
-
   private getDeviceName(): string {
     return navigator.userAgent.substring(0, 80);
   }

package/src/model/appdata.ts

@@ -160,7 +160,6 @@ export interface TwoFactorVerifyRequest {
   code:             string;
   loginToken?:      string;
   trustDevice?:     boolean;
-  deviceFingerprint?: string;
   deviceName?:      string;
 }
 
@@ -172,7 +171,6 @@ export interface TwoFactorVerifyResponse {
 export interface TrustedDevice {
   id:         number;
   name:       string;
-  fingerprint: string;
   last_used_at: string;
   created_at:   string;
 }

package/src/model/auth.ts

@@ -80,6 +80,10 @@ export interface OtpRequest {
 // wrong code.
 export interface OtpResponse {
   otpToken: string;
+  // Seconds the client should wait before allowing a resend; mirrors
+  // the server's --otp_ttl_seconds. Optional for back-compat with
+  // older keel versions that didn't return it.
+  resendCountdownSec?: number;
 }
 
 export interface OtpVerifyRequest {

package/src/service/auth.service.ts

@@ -104,8 +104,11 @@ export abstract class BaseAuthService extends BaseRestService {
     this.initRoutes();
   }
 
-  login(username: string, password: string, deviceFingerprint?: string) {
-    this.http.post<LoginResponse2FA>(this.loginUrl, { username, password, deviceFingerprint }).subscribe({
+  login(username: string, password: string) {
+    // withCredentials so the browser sends the server-set `keel_td` cookie
+    // (keel v0.9 trusted-device secret). When it maps to a trusted row, keel
+    // skips 2FA. The old client-supplied `deviceFingerprint` field is gone.
+    this.http.post<LoginResponse2FA>(this.loginUrl, { username, password }, { withCredentials: true }).subscribe({
         next: (res) => {
             if (res.twoFactorRequired && res.loginToken) {
                 localStorage.setItem('loginToken', res.loginToken);
@@ -121,7 +124,7 @@ export abstract class BaseAuthService extends BaseRestService {
   }
 
   loginWithGoogle(code: string, redirectUri?: string) {
-    this.http.post<LoginResponse2FA>(this.loginGoogleUrl, { code, redirectUri }).subscribe({
+    this.http.post<LoginResponse2FA>(this.loginGoogleUrl, { code, redirectUri }, { withCredentials: true }).subscribe({
         next: (res) => {
             if (res.twoFactorRequired && res.loginToken) {
                 localStorage.setItem('loginToken', res.loginToken);
@@ -156,7 +159,7 @@ export abstract class BaseAuthService extends BaseRestService {
   /**
    * Verify a TOTP code during the LOGIN flow (public endpoint). Uses `/public/2fa/verify`
    */
-  verify2FALogin(code: string, trustDevice = false, deviceFingerprint?: string, deviceName?: string) {
+  verify2FALogin(code: string, trustDevice = false, deviceName?: string) {
     const loginToken = localStorage.getItem('loginToken');
     if (!loginToken) {
         console.error('No login token found');
@@ -166,10 +169,11 @@ export abstract class BaseAuthService extends BaseRestService {
         code,
         loginToken,
         trustDevice,
-        deviceFingerprint,
         deviceName,
     };
-    this.http.post<TwoFactorVerifyResponse>(this.twoFactorLoginVerifyUrl, request).subscribe({
+    // withCredentials so the browser stores the `keel_td` cookie keel sets on
+    // a `trustDevice:true` verify — that cookie is what skips 2FA next login.
+    this.http.post<TwoFactorVerifyResponse>(this.twoFactorLoginVerifyUrl, request, { withCredentials: true }).subscribe({
         next: (res) => {
             if (res.valid && res.token) {
                 localStorage.removeItem('loginToken');
@@ -185,7 +189,7 @@ export abstract class BaseAuthService extends BaseRestService {
   /** Verify a single-use backup code during the LOGIN flow (public endpoint). */
   verifyBackupCode(code: string) {
     const loginToken = localStorage.getItem('loginToken');
-    return this.http.post<TwoFactorVerifyResponse>(this.twoFactorBackupVerifyUrl, { code, loginToken });
+    return this.http.post<TwoFactorVerifyResponse>(this.twoFactorBackupVerifyUrl, { code, loginToken }, { withCredentials: true });
   }
 
   /**