Proposal: CAIPE App Contract for native UI, iframe apps, and agent capabilities

[sriaradhyula]

Proposal: CAIPE App Contract for native UI, iframe apps, and agent capabilities

Status — October 13, 2026: Architecture proposal and phased roadmap. PR #2852 now implements Phases 0–1: native component interface 2.0, shared AgenticAppManifest API 2.0, and SDK/checker @caipe-io/app-sdk@2.0.0-rc.1, at snapshot 6aabb9a9cf4c3171fcf1d39a0bbf05bb1f299f02. The PR is open and unmerged. The App SDK package identity is prepared as an RC; npm publication is a separate release step and is not asserted here. CAS application grants, a shared iframe/native lifecycle SDK, and generic agent capability integration remain proposed follow-on phases.

Existing platform capabilities are reused where available. A capability appearing in an example or milestone does not imply that PR #2852 implements it.

TL;DR

• Establish one application contract for identity, installation, compatibility, capability declarations, requested permissions, and service integration.
• Support two UI profiles: trusted native packages for close CAIPE integration, and hosted iframe apps for independent UI deployment. Apps may be UI-only, service-only, or provide both.
• Native and current same-origin iframe code both require host-level trust. Less-trusted apps require an enforced isolated iframe profile; see the threat model in section 5.
• Treat the manifest like an Android manifest for declarations and review: it describes what an app provides and requests. Installation approval and runtime authorization are separate decisions.
• Reuse CAS, the Centralized Authorization Service, as the platform authorization boundary. API handlers, gateways, and services authenticate callers, request decisions, and enforce the result.
• Make Agent Builder a primary consumer of shared platform capability contracts. Components advertise agent-usable operations; apps, workflows, and headless clients consume agent/tool contracts independently of the builder UI.
• Build on existing MCP, A2A, workflow, credential, and authorization integrations. Avoid creating a second discovery protocol or a separate OpenFGA policy implementation in each app.
• Ship incrementally: Phase 0 / PR feat(ui): add shared AgenticAppManifest and native UI contract #2852 → shared manifest → CAS app authorization → shared host SDK → agent capabilities → release validation.

Phase 1 implementation update

CAIPE App Contract is the umbrella term for the shared manifest and rendering-profile interfaces. AgenticAppManifest remains the manifest type; native packages implement a native component interface. Public version fields and behavior are unchanged.

The name remains AgenticAppManifest. New publishers use API 2.0; existing hosted v1.0 and native v1.1 inputs have compatibility adapters. The complete native declaration is supplied by its pinned package, while enablement, UI selection, and private service/resource bindings stay deployment-owned. See PR #2852 and the implementation documentation.

This completes the shared declaration/registration foundation described in Phase 1. The CAS and Agent Builder sections below continue to describe the intended next phases. Permission requests remain metadata rather than effective grants.

1. Problem and intended outcome

CAIPE needs a consistent way to integrate independently maintained applications while preserving user identity, access controls, navigation, and agent interoperability.

Rendering is only one part of that problem:

• A native React package needs host compatibility, route ownership, styling, package integrity, and a coordinated image build.
• An iframe app needs a lifecycle and messaging contract, route synchronization, deployment configuration, and an explicit browser trust model.
• Both need app identity, installation policy, protected service access, audit context, and a discoverable description of any agent-usable operations.
• Agents, workflows, and scheduled jobs need those service contracts even when no application UI is loaded.

The proposed outcome is a small shared application model with rendering-specific adapters and platform service contracts. An app should be able to change its UI rendering profile without redefining its domain APIs, agent identity, or authorization semantics.

This proposal extends the External Apps architecture discussion. It preserves hosted apps and adds a trusted native option.

2. Architectural choices and trade-offs

Dimension	Trusted native package	Hosted iframe app
UI composition	React component integrated with CAIPE's host tree and document	Separate document and application lifecycle
Routing	Host router; canonical public paths	Host public route plus a synchronized child route
Theme and components	Can use shared host runtime and approved UI primitives	Theme/context supplied through the bridge; app owns its document styles
UI release	New pinned package requires a derived CAIPE UI image build and rollout	App service/UI can release independently while compatible with the host contract
Framework compatibility	Must match the supported host React/Next and SDK versions	Child may use an independent framework/runtime
Browser privileges	Shares CAIPE origin, DOM, storage, and session privileges	Depends on origin and sandbox configuration; separate document alone is insufficient
Initial work	Avoids a second document/runtime; loading strategy still matters	Loads another document/runtime; caching and retaining the frame can reduce repeated work
Failure behavior	Needs error/loading boundaries; failures may affect the host	Many UI failures remain in the child; resource exhaustion and bridge failures still need handling
Appropriate publishers	Reviewed, trusted code accepted into the host trust boundary	Independently deployed apps; less-trusted code only with enforced browser isolation

Keeping an app's source directly in CAIPE remains reasonable for a core feature. A package provides source ownership and a versioned extension boundary, but introduces packaging, compatibility, and release coordination costs.

Performance expectation: a well-integrated native package can approach a built-in feature's performance. Packaging alone does not guarantee equal startup, rendering, data-fetch, or navigation behavior. Iframe performance must likewise be measured for the actual app and deployment.

3. One app contract, separate rendering profiles

Contract layer	Common responsibility	Rendering-specific responsibility
Application identity	Stable ID, version, ownership, support metadata	Package identity or hosted deployment identity
Compatibility	Supported platform/API contract versions; required and optional capabilities	React/Next/runtime requirements or iframe bridge version
Surfaces	Route intent, navigation intent, internal visibility, optional slots	React integration or child URL/route mapping
Capabilities	References to provided and consumed agent, tool, workflow, and service contracts	Optional UI associated with a capability
Permission requests	Resource/action intent and audience requirements	Browser sandbox/permission-policy requests for iframe profiles
Installation	Approved app/artifact, enabled state, selected profile, bindings	Pinned native package or approved hosted endpoint
Authorization	Authenticated caller, CAS decisions, approved grant envelope, resource checks	Adapter-specific authentication transport
Observability	Correlation, lifecycle/error events, readiness marks	Hydration/component events or frame/bridge events

%%{init: {"htmlLabels": false, "flowchart": {"htmlLabels": false, "padding": 20, "nodeSpacing": 40, "rankSpacing": 45}}}%%
flowchart TD
    Manifest["Common application<br/>manifest"] --> Installation["Approved installation<br/>and deployment bindings"]
    Installation --> Native["Native UI adapter"]
    Installation --> Frame["Iframe UI adapter"]
    Native --> SDK["Common host SDK<br/>behavior"]
    Frame --> SDK
    SDK --> APIs["Platform and app<br/>service APIs"]
    Builder["Agent Builder"] --> APIs
    Headless["Workflows and<br/>headless clients"] --> APIs
    APIs --> Enforcement["Gateway and service<br/>enforcement"]
    Enforcement --> CAS["CAS decision<br/>boundary"]
    CAS --> FGA["OpenFGA adapter"]
    Enforcement --> Services["Agents, tools, workflows,<br/>and app services"]

Loading

The diagram describes the target. CAS answers authorization questions; execution continues through the responsible handler/service after an allow decision.

Internal applications and optional surfaces

• Navigation and app-catalog visibility are optional presentation choices.
• A hidden app may still have an authorized deep link or a contextual entry point.
• Hidden does not mean authorized; visible does not mean granted.
• Route-less UI contributions need explicitly supported slots.
• Service-only apps can advertise capabilities without providing a UI.
• UI-only apps need not invent agent capabilities.
• Native and iframe apps should follow the same installation and access semantics; visibility exceptions should not become separate security rules for each renderer.

4. Manifest model: declarations, approvals, and runtime decisions

The Android-manifest analogy is useful for identifying components, required capabilities, compatibility, and permission requests. Its operating-system isolation does not transfer to native JavaScript inside a shared browser document.

Use three separate records:

1. Publisher manifest: immutable app metadata; provided surfaces/capabilities; required contracts; requested permissions.
2. Installation policy: operator-approved version/artifact and selected UI profile; service bindings; approved permission envelope; enablement and visibility.
3. Authorization state: grants and relationships for verified user/service principals, managed through CAS and approved relationship adapters.

A publisher cannot grant itself access by editing its manifest. An app update that expands requested authority must produce a reviewable permission diff. Existing approval must not silently expand to cover new requests.

Illustrative future manifest

PR #2852 now provides AgenticAppManifest API 2.0. The following is the original illustrative design sketch, retained to explain the declaration/installation boundary; it is not the executable schema. Use the implemented Phase 1 reference for current field names and checker behavior. Registry references do not provision services automatically.

schemaVersion: proposal
id: example-app
version: 1.0.0
displayName: Example App
description: Example application with native and hosted UI options

ui:
  profiles:
    - id: native
      mode: native-package
      package: "@example/native-app"
      packageVersion: 1.0.0
    - id: hosted
      mode: iframe
      runtimeBinding: example-ui
      bridgeContract: app-host-v1
  routes:
    - id: home
      defaultPath: /tools/example
  navigation:
    routeRef: home
    label: Example

provides:
  mcp:
    - registryRef: example-mcp
  agents:
    - registryRef: example-agent
  workflows:
    - registryRef: example-workflow

consumes:
  platformApis:
    - id: agents.discovery
      required: true
    - id: agents.invocation
      required: true

requestedPermissions:
  - resourceType: agent
    resourceBinding: assistant
    actions: [use]
  - resourceType: knowledge_base
    resourceBinding: selected-knowledge-base
    actions: [read]

auth:
  mode: app-scoped-token
  audienceBinding: example-api

The concrete agent/resource IDs and runtime origins are bound by the approved installation. Secrets, raw tokens, and connected credentials do not belong in a publisher manifest or browser context.

An illustrative installation records appId, appVersion, manifestDigest, selectedUiProfile, installed, enabled, visible, bindings, and references to the approved permission requests. Actual permission grants target authenticated principals and must retain their own ownership, audit, and revocation semantics.

Claims are different from permissions

• Claiming a URL establishes routing ownership; it does not authorize access to data at that URL.
• Advertising an agent/tool establishes discoverability; it does not authorize invocation.
• Requesting access to a credential does not reveal its value or override resource authorization.
• Installation approval establishes the accepted integration and authority envelope; each protected operation still needs the applicable caller/resource decision.

Stable route references should let the host bind concrete paths without downstream apps hard-coding another app's URL. Reserved paths and collisions must be checked for every rendering profile.

5. Threat model: native packages and iframe apps

Summary: native packages are trusted host code. The current same-origin, unsandboxed iframe is also a trusted-code profile—not an untrusted-app sandbox. A separately hosted backend or a different URL path does not change that browser boundary. An isolated iframe is a distinct future trust profile with additional enforcement requirements.

5.1 Scope, assets, and attackers

This model assumes an authenticated browser, HTTPS in deployed environments, a CAIPE shell/BFF, operator-owned installation configuration, and separately deployed app services. It distinguishes browser compromise from service compromise and build/publisher compromise. The source snapshot is PR #2852 at 6bfd938; these are source-level observations, not a penetration-test certification of any deployment.

Protect:

