@jskit-ai/users-core 0.1.172 → 0.1.174

package/package.json

@@ -1,25 +1,27 @@
 {
   "name": "@jskit-ai/users-core",
-  "version": "0.1.172",
+  "version": "0.1.174",
   "type": "module",
   "scripts": {
     "test": "node --test"
   },
   "exports": {
-    "./server/profileSyncLifecycleContributorRegistry": "./src/server/profileSyncLifecycleContributorRegistry.js",
+    "./server/UsersFeature": "./src/server/UsersFeature.js",
+    "./server/UsersIdentityProvider": "./src/server/UsersIdentityProvider.js",
+    "./server/usersExtensions": "./src/server/usersExtensions.js",
     "./shared/resources/userProfileResource": "./src/shared/resources/userProfileResource.js",
     "./shared/resources/userSettingsResource": "./src/shared/resources/userSettingsResource.js"
   },
   "dependencies": {
-    "@jskit-ai/auth-core": "0.1.157",
-    "@jskit-ai/database-runtime": "0.1.159",
-    "@jskit-ai/http-runtime": "0.1.157",
-    "@jskit-ai/json-rest-api-core": "0.1.103",
-    "@jskit-ai/kernel": "0.1.159",
-    "@jskit-ai/resource-core": "0.1.101",
-    "@jskit-ai/resource-crud-core": "0.1.101",
-    "@jskit-ai/storage-runtime": "0.1.156",
-    "@jskit-ai/uploads-runtime": "0.1.134",
+    "@jskit-ai/auth-core": "0.1.159",
+    "@jskit-ai/database-runtime": "0.1.161",
+    "@jskit-ai/http-runtime": "0.1.159",
+    "@jskit-ai/json-rest-api-core": "0.1.105",
+    "@jskit-ai/kernel": "0.1.161",
+    "@jskit-ai/resource-core": "0.1.103",
+    "@jskit-ai/resource-crud-core": "0.1.103",
+    "@jskit-ai/storage-runtime": "0.1.158",
+    "@jskit-ai/uploads-runtime": "0.1.136",
     "json-rest-schema": "^1.0.17"
   },
   "description": "Users/account runtime plus HTTP routes for account features.",
@@ -28,24 +30,35 @@
     "capabilities": {
       "provides": [
         "users.core",
-        "users.server-routes"
+        "users.identity",
+        "users.extensions"
       ],
       "requires": [
+        "auth.extensions",
+        "auth.service",
         "runtime.actions",
+        "runtime.bootstrap",
         "runtime.database",
-        "json-rest-api.core",
+        "runtime.http",
+        "runtime.json-rest-api",
         "runtime.storage",
-        "runtime.uploads",
-        "auth.provider",
-        "auth.policy"
+        "runtime.uploads"
       ]
     },
     "runtime": {
       "server": {
         "providers": [
           {
-            "entrypoint": "src/server/UsersCoreServiceProvider.js",
-            "export": "UsersCoreServiceProvider"
+            "entrypoint": "src/server/UsersExtensionsProvider.js",
+            "export": "UsersExtensionsProvider"
+          },
+          {
+            "entrypoint": "src/server/UsersIdentityProvider.js",
+            "export": "UsersIdentityProvider"
+          },
+          {
+            "entrypoint": "src/server/UsersFeature.js",
+            "export": "UsersFeature"
           }
         ]
       },
@@ -58,9 +71,7 @@
         "tableOwnership": {
           "tables": [
             {
-              "tableName": "user_settings",
-              "provenance": "runtime-package",
-              "ownerKind": "package-runtime"
+              "tableName": "user_settings"
             }
           ]
         }
@@ -69,7 +80,7 @@
         "surfaces": [
           {
             "subpath": "./server",
-            "summary": "Exports UsersCoreServiceProvider plus account feature route registration modules and action definitions."
+            "summary": "Exports the explicit users feature, account services, repositories, actions, and extension API."
           },
           {
             "subpath": "./shared",
@@ -80,13 +91,11 @@
             "summary": "Exports no runtime API today (reserved client entrypoint)."
           }
         ],
-        "containerTokens": {
-          "server": [
-            "users.profile.sync.service",
-            "auth.profile.projector"
-          ],
-          "client": []
-        }
+        "capabilities": [
+          "users.core",
+          "users.identity",
+          "users.extensions"
+        ]
       },
       "server": {
         "routes": [
@@ -153,230 +162,9 @@
         ]
       }
     },
