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

package/dist/esm/sdk/apps.js

@@ -0,0 +1,447 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+import { appsAddAppDeveloper } from "../funcs/appsAddAppDeveloper.js";
+import { appsCloseAppDevSession } from "../funcs/appsCloseAppDevSession.js";
+import { appsCreateAppDevSession } from "../funcs/appsCreateAppDevSession.js";
+import { appsDeleteAppSecret } from "../funcs/appsDeleteAppSecret.js";
+import { appsFindAppSecret } from "../funcs/appsFindAppSecret.js";
+import { appsHeartbeatAppDevSession } from "../funcs/appsHeartbeatAppDevSession.js";
+import { appsListAppActivations } from "../funcs/appsListAppActivations.js";
+import { appsListAppDevelopers } from "../funcs/appsListAppDevelopers.js";
+import { appsListAppSecrets } from "../funcs/appsListAppSecrets.js";
+import { appsListAppVersions } from "../funcs/appsListAppVersions.js";
+import { appsPublishAppManifest } from "../funcs/appsPublishAppManifest.js";
+import { appsRemoveAppDeveloper } from "../funcs/appsRemoveAppDeveloper.js";
+import { appsRotateAppWebhookEndpointSecret } from "../funcs/appsRotateAppWebhookEndpointSecret.js";
+import { appsSetAppSecret } from "../funcs/appsSetAppSecret.js";
+import { ClientSDK } from "../lib/sdks.js";
+import { unwrapAsync } from "../types/fp.js";
+import { unwrapResultIterator } from "../types/operations.js";
+export class Apps extends ClientSDK {
+    /**
+     * List your app's activations
+     *
+     * @remarks
+     * Lists the activations (installations) of the apps your service account belongs to: which
+     * app, what each installation covers, and when it was made. A back-end-only app has no UI to
+     * be handed an activation id, so this is where its backend finds the `activation_id` it passes
+     * to `POST /oauth/token` with `grant_type=client_credentials` to get an installation token for
+     * one installation.
+     *
+     * To hear about installs as they happen, declare `webhooks` in your app's manifest: your app's
+     * own endpoint then receives `MarketplaceAppActivation.created`, `.updated` and `.destroyed`
+     * for every installation, the first one included. Use this list to reconcile, on start-up and
+     * after any delivery you could not process.
+     *
+     * Sorted by `id` unless `sort` says otherwise, ascending unless `desc` is set.
+     *
+     * **Permissions.** Accepts only the app service account's own unscoped token, as
+     * `Authorization: Bearer`: its permanent token, or an access token from `client_credentials`
+     * issued without `activation_id` or `scope`. App tokens (`gsu_`, `gsi_`, `gsd_`, and the
+     * `gsdr_` refresh token) are refused with `403` — an installation token acts as the same service
+     * account but is narrowed to one installation — and so is a token narrowed with `scope`. A
+     * `token` query parameter is refused with `401`, even alongside the header. A user that is not
+     * the service account of any app gets `403`.
+     */
+    async listAppActivations(request, options) {
+        return unwrapResultIterator(appsListAppActivations(this, request, options));
+    }
+    /**
+     * Rotate your app's webhook signing secret
+     *
+     * @remarks
+     * Issues a new signing secret for your app's own webhook endpoint (the one its manifest's
+     * `webhooks` declares) and returns it. This is the only way to obtain the secret, and the only
+     * response that ever carries it.
+     *
+     * Call it once after the first publish that adds `webhooks`: the endpoint is created with a
+     * secret nobody has seen, so deliveries fail your signature check until you rotate. Each retry
+     * is signed again when it is sent, so a delivery still being retried (for about 50 minutes after
+     * it was first sent) verifies once you have the new secret; reconcile anything older with
+     * `GET /marketplace/activations`. Call it again whenever you want to replace the secret or have lost it. After the
+     * first rotation, the secret being replaced keeps signing for 24 hours, next to the new one, so
+     * you can deploy the new secret without rejecting deliveries already on their way.
+     *
+     * Changing `webhooks.url` or `webhooks.events` in a later publish keeps the secret.
+     *
+     * **Permissions.** Accepts only the app service account's own unscoped token, as
+     * `Authorization: Bearer`: its permanent token, or an access token from `client_credentials`
+     * issued without `activation_id` or `scope`. App tokens (`gsu_`, `gsi_`, `gsd_`, and the
+     * `gsdr_` refresh token) and a token narrowed with `scope` are refused with `403`. A `token`
+     * query parameter is refused with `401`, even alongside the header. An app the caller is not the
+     * service account of reads as `404`, the same as one that does not exist.
+     */
+    async rotateAppWebhookEndpointSecret(request, options) {
+        return unwrapAsync(appsRotateAppWebhookEndpointSecret(this, request, options));
+    }
+    /**
+     * List app secrets
+     *
+     * @remarks
+     * Lists the secrets in one scope of your app's activation. Payloads are never included; use
+     * `GET /apps/secrets/find` with `expand=payload` to read one. Expired secrets are not
+     * listed.
+     *
+     * Sorted by `name` unless `sort` says otherwise, ascending unless `desc` is set.
+     *
+     * **Permissions.** Send one of these as `Authorization: Bearer`; any other token is refused
+     * with `403`.
+     *
+     * - **An app token**: an app user token (`gsu_`) or an app installation token (`gsi_`). The
+     *   activation comes from the token, so leave `activation_id` out; if you send it, it must be
+     *   the token's own activation (`403` otherwise). Either token may read the `installation`
+     *   scope. For the `user` scope:
+     *   - an app user token reaches only its own user (`user_id` may be left out);
+     *   - an installation token the host minted for one of your views reaches only that view's
+     *     viewer (`user_id` may be left out);
+     *   - an installation token from `client_credentials` reaches any user its activation
+     *     covers, and `user_id` is required.
+     * - **Your app's service account**: its permanent token, or a short-lived OAuth access token
+     *   issued to it without `scope` (by `client_credentials` without `activation_id`, or by the
+     *   `refresh_token` grant). A token issued with `scope` is refused with `403`, and any other
+     *   kind of token, such as a one-time sign-in link token, with `403` "This kind of token may
+     *   not access app secrets". It has no activation of its own, so `activation_id` is required
+     *   (`422` without it) and must be one of your app's activations (`403` otherwise). Its `user`
+     *   scope reaches any user the activation covers, and `user_id` is required.
+     *
+     * A `user_id` that does not exist and one the token may not reach get the same `403` "This
+     * credential may not access secrets of that user", so the endpoint never reveals which user
+     * ids exist.
+     *
+     * Whatever the token, your app must hold the platform permission `app_secrets.write`: list
+     * it in the manifest's `permissions` and upload. Until then every Secret Store call is
+     * refused with `403` "This app has not been granted app_secrets.write." For the service
+     * account this is checked before `activation_id` is looked at, so an app without the
+     * permission gets that answer whether or not it sent an `activation_id`.
+     *
+     * Every response carries `Cache-Control: no-store`, errors included, so no cache keeps a
+     * secret.
+     */
+    async listAppSecrets(request, options) {
+        return unwrapResultIterator(appsListAppSecrets(this, request, options));
+    }
+    /**
+     * Set an app secret
+     *
+     * @remarks
+     * Creates a secret, or replaces the payload and expiry of the secret with the same `name`
+     * in the same scope. Secrets are encrypted at rest and belong to one activation of your
+     * app: the app token's own activation, or the `activation_id` the service account sends.
+     * Removing that activation, or changing what it covers (its app, or the site, system,
+     * facility, company or user it is installed for), deletes all of its secrets.
+     *
+     * Each scope holds at most 25 secrets, and a payload is at most 8192 bytes once UTF-8
+     * encoded (fewer characters than that if it has multi-byte ones). `expires_at`, when
+     * given, must be in the future and less than 100 years away.
+     *
+     * **Permissions.** Send one of these as `Authorization: Bearer`; any other token is refused
+     * with `403`.
+     *
+     * - **An app token**: an app user token (`gsu_`) or an app installation token (`gsi_`). The
+     *   activation comes from the token, so leave `activation_id` out; if you send it, it must be
+     *   the token's own activation (`403` otherwise). Either token may write to the `installation`
+     *   scope. For the `user` scope:
+     *   - an app user token reaches only its own user (`user_id` may be left out);
+     *   - an installation token the host minted for one of your views reaches only that view's
+     *     viewer (`user_id` may be left out);
+     *   - an installation token from `client_credentials` reaches any user its activation
+     *     covers, and `user_id` is required.
+     * - **Your app's service account**: its permanent token, or a short-lived OAuth access token
+     *   issued to it without `scope` (by `client_credentials` without `activation_id`, or by the
+     *   `refresh_token` grant). A token issued with `scope` is refused with `403`, and any other
+     *   kind of token, such as a one-time sign-in link token, with `403` "This kind of token may
+     *   not access app secrets". It has no activation of its own, so `activation_id` is required
+     *   (`422` without it) and must be one of your app's activations (`403` otherwise). Its `user`
+     *   scope reaches any user the activation covers, and `user_id` is required.
+     *
+     * A `user_id` that does not exist and one the token may not reach get the same `403` "This
+     * credential may not access secrets of that user", so the endpoint never reveals which user
+     * ids exist.
+     *
+     * Whatever the token, your app must hold the platform permission `app_secrets.write`: list
+     * it in the manifest's `permissions` and upload. Until then every Secret Store call is
+     * refused with `403` "This app has not been granted app_secrets.write." For the service
+     * account this is checked before `activation_id` is looked at, so an app without the
+     * permission gets that answer whether or not it sent an `activation_id`.
+     *
+     * Every response carries `Cache-Control: no-store`, errors included, so no cache keeps a
+     * secret.
+     */
+    async setAppSecret(request, options) {
+        return unwrapAsync(appsSetAppSecret(this, request, options));
+    }
+    /**
+     * Find an app secret
+     *
+     * @remarks
+     * Returns the secret with `name` in the given scope. The payload is only included when you
+     * ask for it with `expand=payload`, so a lookup that only needs to know the secret exists
+     * never moves the value. An expired secret is reported as not found.
+     *
+     * **Permissions.** Send one of these as `Authorization: Bearer`; any other token is refused
+     * with `403`.
+     *
+     * - **An app token**: an app user token (`gsu_`) or an app installation token (`gsi_`). The
+     *   activation comes from the token, so leave `activation_id` out; if you send it, it must be
+     *   the token's own activation (`403` otherwise). Either token may read the `installation`
+     *   scope. For the `user` scope:
+     *   - an app user token reaches only its own user (`user_id` may be left out);
+     *   - an installation token the host minted for one of your views reaches only that view's
+     *     viewer (`user_id` may be left out);
+     *   - an installation token from `client_credentials` reaches any user its activation
+     *     covers, and `user_id` is required.
+     * - **Your app's service account**: its permanent token, or a short-lived OAuth access token
+     *   issued to it without `scope` (by `client_credentials` without `activation_id`, or by the
+     *   `refresh_token` grant). A token issued with `scope` is refused with `403`, and any other
+     *   kind of token, such as a one-time sign-in link token, with `403` "This kind of token may
+     *   not access app secrets". It has no activation of its own, so `activation_id` is required
+     *   (`422` without it) and must be one of your app's activations (`403` otherwise). Its `user`
+     *   scope reaches any user the activation covers, and `user_id` is required.
+     *
+     * A `user_id` that does not exist and one the token may not reach get the same `403` "This
+     * credential may not access secrets of that user", so the endpoint never reveals which user
+     * ids exist.
+     *
+     * Whatever the token, your app must hold the platform permission `app_secrets.write`: list
+     * it in the manifest's `permissions` and upload. Until then every Secret Store call is
+     * refused with `403` "This app has not been granted app_secrets.write." For the service
+     * account this is checked before `activation_id` is looked at, so an app without the
+     * permission gets that answer whether or not it sent an `activation_id`.
+     *
+     * Every response carries `Cache-Control: no-store`, errors included, so no cache keeps a
+     * secret.
+     */
+    async findAppSecret(request, options) {
+        return unwrapAsync(appsFindAppSecret(this, request, options));
+    }
+    /**
+     * Delete an app secret
+     *
+     * @remarks
+     * Deletes the secret with `name` in the given scope, and returns it with `deleted: true`.
+     *
+     * **Permissions.** Send one of these as `Authorization: Bearer`; any other token is refused
+     * with `403`.
+     *
+     * - **An app token**: an app user token (`gsu_`) or an app installation token (`gsi_`). The
+     *   activation comes from the token, so leave `activation_id` out; if you send it, it must be
+     *   the token's own activation (`403` otherwise). Either token may delete from the `installation`
+     *   scope. For the `user` scope:
+     *   - an app user token reaches only its own user (`user_id` may be left out);
+     *   - an installation token the host minted for one of your views reaches only that view's
+     *     viewer (`user_id` may be left out);
+     *   - an installation token from `client_credentials` reaches any user its activation
+     *     covers, and `user_id` is required.
+     * - **Your app's service account**: its permanent token, or a short-lived OAuth access token
+     *   issued to it without `scope` (by `client_credentials` without `activation_id`, or by the
+     *   `refresh_token` grant). A token issued with `scope` is refused with `403`, and any other
+     *   kind of token, such as a one-time sign-in link token, with `403` "This kind of token may
+     *   not access app secrets". It has no activation of its own, so `activation_id` is required
+     *   (`422` without it) and must be one of your app's activations (`403` otherwise). Its `user`
+     *   scope reaches any user the activation covers, and `user_id` is required.
+     *
+     * A `user_id` that does not exist and one the token may not reach get the same `403` "This
+     * credential may not access secrets of that user", so the endpoint never reveals which user
+     * ids exist.
+     *
+     * Whatever the token, your app must hold the platform permission `app_secrets.write`: list
+     * it in the manifest's `permissions` and upload. Until then every Secret Store call is
+     * refused with `403` "This app has not been granted app_secrets.write." For the service
+     * account this is checked before `activation_id` is looked at, so an app without the
+     * permission gets that answer whether or not it sent an `activation_id`.
+     *
+     * Every response carries `Cache-Control: no-store`, errors included, so no cache keeps a
+     * secret.
+     */
+    async deleteAppSecret(request, options) {
+        return unwrapAsync(appsDeleteAppSecret(this, request, options));
+    }
+    /**
+     * Publish an app manifest
+     *
+     * @remarks
+     * Publishes a new version of your marketplace app's manifest: its listing, the permissions
+     * it requests, its UI bundle and views, and the extra origins its sandbox may reach.
+     * `apps-cli upload` calls it after checking that the hosted bundle matches your local
+     * build.
+     *
+     * Every submission is reviewed against the app's last accepted version, and the response's
+     * `status` says what became of it: `accepted`, `screening` (the network sources it adds are
+     * being checked), `pending_review` (it adds a sensitive permission and waits for a Green
+     * Security admin) or `rejected`, with `review_reasons`. A rejection still answers `200`, with
+     * `success` false. Only an accepted version replaces the permissions granted to the app, and
+     * new installations get it. An installation it adds nothing for uses it from the next time
+     * its views are opened; one it adds permissions or network sources for keeps its version
+     * until one of its admins approves the new ones. So publish only once the bundle at
+     * `ui_extensions.bundle.url` is live and matches `integrity`, and keep earlier bundles
+     * hosted. An upload that repeats the last accepted manifest exactly changes nothing.
+     *
+     * Leave out `ui_extensions` to publish a back-end-only app, one with no views that works
+     * only through its service account (see the second example). With a `version`, the
+     * manifest may only send installers to a view it has: `post_install_action.type`
+     * `app_settings_view` needs a `settings` view, and `app_main_view` needs a view for a
+     * viewport other than `settings`, or the manifest is refused with `422`. So an app whose
+     * only view is `settings` uses `app_settings_view`, and a back-end-only app uses `url` or
+     * leaves `post_install_action` out. Left out, the action follows the app's views:
+     * `app_main_view`, `app_settings_view` for a settings-only app, or no post-install step for
+     * a back-end-only app.
+     *
+     * Each permission must be an existing Green Security permission or a platform permission
+     * such as `app_secrets.write` (see `AppManifestPermission`). A manifest that names any
+     * other permission is refused with `400` "Permission '<name>' not found." and writes
+     * nothing: the app, its role and its role's permissions are left as they were.
+     *
+     * **Permissions.** Accepts the app service account's permanent token, or a developer CLI
+     * token (`gsd_`) of a user who is an `owner` or `developer` of the app, as
+     * `Authorization: Bearer`. App user and installation tokens are refused.
+     */
+    async publishAppManifest(request, options) {
+        return unwrapAsync(appsPublishAppManifest(this, request, options));
+    }
+    /**
+     * List app developers
+     *
+     * @remarks
+     * Lists the users who may publish, preview and manage this app with the developer CLI,
+     * oldest first. An app has at most 100 developers.
+     *
+     * **Permissions.** Accepts the app service account's permanent token, or a developer CLI
+     * token (`gsd_`) of an `owner` of the app, as `Authorization: Bearer`. Anyone else, including
+     * a `developer` who is not an owner, is told the app does not exist (`404`).
+     */
+    async listAppDevelopers(request, options) {
+        return unwrapResultIterator(appsListAppDevelopers(this, request, options));
+    }
+    /**
+     * Add an app developer
+     *
+     * @remarks
+     * Makes a user an `owner` or `developer` of the app. Adding a user who is already on the
+     * list changes their role; demoting the app's last owner is refused with `409`, and so is
+     * adding a `developer` to an app that has no owner yet. Otherwise the response is `200`
+     * with the developer.
+     *
+     * The user must already be covered by an installation of the app. An app has at most 100
+     * developers: adding one more is refused with `422`, as is a request that does not send
+     * exactly one of `user_id` and `email`.
+     *
+     * **Permissions.** Accepts the app service account's permanent token, or a developer CLI
+     * token (`gsd_`) of an `owner` of the app, as `Authorization: Bearer`. Anyone else is told
+     * the app does not exist (`404`).
+     */
+    async addAppDeveloper(request, options) {
+        return unwrapAsync(appsAddAppDeveloper(this, request, options));
+    }
+    /**
+     * Remove an app developer
+     *
+     * @remarks
+     * Removes a user from the app's developers and closes their dev sessions for it. The app's
+     * last `owner` cannot be removed (`409`).
+     *
+     * **Permissions.** Accepts the app service account's permanent token, or a developer CLI
+     * token (`gsd_`) of an `owner` of the app, as `Authorization: Bearer`. Anyone else is told
+     * the app does not exist (`404`).
+     */
+    async removeAppDeveloper(request, options) {
+        return unwrapAsync(appsRemoveAppDeveloper(this, request, options));
+    }
+    /**
+     * List app versions with installation counts
+     *
+     * @remarks
+     * Lists every uploaded version of the app, with the review status of each and the number of
+     * installations that run it. `apps-cli status` shows the same information.
+     *
+     * The response is an object keyed by version string, in the order the versions were first
+     * uploaded. Every version is listed, including versions that are in review or
+     * rejected, which no installation runs. An app that hasn't been uploaded since review began has
+     * no versions yet, and the response is `{}`.
+     *
+     * A version that's uploaded more than once has one key. Its `status` is the status of the
+     * latest upload, and its counts cover every installation that runs an accepted upload of that
+     * version. A manifest without a `version` is listed under the key `""`.
+     *
+     * Each installation counts under the version it runs, which is the version its administrators
+     * last approved (see [Existing installations keep their version](/apps/security-and-review#existing-installations-keep-their-version)).
+     * **Site-wide installations aren't counted.** An installation for a whole site covers every
+     * user, company, facility, and health system in it, so the counts leave it out.
+     *
+     * **Permissions.** Accepts the app service account's permanent token, or the developer CLI
+     * token (`gsd_`, from `apps-cli login`) of an `owner` or `developer` of the app, as
+     * `Authorization: Bearer`. Any other app token gets `403`. Anyone else gets `404`, the same
+     * response as for an app id that doesn't exist. That includes a developer signed in with a
+     * browser session.
+     */
+    async listAppVersions(request, options) {
+        return unwrapAsync(appsListAppVersions(this, request, options));
+    }
+    /**
+     * Start a dev session
+     *
+     * @remarks
+     * Registers a dev session, which is what `gs-apps dev` does on start. While the session is
+     * active, the Green Security app loads your views from the CLI's dev server at `origin`
+     * instead of the published bundle, for you only: other users of the same tenant keep
+     * seeing the published version. Every build the dev server announces must be signed with
+     * the private half of `public_key_jwk`.
+     *
+     * Starting a session closes any earlier session of yours for the same app. A session lasts
+     * 12 hours and counts as inactive after 2 minutes without a heartbeat, so call
+     * `POST /apps/{app_id}/dev-sessions/{id}/heartbeat` every 30 seconds.
+     *
+     * A `422` means a field failed validation: `origin`, `server_token`, `public_key_jwk` or
+     * `manifest` is malformed, `manifest` changes a field a dev session may not (see
+     * `AppDevManifest`), or several installations cover you and `activation_id` was left out.
+     *
+     * The response never includes `server_token`: you generated it, so keep your own copy.
+     *
+     * Dev sessions are available on staging, and in production only for apps an administrator
+     * has enabled dev preview for; otherwise this endpoint answers `403`.
+     *
+     * **Permissions.** Requires a developer CLI token (`gsd_`, from `gs-apps login`) of an
+     * `owner` or `developer` of the app, as `Authorization: Bearer`. Any other token, including
+     * your own session token and the app's service account token, is refused with `403`. An app
+     * you are not a developer of is reported as not found.
+     */
+    async createAppDevSession(request, options) {
+        return unwrapAsync(appsCreateAppDevSession(this, request, options));
+    }
+    /**
+     * Close a dev session
+     *
+     * @remarks
+     * Closes a dev session, which is what `apps-cli dev` does on exit. The Green Security app
+     * goes back to the published bundle once the session has ended. Closing a session that
+     * is already closed or expired succeeds too.
+     *
+     * **Permissions.** Requires the developer CLI token (`gsd_`) of the developer who started
+     * the session, as `Authorization: Bearer`. Another developer's session is reported as not
+     * found.
+     */
+    async closeAppDevSession(request, options) {
+        return unwrapAsync(appsCloseAppDevSession(this, request, options));
+    }
+    /**
+     * Keep a dev session alive
+     *
+     * @remarks
+     * Marks a dev session as still running. Call it every 30 seconds; a session with no
+     * heartbeat for 2 minutes is treated as inactive and the host stops using it until the next
+     * heartbeat. A heartbeat does not extend the 12-hour lifetime.
+     *
+     * Access is checked again on every heartbeat. A `404` means the session was closed,
+     * expired or replaced by a newer one, or you are no longer a developer of the app; a `403`
+     * means dev preview has been switched off for the app. Either way the session is closed:
+     * start a new one with `POST /apps/{app_id}/dev-sessions` once the cause is resolved.
+     *
+     * **Permissions.** Requires the developer CLI token (`gsd_`) of the developer who started
+     * the session, as `Authorization: Bearer`. Another developer's session is reported as not
+     * found.
+     */
+    async heartbeatAppDevSession(request, options) {
+        return unwrapAsync(appsHeartbeatAppDevSession(this, request, options));
+    }
+}
+//# sourceMappingURL=apps.js.map

