@enbox/dwn-sdk-js 0.4.2 → 0.4.4

package/dist/types/src/types/permission-types.d.ts

@@ -1,4 +1,46 @@
 import type { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+/**
+ * Metadata describing the connect approval session that created a permission grant.
+ *
+ * Wallets use this to group grants into user-facing app sessions and to
+ * distinguish active sessions from expired permission bundles. App and client
+ * fields are self-reported by the requester, unauthenticated, and intended for
+ * display only. Consumers must not treat them as verified app identity.
+ */
+export type ConnectSessionMetadata = {
+    /** Stable session ID shared by all grants created by one connect approval. */
+    id: string;
+    /** Human-readable app name shown during approval. Self-reported display data. */
+    appName?: string;
+    /** App icon URL shown during approval. Self-reported display data. */
+    appIcon?: string;
+    /** Origin of the requesting app, when known. Self-reported display data. */
+    origin?: string;
+    /** User agent string captured by the connect client, when available. Display data only. */
+    userAgent?: string;
+    /** Platform/device hint captured by the connect client, when available. */
+    platform?: string;
+    /** Primary browser language captured by the connect client, when available. */
+    language?: string;
+    /** Browser language preferences captured by the connect client, when available. */
+    languages?: string[];
+    /** IANA timezone captured by the connect client, when available. */
+    timezone?: string;
+    /** Connect transport that created the session. */
+    transport?: ConnectSessionTransport;
+    /** Timestamp when the wallet approved the connect session. */
+    createdAt: string;
+    /**
+     * Display timestamp for when the connect session expires.
+     *
+     * The enforcing value is the enclosing permission grant's `dateExpires`.
+     * Consumers must use `dateExpires`, not this metadata field, for any
+     * authorization or security decision.
+     */
+    expiresAt: string;
+};
+/** Connect transport that created a connect session. */
+export type ConnectSessionTransport = 'relay' | 'postMessage';
 /**
  * Type for the data payload of a permission request message.
  */
@@ -51,6 +93,8 @@ export type PermissionGrantData = {
         rootKeyId: string;
         publicKeyJwk: Record<string, any>;
     };
+    /** Optional metadata for the connect session that created this grant. */
+    connectSession?: ConnectSessionMetadata;
 };
 /**
  * Type for the data payload of a permission revocation message.
@@ -87,10 +131,13 @@ export type MessagesPermissionScope = {
 };
 /**
  * The data model for a permission scope that is specific to the Records interface.
+ *
+ * `Read` is the only valid read-like Records permission scope and authorizes
+ * `RecordsRead`, `RecordsQuery`, `RecordsSubscribe`, and `RecordsCount` operations.
  */
 export type RecordsPermissionScope = {
     interface: DwnInterfaceName.Records;
-    method: DwnMethodName.Count | DwnMethodName.Read | DwnMethodName.Write | DwnMethodName.Query | DwnMethodName.Subscribe | DwnMethodName.Delete;
+    method: DwnMethodName.Read | DwnMethodName.Write | DwnMethodName.Delete;
     protocol: string;
     /** May only be present when `protocol` is defined and `protocolPath` is undefined */
     contextId?: string;

package/dist/types/src/types/permission-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"permission-types.d.ts","sourceRoot":"","sources":["../../../../src/types/permission-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAExF;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAElC;;OAEG;IACH,SAAS,EAAE,OAAO,CAAC;IAEnB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,KAAK,EAAE,eAAe,CAAC;IAEvB,UAAU,CAAC,EAAE,oBAAoB,CAAA;CAClC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;SAEK;IACL,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;OAEG;IACH,KAAK,EAAE,eAAe,CAAC;IAEvB,UAAU,CAAC,EAAE,oBAAoB,CAAC;IAElC;;;;OAIG;IACH,mBAAmB,CAAC,EAAE;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;KACnC,CAAC;CACH,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,uBAAuB,GAAG,uBAAuB,GAAG,sBAAsB,CAAC;AAEzG,MAAM,MAAM,uBAAuB,GAAG;IACpC,SAAS,EAAE,gBAAgB,CAAC,SAAS,CAAC;IACtC,MAAM,EAAE,aAAa,CAAC,SAAS,GAAG,aAAa,CAAC,KAAK,CAAC;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,SAAS,EAAE,gBAAgB,CAAC,QAAQ,CAAC;IACrC,MAAM,EAAE,aAAa,CAAC,IAAI,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qFAAqF;IACrF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kFAAkF;IAClF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,SAAS,EAAE,gBAAgB,CAAC,OAAO,CAAC;IACpC,MAAM,EAAE,aAAa,CAAC,KAAK,GAAG,aAAa,CAAC,IAAI,GAAG,aAAa,CAAC,KAAK,GAAG,aAAa,CAAC,KAAK,GAAG,aAAa,CAAC,SAAS,GAAG,aAAa,CAAC,MAAM,CAAC;IAC9I,QAAQ,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kFAAkF;IAClF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,oBAAY,8BAA8B;IACxC,QAAQ,aAAa;IACrB,UAAU,eAAe;CAC1B;AAED,MAAM,MAAM,oBAAoB,GAAG;IACjC;;;;OAIG;IACH,WAAW,CAAC,EAAE,8BAA8B,CAAC;CAC9C,CAAC"}
+{"version":3,"file":"permission-types.d.ts","sourceRoot":"","sources":["../../../../src/types/permission-types.ts"],"names":[],"mappings":"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"}

package/dist/types/tests/features/author-delegated-grant.spec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"author-delegated-grant.spec.d.ts","sourceRoot":"","sources":["../../../../tests/features/author-delegated-grant.spec.ts"],"names":[],"mappings":"AA2BA,wBAAgB,wBAAwB,IAAI,IAAI,CA0iD/C"}
+{"version":3,"file":"author-delegated-grant.spec.d.ts","sourceRoot":"","sources":["../../../../tests/features/author-delegated-grant.spec.ts"],"names":[],"mappings":"AA2BA,wBAAgB,wBAAwB,IAAI,IAAI,CAurD/C"}

