@enbox/dwn-sdk-js 0.0.2 → 0.0.3

package/src/interfaces/records-write.ts

@@ -1,9 +1,9 @@
 import type { GeneralJws } from '../types/jws-types.js';
 import type { KeyValues } from '../types/query-types.js';
 import type { MessageInterface } from '../types/message-interface.js';
+import type { MessageSigner } from '../types/signer.js';
 import type { MessageStore } from '../types/message-store.js';
-import type { PublicJwk } from '../types/jose-types.js';
-import type { Signer } from '../types/signer.js';
+import type { PublicKeyJwk } from '../types/jose-types.js';
 import type {
   DataEncodedRecordsWriteMessage,
   EncryptedKey,
@@ -62,20 +62,31 @@ export type RecordsWriteOptions = {
   /**
    * The signer of the message, which is commonly the author, but can also be a delegate.
    */
-  signer?: Signer;
+  signer?: MessageSigner;
 
   /**
    * The delegated grant invoked to sign on behalf of the logical author, which is the grantor of the delegated grant.
    */
   delegatedGrant?: DataEncodedRecordsWriteMessage;
 
-  attestationSigners?: Signer[];
+  attestationSigners?: MessageSigner[];
   encryptionInput?: EncryptionInput;
   permissionGrantId?: string;
+
+  /**
+   * The author's ProtocolPath-derived public key for key delivery.
+   * When set, this is attached to the authorization model so the DWN owner
+   * can encrypt context keys back to the author without querying the
+   * author's DWN.
+   */
+  authorKeyDeliveryPublicKey?: {
+    rootKeyId: string;
+    publicKeyJwk: PublicKeyJwk;
+  };
 };
 
 /**
- * Input that describes how data is encrypted as spec-ed in TP18 (https://github.com/TBD54566975/technical-proposals/pull/6).
+ * Input that describes how data is encrypted as spec-ed in TP18.
  */
 export type EncryptionInput = {
   /**
@@ -118,7 +129,7 @@ export type KeyEncryptionInput = {
   /**
    * Public key to be used to encrypt the symmetric key.
    */
-  publicKey: PublicJwk;
+  publicKey: PublicKeyJwk;
 
   /**
    * Algorithm used for encrypting the symmetric key. Uses {EncryptionAlgorithm.EciesSecp256k1} if not given.
@@ -144,14 +155,14 @@ export type CreateFromOptions = {
   /**
    * The signer of the message, which is commonly the author, but can also be a delegate.
    */
-  signer?: Signer;
+  signer?: MessageSigner;
 
   /**
    * The delegated grant to sign on behalf of the logical author, which is the grantor (`grantedBy`) of the delegated grant.
    */
   delegatedGrant?: DataEncodedRecordsWriteMessage;
 
-  attestationSigners?: Signer[];
+  attestationSigners?: MessageSigner[];
   encryptionInput?: EncryptionInput;
   protocolRole?: string;
 };
@@ -280,6 +291,14 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
     // Make a copy so that the stored copy is not subject to external, unexpected modification.
     const message = JSON.parse(JSON.stringify(recordsWriteMessage)) as RecordsWriteMessage;
 
+    // Validate the message against the JSON schema.
+    // We strip internal properties that the MessageStore may attach to stored messages
+    // but are not part of the RecordsWrite JSON schema:
+    //   - `encodedData`:  base64url-encoded payload for small records
+    //   - `initialWrite`: the initial RecordsWrite when this message is an update
+    const { encodedData: _, initialWrite: __, ...messageToValidate } = message as RecordsWriteMessage & Record<string, unknown>;
+    Message.validateJsonSchema(messageToValidate);
+
     // asynchronous checks that are required by the constructor to initialize members properly
 
     await Message.validateSignatureStructure(message.authorization.signature, message.descriptor, 'RecordsWriteSignaturePayload');
@@ -335,21 +354,22 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
     const currentTime = Time.getCurrentTimestamp();
 
     const descriptor: RecordsWriteDescriptor = {
-      interface        : DwnInterfaceName.Records,
-      method           : DwnMethodName.Write,
-      protocol         : options.protocol !== undefined ? normalizeProtocolUrl(options.protocol) : undefined,
-      protocolPath     : options.protocolPath,
-      recipient        : options.recipient,
-      schema           : options.schema !== undefined ? normalizeSchemaUrl(options.schema) : undefined,
-      tags             : options.tags,
-      parentId         : RecordsWrite.getRecordIdFromContextId(options.parentContextId),
+      interface         : DwnInterfaceName.Records,
+      method            : DwnMethodName.Write,
+      protocol          : options.protocol !== undefined ? normalizeProtocolUrl(options.protocol) : undefined,
+      protocolPath      : options.protocolPath,
+      recipient         : options.recipient,
+      schema            : options.schema !== undefined ? normalizeSchemaUrl(options.schema) : undefined,
+      tags              : options.tags,
+      parentId          : RecordsWrite.getRecordIdFromContextId(options.parentContextId),
       dataCid,
       dataSize,
-      dateCreated      : options.dateCreated ?? currentTime,
-      messageTimestamp : options.messageTimestamp ?? currentTime,
-      published        : options.published,
-      datePublished    : options.datePublished,
-      dataFormat       : options.dataFormat
+      dateCreated       : options.dateCreated ?? currentTime,
+      messageTimestamp  : options.messageTimestamp ?? currentTime,
+      published         : options.published,
+      datePublished     : options.datePublished,
+      dataFormat        : options.dataFormat,
+      permissionGrantId : options.permissionGrantId,
     };
 
     // generate `datePublished` if the message is to be published but `datePublished` is not given
@@ -385,10 +405,11 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
 
     if (options.signer !== undefined) {
       await recordsWrite.sign({
-        signer            : options.signer,
-        delegatedGrant    : options.delegatedGrant,
-        permissionGrantId : options.permissionGrantId,
-        protocolRole      : options.protocolRole
+        signer                     : options.signer,
+        delegatedGrant             : options.delegatedGrant,
+        permissionGrantId          : options.permissionGrantId,
+        protocolRole               : options.protocolRole,
+        authorKeyDeliveryPublicKey : options.authorKeyDeliveryPublicKey,
       });
     }
 
@@ -477,26 +498,65 @@ 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
+   *   `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
+   *   ProtocolPath entry so both the owner and context key holders can decrypt.
    */
-  public async encryptSymmetricEncryptionKey(encryptionInput: EncryptionInput): Promise<void> {
-    this._message.encryption = await RecordsWrite.createEncryptionProperty(this._message.descriptor, encryptionInput);
+  public async encryptSymmetricEncryptionKey(
+    encryptionInput: EncryptionInput,
+    options?: { append?: boolean },
+  ): Promise<void> {
+    if (options?.append) {
+      if (!this._message.encryption) {
+        throw new DwnError(
+          DwnErrorCode.RecordsWriteMissingEncryption,
+          'Cannot append keyEncryption entries: record does not have an existing `encryption` property.'
+        );
+      }
 
-    // opportunity here to re-sign instead of remove
-    delete this._message.authorization;
-    this._signaturePayload = undefined;
-    this._author = undefined;
+      // Build only the new keyEncryption entries (reuses createEncryptionProperty for ECIES logic)
+      const newEncryption = await RecordsWrite.createEncryptionProperty(this._message.descriptor, encryptionInput);
+      if (newEncryption) {
+        this._message.encryption.keyEncryption.push(...newEncryption.keyEncryption);
+      }
+
+      // 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
+      // updated state. validateIntegrity() skips the encryptionCid check on
+      // the author's signature when an ownerSignature is present.
+      //
+      // NOTE: An alternative design would deliver the DEK out-of-band via the
+      // key-delivery protocol (as a field on the contextKey record) instead of
+      // mutating the record's encryption property. That avoids the stale
+      // encryptionCid issue entirely but adds complexity to the read path and
+      // the contextKey schema. We chose the in-record approach because it keeps
+      // records self-contained and the read/decrypt path unchanged.
+    } else {
+      this._message.encryption = await RecordsWrite.createEncryptionProperty(this._message.descriptor, encryptionInput);
+
+      // Full replacement invalidates the authorization — caller must re-sign.
+      delete this._message.authorization;
+      this._signaturePayload = undefined;
+      this._author = undefined;
+    }
   }
 
   /**
    * Signs the RecordsWrite, the signer is commonly the author, but can also be a delegate.
    */
   public async sign(options: {
-    signer: Signer,
+    signer: MessageSigner,
     delegatedGrant?: DataEncodedRecordsWriteMessage,
     permissionGrantId?: string,
-    protocolRole?: string
+    protocolRole?: string,
+    authorKeyDeliveryPublicKey?: { rootKeyId: string; publicKeyJwk: PublicKeyJwk },
   }): Promise<void> {
-    const { signer, delegatedGrant, permissionGrantId, protocolRole } = options;
+    const { signer, delegatedGrant, permissionGrantId, protocolRole, authorKeyDeliveryPublicKey } = options;
 
     // compute delegated grant ID and author if delegated grant is given
     let delegatedGrantId;
@@ -545,6 +605,10 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
       this._message.authorization.authorDelegatedGrant = delegatedGrant;
     }
 
+    if (authorKeyDeliveryPublicKey !== undefined) {
+      this._message.authorization.authorKeyDeliveryPublicKey = authorKeyDeliveryPublicKey;
+    }
+
     // there is opportunity to optimize here as the payload is constructed within `createAuthorization(...)`
     this._signaturePayload = Jws.decodePlainObjectPayload(signature);
     this._author = authorDid;
@@ -555,7 +619,7 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
    * This is used when the DWN owner wants to retain a copy of a message that the owner did not author.
    * NOTE: requires the `RecordsWrite` to already have the author's signature.
    */
-  public async signAsOwner(signer: Signer): Promise<void> {
+  public async signAsOwner(signer: MessageSigner): Promise<void> {
     if (this._author === undefined) {
       throw new DwnError(
         DwnErrorCode.RecordsWriteSignAsOwnerUnknownAuthor,
@@ -577,7 +641,7 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
    * This is used when a DWN owner-delegate wants to retain a copy of a message that the owner did not author.
    * NOTE: requires the `RecordsWrite` to already have the author's signature.
    */
-  public async signAsOwnerDelegate(signer: Signer, delegatedGrant: DataEncodedRecordsWriteMessage): Promise<void> {
+  public async signAsOwnerDelegate(signer: MessageSigner, delegatedGrant: DataEncodedRecordsWriteMessage): Promise<void> {
     if (this._author === undefined) {
       throw new DwnError(
         DwnErrorCode.RecordsWriteSignAsOwnerDelegateUnknownAuthor,
@@ -661,8 +725,14 @@ 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
-    if (signaturePayload.encryptionCid !== undefined) {
+    // 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
+    // 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.
+    const hasOwnerSignature = this.message.authorization?.ownerSignature !== undefined;
+    if (signaturePayload.encryptionCid !== undefined && !hasOwnerSignature) {
       const expectedEncryptionCid = await Cid.computeCid(this.message.encryption);
       const actualEncryptionCid = signaturePayload.encryptionCid;
       if (actualEncryptionCid !== expectedEncryptionCid) {
@@ -696,7 +766,7 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
       return;
     }
 
-    // TODO: multi-attesters to be unblocked by #205 - Revisit database interfaces (https://github.com/TBD54566975/dwn-sdk-js/issues/205)
+    // TODO: multi-attesters to be unblocked by #205 - Revisit database interfaces (https://github.com/enboxorg/enbox/issues/205)
     if (message.attestation.signatures.length !== 1) {
       throw new DwnError(
         DwnErrorCode.RecordsWriteAttestationIntegrityMoreThanOneSignature,
@@ -742,8 +812,7 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
       throw new DwnError(DwnErrorCode.RecordsWriteGetEntryIdUndefinedAuthor, 'Property `author` is needed to compute entry ID.');
     }
 
-    const entryIdInput = { ...descriptor };
-    (entryIdInput as any).author = author;
+    const entryIdInput: Record<string, unknown> = { ...descriptor, author };
 
     const cid = await Cid.computeCid(entryIdInput);
     return cid;
@@ -783,7 +852,7 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
     }
 
     // add additional indexes to optional values if given
-    // TODO: index multi-attesters to be unblocked by #205 - Revisit database interfaces (https://github.com/TBD54566975/dwn-sdk-js/issues/205)
+    // TODO: index multi-attesters to be unblocked by #205 - Revisit database interfaces (https://github.com/enboxorg/enbox/issues/205)
     if (this.attesters.length > 0) { indexes.attester = this.attesters[0]; }
     if (message.contextId !== undefined) { indexes.contextId = message.contextId; }
 
@@ -907,7 +976,7 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
   /**
    * Creates the `attestation` property of a RecordsWrite message if given signature inputs; returns `undefined` otherwise.
    */
-  public static async createAttestation(descriptorCid: string, signers?: Signer[]): Promise<GeneralJws | undefined> {
+  public static async createAttestation(descriptorCid: string, signers?: MessageSigner[]): Promise<GeneralJws | undefined> {
     if (signers === undefined || signers.length === 0) {
       return undefined;
     }
@@ -928,7 +997,7 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
     descriptorCid: string,
     attestation: GeneralJws | undefined,
     encryption: EncryptionProperty | undefined,
-    signer: Signer,
+    signer: MessageSigner,
     delegatedGrantId?: string,
     permissionGrantId?: string,
     protocolRole?: string
@@ -988,8 +1057,8 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
     for (const descriptorPropertyName of descriptorPropertyNames) {
       // if property is supposed to be immutable
       if (mutableDescriptorProperties.indexOf(descriptorPropertyName) === -1) {
-        const valueInExistingWrite = (existingWriteMessage.descriptor as any)[descriptorPropertyName];
-        const valueInNewMessage = (newMessage.descriptor as any)[descriptorPropertyName];
+        const valueInExistingWrite = (existingWriteMessage.descriptor as Record<string, unknown>)[descriptorPropertyName];
+        const valueInNewMessage = (newMessage.descriptor as Record<string, unknown>)[descriptorPropertyName];
         if (valueInNewMessage !== valueInExistingWrite) {
           throw new DwnError(
             DwnErrorCode.RecordsWriteImmutablePropertyChanged,

package/src/jose/algorithms/signing/ed25519.ts

@@ -1,19 +1,20 @@
 import * as Ed25519 from '@noble/ed25519';
-import type { PrivateJwk, PublicJwk, SignatureAlgorithm } from '../../../types/jose-types.js';
+import type { JwkParamsOkpPrivate, JwkParamsOkpPublic } from '@enbox/crypto';
+import type { PrivateKeyJwk, PublicKeyJwk, SignatureAlgorithm } from '../../../types/jose-types.js';
 
 import { Encoder } from '../../../utils/encoder.js';
 import { DwnError, DwnErrorCode } from '../../../core/dwn-error.js';
 
-function validateKey(jwk: PrivateJwk | PublicJwk): void {
-  if (jwk.kty !== 'OKP' || jwk.crv !== 'Ed25519') {
+function validateKey(jwk: PrivateKeyJwk | PublicKeyJwk): void {
+  if (jwk.kty !== 'OKP' || (jwk as JwkParamsOkpPublic).crv !== 'Ed25519') {
     throw new DwnError(DwnErrorCode.Ed25519InvalidJwk, 'invalid jwk. kty MUST be OKP. crv MUST be Ed25519');
   }
 }
 
-function publicKeyToJwk(publicKeyBytes: Uint8Array): PublicJwk {
+function publicKeyToJwk(publicKeyBytes: Uint8Array): PublicKeyJwk {
   const x = Encoder.bytesToBase64Url(publicKeyBytes);
 
-  const publicJwk: PublicJwk = {
+  const publicJwk: PublicKeyJwk = {
     alg : 'EdDSA',
     kty : 'OKP',
     crv : 'Ed25519',
@@ -24,35 +25,35 @@ function publicKeyToJwk(publicKeyBytes: Uint8Array): PublicJwk {
 }
 
 export const ed25519: SignatureAlgorithm = {
-  sign: async (content: Uint8Array, privateJwk: PrivateJwk): Promise<Uint8Array> => {
+  sign: async (content: Uint8Array, privateJwk: PrivateKeyJwk): Promise<Uint8Array> => {
     validateKey(privateJwk);
 
-    const privateKeyBytes = Encoder.base64UrlToBytes(privateJwk.d);
+    const privateKeyBytes = Encoder.base64UrlToBytes((privateJwk as JwkParamsOkpPrivate).d);
 
     return Ed25519.signAsync(content, privateKeyBytes);
   },
 
-  verify: async (content: Uint8Array, signature: Uint8Array, publicJwk: PublicJwk): Promise<boolean> => {
+  verify: async (content: Uint8Array, signature: Uint8Array, publicJwk: PublicKeyJwk): Promise<boolean> => {
     validateKey(publicJwk);
 
-    const publicKeyBytes = Encoder.base64UrlToBytes(publicJwk.x);
+    const publicKeyBytes = Encoder.base64UrlToBytes((publicJwk as JwkParamsOkpPublic).x);
 
     return Ed25519.verifyAsync(signature, content, publicKeyBytes);
   },
 
-  generateKeyPair: async (): Promise<{publicJwk: PublicJwk, privateJwk: PrivateJwk}> => {
+  generateKeyPair: async (): Promise<{publicJwk: PublicKeyJwk, privateJwk: PrivateKeyJwk}> => {
     const privateKeyBytes = Ed25519.utils.randomPrivateKey();
     const publicKeyBytes = await Ed25519.getPublicKeyAsync(privateKeyBytes);
 
     const d = Encoder.bytesToBase64Url(privateKeyBytes);
 
     const publicJwk = publicKeyToJwk(publicKeyBytes);
-    const privateJwk: PrivateJwk = { ...publicJwk, d };
+    const privateJwk: PrivateKeyJwk = { ...publicJwk, d };
 
     return { publicJwk, privateJwk };
   },
 
-  publicKeyToJwk: async (publicKeyBytes: Uint8Array): Promise<PublicJwk> => {
+  publicKeyToJwk: async (publicKeyBytes: Uint8Array): Promise<PublicKeyJwk> => {
     return publicKeyToJwk(publicKeyBytes);
   }
 };

package/src/jose/algorithms/signing/signature-algorithms.ts

@@ -4,8 +4,13 @@ import { ed25519 } from './ed25519.js';
 import { Secp256k1 } from '../../../utils/secp256k1.js';
 import { Secp256r1 } from '../../../utils/secp256r1.js';
 
+/**
+ * Curves supported by the DWN for signing and verification.
+ */
+export type SupportedCurve = 'Ed25519' | 'secp256k1' | 'P-256';
+
 // the key should be the appropriate `crv` value
-export const signatureAlgorithms: Record<string, SignatureAlgorithm> = {
+export const signatureAlgorithms: Record<SupportedCurve, SignatureAlgorithm> = {
   'Ed25519'   : ed25519,
   'secp256k1' : {
     sign            : Secp256k1.sign,

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

@@ -1,5 +1,5 @@
 import type { GeneralJws } from '../../../types/jws-types.js';
-import type { Signer } from '../../../types/signer.js';
+import type { MessageSigner } from '../../../types/signer.js';
 
 import { Encoder } from '../../../utils/encoder.js';
 
@@ -10,7 +10,7 @@ export class GeneralJwsBuilder {
     this.jws = jws;
   }
 
-  static async create(payload: Uint8Array, signers: Signer[] = []): Promise<GeneralJwsBuilder> {
+  static async create(payload: Uint8Array, signers: MessageSigner[] = []): Promise<GeneralJwsBuilder> {
     const jws: GeneralJws = {
       payload    : Encoder.bytesToBase64Url(payload),
       signatures : []
@@ -25,7 +25,7 @@ export class GeneralJwsBuilder {
     return builder;
   }
 
-  async addSignature(signer: Signer): Promise<void> {
+  async addSignature(signer: MessageSigner): Promise<void> {
     const protectedHeader = {
       kid : signer.keyId,
       alg : signer.algorithm

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

@@ -1,6 +1,6 @@
 import type { Cache } from '../../../types/cache.js';
 import type { GeneralJws } from '../../../types/jws-types.js';
-import type { PublicJwk } from '../../../types/jose-types.js';
+import type { PublicKeyJwk } from '../../../types/jose-types.js';
 import type { DidResolver, DidVerificationMethod } from '@enbox/dids';
 
 import { Jws } from '../../../utils/jws.js';
@@ -80,7 +80,7 @@ export class GeneralJwsVerifier {
   /**
    * Gets the public key given a fully qualified key ID (`kid`) by resolving the DID to its DID Document.
    */
-  private static async getPublicKey(kid: string, didResolver: DidResolver): Promise<PublicJwk> {
+  private static async getPublicKey(kid: string, didResolver: DidResolver): Promise<PublicKeyJwk> {
     // `resolve` throws exception if DID is invalid, DID method is not supported,
     // or resolving DID fails
     const did = Jws.extractDid(kid);
@@ -107,6 +107,6 @@ export class GeneralJwsVerifier {
 
     const { publicKeyJwk: publicJwk } = verificationMethod;
 
-    return publicJwk as PublicJwk;
+    return publicJwk as PublicKeyJwk;
   }
 }

package/src/protocols/permission-grant.ts

@@ -3,6 +3,7 @@ import type { PermissionConditions, PermissionGrantData, PermissionScope } from
 
 import { Encoder } from '../utils/encoder.js';
 import { Message } from '../core/message.js';
+import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
 
 
 /**
@@ -60,11 +61,61 @@ export class PermissionGrant {
    */
   public readonly conditions?: PermissionConditions;
 
+  /**
+   * Parses a `DataEncodedRecordsWriteMessage` into a `PermissionGrant`.
+   * Validates that the message contains required structural fields:
+   * `encodedData`, `authorization` (for grantor extraction), `descriptor.recipient` (grantee),
+   * and that the decoded data contains `scope` and `dateExpires`.
+   * @throws {DwnError} if any required field is missing.
+   */
   public static async parse(message: DataEncodedRecordsWriteMessage): Promise<PermissionGrant> {
+    PermissionGrant.validateMessage(message);
     const permissionGrant = new PermissionGrant(message);
     return permissionGrant;
   }
 
+  /**
+   * Validates that the message has the required structural fields for a permission grant.
+   */
+  private static validateMessage(message: DataEncodedRecordsWriteMessage): void {
+    if (message.encodedData === undefined || message.encodedData === null) {
+      throw new DwnError(
+        DwnErrorCode.PermissionGrantParseMissingEncodedData,
+        'permission grant message is missing encodedData'
+      );
+    }
+
+    if (Message.getSigner(message) === undefined) {
+      throw new DwnError(
+        DwnErrorCode.PermissionGrantParseMissingAuthorization,
+        'permission grant message is missing authorization (unable to extract grantor)'
+      );
+    }
+
+    if (message.descriptor.recipient === undefined) {
+      throw new DwnError(
+        DwnErrorCode.PermissionGrantParseMissingRecipient,
+        'permission grant message is missing descriptor.recipient (grantee)'
+      );
+    }
+
+    const grantData = Encoder.base64UrlToObject(message.encodedData) as Partial<PermissionGrantData>;
+
+    if (grantData.scope === undefined) {
+      throw new DwnError(
+        DwnErrorCode.PermissionGrantParseMissingScope,
+        'permission grant data is missing required property `scope`'
+      );
+    }
+
+    if (grantData.dateExpires === undefined) {
+      throw new DwnError(
+        DwnErrorCode.PermissionGrantParseMissingDateExpires,
+        'permission grant data is missing required property `dateExpires`'
+      );
+    }
+  }
+
   private constructor(message: DataEncodedRecordsWriteMessage) {
     // properties derived from the generic DWN message properties
     this.id = message.recordId;

package/src/protocols/permission-request.ts

@@ -3,6 +3,7 @@ import type { PermissionConditions, PermissionRequestData, PermissionScope } fro
 
 import { Encoder } from '../utils/encoder.js';
 import { Message } from '../core/message.js';
+import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
 
 
 /**
@@ -41,11 +42,47 @@ export class PermissionRequest {
    */
   public readonly conditions?: PermissionConditions;
 
+  /**
+   * Parses a `DataEncodedRecordsWriteMessage` into a `PermissionRequest`.
+   * Validates that the message contains required structural fields:
+   * `encodedData`, `authorization` (for requester extraction),
+   * and that the decoded data contains `scope`.
+   * @throws {DwnError} if any required field is missing.
+   */
   public static async parse(message: DataEncodedRecordsWriteMessage): Promise<PermissionRequest> {
+    PermissionRequest.validateMessage(message);
     const permissionRequest = new PermissionRequest(message);
     return permissionRequest;
   }
 
+  /**
+   * Validates that the message has the required structural fields for a permission request.
+   */
+  private static validateMessage(message: DataEncodedRecordsWriteMessage): void {
+    if (message.encodedData === undefined || message.encodedData === null) {
+      throw new DwnError(
+        DwnErrorCode.PermissionRequestParseMissingEncodedData,
+        'permission request message is missing encodedData'
+      );
+    }
+
+    if (Message.getSigner(message) === undefined) {
+      throw new DwnError(
+        DwnErrorCode.PermissionRequestParseMissingAuthorization,
+        'permission request message is missing authorization (unable to extract requester)'
+      );
+    }
+
+    const requestData = Encoder.base64UrlToObject(message.encodedData) as Partial<PermissionRequestData>;
+
+    if (requestData.scope === undefined) {
+      throw new DwnError(
+        DwnErrorCode.PermissionRequestParseMissingScope,
+        'permission request data is missing required property `scope`'
+      );
+    }
+  }
+
   private constructor(message: DataEncodedRecordsWriteMessage) {
     // properties derived from the generic DWN message properties
     this.id = message.recordId;

package/src/protocols/permissions.ts

@@ -1,7 +1,7 @@
 import type { GenericMessage } from '../types/message-types.js';
+import type { MessageSigner } from '../types/signer.js';
 import type { MessageStore } from '../types/message-store.js';
 import type { ProtocolDefinition } from '../types/protocols-types.js';
-import type { Signer } from '../types/signer.js';
 import type { DataEncodedRecordsWriteMessage, RecordsWriteMessage } from '../types/records-types.js';
 import type { PermissionConditions, PermissionGrantData, PermissionRequestData, PermissionRevocationData, PermissionScope, RecordsPermissionScope } from '../types/permission-types.js';
 
@@ -22,7 +22,7 @@ export type PermissionRequestCreateOptions = {
   /**
    * The signer of the request.
    */
-  signer?: Signer;
+  signer?: MessageSigner;
 
   dateRequested?: string;
 
@@ -41,7 +41,7 @@ export type PermissionGrantCreateOptions = {
   /**
    * The signer of the grant.
    */
-  signer?: Signer;
+  signer?: MessageSigner;
   grantedTo: string;
   dateGranted?: string;
 
@@ -65,7 +65,7 @@ export type PermissionRevocationCreateOptions = {
   /**
    * The signer of the grant.
    */
-  signer?: Signer;
+  signer?: MessageSigner;
   /**
    * The PermissionGrant this revocation is for.
    */
@@ -138,7 +138,7 @@ export class PermissionsProtocol {
           {
             who : 'recipient',
             of  : 'grant',
-            can : ['read', 'query']
+            can : ['read']
           }
         ],
         revocation: {

package/src/schema-validator.ts

@@ -1,15 +1,23 @@
 import * as precompiledValidators from '../generated/precompiled-validators.js';
 import { DwnError, DwnErrorCode } from './core/dwn-error.js';
 
+/** AJV-style validate function with an optional `errors` array after invocation. */
+interface ValidateError {
+  instancePath: string;
+  message: string;
+  keyword: string;
+  params: Record<string, unknown>;
+}
+type ValidateFn = ((payload: unknown) => boolean) & { errors?: ValidateError[] };
+
 /**
  * Validates the given payload using JSON schema keyed by the given schema name. Throws if the given payload fails validation.
  * @param schemaName the schema name use to look up the JSON schema to be used for schema validation.
  *                   The list of schema names can be found in compile-validators.js
  * @param payload javascript object to be validated
  */
-export function validateJsonSchema(schemaName: string, payload: any): void {
-  // const validateFn = validator.getSchema(schemaName);
-  const validateFn = (precompiledValidators as any)[schemaName];
+export function validateJsonSchema(schemaName: string, payload: unknown): void {
+  const validateFn = (precompiledValidators as Record<string, ValidateFn>)[schemaName];
 
   if (!validateFn) {
     throw new DwnError(DwnErrorCode.SchemaValidatorSchemaNotFound, `schema for ${schemaName} not found.`);