@enbox/dwn-sdk-js 0.0.1

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

@@ -0,0 +1,58 @@
+import * as Ed25519 from '@noble/ed25519';
+import type { PrivateJwk, PublicJwk, 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') {
+    throw new DwnError(DwnErrorCode.Ed25519InvalidJwk, 'invalid jwk. kty MUST be OKP. crv MUST be Ed25519');
+  }
+}
+
+function publicKeyToJwk(publicKeyBytes: Uint8Array): PublicJwk {
+  const x = Encoder.bytesToBase64Url(publicKeyBytes);
+
+  const publicJwk: PublicJwk = {
+    alg : 'EdDSA',
+    kty : 'OKP',
+    crv : 'Ed25519',
+    x
+  };
+
+  return publicJwk;
+}
+
+export const ed25519: SignatureAlgorithm = {
+  sign: async (content: Uint8Array, privateJwk: PrivateJwk): Promise<Uint8Array> => {
+    validateKey(privateJwk);
+
+    const privateKeyBytes = Encoder.base64UrlToBytes(privateJwk.d);
+
+    return Ed25519.signAsync(content, privateKeyBytes);
+  },
+
+  verify: async (content: Uint8Array, signature: Uint8Array, publicJwk: PublicJwk): Promise<boolean> => {
+    validateKey(publicJwk);
+
+    const publicKeyBytes = Encoder.base64UrlToBytes(publicJwk.x);
+
+    return Ed25519.verifyAsync(signature, content, publicKeyBytes);
+  },
+
+  generateKeyPair: async (): Promise<{publicJwk: PublicJwk, privateJwk: PrivateJwk}> => {
+    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 };
+
+    return { publicJwk, privateJwk };
+  },
+
+  publicKeyToJwk: async (publicKeyBytes: Uint8Array): Promise<PublicJwk> => {
+    return publicKeyToJwk(publicKeyBytes);
+  }
+};

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

@@ -0,0 +1,22 @@
+import type { SignatureAlgorithm } from '../../../types/jose-types.js';
+
+import { ed25519 } from './ed25519.js';
+import { Secp256k1 } from '../../../utils/secp256k1.js';
+import { Secp256r1 } from '../../../utils/secp256r1.js';
+
+// the key should be the appropriate `crv` value
+export const signatureAlgorithms: Record<string, SignatureAlgorithm> = {
+  'Ed25519'   : ed25519,
+  'secp256k1' : {
+    sign            : Secp256k1.sign,
+    verify          : Secp256k1.verify,
+    generateKeyPair : Secp256k1.generateKeyPair,
+    publicKeyToJwk  : Secp256k1.publicKeyToJwk
+  },
+  'P-256': {
+    sign            : Secp256r1.sign,
+    verify          : Secp256r1.verify,
+    generateKeyPair : Secp256r1.generateKeyPair,
+    publicKeyToJwk  : Secp256r1.publicKeyToJwk,
+  },
+};

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

@@ -0,0 +1,48 @@
+import type { GeneralJws } from '../../../types/jws-types.js';
+import type { Signer } from '../../../types/signer.js';
+
+import { Encoder } from '../../../utils/encoder.js';
+
+export class GeneralJwsBuilder {
+  private jws: GeneralJws;
+
+  private constructor(jws: GeneralJws) {
+    this.jws = jws;
+  }
+
+  static async create(payload: Uint8Array, signers: Signer[] = []): Promise<GeneralJwsBuilder> {
+    const jws: GeneralJws = {
+      payload    : Encoder.bytesToBase64Url(payload),
+      signatures : []
+    };
+
+    const builder = new GeneralJwsBuilder(jws);
+
+    for (const signer of signers) {
+      await builder.addSignature(signer);
+    }
+
+    return builder;
+  }
+
+  async addSignature(signer: Signer): Promise<void> {
+    const protectedHeader = {
+      kid : signer.keyId,
+      alg : signer.algorithm
+    };
+    const protectedHeaderString = JSON.stringify(protectedHeader);
+    const protectedHeaderBase64UrlString = Encoder.stringToBase64Url(protectedHeaderString);
+
+    const signingInputString = `${protectedHeaderBase64UrlString}.${this.jws.payload}`;
+    const signingInputBytes = Encoder.stringToBytes(signingInputString);
+
+    const signatureBytes = await signer.sign(signingInputBytes);
+    const signature = Encoder.bytesToBase64Url(signatureBytes);
+
+    this.jws.signatures.push({ protected: protectedHeaderBase64UrlString, signature });
+  }
+
+  getJws(): GeneralJws {
+    return this.jws;
+  }
+}

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

