@gemina/elements 0.1.2 → 0.2.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/README.md +24 -0
- package/dist/chat.cjs +79 -3
- package/dist/chat.cjs.map +1 -1
- package/dist/chat.js +1 -1
- package/dist/{chunk-DGY2IT73.js → chunk-2UMJ235A.js} +80 -4
- package/dist/chunk-2UMJ235A.js.map +1 -0
- package/dist/index.cjs +79 -3
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +1 -1
- package/package.json +1 -1
- package/dist/chat.d.cts +0 -45
- package/dist/chat.d.ts +0 -45
- package/dist/chunk-DGY2IT73.js.map +0 -1
- package/dist/index.d.cts +0 -8
- package/dist/index.d.ts +0 -8
- package/dist/token-manager.d.cts +0 -99
- package/dist/token-manager.d.ts +0 -99
package/dist/token-manager.d.cts
DELETED
|
@@ -1,99 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* GeminaTokenManager — in-memory holder for short-lived Gemina session
|
|
3
|
-
* tokens, per the Document Intelligence token spec (PRD §6.11.1).
|
|
4
|
-
*
|
|
5
|
-
* Security model (the five footguns this file designs out):
|
|
6
|
-
*
|
|
7
|
-
* 1. **The API key never enters the browser.** The constructor throws if it
|
|
8
|
-
* is handed a raw string instead of a `fetchToken` callback, and
|
|
9
|
-
* `getToken()` rejects if the callback ever resolves with an
|
|
10
|
-
* API-key-shaped string (32 alphanumerics, no dots).
|
|
11
|
-
* 2. **The token is never persisted.** No `localStorage`, `sessionStorage`,
|
|
12
|
-
* cookies, or IndexedDB anywhere in this package — the token lives only
|
|
13
|
-
* in memory, inside state that is not an own property of the instance.
|
|
14
|
-
* 3. **The browser never asserts its own scope.** This manager carries no
|
|
15
|
-
* scope parameters at all; scope is signed into the token server-side.
|
|
16
|
-
* 4. **No refresh token is held in the browser.** Renewal always goes back
|
|
17
|
-
* through the tenant's own authenticated backend via `fetchToken`.
|
|
18
|
-
* 5. **The SDK cannot mint or widen TTL/scope.** This class only *stores*
|
|
19
|
-
* what the tenant backend minted; it has no code path to
|
|
20
|
-
* `POST /v1/sessions/token`.
|
|
21
|
-
*
|
|
22
|
-
* Storage choice: internal state (including the token) lives in a
|
|
23
|
-
* module-scoped `WeakMap` keyed by the instance rather than in an ordinary
|
|
24
|
-
* class field. An ordinary field — even a `#private` one via devtools — is
|
|
25
|
-
* trivially discoverable by enumerating the instance; the WeakMap keeps the
|
|
26
|
-
* token out of `Object.keys`, `JSON.stringify`, spread copies, and casual
|
|
27
|
-
* inspection, and it is unreachable without a reference to both the WeakMap
|
|
28
|
-
* (module-private) and the instance. This is hardening against accidental
|
|
29
|
-
* exposure/serialization, not encryption: code running in the same realm
|
|
30
|
-
* with a debugger can still read process memory. The upgrade path for
|
|
31
|
-
* stronger isolation is a Web Worker (see PRD §6.11.1).
|
|
32
|
-
*
|
|
33
|
-
* SSR-safe: this module touches no `window`/`document` at import time and
|
|
34
|
-
* starts no timers — refresh happens lazily inside `getToken()`, so an idle
|
|
35
|
-
* manager consumes nothing and never keeps a Node process alive.
|
|
36
|
-
*/
|
|
37
|
-
/** What `fetchToken` must resolve with (mirror of the mint response). */
|
|
38
|
-
interface FetchTokenResult {
|
|
39
|
-
/** The raw session token (a JWT). Pass it WITHOUT a "Bearer " prefix. */
|
|
40
|
-
token: string;
|
|
41
|
-
/** Token lifetime in seconds, as returned by the mint endpoint. */
|
|
42
|
-
expiresIn: number;
|
|
43
|
-
}
|
|
44
|
-
/** Constructor options for {@link GeminaTokenManager}. */
|
|
45
|
-
interface GeminaTokenManagerOptions {
|
|
46
|
-
/**
|
|
47
|
-
* Callback that obtains a fresh session token from the TENANT'S OWN
|
|
48
|
-
* backend (which in turn calls Gemina's `POST /v1/sessions/token` with
|
|
49
|
-
* the API key, server-side). It must resolve with
|
|
50
|
-
* `{ token, expiresIn }`. It must NEVER return a Gemina API key.
|
|
51
|
-
*/
|
|
52
|
-
fetchToken: () => Promise<FetchTokenResult>;
|
|
53
|
-
/**
|
|
54
|
-
* How many seconds before the token's expiry `getToken()` starts
|
|
55
|
-
* refreshing. Default 60 (the PRD's `exp − 60s` refresh point).
|
|
56
|
-
*/
|
|
57
|
-
refreshSkewSeconds?: number;
|
|
58
|
-
}
|
|
59
|
-
/**
|
|
60
|
-
* Holds a short-lived Gemina session token in memory and keeps it fresh.
|
|
61
|
-
*
|
|
62
|
-
* ```ts
|
|
63
|
-
* const tokenManager = new GeminaTokenManager({
|
|
64
|
-
* // YOUR backend endpoint — it holds the API key and mints the token.
|
|
65
|
-
* fetchToken: async () => {
|
|
66
|
-
* const res = await fetch("/api/gemina-session", { method: "POST" });
|
|
67
|
-
* if (!res.ok) throw new Error("Failed to mint Gemina session token");
|
|
68
|
-
* return res.json(); // { token, expiresIn }
|
|
69
|
-
* },
|
|
70
|
-
* });
|
|
71
|
-
* ```
|
|
72
|
-
*
|
|
73
|
-
* - `getToken()` fetches lazily on first use, then auto-refreshes when the
|
|
74
|
-
* cached token is within `refreshSkewSeconds` of expiry. Concurrent
|
|
75
|
-
* callers share a single in-flight fetch.
|
|
76
|
-
* - `invalidate()` drops the cache so the next `getToken()` refetches
|
|
77
|
-
* (use after a 401).
|
|
78
|
-
* - No timers run while idle; nothing is ever written to storage.
|
|
79
|
-
*/
|
|
80
|
-
declare class GeminaTokenManager {
|
|
81
|
-
constructor(options: GeminaTokenManagerOptions);
|
|
82
|
-
/**
|
|
83
|
-
* Return a valid session token, fetching or refreshing as needed.
|
|
84
|
-
*
|
|
85
|
-
* A cached token is reused until `now >= expiry - refreshSkewSeconds`
|
|
86
|
-
* (expiry computed as `Date.now() + expiresIn * 1000` at fetch time).
|
|
87
|
-
* All concurrent callers during a refresh share ONE in-flight fetch.
|
|
88
|
-
* A failed fetch is not cached — the next call retries.
|
|
89
|
-
*/
|
|
90
|
-
getToken(): Promise<string>;
|
|
91
|
-
/**
|
|
92
|
-
* Drop the cached token (and detach any in-flight refresh) so the next
|
|
93
|
-
* `getToken()` fetches a fresh one. Call this when the API answers 401,
|
|
94
|
-
* then retry the request once with a new `getToken()`.
|
|
95
|
-
*/
|
|
96
|
-
invalidate(): void;
|
|
97
|
-
}
|
|
98
|
-
|
|
99
|
-
export { type FetchTokenResult, GeminaTokenManager, type GeminaTokenManagerOptions };
|
package/dist/token-manager.d.ts
DELETED
|
@@ -1,99 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* GeminaTokenManager — in-memory holder for short-lived Gemina session
|
|
3
|
-
* tokens, per the Document Intelligence token spec (PRD §6.11.1).
|
|
4
|
-
*
|
|
5
|
-
* Security model (the five footguns this file designs out):
|
|
6
|
-
*
|
|
7
|
-
* 1. **The API key never enters the browser.** The constructor throws if it
|
|
8
|
-
* is handed a raw string instead of a `fetchToken` callback, and
|
|
9
|
-
* `getToken()` rejects if the callback ever resolves with an
|
|
10
|
-
* API-key-shaped string (32 alphanumerics, no dots).
|
|
11
|
-
* 2. **The token is never persisted.** No `localStorage`, `sessionStorage`,
|
|
12
|
-
* cookies, or IndexedDB anywhere in this package — the token lives only
|
|
13
|
-
* in memory, inside state that is not an own property of the instance.
|
|
14
|
-
* 3. **The browser never asserts its own scope.** This manager carries no
|
|
15
|
-
* scope parameters at all; scope is signed into the token server-side.
|
|
16
|
-
* 4. **No refresh token is held in the browser.** Renewal always goes back
|
|
17
|
-
* through the tenant's own authenticated backend via `fetchToken`.
|
|
18
|
-
* 5. **The SDK cannot mint or widen TTL/scope.** This class only *stores*
|
|
19
|
-
* what the tenant backend minted; it has no code path to
|
|
20
|
-
* `POST /v1/sessions/token`.
|
|
21
|
-
*
|
|
22
|
-
* Storage choice: internal state (including the token) lives in a
|
|
23
|
-
* module-scoped `WeakMap` keyed by the instance rather than in an ordinary
|
|
24
|
-
* class field. An ordinary field — even a `#private` one via devtools — is
|
|
25
|
-
* trivially discoverable by enumerating the instance; the WeakMap keeps the
|
|
26
|
-
* token out of `Object.keys`, `JSON.stringify`, spread copies, and casual
|
|
27
|
-
* inspection, and it is unreachable without a reference to both the WeakMap
|
|
28
|
-
* (module-private) and the instance. This is hardening against accidental
|
|
29
|
-
* exposure/serialization, not encryption: code running in the same realm
|
|
30
|
-
* with a debugger can still read process memory. The upgrade path for
|
|
31
|
-
* stronger isolation is a Web Worker (see PRD §6.11.1).
|
|
32
|
-
*
|
|
33
|
-
* SSR-safe: this module touches no `window`/`document` at import time and
|
|
34
|
-
* starts no timers — refresh happens lazily inside `getToken()`, so an idle
|
|
35
|
-
* manager consumes nothing and never keeps a Node process alive.
|
|
36
|
-
*/
|
|
37
|
-
/** What `fetchToken` must resolve with (mirror of the mint response). */
|
|
38
|
-
interface FetchTokenResult {
|
|
39
|
-
/** The raw session token (a JWT). Pass it WITHOUT a "Bearer " prefix. */
|
|
40
|
-
token: string;
|
|
41
|
-
/** Token lifetime in seconds, as returned by the mint endpoint. */
|
|
42
|
-
expiresIn: number;
|
|
43
|
-
}
|
|
44
|
-
/** Constructor options for {@link GeminaTokenManager}. */
|
|
45
|
-
interface GeminaTokenManagerOptions {
|
|
46
|
-
/**
|
|
47
|
-
* Callback that obtains a fresh session token from the TENANT'S OWN
|
|
48
|
-
* backend (which in turn calls Gemina's `POST /v1/sessions/token` with
|
|
49
|
-
* the API key, server-side). It must resolve with
|
|
50
|
-
* `{ token, expiresIn }`. It must NEVER return a Gemina API key.
|
|
51
|
-
*/
|
|
52
|
-
fetchToken: () => Promise<FetchTokenResult>;
|
|
53
|
-
/**
|
|
54
|
-
* How many seconds before the token's expiry `getToken()` starts
|
|
55
|
-
* refreshing. Default 60 (the PRD's `exp − 60s` refresh point).
|
|
56
|
-
*/
|
|
57
|
-
refreshSkewSeconds?: number;
|
|
58
|
-
}
|
|
59
|
-
/**
|
|
60
|
-
* Holds a short-lived Gemina session token in memory and keeps it fresh.
|
|
61
|
-
*
|
|
62
|
-
* ```ts
|
|
63
|
-
* const tokenManager = new GeminaTokenManager({
|
|
64
|
-
* // YOUR backend endpoint — it holds the API key and mints the token.
|
|
65
|
-
* fetchToken: async () => {
|
|
66
|
-
* const res = await fetch("/api/gemina-session", { method: "POST" });
|
|
67
|
-
* if (!res.ok) throw new Error("Failed to mint Gemina session token");
|
|
68
|
-
* return res.json(); // { token, expiresIn }
|
|
69
|
-
* },
|
|
70
|
-
* });
|
|
71
|
-
* ```
|
|
72
|
-
*
|
|
73
|
-
* - `getToken()` fetches lazily on first use, then auto-refreshes when the
|
|
74
|
-
* cached token is within `refreshSkewSeconds` of expiry. Concurrent
|
|
75
|
-
* callers share a single in-flight fetch.
|
|
76
|
-
* - `invalidate()` drops the cache so the next `getToken()` refetches
|
|
77
|
-
* (use after a 401).
|
|
78
|
-
* - No timers run while idle; nothing is ever written to storage.
|
|
79
|
-
*/
|
|
80
|
-
declare class GeminaTokenManager {
|
|
81
|
-
constructor(options: GeminaTokenManagerOptions);
|
|
82
|
-
/**
|
|
83
|
-
* Return a valid session token, fetching or refreshing as needed.
|
|
84
|
-
*
|
|
85
|
-
* A cached token is reused until `now >= expiry - refreshSkewSeconds`
|
|
86
|
-
* (expiry computed as `Date.now() + expiresIn * 1000` at fetch time).
|
|
87
|
-
* All concurrent callers during a refresh share ONE in-flight fetch.
|
|
88
|
-
* A failed fetch is not cached — the next call retries.
|
|
89
|
-
*/
|
|
90
|
-
getToken(): Promise<string>;
|
|
91
|
-
/**
|
|
92
|
-
* Drop the cached token (and detach any in-flight refresh) so the next
|
|
93
|
-
* `getToken()` fetches a fresh one. Call this when the API answers 401,
|
|
94
|
-
* then retry the request once with a new `getToken()`.
|
|
95
|
-
*/
|
|
96
|
-
invalidate(): void;
|
|
97
|
-
}
|
|
98
|
-
|
|
99
|
-
export { type FetchTokenResult, GeminaTokenManager, type GeminaTokenManagerOptions };
|