• Session continuity, access tokens, stable user identity, and tenant/resource boundaries.
• Data rendered by the host and other apps, conversations, documents, and authorization decisions.
• Connected credentials, signing keys, and infrastructure/build secrets.
• Route/API ownership, approved service destinations, installation configuration, and audit integrity.
• Host availability and safe agent/tool/workflow execution.

Consider attackers:

• A compromised publisher, dependency, build runner, package registry account, or hosted app deployment.
• Malicious content that reaches an app through Markdown, HTML, diagrams, files, or tool output.
• An authenticated user attempting unauthorized resource access or identity substitution.
• Another frame/window attempting bridge abuse; an external site attempting forged cookie-authenticated requests.
• A compromised app service or agent attempting to use broader downstream authority.

An app being first-party lowers the ownership uncertainty; it does not eliminate XSS, supply-chain, or compromised-deployment risk.

5.2 Browser trust profiles

Property	Trusted native package	Current same-origin iframe	Proposed isolated iframe
Execution	Package code integrated into the host React application	Independent app URL, document, and React runtime	Independent app on a dedicated origin with reviewed sandbox policy
Host DOM	Direct access	Same-origin child can access parent DOM	Same-origin policy blocks direct parent DOM access
Host storage	Same origin storage and JavaScript-visible state	Same-origin storage; separate React state is not isolation	Separate origin storage; no shared host credentials by design
Acting as the user	Can attempt host API calls using the session	Can attempt the same authenticated host API calls	Host requests must be mediated; CSRF and backend checks remain necessary
Publication compromise	Affects approved host image/build and then user sessions	A hosted UI update can alter executing code without rebuilding host	Child compromise remains dangerous to child data and approved bridge operations
Primary boundary	Publisher/build trust plus backend authorization	Hosted-publisher trust plus backend authorization	Browser origin/sandbox plus narrowly authorized broker and backend authorization

For example, https://example.com/ and https://example.com/apps/example/ have the same origin. Origin is scheme, host, and port—not repository, service container, or URL path. Independent React trees do not create access-control boundaries. MDN: same-origin policy.

flowchart TB
    subgraph Shared["Current trusted browser origin"]
        Host["CAIPE shell and DOM"]
        Native["Native package in host React tree"]
        Frame["Same-origin iframe: separate document"]
        Session["Host session and JavaScript-visible state"]
        Native --> Host
        Frame -->|"same-origin DOM access"| Host
        Native --> Session
        Frame --> Session
    end
    subgraph Isolated["Proposed dedicated app origin"]
        Child["Restricted iframe app"]
    end
    Child <-->|"bounded validated messages"| Broker["Host bridge"]
    Broker --> Host
    Native --> PEP["BFF/API enforcement"]
    Frame --> PEP
    Broker --> PEP
    PEP --> Policy["Applicable authorization checks"]
    Policy --> Service["App service and resource authorization"]

Loading

The isolated profile is not implemented by selecting mode: iframe in the present manifest. Backend enforcement still applies to every profile.

5.3 Native package threats and controls

• Supply chain: package installation, transitive imports, build tooling, and Next.js rendering can execute code within host build/server processes. Review the complete dependency graph, use narrowly scoped ephemeral CI credentials, and avoid making production secrets available to publisher builds.
• Browser compromise: an accepted package can inspect host DOM, manipulate UI, read JavaScript-accessible state, and request other host APIs as the user. The SDK's API client and permission declarations cannot force malicious code to use only the SDK.
• Content injection: unsafe rendering in an extension becomes a host-origin XSS risk. Sanitize rich content at appropriate boundaries; apply a reviewed CSP as defense in depth.
• UI interference: scoped CSS, loading boundaries, and React error boundaries improve reliability. They do not contain malicious JavaScript, infinite loops, or unrestricted host DOM mutation.
• Artifact controls: PR feat(ui): add shared AgenticAppManifest and native UI contract #2852 requires exact/integrity-recorded packages or confined tarballs, checks contract/export compatibility, rejects reserved/colliding claims, and validates selected modules before registry generation. Integrity proves expected bytes, not benign behavior.
• Residual risk: disabling navigation or gateway access does not uninstall compiled code. The current generator uses static imports and stylesheet inclusion. Removing a compromised package requires a clean rebuilt/rolled-back host image and assessment of sessions/data already exposed.

These conclusions follow from the reviewed native integration implementation and its build-time trust assumptions.

5.4 Same-origin iframe versus isolated iframe threats

The current shell embeds a same-origin gateway URL without a sandbox attribute and requests clipboard permissions. Separate documents provide layout/style separation and independent releases, but a compromised child remains able to affect the host origin. An iframe from another service reverse-proxied onto the same browser origin is still same-origin.

For a less-trusted profile:

• Serve app content from a dedicated origin, including direct-link access; do not reverse-proxy it back into the trusted host origin.
• Apply a minimal sandbox policy. Do not combine allow-scripts and allow-same-origin for host-origin content: that child can remove the sandbox. On a genuinely different origin, allow-same-origin preserves the child's own origin; it does not make it the host origin.
• Grant clipboard, camera, microphone, downloads, popups, and top navigation only when justified. Browser feature permissions are different from app/domain authorization.
• Review parent frame-src, child frame-ancestors, script/network policies, redirect destinations, and direct-navigation behavior. Origin isolation does not guarantee CPU/process isolation or prevent phishing inside an approved frame.

These sandbox and browser-feature distinctions are defined by MDN: iframe controls.

Current proxy limitation: the gateway filters upstream Content-Security-Policy, X-Frame-Options, and Set-Cookie. Do not assume a hosted service's headers survive this proxy. An isolated-profile implementation needs deliberate host/child policy enforcement rather than merely adding manifest fields.

5.5 Session, JWT, and user-context threats

Current behavior: both native code and same-origin framed code can use the CAIPE browser session. The gateway authenticates the session and derives the user; it does not need to copy the session cookie into component props or messages. The current session callback exposes accessToken to first-party browser code. Thus neither current profile isolates that bearer token from a compromised app.

Recommended transport and lifecycle controls:

• Keep refresh tokens, signing keys, and connected-credential values server-side. Prefer BFF mediation to distributing reusable bearer tokens into UI state.
• Use HTTPS, HttpOnly session cookies, appropriate Secure/SameSite settings, and narrow host scope. Do not share parent-domain session cookies with a less-trusted app origin.
• HttpOnly prevents reading the cookie value; it does not stop host-origin malicious code from making authenticated requests. Cookie paths are not an app security boundary.
• Apply CSRF defenses to cookie-authenticated mutations. SameSite alone does not isolate sibling same-site origins or protect against same-origin XSS.
• On logout, account/tenant changes, expiry, or app disablement, discard stale UI data and pending bridge requests. Keep personalized data out of immutable/shared asset caches; enforce identity/resource boundaries server-side as well.

Cookie and session safeguards are described in OWASP: session management; the bullets are requirements to validate, not a claim that PR #2852 adds all of them.

Gateway mode	Benefit	Residual risk and service responsibility
app-scoped-token	Short-lived user token bound to the app audience and declared operation scopes	Limits that token's accepted authority; does not isolate browser code. App services still validate identity and enforce domain/resource access.
forward-user-access-token	Existing identity-provider access token can support services already configured to accept it	Forwarding does not attenuate existing authority. A compromised recipient can misuse a stolen bearer token wherever it is accepted. Explicit receiving-service trust is required.

A user ID is an identifier, not authentication proof. Receiving services must verify signatures with trusted keys, allowed algorithms, issuer, audience, expiry and applicable claims; distinguish access tokens from ID/session tokens. Never trust an unsigned sub, role header, route context, or claimed app ID as authorization. Short expiry reduces exposure but does not guarantee immediate revocation. RFC 8725: JWT security practices.

Important limitation: using an app-scoped token on the gateway-to-service hop cannot prevent current host-origin app code from calling a different host endpoint using the same user's session. It protects a service credential boundary, not an npm-package/browser boundary.

5.6 Bridge abuse and confused-deputy threats

A future common iframe SDK must treat every bridge operation as input—not as authority:

• Verify exact sender origin and the expected contentWindow/event.source; an allowed origin may contain multiple frames.
• Validate message type/schema, bounded payloads, route ownership, requested operation, and response correlation.
• Bind a handshake to the active installation, frame instance and login lifecycle. Discard stale messages after frame navigation, logout, or account changes.
• Avoid credentials in messages or URL parameters. Use bounded context and server-authorized operations.
• A sandboxed opaque origin reports "null"; that string is not a trusted identity. Any opaque-origin bridge requires an explicitly designed channel-binding protocol.

Origin/source and exact targetOrigin handling are documented in MDN: postMessage.

For current same-origin hostile code, message validation alone is insufficient: the child can bypass the intended bridge and use direct DOM/API access. Use actual isolation before claiming that the bridge is its only authority path.

Confused deputy: an app must not supply a user ID, agent ID, credential reference or service URL and cause the host to execute with broader authority. Bind destinations/resources to the approved installation, derive the verified caller server-side, and independently authorize the concrete operation. This is the intended Phase 2–4 enforcement design, not a complete capability broker in PR #2852.

5.7 Next.js build and rendering boundary

"use client" selects the client-component module boundary, not a security sandbox. Next.js prerenders Client Components for initial page loads and hydrates them in the browser. Therefore publisher code needs build/render as well as browser review. Next.js: server and client components.

The checker rejects declared server exports and listed server-only import patterns. It does not prove that all transitive code is browser-only or harmless. SSR opt-out, when explicitly configured for a rendering adapter, changes when component rendering occurs; it does not neutralize installation tooling or unsafe package imports.

5.8 Backend authorization, credentials, and agent execution

For both renderers:

• Treat launch authorization as a UX/access gate, not permission to read every resource or invoke every tool.
• Validate direct app API, MCP, agent, webhook, and scheduled-job ingress. Calls that bypass the UI must not bypass resource checks.
• Preserve the execution principal: user, service account, or explicitly delegated job. Do not reinterpret a steward/service credential as the user's unrestricted authority.
• Authorize credential use and the actual target resource before ingestion or agent/tool execution. Keep secret values behind the credential boundary.
• Treat model/tool output and app-provided context as untrusted data. An agent reference or prompt cannot override authorization or approval requirements.
• Fail closed for protected operations when authorization is unavailable. Re-evaluate effective access after grant changes; inherited grants and cached decisions need explicit semantics.
• Derive audit identity server-side. Browser app/route context and client correlation IDs are metadata, not proof of the calling package.

The shared CAS target is described in section 6. PR #2852 retains existing session/role/HTTP-policy enforcement; it does not implement the proposed application CAS grants or universal broker.

5.9 Current controls versus required follow-on evidence

