portal-mojo 0.2.19 → 0.2.21

package/src/admin/deployments/sanitize.ts

@@ -0,0 +1,73 @@
+import { detectTemporal } from '../../ui/date/fns';
+import type { AddressPrecheck, Attempt, Bootstrap, Certificate, Collector, DeploymentStatus, OnboardingOperation, OnboardingOptions, PlatformAttempt, PlatformSnapshot, Proof, Release, WebApp, WebAppList, WebAppObject, WebAppSummary } from './types';
+export const record = (v: unknown): Record<string, unknown> => v && typeof v === 'object' && !Array.isArray(v) ? v as Record<string, unknown> : {};
+export const text = (v: unknown, max = 256): string => typeof v === 'string' ? v.slice(0, max).replace(/[\u0000-\u0008\u000b-\u001f]/g, '') : typeof v === 'number' && Number.isFinite(v) ? String(v) : '';
+export function dateText(v: unknown): string { const temporal = detectTemporal(v); if (!temporal)
+    return text(v); const d = new Date(temporal.ms); return Number.isNaN(d.getTime()) ? text(v) : d.toISOString(); }
+export const positiveId = (v: unknown): number => typeof v === 'number' && Number.isSafeInteger(v) && v > 0 ? v : 0;
+export const count = (v: unknown): number => typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : 0;
+export const list = (v: unknown, max = 128): unknown[] => Array.isArray(v) ? v.slice(0, max) : [];
+export function uuid(v: unknown): string { const s = text(v, 36); return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(s) ? s : ''; }
+function certificate(v: unknown): Certificate | null { if (!v)
+    return null; const r = record(v); return { status: text(r.status) || 'unknown', not_after: text(r.not_after) }; }
+export function projectRelease(v: unknown): Release { const r = record(v); return {
+    id: positiveId(r.id), version: text(r.version), status: text(r.status) || 'unknown', source: text(r.source) || 'unknown', created: text(r.created)
+}; }
+export function projectWebApp(v: unknown): WebApp { const r = record(v); return {
+    id: positiveId(r.id), slug: text(r.slug, 64), display_name: text(r.display_name, 120), environment: text(r.environment), deployment_ref: text(r.deployment_ref), repository: text(r.repository ?? r.github_repository), build_output: text(r.build_output)
+}; }
+export function projectWebAppObject(v: unknown): WebAppObject { const r = record(v), g = record(r.group); return { ...projectWebApp(r), group: { id: positiveId(g.id), name: text(g.name) } }; }
+export function projectAttempt(v: unknown): Attempt { const r = record(v); return {
+    id: positiveId(r.id), status: text(r.status) || 'unknown', created: dateText(r.created), started: dateText(r.started), finished: dateText(r.finished), detail: text(r.detail, 1500), release: r.release ? projectRelease(r.release) : null
+}; }
+export function projectSummary(v: unknown): WebAppSummary { const r = record(v), a = record(r.address), o = record(r.onboarding), k = record(r.deployment_key); return {
+    webapp: projectWebApp(r.webapp), address: r.address ? {
+        hostname: text(a.hostname), certificate: certificate(a.certificate), aliases: list(a.aliases, 32).map(x => { const v = record(x); return { hostname: text(v.hostname), certificate: certificate(v.certificate) }; })
+    } : null, current_release: r.current_release ? projectRelease(r.current_release) : null, latest_deployment: r.latest_deployment ? projectAttempt(r.latest_deployment) : null, onboarding: { status: text(o.status) || 'unknown', cursor: text(o.cursor) }, deployment_key: { linked: k.linked === true, active: k.active === true }
+}; }
+export function projectSummaries(v: unknown): WebAppList { const r = record(v); if (r.schema_version !== 1)
+    throw new Error('Unsupported WebApp summary schema'); return {
+    items: list(r.items, 50).map(projectSummary).filter(x => x.webapp.id > 0), count: count(r.count), limit: count(r.limit), truncated: r.truncated === true
+}; }
+function proof(v: unknown): Proof { const r = record(v), p = record(r.proof), d = record(r.detail); return {
+    runner: text(r.runner ?? r.runner_id), status: text(r.status ?? r.state ?? r.kind) || 'unknown', detail: text(typeof r.detail === 'string' ? r.detail : d.message ?? d.reason ?? d.phase ?? r.reason ?? r.message, 1500), sha: text(p.platform_sha), deployment: uuid(p.platform_deployment), stderr_tail: text(d.stderr_tail ?? r.stderr_tail, 2000)
+}; }
+export function projectPlatformAttempt(v: unknown): PlatformAttempt { const r = record(v), n = record(r.node_summary), d = record(r.detail); return {
+    id: uuid(r.id), sha: text(r.sha, 40), framework_version: text(r.framework_version), status: text(r.status) || 'unknown', source: text(r.source), actor: text(r.actor), retry_of: uuid(r.retry_of), created: dateText(r.created), started: dateText(r.started), finished: dateText(r.finished), duration_seconds: typeof r.duration_seconds === 'number' ? r.duration_seconds : null, desired_commit: text(r.desired_commit, 40), current_commits: list(r.current_commits).map(x => text(x, 40)), frozen_roster: list(r.frozen_roster).map(x => text(x)), transitions: list(r.transitions).map(proof), node_evidence: list(r.node_evidence).map(proof), diagnosis: list(r.diagnosis).map(proof), detail: text(typeof r.detail === 'string' ? r.detail : d.message ?? d.reason, 1500), node_summary: {
+        expected: count(n.expected), proven: count(n.proven), reported: count(n.reported), failed: count(n.failed), dispatched: count(n.dispatched), other: count(n.other)
+    }
+}; }
+function collector<T>(v: unknown, project: (v: unknown) => T): Collector<T> { const r = record(v); return {
+    status: text(r.status) || 'unknown', observed_at: text(r.observed_at ?? r.checked_at), stale_after: dateText(r.stale_after), reason: text(r.reason_detail ?? r.reason, 500), data: r.data && ['healthy', 'degraded', 'unhealthy', 'unknown', 'ok', 'unconfigured', 'stale'].includes(String(r.status)) ? project(r.data) : null
+}; }
+export function projectPlatform(v: unknown): PlatformSnapshot { const r = record(v), s = record(r.sections); if (r.schema_version !== 1)
+    throw new Error('Unsupported platform schema'); return { deployments: collector(s.deployments, v => { const d = record(v), c = record(d.currently_serving), o = record(d.coordination), f = record(d.framework_pin); return {
+        items: list(d.items, 50).map(projectPlatformAttempt).filter(x => x.id), limit: count(d.limit), desired_commit: text(d.desired_commit), desired_deployment: uuid(d.desired_deployment), currently_serving: d.currently_serving ? {
+            deployment: uuid(c.deployment), sha: text(c.sha, 40), framework_version: text(c.framework_version), converged_at: dateText(c.converged_at)
+        } : null, coordination: {
+            state: text(o.state), deployment: uuid(o.deployment), sha: text(o.sha, 40), at: text(o.at)
+        }, framework_pin: { mode: text(f.mode), resolved: text(f.resolved) }
+    }; }), api: collector(s.api, v => { const a = record(v); return { version: text(a.version), commit: text(a.commit) }; }) }; }
+export function projectBootstrap(v: unknown): Bootstrap { const r = record(v); return {
+    groups: list(r.webapp_groups, 128).map(v => { const g = record(v); return {
+        id: positiveId(g.id), name: text(g.name), can_manage_dns: g.can_manage_dns === true
+    }; }).filter(x => x.id > 0), can_create_webapp_group: r.can_create_webapp_group === true, setup: record(r.capabilities).setup === true
+}; }
+export function projectDeployment(v: unknown): DeploymentStatus { const r = record(v), status = text(r.status) || 'unknown'; return {
+    deployment: positiveId(r.deployment), webapp: positiveId(r.webapp), release: positiveId(r.release), version: text(r.version), status, terminal: ['live', 'failed', 'rolled_back', 'superseded'].includes(status) && r.terminal === true, success: status === 'live' && r.success === true, detail: text(r.detail, 1500), created: dateText(r.created), started: dateText(r.started), finished: dateText(r.finished), targets: list(r.targets).map(proof), rollback_targets: list(r.rollback_targets).map(proof)
+}; }
+export function projectOperation(v: unknown): OnboardingOperation { const r = record(v), g = record(r.group), p = record(r.profile), e = record(r.evidence), a = record(e.app), d = record(e.address), h = record(e.github), f = record(e.verify), resources = record(r.resources); if (r.schema_version !== 1 || !uuid(r.operation_id))
+    throw new Error('Invalid onboarding operation'); return {
+    operation_id: uuid(r.operation_id), group: { id: positiveId(g.id), name: text(g.name) }, status: text(r.status) || 'unknown', cursor: text(r.cursor) || 'unknown', revision: count(r.revision), profile: { slug: text(p.slug, 64), display_name: text(p.display_name, 120) }, evidence: {
+        app: { status: text(a.status) }, address: { status: text(d.status), hostname: text(d.hostname) }, github: { status: text(h.status), reason: text(h.reason) }, verify: { status: text(f.status), detail: text(f.detail) }
+    }, activity: list(r.activity, 64).map(v => { const x = record(v); return {
+        message: text(x.message, 500), kind: text(x.kind), at: dateText(x.at)
+    }; }), resources: { webapp: positiveId(resources.webapp) || null }, next_attempt_at: dateText(r.next_attempt_at), last_error: text(r.last_error, 1500), modified: dateText(r.modified)
+}; }
+export function projectOptions(v: unknown): OnboardingOptions { const r = record(v), d = record(r.apps_domain); if (r.schema_version !== 1)
+    throw new Error('Unsupported onboarding options'); return {
+    buckets: list(r.buckets, 64).map(x => text(x)).filter(Boolean), environments: list(r.environments, 8).map(x => text(x)), destination: !!r.destination, destination_error: text(r.destination_error, 500), apps_domain: r.apps_domain ? { id: positiveId(d.id), name: text(d.name) } : null, apps_domain_error: text(r.apps_domain_error, 500), github_connected: r.github_connected === true
+}; }
+export function projectPrecheck(v: unknown): AddressPrecheck { const r = record(v), d = record(r.domain); return {
+    verdict: text(r.verdict) || 'unknown', hostname: text(r.hostname ?? record(r.normalized).hostname), reason: text(r.reason, 500), domain: r.domain ? { id: positiveId(d.id), name: text(d.name) } : null, label: text(r.label ?? record(r.normalized).label)
+}; }

