@greensecurity/javascript-sdk 0.45.0-beta.16 → 0.45.0-beta.18

package/src/models/components/passwordnotsetresponse.ts

@@ -20,9 +20,42 @@ export type PasswordNotSetResponse = {
    */
   error: string;
   /**
-   * URL to redirect the user to set their password (forgot password flow). Includes return_url query param when provided in the request.
+   * URL to redirect the user to set their password (forgot password flow). Carries the `return_url` and `sso_state` query params when those were provided on the request, because the browser follows this redirect and leaves the JSON body behind.
    */
   redirectUrl: string;
+  /**
+   * Opaque, signed state that Green Security issues when a third-party service
+   *
+   * @remarks
+   * provider starts a "Login with Green Security" SAML flow at
+   * `/saml/idp/sso`. The login screen receives it as the `sso_state` query
+   * string parameter and must pass it back, byte for byte, on every call to
+   * this endpoint for the remainder of the login journey — including the
+   * second call that carries an `mfa_code`.
+   *
+   * The blob is signed, not encrypted, and it expires five minutes after the
+   * service provider's request arrives. Do not parse it, shorten it, decode
+   * it, or re-encode it.
+   *
+   * **An invalid blob does not fail the login.** This is the opposite of what
+   * most integrators assume, so it is worth stating plainly: a forged, edited
+   * or expired `sso_state` is silently discarded, and the request then
+   * proceeds as an ordinary login. Valid credentials still authenticate and
+   * still return `200` — just with no `sso` object, leaving the user signed in
+   * to Green Security with no way back to the service provider that sent them.
+   * Never treat a `200` as proof that the SSO hand-off survived; check for
+   * `sso` explicitly.
+   *
+   * Every `202` response echoes the *verified* blob back in its own
+   * `sso_state` field. Always send back the value from the response you just
+   * received rather than the one you started with, so that a blob the server
+   * has already rejected is never resent, and so a client does not have to
+   * hold state of its own across the login journey.
+   *
+   * Omit this field entirely for an ordinary login that did not originate
+   * from a service provider.
+   */
+  ssoState?: string | undefined;
 };
 
 /** @internal */
@@ -35,9 +68,11 @@ export const PasswordNotSetResponse$inboundSchema: z.ZodType<
   success: types.boolean(),
   error: types.string(),
   redirect_url: types.string(),
+  sso_state: types.optional(types.string()),
 }).transform((v) => {
   return remap$(v, {
     "redirect_url": "redirectUrl",
+    "sso_state": "ssoState",
   });
 });
 

package/src/models/components/passwordrequiredresponse.ts

@@ -3,6 +3,7 @@
  */
 
 import * as z from "zod/v3";
+import { remap as remap$ } from "../../lib/primitives.js";
 import { safeParse } from "../../lib/schemas.js";
 import { Result as SafeParseResult } from "../../types/fp.js";
 import * as types from "../../types/primitives.js";
@@ -18,6 +19,39 @@ export type PasswordRequiredResponse = {
    * Error describing the exact condition of what further steps are needed to finish the login process.
    */
   error: string;
+  /**
+   * Opaque, signed state that Green Security issues when a third-party service
+   *
+   * @remarks
+   * provider starts a "Login with Green Security" SAML flow at
+   * `/saml/idp/sso`. The login screen receives it as the `sso_state` query
+   * string parameter and must pass it back, byte for byte, on every call to
+   * this endpoint for the remainder of the login journey — including the
+   * second call that carries an `mfa_code`.
+   *
+   * The blob is signed, not encrypted, and it expires five minutes after the
+   * service provider's request arrives. Do not parse it, shorten it, decode
+   * it, or re-encode it.
+   *
+   * **An invalid blob does not fail the login.** This is the opposite of what
+   * most integrators assume, so it is worth stating plainly: a forged, edited
+   * or expired `sso_state` is silently discarded, and the request then
+   * proceeds as an ordinary login. Valid credentials still authenticate and
+   * still return `200` — just with no `sso` object, leaving the user signed in
+   * to Green Security with no way back to the service provider that sent them.
+   * Never treat a `200` as proof that the SSO hand-off survived; check for
+   * `sso` explicitly.
+   *
+   * Every `202` response echoes the *verified* blob back in its own
+   * `sso_state` field. Always send back the value from the response you just
+   * received rather than the one you started with, so that a blob the server
+   * has already rejected is never resent, and so a client does not have to
+   * hold state of its own across the login journey.
+   *
+   * Omit this field entirely for an ordinary login that did not originate
+   * from a service provider.
+   */
+  ssoState?: string | undefined;
 };
 
 /** @internal */
