portal-mojo 0.1.0

package/src/admin/shortlinks/models.ts

@@ -0,0 +1,246 @@
+import { useQuery, type QueryClient } from '@tanstack/react-query';
+import { apiOrigin, defineModel, mojoCall, mojoDelete, mojoGet, mojoList, mojoSave, type Params } from '../../client';
+
+export const SHORTLINK_MANAGE_PERMISSIONS = ['sys.manage_shortlinks'];
+export const SHORTLINK_ENDPOINT = '/api/shortlink/link';
+export const SHORTLINK_HISTORY_ENDPOINT = '/api/shortlink/history';
+
+export interface ShortlinkRelation { id: number; name?: string; display_name?: string; email?: string }
+export interface ShortlinkRow {
+    id: number;
+    code: string;
+    source: string;
+    hit_count: number;
+    expires_at: number | string | null;
+    is_active: boolean;
+    is_protected: boolean;
+    track_clicks: boolean;
+    bot_passthrough: boolean;
+    created: number | string;
+    modified: number | string | null;
+    user: ShortlinkRelation | number | null;
+    group: ShortlinkRelation | number | null;
+}
+
+export interface ShortlinkHistoryRow {
+    id: number;
+    shortlink_id: number | null;
+    code: string;
+    is_bot: boolean;
+    created: number | string;
+    agent_summary: string;
+    referer_origin: string | null;
+}
+
+const FORBIDDEN_KEYS = /^(url|destination|ip|ip_address|user_agent|referer|metadata)$/i;
+
+/** Defense in depth: fail a verifier if a future projection accidentally retains a raw sensitive key. */
+export function assertSafeShortlinkProjection(value: unknown): void {
+    const visit = (candidate: unknown): void => {
+        if (Array.isArray(candidate)) { candidate.forEach(visit); return; }
+        if (!candidate || typeof candidate !== 'object') return;
+        for (const [key, child] of Object.entries(candidate as Record<string, unknown>)) {
+            if (FORBIDDEN_KEYS.test(key)) throw new Error(`Unsafe shortlink projection retained ${key}`);
+            visit(child);
+        }
+    };
+    visit(value);
+}
+
+function relation(value: unknown): ShortlinkRelation | number | null {
+    if (typeof value === 'number' && Number.isFinite(value)) return value;
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+    const raw = value as Record<string, unknown>;
+    if (!Number.isFinite(Number(raw.id))) return null;
+    return {
+        id: Number(raw.id),
+        ...(typeof raw.name === 'string' ? { name: raw.name.slice(0, 120) } : {}),
+        ...(typeof raw.display_name === 'string' ? { display_name: raw.display_name.slice(0, 120) } : {}),
+        ...(typeof raw.email === 'string' ? { email: raw.email.slice(0, 254) } : {}),
+    };
+}
+
+function temporal(value: unknown): number | string | null {
+    return typeof value === 'number' && Number.isFinite(value) ? value
+        : typeof value === 'string' && value.length <= 40 ? value : null;
+}
+
+/** Positive projection. The backend's graph=list includes url; it never crosses this boundary. */
+export function sanitizeShortlinkRow(input: unknown): ShortlinkRow {
+    const raw = input && typeof input === 'object' && !Array.isArray(input) ? input as Record<string, unknown> : {};
+    const row: ShortlinkRow = {
+        id: Number(raw.id), code: String(raw.code ?? '').slice(0, 10), source: String(raw.source ?? '').slice(0, 50),
+        hit_count: Math.max(0, Number(raw.hit_count ?? 0) || 0), expires_at: temporal(raw.expires_at),
+        is_active: Boolean(raw.is_active), is_protected: Boolean(raw.is_protected),
+        track_clicks: Boolean(raw.track_clicks), bot_passthrough: Boolean(raw.bot_passthrough),
+        created: temporal(raw.created) ?? 0, modified: temporal(raw.modified), user: relation(raw.user), group: relation(raw.group),
+    };
+    assertSafeShortlinkProjection(row);
+    return row;
+}
+
+function boundedAgentSummary(userAgent: unknown, isBot: boolean): string {
+    const ua = typeof userAgent === 'string' ? userAgent : '';
+    const bot = ua.match(/(Googlebot|Bingbot|Slackbot|Discordbot|Twitterbot|facebookexternalhit|bot|crawler|spider)/i)?.[1];
+    if (isBot) return `${bot ? bot.replace(/externalhit/i, '') : 'Bot'} · automated`.slice(0, 60);
+    const browser = ua.match(/Edg\/[\d.]+/i) ? 'Edge'
+        : ua.match(/Firefox\/[\d.]+/i) ? 'Firefox'
+            : ua.match(/(?:Chrome|CriOS)\/[\d.]+/i) ? 'Chrome'
+                : ua.match(/Version\/[\d.]+.*Safari/i) ? 'Safari' : 'Browser';
+    const platform = /Android/i.test(ua) ? 'Android' : /iPhone|iPad/i.test(ua) ? 'iOS'
+        : /Windows/i.test(ua) ? 'Windows' : /Macintosh|Mac OS/i.test(ua) ? 'macOS'
+            : /Linux/i.test(ua) ? 'Linux' : 'unknown platform';
+    return `${browser} · ${platform}`.slice(0, 60);
+}
+
+function refererOrigin(value: unknown): string | null {
+    if (typeof value !== 'string' || value.length > 4096) return null;
+    try {
+        const parsed = new URL(value);
+        return ['http:', 'https:'].includes(parsed.protocol) && !parsed.username && !parsed.password ? parsed.origin.slice(0, 255) : null;
+    } catch { return null; }
+}
+
+/** Positive projection for click evidence: no IP, raw UA, path/query/fragment, metadata, or nested destination. */
+export function sanitizeShortlinkHistoryRow(input: unknown): ShortlinkHistoryRow {
+    const raw = input && typeof input === 'object' && !Array.isArray(input) ? input as Record<string, unknown> : {};
+    const nested = raw.shortlink && typeof raw.shortlink === 'object' && !Array.isArray(raw.shortlink)
+        ? raw.shortlink as Record<string, unknown> : {};
+    const isBot = Boolean(raw.is_bot);
+    const row: ShortlinkHistoryRow = {
+        id: Number(raw.id), shortlink_id: Number.isFinite(Number(nested.id)) ? Number(nested.id) : null,
+        code: String(nested.code ?? '').slice(0, 10), is_bot: isBot, created: temporal(raw.created) ?? 0,
+        agent_summary: boundedAgentSummary(raw.user_agent, isBot), referer_origin: refererOrigin(raw.referer),
+    };
+    assertSafeShortlinkProjection(row);
+    return row;
+}
+
+const LINK_FILTERS = new Set(['id', 'id__in', 'code', 'source', 'source__in', 'is_active', 'created__gte', 'created__lte']);
+const LINK_SORTS = new Set(['id', 'code', 'source', 'hit_count', 'expires_at', 'is_active', 'created']);
+const HISTORY_FILTERS = new Set(['id', 'shortlink', 'is_bot', 'created__gte', 'created__lte']);
+const HISTORY_SORTS = new Set(['id', 'is_bot', 'created']);
+function allow(params: Params, graph: 'list' | 'default', filters: Set<string>, sorts: Set<string>): Params {
+    const out: Params = { graph, start: params.start ?? 0, size: params.size ?? 25 };
+    for (const [key, value] of Object.entries(params)) {
+        if ((filters.has(key) || ['start', 'size', 'sort', 'dr_start', 'dr_end'].includes(key)) && value != null && value !== '') out[key] = value;
+    }
+    if (out.dr_start != null || out.dr_end != null) out.dr_field = 'created';
+    const sort = typeof out.sort === 'string' ? out.sort : '-created';
+    out.sort = sorts.has(sort.replace(/^-/, '')) ? sort : '-created';
+    return out;
+}
+
+export const ShortlinkModel = defineModel<ShortlinkRow>({
+    name: 'shortlink', endpoint: SHORTLINK_ENDPOINT,
+    permissions: { view: SHORTLINK_MANAGE_PERMISSIONS, manage: SHORTLINK_MANAGE_PERMISSIONS, create: SHORTLINK_MANAGE_PERMISSIONS, delete: SHORTLINK_MANAGE_PERMISSIONS },
+    normalizeListParams: (params) => allow(params, 'list', LINK_FILTERS, LINK_SORTS), sanitizeRow: sanitizeShortlinkRow,
+});
+
+export const ShortlinkHistoryModel = defineModel<ShortlinkHistoryRow>({
+    name: 'shortlink-history', endpoint: SHORTLINK_HISTORY_ENDPOINT,
+    permissions: { view: SHORTLINK_MANAGE_PERMISSIONS },
+    normalizeListParams: (params) => allow(params, 'default', HISTORY_FILTERS, HISTORY_SORTS), sanitizeRow: sanitizeShortlinkHistoryRow,
+});
+
+export function functionalShortlinkUrl(code: string): string {
+    const origin = apiOrigin().replace(/\/$/, '');
+    return `${origin}/s/${encodeURIComponent(code)}`;
+}
+
+export class ShortlinkReconciliationError extends Error {
+    readonly retryBlocked = true;
+    constructor(cause: unknown) {
+        super('The change may have persisted, but authoritative reconciliation failed. Refresh successfully before retrying.', { cause });
+        this.name = 'ShortlinkReconciliationError';
+    }
+}
+
+async function authoritativeList(params: Params): Promise<ShortlinkRow[]> {
+    const result = await mojoList<unknown>(SHORTLINK_ENDPOINT, ShortlinkModel.normalizeListParams?.(params) ?? params);
+    return result.rows.map(sanitizeShortlinkRow);
+}
+
+async function reconcile(queryClient: QueryClient, id?: number, code?: string): Promise<ShortlinkRow | null> {
+    let row: ShortlinkRow | null = null;
+    if (id != null) {
+        try { row = sanitizeShortlinkRow(await mojoGet<unknown>(SHORTLINK_ENDPOINT, id)); }
+        catch (error) {
+            if (!(error && typeof error === 'object' && 'status' in error && Number((error as { status: unknown }).status) === 404)) throw error;
+        }
+    } else if (code) row = (await authoritativeList({ code, size: 2 }))[0] ?? null;
+    await queryClient.invalidateQueries({ queryKey: ShortlinkModel.keys.root, refetchType: 'none' });
+    if (row) queryClient.setQueryData(ShortlinkModel.keys.one(row.id), row);
+    else if (id != null) queryClient.removeQueries({ queryKey: ShortlinkModel.keys.one(id) });
+    await queryClient.refetchQueries({ queryKey: ShortlinkModel.keys.root, type: 'active' });
+    return row;
+}
+
+async function runReconciled<T>(mutation: () => Promise<T>, reconcileNow: (result: T | null) => Promise<ShortlinkRow | null>): Promise<ShortlinkRow | null> {
+    let result: T | null = null;
+    let mutationError: unknown;
+    let authoritative: ShortlinkRow | null = null;
+    let reconciliationError: unknown;
+    try { result = await mutation(); }
+    catch (error) { mutationError = error; }
+    finally {
+        try { authoritative = await reconcileNow(result); }
+        catch (error) { reconciliationError = error; }
+    }
+    if (reconciliationError) throw new ShortlinkReconciliationError(reconciliationError);
+    if (mutationError) throw mutationError;
+    return authoritative;
+}
+
+export async function createShortlink(queryClient: QueryClient, changes: { url: string; source?: string; expire_days?: number; expire_hours?: number; track_clicks?: boolean; bot_passthrough?: boolean; is_protected?: boolean }): Promise<ShortlinkRow> {
+    const result = await runReconciled(
+        () => mojoCall(`${SHORTLINK_ENDPOINT}/create`, { method: 'POST', body: changes }),
+        async (body) => {
+            const raw = body?.data && typeof body.data === 'object' ? body.data as Record<string, unknown> : {};
+            const short = typeof raw.short_link === 'string' ? raw.short_link : '';
+            const code = decodeURIComponent(short.split('/').filter(Boolean).at(-1) ?? '');
+            if (!code) {
+                await authoritativeList({ size: 1 });
+                await queryClient.invalidateQueries({ queryKey: ShortlinkModel.keys.root });
+                return null;
+            }
+            const listed = (await authoritativeList({ code, size: 2 }))[0] ?? null;
+            return listed ? reconcile(queryClient, listed.id) : null;
+        },
+    );
+    if (!result) throw new ShortlinkReconciliationError(new Error('Created row was not visible after create'));
+    return result;
+}
+
+export function setShortlinkActive(queryClient: QueryClient, row: ShortlinkRow, isActive: boolean): Promise<ShortlinkRow | null> {
+    return runReconciled(() => mojoSave(SHORTLINK_ENDPOINT, row.id, { is_active: isActive }), () => reconcile(queryClient, row.id));
+}
+
+export function deleteShortlink(queryClient: QueryClient, row: ShortlinkRow): Promise<ShortlinkRow | null> {
+    return runReconciled(() => mojoDelete(SHORTLINK_ENDPOINT, row.id), () => reconcile(queryClient, row.id));
+}
+
+export async function refreshShortlinks(queryClient: QueryClient): Promise<void> {
+    await authoritativeList({ size: 1 });
+    await queryClient.invalidateQueries({ queryKey: ShortlinkModel.keys.root });
+}
+
+export interface TrackedCounts { human: number; bot: number; tracked: number; remainder: number }
+export async function fetchTrackedCounts(shortlink: ShortlinkRow): Promise<TrackedCounts> {
+    const fetchCount = async (isBot: boolean) => {
+        const result = await mojoList<unknown>(SHORTLINK_HISTORY_ENDPOINT,
+            ShortlinkHistoryModel.normalizeListParams?.({ shortlink: shortlink.id, is_bot: isBot, size: 1 }) ?? {});
+        result.rows.forEach(sanitizeShortlinkHistoryRow);
+        return result.count;
+    };
+    const [human, bot] = await Promise.all([fetchCount(false), fetchCount(true)]);
+    const tracked = human + bot;
+    return { human, bot, tracked, remainder: Math.max(0, shortlink.hit_count - tracked) };
+}
+
+export function useTrackedCounts(shortlink: ShortlinkRow | null) {
+    return useQuery({
+        queryKey: ['shortlink-tracked-counts', shortlink?.id, shortlink?.hit_count],
+        queryFn: () => fetchTrackedCounts(shortlink!), enabled: shortlink != null,
+    });
+}

