### utils.to_base64 / utils.from_base64

Source: https://context7.com/sssaas/sssa-python/llms.txt

Provides functions for encoding and decoding 256-bit integers to and from a 44-character URL-safe base64 string. This is used to represent field elements as shareable strings.

```APIDOC
## `utils.to_base64(number)` / `utils.from_base64(number)` — Field integer ↔ base64url encoding

### Description
Encode a 256-bit integer as a 44-character URL-safe base64 string (`to_base64`), and decode it back (`from_base64`). Each share is composed of paired (x, y) base64 values, each 44 characters long, making every share segment exactly 88 characters.

### Method
```python
util.to_base64(number)
util.from_base64(number)
```

### Parameters
- **number** (int) - The 256-bit integer to encode or decode.

### Request Example
```python
from SSSA import utils

util = utils()

# Encode a random field element to a 44-char base64url string
value = util.random()
encoded = util.to_base64(value)

assert len(encoded) == 44
print(encoded)  # e.g. "U1k9koNN67-og3ZY3Mmikeyj4gEFwK4HXDSglM8i_xc="

# Round-trip fidelity
decoded = util.from_base64(encoded)
assert decoded == value

# Validate over 10,000 random values
for _ in range(1000):
    v = util.random()
    assert util.from_base64(util.to_base64(v)) == v
```

### Response
- **`to_base64`**: (str) - A 44-character URL-safe base64 encoded string.
- **`from_base64`**: (int) - The decoded 256-bit integer.
```

--------------------------------

### Create Shares with SSSA Python

Source: https://context7.com/sssaas/sssa-python/llms.txt

Splits a secret string into a specified number of shares. Ensure that the number of shares is greater than or equal to the minimum required for reconstruction.

```python
from SSSA import sssa

sss = sssa()

secret = "my-super-secret-password"
minimum = 3   # need at least 3 shares to reconstruct
total   = 5   # generate 5 shares in total

shares = sss.create(minimum, total, secret)

print(f"Generated {len(shares)} shares:")
for i, share in enumerate(shares):
    print(f"  Share {i+1}: {share}")

# Example output:
# Generated 5 shares:
#   Share 1: U1k9koNN67-og3ZY3Mmikeyj4gEFwK4HXDSglM8i_xc=yA3eU4_XYcJP0ijD63Tv...
#   Share 2: O7c_iMBaGmQQE_uU0XRCPQwhfLBdlc6jseTzK_qN-1s=ICDGdloemG50X5GxteWW...
#   ...

# Guard against invalid arguments
if shares is None:
    raise ValueError("shares must be >= minimum")
```

--------------------------------

### Compute Modular Multiplicative Inverse

Source: https://context7.com/sssaas/sssa-python/llms.txt

Computes the modular multiplicative inverse of a number modulo the prime field using the extended Euclidean algorithm. This is essential for performing field division during Lagrange interpolation in the `combine` function.

```python
from SSSA import utils

util = utils()

value = util.random()
inv = util.mod_inverse(value)

# By definition: value * mod_inverse(value) ≡ 1 (mod prime)
assert (value * inv) % util.prime == 1

# Useful for manual field arithmetic
a, b = util.random(), util.random()
# Compute a / b in the field:
result = (a * util.mod_inverse(b)) % util.prime
```

--------------------------------

### sssa.combine

Source: https://context7.com/sssaas/sssa-python/llms.txt

Reconstructs the original secret from a list of share strings.

```APIDOC
## sssa.combine(shares)

### Description
Reconstructs the original secret from a list of share strings produced by `create`. The function uses Lagrange interpolation over the same prime field to recover the secret polynomial's constant term. Accepts any subset of shares as long as the count meets the original `minimum` threshold. Returns the reconstructed secret string, or `None` if any share is malformed (length not a multiple of 88 characters).

### Parameters
#### Path Parameters
- **shares** (list[str]) - Required - A list of share strings.

### Request Example
```python
from SSSA import sssa

sss = sssa()
# Assuming 'shares' is a list of shares generated by sss.create()
partial_shares = [shares[0], shares[2], shares[4]]
recovered = sss.combine(partial_shares)
```

### Response
#### Success Response (str)
- The reconstructed original secret string.

#### Error Response (None)
- Returns `None` if any share is malformed.
```

--------------------------------

### sssa.create

Source: https://context7.com/sssaas/sssa-python/llms.txt

Splits an arbitrary string secret into a specified number of shares, from which a minimum subset can reconstruct the original secret.

