User

Services

UserService Service

Manages human-user lifecycle and preserves the provisioning-only initialization entry point.

Authentication: gRPC metadata x-api-key: <api-key> for every RPC except CompleteUserEnrollment and InitializeSystem. Completion authenticates one narrowly scoped enrollment credential inside its transaction; initialization is available only through the singleton bootstrap state.

Authorization Model:

• Each protected RPC evaluates a typed operation against the singleton instance or target user.
• Role names are not interpreted by this service.
• Creating a user never creates a credential, grant, authentication mapping, or role assignment.

Global Errors: All RPCs may return DEADLINE_EXCEEDED, CANCELLED, UNAVAILABLE, RESOURCE_EXHAUSTED, or INTERNAL in addition to their operation-specific errors.

CreateUser

Creates a dormant human user without creating credentials or assigning roles.

Auth: gRPC metadata x-api-key: <api-key>

Authorization Required: Instance-wide CREATE_USER with an ANY selector.

Request Behavior:

• email is required, nonblank, at most 255 characters, and globally unique, including among deleted users. It is treated as an identifier rather than subjected to a restrictive email syntax check.
• username is optional and globally unique when present.
• display_name and labels are optional profile metadata.
• The server generates user_id when the caller omits it.

Response: The newly created User, including lifecycle and audit metadata. No credential material is returned.

Side Effects:

• Atomically creates the durable HUMAN principal and its human-profile row.
• Records the exact authenticated principal or API key as the audit actor.
• Does not create an API key, role assignment, direct grant, or authentication mapping.

Error Codes:

• UNAUTHENTICATED: Missing or invalid authentication.
• INVALID_ARGUMENT: Malformed UUID; blank or overlong email; invalid profile field or labels.
• PERMISSION_DENIED: Caller lacks instance-wide CREATE_USER ANY.
• ALREADY_EXISTS: The UUID, email, or username is already occupied.
• INTERNAL: Unexpected server or database failure.

Idempotency: Not inherently idempotent. When a caller supplies user_id, a retry after a successful creation returns ALREADY_EXISTS because that durable UUID remains occupied.

Examples:

grpcurl -plaintext \
-H 'x-api-key: <api-key>' \
-d '{
"email": "[email protected]",
"username": "avery",
"display_name": "Avery Person",
"labels": { "team": "platform" }
}' \
localhost:8080 goodmem.v1.UserService/CreateUser

GetUser

Retrieves one human user by UUID, email, username, or the current request principal.

Auth: gRPC metadata x-api-key: <api-key>

Authorization Required: READ_USER on the resolved user.

Request (Lookup Logic):

• If user_id is set, resolves that exact UUID.
• If email is set, resolves that exact email address.
• If username is set, resolves that exact username.
• If no selector is set, resolves the authenticated principal's own human-user record.
• include_deleted=true permits a tombstone to participate in lookup, but grants no authority.
• UUID and current-user lookups preserve the ordinary distinction between NOT_FOUND and PERMISSION_DENIED.
• Email and username lookups deliberately return NOT_FOUND for both an absent value and an existing user the caller may not read. This prevents guessable natural keys from becoming a user-existence oracle.

Response: The resolved User in the requested lifecycle view.

Side Effects: None; this is a read-only operation.

Error Codes:

• UNAUTHENTICATED: Missing or invalid authentication.
• INVALID_ARGUMENT: Malformed selector value.
• NOT_FOUND: No user exists in the requested lifecycle view, or an email/username match is not readable by the caller.
• PERMISSION_DENIED: A UUID/current-user lookup resolves a user the caller may not read.
• INTERNAL: Unexpected server or database failure.

Idempotency: Read-only and safe to retry.

Examples:

grpcurl -plaintext \
-H 'x-api-key: <api-key>' \
-d '{ "email": "[email protected]" }' \
localhost:8080 goodmem.v1.UserService/GetUser

ListUsers

Lists one stable, authorization-filtered page of human users.

Auth: gRPC metadata x-api-key: <api-key>

Authorization Required:

• LIST_USER on the singleton GoodMem instance; and
• READ_USER on every user returned in the page.

Request Behavior:

