@proveanything/smartlinks 1.15.10 → 1.15.13

package/docs/auth-kit.md

@@ -304,6 +304,116 @@ clearPersistedTokens();
 
 ---
 
+## Step-up MFA (Phase 1)
+
+Backend-only for now — **no admin-console UI and no challenge UI ship with this pass.**
+Factors: **email OTP, SMS OTP, recovery codes**. WhatsApp OTP, TOTP, and passkeys are
+deferred to a later phase; don't build against them yet.
+
+The step-up gate is wired into **`login()` only** — `register`, `verifyPhoneCode`, and
+`verifyMagicLink` never return `MFA_REQUIRED`, regardless of client config.
+
+### Handling `MFA_REQUIRED` from `login()`
+
+`login()`'s return type is unchanged. When the client's MFA policy requires a step-up,
+the server returns 403 instead of a session, and `login()` throws:
+
+```ts
+import { authKit, SmartlinksApiError } from '@proveanything/smartlinks';
+
+try {
+  const session = await authKit.login(clientId, email, password);
+  // logged in, no MFA required
+} catch (err) {
+  if (err instanceof SmartlinksApiError && err.errorCode === 'MFA_REQUIRED') {
+    const { mfaSessionToken, availableFactors, preferredFactor, maskedDestinations } = err.details!;
+    // → route to a challenge UI; call authKit.mfaChallengeSend(clientId, mfaSessionToken, preferredFactor)
+  } else {
+    throw err;
+  }
+}
+```
+
+### Completing the challenge
+
+```ts
+// Send (or resend, or switch factor) a code on the same mfaSessionToken
+const sent = await authKit.mfaChallengeSend(clientId, mfaSessionToken, 'sms');
+// sent.destination is masked, e.g. "+1******1234"
+
+// Verify the code — behaves like login() on success: bearer token is adopted automatically
+const session = await authKit.mfaChallengeVerify(clientId, mfaSessionToken, '123456', /* trustDevice */ true, 'My Laptop');
+
+// Or finalize with a single-use recovery code instead
+const session = await authKit.mfaRecoveryCode(clientId, mfaSessionToken, recoveryCode);
+```
+
+`mfaSessionToken` is short-lived (10 min) and single-use — burned on 5 failed attempts
+(`MFA_TOO_MANY_ATTEMPTS`) or on success. Once burned/expired, there's no "resend within the
+same session" — the caller must restart from `login()`.
+
+### Trusted devices — "don't ask again on this device"
+
+There's no fingerprinting involved: a "recognized device" is purely "the caller presented a
+valid, unexpired, unrevoked `trustedDeviceToken`". Handle it like the native refresh token
+above — same secure storage, same persist-before-next-call discipline:
+
+```ts
+// 1) Persist trustedDeviceToken from a successful challenge (trustDevice: true)
+persistTrustedDeviceToken(session.trustedDeviceToken, session.trustedDeviceExpiresAt);
+
+// 2) Send it on every subsequent login() — if still valid, the challenge is skipped entirely
+const session = await authKit.login(clientId, email, password, storedTrustedDeviceToken);
+// If it's revoked/expired, the server silently falls back to requiring a fresh challenge —
+// login() just throws MFA_REQUIRED again, no special-case handling needed.
+
+// 3) Let users audit/revoke devices from a Settings screen
+const { devices } = await authKit.listTrustedDevices(clientId);
+await authKit.revokeTrustedDevice(clientId, deviceId);
+```
+
+### Factor management (Settings → Security)
+
+Authenticated (bearer token) — same `mfaSessionToken` + code mechanism as login challenges,
+just against a `purpose: 'enroll'` challenge instead of `'login'`.
+
+```ts
+// Enroll email (uses the account's existing email)
+const { mfaSessionToken } = await authKit.enrollEmailMfa(clientId);
+await authKit.confirmEmailMfa(clientId, mfaSessionToken, code);
+
+// Enroll SMS
+const { mfaSessionToken: smsToken } = await authKit.enrollSmsMfa(clientId, '+61400000000');
+await authKit.confirmSmsMfa(clientId, smsToken, code);
+
+// Recovery codes — plaintext, shown exactly once; nothing else in the API returns them again
+const { recoveryCodes } = await authKit.generateMfaRecoveryCodes(clientId, password);
+
+// Inspect / remove
+const factors = await authKit.getMfaFactors(clientId);
+// factors: { enrolledFactors: { email?, sms? }, recoveryCodesRemaining, mfaEnabledForClient }
+await authKit.removeMfaFactor(clientId, 'sms', password);
+```
+
+> Enrollment endpoints don't currently check the client's `mfa.mode` — enrolling is possible
+> even when MFA is configured `'off'` for a client. Those factors simply won't be challenged
+> at login until an admin turns the mode on (via the existing admin AuthKit config update,
+> no new admin route in this pass).
+
+### MFA error codes
+
+| `errorCode` | HTTP | Meaning / client action |
+|---|---|---|
+| `MFA_REQUIRED` | 403 | From `login()` only — see above |
+| `INVALID_MFA_CODE` | 401 | Wrong code — let the user retry (attempts are capped) |
+| `MFA_TOO_MANY_ATTEMPTS` | 429 | 5 wrong attempts — the challenge is burned; restart from `login()` |
+| `MFA_FACTOR_NOT_ENROLLED` | 400 | Requested factor isn't enrolled — programming error if the UI only offers `availableFactors` |
+| `MFA_SESSION_EXPIRED` | 401 | `mfaSessionToken` past its 10-minute TTL — restart from `login()` |
+| `MFA_SESSION_INVALID` | 401 | Unknown/wrong-client/already-consumed token, or (on enroll confirm) mismatched user |
+| `RECOVERY_CODE_INVALID` | 401 | Wrong or already-used recovery code |
+
+---
+
 ## Profile management
 
 ```ts

package/docs/item-context.md

@@ -163,8 +163,7 @@ const showFakeWarning = await validateCondition({
 - `isAuthentic` — passes when `itemContext.isAuthentic` is true (`valid`/`rescan`)
 - `notAuthentic` — passes when an `itemContext` was resolved but isn't authentic (`invalid`/`not-found`/`error`)
 - `invalidProof` — passes specifically when resolution was attempted and came back `invalid` or `not-found` — the "someone scanned a fake tag / typed a bad serial" case, as distinct from `noProof` ("nothing was on the URL to check at all")
-- `isFirstScan` — the single "this is good, show the full experience" check: authentic AND this is the first time it's been seen (`status === 'valid'`)
-- `isRescan` — authentic but a duplicate/replayed tap (`status === 'rescan'`) — use this to suppress "first scan" celebration UX without treating the tag as fake; `isAuthentic` alone is true for both `isFirstScan` and `isRescan` cases
+- `isRescan` — authentic but a duplicate/replayed tap (`status === 'rescan'`) — use this to suppress "first scan" celebration UX without treating the tag as fake; `isAuthentic` alone is true for both a fresh tap and a rescan
 
 ## Deprecated
 

package/docs/utils.md

@@ -530,9 +530,9 @@ await utils.validateCondition({
 Status types:
 - Claim/ownership (reads `proof`): `'isClaimable'`, `'notClaimable'`, `'isVirtual'`, `'notVirtual'`
 - Presence (reads `proof`): `'hasProof'`, `'noProof'` — `noProof` only means *nothing was attempted*, not that an attempt failed
-- Authenticity (reads `itemContext`): `'isAuthentic'`, `'notAuthentic'`, `'invalidProof'`, `'isFirstScan'`, `'isRescan'`
+- Authenticity (reads `itemContext`): `'isAuthentic'`, `'notAuthentic'`, `'invalidProof'`, `'isRescan'`
   - `invalidProof` is specifically "an identifier was passed and resolution came back `invalid`/`not-found`", distinct from `noProof`'s "nothing on the URL to check at all"
-  - `isAuthentic` is true for both a fresh tap and a rescan. Use `isFirstScan` (authentic AND `status === 'valid'`) as the single "this is good, show the full experience" check, and `isRescan` (authentic but `status === 'rescan'`) to suppress "first scan" celebration UX without treating the tag as fake
+  - `isAuthentic` is true for both a fresh tap and a rescan. Use `isRescan` (authentic but `status === 'rescan'`) to suppress "first scan" celebration UX without treating the tag as fake
 
 #### Version Conditions
 For A/B testing or versioned content:

package/openapi.yaml

@@ -8077,7 +8077,7 @@ paths:
     get:
       tags:
         - authKit
-      summary: authKit.load
+      summary: Revoke a single trusted device by id (authenticated).
       operationId: authKit_load
       security: []
       parameters:
@@ -8970,6 +8970,285 @@ paths:
           application/json:
             schema:
               $ref: "#/components/schemas/UpsertContactRequest"
+  /authkit/{clientId}/mfa/challenge/recovery-code:
+    post:
+      tags:
+        - authKit
+      summary: Finalize a challenged login using a single-use recovery code instead of a sent code (public).
+      operationId: authKit_mfaRecoveryCode
+      security: []
+      parameters:
+        - name: clientId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MfaFinalizeResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+  /authkit/{clientId}/mfa/challenge/send:
+    post:
+      tags:
+        - authKit
+      summary: Send (or resend) an MFA challenge code to the given factor (public).
+      operationId: authKit_mfaChallengeSend
+      security: []
+      parameters:
+        - name: clientId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MfaChallengeSendResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: string
+              enum:
+                - email
+                - sms
+  /authkit/{clientId}/mfa/challenge/verify:
+    post:
+      tags:
+        - authKit
+      summary: Verify an MFA challenge code and finalize the login (public).
+      operationId: authKit_mfaChallengeVerify
+      security: []
+      parameters:
+        - name: clientId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MfaFinalizeResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+  /authkit/{clientId}/mfa/factors:
+    get:
+      tags:
+        - authKit
+      summary: List enrolled factors and recovery-code count for the current user (authenticated).
+      operationId: authKit_getMfaFactors
+      security: []
+      parameters:
+        - name: clientId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MfaFactorsResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+  /authkit/{clientId}/mfa/factors/email/confirm:
+    post:
+      tags:
+        - authKit
+      summary: "Confirm email-factor enrollment with the code sent by {@link enrollEmailMfa} (authenticated)."
+      operationId: authKit_confirmEmailMfa
+      security: []
+      parameters:
+        - name: clientId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MfaEnrolledResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+  /authkit/{clientId}/mfa/factors/email/enroll:
+    post:
+      tags:
+        - authKit
+      summary: "Begin email-factor enrollment; sends a code to the account's existing email (authenticated)."
+      operationId: authKit_enrollEmailMfa
+      security: []
+      parameters:
+        - name: clientId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MfaEnrollSendResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+  /authkit/{clientId}/mfa/factors/sms/confirm:
+    post:
+      tags:
+        - authKit
+      summary: "Confirm SMS-factor enrollment with the code sent by {@link enrollSmsMfa} (authenticated)."
+      operationId: authKit_confirmSmsMfa
+      security: []
+      parameters:
+        - name: clientId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MfaEnrolledResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+  /authkit/{clientId}/mfa/factors/sms/enroll:
+    post:
+      tags:
+        - authKit
+      summary: Begin SMS-factor enrollment; sends a code to the given phone number (authenticated).
+      operationId: authKit_enrollSmsMfa
+      security: []
+      parameters:
+        - name: clientId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MfaEnrollSendResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+  /authkit/{clientId}/mfa/factors/{factor}:
+    get:
+      tags:
+        - authKit
+      summary: Remove an enrolled MFA factor (authenticated).
+      operationId: authKit_removeMfaFactor
+      security: []
+      parameters:
+        - name: clientId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: factor
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SuccessResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+  /authkit/{clientId}/mfa/trusted-devices/{id}:
+    delete:
+      tags:
+        - authKit
+      summary: Revoke a single trusted device by id (authenticated).
+      operationId: authKit_revokeTrustedDevice
+      security: []
+      parameters:
+        - name: clientId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SuccessResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
   /platform/location:
     post:
       tags:
@@ -14979,6 +15258,8 @@ components:
           type: boolean
         location:
           $ref: "#/components/schemas/AnalyticsLocation"
+        source:
+          type: string
         metadata:
           type: object
           additionalProperties: true
@@ -15014,6 +15295,8 @@ components:
           $ref: "#/components/schemas/AnalyticsLocation"
         isAdmin:
           type: boolean
+        redirectMode:
+          type: string
         metadata:
           type: object
           additionalProperties: true
@@ -15222,6 +15505,16 @@ components:
           type: boolean
         hasLocation:
           type: boolean
+        sources:
+          type: array
+          items:
+            type: string
+        redirectMode:
+          type: string
+        redirectModes:
+          type: array
+          items:
+            type: string
     AnalyticsSummaryRequest:
       type: object
       properties:
@@ -15666,6 +15959,9 @@ components:
       properties:
         basePlanId:
           type: string
+        productMode:
+          type: object
+          additionalProperties: true
         addOnKeys:
           type: array
           items:
@@ -18413,6 +18709,124 @@ components:
         userInfo:
           type: object
           additionalProperties: true
+    MfaRequiredDetails:
+      type: object
+      properties:
+        mfaSessionToken:
+          type: string
+        availableFactors:
+          type: array
+          items:
+            type: string
+            enum:
+              - email
+              - sms
+        preferredFactor:
+          type: string
+          enum:
+            - email
+            - sms
+        maskedDestinations:
+          type: object
+          additionalProperties: true
+      required:
+        - mfaSessionToken
+        - availableFactors
+        - preferredFactor
+        - maskedDestinations
+    MfaChallengeSendResponse:
+      type: object
+      properties:
+        success:
+          type: object
+          additionalProperties: true
+        factor:
+          type: string
+          enum:
+            - email
+            - sms
+        destination:
+          type: string
+        expiresAt:
+          type: string
+      required:
+        - success
+        - factor
+        - destination
+        - expiresAt
+    MfaFinalizeResponse:
+      type: object
+      properties:
+        trustedDeviceToken:
+          type: string
+        trustedDeviceExpiresAt:
+          type: string
+    MfaEnrollSendResponse:
+      type: object
+      properties:
+        mfaSessionToken:
+          type: string
+        destination:
+          type: string
+        expiresAt:
+          type: string
+      required:
+        - mfaSessionToken
+        - destination
+        - expiresAt
+    MfaEnrolledResponse:
+      type: object
+      properties:
+        enrolled:
+          type: object
+          additionalProperties: true
+        factor:
+          type: string
+          enum:
+            - email
+            - sms
+      required:
+        - enrolled
+        - factor
+    MfaFactorsResponse:
+      type: object
+      properties:
+        enrolledFactors:
+          type: object
+          additionalProperties: true
+        email:
+          type: object
+          additionalProperties: true
+        sms:
+          type: object
+          additionalProperties: true
+        recoveryCodesRemaining:
+          type: number
+        mfaEnabledForClient:
+          type: boolean
+      required:
+        - enrolledFactors
+        - recoveryCodesRemaining
+        - mfaEnabledForClient
+    TrustedDevice:
+      type: object
+      properties:
+        id:
+          type: string
+        label:
+          type: string
+        createdAtMs:
+          type: number
+        lastUsedAtMs:
+          type: number
+        expiresAtMs:
+          type: number
+      required:
+        - id
+        - label
+        - createdAtMs
+        - lastUsedAtMs
+        - expiresAtMs
     MagicLinkSendResponse:
       type: object
       properties:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "1.15.10",
+  "version": "1.15.13",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",