@based/client 2.7.5 → 2.10.0

package/docs/auth-howto.md

@@ -0,0 +1,166 @@
+## JWT Auth Flow HowTo
+
+A short guide to setting up the JWT authentication flow using based.
+An example with the info on this guide can be foud [here](https://github.com/atelier-saulx/auth-demo)
+
+If you created an environment using the based website, the JWT auth flow template is installed by default. This template includes the `user` type schema, the public and private keys, and the default `authorize`, `login`, `logout`, and `renewToken` data functions.
+
+These default data functions can be customized to your needs. Add them to your project from [here](https://github.com/atelier-saulx/based/tree/main/packages/auth-templates/jwt) and deploy with the [based cli `deploy` command](https://github.com/atelier-saulx/based/tree/main/packages/cli#deploy).
+
+### Adding a user to the database
+
+You now need to add a user to the database so that he can log in.
+There are several ways to do this, including the data editor in the Based website admin area.
+We'll add it through a script from the developer's computer environment as it also shows how you can add this functionality from your own apps.
+
+The `user` type installed by default has the following schema:
+
+```
+  ...
+  types: {
+    user: {
+      prefix: 'us',
+      fields: {
+        name: { type: 'string' },
+        email: { type: 'email' },
+        password: { type: 'digest' },
+      },
+    },
+  },
+```
+
+It is ready to accept users with an email, name string, and hashed password.
+Let's create a user from a script.
+
+#### Setting up an apiKey 
+
+If we try to add a user now from a script, we get into a chicken and the egg issue. We don't have an authenticated user to add the user itself. You can work around this while developing using the apiKey functionality.
+This feature lets us create an apikey so we can use based in utility scripts and commands using the [based cli](https://github.com/atelier-saulx/based/tree/main/packages/cli).
+
+```bash
+$ npx based apiKeys add --name auth-demo-api-key --file ./apiKey.key
+```
+
+This command will create an apiKey called "auth-demo-api-key" and saves its value to a file we can load from the script or use as an argument in the [based cli](https://github.com/atelier-saulx/based/tree/main/packages/cli).
+
+**Note:** You should never store apiKeys as plain text in repositories or use them to make based connections client side.
+
+#### Setting a user with a script
+
+With the apiKey, we can now run a simple script to add a new user:
+
+```javascript
+// scripts/createUser.ts
+
+import fs from 'fs'
+import based from '@based/client'
+
+// Loads the based config file that sets up your based connection
+const basedConfig = JSON.parse(fs.readFileSync('../based.json', 'utf8'))
+
+// Loads apiKey so we can have based access from a script
+// Note: apiKeys should only be used for util scripts or server/server connections
+const apiKey = fs.readFileSync('../apiKey.key', 'utf8')
+
+;(async () => {
+  // Create a based client
+  const client = based(basedConfig)
+
+  // Authenticate client with an apiKey
+  await client.auth(apiKey, { isApiKey: true })
+
+  // Add our user
+  const { id } = await client.set({
+    type: 'user',
+    name: 'Demo User',
+    email: 'demo@wawa.com',
+    password: 'superStrongPassword',
+  })
+  console.log('Added user ' + id)
+
+  process.exit()
+})()
+```
+
+And lets run it:
+```bash
+$ cd scripts
+$ npx ts-node scripts/createUser.ts
+Added user us1b3d5a36
+```
+
+## Adding login functionality to your app.
+
+To login a user from your app, you should create a login UI, and use the based client `.login()` method to validate your user and password.
+Example:
+
+```javascript
+import based from '@based/client'
+
+// ...
+
+
+  <button
+    onClick={async () => {
+      const { token, refreshToken } = await client.login({
+        email,
+        password,
+      })
+      setToken(token)
+      setRefreshToken(refreshToken)
+    }}
+  >
+    Login
+  </button>
+```
+
+The `.login()` method takes the email and password supplied by the user, passes it to the `login` data function, and returns the result. Usually, a token and refreshToken if it was successful.
+You should also store your token and refreshToken if you want the session to persist.
+
+## Authenticating the user with a persisted token
+
+If your user already logged in and you persisted the tokens, you can authenticate it with the still valid token instead of login in.
+Example:
+```javascript
+  // ...
+  if (token) {
+    await client.auth(token, { refreshToken })
+  }
+```
+
+The `refreshToken` is also stored by the based client so it can be requested by the based servers if the token is expired and it tries to renew the token automatically.
+
+## Login out user
+
+You should run the based client `.logout()` method to explicitly log out a user. This method will clear the tokens on the based client and run the `logout` data function meant to perform clean-up actions like invalidating the current refreshToken.
+
+Example:
+```javascript
+  // ...
+  <button
+    onClick={async () => {
+      await client.logout()
+      setToken(null)
+      setRefreshToken(null)
+    }}
+  >
+    Logout
+  </button>
+```
+
+You should also clean the stored token and refreshToken from the browser.
+
+## Handling automatic token renewal
+
+The default template already has in place JWT token renewal using a refreshToken. You should however store the new token locally when this happens.
+For this we have the `renewToken` based client event that we can listen.
+Example:
+
+```javascript
+  // ...
+  const renewHandler = ({ token: newToken }: { token: string }) => {
+    setToken(newToken)
+  }
+
+  client.on('renewToken', renewHandler)
+```

package/docs/auth.md

@@ -0,0 +1,91 @@
+# The Auth System
+
+The *Based Auth* system helps developers add a security layer to their data. It does not enforce any logic itself, instead relies on a set of user-configurable *data functions* that restrict data access and implement whatever security strategy the user needs. Be it a 3rd party implementation or its own.
+
+The central concept is that all messages through based go through a [`authorize`](https://github.com/atelier-saulx/based/blob/main/packages/client/docs/authorize.md) function that implements the security logic and decides if each specific call to data should continue or be blocked.
+Within the data request, a "token" is also sent. This token is passed along to the `authorize` function for context, and it is what identifies the user in most implementations.
+
+There are no assumptions about the "token" format. It is up to the user to choose what implementation it wants or needs. However, we provide templates for JSON Web Tokens (JWT) authorization and will soon offer session-based authentication templates. These templates provide minimal authorization strategy implementation and are meant to be tweaked and updated by the user.
+Along with the `authorize` function, these templates also implement more optional functions that make a login flow more straightforward and more semantic. `login`, `logout`, and `renewToken`. 
+
+The *Based* client also catches exceptions triggered by token expiration. When this happens, it tries to call a `renewToken` function sending it a renew payload that includes, for example, the "refreshToken" used for JWT authorization flow. If that's successful and it returns a new token, it will re-request the data with the new token for transparent renewal.
+
+## Auth data functions
+
+### `authorize`
+
+This data function runs every time the based client tries to call, get, modify or observe data.
+It approves or denies the request depending on its context. See [`authorize`](https://github.com/atelier-saulx/based/blob/main/packages/client/docs/authorize.md)
+Returns boolean value allowing or disallowing the connection.
+
+Example: see [here](https://github.com/atelier-saulx/based/blob/main/packages/auth-templates/jwt/authorize/authorize.ts)
+
+### `login`
+
+Called then the client [login()]() method is called. It should authenticate the user and generate the tokens. Authentication flow is up to the user.
+For example, in a JWT flow, this function will validate the user in the data, sign a token and refreshToken returning them to the client.
+
+Example: see [here](https://github.com/atelier-saulx/based/blob/main/packages/auth-templates/jwt/login/login.ts)
+
+### `logout`
+
+When your app logs out a user, it should call the `client.logout()` method. This method calls this data function if it exists. It is meant to have token invalidation and any cleanup that should happen when a user logs out.
+
+Example: see [here](https://github.com/atelier-saulx/based/blob/main/packages/auth-templates/jwt/logout/logout.ts)
+
+### `renewToken`
+
+For auth flows that rely on token renewal. This data function runs when a specific error is triggered in the `authorize` function.
+The result is returned to the client using the `renewToken` client event.
+
+Example: see [here](https://github.com/atelier-saulx/based/blob/main/packages/auth-templates/jwt/renewToken/renewToken.ts)
+
+## Based client methods
+
+### `client.auth()`
+
+Sets the token to be sent during client/server messages. The token will be passed to the `authorize` function and can be decoded from it with `based.token()`.
+
+#### Usage
+```javascript
+// Setting token
+await client.auth(token)
+
+// Setting token and refreshToken for JWT flow
+await client.auth(token, { 
+	renewOptions: { refreshToken }
+})
+```
+
+### `client.login()`
+
+This data function sends the email and password to the `login` data function for authentication.
+Returns tokens if successful. Also, it will automatically set the returned token on the current client connection.
+
+#### Usage
+```javascript
+const tokens = await client.login({email, password}) 
+```
+
+### `client.logout()`
+
+Clears the tokens stored by the client and calls the `logout` data function if it exists.
+
+#### Usage
+```javascript
+await client.logout() 
+```
+
+### `client.on('renewToken', fn)`
+
+This event is called when the renewToken data function is run. It is used to handle and persist the newly generated tokens.
+
+#### Usage
+```javascript
+	client.on('renewToken', (renewTokenResult) => {})
+```
+
+
+## How to use
+
+Check [this guide](https://github.com/atelier-saulx/based/blob/main/packages/client/docs/auth-howto.md) for an example of how the use.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@based/client",
-  "version": "2.7.5",
+  "version": "2.10.0",
   "license": "MIT",
   "main": "dist/index.js",
   "browser": {
@@ -12,7 +12,8 @@
     "watch": "concurrently \"tsc --watch\" \"npm run buildBundle -- --watch\"",
     "test": "ava --timeout 1m --verbose",
     "watchTest": "ava --color --watch --verbose",
-    "clean": "rimraf {.turbo,dist,node_modules}"
+    "clean": "rimraf {.turbo,dist,node_modules}",
+    "browserTest": "concurrently \"node ./test/browser/based-server.js\" \"aristotle watch -t test/browser/index.tsx -p 8005\""
   },
   "sideEffects": false,
   "ava": {
@@ -30,7 +31,7 @@
   "dependencies": {
     "@based/get-service": "2.4.3",
     "@based/graphql": "2.4.2",
-    "@based/types": "^2.6.0",
+    "@based/types": "^2.7.1",
     "@saulx/diff": "^1.1.3",
     "@saulx/hash": "^1.1.0",
     "@saulx/utils": "^2.2.1",
@@ -45,6 +46,7 @@
     "@saulx/selva": "^11.0.0",
     "@saulx/utils": "^2.2.1",
     "@saulx/selva-server": "11.0.0",
+    "@saulx/aristotle": "^4.0.14",
     "@types/jsonwebtoken": "^8.5.6",
     "@types/node": "^17.0.23",
     "@types/ws": "^7.4.6",

package/dist/types.d.ts

@@ -1,253 +0,0 @@
-/// <reference types="node" />
-import type { GetOptions } from './selvaTypes/get';
-import type { SetOptions } from './selvaTypes/set';
-import type { Schema } from './selvaTypes/schema';
-import { Readable } from 'stream';
-export { GetOptions, SetOptions, Schema };
-export declare type DigestOptions = string;
-export declare enum RequestTypes {
-    Subscription = 1,
-    SubscriptionDiff = 2,
-    SendSubscriptionData = 3,
-    Unsubscribe = 4,
-    Set = 5,
-    Get = 6,
-    Configuration = 7,
-    GetConfiguration = 8,
-    Call = 9,
-    GetSubscription = 10,
-    Delete = 11,
-    Copy = 12,
-    Digest = 13,
-    Token = 14,
-    Track = 15,
-    Auth = 16
-}
-export declare enum AuthRequestTypes {
-    Login = 1,
-    Logout = 2,
-    RenewToken = 3
-}
-export declare type Configuration = {
-    schema: {
-        [db: string]: Schema;
-    };
-    dbs: string[];
-};
-export declare type Query = GetOptions;
-export declare type GenericObject = {
-    [key: string]: any;
-};
-export declare type Copy = {
-    $id: string;
-    db?: string;
-    deep?: boolean;
-    parents?: string[];
-    excludeFields?: string[];
-};
-export declare type ErrorObject = {
-    type: string;
-    message: string;
-    name?: string;
-    query?: GenericObject;
-    payload?: any;
-    auth?: boolean;
-    code?: string;
-};
-export declare type FunctionCallMessage = [RequestTypes.Call, string, number, any?];
-export declare type TrackMessage = [RequestTypes.Track, TrackPayload];
-export declare type RequestMessage<T = GenericObject> = [
-    (RequestTypes.Set | RequestTypes.Get | RequestTypes.Configuration | RequestTypes.GetConfiguration | RequestTypes.Delete | RequestTypes.Copy | RequestTypes.Digest),
-    number,
-    T
-];
-export declare type TokenMessage = [RequestTypes.Token, string?, boolean?];
-export declare type AuthMessage = [
-    RequestTypes.Auth,
-    AuthRequestTypes,
-    number,
-    GenericObject?
-];
-export declare type SubscribeMessage = [
-    RequestTypes.Subscription,
-    number,
-    GenericObject?,
-    number?,
-    (2 | 1 | 0)?,
-    string?
-];
-export declare type SendSubscriptionDataMessage = [
-    RequestTypes.SendSubscriptionData,
-    number,
-    number?
-];
-export declare type SendSubscriptionGetDataMessage = [
-    RequestTypes.GetSubscription,
-    number,
-    GenericObject?,
-    number?,
-    string?
-];
-export declare type UnsubscribeMessage = [
-    RequestTypes.Unsubscribe,
-    number
-];
-export declare type SubscriptionMessage = SubscribeMessage | SendSubscriptionDataMessage | UnsubscribeMessage | SendSubscriptionGetDataMessage;
-export declare type Message = RequestMessage | SubscriptionMessage | FunctionCallMessage | AuthMessage;
-export declare type SubscriptionDiffData = [
-    RequestTypes.SubscriptionDiff,
-    number,
-    GenericObject,
-    [
-        number,
-        number
-    ]
-];
-export declare type SubscriptionData = [
-    RequestTypes.Subscription,
-    number,
-    GenericObject,
-    number?,
-    ErrorObject?
-];
-export declare type RequestData = [
-    (RequestTypes.Set | RequestTypes.Get | RequestTypes.Configuration | RequestTypes.GetConfiguration | RequestTypes.Call | RequestTypes.Delete | RequestTypes.Copy | RequestTypes.Digest),
-    number,
-    any,
-    ErrorObject?
-];
-export declare type AuthorizedData = [RequestTypes.Token, number[], boolean?];
-export declare type AuthData = [
-    RequestTypes.Auth,
-    number,
-    GenericObject,
-    ErrorObject?
-];
-export declare type ResponseData = SubscriptionDiffData | SubscriptionData | RequestData | AuthorizedData | AuthData;
-export declare type TrackPayload = {
-    t: string;
-    u?: 1;
-    s?: 1;
-    e?: 1;
-    r?: 1;
-    o?: TrackOpts;
-};
-export declare type TrackOpts = {
-    amount?: number;
-};
-export declare type SendTokenOptions = {
-    isBasedUser?: boolean;
-    isApiKey?: boolean;
-    refreshToken?: string;
-};
-export declare type AnalyticsResult = {
-    all: {
-        total: number;
-        geo?: {
-            [isoCode: string]: number;
-        };
-    };
-    unique: {
-        total: number;
-        geo?: {
-            [isoCode: string]: number;
-        };
-    };
-    active: {
-        total: number;
-        max: number;
-        geo?: {
-            [isoCode: string]: number;
-        };
-    };
-};
-export declare type AnalyticsHistoryResult = {
-    all: {
-        total: [number, number][];
-        geo?: {
-            [isoCode: string]: [number, number][];
-        };
-    };
-    unique: {
-        total: [number, number][];
-        geo?: {
-            [isoCode: string]: [number, number][];
-        };
-    };
-    active: {
-        total: [number, number][];
-        geo?: {
-            [isoCode: string]: [number, number][];
-        };
-    };
-};
-export declare type AnalyticsTypes = string[];
-export declare type AnalyticsTypesOpts = {
-    type?: string;
-    $types: true;
-};
-export declare function isAnalyticsTypesOpts(opts: AnalyticsOpts | AnalyticsTypesOpts): opts is AnalyticsTypesOpts;
-export declare function isAnalyticsHistoryOpts(opts: AnalyticsOpts | AnalyticsTypesOpts): opts is AnalyticsHistoryOpts;
-export declare type AnalyticsOpts = {
-    type: string;
-    params?: {
-        [key: string]: number | string | boolean;
-    };
-    $geo?: string[] | boolean;
-};
-export declare type AnalyticsHistoryOpts = {
-    type: string;
-    params?: {
-        [key: string]: number | string | boolean;
-    };
-    $geo?: string[] | boolean;
-    $history: boolean | number;
-};
-export declare type LoginOpts = {
-    email: string;
-    password: string;
-};
-export declare type RenewTokenOpts = {
-    refreshToken: string;
-};
-export declare type FileUploadOptions = {
-    contents: Buffer | ArrayBuffer | string | File | Blob;
-    mimeType?: string;
-    name?: string;
-    url?: string | (() => Promise<string>);
-    id?: string;
-    raw?: boolean;
-    parents?: string[];
-    functionName?: string;
-};
-export declare type FileUploadStream = {
-    contents: Readable;
-    mimeType?: string;
-    extension?: string;
-    size: number;
-    name?: string;
-    url?: string | (() => Promise<string>);
-    id?: string;
-    raw?: boolean;
-    parents?: string[];
-    functionName?: string;
-};
-export declare type FileUploadPath = {
-    path: string;
-    mimeType?: string;
-    extension?: string;
-    name?: string;
-    url?: string | (() => Promise<string>);
-    id?: string;
-    raw?: boolean;
-    parents?: string[];
-    functionName?: string;
-};
-export declare type FileUploadSrc = {
-    src: string;
-    mimeType?: string;
-    name?: string;
-    id?: string;
-    parents?: string[];
-    size?: number;
-};