第185回では、期限内の承認でも、承認IDや署名鍵IDが取消一覧に含まれていれば拒否しました。
ただし、署名、期限、取消を検証しても、同じ承認文書を複数回提示することはできます。通知、公開、データ更新などを1回だけ許可したい場合は、別の対策が必要です。
今回は、検証済みのapproval_idをSQLiteへ予約し、コミット後に子コマンドを起動します。台帳が削除されたり過去の状態へ戻されたりしない限り、同じ承認IDによる起動は高々1回です。
処理が必ず1回完了するという意味のexactly-onceではありません。予約後に異常終了した場合は、子処理を起動していなくても承認を消費済みとして扱います。
期限、取消、単回利用は別に判定する
| 確認 | 防ぐもの | 防げないもの |
|---|---|---|
| 有効期間 | 開始前や期限切れの承認 | 期限内の繰り返し利用 |
| 取消一覧 | 停止した承認や鍵 | 未取消承認の繰り返し利用 |
| 単回利用台帳 | 同じ台帳へ記録されたapproval_idの再利用 |
別の台帳、台帳の巻き戻し、別の承認IDによる同じ処理 |
承認IDは、発行側で台帳の適用範囲内において一意にします。同じ業務処理へ別々の承認IDを発行すれば、それぞれを1回ずつ使用できます。請求番号などの業務キーによる重複防止は、実行対象側にも必要です。
実行前にreservedを確定する
- 承認文書のバイト列を、信頼済みの検証器へ標準入力で渡す。
- 検証器が署名、期間、成果物、取消一覧を確認する。
- ゲート側で承認文書全体のSHA-256と、検証済み成果物のSHA-256を照合する。
BEGIN IMMEDIATEで書き込みトランザクションを開始する。- 同じ
approval_idがなければ、状態reservedの行を追加してコミットする。 - コミット後に、設定済みの子コマンドをシェルを介さず起動する。
- 終了結果を
succeeded、child_failed、launch_failedのいずれかへ更新する。
SQLiteのトランザクション仕様では、BEGIN IMMEDIATEは書き込みトランザクションを直ちに開始し、別の書き込みトランザクションがある場合はSQLITE_BUSYになり得ます。二つのゲートが同時に同じ承認を検証しても、予約処理は直列化されます。
| 停止した時点 | 台帳 | 同じ承認での再実行 |
|---|---|---|
| 予約前 | 行なし | 検証からやり直せる |
| 予約コミット後、子起動前 | reserved |
拒否する |
| 子起動後、完了記録前 | reserved |
副作用の有無が不明なため拒否する |
| 子が非ゼロ終了 | child_failed |
拒否する |
| 子が正常終了 | succeeded |
拒否する |
reservedを一定時間後に自動削除すると、すでに開始した処理を再実行する可能性があります。本稿では自動解放しません。
今回の実行契約
| 項目 | 仕様 |
|---|---|
| 動作環境 | Python 3.11以上のLinux、ローカルファイルシステム |
| 設定JSON | BOMなしUTF-8、32,768バイト以下。信頼できる管理者だけが変更する |
| 承認文書 | 通常ファイル、131,072バイト以下。同じバイト列を検証器へ渡す |
| 検証器 | 絶対パスの実行ファイルから起動する。成功時は標準エラー出力を空にし、標準出力へ4,096バイト以下の1行JSONを返す |
| 実行対象 | 設定済みの引数配列をshell=Falseで起動する。承認文書からコマンドを読み取らない |
| 信頼するファイル | 設定、検証器、子コマンドとその親ディレクトリを、信頼できない利用者に変更させない |
| 台帳 | 実行ユーザーが所有し、他者が書き込めない実体ディレクトリへ、モード0600の専用SQLiteとして置く |
| 標準入出力 | 子の標準入力はDEVNULL。標準出力と標準エラー出力は継承する。ゲートのイベントは標準エラー出力へ出す |
| 環境変数 | 親プロセスの環境を継承する。必要なら第176回の許可リスト方式で外側から絞る |
| 対象外 | 分散ホスト間の調停、子処理の取り消し、台帳の巻き戻し検出、子孫プロセスの停止 |
検証器との入出力を固定する
検証器は、第185回までの署名、期間、成果物、取消の検証を担当します。成功時の標準出力は次の形式です。山括弧部分は実際の検証結果へ置き換えます。
{
"status": "approved",
"approval_id": "<検証した承認ID>",
"approval_sha256": "<標準入力全体のSHA-256>",
"artifact_sha256": "<実際に照合した成果物のSHA-256>"
}
artifact_sha256は、承認文書内の文字列を転記するだけでは足りません。検証器が実際の成果物を読み、承認されたハッシュと一致したことを確認してから返します。
ゲート設定は次の構造です。パスとハッシュを置き換えて使用します。
{
"version": 1,
"verifier_argv": [
"/絶対パス/python3",
"/絶対パス/verify_approval.py",
"--artifact",
"/絶対パス/artifact.bin",
"--revocations",
"/絶対パス/revocations.json"
],
"command_argv": [
"/絶対パス/python3",
"/絶対パス/apply_artifact.py",
"/絶対パス/artifact.bin"
],
"cwd": "/絶対パス/作業ディレクトリ",
"expected_artifact_sha256": "<承認済みの小文字64桁SHA-256>",
"verifier_timeout_seconds": 30
}
expected_artifact_sha256は、信頼済みのリリース設定などから渡します。配置先のファイルをその場でハッシュ化して設定値にすると、差し替えられた成果物を自分で承認する形になります。
単回利用ゲートを実装する
subprocess.run()のinputへ承認文書のバイト列を渡します。SQLite接続はisolation_level=Noneとし、トランザクションを明示的に制御します。
台帳にはDELETEジャーナルとsynchronous=EXTRAを使用します。SQLiteのPRAGMA synchronous仕様によると、EXTRAはDELETEジャーナルの削除後にディレクトリ同期を追加します。ただし、耐久性はOS、ストレージ、ファイルシステム、SQLiteのVFSが同期要求を正しく処理することに依存します。
#!/usr/bin/env python3
from __future__ import annotations
import argparse
import hashlib
import json
import os
import re
import sqlite3
import stat
import subprocess
import sys
from contextlib import contextmanager
from datetime import datetime, timezone
from pathlib import Path
from typing import Any, Iterator, NoReturn
MAX_CONFIG = 32_768
MAX_APPROVAL = 131_072
MAX_VERIFIER_OUTPUT = 4_096
HASH_RE = re.compile(r"[0-9a-f]{64}")
ID_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:-]{0,127}")
class GateError(Exception):
def __init__(self, code: int, event: str, detail: str, **fields: Any):
super().__init__(detail)
self.code = code
self.event = event
self.fields = fields
def fail(code: int, event: str, detail: str, **fields: Any) -> NoReturn:
raise GateError(code, event, detail, **fields)
def emit(event: str, **fields: Any) -> None:
print(
json.dumps({"event": event, **fields}, ensure_ascii=False,
sort_keys=True, separators=(",", ":")),
file=sys.stderr,
flush=True,
)
def now_utc() -> str:
return datetime.now(timezone.utc).isoformat(
timespec="seconds"
).replace("+00:00", "Z")
def read_small_regular(path: str, limit: int, label: str) -> bytes:
flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0)
try:
fd = os.open(path, flags)
except OSError as exc:
fail(65, "input_error", f"{label}を開けません: {exc.strerror}")
with os.fdopen(fd, "rb") as stream:
info = os.fstat(stream.fileno())
if not stat.S_ISREG(info.st_mode):
fail(65, "input_error", f"{label}は通常ファイルではありません")
if info.st_size > limit:
fail(65, "input_error", f"{label}が{limit}バイトを超えています")
data = stream.read(limit + 1)
if len(data) > limit:
fail(65, "input_error", f"{label}が{limit}バイトを超えています")
return data
def json_object(raw: bytes, label: str) -> dict[str, Any]:
try:
text = raw.decode("utf-8")
if text.startswith(chr(0xFEFF)):
raise ValueError("BOM")
value = json.loads(text)
except (UnicodeDecodeError, json.JSONDecodeError, ValueError):
fail(65, "input_error", f"{label}はBOMなしUTF-8のJSONではありません")
if not isinstance(value, dict):
fail(65, "input_error", f"{label}の最上位はオブジェクトにしてください")
return value
def checked_argv(value: Any, label: str) -> list[str]:
if not isinstance(value, list) or not 1 <= len(value) <= 64:
fail(65, "input_error", f"{label}は1~64要素の配列にしてください")
if any(
not isinstance(x, str) or not x or len(x) > 4096 or chr(0) in x
for x in value
):
fail(65, "input_error", f"{label}の各要素は1~4096文字にしてください")
if not os.path.isabs(value[0]):
fail(65, "input_error", f"{label}の実行ファイルは絶対パスにしてください")
return list(value)
def load_config(path: str) -> dict[str, Any]:
value = json_object(
read_small_regular(path, MAX_CONFIG, "設定JSON"),
"設定JSON",
)
keys = {
"version", "verifier_argv", "command_argv", "cwd",
"expected_artifact_sha256", "verifier_timeout_seconds",
}
if set(value) != keys or type(value["version"]) is not int or value["version"] != 1:
fail(65, "input_error", "設定JSONのキーまたはversionが不正です")
verifier = checked_argv(value["verifier_argv"], "verifier_argv")
command = checked_argv(value["command_argv"], "command_argv")
cwd = value["cwd"]
if (
not isinstance(cwd, str)
or chr(0) in cwd
or not os.path.isabs(cwd)
or not Path(cwd).is_dir()
):
fail(65, "input_error", "cwdは既存ディレクトリの絶対パスにしてください")
artifact_hash = value["expected_artifact_sha256"]
if not isinstance(artifact_hash, str) or HASH_RE.fullmatch(artifact_hash) is None:
fail(65, "input_error", "expected_artifact_sha256は小文字64桁の16進数にしてください")
timeout = value["verifier_timeout_seconds"]
if isinstance(timeout, bool) or not isinstance(timeout, int) or not 1 <= timeout <= 300:
fail(65, "input_error", "verifier_timeout_secondsは1~300の整数にしてください")
return {
"verifier_argv": verifier,
"command_argv": command,
"cwd": cwd,
"expected_artifact_sha256": artifact_hash,
"verifier_timeout_seconds": timeout,
}
def verify(config: dict[str, Any], approval: bytes) -> dict[str, str]:
try:
result = subprocess.run(
config["verifier_argv"],
cwd=config["cwd"],
input=approval,
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
timeout=config["verifier_timeout_seconds"],
check=False,
shell=False,
close_fds=True,
)
except subprocess.TimeoutExpired:
fail(69, "verifier_unavailable", "検証器がタイムアウトしました")
except OSError as exc:
fail(69, "verifier_unavailable", f"検証器を起動できません: {exc.strerror}")
if result.returncode != 0:
fail(
77,
"approval_not_approved",
"検証器が非ゼロで終了し、承認を確認できませんでした",
verifier_returncode=result.returncode,
)
if result.stderr or not result.stdout or len(result.stdout) > MAX_VERIFIER_OUTPUT:
fail(65, "verifier_contract_error", "検証器の成功時出力が契約違反です")
try:
text = result.stdout.decode("utf-8")
lines = text.splitlines()
if len(lines) != 1 or not lines[0]:
raise ValueError("line count")
receipt = json.loads(lines[0])
except (UnicodeDecodeError, json.JSONDecodeError, ValueError):
fail(65, "verifier_contract_error", "検証器の標準出力はUTF-8の1行JSONにしてください")
required = {
"status", "approval_id", "approval_sha256", "artifact_sha256",
}
if (
not isinstance(receipt, dict)
or set(receipt) != required
or receipt.get("status") != "approved"
):
fail(65, "verifier_contract_error", "検証器のJSONキーまたはstatusが不正です")
approval_id = receipt.get("approval_id")
if not isinstance(approval_id, str) or ID_RE.fullmatch(approval_id) is None:
fail(65, "verifier_contract_error", "approval_idの形式が不正です")
for name in ("approval_sha256", "artifact_sha256"):
if not isinstance(receipt.get(name), str) or HASH_RE.fullmatch(receipt[name]) is None:
fail(65, "verifier_contract_error", f"{name}の形式が不正です")
if receipt["approval_sha256"] != hashlib.sha256(approval).hexdigest():
fail(65, "verifier_contract_error", "承認文書のSHA-256がゲート側と一致しません")
if receipt["artifact_sha256"] != config["expected_artifact_sha256"]:
fail(65, "verifier_contract_error", "検証済み成果物が設定の期待値と一致しません")
return {
name: receipt[name]
for name in ("approval_id", "approval_sha256", "artifact_sha256")
}
@contextmanager
def immediate(connection: sqlite3.Connection) -> Iterator[None]:
connection.execute("BEGIN IMMEDIATE")
try:
yield
connection.execute("COMMIT")
except BaseException:
if connection.in_transaction:
try:
connection.execute("ROLLBACK")
except sqlite3.Error:
pass
raise
def open_database(path_text: str) -> sqlite3.Connection:
if chr(0) in path_text:
fail(73, "state_error", "台帳パスにNUL文字は使用できません")
path = Path(path_text)
if not path.is_absolute():
fail(73, "state_error", "台帳パスは絶対パスにしてください")
try:
parent = path.parent.resolve(strict=True)
parent_info = parent.stat()
except OSError:
fail(73, "state_error", "台帳の親ディレクトリを確認できません")
if (
parent != path.parent
or not stat.S_ISDIR(parent_info.st_mode)
or parent_info.st_uid != os.geteuid()
or parent_info.st_mode & 0o022
):
fail(
73,
"state_error",
"台帳の親は実行ユーザー所有で、他者が書き込めない実体ディレクトリにしてください",
)
flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0)
try:
fd = os.open(path_text, flags, 0o600)
except FileExistsError:
pass
except OSError as exc:
fail(73, "state_error", f"台帳を作成できません: {exc.strerror}")
else:
os.close(fd)
try:
info = os.lstat(path_text)
except OSError:
fail(73, "state_error", "台帳ファイルを確認できません")
if (
not stat.S_ISREG(info.st_mode)
or info.st_nlink != 1
or info.st_uid != os.geteuid()
or stat.S_IMODE(info.st_mode) != 0o600
):
fail(
73,
"state_error",
"台帳は実行ユーザー所有、モード0600、リンク数1の通常ファイルにしてください",
)
connection = sqlite3.connect(path_text, timeout=5.0, isolation_level=None)
try:
mode = connection.execute("PRAGMA journal_mode=DELETE").fetchone()
if mode is None or str(mode[0]).lower() != "delete":
fail(73, "state_error", "DELETEジャーナルへ設定できません")
connection.execute("PRAGMA synchronous=EXTRA")
synchronous = connection.execute("PRAGMA synchronous").fetchone()
if synchronous is None or synchronous[0] != 3:
fail(73, "state_error", "synchronous=EXTRAへ設定できません")
with immediate(connection):
version = connection.execute("PRAGMA user_version").fetchone()[0]
if version == 0:
connection.execute(
"""CREATE TABLE approval_use (
approval_id TEXT PRIMARY KEY,
approval_sha256 TEXT NOT NULL,
artifact_sha256 TEXT NOT NULL,
reserved_at TEXT NOT NULL,
state TEXT NOT NULL CHECK (
state IN ('reserved','succeeded','child_failed','launch_failed')
),
finished_at TEXT,
child_returncode INTEGER,
detail TEXT
)"""
)
connection.execute("PRAGMA user_version=1")
elif version != 1:
fail(73, "state_error", "未対応の台帳スキーマです")
expected_columns = [
(0, "approval_id", "TEXT", 0, None, 1),
(1, "approval_sha256", "TEXT", 1, None, 0),
(2, "artifact_sha256", "TEXT", 1, None, 0),
(3, "reserved_at", "TEXT", 1, None, 0),
(4, "state", "TEXT", 1, None, 0),
(5, "finished_at", "TEXT", 0, None, 0),
(6, "child_returncode", "INTEGER", 0, None, 0),
(7, "detail", "TEXT", 0, None, 0),
]
columns = connection.execute(
"PRAGMA table_info(approval_use)"
).fetchall()
objects = connection.execute(
"""SELECT type,name,tbl_name FROM sqlite_schema
WHERE name NOT LIKE 'sqlite_%'
ORDER BY type,name"""
).fetchall()
if columns != expected_columns or objects != [
("table", "approval_use", "approval_use")
]:
fail(73, "state_error", "専用台帳のスキーマが不正です")
except BaseException:
connection.close()
raise
return connection
def reserve(connection: sqlite3.Connection, receipt: dict[str, str]) -> None:
with immediate(connection):
row = connection.execute(
"""SELECT approval_sha256,artifact_sha256,reserved_at,state
FROM approval_use WHERE approval_id=?""",
(receipt["approval_id"],),
).fetchone()
if row is not None:
fail(
78,
"approval_already_used",
"このapproval_idはすでに予約されています",
same_approval=row[0] == receipt["approval_sha256"],
same_artifact=row[1] == receipt["artifact_sha256"],
reserved_at=row[2],
state=row[3],
)
connection.execute(
"""INSERT INTO approval_use
(approval_id,approval_sha256,artifact_sha256,reserved_at,state)
VALUES (?,?,?,?,'reserved')""",
(
receipt["approval_id"],
receipt["approval_sha256"],
receipt["artifact_sha256"],
now_utc(),
),
)
def finish(
connection: sqlite3.Connection,
approval_id: str,
state: str,
returncode: int | None,
detail: str | None,
) -> None:
with immediate(connection):
cursor = connection.execute(
"""UPDATE approval_use
SET state=?,finished_at=?,child_returncode=?,detail=?
WHERE approval_id=? AND state='reserved'""",
(state, now_utc(), returncode, detail, approval_id),
)
if cursor.rowcount != 1:
fail(73, "state_error", "予約行を完了状態へ更新できません")
def execute_once(
config: dict[str, Any],
connection: sqlite3.Connection,
receipt: dict[str, str],
) -> int:
try:
result = subprocess.run(
config["command_argv"],
cwd=config["cwd"],
stdin=subprocess.DEVNULL,
check=False,
shell=False,
close_fds=True,
)
except OSError as exc:
finish(
connection,
receipt["approval_id"],
"launch_failed",
None,
type(exc).__name__,
)
emit("command_launch_failed", approval_id=receipt["approval_id"])
return 70
state = "succeeded" if result.returncode == 0 else "child_failed"
finish(connection, receipt["approval_id"], state, result.returncode, None)
emit(
"command_finished",
approval_id=receipt["approval_id"],
child_returncode=result.returncode,
state=state,
)
return 0 if result.returncode == 0 else 70
class Parser(argparse.ArgumentParser):
def error(self, message: str) -> NoReturn:
fail(64, "usage_error", message)
def main() -> int:
parser = Parser()
parser.add_argument("--config", required=True)
parser.add_argument("--approval", required=True)
parser.add_argument("--database", required=True)
connection: sqlite3.Connection | None = None
try:
args = parser.parse_args()
config = load_config(args.config)
approval = read_small_regular(
args.approval,
MAX_APPROVAL,
"承認文書",
)
receipt = verify(config, approval)
connection = open_database(args.database)
reserve(connection, receipt)
emit("approval_reserved", approval_id=receipt["approval_id"])
return execute_once(config, connection, receipt)
except GateError as exc:
emit(exc.event, detail=str(exc), **exc.fields)
return exc.code
except sqlite3.Error as exc:
message = str(exc).lower()
busy = "locked" in message or "busy" in message
emit("state_busy" if busy else "state_error")
return 75 if busy else 73
except KeyboardInterrupt:
emit("interrupted")
return 130
except Exception as exc:
emit("unexpected_error", error_type=type(exc).__name__)
return 70
finally:
if connection is not None:
connection.close()
if __name__ == "__main__":
raise SystemExit(main())
台帳用ディレクトリを用意して実行する
スクリプトをapproval_once_gate.pyとして保存し、構文を確認します。
python3 -m py_compile approval_once_gate.py
mkdir -m 700 state
設定、承認文書、台帳は絶対パスで指定します。台帳ファイルは初回実行時に作成されます。
python3 approval_once_gate.py \
--config /absolute/path/gate.json \
--approval /absolute/path/approval.json \
--database /absolute/path/state/approval-use.sqlite3
echo $?
初回は、予約のコミット後にapproval_reservedを標準エラー出力へ出し、子コマンドを起動します。二度目は検証後にapproval_already_usedとなり、子コマンドを起動しません。
子コマンドの標準エラー出力も同じ出力先へ流れるため、標準エラー出力全体がJSON Linesになるわけではありません。機械処理する場合は、子側のログ出力先を分けます。
台帳を読み取り専用で点検する
次のスクリプトは、パスを誤っても新しいSQLiteを作らないよう、SQLiteのURIファイル名とmode=roを使います。
import json
import sqlite3
import sys
from pathlib import Path
path = Path(sys.argv[1]).resolve(strict=True)
connection = sqlite3.connect(path.as_uri() + "?mode=ro", uri=True)
try:
rows = connection.execute(
"""SELECT approval_id,reserved_at,state,finished_at,child_returncode
FROM approval_use ORDER BY reserved_at,approval_id"""
).fetchall()
finally:
connection.close()
for row in rows:
print(json.dumps({
"approval_id": row[0],
"reserved_at": row[1],
"state": row[2],
"finished_at": row[3],
"child_returncode": row[4],
}, ensure_ascii=False, separators=(",", ":")))
reserved_atとfinished_atは点検用です。単回利用は時刻ではなく、主キーであるapproval_idの存在で判定します。
終了コードを運用側で分ける
| 終了コード | 意味 | 子コマンド |
|---|---|---|
| 0 | 子が正常終了し、succeededを記録した |
起動済み |
| 64 | CLI引数が不正 | 未起動 |
| 65 | 入力または検証器の成功時出力が契約違反 | 未起動 |
| 69 | 検証器の起動失敗またはタイムアウト | 未起動 |
| 70 | 子の起動失敗、子の非ゼロ終了、または予期しない内部エラー | 状況による |
| 73 | 台帳の作成、形式、更新などのエラー | 発生段階による |
| 75 | SQLiteがロック中またはビジー | 発生段階による |
| 77 | 検証器が非ゼロ終了し、承認を確認できなかった | 未起動 |
| 78 | 同じapproval_idがすでに存在する |
未起動 |
| 130 | 割り込み | 割り込み時点による |
子が非ゼロで終了しても、台帳はchild_failedとなり、承認は消費済みです。再実行が必要なら、副作用の有無を調査し、新しい承認IDを発行する手順を別に定めます。
単回利用台帳の限界
- 台帳の巻き戻しには弱い:古いバックアップへ戻したり台帳を削除したりすれば、過去の承認を再利用できる可能性があります。復元後の再利用を検出するには、台帳外にも巻き戻されない状態が必要です。
- 複数ホストには広がらない:ホストごとに別のSQLiteを持てば、それぞれで1回ずつ起動できます。分散実行には、一貫した共有ストアや業務システム側の一意制約が必要です。
- 完了を保証しない:
reservedのまま止まった場合、未起動、実行途中、完了後の記録失敗を台帳だけでは区別できません。 - 副作用を取り消さない:子が更新後に非ゼロ終了しても、更新内容は戻りません。子処理側でも業務キーによる冪等性を持たせます。
- 検証後の取消を検出しない:検証器の成功直後に承認が取り消されても、今回の起動には反映できません。
- 成果物を固定しない:検証後に子がパスを開き直す場合、その間の差し替えは別問題です。実行ファイルなら第178回の封印済み
memfd、データなら子側での再ハッシュなどを検討します。 - 検証器の出力量を読み取り中には制限しない:
subprocess.run()は出力を取り込んだ後で4,096バイトを判定します。これは契約検査であり、信頼できない検証器による出力洪水への防御ではありません。 - 子孫プロセスを管理しない:タイムアウトで停止するのは検証器の直接のプロセスです。検証器はバックグラウンドプロセスを残さない契約にします。実行対象の子孫やタイムアウトも、このゲートでは管理しません。
導入時は副作用のない子コマンドを使い、初回だけ起動すること、同時実行時に一方だけが予約できること、非ゼロ終了後も再利用できないことを確認します。その後、台帳の保存と復元、reservedの調査、新しい承認の発行手順を運用へ組み込みます。