-    "mutations": {
-      "dependencies": {
-        "runtime": {
-          "@jskit-ai/auth-core": "0.1.157",
-          "@jskit-ai/crud-core": "0.1.170",
-          "@jskit-ai/database-runtime": "0.1.159",
-          "@jskit-ai/http-runtime": "0.1.157",
-          "@jskit-ai/json-rest-api-core": "0.1.103",
-          "@jskit-ai/kernel": "0.1.159",
-          "@jskit-ai/resource-core": "0.1.101",
-          "@jskit-ai/resource-crud-core": "0.1.101",
-          "@local/users": "file:packages/users",
-          "@jskit-ai/uploads-runtime": "0.1.134"
-        },
-        "dev": {}
-      },
-      "packageJson": {
-        "scripts": {}
-      },
-      "procfile": {},
-      "files": [
-        {
-          "op": "install-migration",
-          "from": "templates/migrations/users_core_generic_initial.cjs",
-          "toDir": "migrations",
-          "extension": ".cjs",
-          "reason": "Install users/account core schema migration.",
-          "category": "migration",
-          "id": "users-core-generic-initial-schema"
-        },
-        {
-          "op": "install-migration",
-          "from": "templates/migrations/users_core_profile_username.cjs",
-          "toDir": "migrations",
-          "extension": ".cjs",
-          "reason": "Install users profile username migration.",
-          "category": "migration",
-          "id": "users-core-profile-username-schema"
-        },
-        {
-          "op": "install-migration",
-          "from": "templates/migrations/users_core_profile_updated_at.cjs",
-          "toDir": "migrations",
-          "extension": ".cjs",
-          "reason": "Install users profile updated-at migration.",
-          "category": "migration",
-          "id": "users-core-profile-updated-at-schema"
-        },
-        {
-          "from": "templates/packages/users/package.json",
-          "to": "packages/users/package.json",
-          "ownership": "app",
-          "preserveOnRemove": true,
-          "reason": "Install app-owned users package manifest for non-workspace tenancy.",
-          "category": "users-core",
-          "id": "users-core-users-package-json-base",
-          "when": {
-            "config": "tenancyMode",
-            "notIn": [
-              "personal",
-              "workspaces"
-            ]
-          }
-        },
-        {
-          "from": "templates/packages/users-workspace/package.json",
-          "to": "packages/users/package.json",
-          "ownership": "app",
-          "preserveOnRemove": true,
-          "reason": "Install app-owned users package manifest for workspace tenancy.",
-          "category": "users-core",
-          "id": "users-core-users-package-json-workspace",
-          "when": {
-            "config": "tenancyMode",
-            "in": [
-              "personal",
-              "workspaces"
-            ]
-          }
-        },
-        {
-          "from": "templates/packages/users/src/server/UsersProvider.js",
-          "to": "packages/users/src/server/UsersProvider.js",
-          "ownership": "app",
-          "preserveOnRemove": true,
-          "reason": "Install app-owned users CRUD provider for non-workspace tenancy.",
-          "category": "users-core",
-          "id": "users-core-users-provider-base",
-          "when": {
-            "config": "tenancyMode",
-            "notIn": [
-              "personal",
-              "workspaces"
-            ]
-          }
-        },
-        {
-          "from": "templates/packages/users-workspace/src/server/UsersProvider.js",
-          "to": "packages/users/src/server/UsersProvider.js",
-          "ownership": "app",
-          "preserveOnRemove": true,
-          "reason": "Install app-owned users CRUD provider for workspace tenancy.",
-          "category": "users-core",
-          "id": "users-core-users-provider-workspace",
-          "when": {
-            "config": "tenancyMode",
-            "in": [
-              "personal",
-              "workspaces"
-            ]
-          }
-        },
-        {
-          "from": "templates/packages/users/src/server/actions.js",
-          "to": "packages/users/src/server/actions.js",
-          "ownership": "app",
-          "preserveOnRemove": true,
-          "reason": "Install app-owned users CRUD actions for non-workspace tenancy.",
-          "category": "users-core",
-          "id": "users-core-users-actions-base",
-          "when": {
-            "config": "tenancyMode",
-            "notIn": [
-              "personal",
-              "workspaces"
-            ]
-          }
-        },
-        {
-          "from": "templates/packages/users-workspace/src/server/actions.js",
-          "to": "packages/users/src/server/actions.js",
-          "ownership": "app",
-          "preserveOnRemove": true,
-          "reason": "Install app-owned users CRUD actions for workspace tenancy.",
-          "category": "users-core",
-          "id": "users-core-users-actions-workspace",
-          "when": {
-            "config": "tenancyMode",
-            "in": [
-              "personal",
-              "workspaces"
-            ]
-          }
-        },
-        {
-          "from": "templates/packages/users/src/server/registerRoutes.js",
-          "to": "packages/users/src/server/registerRoutes.js",
-          "ownership": "app",
-          "preserveOnRemove": true,
-          "reason": "Install app-owned users CRUD routes for non-workspace tenancy.",
-          "category": "users-core",
-          "id": "users-core-users-routes-base",
-          "when": {
-            "config": "tenancyMode",
-            "notIn": [
-              "personal",
-              "workspaces"
-            ]
-          }
-        },
-        {
-          "from": "templates/packages/users-workspace/src/server/registerRoutes.js",
-          "to": "packages/users/src/server/registerRoutes.js",
-          "ownership": "app",
-          "preserveOnRemove": true,
-          "reason": "Install app-owned users CRUD routes for workspace tenancy.",
-          "category": "users-core",
-          "id": "users-core-users-routes-workspace",
-          "when": {
-            "config": "tenancyMode",
-            "in": [
-              "personal",
-              "workspaces"
-            ]
-          }
-        },
-        {
-          "from": "templates/packages/users/src/server/repository.js",
-          "to": "packages/users/src/server/repository.js",
-          "ownership": "app",
-          "preserveOnRemove": true,
-          "reason": "Install app-owned users CRUD repository.",
-          "category": "users-core",
-          "id": "users-core-users-repository"
-        },
-        {
-          "from": "templates/packages/users/src/server/service.js",
-          "to": "packages/users/src/server/service.js",
-          "ownership": "app",
-          "preserveOnRemove": true,
-          "reason": "Install app-owned users CRUD service.",
-          "category": "users-core",
-          "id": "users-core-users-service"
-        },
-        {
-          "from": "templates/packages/users/src/shared/index.js",
-          "to": "packages/users/src/shared/index.js",
-          "ownership": "app",
-          "preserveOnRemove": true,
-          "reason": "Install app-owned users shared entrypoint.",
-          "category": "users-core",
-          "id": "users-core-users-shared-index"
-        },
-        {
-          "from": "templates/packages/users/src/shared/userResource.js",
-          "to": "packages/users/src/shared/userResource.js",
-          "ownership": "app",
-          "preserveOnRemove": true,
-          "reason": "Install app-owned users shared resource.",
-          "category": "users-core",
-          "id": "users-core-users-resource"
-        }
-      ],
-      "text": [
-        {
-          "op": "append-text",
-          "file": "config/server.js",
-          "position": "bottom",
-          "skipIfContains": "config.auth.profileMode = \"users\";",
-          "value": "\nconfig.auth ||= {};\nconfig.auth.profileMode = \"users\";\n",
-          "reason": "Enable users-backed auth profile sync when users-core is installed.",
-          "category": "runtime-config",
-          "id": "users-core-auth-profile-mode"
-        }
+    "migrations": {
+      "directories": [
+        "migrations"
       ]
     }
   }

package/patterns/user-administration-server/PATTERN.md

@@ -0,0 +1,64 @@
+---
+id: users/user-administration-server
+title: User administration server package
+summary: Expose user administration and workspace-scoped member operations through app-owned packages backed by JSKIT users runtime APIs.
+keywords: account, admin, member, repository, resource, routes, service, user, workspace
+requires: @jskit-ai/users-core, @jskit-ai/crud-core
+---
+
+# User administration server package
+
+## Use when
+
+Use this pattern when an application needs app-specific administration of user
+profiles or workspace members beyond the built-in account runtime.
+
+## Do not use when
+
+Do not use this pattern for self-service account settings, authentication
+credentials, or an application that needs no administrative user listing.
+
+## Product decisions
+
+Choose global versus workspace scope, visible and editable fields, permission
+policy, route surface, filters, and whether account deletion is part of the
+product. Do not expose password/session data through the resource.
+
+## Framework APIs
+
+Use `@jskit-ai/users-core` for profile persistence and policies,
+`defineCrudJsonApiFeature()` from `@jskit-ai/crud-core` for standard mechanics,
+and the resource contracts from `@jskit-ai/resource-crud-core`.
+
+## Invariants
+
+- The public user id is the resource identity.
+- Workspace operations are scoped before repository access.
+- Permission checks happen before records or record existence are disclosed.
+- Shared profile persistence remains owned by `@jskit-ai/users-core`.
+- The resource is the field contract; the feature projects its repository,
+  service, actions, and routes without app-local ceremony.
+
+## Example files
+
+`example/packages/users/` is a global administration package.
+`example/packages/users-workspace/` demonstrates the workspace route/action
+boundary while reusing the same service contract. Copy only the composition
+that matches the product and adapt it as ordinary application source.
+
+## Variation points
+
+Change scope, route surface, visible fields, filters, sorting, permission
+policy, and user-facing language. Retain the core user identity contract.
+
+## Verification
+
+Test authorized and forbidden list/view/update operations, cross-workspace
+isolation, missing records, null/cleared fields, filtering, and pagination.
+
+## Avoid
+
+- copying authentication credential tables into the user resource
+- trusting route scope without repository scope
+- adding app-local mechanics already provided by `defineCrudJsonApiFeature()`
+- generator metadata or field questionnaires

package/patterns/user-administration-server/example/packages/users/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@app/users",
+  "version": "0.0.0",
+  "description": "App-local read-only user administration feature.",
+  "private": true,
+  "type": "module",
+  "exports": {
+    "./server/UsersFeature": "./src/server/UsersFeature.js",
+    "./shared": "./src/shared/index.js"
+  },
+  "dependencies": {
+    "@jskit-ai/crud-core": "0.1.172",
+    "@jskit-ai/resource-crud-core": "0.1.103"
+  },
+  "jskit": {
+    "kind": "runtime",
+    "capabilities": {
+      "provides": [
+        "app.users"
+      ],
+      "requires": [
+        "runtime.http",
+        "runtime.json-rest-api",
+        "runtime.actions",
+        "runtime.database"
+      ]
+    },
+    "runtime": {
+      "server": {
+        "providers": [
+          {
+            "entrypoint": "src/server/UsersFeature.js",
+            "export": "UsersFeature"
+          }
+        ]
+      },
+      "client": {
+        "providers": []
+      }
+    }
+  }
+}

