Coverage for src / derivepassphrase / _types.py: 100.000%

1# SPDX-FileCopyrightText: 2026 Marco Ricci <software@the13thletter.info> 

2# 

3# SPDX-License-Identifier: Zlib 

4 

5"""Types used by derivepassphrase.""" 

6 

7from __future__ import annotations (empty)

8 

9import enum (empty)

10import json (empty)

11import math (empty)

12import string (empty)

13import warnings (empty)

14from typing import TYPE_CHECKING, Generic, Protocol, TypeVar, cast (empty)

15 

16from typing_extensions import ( (empty)

17 Buffer, 

18 NamedTuple, 

19 NotRequired, 

20 TypeAlias, 

21 TypedDict, 

22 deprecated, 

23 get_overloads, 

24 overload, 

25 runtime_checkable, 

26) 

27 

28if TYPE_CHECKING: (empty)

29 from collections.abc import Callable, Generator, Sequence 

30 from typing import Literal 

31 

32 from typing_extensions import ( 

33 Any, 

34 Required, 

35 TypeIs, 

36 ) 

37 

38__all__ = ( (empty)

39 "SSH_AGENT", 

40 "SSH_AGENTC", 

41 "SSHKeyCommentPair", 

42 "VaultConfig", 

43 "is_vault_config", 

44) 

45 

46 

47class _Omitted: (empty)

48 def __bool__(self) -> bool: (empty)

49 return False 

50 

51 def __repr__(self) -> str: (empty)

52 return "..." 

53 

54 

55class VaultConstructorArgs(TypedDict, total=False): (empty)

56 r"""Common, optional arguments for the vault constructor. 

57 

58 (Also doubles as a base class for the vault configuration global 

59 settings.) 

60 

61 Attributes: 

62 length: 

63 Desired passphrase length. 

64 repeat: 

65 The maximum number of immediate character repetitions 

66 allowed in the passphrase. Disabled if set to 0. 

67 lower: 

68 Optional constraint on ASCII lowercase characters. If 

69 positive, include this many lowercase characters 

70 somewhere in the passphrase. If 0, avoid lowercase 

71 characters altogether. 

72 upper: 

73 Same as `lower`, but for ASCII uppercase characters. 

74 number: 

75 Same as `lower`, but for ASCII digits. 

76 space: 

77 Same as `lower`, but for the space character. 

78 dash: 

79 Same as `lower`, but for the hyphen-minus and underscore 

80 characters. 

81 symbol: 

82 Same as `lower`, but for all other hitherto unlisted 

83 ASCII printable characters (except backquote). 

84 

85 """ 

86 

87 length: NotRequired[int] (empty)

88 """""" (empty)

89 repeat: NotRequired[int] (empty)

90 """""" (empty)

91 lower: NotRequired[int] (empty)

92 """""" (empty)

93 upper: NotRequired[int] (empty)

94 """""" (empty)

95 number: NotRequired[int] (empty)

96 """""" (empty)

97 space: NotRequired[int] (empty)

98 """""" (empty)

99 dash: NotRequired[int] (empty)

100 """""" (empty)

101 symbol: NotRequired[int] (empty)

102 """""" (empty)

103 

104 

105class VaultConfigGlobalSettings(VaultConstructorArgs, total=False): (empty)

106 r"""Configuration for vault: global settings. 

107 

108 Attributes: 

109 key: 

110 The base64-encoded ssh public key to use, overriding the 

111 master passphrase. Optional. 

112 phrase: 

113 The master passphrase. Optional. 

114 unicode_normalization_form: 

115 The preferred Unicode normalization form; we warn the user 

116 if textual passphrases do not match their normalized forms. 

117 Optional, and a `derivepassphrase` extension. 

118 

119 """ 

120 

121 key: NotRequired[str] (empty)

122 """""" (empty)

123 phrase: NotRequired[str] (empty)

124 """""" (empty)

125 unicode_normalization_form: NotRequired[ (empty)

126 Literal["NFC", "NFD", "NFKC", "NFKD"] 

127 ] 

128 """""" (empty)

129 

130 

131class VaultConfigServicesSettings(VaultConfigGlobalSettings, total=False): (empty)

132 r"""Configuration for vault: services settings. 

133 

134 Attributes: 

135 notes: 

136 Optional notes for this service, to display to the user when 

137 generating the passphrase. 

138 key: 

139 As per the global settings. 

140 phrase: 

141 As per the global settings. 

142 unicode_normalization_form: 

143 As per the global settings. 

144 length: 

145 As per the global settings. 

146 repeat: 

147 As per the global settings. 

148 lower: 

149 As per the global settings. 

150 upper: 

151 As per the global settings. 

152 number: 

153 As per the global settings. 

154 space: 

155 As per the global settings. 

156 dash: 

157 As per the global settings. 

158 symbol: 

159 As per the global settings. 

160 

161 """ 

162 

163 notes: NotRequired[str] (empty)

164 """""" (empty)

165 

166 

167_VaultConfig = TypedDict( (empty)

168 "_VaultConfig", 

169 {"global": NotRequired[VaultConfigGlobalSettings]}, 

170 total=False, 

171) 

172 

173 

174class VaultConfig(TypedDict, _VaultConfig, total=False): (empty)

175 r"""Configuration for vault. For typing purposes. 

176 

177 Usually stored as JSON. 

178 

179 Attributes: 

180 global (NotRequired[VaultConfigGlobalSettings]): 

181 Global settings. 

182 services (Required[dict[str, VaultConfigServicesSettings]]): 

183 Service-specific settings. 

184 

185 """ 

186 

187 services: Required[dict[str, VaultConfigServicesSettings]] (empty)

