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

package/dist/client.js

@@ -32,14 +32,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) {
@@ -85,7 +85,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) {
@@ -114,7 +114,7 @@ function normalizeCanonicalLucernAuthContext(input) {
     principalId,
     tenantId,
     workspaceId,
-    principalType,
+    principalType: principalType2,
     authMode,
     roles,
     scopes,
@@ -1103,6 +1103,128 @@ 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 cleanString3(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 = cleanString3(payload.principalId);
+  const clerkId = cleanString3(payload.clerkId);
+  const tenantId = cleanString3(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 = cleanString3(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: cleanString3(payload.principalStatus) ?? "active",
+    tenantStatus: cleanString3(payload.tenantStatus) ?? "active",
+    workspaceStatus: cleanString3(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: cleanString3(payload.permit?.subject) ?? principalId,
+      tenant: cleanString3(payload.permit?.tenant) ?? tenantId,
+      ...workspaceId ? { workspace: cleanString3(payload.permit?.workspace) ?? workspaceId } : {}
+    },
+    authMode: "interactive_user",
+    sessionId: payload.sessionId,
+    delegatedBy: payload.delegatedBy,
+    expiresAt: payload.expiresAt
+  };
+}
+function createControlPlaneIdentityClient(config = {}) {
+  const gateway = createGatewayRequestClient(config);
+  return {
+    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)
+      );
+    }
+  };
+}
+function createControlPlaneClient(config = {}) {
+  return {
+    identity: createControlPlaneIdentityClient(config)
+  };
+}
+
 // src/identityClient.ts
 function createIdentityWhoamiClient(config = {}) {
   const gateway = createGatewayRequestClient(config);
@@ -1170,13 +1292,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,
@@ -1184,6 +1318,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.
      */
@@ -1380,7 +1527,7 @@ var LucernAccessControlError = class extends LucernSdkAuthContextError {
     this.policyDecision = policyDecision;
   }
 };
