@corvushold/guard-sdk 0.15.0 → 0.17.0

package/README.md

@@ -20,6 +20,36 @@ This SDK uses a spec‑first approach. Core auth flows implemented:
 - Token introspection
 - Magic link: send + verify
 
+## OAuth2 Authorization Code (PKCE)
+
+Use the SDK to build the authorization URL from the configured `baseUrl` (Guard API host),
+instead of manually composing `/oauth/authorize` against the current page origin.
+
+```ts
+import { GuardClient } from '@corvushold/guard-sdk';
+
+const client = new GuardClient({
+  baseUrl: 'http://localhost:8082', // Guard API URL
+});
+
+const authorizeUrl = client.buildOAuth2AuthorizeUrl({
+  client_id: 'gc_VXfCQgfwZChIpUFVCLAgEecI_OKSMszh',
+  redirect_uri: 'http://localhost:3000/callback',
+  code_challenge: 'PKCE_CODE_CHALLENGE',
+  code_challenge_method: 'S256',
+  scope: ['openid', 'profile', 'email'],
+  state: crypto.randomUUID(),
+});
+
+window.location.href = authorizeUrl;
+```
+
+Notes:
+
+- `response_type` defaults to `code`.
+- `scope` accepts either a string (`"openid profile email"`) or a string array.
+- When `code_challenge` is set and `code_challenge_method` is omitted, the SDK defaults to `S256`.
+
 ## WorkOS Organization Portal Link
 
 Generate a WorkOS Admin Portal link for an organization (server enforces admin-only RBAC):

package/dist/index.cjs

@@ -279,7 +279,7 @@ var HttpClient = class {
 
 // package.json
 var package_default = {
-  version: "0.15.0"};
+  version: "0.17.0"};
 
 // src/client.ts
 function isTenantSelectionRequired(data) {
@@ -1050,6 +1050,51 @@ var GuardClient = class {
   // ==============================
   // OAuth2 Discovery (RFC 8414)
   // ==============================
+  /**
+   * Build an OAuth2 Authorization Code URL using this Guard client's baseUrl.
+   *
+   * This prevents accidental redirects to the current app origin when initiating
+   * OAuth2 flows from SPAs.
+   *
+   * @example
+   * ```ts
+   * const url = client.buildOAuth2AuthorizeUrl({
+   *   client_id: 'gc_123',
+   *   redirect_uri: 'https://app.example.com/callback',
+   *   code_challenge: 'abc...',
+   *   code_challenge_method: 'S256',
+   *   scope: ['openid', 'profile', 'email'],
+   *   state: 'csrf-state',
+   * });
+   * window.location.href = url;
+   * ```
+   */
+  buildOAuth2AuthorizeUrl(params) {
+    const clientID = params.client_id?.trim();
+    if (!clientID) throw new Error("client_id is required");
+    const redirectURI = params.redirect_uri?.trim();
+    if (!redirectURI) throw new Error("redirect_uri is required");
+    const responseType = params.response_type ?? "code";
+    if (responseType !== "code") {
+      throw new Error('response_type must be "code"');
+    }
+    const scope = Array.isArray(params.scope) ? params.scope.filter(Boolean).join(" ").trim() : params.scope?.trim();
+    const u = new URL("/oauth/authorize", this.baseUrl);
+    u.searchParams.set("response_type", responseType);
+    u.searchParams.set("client_id", clientID);
+    u.searchParams.set("redirect_uri", redirectURI);
+    if (scope) u.searchParams.set("scope", scope);
+    if (params.state) u.searchParams.set("state", params.state);
+    if (params.nonce) u.searchParams.set("nonce", params.nonce);
+    if (params.code_challenge) u.searchParams.set("code_challenge", params.code_challenge);
+    if (params.code_challenge) {
+      u.searchParams.set("code_challenge_method", params.code_challenge_method ?? "S256");
+    }
+    if (params.prompt) u.searchParams.set("prompt", params.prompt);
+    if (params.login_hint) u.searchParams.set("login_hint", params.login_hint);
+    if (params.max_age !== void 0) u.searchParams.set("max_age", String(params.max_age));
+    return u.toString();
+  }
   /**
    * Fetch OAuth 2.0 Authorization Server Metadata (RFC 8414)
    * Returns server capabilities including supported auth modes, endpoints, and grant types.
@@ -1058,6 +1103,47 @@ var GuardClient = class {
   async getOAuth2Metadata() {
     return this.request("/.well-known/oauth-authorization-server", { method: "GET" });
   }
+  /**
+   * Exchange an OAuth2 authorization code for tokens (Authorization Code + PKCE).
+   */
+  async exchangeOAuth2Code(input) {
+    const code = input.code?.trim();
+    const clientID = input.client_id?.trim();
+    const redirectURI = input.redirect_uri?.trim();
+    const codeVerifier = input.code_verifier?.trim();
+    if (!code) throw new Error("code is required");
+    if (!clientID) throw new Error("client_id is required");
+    if (!redirectURI) throw new Error("redirect_uri is required");
+    if (!codeVerifier) throw new Error("code_verifier is required");
+    const body = new URLSearchParams();
+    body.set("grant_type", "authorization_code");
+    body.set("code", code);
+    body.set("client_id", clientID);
+    body.set("redirect_uri", redirectURI);
+    body.set("code_verifier", codeVerifier);
+    const res = await this.request("/oauth/token", {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: body.toString()
+    });
+    if (res.meta.status >= 200 && res.meta.status < 300) this.persistTokensFrom(res.data);
+    return res;
+  }
+  /**
+   * Revoke an OAuth2 token (RFC7009). Server returns 200 for unknown tokens as well.
+   */
+  async revokeOAuth2Token(input) {
+    const token = input.token?.trim();
+    if (!token) throw new Error("token is required");
+    const body = new URLSearchParams();
+    body.set("token", token);
+    if (input.token_type_hint) body.set("token_type_hint", input.token_type_hint);
+    return this.request("/oauth/revoke", {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: body.toString()
+    });
+  }
   /**
    * Static helper to discover OAuth2 metadata from any Guard API base URL.
    * Useful for auto-configuration before creating a GuardClient instance.