@@ -29,6 +63,11 @@ export const PasswordRequiredResponse$inboundSchema: z.ZodType<
   requires: types.literal("password"),
   success: types.boolean(),
   error: types.string(),
+  sso_state: types.optional(types.string()),
+}).transform((v) => {
+  return remap$(v, {
+    "sso_state": "ssoState",
+  });
 });
 
 export function passwordRequiredResponseFromJSON(

package/src/models/components/samlloginrequiredresponse.ts

@@ -28,6 +28,39 @@ export type SamlLoginRequiredResponse = {
    * This is the URL that should be opened to initiate the SAML login flow
    */
   ssoUrl: string;
+  /**
+   * Opaque, signed state that Green Security issues when a third-party service
+   *
+   * @remarks
+   * provider starts a "Login with Green Security" SAML flow at
+   * `/saml/idp/sso`. The login screen receives it as the `sso_state` query
+   * string parameter and must pass it back, byte for byte, on every call to
+   * this endpoint for the remainder of the login journey — including the
+   * second call that carries an `mfa_code`.
+   *
+   * The blob is signed, not encrypted, and it expires five minutes after the
+   * service provider's request arrives. Do not parse it, shorten it, decode
+   * it, or re-encode it.
+   *
+   * **An invalid blob does not fail the login.** This is the opposite of what
+   * most integrators assume, so it is worth stating plainly: a forged, edited
+   * or expired `sso_state` is silently discarded, and the request then
+   * proceeds as an ordinary login. Valid credentials still authenticate and
+   * still return `200` — just with no `sso` object, leaving the user signed in
+   * to Green Security with no way back to the service provider that sent them.
+   * Never treat a `200` as proof that the SSO hand-off survived; check for
+   * `sso` explicitly.
+   *
+   * Every `202` response echoes the *verified* blob back in its own
+   * `sso_state` field. Always send back the value from the response you just
+   * received rather than the one you started with, so that a blob the server
+   * has already rejected is never resent, and so a client does not have to
+   * hold state of its own across the login journey.
+   *
+   * Omit this field entirely for an ordinary login that did not originate
+   * from a service provider.
+   */
+  ssoState?: string | undefined;
 };
 
 /** @internal */
@@ -41,10 +74,12 @@ export const SamlLoginRequiredResponse$inboundSchema: z.ZodType<
   error: types.string(),
   sso_instructions: types.optional(types.string()),
   sso_url: types.string(),
+  sso_state: types.optional(types.string()),
 }).transform((v) => {
   return remap$(v, {
     "sso_instructions": "ssoInstructions",
     "sso_url": "ssoUrl",
+    "sso_state": "ssoState",
   });
 });
 

package/src/models/components/ssocontinuation.ts

