test(auth): add loopback client_id auto-generation tests

Kzoeps · Kzoeps · commit dee032ea6ae8 · 2026-02-20T14:26:27.000+06:00
9 test cases covering: - Auto-append to bare http://localhost and http://localhost/ - Auto-append for http://127.0.0.1 - Scope override to atproto transition:generic with warning - No warning when scope already matches - No-op for client_id with existing query params - No scope override for user-provided loopback query params - No-op for non-localhost and localhost-with-port client_ids
diff --git a/.changeset/auto-generate-loopback-client-id-params.md b/.changeset/auto-generate-loopback-client-id-params.md
@@ -0,0 +1,49 @@
+---
+"@hypercerts-org/sdk-core": minor
+---
+
+Auto-generate `scope` and `redirect_uri` query params in `client_id` for localhost development
+
+When `clientId` is set to `http://localhost` (bare, no query parameters), the SDK now automatically appends the required
+`scope=atproto+transition:generic` and `redirect_uri` query parameters to the `client_id` URL before passing it to the
+AT Protocol authorization server. This is required by the AT Protocol OAuth spec for loopback clients, which embed these
+parameters directly in the `client_id` URL rather than hosting a metadata document.
+
+Previously, developers had to manually construct this URL:
+
+```typescript
+// Before
+const scope = "atproto transition:generic";
+const redirectUri = "http://127.0.0.1:3000/api/auth/callback";
+const sdk = createATProtoSDK({
+  oauth: {
+    clientId: `http://localhost?scope=${encodeURIComponent(scope)}&redirect_uri=${encodeURIComponent(redirectUri)}`,
+    redirectUri,
+    scope,
+    // ...
+  },
+});
+```
+
+Now `clientId: "http://localhost"` is sufficient:
+
+```typescript
+// After
+const sdk = createATProtoSDK({
+  oauth: {
+    clientId: "http://localhost",
+    redirectUri: "http://127.0.0.1:3000/api/auth/callback",
+    scope: "atproto transition:generic",
+    // ...
+  },
+});
+```
+
+**Behaviour details:**
+
+- Only triggers when `clientId` is exactly `http://localhost` or `http://localhost/` (no port, no existing query params)
+- Scope in the generated `client_id` is always `atproto transition:generic` as required by the AT Protocol OAuth spec
+  for loopback clients — a warning is logged if this overrides your configured `scope`
+- `redirect_uri` in the generated `client_id` is taken from `oauth.redirectUri` in your config
+- If `clientId` already contains query parameters, it is left unchanged (manual construction still works)
+- Non-localhost `clientId` values (HTTPS production URLs, ngrok, etc.) are completely unaffected
diff --git a/packages/sdk-core/README.md b/packages/sdk-core/README.md
@@ -60,16 +60,16 @@ For local development and testing, you can use HTTP loopback URLs with `localhos
 import { createATProtoSDK } from "@hypercerts-org/sdk-core";
 
 const baseUrl = "http://127.0.0.1:3000";
-const scope = "atproto transition:generic";
 const redirectUri = `${baseUrl}/api/auth/callback`;
 
 const sdk = createATProtoSDK({
   oauth: {
-    // Client ID embeds all metadata as query parameters
-    clientId: `http://localhost?scope=${encodeURIComponent(scope)}&redirect_uri=${encodeURIComponent(redirectUri)}`,
+    // The SDK automatically appends scope and redirect_uri query params
+    // when clientId is http://localhost (per AT Protocol loopback spec)
+    clientId: "http://localhost",
     // Redirect URI: MUST use 127.0.0.1 (not localhost)
     redirectUri,
-    scope,
+    scope: "atproto transition:generic",
     // JWKS URI: same origin as redirect URI
     jwksUri: `${baseUrl}/jwks.json`,
 
@@ -127,8 +127,10 @@ ATPROTO_JWK_PRIVATE='{"keys":[{"kty":"EC","crv":"P-256",...}]}'
 
 ### Important Notes
 
