@enbox/dwn-sdk-js 0.4.3 → 0.4.5

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/encryption-types.ts

@@ -1,53 +1,24 @@
-import type { JweKeyUnwrapPayload } from '../utils/encryption.js';
 import type { KeyDerivationScheme } from '../utils/hd-key.js';
+import type { KeyUnwrapPayload } from '../utils/encryption.js';
 import type { PublicKeyJwk } from './jose-types.js';
 
-/**
- * A callback interface for deriving HD public encryption keys.
- * The implementor performs HKDF key derivation and public key computation
- * internally — the private key never leaves the implementation boundary.
- *
- * Analogous to `MessageSigner` for signing operations.
- */
+export type KeyDecrypterDerivationScheme = KeyDerivationScheme | 'roleAudience';
+
 export interface EncryptionKeyDeriver {
-  /** Fully qualified key ID (e.g. did:example:alice#enc) */
   rootKeyId: string;
-  /** The derivation scheme (e.g. KeyDerivationScheme.ProtocolPath) */
   derivationScheme: KeyDerivationScheme;
-  /**
-   * Derives an HD child public key for the given full derivation path.
-   * The private key material stays within the implementor's boundary.
-   *
-   * @param fullDerivationPath - The complete HKDF path segments
-   *   (e.g. ['protocolPath', 'https://chat.example', 'thread', 'message'])
-   * @returns The derived child public key as a JWK
-   */
+
   derivePublicKey(fullDerivationPath: string[]): Promise<PublicKeyJwk>;
 }
 
-/**
- * A callback interface for decrypting JWE-wrapped Content Encryption Keys (CEKs).
- * The implementor performs HKDF key derivation, ECDH-ES key agreement, and AES Key Unwrap
- * internally — the private key never leaves the implementation boundary.
- *
- * Analogous to `MessageSigner` for signing operations.
- */
 export interface KeyDecrypter {
-  /** Fully qualified key ID (e.g. did:example:alice#enc) */
   rootKeyId: string;
-  /** The derivation scheme (e.g. KeyDerivationScheme.ProtocolPath) */
-  derivationScheme: KeyDerivationScheme;
-  /**
-   * Unwraps a JWE-encrypted Content Encryption Key (CEK) after deriving the
-   * leaf decryption key via HKDF through the given derivation path, then
-   * performing ECDH-ES key agreement and AES-256 Key Unwrap.
-   *
-   * @param fullDerivationPath - The complete HKDF path to derive the leaf key
-   * @param jweKeyUnwrapPayload - The wrapped CEK and ephemeral public key from the JWE recipient
-   * @returns The unwrapped CEK bytes (typically 32 bytes for AES-256)
-   */
+  derivationScheme: KeyDecrypterDerivationScheme;
+
+  derivePublicKey(fullDerivationPath: string[]): Promise<PublicKeyJwk>;
+
   decrypt(
     fullDerivationPath: string[],
-    jweKeyUnwrapPayload: JweKeyUnwrapPayload,
+    keyUnwrapPayload: KeyUnwrapPayload,
   ): Promise<Uint8Array>;
 }

package/src/types/message-types.ts

@@ -1,6 +1,5 @@
 import type { GeneralJws } from './jws-types.js';
 import type { ProgressToken } from './subscriptions.js';
