xolo-server 1.0.0 → 2.0.2

data/lib/xolo/core.rb

@@ -0,0 +1,47 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+#
+
+# frozen_string_literal: true
+
+# Load the core xolo functionality
+#
+# This is done automatically when you `require 'xolo/admin'` or
+# `require 'xolo/server'`
+
+# Ruby Standard Libraries
+######
+require 'English'
+require 'date'
+require 'time'
+require 'pathname'
+require 'json'
+
+# Other Gems to include at this level
+require 'pixar-ruby-extensions'
+
+# Internal requires - order matters
+require 'xolo/core/loading'
+require 'xolo/core/version'
+require 'xolo/core/constants'
+require 'xolo/core/exceptions'
+
+# The main module
+module Xolo
+
+  extend Xolo::Core::Loading
+  include Xolo::Core::Version
+  include Xolo::Core::Constants
+  include Xolo::Core::Exceptions
+
+end # module Xolo
+
+require 'xolo/core/json_wrappers'
+require 'xolo/core/security_cmd'
+require 'xolo/core/base_classes/configuration'
+require 'xolo/core/base_classes/server_object'
+require 'xolo/core/base_classes/title'
+require 'xolo/core/base_classes/version'
+require 'xolo/core/output'

data/lib/xolo/server/app.rb

@@ -19,6 +19,7 @@ module Xolo
       ##############################
       ##############################
 
+      # register Sinatra extensions - this 'extends' the app class with the extension's methods
       register Xolo::Server::Routes
       register Xolo::Server::Routes::Auth
       register Xolo::Server::Routes::Maint
@@ -27,9 +28,13 @@ module Xolo
       register Xolo::Server::Routes::Titles
       register Xolo::Server::Routes::Versions
       register Xolo::Server::Routes::Uploads
+      register Xolo::Server::Routes::Subscriptions
 
+      # include helper modules - this 'includes' the app class with the helper module's methods
+      # making them available as instance methods in routes and views
       helpers Xolo::Core::Constants
       helpers Xolo::Core::JSONWrappers
+      helpers Xolo::Core::SecurityCmd
       helpers Xolo::Server::Helpers::Log
       helpers Xolo::Server::Helpers::Notification
       helpers Xolo::Server::Helpers::Auth
@@ -41,7 +46,9 @@ module Xolo
       helpers Xolo::Server::Helpers::PkgSigning
       helpers Xolo::Server::Helpers::ProgressStreaming
       helpers Xolo::Server::Helpers::ClientData
+      helpers Xolo::Server::Helpers::Subscriptions
       helpers Xolo::Server::Helpers::Maintenance
+      helpers Xolo::Server::Helpers::AutoPkg
 
       # Sinatra setup
       ##############################

data/lib/xolo/server/configuration.rb