```APIDOC
## sssa.create(minimum, shares, raw)

### Description
Splits an arbitrary string secret (`raw`) into `shares` number of encoded share strings, of which any `minimum` subset can later reconstruct the original. The function builds a random polynomial of degree `minimum - 1` for each 32-byte chunk of the secret and evaluates it at `shares` distinct random points over a 256-bit prime field. Returns a list of base64url-encoded strings, or `None` if `shares < minimum`.

### Parameters
#### Path Parameters
- **minimum** (int) - Required - The minimum number of shares required to reconstruct the secret.
- **shares** (int) - Required - The total number of shares to generate.
- **raw** (str) - Required - The secret string to be split.

### Request Example
```python
from SSSA import sssa

sss = sssa()
secret = "my-super-secret-password"
minimum = 3
shares = sss.create(minimum, 5, secret)
```

### Response
#### Success Response (list[str])
- A list of base64url-encoded share strings.

#### Error Response (None)
- Returns `None` if `shares < minimum`.
```

--------------------------------

### Field Integer to Base64url Encoding

Source: https://context7.com/sssaas/sssa-python/llms.txt

Encodes a 256-bit integer into a 44-character URL-safe base64 string and decodes it back. This is used for share representation, where each share segment is 88 characters long (paired x, y values).

```python
from SSSA import utils

util = utils()

# Encode a random field element to a 44-char base64url string
value = util.random()
encoded = util.to_base64(value)

assert len(encoded) == 44
print(encoded)  # e.g. "U1k9koNN67-og3ZY3Mmikeyj4gEFwK4HXDSglM8i_xc="

# Round-trip fidelity
decoded = util.from_base64(encoded)
assert decoded == value

# Validate over 10,000 random values
for _ in range(1000):
    v = util.random()
    assert util.from_base64(util.to_base64(v)) == v
```

--------------------------------

### utils.mod_inverse

Source: https://context7.com/sssaas/sssa-python/llms.txt

Computes the modular multiplicative inverse of a number modulo the prime field using the extended Euclidean algorithm. This is essential for performing division within the finite field during operations like Lagrange interpolation.

```APIDOC
## `utils.mod_inverse(number)` — Modular multiplicative inverse

### Description
Computes the modular multiplicative inverse of `number` modulo the prime field using the extended Euclidean algorithm. Used internally during Lagrange interpolation in `combine` to perform field division.

### Method
```python
util.mod_inverse(number)
```

### Parameters
- **number** (int) - The number for which to compute the modular inverse.

### Request Example
```python
from SSSA import utils

util = utils()

value = util.random()
inv = util.mod_inverse(value)

# By definition: value * mod_inverse(value) ≡ 1 (mod prime)
assert (value * inv) % util.prime == 1

# Useful for manual field arithmetic
a, b = util.random(), util.random()
# Compute a / b in the field:
result = (a * util.mod_inverse(b)) % util.prime
```

### Response
- **inv** (int) - The modular multiplicative inverse of the input number.
```

--------------------------------

### Encode String to Field Integers with SSSA Utils

Source: https://context7.com/sssaas/sssa-python/llms.txt

Converts a UTF-8 string into a list of integers suitable for the prime field arithmetic. Secrets are chunked into 32-byte segments before conversion.

```python
from SSSA import utils

util = utils()

chunks = util.split_ints("hello world")
print(chunks)
# [48656c6c6f20776f726c640000...  (as integer)]

# Round-trip: split then merge recovers the original string
original = "hello world"
assert util.merge_ints(util.split_ints(original)) == original

# Works with Unicode and binary-like content
unicode_secret = "こんにちは、世界"
assert util.merge_ints(util.split_ints(unicode_secret)) == unicode_secret
```

--------------------------------

### utils.split_ints

Source: https://context7.com/sssaas/sssa-python/llms.txt

Encodes a string as a list of integers suitable for the finite field arithmetic.

```APIDOC
## utils.split_ints(secret)

### Description
Converts an arbitrary UTF-8 string into a list of integers, each fitting within the 256-bit prime field. The string is hex-encoded, zero-padded to 32-byte (64 hex character) chunks, and each chunk is interpreted as a big integer. This chunking allows secrets of arbitrary length to be handled by the polynomial scheme.

### Parameters
#### Path Parameters
- **secret** (str) - Required - The string to encode.

### Request Example
```python
from SSSA import utils

util = utils()
chunks = util.split_ints("hello world")
```

### Response
#### Success Response (list[int])
- A list of integers representing the encoded secret.
```

--------------------------------

### Reconstruct Secret with SSSA Python

Source: https://context7.com/sssaas/sssa-python/llms.txt

Reconstructs the original secret from a list of shares. The number of provided shares must meet the original minimum threshold. Malformed shares can cause reconstruction to fail.