-import type { PublicKeyJwk } from './jose-types.js';
 import type { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
 import type { PaginationCursor, SortDirection } from './query-types.js';
 
@@ -44,18 +43,6 @@ export type AuthorizationModel = {
    */
   ownerDelegatedGrant?: DelegatedGrantRecordsWriteMessage;
 
-  /**
-   * The author's ProtocolPath-derived public key for the key-delivery protocol's
-   * `contextKey` path.  Included by external authors on cross-DWN encrypted
-   * protocol records so the DWN owner can encrypt a context key back to them
-   * without needing to query the author's DWN.
-   */
-  authorKeyDeliveryPublicKey?: {
-    /** Fully-qualified verification method ID (e.g. `did:example:bob#enc`). */
-    rootKeyId: string;
-    /** The author's ProtocolPath-derived public key in JWK format. */
-    publicKeyJwk: PublicKeyJwk;
-  };
 };
 
 export type DelegatedGrantRecordsWriteMessage = {

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.
  */
@@ -54,15 +109,8 @@ export type PermissionGrantData = {
 
   conditions?: PermissionConditions;
 
-  /**
-   * Optional delegate key-delivery metadata for cross-device context key delivery.
-   * Contains the pre-derived ProtocolPath leaf public key that the owner uses
-   * to encrypt contextKey records addressed to the delegate.
-   */
-  delegateKeyDelivery?: {
-    rootKeyId: string;
-    publicKeyJwk: Record<string, any>;
-  };
+  /** Optional metadata for the connect session that created this grant. */
+  connectSession?: ConnectSessionMetadata;
 };
 
 /**

package/src/types/protocols-types.ts

@@ -12,6 +12,7 @@ export type ProtocolsConfigureDescriptor = {
 
 export type ProtocolDefinition = {
   protocol: string;
+  $keyAgreement?: ProtocolKeyAgreement;
   /**
    * Denotes if this Protocol Definition can be returned by unauthenticated or unauthorized `ProtocolsQuery`.
    */
@@ -132,18 +133,9 @@ export type ProtocolActionRule = {
   can: (ProtocolAction | `${ProtocolAction}` | (string & {}))[];
 };
 /**
- * Config for protocol-path encryption scheme.
+ * Public key used for protocol-path content encryption.
  */
-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.
-   */
+export type ProtocolKeyAgreement = {
   publicKeyJwk: PublicKeyJwk;
 };
 
@@ -224,6 +216,7 @@ export type ProtocolTagSchema = {
   exclusiveMaximum?: number;
   minLength?: number;
   maxLength?: number;
+  pattern?: string;
   minItems?: number;
   maxItems?: number;
   uniqueItems?: boolean;
@@ -234,13 +227,13 @@ export type ProtocolTagSchema = {
 /**
  * Union of all value types that can appear as properties of a `ProtocolRuleSet`.
  * This includes:
- * - `$`-prefixed directive values (`$encryption`, `$actions`, `$role`, `$ref`, `$size`, `$tags`, `$delivery`)
+ * - `$`-prefixed directive values (`$keyAgreement`, `$actions`, `$role`, `$ref`, `$size`, `$tags`, `$delivery`)
  * - Child `ProtocolRuleSet` entries (non-`$` keys)
  */
 type ProtocolRuleSetValue =
   | ProtocolRuleSet
   | ProtocolActionRule[]
-  | ProtocolPathEncryption
+  | ProtocolKeyAgreement
   | ProtocolTagsDefinition
   | ProtocolSizeDefinition
   | ProtocolRecordLimitDefinition
@@ -251,9 +244,9 @@ type ProtocolRuleSetValue =
 
 export type ProtocolRuleSet = {
   /**
-   * Encryption setting for objects that are in this protocol path.
+   * Key agreement setting for records at this protocol path.
    */
-  $encryption?: ProtocolPathEncryption;
+  $keyAgreement?: ProtocolKeyAgreement;
   $actions?: ProtocolActionRule[];
 
   /**
@@ -268,7 +261,7 @@ export type ProtocolRuleSet = {
    * and `typePath` is the protocol path of the type in the external protocol's structure.
    *
    * A `$ref` node is a pure attachment point — it must NOT have `$actions`, `$role`, `$size`,
-   * `$tags`, or `$encryption`. Authorization for the referenced type is governed by its own
+   * `$tags`, or `$keyAgreement`. Authorization for the referenced type is governed by its own
    * protocol. Only children defined under the `$ref` node get `$actions` from the composing protocol.
    *
    * Example:

package/src/types/records-types.ts

@@ -1,5 +1,5 @@
+import type { DwnEncryption } from '../utils/encryption.js';
 import type { GeneralJws } from './jws-types.js';
-import type { JweEncryption } from '../utils/encryption.js';
 import type { AuthorizationModel, GenericMessage, GenericMessageReply, GenericSignaturePayload, MessageSubscription, Pagination } from './message-types.js';
 import type { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
 import type { PaginationCursor, RangeCriterion, RangeFilter, StartsWithFilter } from './query-types.js';
@@ -60,7 +60,7 @@ export type InternalRecordsWriteMessage = GenericMessage & {
   contextId?: string;
   descriptor: RecordsWriteDescriptor;
   attestation?: GeneralJws;
-  encryption?: JweEncryption;
+  encryption?: DwnEncryption;
 };
 
 export type RecordsWriteMessage = {
@@ -69,7 +69,7 @@ export type RecordsWriteMessage = {
   contextId: string;
   descriptor: RecordsWriteDescriptor;
   attestation?: GeneralJws;
-  encryption?: JweEncryption;
+  encryption?: DwnEncryption;
 };
 
 /**

package/src/types/validation-state-reader.ts

@@ -78,6 +78,19 @@ export interface ValidationStateReader {
     contextIdPrefix?: string;
   }): Promise<RecordsWriteMessage[]>;
 
+  /**
+   * Queries accepted audience epoch records in the Encryption Protocol.
+   * The optional `keyId` narrows the lookup to one published audience key.
+   */
+  queryAudienceEpochs(input: {
+    tenant: string;
+    protocol: string;
+    contextId: string;
+    role: string;
+    epoch: number;
+    keyId?: string;
+  }): Promise<RecordsWriteMessage[]>;
+
   /**
    * Fetches the permission grant with the given record ID, with its scope parsed from grant data.
    * @throws {DwnError} with `GrantAuthorizationGrantMissing` when the grant does not exist.