[Design Discussion] Client verification enhancement for app native flows

[Malith-19]

Related Feature Issue

#2009

Problem Summary

Thunder's app-native flow execution lets first-party clients call /flow/execute directly using an applicationId, which is a public identifier rather than a credential. As a defense-in-depth improvement, we want to strengthen client authenticity at flow initiation so that Thunder has positive verification that the calling client is the one the application was registered for, rather than relying on the identifier alone. The same hardening applies to gate, and we are also taking the opportunity to improve the in-flow challengeToken by moving it out of the JavaScript-readable response body for web clients and giving it an explicit lifetime, bringing the runtime token handling in line with modern best practice.

High-Level Approach

We split the problem along the two client form factors, because the strongest mechanism differs for each.

For browser-based clients (gate and customer-hosted SPAs), Thunder relocates challengeToken from the response body into an HttpOnly, Secure, SameSite cookie set on the first /flow/execute response — no separate pre-flight endpoint. The first call's Origin and Sec-Fetch-Site headers, checked against the application's allowed origins, are what admit the flow; from the second call onward the browser attaches the cookie automatically and Thunder uses it to bind every subsequent request. SameSite is Strict for same-domain deployments and None for cross-domain, paired with POST-only and strict origin checks. For gate specifically, the first /flow/execute is made by the OAuth component server-side, so it must forward the resulting Set-Cookie through its /authorize response to the browser — a small but deliberate piece of wiring.

For mobile clients, cookies are not a good fit. We require platform attestation — Apple App Attest on iOS, Play Integrity on Android — on the first /flow/execute call. The app obtains a signed assertion proving its binary matches the registered app identity, Thunder verifies it with Apple's and Google's APIs, and executionId and challengeToken are then issued in the body as today.

In both cases, the existing executionId and challengeToken continue to drive subsequent flow steps, with the addition of an explicit TTL replacing the current valid-until-consumed behavior.

Architecture Overview

The diagram above shows both client paths converging on the same verification gate inside Thunder, with the verification folded into the first /flow/execute call rather than a separate endpoint.

The /flow/execute endpoint gains a verification step at flow initiation, Thunder runs the verification path: check Origin against the application's allowedOrigins, check Sec-Fetch-Site to confirm the request is a same-origin or known cross-origin fetch, and for mobile requests verify the platform attestation token. If all checks pass, Thunder issues a server-side session record bound to the applicationId, generates a cookie value, sets Set-Cookie on the response (HttpOnly, Secure, SameSite per the rules above, with an explicit Max-Age), and returns executionId in the body and challengeToken as a cookie. From the second call onward, Thunder requires the cookie to be present on the request and to map to the same applicationId carried in the body.

For browser clients calling /flow/execute directly (customer SPAs), the Set-Cookie lands on the browser naturally because the browser issued the request.

For gate, the flow is one hop longer. The OAuth /authorize handler creates the flow by calling /flow/execute internally. The response from /flow/execute carries Set-Cookie, which the OAuth handler must explicitly include in the response it sends back to the browser alongside the existing flowId, appId, authId payload. The OAuth component effectively acts as a transparent forwarder of the cookie. From that point on, the browser-side gate client drives /flow/execute calls directly and the cookie is sent automatically.

The attestation verifier is a new internal component that holds Apple's and Google's public keys (or calls their verification APIs) and validates the assertion against the registered app ID, team ID, and bundle ID stored on the application configuration. Per-app configuration adds an attestation block listing the platform, app IDs, and key IDs that Thunder will accept.

The application configuration model gains two fields: allowedOrigins (list, used by the cookie path) and attestation (object, used by the mobile path). Both are optional — an application can be configured for one path, the other, or both.

Security Considerations

What relocating the token to a cookie actually buys us. The cookie itself is not a new authenticator, it carries the same challengeToken we already issue. The win is the transport: HttpOnly removes the token from anything JavaScript can reach, which closes off XSS exfiltration, browser-extension exfiltration, and accidental logging by the client. The token is no less secret than before; it is just no longer handed to code that has no business reading it. Secure keeps it off plaintext channels, and SameSite keeps it off cross-site requests.

