@company-semantics/contracts 0.35.0 → 0.36.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.35.0",
+  "version": "0.36.1",
   "private": false,
   "repository": {
     "type": "git",

package/src/index.ts

@@ -120,8 +120,35 @@ export type {
   OrganizationInfo,
   OwnershipTransferRequest,
   OwnershipTransferStatus,
+  // Workspace visibility DTOs (Phase 2)
+  // @see ADR-CONT-030 for design rationale
+  WorkspaceRole,
+  WorkspaceOverview,
+  WorkspaceMember,
+  AuthMethodConfig,
+  WorkspaceAuthConfig,
+  IntegrationStatus,
+  WorkspaceIntegration,
+  WorkspaceAuditEvent,
+  // Workspace expansion DTOs (Phase 3)
+  // @see ADR-CONT-031 for design rationale
+  OrgInviteStatus,
+  OrgInvite,
+  CreateInviteRequest,
+  AcceptInviteRequest,
+  RemoveMemberRequest,
+  ChangeMemberRoleRequest,
+  OrgAuthPolicy,
+  UpdateAuthPolicyRequest,
+  PromoteIntegrationRequest,
+  DemoteIntegrationRequest,
+  Phase3AuditAction,
+  // Workspace capability types (Phase 3)
+  WorkspaceCapability,
 } from './org/index'
 
+export { ROLE_DISPLAY_MAP, WORKSPACE_CAPABILITIES, ROLE_CAPABILITY_MAP } from './org/index'
+
 // MCP tool discovery types
 // @see company-semantics-backend/src/interfaces/mcp/ for implementation
 export type {

package/src/org/capabilities.ts

@@ -0,0 +1,83 @@
+/**
+ * Workspace Capability Types
+ *
+ * Capability constants for Phase 3 workspace expansion features.
+ * These define the permission boundaries for workspace actions.
+ *
+ * INVARIANTS:
+ * - Capabilities are checked server-side before any mutation
+ * - UI uses capabilities to gate action visibility
+ * - Capabilities map to RBAC roles (see RoleCapabilityMap)
+ *
+ * @see ADR-CONT-031 for design rationale
+ */
+
+// =============================================================================
+// Workspace Capability Type
+// =============================================================================
+
+/**
+ * Capabilities for workspace actions.
+ * Used for capability-based access control in Phase 3 features.
+ *
+ * Capability hierarchy (implicit):
+ * - owner: all capabilities
+ * - admin: invite_member, manage_members (limited)
+ * - member: none (read-only)
+ */
+export type WorkspaceCapability =
+  // Member management
+  | 'org.invite_member'
+  | 'org.manage_members'
+  // Integration management
+  | 'org.promote_integration'
+  | 'org.demote_integration'
+  // Auth policy
+  | 'org.manage_auth'
+  // Domain claiming (future)
+  | 'org.claim_domain';
+
+/**
+ * All workspace capabilities.
+ * Use for iteration and validation.
+ */
+export const WORKSPACE_CAPABILITIES: readonly WorkspaceCapability[] = [
+  'org.invite_member',
+  'org.manage_members',
+  'org.promote_integration',
+  'org.demote_integration',
+  'org.manage_auth',
+  'org.claim_domain',
+] as const;
+
+// =============================================================================
+// Role → Capability Mapping
+// =============================================================================
+
+/**
+ * Capabilities granted to each workspace role.
+ *
+ * INVARIANTS:
+ * - Owner has all capabilities (cannot be restricted)
+ * - Admin cannot demote other admins (enforce in service layer)
+ * - Member has no mutation capabilities
+ *
+ * @see Phase 3 Invariant #4: Admin floor
+ * @see Phase 3 Invariant #5: Admin ≠ owner
+ */
+export const ROLE_CAPABILITY_MAP = {
+  owner: [
+    'org.invite_member',
+    'org.manage_members',
+    'org.promote_integration',
+    'org.demote_integration',
+    'org.manage_auth',
+    'org.claim_domain',
+  ],
+  admin: [
+    'org.invite_member',
+    'org.manage_members', // Note: cannot remove/demote other admins
+    'org.demote_integration', // Can demote own integrations only
+  ],
+  member: [],
+} as const satisfies Record<string, readonly WorkspaceCapability[]>;

package/src/org/index.ts

@@ -11,4 +11,31 @@ export type {
   OrganizationInfo,
   OwnershipTransferRequest,
   OwnershipTransferStatus,
+  // Workspace visibility DTOs (Phase 2)
+  WorkspaceRole,
+  WorkspaceOverview,
+  WorkspaceMember,
+  AuthMethodConfig,
+  WorkspaceAuthConfig,
+  IntegrationStatus,
+  WorkspaceIntegration,
+  WorkspaceAuditEvent,
+  // Workspace expansion DTOs (Phase 3)
+  OrgInviteStatus,
+  OrgInvite,
+  CreateInviteRequest,
+  AcceptInviteRequest,
+  RemoveMemberRequest,
+  ChangeMemberRoleRequest,
+  OrgAuthPolicy,
+  UpdateAuthPolicyRequest,
+  PromoteIntegrationRequest,
+  DemoteIntegrationRequest,
+  Phase3AuditAction,
 } from './types';
+
+export { ROLE_DISPLAY_MAP } from './types';
+
+// Workspace capability types (Phase 3)
+export type { WorkspaceCapability } from './capabilities';
+export { WORKSPACE_CAPABILITIES, ROLE_CAPABILITY_MAP } from './capabilities';

package/src/org/types.ts

@@ -47,3 +47,247 @@ export interface OwnershipTransferStatus {
   requestedAt?: string;
   expiresAt?: string;
 }
+
+// =============================================================================
+// Workspace Visibility DTOs (Phase 2)
+// @see ADR-CONT-030 for design rationale
+// =============================================================================
+
+/**
+ * Display role for workspace members.
+ * Presentation-layer simplification of the internal RBAC roles.
+ */
+export type WorkspaceRole = 'owner' | 'admin' | 'member';
+
+/**
+ * RBAC → UI role mapping (presentation only).
+ * Maps internal system roles to user-facing display roles.
+ */
+export const ROLE_DISPLAY_MAP = {
+  org_owner: 'owner',
+  org_admin: 'admin',
+  // All other roles → 'member'
+} as const satisfies Partial<Record<string, WorkspaceRole>>;
+
+/**
+ * Workspace overview for the control plane UI.
+ * Read-only projection of organization state.
+ */
+export interface WorkspaceOverview {
+  id: string;
+  name: string;
+  type: OrgType;
+  owner: {
+    id: string;
+    name: string;
+    email: string;
+  };
+  createdAt: string;
+  memberCount: number;
+  claimable: boolean;
+}
+
+/**
+ * Workspace member for the members list.
+ * Human users only (no agent actors).
+ */
+export interface WorkspaceMember {
+  id: string;
+  name: string;
+  email: string;
+  role: WorkspaceRole;
+  joinedAt: string;
+}
+
+/**
+ * Authentication method configuration.
+ */
+export interface AuthMethodConfig {
+  enabled: boolean;
+  provider?: string;
+}
+
+/**
+ * Workspace authentication configuration.
+ * Enabled auth methods and provider metadata.
+ */
+export interface WorkspaceAuthConfig {
+  emailOtp: AuthMethodConfig;
+  googleSso: AuthMethodConfig;
+  microsoftSso: AuthMethodConfig;
+  okta: AuthMethodConfig;
+}
+
+/**
+ * Integration connection status.
+ */
+export type IntegrationStatus = 'active' | 'expired' | 'revoked';
+
+/**
+ * Workspace integration for the integrations list.
+ * Shows connections visible to workspace admins.
+ *
+ * SECURITY: connectedBy.id should be empty string (not exposed for security).
+ * lastActivity is aggregated to reduce precision for timing attack mitigation.
+ * @see security-safety-reviewer finding: Excessive Information Disclosure
+ */
+export interface WorkspaceIntegration {
+  id: string;
+  provider: string;
+  status: IntegrationStatus;
+  connectedBy: {
+    /** Always empty string for security (user IDs not exposed) */
+    id: string;
+    /** Name of the user who connected this integration, or 'A team member' if unknown */
+    name: string;
+  };
+  executionScope: ExecutionScope;
+  /** Aggregated last activity (e.g., 'within the last day', 'within the last week') */
+  lastActivity: string | null;
+}
+
+/**
+ * Audit event for the workspace audit log.
+ * Filtered to spec events only (server-side).
+ */
+export interface WorkspaceAuditEvent {
+  id: string;
+  timestamp: string;
+  actor: {
+    id: string;
+    name: string;
+    type: 'user' | 'system';
+  };
+  action: string;
+  summary: string;
+}
+
+// =============================================================================
+// Workspace Expansion DTOs (Phase 3)
+// @see ADR-CONT-031 for design rationale
+// =============================================================================
+
+/**
+ * Status of an organization invite.
+ */
+export type OrgInviteStatus = 'pending' | 'accepted' | 'expired' | 'revoked';
+
+/**
+ * Organization invite for the workspace invites list.
+ * Represents a pending or historical invitation.
+ */
+export interface OrgInvite {
+  id: string;
+  orgId: string;
+  email: string;
+  role: WorkspaceRole;
+  invitedBy: {
+    id: string;
+    name: string;
+  };
+  status: OrgInviteStatus;
+  createdAt: string;
+  expiresAt: string;
+  acceptedAt?: string;
+}
+
+/**
+ * Request payload for creating an organization invite.
+ */
+export interface CreateInviteRequest {
+  email: string;
+  role: 'admin' | 'member';
+}
+
+/**
+ * Request payload for accepting an organization invite.
+ */
+export interface AcceptInviteRequest {
+  token: string;
+}
+
+/**
+ * Request payload for removing a member from the workspace.
+ */
+export interface RemoveMemberRequest {
+  memberId: string;
+}
+
+/**
+ * Request payload for changing a member's role.
+ */
+export interface ChangeMemberRoleRequest {
+  memberId: string;
+  newRole: 'admin' | 'member';
+}
+
+/**
+ * Organization authentication policy.
+ * Configures authentication requirements for workspace members.
+ *
+ * INVARIANT: Auth policy changes do not affect existing sessions
+ * (unless explicitly revoked via separate action).
+ * @see Phase 3 Invariant #11: No retroactive enforcement
+ */
+export interface OrgAuthPolicy {
+  /** Whether SSO is required for all members */
+  requireSSO: boolean;
+  /** List of allowed authentication providers (e.g., 'google', 'microsoft', 'okta') */
+  allowedProviders: string[];
+}
+
+/**
+ * Request payload for updating organization auth policy.
+ */
+export interface UpdateAuthPolicyRequest {
+  requireSSO?: boolean;
+  allowedProviders?: string[];
+}
+
+/**
+ * Request payload for promoting an integration to org scope.
+ *
+ * INVARIANT: acknowledgedRisk must be true to prove explicit intent.
+ * @see Phase 3 Invariant #15: Blast radius acknowledgment
+ */
+export interface PromoteIntegrationRequest {
+  /** User must acknowledge the blast radius of org-wide access */
+  acknowledgedRisk: boolean;
+}
+
+/**
+ * Request payload for demoting an integration to self scope.
+ */
+export interface DemoteIntegrationRequest {
+  /** Optional reason for demotion */
+  reason?: string;
+}
+
+// =============================================================================
+// Phase 3 Audit Action Types
+// @see ADR-CONT-031 for design rationale
+// =============================================================================
+
+/**
+ * Audit actions for Phase 3 workspace expansion features.
+ * These actions are emitted by the backend when workspace state changes.
+ *
+ * INVARIANT: All mutations must emit corresponding audit events.
+ * @see Phase 3 Invariant #13: All mutations are auditable
+ */
+export type Phase3AuditAction =
+  // Invite lifecycle
+  | 'org.member.invited'
+  | 'org.member.joined'
+  | 'org.invite.revoked'
+  | 'org.invite.expired'
+  // Member mutations
+  | 'org.member.removed'
+  | 'org.member.role_changed'
+  // Organization transition
+  | 'org.type_transition'
+  // Integration scope changes
+  | 'integration.scope_promoted'
+  | 'integration.scope_demoted'
+  // Auth policy
+  | 'org.auth_policy.updated';