@bentoforge/umami-iam 0.1.0 → 0.2.0

package/src/client.ts

@@ -2,7 +2,7 @@ import type {
   AccessClaims,
   ApiErrorBody,
   ApiKeyView,
-  AuditEntry,
+  AuditPage,
   Config,
   CreateApiKeyRequest,
   CreateApiKeyResponse,
@@ -10,24 +10,22 @@ import type {
   CreateTenantRequest,
   CreateTenantResponse,
   CreateUserRequest,
+  CreateUserResponse,
   CustomFieldsSchema,
-  EntitlementsResponse,
   ExchangeResponse,
-  FeatureToggle,
   LoginResponse,
   MeResponse,
   MessagingCodeResponse,
   MessagingLink,
-  MetricUsage,
   MfaStatus,
+  NameInput,
   PatchUserRequest,
   ResetPasswordResponse,
   ResolvedMessagingUser,
+  SessionView,
   Tenant,
-  TenantStatus,
   TokenResponse,
   TotpSetup,
-  UsageResponse,
   UserView,
 } from "./types.js";
 import {
@@ -65,6 +63,8 @@ export class UmamiClient {
   private readonly baseUrl: string;
   private readonly onTokenChange?: (token: string | null) => void;
   private accessToken: string | null = null;
+  /** In-flight refresh, if any — coalesces concurrent 401s into a single rotation. */
+  private refreshing: Promise<boolean> | null = null;
 
   constructor(options: UmamiClientOptions) {
     this.baseUrl = options.baseUrl.replace(/\/+$/, "");
@@ -141,8 +141,8 @@ export class UmamiClient {
 
   /** Password login by username. On success the access token is stored; if MFA is enabled and no
    * `totpCode` is given, the response has `mfaRequired: true` and no token. Pass `api` to mint the
-   * token for a product API directly (default: the umami admin API); the session keeps that
-   * audience across refreshes. */
+   * first token for a product API directly (default: the umami admin API); the session itself is
+   * audience-agnostic, so later `refresh` calls choose their own `api`. */
   async login(
     username: string,
     password: string,
@@ -158,8 +158,20 @@ export class UmamiClient {
     return data;
   }
 
-  /** Silent refresh via the cookie. Returns whether a fresh token was obtained. */
+  /** Silent refresh via the cookie. Returns whether a fresh token was obtained.
+   *
+   * Single-flighted: concurrent callers (e.g. several requests that 401 at once) all await one
+   * rotation. Without this, the second refresh would send the just-rotated-out cookie secret, which
+   * the server treats as token reuse and revokes the whole session. */
   async refresh(): Promise<boolean> {
+    if (this.refreshing) return this.refreshing;
+    this.refreshing = this.doRefresh().finally(() => {
+      this.refreshing = null;
+    });
+    return this.refreshing;
+  }
+
+  private async doRefresh(): Promise<boolean> {
     const response = await this.doFetch("/auth/refresh", { method: "POST" }, false);
     if (!response.ok) {
       this.setToken(null);
@@ -181,16 +193,29 @@ export class UmamiClient {
     await this.request("/auth/logout-all", { method: "POST" }, true);
   }
 
+  /** Lists the caller's active login sessions (the current one is flagged). */
+  listSessions(): Promise<SessionView[]> {
+    return this.request<SessionView[]>("/auth/sessions");
+  }
+
+  /** Revokes one of the caller's own sessions (single-device logout). */
+  async deleteSession(sessionId: string): Promise<void> {
+    await this.request(`/auth/sessions/${enc(sessionId)}`, { method: "DELETE" });
+  }
+
   /** Current profile (user + tenant). */
   getMe(): Promise<MeResponse> {
     return this.request<MeResponse>("/auth/me");
   }
-  /** Update the caller's own profile (name/locale). Blocked for `self:readonly` users. */
-  patchMe(body: { name?: string; locale?: string }): Promise<MeResponse> {
-    return this.request<MeResponse>("/auth/me", { method: "PATCH", body: JSON.stringify(body) });
+  /** Self-service profile edit: the structured name parts are always editable; custom fields only
+   * when marked `selfEditable`. Blocked for `self:readonly` users. */
+  patchMe(body: NameInput & { customFields?: Record<string, unknown> }): Promise<MeResponse> {
+    return this.request<MeResponse>("/auth/me", {
+      method: "PATCH",
+      body: JSON.stringify(body),
+    });
   }
-
-  /** Re-scope the access token to another tenant (requires `admin:system`). Access-token only —
+  /** Re-scope the access token to another tenant (requires `switch:tenant`). Access-token only —
    * a later silent refresh returns to the home tenant. Returns the active tenant id. */
   async switchTenant(tenantId: string): Promise<string> {
     const data = await this.request<TokenResponse>("/auth/switch-tenant", {
@@ -284,14 +309,18 @@ export class UmamiClient {
     return data;
   }
 
-  /** Downstream token exchange: mints a token for a product API (`api` from the config catalog)
-   * for the currently-logged-in user, WITHOUT replacing the stored umami token. Returns the
-   * downstream token for the caller to use against that API. */
-  exchange(api: string): Promise<ExchangeResponse> {
-    return this.request<ExchangeResponse>("/auth/exchange", {
-      method: "POST",
-      body: JSON.stringify({ api }),
-    });
+  /** Mode 2 exchange: prove possession of `keyId`/`secret` with an HMAC over the current hour bucket
+   * instead of sending the secret. Same result as {@link exchangeApiKey}; the raw secret never
+   * leaves the process. `secret` is the part after `umk_<keyId>_`. Uses WebCrypto (Node 18+/browser). */
+  async exchangeApiKeyHmac(keyId: string, secret: string, api?: string): Promise<ExchangeResponse> {
+    const mac = await apiKeyMac(keyId, secret);
+    const data = await this.request<ExchangeResponse>(
+      "/auth/token",
+      { method: "POST", body: JSON.stringify(api ? { keyId, mac, api } : { keyId, mac }) },
+      false,
+    );
+    this.setToken(data.accessToken);
+    return data;
   }
 
   // ── tenants ────────────────────────────────────────────────────────────────────
@@ -299,9 +328,8 @@ export class UmamiClient {
   /** List every tenant (system-admin only; sorted newest-updated first, capped at 250). `q` is an
    * optional case-insensitive search: whitespace-separated terms must all match (over name / slug /
    * custom fields). `truncated` is true when more than 250 matched. */
-  listTenants(q?: string): Promise<{ tenants: Tenant[]; truncated: boolean }> {
-    const qs = q ? `?q=${encodeURIComponent(q)}` : "";
-    return this.request<{ tenants: Tenant[]; truncated: boolean }>(`/tenants${qs}`);
+  listTenants(q?: string, limit?: number): Promise<{ tenants: Tenant[]; truncated: boolean }> {
+    return this.request<{ tenants: Tenant[]; truncated: boolean }>(`/tenants${listQs(q, limit)}`);
   }
   /** Create a tenant and its first owner (system-admin only). */
   createTenant(request: CreateTenantRequest): Promise<CreateTenantResponse> {
@@ -320,51 +348,13 @@ export class UmamiClient {
   }
   patchTenant(
     tenantId: string,
-    body: Partial<Pick<Tenant, "name" | "plan" | "customFields">>,
+    body: Partial<Pick<Tenant, "name" | "customFields">>,
   ): Promise<Tenant> {
     return this.request<Tenant>(`/tenants/${enc(tenantId)}`, {
       method: "PATCH",
       body: JSON.stringify(body),
     });
   }
-  patchStatus(tenantId: string, status: TenantStatus): Promise<Tenant> {
-    return this.request<Tenant>(`/tenants/${enc(tenantId)}/status`, {
-      method: "PATCH",
-      body: JSON.stringify({ status }),
-    });
-  }
-  patchLicense(
-    tenantId: string,
-    body: { plan?: string; billedUntil?: string; seatsLimit?: number },
-  ): Promise<Tenant> {
-    return this.request<Tenant>(`/tenants/${enc(tenantId)}/license`, {
-      method: "PATCH",
-      body: JSON.stringify(body),
-    });
-  }
-  getEntitlements(tenantId: string): Promise<EntitlementsResponse> {
-    return this.request<EntitlementsResponse>(`/tenants/${enc(tenantId)}/entitlements`);
-  }
-  assignPackage(
-    tenantId: string,
-    request: { code: string; monthlyPrice?: string },
-  ): Promise<Tenant> {
-    return this.request<Tenant>(`/tenants/${enc(tenantId)}/packages`, {
-      method: "POST",
-      body: JSON.stringify(request),
-    });
-  }
-  removePackage(tenantId: string, assignmentId: string): Promise<Tenant> {
-    return this.request<Tenant>(`/tenants/${enc(tenantId)}/packages/${enc(assignmentId)}`, {
-      method: "DELETE",
-    });
-  }
-  setFeature(tenantId: string, code: string, value: FeatureToggle): Promise<Tenant> {
-    return this.request<Tenant>(`/tenants/${enc(tenantId)}/features/${enc(code)}`, {
-      method: "PUT",
-      body: JSON.stringify({ value }),
-    });
-  }
 
   // ── authorization: assignable roles/scopes/features + feature grant/revoke ─────
 
@@ -392,26 +382,23 @@ export class UmamiClient {
       method: "DELETE",
     });
   }
-  getUsage(tenantId: string): Promise<UsageResponse> {
-    return this.request<UsageResponse>(`/tenants/${enc(tenantId)}/usage`);
-  }
-  incrementUsage(tenantId: string, metric: string, amount = 1): Promise<MetricUsage> {
-    return this.request<MetricUsage>(`/tenants/${enc(tenantId)}/usage/${enc(metric)}`, {
-      method: "POST",
-      body: JSON.stringify({ amount }),
-    });
-  }
 
   // ── users ────────────────────────────────────────────────────────────────────
 
-  createUser(request: CreateUserRequest): Promise<UserView> {
-    return this.request<UserView>("/users", { method: "POST", body: JSON.stringify(request) });
+  createUser(request: CreateUserRequest): Promise<CreateUserResponse> {
+    return this.request<CreateUserResponse>("/users", {
+      method: "POST",
+      body: JSON.stringify(request),
+    });
   }
   /** List the caller's tenant's users (sorted by recent activity, capped at 250). `q` is an
    * optional case-insensitive search over username / email / name / custom fields. */
-  listUsers(q?: string): Promise<{ users: UserView[]; truncated: boolean }> {
-    const qs = q ? `?q=${encodeURIComponent(q)}` : "";
-    return this.request<{ users: UserView[]; truncated: boolean }>(`/users${qs}`);
+  listUsers(q?: string, limit?: number): Promise<{ users: UserView[]; truncated: boolean }> {
+    return this.request<{ users: UserView[]; truncated: boolean }>(`/users${listQs(q, limit)}`);
+  }
+  /** Read one user in the caller's tenant (requires `manage:users`). */
+  getUser(userId: string): Promise<UserView> {
+    return this.request<UserView>(`/users/${enc(userId)}`);
   }
   patchUser(userId: string, body: PatchUserRequest): Promise<UserView> {
     return this.request<UserView>(`/users/${enc(userId)}`, {
@@ -441,19 +428,25 @@ export class UmamiClient {
       body: JSON.stringify({ currentPassword, newPassword }),
     });
   }
-  /** The current user's own audit trail (newest first). */
-  async myAudit(limit?: number): Promise<AuditEntry[]> {
-    const qs = limit ? `?limit=${limit}` : "";
-    const data = await this.request<{ entries: AuditEntry[] }>(`/auth/me/audit${qs}`);
-    return data.entries;
-  }
-  /** A tenant's audit trail (requires `admin:tenant`; own tenant). */
-  async tenantAudit(tenantId: string, limit?: number): Promise<AuditEntry[]> {
-    const qs = limit ? `?limit=${limit}` : "";
-    const data = await this.request<{ entries: AuditEntry[] }>(
-      `/tenants/${enc(tenantId)}/audit${qs}`,
-    );
-    return data.entries;
+  /** One page of the current user's own audit trail (newest first). Pass `cursor` to page. */
+  myAudit(limit?: number, cursor?: string): Promise<AuditPage> {
+    return this.request<AuditPage>(`/auth/me/audit${auditQs(limit, cursor)}`);
+  }
+  /** One page of a tenant's audit trail (requires `admin:tenant`; own tenant). */
+  tenantAudit(tenantId: string, limit?: number, cursor?: string): Promise<AuditPage> {
+    return this.request<AuditPage>(`/tenants/${enc(tenantId)}/audit${auditQs(limit, cursor)}`);
+  }
+  /** One page of a tenant user's audit trail (requires `manage:users`; own tenant). */
+  userAudit(userId: string, limit?: number, cursor?: string): Promise<AuditPage> {
+    return this.request<AuditPage>(`/users/${enc(userId)}/audit${auditQs(limit, cursor)}`);
+  }
+  /** A tenant user's active login sessions (requires `manage:users`; own tenant). */
+  userSessions(userId: string): Promise<SessionView[]> {
+    return this.request<SessionView[]>(`/users/${enc(userId)}/sessions`);
+  }
+  /** Revokes all of a tenant user's sessions by bumping their tokenVersion (requires `manage:users`). */
+  async logoutUser(userId: string): Promise<void> {
+    await this.request(`/users/${enc(userId)}/logout-all`, { method: "POST" });
   }
 
   // ── messaging links ─────────────────────────────────────────────────────────
@@ -479,6 +472,13 @@ export class UmamiClient {
       { method: "DELETE" },
     );
   }
+  /** A tenant user's linked identities, read-only (requires `manage:users`; own tenant). */
+  async listUserMessagingLinks(userId: string): Promise<MessagingLink[]> {
+    const data = await this.request<{ links: MessagingLink[] }>(
+      `/users/${enc(userId)}/messaging-links`,
+    );
+    return data.links;
+  }
   /** Machine (`messaging:link`): claim a `(platform, externalId)` mapping from a link code. */
   createMessagingLink(
     code: string,
@@ -553,8 +553,61 @@ export class UmamiClient {
   async deleteMyPat(keyId: string): Promise<void> {
     await this.request(`/auth/me/api-keys/${enc(keyId)}`, { method: "DELETE" });
   }
+  /** A tenant user's personal access tokens, read-only (requires `manage:users`; own tenant). */
+  async listUserPats(userId: string): Promise<ApiKeyView[]> {
+    const data = await this.request<{ keys: ApiKeyView[] }>(`/users/${enc(userId)}/pats`);
+    return data.keys;
+  }
 }
 
 function enc(value: string): string {
   return encodeURIComponent(value);
 }
+
+/** base64url (no padding) of raw bytes. */
+function b64url(bytes: Uint8Array): string {
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/** Computes the Mode-2 API-key MAC: `HMAC-SHA256(key = SHA-256(secret), "umami:apikey:<keyId>:<hour>")`,
+ * base64url. The HMAC key is the SHA-256 of the secret — exactly the digest umami stores — so the
+ * server verifies without ever holding the raw secret. Matches `verify_key_hmac` on the server. */
+async function apiKeyMac(keyId: string, secret: string): Promise<string> {
+  const subtle = globalThis.crypto.subtle;
+  const enc8 = new TextEncoder();
+  const secretHash = new Uint8Array(await subtle.digest("SHA-256", enc8.encode(secret)));
+  const key = await subtle.importKey("raw", secretHash, { name: "HMAC", hash: "SHA-256" }, false, [
+    "sign",
+  ]);
+  const bucket = Math.floor(Date.now() / 3_600_000); // unix ms → whole hours
+  const mac = await subtle.sign("HMAC", key, enc8.encode(`umami:apikey:${keyId}:${bucket}`));
+  return b64url(new Uint8Array(mac));
+}
+
+/** Builds a `?limit=&cursor=` query string for the audit endpoints (omitting absent params). */
+function auditQs(limit?: number, cursor?: string): string {
+  const params = new URLSearchParams();
+  if (limit != null) {
+    params.set("limit", String(limit));
+  }
+  if (cursor) {
+    params.set("cursor", cursor);
+  }
+  const s = params.toString();
+  return s ? `?${s}` : "";
+}
+
+/** Builds a `?q=&limit=` query string for the list endpoints (omitting absent params). */
+function listQs(q?: string, limit?: number): string {
+  const params = new URLSearchParams();
+  if (q) {
+    params.set("q", q);
+  }
+  if (limit != null) {
+    params.set("limit", String(limit));
+  }
+  const s = params.toString();
+  return s ? `?${s}` : "";
+}