@coasys/ad4m-connect 0.10.0 → 0.10.1-multi-user-1

package/README.md

@@ -1,60 +1,110 @@
-# AD4M connection library and wizard for apps
+# AD4M Connection Library and Authentication Wizard
 
-This package makes it easy for AD4M apps to connect to a local or remote AD4M executor by handling all the complex things like finding the local executor port, requesting and storing a capability token, creating and recreating an Ad4mClient.
+A powerful library that simplifies connecting applications to AD4M executors by handling:
+- Executor discovery and connection
+- Capability-based authentication
+- Token management and storage
+- Connection state management
 
 <div style="text-align: center">
-<img src="screenshots/Screenshot_executor_url.png" width="400"></img>
+<img src="/docs/public/images/connect1.jpg" width="400" alt="AD4M Connect Initial Screen"></img>
 </div>
 
+## Overview
+
+AD4M uses a capability-based security model to protect user data and control access to agent functionality. Every application that wants to interact with an AD4M executor needs to request specific capabilities, which are then granted (or denied) by the user.
+
+### What are Capabilities?
+
+Capabilities in AD4M are like permission tokens that:
+- Define what data an application can access (which perspectives)
+- Specify what operations an application can perform
+- Are scoped to specific domains and functions
+- Can be revoked by the user at any time
+
+A capability token might grant permissions like:
+- Read access to specific perspectives
+- Write access to create or modify links
+- Ability to create new perspectives
+- Permission to manage agent relationships
+- Access to specific language functions
+
 ## Installation
 
-`npm install -s @coasys/ad4m-connect`
+```bash
+npm install -s @coasys/ad4m-connect
+```
 
-## Properties
+## Authentication Flow
 
-- `appName(required)`: Name of the application using ad4m-connect.
-- `appDesc(required)`: Description of the application using ad4m-connect.
-- `appDomain(required)`: Domain of the application using ad4m-connect.
-- `capabilities(required)`: Capabilities requested by the application.
-- `appIconPath`: Icon for the app using ad4m-connect.
-- `port`: Port that AD4M is running on.
-- `token`: JWT token if you have one.
-- `url`: The url that we should connect to.
+When an application wants to connect to an AD4M executor, it goes through a secure authentication handshake:
 
-## Events
+1. The application requests access with specific capabilities
+2. The AD4M executor generates a random verification code
+3. The user must confirm the request and enter the code
+4. Upon successful verification, a capability token is issued
+
+### Visual Flow
+
+1. Initial Connection Screen:
+   ![Initial Connection](/docs/public/images/connect1.jpg)
+
+2. Executor Found:
+   ![Executor Found](/docs/public/images/connect2.jpg)
 
-- `authstatechange`: `authenticated` | `unauthenticated` | `locked`
-- `connectionstatechange`: `connecting` | `connected` | `not_connected` | `disconnected` | `error`;
-- `configstatechange`: `token` | `url` | `port`
+3. Authorization Request:
+   ![Authorization Request](/docs/public/images/authorize1.jpg)
 
-## In the Browser
+4. Verification Code:
+   ![Verification Code](/docs/public/images/authorize2.jpg)
+
+## Usage
+
+### In the Browser
 
 ```js
 import Ad4mConnectUI from "@coasys/ad4m-connect";
 
 const ui = Ad4mConnect({
-  appName: "Example",
-  appDesc: "This is a sample app.",
-  appDomain: "ad4m.dev",
-  appIconPath: "https://i.ibb.co/GnqjPJP/icon.png",
-  capabilities: [{ with: { domain: "*", pointers: ["*"] }, can: ["*"] }],
+  // Required parameters
+  appName: "My AD4M App",
+  appDesc: "A description of what your app does",
+  appDomain: "myapp.com",
+  capabilities: [{ 
+    with: { domain: "*", pointers: ["*"] }, 
+    can: ["*"] 
+  }],
+  
+  // Optional parameters
+  appIconPath: "https://myapp.com/icon.png",
+  port: 12345,  // Custom port
+  token: "existing-token",  // Existing JWT token
+  url: "custom-executor-url"  // Custom executor URL
 });
 
+// Listen for authentication state changes
 ui.addEventListener("authstatechange", (e) => {
-  if (e.detail === "authenticated") {
-    // We are authenticated
+  switch(e.detail) {
+    case "authenticated":
+      console.log("Successfully authenticated");
+      break;
+    case "unauthenticated":
+      console.log("Not authenticated");
+      break;
+    case "locked":
+      console.log("Agent is locked");
+      break;
   }
 });
 
-// Open popup and save the client when we are done
+// Connect and get AD4M client
 ui.connect().then((client) => {
-  // Save the client
+  // Client is now ready to use
+  console.log("Connected with capabilities");
 });
 ```
 