-> **Embed scope and redirect in client_id**: For loopback clients, embed scope and redirect in client_id. Otherwise the
-> oauth complains about missing scope and redirect.
+> **Auto-generated loopback params**: When `clientId` is `http://localhost` (bare, no query params), the SDK
+> automatically appends `scope` and `redirect_uri` from your config. If you need custom query params, you can still
+> construct the URL manually (e.g.,
+> `http://localhost?scope=${encodeURIComponent(scope)}&redirect_uri=${encodeURIComponent(redirectUri)}`).
 
 > **Authorization Server Support**: The AT Protocol OAuth spec makes loopback support **optional**. Most AT Protocol
 > servers support loopback clients for development, but verify your target authorization server supports this feature.
diff --git a/packages/sdk-core/tests/auth/OAuthClient.test.ts b/packages/sdk-core/tests/auth/OAuthClient.test.ts
@@ -291,4 +291,299 @@ describe("OAuthClient", () => {
       expect(warnLogs.length).toBe(0);
     });
   });
+
+  describe("loopback client_id auto-generation", () => {
+    it("should auto-append scope and redirect_uri to bare http://localhost client_id", async () => {
+      const { MockLogger } = await import("../utils/mocks.js");
+      const logger = new MockLogger();
+      const baseConfig = await createTestConfigAsync({ logger });
+      const configWithLoopback = await createTestConfigAsync({
+        logger,
+        oauth: {
+          ...baseConfig.oauth,
+          clientId: "http://localhost",
+          scope: "atproto",
+          redirectUri: "http://127.0.0.1:3000/callback",
+          developmentMode: true,
+        },
+      });
+
+      const client = new OAuthClient(configWithLoopback);
+
+      // Trigger async initialization to run buildClientMetadata()
+      // The underlying @atproto/oauth-client may reject loopback URLs, so we catch the error
+      try {
+        await client.authorize("test.bsky.social");
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      } catch (error) {
+        // Expected - underlying client may reject loopback URLs
+      }
+
+      // Verify info log about auto-generating was emitted
+      const infoLogs = logger.logs.filter((log) => log.level === "info");
+      const autoGenLog = infoLogs.find((log) => log.message.includes("Loopback client detected"));
+      expect(autoGenLog).toBeDefined();
+    });
+
+    it("should auto-append to http://localhost/ (with trailing slash)", async () => {
+      const { MockLogger } = await import("../utils/mocks.js");
+      const logger = new MockLogger();
+      const baseConfig = await createTestConfigAsync({ logger });
+      const configWithLoopback = await createTestConfigAsync({
+        logger,
+        oauth: {
+          ...baseConfig.oauth,
+          clientId: "http://localhost/",
+          scope: "atproto",
+          redirectUri: "http://127.0.0.1:3000/callback",
+          developmentMode: true,
+        },
+      });
+
+      const client = new OAuthClient(configWithLoopback);
+
+      // Trigger async initialization to run buildClientMetadata()
+      try {
+        await client.authorize("test.bsky.social");
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      } catch (error) {
+        // Expected - underlying client may reject loopback URLs
+      }
+
+      // Verify info log emitted
+      const infoLogs = logger.logs.filter((log) => log.level === "info");
+      const autoGenLog = infoLogs.find((log) => log.message.includes("Loopback client detected"));
+      expect(autoGenLog).toBeDefined();
+    });
+
+    it("should use atproto transition:generic scope regardless of configured scope", async () => {
+      const { MockLogger } = await import("../utils/mocks.js");
+      const logger = new MockLogger();
+      const baseConfig = await createTestConfigAsync({ logger });
+      const configWithLoopback = await createTestConfigAsync({
+        logger,
+        oauth: {
+          ...baseConfig.oauth,
+          clientId: "http://localhost",
+          scope: "atproto",
+          redirectUri: "http://127.0.0.1:3000/callback",
+          developmentMode: true,
+        },
+      });
+
+      const client = new OAuthClient(configWithLoopback);
+
+      // Trigger async initialization to run buildClientMetadata()
+      try {
+        await client.authorize("test.bsky.social");
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      } catch (error) {
+        // Expected - underlying client may reject loopback URLs
+      }
+
+      // Verify a warning log is emitted mentioning the scope override
+      const warnLogs = logger.logs.filter((log) => log.level === "warn");
+      const scopeOverrideWarning = warnLogs.find(
+        (log) =>
+          log.message.includes("overriding configured scope") &&
+          log.message.includes("as required by the AT Protocol OAuth spec"),
+      );
+      expect(scopeOverrideWarning).toBeDefined();
+
+      // Verify the info log mentions "atproto transition:generic"
+      const infoLogs = logger.logs.filter((log) => log.level === "info");
+      const autoGenLog = infoLogs.find((log) => log.message.includes("atproto transition:generic"));
+      expect(autoGenLog).toBeDefined();
+    });
+
+    it("should not warn about scope override when scope already matches", async () => {
+      const { MockLogger } = await import("../utils/mocks.js");
+      const logger = new MockLogger();
+      const baseConfig = await createTestConfigAsync({ logger });
+      const configWithLoopback = await createTestConfigAsync({
+        logger,
+        oauth: {
+          ...baseConfig.oauth,
+          clientId: "http://localhost",
+          scope: "atproto transition:generic",
+          redirectUri: "http://127.0.0.1:3000/callback",
+          developmentMode: true,
+        },
+      });
+
+      const client = new OAuthClient(configWithLoopback);
+
+      // Trigger async initialization to run buildClientMetadata()
+      try {
+        await client.authorize("test.bsky.social");
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      } catch (error) {
+        // Expected - underlying client may reject loopback URLs
+      }
+
+      // Verify info log emitted
+      const infoLogs = logger.logs.filter((log) => log.level === "info");
+      const autoGenLog = infoLogs.find((log) => log.message.includes("Loopback client detected"));
+      expect(autoGenLog).toBeDefined();
+
+      // Verify NO scope-override warning log
+      const warnLogs = logger.logs.filter((log) => log.level === "warn");
+      const scopeOverrideWarning = warnLogs.find((log) => log.message.includes("overriding configured scope"));
+      expect(scopeOverrideWarning).toBeUndefined();
+    });
+
+    it("should not modify client_id that already has query params", async () => {
+      const { MockLogger } = await import("../utils/mocks.js");
+      const logger = new MockLogger();
+      const baseConfig = await createTestConfigAsync({ logger });
+      const configWithQueryParams = await createTestConfigAsync({
+        logger,
+        oauth: {
+          ...baseConfig.oauth,
+          clientId: "http://localhost?scope=custom&redirect_uri=http://127.0.0.1:3000/cb",
+          scope: "atproto",
+          redirectUri: "http://127.0.0.1:3000/callback",
+          developmentMode: true,
+        },
+      });
+
+      const client = new OAuthClient(configWithQueryParams);
+
+      // Trigger async initialization to run buildClientMetadata()
+      try {
+        await client.authorize("test.bsky.social");
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      } catch (error) {
+        // Expected - underlying client may reject loopback URLs
+      }
+
+      // Verify NO auto-generation info log emitted (because it already has query params)
+      const infoLogs = logger.logs.filter((log) => log.level === "info");
+      const autoGenLog = infoLogs.find((log) => log.message.includes("Loopback client detected"));
+      expect(autoGenLog).toBeUndefined();
+    });
+
+    it("should not modify non-localhost client_id", async () => {
+      const { MockLogger } = await import("../utils/mocks.js");
+      const logger = new MockLogger();
+      const baseConfig = await createTestConfigAsync({ logger });
+      const configWithNonLocalhost = await createTestConfigAsync({
+        logger,
+        oauth: {
+          ...baseConfig.oauth,
+          clientId: "https://example.com/client-metadata.json",
+          scope: "atproto",
+          redirectUri: "https://example.com/callback",
+        },
+      });
+
+      const client = new OAuthClient(configWithNonLocalhost);
+
+      // Trigger async initialization to run buildClientMetadata()
+      try {
+        await client.authorize("test.bsky.social");
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      } catch (error) {
+        // Expected - network error or other issues
+      }
+
+      // Verify NO auto-generation info log emitted
+      const infoLogs = logger.logs.filter((log) => log.level === "info");
+      const autoGenLog = infoLogs.find((log) => log.message.includes("Loopback client detected"));
+      expect(autoGenLog).toBeUndefined();
+    });
+
+    it("should not modify localhost client_id with port", async () => {
+      const { MockLogger } = await import("../utils/mocks.js");
+      const logger = new MockLogger();
+      const baseConfig = await createTestConfigAsync({ logger });
+      const configWithPort = await createTestConfigAsync({
+        logger,
+        oauth: {
+          ...baseConfig.oauth,
+          clientId: "http://localhost:3000",
+          scope: "atproto",
+          redirectUri: "http://127.0.0.1:3000/callback",
+          developmentMode: true,
+        },
+      });
+
+      const client = new OAuthClient(configWithPort);
+
+      // Trigger async initialization to run buildClientMetadata()
+      try {
+        await client.authorize("test.bsky.social");
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      } catch (error) {
+        // Expected - underlying client may reject loopback URLs
+      }
+
+      // Verify NO auto-generation info log emitted (because it has a port)
+      const infoLogs = logger.logs.filter((log) => log.level === "info");
+      const autoGenLog = infoLogs.find((log) => log.message.includes("Loopback client detected"));
+      expect(autoGenLog).toBeUndefined();
+    });
+
+    it("should auto-append params for http://127.0.0.1 client_id", async () => {
+      const { MockLogger } = await import("../utils/mocks.js");
+      const logger = new MockLogger();
+      const baseConfig = await createTestConfigAsync({ logger });
+      const configWithLoopback = await createTestConfigAsync({
+        logger,
+        oauth: {
+          ...baseConfig.oauth,
+          clientId: "http://127.0.0.1",
+          scope: "atproto",
+          redirectUri: "http://127.0.0.1:3000/callback",
+          developmentMode: true,
+        },
+      });
+
+      const client = new OAuthClient(configWithLoopback);
+
+      // Trigger async initialization to run buildClientMetadata()
+      try {
+        await client.authorize("test.bsky.social");
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      } catch (error) {
+        // Expected - underlying client may reject loopback URLs
+      }
+
+      // Verify info log about auto-generating was emitted (since isLoopbackUrl covers 127.0.0.1)
+      const infoLogs = logger.logs.filter((log) => log.level === "info");
+      const autoGenLog = infoLogs.find((log) => log.message.includes("Loopback client detected"));
+      expect(autoGenLog).toBeDefined();
+    });
+
+    it("should not override scope when user passes loopback with own query params", async () => {
+      const { MockLogger } = await import("../utils/mocks.js");
+      const logger = new MockLogger();
+      const baseConfig = await createTestConfigAsync({ logger });
+      const configWithQueryParams = await createTestConfigAsync({
+        logger,
+        oauth: {
+          ...baseConfig.oauth,
+          clientId: "http://localhost?scope=atproto&redirect_uri=http://127.0.0.1:3000/cb",
+          scope: "atproto",
+          redirectUri: "http://127.0.0.1:3000/callback",
+          developmentMode: true,
+        },
+      });
+
+      const client = new OAuthClient(configWithQueryParams);
+
+      // Trigger async initialization to run buildClientMetadata()
+      try {
+        await client.authorize("test.bsky.social");
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      } catch (error) {
+        // Expected - underlying client may reject loopback URLs
+      }
+
+      // Verify NO scope override warning is emitted (because clientId wasn't auto-generated)
+      const warnLogs = logger.logs.filter((log) => log.level === "warn");
+      const scopeOverrideWarning = warnLogs.find((log) => log.message.includes("overriding configured scope"));
+      expect(scopeOverrideWarning).toBeUndefined();
+    });
+  });
 });
