@reopt-ai/brandapp-sdk 3.0.0 → 3.3.0

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.
Files changed (47) hide show
  1. package/CHANGELOG.md +111 -3
  2. package/README.md +29 -13
  3. package/dist/ai/index.js +4 -3
  4. package/dist/ai-provider/index.js +16 -2
  5. package/dist/auth/index.js +4 -3
  6. package/dist/better-auth/index.d.ts +1 -1
  7. package/dist/better-auth/index.js +35 -24
  8. package/dist/chunk-2LSCQHAU.js +21 -0
  9. package/dist/{chunk-E457LO5A.js → chunk-4U4ZPPL4.js} +4 -4
  10. package/dist/{chunk-K3YVJE6E.js → chunk-55KHY5GH.js} +3 -3
  11. package/dist/{chunk-J5Y2GSJF.js → chunk-C5VTRZWX.js} +43 -28
  12. package/dist/{chunk-KU2LN5SE.js → chunk-FJUCWXX3.js} +4 -4
  13. package/dist/{chunk-TUKIYH4Q.js → chunk-H33OTQEN.js} +3 -3
  14. package/dist/chunk-OG7R3UAR.js +105 -0
  15. package/dist/{chunk-6FLYVNZI.js → chunk-PF24XU54.js} +3 -3
  16. package/dist/{chunk-6KPKZ7ZB.js → chunk-QN3QD67K.js} +3 -3
  17. package/dist/{chunk-YRGLBM6V.js → chunk-UGBBXCZE.js} +6 -6
  18. package/dist/{chunk-WSEROZVO.js → chunk-UVT2E6KD.js} +6 -6
  19. package/dist/{chunk-PJZB4VP7.js → chunk-YPLT3RFL.js} +3 -3
  20. package/dist/{chunk-DI6QJPTQ.js → chunk-YTKSAWV2.js} +20 -6
  21. package/dist/cms/index.js +10 -6
  22. package/dist/dev/index.d.ts +19 -0
  23. package/dist/dev/index.js +107 -4
  24. package/dist/eav/index.d.ts +1 -1
  25. package/dist/eav/index.js +5 -4
  26. package/dist/{errors-5hd5ZR-M.d.ts → errors-BjDFIyA6.d.ts} +25 -3
  27. package/dist/feedback/index.js +4 -3
  28. package/dist/files/index.js +4 -3
  29. package/dist/index.d.ts +10 -1
  30. package/dist/index.js +14 -13
  31. package/dist/logout/index.d.ts +106 -0
  32. package/dist/logout/index.js +321 -0
  33. package/dist/plans/index.d.ts +107 -11
  34. package/dist/plans/index.js +4 -3
  35. package/dist/push/index.js +4 -3
  36. package/dist/react/hooks.d.ts +5 -1
  37. package/dist/react/hooks.js +63 -15
  38. package/dist/terms/index.js +4 -3
  39. package/dist/testing/index.d.ts +1 -1
  40. package/dist/webhooks/index.d.ts +6 -3
  41. package/docs/api-reference.md +99 -3
  42. package/docs/cms.md +0 -1
  43. package/docs/dev-server.md +19 -18
  44. package/docs/errors.md +72 -15
  45. package/docs/logout.md +166 -0
  46. package/package.json +7 -1
  47. package/dist/chunk-T2WXHAAC.js +0 -54
