@company-semantics/contracts 0.37.0 → 0.39.0

package/package.json

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

package/src/index.ts

@@ -145,9 +145,22 @@ export type {
   Phase3AuditAction,
   // Workspace capability types (Phase 3)
   WorkspaceCapability,
+  // Domain and multi-org types (Phase 4)
+  // @see ADR-CONT-032 for design rationale
+  DomainStatus,
+  DomainVerificationMethod,
+  OrgDomain,
+  Phase4AuditAction,
+  UserOrgMembership,
+  // Authorization context types (Phase 5)
+  // @see ADR-CTRL-010 for design rationale
+  OrgScopedContext,
 } from './org/index'
 
-export { ROLE_DISPLAY_MAP, WORKSPACE_CAPABILITIES, ROLE_CAPABILITY_MAP } from './org/index'
+export { ROLE_DISPLAY_MAP, WORKSPACE_CAPABILITIES, ROLE_CAPABILITY_MAP, VIEW_SCOPE_MAP, getViewScope } from './org/index'
+
+// View authorization types (Phase 5 - ADR-APP-013)
+export type { AuthorizableView } from './org/index'
 
 // MCP tool discovery types
 // @see company-semantics-backend/src/interfaces/mcp/ for implementation

package/src/org/domain.ts

@@ -0,0 +1,67 @@
+/**
+ * Domain Types (Phase 4)
+ *
+ * Vocabulary types for enterprise domain verification and trust.
+ * @see ADR-CONT-032 (Phase 4: Enterprise Identity, Domain Trust, Multi-Org)
+ */
+
+/**
+ * Status of a domain claim within an organization.
+ * - 'pending': Domain claimed but not yet verified
+ * - 'verified': Domain ownership confirmed via DNS TXT record
+ * - 'revoked': Domain claim revoked by org owner
+ *
+ * INVARIANT: Only ONE org may have status='verified' for any domain globally.
+ */
+export type DomainStatus = 'pending' | 'verified' | 'revoked';
+
+/**
+ * Method used to verify domain ownership.
+ * - 'dns_txt': DNS TXT record verification (primary method)
+ * - 'email': Email-based verification (reserved for future)
+ * - 'idp': IdP-based verification via SAML/OIDC (reserved for future)
+ */
+export type DomainVerificationMethod = 'dns_txt' | 'email' | 'idp';
+
+/**
+ * Organization domain claim and verification status.
+ * Represents a domain that an org has claimed or verified ownership of.
+ *
+ * INVARIANT: Domain verification does not grant access.
+ * INVARIANT: Only one org can have a verified claim on any email domain.
+ */
+export interface OrgDomain {
+  id: string;
+  orgId: string;
+  domain: string;
+  status: DomainStatus;
+  verificationMethod: DomainVerificationMethod;
+  /** Verification token - only visible to org owner. */
+  verificationToken?: string;
+  /** ISO8601 timestamp when domain was verified, null if pending/revoked. */
+  verifiedAt: string | null;
+  /** ISO8601 timestamp when claim was created. */
+  createdAt: string;
+}
+
+// =============================================================================
+// Phase 4 Audit Action Types
+// =============================================================================
+
+/**
+ * Audit actions for Phase 4 enterprise identity features.
+ * These actions are emitted by the backend when domain/auth state changes.
+ *
+ * INVARIANT: All domain and auth policy mutations must emit audit events.
+ */
+export type Phase4AuditAction =
+  // Domain lifecycle
+  | 'org.domain.claimed'
+  | 'org.domain.verified'
+  | 'org.domain.revoked'
+  // Auth policy enforcement
+  | 'org.auth_policy.enforced'
+  | 'org.auth_policy.override_used' // Emergency SSO bypass succeeded
+  | 'org.auth_policy.override_attempted' // Emergency SSO bypass denied (incident review)
+  // Multi-org context
+  | 'user.active_org.switched';

package/src/org/index.ts

@@ -32,6 +32,10 @@ export type {
   PromoteIntegrationRequest,
   DemoteIntegrationRequest,
   Phase3AuditAction,
+  // Multi-org membership types (Phase 4)
+  UserOrgMembership,
+  // Authorization context types (Phase 5 - ADR-CTRL-010)
+  OrgScopedContext,
 } from './types';
 
 export { ROLE_DISPLAY_MAP } from './types';
@@ -39,3 +43,15 @@ export { ROLE_DISPLAY_MAP } from './types';
 // Workspace capability types (Phase 3)
 export type { WorkspaceCapability } from './capabilities';
 export { WORKSPACE_CAPABILITIES, ROLE_CAPABILITY_MAP } from './capabilities';
