@company-semantics/contracts 0.62.0 → 0.63.0

package/package.json

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

package/src/impersonation.ts

@@ -0,0 +1,68 @@
+/**
+ * Break-Glass Impersonation — Shared Vocabulary
+ *
+ * This module defines the types for the emergency impersonation mechanism.
+ * See ADR-BE-068 for the trust model and invariant documentation.
+ */
+
+// Authentication mode — tags every request context
+export type AuthMode = 'STANDARD' | 'BREAK_GLASS';
+
+// Impersonation session model — full session state
+export interface ImpersonationSession {
+  readonly impersonationSessionId: string;
+  readonly adminUserId: string;
+  readonly targetUserId: string;
+  readonly reason: string;
+  readonly reasonHash: string; // SHA-256 of reason text — tamper-evidence
+  readonly startedAt: string; // ISO 8601
+  readonly expiresAt: string; // ISO 8601
+  readonly endedAt: string | null; // ISO 8601 or null if active
+  readonly ipAddress: string;
+  readonly userAgent: string;
+}
+
+// Restricted action classes — single source of truth
+// Backend impersonation middleware consumes this enum centrally.
+// Routes do NOT self-classify. This prevents bypass via new routes.
+export type RestrictedImpersonationAction =
+  | 'delete_chat'
+  | 'delete_message'
+  | 'modify_billing'
+  | 'rotate_credentials'
+  | 'invite_remove_users'
+  | 'accept_agreements'
+  | 'irreversible_write';
+
+// All restricted actions as a const array for runtime checks
+export const RESTRICTED_IMPERSONATION_ACTIONS: readonly RestrictedImpersonationAction[] = [
+  'delete_chat',
+  'delete_message',
+  'modify_billing',
+  'rotate_credentials',
+  'invite_remove_users',
+  'accept_agreements',
+  'irreversible_write',
+] as const;
+
+// Impersonation-specific company capability
+export type ImpersonationCapability = 'company.impersonate';
+
+// Session summary — emitted on impersonation.ended and impersonation.expired
+export interface ImpersonationSessionSummary {
+  readonly impersonationSessionId: string;
+  readonly adminUserId: string;
+  readonly targetUserId: string;
+  readonly durationMs: number;
+  readonly actionCount: number;
+  readonly blockedActionCount: number;
+}
+
+// Impersonation audit event types
+export type ImpersonationAuditEventType =
+  | 'impersonation.started'
+  | 'impersonation.ended'
+  | 'impersonation.expired'
+  | 'impersonation.session_summary'
+  | 'impersonated.action'
+  | 'impersonation.blocked_action';

package/src/index.ts

@@ -401,3 +401,16 @@ export { RateLimitTier } from './rate-limit/index'
 // Billing domain types (v1 — read-only)
 // @see PRD-00121 for design rationale
 export type { OrgPlanStatus, OrgBillingInfo } from './billing/index'
+
+// Impersonation types (break-glass emergency access)
+// @see ADR-BE-068 for trust model
+export type {
+  AuthMode,
+  ImpersonationSession,
+  RestrictedImpersonationAction,
+  ImpersonationCapability,
+  ImpersonationSessionSummary,
+  ImpersonationAuditEventType,
+} from './impersonation'
+
+export { RESTRICTED_IMPERSONATION_ACTIONS } from './impersonation'