@@ -0,0 +1,71 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod/v3";
+import { remap as remap$ } from "../../lib/primitives.js";
+import { safeParse } from "../../lib/schemas.js";
+import { Result as SafeParseResult } from "../../types/fp.js";
+import * as types from "../../types/primitives.js";
+import { SDKValidationError } from "../errors/sdkvalidationerror.js";
+
+/**
+ * Where to send the browser to finish a "Login with Green Security" flow.
+ *
+ * @remarks
+ *
+ * Present on a `200` from `POST /users/authenticate` only when the request
+ * carried a valid, unexpired `sso_state`. Its absence means the login
+ * succeeded but the SAML flow did not resume — treat the login as an
+ * ordinary one rather than retrying.
+ *
+ * This object is additive. The login itself is unaffected by it: the
+ * caller's own permanent token is in `user_token` exactly as it would be on
+ * any other successful authentication, and it is not the token embedded in
+ * `continue_url`.
+ */
+export type SsoContinuation = {
+  /**
+   * An absolute, single-use URL on Green Security's domain. Navigate the
+   *
+   * @remarks
+   * browser to it (a full page navigation, not `fetch`); it answers with a
+   * self-submitting form that POSTs the signed `SAMLResponse` and the
+   * original `RelayState` to the service provider's assertion consumer
+   * service URL.
+   *
+   * The `token` in this URL is a separate **one-time** token that is
+   * consumed the first time the URL is followed, so the URL is good for
+   * exactly one navigation. It is not the caller's permanent token, which
+   * is returned unchanged in `user_token`. Treat the URL as a secret:
+   * whoever follows it first receives that user's assertion.
+   *
+   * Never fetch this URL from your own back end: the response is meant for
+   * the user's browser, and posting the assertion from anywhere else
+   * breaks the flow.
+   */
+  continueUrl: string;
+};
+
+/** @internal */
+export const SsoContinuation$inboundSchema: z.ZodType<
+  SsoContinuation,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  continue_url: types.string(),
+}).transform((v) => {
+  return remap$(v, {
+    "continue_url": "continueUrl",
+  });
+});
+
+export function ssoContinuationFromJSON(
+  jsonString: string,
+): SafeParseResult<SsoContinuation, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => SsoContinuation$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'SsoContinuation' from JSON`,
+  );
+}

package/src/models/operations/postauthenticate.ts

@@ -26,7 +26,7 @@ export type PostAuthenticateResponseBody =
   | components.PasswordNotSetResponse;
 
 export type PostAuthenticateResponse =
-  | components.User
+  | components.AuthenticateSuccessResponse
   | components.MfaRequiredResponse
   | components.SamlLoginRequiredResponse
   | components.PasswordRequiredResponse
@@ -85,7 +85,7 @@ export const PostAuthenticateResponse$inboundSchema: z.ZodType<
   z.ZodTypeDef,
   unknown
 > = smartUnion([
-  components.User$inboundSchema,
+  components.AuthenticateSuccessResponse$inboundSchema,
   z.union([
     components.MfaRequiredResponse$inboundSchema,
     components.SamlLoginRequiredResponse$inboundSchema,

package/src/react-query/usersPostAuthenticate.ts

@@ -81,6 +81,43 @@ export type UsersPostAuthenticateMutationError =
  * 3. Site redirects to your selected `return_url`
  * 4. The `user_token` will be appended as a query string parameter to your `return_url` - you must parse this token and store it
  * 5. Fetch the user object from `/users/me` using the token
+ *
+ * ## Finishing a "Login with Green Security" flow
+ *
+ * Green Security is also a SAML2 **identity provider**. When a third-party service provider sends a user to
+ * `/saml/idp/sso` to sign in with their Green Security account, the user lands on a Green Security login screen
+ * carrying an `sso_state` query string parameter. That parameter is a signed, five-minute record of which service
+ * provider is waiting, where its assertion consumer service lives, and what `RelayState` it sent.
+ *
+ * Authentication itself is unchanged - the user may still need a password, an MFA code, a magic link or a round trip
+ * to their own SAML IdP, and every `requires` value above applies as normal. The only difference is that you must
+ * echo `sso_state` back on **every** call in the sequence, unchanged, including the follow-up that carries the
+ * `mfa_code`.
+ *
+ * Each `202` response carries the verified blob back to you in its own top-level `sso_state` field. Send back the
+ * value from the response you just received rather than the one you started with. The two are normally the same
+ * string, but re-sending your original copy is how a blob the server has already rejected gets resent, and it forces
+ * you to hold login state you would otherwise not need.
+ *
+ * 1. Read `sso_state` from the query string of the login screen you were sent to
+ * 2. Run the login exactly as you would otherwise, adding `sso_state` to each request body and taking the value for
+ *    the next request from the previous `202` response
+ * 3. On the `200` response, read `sso.continue_url`
+ * 4. Navigate the browser to `sso.continue_url` - a full page navigation, not a background fetch. It answers with a
+ *    self-submitting form that delivers the signed `SAMLResponse` and the original `RelayState` to the service
+ *    provider
+ * 5. The service provider validates the assertion and the user is signed in on their side
+ *
+ * On the `password_reset` leg the blob is **also** appended to `redirect_url` as a query parameter, alongside
+ * `return_url`. The browser follows that redirect and leaves the JSON body behind, so anything the remaining legs of
+ * the login still need has to ride the URL. Preserve the query string exactly as given.
+ *
+ * An invalid `sso_state` never fails a login. A forged, edited or expired blob is silently dropped and the request is
+ * then treated as an ordinary login, so valid credentials still return `200` - just with no `sso` object. Check for
+ * `sso` explicitly rather than reading `200` as proof the hand-off survived. When it is absent, do not retry with the
+ * same blob; the user has to start again from the service provider. See the
+ * [Login with Green Security](https://greensecurity.apidocumentation.com/guides/sso-login-with-green-security)
+ * guide for the service provider half of this flow.
  */
 export function useUsersPostAuthenticateMutation(
   options?: MutationHookOptions<

package/src/sdk/users.ts

@@ -148,6 +148,43 @@ export class Users extends ClientSDK {
    * 3. Site redirects to your selected `return_url`
    * 4. The `user_token` will be appended as a query string parameter to your `return_url` - you must parse this token and store it
    * 5. Fetch the user object from `/users/me` using the token
+   *
+   * ## Finishing a "Login with Green Security" flow
+   *
+   * Green Security is also a SAML2 **identity provider**. When a third-party service provider sends a user to
+   * `/saml/idp/sso` to sign in with their Green Security account, the user lands on a Green Security login screen
+   * carrying an `sso_state` query string parameter. That parameter is a signed, five-minute record of which service
+   * provider is waiting, where its assertion consumer service lives, and what `RelayState` it sent.
+   *
+   * Authentication itself is unchanged - the user may still need a password, an MFA code, a magic link or a round trip
+   * to their own SAML IdP, and every `requires` value above applies as normal. The only difference is that you must
+   * echo `sso_state` back on **every** call in the sequence, unchanged, including the follow-up that carries the
+   * `mfa_code`.
+   *
+   * Each `202` response carries the verified blob back to you in its own top-level `sso_state` field. Send back the
+   * value from the response you just received rather than the one you started with. The two are normally the same
+   * string, but re-sending your original copy is how a blob the server has already rejected gets resent, and it forces
+   * you to hold login state you would otherwise not need.
+   *
+   * 1. Read `sso_state` from the query string of the login screen you were sent to
+   * 2. Run the login exactly as you would otherwise, adding `sso_state` to each request body and taking the value for
+   *    the next request from the previous `202` response
+   * 3. On the `200` response, read `sso.continue_url`
+   * 4. Navigate the browser to `sso.continue_url` - a full page navigation, not a background fetch. It answers with a
+   *    self-submitting form that delivers the signed `SAMLResponse` and the original `RelayState` to the service
+   *    provider
+   * 5. The service provider validates the assertion and the user is signed in on their side
+   *
+   * On the `password_reset` leg the blob is **also** appended to `redirect_url` as a query parameter, alongside
+   * `return_url`. The browser follows that redirect and leaves the JSON body behind, so anything the remaining legs of
+   * the login still need has to ride the URL. Preserve the query string exactly as given.
+   *
+   * An invalid `sso_state` never fails a login. A forged, edited or expired blob is silently dropped and the request is
+   * then treated as an ordinary login, so valid credentials still return `200` - just with no `sso` object. Check for
+   * `sso` explicitly rather than reading `200` as proof the hand-off survived. When it is absent, do not retry with the
+   * same blob; the user has to start again from the service provider. See the
+   * [Login with Green Security](https://greensecurity.apidocumentation.com/guides/sso-login-with-green-security)
+   * guide for the service provider half of this flow.
    */
   async postAuthenticate(
     request: operations.PostAuthenticateRequestBody,