Merge pull request #189 from Open-Document-Alliance/codex/lumin-public-workflow-20260905

Expose consent-gated Lumin signing workflow

Author: silverstein

AGENTS.md

@@ -16,7 +16,7 @@ separate example to locate.
 ### Tools currently shipped
 This is the complete registered set, not a selection.
 
-- `display_pdf`, `list_pdfs`, `read_pdf_fields`, `fill_pdf`, `bulk_fill_from_csv`, `save_profile`, `load_profile`, `list_profiles`, `fill_with_profile`, `extract_to_csv`, `validate_pdf`, `read_pdf_content`, `read_pdf_pages`, `read_pdf_layout`, `search_pdf_text`, `convert_pdf_to_markdown`, `verify_table_proposal`, `get_pdf_identity`, `get_pdf_info`, `get_page_analysis`, `inspect_pdf_accessibility`, `compare_pdfs`, `render_pdf_page`, `render_pdf_region`, `fetch_pdf_from_url`, `merge_pdfs`, `split_pdf`, `rotate_pdf_pages`, `reorder_pdf_pages`, `apply_page_plan`, `create_signature`, `list_signatures`, `load_signature`, `detect_signature_zones`, `add_signature_field`, `prepare_signing_packet`, `apply_signature`, `apply_text`, `get_active_document`, `set_active_document`, `get_allowed_directories`, `get_pdf_resource_uri`, `create_extraction_workspace`, `inspect_extraction_state`, `read_extraction_workspace`, `read_extraction_chunk`, `submit_extraction_proposal`, `verify_extraction_proposal`, `delete_extraction_workspace`, `reveal_in_finder`, `read_pdf_bytes` (app-only).
+- `display_pdf`, `list_pdfs`, `read_pdf_fields`, `fill_pdf`, `bulk_fill_from_csv`, `save_profile`, `load_profile`, `list_profiles`, `fill_with_profile`, `extract_to_csv`, `validate_pdf`, `read_pdf_content`, `read_pdf_pages`, `read_pdf_layout`, `search_pdf_text`, `convert_pdf_to_markdown`, `verify_table_proposal`, `get_pdf_identity`, `get_pdf_info`, `get_page_analysis`, `inspect_pdf_accessibility`, `compare_pdfs`, `render_pdf_page`, `render_pdf_region`, `fetch_pdf_from_url`, `merge_pdfs`, `split_pdf`, `rotate_pdf_pages`, `reorder_pdf_pages`, `apply_page_plan`, `create_signature`, `list_signatures`, `load_signature`, `detect_signature_zones`, `add_signature_field`, `prepare_signing_packet`, `apply_signature`, `apply_text`, `start_lumin_authorization`, `finish_lumin_authorization`, `prepare_lumin_request`, `send_lumin_request`, `check_lumin_status`, `download_lumin_artifact`, `get_active_document`, `set_active_document`, `get_allowed_directories`, `get_pdf_resource_uri`, `create_extraction_workspace`, `inspect_extraction_state`, `read_extraction_workspace`, `read_extraction_chunk`, `submit_extraction_proposal`, `verify_extraction_proposal`, `delete_extraction_workspace`, `reveal_in_finder`, `read_pdf_bytes` (app-only).
 
 `get_pdf_info` returns bounded source-bound observations. Widget annotations
 belong to form fields; ordinary annotations remain separate and their targets

CLAUDE.md

@@ -412,15 +412,17 @@ future local OCR engine is optional planned work, not a current capability.
 The signature tools implement a **two-tier model** agreed with Max Ferguson on 2026-04-09:
 
 - **Tier 1 (this repo, local, free)**: Visible stamp via pdf-lib. `apply_signature` stamps a saved signature + writes an audit trail to PDF metadata. NOT legally-binding. NOT cryptographic.
