@proveanything/smartlinks 1.16.6 → 1.17.0

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.16.6  |  Generated: 2026-09-06T07:49:21.444Z
+Version: 1.17.0  |  Generated: 2026-09-13T07:38:31.861Z
 
 This is a concise summary of all available API functions and types.
 
@@ -134,6 +134,7 @@ The Smartlinks SDK is organized into the following namespaces:
 - **containers** - Functions for containers operations
 - **facets** - Functions for facets operations
 - **http** - Functions for http operations
+- **integrations** - Functions for integrations operations
 - **jobs** - Functions for jobs operations
 - **journeysAnalytics** - Functions for journeysAnalytics operations
 - **location** - Functions for location operations
@@ -142,6 +143,7 @@ The Smartlinks SDK is organized into the following namespaces:
 - **order** - Functions for order operations
 - **products** - Functions for products operations
 - **realtime** - Functions for realtime operations
+- **secrets** - Functions for secrets operations
 - **tags** - Functions for tags operations
 - **template** - Functions for template operations
 - **translations** - Functions for translations operations
@@ -2745,6 +2747,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
@@ -2810,6 +2821,23 @@ interface OwnerAttestationInput {
   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
 }
 ```
 
@@ -2905,6 +2933,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
@@ -2969,6 +3001,8 @@ interface AttestationTreeLatestParams {
 
 **AttestationVisibility** = `'public' | 'owner' | 'admin'`
 
+**AttestationModerationStatus** = `'approved' | 'pending' | 'rejected'`
+
 **AttestationAudience** = `'public' | 'owner' | 'admin'`
 
 **AttestationGroupBy** = `'hour' | 'day' | 'week' | 'month'`
@@ -5736,6 +5770,195 @@ interface UploadDoneMessage {
 
 **UploadMessage** = ``
 
+### integrations
+
+**FieldMapping** (interface)
+```typescript
+interface FieldMapping {
+  targetPath: string
+  sourcePath?: string
+  transformType: TransformType
+  transformExpression?: string
+}
+```
+
+**FlowConnectionAuth** (interface)
+```typescript
+interface FlowConnectionAuth {
+  method: FlowAuthMethod
+  headerName?: string
+  credentialRef?: string
+}
+```
+
+**FlowConnection** (interface)
+```typescript
+interface FlowConnection {
+  baseUrl?: string
+  sendEndpoint?: string
+  fetchEndpoint?: string
+  defaultHeaders?: Record<string, string>
+  auth?: FlowConnectionAuth
+}
+```
+
+**IntegrationFlowConfig** (interface)
+```typescript
+interface IntegrationFlowConfig {
+  connection?: FlowConnection
+  fieldMappings?: FieldMapping[]
+  [key: string]: any
+}
+```
+
+**IntegrationFlow** (interface)
+```typescript
+interface IntegrationFlow {
+  id: string
+  orgId: string
+  collectionId: string
+  appId: string
+  direction: FlowDirection
+  name: string
+  status: FlowStatus
+  eventTypes: string[]
+  schedule: string | null
+  sourceEntity: string | null
+  targetEntity: string | null
+  config: IntegrationFlowConfig
+  createdBy: string | null
+  createdAt: string
+  updatedAt: string
+  deletedAt?: string | null
+  lastRunAt?: string | null
+  lastRunStatus?: string | null
+  lastRunError?: string | null
+  lastRunCount?: number | null
+  lastPollAt?: string | null
+  lastCursor?: string | null
+  totalSynced?: number | null
+}
+```
+
+**CreateFlowInput** (interface)
+```typescript
+interface CreateFlowInput {
+  appId: string
+  direction: FlowDirection
+  name: string
+  status?: FlowStatus
+  eventTypes?: string[]
+  schedule?: string | null
+  sourceEntity?: string | null
+  targetEntity?: string | null
+  config?: IntegrationFlowConfig
+}
+```
+
+**ListFlowsQuery** (interface)
+```typescript
+interface ListFlowsQuery {
+  direction?: FlowDirection
+  status?: FlowStatus
+  appId?: string
+}
+```
+
+**FlowList** (interface)
+```typescript
+interface FlowList {
+  flows: IntegrationFlow[]
+}
+```
+
+**RunFlowInput** (interface)
+```typescript
+interface RunFlowInput {
+  entityId?: string
+}
+```
+
+**RunFlowSummary** (interface)
+```typescript
+interface RunFlowSummary {
+  flowId: string
+  direction: FlowDirection
+  records: number
+  sent: number
+  failed: number
+  status: RunStatus
+}
+```
+
+**RunFlowEnqueued** (interface)
+```typescript
+interface RunFlowEnqueued {
+  enqueued: true
+  flowId: string
+  entityId: string | null
+}
+```
+
+**SecretMeta** (interface)
+```typescript
+interface SecretMeta {
+  ref: string
+  name: string | null
+  purpose: string
+  hint: string
+  keyVersion: number
+  createdBy: string | null
+  createdAt: string
+  updatedAt: string
+  rotatedAt?: string | null
+}
+```
+
+**SecretList** (interface)
+```typescript
+interface SecretList {
+  secrets: SecretMeta[]
+}
+```
+
+**SetSecretInput** (interface)
+```typescript
+interface SetSecretInput {
+  value: string
+  name?: string
+  purpose?: string
+}
+```
+
+**SetSecretResult** (interface)
+```typescript
+interface SetSecretResult {
+  ref: string
+  hint: string
+}
+```
+
+**ListSecretsQuery** (interface)
+```typescript
+interface ListSecretsQuery {
+  purpose?: string
+}
+```
+
+**FlowDirection** = `'inbound' | 'outbound'`
+
+**FlowStatus** = `'draft' | 'active' | 'paused' | 'error'`
+
+**RunStatus** = `'success' | 'partial' | 'error'`
+
+**TransformType** = `'direct' | 'static' | 'template' | 'jsonata' | 'ai'`
+
+**FlowAuthMethod** = `'api_key' | 'bearer' | 'basic' | 'webhook' | 'oauth2' | 'none'`
+
+**UpdateFlowInput** = `Partial<Omit<CreateFlowInput, 'direction'>> & {`
+
+**RunFlowResult** = `RunFlowSummary | RunFlowEnqueued`
+
 ### interaction
 
 **AdminInteractionsQueryRequest** (interface)
@@ -7564,6 +7787,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
@@ -7582,6 +7808,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
 }
 ```
 
@@ -7679,7 +7910,7 @@ interface CancelTransferOptions {
 
 **ProofFieldDef** = `ScopedFieldDef & { scope?: ProofFieldScope }`
 
-**GrantScope** = `'read' | 'comment' | 'admin' | 'verify_owner'`
+**GrantScope** = `'read' | 'comment' | 'contribute' | 'admin' | 'verify_owner'`
 
 **RedeemGrantResult** = ``
 
@@ -9088,7 +9319,12 @@ List attestations for a subject (public). Records with `visibility='admin'` are
 
 **publicCreate**(collectionId: string,
     data: OwnerAttestationInput) → `Promise<CreateOwnerAttestationResponse>`
-Create an OWNER-authored attestation (public write) — the counterpart to the admin {@link create}. The authenticated caller must OWN the linked proof (identity, not a read grant). Guardrails enforced server-side: they may write `value` + `ownerData` only (`adminData` is dropped), `visibility` is clamped to `'public' | 'owner'`, and `authorId` is forced to the caller. The record joins the same tamper-evident hash chain. POST /public/collection/:collectionId/attestations ```ts await attestations.publicCreate('coll_123', { subjectType: 'proof', subjectId: 'proof_1', attestationType: 'condition-report', value: { grade: 'excellent' }, visibility: 'public', }) ```
+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>`
@@ -9876,6 +10112,34 @@ Perform a PATCH request to any API endpoint.
 **del**(path: string) → `Promise<T>`
 Perform a DELETE request to any API endpoint.
 
+### integrations
+
+**listFlows**(collectionId: string, query: ListFlowsQuery = {}) → `Promise<FlowList>`
+List flows in a collection. GET /integrations/flows
+
+**createFlow**(collectionId: string, input: CreateFlowInput) → `Promise<IntegrationFlow>`
+Create a flow. POST /integrations/flows
+
+**getFlow**(collectionId: string, id: string) → `Promise<IntegrationFlow>`
+Get one flow. GET /integrations/flows/:id
+
+**updateFlow**(collectionId: string, id: string, input: UpdateFlowInput) → `Promise<IntegrationFlow>`
+Update whitelisted fields. PUT /integrations/flows/:id
+
+**deleteFlow**(collectionId: string, id: string) → `Promise<`
+Soft-delete a flow. DELETE /integrations/flows/:id
+
+**runFlow**(collectionId: string,
+    id: string,
+    options: RunFlowInput & { async?: boolean } = {}) → `Promise<RunFlowResult>`
+Run a flow now. POST /integrations/flows/:id/run - inline (default): resolves and returns the run summary. - options.async: enqueue on the worker, returns { enqueued: true }. Pass options.entityId to run for a single source entity.
+
+**isRunSummary**(r: RunFlowResult) → `r is RunFlowSummary`
+Type guard: the run executed inline and returned a summary.
+
+**isRunEnqueued**(r: RunFlowResult) → `r is RunFlowEnqueued`
+Type guard: the run was enqueued (async).
+
 ### interactions
 
 **query**(collectionId: string,
@@ -10568,6 +10832,23 @@ Get an Ably token for public (user-scoped) real-time communication. This endpoin
 **getAdminToken**() → `Promise<AblyTokenRequest>`
 Get an Ably token for admin real-time communication. This endpoint returns an Ably TokenRequest that can be used to initialize an Ably client with admin permissions to receive system notifications and alerts. Admin users get subscribe-only (read-only) access to the interaction:{userId} channel pattern. Requires admin authentication (Bearer token). ```ts const tokenRequest = await realtime.getAdminToken() // Use with Ably const ably = new Ably.Realtime.Promise({ authCallback: async (data, callback) => { callback(null, tokenRequest) } }) // Subscribe to admin interaction channel const userId = 'my-user-id' const channel = ably.channels.get(`interaction:${userId}`) await channel.subscribe((message) => { console.log('Admin notification:', message.data) }) ```
 
+### secrets
+
+**list**(collectionId: string, query: ListSecretsQuery = {}) → `Promise<SecretList>`
+List secrets as refs + masked hints + metadata (never values). GET /secrets
+
+**set**(collectionId: string, input: SetSecretInput) → `Promise<SetSecretResult>`
+Create a secret. POST /secrets → { ref, hint }. Store the ref on a flow.
+
+**get**(collectionId: string, ref: string) → `Promise<SecretMeta>`
+Metadata for one secret (never the value). GET /secrets/:ref
+
+**rotate**(collectionId: string, ref: string, input: SetSecretInput) → `Promise<SetSecretResult>`
+Rotate/update a secret's value (and optionally name/purpose). PUT /secrets/:ref → { ref, hint }
+
+**remove**(collectionId: string, ref: string) → `Promise<`
+Soft-delete a secret. DELETE /secrets/:ref
+
 ### segments
 
 **create**(collectionId: string,

package/dist/docs/attestations.md

@@ -166,6 +166,25 @@ When ownership is confirmed the request is served at `audience='owner'`, which i
 - `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

package/dist/docs/integrations.md

@@ -0,0 +1,141 @@
+# Integrations
+
+An **integration flow** is one input/output pipeline between SmartLinks and an external
+system. There are two directions:
+
+- **outbound** — read a SmartLinks entity (v1: a product), transform it with field
+  mappings, and send it to an external endpoint.
+- **inbound** — fetch from an external system and write a SmartLinks entity. *(Executor is
+  outbound-first; inbound lands in a later increment.)*
+
+Flows are triggered three ways, all converging on the same executor:
+
+- **manual** — `integrations.runFlow(...)`, inline (returns a run summary) or enqueued.
+- **event** — an outbound flow subscribed to an event type (e.g. `product.updated`) fires
+  automatically when that entity changes.
+- **schedule** — a flow carrying a cron/interval `schedule` is run by the scan job. *(next)*
+
+Credentials are **never** stored on the flow. The connection holds an opaque
+`credentialRef` into the **sealed-secret store** (`secrets` namespace); the value is sealed
+at rest and resolved server-side only, at execution.
+
+---
+
+## The flow model
+
+```ts
+interface IntegrationFlow {
+  id: string
+  direction: 'inbound' | 'outbound'
+  name: string
+  status: 'draft' | 'active' | 'paused' | 'error'  // only 'active' flows fire on events/schedule
+  eventTypes: string[]                              // e.g. ['product.updated']
+  schedule: string | null                           // cron/interval for scheduled flows
+  sourceEntity: string | null                       // outbound source, v1: 'product'
+  targetEntity: string | null                       // inbound target
+  config: {
+    connection?: {
+      baseUrl?: string
+      sendEndpoint?: string                          // outbound: appended to baseUrl
+      defaultHeaders?: Record<string, string>
+      auth?: { method: 'api_key' | 'bearer' | 'basic' | ..., headerName?: string, credentialRef?: string }
+    }
+    fieldMappings?: FieldMapping[]
+  }
+  // ...run watermark/telemetry: lastRunAt, lastRunStatus, lastRunCount, totalSynced
+}
+```
+
+### Field mappings (transform)
+
+Each mapping produces one field on the target payload:
+
+| transformType | uses | meaning |
+|---|---|---|
+| `direct` | `sourcePath` | copy the value at that dot-path |
+| `static` | `transformExpression` | a constant |
+| `template` | `transformExpression` | a Liquid template rendered against the source record |
+| `jsonata` / `ai` | — | recognised but not yet executed; reported as a per-field error |
+
+A single field's failure is collected and the rest continue (partial success) — it never
+aborts the whole record.
+
+---
+
+## Secrets (write-only)
+
+The secret store is **write-only from the client**: you can set, rotate, list (refs +
+masked hints + metadata) and delete — but a value never comes back over the API.
+
+```ts
+import { secrets, integrations } from '@proveanything/smartlinks'
+
+// 1. Store the destination credential — keep the returned ref.
+const { ref } = await secrets.set(collectionId, {
+  name: 'Acme API key',
+  purpose: 'integration',
+  value: 'sk_live_…',           // sent once; never retrievable
+})
+
+// list shows refs + masked hints only (safe to render)
+const { secrets: list } = await secrets.list(collectionId)
+// → [{ ref, name: 'Acme API key', hint: '…live_1a2b', purpose, createdAt, ... }]
+```
+
+---
+
+## Creating and running a flow
+
+```ts
+// 2. Create an outbound flow that pushes products to Acme, authed by the secret above.
+const flow = await integrations.createFlow(collectionId, {
+  appId: 'my-integration-app',
+  direction: 'outbound',
+  name: 'Push products to Acme',
+  status: 'active',
+  eventTypes: ['product.updated'],   // fire whenever a product changes
+  sourceEntity: 'product',
+  config: {
+    connection: {
+      baseUrl: 'https://api.acme.example',
+      sendEndpoint: '/v1/products',
+      auth: { method: 'api_key', headerName: 'X-API-Key', credentialRef: ref },
+    },
+    fieldMappings: [
+      { targetPath: 'sku',   sourcePath: 'sku',  transformType: 'direct' },
+      { targetPath: 'name',  sourcePath: 'name', transformType: 'direct' },
+      { targetPath: 'label', transformType: 'template', transformExpression: '{{name}} ({{sku}})' },
+    ],
+  },
+})
+
+// 3a. Test it now against one product — inline, returns a summary.
+const result = await integrations.runFlow(collectionId, flow.id, { entityId: 'P1045716' })
+if (integrations.isRunSummary(result)) {
+  console.log(result) // { records: 1, sent: 1, failed: 0, status: 'success' }
+}
+
+// 3b. Or enqueue on the worker (returns immediately).
+await integrations.runFlow(collectionId, flow.id, { entityId: 'P1045716', async: true })
+```
+
+Once `status: 'active'` with `eventTypes: ['product.updated']`, editing that product in the
+admin API fires the flow automatically — no manual run needed.
+
+---
+
+## Reference
+
+| Function | HTTP |
+|---|---|
+| `integrations.listFlows(collectionId, query?)` | `GET /integrations/flows` |
+| `integrations.createFlow(collectionId, input)` | `POST /integrations/flows` |
+| `integrations.getFlow(collectionId, id)` | `GET /integrations/flows/:id` |
+| `integrations.updateFlow(collectionId, id, input)` | `PUT /integrations/flows/:id` |
+| `integrations.deleteFlow(collectionId, id)` | `DELETE /integrations/flows/:id` |
+| `integrations.runFlow(collectionId, id, opts?)` | `POST /integrations/flows/:id/run` |
+| `secrets.list(collectionId, query?)` | `GET /secrets` |
+| `secrets.set(collectionId, input)` | `POST /secrets` |
+| `secrets.get(collectionId, ref)` | `GET /secrets/:ref` |
+| `secrets.rotate(collectionId, ref, input)` | `PUT /secrets/:ref` |
+| `secrets.remove(collectionId, ref)` | `DELETE /secrets/:ref` |

package/dist/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