@enbox/dwn-sdk-js 0.0.1

package/src/types/message-types.ts

@@ -0,0 +1,132 @@
+import type { GeneralJws } from './jws-types.js';
+import type { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+import type { PaginationCursor, SortDirection } from './query-types.js';
+
+/**
+ * Intersection type for all concrete message types.
+ */
+export type GenericMessage = {
+  descriptor: Descriptor;
+  authorization?: AuthorizationModel;
+};
+
+/**
+ * The data model for the `authorization` property in a DWN message.
+ */
+export type AuthorizationModel = {
+  /**
+   * The signature of the message signer.
+   * NOTE: the signer is not necessarily the logical author of the message (e.g. signer is a delegate).
+   */
+  signature: GeneralJws;
+
+  /**
+   * The delegated grant required when the message is signed by an author-delegate.
+   */
+  authorDelegatedGrant?: DelegatedGrantRecordsWriteMessage;
+
+  /**
+   * An "overriding" signature for a DWN owner or owner-delegate to store a message authored by another entity.
+   */
+  ownerSignature?: GeneralJws;
+
+  /**
+   * The delegated grant required when the message is signed by an owner-delegate.
+   */
+  ownerDelegatedGrant?: DelegatedGrantRecordsWriteMessage;
+};
+
+export type DelegatedGrantRecordsWriteMessage = {
+  authorization: {
+    /**
+     * The signature of the author.
+     */
+    signature: GeneralJws;
+  },
+  recordId: string,
+  contextId?: string;
+  // NOTE: This is a direct expansion and copy of `DataEncodedRecordsWriteMessage` to avoid circular references.
+  descriptor: {
+    interface: DwnInterfaceName.Records;
+    method: DwnMethodName.Write;
+    protocol?: string;
+    protocolPath?: string;
+    recipient?: string;
+    schema?: string;
+    parentId?: string;
+    dataCid: string;
+    dataSize: number;
+    dateCreated: string;
+    messageTimestamp: string;
+    published?: boolean;
+    datePublished?: string;
+    dataFormat: string;
+  };
+  encodedData: string;
+};
+
+/**
+ * Type of common decoded `authorization` property payload.
+ */
+export type GenericSignaturePayload = {
+  descriptorCid: string;
+  permissionGrantId?: string;
+
+  /**
+   * Record ID of a permission grant DWN `RecordsWrite` with `delegated` set to `true`.
+   */
+  delegatedGrantId?: string;
+
+  /**
+   * Used in the Records interface to authorize role-authorized actions for protocol records.
+   */
+  protocolRole?: string;
+};
+
+/**
+ * Intersection type for all DWN message descriptor.
+ */
+export type Descriptor = {
+  interface: string;
+  method: string;
+  messageTimestamp: string;
+};
+
+/**
+ * Message returned in a query result.
+ * NOTE: the message structure is a modified version of the message received, the most notable differences are:
+ * 1. May include encoded data
+ */
+export type QueryResultEntry = GenericMessage & {
+  encodedData?: string;
+};
+
+export interface MessageSubscription {
+  id: string;
+  close: () => Promise<void>;
+};
+
+/**
+ * Pagination Options for querying messages.
+ *
+ * The cursor is the messageCid of the message you would like to pagination from.
+ */
+export type Pagination = {
+  cursor?: PaginationCursor;
+  limit?: number;
+};
+
+export type Status = {
+  code: number
+  detail: string
+};
+
+export type GenericMessageReply = {
+  status: Status;
+};
+
+export type MessageSort = {
+  dateCreated?: SortDirection;
+  datePublished?: SortDirection;
+  messageTimestamp?: SortDirection;
+};

package/src/types/messages-types.ts

@@ -0,0 +1,77 @@
+import type { MessageEvent } from './subscriptions.js';
+import type { Readable } from 'readable-stream';
+import type { AuthorizationModel, GenericMessage, GenericMessageReply, MessageSubscription } from './message-types.js';
+import type { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+import type { PaginationCursor, RangeCriterion } from './query-types.js';
+
+/**
+ * filters used when filtering for any type of Message across interfaces
+ */
+export type MessagesFilter = {
+  interface?: string;
+  method?: string;
+  protocol?: string;
+  messageTimestamp?: RangeCriterion;
+};
+
+export type MessagesReadDescriptor = {
+  interface : DwnInterfaceName.Messages;
+  method: DwnMethodName.Read;
+  messageCid: string;
+  messageTimestamp: string;
+};
+
+export type MessagesReadMessage = GenericMessage & {
+  authorization: AuthorizationModel; // overriding `GenericMessage` with `authorization` being required
+  descriptor: MessagesReadDescriptor;
+};
+
+export type MessagesReadReplyEntry = {
+  messageCid: string;
+  message: GenericMessage;
+  data?: Readable;
+};
+
+export type MessagesReadReply = GenericMessageReply & {
+  entry?: MessagesReadReplyEntry;
+};
+
+export type MessagesQueryDescriptor = {
+  interface: DwnInterfaceName.Messages;
+  method: DwnMethodName.Query;
+  messageTimestamp: string;
+  filters: MessagesFilter[];
+  cursor?: PaginationCursor;
+};
+
+export type MessagesQueryMessage = GenericMessage & {
+  authorization: AuthorizationModel;
+  descriptor: MessagesQueryDescriptor;
+};
+
+export type MessagesQueryReply = GenericMessageReply & {
+  entries?: string[];
+  cursor?: PaginationCursor;
+};
+
+export type MessageSubscriptionHandler = (event: MessageEvent) => void;
+
+export type MessagesSubscribeMessageOptions = {
+  subscriptionHandler: MessageSubscriptionHandler;
+};
+
+export type MessagesSubscribeMessage = {
+  authorization: AuthorizationModel;
+  descriptor: MessagesSubscribeDescriptor;
+};
+
+export type MessagesSubscribeReply = GenericMessageReply & {
+  subscription?: MessageSubscription;
+};
+
+export type MessagesSubscribeDescriptor = {
+  interface: DwnInterfaceName.Messages;
+  method: DwnMethodName.Subscribe;
+  messageTimestamp: string;
+  filters: MessagesFilter[];
+};

package/src/types/method-handler.ts

@@ -0,0 +1,19 @@
+import type { MessageSubscriptionHandler } from './messages-types.js';
+import type { Readable } from 'readable-stream';
+import type { RecordSubscriptionHandler } from './records-types.js';
+import type { GenericMessage, GenericMessageReply } from './message-types.js';
+
+/**
+ * Interface that defines a message handler of a specific method.
+ */
+export interface MethodHandler {
+  /**
+   * Handles the given message and returns a `MessageReply` response.
+   */
+  handle(input: {
+    tenant: string;
+    message: GenericMessage;
+    dataStream?: Readable
+    subscriptionHandler?: MessageSubscriptionHandler | RecordSubscriptionHandler;
+  }): Promise<GenericMessageReply>;
+}

package/src/types/permission-types.ts

@@ -0,0 +1,110 @@
+import type { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+
+/**
+ * Type for the data payload of a permission request message.
+ */
+export type PermissionRequestData = {
+
+  /**
+   * If the grant is a delegated grant or not. If `true`, the `grantedTo` will be able to act as the `grantedBy` within the scope of this grant.
+   */
+  delegated: boolean;
+
+  /**
+   * Optional string that communicates what the grant would be used for.
+   */
+  description?: string;
+
+  /**
+   * The scope of the allowed access.
+   */
+  scope: PermissionScope;
+
+  conditions?: PermissionConditions
+};
+
+/**
+ * Type for the data payload of a permission grant message.
+ */
+export type PermissionGrantData = {
+  /**
+   * Optional string that communicates what the grant would be used for
+   */
+  description?: string;
+
+  /**
+   * Optional CID of a permission request. This is optional because grants may be given without being officially requested
+   * */
+  requestId?: string;
+
+  /**
+   * Timestamp at which this grant will no longer be active.
+   */
+  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.
+   */
+  delegated?: boolean;
+
+  /**
+   * The scope of the allowed access.
+   */
+  scope: PermissionScope;
+
+  conditions?: PermissionConditions
+};
+
+/**
+ * Type for the data payload of a permission revocation message.
+ */
+export type PermissionRevocationData = {
+  /**
+   * Optional string that communicates the details of the revocation.
+   */
+  description?: string;
+};
+
+/**
+ * The data model for a permission scope.
+ */
+export type PermissionScope = ProtocolPermissionScope | MessagesPermissionScope | RecordsPermissionScope;
+
+export type ProtocolPermissionScope = {
+  interface: DwnInterfaceName.Protocols;
+  method: DwnMethodName.Configure | DwnMethodName.Query;
+  protocol?: string;
+};
+
+export type MessagesPermissionScope = {
+  interface: DwnInterfaceName.Messages;
+  method: DwnMethodName.Query | DwnMethodName.Read | DwnMethodName.Subscribe;
+  protocol?: string;
+};
+
+/**
+ * The data model for a permission scope that is specific to the Records interface.
+ */
+export type RecordsPermissionScope = {
+  interface: DwnInterfaceName.Records;
+  method: DwnMethodName.Read | DwnMethodName.Write | DwnMethodName.Query | DwnMethodName.Subscribe | DwnMethodName.Delete;
+  protocol: string;
+  /** May only be present when `protocol` is defined and `protocolPath` is undefined */
+  contextId?: string;
+  /** May only be present when `protocol` is defined and `contextId` is undefined */
+  protocolPath?: string;
+};
+
+export enum PermissionConditionPublication {
+  Required = 'Required',
+  Prohibited = 'Prohibited',
+}
+
+export type PermissionConditions = {
+  /**
+   * indicates whether a message written with the invocation of a permission must, may, or must not
+   * be marked as public.
+   * If `undefined`, it is optional to make the message public.
+   */
+  publication?: PermissionConditionPublication;
+};

package/src/types/protocols-types.ts

@@ -0,0 +1,177 @@
+import type { PublicJwk } from './jose-types.js';
+import type { AuthorizationModel, GenericMessage, GenericMessageReply } from './message-types.js';
+import type { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+
+export type ProtocolsConfigureDescriptor = {
+  interface : DwnInterfaceName.Protocols;
+  method: DwnMethodName.Configure;
+  messageTimestamp: string;
+  definition: ProtocolDefinition;
+};
+
+export type ProtocolDefinition = {
+  protocol: string;
+  /**
+   * Denotes if this Protocol Definition can be returned by unauthenticated or unauthorized `ProtocolsQuery`.
+   */
+  published: boolean;
+  types: ProtocolTypes;
+  structure: {
+    [key: string]: ProtocolRuleSet;
+  }
+};
+
+export type ProtocolType = {
+  schema?: string,
+  dataFormats?: string[],
+};
+
+export type ProtocolTypes = {
+  [key: string]: ProtocolType;
+};
+
+export enum ProtocolActor {
+  Anyone = 'anyone',
+  Author = 'author',
+  Recipient = 'recipient'
+}
+
+export enum ProtocolAction {
+  CoDelete = 'co-delete',
+  CoPrune = 'co-prune',
+  CoUpdate = 'co-update',
+  Create = 'create',
+  Delete = 'delete',
+  Prune = 'prune',
+  Query = 'query',
+  Read = 'read',
+  Subscribe = 'subscribe',
+  Update = 'update'
+}
+
+/**
+ * Rules defining which actors may access a record at the given protocol path.
+ * Rules take three forms, e.g.:
+ * 1. Anyone can create.
+ *   {
+ *     who: 'anyone',
+ *     can: ['create']
+ *   }
+ *
+ * 2. Author of protocolPath can create; OR
+ *    Recipient of protocolPath can write.
+ *   {
+ *     who: 'recipient'
+ *     of: 'requestForQuote',
+ *     can: ['create']
+ *   }
+ *
+ * 3. Role can create.
+ *   {
+ *     role: 'friend',
+ *     can: ['create']
+ *   }
+ */
+export type ProtocolActionRule = {
+  /**
+   * May be 'anyone' | 'author' | 'recipient'.
+   * If `who` === 'anyone', then `of` must be omitted. Otherwise `of` must be present.
+   * Mutually exclusive with `role`
+   */
+  who?: string,
+
+  /**
+   * The protocol path of a role record type marked with $role: true.
+   * Mutually exclusive with `who`
+   */
+  role?: string;
+
+  /**
+   * Protocol path.
+   * Must be present if `who` === 'author' or 'recipient'
+   */
+  of?: string;
+
+  /**
+   * Array of actions that the actor/role can perform.
+   * See {ProtocolAction} for possible values.
+   * 'query' and 'subscribe' are only supported for `role` rules.
+   */
+  can: string[];
+};
+/**
+ * Config for protocol-path encryption scheme.
+ */
+export type ProtocolPathEncryption = {
+
+  /**
+   * The ID of the root key that derives the public key at this protocol path for encrypting the symmetric key used for data encryption.
+   */
+  rootKeyId: string;
+
+  /**
+   * Public key for encrypting the symmetric key used for data encryption.
+   */
+  publicKeyJwk: PublicJwk;
+};
+
+export type ProtocolRuleSet = {
+  /**
+   * Encryption setting for objects that are in this protocol path.
+   */
+  $encryption?: ProtocolPathEncryption;
+  $actions?: ProtocolActionRule[];
+
+  /**
+   * If true, this marks a record as a `role` that may used within a context.
+   * The recipient of a $role record may invoke their role by setting `protocolRole` property to the protocol path of the $role record.
+   */
+  $role?: boolean;
+
+  /**
+   * If $size is set, the record size in bytes must be within the limits.
+   */
+  $size?: {
+    min?: number,
+    max?: number
+  }
+
+  /**
+   * If $tags is set, the record must conform to the tag rules.
+   */
+  $tags?: {
+    /** array of required tags */
+    $requiredTags?: string[],
+    /** allow properties other than those explicitly listed. defaults to false  */
+    $allowUndefinedTags?: boolean;
+
+    [key: string]: any;
+  }
+
+  // JSON Schema verifies that properties other than properties prefixed with $ will actually have type ProtocolRuleSet
+  [key: string]: any;
+};
+
+export type ProtocolsConfigureMessage = GenericMessage & {
+  authorization: AuthorizationModel; // overriding `GenericMessage` with `authorization` being required
+  descriptor: ProtocolsConfigureDescriptor;
+};
+
+export type ProtocolsQueryFilter = {
+  protocol: string,
+};
+
+export type ProtocolsQueryDescriptor = {
+  interface : DwnInterfaceName.Protocols,
+  method: DwnMethodName.Query;
+  messageTimestamp: string;
+  filter?: ProtocolsQueryFilter
+};
+
+export type ProtocolsQueryMessage = GenericMessage & {
+  descriptor: ProtocolsQueryDescriptor;
+};
+
+export type ProtocolsQueryReply = GenericMessageReply & {
+  entries?: ProtocolsConfigureMessage[];
+};

package/src/types/query-types.ts

@@ -0,0 +1,61 @@
+export type QueryOptions = {
+  sortProperty: string;
+  sortDirection?: SortDirection;
+  limit?: number;
+  cursor?: PaginationCursor;
+};
+
+export enum SortDirection {
+  Descending = -1,
+  Ascending = 1
+}
+
+export type KeyValues = { [key:string]: string | number | boolean | string[] | number[] };
+
+export type EqualFilter = string | number | boolean;
+
+export type OneOfFilter = EqualFilter[];
+
+export type RangeValue = string | number;
+
+/**
+ * "greater than" or "greater than or equal to" range condition. `gt` and `gte` are mutually exclusive.
+ */
+export type GT = ({ gt: RangeValue } & { gte?: never }) | ({ gt?: never } & { gte: RangeValue });
+
+/**
+ * "less than" or "less than or equal to" range condition. `lt`, `lte` are mutually exclusive.
+ */
+export type LT = ({ lt: RangeValue } & { lte?: never }) | ({ lt?: never } & { lte: RangeValue });
+
+/**
+ * Ranger filter. 1 condition is required.
+ */
+export type RangeFilter = (GT | LT) & Partial<GT> & Partial<LT>;
+
+export type StartsWithFilter = {
+  startsWith: string;
+};
+
+export type FilterValue = EqualFilter | OneOfFilter | RangeFilter;
+
+export type Filter = {
+  [property: string]: FilterValue;
+};
+
+export type RangeCriterion = {
+  /**
+   * Inclusive starting date-time.
+   */
+  from?: string;
+
+  /**
+   * Inclusive end date-time.
+   */
+  to?: string;
+};
+
+export type PaginationCursor = {
+  messageCid: string;
+  value: string | number;
+};