portal-mojo 0.2.19 → 0.2.21

package/src/client/geo-provider-mock.ts

@@ -0,0 +1,82 @@
+/** Fixture-only GeoLocation provider setup. No submitted credential is retained or observed. */
+import type { GeoDraft, GeoLocationState, GeoVerdict, StoredGeoVerification } from '../admin/geolocation/data';
+export const mockGeoProviderScenarios = ['ready', 'no-key', 'unknown-provider', 'empty-registry', 'unavailable', 'remote-error', 'rejected-key', 'missing-sync-permission', 'changed-origin', 'stale-revision', 'pending-restart', 'published-origin-pending', 'missing-delegation', 'old-api', 'malformed', 'fresh-auth', 'save-uncertain'] as const;
+export type MockGeoProviderScenario = typeof mockGeoProviderScenarios[number];
+const endpoint = '/api/account/admin/settings';
+const keys = ['GEOIP_PRIMARY_PROVIDER', 'GEOIP_FALLBACK_PROVIDER', 'GEOIP_ADDITIONAL_PROVIDERS', 'GEOIP_MOJO_PROVIDER_URL', 'GEOIP_MOJO_SYNC_ENABLED'];
+const defaults: GeoDraft = { GEOIP_PRIMARY_PROVIDER: 'mojo', GEOIP_FALLBACK_PROVIDER: 'ipinfo', GEOIP_ADDITIONAL_PROVIDERS: ['ip-api', 'maxmind'], GEOIP_MOJO_PROVIDER_URL: 'https://api.mojoverify.com', GEOIP_MOJO_SYNC_ENABLED: false };
+const metadata = [
+    ['Primary GeoIP provider', 'Provider queried first for IP intelligence.', 'string', 'Provider identifier'],
+    ['Fallback GeoIP provider', 'Provider used when the primary cannot answer.', 'string', 'Provider identifier'],
+    ['Additional GeoIP providers', 'Extra providers available after primary and fallback.', 'list', 'Unique provider identifiers'],
+    ['Mojo GeoIP URL', 'Canonical HTTPS origin of the upstream django-mojo provider.', 'origin', 'One HTTPS origin'],
+    ['Mojo GeoIP sync', 'Push observed abuse signals back to the upstream provider.', 'boolean', ''],
+];
+let scenario: MockGeoProviderScenario = 'ready', sequence = 1, publishedVersion = 1, usedFault = false;
+let configurationRevision = '1'.repeat(32), publishedRevision = '1'.repeat(32), loadedRevision = '1'.repeat(32);
+let values: GeoDraft = structuredClone(defaults), loadedOrigin = defaults.GEOIP_MOJO_PROVIDER_URL, loadedSync = false;
+let keyConfigured = true, keyHint = '9f2c', stored: StoredGeoVerification | undefined;
+const observations: { action: string; key_action: 'keep' | 'replace' | 'clear'; stored_test: boolean; expected_revision: string | null }[] = [];
+export function setMockGeoProviderScenario(value: MockGeoProviderScenario): void {
+    if (!mockGeoProviderScenarios.includes(value)) throw new Error('Unknown GeoLocation fixture');
+    scenario = value; usedFault = false; sequence = 1; publishedVersion = 1; configurationRevision = publishedRevision = loadedRevision = '1'.repeat(32);
+    values = structuredClone(defaults); loadedOrigin = defaults.GEOIP_MOJO_PROVIDER_URL; loadedSync = false; keyConfigured = true; keyHint = '9f2c'; observations.length = 0;
+    stored = { ok: true, code: null, message: 'Connection verified', at: '2026-10-21T12:00:00Z' };
+    if (value === 'no-key') { keyConfigured = false; keyHint = ''; stored = undefined; }
+    if (value === 'unknown-provider') { values.GEOIP_PRIMARY_PROVIDER = 'custom_geo'; values.GEOIP_ADDITIONAL_PROVIDERS = ['custom_extra', 'maxmind']; }
+    if (['pending-restart', 'published-origin-pending', 'changed-origin'].includes(value)) { publishedRevision = configurationRevision = '2'.repeat(32); }
+    if (['published-origin-pending', 'changed-origin'].includes(value)) loadedOrigin = 'https://legacy-geo.example.invalid';
+}
+export const getMockGeoProviderScenario = (): MockGeoProviderScenario => scenario;
+export const getMockGeoProviderObservations = () => observations.map(row => ({ ...row }));
+export const clearMockGeoProviderObservations = () => { observations.length = 0; };
+export function geoProviderSetupMock(): GeoLocationState {
+    return { available: scenario !== 'unavailable', bucket_configured: scenario !== 'unavailable', restart_configured: true, object_key: 'fixture/config/django.override.json',
+        delegated_keys: keys.filter(key => scenario !== 'missing-delegation' || key !== keys[2]), fleet_fields: keys.map((key, i) => ({ key, label: metadata[i]![0]!, description: metadata[i]![1]!, value_type: metadata[i]![2]!, constraints: metadata[i]![3]! })),
+        loaded_revision: loadedRevision, published_revision: publishedRevision, configuration_revision: configurationRevision, published_version: `fixture-version-${publishedVersion}`, pending_restart: publishedRevision !== loadedRevision,
+        remote_error: scenario === 'remote-error' ? 'FixtureRemoteReadError' : null, geoip: { ...structuredClone(values), GEOIP_API_KEY_MOJO_CONFIGURED: keyConfigured, GEOIP_API_KEY_MOJO_HINT: keyHint },
+        geoip_providers: scenario === 'empty-registry' ? [] : ['maxmind', 'ipinfo', 'ipstack', 'ip-api', 'mojo'], verify_state: stored ? { geoip: { ...stored } } : {} };
+}
+const fail = (error: string, code = 400) => ({ status: false, code, error_code: code, error });
+const provider = (v: unknown): v is string => typeof v === 'string' && /^[a-z][a-z0-9_-]{0,31}$/.test(v);
+function origin(v: unknown): v is string {
+    if (typeof v !== 'string' || v.length > 512) return false;
+    try { const u = new URL(v); return u.protocol === 'https:' && !!u.hostname && !u.username && !u.password && !u.search && !u.hash && ['', '/'].includes(u.pathname) && (!u.port || u.port === '443'); } catch { return false; }
+}
+const record = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v);
+/** Undefined means another topic/route owns the request. The central mock supplies session gates. */
+export function geoProviderMock(path: string, method: string, body: Record<string, unknown> | undefined, superuser: boolean): unknown {
+    if (path !== endpoint) return undefined;
+    if (method !== 'GET' && body?.topic !== 'geoip') return undefined;
+    if (!superuser) return fail('Superuser required', 403);
+    if (scenario === 'old-api') return fail('Not found', 404);
+    if (method === 'GET') return { status: true, data: { schema_version: scenario === 'malformed' ? 999 : 1, provider_setup: geoProviderSetupMock() } };
+    if (method !== 'POST' || !body || Object.keys(body).sort().join(',') !== 'action,providers,topic' || !['test_providers', 'configure_providers'].includes(String(body.action))) return fail('Provider setup accepts only action, topic, and providers');
+    const p = body.providers;
+    if (!record(p) || Object.keys(p).some(k => !['expected_revision', 'geoip'].includes(k)) || !record(p.geoip)) return fail('Provider setup accepts only geoip and expected_revision');
+    const g = p.geoip;
+    if (Object.keys(g).some(k => ![...keys, 'GEOIP_API_KEY_MOJO', 'clear_api_key'].includes(k))) return fail('GeoIP setup contains unsupported fields');
+    const candidate = { ...defaults, GEOIP_ADDITIONAL_PROVIDERS: [], GEOIP_MOJO_PROVIDER_URL: 'https://api.mojoverify.com', ...g };
+    if (!provider(candidate.GEOIP_PRIMARY_PROVIDER) || !provider(candidate.GEOIP_FALLBACK_PROVIDER) || !Array.isArray(candidate.GEOIP_ADDITIONAL_PROVIDERS) || candidate.GEOIP_ADDITIONAL_PROVIDERS.length > 16 || !candidate.GEOIP_ADDITIONAL_PROVIDERS.every(provider) || new Set(candidate.GEOIP_ADDITIONAL_PROVIDERS).size !== candidate.GEOIP_ADDITIONAL_PROVIDERS.length || !origin(candidate.GEOIP_MOJO_PROVIDER_URL) || typeof candidate.GEOIP_MOJO_SYNC_ENABLED !== 'boolean') return fail('Invalid GeoIP provider settings');
+    if (p.expected_revision != null && (typeof p.expected_revision !== 'string' || !/^[a-f0-9]{32,64}$/.test(p.expected_revision))) return fail('Provider setup revision is invalid');
+    if (g.GEOIP_API_KEY_MOJO != null && (typeof g.GEOIP_API_KEY_MOJO !== 'string' || g.GEOIP_API_KEY_MOJO.length > 4096)) return fail('GeoIP API key is invalid');
+    if (scenario === 'missing-delegation' || body.action === 'configure_providers' && ['unavailable', 'remote-error'].includes(scenario)) return fail('Fleet publishing requires its exact object, all provider delegations, a KMS key, and config-sync restart');
+    if (scenario === 'fresh-auth' && !usedFault) { usedFault = true; return fail('Fresh authentication required', 440); }
+    const next: GeoDraft = { GEOIP_PRIMARY_PROVIDER: candidate.GEOIP_PRIMARY_PROVIDER, GEOIP_FALLBACK_PROVIDER: candidate.GEOIP_FALLBACK_PROVIDER, GEOIP_ADDITIONAL_PROVIDERS: [...candidate.GEOIP_ADDITIONAL_PROVIDERS], GEOIP_MOJO_PROVIDER_URL: candidate.GEOIP_MOJO_PROVIDER_URL.replace(/\/$/, ''), GEOIP_MOJO_SYNC_ENABLED: candidate.GEOIP_MOJO_SYNC_ENABLED };
+    const clear = g.clear_api_key === true, typed = typeof g.GEOIP_API_KEY_MOJO === 'string' && g.GEOIP_API_KEY_MOJO !== '';
+    // The real predicate ignores primary/fallback/additional differences and compares NODE-LOADED connection facts.
+    const testedStored = !clear && !typed && next.GEOIP_MOJO_PROVIDER_URL === loadedOrigin && next.GEOIP_MOJO_SYNC_ENABLED === loadedSync;
+    observations.push({ action: String(body.action), key_action: clear ? 'clear' : typed ? 'replace' : 'keep', stored_test: testedStored, expected_revision: p.expected_revision == null ? null : String(p.expected_revision) });
+    const accepted = scenario !== 'rejected-key' && (typed ? !String(g.GEOIP_API_KEY_MOJO).startsWith('rejected') : keyConfigured && next.GEOIP_MOJO_PROVIDER_URL === loadedOrigin);
+    const result: GeoVerdict = clear ? { success: true, code: 'clear_requested', message: 'GeoIP credential will be cleared' } : accepted && next.GEOIP_MOJO_SYNC_ENABLED && scenario === 'missing-sync-permission' ? { success: false, code: 'insufficient_permission', message: `${new URL(next.GEOIP_MOJO_PROVIDER_URL).hostname} accepted the key, but it is missing geoip_sync` } : accepted ? { success: true, code: null, message: 'Connection verified' } : { success: false, code: 'http_401', message: `${new URL(next.GEOIP_MOJO_PROVIDER_URL).hostname} rejected the API key` };
+    const remember = () => { stored = { ok: result.success, code: result.code, message: result.message, at: new Date().toISOString() }; };
+    if (body.action === 'test_providers') { if (testedStored) remember(); return { status: true, tested: true, topic: 'geoip', results: { geoip: result }, success: result.success }; }
+    if (!result.success) return fail('Provider verification failed for geoip');
+    if (p.expected_revision !== configurationRevision || scenario === 'stale-revision' && !usedFault) { usedFault = true; configurationRevision = '3'.repeat(32); return fail('Provider configuration changed; reload before publishing'); }
+    const changed = JSON.stringify(next) !== JSON.stringify(values);
+    if (clear) { keyConfigured = false; keyHint = ''; } else if (typed) { keyConfigured = true; keyHint = String(g.GEOIP_API_KEY_MOJO).length >= 8 ? String(g.GEOIP_API_KEY_MOJO).slice(-4) : ''; }
+    values = next; configurationRevision = (++sequence).toString(16).padStart(32, '0'); if (changed) { publishedRevision = configurationRevision; publishedVersion++; } remember();
+    if (scenario === 'save-uncertain' && !usedFault) { usedFault = true; return fail('Connection unavailable after persistence', 503); }
+    return { status: true, published: changed, unchanged: !changed, topic: 'geoip', revision: configurationRevision, published_revision: publishedRevision, version_id: `fixture-version-${publishedVersion}`, pending_restart: publishedRevision !== loadedRevision, results: { geoip: result } };
+}
+setMockGeoProviderScenario('ready');

