Shared types and service contracts

pkg/types contains shared IDs, emails, entity metadata, validation errors, and identity/authorization service contracts. These types provide reusable value handling and service boundaries without transferring business ownership between services.

Use validated constructors/helpers where offered instead of reimplementing empty-ID/email checks in every consumer. Keep service-owned public DTOs distinct from private persistence/domain models even when both use shared primitives. Shared types and interfaces do not supply authorization behavior, persistence, or Huma validation by themselves.

Errors such as empty/invalid email and empty ID belong to this value-type layer; provider-specific errors stay in the provider contract, and HTTP response mapping stays in presentation. See the generated signatures below for the exact constructors and operations available.

Identity and authorization contracts

IIdentityService.Verify(ctx, authorization) accepts the full Authorization header and returns a verified Identity containing UserID and SessionID, or an error. Both fields use the shared ID type. Verification covers the access credential and its persistent session.

IAuthorizationService exposes AdminHasPermission and OrgHasPermission. Each method accepts a context and a dedicated input type, and returns (bool, error). Permission inputs carry a verified user ID, a PermissionKey, and ResourceAccess (AccessAny or AccessOwn); organization inputs also require an organization ID. Normal denials return false, nil; invalid input and dependency failures return errors. Callers must stop on either a denial or an error.

Resource-owning services determine ownership using trusted, server-loaded facts. For record actions, request AccessOwn only after ownership succeeds, and always select it for an owned resource so explicit own-access denials are considered. Omitted access defaults to AccessAny; any grants also match own checks, own grants never match any checks, matching explicit denials override allows, and missing grants deny access.

IIdentityService is implemented by Identity's internal/services.IdentityService and exposed through Module.Identity(). The existing service-owned Authentication() capability adapts this service for current consumers.

IAuthorizationService is provided by Authorization's internal/services.AuthorizationService and exposed through Module.Authorization() or module.NewAuthorizationService(). This is a placeholder: both methods return true, nil without evaluating input. Admin injects the shared Identity and Authorization interfaces into CreateOrganizationUseCase through its Dependencies struct. Other callers continue to use Module.Permissions() for permission enforcement. Doctor authorization and IsOwner methods are deferred.

Code reference

See the generated types package.

Clinical domain and ports packages

pkg/types/domain contains clinical catalog models, inputs, errors and validation. pkg/types/ports contains AdminClinicalSuggestionService, DoctorClinicalService, and repository/transaction interfaces using domain values. Doctor receives the query-only service; Admin receives the combined catalog management service. DTOs and storage adapters stay local to their services. Other existing root types models and service contracts are unchanged by this feature refactor. See DTOs and ports.