@mpfrontend/security-bff 0.1.0 → 1.1.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/dist/core.d.ts ADDED
@@ -0,0 +1,163 @@
1
+ import { type KeyObject } from 'node:crypto';
2
+ import type { IncomingMessage, ServerResponse } from 'node:http';
3
+ import { type PreferenceCookieContract } from '@mpfrontend/i18n';
4
+ import { type SessionVault } from './session-store-core.js';
5
+ export type { VaultSecurity } from './session-store-core.js';
6
+ /**
7
+ * A route may require a recent sign-in (`maxAge`, seconds since the person authenticated) and, optionally,
8
+ * an authentication context class (`acr`, the values that count). A consumer may use maxAge alone.
9
+ */
10
+ export type AuthenticationRequirement = Readonly<{
11
+ maxAge?: number;
12
+ acr?: readonly string[];
13
+ }>;
14
+ /** The typed answer when the current sign-in is not enough; it never names the provider's origin. */
15
+ export type StepUpChallenge = Readonly<{
16
+ maxAge?: number;
17
+ acrValues?: readonly string[];
18
+ login: string;
19
+ resubmit: 'idempotent' | 'manual';
20
+ }>;
21
+ /** The response headers a streamed route may pass to the client; no other upstream header ever crosses. */
22
+ export declare const STREAM_RESPONSE_HEADERS: readonly ["content-type", "content-length", "content-disposition", "content-security-policy"];
23
+ export type StreamResponseHeader = (typeof STREAM_RESPONSE_HEADERS)[number];
24
+ /**
25
+ * A route whose bodies stream instead of being read whole as JSON. The consumer sets every value; nothing has
26
+ * a default. A request body (any method but GET) needs `requestTypes` and `maxRequestBytes`, and its
27
+ * Content-Length; the answer must have one of `responseTypes`. `responseHeaders` names the headers passed to
28
+ * the client and includes `content-type`. The timeouts and the session check interval are milliseconds.
29
+ */
30
+ export type StreamPolicy = Readonly<{
31
+ requestTypes?: readonly string[];
32
+ maxRequestBytes?: number;
33
+ responseTypes: readonly string[];
34
+ responseHeaders: readonly StreamResponseHeader[];
35
+ idleTimeoutMs: number;
36
+ totalTimeoutMs: number;
37
+ sessionCheckMs: number;
38
+ }>;
39
+ export type ApiRoute = {
40
+ method: string;
41
+ pattern: RegExp;
42
+ roles?: readonly string[];
43
+ origin: string;
44
+ prefix?: string;
45
+ authentication?: AuthenticationRequirement;
46
+ /** A streamed body (see StreamPolicy); a route without it keeps the JSON contract. Not allowed with invoke. */
47
+ stream?: StreamPolicy;
48
+ invoke?: (input: {
49
+ path: string;
50
+ headers: Readonly<Record<string, string>>;
51
+ body: Uint8Array | undefined;
52
+ }) => Promise<{
53
+ status: number;
54
+ body: unknown;
55
+ }>;
56
+ };
57
+ /** The locales the BFF may send upstream as Accept-Language; anything else becomes the default. */
58
+ export type ApiLocales = Readonly<{
59
+ supported: readonly string[];
60
+ defaultLocale: string;
61
+ }>;
62
+ /** English only, MP Frontend's one built-in language; a product lists the locales its backends answer in. */
63
+ export declare const defaultApiLocales: ApiLocales;
64
+ type CommonConfig = {
65
+ publicOrigin: string;
66
+ issuer: string;
67
+ providerOrigin?: string;
68
+ clientId: string;
69
+ audience: string;
70
+ cookieName: string;
71
+ routes: readonly ApiRoute[];
72
+ requireTenant?: boolean;
73
+ tenantExemptRoles?: readonly string[];
74
+ supportedUiLocales?: readonly string[];
75
+ uiLocaleCookie?: string;
76
+ apiLocales?: ApiLocales;
77
+ contextClaims?: readonly string[];
78
+ contextClaimSource?: 'id' | 'access';
79
+ preferenceCookie?: PreferenceCookieContract;
80
+ session?: SessionPolicy;
81
+ /** Absolute login transaction lifetime in seconds, 300 through 600. A step-up always keeps 300. */
82
+ ordinaryLoginTimeoutSeconds?: number;
83
+ /** Enables POST /backchannel-logout (OpenID Connect Back-Channel Logout 1.0); expose it only on the provider's network path. */
84
+ backChannelLogout?: boolean;
85
+ /** The acr values a step-up may request; without this list a login cannot request an acr. */
86
+ acrValues?: readonly string[];
87
+ /** The paths the browser may return to after sign-in; '/' when unset. A string matches exactly. */
88
+ returnPaths?: readonly (string | RegExp)[];
89
+ loginRateLimit?: (peer: string) => Promise<boolean>;
90
+ };
91
+ /**
92
+ * How the BFF authenticates to the token endpoint. A public client sends only its client id; the
93
+ * production profile accepts it only when the configuration declares it explicitly.
94
+ */
95
+ export type ClientAuthentication = Readonly<{
96
+ method: 'none';
97
+ publicClient: true;
98
+ }> | Readonly<{
99
+ method: 'client_secret_basic';
100
+ secret: string | (() => string);
101
+ }> | Readonly<{
102
+ method: 'private_key_jwt';
103
+ key: SigningKey | (() => SigningKey);
104
+ }>;
105
+ /**
106
+ * A private key held by the host, identified by its key id so that the identity provider can rotate keys:
107
+ * a function returns the current key at each use. The package never stores, logs or returns it.
108
+ */
109
+ export type SigningKey = Readonly<{
110
+ keyId: string;
111
+ privateKey: KeyObject;
112
+ algorithm?: 'RS256' | 'PS256' | 'ES256';
113
+ }>;
114
+ /** A client assertion lives this long (RFC 7523 recommends a short lifetime). */
115
+ export declare const CLIENT_ASSERTION_LIFETIME_SECONDS = 60;
116
+ /** A private_key_jwt client assertion (RFC 7523 section 3): iss and sub are the client, aud the token endpoint. */
117
+ export declare function clientAssertion(clientId: string, audience: string, source: SigningKey | (() => SigningKey), now?: number): string;
118
+ /** Today's single-process development profile, refused when NODE_ENV is production. */
119
+ export type DevelopmentBffConfig = CommonConfig & {
120
+ development: true;
121
+ production?: never;
122
+ sessionVault?: SessionVault;
123
+ clientAuthentication?: ClientAuthentication;
124
+ };
125
+ /** Every field is required; createBff refuses to start, with a named reason, when a condition does not hold. */
126
+ export type ProductionProfile = Readonly<{
127
+ sessionVault: SessionVault;
128
+ clientAuthentication: ClientAuthentication;
129
+ secureCookies: true;
130
+ /** The session cookie carries the __Host- prefix unless this is false. */
131
+ hostPrefix?: boolean;
132
+ }>;
133
+ export type ProductionBffConfig = CommonConfig & {
134
+ production: ProductionProfile;
135
+ development?: never;
136
+ };
137
+ export type BffConfig = DevelopmentBffConfig | ProductionBffConfig;
138
+ /** The unmet conditions of a production configuration, in a stable order; empty when it may start. */
139
+ export declare function productionRefusals(config: ProductionBffConfig): string[];
140
+ /**
141
+ * The session cookie and lifetimes. SameSite applies to the session cookie only; the short login transaction
142
+ * cookie stays Lax so that the provider's redirect back can carry it. Lifetimes have bounded maxima; a value
143
+ * above a maximum refuses startup rather than being shortened.
144
+ */
145
+ export type SessionPolicy = Readonly<{
146
+ sameSite?: 'Strict' | 'Lax';
147
+ idleTimeoutSeconds?: number;
148
+ absoluteLifetimeSeconds?: number;
149
+ /** Claims whose change at refresh rotates the session id. */
150
+ authorizationClaims?: readonly string[];
151
+ }>;
152
+ export declare const SESSION_LIMITS: Readonly<{
153
+ defaultIdleTimeoutSeconds: 1800;
154
+ maxIdleTimeoutSeconds: 86400;
155
+ defaultAbsoluteLifetimeSeconds: 28800;
156
+ maxAbsoluteLifetimeSeconds: 604800;
157
+ }>;
158
+ export declare const defaultAuthorizationClaims: readonly string[];
159
+ /** A projected claim value: plain data only, never an object, never a token. */
160
+ export type ClaimValue = string | number | boolean | readonly string[];
161
+ /** The allowlisted claims for /context, bounded in size. A token, an object or an oversized value is left out. */
162
+ export declare function projectClaims(claims: Readonly<Record<string, unknown>>, allowed: readonly string[]): Readonly<Record<string, ClaimValue>>;
163
+ export declare function createBff(config: BffConfig): (req: IncomingMessage, res: ServerResponse) => Promise<void>;