@ekanos/integration-schema

The canonical, dependency-pure contract for Ekanos integration definitions.

One zod schema and one set of types, imported by both @ekanos/sdk (authoring — defineIntegration()) and @kit/integrations-core (the host trust boundary — registerPartnerIntegration() re-parses against the same schema). This package depends on nothing but zod, so neither consumer forms a dependency cycle and there is no hand-written structural twin to drift.

Docs: sdk.ekanos.dev/schema/overview.

Why it exists

A security review found three problems a shared schema resolves at once:

• The host must re-parse partner exports at the trust boundary rather than trust a .d.ts. registerPartnerIntegration() calls parseIntegrationDefinition() from here, so a definition is validated twice against the same rules: once when you author it, once when the host accepts it.
• Hand-written structural twins on the host side could not catch security-relevant drift. There are no twins now: one type, imported by both sides.
• The SDK used to validate a weaker workspace contract than the host. The workspace-target schema lives here; the host injects icon-name validity via createWorkspaceTargetListSchema({ isValidIcon }).

Authoring an integration? Read the @ekanos/sdk README instead. It is the partner guide, and it documents every field this schema validates with a worked example. This package is the contract underneath it: you install it only if you need the schema or the types without the SDK.

What's here

• IntegrationDefinitionSchema — the strict canonical zod schema.
• parseIntegrationDefinition(input) — rejects non-plain containers, parses, returns sanitized result.data (never the caller's object).
• validateIntegrationDefinitions(defs, firstParty?) — cross-definition + first-party collision detection.
• IntegrationDefinition<Schemas> and friends — the generic authoring types.
• The capability-context types (IntegrationContext, StorageSchemas, …) — canonical home; @ekanos/sdk re-exports them.
• The workspace-target schema + normalizeWorkspaceTargets.

Dependency-pure by construction: zod only. No @kit/*, no React, no server-only.

Publishing

This package is a runtime dependency of @ekanos/sdk, so it must be published before the SDK — a fresh npm install @ekanos/sdk resolves @ekanos/integration-schema from the registry. (It carries private: true between releases as a deliberate publish latch; a release commit lifts it on every publishable package at once.) The compiled ESM in dist/ uses explicit .js relative specifiers so a real Node import resolves without a bundler; the SDK's pack:test exercises that path end to end.