@@ -79,6 +79,18 @@ module Xolo
       # The attribute keys we maintain, and their definitions
       KEYS = {
 
+        # @!attribute test_server
+        #   @return [Boolean] Is this a development/testing server? If so, Objects in Jamf will have
+        #      the prefix 'Xolo-Test-' rather than just 'Xolo-' to avoid confusion and collision with production objects,
+        #      and some other things may be different as well.
+        test_server: {
+          type: :boolean,
+          desc: <<~ENDDESC
+            Is this a development/testing server? If so, Objects in Jamf will have the prefix 'xolotest-' rather than just 'xolo-'
+            to avoid confusion and collision with production objects, and some other things may be different as well.
+          ENDDESC
+        },
+
         # @!attribute ssl_cert
         #   @return [String] A command, path, or value for the SSL Cert.
         ssl_cert: {
@@ -89,7 +101,8 @@ module Xolo
           desc: <<~ENDDESC
             The SSL Certificate for the https server in .pem format. When the server starts, it will be read from here, and securely stored in #{SSL_CERT_FILE}.
 
-            If you start this value with a vertical bar '|', everything after the bar is a command to be executed by the server at start-time. The command must return the certificate to standard output. This is useful when using a secret-storage system to manage secrets.
+            If you start this value with a vertical bar '|', everything after the bar is a command to be executed by the server at start-time.
+            The command must return the certificate to standard output. This is useful when using a secret-storage system to manage secrets.
 
             If the value is a path to a readable file, the file's contents are used.
 
@@ -109,7 +122,8 @@ module Xolo
           desc: <<~ENDDESC
             The private key for the SSL Certificate in .pem format. When the server starts, it will be read from here, and securely stored in #{SSL_KEY_FILE}/
 
-            If you start this value with a vertical bar '|', everything after the bar is a command to be executed by the server at start-time. The command must return the certificate to standard output. This is useful when using a secret-storage system to manage secrets.
+            If you start this value with a vertical bar '|', everything after the bar is a command to be executed by the server at start-time.
+            The command must return the certificate to standard output. This is useful when using a secret-storage system to manage secrets.
 
             If the value is a path to a readable file, the file's contents are used.
 
@@ -135,7 +149,8 @@ module Xolo
           required: true,
           type: :string,
           desc: <<~ENDDESC
-            The name of a Jamf account-group (not a User group) that allows the use of 'xadm' to create and maintain titles and versions. Users of xadm must be in this group, and provide their valid Jamf credentials.
+            The name of a Jamf account-group (not a User group) that allows the use of 'xadm' to create and maintain titles and versions.
+            Users of xadm must be in this group, and provide their valid Jamf credentials.
           ENDDESC
         },
 
@@ -144,7 +159,9 @@ module Xolo
         server_admin_jamf_group: {
           type: :string,
           desc: <<~ENDDESC
-            The name of a Jamf account-group (not a User group) that allows the use of the server admin commands of 'xadm', including --run-server-cleanup, --update-client-data, --rotate-server-logs and --set-server-log-level.
+            The name of a Jamf account-group (not a User group) that allows the use of the server admin commands of 'xadm', including --run-server-cleanup,
+            --update-client-data, --rotate-server-logs and --set-server-log-level.
+
             Members of this group can also use the xadm commands that require the 'admin_jamf_group' group.
             If unset, no one can use the server admin commands.
           ENDDESC
@@ -156,7 +173,8 @@ module Xolo
           default: Xolo::Server::Log::DFT_LOG_DAYS_TO_KEEP,
           type: :integer,
           desc: <<~ENDDESC
-            The server log is rotated daily. How many days of log files should be kept? All logs are kept in #{Xolo::Server::LOG_DIR}. The current file is named '#{Xolo::Server::LOG_FILE_NAME}', older files are appended with '.0' for yesterday, '.1' for the previous day, etc.
+            The server log is rotated daily. How many days of log files should be kept? All logs are kept in #{Xolo::Server::LOG_DIR}.
+            The current file is named '#{Xolo::Server::LOG_FILE_NAME}', older files are appended with '.0' for yesterday, '.1' for the previous day, etc.
           ENDDESC
         },
 
@@ -166,7 +184,9 @@ module Xolo
           default: Xolo::Server::Log::DFT_LOG_COMPRESS_AFTER_DAYS,
           type: :integer,
           desc: <<~ENDDESC
-            Once a log file is rotated, how many days before it is compressed? Compressed logs are named '#{Xolo::Server::LOG_FILE_NAME}.XX.bz2'. It can be accessed using the various bzip2 tools (bzip2, bunzip2, bzcat, bzgrep, etc). If this number is negative, or larger than log_days_to_keep, no logs will be compressed, if it is zero, all older logs will be compressed.
+            Once a log file is rotated, how many days before it is compressed? Compressed logs are named '#{Xolo::Server::LOG_FILE_NAME}.XX.bz2'.
+            It can be accessed using the various bzip2 tools (bzip2, bunzip2, bzcat, bzgrep, etc). If this number is negative, or larger than log_days_to_keep,
+            no logs will be compressed, if it is zero, all older logs will be compressed.
           ENDDESC
         },
 
