Protocol Consolidation: Establish 3-Layer Sync Architecture, Canonical Webhook & Auth Schemas by Copilot · Pull Request #391 · objectstack-ai/framework

Copilot · 2026-01-30T14:00:14Z

Three protocol areas had overlapping definitions and unclear boundaries: synchronization (sync/ETL/connector), webhooks (3 locations), and authentication (scattered configs).

Changes

3-Layer Synchronization Architecture

Established clear abstraction layers with distinct audiences:

L1: Simple Sync (automation/sync.zod.ts) - Business users, field-level mappings only
L2: ETL Pipeline (automation/etl.zod.ts) - Data engineers, multi-source transformations (joins, aggregations, custom SQL)
L3: Enterprise Connector (integration/connector.zod.ts) - System integrators, full feature set (auth, webhooks, rate limiting)

Added SYNC_ARCHITECTURE.md with decision matrix and migration paths.

Canonical Webhook Protocol

Established automation/webhook.zod.ts as single source of truth:

// Before: Duplicate definitions in 3 files
// After: Single canonical schema
export const WebhookSchema = z.object({
  name: SnakeCaseIdentifierSchema,
  url: z.string().url(),
  method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']),
  authentication: z.object({...}),
  retryPolicy: z.object({
    maxRetries: z.number().default(3),
    backoffStrategy: z.enum(['exponential', 'linear', 'fixed']),
  }),
  // ...
});

// workflow.zod.ts references it
export const WebhookTriggerActionSchema = z.object({
  type: z.literal('webhook_trigger'),
  config: WebhookSchema,  // Reference, not duplicate
});

// connector.zod.ts extends it
export const WebhookConfigSchema = WebhookSchema.extend({
  events: z.array(WebhookEventSchema),  // Connector-specific
});

Shared Authentication Schemas

Created canonical auth schemas in auth/config.zod.ts (OAuth2, API Key, Basic, Bearer, JWT, SAML):

// Eliminated 170+ lines of duplicate code
export const AuthConfigSchema = z.discriminatedUnion('type', [
  OAuth2Schema,
  APIKeySchema,
  BasicAuthSchema,
  BearerAuthSchema,
  JWTAuthSchema,
  SAMLAuthSchema,
  NoAuthSchema,
]);

// Connectors now import shared definition
import { AuthConfigSchema as ConnectorAuthConfigSchema } from '../auth/config.zod';

Renamed application-level auth to ApplicationAuthConfigSchema to distinguish from connector auth.

Breaking Changes

Webhook: retryCount → retryPolicy.maxRetries
Auth: type: 'api_key' → type: 'api-key', apiKey → key
Application auth schema: AuthConfigSchema → ApplicationAuthConfigSchema

Original prompt

Task 1.3: 整合同步协议

问题描述:

automation/sync.zod.ts - 简单推拉同步
automation/etl.zod.ts - 复杂 ETL 管道
integration/connector.zod.ts - 包含 fieldMappings 同步
三者边界模糊
解决方案: 分层定位而非合并

// automation/sync.zod.ts - Level 1: Simple Sync
export const SimpleSyncSchema = z.object({
direction: z.enum(['push', 'pull', 'bidirectional']),
source: z.string(),
target: z.string(),
frequency: z.object({
type: z.enum(['realtime', 'scheduled', 'manual']),
cron: z.string().optional(),
}),
// NO complex transformations, just field mappings
});

// automation/etl.zod.ts - Level 2: Data Engineering
export const ETLPipelineSchema = z.object({
stages: z.array(z.object({
type: z.enum(['extract', 'transform', 'load']),
source: z.string(),
transformations: z.array(z.object({
type: z.enum(['join', 'aggregate', 'filter', 'custom-sql']),
// Complex transformations
})),
})),
// Advanced: Multi-source, multi-stage
});

// integration/connector.zod.ts - Level 3: Enterprise Connector
export const ConnectorSchema = z.object({
// Includes auth, webhooks, rate limiting, sync
// Most comprehensive
});
文档更新:

Data Synchronization Levels

Level Protocol Audience Use Case

L1: Simple Sync automation/sync.zod.ts Business users Sync Salesforce to Sheets

L2: ETL Pipeline automation/etl.zod.ts Data engineers Aggregate 10 sources to warehouse

