Skip to content

Auth

erpc.auth

eRPC authentication configuration dataclasses.

Maps the eRPC auth strategy surface to Python dataclasses. Each strategy type corresponds to a supported eRPC authentication method: secret tokens, JWT verification, Sign-In with Ethereum (SIWE), and network-level IP filtering.

Examples:

>>> from erpc.auth import AuthConfig, SecretAuth, SIWEAuth
>>> auth = AuthConfig(
...     strategies=[
...         SecretAuth(value="my-api-key", rate_limit_budget="free-tier"),
...         SIWEAuth(rate_limit_budget="wallet-tier"),
...     ]
... )
>>> auth.to_dict()["strategies"][0]["type"]
'secret'

AuthStrategy dataclass

Base class for eRPC authentication strategies.

Subclasses must set strategy_type and implement to_dict().

Attributes:

Name Type Description
strategy_type str

The eRPC strategy type identifier.
Source code in erpc/auth.py 
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
@dataclass
class AuthStrategy:
    """Base class for eRPC authentication strategies.

    Subclasses must set ``strategy_type`` and implement ``to_dict()``.

    Attributes:
        strategy_type: The eRPC strategy type identifier.

    """

    strategy_type: str = ""

    def to_dict(self) -> dict[str, Any]:
        """Serialize to an eRPC-compatible dictionary.

        Returns:
            Dictionary matching the eRPC auth strategy YAML schema.

        Raises:
            NotImplementedError: If called on the base class directly.

        """
        raise NotImplementedError

to_dict 

to_dict() -> dict[str, Any]

Serialize to an eRPC-compatible dictionary.

Returns:

Type Description
dict[str, Any]

Dictionary matching the eRPC auth strategy YAML schema.

Raises:

Type Description
NotImplementedError

If called on the base class directly.
Source code in erpc/auth.py 
52
53
54
55
56
57
58
59
60
61
62
def to_dict(self) -> dict[str, Any]:
    """Serialize to an eRPC-compatible dictionary.

    Returns:
        Dictionary matching the eRPC auth strategy YAML schema.

    Raises:
        NotImplementedError: If called on the base class directly.

    """
    raise NotImplementedError

SecretAuth dataclass

Bases: AuthStrategy

Secret token authentication strategy.

Authenticates requests via a shared secret value (e.g., API key).

Attributes:

Name Type Description
value str

The secret token value.
rate_limit_budget str | None

Optional rate limit budget name to apply.

Examples:

>>> auth = SecretAuth(value="my-key")
>>> auth.to_dict()
{'type': 'secret', 'secret': {'value': 'my-key'}}
Source code in erpc/auth.py 
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
@dataclass
class SecretAuth(AuthStrategy):
    """Secret token authentication strategy.

    Authenticates requests via a shared secret value (e.g., API key).

    Attributes:
        value: The secret token value.
        rate_limit_budget: Optional rate limit budget name to apply.

    Examples:
        >>> auth = SecretAuth(value="my-key")
        >>> auth.to_dict()
        {'type': 'secret', 'secret': {'value': 'my-key'}}

    """

    strategy_type: str = field(default="secret", init=False, repr=False)
    value: str = ""
    rate_limit_budget: str | None = None

    def to_dict(self) -> dict[str, Any]:
        """Serialize to an eRPC-compatible dictionary.

        Returns:
            Dictionary with ``type``, ``secret``, and optional ``rateLimitBudget``.

        """
        d: dict[str, Any] = {
            "type": "secret",
            "secret": {"value": self.value},
        }
        if self.rate_limit_budget is not None:
            d["rateLimitBudget"] = self.rate_limit_budget
        return d

to_dict 

to_dict() -> dict[str, Any]

Serialize to an eRPC-compatible dictionary.

Returns:

Type Description
dict[str, Any]

Dictionary with type, secret, and optional rateLimitBudget.
Source code in erpc/auth.py 
86
87
88
89
90
91
92
93
94
95
96
97
98
99
def to_dict(self) -> dict[str, Any]:
    """Serialize to an eRPC-compatible dictionary.

    Returns:
        Dictionary with ``type``, ``secret``, and optional ``rateLimitBudget``.

    """
    d: dict[str, Any] = {
        "type": "secret",
        "secret": {"value": self.value},
    }
    if self.rate_limit_budget is not None:
        d["rateLimitBudget"] = self.rate_limit_budget
    return d

JWTAuth dataclass

Bases: AuthStrategy

JWT (JSON Web Token) authentication strategy.

Verifies JWTs using public keys and extracts rate limit budget from a configurable claim.

Attributes:

Name Type Description
verification_keys list[dict[str, Any]]

List of key configs (algorithm + publicKeyPem).
rate_limit_budget_claim_name str

JWT claim name containing the budget identifier.
allowed_issuers list[str] | None

Optional whitelist of token issuers.
allowed_audiences list[str] | None

Optional whitelist of token audiences.

Examples:

>>> keys = [{"algorithm": "RS256", "publicKeyPem": "..."}]
>>> auth = JWTAuth(verification_keys=keys, rate_limit_budget_claim_name="plan")
>>> auth.to_dict()["type"]
'jwt'
Source code in erpc/auth.py 
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
143
144
@dataclass
class JWTAuth(AuthStrategy):
    """JWT (JSON Web Token) authentication strategy.

    Verifies JWTs using public keys and extracts rate limit budget
    from a configurable claim.

    Attributes:
        verification_keys: List of key configs (algorithm + publicKeyPem).
        rate_limit_budget_claim_name: JWT claim name containing the budget identifier.
        allowed_issuers: Optional whitelist of token issuers.
        allowed_audiences: Optional whitelist of token audiences.

    Examples:
        >>> keys = [{"algorithm": "RS256", "publicKeyPem": "..."}]
        >>> auth = JWTAuth(verification_keys=keys, rate_limit_budget_claim_name="plan")
        >>> auth.to_dict()["type"]
        'jwt'

    """

    strategy_type: str = field(default="jwt", init=False, repr=False)
    verification_keys: list[dict[str, Any]] = field(default_factory=list)
    rate_limit_budget_claim_name: str = ""
    allowed_issuers: list[str] | None = None
    allowed_audiences: list[str] | None = None

    def to_dict(self) -> dict[str, Any]:
        """Serialize to an eRPC-compatible dictionary.

        Returns:
            Dictionary with ``type`` and ``jwt`` containing verification config.

        """
        jwt_config: dict[str, Any] = {
            "verificationKeys": self.verification_keys,
            "rateLimitBudgetClaimName": self.rate_limit_budget_claim_name,
        }
        if self.allowed_issuers is not None:
            jwt_config["allowedIssuers"] = self.allowed_issuers
        if self.allowed_audiences is not None:
            jwt_config["allowedAudiences"] = self.allowed_audiences
        return {"type": "jwt", "jwt": jwt_config}

to_dict 

to_dict() -> dict[str, Any]

Serialize to an eRPC-compatible dictionary.

Returns:

Type Description
dict[str, Any]

Dictionary with type and jwt containing verification config.
Source code in erpc/auth.py 
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
def to_dict(self) -> dict[str, Any]:
    """Serialize to an eRPC-compatible dictionary.

    Returns:
        Dictionary with ``type`` and ``jwt`` containing verification config.

    """
    jwt_config: dict[str, Any] = {
        "verificationKeys": self.verification_keys,
        "rateLimitBudgetClaimName": self.rate_limit_budget_claim_name,
    }
    if self.allowed_issuers is not None:
        jwt_config["allowedIssuers"] = self.allowed_issuers
    if self.allowed_audiences is not None:
        jwt_config["allowedAudiences"] = self.allowed_audiences
    return {"type": "jwt", "jwt": jwt_config}

SIWEAuth dataclass

Bases: AuthStrategy

Sign-In with Ethereum (SIWE) authentication strategy.

Authenticates requests using EIP-4361 signed messages.

Attributes:

Name Type Description
rate_limit_budget str | None

Optional rate limit budget name to apply.

Examples:

>>> auth = SIWEAuth(rate_limit_budget="wallet-tier")
>>> auth.to_dict()
{'type': 'siwe', 'rateLimitBudget': 'wallet-tier'}
Source code in erpc/auth.py 
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
@dataclass
class SIWEAuth(AuthStrategy):
    """Sign-In with Ethereum (SIWE) authentication strategy.

    Authenticates requests using EIP-4361 signed messages.

    Attributes:
        rate_limit_budget: Optional rate limit budget name to apply.

    Examples:
        >>> auth = SIWEAuth(rate_limit_budget="wallet-tier")
        >>> auth.to_dict()
        {'type': 'siwe', 'rateLimitBudget': 'wallet-tier'}

    """

    strategy_type: str = field(default="siwe", init=False, repr=False)
    rate_limit_budget: str | None = None

    def to_dict(self) -> dict[str, Any]:
        """Serialize to an eRPC-compatible dictionary.

        Returns:
            Dictionary with ``type`` and optional ``rateLimitBudget``.

        """
        d: dict[str, Any] = {"type": "siwe"}
        if self.rate_limit_budget is not None:
            d["rateLimitBudget"] = self.rate_limit_budget
        return d

to_dict 

to_dict() -> dict[str, Any]

Serialize to an eRPC-compatible dictionary.

Returns:

Type Description
dict[str, Any]

