@hyper.authio/bff 0.0.0-stage → 0.7.0

package/dist/index.d.ts

@@ -0,0 +1,327 @@
+import { RequestHandler, Request, Response } from 'express';
+import { AuthioClock, AuthioClientOptions, AuthioClient, AuthioPrompt } from '@hyper.authio/client';
+
+/**
+ * A session as the store keeps it. `data` is encrypted by the BFF (AES-256-GCM, from `cookieSecret`): the store never
+ * sees the tokens. `sessionId` and `subject` are kept in clear so back-channel logout can find the sessions to end.
+ */
+interface AuthioBffStoredSession {
+    /** The store key: `sessionKeyPrefix` followed by 64 random hex characters. The cookie carries the part after the prefix. */
+    readonly key: string;
+    /** The Authio session (`sid` of the ID token), when Authio named one. */
+    readonly sessionId: string | undefined;
+    /** The person (`sub`). */
+    readonly subject: string | undefined;
+    /** When the session expires, in milliseconds since the epoch; a store may drop it from then on. */
+    readonly expiresAt: number;
+    /** The encrypted session. */
+    readonly data: string;
+}
+/**
+ * Where the BFF keeps its sessions. The default is in memory (one process); implement this over Redis or a database for
+ * several instances, indexing each session by `sessionId` and `subject` so back-channel logout can end them.
+ * Every method may return a value or a promise.
+ */
+interface AuthioBffSessionStore {
+    /** Reads a session; `undefined` when it is unknown or expired. */
+    get(key: string): AuthioBffStoredSession | undefined | Promise<AuthioBffStoredSession | undefined>;
+    /** Creates or replaces a session, kept until `expiresAt`. */
+    set(session: AuthioBffStoredSession): void | Promise<void>;
+    /** Deletes a session. */
+    delete(key: string): void | Promise<void>;
+    /** Deletes every session of an Authio session (`sid`). */
+    deleteBySessionId(sessionId: string): void | Promise<void>;
+    /** Deletes every session of a person (`sub`). */
+    deleteBySubject(subject: string): void | Promise<void>;
+}
+/**
+ * Options of the in-memory store.
+ */
+interface AuthioBffMemoryStoreOptions {
+    /** The clock expiry is measured with. Defaults to the system clock. */
+    clock?: AuthioClock;
+}
+/**
+ * An in-memory session store, indexed by `sessionId` and `subject`, that drops expired sessions. Sessions live in one
+ * process and are lost on restart: use a shared store for several instances.
+ */
+interface AuthioBffMemoryStore extends AuthioBffSessionStore {
+    /** The number of sessions held, expired ones included until they are swept. */
+    readonly size: number;
+    get(key: string): AuthioBffStoredSession | undefined;
+    set(session: AuthioBffStoredSession): void;
+    delete(key: string): void;
+    deleteBySessionId(sessionId: string): void;
+    deleteBySubject(subject: string): void;
+}
+/**
+ * Creates the in-memory session store.
+ */
+declare function createAuthioBffMemoryStore(options?: AuthioBffMemoryStoreOptions): AuthioBffMemoryStore;
+
+/**
+ * Default names and values of the Authio BFF, the same as `Authio.AspNetCore.Bff`'s.
+ */
+declare const AuthioBffDefaults: {
+    /** The session cookie name. `__Host-` makes browsers refuse it unless it is `Secure`, has `Path=/` and no `Domain`. */
+    readonly CookieName: "__Host-authio";
+    /** The route prefix of the BFF endpoints. */
+    readonly EndpointPrefix: "/bff";
+    /** The anti-forgery header the SPA sends on every API call. */
+    readonly AntiForgeryHeaderName: "X-CSRF";
+    /** The value the anti-forgery header carries. */
+    readonly AntiForgeryHeaderValue: "1";
+    /** The redirect path Authio sends the person back to after sign-in. */
+    readonly CallbackPath: "/signin-oidc";
+    /** The redirect path Authio sends the person back to after sign-out. */
+    readonly SignedOutCallbackPath: "/signout-callback-oidc";
+    /** The `source` of the message the silent-login page posts to its parent window. */
+    readonly SilentLoginMessageSource: "authio-bff-silent-login";
+    /** The prefix of the keys sessions are stored under. */
+    readonly SessionKeyPrefix: "authio-bff:";
+    /** Seconds a session lasts without activity (8 hours). */
+    readonly SessionLifetime: number;
+    /** Seconds between two checks of the Authio session (5 minutes). */
+    readonly SessionValidationInterval: number;
+    /** Seconds a sign-in may take between the login request and the callback (15 minutes). */
+    readonly LoginLifetime: number;
+    /** The scopes asked for at sign-in; `offline_access` gives the BFF a refresh token. */
+    readonly Scopes: readonly string[];
+};
+/**
+ * How the BFF checks that the person's Authio session is still alive: `none`, or `introspection` of the session's
+ * refresh token (its access token when there is none) every `sessionValidationInterval`.
+ */
+type AuthioBffSessionValidation = "none" | "introspection";
+/**
+ * The `SameSite` mode of the session cookie.
+ */
+type AuthioBffCookieSameSite = "lax" | "strict";
+/**
+ * Settings of the Authio BFF. The client itself (`issuer` or `authority` + `realm`, `clientId`, `clientSecret`,
+ * `clientAuthentication`, `clientPrivateKey`, `clientEncryptionKey`, `tokenRefreshSkew`…) takes the names of
+ * `conformance/options.md`; the BFF's own settings are those of `Authio.AspNetCore.Bff` (`Authio:Bff`).
+ */
+interface AuthioBffOptions extends Partial<AuthioClientOptions> {
+    /**
+     * An Authio client to use instead of creating one from the connection and credential options above. The BFF still
+     * reads `tokenRefreshSkew`, `clientEncryptionKey`, `redirectUri` and `postLogoutRedirectUri` from these options.
+     */
+    client?: AuthioClient;
+    /**
+     * Secrets the session cookie is signed with and the stored sessions and sign-in cookies are encrypted with, at least
+     * 32 characters each. The first one signs and encrypts; every one is accepted, so a new secret can be put first and
+     * the old one removed once the sessions it protects have expired.
+     */
+    cookieSecret: string | readonly string[];
+    /** Where sessions live. Defaults to an in-memory store; give a shared one (Redis…) for several instances. */
+    store?: AuthioBffSessionStore;
+    /** The route prefix of the BFF endpoints. Defaults to `/bff`. */
+    endpointPrefix?: string;
+    /** The scopes asked for at sign-in. Defaults to `openid profile email offline_access`; `openid` is always sent. */
+    scopes?: readonly string[];
+    /** Adds the `roles` scope, so the session carries the `*_resource_access` claims flattened on `/bff/user`. */
+    requestRoles?: boolean;
+    /** Calls Authio's UserInfo endpoint after sign-in and adds its claims to the session. Defaults to `false`. */
+    getClaimsFromUserInfoEndpoint?: boolean;
+    /** The `organization` sent on every sign-in unless the login request names one. */
+    organization?: string;
+    /**
+     * The `resource` (RFC 8707) sent on every sign-in unless the login request names one: the session's access token is
+     * then addressed to that API. Keep `offline_access`, so the session check introspects the refresh token.
+     */
+    resource?: string;
+    /** The resources a login request may ask for with `?resource=`; any other is refused with `400`. */
+    allowedResources?: readonly string[];
+    /** The `prompt` sent on every sign-in unless the login request names one. */
+    prompt?: AuthioPrompt;
+    /** The `ui_locales` sent on every sign-in and sign-out unless the request names one. */
+    uiLocales?: string;
+    /** The `max_age` (seconds) sent on every sign-in unless the login request names one. */
+    maxAge?: number;
+    /** Extra authorize parameters sent on every sign-in. */
+    additionalAuthorizationParameters?: Readonly<Record<string, string>>;
+    /** Refuses an authorization response without `iss` (RFC 9207). Defaults to `true`; Authio always sends it. */
+    requireIssuerParameter?: boolean;
+    /** The redirect path registered at Authio for sign-in. Defaults to `/signin-oidc`. */
+    callbackPath?: string;
+    /** The post-logout redirect path registered at Authio. Defaults to `/signout-callback-oidc`. */
+    signedOutCallbackPath?: string;
+    /** Where the browser lands after login or logout without a `returnUrl`. Must be local. Defaults to `/`. */
+    defaultReturnUrl?: string;
+    /** The session cookie name. Defaults to `__Host-authio`; it must start with `__Host-` or `__Secure-`. */
+    cookieName?: string;
+    /** The session cookie's `SameSite`: `lax` (default) or `strict`. */
+    cookieSameSite?: AuthioBffCookieSameSite;
+    /** Seconds a session lasts without activity. Defaults to 28800 (8 hours). */
+    sessionLifetime?: number;
+    /** Renews `sessionLifetime` on activity once half of it has passed. Defaults to `true`. */
+    slidingExpiration?: boolean;
+    /** How the Authio session is checked. Defaults to `introspection`. */
+    sessionValidation?: AuthioBffSessionValidation;
+    /** Seconds between two checks of the Authio session. Defaults to 300. */
+    sessionValidationInterval?: number;
+    /** Revokes the refresh token at Authio on logout. Defaults to `true`. */
+    revokeRefreshTokenOnLogout?: boolean;
+    /** The anti-forgery header API calls must carry. Defaults to `X-CSRF`. */
+    antiForgeryHeaderName?: string;
+    /** The value the anti-forgery header must carry. Defaults to `1`. */
+    antiForgeryHeaderValue?: string;
+    /** The prefix of the keys sessions are stored under. Defaults to `authio-bff:`. */
+    sessionKeyPrefix?: string;
+    /**
+     * Serves `POST {endpointPrefix}/backchannel-logout`, which ends the sessions of the Authio session (`sid`) or person
+     * (`sub`) a logout token names. Defaults to `true`; register that URL as the client's back-channel logout URI.
+     */
+    backChannelLogout?: boolean;
+    /** Called with errors the BFF recovers from: a failed revocation, introspection or refresh, a refused logout token. */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Whether a URL is local to the application: it starts with a single `/` (not `//` nor `/\`) and holds no control
+ * characters, so redirecting to it cannot leave the site.
+ */
+declare function isLocalUrl(url: string | undefined | null): url is string;
+
+/**
+ * Which token a remote API call is forwarded with, as `AuthioBffRemoteApiTokenMode` in .NET:
+ *
+ * - `user`: the person's access token (refreshed when needed); anonymous calls are refused with `401`.
+ * - `userOrNone`: the person's token when signed in, otherwise no token.
+ * - `clientCredentials`: a client-credentials token of the BFF itself, whoever is signed in.
+ * - `userOrClientCredentials`: the person's token when signed in, otherwise a client-credentials token.
+ * - `none`: no token (cookies and the anti-forgery header are still stripped).
+ */
+type AuthioBffRemoteApiTokenMode = "user" | "userOrNone" | "clientCredentials" | "userOrClientCredentials" | "none";
+/**
+ * Settings of one remote API.
+ */
+interface AuthioBffRemoteApiOptions {
+    /** Which token the calls are forwarded with. Defaults to `user`. */
+    tokenMode?: AuthioBffRemoteApiTokenMode;
+    /**
+     * The resource (RFC 8707) the token must be issued for: a user token is exchanged for it (cached per session and
+     * resource), a client-credentials token is asked for it.
+     */
+    resource?: string;
+    /** The scopes the token must carry; for a user token, setting them triggers a token exchange (down-scoping). */
+    scopes?: readonly string[];
+    /** Requires the anti-forgery header on every call. Defaults to `true`; turn it off only for an anonymous API. */
+    requireAntiForgery?: boolean;
+    /** When the remote API answers `401` to a user call, checks the Authio session and ends the BFF session if it is gone. Defaults to `true`. */
+    validateSessionOnUnauthorized?: boolean;
+    /** The `fetch` the calls go through. Defaults to the global one. */
+    fetch?: typeof fetch;
+}
+
+/**
+ * The signed-in session as the application sees it: who, which Authio session, until when. Never the tokens.
+ */
+interface AuthioBffSessionInfo {
+    /** The person (`sub`). */
+    readonly subject: string | undefined;
+    /** The Authio session (`sid`). */
+    readonly sessionId: string | undefined;
+    /** The session's claims: the ID token's, the access token's `*_resource_access` and organization, UserInfo's. */
+    readonly claims: Readonly<Record<string, unknown>>;
+    /** When the BFF session expires, in milliseconds since the epoch. */
+    readonly expiresAt: number;
+}
+declare global {
+    namespace Express {
+        interface Request {
+            /** The Authio BFF session, once the BFF read it for this request; `undefined` when nobody is signed in. */
+            authioBff?: AuthioBffSessionInfo;
+        }
+    }
+}
+/**
+ * Options of `bff.api()`.
+ */
+interface AuthioBffApiOptions {
+    /** Requires the anti-forgery header. Defaults to `true`. */
+    requireAntiForgery?: boolean;
+    /** Lets anonymous calls through (with `req.authioBff` undefined) instead of answering `401`. Defaults to `false`. */
+    optional?: boolean;
+}
+/**
+ * What a user token is asked for: a resource (RFC 8707) and/or narrower scopes make the BFF exchange the session's
+ * token (RFC 8693) and cache the result per session, resource and scopes.
+ */
+interface AuthioBffUserTokenOptions {
+    /** The resource the token must be issued for. */
+    resource?: string;
+    /** The scopes the token must carry. */
+    scopes?: readonly string[];
+}
+/**
+ * The Authio BFF: an Express middleware serving the BFF endpoints, plus the helpers the application's own routes use.
+ */
+interface AuthioBff extends RequestHandler {
+    /** The Authio client the BFF talks to Authio with. */
+    readonly client: AuthioClient;
+    /** Where the sessions live. */
+    readonly store: AuthioBffSessionStore;
+    /**
+     * Marks a local API: requires the anti-forgery header (`401 antiforgery_required`) and a session (`401
+     * unauthorized`), never redirects, and sets `req.authioBff`.
+     */
+    api(options?: AuthioBffApiOptions): RequestHandler;
+    /**
+     * Forwards the calls mounted under a path to a remote API with the token `tokenMode` asks for:
+     * `app.use("/api/orders", bff.remoteApi("https://orders.example.com"))`. Mount it before any body parser.
+     */
+    remoteApi(destination: string, options?: AuthioBffRemoteApiOptions): RequestHandler;
+    /** Reads the request's session (once per request), checking and renewing it as configured. */
+    getSession(request: Request, response: Response): Promise<AuthioBffSessionInfo | undefined>;
+    /**
+     * The person's access token, refreshed `tokenRefreshSkew` before it expires (one refresh per session at a time), or
+     * exchanged for `resource`/`scopes`. `undefined` when nobody is signed in or the session ended (a refused refresh
+     * ends it).
+     */
+    getUserAccessToken(request: Request, response: Response, options?: AuthioBffUserTokenOptions): Promise<string | undefined>;
+    /** A `fetch` that sends the person's access token (see `getUserAccessToken`), for calling APIs from a route. */
+    userFetch(request: Request, response: Response, options?: AuthioBffUserTokenOptions & {
+        fetch?: typeof fetch;
+    }): typeof fetch;
+    /** Ends the request's session locally: deletes it from the store and clears the cookie. Authio is not told. */
+    endSession(request: Request, response: Response): Promise<void>;
+}
+/**
+ * Creates the Authio BFF. Mount it with `app.use(bff)`: it serves `{endpointPrefix}/login`, `/logout`, `/user`,
+ * `/silent-login`, `/silent-login-callback`, `/backchannel-logout`, the sign-in callback (`callbackPath`) and the
+ * sign-out callback (`signedOutCallbackPath`), and reads the session of every other request that carries the cookie.
+ *
+ * @throws AuthioConfigurationError naming every invalid option.
+ */
+declare function authioBff(options: AuthioBffOptions): AuthioBff;
+
+/**
+ * The claim types `/bff/user` adds to the person's claims.
+ */
+declare const AuthioBffClaimTypes: {
+    /** Seconds until the BFF session expires. */
+    readonly SessionExpiresIn: "bff:session_expires_in";
+    /** The URL the SPA navigates to in order to log out; it carries the session's `sid`. */
+    readonly LogoutUrl: "bff:logout_url";
+    /** One Authio role the person holds (flattened from the `*_resource_access` claims). */
+    readonly Role: "role";
+    /** One permission the person holds, as `{resource}:{method}` (flattened from the `*_resource_access` claims). */
+    readonly Permission: "permission";
+};
+/**
+ * One entry of the `/bff/user` answer: a string value, or a number for `bff:session_expires_in`.
+ */
+interface AuthioBffClaim {
+    readonly type: string;
+    readonly value: string | number;
+}
+/**
+ * The JSON body of a BFF refusal, shaped like an OAuth error.
+ */
+interface AuthioBffError {
+    readonly error: string;
+    readonly error_description?: string;
+}
+
+export { type AuthioBff, type AuthioBffApiOptions, type AuthioBffClaim, AuthioBffClaimTypes, type AuthioBffCookieSameSite, AuthioBffDefaults, type AuthioBffError, type AuthioBffMemoryStore, type AuthioBffMemoryStoreOptions, type AuthioBffOptions, type AuthioBffRemoteApiOptions, type AuthioBffRemoteApiTokenMode, type AuthioBffSessionInfo, type AuthioBffSessionStore, type AuthioBffSessionValidation, type AuthioBffStoredSession, type AuthioBffUserTokenOptions, authioBff, createAuthioBffMemoryStore, isLocalUrl };