Trust on the first call. The first /flow/execute call has no cookie yet, that's the call that establishes the cookie. Its protection rests on Origin and Sec-Fetch-Site, both browser-set and unforgeable from JavaScript, plus the POST-only requirement. This is sound, but it is the most security-critical moment in the flow and the checks must be strict. Any application without a valid allowedOrigins entry must be refused, not allowed through with a warning.

Challenge token lifetime — explicit TTL, not until-consumed. Today the token is effectively valid until consumed. The proposal adds an explicit expiration enforced on every check, on both transports. The reasoning:

• A token sitting in browser memory or device storage with no expiration is a credential whose blast radius grows with time. If a flow is started and abandoned for hours, the token remains usable.
• Flows are inherently short — the user is at the keyboard working through the steps. There is no legitimate reason for a token to outlive that.
• Tying expiration only to first use assumes the legitimate user will be the first to use it, which is the assumption we are otherwise hardening against.

Concrete recommendation: a default of 15 minutes, re-issued on each /flow/execute response with a sliding 15-minute window. The exact value should be a deployment configuration so operators can tune it. Expired tokens get a distinct error code so SDKs can restart the flow gracefully.

Thunder OAuth-component-as-forwarder. Because Thunder OAuth component is the one that receives Set-Cookie and must forward it, an implementation bug there (dropping the header, mangling attributes) results in gate failing on the second /flow/execute. This is observable rather than exploitable, but it means the OAuth component now has a small but real responsibility for security headers. Worth a focused unit test asserting Set-Cookie is present on /authorize with the expected flags.

Mobile transport remains body-based. Mobile clients still receive challengeToken in the body, which means it sits in process memory accessible to the app's own code. This is acceptable because,

• attestation on the first call has already verified the app's binary identity, so a malicious app on the same device cannot have obtained that token in the first place
• iOS and Android process isolation prevents other apps from reading it.

The threat model on mobile is genuinely different from the browser, and a body-borne token is appropriate there.

Impacted Areas

• API Layer
• Flows
• Gate App
• Oauth

Alternatives Considered

Backend-for-Frontend (BFF) pattern

Route all flow execution through a server-side proxy that holds client credentials, turning a public web client into a confidential one. Partially adopted as opt-in. Genuinely effective for web and we should document it as a stronger posture for customers who want it. Rejected as the baseline because it forces every web customer to stand up server-side infrastructure, adds a latency hop, and does nothing for standalone mobile apps that don't route through a web server.

Trusted domains / origin allowlist

Per-application list of allowed origins; reject /flow/execute requests whose Origin is not on the list. Partially adopted. Folded into the proposed solution as the gate on the first call. Rejected as a standalone solution because Origin is spoofable by non-browser clients, doesn't apply to mobile, and on its own doesn't protect the in-flow challengeToken from XSS — the cookie relocation is what addresses that.

DPoP-style proof of possession with a browser-generated key

SPA generates a non-extractable key in SubtleCrypto and signs each request. Rejected. The key would still be reachable by JS in the page, so XSS can use it freely. HttpOnly cookies are strictly stronger against the XSS vector, which is the most likely attack surface on a SPA. Worth revisiting if hardware-bound browser keys become broadly available.

Reverse proxy with secret injection

Developer-operated proxy injects a client_secret into requests before forwarding to Thunder. Rejected as a distinct option. Effectively the BFF pattern framed as a proxy configuration; the security properties and cost trade-offs are identical. Covered by adopting BFF as an opt-in.

Questions for Community Input

No response

[sahandilshan]

Consider CIBA as a first-class use case for mobile attestation

The mobile attestation path proposed here has a direct intersection with the CIBA design in #2740. In CIBA, the "Async User Auth" sub-flow — where the user authenticates on their device after receiving a notification — is essentially an app-native flow execution via /flow/execute. That makes it a primary consumer of the mobile attestation mechanism being designed here.