L3: Enterprise Connector integration/connector.zod.ts System integrators Full SAP integration

验收标准:

添加三层同步文档
明确每个协议的使用场景
添加示例和最佳实践
所有测试通过
Task 1.4: 统一 Webhook 协议

问题描述:

automation/webhook.zod.ts - Webhook 管理
automation/workflow.zod.ts - 包含 webhookAction
integration/connector.zod.ts - 包含 webhooks 配置
三处定义不一致
解决方案: 建立引用关系

// automation/webhook.zod.ts - CANONICAL DEFINITION
export const WebhookSchema = z.object({
url: z.string().url(),
method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']),
headers: z.record(z.string()).optional(),
body: z.any().optional(),
authentication: z.object({
type: z.enum(['none', 'bearer', 'basic', 'api-key']),
credentials: z.record(z.string()).optional(),
}).optional(),
retryPolicy: z.object({
maxRetries: z.number().default(3),
backoffStrategy: z.enum(['exponential', 'linear', 'fixed']),
}).optional(),
});

// automation/workflow.zod.ts - REFERENCE
import { WebhookSchema } from './webhook.zod';
export const WorkflowActionSchema = z.union([
z.object({ type: z.literal('email'), ... }),
z.object({ type: z.literal('webhook'), config: WebhookSchema }),
// Other actions
]);

// integration/connector.zod.ts - REFERENCE
import { WebhookSchema } from '../automation/webhook.zod';
export const ConnectorSchema = z.object({
webhooks: z.array(WebhookSchema).optional(),
// Other connector fields
});
验收标准:

automation/webhook.zod.ts 成为唯一 Webhook 定义
其他协议通过 import 引用
消除重复定义
所有测试通过
Task 1.5: 统一认证配置

问题描述:

auth/config.zod.ts - 系统认证配置
automation/connector.zod.ts - 包含 auth 字段
integration/connector.zod.ts - 包含 authConfig
认证配置散落各处
解决方案: 建立共享认证 Schema

// auth/config.zod.ts - ADD SHARED SCHEMAS
export const OAuth2Schema = z.object({
authorizationUrl: z.string().url(),
tokenUrl: z.string().url(),
clientId: z.string(),
clientSecret: z.string(),
scopes: z.array(z.string()),
});

export const APIKeySchema = z.object({
type: z.literal('api-key'),
key: z.string(),
headerName: z.string().default('X-API-Key'),
});

export const BasicAuthSchema = z.object({
type: z.literal('basic'),
username: z.string(),
password: z.string(),
});

export const AuthConfigSchema = z.discriminatedUnion('type', [
z.object({ type: z.literal('oauth2'), config: OAuth2Schema }),
z.object({ type: z.literal('api-key'), config: APIKeySchema }),
z.object({ type: z.literal('basic'), config: BasicAuthSchema }),
]);

// integration/connector.zod.ts - USE SHARED
import { AuthConfigSchema } from '../auth/config.zod';
export const ConnectorSchema = z.object({
authConfig: AuthConfigSchema,
// Other fields
});
验收标准:

auth/config.zod.ts 定义共享认证 Schema
连接器协议引用共享 Schema
消除认证配置重复
所有测试通过

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

vercel · 2026-01-30T14:00:20Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jan 30, 2026 2:28pm

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

github-actions · 2026-01-30T14:19:00Z

This PR is very large. Consider breaking it into smaller PRs for easier review.

Copilot

Pull request overview

This PR consolidates three overlapping protocol areas in the ObjectStack specification through a well-structured refactoring that establishes clear boundaries and single sources of truth.

Changes:

Established a 3-layer synchronization architecture (Simple Sync → ETL Pipeline → Enterprise Connector) with clear audience targeting and use case differentiation
Unified webhook protocol into a canonical schema (automation/webhook.zod.ts) that other protocols reference or extend, eliminating duplicate definitions
Created shared authentication schemas in auth/config.zod.ts for connector authentication, removing ~170 lines of duplicate code and renaming application-level auth for clarity

Reviewed changes

