Add JWT authentication debugging and plaintext auth support

This commit introduces comprehensive JWT debugging capabilities and experimental
plaintext authentication support to help developers troubleshoot authentication issues.

**New Features:**
- getUserIdentityDebug() method returns detailed error information when JWT validation fails
- getUserIdentityInsecure() method for accessing raw plaintext tokens (development/debugging only)
- setAuthInsecure() client method for plaintext authentication mode

**Backend Implementation:**
- New 1.0/getUserIdentityDebug and 1.0/getUserIdentityInsecure syscalls in Rust
- PlaintextUser identity type added to authentication system
- Enhanced error metadata for JWT validation failures

**Frontend Integration:**
- TypeScript Auth interface extended with new debug methods
- React client support for plaintext authentication mode
- WebSocket protocol updates for plaintext token handling

**Backward Compatibility:**
- Existing getUserIdentity() method unchanged
- All current authentication flows continue to work
- New features are opt-in and don't affect existing implementations

This implementation enables developers to get detailed JWT error messages instead of
generic authentication failures, significantly improving the debugging experience
for authentication issues.

Author: graham

crates/application/src/lib.rs

@@ -2808,6 +2808,11 @@ impl<RT: Runtime> Application<RT> {
 
                 Identity::user(identity_result?)
             },
+            AuthenticationToken::PlaintextUser(token) => {
+                // For plaintext authentication, create a PlaintextUser identity
+                // The server is responsible for validating the token
+                Identity::PlaintextUser(token)
+            },
             AuthenticationToken::None => Identity::Unknown(None),
         };
         Ok(identity)

crates/authentication/src/lib.rs

@@ -131,6 +131,7 @@ pub fn token_to_authorization_header(token: AuthenticationToken) -> anyhow::Resu
             None => Ok(Some(format!("Convex {key}"))),
         },
         AuthenticationToken::User(key) => Ok(Some(format!("Bearer {key}"))),
+        AuthenticationToken::PlaintextUser(key) => Ok(Some(format!("Bearer {key}"))),
         AuthenticationToken::None => Ok(None),
     }
 }

crates/convex/sync_types/src/json.rs

@@ -155,6 +155,9 @@ enum AuthenticationTokenJson {
     User {
         value: String,
     },
+    PlaintextUser {
+        value: String,
+    },
     None,
 }
 
@@ -282,6 +285,13 @@ impl TryFrom<ClientMessage> for JsonValue {
                 base_version,
                 token: AuthenticationTokenJson::User { value },
             },
+            ClientMessage::Authenticate {
+                base_version,
+                token: AuthenticationToken::PlaintextUser(value),
+            } => ClientMessageJson::Authenticate {
+                base_version,
+                token: AuthenticationTokenJson::PlaintextUser { value },
+            },
             ClientMessage::Authenticate {
                 base_version,
                 token: AuthenticationToken::None,
@@ -374,6 +384,9 @@ impl TryFrom<JsonValue> for ClientMessage {
                         )
                     },
                     AuthenticationTokenJson::User { value } => AuthenticationToken::User(value),
+                    AuthenticationTokenJson::PlaintextUser { value } => {
+                        AuthenticationToken::PlaintextUser(value)
+                    },
                     AuthenticationTokenJson::None => AuthenticationToken::None,
                 },
             },

crates/convex/sync_types/src/types.rs

