Skip to content

armgit / memos

Public Imported from GitHub
0

Memos is an open-source, self-hosted note-taking app that brings your everyday thoughts together in a personal timeline. Your data stays yours, and you choose what to keep private or share.

4.6 KB
Raw Blame
syntax = "proto3";

package memos.api;

import "api/user_service.proto";
import "google/api/annotations.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/timestamp.proto";

option go_package = "gen/api";

// AuthService manages sign-in sessions: it issues, refreshes, and revokes the tokens that authenticate API calls.
service AuthService {
  // SignIn authenticates a user with password or SSO credentials.
  // On success, returns a short-lived access token and sets a refresh token in an HttpOnly cookie.
  // Public. Attempts are rate limited. Archived users cannot sign in.
  rpc SignIn(SignInRequest) returns (SignInResponse) {
    option (google.api.http) = {
      post: "/api/auth/signin"
      body: "*"
    };
  }

  // RefreshToken exchanges the refresh token for a new access token.
  // The refresh token is read from the HttpOnly cookie and rotated: the old token is revoked and a new one with a
  // fresh 30-day expiry is set in the cookie.
  // Public, so it can be called after the access token has expired.
  rpc RefreshToken(RefreshTokenRequest) returns (RefreshTokenResponse) {
    option (google.api.http) = {
      post: "/api/auth/refresh"
      body: "*"
    };
  }

  // GetCurrentUser returns the authenticated user, similar to OIDC's /userinfo endpoint.
  // When the caller is not signed in or the account is no longer active, clears the refresh token cookie and returns
  // UNAUTHENTICATED.
  rpc GetCurrentUser(GetCurrentUserRequest) returns (GetCurrentUserResponse) {
    option (google.api.http) = {get: "/api/auth/me"};
  }

  // SignOut ends the current session.
  // Revokes the refresh token from the cookie and clears the cookie.
  rpc SignOut(SignOutRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {post: "/api/auth/signout"};
  }
}

// Request message for AuthService.SignIn.
message SignInRequest {
  // The credentials to authenticate with. Provide exactly one.
  oneof credentials {
    // Username and password credentials.
    PasswordCredentials password_credentials = 1;

    // SSO credentials from an OAuth2 authorization code flow.
    SsoCredentials sso_credentials = 2;
  }

  // PasswordCredentials are a username and password.
  // Regular users cannot use them when the instance disallows password sign-in.
  message PasswordCredentials {
    // Required. The username to sign in with.
    string username = 1 [(google.api.field_behavior) = REQUIRED];

    // Required. The password to sign in with.
    string password = 2 [(google.api.field_behavior) = REQUIRED];
  }

  // SsoCredentials are the result of an OAuth2 authorization code flow with an identity provider.
  // A first sign-in creates a local user unless the instance disallows user registration.
  message SsoCredentials {
    // Required. The resource name of the identity provider.
    // Format: identity-providers/{idp}
    string identity_provider = 1 [
      (google.api.field_behavior) = REQUIRED,
      (google.api.resource_reference) = {type: "memos.api/IdentityProvider"}
    ];

    // Required. The authorization code returned by the identity provider.
    string code = 2 [(google.api.field_behavior) = REQUIRED];

    // Required. The redirect URI used in the authorization request.
    string redirect_uri = 3 [(google.api.field_behavior) = REQUIRED];

    // Optional. The PKCE code verifier (RFC 7636). Set it when the authorization request used a code challenge.
    string code_verifier = 4 [(google.api.field_behavior) = OPTIONAL];
  }
}

// Response message for AuthService.SignIn.
message SignInResponse {
  // The signed-in user.
  User user = 1;

  // The short-lived access token for API requests.
  // Keep it in memory only, not in localStorage.
  string access_token = 2;

  // When the access token expires.
  // Call RefreshToken before this time.
  google.protobuf.Timestamp access_token_expire_time = 3;
}

// Request message for AuthService.RefreshToken.
// It has no fields: the refresh token is read from the HttpOnly cookie.
message RefreshTokenRequest {}

// Response message for AuthService.RefreshToken.
message RefreshTokenResponse {
  // The new short-lived access token.
  string access_token = 1;

  // When the new access token expires.
  google.protobuf.Timestamp access_token_expire_time = 2;
}

// Request message for AuthService.GetCurrentUser.
message GetCurrentUserRequest {}

// Response message for AuthService.GetCurrentUser.
message GetCurrentUserResponse {
  // The authenticated user.
  User user = 1;
}

// Request message for AuthService.SignOut.
message SignOutRequest {}