[BE-131] Document a secrets management and rotation procedure

[mftee]

Overview

The backend depends on a JWT signing secret, database credentials, mail credentials, OAuth client secrets for Google and GitHub, and Stellar configuration. There is no documented procedure for how these are supplied, who can access them, or how they are rotated.

A written procedure is what makes rotation a routine operation rather than an emergency.

Tasks

• Document every secret the system requires, what it protects, and the blast radius if it leaks.
• Document where each is stored per environment (platform secret store, CI secrets) — never a committed file, per [BE-112].
• Write a rotation runbook per secret, including steps that avoid downtime. Note that rotating the JWT secret invalidates all live sessions unless a key-id scheme supports overlapping keys.
• Consider supporting a key-id header on JWTs so signing keys can be rotated with a grace period.
• Define a rotation cadence and an incident procedure for suspected exposure.
• Document how contributors obtain development credentials without touching real ones.

Acceptance Criteria

• Every secret is inventoried with its purpose and blast radius.
• A tested rotation runbook exists for each.
• JWT rotation has a documented approach to existing sessions.

Dependencies

Pairs with [BE-112].

Notes for Contributors

Comment below to be assigned.

[iheanyiezumaukom-ai]

@iheanyiezumaukom-ai has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

Hello Maintainer, I'm interested in taking on this issue. I've reviewed the requirements and believe I can deliver within the timeframe.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @iheanyiezumaukom-ai to this issue.

[olamidemutiat300-debug]

@olamidemutiat300-debug has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

Hi, I would like to work on this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @olamidemutiat300-debug to this issue.

[Mkalbani]

@Mkalbani has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

Hi maintainers, can I work on this. I've worked on a similar work. Thank you.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Mkalbani to this issue.

[vincentchimene]

@vincentchimene has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

Hi! I’d like to contribute to #990 – Document a secrets management and rotation procedure. I’m interested in improving the project's security posture by turning secret management into a predictable operational process rather than an emergency response activity.

I can create a comprehensive secrets management guide covering the full lifecycle of backend secrets, including JWT signing keys, database credentials, mail services, OAuth credentials, and Stellar configuration. The documentation will include each secret’s purpose, potential blast radius, approved storage locations per environment, rotation procedures designed to minimise downtime, JWT key rotation strategies, contributor development credential workflows, and incident response steps for suspected exposure.

I’ll ensure the procedure is practical for maintainers and contributors, aligns with existing security practices, and provides clear guidance for safely operating the system across development, CI, and production environments.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @vincentchimene to this issue.

[drips-wave]

Congratulations, @Mkalbani! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on July 30, 2026.

🧑‍💻 @Mkalbani: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊

[drips-wave]

This issue has been completed by @Mkalbani as part of the Stellar Wave Program's 7th Wave 🥳

😎 @Mkalbani: You earned 200 Points for completing this issue! After the current Wave ends, you'll be eligible for a percentage of the Wave's reward pool based on the percentage of total points you've earned. Learn more here. You can also Leave a review to share your experience working on this issue.

🧑‍💻 Repo maintainers: How'd the contributor do? Leave a review to share your experience working with them.