@@ -177,18 +197,23 @@ module Xolo
         alert_tool: {
           type: :string,
           desc: <<~ENDDESC
-            Server errors or other events that happen as part of xadm actions are reported to the xadm user. But sometimes such events happen outside of the scope of a xadm session. While these events will be logged, you might want them reported to a server administrator in real time.
+            Server errors or other events that happen as part of xadm actions are reported to the xadm user. But sometimes such events happen outside of the scope
+            of a xadm session. While these events will be logged, you might want them reported to a server administrator in real time.
 
             This value is either:
 
-            - a command (path to executable plus CLI args) on the Xolo server which will accept an error or other alert message on standard input and send it somewhere where it'll be seen by an appropriate audiance, be that an email address, a Slack channel - anything you'd like.
+            - a command (path to executable plus CLI args) on the Xolo server which will accept an error or other alert message on standard input and send it
+            somewhere where it'll be seen by an appropriate audiance, be that an email address, a Slack channel - anything you'd like.
 
-            - or a string "email:email_address" where email_address is the email address to send alerts to. In this case, the server will send an email to that address using the smtp_server and email_from configuration values.
+            - or a string "#{Xolo::Server::Helpers::Notification::ALERT_TOOL_EMAIL_PREFIX}email_address" where email_address is the email address to send alerts to.
+            In this case, the server will send an email to that address using the smtp_server and email_from configuration values.
 
             Fictional command example:
                /path/to/slackerator --sender xolo-server --channel xolo-alerts --icon dante
             Fictional email example:
-               email:xolo-server-admins@myschool.edu
+               #{Xolo::Server::Helpers::Notification::ALERT_TOOL_EMAIL_PREFIX}xolo-server-admins@myschool.edu
+
+            While not required, it is strongly recommended to use this, so that server admins are made aware of issues that need their attention.
           ENDDESC
         },
 
@@ -220,7 +245,8 @@ module Xolo
           desc: <<~ENDDESC
             The password to unlock the keychain used for package signing.
 
-            If you start this value with a vertical bar '|', everything after the bar is a command to be executed by the server at start-time. The command must return the certificate to standard output. This is useful when using a secret-storage system to manage secrets.
+            If you start this value with a vertical bar '|', everything after the bar is a command to be executed by the server at start-time.
+            The command must return the certificate to standard output. This is useful when using a secret-storage system to manage secrets.
 
             If the value is a path to a readable file, the file's contents are used.
 
@@ -235,16 +261,36 @@ module Xolo
         sign_pkgs: {
           type: :boolean,
           desc: <<~ENDDESC
-            When someone uses xadm to upload a .pkg, and it isn't signed, should the server sign it before uploading to Jamf's Distribution Point(s)?
+            When a .pkg, is received for a version and it isn't signed, should the server sign it before uploading to Jamf's Distribution Point(s)?
 
             If you set this to true, it will use the same keychain and identity as the 'pkg_signing_identity' config value to sign the pkg, using the keychain you installed at:
               /Library/Application Support/xoloserver/xolo-pkg-signing.keychain-db
 
+            Packages must be signed distribution packages to work with the `xadm deploy` command, which uses MDM to push the package to client machines.
+
             NOTE: While it may seem insecure to allow the server to sign pkgs, consider:
             - Users of xadm are authenticated and authorized to use the server (see 'admin_jamf_group')
             - You don't need to distribute your signing certificates to a wide group of individual developers.
             - While you need to trust your xadm users not to upload a malicious pkg, this would be true
               even if you deployed the certs to them, so keeping the certs on the server is more secure.
+
+            See also the 'sign_autopkg_pkgs' abd 'create_distribution_pkgs' config values.
+          ENDDESC
+        },
+
+        # @!attribute create_distribution_pkgs
+        #   @return [Boolean] When processing uploaded pkgs, should we wrap component pkgs in distribution pkgs?
+        create_distribution_pkgs: {
+          type: :boolean,
+          desc: <<~ENDDESC
+            When a .pkg, is received for a version and it is a component package, should the server wrap it in a distribution package before uploading to Jamf's Distribution Point(s)?
+
+            If you set this to true, component packages will be wrapped in a distribution package using the productbuild tool, like so:
+                /usr/bin/productbuild –package /path/to/recieved.pkg /path/to/distribution_package.pkg
+
+            If sign_pkgs is true, the distribution package will be signed, otherwise it will be unsigned.
+
+            Packages must be signed distribution packages to work with the `xadm deploy` command, which uses MDM to push the package to client machines.
           ENDDESC
         },
 
@@ -256,7 +302,8 @@ module Xolo
           desc: <<~ENDDESC
             The name of a Jamf account-group (not a User group) whose members may set a title's release_groups to 'all'.
 
-            When this is set, and someone not in this group tries to set a title's release_groups to 'all', they will get a message telling them to contact the person or group named in 'release_to_all_contact' to get approval.
+            When this is set, and someone not in this group tries to set a title's release_groups to 'all', they will get a message telling
+            them to contact the person or group named in 'release_to_all_contact' to get approval.
 
             To approve the request, one of the members of this group must run 'xadm edit-title <title> --release-groups all'.
 
