はじめて立ち上げるとき¶

NAAN を持っていない状態から、組織が採番できる状態までの通し。arkhe の外で起きることが半分を占めるので、そこも含めて並べる。

① ARK Alliance に NAAN を申請する          arkhe の外
② arkhe を立てる                            → デプロイ
③ NAAN registry に解決先の URL を登録する   arkhe の外
④ arkhe に NAAN を登録し、方針を述べる       arkhe naan add
⑤ 組織を迎え、名前空間を委譲する             arkhe onboard
⑥ 組織の約束の水準を確かめる                 arkhe manager commitment
⑦ 人と機械を登録する                         arkhe client add
⑧ 以後：ローテーション・承継・離脱

① NAAN を申請する¶

ARK Alliance から無償で交付される。登録組織に払う金も、維持する会員資格も無い。

申請には、その NAAN で何をするつもりかを述べる欄がある。ここで書いたことが ④ 以降で台帳に載る内容と一致していなければならない。 別々に考えると、外向きの宣言と実際の運用がずれる。

② arkhe を立てる¶

デプロイを見ること。③ の前に立てる必要がある——③ で登録するのはこのリゾルバの URL だからである。

③ NAAN registry に解決先の URL を登録する¶

ここが抜けると n2t.net/ark:/99999/… は自分のところに届かない。 NAAN の交付は番号をもらって終わりではなく、registry のエントリに自分のリゾルバの URL を書くまでが一続きである。

リゾルバの URL が変わったらそのたびに更新する。ここは自動では追随しない。

自分の側でも公開している

arkhe は /.well-known/ark で、その NAAN の採番をどこで行っているかを返す。 registry の代わりにはならない（外から見つけてもらう経路は registry だけ）が、採番の窓口が別にある構成では、クライアントがどこへ行けばよいか分かる。

④ NAAN を登録し、方針を述べる¶

arkhe naan add 99999 "○○大学" \
  --policy "NP | NR, OP, CC | 2026 | https://example.ac.jp/ark-policy"

NAA ポリシーを述べるのはここ。 事務手続きではなく、arkhe にとって中心的な宣言である——ARK には代わりに永続性を保証してくれる登録組織がいないので、約束はこちらのものであり、その中身も自分で述べるしかない。述べていないものは ?? で答えられない。

--authoritative（既定）は「この NAAN の未知の名前には 404 と答えてよい」という意味である。採番を他所が続けている NAAN を引き受けた場合は --authoritative false と --redirect を付ける。この 2 つは対で、片方だけでは登録できない。

⑤ 組織を迎え、名前空間を委譲する¶

arkhe onboard 99999 "○○研究所" --shoulder /x9 --commitment permanent-stable

組織の登録と shoulder の委譲は必ず対で起きる。 分けられない——名前空間を持たない組織は採番できないので、台帳に置く意味がない。

shoulder の設計は先に決めておくこと。一度配ったら取り戻せない（NR を宣言している以上、既存の ARK は解決し続ける）。使わなくなった名前空間は消すのではなく retired にする。

arkhe shoulder add 99999 /y2 --reserve   # 将来のために押さえるだけ
arkhe shoulder list --naan 99999

⑥ 約束の水準を確かめる¶

arkhe manager commitment --list
arkhe manager list
arkhe manager commitment 1 permanent-stable

管理画面からも変えられる（一覧の組織行の「操作」）。ここは組織管理者自身も変えられる——約束は組織自身のもので、述べる主体が述べられなければ意味がない。

--commitment を付けずに迎えると既定の permanent-dynamic が付く。既定のまま置いてはいけない。 この値は ? と ?? でそのまま公開されるので、放置すると 組織が述べていない約束を、組織の名前で名乗ることになる。宣言していないものを宣言として出すのは、何も出さないより悪い。

水準は NLM の permanence ratings を採っている（descriptive-only だけは物理オブジェクト向けの追加）。


`not-guaranteed`	約束しない
`permanent-dynamic`	永続。内容は変わりうる
`permanent-stable`	永続。内容は実質的に変わらない
`permanent-unchanging`	永続。内容は変えない
`descriptive-only`	記述だけ（物理オブジェクトなど、対象がオンラインに無い）

水準を下げるのも正当な操作である。 守れない約束を掲げ続けるより、実態に合わせて言い直すほうが誠実で、?? を尋ねる意味も保たれる。

⑦ 人と機械を登録する¶

この 2 つは混ぜられない。

	名乗り方	持てる資格情報
人（組織管理者など）	外部ログイン（OIDC / proxy）またはパスワード	API キー・client_secret は持てない
機械（リポジトリ本体など）	API キー / client_secret	パスワードは持てない

