@seatable/mcp-seatable 1.5.1 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/.env.example CHANGED
@@ -6,9 +6,28 @@ SEATABLE_MOCK=
6
6
  # Server mode: selfhosted (default) or managed (multi-tenant HTTP with per-client auth)
7
7
  SEATABLE_MODE=selfhosted
8
8
 
9
+ # Required in managed mode (min. 32 chars). Seals the OAuth access/refresh tokens and
10
+ # client registrations the server issues, so the raw SeaTable API token is never handed
11
+ # to a client. Must stay stable across restarts: generate with `openssl rand -hex 32`.
12
+ # SEATABLE_TOKEN_SECRET=
13
+
9
14
  # Multi-base mode (selfhosted only): serve multiple bases from one process.
10
15
  # JSON array with base_name and api_token. Use instead of SEATABLE_API_TOKEN.
11
16
  # SEATABLE_BASES='[{"base_name":"CRM","api_token":"token_abc"},{"base_name":"Projects","api_token":"token_def"}]'
12
17
 
13
18
  # CORS: comma-separated list of allowed origins (HTTP mode only). If empty, CORS is disabled.
14
19
  # CORS_ALLOWED_ORIGINS=https://cloud.seatable.io,https://seatable-demo.de,http://localhost:3000
20
+
21
+ # OAuth (managed mode only): comma-separated hosts whose https callbacks are shown
22
+ # without the "unknown destination" confirmation step. Loopback addresses and
23
+ # private-use app schemes (cursor://, vscode://, ...) never need an entry — the
24
+ # code stays on the user's machine. Unknown https hosts still work; the user just
25
+ # has to confirm the destination first. Unset = the built-in list of hosted MCP
26
+ # clients. A single '*' disables the confirmation entirely (not recommended).
27
+ # SEATABLE_OAUTH_TRUSTED_REDIRECT_HOSTS=claude.ai,claude.com,chatgpt.com
28
+
29
+ # Lifetime of an issued OAuth access token, in seconds (default 3600, range 30..2592000).
30
+ # Lower it to narrow the window after a SeaTable token is revoked; raise it if real
31
+ # clients renew badly and would otherwise re-prompt their users. Useful for testing:
32
+ # set it to 120 and you see within minutes whether a client refreshes silently.
33
+ # SEATABLE_ACCESS_TOKEN_TTL=3600
package/README.md CHANGED
@@ -128,12 +128,33 @@ For hosting an MCP endpoint where each client authenticates with their own SeaTa
128
128
  ```bash
129
129
  SEATABLE_MODE=managed \
130
130
  SEATABLE_SERVER_URL=https://your-seatable-server.com \
131
+ SEATABLE_TOKEN_SECRET=$(openssl rand -hex 32) \
131
132
  PORT=3000 npx -y @seatable/mcp-seatable --sse
132
133
  ```
133
134
 
134
- Clients pass their API token via `Authorization: Bearer <token>` on session initialization. The server validates the token against SeaTable and applies rate limits (60 req/min per token, 120/min per IP, 20 concurrent connections per token).
135
+ `SEATABLE_TOKEN_SECRET` is **required** in managed mode. It seals the OAuth tokens the server issues, so the underlying SeaTable API token never has to be handed to a client. Keep it stable across restarts — changing it invalidates every issued access and refresh token and forces all clients to re-authorize.
135
136
 
