@company-semantics/contracts 86.1.0 → 88.0.0

package/src/org/sso-stepper-types.ts

@@ -0,0 +1,81 @@
+/**
+ * SSO Stepper Types (PRD-00197)
+ *
+ * Provider state machine, workspace SSO state, stepper step, OIDC validation,
+ * SSO test flow and provider-suggestion types.
+ *
+ * Split out of `./types.ts`, which re-exports this module unchanged — import
+ * from `./types` (or the `./org` entry), not from this file directly.
+ */
+
+// =============================================================================
+// SSO Stepper Types (PRD-00197)
+// Types for the provider state machine, workspace SSO state, stepper step,
+// and supporting types for the SSO stepper redesign.
+// =============================================================================
+
+/**
+ * Provider-level configuration lifecycle.
+ * NOT_CONFIGURED → CONFIG_SAVED → CONFIG_VALID → TEST_SUCCESS → ENABLED
+ * Any state → NOT_CONFIGURED (on credential removal or provider switch)
+ */
+export type ProviderStatus =
+  | "NOT_CONFIGURED"
+  | "CONFIG_SAVED"
+  | "CONFIG_VALID"
+  | "TEST_SUCCESS"
+  | "ENABLED";
+
+/** Workspace SSO state derived from provider status + policy. */
+export type WorkspaceSsoState = "SSO_DISABLED" | "SSO_ENABLED" | "SSO_ENFORCED";
+
+/** Backend-authoritative stepper step. Frontend MUST NOT re-derive. */
+export type SsoStepperStep = "configure" | "test" | "enable" | "enforce";
+
+/** Owner identity information for the SSO readiness surface. */
+export interface OwnerIdentityInfo {
+  userId: string;
+  name: string;
+  email: string;
+  hasSsoIdentity: boolean;
+  linkedProvider: string | null;
+  lastSsoLoginAt: string | null;
+}
+
+/** Result of validating an OIDC discovery URL. */
+export interface OidcValidationResult {
+  valid: boolean;
+  issuer?: string;
+  authorizationEndpoint?: string;
+  error?: string;
+  errorCode?:
+    "UNREACHABLE" | "INVALID_DOCUMENT" | "MISSING_FIELDS" | "SSRF_BLOCKED";
+}
+
+/** Initiation payload for a test SSO login attempt. */
+export interface TestSsoInitiation {
+  authorizationUrl: string;
+  attemptId: string;
+}
+
+/** Result of a test SSO login attempt. */
+export interface TestSsoResult {
+  status: "pending" | "success" | "failed" | "expired";
+  claims?: { sub: string; email?: string; name?: string; issuer: string };
+  identityLinked?: boolean;
+  error?: string;
+  errorCode?:
+    | "IDENTITY_CONFLICT"
+    | "DOMAIN_MISMATCH"
+    | "ISSUER_MISMATCH"
+    | "CALLBACK_ERROR";
+}
+
+/** MX-based provider suggestion for SSO setup. */
+export interface ProviderSuggestion {
+  suggestedProvider: "google" | "microsoft" | null;
+  confidence: "high" | "low";
+  reason: string;
+  /** The verified domain that triggered the suggestion (for pre-filling provider inputs). */
+  detectedDomain?: string;
+}

package/src/org/types.ts

@@ -3,9 +3,23 @@
  *
  * Vocabulary types for the personal → shared organization model.
  * @see ADR-BE-XXX (Personal vs Shared Organization Model)
+ *
+ * The SSO stepper vocabulary (`./sso-stepper-types`) and the ownership-transfer
+ * DTOs (`./ownership-transfer-types`) live in sibling modules re-exported below,
+ * so `./types` stays the one import path for every org type.
  */
-
 import type { OrgChartRole } from "../permissions/orgchart-roles";