package/patterns/user-administration-server/example/packages/users/src/server/UsersFeature.js

@@ -0,0 +1,13 @@
+import { defineCrudJsonApiFeature } from "@jskit-ai/crud-core/server/defineCrudJsonApiFeature";
+import { resource } from "../shared/userResource.js";
+
+const UsersFeature = defineCrudJsonApiFeature({
+  resource,
+  id: "app.users",
+  capability: "app.users",
+  surface: "home",
+  ownershipFilter: "public",
+  relativePath: "/users"
+});
+
+export { UsersFeature };

package/patterns/user-administration-server/example/packages/users/src/shared/index.js

@@ -0,0 +1 @@
+export { resource } from "./userResource.js";

package/patterns/user-administration-server/example/packages/users-workspace/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@app/users-workspace",
+  "version": "0.0.0",
+  "description": "App-local workspace-scoped read-only user administration feature.",
+  "private": true,
+  "type": "module",
+  "exports": {
+    "./server/UsersWorkspaceFeature": "./src/server/UsersWorkspaceFeature.js",
+    "./shared": "./src/shared/index.js"
+  },
+  "dependencies": {
+    "@jskit-ai/crud-core": "0.1.172",
+    "@jskit-ai/resource-crud-core": "0.1.103",
+    "@jskit-ai/workspaces-core": "0.1.139"
+  },
+  "jskit": {
+    "kind": "runtime",
+    "capabilities": {
+      "provides": [
+        "app.users-workspace"
+      ],
+      "requires": [
+        "runtime.http",
+        "runtime.json-rest-api",
+        "runtime.actions",
+        "runtime.database"
+      ]
+    },
+    "runtime": {
+      "server": {
+        "providers": [
+          {
+            "entrypoint": "src/server/UsersWorkspaceFeature.js",
+            "export": "UsersWorkspaceFeature"
+          }
+        ]
+      },
+      "client": {
+        "providers": []
+      }
+    }
+  }
+}