Copilot reviewed 35 out of 37 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
packages/spec/src/auth/config.zod.ts	Added shared connector auth schemas (OAuth2, APIKey, Basic, Bearer, JWT, SAML, NoAuth); renamed application auth to ApplicationAuthConfigSchema
packages/spec/src/auth/config.test.ts	Updated test imports and schema references (contains critical bugs)
packages/spec/src/automation/webhook.zod.ts	Enhanced canonical webhook schema with authentication, retryPolicy, and comprehensive error handling
packages/spec/src/automation/webhook.test.ts	Updated tests to match new webhook schema structure
packages/spec/src/automation/workflow.zod.ts	Refactored to reference canonical WebhookSchema instead of duplicating fields
packages/spec/src/automation/workflow.test.ts	Updated workflow action tests to use nested config structure
packages/spec/src/integration/connector.zod.ts	Removed duplicate auth code, now imports from auth/config.zod.ts; extends WebhookSchema for connector-specific events
packages/spec/src/integration/connector.test.ts	Updated to import auth schemas from canonical source
packages/spec/src/automation/sync.zod.ts	Added L1 positioning documentation in 3-layer architecture
packages/spec/src/automation/etl.zod.ts	Added L2 positioning documentation in 3-layer architecture
packages/spec/docs/SYNC_ARCHITECTURE.md	Comprehensive new documentation with decision matrix, examples, and migration guides
JSON schema files	Generated schemas reflecting Zod changes (multiple files)
Documentation files	Updated references to reflect renamed schemas and new architecture

Copilot · 2026-01-30T14:23:07Z