@@ -270,7 +317,8 @@ module Xolo
           required: false,
           type: :string,
           desc: <<~ENDDESC
-            When release_to_all_jamf_group is set, and someone not in that group tries to set a title's release_groups to 'all', they are told to use this contact info to get approval.
+            When release_to_all_jamf_group is set, and someone not in that group tries to set a title's release_groups to 'all', they are
+            old to use this contact info to get approval.
 
             This string could be an email address, a chat channel, a phone number, etc.
 
@@ -305,11 +353,13 @@ module Xolo
           default: Xolo::Server::Helpers::Maintenance::DFT_DEPRECATED_LIFETIME_DAYS,
           type: :integer,
           desc: <<~ENDDESC
-            When a version is deprecated, it will be automatically deleted by the nightly cleanup this many days later. If set to 0 or less, deprecated versions will never be deleted.
+            When a version is deprecated, it will be automatically deleted by the nightly cleanup this many days later. If set to 0 or less,
+            deprecated versions will never be deleted.
 
             Deprecated versions are those that have been released, but a newer version has been released since then.
 
-            WARNING: If you set this to 0 or less, you will need to manually delete deprecated versions. Keeping them around can cause confusion and clutter in the GUI, and use up disk space.
+            WARNING: If you set this to 0 or less, you will need to manually delete deprecated versions. Keeping them around can cause confusion
+            and clutter in the GUI, and use up disk space.
           ENDDESC
         },
 
@@ -323,7 +373,8 @@ module Xolo
 
             Skipped versions are those that were never released, but a newer version has been released.
 
-            WARNING: If you set this to true, you will need to manually delete skipped versions. Keeping them around can cause confusion and clutter in the GUI, and use up disk space.
+            WARNING: If you set this to true, you will need to manually delete skipped versions. Keeping them around can cause confusion
+            and clutter in the GUI, and use up disk space.
           ENDDESC
         },
 
@@ -336,9 +387,11 @@ module Xolo
           default: Xolo::Server::Helpers::Maintenance::DFT_UNRELEASED_PILOTS_NOTIFICATION_DAYS,
           type: :integer,
           desc: <<~ENDDESC
-            If the newest pilot of a title has not been released in this many days, notify someone about it monthly, asking to release it or delete it. If set to 0 or less, these notifications are disabled.
+            If the newest pilot of a title has not been released in this many days, notify someone about it monthly, asking to release it or delete it.
+            If set to 0 or less, these notifications are disabled.
 
-            Notifications are sent on the first of the month via email to the title's contact email address, and the alert_tool (if defined). Default is 180 days (about 6 months).
+            Notifications are sent on the first of the month via email to the title's contact email address, and the alert_tool (if defined).
+            Default is 180 days (about 6 months).
 
             Pilot versions are those that have been added for testing, but not yet released.
 
@@ -353,7 +406,8 @@ module Xolo
         smtp_server: {
           type: :string,
           desc: <<~ENDDESC
-            The hostname of the SMTP server to use for sending email. This is a server that can recieve email for your organizaion from the xolo server. Used for sending alerts and notifications. If not set, no email notifications will be sent.
+            The hostname of the SMTP server to use for sending email. This is a server that can recieve email for your organizaion from the xolo server.
+            Used for sending alerts and notifications. If not set, no email notifications will be sent.
           ENDDESC
         },
 
@@ -364,7 +418,8 @@ module Xolo
           desc: <<~ENDDESC
             The email address to use as the 'from' address for emails sent by xolo. This should be a valid email address that can recieve replies.
 
-            Will default to '#{Xolo::Server::Helpers::Notification::DFT_EMAIL_FROM}@<hostname>' if not set. The human-readable part of the address will be 'Xolo Server on <hostname>'.
+            Will default to '#{Xolo::Server::Helpers::Notification::DFT_EMAIL_FROM}@<hostname>' if not set. The human-readable part of the address
+            will be 'Xolo Server on <hostname>'.
           ENDDESC
         },
 
