ドキュメント

連署ワークフロー

最初の署名者は、文書の完了に必要な連署を require に宣言できます。宣言は署名対象ペイロードに含まれるため、後続の署名者が書き換えることはできません。検証者は宣言と後続の署名を照合し、合意の状態を報告します。

require の宣言

require は折り返し値で、1行に1つずつ次の3種類の行を記述します。段階行を用いない場合、すべての要件行が1つの段階となり、全員の署名を必要とします。

行の種類 構文 意味
要件行 <method>:<signer> [role] 必要な署名者。role を付与すると、その役割の署名に限定する。
段階行 step <n> [any <m>] 以降の要件行が属する段階を開始する。any m は、その段階の要件行のうち m 件で成立することを示す。省略時は全員。
順序行 order pending|guide|strict 順番より前に署名した場合の扱い。最初の行にのみ記述でき、省略時は pending。

形式不正(malformed)となる値

  1. 順序行が最初の行以外にある。
  2. 段階行を用いる場合に、最初の段階が step 1 でない、または番号が連続しない。
  3. 要件行のない段階がある、または any m の m がその段階の要件行の件数を超える。
  4. 同じ段階に、method・signer・role が同一の要件行が重複している。
  5. v が 0.0.1 のブロックに段階行または順序行がある。
  6. 要件行の method が tsa である(0.0.2 以降)。
3段階の承認フロー
require: |
  order strict
  step 1
  dns:example.com approver
  step 2 any 2
  git-hosting:github.com/bob reviewer
  git-hosting:github.com/carol reviewer
  git-hosting:github.com/dave reviewer
  step 3
  dns:legal.example.com
  1. step 1全員
    • example.com approver
  2. step 23人中2人
    • github.com/bob
    • github.com/carol
    • github.com/dave
  3. step 3全員
    • legal.example.com

example.com の承認の後に、3人のうち2人がレビューし、最後に legal.example.com が署名すると完了します。

段階行のない宣言
require: |
  dns:example.com approver
  git-hosting:github.com/bob

2名の署名がそろえば完了します。署名の順番は問いません。

照合の規則

要件は、宣言したブロックより後ろにあるブロックと照合します。照合に用いるのは、署名によって認証される method と signer です。

要件を満たすブロック

  1. 宣言したブロックより後ろにあり、ステータスが valid である。
  2. method と signer が要件行と一致する。dns の signer は大文字と小文字を区別せず、末尾のドットも無視して比較する。
  3. 要件行に role があれば、同じ role を持つ。role は署名者自身の申告にすぎないため、単独では照合の根拠にならない。
  4. 1つのブロックは、同じ宣言の中では1件の要件にのみ数える。any 2 の段階は、異なる2件の要件が満たされて成立する。

要件を満たさないブロック

  • scope を持つブロック。宣言したブロックを署名対象に含まず、同じセクションを持つ別の文書へ移しても有効なままであるため。
  • tsa ブロック。署名者を持たないため。tsa: の要件行も記述できない。
  • invalid、unresolved などのブロック。ただし unresolved のブロックが宣言した要件は収集するため、確認しきれなかったチェーンが完了と報告されることはない。
  • 宣言したブロックより前にあるブロック。

複数のブロックが require を宣言した場合は宣言ごとに評価し、すべての宣言が成立した時点で complete となります。

順序の扱い(order)

段階のある宣言では、前の段階が成立する前に署名される場合があります。その署名の扱いは、宣言した署名者が順序行で選択します。

order 順番より前の署名 報告 合意への影響
pending 数えない 不足する連署の一覧に、順番より前に署名済みである旨(early)を付記 その署名者が改めて署名するまで pending
guide 数える 順序違反(violations)として報告 影響しない。ほかが満たされれば complete
strict 数える 順序違反(violations)として報告 violated。文書は不合格(終了コード 1)

前の段階の成立位置は、その段階の m 件目を満たしたブロックの位置です。step 1 の署名は、宣言したブロックより後ろであれば常に順番どおりです。

例:bob が承認より前に署名した場合
  1. #1github.com/alicerequire を宣言
  2. #2github.com/bobstep 2(順番より前)
  3. #3example.comstep 1 の承認
require: |
  order <mode>
  step 1
  dns:example.com approver
  step 2
  git-hosting:github.com/bob
pending pending #2 は数えない。step 2 の bob が不足(early: true)。bob が改めて署名すれば完了。
guide complete #2 を数えて完了。#2 を順序違反として報告する。
strict violated #2 を順序違反とし、合意は不成立。

合意ステータスと終了コード

検証者は、すべてのブロックの判定とは別に、宣言全体の合意ステータスを報告します。

status 意味 終了コード
none require の宣言がない 0
complete すべての段階が成立した 0
pending 不足する連署がある。各要素はあと何件必要か(need)、待機中の段階(blocked_by)、順番より前の署名(early)を持つ 5
violated order strict の順序違反がある。違反したブロックを列挙する 1

すべての署名が有効でも、合意が pending の文書は verified but pending です。検証者はこれを完了として提示してはなりません。violated の文書は合意済みとして提示してはなりません。

JSON 出力の agreement(上の例を pending で宣言した場合)
"agreement": {
  "status": "pending",
  "required": [
    { "method": "dns", "signer": "example.com", "role": "approver",
      "declared_by": 1, "step": 1, "any": 1 },
    { "method": "git-hosting", "signer": "github.com/bob",
      "declared_by": 1, "step": 2, "any": 1 }
  ],
  "missing": [
    { "method": "git-hosting", "signer": "github.com/bob",
      "declared_by": 1, "step": 2, "any": 1, "need": 1, "early": true }
  ],
  "violations": []
}

段階行のない宣言では、step は 1、any は要件行の件数となります。

CLI と CI での利用

mdsig sign の --require は1回につき1行を受け取り、指定した順に行を並べます。値全体は署名の前に上記の規則で検査します。

宣言を含めて署名する
mdsig sign plan.md -m git-hosting -s github.com/alice -r author \
  --require "order guide" \
  --require "step 1" --require "dns:example.com approver" \
  --require "step 2 any 2" \
  --require "git-hosting:github.com/bob" \
  --require "git-hosting:github.com/carol" \
  --require "git-hosting:github.com/dave"

デモとエディタでは、連署の追加画面の詳細設定で同じ宣言を作成できます。

CI で完了を確認する(GitHub Actions)
- run: go install mdsig.dev/cmd/mdsig@latest
- run: mdsig verify docs/plan.md

連署が不足している間、mdsig verify は終了コード 5 を返すため、このジョブは失敗します。ブランチ保護の必須チェックに設定すれば、全員の署名がそろうまでマージできません。

形式 0.0.1 のブロックが宣言した要件は従来の規則で評価します。段階はなく、1つのブロックが複数の要件を満たしてもかまいません。

仕様書 §5.8 必須の連署CLI 仕様 §3.1 mdsig sign