mcias/proto/mcias/v1/auth.proto

// AuthService: login, logout, token renewal, and TOTP management.
syntax = "proto3";

package mcias.v1;

option go_package = "git.wntrmute.dev/kyle/mcias/gen/mcias/v1;mciasv1";

import "google/protobuf/timestamp.proto";

// --- Login ---

// LoginRequest carries username/password and an optional TOTP code.
// Security: never logged; password and totp_code must not appear in audit logs.
message LoginRequest {
  string username  = 1;
  string password  = 2;  // security: never logged or stored
  string totp_code = 3;  // optional; required if TOTP enrolled
}

// LoginResponse returns the signed JWT and its expiry time.
// Security: token is a bearer credential; the caller must protect it.
message LoginResponse {
  string token = 1;
  google.protobuf.Timestamp expires_at = 2;
}

// --- Logout ---

// LogoutRequest carries no body; the token is extracted from gRPC metadata.
message LogoutRequest {}

// LogoutResponse confirms the token has been revoked.
message LogoutResponse {}

// --- Token renewal ---

// RenewTokenRequest carries no body; the existing token is in metadata.
message RenewTokenRequest {}

// RenewTokenResponse returns a new JWT with a fresh expiry.
message RenewTokenResponse {
  string token = 1;
  google.protobuf.Timestamp expires_at = 2;
}

// --- TOTP enrollment ---

// EnrollTOTPRequest carries the current password for re-authentication.
// Security (SEC-01): password is required to prevent a stolen session token
// from being used to enroll attacker-controlled TOTP on the victim's account.
message EnrollTOTPRequest {
  string password = 1;  // security: current password required; never logged
}

// EnrollTOTPResponse returns the TOTP secret and otpauth URI for display.
// Security: the secret is shown once; it is stored only in encrypted form.
message EnrollTOTPResponse {
  string secret      = 1;  // base32-encoded; display once, then discard
  string otpauth_uri = 2;
}

// ConfirmTOTPRequest carries the TOTP code to confirm enrollment.
message ConfirmTOTPRequest {
  string code = 1;
}

// ConfirmTOTPResponse confirms TOTP enrollment is complete.
message ConfirmTOTPResponse {}

// RemoveTOTPRequest carries the target account ID (admin only).
message RemoveTOTPRequest {
  string account_id = 1;  // UUID of the account to remove TOTP from
}

// RemoveTOTPResponse confirms removal.
message RemoveTOTPResponse {}

// AuthService handles all authentication flows.
service AuthService {
  // Login authenticates with username+password (+optional TOTP) and returns a JWT.
  // Public RPC — no auth required.
  rpc Login(LoginRequest) returns (LoginResponse);

  // Logout revokes the caller's current token.
  // Requires: valid JWT in metadata.
  rpc Logout(LogoutRequest) returns (LogoutResponse);

  // RenewToken exchanges the caller's token for a fresh one.
  // Requires: valid JWT in metadata.
  rpc RenewToken(RenewTokenRequest) returns (RenewTokenResponse);

  // EnrollTOTP begins TOTP enrollment for the calling account.
  // Requires: valid JWT in metadata.
  rpc EnrollTOTP(EnrollTOTPRequest) returns (EnrollTOTPResponse);

  // ConfirmTOTP confirms TOTP enrollment with a code from the authenticator app.
  // Requires: valid JWT in metadata.
  rpc ConfirmTOTP(ConfirmTOTPRequest) returns (ConfirmTOTPResponse);

  // RemoveTOTP removes TOTP from an account (admin only).
  // Requires: admin JWT in metadata.
  rpc RemoveTOTP(RemoveTOTPRequest) returns (RemoveTOTPResponse);
}