portal-mojo 0.2.0 → 0.2.1

package/docs/README.md

@@ -13,7 +13,7 @@ everything: run the showcase (`npm run dev:showcase`) → **Develop → Componen
 | [auth.md](auth.md) | Login flows, token upkeep, hosted-auth (bouncer page) bridge, auth events |
 | [realtime.md](realtime.md) | Auth-challenged WebSocket lifecycle, heartbeat/backoff, refcounted topics, typed event projection, deterministic mock |
 | [auth-pages.md](auth-pages.md) | The in-app auth pages: routes + guard, `VITE_MOJO_AUTH` switch, fresh-auth (440 step-up) modal, MFA panel, password tools |
-| [admin-credentials.md](admin-credentials.md) | Group API keys and webhook subscriptions — dual-mount pages, permission registry, secret-safe create/reveal/rotation |
+| [admin-credentials.md](admin-credentials.md) | Group API keys and webhook subscriptions — dual-mount pages, lossless per-endpoint rate limits, permission registry, secret-safe create/reveal/rotation |
 | [admin-dashboard.md](admin-dashboard.md) | Package-owned global Admin landing, authoritative signals, independent gates, caller-isolated caches, and root fallback |
 | [admin-cloudwatch.md](admin-cloudwatch.md) | Global EC2/RDS/Redis CloudWatch charts, exact resource/fetch wires, constrained controls, refresh ownership, and modal details |
 | [admin-monitoring.md](admin-monitoring.md) | Monitoring Admin registration, logs, and exact Redis-backed metrics-permission mutations |

package/docs/admin-credentials.md

@@ -30,8 +30,12 @@ the current operator can see.
 
 ```tsx
 import {
+  ApiKeyLimitsSummary,
+  ApiKeyRateLimitsEditor,
   GroupApiKeysSection,
   GroupApiKeysPage,
+  buildApiKeyLimitPatch,
+  readApiKeyRateLimits,
   registerGroupApiKeyPermissions,
 } from 'portal-mojo/admin';
 
@@ -85,6 +89,66 @@ Registration replaces the same permission name and appends new names. Mounted
 editors subscribe to changes. `grantPermissions` gates the control itself; the
 backend remains authoritative on every save.
 
+### Rate-limit overrides
+
+Group API keys expose the raw django-mojo JSONField shape without normalizing
+endpoint identity:
+
+```ts
+const limits = {
+  orders: { limit: 500, window: 5, extension_owned: { burst: 20 } },
+};
+
+const state = readApiKeyRateLimits(limits);
+const patch = buildApiKeyLimitPatch(
+  'orders',
+  { limit: 750, window: 10 },
+  limits.orders, // preserves extension_owned and every other nested sibling
+);
+```
+
+`limit` and `window` are positive integers with no fixed maximum. `window` is
+always measured in **minutes** in `ApiKey.limits`; django-mojo converts it to
+seconds at enforcement time. `ApiKeyLimitsSummary` is the bounded card/table
+presentation. `ApiKeyRateLimitsEditor` is the controlled detail editor and
+keeps saves on the rejecting `GroupApiKeyModel.useSave()` path.
+
+This UI depends on django-mojo 1.20.0 / item 3105. A genuinely empty object is
+shown as **Unlimited (default)** because ordinary API-key throughput has no
+built-in hard ceiling. Strict endpoint limits, a positive decorator fallback,
+or an enabled deployment ceiling may still apply. When safe overrides exist,
+unlisted ordinary endpoint buckets remain unlimited. Any malformed top-level
+or nested value shows **Review required** instead of either safe claim.
+
+Add trims the new endpoint name and rejects blank, duplicate, and reserved
+`__replace` names. Edit keeps the stored endpoint identity immutable. Clear
+sends one narrow null tombstone, for example `{limits: {orders: null}}`; the
+authoritative complete row returned by django-mojo replaces Query state while
+every unrelated endpoint remains intact.
+
+Legacy data is lossless:
+
+- empty and whitespace-only keys are quoted distinctly and clear only by their
+  exact raw key;
+- scalar entries may be cleared but not edited as structured limits;
+- partial object entries may be repaired, preserving extra nested siblings. A
+  positive limit with no `window` currently uses the endpoint decorator's
+  default window; other malformed/non-positive entries fail open;
+- valid entries with extra siblings retain them on edit;
+- a stored `__replace` root key is read-only. django-mojo consumes that name as
+  a JSON replacement signal, so generic edit/clear controls would be dishonest;
+  repair the full stored value outside this editor.
+
+Mutation controls are fail-closed behind the supplied `PermSpec`. The global
+detail uses `GLOBAL_CREDENTIAL_PERMS`; embedded group surfaces default to
+`GROUP_CREDENTIAL_PERMS`. Denied viewers receive no mutation controls or extra
+credential queries. Limit mutations never request the token graph and retain
+the existing pre-cache token scrubber.
+
+Pitfalls: do not clone the raw object into a typed-only map, trim an existing
+key, send `__replace`, label malformed data unlimited, measure windows in
+seconds, or replace the full JSONField to clear one endpoint.
+
 ## Webhooks
 
 ```tsx

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "portal-mojo",
-    "version": "0.2.0",
+    "version": "0.2.1",
     "description": "React portal toolkit for django-mojo — typed client + params store, mission-control UI, dependency-free SVG charts, admin section bundles.",
     "type": "module",
     "license": "Apache-2.0",

package/src/admin/credentials/api-key-rate-limits.tsx