package/dist/esm/sdk/apps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apps.js","sourceRoot":"","sources":["../../../src/sdk/apps.ts"],"names":[],"mappings":"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"}

package/dist/esm/sdk/oauth.d.ts

@@ -0,0 +1,150 @@
+import { ClientSDK, RequestOptions } from "../lib/sdks.js";
+import * as components from "../models/components/index.js";
+import * as operations from "../models/operations/index.js";
+export declare 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.
+     */
+    createToken(request: components.OAuthTokenRequest, options?: RequestOptions): Promise<components.TokenResponse>;
+    /**
+     * 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.
+     */
+    createDeviceAuthorization(request: components.DeviceAuthorizationRequest, options?: RequestOptions): Promise<components.DeviceAuthorizationResponse>;
+    /**
+     * 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.
+     */
+    introspectToken(request: components.TokenIntrospectionRequest, options?: RequestOptions): Promise<components.TokenIntrospection>;
+    /**
+     * 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.
+     */
+    revokeToken(request: components.TokenRevocationRequest, options?: RequestOptions): Promise<operations.RevokeTokenRevokeTokenOk>;
+}
+//# sourceMappingURL=oauth.d.ts.map

package/dist/esm/sdk/oauth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../../../src/sdk/oauth.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,KAAK,UAAU,MAAM,+BAA+B,CAAC;AAC5D,OAAO,KAAK,UAAU,MAAM,+BAA+B,CAAC;AAG5D,qBAAa,KAAM,SAAQ,SAAS;IAClC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoDG;IACG,WAAW,CACf,OAAO,EAAE,UAAU,CAAC,iBAAiB,EACrC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC;IAQpC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,yBAAyB,CAC7B,OAAO,EAAE,UAAU,CAAC,0BAA0B,EAC9C,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,CAAC,2BAA2B,CAAC;IAQlD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACG,eAAe,CACnB,OAAO,EAAE,UAAU,CAAC,yBAAyB,EAC7C,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,CAAC,kBAAkB,CAAC;IAQzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACG,WAAW,CACf,OAAO,EAAE,UAAU,CAAC,sBAAsB,EAC1C,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,CAAC,wBAAwB,CAAC;CAOhD"}