@proveanything/smartlinks 1.15.18 → 1.15.20

package/dist/docs/auth-kit.md

@@ -502,6 +502,113 @@ await authKit.completePasswordReset(clientId, tokenFromUrl, 'newSecurePassword')
 
 ---
 
+## Account security policy
+
+Each collection can configure account-security rules. **The API enforces all of it**; your
+login UI reads the policy for UX only (a live password checklist, idle sign-out). There are
+two sides: an **admin** writes the policy, and the **login UI** reads the public subset.
+
+**Read (login UI, public — no auth):**
+
+```ts
+const config = await authKit.load(clientId);
+const policy  = config.security?.passwordPolicy; // min length, char classes, block-common
+const session = config.security?.session;        // inactivity + absolute timeouts, rememberMe
+```
+
+`lockout` values are admin-only and never returned by `load`.
+
+**Write (admin):** set the whole `security` block with `authKit.update` (or `authKit.create`).
+The shape is {@link AuthKitSecurityConfig}; see {@link AuthKitConfigInput}.
+
+```ts
+await authKit.update(collectionId, clientId, {
+  security: {
+    passwordPolicy: {
+      minLength: 8,               // hard floor enforced server-side
+      blockCommonPasswords: true, // reject the common/breached list
+      requireUppercase: false, requireLowercase: false,
+      requireNumber: false, requireSymbol: false,
+      expiryDays: 0,              // 0 = never expires
+      historyCount: 0,            // 0 = reuse allowed
+    },
+    lockout: {                    // admin-only; enforced server-side
+      enabled: true, maxFailedAttempts: 5,
+      attemptWindowMinutes: 15, lockoutMinutes: 15,
+      notifyUserOnLockout: true,
+    },
+    session: {
+      inactivityTimeoutMinutes: 0, // 0 = disabled (client-enforced when set)
+      inactivityWarningSeconds: 60,
+      absoluteTimeoutHours: 0,     // 0 = use token lifetime (server-enforced)
+      rememberMe: true,
+    },
+  },
+});
+```
+
+Defaults if a collection has never set a policy: 8-char minimum + block-common for everyone,
+lockout disabled, no expiry/history, no idle/absolute timeout. Omit any field to take its default.
+
+### Password policy
+
+`register`, `completePasswordReset`, and `changePassword` validate the new password
+server-side and throw a `SmartlinksApiError` with a {@link PasswordPolicyErrorCode}:
+
+| `errorCode` (400) | Meaning |
+|---|---|
+| `PASSWORD_TOO_SHORT` | below `minLength` |
+| `PASSWORD_REQUIREMENTS_NOT_MET` | missing a required character class |
+| `PASSWORD_TOO_COMMON` | on the common/breached list |
+| `PASSWORD_RECENTLY_USED` | matched one of the last `historyCount` passwords |
+
+Render a live checklist from `policy` so users see the rules before submitting.
+
+### Lockout
+
+After too many failed logins the account is temporarily locked. `login` throws:
+
+```ts
+try {
+  await authKit.login(clientId, email, password);
+} catch (err) {
+  if (err.errorCode === 'ACCOUNT_TEMPORARILY_LOCKED') {
+    const mins = Math.ceil(err.details.retryAfterSeconds / 60);
+    show(`Too many attempts. Try again in ${mins} minute(s).`);
+  }
+}
+```
+
+Failed MFA challenges count toward the same lock. Locking responds identically for unknown
+accounts (no enumeration).
+
+### Password expiry
+
+If a password is older than `passwordPolicy.expiryDays`, a valid login is refused with
+**403 `PASSWORD_EXPIRED`** carrying a short-lived `resetToken` — send the user straight into
+the reset form to change it in place:
+
+```ts
+catch (err) {
+  if (err.errorCode === 'PASSWORD_EXPIRED') {
+    await authKit.completePasswordReset(clientId, err.details.resetToken, newPassword);
+  }
+}
+```
+
+### Session lifetime
+
+- **Absolute timeout** (`session.absoluteTimeoutHours`) is enforced server-side on the native
+  refresh path: once the session is too old, `refreshToken` throws **401 `SESSION_EXPIRED`**
+  (see {@link RefreshErrorCode}) — clear storage and route to login. Web sessions use the
+  stateless bearer token and rely on inactivity sign-out below.
+- **Inactivity timeout** (`session.inactivityTimeoutMinutes` / `inactivityWarningSeconds`) is
+  **client-enforced** — sign the user out after idle, warning first. Sync across tabs.
+- **`session.rememberMe: false`** → don't persist tokens to durable storage; treat the session
+  as browser-scoped.
+
+---
+
 ## Relationship to other parts of the SDK
 
 | Concern | Where it lives |