• label_selectors are combined with logical AND.
• include_deleted=true adds tombstones to the candidate set but does not bypass either gate.
• max_results defaults to 50 and may not exceed 1,000.
• next_token is opaque and bound to the caller, authentication context, and stable filters.
• include_enrollment_summary=true requests non-secret bootstrap posture. A summary is present only on active rows for which the caller also has effective MANAGE_USER_ENROLLMENT; rows remain readable when that additional check is denied.
• Filtering, authorization, and keyset pagination execute in PostgreSQL.

Response: A ListUsersResponse ordered by ascending creation time and UUID. next_token is absent after the final page.

Side Effects: None; this is a read-only operation.

Error Codes:

• UNAUTHENTICATED: Missing or invalid authentication.
• INVALID_ARGUMENT: Invalid filters, page size, or continuation token.
• PERMISSION_DENIED: Caller lacks the instance-level LIST_USER collection gate.
• INTERNAL: Unexpected server or database failure.

Idempotency: Read-only and safe to retry. Concurrent mutations may change later pages.

Examples:

grpcurl -plaintext \
-H 'x-api-key: <api-key>' \
-d '{ "label_selectors": { "team": "platform" }, "max_results": 50 }' \
localhost:8080 goodmem.v1.UserService/ListUsers

UpdateUser

Updates mutable human profile fields or labels.

Auth: gRPC metadata x-api-key: <api-key>

Authorization Required: UPDATE_USER on the resolved user.

Request Behavior:

• At least one mutable field or label strategy must be present.
• A present empty username or display_name clears that optional field.
• A present email must be nonblank and at most 255 characters.
• replace_labels replaces the complete label map; merge_labels upserts supplied entries.
• The two label strategies are mutually exclusive.
• In protobuf JSON and grpcurl, the bytes-valued user_id is base64-encoded.
• The final write rechecks authorization and active lifecycle state.

Response: The updated User, including refreshed update-audit metadata.

Side Effects: Updates explicitly selected profile fields, labels, and update-audit metadata.

Error Codes (in precedence order):

• UNAUTHENTICATED: Missing or invalid authentication.
• INVALID_ARGUMENT: Malformed UUID; blank or overlong email; invalid/no-op mutation; or invalid labels.
• NOT_FOUND: The user UUID does not exist.
• PERMISSION_DENIED: Caller lacks UPDATE_USER on the resolved user.
• FAILED_PRECONDITION: The user is permanently deleted.
• ALREADY_EXISTS: The replacement email or username is already occupied.
• ABORTED: A concurrent lifecycle or authorization change invalidated the final write.
• INTERNAL: Unexpected server or database failure.

Idempotency: Repeating the same explicit values preserves the same profile state, although each successful call advances update-audit metadata.

Examples:

grpcurl -plaintext \
-H 'x-api-key: <api-key>' \
-d '{
"user_id": "BASE64_ENCODED_UUID",
"display_name": "Avery Person",
"merge_labels": { "labels": { "environment": "production" } }
}' \
localhost:8080 goodmem.v1.UserService/UpdateUser

DeleteUser

Permanently soft-deletes one human user.

Auth: gRPC metadata x-api-key: <api-key>

Authorization Required: Instance-wide DELETE_USER with an ANY selector.

Request Behavior:

• The target must be an existing human principal.
• In protobuf JSON and grpcurl, the bytes-valued user_id is base64-encoded.
• The current GoodMem instance owner cannot be deleted; ownership must first be transferred.
• Deleting an already deleted user succeeds without changing its original tombstone or audit provenance.

Response: An empty protobuf message after the tombstone is committed.

Side Effects:

• Atomically records the permanent principal tombstone and deleting audit actor.
• Preserves the human profile, roles, grants, API keys, and resource ownership for history.
• Authentication subsequently rejects API keys whose subject is the deleted principal.

Error Codes (in precedence order):

• UNAUTHENTICATED: Missing or invalid authentication.
• INVALID_ARGUMENT: Malformed user UUID.
• NOT_FOUND: The user UUID does not exist.
• PERMISSION_DENIED: Caller lacks instance-wide DELETE_USER ANY.
• FAILED_PRECONDITION: The user owns the GoodMem instance.
• ABORTED: A concurrent lifecycle or authorization change invalidated the final write.
• INTERNAL: Unexpected server or database failure.

