@pega/sdk 0.0.13 → 0.0.15

package/templates/react-sdk-reference/.ai-common/skills/embedded-flow/authenticate.md

@@ -1,311 +0,0 @@
-# Skill: Authenticate to Pega
-
-Establish an authenticated OAuth 2.0 session against the customer's Pega server, persist the resulting token locally, and use it to make DX API calls.
-
-> **This skill is not part of the embedded flow.** The embedded flow resolves case types, their starting fields, and their components through the Pega MCP server, and the wired application authenticates itself in the browser at runtime — so no design-time token is needed and no workflow invokes this skill. Do not run it as a prerequisite to embedding, and do not let it write configuration that the embedded flow depends on. It remains available for making DX API calls directly.
-
----
-
-## Purpose
-
-The embedded flow needs to know which case type to embed, which components that case requires, and how the customer's Pega environment is configured. All of that lives on the Pega server behind an OAuth-protected DX API.
-
-This skill collects connection details, writes them to `.pega-auth.json`, and invokes `npx pega-auth` — the headless CLI shipped inside the `@pega/auth` package — to exchange them for an access token, enrich the token with Constellation bootstrap data, and store it for reuse.
-
-Once complete, the agent can call:
-
-- `/api/application/v2/casetypes` — to list case types and present a pick-list
-- `/api/application/v2/data_views/{D_page}` — to read any data page
-- `D_pxBootstrapConfig` — to read Constellation runtime configuration
-
----
-
-## Prerequisites
-
-- A reachable Pega Infinity or Launchpad server
-- An **OAuth 2.0 Client Registration** record on that server, configured for the grant type being used
-- For the authorization-code grant: a redirect URI registered on that client record, and a browser available on the machine running the flow
-- For the client-credentials grant: the client registration must be enabled for client credentials and mapped to an operator with DX API access
-
----
-
-## Storage Contract
-
-Two files at the project root. **Both must be gitignored.**
-
-| File               | Contents                                                            | Committed? |
-| ------------------ | ------------------------------------------------------------------- | ---------- |
-| `.pega-auth.json`  | Collected connection details, including `clientSecret` / `password` | ❌ Never   |
-| `.pega-token.json` | The raw token response, plus `C11NB2S` and `appStaticContentServer` | ❌ Never   |
-| `sdk-config.json`  | Non-secret runtime values only                                      | ✅ Yes     |
-
-⚠️ **`sdk-config.json` is served publicly at the application's web root.** Anything written into it is retrievable by any visitor. Client secrets and passwords must never be written there.
-
-`.pega-auth.json` shape:
-
-```json
-{
-  "serverType": "infinity",
-  "server": "https://example.pega.com/prweb",
-  "grantType": "clientCreds",
-  "authService": "pega",
-  "redirectUri": "https://localhost:4010/",
-  "clientId": "...",
-  "clientSecret": "...",
-  "user": "",
-  "password": "",
-  "isolationId": "",
-  "appAlias": "MediaCo"
-}
-```
-
-`.pega-token.json` shape (the token endpoint response, plus two enrichment fields):
-
-```json
-{
-  "token_type": "Bearer",
-  "access_token": "...",
-  "refresh_token": "...",
-  "expires_in": 3600,
-  "obtained_at": 1753833600000,
-  "C11NB2S": "...",
-  "appStaticContentServer": "https://..."
-}
-```
-
----
-
-## Steps
-
-### Step 1 — Detect an existing session
-
-Read `.pega-token.json` if it exists.
-
-- If it contains an `access_token` and `obtained_at + expires_in * 1000` is still in the future, tell the user which server the session belongs to and ask whether to reuse it. On reuse, **skip to Step 6**.
-- If the token is expired and a `refresh_token` is present, attempt a refresh (Step 4c) before falling back to a full re-authentication.
-- If no token file exists, continue to Step 2.
-
-Never print the token value itself — refer to it only by its presence and expiry.
-
-### Step 2 — Collect connection details
-
-Ask for each value below **in this order**. Only ask a question when its condition is met.
-
-| #   | Prompt                                                                   | Key            | Default                        | Ask when                                                                                              |
-| --- | ------------------------------------------------------------------------ | -------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------- |
-| 1   | Enter Pega server type                                                   | `serverType`   | `infinity`                     | Always                                                                                                |
-| 2   | Enter Pega server url                                                    | `server`       | `https://localhost:1080/prweb` | Always                                                                                                |
-| 3   | Enter OAuth 2.0 grant type                                               | `grantType`    | `authCode`                     | Always                                                                                                |
-| 4   | Enter authentication service alias                                       | `authService`  | `pega`                         | `serverType` is `infinity` **and** `grantType` is `authCode`                                          |
-| 5   | Enter valid redirect URI within the OAuth 2.0 client registration record | `redirectUri`  | `https://localhost:4010/`      | `serverType` is `infinity` **and** `grantType` is `authCode`                                          |
-| 6   | Enter user id                                                            | `user`         | —                              | `serverType` is `infinity` **and** `grantType` is `passwordCreds`                                     |
-| 7   | Enter password                                                           | `password`     | —                              | `user` was answered **and** `serverType` is `infinity` **and** `grantType` is `passwordCreds`         |
-| 8   | Enter clientId                                                           | `clientId`     | —                              | Always                                                                                                |
-| 9   | Enter clientSecret                                                       | `clientSecret` | —                              | (`serverType` is `infinity` **and** `grantType` is not `authCode`) **or** `serverType` is `launchpad` |
-
-**Allowed values:**
-
-| Key          | Values                                                                                                      |
-| ------------ | ----------------------------------------------------------------------------------------------------------- |
-| `serverType` | `infinity`, `launchpad`                                                                                     |
-| `grantType`  | `authCode` (Authorization code), `passwordCreds` (Password credentials), `clientCreds` (Client credentials) |
-
-`passwordCreds` is **not supported on Launchpad** — omit it from the choices when `serverType` is `launchpad`.
-
-**Launchpad only:** additionally ask for `isolationId` if the customer's Launchpad tenant requires one.
-
-**Pre-filling (do not re-ask what is already known):**
-
-Resolve each value from the first source that has a non-empty entry:
-
-1. `.pega-auth.json`
-2. `sdk-config.json` — `serverConfig.infinityRestServerUrl` → `server`, `serverConfig.appAlias` → `appAlias`, `authConfig.authService` → `authService`, `authConfig.mashupClientId` → `clientId`, `authConfig.mashupUserIdentifier` → `user`
-3. The defaults in the table above
-
-Present the resolved values as a summary and ask the user to **confirm or amend** them, rather than prompting for each one individually. Only fall back to asking question-by-question for values that could not be resolved.
-
-**Secret handling:** never ask the user to paste a `clientSecret` or `password` into chat if it can be avoided. Prefer reading them from an environment variable (`PEGA_CLIENT_SECRET`, `PEGA_PASSWORD`) or from an existing `.pega-auth.json`. If the user must supply one, tell them to place it in `.pega-auth.json` directly and confirm when done.
-
-**Normalization:** ensure `server` and `redirectUri` end with a trailing `/` before building any URL from them, then join path segments without duplicating slashes.
-
-### Step 3 — Persist the collected configuration
-
-Write the confirmed values to `.pega-auth.json`. Confirm the file is gitignored (see Step 7) **before** writing any secret into it.
-
-### Step 4 — Obtain an access token
-
-Run the `@pega/auth` headless CLI from the project root:
-
-```
-npx pega-auth
-```
-
-The CLI reads `.pega-auth.json`, performs the OAuth token exchange, and writes `.pega-token.json`. It handles all grant types, token refresh, enrichment, and `sdk-config.json` synchronization in a single invocation.
-
-**What the CLI does internally (for reference — the agent does not need to replicate this):**
-
-1. Checks `.pega-token.json` for an unexpired token — reuses if fresh
-2. Attempts `refresh_token` exchange if the token is expired but a refresh token exists
-3. Falls back to full authentication using the `grantType` in `.pega-auth.json`
-4. For `authCode`: opens the system browser for OAuth consent (requires a human to complete)
-5. For `clientCreds` / `passwordCreds`: completes headlessly with no interaction
-6. On success: writes token to `.pega-token.json`, fetches `D_pxBootstrapConfig` (Infinity only), and mirrors non-secret values into `sdk-config.json`
-
-**Exit codes:**
-
-| Code | Meaning                                                        |
-| ---- | -------------------------------------------------------------- |
-| `0`  | Success — token is fresh and `.pega-token.json` is ready       |
-| `1`  | Invalid config or missing `.pega-auth.json`                    |
-| `2`  | Authentication failed (bad credentials, disabled client, etc.) |
-
-**CLI options (all optional):**
-
-| Flag                  | Default            | Purpose                   |
-| --------------------- | ------------------ | ------------------------- |
-| `--config <path>`     | `.pega-auth.json`  | Path to auth config file  |
-| `--token <path>`      | `.pega-token.json` | Path to token output file |
-| `--sdk-config <path>` | `sdk-config.json`  | Path to SDK config file   |
-
-**Environment variable overrides:**
-
-Secrets can be supplied via environment variables instead of writing them into `.pega-auth.json`:
-
-| Variable             | Overrides      |
-| -------------------- | -------------- |
-| `PEGA_CLIENT_SECRET` | `clientSecret` |
-| `PEGA_PASSWORD`      | `password`     |
-
-**Interpreting output:**
-
-All CLI output goes to stderr. On exit code `0`, read `.pega-token.json` to confirm `access_token` is present and proceed to Step 5.
-
-On a non-zero exit code, read stderr for the specific error and consult the Troubleshooting section.
-
-**Notes:**
-
-- The CLI reads secrets from `.pega-auth.json` or env vars — they never appear on the command line or in the process list.
-- Local/lab servers with self-signed certificates are handled via `"ignoreInvalidCerts": true` in `.pega-auth.json`.
-- The `authCode` grant opens a browser and a local HTTPS listener on the configured `redirectUri`. A human must complete consent in the browser.
-- Prefer `clientCreds` for agent-driven workflows — it requires no human interaction.
-
-### Step 5 — Verify enrichment
-
-**Infinity only.** Launchpad has no equivalent step — skip it.
-
-The CLI (Step 4) automatically fetches `D_pxBootstrapConfig` and writes the enrichment values into `.pega-token.json`. Verify they are present:
-
-| Field in `.pega-token.json` | Source (fetched by the CLI)                         | Purpose                               |
-| --------------------------- | --------------------------------------------------- | ------------------------------------- |
-| `C11NB2S`                   | `pyConfigJSON.tokens.C11NB2S`                       | Constellation browser-to-server token |
-| `appStaticContentServer`    | `pyConfigJSON.serviceConfig.appStaticContentServer` | Static content CDN URL                |
-
-If these fields are missing (the CLI prints a warning when enrichment fails), the token is still valid for DX API calls but the runtime won't have CDN configuration. The most common cause is a `403` on `D_pxBootstrapConfig` — the operator's access group lacks the Constellation runtime privilege.
-
-**Verification criterion:** `.pega-token.json` contains both `access_token` and `C11NB2S`.
-
-### Step 6 — Verify the session and make DX API calls
-
-All DX API v2 calls use the same authorization header:
-
-```
-Authorization: Bearer {access_token}
-```
-
-When an `appAlias` is configured, address the application-scoped base instead of the default one:
-
-| Scope               | Base URL                                     |
-| ------------------- | -------------------------------------------- |
-| Default application | `{server}/api/application/v2`                |
-| Aliased application | `{server}/app/{appAlias}/api/application/v2` |
-
-Because `server` already includes the context root, the aliased base resolves to e.g. `https://example.pega.com/prweb/app/MediaCo/api/application/v2`. Do not add a second context-root segment.
-
-These operations belong to the **Constellation DX APIs** service package. To confirm exact paths, parameters, and response schemas for a given Infinity version, open the API explorer on the target server and select that service package.
-
-**List case types** — this is what allows the case type to be chosen from a list rather than typed:
-
-```
-GET {base}/casetypes
-```
-
-This operation takes **no parameters**. The response has the shape:
-
-| Field                                  | Meaning                                                                                             |
-| -------------------------------------- | --------------------------------------------------------------------------------------------------- |
-| `applicationIsConstellationCompatible` | Whether the application can run Constellation at all                                                |
-| `caseTypes[].ID`                       | The **fully qualified class name** (e.g. `DIXL-MediaCo-Work-NewService`) — this is the value needed |
-| `caseTypes[].name`                     | Display label to show the user                                                                      |
-| `caseTypes[].links`                    | Creation affordance — `href`, `rel`, `type`, and a `request_body` describing the create payload     |
-
-⛔ **Check `applicationIsConstellationCompatible` first.** If it is `false`, stop and tell the user that the target application is not Constellation-compatible and the embedded flow cannot work against it. Do not proceed to analysis, generation, or wiring — the failure would otherwise only surface much later as an unexplained runtime error.
-
-Present `caseTypes` to the user as a numbered pick-list of `name — ID` pairs and have them choose one. The chosen `ID` is the fully qualified class name. The endpoint already returns only the case types the authenticated operator is permitted to create, so no additional filtering is required.
-
-`links.request_body` describes the payload accepted when creating a case of that type — use it to determine which starting field values the mashup API call can supply (see Step 4 of the wire-integration skill).
-
-**Read any data page:**
-
-| Method                            | Usage                                                                  |
-| --------------------------------- | ---------------------------------------------------------------------- |
-| `GET {base}/data_views/{D_page}`  | Parameters passed as query-string values                               |
-| `POST {base}/data_views/{D_page}` | Parameters passed in a `dataViewParameters` object in the request body |
-
-Use `GET` for parameterless or simply-parameterized pages; use `POST` when the page takes structured parameters or when paging/filtering options are needed.
-
-**Verification criterion:** the case types request returns HTTP 200 with a parsable JSON body containing at least one entry. A `401` means the token is invalid or expired; a `403` means the token is valid but the operator's access group lacks the required privilege.
-
-### Step 7 — Mirror non-secret values into `sdk-config.json`
-
-The CLI (Step 4) automatically syncs non-secret values into `sdk-config.json`. After the CLI completes, the following fields are set:
-
-| `sdk-config.json` field              | Source        |
-| ------------------------------------ | ------------- |
-| `serverConfig.infinityRestServerUrl` | `server`      |
-| `serverConfig.appAlias`              | `appAlias`    |
-| `authConfig.authService`             | `authService` |
-| `authConfig.mashupClientId`          | `clientId`    |
-| `authConfig.portalClientId`          | `clientId`    |
-
-The **one field the CLI does not set** is `serverConfig.appMashupCaseType` — that requires the case type chosen in Step 6. After the user picks a case type, write its `ID` into this field.
-
-⚠️ **`portalClientId` must be non-empty.** If it is missing, the SDK's authentication initializer classifies the session as custom-auth and returns without ever resolving its readiness promise — producing a silent, permanent hang with no network activity and no error. See Step 2 of the wire-integration skill. The CLI ensures this is always populated.
-
-The CLI leaves `authConfig.portalClientSecret`, `authConfig.portalGrantType`, and `authConfig.mashupPassword` present but empty. Secrets are never written to this file.
-
----
-
-## Security Notes
-
-- `.pega-auth.json` and `.pega-token.json` hold live credentials. Confirm both are gitignored before writing to them, and re-confirm with `git status --ignored` afterwards.
-- Never echo an access token, refresh token, client secret, or password back to the user, into a log, or into a commit message. Refer to them by name only.
-- Prefer `clientCreds` over `passwordCreds` — it avoids handling an end-user password entirely.
-- Treat relaxed TLS verification as a local-development affordance only. Never suggest it for a production or shared environment.
-- If a secret is ever pasted into chat or committed by accident, tell the user to rotate the OAuth client registration record — the value must be considered compromised.
-
----
-
-## Troubleshooting
-
-| Symptom                                                    | Cause                                                                                                        | Resolution                                                                                                                                                          |
-| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `401` with `invalid_client` from the token endpoint        | `clientId` / `clientSecret` do not match an OAuth client registration record, or the record is disabled      | Verify the values against the client registration record in Dev Studio. Confirm the record is enabled.                                                              |
-| `401` with `invalid_grant`                                 | The grant type requested is not enabled on the client registration record, or the user credentials are wrong | Enable the grant on the record, or correct `user` / `password`.                                                                                                     |
-| `unsupported_grant_type` on Launchpad with `passwordCreds` | Launchpad does not support the password grant                                                                | Use `authCode` or `clientCreds`.                                                                                                                                    |
-| TLS handshake fails / self-signed certificate error        | Local or lab server presents an untrusted certificate                                                        | Add `"ignoreInvalidCerts": true` to `.pega-auth.json` and re-run `npx pega-auth`. Only use against local/lab servers.                                               |
-| `404` on the token endpoint                                | `server` is missing the `/prweb` context root, or path segments were joined with a doubled or missing slash  | Normalize `server` to end with `/` and re-derive the endpoint (see Step 2).                                                                                         |
-| Authorization-code flow hangs with no browser activity     | `npx pega-auth` opened a browser but consent was not completed, or the redirect URI is not registered        | Complete the consent in the browser. Confirm the redirect URI on the client registration record matches `redirectUri` exactly, including its trailing slash.        |
-| Redirect returns "redirect_uri mismatch"                   | `redirectUri` differs from the registered value — most often by a missing trailing slash                     | Make both values byte-identical.                                                                                                                                    |
-| `403` on `D_pxBootstrapConfig`                             | The authenticated operator's access group lacks the privilege to read the bootstrap data page                | Authenticate as an operator with an access group that includes the Constellation runtime privileges.                                                                |
-| `pyConfigJSON` is present but `tokens.C11NB2S` is missing  | The response was only parsed once — `pyConfigJSON` is a JSON **string**                                      | Parse `pyConfigJSON` a second time before reading `tokens` (see Step 5).                                                                                            |
-| `/casetypes` returns an empty array                        | The operator has no creatable case types in that application, or `appAlias` targets the wrong application    | Confirm `appAlias` matches the target application and that the operator can create cases in it.                                                                     |
-| `applicationIsConstellationCompatible` is `false`          | The target application is not enabled for Constellation                                                      | Stop. Confirm `appAlias` points at the intended application; if it does, the application must be made Constellation-compatible before an embedded flow is possible. |
-| Calls succeed, then start returning `401`                  | The access token expired                                                                                     | Re-run `npx pega-auth` — it will attempt a refresh automatically, or perform a fresh login.                                                                         |
-
----
-
-## Notes
-
-- This skill is a prerequisite for case-type resolution. Do not ask the user for a fully qualified case type class before it has completed — the class name should come from `/casetypes`, not from memory.
-- The token obtained here is used by the **agent**, for design-time DX API calls. It is unrelated to the token the browser obtains at runtime, which the SDK's auth client negotiates from `sdk-config.json`.
-- Re-running this skill is safe. It detects an existing valid session and reuses it rather than forcing a fresh authentication.