Skip to content

Help Wanted: Open Puter Login and Sign Up in the External Default Browser #1

Open

Description

@CodeByArnob

Problem Summary

FoodLens is an open-source AI food intelligence and nutrition platform developed with Flutter. It implements a decentralized User-Pays cloud architecture using Puter.js. Under this model, each user authenticates with their own personal Puter account and consumes their own monthly free AI allowance ($10.00 monthly quota) to run cloud vision inference. This ensures that users own their data and the open-source project maintainer incurs no centralized server costs.

Currently, when a user taps Login or Sign Up in FoodLens, the application displays an embedded WebView inside the Flutter application. This in-app WebView approach creates usability challenges, including lack of access to saved browser passwords, autofill limitations, and inconsistent window handling.

We want both Puter Login and Sign Up actions to open the user default Android external browser (such as Chrome, Firefox, Samsung Internet, or their preferred system browser). After completing authentication in their browser, the user should return to FoodLens with their Puter account session recognized and persisted.

We invite experienced international Flutter, Android, OAuth, and Puter.js developers to investigate this architecture and contribute a verified solution.


Current Behavior vs Expected Behavior

Current Behavior

  1. The user opens FoodLens and navigates to Onboarding or Profile Settings.
  2. The user taps Sign In with Puter or Sign Up.
  3. An internal embedded WebView modal opens within the mobile application.
  4. The user must authenticate inside this isolated embedded browser instance.
  5. In-app WebViews lack integration with system-level credential managers and create a suboptimal user experience.

Expected Behavior

  1. The user taps Sign In with Puter or Sign Up.
  2. The application opens the user configured default Android browser (or Chrome Custom Tabs if officially supported by the auth provider).
  3. The user authenticates securely on the official Puter portal using their existing browser session and saved credentials.
  4. Upon successful authentication, the user is redirected back to the FoodLens mobile application.
  5. The application securely establishes the user session, verifies their available monthly allowance, and persists the session across app restarts.

Architectural Context and Technical Findings

Current Flutter and JavaScript Bridge Architecture

FoodLens currently communicates with Puter.js through a local headless bridge:

  • JavaScript Bridge: assets/html/puter_bridge.html
  • Dart Bridge Service: lib/features/auth/services/puter_bridge_service.dart
  • In-App WebView Screen: lib/features/auth/screens/puter_auth_webview_screen.dart
  • Auth State Provider: lib/features/auth/providers/auth_provider.dart

