portal-mojo 0.2.20 → 0.2.21

package/src/admin/deployments/api.ts

@@ -0,0 +1,158 @@
+import { mojoCall, isReauthRequired, requestFreshAuth } from '../../client/runtime';
+import { MojoError } from '../../client/errors';
+import { appActionsRefused, refuseAppActions } from './authority-state';
+import type { FetchOpts } from '../../client/client';
+import { projectAttempt, projectBootstrap, projectDeployment, projectOperation, projectOptions, projectPlatform, projectPlatformAttempt, projectPrecheck, projectRelease, projectSummaries, projectSummary, projectWebAppObject, record, text, positiveId, list, uuid } from './sanitize';
+import { assertOwner, webAppAuthority, type DeploymentOwner } from './permissions';
+import { appUnsettled, receiptsFor, saveReceipt, singleFlight, type ActionReceipt } from './receipts';
+import type { BackendGlobalUser } from '../fleet/access';
+import type { WebAppObject } from './types';
+import type { ApiAction, CreateProfile, ManifestEntry, OnboardingOperation } from './types';
+const ROOT = '/api/edge';
+function privateError(error: unknown): Error { if (error instanceof DOMException && error.name === 'AbortError')
+    return new DOMException('Deployment owner changed', 'AbortError'); const status = error && typeof error === 'object' && 'status' in error && typeof error.status === 'number' ? error.status : 0; return new MojoError(status === 440 ? 'Fresh authentication required' : status === 403 ? 'Deployment observation or action denied' : 'Deployment request unavailable; outcome may be unknown', status); }
+export async function safeCall<T>(owner: DeploymentOwner, path: string, project: (v: unknown) => T, opts: FetchOpts = {}): Promise<T> { assertOwner(owner, opts.signal); try {
+    const body = await mojoCall(path, {
+        ...opts, unscoped: true, beforeSend: () => { assertOwner(owner, opts.signal); opts.beforeSend?.(); }
+    });
+    assertOwner(owner, opts.signal);
+    return project(body.data);
+}
+catch (error) {
+    throw privateError(error);
+} }
+export const getBootstrap = (o: DeploymentOwner, signal?: AbortSignal) => safeCall(o, '/api/account/admin/bootstrap', projectBootstrap, { signal });
+export const getPlatform = (o: DeploymentOwner, signal?: AbortSignal) => safeCall(o, '/api/account/admin/platform', projectPlatform, { params: { sections: 'deployments,api' }, signal });
+export const getWebApps = (o: DeploymentOwner, signal?: AbortSignal) => safeCall(o, `${ROOT}/webapp/summaries`, projectSummaries, { signal });
+export const getSummary = (o: DeploymentOwner, id: number, signal?: AbortSignal) => safeCall(o, `${ROOT}/webapp/summary`, v => { const s = projectSummary(v); if (s.webapp.id !== id)
+    throw new Error('App identity changed'); return s; }, { params: { webapp: id }, signal });
+export const getWebApp = (o: DeploymentOwner, id: number, signal?: AbortSignal) => safeCall(o, `${ROOT}/webapp/${id}`, v => { const s = projectWebAppObject(v); if (s.id !== id || !s.group.id)
+    throw new Error('App ownership unavailable'); return s; }, { params: { graph: 'default' }, signal });
+export const getMember = (o: DeploymentOwner, group: number, signal?: AbortSignal) => safeCall(o, `/api/group/${group}/member`, v => { const r = record(v), p = record(r.permissions); return { permissions: Object.fromEntries(['view_dns', 'manage_dns', 'security', 'manage_webapp'].filter(k => Object.hasOwn(p, k)).map(k => [k, p[k]])) }; }, { signal });
+export async function resolveAppAuthority(o: DeploymentOwner, user: BackendGlobalUser | undefined, app: WebAppObject, kind: 'custom' | 'workflow' | 'release', signal?: AbortSignal) { const base = webAppAuthority(user, app); return base[kind] ? base : webAppAuthority(user, app, await getMember(o, app.group.id, signal)); }
+export async function getHistory(o: DeploymentOwner, app: number, kind: 'release' | 'deployment', start = 0, signal?: AbortSignal, size = kind === 'release' ? 25 : 15) { const body = await mojoCall(`${ROOT}/${kind}`, {
+    unscoped: true, signal, params: {
+        webapp: app, graph: 'list', sort: '-created', start, size: Math.max(1, Math.min(100, Math.floor(size)))
+    }, beforeSend: () => assertOwner(o, signal)
+}).catch(error => { throw privateError(error); }); assertOwner(o, signal); return { items: list(body.data, Math.max(1, Math.min(100, Math.floor(size)))).map(v => kind === 'release' ? projectRelease(v) : projectAttempt(v)), count: typeof body.count === 'number' ? body.count : 0 }; }
+export const getDeployment = (o: DeploymentOwner, id: number, app: number, release: number, signal?: AbortSignal) => safeCall(o, `${ROOT}/release/deployment/${id}`, v => { const d = projectDeployment(v); if (d.deployment !== id || d.webapp !== app || d.release !== release)
+    throw new Error('Deployment identity mismatch'); return d; }, { signal });
+/** Generic graphs omit the parent: bind the read through both exact server filters. */
+export const getAttempt = (o: DeploymentOwner, id: number, app: number, signal?: AbortSignal) => safeCall(o, `${ROOT}/deployment`, v => {
+    const rows = list(v, 2); const row = projectAttempt(rows[0]);
+    if (!positiveId(id) || !positiveId(app) || rows.length !== 1 || row.id !== id || !row.release?.id) throw new Error('Attempt unavailable in this WebApp');
+    return row;
+}, { params: { webapp: app, id, graph: 'default', start: 0, size: 1 }, signal });
+export const getRelease = (o: DeploymentOwner, id: number, app: number, signal?: AbortSignal) => safeCall(o, `${ROOT}/release`, v => {
+    const rows = list(v, 2); const row = projectRelease(rows[0]);
+    if (!positiveId(id) || !positiveId(app) || rows.length !== 1 || row.id !== id) throw new Error('Release unavailable in this WebApp');
+    return row;
+}, { params: { webapp: app, id, graph: 'default', start: 0, size: 1 }, signal });
+export async function write<T>(o: DeploymentOwner, r: ActionReceipt, path: string, body: Record<string, unknown>, project: (v: unknown) => T, signal?: AbortSignal): Promise<T> { assertOwner(o, signal); if (appActionsRefused(o, r.app))
+    throw new Error('App actions were refused. Refresh safe state and establish a new session before another mutation.'); if (appUnsettled(o, r.app, r.key))
+    throw new Error('Another app operation has an unknown outcome. Refresh its exact status before continuing.'); if (['rollback', 'profile'].includes(r.kind) && r.submitted && !r.settled)
+    throw new Error(r.kind === 'profile' ? 'Settings save outcome is unknown. Reload saved settings before making another save.' : 'Rollback delivery is unknown. Observe summary/history; no rollback was replayed.'); saveReceipt({
+    ...r, submitted: true, submittedAt: r.submittedAt ?? Date.now()
+}); return singleFlight(`${o.actor}:${r.app || r.key}`, async () => { try {
+    return await safeCall(o, path, project, {
+        method: 'POST', body, signal, ...(r.kind === 'api' ? { idempotencyKey: r.operation } : {})
+    });
+}
+catch (error) {
+    if (isReauthRequired(error)) {
+        saveReceipt({ ...r, submitted: false, ...(r.kind === 'profile' ? { settled: true } : {}) });
+        await requestFreshAuth();
+        throw new Error('Authentication renewed or cancelled. Refresh authoritative state and explicitly confirm again; nothing was replayed.');
+    }
+    if (error instanceof MojoError && error.status === 403 && r.app)
+        refuseAppActions(o, r.app);
+    if (error && typeof error === 'object' && 'status' in error && [400, 401, 403, 404, 409, 440].includes(Number(error.status)))
+        saveReceipt({ ...r, settled: r.kind==='upload'&&r.uploadPhase==='completion_submitted'?false:true });
+    throw new Error(error instanceof DOMException && error.name === 'AbortError' ? 'Session or view changed. The submitted operation may persist. Resume to reconcile.' : 'The operation was refused or delivery is uncertain. Refresh authoritative state before retrying.');
+} }); }
+export type WebAppProfilePatch = { display_name: string; environment: string; github_repository: string; deployment_ref: string; build_output: string };
+export function saveWebAppProfile(o: DeploymentOwner, r: ActionReceipt, app: WebAppObject, patch: WebAppProfilePatch, signal?: AbortSignal) {
+    const fields = ['display_name', 'environment', 'github_repository', 'deployment_ref', 'build_output'] as const;
+    if (r.kind !== 'profile' || r.app !== app.id || Object.keys(patch).some(key => !fields.includes(key as typeof fields[number])) || fields.some(key => typeof patch[key] !== 'string')) throw new Error('Unsupported WebApp profile fields');
+    return write(o, r, `${ROOT}/webapp/${app.id}`, Object.fromEntries(fields.map(key => [key, patch[key]])), v => {
+        const saved = projectWebAppObject(v);
+        if (saved.id !== app.id || saved.group.id !== app.group.id) throw new Error('WebApp ownership changed');
+        return saved;
+    }, signal);
+}
+export async function recoverApi(o: DeploymentOwner, r: ActionReceipt, id: string, action: ApiAction, signal?: AbortSignal) { if (!uuid(id))
+    throw new Error('Invalid deployment ID'); return write(o, r, `/api/account/admin/platform/deploy/${action}`, { deployment: id }, v => { const d = projectPlatformAttempt(record(v).deployment); if (!d.id || (action !== 'retry' && d.id !== id))
+    throw new Error('Deployment identity mismatch'); return d; }, signal); }
+export const rollback = (o: DeploymentOwner, r: ActionReceipt, app: number, release: number, group: number, signal?: AbortSignal) => write(o, r, `${ROOT}/webapp/rollback`, {
+    webapp: app, release, group
+}, v => { const d = projectDeployment(v); if (!d.deployment || d.webapp !== app || d.release !== release)
+    throw new Error('Rollback identity mismatch'); return d; }, signal);
+export const getOptions = (o: DeploymentOwner, intent: {
+    group: number;
+} | {
+    group_intent: 'new';
+}, signal?: AbortSignal) => safeCall(o, `${ROOT}/webapp/onboarding/options`, projectOptions, { params: intent, signal });
+export const precheckAddress = (o: DeploymentOwner, intent: {
+    group: number;
+} | {
+    group_intent: 'new';
+}, url: string, signal?: AbortSignal) => safeCall(o, `${ROOT}/webapp/onboarding/precheck`, projectPrecheck, { params: { ...intent, url }, signal });
+export const getOperation = (o: DeploymentOwner, id: string, signal?: AbortSignal) => safeCall(o, `${ROOT}/webapp/onboarding/detail`, v => { const p = projectOperation(v); if (p.operation_id !== id)
+    throw new Error('Operation identity mismatch'); return p; }, { params: { operation: id }, signal });
+export const createApp = (o: DeploymentOwner, r: ActionReceipt, p: CreateProfile, signal?: AbortSignal) => write(o, r, `${ROOT}/webapp/onboarding/create`, { ...p }, v => { const operation = projectOperation(record(v).operation); if (operation.operation_id !== p.operation_id)
+    throw new Error('Operation identity mismatch'); return operation; }, signal);
+export const chooseOnboarding = (o: DeploymentOwner, r: ActionReceipt, p: OnboardingOperation, choice: Record<string, unknown>, signal?: AbortSignal) => write(o, r, `${ROOT}/webapp/onboarding/choose`, {
+    operation: p.operation_id, revision: p.revision, step: p.cursor, choice
+}, v => { const next = projectOperation(v); if (next.operation_id !== p.operation_id)
+    throw new Error('Operation identity mismatch'); return next; }, signal);
+export const cancelOnboarding = (o: DeploymentOwner, r: ActionReceipt, id: string, signal?: AbortSignal) => write(o, r, `${ROOT}/webapp/onboarding/cancel`, { operation: id }, projectOperation, signal);
+export const getWorkflow = (o: DeploymentOwner, app: number, group: number, signal?: AbortSignal) => safeCall(o, `${ROOT}/webapp/onboarding/workflow`, v => { const r = record(v); return {
+    filename: '.github/workflows/deploy-webapp.yml', repository: text(r.repository), yaml: text(r.yaml, 32000)
+}; }, {
+    method: 'POST', body: { webapp: app, group }, signal
+}).catch(async (error) => { if (isReauthRequired(error)) {
+    await requestFreshAuth();
+    throw new Error('Authentication prompted. Review and explicitly generate the workflow again; nothing was replayed.');
+} throw error; });
+/** Secret never crosses a Query/Mutation cache or error object. */
+export const changeKey = (o: DeploymentOwner, r: ActionReceipt, app: number, group: number, action: 'mint' | 'rotate' | 'revoke', signal?: AbortSignal) => write(o, r, `${ROOT}/webapp/${action === 'revoke' ? 'revoke_key' : 'link_key'}`, {
+    webapp: app, group, operation_id: r.operation, ...(action === 'revoke' ? {} : { action })
+}, v => { const x = record(v); if (positiveId(x.webapp) !== app)
+    throw new Error('Key receipt identity mismatch'); return { token: typeof x.token === 'string' ? x.token.slice(0, 8192) : null, replayed: x.replayed === true }; }, signal);
+export const getKeyStatus = (o: DeploymentOwner, app: number, group: number, signal?: AbortSignal) => safeCall(o, `${ROOT}/webapp/key_status`, v => { const r = record(v), s = record(r.status); if (positiveId(r.webapp) !== app)
+    throw new Error('Key identity mismatch'); return { linked: s.linked === true, active: s.active === true }; }, { params: { webapp: app, group }, signal });
+export const getHealth = (o: DeploymentOwner, app: number, group: number, signal?: AbortSignal) => safeCall(o, `${ROOT}/webapp/health`, v => { const r = record(v); if (positiveId(r.webapp) !== app)
+    throw new Error('Health identity mismatch'); return {
+    status: text(r.status) || 'unknown', detail: text(r.detail, 500), checked: text(r.checked)
+}; }, { params: { webapp: app, group }, signal });
+export async function registerUpload(o: DeploymentOwner, r: ActionReceipt, app: number, group: number, version: string, manifest: ManifestEntry[], signal?: AbortSignal) { const current=receiptsFor(o).find(x=>x.key===r.key)??r;if(['completion_submitted','observing'].includes(current.uploadPhase??''))throw new Error('Completion was already submitted. Reconcile its exact deployment before a new explicit deployment decision.');return write(o, r, `${ROOT}/release`, {
+    webapp: app, group, version, manifest
+}, v => { const d = record(v); if (!positiveId(d.release) || text(d.version) !== version)
+    throw new Error('Release identity mismatch'); return {
+    release: positiveId(d.release), status: text(d.status), uploads: list(d.uploads, 5000).map(v => { const u = record(v), h = record(u.headers); return {
+        path: text(u.path, 1024), url: text(u.url, 8192), headers: { 'x-amz-checksum-sha256': text(h['x-amz-checksum-sha256'], 64) }
+    }; })
+}; }, signal); }
+/** Completion is a deployment request, not an idempotent verification read. */
+export async function completeUpload(o:DeploymentOwner,r:ActionReceipt,release:number,app:number,group:number,signal?:AbortSignal){
+ return singleFlight(`upload-completion:${o.actor}:${app}`,async()=>{
+  const current=receiptsFor(o).find(x=>x.key===r.key)??r;
+  if(['completion_submitted','observing'].includes(current.uploadPhase??''))throw new Error('Completion delivery is unsettled or already observed. Reconcile before consenting to another deployment.');
+  if(current.release!==release||current.app!==app)throw new Error('Upload receipt identity changed');
+  const history=await getHistory(o,app,'deployment',0,signal,100);
+  const submitted=saveReceipt({...current,uploadPhase:'completion_submitted',completionSubmittedAt:Date.now(),completionBaseline:history.items.map(x=>x.id)});
+  const result=await write(o,submitted,`${ROOT}/release/complete`,{release,group},v=>{const d=record(v);if(positiveId(d.release)!==release||positiveId(d.webapp)!==app||!positiveId(d.deployment))throw new Error('Completion identity mismatch');return {deployment:positiveId(d.deployment),release,app};},signal);
+  saveReceipt({...submitted,uploadPhase:'observing',deployment:result.deployment});return result;
+ });
+}
+export async function reconcileUploadCompletion(o:DeploymentOwner,r:ActionReceipt,signal?:AbortSignal){
+ const current=receiptsFor(o).find(x=>x.key===r.key)??r;
+ if(current.kind!=='upload'||!current.release||!['completion_submitted','observing'].includes(current.uploadPhase??''))throw new Error('No submitted completion receipt is available');
+ const [summary,history]=await Promise.all([getSummary(o,current.app,signal),getHistory(o,current.app,'deployment',0,signal,100)]);
+ const candidates=history.items.filter(x=>{const a=x as import('./types').Attempt;return !!a.release&&a.release.id===current.release&&a.release.version===current.target&&!(current.completionBaseline??[]).includes(a.id);});
+ const id=current.deployment??(candidates.length===1?candidates[0]!.id:0);
+ const status=id?await getDeployment(o,id,current.app,current.release,signal):null;
+ const signature=JSON.stringify([summary.current_release?.id??null,history.items.map(x=>[x.id,x.status,(x as import('./types').Attempt).release?.id])]);
+ if(status)saveReceipt({...current,uploadPhase:'observing',deployment:status.deployment,settled:status.terminal});
+ return {receipt:receiptsFor(o).find(x=>x.key===current.key)!,status,signature};
+}