+import type {
+  OidcValidationResult,
+  OwnerIdentityInfo,
+  ProviderStatus,
+  ProviderSuggestion,
+  SsoStepperStep,
+  WorkspaceSsoState,
+} from "./sso-stepper-types";
+
+export * from "./sso-stepper-types";
+export * from "./ownership-transfer-types";
 
 /**
  * Organization type distinguishes personal workspaces from shared organizations.
@@ -274,78 +288,6 @@ export interface SsoEnforcementStatus {
   enforcedSince: string | null;
 }
 
-// =============================================================================
-// SSO Stepper Types (PRD-00197)
-// Types for the provider state machine, workspace SSO state, stepper step,
-// and supporting types for the SSO stepper redesign.
-// =============================================================================
-
-/**
- * Provider-level configuration lifecycle.
- * NOT_CONFIGURED → CONFIG_SAVED → CONFIG_VALID → TEST_SUCCESS → ENABLED
- * Any state → NOT_CONFIGURED (on credential removal or provider switch)
- */
-export type ProviderStatus =
-  | "NOT_CONFIGURED"
-  | "CONFIG_SAVED"
-  | "CONFIG_VALID"
-  | "TEST_SUCCESS"
-  | "ENABLED";
-
-/** Workspace SSO state derived from provider status + policy. */
-export type WorkspaceSsoState = "SSO_DISABLED" | "SSO_ENABLED" | "SSO_ENFORCED";
-
-/** Backend-authoritative stepper step. Frontend MUST NOT re-derive. */
-export type SsoStepperStep = "configure" | "test" | "enable" | "enforce";
-
-/** Owner identity information for the SSO readiness surface. */
-export interface OwnerIdentityInfo {
-  userId: string;
-  name: string;
-  email: string;
-  hasSsoIdentity: boolean;
-  linkedProvider: string | null;
-  lastSsoLoginAt: string | null;
-}
-
-/** Result of validating an OIDC discovery URL. */
-export interface OidcValidationResult {
-  valid: boolean;
-  issuer?: string;
-  authorizationEndpoint?: string;
-  error?: string;
-  errorCode?:
-    "UNREACHABLE" | "INVALID_DOCUMENT" | "MISSING_FIELDS" | "SSRF_BLOCKED";
-}
-
-/** Initiation payload for a test SSO login attempt. */
-export interface TestSsoInitiation {
-  authorizationUrl: string;
-  attemptId: string;
-}
-
-/** Result of a test SSO login attempt. */
-export interface TestSsoResult {
-  status: "pending" | "success" | "failed" | "expired";
-  claims?: { sub: string; email?: string; name?: string; issuer: string };
-  identityLinked?: boolean;
-  error?: string;
-  errorCode?:
-    | "IDENTITY_CONFLICT"
-    | "DOMAIN_MISMATCH"
-    | "ISSUER_MISMATCH"
-    | "CALLBACK_ERROR";
-}
-
-/** MX-based provider suggestion for SSO setup. */
-export interface ProviderSuggestion {
-  suggestedProvider: "google" | "microsoft" | null;
-  confidence: "high" | "low";
-  reason: string;
-  /** The verified domain that triggered the suggestion (for pre-filling provider inputs). */
-  detectedDomain?: string;
-}
-
 /**
  * Workspace authentication configuration.
  * Enabled auth methods and provider metadata.
@@ -739,48 +681,6 @@ export interface WorkspaceSettingsOverview extends WorkspaceInfoOverview {
   };
 }
 
-// =============================================================================
-// Ownership Transfer DTOs (PRD-00153)
-// Rich types for the transfer UI flows, supplementing OwnershipTransferRequest
-// and OwnershipTransferStatus above.
-// =============================================================================
-
-/** Request body for initiating ownership transfer (extends existing to include optional note). */
-export interface TransferInitiateRequest {
-  readonly newOwnerEmail: string;
-  readonly note?: string;
-}
-
-/** Response for transfer status queries — extends existing OwnershipTransferStatus. */
-export interface TransferStatusResponse {
-  readonly pending: boolean;
-  readonly newOwnerEmail?: string;
-  readonly note?: string;
-  readonly requestedAt?: string;
-  readonly expiresAt?: string;
-  readonly initiatorName?: string;
-}
-
-/** Read-only view for the transfer acceptance page. */
-export interface TransferAcceptanceView {
-  readonly workspaceName: string;
-  readonly initiatorName: string;
-  readonly initiatorEmail: string;
-  readonly note?: string;
-  readonly expiresAt: string;
-  readonly token: string;
-}
-
-/** Responsibility checklist items shown on the acceptance page. */
-export const TRANSFER_RESPONSIBILITIES = [
-  "You will become the sole owner of this workspace",
-  "You will be responsible for billing and compliance",
-  "The current owner will be downgraded to admin",
-  "This action cannot be undone without a new transfer",
-] as const;
-
-export type TransferResponsibility = (typeof TRANSFER_RESPONSIBILITIES)[number];
-
 // =============================================================================
 // Identity Trust Level Types (PRD-00154)
 // Org identity posture for ownership transfer constraints.

