apiblaze 0.17.21 → 0.17.23

package/dist/server/index.d.mts

@@ -1,11 +1,143 @@
 /**
- * apiblaze/server — the server-side half of the API-key widget.
+ * apiblaze/server — SHARED widget-server substrate.
+ *
+ * One CP credential, one getUser contract, one ensure-tenant/ensure-user path —
+ * consumed by BOTH widget faces (`createApiblazeKeys` and `createApiblazeGroups`).
+ * Factored per iam_toolkit_spec ("share, don't fork" — copy-forking this
+ * bootstrap is a spec failure).
+ *
+ * Trust model: the CP key stays server-side and vouches for the CHANNEL; the
+ * acting end-user rides X-End-User-Id / X-End-User-Email. On the apikeys plane
+ * the end-user header only narrows (self-scoped key ops); on the iam plane it
+ * IS the principal (iam-worker independently checks the resolved user's
+ * apiblaze_admins membership before any group op).
+ */
+interface AppUser {
+    /** The producer's stable id for the consumer COMPANY — becomes the tenant (isolation). */
+    tenant: string;
+    /** The producer's stable id for the PERSON — the acting end-user. */
+    userId: string;
+    /** Optional; REQUIRED in practice for the groups widget — tenant-admin status
+     *  is granted by email (the tenant's admin-emails allowlist). */
+    email?: string;
+    /** Optional display name (cosmetic). */
+    label?: string;
+    /** Key-widget eligibility (see createApiblazeKeys). Ignored by the groups widget. */
+    keyTypes?: string[] | false;
+    /** Any extra fields your eligibility logic wants (e.g. isEngineer). */
+    [k: string]: unknown;
+}
+declare class PlaneError extends Error {
+    status: number;
+    detail: string;
+    constructor(status: number, detail: string);
+}
+
+/**
+ * createApiblazeGroups — the server-side half of the Users & Groups widget
+ * (<UsersGroupsWidget/>), riding the SAME shared substrate (core.ts) and the
+ * SAME one CP widget credential as the API-key widget.
+ *
+ * Usage (Next.js App Router — app/api/apiblaze/groups/route.ts):
+ *
+ *   import { createApiblazeGroups } from 'apiblaze/server';
+ *   const groups = createApiblazeGroups({
+ *     cpKey: process.env.APIBLAZE_CP_KEY!,   // the SAME key the key widget uses
+ *     getUser: async () => { ...same contract... return { tenant, userId, email } },
+ *   });
+ *   export const GET = groups.handler;
+ *   export const POST = groups.handler;
+ *
+ * AUTHORIZATION MODEL (iam_toolkit_spec): unlike key ops (self-scoped), group
+ * admin ops are tenant-wide — so the acting END-USER IS THE PRINCIPAL. This
+ * server forwards the session user via X-End-User-Id/-Email; apiblaze's iam
+ * plane independently verifies that user is a TENANT ADMIN (apiblaze_admins
+ * member, granted via the tenant's admin-emails allowlist) before any op. A
+ * non-admin gets `access: 'pending'` — nothing here can elevate them, and no
+ * producer-side flag can either. The CP key is only the channel.
+ *
+ * Strictly users + groups — NO authorization-rule authoring (that stays in
+ * `apiblaze authz` / the dashboard).
+ */
+
+interface ApiblazeGroupsConfig {
+    /** The producer CP key — the SAME widget key the API-key widget uses. Server-only. */
+    cpKey: string;
+    /** Return the logged-in user from the request/session, or null if unauthenticated.
+     *  `email` is how tenant-admin status is granted (admin-emails allowlist) — pass it. */
+    getUser: (req: Request) => Promise<AppUser | null> | AppUser | null;
+    /** Override the apikeys plane base (tenant/user provisioning). Default https://apikeys.apiblaze.com */
+    base?: string;
+    /** Override the iam plane base. Default https://iam.apiblaze.com */
+    iamBase?: string;
+}
+type GroupsAction = {
+    action: 'snapshot';
+} | {
+    action: 'create-group';
+    name: string;
+    description?: string;
+} | {
+    action: 'rename-group';
+    groupId: string;
+    name?: string;
+    description?: string;
+} | {
+    action: 'delete-group';
+    groupId: string;
+} | {
+    action: 'add-member';
+    groupId: string;
+    abzSub: string;
+    role?: 'member' | 'admin';
+} | {
+    action: 'change-role';
+    groupId: string;
+    abzSub: string;
+    role: 'member' | 'admin';
+} | {
+    action: 'remove-member';
+    groupId: string;
+    abzSub: string;
+} | {
+    action: 'add-subgroup';
+    groupId: string;
+    childGroupId: string;
+} | {
+    action: 'remove-subgroup';
+    groupId: string;
+    childGroupId: string;
+} | {
+    action: 'group-detail';
+    groupId: string;
+} | {
+    action: 'provision-observed';
+    consumerUserId: string;
+    email?: string;
+    displayName?: string;
+    groups?: string[];
+};
+declare function createApiblazeGroups(cfg: ApiblazeGroupsConfig): {
+    handler: (req: Request) => Promise<Response>;
+    run: (user: AppUser, op: GroupsAction) => Promise<{
+        status: number;
+        data: unknown;
+    }>;
+};
+
+/**
+ * apiblaze/server — the server-side half of the apiblaze widgets.
  *
  * Holds the producer's CP key (server-only, never shipped to the browser) and turns
- * a logged-in user into API-key operations against apiblaze.com. The browser widget
- * (`apiblaze/react`) talks ONLY to your own backend; your backend talks to apiblaze —
- * so there are no cross-domain cookies, no secrets in the client, and no auth wiring
- * beyond "read my session."
+ * a logged-in user into apiblaze operations. The browser widgets (`apiblaze/react`)
+ * talk ONLY to your own backend; your backend talks to apiblaze — so there are no
+ * cross-domain cookies, no secrets in the client, and no auth wiring beyond
+ * "read my session."
+ *
+ * TWO faces over ONE shared substrate (core.ts — one CP credential, one
+ * ensure-tenant/ensure-user path):
+ *   - createApiblazeKeys   → API-key management  (<ApiKeyWidget/>)
+ *   - createApiblazeGroups → users & groups IAM  (<UsersGroupsWidget/>)
  *
  * Usage (Next.js App Router — app/api/apiblaze/keys/route.ts):
  *
@@ -17,34 +149,41 @@
  *     getUser: async () => {
  *       const s = await auth();
  *       if (!s?.user) return null;
- *       return { tenant: s.user.orgId ?? s.user.id, userId: s.user.id, email: s.user.email ?? undefined, label: s.user.name ?? undefined };
+ *       return {
+ *         tenant: s.user.orgId ?? s.user.id,
+ *         userId: s.user.id,
+ *         email: s.user.email ?? undefined,
+ *         // Which key types this person may create. Omit → ['call-only'].
+ *         // false → no API access. A list of 2+ → the widget shows a picker.
+ *         keyTypes: s.user.isEngineer ? ['manager', 'call-only'] : undefined,
+ *       };
  *     },
- *     resolveScopes: (u) => u.isEngineer ? ['call', 'use-premium'] : ['call'],   // optional
  *   });
  *   export const GET = keys.handler;
  *   export const POST = keys.handler;
+ *
+ * SECURITY: eligibility is decided HERE, on your server, from your session —
+ * never from the browser. When a user is eligible for more than one type the
+ * browser sends its pick, but this handler only honors it if it's in the user's
+ * allowed set; otherwise it's rejected. `keyTypes: false` is enforced server-side
+ * (403) before anything is provisioned, not merely hidden in the UI.
  */
