SPECIFICATION

第 2 章：データモデル

本章は CAP プロトコルにおけるコアデータ構造を定義する。フィールド名、型、制約、デフォルト値を含む。本章のフィールド定義は規範的である——CAP プロトコルに適合するすべての実装は MUST 本章定義に従ってこれらのデータ構造を生成および解析する。

schema/{version}/schema.json は本章データ構造の形式化補足を提供する。schema.json と本章記述に衝突がある場合、schema.json を優先する。

2.1 データ型規約

本仕様は以下の基本型を用いてフィールドを記述する：

型説明エンコーディング
stringUTF-8 文字列UTF-8 バイトシーケンス
bytesバイトシーケンス原始バイト
uint32 / uint64符号なし整数ビッグエンディアン
timestampUnix タイムスタンプ（秒）uint64
uuidRFC 4122 UUID v716 バイト
enum列挙値文字列リテラル
array<T>型 T の要素の順序付き集合配列
map<K,V>K から V へのマッピングオブジェクト

フィールド制約は以下の記法を用いる：

  • required：フィールドは MUST 出現し、値は null でない
  • optional：フィールドは MAY 出現し、欠如時は未設定とみなす
  • unique：フィールド値はシステム範囲内で一意
  • len(N..M)：文字列/バイト長は N から M の間（端点含む）
  • regex(...)：フィールド値は MUST 指定正規表現にマッチする

2.2 識別子

CAP プロトコルにおけるコア識別子は MUST グローバルな一意性を満たす。本節は各種識別子の形式と生成規則を定義する。

2.2.1 Fay_ID

Fay_ID は Fay インスタンスを一意に識別する。

属性値
型string
形式"fay:" + uuid_v7
長さ40 文字（プレフィックス含む）
一意性グローバル一意
生成者アイデンティティ管理サブシステム（CAP プロトコル範囲外）

例：fay:01927b34-7e21-7c4d-a89f-1234567890ab

2.2.2 Terminal_ID

Terminal_ID は端末デバイスを一意に識別する。

属性値
型string
形式"terminal:" + uuid_v7
長さ45 文字（プレフィックス含む）
一意性グローバル一意
生成者Registration_Authority

2.2.3 Resource_ID

Resource_ID は端末上の具体的なリソースを識別する。

属性値
型string
形式terminal_id + "/" + resource_path
長さ最長 256 文字
一意性端末範囲内で一意
生成者端末オペレーティングシステム

resource_path は MUST 正規表現 ^[a-zA-Z0-9._\-/]+$ を満たす。

例：terminal:01927b34-.../device/camera/front

2.2.4 Descriptor_ID

Descriptor_ID は 1 つの Authorization_Descriptor を一意に識別する。

属性値
型uuid
形式UUID v7
一意性グローバル一意（すべての Descriptor_Issuer 範囲内）
生成者Descriptor_Issuer

失効リストは Descriptor_ID を用いて失効済みクレデンシャルを識別する。Descriptor_Issuer は MUST NOT 既使用の Descriptor_ID を再利用する。

2.2.5 Session_ID

Session_ID はアクティブなセッションを一意に識別する。

属性値
型uuid
形式UUID v7
一意性端末範囲内で一意
生成者端末 Protocol_Engine
ライフサイクルセッションがアクティブな間のみ有効、セッション終了後 ID は再利用しない

2.3 Authorization_Descriptor

Authorization_Descriptor はオフライン認可のコアデータ構造である。1 つの Authorization_Descriptor は 2 つの部分から構成される：ペイロード（payload） と 署名（signature）。

2.3.1 トップレベル構造

AuthorizationDescriptor {
  required version       : uint32
  required payload       : DescriptorPayload
  required signature     : DescriptorSignature
}
フィールド説明
versionプロトコルバージョン番号、v1 実装は MUST 1 に設定する
payload認可情報ペイロード（§2.3.2 を参照）
signaturepayload に対するデジタル署名（§2.3.3 を参照）

2.3.2 DescriptorPayload

DescriptorPayload {
  required descriptor_id   : Descriptor_ID
  required issuer_id       : string
  required subject_fay_id  : Fay_ID
  required terminal_id     : Terminal_ID
  required grants          : array<Grant> (len 1..256)
  required issued_at       : timestamp
  required not_before      : timestamp
  required not_after       : timestamp
  optional grantor_id      : string
  optional metadata        : map<string, string>
}
フィールド制約説明
descriptor_idrequired, unique本クレデンシャルのグローバル一意識別子
issuer_idrequired発行者識別子、鍵信頼パスにおける Descriptor_Issuer に対応
subject_fay_idrequired認可される Fay 識別子
terminal_idrequired認可範囲を限定する端末識別子
grantsrequired, 1..256 個の要素具体的認可項目リスト（§2.3.4 を参照）
issued_atrequired発行時刻
not_beforerequired, ≥ issued_at発効開始時刻
not_afterrequired, > not_before失効時刻
grantor_idoptional認可者識別子（Natural_Person または Official_Post）
metadataoptional発行者カスタムメタデータ、プロトコルセマンティクスに影響しない

