@proveanything/smartlinks 1.15.18 → 1.15.20

package/dist/types/proof.d.ts

@@ -40,16 +40,71 @@ export interface Proof {
     values: ProofValues;
 }
 export type ProofResponse = Proof;
-export interface ProofCreateRequest {
-    values: ProofValues;
-    /** Business-writable public spec data. */
+/**
+ * The proof's writable content, addressed by zone. Its keys mirror the proof
+ * document, so what you pass is what the proof looks like. Each zone has its own
+ * read/write visibility:
+ *
+ * | Zone     | Stored at      | Readable by            | Writable by   |
+ * |----------|----------------|------------------------|---------------|
+ * | `values` | `proof.values` | public + owner + admin | owner + admin |
+ * | `data`   | `proof.data`   | public + owner + admin | admin only    |
+ * | `admin`  | `proof.admin`  | admin only             | admin only    |
+ * | `owner`  | `proof.owner`  | admin only             | admin only    |
+ *
+ * Use `data` for business fields everyone should *see* but only the business
+ * should *set* (e.g. a serial number). Use `admin` for fields only the business
+ * should see at all. On update, object zones deep-merge.
+ */
+export interface ProofWrite {
+    /**
+     * Choose the proof's ID (serial, NFC id, etc.). Honoured **on create only** —
+     * the ledger doc becomes `{productId}-{id}`. Omit to auto-generate. Ignored on
+     * update (a proof's ID is immutable).
+     */
+    id?: string;
+    /** Owner + business-writable consumer data. Public + owner readable. → `proof.values` */
+    values?: ProofValues;
+    /** Business spec data (e.g. serialNo). Public + owner readable, admin-only writable. → `proof.data` */
     data?: Record<string, JsonValue>;
-    /** Business-only spec data. */
+    /** Business-only spec data — admin-only read & write (stripped from public + owner). → `proof.admin` */
     admin?: Record<string, JsonValue>;
+    /** Business-only root data — admin-only. → `proof.owner` */
+    owner?: Record<string, JsonValue>;
+    /** Is this proof available to be claimed. */
+    claimable?: boolean;
+    /** Any other named root field. */
+    [key: string]: JsonValue | Record<string, JsonValue> | ProofValues | undefined;
+}
+export interface ProofCreateRequest {
+    /**
+     * The proof to create, by zone (mirrors the proof document). This is the clear,
+     * recommended shape — `create(collectionId, productId, { proof: {...} })`.
+     */
+    proof?: ProofWrite;
+    /** Owner + business-writable consumer data (→ `proof.values`). Same as `proof.values`. */
+    values?: ProofValues;
+    /** Canonical root `claimable` flag (also accepted as `proof.claimable`). */
     claimable?: boolean;
     virtual?: boolean;
+    /** @deprecated Legacy alias for `proof`. Use `proof`. */
+    core?: ProofWrite;
+    /**
+     * @deprecated On the request body this is folded into the **values bag**
+     * (public + owner-writable) — NOT `proof.data`. Use `proof.data`.
+     */
+    data?: Record<string, JsonValue>;
+    /** @deprecated Not routed to `proof.admin` on create — use `proof.admin`. */
+    admin?: Record<string, JsonValue>;
 }
-export type ProofUpdateRequest = Partial<ProofCreateRequest>;
+/**
+ * Update passes the proof's fields **at the root** — `update(c, p, id, { data: {...} })`
+ * sets `proof.data`, `{ values: {...} }` sets `proof.values`, etc. (A `proof` block is
+ * also accepted and routed the same way.) Object zones deep-merge.
+ */
+export type ProofUpdateRequest = Partial<ProofWrite> & {
+    proof?: ProofWrite;
+};
 export type ProofClaimRequest = Record<string, any>;
 /**
  * `'public'` (default, omitted) reads/writes `proof.values[key]`.
@@ -120,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.18  |  Generated: 2026-08-19T06:40:47.505Z
+Version: 1.15.20  |  Generated: 2026-08-25T07:03:45.544Z
 
 This is a concise summary of all available API functions and types.
 
@@ -3464,6 +3464,55 @@ 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
+}
+```
+
+**AuthKitSecurityConfig** (interface)
+```typescript
+interface AuthKitSecurityConfig {
+  passwordPolicy?: AuthKitPasswordPolicy
+  session?: AuthKitSessionPolicy
+  lockout?: AuthKitLockoutPolicy
+}
+```
+
+**AuthKitPasswordPolicy** (interface)
+```typescript
+interface AuthKitPasswordPolicy {
+  minLength?: number
+  requireUppercase?: boolean
+  requireLowercase?: boolean
+  requireNumber?: boolean
+  requireSymbol?: boolean
+  blockCommonPasswords?: boolean
+  expiryDays?: number
+  historyCount?: number
+}
+```
+
+**AuthKitSessionPolicy** (interface)
+```typescript
+interface AuthKitSessionPolicy {
+  inactivityTimeoutMinutes?: number
+  inactivityWarningSeconds?: number
+  absoluteTimeoutHours?: number
+  rememberMe?: boolean
+}
+```
+
+**AuthKitLockoutPolicy** (interface)
+```typescript
+interface AuthKitLockoutPolicy {
+  enabled?: boolean
+  maxFailedAttempts?: number
+  attemptWindowMinutes?: number
+  lockoutMinutes?: number
+  notifyUserOnLockout?: boolean
 }
 ```
 
@@ -3475,6 +3524,12 @@ interface AuthKitConfig {
 
 **VerifyStatus** = `'pending' | 'verified' | 'failed' | 'expired' | 'unknown'`
 
+**AuthKitConfigInput** = ``
+
+**PasswordPolicyErrorCode** = ``
+
+**LoginSecurityErrorCode** = ``
+
 ### batch
 
 **FirebaseTimestamp** (interface)
@@ -7279,14 +7334,36 @@ interface Proof {
 }
 ```
 
-**ProofCreateRequest** (interface)
+**ProofWrite** (interface)
 ```typescript
-interface ProofCreateRequest {
-  values: ProofValues
+interface ProofWrite {
+  * Choose the proof's ID (serial, NFC id, etc.). Honoured **on create only** —
+  * the ledger doc becomes `{productId}-{id}`. Omit to auto-generate. Ignored on
+  * update (a proof's ID is immutable).
+  id?: string
+  values?: ProofValues
   data?: Record<string, JsonValue>
   admin?: Record<string, JsonValue>
+  owner?: Record<string, JsonValue>
+  claimable?: boolean
+  [key: string]: JsonValue | Record<string, JsonValue> | ProofValues | undefined
+}
+```
+
+**ProofCreateRequest** (interface)
+```typescript
+interface ProofCreateRequest {
+  * The proof to create, by zone (mirrors the proof document). This is the clear,
+  * recommended shape — `create(collectionId, productId, { proof: {...} })`.
+  proof?: ProofWrite
+  values?: ProofValues
   claimable?: boolean
   virtual?: boolean
+  core?: ProofWrite
+  * @deprecated On the request body this is folded into the **values bag**
+  * (public + owner-writable) — NOT `proof.data`. Use `proof.data`.
+  data?: Record<string, JsonValue>
+  admin?: Record<string, JsonValue>
 }
 ```
 
@@ -7341,9 +7418,51 @@ 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<ProofCreateRequest>`
+**ProofUpdateRequest** = `Partial<ProofWrite> & { proof?: ProofWrite }`
 
 **ProofClaimRequest** = `Record<string, any>`
 
@@ -7355,6 +7474,10 @@ interface RedeemGrantOptions {
 
 **RedeemGrantResult** = ``
 
+**ProofTransferType** = `'directed' | 'open_release' | 'contested'`
+
+**ProofTransferState** = ``
+
 ### qr
 
 **QrShortCodeLookupResponse** (interface)
@@ -8748,10 +8871,10 @@ Gets current account information for the logged in user. Returns user, owner, ac
 ### authKit
 
 **login**(clientId: string, email: string, password: string, trustedDeviceToken?: string) → `Promise<AuthLoginResponse>`
-Login with email + password (public). When the client's MFA policy requires a step-up, the server returns **403 `MFA_REQUIRED`** instead of a session — `login()` throws a `SmartlinksApiError` with `err.errorResponse?.errorCode === 'MFA_REQUIRED'` and the challenge details in `err.details` (see {@link MfaRequiredDetails}). Route the caller to {@link mfaChallengeSend} on that error; this method's return type is unchanged. returned one (via {@link mfaChallengeVerify}/{@link mfaRecoveryCode} with `trustDevice: true`), pass it here to skip the challenge entirely as long as it's still valid. If it's revoked/expired, the server silently falls back to requiring a fresh challenge — `login()` just returns `MFA_REQUIRED` again, no special handling.
+Login with email + password (public). When the client's MFA policy requires a step-up, the server returns **403 `MFA_REQUIRED`** instead of a session — `login()` throws a `SmartlinksApiError` with `err.errorResponse?.errorCode === 'MFA_REQUIRED'` and the challenge details in `err.details` (see {@link MfaRequiredDetails}). Route the caller to {@link mfaChallengeSend} on that error; this method's return type is unchanged. returned one (via {@link mfaChallengeVerify}/{@link mfaRecoveryCode} with `trustDevice: true`), pass it here to skip the challenge entirely as long as it's still valid. If it's revoked/expired, the server silently falls back to requiring a fresh challenge — `login()` just returns `MFA_REQUIRED` again, no special handling. Security errors (thrown as `SmartlinksApiError`, see {@link LoginSecurityErrorCode}): - `ACCOUNT_TEMPORARILY_LOCKED` (429) — `err.details.retryAfterSeconds` says how long to wait. - `PASSWORD_EXPIRED` (403) — `err.details.resetToken` is short-lived; route into {@link completePasswordReset} to change the password in place.
 
 **register**(clientId: string, data: { email: string; password: string; displayName?: string; accountData?: Record<string, any> }) → `Promise<AuthLoginResponse>`
-Register a new user (public). Not gated by step-up MFA — a brand-new user has no enrolled factors yet, so there's nothing to challenge against.
+Register a new user (public). Not gated by step-up MFA — a brand-new user has no enrolled factors yet, so there's nothing to challenge against. The new password is validated against the collection's `passwordPolicy` — may throw a {@link PasswordPolicyErrorCode} (400). The same validation applies to {@link completePasswordReset} and {@link changePassword}. Read the policy for a live checklist from `authKit.load(clientId)` → `config.security.passwordPolicy`.
 
 **googleLogin**(clientId: string, idToken: string, trustedDeviceToken?: string) → `Promise<AuthLoginResponse>`
 Google OAuth login via ID token (public). Gated by step-up MFA — see {@link login} for the `MFA_REQUIRED` error shape. {@link mfaChallengeVerify}/{@link mfaRecoveryCode} (with `trustDevice: true`) to skip the challenge on this device, same as {@link login}.
@@ -8877,22 +9000,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
 
@@ -9952,14 +10075,14 @@ List all Proofs for a Collection.
 
 **create**(collectionId: string,
     productId: string,
-    values: ProofCreateRequest) → `Promise<ProofResponse>`
-Create a proof for a product (admin only). POST /admin/collection/:collectionId/product/:productId/proof
+    request: ProofCreateRequest) → `Promise<ProofResponse>`
+Create a proof for a product (admin only). POST /admin/collection/:collectionId/product/:productId/proof Pass the proof's content in a `proof` block, keyed by zone (see {@link ProofWrite}): ```ts proof.create(collectionId, productId, { proof: { values: { colour: 'red' },   // public + owner readable, owner + admin writable data:   { serialNo: 1001 },  // public + owner readable, ADMIN-only writable admin:  { costPrice: 4.20 }, // admin-only }, claimable: true, }) ``` Note: a top-level `data`/`admin` on the request body is legacy — top-level `data` gets folded into the values bag, so use `proof.data` for `proof.data`.
 
 **update**(collectionId: string,
     productId: string,
     proofId: string,
     values: ProofUpdateRequest) → `Promise<ProofResponse>`
-Update a proof for a product (admin only). PUT /admin/collection/:collectionId/product/:productId/proof/:proofId
+Update a proof for a product (admin only). PUT /admin/collection/:collectionId/product/:productId/proof/:proofId Pass the fields to change **at the root**, keyed by zone (see {@link ProofWrite}): ```ts proof.update(collectionId, productId, proofId, { data:   { serialNo: 1002 },   // → proof.data (admin-only writable) values: { colour: 'blue' },   // → proof.values }) ``` Object zones deep-merge, so you can change one field without wiping the rest.
 
 **claim**(collectionId: string,
     productId: string,
@@ -10026,6 +10149,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

@@ -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/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).