@proveanything/smartlinks 1.15.19 → 1.15.21

package/dist/api/authKit.d.ts

@@ -1,4 +1,4 @@
-import type { AuthLoginResponse, AppleLoginOptions, RefreshResponse, LogoutResponse, PhoneSendCodeResponse, PhoneVerifyResponse, PasswordResetRequestResponse, VerifyResetTokenResponse, PasswordResetCompleteResponse, EmailVerificationActionResponse, EmailVerifyTokenResponse, AuthKitConfig, MagicLinkSendResponse, MagicLinkVerifyResponse, UserProfile, UpdateProfileResponse, ProfileUpdateData, SuccessResponse, SendWhatsAppRequest, SendWhatsAppResponse, ExchangeWhatsAppSessionResponse, VerifyWhatsAppResponse, WhatsAppStatusResponse, SendSmsVerifyRequest, SendSmsVerifyResponse, VerifySmsResponse, UpsertContactRequest, UpsertContactResponse, MfaChallengeSendResponse, MfaFinalizeResponse, MfaEnrollSendResponse, MfaEnrolledResponse, MfaFactorsResponse, TrustedDevice } from "../types/authKit";
+import type { AuthLoginResponse, AppleLoginOptions, RefreshResponse, LogoutResponse, PhoneSendCodeResponse, PhoneVerifyResponse, PasswordResetRequestResponse, VerifyResetTokenResponse, PasswordResetCompleteResponse, EmailVerificationActionResponse, EmailVerifyTokenResponse, AuthKitConfig, AuthKitConfigInput, MagicLinkSendResponse, MagicLinkVerifyResponse, UserProfile, UpdateProfileResponse, ProfileUpdateData, SuccessResponse, SendWhatsAppRequest, SendWhatsAppResponse, ExchangeWhatsAppSessionResponse, VerifyWhatsAppResponse, WhatsAppStatusResponse, SendSmsVerifyRequest, SendSmsVerifyResponse, VerifySmsResponse, UpsertContactRequest, UpsertContactResponse, MfaChallengeSendResponse, MfaFinalizeResponse, MfaEnrollSendResponse, MfaEnrolledResponse, MfaFactorsResponse, TrustedDevice } from "../types/authKit";
 /**
  * Namespace containing helper functions for the new AuthKit API.
  * Legacy collection-based authKit helpers retained (marked as *Legacy*).
@@ -231,10 +231,24 @@ export declare namespace authKit {
     }>;
     /** Revoke a single trusted device by id (authenticated). */
     function revokeTrustedDevice(clientId: string, id: string): Promise<SuccessResponse>;
+    /**
+     * Load the **public** AuthKit config for a client (no auth). Returns branding +
+     * the public security subset (`security.passwordPolicy` + `security.session`);
+     * `security.lockout` is admin-only and never included here. Use this in the login
+     * UI to render password checklists and drive idle sign-out.
+     */
     function load(authKitId: string): Promise<AuthKitConfig>;
+    /** Get the full AuthKit config, including admin-only fields like `security.lockout` (admin auth). */
     function get(collectionId: string, authKitId: string): Promise<AuthKitConfig>;
     function list(collectionId: string, admin?: boolean): Promise<AuthKitConfig[]>;
-    function create(collectionId: string, data: any): Promise<AuthKitConfig>;
-    function update(collectionId: string, authKitId: string, data: any): Promise<AuthKitConfig>;
+    /** Create an AuthKit client config (admin). Accepts the account `security` policy — see {@link AuthKitConfigInput}. */
+    function create(collectionId: string, data: AuthKitConfigInput): Promise<AuthKitConfig>;
+    /**
+     * Update an AuthKit client config (admin). This is how the account **security
+     * policy** is written — pass a `security` block ({@link AuthKitSecurityConfig}).
+     * The server validates it and enforces it; the login UI reads the public subset
+     * back via {@link load}.
+     */
+    function update(collectionId: string, authKitId: string, data: AuthKitConfigInput): Promise<AuthKitConfig>;
     function remove(collectionId: string, authKitId: string): Promise<void>;
 }

package/dist/api/authKit.js

@@ -444,11 +444,18 @@ export var authKit;
     /* ===================================
      * Collection-based AuthKit
      * =================================== */