@@ -252,6 +252,8 @@ pub enum AuthenticationToken {
     Admin(String, Option<UserIdentityAttributes>),
     /// OpenID Connect JWT
     User(String),
+    /// Plaintext authentication token (no JWT validation)
+    PlaintextUser(String),
     #[default]
     /// Logged out.
     None,

crates/isolate/src/environment/udf/async_syscall.rs

@@ -696,6 +696,12 @@ impl<RT: Runtime, P: AsyncSyscallProvider<RT>> DatabaseSyscallsV1<RT, P> {
                     "1.0/getUserIdentity" => {
                         Box::pin(Self::get_user_identity(provider, args)).await
                     },
+                    "1.0/getUserIdentityDebug" => {
+                        Box::pin(Self::get_user_identity_debug(provider, args)).await
+                    },
+                    "1.0/getUserIdentityInsecure" => {
+                        Box::pin(Self::get_user_identity_insecure(provider, args)).await
+                    },
                     // Storage
                     "1.0/storageDelete" => Box::pin(Self::storage_delete(provider, args)).await,
                     "1.0/storageGetMetadata" => {
@@ -788,6 +794,60 @@ impl<RT: Runtime, P: AsyncSyscallProvider<RT>> DatabaseSyscallsV1<RT, P> {
         Ok(JsonValue::Null)
     }
 
+    #[convex_macro::instrument_future]
+    async fn get_user_identity_debug(
+        provider: &mut P,
+        _args: JsonValue,
+    ) -> anyhow::Result<JsonValue> {
+        provider.observe_identity()?;
+        let component = provider.component()?;
+        let tx = provider.tx()?;
+        let user_identity = tx.user_identity();
+
+        if !component.is_root() {
+            log_component_get_user_identity(user_identity.is_some());
+        }
+
+        // If we have a valid user identity, return it
+        if let Some(user_identity) = user_identity {
+            return user_identity.try_into();
+        }
+
+        // If no user identity, check if we have error details from JWT validation
+        let identity = tx.identity();
+        if let keybroker::Identity::Unknown(Some(error_metadata)) = identity {
+            // Create a structured error response with details for debugging
+            let error_response = json!({
+                "error": {
+                    "code": error_metadata.short_msg,
+                    "message": error_metadata.msg,
+                    "details": "JWT validation failed. Check your token format, expiration, issuer, and audience claims."
+                }
+            });
+            return Ok(error_response);
+        }
+
+        // No identity provided (not an error case)
+        Ok(JsonValue::Null)
+    }
+
+    #[convex_macro::instrument_future]
+    async fn get_user_identity_insecure(
+        provider: &mut P,
+        _args: JsonValue,
+    ) -> anyhow::Result<JsonValue> {
+        let tx = provider.tx()?;
+        let identity = tx.identity();
+
+        // Return the plaintext token if this is a PlaintextUser identity
+        if let keybroker::Identity::PlaintextUser(token) = identity {
+            return Ok(JsonValue::String(token.clone()));
+        }
+
+        // Return null for any other identity type (including regular User identities)
+        Ok(JsonValue::Null)
+    }
+
     #[convex_macro::instrument_future]
     async fn storage_generate_upload_url(
         provider: &mut P,

crates/keybroker/src/broker.rs

@@ -65,6 +65,7 @@ use pb::{
     convex_identity::{
         unchecked_identity::Identity as UncheckedIdentityProto,
         ActingUser,
+        PlaintextUserIdentity,
         UnknownIdentity,
     },
     convex_keys::{
@@ -144,6 +145,8 @@ pub enum Identity {
     // ActingUser keeps track of the ID of the admin acting as a user,
     // and that user's fake attributes
     ActingUser(AdminIdentity, UserIdentityAttributes),
+    // PlaintextUser holds a plaintext authentication token for server-side validation
+    PlaintextUser(String),
     // Unknown(None) means no identity was provided.
     // Unknown(Some(error_message)) means an error occurred while parsing the identity.
     // We allow the request to go through, but keep the error to throw when code tries to
@@ -159,6 +162,7 @@ impl From<Identity> for AuthenticationToken {
                 AuthenticationToken::Admin(identity.key, Some(user))
             },
             Identity::InstanceAdmin(identity) => AuthenticationToken::Admin(identity.key, None),
+            Identity::PlaintextUser(token) => AuthenticationToken::PlaintextUser(token),
             _ => AuthenticationToken::None,
         }
     }
@@ -180,6 +184,11 @@ impl From<Identity> for pb::convex_identity::UncheckedIdentity {
                     attributes: Some(attributes.into()),
                 })
             },
+            Identity::PlaintextUser(token) => {
+                UncheckedIdentityProto::PlaintextUserIdentity(PlaintextUserIdentity {
+                    token: Some(token),
+                })
+            },
             Identity::Unknown(error_message) => UncheckedIdentityProto::Unknown(UnknownIdentity {
                 error_message: error_message.map(|e| e.into()),
             }),
@@ -216,6 +225,10 @@ impl Identity {
                     attributes.ok_or_else(|| anyhow::anyhow!("Missing user attributes"))?;
                 Ok(Identity::ActingUser(admin_identity, attributes.try_into()?))
             },
+            UncheckedIdentityProto::PlaintextUserIdentity(PlaintextUserIdentity { token }) => {
+                let token = token.ok_or_else(|| anyhow::anyhow!("Missing plaintext token"))?;
+                Ok(Identity::PlaintextUser(token))
+            },
             UncheckedIdentityProto::Unknown(UnknownIdentity { error_message }) => Ok(
                 Identity::Unknown(error_message.map(|e| e.try_into()).transpose()?),
             ),
@@ -252,6 +265,7 @@ impl From<Identity> for InertIdentity {
             Identity::InstanceAdmin(i) => InertIdentity::InstanceAdmin(i.instance_name),
             Identity::System(_) => InertIdentity::System,
             Identity::Unknown(_) => InertIdentity::Unknown,
+            Identity::PlaintextUser(_) => InertIdentity::Unknown,
             Identity::User(user) => InertIdentity::User(user.attributes.token_identifier),
             Identity::ActingUser(identity, user) => match identity.principal {
                 AdminIdentityPrincipal::Member(member_id) => {
@@ -273,6 +287,7 @@ impl PartialEq for Identity {
             (Self::User(l), Self::User(r)) => {
                 l.attributes.token_identifier == r.attributes.token_identifier
             },
+            (Self::PlaintextUser(l), Self::PlaintextUser(r)) => l == r,
             (Self::Unknown(_), Self::Unknown(_)) => true,
             (
                 Self::ActingUser(l_admin_identity, l_attributes),
@@ -281,6 +296,7 @@ impl PartialEq for Identity {
             (Self::InstanceAdmin(_), _)
             | (Self::System(_), _)
             | (Self::User(_), _)
+            | (Self::PlaintextUser(_), _)
             | (Self::Unknown(_), _)
             | (Self::ActingUser(..), _) => false,
         }
@@ -297,6 +313,7 @@ impl Identity {
             Identity::Unknown(error_message) => {
                 IdentityCacheKey::Unknown(error_message.map(|e| e.to_string()))
             },
+            Identity::PlaintextUser(_) => IdentityCacheKey::Unknown(None),
             Identity::User(user) => IdentityCacheKey::User(user.attributes),
             // Identity of the impersonator not relevant for caching. Only the one being
             // impersonated.

crates/local_backend/src/admin.rs

@@ -67,7 +67,10 @@ fn must_be_admin_internal(
     let admin_identity = match identity {
         Identity::InstanceAdmin(admin_identity) => admin_identity,
         Identity::ActingUser(admin_identity, _user_identity_attributes) => admin_identity,
-        Identity::System(_) | Identity::User(_) | Identity::Unknown(_) => {
+        Identity::System(_)
+        | Identity::User(_)
+        | Identity::PlaintextUser(_)
+        | Identity::Unknown(_) => {
             return Err(bad_admin_key_error(identity.instance_name()).into());
         },
     };

crates/pb/protos/convex_identity.proto

@@ -9,6 +9,7 @@ message AuthenticationToken {
   oneof identity  {
     AdminAuthenticationToken admin = 1;
     string user = 2;
+    string plaintext_user = 4;
     google.protobuf.Empty none = 3;
   }
 }
@@ -26,13 +27,18 @@ message UncheckedIdentity {
     UserIdentity user_identity = 3;   
     ActingUser acting_user = 4;
     UnknownIdentity unknown = 5;
+    PlaintextUserIdentity plaintext_user_identity = 6;
   }
 }
 
 message UnknownIdentity {
   optional errors.ErrorMetadata error_message = 1;
 }
 
+message PlaintextUserIdentity {
+  optional string token = 1;
+}
+
 message AdminIdentity {
   optional string instance_name = 1;
   optional string key = 3;

crates/pb/src/authentication_token.rs

@@ -23,6 +23,9 @@ impl TryFrom<crate::convex_identity::AuthenticationToken> for AuthenticationToke
                 AuthenticationToken::Admin(key, acting_as)
             },
             AuthenticationTokenProto::User(token) => AuthenticationToken::User(token),
+            AuthenticationTokenProto::PlaintextUser(token) => {
+                AuthenticationToken::PlaintextUser(token)
+            },
             AuthenticationTokenProto::None(_) => AuthenticationToken::None,
         };
         Ok(token)
@@ -40,6 +43,9 @@ impl From<AuthenticationToken> for crate::convex_identity::AuthenticationToken {
                 })
             },
             AuthenticationToken::User(token) => AuthenticationTokenProto::User(token),
+            AuthenticationToken::PlaintextUser(token) => {
+                AuthenticationTokenProto::PlaintextUser(token)
+            },
             AuthenticationToken::None => AuthenticationTokenProto::None(()),
         };
         Self {

npm-packages/convex/src/browser/index.ts

@@ -23,6 +23,7 @@ export type {
   SubscribeOptions,
   ConnectionState,
   AuthTokenFetcher,
+  PlaintextAuthTokenFetcher,
 } from "./sync/client.js";
 export type { ConvexClientOptions } from "./simple_client.js";
 export { ConvexClient } from "./simple_client.js";