package/src/admin/storage/BackendsPage.tsx

@@ -0,0 +1,43 @@
+import { useQueryClient } from '@tanstack/react-query';
+import { Badge, ModelTable, fmt, modal, toast, type BatchAction, type Column, type FilterDef } from '../../ui';
+import { useCan } from '../../client';
+import { FileManagerDetail } from './FileManagerDetail';
+import { openFileManagerEditor } from './storage-dialogs';
+import { FileManagerModel, GROUP_DIRECTORY_PERMS, STORAGE_MANAGE_PERMS, USER_DIRECTORY_PERMS, exportFileManagers, storageRelationId, saveFileManagerAtomic, type FileManagerRow } from './models';
+
+function scope(row: FileManagerRow): string { return storageRelationId(row.group) != null ? `Group · ${(typeof row.group === 'object' && row.group?.name) || `#${storageRelationId(row.group)}`}` : storageRelationId(row.user) != null ? `User · ${(typeof row.user === 'object' && row.user && (row.user.display_name || row.user.name)) || `#${storageRelationId(row.user)}`}` : 'System'; }
+const COLUMNS: Column<FileManagerRow>[] = [
+    { key: 'name', label: 'Name', sortable: true, hideable: false },
+    { key: 'backend_type', label: 'Backend', sortable: true, render: (row) => <Badge tone={row.backend_type === 's3' ? 'info' : 'muted'}>{row.backend_type}</Badge> },
+    { key: 'backend_url', label: 'Location', render: (row) => <code>{fmt.truncate(row.backend_url, 36)}</code> },
+    { key: 'scope', label: 'Scope', render: scope },
+    { key: 'is_active', label: 'Active', sortable: true, render: (row) => <Badge tone={row.is_active ? 'success' : 'muted'}>{row.is_active ? 'Active' : 'Inactive'}</Badge> },
+    { key: 'is_default', label: 'Default', sortable: true, render: (row) => row.is_default ? <i className="bi bi-star-fill text-warn" /> : '—' },
+    { key: 'is_public', label: 'Access', sortable: true, render: (row) => <Badge tone={row.is_public ? 'warning' : 'success'}>{row.is_public ? 'Public' : 'Private'}</Badge> },
+    { key: 'aws_region', label: 'Region', render: (row) => row.aws_region || '—' },
+    { key: 'credentials', label: 'Credentials', render: (row) => row.aws_key_masked ? <code>{row.aws_key_masked}</code> : '—' },
+    { key: 'created', label: 'Created', sortable: true, render: (row) => fmt.date(row.created) },
+];
+const FILTERS: FilterDef[] = [
+    { key: 'backend_type', label: 'Backend', type: 'select', options: [{ value: 'file', label: 'File system' }, { value: 's3', label: 'AWS S3' }] },
+    { key: 'is_active', label: 'Active', type: 'boolean' }, { key: 'is_default', label: 'Default', type: 'boolean' }, { key: 'is_public', label: 'Public', type: 'boolean' },
+    { key: 'group__isnull', label: 'Group scope', type: 'boolean', trueLabel: 'No group', falseLabel: 'Has group' },
+];
+
+export function showFileManagerDetail(id: number): void { void modal.detail((close) => <FileManagerDetail id={id} onClose={() => close(null)} />); }
+
+export function BackendsPage() {
+    const queryClient = useQueryClient();
+    const manage = useCan(STORAGE_MANAGE_PERMS);
+    const canManage = manage.can;
+    const canViewGroups = useCan(GROUP_DIRECTORY_PERMS).can;
+    const canViewUsers = useCan(USER_DIRECTORY_PERMS).can;
+    const canCreate = canManage && (Boolean(manage.me?.is_superuser) || canViewGroups || canViewUsers);
+    const saveState = (row: FileManagerRow, active: boolean) => saveFileManagerAtomic({ queryClient, id: row.id, changes: { is_active: active } });
+    const batchActions: BatchAction<FileManagerRow>[] = [
+        { key: 'activate', label: 'Activate', eligible: (row) => !row.is_active, run: (row) => saveState(row, true) },
+        { key: 'deactivate', label: 'Deactivate', eligible: (row) => row.is_active, run: (row) => saveState(row, false) },
+    ];
+    const add = async () => { const row = await openFileManagerEditor('create'); if (row) toast.success(`${row.name} created private`); };
+    return <ModelTable model={FileManagerModel} eyebrow="Infrastructure · Storage" title="Storage Backends" columns={COLUMNS} filters={FILTERS} defaultSort="-created" searchable searchPlaceholder="Search name, backend, description" selectable={canManage} batchActions={canManage ? batchActions : []} columnChooser persistState persistKey="admin:storage:backends" exportFormats={['csv', 'json']} exporter={exportFileManagers} onRowClick={(row) => showFileManagerDetail(row.id)} {...(canCreate ? { addLabel: 'Create backend', onAdd: () => void add() } : {})} />;
+}

package/src/admin/storage/BucketDetail.tsx

@@ -0,0 +1,77 @@
+import { useState } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+import { ArmedButton, DetailView, FlatRow, SchemaForm, fmt, modal, toast } from '../../ui';
+import {
+    BUCKET_MANAGE_PERMS, emptyBucket, setBucketPublic,
+    type BucketEmptyResult, type BucketMutationOutcome, type S3BucketRow, type S3FailureEvidence,
+} from './models';
+
+function message(error: unknown): string { return error instanceof Error ? error.message : 'Storage operation failed'; }
+
+function AggregateEvidence({ label, values }: { label: string; values: Record<string, number | null> | null | undefined }) {
+    if (values === undefined) return null;
+    if (values === null) return <p><b>{label}:</b> Unknown (no safe final probe)</p>;
+    const entries = Object.entries(values);
+    return entries.length > 0 ? <><h4>{label}</h4><dl>{entries.map(([key, value]) => <div key={key}><dt>{key.replaceAll('_', ' ')}</dt><dd>{value == null ? 'Unknown' : value.toLocaleString()}</dd></div>)}</dl></> : null;
+}
+
+function posture(value: boolean | null | undefined): string { return value == null ? 'Unknown' : value ? 'Public' : 'Private'; }
+
+export function IncompleteEvidence({ evidence }: { evidence: S3FailureEvidence }) {
+    const failure = evidence.failure;
+    return <div className="storage-operation-evidence"><b>External operation incomplete: {evidence.mutation_state}</b><p>AWS state may have changed. Stop writers where relevant, correct IAM/provider posture, refresh, and retry.</p><AggregateEvidence label="Acknowledged counts" values={evidence.counts} /><AggregateEvidence label="Failed" values={evidence.failed} /><AggregateEvidence label="Remaining" values={evidence.remaining} />{failure && <dl>{failure.operation !== undefined && <div><dt>Failure operation</dt><dd>{failure.operation}</dd></div>}{failure.provider_code !== undefined && <div><dt>Provider code</dt><dd>{failure.provider_code}</dd></div>}{failure.retryable !== undefined && <div><dt>Retryable</dt><dd>{failure.retryable ? 'Yes' : 'No'}</dd></div>}</dl>}{evidence.requested_public !== undefined && <p>Requested posture: <b>{posture(evidence.requested_public)}</b></p>}{evidence.configured_public !== undefined && <p>Configured posture: <b>{posture(evidence.configured_public)}</b></p>}{evidence.created_new !== undefined && <p>Bucket newly created: <b>{evidence.created_new == null ? 'Unknown' : evidence.created_new ? 'Yes' : 'No'}</b></p>}{evidence.safety_lock && <p>Safety lock: <b>{evidence.safety_lock}</b></p>}</div>;
+}
+
+function Outcome({ value }: { value: BucketMutationOutcome<unknown> | null }) {
+    if (!value) return null;
+    return <div className={`storage-operation-result${value.error ? ' is-error' : ''}`}>{Boolean(value.error) && <p>{message(value.error)}</p>}{value.evidence && <IncompleteEvidence evidence={value.evidence} />}{Boolean(value.refreshError) && <p className="text-warn"><i className="bi bi-exclamation-triangle" /> Authoritative refresh also failed. Refresh manually before another action.</p>}</div>;
+}
+
+export function BucketDetail({ bucket, onClose }: { bucket: S3BucketRow; onClose: () => void }) {
+    const queryClient = useQueryClient();
+    const [outcome, setOutcome] = useState<BucketMutationOutcome<unknown> | null>(null);
+    const [emptyResult, setEmptyResult] = useState<BucketEmptyResult | null>(null);
+
+    const access = async (isPublic: boolean) => {
+        const confirmed = await modal.confirm({
+            title: isPublic ? 'Make whole bucket public?' : 'Make whole bucket private?',
+            message: isPublic
+                ? <>This changes account-level S3 policy and Public Access Block posture for <code>{bucket.name}</code>. Verified configuration does not guarantee every anonymous fetch.</>
+                : <>This applies the all-private Public Access Block posture to <code>{bucket.name}</code>. The operation is externally observable and not atomic.</>,
+            confirmText: isPublic ? 'Make public' : 'Make private', danger: isPublic,
+        });
+        if (!confirmed) return;
+        const next = await setBucketPublic(queryClient, bucket.name, isPublic);
+        setOutcome(next);
+        if (next.data) toast.success(`${bucket.name} verified ${next.data.is_public ? 'public' : 'private'}`);
+    };
+
+    const confirmEmpty = async () => {
+        await modal.open((close) => (
+            <div className="modal-pad">
+                <h2 className="modal-title">Empty {bucket.name}</h2>
+                <p className="modal-message">Irreversibly removes current objects, every version/delete marker, and outstanding multipart uploads. Enter the exact case-sensitive name.</p>
+                <SchemaForm
+                    fields={[{ name: 'confirm_name', type: 'text', label: 'Exact bucket name', required: true }]}
+                    submitText="Empty bucket"
+                    onCancel={() => close(null)}
+                    onSubmit={async (data) => {
+                        const exact = String(data.confirm_name ?? '');
+                        if (exact !== bucket.name) throw new Error('Bucket name does not match exactly. No request was sent.');
+                        const next = await emptyBucket(queryClient, bucket.name, exact);
+                        setOutcome(next);
+                        if (next.error) throw next.error;
+                        if (next.data) { setEmptyResult(next.data); toast.success(`${bucket.name} empty acknowledged`); }
+                        close(true);
+                    }}
+                />
+            </div>
+        ), { size: 'sm' });
+    };
+
+    return <DetailView title={bucket.name} subtitle="Account-level S3 bucket" icon="bi-bucket" chips={[{ text: 'Global', tone: 'info' }]} sections={[
+        { key: 'overview', label: 'Overview', icon: 'bi-info-circle', render: () => <div className="detail-section"><FlatRow label="Name"><code>{bucket.name}</code></FlatRow><FlatRow label="Created">{fmt.datetime(bucket.created)}</FlatRow><FlatRow label="Inventory">Complete account inventory row</FlatRow><Outcome value={outcome} />{emptyResult && <div className="storage-counts"><b>Last acknowledged empty counts</b><span>Objects {emptyResult.deleted_objects}</span><span>Versions {emptyResult.deleted_versions}</span><span>Delete markers {emptyResult.deleted_markers}</span><span>Multipart uploads {emptyResult.aborted_uploads}</span></div>}</div> },
+        { key: 'access', label: 'Access', icon: 'bi-shield-lock', permissions: BUCKET_MANAGE_PERMS, render: () => <div className="detail-section"><h3>Verified access posture</h3><p className="dim">Every attempt refreshes inventory in a finally path. A rejection can still represent partial external change.</p><div className="storage-action-row"><button className="btn btn-danger" onClick={() => void access(true)}>Make public…</button><button className="btn" onClick={() => void access(false)}>Make private…</button></div></div> },
+        { key: 'danger', label: 'Danger zone', icon: 'bi-exclamation-octagon', permissions: BUCKET_MANAGE_PERMS, render: () => <div className="detail-section storage-danger"><h3>Empty bucket</h3><p>Irreversible and non-atomic against active writers. Bucket deletion is unavailable.</p><ArmedButton className="btn-danger" icon="bi-trash3" label="Empty bucket" armedLabel="Click again — remove all objects, versions, markers, and uploads" onConfirm={confirmEmpty} /></div> },
+    ]} initialSection="overview" onClose={onClose} />;
+}

package/src/admin/storage/BucketsPage.tsx

@@ -0,0 +1,64 @@
+import { useMemo, useState } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+import { fmt, modal, toast } from '../../ui';
+import { BucketDetail, IncompleteEvidence } from './BucketDetail';
+import { createBucket, useBuckets, type BucketMutationOutcome, type BucketCreateResult, type S3BucketRow } from './models';
+
+export function showBucketDetail(bucket: S3BucketRow): void {
+    void modal.detail((close) => <BucketDetail bucket={bucket} onClose={() => close(null)} />);
+}
+
+export function BucketsPage() {
+    const queryClient = useQueryClient();
+    const query = useBuckets();
+    const [search, setSearch] = useState('');
+    const [name, setName] = useState('');
+    const [creating, setCreating] = useState(false);
+    const [createOutcome, setCreateOutcome] = useState<BucketMutationOutcome<BucketCreateResult> | null>(null);
+    const rows = useMemo(() => [...(query.data ?? [])]
+        .filter((row) => row.name.toLowerCase().includes(search.trim().toLowerCase()))
+        .sort((a, b) => a.name.localeCompare(b.name)), [query.data, search]);
+
+    const submit = async (event: React.FormEvent) => {
+        event.preventDefault();
+        const bucketName = name.trim();
+        if (!bucketName) return;
+        setCreating(true);
+        setCreateOutcome(null);
+        const outcome = await createBucket(queryClient, bucketName);
+        setCreateOutcome(outcome);
+        setCreating(false);
+        if (outcome.error) {
+            toast.error(outcome.error instanceof Error ? outcome.error.message : 'Bucket create failed');
+            return;
+        }
+        setName('');
+        toast.success(outcome.data?.created_new === false ? `${bucketName} already exists` : `${bucketName} created private`);
+        if (outcome.refreshError) toast.warning('Bucket created, but inventory refresh failed. Retry refresh before another action.');
+    };
+
+    return (
+        <div className="panel storage-buckets">
+            <div className="toolbar">
+                <div className="toolbar-heading"><div className="eyebrow">Infrastructure · Storage</div><h1 className="panel-title">Buckets</h1></div>
+                <button className="btn-icon" title="Refresh bucket inventory" onClick={() => void query.refetch()}>
+                    <i className={`bi bi-arrow-repeat${query.isFetching ? ' spin' : ''}`} />
+                </button>
+            </div>
+            <div className="storage-bucket-tools">
+                <label className="field"><span className="field-label">Local name search</span><input value={search} onChange={(event) => setSearch(event.target.value)} placeholder="Search complete inventory" /></label>
+                <form className="storage-bucket-create" onSubmit={(event) => void submit(event)}>
+                    <label className="field"><span className="field-label">New private bucket</span><input value={name} onChange={(event) => setName(event.target.value)} required placeholder="exact-bucket-name" /></label>
+                    <button className="btn btn-primary" disabled={creating || !name.trim()}>{creating ? 'Creating…' : 'Create private'}</button>
+                </form>
+                {createOutcome && Boolean(createOutcome.evidence || createOutcome.refreshError) && <div className={`storage-operation-result${createOutcome.error ? ' is-error' : ''}`}>{Boolean(createOutcome.error) && <p>{createOutcome.error instanceof Error ? createOutcome.error.message : 'Bucket create failed'}</p>}{createOutcome.evidence && <IncompleteEvidence evidence={createOutcome.evidence} />}{Boolean(createOutcome.refreshError) && <p className="text-warn"><i className="bi bi-exclamation-triangle" /> Authoritative refresh also failed. Refresh manually before another action.</p>}</div>}
+            </div>
+            {query.isError ? (
+                <div className="empty storage-error"><i className="bi bi-cloud-slash" /><h2>Bucket inventory unavailable</h2><p>{query.error instanceof Error ? query.error.message : 'AWS did not return a conclusive inventory.'}</p><button className="btn" onClick={() => void query.refetch()}>Retry</button></div>
+            ) : query.isLoading ? <div className="empty"><i className="bi bi-hourglass-split" /><p>Loading the complete account inventory…</p></div>
+                : rows.length === 0 ? <div className="empty"><i className="bi bi-bucket" /><h2>{query.data?.length ? 'No matching buckets' : 'No buckets'}</h2><p>{query.data?.length ? 'Clear the local name search.' : 'AWS returned a conclusive empty inventory.'}</p></div>
+                    : <div className="tbl-wrap"><table className="tbl"><thead><tr><th>Name</th><th>Created</th><th aria-label="Open" /></tr></thead><tbody>{rows.map((row) => <tr key={row.id} className="row-click" onClick={() => showBucketDetail(row)}><td><code>{row.name}</code></td><td>{fmt.datetime(row.created)}</td><td className="text-end"><i className="bi bi-chevron-right" /></td></tr>)}</tbody></table></div>}
+            <p className="storage-footnote">This is a bounded complete-list surface. Bucket deletion is not supported.</p>
+        </div>
+    );
+}

package/src/admin/storage/FileManagerDetail.tsx

@@ -0,0 +1,36 @@
+import { useQueryClient } from '@tanstack/react-query';
+import { Badge, DetailView, FlatRow, fmt, modal, toast } from '../../ui';
+import { useCan } from '../../client';
+import { FileView } from './FileView';
+import { openFileManagerEditor } from './storage-dialogs';
+import { FileManagerModel, FileModel, GROUP_DIRECTORY_PERMS, STORAGE_MANAGE_PERMS, USER_DIRECTORY_PERMS, storageRelationId, runFileManagerAction, saveFileManagerAtomic } from './models';
+
+function NestedFiles({ managerId }: { managerId: number }) {
+    const query = FileModel.useList({ file_manager: managerId, start: 0, size: 10, sort: '-created' });
+    if (query.isLoading) return <p className="dim">Loading recent files…</p>;
+    if (query.isError) return <div className="form-alert">{query.error instanceof Error ? query.error.message : 'Files unavailable'}</div>;
+    const rows = query.data?.rows ?? [];
+    return <div className="storage-child-files">{rows.length === 0 ? <p className="dim">No files. Upload is unavailable in this release.</p> : rows.map((file) => <button key={file.id} className="storage-child-file" onClick={() => void modal.detail((close) => <FileView id={file.id} onClose={() => close(null)} />)}><span><b>{file.filename}</b><small>{file.content_type} · {fmt.filesize(file.file_size ?? 0)}</small></span><i className="bi bi-chevron-right" /></button>)}</div>;
+}
+
+export function FileManagerDetail({ id, onClose }: { id: number; onClose: () => void }) {
+    const queryClient = useQueryClient();
+    const query = FileManagerModel.useOne(id);
+    const managerPermission = useCan(STORAGE_MANAGE_PERMS);
+    const groupDirectoryPermission = useCan(GROUP_DIRECTORY_PERMS);
+    const userDirectoryPermission = useCan(USER_DIRECTORY_PERMS);
+    const canManage = managerPermission.can;
+    const canChangeOwner = groupDirectoryPermission.can || userDirectoryPermission.can || Boolean(managerPermission.me?.is_superuser);
+    if (query.isLoading) return <div className="empty"><p>Loading storage backend…</p></div>;
+    if (!query.data) return <div className="empty"><h2>Storage backend unavailable</h2><p>{query.error instanceof Error ? query.error.message : 'The record was not returned.'}</p><button className="btn" onClick={onClose}>Close</button></div>;
+    const row = query.data;
+    const edit = async (mode: 'general' | 'credentials' | 'owner') => { const saved = await openFileManagerEditor(mode, row); if (saved) { toast.success(`${saved.name} updated`); await query.refetch(); } };
+    const action = async (name: 'test_connection' | 'check_cors' | 'fix_cors') => { try { const result = await runFileManagerAction(id, name); toast.success(name === 'test_connection' ? 'Connection succeeded' : `${name.replace('_', ' ')} completed`); await modal.open((close) => <div className="modal-pad"><h2 className="modal-title">{name.replaceAll('_', ' ')}</h2><pre className="storage-result-json">{JSON.stringify(result, null, 2)}</pre><div className="modal-actions"><button className="btn" onClick={() => close(null)}>Close</button></div></div>); } catch (error) { toast.error(error instanceof Error ? error.message : `${name} failed`); } };
+    const clone = async () => { const ok = await modal.confirm({ title: 'Clone backend?', message: <>Create a private clone of <b>{row.name}</b> under the same explicit owner scope?</>, confirmText: 'Clone' }); if (!ok) return; try { await runFileManagerAction(id, 'clone'); await FileManagerModel.invalidate(queryClient); toast.success(`${row.name} cloned`); } catch (error) { toast.error(error instanceof Error ? error.message : 'Clone failed'); } };
+    const toggle = async () => { const ok = await modal.confirm({ title: row.is_public ? 'Make backend private?' : 'Make backend public?', message: 'This changes prefix policy on the storage provider. Continue?', confirmText: row.is_public ? 'Make private' : 'Make public', danger: !row.is_public }); if (!ok) return; try { await saveFileManagerAtomic({ queryClient, id, changes: { is_public: !row.is_public } }); await query.refetch(); } catch (error) { toast.error(error instanceof Error ? error.message : 'Access change failed'); } };
+    return <DetailView title={row.name} subtitle={`${row.backend_type} · ${row.backend_url}`} icon="bi-hdd-stack" chips={[{ text: row.is_active ? 'Active' : 'Inactive', tone: row.is_active ? 'success' : 'muted' }, { text: row.is_public ? 'Public' : 'Private', tone: row.is_public ? 'warning' : 'success' }]} sections={[
+        { key: 'overview', label: 'Overview', icon: 'bi-info-circle', render: () => <div className="detail-section"><div className="storage-action-row">{canManage && <><button className="btn" onClick={() => void edit('general')}>Edit</button><button className="btn" onClick={() => void edit('credentials')}>Credentials</button>{canChangeOwner && <button className="btn" onClick={() => void edit('owner')}>Owner scope</button>}<button className="btn" onClick={() => void toggle()}>{row.is_public ? 'Make private…' : 'Make public…'}</button></>}</div><FlatRow label="Backend"><Badge tone="info">{row.backend_type}</Badge></FlatRow><FlatRow label="Use">{row.use || '—'}</FlatRow><FlatRow label="URL"><code>{row.backend_url}</code></FlatRow><FlatRow label="Owner">{storageRelationId(row.group) != null ? `Group #${storageRelationId(row.group)}` : storageRelationId(row.user) != null ? `User #${storageRelationId(row.user)}` : 'System'}</FlatRow><FlatRow label="Default">{row.is_default ? 'Yes' : 'No'}</FlatRow><FlatRow label="Region">{row.aws_region || '—'}</FlatRow><FlatRow label="Access key">{row.aws_key_masked || 'Not configured'}</FlatRow><FlatRow label="Secret key">{row.aws_secret_masked || 'Not configured'}</FlatRow><FlatRow label="Created">{fmt.datetime(row.created)}</FlatRow></div> },
+        { key: 'files', label: 'Files', icon: 'bi-files', render: () => <div className="detail-section"><h3>Recent files</h3><p className="dim">Newest 10 for this backend. This bounded child inventory does not own URL table state.</p><NestedFiles managerId={id} /></div> },
+        { key: 'operations', label: 'Operations', icon: 'bi-tools', permissions: STORAGE_MANAGE_PERMS, render: () => <div className="detail-section"><h3>Provider operations</h3><div className="storage-action-row"><button className="btn" onClick={() => void action('test_connection')}>Test connection</button>{row.backend_type === 's3' && <><button className="btn" onClick={() => void action('check_cors')}>Check CORS</button><button className="btn" onClick={() => void action('fix_cors')}>Fix CORS</button></>}<button className="btn" onClick={() => void clone()}>Clone…</button></div><p className="dim">Backend deletion and public-access audit shortcuts are deliberately unavailable.</p></div> },
+    ]} initialSection="overview" onClose={onClose} />;
+}

package/src/admin/storage/FilePreview.tsx

@@ -0,0 +1,54 @@
+import { useEffect, useRef } from 'react';
+import { openCapabilityUrl, isSafeCapabilityUrl, type FileRow } from './models';
+import { normalizeRenditions } from './file-renditions';
+
+const KNOWN = new Set(['image', 'video', 'audio', 'pdf', 'document', 'spreadsheet', 'presentation', 'archive', 'text', 'csv']);
+
+export function filePreviewCategory(file: Pick<FileRow, 'category' | 'content_type'>): string {
+    if (file.category) return file.category.toLowerCase();
+    const mime = file.content_type.toLowerCase();
+    if (mime.startsWith('image/')) return 'image';
+    if (mime.startsWith('video/')) return 'video';
+    if (mime.startsWith('audio/')) return 'audio';
+    if (mime === 'application/pdf') return 'pdf';
+    if (mime.includes('spreadsheet') || mime.includes('excel') || mime.includes('csv')) return 'spreadsheet';
+    if (mime.includes('presentation') || mime.includes('powerpoint')) return 'presentation';
+    if (mime.includes('word') || mime.includes('document')) return 'document';
+    if (mime.includes('zip') || mime.includes('archive') || mime.includes('tar')) return 'archive';
+    if (mime.startsWith('text/')) return 'text';
+    return 'unknown';
+}
+
+function SafeActions({ url, download = true }: { url: string | null | undefined; download?: boolean }) {
+    if (!isSafeCapabilityUrl(url)) return <p className="storage-unsafe"><i className="bi bi-shield-exclamation" /> URL withheld: the capability value is missing or unsafe.</p>;
+    return <div className="storage-action-row"><button className="btn" onClick={() => openCapabilityUrl(url)}><i className="bi bi-box-arrow-up-right" /> Open</button>{download && <button className="btn" onClick={() => openCapabilityUrl(url, true)}><i className="bi bi-download" /> Download</button>}</div>;
+}
+
+/** Captures one safe media source for this mounted File id. */
+export function StableMediaPreview({ file }: { file: FileRow }) {
+    const source = useRef(isSafeCapabilityUrl(file.url) ? file.url : null);
+    const category = filePreviewCategory(file);
+    if (!source.current) return <SafeActions url={file.url} />;
+    if (category === 'video') return <video className="storage-media" controls src={source.current} preload="metadata" />;
+    return <audio className="storage-media storage-audio" controls src={source.current} preload="metadata" />;
+}
+
+export function FilePreview({ file }: { file: FileRow }) {
+    const category = filePreviewCategory(file);
+    const warned = useRef(false);
+    useEffect(() => {
+        if (!KNOWN.has(category) && !warned.current) {
+            warned.current = true;
+            console.warn(`FilePreview: unknown category "${category}" — using safe generic actions`);
+        }
+    }, [category]);
+    if (category === 'image') return isSafeCapabilityUrl(file.url) ? <div className="storage-preview"><img src={file.url} alt={file.filename} referrerPolicy="no-referrer" /><SafeActions url={file.url} /></div> : <SafeActions url={file.url} />;
+    if (category === 'video' || category === 'audio') return <div className="storage-preview"><StableMediaPreview file={file} /><SafeActions url={file.url} /></div>;
+    if (['document', 'spreadsheet', 'presentation'].includes(category)) {
+        const image = normalizeRenditions(file.renditions).find((row) => row.content_type.startsWith('image/') && isSafeCapabilityUrl(row.url));
+        return <div className="storage-preview">{image?.url && <img src={image.url} alt={`${file.filename} preview`} referrerPolicy="no-referrer" />}<SafeActions url={file.url} /></div>;
+    }
+    if (category === 'archive') return <div className="storage-generic-preview"><i className="bi bi-file-earmark-zip" /><h3>{file.filename}</h3><SafeActions url={file.url} /></div>;
+    if (category === 'pdf') return <div className="storage-generic-preview"><i className="bi bi-file-earmark-pdf" /><h3>PDF document</h3><SafeActions url={file.url} download={false} /></div>;
+    return <div className="storage-generic-preview"><i className="bi bi-file-earmark" /><h3>{file.filename}</h3><p>{file.content_type}</p><SafeActions url={file.url} /></div>;
+}