@@ -0,0 +1,112 @@
+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 { DidResolver, DidVerificationMethod } from '@enbox/dids';
+
+import { Jws } from '../../../utils/jws.js';
+import { MemoryCache } from '../../../utils/memory-cache.js';
+import { validateJsonSchema } from '../../../schema-validator.js';
+import { DwnError, DwnErrorCode } from '../../../core/dwn-error.js';
+
+type VerificationResult = {
+  /** DIDs of all signers */
+  signers: string[];
+};
+
+/**
+ * Verifies the signature(s) of a General JWS.
+ */
+export class GeneralJwsVerifier {
+
+  private static _singleton: GeneralJwsVerifier;
+
+  cache: Cache;
+
+  private constructor(cache?: Cache) {
+    this.cache = cache || new MemoryCache(600);
+  }
+
+  private static get singleton(): GeneralJwsVerifier {
+    if (GeneralJwsVerifier._singleton === undefined) {
+      GeneralJwsVerifier._singleton = new GeneralJwsVerifier();
+    }
+
+    return GeneralJwsVerifier._singleton;
+  }
+
+  /**
+   * Verifies the signatures of the given General JWS.
+   * @returns the list of signers that have valid signatures.
+   */
+  public static async verifySignatures(jws: GeneralJws, didResolver: DidResolver): Promise<VerificationResult> {
+    return await GeneralJwsVerifier.singleton.verifySignatures(jws, didResolver);
+  }
+
+  /**
+   * Verifies the signatures of the given General JWS.
+   * @returns the list of signers that have valid signatures.
+   */
+  public async verifySignatures(jws: GeneralJws, didResolver: DidResolver): Promise<VerificationResult> {
+    const signers: string[] = [];
+
+    for (const signatureEntry of jws.signatures) {
+      let isVerified: boolean;
+      const kid = Jws.getKid(signatureEntry);
+
+      const cacheKey = `${signatureEntry.protected}.${jws.payload}.${signatureEntry.signature}`;
+      const cachedValue = await this.cache.get(cacheKey);
+
+      // explicit `undefined` check to differentiate `false`
+      if (cachedValue === undefined) {
+        const publicJwk = await GeneralJwsVerifier.getPublicKey(kid, didResolver);
+        isVerified = await Jws.verifySignature(jws.payload, signatureEntry, publicJwk);
+        await this.cache.set(cacheKey, isVerified);
+      } else {
+        isVerified = cachedValue;
+      }
+
+      const did = Jws.extractDid(kid);
+
+      if (isVerified) {
+        signers.push(did);
+      } else {
+        throw new DwnError(DwnErrorCode.GeneralJwsVerifierInvalidSignature, `Signature verification failed for ${did}`);
+      }
+    }
+
+    return { signers };
+  }
+
+  /**
+   * 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> {
+    // `resolve` throws exception if DID is invalid, DID method is not supported,
+    // or resolving DID fails
+    const did = Jws.extractDid(kid);
+    const { didDocument } = await didResolver.resolve(did);
+    const { verificationMethod: verificationMethods = [] } = didDocument || {};
+
+    let verificationMethod: DidVerificationMethod | undefined;
+
+    for (const method of verificationMethods) {
+      // consider optimizing using a set for O(1) lookups if needed
+      // key ID in DID Document may or may not be fully qualified. e.g.
+      // `did:ion:alice#key1` or `#key1`
+      if (kid.endsWith(method.id)) {
+        verificationMethod = method;
+        break;
+      }
+    }
+
+    if (!verificationMethod) {
+      throw new DwnError(DwnErrorCode.GeneralJwsVerifierGetPublicKeyNotFound, 'public key needed to verify signature not found in DID Document');
+    }
+
+    validateJsonSchema('JwkVerificationMethod', verificationMethod);
+
+    const { publicKeyJwk: publicJwk } = verificationMethod;
+
+    return publicJwk as PublicJwk;
+  }
+}

package/src/protocols/permission-grant.ts

@@ -0,0 +1,86 @@
+import type { DataEncodedRecordsWriteMessage } from '../types/records-types.js';
+import type { PermissionConditions, PermissionGrantData, PermissionScope } from '../types/permission-types.js';
+
+import { Encoder } from '../utils/encoder.js';
+import { Message } from '../core/message.js';
+
+
+/**
+ * A class representing a Permission Grant for a more convenient abstraction.
+ */
+export class PermissionGrant {
+
+  /**
+   * The ID of the permission grant, which is the record ID DWN message.
+   */
+  public readonly id: string;
+
+  /**
+   * The grantor of the permission.
+   */
+  public readonly grantor: string;
+
+  /**
+   * The grantee of the permission.
+   */
+  public readonly grantee: string;
+
+  /**
+   * The date at which the grant was given.
+   */
+  public readonly dateGranted: string;
+
+  /**
+   * Optional string that communicates what the grant would be used for
+   */
+  public readonly description?: string;
+
+  /**
+   * Optional CID of a permission request. This is optional because grants may be given without being officially requested
+   */
+  public readonly requestId?: string;
+
+  /**
+   * Timestamp at which this grant will no longer be active.
+   */
+  public readonly dateExpires: string;
+
+  /**
+   * Whether this grant is delegated or not. If `true`, the `grantedTo` will be able to act as the `grantedTo` within the scope of this grant.
+   */
+  public readonly delegated?: boolean;
+
+  /**
+   * The scope of the allowed access.
+   */
+  public readonly scope: PermissionScope;
+
+  /**
+   * Optional conditions that must be met when the grant is used.
+   */
+  public readonly conditions?: PermissionConditions;
+
+  public static async parse(message: DataEncodedRecordsWriteMessage): Promise<PermissionGrant> {
+    const permissionGrant = new PermissionGrant(message);
+    return permissionGrant;
+  }
+
+  private constructor(message: DataEncodedRecordsWriteMessage) {
+    // properties derived from the generic DWN message properties
+    this.id = message.recordId;
+    this.grantor = Message.getSigner(message)!;
+    this.grantee = message.descriptor.recipient!;
+    this.dateGranted = message.descriptor.dateCreated;
+
+    // properties from the data payload itself.
+    const permissionGrantEncoded = message.encodedData;
+    const permissionGrant = Encoder.base64UrlToObject(permissionGrantEncoded) as PermissionGrantData;
+    this.dateExpires = permissionGrant.dateExpires;
+    this.delegated = permissionGrant.delegated;
+    this.description = permissionGrant.description;
+    this.requestId = permissionGrant.requestId;
+    this.scope = permissionGrant.scope;
+    this.conditions = permissionGrant.conditions;
+  }
+}
+

package/src/protocols/permission-request.ts

@@ -0,0 +1,63 @@
+import type { DataEncodedRecordsWriteMessage } from '../types/records-types.js';
+import type { PermissionConditions, PermissionRequestData, PermissionScope } from '../types/permission-types.js';
+
+import { Encoder } from '../utils/encoder.js';
+import { Message } from '../core/message.js';
+
+
+/**
+ * A class representing a Permission Request for a more convenient abstraction.
+ */
+export class PermissionRequest {
+
+  /**
+   * The ID of the permission request, which is the record ID DWN message.
+   */
+  public readonly id: string;
+
+  /**
+   * The requester for of the permission.
+   */
+  public readonly requester: string;
+
+  /**
+   * Optional string that communicates what the requested grant would be used for.
+   */
+  public readonly description?: string;
+
+  /**
+   * Whether the requested grant is delegated or not.
+   * If `true`, the `requestor` will be able to act as the grantor of the permission within the scope of the requested grant.
+   */
+  public readonly delegated?: boolean;
+
+  /**
+   * The scope of the allowed access.
+   */
+  public readonly scope: PermissionScope;
+
+  /**
+   * Optional conditions that must be met when the requested grant is used.
+   */
+  public readonly conditions?: PermissionConditions;
+
+  public static async parse(message: DataEncodedRecordsWriteMessage): Promise<PermissionRequest> {
+    const permissionRequest = new PermissionRequest(message);
+    return permissionRequest;
+  }
+
+  private constructor(message: DataEncodedRecordsWriteMessage) {
+    // properties derived from the generic DWN message properties
+    this.id = message.recordId;
+    this.requester = Message.getSigner(message)!;
+
+    // properties from the data payload itself.
+    const permissionRequestEncodedData = message.encodedData;
+    const permissionRequestData = Encoder.base64UrlToObject(permissionRequestEncodedData) as PermissionRequestData;
+    this.delegated = permissionRequestData.delegated;
+    this.description = permissionRequestData.description;
+    this.scope = permissionRequestData.scope;
+    this.conditions = permissionRequestData.conditions;
+  }
+}
+