package/src/admin/deployments/shared.tsx

@@ -0,0 +1,39 @@
+import { useEffect, useRef, useState, type ReactNode } from 'react';
+import { deploymentTone } from './deployment-state';
+import type { DeploymentOwner } from './permissions';
+import { assertOwner } from './permissions';
+export { FleetHelp as DeploymentHelp } from '../fleet/FleetHelp';
+export function Status({ value }: {
+    value: string;
+}) { return <span className={`deployment-status text-${deploymentTone(value)}`}>{value || 'unknown'}</span>; }
+export function Facts({ rows }: {
+    rows: [
+        string,
+        ReactNode
+    ][];
+}) { return <dl className="deployment-facts">{rows.map(([label, value]) => <div key={label}><dt>{label}</dt><dd>{value || 'Unknown'}</dd></div>)}</dl>; }
+export function ErrorNotice({ children }: {
+    children: ReactNode;
+}) { return <p role="alert" className="text-bad">{children}</p>; }
+/** A ref locks the initiating event before React's next render. */
+export function useWrite(owner: DeploymentOwner, signal: AbortSignal, onBusy?: (busy: boolean) => void) { const lock = useRef(false), alive = useRef(true); const [busy, setBusy] = useState(false), [error, setError] = useState(''); useEffect(() => { alive.current = true; return () => { alive.current = false; }; }, []); return {
+    busy, error, run: async (fn: () => Promise<void>) => { if (lock.current)
+        return; lock.current = true; setBusy(true); setError(''); onBusy?.(true); try {
+        assertOwner(owner, signal);
+        await fn();
+        assertOwner(owner, signal);
+    }
+    catch (e) {
+        if (alive.current && !signal.aborted)
+            setError(e instanceof Error ? e.message : 'Operation outcome unknown. Refresh to reconcile.');
+    }
+    finally {
+        lock.current = false;
+        if (alive.current) {
+            setBusy(false);
+            onBusy?.(false);
+        }
+    } }
+}; }
+export function useCloseOnOwnerChange(key: string, onClose: () => void) { const previous = useRef(key); useEffect(() => { if (previous.current !== key)
+    onClose(); previous.current = key; }, [key, onClose]); }

