@plasgos/oidc-client 0.0.0-stage → 0.1.0-next.2
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 +31 -0
- package/LICENSE +15 -0
- package/README.md +145 -2
- package/dist/index.cjs +884 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +33 -0
- package/dist/index.d.ts +33 -0
- package/dist/index.js +860 -0
- package/dist/index.js.map +1 -0
- package/dist/service.cjs +432 -0
- package/dist/service.cjs.map +1 -0
- package/dist/service.d.cts +88 -0
- package/dist/service.d.ts +88 -0
- package/dist/service.js +419 -0
- package/dist/service.js.map +1 -0
- package/dist/session.cjs +601 -0
- package/dist/session.cjs.map +1 -0
- package/dist/session.d.cts +289 -0
- package/dist/session.d.ts +289 -0
- package/dist/session.js +568 -0
- package/dist/session.js.map +1 -0
- package/dist/types-JE0OMyoi.d.cts +375 -0
- package/dist/types-JE0OMyoi.d.ts +375 -0
- package/docs/consumers.md +90 -0
- package/docs/contoh-hitungcuan.md +255 -0
- package/docs/contoh-plaslink.md +244 -0
- package/docs/error.md +428 -0
- package/docs/examples/auth-verify-readme.ts +18 -0
- package/docs/examples/config-error.ts +24 -0
- package/docs/examples/env.ts +99 -0
- package/docs/examples/failure-log.ts +18 -0
- package/docs/examples/login-client.ts +46 -0
- package/docs/examples/login-flow.ts +186 -0
- package/docs/examples/plaslink-connect.ts +48 -0
- package/docs/examples/readme.ts +60 -0
- package/docs/examples/service-client.ts +105 -0
- package/docs/examples/session-store.ts +53 -0
- package/docs/examples/webhook-express.ts +46 -0
- package/docs/examples/webhook-fetch.ts +60 -0
- package/docs/examples/webhook-nestjs.ts +59 -0
- package/docs/examples/webhook-testing.ts +60 -0
- package/docs/examples/webhook-verifier.ts +143 -0
- package/docs/login-web.md +618 -0
- package/docs/memulai.md +339 -0
- package/docs/server-ke-server.md +275 -0
- package/docs/webhook.md +625 -0
- package/package.json +67 -3
|
@@ -0,0 +1,375 @@
|
|
|
1
|
+
import { Environment, OidcErrorReason, TokenSet, IdTokenClaims, UserScope, ClientProfile } from '@plasgos/auth-shared';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* The step of the SDK that failed.
|
|
5
|
+
*
|
|
6
|
+
* @example
|
|
7
|
+
* if (event.operation === "refresh" && event.reason === "config_invalid") alertOps(event);
|
|
8
|
+
*/
|
|
9
|
+
type OidcOperation = "callback" | "token" | "refresh" | "revocation" | "logout_ticket" | "service_token" | "service_request";
|
|
10
|
+
/**
|
|
11
|
+
* One failure, as the `onFailure` hook receives it. It never holds a token, code, secret, body or
|
|
12
|
+
* query string.
|
|
13
|
+
*
|
|
14
|
+
* @example
|
|
15
|
+
* const onFailure = (event: OidcFailureEvent) => {
|
|
16
|
+
* logger.error(`login failed: ${event.operation} ${event.reason} request_id=${event.requestId ?? "-"}`);
|
|
17
|
+
* };
|
|
18
|
+
*/
|
|
19
|
+
interface OidcFailureEvent {
|
|
20
|
+
/** The `environment` of the client that failed. */
|
|
21
|
+
environment: Environment;
|
|
22
|
+
/** The step that failed. */
|
|
23
|
+
operation: OidcOperation;
|
|
24
|
+
/** The same reason an `OidcError` of this failure carries. */
|
|
25
|
+
reason: OidcErrorReason;
|
|
26
|
+
/** HTTP method of the call that failed, or null. */
|
|
27
|
+
method: string | null;
|
|
28
|
+
/** Path of the call that failed, without query string or fragment, or null. */
|
|
29
|
+
path: string | null;
|
|
30
|
+
/** HTTP status of the provider's answer; null when there was none. */
|
|
31
|
+
status: number | null;
|
|
32
|
+
/** `x-request-id` of the provider's answer, or null. */
|
|
33
|
+
requestId: string | null;
|
|
34
|
+
/** The `error` code the provider answered with, or null. */
|
|
35
|
+
providerError: string | null;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* Where the client keeps refreshes in flight. The key is the SHA-256 of the refresh token, never
|
|
40
|
+
* the token itself. Implement it over a shared store to hold the lock across several instances.
|
|
41
|
+
*
|
|
42
|
+
* @example
|
|
43
|
+
* const redisLock: RefreshLockStore = {
|
|
44
|
+
* run: (key, refresh, reuseMs) => runOnceAcrossInstances(redis, key, refresh, reuseMs),
|
|
45
|
+
* };
|
|
46
|
+
* const client = createOidcClient({ ...options, refreshLock: redisLock });
|
|
47
|
+
*/
|
|
48
|
+
interface RefreshLockStore {
|
|
49
|
+
/**
|
|
50
|
+
* Runs `refresh` at most once per key among callers sharing this store and gives every caller the same result.
|
|
51
|
+
* A fulfilled result is reused for `reuseMs`; a rejection is not cached.
|
|
52
|
+
*/
|
|
53
|
+
run(key: string, refresh: () => Promise<TokenSet>, reuseMs: number): Promise<TokenSet>;
|
|
54
|
+
}
|
|
55
|
+
/**
|
|
56
|
+
* The default lock store: a map in this process, so it only holds within one instance.
|
|
57
|
+
*
|
|
58
|
+
* @example
|
|
59
|
+
* const client = createOidcClient({ ...options, refreshLock: memoryLockStore() });
|
|
60
|
+
*/
|
|
61
|
+
declare function memoryLockStore(options?: {
|
|
62
|
+
now?: (() => number) | undefined;
|
|
63
|
+
}): RefreshLockStore;
|
|
64
|
+
|
|
65
|
+
/**
|
|
66
|
+
* One login in progress: what `startLogin` creates, the transaction cookie carries, and
|
|
67
|
+
* `handleCallback` checks the provider's answer against.
|
|
68
|
+
*
|
|
69
|
+
* @example
|
|
70
|
+
* const tx: OidcTransaction = {
|
|
71
|
+
* state, nonce, code_verifier,
|
|
72
|
+
* return_to: "/packages",
|
|
73
|
+
* created_at: Date.now(),
|
|
74
|
+
* };
|
|
75
|
+
*/
|
|
76
|
+
interface OidcTransaction {
|
|
77
|
+
/** Random value the callback must return unchanged. */
|
|
78
|
+
state: string;
|
|
79
|
+
/** Random value the ID token must carry. */
|
|
80
|
+
nonce: string;
|
|
81
|
+
/** PKCE verifier, sent with the code exchange. */
|
|
82
|
+
code_verifier: string;
|
|
83
|
+
/** Where the app sends the user after the callback; the app validates it. */
|
|
84
|
+
return_to: string;
|
|
85
|
+
/** Epoch milliseconds. */
|
|
86
|
+
created_at: number;
|
|
87
|
+
/** The login re-authenticates a signed-in user (`prompt=login`). */
|
|
88
|
+
reauth?: boolean | undefined;
|
|
89
|
+
/** The `max_age` sent to the provider, in seconds. */
|
|
90
|
+
max_age?: number | undefined;
|
|
91
|
+
}
|
|
92
|
+
/**
|
|
93
|
+
* The `fetch` the SDK calls: always with a string URL and a `RequestInit`.
|
|
94
|
+
*
|
|
95
|
+
* @example
|
|
96
|
+
* const tracedFetch: OidcFetch = (input, init) => fetch(input, { ...init, headers: withTraceId(init.headers) });
|
|
97
|
+
* const client = createOidcClient({ ...options, fetch: tracedFetch });
|
|
98
|
+
*/
|
|
99
|
+
type OidcFetch = (input: string, init: RequestInit) => Promise<Response>;
|
|
100
|
+
/**
|
|
101
|
+
* Options of `createOidcClient`. Values usually come from `process.env`; every problem is reported
|
|
102
|
+
* at once in one `ConfigError`, by field name and never by value.
|
|
103
|
+
*
|
|
104
|
+
* @example
|
|
105
|
+
* const options: OidcClientOptions = {
|
|
106
|
+
* environment: "production",
|
|
107
|
+
* issuer: "https://accounts.plasgos.co.id",
|
|
108
|
+
* backchannelUrl: process.env.PLASGOS_BACKCHANNEL_URL,
|
|
109
|
+
* clientId: process.env.PLASGOS_LOGIN_CLIENT_ID ?? "",
|
|
110
|
+
* clientSecret: process.env.PLASGOS_LOGIN_CLIENT_SECRET ?? "",
|
|
111
|
+
* redirectUri: "https://kirim.plasgos.co.id/auth/callback",
|
|
112
|
+
* scopes: ["openid", "profile", "email", "packages:read", "packages:write"],
|
|
113
|
+
* profile: "first-party",
|
|
114
|
+
* resource: "https://api.plasgos.co.id/packages",
|
|
115
|
+
* };
|
|
116
|
+
*/
|
|
117
|
+
interface OidcClientOptions {
|
|
118
|
+
/** `"sandbox"` or `"production"`; checked against `issuer`, `resource` and `backchannelUrl`. */
|
|
119
|
+
environment: Environment;
|
|
120
|
+
/** Bare origin of the provider: browser URLs and the exact `iss` value. */
|
|
121
|
+
issuer: string;
|
|
122
|
+
/** Internal Plasgos server origin for the token, revocation and logout-ticket calls; `http:` allowed. Default: `issuer`. */
|
|
123
|
+
backchannelUrl?: string | undefined;
|
|
124
|
+
/** Client id of the interactive (login) client. */
|
|
125
|
+
clientId: string;
|
|
126
|
+
/** Sent only as `client_secret_basic`. */
|
|
127
|
+
clientSecret: string;
|
|
128
|
+
/** Registered callback URL, exact. `https:` unless `allowInsecureHttp`. */
|
|
129
|
+
redirectUri: string;
|
|
130
|
+
/** Registered post-logout URL, same scheme rule. */
|
|
131
|
+
postLogoutRedirectUri?: string | undefined;
|
|
132
|
+
/** Must include `"openid"`. */
|
|
133
|
+
scopes: readonly UserScope[];
|
|
134
|
+
/** `"first-party"`: an app of Plasgos itself. `"third-party"`: any other app. */
|
|
135
|
+
profile: ClientProfile;
|
|
136
|
+
/** Resource indicator (audience); required by `account:*` / `packages:*`, refused for `"third-party"`. */
|
|
137
|
+
resource?: string | undefined;
|
|
138
|
+
/**
|
|
139
|
+
* Mint a logout ticket at logout. Default: `true` for first-party with `endSession: "redirect"`
|
|
140
|
+
* and a `backchannelUrl`, otherwise `false`. An explicit `true` requires `backchannelUrl`.
|
|
141
|
+
*/
|
|
142
|
+
logoutTicket?: boolean | undefined;
|
|
143
|
+
/** `"redirect"` (default, a GET URL) or `"form-post"` (only for an app on the issuer's own origin). */
|
|
144
|
+
endSession?: "redirect" | "form-post" | undefined;
|
|
145
|
+
/** ID token claims returned in `claims.extra`, for example `["plasgos_public_id"]`. */
|
|
146
|
+
extraClaims?: readonly string[] | undefined;
|
|
147
|
+
/** Sandbox only: `http:` for the issuer, redirect and post-logout URLs. */
|
|
148
|
+
allowInsecureHttp?: boolean | undefined;
|
|
149
|
+
/** Per call, body read included: integers from 1 to 60000. Defaults 10000 and 3000. */
|
|
150
|
+
timeouts?: {
|
|
151
|
+
tokenMs?: number | undefined;
|
|
152
|
+
logoutMs?: number | undefined;
|
|
153
|
+
} | undefined;
|
|
154
|
+
/** Default: the global `fetch`. */
|
|
155
|
+
fetch?: OidcFetch | undefined;
|
|
156
|
+
/** Single-flight store for refresh. Default: one `memoryLockStore()` per client. */
|
|
157
|
+
refreshLock?: RefreshLockStore | undefined;
|
|
158
|
+
/** Called once per failure, thrown or swallowed. Exceptions it throws are swallowed. */
|
|
159
|
+
onFailure?: ((event: OidcFailureEvent) => void) | undefined;
|
|
160
|
+
}
|
|
161
|
+
/**
|
|
162
|
+
* Input of `client.startLogin`.
|
|
163
|
+
*
|
|
164
|
+
* @example
|
|
165
|
+
* client.startLogin({ returnTo: "/orders", prompt: "login", maxAge: 0, reauth: true });
|
|
166
|
+
*/
|
|
167
|
+
interface StartLoginInput {
|
|
168
|
+
/** Already sanitised by the app: starts with one "/", at most 512 chars. */
|
|
169
|
+
returnTo: string;
|
|
170
|
+
/** OIDC `prompt`: `"login"` forces a new login. */
|
|
171
|
+
prompt?: "login" | "consent" | "none" | undefined;
|
|
172
|
+
/** Seconds; OIDC max_age. */
|
|
173
|
+
maxAge?: number | undefined;
|
|
174
|
+
/** OIDC `login_hint`, at most 512 characters. */
|
|
175
|
+
loginHint?: string | undefined;
|
|
176
|
+
/** Marks a step-up login; returned by handleCallback for the app's subject check. */
|
|
177
|
+
reauth?: boolean | undefined;
|
|
178
|
+
/** Epoch ms, for tests. */
|
|
179
|
+
now?: number | undefined;
|
|
180
|
+
}
|
|
181
|
+
/**
|
|
182
|
+
* Where to send the browser, and the transaction to seal into the transaction cookie.
|
|
183
|
+
*
|
|
184
|
+
* @example
|
|
185
|
+
* const { location, transaction } = client.startLogin({ returnTo: "/" });
|
|
186
|
+
* headers.append("Set-Cookie", store.commitTransaction(transaction));
|
|
187
|
+
* headers.set("Location", location);
|
|
188
|
+
* return new Response(null, { status: 302, headers });
|
|
189
|
+
*/
|
|
190
|
+
interface StartLoginResult {
|
|
191
|
+
/** The authorization URL on the issuer to redirect the browser to. */
|
|
192
|
+
location: string;
|
|
193
|
+
/** To be sealed with `store.commitTransaction` and read back at the callback. */
|
|
194
|
+
transaction: OidcTransaction;
|
|
195
|
+
}
|
|
196
|
+
/**
|
|
197
|
+
* The checked ID token claims, plus the claims named in `extraClaims` (prototype-free, frozen).
|
|
198
|
+
*
|
|
199
|
+
* @example
|
|
200
|
+
* // createOidcClient({ ...options, extraClaims: ["plasgos_public_id"] })
|
|
201
|
+
* const { claims } = await client.handleCallback(request.url, transaction);
|
|
202
|
+
* const publicId = claims.extra["plasgos_public_id"];
|
|
203
|
+
*/
|
|
204
|
+
type VerifiedIdTokenClaims = IdTokenClaims & {
|
|
205
|
+
extra: Readonly<Record<string, string | number | boolean>>;
|
|
206
|
+
};
|
|
207
|
+
/**
|
|
208
|
+
* Options of `client.handleCallback`.
|
|
209
|
+
*
|
|
210
|
+
* @example
|
|
211
|
+
* await client.handleCallback(callbackUrl, transaction, { now: Date.UTC(2026, 0, 1) });
|
|
212
|
+
*/
|
|
213
|
+
interface HandleCallbackOptions {
|
|
214
|
+
/** Epoch ms, for tests. */
|
|
215
|
+
now?: number | undefined;
|
|
216
|
+
}
|
|
217
|
+
/**
|
|
218
|
+
* What `client.handleCallback` returns: the token set, the checked ID token claims, and the
|
|
219
|
+
* transaction the login started with (`return_to`, `reauth`).
|
|
220
|
+
*
|
|
221
|
+
* @example
|
|
222
|
+
* const { tokens, claims, transaction } = await client.handleCallback(request.url, store.readTransaction(request));
|
|
223
|
+
* const expiresAt = accessTokenExpiry(tokens, Date.now());
|
|
224
|
+
* return redirect(transaction.return_to);
|
|
225
|
+
*/
|
|
226
|
+
interface CallbackResult {
|
|
227
|
+
/** The token set of the code exchange. */
|
|
228
|
+
tokens: TokenSet;
|
|
229
|
+
/** The checked ID token claims. */
|
|
230
|
+
claims: VerifiedIdTokenClaims;
|
|
231
|
+
/** The transaction the login started with. */
|
|
232
|
+
transaction: OidcTransaction;
|
|
233
|
+
}
|
|
234
|
+
/**
|
|
235
|
+
* The part of a stored session `client.ensureFresh` reads and renews. Any object with these fields
|
|
236
|
+
* fits, for example the `AuthState` of `@plasgos/oidc-client/session`.
|
|
237
|
+
*
|
|
238
|
+
* @example
|
|
239
|
+
* const auth: RefreshableAuth = { access_token, refresh_token, expires_at: accessTokenExpiry(tokens, Date.now()) };
|
|
240
|
+
* const fresh = await client.ensureFresh(auth);
|
|
241
|
+
*/
|
|
242
|
+
interface RefreshableAuth {
|
|
243
|
+
/** The current access token. */
|
|
244
|
+
access_token: string;
|
|
245
|
+
/** Absent for a client without refresh tokens; then nothing can be renewed. */
|
|
246
|
+
refresh_token?: string | undefined;
|
|
247
|
+
/** Epoch seconds at which the access token expires. */
|
|
248
|
+
expires_at: number;
|
|
249
|
+
}
|
|
250
|
+
/**
|
|
251
|
+
* Options of `client.ensureFresh`.
|
|
252
|
+
*
|
|
253
|
+
* @example
|
|
254
|
+
* // The API answered 401 invalid_token: refresh once, whatever the expiry says.
|
|
255
|
+
* const { auth } = await client.ensureFresh(session.data.auth, { force: true });
|
|
256
|
+
*/
|
|
257
|
+
interface EnsureFreshOptions {
|
|
258
|
+
/** Refresh when the access token expires within this many seconds. Default 60. */
|
|
259
|
+
skewSeconds?: number | undefined;
|
|
260
|
+
/** Refresh even if the token looks valid (the API answered 401 invalid_token). Default false. */
|
|
261
|
+
force?: boolean | undefined;
|
|
262
|
+
/** Epoch ms, for tests. */
|
|
263
|
+
now?: number | undefined;
|
|
264
|
+
}
|
|
265
|
+
/**
|
|
266
|
+
* What `client.ensureFresh` returns: the auth to use, and whether it has to be stored again.
|
|
267
|
+
*
|
|
268
|
+
* @example
|
|
269
|
+
* const { auth, changed } = await client.ensureFresh(current);
|
|
270
|
+
* if (changed) session.update({ auth });
|
|
271
|
+
*/
|
|
272
|
+
interface EnsureFreshResult<A> {
|
|
273
|
+
/** The input object itself when `changed` is false, a renewed copy otherwise. */
|
|
274
|
+
auth: A;
|
|
275
|
+
/** True when `auth` was renewed and must be stored again. */
|
|
276
|
+
changed: boolean;
|
|
277
|
+
}
|
|
278
|
+
/**
|
|
279
|
+
* Input of `client.logout`: what the session being ended still holds.
|
|
280
|
+
*
|
|
281
|
+
* @example
|
|
282
|
+
* await client.logout({
|
|
283
|
+
* refreshToken: auth?.refresh_token,
|
|
284
|
+
* idToken: auth?.id_token,
|
|
285
|
+
* browser: { clientIp: null, userAgent: request.headers.get("User-Agent") },
|
|
286
|
+
* });
|
|
287
|
+
*/
|
|
288
|
+
interface LogoutInput {
|
|
289
|
+
/** Revoked at the provider when given. */
|
|
290
|
+
refreshToken?: string | undefined;
|
|
291
|
+
/** Swapped for a one-time logout ticket, or sent as `id_token_hint` in `"form-post"` mode. */
|
|
292
|
+
idToken?: string | undefined;
|
|
293
|
+
/** The browser's address and agent, forwarded as X-Client-Ip / X-Client-User-Agent when not null. */
|
|
294
|
+
browser?: {
|
|
295
|
+
clientIp: string | null;
|
|
296
|
+
userAgent: string | null;
|
|
297
|
+
} | undefined;
|
|
298
|
+
}
|
|
299
|
+
/**
|
|
300
|
+
* Where `client.logout` sends the browser. `redirect`: a GET URL without any token; `ticket` tells
|
|
301
|
+
* whether the provider will end its session without asking. `form`: the fields of a POST form to
|
|
302
|
+
* `action`, for an app on the issuer's own origin (`endSession: "form-post"`).
|
|
303
|
+
*
|
|
304
|
+
* @example
|
|
305
|
+
* const result = await client.logout({ refreshToken, idToken });
|
|
306
|
+
* if (result.kind === "redirect") return new Response(null, { status: 303, headers: { Location: result.location } });
|
|
307
|
+
* return renderAutoSubmitForm(result.action, result.fields);
|
|
308
|
+
*/
|
|
309
|
+
type LogoutResult = {
|
|
310
|
+
kind: "redirect";
|
|
311
|
+
location: string;
|
|
312
|
+
ticket: boolean;
|
|
313
|
+
} | {
|
|
314
|
+
kind: "form";
|
|
315
|
+
action: string;
|
|
316
|
+
fields: Readonly<Record<string, string>>;
|
|
317
|
+
};
|
|
318
|
+
/**
|
|
319
|
+
* What `createOidcClient` returns.
|
|
320
|
+
*
|
|
321
|
+
* @example
|
|
322
|
+
* const { location, transaction } = client.startLogin({ returnTo: "/packages" });
|
|
323
|
+
* headers.append("Set-Cookie", store.commitTransaction(transaction));
|
|
324
|
+
* headers.set("Location", location);
|
|
325
|
+
* return new Response(null, { status: 302, headers });
|
|
326
|
+
*/
|
|
327
|
+
interface OidcClient {
|
|
328
|
+
/** The `environment` the client was created with. */
|
|
329
|
+
readonly environment: Environment;
|
|
330
|
+
/** The validated issuer (canonical origin). */
|
|
331
|
+
readonly issuer: string;
|
|
332
|
+
/** The client id the client was created with. */
|
|
333
|
+
readonly clientId: string;
|
|
334
|
+
/** Builds the authorization URL (code + PKCE S256) and its transaction. Throws `TypeError` on a bad input. */
|
|
335
|
+
startLogin(input: StartLoginInput): StartLoginResult;
|
|
336
|
+
/**
|
|
337
|
+
* Checks the callback URL against the transaction, exchanges the code and checks the ID token.
|
|
338
|
+
* Rejects with an `OidcError`; the app clears the transaction cookie on every path.
|
|
339
|
+
*
|
|
340
|
+
* @example
|
|
341
|
+
* const { tokens, claims, transaction } = await client.handleCallback(request.url, store.readTransaction(request));
|
|
342
|
+
*/
|
|
343
|
+
handleCallback(url: URL | string, transaction: OidcTransaction | null, options?: HandleCallbackOptions): Promise<CallbackResult>;
|
|
344
|
+
/**
|
|
345
|
+
* One rotated refresh. Calls with the same refresh token share one request (and its result for
|
|
346
|
+
* 30 s) through the client's `refreshLock`. Rejects with an `OidcError`: `invalid_grant` and
|
|
347
|
+
* `invalid_target` mean the session is over.
|
|
348
|
+
*
|
|
349
|
+
* @example
|
|
350
|
+
* const tokens = await client.refresh(auth.refresh_token);
|
|
351
|
+
*/
|
|
352
|
+
refresh(refreshToken: string): Promise<TokenSet>;
|
|
353
|
+
/**
|
|
354
|
+
* Renews `auth` when its access token is about to expire. Never changes `auth` itself. A refresh
|
|
355
|
+
* that fails while the access token still works keeps the current auth (`changed: false`), except
|
|
356
|
+
* for `invalid_grant` and `invalid_target`, which always reject: the app then clears the session.
|
|
357
|
+
*
|
|
358
|
+
* @example
|
|
359
|
+
* const { auth, changed } = await client.ensureFresh(session.data.auth);
|
|
360
|
+
* if (changed) session.update({ auth });
|
|
361
|
+
*/
|
|
362
|
+
ensureFresh<A extends RefreshableAuth>(auth: A, options?: EnsureFreshOptions): Promise<EnsureFreshResult<A>>;
|
|
363
|
+
/**
|
|
364
|
+
* Revokes the refresh token and builds the provider's end-session step. Never rejects: a failed
|
|
365
|
+
* back-channel call is one `onFailure` event. The app clears its session cookies itself.
|
|
366
|
+
*
|
|
367
|
+
* @example
|
|
368
|
+
* const result = await client.logout({ refreshToken: auth?.refresh_token, idToken: auth?.id_token });
|
|
369
|
+
* if (result.kind === "redirect") return redirect(result.location, { status: 303, headers });
|
|
370
|
+
*/
|
|
371
|
+
logout(input: LogoutInput): Promise<LogoutResult>;
|
|
372
|
+
}
|
|
373
|
+
|
|
374
|
+
export { memoryLockStore as m };
|
|
375
|
+
export type { CallbackResult as C, EnsureFreshOptions as E, HandleCallbackOptions as H, LogoutInput as L, OidcClientOptions as O, RefreshLockStore as R, StartLoginInput as S, VerifiedIdTokenClaims as V, OidcClient as a, EnsureFreshResult as b, LogoutResult as c, OidcFailureEvent as d, OidcFetch as e, OidcOperation as f, OidcTransaction as g, RefreshableAuth as h, StartLoginResult as i };
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
# Install paket `@plasgos/*`
|
|
2
|
+
|
|
3
|
+
Panduan ini untuk aplikasi yang memakai paket `@plasgos/oidc-client` atau `@plasgos/auth-verify`. Isinya: cara install di laptop, di Docker, dan di CI, aturan versi, dan lisensi.
|
|
4
|
+
|
|
5
|
+
Paket diterbitkan di npmjs.com (`registry.npmjs.org`) sebagai paket **publik** di scope `@plasgos`, sama seperti paket `@plasgos/*` lain (misalnya `@plasgos/webchat`). Install tidak butuh token, `.npmrc` khusus, atau secret. Repo sumbernya privat; yang publik hanya paket hasil build. Panduan pemakaian ikut di dalam paket `@plasgos/oidc-client` dan `@plasgos/auth-verify` (isinya sama), di folder `docs/`: bisa dibaca di tab **Code** halaman paket di npmjs.com, atau di `node_modules/@plasgos/oidc-client/docs/` atau `node_modules/@plasgos/auth-verify/docs/` setelah install.
|
|
6
|
+
|
|
7
|
+
Status saat ini: `@plasgos/auth-shared`, `@plasgos/oidc-client`, dan `@plasgos/auth-verify` terbit di npmjs.com sebagai pre-release, selalu dengan nomor versi yang sama. Cek versi yang ada dengan `npm view @plasgos/auth-verify versions`.
|
|
8
|
+
|
|
9
|
+
Setelah paket terpasang, lanjut ke [`memulai.md`](memulai.md).
|
|
10
|
+
|
|
11
|
+
## 1. Install
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
pnpm add @plasgos/oidc-client@<versi> --save-exact
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Aplikasi yang menerima webhook dari Plasgos meng-install `@plasgos/auth-verify`, sendiri atau di samping `@plasgos/oidc-client`, dengan versi yang sama:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
pnpm add @plasgos/auth-verify@<versi> --save-exact
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Ganti `<versi>` dengan nomor versi persis (lihat §5). `@plasgos/auth-shared` ikut terpasang dengan versi yang sama, jadi tidak perlu di-install sendiri.
|
|
24
|
+
|
|
25
|
+
Perintah ini sama di laptop, di Docker, dan di CI. Tidak ada token yang perlu dibuat atau diatur.
|
|
26
|
+
|
|
27
|
+
## 2. `.npmrc` di repo aplikasi
|
|
28
|
+
|
|
29
|
+
Tidak perlu baris apa pun untuk `@plasgos`. Paket diambil dari registry bawaan (`registry.npmjs.org`).
|
|
30
|
+
|
|
31
|
+
Bila `.npmrc` aplikasi masih punya baris yang mengarahkan `@plasgos` ke GitHub Packages, hapus baris itu beserta baris token-nya:
|
|
32
|
+
|
|
33
|
+
```
|
|
34
|
+
@plasgos:registry=https://npm.pkg.github.com
|
|
35
|
+
//npm.pkg.github.com/:_authToken=${NPM_TOKEN}
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Satu scope hanya bisa diarahkan ke satu registry. Selama baris pertama masih ada, semua paket `@plasgos/*` dicari di GitHub Packages dan install gagal. Baris lain di `.npmrc` (misalnya `save-exact=true`) tetap dipakai.
|
|
39
|
+
|
|
40
|
+
## 3. Dockerfile
|
|
41
|
+
|
|
42
|
+
Install di Docker cukup `pnpm install` biasa. Tidak ada BuildKit secret, `--mount=type=secret`, `ARG`, atau `ENV` untuk token.
|
|
43
|
+
|
|
44
|
+
```dockerfile
|
|
45
|
+
FROM node:26-trixie-slim AS deps
|
|
46
|
+
WORKDIR /app
|
|
47
|
+
COPY package.json pnpm-lock.yaml ./
|
|
48
|
+
# Node 26 tidak lagi membawa corepack, jadi pnpm dipasang lewat npm (versi dari `packageManager`).
|
|
49
|
+
RUN npm install -g --no-fund --no-audit "$(node -p 'require("./package.json").packageManager')"
|
|
50
|
+
RUN pnpm install --frozen-lockfile
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Build-nya:
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
docker build -t app .
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Aturan:
|
|
60
|
+
|
|
61
|
+
- Stage `runtime` hanya mengambil `node_modules`, hasil build, dan file yang dibutuhkan saat aplikasi berjalan. Stage itu tidak meng-copy `.npmrc`.
|
|
62
|
+
- Bila Dockerfile aplikasi masih memakai `--mount=type=secret,id=npm_token,…` hanya untuk `@plasgos/*`, mount itu boleh dihapus, begitu juga `--secret id=npm_token,…` di perintah `docker build`.
|
|
63
|
+
|
|
64
|
+
## 4. CI
|
|
65
|
+
|
|
66
|
+
GitLab CI dan GitHub Actions menjalankan `pnpm install` atau `docker build` seperti biasa, tanpa variable atau secret untuk paket ini.
|
|
67
|
+
|
|
68
|
+
Bila project GitLab aplikasi punya variable `NPM_TOKEN` yang hanya dipakai untuk `@plasgos/*` dari GitHub Packages, variable itu tidak dipakai lagi dan boleh dihapus. Bila workflow GitHub Actions aplikasi memberi `packages: read` dan meneruskan `GITHUB_TOKEN` hanya untuk paket ini, keduanya juga boleh dihapus.
|
|
69
|
+
|
|
70
|
+
## 5. Versi
|
|
71
|
+
|
|
72
|
+
- Selama versi masih `0.x`, tulis rentang `~0.y.z` di `package.json` aplikasi. Di `0.x`, kenaikan minor dianggap breaking, jadi aplikasi hanya menerima patch secara otomatis. `pnpm add` tidak menulis rentang ini (ia menulis versi persis bila `save-exact=true`, selain itu `^`), jadi ubah rentangnya dengan tangan setelah `pnpm add`.
|
|
73
|
+
- Setelah `1.0.0`, pakai rentang `^`.
|
|
74
|
+
- Versi yang benar-benar terpasang ditentukan lockfile aplikasi. Menaikkan versi berarti membuat PR di repo aplikasi, supaya test aplikasi ikut berjalan.
|
|
75
|
+
- Semua paket `@plasgos/*` di SDK ini dirilis dengan nomor versi yang sama. Aplikasi yang memakai dua paket menaikkan keduanya sekaligus.
|
|
76
|
+
- `@plasgos/auth-shared` tidak di-install langsung. Paket itu ikut terpasang sebagai dependensi `oidc-client` dan `auth-verify`.
|
|
77
|
+
|
|
78
|
+
**Pre-release `next`.** Versi uji terbit sebagai `x.y.z-next.n`. Pre-release hanya di-install dengan nomor versi persis (§1), yang diambil dari halaman paket di npmjs.com atau `CHANGELOG.md` paket. Dist-tag `next` tidak dijamin menunjuk ke versi uji terbaru, jadi jangan meng-install dengan `@next`.
|
|
79
|
+
|
|
80
|
+
Rentang `~0.y.z` tidak pernah cocok dengan pre-release. Sampai rilis stabil pertama terbit, `pnpm add @plasgos/oidc-client` tanpa nomor versi gagal (tidak ada versi di dist-tag `latest`) atau mendapat sebuah pre-release yang tidak Anda pilih. Karena itu selalu install dengan nomor versi persis.
|
|
81
|
+
|
|
82
|
+
Perintah di §1 menulis versi persis (`x.y.z-next.n`) ke `package.json`, dan versi persis tidak pernah pindah sendiri. Bila yang tertulis adalah rentang `^` atau `~` pada pre-release, rentang itu juga menerima rilis stabil di minor yang sama, tetapi lockfile menahan pre-release itu sampai aplikasi menjalankan `pnpm update`. Setelah rilis stabil terbit, ubah versinya menjadi `~0.y.z` lewat PR.
|
|
83
|
+
|
|
84
|
+
**Perbaikan keamanan.** Perbaikan dirilis sebagai patch, dan tim Plasgos memberi tahu tim aplikasi yang memakai paket ini. Naikkan versi, perbarui lockfile, dan deploy secepatnya. Versi yang bermasalah di-deprecate (`npm deprecate`), tidak dihapus, supaya lockfile lama tetap bisa di-install sampai aplikasinya naik versi.
|
|
85
|
+
|
|
86
|
+
## 6. Isi paket dan lisensi
|
|
87
|
+
|
|
88
|
+
- Paket berisi `dist` (ESM, CJS, `.d.ts`, dan source map), `README.md`, `CHANGELOG.md`, dan `LICENSE`. `@plasgos/oidc-client` dan `@plasgos/auth-verify` juga membawa folder `docs/` dengan isi yang sama: panduan ini dan file contohnya (`docs/examples/`).
|
|
89
|
+
- Source map ikut terbit lengkap dengan `sourcesContent`, supaya stack trace menunjuk ke sumber TypeScript. Karena paketnya publik, sumber TypeScript paket ikut terbaca siapa pun yang mengunduh paket. Ini disengaja.
|
|
90
|
+
- Lisensi: bukan open source. Paket milik Plasgos dan hanya boleh dipakai untuk menghubungkan aplikasi ke layanan Plasgos (login dan API Plasgos) oleh pemegang kredensial client resmi dari Plasgos dan pengembang yang bekerja untuk mereka. Menyalin, mengubah, menerbitkan ulang, atau mendistribusikan paket tanpa izin tertulis Plasgos dilarang. Teks lengkapnya ada di file [`LICENSE`](../LICENSE) di setiap paket.
|