@conarium-ai/core 0.2.10 → 0.2.12

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 (111) hide show
  1. package/CHANGELOG.md +43 -2
  2. package/LIMITATIONS.md +39 -5
  3. package/LIMITATIONS.tr.md +38 -5
  4. package/README.md +11 -8
  5. package/SECURITY.md +1 -0
  6. package/bin/conarium-doctor.mjs +226 -7
  7. package/bin/doctor-sql.mjs +47 -0
  8. package/dist/audit.d.ts.map +1 -1
  9. package/dist/audit.js +12 -3
  10. package/dist/audit.js.map +1 -1
  11. package/dist/config.d.ts +22 -8
  12. package/dist/config.d.ts.map +1 -1
  13. package/dist/config.js +22 -1
  14. package/dist/config.js.map +1 -1
  15. package/dist/connectors/custom-sql.d.ts +22 -0
  16. package/dist/connectors/custom-sql.d.ts.map +1 -0
  17. package/dist/connectors/custom-sql.js +67 -0
  18. package/dist/connectors/custom-sql.js.map +1 -0
  19. package/dist/connectors/index.d.ts +1 -0
  20. package/dist/connectors/index.d.ts.map +1 -1
  21. package/dist/connectors/index.js +5 -1
  22. package/dist/connectors/index.js.map +1 -1
  23. package/dist/connectors/openapi.d.ts.map +1 -1
  24. package/dist/connectors/openapi.js +0 -1
  25. package/dist/connectors/openapi.js.map +1 -1
  26. package/dist/connectors/supabase_rest.d.ts.map +1 -1
  27. package/dist/connectors/supabase_rest.js +0 -1
  28. package/dist/connectors/supabase_rest.js.map +1 -1
  29. package/dist/console.d.ts.map +1 -1
  30. package/dist/console.js +14 -3
  31. package/dist/console.js.map +1 -1
  32. package/dist/executor.d.ts.map +1 -1
  33. package/dist/executor.js +0 -1
  34. package/dist/executor.js.map +1 -1
  35. package/dist/governance.d.ts +8 -0
  36. package/dist/governance.d.ts.map +1 -1
  37. package/dist/governance.js +29 -78
  38. package/dist/governance.js.map +1 -1
  39. package/dist/masking-cost.d.ts +16 -0
  40. package/dist/masking-cost.d.ts.map +1 -0
  41. package/dist/masking-cost.js +31 -0
  42. package/dist/masking-cost.js.map +1 -0
  43. package/dist/search_policy.d.ts.map +1 -1
  44. package/dist/search_policy.js +8 -4
  45. package/dist/search_policy.js.map +1 -1
  46. package/dist/server.d.ts.map +1 -1
  47. package/dist/server.js +90 -13
  48. package/dist/server.js.map +1 -1
  49. package/dist/sql-executor.d.ts +14 -0
  50. package/dist/sql-executor.d.ts.map +1 -0
  51. package/dist/sql-executor.js +75 -0
  52. package/dist/sql-executor.js.map +1 -0
  53. package/dist/sql-gate/dispatch.d.ts +17 -0
  54. package/dist/sql-gate/dispatch.d.ts.map +1 -0
  55. package/dist/sql-gate/dispatch.js +30 -0
  56. package/dist/sql-gate/dispatch.js.map +1 -0
  57. package/dist/sql-gate/mssql.d.ts +11 -0
  58. package/dist/sql-gate/mssql.d.ts.map +1 -0
  59. package/dist/sql-gate/mssql.js +287 -0
  60. package/dist/sql-gate/mssql.js.map +1 -0
  61. package/dist/sql-gate/oracle.d.ts +11 -0
  62. package/dist/sql-gate/oracle.d.ts.map +1 -0
  63. package/dist/sql-gate/oracle.js +227 -0
  64. package/dist/sql-gate/oracle.js.map +1 -0
  65. package/dist/sql-gate/postgres.d.ts +12 -0
  66. package/dist/sql-gate/postgres.d.ts.map +1 -0
  67. package/dist/sql-gate/postgres.js +64 -0
  68. package/dist/sql-gate/postgres.js.map +1 -0
  69. package/dist/sql-gate/rules.d.ts +14 -0
  70. package/dist/sql-gate/rules.d.ts.map +1 -0
  71. package/dist/sql-gate/rules.js +73 -0
  72. package/dist/sql-gate/rules.js.map +1 -0
  73. package/dist/sql-gate/types.d.ts +31 -0
  74. package/dist/sql-gate/types.d.ts.map +1 -0
  75. package/dist/sql-gate/types.js +9 -0
  76. package/dist/sql-gate/types.js.map +1 -0
  77. package/dist/table-unavailable.d.ts +12 -0
  78. package/dist/table-unavailable.d.ts.map +1 -0
  79. package/dist/table-unavailable.js +32 -0
  80. package/dist/table-unavailable.js.map +1 -0
  81. package/dist/types.d.ts +8 -1
  82. package/dist/types.d.ts.map +1 -1
  83. package/docs/API-STABILITY.md +174 -0
  84. package/docs/BENCHMARK.md +144 -0
  85. package/docs/audit/2026-08-14-e2e-health.md +69 -0
  86. package/docs/audit/2026-08-14-security-scan.md +48 -0
  87. package/docs/audit/2026-08-14-surface-sync.md +34 -0
  88. package/docs/benchmarks/concurrency-20260814.json +38 -0
  89. package/docs/benchmarks/latest.json +2310 -0
  90. package/docs/benchmarks/masking-cost-threshold.json +6 -0
  91. package/docs/benchmarks/overhead-20260814T1238Z-win32.json +402 -0
  92. package/docs/benchmarks/overhead-20260814T1346Z-linux.json +2310 -0
  93. package/docs/benchmarks/overhead-20260814T1644Z-win32.json +2310 -0
  94. package/docs/releases/v0.2.10.md +24 -0
  95. package/docs/releases/v0.2.8.md +23 -0
  96. package/docs/releases/v0.2.9.md +26 -0
  97. package/docs/security/NPM-PROVENANCE.md +64 -0
  98. package/docs/security/PENTEST-SCOPE.md +1 -1
  99. package/docs/security/THREAT-MODEL.md +25 -5
  100. package/docs/specs/2026-08-14-mssql-bypass-inventory.md +37 -0
  101. package/docs/specs/2026-08-14-oracle-bypass-inventory.md +28 -0
  102. package/examples/custom-sql/README.md +50 -0
  103. package/examples/custom-sql/conarium.config.json +22 -0
  104. package/examples/custom-sql/memory-executor.mjs +16 -0
  105. package/package.json +5 -5
  106. package/scripts/benchmark-concurrency.mjs +133 -0
  107. package/scripts/benchmark-overhead.mjs +492 -0
  108. package/test-vectors/README.md +3 -0
  109. package/test-vectors/sql-gate/LAST-RUN.json +11 -0
  110. package/test-vectors/sql-gate/README.md +19 -0
  111. package/test-vectors/sql-gate/vectors.json +331 -0
