ドキュメント
連署ワークフロー
最初の署名者は、文書の完了に必要な連署を require に宣言できます。宣言は署名対象ペイロードに含まれるため、後続の署名者が書き換えることはできません。検証者は宣言と後続の署名を照合し、合意の状態を報告します。
require の宣言
require は折り返し値で、1行に1つずつ次の3種類の行を記述します。段階行を用いない場合、すべての要件行が1つの段階となり、全員の署名を必要とします。
| 行の種類 | 構文 | 意味 |
|---|---|---|
| 要件行 | <method>:<signer> [role] |
必要な署名者。role を付与すると、その役割の署名に限定する。 |
| 段階行 | step <n> [any <m>] |
以降の要件行が属する段階を開始する。any m は、その段階の要件行のうち m 件で成立することを示す。省略時は全員。 |
| 順序行 | order pending|guide|strict |
順番より前に署名した場合の扱い。最初の行にのみ記述でき、省略時は pending。 |
形式不正(malformed)となる値
- 順序行が最初の行以外にある。
- 段階行を用いる場合に、最初の段階が
step 1でない、または番号が連続しない。 - 要件行のない段階がある、または
any mの m がその段階の要件行の件数を超える。 - 同じ段階に、
method・signer・roleが同一の要件行が重複している。 vが0.0.1のブロックに段階行または順序行がある。- 要件行の
methodがtsaである(0.0.2以降)。
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
- step 1全員
- example.com approver
- step 23人中2人
- github.com/bob
- github.com/carol
- github.com/dave
- 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 です。
要件を満たすブロック
- 宣言したブロックより後ろにあり、ステータスが valid である。
methodとsignerが要件行と一致する。dnsのsignerは大文字と小文字を区別せず、末尾のドットも無視して比較する。- 要件行に
roleがあれば、同じroleを持つ。roleは署名者自身の申告にすぎないため、単独では照合の根拠にならない。 - 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 の署名は、宣言したブロックより後ろであれば常に順番どおりです。
- #1github.com/alicerequire を宣言
- #2github.com/bobstep 2(順番より前)
- #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 の文書は合意済みとして提示してはなりません。
"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"
デモとエディタでは、連署の追加画面の詳細設定で同じ宣言を作成できます。
- run: go install mdsig.dev/cmd/mdsig@latest
- run: mdsig verify docs/plan.md
連署が不足している間、mdsig verify は終了コード 5 を返すため、このジョブは失敗します。ブランチ保護の必須チェックに設定すれば、全員の署名がそろうまでマージできません。
形式 0.0.1 のブロックが宣言した要件は従来の規則で評価します。段階はなく、1つのブロックが複数の要件を満たしてもかまいません。