package/patterns/user-administration-server/example/packages/users-workspace/src/server/UsersWorkspaceFeature.js

@@ -0,0 +1,22 @@
+import { defineCrudJsonApiFeature } from "@jskit-ai/crud-core/server/defineCrudJsonApiFeature";
+import { buildWorkspaceInputFromRouteParams } from "@jskit-ai/workspaces-core/server/support/workspaceRouteInput";
+import { workspaceSlugParamsValidator } from "@jskit-ai/workspaces-core/server/validators/routeParamsValidator";
+import { resource } from "../shared/userResource.js";
+
+const UsersWorkspaceFeature = defineCrudJsonApiFeature({
+  resource,
+  id: "app.users-workspace",
+  capability: "app.users-workspace",
+  surface: "admin",
+  ownershipFilter: "workspace",
+  relativePath: "/users",
+  scope: {
+    routeBase: "/w/:workspaceSlug",
+    actionInputValidator: workspaceSlugParamsValidator,
+    routeParamsValidator: workspaceSlugParamsValidator,
+    inputKeys: ["workspaceSlug"],
+    input: (request) => buildWorkspaceInputFromRouteParams(request.input.params)
+  }
+});
+
+export { UsersWorkspaceFeature };

package/patterns/user-administration-server/example/packages/users-workspace/src/shared/userResource.js

