@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.
- package/LICENSE +21 -0
- package/README.md +356 -2
- package/dist/authorization-url.d.ts +21 -0
- package/dist/authorization-url.d.ts.map +1 -0
- package/dist/check-options.d.ts +22 -0
- package/dist/check-options.d.ts.map +1 -0
- package/dist/claims.d.ts +15 -0
- package/dist/claims.d.ts.map +1 -0
- package/dist/code-exchange.d.ts +79 -0
- package/dist/code-exchange.d.ts.map +1 -0
- package/dist/connections/abort.d.ts +8 -0
- package/dist/connections/abort.d.ts.map +1 -0
- package/dist/connections/at-hash.d.ts +24 -0
- package/dist/connections/at-hash.d.ts.map +1 -0
- package/dist/connections/body-limit.d.ts +15 -0
- package/dist/connections/body-limit.d.ts.map +1 -0
- package/dist/connections/build.d.ts +7 -0
- package/dist/connections/build.d.ts.map +1 -0
- package/dist/connections/check.d.ts +25 -0
- package/dist/connections/check.d.ts.map +1 -0
- package/dist/connections/claims.d.ts +16 -0
- package/dist/connections/claims.d.ts.map +1 -0
- package/dist/connections/discovery.d.ts +20 -0
- package/dist/connections/discovery.d.ts.map +1 -0
- package/dist/connections/domain.d.ts +15 -0
- package/dist/connections/domain.d.ts.map +1 -0
- package/dist/connections/guarded-fetch.d.ts +49 -0
- package/dist/connections/guarded-fetch.d.ts.map +1 -0
- package/dist/connections/id-token-steps.d.ts +15 -0
- package/dist/connections/id-token-steps.d.ts.map +1 -0
- package/dist/connections/id-token.d.ts +63 -0
- package/dist/connections/id-token.d.ts.map +1 -0
- package/dist/connections/index.d.ts +11 -0
- package/dist/connections/index.d.ts.map +1 -0
- package/dist/connections/ip.d.ts +14 -0
- package/dist/connections/ip.d.ts.map +1 -0
- package/dist/connections/issuer-cache.d.ts +40 -0
- package/dist/connections/issuer-cache.d.ts.map +1 -0
- package/dist/connections/issuer.d.ts +4 -0
- package/dist/connections/issuer.d.ts.map +1 -0
- package/dist/connections/key-flights.d.ts +16 -0
- package/dist/connections/key-flights.d.ts.map +1 -0
- package/dist/connections/memory.d.ts +10 -0
- package/dist/connections/memory.d.ts.map +1 -0
- package/dist/connections/oidc-connections.d.ts +71 -0
- package/dist/connections/oidc-connections.d.ts.map +1 -0
- package/dist/connections/provider.d.ts +25 -0
- package/dist/connections/provider.d.ts.map +1 -0
- package/dist/connections/server.d.ts +55 -0
- package/dist/connections/server.d.ts.map +1 -0
- package/dist/connections/types.d.ts +87 -0
- package/dist/connections/types.d.ts.map +1 -0
- package/dist/connections/url-policy.d.ts +30 -0
- package/dist/connections/url-policy.d.ts.map +1 -0
- package/dist/connections/wiring.d.ts +5 -0
- package/dist/connections/wiring.d.ts.map +1 -0
- package/dist/discovery.d.ts +11 -0
- package/dist/discovery.d.ts.map +1 -0
- package/dist/dpop.d.ts +18 -0
- package/dist/dpop.d.ts.map +1 -0
- package/dist/failure.d.ts +14 -0
- package/dist/failure.d.ts.map +1 -0
- package/dist/github-identity.d.ts +11 -0
- package/dist/github-identity.d.ts.map +1 -0
- package/dist/github.d.ts +11 -0
- package/dist/github.d.ts.map +1 -0
- package/dist/google.d.ts +11 -0
- package/dist/google.d.ts.map +1 -0
- package/dist/guard-error.d.ts +14 -0
- package/dist/guard-error.d.ts.map +1 -0
- package/dist/index.d.ts +23 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +1825 -0
- package/dist/index.js.map +51 -0
- package/dist/microsoft-tenant.d.ts +32 -0
- package/dist/microsoft-tenant.d.ts.map +1 -0
- package/dist/microsoft.d.ts +16 -0
- package/dist/microsoft.d.ts.map +1 -0
- package/dist/oauth2.d.ts +13 -0
- package/dist/oauth2.d.ts.map +1 -0
- package/dist/oidc-engine.d.ts +62 -0
- package/dist/oidc-engine.d.ts.map +1 -0
- package/dist/oidc-step-up.d.ts +15 -0
- package/dist/oidc-step-up.d.ts.map +1 -0
- package/dist/oidc.d.ts +11 -0
- package/dist/oidc.d.ts.map +1 -0
- package/dist/options.d.ts +108 -0
- package/dist/options.d.ts.map +1 -0
- package/dist/pushed-authorization.d.ts +23 -0
- package/dist/pushed-authorization.d.ts.map +1 -0
- package/dist/step-up.d.ts +50 -0
- package/dist/step-up.d.ts.map +1 -0
- package/dist/transport.d.ts +18 -0
- package/dist/transport.d.ts.map +1 -0
- package/docs/README.md +35 -0
- package/docs/guide/custom-providers.md +182 -0
- package/docs/guide/github.md +109 -0
- package/docs/guide/google.md +103 -0
- package/docs/guide/microsoft.md +158 -0
- package/docs/guide/oidc-connections.md +265 -0
- package/docs/guide/oidc-step-up.md +122 -0
- package/docs/guide/par-dpop.md +63 -0
- package/docs/roadmap.md +33 -0
- package/docs/troubleshooting.md +632 -0
- 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
|
-
#
|
|
1
|
+
# @softistx/janus-social
|
|
2
2
|
|
|
3
|
-
|
|
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"}
|
package/dist/claims.d.ts
ADDED
|
@@ -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"}
|