Threat	Existing foundation in PR #2852	Follow-on acceptance evidence
Undeclared or conflicting app surfaces	Manifest/component-contract validation, installation/profile checks, reserved route/API claims	Upgrade permission-diff review and compatibility matrix
Denied app shown or launched	Access-filtered native navigation; server launch/gateway checks; hidden is not granted	CAS-backed app discover/use/manage and direct-ingress tests
Agent denied or unavailable	Assistant waits for enabled-agent lookup before creating history; retry regressions	Full invocation, cancellation, identity and resource-denial tests
Compromised native dependency	Exact pins, lock integrity, confined artifacts, checker gates	Provenance/dependency review, isolated CI, rebuild/rollback incident exercise
Compromised same-origin iframe	No claimed malicious-code isolation	Dedicated-origin/sandbox profile; host/child CSP and permission tests
Token theft or excessive delegation	Explicit gateway auth mode and verified-session identity	Browser token-exposure assessment, audience/expiry/replay and revocation tests
Bridge spoofing or stale user context	No common iframe/native lifecycle SDK claimed	Wrong-origin/source, malformed payload, navigation, logout and account-switch tests
Service/credential/agent bypass	Existing gateway policy plus app-owned service enforcement	CAS/resource/credential tests across UI, MCP, agents and scheduled execution

These are threat-model test obligations, not all passing results today.

5.10 Recommendation and explicit residual risk

• Trusted first-party/native-UX applications: native packages are appropriate when their code and supply chain are accepted as host code. Use backend least privilege, reproducible builds, reviewed updates, and full-image rollback.
• Trusted independently deployed applications: same-origin iframes are valid for deployment/framework separation, but publish the same broad browser-trust assumption.
• Less-trusted applications: require an enforced isolated-origin iframe profile and a narrow authorized bridge before installation. Do not promise this from the present iframe selector.
• Services and capabilities: share identity, installation, CAS and protocol contracts across profiles, but keep browser permissions, requested domain authority, and actual grants distinct.

Separate repositories, Shadow DOM/scoped CSS, React trees, manifests, and integrity hashes do not individually create a malicious-code sandbox. OWASP: micro-frontend boundaries.

Residual risk accepted by current trusted profiles: an app compromise can affect host-visible data and exercise the user's otherwise authorized session. Backend authorization limits access beyond that user's authority; it cannot make hostile code safe inside the user's trusted browser context.

6. CAS: shared authorization for both rendering modes

Current foundation

CAS means CAIPE's Centralized Authorization Service in ui/src/lib/authz. In the reviewed source snapshot it is a module inside the BFF; this proposal does not assume a separately deployed CAS service.

Existing foundation APIs include:

Operation	Purpose
POST /api/access/check	Check the authenticated caller's action on a resource
POST /api/access/query	Filter a supplied, bounded page of candidate resource IDs
POST /api/access/grants	Add a grant after management authorization
DELETE /api/access/grants	Remove a direct grant after management authorization

BFF callers use CAS in process. Remote consumers need an approved authenticated adapter/API. Existing legacy authorization and gateway paths are not all migrated; adding the app contract must not imply that platform-wide CAS migration is complete.

Identity rules

• Derive the caller from a verified session or bearer token.
• Bind checks to that authenticated caller.
• The current public Access API does not accept an arbitrary subject, delegated identity, or caller-supplied trusted context.
• A service token asks about the service's own authority. It does not become the end user's identity because a request body contains a user ID.
• On-behalf-of user checks need a verified user credential or an explicitly designed, authenticated delegation adapter.
• An internal gateway adapter must authenticate its caller and validate the source of delegated identity/context. Forwarded headers alone are insufficient.
• A user-context token intended for an app API is not automatically a credential accepted by CAS; issuer, audience, and adapter trust requirements must be satisfied.

Proposed app authorization model

Phase 2 should add application resources and actions through the approved resource-model and CAS adapter boundary. The exact new resource name and action vocabulary require design review; examples such as application/use below are proposed, not current supported Access API pairs.

The model should distinguish:

• Discover: may the caller see this installed app or its capabilities?
• Use/launch: may the caller enter or invoke the app?
• Manage installation: may an administrator enable, disable, configure, or approve requested permissions?
• Use a referenced capability: may the caller invoke the specific agent, workflow, or tool?
• Access the target resource: may the operation read or change the actual domain object?

For each protected operation, all applicable conditions must allow it:

approved installation and operation envelope
AND authenticated caller authorization
AND applicable agent/tool/workflow policy
AND target resource authorization

This is the target enforcement rule, not a claim that every layer is already wired. The envelope can restrict brokered service operations; it does not isolate native JavaScript from all host browser APIs.

Example request lifecycle

sequenceDiagram
    actor User
    participant UI as Native or iframe UI
    participant PEP as Gateway / API handler
    participant CAS as CAS module or authenticated adapter
    participant FGA as OpenFGA
    participant Service as App / agent service

    User->>UI: Request protected operation
    UI->>PEP: Authenticated request
    PEP->>PEP: Verify caller, installation, binding, and input
    PEP->>CAS: Caller-bound action/resource check
    CAS->>FGA: Evaluate policy and relationships
    FGA-->>CAS: Decision
    CAS-->>PEP: ALLOW, DENY, or unavailable

    alt Authorized
        PEP->>Service: Approved operation with verified identity
        Service->>Service: Enforce domain and downstream resource access
        Service-->>UI: Result and correlation context
    else Denied or unavailable
        PEP-->>UI: Stop operation with appropriate error
    end

Loading

The service must enforce its checks when invoked directly, including by agents, MCP callers, webhooks, or schedules. A browser launch check is not a substitute for data-plane authorization.

Failure, cache, revocation, and audit rules

• A completed Access API check can return HTTP 200 with DENY. Callers must inspect the decision.
• Authorization unavailability is an error; do not convert it to allow or silently return an empty capability catalog.
• Frontend access checks improve UX; backend execution checks remain authoritative.
• The current query API filters at most 200 supplied IDs. It is not an unbounded discovery/catalog service.
• Single agent/use checks currently have fresher execution semantics than some batch/list decisions. Do not enforce invocation from a stale picker result.
• Define and test revocation/cache freshness for new app actions. HTTP no-store and short token lifetimes do not by themselves provide immediate revocation.
• Removing a direct grant may leave inherited/team grants. Report effective access accurately.
• Route relationship changes through CAS-approved grant/reconcile helpers so audit and invalidation are preserved.
• Audit should correlate the installation, authenticated principal, action, target resource, decision, and execution trace. Browser-supplied app/route context is descriptive metadata, not proof of identity.
• Disabling an app must block new protected operations. Cancellation of already running work requires explicit runtime semantics.

Credentials and domain authorization

Connected credentials stay behind the credential-management boundary. Services request authorized use of a credential; browser components do not receive raw secrets.

A steward, owner, or service credential must not widen a requesting user's access implicitly. The service must validate the operation's execution identity and policy, credential-use permission, and target-resource access. App-owned domain resources should use approved authorization adapters and scoped relationship ownership; apps must not mutate unrelated platform/team/admin relations directly.

7. Authentication continuity without unrestricted token sharing

Both UI profiles should preserve one CAIPE sign-in and a stable user subject. Authentication mode and service audience are deployment-reviewed contract choices.

• The existing default gateway mode mints a short-lived app-scoped user token.
• The current native contract also permits explicitly configured forward-user-access-token.
• The receiving service must validate issuer, audience, expiry, and the appropriate authorization.
• PR feat(ui): add shared AgenticAppManifest and native UI contract #2852 does not implement a general token-exchange/delegation framework for all downstream services.
• A token is not passed as a native component prop. However, first-party code can access the current CAIPE session's exposed access-token field; the absence of a token prop is not browser token isolation.
• Iframe bridge messages should carry bounded context and mediated requests rather than raw CAIPE session cookies or bearer tokens.
• Machine callers use supported bearer/service ingress and authorization; they cannot depend on a browser session.
• End-user operations, service-account operations, and explicitly delegated scheduled execution must remain distinguishable.

One user login should feel continuous across apps while each service's accepted authority remains explicit.

8. Agent Builder, agents, tools, and workflow contracts

Agent Builder is a core CAIPE experience for discovering, configuring, and composing agent capabilities. The underlying contracts belong to the platform APIs and runtime, so their use does not depend on the builder UI being loaded.

Providers advertise; consumers compose and invoke

flowchart LR
    AppServices["App services"] -->|MCP tools| Registry["Existing registries + capability adapters"]
    RemoteAgents["Remote agents"] -->|A2A cards and skills| Registry
    Workflows["Workflow services"] -->|Workflow references and schemas| Registry
    Registry -->|Authorized discovery| Builder["Agent Builder"]
    Registry -->|Authorized discovery| Apps["Native and iframe apps"]
    Builder -->|Persist configuration references| Runtime["Agent/runtime service APIs"]
    Apps -->|Invoke or subscribe| Runtime
    Headless["Schedules and headless clients"] -->|Invoke| Runtime
    Runtime --> Authz["CAS and downstream enforcement"]

Loading

Reuse existing protocol foundations

Capability	Existing foundation	Contract work
Agent-usable tools	MCP discovery and tool schemas	Registry references, access filtering, credential bindings, operation policy
Remote agents	A2A Agent Cards, skills, tasks, streaming, cancellation	Supported-version adapters, registry approval, authorization, UI/runtime clients
Workflows	Existing workflow configs and execution APIs	Versioned references, inputs/outputs, execution/status contracts
Platform-managed agents	Existing agent APIs/runtime	Stable consumer APIs, lifecycle/status behavior, authorization alignment
App domain APIs	App-owned service contracts	Documented versioned APIs; adapters where agent/tool exposure is useful

An app manifest should reference the source of capability truth rather than copy every live tool schema or agent description into a UI package.

• Required dependencies affect installation/enablement compatibility.
• Optional capabilities support graceful degradation.
• Capability changes need revision/cache invalidation semantics.
• Provider metadata is validated and registered through controlled server-side paths.
• Discovery permissions and invocation permissions are separate.
• Agent descriptions and tool annotations do not grant authority or establish that an operation is safe.
• Hidden/internal capabilities can be available to authorized consumers without public navigation.

Bidirectional integration examples

• A knowledge app exposes authorized context retrieval through MCP; Agent Builder can attach that capability to an agent.
• A native or iframe app consumes a platform-managed agent through the same invocation/status contract.
• A workflow invokes an approved remote agent through an A2A adapter.
• A service-only app registers capabilities without shipping a UI.
• A UI-only app participates in shell/auth integration without advertising tools.

Prefer meaningful domain operations with explicit inputs, outputs, and effects over exposing every UI button as a tool. Distinguish read operations from writes, approval-required actions, and long-running jobs. Runtime checks must re-evaluate the actual resource/action and approved execution identity.

Example: Workflows as a modular native feature

Workflows could publish a native UI package and AgenticAppManifest while retaining its existing backend. The UI would share CAIPE's React tree, session, theme, routing, and breadcrumbs; modular packaging does not require a separate repository.

Detailed Workflows example, architecture diagram, build lifecycle, and proposed built-in registration adapter.

Current boundary: external packages cannot claim reserved /workflows or replace workflow APIs. A PoC can use /workflow-studio; preserving the core route requires a separately designed, host-owned registration adapter. This is a proposal, not functionality delivered by PR #2852.

9. Host SDK and UI lifecycle

Phase 3 should define common behavioral operations, with transport-specific adapters.

