md-signature
導入
署名と検証には、コマンドライン(mdsig)、TypeScript ライブラリ、Go ライブラリ、HTTP の検証サーバを使用できます。いずれも同じ仕様とテストベクタに基づいて実装しています。
コマンドライン(mdsig)
Go 製の単一バイナリです。macOS、Windows、Linux で動作し、引数なしで起動すると対話メニューを表示します。
# インストール(Homebrew)
brew install SHIOZAKI-Shota/tap/mdsig
# インストール(Go 1.26 以降。winget は準備中)
go install mdsig.dev/cmd/mdsig@latest
# インストール(Go 1.26 以降。.deb / .rpm は準備中)
go install mdsig.dev/cmd/mdsig@latest
# 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 なら日本語で表示する。 |
TypeScript ライブラリ(@md-signature/core)
実行時の依存関係はありません。Web Crypto などの Web 標準 API のみを使用するため、ブラウザ、Node.js、Deno、Bun、Cloudflare Workers で同じコードが動作します。
# 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 ?? "");
# npm への公開は準備中
bun add @md-signature/core
import { verifyDocument } from "@md-signature/core";
const markdown = await Bun.file("contract.md").text();
const { ok, signatures } = await verifyDocument(markdown);
console.log(ok, signatures.map((s) => `${s.fields.signer}: ${s.status}`));
# npm への公開は準備中(公開後はインストール不要、npm: 指定子)
import { verifyDocument } from "npm:@md-signature/[email protected]";
const markdown = await Deno.readTextFile("contract.md");
const { ok, signatures } = await verifyDocument(markdown);
console.log(ok, signatures.map((s) => `${s.fields.signer}: ${s.status}`));
# npm への公開は準備中(公開後はインストール不要、ESM CDN)
<script type="module">
import { verifyDocument } from "https://esm.sh/@md-signature/[email protected]";
const markdown = await (await fetch("contract.md")).text();
const { ok, signatures } = await verifyDocument(markdown);
document.body.dataset.signed = String(ok);
</script>
# npm への公開は準備中
npm install @md-signature/core
import { verifyDocument } from "@md-signature/core";
export default {
async fetch(request) {
const markdown = await request.text();
const result = await verifyDocument(markdown);
return Response.json(result, { status: result.ok ? 200 : 422 });
},
};
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 で差し替えられます。
検証サーバ
ブラウザ単体では確認できない項目(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つの判定は統合せず、出所を区別して表示してください。
CI と AI エージェント
mdsig verify の終了コードで後続の処理を制御します。0 以外(連署が不足する 5 を含む)で処理を中止すれば、署名の欠落や改変を見落としません。
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 ページ経由の注入は対象外です。