arkhai-core-registry 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (27) hide show
  1. arkhai_core_registry-0.1.0/PKG-INFO +19 -0
  2. arkhai_core_registry-0.1.0/README.md +89 -0
  3. arkhai_core_registry-0.1.0/pyproject.toml +49 -0
  4. arkhai_core_registry-0.1.0/setup.cfg +4 -0
  5. arkhai_core_registry-0.1.0/src/api/__init__.py +4 -0
  6. arkhai_core_registry-0.1.0/src/api/admin_routes.py +91 -0
  7. arkhai_core_registry-0.1.0/src/api/api_key_auth.py +153 -0
  8. arkhai_core_registry-0.1.0/src/api/filter_eval.py +414 -0
  9. arkhai_core_registry-0.1.0/src/api/filter_spec.py +193 -0
  10. arkhai_core_registry-0.1.0/src/api/listing_routes.py +280 -0
  11. arkhai_core_registry-0.1.0/src/api/publisher_routes.py +67 -0
  12. arkhai_core_registry-0.1.0/src/api/routes.py +34 -0
  13. arkhai_core_registry-0.1.0/src/api/system_model.py +32 -0
  14. arkhai_core_registry-0.1.0/src/api/system_routes.py +115 -0
  15. arkhai_core_registry-0.1.0/src/api/utils.py +200 -0
  16. arkhai_core_registry-0.1.0/src/api/validate_model.py +52 -0
  17. arkhai_core_registry-0.1.0/src/api/validate_routes.py +105 -0
  18. arkhai_core_registry-0.1.0/src/arkhai_core_registry.egg-info/PKG-INFO +19 -0
  19. arkhai_core_registry-0.1.0/src/arkhai_core_registry.egg-info/SOURCES.txt +25 -0
  20. arkhai_core_registry-0.1.0/src/arkhai_core_registry.egg-info/dependency_links.txt +1 -0
  21. arkhai_core_registry-0.1.0/src/arkhai_core_registry.egg-info/requires.txt +14 -0
  22. arkhai_core_registry-0.1.0/src/arkhai_core_registry.egg-info/top_level.txt +4 -0
  23. arkhai_core_registry-0.1.0/src/db/__init__.py +4 -0
  24. arkhai_core_registry-0.1.0/src/db/database.py +81 -0
  25. arkhai_core_registry-0.1.0/src/db/models.py +119 -0
  26. arkhai_core_registry-0.1.0/src/services/__init__.py +0 -0
  27. arkhai_core_registry-0.1.0/src/types/__init__.py +14 -0
