@nauticana/sail 1.1.30 → 1.1.31

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.30 adopts keel v1.2.99 (password routes; a password change signs out), sail v1.1.29 adopts keel v1.2.94 (signup: confirmation signs in, partner setup, sign-in hand-off code), 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`.
+> **Compatibility:** sail and keel are versioned in lock-step. The current line is **sail v1.1.x ↔ keel v1.2.x**; sail v1.1.31 adopts keel v1.2.100 (tenant single sign-on, DNS and HTTP-file domain verification), sail v1.1.30 adopts keel v1.2.99 (password routes; a password change signs out), sail v1.1.29 adopts keel v1.2.94 (signup: confirmation signs in, partner setup, sign-in hand-off code), 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.
 
@@ -18,7 +18,7 @@ A shared Angular component library for building CRUD-based admin frontends. Prov
 | **Login** | `LoginComponent`, `RegisterComponent`, `ChpassComponent`, `ConfirmRegisterComponent`, `ConfirmChpassComponent` |
 | **Security** | `TwoFactorSetupComponent`, `TwoFactorVerifyComponent`, `TrustedDevicesComponent`, `AccountDeletionComponent` |
 | **Account** | `MyAccountComponent` (self-service hub), `ProfileEditorComponent` (name/locale immediate; email/phone verify-before-apply) |
-| **Auth** | `ConsentGateComponent`, `OtpInputComponent`, `SocialLoginComponent` |
+| **Auth** | `ConsentGateComponent`, `OtpInputComponent`, `SocialLoginComponent`, `SsoLoginComponent`, `SsoReturnComponent` |
 | **Billing** | `PlanSelectorComponent`, `PriceSelectorComponent`, `CheckoutButtonComponent`, `PaymentMethodsComponent`, `PortalButtonComponent`, `UsageMeterComponent`, `StatusChipComponent`, `TrialBannerComponent`, `SeatSelectorComponent`, `DunningBannerComponent` |
 | **Dashboard** | `DashboardShellComponent`, `DataCardComponent`, `StatTileComponent`, `LockedOverlayComponent`, `ActionCenterComponent`, `EntitySelectorComponent`, `VerificationFlowComponent` |
 | **Payout** | `PayoutProviderOnboardingComponent`, `PayoutBankInfoFormComponent` |
@@ -236,6 +236,8 @@ sail follows a **metadata-driven** architecture. On login, the backend returns `
 
 `BaseAuthService.initRoutes()` dynamically builds Angular routes from this metadata. Each menu item automatically gets a `TableSearch` or `TableList` route with the correct API endpoint and table metadata. Custom components can override specific menu items via `menuItemRouteOverrides` in the config.
 
+Application controls can call `BaseAuthService.hasPermission(object, action, value)` for any backend grant. Table actions continue to use `canExecute()`.
+
 ## List pagination
 
 keel REST list responses are paginated:
@@ -310,6 +312,8 @@ interface SailGuiConfig {
   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
+  ssoLogin?: boolean;                 // Shows organization sign-in on <sail-login> (see Tenant single sign-on)
+  ssoErrorMessages?: Partial<Record<SsoErrorCode, string>>; // Rewords single sign-on errors
 }
 ```
 
@@ -601,7 +605,7 @@ A `TableAction` with `kind: 'R'` (redirect — the `constant_value` code) makes
 
 ### Action parameters (v1.1.25)
 
-An action with `parameters` (keel v1.2.75 `table_action_parameter`) opens a dialog before posting: one field per parameter, typed by `dataType` (`boolean` checkbox, numeric, `date`, `timestamp`, `file`, otherwise text), or a dropdown when `lookupTable` names a table in the client cache (a `foreign_key_lookup` dropdown table); a numeric `dataType` still posts the chosen key as a number. The dialog shows `confirmMessage` in place of the native prompt and posts `{...primaryKeyValues(record), ...values}`; empty optional values are left out. A `file` parameter turns the post into `multipart/form-data`, so a table-level `upload` action whose parameters are `file`, `document_type` (lookup `document_type`), `title`, … posts straight to keel's `DocumentHandler.Upload`. An action without parameters behaves as before.
+An action with `parameters` (keel v1.2.75 `table_action_parameter`) opens a dialog before posting: one field per parameter, typed by `dataType` (`boolean` checkbox, numeric, `date`, `timestamp`, `file`, `secret` or `password` as a masked input posted as a string, otherwise text), or a dropdown when `lookupTable` names a table in the client cache (a `foreign_key_lookup` dropdown table); a numeric `dataType` still posts the chosen key as a number. The dialog shows `confirmMessage` in place of the native prompt and posts `{...primaryKeyValues(record), ...values}`; empty optional values are left out. A `file` parameter turns the post into `multipart/form-data`, so a table-level `upload` action whose parameters are `file`, `document_type` (lookup `document_type`), `title`, … posts straight to keel's `DocumentHandler.Upload`. An action without parameters behaves as before.
 
 ### Status chip (v1.0.1)
 
@@ -1006,6 +1010,29 @@ 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.
 
+## Tenant single sign-on (v1.1.31)
+
+Requires keel v1.2.100 with `SSOHandler` mounted. An organization signs its users in through its own OpenID Connect or SAML identity provider; keel owns the protocol and every security decision.
+
+Opt in and add the return route:
+
+```typescript
+{
+  ssoLogin: true,   // <sail-login> shows "Continue with your organization"
+  publicRoutes: [
+    { path: 'login/sso', loadComponent: () => import('@nauticana/sail').then(m => m.SsoReturnComponent) },
+  ],
+}
+```
+
+Pair it with keel's `SSOHandler.PublicBaseURL` (the API origin) and `SSOHandler.FrontendReturnURL` (`https://<app>/login/sso`).
+
+- `<sail-sso-login>` navigates the browser to `RestURL.ssoStartURL` (`/public/sso/start?email=…`) on the API host. It is a top-level navigation, never XHR, because keel binds the sign-in to an HttpOnly cookie there.
+- `<sail-sso-return>` handles keel's answer. A `code` is removed from the address bar and exchanged once through `exchangeHandoff()`; the user lands on the dashboard. An `error` shows its message and links to `/login/local`. A test outcome (`test=passed`, or `test=failed&error=`) is shown with a link to the identity provider screen found in the menu metadata.
+- `SSO_ERROR_MESSAGES` holds the wording of every keel error code; an unknown code reads as `server_error`. Override entries through `SailGuiConfig.ssoErrorMessages`.
+
+Administration uses the generic screens for `partner_identity_provider` and the SCIM tables. The `configure` dialog filters fields by protocol and OIDC client authentication, masks the client secret, uses metadata captions for code lists, and links the SAML service-provider metadata. `test` redirects through keel; generated provisioning tokens appear once in the reveal dialog.
+
 ## Dashboard components
 
 Horizontal building blocks for an entitlement-aware dashboard. All are presentational (signals in, events out) and ship no CSS — the app styles the documented class hooks and supplies the metric data, chart, and action logic.
