context-drop 0.0.0-stage → 0.3.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.
Files changed (60) hide show
  1. package/MIT-LICENSE +21 -0
  2. package/README.md +710 -2
  3. package/app/assets/javascripts/context_drop/context_drop.js +9949 -0
  4. package/dist/app/javascript/context_drop/api-client.d.ts +53 -0
  5. package/dist/app/javascript/context_drop/api-client.js +470 -0
  6. package/dist/app/javascript/context_drop/element-picker.d.ts +111 -0
  7. package/dist/app/javascript/context_drop/element-picker.js +1428 -0
  8. package/dist/app/javascript/context_drop/icons.d.ts +34 -0
  9. package/dist/app/javascript/context_drop/icons.js +34 -0
  10. package/dist/app/javascript/context_drop/index.d.ts +7 -0
  11. package/dist/app/javascript/context_drop/index.js +9 -0
  12. package/dist/app/javascript/context_drop/markdown.d.ts +7 -0
  13. package/dist/app/javascript/context_drop/markdown.js +129 -0
  14. package/dist/app/javascript/context_drop/sanitizer.d.ts +38 -0
  15. package/dist/app/javascript/context_drop/sanitizer.js +769 -0
  16. package/dist/app/javascript/context_drop/screenshot.d.ts +21 -0
  17. package/dist/app/javascript/context_drop/screenshot.js +245 -0
  18. package/dist/app/javascript/context_drop/styles.d.ts +1 -0
  19. package/dist/app/javascript/context_drop/styles.js +2196 -0
  20. package/dist/app/javascript/context_drop/types.d.ts +316 -0
  21. package/dist/app/javascript/context_drop/types.js +1 -0
  22. package/dist/app/javascript/context_drop/widget.d.ts +206 -0
  23. package/dist/app/javascript/context_drop/widget.js +3752 -0
  24. package/dist/src/cli.d.ts +3 -0
  25. package/dist/src/cli.js +207 -0
  26. package/dist/src/index.d.ts +5 -0
  27. package/dist/src/index.js +5 -0
  28. package/dist/src/mcp/dispatcher.d.ts +42 -0
  29. package/dist/src/mcp/dispatcher.js +895 -0
  30. package/dist/src/mcp/environment-router.d.ts +38 -0
  31. package/dist/src/mcp/environment-router.js +174 -0
  32. package/dist/src/mcp/index.d.ts +24 -0
  33. package/dist/src/mcp/index.js +75 -0
  34. package/dist/src/mcp/remote-client.d.ts +25 -0
  35. package/dist/src/mcp/remote-client.js +98 -0
  36. package/dist/src/next/index.d.ts +13 -0
  37. package/dist/src/next/index.js +25 -0
  38. package/dist/src/next/server.d.ts +1 -0
  39. package/dist/src/next/server.js +1 -0
  40. package/dist/src/react/index.d.ts +104 -0
  41. package/dist/src/react/index.js +144 -0
  42. package/dist/src/server/handler.d.ts +48 -0
  43. package/dist/src/server/handler.js +1180 -0
  44. package/dist/src/server/index.d.ts +8 -0
  45. package/dist/src/server/index.js +8 -0
  46. package/dist/src/server/sanitizer.d.ts +15 -0
  47. package/dist/src/server/sanitizer.js +201 -0
  48. package/dist/src/server/storage/local.d.ts +22 -0
  49. package/dist/src/server/storage/local.js +827 -0
  50. package/dist/src/server/storage/memory.d.ts +8 -0
  51. package/dist/src/server/storage/memory.js +387 -0
  52. package/dist/src/server/storage/postgres.d.ts +27 -0
  53. package/dist/src/server/storage/postgres.js +629 -0
  54. package/dist/src/server/types.d.ts +227 -0
  55. package/dist/src/server/types.js +7 -0
  56. package/dist/src/server/upload-validator.d.ts +16 -0
  57. package/dist/src/server/upload-validator.js +196 -0
  58. package/dist/src/widget/index.d.ts +1 -0
  59. package/dist/src/widget/index.js +1 -0
  60. package/package.json +99 -4
