fix: replace keeps a write-only attribute left out of the replacement

RFC 7644 §3.5.1 only lets an omitted readWrite attribute be cleared. A client
that retrieved the resource and revised it never got a write-only value such
as password back, so a PUT built from a GET used to erase it. An explicit null
still clears it.

Author: azmeuk

doc/changelog.rst

@@ -26,6 +26,9 @@ Fixed
   <7643#section-3.1>` declares it, so filters and orders on it respect the case.
 - The :class:`~scim2_models.Meta` sub-attributes are read-only, and ``resourceType`` and
   ``version`` are case-exact, as :rfc:`RFC7643 §3.1 <7643#section-3.1>` declares them.
+- :meth:`Resource.replace <scim2_models.Resource.replace>` keeps a write-only attribute, such
+  as ``password``, that the replacement leaves out, and clears it on an explicit null only. A
+  client never gets that value back, so a PUT built from a GET used to erase it.
 
 [0.8.1] - 2026-09-25
 --------------------

scim2_models/base.py

@@ -701,6 +701,8 @@ def _apply_replace_constraints(self, original: Self) -> None:
         - ``readOnly`` fields are copied from *original* unconditionally.
         - ``immutable`` fields are copied from *original* when absent from
           ``self``; a MutabilityException is raised when the value differs.
+        - ``writeOnly`` fields left out of ``self`` are copied from *original*,
+          and only an explicit null clears them.
 
         Recursively applies to nested complex attributes, and to the entries of
         a multi-valued one whose ``value`` designates a single entry on both
@@ -727,6 +729,14 @@ def _apply_replace_constraints(self, original: Self) -> None:
                     raise MutabilityException(
                         attribute=field_name, mutability="immutable"
                     )
+            elif (
+                mutability == Mutability.write_only
+                and field_name not in self.model_fields_set
+            ):
+                # RFC 7644 §3.5.1 only lets an omitted "readWrite" attribute be
+                # cleared: a client that retrieved the resource and revised it
+                # never got the write-only value back, and cannot resend it.
+                self.__dict__[field_name] = original_val
 
         complex_and_extensions = self.__scim_info__.complex_fields.union(
             self.__scim_info__.extensions

scim2_models/resources/resource.py

@@ -192,7 +192,9 @@ def replace(self, original: Self) -> None:
 
         ``readOnly`` fields are copied from *original*.
         ``immutable`` fields are preserved from *original* when absent,
-        or checked for equality when present.
+        or checked for equality when present. ``writeOnly`` fields, such as
+        ``password``, are preserved from *original* when left out, and cleared
+        by an explicit null only.
 
         The same applies to the sub-attributes of a complex attribute, and to
         those of an entry a multi-valued one keeps. Entries are matched on their

tests/test_model_validation.py

@@ -490,6 +490,69 @@ def test_replace_preserves_immutable_when_absent():
     assert replacement.immutable == "y"
 
 
+def test_replace_preserves_a_write_only_field_left_out():
+    """RFC 7644 §3.5.1 only clears omitted readWrite attributes: a write-only value is never returned to resend."""
+    original = MutResource(write_only="secret")
+    replacement = MutResource(read_write="x")
+    replacement.replace(original)
+    assert replacement.write_only == "secret"
+    assert "write_only" not in replacement.model_fields_set
+
+
+def test_replace_clears_a_write_only_field_set_to_null():
+    """An explicit null is how RFC 7644 §3.5.1 lets a client clear a value."""
+    original = MutResource(write_only="secret")
+    replacement = MutResource(write_only=None)
+    replacement.replace(original)
+    assert replacement.write_only is None
+
+
+def test_replace_takes_a_provided_write_only_value():
+    """RFC 7644 §3.5.1: write-only values provided "SHALL replace the existing" ones."""
+    original = MutResource(write_only="secret")
+    replacement = MutResource(write_only="new")
+    replacement.replace(original)
+    assert replacement.write_only == "new"
+
+
+@pytest.mark.parametrize(
+    ("payload", "expected"),
+    [({}, "secret"), ({"writeOnly": None}, None), ({"writeOnly": "new"}, "new")],
+    ids=["omitted", "null", "provided"],
+)
+def test_replace_reads_a_write_only_field_from_a_replacement_request(payload, expected):
+    """A payload tells an omitted write-only attribute apart from a null one."""
+    original = MutResource(write_only="secret")
+    replacement = MutResource.model_validate(
+        {"schemas": ["urn:example:MutResource"], **payload},
+        scim_ctx=Context.RESOURCE_REPLACEMENT_REQUEST,
+    )
+    replacement.replace(original)
+    assert replacement.write_only == expected
+
+
+def test_replace_preserves_a_write_only_sub_attribute_left_out():
+    """The rule applies to the sub-attributes of complex and multi-valued attributes."""
+
+    class Sub(ComplexAttribute):
+        value: str | None = None
+        write_only: Annotated[str | None, Mutability.write_only] = None
+
+    class Holder(Resource):
+        __schema__ = URN("urn:example:Holder")
+        sub: Sub | None = None
+        subs: list[Sub] | None = None
+
+    original = Holder(
+        sub=Sub(value="a", write_only="secret"),
+        subs=[Sub(value="a", write_only="secret")],
+    )
+    replacement = Holder(sub=Sub(value="b"), subs=[Sub(value="a")])
+    replacement.replace(original)
+    assert replacement.sub.write_only == "secret"
+    assert replacement.subs[0].write_only == "secret"
+
+
 def test_replace_does_not_assert_the_fields_it_copies():
     """The fields replace copies from the original are not reported as set.