package/src/admin/deployments/authority-state.ts

@@ -0,0 +1,9 @@
+import { useSyncExternalStore } from 'react';
+import { ownerKey, type DeploymentOwner } from './permissions';
+const refused = new Set<string>();
+const listeners = new Set<() => void>();
+const key = (owner: DeploymentOwner, app: number) => `${ownerKey(owner)}:${app}`;
+export function refuseAppActions(owner: DeploymentOwner, app: number): void { refused.add(key(owner, app)); for (const fn of listeners)
+    fn(); }
+export function appActionsRefused(owner: DeploymentOwner, app: number): boolean { return refused.has(key(owner, app)); }
+export function useAppActionsRefused(owner: DeploymentOwner, app: number): boolean { return useSyncExternalStore(fn => { listeners.add(fn); return () => listeners.delete(fn); }, () => appActionsRefused(owner, app), () => true); }

package/src/admin/deployments/deployment-state.ts

@@ -0,0 +1,13 @@
+import type { ApiAction, PlatformAttempt, Release } from './types';
+export function apiActions(status: string): ApiAction[] { switch (status) {
+    case 'failed': return ['retry', 'verify'];
+    case 'verified':
+    case 'partial':
+    case 'unknown': return ['verify', 'converge'];
+    case 'converged': return ['verify'];
+    default: return [];
+} }
+export function rollbackEligible(release: Release, current: Release | null): boolean { return release.id > 0 && release.id !== current?.id && ['uploaded', 'live', 'superseded'].includes(release.status); }
+export function platformProof(attempt: PlatformAttempt): string { const n = attempt.node_summary; if (attempt.status === 'converged' && n.expected > 0 && n.proven === n.expected)
+    return `${n.proven}/${n.expected} restart proofs at observation`; return `${n.proven}/${n.expected} restart proofs; ${n.reported} reported, ${n.failed} failed (${attempt.status})`; }
+export function deploymentTone(status: string): string { return ['live', 'converged'].includes(status) ? 'ok' : ['failed', 'rolled_back'].includes(status) ? 'bad' : ['requested', 'queued', 'deploying', 'canary', 'fleet', 'partial', 'verified'].includes(status) ? 'warn' : 'dim'; }

