{
  "markdown": "# Universal Bitcoin Identity Layer\n\n[![pytest](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/actions/workflows/pytest.yml/badge.svg?branch=main)](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/actions/workflows/pytest.yml)\n[![lint](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/actions/workflows/lint.yml)\n[![security](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/actions/workflows/security.yml/badge.svg?branch=main)](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/actions/workflows/security.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\nA production-focused Flask service that bridges OAuth2/OpenID Connect with Lightning Network authentication. The project couples hardened security defaults, Redis-backed rate limiting, RS256 JWT issuance, and Postgres persistence so Bitcoin-enabled applications can expose standards-compliant identity endpoints.\n\n---\n\n## 🚀 Highlights\n\n- **Security-first OAuth2/OIDC core** – RS256 tokens with on-disk JWKS rotation, PKCE validation, HTTPS enforcement through `app.security`, and Redis-powered rate limiting with production fail-closed behavior and explicit non-production in-memory fallback warnings.\n- **Lightning-aware identity workflows** – LNURL-auth challenge storage, Bitcoin signature verification helpers, and adapters that keep the legacy authorization views working while the storage layer matured.\n- **Persistent storage** – SQLAlchemy models for OAuth clients/codes/tokens, sessions, LNURL challenges, proof-of-funds requests, and audit logs backed by Postgres with Redis coordination for ephemeral state.\n- **Operational tooling** – `/metrics/prometheus` endpoint, structured JSON logging, and a reusable `create_app()` factory (`app/factory.py`) for factory-based deployments.\n- **Typed configuration surface** – Environment-driven configuration validated by `app.config`, including production guardrails for secrets, Redis, and database connectivity.\n\n---\n\n## 🏗️ Architecture at a Glance\n\n| Layer | Key Modules | Responsibilities |\n| --- | --- | --- |\n| Web application | [`app/app.py`](app/app.py), [`app/factory.py`](app/factory.py) | Flask application, OAuth2/LNURL routes, Prometheus metrics, Socket.IO events, plus the factory-based app initialization |\n| Security | [`app/security.py`](app/security.py) | Proxy/header fixes, HTTPS enforcement, Flask-Limiter setup, logging defaults |\n| Identity tokens | [`app/tokens.py`](app/tokens.py), [`app/jwks.py`](app/jwks.py) | RS256 JWT issuance, keypair persistence, JWKS publication |\n| Storage | [`app/db_storage.py`](app/db_storage.py), [`app/database.py`](app/database.py), [`app/storage.py`](app/storage.py) | Postgres session helpers, Redis utilities, and in-memory parity for tests |\n| Configuration | [`app/config.py`](app/config.py) | Typed env loader, production validation helpers |\n| Observability | [`app/app.py`](app/app.py), [`deployment/README.md`](deployment/README.md) | Prometheus counter wiring and deployment guidance |\n\nFurther documentation lives in the [`app/`](app/README.md) directory and supporting deployment guides under [`deployment/`](deployment/README.md).\n\n---\n\n## 🧰 Prerequisites\n\n- Python 3.10+\n- Postgres 13+\n- Redis 6+\n- Bitcoin Core 24+ (for RPC-backed features)\n\nFor local development you can omit Postgres/Redis by exporting `DATABASE_URL` and `REDIS_URL` pointing to ephemeral services (e.g. docker-compose) or by relying on the in-memory storage adapter for tests.\n\n---\n\n## 🏁 Quick Start\n\n```bash\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\nexport FLASK_APP=app.app:app\nexport FLASK_ENV=development\nexport RPC_USER=bitcoinrpc\nexport RPC_PASSWORD=change-me\nflask run\n```\n\nThe service exposes:\n\n- `/.well-known/openid-configuration`, `/oauth/token`, `/oauth/authorize`\n\nFor third-party login setup, see [Sign in with HODLXXI Integration Guide](docs/OIDC_INTEGRATION.md).\n\n- `/.well-known/agent.json`, `/agent/capabilities`, `/agent/capabilities/schema`\n- `/agent/skills`, `/agent/marketplace/listing`, `/agent/reputation`, `/agent/attestations`\n- `/lnurl/auth` LNURL challenge endpoints\n- `/metrics/prometheus` for Prometheus scrapers\n- `/health` basic liveness probe\n\n### Docker Compose quick start\n\nIf you want a production-like stack without installing Postgres/Redis/Bitcoin Core locally, use the bundled Compose file:\n\n```bash\ncp env.example .env\ndocker compose up --build\n```\n\nThe Postgres, Redis, and Bitcoin services wait for health checks before the Flask app starts. Mounts for `./app`, `./logs`, and `./keys` ensure code edits and generated keys persist on the host. See `docs/DEV_ONBOARDING_CHECKLIST.md` for the full onboarding flow and smoke tests.\n\nSee [`TESTING.md`](TESTING.md) for pytest, mypy, and linting guidance.\n\n---\n\n## ⚙️ Configuration Reference\n\n`app/config.py` documents every supported environment variable. Highlights include:\n\n- `JWT_ALGORITHM=RS256` to force asymmetric signing; JWKS files are stored in `JWKS_DIR`.\n- `RATE_LIMIT_ENABLED` / `RATE_LIMIT_DEFAULT` for limiter tuning.\n- `DATABASE_URL` or discrete `DB_*` variables for SQLAlchemy.\n- `REDIS_URL`/`REDIS_*` for rate limiting and challenge/session TTL handling.\n- `SOCKETIO_ASYNC_MODE` to pick a compatible backend (defaults to `eventlet` when available, otherwise falls back to `threading`).\n- `FORCE_HTTPS`, `SECURE_COOKIES`, and `CSRF_ENABLED` for deployment hardening.\n\nRun `python -m app.config` (or import `validate_config`) inside your deployment pipeline to fail fast on insecure production settings.\n\n---\n\n## 🧪 Testing\n\n```bash\npytest\n```\n\nUnit tests cover configuration parsing/validation along with storage adapters. Integration tests spin up the in-memory backend to exercise OAuth and LNURL flows without external services.\n\n---\n\n## Product Positioning\n\n- [Runtime Product Positioning](docs/RUNTIME_PRODUCT_POSITIONING.md) - current product framing: HODLXXI as a Bitcoin-native trust runtime for public-key agents and services.\n\n## Agent Readiness\n\n- [HODLXXI Readiness Evaluation](docs/READINESS_EVALUATION.md) - current external evaluation path for public agent/runtime readiness.\n- [HODLXXI External Reviewer Packet](docs/EXTERNAL_REVIEWER_PACKET.md) - canonical public review packet for live reviewers, developers, investors, agent marketplace reviewers, and technical evaluators.\n- [Agent Readiness Report v1](docs/AGENT_READINESS_REPORT_V1.md) - contract for public agent/service readiness reports backed by receipts and attestations.\n- `GET /agent/readiness/self-scan` - public machine-readable self-scan report for the current HODLXXI runtime. It returns `schema`, `summary`, `checks`, `verification`, `report_sha256`, and current `receipt` / `attestation` status.\n\n## Developer Quickstarts\n\n- [Agent Receipt Quickstart](docs/AGENT_RECEIPT_QUICKSTART.md) — external developer flow: discovery, paid job request, polling, receipt verification, attestations, and reputation.\n\n## 🤖 Agent, Skills, and Marketplace Discovery\n\nThe repository now exposes a coherent machine-readable agent surface:\n\n- `/.well-known/agent.json` for the public identity/discovery document\n- `/agent/capabilities` for the signed capabilities handshake\n- `/agent/capabilities/schema` for the canonical JSON Schema of that handshake\n- `/agent/skills` for first-class skill discovery sourced from `skills/public/`\n- `/agent/marketplace/listing` for normalized directory/marketplace ingestion\n\nFor the protocol and trust model, see:\n\n- [`docs/DOCUMENTATION_MAP.md`](docs/DOCUMENTATION_MAP.md) explains which docs are current, historical, experimental, or archive candidates.\n- [`AGENT_PROTOCOL.md`](AGENT_PROTOCOL.md) for the signed discovery and job protocol\n- [`TRUST_MODEL.md`](TRUST_MODEL.md) for the normative trust language and verification boundaries\n- [`docs/AGENT_SURFACES.md`](docs/AGENT_SURFACES.md) for how the runtime discovery endpoints expose those claims\n\nThe current agent surface is intentionally conservative: it exposes public-key identity, declared operator metadata, paid execution, signed receipts, and observable history, while treating time-locked capital and on-chain backing as optional trust anchors rather than verified runtime facts.\n\n\n### Python SDK for agents\n\nDevelopers can start from the SDK index:\n\n- `docs/sdk/README.md`\n\nThe SDK covers:\n\n- public discovery and agent job requests\n- Bitcoin-message auth challenge flow\n- Nostr auth challenge flow\n- receipt helpers\n- signing helpers with caller-provided signers\n\nExamples:\n\n- `examples/python/ping_agent.py`\n- `examples/python/auth_challenge_flow.py`\n- `examples/python/nostr_auth_challenge_flow.py`\n\nThe SDK does not hold private keys. Applications bring their own wallet, hardware, Bitcoin Core, Nostr, or agent-runtime signer.\n\n---\n\n## 🤝 Contributing\n\n1. Fork the repository and create a virtual environment.\n2. Install dev dependencies with `pip install -r requirements-dev.txt`.\n3. Run `pytest` before opening a pull request.\n4. Follow the [code of conduct](CODE_OF_CONDUCT.md) and [contribution guidelines](CONTRIBUTING.md).\n\nBug reports and feature proposals are welcome via [GitHub Issues](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/issues).\n\n---\n\n## 📄 License\n\nReleased under the [MIT License](LICENSE).\n\n### Production readiness artifact storage\n\nPersisted readiness self-scan reports are runtime artifacts, not source files.\nFor hardened production deployments, set:\n\n```text\nAGENT_READINESS_REPORT_DIR=/srv/ubid/runtime/agent_readiness_reports\n```\n\nFor `hodlxxi.service`, this path should live under the writable runtime area and be owned by the service user.\n",
  "bytes": 10010,
  "sha": "f27bd5a797945848e6b453a5751e919b7a7cbdbba15df0ec68f1cf82043a0e56",
  "repo_slug": "hodlxxi/universal-bitcoin-identity-layer",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_hodlxxi_hodlxxi_readonly_be7f60c6/readme"
}