@ekanos/sdk 0.1.1 → 0.1.2

package/eslint.preset.mjs

@@ -0,0 +1,375 @@
+/**
+ * @ekanos/sdk/eslint — the capability ESLint preset ("R5").
+ *
+ * This is a SECURITY CONTROL, not a style preset. Partner integration code
+ * runs UNSANDBOXED, in-process, inside the host: the generated
+ * `partner-integration-bootstrap.ts` statically imports each partner package,
+ * so a partner module graph evaluates with full host authority before any
+ * validation runs (see the "Trust model (F1, accepted T1)" header in
+ * `apps/web/scripts/generate-partner-integration-bootstrap.ts`).
+ *
+ * The accepted T1 trust tier rests on exactly two controls:
+ *
+ *   1. the promotion gate — a human reads the SOURCE before it is built, and
+ *   2. THIS PRESET — which bans the escapes that route around the capability
+ *      layer, so "reads the source" is a tractable review rather than an
+ *      invitation to spot `globalThis.fetch` by eye.
+ *
+ * Runtime SANDBOXING of handlers is the deferred T3 tier. Until it exists,
+ * every rule below is load-bearing. Docs: `docs/devex/sdk-export-map.md`
+ * (review outcome F1), `docs/devex/adversarial-review-2026-08-30.md`.
+ *
+ * ── Why it lives here ────────────────────────────────────────────────────
+ * A partner already installs `@ekanos/sdk`, so the control ships with the
+ * surface it protects and versions in lockstep with it: the day `ctx.fetch`
+ * grows a documented client-side twin, the fetch rule relaxes in the same
+ * release. It is dependency-free — every rule below is core ESLint — so it
+ * adds nothing to the SDK's build, `api-report`, or `pack:test`.
+ *
+ * ── Usage (a partner's eslint.config.mjs) ────────────────────────────────
+ *
+ *   import capabilityPreset from '@ekanos/sdk/eslint';
+ *
+ *   export default [
+ *     ...someBaseConfig,
+ *     ...capabilityPreset,
+ *   ];
+ *
+ * ── Inline disables do not work, by design ───────────────────────────────
+ * The preset sets `linterOptions.noInlineConfig` over the source glob, so
+ * `// eslint-disable-next-line` cannot silence these rules from partner
+ * source — otherwise the control would be opt-out by the very code it
+ * constrains. A genuine exception must be a FILE-SCOPED OVERRIDE in the
+ * package's own `eslint.config.mjs`, where a reviewer reads it. Both
+ * exceptions currently granted in this repo live in the example packages'
+ * configs and are recorded there with the reason.
+ */
+
+/**
+ * Glob for partner integration SOURCE. Build tooling — `vitest.config.ts`,
+ * `eslint.config.mjs`, `tsup.config.ts` — is deliberately OUT of scope: it
+ * runs on the partner's build machine, never in the host process, and it
+ * legitimately imports `node:path`/`node:url`. Narrowing the preset to source
+ * is what keeps it free of the false positives that get a control disabled.
+ */
+const SOURCE_GLOB = ['src/**/*.ts', 'src/**/*.tsx'];
+
+const CTX_FETCH_REMEDIATION =
+  'Use `ctx.fetch` from the capability context (`IntegrationContext`) instead, ' +
+  "and declare every origin you call in your integration's `egress` " +
+  'allowlist — `defineIntegration({ egress: [...] })`. `ctx.fetch` refuses an ' +
+  'undeclared origin before any I/O, re-checks every redirect hop, and pins ' +
+  'the vetted IP addresses so an allowlisted hostname cannot be rebound to a ' +
+  'host-internal address. A global fetch has none of that, so it is an egress ' +
+  'bypass. Widening `egress` is a reviewed security-posture change, not a ' +
+  'config tweak.';
+
+const CTX_SECRETS_REMEDIATION =
+  'Use `ctx.secrets.get(name)` from the capability context instead, and ' +
+  "declare the credential in your integration's activation schema. The host " +
+  "process environment holds the platform's own credentials — it is not your " +
+  'configuration store, and reading it is how an integration gets a secret it ' +
+  'was never granted.';
+
+/**
+ * Node builtins a partner integration must never reach, each with the
+ * capability that replaces it. Every entry is listed twice — bare and
+ * `node:`-prefixed — because both resolve.
+ *
+ * This is an explicit list rather than a blanket `node:*` ban on purpose: the
+ * SDK surface is isomorphic, and `node:crypto`/`node:url`-shaped imports are
+ * neither an escape nor worth training a partner to reach for a disable
+ * comment over. The generic escape hatch — a computed dynamic `import()` — is
+ * closed separately in `no-restricted-syntax` below, so the list cannot be
+ * routed around by building the specifier at runtime.
+ */
+const BANNED_MODULES = [
+  {
+    names: ['fs', 'node:fs', 'fs/promises', 'node:fs/promises'],
+    message:
+      'The host filesystem is not part of the capability surface. Use ' +
+      '`ctx.storage.account` / `ctx.storage.user` for integration state — it ' +
+      'is scoped to the account the request is authorized for, quota-bounded, ' +
+      'and schema-validated. Filesystem access reads and writes host state ' +
+      'that no account owns.',
+  },
+  {
+    names: ['child_process', 'node:child_process'],
+    message:
+      'Spawning a process escapes every capability control at once. There is ' +
+      'no replacement: an integration is data-in / data-out. If you need work ' +
+      "the SDK cannot express, raise it as an SDK gap in your integration's " +
+      'README rather than shelling out.',
+  },
+  {
+    names: [
+      'net',
+      'node:net',
+      'tls',
+      'node:tls',
+      'dgram',
+      'node:dgram',
+      'http',
+      'node:http',
+      'https',
+      'node:https',
+      'http2',
+      'node:http2',
+    ],
+    message:
+      'Raw sockets and the `http`/`https` clients bypass the egress allowlist ' +
+      'and its address guard entirely. ' +
+      CTX_FETCH_REMEDIATION,
+  },
+  {
+    names: ['dns', 'node:dns', 'dns/promises', 'node:dns/promises'],
+    message:
+      'Resolving hostnames yourself is the first half of a DNS-rebinding ' +
+      'egress bypass — `ctx.fetch` resolves ONCE and pins the vetted ' +
+      'addresses precisely so that a name cannot resolve differently between ' +
+      'the check and the connection. ' +
+      CTX_FETCH_REMEDIATION,
+  },
+  {
+    names: ['worker_threads', 'node:worker_threads'],
+    message:
+      'A worker thread runs on a path where the capability context does not ' +
+      'exist, so nothing inside it can reach `ctx.fetch`, `ctx.secrets` or ' +
+      '`ctx.storage`. Do the work in the handler, with `ctx`, and let the ' +
+      'host own concurrency — batch or paginate rather than fanning out.',
+  },
+  {
+    names: ['vm', 'node:vm'],
+    message:
+      '`vm` executes code from a string, which makes the source a reviewer ' +
+      'reads no longer the code that runs — the assumption the T1 trust tier ' +
+      'is built on. Write the logic as source.',
+  },
+  {
+    names: ['module', 'node:module'],
+    message:
+      '`node:module` (`createRequire`) is a loader escape hatch: it resolves ' +
+      'modules this preset bans by name at runtime. Use a static `import` of ' +
+      'a package you declare in `dependencies`.',
+  },
+  {
+    names: ['process', 'node:process'],
+    message:
+      'Importing `process` reaches the host environment. ' +
+      CTX_SECRETS_REMEDIATION,
+  },
+  {
+    names: ['os', 'node:os'],
+    message:
+      '`node:os` reports the host machine — hostname, users, network ' +
+      'interfaces, home directories. None of it describes the account your ' +
+      'integration is running for, and all of it is host reconnaissance. ' +
+      'Read what you need from the capability context instead: ' +
+      '`ctx.accountId` for who this run is for, `ctx.storage` for state you ' +
+      'persisted, `ctx.logger` for diagnostics.',
+  },
+  {
+    names: ['undici', 'node-fetch', 'axios', 'got', 'superagent', 'request'],
+    message:
+      'A third-party HTTP client issues requests the egress allowlist never ' +
+      'sees, which is the same bypass as a global `fetch` with an extra ' +
+      'dependency. ' +
+      CTX_FETCH_REMEDIATION,
+  },
+  {
+    names: ['react-i18next'],
+    importNames: ['Trans'],
+    message:
+      'Use `Trans` from `@ekanos/ui/trans` instead — it is wired to the ' +
+      "host's i18n instance, so your strings resolve against the same " +
+      'namespaces and language the surrounding page already loaded.',
+  },
+];
+
+/** Globals that reach the network without passing through `ctx.fetch`. */
+const EGRESS_GLOBALS = ['fetch', 'XMLHttpRequest', 'WebSocket', 'EventSource'];
+
+/** Objects a `globalThis.fetch`-style member access can hide behind. */
+const GLOBAL_OBJECTS = 'globalThis|window|self|global';
+
+/** Members of those objects that are the very escapes banned as bare globals. */
+const GLOBAL_ESCAPE_MEMBERS =
+  'fetch|XMLHttpRequest|WebSocket|EventSource|process|eval|require|Function';
+
+/**
+ * `@kit/*` is checked with a PATTERN rather than a path so every subpath is
+ * covered (`@kit/ui/badge`, `@kit/next/actions`, …). This is the rule that
+ * catches, at lint time in the partner's own editor, the failure that
+ * otherwise surfaces as an unresolvable module at install time — which is
+ * exactly how our own reference example turned out to be unbuildable outside
+ * the monorepo.
+ */
+const KIT_PATTERN = {
+  group: ['@kit/*', '@kit/*/**'],
+  message:
+    '`@kit/*` packages are workspace-internal to the Fusion monorepo and do ' +
+    'not exist on any registry, so this import cannot resolve for anyone ' +
+    'outside it — including in the clean-room build your submission is gated ' +
+    'on. Import UI primitives from `@ekanos/ui/*` (badge, button, card, form, ' +
+    'input, select, icon, utils, …), integration surfaces from `@ekanos/sdk` ' +
+    'and its `/components`, `/hooks`, `/mcp`, `/context`, `/integration` ' +
+    'entrypoints, and nothing else from the host.',
+};
+
+const SUPABASE_PATTERN = {
+  group: ['@supabase/*', '@supabase/*/**'],
+  message:
+    'A direct Supabase client talks to the database with whatever key it is ' +
+    'given, outside the account scoping and RLS the host applies for you. Use ' +
+    '`ctx.storage.account` / `ctx.storage.user` for integration state — ' +
+    'authorized for the account in the request and validated against your ' +
+    'declared schema.',
+};
+
+/** Flattens BANNED_MODULES into `no-restricted-imports` `paths` entries. */
+function bannedPaths() {
+  return BANNED_MODULES.flatMap((entry) =>
+    entry.names.map((name) => ({
+      name,
+      message: entry.message,
+      ...(entry.importNames ? { importNames: entry.importNames } : {}),
+    })),
+  );
+}
+
+/**
+ * The rules, exported separately so a consumer can compose them into its own
+ * config block (a different `files` glob, say) without re-deriving them.
+ */
+export const capabilityRules = {
+  /**
+   * Bare global references only. ESLint resolves scope first, so a parameter
+   * or local named `fetch` — the SDK's own `IntegrationFetch` injection
+   * pattern, `getJson(fetch, url)` — is NOT reported. That is the intended
+   * shape: pass the mediated fetch in as a value.
+   */
+  'no-restricted-globals': [
+    'error',
+    ...EGRESS_GLOBALS.map((name) => ({
+      name,
+      message: `\`${name}\` reaches the network outside the capability layer. ${CTX_FETCH_REMEDIATION}`,
+    })),
+    {
+      name: 'process',
+      message: `\`process\` (including \`process.env\`) is host state, not integration state. ${CTX_SECRETS_REMEDIATION}`,
+    },
+    {
+      name: 'require',
+      message:
+        '`require` resolves modules at runtime, so no reviewer and no import ' +
+        'rule can see what is actually loaded. Use a static `import` of a ' +
+        'package declared in `dependencies`.',
+    },
+    {
+      name: 'eval',
+      message:
+        '`eval` runs code built at runtime, so the source a reviewer reads ' +
+        'stops being the code that runs — and human review of source is half ' +
+        'of what makes running your integration in-process acceptable. Write ' +
+        'the logic as source.',
+    },
+  ],
+
+  'no-restricted-imports': [
+    'error',
+    { paths: bannedPaths(), patterns: [KIT_PATTERN, SUPABASE_PATTERN] },
+  ],
+
+  'no-restricted-syntax': [
+    'error',
+    {
+      // Closes the hole in no-restricted-globals: that rule resolves
+      // identifiers, so `globalThis.fetch` (a member access, not a global
+      // reference) is invisible to it.
+      selector: `MemberExpression[object.name=/^(${GLOBAL_OBJECTS})$/][property.name=/^(${GLOBAL_ESCAPE_MEMBERS})$/]`,
+      message:
+        'Reaching an escape through the global object is the same bypass as ' +
+        'naming it directly, and it is how a capability control gets routed ' +
+        'around without tripping an import rule. Use the capability context: ' +
+        '`ctx.fetch` for network calls (with the origin declared in `egress`) ' +
+        'and `ctx.secrets` for credentials.',
+    },
+    {
+      // Computed-string member access, e.g. `globalThis['fetch']`.
+      selector: `MemberExpression[computed=true][object.name=/^(${GLOBAL_OBJECTS})$/]`,
+      message:
+        'Indexing the global object with a computed key hides which global is ' +
+        'being reached, which defeats every rule in this preset. Reference ' +
+        'what you need directly, through the capability context — `ctx.fetch` ' +
+        'for network calls, `ctx.secrets` for credentials, `ctx.storage` for ' +
+        'state.',
+    },
+    {
+      selector: 'NewExpression[callee.name="Function"]',
+      message:
+        '`new Function` compiles code from a string — the same problem as ' +
+        '`eval`: the source under review is no longer the code that runs. ' +
+        'Write the logic as source.',
+    },
+    {
+      selector: 'CallExpression[callee.name="Function"]',
+      message:
+        '`Function(...)` compiles code from a string — the same problem as ' +
+        '`eval`: the source under review is no longer the code that runs. ' +
+        'Write the logic as source.',
+    },
+    {
+      // The generic route around no-restricted-imports: build the specifier
+      // at runtime and the import rule has nothing to match.
+      selector: 'ImportExpression[source.type!="Literal"]',
+      message:
+        'A dynamic `import()` with a computed specifier hides what is loaded ' +
+        'from both the import rules and the human promotion review. Use a ' +
+        'static `import`, or `import("literal-specifier")` if you genuinely ' +
+        'need lazy loading.',
+    },
+    {
+      // `no-restricted-imports` does not inspect dynamic import specifiers,
+      // so the banned module list is re-applied to literal ones here.
+      selector:
+        'ImportExpression[source.value=/^(node:)?(fs|child_process|net|tls|dgram|dns|http|https|http2|worker_threads|vm|module|process|os)$/]',
+      message:
+        'This Node builtin is banned for integration code whether it is ' +
+        'imported statically or dynamically — a dynamic `import()` of it is ' +
+        'the same capability escape. See the static-import message for the ' +
+        'capability that replaces it (`ctx.fetch`, `ctx.secrets`, ' +
+        '`ctx.storage`).',
+    },
+    {
+      // The `/promises` faces of the same builtins. Split out because a `/`
+      // cannot appear inside an esquery regex-literal attribute value.
+      selector:
+        'ImportExpression[source.value=/^(node:)?(fs|dns)\\u002Fpromises$/]',
+      message:
+        'This Node builtin is banned for integration code whether it is ' +
+        'imported statically or dynamically. Use `ctx.storage` for state and ' +
+        '`ctx.fetch` for network calls.',
+    },
+  ],
+};
+
+/**
+ * The preset. Spread it AFTER any base config: it deliberately replaces a
+ * base `no-restricted-imports` / `no-restricted-globals` /
+ * `no-restricted-syntax` setting rather than merging with it (flat config does
+ * not merge rule options), and it re-states the one entry the Fusion base
+ * config carries — `react-i18next`'s `Trans` — in its partner-correct form.
+ */
+export default [
+  {
+    name: '@ekanos/sdk/eslint:capabilities',
+    files: SOURCE_GLOB,
+    linterOptions: {
+      // A control the constrained code can switch off is not a control.
+      // Exceptions belong in the consumer's config, where review sees them.
+      // See the header.
+      noInlineConfig: true,
+    },
+    rules: capabilityRules,
+  },
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekanos/sdk",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "description": "The official SDK for building Ekanos integrations.",
   "license": "MIT",
@@ -13,7 +13,8 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "eslint.preset.mjs"
   ],
   "exports": {
     ".": {
@@ -43,7 +44,8 @@
     "./integration": {
       "types": "./dist/integration/index.d.ts",
       "default": "./dist/integration/index.js"
-    }
+    },
+    "./eslint": "./eslint.preset.mjs"
   },
   "publishConfig": {
     "access": "public"
@@ -51,8 +53,8 @@
   "dependencies": {
     "@supabase/supabase-js": "2.87.1",
     "server-only": "^0.0.1",
-    "@ekanos/integration-schema": "0.1.1",
-    "@ekanos/ui": "0.1.1"
+    "@ekanos/integration-schema": "0.1.2",
+    "@ekanos/ui": "0.1.2"
   },
   "peerDependencies": {
     "@hookform/resolvers": "^5.2.2",
@@ -72,9 +74,9 @@
     "typescript": "^5.9.3",
     "vitest": "4.1.10",
     "zod": "^3.25.74",
-    "@kit/eslint-config": "0.2.0",
     "@kit/prettier-config": "0.1.0",
-    "@kit/tsconfig": "0.1.0"
+    "@kit/tsconfig": "0.1.0",
+    "@kit/eslint-config": "0.2.0"
   },
   "prettier": "@kit/prettier-config",
   "typesVersions": {