@jskit-ai/agent-docs 0.1.61 → 0.1.63

package/guide/agent/app-setup/database-layer.md

@@ -2,7 +2,7 @@
 
 # Database layer
 
-At the end of the previous chapter, the app could already authenticate real users through Supabase, but JSKIT was still using its no-database fallback for the app-side user mirror. In this chapter, we install the MySQL database runtime, add the migration tooling, and explain what that changes immediately and what it still does **not** change yet.
+At the end of the previous chapter, the app could already authenticate real users through the local auth provider, without requiring Supabase or a database. In this chapter, we install the MySQL database runtime, add the migration tooling, and explain what that changes immediately and what it still does **not** change yet.
 
 This chapter is more infrastructural than the previous ones. That is intentional. There is no dramatic new screen in the browser. The important change is that the app gains a real database layer that later packages can depend on.
 
@@ -484,32 +484,31 @@ But the app still does **not** have:
 - workspace tables
 - CRUD tables of its own
 
-That means authentication is still only **partly** database-backed.
+That means the app's account model still is not database-backed.
 
-- Supabase is still the real source of truth for auth users and sessions.
+- local auth is still the real source of truth for auth users and sessions.
 - JSKIT still has a database runtime available.
-- But JSKIT still has **no installed package yet** that tells auth to switch from the standalone in-memory profile mirror to the persistent users-backed one.
+- But JSKIT still has **no installed package yet** that projects auth identities into persistent users/account tables.
 
 So this chapter is an infrastructure step. It makes the database layer available, but it does not yet install the package that uses that layer for persistent JSKIT-side user data.
 
-**Important: Auth Is Still In Standalone Mode**
+**Important: Auth Is Not Users-Backed Yet**
 
 This is the most important thing to keep straight:
 
-- adding `database-runtime-mysql` does **not** automatically make the auth chapter's temporary mirror disappear
+- adding `database-runtime-mysql` does **not** automatically change where auth stores credentials or sessions
 - it also does **not** create JSKIT user rows yet
 
-That only changes later, when a package such as `users-core` is installed and tells auth to use the persistent users-backed profile sync mode.
+That only changes later, when a package such as `users-core` is installed and registers the persistent users-backed `auth.profile.projector`.
 
 So after this chapter the app has a database layer, but authentication still behaves like:
 
-- real Supabase auth
-- temporary JSKIT-side mirror
+- real local auth
+- provider identity in the auth session
 
 not yet:
 
-- real Supabase auth
-- persistent JSKIT-side users layer
+- real local auth plus a persistent JSKIT-side users layer
 
 ## Under the hood
 
@@ -702,43 +701,34 @@ Right now:
 
 - `shell-web` is still a shell/layout package
 - `auth-web` is still a web auth package
-- `auth-provider-supabase-core` is still talking to Supabase for the real auth work
+- `auth-provider-local-core` is still handling credentials and sessions through `auth.local.backend`
 
 So the app has gained a new capability, but no visible part of the UI depends on that capability yet.
 
-### Why auth still uses the standalone profile mirror
+### Why auth is not users-backed yet
 
 This is the most important code path to read in this chapter.
 
-Inside `AuthSupabaseServiceProvider`, auth resolves its profile mode from server app config:
+Inside the local provider, auth only projects provider identities into the app users layer when something registers the provider-neutral `auth.profile.projector` token:
 
 ```js
-const authProfileMode = resolveAuthProfileMode(appConfig);
-let userProfileSyncService = fallbackStandaloneProfileSyncService;
-
-if (authProfileMode === PROFILE_MODE_USERS) {
-  if (!scope.has("users.profile.sync.service")) {
-    throw new Error(
-      "AuthSupabaseServiceProvider requires users.profile.sync.service when config.auth.profileMode is \"users\"."
-    );
-  }
-  userProfileSyncService = scope.make("users.profile.sync.service");
-}
+const profileProjector = scope.has("auth.profile.projector")
+  ? scope.make("auth.profile.projector")
+  : null;
 ```
 
 That snippet explains the whole consequence of this chapter.
 
