Debian Codegraph @

x3dh/migrations.py

raw
1 from __future__ import annotations
2
3 import base64
4 from typing import List, Tuple, cast
5
6 from pydantic import BaseModel
7
8 from .models import IdentityKeyPairModel, SignedPreKeyPairModel, BaseStateModel
9 from .types import JSONObject, SecretType
10
11
12 __all__ = [
13 "parse_identity_key_pair_model",
14 "parse_signed_pre_key_pair_model",
15 "parse_base_state_model"
16 ]
17
18
19 class PreStableKeyPairModel(BaseModel):
20 """
21 This model describes how a key pair was serialized in pre-stable serialization format.
22 """
23
24 priv: str
25 pub: str
26
27
28 class PreStableSignedPreKeyModel(BaseModel):
29 """
30 This model describes how a signed pre-key was serialized in pre-stable serialization format.
31 """
32
33 key: PreStableKeyPairModel
34 signature: str
35 timestamp: float
36
37
38 class PreStableModel(BaseModel):
39 """
40 This model describes how State instances were serialized in pre-stable serialization format.
41 """
42
43 changed: bool
44 ik: PreStableKeyPairModel
45 spk: PreStableSignedPreKeyModel
46 otpks: List[PreStableKeyPairModel]
47
48
49 def parse_identity_key_pair_model(serialized: JSONObject) -> IdentityKeyPairModel:
50 """
51 Parse a serialized :class:`~x3dh.identity_key_pair.IdentityKeyPair` instance, as returned by
52 :attr:`~x3dh.identity_key_pair.IdentityKeyPair.json`, into the most recent pydantic model available for
53 the class. Perform migrations in case the pydantic models were updated.
54
55 Args:
56 serialized: The serialized instance.
57
58 Returns:
59 The model, which can be used to restore the instance using
60 :meth:`~x3dh.identity_key_pair.IdentityKeyPair.from_model`.
61
62 Note:
63 Pre-stable data can only be migrated as a whole using :func:`parse_base_state_model`.
64 """
65
66 # Each model has a Python string "version" in its root. Use that to find the model that the data was
67 # serialized from.
68 version = cast(str, serialized["version"])
69 model: BaseModel = {
70 "1.0.0": IdentityKeyPairModel,
71 "1.0.1": IdentityKeyPairModel
72 }[version](**serialized) # type: ignore[arg-type]
73
74 # Once all migrations have been applied, the model should be an instance of the most recent model
75 assert isinstance(model, IdentityKeyPairModel)
76
77 return model
78
79
80 def parse_signed_pre_key_pair_model(serialized: JSONObject) -> SignedPreKeyPairModel:
81 """
82 Parse a serialized :class:`~x3dh.signed_pre_key_pair.SignedPreKeyPair` instance, as returned by
83 :attr:`~x3dh.signed_pre_key_pair.SignedPreKeyPair.json`, into the most recent pydantic model available for
84 the class. Perform migrations in case the pydantic models were updated.
85
86 Args:
87 serialized: The serialized instance.
88
89 Returns:
90 The model, which can be used to restore the instance using
91 :meth:`~x3dh.signed_pre_key_pair.SignedPreKeyPair.from_model`.
92
93 Note:
94 Pre-stable data can only be migrated as a whole using :func:`parse_base_state_model`.
95 """
96
97 # Each model has a Python string "version" in its root. Use that to find the model that the data was
98 # serialized from.
99 version = cast(str, serialized["version"])
100 model: BaseModel = {
101 "1.0.0": SignedPreKeyPairModel,
102 "1.0.1": SignedPreKeyPairModel
103 }[version](**serialized) # type: ignore[arg-type]
104
105 # Once all migrations have been applied, the model should be an instance of the most recent model
106 assert isinstance(model, SignedPreKeyPairModel)
107
108 return model
109
110
111 def parse_base_state_model(serialized: JSONObject) -> Tuple[BaseStateModel, bool]:
112 """
113 Parse a serialized :class:`~x3dh.base_state.BaseState` instance, as returned by
114 :attr:`~x3dh.base_state.BaseState.json`, into the most recent pydantic model available for the class.
115 Perform migrations in case the pydantic models were updated. Supports migration of pre-stable data.
116
117 Args:
118 serialized: The serialized instance.
119
120 Returns:
121 The model, which can be used to restore the instance using
122 :meth:`~x3dh.base_state.BaseState.from_model`, and a flag that indicates whether the bundle needs to
123 be published, which was part of the pre-stable serialization format.
124 """
125
126 bundle_needs_publish = False
127
128 # Each model has a Python string "version" in its root. Use that to find the model that the data was
129 # serialized from. Special case: the pre-stable serialization format does not contain a version.
130 version = cast(str, serialized["version"]) if "version" in serialized else None
131 model: BaseModel = {
132 None: PreStableModel,
133 "1.0.0": BaseStateModel,
134 "1.0.1": BaseStateModel
135 }[version](**serialized)
136
137 if isinstance(model, PreStableModel):
138 # Run migrations from PreStableModel to StateModel
139 bundle_needs_publish = bundle_needs_publish or model.changed
140
141 model = BaseStateModel(
142 identity_key=IdentityKeyPairModel(
143 secret=base64.b64decode(model.ik.priv),
144 secret_type=SecretType.PRIV
145 ),
146 signed_pre_key=SignedPreKeyPairModel(
147 priv=base64.b64decode(model.spk.key.priv),
148 sig=base64.b64decode(model.spk.signature),
149 timestamp=int(model.spk.timestamp)
150 ),
151 old_signed_pre_key=None,
152 pre_keys=frozenset({ base64.b64decode(pre_key.priv) for pre_key in model.otpks })
153 )
154
155 # Once all migrations have been applied, the model should be an instance of the most recent model
156 assert isinstance(model, BaseStateModel)
157
158 return model, bundle_needs_publish