@knpkv/atlassian-common 0.2.0

package/test/OAuthEndpoints.test.ts

@@ -0,0 +1,109 @@
+import { it as effectIt } from "@effect/vitest"
+import * as Effect from "effect/Effect"
+import { describe, expect, it } from "vitest"
+import { AUTH_URL, buildAuthUrl, computeCodeChallenge, generateCodeVerifier } from "../src/auth/OAuthEndpoints.js"
+
+describe("OAuthEndpoints", () => {
+  // ---- PKCE ----
+
+  describe("generateCodeVerifier", () => {
+    // 32 random bytes base64url-encoded = 43 chars; verifies output shape for RFC 7636 compliance
+    it("returns a base64url string of 43 characters (32 random bytes)", () => {
+      const verifier = generateCodeVerifier()
+      expect(verifier).toHaveLength(43)
+      expect(verifier).toMatch(/^[A-Za-z0-9_-]+$/)
+    })
+
+    // PKCE verifiers must be unique per auth request — reuse enables replay attacks
+    it("produces unique values", () => {
+      const a = generateCodeVerifier()
+      const b = generateCodeVerifier()
+      expect(a).not.toBe(b)
+    })
+  })
+
+  describe("computeCodeChallenge", () => {
+    // Known test vector from RFC 7636 appendix B — proves SHA-256 + base64url is correct
+    effectIt.effect("matches RFC 7636 appendix B test vector", () =>
+      Effect.gen(function*() {
+        const verifier = "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
+        const expected = "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
+        const challenge = yield* computeCodeChallenge(verifier)
+        expect(challenge).toBe(expected)
+      }))
+
+    // Same verifier must always produce same challenge — server verifies this on token exchange
+    effectIt.effect("is deterministic", () =>
+      Effect.gen(function*() {
+        const v = generateCodeVerifier()
+        const a = yield* computeCodeChallenge(v)
+        const b = yield* computeCodeChallenge(v)
+        expect(a).toBe(b)
+      }))
+
+    // base64url must not contain +, /, = — these break URL query params
+    effectIt.effect("produces base64url output (no +, /, =)", () =>
+      Effect.gen(function*() {
+        const challenge = yield* computeCodeChallenge("test-verifier-string")
+        expect(challenge).toMatch(/^[A-Za-z0-9_-]+$/)
+      }))
+  })
+
+  // ---- buildAuthUrl ----
+
+  describe("buildAuthUrl", () => {
+    // Verifies all required OAuth2 params (audience, client_id, scope, redirect_uri, state, response_type, prompt)
+    it("includes required parameters", () => {
+      const url = buildAuthUrl({
+        clientId: "cid",
+        state: "state-123",
+        port: 9876,
+        scopes: ["read:jira-work", "offline_access"]
+      })
+
+      const parsed = new URL(url)
+      expect(parsed.origin + parsed.pathname).toBe(AUTH_URL)
+      expect(parsed.searchParams.get("client_id")).toBe("cid")
+      expect(parsed.searchParams.get("state")).toBe("state-123")
+      expect(parsed.searchParams.get("redirect_uri")).toBe("http://localhost:9876/callback")
+      expect(parsed.searchParams.get("scope")).toBe("read:jira-work offline_access")
+      expect(parsed.searchParams.get("response_type")).toBe("code")
+      expect(parsed.searchParams.get("audience")).toBe("api.atlassian.com")
+      expect(parsed.searchParams.get("prompt")).toBe("consent")
+    })
+
+    // PKCE is optional — omitting codeChallenge must not add params (backwards compat)
+    it("omits PKCE params when codeChallenge not provided", () => {
+      const url = buildAuthUrl({
+        clientId: "cid",
+        state: "s",
+        port: 3000,
+        scopes: ["read:me"]
+      })
+
+      const parsed = new URL(url)
+      expect(parsed.searchParams.has("code_challenge")).toBe(false)
+      expect(parsed.searchParams.has("code_challenge_method")).toBe(false)
+    })
+
+    // When PKCE is used, both code_challenge and method=S256 must appear for server to validate
+    effectIt.effect(
+      "includes code_challenge and code_challenge_method=S256 when provided",
+      () =>
+        Effect.gen(function*() {
+          const challenge = yield* computeCodeChallenge("my-verifier")
+          const url = buildAuthUrl({
+            clientId: "cid",
+            state: "s",
+            port: 3000,
+            scopes: ["read:me"],
+            codeChallenge: challenge
+          })
+
+          const parsed = new URL(url)
+          expect(parsed.searchParams.get("code_challenge")).toBe(challenge)
+          expect(parsed.searchParams.get("code_challenge_method")).toBe("S256")
+        })
+    )
+  })
+})