実装は MUST 以下の条件を満たさない Authorization_Descriptor を拒否する：

  1. not_after - not_before > 90 日：本仕様は単一クレデンシャルの最長有効期間を 90 日に限定する
  2. not_before > 現在時刻 + 24 時間：早すぎる発効のクレデンシャル発行を禁止する（事前発行濫用を防止）
  3. grants 配列が空：認可項目のないクレデンシャルは無意味

2.3.3 DescriptorSignature

DescriptorSignature {
  required algorithm       : enum["ed25519", "ecdsa-p256-sha256"]
  required key_id          : string
  required signature_value : bytes
}
フィールド説明
algorithm署名アルゴリズム、第 8 章を参照
key_id署名に使用された鍵識別子、Verification_Key 識別子に対応
signature_valuepayload の CBOR シリアライズバイトに対する署名結果

署名入力：DescriptorPayload を RFC 8949 CBOR 確定性エンコーディング（Deterministic Encoding）でバイトシーケンスにシリアライズし、署名アルゴリズムの入力とする。

2.3.4 Grant

Grant {
  required resource_pattern : string
  required modes            : array<AccessMode> (len 1..4)
  optional constraints      : map<string, string>
}
フィールド説明
resource_patternリソースマッチングパターン（§2.3.5 を参照）
modes認可されたアクセスモードリスト、要素型 AccessMode
constraints付加制約（時間ウィンドウ、地理フェンス等）、プロトコルセマンティクスへの影響は第 7 章を参照

2.3.5 リソースマッチングパターン

