index.d.ts

import { Request } from "express-serve-static-core";

declare global {
  var ENV: {
    NODE_ENV: string;
    GOOGLE_ANALYTICS_ID: string;
    FHIR_SERVER_R2: string;
    FHIR_SERVER_R3: string;
    FHIR_SERVER_R4: string;
    ACCESS_TOKEN: string;
    VERSION: string;
    COMMIT: string;
  };
}

declare namespace SMART {
  /**
   * All the launch types that we recognize
   */
  type LaunchType =
    | "provider-ehr"
    | "patient-portal"
    | "provider-standalone"
    | "patient-standalone"
    | "backend-service"; //| "cds-hooks";

  type SimulatedError =
    // authorize request ---------------------------------------------------
    | "auth_invalid_client_id"
    | "auth_invalid_redirect_uri"
    | "auth_invalid_scope"
    | "auth_invalid_client_secret"

    // token request -------------------------------------------------------
    | "token_invalid_token"
    | "token_expired_refresh_token"
    | "token_expired_registration_token"
    | "token_invalid_scope"
    | "token_invalid_jti"

    // FHIR requests -------------------------------------------------------
    | "request_invalid_token"
    | "request_expired_token";

  interface JWKS {
    keys: JsonWebKey[];
  }

  type SMARTClientType =
    | "public"
    | "confidential-symmetric"
    | "confidential-asymmetric"
    | "backend-service";

  type PKCEValidation = "none" | "auto" | "always";

  /**
   * All the possible launch parameters. Only `launch_type` is required and
   * everything else is optional.
   */
  interface LaunchParams {
    launch_type: LaunchType;
    patient?: string;
    provider?: string;
    encounter?: string;
    skip_login?: boolean;
    skip_auth?: boolean;
    sim_ehr?: boolean;
    scope?: string;
    redirect_uris?: string;
    client_id?: string;
    client_secret?: string;
    auth_error?: SimulatedError;
    jwks_url?: string;
    jwks?: string;
    pkce?: PKCEValidation;
    client_type?: SMARTClientType;
    fhir_server?: string;
    fhir_context_str?: string;
  }

  interface AuthorizeParams {
    response_type: "code" | "token";
    client_id: string;
    redirect_uri: string;
    launch?: string;
    scope: string;
    state: string;
    aud: string;

    code_challenge_method?: "S256";
    code_challenge?: string;
    // jwks_url?: string

    // These can be set by dialogs
    patient?: string;
    provider?: string;
    encounter?: string;
    auth_success?: "0" | "1";
    login_success?: string;
  }

  // Describe possible authorize requests ------------------------------------
  // interface Request<
  //     P = ParamsDictionary,
  //     ResBody = any,
  //     ReqBody = any,
  //     ReqQuery = ParsedQs,
  //     Locals extends Record<string, any> = Record<string, any>
  // > extends http.IncomingMessage, Express.Request

  interface AuthorizeGetRequest extends Request {
    method: "GET";
    params: { fhir_release: "r2" | "r3" | "r4"; sim?: string };
    query: AuthorizeParams;
  }

  interface AuthorizePostRequest extends Request {
    method: "POST";
    params: { fhir_release: "r2" | "r3" | "r4"; sim?: string };
    body: AuthorizeParams;
  }

  type AuthorizeRequest = AuthorizeGetRequest | AuthorizePostRequest;

  /**
   * Defines the shapes of the payload or query parameters that various
   * backend endpoints expect
   */
  namespace Request {
    /**
     * An HTTP POST transaction is made to the EHR authorization server’s
     * token URL, with content-type application/x-www-form-urlencoded. The
     * decision about how long the refresh token lasts is determined by a
     * mechanism that the server chooses. For clients with online access,
     * the goal is to ensure that the user is still online.
     */
    interface RefreshToken {
      grant_type: "refresh_token";

      /**
       * The refresh token from a prior authorization response
       */
      refresh_token: string;

      /**
       * The scopes of access requested. If present, this value must be a
       * strict sub-set of the scopes granted in the original launch (no
       * new permissions can be obtained at refresh time). A missing value
       * indicates a request for the same scopes granted in the original
       * launch.
       */
      scope?: string;

      client_assertion_type;
      client_assertion;
    }

    /**
     * The body of POST requests sent to the token endpoint sending a `code`
     * and expecting an AccessToken response in return
     */
    interface AuthorizationCode {
      grant_type: "authorization_code";

