@softr/sdk 0.0.24 → 0.0.25

package/skills/softr-sdk/auth/SKILL.md

@@ -1,30 +1,69 @@
 ---
 name: auth
 description: >-
-  Sign a Softr visitor in, out, or up from a server function: auth.signIn,
-  auth.signOut, auth.signUp and auth.confirmSignUp from @softr/sdk/server, the
-  Result shape they answer with ({ success, data } | { success, error }) and its
-  codes invalidCredentials, tooManyAttempts, emailTaken, invalidDetails and
-  invalidCode, the two-step sign-up, and redirecting after a successful sign-in.
-  The blank template already ships working login and signup pages.
+  Sign a Softr visitor in, out or up from a server function: auth.signIn,
+  signInWithCode, signInWithGoogle, signInWithMagicLink, signUp, confirmSignUp
+  and signOut from @softr/sdk/server, the authenticator-app calls that finish a
+  sign-in (verifyAuthenticator, startAuthenticatorSetup,
+  confirmAuthenticatorSetup, skipAuthenticatorSetup) and the ones that change an
+  authenticator from a settings page (sendAuthenticatorResetCode,
+  resetAuthenticator, removeAuthenticator). Covers the Result shape they answer
+  with ({ success, data } | { success, error }) and its codes
+  invalidCredentials, tooManyAttempts, emailTaken, invalidDetails, invalidCode
+  and notAuthenticated, the two-step sign-up, and why a successful sign-in does
+  not always mean the visitor is signed in. The blank template already ships
+  working login and signup pages.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.24
+  library_version: 0.0.25
 ---
 
 **Boundary.** `auth` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineVisibility`, the hooks and every type come from `@softr/sdk`. The app is already wired (`src/start.ts`, `src/router.tsx`, `src/routes/__root.tsx`); never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
 
 # Auth
 
-`auth` is what changes who the visitor is. It exposes four calls and nothing else:
+`auth` is what changes who the visitor is.
+
+Signing in:
+
+| Call | Does |
+| --- | --- |
+| `auth.signIn({ email, password })` | Signs a visitor in with an email and password |
+| `auth.sendSignInCode({ email })` | Emails a one-time sign-in code |
+| `auth.signInWithCode({ email, code })` | Signs a visitor in with that code |
+| `auth.signInWithGoogle({ email, token, fullName? })` | Signs a visitor in with a Google id token the browser obtained, creating the account the first time |
+| `auth.signInWithMagicLink({ token })` | Signs a visitor in with the token from a magic link they followed |
+
+Signing up:
 
 | Call | Does |
 | --- | --- |
-| `auth.signIn({ email, password })` | Signs a visitor in |
-| `auth.signOut()` | Signs the visitor out |
 | `auth.signUp({ email, name? })` | Emails a verification code, creates no account |
-| `auth.confirmSignUp({ email, password, code, name? })` | Creates the account and signs in |
+| `auth.confirmSignUp({ email, code, name?, password? })` | Creates the account and signs the visitor in |
+
+Signing out:
+
+| Call | Does |
+| --- | --- |
+| `auth.signOut()` | Ends every session that visitor has in this app, on every device |
+
+Finishing a sign-in that wants an authenticator app:
+
+| Call | Does |
+| --- | --- |
+| `auth.verifyAuthenticator({ code })` or `({ backupCode })` | Answers the challenge with the code their app shows |
+| `auth.startAuthenticatorSetup()` | Hands back a QR code for enrolling an app |
+| `auth.confirmAuthenticatorSetup({ code })` | Enrols it on its first code, and returns the backup codes once |
+| `auth.skipAuthenticatorSetup()` | Skips enrolment, where the app allows skipping |
+
+Changing an authenticator from a settings page:
+
+| Call | Does |
+| --- | --- |
+| `auth.sendAuthenticatorResetCode()` | Emails the code the next two ask for |
+| `auth.resetAuthenticator({ code })` | Unpairs the app, so a new one can be enrolled |
+| `auth.removeAuthenticator({ code })` | Turns the authenticator off |
 
 **The blank template already ships a working login page and signup page.** Read `src/routes/_auth/login.tsx` before writing anything new. Most tasks are an edit to those, not a new flow.
 
@@ -57,7 +96,7 @@ A form that posts `FormData` instead validates with a function, since a zod obje
 .validator((fields: FormData) => Credentials.parse(Object.fromEntries(fields)))
 ```
 
