@ekanos/sdk 0.1.0

package/dist/integration/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @ekanos/sdk/integration — the partner authoring contract.
+ *
+ * `defineIntegration()` is THE way a partner declares an integration
+ * (adversarial review outcome 3: partners never extend `BaseIntegration`).
+ * The host adapts the returned definition internally via
+ * `registerPartnerIntegration` in `@kit/integrations-core`, which re-parses
+ * against the SAME canonical schema (`@ekanos/integration-schema`) at the
+ * trust boundary — one contract, no structural twin (F3/F9).
+ *
+ * Dependency-pure and isomorphic: zod plus the schema package, no `@kit/*`,
+ * no `server-only`.
+ *
+ * Surface discipline: additions require an entry in
+ * docs/devex/sdk-export-map.md ("`@ekanos/sdk/integration`").
+ */
+export { defineIntegration } from './define-integration.js';
+export { parseCronExpression } from './cron.js';
+export { IntegrationDefinitionSchema, validateIntegrationDefinitions, } from '@ekanos/integration-schema';
+export type { IntegrationDefinition, IntegrationComponentDeclarations, IntegrationProposals, IntegrationCapabilityDeclaration, IntegrationPermissionDeclaration, PartnerWidgetDeclaration, PartnerToolModule, PartnerToolParameters, ToolClassificationProposal, DefinitionCollisionInput, FirstPartyInventory, PartnerWebhookDeclaration, WebhookSignatureDeclaration, WebhookEvent, WebhookResult, PartnerScheduleDeclaration, ScheduleInvocation, ScheduleResult, PartnerOAuthDeclaration, OAuthProviderDeclaration, OAuthTokens, } from '@ekanos/integration-schema';

package/dist/integration/index.js

@@ -0,0 +1,23 @@
+/**
+ * @ekanos/sdk/integration — the partner authoring contract.
+ *
+ * `defineIntegration()` is THE way a partner declares an integration
+ * (adversarial review outcome 3: partners never extend `BaseIntegration`).
+ * The host adapts the returned definition internally via
+ * `registerPartnerIntegration` in `@kit/integrations-core`, which re-parses
+ * against the SAME canonical schema (`@ekanos/integration-schema`) at the
+ * trust boundary — one contract, no structural twin (F3/F9).
+ *
+ * Dependency-pure and isomorphic: zod plus the schema package, no `@kit/*`,
+ * no `server-only`.
+ *
+ * Surface discipline: additions require an entry in
+ * docs/devex/sdk-export-map.md ("`@ekanos/sdk/integration`").
+ */
+export { defineIntegration } from './define-integration.js';
+// Event-surface validation values: the 5-field cron parser backing
+// `defineIntegration()`'s schedule validation, exported so validators and
+// the harness can check/describe an expression the same way the SDK does.
+export { parseCronExpression } from './cron.js';
+export { IntegrationDefinitionSchema, validateIntegrationDefinitions, } from '@ekanos/integration-schema';
+//# sourceMappingURL=index.js.map

package/dist/integration/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/integration/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAEzD,mEAAmE;AACnE,0EAA0E;AAC1E,0EAA0E;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AAE7C,OAAO,EACL,2BAA2B,EAC3B,8BAA8B,GAC/B,MAAM,4BAA4B,CAAC","sourcesContent":["/**\n * @ekanos/sdk/integration — the partner authoring contract.\n *\n * `defineIntegration()` is THE way a partner declares an integration\n * (adversarial review outcome 3: partners never extend `BaseIntegration`).\n * The host adapts the returned definition internally via\n * `registerPartnerIntegration` in `@kit/integrations-core`, which re-parses\n * against the SAME canonical schema (`@ekanos/integration-schema`) at the\n * trust boundary — one contract, no structural twin (F3/F9).\n *\n * Dependency-pure and isomorphic: zod plus the schema package, no `@kit/*`,\n * no `server-only`.\n *\n * Surface discipline: additions require an entry in\n * docs/devex/sdk-export-map.md (\"`@ekanos/sdk/integration`\").\n */\n\nexport { defineIntegration } from './define-integration';\n\n// Event-surface validation values: the 5-field cron parser backing\n// `defineIntegration()`'s schedule validation, exported so validators and\n// the harness can check/describe an expression the same way the SDK does.\nexport { parseCronExpression } from './cron';\n\nexport {\n  IntegrationDefinitionSchema,\n  validateIntegrationDefinitions,\n} from '@ekanos/integration-schema';\n\nexport type {\n  IntegrationDefinition,\n  IntegrationComponentDeclarations,\n  IntegrationProposals,\n  IntegrationCapabilityDeclaration,\n  IntegrationPermissionDeclaration,\n  PartnerWidgetDeclaration,\n  PartnerToolModule,\n  PartnerToolParameters,\n  ToolClassificationProposal,\n  DefinitionCollisionInput,\n  FirstPartyInventory,\n  // Event surfaces (webhooks, schedules, OAuth): declared in the definition,\n  // executed locally by the harness/testing helpers today; the host's real\n  // transports (public ingress, scheduler, hosted OAuth callback) bind to\n  // these exact declarations later with no partner code change.\n  PartnerWebhookDeclaration,\n  WebhookSignatureDeclaration,\n  WebhookEvent,\n  WebhookResult,\n  PartnerScheduleDeclaration,\n  ScheduleInvocation,\n  ScheduleResult,\n  PartnerOAuthDeclaration,\n  OAuthProviderDeclaration,\n  OAuthTokens,\n} from '@ekanos/integration-schema';\n"]}

package/dist/integration/types.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The partner authoring types are owned by `@ekanos/integration-schema` (the
+ * dependency-pure package `@kit/integrations-core` also imports, so there is
+ * one contract and no structural twin — F9). This file re-exports them under
+ * `@ekanos/sdk/integration`.
+ */
+export type { IntegrationDefinition, IntegrationComponentDeclarations, IntegrationProposals, IntegrationCapabilityDeclaration, IntegrationPermissionDeclaration, PartnerWidgetDeclaration, PartnerToolModule, PartnerToolParameters, ToolClassificationProposal, PartnerWebhookDeclaration, WebhookSignatureDeclaration, WebhookEvent, WebhookResult, PartnerScheduleDeclaration, ScheduleInvocation, ScheduleResult, PartnerOAuthDeclaration, OAuthProviderDeclaration, OAuthTokens, } from '@ekanos/integration-schema';