Shared behavior	Native binding	Iframe binding
Initialize and negotiate compatibility	Host SDK/component initialization	Versioned handshake and approved host capabilities
Read bounded host context	SDK context/capabilities	Validated serialized context
Request navigation	Host router API	Message to host; host validates and updates router
Update breadcrumbs	Host breadcrumb API	Serialized breadcrumb request
Observe route/theme changes	SDK subscription/state	Ordered host events
Request a capability operation	Platform client through protected API	Mediated bridge or approved authenticated service API
Report ready/error/data timing	Host callbacks/marks	Validated lifecycle events
Release subscriptions/resources	Component cleanup	Explicit teardown/disconnect behavior

Common methods should have defined result/error semantics. React components and functions are not serialized across an iframe; each adapter implements local SDK methods over its transport. The current optional native Link prop remains a native-specific convenience.

Iframe messages must validate origin/source or the expected opaque-origin sandbox channel, schema, bounded payloads, and handshake/session identity. Requests need correlation, timeouts, and ordering to prevent stale route events from overwriting current navigation. Native integration needs cleanup, suspense/loading states, and error boundaries.

The canonical public route belongs to CAIPE. Internal host rewrite paths must not leak into app links. Route transitions should preserve app state when intended and invalidate resource-specific data when the route changes.

The MCP Apps host bridge and lifecycle offer patterns to reuse for tool-associated iframe views. Full routed applications still need route, session, and lifecycle requirements beyond a tool-result view.

10. Build, publish, install, and rollback

Native profile

1. Publisher builds compiled UI assets and runs the supported contract checker.
2. Publisher tests the package against its declared host compatibility matrix.
3. Deployment selects an exact package/tarball and records its integrity and source provenance.
4. Derived CAIPE UI build validates claims and generates the selected registry.
5. CI measures actual emitted initial assets and lazy chunks, including relevant transitive dependencies.
6. Rollout deploys the pinned host/package combination.
7. Rollback restores a compatible pinned host/package combination; runtime enablement does not remove compiled JavaScript from an image.

Use CI artifact caching and automated image assembly to reduce coordinated-release friction. Host-version compatibility and reproducible rollbacks remain operator responsibilities.

Iframe profile

1. Publisher releases its hosted UI/service and declares supported bridge/API versions.
2. Installation binds an approved runtime origin/service; the browser cannot supply arbitrary proxy targets.
3. Host verifies compatibility and applies the selected origin/sandbox/CSP/permission policy.
4. Rollout may update the app independently when shared contracts remain compatible.
5. Rollback restores the app service/configuration version; host bridge changes may still require a coordinated rollout.

Shared release record

Record the app version and manifest digest, source commit, selected UI profile, host version, SDK/checker version, service versions, relevant authorization model/policy revision, and approved permission changes. Do not store credentials or raw JWTs in that record.

11. Milestone phases and completion gates

The five-milestone sequence remains the delivery roadmap. PR #2852 now contains the Phase 0 native foundation and Phase 1 shared manifest/installation implementation. Phases 2–5 are follow-on proposals.

Phase	Scope	Current status	Dependencies	Completion gate
0 — Native UI foundation	Build-time native package contract 2.0 and host integration (explicit legacy 1.1 compatibility)	Implemented in open PR #2852; unmerged	Existing CAIPE shell and app gateway	Reviewed native foundation with accurate security/lifecycle documentation and focused checks
1 — Shared application manifest	Common AgenticAppManifest 2.0, installation, capability references, permission requests, rendering profiles	Implemented in open PR #2852; unmerged	Phase 0 and existing hosted-app model	Native and iframe examples validate against one schema and installation model
2 — CAS app authorization	App discovery/use/manage model; approved operation envelopes; remote identity adapters	Proposed; CAS foundation exists	Phase 1 and existing CAS resource/adapters	Denied/direct/bypassed requests stop; grant/revoke and audit semantics proved
3 — Shared host SDK	Common behavior with native and iframe adapters; lifecycle/routing/errors/context	Proposed; native hooks exist in Phase 0	Phases 1–2	Deep links, history, breadcrumbs, theme, lifecycle, and denied operations behave correctly in both profiles
4 — Agent capability integration	Existing MCP/A2A/workflow registries consumed through platform APIs	Proposed; protocol/runtime integrations already exist	Phases 1–2; Phase 3 for UI consumers	An app provides a capability used by Agent Builder and consumes a platform agent through supported APIs
5 — Validation and release	Compatibility, loading budgets, security tests, controlled benchmarks, rollback and operations	Proposed; some Phase 0 tests/build checks exist	Acceptance evidence from preceding phases	Publish supported contracts, evidence, compatibility matrix, and operational release/rollback instructions

Security, compatibility, and performance tests should begin in each phase. Phase 5 consolidates release evidence; it is not the first time authorization is tested.

Phases 0–1 — What PR #2852 implements

The implementation snapshot is 6aabb9a9cf4c3171fcf1d39a0bbf05bb1f299f02. The code and documents in the PR are the implementation reference; this roadmap does not expand its scope retroactively.

Area	Included in PR #2852	Remaining scope
Shared application SDK	AgenticAppManifest 2.0, native component interface 2.0, App SDK/checker 2.0.0-rc.1, common manifest CLI	Broader published compatibility/conformance policy
Artifact validation	Exact/integrity-recorded installations; shared app version/package matching; legacy input adapters	Broader provenance and full dependency/lifecycle review
Route ownership	Reserved/overlap checks; canonical route rewrite to the native host	Shared route references and parity across profiles
Host integration	Route state, navigate, optional host Link, breadcrumbs, shared shell	Transport-neutral host SDK and iframe bridge
App surfaces	Optional navigation, native home slot, UI-only/service-only records, hidden-app lookup in both modes	Shared iframe/native lifecycle and additional slots
Installation and access	Shared installed/enabled/profile/visibility model; authenticated direct lookup for hidden apps; role checks	Generic CAS app discovery/use/manage permissions
API integration	Declared mounts using the existing app gateway; auth-mode agreement	Generic granted capability broker and broader CAS coverage
Identity modes	App-scoped token and explicit user-access-token forwarding	General app-audience exchange and trusted delegation design
Assistant	Optional configured-agent reference and host-owned floating panel	Generic capability advertising, discovery, and agent composition APIs
Performance	Host route-ready mark; artifact entry and compiled-JS budgets	Host-generated per-app lazy loading and emitted/transitive initial-payload budgets
Styling	Package stylesheet integration and basic document-selector checks	Stronger CSS isolation and cross-app collision tests
Testing/docs	Focused contract/host/gateway tests and native extension documentation	Full renderer-parity, lifecycle, failure, revocation, and release evidence

PR #2852 has a 64 KiB entry-module and 2 MiB compiled package JavaScript checker budget. Those are uncompressed artifact checks; they are not measured network latency or proof of the total initial payload.

The generator currently uses eager static package imports and global stylesheet inclusion. A small entry can import expensive dependencies. The future loading gate must inspect emitted bundles and test whether unopened apps affect shell loading.

PR #2852 implements Phases 0–1. Phase 1 retains the name AgenticAppManifest and introduces API version 2.0. The native component interface is now 2.0; explicit legacy native component contract 1.1 remains supported without relabeling legacy modules. The implementation includes:

• One publisher declaration with native/iframe profiles, named routes, service policy, capability references, and requested-permission metadata.
• Deployment-owned profile selection, private runtime/resource bindings, and optional expected app version.
• Normalization of hosted v1.0 and native v1.1 inputs, with legacy policy joins restricted to genuinely legacy native packages.
• A generated common registry; a runtime file cannot replace a new pinned native declaration or enable absent native code.
• Public catalog visibility separated from authenticated direct lookup and API authorization; hidden navigation remains filtered.
• UI-only native and service-only applications; explicit selection for new multi-profile installations.
• Reference manifests, publisher checking, migration/denial tests, and implementation documentation.

Phase 1 limits: provided/consumed capabilities and permission requests are declarations. They do not create grants, provision agents/tools, or change token scopes. Unsupported required capabilities fail validation. The current iframe profile still launches under /apps/<id>; profile selection does not implement the future cross-document route/lifecycle SDK.

Still outside this PR:

• CAS application resource/actions and generic permission grants.
• Trusted cross-service delegation and general audience token exchange.
• Shared iframe/native lifecycle and messaging SDK.
• Generic Agent Builder capability discovery, registration, and composition.
• Android-like browser package isolation.
• Host-generated per-app lazy loading, full initial-payload budgets, and controlled performance certification.

Validation: full UI evidence is from behavior snapshot 6bfd938. The terminology-only update 6aabb9a reran 26 contract/package tests, 16 native UI tests, lint, and the production build successfully. Prior full-suite evidence: 26 contract/generator/packed-SDK tests; 719 UI Jest suites and 8,454 tests passed (12 tests and one suite skipped); lint and optimized UI build passed. The SDK package dry run includes the common types/validator and both checker CLIs. An existing asynchronous audit-log warning remains. These checks do not certify authenticated deployment behavior or production performance.

The implementation reference is the shared manifest documentation. The native foundation retains its existing interfaces and limitations.

Phase 1 — Shared application manifest

Deliverables

• Versioned schema and documented identity/installation semantics.
• Native, iframe, UI-only, and service-only profiles.
• Provided/consumed capability references.
• Permission-request vocabulary separate from grants.
• Optional navigation, hidden/internal applications, route references, and owned slots.
• Migration adapters from the existing hosted and native manifests.
• Permission/compatibility diff review for app upgrades.

Exit criteria

• Both rendering examples use one app identity and installation record.
• Invalid profiles, conflicting claims, and unsupported required capabilities are rejected.
• Hidden apps retain authorized deep links without appearing in public navigation.
• Changing rendering profile preserves app service/agent references.
• Existing installations have a documented migration and rollback path.

Suggested ownership: platform contract and UI integration maintainers, with authorization review.

Phase 2 — CAS app authorization

Deliverables

• Approved application resource/action model.
• CAS-backed discovery, launch/use, and installation management checks.
• Installation operation-envelope checks and service credential/identity bindings.
• Approved remote adapters; explicit delegation rules where needed.
• CAS-based grant/reconcile operations and decision/audit correlation.
• Cache, revocation, disablement, and dependency-failure semantics.

Exit criteria

• User access and service-account access are tested separately.
• A client cannot impersonate another subject through body fields or headers.
• Denied launch, direct API calls, and direct agent/tool calls stop at their enforcement boundary.
• Capability discovery and execution remain consistent while execution rechecks current access.
• Grant/revoke behavior accounts for inherited/team access.
• CAS failures stop protected operations; no permissive fallback.
• New application/action pairs are actually registered and tested rather than accepted as arbitrary strings.

Suggested ownership: authorization and gateway maintainers, with app-service owners.

Phase 3 — Shared host SDK

Deliverables

• Versioned behavior contract and initialization negotiation.
• Native bindings and iframe messaging bindings.
• Canonical route synchronization, breadcrumb behavior, theme/context updates.
• Ready/error/teardown events and bounded capability requests.
• Native error/loading boundaries and generated lazy loaders.
• Explicit Next.js rendering policy and iframe origin/sandbox policy.

Exit criteria

