@nauticana/sail 1.1.26 → 1.1.28

package/README.md

@@ -2,7 +2,7 @@
 
 A shared Angular component library for building CRUD-based admin frontends. Provides table management, form handling, navigation, authentication, two-factor authentication, and trusted device management — all driven by metadata from a [keel](https://github.com/nauticana/keel) Go backend.
 
-> **Compatibility:** sail and keel are versioned in lock-step. The current line is **sail v1.1.x ↔ keel v1.2.x**; sail v1.1.18 adopts keel v1.2.58 (refresh-token rotation, `/public/logout`, setup intents, the realtime hub), the agency components in sail v1.1.14 require keel v1.2.41 (sail v1.1.9 needs keel v1.2.16 for the OAuth-connect layer). Earlier lines: **sail v0.5.x ↔ keel v0.5.x**, **sail v0.6.x / v0.7.x ↔ keel v0.7.x**, **sail v0.8.x ↔ keel v0.8.x**, **sail v0.9.x ↔ keel v0.9.x**. Newer sail releases extend the contract — older keel servers reject unknown endpoints with HTTP 404 / 400. The v0.8.x line additionally ships the `table_action` framework (per-table custom buttons surfaced in `TableList` / `TableSearch` / `TableEdit` / `TableDetail`); see the [Migrating to v0.7.0 §5 — TableAction](#migrating-to-v070--payout-user-payment-methods-table-actions) section for the seed shape (basis `table_action` + `authorization_object` + `authorization_object_action` rows) and the [keel/README Table Actions](https://github.com/nauticana/keel#table-actions) section for backend wiring via `handler.WrapTableAction`.
+> **Compatibility:** sail and keel are versioned in lock-step. The current line is **sail v1.1.x ↔ keel v1.2.x**; sail v1.1.28 adopts keel v1.2.93 (absolute `return` for the OAuth hand-off), sail v1.1.18 adopts keel v1.2.58 (refresh-token rotation, `/public/logout`, setup intents, the realtime hub), the agency components in sail v1.1.14 require keel v1.2.41 (sail v1.1.9 needs keel v1.2.16 for the OAuth-connect layer). Earlier lines: **sail v0.5.x ↔ keel v0.5.x**, **sail v0.6.x / v0.7.x ↔ keel v0.7.x**, **sail v0.8.x ↔ keel v0.8.x**, **sail v0.9.x ↔ keel v0.9.x**. Newer sail releases extend the contract — older keel servers reject unknown endpoints with HTTP 404 / 400. The v0.8.x line additionally ships the `table_action` framework (per-table custom buttons surfaced in `TableList` / `TableSearch` / `TableEdit` / `TableDetail`); see the [Migrating to v0.7.0 §5 — TableAction](#migrating-to-v070--payout-user-payment-methods-table-actions) section for the seed shape (basis `table_action` + `authorization_object` + `authorization_object_action` rows) and the [keel/README Table Actions](https://github.com/nauticana/keel#table-actions) section for backend wiring via `handler.WrapTableAction`.
 
 **Recent additions:** `BaseAuthService.acceptToken(jwt)` — adopt an externally-minted JWT (registration / SSO-handoff flows) and run the full post-login sequence (store under the canonical `jwt` key, load appdata, init routes); apps must use this instead of writing `localStorage` directly. `BaseRestService.analytic<T>(endpoint, params?)` — GET a keel `analytic/<endpoint>` report and return its rows. `passwordPolicyValidator` + `BaseAuthService.ensurePasswordPolicy()` — validate passwords against keel's policy (via `SailGuiConfig.passwordPolicyUrl`); see Configuration reference.
 
@@ -308,11 +308,25 @@ interface SailGuiConfig {
   defaultPolicyLanguage?: string;     // ISO 639-1 fallback language
   accountDeletedRoute?: string;       // Route after account deletion (default '/login/local')
   passwordPolicyUrl?: string;         // Public route serving keel's password policy (see below)
+  oauthServerUrl?: string;            // Base URL of keel's OAuth authorization server (see below)
+  allowedReturnHosts?: string[];      // Hosts a post-login ?return= may name
 }
 ```
 
 ### Password-policy validation
 
+**OAuth sign-in hand-off (v1.1.28, keel v1.2.93).** When the login page is opened with
+`?return=<absolute authorize URL>` and both `oauthServerUrl` and `allowedReturnHosts` are set,
+sail posts `{"return": <raw value>}` with the bearer JWT to
+`{oauthServerUrl}/oauth/session/handoff` and then leaves the SPA with a full navigation to the
+`redirect` keel answers. This runs after a sign-in, and from `loadStoredSession()` when a user
+who is already signed in opens a `/login` route; a 401 rotates the refresh token once and retries. keel sets the authorization server's own HttpOnly cookie while
+redeeming that URL; sail does not opt into cross-origin cookies or send a CSRF token. A
+`return` whose host is not in `allowedReturnHosts`, or a `redirect` outside `oauthServerUrl`'s
+origin, is not followed. Failures set `BaseAuthService.sessionHandoffError` (rendered by
+`<sail-login>`) and never redirect: 400 means keel rejected the return URL, 401 means the user
+signs in again to retry. The authorization server must allow the SPA origin by CORS.
+
 Set `passwordPolicyUrl` to the app's public route for keel's `PublicHandler.GetPasswordPolicy`
 (e.g. `'/public/v1/auth/password/policy'`). `BaseAuthService.ensurePasswordPolicy()` fetches it
 once into the `passwordRules` signal, and `passwordPolicyValidator(() => auth.passwordRules())`
@@ -434,6 +448,11 @@ export class PricingPage {
 | `createPortalSession()` | `POST /api/billing/portal` | `Observable<PortalResponse>` |
 | `listUsage()` | `GET /api/billing/usage` | `Observable<UsageMeter[]>` |
 
+`cancelSubscription()`, `changePlan()` and `createPortalSession()` answer 403 (keel v1.2.89)
+unless the user holds `PARTNER_PLAN_SUBSCRIPTION` `CANCEL` / `CHANGE` / `PORTAL`, seeded for
+`PARTNER_ADMIN`. Test a failure with `isPermissionDenied(err)` and report it as not permitted;
+`<sail-portal-button>` does.
+
 ### Components
 
 **Plan picker** — pure presentational, no API calls:
@@ -774,6 +793,15 @@ currency exponent reported by `Intl.NumberFormat`, so zero- and three-decimal
 currencies render correctly; earnings stay separated by currency rather than
 being summed into a misleading total.
 
+**Delegation roles (v1.1.27, keel v1.2.89).** `AgencyDelegation.roles` (always present) and
+`AgencyClient.roles` carry `AgencyRoleGrant { role, expiresAt? }`; no `expiresAt` is
+open-ended, and a delegation without roles grants no access.
+`AgencyService.setDelegationRoles(roles, clientPartnerId = 0)` replaces the whole set — an
+empty list removes access without revoking the delegation. Role codes and captions come from
+the `agency_delegation_role` constant catalogue (`LabelService.options('agency_delegation_role')`);
+do not hardcode them. keel answers 422 for an unknown, duplicate or blank role, more than 32
+roles, or an expiry not in the future, and 403 without `AGENCY_DELEGATION` / `SET_ROLE`.
+
 The agency URL defaults use `/api/v1/agency/*`. Apps mounting Keel elsewhere
 must override the `RestURL.agency*URL` values with `configureRestUrls()`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nauticana/sail",
-  "version": "1.1.26",
+  "version": "1.1.28",
   "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",
   "exports": {

package/src/component/billing/portal_button.ts

@@ -2,12 +2,14 @@ import { ChangeDetectionStrategy, Component, ViewEncapsulation, inject, input }
 import { MatButtonModule } from '@angular/material/button';
 import { BaseAsync } from '../abstract/base_async';
 import { BillingService } from '../../service/billing.service';
+import { isPermissionDenied } from '../../util/errors';
 
 /**
  * Button that opens a provider customer-portal session and redirects the
  * browser to the returned URL — the partner manages their payment method /
  * subscription on the provider's hosted page. Mirrors CheckoutButtonComponent;
- * uses BaseAsync for loading/error state.
+ * uses BaseAsync for loading/error state. A 403 (no PARTNER_PLAN_SUBSCRIPTION /
+ * PORTAL grant) reads as not permitted rather than as a provider failure.
  */
 @Component({
   selector: 'sail-portal-button',
@@ -26,6 +28,9 @@ export class PortalButtonComponent extends BaseAsync {
       this.billing.createPortalSession(),
       (resp) => { window.location.href = resp.portalUrl; },
       'Could not open the billing portal. Please try again.',
+      (err) => {
+        if (isPermissionDenied(err)) this.errorMessage.set('You are not permitted to manage billing.');
+      },
     );
   }
 }

package/src/component/login/login_component.ts

@@ -29,7 +29,7 @@ export class LoginComponent extends BaseAsync {
   protected fb = inject(FormBuilder);
   protected readonly guiConfig: SailGuiConfig = inject(SAIL_GUI_CONFIG, {optional: true}) ?? DEFAULT_CONFIG;
   protected readonly loggedOut = inject(ActivatedRoute).snapshot.queryParamMap.get('loggedOut') === 'true';
-  /** OAuth session-cookie handoff failure from BaseAuthService, shown below. */
+  /** OAuth session hand-off failure from BaseAuthService, shown below. */
   protected readonly sessionHandoffError = this.auth.sessionHandoffError;
 
   /**
@@ -64,8 +64,8 @@ export class LoginComponent extends BaseAsync {
 
   /**
    * loginSocial already ran completeLogin, which owns post-login navigation
-   * (route init, or the OAuth cookie handoff). Handlers must NOT navigate here —
-   * doing so abandons a pending handoff before its cookie is set. Downstream
+   * (route init, or the OAuth session hand-off). Handlers must NOT navigate here —
+   * doing so abandons a pending hand-off before it redirects. Downstream
    * social-login handlers should follow the same rule.
    */
   protected onSocialSuccess(_: LoginResponseSocial): void {}

package/src/config.ts

@@ -67,11 +67,11 @@ export interface SailGuiConfig {
   accountDeletedRoute?: string;
 
   // ── OAuth authorization-flow bridge (for an OAuth AS on a different host) ──
-  /** Backend path that mirrors the bearer JWT into an HttpOnly session cookie so
-   * a cross-site OAuth `/authorize` can see the session, e.g. '/api/v1/auth/session-cookie'.
-   * When set, login POSTs here before handing off to an allowed ?return= host. */
-  sessionCookieUrl?: string;
-  /** Hostnames a post-login `?return=` may redirect to (open-redirect allowlist),
+  /** Base URL of keel's OAuth authorization server, e.g. 'https://mcp.example.com'.
+   * When set, a login carrying an allowed ?return= POSTs it to
+   * `{oauthServerUrl}/oauth/session/handoff` and navigates to the URL keel answers. */
+  oauthServerUrl?: string;
+  /** Hostnames a post-login `?return=` may name (open-redirect allowlist),
    * e.g. ['mcp.example.com']. Anything not listed is ignored. */
   allowedReturnHosts?: string[];
 

package/src/model/agency.ts

@@ -24,6 +24,7 @@ export interface AgencyClient {
   acceptedAt?: string;
   expired?: boolean;
   billingModel?: string;
+  roles?: AgencyRoleGrant[];
 }
 
 export interface AgencyInvite {
@@ -42,6 +43,13 @@ export interface AgencyDelegation {
   agencyName: string;
   billingModel?: string;
   grantedAt: string;
+  roles: AgencyRoleGrant[];
+}
+
+/** One `agency_delegation_role` code a client grants its agency; no expiresAt is open-ended. */
+export interface AgencyRoleGrant {
+  role: string;
+  expiresAt?: string;
 }
 
 export interface AgencyEarningsBalance {

package/src/service/agency.service.ts

@@ -8,6 +8,7 @@ import {
   AgencyInvite,
   AgencyPayoutProfileOptions,
   AgencyProfile,
+  AgencyRoleGrant,
 } from '../model/agency';
 import { BaseRestService } from './base_rest.service';
 import { RestURL } from './rest_url';
@@ -73,4 +74,10 @@ export class AgencyService extends BaseRestService {
   revokeDelegation(clientPartnerId = 0): Observable<{ status: string }> {
     return this.http.post<{ status: string }>(this.url(RestURL.agencyRevokeDelegationURL), { clientPartnerId });
   }
+
+  /** Replace the whole role set the client grants its agency; an empty list
+   *  removes access without revoking the delegation. */
+  setDelegationRoles(roles: AgencyRoleGrant[], clientPartnerId = 0): Observable<{ status: string }> {
+    return this.http.post<{ status: string }>(this.url(RestURL.agencyDelegationRolesURL), { clientPartnerId, roles });
+  }
 }

package/src/service/auth.service.ts

@@ -25,6 +25,20 @@ export class RefreshSupersededError extends Error {
   constructor() { super('session changed during refresh'); this.name = 'RefreshSupersededError'; }
 }
 
+function handoffErrorMessage(status: number | undefined): string {
+  if (status === 400) return 'This sign-in link is not valid. Start again from the application you were connecting.';
+  if (status === 401) return 'Your session was not accepted. Please sign in again.';
+  return 'Could not complete sign-in. Please try again.';
+}
+
+function sameOrigin(a: string, b: string): boolean {
+  try {
+    return new URL(a, window.location.origin).origin === new URL(b, window.location.origin).origin;
+  } catch {
+    return false;
+  }
+}
+
 /** Sort dropdown options by their visible label so long lookup lists are scannable. */
 const byCaption = (a: ConstantValue, b: ConstantValue) =>
   (a.Caption ?? '').localeCompare(b.Caption ?? '', undefined, { numeric: true, sensitivity: 'base' });
@@ -124,8 +138,8 @@ export abstract class BaseAuthService extends BaseRestService {
   /** Last appdata load failure (null when none). */
   readonly appDataError = signal<unknown>(null);
 
-  /** Set when the OAuth session-cookie handoff fails; the UI shows it and lets the
-   *  user retry instead of being redirected into a cookieless login loop. */
+  /** Set when the OAuth session hand-off fails; the UI shows it and the user
+   *  signs in again to retry instead of being redirected without a session. */
   readonly sessionHandoffError = signal<string | null>(null);
 
   /**
@@ -203,42 +217,73 @@ export abstract class BaseAuthService extends BaseRestService {
     this.sessionGeneration++;
     this.storeTokens(token, refreshToken);
     this.isLoggedIn.set(true);
+    this.sessionHandoffError.set(null);
     resetAuthCircuit(); // a new session must not inherit a prior session's open circuit
-    const ret = this.validatedReturnUrl();
-    if (ret && this.guiConfig.sessionCookieUrl) {
-      // OAuth flow: mirror the bearer into a cookie, then hand off to the
-      // (cross-origin) authorization server via a full navigation. Only hand off
-      // once the cookie is actually set — redirecting after a failed cookie request
-      // sends the user on without a session and loops them back to login.
-      this.sessionHandoffError.set(null);
-      this.http.post(this.url(this.guiConfig.sessionCookieUrl), {}, { withCredentials: true })
-          .pipe(take(1))
-          .subscribe({
-            next: () => window.location.assign(ret),
-            error: (err) => {
-              console.error('Session cookie handoff failed:', err);
-              this.sessionHandoffError.set('Could not complete sign-in. Please try again.');
-            },
-          });
-      return;
-    }
+    if (this.startHandoff()) return;
     this.loadAppData();
     this.initRoutes();
   }
 
-  /** A post-login `?return=` URL, only when its host is in allowedReturnHosts and
-   * the scheme is https (or loopback) — an open-redirect guard. '' otherwise. */
+  /** Hands the session to the OAuth authorization server when the page carries an
+   * allowed `?return=` and oauthServerUrl is set; false when there is nothing to hand off. */
+  private startHandoff(): boolean {
+    const ret = this.validatedReturnUrl();
+    const oauthServer = this.oauthServerBase();
+    if (!ret || !oauthServer) return false;
+    this.handOffSession(oauthServer, ret);
+    return true;
+  }
+
+  /** Exchange the bearer session for the authorization server's own cookie session
+   * (keel POST /oauth/session/handoff), then leave the SPA for the URL it returns.
+   * A 401 rotates the refresh token once and retries. Any failure stays on the
+   * login page; the browser is never sent elsewhere. */
+  private handOffSession(oauthServer: string, ret: string): void {
+    const mint = (token: string) => this.http.post<{ data?: { redirect?: unknown } }>(
+        oauthServer + '/oauth/session/handoff',
+        { return: ret },
+        { headers: { Authorization: `Bearer ${token}` } },
+    );
+    mint(this.token ?? '').pipe(
+      catchError((err: HttpErrorResponse) => err.status === 401 && localStorage.getItem('refreshToken')
+        ? this.refreshSession().pipe(mergeMap(mint))
+        : throwError(() => err)),
+      take(1),
+    ).subscribe({
+      next: (res) => {
+        const redirect = res?.data?.redirect;
+        if (typeof redirect !== 'string' || !sameOrigin(redirect, oauthServer)) {
+          console.error('Session handoff returned an unexpected redirect:', redirect);
+          this.sessionHandoffError.set('Could not complete sign-in. Please try again.');
+          return;
+        }
+        window.location.assign(redirect);
+      },
+      error: (err: unknown) => {
+        console.error('Session handoff failed:', err);
+        this.sessionHandoffError.set(handoffErrorMessage((err as { status?: number } | null)?.status));
+      },
+    });
+  }
+
+  /** guiConfig.oauthServerUrl without trailing slashes; '' when unset. */
+  private oauthServerBase(): string {
+    return (this.guiConfig.oauthServerUrl ?? '').replace(/\/+$/, '');
+  }
+
+  /** The raw post-login `?return=` value, only when its host is in allowedReturnHosts
+   * and the scheme is https (or loopback) — an open-redirect guard. '' otherwise. */
   private validatedReturnUrl(): string {
     const raw = new URLSearchParams(window.location.search).get('return');
     if (!raw) return '';
     try {
-      const u = new URL(raw, window.location.origin);
+      const u = new URL(raw);
       if (u.username || u.password) return '';   // reject userinfo ("user@host") spoofing
       const host = u.hostname.toLowerCase();
       const okScheme = u.protocol === 'https:' || host === 'localhost' || host === '127.0.0.1';
       const allowed = (this.guiConfig.allowedReturnHosts ?? []).some((h) => h.toLowerCase() === host);
       if (okScheme && allowed) {
-        return u.toString();
+        return raw;
       }
     } catch { /* malformed → reject */ }
     return '';
@@ -415,11 +460,12 @@ export abstract class BaseAuthService extends BaseRestService {
 
   loadStoredSession() {
     this.token = localStorage.getItem('jwt');
-    if (this.token) {
-      this.isLoggedIn.set(true);
-      this.loadAppData();
-      this.initRoutes();
-    }
+    if (!this.token) return;
+    this.isLoggedIn.set(true);
+    // A signed-in user sent to the login page by the authorization server is handed off without signing in again.
+    if (window.location.pathname.startsWith('/login') && this.startHandoff()) return;
+    this.loadAppData();
+    this.initRoutes();
   }
 
   /** Revoke the refresh token server-side (best effort: the local session is
@@ -564,6 +610,7 @@ export abstract class BaseAuthService extends BaseRestService {
     this.cache = undefined;
     this.authIndex.clear();
     this.appDataError.set(null);
+    this.sessionHandoffError.set(null);
     this.refreshInFlight = null;
     this.sessionGeneration++;           // in-flight loads and refreshes from this session are ignored
     this.appData$.next(null);           // live subscribers see menus clear; identity stays stable

package/src/service/billing.service.ts

@@ -45,7 +45,7 @@ export class BillingService extends BaseRestService {
     return this.http.get<Subscription>(this.url(RestURL.subscriptionURL));
   }
 
-  /** Cancel auto-renew on the current subscription. */
+  /** Cancel auto-renew on the current subscription. 403 without PARTNER_PLAN_SUBSCRIPTION / CANCEL. */
   cancelSubscription(): Observable<void> {
     return this.http.post<void>(this.url(RestURL.cancelSubURL), {});
   }
@@ -53,7 +53,7 @@ export class BillingService extends BaseRestService {
   /**
    * Upgrade / downgrade the current subscription to `planId` — distinct from
    * first-time checkout. Routes to keel's `SubscriptionLifecycle.ChangePlan`
-   * (atomic close+open) via an endpoint the app exposes.
+   * (atomic close+open). 403 without PARTNER_PLAN_SUBSCRIPTION / CHANGE.
    */
   changePlan(planId: string): Observable<void> {
     return this.http.post<void>(this.url(RestURL.changePlanURL), { planId });
@@ -86,7 +86,7 @@ export class BillingService extends BaseRestService {
   /**
    * Create a provider customer-portal session; caller redirects to the URL so
    * the partner can manage their payment method / subscription on the
-   * provider's hosted page.
+   * provider's hosted page. 403 without PARTNER_PLAN_SUBSCRIPTION / PORTAL.
    */
   createPortalSession(): Observable<PortalResponse> {
     return this.http.post<PortalResponse>(this.url(RestURL.portalURL), {});

package/src/service/rest_url.ts

@@ -77,6 +77,7 @@ export const RestURL = {
   agencyAcceptInviteURL:     '/api/v1/agency/invite/accept',
   agencyDelegationURL:       '/api/v1/agency/delegation',
   agencyRevokeDelegationURL: '/api/v1/agency/delegation/revoke',
+  agencyDelegationRolesURL:  '/api/v1/agency/delegation/roles',
   // User payment methods — list is keel's generic REST CRUD; set_default and
   // remove are keel UserPaymentMethodHandler table actions.
   paymentMethodSetDefaultURL: '/api/v1/user_payment_method/set_default',

package/src/util/errors.ts

@@ -31,6 +31,11 @@ export function isTransportFailure(err: unknown): boolean {
   return statusOf(err) === 0;
 }
 
+/** True for keel's 403: the session is valid but lacks the grant for this action. */
+export function isPermissionDenied(err: unknown): boolean {
+  return statusOf(err) === 403;
+}
+
 /**
  * Human-readable message from any sail error shape — SailApiError (BackendService),
  * raw HttpErrorResponse (direct HttpClient calls), or plain Error.