@seatable/mcp-seatable 1.5.2 → 1.6.1

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
 
@@ -207,6 +228,8 @@ Authentication (one of these is required in selfhosted mode):
207
228
  Optional:
208
229
 
209
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.
210
233
  - `SEATABLE_MOCK=true` — Enable mock mode for offline testing
211
234
  - `CORS_ALLOWED_ORIGINS` — Comma-separated list of allowed origins for CORS (HTTP mode only, disabled if unset)
212
235
  - `METRICS_PORT` — Prometheus metrics port (default: `9090`, HTTP mode only)
@@ -3,13 +3,86 @@ 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[];
40
+ /** The protected resource clients authorize against — the Streamable HTTP endpoint. */
41
+ export declare const MCP_RESOURCE_PATH = "/mcp";
42
+ /** RFC 9728 well-known prefix. The resource path is appended to it. */
43
+ export declare const PROTECTED_RESOURCE_PATH = "/.well-known/oauth-protected-resource";
7
44
  export declare class OAuthProvider {
8
45
  private readonly codes;
9
46
  private readonly cleanupInterval;
10
47
  private readonly configuredHostname?;
11
48
  private readonly validateToken?;
49
+ private readonly cipher;
50
+ private readonly trustedRedirectHosts;
51
+ private readonly getClientIp?;
52
+ private readonly accessTokenTtlMs;
53
+ private readonly refreshTokenTtlMs;
54
+ private readonly looksLikeAccountToken?;
12
55
  constructor(options?: OAuthProviderOptions);
56
+ private clientIp;
57
+ /**
58
+ * May this callback be used at all?
59
+ *
60
+ * Rejects only destinations that can never be safe: schemes that execute or
61
+ * read local content, and plaintext http to a remote host. An unknown https
62
+ * host is permitted — it meets the acknowledgement instead (see below).
63
+ */
64
+ isPermittedRedirectUri(raw: string): boolean;
65
+ /**
66
+ * May this callback receive an authorization code without further friction?
67
+ *
68
+ * The question is not whether we recognise the client — with open dynamic
69
+ * registration an attacker registers honestly — but whether the code would
70
+ * leave the user's machine:
71
+ *
72
+ * loopback stays on the user's own machine
73
+ * private-use scheme goes to a locally installed app
74
+ * https + curated host a known hosted client (ChatGPT, Claude, ...)
75
+ *
76
+ * Everything else is still allowed, but only after the user has explicitly
77
+ * acknowledged where their token is about to be sent. Curation therefore
78
+ * removes friction; it is not a gate, and an empty list breaks nothing.
79
+ */
80
+ isTrustedRedirectUri(raw: string): boolean;
81
+ /**
82
+ * Resolves one of our own access tokens back to the SeaTable API token it seals.
83
+ * Returns undefined for anything we did not issue, or that has expired.
84
+ */
85
+ resolveAccessToken(accessToken: string): string | undefined;
13
86
  /**
14
87
  * Derive the base URL from SEATABLE_MCP_HOSTNAME or the incoming Host header.
15
88
  */
@@ -18,26 +91,75 @@ export declare class OAuthProvider {
18
91
  * GET /.well-known/oauth-authorization-server — RFC 8414 metadata
19
92
  */
20
93
  handleMetadata(req: IncomingMessage, res: ServerResponse): void;
94
+ /**
95
+ * The resource identifier clients authorize against: the MCP endpoint itself.
96
+ */
97
+ private resourceIdentifier;
98
+ /**
99
+ * Where the protected resource metadata for that identifier lives.
100
+ *
101
+ * RFC 9728 section 3.1: the resource's path is appended to the well-known
102
+ * suffix, so `https://host/mcp` is described at
103
+ * `https://host/.well-known/oauth-protected-resource/mcp`.
104
+ */
105
+ resourceMetadataUrl(req: IncomingMessage): string;
106
+ /**
107
+ * GET /.well-known/oauth-protected-resource[/mcp] — RFC 9728 metadata
108
+ *
109
+ * `authorization_servers` MUST agree with the issuer that handleMetadata()
110
+ * reports. A conformant client follows this document INSTEAD of probing
111
+ * /.well-known/oauth-authorization-server, so a disagreement here breaks
112
+ * clients that work today. Both derive from resolveBaseUrl() for that reason.
113
+ */
114
+ handleProtectedResourceMetadata(req: IncomingMessage, res: ServerResponse): void;
115
+ /**
116
+ * The WWW-Authenticate challenge for a 401, pointing at the metadata above.
117
+ *
118
+ * RFC 6750 section 3.1: a request that carried no credential at all gets no
119
+ * error code — only one that presented a credential we rejected does.
120
+ */
121
+ challenge(req: IncomingMessage, error?: 'invalid_token'): string;
21
122
  /**
22
123
  * POST /register — Dynamic Client Registration (RFC 7591)
23
- * Returns a generated client_id. We don't validate client credentials.
124
+ *
125
+ * The returned client_id is a sealed envelope containing the client's name and
126
+ * its redirect_uris. That makes the registration tamper-proof and verifiable at
127
+ * /authorize without any server-side storage: a client_id we did not issue
128
+ * cannot be opened, and the callback list inside it cannot be edited.
24
129
  */
25
130
  handleRegister(req: IncomingMessage, res: ServerResponse): Promise<void>;
26
131
  /**
27
132
  * GET /authorize — renders the authorization form
28
133
  * POST /authorize — processes the form submission
134
+ *
135
+ * Both paths validate the request the same way, and neither shows the token
136
+ * prompt until the client, the callback and the PKCE challenge all check out.
29
137
  */
30
138
  handleAuthorize(req: IncomingMessage, res: ServerResponse, url: URL): Promise<void>;
31
139
  /**
32
- * POST /token — exchanges authorization code for access token
140
+ * POST /token — exchanges an authorization code (or refresh token) for an access token.
141
+ *
142
+ * The issued access token is a sealed envelope around the SeaTable API token,
143
+ * never the API token itself.
33
144
  */
34
145
  handleToken(req: IncomingMessage, res: ServerResponse): Promise<void>;
35
146
  destroy(): void;
147
+ private handleRefreshGrant;
148
+ private issueTokens;
149
+ private tokenError;
150
+ private registrationError;
151
+ private parseRedirectUris;
36
152
  private cleanup;
37
153
  private parseFormBody;
38
154
  private parseBody;
39
155
  private readBody;
156
+ /** An error page that deliberately does not render the API token prompt. */
157
+ private authorizeError;
158
+ private renderAcknowledgementPage;
40
159
  private renderAuthorizePage;
160
+ private hiddenFlowFields;
161
+ /** Shared chrome for every page this provider renders. */
162
+ private page;
41
163
  private escapeHtml;
42
164
  }
43
165
  //# 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;AAExF,uFAAuF;AACvF,eAAO,MAAM,iBAAiB,SAAS,CAAA;AAEvC,uEAAuE;AACvE,eAAO,MAAM,uBAAuB,0CAA0C,CAAA;AAyB9E,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;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAI1B;;;;;;OAMG;IACH,mBAAmB,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM;IAIjD;;;;;;;OAOG;IACH,+BAA+B,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,GAAG,IAAI;IAUhF;;;;;OAKG;IACH,SAAS,CAAC,GAAG,EAAE,eAAe,EAAE,KAAK,CAAC,EAAE,eAAe,GAAG,MAAM;IAMhE;;;;;;;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"}