@enbox/api 0.0.1

package/src/grant-revocation.ts

@@ -0,0 +1,124 @@
+import { AgentPermissionsApi, DwnDataEncodedRecordsWriteMessage, DwnResponseStatus, getRecordAuthor, SendDwnRequest, Web5Agent } from '@enbox/agent';
+import { DwnInterface } from '@enbox/agent';
+import { Convert } from '@enbox/common';
+
+/**
+ * Represents the structured data model of a GrantRevocation record, encapsulating the essential fields that define.
+ */
+export interface GrantRevocationModel {
+  /** The DWN message used to construct this revocation */
+  rawMessage: DwnDataEncodedRecordsWriteMessage;
+}
+
+/**
+ * Represents the options for creating a new GrantRevocation instance.
+ */
+export interface GrantRevocationOptions {
+  /** The DID of the DWN tenant under which record operations are being performed. */
+  connectedDid: string;
+  /** The DWN message used to construct this revocation */
+  message: DwnDataEncodedRecordsWriteMessage;
+}
+
+/**
+ * The `PermissionGrantRevocation` class encapsulates a permissions protocol `grant/revocation` record, providing a more
+ * developer-friendly interface for working with Decentralized Web Node (DWN) records.
+ *
+ * Methods are provided to manage the grant revocation's lifecycle, including writing to remote DWNs.
+ *
+ * @beta
+ */
+export class PermissionGrantRevocation implements GrantRevocationModel {
+  /** The PermissionsAPI used to interact with the underlying revocation  */
+  private _permissions: AgentPermissionsApi;
+  /** The DID to use as the author and default target for the underlying revocation */
+  private _connectedDid: string;
+  /** The DWN `RecordsWrite` message, along with encodedData that represents the revocation */
+  private _message: DwnDataEncodedRecordsWriteMessage;
+
+  private constructor(permissions: AgentPermissionsApi, options: GrantRevocationOptions) {
+    this._permissions = permissions;
+    this._connectedDid = options.connectedDid;
+
+    // Store the message that represents the grant.
+    this._message = options.message;
+  }
+
+  /** The author of the underlying revocation message */
+  get author() {
+    return getRecordAuthor(this._message);
+  }
+
+  /** parses the grant revocation given am agent, connectedDid and data encoded records write message  */
+  static async parse({ connectedDid, agent, message }:{
+    connectedDid: string;
+    agent: Web5Agent;
+    message: DwnDataEncodedRecordsWriteMessage;
+  }): Promise<PermissionGrantRevocation> {
+    const permissions = new AgentPermissionsApi({ agent });
+    return new PermissionGrantRevocation(permissions, { connectedDid, message });
+  }
+
+  /** The agent to use for this instantiation of the grant revocation */
+  private get agent(): Web5Agent {
+    return this._permissions.agent;
+  }
+
+  /** The raw `RecordsWrite` DWN message with encoded data that was used to instantiate this grant revocation */
+  get rawMessage(): DwnDataEncodedRecordsWriteMessage {
+    return this._message;
+  }
+
+  /**
+   * Send the current grant revocation to a remote DWN by specifying their DID
+   * If no DID is specified, the target is assumed to be the owner (connectedDID).
+   *
+   * @param target - the optional DID to send the grant revocation to, if none is set it is sent to the connectedDid
+   * @returns the status of the send grant revocation request
+   *
+   * @beta
+   */
+  async send(target?: string): Promise<DwnResponseStatus> {
+    target ??= this._connectedDid;
+
+    const { encodedData, ...rawMessage } = this._message;
+    const dataStream = new Blob([ Convert.base64Url(encodedData).toUint8Array() ]);
+
+    const sendRequestOptions: SendDwnRequest<DwnInterface.RecordsWrite> = {
+      messageType : DwnInterface.RecordsWrite,
+      author      : this._connectedDid,
+      target      : target,
+      dataStream,
+      rawMessage,
+    };
+
+    // Send the current/latest state to the target.
+    const { reply } = await this.agent.sendDwnRequest(sendRequestOptions);
+    return reply;
+  }
+
+  /**
+   * Stores the current grant revocation to the owner's DWN.
+   *
+   * @param importGrant - if true, the grant revocation will signed by the owner before storing it to the owner's DWN. Defaults to false.
+   * @returns the status of the store request
+   *
+   * @beta
+   */
+  async store(importRevocation?: boolean): Promise<DwnResponseStatus> {
+    const { encodedData, ...rawMessage } = this.rawMessage;
+    const dataStream = new Blob([ Convert.base64Url(encodedData).toUint8Array() ]);
+
+    const { reply, message } = await this.agent.processDwnRequest({
+      author      : this._connectedDid,
+      target      : this._connectedDid,
+      messageType : DwnInterface.RecordsWrite,
+      signAsOwner : importRevocation,
+      rawMessage,
+      dataStream,
+    });
+
+    this._message = { ...message, encodedData: encodedData };
+    return { status: reply.status };
+  }
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+/**
+ * Making developing with Web5 components at least 5 times easier to work with.
+ *
+ * Web5 consists of the following components:
+ * - Decentralized Identifiers
+ * - Verifiable Credentials
+ * - DWeb Node personal datastores
+ *
+ * The SDK sets out to gather the most oft used functionality from all three of
+ * these pillar technologies to provide a simple library that is as close to
+ * effortless as possible.
+ *
+ * The SDK is currently still under active development, but having entered the
+ * Tech Preview phase there is now a drive to avoid unnecessary changes unless
+ * backwards compatibility is provided. Additional functionality will be added
+ * in the lead up to 1.0 final, and modifications will be made to address
+ * issues and community feedback.
+ *
+ * [Link to GitHub Repo](https://github.com/TBD54566975/web5-js)
+ *
+ * @packageDocumentation
+ */
+
+export * from './did-api.js';
+export * from './dwn-api.js';
+export * from './grant-revocation.js';
+export * from './permission-grant.js';
+export * from './permission-request.js';
+export * from './protocol.js';
+export * from './record.js';
+export * from './vc-api.js';
+export * from './web5.js';
+
+import * as utils from './utils.js';
+export { utils };

package/src/permission-grant.ts

@@ -0,0 +1,327 @@
+import type {
+  DwnDataEncodedRecordsWriteMessage,
+  DwnPermissionConditions,
+  DwnPermissionScope,
+  DwnResponseStatus,
+  SendDwnRequest,
+  Web5Agent
+} from '@enbox/agent';
+
+import { Convert } from '@enbox/common';
+import {
+  AgentPermissionsApi,
+  DwnInterface,
+  DwnPermissionGrant,
+} from '@enbox/agent';
+import { PermissionGrantRevocation } from './grant-revocation.js';
+
+/**
+ * Represents the structured data model of a PermissionGrant record, encapsulating the essential fields that define
+ */
+export interface PermissionGrantModel {
+  /**
+   * The ID of the permission grant, which is the record ID DWN message.
+   */
+  readonly id: string;
+
+  /**
+   * The grantor of the permission.
+   */
+  readonly grantor: string;
+
+  /**
+   * The grantee of the permission.
+   */
+  readonly grantee: string;
+
+  /**
+   * The date at which the grant was given.
+   */
+  readonly dateGranted: string;
+
+  /**
+   * Optional string that communicates what the grant would be used for
+   */
+  readonly description?: string;
+
+  /**
+   * Optional CID of a permission request. This is optional because grants may be given without being officially requested
+   */
+  readonly requestId?: string;
+
+  /**
+   * Timestamp at which this grant will no longer be active.
+   */
+  readonly dateExpires: string;
+
+  /**
+   * Whether this grant is delegated or not. If `true`, the `grantedTo` will be able to act as the `grantedTo` within the scope of this grant.
+   */
+  readonly delegated?: boolean;
+
+  /**
+   * The scope of the allowed access.
+   */
+  readonly scope: DwnPermissionScope;
+
+  /**
+   * Optional conditions that must be met when the grant is used.
+   */
+  readonly conditions?: DwnPermissionConditions;
+}
+
+/**
+ * Represents the options for creating a new PermissionGrant instance.
+ */
+export interface PermissionGrantOptions {
+  /** The DID to use when interacting with the underlying DWN record representing the grant */
+  connectedDid: string;
+  /** The underlying DWN `RecordsWrite` message along with encoded data that represent the grant */
+  message: DwnDataEncodedRecordsWriteMessage;
+  /** The agent to use when interacting with the underlying DWN record representing the grant */
+  agent: Web5Agent;
+}
+
+/**
+ * The `PermissionGrant` class encapsulates a permissions protocol `grant` record, providing a more
+ * developer-friendly interface for working with Decentralized Web Node (DWN) records.
+ *
+ * Methods are provided to revoke, check if isRevoked, and manage the grant's lifecycle, including writing to remote DWNs.
+ *
+ * @beta
+ */
+export class PermissionGrant implements PermissionGrantModel {
+  /** The PermissionsAPI used to interact with the underlying permission grant */
+  private _permissions: AgentPermissionsApi;
+  /** The DID to use as the author and default target for the underlying permission grant */
+  private _connectedDid: string;
+  /** The underlying DWN `RecordsWrite` message along with encoded data that represent the grant */
+  private _message: DwnDataEncodedRecordsWriteMessage;
+  /** The parsed grant object */
+  private _grant: DwnPermissionGrant;
+
+  private constructor({ api, connectedDid, message, grant }:{
+    api: AgentPermissionsApi;
+    connectedDid: string;
+    message: DwnDataEncodedRecordsWriteMessage;
+    grant: DwnPermissionGrant;
+  }) {
+    this._permissions = api;
+
+    // Store the connected DID for convenience.
+    this._connectedDid = connectedDid;
+
+    // Store the message that represents the grant.
+    this._message = message;
+
+    // Store the parsed grant object.
+    this._grant = grant;
+  }
+
+  /** parses the grant given an agent, connectedDid and data encoded records write message  */
+  static async parse(options: PermissionGrantOptions): Promise<PermissionGrant> {
+    //TODO: this does not have to be async https://github.com/TBD54566975/web5-js/pull/831/files
+    const grant = await DwnPermissionGrant.parse(options.message);
+    const api = new AgentPermissionsApi({ agent: options.agent });
+    return new PermissionGrant({ ...options, grant, api });
+  }
+
+  /** The agent to use for this instantiation of the grant */
+  private get agent(): Web5Agent {
+    return this._permissions.agent;
+  }
+
+  /** The grant's ID, which is also the underlying record's ID */
+  get id(): string {
+    return this._grant.id;
+  }
+
+  /** The DID which granted the permission  */
+  get grantor(): string {
+    return this._grant.grantor;
+  }
+
+  /** The DID which the permission was granted to */
+  get grantee(): string {
+    return this._grant.grantee;
+  }
+
+  /** The date the permission was granted */
+  get dateGranted(): string {
+    return this._grant.dateGranted;
+  }
+
+  /** (optional) Description of the permission grant */
+  get description(): string | undefined {
+    return this._grant.description;
+  }
+
+  /** (optional) The Id of the PermissionRequest if one was used */
+  get requestId(): string | undefined {
+    return this._grant.requestId;
+  }
+
+  /** The date on which the permission expires */
+  get dateExpires(): string {
+    return this._grant.dateExpires;
+  }
+
+  /** Whether or not the permission grant can be used to impersonate the grantor */
+  get delegated(): boolean | undefined {
+    return this._grant.delegated;
+  }
+
+  /** The permission scope under which the grant is valid */
+  get scope(): DwnPermissionScope {
+    return this._grant.scope;
+  }
+
+  /** The conditions under which the grant is valid */
+  get conditions(): DwnPermissionConditions {
+    return this._grant.conditions;
+  }
+
+  /** The raw `RecordsWrite` DWN message with encoded data that was used to instantiate this grant */
+  get rawMessage(): DwnDataEncodedRecordsWriteMessage {
+    return this._message;
+  }
+
+  /**
+   * Send the current grant to a remote DWN by specifying their DID
+   * If no DID is specified, the target is assumed to be the owner (connectedDID).
+   *
+   * @param target - the optional DID to send the grant to, if none is set it is sent to the connectedDid
+   * @returns the status of the send grant request
+   *
+   * @beta
+   */
+  async send(target?: string): Promise<DwnResponseStatus> {
+    target ??= this._connectedDid;
+
+    const { encodedData, ...rawMessage } = this._message;
+    const dataStream = new Blob([ Convert.base64Url(encodedData).toUint8Array() ]);
+
+    const sendRequestOptions: SendDwnRequest<DwnInterface.RecordsWrite> = {
+      messageType : DwnInterface.RecordsWrite,
+      author      : this._connectedDid,
+      target      : target,
+      dataStream,
+      rawMessage,
+    };
+
+    // Send the current/latest state to the target.
+    const { reply } = await this.agent.sendDwnRequest(sendRequestOptions);
+    return reply;
+  }
+
+  /**
+   * Stores the current grant to the owner's DWN.
+   *
+   * @param importGrant - if true, the grant will signed by the owner before storing it to the owner's DWN. Defaults to false.
+   * @returns the status of the store request
+   *
+   * @beta
+   */
+  async store(importGrant: boolean = false): Promise<DwnResponseStatus> {
+    const { encodedData, ...rawMessage } = this.rawMessage;
+    const dataStream = new Blob([ Convert.base64Url(encodedData).toUint8Array() ]);
+
+    const { reply, message } = await this.agent.processDwnRequest({
+      store       : true,
+      author      : this._connectedDid,
+      target      : this._connectedDid,
+      messageType : DwnInterface.RecordsWrite,
+      signAsOwner : importGrant,
+      rawMessage,
+      dataStream,
+    });
+
+    this._message = { ...message, encodedData: encodedData };
+    return { status: reply.status };
+  }
+
+  /**
+   * Signs the current grant as the owner and optionally stores it to the owner's DWN.
+   * This is useful when importing a grant that was signed by someone else into your own DWN.
+   *
+   * @param store - if true, the grant will be stored to the owner's DWN after signing. Defaults to true.
+   * @returns the status of the import request
+   *
+   * @beta
+   */
+  async import(store: boolean = false): Promise<DwnResponseStatus> {
+    const { encodedData, ...rawMessage } = this.rawMessage;
+    const dataStream = new Blob([ Convert.base64Url(encodedData).toUint8Array() ]);
+
+    const { reply, message } = await this.agent.processDwnRequest({
+      store,
+      author      : this._connectedDid,
+      target      : this._connectedDid,
+      messageType : DwnInterface.RecordsWrite,
+      signAsOwner : true,
+      rawMessage,
+      dataStream,
+    });
+
+    this._message = { ...message, encodedData: encodedData };
+    return { status: reply.status };
+  }
+
+  /**
+   * Revokes the grant and optionally stores the revocation to the owner's DWN.
+   *
+   * @param store - if true, the revocation will be stored to the owner's DWN. Defaults to true.
+   * @returns {PermissionGrantRevocation} the grant revocation object
+   *
+   * @beta
+   */
+  async revoke(store: boolean = true): Promise<PermissionGrantRevocation> {
+    const revocation = await this._permissions.createRevocation({
+      store,
+      author : this._connectedDid,
+      grant  : this._grant,
+    });
+
+    return PermissionGrantRevocation.parse({
+      connectedDid : this._connectedDid,
+      agent        : this.agent,
+      message      : revocation.message,
+    });
+  }
+
+  /**
+   * Checks if the grant has been revoked.
+   *
+   * @param remote - if true, the check will be made against the remote DWN. Defaults to false.
+   * @returns true if the grant has been revoked, false otherwise.
+   * @throws if there is an error checking the revocation status.
+   *
+   * @beta
+   */
+  isRevoked(remote: boolean = false): Promise<boolean> {
+    return this._permissions.isGrantRevoked({
+      author        : this._connectedDid,
+      target        : this.grantor,
+      grantRecordId : this.id,
+      remote
+    });
+  }
+
+  /**
+   * @returns the JSON representation of the grant
+   */
+  toJSON(): DwnPermissionGrant {
+    return {
+      id          : this.id,
+      grantor     : this.grantor,
+      grantee     : this.grantee,
+      dateGranted : this.dateGranted,
+      description : this.description,
+      requestId   : this.requestId,
+      dateExpires : this.dateExpires,
+      delegated   : this.delegated,
+      scope       : this.scope,
+      conditions  : this.conditions
+    };
+  }
+}

package/src/permission-request.ts

@@ -0,0 +1,214 @@
+import { AgentPermissionsApi, DwnDataEncodedRecordsWriteMessage, DwnPermissionConditions, DwnPermissionRequest, DwnPermissionScope, DwnResponseStatus, SendDwnRequest, Web5Agent } from '@enbox/agent';
+import { DwnInterface } from '@enbox/agent';
+import { Convert } from '@enbox/common';
+import { PermissionGrant } from './permission-grant.js';
+
+/**
+ * Represents the structured data model of a PermissionsRequest record, encapsulating the essential fields that define
+ * the request's data and payload within a Decentralized Web Node (DWN).
+ */
+export interface PermissionRequestModel {
+  /**
+   * The ID of the permission request, which is the record ID DWN message.
+   */
+  readonly id: string;
+
+  /**
+   * The requester for of the permission.
+   */
+  readonly requester: string;
+
+  /**
+   * Optional string that communicates what the requested grant would be used for.
+   */
+  readonly description?: string;
+
+  /**
+   * Whether the requested grant is delegated or not.
+   * If `true`, the `requestor` will be able to act as the grantor of the permission within the scope of the requested grant.
+   */
+  readonly delegated?: boolean;
+
+  /**
+   * The scope of the allowed access.
+   */
+  readonly scope: DwnPermissionScope;
+
+  /**
+   * Optional conditions that must be met when the requested grant is used.
+   */
+  readonly conditions?: DwnPermissionConditions;
+}
+
+/**
+ * The `PermissionRequest` class encapsulates a permissions protocol `request` record, providing a more
+ * developer-friendly interface for working with Decentralized Web Node (DWN) records.
+ *
+ * Methods are provided to grant the request and manage the request's lifecycle, including writing to remote DWNs.
+ *
+ * @beta
+ */
+export class PermissionRequest implements PermissionRequestModel {
+  /** The PermissionsAPI used to interact with the underlying permission request */
+  private _permissions: AgentPermissionsApi;
+  /** The DID to use as the author and default target for the underlying permission request */
+  private _connectedDid: string;
+  /** The underlying DWN `RecordsWrite` message along with encoded data that represent the request */
+  private _message: DwnDataEncodedRecordsWriteMessage;
+  /** The parsed permission request object */
+  private _request: DwnPermissionRequest;
+
+  private constructor({ api, connectedDid, message, request }: {
+    api: AgentPermissionsApi;
+    connectedDid: string;
+    message: DwnDataEncodedRecordsWriteMessage;
+    request: DwnPermissionRequest;
+  }) {
+    this._permissions = api;
+    this._connectedDid = connectedDid;
+
+    // Store the parsed request object.
+    this._request = request;
+
+    // Store the message that represents the grant.
+    this._message = message;
+  }
+
+  /** parses the request given an agent, connectedDid and data encoded records write message  */
+  static async parse({ connectedDid, agent, message }:{
+    connectedDid: string;
+    agent: Web5Agent;
+    message: DwnDataEncodedRecordsWriteMessage;
+  }): Promise<PermissionRequest> {
+    //TODO: this does not have to be async https://github.com/TBD54566975/web5-js/pull/831/files
+    const request = await DwnPermissionRequest.parse(message);
+    const api = new AgentPermissionsApi({ agent });
+    return new PermissionRequest({ api, connectedDid, message, request });
+  }
+
+  /** The agent to use for this instantiation of the request */
+  private get agent(): Web5Agent {
+    return this._permissions.agent;
+  }
+
+  /** The request's ID, which is also the underlying record's ID  */
+  get id() {
+    return this._request.id;
+  }
+
+  /** The DID that is requesting a permission */
+  get requester() {
+    return this._request.requester;
+  }
+
+  /** (optional) Description of the permission request */
+  get description() {
+    return this._request.description;
+  }
+
+  /** Whether or not the permission request can be used to impersonate the grantor */
+  get delegated() {
+    return this._request.delegated;
+  }
+
+  /** The permission scope under which the requested grant would be valid */
+  get scope() {
+    return this._request.scope;
+  }
+
+  /** The conditions under which the requested grant would be valid */
+  get conditions() {
+    return this._request.conditions;
+  }
+
+  /** The `RecordsWrite` DWN message with encoded data that was used to instantiate this request */
+  get rawMessage(): DwnDataEncodedRecordsWriteMessage {
+    return this._message;
+  }
+
+  /**
+   * Send the current permission request to a remote DWN by specifying their DID
+   * If no DID is specified, the target is assumed to be the owner (connectedDID).
+   *
+   * @param target - the optional DID to send the permission request to, if none is set it is sent to the connectedDid
+   * @returns the status of the send permission request
+   *
+   * @beta
+   */
+  async send(target?: string): Promise<DwnResponseStatus> {
+    target ??= this._connectedDid;
+
+    const { encodedData, ...rawMessage } = this._message;
+    const dataStream = new Blob([ Convert.base64Url(encodedData).toUint8Array() ]);
+
+    const sendRequestOptions: SendDwnRequest<DwnInterface.RecordsWrite> = {
+      messageType : DwnInterface.RecordsWrite,
+      author      : this._connectedDid,
+      target      : target,
+      dataStream,
+      rawMessage,
+    };
+
+    // Send the current/latest state to the target.
+    const { reply } = await this.agent.sendDwnRequest(sendRequestOptions);
+    return reply;
+  }
+
+  /**
+   * Stores the current permission request to the owner's DWN.
+   *
+   * @param importGrant - if true, the permission request will signed by the owner before storing it to the owner's DWN. Defaults to false.
+   * @returns the status of the store request
+   *
+   * @beta
+   */
+  async store(): Promise<DwnResponseStatus> {
+    const { encodedData, ...rawMessage } = this.rawMessage;
+    const dataStream = new Blob([ Convert.base64Url(encodedData).toUint8Array() ]);
+
+    const { reply, message } = await this.agent.processDwnRequest({
+      author      : this._connectedDid,
+      target      : this._connectedDid,
+      messageType : DwnInterface.RecordsWrite,
+      rawMessage,
+      dataStream,
+    });
+
+    this._message = { ...message, encodedData: encodedData };
+    return { status: reply.status };
+  }
+
+  /**
+   * Grants the permission request to the requester.
+   *
+   * @param dateExpires - the date when the permission grant will expire.
+   * @param store - if true, the permission grant will be stored in the owner's DWN. Defaults to true.
+   * @returns {PermissionGrant} the granted permission.
+   *
+   * @beta
+   */
+  async grant(dateExpires: string, store: boolean = true): Promise<PermissionGrant> {
+    const { message } = await this._permissions.createGrant({
+      requestId : this.id,
+      grantedTo : this.requester,
+      scope     : this.scope,
+      delegated : this.delegated,
+      author    : this._connectedDid,
+      store,
+      dateExpires,
+    });
+
+    return PermissionGrant.parse({
+      connectedDid : this._connectedDid,
+      agent        : this.agent,
+      message
+    });
+  }
+
+  /**
+   * @returns the JSON representation of the permission request
+   */
+  toJSON(): PermissionRequestModel {
+    return this._request;
+  }
+}