-- The auth provider's server config still sets `config.auth.profileMode = "standalone"`.
-- If `profileMode` is missing entirely, the runtime assumes `users`, but it is not missing in the auth-only scaffold.
-- The fallback service is still the in-memory profile sync service from the previous chapter.
-- Nothing in `database-runtime-mysql` changes `config.auth.profileMode`.
+- The auth provider can authenticate users without an app database.
+- Nothing in `database-runtime-mysql` registers `auth.profile.projector`.
 - Nothing in `database-runtime-mysql` provides `users.profile.sync.service`.
+- The database runtime only provides the database foundation that later packages can use.
 
 So the auth layer keeps behaving the same way it did before:
 
-- Supabase still owns the real auth user and session
-- JSKIT still mirrors just enough profile data locally
-- that JSKIT-side mirror is still not persistent yet
+- local auth still owns the auth user and session
+- JSKIT can still display the provider identity from the auth session
+- there is still no persistent JSKIT users/account model yet
 
 The database runtime is ready, but the users layer that will actually use it has not been installed yet.
 
@@ -765,12 +755,12 @@ This chapter did not make the app feel dramatically different in the browser, bu
 
 But just as importantly, this chapter also defined what has **not** changed yet:
 
-- auth still uses the standalone JSKIT-side mirror
+- auth still uses the local provider's own backend
 - JSKIT still has no persistent users layer of its own
 - no feature package has started storing real app data yet
 
 So the right mental model at the end of this chapter is:
 
-- Supabase already handles real authentication
+- local auth already handles real authentication
 - MySQL is wired up and ready
 - the persistent JSKIT-side user model arrives in the next chapter

package/guide/agent/app-setup/initial-scaffolding.md

@@ -43,8 +43,6 @@ Minimal apps can still install the standard shell later with `npx jskit add pack
 If you already know you want a small non-workspace baseline right after the scaffold, this is the shortest reproducible path:
 
 ```bash
-SUPABASE_URL=...
-SUPABASE_KEY=...
 DB_HOST=127.0.0.1
 DB_PORT=3306
 DB_NAME=exampleapp
@@ -55,12 +53,7 @@ npx @jskit-ai/create-app exampleapp --tenancy-mode none
 cd exampleapp
 npm install
 
-npx jskit add package auth-provider-supabase-core \
-  --auth-supabase-url "$SUPABASE_URL" \
-  --auth-supabase-publishable-key "$SUPABASE_KEY" \
-  --app-public-url "http://localhost:5173"
-
-npx jskit add bundle auth-base
+npx jskit add bundle auth-local
 
 npx jskit add package database-runtime-mysql \
   --db-host "$DB_HOST" \
@@ -76,6 +69,8 @@ npm install
 npm run db:migrate
 ```
 
+The default auth install is intentionally local and simple. Do not start a new app by adding Supabase, OAuth, OTP, provider linking, or a users/profile projection unless that complexity is already part of the app you are building.
+
 If you want the larger workspace-enabled stack with the first assistant already configured, use [Quickstart](/guide/app-setup/quickstart) instead.
 
 **Try Bash Completion!**

package/guide/agent/app-setup/quickstart.md

@@ -15,7 +15,7 @@ The base flow below gives you:
 - users
 - console
 - MySQL
-- Supabase auth
+- local auth with no external auth service
 - one `admin` assistant configured from `console`
 
 It also shows the first page-extension moves most apps need:
@@ -32,8 +32,6 @@ Set these values first:
 
 ```bash
 OPENAI_API_KEY=...
-SUPABASE_URL=...
-SUPABASE_KEY=...
 DB_HOST=127.0.0.1
 DB_PORT=3306
 DB_NAME=testapp
@@ -50,12 +48,7 @@ npx @jskit-ai/create-app testapp --tenancy-mode personal
 cd testapp
 npm install
 
-npx jskit add package auth-provider-supabase-core \
-  --auth-supabase-url "$SUPABASE_URL" \
-  --auth-supabase-publishable-key "$SUPABASE_KEY" \
-  --app-public-url "http://localhost:5173"
-
-npx jskit add bundle auth-base
+npx jskit add bundle auth-local
 
 npx jskit add package database-runtime-mysql \
   --db-host "$DB_HOST" \
