md-signature

導入

署名と検証には、コマンドライン(mdsig)、TypeScript ライブラリ、Go ライブラリ、HTTP の検証サーバを使用できます。いずれも同じ仕様とテストベクタに基づいて実装しています。

コマンドライン(mdsig)

Go 製の単一バイナリです。macOS、Windows、Linux で動作し、引数なしで起動すると対話メニューを表示します。

コマンドライン(mdsig)
# インストール(Homebrew)
brew install SHIOZAKI-Shota/tap/mdsig
# GitHub で使用中の SSH 鍵で署名
mdsig sign contract.md -m git-hosting -s github.com/alice -r author
# 承認者を指定し、画像を固定して連署を要求
mdsig sign quote.md -m git-hosting -s github.com/alice --require "dns:example.com approver" --auto-resources
# チェーン全体を検証(終了コード 0〜5)
mdsig verify contract.md
mdsig verify --json contract.md
# 引数なしで対話メニューを起動
mdsig
コマンド 内容
mdsig sign <file> 署名を追記する。署名済みのファイルには連署として追加する。
mdsig verify <file>… チェーン全体を検証する。終了コードは 0〜5、--json で JSON 出力。
mdsig inspect <file> ネットワークを使用せず、各ブロックのフィールドとハッシュの一致を表示する。
mdsig keygen Ed25519 の鍵ペアを生成し、DNS の TXT レコードと tofu の pubkey を表示する。
mdsig revoke <file> 署名を撤回リストに追加し、リストに署名する。
mdsig timestamp <file> タイムスタンプ専用ブロックを追記する。重ねて実行すると更新になる。
mdsig serve 検証を HTTP API として提供する。
mdsig 対話メニューを起動する。LANG=ja_JP.UTF-8 なら日本語で表示する。

CLI 仕様

TypeScript ライブラリ(@md-signature/core)

実行時の依存関係はありません。Web Crypto などの Web 標準 API のみを使用するため、ブラウザ、Node.js、Deno、Bun、Cloudflare Workers で同じコードが動作します。

ライブラリ(@md-signature/core)
# npm への公開は準備中
npm install @md-signature/core
import { readFile } from "node:fs/promises";
import { dirname, join } from "node:path";
import { verifyDocument } from "@md-signature/core";

const file = "contract.md";
const markdown = await readFile(file, "utf8");
const result = await verifyDocument(markdown, {
  // local paths in `resources` are relative to the document's directory
  loadResource: (ref) => readFile(join(dirname(file), ref)).catch(() => null),
});

console.log(result.ok, result.agreement.status);
for (const s of result.signatures) console.log(s.index, s.fields.signer, s.status, s.code ?? "");
鍵を生成して署名する
import { signDocument, generateEd25519 } from "@md-signature/core";

const { signer } = await generateEd25519();
const { text } = await signDocument(markdown, {
  signer,
  method: "tofu",
  signerId: "bob@laptop",
  role: "reviewer",
  require: ["dns:example.com approver"],
});

主なオプション

  • fetch、resolvers、loadResource:鍵、撤回リスト、リソースの取得方法を差し替える。
  • tsaRoots、extraTsaRoots:TSA のルート証明書を置換、追加する。
  • tsaVerifier:トークンの検証をサーバに委ねる(remoteTsaVerifier(url))。

packages/core の README(全オプション)

Go ライブラリ(mdsig.dev/mdsig)

CLI と同じ検証処理を関数として呼び出せます。OpenPGP の処理を除き、標準ライブラリのみで動作します。

文書を検証する
import "mdsig.dev/mdsig"

res := mdsig.VerifyDocument(ctx, text, nil)
fmt.Println(res.OK, res.Agreement.Status)
for _, s := range res.Signatures {
	fmt.Println(s.Index, s.Fields["signer"], s.Status, s.Code)
}
go get mdsig.dev/mdsig
タイムスタンプ専用ブロックを追記する
out, err := mdsig.TimestampDocument(ctx, text, mdsig.TimestampOptions{
	TSAURL: "http://ts.ssl.com",
	Hash:   "sha512",
})

外部への接続はすべて SafeHTTPClient を経由し、プライベートアドレスへの接続を拒否します。鍵の解決方法は Resolver、TOFU の記録先は TofuStore で差し替えられます。

pkg.go.dev のリファレンス

検証サーバ

ブラウザ単体では確認できない項目(OS のトラストストアによる TSA の検証、CORS で取得できない鍵など)を、サーバに委ねられます。応答を受け取った側は、そのサーバの判定を信頼することになります。

起動して文書を送信する
mdsig serve --listen 127.0.0.1:8787 --allow-origin https://example.org

jq -Rs '{document: .}' contract.md |
  curl -s http://127.0.0.1:8787/v1/verify \
    -H 'content-type: application/json' -d @-
エンドポイント 要求と応答
POST /v1/verify { "document": "…" } を受け取り、JSON 出力の files の1要素と同じ形で応答する。
POST /v1/tsa tsa_token と署名のバイト列を受け取り、tsa オブジェクトで応答する。
GET /v1/health 名称、バージョン、API のバージョンを返す。
自前のサーバに組み込む
// Go
http.Handle("/", server.NewHandler(server.Options{
	AllowOrigins: []string{"https://example.org"},
}))

// TypeScript (Deno, Bun, Workers, Node.js)
Deno.serve(createVerifyHandler({ allowOrigins: ["https://example.org"] }));
手元の判定とサーバの判定を突き合わせる
import { verifyDocument, remoteVerify, compareResults } from "@md-signature/core";

const local = await verifyDocument(markdown);
const remote = await remoteVerify("https://verify.example.org", markdown);
const diff = compareResults(local, remote);

サーバは要求ごとに独立して検証し、TOFU の記録、鍵束、サーバ上のファイルを使用しません。ブラウザからの要求は --allow-origin で許可したオリジンに限ります。2つの判定は統合せず、出所を区別して表示してください。

CLI 仕様 §3.6 mdsig serve

CI と AI エージェント

mdsig verify の終了コードで後続の処理を制御します。0 以外(連署が不足する 5 を含む)で処理を中止すれば、署名の欠落や改変を見落としません。

GitHub Actions
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with: { go-version: "1.26" }
      - run: go install mdsig.dev/cmd/mdsig@latest
      - run: mdsig verify docs/*.md

承認の順序と人数を規定する場合は「連署ワークフロー」を参照してください。

エージェント向けの指示書
mdsig sign CLAUDE.md -m git-hosting -s github.com/alice
mdsig sign AGENTS.md -m git-hosting -s github.com/alice
mdsig verify CLAUDE.md AGENTS.md || exit 1

CLAUDE.md や AGENTS.md に署名し、エージェントの実行環境(Claude Code の SessionStart フックなど)が読み込み前に検証します。検証は実行環境の側で行ってください。防止できるのは PR や再配布の過程での改変で、ツール出力や Web ページ経由の注入は対象外です。