@tailor-platform/sdk 2.0.0-next.0 → 2.0.0-next.10

package/docs/services/auth.md

@@ -86,7 +86,7 @@ Example TailorDB type for user profile:
 // tailordb/user.ts
 import { db } from "@tailor-platform/sdk";
 
-export const user = db.type("User", {
+export const user = db.table("User", {
   email: db.string().unique(), // usernameField must have unique constraint
   role: db.enum(["admin", "user"]),
   ...db.fields.timestamps(),
@@ -107,7 +107,7 @@ userProfile: {
 
 **usernameField**: The field in the TailorDB type used as the username. This field must have a unique constraint (`.unique()`) since it is used to uniquely identify users.
 
-**attributes**: Specifies which fields from the TailorDB type are used as user attributes. Set to `true` to enable a field. Enabled attributes must be assigned values in all machine user definitions. Only fields with ValueOperand types (string, boolean, string[], boolean[]) can be used as attributes. The `id` field and datetime/date/time types are excluded.
+**attributes**: Specifies which fields from the TailorDB type are used as user attributes. Set to `true` to enable a field. Machine user definitions must assign values to attributes derived from required fields; attributes derived from optional fields may be omitted (see [Machine Users](#machine-users)). Only fields with ValueOperand types (string, boolean, string[], boolean[]) can be used as attributes. The `id` field and datetime/date/time types are excluded.
 
 ## Attribute List
 
@@ -130,7 +130,7 @@ Example TailorDB type with UUID fields for attribute list:
 // tailordb/user.ts
 import { db } from "@tailor-platform/sdk";
 
-export const user = db.type("User", {
+export const user = db.table("User", {
   email: db.string().unique(),
   role: db.enum(["admin", "user"]),
   organizationId: db.uuid(), // Can be used in attributeList
@@ -139,18 +139,18 @@ export const user = db.type("User", {
 });
 ```
 
-The `attributeList` values are accessible via `user.attributeList` as a tuple:
+The `attributeList` values are accessible via the runtime principal's `attributeList` as a tuple:
 
 ```typescript
 // In a resolver
 body: (context) => {
-  const [organizationId, teamId] = context.user.attributeList;
+  const [organizationId, teamId] = context.caller?.attributeList ?? [];
 },
 
 // In TailorDB hooks
 .hooks({
   field: {
-    create: ({ user }) => user.attributeList[0], // First UUID from list
+    create: ({ invoker }) => invoker?.attributeList[0] ?? null, // First UUID from list
   },
 })
 ```
@@ -160,7 +160,7 @@ body: (context) => {
 When you want to use machine users without defining a `userProfile`, define `machineUserAttributes` instead. These attributes are used for:
 
 - type-safe `machineUsers[*].attributes`
-- `context.user.attributes` typing (via `tailor.d.ts`)
+- runtime principal `attributes` typing (via `tailor.d.ts`)
 
 ```typescript
 import { defineAuth, t } from "@tailor-platform/sdk";
@@ -182,7 +182,7 @@ export const auth = defineAuth("my-auth", {
 To update types in `tailor.d.ts`, run:
 
 ```bash
-tailor-sdk generate
+tailor generate
 ```
 
 ## Machine Users
@@ -200,12 +200,12 @@ machineUsers: {
 },
 ```
 
-**attributes**: Values for attributes enabled in `userProfile.attributes` (or all fields defined in `machineUserAttributes` when `userProfile` is omitted). All enabled fields must be set here. These values are accessible via `user.attributes`:
+**attributes**: Values for attributes enabled in `userProfile.attributes` (or fields defined in `machineUserAttributes` when `userProfile` is omitted). Attribute keys mirror the field's optionality: attributes derived from required fields must be set, while attributes derived from optional fields may be omitted. Setting an attribute to `null` or `undefined` is equivalent to omitting it — the attribute is deployed as unset. These values are accessible via the runtime principal's `attributes`:
 
 ```typescript
 // In a resolver
 body: (context) => {
-  const role = context.user.attributes?.role;
+  const role = context.caller?.attributes.role;
 },
 ```
 
@@ -230,25 +230,25 @@ machineUsers: {
 },
 ```
 
-These values are accessible via `user.attributeList`:
+These values are accessible via the runtime principal's `attributeList`:
 
 ```typescript
 // In a resolver
 body: (context) => {
-  const [organizationId, teamId] = context.user.attributeList;
+  const [organizationId, teamId] = context.caller?.attributeList ?? [];
 },
 
 // In TailorDB hooks
 .hooks({
   field: {
-    create: ({ user }) => user.attributes?.role === "ADMIN" ? "default" : null,
+    create: ({ invoker }) => invoker?.attributes.role === "ADMIN" ? "default" : null,
   },
 })
 
 // In TailorDB validate
 .validate({
   field: [
-    ({ user }) => user.attributes?.role === "ADMIN",
+    ({ invoker }) => invoker?.attributes.role === "ADMIN",
     "Only admins can set this field",
   ],
 })
@@ -264,12 +264,12 @@ Machine users are useful for:
 Get a machine user token using the CLI:
 
 ```bash
-tailor-sdk machineuser token <name>
+tailor machineuser token <name>
 ```
 
 ### Specifying a machine user invoker
 
-Resolvers, executors, and `workflow.trigger()` accept an `authInvoker` option that chooses which machine user runs the operation. Pass the machine user name as a plain string — it is type-narrowed to the names you registered in `machineUsers`.
+Resolvers, executors, and `workflow.start()` accept an `invoker` option that chooses which machine user runs the operation. Pass the machine user name as a plain string — it is type-narrowed to the names you registered in `machineUsers`.
 
 ```typescript
 // tailor.config.ts
@@ -284,21 +284,21 @@ export const auth = defineAuth("my-auth", {
 ```
 
 ```typescript
-// resolvers/trigger-workflow.ts
+// resolvers/start-workflow.ts
 import { createResolver, t } from "@tailor-platform/sdk";
 import myWorkflow from "../workflows/my-workflow";
 
 export default createResolver({
-  name: "triggerMyWorkflow",
+  name: "startMyWorkflow",
   operation: "mutation",
   input: {
     id: t.string(),
   },
   body: async ({ input }) => {
-    // Trigger workflow with machine user permissions
-    const workflowRunId = await myWorkflow.trigger(
+    // Start workflow with machine user permissions
+    const workflowRunId = await myWorkflow.start(
       { id: input.id },
-      { authInvoker: "admin-machine-user" },
+      { invoker: "admin-machine-user" },
     );
     return { workflowRunId };
   },
@@ -308,9 +308,7 @@ export default createResolver({
 });
 ```
 
-Type narrowing is provided by the generated `tailor.d.ts` (the `MachineUserNameRegistry` interface). Run `tailor-sdk generate` (or `apply`) after defining new machine users to refresh it.
-
-> **Deprecated:** The `auth.invoker("<name>")` helper is still available for backward compatibility. Prefer the string form — it does not require importing `auth` from `tailor.config.ts` into runtime files, avoiding bundling config-layer (Node-only) dependencies.
+Type narrowing is provided by the generated `tailor.d.ts` (the `MachineUserNameRegistry` interface). Run `tailor generate` (or `deploy`) after defining new machine users to refresh it.
 
 ## OAuth 2.0 Clients
 
@@ -350,7 +348,7 @@ oauth2Clients: {
 Get OAuth2 client credentials using the CLI:
 
 ```bash
-tailor-sdk oauth2client get <name>
+tailor oauth2client get <name>
 ```
 
 ## Identity Provider
@@ -365,21 +363,18 @@ See [IdP](./idp.md) for configuring identity providers.
 
 ## Auth Connections
 
-Auth connections enable OAuth2 authentication with external providers (Google, Microsoft 365, QuickBooks, etc.) for application-to-application flows. Functions can access connection tokens at runtime via `tailor.authconnection.getConnectionToken()`.
+Auth connections enable OAuth2 authentication with external providers (Google, Microsoft 365, QuickBooks, etc.) for application-to-application flows. Functions can access connection tokens at runtime via `authconnection.getConnectionToken()` (from `@tailor-platform/sdk/runtime`).
 
 For the official Tailor Platform documentation, see [AuthConnection Guide](https://docs.tailor.tech/guides/auth/authconnection).
 
-> [!WARNING]
-> **Managing connections through `tailor.config.ts` is unreliable for shared and CI deploys.**
-> A deploy revokes and recreates the connection — discarding the token obtained via `authconnection authorize` — whenever it cannot confirm the secret is unchanged. That check relies on a hash stored locally in `.tailor-sdk/secrets-state.json`, which is gitignored and therefore not shared across machines. So a deploy from CI, a clean checkout, another developer's machine, or after deleting `.tailor-sdk/` recreates the connection and drops its token. Only repeated deploys from the same machine that still holds that state keep the token.
->
-> Because of this, prefer to **create the connection and its token from the Console**. You can jump to the connections page with:
+> [!NOTE]
+> Deploy updates connections **in-place**, preserving the OAuth token. If the connection requires re-authorization after an update, the deploy will warn you:
 >
 > ```bash
-> tailor-sdk authconnection open
+> tailor authconnection authorize --name <connection-name>
+> # Or via the Console:
+> tailor authconnection open
 > ```
->
-> The `connections` field in `defineAuth()` and the `authconnection authorize` flow are documented below for reference.
 
 ### Setup Flow
 
@@ -411,10 +406,10 @@ export const auth = defineAuth("my-auth", {
 });
 ```
 
-After `tailor-sdk deploy`, authorize the connection:
+After `tailor deploy`, authorize the connection:
 
 ```bash
-tailor-sdk authconnection authorize --name google-connection \
+tailor authconnection authorize --name google-connection \
   --scopes "openid,profile,email"
 ```
 
@@ -432,30 +427,25 @@ The authorize command opens a browser for the OAuth2 flow. The authorization cod
 | `authUrl`      | `string` | No       | Override for the authorization endpoint.    |
 | `tokenUrl`     | `string` | No       | Override for the token endpoint.            |
 
-### Change Detection
-
-The SDK uses hash-based change detection for connection configs. Only connections whose configuration has changed since the last `apply` are updated (revoked and recreated). Deleting the `.tailor-sdk/` directory forces all connections to be re-sent.
+### Retrieving Connection Tokens
 
-> [!WARNING]
-> The secret hash lives in `.tailor-sdk/secrets-state.json`, which is gitignored and not shared across machines or CI. When that state is missing — a clean checkout, CI, another machine, or after deleting `.tailor-sdk/` — a deploy cannot confirm the secret is unchanged, so it revokes and recreates the connection and discards the token stored by `authconnection authorize`. For shared and CI workflows, manage the connection and create its token from the Console (`tailor-sdk authconnection open`) instead.
-
-### `auth.getConnectionToken()`
-
-`auth.getConnectionToken()` retrieves connection tokens at runtime by calling `tailor.authconnection.getConnectionToken()` internally. When `connections` is defined in `defineAuth()`, the connection name is type-checked and autocompleted against the defined keys:
+Use `authconnection.getConnectionToken()` from `@tailor-platform/sdk/runtime` to retrieve connection tokens at runtime. The connection name is type-checked and autocompleted against the connections defined in `defineAuth()`'s `connections`:
 
 ```typescript
-import { auth } from "../tailor.config";
+import { authconnection } from "@tailor-platform/sdk/runtime";
 
 // In a resolver, executor, or workflow:
-const tokens = await auth.getConnectionToken("google-connection");
+const tokens = await authconnection.getConnectionToken("google-connection");
 const response = await fetch("https://www.googleapis.com/...", {
   headers: { Authorization: `Bearer ${tokens.access_token}` },
 });
 
-// auth.getConnectionToken("unknown"); // Type error — only "google-connection" is allowed
+// authconnection.getConnectionToken("unknown"); // Type error — only "google-connection" is allowed
 ```
 
-When `connections` is not defined, `getConnectionToken()` accepts any string. This supports connections managed entirely via the CLI.
+Type narrowing is provided by the generated `tailor.d.ts` (the `ConnectionNameRegistry` interface). Run `tailor generate` (or `deploy`) after defining new connections to refresh it. Before the first generate, or when `connections` is not defined in `defineAuth()`, `getConnectionToken()` accepts any string — this also supports connections managed entirely via the CLI.
+
+This keeps runtime files independent from `tailor.config.ts`.
 
 See [Built-in Interfaces](https://docs.tailor.tech/guides/function/builtin-interfaces.html#auth-connection) for the full runtime API.
 
@@ -465,19 +455,19 @@ Auth connections can also be managed via the CLI:
 
 ```bash
 # Open the connections page in the Console (recommended for creating connections/tokens)
-tailor-sdk authconnection open
+tailor authconnection open
 
 # Authorize (opens browser for OAuth2 flow)
-tailor-sdk authconnection authorize --name google-connection
+tailor authconnection authorize --name google-connection
 
 # List all connections
-tailor-sdk authconnection list
+tailor authconnection list
 
 # Revoke a connection
-tailor-sdk authconnection revoke --name google-connection
+tailor authconnection revoke --name google-connection
 ```
 
-Connection creation is handled by `tailor-sdk deploy` via the config, but recreation on deploy can drop the authorized token (see the warning at the top of this section) — for shared and CI workflows, create connections and tokens from the Console (`tailor-sdk authconnection open`) instead.
+Connection creation and updates are handled by `tailor deploy` via the config. Deploy updates connections in-place, preserving the authorized token, and warns you if an update requires re-authorization (see the note above).
 
 See [Auth Resource Commands](../cli/auth.md) for full CLI documentation.
 
@@ -515,27 +505,46 @@ export const auth = defineAuth("my-auth", {
 
 **invoker**: The machine user whose permissions are used to execute the hook. Must reference a machine user defined in the same auth configuration.
 
+### Federated identity claims
+
+When a user signs in through a Built-in IdP OAuth provider (Google or Microsoft), the upstream provider's profile is available on `claims.federated_identity`. It is `undefined` for password logins, so guard before reading it. Commonly present claims (`name`, `given_name`, `family_name`, `picture`, `locale`) are typed; any other claim the provider issues is forwarded as-is. Availability varies by provider (for example, Microsoft does not issue `picture`).
+
+```typescript
+hooks: {
+  beforeLogin: {
+    handler: async ({ claims }) => {
+      const federated = claims.federated_identity;
+      if (federated?.provider === "google") {
+        // Populate the user record from the upstream profile
+        const avatarUrl = federated.claims.picture;
+      }
+    },
+    invoker: "hook-invoker",
+  },
+}
+```
+
 ## CLI Commands
 
 Manage Auth resources using the CLI:
 
 ```bash
 # Auth connections
-tailor-sdk authconnection authorize --name <name>
-tailor-sdk authconnection list
-tailor-sdk authconnection revoke --name <name>
+tailor authconnection authorize --name <name>
+tailor authconnection list
+tailor authconnection revoke --name <name>
 
 # List machine users
-tailor-sdk machineuser list
+tailor machineuser list
 
 # Get machine user token
-tailor-sdk machineuser token <name>
+tailor machineuser token <name>
 
 # List OAuth2 clients
-tailor-sdk oauth2client list
+tailor oauth2client list
 
 # Get OAuth2 client credentials
-tailor-sdk oauth2client get <name>
+tailor oauth2client get <name>
 ```
 
 See [Auth Resource Commands](../cli/auth.md) for full documentation.

package/docs/services/executor.md

@@ -219,7 +219,7 @@ createExecutor({
 });
 ```
 
-Executor callbacks receive the trigger args, including `env` from `defineConfig({ env })`. `function` and `jobFunction` `body` args also include an `invoker` field: the principal running this function, overridden by `authInvoker` when set; `null` for anonymous calls. Other operation kinds (`graphql`, `webhook`, `workflow`) receive `env` through their callback args but do not pass `invoker` into those callbacks.
+Executor callbacks receive the trigger args, including `env` from `defineConfig({ env })`. `function` and `jobFunction` `body` args also include an `invoker` field: the principal running this function, or the machine user configured through the operation `invoker` option; `null` for anonymous calls. Other operation kinds (`graphql`, `webhook`, `workflow`) receive `env` through their callback args but do not pass `invoker` into those callbacks.
 
 ### Job Function Operation
 
@@ -329,9 +329,14 @@ createExecutor({
 });
 ```
 
+`args` must match the workflow's main job input. It is required when that input is required
+and can be omitted when the workflow has no input. Static arguments can be JSON-compatible
+primitives, arrays, or plain objects; top-level `null` is not supported. An argument callback
+must return the same input type.
+
 ### Authentication for Operations
 
-GraphQL and Workflow operations can specify an `authInvoker` to execute with machine user credentials. Pass the machine user name as a plain string — it is type-narrowed to the names defined in your auth config:
+GraphQL and Workflow operations can specify an `invoker` to execute with machine user credentials. Pass the machine user name as a plain string — it is type-narrowed to the names defined in your auth config:
 
 ```typescript
 import { createExecutor, scheduleTrigger } from "@tailor-platform/sdk";
@@ -342,13 +347,11 @@ export default createExecutor({
   operation: {
     kind: "graphql",
     query: `mutation { cleanupOldRecords { count } }`,
-    authInvoker: "batch-processor",
+    invoker: "batch-processor",
   },
 });
 ```
 
-> **Deprecated:** `auth.invoker("batch-processor")` still works, but is deprecated. Prefer the string form to avoid importing config-layer modules into runtime files.
-
 ## Event Payloads
 
 Each trigger type provides specific context data in the callback functions.

package/docs/services/http-adapter.md

@@ -7,7 +7,7 @@ HTTP adapters expose REST-style HTTP endpoints on your application by translatin
 Each HTTP adapter is a single file that declares:
 
 - A `pathPattern` (which methods it handles is derived from the `input` keys)
-- An `input` object keyed by lowercase HTTP method (`get`, `post`, `put`, `patch`, `delete`) — each value is a function that converts an incoming HTTP request into a GraphQL request (`query`, `variables`, `operationName`)
+- An `input` object keyed by lowercase HTTP method (`get`, `post`, `put`, `patch`, `delete`) — each value is a function that converts an incoming HTTP request into a GraphQL request (`query`, `variables`, `operationName`). `query` can be a GraphQL string or a generated `TypedDocumentNode`.
 - An optional `output` function — **shared across all methods** — that converts the GraphQL response into an HTTP response (`statusCode`, `headers`, `body`)
 
 Adapters are deployed together with your application. When a request arrives under the `/api/` prefix and matches an adapter, the handler for the request method runs server-side.
@@ -74,6 +74,21 @@ A request to `GET /api/users/abc-123` invokes the `get` handler, runs the result
 
 If `output` is omitted, the raw GraphQL response is returned as JSON.
 
+### Typed GraphQL Documents
+
+`input` handlers can return generated `TypedDocumentNode` values instead of query strings. The SDK uses the document's variables type for `variables`, and passes the document's result type to `output` as `resp.data`.
+
+```typescript
+import { GetUserDocument } from "../generated/graphql";
+
+get: (req) => ({
+  query: GetUserDocument,
+  variables: { id: req.path.split("/")[2] ?? "" },
+});
+```
+
+When multiple methods return different typed documents, `resp.data` is the union of those result types because `output` is shared across the adapter. If a method returns a plain string query, its result type is `unknown`. When extracting an input handler and annotating it separately, pass the document type to `HttpAdapterInputFn` so required variables stay typed.
+
 ### Optional fields
 
 Beyond `name`, `pathPattern`, `input`, and `output`, two optional fields control deploy-time behavior:

package/docs/services/idp.md

@@ -86,7 +86,8 @@ defineIdp("my-idp", {
 - `read` - Controls who can read IdP users
 - `update` - Controls who can update IdP users
 - `delete` - Controls who can delete IdP users
-- `sendPasswordResetEmail` - Controls who can send password reset emails. The examples above disable this operation; to enable it, use a permission such as `[{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }]`.
+- `sendPasswordResetEmail` - Controls who can send password reset emails. Required unless `userAuthPolicy.disablePasswordAuth` is `true` or `gqlOperations.sendPasswordResetEmail` is `false` (the password-reset flow has no meaning when password authentication is off or the operation is disabled). Set `[{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }]` to allow, or `[]` to deny.
+- `unenrollMfa` - Controls who can remove an enrolled MFA factor from a user. Required when `userAuthPolicy.enableMfa` is `true` unless `gqlOperations.unenrollMfa` is `false`; omit otherwise. Typically restricted to administrators.
 
 **Policy fields:** each entry in an operation's policy array supports:
 
@@ -166,6 +167,37 @@ defineIdp("my-idp", {
 - `allowGoogleOauth` - Enable the "Sign in with Google" button. Default `false`.
 - `allowMicrosoftOauth` - Enable the "Sign in with Microsoft" button. Default `false`.
 
+**MFA (TOTP):**
+
+```typescript
+import { defineIdp, defineStaticWebSite } from "@tailor-platform/sdk";
+
+const website = defineStaticWebSite("my-frontend", { description: "App frontend" });
+
+defineIdp("my-idp", {
+  clients: ["my-client"],
+  userAuthPolicy: {
+    enableMfa: true,
+    requireMfa: false,
+    allowedReturnOrigins: [website.url, "https://admin.example.com"],
+    mfaIssuer: "My App",
+  },
+  permission: {
+    create: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
+    read: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
+    update: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
+    delete: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
+    sendPasswordResetEmail: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
+    unenrollMfa: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
+  },
+});
+```
+
+- `enableMfa` - Make TOTP MFA available for users in this namespace. Default `false`. When enabled, users can register an authenticator app (Google Authenticator, 1Password, etc.) from the IdP self-service page.
+- `requireMfa` - Force password-authenticated users to enroll and pass an MFA challenge on each sign-in. Default `false`. Social sign-in (`allowGoogleOauth` / `allowMicrosoftOauth`) is not affected; the upstream provider's MFA covers those sessions.
+- `allowedReturnOrigins` - Origins the IdP self-service pages (such as `/mfa/settings`) are allowed to redirect back to. Each entry is either a literal origin (`https://app.example.com`, scheme + host + optional port, no path/query/fragment) or a static-website placeholder `<name>:url` (e.g. `website.url`) that the CLI resolves to the deployed website's URL at apply time. Required when `enableMfa` is `true`.
+- `mfaIssuer` - Label shown next to the user account in authenticator apps when TOTP is enrolled. Up to 64 characters. Falls back to `"Tailor Platform IdP"` when empty.
+
 **Constraints:** the following combinations are rejected at parse time.
 
 - `passwordMinLength` must be less than or equal to `passwordMaxLength`.
@@ -173,6 +205,23 @@ defineIdp("my-idp", {
 - `allowGoogleOauth` requires a non-empty `allowedEmailDomains`.
 - `allowMicrosoftOauth` requires both a non-empty `allowedEmailDomains` and `disablePasswordAuth: true`.
 - `disablePasswordAuth` requires `allowGoogleOauth` or `allowMicrosoftOauth`, and cannot be combined with `allowSelfPasswordReset`.
+- `requireMfa: true` requires `enableMfa: true`.
+- `enableMfa: true` requires at least one entry in `allowedReturnOrigins`.
+- `enableMfa: true` requires `permission` to be defined and to include an explicit `unenrollMfa` policy (an empty array `[]` to deny is fine), unless `gqlOperations.unenrollMfa` is `false` (or `gqlOperations: "query"`, which normalizes to the same), in which case the operation is turned off and the policy may be omitted.
+
+**Runtime API:** function code can inspect and revoke a user's enrolled factor through `idp.Client`. The `User` records returned by `user`, `userByName`, `users`, `createUser`, and `updateUser` expose `mfaEnrolled` (boolean) and `mfaFactorIds` (string array), and `client.unenrollMfa({ userId, mfaFactorId })` removes a single factor. The factor ID to pass back is one of the entries in `user.mfaFactorIds`. Calling `unenrollMfa` requires the `unenrollMfa` permission above.
+
+```typescript
+import { idp } from "@tailor-platform/sdk/runtime";
+
+const client = new idp.Client({ namespace: "my-idp" });
+const user = await client.user("user-id");
+if (user.mfaEnrolled) {
+  for (const factorId of user.mfaFactorIds) {
+    await client.unenrollMfa({ userId: user.id, mfaFactorId: factorId });
+  }
+}
+```
 
 ### gqlOperations
 
@@ -187,6 +236,8 @@ defineIdp("my-idp", {
     update: true,
     delete: false,
     sendPasswordResetEmail: false,
+    requestMfaSettingsUrl: false,
+    unenrollMfa: false,
   },
 });
 ```
@@ -198,8 +249,10 @@ defineIdp("my-idp", {
 - `update` - The `_updateUser` mutation.
 - `delete` - The `_deleteUser` mutation.
 - `sendPasswordResetEmail` - The `_sendPasswordResetEmail` mutation.
+- `requestMfaSettingsUrl` - The `_requestMfaSettingsUrl` query that issues a self-service URL for MFA settings.
+- `unenrollMfa` - The `_unenrollMfa` mutation that removes a user's enrolled MFA factor. When set to `false`, `permission.unenrollMfa` may be omitted even with `userAuthPolicy.enableMfa: true`.
 
-**Shortcut:** pass the string `"query"` to expose a read-only IdP. It enables `read` and disables every mutation.
+**Shortcut:** pass the string `"query"` to expose a read-only IdP. It enables the queries (`read`, `requestMfaSettingsUrl`) and disables every mutation.
 
 ```typescript
 defineIdp("my-idp", {

package/docs/services/resolver.md

@@ -108,7 +108,7 @@ Define input/output schemas using methods of `t` object. Basic usage and support
 You can reuse fields defined with `db` object, but note that unsupported options will be ignored:
 
 ```typescript
-const user = db.type("User", {
+const user = db.table("User", {
   name: db.string().unique(),
   age: db.int(),
 });
@@ -208,7 +208,7 @@ Validation functions receive:
 
 - `value` - The field value being validated
 - `data` - The entire input object
-- `user` - The user performing the operation
+- `invoker` - The principal performing the operation
 
 You can specify validation as:
 
@@ -234,13 +234,13 @@ Validation runs automatically before the `body` function executes. When validati
 Define actual resolver logic in the `body` function. Function arguments include:
 
 - `input` - Input data from GraphQL request
-- `user` - The user who called this resolver; unaffected by `authInvoker`
-- `invoker` - The principal running this function; equals `user` by default, or the machine user set by `authInvoker`. `null` for anonymous calls.
+- `caller` - The user or machine user who called this resolver; unaffected by `invoker`. `null` for anonymous calls.
+- `invoker` - The principal running this function; equals `caller` by default, or the machine user configured through the resolver `invoker` option. `null` for anonymous calls.
 - `env` - Environment variables declared in `tailor.config.ts`
 
 ### Using Kysely for Database Access
 
-If you're generating Kysely types with a generator, you can use `getDB` to execute typed queries:
+If you're generating Kysely types with `kyselyTypePlugin`, you can use `getDB` to execute typed queries:
 
 ```typescript
 import { getDB } from "../generated/tailordb";
@@ -306,7 +306,7 @@ createResolver({
 
 - When `publishEvents: true`, resolver execution events are published
 - When not specified, it is **automatically set to `true`** if an executor uses this resolver with `resolverExecutedTrigger`
-- When explicitly set to `false` while an executor uses this resolver, an error is thrown during `tailor apply`
+- When explicitly set to `false` while an executor uses this resolver, an error is thrown during `tailor deploy`
 
 **Use cases:**
 
@@ -350,9 +350,63 @@ createResolver({
    });
    ```
 
+## Permissions
+
+### Access Requirement (`permission`)
+
+By default, a resolver with no in-body check is reachable by an anonymous (unauthenticated) caller. Set `permission` to reject callers that don't match a condition, evaluated before `body` runs:
+
+```typescript
+import { createResolver, t } from "@tailor-platform/sdk";
+
+export default createResolver({
+  name: "getMyOrders",
+  operation: "query",
+  permission: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
+  output: t.object({ count: t.int() }),
+  body: async (context) => {
+    // context.user is guaranteed to be an authenticated caller here
+    return { count: 0 };
+  },
+});
+```
+
+`permission` uses the same `conditions`/`permit` notation as TailorDB's `.permission()` — an array of policies, restricted to `user` operands (a resolver has no associated record to compare against) with equality (`=`/`!=`) comparisons:
+
+- `{ user: "_loggedIn" }` — whether the caller is authenticated
+- `{ user: "id" }` — the caller's user ID
+- `{ user: "someAttribute" }` — any string or boolean attribute enabled in `auth.userProfile.attributes` (or `auth.machineUserAttributes` for machine users); array attributes aren't supported, since conditions only compare against a single string/boolean value
+
+Multiple conditions within the same policy's `conditions` array are combined with AND. `permit` is required, with no implicit default. At least one `permit: true` policy is required: `permission` is an allow-list, denied by default and granted only by a matching `permit: true` policy. This lets you express different eligibility paths, e.g. allowing machine-user callers unconditionally while gating regular users behind a role check:
+
+```typescript
+permission: [
+  { conditions: [[{ user: "isServiceAccount" }, "=", true]], permit: true },
+  { conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true },
+],
+```
+
+A `permit: false` policy always denies matching callers, even ones another policy would otherwise allow. Combine it with a `permit: true` policy to carve out an explicit exception, e.g. granting access broadly but rejecting one banned role:
+
+```typescript
+permission: [
+  { conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true },
+  { conditions: [[{ user: "role" }, "=", "BANNED"]], permit: false },
+],
+```
+
+A policy array made up of only `permit: false` policies is rejected: since none of its conditions apply to a caller presenting no user attributes at all, it wouldn't actually keep anyone out who's willing to drop their credentials, so it can't stand in for an allow-list.
+
+Besides a policy array, `permission` also accepts:
+
+- `"allowAnonymous"` — explicitly documents that anonymous callers are allowed. Behaves the same as omitting `permission`, but records the decision so it isn't mistaken for an oversight.
+- Omitted (default) — unchanged: anonymous callers can still reach the resolver.
+
+This check is based on `context.user`, the original caller, so it still applies even when `authInvoker` swaps in a machine user for database access.
+
 ## Authentication
 
-Specify an `authInvoker` to execute the resolver with machine user credentials. Pass the machine user name as a plain string — it is type-narrowed to the names you defined in your auth config:
+Specify an `invoker` to execute the resolver with machine user credentials. Pass the machine user name as a plain string — it is type-narrowed to the names you defined in your auth config:
 
 ```typescript
 import { createResolver, t } from "@tailor-platform/sdk";
@@ -365,12 +419,10 @@ export default createResolver({
     // Executes as "batch-processor" machine user
     return { result: "ok" };
   },
-  authInvoker: "batch-processor",
+  invoker: "batch-processor",
 });
 ```
 
 The machine user name is looked up in the auth service configured on your app (`machineUsers` in `defineAuth`). The namespace is resolved automatically — no need to import `auth` from `tailor.config.ts` in resolver files.
 
-> **Deprecated:** `auth.invoker("batch-processor")` still works, but is deprecated. Importing `auth` into runtime files pulls config-layer (Node-only) dependencies into the bundle.
-
-**Note:** `authInvoker` controls the permissions for database operations and other platform actions. The `user` object passed to `body` still reflects the original caller, while `invoker` reflects the principal actually running the body.
+**Note:** The `invoker` option controls the permissions for database operations and other platform actions. The `caller` object passed to `body` still reflects the original caller, while the `invoker` body field reflects the principal actually running the body.