@coasys/ad4m-connect v0.10.1-release-candidate-4-test
AD4M Connection Library and Authentication Wizard
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
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
Authentication Flow
When an application wants to connect to an AD4M executor, it goes through a secure authentication handshake:
- The application requests access with specific capabilities
- The AD4M executor generates a random verification code
- The user must confirm the request and enter the code
- Upon successful verification, a capability token is issued
Visual Flow
Initial Connection Screen:
Executor Found:
Authorization Request:
Verification Code:
Usage
In the Browser
import Ad4mConnectUI from "@coasys/ad4m-connect";
const ui = Ad4mConnect({
// 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) => {
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;
}
});
// Connect and get AD4M client
ui.connect().then((client) => {
// Client is now ready to use
console.log("Connected with capabilities");
});
In Node.js / Electron
const { ad4mConnect } = require("@coasys/ad4m-connect/electron");
ad4mConnect({
// Provide the name of your app to be displayed in the dialog
appName: "Perspect3ve",
// Provide an icon to be displayed in the dialog as well
appIconPath: path.join(__dirname, "graphics", "Logo.png"),
// Name the capabilities your app needs
// (this is an example with all capabilities)
capabilities: [{ with: { domain: "*", pointers: ["*"] }, can: ["*"] }],
// Provide a directory in which the capability token and the executor
// URL will be stored such that future calls won't even open a dialog
// but try the token against that URL and resolve immediately
// if it works.
dataPath: path.join(homedir(), ".perspect3ve"),
})
.then(({ client, capabilityToken, executorUrl }) => {
// Retrieved `capabilityToken` and selected `executorUrl` are returned
// but all that is really needed is `client` which is a fully setup
// (including capability token) and working Ad4mClient.
//
// Both, the URL and the token have already been stored on disk
// in the directory provided as `dataPath`.
//
// Consequetive calls
createWindow(client);
})
.catch(() => {
console.log("User closed AD4M connection wizard. Exiting...");
app.exit(0);
process.exit(0);
});
Capability Specification
When requesting capabilities, specify:
{
with: {
domain: string | "*", // Which perspective/domain
pointers: string[] | "*" // Which parts of the domain
},
can: string[] | "*" // Which operations are allowed
}
Examples:
// 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 capabilitiesunauthenticated
: No valid authenticationlocked
: Agent is locked
connectionstatechange
:connecting
: Attempting to connectconnected
: Successfully connectednot_connected
: No connectiondisconnected
: Lost connectionerror
: Connection error
configstatechange
: Configuration changes fortoken
,url
, orport
Mobile Integration
Android Setup
Add to android/app/src/main/AndroidManifest.xml
:
<?xml version="1.0" encoding="utf-8"?>
<manifest
xmlns:android="http://schemas.android.com/apk/res/android"
+ xmlns:tools="http://schemas.android.com/tools"
package="com.example">
<application
+ android:hardwareAccelerated="true"
>
</application>
+ <uses-permission android:name="android.permission.CAMERA" />
+ <uses-sdk tools:overrideLibrary="com.google.zxing.client.android" />
</manifest>
iOS Setup
Add to Info.plist
:
<dict>
+ <key>NSCameraUsageDescription</key>
+ <string>To be able to scan barcodes</string>
</dict>
After changes, run:
npx cap sync
npx cap build
Best Practices
Request Minimal Capabilities
- Only request permissions your app actually needs
- Use specific domains and operations instead of wildcards
- Consider read-only access when possible
Handle Authentication States
- Check if capabilities are still valid
- Implement reconnection logic
- Handle capability revocation gracefully
Secure Storage
- Store capability tokens securely
- Never expose admin credentials
- Implement token refresh mechanisms
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:
9 months ago
9 months ago
9 months ago
9 months ago
8 months ago
9 months ago
9 months ago
10 months ago
10 months ago
10 months ago
6 months ago
7 months ago
7 months ago
5 months ago
8 months ago
7 months ago
4 months ago
10 months ago
8 months ago
8 months ago
8 months ago
10 months ago
7 months ago
8 months ago
6 months ago
10 months ago
11 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
10 months ago
8 months ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago