feat: add CNS (Cartão Nacional de Saúde) validator

CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Utilitário `is_valid_cns` [#774](https://github.com/brazilian-utils/python/issues/774)
+- Utilitário `generate_cns` [#774](https://github.com/brazilian-utils/python/issues/774)
+- Utilitário `format_cns` [#774](https://github.com/brazilian-utils/python/issues/774)
+- Utilitário `remove_symbols_cns` [#774](https://github.com/brazilian-utils/python/issues/774)
+
 ## [2.5.0] - 2026-06-30
 
 ### Added

README.md

@@ -76,6 +76,11 @@ False
   - [convert\_date\_to_text](#convert_date_to_text)
 - [CNH](#cnh)
   - [is\_valid\_cnh](#is_valid_cnh)
+- [CNS](#cns)
+  - [is\_valid\_cns](#is_valid_cns)
+  - [format\_cns](#format_cns)
+  - [remove\_symbols\_cns](#remove_symbols_cns)
+  - [generate\_cns](#generate_cns)
 - [Placa de Carro](#placa-de-carro)
   - [is\_valid\_license\_plate](#is_valid_license_plate)
   - [format\_license\_plate](#format_license_plate)
@@ -727,6 +732,103 @@ True
 True
 ```
 
+## CNS
+
+### is_valid_cns
+
+Verifica se o número do CNS (Cartão Nacional de Saúde) é válido. Apenas números, formatado como
+uma string, com o tamanho correto (15 dígitos). Não verifica se o CNS realmente existe.
+
+Referências:
+
+- <https://gist.github.com/dudanogueira/7af722477c33bd4bb85843cf0e035b77>.
+- <https://integracao.esusaps.bridge.ufsc.tech/v211/docs/algoritmo_CNS.html>.
+
+Argumentos:
+
+- cns (str): número do CNS como uma string do tamanho correto.
+
+Retorno:
+
+- bool: True se o CNS for válido, False caso contrário.
+
+Exemplo:
+
+```python
+from brutils import is_valid_cns
+>>> is_valid_cns("161243374450004")
+True
+>>> is_valid_cns("123456789012345")
+False
+```
+
+### format_cns
+
+Formata uma string de CNS (Cartão Nacional de Saúde) válida com os símbolos visuais padrão de
+exibição.
+
+Argumentos:
+
+- cns (str): uma string de CNS válida contendo apenas números.
+
+Retorno:
+
+- str: uma string de CNS formatada com os símbolos visuais padrão ou None caso a entrada seja
+  inválida.
+
+Exemplo:
+
+```python
+from brutils import format_cns
+>>> format_cns("161243374450004")
+'161 2433 7445 0004'
+```
+
+### remove_symbols_cns
+
+Esta função recebe uma string de CNS (Cartão Nacional de Saúde) com símbolos de formatação e
+retorna uma versão limpa sem determinados símbolos. Remove intencionalmente apenas os símbolos
+"-", "." e " ", deixando os demais símbolos intactos.
+
+Argumentos:
+
+- cns (str): uma string de CNS que pode conter símbolos de formatação.
+
+Retorno:
+
+- str: uma string de CNS limpa, sem símbolos de formatação.
+
+Exemplo:
+
+```python
+from brutils import remove_symbols_cns
+>>> remove_symbols_cns("161 2433 7445 0004")
+'161243374450004'
+```
+
+### generate_cns
+
+Gera uma string de dígitos contendo um número de CNS brasileiro válido aleatório. Pode gerar um
+CNS "definitivo" (iniciado em 1 ou 2) ou "provisório" (iniciado em 7, 8 ou 9).
+
+Argumentos:
+
+- is_final (bool): se deve gerar um CNS definitivo. Padrão é True.
+
+Retorno:
+
+- str: um número de CNS válido gerado aleatoriamente, como uma string.
+
+Exemplo:
+
+```python
+from brutils import generate_cns
+>>> generate_cns()
+'161243374450004'
+>>> generate_cns(is_final=False)
+'905885616557480'
+```
+
 
 ## Placa de Carro
 

README_EN.md

@@ -75,6 +75,11 @@ False
   - [is\_valid\_email](#is_valid_email)
 - [CNH](#cnh)
   - [is\_valid\_cnh](#is_valid_cnh)
+- [CNS](#cns)
+  - [is\_valid\_cns](#is_valid_cns)
+  - [format\_cns](#format_cns)
+  - [remove\_symbols\_cns](#remove_symbols_cns)
+  - [generate\_cns](#generate_cns)
 - [License Plate](#license-plate)
   - [is\_valid\_license\_plate](#is_valid_license_plate)
   - [format\_license\_plate](#format_license_plate)
@@ -719,6 +724,96 @@ True
 True
 ```
 
+## CNS
+
+### is_valid_cns
+
+Verifies if the CNS (Cartão Nacional de Saúde) number is valid. Only numbers, formatted as a string, with proper length (15 digits). It does not check if the CNS actually exists.
+
+References:
+
+- <https://gist.github.com/dudanogueira/7af722477c33bd4bb85843cf0e035b77>.
+- <https://integracao.esusaps.bridge.ufsc.tech/v211/docs/algoritmo_CNS.html>.
+
+Args:
+
+- cns (str): CNS number as a string of proper length.
+
+Returns:
+
+- bool: True if the CNS is valid, False otherwise.
+
+Example:
+
+```python
+from brutils import is_valid_cns
+>>> is_valid_cns("161243374450004")
+True
+>>> is_valid_cns("123456789012345")
+False
+```
+
+### format_cns
+
+Formats a valid CNS (Cartão Nacional de Saúde) string with standard visual aid symbols for display.
+
+Args:
+
+- cns (str): A valid string of CNS containing only numbers.
+
+Returns:
+
+- str: A formatted CNS string with standard visual aid symbols or None if the input is invalid.
+
+Example:
+
+```python
+from brutils import format_cns
+>>> format_cns("161243374450004")
+'161 2433 7445 0004'
+```
+
+### remove_symbols_cns
+
+This function takes a string of CNS (Cartão Nacional de Saúde) with formatting symbols and returns a clean version without certain symbols. It intentionally removes only the symbols "-", "." and " ", leaving other symbols untouched.
+
+Args:
+
+- cns (str): A string of CNS that may contain formatting symbols.
+
+Returns:
+
+- str: A clean string of CNS without formatting symbols.
+
+Example:
+
+```python
+from brutils import remove_symbols_cns
+>>> remove_symbols_cns("161 2433 7445 0004")
+'161243374450004'
+```
+
+### generate_cns
+
+Generates a string of digits containing a random valid Brazilian CNS number. Can generate either a "definitive" CNS (starting with 1 or 2) or a "provisional" one (starting with 7, 8 or 9).
+
+Args:
+
+- is_final (bool): Whether to generate a definitive CNS. Defaults to True.
+
+Returns:
+
+- str: A randomly generated valid CNS number as a string.
+
+Example:
+
+```python
+from brutils import generate_cns
+>>> generate_cns()
+'161243374450004'
+>>> generate_cns(is_final=False)
+'905885616557480'
+```
 
 ## License Plate
 

brutils/__init__.py

@@ -17,6 +17,12 @@
 from brutils.cnpj import is_valid as is_valid_cnpj
 from brutils.cnpj import remove_symbols as remove_symbols_cnpj
 
+# CNS Imports
+from brutils.cns import format_cns
+from brutils.cns import generate as generate_cns
+from brutils.cns import is_valid as is_valid_cns
+from brutils.cns import remove_symbols as remove_symbols_cns
+
 # CPF Imports
 from brutils.cpf import format_cpf
 from brutils.cpf import generate as generate_cpf
@@ -114,6 +120,11 @@
     "remove_symbols_cpf",
     # CNH
     "is_valid_cnh",
+    # CNS
+    "format_cns",
+    "generate_cns",
+    "is_valid_cns",
+    "remove_symbols_cns",
     # Email
     "is_valid_email",
     # Legal Process