• Direct links, refresh, back/forward, and query changes work in both profiles.
• Host and child route state cannot be overwritten by stale messages.
• Navigation preserves intended state and updates route-specific data.
• Frame reloads and native component failures produce bounded, recoverable states.
• Loading an app does not load unrelated app payloads without an explicit prefetch policy.
• Tokens/secrets are absent from bridge/context payloads.
• Each trust profile is tested against its stated browser boundary.

Suggested ownership: UI host/SDK maintainers and app publishers.

Phase 4 — Agent capability integration

Deliverables

• Versioned platform clients/adapters for existing MCP, A2A, and workflow capabilities.
• Authorized capability discovery and registry references in app manifests.
• Agent Builder composition based on those references.
• Downstream app invocation and status/streaming interfaces independent of builder UI internals.
• Compatibility, dependency revision, and optional-capability handling.
• Credential-use, approval, cancellation, and execution identity requirements for relevant operations.

Exit criteria

• An app-provided tool/capability is selectable and usable in Agent Builder.
• Both a native and iframe app consume a platform agent through the same service contract.
• A headless workflow uses the same authorized runtime path.
• Unavailable optional capabilities degrade predictably.
• Denied tools/resources cannot be accessed through an otherwise authorized agent.
• Provider metadata and client context cannot grant permissions or override execution identity.

Suggested ownership: Agent Builder/runtime, MCP/A2A, workflow, and authorization maintainers.

Phase 5 — Validation, compatibility, and release

Deliverables

• Public publisher conformance suite and reference applications.
• Host/SDK/API compatibility matrix and migration policy.
• Emitted bundle budgets, CSS isolation, lazy-loading and dependency checks.
• Security evidence for identity, permissions, direct ingress, revocation, and failures.
• Controlled native/iframe/built-in measurements where comparable.
• Reproducible image assembly, rollout, rollback, and incident diagnostics.

Exit criteria

• Benchmark the same app/service/data/auth context across compared profiles.
• Separate cold and warm loads, shell-ready, UI-ready, data-ready, and navigation timing.
• Report sample count and appropriate median/tail latency; do not infer platform-wide equivalence from a single deployment.
• Record initial transferred assets, execution/hydration work, and backend/authorization latency separately.
• Verify supported updates and rollback of a pinned host/app/service combination.
• Define measured revocation and authorization availability behavior.
• Publish the acceptance evidence and remaining limitations.

Suggested ownership: platform release, UI performance, authorization, runtime, and app publisher maintainers.

12. Milestone and issue organization

The phases above are proposed GitHub milestone definitions in this discussion. This update does not create milestone or issue objects.

Suggested milestone names:

• App Contract 0 — Native UI Foundation — PR feat(ui): add shared AgenticAppManifest and native UI contract #2852.
• App Contract 1 — Shared Manifest and Installation — included in PR feat(ui): add shared AgenticAppManifest and native UI contract #2852.
• App Contract 2 — CAS Authorization.
• App Contract 3 — Host SDK and Rendering Adapters.
• App Contract 4 — Agent Capability Integration.
• App Contract 5 — Conformance and Release.

For each implementation issue, record:

• Owning boundary and expected behavior.
• Native/iframe/service-only applicability.
• Current behavior and concrete acceptance examples.
• Authorization principal/action/resource and enforcement location.
• Compatibility, migration, and rollback impact.
• Required evidence and phase dependencies.

Keep changes reviewable: schema/migration, authorization model/adapter, host SDK/adapters, protocol integration, and release evidence should be separate work items/PRs where feasible. UI, runtime, and auth work can progress in parallel only when their prerequisite contracts are agreed.

PR #2852 should be reviewed as the native foundation plus shared AgenticAppManifest Phase 1 migration. CAS grants, generalized capability execution/composition, and a shared iframe lifecycle SDK should not be represented as already delivered.

13. Decisions requested

1. Adopt a shared application identity/installation model with separate native and iframe profiles?
2. Which permission vocabulary and application resource/actions should Phase 2 standardize first?
3. What authenticated remote/delegation adapter is required for service/gateway CAS checks?
4. Which existing MCP/A2A/workflow integration provides the first end-to-end capability example?
5. Which trust profiles support native prerendering, same-origin hosted apps, and isolated iframe apps?
6. What compatibility, revocation, payload, and release evidence is required before broader adoption?

References

CAIPE implementation and authorization

• Native foundation PR #2852.
• Native 2.0 implementation and explicit legacy compatibility at the reviewed snapshot.
• CAS / Access API foundation and current limitations.
• CAS Access API request and failure semantics.
• CAS coverage and migration gaps.
• External Apps discussion.
• Weather native package example PR.

Established architecture and protocol foundations

• Backstage typed Utility APIs and permission enforcement.
• Android manifest declarations and OS-enforced app sandbox.
• Next.js server/client rendering and lazy loading / prerendering controls.
• Browser iframe sandbox limitations.
• MCP tools and schemas, MCP authorization, and MCP Apps bridge.
• A2A discovery, execution, and authorization.

[juliarvalenti]

Thanks for writing this up. I think the client-only package plus an app-owned service behind the gateway is the right split, and the build-time checks in #2852 (pinned integrity, reserved paths, overlap detection, peer dependencies, auth-mode agreement) are a solid base. Some thoughts on how I'd like the plugin architecture to work more broadly.

1. Keep the boundary at "UI in the host, backend in the app"

• The package contributes React views and nothing server-side. All domain APIs, jobs, agents and MCP endpoints live in the app's own service.
• This keeps the trust question small: reviewing a client bundle is very different from admitting code into the host's server process.
• I'd make "no server entry point in v1" an explicit contract rule, not just the current shape.

2. Identity: verify the subject, never trust forwarded privilege

• The gateway forwards x-caipe-roles. Apps should be told explicitly not to derive privileges from it (or from any x-caipe-* header). They should decide access from the verified subject via CAS/OpenFGA. If roles are needed downstream, they belong in a signed claim.
• forward-user-access-token:
  • Prefer Keycloak token exchange to a token whose audience is the app, rather than forwarding the host-audience token. Otherwise every app that accepts it also holds a token the host itself accepts.
  • Check expiry, and refresh if needed, before forwarding.
  • Document the mandatory audience/issuer validation in the app.

3. Non-browser callers need a first-class story

• The gateway authenticates with the browser session. Many apps will also have machine callers: MCP clients with OAuth bearer tokens, API keys, webhooks.
• If those paths are declared as API mounts, they'll be rewritten into a cookie-only gateway and fail.
• The contract should say how this works: either declared mounts may accept a validated bearer, or machine traffic goes to the app's own ingress. Either is fine, but it should be decided, not discovered.

4. Adding vs. replacing host surfaces

• Default: an extension adds pages, slots and APIs. It doesn't replace host-owned ones.
• If replacing a host page or a host API is ever allowed, I'd make it a separate, explicitly approved capability rather than a side effect of hostPaths/mounts. The reserved list should then cover host APIs that other host features call, not just top-level pages.
• Replacing an API is riskier than replacing a page: every host feature calling that endpoint silently starts talking to the extension's implementation.

5. Data and authorization ownership

• App data lives in app-owned storage with its own credentials (a separate DB, or a restricted user).
• Host data is reached through versioned host APIs, not shared collections.
• OpenFGA writes are limited to the app's own object types and go through the authz adapter. Host relations (teams, admin surfaces, the model itself) stay host-owned.

6. Smaller contract details

• Proxy matcher: it now runs on every non-static request. It could be generated from the installed manifests so only extension paths pay for it.
• CSS scoping: this is a naming convention today. The checker could enforce a class prefix, or the contract could require CSS modules.
• Bundle hygiene: make lazy loading part of conformance, e.g. a size budget on the package entry module, since every installed extension is statically imported into the host.
• Navigation: navigate/setBreadcrumbs as props are a nice narrow surface. Since next is a required peer, it's worth stating whether packages may also use next/link directly, so publishers don't guess.

On the decisions requested

1. Yes, an opt-in trusted mode alongside iframe apps, with no runtime/marketplace installation of native JS.
2. Require compiled JS/CSS for v1. Revisit transpilePackages only with a concrete need.
3. Semver the contract separately from the CAIPE release, and publish the conformance checker as a versioned package that publishers run in CI.
4. Default to app-scoped tokens. Allow user-token forwarding only via token exchange to the app's audience, and never derive privilege from headers.
5. Before use beyond a PoC: provenance plus a pinned digest, a bundle budget, a tested rollback, and negative tests (disabled extension, denied launch, wrong audience, header spoofing).

[sriaradhyula]

PoC status update: contract 1.1

This remains a proposal. The host contract PR is still a draft, and the following describes what the current proof of concept validates, not a generally accepted platform contract.

Implemented and exercised

• The versioned SDK/checker (1.1.1 for contract 1.1) validates compiled browser assets, peer dependencies, bundle budgets, manifest claims, reserved paths, and integrity-pinned package installation. CAIPE generates static imports during the derived UI image build; there is no runtime download or hot installation.
• The host provides route state, navigation, a host Link component, breadcrumbs, and the API base path. An extension can claim a route without advertising it in the left navigation. In the TOME PoC, /projects and /tome/settings are extension-owned while CAIPE retains /admin; this caught and resolved a real route collision.
• Declared browser API mounts go through the CAIPE session-backed gateway and request policy. The default identity mode is an app-scoped token. The opt-in forward-user-access-token mode currently forwards the existing Keycloak user token server-to-server; no token is passed as a component prop. The app service remains responsible for resource-level authorization. Machine callers use the app-owned bearer/webhook ingress, not the browser-cookie gateway.

Still open before broader adoption

• App-audience token exchange is not implemented. The direct user-token mode needs an explicit audience, expiry/refresh, and threat-model decision; forwarded role headers must not grant privileges.
• A trusted native package shares the CAIPE document and same-origin privileges. A no-token-prop API is not browser isolation: review and provenance requirements remain essential.
• Negative authorization tests, rollback criteria, CSS isolation, publisher compatibility policy, and a measured performance comparison remain acceptance work. A package update still requires rebuilding and rolling out the derived CAIPE UI image.

These observations support the add-on UI plus app-owned backend boundary in the proposal while preserving the iframe mode for less-trusted apps.

[subbaksh]

My concern is the developer and operator experience when multiple plugins live in separate repositories:

• Developers: publishing a plugin release still depends on a downstream CAIPE build and rollout, plus compatibility with the host’s React/Next versions.
• Operators: must maintain compatible version combinations and build a CAIPE image for each deployment’s plugin selection.
• Upgrades and rollback: a single plugin update requires a host rollout; restoring a previous image may also revert unrelated changes.

Example: Plugins A, B, and C are maintained in separate repos. A small UI fix in A requires rebuilding CAIPE with the published packages from all three plugins, then redeploying the host, even though Plugins B, C, and CAIPE’s source haven’t changed.

So for a small fix, developers of plugins need to rely on operators to rebuild CAIPE with new plugin version, and deploy, leading to frustrations from both.

Release A → assemble A/B/C packages (different repos) → rebuild CAIPE → redeploy CAIPE

[jnapper7]

