Own ts definitions

.eslintrc.json

@@ -10,7 +10,7 @@
     "es6": true
   },
   "parserOptions": {
-    "ecmaVersion": 2019
+    "ecmaVersion": 2023
   },
   "plugins": [
     "prettier"

README.md

@@ -126,7 +126,7 @@ NOTE: The test suite requires an active kerberos deployment.
 ## Functions
 
 <dl>
-<dt><a href="#checkPassword">checkPassword(username, password, service, [defaultRealm], [callback])</a> ⇒ <code>Promise</code></dt>
+<dt><a href="#checkPassword">checkPassword(username, password, service, [defaultRealm])</a> ⇒ <code>Promise.&lt;null&gt;</code></dt>
 <dd><p>This function provides a simple way to verify that a user name and password
 match those normally used for Kerberos authentication.
 It does this by checking that the supplied user name and password can be
@@ -141,14 +141,14 @@ has the correct realms and KDCs listed.</p>
 only be used for testing. Do not use this in any production system - your
 security could be compromised if you do.</p>
 </dd>
-<dt><a href="#principalDetails">principalDetails(service, hostname, [callback])</a> ⇒ <code>Promise</code></dt>
+<dt><a href="#principalDetails">principalDetails(service, hostname)</a> ⇒ <code>Promise</code></dt>
 <dd><p>This function returns the service principal for the server given a service type and hostname.</p>
 <p>Details are looked up via the <code>/etc/keytab</code> file.</p>
 </dd>
-<dt><a href="#initializeClient">initializeClient(service, [options], [callback])</a> ⇒ <code>Promise</code></dt>
+<dt><a href="#initializeClient">initializeClient(service, [options])</a> ⇒ <code><a href="#KerberosClient">Promise.&lt;KerberosClient&gt;</a></code></dt>
 <dd><p>Initializes a context for client-side authentication with the given service principal.</p>
 </dd>
-<dt><a href="#initializeServer">initializeServer(service, [callback])</a> ⇒ <code>Promise</code></dt>
+<dt><a href="#initializeServer">initializeServer(service)</a> ⇒ <code><a href="#KerberosServer">Promise.&lt;KerberosServer&gt;</a></code></dt>
 <dd><p>Initializes a context for server-side authentication with the given service principal.</p>
 </dd>
 </dl>
@@ -168,52 +168,46 @@ security could be compromised if you do.</p>
 
 * [KerberosClient](#KerberosClient)
 
-    * [.step(challenge, [callback])](#KerberosClient+step)
+    * [.step(challenge)](#KerberosClient+step)
 
-    * [.wrap(challenge, [options], [callback])](#KerberosClient+wrap)
+    * [.wrap(challenge, [options])](#KerberosClient+wrap)
 
-    * [.unwrap(challenge, [callback])](#KerberosClient+unwrap)
+    * [.unwrap(challenge)](#KerberosClient+unwrap)
 
 
 <a name="KerberosClient+step"></a>
 
-### *kerberosClient*.step(challenge, [callback])
+### *kerberosClient*.step(challenge)
 
 | Param | Type | Description |
 | --- | --- | --- |
 | challenge | <code>string</code> | A string containing the base64-encoded server data (which may be empty for the first step) |
-| [callback] | <code>function</code> |  |
 
 Processes a single kerberos client-side step using the supplied server challenge.
 
-**Returns**: <code>Promise</code> - returns Promise if no callback passed  
 <a name="KerberosClient+wrap"></a>
 
-### *kerberosClient*.wrap(challenge, [options], [callback])
+### *kerberosClient*.wrap(challenge, [options])
 
 | Param | Type | Description |
 | --- | --- | --- |
 | challenge | <code>string</code> | The response returned after calling `unwrap` |
-| [options] | <code>object</code> | Optional settings |
+| [options] | <code>object</code> | Options |
 | [options.user] | <code>string</code> | The user to authorize |
 | [options.protect] | <code>boolean</code> | Indicates if the wrap should request message confidentiality |
-| [callback] | <code>function</code> |  |
 
 Perform the client side kerberos wrap step.
 
-**Returns**: <code>Promise</code> - returns Promise if no callback passed  
 <a name="KerberosClient+unwrap"></a>
 
-### *kerberosClient*.unwrap(challenge, [callback])
+### *kerberosClient*.unwrap(challenge)
 
 | Param | Type | Description |
 | --- | --- | --- |
 | challenge | <code>string</code> | A string containing the base64-encoded server data |
-| [callback] | <code>function</code> |  |
 
 Perform the client side kerberos unwrap step
 
-**Returns**: <code>Promise</code> - returns Promise if no callback passed  
 <a name="KerberosServer"></a>
 
 ## KerberosServer
@@ -228,27 +222,24 @@ Perform the client side kerberos unwrap step
 
 <a name="KerberosServer+step"></a>
 
-### *kerberosServer*.step(challenge, [callback])
+### *kerberosServer*.step(challenge)
 
 | Param | Type | Description |
 | --- | --- | --- |
 | challenge | <code>string</code> | A string containing the base64-encoded client data |
-| [callback] | <code>function</code> |  |
 
 Processes a single kerberos server-side step using the supplied client data.
 
-**Returns**: <code>Promise</code> - returns Promise if no callback passed  
 <a name="checkPassword"></a>
 
-## checkPassword(username, password, service, [defaultRealm], [callback])
+## checkPassword(username, password, service, [defaultRealm])
 
 | Param | Type | Description |
 | --- | --- | --- |
 | username | <code>string</code> | The Kerberos user name. If no realm is supplied, then the `defaultRealm` will be used. |
 | password | <code>string</code> | The password for the user. |
 | service | <code>string</code> | The Kerberos service to check access for. |
 | [defaultRealm] | <code>string</code> | The default realm to use if one is not supplied in the user argument. |
-| [callback] | <code>function</code> |  |
 
 This function provides a simple way to verify that a user name and password
 match those normally used for Kerberos authentication.
@@ -266,25 +257,24 @@ IMPORTANT: This method is vulnerable to KDC spoofing attacks and it should
 only be used for testing. Do not use this in any production system - your
 security could be compromised if you do.
 
-**Returns**: <code>Promise</code> - returns Promise if no callback passed  
+**Returns**: <code>Promise.&lt;null&gt;</code> - returns Promise that rejects if the password is invalid  
 <a name="principalDetails"></a>
 
-## principalDetails(service, hostname, [callback])
+## principalDetails(service, hostname)
 
 | Param | Type | Description |
 | --- | --- | --- |
 | service | <code>string</code> | The Kerberos service type for the server. |
 | hostname | <code>string</code> | The hostname of the server. |
-| [callback] | <code>function</code> |  |
 
 This function returns the service principal for the server given a service type and hostname.
 
 Details are looked up via the `/etc/keytab` file.
 
-**Returns**: <code>Promise</code> - returns Promise if no callback passed  
+**Returns**: <code>Promise</code> - returns Promise  
 <a name="initializeClient"></a>
 
-## initializeClient(service, [options], [callback])
+## initializeClient(service, [options])
 
 | Param | Type | Description |
 | --- | --- | --- |
@@ -293,20 +283,20 @@ Details are looked up via the `/etc/keytab` file.
 | [options.principal] | <code>string</code> | Optional string containing the client principal in the form 'user@realm' (e.g. '[email protected]'). |
 | [options.flags] | <code>number</code> | Optional integer used to set GSS flags. (e.g.  `GSS_C_DELEG_FLAG\|GSS_C_MUTUAL_FLAG\|GSS_C_SEQUENCE_FLAG` will allow for forwarding credentials to the remote host) |
 | [options.mechOID] | <code>number</code> | Optional GSS mech OID. Defaults to None (GSS_C_NO_OID). Other possible values are `GSS_MECH_OID_KRB5`, `GSS_MECH_OID_SPNEGO`. |
-| [callback] | <code>function</code> |  |
+| [options.user] | <code>string</code> | The username with which to authenticate.  Only used on Windows. |
+| [options.pass] | <code>string</code> | The password with which to authenticate.  Only used on Windows. |
 
 Initializes a context for client-side authentication with the given service principal.
 
-**Returns**: <code>Promise</code> - returns Promise if no callback passed  
+**Returns**: [<code>Promise.&lt;KerberosClient&gt;</code>](#KerberosClient) - returns Promise  
 <a name="initializeServer"></a>
 
-## initializeServer(service, [callback])
+## initializeServer(service)
 
 | Param | Type | Description |
 | --- | --- | --- |
 | service | <code>string</code> | A string containing the service principal in the form 'type@fqdn' (e.g. '[email protected]'). |
-| [callback] | <code>function</code> |  |
 
 Initializes a context for server-side authentication with the given service principal.
 
-**Returns**: <code>Promise</code> - returns Promise if no callback passed  
+**Returns**: [<code>Promise.&lt;KerberosServer&gt;</code>](#KerberosServer) - returns Promise  

index.d.ts

@@ -0,0 +1,177 @@
+export const GSS_C_DELEG_FLAG: number;
+export const GSS_C_MUTUAL_FLAG: number;
+export const GSS_C_REPLAY_FLAG: number;
+export const GSS_C_SEQUENCE_FLAG: number;
+export const GSS_C_CONF_FLAG: number;
+export const GSS_C_INTEG_FLAG: number;
+export const GSS_C_ANON_FLAG: number;
+export const GSS_C_PROT_READY_FLAG: number;
+export const GSS_C_TRANS_FLAG: number;
+
+export const GSS_C_NO_OID: number;
+export const GSS_MECH_OID_KRB5: number;
+export const GSS_MECH_OID_SPNEGO: number;
+
+/**
+ * Optional settings for *KerberosClient.wrap* method.
+ */
+export interface WrapOptions {
+    /**
+     * The user to authorize.
+     */
+    user?: string | undefined;
+
+    /**
+     * Indicates if the wrap should request message confidentiality.
+     */
+    protect?: boolean
+}
+
+/**
+ * Options for `initializeClient()`.
+ */
+export interface InitializeClientOptions {
+    /**
+     * Optional string containing the client principal in the form 'user@realm' (e.g. '[email protected]').
+     */
+    principal?: string | undefined;
+    /**
+     * Optional integer used to set GSS flags. (e.g.  `GSS_C_DELEG_FLAG|GSS_C_MUTUAL_FLAG|GSS_C_SEQUENCE_FLAG` will allow for forwarding credentials to the remote host).
+     */
+    gssFlag?: number | undefined;
+    /**
+     * Optional GSS mech OID. Defaults to None (GSS_C_NO_OID). Other possible values are `GSS_MECH_OID_KRB5`, `GSS_MECH_OID_SPNEGO`.
+     */
+    mechOID?: number | undefined;
+
+    /**
+     * The username with which to authenticate.  Only used on Windows.
+     */
+    user?: string;
+
+    /**
+     * The password with which to authenticate.  Only used on Windows.
+     */
+    pass?: string;
+}
+
+export class KerberosClient {
+    /**
+     * The username used for authentication.
+     */
+    username: string;
+    /**
+     * The last response received during authentication steps.
+     */
+    response: string;
+    /**
+     * Indicates whether confidentiality was applied or not (GSSAPI only).
+     */
+    responseConf: string;
+    /**
+     * Indicates that authentication has successfully completed or not.
+     */
+    contextComplete: boolean;
+
+    /**
+     * Processes a single kerberos client-side step using the supplied server challenge.
+     *
+     * @param challenge A string containing the base64-encoded server data (which may be empty for the first step)
+     */
+    step(challenge: string): Promise<string>;
+
+    /**
+     * Perform the client side kerberos wrap step.
+     *
+     * @param challenge The response returned after calling `unwrap`
+     * @param options Optional settings
+     */
+    wrap(challenge: string, options?: WrapOptions): Promise<string>;
+
+    /**
+     * Perform the client side kerberos unwrap step
+     *
+     * @param challenge A string containing the base64-encoded server data
+     */
+    unwrap(challenge: string): Promise<string>;
+}
+
+export class KerberosServer {
+    /**
+     * The username used for authentication
+     */
+    username: string;
+    /**
+     * @description The last response received during authentication steps
+     */
+    response: string;
+    /**
+     * @description The target used for authentication
+     */
+    targetName: string;
+    /**
+     * @description Indicates that authentication has successfully completed or not
+     */
+    contextComplete: boolean;
+
+    /**
+     * Processes a single kerberos server-side step using the supplied client data.
+     *
+     * @param challenge A string containing the base64-encoded client data
+     */
+    step(challenge: string): Promise<string>;
+}
+
+/**
+ * This function provides a simple way to verify that a user name and password
+ * match those normally used for Kerberos authentication.
+ * It does this by checking that the supplied user name and password can be
+ * used to get a ticket for the supplied service.
+ * If the user name does not contain a realm, then the default realm supplied
+ * is used.
+ *
+ * For this to work properly the Kerberos must be configured properly on this
+ * machine.
+ * That will likely mean ensuring that the edu.mit.Kerberos preference file
+ * has the correct realms and KDCs listed.
+ *
+ * IMPORTANT: This method is vulnerable to KDC spoofing attacks and it should
+ * only be used for testing. Do not use this in any production system - your
+ * security could be compromised if you do.
+ *
+ * @param username The Kerberos user name. If no realm is supplied, then the `defaultRealm` will be used.
+ * @param password The password for the user.
+ * @param service The Kerberos service to check access for.
+ * @param defaultRealm The default realm to use if one is not supplied in the user argument.
+ */
+export function checkPassword(name: string, password: string, service: string, defaultRealm?: string): Promise<void>;
+
+/**
+ * This function returns the service principal for the server given a service type and hostname.
+ *
+ * Details are looked up via the `/etc/keytab` file.
+ *
+ * @param service The Kerberos service type for the server.
+ * @param hostname The hostname of the server.
+ */
+export function principalDetails(service: string, hostname: string): Promise<string>;
+
+/**
+ * Initializes a context for client-side authentication with the given service principal.
+ *
+ * @param service A string containing the service principal in the form '`type@fqdn`'.
+ * @param [options] Optional settings
+ */
+export function initializeClient(service: string, options?: InitializeClientOptions): Promise<KerberosClient>;
+
+/**
+ * Initializes a context for server-side authentication with the given service principal.
+ *
+ * @param service A string containing the service principal in the form 'type@fqdn' (e.g. '[email protected]').
+ */
+export function initializeServer(service: string): Promise<KerberosServer>;
+
+/**
+ * The version of the Kerberos package.
+ */
+export const version: string;