A few things worth considering while this is still in design:

1. Attestation + CIBA binding message — Should the platform attestation assertion also bind to the auth_req_id or the CIBA binding message? This would tie the device proof to the specific CIBA request, preventing an attested app from being used to approve a different request than the one the user was notified about.

2. TTL coherence — The proposed 15-minute sliding challengeToken TTL needs to align with CIBA's auth_req_id expiry (spec suggests 120–300 seconds). If the CIBA request expires in 5 minutes but the flow-level token lives for 15, there's a window where the flow is technically still alive but the CIBA request it serves has already expired.

3. Notification-initiated flows — CIBA flows on mobile start from a push notification or deep link, not from a user-initiated app launch. The attestation verification on the first /flow/execute call should account for this entry path — ensure that attestation can be obtained and attached before the first flow call even when the app is cold-started from a notification.

Referencing #2740 from this discussion would help keep the two designs aligned.

[Malith-19]

I had a discussion with @darshanasbg regarding the approach two weeks ago and he has suggested to block the flows API for the redirect based applications (for those use authorization code grant type).

Restricting /flow/execute for redirect-based applications

For redirect-based applications (those configured with the authorization_code grant type and redirect URIs), the /flow/execute HTTP endpoint is never legitimately called to initiate a new flow — the OAuth /authorize handler already does that internally via a direct Go service call (InitiateFlow), which bypasses the HTTP endpoint entirely. The browser-side Gate client then drives subsequent steps using an already-established executionId.

This means we can enforce a simple rule: if an application has authorization_code in its grant types, reject any HTTP call
to POST /flow/execute that arrives without an executionId (i.e., a new-flow initiation attempt). Continuing an existing
flow with a known executionId is unaffected, so Gate keeps working normally.

The check would live in loadNewContext() in the flow execution service — not in initContext() — so it only fires on the
HTTP-initiated new-flow path and never blocks the OAuth component's internal InitiateFlow() calls.

Effect on the paths:

• HTTP new-flow initiation for a redirect-based app → blocked (authorization_code grant detected)
• Gate SPA continuing an existing flow via executionId → unaffected
• OAuth component's internal InitiateFlow() → unaffected (different code path)
• App-native apps (no authorization_code grant) → unaffected

This narrows the scope of the cookie/attestation work proposed here: those mechanisms only need to address app-native
clients (mobile and custom SPAs using direct flow execution). Redirect-based apps are fully covered by this access control
with no new token transport required.

[ThumulaPerera]

Please correct me if I misunderstood. I found the description to be a bit confusing.

High-Level Approach says

Thunder relocates challengeToken from the response body into an HttpOnly, Secure, SameSite cookie set on the first /flow/execute response

But Architecture Overview says

Thunder issues a server-side session record bound to the applicationId, generates a cookie value, sets Set-Cookie on the response (HttpOnly, Secure, SameSite per the rules above, with an explicit Max-Age), and returns executionId and challengeToken in the body as today.

Can you clarify whether we are moving the challengeToken to a cookie or keeping challengeToken in the body and introducing a new nonce as the cookie ?

[Malith-19]

Hi @ThumulaPerera,

Yes the architecture overview should be updated to include the challengeToken as the cookie for browser based apps. I have updated it now.

[ThumulaPerera]

SameSite is Strict for same-domain deployments and None for cross-domain

For customer apps deployed on different domains, won't this create a vulnerability to CSRF attacks? We cross check the origin against an allowlist for the initial request. But once the cookie is set, a forged request from a malicious site will also have the cookie attached to it. A correctly timed such request (eg: before a user attribute updating step) may be harmful.

Thinking along that, I'm thinking whether we should re-evaluateorigin allowlist as an alternative approach for browser based flows. My counter arguments to the reasons for rejection are these

Origin is spoofable

The proposed approach is also vulnerable to this as the initial request validation is purely based on this

doesn't apply to mobile

