@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
@@ -0,0 +1,62 @@
1
+ /**
2
+ * What `oidcProvider`, Google and Microsoft share: an OpenID Connect
3
+ * `SocialProvider` that differs from the next only in where its server comes
4
+ * from and how its claims read.
5
+ */
6
+ import type { SocialIdentity, SocialProvider } from '@softistx/janus';
7
+ import type * as oauth from 'oauth4webapi';
8
+ import { type IdTokenSteps } from './code-exchange';
9
+ import type { OidcSecurityOptions, ProviderCredentials } from './options';
10
+ import { type FixedStepUp } from './step-up';
11
+ import { transport } from './transport';
12
+ /**
13
+ * What one exchange or authorization URL runs against: the server, the
14
+ * transport to reach it and, for an upstream connection, the ID token steps.
15
+ */
16
+ export interface EngineSession {
17
+ readonly server: oauth.AuthorizationServer;
18
+ readonly http: ReturnType<typeof transport>;
19
+ /** Set for a connection: the signature check is then mandatory. Absent for the presets. */
20
+ readonly idToken?: IdTokenSteps;
21
+ }
22
+ /** The server a preset reaches (read lazily) or the session a connection runs in, never both. */
23
+ export type EngineServer = {
24
+ /** The server, read lazily: discovery, or a fixed description. */
25
+ readonly server: () => Promise<oauth.AuthorizationServer>;
26
+ readonly session?: never;
27
+ } | {
28
+ /**
29
+ * Looks up the whole session at once, so the server, its transport
30
+ * and the signature check come from the same lookup.
31
+ */
32
+ readonly session: () => Promise<EngineSession>;
33
+ readonly server?: never;
34
+ };
35
+ /** One OpenID Connect provider, as its preset describes it. */
36
+ export type OidcEngine = EngineServer & EngineBase;
37
+ interface EngineBase {
38
+ readonly credentials: ProviderCredentials;
39
+ /** `pushedAuthorization` and `dpop`, as the application gave them. */
40
+ readonly security?: OidcSecurityOptions;
41
+ readonly scopes: readonly string[];
42
+ /** How the secret reaches the token endpoint; by default the method the server lists. */
43
+ readonly authentication?: 'post' | 'basic';
44
+ /** Parameters the authorization URL carries beside the standard ones. */
45
+ readonly authorizationParams?: Readonly<Record<string, string>>;
46
+ /** For a server whose issuer is known only from the token response. */
47
+ readonly serverForTokens?: (server: oauth.AuthorizationServer, answer: Response) => Promise<oauth.AuthorizationServer>;
48
+ /** Step-up values every sign-in must meet (`oidcStepUp`); sent with each request and held by `identity`. */
49
+ readonly fixedStepUp?: FixedStepUp;
50
+ /**
51
+ * Whether a flow's `stepUp` request is sent and the ID token's `acr` and
52
+ * `auth_time` are reported on the identity: the provider's
53
+ * `supportsStepUp`. `false` for a server that ignores `acr_values`.
54
+ */
55
+ readonly perRequestStepUp: boolean;
56
+ /** The account the validated ID token's claims describe. */
57
+ readonly identity: (claims: oauth.IDToken) => SocialIdentity;
58
+ }
59
+ /** Builds the `SocialProvider` of an OpenID Connect engine. */
60
+ export declare function createOidcProvider(engine: OidcEngine): SocialProvider;
61
+ export {};
62
+ //# sourceMappingURL=oidc-engine.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"oidc-engine.d.ts","sourceRoot":"","sources":["../src/oidc-engine.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtE,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAE3C,OAAO,EAAE,KAAK,YAAY,EAAU,MAAM,iBAAiB,CAAC;AAG5D,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAE1E,OAAO,EAEN,KAAK,WAAW,EAGhB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAc,SAAS,EAAE,MAAM,aAAa,CAAC;AAEpD;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,mBAAmB,CAAC;IAC3C,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;IAC5C,2FAA2F;IAC3F,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC;CAChC;AAED,iGAAiG;AACjG,MAAM,MAAM,YAAY,GACrB;IACA,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC;IAC1D,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC;CACxB,GACD;IACA;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,CAAC;IAC/C,QAAQ,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC;CACvB,CAAC;AAEL,+DAA+D;AAC/D,MAAM,MAAM,UAAU,GAAG,YAAY,GAAG,UAAU,CAAC;AAEnD,UAAU,UAAU;IACnB,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAC;IAC1C,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,yFAAyF;IACzF,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3C,yEAAyE;IACzE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAChE,uEAAuE;IACvE,QAAQ,CAAC,eAAe,CAAC,EAAE,CAC1B,MAAM,EAAE,KAAK,CAAC,mBAAmB,EACjC,MAAM,EAAE,QAAQ,KACZ,OAAO,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC;IACxC,4GAA4G;IAC5G,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,KAAK,cAAc,CAAC;CAC7D;AASD,+DAA+D;AAC/D,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,UAAU,GAAG,cAAc,CA2ErE"}
@@ -0,0 +1,15 @@
1
+ /** `oidcStepUp`: an OpenID Connect tenant that enforces a step-up. */
2
+ import { type SocialProvider } from '@softistx/janus';
3
+ import type { OidcStepUpOptions } from './options';
4
+ /**
5
+ * Sign-in, by the tenant's issuer. The e-mail counts when the ID
6
+ * token's `email_verified` is true. With `acrValues` and `maxAge`, the
7
+ * authorization request asks for them and the sign-in is refused unless the
8
+ * ID token's `acr` and `auth_time` prove them: the request parameters are
9
+ * hints the visitor can edit, so the claims are what is trusted; an unproven
10
+ * step-up is `SOCIAL_STEP_UP_UNMET`. "Now" is `Date.now()` at the exchange.
11
+ * A flow's own `stepUp` request is held too, on top of these fixed values
12
+ * (the `acr_values` both list, the smaller `max_age`).
13
+ */
14
+ export declare function oidcStepUp(options: OidcStepUpOptions): SocialProvider;
15
+ //# sourceMappingURL=oidc-step-up.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"oidc-step-up.d.ts","sourceRoot":"","sources":["../src/oidc-step-up.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,OAAO,EAAe,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAKnE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAInD;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,cAAc,CA+BrE"}
package/dist/oidc.d.ts ADDED
@@ -0,0 +1,11 @@
1
+ /** `oidcProvider`: any OpenID Connect provider, by its issuer. */
2
+ import type { SocialProvider } from '@softistx/janus';
3
+ import type { OidcProviderOptions } from './options';
4
+ /**
5
+ * An OpenID Connect provider, found through
6
+ * `<issuer>/.well-known/openid-configuration` on first use. The authorization
7
+ * code flow with PKCE; the ID token's `iss`, `aud`, `exp` and `nonce` are
8
+ * checked, and `email_verified` decides whether its e-mail counts.
9
+ */
10
+ export declare function oidcProvider(options: OidcProviderOptions): SocialProvider;
11
+ //# sourceMappingURL=oidc.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"oidc.d.ts","sourceRoot":"","sources":["../src/oidc.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAElE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAUtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAKrD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,cAAc,CAezE"}
@@ -0,0 +1,108 @@
1
+ /** The options of every provider this package builds. */
2
+ import type { SocialIdentity } from '@softistx/janus';
3
+ /**
4
+ * The `fetch` a provider calls the identity provider with: the global one
5
+ * when absent. Typed narrower than `typeof fetch` so a plain function fits.
6
+ */
7
+ export type SocialFetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
8
+ /** What every provider needs to be a client of the identity provider. */
9
+ export interface ProviderCredentials {
10
+ /** The client id the identity provider issued for this application. */
11
+ readonly clientId: string;
12
+ /** The client secret that goes with it. Never logged, never put in an error. */
13
+ readonly clientSecret: string;
14
+ /**
15
+ * The callback URL registered with the identity provider. **It must be
16
+ * exactly the one registered there**, scheme, host, port and path. `https`,
17
+ * or `http` on a loopback host while developing.
18
+ */
19
+ readonly redirectUri: string;
20
+ /** Replaces the global `fetch` for every request to the identity provider. */
21
+ readonly fetch?: SocialFetch;
22
+ /**
23
+ * Milliseconds each request to the identity provider may take, its body
24
+ * included. `10000` when absent. A request past it fails as a
25
+ * `PROVIDER_ERROR` with the reason `'unreachable'`.
26
+ */
27
+ readonly timeout?: number;
28
+ }
29
+ /** The algorithms a DPoP key may use. */
30
+ export type DpopAlgorithm = 'ES256' | 'EdDSA';
31
+ /** What the OpenID Connect presets add for servers with stricter rules (RFC 9126, RFC 9449). */
32
+ export interface OidcSecurityOptions {
33
+ /**
34
+ * Pushed authorization requests (RFC 9126). `'auto'` (the default) pushes
35
+ * when the server's discovery says `require_pushed_authorization_requests`.
36
+ * `'always'` pushes whenever the server lists a
37
+ * `pushed_authorization_request_endpoint`, and fails with `PROVIDER_ERROR`
38
+ * when it lists none. The URL then carries only `client_id` and `request_uri`.
39
+ */
40
+ readonly pushedAuthorization?: 'auto' | 'always';
41
+ /**
42
+ * Sender-constrain the tokens with DPoP (RFC 9449): the token request carries
43
+ * a proof signed by a fresh, non-extractable key pair made for that exchange.
44
+ * `true` means `ES256`. Off when absent.
45
+ */
46
+ readonly dpop?: true | {
47
+ readonly algorithm: DpopAlgorithm;
48
+ };
49
+ }
50
+ /** An OpenID Connect provider found through its discovery document. */
51
+ export interface OidcProviderOptions extends ProviderCredentials, OidcSecurityOptions {
52
+ /** The issuer URL (`https`), whose `/.well-known/openid-configuration` is read on first use. */
53
+ readonly issuer: string;
54
+ /** Scopes to ask for; `openid` is always added. `['openid', 'email', 'profile']` when absent. */
55
+ readonly scopes?: readonly string[];
56
+ }
57
+ /** What a plain OAuth 2.0 provider tells the core about the account. */
58
+ export type OAuth2Identity = SocialIdentity;
59
+ /** A plain OAuth 2.0 provider: no ID token, so you say how to read the account. */
60
+ export interface OAuth2ProviderOptions extends ProviderCredentials {
61
+ /** The provider's authorization endpoint (`https`). */
62
+ readonly authorizationEndpoint: string;
63
+ /** The provider's token endpoint (`https`). */
64
+ readonly tokenEndpoint: string;
65
+ /** Scopes to ask for. */
66
+ readonly scopes: readonly string[];
67
+ /** How the client secret is sent to the token endpoint. `'post'` when absent. */
68
+ readonly clientAuthentication?: 'post' | 'basic';
69
+ /**
70
+ * Reads the account with the access token. It is given the `fetch` to use
71
+ * (yours, when you passed one). Throw to refuse; anything but a `SocialError`
72
+ * becomes a `PROVIDER_ERROR`.
73
+ */
74
+ readonly identity: (accessToken: string, fetch: SocialFetch) => Promise<OAuth2Identity>;
75
+ }
76
+ /** Google, through OpenID Connect. */
77
+ export interface GoogleOptions extends ProviderCredentials {
78
+ /** Only accounts of this Google Workspace domain. Checked on the ID token's `hd`, not only asked for. */
79
+ readonly hostedDomain?: string;
80
+ }
81
+ /** GitHub, through OAuth 2.0. */
82
+ export type GithubOptions = ProviderCredentials;
83
+ /** Microsoft identity platform (Entra ID and personal accounts), through OpenID Connect. */
84
+ export interface MicrosoftOptions extends ProviderCredentials {
85
+ /**
86
+ * Whose accounts may sign in: `'common'` (any, the default), `'organizations'`,
87
+ * `'consumers'`, a tenant id (a GUID) or a verified domain.
88
+ */
89
+ readonly tenant?: string;
90
+ }
91
+ /** An OpenID Connect tenant that can require a step-up (`acr`, `max_age`). */
92
+ export interface OidcStepUpOptions extends ProviderCredentials, OidcSecurityOptions {
93
+ /** The tenant's issuer URL (`https`), whose `/.well-known/openid-configuration` is read on first use. */
94
+ readonly issuer: string;
95
+ /**
96
+ * Authentication context class references to ask for (`acr_values`, space
97
+ * joined). Non-empty. The sign-in is refused unless the ID token's `acr` is
98
+ * one of them.
99
+ */
100
+ readonly acrValues?: readonly string[];
101
+ /**
102
+ * Seconds since the visitor last authenticated (`max_age`), a non-negative
103
+ * integer. The sign-in is refused unless the ID token's `auth_time` is a
104
+ * number no older than that.
105
+ */
106
+ readonly maxAge?: number;
107
+ }
108
+ //# sourceMappingURL=options.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AAAA,yDAAyD;AAEzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,CACzB,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,EAC7B,IAAI,CAAC,EAAE,WAAW,KACd,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEvB,yEAAyE;AACzE,MAAM,WAAW,mBAAmB;IACnC,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gFAAgF;IAChF,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,yCAAyC;AACzC,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,OAAO,CAAC;AAE9C,gGAAgG;AAChG,MAAM,WAAW,mBAAmB;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IACjD;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG;QAAE,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAA;KAAE,CAAC;CAC7D;AAED,uEAAuE;AACvE,MAAM,WAAW,mBAChB,SAAQ,mBAAmB,EAC1B,mBAAmB;IACpB,gGAAgG;IAChG,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iGAAiG;IACjG,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,wEAAwE;AACxE,MAAM,MAAM,cAAc,GAAG,cAAc,CAAC;AAE5C,mFAAmF;AACnF,MAAM,WAAW,qBAAsB,SAAQ,mBAAmB;IACjE,uDAAuD;IACvD,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,+CAA+C;IAC/C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,yBAAyB;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,iFAAiF;IACjF,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACjD;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAClB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,WAAW,KACd,OAAO,CAAC,cAAc,CAAC,CAAC;CAC7B;AAED,sCAAsC;AACtC,MAAM,WAAW,aAAc,SAAQ,mBAAmB;IACzD,yGAAyG;IACzG,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,iCAAiC;AACjC,MAAM,MAAM,aAAa,GAAG,mBAAmB,CAAC;AAEhD,4FAA4F;AAC5F,MAAM,WAAW,gBAAiB,SAAQ,mBAAmB;IAC5D;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,8EAA8E;AAC9E,MAAM,WAAW,iBAChB,SAAQ,mBAAmB,EAC1B,mBAAmB;IACpB,yGAAyG;IACzG,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACzB"}
@@ -0,0 +1,23 @@
1
+ /**
2
+ * Pushed authorization requests (RFC 9126): the parameters go to the server's
3
+ * endpoint, authenticated like the token request, and the visitor is sent
4
+ * with only `client_id` and the `request_uri` it answered.
5
+ */
6
+ import * as oauth from 'oauth4webapi';
7
+ import type { transport } from './transport';
8
+ /** Whether this authorization request is pushed, or throws when it must be and cannot. */
9
+ export declare function shouldPush(server: oauth.AuthorizationServer, mode: 'auto' | 'always'): boolean;
10
+ /** What a push needs beside the parameters. */
11
+ export interface PushSetup {
12
+ readonly server: oauth.AuthorizationServer;
13
+ readonly clientId: string;
14
+ readonly auth: oauth.ClientAuth;
15
+ readonly http: ReturnType<typeof transport>;
16
+ }
17
+ /**
18
+ * Pushes `url`'s query and returns the URL the visitor is sent to. Every
19
+ * failure leaves as `PROVIDER_ERROR` at the step "the pushed authorization
20
+ * request", never carrying a parameter.
21
+ */
22
+ export declare function push(setup: PushSetup, url: URL, endpoint: string): Promise<URL>;
23
+ //# sourceMappingURL=pushed-authorization.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"pushed-authorization.d.ts","sourceRoot":"","sources":["../src/pushed-authorization.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAGtC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAI7C,0FAA0F;AAC1F,wBAAgB,UAAU,CACzB,MAAM,EAAE,KAAK,CAAC,mBAAmB,EACjC,IAAI,EAAE,MAAM,GAAG,QAAQ,GACrB,OAAO,CAMT;AAED,+CAA+C;AAC/C,MAAM,WAAW,SAAS;IACzB,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,mBAAmB,CAAC;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,UAAU,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;CAC5C;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CACnB,KAAK,EAAE,SAAS,EAChB,GAAG,EAAE,GAAG,EACR,QAAQ,EAAE,MAAM,GACd,OAAO,CAAC,GAAG,CAAC,CA4Bd"}
@@ -0,0 +1,50 @@
1
+ /**
2
+ * The step-up of an OpenID Connect preset: the fixed values `oidcStepUp()`
3
+ * holds the ID token to, the request one flow adds, and the evidence the ID
4
+ * token gives.
5
+ */
6
+ import type { SocialStepUpRequest } from '@softistx/janus';
7
+ import type { IDToken } from 'oauth4webapi';
8
+ /** A fixed step-up: what a preset is configured to require on every sign-in. */
9
+ export interface FixedStepUp {
10
+ readonly acrValues?: readonly string[];
11
+ readonly maxAge?: number;
12
+ }
13
+ /** Throws unless `acrValues` is a non-empty array of tokens with no spaces, and `maxAge` a non-negative integer. */
14
+ export declare function checkStepUp(where: string, acrValues: unknown, maxAge: unknown): void;
15
+ /** The `acr_values` and `max_age` request parameters. */
16
+ export declare function stepUpParams({ acrValues, maxAge, }: {
17
+ readonly acrValues?: readonly string[] | undefined;
18
+ readonly maxAge?: number | undefined;
19
+ }): Record<string, string>;
20
+ /**
21
+ * The step-up a request effectively asks for: **both the preset's fixed values
22
+ * and the flow's request must hold**, so the URL sends the `acr_values` they
23
+ * share and the smaller `max_age`. Throws a `TypeError` when the two share no
24
+ * `acr_values`, since no sign-in could satisfy both.
25
+ */
26
+ export declare function combineStepUp(fixed: FixedStepUp, request: SocialStepUpRequest | null): {
27
+ acrValues: readonly string[] | undefined;
28
+ maxAge: number | undefined;
29
+ };
30
+ /**
31
+ * The evidence an ID token gives the core: its `acr` (a non-empty string of at
32
+ * most 256 characters) and `auth_time` (a finite number of seconds). A claim
33
+ * that is missing or malformed is left out, and the core refuses the flow
34
+ * that needed it.
35
+ */
36
+ export declare function stepUpClaims(claims: IDToken): {
37
+ acr?: string;
38
+ authTime?: Date;
39
+ };
40
+ /**
41
+ * Whether the ID token proves the step-up: its `acr` is one of `acrValues`,
42
+ * and its `auth_time` lies within `[now - maxAge - 60 s, now + 60 s]`
43
+ * (`now` in epoch milliseconds), so `maxAge: 0` means roughly the last minute.
44
+ * A missing claim fails; a request parameter alone proves nothing, since the
45
+ * visitor can edit the URL. **The same rule as `proveStepUp` in
46
+ * `@softistx/janus`** (AGENTS.md, "Deliberate duplications"): change one,
47
+ * change both.
48
+ */
49
+ export declare function holdsStepUp(claims: IDToken, acrValues: readonly string[] | undefined, maxAge: number | undefined, now: number): boolean;
50
+ //# sourceMappingURL=step-up.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"step-up.d.ts","sourceRoot":"","sources":["../src/step-up.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAQ5C,gFAAgF;AAChF,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,oHAAoH;AACpH,wBAAgB,WAAW,CAC1B,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,OAAO,EAClB,MAAM,EAAE,OAAO,GACb,IAAI,CAmBN;AAED,yDAAyD;AACzD,wBAAgB,YAAY,CAAC,EAC5B,SAAS,EACT,MAAM,GACN,EAAE;IACF,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACnD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAKzB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC5B,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,mBAAmB,GAAG,IAAI,GACjC;IAAE,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAkB1E;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG;IAC9C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,IAAI,CAAC;CAChB,CAeA;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAC1B,MAAM,EAAE,OAAO,EACf,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EACxC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,GAAG,EAAE,MAAM,GACT,OAAO,CAeT"}
@@ -0,0 +1,18 @@
1
+ /** How requests leave: the `fetch` in use, and the client authentication. */
2
+ import * as oauth from 'oauth4webapi';
3
+ import type { SocialFetch } from './options';
4
+ /** Milliseconds a request to the identity provider may take when `timeout` is absent. */
5
+ export declare const DEFAULT_TIMEOUT = 10000;
6
+ /** The request options that route oauth4webapi through `fetch`, when it is not the global one. */
7
+ export declare function transport(fetchWith: SocialFetch | undefined, timeout: number | undefined): {
8
+ signal: () => AbortSignal;
9
+ [oauth.customFetch]?: (url: string, options: object) => Promise<Response>;
10
+ };
11
+ /**
12
+ * The `fetch` the provider hands to code of the application's (the identity
13
+ * callback). Each call gets its own timeout, unless the caller passes a `signal`.
14
+ */
15
+ export declare function fetcher(fetchWith: SocialFetch | undefined, timeout: number | undefined): SocialFetch;
16
+ /** The client authentication for a secret, by the method the provider takes. */
17
+ export declare function clientAuth(secret: string, method: 'post' | 'basic'): oauth.ClientAuth;
18
+ //# sourceMappingURL=transport.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAE7E,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,yFAAyF;AACzF,eAAO,MAAM,eAAe,QAAS,CAAC;AAEtC,kGAAkG;AAClG,wBAAgB,SAAS,CACxB,SAAS,EAAE,WAAW,GAAG,SAAS,EAClC,OAAO,EAAE,MAAM,GAAG,SAAS,GACzB;IACF,MAAM,EAAE,MAAM,WAAW,CAAC;IAC1B,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC1E,CAQA;AAED;;;GAGG;AACH,wBAAgB,OAAO,CACtB,SAAS,EAAE,WAAW,GAAG,SAAS,EAClC,OAAO,EAAE,MAAM,GAAG,SAAS,GACzB,WAAW,CAOb;AAED,gFAAgF;AAChF,wBAAgB,UAAU,CACzB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GAAG,OAAO,GACtB,KAAK,CAAC,UAAU,CAIlB"}
package/docs/README.md ADDED
@@ -0,0 +1,35 @@
1
+ # @softistx/janus-social — documentation
2
+
3
+ The [README](../README.md) shows the wiring of the four presets and the two
4
+ core calls; these pages give the detail, one per provider and one for connections stored at runtime.
5
+
6
+ | Page | Read it when |
7
+ | --- | --- |
8
+ | [Google](guide/google.md) | You register an OAuth client in Google Cloud, restrict sign-in to a Workspace domain, or wonder which Google claim counts as a verified e-mail |
9
+ | [GitHub](guide/github.md) | You register an OAuth app or a GitHub App, and need to know which e-mail GitHub gives you and when it gives none |
10
+ | [Microsoft](guide/microsoft.md) | You register an app in Microsoft Entra: work, school or personal accounts, the tenant to choose, and the `xms_edov` claim that makes the e-mail count |
11
+ | [OIDC step-up](guide/oidc-step-up.md) | You sign in with an OpenID Connect tenant, and want to require a level of assurance (`acr`) or a recent authentication (`max_age`) |
12
+ | [PAR and DPoP](guide/par-dpop.md) | Your OpenID Connect server requires pushed authorization requests (`invalid_request` at the authorize page) or wants DPoP-bound tokens |
13
+ | [OIDC connections](guide/oidc-connections.md) | Your customers bring their own OpenID Connect identity provider (Entra ID, Okta, Google Workspace) and you store the connections in your database: wiring, the record, e-mail trust, home-realm discovery |
14
+ | [Your own provider](guide/custom-providers.md) | You sign in with another OpenID Connect provider (`oidcProvider`), a plain OAuth 2.0 one (`oauth2Provider`), or write a `SocialProvider` by hand |
15
+ | [Troubleshooting](troubleshooting.md) | You paste an error message into a search box: a wiring `TypeError`, a `PROVIDER_ERROR` step, `redirect_uri_mismatch`, `EMAIL_UNVERIFIED` after a Microsoft sign-up |
16
+ | [Roadmap](roadmap.md) | You want to know what is coming and what is not planned |
17
+
18
+ The flow itself (`start`, `complete`, the flow cookie, linking, the cases a
19
+ callback decides) is in
20
+ [Social sign-in](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/social.md)
21
+ of `@softistx/janus`.
22
+
23
+ ## Words
24
+
25
+ The words of [`@softistx/janus`'s vocabulary](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/vocabulary.md)
26
+ keep their meaning. This package adds:
27
+
28
+ | Word | Means | Not |
29
+ | --- | --- | --- |
30
+ | **provider** | A `SocialProvider`: the object under `social.providers` with `authorizationUrl` and `exchange`. Also the identity provider it talks to, where the sentence says so | "strategy", "connector" |
31
+ | **preset** | `google()`, `github()`, `microsoft()` or `oidcStepUp()`: a provider with its endpoints and rules already known | "adapter" |
32
+ | **app registration** | What you create in the identity provider's console to get a client id and a secret | "app" alone, "project" |
33
+ | **OIDC connection** | One tenant's identity provider as your application stores it (`OidcConnection`), read through a `ConnectionSource` and answered by `oidcConnections` as a provider named by its `id`. Not a database connection | "tenant provider", "SSO config" |
34
+ | **redirect URI** | The callback URL of your application, registered with the identity provider and given as `redirectUri`. They must be the same string | "callback URL" for the registration field only |
35
+ | **account id** | The provider's stable id for an account (`accountId`): `sub`, or GitHub's numeric id. The key of a link, never the e-mail | "user id" (that is yours) |
@@ -0,0 +1,182 @@
1
+ # Your own provider
2
+
3
+ This page is for signing in with an identity provider the presets do not cover:
4
+ `oidcProvider` for anything that speaks OpenID Connect, `oauth2Provider` for a
5
+ plain OAuth 2.0 provider, and a hand-written `SocialProvider` for the rest.
6
+
7
+ ## OpenID Connect: `oidcProvider`
8
+
9
+ ```ts
10
+ import { oidcProvider } from '@softistx/janus-social';
11
+
12
+ export const provider = oidcProvider({
13
+ issuer: 'https://id.example.com', // yours: the provider's issuer URL
14
+ clientId: process.env.OIDC_CLIENT_ID!, // yours
15
+ clientSecret: process.env.OIDC_CLIENT_SECRET!, // yours
16
+ redirectUri: 'https://app.example.com/auth/sso/callback', // yours: registered with the provider
17
+ });
18
+ ```
19
+
20
+ | Option | Type | Default | Effect |
21
+ | --- | --- | --- | --- |
22
+ | `issuer` | `string` | required | An `https` URL; `<issuer>/.well-known/openid-configuration` is read on first use and kept (a failure is not kept) |
23
+ | `clientId`, `clientSecret`, `redirectUri` | `string` | required | The app registration; the redirect URI is `https`, or `http` on a loopback host |
24
+ | `scopes` | `readonly string[]` | `['openid', 'email', 'profile']` | Scopes to ask for; `openid` is always added; none may hold a space |
25
+ | `fetch` | `SocialFetch` | global `fetch` | Used for discovery and every other request |
26
+ | `timeout` | `number` | `10000` | Milliseconds each request may take; past it the step fails as `unreachable` |
27
+
28
+ ```ts
29
+ interface OidcProviderOptions extends ProviderCredentials {
30
+ readonly issuer: string;
31
+ readonly scopes?: readonly string[];
32
+ }
33
+ ```
34
+
35
+ The identity comes from the ID token alone: `accountId` is `sub`, `email` is the
36
+ `email` claim, and `emailVerified` is `email_verified` being `true` (or `"true"`).
37
+ There is no userinfo call, so the provider must put `email` and `email_verified`
38
+ in the ID token (ask for the `email` scope). The token's `iss`, `aud`, `exp` and
39
+ `nonce` are checked; its signature is not, for the direct TLS exchange. The secret
40
+ is sent in the body when the provider lists `client_secret_post`, else as HTTP
41
+ Basic.
42
+
43
+ A flow's `stepUp` request (`acr_values`, `max_age`) is sent by `oidcProvider` and
44
+ `oidcStepUp` and not by the other presets: see [OIDC step-up](oidc-step-up.md#one-sign-in-at-a-time).
45
+
46
+ ## Plain OAuth 2.0: `oauth2Provider`
47
+
48
+ ```ts
49
+ import { oauth2Provider } from '@softistx/janus-social';
50
+
51
+ export const provider = oauth2Provider({
52
+ authorizationEndpoint: 'https://id.example.com/oauth/authorize', // yours
53
+ tokenEndpoint: 'https://id.example.com/oauth/token', // yours
54
+ clientId: process.env.SSO_CLIENT_ID!,
55
+ clientSecret: process.env.SSO_CLIENT_SECRET!,
56
+ redirectUri: 'https://app.example.com/auth/sso/callback',
57
+ scopes: ['profile', 'email'], // yours: exactly what is asked for
58
+ identity: async (accessToken, fetch) => {
59
+ const answer = await fetch('https://id.example.com/api/me', {
60
+ headers: { authorization: `Bearer ${accessToken}` },
61
+ });
62
+ if (!answer.ok) throw new Error('the profile request failed');
63
+ const me = (await answer.json()) as { id: number; email?: string; email_confirmed?: boolean };
64
+ return {
65
+ accountId: String(me.id),
66
+ email: me.email ?? null,
67
+ emailVerified: me.email !== undefined && me.email_confirmed === true,
68
+ };
69
+ },
70
+ });
71
+ ```
72
+
73
+ | Option | Type | Default | Effect |
74
+ | --- | --- | --- | --- |
75
+ | `authorizationEndpoint`, `tokenEndpoint` | `string` | required | `https` URLs |
76
+ | `scopes` | `readonly string[]` | required | Asked for exactly as given, no spaces inside one |
77
+ | `identity` | `(accessToken, fetch) => Promise<OAuth2Identity>` | required | Reads the account with the access token |
78
+ | `clientAuthentication` | `'post' \| 'basic'` | `'post'` | How the secret reaches the token endpoint |
79
+ | `clientId`, `clientSecret`, `redirectUri`, `fetch` | | | As above |
80
+
81
+ ```ts
82
+ // The same shape as the core's SocialIdentity: OAuth2Identity is an alias of it
83
+ interface OAuth2Identity {
84
+ readonly accountId: string;
85
+ readonly email: string | null;
86
+ readonly emailVerified: boolean;
87
+ readonly name?: string;
88
+ readonly picture?: string;
89
+ }
90
+ ```
91
+
92
+ - **`identity` is the only voucher for the e-mail.** Answer `emailVerified: true`
93
+ only for an address the provider itself says the account holds. The core links
94
+ accounts by e-mail on that word.
95
+ - **`accountId` is the provider's stable id**, not a login or an e-mail, which can
96
+ change.
97
+ - **Use the `fetch` you are given**, not the global one: it is yours when you
98
+ passed `fetch` to the provider, so a test stub reaches it.
99
+ - **Throw to refuse.** A `SocialError` passes through; anything else becomes
100
+ `PROVIDER_ERROR` at "the account request" (`unreachable` for a network error,
101
+ else `refused`).
102
+ - PKCE `S256` and `state` are used; there is no `nonce`, since there is no ID token.
103
+
104
+ ## Neither: a `SocialProvider` by hand
105
+
106
+ For a provider that needs a signed JWT as its client secret, a form post, or
107
+ anything else, write the two calls the core asks for. The contract (what the
108
+ provider must check, how `emailVerified` is honest) is in the
109
+ [core guide](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/social.md#writing-a-provider).
110
+ Throw a `SocialError('PROVIDER_ERROR', ...)` with a `reason` to be logged the
111
+ way this package's providers are.
112
+
113
+ ```ts
114
+ import { SocialError, type SocialProvider } from '@softistx/janus';
115
+
116
+ export const provider: SocialProvider = {
117
+ async authorizationUrl({ state }) {
118
+ const url = new URL('https://id.example.com/authorize');
119
+ url.searchParams.set('state', state);
120
+ // ...client_id, redirect_uri, scope, code_challenge from codeVerifier, nonce
121
+ return url;
122
+ },
123
+ async exchange({ callback, state }) {
124
+ if (callback.get('state') !== state) {
125
+ throw new SocialError('PROVIDER_ERROR', 'the authorization response: refused', { reason: 'refused' });
126
+ }
127
+ // ...trade callback.get('code') with codeVerifier, read the account
128
+ return { accountId: 'abc', email: null, emailVerified: false };
129
+ },
130
+ };
131
+ ```
132
+
133
+ ### Supporting a step-up
134
+
135
+ A provider by hand opts in with `supportsStepUp: true`. It then gets `flow.stepUp`
136
+ (`{ acrValues: string[] | null, maxAge: number | null }`, or `null`) on both calls, sends it to the
137
+ authorization server, and reports `acr` and `authTime` (a `Date`) on the identity it answers; the core
138
+ refuses a flow whose identity does not prove the request. Without the flag, a flow asking for a step-up is
139
+ refused at `start`: set it only when the server honours `acr_values`.
140
+
141
+ ```ts
142
+ export const provider: SocialProvider = {
143
+ supportsStepUp: true,
144
+ async authorizationUrl({ state, stepUp }) {
145
+ const url = new URL('https://id.example.com/authorize');
146
+ url.searchParams.set('state', state);
147
+ if (stepUp?.acrValues) url.searchParams.set('acr_values', stepUp.acrValues.join(' '));
148
+ if (stepUp?.maxAge !== null && stepUp?.maxAge !== undefined) url.searchParams.set('max_age', String(stepUp.maxAge));
149
+ return url;
150
+ },
151
+ async exchange() {
152
+ return { accountId: 'abc', email: null, emailVerified: false, acr: 'urn:example:mfa', authTime: new Date() };
153
+ },
154
+ };
155
+ ```
156
+
157
+ ## Testing
158
+
159
+ Pass `fetch` to the provider and answer the provider's endpoints from a stub; no
160
+ network is needed, and nothing else reaches the identity provider. A fake
161
+ `SocialProvider` for the whole flow is in the core guide.
162
+
163
+ ```ts
164
+ import { oauth2Provider } from '@softistx/janus-social';
165
+
166
+ const calls: string[] = [];
167
+ export const provider = oauth2Provider({
168
+ authorizationEndpoint: 'https://id.example.com/authorize',
169
+ tokenEndpoint: 'https://id.example.com/token',
170
+ clientId: 'client',
171
+ clientSecret: 'secret',
172
+ redirectUri: 'http://localhost:3000/callback',
173
+ scopes: ['profile'],
174
+ fetch: async (input) => {
175
+ calls.push(String(input));
176
+ return Response.json({ access_token: 'token', token_type: 'bearer' });
177
+ },
178
+ identity: async () => ({ accountId: '1', email: null, emailVerified: false }),
179
+ });
180
+ ```
181
+
182
+ More in [troubleshooting](../troubleshooting.md).