      /**
       * The authorization token as obtained from the `authorize` call
       */
      code: string;

      /**
       * The same redirect_uri used in the initial authorization request
       */
      redirect_uri: string;

      /**
       * This parameter is used to verify against the code_challenge
       * parameter previously provided in the authorize request.
       */
      code_verifier?: string;

      /**
       * Required for public apps. Omit for confidential apps.
       */
      client_id?: string;

      /**
       * Auth token sighed with the client's private jwk
       */
      client_assertion?: string;

      /**
       * If client_assertion is set, then this should be set to
       * "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
       */
      client_assertion_type?: string;
    }
  }

  /**
   * Defines the shapes of the payload returned various backend endpoints
   */
  namespace Response {
    /**
     * The shape of the response of the token endpoint.
     */
    interface TokenResponse {
      token_type: "Bearer";

      access_token: string;

      /**
       * Lifetime in seconds of the access token, after which the token SHALL
       * NOT be accepted by the resource server
       */
      expires_in?: number;

      /**
       * Scope of access authorized. Note that this can be different from the
       * scopes requested by the app.
       */
      scope: string;

      /**
       * Token that can be used to obtain a new access token, using the same
       * or a subset of the original authorization grants. If present, the
       * app should discard any previous refresh_token associated with this
       * launch and replace it with this new value.
       */
      refresh_token?: string;
    }

    interface RefreshToken {
      token_type: "Bearer";

      access_token: string;

      /**
       * Lifetime in seconds of the access token, after which the token
       * SHALL NOT be accepted by the resource server
       */
      expires_in?: number;

      /**
       * Scope of access authorized. Note that this can be different from
       * the scopes requested by the app.
       */
      scope: string;

      /**
       * Token that can be used to obtain a new access token, using the
       * same or a subset of the original authorization grants. If present,
       * the app should discard any previous refresh_token associated with
       * this launch and replace it with this new value.
       */
      refresh_token?: string;
    }
  }

  /**
   * Once an app is authorized, the token response will include any context
   * data the app requested and any (potentially) unsolicited context data the
   * EHR may decide to communicate. For example, EHRs may use launch context
   * to communicate UX and UI expectations to the app (need_patient_banner).
   */
  interface LaunchContext {
    /**
     * Boolean value indicating whether the app was launched in a UX context
     * where a patient banner is required (when true) or not required (when
     * false). An app receiving a value of false should not take up screen
     * real estate displaying a patient banner.
     */
    need_patient_banner?: boolean;

    /**
     * String value with a patient id, indicating that the app was launched
     * in the context of FHIR Patient 123. If the app has any patient-level
     * scopes, they will be scoped to Patient 123.
     */
    patient?: string;

    /**
     * String value with an encounter id, indicating that the app was
     * launched in the context of FHIR Encounter 123.
     */
    encounter?: string;

    /**
     * String URL where the EHR’s style parameters can be retrieved (for
     * apps that support styling)
     */
    smart_style_url?: string;

    /**
     * String value describing the intent of the application launch.
     * Some SMART apps might offer more than one context or user interface
     * that can be accessed during the SMART launch. The optional intent
     * parameter in the launch context provides a mechanism for the SMART
     * EHR to communicate to the client app which specific context should be
     * displayed as the outcome of the launch. This allows for closer
     * integration between the EHR and client, so that different launch
     * points in the EHR UI can target specific displays within the client
     * app.
     *
     * For example, a patient timeline app might provide three specific UI
     * contexts, and inform the SMART EHR (out of band, at app configuration
     * time) of the intent values that can be used to launch the app
     * directly into one of the three contexts. The app might respond to
     * intent values like:
     *
     * `summary-timeline-view` - A default UI context, showing a data summary
     * `recent-history-timeline` - A history display, showing a list of entries
     * `encounter-focused-timeline` - A timeline focused on the currently
     * in-context encounter
     *
     * If a SMART EHR provides a value that the client does not recognize,
     * or does not provide a value, the client app SHOULD display a default
     * application UI context.
     *
     * Note that SMART makes no effort to standardize intent values. Intents
     * simply provide a mechanism for tighter custom integration between an
     * app and a SMART EHR. The meaning of intent values must be negotiated
     * between the app and the EHR.
     */
    intent?: string;

    /**
     * String conveying an opaque identifier for the healthcare organization
     * that is launching the app. This parameter is intended primarily to
     * support EHR Launch scenarios.
     */
    tenant?: string;