@@ -0,0 +1,284 @@
+import { useCan, type PermSpec } from '../../client/runtime';
+import { Badge, SchemaForm, modal, toast, type Field, type FormData } from '../../ui';
+import { z } from 'zod';
+import {
+    GROUP_CREDENTIAL_PERMS, GroupApiKeyModel,
+    buildApiKeyLimitPatch, readApiKeyRateLimits, validateApiKeyRateLimitInput,
+    type ApiKeyRateLimitEntry, type GroupApiKeyRow,
+} from './models';
+
+function endpointLabel(rawEndpoint: string): string {
+    return JSON.stringify(rawEndpoint);
+}
+
+function rawValueLabel(value: unknown): string {
+    if (value === undefined) return 'undefined';
+    try {
+        const serialized = JSON.stringify(value);
+        return serialized === undefined ? String(value) : serialized;
+    } catch {
+        return String(value);
+    }
+}
+
+function entryTone(entry: ApiKeyRateLimitEntry): 'success' | 'warning' | 'danger' {
+    if (entry.kind === 'valid') return 'success';
+    if (entry.kind === 'reserved' || entry.kind === 'scalar') return 'danger';
+    return 'warning';
+}
+
+/** Compact, bounded rate-limit state for cards and table cells. */
+export function ApiKeyLimitsSummary({ limits, maxEntries = 2 }: {
+    limits: unknown;
+    maxEntries?: number;
+}) {
+    const read = readApiKeyRateLimits(limits);
+    if (read.isEmpty) {
+        return (
+            <span className="ga-limit-summary ga-limit-summary-empty">
+                <i className="bi bi-infinity" /> Unlimited (default)
+            </span>
+        );
+    }
+    if (!read.isObject || read.hasUnsafe) {
+        const visible = read.entries.slice(0, Math.max(0, maxEntries));
+        return (
+            <span className="ga-limit-summary ga-limit-summary-review" title="Stored rate limits require review">
+                <span><i className="bi bi-exclamation-triangle" /> Review required</span>
+                {visible.map((entry) => (
+                    <code key={entry.rawEndpoint}>{endpointLabel(entry.rawEndpoint)}</code>
+                ))}
+                {read.entries.length > visible.length && <span>+{read.entries.length - visible.length}</span>}
+            </span>
+        );
+    }
+    const visible = read.entries.slice(0, Math.max(0, maxEntries));
+    return (
+        <span className="ga-limit-summary ga-limit-summary-configured">
+            {visible.map((entry) => (
+                <code key={entry.rawEndpoint}>
+                    {entry.rawEndpoint} {entry.override!.limit}/{entry.override!.window}m
+                </code>
+            ))}
+            {read.entries.length > visible.length && <span>+{read.entries.length - visible.length}</span>}
+            <span className="ga-limit-summary-note">all other endpoints unlimited</span>
+        </span>
+    );
+}
+
+const positiveIntegerSchema = (label: string) => z.any().refine((value) => {
+    if (typeof value === 'boolean') return false;
+    const text = String(value ?? '').trim();
+    if (!text) return false;
+    const parsed = Number(text);
+    return Number.isInteger(parsed) && parsed > 0;
+}, { message: `${label} must be a positive integer.` });
+
+const LIMIT_FIELDS: Field[] = [
+    {
+        name: 'limit', type: 'text', label: 'Request limit', required: true,
+        min: 1, step: 1, columns: 6,
+        schema: positiveIntegerSchema('Request limit'),
+        help: 'Positive whole number; there is no fixed maximum.',
+    },
+    {
+        name: 'window', type: 'text', label: 'Window (minutes)', required: true,
+        min: 1, step: 1, columns: 6,
+        schema: positiveIntegerSchema('Window in minutes'),
+        help: 'Positive whole number of minutes.',
+    },
+];
+
+const ADD_FIELDS: Field[] = [
+    {
+        name: 'endpoint', type: 'text', label: 'Endpoint key', required: true,
+        placeholder: 'orders',
+        help: 'The endpoint decorator bucket key. New names are trimmed and cannot be renamed.',
+    },
+    ...LIMIT_FIELDS,
+];
+
+function initialEntry(entry: ApiKeyRateLimitEntry): FormData {
+    const raw = entry.rawValue && typeof entry.rawValue === 'object' && !Array.isArray(entry.rawValue)
+        ? entry.rawValue as Record<string, unknown>
+        : {};
+    return {
+        limit: typeof raw.limit === 'number' && Number.isInteger(raw.limit) && raw.limit > 0 ? raw.limit : '',
+        window: typeof raw.window === 'number' && Number.isInteger(raw.window) && raw.window > 0 ? raw.window : '',
+    };
+}
+
+/** Lossless detail editor. All mutation controls stay behind the supplied gate. */
+export function ApiKeyRateLimitsEditor({ row, permission = GROUP_CREDENTIAL_PERMS }: {
+    row: GroupApiKeyRow;
+    permission?: PermSpec;
+}) {
+    const { can } = useCan(permission);
+    const save = GroupApiKeyModel.useSave();
+    const read = readApiKeyRateLimits(row.limits);
+
+    const savePatch = async (patch: Record<string, unknown>, success: string) => {
+        try {
+            const saved = await save.mutateAsync({ id: row.id, changes: { limits: patch } });
+            toast.success(success);
+            return saved;
+        } catch (error) {
+            const message = error instanceof Error ? error.message : 'Failed to save the rate limit override';
+            toast.error(message);
+            throw error instanceof Error ? error : new Error(message);
+        }
+    };
+
+    const openAdd = () => {
+        if (!can || !read.isObject || save.isPending) return;
+        let pending = false;
+        void modal.open<GroupApiKeyRow | null>((close) => (
+            <div className="modal-pad">
+                <h2 className="modal-title">Add rate limit override</h2>
+                <p className="dim">This creates a hard per-key ceiling for one endpoint bucket.</p>
+                <SchemaForm
+                    fields={ADD_FIELDS}
+                    submitText="Add override"
+                    onBusyChange={(busy) => { pending = busy; }}
+                    onCancel={() => close(null)}
+                    onSubmit={async (form) => {
+                        const parsed = validateApiKeyRateLimitInput(form, { existing: row.limits });
+                        const saved = await savePatch(
+                            buildApiKeyLimitPatch(parsed.endpoint, parsed.override),
+                            'Rate limit override added',
+                        );
+                        close(saved);
+                        return saved;
+                    }}
+                />
+            </div>
+        ), { size: 'sm', canDismiss: () => !pending });
+    };
+
+    const openEdit = (entry: ApiKeyRateLimitEntry) => {
+        if (!can || !entry.canEdit || save.isPending) return;
+        let pending = false;
+        void modal.open<GroupApiKeyRow | null>((close) => (
+            <div className="modal-pad">
+                <h2 className="modal-title">{entry.kind === 'valid' ? 'Edit' : 'Repair'} rate limit override</h2>
+                <p className="dim">
+                    Endpoint identity is immutable: <code>{endpointLabel(entry.rawEndpoint)}</code>
+                </p>
+                <SchemaForm
+                    fields={LIMIT_FIELDS}
+                    initial={initialEntry(entry)}
+                    submitText={entry.kind === 'valid' ? 'Save override' : 'Repair override'}
+                    onBusyChange={(busy) => { pending = busy; }}
+                    onCancel={() => close(null)}
+                    onSubmit={async (form) => {
+                        const parsed = validateApiKeyRateLimitInput(form, { fixedEndpoint: entry.rawEndpoint });
+                        const saved = await savePatch(
+                            buildApiKeyLimitPatch(entry.rawEndpoint, parsed.override, entry.rawValue),
+                            entry.kind === 'valid' ? 'Rate limit override updated' : 'Rate limit override repaired',
+                        );
+                        close(saved);
+                        return saved;
+                    }}
+                />
+            </div>
+        ), { size: 'sm', canDismiss: () => !pending });
+    };
+
+    const clearEntry = async (entry: ApiKeyRateLimitEntry) => {
+        if (!can || !entry.canClear || save.isPending) return;
+        const confirmed = await modal.confirm({
+            title: 'Clear rate limit override?',
+            message: (
+                <>
+                    Clear the exact stored endpoint <code>{endpointLabel(entry.rawEndpoint)}</code>?
+                    Other endpoints and extension-owned values are preserved. Clearing may increase throughput.
+                </>
+            ),
+            confirmText: 'Clear override',
+            danger: true,
+        });
+        if (!confirmed) return;
+        try {
+            await savePatch(buildApiKeyLimitPatch(entry.rawEndpoint, null), 'Rate limit override cleared');
+        } catch {
+            // savePatch already surfaced the rejecting save through the shared toast.
+        }
+    };
+
+    if (!read.isObject) {
+        return (
+            <div className="ga-limit-review" role="alert">
+                <i className="bi bi-exclamation-triangle" />
+                <div>
+                    <b>Stored rate limits are malformed.</b>
+                    <p>They do not create a per-key hard ceiling and cannot be edited safely here. Repair the full value through the backend.</p>
+                </div>
+            </div>
+        );
+    }
+
+    return (
+        <div className="ga-limit-editor">
+            <div className="ga-limit-head">
+                <div>
+                    <h3>Per-endpoint hard overrides</h3>
+                    <p className="dim">Windows are stored in minutes. The backend remains authoritative on every save.</p>
+                </div>
+                {can && (
+                    <button className="btn btn-primary btn-compact" disabled={save.isPending} onClick={openAdd}>
+                        <i className="bi bi-plus-lg" /> Add override
+                    </button>
+                )}
+            </div>
+
+            {read.isEmpty ? (
+                <div className="ga-limit-empty">
+                    <b><i className="bi bi-infinity" /> Unlimited (default)</b>
+                    <p>No per-key hard overrides are configured. Strict endpoint limits, positive decorator fallbacks, and enabled deployment ceilings can still apply.</p>
+                </div>
+            ) : (
+                <>
+                    {read.hasUnsafe ? (
+                        <div className="ga-limit-review" role="alert">
+                            <i className="bi bi-exclamation-triangle" />
+                            <div><b>Review stored rate limits.</b><p>Unsafe entries are preserved and are not treated as an unlimited or valid configured state.</p></div>
+                        </div>
+                    ) : (
+                        <p className="ga-limit-policy-note">
+                            These endpoints have explicit hard ceilings; every unlisted ordinary endpoint remains unlimited by default.
+                        </p>
+                    )}
+                    <div className="ga-limit-table-wrap">
+                        <table className="ga-limit-table">
+                            <thead><tr><th>Endpoint key</th><th>Limit</th><th>Window</th><th>State</th><th>Actions</th></tr></thead>
+                            <tbody>
+                                {read.entries.map((entry) => (
+                                    <tr key={entry.rawEndpoint}>
+                                        <td><code>{endpointLabel(entry.rawEndpoint)}</code></td>
+                                        <td>{entry.override?.limit ?? '—'}</td>
+                                        <td>{entry.override ? `${entry.override.window} min` : '—'}</td>
+                                        <td>
+                                            <Badge tone={entryTone(entry)}>
+                                                {entry.kind === 'valid' ? 'Configured' : entry.kind === 'repairable' ? 'Repairable' : entry.kind === 'reserved' ? 'Backend repair' : 'Invalid scalar'}
+                                            </Badge>
+                                            {entry.issue && <small className="ga-limit-issue">{entry.issue}</small>}
+                                            {entry.kind !== 'valid' && <small className="ga-limit-raw">Raw: {rawValueLabel(entry.rawValue)}</small>}
+                                        </td>
+                                        <td>
+                                            {can && (entry.canEdit || entry.canClear) ? (
+                                                <span className="ga-limit-actions">
+                                                    {entry.canEdit && <button className="btn btn-compact" disabled={save.isPending} onClick={() => openEdit(entry)}>{entry.kind === 'valid' ? 'Edit' : 'Repair'}</button>}
+                                                    {entry.canClear && <button className="btn btn-compact btn-danger-ghost" disabled={save.isPending} onClick={() => void clearEntry(entry)}>Clear</button>}
+                                                </span>
+                                            ) : <span className="dim">Read only</span>}
+                                        </td>
+                                    </tr>
+                                ))}
+                            </tbody>
+                        </table>
+                    </div>
+                </>
+            )}
+        </div>
+    );
+}