package/dist/types/tests/handlers/records-read.spec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"records-read.spec.d.ts","sourceRoot":"","sources":["../../../../tests/handlers/records-read.spec.ts"],"names":[],"mappings":"AAkCA,wBAAgB,sBAAsB,IAAI,IAAI,CAqnE7C"}
+{"version":3,"file":"records-read.spec.d.ts","sourceRoot":"","sources":["../../../../tests/handlers/records-read.spec.ts"],"names":[],"mappings":"AAkCA,wBAAgB,sBAAsB,IAAI,IAAI,CA2nE7C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enbox/dwn-sdk-js",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "A reference implementation of https://identity.foundation/decentralized-web-node/spec/",
   "repository": {
     "type": "git",

package/src/core/grant-authorization.ts

@@ -119,7 +119,8 @@ export class GrantAuthorization {
    * Verify that the `interface` and `method` grant scopes match the incoming message.
    *
    * For the Messages interface, a `Read` scope is treated as a unified scope that also authorizes
-   * `Query`, `Subscribe`, and `Sync` operations.
+   * `Query` and `Subscribe` operations. For Records, `Read` is likewise the canonical read-like
+   * scope and authorizes `Read`, `Query`, `Subscribe`, and `Count` operations.
    *
    * @throws {DwnError} if the `interface` and `method` of the incoming message do not match the scope of the permission grant.
    */
@@ -155,6 +156,22 @@ export class GrantAuthorization {
       return;
     }
 
+    // Records.Read is the only valid read-like Records scope and covers Read, Query,
+    // Subscribe, and Count operations. Reject malformed Records Query/Subscribe/Count
+    // grants instead of treating them as compatible with the canonical Read scope.
+    if (dwnInterface === DwnInterfaceName.Records) {
+      const readLikeMethods = [DwnMethodName.Read, DwnMethodName.Query, DwnMethodName.Subscribe, DwnMethodName.Count];
+      if (readLikeMethods.includes(dwnMethod as DwnMethodName)) {
+        if (permissionGrant.scope.method !== DwnMethodName.Read) {
+          throw new DwnError(
+            DwnErrorCode.GrantAuthorizationMethodMismatch,
+            `records read-like permission grant must have method 'Read', got '${permissionGrant.scope.method}' for grant ${permissionGrant.id}`
+          );
+        }
+        return;
+      }
+    }
+
     if (dwnMethod !== permissionGrant.scope.method) {
       throw new DwnError(
         DwnErrorCode.GrantAuthorizationMethodMismatch,

package/src/protocols/permission-grant.ts

@@ -1,5 +1,5 @@
 import type { DataEncodedRecordsWriteMessage } from '../types/records-types.js';
-import type { PermissionConditions, PermissionGrantData, PermissionScope } from '../types/permission-types.js';
+import type { ConnectSessionMetadata, PermissionConditions, PermissionGrantData, PermissionScope } from '../types/permission-types.js';
 
 import { Encoder } from '../utils/encoder.js';
 import { Message } from '../core/message.js';
@@ -66,6 +66,11 @@ export class PermissionGrant {
    */
   public readonly delegateKeyDelivery?: { rootKeyId: string; publicKeyJwk: Record<string, any> };
 
+  /**
+   * Optional metadata describing the connect approval session that created this grant.
+   */
+  public readonly connectSession?: ConnectSessionMetadata;
+
   /**
    * Parses a `DataEncodedRecordsWriteMessage` into a `PermissionGrant`.
    * Validates that the message contains required structural fields:
@@ -138,6 +143,6 @@ export class PermissionGrant {
     this.scope = permissionGrant.scope;
     this.conditions = permissionGrant.conditions;
     this.delegateKeyDelivery = permissionGrant.delegateKeyDelivery;
+    this.connectSession = permissionGrant.connectSession;
   }
 }
-

package/src/protocols/permissions.ts

@@ -3,9 +3,9 @@ import type { MessagesFilter } from '../types/messages-types.js';
 import type { MessageSigner } from '../types/signer.js';
 import type { ProtocolDefinition } from '../types/protocols-types.js';
 import type { ValidationStateReader } from '../types/validation-state-reader.js';
+import type { ConnectSessionMetadata, PermissionConditions, PermissionGrantData, PermissionRequestData, PermissionRevocationData, PermissionScope, RecordsPermissionScope } from '../types/permission-types.js';
 import type { CoreProtocol, CoreProtocolStores } from '../core/core-protocol.js';
 import type { DataEncodedRecordsWriteMessage, RecordsWriteMessage } from '../types/records-types.js';
-import type { PermissionConditions, PermissionGrantData, PermissionRequestData, PermissionRevocationData, PermissionScope, RecordsPermissionScope } from '../types/permission-types.js';
 
 import { DwnConstant } from '../core/dwn-constant.js';
 import { DwnMethodName } from '../enums/dwn-interface-method.js';
@@ -63,6 +63,7 @@ export type PermissionGrantCreateOptions = {
   delegated?: boolean;
   scope: PermissionScope;
   conditions?: PermissionConditions;
+  connectSession?: ConnectSessionMetadata;
 };
 
 /**
@@ -422,12 +423,13 @@ export class PermissionsProtocol implements CoreProtocol {
     const scope = PermissionsProtocol.normalizePermissionScope(options.scope);
 
     const permissionGrantData: PermissionGrantData = {
-      dateExpires : options.dateExpires,
-      requestId   : options.requestId,
-      description : options.description,
-      delegated   : options.delegated,
+      dateExpires    : options.dateExpires,
+      requestId      : options.requestId,
+      description    : options.description,
+      delegated      : options.delegated,
       scope,
-      conditions  : options.conditions,
+      conditions     : options.conditions,
+      connectSession : options.connectSession,
     };
 
     // If the grant is scoped to a protocol, the protocol tag must be included with the record.

package/src/types/permission-types.ts

@@ -1,5 +1,60 @@
 import type { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
 
+/**
+ * Metadata describing the connect approval session that created a permission grant.
+ *
+ * Wallets use this to group grants into user-facing app sessions and to
+ * distinguish active sessions from expired permission bundles. App and client
+ * fields are self-reported by the requester, unauthenticated, and intended for
+ * display only. Consumers must not treat them as verified app identity.
+ */
+export type ConnectSessionMetadata = {
+  /** Stable session ID shared by all grants created by one connect approval. */
+  id: string;
+
+  /** Human-readable app name shown during approval. Self-reported display data. */
+  appName?: string;
+
+  /** App icon URL shown during approval. Self-reported display data. */
+  appIcon?: string;
+
+  /** Origin of the requesting app, when known. Self-reported display data. */
+  origin?: string;
+
+  /** User agent string captured by the connect client, when available. Display data only. */
+  userAgent?: string;
+
+  /** Platform/device hint captured by the connect client, when available. */
+  platform?: string;
+
+  /** Primary browser language captured by the connect client, when available. */
+  language?: string;
+
+  /** Browser language preferences captured by the connect client, when available. */
+  languages?: string[];
+
+  /** IANA timezone captured by the connect client, when available. */
+  timezone?: string;
+
+  /** Connect transport that created the session. */
+  transport?: ConnectSessionTransport;
+
+  /** Timestamp when the wallet approved the connect session. */
+  createdAt: string;
+
+  /**
+   * Display timestamp for when the connect session expires.
+   *
+   * The enforcing value is the enclosing permission grant's `dateExpires`.
+   * Consumers must use `dateExpires`, not this metadata field, for any
+   * authorization or security decision.
+   */
+  expiresAt: string;
+};
+
+/** Connect transport that created a connect session. */
+export type ConnectSessionTransport = 'relay' | 'postMessage';
+
 /**
  * Type for the data payload of a permission request message.
  */
@@ -63,6 +118,9 @@ export type PermissionGrantData = {
     rootKeyId: string;
     publicKeyJwk: Record<string, any>;
   };
+
+  /** Optional metadata for the connect session that created this grant. */
+  connectSession?: ConnectSessionMetadata;
 };
 
 /**
@@ -104,10 +162,13 @@ export type MessagesPermissionScope = {
 
 /**
  * The data model for a permission scope that is specific to the Records interface.
+ *
+ * `Read` is the only valid read-like Records permission scope and authorizes
+ * `RecordsRead`, `RecordsQuery`, `RecordsSubscribe`, and `RecordsCount` operations.
  */
 export type RecordsPermissionScope = {
   interface: DwnInterfaceName.Records;
-  method: DwnMethodName.Count | DwnMethodName.Read | DwnMethodName.Write | DwnMethodName.Query | DwnMethodName.Subscribe | DwnMethodName.Delete;
+  method: DwnMethodName.Read | DwnMethodName.Write | DwnMethodName.Delete;
   protocol: string;
   /** May only be present when `protocol` is defined and `protocolPath` is undefined */
   contextId?: string;