188 

189 

190def json_path(path: Sequence[str | int], /) -> str: (empty)

191 r"""Transform a series of keys and indices into a JSONPath selector. 

192 

193 The resulting JSONPath selector conforms to RFC 9535, is always 

194 rooted at the JSON root node (i.e., starts with `$`), and only 

195 contains name and index selectors (in shorthand dot notation, where 

196 possible). 

197 

198 Args: 

199 path: 

200 A sequence of object keys or array indices to navigate to 

201 the desired JSON value, starting from the root node. 

202 

203 Returns: 

204 A valid JSONPath selector (a string) identifying the desired 

205 JSON value. 

206 

207 Examples: 

208 >>> json_path(["global", "phrase"]) 

209 '$.global.phrase' 

210 >>> json_path(["services", "service name with spaces", "length"]) 

211 '$.services["service name with spaces"].length' 

212 >>> json_path(["services", "special\u000acharacters", "notes"]) 

213 '$.services["special\\ncharacters"].notes' 

214 >>> print(json_path(["services", "special\u000acharacters", "notes"])) 

215 $.services["special\ncharacters"].notes 

216 >>> json_path(["custom_array", 2, 0]) 

217 '$.custom_array[2][0]' 

218 

219 """ 

220 

221 def needs_longhand(x: str | int) -> bool: 66 ctx1ampkqTrUvVW'XBCDEOlsjnoYZt0FGH1IJ2Khg3456LM789!#$deNPwQRxySzuAicfb

222 initial = ( 66 ctx1ampkqTrUvVW'XBCDEOlsjnoYZt0FGH1IJ2Khg3456LM789!#$deNPwQRxySzuAicfb

223 frozenset(string.ascii_lowercase) 

224 | frozenset(string.ascii_uppercase) 

225 | frozenset("_") 

226 ) 

227 chars = initial | frozenset(string.digits) 66 ctx1ampkqTrUvVW'XBCDEOlsjnoYZt0FGH1IJ2Khg3456LM789!#$deNPwQRxySzuAicfb

228 return not ( 66 ctx1ampkqTrUvVW'XBCDEOlsjnoYZt0FGH1IJ2Khg3456LM789!#$deNPwQRxySzuAicfb

229 isinstance(x, str) 

230 and x 

231 and set(x).issubset(chars) 

232 and x[:1] in initial 

233 ) 

234 

235 chunks = ["$"] 66 ctx1ampkqTrUvVW'XBCDEOlsjnoYZt0FGH1IJ2Khg3456LM789!#$deNPwQRxySzuAicfb

236 chunks.extend( 66 ctx1ampkqTrUvVW'XBCDEOlsjnoYZt0FGH1IJ2Khg3456LM789!#$deNPwQRxySzuAicfb

237 f"[{json.dumps(x)}]" if needs_longhand(x) else f".{x}" for x in path 

238 ) 

239 return "".join(chunks) 66 ctx1ampkqTrUvVW'XBCDEOlsjnoYZt0FGH1IJ2Khg3456LM789!#$deNPwQRxySzuAicfb

240 

241 

242class _VaultConfigValidator: (empty)

243 INVALID_CONFIG_ERROR = "vault config is invalid" (empty)

244 

245 def __init__(self, maybe_config: Any) -> None: # noqa: ANN401 (empty)

246 self.maybe_config = maybe_config 72 ctx1ampk*qTrUvVW'XBCDE,OlsjnoYZt0FGH1IJ2K-+h(g3456LM789!#$deNPwQRxyS.zuAicfb

247 

248 def traverse_path(self, path: tuple[str, ...]) -> Any: # noqa: ANN401 (empty)

249 obj = self.maybe_config 19 ctx1ampkqrlsjnohgdeicfb

250 for key in path: 19 ctx1ampkqrlsjnohgdeicfb

251 obj = obj[key] 19 ctx1ampkqrlsjnohgdeicfb

252 return obj 19 ctx1ampkqrlsjnohgdeicfb

253 

254 def walk_subconfigs( (empty)

255 self, 

256 ) -> Generator[tuple[tuple[str] | tuple[str, str], str, Any], None, None]: 

257 obj = cast("dict[str, dict[str, Any]]", self.maybe_config) 67 ctx1ampk*qTrUvVWXBCDEOlsjnoYZt0FGH1IJ2K+hg3456LM789!#$deNPwQRxySzuAicfb

258 if isinstance(obj.get("global", False), dict): 67 ctx1ampk*qTrUvVWXBCDEOlsjnoYZt0FGH1IJ2K+hg3456LM789!#$deNPwQRxySzuAicfb

259 for k, v in list(obj["global"].items()): 51 ctx1amkvBCDEOlsotFGH1IJKhg3456LM789!#$deNPwQRxySzuAicfb

260 yield ("global",), k, v 51 ctx1amkvBCDEOlsotFGH1IJKhg3456LM789!#$deNPwQRxySzuAicfb

261 for sv_name, sv_obj in list(obj["services"].items()): 67 ctx1ampk*qTrUvVWXBCDEOlsjnoYZt0FGH1IJ2K+hg3456LM789!#$deNPwQRxySzuAicfb

262 for k, v in list(sv_obj.items()): 53 ctx1ampkqTrUvVWXBCDEOjnoYZt0FGH1IJ2KhgLMdeNPwQRxySzuAicfb

263 yield ("services", sv_name), k, v 53 ctx1ampkqTrUvVWXBCDEOjnoYZt0FGH1IJ2KhgLMdeNPwQRxySzuAicfb

264 

265 def validate( # noqa: C901,PLR0912 (empty)

266 self, 

267 *, 

268 allow_unknown_settings: bool = False, 

269 ) -> None: 