Dictionary with type and optional rateLimitBudget.
Source code in erpc/auth.py 
166
167
168
169
170
171
172
173
174
175
176
def to_dict(self) -> dict[str, Any]:
    """Serialize to an eRPC-compatible dictionary.

    Returns:
        Dictionary with ``type`` and optional ``rateLimitBudget``.

    """
    d: dict[str, Any] = {"type": "siwe"}
    if self.rate_limit_budget is not None:
        d["rateLimitBudget"] = self.rate_limit_budget
    return d

NetworkAuth dataclass

Bases: AuthStrategy

Network-level (IP-based) authentication strategy.

Restricts access by source IP address or CIDR range.

Attributes:

Name Type Description
rate_limit_budget str | None

Optional rate limit budget name to apply.
allowed_ips list[str] | None

Optional list of allowed IP addresses or CIDR ranges.

Examples:

>>> auth = NetworkAuth(allowed_ips=["10.0.0.0/8"])
>>> auth.to_dict()
{'type': 'network', 'network': {'allowedIPs': ['10.0.0.0/8']}}
Source code in erpc/auth.py 
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
@dataclass
class NetworkAuth(AuthStrategy):
    """Network-level (IP-based) authentication strategy.

    Restricts access by source IP address or CIDR range.

    Attributes:
        rate_limit_budget: Optional rate limit budget name to apply.
        allowed_ips: Optional list of allowed IP addresses or CIDR ranges.

    Examples:
        >>> auth = NetworkAuth(allowed_ips=["10.0.0.0/8"])
        >>> auth.to_dict()
        {'type': 'network', 'network': {'allowedIPs': ['10.0.0.0/8']}}

    """

    strategy_type: str = field(default="network", init=False, repr=False)
    rate_limit_budget: str | None = None
    allowed_ips: list[str] | None = None

    def to_dict(self) -> dict[str, Any]:
        """Serialize to an eRPC-compatible dictionary.

        Returns:
            Dictionary with ``type``, optional ``network``, and ``rateLimitBudget``.

        """
        d: dict[str, Any] = {"type": "network"}
        if self.allowed_ips is not None:
            d["network"] = {"allowedIPs": self.allowed_ips}
        if self.rate_limit_budget is not None:
            d["rateLimitBudget"] = self.rate_limit_budget
        return d

to_dict 

to_dict() -> dict[str, Any]

Serialize to an eRPC-compatible dictionary.

Returns:

Type Description
dict[str, Any]

Dictionary with type, optional network, and rateLimitBudget.
Source code in erpc/auth.py 
200
201
202
203
204
205
206
207
208
209
210
211
212
def to_dict(self) -> dict[str, Any]:
    """Serialize to an eRPC-compatible dictionary.

    Returns:
        Dictionary with ``type``, optional ``network``, and ``rateLimitBudget``.

    """
    d: dict[str, Any] = {"type": "network"}
    if self.allowed_ips is not None:
        d["network"] = {"allowedIPs": self.allowed_ips}
    if self.rate_limit_budget is not None:
        d["rateLimitBudget"] = self.rate_limit_budget
    return d

AuthConfig dataclass

Composable authentication configuration for an eRPC project.

Combines multiple authentication strategies. Each strategy is tried in order until one succeeds.

Attributes:

Name Type Description
strategies list[AuthStrategy]

Ordered list of authentication strategies.

Examples:

>>> config = AuthConfig(strategies=[SecretAuth(value="key")])
>>> len(config.to_dict()["strategies"])
1
Source code in erpc/auth.py 
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
@dataclass
class AuthConfig:
    """Composable authentication configuration for an eRPC project.

    Combines multiple authentication strategies. Each strategy is tried
    in order until one succeeds.

    Attributes:
        strategies: Ordered list of authentication strategies.

    Examples:
        >>> config = AuthConfig(strategies=[SecretAuth(value="key")])
        >>> len(config.to_dict()["strategies"])
        1

    """

    strategies: list[AuthStrategy] = field(default_factory=list)

    def to_dict(self) -> dict[str, Any]:
        """Serialize to an eRPC-compatible dictionary.

        Returns:
            Dictionary with ``strategies`` list of serialized strategy dicts.

        """
        return {"strategies": [s.to_dict() for s in self.strategies]}

to_dict 

to_dict() -> dict[str, Any]

Serialize to an eRPC-compatible dictionary.

Returns:

Type Description
dict[str, Any]

Dictionary with strategies list of serialized strategy dicts.
Source code in erpc/auth.py 
234
235
236
237
238
239
240
241
def to_dict(self) -> dict[str, Any]:
    """Serialize to an eRPC-compatible dictionary.

    Returns:
        Dictionary with ``strategies`` list of serialized strategy dicts.

    """
    return {"strategies": [s.to_dict() for s in self.strategies]}