User

Services

UserService Service

Service for user management and system initialization.

Provides basic functionality to retrieve user information and to perform the one-time initialization of the system to create the first root user.

Authentication: gRPC metadata authorization: Bearer <api-key> for all calls except InitializeSystem

Global errors: All RPCs may return DEADLINE_EXCEEDED, CANCELLED, UNAVAILABLE, RESOURCE_EXHAUSTED, INTERNAL.

Permissions model:

• *_USER_OWN: Operate on the caller's own user record
• *_USER_ANY: Operate on any user's record (requires elevated role)

GetUser

Retrieves user details based on a specified identifier.

Auth: gRPC metadata authorization: Bearer <api-key>

Permissions Required: DISPLAY_USER_OWN or DISPLAY_USER_ANY

Request (Lookup Logic):

• If neither user_id nor email is set: returns the authenticated user
• If user_id is set: looks up user by ID (highest priority)
• If email is set (and user_id is not): looks up user by email
• With DISPLAY_USER_OWN, any request for another user's data is denied

Side Effects: None (read-only operation)

Error Codes:

• UNAUTHENTICATED: Missing or invalid auth token
• PERMISSION_DENIED: Caller lacks DISPLAY_USER_* permission for the requested user
• INVALID_ARGUMENT: Invalid user_id format
• NOT_FOUND: No user exists for the given identifier
• INTERNAL: Unexpected server error

Idempotency: Read-only; safe to retry.

Examples:

grpcurl -plaintext \
-H 'authorization: Bearer <api-key>' \
-d '{ "user_id": "BASE64_ENCODED_UUID_HERE" }' \
localhost:8080 goodmem.v1.UserService/GetUser

InitializeSystem

Initializes the system with a root user and API key.

This is a one-time administrative operation that creates the initial system user. It can only be run successfully once. Subsequent calls will report that the system is already initialized.

Auth: None. This is the only method that does not require authentication.

Side Effects:

• On first run, creates a new root user and an associated API key.

Idempotency:

• Idempotent. The first call performs initialization; subsequent calls do nothing and return a response indicating the system was already initialized.

Error Codes:

• INTERNAL: Unexpected server error during the initialization process.

Note: ALREADY_EXISTS is not returned as a status code; it is indicated by the already_initialized field in the response.

Examples:

grpcurl -plaintext -d '{}' localhost:8080 goodmem.v1.UserService/InitializeSystem

Messages

User

Represents a user in the GoodMem system.

A user is the core entity for ownership and permissions. All fields are output-only as user management is currently handled outside of this basic service.

Notes:

• All timestamps are UTC (google.protobuf.Timestamp).
• Sensitive information like password hashes is never exposed.

GetUserRequest

Request message for the GetUser RPC.

Specifies the identifier for the user to retrieve. See the GetUser RPC documentation for the detailed lookup logic.

InitializeSystemRequest

Request message for the InitializeSystem RPC.

This request is empty as the operation requires no parameters. Empty request as no parameters are needed

InitializeSystemResponse

Response message for the InitializeSystem RPC.

Reports the result of the initialization, indicating whether it was performed on this call or had been done previously.