I agree. I think we should understand if the UI benefits are worth the cost here? An app does not necessarily need to be embedded in CAIPE and if it supports deep linking can interwork just fine with CAIPE from a user perspective, no? The main concern I feel is that the look and feel with undoubtedly diverge. Is that important? It could also be seen as a benefit.

[artdroz]

I agree with Shubham that separate repositories do not automatically provide independent releases. With static native imports, a small app UI change still requires rebuilding and deploying the host. Operators must manage compatible package combinations, and a host rollback may also revert unrelated app changes. Automation reduces the effort, but the coupling remains.

Hosted applications offer another option: separate deployment and rollback while retaining the surrounding shell. The tradeoff is a second browser document and coordination for navigation, theme and sizing. Native packages offer closer UI integration, but introduce host dependency constraints and broader trust in application code.

I would keep hosted and standalone applications as the default choices, with native packages available for trusted applications that demonstrate a need for tighter integration. All approaches still need clear identity, resource authorization, machine-client support and compatibility contracts.

[labagent24]

This is a well-structured proposal, and I fully agree that build-time composition is the only sustainable path for native UI integration in a complex host like CAIPE. The distinction between "trusted native" and "hosted iframe" is critical, and your architectural table clearly highlights why the former is necessary for seamless navigation and theming without sacrificing the security boundaries of the latter.

One significant challenge with the "same React tree" approach is managing state isolation and dependency conflicts across multiple trusted packages. If different app teams use slightly different versions of shared UI libraries or state management tools, you risk subtle bugs or bundle bloat. I’d recommend the contract strictly enforce a single, host-managed set of peer dependencies for all native packages, similar to how you’re handling the CSS scoping. This prevents any single app from accidentally introducing a divergent runtime environment.

Regarding point 6 about bundle hygiene, I’ve found that enforcing strict size budgets at the CI stage is non-negotiable. When we reviewed similar plugin systems, we saw performance degradation quickly once multiple large bundles were statically imported. A hard limit on the initial load payload, combined with mandatory code-splitting for route-based views, keeps the shell responsive. Also, explicitly stating whether next/link can be used directly is a great catch; it removes ambiguity for developers and prevents unexpected routing side-effects. This feels like a solid foundation for evolving the platform without compromising its core stability.

[sriaradhyula]

Example: Workflows as a modular native CAIPE feature

Proposal, not a completed migration. PR #2852 supplies the native-package/shared-manifest foundation. Packaging the existing Workflows UI and supporting manifest-based registration of built-in features require additional work.

Intended boundary

Workflows could use AgenticAppManifest without an iframe and without requiring a separate repository. Modular composition and independent deployment are different decisions.

Module	Responsibility
Workflow UI package	Editor/canvas, configuration views, run history, progress views, and feature-local UI state
AgenticAppManifest	Identity/version, native profile, owned routes, navigation intent, and capability references
CAIPE shell	Browser session, theme, shared React/Next runtime, routing, breadcrumbs, and loading/error integration
Workflow backend	Persistence, execution, cancellation/resume, credential use, agent invocation, and authorization

The package consumes documented workflow APIs rather than importing host-private server modules or accessing MongoDB directly. The backend need not move into a separate service just to modularize the UI.

Solution-level architecture

%%{init: {"htmlLabels": false, "flowchart": {"htmlLabels": false, "padding": 20}}}%%
flowchart TB
    Manifest["AgenticAppManifest<br/>native profile"] --> Build["Reviewed package<br/>and CAIPE image build"]
    Build --> Registry["Generated module<br/>registration"]
    Registry --> Shell["CAIPE shell<br/>shared React tree"]
    Shell --> UI["Workflow UI<br/>native component"]
    UI --> API["Authenticated<br/>workflow APIs"]
    API --> Authz["Workflow and agent<br/>authorization"]
    Authz --> Engine["Workflow engine"]
    Engine --> Data["Workflow persistence"]
    Engine --> Agents["Authorized agent<br/>invocation"]

Loading

The diagram describes the proposed module boundary. It does not imply that registration grants workflow/agent permissions or that PR #2852 implements a new workflow engine.

Build and runtime lifecycle

1. Extract the workflow client rendering surface and feature-local state behind a package interface.
2. Build compiled React assets; publish a native profile implementing the CAIPE App Contract's component interface 2.0 with the shared manifest API 2.0.
3. Select an exact reviewed package/artifact during the CAIPE UI build. Use the host's shared framework peer dependencies.
4. Generate registration, validate compatibility/ownership, and build the host image.
5. Render the workflow component directly in CAIPE's document using host navigation and breadcrumb integration.
6. Consume authenticated workflow APIs; backend handlers retain operation/resource checks and execution identity.
7. Roll out or roll back the pinned host/package combination.

Native packaging avoids a second document and iframe router coordination. It can approach built-in performance, but does not guarantee it: emitted bundles, lazy loading, dependencies, and data latency still need measurement. A UI package update still requires a CAIPE image rebuild and rollout.

Current implementation versus next work

At the reviewed 6bfd938 snapshot:

• The workflow client imports host-local components, stores, and types. These dependencies must be extracted or replaced with supported package interfaces.
• Workflow API handlers and the execution engine currently live in the CAIPE UI/BFF source. UI extraction does not automatically externalize that backend.
• /workflows is a reserved built-in path. An external package cannot claim it.
• /api/workflow-configs and /api/workflow-runs are reserved host APIs. A native component may consume these APIs; declaring an API mount cannot replace them.
• Capability references and permission requests remain declarations. They do not automatically publish a workflow provider to Agent Builder, create grants, or bypass workflow/agent authorization.
• The current extension contract has constrained navigation/slot choices. It is not a complete modular replacement for every existing built-in layout or sidebar integration.

See the workflow client, workflow engine, and reserved path/API rules.

Recommended proof of concept and core registration design

Immediate PoC: extract a workflow client package and register it at a non-conflicting path such as /workflow-studio. Keep existing backend APIs and authorization in place. Validate editor behavior, direct links, refresh/history, breadcrumbs, run status, denied operations, and compatibility without claiming the existing /workflows route.

Core-feature target: introduce a host-owned built-in module registration adapter using the same manifest model. Host-maintained registration may explicitly assign the existing /workflows surface and its navigation/layout. External publishers remain subject to reserved-path checks.

Do not remove /workflows from the external reservation list merely to make the example work. Replacing a built-in surface must be an explicit host decision, with one authoritative owner and no duplicate navigation or route claims.

The manifest can be common, while admission and ownership rules differ:

• Built-in modules: platform-owned registration and approved core surfaces.
• External native packages: operator-approved installation and non-conflicting extension surfaces.
• Both: shared UI composition rules and authoritative backend authorization.

This is modular architecture, not Android-style browser isolation. Workflow native code would carry the same host-browser trust assumptions as other native packages.

Roadmap fit

• Phases 0–1: existing package/manifest foundation; validate an extracted workflow UI on an unreserved PoC route.
• Separate follow-on design: built-in module registration, supported shared UI/API interfaces, route/navigation ownership, and migration. This is not an implemented field or adapter in PR feat(ui): add shared AgenticAppManifest and native UI contract #2852.
• Phases 2–4: align applicable app access and capability consumption with CAS and Agent Builder contracts, reusing existing workflow/domain authorization.
• Phase 5: consolidate compatibility, negative authorization tests, performance, rollout, and rollback evidence.

Recommendation: use Workflows to prove that one application model can describe both platform-owned native modules and separately maintained extensions. Keep the backend boundary and trust rules explicit; do not require repository or service separation solely for modular UI packaging.

[subbaksh]

App contract review: scope, complexity, and security

My understanding is that this contract/API pertains to two types of integration:

• iframe-apps: independently deployed UI/services that integrate with CAIPE's shell and supported platform APIs, allowing other teams to contribute without changing CAIPE source.
• native-package-apps: packaged UI code composed into CAIPE for deeper integration through typed host interfaces.

Assumptions behind this review

• Operators deploy and manage CAIPE on their organization's Kubernetes cluster.
• Operators explicitly approve the workloads and images admitted to that cluster, including services for iframe-apps and CAIPE images containing native-package-apps.
• Operators control deployment configuration: service addresses, credentials, network exposure, enablement, and presentation.
• Publishers provide the app implementation, technical requirements, and recommended deployment settings. Operators own the final deployment decisions.
• Deployment approval does not grant every CAIPE user access to the app or its resources. Users still have different effective permissions.
• App services must verify callers and enforce resource access, including requests that bypass the CAIPE UI.
• An app service acting as itself is distinct from acting on behalf of a user; delegation must be explicit and verified.
• Approved code can still contain vulnerabilities or become compromised. Operator approval establishes who may install an app; it does not establish browser isolation or make all internal traffic trustworthy.

The critique below evaluates each field against these assumptions: what it enables, who should own it, and whether its complexity provides an actual integration or security benefit.

Main changes requested

1. Make unused auth/policy/capability fields optional for UI-only native-package-apps; move deployment-specific presentation and access settings to operator configuration.
2. Limit the credentials given to app services and prioritize a supported app-to-CAIPE API/delegation contract for the next phases.
3. Address the existing shared signing/browser trust limits before widening the set of trusted services or publishers.
4. For the next phases, define how iframe-apps communicate with CAIPE's shell for navigation, breadcrumbs, theme, and loading/errors; extend native component APIs for deeper features such as workflow panels; and document the APIs app backends use to call CAIPE operations.
5. Add effective-configuration diagnostics and clearer policy matching guidance.

Detailed field, security, and configuration reasoning

1. Generic permission requests: high complexity, little current value

Fields: requestedPermissions.resourceType, resourceRef, actions.

The schema requires a requestedPermissions array even when the app requests no permissions. Its contents record intent without creating grants or enforcing operations. The concern is requiring unused structure and concepts, not an authorization bypass.

For example, declaring “use this agent” does not prevent a component in a native-package-app from calling the agent API directly. That API must check the user's permission independently.

An enforceable version needs all of the following:

• The principal being authorized: user, app service, or verified delegation.
• Supported resource/action pairs and resource-binding resolution.
• Who approves access and where the approved state is stored.
• The server-side enforcement point, including direct API calls.
• Revocation and failure behavior.

Recommendation: Defer this from the mandatory core until one complete operation demonstrates enforcement. Keep the manifest extensible through optional, versioned sections with defined compatibility rules. Do not require empty permission declarations today. If retained as future metadata, make that status explicit.

Worth solving? Unauthorized resource access is worth solving through existing API/resource authorization. A generic installation permission envelope is worth adding only if it provides a defined restriction beyond those checks. Browser confinement of native-package-apps cannot be delivered by this field.

2. Gateway policy: useful for hosted services, excessive as a universal requirement

Fields: auth.mode, access.tokenScopes, access.policyActions, requiredScopes.

Authentication has a concrete purpose when CAIPE proxies a request to another service: the receiving service must verify the caller. HTTP admission rules and operation scopes can also be useful there.

However, a native-package-app using only CAIPE APIs still has to declare auth.mode and empty access/API structures, even when no service integration uses them. Selecting a token transport and declaring empty service policy does not enable an integration for that app shape; these fields should be optional.

