feat: build core API, fraud engine, notifier, and frontend

Phase 1 — Core API (Go):
- Events, guests, tokens, RSVPs CRUD on PostgreSQL via pgx/v5
- HMAC-signed per-guest tokens with format validation
- Health endpoint with DB ping, slog JSON logging, graceful shutdown

Phase 2 — NATS + Fraud Engine:
- NATS JetStream pub/sub with explicit-ack consumers
- Python/FastAPI fraud engine with heuristic risk scoring
  (fingerprint mismatch, IP change, missing signals, repeated access)
- gRPC sync scoring with 250ms fail-open timeout
- Per-guest baseline tracking; risk bands low/medium/high/block

Phase 3 — Notifications + Frontend:
- Notification worker scaffolding (Twilio/SES stubs, retry/backoff)
- Nuxt 3 frontend with Tailwind dark theme + brand green
- Live monitor via WebSocket with auto-reconnect
- Activity history endpoint backfills monitor with RSVPs +
  scored access checks (including blocked attempts)

UX polish:
- Marketing-friendly landing page (hero mockup, how-it-works,
  features, use cases, testimonials, FAQ, final CTA)
- Animated layered card mockups on landing + new-event page
- Plus-ones stepper, RSVP status badges, filter buttons
- Friendly access-check labels (Verified/Review/Suspicious/Blocked)
- Dashboard hydration fix via ClientOnly wrapper

Infrastructure:
- docker-compose for full local dev (postgres, nats, api,
  fraud-engine, notifier, frontend)
