rare-identity-protocol 0.1.0__tar.gz

rare_identity_protocol-0.1.0/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: rare-identity-protocol
+Version: 0.1.0
+Summary: Rare identity protocol primitives and signing helpers
+Project-URL: Homepage, https://api.rareid.cc
+Project-URL: Repository, https://github.com/0xsidfan/Rare
+Project-URL: Documentation, https://github.com/0xsidfan/Rare/tree/main/rare-identity-protocol-python
+Project-URL: Issues, https://github.com/0xsidfan/Rare/issues
+Keywords: rare,identity,protocol,ed25519,jws
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=42.0.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.2.0; extra == "test"
+
+# rare-identity-protocol-python
+
+Rare 的协议层 Python 包，提供：
+
+- 固定 signing input 构造
+- Ed25519 / JWS 签名与验签辅助
+- name normalization / validation
+- expiring map / set 等基础安全数据结构
+
+## Install
+
+```bash
+pip install rare-identity-protocol
+```
+
+本地工作区开发：
+
+```bash
+pip install -e .[test]
+```

rare_identity_protocol-0.1.0/README.md

@@ -0,0 +1,20 @@
+# rare-identity-protocol-python
+
+Rare 的协议层 Python 包，提供：
+
+- 固定 signing input 构造
+- Ed25519 / JWS 签名与验签辅助
+- name normalization / validation
+- expiring map / set 等基础安全数据结构
+
+## Install
+
+```bash
+pip install rare-identity-protocol
+```
+
+本地工作区开发：
+
+```bash
+pip install -e .[test]
+```

rare_identity_protocol-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rare-identity-protocol"
+version = "0.1.0"
+description = "Rare identity protocol primitives and signing helpers"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+  "cryptography>=42.0.0",
+]
+keywords = ["rare", "identity", "protocol", "ed25519", "jws"]
+
+[project.optional-dependencies]
+test = [
+  "pytest>=8.2.0",
+]
+
+[project.urls]
+Homepage = "https://api.rareid.cc"
+Repository = "https://github.com/0xsidfan/Rare"
+Documentation = "https://github.com/0xsidfan/Rare/tree/main/rare-identity-protocol-python"
+Issues = "https://github.com/0xsidfan/Rare/issues"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["rare_identity_protocol*"]

rare_identity_protocol-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

rare_identity_protocol-0.1.0/src/rare_identity_protocol/__init__.py

@@ -0,0 +1,75 @@
+from rare_identity_protocol.actions import build_action_payload
+from rare_identity_protocol.challenge import (
+    build_auth_challenge_payload,
+    build_full_attestation_issue_payload,
+    build_agent_auth_payload,
+    build_register_payload,
+    build_set_name_payload,
+    build_upgrade_request_payload,
+)
+from rare_identity_protocol.crypto import (
+    b64url_decode,
+    b64url_encode,
+    decode_jws,
+    generate_ed25519_keypair,
+    generate_nonce,
+    json_dumps_compact,
+    load_private_key,
+    load_public_key,
+    now_ts,
+    public_key_to_b64,
+    sign_detached,
+    sign_jws,
+    verify_detached,
+    verify_jws,
+)
+from rare_identity_protocol.errors import (
+    ProtocolError,
+    ResourceLimitError,
+    SignatureError,
+    TokenValidationError,
+)
+from rare_identity_protocol.expiring_store import ExpiringMap, ExpiringSet
+from rare_identity_protocol.name_policy import normalize_name, validate_name
+from rare_identity_protocol.tokens import (
+    issue_agent_delegation,
+    issue_full_identity_attestation,
+    issue_public_identity_attestation,
+    issue_rare_delegation,
+)
+
+__all__ = [
+    "ProtocolError",
+    "ResourceLimitError",
+    "SignatureError",
+    "TokenValidationError",
+    "ExpiringMap",
+    "ExpiringSet",
+    "b64url_decode",
+    "b64url_encode",
+    "decode_jws",
+    "generate_ed25519_keypair",
+    "generate_nonce",
+    "json_dumps_compact",
+    "load_private_key",
+    "load_public_key",
+    "now_ts",
+    "public_key_to_b64",
+    "sign_detached",
+    "sign_jws",
+    "verify_detached",
+    "verify_jws",
+    "build_auth_challenge_payload",
+    "build_full_attestation_issue_payload",
+    "build_agent_auth_payload",
+    "build_register_payload",
+    "build_action_payload",
+    "build_set_name_payload",
+    "build_upgrade_request_payload",
+    "normalize_name",
+    "validate_name",
+    "issue_agent_delegation",
+    "issue_public_identity_attestation",
+    "issue_full_identity_attestation",
+    "issue_rare_delegation",
+]

