feat: add authentication, storage, and metadata schemas for enhanced API functionality

Author: hotlong

packages/spec/src/api/auth.zod.ts

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+import { BaseResponseSchema } from './contract.zod';
+
+/**
+ * Authentication Service Protocol
+ * 
+ * Defines the standard API contracts for Identity, Session Management,
+ * and Access Control.
+ */
+
+// ==========================================
+// Authentication Types
+// ==========================================
+
+export const AuthProvider = z.enum([
+  'local',
+  'google',
+  'github',
+  'microsoft',
+  'ldap',
+  'saml'
+]);
+
+export const SessionUserSchema = z.object({
+  id: z.string().describe('User ID'),
+  username: z.string().describe('Username'),
+  email: z.string().email().describe('Email address'),
+  name: z.string().describe('Display name'),
+  roles: z.array(z.string()).describe('Assigned role IDs'),
+  tenantId: z.string().describe('Current tenant ID'),
+  avatar: z.string().optional().describe('Avatar URL'),
+  language: z.string().default('en').describe('Preferred language'),
+  timezone: z.string().optional().describe('Preferred timezone'),
+});
+
+// ==========================================
+// Requests
+// ==========================================
+
+export const LoginRequestSchema = z.object({
+  username: z.string().describe('Username or Email'),
+  password: z.string().describe('Password credential'),
+  type: z.literal('password').default('password'),
+});
+
+export const RefreshTokenRequestSchema = z.object({
+  refreshToken: z.string().describe('Refresh token'),
+});
+
+// ==========================================
+// Responses
+// ==========================================
+
+export const SessionResponseSchema = BaseResponseSchema.extend({
+  data: z.object({
+    accessToken: z.string().describe('JWT Access Token'),
+    refreshToken: z.string().optional().describe('Refresh Token (if enabled)'),
+    expiresIn: z.number().describe('Token expiry in seconds'),
+    user: SessionUserSchema.describe('Current user details'),
+  }),
+});
+
+export const UserProfileResponseSchema = BaseResponseSchema.extend({
+  data: SessionUserSchema,
+});

packages/spec/src/api/index.ts

@@ -30,3 +30,6 @@ export * from './documentation.zod';
 // Legacy interface export (deprecated)
 // export type { IObjectStackProtocol } from './protocol';
 
+export * from './auth.zod';
+export * from './storage.zod';
+export * from './metadata.zod';

packages/spec/src/api/metadata.zod.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+import { BaseResponseSchema } from './contract.zod';
+import { ObjectSchema } from '../data/object.zod';
+import { AppSchema } from '../ui/app.zod';
+
+/**
+ * Metadata Service Protocol
+ * 
+ * Defines the standard API contracts for fetching system metadata.
+ * Frontend, IDEs, and Mobile apps use this to build dynamic UIs.
+ */
+
+// ==========================================
+// Responses
+// ==========================================
+
+/**
+ * Single Object Definition Response
+ * Returns the full JSON schema for an Entity (Fields, Actions, Config).
+ */
+export const ObjectDefinitionResponseSchema = BaseResponseSchema.extend({
+  data: ObjectSchema.describe('Full Object Schema'),
+});
+
+/**
+ * App Definition Response
+ * Returns the navigation, branding, and layout for an App.
+ */
+export const AppDefinitionResponseSchema = BaseResponseSchema.extend({
+  data: AppSchema.describe('Full App Configuration'),
+});
+
+/**
+ * All Concepts Response
+ * Bulk load lightweight definitions for autocomplete/pickers.
+ */
+export const ConceptListResponseSchema = BaseResponseSchema.extend({
+  data: z.array(z.object({
+    name: z.string(),
+    label: z.string(),
+    icon: z.string().optional(),
+    description: z.string().optional(),
+  })).describe('List of available concepts (Objects, Apps, Flows)'),
+});

packages/spec/src/api/storage.zod.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import { BaseResponseSchema } from './contract.zod';
+import { FileMetadataSchema } from '../system/object-storage.zod';
+
+/**
+ * Storage Service Protocol
+ * 
+ * Defines the API contract for client-side file operations.
+ * Focuses on secure, direct-to-cloud uploads (Presigned URLs)
+ * rather than proxying bytes through the API server.
+ */
+
+// ==========================================
+// Requests
+// ==========================================
+
+export const GetPresignedUrlRequestSchema = z.object({
+  filename: z.string().describe('Original filename'),
+  mimeType: z.string().describe('File MIME type'),
+  size: z.number().describe('File size in bytes'),
+  scope: z.string().default('user').describe('Target storage scope (e.g. user, private, public)'),
+  bucket: z.string().optional().describe('Specific bucket override (admin only)'),
+});
+
+export const CompleteUploadRequestSchema = z.object({
+  fileId: z.string().describe('File ID returned from presigned request'),
+  eTag: z.string().optional().describe('S3 ETag verification'),
+});
+
+// ==========================================
+// Responses
+// ==========================================
+
+export const PresignedUrlResponseSchema = BaseResponseSchema.extend({
+  data: z.object({
+    uploadUrl: z.string().describe('PUT/POST URL for direct upload'),
+    downloadUrl: z.string().optional().describe('Public/Private preview URL'),
+    fileId: z.string().describe('Temporary File ID'),
+    method: z.enum(['PUT', 'POST']).describe('HTTP Method to use'),
+    headers: z.record(z.string()).optional().describe('Required headers for upload'),
+    expiresIn: z.number().describe('URL expiry in seconds'),
+  }),
+});
+
+export const FileUploadResponseSchema = BaseResponseSchema.extend({
+  data: FileMetadataSchema.describe('Uploaded file metadata'),
+});