CS Cloud Auth

Reusable client-side helpers for adding Sign in with CS Cloud to Control Solutions applications.

This package wraps the shared Cognito/OIDC sign-in flow. It does not replace Cognito, it is not an auth server, and it does not own app-specific authorization. Each consuming app still validates its own allowed groups, tenants, routes, and API access.

Package Shape

@csllc/cs-cloud-auth
  core OAuth/OIDC redirect helpers
  React button components

The package is framework/core OIDC first and Amplify-free. React support is provided through the optional @csllc/cs-cloud-auth/react entry point.

Install

npm install @csllc/cs-cloud-auth

Public API

import {
  completeCsCloudRedirect,
  loginWithCsCloud,
  logoutFromCsCloud,
} from "@csllc/cs-cloud-auth";

import {
  CsCloudBrandedLoginButton,
  CsCloudLoginButton,
  useCsCloudLogin,
} from "@csllc/cs-cloud-auth/react";

The primary core helpers are:

• loginWithCsCloud(config, options) starts the authorization-code + PKCE redirect.
• completeCsCloudRedirect(config, options) validates callback state and exchanges the code for tokens.
• logoutFromCsCloud(config, options) redirects to the Cognito hosted logout endpoint.
• CsCloudBrandedLoginButton provides the default CS Cloud branded sign-in button.
• CsCloudLoginButton provides a minimal React button wrapper around useCsCloudLogin.
• useCsCloudLogin(config, defaults) exposes login behavior for apps with their own design-system buttons.

Branded Login Button

import { CsCloudBrandedLoginButton } from "@csllc/cs-cloud-auth/react";

const csCloudAuthConfig = {
  authDomain: "https://auth.cs-cloud.example",
  clientId: "cognito-app-client-id",
  redirectUri: `${window.location.origin}/auth/callback`,
  scopes: ["openid", "email", "profile"],
};

export function LoginPanel() {
  return (
    <CsCloudBrandedLoginButton
      config={csCloudAuthConfig}
      returnTo="/"
    />
  );
}

returnTo must be a same-origin relative path such as /, /dashboard, or /devices/123?tab=history. Absolute URLs and protocol-relative URLs are rejected to avoid open redirects.

CsCloudBrandedLoginButton defaults to the CS Cloud visual treatment: the embedded Control Solutions round logo, left-side diagonal blue panel, soft blue glow, and a hover/focus fill animation. Apps can customize it without replacing the login behavior:

<CsCloudBrandedLoginButton
  config={csCloudAuthConfig}
  returnTo="/dashboard"
  stripeWidth="30%"
  logo={<img src="/assets/cs-logo.png" alt="" />}
  logoStyle={{ height: 34, width: 34 }}
  minHeight={60}
>
  Continue with CS Cloud
</CsCloudBrandedLoginButton>

See docs/branding/branded-login-button.md for the reusable button customization guide.

Minimal Login Button

import { CsCloudLoginButton } from "@csllc/cs-cloud-auth/react";

export function PlainLoginPanel() {
  return <CsCloudLoginButton config={csCloudAuthConfig} returnTo="/" />;
}

CsCloudLoginButton defaults to type="button", disables itself while login is starting, and sets aria-busy during that loading window. Styling is intentionally minimal and can be overridden with normal button props.

Custom React Button

import { useCsCloudLogin } from "@csllc/cs-cloud-auth/react";

export function DesignSystemLoginButton() {
  const { login, isLoading, error } = useCsCloudLogin(csCloudAuthConfig, {
    returnTo: "/dashboard",
    onError: (loginError) => {
      console.error("CS Cloud login failed", loginError);
    },
  });

  return (
    <>
      <button
        type="button"
        disabled={isLoading}
        aria-busy={isLoading || undefined}
        onClick={() => {
          void login();
        }}
      >
        Continue with CS Cloud
      </button>
      {error ? <p role="alert">Unable to start login.</p> : null}
    </>
  );
}

The hook returns { login, isLoading, error }. login(overrides) merges defaults with per-call overrides, calls the core loginWithCsCloud helper, records the latest error, calls onError when provided, and rethrows failures so custom UI can decide how to respond.

Callback Route

import { completeCsCloudRedirect } from "@csllc/cs-cloud-auth";

const result = await completeCsCloudRedirect({
  authDomain: "https://auth.cs-cloud.example",
  clientId: "cognito-app-client-id",
  redirectUri: `${window.location.origin}/auth/callback`,
  scopes: ["openid", "email", "profile"],
});

// The consuming app owns token persistence, app session creation,
// authorization checks, and navigation after callback completion.
const { tokens, state } = result;

Callback state is single-use and expires quickly. completeCsCloudRedirect verifies the ID token nonce by default, returns tokens and validated redirect context, but it does not persist tokens or navigate the app. The consuming app should validate its own authorization rules before routing to state.returnTo.

Logout Flow

import { logoutFromCsCloud } from "@csllc/cs-cloud-auth";

// Clear the consuming app's local/session state first.
logoutFromCsCloud(
  {
    authDomain: "https://auth.cs-cloud.example",
    clientId: "cognito-app-client-id",
    redirectUri: `${window.location.origin}/auth/callback`,
  },
  {
    logoutUri: `${window.location.origin}/login`,
  },
);

logoutFromCsCloud only redirects to Cognito hosted logout. The consuming app owns local token/session cleanup before calling it.

logoutUri must be an absolute http or https URL. In a browser, the current origin is allowed by default; cross-origin logout targets must be explicitly allowed by the consuming app and configured in Cognito.

Cognito Configuration Checklist

Each consuming app should have its own Cognito app client and environment-specific configuration:

• Hosted UI or custom Cognito auth domain.
• Authorization code grant enabled with PKCE support.
• App client ID configured for the consuming app.
• Allowed callback URLs for every deployed environment.
• Allowed sign-out URLs for every deployed environment.
• Scopes such as openid, email, and profile, plus approved custom scopes when needed.
• Token lifetime and refresh-token policy chosen intentionally.
• Cognito groups or custom claims for app-specific authorization.
• App-side API authorization, tenant/org checks, and post-login routing.

For Cognito classic Hosted UI styling, see docs/branding/hosted-ui-branding.md. The packaged CSS includes the latest CS Cloud pilot edge polish for rounded Hosted UI cards, but it is published as guidance only; this package does not mutate Cognito branding at runtime.

Development

npm install
npm run typecheck
npm test
npm run build
npm run lint

See docs/pilot-integration.md for first-app wiring and real-browser QA guidance.

Release notes are tracked in CHANGELOG.md.

Publishing

This package publishes publicly under the @csllc scope. Before publishing, make sure no app-specific secrets, Cognito client secrets, or environment-specific private values have been added:

npm publish --access public