    /**
     * Array of relative resource References to any resource type other than
     * “Patient” or “Encounter”. It is not prohibited to have more than one
     * Reference to a given type of resource.
     */
    fhirContext?: Record<string, string>[];

    /**
     * Simulated error to throw
     * @PROPRIETARY
     */
    sim_error?: string;
  }

  /**
   * The shape of the response of the token endpoint.
   */
  interface TokenResponse {
    token_type: "Bearer";

    access_token: string;

    /**
     * Lifetime in seconds of the access token, after which the token SHALL
     * NOT be accepted by the resource server
     */
    expires_in?: number;

    /**
     * Scope of access authorized. Note that this can be different from the
     * scopes requested by the app.
     */
    scope: string;

    /**
     * Token that can be used to obtain a new access token, using the same
     * or a subset of the original authorization grants. If present, the
     * app should discard any previous refresh_token associated with this
     * launch and replace it with this new value.
     */
    refresh_token?: string;
  }

  /**
   * The shape of the response of the token endpoint.
   */
  interface AccessTokenResponse extends TokenResponse, LaunchContext {
    /**
     * Authenticated user identity and user details, if requested
     */
    id_token?: string;
  }

  /**
   * This is similar to the access token response but it does not include
   * launch context and id_token
   */
  interface RefreshTokenResponse extends TokenResponse {}

  /**
   * In our case the client_id is also a token. It contains details about the
   * registered client and allows us to be stateless
   */
  interface ClientToken {
    /**
     * In case the app wants to simulate certain errors
     */
    auth_error?: SimulatedError;

    /**
     * Identifies principal that issued the JWT. This is the FHIR server URL
     */
    iss: string;

    scope: string;

    pub_key: JsonWebKey;

    jwks_url?: string;

    jwks?: { keys: JsonWebKey[] };
  }

  /**
   * The authorization token (for example the one that is represented as `code`
   * parameter in the code flow)
   */
  interface AuthorizationToken extends LaunchContext {
    context: LaunchContext;

    /**
     * The client_id of the app being launched
     */
    client_id: string;

    /**
     * The scopes requested bu the app
     */
    scope: string;

    /**
     * The code_challenge_method used by the app
     */
    code_challenge_method?: string;

    /**
     * The code_challenge used by the app
     */
    code_challenge?: string;

    /**
     * Service Discovery URL
     */
    // sde: string

    /**
     * In case the app wants to simulate certain errors
     * @PROPRIETARY
     */
    auth_error?: SimulatedError;

    /**
     * AccessToken lifetime in minutes
     * @PROPRIETARY
     */
    accessTokensExpireIn?: number;

    /**
     * The client_secret for the client
     * @PROPRIETARY
     */
    client_secret?: string;

    nonce?: string;

    redirect_uri: string;

    /**
     * The selected user ID (if any)
     * @example `Patient/123` or `Practitioner/123`
     */
    user?: string;

    jwks_url?: string;
    jwks?: string;

    validation?: 0 | 1;
    pkce?: PKCEValidation;
    client_type?: SMARTClientType;
  }

  interface ClientMetadata {
    /**
     * Array of redirection URI strings for use in redirect-based flows
     * such as the authorization code and implicit flows.  As required by
     * Section 2 of OAuth 2.0 [RFC6749], clients using flows with
     * redirection MUST register their redirection URI values.
     * Authorization servers that support dynamic registration for
     * redirect-based flows MUST implement support for this metadata
     * value.
     */
    redirect_uris: string[];

    /**
     * String indicator of the requested authentication method for the
     * token endpoint.  Values defined by this specification are:
     *
     * - "none": The client is a public client as defined in OAuth 2.0,
     * Section 2.1, and does not have a client secret.
     *
     * - "client_secret_post": The client uses the HTTP POST parameters
     * as defined in OAuth 2.0, Section 2.3.1.
     *
     * - "client_secret_basic": The client uses HTTP Basic as defined in
     * OAuth 2.0, Section 2.3.1.
     *
     * Additional values can be defined via the IANA "OAuth Token
     * Endpoint Authentication Methods" registry established in
     * Section 4.2.  Absolute URIs can also be used as values for this
     * parameter without being registered.  If unspecified or omitted,
     * the default is "client_secret_basic", denoting the HTTP Basic
     * authentication scheme as specified in Section 2.3.1 of OAuth 2.0.
     */
    token_endpoint_auth_method?:
      | "none"
      | "client_secret_post"
      | "client_secret_basic"
      | string;
  }
}