# SenseSpace DID Token Verification
[](https://badge.fury.io/py/sensespace-did)
[](https://pypi.org/project/sensespace-did/)
[](https://opensource.org/licenses/MIT)
A comprehensive Python library for verifying JWT tokens with Ed25519 signatures using SS58 addresses in the SenseSpace ecosystem. This library provides both standalone token verification and FastMCP integration for building secure, decentralized applications.
## Features
- 🔐 **Ed25519 JWT Verification**: Verify JWT tokens with EdDSA algorithm
- 🌐 **SS58 Address Support**: Native support for Substrate-style SS58 addresses
- 📄 **DID Document Resolution**: Optional DID document fetching and validation
- ⚡ **FastMCP Integration**: Built-in FastMCP TokenVerifier for server applications
- 🔧 **Flexible Configuration**: Customizable DID service endpoints
- 🛡️ **Security Focused**: Comprehensive error handling and validation
- 📦 **Easy Installation**: Simple pip installation with minimal dependencies
## Installation
```bash
pip install sensespace-did
```
## Quick Start
### Basic Token Verification
```python
from sensespace_did import verify_token
# Your JWT token
token = "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."
# Verify the token
result = await verify_token(token)
if result.success:
print("✅ Token verified successfully!")
print(f"Subject: {result.claims['sub']}")
print(f"Claims: {result.claims}")
else:
print(f"❌ Verification failed: {result.error}")
```
### With DID Document Fetching
```python
from sensespace_did import verify_token
# Verify token and fetch DID document
result = await verify_token(
token=token,
did_base_url="https://api.sensespace.xyz/api/did/" # Optional, this is the default
)
if result.success:
print(f"✅ Token verified: {result.claims}")
if result.did_document:
print(f"📄 DID Document: {result.did_document}")
```
### FastMCP Integration
```python
from fastmcp.server import FastMCPServer
from sensespace_did import SenseSpaceTokenVerifier
# Create FastMCP server with SenseSpace authentication
server = FastMCPServer(
token_verifier=SenseSpaceTokenVerifier(
did_base_url="https://api.sensespace.xyz/api/did/"
)
)
# Your server implementation...
```
## API Reference
### Core Functions
#### `verify_token(token, did_base_url=None)`
Verifies a JWT token with Ed25519 signature using SS58 address.
**Parameters:**
- `token` (str): The JWT token to verify
- `did_base_url` (str, optional): Base URL for DID API. Default: `"https://api.sensespace.xyz/api/did/"`
**Returns:**
`VerifyTokenResult` object containing:
- `success` (bool): Whether verification succeeded
- `claims` (dict): JWT claims (if successful)
- `error` (str): Error message (if verification failed)
- `did_document` (dict): DID document (if fetched successfully)
#### `generate_token(private_key)`
Generates a JWT token for a given private key.
**Parameters:**
- `private_key` (bytes|str): Ed25519 private key in bytes or hex/base58 string
**Returns:**
- `str`: JWT token string
### FastMCP Integration
#### `SenseSpaceTokenVerifier`
A specialized TokenVerifier for the SenseSpace ecosystem that can be used with FastMCP servers.
```python
from sensespace_did import SenseSpaceTokenVerifier
verifier = SenseSpaceTokenVerifier(
did_base_url="https://api.sensespace.xyz/api/did/"
)
# Use with FastMCP server
server = FastMCPServer(token_verifier=verifier)
```
## Advanced Usage
### Custom DID Service
```python
# Use a custom DID service URL
result = await verify_token(
token=token,
did_base_url="https://your-custom-did-service.com/api/did/"
)
```
### Error Handling
```python
from sensespace_did import verify_token
try:
result = await verify_token(token)
if result.success:
print("Token is valid")
print(f"Subject: {result.claims['sub']}")
print(f"Issued at: {result.claims['iat']}")
print(f"Expires at: {result.claims['exp']}")
else:
print(f"Token verification failed: {result.error}")
except Exception as e:
print(f"Unexpected error: {e}")
```
### Token Generation
```python
from sensespace_did import generate_token
import secrets
# Generate a random Ed25519 private key
private_key = secrets.token_bytes(32)
# Generate a JWT token
token = generate_token(private_key)
print(f"Generated token: {token}")
```
## Requirements
- **Python**: >= 3.10
- **PyJWT**: >= 2.8.0
- **cryptography**: >= 41.0.0
- **base58**: >= 2.1.1
- **httpx**: >= 0.25.0
- **fastmcp**: >= 2.11.0 (for FastMCP integration)
## Development
### Installation from Source
```bash
git clone https://github.com/verisense-network/sensespace-did.git
cd sensespace-did
pip install -e .
```
### Running Tests
```bash
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest
```
### Building and Publishing
```bash
# Build the package
python -m build
# Publish to PyPI
twine upload dist/*
```
## Security Considerations
- **Private Key Handling**: Never expose private keys in client-side code
- **Token Storage**: Store tokens securely and use HTTPS for transmission
- **DID Resolution**: Verify DID documents from trusted sources
- **Token Expiration**: Always check token expiration times
- **Algorithm Validation**: This library only accepts EdDSA algorithm tokens
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "sensespace-did",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "did, ed25519, jwt, sensespace, ss58, verification",
"author": null,
"author_email": "Shiotoli <shiotoli@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/71/ba/6b0b390cde628caf0e3eae3e96f4dfba3baca9f9fec5347c018bdfbef592/sensespace_did-0.1.0.tar.gz",
"platform": null,
"description": "# SenseSpace DID Token Verification\n\n[](https://badge.fury.io/py/sensespace-did)\n[](https://pypi.org/project/sensespace-did/)\n[](https://opensource.org/licenses/MIT)\n\nA comprehensive Python library for verifying JWT tokens with Ed25519 signatures using SS58 addresses in the SenseSpace ecosystem. This library provides both standalone token verification and FastMCP integration for building secure, decentralized applications.\n\n## Features\n\n- \ud83d\udd10 **Ed25519 JWT Verification**: Verify JWT tokens with EdDSA algorithm\n- \ud83c\udf10 **SS58 Address Support**: Native support for Substrate-style SS58 addresses\n- \ud83d\udcc4 **DID Document Resolution**: Optional DID document fetching and validation\n- \u26a1 **FastMCP Integration**: Built-in FastMCP TokenVerifier for server applications\n- \ud83d\udd27 **Flexible Configuration**: Customizable DID service endpoints\n- \ud83d\udee1\ufe0f **Security Focused**: Comprehensive error handling and validation\n- \ud83d\udce6 **Easy Installation**: Simple pip installation with minimal dependencies\n\n## Installation\n\n```bash\npip install sensespace-did\n```\n\n## Quick Start\n\n### Basic Token Verification\n\n```python\nfrom sensespace_did import verify_token\n\n# Your JWT token\ntoken = \"eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...\"\n\n# Verify the token\nresult = await verify_token(token)\n\nif result.success:\n print(\"\u2705 Token verified successfully!\")\n print(f\"Subject: {result.claims['sub']}\")\n print(f\"Claims: {result.claims}\")\nelse:\n print(f\"\u274c Verification failed: {result.error}\")\n```\n\n### With DID Document Fetching\n\n```python\nfrom sensespace_did import verify_token\n\n# Verify token and fetch DID document\nresult = await verify_token(\n token=token,\n did_base_url=\"https://api.sensespace.xyz/api/did/\" # Optional, this is the default\n)\n\nif result.success:\n print(f\"\u2705 Token verified: {result.claims}\")\n \n if result.did_document:\n print(f\"\ud83d\udcc4 DID Document: {result.did_document}\")\n```\n\n### FastMCP Integration\n\n```python\nfrom fastmcp.server import FastMCPServer\nfrom sensespace_did import SenseSpaceTokenVerifier\n\n# Create FastMCP server with SenseSpace authentication\nserver = FastMCPServer(\n token_verifier=SenseSpaceTokenVerifier(\n did_base_url=\"https://api.sensespace.xyz/api/did/\"\n )\n)\n\n# Your server implementation...\n```\n\n## API Reference\n\n### Core Functions\n\n#### `verify_token(token, did_base_url=None)`\n\nVerifies a JWT token with Ed25519 signature using SS58 address.\n\n**Parameters:**\n- `token` (str): The JWT token to verify\n- `did_base_url` (str, optional): Base URL for DID API. Default: `\"https://api.sensespace.xyz/api/did/\"`\n\n**Returns:**\n`VerifyTokenResult` object containing:\n- `success` (bool): Whether verification succeeded\n- `claims` (dict): JWT claims (if successful)\n- `error` (str): Error message (if verification failed)\n- `did_document` (dict): DID document (if fetched successfully)\n\n#### `generate_token(private_key)`\n\nGenerates a JWT token for a given private key.\n\n**Parameters:**\n- `private_key` (bytes|str): Ed25519 private key in bytes or hex/base58 string\n\n**Returns:**\n- `str`: JWT token string\n\n### FastMCP Integration\n\n#### `SenseSpaceTokenVerifier`\n\nA specialized TokenVerifier for the SenseSpace ecosystem that can be used with FastMCP servers.\n\n```python\nfrom sensespace_did import SenseSpaceTokenVerifier\n\nverifier = SenseSpaceTokenVerifier(\n did_base_url=\"https://api.sensespace.xyz/api/did/\"\n)\n\n# Use with FastMCP server\nserver = FastMCPServer(token_verifier=verifier)\n```\n\n## Advanced Usage\n\n### Custom DID Service\n\n```python\n# Use a custom DID service URL\nresult = await verify_token(\n token=token,\n did_base_url=\"https://your-custom-did-service.com/api/did/\"\n)\n```\n\n### Error Handling\n\n```python\nfrom sensespace_did import verify_token\n\ntry:\n result = await verify_token(token)\n \n if result.success:\n print(\"Token is valid\")\n print(f\"Subject: {result.claims['sub']}\")\n print(f\"Issued at: {result.claims['iat']}\")\n print(f\"Expires at: {result.claims['exp']}\")\n else:\n print(f\"Token verification failed: {result.error}\")\n \nexcept Exception as e:\n print(f\"Unexpected error: {e}\")\n```\n\n### Token Generation\n\n```python\nfrom sensespace_did import generate_token\nimport secrets\n\n# Generate a random Ed25519 private key\nprivate_key = secrets.token_bytes(32)\n\n# Generate a JWT token\ntoken = generate_token(private_key)\nprint(f\"Generated token: {token}\")\n```\n\n## Requirements\n\n- **Python**: >= 3.10\n- **PyJWT**: >= 2.8.0\n- **cryptography**: >= 41.0.0\n- **base58**: >= 2.1.1\n- **httpx**: >= 0.25.0\n- **fastmcp**: >= 2.11.0 (for FastMCP integration)\n\n## Development\n\n### Installation from Source\n\n```bash\ngit clone https://github.com/verisense-network/sensespace-did.git\ncd sensespace-did\npip install -e .\n```\n\n### Running Tests\n\n```bash\n# Install development dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest\n```\n\n### Building and Publishing\n\n```bash\n# Build the package\npython -m build\n\n# Publish to PyPI\ntwine upload dist/*\n```\n\n## Security Considerations\n\n- **Private Key Handling**: Never expose private keys in client-side code\n- **Token Storage**: Store tokens securely and use HTTPS for transmission\n- **DID Resolution**: Verify DID documents from trusted sources\n- **Token Expiration**: Always check token expiration times\n- **Algorithm Validation**: This library only accepts EdDSA algorithm tokens\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": null,
"summary": "SenseSpace DID token verification library",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/verisense-network/sensespace-did/issues",
"Homepage": "https://github.com/verisense-network/sensespace-did"
},
"split_keywords": [
"did",
" ed25519",
" jwt",
" sensespace",
" ss58",
" verification"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "98c29fc3bd9d01a2d4ca93cd1ba1068df16fd2564e6c0b86c880f869171572c3",
"md5": "495a006e72a7eac6e92ff114550924f2",
"sha256": "9614a9d28dab34087f1ec86324a6ae6ca9f96bfc7aea7c3958f9e449295d3c21"
},
"downloads": -1,
"filename": "sensespace_did-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "495a006e72a7eac6e92ff114550924f2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 8724,
"upload_time": "2025-08-27T12:18:15",
"upload_time_iso_8601": "2025-08-27T12:18:15.475567Z",
"url": "https://files.pythonhosted.org/packages/98/c2/9fc3bd9d01a2d4ca93cd1ba1068df16fd2564e6c0b86c880f869171572c3/sensespace_did-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "71ba6b0b390cde628caf0e3eae3e96f4dfba3baca9f9fec5347c018bdfbef592",
"md5": "a69891e11593c75465c54df13821af33",
"sha256": "d33bf2234cde6cf51d8e19b114097aeddf532cb68bc52bca9dbb0708049c231b"
},
"downloads": -1,
"filename": "sensespace_did-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "a69891e11593c75465c54df13821af33",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 84264,
"upload_time": "2025-08-27T12:18:17",
"upload_time_iso_8601": "2025-08-27T12:18:17.301526Z",
"url": "https://files.pythonhosted.org/packages/71/ba/6b0b390cde628caf0e3eae3e96f4dfba3baca9f9fec5347c018bdfbef592/sensespace_did-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-27 12:18:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "verisense-network",
"github_project": "sensespace-did",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "sensespace-did"
}
JSON
