Initial commit: AS4/411 directory and discovery service for Sankofa Marketplace

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-08 08:44:20 -08:00
commit c24ae925cf
109 changed files with 7222 additions and 0 deletions
--- a/docs/protocols/_rail-template.md
+++ b/docs/protocols/_rail-template.md
@@ -0,0 +1,49 @@
+# Rail Definition Template
+
+**Required before implementing a new rail or protocol adapter.** Copy this template, fill every section, and ensure the rail doc is complete before merge. See [catalog.md](catalog.md).
+
+---
+
+## 1. Owner and Authority
+
+- **Governing body / owner:**
+- **Normative specifications (links):**
+- **Message families / standards:**
+
+## 2. Identifier Scheme(s)
+
+- **Identifier types** (e.g. partyId, BIC, BIN):
+- **Validation rules** (format, length, allowed characters):
+- **Uniqueness and scope** (global vs tenant-scoped):
+
+## 3. Addressing and Endpoint Rules
+
+- **Endpoint types** (URL, queue, point code, etc.):
+- **Address format** (regex or pattern):
+- **Transport profiles** (if any):
+
+## 4. Security Model
+
+- **Authentication** (how participants are authenticated):
+- **Integrity** (signing, hashing):
+- **Confidentiality** (encryption, TLS):
+
+## 5. Discovery Model
+
+- **Public directory?** (yes / no / partial)
+- **Contractual only?** (e.g. BIN tables, member config)
+- **Authoritative source** (SML/SMP, vendor API, internal only):
+
+## 6. Compliance Constraints
+
+- **Regulatory** (e.g. PCI-DSS, data residency):
+- **Data handling** (what must not be stored, encryption requirements):
+
+## 7. Sample Payloads and Test Vectors
+
+- **Sample request/response or message** (anonymized):
+- **Test vectors** (identifier in → expected directive or behavior):
+
+---
+
+*Block merge of new rails until this template is completed for the rail.*
--- a/docs/protocols/cards.md
+++ b/docs/protocols/cards.md
@@ -0,0 +1,39 @@
+# Card Networks (Visa, Mastercard, Amex, Discover, Diners)
+
+## Scope
+
+Card rails are **private routing artifacts** (BIN tables, acquirer routing). There is **no public "discover Visa endpoint"** behavior. Ingestion is from internal systems only; strong encryption and access controls apply. The directory stores routing tables and returns directives to an ISO8583/API switch. Never store PAN; BIN ranges only. Merchant ID (MID), Terminal ID (TID), and contract identifiers are **Tier 2** (confidential)—encrypt at rest and restrict access. See [data-classification](../security/data-classification.md).
+
+## Identifier Taxonomy
+
+- **pan.bin** — BIN/IIN range (6–8 digits only); never full PAN.
+- **mid**, **tid**, **caid** — Merchant/terminal/card-acceptor IDs (tenant-scoped).
+- **processorId** / **acquirerId** — Tenant/contract scoped.
+- **network.brand** — Constraint: visa, mastercard, amex, discover, diners.
+
+Do not store PAN or token values in plaintext.
+
+## Endpoints
+
+- **iso8583.tcp** — Host:port, mTLS/VPN.
+- **api.https** — Base URL + auth.
+- **file.sftp** — Clearing files.
+- **mq** — Internal switch.
+
+Profile indicates channel (e.g. visa-base1, mc-mip).
+
+## BIN-Table Model
+
+- Artifact type: **bin_table**. Payload: versioned entries with binPrefix, binLength, brand, region, routingTarget, optional tenantId.
+- Resolver matches request BIN to longest-matching prefix and returns directive with target_address = routingTarget. Per-tenant overrides supported.
+
+## Directive Outputs
+
+- ISO8583: target_protocol iso8583, target_address host:port.
+- API: target_protocol api/https, target_address base URL.
+
+Capabilities: auth.request/response, clearing.presentment, chargeback, reversal, advice, tokenization, 3ds.
+
+## Security
+
+- Store BIN ranges only; no PAN/token. Field-level encryption for merchant/terminal IDs. Strict RBAC and audit for card-related records. See security/key-reference-model.md.
--- a/docs/protocols/catalog.md
+++ b/docs/protocols/catalog.md
@@ -0,0 +1,23 @@
+# Protocol and Rail Catalog
+
+Extensibility catalog for additional rails. **New rails require a completed doc derived from [_rail-template.md](_rail-template.md) before merge.**
+ Adapters are added incrementally; each defines identifier types, endpoint profiles, capability taxonomy, and optional connector in `packages/connectors/`.
+
+## Implemented
+
+- **AS4 / PEPPOL** — See data-model identifier types; SMP/SML connector spec in docs/architecture/connectors.md.
+- **ISO 20022 over AS4 (FI-to-FI)** — [iso20022-over-as4.md](iso20022-over-as4.md). PartyId (BIC, LEI) → endpoint + cert + AS4 profile; Service/Action for pacs/camt; directory-only (no ISO 20022 parsing, no settlement). Scheme-specific profiles: [iso20022-scheme-profiles.md](iso20022-scheme-profiles.md) (TARGET2, Fedwire, CHAPS).
+- **SS7** — e164, gt, pc, ssn; GTT via routing artifacts.
+- **Card networks** — [cards.md](cards.md); pan.bin, BIN table, ISO8583.
+- **DTC / Digital securities** — [dtc.md](dtc.md); lei, bic, dtc.participantId, dtc.accountId.
+- **KTT** — [ktt.md](ktt.md); placeholder rail.
+
+## Candidate Families (priority order)
+
+- **Payments:** ISO 20022 over AS4 (FI-to-FI) documented; ISO 20022 over API, SWIFT, Fedwire-like remain candidates.
+- **EDI / B2B:** AS2, SFTP EDI, RosettaNet.
+- **Healthcare:** HL7 MLLP, FHIR endpoints (endpoint registry + certs).
+- **Identity:** DID, DNSSEC, PKI directories.
+- **Message brokers:** Kafka topics, NATS subjects, AMQP queues (logical addresses + ACL).
+
+Integration: add identifier validators in core, register profile in protocol_registry, optional connector; document in a new docs/protocols/*.md.
--- a/docs/protocols/dtc.md
+++ b/docs/protocols/dtc.md
@@ -0,0 +1,44 @@
+# DTC / Digital Securities (DTCC Ecosystem)
+
+## Overview
+
+DTC and DTC-related messaging cover securities post-trade and custody. Participants include broker-dealers, custodian banks, and clearing members. Directory use is often **client-owned configuration**; public directory availability is limited.
+
+## Scope
+
+**Identity mapping** (LEI, BIC, participant IDs) plus **contractual endpoint profiles**. Optional import from customer-managed config (files or APIs). Do **not** claim automated discovery unless an authoritative or licensed directory feed exists. Prefer routing artifacts and admin API for participant/endpoint maps.
+
+## Identifier Taxonomy
+
+| Type | Description | Scope |
+|------|-------------|--------|
+| `lei` | Legal Entity Identifier | Public/registry |
+| `bic` | Bank Identifier Code (SWIFT) | Market identifier |
+| `dtc.participantId` | DTC/internal participant ID | Tenant/confidential |
+| `dtc.accountId` | Custody/account ID (proprietary) | Tenant/confidential |
+
+Historical: `duns` (D&B) where still in use.
+
+## Endpoint Profiles
+
+| Profile | Protocol | Description |
+|---------|----------|-------------|
+| `dtcc-mq` | MQ | DTCC connectivity / message system |
+| `sftp.*` | SFTP | File-based instructions |
+| `https.*` | HTTPS/AS2/AS4 | API or EDI over HTTP |
+
+Address format is vendor- or channel-specific (queue name, path, URL).
+
+## Capability Taxonomy
+
+- `securities.settlement.*` — Settlement instructions and messages.
+- `securities.corpactions.*` — Corporate actions.
+- `securities.assetservices.*` — Asset servicing.
+
+Used in resolution to match service context (e.g. request for settlement instructions).
+
+## Tenancy and Confidentiality
+
+- **Strong tenant scoping:** DTC and account identifiers are frequently confidential. Resolution must be scoped by tenant; no cross-tenant leakage.
+- **Prefer integration via client-owned configuration:** Ingest from client-provided files or APIs rather than assuming a public directory. Use [routing artifacts](../architecture/data-model.md) and admin API for participant/endpoint maps.
+- **Audit:** All access to DTC-related participant and endpoint data must be audited.
--- a/docs/protocols/iso20022-as4-sample-envelope.xml
+++ b/docs/protocols/iso20022-as4-sample-envelope.xml
@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Anonymized AS4/ebMS3-style sample for ISO 20022 FI-to-FI.
+     References: OASIS ebMS 3.0, AS4. Payload is opaque (ISO 20022 XML).
+     Placeholders: SENDERBICXXX, RECEIVERBICXXX; endpoint resolved via directory. -->
+<Envelope xmlns="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/">
+  <Header>
+    <Messaging>
+      <UserMessage>
+        <MessageInfo>
+          <MessageId>uuid-sample-message-id-001</MessageId>
+          <Timestamp>2025-02-07T12:00:00Z</Timestamp>
+          <RefToMessageId>optional-ref</RefToMessageId>
+        </MessageInfo>
+        <PartyInfo>
+          <From>
+            <PartyId>SENDERBICXXX</PartyId>
+            <Role>http://example.org/roles/sender</Role>
+          </From>
+          <To>
+            <PartyId>RECEIVERBICXXX</PartyId>
+            <Role>http://example.org/roles/receiver</Role>
+          </To>
+        </PartyInfo>
+        <CollaborationInfo>
+          <AgreementRef>as4.fifi.iso20022.v1</AgreementRef>
+          <Service type="application">iso20022.fi</Service>
+          <Action>credit.transfer</Action>
+          <ConversationId>conv-sample-001</ConversationId>
+        </CollaborationInfo>
+        <PayloadInfo>
+          <PartInfo href="cid:pacs008.xml">
+            <Schema location="urn:iso:std:iso:20022:tech:xsd:pacs.008.001.08"/>
+          </PartInfo>
+        </PayloadInfo>
+      </UserMessage>
+    </Messaging>
+  </Header>
+  <!-- Body: multipart with signed+encrypted payload (omitted here; AS4 treats as opaque) -->
+</Envelope>
--- a/docs/protocols/iso20022-over-as4.md
+++ b/docs/protocols/iso20022-over-as4.md
@@ -0,0 +1,299 @@
+# ISO 20022 over AS4 (FI-to-FI)
+
+Canonical reference for ISO 20022 messages transported via AS4 between financial institutions. Used by gateway teams, auditors, and scheme designers. as4-411 provides **directory and resolution only**; it does not parse ISO 20022, perform settlement, or replace AS4 MSH (see [ADR-000](../adr/000-scope-and-non-goals.md)).
+
+---
+
+## 1. Overview and layer model
+
+ISO 20022 is the **business payload** (pacs, camt); AS4 (ebMS 3.0) is the **messaging envelope**; HTTPS is the **transport**. Identity-based addressing: PartyId (BIC, LEI) is resolved by the directory to endpoint URL, certificates, and profile. No URL in the envelope—only PartyId.
+
+```mermaid
+flowchart TB
+  subgraph business [Business Layer]
+    ISO20022["ISO 20022 XML (pacs, camt)"]
+  end
+  subgraph messaging [Messaging Layer]
+    AS4["ebMS 3.0 / AS4 Envelope"]
+    AS4_detail["PartyId, Service, Action, MPC, Receipts"]
+  end
+  subgraph transport [Transport Layer]
+    HTTPS["HTTPS + TLS"]
+  end
+  ISO20022 --> AS4
+  AS4 --> AS4_detail
+  AS4_detail --> HTTPS
+```
+
+**Principle:** ISO 20022 never handles transport. AS4 never interprets business content.
+
+---
+
+## 2. Message classes (pacs, camt)
+
+| ISO 20022 Message | Description |
+| ----------------- | ----------- |
+| pacs.008 | Customer Credit Transfer |
+| pacs.009 | Financial Institution Credit Transfer |
+| pacs.002 | Payment Status |
+| camt.056 | Payment Cancellation |
+| camt.029 | Resolution of Investigation |
+| camt.053 | Statement |
+| camt.054 | Debit/Credit Notification |
+
+Payload: XML, UTF-8, strict XSD validation. May include BICs, LEIs, clearing member IDs. **AS4 treats payload as opaque.**
+
+---
+
+## 3. AS4 envelope mapping
+
+ebMS headers: From.PartyId, To.PartyId, Service, Action, ConversationId, MessageId, MPC. **Profile ID:** `as4.fifi.iso20022.v1`. **Service:** `iso20022.fi`. **Action:** one per ISO 20022 message type (see §4).
+
+Header skeleton (simplified):
+
+```xml
+<eb:Messaging>
+  <eb:UserMessage>
+    <eb:MessageInfo>
+      <eb:MessageId>uuid</eb:MessageId>
+      <eb:ConversationId>business-id</eb:ConversationId>
+    </eb:MessageInfo>
+
+    <eb:PartyInfo>
+      <eb:From>
+        <eb:PartyId type="BIC">BANKDEFFXXX</eb:PartyId>
+      </eb:From>
+      <eb:To>
+        <eb:PartyId type="BIC">BANKUS33XXX</eb:PartyId>
+      </eb:To>
+    </eb:PartyInfo>
+
+    <eb:CollaborationInfo>
+      <eb:Service>iso20022.fi</eb:Service>
+      <eb:Action>credit.transfer</eb:Action>
+    </eb:CollaborationInfo>
+
+    <eb:PayloadInfo>
+      <eb:PartInfo href="cid:pacs008.xml"/>
+    </eb:PayloadInfo>
+  </eb:UserMessage>
+</eb:Messaging>
+```
+
+Payload: detached MIME; **signed → encrypted → attached**. Full sample: [iso20022-as4-sample-envelope.xml](iso20022-as4-sample-envelope.xml).
+
+---
+
+## 4. Addressing and identity
+
+- **PartyId types:** BIC, LEI, internal.bank.code, scheme-specific (e.g. TARGET2, RTGS).
+- **Directory:** maps PartyId → HTTPS endpoint URL + transport profile + receiver encryption cert + receipt requirements. **Profile:** `as4.fifi.iso20022.v1`.
+- Discovery is directory-driven (contractual or internal); no public “discover any BIC” without directory data. See [data-model](../architecture/data-model.md) (`as4.partyId`, scope/partyIdType).
+
+### AS4 FI-to-FI profile definition
+
+| Feature | Requirement |
+| ------- | ----------- |
+| ebMS Version | ebMS 3.0 |
+| Transport | HTTPS |
+| Payload | ISO 20022 XML |
+| Signing | Mandatory |
+| Encryption | Mandatory |
+| Receipts | Signed Receipts |
+| Duplicate Detection | Enabled |
+| Reliability | Exactly-once delivery |
+
+### MPC usage
+
+| MPC | Purpose |
+| --- | ------- |
+| `default` | Normal traffic |
+| `urgent` | Time-critical payments |
+| `bulk` | High-volume settlement batches |
+
+### Service / Action taxonomy
+
+**Service namespace:** `iso20022.fi`. **Rule:** one ISO 20022 message type = one AS4 Action.
+
+| ISO 20022 Message | Action |
+| ----------------- | ------ |
+| pacs.008 | credit.transfer |
+| pacs.009 | fi.credit.transfer |
+| pacs.002 | payment.status |
+| camt.056 | payment.cancellation |
+| camt.029 | resolution.of.investigation |
+| camt.053 | statement |
+| camt.054 | notification |
+
+---
+
+## 5. Security model
+
+- **Message-level:** XML Digital Signature (sender), XML Encryption (receiver); mandatory for profile `as4.fifi.iso20022.v1`. Optional compression.
+- **Transport:** HTTPS, TLS; optional mTLS; network allowlisting.
+- See [key-reference-model](../security/key-reference-model.md).
+
+---
+
+## 6. Reliability and receipts
+
+- **Signed receipts** required (non-repudiation).
+- **Duplicate detection** enabled.
+- **Exactly-once delivery** per profile.
+- Retries on transient failure; receipt stored by sender.
+
+---
+
+## 7. Processing lifecycle
+
+```
+ISO 20022 XML created
+        ↓
+AS4 envelope built (PartyId, Service, Action)
+        ↓
+Directory resolves PartyId → endpoint + cert
+        ↓
+AS4 signs + encrypts
+        ↓
+HTTPS transmission
+        ↓
+Receiver AS4 gateway validates + decrypts
+        ↓
+ISO 20022 payload extracted
+        ↓
+ISO 20022 engine processes message
+```
+
+---
+
+## 8. Error separation (transport vs business)
+
+| Layer | Handled by | Examples |
+| ----- | ---------- | -------- |
+| Transport | AS4 only | Retries, receipts, duplicate suppression. |
+| Business | ISO 20022 | pacs.002 (status), camt.056 (cancellation), scheme rejects. |
+
+**Never mix transport errors with business rejects.**
+
+---
+
+## 9. as4-411 integration
+
+**Provides:** PartyId → endpoint resolution; Service/Action constraints; certificate references; multi-rail identity (BIC ↔ LEI ↔ internal); deterministic, auditable routing directives.
+
+**Does not:** Parse ISO 20022; perform settlement; replace AS4 MSH.
+
+---
+
+## 10. Compliance and audit notes
+
+- Receipts and **resolution_trace** support audit (which source contributed the directive).
+- BIC/LEI are Tier 0/1 per [data-classification](../security/data-classification.md).
+- Who may call resolve and what they see: [trust-model](../security/trust-model.md).
+
+---
+
+## 11. Sample AS4 envelopes
+
+See §3 for header skeleton. Full anonymized envelope: [iso20022-as4-sample-envelope.xml](iso20022-as4-sample-envelope.xml). Resolution examples: [../examples/iso20022-as4-resolution-examples.yaml](../examples/iso20022-as4-resolution-examples.yaml).
+
+---
+
+## 12. as4-411 resolution examples
+
+### Example 1 — BIC-based resolution
+
+**Input**
+
+- To.PartyId = BANKUS33XXX  
+- PartyIdType = BIC  
+- Service = iso20022.fi  
+- Action = credit.transfer  
+
+**Resolution output**
+
+- Endpoint: https://as4.bankus.com/fi  
+- EncryptionCert: vault://certs/bankus/iso20022  
+- Profile: as4.fifi.iso20022.v1  
+- Receipts: signed  
+
+### Example 2 — LEI-based resolution
+
+**Input**
+
+- To.PartyId = 5493001KJTIIGC8Y1R12  
+- PartyIdType = LEI  
+
+**Mapping**
+
+- LEI → BIC(s) → AS4 Endpoint  
+
+**Output**
+
+- Same directive structure as BIC.  
+- Evidence includes LEI→BIC mapping source.  
+
+(JSON request/response shapes in [../examples/iso20022-as4-resolution-examples.yaml](../examples/iso20022-as4-resolution-examples.yaml) and [OpenAPI](../api/openapi.yaml).)
+
+---
+
+## 13. RTGS-specific nuances
+
+- **Characteristics:** Real-time settlement, tight SLA windows, liquidity constraints.
+- **AS4 adjustments:**
+
+| Aspect | RTGS requirement |
+| ------ | ----------------- |
+| MPC | `urgent` |
+| Retry | Minimal / controlled |
+| Timeouts | Aggressive |
+| Receipts | Mandatory, immediate |
+
+- **Message patterns:** pacs.008 / pacs.009; immediate pacs.002 response expected.
+
+---
+
+## 14. Cross-border correspondent banking
+
+- **Topology:** Bank A → Correspondent X → Correspondent Y → Bank B.
+- **as4-411 role:** Resolve **next hop**, not final destination; maintain correspondent routing tables; apply jurisdiction and currency policies.
+- **Envelope:** Each hop = new AS4 envelope; business ConversationId preserved; transport MessageId regenerated.
+
+---
+
+## 15. CBDC / tokenized settlement overlays
+
+- **Overlay model:** ISO 20022 remains the **instruction layer**; token/CBDC rails provide the **settlement layer**.
+- **Directory extensions:** Map PartyId → wallet/DLT endpoint; store settlement rail capability (RTGS, CBDC, tokenized deposit). See [cbdc-settlement-adapter](../architecture/cbdc-settlement-adapter.md).
+- **Dual-track:** ISO 20022 instruction → AS4 transport → settlement adapter (RTGS or CBDC ledger).
+
+---
+
+## 16. Appendix: ISO 20022 over AS4 vs over API
+
+| Dimension | AS4 | API |
+| --------- | --- | --- |
+| Reliability | Guaranteed | Best-effort |
+| Non-repudiation | Built-in | Custom |
+| Identity | PartyId-based | URL/token-based |
+| Audit | Native | Add-on |
+| Regulatory fit | High | Medium |
+| Latency | Higher | Lower |
+
+**Guidance:** AS4 for interbank, regulated, cross-border. API for internal, fintech, low-latency. **Hybrid:** API inside the bank; AS4 between banks.
+
+---
+
+## 17. Rail-template alignment
+
+| Section | Content |
+| ------- | ------- |
+| Owner/authority | ISO 20022, OASIS ebMS 3.0 / AS4; as4-411 directory only. |
+| Identifier scheme | BIC, LEI; as4.partyId with scope/partyIdType. |
+| Addressing | HTTPS endpoint; profile as4.fifi.iso20022.v1. |
+| Security | Mandatory sign + encrypt; HTTPS; optional mTLS. |
+| Discovery | Directory-driven; no public discover-any-BIC. |
+| Compliance | data-classification (BIC/LEI Tier 0/1). |
+| Sample payloads | §11–12; test-vectors and scheme profiles. |
+
+Scheme-specific profiles (TARGET2, Fedwire, CHAPS): [iso20022-scheme-profiles.md](iso20022-scheme-profiles.md).
--- a/docs/protocols/iso20022-scheme-profiles.md
+++ b/docs/protocols/iso20022-scheme-profiles.md
@@ -0,0 +1,39 @@
+# Scheme-specific profiles (ISO 20022 over AS4)
+
+Constraint layers on top of the base FI-to-FI profile **as4.fifi.iso20022.v1** (service **iso20022.fi**, same [Action taxonomy](iso20022-over-as4.md#service--action-taxonomy)). The directory may store scheme in constraints or as transport_profile variant (e.g. `as4.fifi.iso20022.v1.target2`).
+
+---
+
+## TARGET2
+
+- **Base profile:** as4.fifi.iso20022.v1
+- **Identifiers:** BIC; TARGET2 participant ID (scheme-specific)
+- **MPC:** `urgent` for RTGS traffic
+- **SLA / timeouts:** Per ECB TARGET2 documentation; tight windows for real-time settlement
+- **Reference:** ECB TARGET2 documentation and rulebooks
+
+---
+
+## Fedwire
+
+- **Base profile:** as4.fifi.iso20022.v1
+- **Identifiers:** Fedwire-specific participant / routing identifiers; US-facing
+- **MPC:** As per scheme (e.g. `default` or `urgent` for time-critical)
+- **SLA / timeouts:** Per Fedwire rules
+- **Reference:** Fedwire documentation and operator rules
+
+---
+
+## CHAPS
+
+- **Base profile:** as4.fifi.iso20022.v1
+- **Identifiers:** UK CHAPS participant identifiers; BIC where applicable
+- **MPC:** As per CHAPS rules (e.g. `urgent` for same-day)
+- **SLA / timeouts:** Per CHAPS rules
+- **Reference:** CHAPS documentation and Bank of England rules
+
+---
+
+## Catalog
+
+See [catalog.md](catalog.md). ISO 20022 over AS4 (FI-to-FI) links to this document for scheme-specific profiles.
--- a/docs/protocols/ktt.md
+++ b/docs/protocols/ktt.md
@@ -0,0 +1,30 @@
+# KTT Rail (Placeholder)
+
+## Status
+
+KTT is a **rail plugin slot** until sector-specific definition. The name is used in different sectors for different systems; this document reserves the slot and describes placeholder behavior.
+
+## Identifier Types
+
+- **ktt.id** — Generic KTT identifier; format: alphanumeric, optional `.` `_` `-`.
+- **ktt.participantId** — Same validation as ktt.id.
+
+Validation is in `@as4-411/core` (validation.ts). A valid `ktt.*` identifier can be stored and resolved to a RouteDirective like any other identifier once directory data exists.
+
+## Endpoints
+
+To be defined when the rail is specified. Use standard protocol values (https, mq, etc.) and a profile name indicating the KTT channel.
+
+## Trust and Directory Source
+
+- **Authoritative directory source(s):** TBD per sector.
+- **Trust constraints:** TBD. Prefer tenant scoping and explicit allow/deny.
+
+## Connector
+
+- **packages/connectors/ktt**: Placeholder adapter with `ingestFromFile` and `ingestFromApi` stubs. When the rail is defined, implement ingest that maps external participants/identifiers/endpoints into the core directory model.
+
+## Acceptance
+
+- A valid `ktt.*` identifier resolves to at least one RouteDirective when directory data is present.
+- Adapter supports ingest (file + API modes) as stubs; full implementation when KTT is clarified.
--- a/docs/protocols/test-vectors/iso20022-as4/README.md
+++ b/docs/protocols/test-vectors/iso20022-as4/README.md
@@ -0,0 +1,9 @@
+# ISO 20022 over AS4 — Golden test vectors
+
+Use these as golden request/response pairs for resolver tests. See [testing-strategy](../../architecture/testing-strategy.md).
+
+- **bic-resolution.json** — BIC + iso20022.fi + credit.transfer → primary directive with profile as4.fifi.iso20022.v1.
+- **lei-resolution.json** — LEI resolution; evidence may include LEI→BIC mapping.
+- **negative-unknown-identifier.json** — Unknown identifier → empty directives, negative_cache_ttl set.
+
+Tests: seed store (or routing artifact) with participant/endpoint for BIC/LEI; run resolve with request; assert output matches expectedResponse (or key fields). Placeholder URLs and cert refs (e.g. https://as4.bankus.com/fi) are for assertion only; replace with test fixtures as needed.
--- a/docs/protocols/test-vectors/iso20022-as4/bic-resolution.json
+++ b/docs/protocols/test-vectors/iso20022-as4/bic-resolution.json
@@ -0,0 +1,29 @@
+{
+  "description": "BIC-based resolution for ISO 20022 FI-to-FI. Service iso20022.fi, action credit.transfer.",
+  "request": {
+    "identifiers": [
+      { "type": "as4.partyId", "value": "BANKUS33XXX", "scope": "BIC" }
+    ],
+    "serviceContext": {
+      "service": "iso20022.fi",
+      "action": "credit.transfer"
+    }
+  },
+  "expectedResponse": {
+    "primary": {
+      "target_protocol": "as4",
+      "target_address": "https://as4.bankus.com/fi",
+      "transport_profile": "as4.fifi.iso20022.v1",
+      "security": {
+        "signRequired": true,
+        "encryptRequired": true,
+        "keyRefs": ["vault://certs/bankus/iso20022"]
+      },
+      "service_context": {
+        "service": "iso20022.fi",
+        "action": "credit.transfer"
+      }
+    },
+    "resolution_trace": [{ "source": "internal directory" }]
+  }
+}
--- a/docs/protocols/test-vectors/iso20022-as4/lei-resolution.json
+++ b/docs/protocols/test-vectors/iso20022-as4/lei-resolution.json
@@ -0,0 +1,30 @@
+{
+  "description": "LEI-based resolution; directory maps LEI to BIC(s) then to AS4 endpoint. Evidence may include LEI->BIC mapping source.",
+  "request": {
+    "identifiers": [
+      { "type": "as4.partyId", "value": "5493001KJTIIGC8Y1R12", "scope": "LEI" }
+    ],
+    "serviceContext": {
+      "service": "iso20022.fi",
+      "action": "fi.credit.transfer"
+    }
+  },
+  "expectedResponse": {
+    "primary": {
+      "target_protocol": "as4",
+      "target_address": "https://as4.bankus.com/fi",
+      "transport_profile": "as4.fifi.iso20022.v1",
+      "security": {
+        "signRequired": true,
+        "encryptRequired": true,
+        "keyRefs": ["vault://certs/bankus/iso20022"]
+      },
+      "service_context": {
+        "service": "iso20022.fi",
+        "action": "fi.credit.transfer"
+      },
+      "evidence": [{ "source": "internal directory", "message": "LEI to BIC mapping applied" }]
+    },
+    "resolution_trace": [{ "source": "internal directory" }]
+  }
+}
--- a/docs/protocols/test-vectors/iso20022-as4/negative-unknown-identifier.json
+++ b/docs/protocols/test-vectors/iso20022-as4/negative-unknown-identifier.json
@@ -0,0 +1,16 @@
+{
+  "description": "Unknown BIC/LEI: no match. Response must have no primary (or empty directives) and negative_cache_ttl set.",
+  "request": {
+    "identifiers": [
+      { "type": "as4.partyId", "value": "UNKNOWNBICXXX", "scope": "BIC" }
+    ],
+    "serviceContext": {
+      "service": "iso20022.fi",
+      "action": "credit.transfer"
+    }
+  },
+  "expectedResponse": {
+    "directives": [],
+    "negative_cache_ttl": 60
+  }
+}