+
+// Domain types (Phase 4)
+export type {
+  DomainStatus,
+  DomainVerificationMethod,
+  OrgDomain,
+  Phase4AuditAction,
+} from './domain';
+
+// View authorization scopes (Phase 5 - ADR-APP-013)
+export type { AuthorizableView } from './view-scopes';
+export { VIEW_SCOPE_MAP, getViewScope } from './view-scopes';

package/src/org/types.ts

@@ -304,3 +304,74 @@ export type Phase3AuditAction =
   | 'integration.scope_demoted'
   // Auth policy
   | 'org.auth_policy.updated';
+
+// =============================================================================
+// Multi-Org Membership Types (Phase 4)
+// @see ADR-CONT-032 for design rationale
+// =============================================================================
+
+/**
+ * User organization membership summary.
+ * Represents a user's membership in an organization for multi-org context switching.
+ *
+ * INVARIANT: role is DERIVED from RBAC at write-time (presentation only).
+ * INVARIANT: RBAC remains the authoritative source of truth for permissions.
+ */
+export interface UserOrgMembership {
+  userId: string;
+  orgId: string;
+  orgName: string;
+  orgSlug: string;
+  /** Display role derived from RBAC - presentation only, not for auth decisions. */
+  role: WorkspaceRole;
+  /** ISO8601 timestamp when user joined the organization. */
+  joinedAt: string;
+  /** Whether this membership is currently active. */
+  isActive: boolean;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Authorization Context Types (Phase 5 - ADR-CTRL-010)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Validated organization-scoped context for policy implementations.
+ *
+ * This type provides compile-time proof that org membership was validated
+ * upstream. Policy implementations MUST accept this type instead of raw
+ * `orgId: string` to prevent user-controlled org bypass attacks.
+ *
+ * @invariant orgId comes from validated session, never user input
+ * @invariant userId is the authenticated user from session
+ * @invariant _orgValidated is a type-level marker (not runtime)
+ *
+ * @see ADR-CTRL-010 Org-Scoped Context Type requirement
+ * @see ADR-BE-060 Policy Delegation Pattern
+ *
+ * @example
+ * ```typescript
+ * // Policy implementation - accepts context, not raw orgId
+ * export const DomainViewPolicyImpl = {
+ *   async getDomainById(
+ *     db: Db,
+ *     ctx: OrgScopedContext,
+ *     domainId: string
+ *   ): Promise<OrgDomain | null> {
+ *     return db.select().from(orgDomains)
+ *       .where(and(eq(orgDomains.orgId, ctx.orgId), eq(orgDomains.id, domainId)));
+ *   }
+ * };
+ * ```
+ */
+export interface OrgScopedContext {
+  /** Organization ID from validated session. */
+  readonly orgId: string;
+  /** Authenticated user ID from session. */
+  readonly userId: string;
+  /**
+   * Type-level marker proving org validation occurred.
+   * This is a compile-time constraint, not a runtime value.
+   * Set to `true as const` when constructing from validated session.
+   */
+  readonly _orgValidated: true;
+}

package/src/org/view-scopes.ts

@@ -0,0 +1,42 @@
+/**
+ * View Authorization Scope Mapping
+ *
+ * Maps frontend views to required RBAC scopes.
+ * Used by useViewAuthorization hook for centralized view access control.
+ *
+ * See: ADR-APP-013
+ *
+ * INVARIANT: VIEW_SCOPE_MAP must stay in sync with AppView type in app-state.ts
+ */
+
+/**
+ * View-to-scope mapping for frontend authorization.
+ *
+ * - Views with string values require that scope for access
+ * - Views with null values are public (require only authentication)
+ */
+export const VIEW_SCOPE_MAP = {
+  // Protected views (require specific scope)
+  workspace: 'org.view_workspace',
+  timeline: 'org.view_timeline',
+  dashboard: 'org.view_dashboard',
+  'organization-strategy': 'org.view_strategy',
+  'system-snapshot': 'org.view_system',
+  // Public views (require only authentication)
+  chat: null,
+  settings: null,
+  chats: null,
+  upgrade: null,
+} as const;
+
+/**
+ * Type for views that can be checked against VIEW_SCOPE_MAP.
+ */
+export type AuthorizableView = keyof typeof VIEW_SCOPE_MAP;
+
+/**
+ * Get the required scope for a view, or null if public.
+ */
+export function getViewScope(view: string): string | null {
+  return VIEW_SCOPE_MAP[view as AuthorizableView] ?? null;
+}