@proveanything/smartlinks 1.16.5 → 1.16.7

package/dist/openapi.yaml

@@ -1261,6 +1261,11 @@ paths:
           required: false
           schema:
             type: string
+        - name: moderationStatus
+          in: query
+          required: false
+          schema:
+            $ref: "#/components/schemas/AttestationModerationStatus"
         - name: recordedAfter
           in: query
           required: false
@@ -10237,6 +10242,11 @@ paths:
           required: false
           schema:
             type: string
+        - name: moderationStatus
+          in: query
+          required: false
+          schema:
+            $ref: "#/components/schemas/AttestationModerationStatus"
         - name: recordedAfter
           in: query
           required: false
@@ -10270,6 +10280,37 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+    post:
+      tags:
+        - attestations
+      summary: attestations.publicCreate
+      operationId: attestations_publicCreate
+      security: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CreateOwnerAttestationResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/OwnerAttestationInput"
   /public/collection/{collectionId}/attestations/latest:
     get:
       tags:
@@ -10474,6 +10515,43 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /public/collection/{collectionId}/attestations/{attestationId}/moderate:
+    post:
+      tags:
+        - attestations
+      summary: Moderate a contributed attestation (proof OWNER by identity, or collection admin).
+      operationId: attestations_moderate
+      security: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: attestationId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ModerateAttestationResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ModerateAttestationInput"
   /public/collection/{collectionId}/comm/email/register:
     post:
       tags:
@@ -11084,6 +11162,11 @@ paths:
           required: false
           schema:
             type: string
+        - name: moderationStatus
+          in: query
+          required: false
+          schema:
+            $ref: "#/components/schemas/AttestationModerationStatus"
         - name: recordedAfter
           in: query
           required: false
@@ -18689,6 +18772,10 @@ components:
           type: string
         authorId:
           type: string
+        grantId:
+          type: string
+        moderationStatus:
+          $ref: "#/components/schemas/AttestationModerationStatus"
         metadata:
           type: object
           additionalProperties: true
@@ -18782,6 +18869,58 @@ components:
         - subjectType
         - subjectId
         - attestationType
+    OwnerAttestationInput:
+      type: object
+      properties:
+        subjectType:
+          $ref: "#/components/schemas/AttestationSubjectType"
+        subjectId:
+          type: string
+        attestationType:
+          type: string
+        recordedAt:
+          type: string
+        visibility:
+          type: string
+          enum:
+            - public
+            - owner
+        value:
+          type: object
+          additionalProperties: true
+        ownerData:
+          type: object
+          additionalProperties: true
+        unit:
+          type: string
+        source:
+          type: string
+        metadata:
+          type: object
+          additionalProperties: true
+        guestName:
+          type: string
+      required:
+        - subjectType
+        - subjectId
+        - attestationType
+    ModerateAttestationInput:
+      type: object
+      properties:
+        decision:
+          type: string
+          enum:
+            - approve
+            - reject
+      required:
+        - decision
+    ModerateAttestationResponse:
+      type: object
+      properties:
+        attestation:
+          $ref: "#/components/schemas/Attestation"
+      required:
+        - attestation
     ListAttestationsResponse:
       type: object
       properties:
@@ -18791,6 +18930,13 @@ components:
             $ref: "#/components/schemas/Attestation"
       required:
         - attestations
+    CreateOwnerAttestationResponse:
+      type: object
+      properties:
+        attestation:
+          $ref: "#/components/schemas/Attestation"
+      required:
+        - attestation
     PublicListAttestationsResponse:
       type: object
       properties:
@@ -18914,6 +19060,8 @@ components:
           type: string
         attestationType:
           type: string
+        moderationStatus:
+          $ref: "#/components/schemas/AttestationModerationStatus"
         recordedAfter:
           type: string
         recordedBefore:
@@ -25761,6 +25909,8 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/GrantScope"
+        moderate:
+          type: boolean
         audience:
           $ref: "#/components/schemas/GrantAudience"
         createdBy:
@@ -25801,6 +25951,8 @@ components:
         expiresAt:
           type: object
           additionalProperties: true
+        moderate:
+          type: boolean
       required:
         - scope
     RedeemGrantOptions:

package/dist/types/attestations.d.ts

@@ -17,6 +17,14 @@ export type AttestationSubjectType = 'container' | 'proof' | 'product' | 'tag' |
  * - `'admin'`   — visible to admin callers only
  */
 export type AttestationVisibility = 'public' | 'owner' | 'admin';
