guard.ts

mcp-server/src/lib/guard.ts

1. /**
2. * Write-prevention failsafe (defense in depth).
3. *
4. * This server is read-only by contract. But the Plinth API is a single dispatch
5. * endpoint where the `method` query param selects the action, and two tools
6. * (get_product / get_inventory) accept a free-form passthrough param bag. That
7. * combination means a caller (including an LLM that fabricates arguments, tries
8. * to smuggle a write method through the passthrough bag, or guesses a real
9. * write method name by chance) could otherwise attempt a mutation.
10. *
11. * These guards make that structurally impossible. They are independent of the
12. * TypeScript `ReadMethod` type on purpose: the type is a compile-time promise,
13. * this is the runtime enforcement that still holds if someone casts to `any`,
14. * edits a handler, or calls the client from plain JS. Every layer fails closed:
15. * a violation stops the request rather than letting it through.
16. *
17. * Layer 1 assertReadMethod: the dispatched method must be on the allowlist.
18. * Layer 2 assertSafeParams: no reserved/override keys, no write-intent keys.
19. * Layer 3 buildUrl (http.ts) sets method/api_key last and skips reserved
20. * keys, so params can never override them.
21. * Layer 4 assertUrlIsRead: final check on the built wire URL before fetch.
22. */
24. /** The ONLY methods this server may ever dispatch. Frozen source of truth. */
25. export const READ_METHODS = Object.freeze([
26. "orders.fetch",
27. "statuses.list",
28. "customers.fetch",
29. "orders.splitShipments",
30. "products.fetch",
31. "inventory.fetch",
32. ] as const);
34. export type ReadMethod = (typeof READ_METHODS)[number];
36. const READ_METHOD_SET: ReadonlySet<string> = new Set(READ_METHODS);
38. /** Params the server sets itself; a caller may never provide or override them. */
39. export const RESERVED_PARAM_KEYS: ReadonlySet<string> = new Set(["method", "api_key"]);
41. /**
42. * Param keys that signal a mutation. Read methods never take these, so their
43. * presence is treated as an attempted write and rejected. Kept deliberately
44. * narrow to avoid colliding with legitimate read params (e.g. `email`,
45. * `status_code`, `shop`, `date_field`).
46. */
47. const WRITE_INTENT_KEY =
48. /^(set|insert|update|delete|destroy|drop|truncate|create|remove|write|save|approve|cancel|notify|adjust)/i;
50. /** Raised whenever any failsafe layer detects an attempt to leave read-only territory. */
51. export class WriteAttemptError extends Error {
52. constructor(message: string) {
53. super(`Write-prevention failsafe tripped: ${message}`);
54. this.name = "WriteAttemptError";
55. }
56. }
58. /** Layer 1: runtime backstop for the compile-time ReadMethod type. */
59. export function assertReadMethod(method: string): asserts method is ReadMethod {
60. if (!READ_METHOD_SET.has(method)) {
61. throw new WriteAttemptError(
62. `method "${method}" is not one of the ${READ_METHODS.length} allowed read methods ` +
63. `(${READ_METHODS.join(", ")}).`,
64. );
65. }
66. }
68. /** Layer 2: reject reserved/override keys and any key signaling write intent. */
69. export function assertSafeParams(params: Record<string, unknown>): void {
70. for (const key of Object.keys(params)) {
71. const k = key.trim().toLowerCase();
72. if (RESERVED_PARAM_KEYS.has(k)) {
73. throw new WriteAttemptError(
74. `param "${key}" is reserved (the server sets it) and cannot be supplied by a caller.`,
75. );
76. }
77. if (WRITE_INTENT_KEY.test(k)) {
78. throw new WriteAttemptError(
79. `param "${key}" signals write intent; only read parameters are permitted.`,
80. );
81. }
82. }
83. }
85. /** Layer 4: final gate on the fully-built URL, immediately before fetch. */
86. export function assertUrlIsRead(url: URL): void {
87. const methods = url.searchParams.getAll("method");
88. if (methods.length !== 1) {
89. throw new WriteAttemptError(
90. `built request URL must carry exactly one "method" param (found ${methods.length}).`,
91. );
92. }
93. const [method] = methods;
94. if (method === undefined || !READ_METHOD_SET.has(method)) {
95. throw new WriteAttemptError(`built request URL method "${method}" is not an allowed read method.`);
96. }
97. }