@@ -0,0 +1,8 @@
1
+ export * from "./types.js";
2
+ export * from "./sanitizer.js";
3
+ export * from "./upload-validator.js";
4
+ export * from "./storage/memory.js";
5
+ export * from "./storage/local.js";
6
+ export * from "./storage/postgres.js";
7
+ export * from "./handler.js";
8
+ export { ContextDropMcpDispatcher, EnvironmentRouter, MCP_PROTOCOL_VERSION, RemoteMcpClient, RemoteMcpError, createContextDropMcpServer, runContextDropMcpStdio } from "../mcp/index.js";
@@ -0,0 +1,8 @@
1
+ export * from "./types.js";
2
+ export * from "./sanitizer.js";
3
+ export * from "./upload-validator.js";
4
+ export * from "./storage/memory.js";
5
+ export * from "./storage/local.js";
6
+ export * from "./storage/postgres.js";
7
+ export * from "./handler.js";
8
+ export { ContextDropMcpDispatcher, EnvironmentRouter, MCP_PROTOCOL_VERSION, RemoteMcpClient, RemoteMcpError, createContextDropMcpServer, runContextDropMcpStdio } from "../mcp/index.js";
@@ -0,0 +1,15 @@
1
+ import type { BoundingRectSnapshot, ViewportSnapshot } from "../../app/javascript/context_drop/types.js";
2
+ import type { SanitizedElementInput } from "./types.js";
3
+ export declare const ALLOWED_ATTRIBUTE_KEYS: Set<string>;
4
+ export declare const FORBIDDEN_METADATA_KEYS: Set<string>;
5
+ export declare const MANDATORY_SERVER_EXCLUDED_SELECTORS: readonly ["[data-feedback-ignore]", "[data-feedback-sensitive]", "input[type='password']", "input[type='hidden']", "[autocomplete^='cc-']"];
6
+ export declare class SensitiveElementError extends Error {
7
+ readonly status = 422;
8
+ constructor(message?: string);
9
+ }
10
+ export declare function isSensitiveElementPayload(tagName: string, attrs: Record<string, unknown>, selector?: string): boolean;
11
+ export declare function sanitizeAttributes(rawAttrs: unknown): Record<string, string>;
12
+ export declare function sanitizeBoundingRect(rawRect: unknown): Partial<BoundingRectSnapshot>;
13
+ export declare function sanitizeViewport(rawViewport: unknown): Partial<ViewportSnapshot>;
14
+ export declare function sanitizeGenericMetadata(input: unknown, depth?: number): Record<string, unknown>;
15
+ export declare function sanitizeElementReference(rawInput: unknown): SanitizedElementInput;
@@ -0,0 +1,201 @@
1
+ export const ALLOWED_ATTRIBUTE_KEYS = new Set([
2
+ "id",
3
+ "class",
4
+ "role",
5
+ "name",
6
+ "type",
7
+ "href",
8
+ "title",
9
+ "placeholder",
10
+ "alt",
11
+ "data-testid",
12
+ "data-test",
13
+ "data-cy",
14
+ "data-qa",
15
+ "data-turbo-frame"
16
+ ]);
17
+ export const FORBIDDEN_METADATA_KEYS = new Set([
18
+ "outerhtml",
19
+ "innerhtml",
20
+ "value",
21
+ "defaultvalue",
22
+ "password",
23
+ "secret",
24
+ "token",
25
+ "authorization",
26
+ "cookie"
27
+ ]);
28
+ export const MANDATORY_SERVER_EXCLUDED_SELECTORS = [
29
+ "[data-feedback-ignore]",
30
+ "[data-feedback-sensitive]",
31
+ "input[type='password']",
32
+ "input[type='hidden']",
33
+ "[autocomplete^='cc-']"
34
+ ];
35
+ const MAX_TEXT_LENGTH = 500;
36
+ const MAX_SELECTOR_LENGTH = 500;
37
+ const MAX_DOM_PATH_LENGTH = 1000;
38
+ const MAX_ATTR_VALUE_LENGTH = 300;
39
+ export class SensitiveElementError extends Error {
40
+ status = 422;
41
+ constructor(message = "Cannot attach excluded or sensitive DOM element") {
42
+ super(message);
43
+ this.name = "SensitiveElementError";
44
+ }
45
+ }
46
+ function asRecord(input) {
47
+ if (input && typeof input === "object" && !Array.isArray(input)) {
48
+ return input;
49
+ }
50
+ return {};
51
+ }
52
+ function truncateStr(val, maxLen) {
53
+ if (val === null || val === undefined)
54
+ return null;
55
+ const str = String(val);
56
+ return str.length > maxLen ? str.slice(0, maxLen) : str;
57
+ }
58
+ export function isSensitiveElementPayload(tagName, attrs, selector = "") {
59
+ const inputType = String(attrs["type"] ?? "").trim().toLowerCase();
60
+ if (tagName === "input" && (inputType === "password" || inputType === "hidden")) {
61
+ return true;
62
+ }
63
+ const lowerAttrKeys = Object.keys(attrs).map((k) => k.trim().toLowerCase());
64
+ if (lowerAttrKeys.includes("data-feedback-ignore") ||
65
+ lowerAttrKeys.includes("data-feedback-sensitive")) {
66
+ return true;
67
+ }
68
+ const autocomplete = String(attrs["autocomplete"] ?? "").trim().toLowerCase();
69
+ if (autocomplete.startsWith("cc-")) {
70
+ return true;
71
+ }
72
+ const selDown = selector.toLowerCase();
73
+ if (selDown.includes("data-feedback-ignore") ||
74
+ selDown.includes("data-feedback-sensitive")) {
75
+ return true;
76
+ }
77
+ return false;
78
+ }
79
+ export function sanitizeAttributes(rawAttrs) {
80
+ const attrs = asRecord(rawAttrs);
81
+ const sanitized = {};
82
+ for (const [key, value] of Object.entries(attrs)) {
83
+ const normalizedKey = key.trim().toLowerCase();
84
+ if (!normalizedKey)
85
+ continue;
86
+ if (FORBIDDEN_METADATA_KEYS.has(normalizedKey))
87
+ continue;
88
+ if (normalizedKey.startsWith("on"))
89
+ continue;
90
+ const allowed = ALLOWED_ATTRIBUTE_KEYS.has(normalizedKey) ||
91
+ (normalizedKey.startsWith("aria-") && normalizedKey !== "aria-hidden");
92
+ if (!allowed)
93
+ continue;
94
+ const strVal = String(value ?? "").trim();
95
+ if (normalizedKey === "href" &&
96
+ (strVal.toLowerCase().startsWith("javascript:") || strVal.toLowerCase().startsWith("data:"))) {
97
+ continue;
98
+ }
99
+ sanitized[normalizedKey] = truncateStr(strVal, MAX_ATTR_VALUE_LENGTH) ?? "";
100
+ }
101
+ return sanitized;
102
+ }
103
+ export function sanitizeBoundingRect(rawRect) {
104
+ const rect = asRecord(rawRect);
105
+ const result = {};
106
+ for (const coord of ["x", "y", "width", "height"]) {
107
+ if (rect[coord] === undefined || rect[coord] === null)
108
+ continue;
109
+ const num = Number(rect[coord]);
110
+ if (!Number.isNaN(num)) {
111
+ result[coord] = Number.isFinite(num) ? Math.round(num * 100) / 100 : 0;
112
+ }
113
+ }
114
+ return result;
115
+ }
116
+ export function sanitizeViewport(rawViewport) {
117
+ const vp = asRecord(rawViewport);
118
+ const result = {};
119
+ for (const dim of ["width", "height"]) {
120
+ if (vp[dim] === undefined || vp[dim] === null)
121
+ continue;
122
+ const num = Math.trunc(Number(vp[dim]));
123
+ if (!Number.isNaN(num)) {
124
+ result[dim] = num > 0 ? num : 0;
125
+ }
126
+ }
127
+ return result;
128
+ }
129
+ function sanitizeScalar(val) {
130
+ if (val === null || typeof val === "boolean")
131
+ return val;
132
+ if (typeof val === "number")
133
+ return Number.isFinite(val) ? val : 0;
134
+ return truncateStr(String(val), MAX_TEXT_LENGTH);
135
+ }
136
+ export function sanitizeGenericMetadata(input, depth = 0) {
137
+ if (depth > 4)
138
+ return {};
139
+ const obj = asRecord(input);
140
+ const cleaned = {};
141
+ for (const [k, v] of Object.entries(obj)) {
142
+ const keyStr = k.trim();
143
+ if (!keyStr)
144
+ continue;
145
+ if (FORBIDDEN_METADATA_KEYS.has(keyStr.toLowerCase()))
146
+ continue;
147
+ if (Array.isArray(v)) {
148
+ cleaned[keyStr] = v.slice(0, 25).map((item) => item && typeof item === "object" && !Array.isArray(item)
149
+ ? sanitizeGenericMetadata(item, depth + 1)
150
+ : sanitizeScalar(item));
151
+ }
152
+ else if (v && typeof v === "object") {
153
+ cleaned[keyStr] = sanitizeGenericMetadata(v, depth + 1);
154
+ }
155
+ else if (v !== undefined) {
156
+ cleaned[keyStr] = sanitizeScalar(v);
157
+ }
158
+ }
159
+ return cleaned;
160
+ }
161
+ function sanitizeTextContent(tagName, text) {
162
+ if (text === null || text === undefined)
163
+ return null;
164
+ if (["input", "textarea", "select", "password"].includes(tagName)) {
165
+ return null;
166
+ }
167
+ const normalized = String(text).replace(/\s+/g, " ").trim();
168
+ if (!normalized)
169
+ return null;
170
+ return truncateStr(normalized, MAX_TEXT_LENGTH);
171
+ }
172
+ function parseIsoTimestamp(val) {
173
+ if (typeof val === "string" && val.trim().length > 0) {
174
+ const parsed = Date.parse(val.trim());
175
+ if (!Number.isNaN(parsed)) {
176
+ return new Date(parsed).toISOString();
177
+ }
178
+ }
179
+ return new Date().toISOString();
180
+ }
181
+ export function sanitizeElementReference(rawInput) {
182
+ const params = asRecord(rawInput);
183
+ const tagName = String(params["tag_name"] ?? "").trim().toLowerCase();
184
+ const rawAttrs = asRecord(params["attributes_snapshot"] ?? params["attributes"]);
185
+ const rawSelector = String(params["selector"] ?? "");
186
+ if (isSensitiveElementPayload(tagName, rawAttrs, rawSelector)) {
187
+ throw new SensitiveElementError("Cannot attach excluded or sensitive DOM element");
188
+ }
189
+ return {
190
+ client_ref: truncateStr(params["client_ref"], 128),
191
+ tag_name: tagName || "div",
192
+ selector: (truncateStr(rawSelector, MAX_SELECTOR_LENGTH) ?? "").trim() || tagName || "div",
193
+ dom_path: truncateStr(params["dom_path"], MAX_DOM_PATH_LENGTH),
194
+ text_content: sanitizeTextContent(tagName, params["text_content"]),
195
+ attributes_snapshot: sanitizeAttributes(rawAttrs),
196
+ bounding_rect: sanitizeBoundingRect(params["bounding_rect"]),
197
+ viewport: sanitizeViewport(params["viewport"]),
198
+ metadata: sanitizeGenericMetadata(params["metadata"]),
199
+ captured_at: parseIsoTimestamp(params["captured_at"])
200
+ };
201
+ }
@@ -0,0 +1,22 @@
1
+ import type { BlobStorageAdapter, StorageAdapter } from "../types.js";
2
+ export interface LocalStorageAdapterOptions {
3
+ /**
4
+ * Directory where local SQLite/JSON metadata and binary attachment blobs are stored.
5
+ * Defaults to `process.env.CONTEXT_DROP_STORAGE_DIR` or `<cwd>/.context-drop`.
6
+ */
7
+ dir?: string;
8
+ /**
9
+ * Storage backend engine: `"auto"` (uses Node 22.5+ built-in `node:sqlite` when available,
10
+ * falling back to atomic JSON), `"sqlite"`, or `"json"`.
11
+ */
12
+ backend?: "auto" | "sqlite" | "json";
13
+ /**
14
+ * Optional HMAC secret for signing pending upload blob IDs and ownership tokens.
15
+ */
16
+ secret?: string;
17
+ /**
18
+ * Optional custom blob store (e.g. S3 / Vercel Blob) instead of `<dir>/blobs/`.
19
+ */
20
+ blobStore?: BlobStorageAdapter;
21
+ }
22
+ export declare function createLocalStorageAdapter(options?: LocalStorageAdapterOptions): StorageAdapter;