AI Consent Developer Guide

PATENT PENDING — Ma'atara Protocol.

Public integration contract reviewed: 21 September 2026.

The AI Consent service publishes cryptographically attributable AI-use preferences for opaque content identifiers. It is a metadata and evidence service: referenced content stays at the endpoint, and preference signals neither force recipients to comply nor create legal rights by themselves.

Current boundary

Public reads deliberately expose signed preference evidence. Private keys, plaintext content, titles, tags, filenames, and note bodies are outside this service boundary.

Standards profile

IETF AI-Pref

The service implements the AI-Pref vocabulary draft revision 06. This is a versioned draft projection, not a claim to track the latest revision automatically:

Example:

train-ai=n, search=y

Ma'atara records may retain generative_ai_training, automated_processing, or conditional in the signed JSON record. Those are Ma'atara record fields and are not emitted as retired or invented AI-Pref wire tokens. Unknown or non-draft tokens are ignored when parsing the IETF projection.

/.well-known/ai-consent, the Aegis comment in robots.txt, and X-Robots-Tag: noai are product discovery conventions. They are not presented as IETF-standard attachment mechanisms.

TDMRep

/.well-known/tdmrep.json follows the TDMRep Final Community Group Report:

[
  {
    "location": "/",
    "tdm-reservation": 1
  }
]

tdm-policy is optional and is omitted until Ma'atara publishes a conforming, dereferenceable policy document. TDMRep is a W3C Community Group report, not a W3C Recommendation, and its signal is a rights reservation rather than a technical access control.

API

Production base URL: https://consent.maatara.io.

Public reads

The identifier is an exact opaque string of 16–256 characters. Ma'atara products use SHA3-384 over the agreed source bytes; callers must agree on byte encoding and normalization because the service does not recompute content hashes.

curl https://consent.maatara.io/api/v1/consent/<sha3-384-content-hash>

Create

Use proto.jcsCanonicalize from an initialized @maatara/pqc-toolkit for the public consent request contract. @maatara/worker-utils is private and is not an external npm dependency:

const message = proto.jcsCanonicalize({
  content_hash: contentHash,
  preferences: {
    ai_training: 'disallow',
    search: 'allow',
  },
  creator_did: creatorDid,
});

Sign the base64url encoding of the message's UTF-8 bytes with the acting ML-DSA-65 secret in endpoint memory. Send the base64url signature in X-Aegis-Signature:

POST /api/v1/consent
Content-Type: application/json
X-Aegis-Signature: <base64url-ml-dsa-65-signature>

{
  "content_hash": "<sha3-384-content-hash>",
  "creator_did": "did:maatara:<canonical-fingerprint>",
  "public_key_b64u": "<acting-ml-dsa-65-public-key>",
  "preferences": {
    "ai_training": "disallow",
    "search": "allow"
  }
}

The Worker verifies that public_key_b64u is entitled to speak for creator_did and verifies the signature with that exact key. It never accepts an anonymous or signature-only write.

Update

PUT /api/v1/consent/:hash accepts:

{
  "public_key_b64u": "<acting-ml-dsa-65-public-key>",
  "preferences": {
    "ai_training": "allow"
  }
}

Use the same SDK canonicalization call as create with {content_hash, preferences, creator_did}. Obtain creator_did from the existing native record; do not substitute an unverified caller-supplied owner.

Delete

DELETE /api/v1/consent/:hash requires a JSON body containing public_key_b64u. The canonical signed object is {content_hash, action: "delete", creator_did}. Deletion requires both key-to-DID authority and a valid signature.

Error contract

Integration rules

• Hash content and sign at the endpoint. Never send plaintext content merely to obtain a consent identifier.
• Mint or load the user's acting key only in the approved endpoint custody boundary; never persist a bearer assertion or raw private key.
• Use shared canonical JSON. Property insertion order and ordinary JSON.stringify are not signature protocols.
• Treat absent records as unknown, not as permission.
• Treat AI-Pref and TDMRep signals as discoverable evidence whose legal and operational effect must be evaluated independently.
• Do not mutate ownerless historical rows through the live Worker. Temporary legacy healing is retired (HTTP 410); contact support for a current-authority remediation path without uploading content or keys.

Verification

Read back the published preference and verify its attribution through the supported verifier. A successful write records a preference; it does not prove a crawler will comply. Use Testing for package loading and endpoint integration checks.