@softistx/janus-social 0.0.0-stage → 0.7.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 +10 -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 +63 -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 +1821 -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 +255 -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
@@ -0,0 +1,122 @@
1
+ # OIDC with step-up
2
+
3
+ This page is for signing in with an OpenID Connect tenant that enforces a step-up: the wiring, what identity you
4
+ get, and how to require a level of assurance or a recent authentication.
5
+
6
+ ```ts
7
+ import { oidcStepUp } from '@softistx/janus-social';
8
+
9
+ export const provider = oidcStepUp({
10
+ issuer: 'https://login.example.com', // yours: your OpenID Connect tenant's issuer
11
+ clientId: process.env.OIDC_CLIENT_ID!, // yours: from the client you registered
12
+ clientSecret: process.env.OIDC_CLIENT_SECRET!, // yours
13
+ redirectUri: 'https://app.example.com/auth/oidc/callback', // yours: the route that calls social.complete
14
+ });
15
+ ```
16
+
17
+ Put it under `social.providers` of your user type (`providers: { oidcStepUp: provider }`)
18
+ as in the [README](../../README.md). Register `redirectUri` with the tenant
19
+ byte for byte (scheme, case, trailing slash).
20
+
21
+ ## Options
22
+
23
+ | Option | Type | Default | Effect |
24
+ | --- | --- | --- | --- |
25
+ | `issuer` | `string` | required | The tenant's issuer, `https` only |
26
+ | `clientId` | `string` | required | The client's id |
27
+ | `clientSecret` | `string` | required | Its secret |
28
+ | `redirectUri` | `string` | required | `https`, or `http` on a loopback host; registered exactly |
29
+ | `acrValues` | `string[]` | absent | Non-empty. Asked for, and the ID token's `acr` must be one of them |
30
+ | `maxAge` | `number` | absent | Non-negative integer seconds. Asked for, and the ID token's `auth_time` must be no older |
31
+ | `fetch` | `SocialFetch` | global `fetch` | Used for every request to the tenant |
32
+ | `timeout` | `number` | `10000` | Milliseconds each request may take |
33
+
34
+ ```ts
35
+ interface OidcStepUpOptions extends ProviderCredentials {
36
+ readonly issuer: string;
37
+ readonly acrValues?: readonly string[];
38
+ readonly maxAge?: number;
39
+ }
40
+ ```
41
+
42
+ ## The identity
43
+
44
+ | Field | From |
45
+ | --- | --- |
46
+ | `accountId` | the ID token's `sub` |
47
+ | `email` | the `email` claim, or `null` when absent |
48
+ | `emailVerified` | `email_verified` is `true` (a boolean or the string `"true"`) |
49
+ | `name`, `picture` | the `name` and `picture` claims, when present |
50
+
51
+ The scopes asked for are `openid email profile`. The tenant is read through
52
+ OpenID Connect: its discovery document is fetched on first use and kept (a
53
+ failure is not kept). The ID token's `iss`, `aud`, `exp` and `nonce` are checked.
54
+
55
+ ## Step-up
56
+
57
+ ```ts
58
+ import { oidcStepUp } from '@softistx/janus-social';
59
+
60
+ export const strong = oidcStepUp({
61
+ issuer: 'https://login.example.com', // yours
62
+ clientId: process.env.OIDC_CLIENT_ID!,
63
+ clientSecret: process.env.OIDC_CLIENT_SECRET!,
64
+ redirectUri: 'https://app.example.com/auth/oidc/callback',
65
+ acrValues: ['urn:example:mfa'], // yours: the values your tenant defines
66
+ maxAge: 300, // the visitor authenticated within the last 5 minutes
67
+ });
68
+ ```
69
+
70
+ `acrValues` adds `acr_values=urn:example:mfa` (several values are space-joined)
71
+ and `maxAge` adds `max_age=300` to the authorization URL. Those parameters are
72
+ hints the visitor can edit, so the ID token is what is trusted. The sign-in is
73
+ refused with `SOCIAL_STEP_UP_UNMET` (403) when:
74
+
75
+ - `acrValues` is set and the token's `acr` is missing or not one of the values;
76
+ - `maxAge` is set and `auth_time` is missing, not a number, or older than
77
+ `maxAge` seconds plus 60 s before the server's clock at the exchange, or more
78
+ than 60 s in the future (the tolerance for clock skew, in both directions,
79
+ compared in milliseconds: `maxAge: 0` means roughly the last minute).
80
+
81
+ Before 0.5.0 this refusal was `PROVIDER_ERROR` with `reason: 'refused'`; code that caught that for a failed
82
+ step-up catches `SOCIAL_STEP_UP_UNMET` now.
83
+
84
+ ## One sign-in at a time
85
+
86
+ The fixed step-up above applies to every sign-in through that provider. To ask for more on **one**
87
+ sign-in (a sensitive action, a recent re-authentication), pass `stepUp` to `social.start` or
88
+ `social.link` (see the [core guide](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/social.md)):
89
+
90
+ ```ts
91
+ const start = await auth.social.start({
92
+ provider: 'oidcStepUp',
93
+ stepUp: { acrValues: ['urn:example:mfa'], maxAge: 300 }, // yours: the values your tenant defines
94
+ });
95
+ ```
96
+
97
+ `oidcStepUp` and `oidcProvider` both support it (`supportsStepUp: true`): they send the request as
98
+ `acr_values` and `max_age` (inside the pushed request too, when PAR is on), and report the ID token's
99
+ `acr` and `auth_time` so the core can check them. **The core does the checking**, on its own clock, and
100
+ answers `SOCIAL_STEP_UP_UNMET` when the proof is missing.
101
+
102
+ With `oidcStepUp`'s fixed values **both hold**: the URL sends the `acr_values` the fixed list and the
103
+ request share (in the request's order) and the smaller `max_age`. When they share no value, `start`
104
+ fails (a `PROVIDER_ERROR` with `reason: 'refused'`, never naming the values) rather than send a request
105
+ nothing could satisfy. A request weaker than the fixed values is never sent alone.
106
+
107
+ `google()` and `microsoft()` do **not** support it (`supportsStepUp: false`): neither honours
108
+ `acr_values` (Google ignores it; Microsoft answers its own `acrs` values), so `start` refuses
109
+ a step-up flow with a `TypeError` before any token. `github()` and `oauth2Provider()` do not either.
110
+
111
+ ## Traps
112
+
113
+ - The tenant must return `acr` and `auth_time` in the ID token. When it does
114
+ not, every sign-in that asks for them is refused (`SOCIAL_STEP_UP_UNMET`): drop the option, or configure the tenant.
115
+ - `acr_values` is only a request: a tenant may ignore it and sign the visitor in
116
+ anyway, which is why the ID token's `acr` is checked and a missing one is a refusal.
117
+ - An empty `acrValues`, or a `maxAge` that is negative or fractional, is a
118
+ `TypeError` at wiring; so is an `issuer` that is not `https`.
119
+ - An account is one link per instance, like any provider: see the
120
+ [core guide](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/social.md).
121
+
122
+ More in [troubleshooting](../troubleshooting.md).
@@ -0,0 +1,63 @@
1
+ # Servers that require PAR or DPoP
2
+
3
+ This page is for signing in with an OpenID Connect server that wants the authorization request pushed
4
+ (RFC 9126), or the tokens bound to a key (DPoP, RFC 9449). Both are options of `oidcProvider` and
5
+ `oidcStepUp`. Google, Microsoft, GitHub and `oauth2Provider` take no option; Google and
6
+ Microsoft still push when their discovery says the server requires it.
7
+
8
+ ```ts
9
+ import { oidcProvider } from '@softistx/janus-social';
10
+
11
+ export const provider = oidcProvider({
12
+ issuer: 'https://login.example.com', // yours
13
+ clientId: process.env.OIDC_CLIENT_ID!, // yours
14
+ clientSecret: process.env.OIDC_CLIENT_SECRET!, // yours
15
+ redirectUri: 'https://app.example.com/auth/oidc/callback', // yours
16
+ pushedAuthorization: 'auto', // the default: push when the server requires it
17
+ dpop: true, // opt in: ES256 proofs on the token request
18
+ });
19
+ ```
20
+
21
+ ## Pushed authorization requests
22
+
23
+ A server that sets `require_pushed_authorization_requests: true` in its discovery refuses an authorization
24
+ URL that carries the parameters: the sign-in fails at its page with `invalid_request`. With
25
+ `pushedAuthorization: 'auto'` (the default) the package sees that flag and pushes instead.
26
+
27
+ | Value | Pushes when | Fails with `PROVIDER_ERROR` when |
28
+ | --- | --- | --- |
29
+ | `'auto'` (default) | discovery says `require_pushed_authorization_requests: true` | it does, and discovery lists no `pushed_authorization_request_endpoint` |
30
+ | `'always'` | the server lists a `pushed_authorization_request_endpoint`, required or not | it lists none |
31
+
32
+ What is pushed: every parameter the URL carries otherwise (PKCE challenge, `state`, `nonce`, the scopes, a
33
+ step-up's `acr_values` and `max_age`), authenticated with the client secret the way the token request is
34
+ (`client_secret_post`, or basic when the server does not list post). The visitor is then sent to the
35
+ authorization endpoint (its own query, if it has one, is kept and not pushed) with only `client_id` and
36
+ the `request_uri` the server answered. A refusal, or an
37
+ answer without a `request_uri`, is a `PROVIDER_ERROR` at the step "the pushed authorization request";
38
+ the message carries no parameter and no secret.
39
+
40
+ ## DPoP
41
+
42
+ With `dpop: true` (ES256) or `dpop: { algorithm: 'EdDSA' }`, the token request carries a `DPoP` proof
43
+ (`typ: dpop+jwt`, the public key as `jwk`, `htm: POST`, `htu` the token endpoint) signed by a fresh,
44
+ non-extractable key pair made for that exchange. The tokens are used once, to read the ID token, so no
45
+ key is kept.
46
+
47
+ `EdDSA` makes an Ed25519 key, and the proof's `alg` header then reads `Ed25519`. A server whose
48
+ `dpop_signing_alg_values_supported` lists only `EdDSA` will refuse that proof; use `ES256` there. A
49
+ runtime without Ed25519 throws a `TypeError` naming the algorithm.
50
+
51
+ A server that answers a DPoP request with a Bearer token is refused, not accepted: the tokens would not be
52
+ bound to the key.
53
+
54
+ When the token endpoint answers `use_dpop_nonce`, the request is sent once more with the server's nonce. A
55
+ second refusal is a `PROVIDER_ERROR` at the step "the token response". The nonce is not kept across
56
+ sign-ins, so a server that requires a nonce costs one extra token round trip per sign-in. Without `dpop`
57
+ there is no retry.
58
+
59
+ Not covered, on purpose: `dpop_jkt` at the authorization request (the key does not exist yet), and refresh
60
+ (janus-social redeems one code per sign-in and never refreshes).
61
+
62
+ See the [troubleshooting entries](../troubleshooting.md) for the errors, and the
63
+ [roadmap](../roadmap.md) for key persistence.
@@ -0,0 +1,33 @@
1
+ # Roadmap
2
+
3
+ Where `@softistx/janus-social` is heading. A direction, not a commitment: there
4
+ are no dates here, and the version something shipped in is the only number.
5
+
6
+ ## Now
7
+
8
+ Nothing is in flight.
9
+
10
+ ## Next
11
+
12
+ - **GitHub Enterprise Server** — a base URL option on `github()`, for GitHub on your own domain.
13
+ - **A userinfo fallback** — read the account from the userinfo endpoint when the ID token carries no `email`, for providers that keep claims there: `oidcProvider`, and an opt-in field on an OIDC connection record, added when the fallback exists. The `sub` must match the ID token's.
14
+ - **Per-connection Google Workspace check (`hd`)** — a record rule that requires the `hd` claim, so a personal Google account on your domain no longer passes as verified.
15
+
16
+ ## Later
17
+
18
+ - **Apple** — Sign in with Apple: the `form_post` callback and the client secret that is a signed JWT.
19
+ - **Provider tokens** — keep and refresh the provider's access token, to call the provider's API on the user's behalf. Today the access token is used once, to read the account, and dropped. DPoP would then keep its key too, and send `dpop_jkt` at the authorization request.
20
+
21
+ ## Not planned
22
+
23
+ - **Verifying the ID token's signature for the presets' direct exchange** — the code goes to the token endpoint over TLS and OpenID Connect Core 3.1.3.7 lets the client trust that answer; oauth4webapi does not verify it either. `iss`, `aud`, `exp` and `nonce` are checked. This still holds for the presets and `oidcProvider`; **OIDC connections verify the signature**, always, with asymmetric algorithms only.
24
+ - **An option to allow insecure requests** — endpoints carry secrets; `https` only (a loopback `http` redirect URI excepted).
25
+
26
+ ## Shipped
27
+
28
+ - **The deprecated step-up alias is removed.** The old alias of `oidcStepUp()` and its options type are gone; use `oidcStepUp` and `OidcStepUpOptions`.
29
+ - **OIDC connections at runtime, v0.6.0.** `oidcConnections({ source, redirectUri })` turns identity providers stored in your database into providers for `social.resolveProvider`: add, edit or drop a tenant's OpenID Connect connection with no restart. The ID token's signature is verified; the e-mail is trusted by `emailTrust` (`'claimAndDomain'` by default) against the connection's verified `domains`; claim names are mapped per record; `forEmail` finds a company's sign-in from an e-mail address; `checkConnection` validates a record on your write path; every URL a tenant names goes through an https-only, public-address policy; discovery and signing keys are cached per issuer. `createMemoryConnections` is a reference source for specs. Needs `@softistx/janus` with `social.resolveProvider`. [#509](https://github.com/softistx/nxgt-janus/issues/509)
30
+ - **The first release, v0.1.0.** `google()`, `github()` and `microsoft()`; `oidcProvider()` for any OpenID Connect provider and `oauth2Provider()` for a plain OAuth 2.0 one; PKCE `S256`, `state` and `nonce`; Google `hostedDomain`; Microsoft tenants and the `xms_edov` e-mail rule; `PROVIDER_ERROR` with a `reason` for logs.
31
+ - **`oidcStepUp()`, v0.2.0.** A preset for an OpenID Connect tenant, by its `issuer`, with an optional fixed step-up: `acrValues` and `maxAge` are sent as `acr_values` and `max_age`, and the sign-in is refused unless the ID token's `acr` and `auth_time` prove them.
32
+ - **Pushed authorization requests and DPoP for OpenID Connect providers.** `oidcProvider()` and `oidcStepUp()` take `pushedAuthorization` (`'auto'` pushes when the server requires it, `'always'`) and `dpop` (`true` or `{ algorithm }`): the request is pushed to the server's endpoint, and the token request carries a DPoP proof with a single nonce retry. [#856](https://github.com/softistx/nxgt-janus/issues/856)
33
+ - **Step-up per request, v0.5.0.** `social.start` / `social.link` take `stepUp` (`acr_values`, `max_age`): `oidcProvider` and `oidcStepUp` send it (PAR included) and report the ID token's `acr` and `auth_time`, the core checks them; `google` and `microsoft` do not support it. `oidcStepUp`'s fixed-value refusal is now `SOCIAL_STEP_UP_UNMET`, with the core's 60 s tolerance both ways. [#643](https://github.com/softistx/nxgt-janus/issues/643)