rare_identity_protocol-0.1.0/src/rare_identity_protocol/actions.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+
+def _canonical_json(payload: dict[str, Any]) -> str:
+    return json.dumps(payload, separators=(",", ":"), sort_keys=True, ensure_ascii=False)
+
+
+def build_action_payload(
+    *,
+    aud: str,
+    session_token: str,
+    action: str,
+    action_payload: dict[str, Any],
+    nonce: str,
+    issued_at: int,
+    expires_at: int,
+) -> str:
+    body_hash = hashlib.sha256(_canonical_json(action_payload).encode("utf-8")).hexdigest()
+    return (
+        f"rare-act-v1:{aud}:{session_token}:{action}:{body_hash}:{nonce}:{issued_at}:{expires_at}"
+    )

rare_identity_protocol-0.1.0/src/rare_identity_protocol/challenge.py

@@ -0,0 +1,76 @@
+from rare_identity_protocol.name_policy import normalize_name
+
+
+def build_auth_challenge_payload(
+    *,
+    aud: str,
+    nonce: str,
+    issued_at: int,
+    expires_at: int,
+) -> str:
+    return f"rare-auth-v1:{aud}:{nonce}:{issued_at}:{expires_at}"
+
+
+def build_set_name_payload(
+    *,
+    agent_id: str,
+    name: str,
+    nonce: str,
+    issued_at: int,
+    expires_at: int,
+) -> str:
+    normalized_name = normalize_name(name)
+    return f"rare-name-v1:{agent_id}:{normalized_name}:{nonce}:{issued_at}:{expires_at}"
+
+
+def build_register_payload(
+    *,
+    agent_id: str,
+    name: str,
+    nonce: str,
+    issued_at: int,
+    expires_at: int,
+) -> str:
+    normalized_name = normalize_name(name)
+    return f"rare-register-v1:{agent_id}:{normalized_name}:{nonce}:{issued_at}:{expires_at}"
+
+
+def build_full_attestation_issue_payload(
+    *,
+    agent_id: str,
+    platform_aud: str,
+    nonce: str,
+    issued_at: int,
+    expires_at: int,
+) -> str:
+    return f"rare-full-att-v1:{agent_id}:{platform_aud}:{nonce}:{issued_at}:{expires_at}"
+
+
+def build_upgrade_request_payload(
+    *,
+    agent_id: str,
+    target_level: str,
+    request_id: str,
+    nonce: str,
+    issued_at: int,
+    expires_at: int,
+) -> str:
+    return (
+        f"rare-upgrade-v1:{agent_id}:{target_level}:"
+        f"{request_id}:{nonce}:{issued_at}:{expires_at}"
+    )
+
+
+def build_agent_auth_payload(
+    *,
+    agent_id: str,
+    operation: str,
+    resource_id: str,
+    nonce: str,
+    issued_at: int,
+    expires_at: int,
+) -> str:
+    return (
+        f"rare-agent-auth-v1:{agent_id}:{operation}:{resource_id}:"
+        f"{nonce}:{issued_at}:{expires_at}"
+    )

