@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,289 @@
|
|
|
1
|
+
import { g as OidcTransaction } from './types-JE0OMyoi.js';
|
|
2
|
+
export { R as RefreshLockStore, m as memoryLockStore } from './types-JE0OMyoi.js';
|
|
3
|
+
import { Environment } from '@plasgos/auth-shared';
|
|
4
|
+
export { ConfigError } from '@plasgos/auth-shared';
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* The keys of one cookie: `current` seals, every key in `all` (by kid) opens.
|
|
8
|
+
*
|
|
9
|
+
* @example
|
|
10
|
+
* const ring: KeyRing = deriveKeyRing([process.env.SESSION_SECRET ?? ""], "kp", "plasgos-shipping-v2");
|
|
11
|
+
* ring.all.has(ring.current.kid); // true
|
|
12
|
+
*/
|
|
13
|
+
interface KeyRing {
|
|
14
|
+
/** The key that seals: derived from the first secret. */
|
|
15
|
+
readonly current: {
|
|
16
|
+
readonly kid: string;
|
|
17
|
+
readonly key: Buffer;
|
|
18
|
+
};
|
|
19
|
+
/** Every key that opens, by kid. */
|
|
20
|
+
readonly all: ReadonlyMap<string, Buffer>;
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* Derives the key ring of one cookie: HKDF-SHA256(secret, hkdfSalt, "cookie:<cookie>:v1", 32) per
|
|
24
|
+
* secret. The first secret seals, all of them open; the kid is the first 8 base64url characters of
|
|
25
|
+
* the key's SHA-256. Throws when `secrets` is empty.
|
|
26
|
+
*
|
|
27
|
+
* @example
|
|
28
|
+
* // Rotation: the new secret first, the old one kept until its cookies have expired.
|
|
29
|
+
* const ring = deriveKeyRing([newSecret, oldSecret], "kp-auth", "plasgos-shipping-v2");
|
|
30
|
+
*/
|
|
31
|
+
declare function deriveKeyRing(secrets: readonly string[], cookie: string, hkdfSalt: string): KeyRing;
|
|
32
|
+
/**
|
|
33
|
+
* Seals `value` (as JSON) for the cookie named `cookie` with `ring.current`: AES-256-GCM, a fresh
|
|
34
|
+
* random 96-bit IV, AAD `v1.<cookie>`, wire format `v1.<kid>.<iv>.<ct>.<tag>` (base64url).
|
|
35
|
+
*
|
|
36
|
+
* @example
|
|
37
|
+
* const sealed = sealCookie("kp", { theme: "dark" }, ring);
|
|
38
|
+
* // "v1.<kid>.<iv>.<ct>.<tag>"
|
|
39
|
+
*/
|
|
40
|
+
declare function sealCookie(cookie: string, value: unknown, ring: KeyRing): string;
|
|
41
|
+
/**
|
|
42
|
+
* Opens a value sealed by {@link sealCookie} for the same cookie name. Returns the value and the kid
|
|
43
|
+
* of the key that opened it (compare with `ring.current.kid` to re-seal after a rotation), or null
|
|
44
|
+
* for anything that does not open: malformed, tampered, another key, another cookie name. Never
|
|
45
|
+
* throws on input.
|
|
46
|
+
*
|
|
47
|
+
* @example
|
|
48
|
+
* const opened = openCookie("kp", sealed, ring);
|
|
49
|
+
* if (opened === null) return null; // no session
|
|
50
|
+
* const needsReseal = opened.kid !== ring.current.kid;
|
|
51
|
+
*/
|
|
52
|
+
declare function openCookie(cookie: string, sealed: string, ring: KeyRing): {
|
|
53
|
+
value: unknown;
|
|
54
|
+
kid: string;
|
|
55
|
+
} | null;
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* The signed-in user as the session keeps it.
|
|
59
|
+
*
|
|
60
|
+
* @example
|
|
61
|
+
* const user: SessionUser = { id: claims.sub, name: claims.name ?? "", email: claims.email ?? null, avatar_url: null };
|
|
62
|
+
*/
|
|
63
|
+
interface SessionUser {
|
|
64
|
+
/** The app's id of the user, usually the ID token `sub`. 1 to 512 characters. */
|
|
65
|
+
id: string;
|
|
66
|
+
/** Display name, at most 512 characters; may be empty. */
|
|
67
|
+
name: string;
|
|
68
|
+
/** Stored by plasgos-shipping-v2 (`null` when unknown); absent in plasgos-accounts-v2. */
|
|
69
|
+
email?: string | null | undefined;
|
|
70
|
+
/** Picture URL, or null. */
|
|
71
|
+
avatar_url: string | null;
|
|
72
|
+
}
|
|
73
|
+
/**
|
|
74
|
+
* The tokens and the user of a signed-in session.
|
|
75
|
+
*
|
|
76
|
+
* @example
|
|
77
|
+
* session.update({
|
|
78
|
+
* auth: {
|
|
79
|
+
* access_token: tokens.access_token,
|
|
80
|
+
* refresh_token: tokens.refresh_token,
|
|
81
|
+
* expires_at: accessTokenExpiry(tokens, Date.now()),
|
|
82
|
+
* user: { id: claims.sub, name: "Budi", email: null, avatar_url: null },
|
|
83
|
+
* id_token: tokens.id_token,
|
|
84
|
+
* },
|
|
85
|
+
* });
|
|
86
|
+
*/
|
|
87
|
+
interface AuthState {
|
|
88
|
+
/** 1 to 4096 characters. */
|
|
89
|
+
access_token: string;
|
|
90
|
+
/** 1 to 4096 characters; absent for a client without refresh tokens. */
|
|
91
|
+
refresh_token?: string | undefined;
|
|
92
|
+
/** Epoch seconds. */
|
|
93
|
+
expires_at: number;
|
|
94
|
+
/** The signed-in user. */
|
|
95
|
+
user: SessionUser;
|
|
96
|
+
/** Kept in its own cookie (idToken), only for the logout ticket / id_token_hint. */
|
|
97
|
+
id_token?: string | undefined;
|
|
98
|
+
/** Epoch seconds of the login, kept across refreshes. */
|
|
99
|
+
auth_time?: number | undefined;
|
|
100
|
+
/** Remember-me (accounts); drives authMaxAgeSeconds when it is a function. */
|
|
101
|
+
remember?: boolean | undefined;
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* Validates the app cookie; `null` means "no app data". The app's zod schema fits behind it.
|
|
106
|
+
*
|
|
107
|
+
* @example
|
|
108
|
+
* const appSchema: SessionSchema<{ theme?: string }> = {
|
|
109
|
+
* parse: (input) => (isThemeObject(input) ? input : null),
|
|
110
|
+
* };
|
|
111
|
+
*/
|
|
112
|
+
interface SessionSchema<T> {
|
|
113
|
+
/** Returns the validated app data, or null when `input` is not what the app stored. May throw: that counts as null. */
|
|
114
|
+
parse(input: unknown): T | null;
|
|
115
|
+
}
|
|
116
|
+
/**
|
|
117
|
+
* The app's own session fields plus the SDK-owned `auth`.
|
|
118
|
+
*
|
|
119
|
+
* @example
|
|
120
|
+
* type App = { flash?: string };
|
|
121
|
+
* const data: SessionData<App> = store.read(request).data;
|
|
122
|
+
* data.flash; data.auth?.user.id;
|
|
123
|
+
*/
|
|
124
|
+
type SessionData<App extends object> = Omit<App, "auth"> & {
|
|
125
|
+
auth?: AuthState | undefined;
|
|
126
|
+
};
|
|
127
|
+
/**
|
|
128
|
+
* One request's session.
|
|
129
|
+
*
|
|
130
|
+
* @example
|
|
131
|
+
* const session = store.read(request);
|
|
132
|
+
* session.update({ flash: { kind: "success", message: "Tersimpan" } });
|
|
133
|
+
* session.update({ auth: undefined }); // sign out, the app data stays
|
|
134
|
+
* const setCookies = store.commit(session);
|
|
135
|
+
*/
|
|
136
|
+
interface SessionHandle<App extends object> {
|
|
137
|
+
/** The current session: the app's fields and `auth` when signed in. */
|
|
138
|
+
readonly data: Readonly<SessionData<App>>;
|
|
139
|
+
/** True when anything has to be written back. */
|
|
140
|
+
readonly dirty: boolean;
|
|
141
|
+
/** Auth changed (login, refresh, logout, destroy). Never set by a key migration alone. */
|
|
142
|
+
readonly authDirty: boolean;
|
|
143
|
+
/** Anything but auth changed, or the app cookie was opened with a retiring secret. */
|
|
144
|
+
readonly restDirty: boolean;
|
|
145
|
+
/** A key given as `undefined` is deleted (works under exactOptionalPropertyTypes). */
|
|
146
|
+
update(patch: {
|
|
147
|
+
[K in keyof SessionData<App>]?: SessionData<App>[K] | undefined;
|
|
148
|
+
}): void;
|
|
149
|
+
/** Deletes one key; nothing happens when it is absent. */
|
|
150
|
+
unset(key: keyof SessionData<App>): void;
|
|
151
|
+
/** Empties the session; the next commit expires its cookies. */
|
|
152
|
+
destroy(): void;
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/**
|
|
156
|
+
* What `commit()` reports when a cookie did not fit and was expired instead. Sizes only.
|
|
157
|
+
*
|
|
158
|
+
* @example
|
|
159
|
+
* createSessionStore({
|
|
160
|
+
* ...options,
|
|
161
|
+
* onFailure: (event) => logger.warn(`session cookie ${event.cookie} dropped: ${String(event.size)} chars`),
|
|
162
|
+
* });
|
|
163
|
+
*/
|
|
164
|
+
type SessionFailureEvent = {
|
|
165
|
+
/** The only kind so far. */
|
|
166
|
+
kind: "session_too_large";
|
|
167
|
+
/** The cookie that did not fit. */
|
|
168
|
+
cookie: "app" | "auth" | "idToken";
|
|
169
|
+
/** Length of the refused `Set-Cookie` value, in characters. */
|
|
170
|
+
size: number;
|
|
171
|
+
};
|
|
172
|
+
/**
|
|
173
|
+
* A cookie would not fit in a browser. Thrown by `commitApp`, `commitAuth` and `commitIdToken`;
|
|
174
|
+
* `commit()` handles it itself.
|
|
175
|
+
*
|
|
176
|
+
* @example
|
|
177
|
+
* try {
|
|
178
|
+
* headers.append("Set-Cookie", store.commitAuth(session));
|
|
179
|
+
* } catch (error) {
|
|
180
|
+
* if (error instanceof SessionTooLargeError) return loginFailed();
|
|
181
|
+
* throw error;
|
|
182
|
+
* }
|
|
183
|
+
*/
|
|
184
|
+
declare class SessionTooLargeError extends Error {
|
|
185
|
+
/** Length of the refused `Set-Cookie` value, in characters. */
|
|
186
|
+
readonly size: number;
|
|
187
|
+
/** Message "Session cookie too large: <size> chars (limit 4000)"; never the cookie value. */
|
|
188
|
+
constructor(size: number);
|
|
189
|
+
}
|
|
190
|
+
/**
|
|
191
|
+
* Options of {@link createSessionStore}. For an app that already has sessions, `hkdfSalt`,
|
|
192
|
+
* `cookies` and `compactKeys` must stay exactly what the app uses today.
|
|
193
|
+
*
|
|
194
|
+
* @example
|
|
195
|
+
* const options: SessionStoreOptions<{ flash?: string }> = {
|
|
196
|
+
* environment: "production",
|
|
197
|
+
* secrets: [process.env.SESSION_SECRET ?? ""],
|
|
198
|
+
* hkdfSalt: "my-app",
|
|
199
|
+
* cookies: { app: "my", auth: "my-auth", idToken: "my-idt", transaction: "my-oidc" },
|
|
200
|
+
* authMaxAgeSeconds: 2_592_000,
|
|
201
|
+
* appSchema,
|
|
202
|
+
* };
|
|
203
|
+
*/
|
|
204
|
+
interface SessionStoreOptions<App extends object> {
|
|
205
|
+
/** The same value the app gives its client. `"production"` refuses `hostPrefix: false`. */
|
|
206
|
+
environment: Environment;
|
|
207
|
+
/** One or two secrets, each at least 32 bytes; the first seals, all open. */
|
|
208
|
+
secrets: readonly string[];
|
|
209
|
+
/** HKDF salt, for example `"plasgos-shipping-v2"`. */
|
|
210
|
+
hkdfSalt: string;
|
|
211
|
+
/** Logical cookie names (`/^[a-z0-9-]{1,32}$/`, distinct); they feed the key and the AAD. */
|
|
212
|
+
cookies: {
|
|
213
|
+
app: string;
|
|
214
|
+
auth: string;
|
|
215
|
+
idToken: string;
|
|
216
|
+
transaction: string;
|
|
217
|
+
};
|
|
218
|
+
/** `true` (default): wire name `__Host-<name>` plus `Secure`. `false` only for local http. */
|
|
219
|
+
hostPrefix?: boolean | undefined;
|
|
220
|
+
/** Max-Age of the auth and idToken cookies: a positive integer, or a function of the auth. */
|
|
221
|
+
authMaxAgeSeconds: number | ((auth: AuthState) => number);
|
|
222
|
+
/** Validates the app cookie. Every app field must be optional. */
|
|
223
|
+
appSchema: SessionSchema<Omit<App, "auth">>;
|
|
224
|
+
/** The app's compact key table, merged with the core table; omitted means no renaming. */
|
|
225
|
+
compactKeys?: Readonly<Record<string, string>> | undefined;
|
|
226
|
+
/** Receives the overflow fallbacks of `commit()`. Exceptions are swallowed. */
|
|
227
|
+
onFailure?: ((event: SessionFailureEvent) => void) | undefined;
|
|
228
|
+
}
|
|
229
|
+
/**
|
|
230
|
+
* What {@link createSessionStore} returns.
|
|
231
|
+
*
|
|
232
|
+
* @example
|
|
233
|
+
* const session = store.read(request);
|
|
234
|
+
* session.update({ auth });
|
|
235
|
+
* for (const cookie of store.commit(session)) headers.append("Set-Cookie", cookie);
|
|
236
|
+
*/
|
|
237
|
+
interface SessionStore<App extends object> {
|
|
238
|
+
/** Opens the session cookies of a request (or of a raw Cookie header). Never throws on input. */
|
|
239
|
+
read(input: Request | string | null | undefined): SessionHandle<App>;
|
|
240
|
+
/**
|
|
241
|
+
* Every `Set-Cookie` value a dirty session needs (none when clean): the app cookie when the rest
|
|
242
|
+
* changed, then auth and idToken when auth changed. A cookie that does not fit is expired, its
|
|
243
|
+
* data removed from the session, and reported through `onFailure`.
|
|
244
|
+
*/
|
|
245
|
+
commit(session: SessionHandle<App>): string[];
|
|
246
|
+
/** The app cookie (everything but auth), a browser-session cookie. Throws SessionTooLargeError. */
|
|
247
|
+
commitApp(session: SessionHandle<App>): string;
|
|
248
|
+
/** The auth cookie: tokens and user, never `id_token`. Throws SessionTooLargeError. */
|
|
249
|
+
commitAuth(session: SessionHandle<App>): string;
|
|
250
|
+
/** The idToken cookie: `auth.id_token` alone. Throws SessionTooLargeError. */
|
|
251
|
+
commitIdToken(session: SessionHandle<App>): string;
|
|
252
|
+
/** Whether the cookies of `auth` would fit, checked before a login is stored. */
|
|
253
|
+
fits(auth: AuthState): {
|
|
254
|
+
auth: boolean;
|
|
255
|
+
idToken: boolean;
|
|
256
|
+
};
|
|
257
|
+
/** The transaction, or null when missing, invalid, older than 600 s or over 5 s in the future. */
|
|
258
|
+
readTransaction(input: Request | string | null | undefined, now?: number): OidcTransaction | null;
|
|
259
|
+
/** The `Set-Cookie` value of the transaction cookie (Max-Age 600). */
|
|
260
|
+
commitTransaction(tx: OidcTransaction): string;
|
|
261
|
+
/** The `Set-Cookie` value that expires the transaction cookie. */
|
|
262
|
+
clearTransaction(): string;
|
|
263
|
+
/** Wire names (with __Host- when hostPrefix). */
|
|
264
|
+
readonly cookieNames: Readonly<{
|
|
265
|
+
app: string;
|
|
266
|
+
auth: string;
|
|
267
|
+
idToken: string;
|
|
268
|
+
transaction: string;
|
|
269
|
+
}>;
|
|
270
|
+
}
|
|
271
|
+
/**
|
|
272
|
+
* Creates the session store of an app. Throws one `ConfigError` naming every invalid option.
|
|
273
|
+
*
|
|
274
|
+
* @example
|
|
275
|
+
* const store = createSessionStore<{ flash?: Flash }>({
|
|
276
|
+
* environment: "sandbox",
|
|
277
|
+
* secrets: [process.env.SESSION_SECRET ?? ""],
|
|
278
|
+
* hkdfSalt: "my-app",
|
|
279
|
+
* cookies: { app: "my", auth: "my-auth", idToken: "my-idt", transaction: "my-oidc" },
|
|
280
|
+
* authMaxAgeSeconds: 2_592_000,
|
|
281
|
+
* appSchema: { parse: (input) => parseAppCookie(input) },
|
|
282
|
+
* });
|
|
283
|
+
* const session = store.read(request);
|
|
284
|
+
* for (const cookie of store.commit(session)) headers.append("Set-Cookie", cookie);
|
|
285
|
+
*/
|
|
286
|
+
declare function createSessionStore<App extends object>(options: SessionStoreOptions<App>): SessionStore<App>;
|
|
287
|
+
|
|
288
|
+
export { OidcTransaction, SessionTooLargeError, createSessionStore, deriveKeyRing, openCookie, sealCookie };
|
|
289
|
+
export type { AuthState, KeyRing, SessionData, SessionFailureEvent, SessionHandle, SessionSchema, SessionStore, SessionStoreOptions, SessionUser };
|