package/src/org/view-scopes.ts

@@ -33,7 +33,6 @@ export const VIEW_SCOPE_MAP = {
   // not a scope. Repointed from the never-enforced `org.view_teams` to null when
   // that scope was retired from the backend catalog (ADR-CONTRACTS-062 / ADR-BE-256).
   teams: null,
-  chat: null,
   settings: null,
   "my-work": null,
   "user-md": null,

package/src/org/workspace-admin-schemas.ts

@@ -0,0 +1,240 @@
+/**
+ * Workspace Admin Response Schemas
+ *
+ * Workspace auth configuration (SSO setup, readiness, enforcement), audit log,
+ * resolve-path, auth policy, Slack logo resync and SSO test flows.
+ *
+ * Split out of `./schemas.ts`, which re-exports this module unchanged — import
+ * from `./schemas` (or the `./org` entry), not from this file directly.
+ */
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// GET /api/workspace/auth
+// ---------------------------------------------------------------------------
+
+const OidcValidationResultSchema = z.object({
+  valid: z.boolean(),
+  issuer: z.string().optional(),
+  authorizationEndpoint: z.string().optional(),
+  error: z.string().optional(),
+  errorCode: z
+    .enum(["UNREACHABLE", "INVALID_DOCUMENT", "MISSING_FIELDS", "SSRF_BLOCKED"])
+    .optional(),
+});
+
+const SsoDiscoveryConfigSchema = z.object({
+  redirectUri: z.string(),
+  requiredScopes: z.array(z.string()),
+  isOidcConfigured: z.boolean(),
+  oidcDiscoveryUrl: z.string().nullable(),
+});
+
+const SsoCredentialStatusSchema = z.object({
+  hasClientId: z.boolean(),
+  hasClientSecret: z.boolean(),
+});
+
+const ProviderStatusSchema = z.enum([
+  "NOT_CONFIGURED",
+  "CONFIG_SAVED",
+  "CONFIG_VALID",
+  "TEST_SUCCESS",
+  "ENABLED",
+]);
+
+const SsoStepperStepSchema = z.enum(["configure", "test", "enable", "enforce"]);
+
+const SsoOperationalStateSchema = z.object({
+  providerStatus: ProviderStatusSchema,
+  currentStep: SsoStepperStepSchema,
+  stepCompleted: z.boolean(),
+  activeProvider: z.string().nullable(),
+  oidcValidation: OidcValidationResultSchema.optional(),
+  credentialsSavedAt: z.string().optional(),
+  lastTestSuccessAt: z.string().optional(),
+  lastTestSuccessProvider: z.string().optional(),
+});
+
+const SsoSetupInfoSchema = SsoDiscoveryConfigSchema.merge(
+  SsoCredentialStatusSchema,
+).merge(SsoOperationalStateSchema);
+
+const SsoReadinessCheckSchema = z.object({
+  code: z.string(),
+  label: z.string(),
+  passed: z.boolean(),
+  message: z.string(),
+});
+
+const SsoReadinessSchema = z.object({
+  ready: z.boolean(),
+  checks: z.array(SsoReadinessCheckSchema),
+});
+
+const SsoEnforcementStatusSchema = z.object({
+  enforced: z.boolean(),
+  enforcedDomains: z.array(z.string()),
+  enforcedSince: z.string().nullable(),
+});
+
+const OwnerIdentityInfoSchema = z.object({
+  userId: z.string(),
+  name: z.string(),
+  email: z.string(),
+  hasSsoIdentity: z.boolean(),
+  linkedProvider: z.string().nullable(),
+  lastSsoLoginAt: z.string().nullable(),
+});
+
+const ProviderSuggestionSchema = z.object({
+  suggestedProvider: z.enum(["google", "microsoft"]).nullable(),
+  confidence: z.enum(["high", "low"]),
+  reason: z.string(),
+  detectedDomain: z.string().optional(),
+});
+
+const AuthMethodConfigSchema = z.object({
+  enabled: z.boolean(),
+  provider: z.string().optional(),
+});
+
+export const WorkspaceAuthConfigSchema = z.object({
+  emailOtp: AuthMethodConfigSchema,
+  googleSso: AuthMethodConfigSchema,
+  microsoftSso: AuthMethodConfigSchema,
+  okta: AuthMethodConfigSchema,
+  policy: z.object({
+    requireSSO: z.boolean(),
+    allowedProviders: z.array(z.string()),
+  }),
+  ssoSetup: SsoSetupInfoSchema.optional(),
+  ssoReadiness: SsoReadinessSchema.optional(),
+  ssoEnforcement: SsoEnforcementStatusSchema.optional(),
+  workspaceSsoState: z
+    .enum(["SSO_DISABLED", "SSO_ENABLED", "SSO_ENFORCED"])
+    .optional(),
+  ownerIdentities: z.array(OwnerIdentityInfoSchema).optional(),
+  providerSuggestion: ProviderSuggestionSchema.optional(),
+});
+
+export type WorkspaceAuthConfig = z.infer<typeof WorkspaceAuthConfigSchema>;
+
+// ---------------------------------------------------------------------------
+// GET /api/workspace/audit
+// ---------------------------------------------------------------------------
+
+export const WorkspaceAuditEventSchema = z.object({
+  id: z.string(),
+  timestamp: z.string(),
+  actor: z.object({
+    id: z.string(),
+    name: z.string(),
+    type: z.enum(["user", "system"]),
+  }),
+  action: z.string(),
+  summary: z.string(),
+});
+
+export const WorkspaceAuditResponseSchema = z.array(WorkspaceAuditEventSchema);
+
+export type WorkspaceAuditEvent = z.infer<typeof WorkspaceAuditEventSchema>;
+
+// ---------------------------------------------------------------------------
+// POST /api/workspace/resolve-path
+// ---------------------------------------------------------------------------
+
+const ResolvedDeptEntitySchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  slug: z.string(),
+  memberCount: z.number(),
+});
+
+export const WorkspaceResolvePathResponseSchema = z.object({
+  layers: z.array(
+    z.discriminatedUnion("type", [
+      z.object({ type: z.literal("dept"), entity: ResolvedDeptEntitySchema }),
+      z.object({ type: z.literal("team"), entity: ResolvedDeptEntitySchema }),
+      z.object({
+        type: z.literal("members"),
+        scope: z.enum(["org", "dept", "team"]),
+      }),
+    ]),
+  ),
+});
+
+export type WorkspaceResolvePathResponse = z.infer<
+  typeof WorkspaceResolvePathResponseSchema
+>;
+
+// ---------------------------------------------------------------------------
+// PATCH /api/workspace/auth-policy
+// ---------------------------------------------------------------------------
+
+export const OrgAuthPolicySchema = z.object({
+  requireSSO: z.boolean(),
+  allowedProviders: z.array(z.string()),
+  selfRevoked: z.boolean().optional(),
+});
+
+export type OrgAuthPolicy = z.infer<typeof OrgAuthPolicySchema>;
+
+// ---------------------------------------------------------------------------
+// POST /api/workspace/auth-policy/validate-oidc
+// ---------------------------------------------------------------------------
+
+export { OidcValidationResultSchema };
+export type OidcValidationResult = z.infer<typeof OidcValidationResultSchema>;
+
+// ---------------------------------------------------------------------------
+// POST /api/workspace/resync-slack-logo
+// ---------------------------------------------------------------------------
+
+export const WorkspaceResyncSlackLogoResponseSchema = z.object({
+  success: z.literal(true),
+  logoUrl: z.string().nullable(),
+});
+
+export type WorkspaceResyncSlackLogoResponse = z.infer<
+  typeof WorkspaceResyncSlackLogoResponseSchema
+>;
+
+// ---------------------------------------------------------------------------
+// POST /api/workspace/auth-policy/test-sso
+// ---------------------------------------------------------------------------
+
+export const TestSsoInitiationSchema = z.object({
+  authorizationUrl: z.string(),
+  attemptId: z.string(),
+});
+
+export type TestSsoInitiation = z.infer<typeof TestSsoInitiationSchema>;
+
+// ---------------------------------------------------------------------------
+// GET /api/workspace/auth-policy/test-sso/:attemptId
+// ---------------------------------------------------------------------------
+
+export const TestSsoResultSchema = z.object({
+  status: z.enum(["pending", "success", "failed", "expired"]),
+  claims: z
+    .object({
+      sub: z.string(),
+      email: z.string().optional(),
+      name: z.string().optional(),
+      issuer: z.string(),
+    })
+    .optional(),
+  identityLinked: z.boolean().optional(),
+  error: z.string().optional(),
+  errorCode: z
+    .enum([
+      "IDENTITY_CONFLICT",
+      "DOMAIN_MISMATCH",
+      "ISSUER_MISMATCH",
+      "CALLBACK_ERROR",
+    ])
+    .optional(),
+});
+
+export type TestSsoResult = z.infer<typeof TestSsoResultSchema>;

