@collective-intelligence/external-apps-server-sdk 0.2.14 → 0.2.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -205,6 +205,41 @@ Override `validate`, `idempotencyKey`, `authorize`, or `getAccessToken` when
205
205
  the application needs different policy. The deprecated `./express` entry
206
206
  re-exports only `createGatewayExpressMiddleware` from `./runtime/express`.
207
207
 
208
+ ### Run the BFF on a developer machine
209
+
210
+ `publicOrigin` is the origin of your app that the BFF and federated auth see.
211
+ It must be an HTTPS origin: the session cookie is `__Host-ci-federated` with
212
+ `Secure`. To run the app on a developer machine against a remote CI without a
213
+ local TLS proxy, set `allowLoopbackHttp: true` on
214
+ `createExternalApplicationBff`, `createExternalApplicationBffNextHandlers` or
215
+ `createFixedWorkflowRoute`. `publicOrigin` may then also be an HTTP origin on
216
+ an exact loopback host: `http://localhost:3000`, `http://127.0.0.1:3000` or
217
+ `http://[::1]:3000`. Give `createFederatedAuth` the same origin as
218
+ `applicationOrigin`; its session cookie is then `ci-federated`, without the
219
+ `__Host-` prefix and without `Secure`.
220
+
221
+ ```ts
222
+ createExternalApplicationBffNextHandlers({
223
+ // `false` by default; turn it on for development or staging only.
224
+ allowLoopbackHttp: env.ALLOW_LOOPBACK_HTTP === "1",
225
+ auth,
226
+ // `http://localhost:3000` on a developer machine, an HTTPS origin elsewhere.
227
+ publicOrigin: env.APP_ORIGIN
228
+ })
229
+ ```
230
+
231
+ - Without the flag, an HTTP `publicOrigin` throws
232
+ `publicOrigin must contain only an HTTPS origin` on the first request.
233
+ - With it, every other HTTP origin still throws: `http://app.example.com`,
234
+ `http://localhost.evil.com`, `http://10.0.0.1:3000`, an origin with a path or
235
+ credentials. A forwarded host (`x-forwarded-host`) stays HTTPS-only, and so do
236
+ `tenantUrl` and `realtime.host`, which are CI's own authority.
237
+ - Keep it off in production. It lets a configuration choose an origin that
238
+ carries the session cookie without `Secure`.
239
+ - CI must accept the callback too: register `<publicOrigin><basePath>/callback`
240
+ as a redirect URI of the application, with its origin as an allowed origin.
241
+ CI accepts an HTTP redirect URI only on a loopback host with an explicit port.
242
+
208
243
  ## Call CI as a member your server signed in
209
244
 
210
245
  A server that signs members in to CI itself (for example through
@@ -1754,6 +1789,32 @@ OAuth client may supply `clientSecret`; a public PKCE client omits it. The
1754
1789
  client type decides how long the User session lasts; see
1755
1790
  [Session lifetime and renewal](#session-lifetime-and-renewal).
1756
1791
 
1792
+ ### Sign-in failures at the callback
1793
+
1794
+ `GET <basePath>/callback` is a browser navigation, so a failure there should
1795
+ end on a page of your app. Set `errorPath`, for example `/auth/error`, and the
1796
+ callback redirects to `<errorPath>?error=<code>`:
1797
+
1798
+ | `error` | Cause |
1799
+ | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
1800
+ | `access_denied` | CI refused the sign-in: the user chose "Back" on CI's page for an account without access, or declined consent. |
1801
+ | `authorization_failed` | CI answered another OAuth error, or refused the authorization code. |
1802
+ | `invalid_state` | No pending login matches this browser: it expired, a newer login in another tab replaced it, or the link was altered. |
1803
+ | `invalid_request`, `invalid_identity` | The request or the identity was not valid. |
1804
+ | `user_auth_unavailable` | CI or the session store did not answer. |
1805
+
1806
+ A refusal from CI (`?error=…&state=…`, with no `code`) is classified only after
1807
+ `state` matches the pending login of this browser. CI's error text is never
1808
+ copied into the redirect: an unknown `error` is `authorization_failed`. The
1809
+ page can offer a retry through `<basePath>/login?returnTo=<path>`, which starts
1810
+ a new login.
1811
+
1812
+ `errorPath` is an absolute path without a query or a trailing slash, outside
1813
+ `basePath`; the SDK rejects anything else when it creates the auth. Without
1814
+ `errorPath`, the callback answers JSON as before: `400 {"error": "<code>"}`,
1815
+ or `503` for `user_auth_unavailable`. A failure on another route (login,
1816
+ session, logout) always answers JSON.
1817
+
1757
1818
  ### Session lifetime and renewal
1758
1819
 
1759
1820
  `sessionTtlSeconds` sets the Session lifetime: the time from sign-in to the
@@ -238,6 +238,20 @@ export type FederatedAuthOptions = Readonly<{
238
238
  basePath?: string;
239
239
  clientId: string;
240
240
  clientSecret?: string;
241
+ /**
242
+ * App path, such as `/auth/error`, that `<basePath>/callback` redirects to
243
+ * when a sign-in fails, so the browser lands on a page of the app and not on
244
+ * raw JSON. The redirect is `<errorPath>?error=<code>`, with one of:
245
+ * `access_denied` (the user, or CI for an account without access, refused
246
+ * the sign-in), `authorization_failed` (CI answered another authorization
247
+ * error or refused the code), `invalid_state` (no matching pending login:
248
+ * it expired, another tab started a newer login, or the link was altered),
249
+ * `invalid_request`, `invalid_identity` and `user_auth_unavailable` (CI or the
250
+ * session store did not answer). The path must be absolute, without a query
251
+ * or a trailing slash, and outside `basePath`. Default: no redirect, and the
252
+ * callback answers JSON with `400`, or `503` for `user_auth_unavailable`.
253
+ */
254
+ errorPath?: string;
241
255
  fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
242
256
  issuer: string;
243
257
  now?: () => number;
@@ -247,7 +261,7 @@ export type FederatedAuthOptions = Readonly<{
247
261
  store?: FederatedSessionStore;
248
262
  }>;
249
263
  declare class FederatedAuthRejectedError extends Error {
250
- readonly code: "invalid_request" | "invalid_state" | "invalid_identity" | "authorization_failed";
264
+ readonly code: "access_denied" | "invalid_request" | "invalid_state" | "invalid_identity" | "authorization_failed";
251
265
  constructor(code: FederatedAuthRejectedError["code"]);
252
266
  }
253
267
  declare const ApplicationUserAuthUnavailableError$1: typeof ApplicationUserAuthUnavailableError;