+/**
+ * Moderation state of an attestation (separate from {@link AttestationVisibility}).
+ * - `'approved'` — live; follows its declared visibility (the default)
+ * - `'pending'`  — awaiting owner review; returned only to its author and to
+ *   owner/admin audiences, never to the public, whatever its target visibility
+ * - `'rejected'` — owner declined; author + admin only
+ */
+export type AttestationModerationStatus = 'approved' | 'pending' | 'rejected';
 /**
  * Resolved audience tier returned by public endpoints.
  * Tells the client which data zones are populated in the response.
@@ -59,6 +67,19 @@ export interface Attestation {
     source?: string;
     /** User ID or service account that recorded the fact */
     authorId?: string;
+    /**
+     * When authored under a `contribute` grant (rather than by identity), the id of
+     * the granting token — provenance for a contributed record. `null`/absent for
+     * owner/admin/identity writes.
+     */
+    grantId?: string | null;
+    /**
+     * Moderation gate, orthogonal to {@link visibility} and excluded from the hash
+     * chain. `'approved'` (default) is live; `'pending'` is held for owner review
+     * (visible only to its author and owner/admin audiences); `'rejected'` was
+     * declined. Contributions under a `moderate` grant start `'pending'`.
+     */
+    moderationStatus?: AttestationModerationStatus;
     /** Arbitrary extra metadata */
     metadata?: Record<string, any>;
     /** SHA-256 digest of this record (includes `prevHash`) */
@@ -128,9 +149,51 @@ export interface CreateAttestationInput {
     authorId?: string;
     metadata?: Record<string, any>;
 }
+/**
+ * Public attestation write input, used by {@link attestations.publicCreate}.
+ *
+ * Authorised two ways, same input shape (the server decides from the request):
+ *   1. the proof OWNER (Firebase ID token) adds an attestation to their own item;
+ *   2. a holder of a `contribute`-scope grant adds one — set the grant token with
+ *      `setGrantToken(token)` first; for a public-link (anonymous) grant, pass
+ *      `guestName` for attribution.
+ *
+ * Restricted vs {@link CreateAttestationInput}: no `adminData` (business-only
+ * zone), `visibility` limited to `'public' | 'owner'`, and `authorId` / `grantId`
+ * are server-stamped (so they're omitted here). If the contribute grant was issued
+ * with `moderate: true`, the created record comes back `moderationStatus: 'pending'`.
+ */
+export interface OwnerAttestationInput {
+    subjectType: AttestationSubjectType;
+    subjectId: string;
+    attestationType: string;
+    recordedAt?: string;
+    /** `'public'` | `'owner'` only — defaults to `'owner'`. */
+    visibility?: 'public' | 'owner';
+    value?: Record<string, any>;
+    ownerData?: Record<string, any>;
+    unit?: string;
+    source?: string;
+    metadata?: Record<string, any>;
+    /**
+     * Attribution for an anonymous (public-link) contribute-grant write. Ignored
+     * for owner writes and for named-grant writes (attributed to the signed-in uid).
+     */
+    guestName?: string;
+}
+/** Owner/admin decision on a pending contributed attestation. */
+export interface ModerateAttestationInput {
+    decision: 'approve' | 'reject';
+}
+export interface ModerateAttestationResponse {
+    attestation: Attestation;
+}
 export interface ListAttestationsResponse {
     attestations: Attestation[];
 }
