{"id":20365990,"url":"https://github.com/altcha-org/altcha-lib-py","last_synced_at":"2025-06-12T20:32:59.089Z","repository":{"id":250311943,"uuid":"834121334","full_name":"altcha-org/altcha-lib-py","owner":"altcha-org","description":"A lightweight Python library for creating and verifying ALTCHA challenges.","archived":false,"fork":false,"pushed_at":"2025-06-07T11:43:29.000Z","size":47,"stargazers_count":14,"open_issues_count":1,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-12T20:32:01.784Z","etag":null,"topics":["altcha","python"],"latest_commit_sha":null,"homepage":"https://altcha.org/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/altcha-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-07-26T13:14:19.000Z","updated_at":"2025-06-07T11:43:28.000Z","dependencies_parsed_at":"2024-07-26T13:47:06.875Z","dependency_job_id":"4a5e8abe-c89a-4fe1-acf1-7bd9eff6d7b8","html_url":"https://github.com/altcha-org/altcha-lib-py","commit_stats":null,"previous_names":["altcha-org/altcha-lib-py"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/altcha-org/altcha-lib-py","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/altcha-org%2Faltcha-lib-py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/altcha-org%2Faltcha-lib-py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/altcha-org%2Faltcha-lib-py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/altcha-org%2Faltcha-lib-py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/altcha-org","download_url":"https://codeload.github.com/altcha-org/altcha-lib-py/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/altcha-org%2Faltcha-lib-py/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259522453,"owners_count":22870469,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["altcha","python"],"created_at":"2024-11-15T00:21:43.344Z","updated_at":"2025-06-12T20:32:59.044Z","avatar_url":"https://github.com/altcha-org.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ALTCHA Python Library\n\nThe ALTCHA Python Library is a lightweight, zero-dependency library designed for creating and verifying [ALTCHA](https://altcha.org) challenges, specifically tailored for Python applications.\n\n## Compatibility\n\nThis library is compatible with:\n\n- Python 3.9+\n\n## Example\n\n- [Demo server](https://github.com/altcha-org/altcha-starter-py)\n\n## Installation\n\nTo install the ALTCHA Python Library, use the following command:\n\n```sh\npip install altcha\n```\n\n## Build\n\n```sh\npython -m build\n```\n\n## Tests\n\n```sh\npython -m unittest discover tests\n```\n\n## Usage\n\nHere’s a basic example of how to use the ALTCHA Python Library:\n\n```python\nimport datetime\nfrom altcha import ChallengeOptions, create_challenge, verify_solution\n\ndef main():\n    hmac_key = \"secret hmac key\"\n\n    # Create a new challenge\n    options = ChallengeOptions(\n        expires=datetime.datetime.now() + datetime.timedelta(hours=1),\n        max_number=100000, # The maximum random number\n        hmac_key=hmac_key,\n    )\n    challenge = create_challenge(options)\n    print(\"Challenge created:\", challenge)\n\n    # Example payload to verify\n    payload = {\n        \"algorithm\": challenge.algorithm,\n        \"challenge\": challenge.challenge,\n        \"number\": 12345,  # Example number\n        \"salt\": challenge.salt,\n        \"signature\": challenge.signature,\n    }\n\n    # Verify the solution\n    ok, err = verify_solution(payload, hmac_key, check_expires=True)\n    if err:\n        print(\"Error:\", err)\n    elif ok:\n        print(\"Solution verified!\")\n    else:\n        print(\"Invalid solution.\")\n\nif __name__ == \"__main__\":\n    main()\n```\n\n## API\n\n### `create_challenge(options)`\n\nCreates a new challenge for ALTCHA.\n\n**Parameters:**\n\n- `options (dict)`:\n  - `algorithm (str)`: Hashing algorithm to use (`'SHA-1'`, `'SHA-256'`, `'SHA-512'`, default: `'SHA-256'`).\n  - `max_number (int)`: Maximum number for the random number generator (default: 1,000,000).\n  - `salt_length (int)`: Length of the random salt in bytes (default: 12).\n  - `hmac_key (str)`: Required HMAC key.\n  - `salt (str)`: Optional salt string. If not provided, a random salt will be generated.\n  - `number (int)`: Optional specific number to use. If not provided, a random number will be generated.\n  - `expires (datetime)`: Optional expiration time for the challenge.\n  - `params (dict)`: Optional URL-encoded query parameters.\n\n**Returns:** `Challenge`\n\n### `verify_solution(payload, hmac_key, check_expires)`\n\nVerifies an ALTCHA solution.\n\n**Parameters:**\n\n- `payload (dict)`: The solution payload to verify.\n- `hmac_key (str)`: The HMAC key used for verification.\n- `check_expires (bool)`: Indicates whether to validate the challenge's expiration. If set to True, the function checks the expires field within the salt (if present) to ensure the challenge has not expired.\n(Note: To use this feature, the expires parameter must be included when creating the challenge.)\n\n**Returns:** `(bool, str or None)`\n\n### `extract_params(payload)`\n\nExtracts URL parameters from the payload's salt.\n\n**Parameters:**\n\n- `payload (dict)`: The payload containing the salt.\n\n**Returns:** `dict`\n\n### `verify_fields_hash(form_data, fields, fields_hash, algorithm)`\n\nVerifies the hash of form fields.\n\n**Parameters:**\n\n- `form_data (dict)`: The form data to hash.\n- `fields (list)`: The fields to include in the hash.\n- `fields_hash (str)`: The expected hash value.\n- `algorithm (str)`: Hashing algorithm (`'SHA-1'`, `'SHA-256'`, `'SHA-512'`).\n\n**Returns:** `bool`\n\n### `verify_server_signature(payload, hmac_key)`\n\nVerifies the server signature.\n\n**Parameters:**\n\n- `payload (dict or str)`: The payload to verify (base64 encoded JSON string or dictionary).\n- `hmac_key (str)`: The HMAC key used for verification.\n\n**Returns:** `(bool, ServerSignatureVerificationData, str or None)`\n\n### `solve_challenge(challenge, salt, algorithm, max_number, start, stop_chan)`\n\nFinds a solution to the given challenge.\n\n**Parameters:**\n\n- `challenge (str)`: The challenge hash.\n- `salt (str)`: The challenge salt.\n- `algorithm (str)`: Hashing algorithm (`'SHA-1'`, `'SHA-256'`, `'SHA-512'`).\n- `max_number (int)`: Maximum number to iterate to.\n- `start (int)`: Starting number.\n\n**Returns:** `Solution or None`\n\n## License\n\nMIT","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faltcha-org%2Faltcha-lib-py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faltcha-org%2Faltcha-lib-py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faltcha-org%2Faltcha-lib-py/lists"}