This is valid. My suggestion is to rely on this only for browser apps

doesn't protect the in-flow challengeToken from XSS

As I understood from #2008, the purpose of the challenge token is to ensure that that client that initiated the flow and the one advancing it are the same. By cross checking each request against the origin allowlist, we are achieving the same thing. We might not need a challenge token at all in that case.

[ThumulaPerera]

Found the discussion for challenge token at #1940. According to this as well, the purpose of the challenge token is to ensure that that client that initiated the flow and the one advancing it are the same.

[Malith-19]

cc: @ThaminduDilshan

[Malith-19]

Update from review call

We held a call to review the security model for the Flow API. Here's a summary of what was discussed and decided.

Key decisions reached:

• The Flow API will move to a secured-by-default model — flow initiation will fail unless a valid authorization mechanism is present. No more open-ended flow initiation.
• Backend apps will use API keys or secrets. SPAs will use origin header validation against configured allowed domains as a best-effort protection.
• SPA implementation is prioritized before mobile app support.

On challenge tokens:
Challenge tokens remain necessary alongside domain validation to prevent session hijacking. Regarding introducing the TTL for challenge tokens, it's already present in the flow context as it has an expiry time we don't need to introduce separate time for challenge tokens. Hence we can skip it.

On SPAs and CSRF:
The team acknowledged the known limitation: when a SPA is on a different domain, SameSite=None reintroduces CSRF risk. A cookie-only solution is insufficient for cross-domain scenarios. Origin header validation is the agreed "maximum feasible protection" for this architecture, accepting that it's best-effort. This connects to @ThumulaPerera's point above — the CSRF concern with cross-domain cookies is a known trade-off the team is aware of.

On mobile:
Further research is needed to confirm whether current mobile SDKs support the required redirections and server-side checks before finalizing the mobile attestation path.

[Malith-19]

Concluded solution diagram

[Malith-19]

Sequence Diagram

sequenceDiagram
    actor Admin as Administrator
    actor User as End User
    participant MW as Security Middleware
    participant FMGMT as Flow Management<br/>Service
    participant VERIFY as Initiation Verification<br/>(Planned)
    participant FES as Flow Execution<br/>Service
    participant Engine as Flow Engine
    participant Exec as Executor
    participant Store as Context Store<br/>(DB or Redis)
    participant Ext as External Service /<br/>User Store

    Note over Admin, Store: Phase 1 — Admin publishes flow definition
    Admin->>MW: POST /flows (Bearer JWT)
    MW->>MW: Validate JWT + system permission
    MW->>FMGMT: Forward request
    FMGMT->>Store: Persist flow definition (graph)
    Store-->>FMGMT: OK
    FMGMT-->>Admin: 201 Created

    Note over User, Ext: Phase 2 — End user executes a flow
    User->>VERIFY: POST /flow/execute {applicationId, flowType}<br/>(new flow — Origin header / API key / attestation)
    VERIFY->>VERIFY: Validate client type<br/>(Origin vs allowedOrigins, or API key, or attestation)
    VERIFY-->>FES: Verified request
    FES->>Store: Resolve flow graph for app
    Store-->>FES: Flow definition
    FES->>Engine: Start traversal at START node

    loop Graph Traversal
        alt TASK_EXECUTION Node
            Engine->>Engine: Validate challenge token (if continuation)
            Engine->>Exec: Delegate to registered executor
            Exec->>Ext: Call external service / user store
            Ext-->>Exec: Response
            Exec-->>Engine: Status (SUCCESS / FAIL / INCOMPLETE)
            Engine->>Engine: Follow onSuccess / onFailure / onIncomplete branch
        else PROMPT Node
            Engine->>Engine: Generate fresh challenge token (32-byte random)
            Engine->>Store: Persist flow context (executionId, current node,<br/>inputs, challengeTokenHash)
            Engine-->>FES: INCOMPLETE + prompt + challengeToken
            FES-->>User: 200 {status: INCOMPLETE, executionId, challengeToken}
            User->>FES: POST /flow/execute {executionId, inputs, challengeToken}
            FES->>Store: Retrieve flow context
            Store-->>FES: Persisted context (with challengeTokenHash)
            FES->>Engine: Resume traversal (challengeToken set for validation)
        end
    end

    Engine->>Store: Clean up flow context
    Engine-->>FES: COMPLETE + result / assertion JWT
    FES-->>User: 200 {status: COMPLETE, assertion}

