Security and Users & Roles Sections Migration by Ethan-Arrowood · Pull Request #452 · HarperFast/documentation

Ethan-Arrowood · 2026-03-04T18:06:15Z

Security and Users & Roles Sections Migration

Summary

Migration of Security and Users & Roles documentation from versioned_docs into the new reference_versioned_docs/version-v4/ structure.

Originally scoped as a single security/users-and-roles.md page, Users & Roles was promoted to its own top-level section during migration due to the breadth of content (permission structure reference, config file roles, full Operations API coverage). This also revealed that authentication config was a top-level key in harperdb-config.yaml — not nested under operationsApi as the source docs incorrectly implied — and that authentication.hashFunction (password hashing algorithm, added in v4.5.0) was entirely undocumented.

Files Created

Security

reference_versioned_docs/version-v4/security/overview.md
reference_versioned_docs/version-v4/security/configuration.md (new — documents authentication: config block, including undocumented hashFunction key)
reference_versioned_docs/version-v4/security/basic-authentication.md
reference_versioned_docs/version-v4/security/jwt-authentication.md
reference_versioned_docs/version-v4/security/mtls-authentication.md
reference_versioned_docs/version-v4/security/certificate-management.md
reference_versioned_docs/version-v4/security/certificate-verification.md

Users & Roles (new top-level section)

reference_versioned_docs/version-v4/users-and-roles/overview.md
reference_versioned_docs/version-v4/users-and-roles/configuration.md
reference_versioned_docs/version-v4/users-and-roles/operations.md

Other

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

Files Removed

reference_versioned_docs/version-v4/security/cors.md (content lives in http/configuration.md)
reference_versioned_docs/version-v4/security/ssl.md (content lives in http/tls.md)
reference_versioned_docs/version-v4/security/users-and-roles.md (replaced by users-and-roles/ section)

Notable Changes vs. Original Plan

Users & Roles promoted to top-level section: The original plan had security/users-and-roles.md as a single page. During migration it was split into users-and-roles/overview.md, users-and-roles/configuration.md, and users-and-roles/operations.md — consistent with how other content-rich sections like logging/ are structured.
security/configuration.md added: The source docs incorrectly nested token timeout config under operationsApi.authentication; the actual key is top-level authentication:. A dedicated configuration page now documents all auth config options. The jwt-authentication.md page has been corrected accordingly.
authentication.hashFunction documented for first time: The v4.5.0 password hashing feature (sha256/argon2id) was noted in release notes but never had a documented config key. security/configuration.md documents it with a TODO to verify the exact key name against Harper source.
Plan updated: v4-docs-reference-plan.md updated to reflect the new users-and-roles/ top-level section and security/configuration.md.

Source Files Used

security/overview.md

versioned_docs/version-4.7/developers/security/index.md (primary)
versioned_docs/version-4.7/developers/security/configuration.md (CORS/SSL overview)

security/configuration.md

versioned_docs/version-4.7/deployments/configuration.md (authentication section)

security/basic-authentication.md

versioned_docs/version-4.7/developers/security/basic-auth.md (primary)

security/jwt-authentication.md

versioned_docs/version-4.7/developers/security/jwt-auth.md (primary)

security/mtls-authentication.md

versioned_docs/version-4.7/developers/security/mtls-auth.md (primary)
release-notes/v4-tucker/4.3.0.md (confirmed mTLS introduction)

security/certificate-management.md

versioned_docs/version-4.7/developers/security/certificate-management.md (primary)
release-notes/v4-tucker/4.4.0.md (dynamic certificate management)
release-notes/v4-tucker/4.5.0.md (certificate revocation)

security/certificate-verification.md

versioned_docs/version-4.7/developers/security/certificate-verification.md (primary)
release-notes/v4-tucker/4.5.0.md (revocation support)
release-notes/v4-tucker/4.7.0.md (OCSP support confirmed)

users-and-roles/overview.md

versioned_docs/version-4.7/developers/security/users-and-roles.md (primary)

users-and-roles/configuration.md

versioned_docs/version-4.7/reference/roles.md (roles config file format)
release-notes/v4-tucker/4.5.0.md (password hashing upgrade)

users-and-roles/operations.md

versioned_docs/version-4.7/developers/operations-api/users-and-roles.md (primary)

Version Annotations Added

High Confidence (Confirmed via release notes)

mTLS Authentication: Added in v4.3.0
Dynamic Certificate Management: Added in v4.4.0
Certificate Revocation: Added in v4.5.0
OCSP Support: Added in v4.7.0
Password Hashing (sha256, argon2id): Added in v4.5.0
Cookie-based sessions (enableSessions): Added in v4.2.0

Needs Verification

Basic Auth available since v4.1.0 (inferred from migration map; v4.1 source files not found in repo)
JWT Auth available since v4.1.0 (same note)
authentication.hashFunction config key name (documented in release notes but key name not in any source doc — TODO left in security/configuration.md)

Link Placeholders

See migration-context/link-placeholders/security-link-placeholders.md for complete list.

Summary:

3 placeholders to replication/clustering section (mTLS for replication)
3 already resolved (cli/commands.md, http/configuration.md, http/tls.md)

Checklist for Human Reviewer

Verify v4.1.0 "available since" annotations for Basic Auth and JWT
Confirm authentication.hashFunction is the correct config key name and remove the TODO in security/configuration.md
Review users-and-roles operation examples for accuracy
Check inline source comments are accurate
Ensure link placeholders to replication/clustering make sense
Update migration-map.md status to "Complete" after merge

