portal-mojo 0.2.20 → 0.2.21

package/src/admin/maintenance/operations.ts

@@ -0,0 +1,208 @@
+/** Installation + actor receipt registry deliberately outlives every page/dialog. */
+import { apiOrigin } from '../../client/client';
+import { getAuthSnapshot } from '../../client/runtime';
+import {
+    applyMaintenance,
+    updateFramework,
+    readMaintenanceStatus,
+    readFrameworkDeployment, saveFrameworkPolicy, policyMatches, normalizePolicy,
+    MaintenanceError,
+    type ApplyInput,
+    type ResourceStatus,
+    type Scope,
+    type Framework, type FrameworkObservation,
+} from './data';
+export type AttemptState =
+    | 'sending'
+    | 'waiting'
+    | 'uncertain'
+    | 'refused'
+    | 'complete'
+    | 'accepted'
+    | 'timeout';
+export interface MaintenanceAttempt {
+    key: string;
+    actor: string;
+    input: Readonly<ApplyInput> | { version: string } | { policy: string };
+    state: AttemptState;
+    message: string;
+    observations: number;
+    observation?: ResourceStatus;
+    deployment?: { id: string; sha: string; status: string };
+    generation: number;
+    observedAt?: number;
+    frameworkObservation?: FrameworkObservation;
+}
+const attempts = new Map<string, MaintenanceAttempt>();
+const listeners = new Set<() => void>();
+let revision = 0;
+const changed = () => {
+    revision++;
+    for (const cb of listeners) cb();
+};
+export const subscribeMaintenanceAttempts = (cb: () => void) => {
+    listeners.add(cb);
+    return () => {
+        listeners.delete(cb);
+    };
+};
+export const maintenanceAttemptsRevision = () => revision;
+export const maintenanceActor = () => `${apiOrigin()}|${getAuthSnapshot().uid ?? 'anonymous'}`;
+export const resourceKey = (input: Pick<ApplyInput, 'kind' | 'resource'>) =>
+    `${input.kind}:${input.resource}`;
+const scopedKey = (key: string, actor = maintenanceActor()) => `${actor}|${key}`;
+export const getMaintenanceAttempts = () =>
+    [...attempts.values()].filter((a) => a.actor === maintenanceActor());
+export const getMaintenanceAttempt = (key: string) => attempts.get(scopedKey(key));
+export const maintenanceCompleted = (r: ResourceStatus) =>
+    r.found === true && r.settled === true && r.upgraded === true;
+function claim(key: string, input: MaintenanceAttempt['input']): MaintenanceAttempt {
+    const id = scopedKey(key);
+    if (!canRequestMaintenance(key, input)) throw new MaintenanceError('attempt_requires_reconciliation');
+    const attempt: MaintenanceAttempt = {
+        key,
+        actor: maintenanceActor(),
+        input: Object.freeze({ ...input }),
+        state: 'sending',
+        message: 'Requesting operation…',
+        observations: 0,
+        generation: 0,
+    };
+    attempts.set(id, attempt);
+    changed();
+    return attempt;
+}
+export function canRequestMaintenance(key: string, input?: MaintenanceAttempt['input']) {
+    const a = getMaintenanceAttempt(key);
+    if ((key === 'framework' || key === 'framework-policy') && getMaintenanceAttempts().some(x => (x.key === 'framework' || x.key === 'framework-policy') && x.key !== key && !['complete','refused'].includes(x.state))) return false;
+    if (!a) return true;
+    if (a.state !== 'complete') return false;
+    if (!input) return true;
+    return 'kind' in a.input && 'kind' in input ? a.input.target_version !== input.target_version : 'version' in a.input && 'version' in input ? a.input.version !== input.version : 'policy' in a.input && 'policy' in input && a.input.policy !== input.policy;
+}
+function failed(a: MaintenanceAttempt, e: unknown) {
+    a.state = e instanceof MaintenanceError && e.mutationState === 'none' ? 'refused' : 'uncertain';
+    a.message =
+        e instanceof MaintenanceError
+            ? e.message
+            : 'The response is unknown. Reconcile provider operations before another request.';
+    changed();
+}
+export async function requestMaintenance(input: ApplyInput, scope?: Scope) {
+    const a = claim(resourceKey(input), input);
+    try {
+        await applyMaintenance(input, scope);
+        a.state = 'waiting';
+        a.message = 'Requested — waiting for AWS evidence.';
+        changed();
+        return a;
+    } catch (e) {
+        failed(a, e);
+        throw e;
+    }
+}
+export async function requestFramework(version: string, scope?: Scope) {
+    const a = claim('framework', { version });
+    try {
+        const result = await updateFramework(version, scope);
+        a.state = 'accepted';
+        a.deployment = result.deployment;
+        a.message =
+            'Deployment requested. Follow its node evidence in Deployments; fleet completion is unconfirmed.';
+        changed();
+        return a;
+    } catch (e) {
+        failed(a, e);
+        if (a.state === 'uncertain')
+            a.message =
+                'The pin may already be cleared while deployment acceptance is unknown. Refresh Framework and reconcile Deployments before any further update.';
+        changed();
+        throw e;
+    }
+}
+export async function requestPolicy(policy: string, scope?: Scope) {
+    policy = normalizePolicy(policy);
+    const a = claim('framework-policy', { policy });
+    try { await saveFrameworkPolicy(policy, scope); a.state = 'waiting'; a.message = 'Policy saved. Reading back current policy; no deployment requested.'; changed(); return a; }
+    catch (error) { failed(a, error); throw error; }
+}
+export function reconcilePolicy(f: Framework) {
+    const a = getMaintenanceAttempt('framework-policy');
+    if (!a || !('policy' in a.input) || a.state === 'sending' || a.state === 'refused' || a.state === 'complete') return;
+    a.observedAt = Date.now();
+    if (policyMatches(f.pin, a.input.policy)) {
+        if (a.state === 'uncertain' || a.state === 'timeout') a.message = 'Requested policy is now observed, but the original save outcome remains unknown. Readback cannot prove that request finished. Reconcile the server audit before any further policy write.';
+        else { a.state = 'complete'; a.message = 'Saved policy is now observed. No deployment was requested; node activation is separate.'; }
+    }
+    else a.message = 'Current policy differs from the submitted choice. Its outcome is unresolved; refresh and reconcile before another write.';
+    changed();
+}
+export async function observeFramework(a: MaintenanceAttempt, scope: Scope = {}) {
+    if (!('version' in a.input) || !a.deployment || ['sending','refused','complete'].includes(a.state)) return;
+    const generation = ++a.generation, actor = maintenanceActor();
+    try {
+        const result = await readFrameworkDeployment(a.deployment, a.input.version, scope); scope.beforeSend?.();
+        if (scope.signal?.aborted || actor !== maintenanceActor() || a.actor !== actor || generation !== a.generation) return;
+        a.frameworkObservation = result; a.observedAt = Date.now(); a.observations++;
+        a.state = result.terminal ? 'complete' : 'accepted';
+        a.message = `Deployment ${result.status}. ${result.versionProven ? 'Requested framework version observed on every deployment target.' : 'Requested framework version remains unverified.'}`;
+        changed();
+    } catch (error) {
+        if (scope.signal?.aborted || actor !== maintenanceActor() || generation !== a.generation) return;
+        a.observations++; a.message = error instanceof MaintenanceError ? error.message : 'Deployment evidence unavailable; the original update remains guarded.'; changed();
+    }
+}
+/** Only a proven pre-provider refusal is releasable by explicit successful refresh. */
+export function refreshRefusedMaintenanceAttempt(key: string) {
+    const a = getMaintenanceAttempt(key);
+    if (a?.state === 'refused') {
+        attempts.delete(scopedKey(key));
+        changed();
+    }
+}
+export async function observeMaintenance(a: MaintenanceAttempt, scope: Scope = {}) {
+    if (!('kind' in a.input) || a.state === 'complete' || a.state === 'sending' || a.state === 'refused')
+        return;
+    const generation = ++a.generation;
+    const actor = maintenanceActor();
+    try {
+        const result = await readMaintenanceStatus(a.input, scope);
+        scope.beforeSend?.();
+        if (
+            scope.signal?.aborted ||
+            actor !== maintenanceActor() ||
+            a.actor !== actor ||
+            generation !== a.generation
+        )
+            return;
+        a.observation = result;
+        a.observedAt = Date.now();
+        a.observations++;
+        a.state = maintenanceCompleted(result)
+            ? 'complete'
+            : a.state === 'uncertain'
+              ? 'uncertain'
+              : 'waiting';
+        a.message =
+            a.state === 'complete'
+                ? `Upgraded to ${a.input.target_version}; AWS reports ${a.input.kind === 'rds-cluster' ? 'the cluster' : 'every member'} settled.`
+                : `${result.status ?? 'Status unknown'} — waiting/unconfirmed. A version or available state alone does not prove completion.`;
+        changed();
+    } catch (e) {
+        if (scope.signal?.aborted || actor !== maintenanceActor() || generation !== a.generation) return;
+        a.observations++;
+        a.message =
+            e instanceof MaintenanceError
+                ? e.message
+                : 'Status unavailable; the original request remains guarded.';
+        changed();
+    }
+}
+export function maintenanceObservationLimit(a: MaintenanceAttempt) {
+    if (a.state === 'waiting' || a.state === 'uncertain' || a.state === 'accepted') {
+        a.state = 'timeout';
+        a.message =
+            'Automatic observations reached their limit. The attempt remains guarded. Refresh status or reconcile the provider operation and maintenance window.';
+        changed();
+    }
+}

