Give JWK independent value semantics for thread-safe copies

README.md

@@ -4,6 +4,30 @@ This is a standards-compliant implementation of the JWT, JWK, JWS, and JWE
 standards in Nim, using the [BearSSL](https://www.bearssl.org/) library to
 provide the underlying cryptographic primatives.
 
+## JWK ownership and threads
+
+`JWK` and `JwkSet` have value semantics. Parsed keys own their key material and
+metadata; changing the input `JsonNode` after `initJwk` or `initJwkSet` does not
+change the keys. Assigning a key, key set, or `Table[string, JwkSet]` produces an
+independent value suitable for handing to a worker thread. Synchronize access
+to any source value that another thread may be modifying.
+
+The typed accessors (`kid`, `alg`, `rsaPrv`, etc.) return values. The JSON member
+accessor, `key["member"]`, keeps its `Option[JsonNode]` return type, but each call
+returns a fresh node. Mutating that node does not update the key; construct a
+new key with `initJwk` to change it. Missing members return `none`, while an
+explicit JSON null returns `some` containing a `JNull` node.
+Use `%key` to serialize a complete key, including extension members, to an
+independent JSON object.
+
+Internally, arbitrary JSON members are stored as encoded strings in a value
+table. Only JSON member lookups decode them. Signing and verification use the
+parsed key fields directly. This ownership guarantee applies to `JWK` and
+`JwkSet`; JWT claims and JOSE headers retain their existing ownership behavior.
+
+Run `nimble unittest` to run the suite, including worker-thread tests, under
+both ARC and ORC.
+
 ## Supported Algorithms (JWA)
 
 [RFC7518 (JWA)][rfc7518] registers