@oatscenter/trellis-svelte 0.100.0-rc.1

package/src/internal/activation_view.ts

@@ -0,0 +1,179 @@
+import type {
+  DeviceUserAuthoritiesResolveOutput,
+  DeviceUserAuthoritiesResolveProgress,
+} from "@oatscenter/trellis/auth";
+import type { TerminalOperation } from "@oatscenter/trellis";
+
+export type DeviceActivationView =
+  | { mode: "sign_in_required"; flowId: string }
+  | { mode: "ready"; flowId: string }
+  | {
+    mode: "pending_review";
+    flowId: string;
+    state: DeviceUserAuthoritiesResolveProgress["state"];
+  }
+  | {
+    mode: "activated";
+    flowId: string;
+    instanceId: string;
+    deploymentId: string;
+    activatedAt: string;
+  }
+  | { mode: "rejected"; flowId: string; reason?: string }
+  | { mode: "expired"; flowId: string; reason: string }
+  | { mode: "invalid_flow"; reason: string; flowId?: string };
+
+function isoString(value: string | number | bigint | Date): string {
+  return value instanceof Date
+    ? value.toISOString()
+    : typeof value === "number" || typeof value === "bigint"
+    ? new Date(Number(value)).toISOString()
+    : value;
+}
+
+function errorReason(error: unknown): string | undefined {
+  if (typeof error !== "object" || error === null || !("reason" in error)) {
+    return undefined;
+  }
+
+  const reason = Reflect.get(error, "reason");
+  return typeof reason === "string" ? reason : undefined;
+}
+
+/**
+ * Whether a companion resubmission failed because the signed-in user is not
+ * allowed to decide it, which leaves the activation to a reviewer. Malformed,
+ * stale, and transport failures are not reviewer outcomes.
+ */
+export function isDeviceActivationReviewerRequiredFailure(
+  error: unknown,
+): boolean {
+  const reason = errorReason(error);
+  return (
+    reason === "not_authorized" ||
+    reason === "insufficient_permissions" ||
+    reason === "forbidden"
+  );
+}
+
+export function createDeviceActivationReadyView(
+  flowId: string,
+): DeviceActivationView {
+  return { mode: "ready", flowId };
+}
+
+export function createDeviceActivationSignInRequiredView(
+  flowId: string,
+): DeviceActivationView {
+  return { mode: "sign_in_required", flowId };
+}
+
+export function createInvalidDeviceActivationView(
+  reason: string,
+  flowId?: string,
+): DeviceActivationView {
+  return flowId
+    ? { mode: "invalid_flow", reason, flowId }
+    : { mode: "invalid_flow", reason };
+}
+
+export function mapDeviceActivationOutput(
+  flowId: string,
+  result: DeviceUserAuthoritiesResolveOutput,
+): DeviceActivationView {
+  if (result.review.state === "approved") {
+    return {
+      mode: "activated",
+      flowId,
+      instanceId: result.device.instanceId,
+      deploymentId: result.device.deploymentId,
+      activatedAt: isoString(
+        result.review.decidedAt ?? result.device.updatedAt,
+      ),
+    };
+  }
+
+  return {
+    mode: "rejected",
+    flowId,
+    ...(result.review.reason ? { reason: result.review.reason } : {}),
+  };
+}
+
+export function mapDeviceActivationProgress(
+  flowId: string,
+  progress: DeviceUserAuthoritiesResolveProgress,
+): DeviceActivationView {
+  return {
+    mode: "pending_review",
+    flowId,
+    state: progress.state,
+  };
+}
+
+export function mapDeviceActivationFailure(
+  flowId: string,
+  error: unknown,
+): DeviceActivationView | null {
+  const reason = errorReason(error);
+
+  if (reason === "device_activation_flow_not_found") {
+    return createInvalidDeviceActivationView(
+      "This activation link is no longer valid.",
+      flowId,
+    );
+  }
+
+  if (reason === "device_activation_flow_expired") {
+    return {
+      mode: "expired",
+      flowId,
+      reason:
+        "The activation request expired. Start again from the auth service.",
+    };
+  }
+
+  if (reason === "unknown_device") {
+    return createInvalidDeviceActivationView(
+      "This activation link no longer matches a known device.",
+      flowId,
+    );
+  }
+
+  if (reason === "device_deployment_not_found") {
+    return createInvalidDeviceActivationView(
+      "This device deployment is no longer available.",
+      flowId,
+    );
+  }
+
+  if (reason === "invalid_request") {
+    return createInvalidDeviceActivationView(
+      "Trellis rejected this activation request. Start again from the device.",
+      flowId,
+    );
+  }
+
+  if (
+    reason === "device_activation_revoked"
+  ) {
+    return { mode: "rejected", flowId, reason };
+  }
+
+  return null;
+}
+
+export function mapDeviceActivationTerminal(
+  flowId: string,
+  terminal: TerminalOperation<unknown, DeviceUserAuthoritiesResolveOutput>,
+): DeviceActivationView | null {
+  if (terminal.state === "completed") {
+    return terminal.output
+      ? mapDeviceActivationOutput(flowId, terminal.output)
+      : null;
+  }
+
+  return terminal.error
+    ? mapDeviceActivationFailure(flowId, terminal.error)
+    : null;
+}

package/src/internal/callback_state.ts

@@ -0,0 +1,48 @@
+export type DeviceActivationCallbackState = {
+  flowId: string;
+  callbackToken: string;
+};
+
+export type StorageLike = Pick<Storage, "getItem" | "setItem" | "removeItem">;
+
+const PRESERVED_ACTIVATION_FLOW_ID_STORAGE_KEY = "portal.activate.flowId";
+const ACTIVATION_CALLBACK_TOKEN_STORAGE_KEY = "portal.activate.callbackToken";
+const ACTIVATION_CALLBACK_QUERY_PARAM = "portalCallback";
+
+export function getPreservedDeviceActivationCallbackState(
+  storage: StorageLike,
+): DeviceActivationCallbackState | null {
+  const flowId = storage.getItem(PRESERVED_ACTIVATION_FLOW_ID_STORAGE_KEY);
+  const callbackToken = storage.getItem(ACTIVATION_CALLBACK_TOKEN_STORAGE_KEY);
+
+  if (!flowId || !callbackToken) return null;
+
+  return { flowId, callbackToken };
+}
+
+export function preserveDeviceActivationCallbackState(
+  storage: StorageLike,
+  nextState: DeviceActivationCallbackState,
+): void {
+  storage.setItem(PRESERVED_ACTIVATION_FLOW_ID_STORAGE_KEY, nextState.flowId);
+  storage.setItem(
+    ACTIVATION_CALLBACK_TOKEN_STORAGE_KEY,
+    nextState.callbackToken,
+  );
+}
+
+export function clearPreservedDeviceActivationCallbackState(
+  storage: StorageLike,
+): void {
+  storage.removeItem(PRESERVED_ACTIVATION_FLOW_ID_STORAGE_KEY);
+  storage.removeItem(ACTIVATION_CALLBACK_TOKEN_STORAGE_KEY);
+}
+
+export function isDeviceActivationAuthCallback(
+  currentUrl: URL,
+  preservedState: DeviceActivationCallbackState | null,
+): boolean {
+  if (!preservedState) return false;
+  return currentUrl.searchParams.get(ACTIVATION_CALLBACK_QUERY_PARAM) ===
+    preservedState.callbackToken;
+}

package/src/internal/portal_url.ts

@@ -0,0 +1,94 @@
+import type { DeviceActivationCallbackState } from "./callback_state.ts";
+import { isDeviceActivationAuthCallback } from "./callback_state.ts";
+
+export type DeviceActivationConnectAuthUrlState = {
+  currentUrl: URL;
+  redirectTo: string;
+};
+
+export type DeviceActivationUrlState = {
+  flowId: string | null;
+  isAuthCallback: boolean;
+};
+
+const ACTIVATION_CALLBACK_QUERY_PARAM = "portalCallback";
+const AUTH_ERROR_QUERY_PARAM = "authError";
+const DEVICE_FLOW_ID_QUERY_PARAM = "deviceFlowId";
+const FLOW_ID_QUERY_PARAM = "flowId";
+
+export function buildDeviceActivationCallbackPath(
+  currentUrl: URL,
+  callbackToken: string,
+): string {
+  const callbackUrl = new URL(currentUrl.pathname, currentUrl.origin);
+  callbackUrl.searchParams.set(ACTIVATION_CALLBACK_QUERY_PARAM, callbackToken);
+  const flowId = currentUrl.searchParams.get(FLOW_ID_QUERY_PARAM);
+  if (flowId) {
+    callbackUrl.searchParams.set(DEVICE_FLOW_ID_QUERY_PARAM, flowId);
+  }
+  callbackUrl.hash = currentUrl.hash;
+  return `${callbackUrl.pathname}${callbackUrl.search}${callbackUrl.hash}`;
+}
+
+export function buildDeviceActivationConnectAuthUrlState(
+  currentUrl: URL,
+): DeviceActivationConnectAuthUrlState {
+  const redirectUrl = new URL(currentUrl);
+  redirectUrl.searchParams.delete(ACTIVATION_CALLBACK_QUERY_PARAM);
+  redirectUrl.searchParams.delete(AUTH_ERROR_QUERY_PARAM);
+  redirectUrl.searchParams.delete(DEVICE_FLOW_ID_QUERY_PARAM);
+
+  const authCurrentUrl = new URL(redirectUrl);
+  authCurrentUrl.searchParams.delete(DEVICE_FLOW_ID_QUERY_PARAM);
+  authCurrentUrl.searchParams.delete(FLOW_ID_QUERY_PARAM);
+
+  return {
+    currentUrl: authCurrentUrl,
+    redirectTo: redirectUrl.toString(),
+  };
+}
+
+export function cleanupDeviceActivationCallbackUrl(
+  currentUrl: URL,
+  flowId: string | null,
+): string | null {
+  if (
+    !currentUrl.searchParams.has(FLOW_ID_QUERY_PARAM) &&
+    !currentUrl.searchParams.has(AUTH_ERROR_QUERY_PARAM) &&
+    !currentUrl.searchParams.has(DEVICE_FLOW_ID_QUERY_PARAM) &&
+    !currentUrl.searchParams.has(ACTIVATION_CALLBACK_QUERY_PARAM)
+  ) {
+    return null;
+  }
+
+  const nextUrl = new URL(currentUrl);
+  nextUrl.searchParams.delete(FLOW_ID_QUERY_PARAM);
+  nextUrl.searchParams.delete(AUTH_ERROR_QUERY_PARAM);
+  nextUrl.searchParams.delete(DEVICE_FLOW_ID_QUERY_PARAM);
+  nextUrl.searchParams.delete(ACTIVATION_CALLBACK_QUERY_PARAM);
+  if (flowId) {
+    nextUrl.searchParams.set(FLOW_ID_QUERY_PARAM, flowId);
+  }
+
+  return `${nextUrl.pathname}${nextUrl.search}${nextUrl.hash}`;
+}
+
+export function resolveDeviceActivationUrlState(
+  currentUrl: URL,
+  preservedState: DeviceActivationCallbackState | null,
+): DeviceActivationUrlState {
+  const callbackFlowId = currentUrl.searchParams.get(
+    DEVICE_FLOW_ID_QUERY_PARAM,
+  );
+  const isAuthCallback =
+    isDeviceActivationAuthCallback(currentUrl, preservedState) ||
+    (currentUrl.searchParams.has(ACTIVATION_CALLBACK_QUERY_PARAM) &&
+      !!callbackFlowId);
+
+  return {
+    flowId: isAuthCallback
+      ? preservedState?.flowId ?? callbackFlowId
+      : currentUrl.searchParams.get(FLOW_ID_QUERY_PARAM),
+    isAuthCallback,
+  };
+}

package/src/portal_flow.svelte.ts

@@ -0,0 +1,143 @@
+import {
+  type BrowserPortalFlowState as PortalFlowState,
+  fetchPortalFlowState,
+  getOrCreatePortalBinding,
+  type PortalBinding,
+  portalFlowIdFromUrl,
+  portalProviderLoginUrl,
+  submitPortalApproval,
+  TrellisHttpError,
+} from "@oatscenter/trellis/auth/browser";
+
+type AuthConfig = { authUrl: string };
+
+export type CreatePortalFlowConfig = AuthConfig & {
+  getUrl?: () => URL;
+  sessionStorage?: Storage;
+};
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function defaultGetUrl(): URL {
+  return new URL(globalThis.location.href);
+}
+
+export class PortalFlowController {
+  flowId: string | null = $state(null);
+  state: PortalFlowState | null = $state(null);
+  loading = $state(false);
+  error: string | null = $state(null);
+  errorCode: string | null = $state(null);
+
+  #config: AuthConfig;
+  #getUrl: () => URL;
+  #sessionStorage: Storage;
+  #binding: PortalBinding | null = null;
+
+  constructor(config: CreatePortalFlowConfig) {
+    this.#config = { authUrl: config.authUrl };
+    this.#getUrl = config.getUrl ?? defaultGetUrl;
+    this.#sessionStorage = config.sessionStorage ?? globalThis.sessionStorage;
+  }
+
+  async load(): Promise<PortalFlowState | null> {
+    this.loading = true;
+    this.error = null;
+    this.errorCode = null;
+    this.state = null;
+
+    try {
+      const flowId = portalFlowIdFromUrl(this.#getUrl());
+      this.flowId = flowId;
+      if (!flowId) {
+        this.error = "Missing flow id.";
+        this.errorCode = "missing_flow_id";
+        return null;
+      }
+
+      this.#binding = await getOrCreatePortalBinding(
+        flowId,
+        this.#sessionStorage,
+      );
+      const state = await fetchPortalFlowState(
+        this.#config,
+        flowId,
+        this.#binding,
+      );
+      this.state = state;
+      return state;
+    } catch (error) {
+      this.error = errorMessage(error);
+      this.errorCode = error instanceof TrellisHttpError ? error.code : null;
+      this.state = null;
+      return null;
+    } finally {
+      this.loading = false;
+    }
+  }
+
+  providerUrl(providerId: string): string {
+    if (!this.flowId) {
+      throw new Error("Missing flow id.");
+    }
+
+    if (!this.#binding) throw new Error("Portal flow has not loaded.");
+    return portalProviderLoginUrl(
+      this.#config,
+      providerId,
+      this.flowId,
+      this.#binding,
+    );
+  }
+
+  get binding(): PortalBinding {
+    if (!this.#binding) throw new Error("Portal flow has not loaded.");
+    return this.#binding;
+  }
+
+  async approve(): Promise<PortalFlowState | null> {
+    return this.#submit("approved");
+  }
+
+  async deny(): Promise<PortalFlowState | null> {
+    return this.#submit("denied");
+  }
+
+  async #submit(
+    decision: "approved" | "denied",
+  ): Promise<PortalFlowState | null> {
+    if (!this.flowId) {
+      this.error = "Missing flow id.";
+      return null;
+    }
+
+    this.loading = true;
+    this.error = null;
+    this.errorCode = null;
+
+    try {
+      const state = await submitPortalApproval(
+        this.#config,
+        this.flowId,
+        this.binding,
+        decision,
+      );
+      this.state = state;
+      return state;
+    } catch (error) {
+      this.error = errorMessage(error);
+      this.errorCode = error instanceof TrellisHttpError ? error.code : null;
+      return null;
+    } finally {
+      this.loading = false;
+    }
+  }
+}
+
+export function createPortalFlow(
+  config: CreatePortalFlowConfig,
+): PortalFlowController {
+  return new PortalFlowController(config);
+}