+    /**
+     * Load the **public** AuthKit config for a client (no auth). Returns branding +
+     * the public security subset (`security.passwordPolicy` + `security.session`);
+     * `security.lockout` is admin-only and never included here. Use this in the login
+     * UI to render password checklists and drive idle sign-out.
+     */
     async function load(authKitId) {
         const path = `/authKit/${encodeURIComponent(authKitId)}/config`;
         return request(path);
     }
     authKit.load = load;
+    /** Get the full AuthKit config, including admin-only fields like `security.lockout` (admin auth). */
     async function get(collectionId, authKitId) {
         const path = `/admin/collection/${encodeURIComponent(collectionId)}/authKit/${encodeURIComponent(authKitId)}`;
         return request(path);
@@ -460,11 +467,18 @@ export var authKit;
         return request(path);
     }
     authKit.list = list;
+    /** Create an AuthKit client config (admin). Accepts the account `security` policy — see {@link AuthKitConfigInput}. */
     async function create(collectionId, data) {
         const path = `/admin/collection/${encodeURIComponent(collectionId)}/authKit`;
         return post(path, data);
     }
     authKit.create = create;
+    /**
+     * Update an AuthKit client config (admin). This is how the account **security
+     * policy** is written — pass a `security` block ({@link AuthKitSecurityConfig}).
+     * The server validates it and enforces it; the login UI reads the public subset
+     * back via {@link load}.
+     */
     async function update(collectionId, authKitId, data) {
         const path = `/admin/collection/${encodeURIComponent(collectionId)}/authKit/${encodeURIComponent(authKitId)}`;
         return put(path, data);

package/dist/api/proof.d.ts

@@ -1,4 +1,4 @@
-import { ProofResponse, ProofCreateRequest, ProofUpdateRequest, ProofClaimRequest, ProofGrant, CreateGrantOptions, RedeemGrantOptions, RedeemGrantResult } from "../types/proof";
+import { ProofResponse, ProofCreateRequest, ProofUpdateRequest, ProofClaimRequest, ProofGrant, CreateGrantOptions, RedeemGrantOptions, RedeemGrantResult, ProofTransfer, TransferProofOptions, TransferProofResult } from "../types/proof";
 export declare namespace proof {
     /**
      * Retrieves a single Proof by Collection ID, Product ID, and Proof ID.
@@ -145,4 +145,37 @@ export declare namespace proof {
      * {@link setGrantToken} so subsequent data requests carry the token.
      */
     function redeemGrant(collectionId: string, productId: string, proofId: string, token: string, options?: RedeemGrantOptions): Promise<RedeemGrantResult>;
+    /**
+     * Start a push transfer of a proof (current owner / collection admin only).
+     *
+     * Directed — hand it to a named recipient who then calls {@link acceptTransfer}:
+     * ```ts
+     * await proof.transfer(collectionId, productId, proofId, { toEmail: 'buyer@example.com' })
+     * ```
+     * Open release — make the proof claimable by anyone:
+     * ```ts
+     * await proof.transfer(collectionId, productId, proofId, { release: true })
+     * ```
+     */
+    function transfer(collectionId: string, productId: string, proofId: string, options: TransferProofOptions): Promise<TransferProofResult>;
+    /**
+     * Accept a directed transfer (the named recipient only). Completes the ownership
+     * move — the proof's `userId` becomes the caller and the previous owner's private
+     * data and share grants are cleared/voided.
+     */
+    function acceptTransfer(collectionId: string, productId: string, proofId: string): Promise<{
+        ok: boolean;
+        proof: ProofResponse;
+    }>;
+    /** Cancel a pending push transfer (current owner / collection admin only). */
+    function cancelTransfer(collectionId: string, productId: string, proofId: string): Promise<{
+        ok: boolean;
+    }>;
+    /**
+     * Get the active transfer/status for a proof (owner, collection admin, or the
+     * named recipient). Returns `{ transfer: null }` when nothing is in flight.
+     */
+    function getTransfer(collectionId: string, productId: string, proofId: string): Promise<{
+        transfer: ProofTransfer | null;
+    }>;
 }

package/dist/api/proof.js

@@ -223,4 +223,53 @@ export var proof;
         return post(`${grantBase(collectionId, productId, proofId)}/redeem`, body);
     }
     proof.redeemGrant = redeemGrant;