@@ -0,0 +1,56 @@
+import { defineCrudResource } from "@jskit-ai/resource-crud-core/shared/crudResource";
+
+const resource = defineCrudResource({
+  namespace: "users",
+  tableName: "users",
+  crudOperations: ["list", "view"],
+  schema: {
+    name: {
+      type: "string",
+      required: true,
+      minLength: 1,
+      maxLength: 160,
+      actualField: "display_name",
+      search: true,
+      operations: { output: { required: false } }
+    },
+    email: {
+      type: "string",
+      required: true,
+      search: true,
+      operations: { output: { required: false } }
+    },
+    username: {
+      type: "string",
+      required: true,
+      search: true,
+      operations: { output: { required: false } }
+    },
+    createdAt: {
+      type: "dateTime",
+      required: true,
+      storage: { writeSerializer: "datetime-utc" },
+      operations: { output: { required: true } }
+    },
+    updatedAt: {
+      type: "dateTime",
+      required: true,
+      storage: { writeSerializer: "datetime-utc" },
+      operations: { output: { required: true } }
+    }
+  },
+  searchSchema: {
+    id: { type: "id", actualField: "id" },
+    q: {
+      type: "string",
+      oneOf: ["name", "email", "username"],
+      filterOperator: "like",
+      splitBy: " ",
+      matchAll: true
+    }
+  },
+  defaultSort: ["name", "email"],
+  autofilter: "public"
+});
+
+export { resource };

package/src/server/UsersExtensionsProvider.js

@@ -0,0 +1,14 @@
+import { defineProvider } from "@jskit-ai/kernel/shared/capabilities";
+import { createUsersExtensions } from "./usersExtensions.js";
+
+const UsersExtensionsProvider = defineProvider({
+  id: "users.extensions",
+  provides: {
+    extensions: "users.extensions"
+  },
+  setup() {
+    return { extensions: createUsersExtensions() };
+  }
+});
+
+export { UsersExtensionsProvider };