package/dist/docs/overview.md

@@ -81,6 +81,9 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **App Records Pattern** | `docs/app-records-pattern.md` | Standard pattern for per-product/facet/variant/batch admin + public widget UIs |
 | **UI Utils** | `docs/ui-utils.md` | `@proveanything/smartlinks-utils-ui` — React shells, hooks, and primitives for records-based apps |
 | **Product/Proof Data Scoping** | `docs/proof-product-data-scoping.md` | Canonical spec for `product.data`/`.admin` and `proof.data`/`.admin`/`.values` (owner/personal) — who can read and write each bucket |
+| **Proof Claiming** | `docs/proof-claiming-methods.md` | The ways a user claims a proof (serial, NFC, claim-set, auto-generate) |
+| **Proof Share Grants** | `docs/proof-share-grants.md` | Delegated, scoped, revocable bearer access to a single proof (read/comment/verify-owner) |
+| **Proof Ownership Transfer** | `docs/proof-ownership-transfer.md` | Moving a proof's single owner (directed transfer / open release), accept/cancel, and the state machine |
 | **appConfig / Feature Flags** | `docs/appConfig.md` | `appConfig` settings contract — installed apps, `system.features`/`entitledAppGroups`/`meters`, `isFeatureEnabled()` helper |
 
 ---

package/dist/docs/proof-ownership-transfer.md

