feat: add Meta App Review access mode

- Add token-gated, short-lived reviewer sessions outside LINE LIFF\n- Preserve review authentication through Facebook OAuth redirects\n- Keep Rich Menu actions disabled for review sessions and document Railway configuration\n- Cover review session creation, expiration, and protected API access\n\nThis gives Meta reviewers a revocable browser-based test flow without weakening normal LINE authentication.

Author: Pachared

apps/api/.env.example

@@ -3,6 +3,11 @@ APP_URL=http://localhost:5173
 API_URL=http://localhost:8080
 PORT=8080
 
+# Enable only while Meta reviews the app. Use a long random value and share
+# the resulting review URL only through the Meta App Review submission.
+META_REVIEW_ENABLED=false
+META_REVIEW_TOKEN=
+
 DB_DSN=host=127.0.0.1 user=linora password=linora dbname=linora port=5433 sslmode=disable TimeZone=Asia/Bangkok
 REDIS_URL=redis://127.0.0.1:6379/0
 

apps/api/internal/config/config.go

@@ -32,13 +32,19 @@ type LineConfig struct {
 	DashboardRichMenuID string
 }
 
+type MetaReviewConfig struct {
+	Enabled bool
+	Token   string
+}
+
 type Config struct {
 	AI            AIConfig
 	DatabaseDSN   string
 	EncryptionKey string
 	Environment   string
 	Facebook      FacebookConfig
 	Line          LineConfig
+	MetaReview    MetaReviewConfig
 	Port          string
 	RedisURL      string
 }
@@ -78,16 +84,30 @@ func Load() (Config, error) {
 			ConnectRichMenuID:   os.Getenv("LINE_RICH_MENU_CONNECT_ID"),
 			DashboardRichMenuID: os.Getenv("LINE_RICH_MENU_DASHBOARD_ID"),
 		},
+		MetaReview: MetaReviewConfig{
+			Enabled: strings.EqualFold(strings.TrimSpace(os.Getenv("META_REVIEW_ENABLED")), "true"),
+			Token:   strings.TrimSpace(os.Getenv("META_REVIEW_TOKEN")),
+		},
 	}
 	if err := cfg.AI.Validate(); err != nil {
 		return Config{}, err
 	}
 	if err := cfg.Facebook.Validate(); err != nil {
 		return Config{}, err
 	}
+	if err := cfg.MetaReview.Validate(); err != nil {
+		return Config{}, err
+	}
 	return cfg, nil
 }
 
+func (c MetaReviewConfig) Validate() error {
+	if c.Enabled && c.Token == "" {
+		return fmt.Errorf("missing required Meta review environment variable: META_REVIEW_TOKEN")
+	}
+	return nil
+}
+
 func (c FacebookConfig) Validate() error {
 	missing := make([]string, 0, 6)
 	if strings.TrimSpace(c.AppID) == "" {

apps/api/internal/config/config_test.go

@@ -35,3 +35,15 @@ func TestFacebookConfigValidateRequiresEveryEnvironmentValue(t *testing.T) {
 		}
 	}
 }
+
+func TestMetaReviewConfigRequiresTokenOnlyWhenEnabled(t *testing.T) {
+	if err := (MetaReviewConfig{}).Validate(); err != nil {
+		t.Fatalf("disabled review mode should be valid: %v", err)
+	}
+	if err := (MetaReviewConfig{Enabled: true}).Validate(); err == nil {
+		t.Fatal("enabled review mode should require a token")
+	}
+	if err := (MetaReviewConfig{Enabled: true, Token: "review-token"}).Validate(); err != nil {
+		t.Fatalf("enabled review mode with a token should be valid: %v", err)
+	}
+}

apps/api/internal/controllers/meta_review_controller.go