package/src/root-exports/README.md

@@ -0,0 +1,91 @@
+# root-exports/
+
+Themed slices of the package root entry (`src/index.ts`).
+
+## Purpose
+
+Named re-export lists for most of the package root surface, split by theme.
+
+They keep `src/index.ts` a short table of contents under the `graduation`
+guard's thresholds; `src/index.ts` re-exports every slice here with
+`export * from "./root-exports/<slice>"`.
+
+| Slice              | Covers                                                                                                           |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| `delivery.ts`      | notifications, action items, user events, the in-app inbox, proactive delivery, workflows                        |
+| `collaboration.ts` | the comment wire contract and the chat domain                                                                    |
+| `org-workspace.ts` | org, workspace, membership, invite, directory, company.md and sharing vocabulary                                 |
+| `org-structure.ts` | sync runs, conflicts, reconciliation, structure findings, transformations, canonical facts, inference, authority |
+| `agent-runtime.ts` | MCP tool discovery, message parts, execution kinds, Ralph, internal admin, rate limits                           |
+| `platform.ts`      | impersonation, usage telemetry, resource keys, errors, the generated OpenAPI surface, security, request tiers    |
+
+## Invariants
+
+- **Named lists only.** A slice re-exports by name, never with `export *`. Most
+  root lists are a deliberate SUBSET of their domain barrel (e.g. the root exposes
+  307 of the org barrel's 483 names); a star here would silently widen the root.
+- **Content, not policy.** A slice decides nothing: moving a list between a slice
+  and `src/index.ts` must leave the root surface byte-for-byte unchanged.
+- **No name in two root star sources.** `src/index.ts` star-exports these slices
+  next to whole-domain stars (`./permissions`, `./billing/index`, …). Two star
+  exports of one name with different bindings are ambiguous, and the name drops
+  out of the surface — so a name that collides is exported BY NAME from
+  `src/index.ts` instead (today: the org sharing `AccessLevel`, which collides
+  with `./permissions`). `tsc` reports the collision as TS2308.
+- **Root-only.** Nothing imports a slice except `src/index.ts`; consumers import
+  the package root. The `system` and `identity` lists stay in `src/index.ts`
+  itself, because the export guard reads their names from that file.
+
+## Public API
+
+None of its own. Every name here is part of the package root surface and is
+documented in its owning domain (`src/org/`, `src/chat/`, `src/comments/`, …).
+
+<!-- BEGIN GENERATED: readme-dependencies — derived from code by `pnpm readme-api`. Do not edit. -->
+
+## Dependencies
+
+**Internal domains:**
+
+- `action-items`
+- `api`
+- `autotune`
+- `chat`
+- `comments`
+- `errors`
+- `execution`
+- `generated`
+- `impersonation`
+- `impersonation-events`
+- `internal-admin`
+- `mcp`
+- `message-parts`
+- `mutations`
+- `notifications`
+- `observability`
+- `org`
+- `pressure`
+- `proactive`
+- `queryIntent`
+- `ralph`
+- `rate-limit`
+- `requests`
+- `resource-keys`
+- `resource-response`
+- `route-builder`
+- `safe-mode`
+- `security`
+- `sse`
+- `timeouts`
+- `tracing`
+- `types`
+- `usage`
+- `user-events`
+- `user-notifications`
+- `workflows`
+
+**External packages:**
+
+_None._
+
+<!-- END GENERATED: readme-dependencies -->