@@ -0,0 +1,114 @@
+# Proof Ownership Transfer
+
+Every proof has exactly **one owner** (`proof.userId`). A *transfer* moves that
+owner from A to B — for a resale, a gift, or handing an item on. Ownership carries
+the owner-scoped data with it and voids the previous owner's private access.
+
+This covers **push (owner-initiated) transfers** — the current owner consents to the
+move. Contested pull-claims and dispute resolution (where a holder claims ownership
+the owner never released) are a later addition; the state machine below already
+reserves states for them.
+
+---
+
+## Two ways to push
+
+| Mode | How | Who completes it |
+|------|-----|------------------|
+| **Directed** | Owner names a recipient (`toEmail` / `toUserId`). The proof is earmarked for them (`claimUserId`) and they're emailed a link. | The named recipient calls `acceptTransfer`. |
+| **Open release** | Owner marks the proof `claimable`. | Anyone claims it via the normal claim flow. |
+
+Only the current owner (or a collection admin) can start a transfer. A proof can
+have **one active transfer at a time**.
+
+### What completion does
+
+When a directed transfer is accepted (or an admin resolves one), the move is
+authoritative and atomic:
+
+- `proof.userId` becomes the new owner; `claimable` is cleared.
+- The **previous owner's private zones are removed** — `values.owner`,
+  `values.personal[oldOwner]`, and their `roles` entry.
+- Every **share grant auto-voids** (grants are bound to the owner at issue), so
+  stale "I own this" links stop resolving.
+- An append-only **`ownership_transfer` attestation** records `from → to`, so the
+  chain of custody is verifiable.
+
+---
+
+## Owner flow
+
+```ts
+import { proof } from '@proveanything/smartlinks'
+
+// Directed — hand it to a named buyer (they must accept)
+const { transfer } = await proof.transfer(collectionId, productId, proofId, {
+  toEmail: 'buyer@example.com',
+  message: 'Enjoy the watch!',
+})
+
+// …or an open release — anyone can now claim it
+await proof.transfer(collectionId, productId, proofId, { release: true })
+
+// Check status at any time
+const { transfer: active } = await proof.getTransfer(collectionId, productId, proofId)
+
+// Change your mind before it's accepted
+await proof.cancelTransfer(collectionId, productId, proofId)
+```
+
+## Recipient flow (directed)
+
+```ts
+// Only the named recipient can accept — a third party is rejected.
+const { proof: mine } = await proof.acceptTransfer(collectionId, productId, proofId)
+```
+
+The recipient sees the pending transfer on their account (a pending claim) and via
+the email link. Until they accept, the proof still belongs to the seller.
+
+---
+
+## State machine
+
+```
+              transfer({toEmail})                accept
+ (owned) ────────────────────────▶ pending ─────────────▶ completed
+    │                                 │
+    │        transfer({release})      │  cancel
+    └────────────────────────────────▶├─────────────────▶ cancelled
+                                       │
+                                       │  (later: dispute / escalation)
+                                       └─────────▶ disputed / escalated / rejected
+```
+
+- `pending` — a transfer is in flight (directed earmark or open release).
+- `completed` — ownership moved.
+- `cancelled` — the owner withdrew it before acceptance.
+- `expired` / `disputed` / `escalated` / `rejected` — reserved for contested
+  claims + dispute resolution (later).
+
+---
+
+## Security notes
+
+- **Directed accept is access-controlled.** Only the earmarked recipient
+  (`transfer.toUserId`) can accept; the claim endpoint also rejects anyone whose
+  id ≠ `claimUserId` while a directed transfer is pending. A directed transfer
+  can't be grabbed by a bystander.
+- **Ownership only moves one way** — through completion. There is no path that
+  silently strips an active owner without their consent (contested claims, when
+  added, are dispute-protected and never auto-transfer by default).
+- **Every state change is audited** as an append-only attestation on the proof.
+
+## API
+
+| Method | Endpoint |
+|--------|----------|
+| `proof.transfer(c, p, id, opts)` | `POST …/proof/:id/transfer` |
+| `proof.acceptTransfer(c, p, id)` | `POST …/proof/:id/transfer/accept` |
+| `proof.cancelTransfer(c, p, id)` | `POST …/proof/:id/transfer/cancel` |
+| `proof.getTransfer(c, p, id)` | `GET …/proof/:id/transfer` |
+
+See also [Proof Share Grants](./proof-share-grants.md) and
+[Proof Claiming Methods](./proof-claiming-methods.md).

package/dist/index.d.ts

