gRPC MERIDIAN Adapter (Tier 3)

ELI5

The MERIDIAN adapter is like a passport office that lets IRIS citizens travel to the MERIDIAN country. It issues them a local MERIDIAN ID, verifies their passport is genuine (fingerprint check), and gives them a temporary visa (capability token) that expires after a set time. The adapter makes sure both countries agree on who this person is.

Technical Deep Dive

gRPC Service Definition

Package: iris.meridian.v1 Service: IrisMeridianAdapter

service IrisMeridianAdapter {
  rpc MapSprite(MapSpriteRequest) returns (MapSpriteResponse);
  rpc VerifyFingerprint(VerifyFingerprintRequest) returns (VerifyFingerprintResponse);
  rpc GenerateCapabilityToken(TokenRequest) returns (TokenResponse);
  rpc ListMappings(ListMappingsRequest) returns (ListMappingsResponse);
}

RPC 1: MapSprite

Purpose: Register an IRIS sprite in the MERIDIAN namespace.

sequenceDiagram
    participant Meridian as MERIDIAN Client
    participant Adapter as iris-meridian-adapter
    participant IrisClient as IrisServiceClient
    participant Iris as iris-service
    participant Store as MappingStore

    Meridian->>Adapter: MapSprite(iris_sprite_id, meridian_council_id)
    Adapter->>IrisClient: get_sprite(iris_sprite_id)
    IrisClient->>Iris: GET /v1/sprites/{id}
    Iris-->>IrisClient: Sprite
    IrisClient-->>Adapter: SpriteData

    Adapter->>Store: Check existing mapping
    alt Mapping exists AND NOT force_remap
        Store-->>Adapter: ALREADY_EXISTS
        Adapter-->>Meridian: ALREADY_EXISTS
    else New or force_remap
        Adapter->>Adapter: Determine MERIDIAN role
        Adapter->>Store: create_mapping(iris_id, meridian_id, role)
        Store-->>Adapter: SpriteMapping
        Adapter->>Adapter: Fingerprint verification
        Adapter-->>Meridian: MapSpriteResponse {mapping, fingerprint}
    end

Creates bidirectional mapping:

• IRIS namespace: iris://{domain}/{name}@{version}
• MERIDIAN namespace: strat://{council}/{role}/{name}

RPC 2: VerifyFingerprint

Purpose: Cross-system fingerprint verification using the STRATT 5-stage canonical pipeline.

sequenceDiagram
    participant Meridian as MERIDIAN
    participant Adapter as iris-meridian-adapter
    participant Verifier as FingerprintVerifier
    participant IrisClient as IrisServiceClient

    Meridian->>Adapter: VerifyFingerprint(iris_sprite_id, expected_hash, algorithm)
    Adapter->>IrisClient: get_sprite(iris_sprite_id)
    IrisClient-->>Adapter: SpriteData
    Adapter->>Verifier: verify_sprite_fingerprint(sprite, expected_hash)
    Verifier->>Verifier: Recompute Blake3 via 5-stage pipeline
    Verifier->>Verifier: Compare IRIS hash, computed hash, optional MERIDIAN hash
    alt All match
        Verifier-->>Adapter: verified: true
    else Mismatch
        Verifier-->>Adapter: verified: false
    end
    Adapter-->>Meridian: VerifyFingerprintResponse {identity, fingerprint_result}

Verification logic: Returns True only if all present hashes match (case-insensitive). If iris_hash mismatches computed_hash, or meridian_hash mismatches computed_hash, verification fails.

RPC 3: GenerateCapabilityToken

Purpose: Issue NFT-style capability tokens scoped to a MERIDIAN council.

flowchart TD
    A["GenerateCapabilityToken"] --> B["Validate TTL bounds"]
    B --> C["Fetch sprite from iris-service"]
    C --> D["Verify requested capabilities ⊆ sprite capabilities"]
    D -->|Mismatch| E["ValueError"]
    D -->|Valid| F["Create CapabilityToken"]
    F --> G["Sign with HMAC-SHA256"]
    G --> H["Compute Blake3 integrity hash"]
    H --> I["Return TokenResponse"]

Token properties:

• Time-limited: default 1 hour, maximum 24 hours (configurable via AdapterConfig)
• Scoped: capabilities must be a subset of the sprite’s declared capabilities
• Signed: HMAC-SHA256 of canonical JSON payload
• Revocable: stored in mapping store with active flag
• Integrity: Blake3 hash of token payload included in response

Token format: {token_id}.{first_32_chars_of_signature}

RPC 4: ListMappings

Purpose: Paginated listing of active IRIS-to-MERIDIAN mappings.

Filters:

• iris_domain — filter by IRIS domain
• meridian_council_id — filter by MERIDIAN council
• status_filter — ACTIVE, PENDING_VERIFICATION, SUSPENDED, REVOKED

Pagination:

• page_size: 1–100 (clamped)
• page_token: base64-encoded offset
• Returns next_page_token for subsequent pages

Namespace URI System

classDiagram
    class SpriteMapping {
        +UUID mapping_id
        +SpriteIdentity iris_identity
        +MeridianCouncilMapping meridian_mapping
        +MappingStatus status
        +string iris_namespace_uri
    }
    class SpriteIdentity {
        +UUID iris_id
        +string name
        +string version
        +string domain
        +string role
        +string fingerprint_hash
    }
    class MeridianCouncilMapping {
        +UUID meridian_council_id
        +string meridian_role
        +string meridian_namespace_uri
        +boolean active
        +datetime created_at
        +datetime last_verified_at
    }
    SpriteMapping --> SpriteIdentity : contains
    SpriteMapping --> MeridianCouncilMapping : contains

URI formats:

Mapping Status Lifecycle

stateDiagram-v2
    [*] --> ACTIVE: MapSprite created
    ACTIVE --> PENDING_VERIFICATION: Scheduled re-verification
    PENDING_VERIFICATION --> ACTIVE: Fingerprint matches
    PENDING_VERIFICATION --> SUSPENDED: Fingerprint mismatch
    ACTIVE --> SUSPENDED: Manual suspension
    SUSPENDED --> ACTIVE: Re-verified
    ACTIVE --> REVOKED: Explicit revocation
    SUSPENDED --> REVOKED: Explicit revocation
    REVOKED --> [*]

Key Terms

• MERIDIAN → The STRATT protocol’s council ecosystem; Tier 3 federates IRIS sprites into it
• gRPC → Google’s high-performance RPC framework using Protocol Buffers
• Namespace URI → A structured identifier mapping sprites between systems (iris:// and strat://)
• Capability token → A time-limited, signed, council-scoped authorization token
• Cross-system verification → Using the same Blake3 canonical pipeline to verify identity across IRIS and MERIDIAN
• Mapping status → ACTIVE, PENDING_VERIFICATION, SUSPENDED (fingerprint mismatch), REVOKED
• Force remap → Overwriting an existing mapping when force_remap=true

Q&A

Q: What port does the gRPC adapter listen on? A: Default 0.0.0.0:50051. Configurable via serve(host, port, config_path, iris_service_url).

Q: Can a sprite be mapped to multiple MERIDIAN councils? A: Yes. The mapping store uses a composite key of (iris_sprite_id, meridian_council_id), allowing one sprite to exist in multiple MERIDIAN councils with different roles.

Q: What happens when a capability token expires? A: The token’s is_active property becomes False (checked via now < expires_at). The mapping store retains the token record for audit purposes, but MERIDIAN should reject expired tokens.

Q: Is the HMAC signing key secure? A: The current implementation uses a hardcoded signing key. Production deployments must replace this with a secure key management system (e.g., HashiCorp Vault, AWS KMS).

Q: How does ListMappings handle large result sets? A: It uses cursor-based pagination with base64-encoded offset tokens. This prevents issues with offset-based pagination when mappings are created/deleted during iteration.

Examples

The MERIDIAN adapter is like an international embassy:

• MapSprite = Issuing a citizen a visa to another country (creates a record in both systems)
• VerifyFingerprint = The embassy calling your home country to verify your passport is genuine (not forged)
• GenerateCapabilityToken = Issuing a temporary diplomatic visa with specific permissions (“you may attend meetings but cannot sign treaties”) and an expiration date
• ListMappings = The embassy’s ledger of all current visa holders, filterable by nationality, visa type, and status