rare_identity_protocol-0.1.0/src/rare_identity_protocol/crypto.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+import base64
+import json
+import secrets
+import time
+from dataclasses import dataclass
+from typing import Any
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+
+from rare_identity_protocol.errors import SignatureError, TokenValidationError
+
+
+RAW_KEY_SIZE = 32
+
+
+def now_ts() -> int:
+    return int(time.time())
+
+
+def b64url_encode(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def b64url_decode(data: str) -> bytes:
+    padding = "=" * ((4 - len(data) % 4) % 4)
+    return base64.urlsafe_b64decode((data + padding).encode("ascii"))
+
+
+def json_dumps_compact(payload: dict[str, Any]) -> bytes:
+    return json.dumps(payload, separators=(",", ":"), sort_keys=True).encode("utf-8")
+
+
+def generate_ed25519_keypair() -> tuple[str, str]:
+    private_key = Ed25519PrivateKey.generate()
+    public_key = private_key.public_key()
+    private_raw = private_key.private_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PrivateFormat.Raw,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+    public_raw = public_key.public_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PublicFormat.Raw,
+    )
+    return b64url_encode(private_raw), b64url_encode(public_raw)
+
+
+def load_private_key(raw_b64url: str) -> Ed25519PrivateKey:
+    key_bytes = b64url_decode(raw_b64url)
+    if len(key_bytes) != RAW_KEY_SIZE:
+        raise TokenValidationError("invalid Ed25519 private key length")
+    return Ed25519PrivateKey.from_private_bytes(key_bytes)
+
+
+def load_public_key(raw_b64url: str) -> Ed25519PublicKey:
+    key_bytes = b64url_decode(raw_b64url)
+    if len(key_bytes) != RAW_KEY_SIZE:
+        raise TokenValidationError("invalid Ed25519 public key length")
+    return Ed25519PublicKey.from_public_bytes(key_bytes)
+
+
+def public_key_to_b64(public_key: Ed25519PublicKey) -> str:
+    return b64url_encode(
+        public_key.public_bytes(
+            encoding=serialization.Encoding.Raw,
+            format=serialization.PublicFormat.Raw,
+        )
+    )
+
+
+def sign_detached(message: str, private_key: Ed25519PrivateKey) -> str:
+    signature = private_key.sign(message.encode("utf-8"))
+    return b64url_encode(signature)
+
+
+def verify_detached(message: str, signature_b64url: str, public_key: Ed25519PublicKey) -> None:
+    try:
+        signature = b64url_decode(signature_b64url)
+        public_key.verify(signature, message.encode("utf-8"))
+    except (InvalidSignature, ValueError) as exc:
+        raise SignatureError("invalid detached signature") from exc
+
+
+@dataclass(frozen=True)
+class DecodedJWS:
+    header: dict[str, Any]
+    payload: dict[str, Any]
+    signing_input: bytes
+    signature: bytes
+
+
+def sign_jws(
+    *,
+    payload: dict[str, Any],
+    private_key: Ed25519PrivateKey,
+    kid: str,
+    typ: str,
+) -> str:
+    header = {"alg": "EdDSA", "kid": kid, "typ": typ}
+    encoded_header = b64url_encode(json_dumps_compact(header))
+    encoded_payload = b64url_encode(json_dumps_compact(payload))
+    signing_input = f"{encoded_header}.{encoded_payload}".encode("ascii")
+    signature = private_key.sign(signing_input)
+    encoded_signature = b64url_encode(signature)
+    return f"{encoded_header}.{encoded_payload}.{encoded_signature}"
+
+
+def decode_jws(token: str) -> DecodedJWS:
+    try:
+        encoded_header, encoded_payload, encoded_signature = token.split(".")
+    except ValueError as exc:
+        raise TokenValidationError("invalid compact JWS format") from exc
+
+    try:
+        header = json.loads(b64url_decode(encoded_header))
+        payload = json.loads(b64url_decode(encoded_payload))
+        signature = b64url_decode(encoded_signature)
+    except (ValueError, json.JSONDecodeError) as exc:
+        raise TokenValidationError("invalid JWS encoding") from exc
+
+    if not isinstance(header, dict) or not isinstance(payload, dict):
+        raise TokenValidationError("JWS header/payload must be JSON objects")
+
+    signing_input = f"{encoded_header}.{encoded_payload}".encode("ascii")
+    return DecodedJWS(
+        header=header,
+        payload=payload,
+        signing_input=signing_input,
+        signature=signature,
+    )
+
+
+def verify_jws(token: str, public_key: Ed25519PublicKey) -> DecodedJWS:
+    decoded = decode_jws(token)
+
+    if decoded.header.get("alg") != "EdDSA":
+        raise TokenValidationError("unsupported JWS alg")
+
+    try:
+        public_key.verify(decoded.signature, decoded.signing_input)
+    except InvalidSignature as exc:
+        raise SignatureError("invalid JWS signature") from exc
+
+    return decoded
+
+
+def generate_nonce(length: int = 24) -> str:
+    return secrets.token_urlsafe(length)

rare_identity_protocol-0.1.0/src/rare_identity_protocol/errors.py

@@ -0,0 +1,14 @@
+class ProtocolError(ValueError):
+    """Base protocol error for validation/signature failures."""
+
+
+class SignatureError(ProtocolError):
+    """Raised when signature verification fails."""
+
+
+class TokenValidationError(ProtocolError):
+    """Raised when a token does not match protocol constraints."""
+
+
+class ResourceLimitError(ProtocolError):
+    """Raised when an in-memory security store reaches its capacity."""