package/src/admin/deployments/index.ts

@@ -0,0 +1,4 @@
+export { DeploymentsPage } from './DeploymentsPage';
+export { WebAppDetail } from './WebAppDetail';
+export { DEPLOYMENTS_PERMISSIONS } from './permissions';
+export type { WebAppSummary, PlatformAttempt, OnboardingOperation, DeploymentStatus, DeploymentsDestinations } from './types';

package/src/admin/deployments/onboarding-state.ts

@@ -0,0 +1,11 @@
+import type { OnboardingOperation } from './types';
+export const onboardingTerminal = (o: OnboardingOperation) => ['succeeded', 'failed', 'cancelled'].includes(o.status);
+export function onboardingPollable(o: OnboardingOperation): boolean { return !onboardingTerminal(o) && ['app', 'address', 'github', 'verify'].includes(o.cursor) && (o.status === 'active' || (o.status === 'waiting' && !!o.next_attempt_at)); }
+export function onboardingGeneration(o: OnboardingOperation): string { return `${o.operation_id}:${o.revision}:${o.cursor}`; }
+export function managedChoice(o: OnboardingOperation, domain: number, label: string): Record<string, unknown> | null { switch (o.cursor) {
+    case 'app': return {};
+    case 'address': return domain > 0 && /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label) ? { domain, label } : null;
+    case 'github': return { skip: true };
+    case 'verify': return {};
+    default: return null;
+} }

