@enbox/dwn-sdk-js 0.4.4 → 0.4.6

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

@@ -109,16 +109,6 @@ 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.