Loading

[Malith-19]

Architecture diagram

graph LR
    subgraph External Actors
        EU["End User\n(Browser / Mobile / Backend)"]
        ADMIN["Administrator"]
    end

    subgraph Thunder Server
        subgraph "Flow Initiation Verification (Planned)"
            VERIFY["Client Type Verification\n• Browser SPA: Origin vs allowedOrigins\n• Redirect-app: Block new-flow HTTP init\n• Mobile: Platform attestation [research]\n• Backend: API key / client secret"]
        end

        subgraph Public APIs
            FES["Flow Execution Service\nPOST /flow/execute"]
            FMS_META["Flow Metadata Service\nGET /flow/meta"]
        end

        subgraph Admin APIs ["Admin APIs (Bearer JWT + system permission)"]
            FMGMT["Flow Management Service\n/flows/**"]
        end

        subgraph Internal Components
            ENGINE["Flow Engine\n(Challenge Token Validation\n+ Node Traversal)"]
            REG["Executor Registry\n(26 Executors)"]
            OAUTH_INT["OAuth Component\n(internal InitiateFlow())"]
        end

        subgraph Security
            MW["Security Middleware\nCorrelationID → AccessLog\n→ SecurityMiddleware"]
        end
    end

    subgraph Context Stores
        DB[("Primary Database\nPostgreSQL / SQLite\n(Flow Definitions +\nFlow Contexts)")]
        REDIS[("Redis\n(Flow Contexts)\n[optional]")]
    end

    subgraph External Services
        EXT_HTTP["External HTTP Services\n(Admin-configured URLs)"]
        IDP["Identity Providers\n/ User Stores"]
    end

    EU -->|"HTTPS + client verification\n(see verification layer — Planned)"| VERIFY
    EU -->|"No Auth"| FMS_META
    VERIFY -->|"Verified\n(new-flow initiation)"| FES
    VERIFY -. "401/403 reject" .-> EU
    EU -->|"HTTPS + executionId\n+ challengeToken\n(continuation)"| FES
    OAUTH_INT -->|"Internal InitiateFlow()\n(bypasses HTTP guard)"| ENGINE
    ADMIN -->|"Bearer JWT"| MW
    MW --> FMGMT

    FES --> ENGINE
    ENGINE --> REG
    ENGINE -->|"Read/Write\nFlow Context"| DB
    ENGINE -->|"Read/Write\nFlow Context\n(if configured)"| REDIS
    FMGMT -->|"CRUD\nFlow Definitions"| DB
    FES -->|"Read\nFlow Definitions"| DB
    REG -->|"HTTPRequestExecutor"| EXT_HTTP
    REG -->|"BasicAuth, OIDC,\nOAuth, etc."| IDP

Loading

[rajithacharith]

How are the allowedOrigins configured? Are they defined at the application level as an application-specific attribute, or are they managed through a system-wide configuration?

[Malith-19]

Hi @rajithacharith, initial plan was to bring application level configuration but with the latest discussions, we agreed to not to bring this allowedOrgins config [1].

[1] #2744 (comment)

[Malith-19]

Update: Decision Summary and Implementation Direction

Following further design discussions and review, we've reached agreement on the approach for the secured-by-default flow initiation model. This post summarizes the decisions and how we are moving forward with implementation.

---

Decision 1 — Browser SPAs restricted to redirect-based flows

After evaluating the native SPA flow pattern (SPA calling POST /flow/execute directly), we've decided to restrict browser SPAs to redirect-based flows only, following the same model used in Identity Server and standard OAuth 2.0 + PKCE implementations.