package/src/admin/deployments/types.ts

@@ -0,0 +1,238 @@
+/** Safe display DTOs. Raw server objects and upload/key material never reach Query. */
+export interface Release {
+    id: number;
+    version: string;
+    status: string;
+    source: string;
+    created: string;
+}
+export interface WebApp {
+    id: number;
+    slug: string;
+    display_name: string;
+    environment: string;
+    deployment_ref: string;
+    repository: string;
+    build_output: string;
+}
+export interface WebAppObject extends WebApp {
+    group: {
+        id: number;
+        name: string;
+    };
+}
+export interface Certificate {
+    status: string;
+    not_after: string;
+}
+export interface Attempt {
+    id: number;
+    started?: string;
+    detail?: string;
+    status: string;
+    created: string;
+    finished: string;
+    release: Release | null;
+}
+export interface WebAppSummary {
+    webapp: WebApp;
+    address: {
+        hostname: string;
+        certificate: Certificate | null;
+        aliases: {
+            hostname: string;
+            certificate: Certificate | null;
+        }[];
+    } | null;
+    current_release: Release | null;
+    latest_deployment: Attempt | null;
+    onboarding: {
+        status: string;
+        cursor: string;
+    };
+    deployment_key: {
+        linked: boolean;
+        active: boolean;
+    };
+}
+export interface WebAppList {
+    items: WebAppSummary[];
+    count: number;
+    limit: number;
+    truncated: boolean;
+}
+export interface Proof {
+    runner: string;
+    status: string;
+    detail: string;
+    sha: string;
+    deployment: string;
+    stderr_tail: string;
+}
+export interface PlatformAttempt {
+    id: string;
+    sha: string;
+    framework_version: string;
+    status: string;
+    source: string;
+    actor: string;
+    retry_of: string;
+    created: string;
+    started: string;
+    finished: string;
+    duration_seconds: number | null;
+    desired_commit: string;
+    current_commits: string[];
+    frozen_roster: string[];
+    transitions: Proof[];
+    node_evidence: Proof[];
+    diagnosis: Proof[];
+    detail: string;
+    node_summary: Record<'expected' | 'proven' | 'reported' | 'failed' | 'dispatched' | 'other', number>;
+}
+export interface Collector<T> {
+    status: string;
+    observed_at: string;
+    stale_after: string;
+    reason: string;
+    data: T | null;
+}
+export interface PlatformSnapshot {
+    deployments: Collector<{
+        items: PlatformAttempt[];
+        limit: number;
+        desired_commit: string;
+        desired_deployment: string;
+        currently_serving: {
+            deployment: string;
+            sha: string;
+            framework_version: string;
+            converged_at: string;
+        } | null;
+        coordination: {
+            state: string;
+            deployment: string;
+            sha: string;
+            at: string;
+        };
+        framework_pin: {
+            mode: string;
+            resolved: string;
+        };
+    }>;
+    api: Collector<{
+        version: string;
+        commit: string;
+    }>;
+}
+export interface Bootstrap {
+    groups: {
+        id: number;
+        name: string;
+        can_manage_dns: boolean;
+    }[];
+    can_create_webapp_group: boolean;
+    setup: boolean;
+}
+export interface DeploymentStatus {
+    deployment: number;
+    webapp: number;
+    release: number;
+    version: string;
+    status: string;
+    terminal: boolean;
+    success: boolean;
+    detail: string;
+    created: string;
+    started: string;
+    finished: string;
+    targets: Proof[];
+    rollback_targets: Proof[];
+}
+export interface CreateProfile {
+    operation_id: string;
+    group?: number;
+    group_intent?: 'new';
+    slug: string;
+    display_name: string;
+    environment: string;
+    bucket: string;
+    github_repository: string;
+    deployment_ref: string;
+    build_output: string;
+}
+export interface OnboardingOperation {
+    operation_id: string;
+    group: {
+        id: number;
+        name: string;
+    };
+    status: string;
+    cursor: string;
+    revision: number;
+    profile: {
+        slug: string;
+        display_name: string;
+    };
+    evidence: {
+        app: {
+            status: string;
+        };
+        address: {
+            status: string;
+            hostname: string;
+        };
+        github: {
+            status: string;
+            reason: string;
+        };
+        verify: {
+            status: string;
+            detail: string;
+        };
+    };
+    activity: {
+        message: string;
+        kind: string;
+        at: string;
+    }[];
+    resources: {
+        webapp: number | null;
+    };
+    next_attempt_at: string;
+    last_error: string;
+    modified: string;
+}
+export interface OnboardingOptions {
+    buckets: string[];
+    environments: string[];
+    destination: boolean;
+    destination_error: string;
+    apps_domain: {
+        id: number;
+        name: string;
+    } | null;
+    apps_domain_error: string;
+    github_connected: boolean;
+}
+export interface AddressPrecheck {
+    verdict: string;
+    hostname: string;
+    reason: string;
+    domain: {
+        id: number;
+        name: string;
+    } | null;
+    label: string;
+}
+export interface ManifestEntry {
+    path: string;
+    sha256: string;
+    size: number;
+}
+export type ApiAction = 'retry' | 'verify' | 'converge';
+/** Registered router paths supplied by the host, already checked against its section roster. */
+export interface DeploymentsDestinations {
+    domains?: string;
+    serving?: string;
+}

