@lucern/sdk 0.3.0-alpha.2 → 0.3.0-alpha.3

package/dist/gatewayFacades.js

@@ -1,3 +1,169 @@
+// src/authContext.ts
+var LucernSdkAuthContextError = class extends Error {
+  reason;
+  constructor(reason, message) {
+    super(message);
+    this.name = "LucernSdkAuthContextError";
+    this.reason = reason;
+  }
+};
+function cleanString(value) {
+  const normalized = value?.trim();
+  return normalized ? normalized : void 0;
+}
+function cleanStringList(values) {
+  if (!values) {
+    return [];
+  }
+  return values.map((value) => value.trim()).filter(
+    (value, index, list) => value.length > 0 && list.indexOf(value) === index
+  );
+}
+function requireString(value, reason, label) {
+  const normalized = cleanString(value);
+  if (!normalized) {
+    throw new LucernSdkAuthContextError(
+      reason,
+      `Canonical Lucern SDK auth context is missing ${label}.`
+    );
+  }
+  return normalized;
+}
+function requirePrincipalType(principalType) {
+  if (!principalType) {
+    throw new LucernSdkAuthContextError(
+      "principal_missing",
+      "Canonical Lucern SDK auth context is missing principalType."
+    );
+  }
+  return principalType;
+}
+function requireAuthMode(authMode) {
+  if (!authMode) {
+    throw new LucernSdkAuthContextError(
+      "principal_missing",
+      "Canonical Lucern SDK auth context is missing authMode."
+    );
+  }
+  return authMode;
+}
+function ensurePermitMatch(args) {
+  const actual = cleanString(args.actual);
+  if (actual && actual !== args.expected) {
+    throw new LucernSdkAuthContextError(
+      "policy_denied",
+      `Canonical Lucern SDK auth context has conflicting Permit ${args.field}.`
+    );
+  }
+}
+function normalizeCanonicalLucernAuthContext(input) {
+  if (!input) {
+    throw new LucernSdkAuthContextError(
+      "principal_missing",
+      "Canonical Lucern SDK auth context is required."
+    );
+  }
+  if (input.policyDecision === "deny") {
+    throw new LucernSdkAuthContextError(
+      "policy_denied",
+      "Canonical Lucern SDK auth context carries a denied policy decision."
+    );
+  }
+  const principalId = requireString(
+    input.principalId,
+    "principal_missing",
+    "principalId"
+  );
+  const tenantId = requireString(input.tenantId, "tenant_missing", "tenantId");
+  const workspaceId = requireString(
+    input.workspaceId,
+    "workspace_missing",
+    "workspaceId"
+  );
+  const roles = cleanStringList(input.roles);
+  const scopes = cleanStringList(input.scopes);
+  if (roles.length === 0 || scopes.length === 0) {
+    throw new LucernSdkAuthContextError(
+      "membership_missing",
+      "Canonical Lucern SDK auth context requires non-empty roles and scopes."
+    );
+  }
+  const principalType = requirePrincipalType(input.principalType);
+  const authMode = requireAuthMode(input.authMode);
+  const subject = cleanString(input.permit?.subject) ?? principalId;
+  const tenant = cleanString(input.permit?.tenant) ?? tenantId;
+  const workspace = cleanString(input.permit?.workspace) ?? workspaceId;
+  ensurePermitMatch({
+    field: "subject",
+    expected: principalId,
+    actual: subject
+  });
+  ensurePermitMatch({ field: "tenant", expected: tenantId, actual: tenant });
+  ensurePermitMatch({
+    field: "workspace",
+    expected: workspaceId,
+    actual: workspace
+  });
+  const context = input.permit?.context ? { ...input.permit.context } : void 0;
+  return {
+    clerkId: cleanString(input.clerkId),
+    principalId,
+    tenantId,
+    workspaceId,
+    principalType,
+    authMode,
+    roles,
+    scopes,
+    delegationChain: input.delegationChain ? [...input.delegationChain] : [],
+    policyTraceId: cleanString(input.policyTraceId),
+    correlationId: cleanString(input.correlationId),
+    membershipId: cleanString(input.membershipId),
+    permit: {
+      subject,
+      tenant,
+      workspace,
+      resource: cleanString(input.permit?.resource),
+      action: cleanString(input.permit?.action),
+      relation: cleanString(input.permit?.relation),
+      context
+    }
+  };
+}
+function createCanonicalAuthHeaders(authContext) {
+  const headers = {
+    "x-lucern-principal-id": authContext.principalId,
+    "x-lucern-principal-type": authContext.principalType,
+    "x-lucern-tenant": authContext.tenantId,
+    "x-lucern-tenant-id": authContext.tenantId,
+    "x-lucern-workspace": authContext.workspaceId,
+    "x-lucern-workspace-id": authContext.workspaceId,
+    "x-lucern-auth-mode": authContext.authMode,
+    "x-lucern-roles": authContext.roles.join(","),
+    "x-lucern-scopes": authContext.scopes.join(","),
+    "x-lucern-permit-context": JSON.stringify(authContext.permit)
+  };
+  if (authContext.clerkId) {
+    headers["x-lucern-clerk-id"] = authContext.clerkId;
+    headers["x-lucern-user-id"] = authContext.clerkId;
+  }
+  if (authContext.delegationChain.length > 0) {
+    headers["x-lucern-delegation-chain"] = JSON.stringify(
+      authContext.delegationChain
+    );
+  }
+  if (authContext.policyTraceId) {
+    headers["x-lucern-policy-trace-id"] = authContext.policyTraceId;
+  }
+  if (authContext.correlationId) {
+    headers["x-correlation-id"] = authContext.correlationId;
+    headers["x-lucern-correlation-id"] = authContext.correlationId;
+  }
+  if (authContext.membershipId) {
+    headers["x-lucern-membership-id"] = authContext.membershipId;
+  }
+  return headers;
+}
+
 // src/coreClient.ts
 var LucernApiError = class extends Error {
   code;
@@ -154,16 +320,41 @@ function readPolicySummaryFromDetails(details) {
   }
   return null;
 }