Rationale: In a native SPA flow, the applicationId is embedded in the browser and visible in network requests. This makes it structurally impossible to distinguish a legitimate SPA from a malicious one mimicking it. The redirect-based model avoids this entirely — the IDP enforces redirection to pre-registered redirect_uri values, meaning the authorization code exchange can only be completed by the legitimate application.

Implication: Any application configured with the authorization_code grant type — including browser SPAs — will have direct HTTP new-flow initiation blocked. Flows for these clients continue to be initiated exclusively via the OAuth component's internal InitiateFlow() call, exactly as the redirect-based app path works today. SPA implementation is the priority for this work.

---

Decision 2 — Origin header validation for native SPA flows is not being pursued

We evaluated adding allowedOrigins-based Origin header validation as a hardening option for SPAs that want to call the flow endpoint natively. This proposal has been shelved.

Rationale: Rather than offering a partial control that developers might rely on as sufficient protection, we've agreed it's a cleaner and more consistent approach to simply not support the native SPA pattern and direct developers toward the redirect-based flow. The SDK will be updated to reflect this.

---

Implementation Plan

The secured-by-default initiation model will be implemented in the following order:

1. SPA / Redirect-based apps — HTTP guard in loadNewContext() to block direct new-flow initiation for authorization_code grant type applications. This is the priority item.
2. Backend / server-side clients — API key or client secret verification at flow initiation.
3. Mobile clients — Platform attestation (Apple App Attest / Google Play Integrity). Currently in the research phase; implementation will follow once the attestation integration design is finalised.

---

Next Steps

• Implement HTTP guard for authorization_code grant type applications in loadNewContext()
• Block the SPA creation with emebedded flows and add backend validation.
• Update SDK to remove native SPA flow patterns and guide developers toward redirect-based flows
• Update documentation to clarify that direct flow execution is not supported for browser SPAs

Please comment if you have questions or alternative perspectives.

[Malith-19]

Architecture Diagram

graph LR
    subgraph External Actors
        EU["End User\n(Browser / Mobile / Backend)"]
        ADMIN["Administrator"]
    end

    subgraph ThunderID Server
        subgraph "Flow Initiation Verification (Planned)"
            VERIFY["Client Type Verification\n• Redirect-app + SPA: Block new-flow HTTP init\n• Mobile: Platform attestation [research]\n• Backend: App secret"]
        end

        subgraph Public APIs
            FES["Flow Execution Service\nPOST /flow/execute"]
            FMS_META["Flow Metadata Service\nGET /flow/meta"]
        end

        subgraph Admin APIs ["Admin APIs (Bearer JWT + system permission)"]
            FMGMT["Flow Management Service\n/flows/**"]
        end

        subgraph Internal Components
            ENGINE["Flow Engine\n(Challenge Token Validation\n+ Node Traversal)"]
            REG["Executor Registry\n(26 Executors)"]
            OAUTH_INT["OAuth Component\n(internal InitiateFlow())"]
        end

        subgraph Security
            MW["Security Middleware\nCorrelationID → AccessLog\n→ SecurityMiddleware"]
        end
    end

    subgraph Context Stores
        DB[("Primary Database\nPostgreSQL / SQLite\n(Flow Definitions +\nFlow Contexts)")]
        REDIS[("Redis\n(Flow Contexts)\n[optional]")]
    end

    subgraph External Services
        EXT_HTTP["External HTTP Services\n(Admin-configured URLs)"]
        IDP["Identity Providers\n/ User Stores"]
    end

    EU -->|"HTTPS + client verification\n(see verification layer — Planned)"| VERIFY
    EU -->|"No Auth"| FMS_META
    VERIFY -->|"Verified\n(new-flow initiation)"| FES
    VERIFY -. "401/403 reject" .-> EU
    EU -->|"HTTPS + executionId\n+ challengeToken\n(continuation)"| FES
    OAUTH_INT -->|"Internal InitiateFlow()\n(bypasses HTTP guard)"| ENGINE
    ADMIN -->|"Bearer JWT"| MW
    MW --> FMGMT

    FES --> ENGINE
    ENGINE --> REG
    ENGINE -->|"Read/Write\nFlow Context"| DB
    ENGINE -->|"Read/Write\nFlow Context\n(if configured)"| REDIS
    FMGMT -->|"CRUD\nFlow Definitions"| DB
    FES -->|"Read\nFlow Definitions"| DB
    REG -->|"HTTPRequestExecutor"| EXT_HTTP
    REG -->|"BasicAuth, OIDC,\nOAuth, etc."| IDP

