feat: document utility functions

docs/api/server/document/document-account.md

@@ -16,16 +16,15 @@ import { useAccount, useAccountBinder } from '@Server/document/account.js';
 const someAccountData = someDatabaseFetchOrCreateFunction();
 
 // Bind account data to the player after fetching
-const accBinder = useAccountBinder(player);
-accBinder.bind(someAccountData);
+const document = useAccountBinder(player).bind(someAccountData);
 ```
 
 ## Getting Data
 
 Data can be retrieved for the bound account like this.
 
 ```ts
-import { useAccount, useAccountBinder } from '@Server/document/account.js';
+import { useAccount } from '@Server/document/account.js';
 
 //... some function
 const account = useAccount(player);
@@ -38,7 +37,7 @@ console.log(data.email);
 Data can easily be appended or set in two different ways.
 
 ```ts
-import { useAccount, useAccountBinder } from '@Server/document/account.js';
+import { useAccount } from '@Server/document/account.js';
 
 type CustomAccount = { whatever: string };
 
@@ -88,3 +87,33 @@ await document.permission.addPermission('admin');
 await document.permission.removePermission('admin');
 const result = document.permission.hasPermission('admin');
 ```
+
+## Password
+
+When you setup an account you often want to also setup a password, or check a password.
+
+We've made it pretty easy in Rebar to simply check a password to login.
+
+```ts
+import { useAccount, useAccountBinder } from '@Server/document/account.js';
+
+// Bind, and get the document
+const document = useAccountBinder(player).bind(someAccountDataHere);
+
+// Verify a password for the account
+const isValid = document.checkPassword('myplaintextpassword');
+```
+
+## Banning
+
+Banning an account is pretty straight forward but it does not prevent new accounts with new ips.
+
+It's simply an account level ban that happens during server runtime.
+
+```ts
+import { useAccount } from '@Server/document/account.js';
+
+// Bind, and get the document
+const document = useAccount(player);
+const isValid = document.setBanned('oops your banned');
+```

docs/api/server/document/document-character.md

@@ -16,8 +16,7 @@ import { useCharacter, useCharacterBinder } from '@Server/document/character.js'
 const someCharacterData = someDatabaseFetchOrCreateFunction();
 
 // Bind character data to the player after fetching
-const charBinder = useCharacterBinder(player);
-charBinder.bind(someCharacterData);
+const document = useCharacterBinder(player).bind(someCharacterData);
 ```
 
 ## Getting Data

docs/api/server/document/document-vehicle.md

@@ -13,11 +13,10 @@ import { useVehicle, useVehicleBinder } from '@Server/document/vehicle.js';
 
 // ... some function
 // Use database functions to fetch or create a vehicle
-const someCharacterData = someDatabaseFetchOrCreateFunction();
+const someVehicleData = someDatabaseFetchOrCreateFunction();
 
 // Bind vehicle data to the player after fetching
-const vehBinder = useVehicleBinder(player);
-vehBinder.bind(someCharacterData);
+const document = useVehicleBinder(player).bind(someVehicleData);
 ```
 
 ## Getting Data

src/main/server/document/account.ts

@@ -1,4 +1,5 @@
 import * as alt from 'alt-server';
+import * as Utility from '../utility/index.js';
 import { Account } from '../../shared/types/account.js';
 import { KnownKeys } from '../../shared/utilityTypes/index.js';
 import { useDatabase } from '@Server/database/index.js';
@@ -176,13 +177,50 @@ export function useAccount(player: alt.Player) {
         return perm.has('account', permission);
     }
 
+    /**
+     * Set the password for this account
+     *
+     * @param {string} plainText
+     */
+    async function setPassword(plainText: string) {
+        await set('password', Utility.hash(plainText));
+    }
+
+    /**
+     * Ban an account with a reason, and kick them from the server.
+     *
+     * @param {string} reason
+     */
+    async function setBanned(reason: string) {
+        await setBulk({ reason, banned: true });
+        if (player && player.valid) {
+            player.kick(reason);
+        }
+    }
+
+    /**
+     * Check a provided password for this account
+     *
+     * @param {string} plainText
+     * @return
+     */
+    function checkPassword(plainText: string) {
+        const data = get();
+        if (!data) {
+            return false;
+        }
+
+        return Utility.check(plainText, data.password);
+    }
+
     const permission = {
         addPermission,
         removePermission,
         hasPermission,
+        setBanned,
     };
 
-    return { addPermission, get, getCharacters, getField, permission, set, setBulk };
+    return { addPermission, get, getCharacters, getField, permission, set, setBulk, setPassword, checkPassword };
 }
 
 export function useAccountBinder(player: alt.Player) {
@@ -193,12 +231,13 @@ export function useAccountBinder(player: alt.Player) {
      *
      * @param {Account & T} document
      */
-    function bind<T = {}>(document: Account & T) {
+    function bind<T = {}>(document: Account & T): ReturnType<typeof useAccount> | undefined {
         if (!player.valid) {
-            return;
+            return undefined;
         }
 
         player.setMeta(sessionKey, document);
+        return useAccount(player);
     }
 
     /**

src/main/server/document/character.ts

@@ -281,12 +281,13 @@ export function useCharacterBinder(player: alt.Player) {
      *
      * @param {Character & T} document
      */
-    function bind<T = {}>(document: Character & T) {
+    function bind<T = {}>(document: Character & T): ReturnType<typeof useCharacter> | undefined {
         if (!player.valid) {
-            return;
+            return undefined;
         }
 
         player.setMeta(sessionKey, document);
+        return useCharacter(player);
     }
 
     /**

src/main/server/document/vehicle.ts

@@ -128,12 +128,13 @@ export function useVehicleBinder(vehicle: alt.Vehicle) {
      *
      * @param {Vehicle & T} document
      */
-    function bind<T = {}>(document: Vehicle & T) {
+    function bind<T = {}>(document: Vehicle & T): ReturnType<typeof useVehicle> | undefined {
         if (!vehicle.valid) {
-            return;
+            return undefined;
         }
 
         vehicle.setMeta(sessionKey, document);
+        return useVehicle(vehicle);
     }
 
     /**

src/main/shared/types/account.ts

@@ -72,4 +72,11 @@ export type Account = {
      *
      */
     reason?: string;
+
+    /**
+     * Set a password for the account
+     *
+     * @type {string}
+     */
+    password?: string;
 };