package/src/admin/deployments/upload.ts

@@ -0,0 +1,53 @@
+import type { ManifestEntry } from './types';
+export function normalizeUploadPath(path: string): string { const p = path.normalize('NFC'); if (!p || p.length > 1024 || p.startsWith('/') || p.includes('\\') || /[\u0000-\u001f]/.test(p) || p.split('/').some(x => !x || x === '.' || x === '..') || /^[a-z]:/i.test(p))
+    throw new Error('Choose normalized relative file paths without traversal or empty segments'); return p; }
+export async function buildManifest(files: File[], signal?: AbortSignal, limits = { files: 5000, bytes: 1024 ** 3 }): Promise<ManifestEntry[]> { if (!files.length || files.length > limits.files || files.reduce((n, f) => n + f.size, 0) > limits.bytes)
+    throw new Error(`Select 1–${limits.files} files, at most ${limits.bytes} bytes. This installation may impose lower limits.`); const seen = new Set<string>(), manifest: ManifestEntry[] = []; for (const file of files) {
+    signal?.throwIfAborted();
+    const path = normalizeUploadPath(file.webkitRelativePath || file.name);
+    if (seen.has(path))
+        throw new Error(`Duplicate normalized file path: ${path}`);
+    seen.add(path);
+    const hash = await crypto.subtle.digest('SHA-256', await file.arrayBuffer());
+    signal?.throwIfAborted();
+    manifest.push({
+        path, sha256: [...new Uint8Array(hash)].map(x => x.toString(16).padStart(2, '0')).join(''), size: file.size
+    });
+} return manifest.sort((a, b) => a.path.localeCompare(b.path)); }
+export function manifestEqual(a: ManifestEntry[], b: ManifestEntry[]): boolean { return JSON.stringify(a) === JSON.stringify(b); }
+export async function putReleaseFiles(files: File[], manifest: ManifestEntry[], uploads: {
+    path: string;
+    url: string;
+    headers: Record<string, string>;
+}[], signal: AbortSignal, onProgress: (n: number) => void, put: typeof fetch = fetch): Promise<void> { if (uploads.length === 0)
+    return; if (uploads.length !== manifest.length)
+    throw new Error('Incomplete signed upload manifest'); const source = new Map(files.map(f => [normalizeUploadPath(f.webkitRelativePath || f.name), f])), seen = new Set<string>(); let completed = 0; for (const upload of uploads) {
+    signal.throwIfAborted();
+    const entry = manifest.find(x => x.path === upload.path), file = source.get(upload.path);
+    if (!entry || !file || seen.has(upload.path))
+        throw new Error('Upload path does not match the selected manifest');
+    seen.add(upload.path);
+    let url: URL;
+    try {
+        url = new URL(upload.url);
+    }
+    catch {
+        throw new Error('Invalid storage upload destination');
+    }
+    if (url.protocol !== 'https:' || url.username || url.password)
+        throw new Error('Storage requires an HTTPS signed destination');
+    const expected = btoa(String.fromCharCode(...Uint8Array.from(entry.sha256.match(/../g) ?? [], x => parseInt(x, 16))));
+    if (Object.keys(upload.headers).length !== 1 || upload.headers['x-amz-checksum-sha256'] !== expected)
+        throw new Error('Storage checksum headers do not match this file');
+    try {
+        const response = await put(url.href, {
+            method: 'PUT', headers: upload.headers, body: file, credentials: 'omit', redirect: 'error', referrerPolicy: 'no-referrer', signal
+        });
+        if (!response.ok)
+            throw new Error('upload refused');
+    }
+    catch {
+        throw new Error('Storage upload failed. Check the bucket CORS policy permits anonymous PUT and x-amz-checksum-sha256 from this Admin origin. Completion was not sent.');
+    }
+    onProgress(++completed);
+} }