-- **Tier 2 (Lumin API handoff, future)**: Cryptographic signing with timestamp and certificate. `request_lumin_signature` will route prepared packets to Lumin.
+- **Tier 2 (optional Lumin API handoff)**: The six `*_lumin_*` workflow tools connect a public PKCE client, preview an exact prepared packet, send one confirmed request without automatic retry, poll status, and download a completed artifact. The PDF and listed recipient details leave the device only at the confirmed send step. Lumin, not PDF Tools, provides the remote signing service and its completion certificate.
 
 **Human-intent constraint** (critical): `apply_signature` requires `user_intent_statement` + `user_confirmed_at` (ISO-8601, within last 24h). This is a legal requirement per Max: *"there's gotta be intent. Having the agent just kind of go and stamp signatures on a document without someone telling it to is not really allowed."* Agents MUST obtain these from the user and never fabricate. The validation enforces length/recency sanity checks; the intent is stored in PDF Keywords metadata for audit.
 
 **Coordinate system**: All signature tools use **top-left origin** (x from left, y from top) in PDF points (72pt = 1 inch). Internally converted to pdf-lib's bottom-left — agents/users never need to think about it.
 
 **Agent-safe vs human-gated split**:
 - Agent-safe (no intent check): `create_signature`, `list_signatures`, `add_signature_field`, `prepare_signing_packet`
-- Human-gated (requires intent): `apply_signature` only
+- Human-gated (requires intent): `apply_signature` and `send_lumin_request`. The
+  Lumin send tool validates exact recent confirmation values, but the host and
+  agent remain responsible for passing only values the user actually supplied.
 
 ## Code Standards
 

README.md

@@ -56,7 +56,7 @@ Claude already knows how to read PDFs in limited ways. PDF Tools goes much furth
 
 - **Interactive viewer:** page navigation, zoom, search, fullscreen, text selection, and form-field sidebar
 - **Form workflows:** `fill_pdf`, `read_pdf_fields`, `bulk_fill_from_csv`, and reusable profiles
-- **Sign mode:** signature/date zone detection, saved or drawn local signatures, text stamping, inspect-region, and preview-to-zone flows
+- **Sign mode:** signature/date zone detection, saved or drawn local signatures, text stamping, inspect-region, preview-to-zone flows, and optional consent-gated Lumin e-signing
 - **URL-to-PDF workflows:** fetch HTTP(S) PDF links to the local machine when sandboxed web fetches are blocked
 - **Page organization:** merge, split, rotate, reorder, and apply full page plans in one pass
 - **Extraction and analysis:** page-bounded reads, text search, page/region rendering, CSV export, page-level analysis, metadata, and validation
@@ -99,6 +99,37 @@ content, so the complete workflow is not necessarily zero egress.
 - Inspect a region, preview it, and turn it into a typed signing zone when automatic detection is not enough
 - Prepare a provider-neutral handoff receipt that binds the exact local input/output, typed zones, participant roles, page geometry, and unresolved inputs without contacting a signing provider
 - Keep signing edits local, with active-document tracking and backup behavior for same-file mutations
+- Optionally connect a Lumin account with browser-based PKCE, preview the exact recipients and disclosure locally, and send the prepared PDF only after the user confirms the exact sending statement
+- Check an existing Lumin request by polling and download an agreement or completion certificate without exposing the temporary signed URL or replacing an existing local file
+
+### Optional Lumin e-signing
+
+Lumin e-signing is an explicit external workflow. The rest of PDF Tools stays
+local-first. PDF Tools contacts Lumin only when a Lumin tool is called. Sending
+requires a provider-ready `prepare_signing_packet` receipt, a local preview, a
+connected Lumin session, and the user's fresh verbatim confirmation. The
+prepared PDF plus listed names and email addresses then leave the device and are
+handled by Lumin.
+
+PDF Tools can validate the exact confirmation text and its freshness, but it
+cannot independently prove who typed it. The MCP host must present the
+destructive tool action, and the agent must pass only the user's actual words
+and time. Agents must never fabricate either value.
+
+Configure a public OAuth client ID in the extension's **Lumin OAuth Client ID**
+setting. Other stdio hosts may set `LUMIN_OAUTH_CLIENT_ID`; Agent Plugin users
+may set `luminOAuthClientId` in the plugin's private `config.json`. Register the
+exact redirect URI `http://127.0.0.1/callback`. The OAuth access token stays only
+in the running PDF Tools process. It is not returned, logged, or written to
+disk, and a restart requires connecting again.
+
+The create call is one-shot and has no automatic retry. If the provider outcome
+is uncertain, PDF Tools preserves that uncertainty and will not create another
+request under the same authority. Status polling is the current desktop path.
+Lumin app webhooks require a private server app and are not part of this public
+PKCE workflow. The durable signing-operation store currently supports macOS and
+Linux. The public Lumin workflow fails closed on Windows until a reviewed
+ACL-aware state adapter exists.
 
 ### Page Organization Tools
 
