feat(client): redeem a platform embed token at createClient

[amitbardos]

Apps embedded by a host platform arrive with a one-time token on the iframe URL, ?ott=. createClient takes it off the URL, trades it for an app-user session through the RFC 8693 token-exchange grant (POST /api/apps/{appId}/auth/embed/token), and keeps the result in memory only — the session lives and dies with the frame.

In the SDK rather than the app template so it reaches every existing app: the platform bumps sdk_min_version and the codemod pulls it in on the next boot.

What changes

• createClient strips ?ott= and exchanges it. Everything that can wait for the session does — axios, functions.fetch, fetchWithAuth, actors. Nothing is persisted, and an embedded load never adopts a stored token: whatever an earlier visitor left is not this session.
• One live getToken() replaces seven token || getAccessToken() closures (socket, agents, actors, aiGateway, functions). They captured a construction-time token or fell back to storage, so a memory-only session reached none of them. The auth module now owns the token and reports changes through onSessionChange — which is how the socket redials, and how logout drops a connection still running as the user who just left.
• base44.auth.isEmbedded() (public). In a frame, redirectToLogin() and logout() show a "session ended" notice instead of navigating: only the platform can mint the next session, and the app's own login would mint a different identity.
• getAccessToken() returns the ?ott= on an embedded load, so an app's existing if (appParams.token) gate still fires and it doesn't render signed-out while authenticated. This is the piece I'd most like a second opinion on — see the inline comment.

Compatibility

An app opened normally runs the code it ran before, storage fallback included. AgentsModuleConfig / AiGatewayModuleConfig (both @internal) take getToken; createClient is their only caller.

Testing

npm test (355 unit + type tests) and eslint pass on Node 26. New coverage: the URL strip, the frame-only report, the RFC 8693 request shape, refused / thrown / 429-retried / timed-out exchanges, and through createClient — a request issued mid-exchange carrying the exchanged bearer, nothing written to storage, a stale stored token ignored, and a normal app untouched.

Server side ships in base44-dev/apper#24167. Supersedes base44-dev/apper#24259.

🤖 Generated with Claude Code

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/sdk@0.8.48-pr.282.094dd5b

Prefer not to change any import paths? Install using npm alias so your code still imports @base44/sdk:

npm i "@base44/sdk@npm:@base44-preview/sdk@0.8.48-pr.282.094dd5b"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "@base44/sdk": "npm:@base44-preview/sdk@0.8.48-pr.282.094dd5b"
  }
}

• 📦 Preview Package: @base44-preview/sdk@0.8.48-pr.282.094dd5b
• 🔗 View this commit on GitHub

---

_{Preview published to npm registry — try new features instantly!}

[amitbardos]

Reviewer note — the one decision here I'd like a second opinion on.

This returns the ?ott= so an existing app's auth gate still fires:

// templates/apps_template/src/lib/AuthContext.jsx
if (appParams.token) { await checkUserAuth(); }

app-params.js calls getAccessToken() before createClient exists, so there is nothing else to ask at that moment. Return null and the app renders signed-out while every request it makes is authenticated.

The trade-off. It buys out a template change, and pays for it by handing app code a value that looks like a session token and isn't — createClient then has to defend against getting its own utility's output back (const token = embedOtt ? undefined : config.token). Two coupled changes in two files, and a reader of either one can't tell why.

The alternative is one line in that same file, which already imports the client:

if (appParams.token || base44.auth.isEmbedded()) {

Cleaner — but it only reaches apps the codemod can patch, not ones that just get the sdk_min_version bump.

@netanelgilad — can the codemod edit template files, or only bump the version? That decides which way this goes. Separately, worth confirming in base44-dev/apper#24167 that the OTT is rejected as a bearer everywhere except the exchange, so an app that naively sends it gets a 401 rather than a compromise.