@@ -395,7 +450,6 @@ module Xolo
         # @!attribute jamf_gui_hostname
         #   @return [String] The hostname of the Jamf Pro server used for links to the GUI webapp
         jamf_gui_hostname: {
-          required: true,
           type: :string,
           desc: <<~ENDDESC
             The hostname of the Jamf Pro server used for links to the GUI webapp, if different from the jamf_hostname.
@@ -460,11 +514,17 @@ module Xolo
         #   @return [String] The username to use when connecting to the Jamf Pro API
         jamf_api_user: {
           required: true,
+          load_method: :data_from_command_file_or_string,
           type: :string,
           desc: <<~ENDDESC
             The username of the Jamf account for connecting to the Jamf Pro APIs.
-            TODO: Document the permissions needed by this account.
-            TODO: Allow using api-clients
+
+            If you start this value with a vertical bar '|', everything after the bar is a shell command to be executed by the server at start-time.
+            The command must return the password to standard output. This is useful when using a secret-storage system to manage secrets.
+
+            If the value is a path to a readable file, the file's contents are used.
+
+            Otherwise the value is used as the  password.
           ENDDESC
         },
 
@@ -478,7 +538,8 @@ module Xolo
           desc: <<~ENDDESC
             The password for the username that connects to the Jamf Pro APIs.
 
-            If you start this value with a vertical bar '|', everything after the bar is a command to be executed by the server at start-time. The command must return the certificate to standard output. This is useful when using a secret-storage system to manage secrets.
+            If you start this value with a vertical bar '|', everything after the bar is a shell command to be executed by the server at start-time.
+            The command must return the password to standard output. This is useful when using a secret-storage system to manage secrets.
 
             If the value is a path to a readable file, the file's contents are used.
 
@@ -488,14 +549,28 @@ module Xolo
           ENDDESC
         },
 
+        # @!attribute jamf_api_client
+        #   @return [Boolean] The provided jamf_api_user is an API client, not a normal user, and the
+        #      jamf_api_pw is the API client's secret.
+        jamf_use_api_client: {
+          type: :boolean,
+          desc: <<~ENDDESC
+            If true, the provided jamf_api_user is an API client's "client_id", not a normal username, and the jamf_api_pw is the API client's 'client_secret'.
+
+            If false, the jamf_api_user is a normal user, and the jamf_api_pw is that user's password.
+          ENDDESC
+        },
+
         # @!attribute jamf_auto_accept_xolo_eas
-        #   @return [Boolean] should we auto-accept the Jamf patch title eas?
+        #   @return [Boolean] should we auto-accept the Jamf patch title eas for managed titles?
         jamf_auto_accept_xolo_eas: {
           type: :boolean,
           desc: <<~ENDDESC
-            For titles fully maintained by Xolo, should we auto-accept the Patch Title Extension Attributes that come from the uploaded version_script from xadm?
+            For titles managed by Xolo, should we auto-accept the Patch Title Extension Attributes that come from the uploaded version_script from xadm?
 
             Default is false, meaning all Title EAs must be manually accepted in the Jamf Pro Web UI.
+
+            EAs must always be manually accepted for subscribed titles, since the code the run is not under the control of Xolo.
           ENDDESC
         },
 
@@ -510,28 +585,28 @@ module Xolo
           desc: <<~ENDDESC
             After a .pkg is uploaded to the Xolo server by someone using xadm, it must then be uploaded to the Jamf distribution point(s) to be available for installation.
 
-            If this value is 'api', and you are using Jamf Pro 11.6 or later,  Xolo will use the Jamf API to upload the package to your primary distribution point. API uploads are only available in Jamf Pro 11.6 and later, and will only upload to the primary distribution point. Syncing to other distribution points is not supported by the API.
+            If your principal distribution point is a Cloud Distribution Point and you're using Jamf Pro 11.6 or later, you can set this value to 'api', and xoloserver will use the Jamf Pro API to upload the pkg to the Cloud Distribution Point. This is the simplest option, and is recommended if it works for your environment.
 
-            If this value is a path, it is to an executable on the xolo server that will do the upload to the distribution point(s). This tool can be anything you like, as long as it can upload a .pkg to the Jamf distribution point(s) you use.
+            If your principal is not a Cloud Distribution Point, xoloserver can use an custom external tool to do the upload.
+
+            To do so, set this value to a path to an executable on the xolo server machine that will do the upload to the distribution point(s). This tool can be anything you like, as long as it can upload a .pkg to the Jamf distribution point(s) you use.
 
             It will be run with two arguments:
-            - First, The display name of the Jamf Package object the .pkg is used with
+            - First, The display name of the Jamf Package record the .pkg is used with
             - Then the path to the .pkg file on the Xolo server, which will be uploaded
               to the Jamf distribution point(s).
 
-            So if the executable is '/usr/local/bin/jamf-pkg-uploader' then when Xolo recieves a .pkg to be uploaded to Jamf, it will run something like:
+            So if the executable is '/usr/local/bin/jamf-pkg-uploader' then when xoloserver recieves a .pkg to be uploaded to Jamf, it will run something like:
 
               /usr/local/bin/jamf-pkg-uploader 'CoolApp' '/Library/Application Support/xoloserver/tmpfiles/CoolApp.pkg'
 
             Where 'CoolApp' is the name of the Jamf Package object that will use this .pkg, and '/Library/Application Support/xoloserver/tmpfiles/CoolApp.pkg' is the location where it was stored on the Xolo server when xadm uploaded it.
 
-            The upload tool can itself run other tools as needed, e.g. one to upload
-            to all fileshare distribution points, and another to upload to a Cloud dist. point.
-            or it can do all the things itself.
+            The upload tool can itself run other tools as needed, e.g. one to upload to all fileshare distribution points, and another to upload to a Cloud dist. point, or it can do all the things itself.
 
-            After that tool runs, the copy of the .pkg on the server ( '/Library/Application Support/xoloserver/tmpfiles/CoolApp.pkg' in the example above) will be deleted.
+            After that tool runs, the copy of the .pkg on the xolo server ('/Library/Application Support/xoloserver/tmpfiles/CoolApp.pkg' in the example above) will be deleted.
 
-            An external tool is used here because every Jamf Pro customer has different needs for this, e.g. various cloud and file-server distribution points. While the packages/upload endpoint of the Jamf Pro API (v11.6+) will upload to the primary distribution point, it won't upload to all the others you might have.
+            An external tool is used here because every Jamf Pro customer has different needs for this depending on their environment of distribution points.
           ENDDESC
         },
 