package/src/admin/deployments/permissions.ts

@@ -0,0 +1,37 @@
+import { backendGlobalCan, type BackendGlobalUser } from '../fleet/access';
+import { decodeJwt } from '../../client/jwt';
+import { getAccessToken, getAuthSessionRevision, getAuthSnapshot } from '../../client/auth';
+import type { Bootstrap, WebAppObject } from './types';
+export const DEPLOYMENTS_PERMISSIONS = ['sys.view_platform', 'sys.manage_platform', 'sys.admin', 'sys.view_dns', 'sys.manage_dns', 'sys.security'];
+const active = (u: BackendGlobalUser | null | undefined) => !!u && (!('is_active' in u) || u.is_active !== false);
+export const canReadApi = (u: BackendGlobalUser | null | undefined) => active(u) && backendGlobalCan(u, ['view_platform', 'manage_platform', 'admin']);
+export const canRecoverApi = (u: BackendGlobalUser | null | undefined) => active(u) && backendGlobalCan(u, ['manage_platform', 'admin']);
+export const canReadWebApps = (u: BackendGlobalUser | null | undefined) => active(u) && backendGlobalCan(u, ['view_dns', 'manage_dns', 'security']);
+export const canReadBootstrap = (u: BackendGlobalUser | null | undefined) => active(u) && backendGlobalCan(u, ['view_admin', 'manage_users', 'manage_settings', 'admin']);
+export function isInteractive(): boolean { const s = getAuthSnapshot(), c = decodeJwt(getAccessToken()); return s.authenticated && !!c && c.credential_kind !== 'api_key' && c.credential_kind !== 'group_scoped_token'; }
+export interface DeploymentOwner {
+    actor: string;
+    origin: string;
+    session: number;
+    signal?: AbortSignal;
+}
+export function deploymentOwner(): DeploymentOwner { return {
+    actor: getAuthSnapshot().uid ?? '', origin: typeof window === 'undefined' ? '' : window.location.origin, session: getAuthSessionRevision()
+}; }
+export function ownerKey(o: DeploymentOwner): string { return `${o.origin}:${o.actor}:${o.session}`; }
+export function assertOwner(o: DeploymentOwner, signal?: AbortSignal): void { signal?.throwIfAborted(); o.signal?.throwIfAborted(); const now = deploymentOwner(); if (!getAuthSnapshot().authenticated || !o.actor || ownerKey(o) !== ownerKey(now))
+    throw new DOMException('Session changed; refresh and review again', 'AbortError'); }
+/** SAVE_PERMS is the first configured RestMeta clause for writes; VIEW is read-only. */
+export function webAppAuthority(user: BackendGlobalUser | null | undefined, app: WebAppObject, member?: {
+    permissions?: Record<string, unknown>;
+} | null) {
+    const local = member ? { permissions: member.permissions } : null;
+    const can = (grants: readonly string[]) => backendGlobalCan(user, grants) || backendGlobalCan(local, grants);
+    const object = active(user) && app.id > 0 && app.group.id > 0;
+    const view = object && can(['view_dns', 'manage_dns', 'security']);
+    const save = object && can(['manage_dns', 'security']);
+    return {
+        read: view, custom: save && can(['manage_webapp']), release: save, workflow: active(user) && app.group.id > 0 && (can(['security']) || (can(['manage_webapp']) && can(['manage_dns'])))
+    };
+}
+export function canOnboard(bootstrap: Bootstrap | undefined): boolean { return !!bootstrap && (bootstrap.groups.length > 0 || bootstrap.can_create_webapp_group); }