- Multi-stage Dockerfiles, non-root UID 1000
- Integration tests with testcontainers-go

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Kwaku Danso
2026-05-11 21:08:56 +01:00
parent f760fc3e21
commit 3f8bc58ca9
89 changed files with 22729 additions and 0 deletions
+381
View File
@@ -0,0 +1,381 @@
// Code generated by protoc-gen-go. DO NOT EDIT.
// versions:
// protoc-gen-go v1.34.2
// protoc v6.31.1
// source: fraud/v1/fraud.proto
package fraudpb
import (
protoreflect "google.golang.org/protobuf/reflect/protoreflect"
protoimpl "google.golang.org/protobuf/runtime/protoimpl"
reflect "reflect"
sync "sync"
)
const (
// Verify that this generated code is sufficiently up-to-date.
_ = protoimpl.EnforceVersion(20 - protoimpl.MinVersion)
// Verify that runtime/protoimpl is sufficiently up-to-date.
_ = protoimpl.EnforceVersion(protoimpl.MaxVersion - 20)
)
type Risk int32
const (
Risk_RISK_UNSPECIFIED Risk = 0
Risk_RISK_LOW Risk = 1
Risk_RISK_MEDIUM Risk = 2
Risk_RISK_HIGH Risk = 3
Risk_RISK_BLOCK Risk = 4
)
// Enum value maps for Risk.
var (
Risk_name = map[int32]string{
0: "RISK_UNSPECIFIED",
1: "RISK_LOW",
2: "RISK_MEDIUM",
3: "RISK_HIGH",
4: "RISK_BLOCK",
}
Risk_value = map[string]int32{
"RISK_UNSPECIFIED": 0,
"RISK_LOW": 1,
"RISK_MEDIUM": 2,
"RISK_HIGH": 3,
"RISK_BLOCK": 4,
}
)
func (x Risk) Enum() *Risk {
p := new(Risk)
*p = x
return p
}
func (x Risk) String() string {
return protoimpl.X.EnumStringOf(x.Descriptor(), protoreflect.EnumNumber(x))
}
func (Risk) Descriptor() protoreflect.EnumDescriptor {
return file_fraud_v1_fraud_proto_enumTypes[0].Descriptor()
}
func (Risk) Type() protoreflect.EnumType {
return &file_fraud_v1_fraud_proto_enumTypes[0]
}
func (x Risk) Number() protoreflect.EnumNumber {
return protoreflect.EnumNumber(x)
}
// Deprecated: Use Risk.Descriptor instead.
func (Risk) EnumDescriptor() ([]byte, []int) {
return file_fraud_v1_fraud_proto_rawDescGZIP(), []int{0}
}
type ScoreRequest struct {
state protoimpl.MessageState
sizeCache protoimpl.SizeCache
unknownFields protoimpl.UnknownFields
EventId string `protobuf:"bytes,1,opt,name=event_id,json=eventId,proto3" json:"event_id,omitempty"`
GuestId string `protobuf:"bytes,2,opt,name=guest_id,json=guestId,proto3" json:"guest_id,omitempty"`
TokenId string `protobuf:"bytes,3,opt,name=token_id,json=tokenId,proto3" json:"token_id,omitempty"`
AccessLogId string `protobuf:"bytes,4,opt,name=access_log_id,json=accessLogId,proto3" json:"access_log_id,omitempty"`
Fingerprint map[string]string `protobuf:"bytes,5,rep,name=fingerprint,proto3" json:"fingerprint,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
IpAddress string `protobuf:"bytes,6,opt,name=ip_address,json=ipAddress,proto3" json:"ip_address,omitempty"`
UserAgent string `protobuf:"bytes,7,opt,name=user_agent,json=userAgent,proto3" json:"user_agent,omitempty"`
Referrer string `protobuf:"bytes,8,opt,name=referrer,proto3" json:"referrer,omitempty"`
}
func (x *ScoreRequest) Reset() {
*x = ScoreRequest{}
if protoimpl.UnsafeEnabled {
mi := &file_fraud_v1_fraud_proto_msgTypes[0]
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
ms.StoreMessageInfo(mi)
}
}
func (x *ScoreRequest) String() string {
return protoimpl.X.MessageStringOf(x)
}
func (*ScoreRequest) ProtoMessage() {}
func (x *ScoreRequest) ProtoReflect() protoreflect.Message {
mi := &file_fraud_v1_fraud_proto_msgTypes[0]
if protoimpl.UnsafeEnabled && x != nil {
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
if ms.LoadMessageInfo() == nil {
ms.StoreMessageInfo(mi)
}
return ms
}
return mi.MessageOf(x)
}
// Deprecated: Use ScoreRequest.ProtoReflect.Descriptor instead.
func (*ScoreRequest) Descriptor() ([]byte, []int) {
return file_fraud_v1_fraud_proto_rawDescGZIP(), []int{0}
}
func (x *ScoreRequest) GetEventId() string {
if x != nil {
return x.EventId
}
return ""
}
func (x *ScoreRequest) GetGuestId() string {
if x != nil {
return x.GuestId
}
return ""
}
func (x *ScoreRequest) GetTokenId() string {
if x != nil {
return x.TokenId
}
return ""
}
func (x *ScoreRequest) GetAccessLogId() string {
if x != nil {
return x.AccessLogId
}
return ""
}
func (x *ScoreRequest) GetFingerprint() map[string]string {
if x != nil {
return x.Fingerprint
}
return nil
}
func (x *ScoreRequest) GetIpAddress() string {
if x != nil {
return x.IpAddress
}
return ""
}
func (x *ScoreRequest) GetUserAgent() string {
if x != nil {
return x.UserAgent
}
return ""
}
func (x *ScoreRequest) GetReferrer() string {
if x != nil {
return x.Referrer
}
return ""
}
type ScoreResponse struct {
state protoimpl.MessageState
sizeCache protoimpl.SizeCache
unknownFields protoimpl.UnknownFields
Score int32 `protobuf:"varint,1,opt,name=score,proto3" json:"score,omitempty"`
Risk Risk `protobuf:"varint,2,opt,name=risk,proto3,enum=guestguard.fraud.v1.Risk" json:"risk,omitempty"`
Reasons []string `protobuf:"bytes,3,rep,name=reasons,proto3" json:"reasons,omitempty"`
}
func (x *ScoreResponse) Reset() {
*x = ScoreResponse{}
if protoimpl.UnsafeEnabled {
mi := &file_fraud_v1_fraud_proto_msgTypes[1]
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
ms.StoreMessageInfo(mi)
}
}
func (x *ScoreResponse) String() string {
return protoimpl.X.MessageStringOf(x)
}
func (*ScoreResponse) ProtoMessage() {}
func (x *ScoreResponse) ProtoReflect() protoreflect.Message {
mi := &file_fraud_v1_fraud_proto_msgTypes[1]
if protoimpl.UnsafeEnabled && x != nil {
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
if ms.LoadMessageInfo() == nil {
ms.StoreMessageInfo(mi)
}
return ms
}
return mi.MessageOf(x)
}
// Deprecated: Use ScoreResponse.ProtoReflect.Descriptor instead.
func (*ScoreResponse) Descriptor() ([]byte, []int) {
return file_fraud_v1_fraud_proto_rawDescGZIP(), []int{1}
}
func (x *ScoreResponse) GetScore() int32 {
if x != nil {
return x.Score
}
return 0
}
func (x *ScoreResponse) GetRisk() Risk {
if x != nil {
return x.Risk
}
return Risk_RISK_UNSPECIFIED
}
func (x *ScoreResponse) GetReasons() []string {
if x != nil {
return x.Reasons
}
return nil
}
var File_fraud_v1_fraud_proto protoreflect.FileDescriptor
var file_fraud_v1_fraud_proto_rawDesc = []byte{
0x0a, 0x14, 0x66, 0x72, 0x61, 0x75, 0x64, 0x2f, 0x76, 0x31, 0x2f, 0x66, 0x72, 0x61, 0x75, 0x64,
0x2e, 0x70, 0x72, 0x6f, 0x74, 0x6f, 0x12, 0x13, 0x67, 0x75, 0x65, 0x73, 0x74, 0x67, 0x75, 0x61,
0x72, 0x64, 0x2e, 0x66, 0x72, 0x61, 0x75, 0x64, 0x2e, 0x76, 0x31, 0x22, 0xf3, 0x02, 0x0a, 0x0c,
0x53, 0x63, 0x6f, 0x72, 0x65, 0x52, 0x65, 0x71, 0x75, 0x65, 0x73, 0x74, 0x12, 0x19, 0x0a, 0x08,
0x65, 0x76, 0x65, 0x6e, 0x74, 0x5f, 0x69, 0x64, 0x18, 0x01, 0x20, 0x01, 0x28, 0x09, 0x52, 0x07,
0x65, 0x76, 0x65, 0x6e, 0x74, 0x49, 0x64, 0x12, 0x19, 0x0a, 0x08, 0x67, 0x75, 0x65, 0x73, 0x74,
0x5f, 0x69, 0x64, 0x18, 0x02, 0x20, 0x01, 0x28, 0x09, 0x52, 0x07, 0x67, 0x75, 0x65, 0x73, 0x74,
0x49, 0x64, 0x12, 0x19, 0x0a, 0x08, 0x74, 0x6f, 0x6b, 0x65, 0x6e, 0x5f, 0x69, 0x64, 0x18, 0x03,
0x20, 0x01, 0x28, 0x09, 0x52, 0x07, 0x74, 0x6f, 0x6b, 0x65, 0x6e, 0x49, 0x64, 0x12, 0x22, 0x0a,
0x0d, 0x61, 0x63, 0x63, 0x65, 0x73, 0x73, 0x5f, 0x6c, 0x6f, 0x67, 0x5f, 0x69, 0x64, 0x18, 0x04,
0x20, 0x01, 0x28, 0x09, 0x52, 0x0b, 0x61, 0x63, 0x63, 0x65, 0x73, 0x73, 0x4c, 0x6f, 0x67, 0x49,
0x64, 0x12, 0x54, 0x0a, 0x0b, 0x66, 0x69, 0x6e, 0x67, 0x65, 0x72, 0x70, 0x72, 0x69, 0x6e, 0x74,
0x18, 0x05, 0x20, 0x03, 0x28, 0x0b, 0x32, 0x32, 0x2e, 0x67, 0x75, 0x65, 0x73, 0x74, 0x67, 0x75,
0x61, 0x72, 0x64, 0x2e, 0x66, 0x72, 0x61, 0x75, 0x64, 0x2e, 0x76, 0x31, 0x2e, 0x53, 0x63, 0x6f,
0x72, 0x65, 0x52, 0x65, 0x71, 0x75, 0x65, 0x73, 0x74, 0x2e, 0x46, 0x69, 0x6e, 0x67, 0x65, 0x72,
0x70, 0x72, 0x69, 0x6e, 0x74, 0x45, 0x6e, 0x74, 0x72, 0x79, 0x52, 0x0b, 0x66, 0x69, 0x6e, 0x67,
0x65, 0x72, 0x70, 0x72, 0x69, 0x6e, 0x74, 0x12, 0x1d, 0x0a, 0x0a, 0x69, 0x70, 0x5f, 0x61, 0x64,
0x64, 0x72, 0x65, 0x73, 0x73, 0x18, 0x06, 0x20, 0x01, 0x28, 0x09, 0x52, 0x09, 0x69, 0x70, 0x41,
0x64, 0x64, 0x72, 0x65, 0x73, 0x73, 0x12, 0x1d, 0x0a, 0x0a, 0x75, 0x73, 0x65, 0x72, 0x5f, 0x61,
0x67, 0x65, 0x6e, 0x74, 0x18, 0x07, 0x20, 0x01, 0x28, 0x09, 0x52, 0x09, 0x75, 0x73, 0x65, 0x72,
0x41, 0x67, 0x65, 0x6e, 0x74, 0x12, 0x1a, 0x0a, 0x08, 0x72, 0x65, 0x66, 0x65, 0x72, 0x72, 0x65,
0x72, 0x18, 0x08, 0x20, 0x01, 0x28, 0x09, 0x52, 0x08, 0x72, 0x65, 0x66, 0x65, 0x72, 0x72, 0x65,
0x72, 0x1a, 0x3e, 0x0a, 0x10, 0x46, 0x69, 0x6e, 0x67, 0x65, 0x72, 0x70, 0x72, 0x69, 0x6e, 0x74,
0x45, 0x6e, 0x74, 0x72, 0x79, 0x12, 0x10, 0x0a, 0x03, 0x6b, 0x65, 0x79, 0x18, 0x01, 0x20, 0x01,
0x28, 0x09, 0x52, 0x03, 0x6b, 0x65, 0x79, 0x12, 0x14, 0x0a, 0x05, 0x76, 0x61, 0x6c, 0x75, 0x65,
0x18, 0x02, 0x20, 0x01, 0x28, 0x09, 0x52, 0x05, 0x76, 0x61, 0x6c, 0x75, 0x65, 0x3a, 0x02, 0x38,
0x01, 0x22, 0x6e, 0x0a, 0x0d, 0x53, 0x63, 0x6f, 0x72, 0x65, 0x52, 0x65, 0x73, 0x70, 0x6f, 0x6e,
0x73, 0x65, 0x12, 0x14, 0x0a, 0x05, 0x73, 0x63, 0x6f, 0x72, 0x65, 0x18, 0x01, 0x20, 0x01, 0x28,
0x05, 0x52, 0x05, 0x73, 0x63, 0x6f, 0x72, 0x65, 0x12, 0x2d, 0x0a, 0x04, 0x72, 0x69, 0x73, 0x6b,
0x18, 0x02, 0x20, 0x01, 0x28, 0x0e, 0x32, 0x19, 0x2e, 0x67, 0x75, 0x65, 0x73, 0x74, 0x67, 0x75,
0x61, 0x72, 0x64, 0x2e, 0x66, 0x72, 0x61, 0x75, 0x64, 0x2e, 0x76, 0x31, 0x2e, 0x52, 0x69, 0x73,
0x6b, 0x52, 0x04, 0x72, 0x69, 0x73, 0x6b, 0x12, 0x18, 0x0a, 0x07, 0x72, 0x65, 0x61, 0x73, 0x6f,
0x6e, 0x73, 0x18, 0x03, 0x20, 0x03, 0x28, 0x09, 0x52, 0x07, 0x72, 0x65, 0x61, 0x73, 0x6f, 0x6e,
0x73, 0x2a, 0x5a, 0x0a, 0x04, 0x52, 0x69, 0x73, 0x6b, 0x12, 0x14, 0x0a, 0x10, 0x52, 0x49, 0x53,
0x4b, 0x5f, 0x55, 0x4e, 0x53, 0x50, 0x45, 0x43, 0x49, 0x46, 0x49, 0x45, 0x44, 0x10, 0x00, 0x12,
0x0c, 0x0a, 0x08, 0x52, 0x49, 0x53, 0x4b, 0x5f, 0x4c, 0x4f, 0x57, 0x10, 0x01, 0x12, 0x0f, 0x0a,
0x0b, 0x52, 0x49, 0x53, 0x4b, 0x5f, 0x4d, 0x45, 0x44, 0x49, 0x55, 0x4d, 0x10, 0x02, 0x12, 0x0d,
0x0a, 0x09, 0x52, 0x49, 0x53, 0x4b, 0x5f, 0x48, 0x49, 0x47, 0x48, 0x10, 0x03, 0x12, 0x0e, 0x0a,
0x0a, 0x52, 0x49, 0x53, 0x4b, 0x5f, 0x42, 0x4c, 0x4f, 0x43, 0x4b, 0x10, 0x04, 0x32, 0x5e, 0x0a,
0x0c, 0x46, 0x72, 0x61, 0x75, 0x64, 0x53, 0x65, 0x72, 0x76, 0x69, 0x63, 0x65, 0x12, 0x4e, 0x0a,
0x05, 0x53, 0x63, 0x6f, 0x72, 0x65, 0x12, 0x21, 0x2e, 0x67, 0x75, 0x65, 0x73, 0x74, 0x67, 0x75,
0x61, 0x72, 0x64, 0x2e, 0x66, 0x72, 0x61, 0x75, 0x64, 0x2e, 0x76, 0x31, 0x2e, 0x53, 0x63, 0x6f,
0x72, 0x65, 0x52, 0x65, 0x71, 0x75, 0x65, 0x73, 0x74, 0x1a, 0x22, 0x2e, 0x67, 0x75, 0x65, 0x73,
0x74, 0x67, 0x75, 0x61, 0x72, 0x64, 0x2e, 0x66, 0x72, 0x61, 0x75, 0x64, 0x2e, 0x76, 0x31, 0x2e,
0x53, 0x63, 0x6f, 0x72, 0x65, 0x52, 0x65, 0x73, 0x70, 0x6f, 0x6e, 0x73, 0x65, 0x42, 0x3d, 0x5a,
0x3b, 0x67, 0x69, 0x74, 0x68, 0x75, 0x62, 0x2e, 0x63, 0x6f, 0x6d, 0x2f, 0x61, 0x6c, 0x63, 0x68,
0x65, 0x6d, 0x69, 0x73, 0x74, 0x6b, 0x61, 0x79, 0x2f, 0x67, 0x75, 0x65, 0x73, 0x74, 0x67, 0x75,
0x61, 0x72, 0x64, 0x2f, 0x69, 0x6e, 0x74, 0x65, 0x72, 0x6e, 0x61, 0x6c, 0x2f, 0x66, 0x72, 0x61,
0x75, 0x64, 0x70, 0x62, 0x3b, 0x66, 0x72, 0x61, 0x75, 0x64, 0x70, 0x62, 0x62, 0x06, 0x70, 0x72,
0x6f, 0x74, 0x6f, 0x33,
}
var (
file_fraud_v1_fraud_proto_rawDescOnce sync.Once
file_fraud_v1_fraud_proto_rawDescData = file_fraud_v1_fraud_proto_rawDesc
)
func file_fraud_v1_fraud_proto_rawDescGZIP() []byte {
file_fraud_v1_fraud_proto_rawDescOnce.Do(func() {
file_fraud_v1_fraud_proto_rawDescData = protoimpl.X.CompressGZIP(file_fraud_v1_fraud_proto_rawDescData)
})
return file_fraud_v1_fraud_proto_rawDescData
}
var file_fraud_v1_fraud_proto_enumTypes = make([]protoimpl.EnumInfo, 1)
var file_fraud_v1_fraud_proto_msgTypes = make([]protoimpl.MessageInfo, 3)
var file_fraud_v1_fraud_proto_goTypes = []any{
(Risk)(0), // 0: guestguard.fraud.v1.Risk
(*ScoreRequest)(nil), // 1: guestguard.fraud.v1.ScoreRequest
(*ScoreResponse)(nil), // 2: guestguard.fraud.v1.ScoreResponse
nil, // 3: guestguard.fraud.v1.ScoreRequest.FingerprintEntry
}
var file_fraud_v1_fraud_proto_depIdxs = []int32{
3, // 0: guestguard.fraud.v1.ScoreRequest.fingerprint:type_name -> guestguard.fraud.v1.ScoreRequest.FingerprintEntry
0, // 1: guestguard.fraud.v1.ScoreResponse.risk:type_name -> guestguard.fraud.v1.Risk
1, // 2: guestguard.fraud.v1.FraudService.Score:input_type -> guestguard.fraud.v1.ScoreRequest
2, // 3: guestguard.fraud.v1.FraudService.Score:output_type -> guestguard.fraud.v1.ScoreResponse
3, // [3:4] is the sub-list for method output_type
2, // [2:3] is the sub-list for method input_type
2, // [2:2] is the sub-list for extension type_name
2, // [2:2] is the sub-list for extension extendee
0, // [0:2] is the sub-list for field type_name
}
func init() { file_fraud_v1_fraud_proto_init() }
func file_fraud_v1_fraud_proto_init() {
if File_fraud_v1_fraud_proto != nil {
return
}
if !protoimpl.UnsafeEnabled {
file_fraud_v1_fraud_proto_msgTypes[0].Exporter = func(v any, i int) any {
switch v := v.(*ScoreRequest); i {
case 0:
return &v.state
case 1:
return &v.sizeCache
case 2:
return &v.unknownFields
default:
return nil
}
}
file_fraud_v1_fraud_proto_msgTypes[1].Exporter = func(v any, i int) any {
switch v := v.(*ScoreResponse); i {
case 0:
return &v.state
case 1:
return &v.sizeCache
case 2:
return &v.unknownFields
default:
return nil
}
}
}
type x struct{}
out := protoimpl.TypeBuilder{
File: protoimpl.DescBuilder{
GoPackagePath: reflect.TypeOf(x{}).PkgPath(),
RawDescriptor: file_fraud_v1_fraud_proto_rawDesc,
NumEnums: 1,
NumMessages: 3,
NumExtensions: 0,
NumServices: 1,
},
GoTypes: file_fraud_v1_fraud_proto_goTypes,
DependencyIndexes: file_fraud_v1_fraud_proto_depIdxs,
EnumInfos: file_fraud_v1_fraud_proto_enumTypes,
MessageInfos: file_fraud_v1_fraud_proto_msgTypes,
}.Build()
File_fraud_v1_fraud_proto = out.File
file_fraud_v1_fraud_proto_rawDesc = nil
file_fraud_v1_fraud_proto_goTypes = nil
file_fraud_v1_fraud_proto_depIdxs = nil
}