270 err_obj_not_a_dict = "vault config is not a dict" 72 ctx1ampk*qTrUvVW'XBCDE,OlsjnoYZt0FGH1IJ2K-+h(g3456LM789!#$deNPwQRxyS.zuAicfb

271 err_non_str_service_name = ( 72 ctx1ampk*qTrUvVW'XBCDE,OlsjnoYZt0FGH1IJ2K-+h(g3456LM789!#$deNPwQRxyS.zuAicfb

272 "vault config contains non-string service name {sv_name!r}" 

273 ) 

274 err_not_a_dict = "vault config entry {json_path_str} is not a dict" 72 ctx1ampk*qTrUvVW'XBCDE,OlsjnoYZt0FGH1IJ2K-+h(g3456LM789!#$deNPwQRxyS.zuAicfb

275 err_not_a_string = "vault config entry {json_path_str} is not a string" 72 ctx1ampk*qTrUvVW'XBCDE,OlsjnoYZt0FGH1IJ2K-+h(g3456LM789!#$deNPwQRxyS.zuAicfb

276 err_not_an_int = "vault config entry {json_path_str} is not an integer" 72 ctx1ampk*qTrUvVW'XBCDE,OlsjnoYZt0FGH1IJ2K-+h(g3456LM789!#$deNPwQRxyS.zuAicfb

277 err_unknown_setting = ( 72 ctx1ampk*qTrUvVW'XBCDE,OlsjnoYZt0FGH1IJ2K-+h(g3456LM789!#$deNPwQRxyS.zuAicfb

278 "vault config entry {json_path_str} uses unknown setting {key!r}" 

279 ) 

280 err_bad_number0 = "vault config entry {json_path_str} is negative" 72 ctx1ampk*qTrUvVW'XBCDE,OlsjnoYZt0FGH1IJ2K-+h(g3456LM789!#$deNPwQRxyS.zuAicfb

281 err_bad_number1 = "vault config entry {json_path_str} is not positive" 72 ctx1ampk*qTrUvVW'XBCDE,OlsjnoYZt0FGH1IJ2K-+h(g3456LM789!#$deNPwQRxyS.zuAicfb

282 

283 kwargs: dict[str, Any] = { 72 ctx1ampk*qTrUvVW'XBCDE,OlsjnoYZt0FGH1IJ2K-+h(g3456LM789!#$deNPwQRxyS.zuAicfb

284 "allow_unknown_settings": allow_unknown_settings, 

285 } 

286 if not isinstance(self.maybe_config, dict): 72 ctx1ampk*qTrUvVW'XBCDE,OlsjnoYZt0FGH1IJ2K-+h(g3456LM789!#$deNPwQRxyS.zuAicfb