package/src/client/index.ts

@@ -32,8 +32,8 @@ export * from './realtime-mock';
 export * from './types';
 // Dev affordance: per-endpoint call counts from the mock (single-flight proof).
 export {
-    armMockReauth, clearMockRequestHistory, getMockCallCounts, setMockAssistantSetupScenario,
-    getMockRequestHistory, setMockDnsConfigMalformed, setMockDnsAcmeMode, armMockDnsWriteFault,
+    armMockReauth, clearMockRequestHistory, getMockCallCounts, setMockAssistantSetupScenario, setMockConnectionScenario, type MockConnectionScenario,
+    getMockRequestHistory, setMockSharedValidationScenario, armMockSharedValidationFault, type MockSharedValidationScenario, setMockDnsConfigMalformed, setMockDnsAcmeMode, armMockDnsWriteFault,
     getMockPhoneConfigCredentialState, getMockEffectivePhoneConfigId,
     deleteMockPhoneGroupForTest,
     setMockDnsRegistrarMode, armMockRegistrarPurchaseFault,

package/src/client/maintenance-mock.ts

@@ -0,0 +1,285 @@
+/** Mock-owned Maintenance provider simulation. Never performs a provider request. */
+import { backendGlobalCan, type BackendGlobalUser } from '../admin/fleet/access';
+import type { Finding, Framework, Report } from '../admin/maintenance/data';
+export const MAINTENANCE_SCENARIOS = [
+    'findings',
+    'support-overdue', 'support-soon', 'later-target', 'status-missing', 'status-error',
+    'framework-cached', 'policy-lost-response', 'policy-refused', 'framework-converged', 'framework-converged-version-missing', 'framework-failed', 'framework-missing-deployment',
+    'empty',
+    'denied-inventory',
+    'unavailable',
+    'scanning-off',
+    'external',
+    'bootstrap-denied',
+    'bootstrap-malformed',
+    'next-window',
+    'target-before-settled',
+    'settled-old',
+    'mixed-cache',
+    'all-members-upgraded',
+    'provider-unknown',
+    'duplicate',
+    'cache-refusal',
+    'stale-target',
+    'reauth',
+    'framework-held',
+    'framework-pinned',
+    'framework-current',
+    'framework-unknown',
+    'framework-no-converged',
+    'framework-requires-superuser',
+    'framework-pin-cleared-503',
+    'framework-lost-response',
+] as const;
+export type MaintenanceScenario = (typeof MAINTENANCE_SCENARIOS)[number];
+let scenario: MaintenanceScenario = 'findings';
+const pending = new Map<string, { target: string; immediate: boolean; reads: number }>();
+let frameworkRequested = false;
+let policyValue: string | undefined;
+let deploymentReads = 0;
+const deploymentId = '92450000-0000-4000-8000-000000000001';
+export function setMockMaintenanceScenario(value: MaintenanceScenario) {
+    scenario = value;
+    pending.clear();
+    frameworkRequested = false; policyValue = undefined; deploymentReads = 0;
+}
+export function readMaintenanceBootstrapFacts(): {
+    mode: 'managed' | 'external';
+    infrastructureManaged: boolean;
+    bootstrap: 'ok' | 'denied' | 'malformed';
+} {
+    return {
+        mode: scenario === 'external' ? 'external' : 'managed',
+        infrastructureManaged: scenario !== 'external',
+        bootstrap:
+            scenario === 'bootstrap-denied'
+                ? 'denied'
+                : scenario === 'bootstrap-malformed'
+                  ? 'malformed'
+                  : 'ok',
+    };
+}
+const date = () => new Date().toISOString();
+const finding = (
+    kind: Finding['kind'],
+    resource_id: string,
+    engine: string,
+    current_version: string,
+    available_major: string,
+): Finding => ({
+    kind,
+    resource_id,
+    engine,
+    current_version,
+    available_major,
+    deadline: kind === 'elasticache' ? null : '2027-02-28T00:00:00Z',
+    extended_deadline: kind === 'elasticache' ? null : '2030-02-28T00:00:00Z',
+    days_remaining: kind === 'elasticache' ? null : scenario === 'support-overdue' ? -14 : scenario === 'support-soon' ? 30 : 130,
+    note:
+        kind === 'elasticache'
+            ? 'A replication group can contain mixed member versions.'
+            : 'Review engine compatibility and snapshot recovery before applying.',
+    release_notes_url: 'https://docs.aws.amazon.com/',
+    status: 'available',
+    pending_version: null,
+    settled: true,
+    ...(kind === 'elasticache' ? { members: 2, engine_versions: ['6.2', '6.0'] } : {}),
+});
+export function maintenanceMockReport(): Report {
+    return {
+        schema_version: 1,
+        generated_at: date(),
+        region: 'us-east-1',
+        status: scenario === 'unavailable' ? 'unavailable' : 'ok',
+        level: 5,
+        scheduled: scenario !== 'scanning-off',
+        findings: ['empty', 'unavailable'].includes(scenario)
+            ? []
+            : [
+                  { ...finding('rds-instance', 'orders-db', 'postgres', scenario === 'later-target' && (pending.get('rds-instance:orders-db')?.reads ?? 0) >= 2 ? pending.get('rds-instance:orders-db')!.target : '14.12', scenario === 'later-target' && (pending.get('rds-instance:orders-db')?.reads ?? 0) >= 2 ? '17.2' : '16.4') },
+                  finding('rds-cluster', 'analytics-cluster', 'aurora-postgresql', '13.12', '15.8'),
+                  finding('elasticache', 'session-cache', 'redis', '6.2', '7.1'),
+                  finding('elasticache', 'standalone-cache', 'redis', '6.0', '7.1'),
+              ],
+        warnings:
+            scenario === 'denied-inventory'
+                ? [
+                      { iam_action: 'rds:DescribeDBClusters', aws_code: 'AccessDenied' },
+                      { iam_action: 'elasticache:DescribeReplicationGroups', aws_code: 'AccessDenied' },
+                  ]
+                : [],
+        reason: scenario === 'unavailable' ? 'AWS credentials unavailable' : null,
+    };
+}
+export function maintenanceMockFramework(user: BackendGlobalUser): Framework {
+    const defaultPin = ['framework-held','framework-pin-cleared-503'].includes(scenario) ? 'hold' : scenario === 'framework-pinned' ? '4.0.0' : '';
+    const pin = policyValue ?? (frameworkRequested ? '' : defaultPin);
+    const mode = pin === '' ? 'latest' : pin === 'hold' ? 'hold' : 'pinned';
+    const unknown = scenario === 'framework-unknown';
+    const latest = unknown ? null : scenario === 'framework-current' ? '4.0.0' : '4.1.0';
+    const installed = '4.0.0';
+    const update_available = !!latest && latest !== installed && mode === 'latest';
+    const blocked_reason: Framework['blocked_reason'] = scenario === 'external' ? 'infrastructure_external' : !latest || !update_available && mode === 'latest' ? 'update_unavailable' : mode !== 'latest' && user.is_superuser !== true ? 'requires_superuser' : scenario === 'framework-no-converged' ? 'no_converged_deployment' : scenario === 'framework-requires-superuser' ? 'requires_superuser' : null;
+    return {schema_version:1, installed, latest, checked_at:date(), source:unknown?'unavailable':scenario==='framework-cached'?'cache':'pypi',update_available,pin:{mode,value:pin||null},can_update:blocked_reason===null,blocked_reason};
+}
+const ok = (data: unknown) => ({ status: true, data });
+const fail = (code: string, status: number, data?: unknown) => ({
+    status: false,
+    error: code.replaceAll('_', ' '),
+    error_code: code,
+    code: status,
+    ...(data ? { data } : {}),
+});
+export interface MaintenanceMockContext {
+    user?: (BackendGlobalUser & { is_active?: boolean; id?: number | string }) | null;
+    keyBacked?: boolean;
+    fresh?: boolean;
+}
+export function maintenanceMock(
+    path: string,
+    method: string,
+    body: Record<string, unknown> | undefined,
+    params: Record<string, unknown> = {},
+    context: MaintenanceMockContext = {},
+): unknown {
+    const aws = [
+            '/api/aws/maintenance/versions',
+            '/api/aws/maintenance/status',
+            '/api/aws/maintenance/apply',
+        ].includes(path),
+        framework =
+            path === '/api/account/admin/platform/framework' ||
+            path === '/api/account/admin/platform/framework/update';
+    const policy = path === '/api/account/admin/advanced/settings' && Object.hasOwn(body ?? {}, 'framework_pin');
+    const platform = path === '/api/account/admin/platform' && params.sections === 'deployments';
+    if (!aws && !framework && !policy && !platform) return undefined;
+    const user = context.user;
+    if (!user || user.is_active === false) return fail('permission_denied', 403);
+    if (!backendGlobalCan(user, aws ? 'manage_aws' : ['view_platform', 'manage_platform', 'admin']))
+        return fail('permission_denied', 403);
+    if (platform && method === 'GET') {
+        deploymentReads++;
+        const status = scenario === 'framework-failed' ? 'failed' : deploymentReads >= 2 ? 'converged' : 'fleet';
+        return ok({ schema_version: 1, sections: { deployments: { status: 'ok', data: { items: !frameworkRequested || scenario === 'framework-missing-deployment' ? [] : [{ id: deploymentId, sha: 'a'.repeat(40), status, framework_version: '4.1.0', frozen_roster: ['runner-maint-1'], node_evidence: [{runner: 'runner-maint-1', state: status === 'converged' ? 'proven' : 'dispatched', observed_at: date(), stale_after: new Date(Date.now()+60000).toISOString(), proof: {platform_deployment: deploymentId, platform_sha: 'a'.repeat(40), django_mojo_version: scenario === 'framework-converged-version-missing' ? null : '4.1.0'}}] }] } } } });
+    }
+    if (method === 'GET' && path === '/api/aws/maintenance/versions') return ok(maintenanceMockReport());
+    if (method === 'GET' && path === '/api/account/admin/platform/framework')
+        return ok(maintenanceMockFramework(user));
+    if (method === 'GET' && path === '/api/aws/maintenance/status') {
+        if (scenario === 'status-error') return fail('provider_unavailable',503);
+        if (scenario === 'status-missing') return ok({schema_version:1,kind:params.kind,resource:params.resource,target_version:params.target_version,found:false,status:null,engine_version:null,engine_versions:[],pending_version:null,settled:false,upgraded:false});
+        const f = maintenanceMockReport().findings.find(
+            (f) => f.kind === params.kind && f.resource_id === params.resource,
+        );
+        if (!f || typeof params.target_version !== 'string') return fail('invalid_request', 400);
+        const attempt = pending.get(`${f.kind}:${f.resource_id}`);
+        if (attempt) attempt.reads++;
+        const waiting =
+            ['next-window', 'settled-old', 'provider-unknown'].includes(scenario) ||
+            (!!attempt && !attempt.immediate);
+        const targetObserved = !!attempt && !waiting && attempt.reads >= 2;
+        const settled =
+            targetObserved && (scenario !== 'target-before-settled' || (attempt?.reads ?? 0) >= 4);
+        const mixed = scenario === 'mixed-cache' && f.kind === 'elasticache';
+        const versions = targetObserved
+            ? mixed
+                ? [params.target_version, f.current_version]
+                : [params.target_version, params.target_version]
+            : [f.current_version];
+        return ok({
+            schema_version: 1,
+            kind: f.kind,
+            resource: f.resource_id,
+            target_version: params.target_version,
+            found: true,
+            status: waiting || settled ? 'available' : 'modifying',
+            engine_version: versions[0],
+            engine_versions: versions,
+            pending_version: attempt && !settled ? attempt.target : null,
+            settled: waiting || settled,
+            upgraded: targetObserved && !mixed,
+        });
+    }
+    if (
+        method !== 'POST' ||
+        !['/api/aws/maintenance/apply', '/api/account/admin/platform/framework/update', '/api/account/admin/advanced/settings'].includes(path)
+    )
+        return fail('method_not_allowed', 405);
+    if (context.keyBacked) return fail('permission_denied', 403);
+    if (!context.fresh || scenario === 'reauth') return fail('fresh_auth_required', 440);
+    if (!backendGlobalCan(user, ['manage_platform', 'admin'])) return fail('permission_denied', 403);
+    if (policy) {
+        if (user.is_superuser !== true) return fail('permission_denied',403);
+        const value = body?.framework_pin;
+        if (typeof value !== 'string' || !(value === '' || value === 'hold' || /^[0-9][a-z0-9._!+-]{0,63}$/.test(value))) return fail('invalid_request',400);
+        if (scenario === 'policy-refused') return fail('invalid_request',400);
+        policyValue = value;
+        if (scenario === 'policy-lost-response') return fail('service_unavailable',503);
+        return ok({schema_version:1,saved:true,value});
+    }
+    if (scenario === 'external') return fail('infrastructure_external', 403);
+    if (!body) return fail('invalid_request', 400);
+    if (aws) {
+        const f = maintenanceMockReport().findings.find(
+            (f) => f.kind === body.kind && f.resource_id === body.resource,
+        );
+        if (!f || body.confirm_resource !== body.resource || typeof body.apply_immediately !== 'boolean')
+            return fail('invalid_request', 400);
+        if (body.target_version !== f.available_major || scenario === 'stale-target')
+            return fail('upgrade_not_offered', 409);
+        const key = `${f.kind}:${f.resource_id}`;
+        if (pending.has(key) && !(scenario === 'later-target' && pending.get(key)!.reads >= 2) || scenario === 'duplicate') return fail('upgrade_in_progress', 409);
+        if (scenario === 'cache-refusal') return fail('cache_unavailable', 503);
+        pending.set(key, { target: f.available_major, immediate: body.apply_immediately, reads: 0 });
+        if (scenario === 'provider-unknown')
+            return fail('provider_unavailable', 503, {
+                failure: {
+                    operation: 'rds.modify_db_instance',
+                    provider_code: 'RequestTimeout',
+                    retryable: true,
+                    mutation_state: 'unknown',
+                    iam_action: 'rds:ModifyDBInstance',
+                },
+            });
+        return ok({
+            schema_version: 1,
+            requested: true,
+            resource: f.resource_id,
+            kind: f.kind,
+            engine: f.engine,
+            from_version: f.current_version,
+            target_version: f.available_major,
+            apply_immediately: body.apply_immediately,
+            release_notes_url: f.release_notes_url,
+            operation:
+                f.kind === 'elasticache'
+                    ? f.resource_id === 'standalone-cache'
+                        ? 'elasticache.modify_cache_cluster'
+                        : 'elasticache.modify_replication_group'
+                    : f.kind === 'rds-cluster'
+                      ? 'rds.modify_db_cluster'
+                      : 'rds.modify_db_instance',
+        });
+    }
+    const fw = maintenanceMockFramework(user);
+    if (!fw.can_update || body.version !== fw.latest || body.confirm_version !== body.version)
+        return fail('update_unavailable', 409);
+    frameworkRequested = true; policyValue = ''; deploymentReads = 0;
+    if (['framework-pin-cleared-503', 'framework-lost-response'].includes(scenario))
+        return fail('deployment_coordination_unavailable', 503);
+    return ok({
+        schema_version: 1,
+        requested: true,
+        version: fw.latest,
+        cleared_pin: fw.pin.value,
+        deployment: { id: deploymentId, sha: 'a'.repeat(40), status: 'pending' },
+    });
+}
+
+export const getMockMaintenanceScenario = () => scenario;
+/** Demo-only provider passage: retain receipts and server operations; never replay a write. */
+export function advanceMockMaintenance() {
+    scenario = 'all-members-upgraded';
+    for (const operation of pending.values()) { operation.immediate = true; operation.reads = Math.max(2, operation.reads); }
+    deploymentReads = Math.max(2, deploymentReads);
+}