Puter.js SDK Investigation

  1. The official Puter.js SDK (https://js.puter.com/v2/) relies on puter.auth.signIn(), which is built around browser popup mechanics (window.open).
  2. An external browser session stores authentication cookies within that browser private profile, isolated from the mobile application local storage sandbox.
  3. Returning from an external browser to an Android native application typically requires Custom URI Schemes (such as foodlens://auth/callback) or verified Android App Links.
  4. Contributors must research whether Puter officially supports an OAuth 2.0 PKCE redirect flow, a custom redirect URI parameter, or an official mobile SDK integration.
  5. If the current public Puter.js SDK does not document this flow, contributors are encouraged to research official Puter developer resources or consult the Puter maintainers rather than creating undocumented workarounds.

Strict Security and User-Pays Requirements

Any proposed solution must satisfy the following constraints:

  1. Preserve User-Pays Model: Every user must authenticate with their own personal Puter account and utilize their own free tier allowance.
  2. No Insecure Token Exposure: Authentication tokens must never be passed through plain, unencrypted, or logged URL query parameters.
  3. No Hardcoded Secrets: No developer API keys, secret client keys, or private tokens may be placed in the client application.
  4. Session Persistence: Once authenticated, the user session must persist across application restarts until explicitly logged out.

Steps to Reproduce Current Implementation

  1. Connect an Android physical device or start an Android 13+ emulator.
  2. Clone the repository and run the application:
    flutter pub get
    flutter run
  3. On the Onboarding screen or Profile Settings, tap Sign in with Puter.
  4. Notice that an internal embedded WebView is presented instead of launching the system default browser.

Acceptance Criteria

  1. Both Login and Sign Up buttons launch the user default external browser or an officially supported Custom Tab session.
  2. After successful authentication on Puter, the user returns smoothly to the FoodLens application.
  3. The user Puter identity and remaining monthly allowance ($10.00 tier) display correctly in FoodLens.
  4. The authentication session survives cold application restarts.
  5. The solution passes dart format, flutter analyze with 0 issues, and all automated tests in flutter test.
  6. Verified on a physical Android device running API 24+.

How to Contribute

  1. Review CONTRIBUTING.md and documentation/AUTHENTICATION_TROUBLESHOOTING.md.
  2. Post a comment on this issue describing your technical approach and findings before writing extensive code.
  3. Submit a Pull Request targeting the main branch with comprehensive verification notes.

Thank you for contributing to open-source food intelligence.

Activity

  1. added
    bugSomething isn't working
    help wantedExtra attention is needed
    authenticationAuthentication, OAuth, and Puter.js integration
    androidAndroid platform integration & WebView
    on Nov 6, 2026
  2. added a commit that references this issue on Nov 6, 2026
  3. added
    enhancementNew feature or request
    and removed
    bugSomething isn't working
    on Nov 6, 2026
  4. changed the title [-]Help Wanted: Investigate and Fix Puter.js Authentication and Google Sign-In Integration[/-] [+]Help Wanted: Open Puter Login and Sign Up in the External Default Browser[/+] on Nov 6, 2026
  5. pinned this issue on Nov 6, 2026
  6. CodeByArnob commented on Nov 6, 2026

    @CodeByArnob
    OwnerAuthor

    Maintainer investigation: external-browser session handoff

    I have verified the current behavior against the official Puter.js documentation and the native-app OAuth security guidance.

    Confirmed findings

    • puter.auth.signIn() is documented as a website-only API. It opens a popup and resolves with a SignInResult.
    • The documented SignInResult includes an authentication token, app_uid, and username.
    • Opening https://puter.com/login directly in Chrome only authenticates the browser's Puter account. It does not authorize FoodLens as a Puter.js website application and does not create a session in the app's isolated WebView.
    • RFC 8252 requires native OAuth authorization to use an external user-agent and a redirect response protected with PKCE. We must not invent a token-in-query callback or scrape Chrome cookies.

    Proposed implementation direction

    1. Keep the Flutter app as a public native client. Generate a per-attempt cryptographically random state and PKCE verifier/challenge where the authorization provider supports the corresponding flow.
    2. Use a first-party HTTPS FoodLens authorization page, served from a stable origin, to invoke the documented Puter website sign-in flow from a real user gesture.
    3. Establish a verified return channel to Android. Preferred options are a Puter-supported authorization-code redirect with PKCE, or an origin-verified Android Custom Tabs postMessage channel (Digital Asset Links) if compatible with Puter's popup flow.
    4. Validate the callback origin, state, one-time transaction, Puter identity and token before storing credentials in Android secure storage. Never put the Puter token in a URL, log, clipboard, or untrusted intent.
    5. Restore the token into the FoodLens Puter.js bridge, verify isSignedIn(), getUser(), AI access and usage, then test cold restart and sign-out revocation.

    Maintainer/provider confirmation requested

    Can the Puter team confirm whether the public Puter.js website sign-in flow supports a native-app callback / authorization-code exchange (including PKCE), or whether there is a supported secure way for a website's SignInResult.token to be delivered to a verified Android Custom Tabs client without exposing it in a redirect URL?

    Until that provider capability and the trusted callback origin are confirmed, I will not ship an insecure token handoff. The existing PR #4 only opens the generic Puter login page and is not an end-to-end authentication fix.

  7. CodeByArnob commented on Nov 6, 2026

    @CodeByArnob
    OwnerAuthor

    GitHub Pages origin provisioned

    The maintainer has created the public repository CodeByArnob/CodeByArnob.github.io for the FoodLens account-connection origin.

    • Intended site origin: https://codebyarnob.github.io/
    • Static landing page and GitHub Actions Pages deployment workflow have been committed.
    • The page explicitly states that authentication handoff is not enabled and does not collect credentials or tokens.

    Remaining setup and security prerequisites

    1. Enable GitHub Pages in the new repository under Settings → Pages, selecting GitHub Actions as the deployment source. Confirm the deployment workflow completes and the HTTPS site is live.
    2. Before enabling Android Verified App Links, obtain the SHA-256 fingerprint of the certificate that signs the actual installed/release FoodLens APK. The current Android Gradle config uses the debug signing config for release builds, so a stable production signing certificate must be configured before we publish an assetlinks.json association.
    3. Confirm a Puter-supported native authorization/session handoff. A static GitHub Pages site cannot securely exchange or store a Puter token by itself.

    No token handoff has been implemented or represented as working yet.

  8. CodeByArnob commented on Nov 6, 2026

    @CodeByArnob
    OwnerAuthor

    Updated authentication compatibility check (November 2026)

    I rechecked the current official Puter.js authentication reference.

    • puter.auth.signIn() is explicitly documented as a website-only popup flow.
    • It resolves with a SignInResult containing a bearer-style token, app_uid, and username.
    • The current public docs do not document a native Android redirect URI, authorization-code exchange, or PKCE flow for this sign-in method.

    Android custom URI schemes can be claimed by another installed app, so we will not pass a Puter token in a custom-scheme URL or query string. We also will not scrape Chrome cookies or treat opening puter.com/login as app authorization.

    Current safe next step

    The GitHub Pages origin is deployed, but its page remains a non-authenticating placeholder. We can prepare the Android callback plumbing and test deep-link routing independently, but that alone cannot establish a Puter session. The actual token/session handoff remains blocked until Puter confirms a supported native handoff, or we identify a supported browser-to-app channel that does not expose credentials to other apps.

    Please confirm whether Puter supports either:

    1. An official native-app authorization-code redirect with PKCE; or
    2. An origin-verified browser-to-native messaging channel for a website SignInResult, without placing the token in a URL or clipboard.

    No insecure callback has been implemented.

  9. CodeByArnob commented on Nov 6, 2026

    @CodeByArnob
    OwnerAuthor

    Further upstream research: Puter auth popup transport

    Additional upstream investigation found Puter issue HeyPuter/puter#1333. It documents that the current sign-in popup relies on window.opener to communicate its result back to the calling page. A maintainer discussion mentioned a possible WebSocket rendezvous design, but the issue was closed as "not planned" on 2026-03-30. This is not a documented public native SDK or supported Android OAuth contract.

    The related redirect issue HeyPuter/puter#1965 was closed as a duplicate. The issue page now references Android-related fixes in September 2026, but those references concern dropped-window / hung-page behavior; they do not document a public native redirect URI, PKCE code exchange, or stable app callback contract.

    Updated conclusion

    • A website-origin Puter sign-in page is viable for browser-based FoodLens web authentication.
    • A browser-to-native bridge is not yet a supported integration contract. Custom Tabs postMessage is an Android transport primitive, not proof that Puter's popup will deliver its result to it.
    • Verified App Links and origin-verified Custom Tabs messaging depend on Digital Asset Links and the installed APK signing certificate. A debug certificate can be used for a local debug-only experiment, but it is not a production identity and should not be published as the permanent association.
    • No Puter bearer token should be placed in an intent URL, query string, fragment, clipboard, or logs.

    Requested upstream confirmation

    Please advise whether Puter intends to expose a supported native mobile sign-in API or documented handoff contract (authorization code + PKCE, or an origin-verified message channel). Without that contract, FoodLens cannot truthfully complete automatic native session return using the public SDK alone.

  10. CodeByArnob commented on Nov 6, 2026

    @CodeByArnob
    OwnerAuthor

    Implementation decision: secure browser-to-app handoff

    I verified the current official Puter.js and Android browser contracts before changing the app:

    • Puter's documented puter.auth.signIn() is a website popup flow. It resolves a SignInResult in the calling web page; the docs do not define an Android redirect URI, authorization-code + PKCE contract, or native SDK callback.
    • Android Auth Tab can return a URI only when the authentication page navigates to a pre-registered redirect URI. That does not by itself expose the Puter popup's result to the Android app.
    • Passing a Puter bearer token in a deep-link URL, scraping Chrome cookies/storage, or accepting an unverified custom-scheme callback would expose credentials or allow app impersonation. I will not ship any of those shortcuts.

    Therefore PR #4 remains the safe first step (external browser launch), but it is not yet end-to-end authentication. The remaining blocker is a supported, secure Puter-to-native handoff contract. A zero-backend app cannot securely exchange a one-time opaque code for a Puter session unless Puter provides that native callback or a trusted relay.

    I am keeping the existing session/bridge implementation intact until a real end-to-end flow is possible. Acceptance test after the supported handoff exists: sign in and sign up in the device browser, return to FoodLens without pasting a token, verify the Puter user/session, perform an authenticated AI request, force-stop/reopen, and confirm session restoration.

  11. CodeByArnob commented on Nov 6, 2026

    @CodeByArnob
    OwnerAuthor

    Browser authentication test page is now deployed from the FoodLens Pages repository

    Added a dedicated test page at:
    https://codebyarnob.github.io/FoodLens/auth-test/

    It invokes the documented puter.auth.signIn({request_auth:true}) flow from a user click, then checks puter.auth.getUser(). It displays only the username and never displays, stores, logs, or transmits the session token.

    What this test proves: Puter browser sign-in can complete on the FoodLens HTTPS origin.

    What it does not prove: Android app session handoff or persistence. The public Puter docs still describe a website popup result, not a native Android callback/PKCE contract. I am not marking the app login complete or moving bearer tokens through a deep-link URL.

  12. CodeByArnob commented on Nov 6, 2026

    @CodeByArnob
    OwnerAuthor

    2026-11-06 implementation audit: secure handoff, encrypted storage, startup validation

    I inspected the current main implementation, including PuterBridgeService, AuthNotifier, LocalStorageService, PuterAuthWebViewScreen, the Android manifest and Gradle configuration.

    Verified current behavior / issues

    1. AuthNotifier._init() restores a cached user immediately from token + username in local storage, then asynchronously calls setAuthToken() and getUser(). It does not clear the cached identity if that validation fails. So the startup UI can temporarily (or indefinitely after a failed sync) show a stale signed-in user.
    2. LocalStorageService currently persists the Puter bearer token in SharedPreferences, not Android Keystore-backed encrypted storage.
    3. The legacy PuterAuthWebViewScreen attempts to read authentication cookies and scan Puter WebView localStorage for token-like values. This is not acceptable as the basis for a new external-browser flow and must be retired when the replacement is proven.
    4. Android manifest currently has no App Link / callback intent filter.
    5. The external browser test page successfully verified Puter browser sign-in, but it does not establish an app session.

    Secure implementation boundary

    The public Puter docs describe puter.auth.signIn() as a browser popup flow. I have not found a documented native redirect URI, authorization-code + PKCE exchange, or native Android callback contract. Android Custom Tabs postMessage is a browser/app channel, but it requires origin verification and a cooperating web page; it does not automatically make Puter's popup return a native session. We must not send a bearer token in a URL, scrape Chrome storage/cookies, or trust an unverified custom-scheme callback.

    Work plan

    • Move token persistence from SharedPreferences to Android encrypted secure storage, with one-time migration and deletion of the old preference key.
    • Make startup restore provisional only; validate the stored token against Puter before setting authenticated state, and clear invalid/expired credentials.
    • Add a browser-to-app handoff only after we have a supported Puter callback or a properly authenticated one-time relay. If a relay is required, it must be explicit because it introduces a backend and a token-handling trust boundary.
    • Keep the existing WebView/token-extraction path from being used as a fallback for external browser login until the new flow passes device testing.

    This is an audit and implementation plan, not a claim that the three requested features are already complete.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    androidAndroid platform integration & WebViewauthenticationAuthentication, OAuth, and Puter.js integrationenhancementNew feature or requestgood first issueGood for newcomershelp wantedExtra attention is needed

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions