@work-shape/catalyst-api-client 0.8.0-rc.10 → 0.8.0-rc.11

package/dist/index.d.ts

@@ -25,13 +25,61 @@ interface AuthResult {
     /** The sign-in library's code for a refusal, such as `INVALID_EMAIL_OR_PASSWORD`. */
     code?: string;
     message?: string;
+    /** The HTTP status of a refusal; 429 is the instance's limit on attempts. */
+    status?: number;
+}
+/** The second factor of a sign-in: a code from the authenticator app, or a backup code. */
+type SecondFactorKind = "app" | "backup";
+/** A sign-in: refused, signed in, or waiting for the second factor (TWO-FACTOR-1). */
+interface SignInResult extends AuthResult {
+    /** The password was right and the account asks for a code before there is a session. */
+    secondFactor?: true;
+}
+/** What an authenticator app reads, and the ten backup codes, shown once. */
+interface TwoFactorSetup {
+    totpUri: string;
+    backupCodes: string[];
 }
 declare function getAuthSession(apiBaseUrl: string): Promise<AuthSession | null>;
 declare function signInWithEmail(input: {
     apiBaseUrl: string;
     email: string;
     password: string;
+}): Promise<SignInResult>;
+/**
+ * The second sign-in step: a code from the authenticator app, or a backup code, which signs in
+ * once. `trustBrowser` skips the code in this browser for 30 days from now.
+ */
+declare function verifySecondFactor(input: {
+    apiBaseUrl: string;
+    code: string;
+    kind: SecondFactorKind;
+    trustBrowser?: boolean;
+}): Promise<AuthResult>;
+/**
+ * Starts the setup of two-factor sign-in with the password. The factor is on only after the
+ * first code from the app is confirmed with `verifySecondFactor`.
+ */
+declare function startTwoFactorSetup(input: {
+    apiBaseUrl: string;
+    password: string;
+}): Promise<AuthResult & {
+    setup?: TwoFactorSetup;
+}>;
+/** Turns two-factor sign-in off with the password; every trusted browser is forgotten. */
+declare function turnOffTwoFactor(input: {
+    apiBaseUrl: string;
+    password: string;
 }): Promise<AuthResult>;
