[PM-32608] docs: document licensing system design choices and constraints

[cyprain-okeke]

🎟️ Tracking

Resolves PM-32608 (spike under PM-32220, Organization and User License Refactor Effort).

📔 Objective

PR #6970 documented the "how" of adding a plan-gated organization ability, including the license step. This spike fills the gap it left: the "why" and the constraints the licensing system must operate within.

Adds src/Core/Billing/Licenses/README.md — a design/constraints reference covering:

• The cloud-signs / self-host-verifies-offline model (no phone-home, no revocation) that drives every other constraint.
• The two coexisting license formats — legacy property-based (RSA signature) vs. modern claims-based (JWT) — and which path validation branches into.
• Six load-bearing constraints (C1–C6): backwards/forwards compatibility as the root constraint, field-by-field version-gating of legacy signatures, why CurrentLicenseFileVersion is held one behind the max accepted version, the PM-33980 HasClaim trap for new claims, offline/time-boxed validation with no revocation, and the many coordinated edits a single new field requires.
• Known design tensions captured for the PM-32220 refactor (god-service, reflection-based hashing, property↔claim duplication, divergent date models, #nullable disable).
• A component-reference table mapping each file/symbol to its role and the constraint it serves.

Discoverability: the two docs now cross-link bidirectionally — the how-to's "Self-host licensing" section points to this doc for the rationale, and this doc points back for the step-by-step.

Note on the file move: the OrganizationAbility how-to README added in PR #6970 (previously at src/Core/AdminConsole/OrganizationFeatures/OrganizationAbility/README.md) has been relocated to src/Core/Billing/Licenses/OrganizationAbility-README.md so the "how" and the "why" sit beside each other and beside the licensing code. Verified no remaining references to the old path. Flagging for AdminConsole reviewers since this moves a doc out of their tree.

📸 Screenshots

N/A — documentation only.

[github-actions]

Bitwarden Claude Code Review

Overall Assessment: APPROVE

Documentation-only change adding src/Core/Billing/Licenses/README.md (a design/constraints reference for the licensing system) and relocating the existing OrganizationAbility/README.md next to the licensing code so the "how" and "why" sit together. Spot-checked every load-bearing claim in the new README against the actual code (OrganizationLicense.cs, UserLicense.cs, LicensingService.cs, LicenseExtensions.cs, claims factories) — the cited symbols, version gates (UsersGetPremium ≥ v2, UseScim ≥ v10), HasClaim guard pattern, JWT issuer/audience (bitwarden / organization:{id} / user:{id}), 1-year token lifetime, zero clock skew, BadRequestException masking, certificate file names, +7 days user expiry, and #nullable disable banners all match. The cross-link anchor OrganizationAbility-README.md#8-self-host-licensing resolves correctly, and there are no remaining references to the old src/Core/AdminConsole/OrganizationFeatures/OrganizationAbility/README.md path.

Code Review Details

No findings. The document is well-grounded in code, intentionally avoids restating drift-prone constants (CurrentLicenseFileVersion, ValidLicenseVersion range), and cleanly separates the "why" from the existing how-to.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 61.19%. Comparing base (b5b6ab4) to head (760f735).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #7811      +/-   ##
==========================================
- Coverage   61.20%   61.19%   -0.02%     
==========================================
  Files        2182     2182              
  Lines       97109    97109              
  Branches     8763     8763              
==========================================
- Hits        59432    59421      -11     
- Misses      35564    35575      +11     
  Partials     2113     2113              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.