-`signIn`, `signUp` and `confirmSignUp` answer with a `Result` rather than throwing on something the visitor can fix. `signOut` returns nothing.
+Every call except `signOut` answers with a `Result` rather than throwing on something the visitor can fix. `signOut` returns nothing.
 
 ```ts
 type Result<T> =
@@ -65,14 +104,42 @@ type Result<T> =
   | { success: false; error: { code: AuthErrorCode; message: string } }
 
 type AuthErrorCode =
-  | 'invalidCredentials'   // signIn: wrong email or password
-  | 'tooManyAttempts'      // signIn: rate limited
-  | 'emailTaken'           // signUp or confirmSignUp: that email already has an account
-  | 'invalidDetails'       // signUp: details Softr rejected
-  | 'invalidCode'          // confirmSignUp: wrong or expired verification code
+  | 'invalidCredentials'   // signIn, signInWithGoogle, signInWithMagicLink: wrong password, or a token Softr would not take
+  | 'tooManyAttempts'      // any call: rate limited
+  | 'emailTaken'           // signUp, confirmSignUp: that email already has an account
+  | 'invalidDetails'       // signUp, sendSignInCode: details Softr rejected
+  | 'invalidCode'          // any call that takes a code: wrong or expired
+  | 'notAuthenticated'     // a call that needs a signed-in visitor, made by one who is not
 ```
 
-Each code comes from the call named beside it. Email and password is the sign-in method these calls cover.
+Branch on `error.code` with a `switch` and write your own wording. Never put `error.message` in front of the visitor.
+
+`code` is typed as every code the SDK produces, not the ones a given call can answer, so a `switch` needs a `default` even when the cases above it are complete. Give it a message rather than leaving it out.
+
+## A successful sign-in is not always a session
+
+`signIn`, `signInWithCode`, `signInWithGoogle`, `signInWithMagicLink` and `confirmSignUp` all answer the same two ways:
+
+```ts
+{ status: 'signedIn', user }
+{ status: 'authenticatorRequired', step: 'verify' | 'setup' | 'setupOptional' }
+```
+
+`signedIn` is a session. Redirect into the app.
+
+`authenticatorRequired` is not. The app asks for an authenticator app as well, and the visitor has no session until they produce one. Redirecting into the app here sends them to a page they cannot see, and a guarded page bounces them back to the login form with nothing on screen explaining why.
+
+Send them on by `step`:
+
+| `step` | Show them | Finish with |
+| --- | --- | --- |
+| `verify` | a code field | `auth.verifyAuthenticator({ code })`, or `({ backupCode })` |
+| `setup` | the QR from `auth.startAuthenticatorSetup()` | `auth.confirmAuthenticatorSetup({ code })` |
+| `setupOptional` | the same, plus a skip button | the same, or `auth.skipAuthenticatorSetup()` |
+
+Those calls take only what the visitor typed. The sign-in they finish is the one already in progress for this browser, so nothing has to be carried through the UI. It does not stay open indefinitely, and a visitor who abandons the page signs in again from the start.
+
+An app with no authenticator app configured never answers `authenticatorRequired`. The type still has both arms either way, so `result.data.user` does not exist until you have narrowed on `status`.
 
 ## Core Patterns
 
