@base44-preview/sdk 0.8.44-pr.264.d98f3ac → 0.8.44-pr.265.790c3c6

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 import { createClient, createClientFromRequest, type Base44Client, type CreateClientConfig, type CreateClientOptions } from "./client.js";
+import { createPlatformClient, type CreatePlatformClientConfig, type PlatformClient, type PrincipalClient } from "./platform-client.js";
 import { Base44Error, type Base44ErrorJSON } from "./utils/axios-client.js";
 import { getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl } from "./utils/auth-utils.js";
-export { createClient, createClientFromRequest, Base44Error, getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl, };
-export type { Base44Client, CreateClientConfig, CreateClientOptions, Base44ErrorJSON, };
+export { createClient, createClientFromRequest, createPlatformClient, Base44Error, getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl, };
+export type { Base44Client, CreateClientConfig, CreateClientOptions, Base44ErrorJSON, CreatePlatformClientConfig, PlatformClient, PrincipalClient, };
 export * from "./types.js";
 export type { DeleteManyResult, DeleteResult, EntitiesModule, EntityFilterOperators, EntityFilterQuery, EntityFilterValue, EntityHandler, EntityRecord, EntityTypeRegistry, ImportResult, RealtimeEventType, RealtimeEvent, RealtimeCallback, SortField, UpdateManyResult, } from "./modules/entities.types.js";
 export type { AuthModule, LoginResponse, RegisterParams, VerifyOtpParams, ChangePasswordParams, ResetPasswordParams, User, } from "./modules/auth.types.js";
@@ -13,6 +14,7 @@ export type { AiGatewayModule, AiGatewayConnection, } from "./modules/ai-gateway
 export type { AppLogsModule } from "./modules/app-logs.types.js";
 export type { ActorsModule, ActorClient, ActorRef, Connection, ActorSubscription, ActorConnectOptions, ActorNameRegistry, ActorRegistry, } from "./modules/actors.types.js";
 export type { SsoModule, SsoAccessTokenResponse } from "./modules/sso.types.js";
+export type { PlatformsModule, PrincipalRole, ProvisionPrincipalParams, ServicePrincipal, DeprovisionResult, } from "./modules/platforms.types.js";
 export { Actor, type Conn } from "./actor.js";
 export type { ConnectorsModule, UserConnectorsModule, ConnectorApiRequest, ConnectorApiResponse, ConnectorApiResponsePhase, } from "./modules/connectors.types.js";
 export type { CustomIntegrationsModule, CustomIntegrationCallParams, CustomIntegrationCallResponse, } from "./modules/custom-integrations.types.js";

package/dist/index.js

@@ -1,6 +1,7 @@
 import { createClient, createClientFromRequest, } from "./client.js";
+import { createPlatformClient, } from "./platform-client.js";
 import { Base44Error } from "./utils/axios-client.js";
 import { getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl, } from "./utils/auth-utils.js";
-export { createClient, createClientFromRequest, Base44Error, getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl, };
+export { createClient, createClientFromRequest, createPlatformClient, Base44Error, getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl, };
 export * from "./types.js";
 export { Actor } from "./actor.js";

package/dist/modules/auth.js

@@ -1,4 +1,3 @@
-import { removeAccessToken } from "../utils/auth-utils.js";
 import { resetAnalyticsSessionContext } from "./analytics.js";
 function isInsideIframe() {
     if (typeof window === "undefined")
@@ -116,10 +115,7 @@ export function createAuthModule(axios, functionsAxiosClient, appId, options) {
                 : window.location.href;
             // Build the login URL
             const loginUrl = `${options.appBaseUrl}/login?from_url=${encodeURIComponent(redirectUrl)}`;
-            // The login page must not boot with the token that just got us here,
-            // or a rejected token redirects to /login forever.
-            removeAccessToken({});
-            removeAccessToken({ storageKey: "token" });
+            // Redirect to the login page
             window.location.href = loginUrl;
         },
         // Redirects the user to a provider's login page
@@ -158,8 +154,17 @@ export function createAuthModule(axios, functionsAxiosClient, appId, options) {
             hasAccessToken = false;
             // Only do the rest if in a browser environment
             if (typeof window !== "undefined") {
-                removeAccessToken({});
-                removeAccessToken({ storageKey: "token" });
+                // Remove token from localStorage
+                if (window.localStorage) {
+                    try {
+                        window.localStorage.removeItem("base44_access_token");
+                        // Remove "token" that is set by the built-in SDK of platform version 2
+                        window.localStorage.removeItem("token");
+                    }
+                    catch (e) {
+                        console.error("Failed to remove token from localStorage:", e);
+                    }
+                }
                 // Determine the from_url parameter
                 const fromUrl = redirectUrl || window.location.href;
                 // Redirect to server-side logout endpoint to clear HTTP-only cookies

package/dist/modules/platforms.d.ts

@@ -0,0 +1,14 @@
+import type { AxiosInstance } from "axios";
+import type { PlatformsModule } from "./platforms.types.js";
+/**
+ * Creates the platforms module.
+ *
+ * Takes the *provision* client specifically, not the mint client. The two keys
+ * are separated so that no code path holding the hot-path key can create or
+ * destroy principals, and passing one client here is what keeps that true.
+ *
+ * @param axios - An Axios instance carrying the `service_users:provision` key.
+ * @returns The platforms module.
+ * @internal
+ */
+export declare function createPlatformsModule(axios: AxiosInstance): PlatformsModule;

package/dist/modules/platforms.js

@@ -0,0 +1,41 @@
+/**
+ * Creates the platforms module.
+ *
+ * Takes the *provision* client specifically, not the mint client. The two keys
+ * are separated so that no code path holding the hot-path key can create or
+ * destroy principals, and passing one client here is what keeps that true.
+ *
+ * @param axios - An Axios instance carrying the `service_users:provision` key.
+ * @returns The platforms module.
+ * @internal
+ */
+export function createPlatformsModule(axios) {
+    return {
+        async provisionPrincipal(params) {
+            const body = {
+                service_external_id: params.externalId,
+            };
+            // Omitted rather than sent as null: the server applies its own defaults
+            // for both, and `role` in particular is clamped to a ceiling.
+            if (params.displayName !== undefined)
+                body.display_name = params.displayName;
+            if (params.role !== undefined)
+                body.role = params.role;
+            const response = await axios.post("/api/service/users", body);
+            return {
+                externalId: response.service_external_id,
+                userId: response.user_id,
+                email: response.email,
+                role: response.role,
+                created: response.created,
+            };
+        },
+        async deprovisionPrincipal(externalId) {
+            const response = await axios.delete(`/api/service/users/${encodeURIComponent(externalId)}`);
+            return {
+                externalId: response.service_external_id,
+                removed: response.removed,
+            };
+        },
+    };
+}

package/dist/modules/platforms.types.d.ts

@@ -0,0 +1,139 @@
+/**
+ * The role a service principal holds in the workspace.
+ *
+ * Capped on the server: a principal is never an owner or an admin, whatever a
+ * caller asks for. Passing anything outside this set is clamped down rather than
+ * rejected, so a typo cannot quietly grant more than intended.
+ */
+export type PrincipalRole = "editor" | "viewer";
+/**
+ * Parameters for provisioning a service principal.
+ */
+export interface ProvisionPrincipalParams {
+    /**
+     * Your own identifier for the person this principal acts for — whatever your
+     * platform already calls them (`"user_42"`, a UUID, a tenant-scoped handle).
+     *
+     * It is opaque to Base44 and is the only thing that addresses this principal
+     * afterwards, so it must be stable for the life of the account. Never an
+     * email, and never an SSO identity.
+     */
+    externalId: string;
+    /**
+     * A human-readable name, shown wherever the principal appears in Base44.
+     *
+     * Cosmetic only: nothing resolves a principal by name.
+     */
+    displayName?: string;
+    /**
+     * The workspace role to create the principal with.
+     *
+     * @defaultValue `"editor"`
+     */
+    role?: PrincipalRole;
+}
+/**
+ * A provisioned service principal.
+ */
+export interface ServicePrincipal {
+    /** The identifier you provisioned it under. */
+    externalId: string;
+    /** Base44's own user id for the principal. */
+    userId: string;
+    /**
+     * The synthetic address Base44 generated for it.
+     *
+     * In a reserved, non-routable domain that can never receive mail — a
+     * principal is a robot identity, not a person with an inbox.
+     */
+    email: string;
+    /** The role it actually holds, after the server's ceiling is applied. */
+    role: string;
+    /**
+     * Whether this call created the principal.
+     *
+     * `false` means it already existed and was returned unchanged. Provisioning is
+     * idempotent, so this is informational — not an error to handle.
+     */
+    created: boolean;
+}
+/**
+ * The outcome of deprovisioning a principal.
+ */
+export interface DeprovisionResult {
+    /** The identifier that was addressed. */
+    externalId: string;
+    /**
+     * Whether this call actually tore a principal down.
+     *
+     * `false` means nothing matched. Repeating a deprovision is safe and still
+     * succeeds, so a `false` on the *first* call is the interesting one: it means
+     * the id is wrong and some live principal is still holding vended tokens.
+     */
+    removed: boolean;
+}
+/**
+ * Platform-level operations, scoped to a workspace rather than to one app.
+ *
+ * Reached through {@link createPlatformClient | createPlatformClient()}, which is
+ * the only client that holds workspace keys. This module manages *who* your
+ * platform acts as; {@link PlatformClient.asPrincipal | asPrincipal()} is how you
+ * then act as one.
+ */
+export interface PlatformsModule {
+    /**
+     * Creates a service principal for one of your users, or returns the existing one.
+     *
+     * Idempotent per `(workspace, externalId)`, so the intended use is to call it
+     * on every request that needs a principal rather than tracking which of your
+     * users you have provisioned. The second call is a plain lookup.
+     *
+     * The principal is created with **no credential of its own** — nothing can log
+     * in as it. The only way to act as it is
+     * {@link PlatformClient.asPrincipal | asPrincipal()}, which needs your
+     * workspace's mint key.
+     *
+     * Requires the `service_users:provision` key.
+     *
+     * @param params - The principal to provision.
+     * @returns The principal, whether it was just created or already existed.
+     *
+     * @throws {Base44Error} 409 if the generated address collides with an existing
+     * account, 403 if service principals are not enabled for the workspace.
+     *
+     * @example
+     * ```typescript
+     * // Safe to call on every request — the second call is just a lookup.
+     * const principal = await base44.platforms.provisionPrincipal({
+     *   externalId: 'user_42',
+     *   displayName: 'Dana',
+     * });
+     *
+     * const asDana = base44.asPrincipal('user_42');
+     * ```
+     */
+    provisionPrincipal(params: ProvisionPrincipalParams): Promise<ServicePrincipal>;
+    /**
+     * Removes a service principal from the workspace.
+     *
+     * This is the offboarding lever, and it bites immediately: every vended token
+     * re-checks the workspace membership on each request, so tokens already handed
+     * out stop working now rather than when they expire.
+     *
+     * Requires the `service_users:provision` key — which is why that key should not
+     * be reachable from a request path.
+     *
+     * Deprovisioning does not delete the apps the principal built; it owns them,
+     * and they outlive it.
+     *
+     * @param externalId - The identifier the principal was provisioned under.
+     * @returns Whether a principal was actually torn down.
+     *
+     * @example
+     * ```typescript
+     * // A user closed their account.
+     * await base44.platforms.deprovisionPrincipal('user_42');
+     * ```
+     */
+    deprovisionPrincipal(externalId: string): Promise<DeprovisionResult>;
+}

package/dist/modules/platforms.types.js

@@ -0,0 +1 @@
+export {};

package/dist/platform-client.d.ts

@@ -0,0 +1,52 @@
+import type { CreatePlatformClientConfig, PlatformClient, PrincipalClient } from "./platform-client.types.js";
+export type { CreatePlatformClientConfig, PlatformClient, PrincipalClient };
+/**
+ * Creates a workspace-scoped Base44 client, for platforms that build apps on
+ * behalf of their own users.
+ *
+ * This is the third client factory, and it exists for the one case neither of
+ * the others covers. {@linkcode createClient | createClient()} is scoped to one
+ * app and one user; {@linkcode createClientFromRequest | createClientFromRequest()}
+ * runs inside a Base44-hosted function. A platform is scoped to a **workspace**:
+ * it has many users, none of whom have a Base44 account, and it needs each of
+ * them to own the apps they build.
+ *
+ * The model is a *service principal* — a synthetic member of your workspace,
+ * created with no credential of its own, that you act as. Your users never see
+ * Base44; you keep your own accounts and map each one to a principal.
+ *
+ * Two steps, and the first is idempotent:
+ *
+ * 1. {@linkcode PlatformsModule.provisionPrincipal | provisionPrincipal()} to
+ *    make sure a principal exists for your user.
+ * 2. {@linkcode PlatformClient.asPrincipal | asPrincipal()} to act as them.
+ *
+ * **Server-side only.** This client holds workspace API keys, which authorize
+ * every app in the workspace. Never construct one in a browser, and never send
+ * either key to one — a browser gets a short-lived token vended *for it*, which
+ * is what {@linkcode PrincipalClient.getToken | getToken()} is for.
+ *
+ * @param config - Configuration object for the platform client.
+ * @returns A configured platform client.
+ *
+ * @example
+ * ```typescript
+ * import { createPlatformClient } from '@base44/sdk';
+ *
+ * const base44 = createPlatformClient({
+ *   mintKey: process.env.BASE44_MINT_KEY,          // user_tokens:mint
+ *   provisionKey: process.env.BASE44_PROVISION_KEY, // service_users:provision
+ * });
+ *
+ * // On a request from one of your users:
+ * await base44.platforms.provisionPrincipal({
+ *   externalId: 'user_42',
+ *   displayName: 'Dana',
+ * });
+ *
+ * const asDana = base44.asPrincipal('user_42');
+ * const app = await asDana.forApp(appId);
+ * const todos = await app.entities.Todo.list();
+ * ```
+ */
+export declare function createPlatformClient(config: CreatePlatformClientConfig): PlatformClient;

package/dist/platform-client.js

@@ -0,0 +1,130 @@
+import { createAxiosClient } from "./utils/axios-client.js";
+import { createPlatformsModule } from "./modules/platforms.js";
+import { createPrincipalTokenStore } from "./utils/principal-tokens.js";
+import { createClient } from "./client.js";
+/**
+ * Creates a workspace-scoped Base44 client, for platforms that build apps on
+ * behalf of their own users.
+ *
+ * This is the third client factory, and it exists for the one case neither of
+ * the others covers. {@linkcode createClient | createClient()} is scoped to one
+ * app and one user; {@linkcode createClientFromRequest | createClientFromRequest()}
+ * runs inside a Base44-hosted function. A platform is scoped to a **workspace**:
+ * it has many users, none of whom have a Base44 account, and it needs each of
+ * them to own the apps they build.
+ *
+ * The model is a *service principal* — a synthetic member of your workspace,
+ * created with no credential of its own, that you act as. Your users never see
+ * Base44; you keep your own accounts and map each one to a principal.
+ *
+ * Two steps, and the first is idempotent:
+ *
+ * 1. {@linkcode PlatformsModule.provisionPrincipal | provisionPrincipal()} to
+ *    make sure a principal exists for your user.
+ * 2. {@linkcode PlatformClient.asPrincipal | asPrincipal()} to act as them.
+ *
+ * **Server-side only.** This client holds workspace API keys, which authorize
+ * every app in the workspace. Never construct one in a browser, and never send
+ * either key to one — a browser gets a short-lived token vended *for it*, which
+ * is what {@linkcode PrincipalClient.getToken | getToken()} is for.
+ *
+ * @param config - Configuration object for the platform client.
+ * @returns A configured platform client.
+ *
+ * @example
+ * ```typescript
+ * import { createPlatformClient } from '@base44/sdk';
+ *
+ * const base44 = createPlatformClient({
+ *   mintKey: process.env.BASE44_MINT_KEY,          // user_tokens:mint
+ *   provisionKey: process.env.BASE44_PROVISION_KEY, // service_users:provision
+ * });
+ *
+ * // On a request from one of your users:
+ * await base44.platforms.provisionPrincipal({
+ *   externalId: 'user_42',
+ *   displayName: 'Dana',
+ * });
+ *
+ * const asDana = base44.asPrincipal('user_42');
+ * const app = await asDana.forApp(appId);
+ * const todos = await app.entities.Todo.list();
+ * ```
+ */
+export function createPlatformClient(config) {
+    const { serverUrl = "https://base44.app", mintKey, provisionKey = mintKey, options, } = config;
+    // Three clients, because they carry three different credentials — and the
+    // separation is the security property, not tidiness. Nothing reachable from a
+    // request should be able to create a principal, and nothing at all should
+    // present a workspace key to an endpoint that authenticates a refresh token.
+    const mintAxios = createAxiosClient({
+        baseURL: serverUrl,
+        token: mintKey,
+        onError: options === null || options === void 0 ? void 0 : options.onError,
+    });
+    const provisionAxios = createAxiosClient({
+        baseURL: serverUrl,
+        token: provisionKey,
+        onError: options === null || options === void 0 ? void 0 : options.onError,
+    });
+    const oauthAxios = createAxiosClient({
+        baseURL: serverUrl,
+        onError: options === null || options === void 0 ? void 0 : options.onError,
+    });
+    const tokens = createPrincipalTokenStore({ mintAxios, oauthAxios });
+    const platforms = createPlatformsModule(provisionAxios);
+    // One principal handle per external id, and one app client per (principal,
+    // app). Both are addressed by stable ids and both wrap cached state, so
+    // rebuilding them per request would throw away the token cache that makes the
+    // mint rate limit survivable.
+    const principals = new Map();
+    const buildPrincipal = (externalId) => {
+        // The token each client was last given, so a rotation can be detected. Held
+        // beside the client rather than read back off it because a client does not
+        // expose its credential.
+        const apps = new Map();
+        const getToken = async () => (await tokens.get(externalId)).accessToken;
+        return {
+            externalId,
+            getToken,
+            async forApp(appId) {
+                const token = await getToken();
+                const held = apps.get(appId);
+                if (held) {
+                    // Only on an actual rotation. `setToken` treats the call as an
+                    // identity change — it discards the in-flight `me()` other callers are
+                    // awaiting and resets the analytics session — so applying it on every
+                    // request would undo work the client does on the caller's behalf.
+                    if (held.token !== token) {
+                        held.client.setToken(token);
+                        held.token = token;
+                    }
+                    return held.client;
+                }
+                const client = createClient({ appId, serverUrl, token, options });
+                apps.set(appId, { client, token });
+                return client;
+            },
+            async revokeToken() {
+                await tokens.revoke(externalId);
+                for (const { client } of apps.values())
+                    client.cleanup();
+                apps.clear();
+            },
+        };
+    };
+    return {
+        platforms,
+        asPrincipal(externalId) {
+            let principal = principals.get(externalId);
+            if (!principal) {
+                principal = buildPrincipal(externalId);
+                principals.set(externalId, principal);
+            }
+            return principal;
+        },
+        getConfig() {
+            return { serverUrl };
+        },
+    };
+}

package/dist/platform-client.types.d.ts

@@ -0,0 +1,144 @@
+import type { Base44Client, CreateClientOptions } from "./client.types.js";
+import type { PlatformsModule } from "./modules/platforms.types.js";
+/**
+ * Configuration for creating a Base44 platform client.
+ */
+export interface CreatePlatformClientConfig {
+    /**
+     * The workspace API key used to vend tokens, holding the `user_tokens:mint` scope.
+     *
+     * This is the hot-path key: it is presented on every request that needs to act
+     * as one of your users. A mint-only key can vend tokens for principals that
+     * already exist but cannot *create* one, which is what stops it from being an
+     * impersonate-anyone primitive if it leaks.
+     */
+    mintKey: string;
+    /**
+     * The workspace API key used to create and remove principals, holding the
+     * `service_users:provision` scope.
+     *
+     * Keep it separate from `mintKey`, and keep it off any code path a request can
+     * reach. That separation is what makes deprovisioning stick: with a
+     * provision-capable key on the hot path, a removed user can be re-provisioned
+     * by the next request that mentions them, quietly undoing the offboarding.
+     *
+     * @defaultValue `mintKey`, for a single-key deployment. Workable, but weaker
+     * for the reason above.
+     */
+    provisionKey?: string;
+    /**
+     * The Base44 server URL.
+     *
+     * @defaultValue `"https://base44.app"`
+     */
+    serverUrl?: string;
+    /**
+     * Additional client options.
+     */
+    options?: CreateClientOptions;
+}
+/**
+ * A view of Base44 that acts as one of your users.
+ *
+ * Obtained from {@link PlatformClient.asPrincipal | asPrincipal()}. Holding one
+ * costs nothing — no token is vended until you ask for something.
+ */
+export interface PrincipalClient {
+    /** The identifier this principal was provisioned under. */
+    readonly externalId: string;
+    /**
+     * A Base44 client for one app, acting as this principal.
+     *
+     * This is the bridge to the rest of the SDK: the returned client is an ordinary
+     * {@link Base44Client}, so `entities`, `agents`, `functions` and the rest work
+     * exactly as documented — scoped to what this principal may see, which is
+     * usually far less than a service role.
+     *
+     * Cheap to call repeatedly. The token behind it is cached and renewed for you,
+     * and the same app gets the same client back, so a long-lived worker can hold
+     * one and a serverless handler can ask for one per request.
+     *
+     * @param appId - The app to act on.
+     * @returns A client scoped to that app, authenticated as this principal.
+     *
+     * @example
+     * ```typescript
+     * const asDana = base44.asPrincipal('user_42');
+     * const app = await asDana.forApp(appId);
+     *
+     * // Every module, with Dana's permissions rather than the workspace's.
+     * const todos = await app.entities.Todo.list();
+     * ```
+     */
+    forApp(appId: string): Promise<Base44Client>;
+    /**
+     * The raw access token for this principal, minting or renewing as needed.
+     *
+     * Most code should use {@link PrincipalClient.forApp | forApp()} instead. Reach
+     * for this when you need to authenticate a request the SDK does not make for
+     * you.
+     *
+     * Do not cache what this returns — it is already cached, and holding a copy is
+     * how a caller ends up using a token the store has since replaced.
+     *
+     * @returns A currently-valid access token.
+     *
+     * @throws {Base44Error} 404 if no principal matches, which is what an
+     * un-provisioned `externalId` looks like: minting never creates one.
+     */
+    getToken(): Promise<string>;
+    /**
+     * Forgets this principal's cached token and revokes its refresh token.
+     *
+     * Use when a user signs out of *your* platform. It does not remove the
+     * principal — the apps it built belong to it, and signing out should not hand
+     * them to the workspace owner. Removing it is
+     * {@link PlatformsModule.deprovisionPrincipal | deprovisionPrincipal()}.
+     *
+     * Only the refresh token can be revoked; a live access token remains valid for
+     * the rest of its hour. Deprovisioning is the lever that cuts one off
+     * immediately.
+     */
+    revokeToken(): Promise<void>;
+}
+/**
+ * A workspace-scoped Base44 client, for platforms that build apps on behalf of
+ * their own users.
+ *
+ * The third client factory, beside {@link createClient | createClient()} (one
+ * app, one user) and {@link createClientFromRequest | createClientFromRequest()}
+ * (inside a Base44 function). This one is scoped to a *workspace*: it manages the
+ * identities your users act as, and hands you a client per identity.
+ */
+export interface PlatformClient {
+    /** {@link PlatformsModule | Platforms module} for managing service principals. */
+    platforms: PlatformsModule;
+    /**
+     * Acts as one of your users.
+     *
+     * Mirrors `base44.asServiceRole` in shape — the same SDK, different
+     * permissions — but parameterised, because a platform has many identities
+     * rather than one privileged one.
+     *
+     * The principal must already exist;
+     * {@link PlatformsModule.provisionPrincipal | provisionPrincipal()} is
+     * idempotent and safe to call first on every request.
+     *
+     * @param externalId - The identifier the principal was provisioned under.
+     * @returns A view of Base44 that acts as that principal.
+     *
+     * @example
+     * ```typescript
+     * await base44.platforms.provisionPrincipal({ externalId: 'user_42' });
+     * const asDana = base44.asPrincipal('user_42');
+     * ```
+     */
+    asPrincipal(externalId: string): PrincipalClient;
+    /**
+     * Gets the current client configuration.
+     * @internal
+     */
+    getConfig(): {
+        serverUrl: string;
+    };
+}

package/dist/platform-client.types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/principal-tokens.d.ts

@@ -0,0 +1,64 @@
+import type { AxiosInstance } from "axios";
+/**
+ * The OAuth client id every service-principal token is issued under.
+ *
+ * Deliberately not one of Base44's MCP client prefixes — a token whose client id
+ * starts with one of those is rejected everywhere except `/mcp`.
+ */
+export declare const SERVICE_CLIENT_ID = "svc_delegate";
+/**
+ * Re-mint this long before a token's stated expiry.
+ *
+ * Access tokens are vended with an explicit one-hour lifetime, so this is a few
+ * percent of the token's life — enough that a slow call cannot land after the
+ * token it was authorized with has expired.
+ */
+export declare const REFRESH_SKEW_MS: number;
+/** A vended access token and what is needed to renew it. */
+export interface VendedToken {
+    accessToken: string;
+    refreshToken?: string;
+    /** Epoch milliseconds at which the access token stops being accepted. */
+    expiresAt: number;
+}
+interface TokenStoreConfig {
+    /** Carries the `user_tokens:mint` key. Used for minting and nothing else. */
+    mintAxios: AxiosInstance;
+    /**
+     * Carries no credential at all.
+     *
+     * `/oauth/token` and `/oauth/revoke` authenticate the *refresh token*, not the
+     * caller, so presenting a workspace key there would be sending a
+     * long-lived secret somewhere it is neither wanted nor checked.
+     */
+    oauthAxios: AxiosInstance;
+    refreshSkewMs?: number;
+}
+/**
+ * Caches one vended token per principal, and renews it before it lapses.
+ *
+ * Caching is not an optimization here. Minting is rate-limited **per workspace**,
+ * so a platform that mints on every request spends one shared budget on behalf of
+ * every user at once and starts failing under exactly the load it was built for.
+ * A vended token is good for an hour; this holds it for that hour.
+ *
+ * @internal
+ */
+export declare function createPrincipalTokenStore({ mintAxios, oauthAxios, refreshSkewMs, }: TokenStoreConfig): {
+    /**
+     * A currently-valid token for the principal, minting or renewing only when
+     * the held one is spent.
+     */
+    get(externalId: string): Promise<VendedToken>;
+    /**
+     * Drops the held token and asks Base44 to revoke its refresh token.
+     *
+     * Only the refresh half is revocable — the access token is self-contained and
+     * stays valid until it expires. To cut a principal off *now*, deprovision it:
+     * the workspace membership is re-checked on every request.
+     */
+    revoke(externalId: string): Promise<void>;
+};
+/** @internal */
+export type PrincipalTokenStore = ReturnType<typeof createPrincipalTokenStore>;
+export {};

package/dist/utils/principal-tokens.js

@@ -0,0 +1,120 @@
+/**
+ * The OAuth client id every service-principal token is issued under.
+ *
+ * Deliberately not one of Base44's MCP client prefixes — a token whose client id
+ * starts with one of those is rejected everywhere except `/mcp`.
+ */
+export const SERVICE_CLIENT_ID = "svc_delegate";
+/**
+ * Re-mint this long before a token's stated expiry.
+ *
+ * Access tokens are vended with an explicit one-hour lifetime, so this is a few
+ * percent of the token's life — enough that a slow call cannot land after the
+ * token it was authorized with has expired.
+ */
+export const REFRESH_SKEW_MS = 5 * 60 * 1000;
+/**
+ * Caches one vended token per principal, and renews it before it lapses.
+ *
+ * Caching is not an optimization here. Minting is rate-limited **per workspace**,
+ * so a platform that mints on every request spends one shared budget on behalf of
+ * every user at once and starts failing under exactly the load it was built for.
+ * A vended token is good for an hour; this holds it for that hour.
+ *
+ * @internal
+ */
+export function createPrincipalTokenStore({ mintAxios, oauthAxios, refreshSkewMs = REFRESH_SKEW_MS, }) {
+    const cache = new Map();
+    // One entry per principal currently being fetched. Without this, N concurrent
+    // requests for a user whose token just lapsed each fire their own mint — a
+    // self-inflicted burst against the very limit the cache exists to respect.
+    const inFlight = new Map();
+    const toVended = (response) => {
+        var _a;
+        const lifetimeMs = Math.max(Number(response.expires_in) || 0, 0) * 1000;
+        // Never let the skew consume the whole lifetime: a token considered stale on
+        // arrival would mint again on the next call, and again, turning the cache
+        // into a mint-per-request loop against a shared budget.
+        const skew = Math.min(refreshSkewMs, lifetimeMs / 2);
+        return {
+            accessToken: response.access_token,
+            refreshToken: (_a = response.refresh_token) !== null && _a !== void 0 ? _a : undefined,
+            expiresAt: Date.now() + lifetimeMs - skew,
+        };
+    };
+    const mint = async (externalId) => {
+        const response = await mintAxios.post("/api/service/user-tokens", { service_external_id: externalId });
+        return toVended(response);
+    };
+    const renew = async (refreshToken) => {
+        const response = await oauthAxios.post("/oauth/token", new URLSearchParams({
+            grant_type: "refresh_token",
+            refresh_token: refreshToken,
+            client_id: SERVICE_CLIENT_ID,
+        }), { headers: { "Content-Type": "application/x-www-form-urlencoded" } });
+        return toVended(response);
+    };
+    const fetchToken = async (externalId) => {
+        const held = cache.get(externalId);
+        if (held === null || held === void 0 ? void 0 : held.refreshToken) {
+            try {
+                return await renew(held.refreshToken);
+            }
+            catch (_a) {
+                // A refresh token can be revoked, expired, or invalidated by a role
+                // change. Minting is the recovery, and it re-checks everything the
+                // refresh would have — so falling through is not a way around a
+                // revocation, it just costs one extra round trip.
+            }
+        }
+        return mint(externalId);
+    };
+    return {
+        /**
+         * A currently-valid token for the principal, minting or renewing only when
+         * the held one is spent.
+         */
+        async get(externalId) {
+            const held = cache.get(externalId);
+            if (held && held.expiresAt > Date.now())
+                return held;
+            const pending = inFlight.get(externalId);
+            if (pending)
+                return pending;
+            const request = fetchToken(externalId)
+                .then((token) => {
+                cache.set(externalId, token);
+                return token;
+            })
+                .finally(() => {
+                inFlight.delete(externalId);
+            });
+            inFlight.set(externalId, request);
+            return request;
+        },
+        /**
+         * Drops the held token and asks Base44 to revoke its refresh token.
+         *
+         * Only the refresh half is revocable — the access token is self-contained and
+         * stays valid until it expires. To cut a principal off *now*, deprovision it:
+         * the workspace membership is re-checked on every request.
+         */
+        async revoke(externalId) {
+            const held = cache.get(externalId);
+            cache.delete(externalId);
+            if (!(held === null || held === void 0 ? void 0 : held.refreshToken))
+                return;
+            // Best effort: a failed revoke must not leave a caller unable to forget a
+            // principal locally.
+            try {
+                await oauthAxios.post("/oauth/revoke", new URLSearchParams({
+                    token: held.refreshToken,
+                    client_id: SERVICE_CLIENT_ID,
+                }), { headers: { "Content-Type": "application/x-www-form-urlencoded" } });
+            }
+            catch (_a) {
+                /* the local record is already gone, which is the part that matters */
+            }
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/sdk",
-  "version": "0.8.44-pr.264.d98f3ac",
+  "version": "0.8.44-pr.265.790c3c6",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",