1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
//! `Sensitive<T>` — a token-redaction newtype (CONTRACT.md §7).
//!
//! Wraps any token-carrying value so that it can never accidentally leak via
//! `Debug`, `Display`, `tracing`, or any other diagnostic sink. The inner
//! value is genuinely private (no `pub` field, no `Deref` impl); the only
//! path to the raw value is [`Sensitive::expose`] — see its doc comment for
//! why it is `pub` (needed by CONTRACT.md §12's `OidcTokenSet`) rather than
//! `pub(crate)`.
use fmt;
/// Wraps a sensitive value (e.g. an access or refresh token) so it can never
/// be printed, logged, or serialized in its raw form.
///
/// This satisfies all four CONTRACT.md §7 rules (as restructured in contract
/// 1.5):
///
/// 1. **Redaction (MUST)** — `Debug` renders `Sensitive(<redacted>)` and
/// `Display` renders `[SENSITIVE]`; `Serialize` is deliberately not
/// implemented, so no serializer can reach the value either.
/// 2. **No implicit reachability (MUST)** — the field is private, and there is
/// no `Deref`, `AsRef`, `From`, or value-comparing `PartialEq`.
/// 3. **One explicit accessor (MAY, RECOMMENDED where §12 ships)** —
/// [`Sensitive::expose`], `pub` because §12's `OidcTokenSet` hands tokens to
/// the calling application, which must be able to read them.
/// 4. **Point-of-use discipline (MUST)** — call `expose()` where the value is
/// actually used, and never pass its result to a log/trace/serialize sink.
;
/// Duplicating the wrapper duplicates the *protection*, not the exposure.
///
/// Written by hand rather than `#[derive(Clone)]` on purpose, so this doc
/// comment sits next to the impl: cloning a `Sensitive<T>` yields another
/// `Sensitive<T>`, whose `Debug`/`Display` still redact (see the impls below
/// and `tests/sensitive_redaction_test.rs`). There is still exactly **one**
/// path to the raw value — [`Sensitive::expose`] — so `Clone` adds no leak
/// path: a caller who can clone could already have called `expose()` on the
/// original. What it *does* enable is CONTRACT.md §9 rule 2 result sharing:
/// the single in-flight `oidc_refresh` has to hand the same `OidcTokenSet`
/// (which is built out of `Sensitive` fields) to every concurrent waiter,
/// and it cannot do that without duplicating the wrapper.
///
/// `Serialize`/`Deserialize` remain deliberately **un**implemented — those
/// *would* be leak paths around the redacting `Debug`/`Display`
/// (RESEARCH.md Pitfall 4).
// Deliberately NOT derived: Serialize, Deserialize.
// A derive of either would create a leak path around the redacting
// Debug/Display impls above (RESEARCH.md Pitfall 4). `Clone` is implemented
// (by hand, above) because duplicating a redacting wrapper cannot leak
// anything — only `expose()` can — and CONTRACT.md §9 rule 2 needs it.
/// Test-only: whether `$t` implements `Debug`, decided at compile time.
///
/// A wire twin — the crate-private struct that carries a [`Sensitive`]
/// field's plaintext to or from the serializer — must not, or one `{:?}`
/// prints the secret (CONTRACT.md §7 rule 1). The probe's inherent constant
/// applies only when the bound holds; otherwise the blanket trait's does.
pub use implements_debug;