Skip to main content
gatewayadaptersdigital-twinsintegrationsnamespacesecurityservices
Status: DraftAuthor: Jacob ReppCreated: Apr 13, 2026Updated: Apr 13, 2026

RFC-066: Integrated Services and Namespace-Bound Adapters

Summary​

This RFC defines how Prism can expand beyond pure data proxying to support:

  • digital twin integrations
  • external API adapters
  • protocol bridges
  • specialized namespace-bound service surfaces

without collapsing into an unrestricted generic API gateway.

The design principle is:

Integrated services enter Prism as typed adapters bound to namespaces and explicit authorization actions, not as arbitrary tenant-supplied endpoints.

Motivation​

Prism's roadmap is naturally expanding past classic data backends. Digital twins and API integrations are valid product directions because they still benefit from:

  • namespace isolation
  • centralized authN/authZ
  • auditability
  • policy-driven control over backend access

The previous RFC-063 draft tried to solve this with unrestricted "service vendoring." That model created unresolved problems:

  • arbitrary endpoint registration
  • SSRF risk
  • unclear ownership boundaries
  • no integration classification
  • architecture drift from ADR-059's transparent proxy design

This RFC provides a controlled expansion path instead.

Goals​

  1. Define safe integration classes for non-pattern services.
  2. Preserve namespace-first authorization semantics.
  3. Define ownership, registration, and egress rules for adapters.
  4. Support digital twin and external API scenarios without making Prism a generic API gateway.
  5. Reuse the RFC-063 backend token and proxy trust model.

Non-Goals​

  • Allowing any namespace admin to register arbitrary URLs or hosts
  • Replacing pattern processes for Prism-native data APIs
  • Building full REST API management features
  • Hiding all integration complexity behind a generic shim promise

Decision​

1. Prism Supports Typed Integration Classes​

All integrated services MUST belong to one of these classes:

  1. pattern-backed
  2. adapter-backed
  3. edge-integrated

Pattern-Backed​

Used when the integration behaves like a Prism-native pattern and can remain behind the launcher/pattern architecture.

Examples:

  • digital twin state storage over KeyValue semantics
  • event-backed twin update streams

Adapter-Backed​

Used when Prism needs a protocol-aware adapter that translates Prism operations into an external system.

Examples:

  • digital twin command bridge to an IoT platform
  • REST adapter to a third-party control-plane API
  • GraphQL or SOAP translation layer

Edge-Integrated​

Used only when Prism intentionally exposes a specialized service surface at the edge and the proxy must understand more than namespace metadata.

Examples:

  • a tightly controlled namespace-scoped twin control API
  • a purpose-built integration endpoint owned by the platform

This class requires additional review because it moves closest to API-gateway behavior.

edge-integrated is not a configuration-only escape hatch. Each edge-integrated surface MUST have its own explicit design review that states:

  • why pattern-backed and adapter-backed are insufficient
  • what protocol-aware behavior the proxy must add
  • how the change interacts with ADR-059
  • what rollback path exists if the surface expands proxy scope too far

2. Registration Is Platform-Controlled, Not Arbitrary Self-Service​

Integrated services MUST be registered through a platform-controlled process that establishes:

  • service ownership
  • approved audience name
  • namespace bindings
  • allowed egress targets
  • health and resiliency requirements

Tenant-supplied arbitrary endpoints are NOT allowed by default.

3. Every Adapter Declares an Authorization Surface​

An integrated service MUST explicitly declare:

  • namespace scope
  • supported actions
  • audience identifier
  • protocol mode
  • data sensitivity

Example:

kind: NamespaceAdapter
metadata:
  name: iot-twin-control
spec:
  class: adapter-backed
  audience: adapter:iot-twin-control
  namespaces:
    - digital-twin-prod
  actions:
    - twin.read
    - twin.write
    - twin.command
  egress:
    allow:
      - iot-control.internal:443

4. RFC-063 Trust Model Still Applies​

Adapters and integrated services remain inside the Prism trust model:

  • proxy strips inbound x-prism-* headers
  • proxy authenticates and authorizes namespace actions
  • proxy mints backend tokens scoped to adapter audience and namespace
  • adapters validate backend tokens before trusting advisory metadata

No integration class may bypass the RFC-063 proof model.

5. Edge-Integrated Surfaces Require Explicit Approval​

An edge-integrated surface MUST NOT be introduced by configuration alone.

It requires:

  1. a dedicated ADR or RFC for that surface
  2. platform ownership
  3. explicit security review
  4. conformance tests showing namespace isolation and token-bound authorization

Architecture​

Adapter Flow​

Client
   │
   ▼
Prism Proxy
   │
   ├─ authN
   ├─ namespace authZ
   ├─ backend token minting
   ▼
Namespace-Bound Adapter
   │
   ├─ token validation
   ├─ protocol translation
   └─ approved egress to external system

Digital Twin Fit​

Digital twins fit Prism best in two modes:

  1. pattern-backed for twin state, history, and event access
  2. adapter-backed for command/control or external synchronization

That split is important because some twin workloads are data-plane oriented while others are protocol-translation oriented.

Security Considerations​

SSRF and Egress Abuse​

Adapters create outbound network authority. Prism MUST enforce:

  • approved target allowlists
  • ownership review
  • namespace-to-adapter bindings
  • audit logs for registration and traffic

Protocol-Aware Proxy Drift​

If too many integrations become edge-integrated, Prism risks drifting into a full API gateway. That class must remain the exception and require explicit architecture review.

Multi-Tenant Safety​

Adapters serving multiple namespaces must validate namespace-bound audiences carefully to prevent one tenant's tokens from being replayed against another tenant's adapter scope.

Implementation Plan​

Phase 1​

  1. Define integration class taxonomy and config schema.
  2. Define registration approval workflow and ownership metadata.
  3. Define adapter audience and action naming conventions.

Phase 2​

  1. Build one reference adapter-backed integration.
  2. Build one digital twin reference design showing pattern-backed plus adapter-backed components.
  3. Add conformance tests for token validation and namespace isolation.

Phase 3​

  1. Add egress policy enforcement.
  2. Add operational health and circuit-breaker requirements for adapters.
  3. Evaluate whether any edge-integrated surface is justified.

Revision History​

  • 2026-04-13: Initial draft split from RFC-063 foundation work