feat: Add audit record APIs and deprecate existing audit log APIs (#422)

* feat: Add audit record APIs and deprecate existing audit log APIs

* chore: Update deprecation notice

* add uuid validation for actor id

* make `type` field optional in `AuditRecordActor`

* add idempotency_key field with UUID validation to AuditRecord

Author: AmanGIT07

raystack/frontier/v1beta1/admin.proto

@@ -788,6 +788,9 @@ service AdminService {
   // Revoke a specific session for a specific user (admin only).
   rpc RevokeUserSession(RevokeUserSessionRequest) returns (RevokeUserSessionResponse) {}
 
+  // Audit Records (Admin Only)
+  rpc ListAuditRecords(ListAuditRecordsRequest) returns (ListAuditRecordsResponse) {}
+
 }
 
 message ListAllUsersRequest {
@@ -1720,3 +1723,15 @@ message RevokeUserSessionRequest {
 }
 
 message RevokeUserSessionResponse {}
+
+// Admin Audit Record messages
+
+message ListAuditRecordsRequest {
+  RQLRequest query = 1;
+}
+
+message ListAuditRecordsResponse {
+  repeated AuditRecord audit_records = 1;
+  RQLQueryPaginationResponse pagination = 2;
+  RQLQueryGroupResponse group = 3;
+}

raystack/frontier/v1beta1/frontier.proto

@@ -1308,32 +1308,38 @@ service FrontierService {
 
   // Audit logs
   rpc ListOrganizationAuditLogs(ListOrganizationAuditLogsRequest) returns (ListOrganizationAuditLogsResponse) {
+    option deprecated = true;
     option (google.api.http) = {get: "/v1beta1/organizations/{org_id}/auditlogs"};
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
       tags: "AuditLog";
       summary: "List audit logs";
-      description: "Returns a list of audit logs of an organization in Frontier.";
+      description: "Returns a list of audit logs of an organization in Frontier. DEPRECATED: Use admin ListAuditRecords API instead.";
+      deprecated: true;
     };
   }
 
   rpc CreateOrganizationAuditLogs(CreateOrganizationAuditLogsRequest) returns (CreateOrganizationAuditLogsResponse) {
+    option deprecated = true;
     option (google.api.http) = {
       post: "/v1beta1/organizations/{org_id}/auditlogs",
       body: "*"
     };
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
       tags: "AuditLog";
       summary: "Create audit log";
-      description: "Create new audit logs in a batch.";
+      description: "Create new audit logs in a batch. DEPRECATED: Use ListAuditRecords API instead with filters.";
+      deprecated: true;
     };
   }
 
   rpc GetOrganizationAuditLog(GetOrganizationAuditLogRequest) returns (GetOrganizationAuditLogResponse) {
+    option deprecated = true;
     option (google.api.http) = {get: "/v1beta1/organizations/{org_id}/auditlogs/{id}"};
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
       tags: "AuditLog";
       summary: "Get audit log";
-      description: "Get an audit log by ID.";
+      description: "Get an audit log by ID. DEPRECATED: Use admin GetAuditRecord API instead.";
+      deprecated: true;
     };
   }
 
@@ -1915,6 +1921,9 @@ service FrontierService {
       description: "Create prospect for given email and activity. Available for public access.";
     };
   }
+
+  // Audit Records
+  rpc CreateAuditRecord(CreateAuditRecordRequest) returns (CreateAuditRecordResponse) {}
 }
 
 // Billing
@@ -4165,3 +4174,38 @@ message RevokeSessionResponse {}
 message PingUserSessionRequest {}
 
 message PingUserSessionResponse {}
+
+message CreateAuditRecordRequest {
+  AuditRecordActor actor = 1 [(google.api.field_behavior) = REQUIRED];
+  
+  string event = 2 [
+    (google.api.field_behavior) = REQUIRED,
+    (validate.rules).string = {min_len: 3}
+  ];
+  
+  // Base resource on which this change happened
+  AuditRecordResource resource = 3 [(google.api.field_behavior) = REQUIRED];
+  
+  // Related resource info (optional)
+  AuditRecordTarget target = 4;
+  
+  // When the event occurred
+  google.protobuf.Timestamp occurred_at = 5 [(google.api.field_behavior) = REQUIRED];
+  
+  string org_id = 6 [(validate.rules).string.uuid = true];
+  
+  // Request ID for tracing
+  string req_id = 7;
+  
+  // Flexible metadata field for any additional data including reason, changes, etc.
+  google.protobuf.Struct metadata = 8;
+
+  // Idempotency key to prevent duplicate audit records. Can be used for storing external id.
+  string idempotency_key = 9 [
+    (google.api.field_behavior) = REQUIRED,
+    (validate.rules).string.uuid = true];
+}
+
+message CreateAuditRecordResponse {
+  AuditRecord audit_record = 1;
+}

raystack/frontier/v1beta1/models.proto

@@ -1044,3 +1044,41 @@ message Session {
   google.protobuf.Timestamp created_at = 4;
   google.protobuf.Timestamp updated_at = 5;
 }
+
+// Audit Record models
+
+message AuditRecordActor {
+  string id = 1 [(google.api.field_behavior) = REQUIRED, (validate.rules).string.uuid = true];
+  string type = 2; // not mandatory if id is zeroUUID
+  string name = 3;
+  google.protobuf.Struct metadata = 4;
+}
+
+message AuditRecordResource {
+  string id = 1 [(google.api.field_behavior) = REQUIRED];
+  string type = 2 [(google.api.field_behavior) = REQUIRED];
+  string name = 3;
+  google.protobuf.Struct metadata = 4;
+}
+
+message AuditRecordTarget {
+  string id = 1;
+  string type = 2;
+  string name = 3;
+  google.protobuf.Struct metadata = 4;
+}
+
+message AuditRecord {
+  string id = 1;
+  
+  AuditRecordActor actor = 2;
+  string event = 3;
+  AuditRecordResource resource = 4;
+  AuditRecordTarget target = 5;
+  google.protobuf.Timestamp occurred_at = 6;
+  string org_id = 7;
+  string req_id = 8;
+  google.protobuf.Struct metadata = 9;
+
+  google.protobuf.Timestamp created_at = 10;
+}