@oneuptime/common 14.0.13 → 14.0.14

package/Types/OnCallDutyPolicy/UserOverrideCoverRequest.ts

@@ -0,0 +1,148 @@
+import OneUptimeDate from "../Date";
+import Dictionary from "../Dictionary";
+
+/*
+ * "GET COVER" OPENS ADD USER OVERRIDE WITH THE SHIFT FILLED IN.
+ *
+ * An upcoming shift's "Get cover" link (User Settings > Calendar Feed)
+ * opens the User Overrides page with Add User Override already open: you as
+ * the person away, and the shift's window as when - so the one thing left to
+ * answer is who covers. The window travels as two query parameters on the
+ * page's address, written here by the link and read back here by the page.
+ *
+ * A shift that has already started is covered from now: the pages that
+ * matter are the ones still to come. A window that has ended, or whose end
+ * is not after its start, asks for nothing.
+ *
+ * Pure: the calendar feed card, the User Overrides table, the Add User
+ * Override form and their tests share it.
+ */
+
+export const USER_OVERRIDE_COVER_STARTS_AT_PARAM: string = "coverStartsAt";
+export const USER_OVERRIDE_COVER_ENDS_AT_PARAM: string = "coverEndsAt";
+
+export interface UserOverrideCoverWindow {
+  startsAt: Date;
+  endsAt: Date;
+}
+
+/*
+ * A time as a form, a link or a shift holds it - a Date, or the ISO string
+ * a date input writes - or null when it is not a real instant yet: empty,
+ * half typed, or not a time at all. The one reader of override times, so
+ * the link, the page and the form's own checks agree on what a time is.
+ */
+export const toUserOverrideTime: (value: unknown) => Date | null = (
+  value: unknown,
+): Date | null => {
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime()) ? null : value;
+  }
+
+  if (typeof value !== "string" || !value.trim()) {
+    return null;
+  }
+
+  // Half-typed text is not a time yet (and would only make moment warn).
+  if (Number.isNaN(Date.parse(value))) {
+    return null;
+  }
+
+  let date: Date;
+
+  try {
+    date = OneUptimeDate.fromString(value);
+  } catch {
+    return null;
+  }
+
+  return Number.isNaN(date.getTime()) ? null : date;
+};
+
+/*
+ * The window to cover for a shift from `start` to `end`, as of `now`: from
+ * the start, or from now once it has started, to the end. Null when either
+ * time is not a real one, when the end is not after the start, or when the
+ * shift has ended.
+ */
+export const getUserOverrideCoverWindow: (data: {
+  start: unknown;
+  end: unknown;
+  now: Date;
+}) => UserOverrideCoverWindow | null = (data: {
+  start: unknown;
+  end: unknown;
+  now: Date;
+}): UserOverrideCoverWindow | null => {
+  const start: Date | null = toUserOverrideTime(data.start);
+  const end: Date | null = toUserOverrideTime(data.end);
+
+  if (!start || !end) {
+    return null;
+  }
+
+  if (end.getTime() <= start.getTime()) {
+    return null;
+  }
+
+  if (end.getTime() <= data.now.getTime()) {
+    return null;
+  }
+
+  return {
+    startsAt: start.getTime() < data.now.getTime() ? new Date(data.now) : start,
+    endsAt: end,
+  };
+};
+
+// The query parameters that ask the User Overrides page to cover a window.
+export const getUserOverrideCoverQueryParams: (
+  window: UserOverrideCoverWindow,
+) => Dictionary<string> = (
+  window: UserOverrideCoverWindow,
+): Dictionary<string> => {
+  return {
+    [USER_OVERRIDE_COVER_STARTS_AT_PARAM]: encodeURIComponent(
+      OneUptimeDate.toString(window.startsAt),
+    ),
+    [USER_OVERRIDE_COVER_ENDS_AT_PARAM]: encodeURIComponent(
+      OneUptimeDate.toString(window.endsAt),
+    ),
+  };
+};
+
+/*
+ * The window a page's address asks to cover, read with `getParam` (one
+ * query parameter's value by name, or null) as of `now`: a link opened an
+ * hour after it was made covers from then. Null when the address asks for
+ * nothing usable, and the page then opens as it always does.
+ */
+export const readUserOverrideCoverRequest: (data: {
+  getParam: (name: string) => string | null | undefined;
+  now: Date;
+}) => UserOverrideCoverWindow | null = (data: {
+  getParam: (name: string) => string | null | undefined;
+  now: Date;
+}): UserOverrideCoverWindow | null => {
+  return getUserOverrideCoverWindow({
+    start: data.getParam(USER_OVERRIDE_COVER_STARTS_AT_PARAM),
+    end: data.getParam(USER_OVERRIDE_COVER_ENDS_AT_PARAM),
+    now: data.now,
+  });
+};
+
+// Whether a page's address carries any part of a cover request.
+export const hasUserOverrideCoverParams: (
+  getParam: (name: string) => string | null | undefined,
+) => boolean = (
+  getParam: (name: string) => string | null | undefined,
+): boolean => {
+  return [
+    USER_OVERRIDE_COVER_STARTS_AT_PARAM,
+    USER_OVERRIDE_COVER_ENDS_AT_PARAM,
+  ].some((name: string): boolean => {
+    const value: string | null | undefined = getParam(name);
+
+    return value !== null && value !== undefined;
+  });
+};

