cloudiamond-scratch 0.1.0__py3-none-any.whl

cloudiamond_scratch/__init__.py

@@ -0,0 +1,7 @@
+"""cloudiamond-scratch: Scratch <-> Python の暗号通信(X25519 + ChaCha20-Poly1305)。"""
+__version__ = "0.1.0"
+
+from .bridge import CloudBridge  # noqa: E402
+from .server import SecureServer, load_or_create_static_key, public_bytes  # noqa: E402
+
+__all__ = ["CloudBridge", "SecureServer", "load_or_create_static_key", "public_bytes", "__version__"]

cloudiamond_scratch/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

cloudiamond_scratch/bridge.py

@@ -0,0 +1,84 @@
+"""
+bridge.py -- クラウド変数(Scratch / TurboWarp)と SecureServer をつなぐ、通信手段に依存しない橋渡し。
+
+CloudBridge は WebSocket も scratchattach も知らない。使う側が次の 2 つだけ用意する。
+    on_variable(name, value)    クラウド変数が更新されたら呼ぶ(受信)
+    write(name, value)          クラウド変数を書く関数を渡す(送信。slot を全部書いた「後で」HDR を書く)
+
+Scratch 側(scratch/program.py)との約束:
+    C2S = クライアント -> サーバー: "☁ C2S_0".."☁ C2S_3"(slot) と "☁ C2S_HDR"(コミット)
+    S2C = サーバー -> クライアント: "☁ S2C_0".."☁ S2C_3" と "☁ S2C_HDR"
+    HDR の値が「変わった」ことが「slot が揃った」合図。だから HDR は書くたびに必ず変わる(seq を増やす)。
+    seq はサーバー全体で単調増加させる。セッションごとに 1 から数え直すと、新しい接続の最初の返信の HDR が
+    前の接続の最後の HDR と同じ値になり、クライアントが「変化なし」と見なしてしまう。
+
+安全性: クラウド変数は誰でも書ける。壊れた値・他人の値は暗号(AEAD)の検証で必ず捨てられる(= 安全側)。
+        捨てられるだけで届かなくはできる(妨害は防げない)。
+"""
+from __future__ import annotations
+
+import random
+import threading
+from typing import Callable, Dict, List, Optional
+
+from .server import MAX_SLOTS, SecureServer, from_slots, to_slots
+
+C2S_HDR = "☁ C2S_HDR"
+C2S_SLOTS = ["☁ C2S_%d" % i for i in range(MAX_SLOTS)]
+S2C_HDR = "☁ S2C_HDR"
+S2C_SLOTS = ["☁ S2C_%d" % i for i in range(MAX_SLOTS)]
+CLOUD_VARIABLES = [C2S_HDR] + C2S_SLOTS + [S2C_HDR] + S2C_SLOTS     # プロジェクトに必要な 10 個
+
+
+class CloudBridge:
+    def __init__(self, server: SecureServer, write: Callable[[str, str], None],
+                 seq_start: Optional[int] = None):
+        self.server = server
+        self._write = write
+        self._values: Dict[str, str] = {}
+        self._seq = seq_start if seq_start is not None else random.SystemRandom().randrange(1, 900000)
+        self._lock = threading.Lock()
+
+    # ---------------------------------------------------------------- 受信
+    def on_variable(self, name: str, value) -> None:
+        """クラウド変数の更新を 1 件渡す。名前が C2S_* 以外なら無視する。"""
+        if name not in C2S_SLOTS and name != C2S_HDR:
+            return
+        with self._lock:
+            self._values[name] = str(value)
+            if name != C2S_HDR:
+                return
+            # 同じ HDR を「重複」として捨てない: 別クライアントの正規フレームが偶然同じ HDR 値になり得るため。
+            # 再接続時の現在値の再送などで同じフレームが再度来ても、サーバーのリプレイ防止
+            # (既存 sid の HELLO・古いカウンタは拒否)が無害化する。
+            frames = self._decode(self._values[C2S_HDR])
+        if frames is None:
+            return
+        for reply in self.server.handle_frame(frames):
+            self._emit(reply)
+
+    def _decode(self, hdr: str) -> Optional[bytes]:
+        try:
+            n = int(hdr[-2:])
+            slots = [self._values[C2S_SLOTS[i]] for i in range(n)]
+            return from_slots(hdr, slots)[1]
+        except (ValueError, KeyError, IndexError):
+            return None                          # 壊れた値は黙って捨てる
+
+    # ---------------------------------------------------------------- 送信
+    def push(self, sid: bytes, data: bytes) -> bool:
+        """サーバー起点でクライアントへ送る(セッションが無い・長すぎる場合は False)。"""
+        frame = self.server.send(sid, data)
+        if frame is None:
+            return False
+        self._emit(frame)
+        return True
+
+    def _emit(self, frame: bytes) -> None:
+        with self._lock:
+            self._seq = self._seq % 999999 + 1   # 1..999999 を巡回。毎回必ず変わる
+            seq = self._seq
+        slots, hdr = to_slots(frame, seq)
+        for i, s in enumerate(slots):
+            self._write(S2C_SLOTS[i], s)
+        self._write(S2C_HDR, hdr)                # HDR を最後に書く = コミット

