@atproto-labs/handle-resolver-node 0.2.5 → 0.2.6

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @atproto-labs/handle-resolver-node
 
+## 0.2.6
+
+### Patch Changes
+
+- [#5193](https://github.com/bluesky-social/atproto/pull/5193) [`ce386ee`](https://github.com/bluesky-social/atproto/commit/ce386eed324f813601db57f873fbb3b987492001) Thanks [@Rex0Lux](https://github.com/Rex0Lux)! - Add an `onError` observability option to the handle resolvers. `WellKnownHandleResolver` previously swallowed every non-abort failure and returned `null`, indistinguishable from "no `.well-known/atproto-did` endpoint exists". Passing `onError` when constructing a resolver (including `AtprotoHandleResolver` and `AtprotoHandleResolverNode`) exposes the underlying cause (SSRF blocks, 5xx upstream errors, redirects, network errors, etc.) without changing the `null` return contract. Because it is set on the instance, it also covers resolution performed internally, for example by an OAuth client the resolver is passed to.
+
+- Updated dependencies [[`ce386ee`](https://github.com/bluesky-social/atproto/commit/ce386eed324f813601db57f873fbb3b987492001)]:
+  - @atproto-labs/handle-resolver@0.4.6
+
 ## 0.2.5
 
 ### Patch Changes

package/dist/atproto-handle-resolver-node.d.ts

@@ -1,5 +1,5 @@
 import { type Fetch } from '@atproto-labs/fetch-node';
-import { AtprotoHandleResolver, type HandleResolver } from '@atproto-labs/handle-resolver';
+import { AtprotoHandleResolver, type HandleResolver, type HandleResolverErrorHandler } from '@atproto-labs/handle-resolver';
 export type AtprotoHandleResolverNodeOptions = {
     /**
      * List of backup nameservers to use in case the primary ones fail. Will
@@ -15,8 +15,16 @@ export type AtprotoHandleResolverNodeOptions = {
      * @default `globalThis.fetch`
      */
     fetch?: Fetch;
+    /**
+     * Optional observability hook, invoked when handle resolution fails for a
+     * non-abort reason (network error, SSRF block, non-2xx response, etc.). The
+     * resolver still returns `null`; this only exposes the cause for logging or
+     * telemetry. Handy for diagnosing why a handle fails to resolve, e.g. when a
+     * PDS sits behind a firewall that trips SSRF protection.
+     */
+    onError?: HandleResolverErrorHandler;
 };
 export declare class AtprotoHandleResolverNode extends AtprotoHandleResolver implements HandleResolver {
-    constructor({ fetch, fallbackNameservers, }?: AtprotoHandleResolverNodeOptions);
+    constructor({ fetch, fallbackNameservers, onError, }?: AtprotoHandleResolverNodeOptions);
 }
 //# sourceMappingURL=atproto-handle-resolver-node.d.ts.map

package/dist/atproto-handle-resolver-node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"atproto-handle-resolver-node.d.ts","sourceRoot":"","sources":["../src/atproto-handle-resolver-node.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAiB,MAAM,0BAA0B,CAAA;AACpE,OAAO,EACL,qBAAqB,EACrB,KAAK,cAAc,EACpB,MAAM,+BAA+B,CAAA;AAMtC,MAAM,MAAM,gCAAgC,GAAG;IAC7C;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAA;IAE9B;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,KAAK,CAAA;CACd,CAAA;AAED,qBAAa,yBACX,SAAQ,qBACR,YAAW,cAAc;IAEzB,YAAY,EACV,KAAwB,EACxB,mBAAmB,GACpB,GAAE,gCAAqC,EAavC;CACF"}
+{"version":3,"file":"atproto-handle-resolver-node.d.ts","sourceRoot":"","sources":["../src/atproto-handle-resolver-node.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAiB,MAAM,0BAA0B,CAAA;AACpE,OAAO,EACL,qBAAqB,EACrB,KAAK,cAAc,EACnB,KAAK,0BAA0B,EAChC,MAAM,+BAA+B,CAAA;AAMtC,MAAM,MAAM,gCAAgC,GAAG;IAC7C;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAA;IAE9B;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,KAAK,CAAA;IAEb;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,0BAA0B,CAAA;CACrC,CAAA;AAED,qBAAa,yBACX,SAAQ,qBACR,YAAW,cAAc;IAEzB,YAAY,EACV,KAAwB,EACxB,mBAAmB,EACnB,OAAO,GACR,GAAE,gCAAqC,EAcvC;CACF"}

package/dist/atproto-handle-resolver-node.js

@@ -2,7 +2,7 @@ import { safeFetchWrap } from '@atproto-labs/fetch-node';
 import { AtprotoHandleResolver, } from '@atproto-labs/handle-resolver';
 import { nodeResolveTxtDefault, nodeResolveTxtFactory, } from './node-resolve-txt-factory.js';
 export class AtprotoHandleResolverNode extends AtprotoHandleResolver {
-    constructor({ fetch = globalThis.fetch, fallbackNameservers, } = {}) {
+    constructor({ fetch = globalThis.fetch, fallbackNameservers, onError, } = {}) {
         super({
             fetch: safeFetchWrap({
                 fetch,
@@ -14,6 +14,7 @@ export class AtprotoHandleResolverNode extends AtprotoHandleResolver {
             resolveTxtFallback: fallbackNameservers?.length
                 ? nodeResolveTxtFactory(fallbackNameservers)
                 : undefined,
+            onError,
         });
     }
 }

package/dist/atproto-handle-resolver-node.js.map

@@ -1 +1 @@
-{"version":3,"file":"atproto-handle-resolver-node.js","sourceRoot":"","sources":["../src/atproto-handle-resolver-node.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,aAAa,EAAE,MAAM,0BAA0B,CAAA;AACpE,OAAO,EACL,qBAAqB,GAEtB,MAAM,+BAA+B,CAAA;AACtC,OAAO,EACL,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,+BAA+B,CAAA;AAoBtC,MAAM,OAAO,yBACX,SAAQ,qBAAqB;IAG7B,YAAY,EACV,KAAK,GAAG,UAAU,CAAC,KAAK,EACxB,mBAAmB,GACpB,GAAqC,EAAE;QACtC,KAAK,CAAC;YACJ,KAAK,EAAE,aAAa,CAAC;gBACnB,KAAK;gBACL,OAAO,EAAE,IAAI,EAAE,YAAY;gBAC3B,cAAc,EAAE,IAAI;gBACpB,eAAe,EAAE,EAAE,GAAG,IAAI,EAAE,+CAA+C;aAC5E,CAAC;YACF,UAAU,EAAE,qBAAqB;YACjC,kBAAkB,EAAE,mBAAmB,EAAE,MAAM;gBAC7C,CAAC,CAAC,qBAAqB,CAAC,mBAAmB,CAAC;gBAC5C,CAAC,CAAC,SAAS;SACd,CAAC,CAAA;IACJ,CAAC;CACF","sourcesContent":["import { type Fetch, safeFetchWrap } from '@atproto-labs/fetch-node'\nimport {\n  AtprotoHandleResolver,\n  type HandleResolver,\n} from '@atproto-labs/handle-resolver'\nimport {\n  nodeResolveTxtDefault,\n  nodeResolveTxtFactory,\n} from './node-resolve-txt-factory.js'\n\nexport type AtprotoHandleResolverNodeOptions = {\n  /**\n   * List of backup nameservers to use in case the primary ones fail. Will\n   * default to no fallback nameservers.\n   */\n  fallbackNameservers?: string[]\n\n  /**\n   * Fetch function to use for HTTP requests. Allows customizing the request\n   * behavior, e.g. adding headers, setting a timeout, mocking, etc. The\n   * provided fetch function will be wrapped with a safeFetchWrap function that\n   * adds SSRF protection.\n   *\n   * @default `globalThis.fetch`\n   */\n  fetch?: Fetch\n}\n\nexport class AtprotoHandleResolverNode\n  extends AtprotoHandleResolver\n  implements HandleResolver\n{\n  constructor({\n    fetch = globalThis.fetch,\n    fallbackNameservers,\n  }: AtprotoHandleResolverNodeOptions = {}) {\n    super({\n      fetch: safeFetchWrap({\n        fetch,\n        timeout: 3000, // 3 seconds\n        ssrfProtection: true,\n        responseMaxSize: 10 * 1048, // DID are max 2048 characters, 10kb for safety\n      }),\n      resolveTxt: nodeResolveTxtDefault,\n      resolveTxtFallback: fallbackNameservers?.length\n        ? nodeResolveTxtFactory(fallbackNameservers)\n        : undefined,\n    })\n  }\n}\n"]}
+{"version":3,"file":"atproto-handle-resolver-node.js","sourceRoot":"","sources":["../src/atproto-handle-resolver-node.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,aAAa,EAAE,MAAM,0BAA0B,CAAA;AACpE,OAAO,EACL,qBAAqB,GAGtB,MAAM,+BAA+B,CAAA;AACtC,OAAO,EACL,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,+BAA+B,CAAA;AA6BtC,MAAM,OAAO,yBACX,SAAQ,qBAAqB;IAG7B,YAAY,EACV,KAAK,GAAG,UAAU,CAAC,KAAK,EACxB,mBAAmB,EACnB,OAAO,GACR,GAAqC,EAAE;QACtC,KAAK,CAAC;YACJ,KAAK,EAAE,aAAa,CAAC;gBACnB,KAAK;gBACL,OAAO,EAAE,IAAI,EAAE,YAAY;gBAC3B,cAAc,EAAE,IAAI;gBACpB,eAAe,EAAE,EAAE,GAAG,IAAI,EAAE,+CAA+C;aAC5E,CAAC;YACF,UAAU,EAAE,qBAAqB;YACjC,kBAAkB,EAAE,mBAAmB,EAAE,MAAM;gBAC7C,CAAC,CAAC,qBAAqB,CAAC,mBAAmB,CAAC;gBAC5C,CAAC,CAAC,SAAS;YACb,OAAO;SACR,CAAC,CAAA;IACJ,CAAC;CACF","sourcesContent":["import { type Fetch, safeFetchWrap } from '@atproto-labs/fetch-node'\nimport {\n  AtprotoHandleResolver,\n  type HandleResolver,\n  type HandleResolverErrorHandler,\n} from '@atproto-labs/handle-resolver'\nimport {\n  nodeResolveTxtDefault,\n  nodeResolveTxtFactory,\n} from './node-resolve-txt-factory.js'\n\nexport type AtprotoHandleResolverNodeOptions = {\n  /**\n   * List of backup nameservers to use in case the primary ones fail. Will\n   * default to no fallback nameservers.\n   */\n  fallbackNameservers?: string[]\n\n  /**\n   * Fetch function to use for HTTP requests. Allows customizing the request\n   * behavior, e.g. adding headers, setting a timeout, mocking, etc. The\n   * provided fetch function will be wrapped with a safeFetchWrap function that\n   * adds SSRF protection.\n   *\n   * @default `globalThis.fetch`\n   */\n  fetch?: Fetch\n\n  /**\n   * Optional observability hook, invoked when handle resolution fails for a\n   * non-abort reason (network error, SSRF block, non-2xx response, etc.). The\n   * resolver still returns `null`; this only exposes the cause for logging or\n   * telemetry. Handy for diagnosing why a handle fails to resolve, e.g. when a\n   * PDS sits behind a firewall that trips SSRF protection.\n   */\n  onError?: HandleResolverErrorHandler\n}\n\nexport class AtprotoHandleResolverNode\n  extends AtprotoHandleResolver\n  implements HandleResolver\n{\n  constructor({\n    fetch = globalThis.fetch,\n    fallbackNameservers,\n    onError,\n  }: AtprotoHandleResolverNodeOptions = {}) {\n    super({\n      fetch: safeFetchWrap({\n        fetch,\n        timeout: 3000, // 3 seconds\n        ssrfProtection: true,\n        responseMaxSize: 10 * 1048, // DID are max 2048 characters, 10kb for safety\n      }),\n      resolveTxt: nodeResolveTxtDefault,\n      resolveTxtFallback: fallbackNameservers?.length\n        ? nodeResolveTxtFactory(fallbackNameservers)\n        : undefined,\n      onError,\n    })\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atproto-labs/handle-resolver-node",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "license": "MIT",
   "description": "Node specific ATProto handle to DID resolver",
   "keywords": [
@@ -31,9 +31,9 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@atproto-labs/handle-resolver": "^0.4.5",
     "@atproto-labs/fetch-node": "^0.3.5",
-    "@atproto/did": "^0.5.4"
+    "@atproto/did": "^0.5.4",
+    "@atproto-labs/handle-resolver": "^0.4.6"
   },
   "scripts": {
     "build": "tsgo --build tsconfig.build.json"