package/dist/integration/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/integration/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/integration/types.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * The partner authoring types are owned by `@ekanos/integration-schema` (the\n * dependency-pure package `@kit/integrations-core` also imports, so there is\n * one contract and no structural twin — F9). This file re-exports them under\n * `@ekanos/sdk/integration`.\n */\nexport type {\n  IntegrationDefinition,\n  IntegrationComponentDeclarations,\n  IntegrationProposals,\n  IntegrationCapabilityDeclaration,\n  IntegrationPermissionDeclaration,\n  PartnerWidgetDeclaration,\n  PartnerToolModule,\n  PartnerToolParameters,\n  ToolClassificationProposal,\n  PartnerWebhookDeclaration,\n  WebhookSignatureDeclaration,\n  WebhookEvent,\n  WebhookResult,\n  PartnerScheduleDeclaration,\n  ScheduleInvocation,\n  ScheduleResult,\n  PartnerOAuthDeclaration,\n  OAuthProviderDeclaration,\n  OAuthTokens,\n} from '@ekanos/integration-schema';\n"]}

package/dist/mcp/guards.d.ts

@@ -0,0 +1,40 @@
+import type { ToolContext } from './types.js';
+/**
+ * Account-resolution and membership guards for MCP tool modules.
+ *
+ * Every tool module MUST resolve the acting account via `getAccountId` and
+ * verify access with `ensureAccountMembership` (or the group variant) before
+ * touching data. Moved here from `@kit/integrations-core/mcp` by the SDK
+ * inversion; the HOST-only tool machinery (partner/first-party branding,
+ * account_slug schema injection) deliberately stays in integrations-core —
+ * branding is the host's provenance pen and must not ship in the
+ * partner-facing SDK.
+ */
+/**
+ * Resolve the account ID from context.
+ *
+ * Machine principal (Workflow Gateway): the account is fixed by the gateway
+ * token grant — never derived from args or the user. Otherwise: uses the
+ * pre-injected accountId from the MCP route, falling back to the user's
+ * personal account. See context/N8N_INTEGRATION_PLAN.md "Machine-principal design".
+ */
+export declare function getAccountId(ctx: ToolContext): string;
+/**
+ * Verify the caller has access to the specified account.
+ *
+ * Machine principal (Workflow Gateway): access is granted iff the requested
+ * account matches the token's bound account — the token is the authorization,
+ * so no DB membership lookup is performed (and none would be correct, since a
+ * machine call has no signed-in user).
+ *
+ * User principal (default): unchanged — true for personal accounts
+ * (accountId === user.id) or a valid team membership row.
+ */
+export declare function ensureAccountMembership(ctx: ToolContext, accountId: string): Promise<boolean>;
+/**
+ * Verify user is a member of a named group within the account.
+ * Returns true only if the named group exists AND the user is a member.
+ * Returns false if the group doesn't exist (deny by default — the group
+ * must be created and the user added before they gain access).
+ */
+export declare function ensureGroupMembership(ctx: ToolContext, accountId: string, groupName: string): Promise<boolean>;

package/dist/mcp/guards.js

@@ -0,0 +1,99 @@
+/**
+ * Account-resolution and membership guards for MCP tool modules.
+ *
+ * Every tool module MUST resolve the acting account via `getAccountId` and
+ * verify access with `ensureAccountMembership` (or the group variant) before
+ * touching data. Moved here from `@kit/integrations-core/mcp` by the SDK
+ * inversion; the HOST-only tool machinery (partner/first-party branding,
+ * account_slug schema injection) deliberately stays in integrations-core —
+ * branding is the host's provenance pen and must not ship in the
+ * partner-facing SDK.
+ */
+/**
+ * Resolve the account ID from context.
+ *
+ * Machine principal (Workflow Gateway): the account is fixed by the gateway
+ * token grant — never derived from args or the user. Otherwise: uses the
+ * pre-injected accountId from the MCP route, falling back to the user's
+ * personal account. See context/N8N_INTEGRATION_PLAN.md "Machine-principal design".
+ */
+export function getAccountId(ctx) {
+    if (ctx.principal === 'machine') {
+        // A machine principal MUST carry a grant. Falling back to ctx.user.id here
+        // would silently retarget the call at the token creator's PERSONAL account
+        // — fail closed instead: a machine context without a grant is a bug.
+        if (!ctx.machineGrant) {
+            throw new Error('Machine principal context is missing its account grant');
+        }
+        return ctx.machineGrant.accountId;
+    }
+    return ctx.accountId || ctx.user.id;
+}
+/**
+ * Verify the caller has access to the specified account.
+ *
+ * Machine principal (Workflow Gateway): access is granted iff the requested
+ * account matches the token's bound account — the token is the authorization,
+ * so no DB membership lookup is performed (and none would be correct, since a
+ * machine call has no signed-in user).
+ *
+ * User principal (default): unchanged — true for personal accounts
+ * (accountId === user.id) or a valid team membership row.
+ */
+export async function ensureAccountMembership(ctx, accountId) {
+    var _a;
+    // Machine principal: the gateway token binds exactly one account. Access is
+    // allowed only for that account; there is no membership table to consult.
+    if (ctx.principal === 'machine') {
+        return ((_a = ctx.machineGrant) === null || _a === void 0 ? void 0 : _a.accountId) === accountId;
+    }
+    // Personal account - user always has access
+    if (accountId === ctx.user.id) {
+        return true;
+    }
+    // Team account - check membership
+    const { data: membershipRows } = await ctx.supabase
+        .from('accounts_memberships')
+        .select('account_id')
+        .eq('account_id', accountId)
+        .eq('user_id', ctx.user.id)
+        .limit(1);
+    return !!(membershipRows && membershipRows.length > 0);
+}
+/**
+ * Verify user is a member of a named group within the account.
+ * Returns true only if the named group exists AND the user is a member.
+ * Returns false if the group doesn't exist (deny by default — the group
+ * must be created and the user added before they gain access).
+ */
+export async function ensureGroupMembership(ctx, accountId, groupName) {
+    // Machine principal (Workflow Gateway): group membership is a per-user
+    // concept and is not meaningful for a token-authenticated machine caller —
+    // checking it against ctx.user.id (the token creator) would be both wrong
+    // and a membership-probing leak. Deny; machine access is governed solely by
+    // the token grant (ensureAccountMembership).
+    if (ctx.principal === 'machine') {
+        return false;
+    }
+    // Check if the named group exists for this account
+    const { data: groups } = await ctx.supabase
+        .from('account_groups')
+        .select('id')
+        .eq('account_id', accountId)
+        .eq('name', groupName)
+        .limit(1);
+    // Group doesn't exist → deny (must be configured first)
+    if (!groups || groups.length === 0) {
+        return false;
+    }
+    const groupId = groups[0].id;
+    // Group exists → check if user is a member
+    const { data: membership } = await ctx.supabase
+        .from('account_group_members')
+        .select('id')
+        .eq('group_id', groupId)
+        .eq('user_id', ctx.user.id)
+        .limit(1);
+    return !!(membership && membership.length > 0);
+}
+//# sourceMappingURL=guards.js.map