-## Usage (from Node / Electron)
-
-Call ad4mConnect with parameters of your app:
+### In Node.js / Electron
 
 ```js
 const { ad4mConnect } = require("@coasys/ad4m-connect/electron");
@@ -91,9 +141,55 @@ ad4mConnect({
   });
 ```
 
-# Extra steps to be used in capacitor:
+### Capability Specification
+
+When requesting capabilities, specify:
+
+```js
+{
+  with: {
+    domain: string | "*",     // Which perspective/domain
+    pointers: string[] | "*"  // Which parts of the domain
+  },
+  can: string[] | "*"         // Which operations are allowed
+}
+```
+
+Examples:
+```js
+// Full access (development only)
+{ with: { domain: "*", pointers: ["*"] }, can: ["*"] }
+
+// Read-only access to a perspective
+{ with: { domain: "perspective-uuid", pointers: ["*"] }, can: ["read"] }
+
+// Specific operations on a domain
+{ with: { domain: "friends", pointers: ["*"] }, can: ["read", "add", "remove"] }
+```
+
+## Events
+
+The library emits various events to help track connection state:
+
+- `authstatechange`: 
+  - `authenticated`: Successfully connected with capabilities
+  - `unauthenticated`: No valid authentication
+  - `locked`: Agent is locked
+
+- `connectionstatechange`:
+  - `connecting`: Attempting to connect
+  - `connected`: Successfully connected
+  - `not_connected`: No connection
+  - `disconnected`: Lost connection
+  - `error`: Connection error
+
+- `configstatechange`: Configuration changes for `token`, `url`, or `port`
+
+## Mobile Integration
 
-- On Android
+### Android Setup
+
+Add to `android/app/src/main/AndroidManifest.xml`:
 ```diff
 <?xml version="1.0" encoding="utf-8"?>
 <manifest
@@ -112,7 +208,9 @@ ad4mConnect({
 </manifest>
 ```
 
-- On IOs
+### iOS Setup
+
+Add to `Info.plist`:
 ```diff
 <dict>
 +  <key>NSCameraUsageDescription</key>
@@ -120,4 +218,35 @@ ad4mConnect({
 </dict>
 ```
 
