@inkeep/agents-core 0.0.0-dev-20260118170655 → 0.0.0-dev-20260119163620

package/dist/auth/authz/client.js

@@ -0,0 +1,189 @@
+import { getSpiceDbConfig } from "./config.js";
+import { v1 } from "@authzed/authzed-node";
+
+//#region src/auth/authz/client.ts
+/**
+* SpiceDB Client Wrapper
+*
+* Provides a singleton SpiceDB client and helper functions for common operations.
+*/
+let client = null;
+/**
+* Get the SpiceDB client singleton.
+* Creates a new client on first call.
+*/
+function getSpiceClient() {
+	if (!client) {
+		const config = getSpiceDbConfig();
+		client = v1.NewClient(config.token, config.endpoint, config.tlsEnabled ? v1.ClientSecurity.SECURE : v1.ClientSecurity.INSECURE_LOCALHOST_ALLOWED);
+	}
+	return client;
+}
+/**
+* Reset the client (useful for testing)
+*/
+function resetSpiceClient() {
+	client = null;
+}
+const PERMISSIONSHIP_HAS_PERMISSION = 2;
+const RELATIONSHIP_OPERATION_CREATE = 1;
+/**
+* Check if a subject has a permission on a resource.
+* Note: Caller must verify isAuthzEnabled(tenantId) before calling.
+*/
+async function checkPermission(params) {
+	return (await getSpiceClient().promises.checkPermission({
+		resource: {
+			objectType: params.resourceType,
+			objectId: params.resourceId
+		},
+		permission: params.permission,
+		subject: {
+			object: {
+				objectType: params.subjectType,
+				objectId: params.subjectId
+			},
+			optionalRelation: ""
+		},
+		consistency: { requirement: {
+			oneofKind: "minimizeLatency",
+			minimizeLatency: true
+		} },
+		context: void 0,
+		withTracing: false
+	})).permissionship === PERMISSIONSHIP_HAS_PERMISSION;
+}
+/**
+* Check multiple permissions on a resource in a single request.
+* More efficient than multiple checkPermission calls.
+*
+* @returns Record mapping permission names to boolean results
+*/
+async function checkBulkPermissions(params) {
+	const spice = getSpiceClient();
+	const items = params.permissions.map((permission) => v1.CheckBulkPermissionsRequestItem.create({
+		resource: v1.ObjectReference.create({
+			objectType: params.resourceType,
+			objectId: params.resourceId
+		}),
+		permission,
+		subject: v1.SubjectReference.create({ object: v1.ObjectReference.create({
+			objectType: params.subjectType,
+			objectId: params.subjectId
+		}) })
+	}));
+	const response = await spice.promises.checkBulkPermissions(v1.CheckBulkPermissionsRequest.create({
+		items,
+		consistency: { requirement: {
+			oneofKind: "minimizeLatency",
+			minimizeLatency: true
+		} }
+	}));
+	const result = {};
+	for (let i = 0; i < params.permissions.length; i++) {
+		const permission = params.permissions[i];
+		const pair = response.pairs[i];
+		if (pair.response.oneofKind === "item") result[permission] = pair.response.item.permissionship === PERMISSIONSHIP_HAS_PERMISSION;
+		else result[permission] = false;
+	}
+	return result;
+}
+/**
+* Find all resources of a type that a subject has a permission on.
+*/
+async function lookupResources(params) {
+	return (await getSpiceClient().promises.lookupResources({
+		resourceObjectType: params.resourceType,
+		permission: params.permission,
+		subject: {
+			object: {
+				objectType: params.subjectType,
+				objectId: params.subjectId
+			},
+			optionalRelation: ""
+		},
+		consistency: { requirement: {
+			oneofKind: "minimizeLatency",
+			minimizeLatency: true
+		} },
+		context: void 0,
+		optionalLimit: 0,
+		optionalCursor: void 0
+	})).map((item) => item.resourceObjectId);
+}
+/**
+* Write a relationship to SpiceDB.
+*/
+async function writeRelationship(params) {
+	await getSpiceClient().promises.writeRelationships({
+		updates: [{
+			operation: RELATIONSHIP_OPERATION_CREATE,
+			relationship: {
+				resource: {
+					objectType: params.resourceType,
+					objectId: params.resourceId
+				},
+				relation: params.relation,
+				subject: {
+					object: {
+						objectType: params.subjectType,
+						objectId: params.subjectId
+					},
+					optionalRelation: ""
+				},
+				optionalCaveat: void 0
+			}
+		}],
+		optionalPreconditions: [],
+		optionalTransactionMetadata: void 0
+	});
+}
+/**
+* Delete a relationship from SpiceDB.
+*/
+async function deleteRelationship(params) {
+	await getSpiceClient().promises.deleteRelationships({
+		relationshipFilter: {
+			resourceType: params.resourceType,
+			optionalResourceId: params.resourceId,
+			optionalResourceIdPrefix: "",
+			optionalRelation: params.relation,
+			optionalSubjectFilter: {
+				subjectType: params.subjectType,
+				optionalSubjectId: params.subjectId,
+				optionalRelation: void 0
+			}
+		},
+		optionalPreconditions: [],
+		optionalLimit: 0,
+		optionalAllowPartialDeletions: false,
+		optionalTransactionMetadata: void 0
+	});
+}
+/**
+* Read relationships for a resource to list subjects with access.
+*/
+async function readRelationships(params) {
+	return (await getSpiceClient().promises.readRelationships({
+		relationshipFilter: {
+			resourceType: params.resourceType,
+			optionalResourceId: params.resourceId,
+			optionalResourceIdPrefix: "",
+			optionalRelation: params.relation || "",
+			optionalSubjectFilter: void 0
+		},
+		consistency: { requirement: {
+			oneofKind: "minimizeLatency",
+			minimizeLatency: true
+		} },
+		optionalLimit: 0,
+		optionalCursor: void 0
+	})).map((item) => ({
+		subjectType: item.relationship?.subject?.object?.objectType || "",
+		subjectId: item.relationship?.subject?.object?.objectId || "",
+		relation: item.relationship?.relation || ""
+	}));
+}
+
+//#endregion
+export { checkBulkPermissions, checkPermission, deleteRelationship, getSpiceClient, lookupResources, readRelationships, resetSpiceClient, v1, writeRelationship };