package/src/admin/deployments/receipts.ts

@@ -0,0 +1,78 @@
+import type { CreateProfile, ManifestEntry } from './types';
+import { record, text, uuid, positiveId, list } from './sanitize';
+import type { DeploymentOwner } from './permissions';
+export interface ActionReceipt {
+    version: 1;
+    actor: string;
+    origin: string;
+    key: string;
+    operation: string;
+    kind: 'create' | 'api' | 'key' | 'rollback' | 'upload' | 'profile';
+    app: number;
+    target: string;
+    settled: boolean;
+    submitted?: boolean;
+    submittedAt?: number;
+    acknowledged?: boolean;
+    address?: {
+        domain: number;
+        label: string;
+    };
+    onboardingGroup?: number;
+    profile?: CreateProfile;
+    manifest?: ManifestEntry[];
+    release?: number;
+    deployment?: number;
+    uploadPhase?: 'registered' | 'completion_submitted' | 'observing';
+    completionSubmittedAt?: number;
+    completionBaseline?: number[];
+}
+const STORAGE = 'mojo.deployment.receipts.v1';
+const memory = new Map<string, ActionReceipt>();
+const active = new Set<string>();
+function project(v: unknown): ActionReceipt | null { const r = record(v); if (r.version !== 1 || !['create', 'api', 'key', 'rollback', 'upload', 'profile'].includes(String(r.kind)) || !uuid(r.operation) || !text(r.actor) || !text(r.origin) || !text(r.key))
+    return null; const receipt: ActionReceipt = {
+    version: 1, actor: text(r.actor), origin: text(r.origin), key: text(r.key), operation: uuid(r.operation), kind: r.kind as ActionReceipt['kind'], app: positiveId(r.app), target: text(r.target), settled: r.settled === true, submitted: r.submitted === true, submittedAt: typeof r.submittedAt === 'number' ? r.submittedAt : undefined, acknowledged: r.acknowledged === true, release: positiveId(r.release) || undefined, deployment: positiveId(r.deployment) || undefined
+}; if(positiveId(r.onboardingGroup))receipt.onboardingGroup=positiveId(r.onboardingGroup);if(r.kind==='upload'){
+    if(['registered','completion_submitted','observing'].includes(String(r.uploadPhase)))receipt.uploadPhase=r.uploadPhase as ActionReceipt['uploadPhase'];
+    if(typeof r.completionSubmittedAt==='number'&&Number.isFinite(r.completionSubmittedAt))receipt.completionSubmittedAt=r.completionSubmittedAt;
+    if(Array.isArray(r.completionBaseline))receipt.completionBaseline=list(r.completionBaseline,100).map(positiveId).filter(Boolean);
+} if (r.address) {
+    const a = record(r.address);
+    receipt.address = { domain: positiveId(a.domain), label: text(a.label, 63) };
+} if (r.kind === 'create' && r.profile) {
+    const p = record(r.profile);
+    receipt.profile = {
+        operation_id: receipt.operation, ...(positiveId(p.group) ? { group: positiveId(p.group) } : { group_intent: 'new' as const }), slug: text(p.slug, 64), display_name: text(p.display_name, 120), environment: text(p.environment, 16), bucket: text(p.bucket), github_repository: text(p.github_repository), deployment_ref: text(p.deployment_ref), build_output: text(p.build_output)
+    };
+} if (r.kind === 'upload' && Array.isArray(r.manifest))
+    receipt.manifest = list(r.manifest, 5000).map(v => { const p = record(v); return {
+        path: text(p.path, 1024), sha256: text(p.sha256, 64), size: typeof p.size === 'number' ? p.size : 0
+    }; }); return receipt; }
+function restore() { try {
+    for (const raw of JSON.parse(sessionStorage.getItem(STORAGE) ?? '[]')) {
+        const r = project(raw);
+        if (r && !memory.has(r.key))
+            memory.set(r.key, r);
+    }
+}
+catch { /* session-only fallback */ } }
+function persist() { try {
+    sessionStorage.setItem(STORAGE, JSON.stringify([...memory.values()].slice(-32)));
+}
+catch { /* receipt remains for this tab */ } }
+export function receiptsFor(owner: DeploymentOwner): ActionReceipt[] { restore(); return [...memory.values()].filter(r => r.actor === owner.actor && r.origin === owner.origin).map(r => ({ ...r })); }
+export function saveReceipt(receipt: ActionReceipt) { const safe = project(receipt); if (!safe)
+    throw new Error('Invalid deployment receipt'); memory.set(safe.key, safe); persist(); return safe; }
+export function makeReceipt(owner: DeploymentOwner, kind: ActionReceipt['kind'], scope: string, app = 0, target = ''): ActionReceipt { const key = `${owner.origin}:${owner.actor}:${kind}:${scope}`; const previous = receiptsFor(owner).find(r => r.key === key); return previous && (!previous.settled || (previous.kind==='upload'&&['completion_submitted','observing'].includes(previous.uploadPhase??''))) ? previous : saveReceipt({
+    version: 1, actor: owner.actor, origin: owner.origin, key, operation: crypto.randomUUID(), kind, app, target, settled: false
+}); }
+export function appUnsettled(owner: DeploymentOwner, app: number, except?: string): ActionReceipt | undefined { return receiptsFor(owner).find(r => r.app === app && app > 0 && !r.settled && r.key !== except); }
+export function settleReceipt(r: ActionReceipt) { saveReceipt({ ...r, settled: true }); }
+export async function singleFlight<T>(key: string, fn: () => Promise<T>): Promise<T> { if (active.has(key))
+    throw new Error('An operation for this target is already pending'); active.add(key); try {
+    return await fn();
+}
+finally {
+    active.delete(key);
+} }

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]); }