136
- **OAuth support:** Managed mode also exposes OAuth 2.0 endpoints (`/authorize` and `/token`), enabling OAuth-compatible clients like ChatGPT to connect. During the OAuth flow, the user enters their SeaTable API token, which is then used as the access token — no external OAuth provider required.
137
+ Clients pass their credential via `Authorization: Bearer <token>` — on session initialization **and on every subsequent request**, including `GET` and `DELETE`. The `mcp-session-id` header is a routing value only; it is never accepted on its own. Each request is re-validated and must resolve to the same identity that created the session, otherwise the server answers `401` (missing/invalid credential) or `403` (valid credential, wrong session). Rate limits apply as before (60 req/min per token, 120/min per IP, 20 concurrent connections per token).
138
+
139
+ **OAuth support:** Managed mode also exposes OAuth 2.0 endpoints (`/authorize` and `/token`), enabling OAuth-compatible clients like ChatGPT to connect — no external OAuth provider required. During the flow the user enters their SeaTable API token; the server seals it into its own short-lived access token (1 h) and a rotating refresh token (14 d). The raw SeaTable API token is never returned to a client.
140
+
141
+ Clients must register at `/register` first: the returned `client_id` carries the client's name and its `redirect_uris`, and the server accepts a callback only if it is one the client registered (loopback callbacks may vary the port, per RFC 8252). PKCE with `S256` is mandatory, and every authorization code is bound to the client, the exact callback and the challenge.
142
+
143
+ **Where a code may be delivered.** With open dynamic registration, "registered client" is not a trust statement — anyone can register. What matters is whether the code leaves the user's machine:
144
+
145
+ | Callback | Behaviour |
146
+ |---|---|
147
+ | Loopback (`http://127.0.0.1:…`, `localhost`, `[::1]`) | allowed, no extra step — the code stays on the user's machine |
148
+ | Private-use scheme (`cursor://`, `vscode://`, `com.example.app:/…`) | allowed, no extra step — handed to a local application |
149
+ | `https` on a host in `SEATABLE_OAUTH_TRUSTED_REDIRECT_HOSTS` | allowed, no extra step |
150
+ | `https` on any other host | allowed **after** the user confirms the destination on a separate page |
151
+ | Remote plaintext `http`, `javascript:`, `data:`, `file:`, `blob:` | rejected |
152
+
153
+ The confirmation cannot be skipped from the entry link: it is read from the form body only, and a POST auto-submitted by a foreign page is refused via `Sec-Fetch-Site`. The trusted-host list therefore removes friction — it is not a gate, and leaving it unset breaks nothing.
154
+
155
+ The consent screen leads with the destination the authorization will be sent to. The application's name is shown as **self-reported**, because with open registration it is chosen by whoever registered the client and cannot be verified.
156
+
157
+ The OAuth endpoints are rate limited per IP (30/min overall, 10/min for token submissions), so `/authorize` cannot be used as an unthrottled oracle for testing SeaTable API tokens.
137
158
 
138
159
  OAuth endpoints follow the MCP specification (RFC 8414 metadata discovery, PKCE, dynamic client registration):
139
160
 
