@company-semantics/contracts 0.38.0 → 0.40.0

package/package.json

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

package/src/identity/README.md

@@ -8,22 +8,27 @@ TypeScript types and functions for user identity and display name resolution.
 
 - Types with minimal runtime code (pure functions only, no side effects)
 - No external dependencies (contracts policy)
-- `preferredName` is assistant-facing only, not user-edited label
-- `fullName` is user-editable override of derived firstName + lastName
+- `fullName` is the only stored name field (no firstName/lastName)
+- `preferredName` is assistant-facing only, always user-editable
+- `fullName` is user-editable only when `nameSource === 'self'`
+- `fullName` is read-only when `nameSource === 'sso'` (managed by organization)
 - `displayName` is NEVER stored — always derived at read time via `resolveDisplayName()`
 - `resolveDisplayName()` is the ONLY approved way to determine assistant addressing
+- Display name fallback: `preferredName ?? extractFirstWord(fullName)`
 
 ## Public API
 
 ### Types
 
 - `ISODateString` — ISO 8601 date-time string alias
-- `UserIdentity` — User identity with name fields and timestamps
+- `NameSource` — `'self' | 'sso'` indicating name data source
+- `UserIdentity` — User identity with name fields, source, and timestamps
 
 ### Functions
 
-- `deriveFullName(firstName, lastName?)` — Derive full name from components
-- `resolveDisplayName(identity)` — Get display name (preferredName or firstName)
+- `extractFirstWord(fullName)` — Extract first word from full name
+- `resolveDisplayName(identity)` — Get display name (preferredName or first word of fullName)
+- `deriveFullName(firstName, lastName?)` — **[DEPRECATED]** Kept for migration only
 
 ## Dependencies
 

package/src/identity/display-name.ts

@@ -4,30 +4,32 @@
  * Canonical functions for deriving and resolving user display names.
  * These are the ONLY approved ways to handle display name logic.
  *
- * @see DECISIONS.md ADR-2026-01-020 for design rationale
+ * @see ADR-CONT-032 for design rationale
  */
 
 import type { UserIdentity } from './types';
 
 // =============================================================================
-// Full Name Derivation
+// Helper Functions
 // =============================================================================
 
 /**
- * Derive fullName from firstName and lastName.
+ * Extract the first word from a full name.
+ * Used as fallback when preferredName is not set.
  *
- * Invariant: fullName MUST be derived automatically unless explicitly provided.
- *
- * @param firstName - User's first name (required)
- * @param lastName - User's last name (optional)
- * @returns Combined full name
+ * @param fullName - The user's full name
+ * @returns The first word (before first space), or entire string if no spaces
  *
  * @example
- * deriveFullName("Ian", "Heidt")  // "Ian Heidt"
- * deriveFullName("Ian")           // "Ian"
+ * extractFirstWord("Ian Heidt")     // "Ian"
+ * extractFirstWord("Madonna")       // "Madonna"
+ * extractFirstWord("Mary Jane")     // "Mary"
+ * extractFirstWord("")              // ""
  */
