@enbox/agent 0.4.0 → 0.5.0

package/dist/types/connect.d.ts

@@ -1,84 +0,0 @@
-import type { EnboxConnectResponse } from './enbox-connect-protocol.js';
-import type { DwnPermissionScope, DwnProtocolDefinition } from './index.js';
-/**
- * Initiates the wallet connect process. Used when a client wants to obtain
- * a did from a provider.
- */
-declare function initClient({ displayName, connectServerUrl, walletUri, permissionRequests, onWalletUriReady, validatePin, }: WalletConnectOptions): Promise<{
-    delegateGrants: EnboxConnectResponse['delegateGrants'];
-    delegatePortableDid: EnboxConnectResponse['delegatePortableDid'];
-    connectedDid: string;
-} | undefined>;
-/**
- * Options for initiating a wallet connect flow (remote, relay-mediated).
- */
-export type WalletConnectOptions = {
-    /** The user-friendly name of the app, displayed in the wallet consent UI. */
-    displayName: string;
-    /** The URL of the connect server which relays messages between the app and wallet. */
-    connectServerUrl: string;
-    /**
-     * The URI of the wallet app. Query params (`request_uri`, `encryption_key`)
-     * are appended and passed to `onWalletUriReady`.
-     * @example `enbox://connect` or `http://localhost:3000/`
-     */
-    walletUri: string;
-    /**
-     * The protocols of permissions requested, along with the definition and
-     * permission scopes for each protocol. The key is the protocol URL and
-     * the value is an object with the protocol definition and the permission scopes.
-     */
-    permissionRequests: ConnectPermissionRequest[];
-    /**
-     * Called with the wallet URI including query params (`request_uri`, `encryption_key`).
-     * The app should render this as a QR code or use it as a deep link.
-     *
-     * @param uri - The wallet URI with connect payload.
-     */
-    onWalletUriReady: (uri: string) => void;
-    /**
-     * Called to collect the PIN from the user. The PIN is used as AAD
-     * when decrypting the connect response from the relay.
-     *
-     * @returns A promise that resolves to the PIN as a string.
-     */
-    validatePin: () => Promise<string>;
-};
-/**
- * The protocols of permissions requested, along with the definition and permission scopes for each protocol.
- */
-export type ConnectPermissionRequest = {
-    /**
-     * The definition of the protocol the permissions are being requested for.
-     * In the event that the protocol is not already installed, the wallet will install this given protocol definition.
-     */
-    protocolDefinition: DwnProtocolDefinition;
-    /** The scope of the permissions being requested for the given protocol */
-    permissionScopes: DwnPermissionScope[];
-};
-/**
- * Shorthand for the types of permissions that can be requested.
- */
-export type Permission = 'write' | 'read' | 'delete' | 'query' | 'subscribe' | 'configure';
-/**
- * The options for creating a permission request for a given protocol.
- */
-export type ProtocolPermissionOptions = {
-    /** The protocol definition for the protocol being requested */
-    definition: DwnProtocolDefinition;
-    /** The permissions being requested for the protocol */
-    permissions: Permission[];
-};
-/**
- * Creates a set of Dwn Permission Scopes to request for a given protocol.
- *
- * If no permissions are provided, the default is to request all relevant record permissions (write, read, delete, query, subscribe).
- * 'configure' is not included by default, as this gives the application a lot of control over the protocol.
- */
-declare function createPermissionRequestForProtocol({ definition, permissions }: ProtocolPermissionOptions): ConnectPermissionRequest;
-export declare const WalletConnect: {
-    initClient: typeof initClient;
-    createPermissionRequestForProtocol: typeof createPermissionRequestForProtocol;
-};
-export {};
-//# sourceMappingURL=connect.d.ts.map