+/** Replaces all ten backup codes with the password. The new ones are shown once. */
+declare function regenerateBackupCodes(input: {
+    apiBaseUrl: string;
+    password: string;
+}): Promise<AuthResult & {
+    backupCodes?: string[];
+}>;
+/** Every browser of the person asks for the code again at its next sign-in. */
+declare function forgetTrustedBrowsers(apiBaseUrl: string): Promise<AuthResult>;
 /**
  * For a tool outside a browser, which keeps no cookies: signs in and returns a fetch that
  * carries the session cookie and the origin the instance trusts on every request.
@@ -248,4 +296,4 @@ declare function listAll<Item>(readPage: (paging: {
     nextCursor?: string;
 }>): Promise<Item[]>;
 
-export { AUTH_MOUNT_PATH, type ApiClient, type ApiClientFor, type ApiClientOptions, ApiError, type ApiOperationMethods, ApiResponseShapeError, type AuthResult, type AuthSession, type OperationInput, type OperationOutcome, completedOutput, createApiClient, createApiClientFor, getAuthSession, listAll, refusalError, signInForSessionFetch, signInWithEmail, signOut, transportError, unreadableResponseError };
+export { AUTH_MOUNT_PATH, type ApiClient, type ApiClientFor, type ApiClientOptions, ApiError, type ApiOperationMethods, ApiResponseShapeError, type AuthResult, type AuthSession, type OperationInput, type OperationOutcome, type SecondFactorKind, type SignInResult, type TwoFactorSetup, completedOutput, createApiClient, createApiClientFor, forgetTrustedBrowsers, getAuthSession, listAll, refusalError, regenerateBackupCodes, signInForSessionFetch, signInWithEmail, signOut, startTwoFactorSetup, transportError, turnOffTwoFactor, unreadableResponseError, verifySecondFactor };

package/dist/index.js

@@ -10,6 +10,11 @@ var authFailureSchema = z.object({
   message: z.string().optional(),
   error: z.object({ message: z.string().optional() }).optional()
 });
+var signInAnswerSchema = z.object({ twoFactorRedirect: z.boolean().optional() });
+var twoFactorSetupSchema = z.object({
+  totpURI: z.string(),
+  backupCodes: z.array(z.string())
+});
 async function getAuthSession(apiBaseUrl) {
   const response = await fetch(authUrl(apiBaseUrl, "/get-session"), {
     credentials: "include"
@@ -33,13 +38,64 @@ async function signInWithEmail(input) {
     })
   });
   if (response.ok) {
-    return { ok: true };
+    const answer = signInAnswerSchema.safeParse(await response.json().catch(() => void 0));
+    return answer.data?.twoFactorRedirect === true ? { ok: true, secondFactor: true } : { ok: true };
   }
+  return failureOf(response, "Sign in failed");
+}
+async function verifySecondFactor(input) {
+  const path = input.kind === "app" ? "/two-factor/verify-totp" : "/two-factor/verify-backup-code";
+  const response = await postAuth(input.apiBaseUrl, path, {
+    code: input.code.replaceAll(/\s/gu, ""),
+    trustDevice: input.trustBrowser === true
+  });
+  return response.ok ? { ok: true } : failureOf(response, "The code was not accepted");
+}
+async function startTwoFactorSetup(input) {
+  const response = await postAuth(input.apiBaseUrl, "/two-factor/enable", {
+    password: input.password
+  });
+  if (!response.ok) {
+    return failureOf(response, "Two-factor sign-in could not be set up");
+  }
+  const setup = twoFactorSetupSchema.parse(await response.json());
+  return { ok: true, setup: { totpUri: setup.totpURI, backupCodes: setup.backupCodes } };
+}
+async function turnOffTwoFactor(input) {
+  const response = await postAuth(input.apiBaseUrl, "/two-factor/disable", {
+    password: input.password
+  });
+  return response.ok ? { ok: true } : failureOf(response, "Two-factor sign-in stayed on");
+}
+async function regenerateBackupCodes(input) {
+  const response = await postAuth(input.apiBaseUrl, "/two-factor/generate-backup-codes", {
+    password: input.password
+  });
+  if (!response.ok) {
+    return failureOf(response, "No new backup codes were made");
+  }
+  const { backupCodes } = twoFactorSetupSchema.pick({ backupCodes: true }).parse(await response.json());
+  return { ok: true, backupCodes };
+}
+async function forgetTrustedBrowsers(apiBaseUrl) {
+  const response = await postAuth(apiBaseUrl, "/two-factor/forget-trusted-browsers", {});
+  return response.ok ? { ok: true } : failureOf(response, "The browsers are still trusted");
+}
+function postAuth(apiBaseUrl, path, body) {
+  return fetch(authUrl(apiBaseUrl, path), {
+    method: "POST",
+    credentials: "include",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body)
+  });
+}
+async function failureOf(response, fallback) {
   const failure = authFailureSchema.safeParse(await response.json().catch(() => void 0));
   return {
     ok: false,
+    status: response.status,
     ...failure.data?.code === void 0 ? {} : { code: failure.data.code },
-    message: failure.data?.message ?? failure.data?.error?.message ?? "Sign in failed"
+    message: failure.data?.message ?? failure.data?.error?.message ?? fallback
   };
 }
 async function signInForSessionFetch(input) {
@@ -52,6 +108,12 @@ async function signInForSessionFetch(input) {
   if (!response.ok) {
     throw new Error(`Sign-in as '${input.email}' was refused with status ${response.status}`);
   }
+  const answer = signInAnswerSchema.safeParse(
+    await response.clone().json().catch(() => void 0)
+  );
+  if (answer.data?.twoFactorRedirect === true) {
+    throw new Error(`'${input.email}' signs in with a second factor; use an API key for this tool`);
+  }
   const cookie = response.headers.getSetCookie().map((value) => value.split(";", 1)[0]).join("; ");
   return (resource, init) => {
     const request = new Request(resource, init);
@@ -433,12 +495,17 @@ export {
   completedOutput,
   createApiClient,
   createApiClientFor,
+  forgetTrustedBrowsers,
   getAuthSession,
   listAll,
   refusalError,
+  regenerateBackupCodes,
   signInForSessionFetch,
   signInWithEmail,
   signOut,
+  startTwoFactorSetup,
   transportError,
-  unreadableResponseError
+  turnOffTwoFactor,
+  unreadableResponseError,
+  verifySecondFactor
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@work-shape/catalyst-api-client",
-  "version": "0.8.0-rc.10",
+  "version": "0.8.0-rc.11",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -29,7 +29,7 @@
   },
   "dependencies": {
     "zod": "4.4.3",
-    "@work-shape/catalyst-api-contract": "0.8.0-rc.10"
+    "@work-shape/catalyst-api-contract": "0.8.0-rc.11"
   },
   "devDependencies": {
     "@types/node": "^24.13.1",