wimotek-edge-agent 1.0.8 → 1.0.9

package/README.md

@@ -375,7 +375,8 @@ Ship this structured log file to your central logging pipeline (Loki, ELK, Cloud
 ## Security model
 
 - **Token Secret**: >= 32 bytes HMAC secret.
-- **Single-Use Replay Protection**: `jti` is stored in SQLite `used_tokens` until expiration. Subsequent attempts are rejected with `token replay detected`.
+- **Compact 40-Character Single-Use HMAC Token**: 14-byte high-entropy ID (112 bits) + 16-byte HMAC-SHA256 signature (128 bits) = 30 raw bytes, Base64URL encoded to strictly 40 characters without padding. Replaces legacy verbose >200-character JWT-style strings while maintaining `O(1)` cryptographic tamper-proof validation.
+- **Single-Use Replay Protection**: Claims are stored in SQLite `issued_tokens` and atomically transferred to `used_tokens` upon first verification. Subsequent attempts are rejected with `token replay detected`.
 - **Identity & Network Binding**: Tokens can be bound to specific `node_uuid` and `allowed_ip_cidr` networks.
 - **TOFU Quarantine**: Unapproved nodes only exchange heartbeats; business data relay is strictly forbidden.
 - **No Downgrade**: Trusted nodes presenting without credentials cannot downgrade to TOFU.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wimotek-edge-agent",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "description": "Universal Edge Reverse Proxy & Service Bridge Agent CLI Runner",
   "bin": {
     "wimotek-edge-agent": "./bin/cli.js",

package/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "wimotek-edge-agent"
-version = "1.0.8"
+version = "1.0.9"
 description = "Universal Edge Reverse Proxy & Service Bridge Agent"
 readme = "README.md"
 requires-python = ">=3.9"

package/wimotek_edge_agent/agent.py

@@ -49,6 +49,7 @@ class EdgeAgent:
 
         self.token_issuer = JoinTokenIssuer(
             secret=config.token_secret,
+            store=self.trust_store,
             audience=config.token_audience,
             issuer=config.token_issuer,
             max_ttl_seconds=config.token_max_ttl_seconds,
@@ -56,6 +57,7 @@ class EdgeAgent:
         self.token_verifier = JoinTokenVerifier(
             secret=config.token_secret,
             replay_store=self.trust_store,
+            store=self.trust_store,
             audience=config.token_audience,
             issuer=config.token_issuer,
             max_ttl_seconds=config.token_max_ttl_seconds,

package/wimotek_edge_agent/tokens.py

@@ -20,6 +20,46 @@ class TokenReplayStore(Protocol):
         ...
 
 
+class TokenStore(Protocol):
+    def save_issued_token(self, token: str, claims: JoinTokenClaims) -> None:
+        ...
+
+    def get_issued_token(self, token: str) -> Optional[JoinTokenClaims]:
+        ...
+
+    def consume_token(self, jti: str, expires_at: int) -> bool:
+        ...
+
+
+class InMemoryTokenStore:
+    """轻量内存 Token 存储，供单测或无 SQLite 场景使用。"""
+
+    def __init__(self) -> None:
+        self._tokens: dict[str, JoinTokenClaims] = {}
+        self._used: set[str] = set()
+
+    def save_issued_token(self, token: str, claims: JoinTokenClaims) -> None:
+        self._tokens[token] = claims
+
+    def get_issued_token(self, token: str) -> Optional[JoinTokenClaims]:
+        now = int(time.time())
+        claims = self._tokens.get(token)
+        if claims and claims.exp < now:
+            self._tokens.pop(token, None)
+            return None
+        return claims
+
+    def is_token_used(self, jti: str) -> bool:
+        return jti in self._used
+
+    def consume_token(self, jti: str, expires_at: int) -> bool:
+        if jti in self._used:
+            return False
+        self._used.add(jti)
+        self._tokens.pop(jti, None)
+        return True
+
+
 def _b64e(data: bytes) -> str:
     return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
 
@@ -42,9 +82,16 @@ class JoinTokenClaims:
 
 
 class JoinTokenIssuer:
+    """
+    签发单次准入令牌。
+    采用 30 字节紧凑编码 (14 字节安全随机 ID + 16 字节 HMAC-SHA256 签名)，
+    Base64URL 编码后长度严格为 40 个字符，摆脱 >200 字符的冗长 JWT 结构。
+    """
+
     def __init__(
         self,
         secret: bytes,
+        store: Optional[TokenStore] = None,
         audience: str = "edge-agent",
         issuer: str = "central",
         max_ttl_seconds: int = 600,
@@ -52,6 +99,7 @@ class JoinTokenIssuer:
         if len(secret) < 32:
             raise ValueError("token secret must be at least 32 bytes")
         self.secret = secret
+        self.store: TokenStore = store if store is not None else InMemoryTokenStore()
         self.audience = audience
         self.issuer = issuer
         self.max_ttl_seconds = max_ttl_seconds
@@ -67,8 +115,18 @@ class JoinTokenIssuer:
             raise ValueError("ttl_seconds out of allowed range")
 
         now = int(time.time())
+
+        # 14 字节密码学高熵安全随机数 (112 位熵)
+        token_id = secrets.token_bytes(14)
+        # 16 字节 HMAC-SHA256 截断签名 (128 位数字签名防伪)
+        sig = hmac.new(self.secret, token_id, hashlib.sha256).digest()[:16]
+        # 拼接为恰好 30 字节的紧凑二进制数据
+        raw = token_id + sig
+        # Base64URL 编码后长度严格为 40 个无填充字符
+        token = _b64e(raw)
+
         claims = JoinTokenClaims(
-            jti=secrets.token_urlsafe(24),
+            jti=token,
             exp=now + ttl_seconds,
             iat=now,
             aud=self.audience,
@@ -77,11 +135,8 @@ class JoinTokenIssuer:
             node_uuid=node_uuid,
             allowed_ip_cidr=allowed_ip_cidr,
         )
-        payload = json.dumps(
-            asdict(claims), separators=(",", ":"), sort_keys=True
-        ).encode("utf-8")
-        signature = hmac.new(self.secret, payload, hashlib.sha256).digest()
-        return f"{_b64e(payload)}.{_b64e(signature)}"
+        self.store.save_issued_token(token, claims)
+        return token
 
 
 class JoinTokenVerifier:
@@ -89,6 +144,7 @@ class JoinTokenVerifier:
         self,
         secret: bytes,
         replay_store: TokenReplayStore,
+        store: Optional[TokenStore] = None,
         audience: str = "edge-agent",
         issuer: str = "central",
         max_ttl_seconds: int = 600,
@@ -97,6 +153,12 @@ class JoinTokenVerifier:
             raise ValueError("token secret must be at least 32 bytes")
         self.secret = secret
         self.replay_store = replay_store
+        if store is not None:
+            self.store = store
+        elif hasattr(replay_store, "get_issued_token"):
+            self.store = replay_store  # type: ignore
+        else:
+            self.store = InMemoryTokenStore()
         self.audience = audience
         self.issuer = issuer
         self.max_ttl_seconds = max_ttl_seconds
@@ -106,6 +168,70 @@ class JoinTokenVerifier:
         token: str,
         source_ip: str,
         node_uuid: str,
+    ) -> JoinTokenClaims:
+        # 兼容旧版带句号 "." 的 JWT 长票据
+        if "." in token:
+            return self._verify_legacy_jwt(token, source_ip, node_uuid)
+
+        # 紧凑型 40 字符 Token 验证
+        try:
+            raw = _b64d(token)
+            if len(raw) != 30:
+                raise TokenError("malformed token length")
+            token_id = raw[:14]
+            signature = raw[14:]
+        except Exception as exc:
+            raise TokenError("malformed token") from exc
+
+        # O(1) 密码学签名核对，拦截伪造与垃圾请求
+        expected = hmac.new(self.secret, token_id, hashlib.sha256).digest()[:16]
+        if not hmac.compare_digest(signature, expected):
+            raise TokenError("bad token signature")
+
+        # 载荷查询
+        claims = self.store.get_issued_token(token)
+        if claims is None:
+            # 明确区分：如果在 used_tokens 中已记录，则准确判定为重放拦截
+            if hasattr(self.replay_store, "is_token_used") and self.replay_store.is_token_used(token):
+                raise TokenError("token replay detected")
+            if hasattr(self.store, "is_token_used") and self.store.is_token_used(token):
+                raise TokenError("token replay detected")
+            raise TokenError("token not found or expired")
+
+        now = int(time.time())
+        if claims.exp <= now:
+            raise TokenError("token expired")
+        if claims.iat > now + 60:
+            raise TokenError("token issued in the future")
+        if claims.exp - claims.iat > self.max_ttl_seconds:
+            raise TokenError("token ttl too long")
+        if claims.aud != self.audience:
+            raise TokenError("token audience mismatch")
+        if claims.iss != self.issuer:
+            raise TokenError("token issuer mismatch")
+
+        if claims.node_uuid is not None and claims.node_uuid != node_uuid:
+            raise TokenError("token node_uuid mismatch")
+
+        if claims.allowed_ip_cidr:
+            try:
+                network = ipaddress.ip_network(claims.allowed_ip_cidr, strict=False)
+                address = ipaddress.ip_address(source_ip)
+            except ValueError as exc:
+                raise TokenError("invalid token ip binding or source ip") from exc
+            if address not in network:
+                raise TokenError("source ip not allowed by token")
+
+        if not self.replay_store.consume_token(claims.jti, claims.exp):
+            raise TokenError("token replay detected")
+
+        return claims
+
+    def _verify_legacy_jwt(
+        self,
+        token: str,
+        source_ip: str,
+        node_uuid: str,
     ) -> JoinTokenClaims:
         try:
             payload_b64, signature_b64 = token.split(".", 1)

package/wimotek_edge_agent/trust_store.py

@@ -54,6 +54,22 @@ class TrustStore:
                 )
                 """
             )
+            conn.execute(
+                """
+                CREATE TABLE IF NOT EXISTS issued_tokens (
+                    token TEXT PRIMARY KEY,
+                    jti TEXT NOT NULL UNIQUE,
+                    exp INTEGER NOT NULL,
+                    iat INTEGER NOT NULL,
+                    aud TEXT NOT NULL,
+                    iss TEXT NOT NULL,
+                    node_group TEXT NOT NULL,
+                    node_uuid TEXT,
+                    allowed_ip_cidr TEXT,
+                    created_at TEXT NOT NULL
+                )
+                """
+            )
 
     def get_node(self, node_uuid: str) -> Optional[NodeRecord]:
         with self._connect() as conn:
@@ -232,15 +248,79 @@ class TrustStore:
             "used_tokens_count": used_tokens_count,
         }
 
-    def consume_token(self, jti: str, expires_at: int) -> bool:
+    def save_issued_token(self, token: str, claims) -> None:
+        """
+        持久化 40 字符紧凑 Token 对应的 claims 载荷。
+        """
+        with self._connect() as conn:
+            conn.execute(
+                """
+                INSERT OR REPLACE INTO issued_tokens
+                (token, jti, exp, iat, aud, iss, node_group, node_uuid, allowed_ip_cidr, created_at)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    token,
+                    claims.jti,
+                    claims.exp,
+                    claims.iat,
+                    claims.aud,
+                    claims.iss,
+                    claims.node_group,
+                    claims.node_uuid,
+                    claims.allowed_ip_cidr,
+                    _utc_now(),
+                ),
+            )
+
+    def get_issued_token(self, token: str):
+        """
+        读取 Token 对应的 claims 载荷并过滤过期项。
+        """
+        from .tokens import JoinTokenClaims
+
+        now_ts = int(time.time())
+        with self._connect() as conn:
+            conn.execute("DELETE FROM issued_tokens WHERE exp < ?", (now_ts,))
+            row = conn.execute(
+                "SELECT * FROM issued_tokens WHERE token = ?", (token,)
+            ).fetchone()
+        if row is None:
+            return None
+        return JoinTokenClaims(
+            jti=row["jti"],
+            exp=row["exp"],
+            iat=row["iat"],
+            aud=row["aud"],
+            iss=row["iss"],
+            node_group=row["node_group"],
+            node_uuid=row["node_uuid"],
+            allowed_ip_cidr=row["allowed_ip_cidr"],
+        )
+
+    def is_token_used(self, jti: str) -> bool:
+        """
+        检查指定 jti 是否已被核销使用。
+        """
+        with self._connect() as conn:
+            row = conn.execute(
+                "SELECT 1 FROM used_tokens WHERE jti = ?", (jti,)
+            ).fetchone()
+            return row is not None
+
+    def consume_token(self, jti: str, expires_at: int, token: Optional[str] = None) -> bool:
         """
         返回 True 表示首次使用；False 表示重放。
+        单次原子核销：写入 used_tokens 并从 issued_tokens 移除。
         """
         now_ts = int(time.time())
         with self._connect() as conn:
             conn.execute(
                 "DELETE FROM used_tokens WHERE expires_at < ?", (now_ts,)
             )
+            conn.execute(
+                "DELETE FROM issued_tokens WHERE exp < ?", (now_ts,)
+            )
             try:
                 conn.execute(
                     """
@@ -249,6 +329,10 @@ class TrustStore:
                     """,
                     (jti, expires_at, _utc_now()),
                 )
+                if token:
+                    conn.execute("DELETE FROM issued_tokens WHERE token = ?", (token,))
+                else:
+                    conn.execute("DELETE FROM issued_tokens WHERE jti = ?", (jti,))
                 return True
             except sqlite3.IntegrityError:
                 return False