@@ -185,6 +206,10 @@ All tool inputs are validated with Zod schemas before execution. Write tools (`a
185
206
 
186
207
  Tool schemas are published with `additionalProperties: true` to remain compatible with MCP clients that may attach internal fields (e.g. `_meta`). Unexpected fields are ignored by the server — they do not cause errors but are not processed either. This is a deliberate trade-off: stricter validation would improve error messages for typos but risk breaking compatibility with MCP clients.
187
208
 
209
+ ### Row Responses
210
+
211
+ Row responses include all columns and SeaTable system fields (`_id`, `_mtime`, `_ctime`, `_creator`, `_last_modifier`). System fields are not filtered — `_id` is required for updates and deletes, timestamps are useful for sorting and freshness checks, and creator/modifier fields can be resolved to display names via `list_collaborators`.
212
+
188
213
  ### Caching
189
214
 
190
215
  The server caches base metadata (table/column definitions) for 60 seconds to avoid redundant API calls during write operations. Schema-reading tools (`get_schema`, `list_tables`) always bypass the cache and return fresh data. If a cached schema becomes stale (e.g. a column was renamed), the SeaTable API will reject the write and the AI agent can call `get_schema` to refresh.
@@ -203,6 +228,8 @@ Authentication (one of these is required in selfhosted mode):
203
228
  Optional:
204
229
 
205
230
  - `SEATABLE_MODE` — `selfhosted` (default) or `managed` (multi-tenant HTTP with per-client auth)
231
+ - `SEATABLE_TOKEN_SECRET` — **required in managed mode**, min. 32 chars. Seals issued OAuth tokens and client registrations; must be stable across restarts (`openssl rand -hex 32`)
232
+ - `SEATABLE_ACCESS_TOKEN_TTL` — lifetime of an issued access token in seconds (default `3600`, range `30`–`2592000`). Lower narrows the window after a SeaTable token is revoked; higher spares users a re-prompt if their client renews badly. The refresh token is never issued shorter-lived than the access token.
206
233
  - `SEATABLE_MOCK=true` — Enable mock mode for offline testing
207
234
  - `CORS_ALLOWED_ORIGINS` — Comma-separated list of allowed origins for CORS (HTTP mode only, disabled if unset)
208
235
  - `METRICS_PORT` — Prometheus metrics port (default: `9090`, HTTP mode only)
@@ -3,13 +3,82 @@ export interface OAuthProviderOptions {
3
3
  hostname?: string;
4
4
  /** Optional callback to validate an API token before issuing an authorization code. */
5
5
  validateToken?: (token: string) => Promise<boolean>;
6
+ /**
7
+ * Hostnames whose https callbacks may receive an authorization code.
8
+ * Exact, case-insensitive match — no subdomain wildcards. Loopback and
9
+ * private-use schemes are always allowed and need no entry here.
10
+ * A single '*' disables curation entirely (dangerous; see README).
11
+ * Defaults to DEFAULT_TRUSTED_REDIRECT_HOSTS.
12
+ */
13
+ trustedRedirectHosts?: string[];
14
+ /**
15
+ * Lifetime of an issued access token, in ms. Defaults to one hour.
16
+ * Shorter narrows the window after a SeaTable token is revoked; longer
17
+ * spares users a re-prompt if their client renews badly.
18
+ */
19
+ accessTokenTtlMs?: number;
20
+ /** Resolves the client IP for audit logging. Falls back to 'unknown'. */
21
+ getClientIp?: (req: IncomingMessage) => string;
22
+ /**
23
+ * Distinguishes the two SeaTable token types. Called only after validation
24
+ * failed, to turn "Invalid API token" into a message that names the mistake.
25
+ */
26
+ looksLikeAccountToken?: (token: string) => Promise<boolean>;
27
+ /**
28
+ * Secret used to seal access tokens, refresh tokens and client registrations.
29
+ * Must be stable across restarts, otherwise every client is forced to re-authorize.
30
+ */
31
+ secret?: string;
6
32
  }
33
+ /**
34
+ * Hosted MCP clients whose callbacks live on their own servers. These are the
35
+ * only destinations that receive an authorization code over the network, so
36
+ * they are curated rather than open. Operators extend or replace this via
37
+ * SEATABLE_OAUTH_TRUSTED_REDIRECT_HOSTS.
38
+ */
39
+ export declare const DEFAULT_TRUSTED_REDIRECT_HOSTS: string[];
7
40
  export declare class OAuthProvider {
8
41
  private readonly codes;
9
42
  private readonly cleanupInterval;
10
43
  private readonly configuredHostname?;
11
44
  private readonly validateToken?;
45
+ private readonly cipher;
46
+ private readonly trustedRedirectHosts;
47
+ private readonly getClientIp?;
48
+ private readonly accessTokenTtlMs;
49
+ private readonly refreshTokenTtlMs;
50
+ private readonly looksLikeAccountToken?;
12
51
  constructor(options?: OAuthProviderOptions);
52
+ private clientIp;
53
+ /**
54
+ * May this callback be used at all?
55
+ *
56
+ * Rejects only destinations that can never be safe: schemes that execute or
57
+ * read local content, and plaintext http to a remote host. An unknown https
58
+ * host is permitted — it meets the acknowledgement instead (see below).
59
+ */
60
+ isPermittedRedirectUri(raw: string): boolean;
61
+ /**
62
+ * May this callback receive an authorization code without further friction?
63
+ *
64
+ * The question is not whether we recognise the client — with open dynamic
65
+ * registration an attacker registers honestly — but whether the code would
66
+ * leave the user's machine:
67
+ *
68
+ * loopback stays on the user's own machine
69
+ * private-use scheme goes to a locally installed app
70
+ * https + curated host a known hosted client (ChatGPT, Claude, ...)
71
+ *
72
+ * Everything else is still allowed, but only after the user has explicitly
73
+ * acknowledged where their token is about to be sent. Curation therefore
74
+ * removes friction; it is not a gate, and an empty list breaks nothing.
75
+ */
76
+ isTrustedRedirectUri(raw: string): boolean;
77
+ /**
78
+ * Resolves one of our own access tokens back to the SeaTable API token it seals.
79
+ * Returns undefined for anything we did not issue, or that has expired.
80
+ */
81
+ resolveAccessToken(accessToken: string): string | undefined;
13
82
  /**
14
83
  * Derive the base URL from SEATABLE_MCP_HOSTNAME or the incoming Host header.
15
84
  */
@@ -20,24 +89,45 @@ export declare class OAuthProvider {
20
89
  handleMetadata(req: IncomingMessage, res: ServerResponse): void;
21
90
  /**
22
91
  * POST /register — Dynamic Client Registration (RFC 7591)
23
- * Returns a generated client_id. We don't validate client credentials.
92
+ *
93
+ * The returned client_id is a sealed envelope containing the client's name and
94
+ * its redirect_uris. That makes the registration tamper-proof and verifiable at
95
+ * /authorize without any server-side storage: a client_id we did not issue
96
+ * cannot be opened, and the callback list inside it cannot be edited.
24
97
  */
25
98
  handleRegister(req: IncomingMessage, res: ServerResponse): Promise<void>;
26
99
  /**
27
100
  * GET /authorize — renders the authorization form
28
101
  * POST /authorize — processes the form submission
102
+ *
103
+ * Both paths validate the request the same way, and neither shows the token
104
+ * prompt until the client, the callback and the PKCE challenge all check out.
29
105
  */
30
106
  handleAuthorize(req: IncomingMessage, res: ServerResponse, url: URL): Promise<void>;
31
107
  /**
32
- * POST /token — exchanges authorization code for access token
108
+ * POST /token — exchanges an authorization code (or refresh token) for an access token.
109
+ *
110
+ * The issued access token is a sealed envelope around the SeaTable API token,
111
+ * never the API token itself.
33
112
  */
34
113
  handleToken(req: IncomingMessage, res: ServerResponse): Promise<void>;
35
114
  destroy(): void;
115
+ private handleRefreshGrant;
116
+ private issueTokens;
117
+ private tokenError;
118
+ private registrationError;
119
+ private parseRedirectUris;
36
120
  private cleanup;
37
121
  private parseFormBody;
38
122
  private parseBody;
39
123
  private readBody;
124
+ /** An error page that deliberately does not render the API token prompt. */
125
+ private authorizeError;
126
+ private renderAcknowledgementPage;
40
127
  private renderAuthorizePage;
128
+ private hiddenFlowFields;
129
+ /** Shared chrome for every page this provider renders. */
130
+ private page;
41
131
  private escapeHtml;
42
132
  }
43
133
  //# sourceMappingURL=oauthProvider.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"oauthProvider.d.ts","sourceRoot":"","sources":["../../src/auth/oauthProvider.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAehE,MAAM,WAAW,oBAAoB;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,uFAAuF;IACvF,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CACtD;AAED,qBAAa,aAAa;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuC;IAC7D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAgC;IAChE,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAQ;IAC5C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAqC;gBAExD,OAAO,CAAC,EAAE,oBAAoB;IAS1C;;OAEG;IACH,OAAO,CAAC,cAAc;IAStB;;OAEG;IACH,cAAc,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,GAAG,IAAI;IAe/D;;;OAGG;IACG,cAAc,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IA6B9E;;;OAGG;IACG,eAAe,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,EAAE,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAqEzF;;OAEG;IACG,WAAW,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAgG3E,OAAO,IAAI,IAAI;IAKf,OAAO,CAAC,OAAO;YASD,aAAa;YAsBb,SAAS;IAiBvB,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,mBAAmB;IA8E3B,OAAO,CAAC,UAAU;CAGrB"}
1
+ {"version":3,"file":"oauthProvider.d.ts","sourceRoot":"","sources":["../../src/auth/oauthProvider.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAsChE,MAAM,WAAW,oBAAoB;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,uFAAuF;IACvF,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IACnD;;;;;;OAMG;IACH,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC/B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,yEAAyE;IACzE,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,MAAM,CAAA;IAC9C;;;OAGG;IACH,qBAAqB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAC3D;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CAClB;AAaD;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,UAA6C,CAAA;AAyBxF,qBAAa,aAAa;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuC;IAC7D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAgC;IAChE,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAQ;IAC5C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAqC;IACpE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAa;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAkC;IAC/D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAQ;IACzC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAQ;IAC1C,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAC,CAAqC;gBAEhE,OAAO,CAAC,EAAE,oBAAoB;IAwB1C,OAAO,CAAC,QAAQ;IAIhB;;;;;;OAMG;IACH,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAc5C;;;;;;;;;;;;;;OAcG;IACH,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAW1C;;;OAGG;IACH,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAK3D;;OAEG;IACH,OAAO,CAAC,cAAc;IAStB;;OAEG;IACH,cAAc,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,GAAG,IAAI;IAgB/D;;;;;;;OAOG;IACG,cAAc,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAoD9E;;;;;;OAMG;IACG,eAAe,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,EAAE,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IA4IzF;;;;;OAKG;IACG,WAAW,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IA8E3E,OAAO,IAAI,IAAI;IAKf,OAAO,CAAC,kBAAkB;IA4B1B,OAAO,CAAC,WAAW;IAanB,OAAO,CAAC,UAAU;IAKlB,OAAO,CAAC,iBAAiB;IAKzB,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,OAAO;YASD,aAAa;YAsBb,SAAS;IAiBvB,OAAO,CAAC,QAAQ;IAmBhB,4EAA4E;IAC5E,OAAO,CAAC,cAAc;IAyBtB,OAAO,CAAC,yBAAyB;IAwBjC,OAAO,CAAC,mBAAmB;IAuB3B,OAAO,CAAC,gBAAgB;IAaxB,0DAA0D;IAC1D,OAAO,CAAC,IAAI;IAkCZ,OAAO,CAAC,UAAU;CAGrB"}