syntax = "proto3";

// Identity gRPC — Backend Architecture §16, §17, §21, §26 (Phase 2/3).
// Exposed only via gRPC, never REST.
//
// CAP is the client-facing entry for NIN (`POST /identity-verification`)
// and for staff invite (`POST /centre/staff`), both of which call this
// service synchronously.
//
// NIN / identification_number: never logged, never persisted raw by
// Orchestrator (§17). Only HMAC (or equivalent) may be stored server-side.
// Generated passwords: never returned on this RPC and never placed on
// `notification.requested` — OL mails them in-process.
// Do not add RPCs here without updating architecture §21 first.
package orchestrator.v1;

option go_package = "github.com/C-STEMP/elimi-ecosystem/proto/orchestrator/v1;orchestratorv1";

service IdentityService {
  rpc VerifyIdentity(VerifyIdentityRequest) returns (VerifyIdentityResponse);
  // Get-or-create an OL User by email (centre-staff invite). Idempotent.
  // Existing email → is_new=false, no password change. New email → create
  // User, generate password, set must_change_password, mail in-process.
  // Also emits user.created when a User is first created (CAP consumes
  // idempotently). CAP must not mint Orchestrator user ids.
  rpc ProvisionAccount(ProvisionAccountRequest) returns (ProvisionAccountResponse);
}

message VerifyIdentityRequest {
  string user_id = 1;
  string type = 2;                  // "nin" — extensible as more ID types are added
  string identification_number = 3; // never logged, never persisted raw (§17)
  string first_name = 4;
  string last_name = 5;
  string date_of_birth = 6;         // ISO 8601 date, e.g. "1998-04-12"
}

message VerifyIdentityResponse {
  bool verified = 1;
  string provider = 2;             // which IdentityProviderAdapter handled the check (§16)
  string provider_reference = 3;   // opaque provider token — never reversible to the raw NIN
  string verified_at = 4;          // ISO 8601 datetime; empty if verified == false
}

message ProvisionAccountRequest {
  string email = 1;
  repeated string intents = 2;     // e.g. "cap"
  string correlation_id = 3;       // CAP CentreStaff id (or invite correlation)
  string display_name = 4;         // from add-staff form; greeting / seed name
  // "new_account" | "existing_member" — CAP may omit; OL decides from email lookup
  // and still uses this as a mail-template hint when provided.
  string notify_kind = 5;
  string centre_name = 6;          // mail context only
  string role = 7;                 // mail context only (centre staff role wire value)
}

message ProvisionAccountResponse {
  string user_id = 1;              // Orchestrator User.id — CAP stores as CapUser.userId
  bool is_new = 2;
}