package/src/admin/credentials/group-api-keys.tsx

@@ -14,9 +14,10 @@ import {
     GroupApiKeyModel, fetchApiKeyToken,
     getGroupApiKeyPermissions, grantedPermissions,
     groupApiKeyPermissionsVersion, subscribeGroupApiKeyPermissions,
-    useCreateGroupApiKey,
+    readApiKeyRateLimits, useCreateGroupApiKey,
     type ApiKeyPermissionDef, type CredentialGroup, type GroupApiKeyRow,
 } from './models';
+import { ApiKeyLimitsSummary, ApiKeyRateLimitsEditor } from './api-key-rate-limits';
 import { showSecretDialog } from './secret-dialog';
 
 function groupLabel(group: GroupApiKeyRow['group']): string {
@@ -257,6 +258,7 @@ function ApiKeyCard({ row, actions }: {
                         ? permissions.map((permission) => <Badge key={permission} tone="info">{permission}</Badge>)
                         : <span className="dim-italic">No permissions granted</span>}
                 </div>
+                <ApiKeyLimitsSummary limits={row.limits} />
                 <div className="dim ga-card-meta">
                     Last used <b>{fmt.relative(row.last_used, 'never')}</b> · Created {fmt.date(row.created)}
                     {row.expires_at != null && <> · Expires {fmt.date(row.expires_at)}</>}
@@ -315,12 +317,18 @@ export function GroupApiKeysSection({ group, permission = GROUP_CREDENTIAL_PERMS
     return <GroupApiKeysContent group={group} permission={permission} />;
 }
 
-export function GroupApiKeyDetail({ id, onClose }: { id: number; onClose: () => void }) {
+function AuthorizedGroupApiKeyDetail({ id, onClose }: { id: number; onClose: () => void }) {
     const { data: row, isPending, error } = GroupApiKeyModel.useOne(id);
     const actions = useGroupApiKeyActions(GLOBAL_CREDENTIAL_PERMS);
     if (isPending) return <div className="modal-pad dim">Loading API key…</div>;
     if (!row || error) return <div className="modal-pad text-bad">{error?.message ?? 'API key not found'}</div>;
     const permissions = grantedPermissions(row.permissions);
+    const limits = readApiKeyRateLimits(row.limits);
+    const limitsChip = limits.isEmpty
+        ? { text: 'Unlimited (default)', tone: 'muted' as const }
+        : limits.hasUnsafe || !limits.isObject
+            ? { text: 'Limits review required', tone: 'warning' as const }
+            : { text: `${limits.entries.length} rate limit${limits.entries.length === 1 ? '' : 's'}`, tone: 'info' as const };
     return (
         <DetailView
             icon="bi-key"
@@ -329,6 +337,7 @@ export function GroupApiKeyDetail({ id, onClose }: { id: number; onClose: () =>
             chips={[
                 { text: row.is_active ? 'Active' : 'Inactive', tone: row.is_active ? 'success' : 'muted' },
                 { text: `${permissions.length} grants`, tone: 'info' },
+                limitsChip,
             ]}
             sections={[
                 {
@@ -339,22 +348,24 @@ export function GroupApiKeyDetail({ id, onClose }: { id: number; onClose: () =>
                             <FlatRow label="Created">{fmt.datetime(row.created)}</FlatRow>
                             <FlatRow label="Last used">{fmt.relative(row.last_used, 'never')}</FlatRow>
                             <FlatRow label="Expires">{row.expires_at ? fmt.datetime(row.expires_at) : 'Never'}</FlatRow>
-                            <div className="ga-toolbar" style={{ marginTop: 16 }}>
-                                <button className="btn btn-compact" onClick={() => void actions.editKey(row)}>
-                                    <i className="bi bi-pencil" /> Edit
-                                </button>
-                                <button className="btn btn-compact" onClick={() => void actions.revealToken(row)}>
-                                    <i className="bi bi-eye" /> Reveal audited token
-                                </button>
-                                <ArmedButton
-                                    className="btn-compact"
-                                    label="Delete"
-                                    armedLabel="Click again — delete now"
-                                    onConfirm={async () => {
-                                        if (await actions.deleteKey(row)) onClose();
-                                    }}
-                                />
-                            </div>
+                            {actions.canManage && (
+                                <div className="ga-toolbar" style={{ marginTop: 16 }}>
+                                    <button className="btn btn-compact" onClick={() => void actions.editKey(row)}>
+                                        <i className="bi bi-pencil" /> Edit
+                                    </button>
+                                    <button className="btn btn-compact" onClick={() => void actions.revealToken(row)}>
+                                        <i className="bi bi-eye" /> Reveal audited token
+                                    </button>
+                                    <ArmedButton
+                                        className="btn-compact"
+                                        label="Delete"
+                                        armedLabel="Click again — delete now"
+                                        onConfirm={async () => {
+                                            if (await actions.deleteKey(row)) onClose();
+                                        }}
+                                    />
+                                </div>
+                            )}
                         </>
                     ),
                 },
@@ -371,6 +382,11 @@ export function GroupApiKeyDetail({ id, onClose }: { id: number; onClose: () =>
                         </>
                     ),
                 },
+                {
+                    key: 'limits', label: 'Rate Limits', icon: 'bi-speedometer2', render: () => (
+                        <ApiKeyRateLimitsEditor row={row} permission={GLOBAL_CREDENTIAL_PERMS} />
+                    ),
+                },
             ]}
             initialSection="permissions"
             onClose={onClose}
@@ -378,6 +394,12 @@ export function GroupApiKeyDetail({ id, onClose }: { id: number; onClose: () =>
     );
 }
 
+export function GroupApiKeyDetail({ id, onClose }: { id: number; onClose: () => void }) {
+    const { can } = useCan(GLOBAL_CREDENTIAL_PERMS);
+    if (!can) return <div className="modal-pad dim">API key details are unavailable for this account.</div>;
+    return <AuthorizedGroupApiKeyDetail id={id} onClose={onClose} />;
+}
+
 const API_KEY_COLUMNS: Column<GroupApiKeyRow>[] = [
     {
         key: 'name', label: 'Key', sortable: true, hideable: false, render: (row) => (
@@ -390,6 +412,7 @@ const API_KEY_COLUMNS: Column<GroupApiKeyRow>[] = [
     { key: 'group', label: 'Group', render: (row) => groupLabel(row.group) },
     { key: 'is_active', label: 'Status', render: (row) => <Badge tone={row.is_active ? 'success' : 'muted'}>{row.is_active ? 'Active' : 'Inactive'}</Badge> },
     { key: 'permissions', label: 'Grants', align: 'center', render: (row) => String(grantedPermissions(row.permissions).length) },
+    { key: 'limits', label: 'Limits', hideable: false, render: (row) => <ApiKeyLimitsSummary limits={row.limits} /> },
     { key: 'last_used', label: 'Last used', sortable: true, render: (row) => fmt.relative(row.last_used, 'never') },
     { key: 'created', label: 'Created', sortable: true, render: (row) => fmt.date(row.created) },
 ];

package/src/admin/credentials/index.ts

@@ -1,4 +1,5 @@
 export * from './models';
 export * from './secret-dialog';
+export * from './api-key-rate-limits';
 export * from './group-api-keys';
 export * from './webhook-subscriptions';

package/src/admin/credentials/models.ts

@@ -35,6 +35,166 @@ export interface GroupApiKeyRow {
     user: unknown | null;
 }
 
+export interface ApiKeyRateLimitOverride {
+    /** Requests permitted inside `window`. Positive whole number, no fixed maximum. */
+    limit: number;
+    /** Window length in minutes. Positive whole number, no fixed maximum. */
+    window: number;
+}
+
+export type ApiKeyRateLimitEntryKind = 'valid' | 'repairable' | 'scalar' | 'reserved';
+
+/** A derived view of one raw `ApiKey.limits` entry. The source value is never rewritten. */
+export interface ApiKeyRateLimitEntry {
+    rawEndpoint: string;
+    rawValue: unknown;
+    kind: ApiKeyRateLimitEntryKind;
+    override: ApiKeyRateLimitOverride | null;
+    issue: string | null;
+    canEdit: boolean;
+    canClear: boolean;
+}
+
+export interface ApiKeyRateLimitsRead {
+    /** False when the top-level wire value is not a JSON object. */
+    isObject: boolean;
+    /** True only for a valid, genuinely empty object. */
+    isEmpty: boolean;
+    /** Unsafe top-level or entry data prevents an unlimited/configured-safe claim. */
+    hasUnsafe: boolean;
+    entries: ApiKeyRateLimitEntry[];
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+    return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isPositiveInteger(value: unknown): value is number {
+    return typeof value === 'number' && Number.isInteger(value) && value > 0;
+}
+
+/**
+ * Derive editable and review-required entries without normalizing raw endpoint
+ * identity or discarding extension-owned values.
+ */
+export function readApiKeyRateLimits(raw: unknown): ApiKeyRateLimitsRead {
+    if (!isPlainObject(raw)) {
+        return { isObject: false, isEmpty: false, hasUnsafe: true, entries: [] };
+    }
+    const entries = Object.entries(raw)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map<ApiKeyRateLimitEntry>(([rawEndpoint, rawValue]) => {
+            const reserved = rawEndpoint === '__replace';
+            const blank = rawEndpoint.trim().length === 0;
+            const objectValue = isPlainObject(rawValue);
+            const validValue = objectValue
+                && isPositiveInteger(rawValue.limit)
+                && isPositiveInteger(rawValue.window);
+
+            if (reserved) {
+                return {
+                    rawEndpoint, rawValue, kind: 'reserved', override: null,
+                    issue: 'Reserved __replace data cannot be changed or cleared by a generic JSON update. Repair the full stored value outside this editor.',
+                    canEdit: false, canClear: false,
+                };
+            }
+            if (blank) {
+                return {
+                    rawEndpoint, rawValue, kind: objectValue ? 'repairable' : 'scalar', override: null,
+                    issue: 'The stored endpoint key is empty or whitespace-only. It may only be cleared using its exact raw identity.',
+                    canEdit: false, canClear: true,
+                };
+            }
+            if (validValue) {
+                return {
+                    rawEndpoint, rawValue, kind: 'valid',
+                    override: { limit: rawValue.limit as number, window: rawValue.window as number },
+                    issue: null, canEdit: true, canClear: true,
+                };
+            }
+            if (objectValue) {
+                const usesDecoratorWindow = isPositiveInteger(rawValue.limit)
+                    && !Object.prototype.hasOwnProperty.call(rawValue, 'window');
+                return {
+                    rawEndpoint, rawValue, kind: 'repairable', override: null,
+                    issue: usesDecoratorWindow
+                        ? 'Legacy override has no explicit window. The server uses the endpoint decorator default; repair it to store a positive whole-minute window.'
+                        : 'Invalid stored override: limit and window must both be positive integers in minutes. This entry does not create a per-key hard ceiling.',
+                    canEdit: true, canClear: true,
+                };
+            }
+            return {
+                rawEndpoint, rawValue, kind: 'scalar', override: null,
+                issue: 'Stored override is not an object. It may be cleared, but cannot be edited as a structured limit.',
+                canEdit: false, canClear: true,
+            };
+        });
+    return {
+        isObject: true,
+        isEmpty: entries.length === 0,
+        hasUnsafe: entries.some((entry) => entry.kind !== 'valid'),
+        entries,
+    };
+}
+
+export interface ApiKeyRateLimitInput {
+    endpoint?: unknown;
+    limit?: unknown;
+    window?: unknown;
+}
+
+function parsePositiveInteger(value: unknown, label: string): number {
+    if (typeof value === 'boolean') throw new Error(`${label} must be a positive integer.`);
+    const parsed = typeof value === 'number' ? value : Number(String(value ?? '').trim());
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new Error(`${label} must be a positive integer.`);
+    }
+    return parsed;
+}
+
+/** Validate normalized Add input or an immutable existing endpoint Edit. */
+export function validateApiKeyRateLimitInput(
+    input: ApiKeyRateLimitInput,
+    options: { existing?: unknown; fixedEndpoint?: string } = {},
+): { endpoint: string; override: ApiKeyRateLimitOverride } {
+    const adding = options.fixedEndpoint === undefined;
+    const endpoint = adding ? String(input.endpoint ?? '').trim() : options.fixedEndpoint!;
+    if (!endpoint) throw new Error('Endpoint key is required.');
+    if (endpoint === '__replace') throw new Error('__replace is reserved and cannot be used as an endpoint key.');
+    if (adding && isPlainObject(options.existing)
+        && Object.prototype.hasOwnProperty.call(options.existing, endpoint)) {
+        throw new Error('That endpoint key already has an override. Edit the existing row instead.');
+    }
+    return {
+        endpoint,
+        override: {
+            limit: parsePositiveInteger(input.limit, 'Request limit'),
+            window: parsePositiveInteger(input.window, 'Window in minutes'),
+        },
+    };
+}
+
+/**
+ * Build one narrow JSONField patch. `currentValue` is optional for Add; Edit
+ * passes the exact raw object so extension-owned nested siblings survive the
+ * backend's recursive merge. Null is an exact-key tombstone after django-mojo
+ * 3105. The reserved root signal is deliberately impossible to target.
+ */
+export function buildApiKeyLimitPatch(
+    rawEndpoint: string,
+    override: ApiKeyRateLimitOverride | null,
+    currentValue?: unknown,
+): Record<string, unknown> {
+    if (rawEndpoint === '__replace') {
+        throw new Error('__replace is a reserved JSON update signal and cannot be edited or cleared here.');
+    }
+    if (override === null) return { [rawEndpoint]: null };
+    const limit = parsePositiveInteger(override.limit, 'Request limit');
+    const window = parsePositiveInteger(override.window, 'Window in minutes');
+    const preserved = isPlainObject(currentValue) ? currentValue : {};
+    return { [rawEndpoint]: { ...preserved, limit, window } };
+}
+
 interface GroupApiKeyCreateResponse extends GroupApiKeyRow {
     /** Present on the create echo only. Never written to Query cache. */
     token?: string;

package/src/admin/messaging/models.ts

@@ -15,13 +15,13 @@ export type EmailDnsMode = 'manual' | 'route53' | 'godaddy' | 'unknown';
 export type SentMessageStatus = 'queued' | 'sending' | 'delivered' | 'bounced' | 'complained' | 'failed' | 'unknown';
 
 export interface EmailDomainRow {
-    id: number; created: number; modified: number; name: string; region: string; status: EmailDomainStatus;
+    id: number; created: number | null; modified: number | null; name: string; region: string; status: EmailDomainStatus;
     receiving_enabled: boolean; s3_inbound_bucket: string | null; s3_inbound_prefix: string; dns_mode: EmailDnsMode;
     aws_key_masked?: string | null; aws_secret_masked?: string | null;
     sns_topic_bounce_arn?: string | null; sns_topic_complaint_arn?: string | null; sns_topic_delivery_arn?: string | null; sns_topic_inbound_arn?: string | null;
 }
 export interface MailboxRow {
-    id: number; created: number; modified: number; email: string; domain: MessagingRelation | number | null;
+    id: number; created: number | null; modified: number | null; email: string; domain: MessagingRelation | number | null;
     allow_inbound: boolean; allow_outbound: boolean; async_handler: string | null;
     is_system_default: boolean; is_domain_default: boolean;
 }
@@ -31,7 +31,7 @@ export interface SentMessageRow {
     ses_message_id: string | null; status_reason?: string | null; body_text?: string | null; body_html?: string | null;
 }
 export interface EmailTemplateRow {
-    id: number; created: number; modified: number; name: string; subject_template?: string; html_template?: string | null; text_template?: string | null;
+    id: number; created: number | null; modified: number | null; name: string; subject_template?: string; html_template?: string | null; text_template?: string | null;
 }
 export interface PublicMessageRow {
     id: number; created: number; modified: number; kind: 'contact_us' | 'support' | string; status: 'open' | 'closed' | string;

package/src/admin/messaging/sanitize.ts

@@ -5,6 +5,7 @@ const object = (value: unknown): Record<string, unknown> => value && typeof valu
 const text = (value: unknown, max = MAX_TEXT): string => typeof value === 'string' ? value.slice(0, max) : '';
 const nullableText = (value: unknown, max = MAX_TEXT): string | null => value == null ? null : text(value, max);
 const number = (value: unknown): number => Number.isFinite(Number(value)) ? Number(value) : 0;
+const nullableNumber = (value: unknown): number | null => value != null && value !== '' && Number.isFinite(Number(value)) ? Number(value) : null;
 const relation = (value: unknown) => {
     if (typeof value === 'number') return value;
     const row = object(value); if (!Number.isInteger(row.id)) return null;
@@ -14,10 +15,10 @@ const strings = (value: unknown, maxItems = 50, max = 1000): string[] => Array.i
 const redactedOptionalText=(value:unknown,max=MAX_TEXT):string=>{const projected=text(value,max);return projected?redactMessagingError(projected):'';};
 
 function safeMask(value:unknown):string|null{const masked=nullableText(value,64);if(!masked)return null;return /^(?:\*{1,60}|•{1,60})[^*•\s]{0,4}$/.test(masked)?masked:'Configured';}
-export function sanitizeEmailDomainRow(value: EmailDomainRow): EmailDomainRow { const raw = object(value); const status=String(raw.status), dnsMode=String(raw.dns_mode); return { id: number(raw.id), created: number(raw.created), modified: number(raw.modified), name: text(raw.name, 253), region: text(raw.region, 64), status: (['pending','verified','ready','missing'].includes(status)?status:'unknown') as EmailDomainRow['status'], receiving_enabled: Boolean(raw.receiving_enabled), s3_inbound_bucket: nullableText(raw.s3_inbound_bucket, 255), s3_inbound_prefix: text(raw.s3_inbound_prefix, 255), dns_mode: (['manual','route53','godaddy'].includes(dnsMode)?dnsMode:'unknown') as EmailDomainRow['dns_mode'], aws_key_masked: safeMask(raw.aws_key_masked), aws_secret_masked: safeMask(raw.aws_secret_masked), sns_topic_bounce_arn: nullableText(raw.sns_topic_bounce_arn, 512), sns_topic_complaint_arn: nullableText(raw.sns_topic_complaint_arn, 512), sns_topic_delivery_arn: nullableText(raw.sns_topic_delivery_arn, 512), sns_topic_inbound_arn: nullableText(raw.sns_topic_inbound_arn, 512) }; }
-export function sanitizeMailboxRow(value: MailboxRow): MailboxRow { const raw = object(value); return { id: number(raw.id), created: number(raw.created), modified: number(raw.modified), email: text(raw.email, 320), domain: relation(raw.domain), allow_inbound: Boolean(raw.allow_inbound), allow_outbound: Boolean(raw.allow_outbound), async_handler: nullableText(raw.async_handler, 255), is_system_default: Boolean(raw.is_system_default), is_domain_default: Boolean(raw.is_domain_default) }; }
+export function sanitizeEmailDomainRow(value: EmailDomainRow): EmailDomainRow { const raw = object(value); const status=String(raw.status), dnsMode=String(raw.dns_mode); return { id: number(raw.id), created: nullableNumber(raw.created), modified: nullableNumber(raw.modified), name: text(raw.name, 253), region: text(raw.region, 64), status: (['pending','verified','ready','missing'].includes(status)?status:'unknown') as EmailDomainRow['status'], receiving_enabled: Boolean(raw.receiving_enabled), s3_inbound_bucket: nullableText(raw.s3_inbound_bucket, 255), s3_inbound_prefix: text(raw.s3_inbound_prefix, 255), dns_mode: (['manual','route53','godaddy'].includes(dnsMode)?dnsMode:'unknown') as EmailDomainRow['dns_mode'], aws_key_masked: safeMask(raw.aws_key_masked), aws_secret_masked: safeMask(raw.aws_secret_masked), sns_topic_bounce_arn: nullableText(raw.sns_topic_bounce_arn, 512), sns_topic_complaint_arn: nullableText(raw.sns_topic_complaint_arn, 512), sns_topic_delivery_arn: nullableText(raw.sns_topic_delivery_arn, 512), sns_topic_inbound_arn: nullableText(raw.sns_topic_inbound_arn, 512) }; }
+export function sanitizeMailboxRow(value: MailboxRow): MailboxRow { const raw = object(value); return { id: number(raw.id), created: nullableNumber(raw.created), modified: nullableNumber(raw.modified), email: text(raw.email, 320), domain: relation(raw.domain), allow_inbound: Boolean(raw.allow_inbound), allow_outbound: Boolean(raw.allow_outbound), async_handler: nullableText(raw.async_handler, 255), is_system_default: Boolean(raw.is_system_default), is_domain_default: Boolean(raw.is_domain_default) }; }
 export function sanitizeSentMessageRow(value: SentMessageRow): SentMessageRow { const raw = object(value); const reason=nullableText(raw.status_reason,1000); return { id: number(raw.id), created: number(raw.created), modified: number(raw.modified), mailbox: relation(raw.mailbox), to_addresses: strings(raw.to_addresses, 50, 320), cc_addresses: strings(raw.cc_addresses, 50, 320), bcc_addresses: strings(raw.bcc_addresses, 50, 320), subject: text(raw.subject, 998), status: (['queued','sending','delivered','bounced','complained','failed','unknown'].includes(String(raw.status)) ? String(raw.status) : 'unknown') as SentMessageRow['status'], ses_message_id: nullableText(raw.ses_message_id, 255), status_reason: reason?redactMessagingError(reason):null, body_text: nullableText(raw.body_text, 100_000), body_html: nullableText(raw.body_html, 200_000) }; }
-export function sanitizeTemplateRow(value: EmailTemplateRow): EmailTemplateRow { const raw = object(value); return { id: number(raw.id), created: number(raw.created), modified: number(raw.modified), name: text(raw.name, 255), subject_template: text(raw.subject_template, 998), html_template: nullableText(raw.html_template, 200_000), text_template: nullableText(raw.text_template, 100_000) }; }
+export function sanitizeTemplateRow(value: EmailTemplateRow): EmailTemplateRow { const raw = object(value); return { id: number(raw.id), created: nullableNumber(raw.created), modified: nullableNumber(raw.modified), name: text(raw.name, 255), subject_template: text(raw.subject_template, 998), html_template: nullableText(raw.html_template, 200_000), text_template: nullableText(raw.text_template, 100_000) }; }
 const PUBLIC_META = new Set(['company','category','severity','referrer','landing_page','utm_source','utm_medium','utm_campaign','utm_term','utm_content']);
 export function sanitizePublicMessageRow(value: PublicMessageRow): PublicMessageRow { const raw = object(value); const source = object(raw.metadata); const metadata: Record<string,string> = {}; for (const [key, val] of Object.entries(source)) if (PUBLIC_META.has(key) && typeof val === 'string') metadata[key] = text(val, 500); return { id: number(raw.id), created: number(raw.created), modified: number(raw.modified), kind: text(raw.kind, 40), status: text(raw.status, 40), name: text(raw.name, 255), email: text(raw.email, 320), subject: text(raw.subject, 998), group: relation(raw.group), ...(typeof raw.message === 'string' ? { message: text(raw.message, 50_000) } : {}), ...(Object.keys(metadata).length ? { metadata } : {}), metadata_withheld: Object.keys(source).some((key) => !PUBLIC_META.has(key)), ip_address: nullableText(raw.ip_address, 64), user_agent: nullableText(raw.user_agent, 1000) }; }
 

package/src/client/mock.ts

@@ -639,6 +639,20 @@ function buildGroupApiKeys(): MockGroupApiKey[] {
         { id: 201, group: 1, user: 1, created: now - 80 * 86400, modified: now - 2 * 86400, name: 'Acme deploy', is_active: true, permissions: { member: true, view_metrics: true }, limits: { assess: { limit: 500, window: 60 } }, last_used: now - 1800, expires_at: null, metadata: { owner: 'platform' }, override_user: false, token: 'mock_gk_acme_deploy' },
         { id: 202, group: 1, user: null, created: now - 30 * 86400, modified: now - 4 * 86400, name: 'Webhook worker', is_active: true, permissions: { manage_webhooks: true }, limits: {}, last_used: now - 86400, expires_at: now + 180 * 86400, metadata: {}, override_user: false, token: 'mock_gk_webhook_worker' },
         { id: 203, group: 2, user: null, created: now - 120 * 86400, modified: now - 20 * 86400, name: 'Legacy importer', is_active: false, permissions: { member: true }, limits: {}, last_used: now - 40 * 86400, expires_at: now + 10 * 86400, metadata: {}, override_user: false, token: 'mock_gk_legacy_importer' },
+        {
+            id: 204, group: 1, user: null, created: now - 150 * 86400, modified: now - 30 * 86400,
+            name: 'Legacy mixed limits', is_active: true, permissions: { view_logs: true },
+            limits: {
+                orders: { limit: 120, window: 5, extension: { burst: 20, source: 'legacy' } },
+                partial: { limit: 8, extension: { keep: true } },
+                scalar: 'legacy-unstructured',
+                '': { limit: 2, window: 1 },
+                '   ': { window: 3 },
+                __replace: { limit: 999, window: 1 },
+            },
+            last_used: now - 3 * 86400, expires_at: null, metadata: { owner: 'legacy' },
+            override_user: false, token: 'mock_gk_legacy_mixed',
+        },
     ];
 }
 
@@ -4566,6 +4580,25 @@ function mergeDicts(existing: Record<string, unknown>, incoming: Record<string,
     return out;
 }
 
+/** ApiKey.limits narrow merge: null deletes one exact endpoint identity. */
+function mergeApiKeyLimits(existing: Record<string, unknown>, incoming: Record<string, unknown>): Record<string, unknown> {
+    const out = { ...existing };
+    for (const [key, value] of Object.entries(incoming)) {
+        // django-mojo consumes this root key as a replace signal before merge.
+        // The mock intentionally offers no destructive replacement surface.
+        if (key === '__replace') continue;
+        if (value === null) {
+            delete out[key];
+            continue;
+        }
+        const previous = out[key];
+        out[key] = isPlainObject(previous) && isPlainObject(value)
+            ? mergeDicts(previous, value)
+            : value;
+    }
+    return out;
+}
+
 const LOGIN_METHODS = new Set(['password', 'sms', 'passkey', 'magic', 'google', 'apple', 'github']);
 const REGISTRATION_METHODS = new Set(['password', 'google', 'apple', 'github']);
 const DEFAULT_AUTH_CONFIG: Record<string, unknown> = {
@@ -9565,7 +9598,7 @@ export async function mockFetch(path: string, opts: MockFetchOpts): Promise<unkn
                 if ('name' in opts.body) row.name = String(opts.body.name ?? '');
                 if ('is_active' in opts.body) row.is_active = Boolean(opts.body.is_active);
                 if (isPlainObject(opts.body.permissions)) row.permissions = mergeDicts(row.permissions, opts.body.permissions);
-                if (isPlainObject(opts.body.limits)) row.limits = mergeDicts(row.limits, opts.body.limits);
+                if (isPlainObject(opts.body.limits)) row.limits = mergeApiKeyLimits(row.limits, opts.body.limits);
                 if (isPlainObject(opts.body.metadata)) row.metadata = mergeDicts(row.metadata, opts.body.metadata);
                 row.modified = Math.floor(Date.now() / 1000);
             }