[design] CapabilityProfile + provenance log + safekey の normative spec

[sotashimozono]

Filed by Claude (Anthropic, AI agent operating under souta's GitHub auth) as a gap-fill discussion. Spawned from cross-references in #16 / #1 / #12 reviews — these specs are referenced but never fully specified.

Question

3 つの低レベル spec を本 Discussion で normative spec として lock する。 これらは複数 Discussion から refer されるが、 どこにも完全な仕様が無い:

1. CapabilityProfile ([legal] Legal posture, tool neutrality framing, and required safeguards #16 §7 / [design] APS / Elsevier / Springer TDM の実装優先度 #5 §8 / [design] Citation graph 機能を Phase 1 必須にするか後ろ倒しか #6 §2 / [design] MCP server が公開する tool の名前と signature #8 から refer)
2. Provenance log format (JSON Lines + hash chain) ([security] threat model + security 対策 #12 §threat 4 / [legal] Legal posture, tool neutrality framing, and required safeguards #16 §5 から refer)
3. safekey algorithm + reference test vectors ([design] BiblioFetch.jl との共存モデル #1 §Contract 4 / [design] BiblioFetch.jl と TOML store の互換性レベル #2 §規律 4 から refer)

各 spec は docs/ 配下の normative document として Phase 0 から commit される (#11 review §2)。

---

1. CapabilityProfile spec

Rust type

// crates/doiget-core/src/capability.rs

use secrecy::Secret;
use chrono::{DateTime, Utc};

#[derive(Debug, Clone)]
pub struct CapabilityProfile {
    pub oa: AlwaysOn,
    pub metadata: MetadataAccess,
    pub tdm_elsevier: Option<TdmGrant>,
    pub tdm_aps: Option<TdmGrant>,
    pub tdm_springer: Option<TdmGrant>,
    pub rate_limits: RateLimits,
}

#[derive(Debug, Clone, Copy)]
pub struct AlwaysOn;   // unit struct — Tier 1 OA は常に許可

#[derive(Debug, Clone)]
pub struct MetadataAccess {
    pub openalex: bool,            // Phase 4 で true になりうる
    pub semantic_scholar: bool,
    pub doaj: bool,
}

#[derive(Debug, Clone)]
pub struct TdmGrant {
    pub api_key: Secret<String>,           // bundled forbidden (#16 §1)
    pub agreed_at: DateTime<Utc>,          // env var を起動時に検出した時刻
    pub agree_env_var: String,             // どの env var で同意したか (e.g. "DOIGET_AGREE_TDM_ELSEVIER")
}

#[derive(Debug, Clone, Copy)]
pub struct RateLimits {
    pub max_concurrent_fetches: u32,    // hard-code 5 (#16 §8)
    pub max_fetches_per_second: f32,    // hard-code 5.0
    pub per_source_backoff_ms: u64,     // hard-code 200
}

Resolution algorithm

impl CapabilityProfile {
    pub fn from_env() -> Result<Self, CapabilityError> {
        let oa = AlwaysOn;
        let metadata = MetadataAccess {
            openalex: env::var("DOIGET_ENABLE_OPENALEX").is_ok(),
            semantic_scholar: env::var("DOIGET_ENABLE_S2").is_ok(),
            doaj: env::var("DOIGET_ENABLE_DOAJ").is_ok(),
        };
        let tdm_elsevier = read_tdm_grant("DOIGET_AGREE_TDM_ELSEVIER", "DOIGET_KEY_ELSEVIER")?;
        let tdm_aps = read_tdm_grant("DOIGET_AGREE_TDM_APS", "DOIGET_KEY_APS")?;
        let tdm_springer = read_tdm_grant("DOIGET_AGREE_TDM_SPRINGER", "DOIGET_KEY_SPRINGER")?;
        let rate_limits = RateLimits::HARD_CODED;
        Ok(Self { oa, metadata, tdm_elsevier, tdm_aps, tdm_springer, rate_limits })
    }
}

fn read_tdm_grant(agree_var: &str, key_var: &str) -> Result<Option<TdmGrant>, CapabilityError> {
    let agreed = matches!(env::var(agree_var).as_deref(), Ok("1"));
    let key = env::var(key_var).ok();
    match (agreed, key) {
        (true, Some(k)) => Ok(Some(TdmGrant {
            api_key: Secret::new(k),
            agreed_at: Utc::now(),
            agree_env_var: agree_var.to_string(),
        })),
        (true, None) => Err(CapabilityError::AgreedButNoKey { agree_var: agree_var.into(), key_var: key_var.into() }),
        (false, Some(_)) => Err(CapabilityError::KeyButNotAgreed { agree_var: agree_var.into() }),
        (false, None) => Ok(None),
    }
}

重要原則:

• env var 不在 = None、 これは feature flag absent 時の default
• agree=1 だが key 不在は error (sloppy 設定の検出、 silent skip しない)
• key 在るが agree 未設定も error (agree env を要求して user の同意を確実に取る)

Source::fetch への注入

pub trait Source: Send + Sync {
    fn name(&self) -> &str;

    fn can_serve(&self, profile: &CapabilityProfile, ref_: &Ref) -> bool;

    async fn fetch(
        &self,
        ref_: &Ref,
        profile: &CapabilityProfile,
        ctx: &FetchContext,
    ) -> Result<FetchResult, FetchError>;
}

各 source 実装が profile を見て自分が serve 可能か判断する。 unauthorized fetch の早期 reject:

impl Source for ElsevierTdm {
    fn can_serve(&self, p: &CapabilityProfile, _: &Ref) -> bool {
        p.tdm_elsevier.is_some()
    }

    async fn fetch(&self, ..., profile: &CapabilityProfile, ...) -> Result<...> {
        let grant = profile.tdm_elsevier.as_ref()
            .ok_or(FetchError::CapabilityDenied)?;
        // grant.api_key を使って fetch
    }
}

Startup banner (auditability)

doiget 起動時、 stderr に 1 行だけ 現在の profile を出力:

[doiget] capability: oa=on metadata=[openalex] tdm=[elsevier:agreed_2026-05-05T08:00:00Z]

これで user / log review 時に「この session で何が許可されていたか」が即わかる。 MCP mode (#14 §2) でも stderr なので JSON-RPC noise にはならない。

---

2. Provenance log format

Format: JSON Lines

各行が独立した JSON object。 改行は LF only (\n)。 timezone は UTC 固定。

Schema (1 行)

{
  "ts": "2026-05-05T08:30:12.345Z",
  "ts_seq": 1234,
  "event": "fetch",
  "ref": "10.1234/example",
  "source": "unpaywall",
  "result": "ok",
  "license": "CC-BY-4.0",
  "size_bytes": 1234567,
  "store_path": "papers/10.1234_example.pdf",
  "capability": "oa",
  "session_id": "01JCKZ7Q...",
  "prev_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "this_hash": "abcdef..."
}

Fields (NORMATIVE)

Field	Type	Required	意味
ts	RFC3339 UTC timestamp	yes	event 時刻、 millisecond 精度
ts_seq	u64	yes	session 内 monotonic seq (collision 回避)
event	enum	yes	"fetch" / "resolve" / "store_write" / "capability_resolved" / "session_start" / "session_end"
ref	string	event 依存	DOI / arXiv id
source	enum	event 依存	"crossref" / "unpaywall" / "arxiv" / "openalex" / "s2" / "doaj" / "tdm-elsevier" / "tdm-aps" / "tdm-springer"
result	enum	yes	"ok" / "err" / "denied"
license	string	event=fetch	OA license string、 OA でなければ "unknown"
size_bytes	u64	event=fetch ok	PDF size
store_path	string	event=fetch ok	relative path under store root
capability	enum	yes	この event を許可した capability ("oa" / "metadata" / "tdm-*")
session_id	string (ULID)	yes	1 process invocation per session
prev_hash	hex string	yes (除く 1 行目)	直前 row の this_hash
this_hash	hex string	yes	本 row の SHA256 (prev_hash 含む全 field over canonical JSON)

Hash chain

各 row の this_hash = SHA256(canonical JSON serialization of (row except this_hash))。 改竄検出のため、 prev_hash で chain を構成。

tools/audit-log (Phase 3+) で全 chain を再計算 / 検証可能。

Failure mode

• write 失敗 → fail-closed: 該当 fetch を error 化、 stdout / MCP に INTERNAL_ERROR を返す
• log file fs full → fetch 全停止 ([security] threat model + security 対策 #12 §threat 4 と整合)
• log directory が startup 時に存在しない → 自動作成、 first row は event=session_start で初期化

Rotation / retention

• 1 file が 100MB を超えたら access.log.YYYY-MM-DD.gz に rotate (gzip compression)
• 90 日 経過した log file を auto-delete ([legal] Legal posture, tool neutrality framing, and required safeguards #16 §5)
• --retention <days> flag で override 可、 0 = 永久保持
• rotation 時 hash chain は新 file 1 行目で再起動 (prev_hash = "GENESIS")

Auditing tool

doiget audit-log --verify           # hash chain 検証
doiget audit-log --since 2026-01-01 # 期間 filter
doiget audit-log --source elsevier  # source filter

---

3. safekey algorithm

Goal

任意の DOI / arXiv id から、 cross-platform / cross-tool で bit-identical な safekey 文字列を導出する deterministic mapping。 path traversal を防ぎ、 collision を防ぐ。

Constraints

• DOI suffix は [A-Za-z0-9._/()-] 等を含みうる、 / を含む
• Windows / Linux / macOS で同じ output
• 256 chars 以下 (filesystem 制約)
• 視認性: original ref から safekey を見て元の ref が想像できると嬉しい

Algorithm (proposal)

pub fn safekey(ref_: &Ref) -> Safekey {
    let raw = match ref_ {
        Ref::Doi(d) => format!("doi_{}", d.as_str()),
        Ref::Arxiv(a) => format!("arxiv_{}", a.as_str()),
    };

    let escaped: String = raw.chars().map(|c| match c {
        'A'..='Z' | 'a'..='z' | '0'..='9' | '.' | '-' | '_' => c,
        _ => '_',  // 全 unsafe char を _ に置換
    }).collect();

    if escaped.len() > 200 {
        // 長い ref は前 192 chars + "_" + first 8 hex of SHA256 で disambiguate
        let hash = hex::encode(&Sha256::digest(raw.as_bytes())[..4]);
        format!("{}_{}", &escaped[..192], hash)
    } else {
        escaped
    }
}

Reference test vectors (snippet、 full は docs/SAFEKEY.md で 100 件)

Input ref	safekey
doi:10.1234/example	doi_10.1234_example
doi:10.1103/PhysRevLett.130.200601	doi_10.1103_PhysRevLett.130.200601
doi:10.1016/S0370-1573(98)00122-3	doi_10.1016_S0370-1573_98_00122-3
arxiv:2401.12345	arxiv_2401.12345
arxiv:2401.12345v2	arxiv_2401.12345v2
doi:10.1234/超長い記号()()/[]{}=<>?@#$%/very-long...	doi_10.1234______________very-long..._XXXXXXXX (truncated + 8-hex disambig)

BiblioFetch.jl 互換性

• BiblioFetch.jl 側の現行 algorithm が上記と異なる場合、 BiblioFetch.jl 側を本 spec に合わせて更新 することを推奨 (collision-safety 観点で本 spec のほうが strict)
• BiblioFetch.jl の H2 issue ([design] BiblioFetch.jl との共存モデル #1 で言及) が本 spec で解決される
• doiget Phase 0 commit までに docs/SAFEKEY.md の 100 vectors を 両 implementation で pass する状態にする

Property tests

proptest! {
    #[test]
    fn safekey_is_path_safe(ref_ in arb_ref()) {
        let key = safekey(&ref_);
        assert!(!key.contains(".."));
        assert!(!key.contains('/'));
        assert!(!key.contains('\\'));
        assert!(key.chars().all(|c| c.is_ascii_alphanumeric() || c == '.' || c == '-' || c == '_'));
    }

    #[test]
    fn safekey_is_deterministic(ref_ in arb_ref()) {
        assert_eq!(safekey(&ref_), safekey(&ref_));
    }

    #[test]
    fn safekey_collision_resistant(r1 in arb_ref(), r2 in arb_ref()) {
        prop_assume!(r1 != r2);
        assert_ne!(safekey(&r1), safekey(&r2));
    }
}

---

Open questions

1. CapabilityProfile を 実行中に reload できるか? (env var 変更後に restart 不要にしたい場合)。 reviewer 推奨: 不可。 reload で security guarantee が緩む
2. provenance log の session_id は何で生成? ULID? UUID v4? reviewer 推奨: ULID (時系列 sortable、 26 chars)
3. safekey が衝突した場合 (2 ref が同 safekey に map) の挙動: error / rename suffix / overwrite warn? reviewer 推奨: error + diagnostic log
4. ~/.config/doiget/credentials.toml の permission 0600 でない時の起動時挙動 ([legal] Legal posture, tool neutrality framing, and required safeguards #16 §open-q-2): reviewer 推奨: warn + 続行 (refuse は user が困る、 silent は危険)

Decision proposal

本 3 spec を Phase 0 で docs/CAPABILITY.md / docs/PROVENANCE_LOG.md / docs/SAFEKEY.md の 3 つの NORMATIVE doc として確定。 全 implementation (Rust doiget、 Julia BiblioFetch.jl) はこれを reference として実装する。

ADR docs/DECISIONS/0005-capability-profile.md / 0006-provenance-log.md / 0007-safekey.md で永続記録。

---

Reviewer: Claude (Anthropic). Filed 2026-05-05.