@awsesh/core 1.0.19 → 1.1.3

package/index.d.ts

@@ -3,6 +3,7 @@ export { AWSClient } from "./client";
 export { Credentials } from "./credentials";
 export { Sessions } from "./sessions";
 export { Storage } from "./storage";
+export { createWorkflow } from "./workflow";
 import type { AwseshOptions, SSOSession, SSOLoginInfo, TokenCache, AccountCache, RoleCredentials, LastSelected, LastSelectedPerSession, ActiveCredential, LastSetCredential, SetCredentialOptions, SetCredentialResult } from "./types";
 export declare function createAwsesh(options: AwseshOptions): {
     sessions: {
@@ -46,6 +47,9 @@ export declare function createAwsesh(options: AwseshOptions): {
         save: (sessionName: string, accountId: string) => Promise<void>;
         getAll: () => Promise<LastSelectedPerSession>;
     };
+    lastProfiles: {
+        getAll: (sessionName: string) => Promise<Record<string, string>>;
+    };
     profileNames: {
         get: (sessionName: string, accountName: string, roleName: string) => Promise<string | undefined>;
         save: (sessionName: string, accountName: string, roleName: string, profileName: string) => Promise<void>;

package/index.js

@@ -20238,6 +20238,209 @@ var Storage;
   }
   Storage.create = create;
 })(Storage ||= {});
+// src/workflow.ts
+import { setTimeout as setTimeout2 } from "node:timers/promises";
+function createWorkflow(awsesh) {
+  const logins = new Map;
+  function validateName(name) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9 _-]{0,127}$/.test(name)) {
+      throw new Error("Session names must contain letters, numbers, spaces, dashes or underscores");
+    }
+  }
+  function validateRegion(region) {
+    if (!/^[a-z]{2}(?:-[a-z]+)+-\d+$/.test(region))
+      throw new Error("Invalid AWS region");
+  }
+  async function session(name) {
+    validateName(name);
+    const value = await awsesh.sessions.get(name);
+    if (!value)
+      throw new Error(`SSO session not found: ${name}`);
+    return value;
+  }
+  async function token(value) {
+    const cached = await awsesh.tokens.get(value.startUrl);
+    if (!cached)
+      throw new Error("Sign in to this SSO session first");
+    return cached.token;
+  }
+  async function account(name, accountId) {
+    const cache = await awsesh.accounts.get(name);
+    const value = cache?.accounts.find((item) => item.accountId === accountId);
+    if (!value)
+      throw new Error("Account not found; refresh the account list");
+    return value;
+  }
+  async function snapshot(name) {
+    const sessions = await awsesh.sessions.list();
+    const selected = name ? await session(name) : undefined;
+    const credentials = await awsesh.activeCredentials.list();
+    const cache = selected ? await awsesh.accounts.get(selected.name) : undefined;
+    const roles = selected ? await awsesh.preferredRoles.getAll(selected.name) : {};
+    const regions = selected ? await awsesh.preferredRegions.getAll(selected.name) : {};
+    const profiles = selected ? await awsesh.lastProfiles.getAll(selected.name) : {};
+    const previous = await awsesh.lastSetCredential.get();
+    return {
+      sessions: await Promise.all(sessions.map(async (value) => ({
+        ...value,
+        authenticated: !!await awsesh.tokens.get(value.startUrl)
+      }))),
+      session: selected?.name,
+      accounts: await Promise.all((cache?.accounts ?? []).map(async (value) => ({
+        ...value,
+        preferredRole: value.roles.includes(roles[value.accountId]) ? roles[value.accountId] : undefined,
+        region: regions[value.accountId] ?? selected?.defaultRegion,
+        profiles: await awsesh.profileNames.getForAccount(selected?.name ?? "", value.name),
+        lastProfile: profiles[value.accountId] ?? (previous?.sessionName === selected?.name && previous?.accountId === value.accountId ? previous.profileName : undefined) ?? credentials.findLast((credential) => credential.sessionName === selected?.name && credential.accountId === value.accountId)?.profileName
+      }))),
+      credentials,
+      lastSelected: await awsesh.lastSelected.get(),
+      lastAccount: selected ? await awsesh.lastAccountPerSession.get(selected.name) : undefined,
+      lastSession: await awsesh.lastSession.get()
+    };
+  }
+  return {
+    snapshot,
+    async selectSession(name, refresh = false) {
+      const value = await session(name);
+      const cache = await awsesh.accounts.get(name);
+      if (refresh || !cache) {
+        const accounts = await awsesh.sso.listAccounts(value, await token(value));
+        await awsesh.accounts.save(name, { accounts, lastUpdated: Date.now() });
+      }
+      await awsesh.lastSession.save(name);
+      return snapshot(name);
+    },
+    async saveSession(value, creating = false) {
+      validateName(value.name);
+      const url = new URL(value.startUrl);
+      if (url.protocol !== "https:" || url.username || url.password)
+        throw new Error("SSO start URL must use HTTPS");
+      validateRegion(value.ssoRegion);
+      validateRegion(value.defaultRegion);
+      if (creating && await awsesh.sessions.exists(value.name))
+        throw new Error("A session with this name already exists");
+      await awsesh.sessions.save(value);
+      return snapshot();
+    },
+    async removeSession(name) {
+      await session(name);
+      logins.delete(name);
+      await awsesh.sessions.remove(name);
+      return snapshot();
+    },
+    async startLogin(name) {
+      const value = await session(name);
+      const info = await awsesh.sso.startLogin(value);
+      logins.set(name, info);
+      return { url: info.verificationUriComplete || info.verificationUri, code: info.userCode };
+    },
+    async pollLogin(name) {
+      const value = await session(name);
+      const info = logins.get(name);
+      if (!info)
+        throw new Error("Start a new SSO login");
+      if (info.expiresAt.getTime() <= Date.now()) {
+        logins.delete(name);
+        throw new Error("SSO authorization expired; sign in again");
+      }
+      await setTimeout2(Math.max(1, info.interval) * 1000);
+      const result = await awsesh.sso.pollForToken(value, info);
+      if (!result)
+        return { complete: false };
+      await awsesh.tokens.save(value.startUrl, result.token, result.expiresAt);
+      logins.delete(name);
+      return { complete: true };
+    },
+    async cancelLogin(name) {
+      logins.delete(name);
+    },
+    async loadRoles(name, accountId, refresh = false) {
+      const value = await session(name);
+      const selected = await account(name, accountId);
+      if (selected.rolesLoaded && !refresh)
+        return snapshot(name);
+      const roles = await awsesh.sso.listRoles(value, await token(value), accountId);
+      const cache = await awsesh.accounts.get(name);
+      if (!cache)
+        throw new Error("Account cache no longer exists");
+      await awsesh.accounts.save(name, {
+        ...cache,
+        accounts: cache.accounts.map((item) => item.accountId === accountId ? { ...item, roles, rolesLoaded: true } : item)
+      });
+      return snapshot(name);
+    },
+    async preferRole(name, accountId, role) {
+      await session(name);
+      const value = await account(name, accountId);
+      if (!value.roles.includes(role))
+        throw new Error("Role is not available for this account");
+      await awsesh.preferredRoles.save(name, accountId, role);
+      return snapshot(name);
+    },
+    async setRegion(name, accountId, region) {
+      await session(name);
+      await account(name, accountId);
+      validateRegion(region);
+      await awsesh.preferredRegions.save(name, accountId, region);
+      return snapshot(name);
+    },
+    async setProfile(name, accountId, role, profile) {
+      await session(name);
+      const value = await account(name, accountId);
+      if (!value.roles.includes(role))
+        throw new Error("Role is not available for this account");
+      if (profile && !/^[a-zA-Z0-9_-]{1,128}$/.test(profile))
+        throw new Error("Invalid CLI profile name");
+      if (profile)
+        await awsesh.profileNames.save(name, value.name, role, profile);
+      if (!profile)
+        await awsesh.profileNames.remove(name, value.name, role);
+      return snapshot(name);
+    },
+    async assumeRole(name, accountId, role) {
+      const value = await session(name);
+      const selected = await account(name, accountId);
+      if (!selected.roles.includes(role))
+        throw new Error("Role is not available for this account");
+      const credentials = await awsesh.sso.getCredentials(value, await token(value), accountId, role);
+      const region = await awsesh.preferredRegions.get(name, accountId) ?? value.defaultRegion;
+      await awsesh.setCredential({ credentials, sessionName: name, accountId, accountName: selected.name, roleName: role, region });
+      await awsesh.lastAccountPerSession.save(name, accountId);
+      return snapshot(name);
+    },
+    async consoleUrl(name, accountId, role) {
+      const value = await session(name);
+      if (!accountId)
+        return awsesh.sso.getDashboardUrl(value);
+      const selected = await account(name, accountId);
+      if (!role || !selected.roles.includes(role))
+        throw new Error("Select an available role first");
+      return awsesh.sso.getAccountUrl(value, accountId, "", role);
+    },
+    async clearCredential(accountId, role, profile, name) {
+      const active = await awsesh.activeCredentials.list();
+      if (!active.some((value) => value.accountId === accountId && value.roleName === role && value.profileName === profile)) {
+        throw new Error("Active credential not found");
+      }
+      await awsesh.clearCredential(accountId, role, profile);
+      return snapshot(name);
+    },
+    async clearAllCredentials(name) {
+      if (name)
+        await session(name);
+      await awsesh.clearAllCredentials(true);
+      return snapshot(name);
+    },
+    async signOut(name) {
+      const value = await session(name);
+      logins.delete(name);
+      await awsesh.clearSessionCredentials(name, true);
+      await awsesh.tokens.remove(value.startUrl);
+      return snapshot(name);
+    }
+  };
+}
 
 // src/index.ts
 import { createHash } from "node:crypto";
@@ -20370,6 +20573,12 @@ function createAwsesh(options) {
         return data ?? {};
       }
     },
+    lastProfiles: {
+      getAll: async (sessionName) => {
+        const data = await storage.read("preference/last-profiles");
+        return data?.[sessionName] ?? {};
+      }
+    },
     profileNames: {
       get: async (sessionName, accountName, roleName) => {
         const data = await storage.read("preference/profile-names");
@@ -20555,6 +20764,11 @@ function createAwsesh(options) {
         region,
         setAt: new Date().toISOString()
       });
+      await storage.update("preference/last-profiles", (draft) => {
+        draft[sessionName] ??= {};
+        draft[sessionName][accountId] = profileName;
+        return draft;
+      });
       await storage.update("preference/last-selected", (existing) => ({
         ...existing,
         session: sessionName,
@@ -20616,5 +20830,6 @@ export {
   Credentials,
   Sessions,
   Storage,
-  createAwsesh
+  createAwsesh,
+  createWorkflow
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awsesh/core",
-  "version": "1.0.19",
+  "version": "1.1.3",
   "description": "AWS SSO session management SDK",
   "type": "module",
   "main": "./index.js",

package/workflow.d.ts

@@ -0,0 +1,314 @@
+import type { Awsesh } from "./index";
+import type { SSOSession } from "./types";
+/** Presentation-independent operations for interactive clients. Never returns credentials or tokens. */
+export declare function createWorkflow(awsesh: Awsesh): {
+    snapshot: (name?: string) => Promise<{
+        sessions: {
+            authenticated: boolean;
+            name: string;
+            startUrl: string;
+            ssoRegion: string;
+            defaultRegion: string;
+            isChina?: boolean;
+        }[];
+        session: string | undefined;
+        accounts: {
+            preferredRole: string | undefined;
+            region: string;
+            profiles: Record<string, string>;
+            lastProfile: string;
+            accountId: string;
+            name: string;
+            roles: string[];
+            rolesLoaded: boolean;
+        }[];
+        credentials: import("./types").ActiveCredential[];
+        lastSelected: import("./types").LastSelected;
+        lastAccount: string | undefined;
+        lastSession: string | undefined;
+    }>;
+    selectSession(name: string, refresh?: boolean): Promise<{
+        sessions: {
+            authenticated: boolean;
+            name: string;
+            startUrl: string;
+            ssoRegion: string;
+            defaultRegion: string;
+            isChina?: boolean;
+        }[];
+        session: string | undefined;
+        accounts: {
+            preferredRole: string | undefined;
+            region: string;
+            profiles: Record<string, string>;
+            lastProfile: string;
+            accountId: string;
+            name: string;
+            roles: string[];
+            rolesLoaded: boolean;
+        }[];
+        credentials: import("./types").ActiveCredential[];
+        lastSelected: import("./types").LastSelected;
+        lastAccount: string | undefined;
+        lastSession: string | undefined;
+    }>;
+    saveSession(value: SSOSession, creating?: boolean): Promise<{
+        sessions: {
+            authenticated: boolean;
+            name: string;
+            startUrl: string;
+            ssoRegion: string;
+            defaultRegion: string;
+            isChina?: boolean;
+        }[];
+        session: string | undefined;
+        accounts: {
+            preferredRole: string | undefined;
+            region: string;
+            profiles: Record<string, string>;
+            lastProfile: string;
+            accountId: string;
+            name: string;
+            roles: string[];
+            rolesLoaded: boolean;
+        }[];
+        credentials: import("./types").ActiveCredential[];
+        lastSelected: import("./types").LastSelected;
+        lastAccount: string | undefined;
+        lastSession: string | undefined;
+    }>;
+    removeSession(name: string): Promise<{
+        sessions: {
+            authenticated: boolean;
+            name: string;
+            startUrl: string;
+            ssoRegion: string;
+            defaultRegion: string;
+            isChina?: boolean;
+        }[];
+        session: string | undefined;
+        accounts: {
+            preferredRole: string | undefined;
+            region: string;
+            profiles: Record<string, string>;
+            lastProfile: string;
+            accountId: string;
+            name: string;
+            roles: string[];
+            rolesLoaded: boolean;
+        }[];
+        credentials: import("./types").ActiveCredential[];
+        lastSelected: import("./types").LastSelected;
+        lastAccount: string | undefined;
+        lastSession: string | undefined;
+    }>;
+    startLogin(name: string): Promise<{
+        url: string;
+        code: string;
+    }>;
+    pollLogin(name: string): Promise<{
+        complete: boolean;
+    }>;
+    cancelLogin(name: string): Promise<void>;
+    loadRoles(name: string, accountId: string, refresh?: boolean): Promise<{
+        sessions: {
+            authenticated: boolean;
+            name: string;
+            startUrl: string;
+            ssoRegion: string;
+            defaultRegion: string;
+            isChina?: boolean;
+        }[];
+        session: string | undefined;
+        accounts: {
+            preferredRole: string | undefined;
+            region: string;
+            profiles: Record<string, string>;
+            lastProfile: string;
+            accountId: string;
+            name: string;
+            roles: string[];
+            rolesLoaded: boolean;
+        }[];
+        credentials: import("./types").ActiveCredential[];
+        lastSelected: import("./types").LastSelected;
+        lastAccount: string | undefined;
+        lastSession: string | undefined;
+    }>;
+    preferRole(name: string, accountId: string, role: string): Promise<{
+        sessions: {
+            authenticated: boolean;
+            name: string;
+            startUrl: string;
+            ssoRegion: string;
+            defaultRegion: string;
+            isChina?: boolean;
+        }[];
+        session: string | undefined;
+        accounts: {
+            preferredRole: string | undefined;
+            region: string;
+            profiles: Record<string, string>;
+            lastProfile: string;
+            accountId: string;
+            name: string;
+            roles: string[];
+            rolesLoaded: boolean;
+        }[];
+        credentials: import("./types").ActiveCredential[];
+        lastSelected: import("./types").LastSelected;
+        lastAccount: string | undefined;
+        lastSession: string | undefined;
+    }>;
+    setRegion(name: string, accountId: string, region: string): Promise<{
+        sessions: {
+            authenticated: boolean;
+            name: string;
+            startUrl: string;
+            ssoRegion: string;
+            defaultRegion: string;
+            isChina?: boolean;
+        }[];
+        session: string | undefined;
+        accounts: {
+            preferredRole: string | undefined;
+            region: string;
+            profiles: Record<string, string>;
+            lastProfile: string;
+            accountId: string;
+            name: string;
+            roles: string[];
+            rolesLoaded: boolean;
+        }[];
+        credentials: import("./types").ActiveCredential[];
+        lastSelected: import("./types").LastSelected;
+        lastAccount: string | undefined;
+        lastSession: string | undefined;
+    }>;
+    setProfile(name: string, accountId: string, role: string, profile: string): Promise<{
+        sessions: {
+            authenticated: boolean;
+            name: string;
+            startUrl: string;
+            ssoRegion: string;
+            defaultRegion: string;
+            isChina?: boolean;
+        }[];
+        session: string | undefined;
+        accounts: {
+            preferredRole: string | undefined;
+            region: string;
+            profiles: Record<string, string>;
+            lastProfile: string;
+            accountId: string;
+            name: string;
+            roles: string[];
+            rolesLoaded: boolean;
+        }[];
+        credentials: import("./types").ActiveCredential[];
+        lastSelected: import("./types").LastSelected;
+        lastAccount: string | undefined;
+        lastSession: string | undefined;
+    }>;
+    assumeRole(name: string, accountId: string, role: string): Promise<{
+        sessions: {
+            authenticated: boolean;
+            name: string;
+            startUrl: string;
+            ssoRegion: string;
+            defaultRegion: string;
+            isChina?: boolean;
+        }[];
+        session: string | undefined;
+        accounts: {
+            preferredRole: string | undefined;
+            region: string;
+            profiles: Record<string, string>;
+            lastProfile: string;
+            accountId: string;
+            name: string;
+            roles: string[];
+            rolesLoaded: boolean;
+        }[];
+        credentials: import("./types").ActiveCredential[];
+        lastSelected: import("./types").LastSelected;
+        lastAccount: string | undefined;
+        lastSession: string | undefined;
+    }>;
+    consoleUrl(name: string, accountId?: string, role?: string): Promise<string>;
+    clearCredential(accountId: string, role: string, profile: string, name?: string): Promise<{
+        sessions: {
+            authenticated: boolean;
+            name: string;
+            startUrl: string;
+            ssoRegion: string;
+            defaultRegion: string;
+            isChina?: boolean;
+        }[];
+        session: string | undefined;
+        accounts: {
+            preferredRole: string | undefined;
+            region: string;
+            profiles: Record<string, string>;
+            lastProfile: string;
+            accountId: string;
+            name: string;
+            roles: string[];
+            rolesLoaded: boolean;
+        }[];
+        credentials: import("./types").ActiveCredential[];
+        lastSelected: import("./types").LastSelected;
+        lastAccount: string | undefined;
+        lastSession: string | undefined;
+    }>;
+    clearAllCredentials(name?: string): Promise<{
+        sessions: {
+            authenticated: boolean;
+            name: string;
+            startUrl: string;
+            ssoRegion: string;
+            defaultRegion: string;
+            isChina?: boolean;
+        }[];
+        session: string | undefined;
+        accounts: {
+            preferredRole: string | undefined;
+            region: string;
+            profiles: Record<string, string>;
+            lastProfile: string;
+            accountId: string;
+            name: string;
+            roles: string[];
+            rolesLoaded: boolean;
+        }[];
+        credentials: import("./types").ActiveCredential[];
+        lastSelected: import("./types").LastSelected;
+        lastAccount: string | undefined;
+        lastSession: string | undefined;
+    }>;
+    signOut(name: string): Promise<{
+        sessions: {
+            authenticated: boolean;
+            name: string;
+            startUrl: string;
+            ssoRegion: string;
+            defaultRegion: string;
+            isChina?: boolean;
+        }[];
+        session: string | undefined;
+        accounts: {
+            preferredRole: string | undefined;
+            region: string;
+            profiles: Record<string, string>;
+            lastProfile: string;
+            accountId: string;
+            name: string;
+            roles: string[];
+            rolesLoaded: boolean;
+        }[];
+        credentials: import("./types").ActiveCredential[];
+        lastSelected: import("./types").LastSelected;
+        lastAccount: string | undefined;
+        lastSession: string | undefined;
+    }>;
+};