Security and Users & Roles Sections Migration

migration-context/link-placeholders/security-link-placeholders.md

@@ -0,0 +1,29 @@
+# Link Placeholders for Security Section
+
+## reference_versioned_docs/version-v4/security/mtls-authentication.md
+
+- Line 47: `[TODO:reference_versioned_docs/version-v4/replication/clustering.md]`
+  - Context: Referring to replication mTLS configuration
+  - Target should be: Replication clustering page that covers mTLS for replication
+
+## reference_versioned_docs/version-v4/security/certificate-management.md
+
+- Line 8: `[TODO:reference_versioned_docs/version-v4/replication/clustering.md]`
+  - Context: Note that this page covers external-facing APIs; replication certs are covered separately
+  - Target should be: Replication clustering page with certificate management section
+
+- ~~Line 105: `[TODO:reference_versioned_docs/version-v4/cli/commands.md]`~~ **RESOLVED** → `../cli/commands.md`
+
+## reference_versioned_docs/version-v4/security/certificate-verification.md
+
+- Line 190: `[TODO:reference_versioned_docs/version-v4/replication/clustering.md]`
+  - Context: Replication mTLS configuration reference
+  - Target should be: Replication clustering page
+
+## reference_versioned_docs/version-v4/security/cors.md
+
+- ~~Line 36: `[TODO:reference_versioned_docs/version-v4/http/configuration.md]`~~ **RESOLVED** → `../http/configuration.md`
+
+## reference_versioned_docs/version-v4/security/ssl.md
+
+- ~~Line 56: `[TODO:reference_versioned_docs/version-v4/http/tls.md]`~~ **RESOLVED** → `../http/tls.md`

reference_versioned_docs/version-v4/http/tls.md