package/dist/types/connect.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../../src/connect.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAyB,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAC/F,OAAO,KAAK,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAS5E;;;GAGG;AACH,iBAAe,UAAU,CAAC,EACxB,WAAW,EACX,gBAAgB,EAChB,SAAS,EACT,kBAAkB,EAClB,gBAAgB,EAChB,WAAW,GACZ,EAAE,oBAAoB,GAAG,OAAO,CAAC;IAChC,cAAc,EAAE,oBAAoB,CAAC,gBAAgB,CAAC,CAAC;IACvD,mBAAmB,EAAE,oBAAoB,CAAC,qBAAqB,CAAC,CAAC;IACjE,YAAY,EAAE,MAAM,CAAC;CACtB,GAAG,SAAS,CAAC,CAkGb;AAED;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,6EAA6E;IAC7E,WAAW,EAAE,MAAM,CAAC;IAEpB,sFAAsF;IACtF,gBAAgB,EAAE,MAAM,CAAC;IAEzB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,kBAAkB,EAAE,wBAAwB,EAAE,CAAC;IAE/C;;;;;OAKG;IACH,gBAAgB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAExC;;;;;OAKG;IACH,WAAW,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CACpC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC;;;OAGG;IACH,kBAAkB,EAAE,qBAAqB,CAAC;IAE1C,0EAA0E;IAC1E,gBAAgB,EAAE,kBAAkB,EAAE,CAAC;CACxC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,GAAG,WAAW,GAAG,WAAW,CAAC;AAE3F;;GAEG;AACH,MAAM,MAAM,yBAAyB,GAAG;IACtC,+DAA+D;IAC/D,UAAU,EAAE,qBAAqB,CAAC;IAElC,uDAAuD;IACvD,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B,CAAC;AAEF;;;;;GAKG;AACH,iBAAS,kCAAkC,CAAC,EAAE,UAAU,EAAE,WAAW,EAAE,EAAE,yBAAyB,GAAG,wBAAwB,CAsE5H;AAED,eAAO,MAAM,aAAa;;;CAAqD,CAAC"}

package/dist/types/sync-api.d.ts

@@ -1,40 +0,0 @@
-import type { EnboxPlatformAgent } from './types/agent.js';
-import type { StartSyncParams, SyncConnectivityState, SyncEngine, SyncIdentityOptions } from './types/sync.js';
-export type SyncApiParams = {
-    agent?: EnboxPlatformAgent;
-    syncEngine: SyncEngine;
-};
-export declare class AgentSyncApi implements SyncEngine {
-    /**
-     * Holds the instance of a `EnboxPlatformAgent` that represents the current execution context for
-     * the `AgentSyncApi`. This agent is used to interact with other Enbox agent components. It's vital
-     * to ensure this instance is set to correctly contextualize operations within the broader Enbox
-     * Agent framework.
-     */
-    private _agent?;
-    private _syncEngine;
-    constructor({ agent, syncEngine }: SyncApiParams);
-    /**
-     * Retrieves the `EnboxPlatformAgent` execution context.
-     *
-     * @returns The `EnboxPlatformAgent` instance that represents the current execution context.
-     * @throws Will throw an error if the `agent` instance property is undefined.
-     */
-    get agent(): EnboxPlatformAgent;
-    set agent(agent: EnboxPlatformAgent);
-    get connectivityState(): SyncConnectivityState;
-    registerIdentity(params: {
-        did: string;
-        options?: SyncIdentityOptions;
-    }): Promise<void>;
-    unregisterIdentity(did: string): Promise<void>;
-    getIdentityOptions(did: string): Promise<SyncIdentityOptions | undefined>;
-    updateIdentityOptions(params: {
-        did: string;
-        options: SyncIdentityOptions;
-    }): Promise<void>;
-    sync(direction?: 'push' | 'pull'): Promise<void>;
-    startSync(params: StartSyncParams): Promise<void>;
-    stopSync(timeout?: number): Promise<void>;
-}
-//# sourceMappingURL=sync-api.d.ts.map

package/dist/types/sync-api.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"sync-api.d.ts","sourceRoot":"","sources":["../../src/sync-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAE/G,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,CAAC,EAAE,kBAAkB,CAAC;IAC3B,UAAU,EAAE,UAAU,CAAC;CACxB,CAAC;AAEF,qBAAa,YAAa,YAAW,UAAU;IAC7C;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,CAAqB;IAEpC,OAAO,CAAC,WAAW,CAAa;gBAEpB,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,aAAa;IAKhD;;;;;OAKG;IACH,IAAI,KAAK,IAAI,kBAAkB,CAM9B;IAED,IAAI,KAAK,CAAC,KAAK,EAAE,kBAAkB,EAGlC;IAED,IAAI,iBAAiB,IAAI,qBAAqB,CAE7C;IAEY,gBAAgB,CAAC,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,mBAAmB,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvF,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9C,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC;IAIzE,qBAAqB,CAAC,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,mBAAmB,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjG,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhD,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGjD"}