package/src/admin/public/infrastructure.ts

@@ -3,3 +3,4 @@ export * from '../domains/infrastructure';
 export * from '../dns';
 export * from '../storage';
 export * from '../edge';
+export * from '../fleet';

package/src/admin/public/operations.ts

@@ -2,3 +2,6 @@ export * from '../domains/operations';
 export * from '../settings';
 export * from '../jobs';
 export { FleetConfigurationPage, FleetNodeStatus } from '../fleet-configuration/FleetConfigurationPage';
+export * from '../geolocation';
+export * from '../maintenance';
+export * from '../deployments';

package/src/admin/registry.ts

@@ -2,12 +2,12 @@ import type { AdminSection } from './core';
 import './dns/setup';
 import { DASHBOARD_ADMIN_SECTION, MONITORING_ADMIN_SECTION, CLOUDWATCH_ADMIN_SECTION } from './domains/observability';
 import { USERS_ADMIN_SECTION, MEMBERS_ADMIN_SECTION, GROUPS_ADMIN_SECTION, PERSONAL_API_KEYS_ADMIN_SECTION, CREDENTIALS_ADMIN_SECTION, SIGNIN_ADMIN_SECTION } from './domains/identity';
-import { SETTINGS_ADMIN_SECTION, FLEET_CONFIGURATION_ADMIN_SECTION, JOBS_ADMIN_SECTION } from './domains/operations';
+import { SETTINGS_ADMIN_SECTION, FLEET_CONFIGURATION_ADMIN_SECTION, JOBS_ADMIN_SECTION, MAINTENANCE_ADMIN_SECTION, DEPLOYMENTS_ADMIN_SECTION, GEOLOCATION_ADMIN_SECTION } from './domains/operations';
 import {
     SECURITY_OPERATIONS_ADMIN_SECTION, BOUNCER_ADMIN_SECTION,
     DEVICE_INTEL_ADMIN_SECTION, GEOIP_ADMIN_SECTION, NETWORK_SECURITY_ADMIN_SECTION,
 } from './domains/security';
-import { DNS_ADMIN_SECTION, EDGE_ADMIN_SECTION, STORAGE_ADMIN_SECTION } from './domains/infrastructure';
+import { FLEET_ADMIN_SECTION, DNS_ADMIN_SECTION, EDGE_ADMIN_SECTION, STORAGE_ADMIN_SECTION } from './domains/infrastructure';
 import {
     SHORTLINKS_ADMIN_SECTION, EMAIL_ADMIN_SECTION, PUBLIC_MESSAGES_ADMIN_SECTION,
     PUSH_ADMIN_SECTION, PHONE_HUB_ADMIN_SECTION,
@@ -25,6 +25,10 @@ export const ADMIN_SECTIONS: readonly AdminSection[] = [
     SIGNIN_ADMIN_SECTION,
     MONITORING_ADMIN_SECTION,
     CLOUDWATCH_ADMIN_SECTION,
+    FLEET_ADMIN_SECTION,
+    MAINTENANCE_ADMIN_SECTION,
+    DEPLOYMENTS_ADMIN_SECTION,
+    GEOLOCATION_ADMIN_SECTION,
     SETTINGS_ADMIN_SECTION,
     FLEET_CONFIGURATION_ADMIN_SECTION,
     SECURITY_OPERATIONS_ADMIN_SECTION,

package/src/admin/settings/SettingDetail.tsx

@@ -1,14 +1,19 @@
 import { Badge, DetailView, Eyebrow, FlatRow, fmt } from '../../ui';
-import { useCan } from '../../client/runtime';
+import { useCan, useMe } from '../../client/runtime';
+import { backendGlobalCan } from '../fleet/access';
 import {
     SETTINGS_PERMISSIONS, SettingModel, settingGroupLabel, type SettingRow,
 } from './model';
 import { showSettingEditor } from './SettingEditor';
 import { SettingValue } from './SettingValue';
+import { useAdminRouteContext } from '../core/route-context';
 
 export function SettingDetail({ id, onClose }: { id: number; onClose: () => void }) {
     const { data: row, isPending, error } = SettingModel.useOne(id);
     const { can } = useCan(SETTINGS_PERMISSIONS);
+    const route = useAdminRouteContext();
+    const { data: me } = useMe();
+    const maintenanceHref = backendGlobalCan(me, ['view_platform','manage_platform','admin']) && route?.paths.includes(`${route.mount.replace(/\/$/, '')}/maintenance`) ? `#${route.mount.replace(/\/$/, '')}/maintenance?tab=framework` : undefined;
     if (isPending) return <div className="modal-pad dim">Loading setting…</div>;
     if (!row || error) return <div className="modal-pad text-bad">{error?.message ?? 'Setting not found'}</div>;
 
@@ -40,7 +45,7 @@ export function SettingDetail({ id, onClose }: { id: number; onClose: () => void
                                     The stored value is write-only. Editing with a blank replacement preserves it.
                                 </p>
                             )}
-                            {can && (
+                            {row.key === 'EDGE_FRAMEWORK_VERSION' ? <p className="dim">Managed by Maintenance → Django-MOJO. {maintenanceHref && <a href={maintenanceHref} onClick={onClose}>Open framework policy</a>}</p> : can && (
                                 <div style={{ marginTop: 16 }}>
                                     <button className="btn btn-compact" onClick={() => void showSettingEditor(row)}>
                                         <i className="bi bi-pencil" /> Edit setting

package/src/admin/settings/SettingEditor.tsx

@@ -73,6 +73,7 @@ function SettingEditor({ row, close }: {
         <form className="modal-pad" onSubmit={submit} noValidate>
             <h2 className="modal-title">{row ? `Edit setting — ${row.key}` : 'Create setting'}</h2>
             {error && <div className="form-alert">{error}</div>}
+            {key.trim() === 'EDGE_FRAMEWORK_VERSION' && <p className="form-alert">Framework update policy is managed in Maintenance → Django-MOJO.</p>}
             <div className="form-grid">
                 <div className="col-12">
                     <label className="field">
@@ -142,7 +143,7 @@ function SettingEditor({ row, close }: {
             </div>
             <div className="modal-actions">
                 <button type="button" className="btn" disabled={busy} onClick={() => close(null)}>Cancel</button>
-                <button type="submit" className="btn btn-primary" disabled={busy || !key.trim()}>
+                <button type="submit" className="btn btn-primary" disabled={busy || !key.trim() || key.trim() === 'EDGE_FRAMEWORK_VERSION'}>
                     {busy ? 'Saving…' : row ? 'Save changes' : 'Create setting'}
                 </button>
             </div>

package/src/admin/settings/SettingsPage.tsx

@@ -1,3 +1,4 @@
+import { AdminRouteContext, useAdminRouteContext } from '../core/route-context';
 import { useQueryClient } from '@tanstack/react-query';
 import {
     Badge, ModelTable, fmt, modal, type Column, type FilterDef,
@@ -44,9 +45,10 @@ const FILTERS: FilterDef[] = [
 
 export function SettingsPage() {
     const queryClient = useQueryClient();
+    const routeContext = useAdminRouteContext();
     const openDetail = (row: SettingRow) => {
         void SettingModel.fetchOne(queryClient, row.id).catch(() => undefined);
-        void modal.detail((close) => <SettingDetail id={row.id} onClose={() => close(null)} />);
+        void modal.detail((close) => <AdminRouteContext.Provider value={routeContext}><SettingDetail id={row.id} onClose={() => close(null)} /></AdminRouteContext.Provider>);
     };
     return (
         <ModelTable<SettingRow>

package/src/admin/settings/model.ts

@@ -77,6 +77,7 @@ export function buildSettingPayload(draft: SettingDraft, original: SettingRow |
     const changes: Record<string, unknown> = {};
     const key = draft.key.trim();
     if (!key) throw new Error('Key is required');
+    if (key === 'EDGE_FRAMEWORK_VERSION' || original?.key === 'EDGE_FRAMEWORK_VERSION') throw new Error('Framework update policy is managed in Maintenance → Django-MOJO, through its dedicated owner writer.');
 
     if (original == null) {
         if (draft.is_secret && draft.value === '') throw new Error('Enter a secret value');

package/src/admin/signin/SigninPage.tsx

@@ -1,5 +1,5 @@
 // System Sign-in admin (#5547): the SYSTEM login page look & feel plus the
-// Google / Apple / GitHub OAuth provider credentials, over one endpoint
+// Google / Apple / GitHub / Microsoft OAuth provider credentials, over one endpoint
 // (GET/POST /api/account/admin/signin, global manage_settings | admin).
 // Deliberately simple: an explicit Save for look & feel that sends only the
 // changed dotted paths, one Save per provider card, and an immediate Enabled
@@ -79,12 +79,19 @@ const FIELD_GROUPS: FieldGroup[] = [
 
 const TOKEN_LABELS: Record<string, string> = {
     password: 'Password', sms: 'SMS code', passkey: 'Passkey', magic: 'Magic link',
-    google: 'Google', apple: 'Apple', github: 'GitHub',
+    google: 'Google', apple: 'Apple', github: 'GitHub', microsoft: 'Microsoft',
     'branded-panel': 'Branded panel',
 };
 const tokenLabel = (token: string) => TOKEN_LABELS[token] ?? token.charAt(0).toUpperCase() + token.slice(1).replace(/-/g, ' ');
 const LAYOUT_ALIASES: Record<string, string> = { card: 'compact', fullscreen: 'branded-panel' };
-const PROVIDER_ICONS: Record<string, string> = { google: 'bi-google', apple: 'bi-apple', github: 'bi-github' };
+const PROVIDER_ICONS: Record<string, string> = { google: 'bi-google', apple: 'bi-apple', github: 'bi-github', microsoft: 'bi-microsoft' };
+// Server-supplied card notices (#8967), e.g. an app secret about to expire. Unknown tones read as info.
+type NoticeTone = NonNullable<SigninProvider['notices']>[number]['tone'];
+const NOTICE_STYLES: Record<NoticeTone, { className: string; icon: string }> = {
+    info: { className: 'signin-note', icon: 'bi-info-circle' },
+    warning: { className: 'signin-note is-warning', icon: 'bi-exclamation-triangle' },
+    danger: { className: 'signin-note is-danger', icon: 'bi-x-octagon' },
+};
 const SOURCE_LABELS: Record<SigninProviderField['source'], string> = {
     admin: 'Set in Admin', deployment: 'Set in server config', none: 'Not set',
 };
@@ -326,6 +333,13 @@ function ProviderCard({ provider, onSaved }: { provider: SigninProvider; onSaved
             <i className="bi bi-exclamation-triangle" />
             <span>Shown on the sign-in page, but it will not work until these are set: {provider.missing.join(', ')}.</span>
         </div>}
+        {(provider.notices ?? []).map((notice, index) => {
+            const style = Object.hasOwn(NOTICE_STYLES, notice.tone) ? NOTICE_STYLES[notice.tone] : NOTICE_STYLES.info;
+            return <div key={index} className={style.className} role="status">
+                <i className={`bi ${style.icon}`} />
+                <span>{notice.text}</span>
+            </div>;
+        })}
         {error && <div className="form-alert" role="alert">{error}</div>}
         <div className="field">
             <label className="field-label" htmlFor={`signin-${provider.name}-callback`}>Callback URL</label>

package/src/admin/signin/api.ts

@@ -30,6 +30,8 @@ export interface SigninProvider {
     console_url: string;
     help: string;
     fields: SigninProviderField[];
+    /** Server-supplied card notes (#8967), e.g. a secret nearing expiry. Absent from older backends; nothing renders then. */
+    notices?: { tone: 'warning' | 'danger' | 'info'; text: string }[];
 }
 
 export interface SigninOptions {

package/src/charts/MetricsChartView.tsx

@@ -1,3 +1,4 @@
+import { ComboBox } from '../ui/ComboBox';
 // Shared MetricsChart presentation. The owner supplies every payload and request.
 import { useLayoutEffect, useRef, useState, useSyncExternalStore, type ReactNode } from 'react';
 import { DateRangePicker } from '../ui/date/DateRangePicker';
@@ -180,17 +181,9 @@ export function MetricsChartView({
                                     );
                                 })}
                             </div>
-                            <select
-                                className="input input-compact gran-select"
-                                value={effective}
-                                disabled={disabled || available.length === 0}
-                                onChange={(e) => setGranularity(e.target.value)}
-                                aria-label="Granularity"
-                            >
-                                {GRANULARITIES.filter((g) => available.includes(g.value)).map((g) => (
-                                    <option key={g.value} value={g.value}>{g.label}</option>
-                                ))}
-                            </select>
+                            <ComboBox allowCustom={false} maxSuggestions={Number.MAX_SAFE_INTEGER} className="gran-select" value={String(effective)} disabled={disabled || available.length === 0} onChange={(selectedValue) => setGranularity(String(selectedValue))} aria-label="Granularity" options={[...(GRANULARITIES.filter((g) => available.includes(g.value)).map((g) => (
+                                    ({ value: String(g.value), label: String(g.label) })
+                                )) ?? [])]} />
                         </>
                     )}
 

package/src/charts/MetricsMiniWidget.tsx

@@ -1,3 +1,4 @@
+import { ComboBox } from '../ui/ComboBox';
 // MetricsMiniWidget — the compact metrics card: icon + title + computed
 // subtitle, windowed trending chip, embedded MiniChart sparkline, and the
 // stats / view-data / refresh / settings action row. Ported from web-mojo
@@ -154,24 +155,11 @@ function SettingsDialog({ title, initial, showDateRange, onDone }: {
             <div className="mmw-settings">
                 <label className="field">
                     <span className="field-label">Granularity</span>
-                    <select
-                        className="input"
-                        value={values.granularity}
-                        onChange={(e) => setValues((v) => ({ ...v, granularity: e.target.value }))}
-                    >
-                        {GRANULARITY_OPTIONS.map((o) => <option key={o.value} value={o.value}>{o.label}</option>)}
-                    </select>
+                    <ComboBox allowCustom={false} maxSuggestions={Number.MAX_SAFE_INTEGER} value={String(values.granularity)} onChange={(selectedValue) => setValues((v) => ({ ...v, granularity: String(selectedValue) }))} options={[...(GRANULARITY_OPTIONS.map((o) => ({ value: String(o.value), label: String(o.label) })) ?? [])]} />
                 </label>
                 <label className="field">
                     <span className="field-label">Chart type</span>
-                    <select
-                        className="input"
-                        value={values.chartType}
-                        onChange={(e) => setValues((v) => ({ ...v, chartType: e.target.value === 'bar' ? 'bar' : 'line' }))}
-                    >
-                        <option value="line">Line</option>
-                        <option value="bar">Bar</option>
-                    </select>
+                    <ComboBox allowCustom={false} maxSuggestions={Number.MAX_SAFE_INTEGER} value={String(values.chartType)} onChange={(selectedValue) => setValues((v) => ({ ...v, chartType: String(selectedValue) === 'bar' ? 'bar' : 'line' }))} options={[({ value: "line", label: "Line" }), ({ value: "bar", label: "Bar" })]} />
                 </label>
                 {showDateRange && (
                     <div className="field">

package/src/client/client.ts

@@ -85,6 +85,8 @@ export function buildQuery(params: Params): string {
 }
 
 export interface FetchOpts {
+    /** Domain receipt identity; the only caller-supplied request header. */
+    idempotencyKey?: string;
     params?: Params;
     method?: 'GET' | 'POST' | 'DELETE';
     body?: Record<string, unknown>;
@@ -145,6 +147,9 @@ export function installAuthHooks(hooks: AuthHooks | null): void {
 }
 
 async function transport(path: string, opts: FetchOpts): Promise<Envelope> {
+    if (opts.idempotencyKey !== undefined && (typeof opts.idempotencyKey !== 'string' || !/^[A-Za-z0-9._:-]{1,128}$/.test(opts.idempotencyKey))) {
+        throw new TypeError('idempotencyKey must contain 1–128 safe receipt characters');
+    }
     // Gate BEFORE headers are built: after a mid-gate token refresh the fresh
     // Authorization value is picked up below by construction (web-mojo had to
     // re-stamp a snapshotted header here).
@@ -157,6 +162,7 @@ async function transport(path: string, opts: FetchOpts): Promise<Envelope> {
     };
     const bearer = authHooks?.authHeader();
     if (bearer) headers['Authorization'] = bearer;
+    if (opts.idempotencyKey !== undefined) headers['Idempotency-Key'] = opts.idempotencyKey;
 
     if (usingMockTransport()) {
         const { mockFetch } = await loadMockModule();