kairos-chain 2.10.1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a238ca634bf5f063383755826516315843ec93b5bbf6a1d9740a76ef367e9450
-  data.tar.gz: f9f3098d7c48248fae20ebaaba7d50353a70792e33dde79c512370017d78ef24
+  metadata.gz: b831eba22baf94d43c7592c5ff2dbf12ca928dcea034b713837bf5253e691f99
+  data.tar.gz: 65c6cd548075ccfccf85d3330548fe51280d39f7c767f6de96c8d64fa5afd799
 SHA512:
-  metadata.gz: b6360bcfaaf7fd8b3920e5b99992cf515cf1448257a29128fc6e33804c872e73339a558829b0ab5891f4699f4117aea71f1fbcfe0ca39d76171de6397138aecb
-  data.tar.gz: 7243622826d6e9b994f29ccb463a6f2b1af78e7e9f3605fc57e247eee1368bcb7ca929406cfa9443228ea3cad0d985f7e78f0def14388b5b03a947c4a1c4b6e7
+  metadata.gz: df294d0d060010e7d589e972ab12164c9cc1451bfd069693d5296bafb9512e95c985d83f4cb849a9d5064f76f0c89b57fbad2245d517f4cc759ce00ebae0f446
+  data.tar.gz: 81a7d541ebf5afc58b938f2b6d2b22c0f38c3c32d69705c2b6cd4074425292a0defa98a4adc74834659bef418a78539b2f7f2a90d48eb26df1f6961c1e41c978

data/CHANGELOG.md

@@ -4,6 +4,44 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [3.0.0] - 2026-03-21
+
+### Added
+
+- **Service Grant SkillSet** (`service_grant`): New SkillSet providing generic, service-independent access control and billing for any KairosChain-based service. Designed and implemented through multi-LLM review methodology (Claude Opus 4.6, GPT-5.4, Composer-2) across 6 phases.
+  - **Phase 0**: Core/Hestia prerequisites — PlaceRouter middleware hooks, session store pubkey_hash support, token store extension
+  - **Phase 1**: Basic access control MVP — GrantManager (auto-grant with ON CONFLICT), UsageTracker (atomic try_consume), AccessChecker (unified pipeline), AccessGate (Path A), PlaceMiddleware (Path B), PlanRegistry (YAML config), PgConnectionPool (thread-safe with circuit breaker), IpRateTracker (anti-Sybil), CycleManager, RequestEnricher, Safety policies, admin tools
+  - **Phase 2**: Synoptis Trust Score integration — TrustScorerAdapter (quality+bridge scoring with caching), anti-collusion PageRank (zero-weight cartel detection), TrustIdentity (canonical `agent://` URIs), PgCircuitBreaker hardening, PoolExhaustedError hierarchy
+  - **Phase 3a**: PaymentVerifier (proof-centric design) — cryptographic signature verification via Synoptis Verifier, issuer authorization, freshness/revocation checks, evidence validation (amount, currency, nonce), idempotent duplicate handling (PG::UniqueViolation rescue), atomic upgrade transaction
+  - **Phase 3b**: Subscription expiry + provider_tx_id — lazy downgrade with atomic conditional UPDATE, concurrent renewal re-read, subscription_duration config validation (1-3650 days), provider_tx_id tracking
+  - **GrantManager-PaymentVerifier unification**: Plan-change SQL consolidated into `apply_plan_upgrade` (single source), event recording unified via `record_plan_upgrade` (called after COMMIT)
+  - 4 billing models: `free`, `per_action`, `metered`, `subscription`
+  - 4 MCP tools: `service_grant_status`, `service_grant_manage`, `service_grant_migrate`, `service_grant_pay`
+  - 3 SQL migrations, YAML-driven plan configuration
+  - Anti-Sybil: IP rate limiting (5/hour, PG-backed), cooldown (5 min write delay), trust score gating
+  - 159 unit tests, 232 assertions
+  - Bundled L1 knowledge: `service_grant_guide`
+
+- **Multi-LLM Design Review L1 Knowledge** (`multi_llm_design_review` v2.1): Methodology and CLI automation for parallel multi-LLM code review.
+  - Auto mode: Codex (GPT-5.4) + Cursor Agent (Composer-2) + Claude Code (Opus 4.6) in parallel
+  - Manual mode fallback with structured prompt generation
+  - Prompt Generation Rules: output filename specification, auto-execution commands
+  - Convergence rules: 2/3 APPROVE = proceed, any REJECT = revise
+  - Observed LLM role differentiation across structural, seam, and safety layers
+
+- **SkillSet Implementation Quality Guide** (`skillset_implementation_quality_guide`): Design constraint tests and wiring checklist derived from Service Grant multi-LLM review experiment.
+
+- **L1 Knowledge**: Service Grant access control documentation (EN/JP) with `readme_order: 4.9`
+
+### Changed
+
+- **HestiaChain PlaceRouter**: Added `register_middleware`/`unregister_middleware` hooks, `ROUTE_ACTION_MAP`, middleware invocation in request handling, pubkey_hash resolution from session store
+- **MMP MeetingSessionStore**: Added `pubkey_hash` storage and `pubkey_hash_for(peer_id)` method
+- **Synoptis TrustScorer**: Extended with anti-collusion PageRank, external attestation weighting, bridge score calculation, attestation weight with zero-weight floor for cartels
+- **Synoptis TrustIdentity**: New module for canonical `agent://` URI handling
+
+---
+
 ## [2.10.1] - 2026-03-19
 
 ### Fixed