package/src/connect.ts

@@ -1,276 +0,0 @@
-
-import type { ConnectPushedResponse, EnboxConnectResponse } from './enbox-connect-protocol.js';
-import type { DwnPermissionScope, DwnProtocolDefinition } from './index.js';
-
-import { CryptoUtils } from '@enbox/crypto';
-import { DidJwk } from '@enbox/dids';
-import { EnboxConnectProtocol } from './enbox-connect-protocol.js';
-import { pollWithTtl } from './utils.js';
-import { Convert, logger } from '@enbox/common';
-import { DwnInterfaceName, DwnMethodName } from '@enbox/dwn-sdk-js';
-
-/**
- * Initiates the wallet connect process. Used when a client wants to obtain
- * a did from a provider.
- */
-async function initClient({
-  displayName,
-  connectServerUrl,
-  walletUri,
-  permissionRequests,
-  onWalletUriReady,
-  validatePin,
-}: WalletConnectOptions): Promise<{
-  delegateGrants: EnboxConnectResponse['delegateGrants'];
-  delegatePortableDid: EnboxConnectResponse['delegatePortableDid'];
-  connectedDid: string;
-} | undefined> {
-  // ephemeral client did for ECDH, signing, verification
-  const clientDid = await DidJwk.create();
-
-  // TODO: properly implement PKCE. this implementation is lacking server side validations and more.
-  // https://github.com/enboxorg/enbox/issues/829
-  // Derive the code challenge based on the code verifier
-  // const { codeChallengeBytes, codeChallengeBase64Url } =
-  //   await Oidc.generateCodeChallenge();
-  const encryptionKey = CryptoUtils.randomBytes(32);
-
-  // Build callback URL for the connect request.
-  const callbackEndpoint = EnboxConnectProtocol.buildConnectUrl({
-    baseURL  : connectServerUrl,
-    endpoint : 'callback',
-  });
-
-  // Build the connect request.
-  const request = await EnboxConnectProtocol.createConnectRequest({
-    clientDid          : clientDid.uri,
-    callbackUrl        : callbackEndpoint,
-    permissionRequests : permissionRequests,
-    appName            : displayName,
-  });
-
-  // Sign the request as a JWT.
-  const requestJwt = await EnboxConnectProtocol.signJwt({
-    did  : clientDid,
-    data : request as unknown as Record<string, unknown>,
-  });
-
-  if (!requestJwt) {
-    throw new Error('Unable to sign requestObject');
-  }
-  // Encrypt the request JWT with the symmetric key.
-  const requestObjectJwe = await EnboxConnectProtocol.encryptRequest({
-    jwt: requestJwt,
-    encryptionKey,
-  });
-
-  const pushedAuthorizationRequestEndpoint = EnboxConnectProtocol.buildConnectUrl({
-    baseURL  : connectServerUrl,
-    endpoint : 'pushedAuthorizationRequest',
-  });
-
-  const parResponse = await fetch(pushedAuthorizationRequestEndpoint, {
-    body    : JSON.stringify({ request: requestObjectJwe }),
-    method  : 'POST',
-    headers : {
-      'Content-Type': 'application/json',
-    },
-    signal: AbortSignal.timeout(30_000),
-  });
-
-  if (!parResponse.ok) {
-    throw new Error(`${parResponse.status}: ${parResponse.statusText}`);
-  }
-
-  const parData: ConnectPushedResponse = await parResponse.json();
-
-  // a deeplink to a compatible wallet. if the wallet scans this link it should receive
-  // a route to its Connect provider flow and the params of where to fetch the auth request.
-  logger.log(`Wallet URI: ${walletUri}`);
-  const generatedWalletUri = new URL(walletUri);
-  generatedWalletUri.searchParams.set('request_uri', parData.request_uri);
-  generatedWalletUri.searchParams.set(
-    'encryption_key',
-    Convert.uint8Array(encryptionKey).toBase64Url()
-  );
-
-  // call user's callback so they can send the URI to the wallet as they see fit
-  onWalletUriReady(generatedWalletUri.toString());
-
-  const tokenUrl = EnboxConnectProtocol.buildConnectUrl({
-    baseURL    : connectServerUrl,
-    endpoint   : 'token',
-    tokenParam : request.state,
-  });
-
-  // subscribe to receiving a response from the wallet with default TTL. receive ciphertext of {@link EnboxConnectAuthResponse}
-  const authResponse = await pollWithTtl(() => fetch(tokenUrl, { signal: AbortSignal.timeout(30_000) }));
-
-  if (authResponse) {
-    const jwe = await authResponse?.text();
-
-    // Get the PIN from the user and use it as AAD to decrypt.
-    const pin = await validatePin();
-    const jwt = await EnboxConnectProtocol.decryptResponse(clientDid, jwe, pin);
-    const verifiedResponse = (await EnboxConnectProtocol.verifyJwt({
-      jwt,
-    })) as unknown as EnboxConnectResponse;
-
-    return {
-      delegateGrants      : verifiedResponse.delegateGrants,
-      delegatePortableDid : verifiedResponse.delegatePortableDid,
-      connectedDid        : verifiedResponse.providerDid,
-    };
-  }
-}
-
-/**
- * Options for initiating a wallet connect flow (remote, relay-mediated).
- */
-export type WalletConnectOptions = {
-  /** The user-friendly name of the app, displayed in the wallet consent UI. */
-  displayName: string;
-
-  /** The URL of the connect server which relays messages between the app and wallet. */
-  connectServerUrl: string;
-
-  /**
-   * The URI of the wallet app. Query params (`request_uri`, `encryption_key`)
-   * are appended and passed to `onWalletUriReady`.
-   * @example `enbox://connect` or `http://localhost:3000/`
-   */
-  walletUri: string;
-
-  /**
-   * The protocols of permissions requested, along with the definition and
-   * permission scopes for each protocol. The key is the protocol URL and
-   * the value is an object with the protocol definition and the permission scopes.
-   */
-  permissionRequests: ConnectPermissionRequest[];
-
-  /**
-   * Called with the wallet URI including query params (`request_uri`, `encryption_key`).
-   * The app should render this as a QR code or use it as a deep link.
-   *
-   * @param uri - The wallet URI with connect payload.
-   */
-  onWalletUriReady: (uri: string) => void;
-
-  /**
-   * Called to collect the PIN from the user. The PIN is used as AAD
-   * when decrypting the connect response from the relay.
-   *
-   * @returns A promise that resolves to the PIN as a string.
-   */
-  validatePin: () => Promise<string>;
-};
-
-/**
- * The protocols of permissions requested, along with the definition and permission scopes for each protocol.
- */
-export type ConnectPermissionRequest = {
-  /**
-   * The definition of the protocol the permissions are being requested for.
-   * In the event that the protocol is not already installed, the wallet will install this given protocol definition.
-   */
-  protocolDefinition: DwnProtocolDefinition;
-
-  /** The scope of the permissions being requested for the given protocol */
-  permissionScopes: DwnPermissionScope[];
-};
-
-/**
- * Shorthand for the types of permissions that can be requested.
- */
-export type Permission = 'write' | 'read' | 'delete' | 'query' | 'subscribe' | 'configure';
-
-/**
- * The options for creating a permission request for a given protocol.
- */
-export type ProtocolPermissionOptions = {
-  /** The protocol definition for the protocol being requested */
-  definition: DwnProtocolDefinition;
-
-  /** The permissions being requested for the protocol */
-  permissions: Permission[];
-};
-
-/**
- * Creates a set of Dwn Permission Scopes to request for a given protocol.
- *
- * If no permissions are provided, the default is to request all relevant record permissions (write, read, delete, query, subscribe).
- * 'configure' is not included by default, as this gives the application a lot of control over the protocol.
- */
-function createPermissionRequestForProtocol({ definition, permissions }: ProtocolPermissionOptions): ConnectPermissionRequest {
-  const requests: DwnPermissionScope[] = [];
-
-  // Add the ability to query for the specific protocol
-  requests.push({
-    protocol  : definition.protocol,
-    interface : DwnInterfaceName.Protocols,
-    method    : DwnMethodName.Query,
-  });
-
-  // A Messages.Read grant is a unified scope that covers MessagesRead, MessagesSync, and MessagesSubscribe.
-  // This single grant enables sync and real-time subscriptions for the protocol.
-  requests.push({
-    protocol  : definition.protocol,
-    interface : DwnInterfaceName.Messages,
-    method    : DwnMethodName.Read,
-  });
-
-  // We also request any additional permissions the user has requested for this protocol
-  for (const permission of permissions) {
-    switch (permission) {
-      case 'write':
-        requests.push({
-          protocol  : definition.protocol,
-          interface : DwnInterfaceName.Records,
-          method    : DwnMethodName.Write,
-        });
-        break;
-      case 'read':
-        requests.push({
-          protocol  : definition.protocol,
-          interface : DwnInterfaceName.Records,
-          method    : DwnMethodName.Read,
-        });
-        break;
-      case 'delete':
-        requests.push({
-          protocol  : definition.protocol,
-          interface : DwnInterfaceName.Records,
-          method    : DwnMethodName.Delete,
-        });
-        break;
-      case 'query':
-        requests.push({
-          protocol  : definition.protocol,
-          interface : DwnInterfaceName.Records,
-          method    : DwnMethodName.Query,
-        });
-        break;
-      case 'subscribe':
-        requests.push({
-          protocol  : definition.protocol,
-          interface : DwnInterfaceName.Records,
-          method    : DwnMethodName.Subscribe,
-        });
-        break;
-      case 'configure':
-        requests.push({
-          protocol  : definition.protocol,
-          interface : DwnInterfaceName.Protocols,
-          method    : DwnMethodName.Configure,
-        });
-        break;
-    }
-  }
-
-  return {
-    protocolDefinition : definition,
-    permissionScopes   : requests,
-  };
-}
-
-export const WalletConnect = { initClient, createPermissionRequestForProtocol };