-- Then run `npx cap sync` & `npx cap build`
+After changes, run:
+```bash
+npx cap sync
+npx cap build
+```
+
+## Best Practices
+
+1. **Request Minimal Capabilities**
+   - Only request permissions your app actually needs
+   - Use specific domains and operations instead of wildcards
+   - Consider read-only access when possible
+
+2. **Handle Authentication States**
+   - Check if capabilities are still valid
+   - Implement reconnection logic
+   - Handle capability revocation gracefully
+
+3. **Secure Storage**
+   - Store capability tokens securely
+   - Never expose admin credentials
+   - Implement token refresh mechanisms
+
+4. **User Experience**
+   - Clearly explain why your app needs certain capabilities
+   - Provide feedback during the authentication process
+   - Handle errors gracefully
+
+## More Information
+
+For more details about AD4M authentication and capabilities:
+- [AD4M Documentation](https://docs.ad4m.dev/auth)

package/dist/components/ConnectionOverview.d.ts

@@ -0,0 +1,13 @@
+type ConnectionOverviewProps = {
+    localDetected: boolean;
+    multiUserConfigured: boolean;
+    backendUrl?: string;
+    configuredUrl?: string;
+    isMobile: boolean;
+    onConnectLocal: () => void;
+    onConnectRemote: () => void;
+    onScanQR: () => void;
+    onDownloadAd4m: () => void;
+};
+export default function ConnectionOverview({ localDetected, multiUserConfigured, backendUrl, configuredUrl, isMobile, onConnectLocal, onConnectRemote, onScanQR, onDownloadAd4m, }: ConnectionOverviewProps): import("lit").TemplateResult<1>;
+export {};

package/dist/components/MultiUserAuth.d.ts

@@ -0,0 +1,15 @@
+type MultiUserAuthProps = {
+    email: string;
+    password: string;
+    error: string | null;
+    isLoading: boolean;
+    backendUrl?: string;
+    changeEmail: (email: string) => void;
+    changePassword: (password: string) => void;
+    onLogin: () => void;
+    onSignup: () => void;
+    activeTab: "login" | "signup";
+    setActiveTab: (tab: "login" | "signup") => void;
+};
+export default function MultiUserAuth({ email, password, error, isLoading, backendUrl, changeEmail, changePassword, onLogin, onSignup, activeTab, setActiveTab, }: MultiUserAuthProps): import("lit").TemplateResult<1>;
+export {};

package/dist/components/RemoteConnection.d.ts

@@ -0,0 +1,13 @@
+type RemoteConnectionProps = {
+    initialUrl?: string;
+    detecting: boolean;
+    multiUserDetected: boolean | null;
+    error: string | null;
+    onBack: () => void;
+    onUrlChange: (url: string) => void;
+    onConnect: () => void;
+    onMultiUserAuth: () => void;
+    onRequestCapability: () => void;
+};
+export default function RemoteConnection({ initialUrl, detecting, multiUserDetected, error, onBack, onUrlChange, onConnect, onMultiUserAuth, onRequestCapability, }: RemoteConnectionProps): import("lit").TemplateResult<1>;
+export {};

package/dist/core.d.ts

@@ -14,11 +14,15 @@ export type Ad4mConnectOptions = {
     url?: string;
     hosting?: boolean;
     mobile?: boolean;
+    multiUser?: boolean;
+    backendUrl?: string;
+    userEmail?: string;
+    userPassword?: string;
 };
 export type AuthStates = "authenticated" | "locked" | "unauthenticated";
 export type Event = "authstatechange" | "connectionstatechange" | "configstatechange";
 export type ConfigStates = "port" | "url" | "token";
-export type ConnectionStates = "connecting" | "connected" | "error" | "port_not_found" | "not_connected" | "disconnected";
+export type ConnectionStates = "connecting" | "connected" | "error" | "port_not_found" | "not_connected" | "disconnected" | "checking_local";
 export default class Ad4mConnect {
     activeSocket: WebSocket;
     requestedRestart: boolean;
@@ -38,8 +42,9 @@ export default class Ad4mConnect {
     appIconPath: string;
     appUrl?: string;
     isHosting: boolean;
+    options: Ad4mConnectOptions;
     listeners: Record<Event, Function[]>;
-    constructor({ appName, appDesc, appIconPath, appUrl, appDomain, capabilities, port, token, url, hosting }: Ad4mConnectOptions);
+    constructor(options: Ad4mConnectOptions);
     private notifyConfigChange;
     private notifyConnectionChange;
     private notifyAuthChange;
@@ -47,7 +52,9 @@ export default class Ad4mConnect {
     setUrl(url: string): void;
     setToken(token: string): void;
     on(event: Event, cb: Function): void;
+    buildTempClient(url: string): Ad4mClient;
     connect(url?: string): Promise<Ad4mClient>;
+    connectMultiUser(): Promise<Ad4mClient>;
     loginToHosting(email: string, password: string): Promise<void>;
     checkEmail(email: string): Promise<boolean>;
     connectToPort(port?: number): Promise<Ad4mClient>;