-describe('AuthConfigSchema', () => {
+describe('ApplicationAuthConfigSchema', () => {
  it('should accept minimal valid configuration', () => {
    const config: AuthConfig = {


Type annotation uses AuthConfig but should use ApplicationAuthConfig to match the renamed schema. The type AuthConfig now refers to connector authentication (from auth/config.zod.ts), while ApplicationAuthConfig is for user-facing authentication.

Copilot · 2026-01-30T14:23:07Z

    };

-    expect(() => EnterpriseAuthConfigSchema.parse(config)).not.toThrow();
+    expect(() => EnterpriseApplicationAuthConfigSchema.parse(config)).not.toThrow();


The test file uses EnterpriseApplicationAuthConfigSchema but this schema does not exist. The correct schema name is EnterpriseAuthConfigSchema (without "Application" in the name). This test should reference the imported schema name.

Copilot · 2026-01-30T14:23:07Z

    };

-    expect(() => EnterpriseAuthConfigSchema.parse(config)).not.toThrow();
+    expect(() => EnterpriseApplicationAuthConfigSchema.parse(config)).not.toThrow();


The test file uses EnterpriseApplicationAuthConfigSchema but this schema does not exist. The correct schema name is EnterpriseAuthConfigSchema (without "Application" in the name). This test should reference the imported schema name.

Copilot · 2026-01-30T14:23:07Z

  it('should accept empty enterprise config', () => {
    const config = {};
-    expect(() => EnterpriseAuthConfigSchema.parse(config)).not.toThrow();
+    expect(() => EnterpriseApplicationAuthConfigSchema.parse(config)).not.toThrow();


The test file uses EnterpriseApplicationAuthConfigSchema but this schema does not exist. The correct schema name is EnterpriseAuthConfigSchema (without "Application" in the name). This test should reference the imported schema name.

Copilot · 2026-01-30T14:23:08Z

+import {
+  APIKeySchema,
+  OAuth2Schema,
+  JWTAuthSchema,
+  SAMLAuthSchema,
+  BasicAuthSchema,
+  BearerAuthSchema,
+  NoAuthSchema,
+  AuthConfigSchema,
+  type APIKey,
+  type OAuth2,
+  type JWTAuth,
+  type SAMLAuth,
+  type BasicAuth,
+  type BearerAuth,
+  type NoAuth,
+  type AuthConfig,
+} from '../auth/config.zod';


Unused imports AuthConfigSchema, BasicAuthSchema, BearerAuthSchema, NoAuthSchema.

Copilot · 2026-01-30T14:23:08Z

+| **certificate** | `string` | ✅ | SAML IdP certificate (X.509) |
+| **privateKey** | `string` | optional | SAML service provider private key |
+| **callbackUrl** | `string` | optional | SAML assertion consumer service URL |
+| **signatureAlgorithm** | `Enum<'sha1' \| 'sha256' \| 'sha512'>` | optional | SAML signature algorithm |


The SAMLAuth configuration currently allows signatureAlgorithm: 'sha1', which relies on the weak SHA-1 hashing algorithm and is no longer considered secure for signing authentication assertions. If a SAML integration is configured with signatureAlgorithm: 'sha1', an attacker with SHA-1 collision capabilities could forge or tamper with SAML assertions and potentially bypass authentication. To mitigate this, restrict the signatureAlgorithm options to stronger algorithms like 'sha256' or 'sha512' and remove support for SHA-1 even for compatibility modes.

Suggested change

| **signatureAlgorithm** | `Enum<'sha1' \| 'sha256' \| 'sha512'>` | optional | SAML signature algorithm |

| **signatureAlgorithm** | `Enum<'sha256' \| 'sha512'>` | optional | SAML signature algorithm |

Initial plan

eb1aa37

Copilot AI assigned Copilot and hotlong Jan 30, 2026

Copilot started work on behalf of hotlong January 30, 2026 14:00 View session

vercel bot deployed to Preview January 30, 2026 14:01 View deployment

Copilot AI and others added 2 commits January 30, 2026 14:09

Implement protocol consolidation: webhooks, auth, and sync layering

3f69c3c

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Add protocol consolidation summary documentation

b22e961

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

vercel bot deployed to Preview January 30, 2026 14:14 View deployment

Copilot AI changed the title ~~[WIP] Refactor sync protocols for clearer boundaries~~ Protocol Consolidation: Establish 3-Layer Sync Architecture, Canonical Webhook & Auth Schemas Jan 30, 2026

Copilot AI requested a review from hotlong January 30, 2026 14:14

Copilot finished work on behalf of hotlong January 30, 2026 14:14

hotlong marked this pull request as ready for review January 30, 2026 14:17

Copilot AI review requested due to automatic review settings January 30, 2026 14:17

Copilot started reviewing on behalf of hotlong January 30, 2026 14:17 View session

Merge branch 'main' into copilot/refactor-sync-protocols

422eee1

github-actions bot added documentation Improvements or additions to documentation tests labels Jan 30, 2026

github-actions bot added the size/xl label Jan 30, 2026

hotlong merged commit 3b84427 into main Jan 30, 2026
7 of 9 checks passed

Copilot AI reviewed Jan 30, 2026

View reviewed changes

vercel bot deployed to Preview January 30, 2026 14:28 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Protocol Consolidation: Establish 3-Layer Sync Architecture, Canonical Webhook & Auth Schemas#391

Protocol Consolidation: Establish 3-Layer Sync Architecture, Canonical Webhook & Auth Schemas#391
hotlong merged 4 commits intomainfrom
copilot/refactor-sync-protocols

Copilot AI commented Jan 30, 2026 •

edited

Loading

Uh oh!

vercel bot commented Jan 30, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Jan 30, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jan 30, 2026

Uh oh!

Copilot AI Jan 30, 2026

Uh oh!

Copilot AI Jan 30, 2026

Uh oh!

Copilot AI Jan 30, 2026

Uh oh!

Copilot AI Jan 30, 2026

Uh oh!

Copilot AI Jan 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Level	Protocol	Audience	Use Case
L1: Simple Sync	`automation/sync.zod.ts`	Business users	Sync Salesforce to Sheets
L2: ETL Pipeline	`automation/etl.zod.ts`	Data engineers	Aggregate 10 sources to warehouse
L3: Enterprise Connector	`integration/connector.zod.ts`	System integrators	Full SAP integration
验收标准:

	\| signatureAlgorithm \| `Enum<'sha1' \\| 'sha256' \\| 'sha512'>` \| optional \| SAML signature algorithm \|
	\| signatureAlgorithm \| `Enum<'sha256' \\| 'sha512'>` \| optional \| SAML signature algorithm \|

Conversation

Copilot AI commented Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

3-Layer Synchronization Architecture

Canonical Webhook Protocol

Shared Authentication Schemas

Breaking Changes

Data Synchronization Levels

Uh oh!

vercel bot commented Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jan 30, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Jan 30, 2026 •

edited

Loading

vercel bot commented Jan 30, 2026 •

edited

Loading