@@ -17,7 +17,7 @@ export type { AdditionalGtin, ISODateString, JsonPrimitive, JsonValue, ProductCr
 export type { TranslationLookupMode, TranslationContentType, TranslationQuality, TranslationItemStatus, TranslationContextValue, TranslationContext, TranslationLookupRequestBase, TranslationLookupSingleRequest, TranslationLookupBatchRequest, TranslationLookupRequest, TranslationLookupItem, TranslationLookupResponse, ResolvedTranslationItem, ResolvedTranslationResponse, TranslationHashOptions, TranslationResolveOptions, TranslationRecord, TranslationListParams, TranslationListResponse, TranslationUpdateRequest, } from "./types/translations";
 export type { FacetBucket, FacetDefinition, FacetDefinitionWriteInput, FacetGetParams, FacetListParams, FacetListResponse, FacetNamespaceListResponse, FacetQueryRequest, FacetQueryResponse, FacetValue, FacetValueDefinition, FacetValueGetParams, FacetValueListParams, FacetValueListResponse, FacetValueResponse, FacetValueWriteInput, PublicFacetListParams, } from "./types/facets";
 export type { Collection, CollectionResponse, CollectionCreateRequest, CollectionUpdateRequest, DomainTarget, HubAvailabilityResponse, } from "./types/collection";
-export type { Proof, ProofResponse, ProofCreateRequest, ProofUpdateRequest, ProofClaimRequest, ProofGrant, GrantScope, GrantAudience, CreateGrantOptions, RedeemGrantOptions, RedeemGrantResult, } from "./types/proof";
+export type { Proof, ProofResponse, ProofWrite, ProofCreateRequest, ProofUpdateRequest, ProofClaimRequest, ProofGrant, GrantScope, GrantAudience, CreateGrantOptions, RedeemGrantOptions, RedeemGrantResult, ProofTransfer, ProofTransferType, ProofTransferState, TransferProofOptions, TransferProofResult, } from "./types/proof";
 export type { QrShortCodeLookupResponse, } from "./types/qr";
 export type { ReverseTagLookupParams, ReverseTagLookupResponse, } from "./types/tags";
 export type { AdminMobileCapability, ActionableCapability, AdminMobileHostId, AdminMobileEvent, AdminMobileEventCallback, AdminMobileEventSubscriber, ScannerEventSubscriber, // @deprecated — use AdminMobileEventCallback
@@ -25,4 +25,4 @@ AdminMobileHostContext, AdminMobileComponentManifest, AdminMobileBundleManifest,
 MobileAdminBundleManifest, } from './mobile-admin/types';
 export { HostCapabilityUnavailableError, HostPermissionDeniedError, HostTimeoutError, } from './mobile-admin/errors';
 export type { NativeCapability, NativeFacade, ShareFacade, ClipboardFacade, HapticImpactStyle, HapticNotificationStyle, HapticsFacade, NetworkStatus, NetworkFacade, DeviceInfo, DeviceFacade, StorageFacade, QrScanOptions, QrFacade, AuthFacade, NfcReadResult, NfcFacade, RfidScanOptions, RfidFacade, EventsFacade, WebSourceMode, WebSourceConfig, WebSourceFacade, } from './native/types';
-export type { AuthKitUser, UserProfile, ProfileUpdateData, UpdateProfileResponse, SuccessResponse, AuthLoginResponse, AppleLoginOptions, AuthKitErrorCode, RefreshResponse, LogoutResponse, RefreshErrorCode, MagicLinkSendResponse, MagicLinkVerifyResponse, PhoneSendCodeResponse, PhoneVerifyResponse, PasswordResetRequestResponse, VerifyResetTokenResponse, PasswordResetCompleteResponse, EmailVerificationActionResponse, EmailVerifyTokenResponse, VerifyStatus, WhatsAppReplyCta, WhatsAppReplyOptions, WhatsAppContactData, SendWhatsAppRequest, SendWhatsAppResponse, ExchangeWhatsAppSessionResponse, VerifyWhatsAppResponse, WhatsAppStatusResponse, SendSmsVerifyRequest, SendSmsVerifyResponse, VerifySmsResponse, UpsertContactRequest, UpsertContactResponse, AuthKitBrandingConfig, AuthKitConfig, } from './types/authKit';
+export type { AuthKitUser, UserProfile, ProfileUpdateData, UpdateProfileResponse, SuccessResponse, AuthLoginResponse, AppleLoginOptions, AuthKitErrorCode, RefreshResponse, LogoutResponse, RefreshErrorCode, MagicLinkSendResponse, MagicLinkVerifyResponse, PhoneSendCodeResponse, PhoneVerifyResponse, PasswordResetRequestResponse, VerifyResetTokenResponse, PasswordResetCompleteResponse, EmailVerificationActionResponse, EmailVerifyTokenResponse, VerifyStatus, WhatsAppReplyCta, WhatsAppReplyOptions, WhatsAppContactData, SendWhatsAppRequest, SendWhatsAppResponse, ExchangeWhatsAppSessionResponse, VerifyWhatsAppResponse, WhatsAppStatusResponse, SendSmsVerifyRequest, SendSmsVerifyResponse, VerifySmsResponse, UpsertContactRequest, UpsertContactResponse, AuthKitBrandingConfig, AuthKitConfig, AuthKitConfigInput, AuthKitSecurityConfig, AuthKitPasswordPolicy, AuthKitSessionPolicy, AuthKitLockoutPolicy, PasswordPolicyErrorCode, LoginSecurityErrorCode, } from './types/authKit';

package/dist/openapi.yaml

@@ -1579,7 +1579,7 @@ paths:
     post:
       tags:
         - authKit
-      summary: authKit.create
+      summary: Create an AuthKit client config (admin).
       operationId: authKit_create
       security:
         - bearerAuth: []
@@ -1602,11 +1602,17 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AuthKitConfigInput"
   /admin/collection/{collectionId}/authKit/{authKitId}:
     get:
       tags:
         - authKit
-      summary: authKit.get
+      summary: "Get the full AuthKit config, including admin-only fields like `security.lockout` (admin auth)."
       operationId: authKit_get
       security:
         - bearerAuth: []
@@ -1637,7 +1643,7 @@ paths:
     put:
       tags:
         - authKit
-      summary: authKit.update
+      summary: Update an AuthKit client config (admin).
       operationId: authKit_update
       security:
         - bearerAuth: []
@@ -1665,6 +1671,12 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AuthKitConfigInput"
     delete:
       tags:
         - authKit
@@ -8077,7 +8089,7 @@ paths:
     get:
       tags:
         - authKit
-      summary: Revoke a single trusted device by id (authenticated).
+      summary: "Load the **public** AuthKit config for a client (no auth)."
       operationId: authKit_load
       security: []
       parameters:
@@ -8401,7 +8413,7 @@ paths:
     post:
       tags:
         - authKit
-      summary: Login with email + password (public).
+      summary: authKit.login
       operationId: authKit_login
       security: []
       parameters:
@@ -19381,8 +19393,74 @@ components:
           type: string
         updatedAt:
           type: string
+        security:
+          $ref: "#/components/schemas/AuthKitSecurityConfig"
       required:
         - id
+    AuthKitSecurityConfig:
+      type: object
+      properties:
+        passwordPolicy:
+          $ref: "#/components/schemas/AuthKitPasswordPolicy"
+        session:
+          $ref: "#/components/schemas/AuthKitSessionPolicy"
+        lockout:
+          $ref: "#/components/schemas/AuthKitLockoutPolicy"
+    AuthKitPasswordPolicy:
+      type: object
+      properties:
+        minLength:
+          type: number
+        requireUppercase:
+          type: boolean
+        requireLowercase:
+          type: boolean
+        requireNumber:
+          type: boolean
+        requireSymbol:
+          type: boolean
+        blockCommonPasswords:
+          type: boolean
+        expiryDays:
+          type: number
+        historyCount:
+          type: number
+    AuthKitSessionPolicy:
+      type: object
+      properties:
+        inactivityTimeoutMinutes:
+          type: number
+        inactivityWarningSeconds:
+          type: number
+        absoluteTimeoutHours:
+          type: number
+        rememberMe:
+          type: boolean
+    AuthKitLockoutPolicy:
+      type: object
+      properties:
+        enabled:
+          type: boolean
+        maxFailedAttempts:
+          type: number
+        attemptWindowMinutes:
+          type: number
+        lockoutMinutes:
+          type: number
+        notifyUserOnLockout:
+          type: boolean
+    AuthKitConfigInput:
+      type: string
+      enum:
+        - id
+        - updatedAt
+    PasswordPolicyErrorCode:
+      type: string
+      enum:
+        - PASSWORD_TOO_SHORT
+        - PASSWORD_REQUIREMENTS_NOT_MET
+        - PASSWORD_TOO_COMMON
+        - PASSWORD_RECENTLY_USED
     FirebaseTimestamp:
       type: object
       properties:
@@ -24994,9 +25072,11 @@ components:
         - tokenId
         - userId
         - values
-    ProofCreateRequest:
+    ProofWrite:
       type: object
       properties:
+        id:
+          type: string
         values:
           $ref: "#/components/schemas/ProofValues"
         data:
@@ -25007,12 +25087,33 @@ components:
           type: object
           additionalProperties:
             $ref: "#/components/schemas/JsonValue"
+        owner:
+          type: object
+          additionalProperties:
+            $ref: "#/components/schemas/JsonValue"
+        claimable:
+          type: boolean
+    ProofCreateRequest:
+      type: object
+      properties:
+        proof:
+          $ref: "#/components/schemas/ProofWrite"
+        values:
+          $ref: "#/components/schemas/ProofValues"
         claimable:
           type: boolean
         virtual:
           type: boolean
-      required:
-        - values
+        core:
+          $ref: "#/components/schemas/ProofWrite"
+        data:
+          type: object
+          additionalProperties:
+            $ref: "#/components/schemas/JsonValue"
+        admin:
+          type: object
+          additionalProperties:
+            $ref: "#/components/schemas/JsonValue"
     ProofFieldsConfig:
       type: object
       properties:
@@ -25096,9 +25197,87 @@ components:
       properties:
         guestName:
           type: string
-    ProofResponse:
+    ProofTransfer:
       type: object
-      additionalProperties: true
+      properties:
+        id:
+          type: string
+        proofId:
+          type: string
+        productId:
+          type: string
+        type:
+          $ref: "#/components/schemas/ProofTransferType"
+        state:
+          $ref: "#/components/schemas/ProofTransferState"
+        fromUserId:
+          type: string
+        toUserId:
+          type: string
+        toEmail:
+          type: string
+        initiatedByUserId:
+          type: string
+        initiatedByRole:
+          type: string
+          enum:
+            - owner
+            - claimant
+            - admin
+        disputeReason:
+          type: string
+        disputeDeadline:
+          type: string
+        completedAt:
+          type: string
+        createdAt:
+          type: string
+        updatedAt:
+          type: string
+      required:
+        - id
+        - proofId
+        - type
+        - state
+        - createdAt
+        - updatedAt
+    TransferProofOptions:
+      type: object
+      properties:
+        toEmail:
+          type: string
+        toUserId:
+          type: string
+        toName:
+          type: string
+        release:
+          type: boolean
+        message:
+          type: string
+        notify:
+          type: boolean
+    TransferProofResult:
+      type: object
+      properties:
+        ok:
+          type: boolean
+        mode:
+          type: string
+          enum:
+            - directed
+            - open_release
+        transfer:
+          $ref: "#/components/schemas/ProofTransfer"
+      required:
+        - ok
+        - mode
+        - transfer
+    ProofTransferType:
+      type: string
+      enum:
+        - directed
+        - open_release
+        - contested
     QrShortCodeLookupResponse:
       type: object
       properties:

package/dist/types/authKit.d.ts

@@ -89,8 +89,11 @@ export interface LogoutResponse {
  * - `INVALID_REFRESH_TOKEN` (401) — unknown / expired / revoked / wrong client → `logout()` + route to login.
  * - `REFRESH_TOKEN_REUSE_DETECTED` (401) — a consumed token was replayed; the **entire session
  *   family was revoked server-side**. Hard logout: clear storage, force re-login.
+ * - `SESSION_EXPIRED` (401) — the session hit the collection's absolute session timeout
+ *   (`security.session.absoluteTimeoutHours`). Clear storage and route to login. Distinct from
+ *   `INVALID_REFRESH_TOKEN` so the UI can message "your session expired" rather than an error.
  */
-export type RefreshErrorCode = 'MISSING_REFRESH_TOKEN' | 'INVALID_REFRESH_TOKEN' | 'REFRESH_TOKEN_REUSE_DETECTED';
+export type RefreshErrorCode = 'MISSING_REFRESH_TOKEN' | 'INVALID_REFRESH_TOKEN' | 'REFRESH_TOKEN_REUSE_DETECTED' | 'SESSION_EXPIRED';
 /**
  * Options for {@link authKit.appleLogin}. All fields are optional — only the
  * `identityToken` (passed as a positional argument) is required by the server.
@@ -397,4 +400,84 @@ export interface AuthKitConfig {
     supportEmail?: string;
     redirectUrl?: string;
     updatedAt?: string;
+    /**
+     * Per-collection security policy. On the public config endpoint only
+     * `passwordPolicy` + `session` are returned (the client renders password
+     * checklists / idle sign-out from them); `lockout` is admin-only and enforced
+     * server-side. See {@link AuthKitSecurityConfig}.
+     */
+    security?: AuthKitSecurityConfig;
+}
+/**
+ * Writable shape for `authKit.create` / `authKit.update` (admin). Known fields are
+ * typed — importantly `security?: AuthKitSecurityConfig` for the account security
+ * policy — while additional admin-console fields are still permitted. `id` and
+ * `updatedAt` are server-owned and omitted.
+ *
+ * ```ts
+ * await authKit.update(collectionId, authKitId, {
+ *   security: {
+ *     passwordPolicy: { minLength: 10, blockCommonPasswords: true },
+ *     lockout:  { enabled: true, maxFailedAttempts: 5, lockoutMinutes: 15 },
+ *     session:  { inactivityTimeoutMinutes: 30, absoluteTimeoutHours: 12 },
+ *   },
+ * })
+ * ```
+ */
+export type AuthKitConfigInput = Partial<Omit<AuthKitConfig, 'id' | 'updatedAt'>> & Record<string, any>;
+/**
+ * Per-collection account-security policy. The API **enforces** all of this; the
+ * client uses `passwordPolicy` (live checklist) and `session` (idle sign-out) for UX.
+ */
+export interface AuthKitSecurityConfig {
+    passwordPolicy?: AuthKitPasswordPolicy;
+    session?: AuthKitSessionPolicy;
+    /** Admin-only; never returned on the public config endpoint. */
+    lockout?: AuthKitLockoutPolicy;
+}
+export interface AuthKitPasswordPolicy {
+    minLength?: number;
+    requireUppercase?: boolean;
+    requireLowercase?: boolean;
+    requireNumber?: boolean;
+    requireSymbol?: boolean;
+    blockCommonPasswords?: boolean;
+    /** 0 = never expires. */
+    expiryDays?: number;
+    /** 0 = reuse allowed. */
+    historyCount?: number;
+}
+export interface AuthKitSessionPolicy {
+    /** 0 = never (client-enforced idle sign-out). */
+    inactivityTimeoutMinutes?: number;
+    inactivityWarningSeconds?: number;
+    /** 0 = use token lifetime. Enforced server-side on the native refresh path (→ `SESSION_EXPIRED`). */
+    absoluteTimeoutHours?: number;
+    rememberMe?: boolean;
+}
+/** Admin-only lockout policy (operational; not exposed publicly). */
+export interface AuthKitLockoutPolicy {
+    enabled?: boolean;
+    maxFailedAttempts?: number;
+    attemptWindowMinutes?: number;
+    lockoutMinutes?: number;
+    notifyUserOnLockout?: boolean;
 }
+/**
+ * Password-policy validation errors (400) returned by `register`, `completePasswordReset`,
+ * and `changePassword`. Surfaced via `SmartlinksApiError.errorCode`.
+ * - `PASSWORD_TOO_SHORT` — below `passwordPolicy.minLength`.
+ * - `PASSWORD_REQUIREMENTS_NOT_MET` — missing a required character class.
+ * - `PASSWORD_TOO_COMMON` — matched the common/breached list.
+ * - `PASSWORD_RECENTLY_USED` — matched one of the last `historyCount` passwords.
+ */
+export type PasswordPolicyErrorCode = 'PASSWORD_TOO_SHORT' | 'PASSWORD_REQUIREMENTS_NOT_MET' | 'PASSWORD_TOO_COMMON' | 'PASSWORD_RECENTLY_USED';
+/**
+ * Security errors returned by `login`. Surfaced via `SmartlinksApiError.errorCode`,
+ * with extra fields in `SmartlinksApiError.details`:
+ * - `ACCOUNT_TEMPORARILY_LOCKED` (429) — too many failed attempts; `details.retryAfterSeconds`
+ *   says how long to wait. Show a "try again in N minutes" message.
+ * - `PASSWORD_EXPIRED` (403) — password older than `passwordPolicy.expiryDays`; `details.resetToken`
+ *   is a short-lived token — send the user straight into `completePasswordReset()` to change it in place.
+ */
+export type LoginSecurityErrorCode = 'ACCOUNT_TEMPORARILY_LOCKED' | 'PASSWORD_EXPIRED';