@enbox/dwn-sdk-js 0.3.7 → 0.3.8

package/src/types/messages-types.ts

@@ -24,7 +24,7 @@ export type MessagesReadDescriptor = {
   method: DwnMethodName.Read;
   messageCid: string;
   messageTimestamp: string;
-  permissionGrantId?: string;
+  permissionGrantIds?: string[];
 };
 
 export type MessagesReadMessage = GenericMessage & {
@@ -50,8 +50,14 @@ export type MessagesSyncDescriptor = {
   messageTimestamp : string;
   action : MessagesSyncAction;
   protocol? : string; // optional protocol scope
+  projectionRootVersion?: string;
+  projectionScopes?: {
+    protocol: string;
+    protocolPath?: string;
+    contextId?: string;
+  }[];
   prefix? : string; // bit path for subtree/leaves (e.g. "0110101...")
-  permissionGrantId? : string;
+  permissionGrantIds? : string[];
   /**
    * For `action: 'diff'`: a map of `{ bitPrefix: hexHash }` representing the client's
    * subtree hashes at `depth`. The server compares each hash against its own tree
@@ -85,6 +91,18 @@ export type MessagesSyncDiffEntry = {
   encodedData? : string;
 };
 
+export type MessagesSyncDependencyClass = 'protocolsConfigure' | 'recordsInitialWrite';
+
+/**
+ * Advisory dependency hint returned with projected diff responses. Dependency
+ * entries are not part of the projected root; clients must rederive that the
+ * dependency is required by the referenced primary before applying it.
+ */
+export type MessagesSyncDependencyEntry = MessagesSyncDiffEntry & {
+  dependencyClass: MessagesSyncDependencyClass;
+  rootMessageCid: string;
+};
+
 export type MessagesSyncReply = GenericMessageReply & {
   root? : string; // hex-encoded root hash (for 'root' action)
   hash? : string; // hex-encoded subtree hash (for 'subtree' action)
@@ -93,6 +111,8 @@ export type MessagesSyncReply = GenericMessageReply & {
   onlyRemote? : MessagesSyncDiffEntry[];
   /** For 'diff' action: bit prefixes where the client has entries the server doesn't. */
   onlyLocal? : string[];
+  /** Advisory dependency messages needed to apply projected `onlyRemote` primary entries. */
+  dependencies? : MessagesSyncDependencyEntry[];
 };
 
 export type MessagesSubscribeMessageOptions = {
@@ -115,7 +135,7 @@ export type MessagesSubscribeDescriptor = {
   method: DwnMethodName.Subscribe;
   messageTimestamp: string;
   filters: MessagesFilter[];
-  permissionGrantId?: string;
+  permissionGrantIds?: string[];
   /**
    * Progress token to resume from. When provided, the handler replays events
    * from the EventLog starting after this position instead of returning no

package/src/types/permission-types.ts

@@ -96,6 +96,10 @@ export type MessagesPermissionScope = {
   interface: DwnInterfaceName.Messages;
   method: DwnMethodName.Read;
   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;
 };
 
 /**
@@ -123,4 +127,4 @@ export type PermissionConditions = {
    * If `undefined`, it is optional to make the message public.
    */
   publication?: PermissionConditionPublication;
-};
+};

package/src/types/records-types.ts

@@ -105,6 +105,7 @@ export type RecordsCountDescriptor = {
   method: DwnMethodName.Count;
   messageTimestamp: string;
   filter: RecordsFilter;
+  permissionGrantId?: string;
 };
 
 export type RecordsCountMessage = GenericMessage & {
@@ -120,6 +121,7 @@ export type RecordsQueryDescriptor = {
   method: DwnMethodName.Query;
   messageTimestamp: string;
   filter: RecordsFilter;
+  permissionGrantId?: string;
   dateSort?: DateSort;
   pagination?: Pagination;
 };
@@ -129,6 +131,7 @@ export type RecordsSubscribeDescriptor = {
   method: DwnMethodName.Subscribe;
   messageTimestamp: string;
   filter: RecordsFilter;
+  permissionGrantId?: string;
   dateSort?: DateSort;
   pagination?: Pagination;
   /**
@@ -267,9 +270,10 @@ export type RecordsDeleteDescriptor = {
   method: DwnMethodName.Delete;
   messageTimestamp: string;
   recordId: string;
+  permissionGrantId?: string;
 
   /**
    * Denotes if all the descendent records should be purged.
    */
   prune: boolean
-};
+};

package/src/types/subscriptions.ts

@@ -110,15 +110,31 @@ export type SubscriptionEose = {
   cursor : ProgressToken;
 };
 
+/**
+ * Subscription-level error emitted after a subscription is already open.
+ *
+ * This is used for conditions that invalidate future delivery, such as a
+ * delegated subscription grant being revoked after the subscription was
+ * authorized. The cursor identifies the event that caused delivery to stop.
+ */
+export type SubscriptionError = {
+  type : 'error';
+  cursor : ProgressToken;
+  error : {
+    code : string;
+    detail : string;
+  };
+};
+
 /**
  * Discriminated union of subscription event types delivered to
  * {@link SubscriptionListener} callbacks.
  */
-export type SubscriptionMessage = SubscriptionEvent | SubscriptionEose;
+export type SubscriptionMessage = SubscriptionEvent | SubscriptionEose | SubscriptionError;
 
 /**
- * Callback for {@link EventLog.subscribe}. Receives either a regular event
- * (with cursor) or an EOSE marker indicating catch-up replay is complete.
+ * Callback for {@link EventLog.subscribe}. Receives events, catch-up EOSE
+ * markers, or subscription-level errors that stop delivery.
  */
 export type SubscriptionListener = (message: SubscriptionMessage) => void;
 

package/src/utils/permission-scope.ts

@@ -0,0 +1,55 @@
+/**
+ * Minimal protocol-bound scope shape used by permission grant authorization.
+ *
+ * Permission grants and candidate records/filters are projected down to these
+ * fields before matching so grant selection and server enforcement use the
+ * same rules.
+ */
+export type ProtocolScope = {
+  protocol?: string;
+  protocolPath?: string;
+  contextId?: string;
+};
+
+/**
+ * Shared matching rules for protocol-scoped permission grants.
+ *
+ * Matching fails closed for invalid combinations: `protocolPath` and
+ * `contextId` are mutually exclusive, and either field requires `protocol`.
+ * `protocol` and `protocolPath` match by exact equality. `contextId` scopes
+ * match a context subtree: the target context must equal the scoped context or
+ * begin with the scoped context followed by `/`.
+ */
+export class PermissionScopeMatcher {
+  /**
+   * Determines whether a candidate target is within a grant scope.
+   */
+  public static matches(scope: ProtocolScope, target: ProtocolScope): boolean {
+    if (scope.protocolPath !== undefined && scope.contextId !== undefined) {
+      return false;
+    }
+
+    if ((scope.protocolPath !== undefined || scope.contextId !== undefined) && scope.protocol === undefined) {
+      return false;
+    }
+
+    if (scope.protocol !== undefined && scope.protocol !== target.protocol) {
+      return false;
+    }
+
+    if (scope.protocolPath !== undefined) {
+      return scope.protocolPath === target.protocolPath;
+    }
+
+    if (scope.contextId !== undefined) {
+      return PermissionScopeMatcher.matchesContextId(scope.contextId, target.contextId);
+    }
+
+    return true;
+  }
+
+  private static matchesContextId(scopeContextId: string, candidateContextId: unknown): boolean {
+    return typeof candidateContextId === 'string' &&
+      (candidateContextId === scopeContextId || candidateContextId.startsWith(scopeContextId + '/'));
+  }
+}