rare_identity_protocol-0.1.0/src/rare_identity_protocol/expiring_store.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import heapq
+from dataclasses import dataclass
+from typing import Generic, Iterator, TypeVar
+
+from rare_identity_protocol.errors import ResourceLimitError
+
+K = TypeVar("K")
+V = TypeVar("V")
+
+
+@dataclass
+class _Entry(Generic[V]):
+    value: V
+    expires_at: int
+    revision: int
+
+
+class ExpiringMap(Generic[K, V]):
+    """Bounded expiring map with O(1) reads and O(log n) expiry operations."""
+
+    def __init__(self, *, capacity: int) -> None:
+        if capacity <= 0:
+            raise ValueError("capacity must be greater than 0")
+        self._capacity = capacity
+        self._entries: dict[K, _Entry[V]] = {}
+        self._expiry_heap: list[tuple[int, int, K]] = []
+        self._revision = 0
+
+    def cleanup(self, *, now: int, grace_seconds: int = 30) -> None:
+        cutoff = now - grace_seconds
+        while self._expiry_heap and self._expiry_heap[0][0] < cutoff:
+            expires_at, revision, key = heapq.heappop(self._expiry_heap)
+            current = self._entries.get(key)
+            if current is None:
+                continue
+            if current.revision != revision:
+                continue
+            if current.expires_at != expires_at:
+                continue
+            del self._entries[key]
+
+    def set(self, *, key: K, value: V, expires_at: int, now: int, grace_seconds: int = 30) -> None:
+        self.cleanup(now=now, grace_seconds=grace_seconds)
+        if key not in self._entries and len(self._entries) >= self._capacity:
+            raise ResourceLimitError("security replay/session store capacity exceeded")
+        self._revision += 1
+        revision = self._revision
+        self._entries[key] = _Entry(value=value, expires_at=expires_at, revision=revision)
+        heapq.heappush(self._expiry_heap, (expires_at, revision, key))
+
+    def get(self, key: K) -> V | None:
+        entry = self._entries.get(key)
+        return entry.value if entry is not None else None
+
+    def pop(self, key: K) -> V | None:
+        entry = self._entries.pop(key, None)
+        return entry.value if entry is not None else None
+
+    def discard(self, key: K) -> None:
+        self._entries.pop(key, None)
+
+    def __contains__(self, key: K) -> bool:
+        return key in self._entries
+
+    def __len__(self) -> int:
+        return len(self._entries)
+
+    def keys(self) -> Iterator[K]:
+        return iter(self._entries.keys())
+
+    def values(self) -> Iterator[V]:
+        for entry in self._entries.values():
+            yield entry.value
+
+    def items(self) -> Iterator[tuple[K, V]]:
+        for key, entry in self._entries.items():
+            yield key, entry.value
+
+
+class ExpiringSet(Generic[K]):
+    """Bounded expiring set for replay protection keys."""
+
+    def __init__(self, *, capacity: int) -> None:
+        self._store: ExpiringMap[K, bool] = ExpiringMap(capacity=capacity)
+
+    def cleanup(self, *, now: int, grace_seconds: int = 30) -> None:
+        self._store.cleanup(now=now, grace_seconds=grace_seconds)
+
+    def add(self, *, key: K, expires_at: int, now: int, grace_seconds: int = 30) -> None:
+        self._store.set(
+            key=key,
+            value=True,
+            expires_at=expires_at,
+            now=now,
+            grace_seconds=grace_seconds,
+        )
+
+    def contains(self, key: K) -> bool:
+        return key in self._store
+
+    def discard(self, key: K) -> None:
+        self._store.discard(key)
+
+    def __len__(self) -> int:
+        return len(self._store)

rare_identity_protocol-0.1.0/src/rare_identity_protocol/name_policy.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import re
+import unicodedata
+
+from rare_identity_protocol.errors import TokenValidationError
+
+
+MAX_NAME_LENGTH = 48
+MIN_NAME_LENGTH = 1
+RESERVED_NAMES = {
+    "admin",
+    "root",
+    "support",
+    "official",
+    "rare",
+}
+_CONTROL_CHAR_RE = re.compile(r"[\x00-\x1F\x7F]")
+
+
+def normalize_name(name: str) -> str:
+    return unicodedata.normalize("NFKC", name.strip())
+
+
+def validate_name(name: str, reserved_words: set[str] | None = None) -> str:
+    normalized = normalize_name(name)
+    if len(normalized) < MIN_NAME_LENGTH or len(normalized) > MAX_NAME_LENGTH:
+        raise TokenValidationError("name length must be between 1 and 48")
+
+    if _CONTROL_CHAR_RE.search(normalized):
+        raise TokenValidationError("name must not include control characters")
+
+    for char in normalized:
+        if unicodedata.category(char).startswith("C"):
+            raise TokenValidationError("name must not include control characters")
+
+    deny_words = reserved_words or RESERVED_NAMES
+    if normalized.casefold() in {w.casefold() for w in deny_words}:
+        raise TokenValidationError("name is reserved")
+
+    return normalized