-interface AppUser {
-    /** The producer's stable id for the consumer COMPANY — becomes the tenant (isolation). */
-    tenant: string;
-    /** The producer's stable id for the PERSON — the key creator/owner (list scope). */
-    userId: string;
-    /** Optional, stored now for possible future portal parity. */
-    email?: string;
-    /** Optional display name (cosmetic). */
-    label?: string;
-    /** Any extra fields your resolveScopes wants (e.g. isEngineer). */
-    [k: string]: unknown;
-}
+
 interface ApiblazeKeysConfig {
-    /** The producer CP key from the apiblaze dashboard Developers section. Server-only. */
+    /** The producer CP key from the apiblaze dashboard Developers section. Server-only.
+     *  Use a purpose-built "widget" key (not a full admin key) so the platform's own
+     *  subset rule is a real backstop under your eligibility logic. */
     cpKey: string;
     /** Return the logged-in user from the request/session, or null if unauthenticated. */
     getUser: (req: Request) => Promise<AppUser | null> | AppUser | null;
-    /** Permission set to mint for a user. Default ['call']. Server-side only, so a browser
-     *  can never escalate — return more for your own engineers here. */
-    resolveScopes?: (user: AppUser) => string[] | Promise<string[]>;
-    /** Default expiry for minted keys (seconds); enables re-reveal. Default 1 year. */
+    /** Optional override for eligibility, if you'd rather compute it here than inline
+     *  in getUser. Same contract as AppUser.keyTypes (undefined → default, false/[] → deny).
+     *  Takes precedence over user.keyTypes when provided. */
+    resolveKeyTypes?: (user: AppUser) => (string[] | false) | Promise<string[] | false>;
+    /** Key lifetime in seconds. Omit for a DURABLE key (no expiry) — the right
+     *  default for a production API key a developer embeds, so it never silently
+     *  stops working. A durable key is shown ONCE at creation (not re-revealable);
+     *  set an expiry if you want keys that stay revealable until they expire. */
     keyExpiresInSeconds?: number;
     /** Override the apiblaze base (tests/self-host). Default https://apikeys.apiblaze.com */
     base?: string;
@@ -53,6 +192,7 @@ type Action = {
     action: 'list';
 } | {
     action: 'create';
+    keyType?: string;
 } | {
     action: 'reveal';
     keyId: string;
@@ -71,4 +211,4 @@ declare function createApiblazeKeys(cfg: ApiblazeKeysConfig): {
     }>;
 };
 
-export { type ApiblazeKeysConfig, type AppUser, createApiblazeKeys };
+export { type ApiblazeGroupsConfig, type ApiblazeKeysConfig, type AppUser, type GroupsAction, PlaneError, createApiblazeGroups, createApiblazeKeys };

package/dist/server/index.d.ts

@@ -1,11 +1,143 @@
 /**
- * apiblaze/server — the server-side half of the API-key widget.
+ * apiblaze/server — SHARED widget-server substrate.
+ *
+ * One CP credential, one getUser contract, one ensure-tenant/ensure-user path —
+ * consumed by BOTH widget faces (`createApiblazeKeys` and `createApiblazeGroups`).
+ * Factored per iam_toolkit_spec ("share, don't fork" — copy-forking this
+ * bootstrap is a spec failure).
+ *
+ * Trust model: the CP key stays server-side and vouches for the CHANNEL; the
+ * acting end-user rides X-End-User-Id / X-End-User-Email. On the apikeys plane
+ * the end-user header only narrows (self-scoped key ops); on the iam plane it
+ * IS the principal (iam-worker independently checks the resolved user's
+ * apiblaze_admins membership before any group op).
+ */
+interface AppUser {
+    /** The producer's stable id for the consumer COMPANY — becomes the tenant (isolation). */
+    tenant: string;
+    /** The producer's stable id for the PERSON — the acting end-user. */
+    userId: string;
+    /** Optional; REQUIRED in practice for the groups widget — tenant-admin status
+     *  is granted by email (the tenant's admin-emails allowlist). */
+    email?: string;
+    /** Optional display name (cosmetic). */
+    label?: string;
+    /** Key-widget eligibility (see createApiblazeKeys). Ignored by the groups widget. */
+    keyTypes?: string[] | false;
+    /** Any extra fields your eligibility logic wants (e.g. isEngineer). */
+    [k: string]: unknown;
+}
+declare class PlaneError extends Error {
+    status: number;
+    detail: string;
+    constructor(status: number, detail: string);
+}
+
+/**
+ * createApiblazeGroups — the server-side half of the Users & Groups widget
+ * (<UsersGroupsWidget/>), riding the SAME shared substrate (core.ts) and the
+ * SAME one CP widget credential as the API-key widget.
+ *
+ * Usage (Next.js App Router — app/api/apiblaze/groups/route.ts):
+ *
+ *   import { createApiblazeGroups } from 'apiblaze/server';
+ *   const groups = createApiblazeGroups({
+ *     cpKey: process.env.APIBLAZE_CP_KEY!,   // the SAME key the key widget uses
+ *     getUser: async () => { ...same contract... return { tenant, userId, email } },
+ *   });
+ *   export const GET = groups.handler;
+ *   export const POST = groups.handler;
+ *
+ * AUTHORIZATION MODEL (iam_toolkit_spec): unlike key ops (self-scoped), group
+ * admin ops are tenant-wide — so the acting END-USER IS THE PRINCIPAL. This
+ * server forwards the session user via X-End-User-Id/-Email; apiblaze's iam
+ * plane independently verifies that user is a TENANT ADMIN (apiblaze_admins
+ * member, granted via the tenant's admin-emails allowlist) before any op. A
+ * non-admin gets `access: 'pending'` — nothing here can elevate them, and no
+ * producer-side flag can either. The CP key is only the channel.
+ *
+ * Strictly users + groups — NO authorization-rule authoring (that stays in
+ * `apiblaze authz` / the dashboard).
+ */
+
+interface ApiblazeGroupsConfig {
+    /** The producer CP key — the SAME widget key the API-key widget uses. Server-only. */
+    cpKey: string;
+    /** Return the logged-in user from the request/session, or null if unauthenticated.
+     *  `email` is how tenant-admin status is granted (admin-emails allowlist) — pass it. */
+    getUser: (req: Request) => Promise<AppUser | null> | AppUser | null;
+    /** Override the apikeys plane base (tenant/user provisioning). Default https://apikeys.apiblaze.com */
+    base?: string;
+    /** Override the iam plane base. Default https://iam.apiblaze.com */
+    iamBase?: string;
+}
+type GroupsAction = {
+    action: 'snapshot';
+} | {
+    action: 'create-group';
+    name: string;
+    description?: string;
+} | {
+    action: 'rename-group';
+    groupId: string;
+    name?: string;
+    description?: string;
+} | {
+    action: 'delete-group';
+    groupId: string;
+} | {
+    action: 'add-member';
+    groupId: string;
+    abzSub: string;
+    role?: 'member' | 'admin';
+} | {
+    action: 'change-role';
+    groupId: string;
+    abzSub: string;
+    role: 'member' | 'admin';
+} | {
+    action: 'remove-member';
+    groupId: string;
+    abzSub: string;
+} | {
+    action: 'add-subgroup';
+    groupId: string;
+    childGroupId: string;
+} | {
+    action: 'remove-subgroup';
+    groupId: string;
+    childGroupId: string;
+} | {
+    action: 'group-detail';
+    groupId: string;
+} | {
+    action: 'provision-observed';
+    consumerUserId: string;
+    email?: string;
+    displayName?: string;
+    groups?: string[];
+};
+declare function createApiblazeGroups(cfg: ApiblazeGroupsConfig): {
+    handler: (req: Request) => Promise<Response>;
+    run: (user: AppUser, op: GroupsAction) => Promise<{
+        status: number;
+        data: unknown;
+    }>;
+};
+
+/**
+ * apiblaze/server — the server-side half of the apiblaze widgets.
  *
  * Holds the producer's CP key (server-only, never shipped to the browser) and turns
- * a logged-in user into API-key operations against apiblaze.com. The browser widget
- * (`apiblaze/react`) talks ONLY to your own backend; your backend talks to apiblaze —
- * so there are no cross-domain cookies, no secrets in the client, and no auth wiring
- * beyond "read my session."
+ * a logged-in user into apiblaze operations. The browser widgets (`apiblaze/react`)
+ * talk ONLY to your own backend; your backend talks to apiblaze — so there are no
+ * cross-domain cookies, no secrets in the client, and no auth wiring beyond
+ * "read my session."
+ *
+ * TWO faces over ONE shared substrate (core.ts — one CP credential, one
+ * ensure-tenant/ensure-user path):
+ *   - createApiblazeKeys   → API-key management  (<ApiKeyWidget/>)
+ *   - createApiblazeGroups → users & groups IAM  (<UsersGroupsWidget/>)
  *
  * Usage (Next.js App Router — app/api/apiblaze/keys/route.ts):
  *
@@ -17,34 +149,41 @@
  *     getUser: async () => {
  *       const s = await auth();
  *       if (!s?.user) return null;
- *       return { tenant: s.user.orgId ?? s.user.id, userId: s.user.id, email: s.user.email ?? undefined, label: s.user.name ?? undefined };
+ *       return {
+ *         tenant: s.user.orgId ?? s.user.id,
+ *         userId: s.user.id,
+ *         email: s.user.email ?? undefined,
+ *         // Which key types this person may create. Omit → ['call-only'].
+ *         // false → no API access. A list of 2+ → the widget shows a picker.
+ *         keyTypes: s.user.isEngineer ? ['manager', 'call-only'] : undefined,
+ *       };
  *     },
- *     resolveScopes: (u) => u.isEngineer ? ['call', 'use-premium'] : ['call'],   // optional
  *   });
  *   export const GET = keys.handler;
  *   export const POST = keys.handler;
+ *
+ * SECURITY: eligibility is decided HERE, on your server, from your session —
+ * never from the browser. When a user is eligible for more than one type the
+ * browser sends its pick, but this handler only honors it if it's in the user's
+ * allowed set; otherwise it's rejected. `keyTypes: false` is enforced server-side
+ * (403) before anything is provisioned, not merely hidden in the UI.
  */
-interface AppUser {
-    /** The producer's stable id for the consumer COMPANY — becomes the tenant (isolation). */
-    tenant: string;
-    /** The producer's stable id for the PERSON — the key creator/owner (list scope). */
-    userId: string;
-    /** Optional, stored now for possible future portal parity. */
-    email?: string;
-    /** Optional display name (cosmetic). */
-    label?: string;
-    /** Any extra fields your resolveScopes wants (e.g. isEngineer). */
-    [k: string]: unknown;
-}
+
 interface ApiblazeKeysConfig {
-    /** The producer CP key from the apiblaze dashboard Developers section. Server-only. */
+    /** The producer CP key from the apiblaze dashboard Developers section. Server-only.
+     *  Use a purpose-built "widget" key (not a full admin key) so the platform's own
+     *  subset rule is a real backstop under your eligibility logic. */
     cpKey: string;
     /** Return the logged-in user from the request/session, or null if unauthenticated. */
     getUser: (req: Request) => Promise<AppUser | null> | AppUser | null;
-    /** Permission set to mint for a user. Default ['call']. Server-side only, so a browser
-     *  can never escalate — return more for your own engineers here. */
-    resolveScopes?: (user: AppUser) => string[] | Promise<string[]>;
-    /** Default expiry for minted keys (seconds); enables re-reveal. Default 1 year. */
+    /** Optional override for eligibility, if you'd rather compute it here than inline
+     *  in getUser. Same contract as AppUser.keyTypes (undefined → default, false/[] → deny).
+     *  Takes precedence over user.keyTypes when provided. */
+    resolveKeyTypes?: (user: AppUser) => (string[] | false) | Promise<string[] | false>;
+    /** Key lifetime in seconds. Omit for a DURABLE key (no expiry) — the right
+     *  default for a production API key a developer embeds, so it never silently
+     *  stops working. A durable key is shown ONCE at creation (not re-revealable);
+     *  set an expiry if you want keys that stay revealable until they expire. */
     keyExpiresInSeconds?: number;
     /** Override the apiblaze base (tests/self-host). Default https://apikeys.apiblaze.com */
     base?: string;
@@ -53,6 +192,7 @@ type Action = {
     action: 'list';
 } | {
     action: 'create';
+    keyType?: string;
 } | {
     action: 'reveal';
     keyId: string;
@@ -71,4 +211,4 @@ declare function createApiblazeKeys(cfg: ApiblazeKeysConfig): {
     }>;
 };
 
-export { type ApiblazeKeysConfig, type AppUser, createApiblazeKeys };
+export { type ApiblazeGroupsConfig, type ApiblazeKeysConfig, type AppUser, type GroupsAction, PlaneError, createApiblazeGroups, createApiblazeKeys };