@@ -0,0 +1,19 @@
1
+ Metadata-Version: 2.4
2
+ Name: arkhai-core-registry
3
+ Version: 0.1.0
4
+ Summary: Listing discovery/index service (registry role)
5
+ Requires-Python: >=3.12
6
+ Requires-Dist: fastapi>=0.104.0
7
+ Requires-Dist: uvicorn[standard]>=0.24.0
8
+ Requires-Dist: sqlalchemy>=2.0.0
9
+ Requires-Dist: alembic>=1.12.0
10
+ Requires-Dist: psycopg2-binary>=2.9.9
11
+ Requires-Dist: pydantic>=2.0.0
12
+ Requires-Dist: pydantic-settings>=2.0.0
13
+ Requires-Dist: eth-account>=0.9.0
14
+ Requires-Dist: python-dotenv>=1.0.0
15
+ Requires-Dist: aiohttp>=3.9.0
16
+ Requires-Dist: pyyaml>=6.0
17
+ Requires-Dist: jsonschema>=4.20
18
+ Requires-Dist: jsonpath-ng>=1.6
19
+ Requires-Dist: arkhai-kit-identity
@@ -0,0 +1,89 @@
1
+ # Registry Indexer
2
+
3
+ FastAPI service that stores published marketplace listings and serves
4
+ them through a filter-spec-driven discovery API. Sellers publish via
5
+ signed `POST /agents/{wallet}/listings`; buyers query `GET /listings`.
6
+
7
+ After the pluggable-identity refactor the registry doesn't read any
8
+ on-chain contracts. Agent rows are created lazily on first signed
9
+ publication — signature recovery is the trust anchor.
10
+
11
+ ## Features
12
+
13
+ - `GET /listings` with filter-spec-driven discovery (filters declared
14
+ in `filter-spec.yaml`; ETag-gated invalidation).
15
+ - `POST /agents/{wallet}/listings` lazy-creates agent rows on first
16
+ signed publication.
17
+ - Scheme-tagged identity storage: `(scheme, identifier)` is the canonical
18
+ agent key. `eip191` (wallet address) is the only built-in scheme.
19
+ - Optional API-key auth, gated independently for read and write
20
+ (`REGISTRY_REQUIRE_READ_API_KEY`, `REGISTRY_REQUIRE_WRITE_API_KEY`);
21
+ keys carry a read/write scope.
22
+
23
+ ## Quick start (local docker-compose)
24
+
25
+ ```bash
26
+ # From repo root — brings up anvil (contracts pre-baked), registry, both
27
+ # storefronts and provisioning.
28
+ docker compose up -d
29
+
30
+ # Direct registry probe (no API key required by default):
31
+ curl http://localhost:8080/health
32
+ curl http://localhost:8080/agents
33
+ curl 'http://localhost:8080/listings?limit=10'
34
+ ```
35
+
36
+ ## Running standalone
37
+
38
+ ```bash
39
+ cd core/registry
40
+ uv sync
41
+ DATABASE_URL=sqlite:///./indexer.db uv run uvicorn src.main:app --port 8080
42
+ ```
43
+
44
+ ## API key auth
45
+
46
+ Read access (discovery, lookups) and write access (publish/update/delete
47
+ listings, heartbeat) gate independently via `REGISTRY_REQUIRE_READ_API_KEY`
48
+ and `REGISTRY_REQUIRE_WRITE_API_KEY`. When a gate is on, the matching
49
+ routes require `Authorization: Bearer <key>` against an active row in
50
+ `api_keys`; write routes additionally require the key's scope to be
51
+ `write` (a write key also satisfies reads). Operators mint keys via
52
+ `POST /admin/api-keys` (gated by `REGISTRY_ADMIN_API_KEY`), passing
53
+ `scope: read|write`; a single write-scoped bootstrap key can be seeded
54
+ via `REGISTRY_BOOTSTRAP_API_KEY` on first start.
55
+
56
+ ## Database
57
+
58
+ - Dev: SQLite (`DATABASE_URL=sqlite:///./indexer.db`)
59
+ - Production: Postgres (`DATABASE_URL=postgresql://...`)
60
+
61
+ Schema is managed by Alembic. Apply migrations with `make migrate`.
62
+
63
+ ## API endpoints
64
+
65
+ Service documentation is served at `/docs` (Swagger UI). The interesting
66
+ endpoints:
67
+
68
+ - `GET /health`
69
+ - `GET /agents` / `GET /agents/{agent_id}` / `GET /agents/search`
70
+ - `POST /agents/{wallet}/listings` (signed)
71
+ - `GET /agents/{wallet}/listings`
72
+ - `GET /listings` (filter-spec-driven discovery)
73
+ - `PUT /listings/{listing_id}` (signed)
74
+ - `DELETE /listings/{listing_id}` (signed)
75
+ - `GET /filter-spec` (returns the active filter spec + ETag)
76
+ - `POST /admin/api-keys` (admin)
77
+ - `GET /api/v1/system/config`
78
+ - `GET /api/v1/system/stats`
79
+
80
+ ## Identity format
81
+
82
+ Agents are keyed on `(scheme, identifier)`. The default and only
83
+ built-in scheme is `eip191` with the lowercase wallet address as
84
+ identifier. Legacy ERC-8004 canonical agent IDs (`eip155:...`) still
85
+ resolve via a back-compat lookup on the deprecated `agents.agent_id`
86
+ column for rows that pre-date the migration.
87
+
88
+ Custom schemes can register via
89
+ `market_identity.register_identity_scheme(verifier)` in a fork.
@@ -0,0 +1,49 @@
1
+ [project]
2
+ name = "arkhai-core-registry"
3
+ version = "0.1.0"
4
+ description = "Listing discovery/index service (registry role)"
5
+ requires-python = ">=3.12"
6
+ dependencies = [
7
+ "fastapi>=0.104.0",
8
+ "uvicorn[standard]>=0.24.0",
9
+ "sqlalchemy>=2.0.0",
10
+ "alembic>=1.12.0",
11
+ "psycopg2-binary>=2.9.9",
12
+ "pydantic>=2.0.0",
13
+ "pydantic-settings>=2.0.0",
14
+ "eth-account>=0.9.0",
15
+ "python-dotenv>=1.0.0",
16
+ "aiohttp>=3.9.0",
17
+ "pyyaml>=6.0",
18
+ "jsonschema>=4.20",
19
+ "jsonpath-ng>=1.6",
20
+ "arkhai-kit-identity",
21
+ ]
22
+
23
+ [tool.uv.sources]
24
+ arkhai-kit-identity = { path = "../../kit/identity", editable = true }
25
+
26
+ [tool.setuptools]
27
+ package-dir = {"" = "src"}
28
+
29
+ [tool.setuptools.packages.find]
30
+ where = ["src"]
31
+
32
+ [build-system]
33
+ requires = ["setuptools>=68", "wheel"]
34
+ build-backend = "setuptools.build_meta"
35
+
36
+ [dependency-groups]
37
+ dev = [
38
+ "pytest>=7.4.0",
39
+ "pytest-asyncio>=0.21.0",
40
+ "httpx>=0.27.0",
41
+ "arkhai-core-registry-client>=0.6.0",
42
+ "black>=23.11.0",
43
+ "ruff>=0.1.6",
44
+ ]
45
+
46
+ [tool.pytest.ini_options]
47
+ testpaths = ["tests"]
48
+ asyncio_mode = "auto"
49
+ addopts = ["--tb=short", "-v"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,4 @@
1
+ from src.api.routes import router
2
+
3
+ __all__ = ["router"]
4
+
@@ -0,0 +1,91 @@
1
+ """Admin endpoints for issuing and revoking API keys.
2
+
3
+ Every endpoint here is gated by ``require_admin_api_key`` — operators
4
+ authenticate with the single shared ``REGISTRY_ADMIN_API_KEY`` env
5
+ var rather than a key from the ``api_keys`` table. This keeps the
6
+ mint-flow bootstrappable: there is no chicken-and-egg with key #1.
7
+
8
+ Issuance returns the raw secret exactly once at creation time. The
9
+ DB only stores the sha256 hash; the registry cannot recover the raw
10
+ value if the operator loses it. Lost key → revoke + mint a fresh one.
11
+ """
12
+ from __future__ import annotations
13
+
14
+ from typing import List, Literal, Optional
15
+
16
+ from fastapi import APIRouter, Depends, HTTPException
17
+ from pydantic import BaseModel, Field
18
+ from sqlalchemy.orm import Session
19
+
20
+ from src.api.api_key_auth import (
21
+ mint_api_key, revoke_api_key, require_admin_api_key,
22
+ )
23
+ from src.db.database import get_db
24
+ from src.db.models import ApiKey
25
+
26
+ router = APIRouter(
27
+ prefix="/admin/api-keys",
28
+ tags=["admin"],
29
+ dependencies=[Depends(require_admin_api_key)],
30
+ )
31
+
32
+
33
+ class CreateApiKeyRequest(BaseModel):
34
+ name: str = Field(..., min_length=1, max_length=128, description="Human-readable label")
35
+ scope: Literal["read", "write"] = Field(
36
+ "read",
37
+ description="'read' (discovery/lookups) or 'write' (publish/update/delete + heartbeat). Write implies read. Defaults to read (least privilege).",
38
+ )
39
+
40
+
41
+ class CreateApiKeyResponse(BaseModel):
42
+ id: int
43
+ name: str
44
+ scope: str
45
+ key: str = Field(..., description="Raw bearer token — store this now; the registry retains only its hash")
46
+ created_at: str
47
+
48
+
49
+ class ApiKeyListItem(BaseModel):
50
+ id: int
51
+ name: str
52
+ scope: str
53
+ created_at: str
54
+ revoked_at: Optional[str] = None
55
+
56
+
57
+ @router.post("", response_model=CreateApiKeyResponse, status_code=201)
58
+ def create_api_key(
59
+ body: CreateApiKeyRequest, db: Session = Depends(get_db),
60
+ ) -> CreateApiKeyResponse:
61
+ """Mint a new key. The response includes the raw token; the
62
+ operator must capture it now — the registry never returns it
63
+ again."""
64
+ raw, row = mint_api_key(db, name=body.name.strip(), scope=body.scope)
65
+ return CreateApiKeyResponse(
66
+ id=row.id, name=row.name, scope=row.scope, key=raw,
67
+ created_at=row.created_at.isoformat(),
68
+ )
69
+
70
+
71
+ @router.get("", response_model=List[ApiKeyListItem])
72
+ def list_api_keys(db: Session = Depends(get_db)) -> List[ApiKeyListItem]:
73
+ """List every key (including revoked) for audit. Raw values are
74
+ not stored and therefore not returned."""
75
+ rows = db.query(ApiKey).order_by(ApiKey.created_at.desc()).all()
76
+ return [
77
+ ApiKeyListItem(
78
+ id=r.id, name=r.name, scope=r.scope,
79
+ created_at=r.created_at.isoformat(),
80
+ revoked_at=r.revoked_at.isoformat() if r.revoked_at else None,
81
+ )
82
+ for r in rows
83
+ ]
84
+
85
+
86
+ @router.delete("/{key_id}", status_code=204)
87
+ def revoke(key_id: int, db: Session = Depends(get_db)) -> None:
88
+ """Mark a key revoked. Idempotent on already-revoked keys; 404
89
+ when the id is unknown."""
90
+ if not revoke_api_key(db, key_id=key_id):
91
+ raise HTTPException(status_code=404, detail=f"API key {key_id} not found")
@@ -0,0 +1,153 @@
1
+ """API key issuance, verification, and revocation for private registries.
2
+
3
+ Access is gated independently per direction. When
4
+ ``settings.require_read_api_key`` is True, read routes (discovery,
5
+ lookups, system diagnostics) require ``Authorization: Bearer <key>``
6
+ matching a non-revoked row. When ``settings.require_write_api_key`` is
7
+ True, write routes (publish / update / delete listings, heartbeat)
8
+ require such a key carrying ``write`` scope. A write key satisfies read
9
+ routes too. Operators mint and revoke keys via the ``/admin/api-keys``
10
+ routes, themselves gated by the ``REGISTRY_ADMIN_API_KEY`` env var (a
11
+ single shared secret distinct from the api_keys table).
12
+
13
+ Storage model: only ``sha256(raw_key)`` is persisted; the raw key is
14
+ returned to the operator exactly once at mint time. A DB leak
15
+ exposes hashes, not live credentials. Revocation sets ``revoked_at``
16
+ rather than deleting the row, preserving audit history.
17
+ """
18
+ from __future__ import annotations
19
+
20
+ import hashlib
21
+ import logging
22
+ import secrets
23
+ from datetime import datetime, timezone
24
+ from typing import Literal
25
+
26
+ from fastapi import Depends, HTTPException, Request
27
+ from sqlalchemy.orm import Session
28
+
29
+ from src.config import settings
30
+ from src.db.database import get_db
31
+ from src.db.models import ApiKey
32
+
33
+ logger = logging.getLogger(__name__)
34
+
35
+ Scope = Literal["read", "write"]
36
+
37
+
38
+ def _hash_key(raw: str) -> str:
39
+ return hashlib.sha256(raw.encode("utf-8")).hexdigest()
40
+
41
+
42
+ def mint_api_key(db: Session, *, name: str, scope: Scope = "read") -> tuple[str, ApiKey]:
43
+ """Generate a fresh secret, store its hash, return both raw value
44
+ and persisted row. The raw value is the operator's only chance to
45
+ capture the key — emit it to the API response and never log it.
46
+
47
+ ``scope`` defaults to ``read`` (least privilege); pass ``write`` for
48
+ seller credentials that publish/update/delete listings.
49
+ """
50
+ raw = secrets.token_urlsafe(32) # ~256 bits of entropy
51
+ row = ApiKey(
52
+ name=name,
53
+ key_hash=_hash_key(raw),
54
+ scope=scope,
55
+ created_at=datetime.now(timezone.utc),
56
+ )
57
+ db.add(row)
58
+ db.commit()
59
+ db.refresh(row)
60
+ logger.info("[API_KEY] minted key id=%s name=%s scope=%s", row.id, name, scope)
61
+ return raw, row
62
+
63
+
64
+ def revoke_api_key(db: Session, *, key_id: int) -> bool:
65
+ """Mark a key revoked. Idempotent — already-revoked keys are
66
+ left unchanged. Returns True iff the key existed."""
67
+ row = db.query(ApiKey).filter(ApiKey.id == key_id).one_or_none()
68
+ if row is None:
69
+ return False
70
+ if row.revoked_at is None:
71
+ row.revoked_at = datetime.now(timezone.utc)
72
+ db.commit()
73
+ logger.info("[API_KEY] revoked key id=%s name=%s", row.id, row.name)
74
+ return True
75
+
76
+
77
+ def verify_api_key(db: Session, raw: str) -> ApiKey | None:
78
+ """Look up a key by its hash. Returns the row when active and
79
+ not revoked, ``None`` otherwise. Constant-time hash comparison
80
+ is provided implicitly by indexing the unique hash column."""
81
+ row = (
82
+ db.query(ApiKey)
83
+ .filter(ApiKey.key_hash == _hash_key(raw))
84
+ .filter(ApiKey.revoked_at.is_(None))
85
+ .one_or_none()
86
+ )
87
+ return row
88
+
89
+
90
+ # ---------------------------------------------------------------------------
91
+ # FastAPI dependencies
92
+ # ---------------------------------------------------------------------------
93
+
94
+ def require_admin_api_key(request: Request) -> None:
95
+ """Dependency for /admin/* routes. 401s when ``REGISTRY_ADMIN_API_KEY``
96
+ isn't set on the server, OR when the request's
97
+ ``Authorization: Bearer <key>`` doesn't match it.
98
+
99
+ The admin key is a single shared secret deliberately — operators
100
+ are expected to store it out-of-band (env var, secret manager).
101
+ No DB row, no minting flow.
102
+ """
103
+ if not settings.admin_api_key:
104
+ raise HTTPException(
105
+ status_code=401,
106
+ detail="Admin endpoints disabled — REGISTRY_ADMIN_API_KEY not set",
107
+ )
108
+ auth = request.headers.get("Authorization", "")
109
+ if not auth.startswith("Bearer "):
110
+ raise HTTPException(status_code=401, detail="Admin bearer token required")
111
+ candidate = auth.removeprefix("Bearer ").strip()
112
+ if not secrets.compare_digest(candidate, settings.admin_api_key):
113
+ raise HTTPException(status_code=401, detail="Invalid admin token")
114
+
115
+
116
+ def _verify_bearer(request: Request, db: Session) -> ApiKey:
117
+ """Pull ``Authorization: Bearer <key>`` and resolve it to an active
118
+ row, or 401. Shared by the read and write gates."""
119
+ auth = request.headers.get("Authorization", "")
120
+ if not auth.startswith("Bearer "):
121
+ raise HTTPException(status_code=401, detail="API key required")
122
+ raw = auth.removeprefix("Bearer ").strip()
123
+ row = verify_api_key(db, raw) if raw else None
124
+ if row is None:
125
+ raise HTTPException(status_code=401, detail="Invalid or revoked API key")
126
+ return row
127
+
128
+
129
+ def require_read_access(
130
+ request: Request, db: Session = Depends(get_db),
131
+ ) -> None:
132
+ """Dependency for read routes. No-op when
133
+ ``settings.require_read_api_key`` is False (public discovery);
134
+ otherwise any active key (read or write scope) is accepted."""
135
+ if not settings.require_read_api_key:
136
+ return
137
+ _verify_bearer(request, db)
138
+
139
+
140
+ def require_write_access(
141
+ request: Request, db: Session = Depends(get_db),
142
+ ) -> None:
143
+ """Dependency for write routes. No-op when
144
+ ``settings.require_write_api_key`` is False (open publishing);
145
+ otherwise requires an active key carrying ``write`` scope. Note the
146
+ per-write signature checks still apply on top of this gate."""
147
+ if not settings.require_write_api_key:
148
+ return
149
+ row = _verify_bearer(request, db)
150
+ if row.scope != "write":
151
+ raise HTTPException(
152
+ status_code=403, detail="Write access requires a write-scoped API key"
153
+ )