@enbox/dwn-sdk-js 0.0.4 → 0.0.5

package/src/interfaces/records-write.ts

@@ -6,8 +6,6 @@ import type { MessageStore } from '../types/message-store.js';
 import type { PublicKeyJwk } from '../types/jose-types.js';
 import type {
   DataEncodedRecordsWriteMessage,
-  EncryptedKey,
-  EncryptionProperty,
   InternalRecordsWriteMessage,
   RecordsWriteAttestationPayload,
   RecordsWriteDescriptor,
@@ -15,12 +13,12 @@ import type {
   RecordsWriteSignaturePayload,
   RecordsWriteTags
 } from '../types/records-types.js';
+import type { EncryptionInput, JweEncryption } from '../utils/encryption.js';
 import type { GenericMessage, GenericSignaturePayload } from '../types/message-types.js';
 
 import { Cid } from '../utils/cid.js';
 import { Encoder } from '../utils/encoder.js';
 import { Encryption } from '../utils/encryption.js';
-import { EncryptionAlgorithm } from '../utils/encryption.js';
 import { GeneralJwsBuilder } from '../jose/jws/general/builder.js';
 import { Jws } from '../utils/jws.js';
 import { KeyDerivationScheme } from '../utils/hd-key.js';
@@ -29,7 +27,6 @@ import { PermissionGrant } from '../protocols/permission-grant.js';
 import { Records } from '../utils/records.js';
 import { RecordsGrantAuthorization } from '../core/records-grant-authorization.js';
 import { removeUndefinedProperties } from '../utils/object.js';
-import { Secp256k1 } from '../utils/secp256k1.js';
 import { Time } from '../utils/time.js';
 import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
 import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
@@ -85,57 +82,7 @@ export type RecordsWriteOptions = {
   };
 };
 
