Merge remote-tracking branch 'origin/main' into stlc/promote-next

Author: kernel-internal[bot]

src/kernel/resources/credentials.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from typing import Dict, Optional
+from typing_extensions import Literal
 
 import httpx
 
@@ -54,6 +55,9 @@ def create(
         name: str,
         values: Dict[str, str],
         sso_provider: str | Omit = omit,
+        totp_algorithm: Literal["SHA1", "SHA256", "SHA512"] | Omit = omit,
+        totp_digits: int | Omit = omit,
+        totp_period: int | Omit = omit,
         totp_secret: str | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
@@ -77,8 +81,20 @@ def create(
               button, it will be clicked first before filling credential values on the
               identity provider's login page.
 
-          totp_secret: Base32-encoded TOTP secret for generating one-time passwords. Used for automatic
-              2FA during login.
+          totp_algorithm: HMAC algorithm used to generate TOTP codes. Defaults to SHA1 and is ignored when
+              an `otpauth://` URI supplies the algorithm.
+
+          totp_digits: Number of digits in generated TOTP codes. Defaults to 6 and is ignored when an
+              `otpauth://` URI supplies the digit count.
+
+          totp_period: TOTP rotation period in seconds. Defaults to 30 and is ignored when an
+              `otpauth://` URI supplies the period.
+
+          totp_secret: Accepts a 16-128 character base32-encoded TOTP secret or an `otpauth://totp/...`
+              URI. The range accepts existing shorter seeds and longer seeds regardless of
+              HMAC algorithm; RFC 6238 recommends unpadded base32 lengths of 32/52/103 for
+              SHA1/SHA256/SHA512. Only URI parameters present override the corresponding
+              explicit TOTP fields. Used for automatic 2FA during login.
 
           extra_headers: Send extra headers
 
@@ -96,6 +112,9 @@ def create(
                     "name": name,
                     "values": values,
                     "sso_provider": sso_provider,
+                    "totp_algorithm": totp_algorithm,
+                    "totp_digits": totp_digits,
+                    "totp_period": totp_period,
                     "totp_secret": totp_secret,
                 },
                 credential_create_params.CredentialCreateParams,
@@ -147,6 +166,9 @@ def update(
         name: str | Omit = omit,
         remove_value_keys: SequenceNotStr[str] | Omit = omit,
         sso_provider: Optional[str] | Omit = omit,
+        totp_algorithm: Literal["SHA1", "SHA256", "SHA512"] | Omit = omit,
+        totp_digits: int | Omit = omit,
+        totp_period: int | Omit = omit,
         totp_secret: str | Omit = omit,
         values: Dict[str, str] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
@@ -170,8 +192,20 @@ def update(
           sso_provider: If set, indicates this credential should be used with the specified SSO
               provider. Set to empty string or null to remove.
 
-          totp_secret: Base32-encoded TOTP secret for generating one-time passwords. Spaces and
-              formatting are automatically normalized. Set to empty string to remove.
+          totp_algorithm: HMAC algorithm used to generate TOTP codes. Requires totp_secret and is ignored
+              when an `otpauth://` URI supplies the algorithm.
+
+          totp_digits: Number of digits in generated TOTP codes. Requires totp_secret and is ignored
+              when an `otpauth://` URI supplies the digit count.
+
+          totp_period: TOTP rotation period in seconds. Requires totp_secret and is ignored when an
+              `otpauth://` URI supplies the period.
+
+          totp_secret: Accepts a 16-128 character base32-encoded TOTP secret or an `otpauth://totp/...`
+              URI. Only URI parameters present override the corresponding explicit TOTP
+              fields. When rotating a raw secret, omitted fields preserve their existing
+              values; a new URI defaults unspecified fields to SHA1/6/30. Set to empty string
+              to remove the secret and its metadata.
 
           values: Field name to value mapping. Values are merged with existing values (new keys
               added, existing keys overwritten).
@@ -193,6 +227,9 @@ def update(
                     "name": name,
                     "remove_value_keys": remove_value_keys,
                     "sso_provider": sso_provider,
+                    "totp_algorithm": totp_algorithm,
+                    "totp_digits": totp_digits,
+                    "totp_period": totp_period,
                     "totp_secret": totp_secret,
                     "values": values,
                 },
@@ -360,6 +397,9 @@ async def create(
         name: str,
         values: Dict[str, str],
         sso_provider: str | Omit = omit,
+        totp_algorithm: Literal["SHA1", "SHA256", "SHA512"] | Omit = omit,
+        totp_digits: int | Omit = omit,
+        totp_period: int | Omit = omit,
         totp_secret: str | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
@@ -383,8 +423,20 @@ async def create(
               button, it will be clicked first before filling credential values on the
               identity provider's login page.
 
-          totp_secret: Base32-encoded TOTP secret for generating one-time passwords. Used for automatic
-              2FA during login.
+          totp_algorithm: HMAC algorithm used to generate TOTP codes. Defaults to SHA1 and is ignored when
+              an `otpauth://` URI supplies the algorithm.
+
+          totp_digits: Number of digits in generated TOTP codes. Defaults to 6 and is ignored when an
+              `otpauth://` URI supplies the digit count.
+
+          totp_period: TOTP rotation period in seconds. Defaults to 30 and is ignored when an
+              `otpauth://` URI supplies the period.
+
+          totp_secret: Accepts a 16-128 character base32-encoded TOTP secret or an `otpauth://totp/...`
+              URI. The range accepts existing shorter seeds and longer seeds regardless of
+              HMAC algorithm; RFC 6238 recommends unpadded base32 lengths of 32/52/103 for
+              SHA1/SHA256/SHA512. Only URI parameters present override the corresponding
+              explicit TOTP fields. Used for automatic 2FA during login.
 
           extra_headers: Send extra headers
 
@@ -402,6 +454,9 @@ async def create(
                     "name": name,
                     "values": values,
                     "sso_provider": sso_provider,
+                    "totp_algorithm": totp_algorithm,
+                    "totp_digits": totp_digits,
+                    "totp_period": totp_period,
                     "totp_secret": totp_secret,
                 },
                 credential_create_params.CredentialCreateParams,
@@ -453,6 +508,9 @@ async def update(
         name: str | Omit = omit,
         remove_value_keys: SequenceNotStr[str] | Omit = omit,
         sso_provider: Optional[str] | Omit = omit,
+        totp_algorithm: Literal["SHA1", "SHA256", "SHA512"] | Omit = omit,
+        totp_digits: int | Omit = omit,
+        totp_period: int | Omit = omit,
         totp_secret: str | Omit = omit,
         values: Dict[str, str] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
@@ -476,8 +534,20 @@ async def update(
           sso_provider: If set, indicates this credential should be used with the specified SSO
               provider. Set to empty string or null to remove.
 
-          totp_secret: Base32-encoded TOTP secret for generating one-time passwords. Spaces and
-              formatting are automatically normalized. Set to empty string to remove.
+          totp_algorithm: HMAC algorithm used to generate TOTP codes. Requires totp_secret and is ignored
+              when an `otpauth://` URI supplies the algorithm.
+
+          totp_digits: Number of digits in generated TOTP codes. Requires totp_secret and is ignored
+              when an `otpauth://` URI supplies the digit count.
+
+          totp_period: TOTP rotation period in seconds. Requires totp_secret and is ignored when an
+              `otpauth://` URI supplies the period.
+
+          totp_secret: Accepts a 16-128 character base32-encoded TOTP secret or an `otpauth://totp/...`
+              URI. Only URI parameters present override the corresponding explicit TOTP
+              fields. When rotating a raw secret, omitted fields preserve their existing
+              values; a new URI defaults unspecified fields to SHA1/6/30. Set to empty string
+              to remove the secret and its metadata.
 
           values: Field name to value mapping. Values are merged with existing values (new keys
               added, existing keys overwritten).
@@ -499,6 +569,9 @@ async def update(
                     "name": name,
                     "remove_value_keys": remove_value_keys,
                     "sso_provider": sso_provider,
+                    "totp_algorithm": totp_algorithm,
+                    "totp_digits": totp_digits,
+                    "totp_period": totp_period,
                     "totp_secret": totp_secret,
                     "values": values,
                 },

src/kernel/types/credential.py

@@ -2,6 +2,7 @@
 
 from typing import List, Optional
 from datetime import datetime
+from typing_extensions import Literal
 
 from .._models import BaseModel
 
@@ -40,15 +41,33 @@ class Credential(BaseModel):
     identity provider's login page.
     """
 
+    totp_algorithm: Optional[Literal["SHA1", "SHA256", "SHA512"]] = None
+    """HMAC algorithm used to generate TOTP codes.
+
+    Defaults to SHA1 for credentials created before this metadata was stored.
+    """
+
     totp_code: Optional[str] = None
-    """Current 6-digit TOTP code.
+    """Current TOTP code.
 
     Only included in create/update responses when totp_secret was just set.
     """
 
     totp_code_expires_at: Optional[datetime] = None
     """When the totp_code expires. Only included when totp_code is present."""
 
+    totp_digits: Optional[int] = None
+    """Number of digits in generated TOTP codes.
+
+    Defaults to 6 for credentials created before this metadata was stored.
+    """
+
+    totp_period: Optional[int] = None
+    """TOTP rotation period in seconds.
+
+    Defaults to 30 for credentials created before this metadata was stored.
+    """
+
     value_keys: Optional[List[str]] = None
     """The field names stored in this credential's values (e.g., username, password).
 

src/kernel/types/credential_create_params.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from typing import Dict
-from typing_extensions import Required, TypedDict
+from typing_extensions import Literal, Required, TypedDict
 
 __all__ = ["CredentialCreateParams"]
 
@@ -26,8 +26,29 @@ class CredentialCreateParams(TypedDict, total=False):
     identity provider's login page.
     """
 
-    totp_secret: str
-    """Base32-encoded TOTP secret for generating one-time passwords.
+    totp_algorithm: Literal["SHA1", "SHA256", "SHA512"]
+    """HMAC algorithm used to generate TOTP codes.
+
+    Defaults to SHA1 and is ignored when an `otpauth://` URI supplies the algorithm.
+    """
+
+    totp_digits: int
+    """Number of digits in generated TOTP codes.
+
+    Defaults to 6 and is ignored when an `otpauth://` URI supplies the digit count.
+    """
 
-    Used for automatic 2FA during login.
+    totp_period: int
+    """TOTP rotation period in seconds.
+
+    Defaults to 30 and is ignored when an `otpauth://` URI supplies the period.
+    """
+
+    totp_secret: str
+    """
+    Accepts a 16-128 character base32-encoded TOTP secret or an `otpauth://totp/...`
+    URI. The range accepts existing shorter seeds and longer seeds regardless of
+    HMAC algorithm; RFC 6238 recommends unpadded base32 lengths of 32/52/103 for
+    SHA1/SHA256/SHA512. Only URI parameters present override the corresponding
+    explicit TOTP fields. Used for automatic 2FA during login.
     """

src/kernel/types/credential_update_params.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from typing import Dict, Optional
-from typing_extensions import TypedDict
+from typing_extensions import Literal, TypedDict
 
 from .._types import SequenceNotStr
 
@@ -28,11 +28,34 @@ class CredentialUpdateParams(TypedDict, total=False):
     Set to empty string or null to remove.
     """
 
-    totp_secret: str
-    """Base32-encoded TOTP secret for generating one-time passwords.
+    totp_algorithm: Literal["SHA1", "SHA256", "SHA512"]
+    """HMAC algorithm used to generate TOTP codes.
+
+    Requires totp_secret and is ignored when an `otpauth://` URI supplies the
+    algorithm.
+    """
+
+    totp_digits: int
+    """Number of digits in generated TOTP codes.
+
+    Requires totp_secret and is ignored when an `otpauth://` URI supplies the digit
+    count.
+    """
 
-    Spaces and formatting are automatically normalized. Set to empty string to
-    remove.
+    totp_period: int
+    """TOTP rotation period in seconds.
+
+    Requires totp_secret and is ignored when an `otpauth://` URI supplies the
+    period.
+    """
+
+    totp_secret: str
+    """
+    Accepts a 16-128 character base32-encoded TOTP secret or an `otpauth://totp/...`
+    URI. Only URI parameters present override the corresponding explicit TOTP
+    fields. When rotating a raw secret, omitted fields preserve their existing
+    values; a new URI defaults unspecified fields to SHA1/6/30. Set to empty string
+    to remove the secret and its metadata.
     """
 
     values: Dict[str, str]

tests/api_resources/test_credentials.py

@@ -45,6 +45,9 @@ def test_method_create_with_all_params(self, client: Kernel) -> None:
                 "password": "mysecretpassword",
             },
             sso_provider="google",
+            totp_algorithm="SHA1",
+            totp_digits=6,
+            totp_period=30,
             totp_secret="JBSWY3DPEHPK3PXP",
         )
         assert_matches_type(Credential, credential, path=["response"])
@@ -143,6 +146,9 @@ def test_method_update_with_all_params(self, client: Kernel) -> None:
             name="my-updated-login",
             remove_value_keys=["old_field"],
             sso_provider="google",
+            totp_algorithm="SHA1",
+            totp_digits=6,
+            totp_period=30,
             totp_secret="JBSWY3DPEHPK3PXP",
             values={
                 "username": "user@example.com",
@@ -338,6 +344,9 @@ async def test_method_create_with_all_params(self, async_client: AsyncKernel) ->
                 "password": "mysecretpassword",
             },
             sso_provider="google",
+            totp_algorithm="SHA1",
+            totp_digits=6,
+            totp_period=30,
             totp_secret="JBSWY3DPEHPK3PXP",
         )
         assert_matches_type(Credential, credential, path=["response"])
@@ -436,6 +445,9 @@ async def test_method_update_with_all_params(self, async_client: AsyncKernel) ->
             name="my-updated-login",
             remove_value_keys=["old_field"],
             sso_provider="google",
+            totp_algorithm="SHA1",
+            totp_digits=6,
+            totp_period=30,
             totp_secret="JBSWY3DPEHPK3PXP",
             values={
                 "username": "user@example.com",