@@ -229,6 +260,12 @@ the `.mcpb` manifest that ordinary model workflows discover.
 - `detect_signature_zones`
 - `add_signature_field`
 - `prepare_signing_packet`
+- `start_lumin_authorization`
+- `finish_lumin_authorization`
+- `prepare_lumin_request`
+- `send_lumin_request`
+- `check_lumin_status`
+- `download_lumin_artifact`
 - `create_signature`
 - `list_signatures`
 - `load_signature`

docs/MAINTAINERS.md

@@ -70,16 +70,19 @@ host and operating system being claimed.
 - PDF.js text extraction and canvas-backed page/region rendering are lazy loaded to avoid startup overhead.
 - Interactive viewer UI lives in `ui/`, built to `dist-ui/` via Vite.
 
-### Lumin signing preparation
+### Optional Lumin signing workflow
 
 `server/lumin-oauth-loopback.js` is an internal native-app OAuth helper.
 `server/lumin-sign-v1-mapper.js` validates and maps the narrow request shape,
 `server/lumin-sign-v1-transport.js` can execute one explicitly authorized
 direct-PDF request through an injected transport, and
 `server/lumin-sign-v1-operation.js` adds the private durable operation boundary.
-All four are packaged for source parity, but none is registered as an MCP tool
-or runs merely because the server starts. The mapper itself continues to return
-`transport_allowed: false`.
+`server/lumin-signing-tools.js` is the public orchestration layer. It registers
+six tools for browser authorization, local request preparation, one-shot send,
+status polling, and artifact download. None runs merely because the server
+starts. The mapper itself continues to return `transport_allowed: false`; only
+the public layer's fresh exact confirmation can construct the short-lived
+authority consumed by the durable wrapper.
 Calling the transport requires a separate, short-lived authority object that
 binds the exact prepared-PDF receipt, PDF digest, complete validated request
 mapping, mapper contract, and participant identities. The low-level transport
@@ -131,10 +134,10 @@ would require a separately approved server integration and signing-secret
 custody boundary.
 
 Portable Node cannot verify the required private Windows ACL or open NTFS
-directories for `fsync`. The durable wrapper therefore fails closed on Windows
-until a separately reviewed ACL-aware state adapter exists. This does not limit
-the existing cross-platform PDF tools because the Lumin modules remain internal
-and unregistered.
+directories for `fsync`. The public Lumin workflow therefore fails closed on
+Windows before OAuth or operation state begins, until a separately reviewed
+ACL-aware state adapter exists. The existing local PDF tools remain
+cross-platform.
 
 Lumin currently registers `http://127.0.0.1/callback` for public PKCE clients
 and ignores the loopback port when matching the redirect. At authorization
@@ -146,9 +149,10 @@ non-loopback listener, or a custom URI scheme without new provider evidence.
 The OAuth helper uses PKCE S256, a separate random state value, a one-use callback,
 strict callback parameter and Host validation, bounded inputs and responses,
 and a public-client token exchange with no client secret. It never writes or
-logs the verifier, authorization code, or returned tokens. Credential storage,
-refresh, revocation, callback verification, and provider artifact handling are
-separate incomplete product boundaries.
+logs the verifier, authorization code, or returned tokens. The public layer
+holds only the access token in process memory behind an opaque session ID,
+discards the refresh token, and requires a new browser connection after restart
+or expiry. Inputs, results, local operation state, and errors contain no token.
 
 The direct-PDF transport is pinned to Lumin's exact multipart example at Git
 commit `cd8ddd73e32c016038691dad21d0e4594c8eeebb`. It accepts an access token only
@@ -168,11 +172,11 @@ publishes a new snapshot, fetch it to a temporary path, run
 projected change, then replace the fixture and pinned identity together. Do not
 refresh the fixture or projection from the network during CI.
 
