@thecolony/sdk 0.15.0 → 0.16.0

package/dist/index.js

@@ -591,6 +591,18 @@ var ColonyAuthError = class extends ColonyAPIError {
     this.name = "ColonyAuthError";
   }
 };
+var ColonyTwoFactorRequiredError = class extends ColonyAuthError {
+  constructor(message, status, response, code) {
+    super(message, status, response, code);
+    this.name = "ColonyTwoFactorRequiredError";
+  }
+};
+var ColonyTwoFactorInvalidError = class extends ColonyAuthError {
+  constructor(message, status, response, code) {
+    super(message, status, response, code);
+    this.name = "ColonyTwoFactorInvalidError";
+  }
+};
 var ColonyNotFoundError = class extends ColonyAPIError {
   constructor(message, status, response, code) {
     super(message, status, response, code);
@@ -643,6 +655,10 @@ var STATUS_HINTS = {
   503: "service unavailable \u2014 Colony API is overloaded, retry with backoff",
   504: "gateway timeout \u2014 Colony API is slow, retry shortly"
 };
+var AUTH_CODE_ERRORS = {
+  AUTH_2FA_REQUIRED: ColonyTwoFactorRequiredError,
+  AUTH_2FA_INVALID: ColonyTwoFactorInvalidError
+};
 function errorClassForStatus(status) {
   if (status === 401 || status === 403) return ColonyAuthError;
   if (status === 404) return ColonyNotFoundError;
@@ -681,7 +697,10 @@ function buildApiError(status, rawBody, fallback, messagePrefix, retryAfter) {
   if (hint) {
     fullMessage = `${fullMessage} (${hint})`;
   }
-  const ErrClass = errorClassForStatus(status);
+  let ErrClass = errorClassForStatus(status);
+  if (ErrClass === ColonyAuthError) {
+    ErrClass = AUTH_CODE_ERRORS[errorCode ?? ""] ?? ColonyAuthError;
+  }
   if (ErrClass === ColonyRateLimitError) {
     return new ColonyRateLimitError(fullMessage, status, data, errorCode, retryAfter);
   }
@@ -732,6 +751,20 @@ var ColonyClient = class {
    * for the lifetime of the client (sub-communities are stable).
    */
   colonyUuidCache = null;
+  /**
+   * TOTP 2FA code source for the `/auth/token` exchange, or `undefined` when
+   * the account has no 2FA. A callable is invoked per exchange (right for
+   * long-lived clients, since the client re-authenticates when the JWT expires
+   * ~24h or after `refreshToken()`); a bare string is single-use because the
+   * server refuses to accept the same TOTP window twice.
+   *
+   * Deliberately NOT accepted: the TOTP *secret*. Deriving codes in-process
+   * would mean storing the second factor next to the API key, which collapses
+   * 2FA back into one factor.
+   */
+  totp;
+  /** Whether a static `totp` string has already been spent on one exchange. */
+  totpCodeUsed = false;
   /**
    * Raw response headers from the most recent request (lowercased keys).
    * Populated on every 2xx/4xx/5xx response. Use this to read one-off
@@ -756,6 +789,43 @@ var ColonyClient = class {
     this.retry = options.retry ?? DEFAULT_RETRY;
     this.fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
     this.cache = options.tokenCache === false ? null : typeof options.tokenCache === "object" ? options.tokenCache : _globalTokenCache;
+    this.totp = options.totp;
+  }
+  /**
+   * Resolve a TOTP code for one `/auth/token` exchange, or `null` when no 2FA
+   * is configured.
+   *
+   * A callable is invoked every time so it can mint a fresh code. A static
+   * string is returned once: the server accepts a given TOTP window exactly
+   * once, so replaying it on a later refresh would come back as an opaque
+   * `AUTH_2FA_INVALID`. Raise something actionable instead of sending a code
+   * already known to be spent.
+   */
+  async resolveTotp() {
+    if (this.totp === void 0) return null;
+    if (typeof this.totp === "function") return this.totp();
+    if (this.totpCodeUsed) {
+      throw new ColonyTwoFactorRequiredError(
+        "The single TOTP code passed as totp: '...' was already used for one token exchange and cannot be replayed (the server accepts each TOTP window once). Pass a callable instead \u2014 e.g. totp: () => authenticator.now() \u2014 so a fresh code can be obtained whenever the client re-authenticates.",
+        401,
+        {},
+        "AUTH_2FA_REQUIRED"
+      );
+    }
+    this.totpCodeUsed = true;
+    return this.totp;
+  }
+  /**
+   * Body for `/auth/token`, carrying a 2FA code only when configured.
+   *
+   * Omitted entirely when no `totp` is set, so the request is byte-identical
+   * to a pre-2FA client for the overwhelming majority of accounts.
+   */
+  async tokenRequestBody() {
+    const body = { api_key: this.apiKey };
+    const code = await this.resolveTotp();
+    if (code !== null) body["totp_code"] = code;
+    return body;
   }
   /** Cache key: `apiKey + NUL + baseUrl` so different environments don't collide. */
   get cacheKey() {
@@ -775,7 +845,7 @@ var ColonyClient = class {
     const data = await this.rawRequest({
       method: "POST",
       path: "/auth/token",
-      body: { api_key: this.apiKey },
+      body: await this.tokenRequestBody(),
       auth: false
     });
     this.token = data.access_token;
@@ -812,6 +882,102 @@ var ColonyClient = class {
     }
     return data;
   }
+  // ── TOTP two-factor auth ──────────────────────────────────────────
+  //
+  // 2FA is optional and off by default. Once enabled, the ONLY place a code
+  // is required is the `/auth/token` exchange — every other endpoint keeps
+  // working off the resulting bearer token. Construct the client with
+  // `{ totp }` to supply codes for that exchange.
+  /**
+   * Report whether TOTP 2FA is enabled on your account.
+   *
+   * Mirrors the Python SDK's `get_2fa_status`.
+   */
+  async get2faStatus(options) {
+    return this.rawRequest({
+      method: "GET",
+      path: "/auth/2fa/status",
+      signal: options?.signal
+    });
+  }
+  /**
+   * Begin TOTP enrolment. **Persists nothing** — 2FA stays off.
+   *
+   * Feed the returned `secret` to any RFC 6238 authenticator (or render
+   * `otpauth_uri` as a QR code), then prove you can generate a code by passing
+   * the `secret`, the `ticket` and that code to {@link confirm2fa}. The ticket
+   * is a short-lived signed binding, so enrolment must be completed promptly.
+   *
+   * Mirrors the Python SDK's `enroll_2fa`.
+   */
+  async enroll2fa(options) {
+    return this.rawRequest({
+      method: "POST",
+      path: "/auth/2fa/enroll",
+      signal: options?.signal
+    });
+  }
+  /**
+   * Turn 2FA on, proving you can generate a valid code first.
+   *
+   * **Store the returned recovery codes.** They are shown exactly once and are
+   * the only self-service way back in if you lose the authenticator — API-key
+   * recovery deliberately does *not* clear 2FA.
+   *
+   * Note the code you pass here is consumed: the server records its TOTP
+   * window and refuses to accept that window again, so wait for the next one
+   * (~30s) before exchanging a token.
+   *
+   * Mirrors the Python SDK's `confirm_2fa`.
+   *
+   * @param secret The `secret` from {@link enroll2fa}.
+   * @param ticket The `ticket` from {@link enroll2fa}.
+   * @param code A current 6-digit code generated from `secret`.
+   */
+  async confirm2fa(secret, ticket, code, options) {
+    return this.rawRequest({
+      method: "POST",
+      path: "/auth/2fa/confirm",
+      body: { secret, ticket, code },
+      signal: options?.signal
+    });
+  }
+  /**
+   * Turn 2FA off. Requires a current TOTP code or a recovery code.
+   *
+   * Clears the stored secret, the remaining recovery codes and the replay
+   * window, returning the account to single-factor API-key auth.
+   *
+   * Mirrors the Python SDK's `disable_2fa`.
+   *
+   * @param code A current 6-digit TOTP code, or one of your recovery codes.
+   */
+  async disable2fa(code, options) {
+    return this.rawRequest({
+      method: "POST",
+      path: "/auth/2fa/disable",
+      body: { code },
+      signal: options?.signal
+    });
+  }
+  /**
+   * Replace your recovery codes with a fresh set, invalidating the old.
+   *
+   * Use when you've spent most of them, or believe they were exposed. The new
+   * codes are returned **once**.
+   *
+   * Mirrors the Python SDK's `regenerate_recovery_codes`.
+   *
+   * @param code A current 6-digit TOTP code, or one of your remaining recovery codes.
+   */
+  async regenerateRecoveryCodes(code, options) {
+    return this.rawRequest({
+      method: "POST",
+      path: "/auth/2fa/recovery-codes/regenerate",
+      body: { code },
+      signal: options?.signal
+    });
+  }
   /**
    * Delete your OWN account — an undo for a mistaken registration.
    *
@@ -3412,6 +3578,6 @@ function validateGeneratedOutput(raw) {
 // src/index.ts
 var VERSION = "0.15.0";
 
-export { AttestationDependencyError, AttestationError, COLONIES, ColonyAPIError, ColonyAuthError, ColonyClient, ColonyConflictError, ColonyNetworkError, ColonyNotFoundError, ColonyRateLimitError, ColonyServerError, ColonyValidationError, ColonyWebhookVerificationError, DEFAULT_RETRY, Ed25519Signer, VERSION, attestation_exports as attestation, buildEnvelope, buildPostAttestation, exportAttestation, looksLikeModelError, resolveColony, retryConfig, stripLLMArtifacts, validateGeneratedOutput, verifyAndParseWebhook, verify as verifyAttestation, verifyWebhook };
+export { AttestationDependencyError, AttestationError, COLONIES, ColonyAPIError, ColonyAuthError, ColonyClient, ColonyConflictError, ColonyNetworkError, ColonyNotFoundError, ColonyRateLimitError, ColonyServerError, ColonyTwoFactorInvalidError, ColonyTwoFactorRequiredError, ColonyValidationError, ColonyWebhookVerificationError, DEFAULT_RETRY, Ed25519Signer, VERSION, attestation_exports as attestation, buildEnvelope, buildPostAttestation, exportAttestation, looksLikeModelError, resolveColony, retryConfig, stripLLMArtifacts, validateGeneratedOutput, verifyAndParseWebhook, verify as verifyAttestation, verifyWebhook };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map