@lucern/sdk 0.3.0-alpha.12 → 0.3.0-alpha.13

package/README.md

@@ -67,6 +67,57 @@ const identity = await lucern.identity.whoami();
 const principal: SdkPrincipalContext = identity.data;
 ```
 
+### Control-Plane Tenant Bootstrap
+
+Interactive tenant applications should resolve Clerk users through the Lucern
+control-plane identity surface before making workspace-scoped graph calls. Clerk
+proves the browser user's identity; Lucern authorization comes from the
+Permit-backed control-plane projection.
+
+```typescript
+import { createLucernClient } from "@lucern/sdk";
+
+async function createLucernForClerkUser(args: {
+  clerkUserId: string;
+  getClerkToken: () => Promise<string | null>;
+  tenantId: string;
+  workspaceId: string;
+  clerkProjectId?: string;
+}) {
+  const token = await args.getClerkToken();
+  if (!token) {
+    throw new Error("Clerk session token is required.");
+  }
+
+  const getAuthHeaders = () => ({ Authorization: `Bearer ${token}` });
+  const lucern = createLucernClient({
+    baseUrl: "https://api.lucern.ai",
+    getAuthHeaders,
+  });
+
+  const principal =
+    await lucern.controlPlane.identity.resolveInteractivePrincipal({
+      clerkId: args.clerkUserId,
+      tenantId: args.tenantId,
+      workspaceId: args.workspaceId,
+      providerProjectId: args.clerkProjectId,
+    });
+
+  return createLucernClient({
+    baseUrl: "https://api.lucern.ai",
+    getAuthHeaders,
+    authContext: principal.data,
+  });
+}
+```
+
+Use `authContext.principalId`, roles, scopes, groups, permitted tools, and
+Permit subject data as the runtime Lucern principal context. Tenant apps must
+not read legacy `users.mcRole` / `defaultTenantId` fields as authorization, and
+they must not call `components.controlPlane.migration` from application code.
+Provisioning and backfills can use migration APIs; runtime bootstrapping uses
+`controlPlane.identity.resolveInteractivePrincipal(...)`.
+
 ## The Full Developer Journey
 
 This walkthrough mirrors what a developer building an AI-powered code review system would experience in a real coding session. Every API call is something you would actually use.

package/dist/accessControl.d.ts

@@ -3,6 +3,7 @@ import { GatewayClientConfig } from './coreClient.js';
 import { PolicyEvaluationInput, PolicyDecisionRecord } from './identityClient.js';
 import { SessionPrincipalType } from './contracts/auth-session.contract.js';
 import { JsonObject } from './types.js';
+import './control-plane.js';
 import './contracts/workflow-runtime.contract.js';
 import './contracts/lens-workflow.contract.js';
 import './contracts/lens-filter.contract.js';

package/dist/accessControl.js

@@ -29,14 +29,14 @@ function requireString(value, reason, label) {
   }
   return normalized;
 }
-function requirePrincipalType(principalType) {
-  if (!principalType) {
+function requirePrincipalType(principalType2) {
+  if (!principalType2) {
     throw new LucernSdkAuthContextError(
       "principal_missing",
       "Canonical Lucern SDK auth context is missing principalType."
     );
   }
-  return principalType;
+  return principalType2;
 }
 function requireAuthMode(authMode) {
   if (!authMode) {
@@ -82,7 +82,7 @@ function normalizeCanonicalLucernAuthContext(input) {
   );
   const roles = cleanStringList(input.roles);
   const scopes = cleanStringList(input.scopes);
-  const principalType = requirePrincipalType(input.principalType);
+  const principalType2 = requirePrincipalType(input.principalType);
   const authMode = requireAuthMode(input.authMode);
   const roleBasedInteractiveAuth = authMode === "interactive_user" && roles.length > 0;
   if (roles.length === 0 || scopes.length === 0 && !roleBasedInteractiveAuth) {
@@ -111,7 +111,7 @@ function normalizeCanonicalLucernAuthContext(input) {
     principalId,
     tenantId,
     workspaceId,
-    principalType,
+    principalType: principalType2,
     authMode,
     roles,
     scopes,
@@ -600,6 +600,109 @@ function listResultFromEnvelope(data, legacyKey) {
   );
 }
 
+// src/control-plane.ts
+var LucernControlPlaneIdentityError = class extends Error {
+  reason;
+  principalStatus;
+  tenantStatus;
+  workspaceStatus;
+  details;
+  constructor(failure) {
+    super(failure.message);
+    this.name = "LucernControlPlaneIdentityError";
+    this.reason = failure.reason;
+    this.principalStatus = failure.principalStatus;
+    this.tenantStatus = failure.tenantStatus;
+    this.workspaceStatus = failure.workspaceStatus;
+    this.details = failure.details;
+  }
+};
+function cleanString2(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
+}
+function stringList(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return [
+    ...new Set(
+      value.filter((entry) => typeof entry === "string").map((entry) => entry.trim()).filter(Boolean)
+    )
+  ];
+}
+function principalType(value) {
+  switch (value) {
+    case "service":
+    case "service_principal":
+      return "service";
+    case "agent":
+      return "agent";
+    case "group":
+      return "group";
+    case "external_viewer":
+    case "external_stakeholder":
+      return "external_viewer";
+    default:
+      return "human";
+  }
+}
+function adminFlags(roles) {
+  const normalized = roles.map((role) => role.toLowerCase());
+  const isPlatformAdmin = normalized.includes("platform_admin");
+  const isTenantAdmin = isPlatformAdmin || normalized.includes("tenant_admin");
+  const isWorkspaceAdmin = isTenantAdmin || normalized.includes("workspace_admin") || normalized.includes("workspace_owner");
+  return { isPlatformAdmin, isTenantAdmin, isWorkspaceAdmin };
+}
+function normalizeResolvedInteractivePrincipal(payload) {
+  if ("ok" in payload && payload.ok === false) {
+    throw new LucernControlPlaneIdentityError(payload);
+  }
+  const principalId = cleanString2(payload.principalId);
+  const clerkId = cleanString2(payload.clerkId);
+  const tenantId = cleanString2(payload.tenantId);
+  if (!principalId || !clerkId || !tenantId) {
+    throw new LucernControlPlaneIdentityError({
+      ok: false,
+      reason: "resolver_unavailable",
+      message: "Control-plane principal resolver returned an incomplete principal context.",
+      principalStatus: payload.principalStatus ?? "missing",
+      tenantStatus: payload.tenantStatus,
+      workspaceStatus: payload.workspaceStatus
+    });
+  }
+  const roles = stringList(payload.roles);
+  const scopes = stringList(payload.scopes);
+  const workspaceId = cleanString2(payload.workspaceId) ?? null;
+  const flags = adminFlags(roles);
+  return {
+    principalId,
+    principalType: principalType(payload.principalType),
+    clerkId,
+    tenantId,
+    workspaceId,
+    roles,
+    scopes,
+    groupIds: stringList(payload.groupIds),
+    permittedToolNames: stringList(payload.permittedToolNames),
+    permittedPackKeys: stringList(payload.permittedPackKeys),
+    principalStatus: cleanString2(payload.principalStatus) ?? "active",
+    tenantStatus: cleanString2(payload.tenantStatus) ?? "active",
+    workspaceStatus: cleanString2(payload.workspaceStatus) ?? (workspaceId ? "active" : "none"),
+    isPlatformAdmin: typeof payload.isPlatformAdmin === "boolean" ? payload.isPlatformAdmin : flags.isPlatformAdmin,
+    isTenantAdmin: typeof payload.isTenantAdmin === "boolean" ? payload.isTenantAdmin : flags.isTenantAdmin,
+    isWorkspaceAdmin: typeof payload.isWorkspaceAdmin === "boolean" ? payload.isWorkspaceAdmin : flags.isWorkspaceAdmin,
+    permit: {
+      subject: cleanString2(payload.permit?.subject) ?? principalId,
+      tenant: cleanString2(payload.permit?.tenant) ?? tenantId,
+      ...workspaceId ? { workspace: cleanString2(payload.permit?.workspace) ?? workspaceId } : {}
+    },
+    authMode: "interactive_user",
+    sessionId: payload.sessionId,
+    delegatedBy: payload.delegatedBy,
+    expiresAt: payload.expiresAt
+  };
+}
+
 // src/identityClient.ts
 function createIdentityWhoamiClient(config = {}) {
   const gateway = createGatewayRequestClient(config);
@@ -667,13 +770,25 @@ function createIdentityClient(config = {}) {
         (response) => mapGatewayData(response, (data) => ({
           principalId: data.principalId,
           principalType: data.principalType,
+          clerkId: data.clerkId,
           tenantId: data.tenantId ?? null,
           workspaceId: data.workspaceId ?? null,
           scopes: Array.isArray(data.scopes) ? data.scopes : [],
           roles: Array.isArray(data.roles) ? data.roles : [],
+          groupIds: Array.isArray(data.groupIds) ? data.groupIds : [],
+          permittedToolNames: Array.isArray(data.permittedToolNames) ? data.permittedToolNames : [],
+          permittedPackKeys: Array.isArray(data.permittedPackKeys) ? data.permittedPackKeys : [],
+          principalStatus: data.principalStatus,
+          tenantStatus: data.tenantStatus,
+          workspaceStatus: data.workspaceStatus,
           isPlatformAdmin: data.isPlatformAdmin === true,
           isTenantAdmin: data.isTenantAdmin === true,
           isWorkspaceAdmin: data.isWorkspaceAdmin === true,
+          permit: data.permit ?? (data.tenantId ? {
+            subject: data.principalId,
+            tenant: data.tenantId,
+            ...data.workspaceId ? { workspace: data.workspaceId } : {}
+          } : void 0),
           authMode: data.authMode,
           sessionId: data.sessionId,
           delegatedBy: data.delegatedBy,
@@ -681,6 +796,19 @@ function createIdentityClient(config = {}) {
         }))
       );
     },
+    /**
+     * Resolve a Clerk subject through the tenant control-plane Permit projection.
+     * @deprecated Prefer lucern.controlPlane.identity.resolveInteractivePrincipal().
+     */
+    async resolveInteractivePrincipal(input) {
+      return gateway.request({
+        path: "/api/platform/v1/control-plane/identity/resolve-interactive-principal",
+        method: "POST",
+        body: input
+      }).then(
+        (response) => mapGatewayData(response, normalizeResolvedInteractivePrincipal)
+      );
+    },
     /**
      * List principals in the current identity scope.
      */
@@ -877,7 +1005,7 @@ var LucernAccessControlError = class extends LucernSdkAuthContextError {
     this.policyDecision = policyDecision;
   }
 };
-function cleanString2(value) {
+function cleanString3(value) {
   const normalized = value?.trim();
   return normalized ? normalized : void 0;
 }
@@ -892,7 +1020,7 @@ function cleanStringList2(values) {
   ];
 }
 function requireString2(value, reason, label) {
-  const normalized = cleanString2(value);
+  const normalized = cleanString3(value);
   if (!normalized) {
     throw new LucernAccessControlError(
       reason,
@@ -901,13 +1029,19 @@ function requireString2(value, reason, label) {
   }
   return normalized;
 }
-function normalizePrincipalType(principalType) {
-  if (principalType === "agent") {
+function normalizePrincipalType(principalType2) {
+  if (principalType2 === "agent") {
     return "agent";
   }
-  if (principalType === "service") {
+  if (principalType2 === "service") {
     return "service";
   }
+  if (principalType2 === "group") {
+    return "group";
+  }
+  if (principalType2 === "external_viewer") {
+    return "external_viewer";
+  }
   return "human";
 }
 function aliasKey(alias) {
@@ -916,15 +1050,15 @@ function aliasKey(alias) {
 function normalizeAliases(input, canonicalClerkUserId) {
   const aliases = /* @__PURE__ */ new Map();
   for (const alias of input ?? []) {
-    const externalSubjectId = cleanString2(alias.externalSubjectId);
+    const externalSubjectId = cleanString3(alias.externalSubjectId);
     if (!externalSubjectId) {
       continue;
     }
     const normalized = {
-      provider: cleanString2(alias.provider) ?? "clerk",
-      providerProjectId: cleanString2(alias.providerProjectId),
+      provider: cleanString3(alias.provider) ?? "clerk",
+      providerProjectId: cleanString3(alias.providerProjectId),
       externalSubjectId,
-      status: cleanString2(alias.status)
+      status: cleanString3(alias.status)
     };
     aliases.set(aliasKey(normalized), normalized);
   }
@@ -969,10 +1103,10 @@ function normalizeCanonicalPrincipalIdentity(input, options = {}) {
     "principal_missing",
     "principalId"
   );
-  const principalType = normalizePrincipalType(principalInput.principalType);
-  const observedClerkId = cleanString2(options.observedClerkId);
-  const canonicalClerkUserId = cleanString2(principalInput.canonicalClerkUserId) ?? cleanString2(principalInput.clerkId);
-  if (principalType === "human" && !canonicalClerkUserId) {
+  const principalType2 = normalizePrincipalType(principalInput.principalType);
+  const observedClerkId = cleanString3(options.observedClerkId);
+  const canonicalClerkUserId = cleanString3(principalInput.canonicalClerkUserId) ?? cleanString3(principalInput.clerkId);
+  if (principalType2 === "human" && !canonicalClerkUserId) {
     throw new LucernAccessControlError(
       "clerk_alias_missing",
       "Human principals require one canonical Clerk user id."
@@ -994,11 +1128,11 @@ function normalizeCanonicalPrincipalIdentity(input, options = {}) {
   }
   return {
     principalId,
-    principalType,
+    principalType: principalType2,
     canonicalClerkUserId,
     clerkIdentityAliases: aliases,
-    tenantId: cleanString2(principalInput.tenantId),
-    workspaceId: cleanString2(principalInput.workspaceId),
+    tenantId: cleanString3(principalInput.tenantId),
+    workspaceId: cleanString3(principalInput.workspaceId),
     roles: cleanStringList2(principalInput.roles),
     scopes: cleanStringList2(principalInput.scopes)
   };
@@ -1023,7 +1157,7 @@ function buildPolicyInput(identity, input) {
     "tenant_missing",
     "tenantId"
   );
-  const workspaceId = cleanString2(input.workspaceId ?? identity.workspaceId);
+  const workspaceId = cleanString3(input.workspaceId ?? identity.workspaceId);
   if (resourceRequiresWorkspace(input.resource) && !workspaceId) {
     throw new LucernAccessControlError(
       "workspace_missing",