@@ -541,7 +616,8 @@ module Xolo
         forced_exclusion: {
           type: :string,
           desc: <<~ENDDESC
-            If you have any jamf computers who should never even know that xolo exists, and should never have any software installed via xolo, put them into a group and put that group's name here.
+            If you have any jamf computers who should never even know that xolo exists, and should never have any software installed via xolo, put them
+            into a group and put that group's name here.
 
             An example would be a group of machines that should have a very minimalist management footprint, only enforcing basic security settings and nothing else.
 
@@ -616,7 +692,8 @@ module Xolo
           desc: <<~ENDDESC
             The password for the username that connects to the Title Editor API.
 
-            If you start this value with a vertical bar '|', everything after the bar is a command to be executed by the server at start-time. The command must return the certificate to standard output. This is useful when using a secret-storage system to manage secrets.
+            If you start this value with a vertical bar '|', everything after the bar is a command to be executed by the server at start-time.
+            The command must return the certificate to standard output. This is useful when using a secret-storage system to manage secrets.
 
             If the value is a path to a readable file, the file's contents are used.
 
@@ -624,6 +701,134 @@ module Xolo
 
             Be careful of security concerns when passwords are stored in files.
           ENDDESC
+        },
+
+        # @!attribute subscription_webhook_token
+        #   @return [String]  A command, path, or value for the authentication token used by Jamf Pro to send
+        #      PatchSoftwareTitleUpdated webhook events for subscribed titles.
+        subscription_webhook_token: {
+          load_method: :data_from_command_file_or_string,
+          private: true,
+          type: :string,
+          desc: <<~ENDDESC
+            The authentication token used by Jamf Pro to send PatchSoftwareTitleUpdated webhook events for subscribed titles.
+
+            This value can be string, but should be treated like a password, and should be changed both here and on the Jamf Pro server if it is ever suspected of being compromised.
+
+            A good way to generate a random token is to use the following command in Terminal:
+
+                openssl rand -hex 16
+
+            When configuring the webhook in Jamf Pro, use "Header Authentication"  to send this JSON to use as the header:
+
+               {"Authorization":"Bearer <token>"}
+
+            Replacing <token> with the value set here.
+
+            If you start this value with a vertical bar '|', everything after the bar is a command to be executed by the server at start-time.
+            The command must return the password to standard output. This is useful when using a secret-storage system to manage secrets.
+
+            If the value is a path to a readable file, the file's contents are used.
+
+            Otherwise the value is used as the token.
+
+            Be careful of security concerns when secrets are stored in files.
+          ENDDESC
+        },
+
+        # @!attribute subscription_updated_alert_tool
+        #   @return [String] A cli tool or an email address to notify when a subscription updated webhook event
+        #      is received, but the title is not configured to use autopkg to fetch the new version.
+        #      If unset, the default alert mechanism is used. See 'alert_tool' for details.
+        subscription_updated_alert_tool: {
+          type: :string,
+          desc: <<~ENDDESC
+            If a title is a subscription from a Patch Source, but is not configured to use autopkg to fetch new versions, when a PatchSoftwareTitleUpdated webhook
+            event is received from Jamf Pro, an alert should be sent to notify someone to add the new version manually.
+
+            Leave this unset to use the default alert mechanism defined by the 'alert_tool' configuration value.
+
+            Otherwise, the value is interpreted the same as for 'alert_tool', either a command to run, or an email address prefixed by "#{Xolo::Server::Helpers::Notification::ALERT_TOOL_EMAIL_PREFIX}".
+          ENDDESC
+        },
+
+        # @!attribute autopkg_executable
+        #   @return [String] The path to the autopkg executable. If unset, titles cannot use autopkg to acquire
+        #      new .pkgs
+        autopkg_executable: {
+          type: :string,
+          desc: <<~ENDDESC
+            The path to the autopkg executable on the server host. If unset, titles cannot use autopkg to acquire
+            new .pkgs.
+
+            AutoPkg must be installed, configured, and maintained on the xoloserver host separately from the xoloserver itself.
+
+            NOTE: AutoPkg recipes are always run with '-k FAIL_RECIPES_WITHOUT_TRUST_INFO=yes', and will fail if you have not 'trusted'
+            them by making an override. See the AutoPkg docs for details.
+          ENDDESC
+        },
+
+        # @!attribute autopkg_user
+        #   @return [String] The name of a local, non-root user that will run actually the autopkg executable as needed.
+        autopkg_user: {
+          type: :string,
+          desc: <<~ENDDESC
+            The name of a local, non-root user that will run the autopkg executable as needed. AutoPkg should never be run as root.
+
+            If unset, titles cannot use autopkg to acquire new .pkgs.
+
+            AutoPkg must be installed, configured, and maintained on the xoloserver host separately from the xoloserver itself.
+
+            NOTE: AutoPkg recipes are always run with '-k FAIL_RECIPES_WITHOUT_TRUST_INFO=yes', and will fail if you have not 'trusted'
+            them by making an override. See the AutoPkg docs for details.
+          ENDDESC
+        },
+
+        # @!attribute autopkg_user_keychain_pw
+        #   @return [String] A command, path, or value for the password to unlock the autopkg_user's login keychain.
+        autopkg_user_keychain_pw: {
+          required: true,
+          load_method: :data_from_command_file_or_string,
+          private: true,
+          type: :string,
+          desc: <<~ENDDESC
+            The password for the login keychain of the autopkg_user.
+
+            Some autopkg recipes may attempt to sign apps or packages, which requires access to the autopkg_user's login keychain.
+
+            Since the user is not expected to be logged into the macOS GUI on the server (and even if it were, the xoloserver process doesn't have
+            access to the GUI context) the keychain will be locked, and must be unlocked by the server before running autopkg recipes that need it.
+
+            This config value is used to unlock that keychain when running autopkg recipes. The keychain used is the one located at
+            /Users/<autopkg_user>/Library/Keychains/login.keychain-db. Be sure the desired signing identities are in that keychain, and that the
+            keychain is set to allow various executables to access them without prompting, including the autopkg itself, codesign, productsign,
+            pkgbuild, and productbuild.
+
+            If you start this value with a vertical bar '|', everything after the bar is a command to be executed by the server at start-time.
+            The command must return the password to standard output. This is useful when using a secret-storage system to manage secrets.
+
+            If the value is a path to a readable file, the file's contents are used.
+
+            Otherwise the value is used as the password.
+
+            Be careful of security concerns when passwords are stored in files.
+          ENDDESC
+        },
+
+        # @!attribute sign_autopkg_pkgs
+        #   @return [Boolean] Should the server sign any unsigned pkgs acquired via autopkg?
+        sign_autopkg_pkgs: {
+          type: :boolean,
+          desc: <<~ENDDESC
+            This is just like sign_pkgs, but only applies to pkgs acquired via autopkg.
+
+            Be sure you trust your autopkg recipes to only download safe pkgs if you enable this.
+
+            Packages must be signed distribution packages to work with the `xadm deploy` command, which uses MDM to push the package to client machines.
+
+            NOTE: AutoPkg recipes are always run with '-k FAIL_RECIPES_WITHOUT_TRUST_INFO=yes', and will fail if you have not 'trusted'
+            them by making an override. See the AutoPkg docs for details.
+          ENDDESC
         }
 
       }.freeze