-This remains an internal vertical slice, not a shipped signing feature. There is
-no public tool, token store, callback listener, cancellation path, artifact
-download transaction, or release claim. The caller still owns secure state-root
-selection, OAuth token custody, webhook endpoint hosting, signing-secret custody,
-retention, and user-visible consent. The filesystem design assumes a trusted
+This is a source-complete public MCP workflow but not a released capability until
+its release gate is separately approved. It has no cancellation tool and no
+webhook endpoint. The public layer owns private state-root selection, ephemeral
+OAuth token custody, user-visible disclosure, exact confirmation, polling, and
+no-overwrite artifact download. The filesystem design assumes a trusted
 same-user and administrator boundary; it prevents accidental and concurrent
 reuse but is not a cryptographic defense against a hostile process with the same
 OS authority. Tests inject fake transports and must not make a live Lumin
@@ -389,7 +393,7 @@ mcp__<display_name, spaces underscored, non [A-Za-z0-9_-] stripped>__<tool_name>
 Identifiers over **64 characters** fail in the host. This shipped as a real
 defect (issue #44): the original benefit-led directory title
 `PDF Tools - Fill, Sign, Merge, Split, Extract` normalizes to 41 characters and
-pushes 23 of the current 50 packed tool identifiers past the ceiling.
+pushes 29 of the current 56 packed tool identifiers past the ceiling.
 
 The naming strategy is therefore **dual**:
 
@@ -405,7 +409,7 @@ Budgets are computed by `scripts/tool-identifier-budget.mjs` and gated in
 
 - `PDF Tools`: longest identifier 43, headroom 21
 - `PDF Tools: Fill, Sign & Edit`: longest identifier 59, headroom 5
-- Original long title: longest identifier 75, 23 identifiers over the limit
+- Original long title: longest identifier 75, 29 identifiers over the limit
 
 **The trap when adding a tool.** The shipped short brand has generous headroom,
 so a new long tool name will not break it and every host-facing check stays

docs/MCP_CONTRACT.md

@@ -27,7 +27,7 @@ template discovery is also unsupported and deterministically returns JSON-RPC
 
 ### Tools
 
-The runtime returns 51 uniquely named tools. Every tool has an object input
+The runtime returns 57 uniquely named tools. Every tool has an object input
 schema plus `title`, `readOnlyHint`, `destructiveHint`, `idempotentHint`, and
 `openWorldHint` annotations. Annotations are user-interface hints, never an
 authorization boundary; path allowlists and signature-intent checks remain the
@@ -36,7 +36,7 @@ every tool in both runtime copies. The handler evidence and classification
 rules are recorded in
 [`TOOL_ANNOTATION_AUDIT_2026-07-21.md`](TOOL_ANNOTATION_AUDIT_2026-07-21.md).
 
-The source manifest lists all 51 tools. The packed MCPB manifest lists the 50
+The source manifest lists all 57 tools. The packed MCPB manifest lists the 56
 normal model-workflow tools and omits `read_pdf_bytes`, whose runtime metadata
 marks it `ui.visibility: ["app"]`. `tools_generated: true` explicitly tells MCPB
 hosts that runtime discovery includes an additional tool. That visibility hint
@@ -53,7 +53,7 @@ Tools path policy. Consequently the active folder list is defense in depth, not
 a source-confidentiality boundary against a Full Access host. Content returned
 through MCP remains subject to the host and model provider's data terms.
 
-Forty-seven tool handlers advertise strict `outputSchema` contracts and return
+Fifty-three tool handlers advertise strict `outputSchema` contracts and return
 `structuredContent`. They also return a human-readable `content` text block so
 non-Apps and older clients remain usable. Successful structured output is
 validated before it leaves the server, with separate generic and tool-specific
@@ -85,7 +85,7 @@ exact-output-identity preconditions. New evaluation suites must bind v3
 explicitly. The grader selects the allowlisted contract and trust registry
 declared by each suite, so historical evidence remains valid under its original
 stack and is not silently rescored. The six existing trajectory jobs do not
-constitute behavioral trajectory coverage of all 51 tools.
+constitute behavioral trajectory coverage of all 57 tools.
 `get_pdf_identity` is covered by its contract, handler, filesystem-race, and
 agent-workflow tests rather than by those six retained jobs.