package/src/sync-api.ts

@@ -1,75 +0,0 @@
-import type { EnboxPlatformAgent } from './types/agent.js';
-import type { StartSyncParams, SyncConnectivityState, SyncEngine, SyncIdentityOptions } from './types/sync.js';
-
-export type SyncApiParams = {
-  agent?: EnboxPlatformAgent;
-  syncEngine: SyncEngine;
-};
-
-export class AgentSyncApi implements SyncEngine {
-  /**
-   * Holds the instance of a `EnboxPlatformAgent` that represents the current execution context for
-   * the `AgentSyncApi`. This agent is used to interact with other Enbox agent components. It's vital
-   * to ensure this instance is set to correctly contextualize operations within the broader Enbox
-   * Agent framework.
-   */
-  private _agent?: EnboxPlatformAgent;
-
-  private _syncEngine: SyncEngine;
-
-  constructor({ agent, syncEngine }: SyncApiParams) {
-    this._syncEngine = syncEngine;
-    this._agent = agent;
-  }
-
-  /**
-   * Retrieves the `EnboxPlatformAgent` execution context.
-   *
-   * @returns The `EnboxPlatformAgent` instance that represents the current execution context.
-   * @throws Will throw an error if the `agent` instance property is undefined.
-   */
-  get agent(): EnboxPlatformAgent {
-    if (this._agent === undefined) {
-      throw new Error('AgentSyncApi: Unable to determine agent execution context.');
-    }
-
-    return this._agent;
-  }
-
-  set agent(agent: EnboxPlatformAgent) {
-    this._agent = agent;
-    this._syncEngine.agent = agent;
-  }
-
-  get connectivityState(): SyncConnectivityState {
-    return this._syncEngine.connectivityState;
-  }
-
-  public async registerIdentity(params: { did: string; options?: SyncIdentityOptions }): Promise<void> {
-    await this._syncEngine.registerIdentity(params);
-  }
-
-  public async unregisterIdentity(did: string): Promise<void> {
-    await this._syncEngine.unregisterIdentity(did);
-  }
-
-  public async getIdentityOptions(did: string): Promise<SyncIdentityOptions | undefined> {
-    return await this._syncEngine.getIdentityOptions(did);
-  }
-
-  public async updateIdentityOptions(params: { did: string, options: SyncIdentityOptions }): Promise<void> {
-    await this._syncEngine.updateIdentityOptions(params);
-  }
-
-  public sync(direction?: 'push' | 'pull'): Promise<void> {
-    return this._syncEngine.sync(direction);
-  }
-
-  public startSync(params: StartSyncParams): Promise<void> {
-    return this._syncEngine.startSync(params);
-  }
-
-  public stopSync(timeout?: number): Promise<void> {
-    return this._syncEngine.stopSync(timeout);
-  }
-}