@cboxdk/id-js 0.18.0 → 0.19.0

package/dist/{client-BxUHm5hX.d.cts → client-BT-jOm0p.d.cts}

@@ -1,4 +1,5 @@
-import { a as CboxIdConfig, A as AuthorizationRequestOptions, b as AuthorizationRequest, C as CboxUser, D as DeviceAuthorization, R as RefreshedTokens, T as TokenTypeHint } from './types-BYZldock.cjs';
+import { C as CboxIdError } from './errors-D61xljZE.cjs';
+import { a as CboxIdConfig, A as AuthorizationRequestOptions, b as AuthorizationRequest, C as CboxUser, D as DeviceAuthorization, R as RefreshedTokens, T as TokenTypeHint } from './types-CC1bz68x.cjs';
 
 /** A stored vault secret's metadata (never its plaintext). */
 interface VaultSecretRef {
@@ -17,6 +18,98 @@ interface VaultLease {
     secret: string;
     expiresAt: string;
 }
+/** A provider a pipe can connect to. */
+type PipeProvider = 'github' | 'google' | 'microsoft' | 'slack' | 'salesforce' | 'hubspot' | 'linear' | 'notion';
+/**
+ * A fresh access token for one person's connected account at a provider — what
+ * {@link VaultClient.leasePipeToken} returns. Use it, drop it, lease again next time.
+ */
+interface PipeToken {
+    /** The provider's access token. Send it as a bearer token to the provider's API. */
+    accessToken: string;
+    tokenType: 'Bearer';
+    provider: string;
+    userId: string;
+    connectionId: string;
+    /** What the person consented to. */
+    scopes: string[];
+    /** When the PROVIDER stops accepting it; null for tokens that do not expire. */
+    expiresAt: string | null;
+    /** When to drop it and lease again. */
+    leaseExpiresAt: string;
+    /** What some providers need to be called at all — Salesforce's `instance_url`, Slack's `team.id`. */
+    metadata: Record<string, string>;
+}
+/** Where a person connects a provider, and where they come back to afterwards. */
+interface PipeConnectOptions {
+    /** Your app's client id — the connect page shows its name and allows its origins. */
+    clientId?: string;
+    /**
+     * Where to land afterwards, with `?provider=…&status=connected|cancelled|failed`. Must be
+     * on one of the app's registered redirect origins, or it is ignored.
+     */
+    returnTo?: string;
+}
+/**
+ * Add `client_id` and `return_to` to a connect URL — the one a lease error carries, or
+ * one built with {@link pipeConnectUrl}.
+ */
+declare function withConnectReturn(connectUrl: string, options?: PipeConnectOptions): string;
+/**
+ * The hosted page where the signed-in person connects their account at `provider`:
+ * `{issuer}/account/connected-services/{provider}/connect?client_id=…&return_to=…`.
+ */
+declare function pipeConnectUrl(issuer: string, provider: PipeProvider | string, options?: PipeConnectOptions): string;
+/**
+ * A pipe token lease was refused. Catch the subclasses for the cases you can act on:
+ *
+ *  - {@link PipeNotConnectedError} (404) and {@link PipeReauthorizationRequiredError}
+ *    (409) — send the person to `connectUrl`.
+ *  - {@link PipeTemporarilyUnavailableError} (503) — retry after `retryAfter` seconds.
+ *  - {@link PipeLeaseDeniedError} (403) — a configuration problem: the app is not granted
+ *    the pipe, it is disabled, or the person is outside the app's organization.
+ *
+ * Anything else (401, 422, 429) arrives as this base class with `status` and `error`.
+ */
+declare class PipeLeaseError extends CboxIdError {
+    /** The server's error code, e.g. `not_connected`. */
+    readonly error: string | null;
+    readonly status: number;
+    /** Where to send the person to (re)connect — set on 404 and 409. */
+    readonly connectUrl: string | null;
+    /** Seconds to wait off `Retry-After`, when the server sent one. */
+    readonly retryAfter: number | null;
+    constructor(message: string, 
+    /** The server's error code, e.g. `not_connected`. */
+    error: string | null, status: number, 
+    /** Where to send the person to (re)connect — set on 404 and 409. */
+    connectUrl?: string | null, 
+    /** Seconds to wait off `Retry-After`, when the server sent one. */
+    retryAfter?: number | null);
+    /** `connectUrl` with your `client_id` and `return_to` on it, or null when there is none. */
+    connectUrlWith(options: PipeConnectOptions): string | null;
+}
+/** The person has not connected this provider (404 `not_connected`). Send them to `connectUrl`. */
+declare class PipeNotConnectedError extends PipeLeaseError {
+    readonly connectUrl: string;
+}
+/**
+ * The provider stopped accepting the connection — revoked, or the refresh token expired
+ * (409 `reauthorization_required`). Send the person to `connectUrl` to connect again.
+ */
+declare class PipeReauthorizationRequiredError extends PipeLeaseError {
+    readonly connectUrl: string;
+}
+/** The provider could not refresh the token just now (503). Retry after `retryAfter`. */
+declare class PipeTemporarilyUnavailableError extends PipeLeaseError {
+}
+/**
+ * The lease was denied (403 `lease_denied`): the app is not granted the pipe, the pipe is
+ * disabled or missing, the person is not in the app's organization, or `userId` names
+ * someone other than the token's person. One answer for every reason, by design.
+ */
+declare class PipeLeaseDeniedError extends PipeLeaseError {
+}
 interface StoreSecretInput {
     name: string;
     provider: string;
@@ -54,8 +147,32 @@ declare class VaultClient {
      * is identified by the token's client; a lease with no live grant is refused.
      */
     lease(secretId: string, purpose: string): Promise<VaultLease>;
+    /**
+     * Lease a fresh access token for a person's connected account at `provider` (Pipes,
+     * scope `vault.lease`). The token is refreshed first when it is about to expire, so
+     * you never handle a refresh token.
+     *
+     * With a client-credentials token, name the person in `userId`. With a token issued to
+     * your app FOR a person, leave it out — the lease is theirs.
+     *
+     * ```ts
+     * try {
+     *   const { accessToken } = await vault.leasePipeToken('github', { userId, purpose: 'list-repos' })
+     * } catch (e) {
+     *   if (e instanceof PipeNotConnectedError || e instanceof PipeReauthorizationRequiredError) {
+     *     return redirect(e.connectUrlWith({ clientId, returnTo }))
+     *   }
+     *   throw e
+     * }
+     * ```
+     */
+    leasePipeToken(provider: PipeProvider | string, options: {
+        purpose: string;
+        userId?: string;
+    }): Promise<PipeToken>;
     private json;
     private request;
+    private send;
 }
 
 /**
@@ -259,6 +376,13 @@ declare class CboxIdClient {
      * registered. `organization` picks which of the person's organizations the keys act in;
      * omitted, the page uses the one they are in.
      */
+    /**
+     * The hosted page where the signed-in person connects their account at `provider`
+     * (Pipes) — `/account/connected-services/{provider}/connect`, preselected to this app.
+     * They come back to `returnTo` with `?provider=…&status=connected|cancelled|failed`,
+     * honoured only on an origin the app registered.
+     */
+    pipeConnectUrl(provider: PipeProvider | string, returnTo?: string): string;
     apiKeysUrl(options?: {
         clientId?: string;
         returnTo?: string;
@@ -338,4 +462,4 @@ declare class CboxIdClient {
     private fetchWithTimeout;
 }
 
-export { CboxIdClient as C, type StoreSecretInput as S, VaultClient as V, type WebhookHeaders as W, type CallbackParams as a, type StoredAuthState as b, type VaultLease as c, type VaultSecretRef as d, type VerifyStandardWebhookOptions as e, type VerifyWebhookOptions as f, verifyWebhook as g, verifyStandardWebhook as v };
+export { CboxIdClient as C, type PipeConnectOptions as P, type StoreSecretInput as S, VaultClient as V, type WebhookHeaders as W, type CallbackParams as a, PipeLeaseDeniedError as b, PipeLeaseError as c, PipeNotConnectedError as d, type PipeProvider as e, PipeReauthorizationRequiredError as f, PipeTemporarilyUnavailableError as g, type PipeToken as h, type StoredAuthState as i, type VaultLease as j, type VaultSecretRef as k, type VerifyStandardWebhookOptions as l, type VerifyWebhookOptions as m, verifyWebhook as n, pipeConnectUrl as p, verifyStandardWebhook as v, withConnectReturn as w };

package/dist/{client-BSZASrMo.d.ts → client-xlEJalu8.d.ts}

@@ -1,4 +1,5 @@
-import { a as CboxIdConfig, A as AuthorizationRequestOptions, b as AuthorizationRequest, C as CboxUser, D as DeviceAuthorization, R as RefreshedTokens, T as TokenTypeHint } from './types-BYZldock.js';
+import { C as CboxIdError } from './errors-D61xljZE.js';
+import { a as CboxIdConfig, A as AuthorizationRequestOptions, b as AuthorizationRequest, C as CboxUser, D as DeviceAuthorization, R as RefreshedTokens, T as TokenTypeHint } from './types-CC1bz68x.js';
 
 /** A stored vault secret's metadata (never its plaintext). */
 interface VaultSecretRef {
@@ -17,6 +18,98 @@ interface VaultLease {
     secret: string;
     expiresAt: string;
 }
+/** A provider a pipe can connect to. */
+type PipeProvider = 'github' | 'google' | 'microsoft' | 'slack' | 'salesforce' | 'hubspot' | 'linear' | 'notion';
+/**
+ * A fresh access token for one person's connected account at a provider — what
+ * {@link VaultClient.leasePipeToken} returns. Use it, drop it, lease again next time.
+ */
+interface PipeToken {
+    /** The provider's access token. Send it as a bearer token to the provider's API. */
+    accessToken: string;
+    tokenType: 'Bearer';
+    provider: string;
+    userId: string;
+    connectionId: string;
+    /** What the person consented to. */
+    scopes: string[];
+    /** When the PROVIDER stops accepting it; null for tokens that do not expire. */
+    expiresAt: string | null;
+    /** When to drop it and lease again. */
+    leaseExpiresAt: string;
+    /** What some providers need to be called at all — Salesforce's `instance_url`, Slack's `team.id`. */
+    metadata: Record<string, string>;
+}
+/** Where a person connects a provider, and where they come back to afterwards. */
+interface PipeConnectOptions {
+    /** Your app's client id — the connect page shows its name and allows its origins. */
+    clientId?: string;
+    /**
+     * Where to land afterwards, with `?provider=…&status=connected|cancelled|failed`. Must be
+     * on one of the app's registered redirect origins, or it is ignored.
+     */
+    returnTo?: string;
+}
+/**
+ * Add `client_id` and `return_to` to a connect URL — the one a lease error carries, or
+ * one built with {@link pipeConnectUrl}.
+ */
+declare function withConnectReturn(connectUrl: string, options?: PipeConnectOptions): string;
+/**
+ * The hosted page where the signed-in person connects their account at `provider`:
+ * `{issuer}/account/connected-services/{provider}/connect?client_id=…&return_to=…`.
+ */
+declare function pipeConnectUrl(issuer: string, provider: PipeProvider | string, options?: PipeConnectOptions): string;
+/**
+ * A pipe token lease was refused. Catch the subclasses for the cases you can act on:
+ *
+ *  - {@link PipeNotConnectedError} (404) and {@link PipeReauthorizationRequiredError}
+ *    (409) — send the person to `connectUrl`.
+ *  - {@link PipeTemporarilyUnavailableError} (503) — retry after `retryAfter` seconds.
+ *  - {@link PipeLeaseDeniedError} (403) — a configuration problem: the app is not granted
+ *    the pipe, it is disabled, or the person is outside the app's organization.
+ *
+ * Anything else (401, 422, 429) arrives as this base class with `status` and `error`.
+ */
+declare class PipeLeaseError extends CboxIdError {
+    /** The server's error code, e.g. `not_connected`. */
+    readonly error: string | null;
+    readonly status: number;
+    /** Where to send the person to (re)connect — set on 404 and 409. */
+    readonly connectUrl: string | null;
+    /** Seconds to wait off `Retry-After`, when the server sent one. */
+    readonly retryAfter: number | null;
+    constructor(message: string, 
+    /** The server's error code, e.g. `not_connected`. */
+    error: string | null, status: number, 
+    /** Where to send the person to (re)connect — set on 404 and 409. */
+    connectUrl?: string | null, 
+    /** Seconds to wait off `Retry-After`, when the server sent one. */
+    retryAfter?: number | null);
+    /** `connectUrl` with your `client_id` and `return_to` on it, or null when there is none. */
+    connectUrlWith(options: PipeConnectOptions): string | null;
+}
+/** The person has not connected this provider (404 `not_connected`). Send them to `connectUrl`. */
+declare class PipeNotConnectedError extends PipeLeaseError {
+    readonly connectUrl: string;
+}
+/**
+ * The provider stopped accepting the connection — revoked, or the refresh token expired
+ * (409 `reauthorization_required`). Send the person to `connectUrl` to connect again.
+ */
+declare class PipeReauthorizationRequiredError extends PipeLeaseError {
+    readonly connectUrl: string;
+}
+/** The provider could not refresh the token just now (503). Retry after `retryAfter`. */
+declare class PipeTemporarilyUnavailableError extends PipeLeaseError {
+}
+/**
+ * The lease was denied (403 `lease_denied`): the app is not granted the pipe, the pipe is
+ * disabled or missing, the person is not in the app's organization, or `userId` names
+ * someone other than the token's person. One answer for every reason, by design.
+ */
+declare class PipeLeaseDeniedError extends PipeLeaseError {
+}
 interface StoreSecretInput {
     name: string;
     provider: string;
@@ -54,8 +147,32 @@ declare class VaultClient {
      * is identified by the token's client; a lease with no live grant is refused.
      */
     lease(secretId: string, purpose: string): Promise<VaultLease>;
+    /**
+     * Lease a fresh access token for a person's connected account at `provider` (Pipes,
+     * scope `vault.lease`). The token is refreshed first when it is about to expire, so
+     * you never handle a refresh token.
+     *
+     * With a client-credentials token, name the person in `userId`. With a token issued to
+     * your app FOR a person, leave it out — the lease is theirs.
+     *
+     * ```ts
+     * try {
+     *   const { accessToken } = await vault.leasePipeToken('github', { userId, purpose: 'list-repos' })
+     * } catch (e) {
+     *   if (e instanceof PipeNotConnectedError || e instanceof PipeReauthorizationRequiredError) {
+     *     return redirect(e.connectUrlWith({ clientId, returnTo }))
+     *   }
+     *   throw e
+     * }
+     * ```
+     */
+    leasePipeToken(provider: PipeProvider | string, options: {
+        purpose: string;
+        userId?: string;
+    }): Promise<PipeToken>;
     private json;
     private request;
+    private send;
 }
 
 /**
@@ -259,6 +376,13 @@ declare class CboxIdClient {
      * registered. `organization` picks which of the person's organizations the keys act in;
      * omitted, the page uses the one they are in.
      */
+    /**
+     * The hosted page where the signed-in person connects their account at `provider`
+     * (Pipes) — `/account/connected-services/{provider}/connect`, preselected to this app.
+     * They come back to `returnTo` with `?provider=…&status=connected|cancelled|failed`,
+     * honoured only on an origin the app registered.
+     */
+    pipeConnectUrl(provider: PipeProvider | string, returnTo?: string): string;
     apiKeysUrl(options?: {
         clientId?: string;
         returnTo?: string;
@@ -338,4 +462,4 @@ declare class CboxIdClient {
     private fetchWithTimeout;
 }
 
-export { CboxIdClient as C, type StoreSecretInput as S, VaultClient as V, type WebhookHeaders as W, type CallbackParams as a, type StoredAuthState as b, type VaultLease as c, type VaultSecretRef as d, type VerifyStandardWebhookOptions as e, type VerifyWebhookOptions as f, verifyWebhook as g, verifyStandardWebhook as v };
+export { CboxIdClient as C, type PipeConnectOptions as P, type StoreSecretInput as S, VaultClient as V, type WebhookHeaders as W, type CallbackParams as a, PipeLeaseDeniedError as b, PipeLeaseError as c, PipeNotConnectedError as d, type PipeProvider as e, PipeReauthorizationRequiredError as f, PipeTemporarilyUnavailableError as g, type PipeToken as h, type StoredAuthState as i, type VaultLease as j, type VaultSecretRef as k, type VerifyStandardWebhookOptions as l, type VerifyWebhookOptions as m, verifyWebhook as n, pipeConnectUrl as p, verifyStandardWebhook as v, withConnectReturn as w };

package/dist/index.cjs

@@ -174,6 +174,7 @@ function assertSecureIssuer(issuer) {
 }
 
 // src/frontend.ts
+var SECOND_FACTOR_KINDS = /* @__PURE__ */ new Set(["totp", "sms", "recovery_code"]);
 var CboxIdFrontend = class {
   issuer;
   publishableKey;
@@ -188,7 +189,7 @@ var CboxIdFrontend = class {
    * fetches of the same immutable document is a waste the SDK should absorb rather than
    * ask every consumer to.
    */
-  configPromise = null;
+  configPromises = /* @__PURE__ */ new Map();
   constructor(options) {
     if (!options.issuer) {
       throw new ConfigurationError("issuer is required.");
@@ -215,13 +216,20 @@ var CboxIdFrontend = class {
    * Fetched once per client instance. The document is small and changes when somebody
    * edits it in the console, so a long-lived page picks changes up on its next full load
    * rather than mid-session — which is the right trade for something that decides layout.
+   * Each `organization` is fetched and cached on its own.
    */
-  async config() {
-    this.configPromise ??= this.get("/frontend/v1/config", {}, isFrontendConfig).catch((error) => {
-      this.configPromise = null;
-      throw error;
-    });
-    return this.configPromise;
+  async config(options = {}) {
+    const organization2 = options.organization ?? "";
+    let pending = this.configPromises.get(organization2);
+    if (pending === void 0) {
+      const path = organization2 === "" ? "/frontend/v1/config" : `/frontend/v1/config?${new URLSearchParams({ organization: organization2 }).toString()}`;
+      pending = this.get(path, {}, isFrontendConfig).catch((error) => {
+        this.configPromises.delete(organization2);
+        throw error;
+      });
+      this.configPromises.set(organization2, pending);
+    }
+    return pending;
   }
   /**
    * Who is signed in, given an access token your app already holds.
@@ -283,8 +291,12 @@ var CboxIdFrontend = class {
     if (body.status === "ok" && typeof body.login_ticket === "string") {
       return { status: "ok", loginTicket: body.login_ticket, expiresIn: body.expires_in ?? 60 };
     }
-    if ((body.status === "mfa_required" || body.status === "otp_required") && typeof body.mfa_token === "string") {
-      return { status: body.status, mfaToken: body.mfa_token };
+    if (body.status === "mfa_required" && typeof body.mfa_token === "string") {
+      const factors = Array.isArray(body.factors) ? body.factors.filter((f) => typeof f === "string" && SECOND_FACTOR_KINDS.has(f)) : void 0;
+      return { status: "mfa_required", mfaToken: body.mfa_token, ...factors ? { factors } : {} };
+    }
+    if (body.status === "otp_required" && typeof body.mfa_token === "string") {
+      return { status: "otp_required", mfaToken: body.mfa_token };
     }
     if (body.status === "sso_required") {
       return { status: "sso_required" };
@@ -301,6 +313,11 @@ var CboxIdFrontend = class {
    *
    * A wrong code costs an attempt, not the sign-in: five are allowed before the token
    * dies and the person starts from the password again.
+   *
+   * `method` says which challenge the code answers: `'mfa'` for an authenticator or
+   * recovery code, `'otp'` for an emailed code (`otp_required`), `'sms'` for a code sent
+   * with {@link sendSmsCode}. A texted code is six digits like an authenticator's, so the
+   * server cannot tell them apart by shape — answering one as the other is refused.
    */
   async submitSecondFactor(mfaToken, code, method = "mfa") {
     const response = await this.post("/frontend/v1/sign-in/factor", { mfa_token: mfaToken, code, method });
@@ -312,6 +329,41 @@ var CboxIdFrontend = class {
     }
     return body.status === "ok" && typeof body.login_ticket === "string" ? { status: "ok", loginTicket: body.login_ticket, expiresIn: body.expires_in ?? 60 } : { status: "invalid" };
   }
+  /**
+   * Text the person a sign-in code, when `mfa_required` listed `'sms'` in `factors`.
+   * Then finish with `submitSecondFactor(mfaToken, code, 'sms')`.
+   *
+   * Only call it when the person asks ("Text me a code"), never on page load: each send
+   * spends one of the token's five attempts — that is what bounds how many texts one
+   * proved password can cause — and every text costs the customer money.
+   *
+   * ```ts
+   * if (result.status === 'mfa_required' && result.factors?.includes('sms')) {
+   *   const sent = await frontend.sendSmsCode(result.mfaToken)
+   *   if (sent.status === 'sent') showCodeField(`We texted ${sent.to}`)
+   * }
+   * ```
+   */
+  async sendSmsCode(mfaToken) {
+    const response = await this.post("/frontend/v1/sign-in/factor/sms", { mfa_token: mfaToken });
+    let body;
+    try {
+      body = await response.json();
+    } catch {
+      throw new FrontendApiError("Cbox ID returned a body that is not JSON.", "malformed", response.status);
+    }
+    if (body.status === "sent" && typeof body.to === "string") {
+      return { status: "sent", to: body.to, expiresIn: typeof body.expires_in === "number" ? body.expires_in : 300 };
+    }
+    if (body.status === "rate_limited" || response.status === 429) {
+      const retryAfter = typeof body.retry_after === "number" ? body.retry_after : Number(response.headers.get("Retry-After") ?? "");
+      return { status: "rate_limited", retryAfter: Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : void 0 };
+    }
+    if (body.status === "unavailable") {
+      return { status: "unavailable" };
+    }
+    return { status: "invalid" };
+  }
   /**
    * The WebAuthn options for a passkey sign-in, and the handle that carries the challenge.
    *
@@ -607,6 +659,14 @@ function hasRole(source, role) {
 function hasPermission(source, permission) {
   return permissions(source).includes(permission);
 }
+var FEATURE_FLAGS_SCOPE = "feature_flags";
+function featureFlags(source) {
+  const claim = claimsOf(source)["feature_flags"];
+  return Array.isArray(claim) ? stringList(claim) : null;
+}
+function hasFeature(source, key) {
+  return featureFlags(source)?.includes(key) ?? false;
+}
 var MAX_ACTOR_DEPTH = 8;
 function parseActor(claim, depth) {
   if (claim === void 0 || claim === null) {
@@ -633,6 +693,43 @@ function isUser(source) {
 }
 
 // src/vault.ts
+function withConnectReturn(connectUrl, options = {}) {
+  const url = new URL(connectUrl);
+  if (options.clientId) url.searchParams.set("client_id", options.clientId);
+  if (options.returnTo) url.searchParams.set("return_to", options.returnTo);
+  return url.toString();
+}
+function pipeConnectUrl(issuer, provider, options = {}) {
+  return withConnectReturn(
+    `${issuer.replace(/\/$/, "")}/account/connected-services/${encodeURIComponent(provider)}/connect`,
+    options
+  );
+}
+var PipeLeaseError = class extends CboxIdError {
+  constructor(message, error, status, connectUrl = null, retryAfter = null) {
+    super(message);
+    this.error = error;
+    this.status = status;
+    this.connectUrl = connectUrl;
+    this.retryAfter = retryAfter;
+  }
+  error;
+  status;
+  connectUrl;
+  retryAfter;
+  /** `connectUrl` with your `client_id` and `return_to` on it, or null when there is none. */
+  connectUrlWith(options) {
+    return this.connectUrl === null ? null : withConnectReturn(this.connectUrl, options);
+  }
+};
+var PipeNotConnectedError = class extends PipeLeaseError {
+};
+var PipeReauthorizationRequiredError = class extends PipeLeaseError {
+};
+var PipeTemporarilyUnavailableError = class extends PipeLeaseError {
+};
+var PipeLeaseDeniedError = class extends PipeLeaseError {
+};
 var VaultClient = class {
   constructor(issuer, token, timeoutMs = 1e4) {
     this.token = token;
@@ -688,11 +785,69 @@ var VaultClient = class {
       return { secretId: r.secret_id, provider: r.provider, secret: r.secret, expiresAt: r.expires_at };
     });
   }
+  /**
+   * Lease a fresh access token for a person's connected account at `provider` (Pipes,
+   * scope `vault.lease`). The token is refreshed first when it is about to expire, so
+   * you never handle a refresh token.
+   *
+   * With a client-credentials token, name the person in `userId`. With a token issued to
+   * your app FOR a person, leave it out — the lease is theirs.
+   *
+   * ```ts
+   * try {
+   *   const { accessToken } = await vault.leasePipeToken('github', { userId, purpose: 'list-repos' })
+   * } catch (e) {
+   *   if (e instanceof PipeNotConnectedError || e instanceof PipeReauthorizationRequiredError) {
+   *     return redirect(e.connectUrlWith({ clientId, returnTo }))
+   *   }
+   *   throw e
+   * }
+   * ```
+   */
+  async leasePipeToken(provider, options) {
+    const path = `/pipes/${encodeURIComponent(provider)}/token`;
+    const response = await this.send("POST", path, {
+      purpose: options.purpose,
+      ...options.userId !== void 0 ? { user_id: options.userId } : {}
+    });
+    let body = {};
+    try {
+      const parsed = await response.json();
+      if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+        body = parsed;
+      }
+    } catch {
+    }
+    if (!response.ok) {
+      throw pipeLeaseError(response, body);
+    }
+    if (typeof body.access_token !== "string") {
+      throw new PipeLeaseError("The pipe lease answered without an access token.", null, response.status);
+    }
+    return {
+      accessToken: body.access_token,
+      tokenType: "Bearer",
+      provider: String(body.provider ?? provider),
+      userId: String(body.user_id ?? ""),
+      connectionId: String(body.connection_id ?? ""),
+      scopes: Array.isArray(body.scopes) ? body.scopes.filter((s) => typeof s === "string") : [],
+      expiresAt: typeof body.expires_at === "string" ? body.expires_at : null,
+      leaseExpiresAt: String(body.lease_expires_at ?? ""),
+      metadata: isStringRecord(body.metadata) ? body.metadata : {}
+    };
+  }
   async json(method, path, body) {
     const response = await this.request(method, path, body);
     return await response.json();
   }
   async request(method, path, body) {
+    const response = await this.send(method, path, body);
+    if (!response.ok) {
+      throw new AuthenticationError(`Vault ${method} ${path} failed with status ${response.status}.`);
+    }
+    return response;
+  }
+  async send(method, path, body) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), this.timeoutMs);
     try {
@@ -707,16 +862,35 @@ var VaultClient = class {
       if (body) {
         init.body = JSON.stringify(body);
       }
-      const response = await fetch(`${this.base}${path}`, init);
-      if (!response.ok) {
-        throw new AuthenticationError(`Vault ${method} ${path} failed with status ${response.status}.`);
-      }
-      return response;
+      return await fetch(`${this.base}${path}`, init);
     } finally {
       clearTimeout(timer);
     }
   }
 };
+function pipeLeaseError(response, body) {
+  const error = typeof body.error === "string" ? body.error : null;
+  const message = typeof body.message === "string" && body.message !== "" ? body.message : `The pipe lease failed with status ${response.status}.`;
+  const connectUrl = typeof body.connect_url === "string" && body.connect_url !== "" ? body.connect_url : null;
+  const header2 = response.headers.get("retry-after")?.trim() ?? "";
+  const retryAfter = /^\d+$/.test(header2) ? Number(header2) : null;
+  if (response.status === 404 && connectUrl !== null) {
+    return new PipeNotConnectedError(message, error, 404, connectUrl, retryAfter);
+  }
+  if (response.status === 409 && connectUrl !== null) {
+    return new PipeReauthorizationRequiredError(message, error, 409, connectUrl, retryAfter);
+  }
+  if (response.status === 503) {
+    return new PipeTemporarilyUnavailableError(message, error, 503, connectUrl, retryAfter);
+  }
+  if (response.status === 403 && error !== "insufficient_scope") {
+    return new PipeLeaseDeniedError(message, error, 403, connectUrl, retryAfter);
+  }
+  return new PipeLeaseError(message, error, response.status, connectUrl, retryAfter);
+}
+function isStringRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && Object.values(value).every((v) => typeof v === "string");
+}
 
 // src/webhook.ts
 function timingSafeEqual2(a, b) {
@@ -986,6 +1160,7 @@ var CboxIdClient = class {
       organization: organization(claims),
       roles: roles(claims),
       permissions: permissions(claims),
+      featureFlags: featureFlags(claims),
       actor: actor(claims),
       sessionId: sessionId(claims),
       // Only present when the instance emitted the claim (exactOptionalPropertyTypes).
@@ -1165,6 +1340,18 @@ var CboxIdClient = class {
    * registered. `organization` picks which of the person's organizations the keys act in;
    * omitted, the page uses the one they are in.
    */
+  /**
+   * The hosted page where the signed-in person connects their account at `provider`
+   * (Pipes) — `/account/connected-services/{provider}/connect`, preselected to this app.
+   * They come back to `returnTo` with `?provider=…&status=connected|cancelled|failed`,
+   * honoured only on an origin the app registered.
+   */
+  pipeConnectUrl(provider, returnTo) {
+    return pipeConnectUrl(this.config.issuer, provider, {
+      clientId: this.config.clientId,
+      ...returnTo !== void 0 ? { returnTo } : {}
+    });
+  }
   apiKeysUrl(options = {}) {
     const params = new URLSearchParams({ client_id: options.clientId ?? this.config.clientId });
     if (options.returnTo) {
@@ -1693,8 +1880,14 @@ exports.CboxIdClient = CboxIdClient;
 exports.CboxIdError = CboxIdError;
 exports.CboxIdFrontend = CboxIdFrontend;
 exports.ConfigurationError = ConfigurationError;
+exports.FEATURE_FLAGS_SCOPE = FEATURE_FLAGS_SCOPE;
 exports.FrontendApiError = FrontendApiError;
 exports.InvalidStateError = InvalidStateError;
+exports.PipeLeaseDeniedError = PipeLeaseDeniedError;
+exports.PipeLeaseError = PipeLeaseError;
+exports.PipeNotConnectedError = PipeNotConnectedError;
+exports.PipeReauthorizationRequiredError = PipeReauthorizationRequiredError;
+exports.PipeTemporarilyUnavailableError = PipeTemporarilyUnavailableError;
 exports.VaultClient = VaultClient;
 exports.actor = actor;
 exports.buildManifest = buildManifest;
@@ -1702,16 +1895,20 @@ exports.challenge = challenge;
 exports.createLegacyVerifier = createLegacyVerifier;
 exports.createVerifier = createVerifier;
 exports.defineAuthz = defineAuthz;
+exports.featureFlags = featureFlags;
+exports.hasFeature = hasFeature;
 exports.hasPermission = hasPermission;
 exports.hasRole = hasRole;
 exports.isSupportSession = isSupportSession;
 exports.organization = organization;
 exports.permissions = permissions;
+exports.pipeConnectUrl = pipeConnectUrl;
 exports.publishManifest = publishManifest;
 exports.randomToken = randomToken;
 exports.roles = roles;
 exports.sessionId = sessionId;
 exports.verifyStandardWebhook = verifyStandardWebhook;
 exports.verifyWebhook = verifyWebhook;
+exports.withConnectReturn = withConnectReturn;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map