@company-semantics/contracts 0.36.0 → 0.37.0

package/package.json

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

package/src/index.ts

@@ -130,9 +130,24 @@ export type {
   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 } 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

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

@@ -20,6 +20,22 @@ export type {
   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

@@ -110,12 +110,25 @@ export interface AuthMethodConfig {
 /**
  * Workspace authentication configuration.
  * Enabled auth methods and provider metadata.
+ *
+ * The `policy` field contains the org-level auth policy (owner-configurable).
+ * If no explicit policy exists, default values are returned.
  */
 export interface WorkspaceAuthConfig {
   emailOtp: AuthMethodConfig;
   googleSso: AuthMethodConfig;
   microsoftSso: AuthMethodConfig;
   okta: AuthMethodConfig;
+  /**
+   * Org-level authentication policy.
+   * Owner-only configuration for SSO requirements.
+   */
+  policy: {
+    /** Whether SSO is required for all members */
+    requireSSO: boolean;
+    /** List of allowed authentication providers */
+    allowedProviders: string[];
+  };
 }
 
 /**
@@ -126,16 +139,23 @@ 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;
 }
 
@@ -154,3 +174,133 @@ export interface WorkspaceAuditEvent {
   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';