package/src/admin/deployments/useDeploymentObservation.ts

@@ -0,0 +1,104 @@
+import { useCallback, useEffect, useMemo, useRef, useLayoutEffect, useState } from 'react';
+import { getAuthSessionRevision, useAuthSnapshot, useMe } from '../../client/runtime';
+import { backendGlobalCan } from '../fleet/access';
+import { assertOwner, deploymentOwner, ownerKey, type DeploymentOwner } from './permissions';
+/** One identity/scope lifetime, including React's development-only effect replay. */
+export function useDeploymentOwner() {
+    const auth = useAuthSnapshot(), me = useMe(), revision = getAuthSessionRevision();
+    const base = useMemo(() => deploymentOwner(), [auth.uid, auth.authenticated, revision]);
+    const authority = [me.data?.is_active !== false, ...[
+        'view_platform', 'manage_platform', 'admin', 'view_dns', 'manage_dns',
+        'security', 'manage_webapp', 'view_admin', 'manage_users', 'manage_settings',
+    ].map(permission => backendGlobalCan(me.data, permission))].join(':');
+    const key = `${ownerKey(base)}:${authority}`;
+    const lifetime = useMemo(() => ({ controller: new AbortController() }), [key]);
+    const [, renderLiveSignal] = useState(0);
+    useLayoutEffect(() => {
+        // StrictMode replays setup after cleanup without replacing query keys.
+        // Renew this same scope before its read effects resume, and publish the
+        // new signal to consumers that capture a concrete signal during render.
+        if (lifetime.controller.signal.aborted) {
+            lifetime.controller = new AbortController();
+            renderLiveSignal(generation => generation + 1);
+        }
+        const mountedController = lifetime.controller;
+        return () => mountedController.abort();
+    }, [lifetime]);
+    // Query callbacks from the first render must see the controller belonging
+    // to the current setup, rather than a permanently aborted render snapshot.
+    // A genuine unmount has no following setup; its lifetime remains aborted.
+    // A different actor/session/authority receives a separate lifetime object.
+    const owner = useMemo<DeploymentOwner>(() => ({
+        ...base,
+        get signal() { return lifetime.controller.signal; },
+    }), [base, lifetime]);
+    return { owner, signal: lifetime.controller.signal, key };
+}
+export interface Observation<T> {
+    value: T | null;
+    state: 'idle' | 'observing' | 'stopped' | 'terminal' | 'error';
+    observedAt: number | null;
+    refresh: () => void;
+}
+/** Known identity only; bounded, owner-fenced, hidden/blur aware; refresh only reads. */
+export function useDeploymentObservation<T>(owner: DeploymentOwner, identity: string | null, read: (signal: AbortSignal) => Promise<T>, terminal: (value: T) => boolean, pollable: (value: T) => boolean = () => true, budgetMs = 60000, intervalMs = 2000): Observation<T> {
+    const [generation, setGeneration] = useState(0), [value, setValue] = useState<T | null>(null), [state, setState] = useState<Observation<T>['state']>('idle'), [observedAt, setObservedAt] = useState<number | null>(null);
+    const current = useRef({
+        read, terminal, pollable
+    });
+    current.current = {
+        read, terminal, pollable
+    };
+    const key = ownerKey(owner), slot = `${key}:${identity}:${generation}`;
+    const seen = useRef('');
+    useEffect(() => {
+        seen.current = slot;
+        if (!identity) {
+            setValue(null);
+            setState('idle');
+            return;
+        }
+        const controller = new AbortController();
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        let cancelled = false;
+        const started = Date.now();
+        setValue(null);
+        setObservedAt(null);
+        setState('observing');
+        const tick = async () => { if (cancelled)
+            return; if (Date.now() - started >= budgetMs) {
+            setState('stopped');
+            return;
+        } if (typeof document !== 'undefined' && (document.visibilityState === 'hidden' || !document.hasFocus())) {
+            timer = setTimeout(tick, intervalMs);
+            return;
+        } try {
+            assertOwner(owner, controller.signal);
+            const next = await current.current.read(controller.signal);
+            assertOwner(owner, controller.signal);
+            if (cancelled)
+                return;
+            setValue(next);
+            setObservedAt(Date.now());
+            if (current.current.terminal(next)) {
+                setState('terminal');
+                return;
+            }
+            if (!current.current.pollable(next)) {
+                setState('stopped');
+                return;
+            }
+            timer = setTimeout(tick, intervalMs);
+        }
+        catch {
+            if (!cancelled)
+                setState('error');
+        } };
+        void tick();
+        return () => { cancelled = true; controller.abort(); clearTimeout(timer); };
+    }, [key, owner.signal, identity, generation, budgetMs, intervalMs]);
+    const matching = seen.current === slot;
+    return {
+        value: matching ? value : null, state: matching ? state : identity ? 'observing' : 'idle', observedAt: matching ? observedAt : null, refresh: useCallback(() => setGeneration(n => n + 1), [])
+    };
+}

