@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.
- package/CHANGELOG.md +111 -3
- package/README.md +29 -13
- package/dist/ai/index.js +4 -3
- package/dist/ai-provider/index.js +16 -2
- package/dist/auth/index.js +4 -3
- package/dist/better-auth/index.d.ts +1 -1
- package/dist/better-auth/index.js +35 -24
- package/dist/chunk-2LSCQHAU.js +21 -0
- package/dist/{chunk-E457LO5A.js → chunk-4U4ZPPL4.js} +4 -4
- package/dist/{chunk-K3YVJE6E.js → chunk-55KHY5GH.js} +3 -3
- package/dist/{chunk-J5Y2GSJF.js → chunk-C5VTRZWX.js} +43 -28
- package/dist/{chunk-KU2LN5SE.js → chunk-FJUCWXX3.js} +4 -4
- package/dist/{chunk-TUKIYH4Q.js → chunk-H33OTQEN.js} +3 -3
- package/dist/chunk-OG7R3UAR.js +105 -0
- package/dist/{chunk-6FLYVNZI.js → chunk-PF24XU54.js} +3 -3
- package/dist/{chunk-6KPKZ7ZB.js → chunk-QN3QD67K.js} +3 -3
- package/dist/{chunk-YRGLBM6V.js → chunk-UGBBXCZE.js} +6 -6
- package/dist/{chunk-WSEROZVO.js → chunk-UVT2E6KD.js} +6 -6
- package/dist/{chunk-PJZB4VP7.js → chunk-YPLT3RFL.js} +3 -3
- package/dist/{chunk-DI6QJPTQ.js → chunk-YTKSAWV2.js} +20 -6
- package/dist/cms/index.js +10 -6
- package/dist/dev/index.d.ts +19 -0
- package/dist/dev/index.js +107 -4
- package/dist/eav/index.d.ts +1 -1
- package/dist/eav/index.js +5 -4
- package/dist/{errors-5hd5ZR-M.d.ts → errors-BjDFIyA6.d.ts} +25 -3
- package/dist/feedback/index.js +4 -3
- package/dist/files/index.js +4 -3
- package/dist/index.d.ts +10 -1
- package/dist/index.js +14 -13
- package/dist/logout/index.d.ts +106 -0
- package/dist/logout/index.js +321 -0
- package/dist/plans/index.d.ts +107 -11
- package/dist/plans/index.js +4 -3
- package/dist/push/index.js +4 -3
- package/dist/react/hooks.d.ts +5 -1
- package/dist/react/hooks.js +63 -15
- package/dist/terms/index.js +4 -3
- package/dist/testing/index.d.ts +1 -1
- package/dist/webhooks/index.d.ts +6 -3
- package/docs/api-reference.md +99 -3
- package/docs/cms.md +0 -1
- package/docs/dev-server.md +19 -18
- package/docs/errors.md +72 -15
- package/docs/logout.md +166 -0
- package/package.json +7 -1
- 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.
|
|
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
|
}
|
package/dist/chunk-T2WXHAAC.js
DELETED
|
@@ -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
|