-export function deriveFullName(firstName: string, lastName?: string): string {
-  return lastName ? `${firstName} ${lastName}` : firstName;
+export function extractFirstWord(fullName: string): string {
+  const trimmed = fullName.trim();
+  const spaceIndex = trimmed.indexOf(' ');
+  return spaceIndex === -1 ? trimmed : trimmed.slice(0, spaceIndex);
 }
 
 // =============================================================================
@@ -42,19 +44,32 @@ export function deriveFullName(firstName: string, lastName?: string): string {
  *
  * Invariants:
  * - preferredName overrides if present and non-empty
- * - Falls back to firstName (never blank)
+ * - Falls back to first word of fullName (never blank if fullName is set)
  * - displayName is NEVER stored, always derived at read time
  *
- * @param identity - Object with preferredName and firstName fields
+ * @param identity - Object with preferredName and fullName fields
  * @returns The resolved display name
  *
  * @example
- * resolveDisplayName({ firstName: "Ian", preferredName: "Heidt" })  // "Heidt"
- * resolveDisplayName({ firstName: "Ian", preferredName: "" })       // "Ian"
- * resolveDisplayName({ firstName: "Ian" })                          // "Ian"
+ * resolveDisplayName({ fullName: "Ian Heidt", preferredName: "Heidt" })  // "Heidt"
+ * resolveDisplayName({ fullName: "Ian Heidt", preferredName: "" })       // "Ian"
+ * resolveDisplayName({ fullName: "Ian Heidt" })                          // "Ian"
+ * resolveDisplayName({ fullName: "Madonna" })                            // "Madonna"
  */
 export function resolveDisplayName(
-  identity: Pick<UserIdentity, 'preferredName' | 'firstName'>
+  identity: Pick<UserIdentity, 'preferredName' | 'fullName'>
 ): string {
-  return identity.preferredName?.trim() || identity.firstName;
+  return identity.preferredName?.trim() || extractFirstWord(identity.fullName);
+}
+
+// =============================================================================
+// Deprecated Functions
+// =============================================================================
+
+/**
+ * @deprecated Use fullName directly. firstName/lastName are no longer stored.
+ * This function is retained for migration compatibility only.
+ */
+export function deriveFullName(firstName: string, lastName?: string): string {
+  return lastName ? `${firstName} ${lastName}` : firstName;
 }

package/src/identity/index.ts

@@ -6,7 +6,12 @@
  */
 
 // Types
-export type { ISODateString, UserIdentity } from './types';
+export type { ISODateString, NameSource, UserIdentity } from './types';
 
 // Functions
-export { deriveFullName, resolveDisplayName } from './display-name';
+export {
+  extractFirstWord,
+  resolveDisplayName,
+  /** @deprecated Use fullName directly */
+  deriveFullName,
+} from './display-name';

package/src/identity/types.ts

@@ -3,7 +3,7 @@
  *
  * Canonical vocabulary for user identity across Company Semantics.
  *
- * @see DECISIONS.md ADR-2026-01-020 for design rationale
+ * @see ADR-CONT-032 for design rationale
  */
 
 // =============================================================================
@@ -16,6 +16,19 @@
  */
 export type ISODateString = string;
 
+// =============================================================================
+// Name Source
+// =============================================================================
+
+/**
+ * Source of the user's name data.
+ * Determines who controls the fullName field.
+ *
+ * - 'self': User-provided (editable by user)
+ * - 'sso': SSO/IdP-provided (read-only, managed by organization)
+ */
+export type NameSource = 'self' | 'sso';
+
 // =============================================================================
 // User Identity
 // =============================================================================
@@ -25,35 +38,34 @@ export type ISODateString = string;
  * Represents the canonical identity vocabulary for a user.
  *
  * Invariants:
- * - firstName is required (always addressable)
- * - lastName is optional (single-name users exist globally)
- * - fullName is STORED (derived by default, user-editable)
- * - preferredName is STORED (assistant-only addressing)
+ * - fullName is the only stored name field (no firstName/lastName)
+ * - preferredName is optional and always user-controlled
+ * - nameSource determines whether fullName is user-editable
  * - displayName is NEVER stored (derived at read time via resolveDisplayName)
  */
 export type UserIdentity = {
   /** Unique user identifier */
   userId: string;
 
-  /** User's first name (required) */
-  firstName: string;
-
-  /** User's last name (optional) */
-  lastName?: string;
-
   /**
    * Full name for display in UI, exports, and audit logs.
-   * Derived by default from firstName + lastName, but user-editable.
+   * Editable when nameSource === 'self', read-only when nameSource === 'sso'.
    */
   fullName: string;
 
   /**
    * Preferred name for AI assistant to use.
-   * Assistant-only field; may differ from firstName.
-   * If not set, assistant falls back to firstName via resolveDisplayName().
+   * Always user-editable regardless of nameSource.
+   * If not set, assistant falls back to first word of fullName via resolveDisplayName().
    */
   preferredName?: string;
 
+  /**
+   * Source of the name data.
+   * Determines whether fullName is editable by the user.
+   */
+  nameSource: NameSource;
+
   /** When the identity was created */
   createdAt: ISODateString;
 

package/src/index.ts

@@ -105,9 +105,9 @@ export { COMPATIBILITY } from './compatibility'
 export type { Compatibility, Deprecation } from './compatibility'
 
 // User identity types and functions
-// @see ADR-2026-01-020 for design rationale
-export type { ISODateString, UserIdentity } from './identity/index'
-export { deriveFullName, resolveDisplayName } from './identity/index'
+// @see ADR-CONT-032 for design rationale
+export type { ISODateString, NameSource, UserIdentity } from './identity/index'
+export { extractFirstWord, resolveDisplayName, deriveFullName } from './identity/index'
 
 // Auth domain types
 export { OTPErrorCode } from './auth/index'
@@ -152,9 +152,15 @@ export type {
   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/index.ts

@@ -34,6 +34,8 @@ export type {
   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';
@@ -49,3 +51,7 @@ export type {
   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

@@ -329,3 +329,49 @@ export interface UserOrgMembership {
   /** 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;
+}