as4-411/docs/architecture/connectors.md

Connector Specifications

This document describes ingest formats and behaviors for directory connectors. Each connector pulls or receives data from an external source and maps it into the core directory model (participants, identifiers, endpoints, capabilities, credentials, policies). Trust, caching, and resilience: see ADR-005. Each connector must define: trust anchors and signature validation; cache TTL and refresh (with jitter); timeouts, retries, circuit-breaker; and data provenance tagging (source, last_verified, confidence).

SMP/SML (PEPPOL)

• Source: SML (Service Metadata Locator) for participant ID → SMP URL; SMP (Service Metadata Publisher) for document/process and endpoint + certificate.
• Ingest: Resolve participant ID via SML, fetch SMP metadata, map to:
  • One participant per PEPPOL participant ID.
  • Identifiers: peppol.participantId, optional peppol.documentTypeId / peppol.processId.
  • Endpoints: HTTPS URL + transport profile (e.g. AS4).
  • Credentials: certificate reference (fingerprint, validity); store only ref or fingerprint, not private key.
• Refresh: On-demand or periodic TTL; cache in directory for resilience. Evidence fields: source: "smp", lastVerified, confidenceScore.
• Trust (SMP/SML): TLS and optional payload signing; document which CAs or pins are accepted. On SMP/SML failure, fall back to cached data only; do not serve stale beyond a configured max stale window.

SS7 (GTT / Point Code)

• Source: GTT (Global Title Translation) tables, point code routing tables, optional number portability/range feeds.
• Ingest: Map E.164/GT → PC/SSN (and translation type) into directory or into routing artifacts (see data model and resolution algorithm). Participants may represent nodes or ranges; endpoints carry protocol: ss7 and address as PC/SSN or route set reference.
• Format: Vendor-specific (CSV, JSON, or proprietary); connector normalizes to internal graph edges and artifact payloads. Tag all edges with provenance and validity; SS7 mapping is only as good as ingested sources (no implied authority).

File / GitOps

• Source: File system or Git repo (YAML/JSON). Used for BIN tables, participant maps, and signed routing artifact bundles.
• Ingest:
  • BIN tables: CSV or JSON with BIN range, brand, region, routing target, optional tenant override; stored as routing_artifacts with artifact_type: bin_table.
  • Participant/endpoint config: YAML or JSON matching directory schema; validate and apply via Admin API or direct store writes.
  • Signed artifacts: Payload + signature/fingerprint, effective_from/effective_to; validate and persist as routing artifacts.
• Refresh: Watch file or webhook; re-ingest on change. Optional version tags for rollback.

KTT (Placeholder)

• Source: TBD per sector. Placeholder connector supports file + API ingest stubs.
• Identifier types: ktt.*; see protocols/ktt.md when defined.

Common Requirements

• All connectors must map into the same core entities; no rail-specific tables for “directory” data beyond optional routing_artifacts.
• Credentials: only references (vault_ref, fingerprint); never private keys.
• Audit: log ingest runs and failures; optional hash-chain for artifact integrity.