Idempotency: Authorized retries succeed without changing the original tombstone or its audit provenance.

Examples:

grpcurl -plaintext \
-H 'x-api-key: <api-key>' \
-d '{ "user_id": "BASE64_ENCODED_UUID" }' \
localhost:8080 goodmem.v1.UserService/DeleteUser

CreateUserEnrollment

Creates a short-lived enrollment credential for one dormant human user.

Auth: gRPC metadata x-api-key: <api-key>

Authorization Required: MANAGE_USER_ENROLLMENT with ANY or EXACT authority covering the target user. Only an authenticated HUMAN may administer enrollment.

Request Behavior:

• user_id must identify an active human that has never completed enrollment and has no API key.
• The server generates enrollment_id when the caller omits it.
• At most one unconsumed, unrevoked enrollment may exist for a user.
• rotate_existing=false returns ALREADY_EXISTS when a live enrollment exists.
• rotate_existing=true atomically revokes an existing open enrollment and creates its replacement. An expired open enrollment is replaced without requiring this flag.
• The server applies its fixed enrollment lifetime; callers cannot select an expiration.

Response: Enrollment metadata and the one-time raw enrollment credential. The credential cannot be read again and must be delivered to the target human over a secure channel.

Side Effects: Atomically creates one enrollment and, when rotating, permanently revokes the previous open enrollment. It does not create an API key, role, grant, or login mapping.

Error Codes (in precedence order):

• UNAUTHENTICATED: Missing or invalid administrator authentication.
• INVALID_ARGUMENT: Malformed user or enrollment UUID.
• FAILED_PRECONDITION: The caller is a service principal.
• NOT_FOUND: The target human does not exist.
• PERMISSION_DENIED: Caller lacks MANAGE_USER_ENROLLMENT on the target user.
• FAILED_PRECONDITION: The user is deleted or no longer eligible for initial enrollment.
• ALREADY_EXISTS: A live enrollment exists without rotation, or the requested enrollment UUID is already occupied.
• ABORTED: A concurrent lifecycle, credential, or authorization change invalidated creation.
• INTERNAL: Unexpected server or database failure.

Idempotency: Not replayable as a secret-returning operation. If the response is lost, use a caller-provided enrollment UUID to inspect the outcome, then revoke and replace any committed enrollment. The raw credential is never disclosed twice.

GetUserEnrollment

Retrieves non-secret metadata for one current or historical enrollment.

Auth: gRPC metadata x-api-key: <api-key>

Authorization Required: MANAGE_USER_ENROLLMENT with ANY or EXACT authority covering user_id. Only an authenticated HUMAN may administer enrollment.

Request Behavior: Both UUIDs are required. The service resolves and authorizes the target user before resolving the enrollment under the pair (user_id, enrollment_id). An enrollment belonging to another user is therefore indistinguishable from an absent enrollment.

Response: Current or historical enrollment metadata. Raw enrollment credential material is never returned.

Side Effects: None; this is a read-only operation.

Error Codes (in precedence order):

• UNAUTHENTICATED: Missing or invalid administrator authentication.
• INVALID_ARGUMENT: Malformed user or enrollment UUID.
• FAILED_PRECONDITION: The caller is a service principal.
• NOT_FOUND: The target user or enrollment does not exist under the requested pair.
• PERMISSION_DENIED: Caller lacks MANAGE_USER_ENROLLMENT on the target user.
• INTERNAL: Unexpected server or database failure.

Idempotency: Read-only and safe to retry.

ListUserEnrollments

Lists one stable page of current and historical enrollments for a human user.

Auth: gRPC metadata x-api-key: <api-key>

Authorization Required: MANAGE_USER_ENROLLMENT with ANY or EXACT authority covering user_id. Only an authenticated HUMAN may administer enrollment.

Request Behavior:

• user_id is required and may identify an active user or retained tombstone.
• max_results defaults to 50 and may not exceed 1,000.
• next_token is opaque and bound to the target user, request principal, and exact authenticating API key when present.
• Pending, expired, consumed, and revoked enrollments all participate in the page.

