@lupinum/better-convex-nuxt 1.0.0-beta.2 → 1.0.0-beta.4

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": ">=4.5.2 <5"
   },
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.4",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/runtime/auth/better-auth-browser-adapter.d.ts

@@ -27,6 +27,7 @@ export declare function createBetterAuthBrowserAdapter(source: BetterAuthBrowser
 }, options?: {
     initialIdentityKey?: string;
 }): BetterConvexAuthAdapter & {
+    isRestrictedSession(): boolean;
     failClosed(message: string): void;
     dispose(): void;
 };

package/dist/runtime/auth/better-auth-browser-adapter.js

@@ -18,6 +18,7 @@ export function createBetterAuthBrowserAdapter(source, callbacks = { authenticat
   let observedSessionToken;
   let observedIdentityKey = options.initialIdentityKey;
   let cachedToken = null;
+  let restrictedGeneration;
   let snapshot = options.initialIdentityKey ? {
     status: "authenticated",
     identityKey: options.initialIdentityKey,
@@ -60,6 +61,7 @@ export function createBetterAuthBrowserAdapter(source, callbacks = { authenticat
     const retainsEstablishedSession = Boolean(value.error) && !isUnauthorized(value.error) && snapshot.status === "authenticated" && observedSessionToken === sessionToken && observedIdentityKey === key;
     if (retainsEstablishedSession) return;
     if (value.error || malformed) {
+      restrictedGeneration = void 0;
       cachedToken = null;
       sessionGeneration += 1;
       observedSessionToken = null;
@@ -80,10 +82,11 @@ export function createBetterAuthBrowserAdapter(source, callbacks = { authenticat
     if (changed) {
       sessionGeneration += 1;
       cachedToken = null;
+      restrictedGeneration = void 0;
     }
     observedSessionToken = sessionToken;
     observedIdentityKey = key;
-    snapshot = sessionToken && key ? {
+    snapshot = sessionToken && key && restrictedGeneration !== sessionGeneration ? {
       status: "authenticated",
       identityKey: key,
       sessionGeneration,
@@ -94,7 +97,7 @@ export function createBetterAuthBrowserAdapter(source, callbacks = { authenticat
       sessionGeneration,
       error: null
     };
-    if (!sessionToken) callbacks.anonymous(null);
+    if (snapshot.status === "anonymous") callbacks.anonymous(null);
     callbacks.sessionChanged?.(sessionToken, null, sessionGeneration);
     notify();
   };
@@ -145,6 +148,7 @@ export function createBetterAuthBrowserAdapter(source, callbacks = { authenticat
   };
   return Object.freeze({
     snapshot: () => snapshot,
+    isRestrictedSession: () => !disposed && restrictedGeneration === sessionGeneration && snapshot.status === "anonymous",
     subscribe(listener) {
       if (disposed) return () => {
       };
@@ -154,8 +158,17 @@ export function createBetterAuthBrowserAdapter(source, callbacks = { authenticat
     async fetchToken() {
       if (disposed || snapshot.status !== "authenticated") return null;
       const expectedKey = snapshot.identityKey;
+      const expectedGeneration = sessionGeneration;
       const outcome = await fetchConvexToken(source);
-      if (disposed || snapshot.status !== "authenticated" || snapshot.identityKey !== expectedKey) {
+      if (disposed || snapshot.status !== "authenticated" || snapshot.identityKey !== expectedKey || sessionGeneration !== expectedGeneration) {
+        return null;
+      }
+      if (outcome.restricted) {
+        cachedToken = null;
+        restrictedGeneration = expectedGeneration;
+        snapshot = { status: "anonymous", identityKey: null, sessionGeneration, error: null };
+        callbacks.anonymous(null);
+        notify();
         return null;
       }
       if (outcome.identity) {
@@ -187,6 +200,7 @@ export function createBetterAuthBrowserAdapter(source, callbacks = { authenticat
     },
     failClosed(message) {
       if (disposed) return;
+      restrictedGeneration = void 0;
       cachedToken = null;
       sessionGeneration += 1;
       snapshot = {
@@ -204,6 +218,7 @@ export function createBetterAuthBrowserAdapter(source, callbacks = { authenticat
     dispose() {
       if (disposed) return;
       disposed = true;
+      restrictedGeneration = void 0;
       stop();
       for (const cancel of [...cancelSessionSettlement]) cancel();
       cancelSessionSettlement.clear();

package/dist/runtime/auth/integrated-client.d.ts

@@ -10,7 +10,7 @@ export interface CanonicalSessionReconciler {
      * without changing its synchronous contract.
      */
     cancel(checkpoint: SessionCheckpoint): void;
-    /** Re-read the canonical provider session, then await its Convex acceptance. */
+    /** Re-read the provider session, then await matching Convex settlement (possibly anonymous). */
     reconcile(checkpoint: SessionCheckpoint): Promise<void>;
 }
 /**

package/dist/runtime/auth/token-fetcher.d.ts

@@ -39,7 +39,9 @@ export declare function decodeFetchedIdentity(token: string): FetchedIdentity |
  * The outcome of one total token fetch. `identity: null` with `authError: null`
  * is a clean anonymous result when the exchange succeeds with no token. A
  * definitive 401/403 means presented credentials were rejected and is reported
- * as an authentication error. `authError` is also set when a token decodes
+ * as an authentication error, except the exact live workforce continuation
+ * refusal. That result is restricted and grants no Convex identity.
+ * `authError` is also set when a token decodes
  * without a stable user id, or a transient transport failure exhausts the retry
  * loop. `definitive`
  * distinguishes such a transient (non-definitive) failure — over which a usable
@@ -49,6 +51,8 @@ export interface FetchOutcome {
     identity: FetchedIdentity | null;
     authError: string | null;
     definitive: boolean;
+    /** A live workforce cookie may continue setup, but cannot authenticate Convex. */
+    restricted?: true;
 }
 /**
  * Total Convex-token fetch; never throws.

package/dist/runtime/auth/token-fetcher.js

@@ -75,6 +75,9 @@ export async function fetchConvexToken(source, options = {}) {
           break;
         }
         if (response.error) {
+          if (typeof response.error === "object" && "status" in response.error && response.error.status === 403 && "code" in response.error && response.error.code === "AUTH_WORKFORCE_FULL_AUTH_REQUIRED") {
+            return { identity: null, authError: null, definitive: true, restricted: true };
+          }
           if (isDefinitiveAuthStatus(response.error)) {
             return {
               identity: null,

package/dist/runtime/cli/auth-schema.js

@@ -21,7 +21,8 @@ const SUPPORTED_SCHEMA_PLUGIN_IDS = /* @__PURE__ */ new Set([
   "two-factor",
   "email-otp",
   "jwt",
-  "oauth-provider"
+  "oauth-provider",
+  "bcn-workforce-schema"
 ]);
 function usage() {
   return [
@@ -88,7 +89,7 @@ function requireSchemaOptions(value) {
       const id = isRecord(plugin) && typeof plugin.id === "string" ? plugin.id : void 0;
       if (!id || !SUPPORTED_SCHEMA_PLUGIN_IDS.has(id) || seen.has(id)) {
         throw new Error(
-          `Schema config plugin at index ${index} is unsupported; the 1.0 profile admits organization, two-factor, email-otp, jwt, and oauth-provider once each.`
+          `Schema config plugin at index ${index} is unsupported; the 1.0 profile admits organization, two-factor, email-otp, jwt, oauth-provider, and bcn-workforce-schema once each.`
         );
       }
       seen.add(id);

package/dist/runtime/cli/convex.d.ts

@@ -1,11 +1,19 @@
 #!/usr/bin/env node
 type ConvexAuthorityKind = 'deployment-key' | 'deployment-name' | 'self-hosted';
+export interface ConvexAuthoritySnapshot {
+    digest: string;
+    development: boolean;
+    label: string;
+}
 /** Validate that the fixed file contains one, and only one, deployment selector class. */
 export declare function assertConvexAuthoritySelection(environment: Readonly<Record<string, string>>): ConvexAuthorityKind;
 /** Build a child environment whose only Convex authority comes from the fixed file. */
 export declare function buildConvexCommandEnvironment(inherited: Readonly<Record<string, string | undefined>>, authorityFile: Readonly<Record<string, string>>): Record<string, string>;
+export declare function inspectConvexAuthority(cwd?: string): Promise<ConvexAuthoritySnapshot>;
 export declare function runConvexCommand(arguments_: readonly string[], options?: {
     cwd?: string;
+    developmentOnly?: boolean;
+    expectedAuthorityDigest?: string;
     inheritedEnvironment?: NodeJS.ProcessEnv;
     input?: string;
     onStdout?: (output: string) => void;

package/dist/runtime/cli/convex.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { realpathSync } from "node:fs";
 import { stat, readFile } from "node:fs/promises";
 import { resolve } from "node:path";
@@ -176,6 +177,21 @@ async function readAuthorityFile(cwd) {
     throw new Error("The Convex authority file is missing, invalid, or too large.");
   }
 }
+function snapshotAuthority(environment) {
+  const kind = assertConvexAuthoritySelection(environment);
+  const selector = TOKEN_SELECTORS.map((name) => environment[name]).find(Boolean) ?? environment.CONVEX_DEPLOYMENT ?? "self-hosted";
+  const publicSelector = selector.includes("|") ? selector.slice(0, selector.indexOf("|")) : selector;
+  const development = kind === "deployment-key" && publicSelector.startsWith("dev:") || kind === "deployment-name" && /^(?:anonymous:anonymous-|dev:|local:)/u.test(publicSelector);
+  const canonicalAuthority = Object.entries(environment).filter(([name]) => ALLOWED_CONVEX_FILE_NAMES.has(name)).sort(([left], [right]) => left.localeCompare(right));
+  return {
+    digest: createHash("sha256").update(JSON.stringify(canonicalAuthority)).digest("hex"),
+    development,
+    label: kind === "self-hosted" ? "self-hosted deployment" : publicSelector
+  };
+}
+export async function inspectConvexAuthority(cwd = process.cwd()) {
+  return snapshotAuthority(await readAuthorityFile(resolve(cwd)));
+}
 function usage() {
   return [
     "Run the pinned Convex CLI with one explicit deployment authority.",
@@ -224,6 +240,13 @@ export async function runConvexCommand(arguments_, options = {}) {
     assertFileBoundArguments(commandArguments);
     const authorityFile = await readAuthorityFile(cwd);
     const authorityKind = assertConvexAuthoritySelection(authorityFile);
+    const authority = snapshotAuthority(authorityFile);
+    if (options.developmentOnly && !authority.development) {
+      throw new Error("This command requires development, local, or anonymous authority.");
+    }
+    if (options.expectedAuthorityDigest !== void 0 && authority.digest !== options.expectedAuthorityDigest) {
+      throw new Error("The Convex authority file changed after the operation was confirmed.");
+    }
     const deploymentKey = TOKEN_SELECTORS.map((name) => authorityFile[name]).find(Boolean);
     if (command === "deploy" && authorityKind === "deployment-name") {
       throw new Error("Deploy requires a deployment-scoped key or self-hosted authority.");

package/dist/runtime/cli/init.d.ts

@@ -1,6 +1,7 @@
 export interface InitDependencies {
     confirm(message: string): Promise<boolean>;
     prompt(message: string, defaultValue: string): Promise<string>;
+    readDevelopmentAuthorityLabel(): Promise<string>;
     runConvex(args: readonly string[], input?: string): Promise<number>;
     readEnvironmentNames(): Promise<ReadonlySet<string>>;
     generateSchema(args: readonly string[]): Promise<number>;

package/dist/runtime/cli/init.js

@@ -3,7 +3,7 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { runAuthSchemaCommand } from "./auth-schema.js";
-import { runConvexCommand } from "./convex.js";
+import { inspectConvexAuthority, runConvexCommand } from "./convex.js";
 const templates = {
   "convex/auth.config.ts": `import { getConvexAuthProvider } from '@lupinum/better-convex-nuxt/better-auth/server'
 import type { AuthConfig } from 'convex/server'
@@ -41,7 +41,8 @@ export default app
 import schema from './schema'
 import schemaMetadata from './schemaMetadata'
 
-export const { consumeOne, count, create, deleteMany, deleteOne, findMany, findOne, incrementOne, rotateSigningKey, updateMany, updateOne } = defineAuthAdapterFunctions({ metadata: schemaMetadata, schema })
+// This module is inside the isolated betterAuth component, not the public app API.
+export const { assertProfile, consumeOne, count, create, deleteMany, deleteOne, findMany, findOne, incrementOne, rotateSigningKey, sessionAdmission, expireWorkforceSession, listWorkforceSessions, revokeAllWorkforceSessions, revokeWorkforceSession, touchWorkforceSession, updateMany, updateOne } = defineAuthAdapterFunctions({ metadata: schemaMetadata, schema })
 `,
   "convex/betterAuth/convex.config.ts": `import { defineComponent } from 'convex/server'
 
@@ -87,7 +88,26 @@ async function readOptional(path) {
     throw error;
   }
 }
-function defaultDependencies() {
+function defaultDependencies(root) {
+  let authorityPromise;
+  const developmentAuthority = async () => {
+    authorityPromise ??= inspectConvexAuthority(root);
+    const authority = await authorityPromise;
+    if (!authority.development) {
+      throw new Error("better-convex init refuses production or unclassified authority");
+    }
+    return authority;
+  };
+  const runDevelopmentConvex = async (args, options = {}) => {
+    const authority = await developmentAuthority();
+    return await runConvexCommand(args, {
+      ...options,
+      cwd: root,
+      developmentOnly: true,
+      expectedAuthorityDigest: authority.digest,
+      quiet: true
+    });
+  };
   async function question(message) {
     const terminal = createInterface({ input: process.stdin, output: process.stdout });
     try {
@@ -105,11 +125,13 @@ function defaultDependencies() {
       const answer = (await question(`${message} [${defaultValue}] `)).trim();
       return answer || defaultValue;
     },
-    runConvex: async (args, input) => await runConvexCommand(args, { input, quiet: true }),
+    async readDevelopmentAuthorityLabel() {
+      return (await developmentAuthority()).label;
+    },
+    runConvex: async (args, input) => await runDevelopmentConvex(args, { input }),
     async readEnvironmentNames() {
       let output = "";
-      const status = await runConvexCommand(["env", "list", "--names-only"], {
-        quiet: true,
+      const status = await runDevelopmentConvex(["env", "list", "--names-only"], {
         onStdout: (value) => {
           output += value;
         }
@@ -217,9 +239,9 @@ export async function runInitCommand(args, overrides = {}) {
     console.log("Usage: better-convex init [--typed-client]");
     return 0;
   }
-  const defaults = defaultDependencies();
-  const dependencies = { ...defaults, ...overrides };
   const root = process.cwd();
+  const defaults = defaultDependencies(root);
+  const dependencies = { ...defaults, ...overrides };
   const schemaPath = join(root, "convex/betterAuth/schema.ts");
   const metadataPath = join(root, "convex/betterAuth/schemaMetadata.ts");
   const [schema, metadata] = await Promise.all([
@@ -255,7 +277,10 @@ export async function runInitCommand(args, overrides = {}) {
       "Generated auth schema conflicts with the reviewed plugin profile. Run better-convex auth schema and review the diff manually."
     );
   }
-  if (!await dependencies.confirm("Provision development secrets and the first signing key?")) {
+  const authorityLabel = await dependencies.readDevelopmentAuthorityLabel();
+  if (!await dependencies.confirm(
+    `Provision development secrets and the first signing key in ${authorityLabel}?`
+  )) {
     return 0;
   }
   await provisionDevelopment(dependencies);

package/dist/runtime/convex-auth/adapter/create-adapter.js

@@ -1,10 +1,23 @@
 import {
   createAdapterFactory
 } from "better-auth/adapters";
+import { APIError } from "better-auth/api";
 import { symmetricDecrypt, symmetricEncrypt } from "better-auth/crypto";
 import { createFunctionHandle } from "convex/server";
+import { ConvexError } from "convex/values";
 import { isWritableAuthCtx, requireWritableAuthCtx } from "../context.js";
-import { createAuthSchema } from "./generate-schema.js";
+import { createWorkforceAdapterTransport } from "../workforce/adapter-transport.js";
+import { hasWorkforceSchema, workforceSchemaPlugin } from "../workforce/schema.js";
+import { createAuthSchema, generateAuthSchemaArtifacts } from "./generate-schema.js";
+function rejectReplay(error) {
+  if (error instanceof ConvexError && error.data === "AUTH_WORKFORCE_TOTP_REPLAYED") {
+    throw new APIError("FORBIDDEN", {
+      code: "INVALID_TWO_FACTOR_CODE",
+      message: "This code cannot be used. Wait for a new code and try again."
+    });
+  }
+  throw error;
+}
 function toComponentWhere(where) {
   return where?.map((condition) => ({
     ...condition,
@@ -144,9 +157,14 @@ export function createConvexAuthAdapter(ctx, component, adapterOptions = {}) {
       customTransformInput: ({ data, fieldAttributes }) => fieldAttributes.type === "date" ? toEpochMilliseconds(data) : data,
       customTransformOutput: ({ data, fieldAttributes }) => fieldAttributes.type === "date" ? toDate(data) : data
     },
-    adapter: ({ getFieldName, getModelName, options }) => {
+    adapter: ({ getFieldName, getModelName, options, schema }) => {
       options.telemetry = { enabled: false };
       if (options.advanced?.database?.joins) throw new Error("AUTH_JOINS_UNSUPPORTED");
+      const workforce = options.plugins?.some((plugin) => plugin.id === workforceSchemaPlugin.id) === true;
+      if (workforce && !hasWorkforceSchema(generateAuthSchemaArtifacts(schema).metadata)) {
+        throw new Error("AUTH_WORKFORCE_SCHEMA_MISMATCH");
+      }
+      const workforceTransport = createWorkforceAdapterTransport(workforce);
       const idTokens = createAccountIdTokenProtector(options);
       const triggerModels = {
         onCreate: configuredTriggerModels(adapterOptions.triggers, "onCreate").map(getModelName),
@@ -181,11 +199,14 @@ export function createConvexAuthAdapter(ctx, component, adapterOptions = {}) {
           data
         }) => {
           requireWritableAuthCtx(ctx);
+          const { operation, consumedChallenge } = await workforceTransport.create(model, data);
           const created = await ctx.runMutation(component.adapter.create, {
             model,
             data: await idTokens.protect(model, data),
-            onCreateHandle: await triggerHandle(model, "onCreate")
-          });
+            onCreateHandle: await triggerHandle(model, "onCreate"),
+            ...operation ? { workforce: operation } : {},
+            ...consumedChallenge ? { workforceConsumedChallenge: consumedChallenge } : {}
+          }).catch(rejectReplay);
           return idTokens.reveal(model, created);
         },
         findOne: async ({
@@ -193,10 +214,12 @@ export function createConvexAuthAdapter(ctx, component, adapterOptions = {}) {
           where,
           select
         }) => {
+          const operation = await workforceTransport.operation(model);
           const found = await ctx.runQuery(component.adapter.findOne, {
             model,
             where: toComponentWhere(where),
-            select: mapSelect(model, select)
+            select: mapSelect(model, select),
+            ...operation?.operation === "confirm-enrollment" ? { workforce: operation } : {}
           });
           return idTokens.reveal(model, found);
         },
@@ -231,12 +254,14 @@ export function createConvexAuthAdapter(ctx, component, adapterOptions = {}) {
         }) => {
           requireWritableAuthCtx(ctx);
           if (where.length === 0) return null;
+          const operation = await workforceTransport.operation();
           const updated = await ctx.runMutation(component.adapter.updateOne, {
             model,
             where: toComponentWhere(where),
             update: await idTokens.protect(model, update),
-            onUpdateHandle: await triggerHandle(model, "onUpdate")
-          });
+            onUpdateHandle: await triggerHandle(model, "onUpdate"),
+            ...operation ? { workforce: operation } : {}
+          }).catch(rejectReplay);
           return idTokens.reveal(model, updated);
         },
         updateMany: async ({ model, where, update }) => {
@@ -283,6 +308,7 @@ export function createConvexAuthAdapter(ctx, component, adapterOptions = {}) {
             onUpdateHandle: await relationshipTriggerHandle("onUpdate"),
             onUpdateModels: triggerModels.onUpdate
           });
+          await workforceTransport.consumed(model, consumed);
           return idTokens.reveal(model, consumed);
         },
         incrementOne: async ({
@@ -292,12 +318,14 @@ export function createConvexAuthAdapter(ctx, component, adapterOptions = {}) {
           set
         }) => {
           requireWritableAuthCtx(ctx);
+          const operation = await workforceTransport.operation();
           const incremented = await ctx.runMutation(component.adapter.incrementOne, {
             model,
             where: toComponentWhere(where),
             increment,
             set: await idTokens.protect(model, set),
-            onUpdateHandle: await triggerHandle(model, "onUpdate")
+            onUpdateHandle: await triggerHandle(model, "onUpdate"),
+            ...operation ? { workforce: operation } : {}
           });
           return idTokens.reveal(model, incremented);
         }