+    // ---------------------------------------------------------------------------
+    // Ownership transfer — moving a proof's single owner from A to B
+    //
+    // A proof always has exactly one owner (`proof.userId`). A transfer moves that
+    // owner with the current owner's consent: either DIRECTED to a named recipient
+    // (who accepts) or an OPEN RELEASE (the proof becomes claimable by anyone).
+    // Contested pull-claims + dispute resolution are a later addition.
+    // ---------------------------------------------------------------------------
+    function transferBase(collectionId, productId, proofId) {
+        return `/public/collection/${encodeURIComponent(collectionId)}/product/${encodeURIComponent(productId)}/proof/${encodeURIComponent(proofId)}/transfer`;
+    }
+    /**
+     * Start a push transfer of a proof (current owner / collection admin only).
+     *
+     * Directed — hand it to a named recipient who then calls {@link acceptTransfer}:
+     * ```ts
+     * await proof.transfer(collectionId, productId, proofId, { toEmail: 'buyer@example.com' })
+     * ```
+     * Open release — make the proof claimable by anyone:
+     * ```ts
+     * await proof.transfer(collectionId, productId, proofId, { release: true })
+     * ```
+     */
+    async function transfer(collectionId, productId, proofId, options) {
+        return post(transferBase(collectionId, productId, proofId), Object.assign({}, options));
+    }
+    proof.transfer = transfer;
+    /**
+     * Accept a directed transfer (the named recipient only). Completes the ownership
+     * move — the proof's `userId` becomes the caller and the previous owner's private
+     * data and share grants are cleared/voided.
+     */
+    async function acceptTransfer(collectionId, productId, proofId) {
+        return post(`${transferBase(collectionId, productId, proofId)}/accept`, {});
+    }
+    proof.acceptTransfer = acceptTransfer;
+    /** Cancel a pending push transfer (current owner / collection admin only). */
+    async function cancelTransfer(collectionId, productId, proofId) {
+        return post(`${transferBase(collectionId, productId, proofId)}/cancel`, {});
+    }
+    proof.cancelTransfer = cancelTransfer;
+    /**
+     * Get the active transfer/status for a proof (owner, collection admin, or the
+     * named recipient). Returns `{ transfer: null }` when nothing is in flight.
+     */
+    async function getTransfer(collectionId, productId, proofId) {
+        return request(transferBase(collectionId, productId, proofId));
+    }
+    proof.getTransfer = getTransfer;
 })(proof || (proof = {}));

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.15.19  |  Generated: 2026-08-20T18:06:08.134Z
+Version: 1.15.21  |  Generated: 2026-08-25T08:34:52.897Z
 
 This is a concise summary of all available API functions and types.
 
@@ -33,6 +33,8 @@ For detailed guides on specific features:
 - **[Theme System](theme.system.md)** - Theme configuration and customization
 - **[Theme Defaults](theme-defaults.md)** - Default theme values and presets
 - **[Proof Claiming Methods](proof-claiming-methods.md)** - All methods for claiming/registering product ownership (NFC tags, serial numbers, auto-generated claims)
+- **[Proof Share Grants](proof-share-grants.md)** - Delegated, scoped, revocable bearer access to a single proof (read/comment/verify-owner links)
+- **[Proof Ownership Transfer](proof-ownership-transfer.md)** - Moving a proof to a new owner: directed transfer, open release, accept/cancel, and the state machine
 - **[Product Facets SDK](PRODUCT_FACETS_SDK.md)** - Admin and public product facet endpoints and TypeScript interfaces
 - **[Attestations](attestations.md)** - Append-only fact log with cryptographic chain integrity, time-series analytics, and public/owner/admin visibility
 - **[Auth Kit](auth-kit.md)** - End-user authentication flows (email/password, magic link, OTP, OAuth) for microapps
