Progmasoft Git

progmaweb

The site and account service of Progmasoft: a Next.js frontend and an ASP.NET Core API.

Clonegit clone https://git.progmasoft.com/progmaweb

mainroot / apps / web / lib / credentials.ts

7.0 KiB · Raw · Log

// SPDX-FileCopyrightText: 2026 Progmasoft <support@progmasoft.com>
// SPDX-License-Identifier: AGPL-3.0-or-later

/**
 * Progmasoft OAuth at credentials.progmasoft.com: the types of its JSON
 * endpoints and the requests the pages make.
 *
 * The protocol endpoints (`/connect/*`, `/.well-known/*`) and the JSON
 * endpoints (`/api/v1/oauth/*`) belong to the account API on the same host;
 * these pages only call them.
 */

/** The types an application may have, in the order the portal offers them. */
export const applicationKinds = [
  "web",
  "spa",
  "desktop",
  "mobile",
  "service",
] as const;
export type ApplicationKind = (typeof applicationKinds)[number];

export function isApplicationKind(value: string): value is ApplicationKind {
  return applicationKinds.includes(value as ApplicationKind);
}

/** Whether applications of a type sign people in, and so register redirection addresses and scopes. */
export function signsPeopleIn(kind: ApplicationKind): boolean {
  return kind !== "service";
}

/** The scopes an application may request, in the order the pages list them. */
export const oauthScopes = [
  "profile",
  "email",
  "offline_access",
] as const;
export type OAuthScope = (typeof oauthScopes)[number];

export interface ApplicationView {
  clientId: string;
  displayName: string;
  homepage: string;
  kind: ApplicationKind;
  isPublic: boolean;
  redirectUris: string[];
  postLogoutRedirectUris: string[];
  scopes: string[];
  createdAt: string;
}

export interface ApplicationList {
  applications: ApplicationView[];
  maximum: number;
}

export interface ApplicationCredentials {
  application: ApplicationView;
  clientSecret: string | null;
}

export interface ApplicationSubmission {
  kind: ApplicationKind;
  displayName: string;
  homepage: string;
  redirectUris: string[];
  postLogoutRedirectUris: string[];
  scopes: string[];
}

export interface AllowedApplication {
  authorizationId: string;
  displayName: string | null;
  scopes: string[];
  createdAt: string | null;
}

export interface ConsentView {
  clientId: string;
  displayName: string;
  homepage: string;
  owner: string | null;
  returnTo: string;
  scopes: string[];
  accountName: string;
}

export interface SessionView {
  accountName: string;
}

/** What a request to the JSON endpoints produced. */
export type ApiResult<T> =
  | { kind: "ok"; value: T }
  | { kind: "signedOut" }
  | { kind: "notFound" }
  | { kind: "refused"; errors: Record<string, string>; title?: string }
  | { kind: "failed" };

interface ProblemDetails {
  title?: string;
  detail?: string;
  errors?: Record<string, string[]>;
}

/**
 * Calls a JSON endpoint of Progmasoft OAuth on this host.
 *
 * The sign-in cookie of the OAuth host goes with the request; the browser adds
 * the `Origin` header the API checks for every request that changes state.
 */
export async function callOAuthApi<T>(
  path: string,
  init: { method?: string; body?: unknown; signal?: AbortSignal } = {},
): Promise<ApiResult<T>> {
  let response: Response;
  try {
    response = await fetch(`/api/v1/oauth${path}`, {
      method: init.method ?? "GET",
      credentials: "same-origin",
      headers:
        init.body === undefined
          ? undefined
          : { "Content-Type": "application/json" },
      body: init.body === undefined ? undefined : JSON.stringify(init.body),
      signal: init.signal,
    });
  } catch {
    return { kind: "failed" };
  }

  if (response.status === 401) {
    return { kind: "signedOut" };
  }
  if (response.status === 404) {
    return { kind: "notFound" };
  }
  if (response.status === 204) {
    return { kind: "ok", value: undefined as T };
  }
  if (response.ok) {
    return { kind: "ok", value: (await response.json()) as T };
  }
  if (response.status === 400) {
    const problem = (await response.json().catch(() => ({}))) as ProblemDetails;
    const errors: Record<string, string> = {};
    for (const [field, messages] of Object.entries(problem.errors ?? {})) {
      if (messages[0]) {
        errors[field] = messages[0];
      }
    }
    return {
      kind: "refused",
      errors,
      title: problem.detail ?? problem.title,
    };
  }
  return { kind: "failed" };
}

/**
 * A return address that stays on this host.
 *
 * The sign-in page sends the account holder back to where they came from,
 * usually `/connect/authorize`; anything that would leave the host goes to `/`.
 */
export function localReturnUrl(value: string | null | undefined): string {
  if (!value || value[0] !== "/" || value.startsWith("//")) {
    return "/";
  }
  if (value.startsWith("/\\") || /[\u0000-\u001f]/.test(value)) {
    return "/";
  }
  return value;
}

/** The address of the sign-in page that returns to the current page. */
export function signInPath(returnTo: string): string {
  return `/signin?ReturnUrl=${encodeURIComponent(localReturnUrl(returnTo))}`;
}

/** Splits a text area into its non-empty lines, each once. */
export function lines(text: string): string[] {
  return [
    ...new Set(
      text
        .split("\n")
        .map((line) => line.trim())
        .filter((line) => line.length > 0),
    ),
  ];
}

/** Drops the trailing slash of every path but the root. */
function trimmed(pathname: string): string {
  return pathname.length > 1 && pathname.endsWith("/")
    ? pathname.slice(0, -1)
    : pathname;
}

/**
 * The public pages of authorize.progmasoft.com and the internal routes that
 * render them: the home page, sign-in, the consent screen and the allowed
 * applications. Nginx sends `/connect` and `/api` of the host to the account
 * API; every other path reaches the proxy.
 */
export function authorizeRoute(pathname: string): string | null {
  const path = trimmed(pathname);
  if (path === "/") {
    return "/authorize";
  }
  if (path === "/signin" || path === "/consent") {
    return `/authorize${path}`;
  }
  if (path === "/account/applications") {
    return "/authorize/applications";
  }
  return null;
}

/**
 * The public pages of credentials.progmasoft.com, the issuer: only its home
 * page. Its endpoints and discovery documents belong to the account API.
 */
export function issuerRoute(pathname: string): string | null {
  return trimmed(pathname) === "/" ? "/issuer" : null;
}

/**
 * The public pages of console.progmasoft.com, the Progmasoft Console, and the
 * internal routes that render them: the overview and the OAuth 2.1
 * credentials under `/credentials` (the list, a new token in two steps, one
 * application). The console has no sign-in page: it uses the Progmasoft
 * account session.
 */
export function consoleRoute(pathname: string): string | null {
  const path = trimmed(pathname);
  if (path === "/") {
    return "/console";
  }
  if (path === "/credentials" || path === "/credentials/new") {
    return `/console${path}`;
  }
  const segments = path.split("/");
  if (segments[1] !== "credentials") {
    return null;
  }
  if (segments.length === 4 && segments[2] === "new" && segments[3]) {
    return `/console${path}`;
  }
  if (segments.length === 3 && segments[2]) {
    return `/console${path}`;
  }
  return null;
}