@greensecurity/javascript-sdk 0.46.0-beta.8 → 0.46.0-beta.9

package/src/sdk/oauth.ts

@@ -0,0 +1,198 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { oauthCreateDeviceAuthorization } from "../funcs/oauthCreateDeviceAuthorization.js";
+import { oauthCreateToken } from "../funcs/oauthCreateToken.js";
+import { oauthIntrospectToken } from "../funcs/oauthIntrospectToken.js";
+import { oauthRevokeToken } from "../funcs/oauthRevokeToken.js";
+import { ClientSDK, RequestOptions } from "../lib/sdks.js";
+import * as components from "../models/components/index.js";
+import * as operations from "../models/operations/index.js";
+import { unwrapAsync } from "../types/fp.js";
+
+export class Oauth extends ClientSDK {
+  /**
+   * Issue an access, app or developer token
+   *
+   * @remarks
+   * The OAuth 2.0 token endpoint. It issues four kinds of short-lived token, chosen by
+   * `grant_type`:
+   *
+   * | Grant | Authenticate with | Issues |
+   * | --- | --- | --- |
+   * | `urn:ietf:params:oauth:grant-type:token-exchange` | The user's session token, as `subject_token` | An app user token (`gsu_`) or an app installation token (`gsi_`), 15 minutes |
+   * | `client_credentials` with `activation_id` | The app service account's `client_id` and `client_secret`, or its permanent token as `Authorization: Bearer` | An app installation token (`gsi_`), 15 minutes |
+   * | `client_credentials` without `activation_id` | An API service account's `client_id` and `client_secret`, or its permanent token as `Authorization: Bearer` | A plain API access token, 15 minutes |
+   * | `refresh_token` (service account) | The service account's `client_id` and `client_secret`, and a `refresh_token` | A plain API access token, 15 minutes, and a new refresh token |
+   * | `refresh_token` (apps CLI) | A `gsdr_` refresh token and `client_id=greensecurity-apps-cli`, no secret | A new developer CLI token (`gsd_`), 15 minutes, and a new `gsdr_` refresh token |
+   * | `urn:ietf:params:oauth:grant-type:device_code` | The `device_code` from `POST /oauth/device_authorization` | A developer CLI token (`gsd_`), 15 minutes, and a `gsdr_` refresh token |
+   *
+   * Token exchange is what the Green Security app does when it opens an app's views: the user
+   * must be covered by an activation of the app named in `audience`. `client_credentials` with
+   * `activation_id` is for the app's own backend. Without `activation_id`, `client_credentials`
+   * and a service account's `refresh_token` are the API service account flows: the response is
+   * a plain access token with no `issued_token_type` and no `activation_id` (see
+   * `TokenResponse`). An app token can never be used to obtain another token.
+   *
+   * The apps CLI logs in with the device grant and then renews its 15-minute developer token
+   * with the public-client `refresh_token` grant. Refresh tokens rotate and are single-use;
+   * presenting a spent one revokes the whole login, except for a retry within 30 seconds whose
+   * replacement is still unused. A login lasts at most 90 days from its device authorization.
+   * See `OAuthCliRefreshTokenGrant`.
+   *
+   * Every grant takes an optional `scope`, which can only narrow the token: it gets what was
+   * requested intersected with what the client is allowed, and if that is empty the request
+   * fails with `invalid_scope`. A refreshed token is never wider than the one it replaces.
+   *
+   * The request body may be JSON or `application/x-www-form-urlencoded`, and every parameter
+   * must be in the body: one sent in the query string is refused with `invalid_request`. Errors
+   * follow RFC 6749 and use `OAuthError` rather than the usual error envelope, including a
+   * body that fails validation (`400` `invalid_request`, never `422`). For the device grant,
+   * `authorization_pending` and `slow_down` mean "poll again later", not failure.
+   *
+   * Only `client_credentials` reads `Authorization`, and only when the body carries neither
+   * `client_id` nor `client_secret`. It accepts only the service account's permanent token
+   * there: a short-lived token (including one this endpoint issued), a narrowed token or an app
+   * token (`gsu_`, `gsi_`, `gsd_`) is answered `401` `invalid_client`, so a token can never be
+   * renewed or widened by presenting it. The other grants ignore the header.
+   *
+   * A narrowed `subject_token` is refused with `invalid_grant`, and a locked service account
+   * gets `401` `invalid_client` on `client_credentials` and `refresh_token`.
+   *
+   * Every response, errors included, carries `Cache-Control: no-store` and `Pragma: no-cache`
+   * (RFC 6749 section 5.1), so no cache keeps a token or code.
+   *
+   * **Permissions.** No named permission.
+   */
+  async createToken(
+    request: components.OAuthTokenRequest,
+    options?: RequestOptions,
+  ): Promise<components.TokenResponse> {
+    return unwrapAsync(oauthCreateToken(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Start a device login
+   *
+   * @remarks
+   * Starts the RFC 8628 device authorization flow that `apps-cli login` uses:
+   *
+   * 1. Call this endpoint and show the user `user_code`, or open `verification_uri_complete`.
+   * 2. The user approves the request in the Green Security app, signed in as themselves.
+   * 3. Meanwhile, poll `POST /oauth/token` with
+   *    `grant_type=urn:ietf:params:oauth:grant-type:device_code` every `interval` seconds.
+   *    It answers `authorization_pending` until the user approves, and then returns a
+   *    15-minute developer CLI token and a refresh token that renews it, for up to 90 days.
+   *
+   * The codes expire after `expires_in` seconds. Each address may start 20 logins per ten
+   * minutes; past that the endpoint answers `429` with `slow_down`. The request body may be
+   * JSON or `application/x-www-form-urlencoded`.
+   *
+   * Every response, errors included, carries `Cache-Control: no-store` and `Pragma: no-cache`
+   * (RFC 6749 section 5.1), so no cache keeps a token or code.
+   *
+   * **Permissions.** No authentication required.
+   */
+  async createDeviceAuthorization(
+    request: components.DeviceAuthorizationRequest,
+    options?: RequestOptions,
+  ): Promise<components.DeviceAuthorizationResponse> {
+    return unwrapAsync(oauthCreateDeviceAuthorization(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Check an app token
+   *
+   * @remarks
+   * RFC 7662 token introspection, for your app's backend. When your app's UI calls your own
+   * API it sends the app user token it was given; call this endpoint to confirm the token is
+   * live and find out which user, app and activation it belongs to before you act on it.
+   *
+   * A back-end-only app (a manifest with no `ui_extensions`) has no UI, so no user token
+   * ever reaches it, and the installation tokens it uses it mints itself with
+   * `client_credentials`. It needs this endpoint only to check an app token that another
+   * party sends it.
+   *
+   * Only app user and app installation tokens issued to your own app are reported as
+   * `active`. Any other token, whether unknown, expired, revoked, another app's, a developer
+   * CLI token, or one whose user has since been locked, returns `{"active": false}` with a
+   * `200`, never an error.
+   *
+   * The request body may be JSON or `application/x-www-form-urlencoded`.
+   *
+   * Every response, errors included, carries `Cache-Control: no-store` and `Pragma: no-cache`
+   * (RFC 6749 section 5.1), so no cache keeps a token or code.
+   *
+   * **Permissions.** Only your app service account's permanent token is accepted, as
+   * `Authorization: Bearer`. A short-lived or narrowed token (including one from
+   * `client_credentials`), a locked service account's token, or a token of a user who is not
+   * an API service account is refused with `401` `invalid_client`. Every app token is refused
+   * the same way, and that includes installation tokens (`gsi_`): the host also hands those to
+   * your app's sandboxed UI, so accepting them here would let code running in the UI introspect
+   * tokens. Keep the service account token on your backend.
+   */
+  async introspectToken(
+    request: components.TokenIntrospectionRequest,
+    options?: RequestOptions,
+  ): Promise<components.TokenIntrospection> {
+    return unwrapAsync(oauthIntrospectToken(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Revoke a token
+   *
+   * @remarks
+   * RFC 7009 token revocation. Revokes an app user, app installation or developer CLI token,
+   * or an apps CLI refresh token, immediately. Revoking any token of an apps CLI login (its
+   * `gsd_` developer token or its `gsdr_` refresh token) revokes every token of that login.
+   * `apps-cli logout` sends its refresh token this way.
+   *
+   * Once the caller is authenticated the response is `200` with `{}`, whether or not anything
+   * was revoked, so it cannot be used to probe for valid tokens. A token the caller may not
+   * revoke is left alone.
+   *
+   * The request body may be JSON or `application/x-www-form-urlencoded`.
+   *
+   * Every response, errors included, carries `Cache-Control: no-store` and `Pragma: no-cache`
+   * (RFC 6749 section 5.1), so no cache keeps a token or code.
+   *
+   * **Permissions.** For an apps CLI refresh token, send `token=gsdr_…` with
+   * `client_id=greensecurity-apps-cli` and no `Authorization` (RFC 7009 public client). It
+   * always answers `200`.
+   *
+   * Otherwise send one of these as `Authorization: Bearer`:
+   *
+   * - the token being revoked, which may revoke itself (a `gsd_` token may also revoke any
+   *   token of its own login), and no other token;
+   * - an unscoped token (session, permanent, or an access token issued without `scope`) of the
+   *   token's subject, or of the user whose view caused it to be issued;
+   * - an unscoped token of the service account of the app it was issued for.
+   *
+   * A narrowed token (an access token issued with `scope`) is refused with `401`
+   * `invalid_client`: its scope says nothing about revoking the caller's other tokens. So is
+   * the token of a locked user.
+   */
+  async revokeToken(
+    request: components.TokenRevocationRequest,
+    options?: RequestOptions,
+  ): Promise<operations.RevokeTokenRevokeTokenOk> {
+    return unwrapAsync(oauthRevokeToken(
+      this,
+      request,
+      options,
+    ));
+  }
+}

package/src/sdk/sdk.ts

@@ -7,6 +7,7 @@ import { ClientSDK } from "../lib/sdks.js";
 import * as webhooks from "../models/webhooks/index.js";
 import { unwrapAsync } from "../types/fp.js";
 import { Alerts } from "./alerts.js";
+import { Apps } from "./apps.js";
 import { Companies } from "./companies.js";
 import { DataRequests } from "./datarequests.js";
 import { Events } from "./events.js";
@@ -15,6 +16,7 @@ import { Invoices } from "./invoices.js";
 import { Lookups } from "./lookups.js";
 import { MedicalProducts } from "./medicalproducts.js";
 import { MobileDevices } from "./mobiledevices.js";
+import { Oauth } from "./oauth.js";
 import { Organizations } from "./organizations.js";
 import { PaymentProfile } from "./paymentprofile.js";
 import { Reports } from "./reports.js";
@@ -63,6 +65,11 @@ export class GreenSecurity extends ClientSDK {
     return (this._webhooks ??= new Webhooks(this._options));
   }
 
+  private _apps?: Apps;
+  get apps(): Apps {
+    return (this._apps ??= new Apps(this._options));
+  }
+
   private _vendorScans?: VendorScans;
   get vendorScans(): VendorScans {
     return (this._vendorScans ??= new VendorScans(this._options));
@@ -128,6 +135,11 @@ export class GreenSecurity extends ClientSDK {
     return (this._reports ??= new Reports(this._options));
   }
 
+  private _oauth?: Oauth;
+  get oauth(): Oauth {
+    return (this._oauth ??= new Oauth(this._options));
+  }
+
   async validateWebhook({
     request,
     secret,
@@ -143,6 +155,9 @@ export class GreenSecurity extends ClientSDK {
     | webhooks.SendFullReportCreatedRequest
     | webhooks.SendFullReportUpdatedRequest
     | webhooks.SendFullReportDestroyedRequest
+    | webhooks.SendMarketplaceAppActivationCreatedRequest
+    | webhooks.SendMarketplaceAppActivationUpdatedRequest
+    | webhooks.SendMarketplaceAppActivationDestroyedRequest
     | webhooks.SendVendorCreatedRequest
     | webhooks.SendVendorUpdatedRequest
     | webhooks.SendVendorDestroyedRequest

package/src/sdk/vendors.ts

@@ -1199,6 +1199,9 @@ export class Vendors extends ClientSDK {
    * turned off. The company must be on the same site as the vendor. Otherwise, the API returns
    * `404`.
    *
+   * The company the vendor belongs to can't be added, because it already has full rights over the
+   * vendor. The API returns `400`, as it does for a company that already manages the vendor.
+   *
    * **Permissions.** Requires the `vendors.edit` permission. Only these callers can change which
    * companies manage the vendor: the vendor, a company manager at the company the vendor belongs to,
    * a Green Security administrator, or an app whose API token can update the vendor (an app