rare_identity_protocol-0.1.0/src/rare_identity_protocol/tokens.py

@@ -0,0 +1,239 @@
+from __future__ import annotations
+
+from typing import Iterable
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+from rare_identity_protocol.crypto import now_ts, sign_jws
+from rare_identity_protocol.errors import TokenValidationError
+
+
+def _build_identity_claims(
+    *,
+    name: str,
+    iat: int,
+    name_updated_at: int | None,
+    owner_id: str | None,
+    org_id: str | None,
+    twitter: dict[str, str] | None,
+    github: dict[str, str] | None,
+    linkedin: dict[str, str] | None,
+    include_extended_claims: bool,
+) -> dict:
+    claims: dict[str, object] = {
+        "profile": {
+            "name": name,
+            "name_updated_at": name_updated_at if name_updated_at is not None else iat,
+        }
+    }
+    if not include_extended_claims:
+        return claims
+
+    if org_id:
+        claims["org_id"] = org_id
+    if owner_id:
+        claims["owner_id"] = owner_id
+    if twitter:
+        claims["twitter"] = twitter
+    if github:
+        claims["github"] = github
+    if linkedin:
+        claims["linkedin"] = linkedin
+    return claims
+
+
+def build_identity_payload(
+    *,
+    agent_id: str,
+    level: str,
+    name: str,
+    iat: int,
+    exp: int,
+    jti: str,
+    aud: str | None = None,
+    include_extended_claims: bool = True,
+    name_updated_at: int | None = None,
+    owner_id: str | None = None,
+    org_id: str | None = None,
+    twitter: dict[str, str] | None = None,
+    github: dict[str, str] | None = None,
+    linkedin: dict[str, str] | None = None,
+) -> dict:
+    claims = _build_identity_claims(
+        name=name,
+        iat=iat,
+        name_updated_at=name_updated_at,
+        owner_id=owner_id,
+        org_id=org_id,
+        twitter=twitter,
+        github=github,
+        linkedin=linkedin,
+        include_extended_claims=include_extended_claims,
+    )
+
+    payload = {
+        "typ": "rare.identity",
+        "ver": 1,
+        "iss": "rare",
+        "sub": agent_id,
+        "lvl": level,
+        "claims": claims,
+        "iat": iat,
+        "exp": exp,
+        "jti": jti,
+    }
+    if aud:
+        payload["aud"] = aud
+    return payload
+
+
+def issue_public_identity_attestation(
+    *,
+    agent_id: str,
+    level: str,
+    name: str,
+    kid: str,
+    signer_private_key: Ed25519PrivateKey,
+    ttl_seconds: int,
+    jti: str,
+    name_updated_at: int | None = None,
+    owner_id: str | None = None,
+    org_id: str | None = None,
+    twitter: dict[str, str] | None = None,
+    github: dict[str, str] | None = None,
+    linkedin: dict[str, str] | None = None,
+) -> str:
+    iat = now_ts()
+    exp = iat + ttl_seconds
+    public_level = level if level in {"L0", "L1"} else "L1"
+    payload = build_identity_payload(
+        agent_id=agent_id,
+        level=public_level,
+        name=name,
+        iat=iat,
+        exp=exp,
+        jti=jti,
+        include_extended_claims=False,
+        name_updated_at=name_updated_at,
+    )
+    return sign_jws(
+        payload=payload,
+        private_key=signer_private_key,
+        kid=kid,
+        typ="rare.identity.public+jws",
+    )
+
+
+def issue_full_identity_attestation(
+    *,
+    agent_id: str,
+    level: str,
+    name: str,
+    aud: str,
+    kid: str,
+    signer_private_key: Ed25519PrivateKey,
+    ttl_seconds: int,
+    jti: str,
+    name_updated_at: int | None = None,
+    owner_id: str | None = None,
+    org_id: str | None = None,
+    twitter: dict[str, str] | None = None,
+    github: dict[str, str] | None = None,
+    linkedin: dict[str, str] | None = None,
+) -> str:
+    iat = now_ts()
+    exp = iat + ttl_seconds
+    payload = build_identity_payload(
+        agent_id=agent_id,
+        level=level,
+        name=name,
+        aud=aud,
+        iat=iat,
+        exp=exp,
+        jti=jti,
+        include_extended_claims=True,
+        name_updated_at=name_updated_at,
+        owner_id=owner_id,
+        org_id=org_id,
+        twitter=twitter,
+        github=github,
+        linkedin=linkedin,
+    )
+    return sign_jws(
+        payload=payload,
+        private_key=signer_private_key,
+        kid=kid,
+        typ="rare.identity.full+jws",
+    )
+
+
+def issue_agent_delegation(
+    *,
+    agent_id: str,
+    session_pubkey: str,
+    aud: str,
+    scope: Iterable[str],
+    signer_private_key: Ed25519PrivateKey,
+    kid: str,
+    ttl_seconds: int = 3600,
+    jti: str,
+) -> str:
+    if not isinstance(jti, str) or not jti.strip():
+        raise TokenValidationError("delegation jti is required")
+    iat = now_ts()
+    payload = {
+        "typ": "rare.delegation",
+        "ver": 1,
+        "iss": "agent",
+        "agent_id": agent_id,
+        "session_pubkey": session_pubkey,
+        "aud": aud,
+        "scope": list(scope),
+        "iat": iat,
+        "exp": iat + ttl_seconds,
+        "act": "delegated_by_agent",
+    }
+    payload["jti"] = jti
+
+    return sign_jws(
+        payload=payload,
+        private_key=signer_private_key,
+        kid=kid,
+        typ="rare.delegation+jws",
+    )
+
+
+def issue_rare_delegation(
+    *,
+    agent_id: str,
+    session_pubkey: str,
+    aud: str,
+    scope: Iterable[str],
+    signer_private_key: Ed25519PrivateKey,
+    kid: str,
+    ttl_seconds: int = 3600,
+    jti: str,
+) -> str:
+    if not isinstance(jti, str) or not jti.strip():
+        raise TokenValidationError("delegation jti is required")
+    iat = now_ts()
+    payload = {
+        "typ": "rare.delegation",
+        "ver": 1,
+        "iss": "rare-signer",
+        "agent_id": agent_id,
+        "session_pubkey": session_pubkey,
+        "aud": aud,
+        "scope": list(scope),
+        "iat": iat,
+        "exp": iat + ttl_seconds,
+        "act": "delegated_by_rare",
+    }
+    payload["jti"] = jti
+
+    return sign_jws(
+        payload=payload,
+        private_key=signer_private_key,
+        kid=kid,
+        typ="rare.delegation+jws",
+    )