-function cleanString3(value) {
+function cleanString4(value) {
   const normalized = value?.trim();
   return normalized ? normalized : void 0;
 }
@@ -1395,7 +1542,7 @@ function cleanStringList2(values) {
   ];
 }
 function requireString2(value, reason, label) {
-  const normalized = cleanString3(value);
+  const normalized = cleanString4(value);
   if (!normalized) {
     throw new LucernAccessControlError(
       reason,
@@ -1404,13 +1551,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) {
@@ -1419,15 +1572,15 @@ function aliasKey(alias) {
 function normalizeAliases(input, canonicalClerkUserId) {
   const aliases = /* @__PURE__ */ new Map();
   for (const alias of input ?? []) {
-    const externalSubjectId = cleanString3(alias.externalSubjectId);
+    const externalSubjectId = cleanString4(alias.externalSubjectId);
     if (!externalSubjectId) {
       continue;
     }
     const normalized = {
-      provider: cleanString3(alias.provider) ?? "clerk",
-      providerProjectId: cleanString3(alias.providerProjectId),
+      provider: cleanString4(alias.provider) ?? "clerk",
+      providerProjectId: cleanString4(alias.providerProjectId),
       externalSubjectId,
-      status: cleanString3(alias.status)
+      status: cleanString4(alias.status)
     };
     aliases.set(aliasKey(normalized), normalized);
   }
@@ -1472,10 +1625,10 @@ function normalizeCanonicalPrincipalIdentity(input, options = {}) {
     "principal_missing",
     "principalId"
   );
-  const principalType = normalizePrincipalType(principalInput.principalType);
-  const observedClerkId = cleanString3(options.observedClerkId);
-  const canonicalClerkUserId = cleanString3(principalInput.canonicalClerkUserId) ?? cleanString3(principalInput.clerkId);
-  if (principalType === "human" && !canonicalClerkUserId) {
+  const principalType2 = normalizePrincipalType(principalInput.principalType);
+  const observedClerkId = cleanString4(options.observedClerkId);
+  const canonicalClerkUserId = cleanString4(principalInput.canonicalClerkUserId) ?? cleanString4(principalInput.clerkId);
+  if (principalType2 === "human" && !canonicalClerkUserId) {
     throw new LucernAccessControlError(
       "clerk_alias_missing",
       "Human principals require one canonical Clerk user id."
@@ -1497,11 +1650,11 @@ function normalizeCanonicalPrincipalIdentity(input, options = {}) {
   }
   return {
     principalId,
-    principalType,
+    principalType: principalType2,
     canonicalClerkUserId,
     clerkIdentityAliases: aliases,
-    tenantId: cleanString3(principalInput.tenantId),
-    workspaceId: cleanString3(principalInput.workspaceId),
+    tenantId: cleanString4(principalInput.tenantId),
+    workspaceId: cleanString4(principalInput.workspaceId),
     roles: cleanStringList2(principalInput.roles),
     scopes: cleanStringList2(principalInput.scopes)
   };
@@ -1526,7 +1679,7 @@ function buildPolicyInput(identity, input) {
     "tenant_missing",
     "tenantId"
   );
-  const workspaceId = cleanString3(input.workspaceId ?? identity.workspaceId);
+  const workspaceId = cleanString4(input.workspaceId ?? identity.workspaceId);
   if (resourceRequiresWorkspace(input.resource) && !workspaceId) {
     throw new LucernAccessControlError(
       "workspace_missing",
@@ -2926,12 +3079,12 @@ function createGraphClient(config = {}) {
 }
 
 // src/topicsClient.ts
-function cleanString4(value) {
+function cleanString5(value) {
   return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
 }
 function normalizeTopicRecord(value) {
   const record = asRecord(value);
-  const topicId = cleanString4(record.topicId) ?? cleanString4(record.id) ?? cleanString4(record._id);
+  const topicId = cleanString5(record.topicId) ?? cleanString5(record.id) ?? cleanString5(record._id);
   return withTopicAlias({
     ...record,
     ...topicId ? { topicId } : {}
@@ -4144,7 +4297,7 @@ function createEmbeddingsClient(config = {}) {
 }
 
 // src/contextClient.ts
-function cleanString5(value) {
+function cleanString6(value) {
   return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
 }
 function cleanNumber(value) {
@@ -4156,11 +4309,11 @@ function cleanBoolean(value) {
 function buildCompileContextRequest(topicIdOrInput = {}, input = {}) {
   const effectiveInput = typeof topicIdOrInput === "string" ? input : topicIdOrInput;
   const payload = {};
-  const topicId = typeof topicIdOrInput === "string" ? cleanString5(topicIdOrInput) : cleanString5(effectiveInput.topicId);
+  const topicId = typeof topicIdOrInput === "string" ? cleanString6(topicIdOrInput) : cleanString6(effectiveInput.topicId);
   if (topicId) {
     payload.topicId = topicId;
   }
-  const query5 = cleanString5(effectiveInput.query);
+  const query5 = cleanString6(effectiveInput.query);
   if (query5) {
     payload.query = query5;
   }
@@ -4168,7 +4321,7 @@ function buildCompileContextRequest(topicIdOrInput = {}, input = {}) {
   if (budget !== void 0) {
     payload.budget = budget;
   }
-  const ranking = cleanString5(effectiveInput.ranking) ?? cleanString5(effectiveInput.rankingProfile);
+  const ranking = cleanString6(effectiveInput.ranking) ?? cleanString6(effectiveInput.rankingProfile);
   if (ranking) {
     payload.ranking = ranking;
   }
@@ -4184,7 +4337,7 @@ function buildCompileContextRequest(topicIdOrInput = {}, input = {}) {
   if (includeEntities !== void 0) {
     payload.includeEntities = includeEntities;
   }
-  const mode = cleanString5(effectiveInput.mode);
+  const mode = cleanString6(effectiveInput.mode);
   if (mode) {
     payload.mode = mode;
   }
@@ -4192,11 +4345,11 @@ function buildCompileContextRequest(topicIdOrInput = {}, input = {}) {
   if (includeFailures !== void 0) {
     payload.includeFailures = includeFailures;
   }
-  const worktreeId = cleanString5(effectiveInput.worktreeId);
+  const worktreeId = cleanString6(effectiveInput.worktreeId);
   if (worktreeId) {
     payload.worktreeId = worktreeId;
   }
-  const sessionId = cleanString5(effectiveInput.sessionId);
+  const sessionId = cleanString6(effectiveInput.sessionId);
   if (sessionId) {
     payload.sessionId = sessionId;
   }
@@ -5273,6 +5426,7 @@ var CONTRACTS = {
   "remove_edges_between": { method: "DELETE", path: "/edges/between", kind: "mutation", idempotent: true, surfaceIntent: "mcp_analysis" },
   "remove_lens_from_topic": { method: "DELETE", path: "/lenses/apply", kind: "mutation", idempotent: true, surfaceIntent: "mcp_workflow" },
   "resolve_effective_ontology": { method: "POST", path: "/ontologies/effective", kind: "query", idempotent: false, surfaceIntent: "mcp_workflow" },
+  "resolve_interactive_principal": { method: "POST", path: "/control-plane/identity/resolve-interactive-principal", kind: "query", idempotent: false, surfaceIntent: "mcp_core" },
   "run_graph_intelligence_query": { method: "POST", path: "/graph-intelligence/run", kind: "query", idempotent: false, surfaceIntent: "mcp_analysis" },
   "search_beliefs": { method: "POST", path: "/beliefs/search", kind: "query", idempotent: false, surfaceIntent: "mcp_core" },
   "search_evidence": { method: "POST", path: "/evidence/search", kind: "query", idempotent: false, surfaceIntent: "mcp_core" },
@@ -5655,6 +5809,9 @@ function createFunctionSurfaceClient(config = {}) {
     resolveEffectiveOntology(input = {}, idempotencyKey) {
       return execute("resolve_effective_ontology", input, idempotencyKey);
     },
+    resolveInteractivePrincipal(input = {}, idempotencyKey) {
+      return execute("resolve_interactive_principal", input, idempotencyKey);
+    },
     runGraphIntelligenceQuery(input = {}, idempotencyKey) {
       return execute("run_graph_intelligence_query", input, idempotencyKey);
     },
@@ -5915,7 +6072,7 @@ var ORG_GRAPH_SEARCH_FIELDS = [
   "cursor",
   "provenanceScope"
 ];
-function cleanString6(value, label) {
+function cleanString7(value, label) {
   const normalized = value?.trim();
   if (!normalized) {
     throw new Error(`${label} is required`);
@@ -5937,9 +6094,9 @@ function searchBody(input) {
     "orgGraphSearch.search"
   );
   return {
-    tenantId: cleanString6(input.tenantId, "tenantId"),
-    workspaceId: cleanString6(input.workspaceId, "workspaceId"),
-    query: cleanString6(input.query, "query"),
+    tenantId: cleanString7(input.tenantId, "tenantId"),
+    workspaceId: cleanString7(input.workspaceId, "workspaceId"),
+    query: cleanString7(input.query, "query"),
     nodeTypes: input.nodeTypes,
     minConfidence: input.minConfidence,
     limit: input.limit,
@@ -5949,8 +6106,8 @@ function searchBody(input) {
 }
 function listQuery2(input) {
   return {
-    tenantId: cleanString6(input.tenantId, "tenantId"),
-    workspaceId: cleanString6(input.workspaceId, "workspaceId"),
+    tenantId: cleanString7(input.tenantId, "tenantId"),
+    workspaceId: cleanString7(input.workspaceId, "workspaceId"),
     nodeTypes: input.nodeTypes?.join(","),
     minConfidence: input.minConfidence,
     limit: input.limit,
@@ -5984,8 +6141,8 @@ function createOrgGraphSearchClient(config = {}) {
       return gateway.request({
         path: `/api/platform/v1/org-graph-search/nodes/${nodePath}${toQueryString(
           {
-            tenantId: cleanString6(input.tenantId, "tenantId"),
-            workspaceId: cleanString6(input.workspaceId, "workspaceId"),
+            tenantId: cleanString7(input.tenantId, "tenantId"),
+            workspaceId: cleanString7(input.workspaceId, "workspaceId"),
             globalId: nodeId ? void 0 : globalId
           }
         )}`
@@ -6950,7 +7107,7 @@ function createToolRegistryClient(config = {}) {
 }
 
 // src/version.ts
-var LUCERN_SDK_VERSION = "0.3.0-alpha.11";
+var LUCERN_SDK_VERSION = "0.3.0-alpha.13";
 
 // src/workflowClient.ts
 function normalizeLensQuery(value) {
@@ -7427,6 +7584,7 @@ function createLucernClient(config = {}) {
   const ontologyLinksClient = createOntologyLinksClient(gatewayConfig);
   const orgGraphSearchClient = createOrgGraphSearchClient(gatewayConfig);
   const functionSurfaceClient = createFunctionSurfaceClient(gatewayConfig);
+  const controlPlaneClient = createControlPlaneClient(gatewayConfig);
   const toolRegistryClient = createToolRegistryClient(gatewayConfig);
   const modelRuntimeClient = createModelRuntimeClient(gatewayConfig);
   const packsClient = createPacksClient(gatewayConfig);
@@ -9090,9 +9248,16 @@ function createLucernClient(config = {}) {
       disable: packsClient.disable
     },
     nodes: nodesNamespace,
+    controlPlane: {
+      identity: {
+        resolveInteractivePrincipal: controlPlaneClient.identity.resolveInteractivePrincipal
+      },
+      raw: controlPlaneClient
+    },
     identity: {
       ...identityFacade,
       access: accessControlClient,
+      resolveInteractivePrincipal: identityClient.resolveInteractivePrincipal,
       evaluatePolicy: identityClient.evaluatePolicy,
       recordPolicyDecision: identityClient.recordPolicyDecision,
       putSecretReference: identityClient.putSecretReference,
@@ -9137,6 +9302,7 @@ function createLucernClient(config = {}) {
       ontologyLinks: ontologyLinksClient,
       orgGraphSearch: orgGraphSearchClient,
       functionSurface: functionSurfaceClient,
+      controlPlane: controlPlaneClient,
       toolRegistry: toolRegistryClient,
       modelRuntime: modelRuntimeClient,
       packs: packsClient,