+async function resolveConfiguredAuthContext(authContext) {
+  if (typeof authContext === "function") {
+    return await authContext();
+  }
+  return authContext;
+}
+function mergeHeaderRecord(base, addition) {
+  const headers = new Headers(base);
+  for (const [key, value] of Object.entries(addition)) {
+    const existing = headers.get(key);
+    if (existing !== null && existing !== value) {
+      throw new LucernSdkAuthContextError(
+        "policy_denied",
+        `Canonical Lucern SDK auth context conflicts with existing ${key} header.`
+      );
+    }
+    headers.set(key, value);
+  }
+  return Object.fromEntries(headers.entries());
+}
 function createGatewayRequestClient(config = {}) {
   const fetchImpl = config.fetchImpl ?? fetch;
   const baseUrl = config.baseUrl?.replace(/\/+$/, "") ?? "";
   const maxRetries = config.maxRetries ?? 2;
   const requestIdFactory = config.requestIdFactory ?? (() => generatePortableRequestId());
   async function resolveAuthHeaders() {
-    if (!config.getAuthHeaders) {
-      return {};
+    const base = config.getAuthHeaders ? await config.getAuthHeaders() : {};
+    const authContextInput = await resolveConfiguredAuthContext(
+      config.authContext
+    );
+    if (!authContextInput && !config.requireCanonicalAuthContext) {
+      return base;
     }
-    return await config.getAuthHeaders();
+    const authContext = normalizeCanonicalLucernAuthContext(authContextInput);
+    return mergeHeaderRecord(base, createCanonicalAuthHeaders(authContext));
   }
   async function fetchWithTimeout(url, init, timeoutMs) {
     const controller = new AbortController();
@@ -338,11 +529,11 @@ function createGatewayRequestClient(config = {}) {
 function asRecord(value) {
   return value && typeof value === "object" ? value : {};
 }
-function cleanString(value) {
+function cleanString2(value) {
   return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
 }
 function normalizeVerificationStatus(value) {
-  const status = cleanString(value);
+  const status = cleanString2(value);
   if (!status) {
     return void 0;
   }
@@ -358,20 +549,20 @@ function cloneWith(value, patch) {
   return { ...value, ...patch };
 }
 function resolveTopicId(value) {
-  return cleanString(value.topicId);
+  return cleanString2(value.topicId);
 }
 function resolveText(value) {
-  return cleanString(value.text) ?? cleanString(value.canonicalText);
+  return cleanString2(value.text) ?? cleanString2(value.canonicalText);
 }
 function withTopicAlias(value) {
-  const topicId = cleanString(value.topicId) ?? void 0;
+  const topicId = cleanString2(value.topicId) ?? void 0;
   if (!topicId) {
     return value;
   }
   return cloneWith(value, { topicId });
 }
 function withTextAlias(value) {
-  const text = cleanString(value.text) ?? cleanString(value.canonicalText) ?? void 0;
+  const text = cleanString2(value.text) ?? cleanString2(value.canonicalText) ?? void 0;
   if (!text) {
     return value;
   }
@@ -401,7 +592,7 @@ function normalizeNodeVerificationStatus(value) {
   return normalizeVerificationStatus(value);
 }
 function normalizeTopicQuery(value) {
-  const topicId = cleanString(value.topicId);
+  const topicId = cleanString2(value.topicId);
   if (!topicId) {
     return value;
   }
@@ -849,6 +1040,39 @@ function createGraphClient(config = {}) {
   };
 }
 
+// src/boundaryClientSurface.ts
+function cleanOptionalString(value) {
+  const normalized = value?.trim();
+  return normalized ? normalized : void 0;
+}
+function cleanRequiredString(value, label) {
+  const normalized = cleanOptionalString(value);
+  if (!normalized) {
+    throw new Error(`${label} is required`);
+  }
+  return normalized;
+}
+function assertKnownKeys(input, allowed, operation) {
+  const allowedSet = new Set(allowed);
+  const unknownKeys = Object.keys(input).filter((key) => !allowedSet.has(key));
+  if (unknownKeys.length > 0) {
+    throw new Error(
+      `${operation} received unsupported field(s): ${unknownKeys.join(", ")}`
+    );
+  }
+}
+function knownPayload(input, allowed, operation) {
+  assertKnownKeys(input, allowed, operation);
+  return { ...input };
+}
+function listResultFromEnvelope(data, legacyKey) {
+  const record = data && typeof data === "object" ? data : {};
+  return createListResult(
+    Array.isArray(record[legacyKey]) ? record[legacyKey] : Array.isArray(data) ? data : [],
+    legacyKey
+  );
+}
+
 // src/identityClient.ts
 function createIdentityWhoamiClient(config = {}) {
   const gateway = createGatewayRequestClient(config);
@@ -860,6 +1084,37 @@ function createIdentityWhoamiClient(config = {}) {
     }
   };
 }
+var TENANT_IDENTITY_FIELDS = [
+  "tenantId",
+  "workspaceId",
+  "principalId",
+  "integrationKey",
+  "secretRef",
+  "policySubject",
+  "policyAction",
+  "policyResource",
+  "decision",
+  "config",
+  "configKey",
+  "configValue",
+  "provider",
+  "status",
+  "metadata",
+  "limit",
+  "cursor"
+];
+function tenantIdentityQuery(input) {
+  return {
+    tenantId: cleanRequiredString(input.tenantId, "tenantId"),
+    workspaceId: input.workspaceId,
+    principalId: input.principalId,
+    limit: input.limit,
+    cursor: input.cursor
+  };
+}
+function tenantIdentityBody(input, operation) {
+  return knownPayload(input, TENANT_IDENTITY_FIELDS, operation);
+}
 function createIdentityClient(config = {}) {
   const gateway = createGatewayRequestClient(config);
   const whoamiClient = createIdentityWhoamiClient(config);
@@ -985,6 +1240,109 @@ function createIdentityClient(config = {}) {
       return gateway.request({
         path: `/api/platform/v1/identity/clerk-users${toQueryString({ q })}`
       });
+    },
+    async getTenantConfig(input) {
+      return gateway.request({
+        path: `/api/platform/v1/identity/tenant-config${toQueryString(
+          tenantIdentityQuery(input)
+        )}`
+      });
+    },
+    async updateTenantConfig(input, idempotencyKey) {
+      cleanRequiredString(input.tenantId, "tenantId");
+      return gateway.request({
+        path: "/api/platform/v1/identity/tenant-config",
+        method: "PATCH",
+        body: tenantIdentityBody(
+          input,
+          "identity.updateTenantConfig"
+        ),
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey()
+      });
+    },
+    async listIntegrations(input) {
+      return gateway.request({
+        path: `/api/platform/v1/identity/integrations${toQueryString(
+          tenantIdentityQuery(input)
+        )}`
+      }).then(
+        (response) => mapGatewayData(
+          response,
+          (data) => listResultFromEnvelope(
+            data,
+            "integrations"
+          )
+        )
+      );
+    },
+    async upsertIntegration(input, idempotencyKey) {
+      cleanRequiredString(input.tenantId, "tenantId");
+      cleanRequiredString(input.integrationKey, "integrationKey");
+      return gateway.request({
+        path: "/api/platform/v1/identity/integrations",
+        method: "PUT",
+        body: tenantIdentityBody(
+          input,
+          "identity.upsertIntegration"
+        ),
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey()
+      });
+    },
+    async listSecrets(input) {
+      return gateway.request({
+        path: `/api/platform/v1/identity/secrets${toQueryString(
+          tenantIdentityQuery(input)
+        )}`
+      }).then(
+        (response) => mapGatewayData(
+          response,
+          (data) => listResultFromEnvelope(
+            data,
+            "secrets"
+          )
+        )
+      );
+    },
+    async putSecretReference(input, idempotencyKey) {
+      cleanRequiredString(input.tenantId, "tenantId");
+      cleanRequiredString(input.secretRef, "secretRef");
+      return gateway.request({
+        path: "/api/platform/v1/identity/secrets",
+        method: "PUT",
+        body: tenantIdentityBody(
+          input,
+          "identity.putSecretReference"
+        ),
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey()
+      });
+    },
+    async evaluatePolicy(input, idempotencyKey) {
+      cleanRequiredString(input.tenantId, "tenantId");
+      cleanRequiredString(input.policySubject, "policySubject");
+      cleanRequiredString(input.policyAction, "policyAction");
+      cleanRequiredString(input.policyResource, "policyResource");
+      return gateway.request({
+        path: "/api/platform/v1/identity/policy/evaluate",
+        method: "POST",
+        body: tenantIdentityBody(
+          input,
+          "identity.evaluatePolicy"
+        ),
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey()
+      });
+    },
+    async recordPolicyDecision(input, idempotencyKey) {
+      cleanRequiredString(input.tenantId, "tenantId");
+      cleanRequiredString(input.decision, "decision");
+      return gateway.request({
+        path: "/api/platform/v1/identity/policy/decisions",
+        method: "POST",
+        body: tenantIdentityBody(
+          input,
+          "identity.recordPolicyDecision"
+        ),
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey()
+      });
     }
   };
 }
@@ -993,12 +1351,12 @@ function createIdentityClient(config = {}) {
 function asRecord2(value) {
   return value && typeof value === "object" ? value : {};
 }
-function cleanString2(value) {
+function cleanString3(value) {
   return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
 }
 function normalizeTopicRecord(value) {
   const record = asRecord2(value);
-  const topicId = cleanString2(record.topicId) ?? cleanString2(record.id) ?? cleanString2(record._id);
+  const topicId = cleanString3(record.topicId) ?? cleanString3(record.id) ?? cleanString3(record._id);
   return withTopicAlias({
     ...record,
     ...topicId ? { topicId } : {}