@@ -85,19 +152,25 @@ const signIn = createServerFn({ method: 'POST' })
     const result = await auth.signIn(data)
 
     if (!result.success) {
-      return {
-        message:
-          result.error.code === 'tooManyAttempts'
-            ? 'Too many attempts. Please try again in a few minutes.'
-            : 'Please ensure your email and password are correct.',
+      switch (result.error.code) {
+        case 'invalidCredentials':
+          return { message: 'Please ensure your email and password are correct.' }
+        case 'tooManyAttempts':
+          return { message: 'Too many attempts. Please try again in a few minutes.' }
+        default:
+          return { message: 'Could not sign you in. Please try again.' }
       }
     }
 
+    if (result.data.status === 'authenticatorRequired') {
+      throw redirect({ to: '/verify', search: { step: result.data.step } })
+    }
+
     throw redirect({ to: '/' })
   })
 ```
 
-Two exits: return a message for the form to render, or `throw redirect` on success. Do not put `error.message` in front of the visitor. Write your own wording, as above.
+Three exits: a message for the form to render, a redirect to the second factor, a redirect into the app.
 
 Call it from the component with `useServerFn`:
 
@@ -111,6 +184,43 @@ A server function that throws `redirect` needs the hook. Call the imported funct
 
 A login page is a `NON_LOGGED_IN_USERS` route, which is what keeps an already-signed-in visitor off it. See [routes-and-visibility](../routes-and-visibility/SKILL.md).
 
+### Sign in with an emailed code
+
+For an app that signs people in with a code instead of a password.
+
+```ts
+// Step 1: emails the code.
+const sent = await auth.sendSignInCode({ email })
+
+// Step 2: same two-armed result as signIn.
+const result = await auth.signInWithCode({ email, code })
+```
+
+Step one succeeds whether or not that address has an account, so the form cannot be used to find out who is registered. Say "check your email" either way, and never branch the UI on it.
+
+### Sign in with Google
+
+```ts
+const result = await auth.signInWithGoogle({
+  email,
+  token,     // the id token Google Identity Services handed the page
+  fullName,  // names a first-time visitor, ignored for an existing one
+})
+```
+
+Only an id token works. An access token, a token minted for another app, and an email that does not match it all fail as `invalidCredentials`.
+
+### Sign in with a magic link
+
+For the route the link in the email points at.
+
+```ts
+// Same two-armed result as signIn.
+const result = await auth.signInWithMagicLink({ token })
+```
+
+The token keeps working after it is used, so anyone holding the link can sign in as that visitor. Never log it, and redirect away from the URL that carried it.
+
 ### Sign out
 
 ```ts
@@ -120,7 +230,7 @@ const signOut = createServerFn({ method: 'POST' }).handler(async () => {
 })
 ```
 
-It returns nothing and has no failure the visitor can act on, so send them somewhere and let the redirect re-resolve the context.
+It returns nothing and has no failure the visitor can act on, so send them somewhere and let the redirect re-resolve the context. It ends every session that visitor has in this app, on every device, so a "sign out of this device only" button is not something you can build on it.
 
 ### Sign up, in two steps
 
@@ -134,11 +244,15 @@ const startSignUp = createServerFn({ method: 'POST' })
   .handler(async ({ data }) => {
     const result = await auth.signUp(data)
     if (!result.success) {
-      return {
-        message:
-          result.error.code === 'emailTaken'
-            ? 'That email already has an account.'
-            : 'Please check the details and try again.',
+      switch (result.error.code) {
+        case 'emailTaken':
+          return { message: 'That email already has an account.' }
+        case 'invalidDetails':
+          return { message: 'Please check the details and try again.' }
+        case 'tooManyAttempts':
+          return { message: 'Too many attempts. Please try again in a few minutes.' }
+        default:
+          return { message: 'Could not start the sign-up. Please try again.' }
       }
     }
     return { message: null }   // now show the code field
@@ -150,19 +264,91 @@ const finishSignUp = createServerFn({ method: 'POST' })
   .handler(async ({ data }) => {
     const result = await auth.confirmSignUp(data)
     if (!result.success) {
-      return {
-        message:
-          result.error.code === 'emailTaken'
-            ? 'That email already has an account. Please sign in instead.'
-            : 'That code is not valid. Please try again.',
+      switch (result.error.code) {
+        case 'emailTaken':
+          return { message: 'That email already has an account. Please sign in instead.' }
+        case 'invalidCode':
+          return { message: 'That code is not valid. Please try again.' }
+        case 'tooManyAttempts':
+          return { message: 'Too many attempts. Please try again in a few minutes.' }
+        default:
+          return { message: 'Could not finish the sign-up. Please try again.' }
       }
     }
 
+    if (result.data.status === 'authenticatorRequired') {
+      throw redirect({ to: '/verify', search: { step: result.data.step } })
+    }
+
     throw redirect({ to: '/' })
   })
 ```
 