package/Types/SSO/OidcProviderDefaults.ts

@@ -0,0 +1,282 @@
+import URL from "../API/URL";
+import {
+  SsoProviderDescriptionFields,
+  fillSsoProviderDescription,
+  isBlankSsoValue,
+} from "./SsoProviderDefaults";
+
+/*
+ * WHAT AN OPENID CONNECT PROVIDER IS GIVEN, AND WHAT IS WORKED OUT FROM IT.
+ *
+ * Adding an OIDC provider - for a project, a status page or the whole
+ * instance - asked for eleven things over four steps. Only three come from
+ * the identity provider and differ from one setup to the next: the issuer,
+ * the client ID and the client secret. The rest has an answer:
+ *
+ *   - the discovery URL is the issuer followed by
+ *     /.well-known/openid-configuration (OpenID Connect Discovery 1.0,
+ *     section 4: any trailing "/" of the issuer is dropped first), so it is
+ *     worked out from the issuer;
+ *   - the scopes, and the claims that hold the email address and the name,
+ *     are "openid email profile", "email" and "name" for nearly every
+ *     provider;
+ *   - the description is "Sign in with <name>" (SsoProviderDefaults).
+ *
+ * The services (ProjectOidcService, StatusPageOidcService,
+ * GlobalOidcService) fill these in when a provider is created without them,
+ * before the required-field check runs, so the columns stay required and
+ * the API and Terraform keep their contract while a caller may leave them
+ * out. The forms show the same values, so what a form shows is what is
+ * saved. A provider that already exists keeps what it has.
+ *
+ * Nothing here fetches anything: the discovery document is read when
+ * someone signs in, as before, through the OIDC egress guard.
+ *
+ * React-free and server-safe: the API, the Dashboard, the Admin Dashboard
+ * and their tests all read it.
+ */
+
+export const OIDC_DISCOVERY_PATH: string = "/.well-known/openid-configuration";
+
+export const DEFAULT_OIDC_SCOPES: string = "openid email profile";
+
+export const DEFAULT_OIDC_EMAIL_CLAIM_NAME: string = "email";
+
+export const DEFAULT_OIDC_NAME_CLAIM_NAME: string = "name";
+
+// The scope every OpenID Connect sign-in has to ask for.
+export const REQUIRED_OIDC_SCOPE: string = "openid";
+
+/*
+ * An issuer is an https URL (OpenID Connect Core 1.0, section 1.2); an
+ * identity provider on the installation's own network may be plain http.
+ */
+const ISSUER_SCHEME: RegExp = /^https?:\/\/\S+/i;
+
+/*
+ * A discovery URL: something, then /.well-known/openid-configuration, then
+ * at most a "/" and a query. Some providers need the query (Azure AD B2C
+ * names its sign-in policy in ?p=), so it is kept; a fragment never reaches
+ * a server and is dropped.
+ */
+const DISCOVERY_URL: RegExp =
+  /^(.+?)\/\.well-known\/openid-configuration\/?(\?[^#]*)?(#.*)?$/i;
+
+export interface OidcIssuerParts {
+  issuerURL: string;
+  discoveryURL: string;
+}
+
+/**
+ * When a value is a discovery URL rather than an issuer (it ends in
+ * /.well-known/openid-configuration, perhaps with a query), the issuer in
+ * front of it and the URL itself. Null for anything else, an issuer
+ * included.
+ */
+export const splitOidcDiscoveryUrl: (
+  value: string | null | undefined,
+) => OidcIssuerParts | null = (
+  value: string | null | undefined,
+): OidcIssuerParts | null => {
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  const match: RegExpMatchArray | null = value.trim().match(DISCOVERY_URL);
+  const issuerURL: string = match?.[1] || "";
+
+  if (!match || !issuerURL.replace(/\/+$/, "")) {
+    return null;
+  }
+
+  return {
+    issuerURL,
+    discoveryURL: `${issuerURL.replace(/\/+$/, "")}${OIDC_DISCOVERY_PATH}${match[2] || ""}`,
+  };
+};
+
+/**
+ * The issuer a value names: the value itself, trimmed - or, for a discovery
+ * URL pasted where the issuer goes, the issuer in front of it.
+ */
+export const getOidcIssuerFromValue: (
+  value: string | null | undefined,
+) => string = (value: string | null | undefined): string => {
+  const split: OidcIssuerParts | null = splitOidcDiscoveryUrl(value);
+
+  if (split) {
+    return split.issuerURL;
+  }
+
+  return typeof value === "string" ? value.trim() : "";
+};
+
+/**
+ * The discovery URL of an issuer: the issuer without a trailing "/", then
+ * /.well-known/openid-configuration. Empty for a blank issuer; a discovery
+ * URL given as the issuer is its own.
+ */
+export const getOidcDiscoveryUrl: (
+  issuer: string | null | undefined,
+) => string = (issuer: string | null | undefined): string => {
+  const split: OidcIssuerParts | null = splitOidcDiscoveryUrl(issuer);
+
+  if (split) {
+    return split.discoveryURL;
+  }
+
+  const trimmed: string = typeof issuer === "string" ? issuer.trim() : "";
+
+  if (!trimmed) {
+    return "";
+  }
+
+  return trimmed.replace(/\/+$/, "") + OIDC_DISCOVERY_PATH;
+};
+
+/**
+ * Whether a discovery URL is the one the issuer gives (or none at all): it
+ * then follows the issuer when the issuer changes. One set by hand, for a
+ * provider that publishes its discovery document somewhere else, stays.
+ */
+export const isDefaultOidcDiscoveryUrl: (data: {
+  discoveryURL: URL | string | null | undefined;
+  issuerURL: string | null | undefined;
+}) => boolean = (data: {
+  discoveryURL: URL | string | null | undefined;
+  issuerURL: string | null | undefined;
+}): boolean => {
+  if (isBlankSsoValue(data.discoveryURL)) {
+    return true;
+  }
+
+  const derived: string = getOidcDiscoveryUrl(data.issuerURL);
+
+  return (
+    Boolean(derived) &&
+    normalizeUrlText(String(data.discoveryURL)) === normalizeUrlText(derived)
+  );
+};
+
+/*
+ * The URL type writes a URL back the way it parsed it, which may differ from
+ * how it was typed in ways that do not matter here: the case of the scheme
+ * and of the host, and a trailing "/".
+ */
+const normalizeUrlText: (value: string) => string = (value: string): string => {
+  const trimmed: string = value.trim().replace(/\/+$/, "");
+  const match: RegExpMatchArray | null = trimmed.match(
+    /^([a-z][a-z0-9+.-]*:\/\/)([^/?#]*)(.*)$/i,
+  );
+
+  if (!match) {
+    return trimmed;
+  }
+
+  return `${(match[1] || "").toLowerCase()}${(match[2] || "").toLowerCase()}${match[3] || ""}`;
+};
+
+// Whether an issuer is written as an http(s) URL.
+export const isOidcIssuerUrl: (value: string | null | undefined) => boolean = (
+  value: string | null | undefined,
+): boolean => {
+  return typeof value === "string" && ISSUER_SCHEME.test(value.trim());
+};
+
+// The scopes, one by one.
+export const getOidcScopeList: (
+  scopes: string | null | undefined,
+) => Array<string> = (scopes: string | null | undefined): Array<string> => {
+  if (typeof scopes !== "string") {
+    return [];
+  }
+
+  return scopes.split(/\s+/).filter((scope: string): boolean => {
+    return scope.length > 0;
+  });
+};
+
+// Whether the scopes ask for openid, which every OIDC sign-in needs.
+export const includesRequiredOidcScope: (
+  scopes: string | null | undefined,
+) => boolean = (scopes: string | null | undefined): boolean => {
+  return getOidcScopeList(scopes).includes(REQUIRED_OIDC_SCOPE);
+};
+
+/*
+ * A provider about to be created: the columns every OIDC provider has that
+ * are filled in here. ProjectOIDC, StatusPageOIDC and GlobalOIDC all fit it.
+ */
+export interface OidcProviderDefaultFields
+  extends SsoProviderDescriptionFields {
+  issuerURL?: string | undefined;
+  discoveryURL?: URL | undefined;
+  scopes?: string | undefined;
+  emailClaimName?: string | undefined;
+  nameClaimName?: string | undefined;
+}
+
+/**
+ * What a provider created without them gets, in place:
+ *
+ *   - an issuer given as a discovery URL becomes the issuer in front of it
+ *     (and the URL its discovery URL, unless one was given);
+ *   - a missing discovery URL is worked out from the issuer;
+ *   - missing scopes and claim names are the usual ones;
+ *   - a missing description is "Sign in with <name>".
+ *
+ * Whatever the caller sent is kept. A value that cannot be worked out (no
+ * issuer, or one that is not a URL) is left missing, so the required-field
+ * check names it.
+ */
+export const fillOidcProviderDefaults: (
+  provider: OidcProviderDefaultFields,
+) => void = (provider: OidcProviderDefaultFields): void => {
+  if (typeof provider.issuerURL === "string") {
+    const split: OidcIssuerParts | null = splitOidcDiscoveryUrl(
+      provider.issuerURL,
+    );
+
+    provider.issuerURL = split ? split.issuerURL : provider.issuerURL.trim();
+
+    if (split && isBlankSsoValue(provider.discoveryURL)) {
+      provider.discoveryURL = toUrl(split.discoveryURL);
+    }
+  }
+
+  if (
+    isBlankSsoValue(provider.discoveryURL) &&
+    isOidcIssuerUrl(provider.issuerURL)
+  ) {
+    provider.discoveryURL = toUrl(getOidcDiscoveryUrl(provider.issuerURL));
+  }
+
+  if (isBlankSsoValue(provider.scopes)) {
+    provider.scopes = DEFAULT_OIDC_SCOPES;
+  }
+
+  if (isBlankSsoValue(provider.emailClaimName)) {
+    provider.emailClaimName = DEFAULT_OIDC_EMAIL_CLAIM_NAME;
+  }
+
+  if (isBlankSsoValue(provider.nameClaimName)) {
+    provider.nameClaimName = DEFAULT_OIDC_NAME_CLAIM_NAME;
+  }
+
+  fillSsoProviderDescription(provider);
+};
+
+// A URL the column can hold, or nothing when the text does not parse.
+const toUrl: (value: string) => URL | undefined = (
+  value: string,
+): URL | undefined => {
+  if (!value) {
+    return undefined;
+  }
+
+  try {
+    return URL.fromString(value);
+  } catch {
+    return undefined;
+  }
+};

package/Types/SSO/SamlProviderDefaults.ts

@@ -0,0 +1,77 @@
+import DigestMethod from "./DigestMethod";
+import SignatureMethod from "./SignatureMethod";
+import {
+  SsoProviderDescriptionFields,
+  fillSsoProviderDescription,
+  isBlankSsoValue,
+} from "./SsoProviderDefaults";
+
+/*
+ * WHAT A SAML PROVIDER IS GIVEN, AND WHAT IS FILLED IN.
+ *
+ * Adding a SAML provider - for a project, a status page or the whole
+ * instance - walked four steps and asked for a description and for two
+ * required dropdowns that started empty, the signature and digest methods,
+ * whose help said "If you do not know what this is, please leave this to
+ * RSA-SHA256" (and "SHA256"). What only the identity provider can give is
+ * its sign-on URL, its issuer and its certificate. The rest has an answer:
+ *
+ *   - the signature method is RSA-SHA256 and the digest method SHA256, what
+ *     nearly every identity provider uses. They are recorded with the
+ *     provider and shown on its page; signing in verifies a response against
+ *     the provider's certificate with the algorithm the signed response names
+ *     (App/FeatureSet/Identity/Utils/SSO), so these two are not something a
+ *     newcomer has to get right;
+ *   - the description is "Sign in with <name>" (SsoProviderDefaults).
+ *
+ * The services (ProjectSsoService, StatusPageSsoService, GlobalSsoService)
+ * fill these in when a provider is created without them, before the
+ * required-field check runs, so the columns stay required and the API and
+ * Terraform keep their contract while a caller may leave them out. The forms
+ * start on the same values (Common/UI/Components/Sso/SamlProviderFormFields),
+ * so what a form shows is what is saved. A provider that already exists keeps
+ * what it has.
+ *
+ * React-free and server-safe: the API, the Dashboard, the Admin Dashboard
+ * and their tests all read it.
+ */
+
+export const DEFAULT_SAML_SIGNATURE_METHOD: SignatureMethod =
+  SignatureMethod.SHA256;
+
+export const DEFAULT_SAML_DIGEST_METHOD: DigestMethod = DigestMethod.SHA256;
+
+/*
+ * A provider about to be created: the columns every SAML provider has that
+ * are filled in here. ProjectSSO, StatusPageSSO and GlobalSSO all fit it.
+ */
+export interface SamlProviderDefaultFields
+  extends SsoProviderDescriptionFields {
+  signatureMethod?: SignatureMethod | undefined;
+  digestMethod?: DigestMethod | undefined;
+}
+
+/**
+ * What a provider created without them gets, in place:
+ *
+ *   - a missing signature method is RSA-SHA256;
+ *   - a missing digest method is SHA256;
+ *   - a missing description is "Sign in with <name>".
+ *
+ * Whatever the caller sent is kept. Nothing else is touched: the sign-on
+ * URL, the issuer and the certificate come from the identity provider, so
+ * the required-field check names any of them that is missing.
+ */
+export const fillSamlProviderDefaults: (
+  provider: SamlProviderDefaultFields,
+) => void = (provider: SamlProviderDefaultFields): void => {
+  if (isBlankSsoValue(provider.signatureMethod)) {
+    provider.signatureMethod = DEFAULT_SAML_SIGNATURE_METHOD;
+  }
+
+  if (isBlankSsoValue(provider.digestMethod)) {
+    provider.digestMethod = DEFAULT_SAML_DIGEST_METHOD;
+  }
+
+  fillSsoProviderDescription(provider);
+};

package/Types/SSO/SsoProviderDefaults.ts

@@ -0,0 +1,101 @@
+/*
+ * What a single sign-on provider is described as when nobody describes it.
+ *
+ * A provider's description is shown under its name wherever people pick a
+ * provider to sign in with: the Accounts "Sign in with SSO" list and a
+ * private status page's sign-in page. Every provider form asked for one, as
+ * a required field, although almost everyone wrote the same thing. A
+ * provider created without one is now described as "Sign in with <name>"
+ * (the services fill it in before the required-field check, so the column
+ * stays required and the API and Terraform keep their contract), and the
+ * forms fill the same text in as the name is typed, so what the form shows is
+ * what is saved.
+ *
+ * Shared by SAML and OpenID Connect providers, for projects, status pages and
+ * the whole instance. React-free and server-safe: the API, the Dashboard, the
+ * Admin Dashboard and their tests all read it.
+ */
+
+const DESCRIPTION_PREFIX: string = "Sign in with";
+
+type IsBlankFunction = (value: unknown) => boolean;
+
+/*
+ * Nothing written: undefined, null, or text that is only spaces. Anything
+ * else (a URL object, say) is read through its text.
+ */
+export const isBlankSsoValue: IsBlankFunction = (value: unknown): boolean => {
+  if (value === undefined || value === null) {
+    return true;
+  }
+
+  return String(value).trim().length === 0;
+};
+
+/**
+ * The description a provider gets from its name: "Sign in with Okta". Empty
+ * while the name is.
+ */
+export const getDefaultSsoProviderDescription: (
+  name: string | null | undefined,
+) => string = (name: string | null | undefined): string => {
+  const trimmed: string = typeof name === "string" ? name.trim() : "";
+
+  if (!trimmed) {
+    return "";
+  }
+
+  return `${DESCRIPTION_PREFIX} ${trimmed}`;
+};
+
+/**
+ * Whether a description is the one the name gives (or none at all): it then
+ * follows the name when the name changes, on a create form and an edit form
+ * alike. A description somebody wrote is theirs and stays.
+ */
+export const isDefaultSsoProviderDescription: (data: {
+  description: string | null | undefined;
+  name: string | null | undefined;
+}) => boolean = (data: {
+  description: string | null | undefined;
+  name: string | null | undefined;
+}): boolean => {
+  if (isBlankSsoValue(data.description)) {
+    return true;
+  }
+
+  return (
+    String(data.description).trim() ===
+    getDefaultSsoProviderDescription(data.name)
+  );
+};
+
+/*
+ * A provider about to be created: the columns every provider has that this
+ * file fills in. The models (ProjectSSO, ProjectOIDC, StatusPageOIDC,
+ * GlobalOIDC...) all fit it.
+ */
+export interface SsoProviderDescriptionFields {
+  name?: string | undefined;
+  description?: string | undefined;
+}
+
+/**
+ * Gives a provider about to be created the description its name gives, when
+ * it was created without one. Changes nothing else, and nothing when the
+ * provider has no name either (the required-field check then says the name
+ * is missing).
+ */
+export const fillSsoProviderDescription: (
+  provider: SsoProviderDescriptionFields,
+) => void = (provider: SsoProviderDescriptionFields): void => {
+  if (!isBlankSsoValue(provider.description)) {
+    return;
+  }
+
+  const description: string = getDefaultSsoProviderDescription(provider.name);
+
+  if (description) {
+    provider.description = description;
+  }
+};