rare_identity_protocol-0.1.0/src/rare_identity_protocol.egg-info/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: rare-identity-protocol
+Version: 0.1.0
+Summary: Rare identity protocol primitives and signing helpers
+Project-URL: Homepage, https://api.rareid.cc
+Project-URL: Repository, https://github.com/0xsidfan/Rare
+Project-URL: Documentation, https://github.com/0xsidfan/Rare/tree/main/rare-identity-protocol-python
+Project-URL: Issues, https://github.com/0xsidfan/Rare/issues
+Keywords: rare,identity,protocol,ed25519,jws
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=42.0.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.2.0; extra == "test"
+
+# rare-identity-protocol-python
+
+Rare 的协议层 Python 包，提供：
+
+- 固定 signing input 构造
+- Ed25519 / JWS 签名与验签辅助
+- name normalization / validation
+- expiring map / set 等基础安全数据结构
+
+## Install
+
+```bash
+pip install rare-identity-protocol
+```
+
+本地工作区开发：
+
+```bash
+pip install -e .[test]
+```

rare_identity_protocol-0.1.0/src/rare_identity_protocol.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+README.md
+pyproject.toml
+src/rare_identity_protocol/__init__.py
+src/rare_identity_protocol/actions.py
+src/rare_identity_protocol/challenge.py
+src/rare_identity_protocol/crypto.py
+src/rare_identity_protocol/errors.py
+src/rare_identity_protocol/expiring_store.py
+src/rare_identity_protocol/name_policy.py
+src/rare_identity_protocol/tokens.py
+src/rare_identity_protocol.egg-info/PKG-INFO
+src/rare_identity_protocol.egg-info/SOURCES.txt
+src/rare_identity_protocol.egg-info/dependency_links.txt
+src/rare_identity_protocol.egg-info/requires.txt
+src/rare_identity_protocol.egg-info/top_level.txt
+tests/test_protocol_unit.py
+tests/test_vectors.py