+export interface CreateOwnerAttestationResponse {
+    attestation: Attestation;
+}
 export interface PublicListAttestationsResponse {
     attestations: Attestation[];
     /** Resolved audience tier; governs which data zones are populated */
@@ -175,6 +238,12 @@ export interface ListAttestationsParams {
     /** Required */
     subjectId: string;
     attestationType?: string;
+    /**
+     * Filter by moderation state. Primarily for the owner review queue
+     * (`moderationStatus: 'pending'`). ANDs with the server's audience gate, so a
+     * public caller can never use it to widen access.
+     */
+    moderationStatus?: AttestationModerationStatus;
     /** ISO 8601 lower bound (inclusive) */
     recordedAfter?: string;
     /** ISO 8601 upper bound (inclusive) */

package/dist/types/proof.d.ts

@@ -164,8 +164,16 @@ export type ProofFieldDef = ScopedFieldDef & {
 export interface ProofFieldsConfig {
     fields: ProofFieldDef[];
 }
-/** What a grant authorises the bearer to do on the proof. */
-export type GrantScope = 'read' | 'comment' | 'admin' | 'verify_owner';
+/**
+ * What a grant authorises the bearer to do on the proof.
+ * - `read` — see owner-tier data
+ * - `comment` — post app threads/comments
+ * - `contribute` — add records / attestations (temporary contribute access); pair
+ *   with `moderate` on {@link CreateGrantOptions} to hold contributions for review
+ * - `admin` — owner-tier read across the proof
+ * - `verify_owner` — redeem an ownership assertion (never the account)
+ */
+export type GrantScope = 'read' | 'comment' | 'contribute' | 'admin' | 'verify_owner';
 /** Who may redeem a grant. */
 export interface GrantAudience {
     kind: 'public_link' | 'named';
@@ -178,6 +186,11 @@ export interface ProofGrant {
     proofId: string;
     productId?: string | null;
     scope: GrantScope[];
+    /**
+     * `contribute` grants only: when true, records/attestations added under this
+     * grant land `pending` (owner-only) until the owner approves them.
+     */
+    moderate?: boolean;
     audience: GrantAudience;
     createdBy: string;
     expiresAt?: string | null;
@@ -200,6 +213,13 @@ export interface CreateGrantOptions {
     audience?: GrantAudience;
     /** Optional expiry — a `Date` or ISO string. */
     expiresAt?: Date | string;
+    /**
+     * Only meaningful with the `contribute` scope: hold contributions made under
+     * this grant for owner review (they start `pending` and are owner-only until
+     * approved). Ignored for other scopes. Defaults to `false` (contributions live
+     * on write).
+     */
+    moderate?: boolean;
 }
 export interface RedeemGrantOptions {
     /** Display name to stamp on guest activity when the redeemer is not signed in. */

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.16.5  |  Generated: 2026-09-05T15:46:49.017Z
+Version: 1.16.7  |  Generated: 2026-09-09T11:29:21.917Z
 
 This is a concise summary of all available API functions and types.
 
@@ -2745,6 +2745,15 @@ interface Attestation {
   unit?: string
   source?: string
   authorId?: string
+  * When authored under a `contribute` grant (rather than by identity), the id of
+  * the granting token — provenance for a contributed record. `null`/absent for
+  * owner/admin/identity writes.
+  grantId?: string | null
+  * Moderation gate, orthogonal to {@link visibility} and excluded from the hash
+  * chain. `'approved'` (default) is live; `'pending'` is held for owner review
+  * (visible only to its author and owner/admin audiences); `'rejected'` was
+  * declined. Contributions under a `moderate` grant start `'pending'`.
+  moderationStatus?: AttestationModerationStatus
   metadata?: Record<string, any>
   contentHash: string
   prevHash?: string
@@ -2797,6 +2806,39 @@ interface CreateAttestationInput {
 }
 ```
 
+**OwnerAttestationInput** (interface)
+```typescript
+interface OwnerAttestationInput {
+  subjectType: AttestationSubjectType
+  subjectId: string
+  attestationType: string
+  recordedAt?: string
+  visibility?: 'public' | 'owner'
+  value?: Record<string, any>
+  ownerData?: Record<string, any>
+  unit?: string
+  source?: string
+  metadata?: Record<string, any>
+  * Attribution for an anonymous (public-link) contribute-grant write. Ignored
+  * for owner writes and for named-grant writes (attributed to the signed-in uid).
+  guestName?: string
+}
+```
+
+**ModerateAttestationInput** (interface)
+```typescript
+interface ModerateAttestationInput {
+  decision: 'approve' | 'reject'
+}
+```
+
+**ModerateAttestationResponse** (interface)
+```typescript
+interface ModerateAttestationResponse {
+  attestation: Attestation
+}
+```
+
 **ListAttestationsResponse** (interface)
 ```typescript
 interface ListAttestationsResponse {
@@ -2804,6 +2846,13 @@ interface ListAttestationsResponse {
 }
 ```
 
+**CreateOwnerAttestationResponse** (interface)
+```typescript
+interface CreateOwnerAttestationResponse {
+  attestation: Attestation
+}
+```
+
 **PublicListAttestationsResponse** (interface)
 ```typescript
 interface PublicListAttestationsResponse {
@@ -2882,6 +2931,10 @@ interface ListAttestationsParams {
   subjectType: AttestationSubjectType
   subjectId: string
   attestationType?: string
+  * Filter by moderation state. Primarily for the owner review queue
+  * (`moderationStatus: 'pending'`). ANDs with the server's audience gate, so a
+  * public caller can never use it to widen access.
+  moderationStatus?: AttestationModerationStatus
   recordedAfter?: string
   recordedBefore?: string
   limit?: number
@@ -2946,6 +2999,8 @@ interface AttestationTreeLatestParams {
 
 **AttestationVisibility** = `'public' | 'owner' | 'admin'`
 
+**AttestationModerationStatus** = `'approved' | 'pending' | 'rejected'`
+
 **AttestationAudience** = `'public' | 'owner' | 'admin'`
 
 **AttestationGroupBy** = `'hour' | 'day' | 'week' | 'month'`
@@ -7541,6 +7596,9 @@ interface ProofGrant {
   proofId: string
   productId?: string | null
   scope: GrantScope[]
+  * `contribute` grants only: when true, records/attestations added under this
+  * grant land `pending` (owner-only) until the owner approves them.
+  moderate?: boolean
   audience: GrantAudience
   createdBy: string
   expiresAt?: string | null
@@ -7559,6 +7617,11 @@ interface CreateGrantOptions {
   scope: GrantScope[]
   audience?: GrantAudience
   expiresAt?: Date | string
+  * Only meaningful with the `contribute` scope: hold contributions made under
+  * this grant for owner review (they start `pending` and are owner-only until
+  * approved). Ignored for other scopes. Defaults to `false` (contributions live
+  * on write).
+  moderate?: boolean
 }
 ```
 
@@ -7656,7 +7719,7 @@ interface CancelTransferOptions {
 
 **ProofFieldDef** = `ScopedFieldDef & { scope?: ProofFieldScope }`
 
-**GrantScope** = `'read' | 'comment' | 'admin' | 'verify_owner'`
+**GrantScope** = `'read' | 'comment' | 'contribute' | 'admin' | 'verify_owner'`
 
 **RedeemGrantResult** = ``
 
@@ -9063,6 +9126,15 @@ Tree latest snapshot — most-recent record per type across a container subtree
     params: ListAttestationsParams) → `Promise<PublicListAttestationsResponse>`
 List attestations for a subject (public). Records with `visibility='admin'` are always excluded. Records with `visibility='owner'` are included only when the caller provides a valid Firebase ID token that resolves to the subject owner. The `audience` field in the response indicates the tier that was served. ```typescript const { attestations: records, audience } = await attestations.publicList('coll_123', { subjectType: 'proof', subjectId:   'proof-uuid', }) ```
 
+**publicCreate**(collectionId: string,
+    data: OwnerAttestationInput) → `Promise<CreateOwnerAttestationResponse>`
+Create a public attestation — the counterpart to the admin {@link create}. Authorised two ways, same call (the server decides from the request): 1. the proof OWNER (identity, via `Authorization: Bearer <Firebase ID token>`) adds an attestation to their own item; or 2. a holder of a `contribute`-scope grant adds one — call {@link setGrantToken} with the grant token first; for a public-link (anonymous) grant, pass `guestName` for attribution. Guardrails (server-enforced): `value` + `ownerData` only (`adminData` dropped), `visibility` clamped to `'public' | 'owner'`, `authorId`/`grantId` server-stamped. If the contribute grant was issued with `moderate: true`, the returned record has `moderationStatus: 'pending'` — held to the owner until {@link moderate}. The record joins the same tamper-evident hash chain. POST /public/collection/:collectionId/attestations ```ts // Owner: await attestations.publicCreate('coll_123', { subjectType: 'proof', subjectId: 'proof_1', attestationType: 'condition-report', value: { grade: 'excellent' }, visibility: 'public', }) // Contributor on a shared link: setGrantToken(shareToken) await attestations.publicCreate('coll_123', { subjectType: 'proof', subjectId: 'proof_1', attestationType: 'photo', value: { url }, visibility: 'public', guestName: 'Sam', }) ```
+
+**moderate**(collectionId: string,
+    attestationId: string,
+    input: ModerateAttestationInput) → `Promise<ModerateAttestationResponse>`
+Moderate a contributed attestation (proof OWNER by identity, or collection admin). `'approve'` releases it to its declared visibility; `'reject'` keeps it author + admin only. Only the `moderationStatus` changes — the hashed fact and its chain are untouched. Find pending items with {@link publicList} + `moderationStatus: 'pending'`. POST /public/collection/:collectionId/attestations/:attestationId/moderate ```ts await attestations.moderate('coll_123', 'att_uuid', { decision: 'approve' }) ```
+
 **publicSummary**(collectionId: string,
     params: AttestationSummaryParams) → `Promise<PublicAttestationSummaryResponse>`
 Time-series summary (public). Always served at `audience='public'`.  Same parameters as the admin version. `attestationType` are required

package/docs/attestations.md

@@ -159,6 +159,34 @@ The middleware resolves the UID and checks ownership:
 
 When ownership is confirmed the request is served at `audience='owner'`, which includes `ownerData`.
 
+**Owner write** — the proof owner may also *author* an attestation on their own item via `POST /api/v1/public/collection/:collectionId/attestations` (`attestations.publicCreate`). It is the public counterpart to the admin write, with tight guardrails:
+
+- the caller must be authenticated and **own the linked proof** (identity — a read grant is not enough); a subject with no linked proof is rejected;
+- they may write `value` and `ownerData` only — **`adminData` is dropped** (the business zone);
+- `visibility` is clamped to `'public' | 'owner'` (never `'admin'`), defaulting to `'owner'`;
+- `authorId` is forced to the caller and `metadata.authorType = 'owner'` is stamped.
+
+**Contribute write (grant)** — the same endpoint also accepts a holder of a
+`contribute`-scope share grant (set the token with `setGrantToken` first), so a
+third party can add an attestation without owning the proof. Named grant →
+attributed to the signed-in uid; public-link grant → anonymous, with `guestName`
+for attribution; `grantId` is stamped either way. If the grant was issued with
+`moderate: true`, the record is created with `moderationStatus: 'pending'` and is
+held to the owner until approved.
+
+**Moderation** — `moderationStatus` (`approved` | `pending` | `rejected`) is a gate
+**orthogonal to `visibility`** and excluded from the hash chain. A `pending` record
+is returned only to its author and to owner/admin audiences — never to the public,
+whatever its target visibility — and is excluded from public analytics. The owner
+(identity) or a collection admin resolves it with `attestations.moderate(collectionId,
+attestationId, { decision: 'approve' | 'reject' })`; approve releases it to its
+declared visibility, reject keeps it author+admin-only. The review queue is
+`attestations.publicList(..., { moderationStatus: 'pending' })`. Flipping the status
+leaves the hashed fact and its chain untouched. See
+[Proof Share Grants → Contribute access](proof-share-grants.md#contribute-access--let-someone-add-to-a-proof).
+
+The record joins the same append-only, hash-chained log as business/system writes. Business writes (any zone/visibility) remain admin-only.
+
 ### Visibility vs audience
 
 `visibility` is a property of an **individual record** set at write time.  `audience` describes the **caller's tier** resolved at read time.  The server applies:

package/docs/proof-share-grants.md

@@ -22,11 +22,12 @@ re-checks the grant **server-side** against the database, so revocation is immed
 |-------|--------------------|
 | `read` | read owner-tier data on the proof (attestations, threads, records, cases) |
 | `comment` | create threads/replies on the proof (guest comments) |
+| `contribute` | add attestations / records to the proof for the life of the grant (temporary contribute access) — optionally held for owner review via `moderate` |
 | `admin` | read owner-tier data (reserved for elevated share cases; never exposes the platform admin zone) |
 | `verify_owner` | redeem a shareable ownership **assertion** (not the account) |
 
 A grant can carry several scopes, e.g. `['read', 'comment']` for a shareable,
-commentable album.
+commentable album, or `['read', 'contribute']` to let someone add photos.
 
 ### Security & lifecycle
 
@@ -124,6 +125,65 @@ Other grant holders (and the owner) see these comments because a `read` grant re
 
 ---
 
+## Contribute access — let someone add to a proof
+
+A `contribute` scope grant is **temporary write access**: the bearer can add
+attestations (a photo, a video reference, a check-in) and app records to the proof
+for the life of the grant — no account or proof claim required. It's the successor
+to ad-hoc "claim windows": properly time-boxed (`expiresAt`), revocable, and voided
+on ownership transfer like every other grant.
+
+```typescript
+// Owner issues a contribute grant that expires in 48h and holds contributions
+// for review before they go public.
+const grant = await proof.createGrant(collectionId, productId, proofId, {
+  scope: ['read', 'contribute'],
+  moderate: true,                                   // contributions land 'pending'
+  expiresAt: new Date(Date.now() + 48 * 60 * 60 * 1000),
+})
+
+// Contributor (on the shared link) adds a photo attestation.
+setGrantToken(shareToken)
+await attestation.publicCreate(collectionId, {
+  subjectType: 'proof', subjectId: proofId,
+  attestationType: 'photo',
+  value: { url: 'https://…/photo.jpg' },
+  visibility: 'public',
+  guestName: 'Sam',                                 // attribution for a public-link bearer
+})
+```
+
+### Moderation — the two-step review
+
+When the grant is issued with `moderate: true`, each contribution is created with
+`moderationStatus: 'pending'` and is **held to the owner**: it is returned only to
+its own author and to owner/admin audiences — never to the public, whatever its
+target `visibility`. The owner reviews and approves (or rejects) it:
+
+```typescript
+// Owner lists what's waiting (owner-tier read = identity or an owner session):
+const { attestations } = await attestation.publicList(collectionId, {
+  subjectType: 'proof', subjectId: proofId,
+  moderationStatus: 'pending',
+})
+
+// Approve → the record goes live at its declared visibility; reject → author+admin only.
+await attestation.moderate(collectionId, attestations[0].id, { decision: 'approve' })
+```
+
+The moderation gate is enforced **server-side** — a front end may badge a pending
+item, but it is the server that withholds it from other viewers. Only
+`moderationStatus` changes on approve/reject; the hashed fact and its chain are
+untouched. Contributions under a grant issued with `moderate: false` (the default)
+go live immediately.
+
+> **Media note.** A contributed photo/video is best modelled as an attestation
+> (`attestationType: 'photo'`, `value: { url }`) so it rides this moderation model.
+> The legacy per-proof asset upload path is unchanged and is not grant- or
+> moderation-aware.
+
+---
+
 ## Proof of ownership — `verify_owner`
 
 Ownership itself is **not** a grant — it is `proof.ownerId`, established via the
@@ -154,6 +214,7 @@ granted proof (and only that proof):
 - **Attestations** — `attestation.publicList({ subjectType: 'proof', subjectId })`
 - **Threads / Records / Cases** — `app.threads.list`, `app.records.*`, `app.cases.list`, and the single-item GETs, filtered to the granted proof
 - **Thread creation / replies** — with a `comment` scope grant (see below)
+- **Attestation / record creation** — with a `contribute` scope grant (see [Contribute access](#contribute-access--let-someone-add-to-a-proof))
 
 The token never exposes the platform `admin` zone, and only reveals `owner`-visibility
 rows for the granted `proofId`.
@@ -175,14 +236,24 @@ at `sites/{collectionId}/apps/{appId}` — a `grant` branch alongside
         "requireScope": "comment",
         "enforce": { "visibility": "owner", "status": "open" }
       }
+    },
+    "records": {
+      "grant": {
+        "allow": true,
+        "requireScope": "contribute",
+        "enforce": { "visibility": "owner" }   // held to the owner until promoted
+      }
     }
   }
 }
 ```
 
-This enables grant-scoped commenting **without** opening up anonymous creation. The
-`enforce.visibility: "owner"` keeps comments private to the proof (visible to the
-owner and other grant holders, not the wider public).
+This enables grant-scoped commenting and contribution **without** opening up
+anonymous creation. The `enforce.visibility: "owner"` keeps the created object
+private to the proof (visible to the owner and other grant holders, not the wider
+public). Attestation contribution is gated the same way, by the `contribute` scope;
+whether those contributions are held for review is set per-grant with `moderate`,
+not in app config.
 
 ---
 
@@ -200,12 +271,13 @@ namespace proof {
 function setGrantToken(token: string | undefined): void
 function getGrantToken(): string | undefined
 
-type GrantScope = 'read' | 'comment' | 'admin' | 'verify_owner'
+type GrantScope = 'read' | 'comment' | 'contribute' | 'admin' | 'verify_owner'
 
 interface CreateGrantOptions {
   scope: GrantScope[]                                   // at least one
   audience?: { kind: 'public_link' } | { kind: 'named'; email?: string; userId?: string }
   expiresAt?: Date | string
+  moderate?: boolean                                    // 'contribute' only — hold for review
 }
 
 interface RedeemGrantOptions { guestName?: string }
@@ -219,6 +291,7 @@ interface ProofGrant {
   proofId: string
   productId?: string | null
   scope: GrantScope[]
+  moderate?: boolean   // 'contribute' grants: contributions held for review when true
   audience: { kind: 'public_link' | 'named'; email?: string; userId?: string }
   createdBy: string
   expiresAt?: string | null