@@ -89,6 +82,8 @@ npm install
 npm run db:migrate
 ```
 
+Keep authentication deliberately basic while the product is still taking shape. Start with `auth-local`, build the app's core workflows, then add Supabase, OAuth, OTP, provider linking, app-user projection, or workspace/account complexity when the product actually needs those features.
+
 At this point you have:
 
 - a workspace-enabled app with `tenancyMode = "personal"`

package/guide/agent/app-setup/users.md

@@ -2,15 +2,15 @@
 
 # Users
 
-At the end of the previous chapter, the app had a real database runtime, but it still did not have JSKIT's own persistent users layer. Authentication worked, but the app-side profile mirror was still only the temporary fallback from the auth chapter.
+At the end of the previous chapter, the app had a real database runtime, but it still did not have JSKIT's own persistent users layer. Authentication worked, but signed-in people were still only provider identities from the auth layer.
 
-This chapter is where that changes. We install `users-web`, run the new migrations, and let JSKIT start treating authenticated people as persistent app users rather than only as Supabase identities.
+This chapter is where that changes. We install `users-web`, run the new migrations, and let JSKIT start treating authenticated people as persistent app users rather than only as auth-provider identities.
 
 `users-web` sounds like a UI package, but it is actually the point where several layers arrive together:
 
 - the persistent users/account data model from `users-core`
 - the account surface and account settings UI
-- the switch from standalone auth profile sync to users-backed auth profile sync
+- the switch from provider-only auth profiles to users-backed auth profile projection
 
 This is also the first chapter where the difference between "JSKIT wrote migration files into the app" and "Knex applied those files to the database" becomes important in practice.
 
@@ -39,10 +39,11 @@ This is the first chapter where the migration step is not just "nice to have."
 
 `users-core` writes:
 
+- the provider-neutral `auth.profile.projector` service binding through its runtime provider
 - `config.auth.profileMode = "users"` into `config/server.js`
 - real users/account schema migrations into `migrations/`
 
-That means the app is expected to use the persistent users-backed profile sync service. If you skip `npm run db:migrate`, the code and routes are installed, but the required tables are still missing.
+That means the app is expected to project authenticated identities into the persistent users-backed profile sync service. If you skip `npm run db:migrate`, the code and routes are installed, but the required tables are still missing.
 
 So the correct flow is:
 
@@ -63,14 +64,14 @@ This chapter is the real transition from "authentication exists" to "the app kno
 
 ### Authentication becomes users-backed
 
-In the database chapter, JSKIT used the standalone in-memory profile mirror. After installing `users-web`, JSKIT expects to synchronize authenticated users into real JSKIT tables.
+In the database chapter, JSKIT still treated the signed-in person as an auth-provider identity. After installing `users-web`, JSKIT expects to synchronize authenticated users into real JSKIT tables.
 
 That is the biggest architectural change in this chapter.
 
-- Supabase still owns the real auth identity and session
+- the selected auth provider still owns the auth identity and session
 - JSKIT owns a persistent users/account data model in MySQL
 
-So after this chapter, a signed-in user is not only "someone Supabase knows about." They are also a persistent JSKIT-side user with settings and profile state in the app database.
+So after this chapter, a signed-in user is not only "someone the auth provider knows about." They are also a persistent JSKIT-side user with settings and profile state in the app database.
 
 ### The app gets an authenticated account surface
 
@@ -119,20 +120,28 @@ This is the first chapter where the app starts to feel like it has a real user m
 
 The most interesting files are spread across config, migrations, routing, and the app-owned account UI.
 
-### `config/server.js` flips auth into users mode
+### `users-core` projects auth identities into app users
 
-The most important new server-only config line is:
+The most important server-side change is the provider-neutral projector binding from `users-core`:
 
 ```js
-config.auth ||= {};
-config.auth.profileMode = "users";
+if (!app.has("auth.profile.projector")) {
+  app.singleton("auth.profile.projector", (scope) => scope.make("users.profile.sync.service"));
+}
 ```
 
-That one line explains the deepest change in the chapter.
+That one binding explains the deepest change in the chapter.
 
-Before this chapter, auth used the standalone fallback profile sync service. After this chapter, auth is told to use the persistent users-backed profile sync flow instead.
+Before this chapter, auth could authenticate a user without creating a persistent app-owned user row. After this chapter, auth providers can call `auth.profile.projector.syncIdentityProfile(...)` and get back a persistent users-backed profile.
 
-That only works because `users-core` also installs the required repositories, services, and tables.
+`users-core` also writes this server-only config line for Supabase compatibility:
+
+```js
+config.auth ||= {};
+config.auth.profileMode = "users";
+```
+
+The local provider uses the token directly. The Supabase provider also understands `config.auth.profileMode = "users"` and resolves the same users-backed sync service. In both cases, this only works because `users-core` installs the required repositories, services, and tables.
 
 ### `migrations/` stops being mostly empty
 
@@ -253,19 +262,19 @@ That is worth noticing because this is a higher level of scaffolding:
 
 ### Why auth uses the users layer
 
-In the previous chapter, auth was explicitly configured for the standalone profile sync fallback. The core logic in `AuthSupabaseServiceProvider` looks like this:
+In the previous chapter, auth did not have a users-backed projector. The core logic in `registerUsersCore()` looks like this:
 
 ```js
-const authProfileMode = resolveAuthProfileMode(appConfig);
-let userProfileSyncService = fallbackStandaloneProfileSyncService;
-
-if (authProfileMode === PROFILE_MODE_USERS) {
-  if (!scope.has("users.profile.sync.service")) {
-    throw new Error(
-      "AuthSupabaseServiceProvider requires users.profile.sync.service when config.auth.profileMode is \"users\"."
-    );
-  }
-  userProfileSyncService = scope.make("users.profile.sync.service");
+app.singleton("users.profile.sync.service", (scope) => {
+  return createAuthProfileSyncService({
+    userProfilesRepository: scope.make("internal.repository.user-profiles"),
+    userSettingsRepository: scope.make("internal.repository.user-settings"),
+    lifecycleContributors: resolveProfileSyncLifecycleContributors(scope)
+  });
+});
+
+if (!app.has("auth.profile.projector")) {
+  app.singleton("auth.profile.projector", (scope) => scope.make("users.profile.sync.service"));
 }
 ```
 
@@ -273,11 +282,11 @@ The important part is concrete.
 
 After `users-web`:
 
-- `config/server.js` sets `config.auth.profileMode = "users"`
-- `users-core` supplies the users-backed sync service
+- `users-core` supplies `users.profile.sync.service`
+- `users-core` aliases that service as `auth.profile.projector`
 - the migrations supply the required tables
 
-So auth has everything it needs to stop using the fallback mirror and start using the persistent users-backed one.
+So auth has everything it needs to stop returning only provider-owned profile data and start using the persistent users-backed profile.
 
 That is the true point of this chapter. The app is not just authenticated. It has a real users layer.
 
@@ -354,11 +363,11 @@ That is not only a workspace-package concern. The generated `packages/users/...`
 
 ## Summary
 
-This chapter is where the app stopped treating signed-in people as only Supabase identities and started treating them as real JSKIT users.
+This chapter is where the app stopped treating signed-in people as only auth-provider identities and started treating them as real JSKIT users.
 
 - `users-core` installed the persistent users/account schema and server layer
 - `users-web` installed the first real account surface and account settings UI
-- auth switched from the standalone fallback mirror to the users-backed sync flow
+- auth switched from provider-only profile data to the users-backed projection flow
 
 That is why this chapter feels bigger than a normal page install. It changes both the browser experience and the server-side meaning of "a signed-in user."
 

package/guide/agent/app-setup/working-with-the-jskit-cli.md

@@ -28,7 +28,7 @@ The easiest way to understand `jskit` is to separate it from the other tools in
 
 That separation is crucial.
 
-When you run a command such as `npx jskit add package auth-provider-supabase-core`, JSKIT updates app-owned files and records what it changed. It does **not** replace npm, Vite, or Knex.
+When you run a command such as `npx jskit add bundle auth-local`, JSKIT updates app-owned files and records what it changed. It does **not** replace npm, Vite, or Knex.
 
 The most important record of that managed state lives here:
 
@@ -153,7 +153,7 @@ That distinction matters.
 
 A bundle is a curated install shortcut for several runtime packages that are meant to go together.
 
-In the current catalog, `auth-base` is the obvious example. It is a single bundle id, but it expands to several real runtime packages.
+In the current catalog, `auth-local` is the obvious example. It is a single bundle id, but it expands to several real runtime packages.
 
 #### Runtime packages
 
@@ -235,32 +235,34 @@ There are two especially common cases:
 
 That second case matters just as much as the first one. Later in the guide, chapters explain package behavior one feature at a time. `show --details` is the generic command that lets you inspect those same package contracts directly.
 
-### A first example: what does `auth-base` actually install?
+### A first example: what does `auth-local` actually install?
 
 Run:
 
 ```bash
-npx jskit show auth-base --details
+npx jskit show auth-local --details
 ```
 
 This output is short, but it already teaches something important:
 
-- `auth-base` is a **bundle**
+- `auth-local` is a **bundle**
 - it is not a runtime package by itself
 
-It expands to two real runtime packages:
+It expands to three real runtime packages:
 
 - `@jskit-ai/auth-core`
 - `@jskit-ai/auth-web`
+- `@jskit-ai/auth-provider-local-core`
 
 That is exactly the kind of thing you want to know before you mutate the app. For a bundle, this is often the main question:
 
 - *what real packages am I about to get?*
 
-`auth-base` is a good example because the bundle name is short and convenient, but the detailed view makes the underlying install explicit. It also helps you keep the mental model straight:
+`auth-local` is a good example because the bundle name is short and convenient, but the detailed view makes the underlying install explicit. It also helps you keep the mental model straight:
 
 - bundles are install shortcuts
 - runtime packages are the things that actually provide capabilities
+- provider bundles also select one concrete `auth.provider`
 
 ### A richer example: what does `workspaces-web` contribute?
 
@@ -476,8 +478,8 @@ This is not required, but it is genuinely useful once you start using commands s
 The install command comes in two main forms:
 
 ```bash
-npx jskit add package auth-provider-supabase-core
-npx jskit add bundle auth-base
+npx jskit add package users-web
+npx jskit add bundle auth-local
 ```
 
 Those two examples look similar, but they do different things.
@@ -519,12 +521,12 @@ npm run devlinks
 Use this when the catalog already offers a sensible grouped install:
 
 ```bash
-npx jskit add bundle auth-base
+npx jskit add bundle auth-local
 ```
 
 Bundles are a convenience layer. They save you from having to remember and install several related runtime packages one by one.
 
-This is why `show auth-base --details` is useful first: it lets you see what the bundle will actually install.
+This is why `show auth-local --details` is useful first: it lets you see what the bundle will actually install. Lower-level bundles such as `auth-base` can still be useful when you are composing your own provider stack, but they require an installed selected provider such as `auth-provider-local-core` or `auth-provider-supabase-core`.
 
 ### Generator packages are different
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.61",
+  "version": "0.1.63",
   "description": "Distributed JSKIT agent references, prompts, guides, and generated reference maps.",
   "type": "module",
   "files": [

package/reference/autogen/README.md

@@ -12,6 +12,7 @@ Startup navigation stays in `KERNEL_MAP.md`.
 - [assistant-core](/packages/agent-docs/reference/autogen/packages/assistant-core.md)
 - [assistant-runtime](/packages/agent-docs/reference/autogen/packages/assistant-runtime.md)
 - [auth-core](/packages/agent-docs/reference/autogen/packages/auth-core.md)
+- [auth-provider-local-core](/packages/agent-docs/reference/autogen/packages/auth-provider-local-core.md)
 - [auth-provider-supabase-core](/packages/agent-docs/reference/autogen/packages/auth-provider-supabase-core.md)
 - [auth-web](/packages/agent-docs/reference/autogen/packages/auth-web.md)
 - [console-core](/packages/agent-docs/reference/autogen/packages/console-core.md)

package/reference/autogen/packages/auth-core.md

@@ -35,6 +35,22 @@ Exports
 Exports
 - `runAuthSignOutFlow`
 
+### `src/server/actions/auth.contributor.js`
+Exports
+- `baseAuthActions`
+- `buildAuthActions()`
+- `requireRequestContext(context, actionId)`
+
+### `src/server/authActor.js`
+Exports
+- `createAuthIdentityId(provider, providerUserId)`
+- `normalizeAuthActor(value = {}, options = {})`
+- `buildLegacyProfileFromActor(actorLike)`
+- `normalizeAuthResult(value = {}, options = {})`
+Local functions
+- `normalizeDisplayName(value, email = "")`
+- `normalizeProviderUserId(value)`
+
 ### `src/server/authPolicyContextResolverRegistry.js`
 Exports
 - `AUTH_POLICY_CONTEXT_RESOLVER_TAG`
@@ -86,6 +102,14 @@ Exports
 - `authPolicyPlugin`
 - `withAuthPolicy`
 - `mergeAuthPolicy`
+- `createAuthIdentityId`
+- `normalizeAuthActor`
+- `buildLegacyProfileFromActor`
+- `normalizeAuthResult`
+- `AUTH_OPERATION_UNSUPPORTED_CODE`
+- `createUnsupportedAuthOperationError`
+- `throwUnsupportedAuthOperation`
+- `isUnsupportedAuthOperationError`
 
 ### `src/server/lib/objectUtils.js`
 Exports
@@ -129,6 +153,10 @@ Exports
 Exports
 - `AccessCoreServiceProvider`
 
+### `src/server/providers/AuthActionsServiceProvider.js`
+Exports
+- `AuthActionsServiceProvider`
+
 ### `src/server/providers/FastifyAuthPolicyServiceProvider.js`
 Exports
 - `FastifyAuthPolicyServiceProvider`
@@ -137,6 +165,19 @@ Local functions
 - `parseList(value)`
 - `defaultHasPermission({ permission, permissions = [] } = {})`
 
+### `src/server/services/authSessionEventsService.js`
+Exports
+- `createAuthSessionEventsService()`
+Local functions
+- `resolveActorId(context = {})`
+
+### `src/server/unsupportedOperation.js`
+Exports
+- `AUTH_OPERATION_UNSUPPORTED_CODE`
+- `createUnsupportedAuthOperationError(operation, message = "")`
+- `throwUnsupportedAuthOperation(operation, message = "")`
+- `isUnsupportedAuthOperationError(error)`
+
 ### `src/server/utils.js`
 Exports
 - `normalizeEmail(value)`
@@ -163,6 +204,20 @@ Local functions
 Exports
 - `createApi({ request })`
 
+### `src/shared/authCapabilities.js`
+Exports
+- `AUTH_PASSWORD_RECOVERY_DELIVERIES`
+- `AUTH_OPTIONAL_OPERATION_FEATURES`
+- `normalizeAuthProviderId(value, { fallback = "unknown" } = {})`
+- `normalizeAuthCapabilities(value = {})`
+- `getCapabilityFeature(capabilities, path)`
+- `isAuthOperationSupported(capabilities, operationName)`
+Local functions
+- `normalizeBoolean(value, fallback = false)`
+- `normalizeProviderLabel(value, providerId)`
+- `normalizeOAuthProviderEntries(value)`
+- `normalizeRecoveryDelivery(value, { request = false, complete = false } = {})`
+
 ### `src/shared/authConstraints.js`
 Exports
 - `AUTH_EMAIL_PATTERN`
@@ -215,6 +270,16 @@ Exports
 - `AUTH_PATHS`
 - `buildAuthOauthStartPath(provider)`
 
+### `src/shared/authSecurityStatus.js`
+Exports
+- `normalizeAuthSecurityStatus(value = {})`
+- `buildSecurityStatusFromAuthMethodsStatus(authMethodsStatus, { actions = {} } = {})`
+Local functions
+- `normalizeBoolean(value, fallback = false)`
+- `countEnabledMethods(methods)`
+- `normalizeAuthMethodStatus(entry)`
+- `normalizeSecurityActions(value = {})`
+
 ### `src/shared/commands/authCommandValidators.js`
 Exports
 - `authEmailFieldDefinition`
@@ -367,6 +432,14 @@ Exports
 - `resolveAuthDeniedLoginMessage`
 - `AUTH_PATHS`
 - `buildAuthOauthStartPath`
+- `AUTH_PASSWORD_RECOVERY_DELIVERIES`
+- `AUTH_OPTIONAL_OPERATION_FEATURES`
+- `normalizeAuthProviderId`
+- `normalizeAuthCapabilities`
+- `getCapabilityFeature`
+- `isAuthOperationSupported`
+- `normalizeAuthSecurityStatus`
+- `buildSecurityStatusFromAuthMethodsStatus`
 
 ### `src/shared/inputNormalization.js`
 Exports