@enbox/dids 0.0.5 → 0.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enbox/dids",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "TBD DIDs library",
   "type": "module",
   "main": "./dist/esm/index.js",
@@ -16,7 +16,7 @@
     "test:node": "bun test tests/",
     "test:node:coverage": "bun test --coverage --coverage-reporter=text --coverage-reporter=lcov --coverage-dir=coverage tests/",
     "test:browser": "bunx --bun vitest --config vitest.browser.config.ts --run",
-    "test:browser:coverage": "bunx --bun vitest --config vitest.browser.config.ts --run --coverage --coverage.provider=istanbul --coverage.reportsDirectory=./coverage-browser"
+    "test:browser:coverage": "bunx --bun vitest --config vitest.browser.config.ts --run --coverage --coverage.provider=istanbul"
   },
   "homepage": "https://github.com/enboxorg/enbox/tree/main/packages/dids#readme",
   "bugs": "https://github.com/enboxorg/enbox/issues",
@@ -80,8 +80,8 @@
   "dependencies": {
     "@decentralized-identity/ion-sdk": "1.0.4",
     "@dnsquery/dns-packet": "6.1.1",
-    "@enbox/common": "0.0.3",
-    "@enbox/crypto": "0.0.4",
+    "@enbox/common": "0.0.5",
+    "@enbox/crypto": "0.0.6",
     "abstract-level": "1.0.4",
     "bencode": "4.0.0",
     "level": "8.0.1",

package/src/did.ts

@@ -145,6 +145,9 @@ export class Did {
     // Return null if the input string is empty or not provided.
     if (!didUri) {return null;}
 
+    // Guard against ReDoS: reject unreasonably long URIs before executing the regex.
+    if (didUri.length > 2048) {return null;}
+
     // Execute the regex pattern on the input string to extract URI components.
     const match = Did.DID_URI_PATTERN.exec(didUri);
 

package/src/methods/did-dht-pkarr.ts

@@ -44,7 +44,7 @@ export async function pkarrGet({ gatewayUri, publicKeyBytes }: {
   // Transmit the Get request to the DID DHT Gateway or Pkarr Relay and get the response.
   let response: Response;
   try {
-    response = await fetch(url, { method: 'GET' });
+    response = await fetch(url, { method: 'GET', signal: AbortSignal.timeout(30_000) });
 
     if (!response.ok) {
       throw new DidError(DidErrorCode.NotFound, `Pkarr record not found for: ${identifier}`);
@@ -113,7 +113,8 @@ export async function pkarrPut({ gatewayUri, bep44Message }: {
     response = await fetch(url, {
       method  : 'PUT',
       headers : { 'Content-Type': 'application/octet-stream' },
-      body
+      body,
+      signal  : AbortSignal.timeout(30_000),
     });
 
   } catch (error: any) {

package/src/methods/did-ion.ts

@@ -600,7 +600,8 @@ export class DidIon extends DidMethod {
         method  : 'POST',
         mode    : 'cors',
         headers : { 'Content-Type': 'application/json' },
-        body    : JSON.stringify(createOperation)
+        body    : JSON.stringify(createOperation),
+        signal  : AbortSignal.timeout(30_000),
       });
 
       // Return the result of processing the Create operation, including the updated DID metadata
@@ -681,7 +682,7 @@ export class DidIon extends DidMethod {
       });
 
       // Attempt to retrieve the DID document and metadata from the Sidetree node.
-      const response = await fetch(resolutionUrl);
+      const response = await fetch(resolutionUrl, { signal: AbortSignal.timeout(30_000) });
 
       // If the DID document was not found, return an error.
       if (!response.ok) {

package/src/methods/did-web.ts

@@ -4,6 +4,46 @@ import { Did } from '../did.js';
 import { DidMethod } from './did-method.js';
 import { EMPTY_DID_RESOLUTION_RESULT } from '../types/did-resolution.js';
 
+/** Default fetch timeout for DID document retrieval (30 seconds). */
+const FETCH_TIMEOUT_MS = 30_000;
+
+/**
+ * Returns `true` when the hostname is a private, loopback, or link-local
+ * address.  Used to block SSRF via crafted `did:web` identifiers such as
+ * `did:web:169.254.169.254` or `did:web:localhost`.
+ */
+function isPrivateHostname(hostname: string): boolean {
+  const h = hostname.toLowerCase();
+
+  if (h === 'localhost' || h === 'localhost.') { return true; }
+
+  // IPv4 literal check
+  const parts = h.split('.');
+  if (parts.length === 4) {
+    const octets = parts.map(Number);
+    if (octets.every((o) => !Number.isNaN(o) && o >= 0 && o <= 255)) {
+      const [a, b] = octets;
+      if (a === 10) { return true; } // 10.0.0.0/8
+      if (a === 172 && b >= 16 && b <= 31) { return true; } // 172.16.0.0/12
+      if (a === 192 && b === 168) { return true; } // 192.168.0.0/16
+      if (a === 127) { return true; } // 127.0.0.0/8
+      if (a === 169 && b === 254) { return true; } // 169.254.0.0/16
+      if (a === 0) { return true; } // 0.0.0.0/8
+    }
+  }
+
+  // IPv6 literal check (bracket-wrapped by URL parser)
+  let v6 = h;
+  if (v6.startsWith('[') && v6.endsWith(']')) { v6 = v6.slice(1, -1); }
+  if (v6.includes(':')) {
+    if (v6 === '::1' || v6 === '::' || v6 === '::0') { return true; }
+    if (v6.startsWith('fe80:') || v6.startsWith('fe80%')) { return true; }
+    if (v6.startsWith('fc') || v6.startsWith('fd')) { return true; }
+  }
+
+  return false;
+}
+
 /**
  * The `DidWeb` class provides an implementation of the `did:web` DID method.
  *
@@ -71,8 +111,19 @@ export class DidWeb extends DidMethod {
       `${baseUrl}/.well-known/did.json`;
 
     try {
+      // Block requests to private/loopback/link-local addresses (SSRF protection).
+      const parsedUrl = new URL(didDocumentUrl);
+      if (isPrivateHostname(parsedUrl.hostname)) {
+        return {
+          ...EMPTY_DID_RESOLUTION_RESULT,
+          didResolutionMetadata: { error: 'notFound' }
+        };
+      }
+
       // Perform an HTTP GET request to obtain the DID document.
-      const response = await fetch(didDocumentUrl);
+      const response = await fetch(didDocumentUrl, {
+        signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+      });
 
       // If the response status code is not 200, return an error.
       if (!response.ok) {throw new Error('HTTP error status code returned');}

package/src/utils.ts

@@ -19,38 +19,44 @@ import { DidError, DidErrorCode } from './did-error.js';
  * Represents a Decentralized Web Node (DWN) service in a DID Document.
  *
  * A DWN DID service is a specialized type of DID service with the `type` set to
- * `DecentralizedWebNode`. It includes specific properties `enc` and `sig` that are used to identify
- * the public keys that can be used to interact with the DID Subject. The values of these properties
- * are strings or arrays of strings containing one or more verification method `id` values present in
- * the same DID document. If the `enc` and/or `sig` properties are an array of strings, an entity
- * interacting with the DID subject is expected to use the verification methods in the order they
- * are listed.
+ * `DecentralizedWebNode`. Encryption and signing keys are resolved from the DID document's
+ * verification methods, not from the service entry.
+ *
+ * The `enc` and `sig` properties are optional legacy fields that may be present on existing
+ * DID documents for backward compatibility. When present, they contain verification method `id`
+ * values that hint at which keys to use for encryption and signing. New implementations should
+ * resolve keys from the DID document's verification methods by purpose (`keyAgreement` for
+ * encryption, `authentication`/`assertionMethod` for signing).
  *
  * @example
  * ```ts
  * const service: DwnDidService = {
  *   id: 'did:example:123#dwn',
  *   type: 'DecentralizedWebNode',
- *   serviceEndpoint: 'https://enbox-dwn.fly.dev',
- *   enc: 'did:example:123#key-1',
- *   sig: 'did:example:123#key-2'
+ *   serviceEndpoint: 'https://enbox-dwn.fly.dev'
  * }
  * ```
  *
- * @see {@link https://identity.foundation/decentralized-web-node/spec/ | DIF Decentralized Web Node (DWN) Specification}
+ * @see {@link https://github.com/enboxorg/dwn-spec | Enbox DWN Specification}
  */
 export interface DwnDidService extends DidService {
   /**
+   * @deprecated Optional legacy field. Resolve encryption keys from the DID document's
+   * `keyAgreement` verification methods instead.
+   *
    * One or more verification method `id` values that can be used to encrypt information
    * intended for the DID subject.
    */
   enc?: string | string[];
 
   /**
+   * @deprecated Optional legacy field. Resolve signing keys from the DID document's
+   * `authentication` or `assertionMethod` verification methods instead.
+   *
    * One or more verification method `id` values that will be used by the DID subject to sign data
    * or by another entity to verify signatures created by the DID subject.
    */
-  sig: string | string[];
+  sig?: string | string[];
 }
 
 /**
@@ -368,9 +374,11 @@ export function isDidService(obj: unknown): obj is DidService {
 /**
  * Checks if a given object is a {@link DwnDidService}.
  *
- * A {@link DwnDidService} is defined as {@link DidService} object with a `type` of
- * "DecentralizedWebNode" and `enc` and `sig` properties, where both properties are either strings
- * or arrays of strings.
+ * A {@link DwnDidService} is defined as a {@link DidService} object with a `type` of
+ * `"DecentralizedWebNode"`. The `enc` and `sig` properties are optional — they may be present
+ * on existing DID documents for backward compatibility, but are not required per the DWN
+ * specification. Encryption and signing keys are resolved from the DID document's verification
+ * methods, not from the service entry.
  *
  * @example
  * ```ts
@@ -382,33 +390,25 @@ export function isDidService(obj: unknown): obj is DidService {
  *       type: 'JsonWebKey2020',
  *       controller: 'did:example:123',
  *       publicKeyJwk: { ... }
- *     },
- *     {
- *       id: 'did:example:123#key-2',
- *       type: 'JsonWebKey2020',
- *       controller: 'did:example:123',
- *       publicKeyJwk: { ... }
  *     }
  *   ],
  *   service: [
  *     {
  *       id: 'did:example:123#dwn',
  *       type: 'DecentralizedWebNode',
- *       serviceEndpoint: 'https://enbox-dwn.fly.dev',
- *       enc: 'did:example:123#key-1',
- *       sig: 'did:example:123#key-2'
+ *       serviceEndpoint: 'https://enbox-dwn.fly.dev'
  *     }
  *   ]
  * };
  *
- * if (isDwnService(didDocument.service[0])) {
+ * if (isDwnDidService(didDocument.service[0])) {
  *   console.log('The object is a DwnDidService');
  * } else {
  *   console.log('The object is not a DwnDidService');
  * }
  * ```
  *
- * @see {@link https://identity.foundation/decentralized-web-node/spec/ | Decentralized Web Node (DWN) Specification}
+ * @see {@link https://github.com/enboxorg/dwn-spec | Enbox DWN Specification}
  *
  * @param obj - The object to be checked.
  * @returns `true` if `obj` is a DwnDidService; otherwise, `false`.
@@ -420,13 +420,14 @@ export function isDwnDidService(obj: unknown): obj is DwnDidService {
   // Validate that the `type` property is `DecentralizedWebNode`.
   if (obj.type !== 'DecentralizedWebNode') {return false;}
 
-  // Validate that the given object has the `enc` and `sig` properties.
-  if (!('enc' in obj && 'sig' in obj)) {return false;}
-
-  // Validate that the `enc` and `sig` properties are either strings or arrays of strings.
+  // If `enc` or `sig` are present, validate they are strings or arrays of strings.
   const isStringOrStringArray = (prop: any): boolean =>
     typeof prop === 'string' || Array.isArray(prop) && prop.every(item => typeof item === 'string');
-  return (isStringOrStringArray(obj.enc)) && (isStringOrStringArray(obj.sig));
+
+  if ('enc' in obj && obj.enc !== undefined && !isStringOrStringArray(obj.enc)) {return false;}
+  if ('sig' in obj && obj.sig !== undefined && !isStringOrStringArray(obj.sig)) {return false;}
+
+  return true;
 }
 
 /**