@company-semantics/contracts 2.17.0 → 2.18.0

package/package.json

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

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;
@@ -4534,6 +4585,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 +8896,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/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>;