@corvushold/guard-sdk 0.15.0 → 0.16.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.16.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.