package/dist/auth/authz/config.d.ts

@@ -0,0 +1,76 @@
+//#region src/auth/authz/config.d.ts
+/**
+ * SpiceDB Authorization Configuration
+ *
+ * Feature flag and configuration for the SpiceDB authorization system.
+ */
+/**
+ * Check if authorization is enabled.
+ *
+ * When called without tenantId:
+ * - Returns true if ENABLE_AUTHZ=true
+ *
+ * When called with tenantId:
+ * - If ENABLE_AUTHZ=false → returns false
+ * - If ENABLE_AUTHZ=true and TENANT_ID is not set → returns true (all tenants)
+ * - If ENABLE_AUTHZ=true and TENANT_ID is set → returns true only if tenantId matches
+ */
+declare function isAuthzEnabled(tenantId: string): boolean;
+/**
+ * Get SpiceDB connection configuration from environment variables.
+ */
+declare function getSpiceDbConfig(): {
+  endpoint: string;
+  token: string;
+  tlsEnabled: boolean;
+};
+/**
+ * SpiceDB resource types used in the schema
+ */
+declare const SpiceDbResourceTypes: {
+  readonly USER: "user";
+  readonly ORGANIZATION: "organization";
+  readonly PROJECT: "project";
+};
+/**
+ * SpiceDB relations used in the schema
+ *
+ * Relations are named as nouns (roles) per SpiceDB best practices.
+ * Project roles are prefixed for clarity when debugging/grepping.
+ */
+declare const SpiceDbRelations: {
+  readonly OWNER: "owner";
+  readonly ADMIN: "admin";
+  readonly MEMBER: "member";
+  readonly ORGANIZATION: "organization";
+  readonly PROJECT_ADMIN: "project_admin";
+  readonly PROJECT_MEMBER: "project_member";
+  readonly PROJECT_VIEWER: "project_viewer";
+};
+/**
+ * SpiceDB permissions used in the schema
+ *
+ * Permissions are named as verbs (actions) per SpiceDB best practices.
+ */
+/**
+ * SpiceDB permissions used in permission checks.
+ *
+ * Note: Organization-level permissions (manage) are handled via
+ * orgRole bypass in permission functions, not direct SpiceDB checks.
+ */
+declare const SpiceDbPermissions: {
+  readonly VIEW: "view";
+  readonly USE: "use";
+  readonly EDIT: "edit";
+  readonly DELETE: "delete";
+};
+type OrgRole = 'owner' | 'admin' | 'member';
+/**
+ * Project roles hierarchy:
+ * - project_admin: Full access (view + use + edit + manage members + delete)
+ * - project_member: Operator access (view + use: invoke agents, create API keys)
+ * - project_viewer: Read-only access (view only)
+ */
+type ProjectRole = 'project_admin' | 'project_member' | 'project_viewer';
+//#endregion
+export { OrgRole, ProjectRole, SpiceDbPermissions, SpiceDbRelations, SpiceDbResourceTypes, getSpiceDbConfig, isAuthzEnabled };