package/test/OAuthOperations.test.ts

@@ -0,0 +1,315 @@
+import * as HttpClient from "@effect/platform/HttpClient"
+import type * as HttpClientRequest from "@effect/platform/HttpClientRequest"
+import * as HttpClientResponse from "@effect/platform/HttpClientResponse"
+import { describe, it } from "@effect/vitest"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import { expect } from "vitest"
+import { OAuthError } from "../src/auth/OAuthErrors.js"
+import {
+  buildOAuthToken,
+  exchangeCodeForTokens,
+  getAccessibleResources,
+  getUserInfo,
+  refreshToken,
+  revokeToken
+} from "../src/auth/OAuthOperations.js"
+import type { OAuthConfig, OAuthToken } from "../src/config/OAuthSchemas.js"
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const createMockHttpClient = (
+  responses: Array<{ status: number; body: unknown }>
+) => {
+  let requestIndex = 0
+  const capturedRequests: Array<HttpClientRequest.HttpClientRequest> = []
+
+  const mockClient: HttpClient.HttpClient = HttpClient.make((request) =>
+    Effect.gen(function*() {
+      capturedRequests.push(request)
+      const response = responses[requestIndex] ?? { status: 200, body: {} }
+      requestIndex++
+      return HttpClientResponse.fromWeb(
+        request,
+        new Response(
+          JSON.stringify(response.body),
+          { status: response.status, headers: { "content-type": "application/json" } }
+        )
+      )
+    })
+  )
+
+  return { mockClient, capturedRequests }
+}
+
+const provide = (client: HttpClient.HttpClient) => Effect.provide(Layer.succeed(HttpClient.HttpClient, client))
+
+const validTokenBody = {
+  access_token: "access-123",
+  refresh_token: "refresh-456",
+  expires_in: 3600,
+  scope: "read:jira-work",
+  token_type: "Bearer"
+}
+
+const oauthConfig: OAuthConfig = {
+  clientId: "cid",
+  clientSecret: "csecret"
+}
+
+const oauthToken: OAuthToken = {
+  access_token: "old-access",
+  refresh_token: "old-refresh",
+  expires_at: Date.now() - 1000,
+  scope: "read:jira-work",
+  cloud_id: "cloud-1",
+  site_url: "https://site.atlassian.net"
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("OAuthOperations", () => {
+  // ---- exchangeCodeForTokens ----
+
+  describe("exchangeCodeForTokens", () => {
+    // Verifies grant_type, client_id, client_secret, code, redirect_uri are sent — the 5 required fields for token exchange
+    // Also confirms code_verifier is absent when PKCE not used
+    it.effect("sends correct body without code_verifier", () =>
+      Effect.gen(function*() {
+        const { capturedRequests, mockClient } = createMockHttpClient([
+          { status: 200, body: validTokenBody }
+        ])
+
+        const result = yield* exchangeCodeForTokens("auth-code", oauthConfig, { port: 9876 }).pipe(
+          provide(mockClient)
+        )
+
+        expect(result.access_token).toBe("access-123")
+        expect(capturedRequests).toHaveLength(1)
+        const req = capturedRequests[0]!
+        expect(req.url).toContain("auth.atlassian.com/oauth/token")
+
+        // body is an Effect — decode from the captured request
+        const body = yield* req.body._tag === "Uint8Array"
+          ? Effect.succeed(JSON.parse(new TextDecoder().decode(req.body.body)))
+          : Effect.succeed({})
+
+        expect(body.grant_type).toBe("authorization_code")
+        expect(body.client_id).toBe("cid")
+        expect(body.client_secret).toBe("csecret")
+        expect(body.code).toBe("auth-code")
+        expect(body.redirect_uri).toBe("http://localhost:9876/callback")
+        expect(body.code_verifier).toBeUndefined()
+      }))
+
+    // PKCE requires code_verifier on token exchange — server checks SHA256(verifier) == challenge from auth URL
+    it.effect("includes code_verifier when provided", () =>
+      Effect.gen(function*() {
+        const { capturedRequests, mockClient } = createMockHttpClient([
+          { status: 200, body: validTokenBody }
+        ])
+
+        yield* exchangeCodeForTokens("auth-code", oauthConfig, { port: 9876, codeVerifier: "my-verifier" }).pipe(
+          provide(mockClient)
+        )
+
+        const req = capturedRequests[0]!
+        const body = yield* req.body._tag === "Uint8Array"
+          ? Effect.succeed(JSON.parse(new TextDecoder().decode(req.body.body)))
+          : Effect.succeed({})
+
+        expect(body.code_verifier).toBe("my-verifier")
+      }))
+
+    // Token exchange failures (invalid code, expired code) must surface as OAuthError with step="token"
+    it.effect("returns OAuthError with step=token on HTTP 400", () =>
+      Effect.gen(function*() {
+        const { mockClient } = createMockHttpClient([
+          { status: 400, body: { error: "invalid_grant" } }
+        ])
+
+        const exit = yield* exchangeCodeForTokens("bad-code", oauthConfig, { port: 9876 }).pipe(
+          provide(mockClient),
+          Effect.flip
+        )
+
+        expect(exit).toBeInstanceOf(OAuthError)
+        expect(exit.step).toBe("token")
+      }))
+  })
+
+  // ---- getAccessibleResources ----
+
+  describe("getAccessibleResources", () => {
+    // Verifies Bearer token is applied to Authorization header and response is decoded into typed array
+    it.effect("applies Bearer token and decodes response", () =>
+      Effect.gen(function*() {
+        const { capturedRequests, mockClient } = createMockHttpClient([
+          {
+            status: 200,
+            body: [
+              { id: "cloud-1", name: "My Site", url: "https://site.atlassian.net", scopes: ["read:jira-work"] }
+            ]
+          }
+        ])
+
+        const result = yield* getAccessibleResources("tok-abc").pipe(provide(mockClient))
+
+        expect(result).toHaveLength(1)
+        expect(result[0]!.id).toBe("cloud-1")
+
+        const req = capturedRequests[0]!
+        expect(req.headers.authorization).toBe("Bearer tok-abc")
+      }))
+
+    // Resources failures must use step="resources" (not "authorize") so callers can distinguish from other phases
+    it.effect("returns OAuthError with step=resources on HTTP 401", () =>
+      Effect.gen(function*() {
+        const { mockClient } = createMockHttpClient([{ status: 401, body: {} }])
+
+        const exit = yield* getAccessibleResources("bad-tok").pipe(
+          provide(mockClient),
+          Effect.flip
+        )
+
+        expect(exit).toBeInstanceOf(OAuthError)
+        expect(exit.step).toBe("resources")
+      }))
+  })
+
+  // ---- getUserInfo ----
+
+  describe("getUserInfo", () => {
+    // Verifies Bearer token and correct decoding of account_id, name, email from /me endpoint
+    it.effect("applies Bearer token and decodes response", () =>
+      Effect.gen(function*() {
+        const { capturedRequests, mockClient } = createMockHttpClient([
+          { status: 200, body: { account_id: "uid-1", name: "Alice", email: "a@b.com" } }
+        ])
+
+        const result = yield* getUserInfo("tok-xyz").pipe(provide(mockClient))
+
+        expect(result.account_id).toBe("uid-1")
+        expect(result.name).toBe("Alice")
+        expect(result.email).toBe("a@b.com")
+
+        const req = capturedRequests[0]!
+        expect(req.headers.authorization).toBe("Bearer tok-xyz")
+      }))
+
+    // User info failures must use step="user-info" (not "authorize") for per-phase error handling
+    it.effect("returns OAuthError with step=user-info on HTTP 403", () =>
+      Effect.gen(function*() {
+        const { mockClient } = createMockHttpClient([{ status: 403, body: {} }])
+
+        const exit = yield* getUserInfo("bad-tok").pipe(
+          provide(mockClient),
+          Effect.flip
+        )
+
+        expect(exit).toBeInstanceOf(OAuthError)
+        expect(exit.step).toBe("user-info")
+      }))
+  })
+
+  // ---- refreshToken ----
+
+  describe("refreshToken", () => {
+    // Verifies grant_type=refresh_token is sent and returned token preserves cloud_id/site_url from original
+    it.effect("sends refresh_token and returns updated OAuthToken", () =>
+      Effect.gen(function*() {
+        const { capturedRequests, mockClient } = createMockHttpClient([
+          { status: 200, body: { ...validTokenBody, access_token: "new-access", refresh_token: "new-refresh" } }
+        ])
+
+        const result = yield* refreshToken(oauthToken, oauthConfig).pipe(provide(mockClient))
+
+        expect(result.access_token).toBe("new-access")
+        expect(result.refresh_token).toBe("new-refresh")
+        // preserves existing fields
+        expect(result.cloud_id).toBe("cloud-1")
+        expect(result.site_url).toBe("https://site.atlassian.net")
+        expect(result.expires_at).toBeGreaterThan(Date.now())
+
+        const req = capturedRequests[0]!
+        const body = yield* req.body._tag === "Uint8Array"
+          ? Effect.succeed(JSON.parse(new TextDecoder().decode(req.body.body)))
+          : Effect.succeed({})
+
+        expect(body.grant_type).toBe("refresh_token")
+        expect(body.refresh_token).toBe("old-refresh")
+      }))
+
+    // Refresh failures (revoked token, expired refresh) must surface as step="refresh"
+    it.effect("returns OAuthError with step=refresh on HTTP 400", () =>
+      Effect.gen(function*() {
+        const { mockClient } = createMockHttpClient([
+          { status: 400, body: { error: "invalid_grant" } }
+        ])
+
+        const exit = yield* refreshToken(oauthToken, oauthConfig).pipe(
+          provide(mockClient),
+          Effect.flip
+        )
+
+        expect(exit).toBeInstanceOf(OAuthError)
+        expect(exit.step).toBe("refresh")
+      }))
+  })
+
+  // ---- revokeToken ----
+
+  describe("revokeToken", () => {
+    // Verifies revoke hits the correct endpoint — logout must invalidate server-side token
+    it.effect("sends revoke request", () =>
+      Effect.gen(function*() {
+        const { capturedRequests, mockClient } = createMockHttpClient([
+          { status: 200, body: {} }
+        ])
+
+        yield* revokeToken(oauthToken, oauthConfig).pipe(provide(mockClient))
+
+        expect(capturedRequests).toHaveLength(1)
+        const req = capturedRequests[0]!
+        expect(req.url).toContain("auth.atlassian.com/oauth/revoke")
+      }))
+
+    // Revoke failures must surface as step="revoke" for caller error handling
+    it.effect("returns OAuthError with step=revoke on HTTP 400", () =>
+      Effect.gen(function*() {
+        const { mockClient } = createMockHttpClient([{ status: 400, body: {} }])
+
+        const exit = yield* revokeToken(oauthToken, oauthConfig).pipe(
+          provide(mockClient),
+          Effect.flip
+        )
+
+        expect(exit).toBeInstanceOf(OAuthError)
+        expect(exit.step).toBe("revoke")
+      }))
+  })
+
+  // ---- buildOAuthToken ----
+
+  describe("buildOAuthToken", () => {
+    // Pure assembly function — verifies token response + site + user are merged correctly with computed expires_at
+    it("assembles OAuthToken from response + site + user", () => {
+      const token = buildOAuthToken(
+        validTokenBody,
+        { id: "cloud-1", name: "Site", url: "https://site.atlassian.net", scopes: [] },
+        { account_id: "uid-1", name: "Alice", email: "a@b.com" }
+      )
+
+      expect(token.access_token).toBe("access-123")
+      expect(token.refresh_token).toBe("refresh-456")
+      expect(token.cloud_id).toBe("cloud-1")
+      expect(token.site_url).toBe("https://site.atlassian.net")
+      expect(token.user).toEqual({ account_id: "uid-1", name: "Alice", email: "a@b.com" })
+      expect(token.expires_at).toBeGreaterThan(Date.now() - 1000)
+    })
+  })
+})

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.jsonc",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "test"]
+}