@greensecurity/javascript-sdk 0.45.0-beta.15 → 0.45.0-beta.17

package/src/models/webhooks/sendfullreportupdated.ts

@@ -0,0 +1,104 @@
+/*
+ * 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 * as components from "../components/index.js";
+import { SDKValidationError } from "../errors/sdkvalidationerror.js";
+
+export type SendFullReportUpdatedRequest = {
+  /**
+   * `t=<unix seconds>,v1=<hex hmac>`, one `v1` per active secret. Each is
+   *
+   * @remarks
+   * `HMAC-SHA256(secret, "<t>.<raw body>")`. Compare with a constant-time function and
+   * reject a timestamp that is not recent.
+   */
+  greenSecuritySignature: string;
+  /**
+   * The event this delivery belongs to. Route on it when one URL serves several events.
+   */
+  greenSecurityEvent: string;
+  /**
+   * Stable per delivery, including across retries. Key your de-duplication on it.
+   */
+  greenSecurityIdempotencyKey: string;
+  /**
+   * The entity in the body.
+   */
+  greenWebhookId: string;
+  fullReport: components.FullReport;
+};
+
+/** @internal */
+export const SendFullReportUpdatedRequest$inboundSchema: z.ZodType<
+  SendFullReportUpdatedRequest,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  "Green-Security-Signature": types.string(),
+  "Green-Security-Event": types.string(),
+  "Green-Security-Idempotency-Key": types.string(),
+  "Green-Webhook-Id": types.string(),
+  FullReport: components.FullReport$inboundSchema,
+}).transform((v) => {
+  return remap$(v, {
+    "Green-Security-Signature": "greenSecuritySignature",
+    "Green-Security-Event": "greenSecurityEvent",
+    "Green-Security-Idempotency-Key": "greenSecurityIdempotencyKey",
+    "Green-Webhook-Id": "greenWebhookId",
+    "FullReport": "fullReport",
+  });
+});
+/** @internal */
+export type SendFullReportUpdatedRequest$Outbound = {
+  "Green-Security-Signature": string;
+  "Green-Security-Event": string;
+  "Green-Security-Idempotency-Key": string;
+  "Green-Webhook-Id": string;
+  FullReport: components.FullReport$Outbound;
+};
+
+/** @internal */
+export const SendFullReportUpdatedRequest$outboundSchema: z.ZodType<
+  SendFullReportUpdatedRequest$Outbound,
+  z.ZodTypeDef,
+  SendFullReportUpdatedRequest
+> = z.object({
+  greenSecuritySignature: z.string(),
+  greenSecurityEvent: z.string(),
+  greenSecurityIdempotencyKey: z.string(),
+  greenWebhookId: z.string(),
+  fullReport: components.FullReport$outboundSchema,
+}).transform((v) => {
+  return remap$(v, {
+    greenSecuritySignature: "Green-Security-Signature",
+    greenSecurityEvent: "Green-Security-Event",
+    greenSecurityIdempotencyKey: "Green-Security-Idempotency-Key",
+    greenWebhookId: "Green-Webhook-Id",
+    fullReport: "FullReport",
+  });
+});
+
+export function sendFullReportUpdatedRequestToJSON(
+  sendFullReportUpdatedRequest: SendFullReportUpdatedRequest,
+): string {
+  return JSON.stringify(
+    SendFullReportUpdatedRequest$outboundSchema.parse(
+      sendFullReportUpdatedRequest,
+    ),
+  );
+}
+export function sendFullReportUpdatedRequestFromJSON(
+  jsonString: string,
+): SafeParseResult<SendFullReportUpdatedRequest, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => SendFullReportUpdatedRequest$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'SendFullReportUpdatedRequest' from JSON`,
+  );
+}

package/src/react-query/reportsGetFullReport.ts

@@ -72,9 +72,9 @@ export type ReportsGetFullReportQueryError =
  * | `404` | No such run, or it is outside your access scope. | Stop. |
  * | `403` | Your account is locked, or lacks the `scheduled_reports` view permission. | Stop. |
  *
- * **Bound your polling.** A `409` is not a promise that the run will finish. Report
- * generation has no terminal failure state today, so a run whose generation crashed part way
- * through stays in `processing` and keeps answering `409` indefinitely. Apply your own
+ * **Bound your polling.** A `409` is not a promise that the run will finish. A run that fails
+ * while generating is now recorded as `failed` and answers `422`, but a run whose worker died
+ * outright still stays in `processing` and keeps answering `409` indefinitely. Apply your own
  * timeout or maximum attempt count and treat exhaustion as a failure; do not retry forever.
  *
  * Access control: the URL's `full_report_id` must be in the caller's read scope for
@@ -122,9 +122,9 @@ export function useReportsGetFullReport(
  * | `404` | No such run, or it is outside your access scope. | Stop. |
  * | `403` | Your account is locked, or lacks the `scheduled_reports` view permission. | Stop. |
  *
- * **Bound your polling.** A `409` is not a promise that the run will finish. Report
- * generation has no terminal failure state today, so a run whose generation crashed part way
- * through stays in `processing` and keeps answering `409` indefinitely. Apply your own
+ * **Bound your polling.** A `409` is not a promise that the run will finish. A run that fails
+ * while generating is now recorded as `failed` and answers `422`, but a run whose worker died
+ * outright still stays in `processing` and keeps answering `409` indefinitely. Apply your own
  * timeout or maximum attempt count and treat exhaustion as a failure; do not retry forever.
  *
  * Access control: the URL's `full_report_id` must be in the caller's read scope for

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/reports.ts

@@ -62,9 +62,9 @@ export class Reports extends ClientSDK {
    * | `404` | No such run, or it is outside your access scope. | Stop. |
    * | `403` | Your account is locked, or lacks the `scheduled_reports` view permission. | Stop. |
    *
-   * **Bound your polling.** A `409` is not a promise that the run will finish. Report
-   * generation has no terminal failure state today, so a run whose generation crashed part way
-   * through stays in `processing` and keeps answering `409` indefinitely. Apply your own
+   * **Bound your polling.** A `409` is not a promise that the run will finish. A run that fails
+   * while generating is now recorded as `failed` and answers `422`, but a run whose worker died
+   * outright still stays in `processing` and keeps answering `409` indefinitely. Apply your own
    * timeout or maximum attempt count and treat exhaustion as a failure; do not retry forever.
    *
    * Access control: the URL's `full_report_id` must be in the caller's read scope for

package/src/sdk/sdk.ts

@@ -140,6 +140,9 @@ export class GreenSecurity extends ClientSDK {
     } | Request;
     secret: string;
   }): Promise<
+    | webhooks.SendFullReportCreatedRequest
+    | webhooks.SendFullReportUpdatedRequest
+    | webhooks.SendFullReportDestroyedRequest
     | webhooks.SendVendorCreatedRequest
     | webhooks.SendVendorUpdatedRequest
     | webhooks.SendVendorDestroyedRequest

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,