🤖 Generated with Claude Code

Migrates all security documentation from versioned_docs into the new reference_versioned_docs/version-v4/security/ structure. Includes 9 pages covering authentication methods, certificate management, CORS, SSL/HTTPS configuration, and users/roles RBAC. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

github-actions · 2026-03-04T18:08:47Z

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-452

This preview will update automatically when you push new commits.

Splits security/users-and-roles.md into a dedicated users-and-roles/ section with overview, configuration, and operations files. Updates the sidebar to reflect the new top-level "Users & Roles" category. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

github-actions · 2026-03-06T21:40:38Z

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-452

This preview will update automatically when you push new commits.

- Add security/configuration.md covering the top-level `authentication:` config block (authorizeLocal, cacheTTL, enableSessions, token timeouts, hashFunction) with a TODO to verify the hashFunction key name - Fix jwt-authentication.md: config was incorrectly nested under `operationsApi.authentication` — it is a top-level `authentication:` section - Fix jwt-authentication.md: update broken ssl.md link to http/tls.md - Update users-and-roles/configuration.md: replace fabricated config snippet with a link to security/configuration.md#hashfunction Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

github-actions · 2026-03-11T15:10:30Z

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-452

This preview will update automatically when you push new commits.

…ection Notes that users-and-roles was broken out from security/ during migration, and documents the new users-and-roles/ and security/configuration.md structure. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

github-actions · 2026-03-11T15:15:28Z

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-452

This preview will update automatically when you push new commits.

reference_versioned_docs/version-v4/security/overview.md

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

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

kriszyp

This is looking great!

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

reference_versioned_docs/version-v4/security/configuration.md

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

kriszyp · 2026-03-16T13:52:25Z

reference_versioned_docs/version-v4/users-and-roles/overview.md

+| 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.                                                        |


This doesn't exist anymore and should be removed.

But it existed in v4 at some point, right? Which version did we remove it? Just v5 or some point in v4 minors?

github-actions · 2026-03-16T17:56:09Z

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-452

This preview will update automatically when you push new commits.

github-actions · 2026-03-16T18:15:33Z

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-452

This preview will update automatically when you push new commits.

github-actions · 2026-03-16T21:02:43Z

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-452

This preview will update automatically when you push new commits.

Ethan-Arrowood requested a review from a team as a code owner March 4, 2026 18:06

Ethan-Arrowood marked this pull request as draft March 4, 2026 18:06

Ethan-Arrowood mentioned this pull request Mar 4, 2026

Docs -> Reference (Major version consolidation) Base #436

Draft

25 tasks

github-actions bot temporarily deployed to pr-452 March 4, 2026 18:08 Inactive

Ethan-Arrowood and others added 2 commits March 4, 2026 16:27

manual edits to security sections

8898658

github-actions bot temporarily deployed to pr-452 March 6, 2026 21:40 Inactive

Ethan-Arrowood and others added 2 commits March 10, 2026 16:05

finish security and users-and-roles sections

f5e8bb8

Ethan-Arrowood marked this pull request as ready for review March 11, 2026 15:08

Ethan-Arrowood changed the title ~~Security Section Migration~~ Security and Users-and-Roles Sections Migration Mar 11, 2026

github-actions bot temporarily deployed to pr-452 March 11, 2026 15:10 Inactive

Ethan-Arrowood changed the title ~~Security and Users-and-Roles Sections Migration~~ Security and Users & Roles Sections Migration Mar 11, 2026

github-actions bot temporarily deployed to pr-452 March 11, 2026 15:15 Inactive

cb1kenobi reviewed Mar 12, 2026

View reviewed changes

kriszyp reviewed Mar 16, 2026

View reviewed changes

pr review fixes

9e6f98f

github-actions bot temporarily deployed to pr-452 March 16, 2026 17:56 Inactive

switch to jsonwebtoken module reference

a3715eb

github-actions bot temporarily deployed to pr-452 March 16, 2026 18:15 Inactive

remove cluster_user

4ed8ba7

github-actions bot deployed to pr-452 March 16, 2026 21:02 View deployment

Conversation

Ethan-Arrowood commented Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Security and Users & Roles Sections Migration

Summary

Files Created

Security

Users & Roles (new top-level section)

Other

Files Removed

Notable Changes vs. Original Plan

Source Files Used

security/overview.md

security/configuration.md

security/basic-authentication.md

security/jwt-authentication.md

security/mtls-authentication.md

security/certificate-management.md

security/certificate-verification.md

users-and-roles/overview.md

users-and-roles/configuration.md

users-and-roles/operations.md

Version Annotations Added

High Confidence (Confirmed via release notes)

Needs Verification

Link Placeholders

Checklist for Human Reviewer

Uh oh!

github-actions bot commented Mar 4, 2026

🚀 Preview Deployment

Uh oh!

github-actions bot commented Mar 6, 2026

🚀 Preview Deployment

Uh oh!

github-actions bot commented Mar 11, 2026

🚀 Preview Deployment

Uh oh!

github-actions bot commented Mar 11, 2026

🚀 Preview Deployment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kriszyp left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kriszyp Mar 16, 2026

Choose a reason for hiding this comment

Uh oh!

Ethan-Arrowood Mar 16, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Mar 16, 2026

🚀 Preview Deployment

Uh oh!

github-actions bot commented Mar 16, 2026

🚀 Preview Deployment

Uh oh!

github-actions bot commented Mar 16, 2026

🚀 Preview Deployment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Ethan-Arrowood commented Mar 4, 2026 •

edited

Loading