@@ -0,0 +1 @@
1
+ {"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../src/sql-gate/rules.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,eAAO,MAAM,YAAY,0JAGf,CAAA;AAEV,eAAO,MAAM,sBAAsB,aAgCjC,CAAA;AAEF,eAAO,MAAM,sBAAsB,aAMjC,CAAA;AAEF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGpD;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAM/D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAEhF;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE/D"}
@@ -0,0 +1,73 @@
1
+ /**
2
+ * Shared gate rules. Dialect-independent decisions.
3
+ * A new dialect must not copy these lists — it must call them.
4
+ */
5
+ export const WRITE_TOKENS = [
6
+ 'DROP ', 'TRUNCATE ', 'DELETE ', 'UPDATE ', 'INSERT ', 'ALTER ', 'CREATE ',
7
+ 'GRANT ', 'REVOKE ', 'MERGE ', 'COPY ', 'CALL ', 'DO ', 'VACUUM ',
8
+ ];
9
+ export const SAFE_BUILTIN_FUNCTIONS = new Set([
10
+ 'abs',
11
+ 'avg',
12
+ 'btrim',
13
+ 'ceil',
14
+ 'ceiling',
15
+ 'char_length',
16
+ 'coalesce',
17
+ 'concat',
18
+ 'concat_ws',
19
+ 'convert_to',
20
+ 'count',
21
+ 'encode',
22
+ 'floor',
23
+ 'greatest',
24
+ 'least',
25
+ 'length',
26
+ 'lower',
27
+ 'ltrim',
28
+ 'max',
29
+ 'min',
30
+ 'nullif',
31
+ 'octet_length',
32
+ 'regexp_replace',
33
+ 'regexp_split_to_array',
34
+ 'replace',
35
+ 'round',
36
+ 'rtrim',
37
+ 'split_part',
38
+ 'sum',
39
+ 'trim',
40
+ 'upper',
41
+ ]);
42
+ export const BLOCKED_DUMP_FUNCTIONS = new Set([
43
+ 'array_agg',
44
+ 'json_agg',
45
+ 'jsonb_agg',
46
+ 'row_to_json',
47
+ 'string_agg',
48
+ ]);
49
+ export function normalizedSqlHead(sql) {
50
+ return ` ${sql.trim().toUpperCase().replace(/\s+/g, ' ')} `;
51
+ }
52
+ export function isSelectOrWith(norm) {
53
+ const head = norm.trimStart();
54
+ return head.startsWith('SELECT') || head.startsWith('WITH');
55
+ }
56
+ export function findWriteToken(norm) {
57
+ for (const tok of WRITE_TOKENS) {
58
+ const regex = new RegExp(`\\b${tok.trim()}\\b`);
59
+ if (regex.test(norm))
60
+ return tok.trim();
61
+ }
62
+ return undefined;
63
+ }
64
+ export function hasRowLockClause(norm) {
65
+ return /\bFOR\s+(?:UPDATE|SHARE|NO\s+KEY\s+UPDATE|KEY\s+SHARE)\b/.test(norm);
66
+ }
67
+ export function isSafeBuiltinFunction(baseName, schema) {
68
+ return SAFE_BUILTIN_FUNCTIONS.has(baseName) && (!schema || schema === 'pg_catalog');
69
+ }
70
+ export function isBlockedDumpFunction(baseName) {
71
+ return BLOCKED_DUMP_FUNCTIONS.has(baseName);
72
+ }
73
+ //# sourceMappingURL=rules.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"rules.js","sourceRoot":"","sources":["../../src/sql-gate/rules.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS;IAC1E,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS;CACzD,CAAA;AAEV,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,GAAG,CAAC;IAC5C,KAAK;IACL,KAAK;IACL,OAAO;IACP,MAAM;IACN,SAAS;IACT,aAAa;IACb,UAAU;IACV,QAAQ;IACR,WAAW;IACX,YAAY;IACZ,OAAO;IACP,QAAQ;IACR,OAAO;IACP,UAAU;IACV,OAAO;IACP,QAAQ;IACR,OAAO;IACP,OAAO;IACP,KAAK;IACL,KAAK;IACL,QAAQ;IACR,cAAc;IACd,gBAAgB;IAChB,uBAAuB;IACvB,SAAS;IACT,OAAO;IACP,OAAO;IACP,YAAY;IACZ,KAAK;IACL,MAAM;IACN,OAAO;CACR,CAAC,CAAA;AAEF,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,GAAG,CAAC;IAC5C,WAAW;IACX,UAAU;IACV,WAAW;IACX,aAAa;IACb,YAAY;CACb,CAAC,CAAA;AAEF,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,OAAO,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAA;AAC7D,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,EAAE,CAAA;IAC7B,OAAO,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAA;AAC7D,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;QAC/C,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,OAAO,GAAG,CAAC,IAAI,EAAE,CAAA;IACzC,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,0DAA0D,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AAC9E,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,QAAgB,EAAE,MAAe;IACrE,OAAO,sBAAsB,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,MAAM,IAAI,MAAM,KAAK,YAAY,CAAC,CAAA;AACrF,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,QAAgB;IACpD,OAAO,sBAAsB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;AAC7C,CAAC"}
@@ -0,0 +1,31 @@
1
+ /**
2
+ * Questions every SQL dialect must answer. The AST type is not shared.
3
+ * pgsql-ast-parser is an input, not a decision.
4
+ *
5
+ * A dialect that only implements `inspect` is not supported. Support means
6
+ * the C vector set is green against that dialect. This file is the contract.
7
+ */
8
+ export type SqlDialectId = 'postgres' | 'mssql' | 'oracle';
9
+ export interface DialectQuestions {
10
+ /** 0 when parse failed. */
11
+ statementCount: number;
12
+ /** schema.table, already folded the way that dialect folds. */
13
+ tables: string[];
14
+ /** Output / referenced column names the adapter could name. */
15
+ columns: string[];
16
+ writes: boolean;
17
+ functions: string[];
18
+ /** True when the adapter saw a native row-limit node it understands. */
19
+ hasRowLimitNode: boolean;
20
+ parseFailed: boolean;
21
+ parseError?: string;
22
+ }
23
+ export interface DialectAdapter {
24
+ readonly dialect: SqlDialectId;
25
+ /**
26
+ * Fail-closed: unparseable input sets parseFailed. It does not throw
27
+ * past the gate, and it does not invent an empty analysis.
28
+ */
29
+ inspect(sql: string): DialectQuestions;
30
+ }
31
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/sql-gate/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAA;AAE1D,MAAM,WAAW,gBAAgB;IAC/B,2BAA2B;IAC3B,cAAc,EAAE,MAAM,CAAA;IACtB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,+DAA+D;IAC/D,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,MAAM,EAAE,OAAO,CAAA;IACf,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,wEAAwE;IACxE,eAAe,EAAE,OAAO,CAAA;IACxB,WAAW,EAAE,OAAO,CAAA;IACpB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;IAC9B;;;OAGG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAAA;CACvC"}
@@ -0,0 +1,9 @@
1
+ /**
2
+ * Questions every SQL dialect must answer. The AST type is not shared.
3
+ * pgsql-ast-parser is an input, not a decision.
4
+ *
5
+ * A dialect that only implements `inspect` is not supported. Support means
6
+ * the C vector set is green against that dialect. This file is the contract.
7
+ */
8
+ export {};
9
+ //# sourceMappingURL=types.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/sql-gate/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}
@@ -0,0 +1,12 @@
1
+ /**
2
+ * Assistant-facing table errors must not distinguish "denied" from "missing".
3
+ * The audit log keeps the real reason. Timing is a residual side channel:
4
+ * a deny never reaches the connector (that stays); a missing table may.
5
+ */
6
+ export declare function tableUnavailableMessage(table: string): string;
7
+ export declare function tableUnavailableError(table: string): Error;
8
+ export declare function tableFromAccessDeny(message: string): string | undefined;
9
+ export declare function isMissingTableMessage(message: string): boolean;
10
+ /** After the real reason is in the audit log, rewrite the assistant error. */
11
+ export declare function publicizeTableError(err: unknown, fallbackTable?: string): never;
12
+ //# sourceMappingURL=table-unavailable.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"table-unavailable.d.ts","sourceRoot":"","sources":["../src/table-unavailable.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,CAE1D;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGvE;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAI9D;AAED,8EAA8E;AAC9E,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,KAAK,CAW/E"}
@@ -0,0 +1,32 @@
1
+ /**
2
+ * Assistant-facing table errors must not distinguish "denied" from "missing".
3
+ * The audit log keeps the real reason. Timing is a residual side channel:
4
+ * a deny never reaches the connector (that stays); a missing table may.
5
+ */
6
+ export function tableUnavailableMessage(table) {
7
+ return `Access to table '${table}' is not available.`;
8
+ }
9
+ export function tableUnavailableError(table) {
10
+ return new Error(tableUnavailableMessage(table));
11
+ }
12
+ export function tableFromAccessDeny(message) {
13
+ const m = message.match(/Access to table '([^']+)' is not permitted by policy/);
14
+ return m?.[1];
15
+ }
16
+ export function isMissingTableMessage(message) {
17
+ return /not found|does not exist|invalid object name|ora-00942|unknown table|unknown relation/i.test(message);
18
+ }
19
+ /** After the real reason is in the audit log, rewrite the assistant error. */
20
+ export function publicizeTableError(err, fallbackTable) {
21
+ const msg = err instanceof Error ? err.message : String(err);
22
+ const denied = tableFromAccessDeny(msg);
23
+ if (denied)
24
+ throw tableUnavailableError(denied);
25
+ if (isMissingTableMessage(msg)) {
26
+ const named = msg.match(/(?:table|relation)\s+(?:not found:\s*)?['"]?([a-zA-Z0-9_.]+)/i)?.[1] ??
27
+ fallbackTable;
28
+ throw tableUnavailableError(named ?? 'unknown');
29
+ }
30
+ throw err;
31
+ }
32
+ //# sourceMappingURL=table-unavailable.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"table-unavailable.js","sourceRoot":"","sources":["../src/table-unavailable.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAa;IACnD,OAAO,oBAAoB,KAAK,qBAAqB,CAAA;AACvD,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,KAAa;IACjD,OAAO,IAAI,KAAK,CAAC,uBAAuB,CAAC,KAAK,CAAC,CAAC,CAAA;AAClD,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,OAAe;IACjD,MAAM,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,sDAAsD,CAAC,CAAA;IAC/E,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;AACf,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,OAAe;IACnD,OAAO,wFAAwF,CAAC,IAAI,CAClG,OAAO,CACR,CAAA;AACH,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,mBAAmB,CAAC,GAAY,EAAE,aAAsB;IACtE,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IAC5D,MAAM,MAAM,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAA;IACvC,IAAI,MAAM;QAAE,MAAM,qBAAqB,CAAC,MAAM,CAAC,CAAA;IAC/C,IAAI,qBAAqB,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/B,MAAM,KAAK,GACT,GAAG,CAAC,KAAK,CAAC,+DAA+D,CAAC,EAAE,CAAC,CAAC,CAAC;YAC/E,aAAa,CAAA;QACf,MAAM,qBAAqB,CAAC,KAAK,IAAI,SAAS,CAAC,CAAA;IACjD,CAAC;IACD,MAAM,GAAG,CAAA;AACX,CAAC"}
package/dist/types.d.ts CHANGED
@@ -18,6 +18,13 @@ export interface GovernancePolicy {
18
18
  maskColumns?: string[];
19
19
  /** Hard cap on rows returned to the AI assistant (default 100). */
20
20
  maxRows?: number;
21
+ /**
22
+ * Which SQL gate the shipped `query` tool uses. Operator declaration —
23
+ * never inferred from the statement. Omitted = `postgres` (today's path)
24
+ * except when a `custom-sql` connector is present: that path requires an
25
+ * explicit dialect. Unknown values reject the config; they do not fall back.
26
+ */
27
+ dialect?: 'postgres' | 'mssql' | 'oracle';
21
28
  /**
22
29
  * Mask names that the text itself marks as names — a title ("Sn. Ahmet
23
30
  * Yılmaz") or a field label ("Yetkili: Ayşe Demir"). Default true.
@@ -127,7 +134,7 @@ export interface AuditConfig {
127
134
  };
128
135
  }
129
136
  export interface ConnectorConfig {
130
- type: 'postgres' | 'supabase' | 'supabase-rest' | 'openapi' | 'files' | 'docs' | 'slack' | 'jira';
137
+ type: 'postgres' | 'supabase' | 'supabase-rest' | 'openapi' | 'files' | 'docs' | 'slack' | 'jira' | 'custom-sql';
131
138
  name: string;
132
139
  description: string;
133
140
  config: Record<string, string>;
@@ -1 +1 @@
1
- {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,174 @@
1
+ # API stability (draft)
2
+
3
+ This is an inventory, not a 1.0 release. Version is 0.2.x. Anything
4
+ unmarked below can still break.
5
+
6
+ **Labels**
7
+
8
+ | Label | Meaning at 0.2.x |
9
+ |---|---|
10
+ | **candidate** | Would be promised at 1.0: break only on a major version, announced in CHANGELOG. |
11
+ | **experimental** | Useful now. Shape can change on a minor. |
12
+ | **internal** | Not an API. Importing it or depending on it is unsupported. |
13
+
14
+ No dates. Shipping 1.0 is a decision, not a document.
15
+
16
+ ---
17
+
18
+ ## What 1.0 would promise
19
+
20
+ - A receipt written as `conarium-receipt/0.3` still verifies with
21
+ `conarium-verify` after a 1.x upgrade. Older published `v` strings
22
+ (`0.1`, `0.2`) stay accepted.
23
+ - Default-deny: missing or empty `policy.allowTables` permits no table.
24
+ A deny list wins over an allow list.
25
+ - The four MCP tools keep their names: `list_tables`, `describe_table`,
26
+ `query`, `search`. Required argument names (`table`, `sql`, `query`)
27
+ stay.
28
+ - `conarium-verify` exit codes in `docs/RECEIPT-SPEC.md` stay.
29
+
30
+ ## What 1.0 would not promise
31
+
32
+ - A JavaScript import surface. `package.json` has `main` pointing at the
33
+ stdio gateway. There is no `exports` map. `import { Governance } from
34
+ '@conarium-ai/core'` is not an API.
35
+ - MySQL. The SQL gate is Postgres, Microsoft SQL Server, and Oracle. Oracle synonyms and database links are not resolved.
36
+ - That an OpenTimestamps stamp is confirmed. `pending` is a valid
37
+ outcome.
38
+ - Console UI layout, playground sample data, or `/api/connectors`
39
+ fixture rows.
40
+ - That a free-text name is masked. See LIMITATIONS.
41
+ - Performance numbers. See `docs/BENCHMARK.md`.
42
+ - Connector types other than `postgres` / `docs` remaining in the
43
+ config enum without change.
44
+
45
+ ## How a breaking change would be announced
46
+
47
+ 1. CHANGELOG, under a major version, names the old shape and the new
48
+ one.
49
+ 2. Receipt schema: a new `v` string. Old strings stay verifiable.
50
+ Fields are not renamed in place.
51
+ 3. MCP / CLI: the old name is rejected with a named error, not a
52
+ silent fallback.
53
+ 4. Config: unknown keys already fail at load (`.strict()`). A removed
54
+ key fails the same way. A changed default that widens access is a
55
+ break even if the key name is unchanged.
56
+
57
+ ---
58
+
59
+ ## CLI (`package.json` `bin`)
60
+
61
+ | Command | Flags / args | Label |
62
+ |---|---|---|
63
+ | `conarium` | `--config <path>` (default `conarium.config.json`) | experimental — stdio MCP entry |
64
+ | `conarium-init` | `--out` `--force` `--no-keys` `--help` | experimental |
65
+ | `conarium-doctor` | `--config` `--no-net` `--help` | experimental |
66
+ | `conarium-verify` | `--pubkey` (repeatable) `--anchor-check` `--anchors` `--expect-seq-from` `--expect-count` `--expect-last-hash` `--json` `--help` | **candidate** (exit codes + flags in RECEIPT-SPEC) |
67
+ | `conarium-coverage` | `--pubkey` `--receipts` `--allow-gaps` `--json` `--help` | experimental |
68
+ | `conarium-reconcile` | `--before` `--after` `--receipts` `--json` `--help` | experimental |
69
+ | `conarium-stamp` | `--sidecar` `--json` `--help` | experimental |
70
+ | `conarium-anchor-upgrade` | `<anchors.jsonl>` | experimental |
71
+ | `conarium-console` | `--config` `--port` `--host` `--install-shortcut` `--uninstall-shortcut` `--launch` `--help` | experimental |
72
+ | `conarium-suggest-policy` | `--sql` `--json` `--help` | experimental |
73
+
74
+ `bin/conarium-anchor-service.mjs` is **not** in `bin`. **internal.**
75
+
76
+ ---
77
+
78
+ ## Config (`conarium.config.json`)
79
+
80
+ Parsed by `src/config.ts` (Zod `.strict()`). Unknown keys reject the file.
81
+
82
+ | Field | Label |
83
+ |---|---|
84
+ | `connectors[]` (`type`, `name`, `description`, `config`) | experimental |
85
+ | `connectors[].type` enum (`postgres`, `supabase`, `supabase-rest`, `openapi`, `files`, `docs`, `slack`, `jira`, `custom-sql`) | experimental — values can be added or removed |
86
+ | `serverName` `serverVersion` `consumer` | experimental |
87
+ | `policy.allowTables` `denyTables` | **candidate** (default-deny, deny wins) |
88
+ | `policy.maskColumns` `maxRows` | experimental (cap ceiling is 10 000 at parse) |
89
+ | `policy.dialect` (`postgres` omitted default, `mssql`, `oracle`) | experimental — unknown values reject the file; not inferred from SQL; required when a `custom-sql` connector is present |
90
+ | `policy.allowConnectors` `denyConnectors` | experimental — empty allow is fail-closed |
91
+ | `policy.allowTools` `denyTools` | experimental |
92
+ | `policy.profiles` `actorProfiles` | experimental |
93
+ | `policy.maskLabelledNames` `scanCharCap` `detectors` `customPatterns` | experimental |
94
+ | `audit.sink` `failClosed` `receiptSink` | experimental |
95
+ | `audit.receiptModel` `audit.receiptClient` | experimental (`source: operator-declared`) |
96
+
97
+ Identity detectors cannot be turned off from config. That rejection is
98
+ **candidate** behaviour.
99
+
100
+ ---
101
+
102
+ ## Receipt JSON
103
+
104
+ Canonical: `docs/RECEIPT-SPEC.md`. Schema string `conarium-receipt/0.3`.
105
+
106
+ | Piece | Label |
107
+ |---|---|
108
+ | Media type `application/vnd.conarium.receipt+json` | **candidate** |
109
+ | Required fields listed in RECEIPT-SPEC (`ts`, `chain`, `sig`, …) | **candidate** |
110
+ | `consentRef` always `null` in 0.3 | **candidate** (field stays; value may change in a later `v`) |
111
+ | `anchor` may be `null` / `pending` | **candidate** |
112
+ | Hash / Ed25519 construction | **candidate** |
113
+ | Adding optional fields in a new `v` | allowed |
114
+ | Renaming or removing a field inside `0.3` | break |
115
+
116
+ ---
117
+
118
+ ## MCP tools
119
+
120
+ | Tool | Params | Label |
121
+ |---|---|---|
122
+ | `list_tables` | `connector?` | **candidate** name; params experimental |
123
+ | `describe_table` | `table` (required), `connector?` | **candidate** name; `table` required |
124
+ | `query` | `sql` (required), `connector?` | **candidate** name; `sql` required |
125
+ | `search` | `query` (required), `tables?`, `connector?` | **candidate** name; `query` required |
126
+
127
+ Tool presence can still be filtered by `policy.allowTools` /
128
+ `denyTools`. That filter is experimental.
129
+
130
+ HTTP MCP (not a `bin` name): `CONARIUM_MCP_TOKEN` (required, ≥24),
131
+ `CONARIUM_MCP_HOST`, `CONARIUM_MCP_PORT`, `CONARIUM_MCP_RATE_PER_MIN`.
132
+ **experimental.**
133
+
134
+ ---
135
+
136
+ ## Console HTTP
137
+
138
+ Loopback operator UI (`conarium-console`). Not a public API.
139
+
140
+ | Route | Label |
141
+ |---|---|
142
+ | `GET /handoff?n=` | experimental |
143
+ | `GET /api/presence` | experimental |
144
+ | `GET /api/receipts` | experimental |
145
+ | `GET /api/receipts/:id` | experimental |
146
+ | `GET /api/receipts/:id/raw` | experimental |
147
+ | `GET /api/receipts/:id/html` | experimental |
148
+ | `GET /api/config` `POST /api/config` | experimental |
149
+ | `GET /api/audit` | experimental |
150
+ | `POST /api/playground` | experimental — in-memory sample rows |
151
+ | `GET /api/connectors` | **internal** — fixture JSON, not live connectors |
152
+ | static `/` and `/assets` | internal |
153
+
154
+ Env: `CONARIUM_CONSOLE_HOST`, `CONARIUM_CONSOLE_PORT`,
155
+ `CONARIUM_CONSOLE_RATE_PER_MIN`. experimental.
156
+
157
+ ---
158
+
159
+ ## Package exports
160
+
161
+ | Entry | Label |
162
+ |---|---|
163
+ | `bin` map above | see CLI |
164
+ | `"main": "./dist/index.js"` | experimental — process entry, not a library |
165
+ | `exports` field | **absent** |
166
+ | `dist/governance.js`, `dist/ots/*`, `dist/http.js`, … | **internal** |
167
+ | TypeScript types in `src/types.ts` | **internal** until an `exports` map exists |
168
+
169
+ ---
170
+
171
+ ## 1.0 is not this file
172
+
173
+ This inventory is input. It does not ship a version, set a date, or
174
+ freeze the tree.
@@ -0,0 +1,144 @@
1
+ # Benchmark — Conarium overhead
2
+
3
+ What is measured: **the cost Conarium adds**, not how fast a machine is.
4
+
5
+ Headline numbers are **p50 / p95 / p99**. Mean is not reported.
6
+
7
+ Replay:
8
+
9
+ ```
10
+ # temporary Postgres (WSL Docker on this machine)
11
+ docker run -d --name conarium-bench-pg \
12
+ -e POSTGRES_USER=conarium -e POSTGRES_PASSWORD=demo-not-a-secret \
13
+ -e POSTGRES_DB=conarium_bench -p 54329:5432 postgres:16-alpine
14
+
15
+ CONARIUM_BENCH_DSN=postgres://conarium:demo-not-a-secret@127.0.0.1:54329/conarium_bench \
16
+ npm run bench:overhead
17
+
18
+ docker rm -f conarium-bench-pg
19
+ ```
20
+
21
+ Raw JSON: [`benchmarks/latest.json`](benchmarks/latest.json)
22
+ (this run: [`benchmarks/overhead-20260814T1346Z-linux.json`](benchmarks/overhead-20260814T1346Z-linux.json)).
23
+
24
+ No competitor numbers. n=15 cells have a thin tail (p95 = p99).
25
+
26
+ ---
27
+
28
+ ## This run
29
+
30
+ | | |
31
+ |---|---|
32
+ | CPU | Intel Core Ultra 9 275HX × 24 |
33
+ | RAM visible | 16 GB (WSL2) |
34
+ | OS | WSL2 Ubuntu, linux 6.18.33.2 |
35
+ | Node | v18.19.1 |
36
+ | Postgres | 16.14 (postgres:16-alpine) |
37
+ | Dataset | 5 000 rows, distinct email per row |
38
+ | When | 2026-08-14T13:46Z |
39
+
40
+ `maxRows` falls back to **100** in code when the policy leaves it unset; the
41
+ `conarium.config.json` shipped with the package sets **50**. A fresh install
42
+ therefore runs at 50. Measurements below use 100 as the conservative case —
43
+ a fresh install is faster, not slower. Caps measured: 100 · 500 · 5 000.
44
+
45
+ Two series, same user SQL both sides:
46
+
47
+ - **same-sql** — no `LIMIT` in the user query. Conarium adds `maxRows`. Direct
48
+ returns 5 000 rows. A negative delta is the cap, not a faster mask.
49
+ - **same-limit** — user SQL already has `LIMIT = maxRows`. Same row count.
50
+ This is the gate tax.
51
+
52
+ Deny must not hit Postgres. It did not.
53
+
54
+ ---
55
+
56
+ ## same-limit (same row count) — the number to quote
57
+
58
+ ### allow (no mask)
59
+
60
+ | maxRows | direct p50 | conarium p50 | overhead p50 / p95 / p99 | n |
61
+ |---|---|---|---|---|
62
+ | 100 | 0.427 ms | 3.798 ms | **2.850 / 3.731 / 4.191** | 50 |
63
+ | 500 | 1.069 ms | 9.257 ms | **7.973 / 11.117 / 11.545** | 50 |
64
+ | 5 000 | 5.660 ms | 73.885 ms | **69.242 / 85.116 / 85.116** | 15 |
65
+
66
+ ### partial (email masked)
67
+
68
+ | maxRows | direct p50 | conarium p50 | overhead p50 / p95 / p99 | n |
69
+ |---|---|---|---|---|
70
+ | 100 | 0.577 ms | 5.968 ms | **5.006 / 6.730 / 7.099** | 50 |
71
+ | 500 | 0.950 ms | 88.363 ms | **86.615 / 112.802 / 341.147** | 50 |
72
+ | 5 000 | 4.828 ms | 21787 ms | **21770 / 25581 / 25581** | 15 |
73
+
74
+ Conservative default (100 rows, masked): **about 5 ms added**. The shipped
75
+ config caps at 50, so a fresh install stays below this figure.
76
+ 500 distinct emails: **about 87 ms**. 5 000: **about 22 s**.
77
+
78
+ ### deny
79
+
80
+ | maxRows | conarium p50 | query ran |
81
+ |---|---|---|
82
+ | 100 | 0.432 ms | no |
83
+ | 500 | 0.404 ms | no |
84
+ | 5 000 | 0.396 ms | no |
85
+
86
+ ---
87
+
88
+ ## same-sql (user query has no LIMIT)
89
+
90
+ Direct always returns 5 000 rows. Conarium returns `maxRows`.
91
+
92
+ | scenario | maxRows | direct p50 | conarium p50 | overhead p50 | rows in / out |
93
+ |---|---|---|---|---|---|
94
+ | allow | 100 | 4.023 | 3.444 | **−1.592** | 5000 → 100 |
95
+ | allow | 500 | 4.411 | 9.147 | 3.943 | 5000 → 500 |
96
+ | allow | 5 000 | 4.511 | 78.854 | 73.775 | 5000 → 5000 |
97
+ | partial | 100 | 5.862 | 6.926 | 1.824 | 5000 → 100 |
98
+ | partial | 500 | 6.177 | 90.215 | 84.854 | 5000 → 500 |
99
+ | partial | 5 000 | 5.856 | 19301 | 19289 | 5000 → 5000 |
100
+
101
+ The −1.6 ms cell is the row cap doing less I/O. It is not a claim that
102
+ masking is free.
103
+
104
+ ---
105
+
106
+ ## In-process redact (WSL, unique email per row)
107
+
108
+ Not a substitute for the table above. Shows the same cliff without a socket.
109
+
110
+ | distinct emails | p50 | p95 | p99 | n |
111
+ |---|---|---|---|---|
112
+ | 50 | 1.137 ms | 2.018 | 3.066 | 50 |
113
+ | 100 | 2.678 ms | 5.821 | 8.998 | 50 |
114
+ | 500 | 76.381 ms | 113.928 | 123.534 | 50 |
115
+
116
+ ---
117
+
118
+ ## Warning threshold
119
+
120
+ `docs/benchmarks/masking-cost-threshold.json` → **warn above 100**.
121
+
122
+ 100 is the last measured point still in the low-millisecond band
123
+ (same-limit partial overhead p50 = 5.0 ms). 500 is already 87 ms.
124
+ The doctor and `parseConariumConfig` warn. They do not reject the query.
125
+
126
+ ---
127
+
128
+ ## Concurrency (in-process, not Hetzner)
129
+
130
+ Replay: `node scripts/benchmark-concurrency.mjs` (needs `npm run build`).
131
+ Raw: [`benchmarks/concurrency-20260814.json`](benchmarks/concurrency-20260814.json).
132
+
133
+ | | |
134
+ |---|---|
135
+ | CPU | Intel Core Ultra 9 275HX × 24 |
136
+ | RAM | 32 GB |
137
+ | OS | win32 10.0.26200 |
138
+ | Node | v24.5.0 |
139
+ | N | 50 concurrent MCP `query` (mock connector) |
140
+ | When | 2026-08-14T18:19Z |
141
+
142
+ p50 **45.5 ms** · p95 **48.6 ms** · p99 **61.3 ms** · wall **98 ms** · error rate **0**.
143
+ Single `Audit` instance: 50 entries, **0** `prevHash` breaks (`log()` is synchronous).
144
+ This is not a leak hunt and not a two-process sink race.
@@ -0,0 +1,69 @@
1
+ # E2E health — 2026-08-14
2
+
3
+ O2. No refactor. Push / npm / Hetzner yok.
4
+
5
+ ## a) Regresyon — temiz
6
+
7
+ | Komut | Sonuç |
8
+ |--|--|
9
+ | `vitest run` | **483 geçti / 1 skip** (console-shortcut) |
10
+ | `npm run test:checks` | **28/28** |
11
+
12
+ Postgres `Governance.guardQuery` hâlâ `pgsql-ast-parser` + `sql-gate/rules` + `sql-gate/postgres`. MSSQL/Oracle ayrı fonksiyon; o yol değişmedi.
13
+
14
+ ## b) Performans — temiz (karşılaştırma notu)
15
+
16
+ `docs/BENCHMARK.md` alıntısı: same-limit partial, maxRows=100, ~**5 ms** (linux 2026-08-14T13:46Z: p50 **5.006** / p95 6.730 / p99 7.099).
17
+
18
+ Bu tur: `docs/benchmarks/overhead-20260814T1644Z-win32.json` (Windows Node → Docker Postgres 16).
19
+
20
+ | | eski p50 (linux) | yeni p50 (win32) |
21
+ |--|--|--|
22
+ | same-limit allow 100 | 2.850 ms | 1.992 ms |
23
+ | same-limit partial 100 | **5.006 ms** | **3.158 ms** |
24
+ | in-process guard allow | (yok / ayrı) | 0.359 ms |
25
+
26
+ Ortak katman ayrımı guard yoluna ölçülebilir ek vergi koymadı. OS farklı; “ürün hızlandı” iddiası yok. 5 000 satır maskeli hâlâ saniye mertebesi (eski ~22 s linux / yeni ~7 s win32) — bilinen maliyet, yeni tıkanma değil.
27
+
28
+ ## c) Uçtan uca zincir — temiz (kısmi bakılamadı)
29
+
30
+ | Halka | Kanıt | Durum |
31
+ |--|--|--|
32
+ | sorgu → kapı | `governance.rowcap.test.ts`, `vectors.test.ts` postgres 28/28, `src/server.ts` `governance.guardQuery` | temiz |
33
+ | maskeleme | `governance.masking.test.ts`, `http_gateway.e2e.mjs` search → `[MASKED_PII]`, email sızmıyor | temiz |
34
+ | makbuz | `audit.receipt.test.ts`, e2e receipts 0→1 | temiz |
35
+ | zincir | `audit.chain.test.ts` | temiz |
36
+ | `conarium-verify` | e2e `verify exit 0` + `/verified/` | temiz |
37
+ | panel | `console_receipts_tab.mjs` + `/api/receipts` (`console.ts`) | temiz (DOM sözleşmesi) |
38
+
39
+ **Bakılamadı:** tarayıcıda, aynı süreçte üretilmiş bir makbuzun panele tıklanması. HTTP e2e SQL `query` aracını değil `search` (docs) yolunu koşuyor. MSSQL/Oracle’ın MCP `query` üzerinden seçilmesi — konnektör yok.
40
+
41
+ ## d) Ölü kod / çift kaynak — bulgu
42
+
43
+ | Bulgu | Kanıt | Etki | Öneri | Aciliyet |
44
+ |--|--|--|--|--|
45
+ | MCP `query` yalnız Postgres kapısı | `src/server.ts` `governance.guardQuery`; `console.ts` aynı. `guardMssqlQuery` / `guardOracleQuery` yalnız test + live betik | Beyan “SQL kapısı Oracle/MSSQL” doğru; **dağıtılan araç T-SQL/Oracle SQL’i Postgres parser’a verir** (fail-closed veya yanlış AST) | Lehçe seçimi ayrı karar. LIMITATIONS’a yazıldı | yüksek (iddia/yol) |
46
+ | `matchGlob` üç kopya | `governance.ts` `match`, `mssql.ts`, `oracle.ts` | Kural sapması riski | Tek fonksiyon | düşük |
47
+ | `*Adapter.inspect` sunucuda kullanılmıyor | yalnız `*.test.ts` | Ölü yüzey, zarar yok | Bırak veya bağla | düşük |
48
+
49
+ ## e) `conarium-doctor` — bulgu
50
+
51
+ `node bin/conarium-doctor.mjs --no-net` (repo `conarium.config.json`):
52
+
53
+ - `maxRows: 50` eşik altı (100) → **uyarı yok** (doğru; eşiği görüyor).
54
+ - Lehçe (MSSQL/Oracle) **yok**.
55
+ - Özel PII deseni **yok** (config’de de yok).
56
+ - FAIL: `DATABASE_READONLY_DSN` set değil — beklenen boş kurulum.
57
+ - WARN: imza anahtarı yok.
58
+
59
+ Yeni lehçeler doctorda sessiz.
60
+
61
+ ## f) Paket bütünlüğü — temiz (not)
62
+
63
+ `npm pack --dry-run`: `dist/sql-gate/{mssql,oracle,postgres,rules,types}.js` + `test-vectors/sql-gate/vectors.json` + `LIMITATIONS.md` var. Live betikler (`test/sql-gate-*-live.mjs`) pakette yok (doğru). `docs/audit/2026-08-14-*.md` tarball’a giriyor — müşteri verisi değil, gürültü.
64
+
65
+ ## Bakılamayan
66
+
67
+ - Canlı panel tıklaması (yukarı).
68
+ - MSSQL/Oracle MCP `query` (konnektör yok).
69
+ - `test:checks` 28; paket metni bazen “27” demişti — sayı 28, drift değil bu turda.