/**
* Root object of the System API, used for accessing the CompleteFTP server's internal state. Accessed
* via the global variable 'system'.
* @namespace
*/
var system = {
/**
* Log in using the given user-name and password, or throws an exception indicating that the user could not be authenticated.
* Until this function is invoked the active user will be the 'anonymous' user.
* Logins are associated with session IDs, which are stored in a cookie named "__cftp_sessid". Cookies must therefore be
* enabled for logins to work. Users must be set up within CompleteFTP. If users are to be managed from within the
* web-app then CompleteFTP's database authentication should be used in combination with the server-side WebSQLDatabase
* feature (see {@link system#openDatabaseSync openDatabaseSync}). Use the {@link system#user user} property to access
* information about the active user.
*
* @method
* @param {String} userName User-name
* @param {String} password Password
* @param {Boolean} [usePublicFolderAsRoot] If `true` the /Public folder will appear
* as the root directory (useful for web-apps), otherwise the user's own home folder will be the root.
* @param {Boolean} [persistentCookie] If `true` the session cookie will be persistent,
* meaning that the user will remain logged in between browser restarts. If `false`, the cookie
* will not be persistent, so the session will end when the browser exits.
*/
login: function (userName, password, usePublicFolderAsRoot, persistentCookie) { },
/**
* Checks if a user is logged in and throws an 'unauthorized access' exception if not. In HTTP, this will result in a 401
* error being returned to the client. A function may optionally be passed in if additional checks are required. This function
* will trigger an exception if it returns a string or if it throws an exception.
*
* @method
* @param {String} [extraCheckFunction] Optional function that can implement checks in addition to the default login check.
* If this function returns a string or throws an exception then an error will be triggered with message returned or thrown.
*/
checkLogin: function (extraCheckFunction) { },
/**
* Log out the current user.
*
* @method
*/
logout: function () { },
/**
* Returns an array of PasswordResetInfo objects for users that match the given user-name or email address.
*
* @method
* @param {String} userNameOrEmail User-name or email address.
* @return {PasswordResetInfo[]}
*/
getPasswordResetInfo: function(userNameOrEmail) { },
/**
* Returns an array of PasswordResetInfo objects for users that match the given user-name or email address.
*
* @method
* @param {String} userNameOrEmail User-name or email address.
* @return {Object}
*/
processPasswordReset: function(passwordResetKey, password) { },
/**
* Returns a {@link File} object for the given path.
* The File object may or may not represent an existing file or directory.
*
* @method
* @param {String} path Path of file
* @return {File}
*/
getFile: function (path) { },
/**
* Opens a connection to the database with the given connection-string. The `connectionString` must be
* either the virtual file-system path of an SQLite or SQL Server Compact file, or a
* prefixed [database connection-string](http://www.connectionstrings.com/). The prefixes are shown below:
*
* | Connection-type | Prefix | File-extension | Database DLLs required? |
* |---|---|---|---|
* | SQLite | sqlite:<sup>*</sup> | .sqlite3 | no |
* | SQL Server Compact | sqlserverce:<sup>*</sup> | .sdf | no |
* | SQL Server | sqlserver: | n/a | no |
* | ODBC | odbc: | n/a | no |
* | OLE DB | oledb: | n/a | yes<sup>**</sup> |
*
* <i><sup>*</sup> - Prefixes are only required for SQLite and SQL Server Compact if the listed file-extension
* isn't being used.</i>
*
* <i><sup>**</sup> - For OLE DB connections the DLLs for the specific database being accessed must be placed in the same directory
* as the CompleteFTP server executables.</i>
*
* @method
* @param {String} connectionString Connection-string.
* @return {DatabaseSync}
*/
openDatabaseSync: function (connectionString) { },
/**
* Executes a custom command and returns the result. Custom commands are methods that
* have been implemented in <a href="../html/sitecommandextensions.html">.NET Custom Command Extensions</a>
* and <a href="../html/jsssitecommandextensions.html">JSS Custom Command Scripts</a>.
* There are some inbuilt commands, including <a href="../html/commandadmin.html">administration commands</a>
* and the file-sharing commands (<a href="https://enterprisedt.com/help">ask support</a>), but
* you can also add your own.
*
* @method
* @param {String} commandName Name of the custom command (e.g. "useradd")
* @param {String[]} [parameters] Arguments to be passed to the command.
* @return {String} Result of the command.
*/
executeCustomCommand: function (commandName, parameters) { },
/**
* Get information about the current state of the system.
*
* @method
* @return {Monitor} Object containing information about the current state of the system.
*/
getMonitor: function () { },
/**
* Represents the CompleteFTP site that is serving up this script.
* @type {SiteInfo}
*/
site: {},
/**
* Represents the current server.
*
* @type {Object}
* @property {String} name Name of the server.
* @property {String[]} ipAddresses IP addresses available on the server.
*/
server: {
name: "",
ipAddresses: []
},
/**
* Represents the currently logged in user or the anonymous user, if a user isn't logged in.
*
* The object has the properties listed below, as well as a method `changePassword(newPassword)`,
* which changes the password of the user to `newPassword`.
*
* @type {Object}
* @property {String} fullName Full name of the user
* @property {String} email Email address of user
* @property {String} description Description of user
* @property {String} userName User-name of the user (excluding any domain-name).
* @property {String} fullUserName Full user-name of the user (including any domain-name).
* @property {String} domainName Domain-name of the user.
* @property {Boolean} isAnonymous True if no user is currently logged in.
* @property {String} homeFolder Absolute path of the user's home-folder.
* @property {String} apparentHomeFolder Path of the user's home-folder as it appears to the user.
* @property {String} uniqueID string that's unique for every user, including those authenticated by authenticators.
* @property {Boolean} sharingEnabled True is sharing is enabled for this user.
* @property {Boolean} tfaEnabled True if two-factor authentication (2FA) is enabled.
* @property {Boolean} tfaInitialized True if the user has activated a 2FA device (can be set).
* @property {Boolean} tfaValidated True if the user has entered a valid 2FA PIN in the current session (can be set).
* @property {Array} tfaBackupPINs Array of strings representing the user's 2FA backup PINs (can be set).
* @property {Boolean} mustChangePassword True if the user must change their password when they log in
* @property {Boolean} allowChangePassword True if the user is able to change their password
* @property {Object} tags Encapsulates a set of name-value pairs whose lifetime is that of the session.
*
* Methods:
* - **set(name, value)** sets the value of the named tag.
* - **get(name)** gets the value of the named tag.
* - **remove(name)** removes the named tag.
* - **clear()** removes all tags.
*/
user: {
fullName: "",
email: "",
description: "",
userName: "",
fullUserName: "",
domainName: "",
isAnonymous: true,
sharingEnabled: true,
tfaEnabled: true,
tfaInitialized: true,
tfaValidated: true,
tfaBackupPINs: [],
homeFolder: "",
apparentHomeFolder: "",
uniqueID: "",
verifyPassword: function (password) { },
changePassword: function (password) { },
tags: {
set: function (name, value) { },
get: function (name) { },
remove: function (name) { },
clear: function () { }
}
},
/**
* Password policy applied to new passwords.
*
* The object has the properties listed below:
*
* @type {Object}
* @property {Boolean} allowChange True if users are allowed to change their own password.
* @property {Number} minLength Minimum number of characters required.
* @property {Boolean} mustHaveMixedCase True if passwords must have at least one upper-case and at least one lower-case letter.
* @property {Boolean} mustHaveDigit True if passwords must include at least one digit.
* @property {Boolean} mustHaveSpecialChar True if passwords must include at least one of the following characters: !\"#$%&'()*+,-./:
* @property {Number} expirySoftDays Number of days since last password change until they are required to change their password when they log in. Null (default) means never.
* @property {Number} expiryHardDays Number of days since last password change until a password expires, preventing the user from logging in. Null (default) means never.
*/
passwordPolicy: {
allowChange: true,
minLength: 0,
mustHaveMixedCase: true,
mustHaveDigit: true,
mustHaveSpecialChar: true
},
/**
* The current working directory for the current session. Can be read and assigned.
* @type {string}
*/
currentFolder: "",
/**
* [Admins only] sudo = Super-User DO. Like its UNIX counterpart, this function executes the given action in the
* admin user context. Windows resources will be accessed in the context of the user that's running the
* CompleteFTP service, which by default is SYSTEM. Care should be taken when using this function as
* the admin user has much greater permissions than non-admin users, so there is a higher potential
* for misbehaviour. This function may only be executed by members of the admins group or by scripts
* that are owned by members of the admin group.
*
* @method
* @param {Function} action Function containing the actions to be run in the admin user context.
*/
sudo: function (action) { },
/**
* [Admins only] Returns a {@link Config} object representing the current configuration of CompleteFTP server.
* This function may only be executed by members of the admins group or by scripts
* that are owned by members of the admin group.
*
* @method
* @return {Config}
*/
getConfig: function () { },
/**
* [Admins only] Change configuration of CompleteFTP server via a callback function. The callback function
* passed in as an argument is called with a Config object as an argument. Changes made to this object will
* be applied automatically after the callback function returns unless and exception is thrown in the callback
* function. Calling this method will give the same result as calling getConfig(), making changes to the returned
* object and calling applyChanges() on that object.
*
* @method
* @param {ChangeConfigCallback} callback Callback function that takes a Config object as an argument.
*/
changeConfig: function (callback) { },
/**
* Callback used by the changeConfig method.
* @callback ChangeConfigCallback
* @param {Config} config Object encapsulating the CompleteFTP configuration.
*/
/**
* Returns the type and fingerprint of key stored in the encodedKey argument, as well as the same key in OpenSSH format,
* which is the format CompleteFTP uses to store key internally.
*
* @method
* @return {PublicKeyInfo} Key information or null if the key could not be parsed.
*/
getPublicKeyInfo: function (encodedKey) { },
/**
* HTML included in .htmljss files. Files with the extension, .htmljss, may have a literal HTML at the beginning and
* then JSS code after a line containing the comment, <!-- SERVER-SIDE -->. This variable contains the HTML.
* @type {string}
*/
inlineHtml: "",
/**
* Path of script previously executed in this request (see nextScriptPath). JSS scripts can be chained together such that,
* after one JSS script is executed, another JSS script is executed before the response is returned.
* @type {string}
*/
previouscriptPath: "",
/**
* Path of script to be executed next (before the HTTP response is returned). JSS scripts can be chained together such that,
* after one JSS script is executed, another JSS script is executed before the response is returned. This is done by setting
* the nextScriptPath field. If the field is not set then the HTTP response, as it's currently set, will be returned.
* @type {string}
*/
nextScriptPath: "",
/**
* Provides the APIs for managing the logged=in user's shared files.
*
* @type {ShareAPI}
*/
shares: null
}
/**
* Contains information about a site
* @typedef {Object} SiteInfo
* @property {String} name Name of the site. This name is not shown to users.
* @property {String} label Name of the site shown to users where required, such as in two-factor authentication (Enterprise Edition)..
* @property {String} welcomeMessage Welcome-message of the site.
* @property {SingleSignOn} singleSignOn Single Sign-on (SAML) settings.
* @property {String} loginPath Path to the login page (usually /Login).
* @property {Boolean} publicAccessEnabled True if public HTTP/HTTPS access is enabled on this site.
* @property {Boolean} httpEnabled True if HTTP is enabled on this site.
* @property {Boolean} httpsEnabled True if HTTPS is enabled on this site.
* @property {Boolean} sharingEnabled True if sharing is enabled on this site.
* @property {Boolean} tfaEnabled True if two-factor authentication is enabled on this site.
* @property {Boolean} allowOverWriteOnRename True if existing files with same names will be overwritten when renaming.
* @property {String} logoutPath Path to the logout page (usually /Logout).
* @property {String} accountPath Path to the account management page (usually /Account)
* @property {String} includePath Path to the include folder (usually /Invluce)
* @property {SiteCertificate} certificate Site certificate.
*/
/**
* Provides access to JWK objects representing the site's certificate and that certificate's public key, as well
* as methods for decrypting and encrypting strings with the certificate's private key.
* @typedef {Object} SiteCertificate
* @property {function(): string} toJWK Returns the site certificate as a JWK object.
* @property {function(): string} publicKeyToJWK Returns the site certificate's public key as a JWK object.
* @property {function(string): string} decryptWithPrivateKey decrypts the given string using the site certificate's private key.
* @property {function(string): string} encryptWithPrivateKey encrypts the given string using the site certificate's private key.
*/
/**
* Contains information about SAML Single Sign-On (SSO).
* @typedef {Object} SingleSignOn
* @property {Boolean} enabled Is SAML SSO enabled?
* @property {String} path Path under which SAML requests are processed (usually /SAML).
* @property {IdentityProvider[]} identityProviders Array of SAML IDPs (IDentity Providers).
*/
/**
* Contains information about an SAML IDP (IDentity Provider)
* @typedef {Object} IdentityProvider
* @property {String} name Name of the IDP.
* @property {String} id Identifier of the IDP (usually its URL).
*/
/**
* Public key information.
* @typedef {Object} PublicKeyInfo
* @property {String} type The algorithm of the key: DSA, RSA, ECDSAsha2Nistp256, ECDSAsha2Nistp384 or ECDSAsha2Nistp512.
* @property {String} fingerprint The fingerprint of the key.
* @property {String} encodedKey The same key encoded in OpenSSH format (no comment included).
*/