@@ -116,4 +116,4 @@ See the [Operations API Configuration](TODO:reference_versioned_docs/version-v4/
 
 - [HTTP Configuration](./configuration) — `http.securePort`, `http.http2`, `http.mtls`
 - [HTTP Overview](./overview)
-- [Security Overview](TODO:reference_versioned_docs/version-v4/security/overview.md 'Certificate management, mTLS, and other security topics')
+- [Security mTLS Authentication](../security/mtls-authentication.md)

reference_versioned_docs/version-v4/security/basic-authentication.md

@@ -0,0 +1,58 @@
+---
+id: basic-authentication
+title: Basic Authentication
+---
+
+<!-- Source: versioned_docs/version-4.7/developers/security/basic-auth.md (primary) -->
+
+Available since: v4.1.0
+
+Harper supports HTTP Basic Authentication. In the context of an HTTP transaction, [Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Authentication#basic_authentication_scheme) is the simplest authorization scheme which transmits credentials as username/password pairs encoded using base64. Importantly, this scheme does not encrypt credentials. If used over an insecure connection, such as HTTP, they are susceptible to being compromised. Only ever use Basic Authentication over secured connections, such as HTTPS. Even then, its better to upgrade to an encryption based authentication scheme or certificates. See [SSL / HTTPS](./ssl.md) for more information.
+
+## How It Works
+
+Each request must contain the `Authorization` header with a value if `Basic <credentials>`, where `<credentials>` is the Base64 encoding of the string `username:password`.
+
+```
+Authorization: Basic <base64(username:password)>
+```
+
+## Example
+
+The following example shows how to construct the Authorization header using `btoa()`:
+
+```javascript
+const username = 'HDB_ADMIN';
+const password = 'abc123!';
+const authorizationValue = `Basic ${btoa(`${username}:${password}`)}`;
+```
+
+Then use the `authorizationValue` as the value for the `Authorization` header such as:
+
+```javascript
+fetch('/', {
+	// ...
+	headers: {
+		Authorization: authorizationValue,
+	},
+	// ...
+});
+```
+
+## cURL Example
+
+With cURL you can use the `--user` (`-u`) command-line option to automatically handle the Base64 encoding:
+
+```bash
+curl -u "username:password" [URL]
+```
+
+## When to Use Basic Auth
+
+Basic authentication is the simplest option and is appropriate for:
+
+- Server-to-server requests in trusted environments
+- Development and testing
+- Scenarios where token management overhead is undesirable
+
+For user-facing applications or when tokens are preferred for performance reasons, see [JWT Authentication](./jwt-authentication.md).

reference_versioned_docs/version-v4/security/certificate-management.md

@@ -0,0 +1,152 @@
+---
+id: certificate-management
+title: Certificate Management
+---
+
+<!-- Source: versioned_docs/version-4.7/developers/security/certificate-management.md (primary) -->
+<!-- Source: release-notes/v4-tucker/4.4.0.md (dynamic certificate management added) -->
+<!-- Source: release-notes/v4-tucker/4.5.0.md (certificate revocation added) -->
+
+This page covers certificate management for Harper's external-facing HTTP and Operations APIs. For replication certificate management, see [Replication Certificate Management](TODO:reference_versioned_docs/version-v4/replication/clustering.md 'Replication clustering and certificate management').
+
+## Default Behavior
+
+On first run, Harper automatically generates self-signed TLS certificates at `<ROOTPATH>/keys/`:
+
+- `certificate.pem` — The server certificate
+- `privateKey.pem` — The server private key
+- `ca.pem` — A self-signed Certificate Authority
+
+These certificates have a valid Common Name (CN), but they are not signed by a root authority. HTTPS can be used with them, but clients must be configured to accept the invalid certificate.
+
+## Development Setup
+
+By default, HTTPS is disabled. HTTP is suitable for local development and trusted private networks. If you are developing on a remote server with requests traversing the Internet, enable HTTPS.
+
+To enable HTTPS, set `http.securePort` in `harperdb-config.yaml` and restart Harper:
+
+```yaml
+http:
+  securePort: 9926
+```
+
+Harper will use the auto-generated certificates from `<ROOTPATH>/keys/`.
+
+## Production Setup
+
+For production, use certificates from your own CA or a public CA, with CNs that match the Fully Qualified Domain Name (FQDN) of your Harper node.
+
+### Option 1: Replace Harper Certificates
+
+Enable HTTPS and replace the certificate files:
+
+```yaml
+http:
+  securePort: 9926
+tls:
+  certificate: ~/hdb/keys/certificate.pem
+  privateKey: ~/hdb/keys/privateKey.pem
+```
+
+Either replace the files at `<ROOTPATH>/keys/` in place, or update `tls.certificate` and `tls.privateKey` to point to your new files and restart Harper.
+
+The `operationsApi.tls` section is optional. If not set, Harper uses the values from the top-level `tls` section. You can specify different certificates for the Operations API:
+
+```yaml
+operationsApi:
+  tls:
+    certificate: ~/hdb/keys/certificate.pem
+    privateKey: ~/hdb/keys/privateKey.pem
+```
+
+### Option 2: Nginx Reverse Proxy
+
+Instead of enabling HTTPS directly on Harper, use Nginx as a reverse proxy. Configure Nginx to handle HTTPS with certificates from your own CA or a public CA, then forward HTTP requests to Harper.
+
+This approach keeps Harper's HTTP interface internal while Nginx handles TLS termination.
+
+### Option 3: External Reverse Proxy / Load Balancer
+
+External services such as an AWS Elastic Load Balancer or Google Cloud Load Balancing can act as TLS-terminating reverse proxies. Configure the service to accept HTTPS connections and forward over a private network to Harper as HTTP.
+
+These services typically include integrated certificate management.
+
+## mTLS Setup
+
+Mutual TLS (mTLS) requires both client and server to present certificates. To enable mTLS, provide a CA certificate that Harper will use to verify client certificates:
+
+```yaml
+http:
+  mtls:
+    required: true
+tls:
+  certificateAuthority: ~/hdb/keys/ca.pem
+```
+
+For full mTLS authentication details, see [mTLS Authentication](./mtls-authentication.md).
+
+## Certificate Verification
+
+Added in: v4.5.0 (certificate revocation); v4.7.0 (OCSP support)
+
+When using mTLS, enable certificate verification to ensure revoked certificates cannot authenticate even if still within their validity period:
+
+```yaml
+http:
+  mtls:
+    required: true
+    certificateVerification: true
+```
+
+Harper supports two industry-standard methods:
+
+**CRL (Certificate Revocation List)**
+
+- Downloaded and cached locally (24 hours by default)
+- Fast verification after first download (no network requests)
+- Best for high-volume verification and offline scenarios
+
+**OCSP (Online Certificate Status Protocol)**
+
+- Real-time query to the CA's OCSP responder
+- Best for certificates without CRL distribution points
+- Responses cached (1 hour by default)
+
+**Harper's approach: CRL-first with OCSP fallback**
+
+1. Checks CRL if available (fast, cached locally)
+2. Falls back to OCSP if CRL is unavailable or fails
+3. Applies the configured failure mode if both methods fail
+
+For full configuration options and troubleshooting, see [Certificate Verification](./certificate-verification.md).
+
+## Dynamic Certificate Management
+
+Added in: v4.4.0 (confirmed via release notes)
+
+Certificates — including CAs and private keys — can be dynamically managed without restarting Harper.
+
+## Multiple Certificate Authorities
+
+It is possible to use different certificates for the Operations API and the HTTP (custom application) API. For example, in scenarios where only your application endpoints need to be exposed to the Internet and the Operations API is reserved for administration, you may use a private CA for the Operations API and a public CA for your application certificates.
+
+Configure each separately:
+
+```yaml
+# Top-level tls: used by HTTP/application endpoints
+tls:
+  certificate: ~/hdb/keys/app-certificate.pem
+  privateKey: ~/hdb/keys/app-privateKey.pem
+
+# Operations API can use a separate cert
+operationsApi:
+  tls:
+    certificate: ~/hdb/keys/ops-certificate.pem
+    privateKey: ~/hdb/keys/ops-privateKey.pem
+```
+
+## Renewing Certificates
+
+The `harper renew-certs` CLI command renews the auto-generated Harper certificates. See [CLI Commands](../cli/commands.md) for details.
+
+**Changes to TLS settings require a restart**, except where dynamic certificate management is used.