Current gateway scopes are selected from the manifest's HTTP policy; they are not calculated from per-user CAS resource grants. Maintaining a manifest rule for every backend endpoint risks duplicating authorization and letting the two copies drift.

Recommendation: Make gateway/auth policy conditional on hosted-service integration. Define receiver-enforced operations and operator-approved policy. Reuse existing resource authorization for calls from native-package-apps to CAIPE APIs.

Worth solving? Verified identity between services is necessary. Reusing CAIPE API resource checks avoids maintaining overlapping access rules for calls from native-package-apps.

forward-user-access-token gives the receiving service the user's existing credential unchanged. An app service holding it can reuse it at other endpoints that accept it, subject to their authorization. That broadens the impact of a compromised service. Prefer a credential limited to the intended app integration.

Delegation recommendation: Define short-lived, narrowly accepted credentials for app-to-CAIPE operations that identify the user and acting service. Reuse the repository's token-exchange experience, but specify the audience, actor validation, supported API surface, and failure behavior. Do not silently fall back to the original broad token if narrowing fails. A dedicated API must enforce the user's resource permission and, if introduced, an operator-approved app operation envelope. This could give future permission requests an enforcement path; it is not implemented today.

Such delegation limits a compromised service's authority. It does not contain native-package-apps or same-origin iframe-apps that can obtain the original user credential through the host browser context.

3. Rendering and service configuration: keep the distinction, simplify the schema

Fields: ui.profiles, runtime.kind, runtime.mountPath, api.mounts.

ui.profiles answers how the UI renders. runtime describes a hosted service/proxy adapter. Both concepts are useful, but the current naming makes them look like competing ways to select a runtime.

The concrete combinations are:

Integration	Configuration needed
native-package-app using CAIPE APIs	Package artifact and host component interface
native-package-app with its own backend	Package artifact plus optional hosted-service integration
iframe-app	Hosted UI/service integration

Only one runtime.kind currently exists, and runtime.mountPath must be /apps/<id>. These provide little choice while requiring repeated configuration. API aliases add rewrite/collision work; many apps can use the canonical app prefix instead.

Recommendation: Keep renderer-specific adapters, clearly name hosted-service configuration, derive canonical paths, and use aliases only where the canonical app prefix is insufficient. Publish the actual support matrix; a shared schema does not currently provide identical renderer capabilities.

4. Operator decisions should not be publisher requirements

Fields: surfaces.showInHub, navOrder, homeEligible, ui.navigation.placement, access.requiredRoles, runtime.maxRequestBodyBytes, concrete ui.assistant.agentId.

These depend on the deployment: which other apps exist, where operators want them, local role names, ingress limits, and installed agents. Keeping these settings in the publisher declaration, sometimes alongside operator overrides, complicates configuration ownership and precedence.

Publishers can recommend placement, role mappings, limits, and resource setup in their READMEs. These recommendations help operators configure the app; they should not become mandatory publisher-manifest policy.

The individual fields are inexpensive. Their combined cost is precedence rules, duplicated configuration, and deployment-specific packages.

Recommendation: Developers declare entry points, supported contributions, and technical compatibility requirements. Publishers document recommended deployment settings in their READMEs. Operators own the final placement/order, role mappings, limits, and resource bindings. Publisher labels/icons can remain optional presentation metadata.

Worth solving? Placement and access mapping are necessary. Making the publisher control deployment decisions is unnecessary complexity.

5. Contracts to prioritize in the next phases

Fields: provides.mcp, provides.agents, provides.workflows, consumes.platformApis.

These references should remain optional until the corresponding registration, resolution, and invocation contracts are ready. Requiring empty declarations adds configuration without enabling an integration.

The more immediate requirement is a supported app-pod-to-CAIPE API. The current app gateway carries CAIPE-to-app traffic; it does not define the reverse integration. The five recognized host capability names are not a complete HTTP API specification.

Recommendation: Start with concrete versioned operations, accepted credentials, request/response/errors, and user/service identity rules. Make capability sections optional and add references as their resolution/invocation behavior ships.

iframe-apps need a documented way to communicate with CAIPE's shell: request navigation, update breadcrumbs, receive theme changes, preserve deep links, and report loading/errors. That communication interface is the host bridge. Define it together with the APIs app backends use to call CAIPE. Decide the supported origin/trust model early, because it affects this communication; a broader less-trusted/opaque-origin profile can remain separate follow-on work.

For workflow integration in native-package-apps, use typed code APIs for panels, editors, callbacks, and subscriptions. Keep provider references in declarations and live workflow objects behind authenticated APIs.

The next phases should complete or extend these explicit contracts:

Contract	Details to define or extend	Priority
App-to-CAIPE API	Supported app operations, versioned inputs/outputs, errors, discovery, and status/streaming/cancellation where relevant	Required for app pods interacting with CAIPE
App-to-CAIPE identity/delegation	App acting as itself versus for a user; accepted issuer/audience/actor; token issuance/validation, expiry, and fail-closed exchange behavior	Required for authenticated platform calls
Iframe-app host bridge	Handshake/version negotiation, navigation, theme, breadcrumbs, deep links, lifecycle/errors, message validation, and session-change cleanup under the chosen origin model	Required for consistent iframe-app integration
Native-package-app feature SDK	Typed contribution interfaces for deeper features such as workflow panels/editors, supported host services, cleanup, and compatibility	Define as each deep integration is introduced
Hosted-service identity and trust	Key separation/rotation, receiver trust, credential/header authority, direct-ingress verification, and mutation protection	Complete before widening the trust boundary
Effective configuration and diagnostics	Authoritative setting ownership, precedence, effective configuration, stage-specific failures, correlation, and deployment/troubleshooting examples	Required to keep configuration/debugging manageable
App authorization / approved operation envelope	Approved resource/action model, principal and resource binding, approval/grants, server enforcement, revocation, and unavailable behavior	Optional follow-on; define before making generic permission requests mandatory

Worth solving? Stable external APIs and SDKs for native-package-apps directly satisfy the requirements. An abstract capability catalog ahead of those interfaces is lower priority.

6. Auth should target realistic threats, with concrete controls

The relevant threats are unauthorized resource access, compromised dependencies, forged identity, and direct calls from reachable pods. Operator-approved deployment does not eliminate these threats.

Threat	Assessment	Protection worth implementing
User accesses another user's resource	Real	Verified identity and resource checks at every protected API/service
Caller forges identity or bypasses the proxy	Real when the service is reachable	Credential validation on direct ingress; network restrictions as an additional control
Compromised app forges tokens for other apps	Concrete shared-key risk	Separate signing trust between apps
Compromised native-package-apps or same-origin iframe-apps act through the user's session or steal its exposed bearer token	Plausible	Explicit browser trust, review of browser token exposure, and actual origin isolation for iframe-apps where containment is required
Forged cookie-authenticated mutation	Deployment-dependent	Explicit CSRF/origin policy and negative tests

These controls need particular attention:

• Signing keys: the current hosted-service integration documentation distributes the same HS256 secret to the BFF and app verifiers. A compromised holder can mint tokens for other users/apps. Prefer host-only asymmetric signing/public verification or an approved identity-provider token contract; per-app HMAC keys still create distribution/rotation work. Audience checking alone cannot contain a holder of the shared signing key. This forgery targets other app verifiers; it is not evidence that the BFF accepts these app JWTs as login credentials.
• Secret separation: provide dedicated app credential references and deployment examples. Do not reuse a combined BFF Secret containing session, identity-provider, or database credentials for app pods. Pod-creation privileges can also expose same-namespace Secrets unless admission controls restrict workload configuration; document that administrative boundary.
• Unsigned identity hints: the gateway forwards x-caipe-user and x-caipe-roles alongside the bearer token. Remove unnecessary identity hints or define them as non-authoritative. Receivers must derive identity/privilege from a verified credential. NetworkPolicy complements that check; it does not replace it.
• Browser token exposure: the session callback exposes accessToken to first-party browser code. A compromised native-package-app or same-origin iframe-app can potentially exfiltrate it and use it beyond the browser until expiry. Narrow service delegation alone does not fix this browser exposure.
• Browser mutations: the inspected gateway/session/rewrite path has no explicit local CSRF/origin check. This is a source observation, not proof of a deployed exploit. SameSite=Lax mitigates ordinary cross-site POSTs; residual scenarios include same-site sibling origins and state-changing GETs. Specify and test the mutation boundary.

Prioritize controls against these concrete threats over mandatory permission metadata with no enforcement path.

7. Refactor responsibilities; reuse CAS for authorization

The useful refactor is to give each decision one owner.

Concern / fields	Recommended owner	Reason
User/service identity validation; auth.mode and token issuance	Authentication/gateway adapter, configured by operator	Establishes who is calling and what credential the receiver accepts; CAS evaluates an already verified principal
User access to agents, workflows, documents, and other protected resources	Existing CAS/domain authorization paths	Reuse authoritative resource decisions instead of creating extension-specific permission checks
App discover/use/manage permissions	CAS, after an approved application resource/action model is added	A resource authorization decision should have the same principal, audit, grant, and revoke semantics as other platform resources
Deployment role mapping; access.requiredRoles	Operator configuration; migrate coarse launch decisions to CAS where justified	Roles are local to the deployment; the publisher should not create a competing access model
Manifest permission requests	Optional publisher declaration; approved authorization state through CAS adapters	A request is not a grant. Define approval, binding, and enforcement before integrating it
Method/path rules, upstream destination, body limits	Gateway and operator installation	These govern allowed proxy traffic and operational limits, not generic resource relationships
tokenScopes and requiredScopes	Service operation contract/gateway token adapter	Scope names need receiver semantics; any resource-based decision behind issuance should reuse authorization rather than static publisher claims
Visibility, ordering, selected renderer, private bindings	Operator installation	Deployment choices; visibility remains separate from discover/use authorization
Routes, slots, workflow panels, callbacks for native-package-apps	SDK/host registration for native-package-apps	Typed client integration, not CAS permission policy
Schema compatibility, package integrity, route collisions	Publisher checker/build registry	Installation correctness, not caller authorization

Enforcement remains in the API/service. CAS answers whether a verified principal may perform an action on a resource; the serving component stops the operation when denied. CAS does not sandbox JavaScript from native-package-apps, perform proxy routing, or replace token verification.

For app services calling CAS, define a supported authenticated adapter first. The existing Access API evaluates its authenticated caller. A service token plus a user ID in the body does not establish user delegation, and a gateway app-audience token is not automatically a valid CAS credential.

Worth refactoring? Yes: consolidate resource authorization through existing CAS/domain authorization paths and give authentication, routing, deployment configuration, and UI integration clear owners.

App launch permissions, generic permission envelopes, and remote delegation remain design work; they should not be represented as capabilities CAS already supplies for this app contract.

8. Configuration and debugging burden

The concern is how many settings must agree and how much knowledge is needed to diagnose a failure. Focus diagnostics on effective configuration and the component responsible for a failed request.

