Security and Users & Roles Sections Migration

[Ethan-Arrowood]

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

[github-actions]

🚀 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]

🚀 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]

🚀 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]

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