Loading

[Malith-19]

Sequence Diagram

sequenceDiagram
    actor Admin as Administrator
    actor User as End User
    participant MW as Security Middleware
    participant FMGMT as Flow Management Service
    participant VERIFY as Initiation Verification (Planned)
    participant FES as Flow Execution Service
    participant Engine as Flow Engine
    participant Exec as Executor
    participant Store as Context Store (DB or Redis)
    participant Ext as External Service / User Store

    Note over Admin, Store: Phase 1 — Admin publishes flow definition
    Admin->>MW: POST /flows (Bearer JWT)
    MW->>MW: Validate JWT + system permission
    MW->>FMGMT: Forward request
    FMGMT->>Store: Persist flow definition (graph)
    Store-->>FMGMT: OK
    FMGMT-->>Admin: 201 Created

    Note over User, Ext: Phase 2 — End user executes a flow
    User->>VERIFY: POST /flow/execute
    VERIFY->>VERIFY: Validate client type
    VERIFY-->>FES: Verified request
    FES->>Store: Resolve flow graph for app
    Store-->>FES: Flow definition
    FES->>Engine: Start traversal at START node

    loop Graph Traversal
        alt TASK_EXECUTION Node
            Engine->>Engine: Validate challenge token
            Engine->>Exec: Delegate to registered executor
            Exec->>Ext: Call external service / user store
            Ext-->>Exec: Response
            Exec-->>Engine: Status (SUCCESS / FAIL / INCOMPLETE)
            Engine->>Engine: Follow onSuccess or onFailure or onIncomplete branch
        else PROMPT Node
            Engine->>Engine: Generate fresh challenge token
            Engine->>Store: Persist flow context (executionId, node, inputs, challengeTokenHash)
            Engine-->>FES: INCOMPLETE + prompt + challengeToken
            FES-->>User: 200 {status: INCOMPLETE, executionId, challengeToken}
            User->>FES: POST /flow/execute {executionId, inputs, challengeToken}
            FES->>Store: Retrieve flow context
            Store-->>FES: Persisted context (with challengeTokenHash)
            FES->>Engine: Resume traversal with challengeToken
        end
    end

    Engine->>Store: Clean up flow context
    Engine-->>FES: COMPLETE + result / assertion JWT
    FES-->>User: 200 {status: COMPLETE, assertion}

Loading

[Malith-19]

Follow-up: decouple the flow-execution guard from protocol (OAuth) specifics

This came out of the review on #3451 / PR #3476 (App Secret verification at flow initiation). Capturing the plan here since it touches the broader app-native flow design and a future protocol (e.g. SAML) would hit the same path.

Problem

The flow-execution guard currently reaches into protocol internals: checkDirectFlowInitiationAllowed calls actorProvider.GetOAuthProfileByID(), inspects grantTypes for authorization_code, separately calls GetInboundClientByID() for existence, then verifies the App Secret. That couples a protocol-agnostic layer to OAuth, and the same "is this redirect-based / does it need an App Secret" rule is now computed in more than one place (issuance vs. the guard), which has already caused drift.

Proposed approach

Move the classification out of flow-exec and into the actor/application layer (the actorprovider seam that flow-exec already depends on):