@@ -3524,6 +3526,8 @@ interface AuthKitLockoutPolicy {
 
 **VerifyStatus** = `'pending' | 'verified' | 'failed' | 'expired' | 'unknown'`
 
+**AuthKitConfigInput** = ``
+
 **PasswordPolicyErrorCode** = ``
 
 **LoginSecurityErrorCode** = ``
@@ -7416,6 +7420,48 @@ interface RedeemGrantOptions {
 }
 ```
 
+**ProofTransfer** (interface)
+```typescript
+interface ProofTransfer {
+  id: string
+  proofId: string
+  productId?: string | null
+  type: ProofTransferType
+  state: ProofTransferState
+  fromUserId?: string | null
+  toUserId?: string | null
+  toEmail?: string | null
+  initiatedByUserId?: string | null
+  initiatedByRole?: 'owner' | 'claimant' | 'admin' | null
+  disputeReason?: string | null
+  disputeDeadline?: string | null
+  completedAt?: string | null
+  createdAt: string
+  updatedAt: string
+}
+```
+
+**TransferProofOptions** (interface)
+```typescript
+interface TransferProofOptions {
+  toEmail?: string
+  toUserId?: string
+  toName?: string
+  release?: boolean
+  message?: string
+  notify?: boolean
+}
+```
+
+**TransferProofResult** (interface)
+```typescript
+interface TransferProofResult {
+  ok: boolean
+  mode: 'directed' | 'open_release'
+  transfer: ProofTransfer
+}
+```
+
 **ProofResponse** = `Proof`
 
 **ProofUpdateRequest** = `Partial<ProofWrite> & { proof?: ProofWrite }`
@@ -7430,6 +7476,10 @@ interface RedeemGrantOptions {
 
 **RedeemGrantResult** = ``
 
+**ProofTransferType** = `'directed' | 'open_release' | 'contested'`
+
+**ProofTransferState** = ``
+
 ### qr
 
 **QrShortCodeLookupResponse** (interface)
@@ -8952,22 +9002,22 @@ List devices trusted to skip MFA challenges for the current user (authenticated)
 Revoke a single trusted device by id (authenticated).
 
 **load**(authKitId: string) → `Promise<AuthKitConfig>`
-Revoke a single trusted device by id (authenticated).
+Load the **public** AuthKit config for a client (no auth). Returns branding + the public security subset (`security.passwordPolicy` + `security.session`); `security.lockout` is admin-only and never included here. Use this in the login UI to render password checklists and drive idle sign-out.
 
 **get**(collectionId: string, authKitId: string) → `Promise<AuthKitConfig>`
-Revoke a single trusted device by id (authenticated).
+Get the full AuthKit config, including admin-only fields like `security.lockout` (admin auth).
 
 **list**(collectionId: string, admin?: boolean) → `Promise<AuthKitConfig[]>`
-Revoke a single trusted device by id (authenticated).
+Get the full AuthKit config, including admin-only fields like `security.lockout` (admin auth).
 
-**create**(collectionId: string, data: any) → `Promise<AuthKitConfig>`
-Revoke a single trusted device by id (authenticated).
+**create**(collectionId: string, data: AuthKitConfigInput) → `Promise<AuthKitConfig>`
+Create an AuthKit client config (admin). Accepts the account `security` policy — see {@link AuthKitConfigInput}.
 
-**update**(collectionId: string, authKitId: string, data: any) → `Promise<AuthKitConfig>`
-Revoke a single trusted device by id (authenticated).
+**update**(collectionId: string, authKitId: string, data: AuthKitConfigInput) → `Promise<AuthKitConfig>`
+Update an AuthKit client config (admin). This is how the account **security policy** is written — pass a `security` block ({@link AuthKitSecurityConfig}). The server validates it and enforces it; the login UI reads the public subset back via {@link load}.
 
 **remove**(collectionId: string, authKitId: string) → `Promise<void>`
-Revoke a single trusted device by id (authenticated).
+Update an AuthKit client config (admin). This is how the account **security policy** is written — pass a `security` block ({@link AuthKitSecurityConfig}). The server validates it and enforces it; the login UI reads the public subset back via {@link load}.
 
 ### batch
 
@@ -10101,6 +10151,27 @@ Revoke a grant by id (owner / collection admin only). Takes effect immediately.
     options?: RedeemGrantOptions) → `Promise<RedeemGrantResult>`
 Redeem a grant token (anonymous or signed-in). Records the redemption and returns the granted scope, or — for a `verify_owner` grant — an ownership assertion (never the account). After redeeming, call {@link setGrantToken} so subsequent data requests carry the token.
 
+**transfer**(collectionId: string,
+    productId: string,
+    proofId: string,
+    options: TransferProofOptions) → `Promise<TransferProofResult>`
+Start a push transfer of a proof (current owner / collection admin only). Directed — hand it to a named recipient who then calls {@link acceptTransfer}: ```ts await proof.transfer(collectionId, productId, proofId, { toEmail: 'buyer@example.com' }) ``` Open release — make the proof claimable by anyone: ```ts await proof.transfer(collectionId, productId, proofId, { release: true }) ```
+
+**acceptTransfer**(collectionId: string,
+    productId: string,
+    proofId: string) → `Promise<`
+Accept a directed transfer (the named recipient only). Completes the ownership move — the proof's `userId` becomes the caller and the previous owner's private data and share grants are cleared/voided.
+
+**cancelTransfer**(collectionId: string,
+    productId: string,
+    proofId: string) → `Promise<`
+Cancel a pending push transfer (current owner / collection admin only).
+
+**getTransfer**(collectionId: string,
+    productId: string,
+    proofId: string) → `Promise<`
+Get the active transfer/status for a proof (owner, collection admin, or the named recipient). Returns `{ transfer: null }` when nothing is in flight.
+
 ### publicClient
 
 **chat**(collectionId: string,

package/dist/docs/auth-kit.md

@@ -504,9 +504,11 @@ await authKit.completePasswordReset(clientId, tokenFromUrl, 'newSecurePassword')
 
 ## Account security policy
 
-Each collection can configure account-security rules (via the admin console). **The API
-enforces all of it**; your login UI reads the policy for UX only (a live password checklist,
-idle sign-out). Read it from the config:
+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);
@@ -514,7 +516,39 @@ const policy  = config.security?.passwordPolicy; // min length, char classes, bl
 const session = config.security?.session;        // inactivity + absolute timeouts, rememberMe
 ```
 
-`lockout` values are admin-only and never returned here.
+`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
 

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, ProofWrite, 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, AuthKitSecurityConfig, AuthKitPasswordPolicy, AuthKitSessionPolicy, AuthKitLockoutPolicy, PasswordPolicyErrorCode, LoginSecurityErrorCode, } 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:
@@ -19437,6 +19449,11 @@ components:
           type: number
         notifyUserOnLockout:
           type: boolean
+    AuthKitConfigInput:
+      type: string
+      enum:
+        - id
+        - updatedAt
     PasswordPolicyErrorCode:
       type: string
       enum:
@@ -25180,6 +25197,87 @@ components:
       properties:
         guestName:
           type: string
+    ProofTransfer:
+      type: object
+      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

@@ -408,6 +408,23 @@ export interface AuthKitConfig {
      */
     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.

package/dist/types/proof.d.ts

@@ -175,3 +175,60 @@ export type RedeemGrantResult = {
     issuedAt?: string;
     expiresAt?: string;
 };
+/**
+ * How a transfer was initiated.
+ * - `directed`     — the owner pushed it to a named recipient, who must accept.
+ * - `open_release` — the owner released it; the proof is `claimable` by anyone.
+ * - `contested`    — a holder claimed ownership the owner did not release (Phase 2).
+ */
+export type ProofTransferType = 'directed' | 'open_release' | 'contested';
+/**
+ * Where a transfer is in its lifecycle. `pending` is in-flight; `completed`
+ * means ownership moved. `disputed`/`escalated` are Phase 2 (contested claims).
+ */
+export type ProofTransferState = 'pending' | 'completed' | 'cancelled' | 'expired' | 'disputed' | 'escalated' | 'rejected';
+/** An ownership-transfer record on a proof. */
+export interface ProofTransfer {
+    id: string;
+    proofId: string;
+    productId?: string | null;
+    type: ProofTransferType;
+    state: ProofTransferState;
+    /** Owner at the time the transfer was initiated. */
+    fromUserId?: string | null;
+    /** Intended recipient (directed) / claimant (contested). */
+    toUserId?: string | null;
+    toEmail?: string | null;
+    initiatedByUserId?: string | null;
+    initiatedByRole?: 'owner' | 'claimant' | 'admin' | null;
+    disputeReason?: string | null;
+    disputeDeadline?: string | null;
+    completedAt?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Start a push transfer. Provide **one** of:
+ * - `toEmail` / `toUserId` — a directed transfer to a named recipient (they accept).
+ * - `release: true`        — an open release (the proof becomes claimable by anyone).
+ */
+export interface TransferProofOptions {
+    /** Directed: recipient email (created/looked up if needed). */
+    toEmail?: string;
+    /** Directed: recipient user id, if already known. */
+    toUserId?: string;
+    /** Directed: display name for a newly-created recipient. */
+    toName?: string;
+    /** Open release: mark the proof claimable instead of directing it. */
+    release?: boolean;
+    /** Optional note included in the recipient email. */
+    message?: string;
+    /** Set `false` to skip the recipient notification email (directed only). */
+    notify?: boolean;
+}
+/** Result of initiating a push transfer. */
+export interface TransferProofResult {
+    ok: boolean;
+    mode: 'directed' | 'open_release';
+    transfer: ProofTransfer;
+}

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.15.19  |  Generated: 2026-08-20T18:06:08.134Z
+Version: 1.15.21  |  Generated: 2026-08-25T08:34:52.897Z
 
 This is a concise summary of all available API functions and types.
 
@@ -33,6 +33,8 @@ For detailed guides on specific features:
 - **[Theme System](theme.system.md)** - Theme configuration and customization
 - **[Theme Defaults](theme-defaults.md)** - Default theme values and presets
 - **[Proof Claiming Methods](proof-claiming-methods.md)** - All methods for claiming/registering product ownership (NFC tags, serial numbers, auto-generated claims)
+- **[Proof Share Grants](proof-share-grants.md)** - Delegated, scoped, revocable bearer access to a single proof (read/comment/verify-owner links)
+- **[Proof Ownership Transfer](proof-ownership-transfer.md)** - Moving a proof to a new owner: directed transfer, open release, accept/cancel, and the state machine
 - **[Product Facets SDK](PRODUCT_FACETS_SDK.md)** - Admin and public product facet endpoints and TypeScript interfaces
 - **[Attestations](attestations.md)** - Append-only fact log with cryptographic chain integrity, time-series analytics, and public/owner/admin visibility
 - **[Auth Kit](auth-kit.md)** - End-user authentication flows (email/password, magic link, OTP, OAuth) for microapps
@@ -3524,6 +3526,8 @@ interface AuthKitLockoutPolicy {
 
 **VerifyStatus** = `'pending' | 'verified' | 'failed' | 'expired' | 'unknown'`
 
+**AuthKitConfigInput** = ``
+
 **PasswordPolicyErrorCode** = ``
 
 **LoginSecurityErrorCode** = ``
@@ -7416,6 +7420,48 @@ interface RedeemGrantOptions {
 }
 ```
 
+**ProofTransfer** (interface)
+```typescript
+interface ProofTransfer {
+  id: string
+  proofId: string
+  productId?: string | null
+  type: ProofTransferType
+  state: ProofTransferState
+  fromUserId?: string | null
+  toUserId?: string | null
+  toEmail?: string | null
+  initiatedByUserId?: string | null
+  initiatedByRole?: 'owner' | 'claimant' | 'admin' | null
+  disputeReason?: string | null
+  disputeDeadline?: string | null
+  completedAt?: string | null
+  createdAt: string
+  updatedAt: string
+}
+```
+
+**TransferProofOptions** (interface)
+```typescript
+interface TransferProofOptions {
+  toEmail?: string
+  toUserId?: string
+  toName?: string
+  release?: boolean
+  message?: string
+  notify?: boolean
+}
+```
+
+**TransferProofResult** (interface)
+```typescript
+interface TransferProofResult {
+  ok: boolean
+  mode: 'directed' | 'open_release'
+  transfer: ProofTransfer
+}
+```
+
 **ProofResponse** = `Proof`
 
 **ProofUpdateRequest** = `Partial<ProofWrite> & { proof?: ProofWrite }`
@@ -7430,6 +7476,10 @@ interface RedeemGrantOptions {
 
 **RedeemGrantResult** = ``
 
+**ProofTransferType** = `'directed' | 'open_release' | 'contested'`
+
+**ProofTransferState** = ``
+
 ### qr
 
 **QrShortCodeLookupResponse** (interface)
@@ -8952,22 +9002,22 @@ List devices trusted to skip MFA challenges for the current user (authenticated)
 Revoke a single trusted device by id (authenticated).
 
 **load**(authKitId: string) → `Promise<AuthKitConfig>`
-Revoke a single trusted device by id (authenticated).
+Load the **public** AuthKit config for a client (no auth). Returns branding + the public security subset (`security.passwordPolicy` + `security.session`); `security.lockout` is admin-only and never included here. Use this in the login UI to render password checklists and drive idle sign-out.
 
 **get**(collectionId: string, authKitId: string) → `Promise<AuthKitConfig>`
-Revoke a single trusted device by id (authenticated).
+Get the full AuthKit config, including admin-only fields like `security.lockout` (admin auth).
 
 **list**(collectionId: string, admin?: boolean) → `Promise<AuthKitConfig[]>`
-Revoke a single trusted device by id (authenticated).
+Get the full AuthKit config, including admin-only fields like `security.lockout` (admin auth).
 
-**create**(collectionId: string, data: any) → `Promise<AuthKitConfig>`
-Revoke a single trusted device by id (authenticated).
+**create**(collectionId: string, data: AuthKitConfigInput) → `Promise<AuthKitConfig>`
+Create an AuthKit client config (admin). Accepts the account `security` policy — see {@link AuthKitConfigInput}.
 
-**update**(collectionId: string, authKitId: string, data: any) → `Promise<AuthKitConfig>`
-Revoke a single trusted device by id (authenticated).
+**update**(collectionId: string, authKitId: string, data: AuthKitConfigInput) → `Promise<AuthKitConfig>`
+Update an AuthKit client config (admin). This is how the account **security policy** is written — pass a `security` block ({@link AuthKitSecurityConfig}). The server validates it and enforces it; the login UI reads the public subset back via {@link load}.
 
 **remove**(collectionId: string, authKitId: string) → `Promise<void>`
-Revoke a single trusted device by id (authenticated).
+Update an AuthKit client config (admin). This is how the account **security policy** is written — pass a `security` block ({@link AuthKitSecurityConfig}). The server validates it and enforces it; the login UI reads the public subset back via {@link load}.
 
 ### batch
 
@@ -10101,6 +10151,27 @@ Revoke a grant by id (owner / collection admin only). Takes effect immediately.
     options?: RedeemGrantOptions) → `Promise<RedeemGrantResult>`
 Redeem a grant token (anonymous or signed-in). Records the redemption and returns the granted scope, or — for a `verify_owner` grant — an ownership assertion (never the account). After redeeming, call {@link setGrantToken} so subsequent data requests carry the token.
 
+**transfer**(collectionId: string,
+    productId: string,
+    proofId: string,
+    options: TransferProofOptions) → `Promise<TransferProofResult>`
+Start a push transfer of a proof (current owner / collection admin only). Directed — hand it to a named recipient who then calls {@link acceptTransfer}: ```ts await proof.transfer(collectionId, productId, proofId, { toEmail: 'buyer@example.com' }) ``` Open release — make the proof claimable by anyone: ```ts await proof.transfer(collectionId, productId, proofId, { release: true }) ```
+
+**acceptTransfer**(collectionId: string,
+    productId: string,
+    proofId: string) → `Promise<`
+Accept a directed transfer (the named recipient only). Completes the ownership move — the proof's `userId` becomes the caller and the previous owner's private data and share grants are cleared/voided.
+
+**cancelTransfer**(collectionId: string,
+    productId: string,
+    proofId: string) → `Promise<`
+Cancel a pending push transfer (current owner / collection admin only).
+
+**getTransfer**(collectionId: string,
+    productId: string,
+    proofId: string) → `Promise<`
+Get the active transfer/status for a proof (owner, collection admin, or the named recipient). Returns `{ transfer: null }` when nothing is in flight.
+
 ### publicClient
 
 **chat**(collectionId: string,

package/docs/auth-kit.md

@@ -504,9 +504,11 @@ await authKit.completePasswordReset(clientId, tokenFromUrl, 'newSecurePassword')
 
 ## Account security policy
 
-Each collection can configure account-security rules (via the admin console). **The API
-enforces all of it**; your login UI reads the policy for UX only (a live password checklist,
-idle sign-out). Read it from the config:
+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);
@@ -514,7 +516,39 @@ const policy  = config.security?.passwordPolicy; // min length, char classes, bl
 const session = config.security?.session;        // inactivity + absolute timeouts, rememberMe
 ```
 
-`lockout` values are admin-only and never returned here.
+`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
 

package/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/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/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:
@@ -19437,6 +19449,11 @@ components:
           type: number
         notifyUserOnLockout:
           type: boolean
+    AuthKitConfigInput:
+      type: string
+      enum:
+        - id
+        - updatedAt
     PasswordPolicyErrorCode:
       type: string
       enum:
@@ -25180,6 +25197,87 @@ components:
       properties:
         guestName:
           type: string
+    ProofTransfer:
+      type: object
+      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/package.json

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