refactor(cloud): reuse Identity module for auth/org/API keys (better-auth aligned)

- Remove DeveloperAccountSchema, DeveloperApiKeySchema, ApiKeyScopeSchema,
  DeveloperAccountStatusSchema from developer-portal.zod.ts
- Add ApiKeySchema to Identity module following better-auth's API key plugin
- Add PublisherProfileSchema that links Identity.Organization to marketplace
- Update developer-portal.zod.ts docs to reference Identity namespace

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

Author: Copilot

packages/spec/src/cloud/developer-portal.test.ts

@@ -1,9 +1,6 @@
 import { describe, it, expect } from 'vitest';
 import {
-  DeveloperAccountStatusSchema,
-  ApiKeyScopeSchema,
-  DeveloperApiKeySchema,
-  DeveloperAccountSchema,
+  PublisherProfileSchema,
   ReleaseChannelSchema,
   VersionReleaseSchema,
   CreateListingRequestSchema,
@@ -15,110 +12,50 @@ import {
   TimeSeriesPointSchema,
 } from './developer-portal.zod';
 
-describe('DeveloperAccountStatusSchema', () => {
-  it('should accept all valid statuses', () => {
-    const statuses = ['pending', 'active', 'suspended', 'deactivated'];
-    statuses.forEach(status => {
-      expect(() => DeveloperAccountStatusSchema.parse(status)).not.toThrow();
-    });
-  });
-
-  it('should reject invalid status', () => {
-    expect(() => DeveloperAccountStatusSchema.parse('banned')).toThrow();
-  });
-});
-
-describe('ApiKeyScopeSchema', () => {
-  it('should accept all valid scopes', () => {
-    const scopes = ['publish', 'read', 'manage', 'admin'];
-    scopes.forEach(scope => {
-      expect(() => ApiKeyScopeSchema.parse(scope)).not.toThrow();
-    });
-  });
-});
-
-describe('DeveloperApiKeySchema', () => {
-  it('should accept minimal API key', () => {
-    const key = {
-      id: 'key-001',
-      label: 'CI/CD Pipeline',
-      scopes: ['publish'],
-      createdAt: '2025-06-01T00:00:00Z',
-    };
-    const parsed = DeveloperApiKeySchema.parse(key);
-    expect(parsed.active).toBe(true);
-  });
-
-  it('should accept full API key', () => {
-    const key = {
-      id: 'key-001',
-      label: 'CI/CD Pipeline',
-      scopes: ['publish', 'read'],
-      prefix: 'os_pk_ab',
-      expiresAt: '2026-06-01T00:00:00Z',
-      createdAt: '2025-06-01T00:00:00Z',
-      lastUsedAt: '2025-09-15T10:30:00Z',
-      active: true,
-    };
-    const parsed = DeveloperApiKeySchema.parse(key);
-    expect(parsed.scopes).toHaveLength(2);
-    expect(parsed.prefix).toBe('os_pk_ab');
-  });
-
-  it('should require at least one scope', () => {
-    const key = {
-      id: 'key-001',
-      label: 'Empty',
-      scopes: [],
-      createdAt: '2025-06-01T00:00:00Z',
-    };
-    expect(() => DeveloperApiKeySchema.parse(key)).toThrow();
-  });
-});
-
-describe('DeveloperAccountSchema', () => {
-  it('should accept minimal account', () => {
-    const account = {
-      id: 'dev-001',
+describe('PublisherProfileSchema', () => {
+  it('should accept minimal publisher profile', () => {
+    const profile = {
+      organizationId: 'org-001',
       publisherId: 'pub-001',
-      organizationName: 'Acme Corp',
-      email: 'dev@acme.com',
       registeredAt: '2025-01-15T10:00:00Z',
     };
-    const parsed = DeveloperAccountSchema.parse(account);
-    expect(parsed.status).toBe('pending');
+    const parsed = PublisherProfileSchema.parse(profile);
     expect(parsed.verification).toBe('unverified');
   });
 
-  it('should accept full account with team members', () => {
-    const account = {
-      id: 'dev-001',
+  it('should accept full publisher profile', () => {
+    const profile = {
+      organizationId: 'org-001',
       publisherId: 'pub-001',
-      status: 'active' as const,
       verification: 'verified' as const,
-      organizationName: 'Acme Corp',
-      email: 'dev@acme.com',
-      teamMembers: [
-        { userId: 'user-001', role: 'owner' as const, joinedAt: '2025-01-15T10:00:00Z' },
-        { userId: 'user-002', role: 'developer' as const },
-      ],
       agreementVersion: '2.0',
+      website: 'https://acme.com',
+      supportEmail: 'support@acme.com',
+      registeredAt: '2025-01-15T10:00:00Z',
+    };
+    const parsed = PublisherProfileSchema.parse(profile);
+    expect(parsed.verification).toBe('verified');
+    expect(parsed.agreementVersion).toBe('2.0');
+  });
+
+  it('should require valid support email', () => {
+    const profile = {
+      organizationId: 'org-001',
+      publisherId: 'pub-001',
+      supportEmail: 'not-an-email',
       registeredAt: '2025-01-15T10:00:00Z',
     };
-    const parsed = DeveloperAccountSchema.parse(account);
-    expect(parsed.teamMembers).toHaveLength(2);
-    expect(parsed.status).toBe('active');
+    expect(() => PublisherProfileSchema.parse(profile)).toThrow();
   });
 
-  it('should require valid email', () => {
-    const account = {
-      id: 'dev-001',
+  it('should require valid website URL', () => {
+    const profile = {
+      organizationId: 'org-001',
       publisherId: 'pub-001',
-      organizationName: 'Acme Corp',
-      email: 'not-an-email',
+      website: 'not-a-url',
       registeredAt: '2025-01-15T10:00:00Z',
     };
-    expect(() => DeveloperAccountSchema.parse(account)).toThrow();
+    expect(() => PublisherProfileSchema.parse(profile)).toThrow();
   });
 });
 

packages/spec/src/cloud/developer-portal.zod.ts

@@ -18,101 +18,56 @@ import { PublisherVerificationSchema } from './marketplace.zod';
  * - **Shopify Partner Dashboard**: App management, analytics, billing
  * - **VS Code Marketplace Management**: Extension publishing, statistics, tokens
  *
+ * ## Identity Integration (better-auth)
+ * Authentication, organization management, and API keys are handled by the
+ * Identity module (`@objectstack/spec` Identity namespace), which follows the
+ * better-auth specification. This module only defines marketplace-specific
+ * extensions on top of the shared identity layer:
+ *
+ * - **User & Session** → `Identity.UserSchema`, `Identity.SessionSchema`
+ * - **Organization & Members** → `Identity.OrganizationSchema`, `Identity.MemberSchema`
+ * - **API Keys** → `Identity.ApiKeySchema` (with marketplace scopes)
+ *
  * ## Key Concepts
- * - **Developer Account**: Registration and API key management
+ * - **Publisher Profile**: Links an Identity Organization to a marketplace publisher
  * - **App Listing Management**: CRUD for marketplace listings (draft → published)
  * - **Version Channels**: alpha / beta / rc / stable release channels
  * - **Publishing Analytics**: Install trends, revenue, ratings over time
  */
 
 // ==========================================
-// Developer Account & API Keys
+// Publisher Profile (extends Identity.Organization)
 // ==========================================
 
 /**
- * Developer Account Status
- */
-export const DeveloperAccountStatusSchema = z.enum([
-  'pending',        // Registration submitted, awaiting approval
-  'active',         // Account active and can publish
-  'suspended',      // Temporarily suspended (policy violation)
-  'deactivated',    // Deactivated by developer
-]);
-
-/**
- * API Key Scope — controls what the key can do
- */
-export const ApiKeyScopeSchema = z.enum([
-  'publish',        // Publish packages to registry
-  'read',           // Read listing/analytics data
-  'manage',         // Manage listings (update, deprecate)
-  'admin',          // Full access (manage team, keys)
-]);
-
-/**
- * Developer API Key
- */
-export const DeveloperApiKeySchema = z.object({
-  /** Key identifier (not the secret) */
-  id: z.string().describe('API key identifier'),
-
-  /** Human-readable label */
-  label: z.string().describe('Key label (e.g., "CI/CD Pipeline")'),
-
-  /** Scopes granted to this key */
-  scopes: z.array(ApiKeyScopeSchema).min(1).describe('Permissions granted'),
-
-  /** Key prefix (first 8 chars) for identification */
-  prefix: z.string().max(8).optional().describe('Key prefix for display'),
-
-  /** Expiration date (optional) */
-  expiresAt: z.string().datetime().optional(),
-
-  /** Creation timestamp */
-  createdAt: z.string().datetime(),
-
-  /** Last used timestamp */
-  lastUsedAt: z.string().datetime().optional(),
-
-  /** Whether this key is currently active */
-  active: z.boolean().default(true),
-});
-
-/**
- * Developer Account Schema
+ * Publisher Profile Schema
  *
- * Represents a registered developer or organization in the portal.
+ * Links an Identity Organization to a marketplace publisher identity.
+ * The organization itself (name, slug, logo, members) is managed via
+ * Identity.OrganizationSchema and Identity.MemberSchema (better-auth aligned).
+ *
+ * This schema only holds marketplace-specific publisher metadata.
  */
-export const DeveloperAccountSchema = z.object({
-  /** Account unique identifier */
-  id: z.string().describe('Developer account ID'),
-
-  /** Publisher ID (links to PublisherSchema in marketplace) */
-  publisherId: z.string().describe('Associated publisher ID'),
+export const PublisherProfileSchema = z.object({
+  /** Organization ID (references Identity.Organization.id) */
+  organizationId: z.string().describe('Identity Organization ID'),
 
-  /** Account status */
-  status: DeveloperAccountStatusSchema.default('pending'),
+  /** Publisher ID (marketplace-assigned identifier) */
+  publisherId: z.string().describe('Marketplace publisher ID'),
 
-  /** Verification level (from marketplace publisher) */
+  /** Verification level (marketplace trust tier) */
   verification: PublisherVerificationSchema.default('unverified'),
 
-  /** Organization name */
-  organizationName: z.string().describe('Organization or developer name'),
-
-  /** Primary contact email */
-  email: z.string().email().describe('Primary contact email'),
+  /** Accepted developer program agreement version */
+  agreementVersion: z.string().optional().describe('Accepted developer agreement version'),
 
-  /** Team members (user IDs with roles) */
-  teamMembers: z.array(z.object({
-    userId: z.string(),
-    role: z.enum(['owner', 'admin', 'developer', 'viewer']),
-    joinedAt: z.string().datetime().optional(),
-  })).optional().describe('Team member list'),
+  /** Publisher-specific website (may differ from org) */
+  website: z.string().url().optional().describe('Publisher website'),
 
-  /** Accepted developer agreement version */
-  agreementVersion: z.string().optional().describe('Accepted ToS version'),
+  /** Publisher-specific support email */
+  supportEmail: z.string().email().optional().describe('Publisher support email'),
 
-  /** Registration timestamp */
+  /** Registration timestamp (when org became a publisher) */
   registeredAt: z.string().datetime(),
 });
 
@@ -354,10 +309,7 @@ export const PublishingAnalyticsResponseSchema = z.object({
 // Export Types
 // ==========================================
 
-export type DeveloperAccountStatus = z.infer<typeof DeveloperAccountStatusSchema>;
-export type ApiKeyScope = z.infer<typeof ApiKeyScopeSchema>;
-export type DeveloperApiKey = z.infer<typeof DeveloperApiKeySchema>;
-export type DeveloperAccount = z.infer<typeof DeveloperAccountSchema>;
+export type PublisherProfile = z.infer<typeof PublisherProfileSchema>;
 export type ReleaseChannel = z.infer<typeof ReleaseChannelSchema>;
 export type VersionRelease = z.infer<typeof VersionReleaseSchema>;
 export type CreateListingRequest = z.infer<typeof CreateListingRequestSchema>;

packages/spec/src/identity/identity.test.ts

@@ -4,10 +4,12 @@ import {
   AccountSchema,
   SessionSchema,
   VerificationTokenSchema,
+  ApiKeySchema,
   type User,
   type Account,
   type Session,
   type VerificationToken,
+  type ApiKey,
 } from "./identity.zod";
 
 describe('UserSchema', () => {
@@ -247,6 +249,78 @@ describe('VerificationTokenSchema', () => {
   });
 });
 
+describe('ApiKeySchema', () => {
+  it('should accept minimal API key', () => {
+    const key = {
+      id: 'key_123',
+      name: 'CI/CD Pipeline',
+      userId: 'user_123',
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    };
+
+    const result = ApiKeySchema.parse(key);
+    expect(result.enabled).toBe(true);
+  });
+
+  it('should accept full API key with rate limiting and permissions', () => {
+    const key: ApiKey = {
+      id: 'key_123',
+      name: 'Production API Key',
+      start: 'os_pk_ab',
+      prefix: 'os_pk_',
+      userId: 'user_123',
+      organizationId: 'org_456',
+      expiresAt: new Date(Date.now() + 86400000).toISOString(),
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+      lastUsedAt: new Date().toISOString(),
+      lastRefetchAt: new Date().toISOString(),
+      enabled: true,
+      rateLimitEnabled: true,
+      rateLimitTimeWindow: 60000,
+      rateLimitMax: 100,
+      remaining: 95,
+      permissions: { 'publish': true, 'read': true, 'manage': false },
+      scopes: ['marketplace:publish', 'marketplace:read'],
+      metadata: { environment: 'production' },
+    };
+
+    const result = ApiKeySchema.parse(key);
+    expect(result.organizationId).toBe('org_456');
+    expect(result.scopes).toHaveLength(2);
+    expect(result.permissions?.publish).toBe(true);
+  });
+
+  it('should accept API key without optional fields', () => {
+    const key = {
+      id: 'key_123',
+      name: 'Minimal Key',
+      userId: 'user_123',
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    };
+
+    const result = ApiKeySchema.parse(key);
+    expect(result.organizationId).toBeUndefined();
+    expect(result.expiresAt).toBeUndefined();
+    expect(result.scopes).toBeUndefined();
+  });
+
+  it('should correctly infer ApiKey type', () => {
+    const key: ApiKey = {
+      id: 'key_123',
+      name: 'Test Key',
+      userId: 'user_123',
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    };
+
+    expect(key.id).toBe('key_123');
+    expect(key.name).toBe('Test Key');
+  });
+});
+
 describe('Type inference', () => {
   it('should correctly infer User type', () => {
     const user: User = {