rare_identity_protocol-0.1.0/src/rare_identity_protocol.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

rare_identity_protocol-0.1.0/src/rare_identity_protocol.egg-info/requires.txt

@@ -0,0 +1,4 @@
+cryptography>=42.0.0
+
+[test]
+pytest>=8.2.0

rare_identity_protocol-0.1.0/src/rare_identity_protocol.egg-info/top_level.txt

@@ -0,0 +1 @@
+rare_identity_protocol

rare_identity_protocol-0.1.0/tests/test_protocol_unit.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+import pytest
+
+from rare_identity_protocol import (
+    ExpiringMap,
+    ExpiringSet,
+    ResourceLimitError,
+    SignatureError,
+    TokenValidationError,
+    b64url_decode,
+    b64url_encode,
+    decode_jws,
+    generate_ed25519_keypair,
+    load_private_key,
+    load_public_key,
+    sign_detached,
+    sign_jws,
+    validate_name,
+    verify_detached,
+    verify_jws,
+)
+
+
+def test_load_key_rejects_invalid_length() -> None:
+    invalid_b64 = b64url_encode(b"short")
+    with pytest.raises(TokenValidationError, match="private key length"):
+        load_private_key(invalid_b64)
+    with pytest.raises(TokenValidationError, match="public key length"):
+        load_public_key(invalid_b64)
+
+
+def test_decode_jws_rejects_invalid_compact_format() -> None:
+    with pytest.raises(TokenValidationError, match="invalid compact JWS format"):
+        decode_jws("only-two.parts")
+
+
+def test_decode_jws_rejects_invalid_encoding_and_non_object_json() -> None:
+    with pytest.raises(TokenValidationError, match="invalid JWS encoding"):
+        decode_jws("a.b.c")
+
+    header = b64url_encode(b'["not-object"]')
+    payload = b64url_encode(b'{"ok":1}')
+    signature = b64url_encode(b"x" * 64)
+    token = f"{header}.{payload}.{signature}"
+    with pytest.raises(TokenValidationError, match="must be JSON objects"):
+        decode_jws(token)
+
+
+def test_verify_jws_rejects_unsupported_alg() -> None:
+    private_b64, public_b64 = generate_ed25519_keypair()
+    private_key = load_private_key(private_b64)
+    public_key = load_public_key(public_b64)
+
+    header = b64url_encode(b'{"alg":"HS256","kid":"k1","typ":"rare.identity.public+jws"}')
+    payload = b64url_encode(b'{"typ":"rare.identity","ver":1}')
+    signing_input = f"{header}.{payload}".encode("ascii")
+    signature = b64url_encode(private_key.sign(signing_input))
+    token = f"{header}.{payload}.{signature}"
+    with pytest.raises(TokenValidationError, match="unsupported JWS alg"):
+        verify_jws(token, public_key)
+
+
+def test_verify_jws_rejects_invalid_signature() -> None:
+    private_b64, public_b64 = generate_ed25519_keypair()
+    token = sign_jws(
+        payload={"typ": "rare.identity", "ver": 1, "iss": "rare"},
+        private_key=load_private_key(private_b64),
+        kid="k1",
+        typ="rare.identity.public+jws",
+    )
+    encoded_header, encoded_payload, encoded_signature = token.split(".")
+    signature_bytes = bytearray(b64url_decode(encoded_signature))
+    signature_bytes[0] ^= 0x01
+    tampered = f"{encoded_header}.{encoded_payload}.{b64url_encode(bytes(signature_bytes))}"
+    with pytest.raises(SignatureError, match="invalid JWS signature"):
+        verify_jws(tampered, load_public_key(public_b64))
+
+
+def test_verify_detached_rejects_invalid_signature() -> None:
+    private_a_b64, public_a_b64 = generate_ed25519_keypair()
+    private_b_b64, _ = generate_ed25519_keypair()
+    message = "rare-auth-v1:platform:nonce:1:2"
+    wrong_sig = sign_detached(message, load_private_key(private_b_b64))
+    with pytest.raises(SignatureError, match="invalid detached signature"):
+        verify_detached(message, wrong_sig, load_public_key(public_a_b64))
+
+
+def test_validate_name_normalizes_and_checks_boundaries() -> None:
+    assert validate_name("  Ａｌｉｃｅ　") == "Alice"
+    assert validate_name("a") == "a"
+    assert validate_name("x" * 48) == "x" * 48
+
+    with pytest.raises(TokenValidationError, match="between 1 and 48"):
+        validate_name("")
+    with pytest.raises(TokenValidationError, match="between 1 and 48"):
+        validate_name("x" * 49)
+
+
+def test_validate_name_rejects_control_and_reserved_words() -> None:
+    with pytest.raises(TokenValidationError, match="control characters"):
+        validate_name("hello\nworld")
+    with pytest.raises(TokenValidationError, match="control characters"):
+        validate_name("hello\u200Eworld")
+    with pytest.raises(TokenValidationError, match="reserved"):
+        validate_name("AdMiN")
+
+
+def test_expiring_map_rejects_invalid_capacity_and_overflow() -> None:
+    with pytest.raises(ValueError, match="capacity must be greater than 0"):
+        ExpiringMap[int, int](capacity=0)
+
+    store = ExpiringMap[str, int](capacity=1)
+    store.set(key="k1", value=1, expires_at=100, now=0)
+    with pytest.raises(ResourceLimitError, match="capacity exceeded"):
+        store.set(key="k2", value=2, expires_at=100, now=0)
+
+
+def test_expiring_map_cleanup_handles_stale_revisions() -> None:
+    store = ExpiringMap[str, str](capacity=4)
+    store.set(key="k", value="old", expires_at=10, now=0)
+    store.set(key="k", value="new", expires_at=200, now=0)
+    store.cleanup(now=50)
+    assert store.get("k") == "new"
+    store.cleanup(now=300)
+    assert store.get("k") is None
+
+
+def test_expiring_map_helpers_pop_discard_keys_values_items() -> None:
+    store = ExpiringMap[str, int](capacity=4)
+    store.set(key="a", value=1, expires_at=100, now=0)
+    store.set(key="b", value=2, expires_at=100, now=0)
+
+    assert "a" in store
+    assert len(store) == 2
+    assert set(store.keys()) == {"a", "b"}
+    assert set(store.values()) == {1, 2}
+    assert set(store.items()) == {("a", 1), ("b", 2)}
+    assert store.pop("a") == 1
+    assert store.pop("missing") is None
+    store.discard("b")
+    store.discard("missing")
+    assert len(store) == 0
+
+
+def test_expiring_set_helpers_cover_add_contains_discard_and_len() -> None:
+    seen = ExpiringSet[str](capacity=4)
+    seen.add(key="nonce-1", expires_at=100, now=0)
+    assert seen.contains("nonce-1")
+    assert len(seen) == 1
+    seen.discard("nonce-1")
+    seen.discard("nonce-404")
+    assert not seen.contains("nonce-1")
+    assert len(seen) == 0