-The UI has to carry email and password into step two, plus the name if step one collected one. `name` is optional to `confirmSignUp`, the rest is not. It is the only call that creates the account.
+The UI has to carry email into step two, plus the name if step one collected one. `confirmSignUp` is the only call that creates the account.
+
+`password` is what the account is created with. Leave it out only for an app that signs people in with an emailed code. An app that expects a password rejects a sign-up without one, and an app that does not expect one rejects a sign-up that sends it.
+
+### Finishing a sign-in that needs an authenticator app
+
+On `step: 'verify'` the visitor already has an app, and owes a code from it:
+
+```ts
+const verify = createServerFn({ method: 'POST' })
+  .validator(z.object({ code: z.string() }))
+  .handler(async ({ data }) => {
+    const result = await auth.verifyAuthenticator(data)
+    if (!result.success) {
+      switch (result.error.code) {
+        case 'invalidCode':
+          return { message: 'That code is not valid. Please try again.' }
+        case 'tooManyAttempts':
+          return { message: 'Too many attempts. Please try again in a few minutes.' }
+        default:
+          return { message: 'Could not check that code. Please try again.' }
+      }
+    }
+    throw redirect({ to: '/' })
+  })
+```
+
+A visitor without their phone sends `{ backupCode }` instead of `{ code }`. Each backup code works once.
+
+On `step: 'setup'` or `'setupOptional'` they have no app yet:
+
+```ts
+const start = await auth.startAuthenticatorSetup()
+if (!start.success) return { message: 'Could not start setup. Please try again.' }
+
+start.data.otpauthUri    // what an authenticator app reads
+start.data.qrPngBase64   // the same URI as a PNG, for
+                         // <img src={`data:image/png;base64,${qrPngBase64}`} />
+```
+
+Neither of those enrols anybody. `confirmAuthenticatorSetup` does, once it accepts a first code:
+
+```ts
+const done = await auth.confirmAuthenticatorSetup({ code })
+if (done.success) {
+  done.data.backupCodes  // returned once. Render them now, nothing fetches them again.
+  throw redirect({ to: '/' })
+}
+```
+
+Call `startAuthenticatorSetup` again to hand back a fresh QR code, for a visitor who lost the first one. Only the newest one enrols them.
+
+`skipAuthenticatorSetup` finishes the sign-in without enrolling, and only on `setupOptional`. Later sign-ins stop asking.
+
+### Changing an authenticator from a settings page
+
+```ts
+await auth.sendAuthenticatorResetCode()   // emails the code the next two ask for
+await auth.resetAuthenticator({ code })   // unpairs the app, so a new one can be enrolled
+await auth.removeAuthenticator({ code })  // turns the authenticator off
+```
+
+All three need a signed-in visitor and answer `notAuthenticated` when there is not one. Both changes ask for a code from the visitor's inbox as well, because both change how that visitor signs in.
+
+After a reset, enrol the new app with `startAuthenticatorSetup` and `confirmAuthenticatorSetup`, which is also where the new backup codes come from. After a removal, an app that requires an authenticator asks the visitor to set one up again on their next sign-in.
 
 ## References
 

package/skills/softr-sdk/current-user/SKILL.md

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.24
+  library_version: 0.0.25
 ---
 
 **Boundary.** `useCurrentUser`, `usePermissions` and every type come from `@softr/sdk` and work anywhere; `ds` and `auth` live on `@softr/sdk/server` and run only inside a `createServerFn` handler. The app is already wired — `src/start.ts` registers `softrAuthMiddleware`, `src/routes/__root.tsx` publishes the visitor as route context — never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.

package/skills/softr-sdk/data-mutations/SKILL.md

@@ -8,7 +8,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.24
+  library_version: 0.0.25
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `q` and every type come from `@softr/sdk` and can be imported anywhere. The app is already wired (`src/start.ts`, `src/router.tsx`, `src/routes/__root.tsx`); never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.

package/skills/softr-sdk/reading-records/SKILL.md

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.24
+  library_version: 0.0.25
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler or a server-side route hook — importing it into a component fails the build. `q` and every type come from `@softr/sdk` and can be imported anywhere. The app is already wired (`src/start.ts`, `src/router.tsx`, `src/routes/__root.tsx`); never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.

package/skills/softr-sdk/routes-and-visibility/SKILL.md

@@ -12,7 +12,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.24
+  library_version: 0.0.25
 ---
 
 **Boundary.** `defineVisibility`, the error predicates and every type come from `@softr/sdk` and work anywhere; `ds` and `auth` live on `@softr/sdk/server` and run only inside a `createServerFn` handler. The app is already wired — `src/start.ts` registers `softrAuthMiddleware`, `src/routes/__root.tsx` publishes the visitor as route context — never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.