secureflows-js

Minimal browser JS/TS SDK for secureFlows hosted session login and Session API reads.

Install

npm install secureflows-js

Quick start (stable hosted login)

Copy templates/web-app-secureflows/ from the secureFlows repo.

import { SecureFlows } from "secureflows-js";

const sf = new SecureFlows({
  origin: "https://www.secure-flows.com",
  appId: "acme-web",
  workspace: "my-workspace",
});

const APP_ORIGIN = "https://your-app-host";
const redirectUri = `${APP_ORIGIN}/callback`;

// App load: restore session payload and signed-in email for the header.
export async function restoreSession() {
  const token = sf.getToken();
  if (!token) return null;
  const [session, identity] = await Promise.all([
    sf.fetchSession(token),
    sf.fetchSessionIdentity(token),
  ]);
  return { session, email: identity.email };
}

// Sign-in CTA: start hosted login from one explicit user action.
export async function signIn() {
  await sf.login({ redirectUri });
}

// /callback route: complete the return and go home.
export async function completeCallback() {
  await sf.ensureSession({ redirectUri });
  window.location.replace("/");
}

Register https://YOUR_HOST/callback in the workspace dashboard. Requires secureflows-js ≥ 0.1.13.

After sign-in, call sf.fetchSessionIdentity(token) to show the user's email in the app header (next to Sign out).

sf.login() and logoutWithRedirect() use the SDK's navigation helper internally. In preview iframes the SDK tries same-frame navigation first (proven on Base44), then top-level breakout if navigation does not start. If all attempts are blocked, sf.login() rejects with HostedLoginNavigationError instead of hanging.

fetchSession() throws SecureFlowsHttpError (with .status) on non-2xx responses. When login() reuses a stored token and gets 401/410, it clears the dead token and falls through to hosted login instead of leaving the caller stuck retrying the same token.

App code should call those methods directly instead of manually using navigateForHostedLogin().

Token storage (multiple apps, same origin)

The SDK stores tokens in sessionStorage under sf.token.v2.<workspace>.<appId> (and login state under sf.state.v2.<workspace>.<appId>). This prevents two secureFlows-integrated apps on the same host (e.g. localhost or a shared preview origin) from overwriting each other's session tokens — even when the same appId exists in multiple workspaces.

Hand-rolled integrations: import sessionStorageKeys(appId, workspace) (recommended) or use the same v2 key format.

Backward compatibility:

• Legacy sf.token (pre-0.1.11) is migrated once on read when the scoped key is empty.
• Previous per-app keys (sf.token.<appId>) are migrated into v2 keys without deleting the old key (it is ambiguous across workspaces).

Integration reference

• SKILL.md
• Session API — includes GET /sessions/identity
• platform-hosted-apps.md

Development

cd secureflows-js && npm install && npm test && npm run build

License

MIT