@@ -438,6 +476,9 @@ This project follows [Semantic Versioning](https://semver.org/).
 - Skill promotion with Persona Assembly
 - Tool guide and metadata system
 
+[3.0.0]: https://github.com/masaomi/KairosChain_2026/compare/v2.10.1...v3.0.0
+[2.10.1]: https://github.com/masaomi/KairosChain_2026/compare/v2.10.0...v2.10.1
+[2.10.0]: https://github.com/masaomi/KairosChain_2026/compare/v2.9.0...v2.10.0
 [2.9.0]: https://github.com/masaomi/KairosChain_2026/compare/v2.8.0...v2.9.0
 [2.8.0]: https://github.com/masaomi/KairosChain_2026/compare/v2.7.0...v2.8.0
 [2.7.0]: https://github.com/masaomi/KairosChain_2026/compare/v2.6.0...v2.7.0

data/bin/kairos-chain

@@ -6,7 +6,7 @@
 Encoding.default_external = Encoding::UTF_8
 Encoding.default_internal = Encoding::UTF_8
 
-# KairosChain - Memory-driven agent framework
+# KairosChain - Self-referential MCP server for auditable skill self-management
 #
 # Usage:
 #   kairos-chain                        # stdio mode (default, for Cursor local)

data/lib/kairos_mcp/auth/token_store.rb

@@ -81,8 +81,9 @@ module KairosMcp
       # @param role [String] Role: "owner", "member", or "guest"
       # @param issued_by [String] Who issued this token
       # @param expires_in [String, nil] Expiry duration: "90d", "24h", "never", or nil (default)
+      # @param pubkey_hash [String, nil] SHA256 hex of agent's public key (for Service Grant)
       # @return [Hash] { raw_token:, token_hash:, user:, role:, ... }
-      def create(user:, role: 'member', issued_by: 'system', expires_in: nil)
+      def create(user:, role: 'member', issued_by: 'system', expires_in: nil, pubkey_hash: nil)
         validate_role!(role)
         validate_user!(user)
 
@@ -101,6 +102,7 @@ module KairosMcp
           'issued_by' => issued_by,
           'status' => 'active'
         }
+        entry['pubkey_hash'] = pubkey_hash if pubkey_hash
 
         @tokens << entry
         save_tokens
@@ -120,12 +122,14 @@ module KairosMcp
         return nil if entry['status'] != 'active'
         return nil if expired?(entry)
 