-/**
- * Input that describes how data is encrypted as spec-ed in TP18.
- */
-export type EncryptionInput = {
-  /**
-   * Algorithm used for encrypting the Data. Uses {EncryptionAlgorithm.Aes256Ctr} if not given.
-   */
-  algorithm?: EncryptionAlgorithm;
-
-  /**
-   * Initialization vector used for encrypting the data.
-   */
-  initializationVector: Uint8Array;
-
-  /**
-   * Symmetric key used to encrypt the data.
-   */
-  key: Uint8Array;
-
-  /**
-   * Array of input that specifies how the symmetric key is encrypted.
-   * Each entry in the array will result in a unique ciphertext of the symmetric key.
-   */
-  keyEncryptionInputs: KeyEncryptionInput[];
-};
-
-/**
- * Input that specifies how a symmetric key is encrypted.
- */
-export type KeyEncryptionInput = {
-  /**
-   * Key derivation scheme used to derive the public key to encrypt the symmetric key.
-   */
-  derivationScheme: KeyDerivationScheme;
-
-  /**
-   * Fully qualified ID of root public key used derive the public key to be used to to encrypt the symmetric key.
-   * (e.g. did:example:abc#encryption-key-id)
-   */
-  publicKeyId: string;
-
-  /**
-   * Public key to be used to encrypt the symmetric key.
-   */
-  publicKey: PublicKeyJwk;
-
-  /**
-   * Algorithm used for encrypting the symmetric key. Uses {EncryptionAlgorithm.EciesSecp256k1} if not given.
-   */
-  algorithm?: EncryptionAlgorithm;
-};
+export type { EncryptionInput, KeyEncryptionInput } from '../utils/encryption.js';
 
 export type CreateFromOptions = {
   recordsWriteMessage: RecordsWriteMessage,
@@ -499,10 +446,10 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
   /**
    * Encrypts the symmetric encryption key using the public keys given and attach the resulting `encryption` property to the RecordsWrite.
    *
-   * @param options.append - When `true`, appends new `keyEncryption` entries to the existing
+   * @param options.append - When `true`, appends new `recipients` entries to the existing
    *   `encryption` property instead of replacing it. Requires `this._message.encryption` to
    *   already exist (i.e., the record must already be encrypted). This is used for the reactive
-   *   root-record upgrade: adding a ProtocolContext `keyEncryption` entry alongside an existing
+   *   root-record upgrade: adding a ProtocolContext recipient entry alongside an existing
    *   ProtocolPath entry so both the owner and context key holders can decrypt.
    */
   public async encryptSymmetricEncryptionKey(
@@ -513,20 +460,20 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
       if (!this._message.encryption) {
         throw new DwnError(
           DwnErrorCode.RecordsWriteMissingEncryption,
-          'Cannot append keyEncryption entries: record does not have an existing `encryption` property.'
+          'Cannot append recipients: record does not have an existing `encryption` property.'
         );
       }
 
-      // Build only the new keyEncryption entries (reuses createEncryptionProperty for ECIES logic)
+      // Build only the new recipients (reuses createEncryptionProperty for ECDH-ES+A256KW logic)
       const newEncryption = await RecordsWrite.createEncryptionProperty(this._message.descriptor, encryptionInput);
       if (newEncryption) {
-        this._message.encryption.keyEncryption.push(...newEncryption.keyEncryption);
+        this._message.encryption.recipients.push(...newEncryption.recipients);
       }
 
       // In append mode, preserve the author's identity and authorization so
       // that signAsOwner() can be called afterwards. The author's signature
       // payload will have a stale encryptionCid (since we just appended new
-      // keyEncryption entries), but the owner's signature vouches for the
+      // recipients), but the owner's signature vouches for the
       // updated state. validateIntegrity() skips the encryptionCid check on
       // the author's signature when an ownerSignature is present.
       //
@@ -727,7 +674,7 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
 
     // If `encryption` is given in message, make sure the correct `encryptionCid`
     // is in the payload of the message signature — UNLESS the message has an
-    // ownerSignature. When the DWN owner appends keyEncryption entries to an
+    // ownerSignature. When the DWN owner appends recipients to an
     // externally-authored record (reactive root-record upgrade), the author's
     // encryptionCid becomes stale. The owner's signature vouches for the
     // updated encryption property, so the mismatch is expected and safe.
@@ -759,7 +706,7 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
 
   /**
    * Validates the structural integrity of the `attestation` property.
-   * NOTE: signature is not verified.
+   * NOTE: Cryptographic verification of attestation signatures is performed in `authenticate()`.
    */
   private static async validateAttestationIntegrity(message: RecordsWriteMessage): Promise<void> {
     if (message.attestation === undefined) {
@@ -906,21 +853,33 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
   }
 
   /**
-   * Creates the `encryption` property if encryption input is given. Else `undefined` is returned.
-   * @param descriptor Descriptor of the `RecordsWrite` message which contains the information need by key path derivation schemes.
+   * Creates the JWE `encryption` property if encryption input is given. Else `undefined` is returned.
+   * Uses ECDH-ES+A256KW key agreement with X25519 and AEAD content encryption (A256GCM or XC20P).
+   * @param descriptor Descriptor of the `RecordsWrite` message which contains the information needed by key path derivation schemes.
+   */
+  /**
+   * Creates the JWE `encryption` property if encryption input is given. Else `undefined` is returned.
+   * Uses ECDH-ES+A256KW key agreement with X25519 and AEAD content encryption (A256GCM or XC20P).
+   * @param descriptor Descriptor of the `RecordsWrite` message which contains the information needed by key path derivation schemes.
+   * @param encryptionInput The encryption input containing CEK, IV, and recipient key encryption inputs.
+   * @param tag The authentication tag from the AEAD content encryption (stored in the JWE, separate from the ciphertext).
+   */
+  /**
+   * Creates the JWE `encryption` property if encryption input is given. Else `undefined` is returned.
+   * Uses ECDH-ES+A256KW key agreement with X25519 and AEAD content encryption (A256GCM or XC20P).
+   * @param descriptor Descriptor of the `RecordsWrite` message which contains the information needed by key path derivation schemes.
+   * @param encryptionInput The encryption input containing CEK, IV, authentication tag, and recipient key encryption inputs.
    */
   private static async createEncryptionProperty(
     descriptor: RecordsWriteDescriptor,
-    encryptionInput: EncryptionInput | undefined
-  ): Promise<EncryptionProperty | undefined> {
+    encryptionInput: EncryptionInput | undefined,
+  ): Promise<JweEncryption | undefined> {
     if (encryptionInput === undefined) {
       return undefined;
     }
 
-    // encrypt the data encryption key once per encryption input
-    const keyEncryption: EncryptedKey[] = [];
+    // Validate derivation scheme prerequisites
     for (const keyEncryptionInput of encryptionInput.keyEncryptionInputs) {
-
       if (keyEncryptionInput.derivationScheme === KeyDerivationScheme.ProtocolPath && descriptor.protocol === undefined) {
         throw new DwnError(
           DwnErrorCode.RecordsWriteMissingProtocol,
@@ -934,43 +893,12 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
           '`schemas` encryption scheme cannot be applied to record without the `schema` property.'
         );
       }
-
-      // NOTE: right now only `ECIES-ES256K` algorithm is supported for asymmetric encryption,
-      // so we will assume that's the algorithm without additional switch/if statements
-      const publicKeyBytes = Secp256k1.publicJwkToBytes(keyEncryptionInput.publicKey);
-      const keyEncryptionOutput = await Encryption.eciesSecp256k1Encrypt(publicKeyBytes, encryptionInput.key);
-
-      const encryptedKey = Encoder.bytesToBase64Url(keyEncryptionOutput.ciphertext);
-      const ephemeralPublicKey = await Secp256k1.publicKeyToJwk(keyEncryptionOutput.ephemeralPublicKey);
-      const keyEncryptionInitializationVector = Encoder.bytesToBase64Url(keyEncryptionOutput.initializationVector);
-      const messageAuthenticationCode = Encoder.bytesToBase64Url(keyEncryptionOutput.messageAuthenticationCode);
-      const encryptedKeyData: EncryptedKey = {
-        rootKeyId            : keyEncryptionInput.publicKeyId,
-        algorithm            : keyEncryptionInput.algorithm ?? EncryptionAlgorithm.EciesSecp256k1,
-        derivationScheme     : keyEncryptionInput.derivationScheme,
-        ephemeralPublicKey,
-        initializationVector : keyEncryptionInitializationVector,
-        messageAuthenticationCode,
-        encryptedKey
-      };
-
-      // we need to attach the actual public key if derivation scheme is protocol-context,
-      // so that the responder to this message is able to encrypt the message/symmetric key using the same protocol-context derived public key,
-      // without needing the knowledge of the corresponding private key
-      if (keyEncryptionInput.derivationScheme === KeyDerivationScheme.ProtocolContext) {
-        encryptedKeyData.derivedPublicKey = keyEncryptionInput.publicKey;
-      }
-
-      keyEncryption.push(encryptedKeyData);
     }
 
-    const encryption: EncryptionProperty = {
-      algorithm            : encryptionInput.algorithm ?? EncryptionAlgorithm.Aes256Ctr,
-      initializationVector : Encoder.bytesToBase64Url(encryptionInput.initializationVector),
-      keyEncryption
-    };
+    // Build the JWE structure. The authentication tag comes from the AEAD encryption of record data.
+    const jwe = await Encryption.buildJwe(encryptionInput, encryptionInput.authenticationTag);
 
-    return encryption;
+    return jwe;
   }
 
   /**
@@ -996,7 +924,7 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
     contextId: string | undefined,
     descriptorCid: string,
     attestation: GeneralJws | undefined,
-    encryption: EncryptionProperty | undefined,
+    encryption: JweEncryption | undefined,
     signer: MessageSigner,
     delegatedGrantId?: string,
     permissionGrantId?: string,

package/src/jose/jws/general/verifier.ts

@@ -3,6 +3,7 @@ import type { GeneralJws } from '../../../types/jws-types.js';
 import type { PublicKeyJwk } from '../../../types/jose-types.js';
 import type { DidResolver, DidVerificationMethod } from '@enbox/dids';
 
+import { Encoder } from '../../../utils/encoder.js';
 import { Jws } from '../../../utils/jws.js';
 import { MemoryCache } from '../../../utils/memory-cache.js';
 import { validateJsonSchema } from '../../../schema-validator.js';
@@ -51,7 +52,16 @@ export class GeneralJwsVerifier {
 
     for (const signatureEntry of jws.signatures) {
       let isVerified: boolean;
-      const kid = Jws.getKid(signatureEntry);
+      const protectedHeader = Encoder.base64UrlToObject(signatureEntry.protected);
+      const { kid, alg } = protectedHeader;
+
+      if (kid === undefined || typeof kid !== 'string') {
+        throw new DwnError(DwnErrorCode.GeneralJwsVerifierMissingKid, `JWS protected header is missing required 'kid' property`);
+      }
+
+      if (alg === undefined || typeof alg !== 'string') {
+        throw new DwnError(DwnErrorCode.GeneralJwsVerifierMissingAlg, `JWS protected header is missing required 'alg' property`);
+      }
 
       const cacheKey = `${signatureEntry.protected}.${jws.payload}.${signatureEntry.signature}`;
       const cachedValue = await this.cache.get(cacheKey);

package/src/smt/smt-utils.ts

@@ -134,7 +134,7 @@ export function hashEquals(a: Hash, b: Hash): boolean {
  * Convert a hash to a hex string for use as a store key.
  */
 export function hashToHex(hash: Hash): string {
-  return Buffer.from(hash).toString('hex');
+  return Array.from(hash, (b: number): string => b.toString(16).padStart(2, '0')).join('');
 }
 
 /**

package/src/types/encryption-types.ts

@@ -1,4 +1,4 @@
-import type { EciesEncryptionOutput } from '../utils/encryption.js';
+import type { JweKeyUnwrapPayload } from '../utils/encryption.js';
 import type { KeyDerivationScheme } from '../utils/hd-key.js';
 import type { PublicKeyJwk } from './jose-types.js';
 
@@ -26,8 +26,8 @@ export interface EncryptionKeyDeriver {
 }
 
 /**
- * A callback interface for decrypting ECIES-encrypted data encryption keys.
- * The implementor performs HKDF key derivation and ECIES decryption
+ * 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.
@@ -38,15 +38,16 @@ export interface KeyDecrypter {
   /** The derivation scheme (e.g. KeyDerivationScheme.ProtocolPath) */
   derivationScheme: KeyDerivationScheme;
   /**
-   * Decrypts an ECIES-SECP256K1 encrypted payload after deriving the
-   * leaf decryption key via HKDF through the given derivation path.
+   * 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 eciesEncryptedPayload - The ECIES ciphertext components
-   * @returns The decrypted plaintext bytes (typically a 32-byte DEK)
+   * @param jweKeyUnwrapPayload - The wrapped CEK and ephemeral public key from the JWE recipient
+   * @returns The unwrapped CEK bytes (typically 32 bytes for AES-256)
    */
   decrypt(
     fullDerivationPath: string[],
-    eciesEncryptedPayload: EciesEncryptionOutput,
+    jweKeyUnwrapPayload: JweKeyUnwrapPayload,
   ): Promise<Uint8Array>;
 }

package/src/types/protocols-types.ts

@@ -49,7 +49,7 @@ export type ProtocolType = {
   /**
    * When `true`, records of this type **must** be encrypted at the DWN record
    * level using the tenant's ProtocolPath-derived encryption key. The tenant
-   * DID must have a secp256k1 keyAgreement key; protocol installation will
+   * DID must have an X25519 keyAgreement key; protocol installation will
    * fail if it does not.
    *
    * When `false` or omitted, encryption is not required for this type.
@@ -105,9 +105,11 @@ 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`
+   * Mutually exclusive with `role`.
+   *
+   * Accepts both enum values (`ProtocolActor.Anyone`) and string literals (`'anyone'`).
    */
-  who?: string,
+  who?: ProtocolActor | `${ProtocolActor}` | (string & {});
 
   /**
    * The protocol path of a role record type marked with $role: true.
@@ -126,7 +128,7 @@ export type ProtocolActionRule = {
    * See {ProtocolAction} for possible values.
    * 'read' authorizes read, query, and subscribe access.
    */
-  can: string[];
+  can: (ProtocolAction | `${ProtocolAction}` | (string & {}))[];
 };
 /**
  * Config for protocol-path encryption scheme.
@@ -144,6 +146,65 @@ export type ProtocolPathEncryption = {
   publicKeyJwk: PublicKeyJwk;
 };
 
+/**
+ * Size constraints for records at a given protocol path.
+ */
+export type ProtocolSizeDefinition = {
+  min?: number;
+  max?: number;
+};
+
+/**
+ * Tag rules for records at a given protocol path. Each non-`$`-prefixed property
+ * is a JSON Schema object constraining that tag's value.
+ */
+export type ProtocolTagsDefinition = {
+  /** Array of tag names that must be present on every record. */
+  $requiredTags?: string[];
+  /** When `false` (default), only tags explicitly listed are allowed. */
+  $allowUndefinedTags?: boolean;
+  /** JSON Schema definitions for individual tags. */
+  [tag: string]: ProtocolTagSchema | string[] | boolean | undefined;
+};
+
+/**
+ * A JSON Schema object constraining a single tag value.
+ * Supports the subset of JSON Schema used by DWN tag validation.
+ */
+export type ProtocolTagSchema = {
+  type: 'string' | 'number' | 'integer' | 'boolean' | 'array';
+  items?: { type: 'string' | 'number' | 'integer' };
+  contains?: { type: 'string' | 'number' | 'integer' };
+  enum?: (string | number | boolean)[];
+  minimum?: number;
+  maximum?: number;
+  exclusiveMinimum?: number;
+  exclusiveMaximum?: number;
+  minLength?: number;
+  maxLength?: number;
+  minItems?: number;
+  maxItems?: number;
+  uniqueItems?: boolean;
+  minContains?: number;
+  maxContains?: number;
+};
+
+/**
+ * Union of all value types that can appear as properties of a `ProtocolRuleSet`.
+ * This includes:
+ * - `$`-prefixed directive values (`$encryption`, `$actions`, `$role`, `$ref`, `$size`, `$tags`)
+ * - Child `ProtocolRuleSet` entries (non-`$` keys)
+ */
+type ProtocolRuleSetValue =
+  | ProtocolRuleSet
+  | ProtocolActionRule[]
+  | ProtocolPathEncryption
+  | ProtocolTagsDefinition
+  | ProtocolSizeDefinition
+  | boolean
+  | string
+  | undefined;
+
 export type ProtocolRuleSet = {
   /**
    * Encryption setting for objects that are in this protocol path.
@@ -179,25 +240,18 @@ export type ProtocolRuleSet = {
   /**
    * If $size is set, the record size in bytes must be within the limits.
    */
-  $size?: {
-    min?: number,
-    max?: number
-  }
+  $size?: ProtocolSizeDefinition;
 
   /**
    * 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;
-  }
+  $tags?: ProtocolTagsDefinition;
 
-  // JSON Schema verifies that properties other than properties prefixed with $ will actually have type ProtocolRuleSet
-  [key: string]: any;
+  /**
+   * Non-`$`-prefixed keys are nested child `ProtocolRuleSet` entries.
+   * At runtime, JSON Schema validation ensures only valid child rule sets appear here.
+   */
+  [key: string]: ProtocolRuleSetValue;
 };
 
 export type ProtocolsConfigureMessage = GenericMessage & {

package/src/types/records-types.ts

@@ -1,7 +1,5 @@
-import type { EncryptionAlgorithm } from '../utils/encryption.js';
 import type { GeneralJws } from './jws-types.js';
-import type { KeyDerivationScheme } from '../utils/hd-key.js';
-import type { PublicKeyJwk } from './jose-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';
@@ -53,7 +51,7 @@ export type InternalRecordsWriteMessage = GenericMessage & {
   contextId?: string;
   descriptor: RecordsWriteDescriptor;
   attestation?: GeneralJws;
-  encryption?: EncryptionProperty;
+  encryption?: JweEncryption;
 };
 
 export type RecordsWriteMessage = {
@@ -62,31 +60,7 @@ export type RecordsWriteMessage = {
   contextId?: string;
   descriptor: RecordsWriteDescriptor;
   attestation?: GeneralJws;
-  encryption?: EncryptionProperty;
-};
-
-export type EncryptionProperty = {
-  algorithm: EncryptionAlgorithm;
-  initializationVector: string;
-  keyEncryption: EncryptedKey[]
-};
-
-export type EncryptedKey = {
-  /**
-   * The fully qualified key ID (e.g. did:example:abc#encryption-key-id) of the root public key used to encrypt the symmetric encryption key.
-   */
-  rootKeyId: string;
-
-  /**
-   * The actual derived public key.
-   */
-  derivedPublicKey?: PublicKeyJwk;
-  derivationScheme: KeyDerivationScheme;
-  algorithm: EncryptionAlgorithm;
-  initializationVector: string;
-  ephemeralPublicKey: PublicKeyJwk;
-  messageAuthenticationCode: string;
-  encryptedKey: string;
+  encryption?: JweEncryption;
 };
 
 /**
@@ -146,6 +120,8 @@ export type RecordsSubscribeDescriptor = {
   method: DwnMethodName.Subscribe;
   messageTimestamp: string;
   filter: RecordsFilter;
+  dateSort?: DateSort;
+  pagination?: Pagination;
 };
 
 export type RecordsFilter = {
@@ -212,6 +188,8 @@ export type RecordsSubscribeMessage = GenericMessage & {
 
 export type RecordsSubscribeReply = GenericMessageReply & {
   subscription?: MessageSubscription;
+  entries?: RecordsQueryReplyEntry[];
+  cursor?: PaginationCursor;
 };
 
 export type RecordsReadMessage = {