data/lib/xolo/server/constants.rb

@@ -63,6 +63,16 @@ module Xolo
       # full object name if appropriate (e.g. Package objects)
       JAMF_OBJECT_NAME_PFX = 'xolo-'
 
+      # Jamf objects from a test server are named with this prefix followed by <title>-<version>
+      # See also:  Xolo::Server::Configuration
+      JAMF_TEST_OBJECT_NAME_PFX = 'xolotest-'
+
+      # when processing things via Jamf webhooks, this is the session[:admin]
+      WEBHOOK_HANDLER_ADMIN_USERNAME = 'xolo-webhook-handler'
+
+      # TODO: remove this stuff when ruby-jss supports Patch Titles via JPAPI
+      JPAPI_PATCH_TITLE_ENDPOINT = 'v2/patch-software-title-configurations'
+
     end # module Constants
 
   end #  Server

data/lib/xolo/server/helpers/auth.rb

@@ -53,6 +53,9 @@ module Xolo
           '/maint/shutdown-server'
         ].freeze
 
+        # the route used by Jamf Webhooks to notify Xolo of Patch Title updates
+        PATCH_TITLE_UPDATED_WEBHOOK_ROUTE = '/subscribed-title-updates'
+
         # The loopback address for IPV4, aka 'localhost'
         IPV4_LOOPBACK = '127.0.0.1'
 
@@ -67,7 +70,7 @@ module Xolo
         end
 
         # If a request comes in from one of our known IP addresses
-        # with a valid internal_auth_toke in the headers, then the request is allowed.
+        # with a valid internal_auth_token in the headers, then the request is allowed.
         #
         # This allows the xolo server to send requests to itself without needing
         # to authenticate, as is needed for some kinds of maintenance tasks
@@ -83,6 +86,12 @@ module Xolo
           @internal_auth_token_header ||= "Bearer #{SecureRandom.hex(64)}"
         end
 
+        # @return [String] The auth token to be used in the Authorization header of webhook event requests
+        #####################
+        def self.jamf_webhook_auth_token_header
+          @jamf_webhook_auth_token_header ||= "Bearer #{Xolo::Server.config.subscription_webhook_token}"
+        end
+
         # Instance methods
         #####################
         #####################
@@ -128,6 +137,12 @@ module Xolo
           Socket.ip_address_list.map(&:ip_address)
         end
 
+        # @return [Boolean] Is the jamf webhook auth token in the headers of the request?
+        #####################
+        def jamf_webhook_auth_token_ok?
+          request.env['HTTP_AUTHORIZATION'] == Xolo::Server::Helpers::Auth.jamf_webhook_auth_token_header
+        end
+
         # is the given username a member of the admin_jamf_group?
         # or the server_admin_jamf_group?
         # If not, they are not allowed to talk to the xolo server.
@@ -212,6 +227,7 @@ module Xolo
           log_debug "Checking if '#{username}' is a member of the Jamf AccountGroup '#{groupname}'"
 
           # This isn't well implemented in ruby-jss, so use c_get directly
+          # TODO: use JP API when ruby-jss supports it
           jgroup = jamf_cnx.c_get("accounts/groupname/#{groupname}")[:group]
 
           if jgroup[:ldap_server]
@@ -223,7 +239,8 @@ module Xolo
           false
         end
 
-        # Try to authenticate the jamf user trying to log in to xolo
+        # Try to authenticate the jamf user trying to log in to xolo.
+        # This must be a regular Jamf user acct, not an API client.
         #
         # @param admin [String] The jamf acct name of the person seeking access
         #