@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 +61 -0
- package/dist/auth/federated.d.ts +15 -1
- package/dist/auth/federated.js +1 -1
- package/dist/next.d.ts +19 -6
- package/dist/next.js +1 -1
- package/dist/runtime/web.d.ts +19 -6
- package/dist/runtime/web.js +1 -1
- package/package.json +2 -2
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
|
package/dist/auth/federated.d.ts
CHANGED
|
@@ -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;
|