chore(docs): Document the AUTH_JWT_KEY_IS_BASE64_ENCODED option (#1169)

docs/api/_AUTH_JWT_KEY.md

@@ -2,7 +2,7 @@ The key to use for JWT verification.
 
 Must be appropriate for the chosen signature algorithm.
 
-For `HS*` algorithms, the symmetric key can be Base64-encoded.
+For `HS*` algorithms, the symmetric key can be base64-encoded, provided that you also configure `AUTH_JWT_KEY_IS_BASE64_ENCODED`.
 
 For `RS*` and `ES*` algorithms, the public key must be in the PEM format:
 

docs/api/_AUTH_JWT_KEY_IS_BASE64_ENCODED.md

@@ -0,0 +1 @@
+A boolean value that indicates whether the key configured in `AUTH_JWT_KEY` needs to be base64-decoded before it is used for token signature verification.

docs/api/service.md

@@ -333,6 +333,7 @@ See <DocPageLink path="usage/auth/secure" />
 
 import AuthJwtAlg from './_AUTH_JWT_ALG.md'
 import AuthJwtKey from './_AUTH_JWT_KEY.md'
+import AuthJwtKeyIsBase64Encoded from './_AUTH_JWT_KEY_IS_BASE64_ENCODED.md'
 import AuthJwtIss from './_AUTH_JWT_ISS.md'
 import AuthJwtAud from './_AUTH_JWT_AUD.md'
 
@@ -350,10 +351,19 @@ import AuthJwtAud from './_AUTH_JWT_AUD.md'
 <EnvVarConfig
     name="AUTH_JWT_KEY"
     required={true}
-    example="AAECAwQFBgc...">
+    example="x\a0CA7Q4_gc...">
   <AuthJwtKey />
 </EnvVarConfig>
 
+#### AUTH_JWT_KEY_IS_BASE64_ENCODED
+
+<EnvVarConfig
+    name="AUTH_JWT_KEY_IS_BASE64_ENCODED"
+    optional={true}
+    example="true">
+  <AuthJwtKeyIsBase64Encoded />
+</EnvVarConfig>
+
 #### AUTH_JWT_ISS
 
 <EnvVarConfig

docs/usage/auth/secure.md

@@ -132,6 +132,10 @@ The key to use for signature verification. A number of different key sizes and f
 
 See [Generating signing keys](#generating-signing-keys) below to learn more about generating keys for different algorithms.
 
+### `AUTH_JWT_KEY_IS_BASE64_ENCODED`
+
+A boolean value that tells the sync service whether the value of `AUTH_JWT_KEY` needs to be base64-decoded before using it for signature verification.
+
 ### `AUTH_JWT_NAMESPACE`
 
 This is an optional setting that specifies the location inside the token of custom claims that are specific to Electric. Currently, only the `sub` custom claim (formerly `user_id`) is required.
@@ -172,6 +176,8 @@ These use the same _secret key_ for both signing and signature verification. The
 
 Minimum required key size is 256 bits for `HS256`, 384 bits for `HS384`, and 512 bits for `HS512`. The longer the key, the more secure the digital signature. We recommend using a 512-bit key regardless of which specific `HS*` algorithm you pick.
 
+If your deployment target makes it difficult to use a string containing random, non-printable characters for an environment variable, encode the secret key with base64 encoding and use the result for the `AUTH_JWT_KEY` setting, while also setting `AUTH_JWT_KEY_IS_BASE64_ENCODED` to `true`.
+
 ### `RS256, RS384, RS512`
 
 RSA is an asymmetric cryptography algorithm that uses a private key to digitally sign a token and a matching public key to verify the signature. The minimum required key size to use with JWTs is 2048 bits.