package/dist/auth/authz/config.js

@@ -0,0 +1,76 @@
+//#region src/auth/authz/config.ts
+/**
+* SpiceDB Authorization Configuration
+*
+* Feature flag and configuration for the SpiceDB authorization system.
+*/
+/**
+* Check if authorization is enabled.
+*
+* When called without tenantId:
+* - Returns true if ENABLE_AUTHZ=true
+*
+* When called with tenantId:
+* - If ENABLE_AUTHZ=false → returns false
+* - If ENABLE_AUTHZ=true and TENANT_ID is not set → returns true (all tenants)
+* - If ENABLE_AUTHZ=true and TENANT_ID is set → returns true only if tenantId matches
+*/
+function isAuthzEnabled(tenantId) {
+	if (process.env.ENABLE_AUTHZ !== "true") return false;
+	const configuredTenantId = process.env.TENANT_ID?.trim();
+	if (!configuredTenantId) return true;
+	return tenantId === configuredTenantId;
+}
+/**
+* Get SpiceDB connection configuration from environment variables.
+*/
+function getSpiceDbConfig() {
+	return {
+		endpoint: process.env.SPICEDB_ENDPOINT || "localhost:50051",
+		token: process.env.SPICEDB_PRESHARED_KEY || "",
+		tlsEnabled: process.env.SPICEDB_TLS_ENABLED === "true"
+	};
+}
+/**
+* SpiceDB resource types used in the schema
+*/
+const SpiceDbResourceTypes = {
+	USER: "user",
+	ORGANIZATION: "organization",
+	PROJECT: "project"
+};
+/**
+* SpiceDB relations used in the schema
+*
+* Relations are named as nouns (roles) per SpiceDB best practices.
+* Project roles are prefixed for clarity when debugging/grepping.
+*/
+const SpiceDbRelations = {
+	OWNER: "owner",
+	ADMIN: "admin",
+	MEMBER: "member",
+	ORGANIZATION: "organization",
+	PROJECT_ADMIN: "project_admin",
+	PROJECT_MEMBER: "project_member",
+	PROJECT_VIEWER: "project_viewer"
+};
+/**
+* SpiceDB permissions used in the schema
+*
+* Permissions are named as verbs (actions) per SpiceDB best practices.
+*/
+/**
+* SpiceDB permissions used in permission checks.
+*
+* Note: Organization-level permissions (manage) are handled via
+* orgRole bypass in permission functions, not direct SpiceDB checks.
+*/
+const SpiceDbPermissions = {
+	VIEW: "view",
+	USE: "use",
+	EDIT: "edit",
+	DELETE: "delete"
+};
+
+//#endregion
+export { SpiceDbPermissions, SpiceDbRelations, SpiceDbResourceTypes, getSpiceDbConfig, isAuthzEnabled };

package/dist/auth/authz/index.d.ts

@@ -0,0 +1,5 @@
+import { checkBulkPermissions, checkPermission, deleteRelationship, getSpiceClient, lookupResources, readRelationships, resetSpiceClient, writeRelationship } from "./client.js";
+import { OrgRole, ProjectRole, SpiceDbPermissions, SpiceDbRelations, SpiceDbResourceTypes, getSpiceDbConfig, isAuthzEnabled } from "./config.js";
+import { canEditProject, canUseProject, canViewProject, listAccessibleProjectIds } from "./permissions.js";
+import { changeProjectRole, grantProjectAccess, listProjectMembers, removeProjectFromSpiceDb, revokeProjectAccess, syncOrgMemberToSpiceDb, syncProjectToSpiceDb } from "./sync.js";
+export { type OrgRole, type ProjectRole, SpiceDbPermissions, SpiceDbRelations, SpiceDbResourceTypes, canEditProject, canUseProject, canViewProject, changeProjectRole, checkBulkPermissions, checkPermission, deleteRelationship, getSpiceClient, getSpiceDbConfig, grantProjectAccess, isAuthzEnabled, listAccessibleProjectIds, listProjectMembers, lookupResources, readRelationships, removeProjectFromSpiceDb, resetSpiceClient, revokeProjectAccess, syncOrgMemberToSpiceDb, syncProjectToSpiceDb, writeRelationship };

package/dist/auth/authz/index.js