package/docs/logout.md ADDED
@@ -0,0 +1,166 @@
1
+ # Logout — Single Logout across reopt and your app
2
+
3
+ `@reopt-ai/brandapp-sdk/logout` implements OIDC **Single Logout** so a session
4
+ can end in both directions between reopt (the Identity Provider) and your app
5
+ (a Relying Party):
6
+
7
+ - **Back-Channel Logout (receive)** — when a user logs out of reopt (or an admin
8
+ bans/deletes them, or another device is signed out), reopt notifies your app
9
+ server-to-server so you can end the matching session in your app.
10
+ - **RP-Initiated Logout (trigger)** — when a user logs out of **your** app, you
11
+ can optionally send them through reopt's `end_session_endpoint` to end their
12
+ reopt session too (and every session derived from it).
13
+
14
+ No external dependencies — signature verification uses Web Crypto (Ed25519).
15
+
16
+ > **Runtime**: Back-Channel Logout verification needs Ed25519 in Web Crypto —
17
+ > available on Node 20+, Deno, Cloudflare Workers, and modern browsers. Since the
18
+ > receiver runs server-side, any Node 20+ host (Firebase Functions, Vercel
19
+ > Functions, etc.) works.
20
+
21
+ ## 1. Receive Back-Channel Logout
22
+
23
+ Mount a handler at a stable URL and register that URL with reopt as your OAuth
24
+ client's `backchannel_logout_uri` (ask your reopt contact, or set it in Studio →
25
+ BrandApp → OAuth). reopt POSTs a signed `logout_token` there whenever the
26
+ originating reopt session is revoked.
27
+
28
+ ```ts
29
+ // Next.js App Router — app/api/auth/backchannel-logout/route.ts
30
+ import { createBackchannelLogoutHandler } from "@reopt-ai/brandapp-sdk/logout";
31
+
32
+ export const POST = createBackchannelLogoutHandler({
33
+ // Revoke every local session derived from this reopt session id.
34
+ onLogout: async ({ sid, sub }) => {
35
+ await db.sessions.deleteMany({ where: { reoptSid: sid } });
36
+ },
37
+ });
38
+ ```
39
+
40
+ The handler is a standard `(Request) => Promise<Response>`, so it also works with
41
+ Hono, plain Fetch servers, or any framework that speaks the Web `Request`/`Response`
42
+ API.
43
+
44
+ ### Wiring the `sid`
45
+
46
+ To end the right sessions, store the reopt **session id (`sid`)** when the user
47
+ logs in. It's the `sid` claim of the `id_token` you receive from the OAuth code
48
+ exchange. Persist it on your session row so `onLogout({ sid })` can find and
49
+ delete the matching sessions.
50
+
51
+ ```ts
52
+ // at login, after code exchange:
53
+ const { sid } = decodeIdToken(tokenResponse.id_token);
54
+ await db.sessions.create({ userId, reoptSid: sid, ... });
55
+ ```
56
+
57
+ ### Verify manually
58
+
59
+ If you need the claims without the HTTP wrapper (custom transport, testing):
60
+
61
+ ```ts
62
+ import { verifyBackchannelLogoutToken } from "@reopt-ai/brandapp-sdk/logout";
63
+
64
+ const { sid, sub } = await verifyBackchannelLogoutToken(logoutToken, {
65
+ clientId: process.env.BRANDAPP_CLIENT_ID,
66
+ });
67
+ ```
68
+
69
+ It throws `ReoptSDKError` (`code: "invalid_logout_token"`) on any failure:
70
+ bad signature, wrong issuer/audience, missing `backchannel-logout` event,
71
+ a forbidden `nonce`, a stale `iat`, or a non-`EdDSA` algorithm.
72
+
73
+ ### Response contract
74
+
75
+ | Situation | Status |
76
+ | ----------------------------------------------------------- | ------ |
77
+ | Valid token, `onLogout` succeeded | `200` |
78
+ | Missing/invalid `logout_token`, verification failed | `400` |
79
+ | Non-POST | `405` |
80
+ | `onLogout` threw (make it idempotent — reopt retries) | `501` |
81
+ | Verification infra (discovery/JWKS) temporarily unavailable | `503` |
82
+
83
+ All responses carry `Cache-Control: no-store` per the spec.
84
+
85
+ The `503` (code `logout_verification_unavailable`) is returned **instead of
86
+ `400`** when the reopt discovery/JWKS endpoint is briefly unreachable (e.g. a
87
+ deploy) — a transient infra failure is not a bad token, so the IdP is told the
88
+ request is retryable rather than permanently invalid.
89
+
90
+ Signatures are verified with Web Crypto **Ed25519** (zero external deps). The
91
+ JWKS is fetched from discovery and cached; on a signature miss it is force-
92
+ refetched once to survive key rotation, but that forced refetch is **throttled
93
+ per `jwks_uri`** and concurrent refetches are coalesced, so a flood of forged
94
+ tokens to this public endpoint cannot reflect load onto the shared JWKS
95
+ endpoint. Discovery/JWKS fetches carry a timeout and fail closed.
96
+
97
+ ## 2. Trigger RP-Initiated Logout
98
+
99
+ When the user logs out of your app, send them to reopt's `end_session_endpoint`
100
+ to also end the reopt session. Pass the `id_token` you got at login as the hint.
101
+
102
+ ```ts
103
+ import { buildEndSessionUrl } from "@reopt-ai/brandapp-sdk/logout";
104
+
105
+ const url = buildEndSessionUrl({
106
+ idToken: session.reoptIdToken, // id_token from login
107
+ postLogoutRedirectUri: "https://app.example.com/goodbye",
108
+ state: csrfToken, // optional, echoed back
109
+ });
110
+
111
+ // end your local session first, then:
112
+ redirect(url);
113
+ ```
114
+
115
+ For reopt to redirect back afterwards, `postLogoutRedirectUri` **must be
116
+ pre-registered** on your OAuth client's `post_logout_redirect_uris`. If it isn't
117
+ registered, reopt still ends the session but won't redirect.
118
+
119
+ ## How it fits together
120
+
121
+ ```
122
+ User logs out of reopt (or ban / delete / device sign-out)
123
+ │
124
+ ▼
125
+ reopt revokes the IdP session, then for each client with a
126
+ backchannel_logout_uri that holds tokens from that session:
127
+ │ POST logout_token (EdDSA JWT: aud, sid, events, …)
128
+ ▼
129
+ your handler → verify → onLogout({ sid }) → delete local sessions
130
+
131
+ User logs out of your app
132
+ │ redirect to buildEndSessionUrl({ idToken })
133
+ ▼
134
+ reopt end_session_endpoint → revokes that IdP session (cascades to all
135
+ derived sessions/tokens) → redirects to post_logout_redirect_uri
136
+ ```
137
+
138
+ ## Testing against the dev server
139
+
140
+ The in-memory dev server (`@reopt-ai/brandapp-sdk/dev`) is a faithful OIDC mock:
141
+ it signs real EdDSA tokens, serves its public key at `/api/auth/jwks`, and mounts
142
+ `/api/auth/oauth2/end-session`. Point your logout verifier at `dev.url` and mint a
143
+ `logout_token` to exercise your handler end-to-end — no reopt server required.
144
+
145
+ ```ts
146
+ import { createDevServer } from "@reopt-ai/brandapp-sdk/dev";
147
+
148
+ const dev = await createDevServer({ brandappId: "dev" });
149
+
150
+ const logoutToken = await dev.mintLogoutToken({
151
+ clientId: "my-brandapp",
152
+ sessionId: "idp-session-1",
153
+ userId: "user-1",
154
+ });
155
+
156
+ // Drive your handler with a form POST carrying logout_token=<token>, or verify
157
+ // directly — both fetch discovery + JWKS from the dev server:
158
+ const res = await POST(
159
+ new Request("http://localhost/api/auth/backchannel-logout", {
160
+ method: "POST",
161
+ headers: { "content-type": "application/x-www-form-urlencoded" },
162
+ body: new URLSearchParams({ logout_token: logoutToken }),
163
+ }),
164
+ );
165
+ // (configure the handler with idBaseUrl: dev.url, clientId: "my-brandapp")
166
+ ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@reopt-ai/brandapp-sdk",
3
- "version": "3.0.0",
3
+ "version": "3.3.0",
4
4
  "description": "Reopt Brandapp SDK — Better Auth adapter, OAuth login, and EAV client",
5
5
  "author": "Reopt",
6
6
  "license": "MIT",
@@ -57,6 +57,10 @@
57
57
  "types": "./dist/feedback/index.d.ts",
58
58
  "import": "./dist/feedback/index.js"
59
59
  },
60
+ "./logout": {
61
+ "types": "./dist/logout/index.d.ts",
62
+ "import": "./dist/logout/index.js"
63
+ },
60
64
  "./files": {
61
65
  "types": "./dist/files/index.d.ts",
62
66
  "import": "./dist/files/index.js"
@@ -167,7 +171,9 @@
167
171
  "dev": "tsup --watch",
168
172
  "type-check": "tsc --noEmit",
169
173
  "test": "vitest run",
174
+ "test:coverage": "vitest run --coverage",
170
175
  "test:critical": "vitest run __tests__/eav-client.test.ts __tests__/http-client.test.ts",
176
+ "test:e2e": "pnpm run build && vitest run --config vitest.e2e.config.ts",
171
177
  "clean": "rm -rf dist"
172
178
  }
173
179
  }
@@ -1,54 +0,0 @@
1
- import { BaseHttpClient } from './chunk-DI6QJPTQ.js';
2
-
3
- // src/plans/client.ts
4
- function unwrap(body) {
5
- if (body && typeof body === "object" && "data" in body) {
6
- const withData = body;
7
- if (withData.data !== void 0) return withData.data;
8
- }
9
- return body;
10
- }
11
- var ReoptPlansClient = class {
12
- http;
13
- constructor(config) {
14
- this.http = new BaseHttpClient(
15
- config,
16
- `/api/v1/brandapp/${config.brandappId}/plans`
17
- );
18
- }
19
- /**
20
- * List active plans for this Brandapp (the customer-facing catalog). Works
21
- * with either Basic Auth (default) or Bearer Auth — pass `accessToken` when
22
- * calling from a handler that already has the customer's OAuth token to avoid
23
- * sending app credentials.
24
- */
25
- async list(accessToken) {
26
- const body = await this.http.fetch(
27
- "GET",
28
- "",
29
- void 0,
30
- accessToken ? { bearerToken: accessToken } : void 0
31
- );
32
- return unwrap(body);
33
- }
34
- /**
35
- * Fetch the current plan / entitlement for the OAuth customer represented by
36
- * `accessToken`. Returns `null` when the customer has no active plan.
37
- */
38
- async getMyPlan(accessToken) {
39
- const body = await this.http.fetch(
40
- "GET",
41
- "/me/plan",
42
- void 0,
43
- { bearerToken: accessToken }
44
- );
45
- return unwrap(body);
46
- }
47
- };
48
- function createReoptPlansClient(config) {
49
- return new ReoptPlansClient(config);
50
- }
51
-
52
- export { ReoptPlansClient, createReoptPlansClient };
53
- //# sourceMappingURL=chunk-T2WXHAAC.js.map
54
- //# sourceMappingURL=chunk-T2WXHAAC.js.map