refactor: user auth improvements (#5360)

Author: johnnyjoygh

.gitignore

@@ -7,6 +7,10 @@ web/dist
 # Build artifacts
 build/
 bin/
+memos
+
+# Plan/design documents
+docs/plans/
 
 .DS_Store
 

proto/api/v1/auth_service.proto

@@ -11,87 +11,104 @@ import "google/protobuf/timestamp.proto";
 option go_package = "gen/api/v1";
 
 service AuthService {
-  // GetCurrentSession returns the current active session information.
-  // This method is idempotent and safe, suitable for checking current session state.
-  rpc GetCurrentSession(GetCurrentSessionRequest) returns (GetCurrentSessionResponse) {
-    option (google.api.http) = {get: "/api/v1/auth/sessions/current"};
+  // GetCurrentUser returns the authenticated user's information.
+  // Validates the access token and returns user details.
+  // Similar to OIDC's /userinfo endpoint.
+  rpc GetCurrentUser(GetCurrentUserRequest) returns (GetCurrentUserResponse) {
+    option (google.api.http) = {get: "/api/v1/auth/me"};
   }
 
-  // CreateSession authenticates a user and creates a new session.
-  // Returns the authenticated user information upon successful authentication.
-  rpc CreateSession(CreateSessionRequest) returns (CreateSessionResponse) {
+  // SignIn authenticates a user with credentials and returns tokens.
+  // On success, returns an access token and sets a refresh token cookie.
+  // Supports password-based and SSO authentication methods.
+  rpc SignIn(SignInRequest) returns (SignInResponse) {
     option (google.api.http) = {
-      post: "/api/v1/auth/sessions"
+      post: "/api/v1/auth/signin"
       body: "*"
     };
   }
 
-  // DeleteSession terminates the current user session.
-  // This is an idempotent operation that invalidates the user's authentication.
-  rpc DeleteSession(DeleteSessionRequest) returns (google.protobuf.Empty) {
-    option (google.api.http) = {delete: "/api/v1/auth/sessions/current"};
+  // SignOut terminates the user's authentication.
+  // Revokes the refresh token and clears the authentication cookie.
+  rpc SignOut(SignOutRequest) returns (google.protobuf.Empty) {
+    option (google.api.http) = {post: "/api/v1/auth/signout"};
+  }
+
+  // RefreshToken exchanges a valid refresh token for a new access token.
+  // The refresh token is read from the HttpOnly cookie.
+  // Returns a new short-lived access token.
+  rpc RefreshToken(RefreshTokenRequest) returns (RefreshTokenResponse) {
+    option (google.api.http) = {
+      post: "/api/v1/auth/refresh"
+      body: "*"
+    };
   }
 }
 
-message GetCurrentSessionRequest {}
+message GetCurrentUserRequest {}
 
-message GetCurrentSessionResponse {
+message GetCurrentUserResponse {
+  // The authenticated user's information.
   User user = 1;
-
-  // Last time the session was accessed.
-  // Used for sliding expiration calculation (last_accessed_time + 2 weeks).
-  google.protobuf.Timestamp last_accessed_at = 2;
 }
 
-message CreateSessionRequest {
+message SignInRequest {
   // Nested message for password-based authentication credentials.
   message PasswordCredentials {
     // The username to sign in with.
-    // Required field for password-based authentication.
     string username = 1 [(google.api.field_behavior) = REQUIRED];
 
     // The password to sign in with.
-    // Required field for password-based authentication.
     string password = 2 [(google.api.field_behavior) = REQUIRED];
   }
 
   // Nested message for SSO authentication credentials.
   message SSOCredentials {
     // The ID of the SSO provider.
-    // Required field to identify the SSO provider.
     int32 idp_id = 1 [(google.api.field_behavior) = REQUIRED];
 
     // The authorization code from the SSO provider.
-    // Required field for completing the SSO flow.
     string code = 2 [(google.api.field_behavior) = REQUIRED];
 
     // The redirect URI used in the SSO flow.
-    // Required field for security validation.
     string redirect_uri = 3 [(google.api.field_behavior) = REQUIRED];
 
     // The PKCE code verifier for enhanced security (RFC 7636).
-    // Optional field - if provided, enables PKCE flow protection against authorization code interception.
+    // Optional - enables PKCE flow protection against authorization code interception.
     string code_verifier = 4 [(google.api.field_behavior) = OPTIONAL];
   }
 
-  // Provide one authentication method (username/password or SSO).
-  // Required field to specify the authentication method.
+  // Authentication credentials. Provide one method.
   oneof credentials {
-    // Username and password authentication method.
+    // Username and password authentication.
     PasswordCredentials password_credentials = 1;
 
-    // SSO provider authentication method.
+    // SSO provider authentication.
     SSOCredentials sso_credentials = 2;
   }
 }
 
-message CreateSessionResponse {
-  // The authenticated user information.
+message SignInResponse {
+  // The authenticated user's information.
   User user = 1;
 
-  // Last time the session was accessed.
-  // Used for sliding expiration calculation (last_accessed_time + 2 weeks).
-  google.protobuf.Timestamp last_accessed_at = 2;
+  // The short-lived access token for API requests.
+  // Store in memory only, not in localStorage.
+  string access_token = 2;
+
+  // When the access token expires.
+  // Client should call RefreshToken before this time.
+  google.protobuf.Timestamp access_token_expires_at = 3;
 }
 
-message DeleteSessionRequest {}
+message SignOutRequest {}
+
+message RefreshTokenRequest {}
+
+message RefreshTokenResponse {
+  // The new short-lived access token.
+  string access_token = 1;
+
+  // When the access token expires.
+  google.protobuf.Timestamp expires_at = 2;
+}

proto/api/v1/user_service.proto

@@ -84,35 +84,39 @@ service UserService {
     option (google.api.method_signature) = "parent";
   }
 
-  // ListUserAccessTokens returns a list of access tokens for a user.
-  rpc ListUserAccessTokens(ListUserAccessTokensRequest) returns (ListUserAccessTokensResponse) {
-    option (google.api.http) = {get: "/api/v1/{parent=users/*}/accessTokens"};
+  // ListPersonalAccessTokens returns a list of Personal Access Tokens (PATs) for a user.
+  // PATs are long-lived tokens for API/script access, distinct from short-lived JWT access tokens.
+  rpc ListPersonalAccessTokens(ListPersonalAccessTokensRequest) returns (ListPersonalAccessTokensResponse) {
+    option (google.api.http) = {get: "/api/v1/{parent=users/*}/personalAccessTokens"};
     option (google.api.method_signature) = "parent";
   }
 
-  // CreateUserAccessToken creates a new access token for a user.
-  rpc CreateUserAccessToken(CreateUserAccessTokenRequest) returns (UserAccessToken) {
+  // CreatePersonalAccessToken creates a new Personal Access Token for a user.
+  // The token value is only returned once upon creation.
+  rpc CreatePersonalAccessToken(CreatePersonalAccessTokenRequest) returns (CreatePersonalAccessTokenResponse) {
     option (google.api.http) = {
-      post: "/api/v1/{parent=users/*}/accessTokens"
-      body: "access_token"
+      post: "/api/v1/{parent=users/*}/personalAccessTokens"
+      body: "*"
     };
-    option (google.api.method_signature) = "parent,access_token";
   }
 
-  // DeleteUserAccessToken deletes an access token.
-  rpc DeleteUserAccessToken(DeleteUserAccessTokenRequest) returns (google.protobuf.Empty) {
-    option (google.api.http) = {delete: "/api/v1/{name=users/*/accessTokens/*}"};
+  // DeletePersonalAccessToken deletes a Personal Access Token.
+  rpc DeletePersonalAccessToken(DeletePersonalAccessTokenRequest) returns (google.protobuf.Empty) {
+    option (google.api.http) = {delete: "/api/v1/{name=users/*/personalAccessTokens/*}"};
     option (google.api.method_signature) = "name";
   }
 
-  // ListUserSessions returns a list of active sessions for a user.
-  rpc ListUserSessions(ListUserSessionsRequest) returns (ListUserSessionsResponse) {
+  // ListSessions returns a list of active login sessions for a user.
+  // Each session represents a browser/device where the user is logged in.
+  // Sessions are backed by refresh tokens with sliding expiration.
+  rpc ListSessions(ListSessionsRequest) returns (ListSessionsResponse) {
     option (google.api.http) = {get: "/api/v1/{parent=users/*}/sessions"};
     option (google.api.method_signature) = "parent";
   }
 
-  // RevokeUserSession revokes a specific session for a user.
-  rpc RevokeUserSession(RevokeUserSessionRequest) returns (google.protobuf.Empty) {
+  // RevokeSession revokes a specific login session.
+  // This invalidates the refresh token, forcing re-authentication on that device.
+  rpc RevokeSession(RevokeSessionRequest) returns (google.protobuf.Empty) {
     option (google.api.http) = {delete: "/api/v1/{name=users/*/sessions/*}"};
     option (google.api.method_signature) = "name";
   }
@@ -398,9 +402,9 @@ message UserSetting {
     KEY_UNSPECIFIED = 0;
     // GENERAL is the key for general user settings.
     GENERAL = 1;
-    // SESSIONS is the key for user authentication sessions.
+    // SESSIONS is the key for user login sessions (refresh tokens).
     SESSIONS = 2;
-    // ACCESS_TOKENS is the key for access tokens.
+    // ACCESS_TOKENS is the key for Personal Access Tokens (PATs).
     ACCESS_TOKENS = 3;
     // WEBHOOKS is the key for user webhooks.
     WEBHOOKS = 4;
@@ -420,14 +424,14 @@ message UserSetting {
 
   // User authentication sessions configuration.
   message SessionsSetting {
-    // List of active user sessions.
-    repeated UserSession sessions = 1;
+    // List of active login sessions.
+    repeated Session sessions = 1;
   }
 
-  // User access tokens configuration.
+  // Personal access tokens configuration.
   message AccessTokensSetting {
-    // List of user access tokens.
-    repeated UserAccessToken access_tokens = 1;
+    // List of personal access tokens (PATs).
+    repeated PersonalAccessToken personal_access_tokens = 1;
   }
 
   // User webhooks configuration.
@@ -487,85 +491,97 @@ message ListUserSettingsResponse {
   int32 total_size = 3;
 }
 
-// User access token message
-message UserAccessToken {
+// PersonalAccessToken represents a long-lived token for API/script access.
+// PATs are distinct from short-lived JWT access tokens used for session authentication.
+message PersonalAccessToken {
   option (google.api.resource) = {
-    type: "memos.api.v1/UserAccessToken"
-    pattern: "users/{user}/accessTokens/{access_token}"
-    singular: "userAccessToken"
-    plural: "userAccessTokens"
+    type: "memos.api.v1/PersonalAccessToken"
+    pattern: "users/{user}/personalAccessTokens/{personal_access_token}"
+    singular: "personalAccessToken"
+    plural: "personalAccessTokens"
   };
 
-  // The resource name of the access token.
-  // Format: users/{user}/accessTokens/{access_token}
+  // The resource name of the personal access token.
+  // Format: users/{user}/personalAccessTokens/{personal_access_token}
   string name = 1 [(google.api.field_behavior) = IDENTIFIER];
 
-  // Output only. The access token value.
-  string access_token = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
+  // The description of the token.
+  string description = 2 [(google.api.field_behavior) = OPTIONAL];
 
-  // The description of the access token.
-  string description = 3 [(google.api.field_behavior) = OPTIONAL];
-
-  // Output only. The issued timestamp.
-  google.protobuf.Timestamp issued_at = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
+  // Output only. The creation timestamp.
+  google.protobuf.Timestamp created_at = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
 
   // Optional. The expiration timestamp.
-  google.protobuf.Timestamp expires_at = 5 [(google.api.field_behavior) = OPTIONAL];
+  google.protobuf.Timestamp expires_at = 4 [(google.api.field_behavior) = OPTIONAL];
+
+  // Output only. The last used timestamp.
+  google.protobuf.Timestamp last_used_at = 5 [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
-message ListUserAccessTokensRequest {
-  // Required. The parent resource whose access tokens will be listed.
+message ListPersonalAccessTokensRequest {
+  // Required. The parent resource whose personal access tokens will be listed.
   // Format: users/{user}
   string parent = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {type: "memos.api.v1/User"}
   ];
 
-  // Optional. The maximum number of access tokens to return.
+  // Optional. The maximum number of tokens to return.
   int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];
 
   // Optional. A page token for pagination.
   string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
 }
 
-message ListUserAccessTokensResponse {
-  // The list of access tokens.
-  repeated UserAccessToken access_tokens = 1;
+message ListPersonalAccessTokensResponse {
+  // The list of personal access tokens.
+  repeated PersonalAccessToken personal_access_tokens = 1;
 
   // A token for the next page of results.
   string next_page_token = 2;
 
-  // The total count of access tokens.
+  // The total count of personal access tokens.
   int32 total_size = 3;
 }
 
-message CreateUserAccessTokenRequest {
-  // Required. The parent resource where this access token will be created.
+message CreatePersonalAccessTokenRequest {
+  // Required. The parent resource where this token will be created.
   // Format: users/{user}
   string parent = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {type: "memos.api.v1/User"}
   ];
 
-  // Required. The access token to create.
-  UserAccessToken access_token = 2 [(google.api.field_behavior) = REQUIRED];
+  // Optional. Description of the personal access token.
+  string description = 2 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Expiration duration in days (0 = never expires).
+  int32 expires_in_days = 3 [(google.api.field_behavior) = OPTIONAL];
+}
+
+message CreatePersonalAccessTokenResponse {
+  // The personal access token metadata.
+  PersonalAccessToken personal_access_token = 1;
 
-  // Optional. The access token ID to use.
-  string access_token_id = 3 [(google.api.field_behavior) = OPTIONAL];
+  // The actual token value - only returned on creation.
+  // This is the only time the token value will be visible.
+  string token = 2;
 }
 
-message DeleteUserAccessTokenRequest {
-  // Required. The resource name of the access token to delete.
-  // Format: users/{user}/accessTokens/{access_token}
+message DeletePersonalAccessTokenRequest {
+  // Required. The resource name of the personal access token to delete.
+  // Format: users/{user}/personalAccessTokens/{personal_access_token}
   string name = 1 [
     (google.api.field_behavior) = REQUIRED,
-    (google.api.resource_reference) = {type: "memos.api.v1/UserAccessToken"}
+    (google.api.resource_reference) = {type: "memos.api.v1/PersonalAccessToken"}
   ];
 }
 
-message UserSession {
+// Session represents a user's login session on a specific device/browser.
+// Sessions are backed by refresh tokens with sliding expiration.
+message Session {
   option (google.api.resource) = {
-    type: "memos.api.v1/UserSession"
+    type: "memos.api.v1/Session"
     pattern: "users/{user}/sessions/{session}"
     name_field: "name"
   };
@@ -605,7 +621,7 @@ message UserSession {
   }
 }
 
-message ListUserSessionsRequest {
+message ListSessionsRequest {
   // Required. The resource name of the parent.
   // Format: users/{user}
   string parent = 1 [
@@ -614,12 +630,12 @@ message ListUserSessionsRequest {
   ];
 }
 
-message ListUserSessionsResponse {
-  // The list of user sessions.
-  repeated UserSession sessions = 1;
+message ListSessionsResponse {
+  // The list of sessions.
+  repeated Session sessions = 1;
 }
 
-message RevokeUserSessionRequest {
+message RevokeSessionRequest {
   // The name of the session to revoke.
   // Format: users/{user}/sessions/{session}
   string name = 1 [(google.api.field_behavior) = REQUIRED];