@@ -0,0 +1,6 @@
+import { SpiceDbPermissions, SpiceDbRelations, SpiceDbResourceTypes, getSpiceDbConfig, isAuthzEnabled } from "./config.js";
+import { checkBulkPermissions, checkPermission, deleteRelationship, getSpiceClient, lookupResources, readRelationships, resetSpiceClient, writeRelationship } from "./client.js";
+import { canEditProject, canUseProject, canViewProject, listAccessibleProjectIds } from "./permissions.js";
+import { changeProjectRole, grantProjectAccess, listProjectMembers, removeProjectFromSpiceDb, revokeProjectAccess, syncOrgMemberToSpiceDb, syncProjectToSpiceDb } from "./sync.js";
+
+export { SpiceDbPermissions, SpiceDbRelations, SpiceDbResourceTypes, canEditProject, canUseProject, canViewProject, changeProjectRole, checkBulkPermissions, checkPermission, deleteRelationship, getSpiceClient, getSpiceDbConfig, grantProjectAccess, isAuthzEnabled, listAccessibleProjectIds, listProjectMembers, lookupResources, readRelationships, removeProjectFromSpiceDb, resetSpiceClient, revokeProjectAccess, syncOrgMemberToSpiceDb, syncProjectToSpiceDb, writeRelationship };

package/dist/auth/authz/permissions.d.ts

@@ -0,0 +1,57 @@
+import { OrgRole } from "./config.js";
+
+//#region src/auth/authz/permissions.d.ts
+
+/**
+ * Check if a user can view a project.
+ *
+ * - If authz is disabled: returns true (current behavior)
+ * - If user is org owner/admin: returns true (bypass)
+ * - Otherwise: checks SpiceDB
+ */
+declare function canViewProject(params: {
+  tenantId: string;
+  userId: string;
+  projectId: string;
+  orgRole: OrgRole;
+}): Promise<boolean>;
+/**
+ * Check if a user can use a project (invoke agents, create API keys, view traces).
+ *
+ * - If authz is disabled: returns true (current behavior)
+ * - If user is org owner/admin: returns true (bypass)
+ * - Otherwise: checks SpiceDB for use permission
+ */
+declare function canUseProject(params: {
+  tenantId: string;
+  userId: string;
+  projectId: string;
+  orgRole: OrgRole;
+}): Promise<boolean>;
+/**
+ * Check if a user can edit a project (modify configurations).
+ *
+ * - If authz is disabled: only org owner/admin can edit
+ * - If user is org owner/admin: returns true (bypass)
+ * - Otherwise: checks SpiceDB for edit permission
+ */
+declare function canEditProject(params: {
+  tenantId: string;
+  userId: string;
+  projectId: string;
+  orgRole: OrgRole;
+}): Promise<boolean>;
+/**
+ * Get list of accessible project IDs for a user.
+ *
+ * - If authz is disabled: returns 'all' (no filtering needed)
+ * - If user is org owner/admin: returns 'all' (no filtering needed)
+ * - Otherwise: uses SpiceDB LookupResources
+ */
+declare function listAccessibleProjectIds(params: {
+  tenantId: string;
+  userId: string;
+  orgRole: OrgRole;
+}): Promise<string[] | 'all'>;
+//#endregion
+export { canEditProject, canUseProject, canViewProject, listAccessibleProjectIds };

package/dist/auth/authz/permissions.js