resource_pattern は以下のマッチング構文をサポートする：

  • 完全一致：terminal:xxx/device/camera/front
  • ワイルドカードマッチング：terminal:xxx/device/camera/*（当該端末下のすべてのカメラにマッチ）
  • 全端末マッチング：terminal:xxx/device/camera/**（当該パス下のすべての階層にマッチ）

実装は MUST：

  1. 上記 3 種類の構文のみをサポートし、他の特殊文字を含むパターンを拒否する
  2. ワイルドカード * は単一階層のパスセグメントのみマッチする
  3. ワイルドカード ** はパターン末尾にのみ出現できる

2.3.6 AccessMode

AccessMode = enum["read", "write", "execute", "configure"]

各アクセスモードのセマンティクスは第 7 章を参照。

2.4 Trusted_Ticket

Trusted_Ticket はオンライン認可クレデンシャルである。その構造は RFC 7515 JWS Compact Serialization に基づく。

2.4.1 トップレベル構造

Trusted_Ticket は JWS 文字列で、. で区切られた 3 つの部分から構成される：

base64url(header) . base64url(payload) . base64url(signature)

2.4.2 Header

TicketHeader {
  required alg : enum["EdDSA", "ES256"]
  required typ : "cap-ticket+jws"
  required kid : string
}
フィールド説明
alg署名アルゴリズム（§8 と一致）
typ固定値 "cap-ticket+jws"、チケット種別の区別に使用
kid鍵識別子、署名検証に使用

2.4.3 Payload

TicketPayload {
  required jti  : uuid                    // チケット一意 ID
  required iss  : string                  // Ticket_Issuer 識別子
  required sub  : Fay_ID                  // 認可される Fay
  required aud  : Terminal_ID             // 対象端末
  required iat  : timestamp               // 発行時刻
  required nbf  : timestamp               // 発効開始時刻
  required exp  : timestamp               // 失効時刻
  required grants : array<Grant>          // §2.3.4 と同構造
  optional convertible : boolean (default true)  // Authorization_Descriptor に変換可能か
}

実装は MUST exp - nbf > 7 日 の Trusted_Ticket を拒否する。オンラインチケットの最長有効期間はオフライン認可より短く、オンライン失効メカニズムが速やかに発効することを保証する。

2.4.4 Trusted_Ticket から Authorization_Descriptor への変換

convertible == true の場合、端末は MAY Trusted_Ticket をローカル Authorization_Descriptor 形式に変換し、オフライン使用に供する。変換規則：

TicketPayload フィールドDescriptorPayload フィールドへのマッピング
jtidescriptor_id
ississuer_id
subsubject_fay_id
audterminal_id
iatissued_at
nbfnot_before
expnot_after（ただし MUST iat + 7 日 を超えない）
grantsgrants

変換後の Authorization_Descriptor は端末がローカル保管鍵を用いて再署名し、署名 key_id は変換元としてマークされる（第 4 章を参照）。元の Trusted_Ticket の署名情報は MUST 監査用に metadata に保持する。

2.5 Session

Session は端末内部のセッション状態構造であり、プロトコルメッセージで完全な構造を伝送しない。本節は Session のフィールドを定義し、状態機械とインタフェース規約を規範化する。

Session {
  required session_id          : Session_ID
  required fay_id              : Fay_ID
  required runtime_id          : string
  required resource_id         : Resource_ID
  required access_mode         : AccessMode
  required granted_modes       : array<AccessMode>
  required state               : SessionState
  required created_at          : timestamp
  required last_heartbeat_at   : timestamp
  required credential_ref      : CredentialRef
}

SessionState = enum[
  "creating",
  "active",
  "handover_pending",
  "terminating",
  "terminated"
]

CredentialRef {
  required type   : enum["descriptor", "ticket"]
  required id     : string                     // descriptor_id または jti
  required not_after : timestamp
}

SessionState 状態機械は第 5 章を参照。

2.6 プロトコルメッセージカプセル化

iFay_Runtime と Protocol_Engine の間のすべてのメッセージは以下のカプセル化構造を共有する：

ProtocolMessage {
  required version         : uint32 (= 1)
  required message_id      : uuid
  required message_type    : string
  required timestamp       : timestamp
  required sender_id       : string
  required body            : object
  optional correlation_id  : uuid
}
フィールド説明
versionプロトコルバージョン番号、v1 では 1
message_id本メッセージの一意識別子
message_typeメッセージ種別リテラル（例："AuthRequest"）
timestampメッセージ送信時刻
sender_id送信者識別子（runtime_id または terminal_id）
bodyメッセージ本体、構造は message_type で決定される
correlation_id関連する要求メッセージ ID（応答メッセージは MUST このフィールドを設定する）

各 message_type に対応する body 構造は対応する章で定義する。

2.7 Verification_Key

Verification_Key は端末が保持する署名検証鍵である。

VerificationKey {
  required key_id        : string
  required algorithm     : enum["ed25519", "ecdsa-p256-sha256"]
  required key_material  : bytes              // 公開鍵バイト
  required issuer_id     : string             // 当該鍵に対応する発行者識別子
  required valid_from    : timestamp
  optional valid_until   : timestamp
  required source        : enum["pre-installed", "ra-distributed"]
}
フィールド説明
key_id鍵識別子、DescriptorSignature.key_id に対応
algorithm当該鍵がサポートする署名アルゴリズム
key_material公開鍵の原始バイト、エンコーディングは algorithm で決定（第 8 章を参照）
issuer_id当該鍵に対応する Descriptor_Issuer 識別子
valid_from鍵発効開始時刻
valid_until鍵失効時刻、未設定は長期有効を意味する
source鍵の出所：pre-installed（端末出荷時プリインストール）または ra-distributed（Registration_Authority がオンライン配布）

端末は MUST すべての Verification_Key を安全に保管する（第 8 章を参照）。

2.8 失効声明

失効声明はあるクレデンシャルが失効したことを端末に通知するために使用される。

RevocationStatement {
  required version              : uint32 (= 1)
  required revocation_id        : uuid
  required target_descriptor_id : Descriptor_ID
  required issuer_id            : string
  required revoked_at           : timestamp
  optional reason               : enum["unspecified", "compromised", "superseded", "no_longer_needed"]
  required signature            : DescriptorSignature
}

失効声明は MUST 元の Authorization_Descriptor の issuer_id によって発行および署名される。

2.9 シリアライゼーションと伝送

CAP プロトコルは以下のシリアライゼーション形式を使用する：

データ構造シリアライゼーション形式用途
AuthorizationDescriptorRFC 8949 CBOR（確定性エンコーディング）オフライン保管と伝送
Trusted_TicketRFC 7515 JWS Compact Serializationオンライン伝送
ProtocolMessageJSON（UTF-8）iFay_Runtime ↔ Protocol_Engine 相互作用
RevocationStatementRFC 8949 CBOR（確定性エンコーディング）失効リスト配布

実装は MAY ProtocolMessage の伝送層で JSON の代わりに CBOR を使用してオーバーヘッドを削減できるが、schema.json で定義されたフィールド名とセマンティクスは MUST 一致させる。