Response: Enrollment metadata ordered by descending creation time and enrollment UUID. next_token is absent after the final page. Raw enrollment credentials are never included.

Side Effects: None; this is a read-only operation.

Error Codes (in precedence order):

• UNAUTHENTICATED: Missing or invalid administrator authentication.
• INVALID_ARGUMENT: Malformed user UUID, invalid page size, or invalid continuation token.
• FAILED_PRECONDITION: The caller is a service principal.
• NOT_FOUND: The target user does not exist in the retained lifecycle view.
• PERMISSION_DENIED: Caller lacks MANAGE_USER_ENROLLMENT on the target user.
• INTERNAL: Unexpected server or database failure.

Idempotency: Read-only and safe to retry. Concurrent enrollment changes may alter later pages.

RevokeUserEnrollment

Permanently revokes one outstanding enrollment credential.

Auth: gRPC metadata x-api-key: <api-key>

Authorization Required: MANAGE_USER_ENROLLMENT with ANY or EXACT authority covering user_id. Only an authenticated HUMAN may administer enrollment.

Request Behavior: Both UUIDs are required. The target user is resolved and authorized before the enrollment pair is resolved. Repeating an authorized revocation preserves and returns its original revocation time and actor. A consumed enrollment cannot be revoked.

Response: Terminal enrollment metadata, including revocation provenance.

Side Effects: The first successful call records permanent revocation time and the exact authenticated principal or API key as revoking actor. The enrollment row is retained.

Error Codes (in precedence order):

• UNAUTHENTICATED: Missing or invalid administrator authentication.
• INVALID_ARGUMENT: Malformed user or enrollment UUID.
• FAILED_PRECONDITION: The caller is a service principal.
• NOT_FOUND: The target user or enrollment does not exist under the requested pair.
• PERMISSION_DENIED: Caller lacks MANAGE_USER_ENROLLMENT on the target user.
• FAILED_PRECONDITION: The enrollment was consumed.
• ABORTED: A concurrent completion or authorization change invalidated revocation.
• INTERNAL: Unexpected server or database failure.

Idempotency: Authorized retries preserve and return the original revocation provenance.

CompleteUserEnrollment

Exchanges one valid enrollment credential for its human's initial API key.

Auth: No ordinary API-key metadata. The required enrollment credential authenticates only this completion operation and is validated inside the completion transaction.

Authorization Required: Possession of the pending, unexpired, unrevoked enrollment credential. MANAGE_USER_ENROLLMENT is not evaluated during completion.

Request Behavior:

• enrollment_token is always required.
• api_key_id and raw_api_key are an all-or-nothing optional pair.
• When both are omitted, the server generates the API-key UUID and canonical raw gm_ key.
• When both are supplied, the client must retain the exact tuple for retry safety.
• The enrollment credential and raw API key are input-only secrets and must never be logged.
• First completion requires an active human with no API key and no previously consumed enrollment.
• An exact retry of a client-supplied tuple succeeds with already_completed=true and changes no durable state. A server-generated completion cannot be replayed or redisclosed.
• Every other nonblank unusable enrollment credential receives the same authentication error.

Response: Metadata for the self-owned, inheriting initial API key, whether the call was an exact retry, and the one-time raw API key only after a fresh server-generated completion. Client-supplied raw material and enrollment credentials are never echoed.

Side Effects: On first completion, atomically creates one active API key for the enrolled human and permanently consumes the enrollment. It assigns no role or grant.

Error Codes:

• INVALID_ARGUMENT: The enrollment credential is blank; exactly one optional key field is present; the supplied UUID is malformed; or the supplied raw API key is not canonical.
• UNAUTHENTICATED: The enrollment credential is invalid, unknown, expired, revoked, bound to a deleted or ineligible user, consumed after server generation, consumed with a different client tuple, or otherwise unusable.
• ALREADY_EXISTS: The proposed API-key UUID or verifier is already used by another key.
• ABORTED: A concurrent completion, revocation, deletion, or credential publication won.
• INTERNAL: Unexpected server or database failure.

