@company-semantics/contracts 2.17.0 → 3.0.0

package/package.json

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

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 = '3d5da96bdeb1' as const;
-export const SPEC_HASH_FULL = '3d5da96bdeb12a1223f19d67956bfa0a481abc37813c181c0897a10c7e8f9b80' as const;
+export const SPEC_HASH = '30c4d8eb9dce' as const;
+export const SPEC_HASH_FULL = '30c4d8eb9dcefed99d44a531c27a9e5a25eb4842c578e8933f64678a13816d07' as const;

package/src/api/generated.ts

@@ -2570,6 +2570,57 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/{entityType}/{id}/who-can-access": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List every principal with effective access to an entity (grouped by source) */
+        get: operations["getEntityWhoCanAccess"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/{entityType}/{id}/recent-decisions": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Newest-first permission_decisions rows for an entity (introspection timeline) */
+        get: operations["getEntityRecentDecisions"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/me/access-list": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Every effective grant for the calling user — "what can I access?" */
+        get: operations["getMyAccessList"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/internal-admin/impersonate/start": {
         parameters: {
             query?: never;
@@ -3539,10 +3590,6 @@ export interface components {
                 id: string;
                 name: string;
             } | null;
-            coOwners: {
-                id: string;
-                name: string;
-            }[];
             canEdit: boolean;
             inheritsFrom: string | null;
             sources: {
@@ -4534,6 +4581,50 @@ export interface components {
                 id: string;
             };
         };
+        WhoCanAccessResponse: {
+            entity_type: string;
+            /** Format: uuid */
+            entity_id: string;
+            principals: {
+                principal: {
+                    /** @enum {string} */
+                    type: "user" | "unit" | "org";
+                    /** Format: uuid */
+                    id: string;
+                };
+                /** @enum {string} */
+                access_level: "owner" | "editor" | "commenter" | "viewer";
+                /** @enum {string} */
+                source: "explicit" | "ownership" | "visibility" | "inheritance" | "migration";
+            }[];
+        };
+        RecentDecisionsResponse: {
+            entity_type: string;
+            /** Format: uuid */
+            entity_id: string;
+            rows: {
+                /** Format: uuid */
+                id: string;
+                policy_name: string;
+                actor_user_id: string | null;
+                allow: boolean;
+                reason: string;
+                source_chain: ("explicit" | "ownership" | "visibility" | "inheritance" | "migration")[];
+                /** Format: date-time */
+                decided_at: string;
+            }[];
+        };
+        MyAccessListResponse: {
+            entries: {
+                entity_type: string;
+                /** Format: uuid */
+                entity_id: string;
+                /** @enum {string} */
+                access_level: "owner" | "editor" | "commenter" | "viewer";
+                /** @enum {string} */
+                source: "explicit" | "ownership" | "visibility" | "inheritance" | "migration";
+            }[];
+        };
         ImpersonationSessionResponse: {
             session: {
                 impersonationSessionId: string;
@@ -8801,6 +8892,88 @@ export interface operations {
             };
         };
     };
+    getEntityWhoCanAccess: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                entityType: string;
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Effective grants for the entity — one element per (principal, source) row in effective_acl_grants */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["WhoCanAccessResponse"];
+                };
+            };
+            /** @description Entity not found or caller lacks View on the entity (no-leak — the deny path 404s like the missing-entity path) */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    getEntityRecentDecisions: {
+        parameters: {
+            query?: {
+                limit?: number;
+            };
+            header?: never;
+            path: {
+                entityType: string;
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Newest-first permission_decisions rows for the entity (reason verbatim) */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["RecentDecisionsResponse"];
+                };
+            };
+            /** @description Entity not found or caller lacks View on the entity (no-leak — the deny path 404s like the missing-entity path) */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    getMyAccessList: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Effective grants for the calling user across all sources */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["MyAccessListResponse"];
+                };
+            };
+        };
+    };
     startImpersonation: {
         parameters: {
             query?: never;

package/src/content/schemas.ts

@@ -66,7 +66,6 @@ export const CompanyMdDocResponseSchema = z.object({
   parentId: z.string().nullable(),
   owningUnitId: z.string().nullable(),
   owner: CompanyMdPersonSchema.nullable(),
-  coOwners: z.array(CompanyMdPersonSchema),
   canEdit: z.boolean(),
   inheritsFrom: z.string().nullable(),
   sources: z.array(CompanyMdSourceSchema),

package/src/generated/openapi-routes.ts

@@ -50,6 +50,7 @@ export const openApiRoutes = {
   '/api/internal-admin/impersonate/session': ['GET'],
   '/api/internal-admin/impersonate/start': ['POST'],
   '/api/me': ['GET'],
+  '/api/me/access-list': ['GET'],
   '/api/me/meetings/recordings/start': ['POST'],
   '/api/me/meetings/recordings/{id}': ['DELETE'],
   '/api/me/meetings/recordings/{id}/complete': ['POST'],
@@ -75,6 +76,7 @@ export const openApiRoutes = {
   '/api/org-units/{unitId}/memberships': ['GET', 'POST'],
   '/api/org-units/{unitId}/memberships/{userId}': ['DELETE'],
   '/api/org-units/{unitId}/memberships/{userId}/role': ['PUT'],
+  '/api/org-units/{unitId}/my-authority': ['GET'],
   '/api/org-units/{unitId}/owners': ['GET'],
   '/api/org-units/{unitId}/permissions': ['GET'],
   '/api/org-units/{unitId}/relationships': ['GET', 'POST'],
@@ -143,8 +145,10 @@ export const openApiRoutes = {
   '/api/{entityType}/{id}/acl': ['GET'],
   '/api/{entityType}/{id}/acl/{principalType}/{principalId}': ['DELETE', 'PUT'],
   '/api/{entityType}/{id}/effective-access': ['POST'],
+  '/api/{entityType}/{id}/recent-decisions': ['GET'],
   '/api/{entityType}/{id}/transfer-ownership': ['POST'],
   '/api/{entityType}/{id}/visibility': ['PATCH'],
+  '/api/{entityType}/{id}/who-can-access': ['GET'],
   '/auth/logout': ['POST'],
   '/auth/me': ['GET'],
   '/auth/sso/callback': ['GET', 'POST'],

package/src/org/company-md.ts

@@ -123,10 +123,6 @@ export interface CompanyMdDocCore extends CompanyMdNodeIdentity {
 
 export interface CompanyMdDocCollaborators {
   readonly owner: { readonly id: string; readonly name: string } | null;
-  readonly coOwners: ReadonlyArray<{
-    readonly id: string;
-    readonly name: string;
-  }>;
   readonly canEdit: boolean;
   readonly members: ReadonlyArray<{
     readonly id: string;

package/src/permissions/index.ts

@@ -8,3 +8,4 @@ export * from './access-levels';
 export * from './orgchart-roles';
 export * from './access-source';
 export * from './share-api';
+export * from './permission-introspection';

package/src/permissions/permission-introspection.ts

@@ -0,0 +1,85 @@
+/**
+ * Permission Introspection API Vocabulary
+ *
+ * Zod schemas for the AUTH-010 introspection surfaces (PRD-00678): three
+ * read-only GET routes over the AUTH-002 effective_acl_grants projection and
+ * the AUTH-006 permission_decisions audit sink.
+ *
+ * Backend routes:
+ *   - GET /api/{entityType}/{id}/who-can-access
+ *   - GET /api/{entityType}/{id}/recent-decisions
+ *   - GET /api/me/access-list
+ *
+ * No new tables or policies — every read goes through existing infrastructure
+ * + the AUTH-006 evaluate() + assertAllowed() gate (entity-scoped routes).
+ *
+ * Per `feedback-decision-logic-must-be-visible`: reason strings + source chains
+ * flow verbatim to the UI. The schema mirrors what the evaluator records into
+ * permission_decisions; the UI never re-derives.
+ */
+import { z } from 'zod';
+import { AccessLevelSchema } from './access-levels';
+import { AccessSourceSchema } from './access-source';
+import { PrincipalSchema } from './share-api';
+
+// ---------------------------------------------------------------------------
+// WhoCanAccess — every principal with effective access to an entity.
+// ---------------------------------------------------------------------------
+
+export const WhoCanAccessPrincipalSchema = z.object({
+  principal: PrincipalSchema,
+  access_level: AccessLevelSchema,
+  source: AccessSourceSchema,
+});
+export type WhoCanAccessPrincipal = z.infer<typeof WhoCanAccessPrincipalSchema>;
+
+export const WhoCanAccessResponseSchema = z.object({
+  entity_type: z.string(),
+  entity_id: z.string().uuid(),
+  principals: z.array(WhoCanAccessPrincipalSchema),
+});
+export type WhoCanAccessResponse = z.infer<typeof WhoCanAccessResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// RecentDecisions — newest-first permission_decisions rows for an entity.
+// ---------------------------------------------------------------------------
+
+export const RecentDecisionSchema = z.object({
+  id: z.string().uuid(),
+  policy_name: z.string(),
+  actor_user_id: z.string().uuid().nullable(),
+  allow: z.boolean(),
+  reason: z.string(),
+  source_chain: z.array(AccessSourceSchema),
+  decided_at: z.string().datetime(),
+});
+export type RecentDecision = z.infer<typeof RecentDecisionSchema>;
+
+export const RecentDecisionsResponseSchema = z.object({
+  entity_type: z.string(),
+  entity_id: z.string().uuid(),
+  rows: z.array(RecentDecisionSchema),
+});
+export type RecentDecisionsResponse = z.infer<typeof RecentDecisionsResponseSchema>;
+
+export const RecentDecisionsQuerySchema = z.object({
+  limit: z.coerce.number().int().min(1).max(200).default(50),
+});
+export type RecentDecisionsQuery = z.infer<typeof RecentDecisionsQuerySchema>;
+
+// ---------------------------------------------------------------------------
+// MyAccessList — every effective row for the calling user's principal.
+// ---------------------------------------------------------------------------
+
+export const MyAccessEntrySchema = z.object({
+  entity_type: z.string(),
+  entity_id: z.string().uuid(),
+  access_level: AccessLevelSchema,
+  source: AccessSourceSchema,
+});
+export type MyAccessEntry = z.infer<typeof MyAccessEntrySchema>;
+
+export const MyAccessListResponseSchema = z.object({
+  entries: z.array(MyAccessEntrySchema),
+});
+export type MyAccessListResponse = z.infer<typeof MyAccessListResponseSchema>;