@shopkit/apps-platform

Apps Platform runtime: iframe host adapter, capability validator, and the static sandbox shell that ships to apps.ratio.win.

What's in this package

| Export | Purpose | | --- | --- | | HostAdapter | Base host adapter — mounts a sandboxed iframe, performs the LOAD_APP_CODE handshake, routes RPC through a capability-validated funnel | | CapabilityValidator | Per-method capability check against a manifest's declared scopes; per-surface allowlist enforcement | | EmbedsHostAdapter | Concrete subclass for the Embed surface | | sandbox-shell/sandbox.html | Static HTML deployed at apps.ratio.win/sandbox.html. Every Apps Platform iframe loads this URL. |

Subclasses for Block / Account / Checkout / Admin surfaces ship in later Phase 1 / 2 / 4 stories.

Quick usage (host side)

import { EmbedsHostAdapter } from "@shopkit/apps-platform";

const adapter = new EmbedsHostAdapter({
  appId: "acme-reviews",
  manifest: installedAppManifest,
  shellUrl: "https://apps.ratio.win/sandbox.html",
  bundleUrl: "https://cdn.ratio.win/apps/acme-reviews/1.0.0/index.js",
  bundleIntegrity: "sha384-...",
  sessionJwt: sessionJwtForThisInstall,
  networkOrigins: ["https://api.acme.com"],
  rpcHandlers: {
    "cart.read":      async () => cartStore.read(),
    "customer.read":  async () => customerStore.read(),
  },
  audit: (event) => analytics.rpcAudit(event),
});

const slot = document.getElementById("embed-slot")!;
await adapter.mount(slot);  // resolves when app:ready arrives

Design

See ARCHITECTURE.md for the full design — what's locked, why each piece exists, and how it fits with Phase 2/4.

Cross-references:

• Architecture Reference §2.1 (sandbox runtime), §2.2 (host adapter), §3 (manifest contract), §4 (per-surface)
• Spike outcomes that shaped this package:
  • RAP-8 — iframe RPC throughput (p95 0.8–1.1 ms laptop, 1.0 ms iOS)
  • RAP-9 — capability validator (11/11 attacks blocked; source-check is the security boundary)
  • RAP-10 — two-layer auth (RFC 7519 + 8693; targetOrigin "*" required for sandboxed iframes)
  • RAP-11 — Block mount budget (LCP Δ +4 ms with 5 iframes on PDP)

Jira

RAP-12 — Sandbox infrastructure. Part of Phase 1 (RAP-3).