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

package/src/sdk/oauth.ts

@@ -1,198 +0,0 @@
-/*
- * 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,
-    ));
-  }
-}