diff --git a/migration-context/link-placeholders/security-link-placeholders.md b/migration-context/link-placeholders/security-link-placeholders.md new file mode 100644 index 00000000..e5464816 --- /dev/null +++ b/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` diff --git a/reference_versioned_docs/version-v4/http/tls.md b/reference_versioned_docs/version-v4/http/tls.md index 9d7508d9..2fbaa4b3 100644 --- a/reference_versioned_docs/version-v4/http/tls.md +++ b/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) diff --git a/reference_versioned_docs/version-v4/security/basic-authentication.md b/reference_versioned_docs/version-v4/security/basic-authentication.md new file mode 100644 index 00000000..d2393fd8 --- /dev/null +++ b/reference_versioned_docs/version-v4/security/basic-authentication.md @@ -0,0 +1,58 @@ +--- +id: basic-authentication +title: Basic Authentication +--- + + + +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 `, where `` is the Base64 encoding of the string `username:password`. + +``` +Authorization: Basic +``` + +## 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). diff --git a/reference_versioned_docs/version-v4/security/certificate-management.md b/reference_versioned_docs/version-v4/security/certificate-management.md new file mode 100644 index 00000000..e59f83ca --- /dev/null +++ b/reference_versioned_docs/version-v4/security/certificate-management.md @@ -0,0 +1,152 @@ +--- +id: certificate-management +title: Certificate Management +--- + + + + + +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 `/keys/`: + +- `certificate.pem` — The server certificate +- `privateKey.pem` — The server private key +- `ca.pem` — A self-signed Certificate Authority + +These certificates do not have a valid Common Name (CN) for your Harper node. 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 `/keys/`. + +## Production Setup + +For production, use certificates from your own CA or a public CA such as Let's Encrypt, 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 `/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 (e.g. via [Certbot](https://certbot.eff.org/) for Let's Encrypt), 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 Application Load Balancer or GCP HTTPS load balancer 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 Revocation Checking + +Added in: v4.5.0 (certificate revocation); v4.7.0 (OCSP support) + +When using mTLS, enable certificate revocation checking 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. diff --git a/reference_versioned_docs/version-v4/security/certificate-verification.md b/reference_versioned_docs/version-v4/security/certificate-verification.md new file mode 100644 index 00000000..8a6aa673 --- /dev/null +++ b/reference_versioned_docs/version-v4/security/certificate-verification.md @@ -0,0 +1,447 @@ +--- +id: certificate-verification +title: Certificate Verification +--- + + + + + +Added in: v4.7.0 (OCSP support confirmed via release notes; certificate revocation support added in v4.5.0) + +Certificate verification (also called certificate revocation checking) ensures that revoked certificates cannot be used for mTLS authentication, even if they are otherwise valid and trusted. This is a critical security control for environments where certificates may need to be revoked before their expiration date — due to compromise, employee departure, or other security concerns. + +## Overview + +When a client presents a certificate for mTLS authentication, Harper performs two levels of checks: + +1. **Certificate Validation** (always performed by Node.js TLS): + - Certificate signature is valid + - Certificate is issued by a trusted CA + - Certificate is within its validity period + - Certificate chain is properly formed + +2. **Certificate Revocation Checking** (optional, must be explicitly enabled): + - Certificate has not been revoked by the issuing CA + - Uses CRL and/or OCSP + +Revocation checking is **disabled by default**. + +## Revocation Checking Methods + +### CRL (Certificate Revocation List) + +A CRL is a digitally signed list of revoked certificates published by a Certificate Authority. + +**Advantages:** + +- Fast verification (cached locally) +- Works offline once downloaded +- Predictable bandwidth usage +- Good for high-volume verification +- No privacy concerns (no per-certificate queries) + +**How it works:** + +1. Harper downloads the CRL from the distribution point specified in the certificate. +2. The CRL is cached locally (24 hours by default). +3. Subsequent verifications check the cached CRL — very fast, no network requests. +4. The CRL is refreshed in the background before expiration. + +**Configuration:** + +```yaml +http: + mtls: + certificateVerification: + crl: + timeout: 10000 # 10 seconds to download CRL + cacheTtl: 86400000 # Cache for 24 hours + gracePeriod: 86400000 # 24 hour grace period after nextUpdate + failureMode: fail-closed # Reject on CRL check failure +``` + +### OCSP (Online Certificate Status Protocol) + +OCSP provides real-time certificate status checking by querying the CA's OCSP responder. + +**Advantages:** + +- Real-time revocation status +- Smaller response size than CRL +- Good for certificates without CRL distribution points +- Works when CRL is unavailable + +**How it works:** + +1. Harper sends a request to the OCSP responder specified in the certificate. +2. The responder returns the current status: good, revoked, or unknown. +3. The response is cached (1 hour by default for success, 5 minutes for errors). + +**Configuration:** + +```yaml +http: + mtls: + certificateVerification: + ocsp: + timeout: 5000 # 5 seconds for OCSP response + cacheTtl: 3600000 # Cache successful responses for 1 hour + errorCacheTtl: 300000 # Cache errors for 5 minutes + failureMode: fail-closed # Reject on OCSP check failure +``` + +## Verification Strategy + +Harper uses a **CRL-first strategy with OCSP fallback**: + +1. **Check CRL** if available (fast; uses cached CRL; no network request if cached). +2. **Fall back to OCSP** if the certificate has no CRL distribution point, the CRL download fails, or the CRL is expired and cannot be refreshed. +3. **Apply failure mode** if both methods fail. + +This provides the best balance of performance, reliability, and security. + +## Configuration + +### Enable with Defaults + +```yaml +http: + mtls: + required: true + certificateVerification: true +``` + +This enables CRL checking (10s timeout, 24h cache), OCSP checking (5s timeout, 1h cache), and fail-closed mode. + +### Custom Configuration + +```yaml +http: + mtls: + required: true + certificateVerification: + failureMode: fail-closed # Global setting + crl: + timeout: 15000 # 15 seconds for CRL download + cacheTtl: 43200000 # Cache CRLs for 12 hours + gracePeriod: 86400000 # 24 hour grace period + failureMode: fail-closed # CRL-specific setting + ocsp: + timeout: 8000 # 8 seconds for OCSP response + cacheTtl: 7200000 # Cache results for 2 hours + errorCacheTtl: 600000 # Cache errors for 10 minutes + failureMode: fail-closed # OCSP-specific setting +``` + +### CRL Only (No OCSP) + +```yaml +http: + mtls: + certificateVerification: + ocsp: false # Disable OCSP; CRL remains enabled +``` + +Only disable OCSP if all client certificates have CRL distribution points. Otherwise, certificates without CRL URLs won't be checked for revocation. + +### OCSP Only (No CRL) + +```yaml +http: + mtls: + certificateVerification: + crl: false # Disable CRL; OCSP remains enabled +``` + +### Environment Variables + +All settings can be configured via environment variables: + +```bash +# Enable certificate verification +HTTP_MTLS_CERTIFICATEVERIFICATION=true + +# Global failure mode +HTTP_MTLS_CERTIFICATEVERIFICATION_FAILUREMODE=fail-closed + +# CRL settings +HTTP_MTLS_CERTIFICATEVERIFICATION_CRL=true +HTTP_MTLS_CERTIFICATEVERIFICATION_CRL_TIMEOUT=15000 +HTTP_MTLS_CERTIFICATEVERIFICATION_CRL_CACHETTL=43200000 +HTTP_MTLS_CERTIFICATEVERIFICATION_CRL_GRACEPERIOD=86400000 +HTTP_MTLS_CERTIFICATEVERIFICATION_CRL_FAILUREMODE=fail-closed + +# OCSP settings +HTTP_MTLS_CERTIFICATEVERIFICATION_OCSP=true +HTTP_MTLS_CERTIFICATEVERIFICATION_OCSP_TIMEOUT=8000 +HTTP_MTLS_CERTIFICATEVERIFICATION_OCSP_CACHETTL=7200000 +HTTP_MTLS_CERTIFICATEVERIFICATION_OCSP_ERRORCACHETTL=600000 +HTTP_MTLS_CERTIFICATEVERIFICATION_OCSP_FAILUREMODE=fail-closed +``` + +For replication servers, use the `REPLICATION_` prefix instead of `HTTP_`. + +## Failure Modes + +### fail-closed (Recommended) + +**Default behavior.** Rejects connections when verification fails due to network errors, timeouts, or other operational issues. + +Use when: + +- Security is paramount +- You can tolerate false positives (rejecting valid certificates due to CA unavailability) +- Your CA infrastructure is highly available +- You're in a zero-trust environment + +```yaml +certificateVerification: + failureMode: fail-closed +``` + +### fail-open + +Allows connections when verification fails, but logs a warning. The connection is still rejected if the certificate is explicitly found to be revoked. + +Use when: + +- Availability is more important than perfect security +- Your CA infrastructure may be intermittently unavailable +- You have other compensating controls +- You're gradually rolling out certificate verification + +```yaml +certificateVerification: + failureMode: fail-open +``` + +**Important:** Invalid signatures on CRLs always result in rejection regardless of failure mode, as this indicates potential tampering. + +## Performance Considerations + +### CRL Performance + +- **First verification**: Downloads CRL (10s timeout by default) +- **Subsequent verifications**: Instant (reads from cache) +- **Background refresh**: CRL is refreshed before expiration without blocking requests +- **Memory usage**: ~10–100KB per CRL depending on size +- **Network usage**: One download per CRL per `cacheTtl` period + +### OCSP Performance + +- **First verification**: OCSP query (5s timeout by default) +- **Subsequent verifications**: Reads from cache (1 hour default) +- **Memory usage**: Minimal (~1KB per cached response) +- **Network usage**: One query per unique certificate per `cacheTtl` period + +### Optimization Tips + +Increase CRL cache TTL for stable environments: + +```yaml + +... +crl: + cacheTtl: 172800000 # 48 hours +``` + +Increase OCSP cache TTL for long-lived connections: + +```yaml + +... +ocsp: + cacheTtl: 7200000 # 2 hours +``` + +Reduce grace period for tighter revocation enforcement: + +```yaml + +... +crl: + gracePeriod: 0 # No grace period +``` + +## Production Best Practices + +### High-Security Environments + +```yaml +http: + mtls: + required: true + certificateVerification: + failureMode: fail-closed + crl: + timeout: 15000 + cacheTtl: 43200000 # 12 hours + gracePeriod: 0 # No grace period for strict enforcement + ocsp: + timeout: 8000 + cacheTtl: 3600000 # 1 hour +``` + +### High-Availability Environments + +```yaml +http: + mtls: + required: true + certificateVerification: + failureMode: fail-open # Prioritize availability + crl: + timeout: 5000 + cacheTtl: 86400000 # 24 hours + gracePeriod: 86400000 # 24 hour grace period + ocsp: + timeout: 3000 + cacheTtl: 7200000 # 2 hours +``` + +### Performance-Critical Environments + +```yaml +http: + mtls: + required: true + certificateVerification: + crl: + cacheTtl: 172800000 # 48 hours + gracePeriod: 86400000 + ocsp: + cacheTtl: 7200000 # 2 hours + errorCacheTtl: 600000 +``` + +## Troubleshooting + +### Connection Rejected: Certificate Verification Failed + +**Cause:** Certificate was found to be revoked, or verification failed in fail-closed mode. + +**Solutions:** + +1. Check if the certificate is actually revoked in the CRL or OCSP responder. +2. Verify CA infrastructure is accessible. +3. Check timeout settings — increase if needed. +4. Temporarily switch to fail-open mode while investigating. + +### High Latency on First Connection + +**Cause:** CRL is being downloaded for the first time. + +**Solutions:** + +1. This is normal; only happens once per CRL per `cacheTtl` period. +2. Subsequent connections will be fast (cached CRL). +3. Increase CRL timeout if downloads are slow: + ```yaml + crl: + timeout: 20000 # 20 seconds + ``` + +### Frequent CRL Downloads + +**Cause:** `cacheTtl` is too short, or the CRL's `nextUpdate` period is very short. + +**Solutions:** + +1. Increase `cacheTtl`: + ```yaml + crl: + cacheTtl: 172800000 # 48 hours + ``` +2. Increase `gracePeriod` to allow using slightly expired CRLs. + +### OCSP Responder Unavailable + +**Cause:** OCSP responder is down or unreachable. + +**Solutions:** + +1. CRL will be used as fallback automatically. +2. Use fail-open mode to allow connections: + ```yaml + ocsp: + failureMode: fail-open + ``` +3. Disable OCSP and rely on CRL only (ensure all certs have CRL URLs): + ```yaml + ocsp: false + ``` + +### Network or Firewall Blocking Outbound Requests + +**Cause:** Secure hosting environments often restrict outbound HTTP/HTTPS traffic. This prevents Harper from reaching CRL distribution points and OCSP responders. + +**Symptoms:** + +- Certificate verification timeouts in fail-closed mode +- Logs show connection failures to CRL/OCSP URLs +- First connection may succeed (no cached data), but subsequent connections fail after cache expires + +**Solutions:** + +1. **Allow outbound traffic to CA infrastructure** (recommended): + - Whitelist CRL distribution point URLs from your certificates + - Whitelist OCSP responder URLs from your certificates + - Example for Let's Encrypt: allow `http://x1.c.lencr.org/` and `http://ocsp.int-x3.letsencrypt.org/` + +2. **Use fail-open mode:** + + ```yaml + certificateVerification: + failureMode: fail-open + ``` + +3. **Set up an internal CRL mirror/proxy:** + + ```yaml + certificateVerification: + crl: + cacheTtl: 172800000 # 48 hours + ocsp: false + ``` + +4. **Disable verification** (if you have alternative security controls): + ```yaml + certificateVerification: false + ``` + +## Security Considerations + +Enable certificate verification when: + +- Certificates have long validity periods (> 1 day) +- You need immediate revocation capability +- Compliance requires revocation checking (PCI DSS, HIPAA, etc.) +- You're in a zero-trust security model +- Client certificates are used for API authentication + +Consider skipping it when: + +- Certificates have very short validity periods (< 24 hours) +- You rotate certificates automatically (e.g., with cert-manager) +- You have alternative revocation mechanisms +- Your CA doesn't publish CRLs or support OCSP + +Certificate verification is one layer of security. Also consider: short certificate validity periods, certificate pinning, network segmentation, access logging, and regular certificate rotation. + +## Replication + +Certificate verification works identically for replication servers. Use the `replication.mtls` configuration: + +```yaml +replication: + hostname: server-one + routes: + - server-two + mtls: + certificateVerification: true +``` + +mTLS is always required for replication and cannot be disabled. This configuration only controls whether certificate revocation checking is performed. + +For complete replication configuration, see [Replication Configuration](TODO:reference_versioned_docs/version-v4/replication/clustering.md 'Replication clustering configuration'). diff --git a/reference_versioned_docs/version-v4/security/configuration.md b/reference_versioned_docs/version-v4/security/configuration.md new file mode 100644 index 00000000..0de0d9d1 --- /dev/null +++ b/reference_versioned_docs/version-v4/security/configuration.md @@ -0,0 +1,71 @@ +--- +id: configuration +title: Authentication Configuration +--- + + + +Harper's authentication system is configured via the top-level `authentication` section of `harperdb-config.yaml`. + +```yaml +authentication: + authorizeLocal: true + cacheTTL: 30000 + enableSessions: true + operationTokenTimeout: 1d + refreshTokenTimeout: 30d + hashFunction: sha256 +``` + +## Options + +### `authorizeLocal` + +_Type: boolean — Default: `true`_ + +Automatically authorizes requests from the loopback IP address (`127.0.0.1`) as the superuser, without requiring credentials. Disable this for any Harper server that may be accessed by untrusted users from the same instance — for example, when using a local proxy or for general server hardening. + +### `cacheTTL` + +_Type: number — Default: `30000`_ + +How long (in milliseconds) an authentication result — a particular `Authorization` header or token — can be cached. Increasing this improves performance at the cost of slower revocation. + +### `enableSessions` + +_Type: boolean — Default: `true`_ + +Added in: v4.2.0 + +Enables cookie-based sessions to maintain an authenticated session across requests. This is the preferred authentication mechanism for web browsers: cookies hold the token securely without exposing it to JavaScript, reducing XSS vulnerability risk. + +### `operationTokenTimeout` + +_Type: string — Default: `1d`_ + +How long a JWT operation token remains valid before expiring. Accepts [`ms`-format](https://github.com/vercel/ms) duration strings (e.g., `1d`, `12h`, `60m`). See [JWT Authentication](./jwt-authentication.md). + +### `refreshTokenTimeout` + +_Type: string — Default: `30d`_ + +How long a JWT refresh token remains valid before expiring. Accepts [`ms`-format](https://github.com/vercel/ms) duration strings. See [JWT Authentication](./jwt-authentication.md). + +### `hashFunction` + +_Type: string — Default: `sha256`_ + +Added in: v4.5.0 + +Password hashing algorithm used when storing user passwords. Replaced the previous MD5 hashing. Options: + +- **`sha256`** — Default. Good security and excellent performance. +- **`argon2id`** — Highest security. More CPU-intensive; recommended for environments that do not require frequent password verifications. + + + +## Related + +- [JWT Authentication](./jwt-authentication.md) +- [Basic Authentication](./basic-authentication.md) +- [Users & Roles / Configuration](../users-and-roles/configuration.md) diff --git a/reference_versioned_docs/version-v4/security/jwt-authentication.md b/reference_versioned_docs/version-v4/security/jwt-authentication.md new file mode 100644 index 00000000..70123d3d --- /dev/null +++ b/reference_versioned_docs/version-v4/security/jwt-authentication.md @@ -0,0 +1,118 @@ +--- +id: jwt-authentication +title: JWT Authentication +--- + +s + +Available since: v4.1.0 + +Harper supports token-based authentication using JSON Web Tokens (JWTs). Rather than sending credentials on every request, a client authenticates once and receives tokens that are used for subsequent requests. + +## Tokens + +JWT authentication uses two token types: + +- **`operation_token`** — Used to authenticate all Harper operations via a `Bearer` token `Authorization` header. Default expiry: 1 day. +- **`refresh_token`** — Used to obtain a new `operation_token` when the current one expires. Default expiry: 30 days. + +## Create Authentication Tokens + +Call `create_authentication_tokens` with your Harper credentials. No `Authorization` header is required for this operation. + +```json +{ + "operation": "create_authentication_tokens", + "username": "username", + "password": "password" +} +``` + +cURL example: + +```bash +curl --location --request POST 'http://localhost:9925' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "operation": "create_authentication_tokens", + "username": "username", + "password": "password" +}' +``` + +Response: + +```json +{ + "operation_token": "", + "refresh_token": "" +} +``` + +## Using the Operation Token + +Pass the `operation_token` as a `Bearer` token in the `Authorization` header on subsequent requests: + +```bash +curl --location --request POST 'http://localhost:9925' \ +--header 'Content-Type: application/json' \ +--header 'Authorization: Bearer ' \ +--data-raw '{ + "operation": "search_by_hash", + "schema": "dev", + "table": "dog", + "hash_values": [1], + "get_attributes": ["*"] +}' +``` + +## Refreshing the Operation Token + +When the `operation_token` expires, use the `refresh_token` to obtain a new one. Pass the `refresh_token` as the `Bearer` token: + +```bash +curl --location --request POST 'http://localhost:9925' \ +--header 'Content-Type: application/json' \ +--header 'Authorization: Bearer ' \ +--data-raw '{ + "operation": "refresh_operation_token" +}' +``` + +Response: + +```json +{ + "operation_token": "" +} +``` + +When both tokens have expired, call `create_authentication_tokens` again with your username and password. + +## Token Expiry Configuration + +Token timeouts are configurable in `harperdb-config.yaml` under the top-level `authentication` section: + +```yaml +authentication: + operationTokenTimeout: 1d # Default: 1 day + refreshTokenTimeout: 30d # Default: 30 days +``` + +Valid duration string values follow the [`ms` package format](https://github.com/vercel/ms) (e.g., `1d`, `12h`, `60m`). See [Security / Configuration](./configuration.md) for the full authentication config reference. + +## When to Use JWT Auth + +JWT authentication is preferred over Basic Auth when: + +- You want to avoid sending credentials on every request +- Your client can store and manage tokens +- You have multiple sequential requests and want to avoid repeated credential encoding + +For simple or server-to-server scenarios, see [Basic Authentication](./basic-authentication.md). + +## Security Notes + +- Always use HTTPS in production to protect tokens in transit. See [HTTP / TLS](../http/tls.md). +- Store tokens securely; treat them like passwords. +- If a token is compromised, it will remain valid until it expires. Consider setting shorter `operationTokenTimeout` values in high-security environments. diff --git a/reference_versioned_docs/version-v4/security/mtls-authentication.md b/reference_versioned_docs/version-v4/security/mtls-authentication.md new file mode 100644 index 00000000..35618425 --- /dev/null +++ b/reference_versioned_docs/version-v4/security/mtls-authentication.md @@ -0,0 +1,79 @@ +--- +id: mtls-authentication +title: mTLS Authentication +--- + + + + +Added in: v4.3.0 + +Harper supports Mutual TLS (mTLS) authentication for incoming HTTP connections. When enabled, the client must present a certificate signed by a trusted Certificate Authority (CA). If the certificate is valid and trusted, the connection is authenticated using the user whose username matches the `CN` (Common Name) from the client certificate's `subject`. + +## How It Works + +1. The client presents a TLS certificate during the handshake. +2. Harper validates the certificate against the configured CA (`tls.certificateAuthority`). +3. If valid, Harper extracts the `CN` from the certificate subject and uses it as the username for the request. +4. Optionally, Harper checks whether the certificate has been revoked (see [Certificate Verification](./certificate-verification.md)). + +## Configuration + +mTLS is configured via the `http.mtls` section in `harperdb-config.yaml`. + +**Require mTLS for all connections:** + +```yaml +http: + mtls: + required: true +tls: + certificateAuthority: ~/hdb/keys/ca.pem +``` + +**Make mTLS optional (accept both mTLS and non-mTLS connections):** + +```yaml +http: + mtls: + required: false +tls: + certificateAuthority: ~/hdb/keys/ca.pem +``` + +When `required` is `false`, clients that do not present a certificate will fall back to other authentication methods (Basic Auth or JWT). + +For more configuration information see the [HTTP / Configuration](../http/configuration.md) and [HTTP / TLS](../http/tls.md) sections. + +## Certificate Revocation Checking + +When using mTLS, you can optionally enable certificate revocation checking to ensure that revoked certificates cannot authenticate, even if they are otherwise valid and trusted. + +To enable: + +```yaml +http: + mtls: + required: true + certificateVerification: true +``` + +Certificate revocation checking is **disabled by default** and must be explicitly enabled. For full details on CRL and OCSP configuration, see [Certificate Verification](./certificate-verification.md). + +## User Identity + +The username for the mTLS-authenticated request is derived from the `CN` field of the client certificate's subject. Ensure the CN value matches an existing Harper user account. See [Users and Roles](./users-and-roles.md) for managing user accounts. + +## Setup Requirements + +To use mTLS you need: + +1. A Certificate Authority (CA) certificate configured in `tls.certificateAuthority`. +2. Client certificates signed by that CA, with a `CN` matching a Harper username. +3. The `http.mtls` configuration enabled. + +For help generating and managing certificates, see [Certificate Management](./certificate-management.md). + +## Replication + +mTLS is always required for Harper replication and cannot be disabled. For replication-specific mTLS configuration, see [Replication Configuration](TODO:reference_versioned_docs/version-v4/replication/clustering.md 'Replication clustering configuration'). diff --git a/reference_versioned_docs/version-v4/security/overview.md b/reference_versioned_docs/version-v4/security/overview.md new file mode 100644 index 00000000..207645e2 --- /dev/null +++ b/reference_versioned_docs/version-v4/security/overview.md @@ -0,0 +1,51 @@ +--- +id: overview +title: Security +--- + + + + +Harper uses role-based, attribute-level security to ensure that users can only gain access to the data they are supposed to be able to access. Granular permissions allow for unparalleled flexibility and control, and can lower the total cost of ownership compared to other database solutions, since you no longer need to replicate subsets of data to isolate use cases. + +## Authentication Methods + +Harper supports three authentication methods: + +- [Basic Authentication](./basic-authentication.md) — Username and password sent as a Base64-encoded `Authorization` header on every request. +- [JWT Authentication](./jwt-authentication.md) — Token-based authentication using JSON Web Tokens. Clients authenticate once and receive short-lived operation tokens and longer-lived refresh tokens. +- [mTLS Authentication](./mtls-authentication.md) — Mutual TLS certificate-based authentication. + +## Certificate Management + +- [Certificate Management](./certificate-management.md) — Managing TLS certificates and Certificate Authorities for HTTPS and mTLS. +- [Certificate Verification](./certificate-verification.md) — Certificate revocation checking via CRL and OCSP. + +## Access Control + +- CORS — Cross-Origin Resource Sharing. + - For HTTP server configuration see [HTTP / Configuration / CORS](../http/configuration.md#cors) + - For Operations API configuration see [Operations API / Configuration / Network](TODO: ../operations-api/configuration.md#network) +- SSL & HTTPS — Enabling HTTPS and configuring TLS for the HTTP server. + - For HTTP server configuration see [HTTP / Configuration / TLS](../http/tls.md) + - For Operations API configuration see [Operations API / Configuration / TLS](TODO: ../operations-api/configuration.md#tls) +- [Users and Roles](./users-and-roles.md) — Role-Based Access Control (RBAC): defining roles, assigning permissions, and managing users. + +## Security Philosophy + +Harper's security model has two distinct layers: + +**Authentication** determines _who_ is making a request. Harper validates each request using one of the methods above, then resolves the caller to a known Harper user account. + +**Authorization** determines _what_ the caller can do. Each Harper user is assigned a role. Roles carry a permissions set that grants or denies CRUD access at the table and attribute level, in addition to controlling access to system operations. + +For details on how roles and permissions work, see [Users and Roles](./users-and-roles.md). + +## Default Behavior + +Out of the box, Harper: + +- Generates self-signed TLS certificates at `/keys/` on first run. +- Runs with HTTPS disabled (HTTP only on port 9925 for the Operations API). It is recommended that you never directly expose Harper's HTTP interface through a publicly available port. +- Enables CORS for all origins (configurable). +- Supports Basic Auth and JWT Auth by default; mTLS must be explicitly configured. diff --git a/reference_versioned_docs/version-v4/users-and-roles/configuration.md b/reference_versioned_docs/version-v4/users-and-roles/configuration.md new file mode 100644 index 00000000..8177180b --- /dev/null +++ b/reference_versioned_docs/version-v4/users-and-roles/configuration.md @@ -0,0 +1,67 @@ +--- +id: configuration +title: Configuration +--- + + + + + +## Managing Roles with Config Files + +In addition to managing roles via the Operations API, Harper supports declaring roles in a configuration file. When the application starts, Harper ensures all declared roles exist with the specified permissions. + +Configure in your application's `config.yaml`: + +```yaml +roles: + files: roles.yaml +``` + +Example `roles.yaml`: + +```yaml +analyst: + super_user: false + data: + Sales: + read: true + insert: false + update: false + delete: false + +editor: + data: + Articles: + read: true + insert: true + update: true + attributes: + title: + read: true + update: true + author: + read: true + update: false +``` + +**Startup behavior:** + +- If a declared role does not exist, Harper creates it. +- If a declared role already exists, Harper updates its permissions to match the definition. + +## Password Hashing + +Added in: v4.5.0 + +Harper supports two password hashing algorithms, replacing the previous MD5 hashing: + +- **`sha256`** — Default algorithm. Good security and excellent performance. +- **`argon2id`** — Highest security. More CPU-intensive; recommended for high-security environments. + +Password hashing is configured via the `authentication.hashFunction` key in `harperdb-config.yaml`. See [Security / Configuration](../security/configuration.md#hashfunction) for details. + +## Related + +- [Overview](./overview) +- [Operations](./operations) diff --git a/reference_versioned_docs/version-v4/users-and-roles/operations.md b/reference_versioned_docs/version-v4/users-and-roles/operations.md new file mode 100644 index 00000000..5dc7c56f --- /dev/null +++ b/reference_versioned_docs/version-v4/users-and-roles/operations.md @@ -0,0 +1,176 @@ +--- +id: operations +title: Operations +--- + + + +## Roles + +### List Roles + +_Restricted to `super_user` roles._ + +```json +{ + "operation": "list_roles" +} +``` + +### Add Role + +_Restricted to `super_user` roles._ + +- `role` _(required)_ — Name for the new role. +- `permission` _(required)_ — Permissions object. See [Permission Structure](./overview#permission-structure). + - `super_user` _(optional)_ — If `true`, grants full access. Defaults to `false`. + - `structure_user` _(optional)_ — Boolean or array of database names. If `true`, can create/drop databases and tables. If array, limited to specified databases. + +```json +{ + "operation": "add_role", + "role": "developer", + "permission": { + "super_user": false, + "structure_user": false, + "dev": { + "tables": { + "dog": { + "read": true, + "insert": true, + "update": true, + "delete": false, + "attribute_permissions": [ + { + "attribute_name": "name", + "read": true, + "insert": true, + "update": true + } + ] + } + } + } + } +} +``` + +### Alter Role + +_Restricted to `super_user` roles._ + +- `id` _(required)_ — The `id` of the role to alter (from `list_roles`). +- `role` _(optional)_ — New name for the role. +- `permission` _(required)_ — Updated permissions object. + +```json +{ + "operation": "alter_role", + "id": "f92162e2-cd17-450c-aae0-372a76859038", + "role": "another_developer", + "permission": { + "super_user": false, + "structure_user": false, + "dev": { + "tables": { + "dog": { + "read": true, + "insert": true, + "update": true, + "delete": false, + "attribute_permissions": [] + } + } + } + } +} +``` + +### Drop Role + +_Restricted to `super_user` roles. Roles with associated users cannot be dropped._ + +- `id` _(required)_ — The `id` of the role to drop. + +```json +{ + "operation": "drop_role", + "id": "developer" +} +``` + +## Users + +### List Users + +_Restricted to `super_user` roles._ + +```json +{ + "operation": "list_users" +} +``` + +### User Info + +Returns user data for the currently authenticated user. Available to all roles. + +```json +{ + "operation": "user_info" +} +``` + +### Add User + +_Restricted to `super_user` roles._ + +- `role` _(required)_ — Role name to assign. +- `username` _(required)_ — Username. Cannot be changed after creation. +- `password` _(required)_ — Plain-text password. Harper encrypts it on receipt. +- `active` _(required)_ — Boolean. If `false`, user cannot access Harper. + +```json +{ + "operation": "add_user", + "role": "role_name", + "username": "hdb_user", + "password": "password", + "active": true +} +``` + +### Alter User + +_Restricted to `super_user` roles._ + +- `username` _(required)_ — Username to modify. +- `password` _(optional)_ — New password. +- `role` _(optional)_ — New role name. +- `active` _(optional)_ — Enable/disable user access. + +```json +{ + "operation": "alter_user", + "role": "role_name", + "username": "hdb_user", + "password": "new_password", + "active": true +} +``` + +### Drop User + +_Restricted to `super_user` roles._ + +```json +{ + "operation": "drop_user", + "username": "harper" +} +``` + +## Related + +- [Overview](./overview) +- [Configuration](./configuration) diff --git a/reference_versioned_docs/version-v4/users-and-roles/overview.md b/reference_versioned_docs/version-v4/users-and-roles/overview.md new file mode 100644 index 00000000..0ec547bc --- /dev/null +++ b/reference_versioned_docs/version-v4/users-and-roles/overview.md @@ -0,0 +1,254 @@ +--- +id: overview +title: Users & Roles +--- + + + + +Harper uses a Role-Based Access Control (RBAC) framework to manage access to Harper instances. Each user is assigned a role that determines their permissions to access database resources and run operations. + +## Roles + +Role permissions in Harper are divided into two categories: + +**Database Manipulation** — CRUD (create, read, update, delete) permissions against database data (tables and attributes). + +**Database Definition** — Permissions to manage databases, tables, roles, users, and other system settings. These are restricted to the built-in `super_user` role. + +### Built-In Roles + +| Role | Description | +| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| `super_user` | Full access to all operations and methods. The admin role. | +| `cluster_user` | Internal system role that allows clustered instances to communicate. Managed internally. | +| `structure_user` | Access to create and delete databases and tables. Can be set to `true` (all databases) or an array of database names (specific databases only). | + +### User-Defined Roles + +Admins (`super_user` users) can create custom roles with explicit permissions on specific tables and attributes. + +- Unless a user-defined role has `super_user: true`, all permissions must be defined explicitly. +- Any table or database not included in the role's permission set will be inaccessible. +- `describe` operations return metadata only for databases, tables, and attributes that the role has CRUD permissions for. + +## Permission Structure + +When creating or altering a role, you define a `permission` object: + +```json +{ + "operation": "add_role", + "role": "software_developer", + "permission": { + "super_user": false, + "database_name": { + "tables": { + "table_name1": { + "read": true, + "insert": true, + "update": true, + "delete": false, + "attribute_permissions": [ + { + "attribute_name": "attribute1", + "read": true, + "insert": true, + "update": true + } + ] + }, + "table_name2": { + "read": true, + "insert": true, + "update": true, + "delete": false, + "attribute_permissions": [] + } + } + } + } +} +``` + +### Table Permissions + +Each table entry defines CRUD access: + +```jsonc +{ + "table_name": { + "read": boolean, // Access to read from this table + "insert": boolean, // Access to insert data + "update": boolean, // Access to update data + "delete": boolean, // Access to delete rows + "attribute_permissions": [ + { + "attribute_name": "attribute_name", + "read": boolean, + "insert": boolean, + "update": boolean + // Note: "delete" is not an attribute-level permission + } + ] + } +} +``` + +### Important Rules + +**Table-level:** + +- If a database or table is not included in the permissions, the role has no access to it. +- If a table-level CRUD permission is `false`, setting the same CRUD permission to `true` on an attribute returns an error. + +**Attribute-level:** + +- If `attribute_permissions` is a non-empty array, only the listed attributes are accessible (plus the table's hash attribute — see below). +- If `attribute_permissions` is empty (`[]`), attribute access follows the table-level CRUD permissions. +- If any non-hash attribute is given CRUD access, the table's `hash_attribute` (primary key) automatically receives the same access, even if not explicitly listed. +- Any attribute not explicitly listed in a non-empty `attribute_permissions` array has no access. +- `DELETE` is not an attribute-level permission. Deleting rows is controlled at the table level. +- The `__createdtime__` and `__updatedtime__` attributes managed by Harper can have `read` permissions set; other attribute-level permissions for these fields are ignored. + +## Role-Based Operation Restrictions + +The following table shows which operations are restricted to `super_user` roles. Non-`super_user` roles are also restricted within their accessible operations by their CRUD permission set. + +### Databases and Tables + +| Operation | Restricted to Super User | +| ------------------- | :----------------------: | +| `describe_all` | | +| `describe_database` | | +| `describe_table` | | +| `create_database` | X | +| `drop_database` | X | +| `create_table` | X | +| `drop_table` | X | +| `create_attribute` | | +| `drop_attribute` | X | + +### NoSQL Operations + +| Operation | Restricted to Super User | +| ---------------------- | :----------------------: | +| `insert` | | +| `update` | | +| `upsert` | | +| `delete` | | +| `search_by_hash` | | +| `search_by_value` | | +| `search_by_conditions` | | + +### SQL Operations + +| Operation | Restricted to Super User | +| --------- | :----------------------: | +| `select` | | +| `insert` | | +| `update` | | +| `delete` | | + +### Bulk Operations + +| Operation | Restricted to Super User | +| ---------------- | :----------------------: | +| `csv_data_load` | | +| `csv_file_load` | | +| `csv_url_load` | | +| `import_from_s3` | | + +### Users and Roles + +| Operation | Restricted to Super User | +| ------------ | :----------------------: | +| `list_roles` | X | +| `add_role` | X | +| `alter_role` | X | +| `drop_role` | X | +| `list_users` | X | +| `user_info` | | +| `add_user` | X | +| `alter_user` | X | +| `drop_user` | X | + +### Clustering + +| Operation | Restricted to Super User | +| ----------------------- | :----------------------: | +| `cluster_set_routes` | X | +| `cluster_get_routes` | X | +| `cluster_delete_routes` | X | +| `add_node` | X | +| `update_node` | X | +| `cluster_status` | X | +| `remove_node` | X | +| `configure_cluster` | X | + +### Components + +| Operation | Restricted to Super User | +| -------------------- | :----------------------: | +| `get_components` | X | +| `get_component_file` | X | +| `set_component_file` | X | +| `drop_component` | X | +| `add_component` | X | +| `package_component` | X | +| `deploy_component` | X | + +### Registration + +| Operation | Restricted to Super User | +| ------------------- | :----------------------: | +| `registration_info` | | +| `get_fingerprint` | X | +| `set_license` | X | + +### Jobs + +| Operation | Restricted to Super User | +| --------------------------- | :----------------------: | +| `get_job` | | +| `search_jobs_by_start_date` | X | + +### Logs + +| Operation | Restricted to Super User | +| -------------------------------- | :----------------------: | +| `read_log` | X | +| `read_transaction_log` | X | +| `delete_transaction_logs_before` | X | +| `read_audit_log` | X | +| `delete_audit_logs_before` | X | + +### Utilities + +| Operation | Restricted to Super User | +| ----------------------- | :----------------------: | +| `delete_records_before` | X | +| `export_local` | X | +| `export_to_s3` | X | +| `system_information` | X | +| `restart` | X | +| `restart_service` | X | +| `get_configuration` | X | + +### Token Authentication + +| Operation | Restricted to Super User | +| ------------------------------ | :----------------------: | +| `create_authentication_tokens` | | +| `refresh_operation_token` | | + +## Troubleshooting: "Must execute as User" + +If you see the error `Error: Must execute as <>`, it means Harper was installed as a specific OS user and must be run by that same user. Harper stores files natively on the operating system and only allows the Harper executable to be run by a single user — this prevents file permission issues and keeps the installation secure. + +To resolve: run Harper with the same OS user account used during installation. + +## Related + +- [Configuration](./configuration) +- [Operations](./operations) diff --git a/reference_versioned_sidebars/version-v4-sidebars.json b/reference_versioned_sidebars/version-v4-sidebars.json index 3deba702..5d3a1bf8 100644 --- a/reference_versioned_sidebars/version-v4-sidebars.json +++ b/reference_versioned_sidebars/version-v4-sidebars.json @@ -154,6 +154,72 @@ } ] }, + { + "type": "category", + "label": "Security", + "collapsible": false, + "className": "learn-category-header", + "items": [ + { + "type": "doc", + "id": "security/overview", + "label": "Overview" + }, + { + "type": "doc", + "id": "security/configuration", + "label": "Configuration" + }, + { + "type": "doc", + "id": "security/basic-authentication", + "label": "Basic Authentication" + }, + { + "type": "doc", + "id": "security/jwt-authentication", + "label": "JWT Authentication" + }, + { + "type": "doc", + "id": "security/mtls-authentication", + "label": "mTLS Authentication" + }, + { + "type": "doc", + "id": "security/certificate-management", + "label": "Certificate Management" + }, + { + "type": "doc", + "id": "security/certificate-verification", + "label": "Certificate Verification" + } + ] + }, + { + "type": "category", + "label": "Users & Roles", + "collapsible": false, + "className": "learn-category-header", + "items": [ + { + "type": "doc", + "id": "users-and-roles/overview", + "label": "Overview" + }, + { + "type": "doc", + "id": "users-and-roles/configuration", + "label": "Configuration" + }, + { + "type": "doc", + "id": "users-and-roles/operations", + "label": "Operations" + } + ] + }, { "type": "category", "label": "Legacy", diff --git a/v4-docs-migration-map.md b/v4-docs-migration-map.md index d0b689ef..6bd81511 100644 --- a/v4-docs-migration-map.md +++ b/v4-docs-migration-map.md @@ -124,28 +124,28 @@ This document maps existing documentation paths from `versioned_docs/version-4.X - **Primary Source**: `versioned_docs/version-4.7/developers/security/index.md` - **Additional Sources**: - `versioned_docs/version-4.7/developers/security/configuration.md` -- **Status**: Not Started +- **Status**: In Progress ### `reference/security/basic-authentication.md` - **Primary Source**: `versioned_docs/version-4.7/developers/security/basic-auth.md` - **Additional Sources**: `versioned_docs/version-4.1/security/basic-authentication.md` - **Version Annotations**: Available since v4.1.0 -- **Status**: Not Started +- **Status**: In Progress ### `reference/security/jwt-authentication.md` - **Primary Source**: `versioned_docs/version-4.7/developers/security/jwt-auth.md` - **Additional Sources**: `versioned_docs/version-4.1/security/jwt.md` - **Version Annotations**: Available since v4.1.0 -- **Status**: Not Started +- **Status**: In Progress ### `reference/security/mtls-authentication.md` - **Primary Source**: `versioned_docs/version-4.7/developers/security/mtls-auth.md` - **Additional Sources**: `versioned_docs/version-4.3/developers/security/mtls-auth.md` - **Version Annotations**: Added in v4.3.0 -- **Status**: Not Started +- **Status**: In Progress - **Release Notes**: - [4.3.0](release-notes/v4-tucker/4.3.0.md) - mTLS support added @@ -157,7 +157,7 @@ This document maps existing documentation paths from `versioned_docs/version-4.X - `versioned_docs/version-4.4+` (dynamic cert management added) - **Merge Required**: Yes - dynamic certificate management added in v4.4 - **Version Annotations**: Dynamic certs added v4.4.0 -- **Status**: Not Started +- **Status**: In Progress - **Release Notes**: - [4.4.0](release-notes/v4-tucker/4.4.0.md) - Dynamic certificate management - [4.5.0](release-notes/v4-tucker/4.5.0.md) - Certificate revocation @@ -166,19 +166,19 @@ This document maps existing documentation paths from `versioned_docs/version-4.X - **Primary Source**: `versioned_docs/version-4.7/developers/security/certificate-verification.md` - **Version Annotations**: Added in v4.7.0 (OCSP support) -- **Status**: Not Started +- **Status**: In Progress - **Release Notes**: - [4.7.0](release-notes/v4-tucker/4.7.0.md) - OCSP support ### `reference/security/cors.md` - **Primary Source**: Extract from `versioned_docs/version-4.7/developers/security/configuration.md` -- **Status**: Not Started +- **Status**: In Progress ### `reference/security/ssl.md` - **Primary Source**: Extract from security/configuration or certificate management docs -- **Status**: Not Started +- **Status**: In Progress ### `reference/security/users-and-roles.md` @@ -188,7 +188,7 @@ This document maps existing documentation paths from `versioned_docs/version-4.X - `versioned_docs/version-4.7/reference/roles.md` - Current `reference/defining-roles.md` - **Merge Required**: Yes - content spread across multiple files -- **Status**: Not Started +- **Status**: In Progress - **Release Notes**: - [4.5.0](release-notes/v4-tucker/4.5.0.md) - Password hashing upgrade (sha256, argon2id) - [4.2.0](release-notes/v4-tucker/4.2.0.md) - Cookie-based sessions diff --git a/v4-docs-reference-plan.md b/v4-docs-reference-plan.md index 6b03eb9b..983c3711 100644 --- a/v4-docs-reference-plan.md +++ b/v4-docs-reference-plan.md @@ -229,11 +229,20 @@ reference/ │ │ │ ├── certificate-verification.md # Certificate verification (OCSP, etc.) │ │ -│ ├── cors.md # CORS configuration and usage +│ └── configuration.md # Authentication configuration (authorizeLocal, cacheTTL, +│ # enableSessions, token timeouts, hashFunction). Top-level +│ # `authentication:` section of harperdb-config.yaml. +│ +├── users-and-roles/ # Broken out from security/ during migration — RBAC warrants +│ │ # its own top-level section given the breadth of content +│ │ # (operations API, config file roles, permission structure). +│ │ +│ ├── overview.md # RBAC intro, roles, permission structure, operation +│ │ # restrictions reference table │ │ -│ ├── ssl.md # SSL/TLS configuration +│ ├── configuration.md # Config file roles (roles.yaml), password hashing │ │ -│ └── users-and-roles.md # User and role management including `roles` plugin +│ └── operations.md # Operations API: all role and user operations │ ├── components/ │ ├── overview.md # What are components? Evolution from custom functions to