{
  "feature": "email-verification",
  "version": "1.0.0",
  "description": "Verify user email ownership via a one-time token link",
  "category": "auth",
  "tags": [
    "email",
    "verification",
    "security",
    "identity",
    "onboarding"
  ],
  "fields": [
    {
      "name": "token",
      "type": "token",
      "required": true,
      "sensitive": true,
      "validation": [
        {
          "type": "required",
          "message": "Verification token is missing"
        }
      ],
      "label": "Token"
    },
    {
      "name": "email",
      "type": "email",
      "required": true,
      "label": "Email Address",
      "placeholder": "you@example.com",
      "validation": [
        {
          "type": "required",
          "message": "Email is required"
        },
        {
          "type": "email",
          "message": "Please enter a valid email address"
        }
      ]
    }
  ],
  "rules": {
    "security": {
      "token": {
        "type": "cryptographic_random",
        "length_bytes": 32,
        "hash_before_storage": true,
        "algorithm": "sha256"
      },
      "token_expiry": {
        "hours": 24
      },
      "single_use": true,
      "rate_limit_resend": {
        "window_seconds": 3600,
        "max_requests": 3,
        "scope": "per_email"
      },
      "rate_limit_verify": {
        "window_seconds": 60,
        "max_requests": 10,
        "scope": "per_ip"
      }
    },
    "email": {
      "case_sensitive": false,
      "trim_whitespace": true,
      "enumeration_prevention": true
    }
  },
  "outcomes": {
    "token_invalid": {
      "priority": 1,
      "error": "VERIFY_TOKEN_INVALID",
      "given": [
        {
          "any": [
            {
              "field": "token_hash",
              "source": "db",
              "operator": "not_exists",
              "description": "Token hash not found in database"
            },
            {
              "field": "token_used",
              "source": "db",
              "operator": "eq",
              "value": true,
              "description": "Token has already been used"
            }
          ]
        }
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "email_verification.token_invalid",
          "payload": [
            "token_hash",
            "timestamp",
            "ip_address"
          ]
        }
      ],
      "result": "show \"This verification link is invalid.\" with option to request a new one"
    },
    "token_expired": {
      "priority": 2,
      "error": "VERIFY_TOKEN_EXPIRED",
      "given": [
        {
          "field": "token_hash",
          "source": "db",
          "operator": "exists"
        },
        {
          "field": "token_created_at",
          "source": "db",
          "operator": "lt",
          "value": "now - 24 hours",
          "description": "Token has expired (older than 24 hours)"
        }
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "email_verification.token_expired",
          "payload": [
            "user_id",
            "timestamp",
            "ip_address"
          ]
        }
      ],
      "result": "show \"This verification link has expired.\" with option to request a new one"
    },
    "already_verified": {
      "priority": 3,
      "given": [
        {
          "field": "email_verified",
          "source": "db",
          "operator": "eq",
          "value": true,
          "description": "Email is already verified"
        }
      ],
      "result": "redirect to /login with message \"Email already verified. Please sign in.\""
    },
    "email_verified": {
      "priority": 10,
      "transaction": true,
      "given": [
        {
          "field": "token",
          "source": "input",
          "operator": "exists",
          "description": "Token is present in URL"
        },
        {
          "field": "token_hash",
          "source": "db",
          "operator": "exists",
          "description": "SHA-256 hash matches a DB record"
        },
        {
          "field": "token_created_at",
          "source": "db",
          "operator": "gte",
          "value": "now - 24 hours",
          "description": "Token has not expired"
        },
        {
          "field": "token_used",
          "source": "db",
          "operator": "eq",
          "value": false,
          "description": "Token has not been used (single-use)"
        },
        {
          "field": "status",
          "source": "db",
          "operator": "neq",
          "value": "disabled",
          "description": "User account is not disabled"
        }
      ],
      "then": [
        {
          "action": "set_field",
          "target": "email_verified",
          "value": true,
          "description": "Mark email as verified"
        },
        {
          "action": "set_field",
          "target": "token_used",
          "value": true,
          "description": "Mark token as used (single-use)"
        },
        {
          "action": "emit_event",
          "event": "email_verification.success",
          "payload": [
            "user_id",
            "email",
            "timestamp",
            "ip_address"
          ]
        }
      ],
      "result": "redirect to /login with message \"Email verified! You can now sign in.\""
    },
    "resend_rate_limited": {
      "priority": 1,
      "error": "VERIFY_RATE_LIMITED",
      "given": [
        {
          "field": "resend_count",
          "source": "computed",
          "operator": "gt",
          "value": 3,
          "description": "More than 3 resend requests in 1 hour for this email"
        }
      ],
      "result": "show \"If an account with that email exists, we've sent a new verification link.\" (same as success)"
    },
    "resend_unknown_email": {
      "priority": 2,
      "given": [
        {
          "any": [
            {
              "field": "user",
              "source": "db",
              "operator": "not_exists",
              "description": "Email not found in database"
            },
            {
              "field": "email_verified",
              "source": "db",
              "operator": "eq",
              "value": true,
              "description": "Email is already verified"
            }
          ]
        }
      ],
      "result": "show SAME message as resend_success (enumeration prevention)"
    },
    "resend_success": {
      "priority": 10,
      "transaction": true,
      "given": [
        {
          "field": "email",
          "source": "input",
          "operator": "matches",
          "value": "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$",
          "description": "Email is valid format"
        },
        {
          "field": "user",
          "source": "db",
          "operator": "exists",
          "description": "User exists"
        },
        {
          "field": "email_verified",
          "source": "db",
          "operator": "eq",
          "value": false,
          "description": "Email is not yet verified"
        }
      ],
      "then": [
        {
          "action": "invalidate",
          "target": "verification_tokens",
          "scope": "all_for_user",
          "description": "Invalidate previous verification tokens"
        },
        {
          "action": "create_record",
          "type": "verification_token",
          "target": "verification_token",
          "description": "Generate crypto.randomBytes(32), store SHA-256 hash, expires in 24h"
        },
        {
          "action": "notify",
          "channel": "email",
          "template": "verification_email",
          "to": "user",
          "description": "Send new verification link"
        },
        {
          "action": "emit_event",
          "event": "email_verification.resent",
          "payload": [
            "user_id",
            "email",
            "timestamp",
            "expires_at"
          ]
        }
      ],
      "result": "show \"If an account with that email exists, we've sent a new verification link.\""
    }
  },
  "errors": [
    {
      "code": "VERIFY_TOKEN_INVALID",
      "status": 400,
      "message": "This verification link is invalid. Please request a new one.",
      "retry": false,
      "redirect": "resend-verification"
    },
    {
      "code": "VERIFY_TOKEN_EXPIRED",
      "status": 400,
      "message": "This verification link has expired. Please request a new one.",
      "retry": false,
      "redirect": "resend-verification"
    },
    {
      "code": "VERIFY_RATE_LIMITED",
      "status": 429,
      "message": "Too many requests. Please wait before trying again.",
      "retry": false
    },
    {
      "code": "VERIFY_VALIDATION_ERROR",
      "status": 422,
      "message": "Please check your input and try again",
      "retry": true
    }
  ],
  "events": [
    {
      "name": "email_verification.success",
      "description": "User successfully verified their email",
      "payload": [
        "user_id",
        "email",
        "timestamp",
        "ip_address"
      ]
    },
    {
      "name": "email_verification.token_invalid",
      "description": "Invalid or tampered verification token submitted",
      "payload": [
        "token_hash",
        "timestamp",
        "ip_address"
      ]
    },
    {
      "name": "email_verification.token_expired",
      "description": "Expired verification token submitted",
      "payload": [
        "user_id",
        "timestamp",
        "ip_address"
      ]
    },
    {
      "name": "email_verification.resent",
      "description": "New verification email sent",
      "payload": [
        "user_id",
        "email",
        "timestamp",
        "expires_at"
      ]
    }
  ],
  "related": [
    {
      "feature": "signup",
      "type": "required",
      "reason": "Verification is triggered by signup"
    },
    {
      "feature": "login",
      "type": "required",
      "reason": "After verification, user logs in",
      "ui_link": "Back to sign in",
      "ui_link_position": "below_form"
    }
  ],
  "agi": {
    "goals": [
      {
        "id": "reliable_email_verification",
        "description": "Verify user email ownership via a one-time token link",
        "success_metrics": [
          {
            "metric": "unauthorized_access_rate",
            "target": "0%",
            "measurement": "Failed authorization attempts that succeed"
          },
          {
            "metric": "response_time_p95",
            "target": "< 500ms",
            "measurement": "95th percentile response time"
          }
        ],
        "constraints": [
          {
            "type": "security",
            "description": "Follow OWASP security recommendations",
            "negotiable": false
          },
          {
            "type": "security",
            "description": "Sensitive fields must be encrypted at rest and never logged in plaintext",
            "negotiable": false
          }
        ]
      }
    ],
    "autonomy": {
      "level": "supervised",
      "human_checkpoints": [
        "before modifying sensitive data fields"
      ],
      "escalation_triggers": [
        "error_rate > 5",
        "consecutive_failures > 3"
      ]
    },
    "safety": {
      "action_permissions": [
        {
          "action": "token_invalid",
          "permission": "autonomous"
        },
        {
          "action": "token_expired",
          "permission": "autonomous"
        },
        {
          "action": "already_verified",
          "permission": "autonomous"
        },
        {
          "action": "email_verified",
          "permission": "autonomous"
        },
        {
          "action": "resend_rate_limited",
          "permission": "autonomous"
        },
        {
          "action": "resend_unknown_email",
          "permission": "autonomous"
        },
        {
          "action": "resend_success",
          "permission": "autonomous"
        }
      ]
    },
    "tradeoffs": [
      {
        "prefer": "security",
        "over": "performance",
        "reason": "authentication must prioritize preventing unauthorized access"
      }
    ],
    "verification": {
      "invariants": [
        "sensitive fields are never logged in plaintext",
        "all data access is authenticated and authorized",
        "error messages never expose internal system details"
      ]
    },
    "coordination": {
      "protocol": "request_response",
      "consumes": [
        {
          "capability": "signup",
          "from": "signup",
          "fallback": "fail"
        },
        {
          "capability": "login",
          "from": "login",
          "fallback": "fail"
        }
      ]
    }
  },
  "ui_hints": {
    "screens": {
      "verify": {
        "layout": "single_column_centered",
        "max_width": "420px",
        "show_logo": true,
        "title": "Verifying your email..."
      },
      "resend": {
        "layout": "single_column_centered",
        "max_width": "420px",
        "show_logo": true,
        "title": "Resend verification email",
        "subtitle": "Enter your email and we'll send a new verification link",
        "fields_order": [
          "email"
        ],
        "actions": {
          "primary": {
            "label": "Resend verification email",
            "type": "submit",
            "full_width": true
          }
        },
        "links": [
          {
            "label": "Back to sign in",
            "target": "login",
            "position": "below_form"
          }
        ]
      }
    },
    "accessibility": {
      "aria_live_region": true
    },
    "loading": {
      "disable_button": true,
      "show_spinner": true,
      "prevent_double_submit": true
    }
  },
  "extensions": {
    "nextjs": {
      "routes": {
        "verify": "/verify-email",
        "resend": "/resend-verification"
      },
      "layout": "(auth)",
      "server_action": true
    },
    "express": {
      "routes": {
        "verify": "/api/auth/verify-email",
        "resend": "/api/auth/resend-verification"
      },
      "middleware": [
        "rate-limit",
        "cors"
      ]
    },
    "laravel": {
      "routes": {
        "verify": "/verify-email/{token}",
        "resend": "/resend-verification"
      },
      "middleware": [
        "guest"
      ],
      "notification": "VerifyEmail"
    }
  }
}