# Legal Document Snapshot Integration

This guide defines the 2.0 groundwork for legal-document consent flows such as terms and conditions, privacy policies, and DPAs.

## Goal

The client should be able to record acceptance for the exact document release the user saw without needing to know c15t's internal `policyId`.

That means the preferred client contract is:

1. A terms server renders or resolves the active legal document release.
2. The terms server issues a signed `documentSnapshotToken` for that release.
3. The client sends that token back when the user accepts or rejects the document.
4. c15t verifies the token and stores append-only consent evidence against the matching legal-document release.

## System Responsibilities

### Terms Server

The terms server is the source of truth for the document release that was shown to the user.

It is responsible for:

* resolving the current legal document release
* knowing the release metadata:
  * `type`
  * `hash`
  * `version`
  * `effectiveDate`
* minting a signed `documentSnapshotToken`
* returning the rendered document and token to the client

The terms server should own signing. c15t should not expose a production-safe browser helper that can mint these tokens because doing that would require shipping the signing key to the client.

### Client SDK / UI

The client should:

* render the document content from the terms server
* hold the `documentSnapshotToken` returned for that rendered release
* call c15t accept or reject primitives with that token when the user acts

The client may know `policyHash`, but it should not need to know `policyId`.

### c15t Backend

The c15t backend is responsible for:

* verifying the signed `documentSnapshotToken`
* extracting authoritative release metadata from the token
* resolving the matching legal-document policy row
* storing append-only consent evidence for the subject and document release

## Preferred Request Contract

For legal-document consent writes, the preferred lookup order is:

1. `documentSnapshotToken`
2. `policyHash`
3. `policyId` as a compatibility fallback only

`documentSnapshotToken` is the auditable path because it proves which release the user saw without forcing the client to understand c15t internals.

`policyHash` remains useful as a lightweight fallback for integrations that can identify the rendered document release but do not yet have a signing service.

`policyId` should not be the long-term client contract.

## Snapshot Token Claims

The signed token should carry enough metadata for c15t to verify and resolve the document release:

* `iss`: token issuer
* `aud`: intended c15t audience
* `sub`: release hash
* `tenantId`: tenant that owns the release, when applicable
* `type`: legal document type
* `version`: release version string
* `hash`: stable release hash
* `effectiveDate`: ISO timestamp for the effective date
* `iat`: issued-at timestamp
* `exp`: expiration timestamp

The current demo helper uses that shape so the wire contract is established now, even though real issuance should move to a dedicated server flow.

## Auditability and Compliance

For a fully auditable flow:

* the rendered release must be versioned
* the release must have stable metadata, especially `hash`
* acceptance must be append-only
* the evidence should tie the subject, action, time, and exact release together
* signed snapshot tokens should be issued by a trusted server, not the browser

This gives c15t a defensible record of what document release was accepted and when.

## What Ships in 2.0

This PR is groundwork, not the full terms-platform rollout.

Included now:

* token-first legal-document consent inputs in c15t
* `policyHash` fallback support
* an example terms demo that identifies the user first and then records acceptance
* a demo-only unsafe browser signer in `examples/demo` for local testing when no real terms server exists yet

Deferred until the next phase:

* a production terms server that owns rendering and token issuance
* automatic release resolution from a real document service
* signed snapshot delivery from server to client as part of document rendering

## Demo-Only Unsafe Signer

`examples/demo/lib/unsafe-demo-legal-document-snapshot.ts` exists only to let the example app exercise the contract before the real terms server lands.

It is intentionally unsafe for production use because it requires exposing a signing key to the browser bundle.

Use it only for local development or temporary internal demos.

## If You Already Have a Privacy Policy Without a Hash

That is not a blocker for 2.0 groundwork, but it is not the end state either.

Short term:

* you can continue using existing legal-document records
* `policyId` compatibility can still exist server-side
* `policyHash` fallback can be added once release hashing exists

Long term:

* every rendered legal-document release should have a stable hash
* the terms server should issue snapshot tokens using that hash

Without a stable release hash, the audit trail is weaker because the acceptance cannot be tied as precisely to the rendered document version.