Idempotency: Client-supplied mode is retry-safe only with the exact original tuple. Server- generated mode is not safely retryable after an ambiguous response because raw material is returned exactly once and cannot be recovered.

InitializeSystem

Initializes the singleton GoodMem instance and its first root human.

Auth: None. This and CompleteUserEnrollment are the only methods in UserService that do not require ordinary API-key authentication.

Authorization Required: None. Availability is limited by the singleton initialization state.

Request: Empty. Initialization values are generated by the server.

Side Effects on First Initialization:

• Atomically creates the first HUMAN principal and human profile.
• Creates the singleton GoodMem instance owned by that principal.
• Creates the ownership-mirroring ROOT assignment and initial ADMIN assignment.
• Creates and returns the one-time raw bootstrap API key.

Subsequent Calls:

• Perform no credential-producing side effect.
• Return already_initialized=true instead of returning ALREADY_EXISTS.
• Never reveal the bootstrap credential again.

Response: An InitializeSystemResponse describing whether initialization occurred. The raw bootstrap API key is populated only on the successful first call.

Error Codes:

• INTERNAL: Unexpected provisioning or database failure.

Idempotency: Idempotent with respect to durable initialization. Only the successful first call returns the raw bootstrap API key, so callers must save it immediately.

Examples:

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

Messages

User

A human user backed by a durable HUMAN principal.

Human users are permanently self-owned. Labels, lifecycle state, and audit provenance are stored on the shared principal, while email, username, and display name are human-profile fields. A deleted user remains a durable tombstone and cannot be restored or recreated under the same UUID.

All fields are OUTPUT_ONLY. Timestamps are UTC. Audit actor identifiers may name either a principal or the exact API key used for the mutation.

User.LabelsEntry

UserEnrollmentSummary

Non-secret bootstrap posture for one active human user.

CreateUserRequest

Request to create a human user without implicit security side effects.

CreateUserRequest.LabelsEntry

GetUserRequest

Request to resolve a user by exactly one selector, or the current user when unset.

ListUsersRequest

Request for one stable, authorization-filtered user page.

ListUsersRequest.LabelSelectorsEntry

ListUsersResponse

One stable page of readable human users. All fields are OUTPUT_ONLY.

ListUsersNextPageToken

Internal cursor encoded by the server; clients must treat public next_token strings as opaque.

ListUsersNextPageToken.LabelSelectorsEntry

UpdateUserRequest

Request to update mutable fields of one active human user.

DeleteUserRequest

Request to permanently soft-delete a human user.

UserEnrollment

Non-secret metadata for one current or historical human-user enrollment.

All fields are OUTPUT_ONLY. The raw enrollment credential is deliberately absent and can be returned only once by CreateUserEnrollment. Status is derived from terminal fields and the current time rather than stored as mutable state.

CreateUserEnrollmentRequest

Request to create or explicitly rotate one human's enrollment credential.

CreateUserEnrollmentResponse

Result of creating an enrollment. All fields are OUTPUT_ONLY.

GetUserEnrollmentRequest

Request to read one enrollment under its target user.

GetUserEnrollmentResponse

Result of reading one enrollment. All fields are OUTPUT_ONLY.

ListUserEnrollmentsRequest

Request for one stable page of a human's enrollment history.

ListUserEnrollmentsResponse

One stable page of enrollment history. All fields are OUTPUT_ONLY.

ListUserEnrollmentsNextPageToken

Internal cursor encoded by the server; public next_token strings are opaque.

RevokeUserEnrollmentRequest

Request to permanently revoke one enrollment under its target user.

RevokeUserEnrollmentResponse

Result of revoking one enrollment. All fields are OUTPUT_ONLY.

CompleteUserEnrollmentRequest

Request to exchange one enrollment credential for its human's initial API key.

CompleteUserEnrollmentResponse

Result of fresh or exactly replayed enrollment completion. All fields are OUTPUT_ONLY.

InitializeSystemRequest

Empty request for the unauthenticated, one-time provisioning operation.

InitializeSystemResponse

Result of singleton system initialization. All fields are OUTPUT_ONLY.

Enums

UserEnrollmentStatus

Derived lifecycle state of a retained human-user enrollment.