fix(security): redact PasswordInput-masked field values from detail payload (#504) (#522)

* fix(security): redact PasswordInput-masked field values from the detail payload (#504)

A CharField the admin routes through forms.PasswordInput (e.g. via
formfield_overrides) was serialized with its stored value intact, so a
secret kept on that field shipped as plaintext in the detail JSON — even
though Django's own admin renders PasswordInput with render_value=False
and never echoes the value back into the page.

Match Django's behaviour at the wire boundary: when the bound form
widget is a PasswordInput, redact `value` to null unless the admin opted
into render_value=True, and emit a `widget: "password"` hint. The SPA
renders a masked <input type="password"> (autoComplete="new-password")
for that hint. Read-only password fields also stop leaking, since the
value is redacted before FieldValueView renders it.

Also types the previously-untyped `widget` descriptor hint
(radio/raw_id/password) in the wire contract.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test(form): cover the masked password input (#504)

The security contract: the backend redacts the value (it arrives null),
so the SPA never receives the secret — assert the input renders
type=password with autoComplete=new-password and stays empty, and that
typed characters propagate via onChange.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Martin Castro Laminrs <mcastro@laminr.ai>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 3 people

CHANGELOG.md

@@ -14,6 +14,13 @@ version section at release.
 
 ## [Unreleased]
 
+### Security
+- A `CharField` the admin masks with `forms.PasswordInput` (e.g. via
+  `formfield_overrides`) no longer leaks its stored value in the detail
+  payload: the backend redacts `value` to `null` (matching Django admin's
+  `render_value=False`) and emits a `widget: "password"` hint, and the SPA
+  renders a masked `<input type="password">` (#504).
+
 ## [0.2.0a8] — 2026-05-28
 [GitHub Release](https://github.com/MartinCastroAlvarez/django-admin-react/releases/tag/v0.2.0a8)
 

django_admin_react/api/views/detail.py

@@ -26,6 +26,7 @@
 from django.db.models import ForeignKey
 from django.db.models import ManyToManyField
 from django.db.models import Model
+from django.forms.widgets import PasswordInput
 from django.forms.widgets import Textarea
 from django.forms.widgets import TextInput
 from django.http import HttpRequest
@@ -380,12 +381,28 @@ def _apply_widget_override(descriptor: dict[str, Any], form_field: Any) -> None:
     Reuses the form widget (source of truth) so ``formfield_overrides``
     has a visible effect, mapping only to the existing ``string`` /
     ``text`` vocabulary so no new wire type is introduced (#446).
+
+    A ``PasswordInput`` override is handled first and separately (#504):
+    it is a security boundary, not a layout hint. Django's admin renders
+    a ``PasswordInput`` with ``render_value=False`` by default, so the
+    stored value is never echoed back into the page. The SPA reads its
+    value over the wire, so the equivalent is to **redact the value from
+    the payload** unless the admin explicitly opted into echoing it
+    (``render_value=True``), and to hint the SPA to mask the input
+    (``widget: "password"``). Without this, a secret stored on a
+    ``CharField`` the admin masked with ``PasswordInput`` would be sent
+    as plaintext in the detail JSON.
     """
     if form_field is None:
         return
     widget = getattr(form_field, "widget", None)
     if widget is None:
         return
+    if isinstance(widget, PasswordInput):
+        descriptor["widget"] = "password"
+        if not getattr(widget, "render_value", False):
+            descriptor["value"] = None
+        return
     if descriptor["type"] == "string" and isinstance(widget, Textarea):
         descriptor["type"] = "text"
     elif (

docs/api-contract.md

@@ -548,13 +548,22 @@ Rules:
   `get_fieldsets`). Anything in `exclude`/`get_exclude` is omitted.
 - `readonly: true` corresponds to membership in
   `ModelAdmin.get_readonly_fields(request, obj)`.
-- `widget` is an optional **presentational** hint (`#251`): `"radio"` when
-  the admin lists the field in `ModelAdmin.radio_fields` (render the
-  choice/FK as radio buttons), or `"raw_id"` when it's in
-  `ModelAdmin.raw_id_fields` (render a pk input + lookup for a
-  high-cardinality FK/M2M, instead of a select). `radio_fields` wins if a
-  field is in both. Absent when the field is in neither; it changes no
-  value, type, or permission gate.
+- `widget` is an optional hint: `"radio"` when the admin lists the field in
+  `ModelAdmin.radio_fields` (render the choice/FK as radio buttons), or
+  `"raw_id"` when it's in `ModelAdmin.raw_id_fields` (render a pk input +
+  lookup for a high-cardinality FK/M2M, instead of a select). `radio_fields`
+  wins if a field is in both. These two are purely **presentational** —
+  they change no value, type, or permission gate (`#251`).
+  - `"password"` is a **security** hint, not a layout one (`#504`): the admin
+    routed the field through `forms.PasswordInput` (e.g. via
+    `formfield_overrides`). Django's admin renders `PasswordInput` with
+    `render_value=False`, so the stored value never re-enters the page; the
+    SPA reads its value over the wire, so the backend matches that by
+    **redacting `value` to `null`** in this descriptor unless the admin set
+    `render_value=True`. The SPA renders a masked `<input type="password">`.
+    A consumer storing a secret on a `CharField` masked with `PasswordInput`
+    therefore never sees it leave the server in the detail payload.
+  - Absent when the field is in none of these.
 - `empty_value_display` (top-level, also on the **list** response §3) is the
   admin's placeholder for empty/null values — `ModelAdmin.empty_value_display`
   if set, else the `AdminSite` default (`"-"`) (`#251`). The SPA renders this

frontend/packages/api/src/contract.ts

@@ -23,6 +23,16 @@ export type FieldType =
   | 'manytomany'
   | 'unsupported';
 
+/**
+ * Presentational widget hint that overrides the default control the SPA
+ * would pick from `type`. `radio` / `raw_id` come from `radio_fields` /
+ * `raw_id_fields` (#251). `password` is a security boundary, not a layout
+ * choice: it marks a field the admin routed through `PasswordInput`, whose
+ * stored value the backend redacts from the payload (matching Django's
+ * `render_value=False`) — the SPA masks the input (#504).
+ */
+export type WidgetHint = 'radio' | 'raw_id' | 'password';
+
 export interface Permissions {
   view: boolean;
   add: boolean;
@@ -346,6 +356,12 @@ export interface FieldDescriptor {
   decimal_places?: number;
   choices?: FieldChoice[];
   to?: { app_label: string; model_name: string };
+  /**
+   * Optional control override (see `WidgetHint`). Absent for the default
+   * control implied by `type`. `password` additionally means the backend
+   * has redacted `value` (it ships `null`).
+   */
+  widget?: WidgetHint;
 }
 
 export interface FieldsetDescriptor {

frontend/packages/form/src/FieldInput.test.tsx

@@ -0,0 +1,58 @@
+import '@testing-library/jest-dom/vitest';
+
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { FieldDescriptor } from '@dar/data';
+
+import { FieldInput } from './FieldInput';
+
+// A field the admin masked with PasswordInput. The backend redacts the
+// stored value (#504), so the descriptor arrives with `value: null` and
+// `widget: 'password'` — the SPA never receives the secret.
+function pwField(overrides: Partial<FieldDescriptor> = {}): FieldDescriptor {
+  return {
+    type: 'string',
+    label: 'API key',
+    required: false,
+    readonly: false,
+    help_text: '',
+    value: null,
+    widget: 'password',
+    ...overrides,
+  };
+}
+
+describe('FieldInput password widget (#504)', () => {
+  it('renders a masked input; the redacted value is never shown', () => {
+    render(
+      <FieldInput
+        name="api_key"
+        field={pwField()}
+        value={null}
+        error={undefined}
+        onChange={() => {}}
+      />,
+    );
+    const input = screen.getByLabelText('API key') as HTMLInputElement;
+    expect(input).toHaveAttribute('type', 'password');
+    expect(input).toHaveAttribute('autocomplete', 'new-password');
+    // Backend redacted the value to null, so the field starts empty.
+    expect(input.value).toBe('');
+  });
+
+  it('reports typed characters via onChange', () => {
+    const onChange = vi.fn();
+    render(
+      <FieldInput
+        name="api_key"
+        field={pwField()}
+        value=""
+        error={undefined}
+        onChange={onChange}
+      />,
+    );
+    fireEvent.change(screen.getByLabelText('API key'), { target: { value: 'new-secret' } });
+    expect(onChange).toHaveBeenCalledWith('new-secret');
+  });
+});

frontend/packages/form/src/FieldInput.tsx

@@ -50,7 +50,22 @@ export function FieldInput({ name, field, value, error, onChange }: FieldInputPr
 
   let control: React.ReactNode;
 
-  if (field.type === 'boolean') {
+  if (field.widget === 'password') {
+    // Field the admin routed through PasswordInput (#504). The backend
+    // redacts the stored value (it ships `null`, matching Django's
+    // `render_value=False`), so the box starts empty. Mask the input and
+    // keep the browser from offering saved credentials for a secret field.
+    control = (
+      <input
+        id={id}
+        type="password"
+        autoComplete="new-password"
+        value={value == null ? '' : String(value)}
+        onChange={(e) => onChange(e.target.value)}
+        className={base}
+      />
+    );
+  } else if (field.type === 'boolean') {
     control = (
       <Checkbox id={id} checked={value === true} onChange={(e) => onChange(e.target.checked)} />
     );

tests/test_detail.py

@@ -786,3 +786,72 @@ def reconcile(type_: str, widget: object) -> str:
     none_field = {"type": "string"}
     _apply_widget_override(none_field, None)
     assert none_field["type"] == "string"
+
+
+def test_apply_widget_override_passwordinput_redacts_value() -> None:
+    """A ``PasswordInput`` widget hints ``password`` and redacts the value
+    unless the admin opted into ``render_value=True`` (#504)."""
+    from django import forms
+
+    from django_admin_react.api.views.detail import _apply_widget_override
+
+    def apply(widget: object, value: object = "s3cret") -> dict:
+        d = {"type": "string", "value": value}
+        _apply_widget_override(d, type("F", (), {"widget": widget})())
+        return d
+
+    # Default PasswordInput (render_value=False): value redacted, hinted.
+    masked = apply(forms.PasswordInput())
+    assert masked["widget"] == "password"
+    assert masked["value"] is None
+    # render_value=True: value preserved, still hinted.
+    echoed = apply(forms.PasswordInput(render_value=True))
+    assert echoed["widget"] == "password"
+    assert echoed["value"] == "s3cret"
+    # Password wins over the string/text reconciliation (it returns early).
+    assert "type" in masked and masked["type"] == "string"
+
+
+@pytest.mark.django_db
+def test_formfield_overrides_passwordinput_masks_and_redacts() -> None:
+    """A CharField the admin masks with ``PasswordInput`` via
+    ``formfield_overrides`` never ships its stored value in the detail
+    payload, and carries the ``widget: "password"`` hint so the SPA masks
+    the input (#504). A plain admin ships the value unmasked."""
+    from django import forms
+    from django.contrib import admin
+    from django.contrib.auth import get_user_model
+    from django.contrib.auth.models import Permission
+    from django.db import models
+    from django.test import RequestFactory
+
+    from django_admin_react.api.views.detail import _descriptor_for
+
+    class _PasswordAdmin(admin.ModelAdmin):
+        formfield_overrides = {models.CharField: {"widget": forms.PasswordInput}}
+
+    request = RequestFactory().get("/")
+    request.user = get_user_model().objects.create_superuser(
+        username="pwd-su", email="pwd@example.com", password="x"  # noqa: S106
+    )
+
+    def descriptor(model_admin: admin.ModelAdmin) -> dict:
+        form = model_admin.get_form(request, obj=None)()
+        return _descriptor_for(
+            model=Permission,
+            model_admin=model_admin,
+            obj=Permission(name="top-secret-value"),  # the field's stored value
+            name="name",  # CharField
+            form=form,
+            is_readonly=False,
+            admin_site=admin.site,
+            request=request,
+        )
+
+    masked = descriptor(_PasswordAdmin(Permission, admin.site))
+    assert masked["widget"] == "password"
+    assert masked["value"] is None  # secret never leaves the server
+
+    plain = descriptor(admin.ModelAdmin(Permission, admin.site))
+    assert plain.get("widget") != "password"
+    assert plain["value"] == "top-secret-value"  # unmasked field is unchanged