287 raise TypeError(err_obj_not_a_dict.format(**kwargs)) 5 ctx1,-(.c

288 if "global" in self.maybe_config: 68 ctx1ampk*qTrUvVW'XBCDEOlsjnoYZt0FGH1IJ2K+hg3456LM789!#$deNPwQRxySzuAicfb

289 o_global = self.maybe_config["global"] 52 ctx1amkv'BCDEOlsotFGH1IJKhg3456LM789!#$deNPwQRxySzuAicfb

290 if not isinstance(o_global, dict): 52 ctx1amkv'BCDEOlsotFGH1IJKhg3456LM789!#$deNPwQRxySzuAicfb

291 kwargs["json_path_str"] = json_path(["global"]) 2 ctx1'c

292 raise TypeError(err_not_a_dict.format(**kwargs)) 2 ctx1'c

293 if not isinstance(self.maybe_config.get("services"), dict): 68 ctx1ampk*qTrUvVW'XBCDEOlsjnoYZt0FGH1IJ2K+hg3456LM789!#$deNPwQRxySzuAicfb

294 kwargs["json_path_str"] = json_path(["services"]) 2 ctx1'c

295 raise TypeError(err_not_a_dict.format(**kwargs)) 2 ctx1'c

296 for sv_name, service in self.maybe_config["services"].items(): 67 ctx1ampk*qTrUvVWXBCDEOlsjnoYZt0FGH1IJ2K+hg3456LM789!#$deNPwQRxySzuAicfb

297 if not isinstance(sv_name, str): 53 ctx1ampkqTrUvVWXBCDEOjnoYZt0FGH1IJ2KhgLMdeNPwQRxySzuAicfb

298 kwargs["sv_name"] = sv_name 2 ctx1cb

299 raise TypeError(err_non_str_service_name.format(**kwargs)) 2 ctx1cb

300 if not isinstance(service, dict): 53 ctx1ampkqTrUvVWXBCDEOjnoYZt0FGH1IJ2KhgLMdeNPwQRxySzuAicfb

301 kwargs["json_path_str"] = json_path(["services", sv_name]) 1 ctx1c

302 raise TypeError(err_not_a_dict.format(**kwargs)) 1 ctx1c

303 for path, key, value in self.walk_subconfigs(): 67 ctx1ampk*qTrUvVWXBCDEOlsjnoYZt0FGH1IJ2K+hg3456LM789!#$deNPwQRxySzuAicfb

304 kwargs["path"] = path 65 ctx1ampkqTrUvVWXBCDEOlsjnoYZt0FGH1IJ2Khg3456LM789!#$deNPwQRxySzuAicfb

305 kwargs["key"] = key 65 ctx1ampkqTrUvVWXBCDEOlsjnoYZt0FGH1IJ2Khg3456LM789!#$deNPwQRxySzuAicfb

306 kwargs["value"] = value 65 ctx1ampkqTrUvVWXBCDEOlsjnoYZt0FGH1IJ2Khg3456LM789!#$deNPwQRxySzuAicfb

307 kwargs["json_path_str"] = json_path([*path, key]) 65 ctx1ampkqTrUvVWXBCDEOlsjnoYZt0FGH1IJ2Khg3456LM789!#$deNPwQRxySzuAicfb

308 # TODO(the-13th-letter): Rewrite using structural pattern 

309 # matching. 

310 # https://the13thletter.info/derivepassphrase/latest/pycompatibility/#after-eol-py3.9 

311 if key in {"key", "phrase"}: 65 ctx1ampkqTrUvVWXBCDEOlsjnoYZt0FGH1IJ2Khg3456LM789!#$deNPwQRxySzuAicfb

312 if not isinstance(value, str): 51 ctx1pkvBCDEOlsjntFGH1IJKhg3456LM789!#$deNPwQRxySzuAicfb

313 raise TypeError(err_not_a_string.format(**kwargs)) 2 ctx1cb

314 elif key == "unicode_normalization_form" and path == ("global",): 52 ctx1ampkqTrUvVWXBCDEOljnoYZ0FGHIJ2KhgLMdeNPwQRxySzuAicfb

315 if not isinstance(value, str): 8 ctx1hgdeicfb

316 raise TypeError(err_not_a_string.format(**kwargs)) 2 ctx1cb

317 if not allow_unknown_settings: 8 ctx1hgdeicfb

318 raise ValueError(err_unknown_setting.format(**kwargs)) 2 ctx1cb

319 elif key == "notes" and path != ("global",): 52 ctx1ampkqTrUvVWXBCDEOljnoYZ0FGHIJ2KhgLMdeNPwQRxySzuAicfb

320 if not isinstance(value, str): 22 ctx1vOjnhgdePwQRxySzuAicfb

321 raise TypeError(err_not_a_string.format(**kwargs)) 2 ctx1cb

322 elif key in { 46 ctx1ampkqTrUvVWXBCDEljoYZ0FGHIJ2KhgLMdeNwxyzuAicfb

323 "length", 

324 "repeat", 

325 "lower", 

326 "upper", 

327 "number", 

328 "space", 

329 "dash", 

330 "symbol", 

331 }: 

332 if not isinstance(value, int): 46 ctx1ampkqTrUvVWXBCDEljoYZ0FGHIJ2KhgLMdeNwxyzuAicfb

333 raise TypeError(err_not_an_int.format(**kwargs)) 2 ctx1cb

334 if key == "length" and value < 1: 46 ctx1ampkqTrUvVWXBCDEljoYZ0FGHIJ2KhgLMdeNwxyzuAicfb

335 raise ValueError(err_bad_number1.format(**kwargs)) 2 ctx1cb

336 if key != "length" and value < 0: 46 ctx1ampkqTrUvVWXBCDEljoYZ0FGHIJ2KhgLMdeNwxyzuAicfb

337 raise ValueError(err_bad_number0.format(**kwargs)) 2 ctx1cb

338 elif not allow_unknown_settings: 8 ctx1hgdeicfb

339 raise ValueError(err_unknown_setting.format(**kwargs)) 2 ctx1cb

340 

341 def clean_up_falsy_values(self) -> Generator[CleanupStep, None, None]: # noqa: C901 (empty)

342 obj = self.maybe_config 21 ctx1ampkqrlsjnoth(gdeicfb

343 if ( 21 ctx1ampkqrlsjnoth(gdeicfb

344 not isinstance(obj, dict) 

345 or "services" not in obj 

346 or not isinstance(obj["services"], dict) 

347 ): 

348 raise ValueError( 2 ctx1(c

349 self.INVALID_CONFIG_ERROR 

350 ) # pragma: no cover [failsafe] 

351 if "global" in obj and not isinstance(obj["global"], dict): 20 ctx1ampkqrlsjnothgdeicfb

352 raise ValueError( 1 ctx1c

353 self.INVALID_CONFIG_ERROR 

354 ) # pragma: no cover [failsafe] 

355 if not all( 20 ctx1ampkqrlsjnothgdeicfb

356 isinstance(service_obj, dict) 

357 for service_obj in obj["services"].values() 

358 ): 

359 raise ValueError( 1 ctx1c

360 self.INVALID_CONFIG_ERROR 

361 ) # pragma: no cover [failsafe] 

362 

363 def falsy(value: Any) -> bool: # noqa: ANN401 20 ctx1ampkqrlsjnothgdeicfb

364 return not js_truthiness(value) 19 ctx1ampkqrlsjnohgdeicfb

365 

366 def falsy_but_not_zero(value: Any) -> bool: # noqa: ANN401 20 ctx1ampkqrlsjnothgdeicfb

367 return not js_truthiness(value) and not ( 14 ctx1ampkljhgdeicfb

368 isinstance(value, int) and value == 0 

369 ) 

370 

371 def falsy_but_not_string(value: Any) -> bool: # noqa: ANN401 20 ctx1ampkqrlsjnothgdeicfb

372 return not js_truthiness(value) and value != "" # noqa: PLC1901 14 ctx1pklsjnhgdeicfb

373 

374 for path, key, value in self.walk_subconfigs(): 20 ctx1ampkqrlsjnothgdeicfb

375 service_obj = self.traverse_path(path) 19 ctx1ampkqrlsjnohgdeicfb

376 # TODO(the-13th-letter): Rewrite using structural pattern 

377 # matching. 

378 # https://the13thletter.info/derivepassphrase/latest/pycompatibility/#after-eol-py3.9 

379 if key == "phrase" and falsy_but_not_string(value): 19 ctx1ampkqrlsjnohgdeicfb

380 yield CleanupStep( 4 ctx1defb

381 (*path, key), service_obj[key], "replace", "" 

382 ) 

383 service_obj[key] = "" 4 ctx1defb

384 elif key == "notes" and falsy(value): 19 ctx1ampkqrlsjnohgdeicfb

385 yield CleanupStep( 6 ctx1jndefb

386 (*path, key), service_obj[key], "remove", None 

387 ) 

388 service_obj.pop(key) 6 ctx1jndefb

389 elif key == "key" and falsy(value): 19 ctx1ampkqrlsjnohgdeicfb

390 if path == ("global",): 8 ctx1lsjndefb

391 yield CleanupStep( 6 ctx1lsdefb

392 (*path, key), service_obj[key], "remove", None 

393 ) 

394 service_obj.pop(key) 6 ctx1lsdefb

395 else: 

396 yield CleanupStep( 6 ctx1jndefb

397 (*path, key), service_obj[key], "replace", "" 

398 ) 

399 service_obj[key] = "" 6 ctx1jndefb

400 elif key == "length" and falsy(value): 19 ctx1ampkqrlsjnohgdeicfb

401 yield CleanupStep( 4 ctx1defb

402 (*path, key), service_obj[key], "replace", 20 

403 ) 

404 service_obj[key] = 20 4 ctx1defb

405 elif key == "repeat" and falsy_but_not_zero(value): 19 ctx1ampkqrlsjnohgdeicfb

406 yield CleanupStep((*path, key), service_obj[key], "replace", 0) 4 ctx1defb

407 service_obj[key] = 0 4 ctx1defb

408 elif key in { 19 ctx1ampkqrlsjnohgdeicfb

409 "lower", 

410 "upper", 

411 "number", 

412 "space", 

413 "dash", 

414 "symbol", 

415 } and falsy_but_not_zero(value): 

416 yield CleanupStep( 4 ctx1defb

417 (*path, key), service_obj[key], "remove", None 

418 ) 

419 service_obj.pop(key) 4 ctx1defb

420 

421 

422@overload (empty)

423@deprecated( (empty)

424 "allow_derivepassphrase_extensions argument is deprecated since v0.4.0, " (empty)

425 "to be removed in v1.0: no extensions are defined" 

426) 

427def validate_vault_config( (empty)

428 obj: Any, # noqa: ANN401 (empty)

429 /, 

430 *, 

431 allow_derivepassphrase_extensions: bool, (empty)

432 allow_unknown_settings: bool = False, (empty)

433) -> None: ... (empty)

434 

435 

436@overload (empty)

437def validate_vault_config( (empty)

438 obj: Any, # noqa: ANN401 (empty)

439 /, 

440 *, 

441 allow_unknown_settings: bool = False, (empty)

442) -> None: ... (empty)

443 

444 

445def validate_vault_config( (empty)

446 obj: Any, 

447 /, 

448 *, 

449 allow_unknown_settings: bool = False, 

450 allow_derivepassphrase_extensions: bool = _Omitted(), # type: ignore[assignment] 

451) -> None: 

452 """Check that `obj` is a valid vault config. 

453 

454 Args: 

455 obj: 

456 The object to test. 

457 allow_unknown_settings: 

458 If false, abort on unknown settings. 

459 allow_derivepassphrase_extensions: 

460 (Deprecated.) Ignored since v0.4.0. 

461 

462 Raises: 

463 TypeError: 

464 An entry in the vault config, or the vault config itself, 

465 has the wrong type. 

466 ValueError: 

467 An entry in the vault config is not allowed, or has a 

468 disallowed value. 

469 

470 Warning: Deprecated argument 

471 **v0.4.0**: 

472 The `allow_derivepassphrase_extensions` keyword argument is 

473 deprecated, and will be removed in v1.0. There are no 

474 specified `derivepassphrase` extensions. 

475 

476 """ 

477 # TODO(the-13th-letter): Remove this block in v1.0. 

478 # https://the13thletter.info/derivepassphrase/latest/upgrade-notes/#v1.0-allow-derivepassphrase-extensions 

479 # TODO(the-13th-letter): Add tests that trigger the deprecation warning, 

480 # then include this in coverage. 

481 if not isinstance( 72 ctx1ampk*qTrUvVW'XBCDE,OlsjnoYZt0FGH1IJ2K-+h(g3456LM789!#$deNPwQRxyS.zuAicfb

482 allow_derivepassphrase_extensions, _Omitted 

483 ): # pragma: no cover [unused] 

484 warnings.warn( 

485 get_overloads(validate_vault_config)[0].__deprecated__, # type: ignore[attr-defined] 

486 DeprecationWarning, 

487 stacklevel=2, 

488 ) 

489 

490 return _VaultConfigValidator(obj).validate( 72 ctx1ampk*qTrUvVW'XBCDE,OlsjnoYZt0FGH1IJ2K-+h(g3456LM789!#$deNPwQRxyS.zuAicfb

491 allow_unknown_settings=allow_unknown_settings 

492 ) 

493 

494 

495def is_vault_config(obj: Any) -> TypeIs[VaultConfig]: # noqa: ANN401 (empty)

496 """Check if `obj` is a valid vault config, according to typing. 

497 

498 Args: 

499 obj: The object to test. 

500 

501 Returns: 

502 True if this is a vault config, false otherwise. 

503 

504 """ # noqa: DOC501 

505 try: 70 ctx1ampk*qTrUvVW'XBCDE,OlsjnoYZt0FGH1IJ2K-+h(g3456LM789!#$deNPwQRxyS.zuAif

506 validate_vault_config( 70 ctx1ampk*qTrUvVW'XBCDE,OlsjnoYZt0FGH1IJ2K-+h(g3456LM789!#$deNPwQRxyS.zuAif

507 obj, 

508 allow_unknown_settings=True, 

509 ) 

510 except (TypeError, ValueError) as exc: 5 ctx1',-(.

511 if "vault config " not in str(exc): # pragma: no cover [failsafe] 5 ctx1',-(.

512 raise 

513 return False 5 ctx1',-(.

514 return True 65 ctx1ampk*qTrUvVWXBCDEOlsjnoYZt0FGH1IJ2K+hg3456LM789!#$deNPwQRxySzuAif

515 

516 

517def js_truthiness(value: Any, /) -> bool: # noqa: ANN401 (empty)

518 """Return the truthiness of the value, according to JavaScript/ECMAScript. 

519 

520 Like Python, ECMAScript considers certain values to be false in 

521 a boolean context, and every other value to be true. These 

522 considerations do not agree: ECMAScript considers [`math.nan`][] to 

523 be false too, and empty arrays and objects/dicts to be true, 

524 contrary to Python. Because of these discrepancies, we cannot defer 

525 to [`bool`][] for ECMAScript truthiness checking, and need 

526 a separate, explicit predicate. 

527 

528 (Some falsy values in ECMAScript aren't defined in Python: 

529 `undefined`, and `document.all`. We do not implement support for 

530 those.) 

531 

532 !!! note 

533 

534 We cannot use a simple `value not in falsy_values` check, 

535 because [`math.nan`][] behaves in annoying and obstructive ways. 

536 In general, `float('NaN') == float('NaN')` is false, and 

537 `float('NaN') != math.nan` and `math.nan != math.nan` are true. 

538 CPython says `float('NaN') in [math.nan]` is false, PyPy3 says 

539 it is true. Seemingly the only reliable and portable way to 

540 check for [`math.nan`][] is to use [`math.isnan`][] directly. 

541 

542 Args: 

543 value: The value to test. 

544 

545 """ # noqa: RUF002 

546 try: 22 ctx1a:mpkqrlsjnothgdeicfb;

547 if value in {None, False, 0, 0.0, ""}: # noqa: B033 22 ctx1a:mpkqrlsjnothgdeicfb;

548 return False 17 ctx1a:mkqrlsjnotgdefb

549 except TypeError: 3 ctx1:cb

550 # All falsy values are hashable, so this can't be falsy. 

551 return True 3 ctx1:cb

552 return not (isinstance(value, float) and math.isnan(value)) 21 ctx1a:mpkqrlsjnohgdeicfb;

553 

554 

555class CleanupStep(NamedTuple): (empty)

556 """A single executed step during vault config cleanup. 

557 

558 Attributes: 

559 path: 

560 A sequence of object keys or array indices to navigate to 

561 the JSON value that was cleaned up. 

562 old_value: 

563 The old value. 

564 action: 

565 Either `'replace'` if `old_value` was replaced with 

566 `new_value`, or `'remove'` if `old_value` was removed. 

567 new_value: 

568 The new value. 

569 

570 """ 

571 

572 path: Sequence[str | int] (empty)

573 """""" (empty)

574 old_value: Any (empty)

575 """""" (empty)

576 action: Literal["replace", "remove"] (empty)

577 """""" (empty)

578 new_value: Any (empty)

579 """""" (empty)

580 

581 

582def clean_up_falsy_vault_config_values( (empty)

583 obj: Any, # noqa: ANN401 

584) -> Sequence[CleanupStep] | None: 

585 """Convert falsy values in a vault config to correct types, in-place. 

586 

587 Needed for compatibility with vault(1), which sometimes uses only 

588 truthiness checks. 

589 

590 If vault(1) considered `obj` to be valid, then after clean up, 

591 `obj` will be valid as per [`validate_vault_config`][]. 

592 

593 Args: 

594 obj: 

595 A presumed valid vault configuration save for using falsy 

596 values of the wrong type. 

597 

598 Returns: 

599 A list of 4-tuples `(key_tup, old_value, action, new_value)`, 

600 indicating the cleanup actions performed. `key_tup` is 

601 a sequence of object keys and/or array indices indicating the 

602 JSON path to the leaf value that was cleaned up, `old_value` is 

603 the old value, `new_value` is the new value, and `action` is 

604 either `replace` (`old_value` was replaced with `new_value`) or 

605 `remove` (`old_value` was removed, and `new_value` is 

606 meaningless). 

607 

608 If cleanup was never attempted because of an obviously invalid 

609 vault configuration, then `None` is returned, directly. 

610 

611 """ 

612 try: 21 ctx1ampkqrlsjnoth(gdeicfb

613 return list(_VaultConfigValidator(obj).clean_up_falsy_values()) 21 ctx1ampkqrlsjnoth(gdeicfb

614 except ValueError: 2 ctx1(c

615 return None 2 ctx1(c

616 

617 

618# TODO(the-13th-letter): Use type variables local to each class. 

619# https://the13thletter.info/derivepassphrase/latest/pycompatibility/#after-eol-py3.11 

620T_Buffer = TypeVar("T_Buffer", bound=Buffer) (empty)

621""" (empty)

622A [`TypeVar`][] for classes implementing the [`Buffer`][] interface. 

623 

624Warning: 

625 Non-public attribute, provided for didactical and educational 

626 purposes only. Subject to change without notice, including 

627 removal. 

628 

629""" 

630 

631 

632class SSHKeyCommentPair(NamedTuple, Generic[T_Buffer]): (empty)

633 """SSH key plus comment pair. For typing purposes. 

634 

635 Attributes: 

636 key: SSH key. 

637 comment: SSH key comment. 

638 

639 """ 

640 

641 key: T_Buffer (empty)

642 """""" (empty)

643 comment: T_Buffer (empty)

644 """""" (empty)

645 

646 def toreadonly(self) -> SSHKeyCommentPair[bytes]: (empty)

647 """Return a copy with read-only entries.""" 

648 return SSHKeyCommentPair( 1 ctx1^

649 key=bytes(self.key), 

650 comment=bytes(self.comment), 

651 ) 

652 

653 

654class SSH_AGENTC(int, enum.Enum): # noqa: N801 (empty)

655 """SSH agent protocol numbers: client requests. 

656 

657 Attributes: 

658 REQUEST_IDENTITIES (int): 

659 List identities. Expecting 

660 [`SSH_AGENT.IDENTITIES_ANSWER`][]. 

661 SIGN_REQUEST (int): 

662 Sign data. Expecting [`SSH_AGENT.SIGN_RESPONSE`][]. 

663 ADD_IDENTITY (int): 

664 Add an (SSH2) identity. 

665 REMOVE_IDENTITY (int): 

666 Remove an (SSH2) identity. 

667 ADD_ID_CONSTRAINED (int): 

668 Add an (SSH2) identity, including key constraints. 

669 EXTENSION (int): 

670 Issue a named request that isn't part of the core agent 

671 protocol. Expecting [`SSH_AGENT.EXTENSION_RESPONSE`][] or 

672 [`SSH_AGENT.EXTENSION_FAILURE`][] if the named request is 

673 supported, [`SSH_AGENT.FAILURE`][] otherwise. 

674 

675 """ 

676 

677 REQUEST_IDENTITIES = 11 (empty)

678 """""" (empty)

679 SIGN_REQUEST = 13 (empty)

680 """""" (empty)

681 ADD_IDENTITY = 17 (empty)

682 """""" (empty)

683 REMOVE_IDENTITY = 18 (empty)

684 """""" (empty)

685 ADD_ID_CONSTRAINED = 25 (empty)

686 """""" (empty)

687 EXTENSION = 27 (empty)

688 """""" (empty)

689 

690 def __bytes__(self) -> bytes: # pragma: no cover [unused] (empty)

691 """Return the corresponding request code.""" 

692 return int.to_bytes(self, 1, "big", signed=False) 

693 

694 

695class SSH_AGENT(int, enum.Enum): # noqa: N801 (empty)

696 """SSH agent protocol numbers: server replies. 

697 

698 Attributes: 

699 FAILURE (int): 

700 Generic failure code. 

701 SUCCESS (int): 

702 Generic success code. 

703 IDENTITIES_ANSWER (int): 

704 Successful answer to [`SSH_AGENTC.REQUEST_IDENTITIES`][]. 

705 SIGN_RESPONSE (int): 

706 Successful answer to [`SSH_AGENTC.SIGN_REQUEST`][]. 

707 EXTENSION_FAILURE (int): 

708 Unsuccessful answer to [`SSH_AGENTC.EXTENSION`][]. 

709 EXTENSION_RESPONSE (int): 

710 Successful answer to [`SSH_AGENTC.EXTENSION`][]. 

711 

712 """ 

713 

714 FAILURE = 5 (empty)

715 """""" (empty)

716 SUCCESS = 6 (empty)

717 """""" (empty)

718 IDENTITIES_ANSWER = 12 (empty)

719 """""" (empty)

720 SIGN_RESPONSE = 14 (empty)

721 """""" (empty)

722 EXTENSION_FAILURE = 28 (empty)

723 """""" (empty)

724 EXTENSION_RESPONSE = 29 (empty)

725 """""" (empty)

726 

727 def __bytes__(self) -> bytes: # pragma: no cover [unused] (empty)

728 """Return the corresponding response code.""" 

729 return int.to_bytes(self, 1, "big", signed=False) 7 ctx1a_`{|1}

730 

731 

732class StoreroomKeyPair(NamedTuple, Generic[T_Buffer]): (empty)

733 """A pair of AES256 keys, one for encryption and one for signing. 

734 

735 Attributes: 

736 encryption_key: 

737 AES256 key, used for encryption with AES256-CBC (with PKCS#7 

738 padding). 

739 signing_key: 

740 AES256 key, used for signing with HMAC-SHA256. 

741 

742 """ 

743 

744 encryption_key: T_Buffer (empty)

745 """""" (empty)

746 signing_key: T_Buffer (empty)

747 """""" (empty)

748 

749 def toreadonly(self) -> StoreroomKeyPair[bytes]: (empty)

750 """Return a copy with read-only entries.""" 

751 return StoreroomKeyPair( 5 ctx1u=?@[

752 encryption_key=bytes(self.encryption_key), 

753 signing_key=bytes(self.signing_key), 

754 ) 

755 

756 

757class StoreroomMasterKeys(NamedTuple, Generic[T_Buffer]): (empty)

758 """A triple of AES256 keys, for encryption, signing and hashing. 

759 

760 Attributes: 

761 hashing_key: 

762 AES256 key, used for hashing with HMAC-SHA256 to derive 

763 a hash table slot for an item. 

764 encryption_key: 

765 AES256 key, used for encryption with AES256-CBC (with PKCS#7 

766 padding). 

767 signing_key: 

768 AES256 key, used for signing with HMAC-SHA256. 

769 

770 """ 

771 

772 hashing_key: T_Buffer (empty)

773 """""" (empty)

774 encryption_key: T_Buffer (empty)

775 """""" (empty)

776 signing_key: T_Buffer (empty)

777 """""" (empty)

778 

779 def toreadonly(self) -> StoreroomMasterKeys[bytes]: (empty)

780 """Return a copy with read-only entries.""" 

781 return StoreroomMasterKeys( 7 ctx2u ~ ab= ? @ [

782 hashing_key=bytes(self.hashing_key), 

783 encryption_key=bytes(self.encryption_key), 

784 signing_key=bytes(self.signing_key), 

785 ) 

786 

787 

788class FeatureTestEnum(Protocol): (empty)

789 """An [`enum.Enum`][] subclass supporting feature tests. (empty)

790 

791 Each value of the enum supports the `test` method, which tests 

792 whether the feature is enabled or not. (The specific test function 

793 may in general require arguments to actually execute the test, 

794 though no function currently does.) 

795 

796 """ 

797 

798 def test(self, *args: Any, **kwargs: Any) -> bool: ... # noqa: ANN401 (empty)

799 

800 

801def _feature_test_function(f: Callable[..., bool]) -> Callable[..., bool]: (empty)

802 """Mark a function as a feature test function. 

803 

804 This decorator exists purely to hold some shared commentary. 

805 

806 Test functions may accept arbitrary arguments, dependent on which 

807 feature they test for. They should make sure to raise no 

808 exceptions. They may use delayed imports to avoid the import cost 

809 until it is actually warranted. 

810 

811 Returns: 

812 The callable. 

813 

814 """ 

815 return f (empty)

816 

817 

818class PEP508Extra(str, enum.Enum): (empty)

819 """PEP 508 extras supported by `derivepassphrase`. 

820 

821 Attributes: 

822 EXPORT: 

823 The necessary dependencies to allow the `export` subcommand 

824 to handle as many foreign configuration formats as possible. 

825 

826 """ 

827 

828 EXPORT = "export" (empty)

829 """""" (empty)

830 

831 @_feature_test_function (empty)

832 @staticmethod (empty)

833 def _test_export() -> bool: (empty)

834 """Return true if [`PEP508Extra.EXPORT`][] is currently supported.""" 

835 import importlib.util # noqa: PLC0415 2 ctx1%/

836 

837 return importlib.util.find_spec("cryptography") is not None 2 ctx1%/

838 

839 def test(self, *_args: Any, **_kwargs: Any) -> bool: # noqa: ANN401 (empty)

840 """Return true if this extra is enabled.""" 

841 if self == PEP508Extra.EXPORT: 2 ctx1%/

842 return self._test_export() 2 ctx1%/

843 return False # pragma: no cover [unused] 

844 

845 __str__ = str.__str__ (empty)

846 __format__ = str.__format__ # type: ignore[assignment] (empty)

847 

848 

849class Feature(str, enum.Enum): (empty)

850 """Optional features supported by `derivepassphrase`. 

851 

852 Attributes: 

853 SSH_KEY: 

854 The `vault` subcommand supports using a master SSH key, 

855 instead of a master passphrase, if an SSH agent is running 

856 and the master SSH key is loaded into it. 

857 

858 This feature requires Python support for the SSH agent's 

859 chosen communication channel technology. 

860 

861 """ 

862 

863 SSH_KEY = "master SSH key" (empty)

864 """""" (empty)

865 

866 @_feature_test_function (empty)

867 @staticmethod (empty)

868 def _test_ssh_key() -> bool: # pragma: no cover [external] (empty)

869 """Return true if [`_types.Feature.SSH_KEY`][] is currently supported. 

870 

871 We test this by attempting to construct an SSH agent client, 

872 reporting whether this can principally work, or not. 

873 

874 """ 

875 # Because BuiltinSSHAgentSocketProvider.test tests the same 

876 # thing, just specific to a certain socket provider, we delegate 

877 # to that test... not only out of laziness, but also out of 

878 # consistency, avoiding two reimplementations of the same logic. 

879 from derivepassphrase import ssh_agent # noqa: PLC0415 2 ctx1%)

880 

881 for provider_name in ssh_agent.SSHAgentClient.SOCKET_PROVIDERS: 2 ctx1%)

882 try: 2 ctx1%)

883 provider = BuiltinSSHAgentSocketProvider(provider_name) 2 ctx1%)

884 except ValueError: 

885 continue 

886 else: 

887 if provider.test(): 2 ctx1%)

888 return True 2 ctx1%)

889 return False 

890 

891 def test(self, *_args: Any, **_kwargs: Any) -> bool: # noqa: ANN401 (empty)

892 """Return true if this feature is enabled.""" 

893 if self == Feature.SSH_KEY: 2 ctx1%)

894 return self._test_ssh_key() 2 ctx1%)

895 return False # pragma: no cover [unused] 

896 

897 __str__ = str.__str__ (empty)

898 __format__ = str.__format__ # type: ignore[assignment] (empty)

899 

900 

901class DerivationScheme(str, enum.Enum): (empty)

902 """Derivation schemes provided by `derivepassphrase`. 

903 

904 Attributes: 

905 VAULT: 

906 The derivation scheme used by James Coglan's `vault`. 

907 

908 """ 

909 

910 VAULT = "vault" (empty)

911 """""" (empty)

912 

913 def test(self, *_args: Any, **_kwargs: Any) -> bool: # noqa: ANN401 (empty)

914 """Return true if this derivation scheme is enabled.""" 

915 return self == DerivationScheme.VAULT 2 ctx1%]

916 

917 __str__ = str.__str__ (empty)

918 __format__ = str.__format__ # type: ignore[assignment] (empty)

919 

920 

921class ForeignConfigurationFormat(str, enum.Enum): (empty)

922 """Configuration formats supported by `derivepassphrase export`. 

923 

924 Attributes: 

925 VAULT_STOREROOM: 

926 The vault "storeroom" format for the `export vault` 

927 subcommand.