ptech-shell-runtime

Production-neutral implementations for contracts exported by ptech-shell-sdk.

This package owns HTTP transport, request context propagation, and host-configurable app settings/runtime caches. It does not own MSAL, React Router, UI, or standalone mocks.

import { createShellApiClientRuntime } from 'ptech-shell-runtime';

const runtime = createShellApiClientRuntime({
  apiBase: 'https://api.example.com',
  apiBaseRoutes: {
    reports: 'https://reports-api.example.com/v1',
  },
  originPolicy: {
    // Explicit host-owned opt-in for an additional context-bearing origin.
    trustedOrigins: ['https://telemetry.example.com'],
    // Optional request allowlist. Omit to allow public cross-origin requests
    // without shell context.
    allowedOrigins: ['https://public-catalog.example.com'],
  },
  getTenantService: () => tenantService,
  getUserService: () => userService,
});

registerService(TOKENS.apiClient, runtime.client);

Destination trust

The runtime resolves the final URL before acquiring an access token. The browser origin, apiBase, and every host-configured apiBaseRoutes origin are trusted automatically. Exact origins in originPolicy.trustedOrigins are the only other destinations that may receive Authorization/cookie, X-Tenant-Id, trace, and correlation context.

An arbitrary cross-origin absolute URL remains callable by default, but the runtime strips shell context, forces credentials: 'omit', and ignores response trace headers. Set originPolicy.allowedOrigins to reject destinations outside the host policy. A request can use shellContext: 'omit' for an explicit opt-out; there is deliberately no per-request include bypass.

Context-bearing redirects use redirect: 'error' by default because a redirect can cross origins after headers are prepared. contextualRedirects: 'follow' is available only as an explicit host-owned compatibility setting for a fully controlled redirect chain.