```python
from SSSA import sssa

sss = sssa()

# Simulate receiving only 3 of the original 5 shares (meets minimum=3)
partial_shares = [shares[0], shares[2], shares[4]]

recovered = sss.combine(partial_shares)
print(f"Recovered secret: {recovered}")
# Output: Recovered secret: my-super-secret-password

assert recovered == secret, "Secret mismatch — shares may be corrupt or insufficient"

# Combining pre-known shares from cross-language (Go) compatibility test
known_shares = [
    "U1k9koNN67-og3ZY3Mmikeyj4gEFwK4HXDSglM8i_xc=yA3eU4_XYcJP0ijD63Tvqu1gklhBV32tu8cHPZXP-bk=",
    "O7c_iMBaGmQQE_uU0XRCPQwhfLBdlc6jseTzK_qN-1s=ICDGdloemG50X5GxteWWVZD3EGuxXST4UfZcek_teng=",
    "8qzYpjk7lmB7cRkOl6-7srVTKNYHuqUO2WO31Y0j1Tw=-g6srNoWkZTBqrKA2cMCA-6jxZiZv25rvbrCUWVHb5g=",
]
print(sss.combine(known_shares))
```

--------------------------------

### utils.evaluate_polynomial

Source: https://context7.com/sssaas/sssa-python/llms.txt

Evaluates a polynomial defined by coefficients (constant term first) at a given value using Horner's method, with all arithmetic performed modulo a 256-bit prime. This is crucial for computing the y-coordinate of each share.

```APIDOC
## `utils.evaluate_polynomial(coefficients, value)` — Evaluate a polynomial over the prime field

### Description
Evaluates a polynomial defined by `coefficients` (constant term first) at a given `value` using Horner's method, with all arithmetic performed modulo the 256-bit prime. This is the core operation used in `create` to compute each share's y-coordinate.

### Method
```python
util.evaluate_polynomial(coefficients, value)
```

### Parameters
- **coefficients** (list of int) - The coefficients of the polynomial, starting with the constant term.
- **value** (int) - The value at which to evaluate the polynomial.

### Request Example
```python
from SSSA import utils

util = utils()

# Polynomial: 42*x^2 + 21*x + 20, evaluated at x=0 → 20
result = util.evaluate_polynomial([20, 21, 42], 0)
assert result == 20

# Polynomial: 5*x^4 + 4*x^3 + 3*x^2 + 2*x + 1, evaluated at x=10 → 54321
result = util.evaluate_polynomial([1, 2, 3, 4, 5], 10)
assert result == 54321

# All arithmetic is mod prime
result = util.evaluate_polynomial([util.prime - 1, 1], 1)
assert result == 0  # (prime - 1 + 1) % prime == 0
```

### Response
- **result** (int) - The result of the polynomial evaluation modulo the prime.
```

--------------------------------

### Evaluate Polynomial using Horner's Method

Source: https://context7.com/sssaas/sssa-python/llms.txt

Evaluates a polynomial defined by coefficients at a given value using Horner's method. All arithmetic is performed modulo a 256-bit prime. This is a core operation for computing share y-coordinates.

```python
from SSSA import utils

util = utils()

# Polynomial: 42*x^2 + 21*x + 20, evaluated at x=0 → 20
result = util.evaluate_polynomial([20, 21, 42], 0)
assert result == 20

# Polynomial: 5*x^4 + 4*x^3 + 3*x^2 + 2*x + 1, evaluated at x=10 → 54321
result = util.evaluate_polynomial([1, 2, 3, 4, 5], 10)
assert result == 54321

# All arithmetic is mod prime
result = util.evaluate_polynomial([util.prime - 1, 1], 1)
assert result == 0  # (prime - 1 + 1) % prime == 0
```

--------------------------------

### Decode Field Integers to String with SSSA Utils

Source: https://context7.com/sssaas/sssa-python/llms.txt

The inverse of `split_ints`. Reconstructs the original string from a list of field integers. Handles trailing null bytes and edge cases.

```python
from SSSA import utils

util = utils()

# Reconstruct from integer chunks
integers = util.split_ints("secret data")
recovered = util.merge_ints(integers)
print(recovered)  # "secret data"

# Handles null bytes and edge cases
edge = "a" + "\x00" * 100 + "a"
assert util.merge_ints(util.split_ints(edge)) == edge
```

--------------------------------

### utils.merge_ints

Source: https://context7.com/sssaas/sssa-python/llms.txt

Decodes a list of field integers back into a string.

```APIDOC
## utils.merge_ints(secrets)

### Description
Inverse of `split_ints`. Takes a list of 256-bit integers and reconstructs the original string by converting each integer to a zero-padded 64-character hex string, concatenating them, decoding from hex to bytes, and stripping trailing null padding bytes.

### Parameters
#### Path Parameters
- **secrets** (list[int]) - Required - A list of integers to decode.

### Request Example
```python
from SSSA import utils

util = utils()
integers = util.split_ints("secret data")
recovered = util.merge_ints(integers)
```

### Response
#### Success Response (str)
- The reconstructed original string.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.