docs: JWE primary document, restructuring documents

Sources/JWSETKit/Cryptography/Algorithms/Algorithms.swift

@@ -12,9 +12,17 @@ import CryptoKit
 import Crypto
 #endif
 
+/// JSON Web Signature Algorithms.
 public protocol JSONWebAlgorithm: RawRepresentable<String>, Hashable, Codable, ExpressibleByStringLiteral, Sendable {
+    /// Key type, which is either `RSA`, `EC` for elliptic curve or `oct` for symmetric keys.
     var keyType: JSONWebKeyType? { get }
+
+    /// Elliptic key curve, if key type is `EC`.
     var curve: JSONWebKeyCurve? { get }
+
+    /// Initialize algorithm from name.
+    ///
+    /// - Parameter rawValue: JWA registered name.
     init<S: StringProtocol>(_ rawValue: S)
 }
 
@@ -88,7 +96,7 @@ extension JSONWebAlgorithm {
     }
 }
 
-/// JSON Web Signature Algorithms
+/// JSON Web Signature Algorithms.
 public struct AnyJSONWebAlgorithm: JSONWebAlgorithm {
     public let rawValue: String
 

Sources/JWSETKit/Documentation.docc/Extensions/JWE.md

@@ -4,9 +4,70 @@ Use JWE to encrypt a payload.
 
 ## Overview
 
+JSON Web Encryption (JWE) represents encrypted content using JSON-based 
+data structures RFC7159. The JWE cryptographic mechanismsencrypt 
+and provide integrity protection for an arbitrary sequence of octets.
+
+## Decoding And Decrypting
+
+To create a new instance from compact or complete serialization,
+
+``` swift
+let jwe = try JSONWebEncryption(from: jweString)
+```
+
+Now it is possible to decrypt data using private key,
+
+```swift
+let data = try jwe.decrypt(using: keyEncryptionKey)
+```
+
+Decrypted content now can be deserialzed. For example if content is JWT claims,
+
+```swift
+let claims = JSONDecoder().decode(JSONWebTokenClaims.self, from: data)
+```
+
+## Encrypting & Encoding
+
+To create a new container from plain-text data and a key, first
+create a new random *Key Encryption Key* or use an existing one.
+
+Either provide no `contentEncryptionKey` to generate new random one,
+or provide an existing one.
+
+Finally, serialize the result into string representation.
+
+```swift
+// Generate a new AES-KeyWrap key with `A256KW` algorithm.
+let kek = JSONWebKeyAESKW(.bits256)
+
+// Alternatively, simply generate a 256-bit `SymmetricKey`.
+//
+// This works well as `keyEncryptingAlgorithm` is provided
+// in next step.
+let kek = SymmetricKey(size: .bits256)
+
+// Create JWE container with random content enc. key.
+let jwe = try! JSONWebEncryption(
+    content: Data("Live long and prosper.".utf8),
+    keyEncryptingAlgorithm: .aesKeyWrap256,
+    keyEncryptionKey: kek,
+    contentEncryptionAlgorithm: .aesEncryptionGCM128
+)
+
+// Encode JWE in compact string.
+let jweString = try! String(jwe: jwe)
+```
+
+In case multiple recipient support is neccessary or a unknown newly registered key type
+is used for encryption, you may first create encrypted key and sealed box and use 
+``JSONWebEncryption/init(header:recipients:sealed:additionalAuthenticatedData:)``
+to create JWE instance from parts.
+
 ## Topics
 
-### Cotents
+### Contents
 
 - ``JSONWebEncryptionHeader``
 - ``JSONWebEncryptionRecipient``
@@ -22,3 +83,8 @@ Use JWE to encrypt a payload.
 
 - ``JSONWebKeyAESGCM``
 - ``JSONWebKeyAESCBCHMAC``
+
+### Encoding
+
+- ``JSONWebEncryptionRepresentation``
+- ``JSONWebEncryptionCodableConfiguration``

Sources/JWSETKit/Documentation.docc/Extensions/JWS.md

@@ -141,3 +141,8 @@ try jws.updateSignature(using: hmacKey)
 - ``JOSEHeader``
 - ``JoseHeaderJWSRegisteredParameters``
 - ``JoseHeaderJWERegisteredParameters``
+
+### Encoding
+
+- ``JSONWebSignatureRepresentation``
+- ``JSONWebSignatureCodableConfiguration``

Sources/JWSETKit/Documentation.docc/Extensions/JWSETKit.md

@@ -53,3 +53,24 @@ of JWS.
 
 Check ``JSONWebEncryption`` documentation for usage, encrypting and decrypting
 payload.
+
+## Topics
+
+### Essentials
+
+- ``JSONWebToken``
+- ``JSONWebSignature``
+- ``JSONWebEncryption``
+
+### Cryptography
+
+- <doc:3-Cryptography>
+
+### Extending
+
+- <doc:7-Extending-Container>
+- ``JSONWebContainer``
+- ``ProtectedWebContainer``
+- ``TypedProtectedWebContainer``
+- ``ProtectedJSONWebContainer``
+- ``ProtectedDataWebContainer``

Sources/JWSETKit/Documentation.docc/Extensions/JWT.md

@@ -100,17 +100,18 @@ extension JSONWebTokenClaims {
 ```
 
 Intrinsic supported types to be parsed by generic accessor are:
+
 - `UnsignedInteger` conforming types, e.g. `UInt`, `UInt32`, etc.
 - `SignedInteger` conforming types, e.g. `Int`, `Int32`, etc.
 - `BinaryFloatingPoint` conforming types, e.g. `Double`, `Float`, etc.
-- `Foundation.  Decimal`
+- `Foundation.Decimal`
 - `Foundation.Date`, serialized as unix timestamp.
 - `Array<UInt8>`, `Foundation.Data`, `Foundation.NSData`, seriailzed as `Base64URL`.
 - `Foundation.URL`
 - `Foundation.Locale`, `Foundation.NSLocale`
 - `Foundation.TimeZone`, `Foundation.NSTimeZone`
 - Types conformed to ``JSONWebKey``.
-- Types conformed to``JSONWebAlgorithm``.
+- Types conformed to ``JSONWebAlgorithm``.
 - Types conformed to `Foundation.Decodable`.