@@ -1045,11 +1072,11 @@ unless the backend sends
 `source.status` is `null` and a missing source is indistinguishable from an
 empty result.
 
-## Domain verification (v1.1.22)
+## Domain verification (v1.1.22; DNS and HTTP file v1.1.31)
 
-`DomainVerificationComponent` (`sail-domain-verification`) is the send-code → confirm
-flow for proving ownership of a domain: the domain field, the two steps, the resend
-cooldown, the expiry state and the errors. Every app that verifies a domain renders
+`DomainVerificationComponent` (`sail-domain-verification`) proves ownership of a
+domain: the domain field, an email code (`EC`) with its resend cooldown and expiry, a
+DNS TXT record (`DT`) or an HTTP file (`HF`) with copy buttons, and the errors. Every app that verifies a domain renders
 the same thing, so only the endpoints stay downstream.
 
 The endpoints reach it through the `DOMAIN_VERIFIER` port — sail ships no
@@ -1057,11 +1084,15 @@ implementation and knows none of the paths:
 
 ```ts
 export interface DomainVerifier {
-  requestVerification(domain: string): Observable<unknown>;
-  confirm(domain: string, code: string): Observable<unknown>;
+  requestVerification(domain: string): Observable<unknown>;            // EC: send the code
+  challenge?(domain: string, method: 'DT' | 'HF'): Observable<DomainChallenge>;
+  confirm(domain: string, code: string, method?: DomainVerificationMethod): Observable<unknown>;
 }
 ```
 
