Send flow secret via Flow-Secret header on native flow init

[Malith-19]

Purpose

The backend is moving the Flow Secret for POST /flow/execute out of the JSON request body and into a dedicated Flow-Secret request header (see thunder-id/thunderid#3795 and PR thunder-id/thunderid#3808). This updates the SDK so backend/server-side applications can present the Flow Secret via the header when they initiate a native (embedded) sign-in flow.

Previously a caller could put flowSecret inside the flow payload and it would serialize into the request body. With the header change that no longer works, and the higher-level Next.js signIn wrapper dropped any custom request config, so there was no way to convey the secret. This adds first-class support.

Approach

• Added an optional flowSecret field to EmbeddedFlowExecuteRequestConfigBase (packages/javascript/src/models/embedded-flow.ts). It is documented as being sent in the Flow-Secret header and only on a new flow initiation.
• executeEmbeddedSignInFlow now sends flowSecret in the Flow-Secret header, but only when initiating a new flow (a payload carrying applicationId + flowType). It is deliberately omitted from continuation/step-submission requests, mirroring the backend, which only gates direct initiation of authentication flows.
• ThunderIDNextClient.signIn forwards flowSecret from the request config into executeEmbeddedSignInFlow, so it is usable through the Next.js server-action path (signInAction(payload, { flowSecret })).
• Scope is the sign-in (authentication) flow, since that is the only flow the backend gates with the Flow Secret. Registration/recovery/onboarding are not gated and are left unchanged.

Server-side initiators that build the request themselves (the Express handleFlow middleware, direct executeEmbeddedSignInFlow callers) can already pass flowSecret via the config; wiring it through their own config/UX is a natural follow-up if needed.

Related Issues

• Refs Move flowSecret from request body to a request header for /flow/execute thunderid#3795

Related PRs

• Backend: Move flowSecret to a request header for /flow/execute thunderid#3808

Checklist

• Followed the contribution guidelines.
• Manual test round performed and verified. (Added unit tests and ran the package build/typecheck; no live end-to-end run)
• Documentation provided. (Add links if there are any)
• Tests provided.
  • Unit Tests
  • Integration Tests
• Breaking changes. (Fill if applicable)
  • Breaking changes section filled.
  • breaking change label added.

Security checks

• Followed secure coding standards in WSO2 Secure Coding Guidelines
• Confirmed that this PR doesn't commit any keys, passwords, tokens, usernames, or other secrets.

Summary by CodeRabbit

• New Features

  • Embedded sign-in flows can now include an optional flow secret when starting a new flow.
  • The secret is sent only on initial requests, not on continuation steps.

• Bug Fixes

  • Improved request handling so step submissions no longer include the flow secret header.

• Tests

  • Added coverage to verify the secret header is included or omitted in the correct cases.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds an optional flowSecret parameter to executeEmbeddedSignInFlow, conditionally setting an X-Flow-Secret request header only when starting a new embedded sign-in flow (not on continuations). Wires flowSecret through ThunderIDNextClient.signIn and adds corresponding tests.

Changes

Flow secret header support

Layer / File(s)	Summary
Model type and core request logic packages/javascript/src/models/embedded-flow.ts, packages/javascript/src/api/executeEmbeddedSignInFlow.ts	Adds documented optional flowSecret field to EmbeddedFlowExecuteRequestConfigBase; executeEmbeddedSignInFlow destructures flowSecret and conditionally sets X-Flow-Secret header only for new flow starts.
Next.js client wiring and tests packages/nextjs/src/ThunderIDNextClient.ts, packages/javascript/src/api/__tests__/executeEmbeddedSignInFlow.test.ts	signIn forwards arg2?.flowSecret to executeEmbeddedSignInFlow; tests add a header capture helper and verify header inclusion/exclusion across new flow start, step submission, and missing-secret cases.

Estimated code review effort: 2 (Simple) | ~10 minutes

Sequence Diagram(s)

sequenceDiagram
  participant NextClient as ThunderIDNextClient
  participant API as executeEmbeddedSignInFlow
  participant FetchAPI

  NextClient->>API: signIn(arg2 with flowSecret)
  alt new flow start and flowSecret provided
    API->>FetchAPI: fetch(request with X-Flow-Secret header)
  else continuation or no flowSecret
    API->>FetchAPI: fetch(request without X-Flow-Secret header)
  end
  FetchAPI-->>API: response
  API-->>NextClient: result

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes the main change: sending the flow secret via the Flow-Secret header on native flow initialization.
Description check	✅ Passed	The PR description matches the template and includes the required Purpose, Approach, Related Issues, Related PRs, Checklist, and Security checks.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}