cloudiamond_scratch/cli.py

@@ -0,0 +1,113 @@
+"""
+cli.py -- コマンドライン: cloudiamond-scratch (または python -m cloudiamond_scratch)
+
+  keygen  server.key            サーバーの長期鍵を作る(0600)。秘密鍵は公開しない。公開鍵が表示される
+  pubkey  server.key            既存の秘密鍵から公開鍵を表示する
+  build   --key server.key -o client.sb3
+          --pub <64桁の16進>                      Scratch クライアント(.sb3)を生成する。埋め込まれるのは公開鍵だけ
+  selftest                      標準実装との照合(RFC ベクトル)と、クライアント/サーバーの往復を自己診断する
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+import zipfile
+from typing import List, Optional
+
+from . import __version__
+from .server import load_or_create_static_key, public_bytes, to_digits
+
+
+def _read_pub(args) -> bytes:
+    if args.pub:
+        h = args.pub.strip().lower().removeprefix("0x")
+        try:
+            raw = bytes.fromhex(h)
+        except ValueError:
+            raise SystemExit("error: --pub は 64 桁の 16 進数です")
+        if len(raw) != 32:
+            raise SystemExit("error: --pub は 32 byte(64 桁の 16 進数)である必要があります")
+        if not any(raw):
+            raise SystemExit("error: 全ゼロの公開鍵は使えません")
+        return raw
+    if args.key:
+        if not os.path.exists(args.key):
+            raise SystemExit("error: 鍵ファイルがありません: %s(先に keygen してください)" % args.key)
+        return public_bytes(load_or_create_static_key(args.key))
+    raise SystemExit("error: --key か --pub のどちらかを指定してください")
+
+
+def cmd_keygen(args) -> int:
+    existed = os.path.exists(args.path)
+    key = load_or_create_static_key(args.path)
+    pub = public_bytes(key)
+    print(("既存の" if existed else "新しい") + "サーバー秘密鍵: %s   ← 絶対に公開・コミットしない" % args.path)
+    _print_pub(pub)
+    return 0
+
+
+def _print_pub(pub: bytes) -> None:
+    print("公開鍵(hex)     :", pub.hex())
+    print("公開鍵(数字列)   :", to_digits(pub))
+    print("→ 公開鍵は Scratch に埋め込んで構いません(公開情報)。`build` が自動で埋め込みます。")
+
+
+def cmd_pubkey(args) -> int:
+    if not os.path.exists(args.path):
+        raise SystemExit("error: 鍵ファイルがありません: %s" % args.path)
+    _print_pub(public_bytes(load_or_create_static_key(args.path)))
+    return 0
+
+
+def cmd_build(args) -> int:
+    from .scratch.build import build_client_sb3
+    pub = _read_pub(args)
+    data = build_client_sb3(pub, sprite_name=args.name)
+    with open(args.output, "wb") as f:
+        f.write(data)
+    with zipfile.ZipFile(args.output) as z:
+        assert z.testzip() is None
+    print("生成しました: %s (%.1f KiB)" % (args.output, len(data) / 1024))
+    print("サーバー公開鍵 :", pub.hex())
+    print("次の手順       : Scratch / TurboWarp で開き、クラウド変数の接続先をサーバーに向ける(README 参照)")
+    print("保存の前に     : 実行した後のプロジェクトを保存・公開する前に『🔒 wipe secrets』ブロックを必ず実行する")
+    return 0
+
+
+def cmd_selftest(args) -> int:
+    from .selftest import run
+    return run(verbose=True)
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    p = argparse.ArgumentParser(prog="cloudiamond-scratch",
+                                description="Scratch <-> Python の暗号通信(X25519 + ChaCha20-Poly1305)")
+    p.add_argument("--version", action="version", version="cloudiamond-scratch " + __version__)
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    s = sub.add_parser("keygen", help="サーバーの長期鍵を作る")
+    s.add_argument("path", help="秘密鍵の保存先(例: server.key)")
+    s.set_defaults(fn=cmd_keygen)
+
+    s = sub.add_parser("pubkey", help="秘密鍵ファイルから公開鍵を表示する")
+    s.add_argument("path")
+    s.set_defaults(fn=cmd_pubkey)
+
+    s = sub.add_parser("build", help="Scratch クライアント(.sb3)を生成する")
+    g = s.add_mutually_exclusive_group(required=True)
+    g.add_argument("--key", help="サーバーの秘密鍵ファイル(公開鍵だけを取り出して埋め込む)")
+    g.add_argument("--pub", help="サーバーの公開鍵(64 桁の 16 進数)")
+    s.add_argument("-o", "--output", default="cloudiamond-client.sb3")
+    s.add_argument("--name", default="Cloudiamond", help="スプライト名")
+    s.set_defaults(fn=cmd_build)
+
+    s = sub.add_parser("selftest", help="自己診断")
+    s.set_defaults(fn=cmd_selftest)
+
+    args = p.parse_args(argv)
+    return args.fn(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

cloudiamond_scratch/reference/__init__.py

@@ -0,0 +1 @@
+"""Scratch の制約内で書いた参照実装(テストと、移植元の仕様書)。"""

cloudiamond_scratch/reference/client.py

@@ -0,0 +1,113 @@
+"""
+cloudiamond_scratch.reference.client -- Scratch クライアントの参照実装(= 移植元の仕様書)
+
+ここで使っているのは cloudiamond_scratch.reference.prims の関数と「リスト・数値・if・ループ」だけ。
+バイト列は Python の list[int](0..255)で扱う = Scratch のリストそのもの。
+各メソッドが、Scratch の「定義 ◯◯」カスタムブロック(実行中に画面を再描画しない)に1対1で対応する。
+"""
+from __future__ import annotations
+
+from typing import List, Optional
+
+from . import prims as sp
+
+T_HELLO, T_REPLY, T_C2S, T_S2C = 1, 2, 3, 4
+LABEL_MASTER = list(b"SCRSEC1-master\0\0")
+LABEL_C2S = list(b"SCRSEC1-c2s\0\0\0\0\0")
+LABEL_S2C = list(b"SCRSEC1-s2c\0\0\0\0\0")
+READY = list(b"SCRSEC1-READY\0\0\0")
+PAD_BUCKET = 32
+MAX_REPLY_TRIES = 3          # 偽の返信を大量に送り付けられても計算を無限にやらない
+
+
+def mix_entropy(*streams: List[int]) -> List[int]:
+    """複数の乱数源を byte ごとに足して mod 256。どれか1つが予測不能なら結果も予測不能。
+    Scratch では: [pick random 0〜255] + [timer と mouse x/y の細かい桁から作った byte] + [ユーザーが
+    3 秒間マウスを振った軌跡] + [days since 2000 の小数下位桁] ... を足し合わせる。"""
+    return [sum(s[i] for s in streams) % 256 for i in range(32)]
+
+
+def _all_zero(v) -> bool:
+    return sum(v) == 0
+
+
+def _ctr6(n) -> List[int]:
+    return [n // 256 ** (5 - i) % 256 for i in range(6)]
+
+
+def _pad(data: List[int]) -> List[int]:
+    n = len(data)
+    body = [n // 256, n % 256] + list(data)
+    return body + [0] * ((PAD_BUCKET - len(body) % PAD_BUCKET) % PAD_BUCKET)
+
+
+def _unpad(p: List[int]) -> Optional[List[int]]:
+    n = p[0] * 256 + p[1]
+    return None if 2 + n > len(p) else p[2:2 + n]
+
+
+class ScratchClient:
+    def __init__(self, server_pub: List[int], entropy32: List[int]):
+        self.S = list(server_pub)                 # プロジェクトに埋め込んだサーバー公開鍵(公開情報)
+        self.e = list(entropy32)                  # 使い捨ての秘密鍵。送信しない・保存しない
+        self.E = sp.x25519_base(self.e)           # 重い処理 #1
+        self.sid = self.E[:8]
+        self.dh_es = None
+        self.ready = False
+        self.tries = 0
+        self.send_ctr = 0
+        self.recv_last = 0
+        self.k_c2s = self.k_s2c = None
+
+    # ---- 定義 HELLOを作る
+    def hello(self) -> List[int]:
+        return self.sid + [T_HELLO] + self.E
+
+    # ---- 定義 返信を処理する
+    def on_reply(self, f: List[int]) -> bool:
+        if self.ready or self.tries >= MAX_REPLY_TRIES or len(f) != 73 or f[8] != T_REPLY or f[:8] != self.sid:
+            return False
+        self.tries += 1
+        R, sealed = f[9:41], f[41:]
+        if self.dh_es is None:
+            self.dh_es = sp.x25519(self.e, self.S)      # 重い処理 #2(1回だけ。サーバー認証の要)
+            if _all_zero(self.dh_es):
+                return False
+        dh_ee = sp.x25519(self.e, R)                    # 重い処理 #3(偽返信 1 個につき 1 回)
+        if _all_zero(dh_ee):                            # R が位数の小さい点 -> 拒否
+            return False
+        inner = sp.hchacha20(self.dh_es, LABEL_MASTER)[:16]
+        master = sp.hchacha20(dh_ee, inner)
+        k_c2s = sp.hchacha20(master, LABEL_C2S)
+        k_s2c = sp.hchacha20(master, LABEL_S2C)
+        aad = self.sid + [T_REPLY] + self.E + R         # E と R を認証 = 差し替え検出
+        pt = sp.aead_open(k_s2c, [0] * 12, aad, sealed)
+        if pt is None or pt != READY:
+            return False
+        self.k_c2s, self.k_s2c, self.ready = k_c2s, k_s2c, True
+        self.dh_es = dh_ee = master = None              # 不要になった秘密を消す
+        return True
+
+    # ---- 定義 暗号化して送るフレームを作る
+    def seal(self, data: List[int]) -> List[int]:
+        assert self.ready
+        self.send_ctr = self.send_ctr + 1
+        hdr = self.sid + [T_C2S] + _ctr6(self.send_ctr)
+        nonce = [0, 0, 0, 0] + [self.send_ctr // 256 ** (7 - i) % 256 for i in range(8)]
+        return hdr + sp.aead_seal(self.k_c2s, nonce, hdr, _pad(data))
+
+    # ---- 定義 受信フレームを復号する(失敗なら None)
+    def open(self, f: List[int]) -> Optional[List[int]]:
+        if not self.ready or len(f) < 15 + PAD_BUCKET + 16 or f[8] != T_S2C or f[:8] != self.sid:
+            return None
+        ctr = 0
+        for i in range(6):
+            ctr = ctr * 256 + f[9 + i]
+        if ctr <= self.recv_last:
+            return None
+        nonce = [0, 0, 0, 0] + [ctr // 256 ** (7 - i) % 256 for i in range(8)]
+        pt = sp.aead_open(self.k_s2c, nonce, f[:15], f[15:])
+        if pt is None:
+            return None
+        self.recv_last = ctr
+        return _unpad(pt)