From 03008acdc9d89b337f85b42225063c4ca0a9d041 Mon Sep 17 00:00:00 2001 From: chrisjleal <184772742+chrisjleal@users.noreply.github.com> Date: Sat, 10 Oct 2026 13:34:14 -0500 Subject: [PATCH] docs(mcp): document signing and secret replacement flows --- mcp/secrets.mdx | 8 +++++--- mcp/tools.mdx | 8 +++++--- mcp/verify.mdx | 11 ++++++----- 3 files changed, 16 insertions(+), 11 deletions(-) diff --git a/mcp/secrets.mdx b/mcp/secrets.mdx index 053156b..612a745 100644 --- a/mcp/secrets.mdx +++ b/mcp/secrets.mdx @@ -10,7 +10,7 @@ Sign in first with OAuth or a server key ([Auth](./auth)). Use the signed-in pro | Tool | Purpose | | ---- | ------- | -| **`proofable_secret_create`** | Store a named secret as an encrypted proof | +| **`proofable_secret_create`** | Store or replace a named secret as an encrypted proof | | **`proofable_secret_list`** | List secret metadata (alias, qHash, type). No values | | **`proofable_secret_revoke`** | Revoke a secret proof by qHash | @@ -30,9 +30,11 @@ When signed in, **omit `walletAddress`**. Secrets bind to your profile account f | ----- | ----- | | `walletAddress` | Optional when signed in; must match the authenticated profile account if set | | `alias` | Letters, numbers, underscore; must start with a letter | -| `secretType` | `single` (default) or `bundle` (JSON object string in `content`) | +| `secretType` | `single` (default), `bundle` (key-value JSON), or `json` (one sealed JSON document) | | `content` | Secret value stored in Vault. Encrypted at rest; never echoed back via MCP | +Saving the same alias again creates a new proof and revokes its older live proof. The result lists revoked proof IDs in `superseded`. If revocation fails after the new save, the tool reports `secret_replacement_incomplete` with both proof IDs so you can retry or revoke the older one. + ## List (`proofable_secret_list`) ```json @@ -58,7 +60,7 @@ Requires authenticated ownership of the secret proof. Omit `walletAddress` when - Store secrets only through **`proofable_secret_create`**. Confirm the stored name and proof ID. Never print the value in chat. - Prefer OAuth or Profile keys in MCP config only. Do not use them in app browser bundles. -- Rotate or revoke through **`proofable_secret_revoke`** and re-create if a value is exposed. +- Rotate by saving the same alias again, or revoke through **`proofable_secret_revoke`** if a value is exposed. diff --git a/mcp/tools.mdx b/mcp/tools.mdx index 5970b89..b4484f0 100644 --- a/mcp/tools.mdx +++ b/mcp/tools.mdx @@ -12,13 +12,15 @@ Call **`proofable_context`** once, then pick the tool for the job. | List what you can verify | `proofable_verifiers_catalog` | Required inputs and supported networks. | | Reuse a proof | `proofable_proofs_check` | Read-only. Reports whether a current proof already satisfies the request. | | Finish what's missing | `proofable_verify_or_guide` | Reuses a proof, or returns the next step. | -| Create or refresh a proof | `proofable_verify` | Creates the proof when a new one is needed. | +| Create a proof in-session | `proofable_verify` | Creates the proof when the signed-in account can authorize it. | +| Prepare an outside signature | `proofable_verify_prepare` | Returns the exact signing string and timestamp; creates no proof. | +| Submit an outside signature | `proofable_verify_submit` | Creates the proof from a signed prepared check. | | Read a proof | `proofable_proofs_get` | Current proof records and status. | | Update or review a proof | `proofable_proofs_update` | Change title/tags, vote, or comment on the same proof. | | Create or import an agent | `proofable_agent_create` | Links the agent to your profile. Optional separate spend account and controls. Pass an existing account address for dedicated spend. | | Confirm the agent is ready | `proofable_agent_link` | Identity and the permissions that account needs. | | Load the agent | `proofable_agent_mount` | Identity, permissions, skills, and current settings. | -| Store a secret | `proofable_secret_create` | Encrypted Vault secret. | +| Store or replace a secret | `proofable_secret_create` | Encrypted Vault secret; the same alias replaces its prior value. | | List secrets | `proofable_secret_list` | Stored names and details. Never the secret itself. | | Revoke a secret | `proofable_secret_revoke` | Removes a stored secret by proof ID. | @@ -44,7 +46,7 @@ Pro adds only the four tools needed to run and manage jobs. Product connections, | Tool | Address field | Verifiers / filters | |------|---------------|---------------------| | `proofable_proofs_check` | `wallet` | `verifiers` | -| `proofable_verify`, `proofable_verify_or_guide` | `walletAddress` | `verifierIds` | +| `proofable_verify`, `proofable_verify_prepare`, `proofable_verify_submit`, `proofable_verify_or_guide` | `walletAddress` | `verifierIds` | | `proofable_proofs_get` | `identifier` | optional `tags` (comma-separated proof tags) | | `proofable_proofs_update` | `qHash` (proof ID) | optional metadata, `vote`, or `comment` | diff --git a/mcp/verify.mdx b/mcp/verify.mdx index b98127a..3db22cf 100644 --- a/mcp/verify.mdx +++ b/mcp/verify.mdx @@ -8,7 +8,9 @@ icon: circle-check Use **[`proofable_verify_or_guide`](./verify-or-guide)** as the normal trust path. It reuses a qualifying proof when one exists or returns the one next step needed to finish verification. -Use **`proofable_verify`** when the signed-in account can complete a known check in-session and a new proof is actually needed. Ownership checks finish here. Share a hosted link only when this tool returns one. +Use **`proofable_verify`** when the signed-in account can complete a known check in-session and a new proof is actually needed. Ownership checks finish here. + +When a separate signer is required, call **`proofable_verify_prepare`** to get the exact signing string, then **`proofable_verify_submit`** with its signature and original timestamp. Preparation does not create a proof. Use **`proofable_proofs_check`** only when the user explicitly needs a yes/no eligibility, gate, or access answer. @@ -22,8 +24,7 @@ When signed in, **omit `walletAddress`**. The tool uses your profile account fro | `walletAddress` | No | Omit when signed in; required only when acting for another account | | `data` | No | Check inputs (see each [check](../verification/verifiers)) | | `chain` | No | CAIP-2 chain when needed | -| `signature` | No | Provided in the finalize step | -| `signedTimestamp` | No | Provided in the finalize step | +| `signedTimestamp` | No | Optional timestamp for direct creation or preparation | | `options.returnUrl` | No | Where to send the user if a hosted step is needed | | `options.publishToHub` | No | Record the proof on the hub chain. Offchain by default. Does not change who can see the proof. | @@ -31,8 +32,8 @@ When signed in, **omit `walletAddress`**. The tool uses your profile account fro { "verifierIds": ["ownership-basic"], "data": { "content": "Hello Proofable" } } ``` -Signed-in sessions do not send `signature` or `signedTimestamp`. Those fields exist only when the session cannot authorize the account. +The direct tool does not ask for a signature. For a separate signer, pass the `walletAddress`, `verifierIds`, `data`, and `chain` used in preparation to `proofable_verify_submit`, together with the returned `signedTimestamp` and the signature over `signerString`. ## Output -A plain-language **Passed**, **Action needed**, or **Blocked** result. On success, the tool also returns the proof ID in `qHash` for your server. A hosted link appears only when the check needs an outside step. +A plain-language **Passed**, **Action needed**, or **Blocked** result. On success, the tool also returns the proof ID in `qHash` for your server. `proofable_verify_prepare` returns signing details or a hosted fallback for an outside step.