@hatk/hatk 0.0.1-alpha.83 → 0.0.1-alpha.84

package/dist/oauth/service-describe.d.ts

@@ -2,20 +2,31 @@
  * What a PDS says it serves, and the scopes worth asking it for.
  *
  * `community.lexicon.service.describe` answers with a service's roles and every
- * XRPC method it routes. It is the only way to ask: atproto publishes no method
- * list, so the alternative is to call a method and read the failure, where a
- * server without an optional feature and one that is broken look alike.
+ * XRPC method it routes. It is the direct question and the answer to trust when
+ * it comes — but it is still a proposal, and implementations exist that serve
+ * the features while serving no describe. The reference spaces build of
+ * `@atproto/pds` is one: it routes every space method and does not contain the
+ * describe NSID at all. Reading its silence as "no optional features" denies it
+ * scopes it could honor.
+ *
+ * So when describe says nothing, the methods a caller actually cares about are
+ * probed directly. Calling one and reading the failure cannot tell a missing
+ * feature from a broken server *on its own* — but it can against a control: ask
+ * for an NSID that certainly does not exist, learn how this server says "no such
+ * method", and a different answer for a real method is evidence it has one.
  *
  * Used before pushing an authorization request, so a PDS is asked for a
  * feature's scopes only when it implements the feature.
  */
 import type { OAuthConfig } from '../config.ts';
 /**
- * Every XRPC method a PDS serves. An empty set for a server that answers no
- * describe — which is every PDS that predates the method, so absence has to
- * read as "no optional features" rather than as an error.
+ * Every XRPC method a PDS serves, as far as it can be established.
+ *
+ * `candidates` are the methods the caller needs an answer about. They are only
+ * used when describe says nothing — an explicit list is always preferred to
+ * inference, and a server that answers describe is taken at its word.
  */
-export declare function describeMethods(pdsEndpoint: string): Promise<Set<string>>;
+export declare function describeMethods(pdsEndpoint: string, candidates?: string[]): Promise<Set<string>>;
 /**
  * The scope string to request from this PDS: `base`, plus any conditional set
  * whose `whenMethod` the server serves.

package/dist/oauth/service-describe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service-describe.d.ts","sourceRoot":"","sources":["../../src/oauth/service-describe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAU/C;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAwB/E;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,UAAU,EAAE,OAAO,GAClB,OAAO,CAAC,MAAM,CAAC,CAUjB;AAED,+CAA+C;AAC/C,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}
+{"version":3,"file":"service-describe.d.ts","sourceRoot":"","sources":["../../src/oauth/service-describe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAkD/C;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,GAAE,MAAM,EAAO,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CA+B1G;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,UAAU,EAAE,OAAO,GAClB,OAAO,CAAC,MAAM,CAAC,CAajB;AAED,+CAA+C;AAC/C,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/dist/oauth/service-describe.js

@@ -4,12 +4,53 @@ const PROBE_TIMEOUT_MS = 5000;
 const CACHE_TTL_MS = 60 * 60 * 1000;
 /** Answers are a property of the server, so one entry covers every account on it. */
 const cache = new Map();
+/** An NSID no server routes, for learning how one says "no such method". */
+const CONTROL_NSID = 'dev.hatk.unspecced.methodThatDoesNotExist';
+/** How a server answered, as a comparable string: status and error code. */
+async function signature(pdsEndpoint, nsid) {
+    try {
+        const res = await fetch(`${pdsEndpoint.replace(/\/$/, '')}/xrpc/${nsid}`, {
+            headers: { accept: 'application/json' },
+            signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+        });
+        const body = (await res.json().catch(() => null));
+        return `${res.status}:${body?.error ?? ''}`;
+    }
+    catch {
+        return null;
+    }
+}
 /**
- * Every XRPC method a PDS serves. An empty set for a server that answers no
- * describe — which is every PDS that predates the method, so absence has to
- * read as "no optional features" rather than as an error.
+ * Which of `candidates` this server appears to route, judged against how it
+ * answers for a method that does not exist.
+ *
+ * Conservative by construction. A server that answers identically either way —
+ * bsky.social returns `401 AuthMissing` for both — yields nothing, so a feature
+ * it does not have is never claimed. The cost is failing to see support that
+ * cannot be distinguished, which is where this started anyway.
  */
-export async function describeMethods(pdsEndpoint) {
+async function probeMethods(pdsEndpoint, candidates) {
+    const control = await signature(pdsEndpoint, CONTROL_NSID);
+    // Unreachable is not evidence about the server, so claim nothing.
+    if (control === null)
+        return new Set();
+    const answers = await Promise.all(candidates.map((n) => signature(pdsEndpoint, n)));
+    const found = new Set();
+    candidates.forEach((nsid, i) => {
+        const a = answers[i];
+        if (a !== null && a !== control)
+            found.add(nsid);
+    });
+    return found;
+}
+/**
+ * Every XRPC method a PDS serves, as far as it can be established.
+ *
+ * `candidates` are the methods the caller needs an answer about. They are only
+ * used when describe says nothing — an explicit list is always preferred to
+ * inference, and a server that answers describe is taken at its word.
+ */
+export async function describeMethods(pdsEndpoint, candidates = []) {
     const cached = cache.get(pdsEndpoint);
     if (cached && cached.expires > Date.now())
         return cached.methods;
@@ -32,6 +73,12 @@ export async function describeMethods(pdsEndpoint) {
     catch {
         methods = new Set();
     }
+    // No describe, or one that listed nothing: fall back to asking about the
+    // methods this caller actually needs. Only those — a probe per method is a
+    // request per method, and the conditional sets name two.
+    if (methods.size === 0 && candidates.length > 0) {
+        methods = await probeMethods(pdsEndpoint, candidates);
+    }
     cache.set(pdsEndpoint, { methods, expires: Date.now() + CACHE_TTL_MS });
     return methods;
 }
@@ -48,7 +95,7 @@ export async function negotiateScope(config, base, pdsEndpoint, isLoopback) {
     const conditional = config.conditionalScopes ?? [];
     if (conditional.length === 0 || !pdsEndpoint || isLoopback)
         return base;
-    const methods = await describeMethods(pdsEndpoint);
+    const methods = await describeMethods(pdsEndpoint, conditional.map((c) => c.whenMethod));
     const granted = conditional.filter((c) => methods.has(c.whenMethod)).flatMap((c) => c.scopes);
     if (granted.length === 0)
         return base;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hatk/hatk",
-  "version": "0.0.1-alpha.83",
+  "version": "0.0.1-alpha.84",
   "license": "MIT",
   "bin": {
     "hatk": "dist/cli.js"