From 62c4c69c2f1aae5068bf506d55998f63f744785a Mon Sep 17 00:00:00 2001 From: Ngo Quoc Dat Date: Wed, 11 Nov 2026 01:24:22 +0700 Subject: [PATCH] docs(features): masking for external callers and Claude Agent approvals --- developers/mcp-prompts.mdx | 2 ++ developers/mcp-resources.mdx | 2 +- developers/mcp-tools.mdx | 22 ++++++++++++++-- development/plugin-development.mdx | 2 +- features/ai-assistant.mdx | 4 ++- features/data-masking.mdx | 41 +++++++++++++++++++++++++++++- features/mcp.mdx | 3 ++- 7 files changed, 69 insertions(+), 7 deletions(-) diff --git a/developers/mcp-prompts.mdx b/developers/mcp-prompts.mdx index 452ab4b6..2bf0a793 100644 --- a/developers/mcp-prompts.mdx +++ b/developers/mcp-prompts.mdx @@ -134,6 +134,8 @@ Anything else returns an empty list rather than an error. `database`, `schema` and `table` need to know which connection to read. Pass it in `context.arguments` under `connection`, `connection_id`, or `id`. Without one, the result is empty. +They also need that connection approved for this client, and completion never asks. It reads the connection once the user has allowed this client at **Ask Once for Each Connection**, under **Never Ask**, or on a connection whose AI policy is **Always Allow**. Otherwise the result is empty. A forgotten or revoked approval applies from the next request. + For a `ref/resource` completion TablePro fills the context from the URI itself, so completing `table` in `tablepro://connections/{id}/tables/{table}` already knows the connection, and the `database` and `schema` query parameters if the URI carries them. Anything you pass in `context.arguments` wins. ### Matching and limits diff --git a/developers/mcp-resources.mdx b/developers/mcp-resources.mdx index 5aee6b2e..b066823c 100644 --- a/developers/mcp-resources.mdx +++ b/developers/mcp-resources.mdx @@ -140,7 +140,7 @@ This is the only subscribable resource. See [Subscriptions](/developers/mcp-subs } ``` -`executed_at` is ISO 8601. `schema_name` appears when the entry has one, and `error_message` when `was_successful` is false, redacted. +`executed_at` is ISO 8601. `schema_name` appears when the entry has one, and `error_message` when `was_successful` is false, redacted. On a connection with masking rules, `query` and `error_message` can hold a fixed sentence and `search` skips some entries: see [Masking rules](/developers/mcp-tools#masking-rules). ## Errors diff --git a/developers/mcp-tools.mdx b/developers/mcp-tools.mdx index b777c41b..094b03f2 100644 --- a/developers/mcp-tools.mdx +++ b/developers/mcp-tools.mdx @@ -15,7 +15,7 @@ In the tables below, required arguments come first and optional ones follow in p - The result comes back twice: as JSON text in `content[0]`, and as a typed object in `structuredContent`. Read `structuredContent`. - Timestamps are ISO 8601, error text is redacted, and "a result set" means `columns[]`, `rows[][]`, `row_count`, `rows_affected`, `execution_time_ms`, `is_truncated`, plus `status_message`, `database` and `schema` when they apply. -A column a [masking rule](/features/data-masking) matches comes back masked in every tool that returns rows, `browse_table`, `execute_query` and `export_data` included. The mask replaces the value in `rows[][]`; `columns[]` and `row_count` are unchanged. A filter or sort in the request still runs on the stored values. +A column a [masking rule](/features/data-masking) matches comes back masked in every tool that returns rows, `browse_table`, `execute_query` and `export_data` included. The mask replaces the value in `rows[][]`; `columns[]` and `row_count` are unchanged. A filter or sort in the request still runs on the stored values. A connection with rules also changes errors, plans and some text fields: see [Masking rules](#masking-rules). Row limits default to the server's **Default row limit** setting (500) and are capped by **Maximum row limit** (10,000). Timeouts default to **Query timeout** (30 seconds) and are capped at 300. Both live in **Settings > MCP**. @@ -41,12 +41,30 @@ Past the scope, a call clears three more gates: 2. **Connection policy.** **External Clients** set to **Blocked** hides the connection: `list_connections` omits it and any tool that names it is refused. An AI policy of **Never** does the same, except that [`purpose: "display"`](#listing-for-display) still lists it. Otherwise the first call that touches a connection asks the user, as often as **Settings > MCP > Approval** says. That question is always a dialog on the user's Mac, never an elicitation: a client that could answer it could also grant itself the connection. It has no deadline, so the client owns the timeout, and a refusal stands for 60 seconds before the question can be put again. 3. **Safe Mode.** A write goes through the connection's Safe Mode, which may ask the user to confirm it or to authenticate. See [Approvals](/developers/mcp-protocol#approvals-and-input-required). +`completion/complete` clears the same connection policy without asking: on a connection this client is not approved for, it completes nothing. See [Context matters](/developers/mcp-prompts#context-matters). + A call that opens a connection may also need approval on the Mac for a pre-connect script, environment variables, or [local sign-in credentials](/connections/connection-form#sign-ins-from-this-mac). A refusal returns `denied`; an unanswered prompt returns `timeout`. `confirm_destructive_operation` needs `admin` as well, so it takes a Full Access token, and **Read Only** refuses it outright whatever the token carries. No token skips the user's approval. **Read Only** refuses a statement classified as a write with `denied`. Reads also use the driver's read-only mode where supported. [What Read Only allows](/developers#what-read-only-allows) lists engine limits and the statements refused at every access level. Multiple statements return `invalid_argument`, except for SQL Server scripts sent to [`execute_query`](#execute_query) or [`confirm_destructive_operation`](#writing-data). +## Masking rules + +On a connection with [masking rules](/features/data-masking#masking-for-ai-and-scripts), PostgreSQL, MySQL, MariaDB and local SQLite mask a cell by the table column it reads, so an alias is masked too. A column that reads no column of a user table comes back masked whole, whatever its name, and `status_message` names it. On engines that cannot trace a column, that is every column of a query. Schema tools such as `describe_table` return the structure as usual. + +The rules also withhold text that can repeat a stored value: + +| Tool | On a connection with rules | +|------|----------------------------| +| A failed statement, in any tool that runs one | `query_failed`, with the error code and SQLSTATE when the driver reports them and the withheld-message sentence in place of the server's text. A failure before the driver takes the statement keeps its text | +| `explain_query` | The plan masked whole, `plan_text` and `plan` included, except on PostgreSQL and SQLite. `status_message` says why | +| `get_server_dashboard` | The withheld-statement sentence as the `query` of every session and slow query | +| `search_query_history`, the history resource | The withheld-message sentence as every `error_message`. An entry whose `source` is `row_edit` or `import` has the withheld-statement sentence as its `query`, and a search with text leaves it out | +| `browse_table`, `export_data` | A system table masked whole | + +The withheld-message sentence reads `The statement failed with error 1146, SQLSTATE 42S02. Its message is withheld because this connection has masking rules, and the message can repeat a masked value.`, without the codes when there are none. The withheld-statement sentence reads `The statement text is withheld because this connection has masking rules, and it can repeat a masked value.` + ## Connections | Tool | Arguments | Returns | @@ -163,7 +181,7 @@ On SQL Server, send the whole script instead. A variable exists only in the batc The top-level fields describe the first result set, with `rows_affected` counting the whole script. When the script returns more than one result set, `result_sets[]` lists every one in order, each with `columns`, `rows`, `row_count` and `is_truncated`. `max_rows` caps each result set on its own. `status_message` says when the script left a transaction open. -A batch that raises an error fails the call with the server's message and line number. The batches after it do not run, and the error says what stays applied. +A batch that raises an error fails the call with the server's message and line number. The batches after it do not run, and the error says what stays applied. On a connection with [masking rules](#masking-rules), the whole message is withheld. ### `explain_query` diff --git a/development/plugin-development.mdx b/development/plugin-development.mdx index 17a1c575..a0dd1519 100644 --- a/development/plugin-development.mdx +++ b/development/plugin-development.mdx @@ -13,7 +13,7 @@ A plugin is a macOS loadable bundle target with `WRAPPER_EXTENSION = tableplugin | Key | Type | Required | Purpose | |-----|------|----------|---------| -| `TableProPluginKitVersion` | integer | Yes | The PluginKit ABI the plugin was built against. Current value: 42 | +| `TableProPluginKitVersion` | integer | Yes | The PluginKit ABI the plugin was built against. Current value: 43 | | `TableProProvidesDatabaseTypeIds` | array of strings | Recommended | Database type IDs the plugin serves, which is what makes lazy loading possible | | `CFBundleShortVersionString` | string | Yes | Plugin version shown in **Settings > Extensions** | | `CFBundleVersion` | string | Yes | Build number. Of two copies of a plugin the higher build loads, and a registry update needs a higher build | diff --git a/features/ai-assistant.mdx b/features/ai-assistant.mdx index 194af070..32dca725 100644 --- a/features/ai-assistant.mdx +++ b/features/ai-assistant.mdx @@ -46,6 +46,8 @@ With no preference, start with Claude or OpenAI on an API key: both take a key, Install Claude Code, run `claude /login` in Terminal, then pick Opus, Sonnet, or Haiku. Replies bill against your Claude subscription instead of an API key. The provider answers from your schema when the MCP server is on in **Settings > MCP**, and falls back to plain chat when it is off. +Whatever the chat mode, its tools only read, and reach only the chat's connection: each reply runs on a [**Read Only**](/developers/tokens) MCP token limited to that connection. At **Ask Once for Each Connection** in **Settings > MCP**, one **Allow** covers every later reply on the connection until you click **Forget** on its **Claude Agent** row, or end its token with **Revoke**, **Delete** or **Disconnect** while a reply runs. + The `claude` tool runs headless here. Claude Code is built for you to use directly rather than as a backend for other apps, so this path can break with any Claude Code release. Your subscription is governed by Anthropic's [Consumer Terms](https://www.anthropic.com/legal/consumer-terms) and [Usage Policy](https://www.anthropic.com/legal/aup), which TablePro cannot grant rights under. Replies also count against the limits you share with claude.ai and your own Claude Code sessions, so running out here stops your work there. For a metered path on commercial terms, add the **Claude** provider with an API key. ## Apple Intelligence @@ -140,7 +142,7 @@ Start with **Review with AI** when you are unsure what to ask: it checks correct Query bar with the Review button, and the assistant answering a review of a JOIN -The request carries the structure of the tables the statement names, read from the tab's own database and schema: columns and types, keys, indexes with their predicates, foreign keys, and estimated row counts. Up to 12 tables go, in the order the statement names them. The chip above your message lists them; hover it to see any table that could not be read or was not found. If the tab already shows an EXPLAIN plan for the same statement, the plan goes too. Building this reads only the database's catalog: your statement never runs, and no rows are sent. Turn off **Include database schema** in **Settings > AI** to send the statement alone. +The request carries the structure of the tables the statement names, read from the tab's own database and schema: columns and types, keys, indexes with their predicates, foreign keys, and estimated row counts. Up to 12 tables go, in the order the statement names them. The chip above your message lists them; hover it to see any table that could not be read or was not found. If the tab already shows an EXPLAIN plan for the same statement, the plan goes too, unless [masking rules](/features/data-masking#on-a-connection-with-rules) hold it back. Building this reads only the database's catalog: your statement never runs, and no rows are sent. Turn off **Include database schema** in **Settings > AI** to send the statement alone. With no provider set up and Apple Intelligence off, the actions are dimmed. With Apple Intelligence on, they are dimmed while it cannot run, and the tooltip says why. With AI turned off, or on a connection whose AI policy is **Never**, they are hidden. diff --git a/features/data-masking.mdx b/features/data-masking.mdx index f8ad8e7b..1fc72502 100644 --- a/features/data-masking.mdx +++ b/features/data-masking.mdx @@ -56,6 +56,33 @@ One rule covers every place a value leaves TablePro: A query result has no source table for most engines, so a `table.column` rule matches a query result by its column name alone. `users.ssn` then also masks an `ssn` column a query reads from another table. +## Masking for AI and scripts + +Results for MCP clients, the AI assistant, Claude Agent, AppleScript and Shortcuts are masked by the table column each result column reads, as well as by its name. On PostgreSQL, MySQL, MariaDB and local SQLite, `SELECT email AS contact FROM users` comes back masked by a `*.email` rule. + +On a connection with at least one rule, a column that reads no column of a user table comes back as `••••`, whatever its name. The result's status message names the columns masked this way. That covers: + +- An expression or an aggregate, such as `lower(email)` or `count(*)`. +- A system table or catalog, such as `pg_stat_activity`, in a query, a browse or an export. Schema lookups such as `describe_table` still return the structure. +- Every column of a statement the driver does not trust: a subquery, a CTE or a `UNION` on MySQL and MariaDB, a compound `SELECT` or `VALUES` on SQLite. One of those words inside a value, such as a filter on `'union'`, counts too. + +These cannot trace a column: ClickHouse, Redis, CockroachDB, Redshift, TiDB, Databend, OceanBase, a SQLite [remote file](/connections/remote-database-files) opened **On the Server**, and every engine from the plugin registry. On a connection with rules, every column of a query on them comes back masked, and a browsed or exported table is matched by column name, as in the grid. + +### On a connection with rules + +The rules also withhold text that can repeat a stored value: + +| Where | What comes back | +|-------|-----------------| +| A statement that fails | The error code and SQLSTATE where the driver reports them, and a sentence saying the message is withheld | +| **Fix with AI** | The failed statement, without the server's message | +| A query plan | The plan masked whole, except PostgreSQL's and SQLite's. **Review with AI**, **Explain with AI** and **Optimize with AI** attach no plan on other engines | +| History entries the app wrote from row data, under **Row Edits** and **Imports** | A sentence in place of the statement. A history search with text leaves them out | +| The error of any history entry | A sentence in place of the message | +| Session and slow-query text from the server dashboard | A sentence in place of the statement | + +A refusal, a timeout or a cancel from TablePro itself keeps its text. + ## Editing and Reveal A grid that shows a masked column is read-only, since a mask cannot be written back or used to find its row. To see or edit the real values, right-click a masked column's header and choose **Reveal Masked Values…**. TablePro asks for Touch ID, or your macOS password on a Mac without it, and reloads the tab unmasked. A query tab whose statement is not a read reveals on its next run instead. @@ -67,5 +94,17 @@ Reveal lasts until the tab closes or opens another table. Other tabs, exports fr Masking hides values inside TablePro. It does not replace database permissions: anyone with the connection's credentials can read the data with another client. - Filters, sorts and `WHERE` clauses run on the server against the stored values, so a filter on a masked column finds the real matches. -- A rule matches the column name a result reports. A query that renames or computes the column, such as `SELECT email AS contact`, returns it unmasked, and that includes queries an MCP client or the AI assistant writes. A **Type** rule catches a renamed column that keeps its type. +- In the grid, a rule matches the column name a result reports. A query that renames or computes the column, such as `SELECT email AS contact`, shows it unmasked. A **Type** rule catches a renamed column that keeps its type. Results for AI and scripts are [masked by what each column reads](#masking-for-ai-and-scripts). - **Copy To**, copying objects to another database and Compare move the stored values, not the masks. +- The **Edit Document** sheet shows a stored document's fields without Reveal. Query plans, and the sessions and slow queries on the server dashboard, are not masked in the app. + +### Known limits for AI and scripts + +A client that may run SQL can still learn a masked value these ways: + +- A view, a generated column or a table copied with `CREATE TABLE … AS SELECT` holds the value under its own name. A rule that does not name that column leaves it unmasked, in the grid too. Making the copy is a write, which a **Read Only** token or connection refuses. +- `WHERE` and `ORDER BY` test a value without returning it, such as `WHERE email LIKE 'a%'`. Row counts and row order answer one guess at a time. +- How long a query takes, and whether it fails, can depend on a masked value. A client can probe both, even with the error text withheld. +- A statement a client or a person typed comes back as written, in history and in its own results. So do literals another session sent, wherever the database shows them outside the masked system views. +- On an engine that cannot trace columns, only the system databases and schemas the engine declares are masked whole, not system tables inside a user database. On a SQLite file opened **On the Server**, `sqlite_stat4` and a full-text table's `_content` copy show their columns as your rules name them. CockroachDB's `crdb_internal`, whose lock and contention views print index keys with their values, is not masked whole either. +- Column names are never masked. On MySQL, a client that may prepare statements can build a column name from a value with `PREPARE`. diff --git a/features/mcp.mdx b/features/mcp.mdx index b1b2ae9a..c7f7bb52 100644 --- a/features/mcp.mdx +++ b/features/mcp.mdx @@ -53,7 +53,8 @@ The first time a client reaches one of your connections, TablePro asks. **Approv Leave it at **Ask Once for Each Connection** unless a client runs unattended, in which case **Never Ask** stops the prompt from waiting for someone who is not there. Approvals already given are listed -underneath, each with **Forget**. +underneath, each with **Forget**. A row names the connection and the client it was given to: a +token's name, **Built-in CLI** for the bundled bridge, or [**Claude Agent**](/features/ai-assistant#claude-agent). Approval decides only whether you are asked. It grants nothing: a connection **Blocked** for external clients stays blocked, a **Read Only** one stays read only, a connection whose AI policy is