package/dist/mcp/guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.js","sourceRoot":"","sources":["../../src/mcp/guards.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAEH;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,GAAgB;IAC3C,IAAI,GAAG,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QAChC,2EAA2E;QAC3E,2EAA2E;QAC3E,qEAAqE;QACrE,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;QAC5E,CAAC;QAED,OAAO,GAAG,CAAC,YAAY,CAAC,SAAS,CAAC;IACpC,CAAC;IAED,OAAO,GAAG,CAAC,SAAS,IAAI,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;AACtC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,GAAgB,EAChB,SAAiB;;IAEjB,4EAA4E;IAC5E,0EAA0E;IAC1E,IAAI,GAAG,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO,CAAA,MAAA,GAAG,CAAC,YAAY,0CAAE,SAAS,MAAK,SAAS,CAAC;IACnD,CAAC;IAED,4CAA4C;IAC5C,IAAI,SAAS,KAAK,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;QAC9B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,kCAAkC;IAClC,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,GAAG,MAAM,GAAG,CAAC,QAAQ;SAChD,IAAI,CAAC,sBAAsB,CAAC;SAC5B,MAAM,CAAC,YAAY,CAAC;SACpB,EAAE,CAAC,YAAY,EAAE,SAAS,CAAC;SAC3B,EAAE,CAAC,SAAS,EAAE,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;SAC1B,KAAK,CAAC,CAAC,CAAC,CAAC;IAEZ,OAAO,CAAC,CAAC,CAAC,cAAc,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACzD,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,GAAgB,EAChB,SAAiB,EACjB,SAAiB;IAEjB,uEAAuE;IACvE,2EAA2E;IAC3E,0EAA0E;IAC1E,4EAA4E;IAC5E,6CAA6C;IAC7C,IAAI,GAAG,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,mDAAmD;IACnD,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,CAAC,QAAQ;SACxC,IAAI,CAAC,gBAAgB,CAAC;SACtB,MAAM,CAAC,IAAI,CAAC;SACZ,EAAE,CAAC,YAAY,EAAE,SAAS,CAAC;SAC3B,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC;SACrB,KAAK,CAAC,CAAC,CAAC,CAAC;IAEZ,wDAAwD;IACxD,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACnC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,CAAC,CAAC,CAAE,CAAC,EAAY,CAAC;IAExC,2CAA2C;IAC3C,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,MAAM,GAAG,CAAC,QAAQ;SAC5C,IAAI,CAAC,uBAAuB,CAAC;SAC7B,MAAM,CAAC,IAAI,CAAC;SACZ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;SACvB,EAAE,CAAC,SAAS,EAAE,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;SAC1B,KAAK,CAAC,CAAC,CAAC,CAAC;IAEZ,OAAO,CAAC,CAAC,CAAC,UAAU,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACjD,CAAC","sourcesContent":["import type { ToolContext } from './types';\n\n/**\n * Account-resolution and membership guards for MCP tool modules.\n *\n * Every tool module MUST resolve the acting account via `getAccountId` and\n * verify access with `ensureAccountMembership` (or the group variant) before\n * touching data. Moved here from `@kit/integrations-core/mcp` by the SDK\n * inversion; the HOST-only tool machinery (partner/first-party branding,\n * account_slug schema injection) deliberately stays in integrations-core —\n * branding is the host's provenance pen and must not ship in the\n * partner-facing SDK.\n */\n\n/**\n * Resolve the account ID from context.\n *\n * Machine principal (Workflow Gateway): the account is fixed by the gateway\n * token grant — never derived from args or the user. Otherwise: uses the\n * pre-injected accountId from the MCP route, falling back to the user's\n * personal account. See context/N8N_INTEGRATION_PLAN.md \"Machine-principal design\".\n */\nexport function getAccountId(ctx: ToolContext): string {\n  if (ctx.principal === 'machine') {\n    // A machine principal MUST carry a grant. Falling back to ctx.user.id here\n    // would silently retarget the call at the token creator's PERSONAL account\n    // — fail closed instead: a machine context without a grant is a bug.\n    if (!ctx.machineGrant) {\n      throw new Error('Machine principal context is missing its account grant');\n    }\n\n    return ctx.machineGrant.accountId;\n  }\n\n  return ctx.accountId || ctx.user.id;\n}\n\n/**\n * Verify the caller has access to the specified account.\n *\n * Machine principal (Workflow Gateway): access is granted iff the requested\n * account matches the token's bound account — the token is the authorization,\n * so no DB membership lookup is performed (and none would be correct, since a\n * machine call has no signed-in user).\n *\n * User principal (default): unchanged — true for personal accounts\n * (accountId === user.id) or a valid team membership row.\n */\nexport async function ensureAccountMembership(\n  ctx: ToolContext,\n  accountId: string,\n): Promise<boolean> {\n  // Machine principal: the gateway token binds exactly one account. Access is\n  // allowed only for that account; there is no membership table to consult.\n  if (ctx.principal === 'machine') {\n    return ctx.machineGrant?.accountId === accountId;\n  }\n\n  // Personal account - user always has access\n  if (accountId === ctx.user.id) {\n    return true;\n  }\n\n  // Team account - check membership\n  const { data: membershipRows } = await ctx.supabase\n    .from('accounts_memberships')\n    .select('account_id')\n    .eq('account_id', accountId)\n    .eq('user_id', ctx.user.id)\n    .limit(1);\n\n  return !!(membershipRows && membershipRows.length > 0);\n}\n\n/**\n * Verify user is a member of a named group within the account.\n * Returns true only if the named group exists AND the user is a member.\n * Returns false if the group doesn't exist (deny by default — the group\n * must be created and the user added before they gain access).\n */\nexport async function ensureGroupMembership(\n  ctx: ToolContext,\n  accountId: string,\n  groupName: string,\n): Promise<boolean> {\n  // Machine principal (Workflow Gateway): group membership is a per-user\n  // concept and is not meaningful for a token-authenticated machine caller —\n  // checking it against ctx.user.id (the token creator) would be both wrong\n  // and a membership-probing leak. Deny; machine access is governed solely by\n  // the token grant (ensureAccountMembership).\n  if (ctx.principal === 'machine') {\n    return false;\n  }\n\n  // Check if the named group exists for this account\n  const { data: groups } = await ctx.supabase\n    .from('account_groups')\n    .select('id')\n    .eq('account_id', accountId)\n    .eq('name', groupName)\n    .limit(1);\n\n  // Group doesn't exist → deny (must be configured first)\n  if (!groups || groups.length === 0) {\n    return false;\n  }\n\n  const groupId = groups[0]!.id as string;\n\n  // Group exists → check if user is a member\n  const { data: membership } = await ctx.supabase\n    .from('account_group_members')\n    .select('id')\n    .eq('group_id', groupId)\n    .eq('user_id', ctx.user.id)\n    .limit(1);\n\n  return !!(membership && membership.length > 0);\n}\n"]}

package/dist/mcp/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @ekanos/sdk/mcp — MCP tool contract and security guards.
+ *
+ * Every tool module MUST resolve the acting account via `getAccountId` and
+ * verify access with `ensureAccountMembership` (or the group/resource
+ * variants) before touching data. `assertResourceOwnership` is exported so
+ * tools never hand-roll ownership checks.
+ *
+ * The SDK OWNS these implementations (the inversion);
+ * `@kit/integrations-core/mcp` re-exports them for first-party code. The
+ * HOST-only machinery stays in integrations-core on purpose:
+ * `brandPartnerTool` / `brandFirstPartyTool` (the provenance pen — exporting
+ * it here would hand partners the classification authority) and
+ * `injectAccountSlugParam(s)` (host route plumbing).
+ *
+ * Surface discipline: additions require an entry in
+ * docs/devex/sdk-export-map.md ("`@ekanos/sdk/mcp`").
+ */
+import 'server-only';
+export type * from './types.js';
+export { ensureAccountMembership, ensureGroupMembership, getAccountId, } from './guards.js';
+export { ToolOwnershipError, assertResourceOwnership, resolveSelfOnly, } from './ownership.js';

package/dist/mcp/index.js

@@ -0,0 +1,22 @@
+/**
+ * @ekanos/sdk/mcp — MCP tool contract and security guards.
+ *
+ * Every tool module MUST resolve the acting account via `getAccountId` and
+ * verify access with `ensureAccountMembership` (or the group/resource
+ * variants) before touching data. `assertResourceOwnership` is exported so
+ * tools never hand-roll ownership checks.
+ *
+ * The SDK OWNS these implementations (the inversion);
+ * `@kit/integrations-core/mcp` re-exports them for first-party code. The
+ * HOST-only machinery stays in integrations-core on purpose:
+ * `brandPartnerTool` / `brandFirstPartyTool` (the provenance pen — exporting
+ * it here would hand partners the classification authority) and
+ * `injectAccountSlugParam(s)` (host route plumbing).
+ *
+ * Surface discipline: additions require an entry in
+ * docs/devex/sdk-export-map.md ("`@ekanos/sdk/mcp`").
+ */
+import 'server-only';
+export { ensureAccountMembership, ensureGroupMembership, getAccountId, } from './guards.js';
+export { ToolOwnershipError, assertResourceOwnership, resolveSelfOnly, } from './ownership.js';
+//# sourceMappingURL=index.js.map

package/dist/mcp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,aAAa,CAAC;AAIrB,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACrB,YAAY,GACb,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,eAAe,GAChB,MAAM,aAAa,CAAC","sourcesContent":["/**\n * @ekanos/sdk/mcp — MCP tool contract and security guards.\n *\n * Every tool module MUST resolve the acting account via `getAccountId` and\n * verify access with `ensureAccountMembership` (or the group/resource\n * variants) before touching data. `assertResourceOwnership` is exported so\n * tools never hand-roll ownership checks.\n *\n * The SDK OWNS these implementations (the inversion);\n * `@kit/integrations-core/mcp` re-exports them for first-party code. The\n * HOST-only machinery stays in integrations-core on purpose:\n * `brandPartnerTool` / `brandFirstPartyTool` (the provenance pen — exporting\n * it here would hand partners the classification authority) and\n * `injectAccountSlugParam(s)` (host route plumbing).\n *\n * Surface discipline: additions require an entry in\n * docs/devex/sdk-export-map.md (\"`@ekanos/sdk/mcp`\").\n */\nimport 'server-only';\n\nexport type * from './types';\n\nexport {\n  ensureAccountMembership,\n  ensureGroupMembership,\n  getAccountId,\n} from './guards';\n\nexport {\n  ToolOwnershipError,\n  assertResourceOwnership,\n  resolveSelfOnly,\n} from './ownership';\n"]}

package/dist/mcp/ownership.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Ownership guards for member-facing MCP tools.
+ *
+ * The LLM controls tool arguments. Any member-facing tool that accepts an
+ * external per-user identifier (a Wild Apricot contactId, a Discourse
+ * username, a LearnWorlds learner id, etc.) is a cross-member data-exposure
+ * risk: the caller can pass *someone else's* id and read or act on their
+ * data. The org-membership gate (`ensureAccountMembership`) does not catch
+ * this — it answers "is this person in the org?", never "is this person's
+ * own data?".
+ *
+ * These helpers make the safe path the default. A tool author reaches for
+ * `resolveSelfOnly` instead of writing a bespoke "default to me" resolver,
+ * and gets ownership enforcement for free.
+ *
+ * Resolving "who am I" is integration-specific (each integration maps the
+ * Supabase user to its own id space), so the caller supplies `resolveSelf`.
+ */
+/**
+ * Thrown when a tool caller attempts to access or act on another user's
+ * data. Tool `run` bodies should let this propagate (or convert it to a
+ * `{ error }` result) — the assistant surfaces a "not permitted" message
+ * rather than the forbidden data.
+ */
+export declare class ToolOwnershipError extends Error {
+    readonly code = "FORBIDDEN_OWNERSHIP";
+    constructor(resourceLabel?: string);
+}
+/**
+ * Self-only identity resolution for member-facing tools.
+ *
+ *   - caller supplied no id        → returns the caller's own id
+ *   - caller supplied their own id → returns it
+ *   - caller supplied a different id → throws ToolOwnershipError
+ *
+ * @example
+ *   // In a Wild Apricot read tool:
+ *   const contactId = await resolveSelfOnly({
+ *     requestedId: args.contactId,
+ *     resolveSelf: () => resolveWaContactId(accountId),
+ *     resourceLabel: 'member data',
+ *   });
+ */
+export declare function resolveSelfOnly<TId extends string | number>(params: {
+    /** The identifier the LLM supplied as a tool argument, if any. */
+    requestedId?: TId | null;
+    /** Integration-specific resolver for the calling user's own id. */
+    resolveSelf: () => Promise<TId>;
+    /** Human-readable noun for the error message, e.g. 'member profile'. */
+    resourceLabel?: string;
+}): Promise<TId>;
+/**
+ * Ownership verification for tools that act on an opaque resource id (an
+ * event registration, a saved document, an invoice) where ownership cannot
+ * be inferred from the id itself. Resolves the resource's owner and the
+ * caller's own id and throws if they differ (or if the resource has no
+ * resolvable owner — fail closed).
+ *
+ * @example
+ *   // In a Wild Apricot cancel tool:
+ *   await assertResourceOwnership({
+ *     resolveSelf: () => resolveWaContactId(accountId),
+ *     resolveOwner: async () => {
+ *       const regs = await getContactRegistrations(accountId, await resolveWaContactId(accountId));
+ *       return regs.find((r) => r.Id === registrationId)?.Contact.Id;
+ *     },
+ *     resourceLabel: 'event registration',
+ *   });
+ */
+export declare function assertResourceOwnership<TId extends string | number>(params: {
+    resolveSelf: () => Promise<TId>;
+    resolveOwner: () => Promise<TId | null | undefined>;
+    resourceLabel?: string;
+}): Promise<void>;

package/dist/mcp/ownership.js

@@ -0,0 +1,83 @@
+/**
+ * Ownership guards for member-facing MCP tools.
+ *
+ * The LLM controls tool arguments. Any member-facing tool that accepts an
+ * external per-user identifier (a Wild Apricot contactId, a Discourse
+ * username, a LearnWorlds learner id, etc.) is a cross-member data-exposure
+ * risk: the caller can pass *someone else's* id and read or act on their
+ * data. The org-membership gate (`ensureAccountMembership`) does not catch
+ * this — it answers "is this person in the org?", never "is this person's
+ * own data?".
+ *
+ * These helpers make the safe path the default. A tool author reaches for
+ * `resolveSelfOnly` instead of writing a bespoke "default to me" resolver,
+ * and gets ownership enforcement for free.
+ *
+ * Resolving "who am I" is integration-specific (each integration maps the
+ * Supabase user to its own id space), so the caller supplies `resolveSelf`.
+ */
+/**
+ * Thrown when a tool caller attempts to access or act on another user's
+ * data. Tool `run` bodies should let this propagate (or convert it to a
+ * `{ error }` result) — the assistant surfaces a "not permitted" message
+ * rather than the forbidden data.
+ */
+export class ToolOwnershipError extends Error {
+    constructor(resourceLabel = 'data') {
+        super(`Forbidden: you can only access your own ${resourceLabel}.`);
+        this.code = 'FORBIDDEN_OWNERSHIP';
+        this.name = 'ToolOwnershipError';
+    }
+}
+/**
+ * Self-only identity resolution for member-facing tools.
+ *
+ *   - caller supplied no id        → returns the caller's own id
+ *   - caller supplied their own id → returns it
+ *   - caller supplied a different id → throws ToolOwnershipError
+ *
+ * @example
+ *   // In a Wild Apricot read tool:
+ *   const contactId = await resolveSelfOnly({
+ *     requestedId: args.contactId,
+ *     resolveSelf: () => resolveWaContactId(accountId),
+ *     resourceLabel: 'member data',
+ *   });
+ */
+export async function resolveSelfOnly(params) {
+    const selfId = await params.resolveSelf();
+    if (params.requestedId !== undefined &&
+        params.requestedId !== null &&
+        params.requestedId !== selfId) {
+        throw new ToolOwnershipError(params.resourceLabel);
+    }
+    return selfId;
+}
+/**
+ * Ownership verification for tools that act on an opaque resource id (an
+ * event registration, a saved document, an invoice) where ownership cannot
+ * be inferred from the id itself. Resolves the resource's owner and the
+ * caller's own id and throws if they differ (or if the resource has no
+ * resolvable owner — fail closed).
+ *
+ * @example
+ *   // In a Wild Apricot cancel tool:
+ *   await assertResourceOwnership({
+ *     resolveSelf: () => resolveWaContactId(accountId),
+ *     resolveOwner: async () => {
+ *       const regs = await getContactRegistrations(accountId, await resolveWaContactId(accountId));
+ *       return regs.find((r) => r.Id === registrationId)?.Contact.Id;
+ *     },
+ *     resourceLabel: 'event registration',
+ *   });
+ */
+export async function assertResourceOwnership(params) {
+    const [selfId, ownerId] = await Promise.all([
+        params.resolveSelf(),
+        params.resolveOwner(),
+    ]);
+    if (ownerId === null || ownerId === undefined || ownerId !== selfId) {
+        throw new ToolOwnershipError(params.resourceLabel);
+    }
+}
+//# sourceMappingURL=ownership.js.map

package/dist/mcp/ownership.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ownership.js","sourceRoot":"","sources":["../../src/mcp/ownership.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;GAKG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAG3C,YAAY,aAAa,GAAG,MAAM;QAChC,KAAK,CAAC,2CAA2C,aAAa,GAAG,CAAC,CAAC;QAH5D,SAAI,GAAG,qBAAqB,CAAC;QAIpC,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAA8B,MAOlE;IACC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,EAAE,CAAC;IAE1C,IACE,MAAM,CAAC,WAAW,KAAK,SAAS;QAChC,MAAM,CAAC,WAAW,KAAK,IAAI;QAC3B,MAAM,CAAC,WAAW,KAAK,MAAM,EAC7B,CAAC;QACD,MAAM,IAAI,kBAAkB,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;IACrD,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAE3C,MAID;IACC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAC1C,MAAM,CAAC,WAAW,EAAE;QACpB,MAAM,CAAC,YAAY,EAAE;KACtB,CAAC,CAAC;IAEH,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACpE,MAAM,IAAI,kBAAkB,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;IACrD,CAAC;AACH,CAAC","sourcesContent":["/**\n * Ownership guards for member-facing MCP tools.\n *\n * The LLM controls tool arguments. Any member-facing tool that accepts an\n * external per-user identifier (a Wild Apricot contactId, a Discourse\n * username, a LearnWorlds learner id, etc.) is a cross-member data-exposure\n * risk: the caller can pass *someone else's* id and read or act on their\n * data. The org-membership gate (`ensureAccountMembership`) does not catch\n * this — it answers \"is this person in the org?\", never \"is this person's\n * own data?\".\n *\n * These helpers make the safe path the default. A tool author reaches for\n * `resolveSelfOnly` instead of writing a bespoke \"default to me\" resolver,\n * and gets ownership enforcement for free.\n *\n * Resolving \"who am I\" is integration-specific (each integration maps the\n * Supabase user to its own id space), so the caller supplies `resolveSelf`.\n */\n\n/**\n * Thrown when a tool caller attempts to access or act on another user's\n * data. Tool `run` bodies should let this propagate (or convert it to a\n * `{ error }` result) — the assistant surfaces a \"not permitted\" message\n * rather than the forbidden data.\n */\nexport class ToolOwnershipError extends Error {\n  readonly code = 'FORBIDDEN_OWNERSHIP';\n\n  constructor(resourceLabel = 'data') {\n    super(`Forbidden: you can only access your own ${resourceLabel}.`);\n    this.name = 'ToolOwnershipError';\n  }\n}\n\n/**\n * Self-only identity resolution for member-facing tools.\n *\n *   - caller supplied no id        → returns the caller's own id\n *   - caller supplied their own id → returns it\n *   - caller supplied a different id → throws ToolOwnershipError\n *\n * @example\n *   // In a Wild Apricot read tool:\n *   const contactId = await resolveSelfOnly({\n *     requestedId: args.contactId,\n *     resolveSelf: () => resolveWaContactId(accountId),\n *     resourceLabel: 'member data',\n *   });\n */\nexport async function resolveSelfOnly<TId extends string | number>(params: {\n  /** The identifier the LLM supplied as a tool argument, if any. */\n  requestedId?: TId | null;\n  /** Integration-specific resolver for the calling user's own id. */\n  resolveSelf: () => Promise<TId>;\n  /** Human-readable noun for the error message, e.g. 'member profile'. */\n  resourceLabel?: string;\n}): Promise<TId> {\n  const selfId = await params.resolveSelf();\n\n  if (\n    params.requestedId !== undefined &&\n    params.requestedId !== null &&\n    params.requestedId !== selfId\n  ) {\n    throw new ToolOwnershipError(params.resourceLabel);\n  }\n\n  return selfId;\n}\n\n/**\n * Ownership verification for tools that act on an opaque resource id (an\n * event registration, a saved document, an invoice) where ownership cannot\n * be inferred from the id itself. Resolves the resource's owner and the\n * caller's own id and throws if they differ (or if the resource has no\n * resolvable owner — fail closed).\n *\n * @example\n *   // In a Wild Apricot cancel tool:\n *   await assertResourceOwnership({\n *     resolveSelf: () => resolveWaContactId(accountId),\n *     resolveOwner: async () => {\n *       const regs = await getContactRegistrations(accountId, await resolveWaContactId(accountId));\n *       return regs.find((r) => r.Id === registrationId)?.Contact.Id;\n *     },\n *     resourceLabel: 'event registration',\n *   });\n */\nexport async function assertResourceOwnership<\n  TId extends string | number,\n>(params: {\n  resolveSelf: () => Promise<TId>;\n  resolveOwner: () => Promise<TId | null | undefined>;\n  resourceLabel?: string;\n}): Promise<void> {\n  const [selfId, ownerId] = await Promise.all([\n    params.resolveSelf(),\n    params.resolveOwner(),\n  ]);\n\n  if (ownerId === null || ownerId === undefined || ownerId !== selfId) {\n    throw new ToolOwnershipError(params.resourceLabel);\n  }\n}\n"]}

package/dist/mcp/types.d.ts

@@ -0,0 +1,145 @@
+import type { SupabaseClient } from '@supabase/supabase-js';
+import type { IntegrationContext } from '@ekanos/integration-schema';
+export type ToolParamsSchema = {
+    type: 'object';
+    properties?: Record<string, unknown>;
+    required?: string[];
+    additionalProperties?: boolean;
+};
+export type ToolContext = {
+    req: Request;
+    /**
+     * Admin Supabase client for in-process MCP execution.
+     * This bypasses RLS; tools must perform their own authorization checks before
+     * reading or mutating protected data.
+     */
+    supabase: SupabaseClient;
+    user: {
+        id: string;
+    } & Record<string, unknown>;
+    /** The resolved account slug from the workspace context (injected by MCP route) */
+    accountSlug?: string;
+    /** The resolved account ID (UUID) from the workspace context (injected by MCP route) */
+    accountId?: string;
+    /** The resolved source ID (UUID) for the current tenant/workspace */
+    sourceId?: string | null;
+    /** The user's resolved IANA timezone (e.g. 'America/New_York') */
+    timezone?: string;
+    /** Whether the authenticated user is a platform super-admin */
+    isSuperAdmin?: boolean;
+    /**
+     * Who is executing this tool call.
+     *
+     * Undefined (the default for every user-facing MCP path) is treated as
+     * `'user'` — the historical behavior. `'machine'` marks a non-interactive
+     * caller (the Workflow Gateway) whose identity IS the account-bound gateway
+     * token, not a signed-in session. See machineGrant below and the
+     * "Machine-principal design" section of context/N8N_INTEGRATION_PLAN.md.
+     */
+    principal?: 'user' | 'machine';
+    /**
+     * Present only when `principal === 'machine'`. Carries the account the
+     * gateway token is bound to (the sole source of account identity for a
+     * machine call), the token row id, and the token creator for audit
+     * attribution. `getAccountId` / `ensureAccountMembership` read this instead
+     * of doing a DB membership lookup — the token itself is the authorization.
+     */
+    machineGrant?: {
+        accountId: string;
+        tokenId: string;
+        createdBy: string | null;
+    };
+    /**
+     * The host-built capability context
+     * (docs/devex/capability-context-proposal.md), attached ADDITIVELY by the
+     * MCP route after authorization. This is the CANONICAL `IntegrationContext`
+     * from `@ekanos/integration-schema` — the same declaration `@ekanos/sdk`
+     * re-exports, so there is no structural twin to drift and no core→SDK
+     * package cycle. Migrated tools may still narrow it with
+     * `requireContext(ctx)` from `@ekanos/sdk/context`; existing tools that
+     * never touch this field are unaffected.
+     */
+    integrationContext?: IntegrationContext;
+};
+export type ToolRunResult = unknown;
+/**
+ * The partner execution channel — the ONLY way partner-authored tool code
+ * runs (capability-context proposal §3 + sdk-export-map.md adversarial
+ * review outcomes 1–2).
+ *
+ * The first argument is the host-built capability context — the canonical
+ * `IntegrationContext` from `@ekanos/integration-schema`, the one declaration
+ * both `@ekanos/sdk` (authoring) and this package (host) import. The
+ * client-bearing `ToolContext` (req, admin supabase, identity fields) is
+ * structurally absent from this signature — a partner tool cannot reach it.
+ */
+export type PartnerToolRun = (integrationContext: IntegrationContext, args: Record<string, unknown>) => Promise<ToolRunResult>;
+export type ToolModule = {
+    name: string;
+    description?: string;
+    parameters?: ToolParamsSchema;
+    run: (ctx: ToolContext, args: Record<string, unknown>) => Promise<ToolRunResult>;
+    /**
+     * Partner EXECUTION function. Set by host adapter code
+     * (`registerPartnerIntegration`'s tool adapter) alongside the host BRAND
+     * (`brandPartnerTool`, mcp/helpers.ts) — never by first-party tool modules.
+     *
+     * IMPORTANT: this property is NOT the partner classification authority
+     * (that is the module-private WeakSet brand — a property can be forged,
+     * stripped, or varied between reads). For a host-branded tool the executor:
+     * - invokes `partnerRun(integrationContext, args)` with the host-built
+     *   capability context and NOTHING else (no ToolContext, no prepareArgs,
+     *   no toUi);
+     * - FAILS CLOSED if the capability context or this function is missing —
+     *   there is no legacy-context fallback for a branded tool.
+     *
+     * An UNBRANDED object carrying this property is treated as first-party and
+     * can never reach the partner path — so a partner cannot escape into, and a
+     * spoofed property cannot fake, the capability-only channel.
+     */
+    partnerRun?: PartnerToolRun;
+    prepareArgs?: (ctx: ToolContext, rawArgs: unknown) => Promise<Record<string, unknown>>;
+    ui?: UiComponentMeta | UiComponentMeta[];
+    toUi?: (ctx: ToolContext, result: unknown) => Promise<null | RenderInstruction | RenderInstruction[]>;
+    /**
+     * Side-effect classification — used by the SOC 2 audit log to decide
+     * whether the call is recorded. When omitted, the audit layer derives
+     * it from the tool name (read-verb prefixes → 'read', otherwise 'write').
+     * Tool authors should set this explicitly when the heuristic would be
+     * wrong (e.g. a `generate_*` tool that materially mutates server state).
+     * See packages/agents/src/security/tool-effect.ts.
+     */
+    effect?: 'read' | 'write';
+    /**
+     * Data classification of what this tool exposes. Mirror of
+     * `Sensitivity` in packages/agents/src/security/redact.ts — kept inline
+     * here to avoid a backwards dependency from integrations-core onto agents.
+     * Reads that expose 'pii' or 'financial' data are recorded in the audit
+     * log even though they are not writes. Defaults to undefined (treated
+     * as 'internal' by the audit filter, 'pii' by the redaction layer).
+     */
+    sensitivity?: 'public' | 'internal' | 'pii' | 'financial';
+    /**
+     * A REPRESENTATIVE example of this tool's SUCCESS return value (top-level
+     * shape, minimal realistic values, arrays trimmed to one element). Consumed
+     * by the workflow authoring layer two ways:
+     *   1. Codegen grounding — the example is embedded in the workflow-generation
+     *      prompt so the model wires `{{stepId.field}}` refs against the tool's
+     *      REAL output keys instead of guessing (`deals` vs `contacts`,
+     *      `contact_id` vs `contactId` — observed failure class).
+     *   2. Ref linting — a workflow ref into this tool's output whose first path
+     *      segment is not a key of this example is rejected at authoring time.
+     * Keep it SMALL (it ships in prompts), faithful to the actual run() return,
+     * and free of real customer data. Omitting it just skips both uses.
+     */
+    outputExample?: Record<string, unknown>;
+};
+export type UiComponentMeta = {
+    component: string;
+    propsSchema: ToolParamsSchema;
+    doc?: string;
+};
+export type RenderInstruction = {
+    component: string;
+    props: unknown;
+};

package/dist/mcp/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/mcp/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/mcp/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { SupabaseClient } from '@supabase/supabase-js';\n\nimport type { IntegrationContext } from '@ekanos/integration-schema';\n\nexport type ToolParamsSchema = {\n  type: 'object';\n  properties?: Record<string, unknown>;\n  required?: string[];\n  additionalProperties?: boolean;\n};\n\nexport type ToolContext = {\n  req: Request;\n  /**\n   * Admin Supabase client for in-process MCP execution.\n   * This bypasses RLS; tools must perform their own authorization checks before\n   * reading or mutating protected data.\n   */\n  supabase: SupabaseClient;\n  user: { id: string } & Record<string, unknown>;\n  /** The resolved account slug from the workspace context (injected by MCP route) */\n  accountSlug?: string;\n  /** The resolved account ID (UUID) from the workspace context (injected by MCP route) */\n  accountId?: string;\n  /** The resolved source ID (UUID) for the current tenant/workspace */\n  sourceId?: string | null;\n  /** The user's resolved IANA timezone (e.g. 'America/New_York') */\n  timezone?: string;\n  /** Whether the authenticated user is a platform super-admin */\n  isSuperAdmin?: boolean;\n  /**\n   * Who is executing this tool call.\n   *\n   * Undefined (the default for every user-facing MCP path) is treated as\n   * `'user'` — the historical behavior. `'machine'` marks a non-interactive\n   * caller (the Workflow Gateway) whose identity IS the account-bound gateway\n   * token, not a signed-in session. See machineGrant below and the\n   * \"Machine-principal design\" section of context/N8N_INTEGRATION_PLAN.md.\n   */\n  principal?: 'user' | 'machine';\n  /**\n   * Present only when `principal === 'machine'`. Carries the account the\n   * gateway token is bound to (the sole source of account identity for a\n   * machine call), the token row id, and the token creator for audit\n   * attribution. `getAccountId` / `ensureAccountMembership` read this instead\n   * of doing a DB membership lookup — the token itself is the authorization.\n   */\n  machineGrant?: {\n    accountId: string;\n    tokenId: string;\n    createdBy: string | null;\n  };\n  /**\n   * The host-built capability context\n   * (docs/devex/capability-context-proposal.md), attached ADDITIVELY by the\n   * MCP route after authorization. This is the CANONICAL `IntegrationContext`\n   * from `@ekanos/integration-schema` — the same declaration `@ekanos/sdk`\n   * re-exports, so there is no structural twin to drift and no core→SDK\n   * package cycle. Migrated tools may still narrow it with\n   * `requireContext(ctx)` from `@ekanos/sdk/context`; existing tools that\n   * never touch this field are unaffected.\n   */\n  integrationContext?: IntegrationContext;\n};\n\nexport type ToolRunResult = unknown;\n\n/**\n * The partner execution channel — the ONLY way partner-authored tool code\n * runs (capability-context proposal §3 + sdk-export-map.md adversarial\n * review outcomes 1–2).\n *\n * The first argument is the host-built capability context — the canonical\n * `IntegrationContext` from `@ekanos/integration-schema`, the one declaration\n * both `@ekanos/sdk` (authoring) and this package (host) import. The\n * client-bearing `ToolContext` (req, admin supabase, identity fields) is\n * structurally absent from this signature — a partner tool cannot reach it.\n */\nexport type PartnerToolRun = (\n  integrationContext: IntegrationContext,\n  args: Record<string, unknown>,\n) => Promise<ToolRunResult>;\n\nexport type ToolModule = {\n  name: string;\n  description?: string;\n  parameters?: ToolParamsSchema;\n  run: (\n    ctx: ToolContext,\n    args: Record<string, unknown>,\n  ) => Promise<ToolRunResult>;\n\n  /**\n   * Partner EXECUTION function. Set by host adapter code\n   * (`registerPartnerIntegration`'s tool adapter) alongside the host BRAND\n   * (`brandPartnerTool`, mcp/helpers.ts) — never by first-party tool modules.\n   *\n   * IMPORTANT: this property is NOT the partner classification authority\n   * (that is the module-private WeakSet brand — a property can be forged,\n   * stripped, or varied between reads). For a host-branded tool the executor:\n   * - invokes `partnerRun(integrationContext, args)` with the host-built\n   *   capability context and NOTHING else (no ToolContext, no prepareArgs,\n   *   no toUi);\n   * - FAILS CLOSED if the capability context or this function is missing —\n   *   there is no legacy-context fallback for a branded tool.\n   *\n   * An UNBRANDED object carrying this property is treated as first-party and\n   * can never reach the partner path — so a partner cannot escape into, and a\n   * spoofed property cannot fake, the capability-only channel.\n   */\n  partnerRun?: PartnerToolRun;\n\n  // Optional advanced features\n  // Compute/override arguments from context so the model doesn't need to supply them\n  prepareArgs?: (\n    ctx: ToolContext,\n    rawArgs: unknown,\n  ) => Promise<Record<string, unknown>>;\n\n  // UI rendering support: declare components and map results to render instructions\n  ui?: UiComponentMeta | UiComponentMeta[];\n  toUi?: (\n    ctx: ToolContext,\n    result: unknown,\n  ) => Promise<null | RenderInstruction | RenderInstruction[]>;\n\n  /**\n   * Side-effect classification — used by the SOC 2 audit log to decide\n   * whether the call is recorded. When omitted, the audit layer derives\n   * it from the tool name (read-verb prefixes → 'read', otherwise 'write').\n   * Tool authors should set this explicitly when the heuristic would be\n   * wrong (e.g. a `generate_*` tool that materially mutates server state).\n   * See packages/agents/src/security/tool-effect.ts.\n   */\n  effect?: 'read' | 'write';\n\n  /**\n   * Data classification of what this tool exposes. Mirror of\n   * `Sensitivity` in packages/agents/src/security/redact.ts — kept inline\n   * here to avoid a backwards dependency from integrations-core onto agents.\n   * Reads that expose 'pii' or 'financial' data are recorded in the audit\n   * log even though they are not writes. Defaults to undefined (treated\n   * as 'internal' by the audit filter, 'pii' by the redaction layer).\n   */\n  sensitivity?: 'public' | 'internal' | 'pii' | 'financial';\n\n  /**\n   * A REPRESENTATIVE example of this tool's SUCCESS return value (top-level\n   * shape, minimal realistic values, arrays trimmed to one element). Consumed\n   * by the workflow authoring layer two ways:\n   *   1. Codegen grounding — the example is embedded in the workflow-generation\n   *      prompt so the model wires `{{stepId.field}}` refs against the tool's\n   *      REAL output keys instead of guessing (`deals` vs `contacts`,\n   *      `contact_id` vs `contactId` — observed failure class).\n   *   2. Ref linting — a workflow ref into this tool's output whose first path\n   *      segment is not a key of this example is rejected at authoring time.\n   * Keep it SMALL (it ships in prompts), faithful to the actual run() return,\n   * and free of real customer data. Omitting it just skips both uses.\n   */\n  outputExample?: Record<string, unknown>;\n};\n\nexport type UiComponentMeta = {\n  component: string;\n  propsSchema: ToolParamsSchema;\n  doc?: string;\n};\n\nexport type RenderInstruction = {\n  component: string;\n  props: unknown;\n};\n"]}

package/dist/testing/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @ekanos/sdk/testing — the partner test harness surface.
+ *
+ * `createMockContext()` is the day-1 in-memory `IntegrationContext`
+ * (proposal §4): partners code and test against `ctx` here before anything
+ * lands in a sandbox. Self-contained — no Supabase, no Vault, no network —
+ * and enforcement (storage schemas, secret tiers, egress) is the same
+ * shared implementation from `@ekanos/sdk/context` that production uses.
+ *
+ * Surface discipline: additions require an entry in
+ * docs/devex/sdk-export-map.md ("Context & testing entrypoints (P1)").
+ */
+export { createMockContext } from './mock-context.js';
+export type { MockContextOptions, MockFetchHandler, MockIntegrationContext, RecordedFetchCall, RecordedLog, } from './mock-context.js';
+export { invokeWebhook, invokeSchedule } from './invoke.js';
+export type { DefinitionContextOptions, InvokeWebhookOptions, InvokeScheduleOptions, WebhookInvocationOutcome, ScheduleInvocationOutcome, } from './invoke.js';