+`challenge` posts keel's `partner_domain` `challenge` action (`{domainUrl, method}`) and
+emits its `challenge`; `confirm` then posts `{domainUrl, method}` with an empty code.
+
 ```ts
 // app config — any service with those two methods satisfies the port
 providers: [{ provide: DOMAIN_VERIFIER, useExisting: RegistrationService }]
@@ -1082,12 +1113,14 @@ providers: [{ provide: DOMAIN_VERIFIER, useExisting: RegistrationService }]
 | `[label]` | Field label, default `Domain`. |
 | `[resendAfterSeconds]` | Resend cooldown, default `60`. |
 | `[codeExpiresInSeconds]` | Code lifetime; `0` (default) shows no expiry. Pass the backend's TTL when it publishes one. |
+| `[methods]` | Methods offered, default `['EC']`; the first is preselected. `DT` and `HF` appear only when the verifier implements `challenge`. Captions come from keel's `domain_verification_method` catalog. |
 | `(domainChange)` | Every edit, so the host form stays in sync. |
 | `(verified)` | Fires once with the proven domain. |
 
 Editing the domain returns the flow to `idle`: a code is bound to the domain it was
 issued for. The component is unstyled — style `.domain-verification`,
-`.domain-verification-field`, `.domain-verification-verified` and the
+`.domain-verification-field`, `.domain-verification-verified`,
+`.domain-verification-method`, `.domain-verification-value` and the
 `.verification-*` hooks of the step UI it composes.
 
 ## Notification inbox (v1.1.23)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nauticana/sail",
-  "version": "1.1.30",
+  "version": "1.1.31",
   "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/abstract/base_table.ts

@@ -1,4 +1,4 @@
-import { computed, inject, Injector, WritableSignal } from "@angular/core";
+import { computed, inject, Injector, Type, WritableSignal } from "@angular/core";
 import { ForeignKey, TableAction, TableColumn, TableDefinition } from "../../model/appdata";
 import { ConstantValue, LookupStyle, OpCode } from "../../model/common";
 import { BaseAuthService } from "../../service/auth.service";
@@ -9,6 +9,7 @@ import { errorDetail } from "../../util/errors";
 import { MatDialog } from "@angular/material/dialog";
 import { RevealDialog } from "../table/reveal_dialog";
 import { ActionParamsDialog } from "../table/action_params_dialog";
+import { IdentityProviderConfigureDialog } from "../sso/identity_provider_configure_dialog";
 
 
 /** CRUD verb used by `requireAuth()` to compose the "Missing authorization" alert. */
@@ -17,6 +18,11 @@ export type AuthVerb = 'create' | 'read' | 'update' | 'delete' | 'view';
 /** ISO-like timestamp prefix — gate for comparing two strings as instants. */
 const ISO_PREFIX = /^\d{4}-\d{2}-\d{2}T/;
 
+/** Parameter dialogs for keel actions the generic dialog cannot lay out, keyed `table/action`. */
+const ACTION_DIALOGS: Record<string, Type<ActionParamsDialog>> = {
+    'partner_identity_provider/configure': IdentityProviderConfigureDialog,
+};
+
 
 export abstract class BaseTable {
     protected readonly cacheService = inject(BaseAuthService);
@@ -146,7 +152,9 @@ export abstract class BaseTable {
         const key = action.recordSpecific && record ? this.primaryKeyValues(record) : {};
         if (action.parameters?.length) {
             this.#injector.get(MatDialog)
-                .open<ActionParamsDialog, TableAction, Record<string, unknown>>(ActionParamsDialog, { data: action, width: this.dialogWidth })
+                .open<ActionParamsDialog, TableAction, Record<string, unknown>>(
+                    ACTION_DIALOGS[this.tableName() + '/' + action.action] ?? ActionParamsDialog,
+                    { data: action, width: this.dialogWidth })
                 .afterClosed()
                 .subscribe((values) => {
                     if (values) this.postAction(action, {...key, ...values}, record);

package/src/component/login/login_component.html

@@ -38,6 +38,10 @@
         (loginSuccess)="onSocialSuccess($event)"
         (loginError)="onSocialError($event)" />
     }
+    @if (guiConfig.ssoLogin) {
+      <hr class="auth-divider">
+      <sail-sso-login />
+    }
     <div class="auth-actions">
       <a routerLink="/login/chpass">I forgot my password</a>
     </div>

package/src/component/login/login_component.ts

@@ -9,6 +9,7 @@ import { MatInputModule } from '@angular/material/input';
 import { SAIL_GUI_CONFIG, SailGuiConfig, DEFAULT_CONFIG } from '../../config';
 import { LoginResponseSocial, SocialProvider } from '../../model/auth';
 import { SocialLoginComponent } from './social_login';
+import { SsoLoginComponent } from '../sso/sso_login';
 
 @Component({
   selector: 'sail-login',
@@ -22,6 +23,7 @@ import { SocialLoginComponent } from './social_login';
     MatInputModule,
     RouterLink,
     SocialLoginComponent,
+    SsoLoginComponent,
   ],
 })
 export class LoginComponent extends BaseAsync {

package/src/component/sso/identity_provider_configure_dialog.ts

@@ -0,0 +1,68 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { ReactiveFormsModule } from '@angular/forms';
+import { MatButtonModule } from '@angular/material/button';
+import { MatCheckboxModule } from '@angular/material/checkbox';
+import { MatDialogModule } from '@angular/material/dialog';
+import { MatFormFieldModule } from '@angular/material/form-field';
+import { MatInputModule } from '@angular/material/input';
+import { MatSelectModule } from '@angular/material/select';
+import { TableActionParameter } from '../../model/appdata';
+import { ConstantValue } from '../../model/common';
+import { RestURL } from '../../service/rest_url';
+import { ActionParamsDialog } from '../table/action_params_dialog';
+
+/** identity_protocol code for SAML 2.0; anything else configures OpenID Connect. */
+const SAML = 'S';
+/** oidc_client_auth code for private key JWT; the other codes take a client secret. */
+const PRIVATE_KEY_JWT = 'J';
+const SAML_ONLY = new Set(['idp_metadata']);
+const OIDC_ONLY = new Set(['issuer', 'client_id', 'client_auth', 'client_secret', 'private_key', 'operator_client', 'scopes']);
+const DOMAINS: Record<string, string> = { protocol: 'identity_protocol', client_auth: 'oidc_client_auth' };
+const CLIENT_FIELDS = new Set(['client_id', 'client_auth', 'client_secret', 'private_key']);
+
+/**
+ * keel's partner_identity_provider `configure` action: shows only the fields of the
+ * chosen protocol, and links keel's SAML service provider metadata.
+ */
+@Component({
+  selector: 'sail-identity-provider-configure-dialog',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [
+    ReactiveFormsModule,
+    MatDialogModule,
+    MatButtonModule,
+    MatCheckboxModule,
+    MatFormFieldModule,
+    MatInputModule,
+    MatSelectModule,
+  ],
+  templateUrl: '../table/action_params_dialog.html',
+})
+export class IdentityProviderConfigureDialog extends ActionParamsDialog {
+  protected override arrange(params: TableActionParameter[]): TableActionParameter[] {
+    return params
+      .map((param) => param.name === 'client_secret' ? { ...param, dataType: 'secret' } : param)
+      .sort((a, b) => Number(b.name === 'protocol') - Number(a.name === 'protocol'));
+  }
+
+  protected override optionsFor(param: TableActionParameter): ConstantValue[] | undefined {
+    const domain = DOMAINS[param.name];
+    return domain ? this.auth.getDomainValues(domain) : super.optionsFor(param);
+  }
+
+  protected override shown(name: string): boolean {
+    if (this.form.controls['protocol']?.value === SAML) return !OIDC_ONLY.has(name);
+    if (SAML_ONLY.has(name)) return false;
+    if (CLIENT_FIELDS.has(name) && String(this.form.controls['operator_client']?.value ?? '').trim()) return false;
+    const clientAuth = this.form.controls['client_auth']?.value;
+    if (name === 'client_secret') return clientAuth !== PRIVATE_KEY_JWT;
+    if (name === 'private_key') return clientAuth === PRIVATE_KEY_JWT;
+    return true;
+  }
+
+  protected override hint(name: string): { href: string; label: string } | null {
+    return name === 'idp_metadata'
+      ? { href: RestURL.httpHost + RestURL.ssoSamlMetadataURL, label: 'Service provider metadata for your identity provider' }
+      : null;
+  }
+}

package/src/component/sso/sso_login.html

@@ -0,0 +1,8 @@
+<div class="sso-login">
+  <mat-form-field appearance="outline">
+    <mat-label>Work email</mat-label>
+    <input matInput type="email" [formControl]="email" autocomplete="email" (keydown.enter)="continue()">
+    <mat-error>Enter your work email address</mat-error>
+  </mat-form-field>
+  <button matButton="elevated" type="button" (click)="continue()">Continue with your organization</button>
+</div>

package/src/component/sso/sso_login.ts

@@ -0,0 +1,32 @@
+import { ChangeDetectionStrategy, Component, ViewEncapsulation } from '@angular/core';
+import { FormControl, ReactiveFormsModule, Validators } from '@angular/forms';
+import { MatButtonModule } from '@angular/material/button';
+import { MatFormFieldModule } from '@angular/material/form-field';
+import { MatInputModule } from '@angular/material/input';
+import { ssoStartUrl } from '../../util/sso';
+
+/**
+ * Organization sign-in: sends the browser to keel's `/public/sso/start` for the
+ * entered address. A top-level navigation, because keel binds the sign-in to an
+ * HttpOnly cookie on the API host.
+ *
+ * Selector: <sail-sso-login>
+ */
+@Component({
+  selector: 'sail-sso-login',
+  templateUrl: './sso_login.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  imports: [ReactiveFormsModule, MatButtonModule, MatFormFieldModule, MatInputModule],
+})
+export class SsoLoginComponent {
+  readonly email = new FormControl('', { nonNullable: true, validators: [Validators.required, Validators.email] });
+
+  continue(): void {
+    if (this.email.invalid) {
+      this.email.markAsTouched();
+      return;
+    }
+    window.location.assign(ssoStartUrl(this.email.value));
+  }
+}

package/src/component/sso/sso_return.html

@@ -0,0 +1,25 @@
+<div class="auth-container">
+  <div class="auth-card sso-return" [attr.data-state]="state()">
+    @switch (state()) {
+      @case ('signing-in') {
+        <p class="auth-message" role="status" aria-live="polite">Signing you in…</p>
+      }
+      @case ('test-passed') {
+        <p class="auth-message" role="status">Test sign-in succeeded. The connection can now be activated.</p>
+      }
+      @default {
+        <p class="auth-error" role="alert">{{ message() }}</p>
+      }
+    }
+    <div class="auth-actions">
+      @if (state() === 'error') {
+        <a routerLink="/login/local">Use another sign-in method</a>
+      }
+      @if (state() === 'test-passed' || state() === 'test-failed') {
+        @if (adminRoute(); as route) {
+          <a [routerLink]="route">Back to identity providers</a>
+        }
+      }
+    </div>
+  </div>
+</div>

package/src/component/sso/sso_return.ts

@@ -0,0 +1,82 @@
+import { ChangeDetectionStrategy, Component, DestroyRef, ViewEncapsulation, inject, signal } from '@angular/core';
+import { takeUntilDestroyed, toSignal } from '@angular/core/rxjs-interop';
+import { Location } from '@angular/common';
+import { ActivatedRoute, Router, RouterLink } from '@angular/router';
+import { catchError, map, of } from 'rxjs';
+import { DEFAULT_CONFIG, SAIL_GUI_CONFIG, SailGuiConfig } from '../../config';
+import { ApplicationData } from '../../model/appdata';
+import { BaseAuthService } from '../../service/auth.service';
+import { ssoErrorMessage } from '../../util/sso';
+
+type SsoReturnState = 'signing-in' | 'error' | 'test-passed' | 'test-failed';
+
+/**
+ * keel's single sign-on return URL (`SSOHandler.FrontendReturnURL`), routed by the
+ * app at `login/sso`. A `code` is exchanged once and removed from the address bar;
+ * `error` and `test` stay so the outcome survives the post-login route rebuild.
+ *
+ * Selector: <sail-sso-return>
+ */
+@Component({
+  selector: 'sail-sso-return',
+  templateUrl: './sso_return.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  imports: [RouterLink],
+})
+export class SsoReturnComponent {
+  private readonly auth = inject(BaseAuthService);
+  private readonly guiConfig: SailGuiConfig = inject(SAIL_GUI_CONFIG, { optional: true }) ?? DEFAULT_CONFIG;
+  private readonly destroyRef = inject(DestroyRef);
+
+  protected readonly state = signal<SsoReturnState>('signing-in');
+  protected readonly message = signal('');
+  /** The identity provider screen from the menu metadata, once the app data is loaded. */
+  protected readonly adminRoute = toSignal(
+    this.auth.getAppData().pipe(map(identityProviderRoute), catchError(() => of(null))),
+    { initialValue: null },
+  );
+
+  constructor() {
+    const params = inject(ActivatedRoute).snapshot.queryParamMap;
+    const location = inject(Location);
+    const code = params.get('code');
+    const test = params.get('test');
+    if (code) {
+      location.replaceState(location.path().split('?')[0]);
+      this.exchange(code);
+    } else if (test === 'passed' || test === 'failed') {
+      this.state.set(test === 'passed' ? 'test-passed' : 'test-failed');
+      if (test === 'failed') this.message.set(this.messageFor(params.get('error')));
+      this.auth.setLanding(location.path());
+      this.destroyRef.onDestroy(() => this.auth.setLanding(null));
+    } else if (params.has('error')) {
+      this.fail(params.get('error'));
+    } else {
+      inject(Router).navigate(['/login/local'], { replaceUrl: true });
+    }
+  }
+
+  private exchange(code: string): void {
+    this.auth.exchangeHandoff(code).pipe(takeUntilDestroyed(this.destroyRef)).subscribe({
+      error: () => this.fail('sso_failed'),
+    });
+  }
+
+  private fail(code: string | null): void {
+    this.state.set('error');
+    this.message.set(this.messageFor(code));
+  }
+
+  private messageFor(code: string | null): string {
+    return ssoErrorMessage(code, this.guiConfig.ssoErrorMessages);
+  }
+}
+
+function identityProviderRoute(data: ApplicationData): string | null {
+  for (const menu of data.MainMenu ?? []) {
+    const item = menu.ApplicationMenuItems?.find((i) => i.RestUri === 'partner_identity_provider');
+    if (menu.Id && item?.ItemId) return `/${menu.Id.toLowerCase()}/${item.ItemId}`;
+  }
+  return null;
+}

package/src/component/table/action_params_dialog.html

@@ -5,40 +5,46 @@
             <p>{{ action.confirmMessage }}</p>
         }
         @for (f of fields; track f.param.name) {
-            @switch (f.kind) {
-                @case ('checkbox') {
-                    <mat-checkbox [formControlName]="f.param.name">{{ f.param.caption }}</mat-checkbox>
-                }
-                @case ('file') {
-                    <div class="action-param-file">
-                        <label [for]="'action-param-' + f.param.name">{{ f.param.caption }}@if (f.param.required) { * }</label>
-                        <input type="file" [id]="'action-param-' + f.param.name" [required]="f.param.required"
-                               (change)="pickFile(f.param.name, $event)">
-                        @if (form.controls[f.param.name].touched && form.controls[f.param.name].invalid) {
-                            <p class="action-param-error" role="alert">{{ f.param.caption }} is required</p>
-                        }
-                    </div>
-                }
-                @case ('select') {
-                    <mat-form-field appearance="outline">
-                        <mat-label>{{ f.param.caption }}</mat-label>
-                        <mat-select [formControlName]="f.param.name" [required]="f.param.required">
-                            @if (!f.param.required) {
-                                <mat-option [value]="''">None</mat-option>
-                            }
-                            @for (opt of f.options; track opt.Value) {
-                                <mat-option [value]="opt.Value">{{ opt.Caption }}</mat-option>
+            @if (shown(f.param.name)) {
+                @switch (f.kind) {
+                    @case ('checkbox') {
+                        <mat-checkbox [formControlName]="f.param.name">{{ f.param.caption }}</mat-checkbox>
+                    }
+                    @case ('file') {
+                        <div class="action-param-file">
+                            <label [for]="'action-param-' + f.param.name">{{ f.param.caption }}@if (f.param.required) { * }</label>
+                            <input type="file" [id]="'action-param-' + f.param.name" [required]="f.param.required"
+                                   (change)="pickFile(f.param.name, $event)">
+                            @if (form.controls[f.param.name].touched && form.controls[f.param.name].invalid) {
+                                <p class="action-param-error" role="alert">{{ f.param.caption }} is required</p>
                             }
-                        </mat-select>
-                        <mat-error>{{ f.param.caption }} is required</mat-error>
-                    </mat-form-field>
+                        </div>
+                    }
+                    @case ('select') {
+                        <mat-form-field appearance="outline">
+                            <mat-label>{{ f.param.caption }}</mat-label>
+                            <mat-select [formControlName]="f.param.name" [required]="f.param.required">
+                                @if (!f.param.required) {
+                                    <mat-option [value]="''">None</mat-option>
+                                }
+                                @for (opt of f.options; track opt.Value) {
+                                    <mat-option [value]="opt.Value">{{ opt.Caption }}</mat-option>
+                                }
+                            </mat-select>
+                            <mat-error>{{ f.param.caption }} is required</mat-error>
+                        </mat-form-field>
+                    }
+                    @default {
+                        <mat-form-field appearance="outline">
+                            <mat-label>{{ f.param.caption }}</mat-label>
+                            <input matInput [type]="f.kind" [formControlName]="f.param.name" [required]="f.param.required"
+                                   [attr.autocomplete]="f.kind === 'password' ? 'new-password' : null">
+                            <mat-error>{{ f.param.caption }} is required</mat-error>
+                        </mat-form-field>
+                    }
                 }
-                @default {
-                    <mat-form-field appearance="outline">
-                        <mat-label>{{ f.param.caption }}</mat-label>
-                        <input matInput [type]="f.kind" [formControlName]="f.param.name" [required]="f.param.required">
-                        <mat-error>{{ f.param.caption }} is required</mat-error>
-                    </mat-form-field>
+                @if (hint(f.param.name); as link) {
+                    <p class="action-param-hint"><a [href]="link.href" target="_blank" rel="noopener">{{ link.label }}</a></p>
                 }
             }
         }

package/src/component/table/action_params_dialog.ts

@@ -10,7 +10,7 @@ import { TableAction, TableActionParameter } from "../../model/appdata";
 import { ConstantValue } from "../../model/common";
 import { BaseAuthService } from "../../service/auth.service";
 
-type ParamKind = 'checkbox' | 'number' | 'date' | 'datetime-local' | 'file' | 'text';
+type ParamKind = 'checkbox' | 'number' | 'date' | 'datetime-local' | 'file' | 'password' | 'text';
 
 interface ParamField {
     param:    TableActionParameter;
@@ -20,7 +20,11 @@ interface ParamField {
     options?: ConstantValue[];
 }
 
-/** Collects a table action's declared parameters; closes with the typed values, or undefined on cancel. */
+/**
+ * Collects a table action's declared parameters; closes with the typed values, or
+ * undefined on cancel. A subclass for one action overrides arrange, optionsFor,
+ * shown and hint.
+ */
 @Component({
     selector: "sail-action-params-dialog",
     changeDetection: ChangeDetectionStrategy.OnPush,
@@ -36,12 +40,12 @@ interface ParamField {
     templateUrl: "./action_params_dialog.html",
 })
 export class ActionParamsDialog {
-    private readonly auth = inject(BaseAuthService);
+    protected readonly auth = inject(BaseAuthService);
     private readonly dialogRef = inject(MatDialogRef<ActionParamsDialog, Record<string, unknown>>);
     readonly action = inject<TableAction>(MAT_DIALOG_DATA);
 
-    readonly fields: ParamField[] = (this.action.parameters ?? []).map((param) => {
-        const options = param.lookupTable ? this.auth.getTableValues(param.lookupTable) : undefined;
+    readonly fields: ParamField[] = this.arrange(this.action.parameters ?? []).map((param) => {
+        const options = this.optionsFor(param);
         const wireKind = kindOf(param.dataType);
         return { param, kind: options ? 'select' : wireKind, wireKind, options };
     });
@@ -53,12 +57,13 @@ export class ActionParamsDialog {
     })));
 
     submit(): void {
-        if (this.form.invalid) {
+        const shown = this.fields.filter((f) => this.shown(f.param.name));
+        if (shown.some((f) => this.form.controls[f.param.name].invalid)) {
             this.form.markAllAsTouched();
             return;
         }
         const values: Record<string, unknown> = {};
-        for (const f of this.fields) {
+        for (const f of shown) {
             const raw = this.form.controls[f.param.name].value;
             if (raw === '' || raw == null) continue;
             values[f.param.name] = toWire(f.wireKind, raw);
@@ -66,6 +71,26 @@ export class ActionParamsDialog {
         this.dialogRef.close(values);
     }
 
+    /** The parameters in display order. */
+    protected arrange(params: TableActionParameter[]): TableActionParameter[] {
+        return params;
+    }
+
+    /** Choices for a parameter; undefined renders a typed input. */
+    protected optionsFor(param: TableActionParameter): ConstantValue[] | undefined {
+        return param.lookupTable ? this.auth.getTableValues(param.lookupTable) : undefined;
+    }
+
+    /** Whether a parameter applies to the values entered so far; a hidden one is not posted. */
+    protected shown(_name: string): boolean {
+        return true;
+    }
+
+    /** A link shown under a parameter. */
+    protected hint(_name: string): { href: string; label: string } | null {
+        return null;
+    }
+
     pickFile(name: string, event: Event): void {
         const control = this.form.controls[name];
         control.setValue((event.target as HTMLInputElement).files?.[0] ?? '');
@@ -91,6 +116,9 @@ function kindOf(dataType: string): ParamKind {
             return 'datetime-local';
         case 'file':
             return 'file';
+        case 'secret':
+        case 'password':
+            return 'password';
         default:
             return 'text';
     }

package/src/component/verification/domain_verification.html

@@ -1,4 +1,4 @@
-<div class="domain-verification" [attr.data-step]="step()">
+<div class="domain-verification" [attr.data-step]="step()" [attr.data-method]="method()">
   <div class="domain-verification-field">
     <mat-form-field appearance="outline">
       <mat-label>{{ label() }}</mat-label>
@@ -11,13 +11,82 @@
     }
   </div>
 
-  <sail-verification-flow
-    [step]="step()"
-    [target]="domain()"
-    [errorMessage]="errorMessage()"
-    [disabled]="loading() || !domain().trim()"
-    [resendAfterSeconds]="resendAfterSeconds()"
-    [codeExpiresInSeconds]="codeExpiresInSeconds()"
-    (requestVerification)="request()"
-    (confirmCode)="confirm($event)" />
+  @if (methods().length > 1 && !isVerified()) {
+    <mat-form-field appearance="outline" class="domain-verification-method">
+      <mat-label>Verification method</mat-label>
+      <mat-select [value]="method()" (selectionChange)="selectMethod($event.value)" [disabled]="loading()">
+        @for (opt of methodOptions(); track opt.value) {
+          <mat-option [value]="opt.value">{{ opt.caption }}</mat-option>
+        }
+      </mat-select>
+    </mat-form-field>
+  }
+
+  @if (method() === 'EC') {
+    <sail-verification-flow
+      [step]="step()"
+      [target]="domain()"
+      [errorMessage]="errorMessage()"
+      [disabled]="loading() || !domain().trim()"
+      [resendAfterSeconds]="resendAfterSeconds()"
+      [codeExpiresInSeconds]="codeExpiresInSeconds()"
+      (requestVerification)="request()"
+      (confirmCode)="confirm($event)" />
+  } @else {
+    <div class="verification-flow domain-verification-challenge" [attr.data-step]="step()">
+      @switch (step()) {
+        @case ('verified') {
+          <p class="verification-success" role="status">Verified.</p>
+        }
+        @case ('idle') {
+          @if (errorMessage()) { <p class="verification-error" role="alert">{{ errorMessage() }}</p> }
+          <button matButton="elevated" type="button" class="primary"
+                  [disabled]="loading() || !domain().trim()" (click)="issueChallenge()">
+            Start verification
+          </button>
+        }
+        @default {
+          @if (challenge(); as ch) {
+            @if (ch.recordName) {
+              <p class="verification-intro">Add this TXT record to the DNS of {{ ch.domainName }}, then confirm.</p>
+              <div class="domain-verification-value">
+                <span>Name</span><code>{{ ch.recordName }}</code>
+                <button matIconButton type="button" (click)="copy(ch.recordName)" aria-label="Copy record name">
+                  <mat-icon>content_copy</mat-icon>
+                </button>
+              </div>
+              <div class="domain-verification-value">
+                <span>Value</span><code>{{ ch.recordValue }}</code>
+                <button matIconButton type="button" (click)="copy(ch.recordValue ?? '')" aria-label="Copy record value">
+                  <mat-icon>content_copy</mat-icon>
+                </button>
+              </div>
+            }
+            @if (ch.fileUrl) {
+              <p class="verification-intro">Serve a file with exactly this content at this address, then confirm.</p>
+              <div class="domain-verification-value">
+                <span>Address</span><code>{{ ch.fileUrl }}</code>
+                <button matIconButton type="button" (click)="copy(ch.fileUrl)" aria-label="Copy file address">
+                  <mat-icon>content_copy</mat-icon>
+                </button>
+              </div>
+              <div class="domain-verification-value">
+                <span>Content</span><code>{{ ch.fileBody }}</code>
+                <button matIconButton type="button" (click)="copy(ch.fileBody ?? '')" aria-label="Copy file content">
+                  <mat-icon>content_copy</mat-icon>
+                </button>
+              </div>
+            }
+          }
+          @if (errorMessage()) { <p class="verification-error" role="alert">{{ errorMessage() }}</p> }
+          <div class="verification-actions">
+            <button matButton="elevated" type="button" class="primary"
+                    [disabled]="loading()" (click)="confirm('')">
+              @if (step() === 'verifying') { Verifying… } @else { Confirm }
+            </button>
+          </div>
+        }
+      }
+    </div>
+  }
 </div>

package/src/component/verification/domain_verification.ts

@@ -1,19 +1,24 @@
 import {
   ChangeDetectionStrategy, Component, ViewEncapsulation,
-  computed, effect, inject, input, output, signal, untracked,
+  computed, effect, inject, input, linkedSignal, output, signal, untracked,
 } from '@angular/core';
+import { Clipboard } from '@angular/cdk/clipboard';
+import { MatButtonModule } from '@angular/material/button';
 import { MatFormFieldModule } from '@angular/material/form-field';
 import { MatIconModule } from '@angular/material/icon';
 import { MatInputModule } from '@angular/material/input';
+import { MatSelectModule } from '@angular/material/select';
 import { VerificationStep } from '../../model/dashboard';
-import { DOMAIN_VERIFIER } from '../../service/domain_verifier';
+import { BaseAuthService } from '../../service/auth.service';
+import { DOMAIN_VERIFIER, DomainChallenge, DomainVerificationMethod } from '../../service/domain_verifier';
 import { BaseAsync } from '../abstract/base_async';
 import { VerificationFlowComponent } from '../dashboard/verification_flow';
 
 /**
- * Domain-ownership verification: the domain field plus the send-code → confirm steps,
- * driven against the injected `DOMAIN_VERIFIER`. The app owns the endpoints, the page
- * shell and the styling; `verified` fires once with the domain that was proven.
+ * Domain-ownership verification: the domain field plus the steps of the chosen method
+ * (email code, DNS TXT record or HTTP file), driven against the injected
+ * `DOMAIN_VERIFIER`. The app owns the endpoints, the page shell and the styling;
+ * `verified` fires once with the domain that was proven.
  *
  * Selector: <sail-domain-verification>
  */
@@ -22,15 +27,19 @@ import { VerificationFlowComponent } from '../dashboard/verification_flow';
   templateUrl: './domain_verification.html',
   changeDetection: ChangeDetectionStrategy.OnPush,
   encapsulation: ViewEncapsulation.None,
-  imports: [MatFormFieldModule, MatIconModule, MatInputModule, VerificationFlowComponent],
+  imports: [MatButtonModule, MatFormFieldModule, MatIconModule, MatInputModule, MatSelectModule, VerificationFlowComponent],
 })
 export class DomainVerificationComponent extends BaseAsync {
   private readonly verifier = inject(DOMAIN_VERIFIER);
+  private readonly auth = inject(BaseAuthService, { optional: true });
+  private readonly clipboard = inject(Clipboard);
 
   readonly domainInput = input('', { alias: 'domain' });
   readonly label = input('Domain');
   readonly resendAfterSeconds = input(60);
   readonly codeExpiresInSeconds = input(0);
+  /** Methods offered, first is the default; DT and HF need `DomainVerifier.challenge`. */
+  readonly methodsInput = input<DomainVerificationMethod[]>(['EC'], { alias: 'methods' });
 
   readonly domainChange = output<string>();
   readonly verified = output<string>();
@@ -38,6 +47,14 @@ export class DomainVerificationComponent extends BaseAsync {
   readonly domain = signal('');
   readonly step = signal<VerificationStep>('idle');
   readonly isVerified = computed(() => this.step() === 'verified');
+  readonly methods = computed(() => this.methodsInput().filter((m) => m === 'EC' || !!this.verifier.challenge));
+  readonly method = linkedSignal<DomainVerificationMethod>(() => this.methods()[0] ?? 'EC');
+  readonly challenge = signal<DomainChallenge | null>(null);
+  /** Captions from keel's domain_verification_method catalog; the code when it is not loaded. */
+  protected readonly methodOptions = computed(() => {
+    const captions = this.auth?.getDomainValues('domain_verification_method') ?? [];
+    return this.methods().map((value) => ({ value, caption: captions.find((c) => c.Value === value)?.Caption ?? value }));
+  });
 
   constructor() {
     super();
@@ -45,18 +62,45 @@ export class DomainVerificationComponent extends BaseAsync {
       const value = this.domainInput();
       if (value === untracked(this.domain)) return;
       this.domain.set(value);
-      this.step.set('idle');
-      this.clearMessages();
+      this.reset();
     });
   }
 
   protected onDomainInput(value: string): void {
     this.domain.set(value);
-    this.step.set('idle');   // a code is bound to the domain it was issued for
-    this.clearMessages();
+    this.reset();   // a code or challenge is bound to the domain it was issued for
     this.domainChange.emit(value);
   }
 
+  protected selectMethod(method: DomainVerificationMethod): void {
+    this.method.set(method);
+    this.reset();
+  }
+
+  protected issueChallenge(): void {
+    const domain = this.domain().trim();
+    const method = this.method();
+    if (!domain || method === 'EC' || !this.verifier.challenge || this.isVerified() || this.loading()) return;
+    this.run(
+      this.verifier.challenge(domain, method),
+      (challenge) => {
+        this.challenge.set(challenge);
+        this.step.set('requested');
+      },
+      'Could not start the verification.',
+    );
+  }
+
+  protected copy(value: string): void {
+    this.clipboard.copy(value);
+  }
+
+  private reset(): void {
+    this.step.set('idle');
+    this.challenge.set(null);
+    this.clearMessages();
+  }
+
   protected request(): void {
     const domain = this.domain().trim();
     if (!domain || this.isVerified() || this.loading()) return;
@@ -68,12 +112,13 @@ export class DomainVerificationComponent extends BaseAsync {
     );
   }
 
+  /** Confirms the email code, or the published challenge when `code` is empty. */
   protected confirm(code: string): void {
     const domain = this.domain().trim();
     if (!domain || this.isVerified() || this.loading()) return;
     this.step.set('verifying');
     this.run(
-      this.verifier.confirm(domain, code),
+      this.verifier.confirm(domain, code, this.method()),
       () => {
         this.step.set('verified');
         this.verified.emit(domain);

package/src/config.ts

@@ -1,6 +1,7 @@
 import { InjectionToken, Type } from '@angular/core';
 import { Routes } from '@angular/router';
 import { ApplicationData } from './model/appdata';
+import { SsoErrorCode } from './util/sso';
 
 export interface RouteLink {
   label: string;
@@ -75,6 +76,11 @@ export interface SailGuiConfig {
    * e.g. ['mcp.example.com']. Anything not listed is ignored. */
   allowedReturnHosts?: string[];
 
+  /** Shows `<sail-sso-login>` (organization sign-in) on `<sail-login>`. Off by default. */
+  ssoLogin?: boolean;
+  /** Replaces the default wording of single sign-on error codes. */
+  ssoErrorMessages?: Partial<Record<SsoErrorCode, string>>;
+
   /** Public route serving the password policy (keel PublicHandler.GetPasswordPolicy),
    * e.g. '/public/v1/auth/password/policy'. When set, sail fetches it once and
    * password inputs validate against it. Omitted → policy validation is skipped. */

package/src/index.ts

@@ -45,6 +45,8 @@ export * from './component/login/sms_consent';
 export * from './component/login/otp_input';
 export * from './component/login/social_login';
 export * from './component/login/account_deletion';
+export * from './component/sso/sso_login';
+export * from './component/sso/sso_return';
 export * from './component/account/profile_editor';
 export * from './component/account/my_account';
 export * from './component/security/twofactor_setup';
@@ -96,3 +98,4 @@ export * from './util/text';
 export * from './util/money';
 export * from './util/errors';
 export * from './util/password_policy';
+export * from './util/sso';

package/src/service/auth.service.ts

@@ -80,6 +80,7 @@ export abstract class BaseAuthService extends BaseRestService {
   /** The route config active before the first initRoutes() — restored on logout
    *  so the login screen doesn't keep the previous user's route tree. */
   private preLoginRoutes: Routes | null = null;
+  private landing: string | null = null;
 
   // Lazy getters, not field initializers: fields would snapshot during super(),
   // before a subclass constructor can call configureRestUrls().
@@ -640,6 +641,7 @@ export abstract class BaseAuthService extends BaseRestService {
     this.appDataError.set(null);
     this.sessionHandoffError.set(null);
     this.refreshInFlight = null;
+    this.landing = 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
     this.appDataFail$.complete();
@@ -770,14 +772,14 @@ export abstract class BaseAuthService extends BaseRestService {
   canCreate(tableName: string) { return this.checkPermission('TABLE', 'INSERT', tableName); }
   canUpdate(tableName: string) { return this.checkPermission('TABLE', 'UPDATE', tableName); }
   canDelete(tableName: string) { return this.checkPermission('TABLE', 'DELETE', tableName); }
-  /**
-   * Authorization check for a custom TableAction. authorityObject is the
-   * uppercased table_name; activity is the uppercased action_name. The
-   * grant's low_limit is checked against the table_name (lowercase) —
-   * matching the convention populated by keel's loadTableActions.
-   */
-  canExecute(authorityObject: string, activity: string, tableName: string): boolean {
-    return this.checkPermission(authorityObject, activity, tableName);
+  /** Whether a grant's low_limit pattern matches value. */
+  hasPermission(authorityObject: string, activity: string, value: string): boolean {
+    return this.checkPermission(authorityObject, activity, value);
+  }
+
+  /** Authorization check for a custom TableAction. */
+  canExecute(authorityObject: string, activity: string, value: string): boolean {
+    return this.hasPermission(authorityObject, activity, value);
   }
   canAccess(pageName: string)  { return this.checkPermission('PAGE', 'ACCESS', pageName); }
   canReport(reportName: string) { return this.checkPermission('REPORT', 'ACCESS', reportName); }
@@ -826,12 +828,23 @@ export abstract class BaseAuthService extends BaseRestService {
     return undefined;
   }
 
+  /** Lands the next route build on `url` instead of the default target, so a
+   * return page under /login keeps its outcome; null withdraws it. */
+  setLanding(url: string | null): void {
+    this.landing = url;
+  }
+
   /**
    * Where to land after routes are (re)built. A fresh login starts from the
    * root or a `/login` route → go to the dashboard. A refresh / bookmark of an
    * authenticated route → preserve it so deep links survive route restoration.
    */
   private postLoginTarget(): string {
+    if (this.landing) {
+      const url = this.landing;
+      this.landing = null;
+      return url;
+    }
     const path = window.location.pathname;
     const preserve = !!path && path !== '/' && !path.startsWith('/login');
     return preserve ? path + window.location.search : '/dashboard';

package/src/service/domain_verifier.ts

@@ -1,20 +1,38 @@
 import { InjectionToken } from '@angular/core';
 import { Observable } from 'rxjs';
 
+/** keel domain_verification_method codes the component can run: email code, DNS TXT record, HTTP file. */
+export type DomainVerificationMethod = 'EC' | 'DT' | 'HF';
+
+/** keel's issued challenge (the `challenge` of the `partner_domain` `challenge` action). */
+export interface DomainChallenge {
+  method: string;
+  domainUrl: string;
+  domainName: string;
+  expiresAt: string;
+  recordName?: string;
+  recordValue?: string;
+  fileUrl?: string;
+  fileBody?: string;
+}
+
 /**
- * Port for proving ownership of a domain: issue a code, then confirm it.
+ * Port for proving ownership of a domain.
  *
  * sail ships no implementation — the endpoints, their paths and their payloads are
  * the app's. Register one at composition time:
  *
  *   { provide: DOMAIN_VERIFIER, useExisting: RegistrationService }
  *
- * Both methods may emit any body; `DomainVerificationComponent` reads only success
- * or failure, and reports the failure through `errorDetail()`.
+ * `requestVerification` sends an email code. `challenge` issues a DNS TXT or HTTP
+ * file challenge; implement it to offer those methods. `confirm` receives the
+ * method for a challenge and an empty code. `DomainVerificationComponent` reads only
+ * success or failure of the other calls, and reports a failure through `errorDetail()`.
  */
 export interface DomainVerifier {
   requestVerification(domain: string): Observable<unknown>;
-  confirm(domain: string, code: string): Observable<unknown>;
+  challenge?(domain: string, method: Exclude<DomainVerificationMethod, 'EC'>): Observable<DomainChallenge>;
+  confirm(domain: string, code: string, method?: DomainVerificationMethod): Observable<unknown>;
 }
 
 export const DOMAIN_VERIFIER = new InjectionToken<DomainVerifier>('SailDomainVerifier');

package/src/service/rest_url.ts

@@ -38,6 +38,9 @@ export const RestURL = {
   otpVerifyURL:        '/public/otp/verify',
   otpResendURL:        '/public/otp/resend',
   loginSocialURL:      '/public/login/social',
+  // Tenant single sign-on (keel SSOHandler): top-level navigations, never XHR.
+  ssoStartURL:         '/public/sso/start',
+  ssoSamlMetadataURL:  '/public/sso/saml/metadata',
   logoutEverywhereURL: '/api/user/logout-everywhere',
   deleteAccountURL:    '/api/user/account',
   // Self-service profile (keel ProfileHandler). GET profileURL reads the

package/src/util/sso.ts

@@ -0,0 +1,43 @@
+import { RestURL } from '../service/rest_url';
+
+/** Error codes keel's SSOHandler sends back to the return URL as `?error=`. */
+export type SsoErrorCode =
+  | 'sso_unavailable'
+  | 'sso_failed'
+  | 'mfa_required'
+  | 'sso_email_not_allowed'
+  | 'sso_no_account'
+  | 'sso_other_partner'
+  | 'sso_required'
+  | 'account_unavailable'
+  | 'identity_linked'
+  | 'sso_test_mismatch'
+  | 'domain_not_proven'
+  | 'server_error';
+
+/** Default wording; an app overrides entries through `SailGuiConfig.ssoErrorMessages`. */
+export const SSO_ERROR_MESSAGES: Record<SsoErrorCode, string> = {
+  sso_unavailable: 'Single sign-on is not available for this email address. Use another sign-in method.',
+  sso_failed: 'The sign-in could not be completed. Please try again.',
+  mfa_required: 'Your organization requires multi-factor authentication. Complete it at your organization\'s sign-in page and try again.',
+  sso_email_not_allowed: 'This account is outside your organization\'s verified domains.',
+  sso_no_account: 'You do not have an account yet. Ask your organization\'s administrator for access.',
+  sso_other_partner: 'This account belongs to another organization.',
+  sso_required: 'Your organization requires you to sign in with single sign-on.',
+  account_unavailable: 'This account is locked or expired. Contact your administrator.',
+  identity_linked: 'This account is already linked to a different identity at your organization\'s identity provider.',
+  sso_test_mismatch: 'The identity provider signed in someone other than you. Sign in there as yourself and test again.',
+  domain_not_proven: 'The identity provider did not prove your organization\'s domain.',
+  server_error: 'Something went wrong. Please try again.',
+};
+
+/** The message for a returned code; an unknown code reads as `server_error`. */
+export function ssoErrorMessage(code: string | null | undefined, overrides?: Partial<Record<SsoErrorCode, string>>): string {
+  const key = (code && code in SSO_ERROR_MESSAGES ? code : 'server_error') as SsoErrorCode;
+  return overrides?.[key] ?? SSO_ERROR_MESSAGES[key];
+}
+
+/** keel's `/public/sso/start` for an address, on the API host. */
+export function ssoStartUrl(email: string): string {
+  return RestURL.httpHost + RestURL.ssoStartURL + '?' + new URLSearchParams({ email: email.trim() }).toString();
+}