docs(proposals): add real human consent proposal

[jpage-godaddy]

Summary

• Proposes a shared ConfirmationAPI/ConfirmationUI mechanism for guaranteeing real human consent (T&Cs acceptance, purchase confirmation, other high-risk operations) rather than relying on LLM agent prompting alone.
• Defines the core concepts (ConfirmationRequest, Agreement, ConfirmationSeeker, ConfirmationAPI, ConfirmationUI), their fields, and the separation of OAuth-based agent access from IDP-based human access.
• Includes diagrams: an actor/interface diagram, a Status lifecycle state diagram, and sequence diagrams for the approval path and the reject/cancel/expire paths.
• Documents rejected alternatives (OS-level popups, relying on agent prompting).

Refined during review

Copilot's review surfaced several real gaps beyond the initial draft, addressed in this PR:

• CustomerID/SeekerID must be bound to the caller's authenticated identity, not merely asserted, for both creation and status/cancel calls.
• Approval must be bound to a specific operation (immutable identifier/digest), and treated as single-use via a mandatory atomic claim - both at approval-consumption time and at request-creation time (idempotent create) - so retries or concurrent pollers can't execute an approved operation twice.
• Status transitions (including expiry) must be an atomic compare-and-set, not a blind write.
• TERMS_AND_CONDITIONS agreement data must capture an immutable snapshot/hash of what was accepted, not just a live URL.
• ConfirmationUI needs a documented read operation, must treat seeker-supplied content as untrusted (XSS), and must have CSRF and clickjacking (framing) protection.
• The "only direct human interaction" claim is scoped to "IDP-authenticated as the customer" rather than proof of live human presence, which is called out as future work.

Two further refinements on the atomicity/idempotency theme (making the lazy expiry-on-read update itself conditional/atomic, and showing the seeker invoking the atomic claim in the approval flow) were raised in a final review round and are left open for human review rather than folded in automatically - see PR comments.

Test plan

• Docs-only change; no build/test required
• Mermaid diagrams render correctly in GitHub's markdown preview

🤖 Generated with Claude Code

[Copilot]

Copilot review overview

🟡 Changes recommended

Critical and moderate issues remain in authorization, operation binding, state transitions, and consent guarantees.

Review effort: Lite
Findings: 4 · 4 · 1

Open (9)

• CustomerID is not bound to the authenticated principal · New
• SeekerID does not identify the authorized customer account · New
• Approval is not bound to the executed operation · New
• Lifecycle transitions lack atomic compare-and-set protection · New
• Expiry transition is undocumented and unenforced · New
• Live terms URL does not preserve accepted content · New
• ConfirmationUI lacks documented access to retrieve confirmation details · New
• Browser authentication does not prove human presence · New
• Fix grammatical error in “where in a customer can” · New

What changed in this PR

This docs-only PR proposes a shared human-consent API/UI workflow for high-risk operations.

Changes:

• Defines confirmation entities, actors, authentication boundaries, and lifecycle states.
• Documents approval, rejection, cancellation, and expiration flows.
• Adds Mermaid diagrams and rejected alternatives.

File	Description
docs/​proposals/​consent.md	Documents the proposed consent model, API contract, UI responsibilities, and workflows.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟡 Changes recommended

Address the unresolved security, expiration, single-use, and consent-scope concerns.

Review effort: Lite
Findings: 1

Open (1)

• Untrusted rendered inputs can enable HTML or script injection · New

Resolved since last review (9)

• Lifecycle transitions lack atomic compare-and-set protection
• Approval is not bound to the executed operation
• SeekerID does not identify the authorized customer account
• CustomerID is not bound to the authenticated principal
• Browser authentication does not prove human presence
• ConfirmationUI lacks documented access to retrieve confirmation details
• Live terms URL does not preserve accepted content
• Expiry transition is undocumented and unenforced
• Fix grammatical error in “where in a customer can”

Previously missed (1)

In code that hasn't changed since last review

Missing CSRF protection on state-changing confirmation requests

docs/​proposals/​consent.md:118

Because ConfirmationUI is an HTML page acting with an IDP-authenticated customer session, a third-party site could forge the approve/reject POST if the session is cookie-based. That would allow a confirmation to be recorded without the customer intentionally interacting with this UI, so the proposal should require CSRF protection (for example, an anti-CSRF token plus Origin/Referer validation, with appropriate cookie settings) on these state-changing calls.

