@company-semantics/contracts 1.16.0 → 1.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "1.16.0",
+  "version": "1.18.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -112,17 +112,17 @@
     "node": "22.x"
   },
   "dependencies": {
-    "zod": "^4.2.1"
+    "zod": "^4.4.1"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",
     "husky": "^9.1.7",
     "lint-staged": "^16.4.0",
-    "markdownlint-cli2": "^0.22.0",
+    "markdownlint-cli2": "^0.22.1",
     "openapi-typescript": "^7.13.0",
     "tsx": "^4.21.0",
     "typescript": "^5",
-    "vitest": "^4.1.4",
+    "vitest": "^4.1.5",
     "yaml": "^2.8.3"
   },
   "pnpm": {

package/src/admin/authz-simulate.ts

@@ -0,0 +1,40 @@
+/**
+ * Admin What-If Simulator — request/response schemas.
+ *
+ * Mirrors the Fastify schema for `POST /api/admin/authz/simulate`. The endpoint
+ * is read-only and returns the full structured AuthDecision verbatim, so that
+ * admins can debug denials by reading evaluator name + reason rather than
+ * guessing. See PRD-00544 and feedback_decision_logic_must_be_visible.md.
+ */
+import { z } from 'zod';
+
+export const SimulateRequest = z.object({
+  actor: z.object({
+    type: z.enum(['user', 'agent']),
+    id: z.string().uuid(),
+  }),
+  scope: z.string(),
+  resource_kind: z.enum(['system', 'org', 'team', 'member', 'doc']),
+  resource_id: z.string().uuid().optional(),
+});
+
+export type SimulateRequest = z.infer<typeof SimulateRequest>;
+
+export const SimulateResponse = z.discriminatedUnion('allow', [
+  z.object({
+    allow: z.literal(true),
+    matched_grant: z.unknown(),
+    evaluator_name: z.string().optional(),
+    evaluator_reason: z.string().optional(),
+  }),
+  z.object({
+    allow: z.literal(false),
+    deny_reasons: z.array(z.unknown()),
+    missing: z.object({
+      scope: z.string().optional(),
+      suggested_role: z.string().optional(),
+    }),
+  }),
+]);
+
+export type SimulateResponse = z.infer<typeof SimulateResponse>;

package/src/admin/direct-grants.ts

@@ -0,0 +1,31 @@
+/**
+ * Admin Direct Grants — request/response schemas.
+ *
+ * Mirrors the Fastify schemas for `POST /api/admin/grants/direct` and the
+ * persisted grant row. `granted_by` is intentionally absent from the create
+ * body — it is set by the server from the authenticated actor (see PRD-00544
+ * direct-grant-audit-trail and the `direct-grant-audit` CI guard).
+ */
+import { z } from 'zod';
+
+export const DirectGrantCreate = z.object({
+  subject_id: z.string().uuid(),
+  scope_pattern: z.string(),
+  resource_filter: z.record(z.string(), z.unknown()).optional(),
+  expires_at: z.string().datetime().optional(),
+});
+
+export type DirectGrantCreate = z.infer<typeof DirectGrantCreate>;
+
+export const DirectGrant = z.object({
+  id: z.string().uuid(),
+  org_id: z.string().uuid(),
+  subject_id: z.string().uuid(),
+  scope_pattern: z.string(),
+  source: z.literal('direct'),
+  granted_by: z.string().uuid(),
+  granted_at: z.string().datetime(),
+  expires_at: z.string().datetime().nullable(),
+});
+
+export type DirectGrant = z.infer<typeof DirectGrant>;

package/src/api/generated-spec-hash.ts

@@ -1,3 +1,3 @@
 // AUTO-GENERATED — do not edit. Run pnpm generate:spec-hash to regenerate.
-export const SPEC_HASH = 'e337542ea39d' as const;
-export const SPEC_HASH_FULL = 'e337542ea39de6f11b03f87d300e3e4c842825267c6918b1a37f2f86502124f8' as const;
+export const SPEC_HASH = '6edfe6e7117c' as const;
+export const SPEC_HASH_FULL = '6edfe6e7117c49e81cd7cad51ac9cd5c6f4c9e18cf7a37ff82a5630855404a00' as const;

package/src/api/generated.ts

@@ -72,6 +72,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/auth/consent/grant": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Grant incremental consent for a write action
+         * @description Records per-(user, org, action) consent for a registered write action. Idempotent: regranting an already-active consent re-emits the audit event but does not create a duplicate row.
+         */
+        post: operations["grantIncrementalConsent"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/me": {
         parameters: {
             query?: never;
@@ -2036,6 +2056,15 @@ export interface components {
             /** @constant */
             ok: true;
         };
+        ConsentGrantResponse: {
+            /** @constant */
+            ok: true;
+            /** Format: date-time */
+            grantedAt: string;
+        };
+        ConsentGrantRequest: {
+            actionId: string;
+        };
         MeResponse: {
             /** Format: uuid */
             userId: string;
@@ -3552,6 +3581,63 @@ export interface operations {
             };
         };
     };
+    grantIncrementalConsent: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ConsentGrantRequest"];
+            };
+        };
+        responses: {
+            /** @description Consent granted */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ConsentGrantResponse"];
+                };
+            };
+            /** @description Invalid or unregistered actionId */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        error: string;
+                        message: string;
+                    };
+                };
+            };
+            /** @description Not authenticated */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description CSRF token missing or invalid */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Rate limit exceeded */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     getCurrentUser: {
         parameters: {
             query?: never;

package/src/generated/openapi-routes.ts

@@ -9,6 +9,7 @@ export const openApiRoutes = {
   '/api/account/deletion-eligibility': ['GET'],
   '/api/account/sessions': ['GET'],
   '/api/account/sessions/{sessionId}': ['DELETE'],
+  '/api/auth/consent/grant': ['POST'],
   '/api/chats': ['GET', 'POST'],
   '/api/chats/by-interaction/{interactionId}': ['GET'],
   '/api/chats/events': ['GET'],
@@ -47,7 +48,8 @@ export const openApiRoutes = {
   '/api/internal-admin/impersonate/start': ['POST'],
   '/api/me': ['GET'],
   '/api/org-units': ['POST'],
-  '/api/org-units/{unitId}': ['GET'],
+  '/api/org-units/tree': ['GET'],
+  '/api/org-units/{unitId}': ['GET', 'PATCH'],
   '/api/org-units/{unitId}/ancestors': ['GET'],
   '/api/org-units/{unitId}/archive': ['POST'],
   '/api/org-units/{unitId}/children': ['GET'],
@@ -73,7 +75,7 @@ export const openApiRoutes = {
   '/api/orgs/{orgId}/billing': ['GET'],
   '/api/orgs/{orgId}/budget-config': ['GET', 'PUT'],
   '/api/orgs/{orgId}/level-config': ['GET', 'PUT'],
-  '/api/orgs/{orgId}/tree': ['GET'],
+  '/api/rbac/roles': ['GET'],
   '/api/scope/check': ['GET'],
   '/api/scope/check-batch': ['POST'],
   '/api/shared/{token}': ['GET'],
@@ -103,7 +105,7 @@ export const openApiRoutes = {
   '/api/workspace/invites/validate': ['GET'],
   '/api/workspace/invites/{id}': ['DELETE'],
   '/api/workspace/members': ['GET'],
-  '/api/workspace/members/{id}': ['DELETE'],
+  '/api/workspace/members/{id}': ['DELETE', 'GET'],
   '/api/workspace/members/{id}/role': ['PATCH'],
   '/api/workspace/name': ['PATCH'],
   '/api/workspace/resolve-path': ['POST'],

package/src/impersonation/index.ts

@@ -29,9 +29,14 @@ export {
   ImpersonationSessionResponseSchema,
   ImpersonationSessionNullableResponseSchema,
   EndImpersonationResponseSchema,
+  ImpersonationSessionWireDtoSchema,
 } from './schemas'
 
 export type {
   ImpersonationSessionResponse,
   EndImpersonationResponse,
+  ImpersonationSessionWireDtoParsed,
 } from './schemas'
+
+// Wire DTO for SSE projection (PRD-00557 F5)
+export type { ImpersonationSessionWireDto } from '../impersonation-events'

package/src/impersonation/schemas.ts

@@ -36,5 +36,24 @@ export const EndImpersonationResponseSchema = z.object({
   ok: z.literal(true),
 })
 
+/**
+ * Wire-only DTO for SSE snapshot/started events (PRD-00557 F5).
+ *
+ * .strict() rejects extraneous keys so a backend regression that leaks
+ * reason / reasonHash / ipAddress / userAgent is caught at the contract
+ * boundary, not at the network. This complements the type-level
+ * narrowing in src/impersonation-events.ts.
+ */
+export const ImpersonationSessionWireDtoSchema = z
+  .object({
+    id: z.string(),
+    targetUserId: z.string(),
+    startedAt: z.string().datetime({ offset: true }),
+    expiresAt: z.string().datetime({ offset: true }),
+    endedAt: z.string().datetime({ offset: true }).nullable(),
+  })
+  .strict()
+
 export type ImpersonationSessionResponse = z.infer<typeof ImpersonationSessionResponseSchema>
 export type EndImpersonationResponse = z.infer<typeof EndImpersonationResponseSchema>
+export type ImpersonationSessionWireDtoParsed = z.infer<typeof ImpersonationSessionWireDtoSchema>

package/src/impersonation-events.ts

@@ -7,7 +7,19 @@
  */
 
 import type { BaseEvent } from './chat/types'
-import type { ImpersonationSession } from './impersonation'
+
+/**
+ * Minimal projection of an impersonation session for over-the-wire delivery.
+ * Excludes reason, reasonHash, ipAddress, userAgent — those stay server-side
+ * (PRD-00557 F5: type-impossible wire exposure of admin-private fields).
+ */
+export interface ImpersonationSessionWireDto {
+  readonly id: string
+  readonly targetUserId: string
+  readonly startedAt: string
+  readonly expiresAt: string
+  readonly endedAt: string | null
+}
 
 /**
  * Sent as the first frame on SSE connection.
@@ -17,7 +29,7 @@ import type { ImpersonationSession } from './impersonation'
 export interface ImpersonationSessionSnapshotEvent extends BaseEvent {
   type: 'impersonation.session.snapshot'
   data: {
-    session: ImpersonationSession | null
+    session: ImpersonationSessionWireDto | null
   }
 }
 
@@ -25,7 +37,7 @@ export interface ImpersonationSessionSnapshotEvent extends BaseEvent {
 export interface ImpersonationSessionStartedEvent extends BaseEvent {
   type: 'impersonation.session.started'
   data: {
-    session: ImpersonationSession
+    session: ImpersonationSessionWireDto
   }
 }