1. Derive, don't store. actorprovider already resolves the inbound client + protocol profile when it loads an actor. It computes a small, neutral classification at runtime from the existing attributes (publicClient, grantTypes) — e.g. IsRedirectBased / RequiresAppSecret, or an InitiationMode { Redirect, Direct } — and surfaces it on the returned actor/application model.

   • No new DB column, no migration, no backfill.
   • No new user-provided field and no /applications API change — apps keep sending the OAuth attributes they do today; the classification is derived from them.
   • "No protocol profile at all" (embedded server-side apps) ⇒ classified as direct/backend, matching today's behaviour.

2. Flow-exec consumes a flag, not a profile. The guard makes one actor-resolution call and branches on the flag, instead of calling GetOAuthProfileByID and poking at grant types. The existence/unknown-app check folds into that same resolution call (clean not-found). This collapses the current multi-call, multi-branch logic to roughly: resolve → if redirect-based reject (403) → else require + verify App Secret.

3. Keep credential verification where it belongs. The flag only answers "does this app initiate directly / require an App Secret." The actual App Secret check stays in the entity service (AuthenticateEntityByID, hashed constant-time compare) — we do not carry secret material on the resolved model.

4. Single source of truth. The same derived eligibility is reused for App Secret issuance (today's isAppSecretEligible) and for the guard, so the two can't drift.

Why this is protocol-agnostic

The detection is expressed in OAuth terms today only because OAuth is the single redirect-based inbound protocol. With this shape, adding SAML (or any other redirect protocol) only touches the actor-layer derivation; flow-exec is untouched because it just reads IsRedirectBased.

Scope / sequencing

This is a cross-cutting refactor of the shared actor model and revisits structures from the App Secret PR, so I'd suggest landing it as its own follow-up rather than expanding #3476 (which is feature-complete and tested). Ideally done when a second protocol makes the abstraction concrete, so we generalise against a real second consumer rather than a hypothetical one. The smaller isAppSecretEligible helper already in #3476 is a first step toward consolidating the duplicated logic.

Open question to evaluate: whether the resolved model should also expose enough for the App Secret presence/requirement, while still keeping verification itself in the entity service.

[ThaminduDilshan]

I have few questions with the design.

1. What's the flag you're trying to introduce? Is it a single boolean flag or multiple flags? If not, is it something like a type? What are the values supported by the flag?
2. "actorprovider already resolves the inbound client + protocol profile when it loads an actor": It's fine for the actor provider to load these data to compute runtime data required. But in flow side, none of these protocol profile data is used right? Do we really need to return them to the flow?

Since changes are related to $subject and #3476 PR introduces significant changes to the flow packages which is going to get removed with this refactoring, I'm fine to do it in the same PR. Maybe as a separate commit

[Malith-19]

1. What's the flag you're trying to introduce? Is it a single boolean flag or multiple flags? If not, is it something like a type? What are the values supported by the flag?

We will be introducing a single type enum (FlowInitiationMode) with three values as per now.

1. RedirectOnly → direct HTTP new-flow initiation is not permitted; the OAuth
   component initiates internally. Direct call → 403 (FES-1011).
2. AppSecret → direct initiation permitted; caller must present a valid
   App Secret (missing → FES-1012, invalid → FES-1013).
3. Attestation → (reserved) direct initiation permitted via mobile platform
   attestation; not implemented yet, listed so the type is
   forward-compatible with the mobile work in this thread.

2. "actorprovider already resolves the inbound client + protocol profile when it loads an actor": It's fine for the actor provider to load these data to compute runtime data required. But in flow side, none of these protocol profile data is used right? Do we really need to return them to the flow?

Agreed, and that's the intent — flow-exec should never see the OAuth profile. The actor layer reads grantTypes/publicClient internally to compute the enum and returns only the enum (plus the normal resolved identifiers). No grantTypes, no publicClient, no profile object crosses into the flow layer. That's the whole point of the decoupling — the protocol fields stay in the actor/protocol layer; the flow layer gets a protocol-neutral classification.

[ThaminduDilshan]

+1