@@ -0,0 +1,32 @@
+package controllers
+
+import (
+	"net/http"
+
+	"github.com/fulltank-garage/linora/apps/api/internal/services"
+	"github.com/gin-gonic/gin"
+)
+
+type MetaReviewController struct {
+	sessions *services.MetaReviewSessionService
+}
+
+func NewMetaReviewController(sessions *services.MetaReviewSessionService) *MetaReviewController {
+	return &MetaReviewController{sessions: sessions}
+}
+
+func (c *MetaReviewController) CreateSession(ctx *gin.Context) {
+	var input struct {
+		Token string `json:"token"`
+	}
+	if err := ctx.ShouldBindJSON(&input); err != nil {
+		ctx.JSON(http.StatusBadRequest, gin.H{"error": "invalid Meta review request"})
+		return
+	}
+	session, err := c.sessions.Create(input.Token)
+	if err != nil {
+		ctx.JSON(http.StatusNotFound, gin.H{"error": "Meta review access is unavailable"})
+		return
+	}
+	ctx.JSON(http.StatusOK, gin.H{"session": session})
+}

apps/api/internal/middleware/cors.go

@@ -20,7 +20,7 @@ func CORS(appURL string) gin.HandlerFunc {
 		if allowedOrigins[origin] {
 			c.Header("Access-Control-Allow-Origin", origin)
 			c.Header("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS")
-			c.Header("Access-Control-Allow-Headers", "Content-Type, Authorization, X-Linora-Dev-User")
+			c.Header("Access-Control-Allow-Headers", "Content-Type, Authorization, X-Linora-Dev-User, X-Linora-Review-Session")
 		}
 
 		if c.Request.Method == http.MethodOptions {

apps/api/internal/middleware/line_identity.go

@@ -10,12 +10,36 @@ import (
 
 const lineUserIDKey = "linora.lineUserID"
 
+const MetaReviewSessionHeader = "X-Linora-Review-Session"
+
 type LineIdentityVerifier interface {
 	VerifyIDToken(context.Context, string) (string, error)
 }
 
+type MetaReviewSessionVerifier interface {
+	Verify(string) (string, error)
+}
+
 func RequireLineIdentity(verifier LineIdentityVerifier, environment string) gin.HandlerFunc {
+	return RequireIdentity(verifier, environment, nil)
+}
+
+// RequireIdentity accepts the normal LINE identity or, when explicitly
+// enabled, a short-lived Meta app-review session.
+func RequireIdentity(verifier LineIdentityVerifier, environment string, review MetaReviewSessionVerifier) gin.HandlerFunc {
 	return func(c *gin.Context) {
+		if review != nil {
+			if session := strings.TrimSpace(c.GetHeader(MetaReviewSessionHeader)); session != "" {
+				userID, err := review.Verify(session)
+				if err != nil {
+					c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "Meta review session has expired. Please use the review link again."})
+					return
+				}
+				c.Set(lineUserIDKey, userID)
+				c.Next()
+				return
+			}
+		}
 		if strings.EqualFold(environment, "development") {
 			if userID := strings.TrimSpace(c.GetHeader("X-Linora-Dev-User")); userID != "" {
 				c.Set(lineUserIDKey, userID)

apps/api/internal/routes/router.go

@@ -23,7 +23,9 @@ func NewRouter(cfg config.Config, analysisService *services.AnalysisService, fac
 	router.Use(middleware.RateLimit(apiRequestsPerMinute, time.Minute))
 
 	facebookController := controllers.NewFacebookController(facebookService, pageService)
-	requireLineIdentity := middleware.RequireLineIdentity(lineIdentity, cfg.Environment)
+	metaReviewSessions := services.NewMetaReviewSessionService(cfg.MetaReview)
+	metaReviewController := controllers.NewMetaReviewController(metaReviewSessions)
+	requireLineIdentity := middleware.RequireIdentity(lineIdentity, cfg.Environment, metaReviewSessions)
 	if pageService != nil && lineService != nil {
 		integrationController := controllers.NewIntegrationController(pageService, lineService, cfg.Line.ChannelSecret, middleware.NewRateLimiter(lineMessagesPerUserPerMinute, time.Minute))
 		facebook := router.Group("/api/facebook", requireLineIdentity)
@@ -48,6 +50,7 @@ func NewRouter(cfg config.Config, analysisService *services.AnalysisService, fac
 		c.JSON(http.StatusOK, gin.H{"status": "ok", "service": "linora-api"})
 	})
 	router.POST("/api/facebook/login", requireLineIdentity, facebookController.Begin)
+	router.POST("/api/meta-review/session", metaReviewController.CreateSession)
 	router.GET("/api/facebook/callback", facebookController.Callback)
 	router.GET("/api/facebook/session", requireLineIdentity, facebookController.Session)
 	router.POST("/api/facebook/deauthorize", facebookController.Deauthorize)

apps/api/internal/routes/router_test.go

@@ -1,11 +1,14 @@
 package routes
 
 import (
+	"bytes"
+	"encoding/json"
 	"net/http"
 	"net/http/httptest"
 	"testing"
 
 	"github.com/fulltank-garage/linora/apps/api/internal/config"
+	"github.com/fulltank-garage/linora/apps/api/internal/middleware"
 	"github.com/fulltank-garage/linora/apps/api/internal/services"
 )
 
@@ -39,3 +42,32 @@ func TestFacebookDeauthorizeRouteIsPublic(t *testing.T) {
 		t.Fatalf("status = %d, want %d", recorder.Code, http.StatusServiceUnavailable)
 	}
 }
+
+func TestMetaReviewSessionAllowsFacebookLoginWithoutLINE(t *testing.T) {
+	cfg := config.Config{
+		Environment: "production",
+		MetaReview:  config.MetaReviewConfig{Enabled: true, Token: "review-access-token"},
+		Port:        "8080",
+	}
+	router := NewRouter(cfg, services.NewAnalysisService(), services.NewFacebookService(cfg.Facebook), nil, nil, services.NewLineIdentityService(cfg.Line))
+	payload, _ := json.Marshal(map[string]string{"token": "review-access-token"})
+	createRecorder := httptest.NewRecorder()
+	router.ServeHTTP(createRecorder, httptest.NewRequest(http.MethodPost, "/api/meta-review/session", bytes.NewReader(payload)))
+	if createRecorder.Code != http.StatusOK {
+		t.Fatalf("session status = %d, want %d", createRecorder.Code, http.StatusOK)
+	}
+	var sessionResponse struct {
+		Session string `json:"session"`
+	}
+	if err := json.Unmarshal(createRecorder.Body.Bytes(), &sessionResponse); err != nil || sessionResponse.Session == "" {
+		t.Fatalf("invalid session response: %v", err)
+	}
+
+	loginRequest := httptest.NewRequest(http.MethodPost, "/api/facebook/login", nil)
+	loginRequest.Header.Set(middleware.MetaReviewSessionHeader, sessionResponse.Session)
+	loginRecorder := httptest.NewRecorder()
+	router.ServeHTTP(loginRecorder, loginRequest)
+	if loginRecorder.Code != http.StatusServiceUnavailable {
+		t.Fatalf("login status = %d, want %d", loginRecorder.Code, http.StatusServiceUnavailable)
+	}
+}

apps/api/internal/services/meta_review_session.go

@@ -0,0 +1,93 @@
+package services
+
+import (
+	"crypto/hmac"
+	"crypto/sha256"
+	"crypto/subtle"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"strings"
+	"time"
+
+	"github.com/fulltank-garage/linora/apps/api/internal/config"
+)
+
+const MetaReviewSessionLifetime = 8 * time.Hour
+
+var ErrMetaReviewUnavailable = errors.New("Meta review access is unavailable")
+var ErrInvalidMetaReviewToken = errors.New("invalid Meta review access")
+
+type metaReviewSessionPayload struct {
+	ExpiresAt int64  `json:"exp"`
+	OwnerID   string `json:"sub"`
+}
+
+// MetaReviewSessionService creates short-lived identities for Meta reviewers.
+// It is enabled explicitly through environment variables and does not change
+// the normal LINE LIFF authentication flow.
+type MetaReviewSessionService struct {
+	enabled bool
+	now     func() time.Time
+	secret  []byte
+	ownerID string
+}
+
+func NewMetaReviewSessionService(cfg config.MetaReviewConfig) *MetaReviewSessionService {
+	token := strings.TrimSpace(cfg.Token)
+	digest := sha256.Sum256([]byte(token))
+	return &MetaReviewSessionService{
+		enabled: cfg.Enabled && token != "",
+		now:     time.Now,
+		secret:  []byte(token),
+		ownerID: "meta-review:" + base64.RawURLEncoding.EncodeToString(digest[:12]),
+	}
+}
+
+func (s *MetaReviewSessionService) Create(accessToken string) (string, error) {
+	if !s.enabled {
+		return "", ErrMetaReviewUnavailable
+	}
+	if subtle.ConstantTimeCompare([]byte(strings.TrimSpace(accessToken)), s.secret) != 1 {
+		return "", ErrInvalidMetaReviewToken
+	}
+	payload, err := json.Marshal(metaReviewSessionPayload{
+		ExpiresAt: s.now().Add(MetaReviewSessionLifetime).Unix(),
+		OwnerID:   s.ownerID,
+	})
+	if err != nil {
+		return "", err
+	}
+	encodedPayload := base64.RawURLEncoding.EncodeToString(payload)
+	mac := hmac.New(sha256.New, s.secret)
+	_, _ = mac.Write([]byte(encodedPayload))
+	return encodedPayload + "." + base64.RawURLEncoding.EncodeToString(mac.Sum(nil)), nil
+}
+
+func (s *MetaReviewSessionService) Verify(session string) (string, error) {
+	if !s.enabled {
+		return "", ErrMetaReviewUnavailable
+	}
+	parts := strings.Split(session, ".")
+	if len(parts) != 2 {
+		return "", ErrInvalidMetaReviewToken
+	}
+	providedMAC, err := base64.RawURLEncoding.DecodeString(parts[1])
+	if err != nil {
+		return "", ErrInvalidMetaReviewToken
+	}
+	mac := hmac.New(sha256.New, s.secret)
+	_, _ = mac.Write([]byte(parts[0]))
+	if !hmac.Equal(providedMAC, mac.Sum(nil)) {
+		return "", ErrInvalidMetaReviewToken
+	}
+	payloadBytes, err := base64.RawURLEncoding.DecodeString(parts[0])
+	if err != nil {
+		return "", ErrInvalidMetaReviewToken
+	}
+	var payload metaReviewSessionPayload
+	if err := json.Unmarshal(payloadBytes, &payload); err != nil || payload.OwnerID != s.ownerID || payload.ExpiresAt <= s.now().Unix() {
+		return "", ErrInvalidMetaReviewToken
+	}
+	return payload.OwnerID, nil
+}

apps/api/internal/services/meta_review_session_test.go

@@ -0,0 +1,42 @@
+package services
+
+import (
+	"testing"
+	"time"
+
+	"github.com/fulltank-garage/linora/apps/api/internal/config"
+)
+
+func TestMetaReviewSessionLifecycle(t *testing.T) {
+	service := NewMetaReviewSessionService(config.MetaReviewConfig{Enabled: true, Token: "review-access-token"})
+	service.now = func() time.Time { return time.Date(2026, 7, 30, 10, 0, 0, 0, time.UTC) }
+
+	session, err := service.Create("review-access-token")
+	if err != nil {
+		t.Fatalf("Create returned error: %v", err)
+	}
+	ownerID, err := service.Verify(session)
+	if err != nil {
+		t.Fatalf("Verify returned error: %v", err)
+	}
+	if ownerID == "" || ownerID[:12] != "meta-review:" {
+		t.Fatalf("owner ID = %q, want a meta review owner", ownerID)
+	}
+	if _, err := service.Create("wrong-token"); err == nil {
+		t.Fatal("Create accepted an invalid token")
+	}
+}
+
+func TestMetaReviewSessionExpires(t *testing.T) {
+	service := NewMetaReviewSessionService(config.MetaReviewConfig{Enabled: true, Token: "review-access-token"})
+	now := time.Date(2026, 7, 30, 10, 0, 0, 0, time.UTC)
+	service.now = func() time.Time { return now }
+	session, err := service.Create("review-access-token")
+	if err != nil {
+		t.Fatalf("Create returned error: %v", err)
+	}
+	service.now = func() time.Time { return now.Add(MetaReviewSessionLifetime + time.Second) }
+	if _, err := service.Verify(session); err == nil {
+		t.Fatal("Verify accepted an expired session")
+	}
+}