package/src/admin/dns/CertificateDetail.tsx

@@ -6,6 +6,9 @@ import { revokeCertificate, useAcmeDelegations, useDnsCapabilities } from './api
 import {
     canInspectHouseCertificate, certificateStatusTone, deriveCertificateRenewalHealth,
 } from './certificate-data';
+import { SharedValidationPanel } from './SharedValidationPanel';
+import { openSharedValidation } from './SharedValidationDialog';
+import { useValidationPlan } from './shared-validation-api';
 import { CertificateModel, DNS_MANAGE_PERMISSIONS, type CertificateRow, type DomainRow } from './models';
 
 function healthLabel(row: CertificateRow): string {
@@ -23,6 +26,7 @@ function AllowedCertificateDetail({ id, domain, onClose }: { id: number; domain:
     const groupId = typeof domain.group === 'number' ? domain.group : domain.group?.id ?? null;
     const capabilities = useDnsCapabilities(groupId);
     const delegations = useAcmeDelegations(domain.id);
+    const shared = useValidationPlan({ domain: domain.id });
     const [revoking, setRevoking] = useState(false);
     const certificate = query.data;
     if (query.isPending) return <div className="modal-pad dim">Loading certificate…</div>;
@@ -89,17 +93,18 @@ function AllowedCertificateDetail({ id, domain, onClose }: { id: number; domain:
             </div> },
             { key: 'delegation', label: 'Delegation', icon: 'bi-diagram-2', render: () => <div className="dns-cert-detail-section">
                 <Eyebrow>DNS-01 routing</Eyebrow>
-                {delegations.isPending ? <p className="dim">Loading delegation status…</p> : delegation ? <>
+                {delegations.isPending ? <p className="dim">Loading delegation status…</p> : delegations.error ? <p className="dns-errors">Delegation status could not be loaded. DNS routing is unknown.</p> : delegation ? <>
                     <FlatRow label="State"><Badge tone={delegation.state === 'verified' ? 'success' : delegation.state === 'broken' ? 'danger' : 'warning'}>{delegation.state}</Badge></FlatRow>
                     <FlatRow label="Source"><code>{delegation.source ?? '—'}</code></FlatRow>
                     <FlatRow label="Target"><code>{delegation.target ?? '—'}</code></FlatRow>
                     {delegation.last_error_code && <FlatRow label="Error code"><code>{delegation.last_error_code}</code></FlatRow>}
                     {delegation.verified_at && delegation.state === 'broken' && <div className="dns-errors">This delegation is sticky after verification. Repair it; issuance will not fall back to direct provider DNS.</div>}
-                </> : <p className="dim">No delegated ACME route is attached; provider DNS is used directly.</p>}
+                </> : <p className="dim">{shared.data?.connection?.mode === 'shared' ? 'An explicit shared connection controls validation; direct DNS fallback is disabled.' : shared.error || shared.loading ? 'Shared routing status is unavailable; no direct-routing claim can be made.' : 'No legacy delegated ACME route is attached.'}</p>}
+                <SharedValidationPanel domain={domain} />
             </div> },
         ]}
         initialSection="overview"
-        contextMenu={canManage && certificate.status === 'active' ? [{ label: revoking ? 'Revoking…' : 'Revoke certificate', icon: 'bi-x-octagon', danger: true, onSelect: () => void revoke() }] : []}
+        contextMenu={[...(canManage && shared.data?.capabilities.group_choices ? [{ label: 'Set up shared validation', icon: 'bi-diagram-2', onSelect: () => void openSharedValidation(domain) }] : []), ...(canManage && certificate.status === 'active' ? [{ label: revoking ? 'Revoking…' : 'Revoke certificate', icon: 'bi-x-octagon', danger: true, onSelect: () => void revoke() }] : [])]}
         menuContext={certificate}
         onClose={onClose}
     />;