Explanation: Context Token Architecture

The Problem

We need to give external "Mini-Apps" access to specific AuditSwarm data without:

1. Giving them full user credentials.
2. Requiring them to implement complex OAuth flows.
3. Exposing our internal database.

The Solution: Context Tokens

We use a Capability-based Security model. The "Context Token" acts as a temporary key that grants access to one specific artifact.

How it works

1. Generation: When a user clicks a link in AuditSwarm, we mint a short-lived JWT signed with our internal secret. This token says "The bearer of this token is allowed to read/write Artifact X for the next hour."
2. Transmission: We pass this token in the URL fragment to the mini-app.
3. Exchange: The mini-app sends the token back to us. We verify the signature. If valid, we return the data.

Lifecycle: Draft vs. Immutable

To ensure data integrity, we enforce a strict lifecycle:

1. Draft Mode:
   • While the artifact is "In Progress", the token allows generating Upload URLs for a drafts/ path.
   • The mini-app can overwrite files here freely.
2. Locked Mode:
   • When a human approves the artifact in AuditSwarm, it becomes Locked.
   • The file is moved to an immutable archives/ path.
   • The token will still allow reading the context, but any attempt to get an upload URL will fail (403).

This ensures that once a document is approved, the mini-app cannot secretly change it.