# 組織管理者。client_id は認可サーバが返す識別子（メール・eppn など）
arkhe client add admin@example.ac.jp 99999 --person --manager 1

# リポジトリ本体。shoulder に固定する
arkhe client add repo-web-api 99999 --shoulder 1 --scopes "ark:mint ark:update"
arkhe client key repo-web-api          # 平文はこの一度だけ

人に API キーを配らないのは、その人が組織を離れても鍵が生き残るからである。人の失効は認可サーバ側で行い、arkhe はそれに従う。arkhe client passwd は ARKHE_ADMIN_LOGIN=password の構成でだけ使う。

プロセスごとに鍵を分けること。 リポジトリの web / worker などで共有すると、 (1) どれが採番したか追えない (2) 1 つ漏れたら全部を失効させるしかない (3) 用途ごとに scope を絞れない。--shoulder で固定しておけば、鍵が漏れても他組織の名前空間には届かない。

最後に設定を確かめる。

arkhe check

認可サーバに寄せた構成では、登録が紐付けになる¶

ARKHE_AUTH=oidc の構成では、arkhe は鍵を持たない。秘密は認可サーバが作り、そこで失効させる——失効が 1 か所で効くのがこの形の利点である。

それでも登録は要る。 認可サーバで認証できることと、この名前空間を触ってよいことは別だからで、台帳に無い主体は正しいトークンを持っていても通らない。

どこで	何を
認可サーバ	クライアントを作り、秘密を発行・失効させる
arkhe	同じ識別子で利用者を登録し、組織・名前空間・できることを決める

識別子は認可サーバが送ってくる文字列そのままでなければならない。

	照合の順
機械	`azp` → `client_id` → `sub`
人	`preferred_username` → `email` → `sub`

作り方¶

① 認可サーバでクライアントを作る（秘密はここで生まれる）

Keycloak なら、管理コンソールで Clients → Create client。


Client ID	`jc2-web-api`（この文字列を arkhe にも登録する）
Client authentication	有効（＝ confidential。秘密が要る）
Service accounts roles	有効（人を介さずトークンを取るため）
Standard flow	無効（ブラウザで人が入る用途ではない）

秘密は Credentials タブに出る。arkhe はこれを受け取らない——受け取る必要が無いし、持たなければ漏らしようもない。

API からやるなら（setup-arkhe-realm.py が JC2 でやっているのと同じこと）:

curl -X POST "$KC/admin/realms/$REALM/clients" \
  -H "Authorization: Bearer $ADMIN_TOKEN" -H 'Content-Type: application/json' \
  -d '{"clientId":"jc2-web-api","publicClient":false,
       "serviceAccountsEnabled":true,"standardFlowEnabled":false}'

② arkhe に同じ識別子で登録する（到達範囲はここで決まる）

arkhe client add jc2-web-api 99999 --shoulder 1 --scopes "ark:mint ark:update"

arkhe client key は叩かない。 叩いても ARKHE_AUTH に apikey / oauth2 が無ければその鍵は通らない。

入れ替えと停止¶

したいこと	どこで
秘密を入れ替える	認可サーバ（arkhe は何も変えなくてよい）
トークンを出さなくする	認可サーバ。他の資源にも一斉に効く
この名前空間だけ止める	`arkhe client disable jc2-web-api`

止める側が 2 つあるのは利点である。 認可サーバ側は全資源に効き、arkhe 側はこの名前空間にだけ効く。「この組織を ARK からは外すが、他の連携は残す」が、相手の設定を触らずにできる。

oidc の構成では、arkhe client disable が arkhe 側の唯一の止め方になる ——資格情報を持たないので、失効させるものが無い。管理画面の利用者ページからもできる。

⑧ 以後の運用¶

日々あるのは払い出しだけではない。

arkhe client key repo-web-api          # 新しい鍵を先に配る
arkhe client revoke <credential_id>    # 切り替わってから古いほうを止める

古い鍵は自動では失効しない。 並行させて切り替えるためで、失効させても 行は消さない（いつ誰の鍵だったかが残る）。

障害対応には期限つきの逃げ道がある。

arkhe client breakglass 99999 --days 7

組織が統合されたり去ったりしたときは承継と離脱を使う。どちらも 既存の識別子は解決し続ける——これを運用手順として持っていないと、NR の宣言は実際には守れない。

この順番である理由¶

順序	そうしないと
② が ③ より先	登録するリゾルバの URL がまだ無い
④ が ⑤ より先	方針を述べていない NAAN の下に組織ができる
⑤ は不可分	採番できない組織が台帳に残る
⑥ は ⑤ の直後	既定値が組織の宣言として公開されたまま動き出す