Stakeholder / integration	Configuration burden	Debugging burden
Operator / iframe-apps	Match app/profile IDs, service origin, base-path handling, auth mode, signing material, role mapping, HTTP policy, visibility, and ingress limits	Trace failures across browser, BFF, Kubernetes service, token verification, and app resource authorization
Publisher / iframe-apps	Implement the gateway/base-path contract, token validation, operation-scope semantics, domain authorization, and supported CAIPE API clients	Distinguish host rewrite problems from broken assets/API URLs, invalid credentials, missing scopes, and resource denial
Operator / native-package-apps	Match compiled package/version with the installation and selected profile; configure bindings, roles, and presentation; hosted-service settings apply only when used	Distinguish missing compiled code, disabled/hidden installation, contract mismatch, route conflict, and actual API denial
Publisher / native-package-apps	Align package exports, manifest, component contract, framework peers, routes, styles, and optional service policy	Reproduce failures in the host React/runtime environment and isolate package behavior from host routing, styling, and API failures

Where the current contract adds avoidable work:

• Two places to explain access: publisher requiredRoles and operator overrides require precedence knowledge. Operators should configure the deployment's effective role mapping once.
• Several places to explain identity: auth mode, issuer/audience/key configuration, declared scopes, gateway actions, and receiver checks must agree. Keep this only for hosted-service integrations that need it.
• Two places to explain placement: showInHub and operator visible can both hide an app. Final placement should have one operator-owned configuration.
• Several paths to reconcile: declared routes, API aliases, the public app prefix, and upstream mount-path handling create potential URL mismatches. Derive canonical paths and use aliases only when the canonical prefix is insufficient.
• Policy matching changes across the method: adding one method/path rule disables the broad proxy:METHOD fallback for every other path using that method. For example, adding GET /reports can cause previously permitted assets to return action_not_declared. Document this intentional fail-closed behavior and validate the complete HTML/asset/API route set. Fine-grained GET policies are possible, but current exact segment matching makes coverage harder.
• Optional capability typos: unknown required: false platform API IDs currently pass as future metadata. Preserve forward compatibility, but warn about unknown references so misspellings are not silently treated as valid integrations.
• Declarations that look operational but are not: changing requestedPermissions cannot fix a resource denial today; declaring provides does not provision a missing agent; health metadata does not imply active launch admission. Inert metadata increases the diagnostic search space.
• Unnecessary sections: a native-package-app using only CAIPE APIs should not require operators or publishers to maintain empty backend/auth/policy structures.

For example, “the app does not work” can mean very different things:

Symptom	Likely layer to investigate
App missing from hub	Installation flags, operator visibility, publisher showInHub, or no UI profile
App entry denied	Session and effective user role mapping
Gateway returns policy_denied	HTTP method/path declaration and effective allow/deny rule
Service rejects the forwarded request	Token signature/issuer/audience/expiry or receiver scope checks
Service denies a specific resource	Verified principal and domain/resource authorization
UI loads but assets/API calls fail	Public/upstream base paths, aliases, and app URL construction

Use consistent failure-stage labels through the gateway, receiving service, and platform APIs so operators know which configuration or permission decision to inspect.

Recommendation: Treat diagnostics as part of the integration contract:

• Provide minimal reference configuration for iframe-apps, UI-only native-package-apps, and native-package-apps with a service.
• Provide an operator-only view of effective configuration and its sources: selected profile, installation flags, role mapping source, resolved routes, service binding, and credential readiness, with secrets redacted.
• Use consistent error codes naming the failing stage and owning component; propagate correlation IDs across services without logging credentials.
• Publishers document configuration recommendations and troubleshooting in READMEs. Operators retain control of the actual configuration.
• Reuse existing authorization paths and derive defaults. Do not make operators debug multiple independent policy systems for one request.

Worth the burden? Verified identity, correct routing, and resource checks are necessary. Duplicate settings, unused mandatory sections, and declarations with no runtime effect are avoidable complexity. The proposal needs a small configuration surface and a clear failure path, not just schema validation.

9. Proposed minimum boundary

Keep: identity/version, compatibility, renderer selection, route/slot ownership, artifact validation, operator installation, and private service/resource bindings.

Simplify or move: canonical paths, duplicate version/configuration entries, presentation, deployment role mappings, and operator limits.

Conditional: hosted gateway/auth policy, API aliases, provider references, and health metadata with a defined purpose beyond Kubernetes probes.

Defer: mandatory generic permission requests until an end-to-end enforcement design exists. Keep the manifest extensible so an optional permission section can be introduced through a versioned schema change with documented compatibility behavior.

Prioritize the app-to-CAIPE API contract, signing-key separation, direct/resource authorization tests, browser trust/mutation decisions, and typed SDK APIs for the first deep feature in native-package-apps. Reuse CAS for resource decisions through approved adapters; retain transport enforcement in the gateway and domain APIs.

Implementation references

• Manifest schema and validation
• Shared manifest behavior and limits
• Hosted-service identity and shared-key trust
• Gateway enforcement
• Existing Access API contract
• Publisher checks and native host build requirements
• Gateway policy fallback and exact segment matching
• Browser session access-token exposure
• Bearer-token acceptance
• Existing token-exchange implementation
• Kubernetes workload-creation and Secret access
• Reviewed PR
• Native component contract and host integration
• Installation validation and migration

[sriaradhyula]

App Contract delivery backlog — October 14, 2026

The review in this comment is now tracked as implementation work under App Contract epic #2928.

Implemented foundation versus remaining work

• PR feat(ui): add shared AgenticAppManifest and native UI contract #2852 merged on October 13. It supplies the shared manifest/native-integration foundation discussed in Phases 0–1. The earlier discussion header saying that PR is open is superseded by this status update.
• It does not complete generic CAS app grants, app-to-platform delegation, the shared iframe lifecycle bridge, deep feature contributions, or the release-conformance phase.
• The issues below are proposed implementation and acceptance work, not evidence of completed capabilities.
• All 14 are formal sub-issues of Epic: Agentic App Manifest — Native and iFrame Apps v2 #2928 and use the existing platform 2.0.0 milestone. That milestone is distinct from the manifest/component contract version 2.0.

Work packages

Stage	Work package	Issue
Phase 1 follow-up	Manifest defaults and publisher/operator ownership	#2943
Phase 2 — identity/security	Hosted-service signing/verification trust	#2942
Phase 2 — identity/security	App credentials and storage boundaries	#2941
Phase 2 — browser security	Browser trust and token exposure	#2944
Phase 2 — browser security	Cookie-authenticated mutation controls	#2946
Phase 2 — platform integration	Versioned app-to-CAIPE operations	#2945
Phase 2 — platform integration	App integration with approved CAS delegation	#2949
Phase 3 — shared host SDK	Iframe bridge and lifecycle	#2948
Phase 3 — shared host SDK	Typed native feature SDK and lifecycle	#2947
Phase 4 — agent capability integration	Workflow integration with Agent Builder	#2951
Cross-cutting — diagnostics	Effective configuration and failure diagnostics	#2952
Phase 2 follow-on — authorization design	Optional, enforceable application operation envelope	#2950
Cross-cutting — authorization lifecycle	Composed OpenFGA model ownership and upgrade lifecycle	#2953
Phase 5 — release conformance	Multi-app compatibility, performance and rollback evidence	#2954

Delivery order and dependencies

1. Start manifest ownership/defaults (refactor(app-contract): simplify optional declarations and configuration ownership #2943) and the identity/browser/security decisions (feat(app-contract): separate hosted-service token signing and verification trust #2942, feat(app-contract): define least-privilege app credentials and storage boundaries #2941, chore(app-contract): define browser trust profiles and access-token exposure policy #2944, fix(app-contract): enforce and test cookie-authenticated mutation boundaries #2946). Build diagnostic evidence alongside each slice, not only at the end (feat(app-contract): expose effective installation configuration and failure stages #2952).
2. Prove one versioned app-to-CAIPE operation (feat(app-contract): publish versioned app-to-CAIPE service APIs #2945) and its authenticated/delegated identity (feat(app-contract): integrate app callers with the approved CAS delegation adapter #2949). Reuse chore(auth): investigate OBO impersonation and delegation scope #2890 and feat(authz): bind delegated authorization to trusted execution context #2891 under Epic: [CAS] CAIPE Authorization Service Migration #2487; these new app issues do not duplicate the core CAS/token-exchange program or assume a new CAS service.
3. Implement the supported iframe bridge (feat(app-sdk): implement a versioned iframe host bridge and lifecycle #2948) and typed native feature interfaces (feat(app-sdk): define typed native feature contributions and lifecycle #2947) against explicit trust profiles.
4. Validate one workflow capability through Agent Builder (feat(agent-builder): validate workflow capabilities through the app contract #2951), coordinated with Epic: Agent Builder v2 #2933 and existing workflow/agent protocols. Registration, binding, invocation and permission are distinct.
5. Decide and prove the optional application operation envelope (chore(app-contract): prove an optional CAS-backed application operation envelope #2950) after the operation/delegation contracts exist. Manifest requests are not grants and must not become mandatory before there is an enforcement path.
6. Keep model composition/upgrade ownership explicit (feat(charts): govern composed OpenFGA models across app installs and upgrades #2953); feat(charts): support deployment-owned OpenFGA models #2940 provides the generic model artifact input, not runtime model layering or a completed lifecycle framework.
7. Complete the multi-profile acceptance gates (test(app-contract): establish multi-app conformance performance and rollback gates #2954) before claiming broader readiness. Test direct ingress, denied access, session changes, compatibility, cold/warm navigation and rollback of pinned app/host/model combinations.

Ownership and acceptance rules

• Each issue names a suggested owning component, applicable profiles, dependencies, acceptance criteria, boundaries and migration/rollback. Maintainer assignments and delivery dates are not assumed.
• Publisher declarations describe technical requirements and contributions; operators own concrete installation choices and bindings. Neither declarations nor installation visibility grant resource access.
• Services verify credentials and enforce CAS/domain decisions. CAS remains a module inside the BFF, not a sandbox, routing engine or new microservice.
• Keep private app implementation, credentials and environment configuration out of the public framework and reference fixtures.
• Existing CAS issues retain their current parents/milestones. Cross-links coordinate work without moving or duplicating their scope.
• Proof-of-concept success, a green build and a merged foundation PR are not substitutes for the acceptance evidence specified by each phase.

[Joaescam]

I agree with @artdroz and @jnapper7. Use iframe as the default and native for apps that show a need for it.

From looking through the code I found that:

• Iframe apps can send the host extra context like route, title, summary, resource refs and suggested prompts. A native approach, as in PR #2852, would need to have similar context transfer.

• Our current iframe apps use plain HTML and JS front ends instead of React. That's fine for iframe, since the app can use any framework, but converting one to native means a rewrite because native has to be a React component under the contract in feat(ui): add shared AgenticAppManifest and native UI contract #2852.

• @subbaksh's point about rebuilding for every small update is important to note. Agentic SDLC would be a good candidate to move to iframe.

• Going forward, a shared host SDK and a clean app-owned API boundary would make conversion between iframe and native easier, since the UI code wouldn't be tied to one profile.

I'm in favor of having both. Iframe works for bigger apps that can grow into something standalone. Native works for small, mostly visual, read-only dashboards.