rare_identity_protocol-0.1.0/tests/test_vectors.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from rare_identity_protocol import (
+    build_action_payload,
+    build_auth_challenge_payload,
+    build_full_attestation_issue_payload,
+    build_register_payload,
+    build_set_name_payload,
+    build_upgrade_request_payload,
+)
+
+
+def test_rip_v1_signing_input_vectors() -> None:
+    root = Path(__file__).resolve().parent
+    vectors_path = root / "fixtures" / "rip-v1-signing-inputs.json"
+    vectors = json.loads(vectors_path.read_text(encoding="utf-8"))
+
+    challenge = vectors["challenge"]
+    assert build_auth_challenge_payload(**challenge["input"]) == challenge["expected"]
+
+    set_name = vectors["set_name"]
+    assert build_set_name_payload(**set_name["input"]) == set_name["expected"]
+
+    set_name_nfkc_trim = vectors["set_name_nfkc_trim"]
+    assert (
+        build_set_name_payload(**set_name_nfkc_trim["input"])
+        == set_name_nfkc_trim["expected"]
+    )
+
+    register = vectors["register"]
+    assert build_register_payload(**register["input"]) == register["expected"]
+
+    register_nfkc_trim = vectors["register_nfkc_trim"]
+    assert (
+        build_register_payload(**register_nfkc_trim["input"])
+        == register_nfkc_trim["expected"]
+    )
+
+    full_attestation_issue = vectors["full_attestation_issue"]
+    assert (
+        build_full_attestation_issue_payload(**full_attestation_issue["input"])
+        == full_attestation_issue["expected"]
+    )
+
+    upgrade_request = vectors["upgrade_request"]
+    assert (
+        build_upgrade_request_payload(**upgrade_request["input"])
+        == upgrade_request["expected"]
+    )
+
+    action_post = vectors["action_post"]
+    assert build_action_payload(**action_post["input"]) == action_post["expected"]