Skip to content

Commit f382ca5

Browse files
PM-40520 - Move open_org_invite_crypto module doc into README with Mermaid key-protection diagram
Adds a README that renders on GitHub with a Mermaid flowchart showing which key protects what (HighEntropySecret -> CEK -> OpenOrgInvite plaintext), and switches mod.rs to include the README via #![doc = include_str!(...)] so the same content lands in rustdoc. Follows the KM key_hierarchy precedent and the Mermaid-diagram-standard ADR.
1 parent f3eceaf commit f382ca5

2 files changed

Lines changed: 35 additions & 7 deletions

File tree

  • crates/bitwarden-auth/src/registration/open_org_invite_crypto
Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# open_org_invite_crypto
2+
3+
Open-organization-invite registration crossing.
4+
5+
The app seals an open org invite context on registration-start submit and unseals it on the accept
6+
open-org-invite component after a successful registration-finish. This module owns the versioned
7+
plaintext payload (`data_v1`), the domain types and crypto operations (`open_org_invite`), their
8+
wire encoding (`serialization`), and the FFI-facing client methods (`client`).
9+
10+
Two envelopes protect the invite: a fresh CEK encrypts the plaintext, and a fresh 256-bit
11+
`HighEntropySecret` encrypts that CEK. The paired envelopes travel together as
12+
`SealedOpenOrgInviteData`; the `HighEntropySecret` is returned separately to the caller and kept
13+
client-side. Both halves are required to unseal.
14+
15+
## Key-protection diagram
16+
17+
- _Audience:_ engineers touching this module.
18+
- _Intent:_ show which key protects what.
19+
- _Scope:_ the two envelopes composing `SealedOpenOrgInviteData` (excludes app flow, wire encoding,
20+
and FFI).
21+
22+
```mermaid
23+
flowchart LR
24+
HES["HighEntropySecret<br/>(kept client-side)"]
25+
CEK[CEK]
26+
Plain["OpenOrgInvite<br/>{ organization_id, invite_link_code, invite_secret }"]
27+
HES -->|"SecretProtectedKeyEnvelope<br/>(key_envelope)"| CEK
28+
CEK -->|"DataEnvelope<br/>(data_envelope)"| Plain
29+
```
30+
31+
- `HighEntropySecret -> SecretProtectedKeyEnvelope -> CEK` (`key_envelope`): the CEK sealed under a
32+
fresh 32-byte `HighEntropySecret` returned to the caller and kept client-side.
33+
- `CEK -> DataEnvelope -> OpenOrgInvite` (`data_envelope`): the versioned invite plaintext sealed
34+
under the fresh CEK. AES-GCM's auth tag at each layer is the substitution defense.

crates/bitwarden-auth/src/registration/open_org_invite_crypto/mod.rs

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,4 @@
1-
//! Open-organization-invite registration crossing.
2-
//!
3-
//! The app seals an invite context on registration-start submit and unseals it on the accept
4-
//! open-org-invite component after a successful registration-finish. This module owns the
5-
//! versioned plaintext payload (`data_v1`), the domain types and crypto operations
6-
//! (`open_org_invite`), their wire encoding (`serialization`), and the FFI-facing client
7-
//! methods (`client`).
1+
#![doc = include_str!("./README.md")]
82

93
mod client;
104
mod data_v1;

0 commit comments

Comments
 (0)