[jpage-godaddy]

Fixed in 417eace (addressing the 'Previously missed' CSRF finding, which has no separate review thread to resolve): added a requirement that the approve/reject call be protected with anti-CSRF measures (anti-CSRF token + Origin/Referer validation) so a third-party site can't forge an approval/rejection on the customer's authenticated session.

[Copilot]

Copilot review overview

🟡 Changes recommended

Unresolved critical authorization and approval-consumption issues, plus an expiration race, block approval.

Review effort: Lite
Findings: 2

Open (2)

• Approval status can be reused for duplicate operations · New
• API does not verify requester identity matches customer · New

Resolved since last review (1)

• Untrusted rendered inputs can enable HTML or script injection

[Copilot]

Copilot review overview

🟡 Changes recommended

Address the critical expiration race and enforce atomic duplicate-execution protection.

Review effort: Lite
Findings: 2

Open (2)

• Enforce expiration atomically during approval and rejection · New
• Require atomic idempotency enforcement for approved operations · New

Resolved since last review (2)

• API does not verify requester identity matches customer
• Approval status can be reused for duplicate operations

[Copilot]

Copilot review overview

🟡 Changes recommended

Unresolved idempotency and atomic audit requirements must be addressed, and the consent terminology should be clarified.

Review effort: Lite
Findings: 1

Open (1)

• Prevent duplicate confirmation tokens for one operation · New

Resolved since last review (2)

• Require atomic idempotency enforcement for approved operations
• Enforce expiration atomically during approval and rejection

[Copilot]

Copilot review overview

🟡 Changes recommended

Critical security and concurrency requirements remain unresolved.

Review effort: Lite
Findings: 1

Open (1)

• Add clickjacking protection to the ConfirmationUI · New

Resolved since last review (1)

• Prevent duplicate confirmation tokens for one operation

[Copilot]

Copilot review overview

🟡 Changes recommended

Unresolved critical atomicity issues and an idempotency-scope issue must be addressed.

Review effort: Lite
Findings: 2

Open (2)

• Make lazy expiry updates conditional and race-safe · New
• Define atomic claim before approved purchase execution · New

Resolved since last review (1)

• Add clickjacking protection to the ConfirmationUI

[jpage-godaddy]

Stopping the automated Copilot review loop here per author decision, after 7 rounds. Six rounds surfaced genuine, progressively-deeper concurrency/security requirements that were fixed (CustomerID/SeekerID authorization binding, operation binding, atomic status transitions, expiry-atomicity, idempotent approval consumption, idempotent creation, clickjacking protection). This final round raised two more in the same vein that are left open for human review rather than auto-fixed:

• Make lazy expiry updates conditional and race-safe - the lazy expiry-on-read persist should itself be a conditional/atomic update, not a blind write.
• Define atomic claim before approved purchase execution - the proposal mandates a one-time claim step but the documented API operations and flow never show the seeker invoking it before executing.

Both are legitimate refinements of points already in the doc, but the review has reached a point of diminishing, increasingly implementation-level returns for what is meant to be a design proposal rather than a full spec. CI is green (cicd, Analyze, Conventional commit, drift all passing).

[mguerrero3-godaddy]

I like this idea a lot. Been reading this for a while and wanted to leave some ideas/questions. Most of them out of curiosity but others are related to the design:

1. This is future-idea but a hook/event handling from cli -> developer portal mobile app could resolve the push notifications. Something similar to claude /remote which gives the notification of an approval needed for an agent on the app.
2. Security wise I think the expiration is strong, but It'll be good to also consider having a max number of open confirmations, otherwise a really elaborate (but plausible) scenario could spam tons of "similar" confirmations so the human behind can fall in "this kind of looks like It?" and confirm. Similar to MFA spam attacks.
3. Curious on If reseller or teams account use the cli how would confirmation delegation work in that case or If that's going to be even an option?
4. Unsure If this could be a valid scenario, but in the case there's several confirmations needed for an action (something requiring T&C and pay in a single go) I see fit a multi-step confirmation where these 'perms' can be checked and then confirmed.
5. I know the doc is not meant to cover that but curious on If there's a base idea on how the AuditData would be handled? I think some of that is PII
6. One extending idea (which could be already inferred from the doc) is that a confirmation should be immutable once created and pending (And I think through the whole process), so there's no way to mid-catch and modify It somehow before approval (approving something that changed on the fly)