@@ -0,0 +1,83 @@
+import { SpiceDbPermissions, SpiceDbResourceTypes, isAuthzEnabled } from "./config.js";
+import { checkPermission, lookupResources } from "./client.js";
+
+//#region src/auth/authz/permissions.ts
+/**
+* SpiceDB Permission Check Functions
+*
+* High-level functions for checking project-level permissions.
+*/
+/**
+* Check if a user can view a project.
+*
+* - If authz is disabled: returns true (current behavior)
+* - If user is org owner/admin: returns true (bypass)
+* - Otherwise: checks SpiceDB
+*/
+async function canViewProject(params) {
+	if (!isAuthzEnabled(params.tenantId)) return true;
+	if (params.orgRole === "owner" || params.orgRole === "admin") return true;
+	return checkPermission({
+		resourceType: SpiceDbResourceTypes.PROJECT,
+		resourceId: params.projectId,
+		permission: SpiceDbPermissions.VIEW,
+		subjectType: SpiceDbResourceTypes.USER,
+		subjectId: params.userId
+	});
+}
+/**
+* Check if a user can use a project (invoke agents, create API keys, view traces).
+*
+* - If authz is disabled: returns true (current behavior)
+* - If user is org owner/admin: returns true (bypass)
+* - Otherwise: checks SpiceDB for use permission
+*/
+async function canUseProject(params) {
+	if (!isAuthzEnabled(params.tenantId)) return true;
+	if (params.orgRole === "owner" || params.orgRole === "admin") return true;
+	return checkPermission({
+		resourceType: SpiceDbResourceTypes.PROJECT,
+		resourceId: params.projectId,
+		permission: SpiceDbPermissions.USE,
+		subjectType: SpiceDbResourceTypes.USER,
+		subjectId: params.userId
+	});
+}
+/**
+* Check if a user can edit a project (modify configurations).
+*
+* - If authz is disabled: only org owner/admin can edit
+* - If user is org owner/admin: returns true (bypass)
+* - Otherwise: checks SpiceDB for edit permission
+*/
+async function canEditProject(params) {
+	if (!isAuthzEnabled(params.tenantId)) return params.orgRole === "owner" || params.orgRole === "admin";
+	if (params.orgRole === "owner" || params.orgRole === "admin") return true;
+	return checkPermission({
+		resourceType: SpiceDbResourceTypes.PROJECT,
+		resourceId: params.projectId,
+		permission: SpiceDbPermissions.EDIT,
+		subjectType: SpiceDbResourceTypes.USER,
+		subjectId: params.userId
+	});
+}
+/**
+* Get list of accessible project IDs for a user.
+*
+* - If authz is disabled: returns 'all' (no filtering needed)
+* - If user is org owner/admin: returns 'all' (no filtering needed)
+* - Otherwise: uses SpiceDB LookupResources
+*/
+async function listAccessibleProjectIds(params) {
+	if (!isAuthzEnabled(params.tenantId)) return "all";
+	if (params.orgRole === "owner" || params.orgRole === "admin") return "all";
+	return lookupResources({
+		resourceType: SpiceDbResourceTypes.PROJECT,
+		permission: SpiceDbPermissions.VIEW,
+		subjectType: SpiceDbResourceTypes.USER,
+		subjectId: params.userId
+	});
+}
+
+//#endregion
+export { canEditProject, canUseProject, canViewProject, listAccessibleProjectIds };

package/dist/auth/authz/sync.d.ts

@@ -0,0 +1,85 @@
+import { OrgRole, ProjectRole } from "./config.js";
+
+//#region src/auth/authz/sync.d.ts
+
+/**
+ * Sync a user's org membership to SpiceDB.
+ * Call when: user joins org, role changes, user leaves org.
+ */
+declare function syncOrgMemberToSpiceDb(params: {
+  tenantId: string;
+  userId: string;
+  role: OrgRole;
+  action: 'add' | 'remove';
+}): Promise<void>;
+/**
+ * Change a user's organization role.
+ * Removes the old role and adds the new one atomically in a single transaction.
+ * Call when: user's org role is updated (e.g., member -> admin).
+ */
+declare function changeOrgRole(params: {
+  tenantId: string;
+  userId: string;
+  oldRole: OrgRole;
+  newRole: OrgRole;
+}): Promise<void>;
+/**
+ * Sync a new project to SpiceDB.
+ * Links project to org and grants creator project_admin role.
+ * Call when: project is created.
+ */
+declare function syncProjectToSpiceDb(params: {
+  tenantId: string;
+  projectId: string;
+  creatorUserId: string;
+}): Promise<void>;
+/**
+ * Grant project access to a user.
+ */
+declare function grantProjectAccess(params: {
+  tenantId: string;
+  projectId: string;
+  userId: string;
+  role: ProjectRole;
+}): Promise<void>;
+/**
+ * Revoke project access from a user.
+ */
+declare function revokeProjectAccess(params: {
+  tenantId: string;
+  projectId: string;
+  userId: string;
+  role: ProjectRole;
+}): Promise<void>;
+/**
+ * Change a user's project role.
+ * Removes the old role and adds the new one atomically in a single transaction.
+ */
+declare function changeProjectRole(params: {
+  tenantId: string;
+  projectId: string;
+  userId: string;
+  oldRole: ProjectRole;
+  newRole: ProjectRole;
+}): Promise<void>;
+/**
+ * Remove a project from SpiceDB.
+ * Call when: project is deleted.
+ */
+declare function removeProjectFromSpiceDb(params: {
+  tenantId: string;
+  projectId: string;
+}): Promise<void>;
+/**
+ * List all explicit project members from SpiceDB.
+ * Returns users with project_admin, project_member, or project_viewer roles.
+ */
+declare function listProjectMembers(params: {
+  tenantId: string;
+  projectId: string;
+}): Promise<Array<{
+  userId: string;
+  role: ProjectRole;
+}>>;
+//#endregion
+export { changeOrgRole, changeProjectRole, grantProjectAccess, listProjectMembers, removeProjectFromSpiceDb, revokeProjectAccess, syncOrgMemberToSpiceDb, syncProjectToSpiceDb };