@softistx/janus-social 0.0.0-stage → 0.8.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 (105) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +356 -2
  3. package/dist/authorization-url.d.ts +21 -0
  4. package/dist/authorization-url.d.ts.map +1 -0
  5. package/dist/check-options.d.ts +22 -0
  6. package/dist/check-options.d.ts.map +1 -0
  7. package/dist/claims.d.ts +15 -0
  8. package/dist/claims.d.ts.map +1 -0
  9. package/dist/code-exchange.d.ts +79 -0
  10. package/dist/code-exchange.d.ts.map +1 -0
  11. package/dist/connections/abort.d.ts +8 -0
  12. package/dist/connections/abort.d.ts.map +1 -0
  13. package/dist/connections/at-hash.d.ts +24 -0
  14. package/dist/connections/at-hash.d.ts.map +1 -0
  15. package/dist/connections/body-limit.d.ts +15 -0
  16. package/dist/connections/body-limit.d.ts.map +1 -0
  17. package/dist/connections/build.d.ts +7 -0
  18. package/dist/connections/build.d.ts.map +1 -0
  19. package/dist/connections/check.d.ts +25 -0
  20. package/dist/connections/check.d.ts.map +1 -0
  21. package/dist/connections/claims.d.ts +16 -0
  22. package/dist/connections/claims.d.ts.map +1 -0
  23. package/dist/connections/discovery.d.ts +20 -0
  24. package/dist/connections/discovery.d.ts.map +1 -0
  25. package/dist/connections/domain.d.ts +15 -0
  26. package/dist/connections/domain.d.ts.map +1 -0
  27. package/dist/connections/guarded-fetch.d.ts +49 -0
  28. package/dist/connections/guarded-fetch.d.ts.map +1 -0
  29. package/dist/connections/id-token-steps.d.ts +15 -0
  30. package/dist/connections/id-token-steps.d.ts.map +1 -0
  31. package/dist/connections/id-token.d.ts +63 -0
  32. package/dist/connections/id-token.d.ts.map +1 -0
  33. package/dist/connections/index.d.ts +11 -0
  34. package/dist/connections/index.d.ts.map +1 -0
  35. package/dist/connections/ip.d.ts +14 -0
  36. package/dist/connections/ip.d.ts.map +1 -0
  37. package/dist/connections/issuer-cache.d.ts +40 -0
  38. package/dist/connections/issuer-cache.d.ts.map +1 -0
  39. package/dist/connections/issuer.d.ts +4 -0
  40. package/dist/connections/issuer.d.ts.map +1 -0
  41. package/dist/connections/key-flights.d.ts +16 -0
  42. package/dist/connections/key-flights.d.ts.map +1 -0
  43. package/dist/connections/memory.d.ts +10 -0
  44. package/dist/connections/memory.d.ts.map +1 -0
  45. package/dist/connections/oidc-connections.d.ts +71 -0
  46. package/dist/connections/oidc-connections.d.ts.map +1 -0
  47. package/dist/connections/provider.d.ts +25 -0
  48. package/dist/connections/provider.d.ts.map +1 -0
  49. package/dist/connections/server.d.ts +55 -0
  50. package/dist/connections/server.d.ts.map +1 -0
  51. package/dist/connections/types.d.ts +87 -0
  52. package/dist/connections/types.d.ts.map +1 -0
  53. package/dist/connections/url-policy.d.ts +30 -0
  54. package/dist/connections/url-policy.d.ts.map +1 -0
  55. package/dist/connections/wiring.d.ts +5 -0
  56. package/dist/connections/wiring.d.ts.map +1 -0
  57. package/dist/discovery.d.ts +11 -0
  58. package/dist/discovery.d.ts.map +1 -0
  59. package/dist/dpop.d.ts +18 -0
  60. package/dist/dpop.d.ts.map +1 -0
  61. package/dist/failure.d.ts +14 -0
  62. package/dist/failure.d.ts.map +1 -0
  63. package/dist/github-identity.d.ts +11 -0
  64. package/dist/github-identity.d.ts.map +1 -0
  65. package/dist/github.d.ts +11 -0
  66. package/dist/github.d.ts.map +1 -0
  67. package/dist/google.d.ts +11 -0
  68. package/dist/google.d.ts.map +1 -0
  69. package/dist/guard-error.d.ts +14 -0
  70. package/dist/guard-error.d.ts.map +1 -0
  71. package/dist/index.d.ts +23 -0
  72. package/dist/index.d.ts.map +1 -0
  73. package/dist/index.js +1825 -0
  74. package/dist/index.js.map +51 -0
  75. package/dist/microsoft-tenant.d.ts +32 -0
  76. package/dist/microsoft-tenant.d.ts.map +1 -0
  77. package/dist/microsoft.d.ts +16 -0
  78. package/dist/microsoft.d.ts.map +1 -0
  79. package/dist/oauth2.d.ts +13 -0
  80. package/dist/oauth2.d.ts.map +1 -0
  81. package/dist/oidc-engine.d.ts +62 -0
  82. package/dist/oidc-engine.d.ts.map +1 -0
  83. package/dist/oidc-step-up.d.ts +15 -0
  84. package/dist/oidc-step-up.d.ts.map +1 -0
  85. package/dist/oidc.d.ts +11 -0
  86. package/dist/oidc.d.ts.map +1 -0
  87. package/dist/options.d.ts +108 -0
  88. package/dist/options.d.ts.map +1 -0
  89. package/dist/pushed-authorization.d.ts +23 -0
  90. package/dist/pushed-authorization.d.ts.map +1 -0
  91. package/dist/step-up.d.ts +50 -0
  92. package/dist/step-up.d.ts.map +1 -0
  93. package/dist/transport.d.ts +18 -0
  94. package/dist/transport.d.ts.map +1 -0
  95. package/docs/README.md +35 -0
  96. package/docs/guide/custom-providers.md +182 -0
  97. package/docs/guide/github.md +109 -0
  98. package/docs/guide/google.md +103 -0
  99. package/docs/guide/microsoft.md +158 -0
  100. package/docs/guide/oidc-connections.md +265 -0
  101. package/docs/guide/oidc-step-up.md +122 -0
  102. package/docs/guide/par-dpop.md +63 -0
  103. package/docs/roadmap.md +33 -0
  104. package/docs/troubleshooting.md +632 -0
  105. package/package.json +67 -5
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Steve Tsala
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,357 @@
1
- # Temporary Holding Version
1
+ # @softistx/janus-social
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Social sign-in providers for [`@softistx/janus`](https://github.com/softistx/nxgt-janus/tree/develop/packages/janus),
4
+ on [oauth4webapi](https://github.com/panva/oauth4webapi): presets for Google, GitHub,
5
+ Microsoft and OpenID Connect with a step-up, and providers of your own for any OpenID Connect or OAuth 2.0
6
+ identity provider. `@softistx/janus` owns the flow (the secret, the cookie, the
7
+ links, the sessions); this package only talks to the identity provider.
8
+
9
+ > Replace what is written with `example.com` (the origins and paths) with your
10
+ > own, and the `process.env` values with your app registration's: each snippet
11
+ > below says so where a value is yours.
12
+
13
+ ```ts
14
+ import { createMemoryStores, janus, scryptHasher } from '@softistx/janus';
15
+ import { github, google, microsoft } from '@softistx/janus-social';
16
+ import { z } from 'zod';
17
+
18
+ const callback = (provider: string) => `https://app.example.com/auth/${provider}/callback`; // yours: the route that calls social.complete
19
+
20
+ export const auth = janus({
21
+ user: z.object({ email: z.email(), name: z.string() }),
22
+ password: { login: 'email' },
23
+ store: createMemoryStores(), // tests only: use a database store in production
24
+ hasher: scryptHasher(),
25
+ social: {
26
+ providers: {
27
+ google: google({
28
+ clientId: process.env.GOOGLE_CLIENT_ID!,
29
+ clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
30
+ redirectUri: callback('google'),
31
+ }),
32
+ github: github({
33
+ clientId: process.env.GITHUB_CLIENT_ID!,
34
+ clientSecret: process.env.GITHUB_CLIENT_SECRET!,
35
+ redirectUri: callback('github'),
36
+ }),
37
+ microsoft: microsoft({
38
+ clientId: process.env.MICROSOFT_CLIENT_ID!,
39
+ clientSecret: process.env.MICROSOFT_CLIENT_SECRET!,
40
+ redirectUri: callback('microsoft'),
41
+ }),
42
+ },
43
+ signUp: (profile) => ({ email: profile.email ?? '', name: profile.name ?? 'Unnamed' }),
44
+ },
45
+ });
46
+ ```
47
+
48
+ The glue is the core's two calls, one in the route that sends the visitor away,
49
+ one in the callback (the cookie, the errors and the sessions are in the
50
+ [core guide](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/social.md)):
51
+
52
+ ```ts
53
+ const start = await auth.social.start({ provider: 'google', returnTo: '/dashboard' });
54
+ // 302 to start.url, with the header set-cookie: start.setCookie
55
+
56
+ const done = await auth.social.complete({ callback: new URL(request.url).searchParams, flow }); // flow: the cookie's value
57
+ // done.status === 'signedIn': send done.token in the session cookie
58
+ ```
59
+
60
+ ## Install
61
+
62
+ Public on npmjs:
63
+
64
+ ```sh
65
+ bun add @softistx/janus-social @softistx/janus
66
+ bun add -d typescript
67
+ ```
68
+
69
+ Two peers are required: `@softistx/janus` (the exact range is in
70
+ `peerDependencies`) and `typescript` (6 or 7). `oauth4webapi` is a dependency:
71
+ you do not install it. `@softistx/janus` is a **peer**, so one copy of it defines
72
+ `SocialError`. The package expects `"moduleResolution": "bundler"`.
73
+
74
+ ## API
75
+
76
+ One entry point, `@softistx/janus-social`. Every function answers the core's
77
+ `SocialProvider` and is called once, at wiring.
78
+
79
+ | Export | What it asks for | What the account is |
80
+ | --- | --- | --- |
81
+ | `google(options)` | `clientId`, `clientSecret`, `redirectUri`, optional `hostedDomain`, `fetch`, `timeout` | `sub`; the e-mail counts when `email_verified` is true |
82
+ | `github(options)` | `clientId`, `clientSecret`, `redirectUri`, optional `fetch`, `timeout` | the numeric user id; the e-mail is the primary address, and only when GitHub says it is verified |
83
+ | `microsoft(options)` | the same, and optional `tenant` | `sub` (pairwise per app registration); the e-mail counts when the `xms_edov` claim is `true` |
84
+ | `oidcStepUp(options)` | the credentials, the tenant's `issuer`, optional `acrValues`, `maxAge`, `pushedAuthorization`, `dpop` | `sub`; the e-mail counts when `email_verified` is true; with `acrValues` or `maxAge`, the ID token's `acr` and `auth_time` must prove them |
85
+ | `oidcProvider(options)` | the credentials, an `issuer`, optional `scopes`, `pushedAuthorization`, `dpop` | `sub`; the e-mail counts when `email_verified` is true |
86
+ | `oauth2Provider(options)` | the credentials, `authorizationEndpoint`, `tokenEndpoint`, `scopes`, `identity`, optional `clientAuthentication` | whatever your `identity` callback answers |
87
+ | `oidcConnections(options)` | the `source` (a `ConnectionSource`), `redirectUri`, optional `fetch`, `timeout`, `allowUrl` (an `AllowUrl`), `cache` (an `IssuerCacheSetting`), `clock`, `resolveHost` (a `ResolveHost`, for specs) | `{ resolve, forEmail }`: `resolve(name)` answers a provider built from the stored record (`null` when absent), for `social.resolveProvider`; `forEmail(email)` is home-realm discovery (the connection id owning the address's domain, or `null`); nothing is kept per connection. The account is `sub`; the e-mail counts per the record's `emailTrust`; the ID token's signature is always verified. The types `OidcConnection`, `ConnectionSource`, `ConnectionClient`, `ConnectionAlgorithm`, `EmailTrust`, `ClaimNames`, `OidcConnections`, `OidcConnectionsOptions`, `AllowUrl`, `ResolveHost` and `IssuerCacheSetting` are exported too |
88
+ | `checkConnection(record)` | an `OidcConnection` (`id`, `issuer`, `client`, `domains`, optional `revision`, `emailTrust`, `scopes`, `claims`, `stepUp`, `pushedAuthorization`, `dpop`) | the record, normalised. For your admin write path: it throws one `TypeError` listing every problem, never a secret; it refuses an unknown key, a malformed domain (empty or over-long label, a character outside `a-z`, `0-9` and `-`, an IP literal) and an issuer that is not written canonically (lowercase scheme and host, no empty, `.` or `..` segment) |
89
+ | `createMemoryConnections(records)`, types `ConnectionSource`, `OidcConnection`, `ConnectionClient`, `ConnectionAlgorithm`, `EmailTrust`, `ClaimNames`, `OidcConnections`, `OidcConnectionsOptions`, and the list `CONNECTION_ALGORITHMS` | the records; the read-only port (`findConnection`, `findConnectionByDomain`; `null` is absent, a throw is a failure) | a reference source for specs and examples; you implement the port over your own table |
90
+
91
+ ```ts
92
+ import type {
93
+ OidcStepUpOptions, GithubOptions, GoogleOptions, MicrosoftOptions, OAuth2Identity,
94
+ OAuth2ProviderOptions, OidcProviderOptions, ProviderCredentials, SocialFetch,
95
+ DpopAlgorithm, OidcSecurityOptions,
96
+ } from '@softistx/janus-social';
97
+
98
+ interface ProviderCredentials {
99
+ readonly clientId: string;
100
+ readonly clientSecret: string;
101
+ readonly redirectUri: string; // https, or http on localhost / 127.0.0.1 / [::1]
102
+ readonly fetch?: SocialFetch; // replaces the global fetch for every request to the provider
103
+ readonly timeout?: number; // ms each request may take, 10000 when absent
104
+ }
105
+ ```
106
+
107
+ - **Redirect URI.** It must be `https`, or `http` on a loopback host while you
108
+ develop, and it must be the callback registered with the identity provider.
109
+ - **The flow.** Authorization code with PKCE `S256`, `state` always, and a
110
+ `nonce` for OpenID Connect providers. The core mints all three; the package
111
+ puts them in the URL and checks them on the way back.
112
+ - **Scopes.** Google and Microsoft ask for `openid email profile`; GitHub for
113
+ `read:user user:email`. `oidcProvider` asks for `['openid', 'email', 'profile']`
114
+ or the `scopes` you give, and adds `openid` when it is missing. `oauth2Provider`
115
+ asks for exactly the `scopes` you give.
116
+ - **Tenant** (`microsoft`): `'common'` (the default), `'organizations'`,
117
+ `'consumers'`, a tenant id (a GUID) or a verified domain.
118
+ - **`hostedDomain`** (`google`): only accounts of that Google Workspace domain.
119
+ - **`acrValues`, `maxAge`** (`oidcStepUp`): a fixed step-up. Both are sent in the
120
+ authorization request (`acr_values` space-joined, `max_age` in seconds) and
121
+ checked on the ID token: its `acr` must be one of `acrValues`, its `auth_time`
122
+ must be a number within `maxAge` (plus or minus 60 s), else `SOCIAL_STEP_UP_UNMET`.
123
+ - **`stepUp` on one flow** (`oidcProvider`, `oidcStepUp`): `social.start({ stepUp: { acrValues, maxAge } })`
124
+ is sent as `acr_values` and `max_age` and the ID token's `acr` and `auth_time` are
125
+ reported for the core to check (`supportsStepUp: true`). With `oidcStepUp`'s fixed values
126
+ both hold. `google` and `microsoft` have `supportsStepUp: false`, `github` and
127
+ `oauth2Provider` none: a flow asking for a step-up through them is refused at `start`.
128
+ - **`pushedAuthorization`** (`oidcProvider`, `oidcStepUp`): `'auto'` (the
129
+ default) or `'always'`. `'auto'` pushes the authorization request (RFC 9126)
130
+ when the server's discovery says `require_pushed_authorization_requests: true`;
131
+ `'always'` pushes whenever it lists a `pushed_authorization_request_endpoint`.
132
+ Either fails as `PROVIDER_ERROR` when the server lists no endpoint. The visitor's
133
+ URL then carries only `client_id` and `request_uri`.
134
+ - **`dpop`** (`oidcProvider`, `oidcStepUp`): `true` (ES256) or
135
+ `{ algorithm: 'ES256' | 'EdDSA' }`, off when absent. The token request carries
136
+ a DPoP proof (RFC 9449) signed by a fresh, non-extractable key made for that
137
+ exchange; on `use_dpop_nonce` it retries once with the server's nonce.
138
+ See [servers that require PAR or DPoP](docs/guide/par-dpop.md).
139
+
140
+ ```ts
141
+ oidcProvider({ ...credentials, issuer,
142
+ dpop: true, pushedAuthorization: 'always' });
143
+ ```
144
+ - **`clientAuthentication`** (`oauth2Provider`): `'post'` (default) or `'basic'`.
145
+ `oidcProvider` takes `client_secret_post` when the provider lists it, else basic.
146
+ - **Errors.** The package defines no error class. A wiring mistake is a
147
+ `TypeError` that names the option and never its value. A failure during a
148
+ flow is the core's `SocialError` with the code `PROVIDER_ERROR` and a
149
+ `reason` for your logs: `'denied'` (the visitor refused), `'refused'` (the
150
+ provider refused or answered something unusable) or `'unreachable'`. The
151
+ message says the step and the reason, never a URL, a token or what the
152
+ provider wrote; the original failure is the `cause`.
153
+
154
+ ```ts
155
+ import { SocialError } from '@softistx/janus';
156
+
157
+ declare const logger: { warn(entry: object): void };
158
+ declare const error: unknown;
159
+
160
+ if (error instanceof SocialError && error.code === 'PROVIDER_ERROR') {
161
+ logger.warn({ provider: error.provider, reason: error.reason, cause: error.cause });
162
+ }
163
+ ```
164
+
165
+ Per-provider detail: [OIDC connections](docs/guide/oidc-connections.md), [Google](docs/guide/google.md), [GitHub](docs/guide/github.md),
166
+ [Microsoft](docs/guide/microsoft.md), [OIDC step-up](docs/guide/oidc-step-up.md), [PAR and DPoP](docs/guide/par-dpop.md), [your own provider](docs/guide/custom-providers.md).
167
+
168
+ ### OIDC connections
169
+
170
+ Identity providers your customers bring, stored in your database and read at sign-in, with no restart
171
+ ([guide](docs/guide/oidc-connections.md)):
172
+
173
+ ```ts
174
+ import { oidcConnections, type ConnectionSource } from '@softistx/janus-social';
175
+
176
+ declare const source: ConnectionSource; // yours: findConnection(id) and findConnectionByDomain(domain) over your table
177
+
178
+ const connections = oidcConnections({
179
+ source,
180
+ redirectUri: 'https://app.example.com/auth/sso/callback', // yours: one route for every connection
181
+ });
182
+
183
+ // in janus({ social: { … } }): providers looked up when a flow starts and when its callback arrives
184
+ const social = { resolveProvider: connections.resolve };
185
+
186
+ const id = await connections.forEmail('ada@acme.example'); // 'acme-corp', or null: home-realm discovery
187
+ ```
188
+
189
+ Validate every record on your admin write path with `checkConnection(record)`.
190
+
191
+ ## Traps
192
+
193
+ **Every request to the provider has a timeout, 10 seconds by default.** Past it the
194
+ request is aborted and the step fails as `PROVIDER_ERROR` with `reason: 'unreachable'`.
195
+ Set `timeout` (milliseconds) on the provider to change it. It applies to discovery,
196
+ the token request, the JWKS, GitHub's API calls and the `fetch` handed to your
197
+ `identity`, each call with its own timeout.
198
+
199
+ **`redirectUri` must match the registration byte for byte.** Scheme, host, port,
200
+ path and trailing slash: the provider answers `redirect_uri_mismatch` (or its
201
+ own words) and the flow ends in `PROVIDER_ERROR`.
202
+
203
+ **The presets do not verify the ID token's signature; OIDC connections do.** For the
204
+ presets the code goes to the token endpoint over TLS and OpenID Connect Core 3.1.3.7
205
+ lets a client trust the issuer that answered; oauth4webapi does not verify it either. `iss`, `aud`,
206
+ `exp` and `nonce` are checked. Use `fetch` only to reach the provider, never to
207
+ point at an untrusted server: there is no option to allow insecure requests.
208
+
209
+ **Microsoft: add `xms_edov` to the app registration's optional ID-token claims.**
210
+ The e-mail counts only when that claim is `true`. Without it every Microsoft
211
+ sign-in has an unverified e-mail: sign-up is refused with `EMAIL_UNVERIFIED` and
212
+ an existing user is never linked by e-mail.
213
+
214
+ **Microsoft: the account id is `sub`, pairwise per app registration.** A new
215
+ registration means new ids, so the links of the old one no longer match.
216
+
217
+ **Microsoft has no discovery.** Endpoints are fixed and the issuer is built from
218
+ the token's `tid`; a named tenant (`consumers`, `organizations`, a GUID) holds the
219
+ account to it.
220
+
221
+ **GitHub: the e-mail is the primary address and only if verified, else `null`.** A
222
+ user with none cannot sign up (`EMAIL_UNVERIFIED`). A GitHub App needs the
223
+ "Email addresses" account permission instead of scopes.
224
+
225
+ **Google: `hostedDomain` is checked on the `hd` claim.** The `hd` request
226
+ parameter is only a hint the visitor can edit.
227
+
228
+ **OIDC step-up: `acrValues` and `maxAge` are checked on the ID token.** The request
229
+ parameters are only asked for; a token with no `acr` or `auth_time` is refused
230
+ (`SOCIAL_STEP_UP_UNMET`, which replaces the `PROVIDER_ERROR` of earlier versions),
231
+ so a tenant that does not return them cannot be used with these options. "Now"
232
+ is the server's clock at the exchange, with 60 s of tolerance either way.
233
+
234
+ **Google and Entra do not honour `acr_values`.** `google()` and `microsoft()` have
235
+ `supportsStepUp: false`, so a per-request step-up through them is refused at `start`
236
+ with a `TypeError`, before any token: a provider that ignores the request would
237
+ otherwise look as if it had stepped up. Use `oidcProvider` or `oidcStepUp` for a tenant
238
+ that honours it.
239
+
240
+ **PAR is automatic only when the server requires it.** A server that merely
241
+ supports it keeps getting the URL form unless you set `pushedAuthorization:
242
+ 'always'`. Google and Microsoft take no option but push when their server requires it;
243
+ GitHub and `oauth2Provider` never push.
244
+
245
+ **DPoP binds the tokens to a key that is dropped.** The key pair lives for one
246
+ code exchange: janus-social reads the ID token and drops the tokens, so nothing
247
+ needs to persist, and there is no `dpop_jkt` at the authorization request and no
248
+ refresh. A server that insists on `dpop_jkt` at PAR cannot be used.
249
+
250
+ **`oidcProvider` reads ID-token claims only.** There is no userinfo call: the
251
+ e-mail needs the `email` scope and a true `email_verified`, or it is `null` or
252
+ unverified.
253
+
254
+ **`oauth2Provider`: your `identity` is the only voucher for the e-mail.** Answer
255
+ `emailVerified: true` only for an address the provider says the account holds;
256
+ the core links accounts by e-mail on that word.
257
+
258
+ **Discovery is read once and kept.** A failed read is not kept, the next
259
+ sign-in asks again. A changed issuer document is seen after a restart.
260
+
261
+ **OIDC connections: the ID token's signature is mandatory, with asymmetric algorithms
262
+ only.** It is checked against the issuer's published keys. `none` and the `HS*` family
263
+ cannot be written in a record and are refused at runtime (also when the metadata lists
264
+ `none`): the failure is `PROVIDER_ERROR` with reason `'refused'`. `client.idTokenSignedResponseAlg`
265
+ pins one algorithm; otherwise `RS256`, `PS256`, `ES256` and `EdDSA` are accepted.
266
+
267
+ **OIDC connections: `emailTrust: 'claim'` is opt-in and dangerous.** A tenant controls its
268
+ own `email_verified`, so with `'claim'` an administrator of any tenant can claim any
269
+ address and take over the account that holds it. The default, `'claimAndDomain'`, also
270
+ needs the address in the connection's `domains`; `'domain'` is for providers that send no
271
+ `email_verified`, such as Entra ID.
272
+
273
+ **OIDC connections: domain uniqueness is your write-side check.** `findConnectionByDomain`
274
+ answers exactly one connection; `checkConnection` cannot see your table. Refuse a write
275
+ that gives a domain to two connections, and add a domain only after the customer proved
276
+ they own it.
277
+
278
+ **OIDC connections: the URL policy.** Every URL read for a connection must be `https`, with
279
+ no credentials and a public host; loopback, private, link-local, metadata, CGNAT,
280
+ unique-local and reserved addresses, `localhost` and single-label hosts are refused. The host
281
+ is resolved before each request and every address must be public; redirects are refused,
282
+ the answer must be JSON and its size is capped. `allowUrl` can only narrow this, never
283
+ widen it. The check resolves the name and the connection resolves it again, so a DNS-rebinding
284
+ server (public to the check, private to the connection) is not stopped here: an egress firewall
285
+ or proxy that denies private ranges is the complete answer.
286
+
287
+ **OIDC connections: `id` and `issuer` never change while accounts are linked.** A link is keyed
288
+ by the provider name and `sub`; a record that points the same `id` at another issuer would
289
+ hand its accounts to that issuer. A new issuer is a new `id`.
290
+
291
+ **OIDC connections: a malformed stored record is refused, not guessed.** `resolve` throws
292
+ `PROVIDER_ERROR` with reason `'refused'` and emits one process warning per id (code
293
+ `JANUS_SOCIAL_CONNECTION_REFUSED`, naming the id and never a value) until the record
294
+ resolves again. Listen with `process.on('warning', …)`, and check records with `checkConnection` before storing them.
295
+
296
+ **OIDC connections: signing keys rotate within minutes, not at once.** The key set is kept per
297
+ issuer. A token signed with an unknown `kid` refetches it only when the kept set is 60 seconds
298
+ old or more, so a fresh rotation may fail one sign-in; a set 300 seconds old or more is never
299
+ used. A revoked key stays trusted for up to 5 minutes.
300
+
301
+ **OIDC connections: `op_policy_uri` and `op_tos_uri` are vetted too.** Discovery refuses a
302
+ document whose `_endpoint` or `_uri` members (those two included) fail the URL policy, so a
303
+ tenant cannot point your server at a private address through a metadata field.
304
+
305
+ **OIDC connections: map `email` only to a claim the identity provider controls.** The mapped
306
+ claim becomes the account's e-mail; a claim the visitor can edit at the provider (a free-text
307
+ profile field) lets them claim any address. Keep the default `email` unless you know the
308
+ provider fills the other one itself.
309
+
310
+ **OIDC connections: `picture` is any URL the provider sends**, `javascript:` included. Check
311
+ the scheme (`https:`) before putting it in an `<img src>` or a link.
312
+
313
+ **OIDC connections: no userinfo fallback in this version.** The e-mail must be in the ID token
314
+ (the `email` scope, and the claim the provider sends); a follow-up with an opt-in field is
315
+ planned ([roadmap](docs/roadmap.md)).
316
+
317
+ **OIDC connections: records are read on every resolve, metadata is cached.** The provider is
318
+ built again from the record each time, so an edit or a deletion takes effect at once. Discovery
319
+ and the signing keys stay cached by issuer for up to 1 hour.
320
+
321
+ **One social account is one link, per instance.** A link is unique per
322
+ `(provider, accountId)`: the same Google account cannot be both a customer's and an
323
+ admin's sign-in on one `janus()` instance. See the
324
+ [core guide](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/social.md)
325
+ for linking.
326
+
327
+ Each has its symptom in [troubleshooting](docs/troubleshooting.md).
328
+
329
+ ## Documentation
330
+
331
+ - [Guides](docs/README.md) — one page per provider, OIDC connections, and your own
332
+ - [Troubleshooting](docs/troubleshooting.md) — by the message you see
333
+ - [Roadmap](docs/roadmap.md) — what is next, and what is not planned
334
+ - [Social sign-in in `@softistx/janus`](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/social.md) — the flow, the cookie, the cases `complete` decides, linking
335
+
336
+ ## Type safety, counted
337
+
338
+ **Thirty-two plausible mistakes, thirty-two refused at compile time.**
339
+ `test/types/presets.ts` holds one `@ts-expect-error` per mistake, beside the
340
+ wiring that must keep compiling (each preset as a `SocialProvider` under
341
+ `social.providers`, the global `fetch` and a plain function as `fetch`): a
342
+ missing secret, a missing `redirectUri`, `oidcProvider` without an `issuer`,
343
+ `oidcStepUp` without an `issuer`, `acrValues` on a preset other than `oidcStepUp`,
344
+ `oauth2Provider` without `identity`, `hostedDomain` on `github`, `tenant` on
345
+ `google`, an `allowInsecureRequests` option, an `identity` that does not say
346
+ `emailVerified`, and, for `pushedAuthorization` and `dpop`: an unknown mode,
347
+ `dpop: false`, an algorithm other than `ES256` or `EdDSA`, and either option on
348
+ `google`, `microsoft`, `github` and `oauth2Provider` (eleven in all).
349
+ `test/types/connections.ts` adds eleven: seven for the OIDC connection record (a missing
350
+ `issuer`, the algorithms `none` and `HS256`, an unknown `emailTrust`, `domains` given as a
351
+ string, a `revision` of the wrong type, and a source answering `undefined`), and four for
352
+ `oidcConnections`: a missing `source`, a missing `redirectUri`, an e-mail given as an object
353
+ and a `forget` that no longer exists.
354
+
355
+ ## Licence
356
+
357
+ MIT
@@ -0,0 +1,21 @@
1
+ /** The URL a visitor is sent to, shared by every provider. */
2
+ import type { SocialProvider } from '@softistx/janus';
3
+ /** What the URL is made of beside the flow's three values. */
4
+ export interface AuthorizationRequest {
5
+ readonly endpoint: string;
6
+ readonly clientId: string;
7
+ readonly redirectUri: string;
8
+ readonly scopes: readonly string[];
9
+ /** Parameters a provider adds (Google's `hd`). They never override the standard ones. */
10
+ readonly extra?: Readonly<Record<string, string>>;
11
+ }
12
+ /** The flow's values, as the core derives and hands them. */
13
+ type FlowValues = Parameters<SocialProvider['authorizationUrl']>[0];
14
+ /**
15
+ * Builds the authorization URL: authorization code with PKCE `S256`, and a
16
+ * `nonce` when `withNonce` (OpenID Connect providers). Query parameters the
17
+ * endpoint already carries are kept.
18
+ */
19
+ export declare function authorizationUrl(request: AuthorizationRequest, flow: FlowValues, withNonce: boolean): Promise<URL>;
20
+ export {};
21
+ //# sourceMappingURL=authorization-url.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"authorization-url.d.ts","sourceRoot":"","sources":["../src/authorization-url.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAE9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAItD,8DAA8D;AAC9D,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,yFAAyF;IACzF,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAClD;AAED,6DAA6D;AAC7D,KAAK,UAAU,GAAG,UAAU,CAAC,cAAc,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAEpE;;;;GAIG;AACH,wBAAsB,gBAAgB,CACrC,OAAO,EAAE,oBAAoB,EAC7B,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,OAAO,GAChB,OAAO,CAAC,GAAG,CAAC,CAwBd"}
@@ -0,0 +1,22 @@
1
+ /**
2
+ * Wiring-time checks: a provider built from a bad option is a bare
3
+ * `TypeError`, naming the option and never its value (a secret is in there).
4
+ */
5
+ import type { OidcSecurityOptions, ProviderCredentials } from './options';
6
+ /** Throws unless `value` is a non-empty string. */
7
+ export declare function requireText(where: string, name: string, value: unknown): asserts value is string;
8
+ /** Throws unless `value` is an absolute `https` URL. */
9
+ export declare function requireHttps(where: string, name: string, value: unknown): URL;
10
+ /** Throws unless `redirectUri` is an `https` URL, or `http` on a loopback host. */
11
+ export declare function checkRedirectUri(where: string, redirectUri: unknown): void;
12
+ /** Throws unless `fetch` is absent or a function. */
13
+ export declare function checkFetch(where: string, fetch: unknown): void;
14
+ /** Throws unless `timeout` is absent or a positive number. */
15
+ export declare function checkTimeout(where: string, timeout: unknown): void;
16
+ /** Throws unless the credentials are text and the redirect URI, `fetch` and `timeout` are what they allow. */
17
+ export declare function checkCredentials(where: string, options: ProviderCredentials): void;
18
+ /** Throws unless `scopes` is an array of non-empty strings without spaces. */
19
+ export declare function checkScopes(where: string, scopes: unknown): string[];
20
+ /** Throws unless `pushedAuthorization` and `dpop` are what the options allow. */
21
+ export declare function checkSecurity(where: string, options: OidcSecurityOptions): void;
22
+ //# sourceMappingURL=check-options.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"check-options.d.ts","sourceRoot":"","sources":["../src/check-options.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAI1E,mDAAmD;AACnD,wBAAgB,WAAW,CAC1B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,GACZ,OAAO,CAAC,KAAK,IAAI,MAAM,CAIzB;AAED,wDAAwD;AACxD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,GAAG,CAO7E;AAED,mFAAmF;AACnF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,GAAG,IAAI,CAY1E;AAED,qDAAqD;AACrD,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAI9D;AAED,8DAA8D;AAC9D,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAOlE;AAED,8GAA8G;AAC9G,wBAAgB,gBAAgB,CAC/B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,mBAAmB,GAC1B,IAAI,CAMN;AAED,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,EAAE,CAUpE;AAUD,iFAAiF;AACjF,wBAAgB,aAAa,CAC5B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,mBAAmB,GAC1B,IAAI,CAkBN"}
@@ -0,0 +1,15 @@
1
+ /** Reading an ID token's claims into the core's `SocialIdentity`. */
2
+ import type { SocialIdentity } from '@softistx/janus';
3
+ import type { IDToken } from 'oauth4webapi';
4
+ /** A claim that is a non-empty string, or `undefined`. */
5
+ export declare function text(claims: IDToken, name: string): string | undefined;
6
+ /** Whether the provider says `true` — as a boolean, or as the string some providers send. */
7
+ export declare function isTrue(claims: IDToken, name: string): boolean;
8
+ /**
9
+ * The identity an OpenID Connect provider vouches for: `sub` is the account,
10
+ * `email` counts only with `verified` true. **A missing `email` claim is
11
+ * `email: null`, never a guess from another claim** (`preferred_username` is
12
+ * the user's to edit).
13
+ */
14
+ export declare function identityOf(claims: IDToken, verified: boolean, step: string): SocialIdentity;
15
+ //# sourceMappingURL=claims.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"claims.d.ts","sourceRoot":"","sources":["../src/claims.ts"],"names":[],"mappings":"AAAA,qEAAqE;AAErE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAG5C,0DAA0D;AAC1D,wBAAgB,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGtE;AAED,6FAA6F;AAC7F,wBAAgB,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAG7D;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CACzB,MAAM,EAAE,OAAO,EACf,QAAQ,EAAE,OAAO,EACjB,IAAI,EAAE,MAAM,GACV,cAAc,CAehB"}
@@ -0,0 +1,79 @@
1
+ /**
2
+ * The authorization-code exchange, shared by every provider: check the
3
+ * callback against the flow's `state`, redeem the code with the PKCE
4
+ * verifier, and have oauth4webapi validate the answer (and, for OpenID
5
+ * Connect, the ID token's `iss`, `aud`, `exp` and `nonce`).
6
+ *
7
+ * **For the presets the ID token's signature is not verified** — the code goes
8
+ * to the token endpoint over TLS, and OpenID Connect Core §3.1.3.7 lets a
9
+ * client trust the issuer that answered. oauth4webapi does not verify it
10
+ * either, for this flow. An upstream connection sets `idToken`
11
+ * (`connections/id-token-steps.ts`): then the signature is verified
12
+ * after oauth4webapi's checks and before any claim is trusted.
13
+ */
14
+ import * as oauth from 'oauth4webapi';
15
+ import type { DpopAlgorithm } from './options';
16
+ import type { transport } from './transport';
17
+ /** What the exchange needs to know about the client and the server. */
18
+ export interface ExchangeSetup {
19
+ readonly clientId: string;
20
+ readonly auth: oauth.ClientAuth;
21
+ readonly redirectUri: string;
22
+ readonly http: ReturnType<typeof transport>;
23
+ /** The server the callback and the code request are checked against. */
24
+ readonly server: oauth.AuthorizationServer;
25
+ /**
26
+ * The server the token response is validated against, when it is known
27
+ * only from that response (Microsoft's issuer carries the account's tenant).
28
+ */
29
+ readonly serverForTokens?: (answer: Response) => Promise<oauth.AuthorizationServer>;
30
+ /** `true` for OpenID Connect: an ID token is required and its `nonce` checked. */
31
+ readonly oidc: boolean;
32
+ /** Sends a DPoP proof with the token request, signed by a key made for this exchange. */
33
+ readonly dpop?: DpopAlgorithm;
34
+ /**
35
+ * An upstream connection's ID token handling. Absent for the presets,
36
+ * which keep the unsigned-trust above. When set, all three members are
37
+ * required, so a connection cannot skip the signature: `verifySignature`
38
+ * always runs, right after oauth4webapi processed the token response and
39
+ * before `checkIdToken` and before any claim is trusted.
40
+ */
41
+ readonly idToken?: IdTokenSteps;
42
+ }
43
+ /** The steps of a connection's ID token handling. */
44
+ export interface IdTokenSteps {
45
+ /** What oauth4webapi is told about the client beyond its id. */
46
+ readonly clientExtras: ClientExtras;
47
+ /** Verifies the signature; `answer` is the response oauth4webapi processed. */
48
+ readonly verifySignature: (answer: Response, tokens: oauth.TokenEndpointResponse) => Promise<void>;
49
+ /** Checks the claims once the signature holds. A throw refuses the exchange. */
50
+ readonly checkIdToken: (tokens: oauth.TokenEndpointResponse, claims: oauth.IDToken) => Promise<void> | void;
51
+ }
52
+ /** The client settings oauth4webapi reads from the client object. */
53
+ export interface ClientExtras {
54
+ /** The one `alg` the ID token may carry (`id_token_signed_response_alg`). */
55
+ readonly idTokenSignedResponseAlg?: string;
56
+ /** Seconds of clock skew oauth4webapi allows on `exp` and `nbf` (its default is 30). */
57
+ readonly clockTolerance?: number;
58
+ }
59
+ /** What the callback is checked against. */
60
+ export interface ExchangeFlow {
61
+ readonly callback: URLSearchParams;
62
+ readonly state: string;
63
+ readonly nonce: string;
64
+ readonly codeVerifier: string;
65
+ }
66
+ /** The validated token response, and the ID token's claims for OpenID Connect. */
67
+ export interface Redeemed {
68
+ readonly tokens: oauth.TokenEndpointResponse;
69
+ readonly claims: oauth.IDToken | undefined;
70
+ }
71
+ /** The client oauth4webapi is told about, from its id. */
72
+ export declare function clientOf(clientId: string, extras?: ClientExtras): oauth.Client;
73
+ /**
74
+ * Redeems the callback's code. Every failure leaves as `PROVIDER_ERROR`,
75
+ * except a runtime that cannot generate the DPoP key: a `TypeError` naming
76
+ * the algorithm (the core wraps it as `PROVIDER_ERROR` with it as the cause).
77
+ */
78
+ export declare function redeem(setup: ExchangeSetup, flow: ExchangeFlow): Promise<Redeemed>;
79
+ //# sourceMappingURL=code-exchange.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"code-exchange.d.ts","sourceRoot":"","sources":["../src/code-exchange.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAGtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,UAAU,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;IAC5C,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,mBAAmB,CAAC;IAC3C;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,CAC1B,MAAM,EAAE,QAAQ,KACZ,OAAO,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC;IACxC,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,yFAAyF;IACzF,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC;IAC9B;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC;CAChC;AAED,qDAAqD;AACrD,MAAM,WAAW,YAAY;IAC5B,gEAAgE;IAChE,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,+EAA+E;IAC/E,QAAQ,CAAC,eAAe,EAAE,CACzB,MAAM,EAAE,QAAQ,EAChB,MAAM,EAAE,KAAK,CAAC,qBAAqB,KAC/B,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,gFAAgF;IAChF,QAAQ,CAAC,YAAY,EAAE,CACtB,MAAM,EAAE,KAAK,CAAC,qBAAqB,EACnC,MAAM,EAAE,KAAK,CAAC,OAAO,KACjB,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC1B;AAED,qEAAqE;AACrE,MAAM,WAAW,YAAY;IAC5B,6EAA6E;IAC7E,QAAQ,CAAC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAC3C,wFAAwF;IACxF,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,4CAA4C;AAC5C,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC9B;AAED,kFAAkF;AAClF,MAAM,WAAW,QAAQ;IACxB,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,qBAAqB,CAAC;IAC7C,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,GAAG,SAAS,CAAC;CAC3C;AAED,0DAA0D;AAC1D,wBAAgB,QAAQ,CACvB,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,YAAiB,GACvB,KAAK,CAAC,MAAM,CAUd;AAiBD;;;;GAIG;AACH,wBAAsB,MAAM,CAC3B,KAAK,EAAE,aAAa,EACpB,IAAI,EAAE,YAAY,GAChB,OAAO,CAAC,QAAQ,CAAC,CA2CnB"}
@@ -0,0 +1,8 @@
1
+ /** Ends a wait when a signal stops, even if the thing waited on ignores it. */
2
+ /**
3
+ * Settles as `promise` does, or rejects with the signal's reason once it
4
+ * aborts. A value that arrives after the abort is handed to `discard`, so a
5
+ * late response's body can be cancelled instead of left open.
6
+ */
7
+ export declare function untilAborted<T>(promise: Promise<T>, signal: AbortSignal, discard?: (late: T) => void): Promise<T>;
8
+ //# sourceMappingURL=abort.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"abort.d.ts","sourceRoot":"","sources":["../../src/connections/abort.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAE/E;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC7B,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,MAAM,EAAE,WAAW,EACnB,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,GACzB,OAAO,CAAC,CAAC,CAAC,CAeZ"}
@@ -0,0 +1,24 @@
1
+ /**
2
+ * The ID token's `at_hash` (OpenID Connect Core §3.1.3.6): the left half of
3
+ * the hash of the access token's ASCII octets, base64url encoded. oauth4webapi
4
+ * does not read it (no `at_hash` in its 3.8.8 source), so it is checked here.
5
+ */
6
+ type Hash = 'SHA-256' | 'SHA-384' | 'SHA-512';
7
+ /**
8
+ * The hash a signature algorithm names: the size in its name for `RS`, `PS`
9
+ * and `ES`; SHA-512 for `EdDSA`, which is what the OpenID Foundation's EdDSA
10
+ * profile says for Ed25519. Ed448 (SHAKE256) is not supported: oauth4webapi's
11
+ * key selection only takes an `Ed25519` key for `EdDSA`, so an Ed448 token
12
+ * never verifies. `undefined` for any other algorithm.
13
+ */
14
+ export declare function atHashAlgorithm(alg: string): Hash | undefined;
15
+ /** The `at_hash` of an access token for the algorithm the ID token was signed with. */
16
+ export declare function atHashOf(alg: string, accessToken: string): Promise<string | undefined>;
17
+ /**
18
+ * Whether `claim` (the ID token's `at_hash`) is the hash of `accessToken`,
19
+ * compared in constant time. A claim that is not a string, or an algorithm
20
+ * with no hash, does not match.
21
+ */
22
+ export declare function atHashMatches(alg: string, claim: unknown, accessToken: string): Promise<boolean>;
23
+ export {};
24
+ //# sourceMappingURL=at-hash.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"at-hash.d.ts","sourceRoot":"","sources":["../../src/connections/at-hash.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,KAAK,IAAI,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAE9C;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAI7D;AAED,uFAAuF;AACvF,wBAAsB,QAAQ,CAC7B,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAW7B;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAClC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,EACd,WAAW,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC,CAOlB"}
@@ -0,0 +1,15 @@
1
+ /** What an answer may be: JSON, and no larger than a cap. */
2
+ /** Bytes an answer may hold when the caller names no other cap. */
3
+ export declare const DEFAULT_MAX_BYTES: number;
4
+ /** Bytes a key set or a userinfo answer may hold. */
5
+ export declare const LARGE_MAX_BYTES: number;
6
+ /** `application/json`, or a structured `application/*+json` (`jwk-set+json`), parameters ignored. */
7
+ export declare function isJson(contentType: string | null): boolean;
8
+ /**
9
+ * Reads the answer into memory, refusing past `max` bytes: `Content-Length`
10
+ * first, then the count of the stream, which is cancelled at the first byte
11
+ * over. Returns a new `Response` holding the buffered body, which the
12
+ * caller (oauth4webapi) reads as usual. A stopped `signal` ends the read.
13
+ */
14
+ export declare function capped(response: Response, max: number, signal: AbortSignal): Promise<Response>;
15
+ //# sourceMappingURL=body-limit.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"body-limit.d.ts","sourceRoot":"","sources":["../../src/connections/body-limit.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAK7D,mEAAmE;AACnE,eAAO,MAAM,iBAAiB,QAAY,CAAC;AAC3C,qDAAqD;AACrD,eAAO,MAAM,eAAe,QAAa,CAAC;AAE1C,qGAAqG;AACrG,wBAAgB,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAG1D;AAED;;;;;GAKG;AACH,wBAAsB,MAAM,CAC3B,QAAQ,EAAE,QAAQ,EAClB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,WAAW,GACjB,OAAO,CAAC,QAAQ,CAAC,CAuCnB"}
@@ -0,0 +1,7 @@
1
+ /** The frozen record `checkConnection` answers, built from validated fields only. */
2
+ import type { EmailTrust, OidcConnection } from './types';
3
+ export declare const CLIENT_KEYS: string[];
4
+ export declare const CLAIM_KEYS: readonly ['email', 'emailVerified', 'name', 'picture'];
5
+ /** The validated fields only, in fresh objects: the caller's input is never frozen. */
6
+ export declare function build(record: Record<string, unknown>, scopes: readonly string[], domains: readonly string[], emailTrust: EmailTrust): OidcConnection;
7
+ //# sourceMappingURL=build.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/connections/build.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAGrF,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE1D,eAAO,MAAM,WAAW,UAKvB,CAAC;AACF,eAAO,MAAM,UAAU,YACtB,OAAO,EACP,eAAe,EACf,MAAM,EACN,SAAS,CACA,CAAC;AAEX,uFAAuF;AACvF,wBAAgB,KAAK,CACpB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,UAAU,EAAE,UAAU,GACpB,cAAc,CA6BhB"}