-        {
+        result = {
           user: entry['user'],
           role: entry['role'],
           issued_at: entry['issued_at'],
           expires_at: entry['expires_at']
         }
+        result[:pubkey_hash] = entry['pubkey_hash'] if entry['pubkey_hash']
+        result
       end
 
       # Revoke a user's token(s)

data/lib/kairos_mcp/http_server.rb

@@ -213,6 +213,16 @@ module KairosMcp
       # so that @initialized=true and tools are available.
       # See L1 knowledge: kairoschain_operations "Streamable HTTP Transport: Stateless Design"
       user_context = auth_result.user_context
+
+      # Inject remote_ip for Service Grant IP rate limiting (D-5).
+      # Uses shared ClientIpResolver when available (Path A/B consistency).
+      if user_context
+        user_context[:remote_ip] = if defined?(ServiceGrant) && ServiceGrant.respond_to?(:ip_resolver) && ServiceGrant.ip_resolver
+                                     ServiceGrant.ip_resolver.resolve(env)
+                                   else
+                                     env['HTTP_X_REAL_IP'] || env['REMOTE_ADDR']
+                                   end
+      end
       protocol = Protocol.new(user_context: user_context)
 
       if method == 'initialize'

data/lib/kairos_mcp/safety.rb

@@ -83,6 +83,14 @@ module KairosMcp
       policy ? policy.call(@current_user) : true
     end
 
+    def can_manage_grants?
+      return true unless @current_user
+      policy = self.class.policy_for(:can_manage_grants)
+      # Default: deny (unlike can_manage_tokens? which defaults to allow).
+      # Service Grant admin ops should be blocked if the policy SkillSet is not loaded.
+      policy ? policy.call(@current_user) : false
+    end
+
     # Set workspace root from MCP client (roots) or environment
     def set_workspace(roots = nil)
       if roots && roots.is_a?(Array) && !roots.empty?

data/lib/kairos_mcp/tools/token_manage.rb

@@ -153,6 +153,7 @@ module KairosMcp
           {
             "mcpServers": {
               "kairos": {
+                "type": "http",
                 "url": "http://<server-host>:<port>/mcp",
                 "headers": {
                   "Authorization": "Bearer #{result['raw_token']}"

data/lib/kairos_mcp/version.rb

@@ -1,4 +1,4 @@
 module KairosMcp
-  VERSION = "2.10.1"
+  VERSION = "3.0.0"
   CHANGELOG_URL = "https://github.com/masaomi/KairosChain_2026/blob/main/CHANGELOG.md"
 end

data/templates/knowledge/kairoschain_setup/kairoschain_setup.md

@@ -554,6 +554,7 @@ Add to `~/.cursor/mcp.json`:
 {
   "mcpServers": {
     "kairos-chain-http": {
+      "type": "http",
       "url": "http://localhost:8080/mcp",
       "headers": {
         "Authorization": "Bearer kc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
@@ -803,6 +804,7 @@ After setting up HTTPS, update `~/.cursor/mcp.json`:
 {
   "mcpServers": {
     "kairos-chain-http": {
+      "type": "http",
       "url": "https://kairos.example.com/mcp",
       "headers": {
         "Authorization": "Bearer kc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

data/templates/knowledge/kairoschain_setup_jp/kairoschain_setup_jp.md

@@ -538,6 +538,7 @@ ruby bin/kairos-chain --http --host 127.0.0.1 --port 8080
 {
   "mcpServers": {
     "kairos-chain-http": {
+      "type": "http",
       "url": "http://localhost:8080/mcp",
       "headers": {
         "Authorization": "Bearer kc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
@@ -787,6 +788,7 @@ HTTPSをセットアップ後、`~/.cursor/mcp.json`を更新：
 {
   "mcpServers": {
     "kairos-chain-http": {
+      "type": "http",
       "url": "https://kairos.example.com/mcp",
       "headers": {
         "Authorization": "Bearer kc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

data/templates/knowledge/service_grant_access_control/service_grant_access_control.md

@@ -0,0 +1,108 @@
+---
+description: Service Grant SkillSet — generic access control, usage tracking, and billing for KairosChain services
+tags: [documentation, readme, service-grant, access-control, billing, payment, subscription]
+readme_order: 4.9
+readme_lang: en
+---
+
+# Service Grant SkillSet
+
+Service Grant provides **generic, service-independent access control and billing** for any KairosChain-based service. It manages "what is permitted" for authenticated agents without managing identity (identity = RSA key pair via MMP).
+
+## Key Concepts
+
+- **pubkey_hash**: SHA-256 hash of agent's public key — this IS the identity
+- **Grant**: Per-(pubkey_hash, service) entry with plan, status, and usage
+- **Plan**: Quota/billing configuration (free, pro, etc.) defined in YAML
+- **Dual-path enforcement**: Both `/mcp` (AccessGate) and `/place/*` (PlaceMiddleware) are gated
+
+## Architecture
+
+```
+Path A (/mcp):   Token -> pubkey_hash -> AccessGate -> AccessChecker
+Path B (/place): Bearer -> peer_id -> PlaceMiddleware -> AccessChecker
+
+AccessChecker pipeline:
+  suspension -> cooldown -> expiry -> trust -> quota
+```
+
+### Components
+
+| Component | Responsibility |
+|-----------|---------------|
+| **GrantManager** | Grant lifecycle (create, upgrade, suspend, downgrade) |
+| **AccessChecker** | Unified access decision pipeline |
+| **UsageTracker** | Atomic quota consumption with cycle management |
+| **PlanRegistry** | YAML config loader with validation |
+| **PaymentVerifier** | Cryptographic payment attestation verification |
+| **PgConnectionPool** | Thread-safe PostgreSQL with circuit breaker |
+| **TrustScorerAdapter** | Synoptis trust score integration with caching |
+
+## Billing Models
+
+```yaml
+billing_model: free          # No charges
+billing_model: per_action    # Pay per API call
+billing_model: metered       # Usage-based with cycle tracking
+billing_model: subscription  # Time-based with auto-expiry
+```
+
+## Payment Flow (Proof-Centric)
+
+```
+Payment Agent (external) creates attestation proof
+  -> PaymentVerifier verifies: signature, issuer, freshness, amount, nonce
+  -> Atomic transaction: ensure_grant + upgrade_plan + record_payment
+  -> Subscription expiry auto-managed (lazy downgrade on access check)
+```
+
+Payment verification uses Synoptis ProofEnvelope — the same cryptographic attestation infrastructure used for trust scoring.
+
+## Anti-Sybil Measures
+
+- IP rate limiting (5 new grants/hour per IP, PostgreSQL-backed)
+- Delayed activation cooldown (5 min for write operations)
+- Synoptis trust score requirements (configurable per action)
+- Anti-collusion PageRank with external attestation weighting
+
+## MCP Tools
+
+| Tool | Access | Description |
+|------|--------|-------------|
+| `service_grant_status` | All users | View grants and usage |
+| `service_grant_manage` | Owner only | Plan changes, suspend/unsuspend |
+| `service_grant_migrate` | Owner only | Database schema migrations |
+| `service_grant_pay` | All users | Submit payment attestation proofs |
+
+## Configuration Example
+
+```yaml
+services:
+  meeting_place:
+    billing_model: per_action
+    currency: USD
+    cycle: monthly
+    write_actions: [deposit_skill]
+    action_map:
+      meeting_deposit: deposit_skill
+      meeting_browse: browse
+    plans:
+      free:
+        limits:
+          deposit_skill: 5
+          browse: -1  # unlimited
+        trust_requirements:
+          deposit_skill: 0.1
+      pro:
+        subscription_price: "9.99"
+        subscription_duration: 30  # days
+        limits:
+          deposit_skill: -1
+          browse: -1
+```
+
+## Dependencies
+
+- **Hard**: PostgreSQL (grants, usage, payments)
+- **Hard**: Synoptis SkillSet (attestation verification, trust scoring)
+- **Soft**: Hestia SkillSet (Meeting Place middleware integration)

data/templates/knowledge/service_grant_access_control_jp/service_grant_access_control_jp.md

@@ -0,0 +1,108 @@
+---
+description: Service Grant SkillSet — KairosChainサービス向け汎用アクセス制御・使用量追跡・課金
+tags: [documentation, readme, service-grant, access-control, billing, payment, subscription]
+readme_order: 4.9
+readme_lang: jp
+---
+
+# Service Grant SkillSet
+
+Service Grantは、KairosChainベースのあらゆるサービスに対する**汎用的かつサービス非依存のアクセス制御・課金**を提供します。認証済みエージェントに対して「何が許可されているか」を管理し、アイデンティティ管理は行いません（アイデンティティ = MMP経由のRSA鍵ペア）。
+
+## 主要概念
+
+- **pubkey_hash**: エージェントの公開鍵のSHA-256ハッシュ — これがアイデンティティ
+- **Grant**: (pubkey_hash, service)ごとのエントリ（プラン、ステータス、使用量）
+- **Plan**: YAML定義のクォータ/課金設定（free, pro等）
+- **デュアルパス適用**: `/mcp`（AccessGate）と `/place/*`（PlaceMiddleware）の両方をゲート
+
+## アーキテクチャ
+
+```
+パスA (/mcp):   Token -> pubkey_hash -> AccessGate -> AccessChecker
+パスB (/place): Bearer -> peer_id -> PlaceMiddleware -> AccessChecker
+
+AccessCheckerパイプライン:
+  停止確認 -> クールダウン -> 有効期限 -> 信頼スコア -> クォータ
+```
+
+### コンポーネント
+
+| コンポーネント | 責務 |
+|--------------|------|
+| **GrantManager** | Grant ライフサイクル（作成、アップグレード、停止、ダウングレード） |
+| **AccessChecker** | 統合アクセス判定パイプライン |
+| **UsageTracker** | サイクル管理付きアトミッククォータ消費 |
+| **PlanRegistry** | バリデーション付きYAML設定ローダー |
+| **PaymentVerifier** | 暗号学的支払い証明の検証 |
+| **PgConnectionPool** | サーキットブレーカー付きスレッドセーフPostgreSQL |
+| **TrustScorerAdapter** | キャッシュ付きSynoptis信頼スコア統合 |
+
+## 課金モデル
+
+```yaml
+billing_model: free          # 無料
+billing_model: per_action    # APIコール単位課金
+billing_model: metered       # 使用量ベース（サイクル内追跡）
+billing_model: subscription  # 期間ベース（自動期限管理）
+```
+
+## 支払いフロー（証明中心設計）
+
+```
+Payment Agent（外部）が証明（attestation proof）を作成
+  -> PaymentVerifierが検証: 署名、発行者、鮮度、金額、ノンス
+  -> アトミックトランザクション: ensure_grant + upgrade_plan + record_payment
+  -> サブスクリプション期限は自動管理（アクセス時の遅延ダウングレード）
+```
+
+支払い検証にはSynoptis ProofEnvelope — 信頼スコアリングと同じ暗号学的証明インフラ — を使用します。
+
+## アンチシビル対策
+
+- IP レート制限（IP あたり 5 新規 Grant/時間、PostgreSQL バック）
+- 遅延アクティベーションクールダウン（書き込み操作に5分）
+- Synoptis 信頼スコア要件（アクション単位で設定可能）
+- 外部証明重み付けのアンチ共謀 PageRank
+
+## MCPツール
+
+| ツール | アクセス | 説明 |
+|-------|---------|------|
+| `service_grant_status` | 全ユーザー | Grant と使用状況の表示 |
+| `service_grant_manage` | オーナーのみ | プラン変更、停止/再開 |
+| `service_grant_migrate` | オーナーのみ | データベーススキーマ移行 |
+| `service_grant_pay` | 全ユーザー | 支払い証明の提出 |
+
+## 設定例
+
+```yaml
+services:
+  meeting_place:
+    billing_model: per_action
+    currency: USD
+    cycle: monthly
+    write_actions: [deposit_skill]
+    action_map:
+      meeting_deposit: deposit_skill
+      meeting_browse: browse
+    plans:
+      free:
+        limits:
+          deposit_skill: 5
+          browse: -1  # 無制限
+        trust_requirements:
+          deposit_skill: 0.1
+      pro:
+        subscription_price: "9.99"
+        subscription_duration: 30  # 日
+        limits:
+          deposit_skill: -1
+          browse: -1
+```
+
+## 依存関係
+
+- **必須**: PostgreSQL（Grant、使用量、支払い記録）
+- **必須**: Synoptis SkillSet（証明検証、信頼スコアリング）
+- **任意**: Hestia SkillSet（Meeting Place ミドルウェア統合）

data/templates/skillsets/hestia/lib/hestia/place_router.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'digest'
 require 'json'
 require 'uri'
 
@@ -20,6 +21,37 @@ module Hestia
       'Cache-Control' => 'no-cache'
     }.freeze
 
+    # Maps HTTP route segments to abstract action names for access control.
+    # Service Grant (or any middleware) uses these for gating.
+    ROUTE_ACTION_MAP = {
+      'deposit'       => 'deposit_skill',
+      'browse'        => 'browse',
+      'skill_content' => 'browse',
+      'needs'         => 'browse',
+      'agents'        => 'browse',
+      'keys'          => 'browse',
+      'acquire'       => 'acquire_skill',
+      'unregister'    => 'unregister',
+    }.freeze
+
+    # Place middleware registry (class-level, thread-safe)
+    @place_middlewares = []
+    @middleware_mutex = Mutex.new
+
+    class << self
+      def register_middleware(middleware)
+        @middleware_mutex.synchronize { @place_middlewares << middleware }
+      end
+
+      def unregister_middleware(middleware)
+        @middleware_mutex.synchronize { @place_middlewares.delete(middleware) }
+      end
+
+      def place_middlewares
+        @middleware_mutex.synchronize { @place_middlewares.dup }
+      end
+    end
+
     attr_reader :registry, :skill_board, :heartbeat_manager, :session_store, :started_at
 
     def initialize(config: nil)
@@ -107,7 +139,30 @@ module Hestia
 
       # All other endpoints require Bearer token
       auth_result = authenticate!(env)
-      return auth_result unless auth_result.nil?
+      # authenticate! returns { peer_id:, auth_token: } on success,
+      # or a Rack response [status, headers, body] on failure.
+      if auth_result.is_a?(Array)
+        return auth_result
+      end
+      peer_id = auth_result[:peer_id]
+      auth_token = auth_result[:auth_token]
+
+      # Resolve action from route for middleware
+      route_segment = extract_route_segment(path)
+      action = resolve_action(route_segment)
+
+      # Run place middlewares (Service Grant, etc.)
+      # Resolve remote_ip via ServiceGrant's ClientIpResolver if available
+      remote_ip = if defined?(ServiceGrant) && ServiceGrant.respond_to?(:ip_resolver) && ServiceGrant.ip_resolver
+                    ServiceGrant.ip_resolver.resolve(env)
+                  else
+                    env['REMOTE_ADDR']
+                  end
+      denial = run_place_middlewares(peer_id, action, service_name,
+                 auth_token: auth_token, remote_ip: remote_ip)
+      if denial
+        return [denial[:status] || 403, JSON_HEADERS, [denial.to_json]]
+      end
 
       case [request_method, path]
       when ['POST', '/place/v1/unregister']
@@ -227,7 +282,8 @@ module Hestia
       # Issue session token if signature was verified
       session_token = nil
       if verified
-        session_token = @session_store.create_session(agent_id, public_key)
+        pubkey_hash = public_key ? Digest::SHA256.hexdigest(public_key) : nil
+        session_token = @session_store.create_session(agent_id, public_key, pubkey_hash: pubkey_hash)
       end
 
       response = result.merge(identity_verified: verified)
@@ -455,6 +511,11 @@ module Hestia
 
     # --- Auth ---
 
+    # Authenticate the request and return identity on success.
+    # Returns a Rack response array on failure.
+    #
+    # @param env [Hash] Rack environment
+    # @return [Hash, Array] { peer_id:, auth_token: } on success, Rack response on failure
     def authenticate!(env)
       token = extract_bearer_token(env)
       unless token
@@ -479,7 +540,7 @@ module Hestia
       # Update heartbeat on any authenticated request
       @heartbeat_manager.touch(peer_id)
 
-      nil # Auth passed
+      { peer_id: peer_id, auth_token: token }
     end
 
     def extract_bearer_token(env)
@@ -519,5 +580,37 @@ module Hestia
     def json_response(status, body)
       [status, JSON_HEADERS, [body.to_json]]
     end
+
+    # Extract route segment from path for action mapping.
+    # For parameterized routes (/keys/:id, /skill_content/:id), falls back to
+    # the first segment when the last segment is not a known action.
+    def extract_route_segment(path)
+      segments = path.sub('/place/v1/', '').split('/')
+      candidate = segments.last || ''
+      ROUTE_ACTION_MAP.key?(candidate) ? candidate : (segments.first || '')
+    end
+
+    # Map route segment to abstract action name for access control.
+    def resolve_action(route_segment)
+      ROUTE_ACTION_MAP[route_segment] || route_segment
+    end
+
+    # Run registered place middlewares. Returns nil if all pass,
+    # or a denial Hash if any middleware denies.
+    def run_place_middlewares(peer_id, action, service, auth_token: nil, remote_ip: nil)
+      self.class.place_middlewares.each do |mw|
+        # Inject session_store if middleware accepts it (e.g., ServiceGrant::PlaceMiddleware)
+        mw.session_store = @session_store if mw.respond_to?(:session_store=)
+        result = mw.check(peer_id: peer_id, action: action, service: service,
+                          auth_token: auth_token, remote_ip: remote_ip)
+        return result if result
+      end
+      nil
+    end
+
+    # Service name for this Meeting Place instance
+    def service_name
+      @config.dig('meeting_place', 'service_name') || 'meeting_place'
+    end
   end
 end

data/templates/skillsets/mmp/lib/mmp/meeting_session_store.rb

@@ -19,7 +19,7 @@ module MMP
     DEFAULT_RATE_LIMIT_PER_MINUTE = 100
 
     Session = Struct.new(
-      :peer_id, :public_key, :token, :created_at,
+      :peer_id, :public_key, :pubkey_hash, :token, :created_at,
       :last_activity, :request_count, :request_window_start,
       keyword_init: true
     )
@@ -28,6 +28,7 @@ module MMP
 
     def initialize(ttl_minutes: DEFAULT_TTL_MINUTES, rate_limit: DEFAULT_RATE_LIMIT_PER_MINUTE)
       @sessions = {}
+      @peer_id_index = {}  # peer_id => token (most recent session)
       @ttl = ttl_minutes * 60
       @ttl_minutes = ttl_minutes
       @rate_limit = rate_limit
@@ -36,19 +37,26 @@ module MMP
 
     # Create a new session for a verified peer.
     # Returns the session token string.
-    def create_session(peer_id, public_key)
+    #
+    # @param peer_id [String] Peer identifier
+    # @param public_key [String] PEM-encoded public key
+    # @param pubkey_hash [String, nil] SHA256 hex of public key (for Service Grant)
+    def create_session(peer_id, public_key, pubkey_hash: nil)
       token = SecureRandom.hex(32)
       now = Time.now
       @mutex.synchronize do
         @sessions[token] = Session.new(
           peer_id: peer_id,
           public_key: public_key,
+          pubkey_hash: pubkey_hash,
           token: token,
           created_at: now,
           last_activity: now,
           request_count: 0,
           request_window_start: now
         )
+        # Update peer_id reverse index (most recent session wins)
+        @peer_id_index[peer_id] = token
       end
       token
     end
@@ -125,12 +133,40 @@ module MMP
       end
     end
 
+    # Reverse lookup: find pubkey_hash for a given peer_id.
+    # Uses O(1) index instead of linear scan.
+    #
+    # @param peer_id [String] Peer identifier
+    # @return [String, nil] pubkey_hash if found
+    def pubkey_hash_for(peer_id)
+      @mutex.synchronize do
+        token = @peer_id_index[peer_id]
+        return @sessions[token]&.pubkey_hash if token && @sessions[token]
+        nil
+      end
+    end
+
+    # Exact session lookup by token. O(1) — no ambiguity with multiple sessions.
+    #
+    # @param token [String] Bearer token
+    # @return [String, nil] pubkey_hash if session exists
+    def pubkey_hash_for_token(token)
+      @mutex.synchronize do
+        session = @sessions[token]
+        session&.pubkey_hash
+      end
+    end
+
     private
 
     # Remove expired sessions (called within mutex).
     def cleanup_expired
       now = Time.now
-      @sessions.delete_if { |_token, session| now - session.created_at > @ttl }
+      @sessions.delete_if do |_token, session|
+        expired = now - session.created_at > @ttl
+        @peer_id_index.delete(session.peer_id) if expired && @peer_id_index[session.peer_id] == _token
+        expired
+      end
     end
   end
 end