@grantjs/schema 1.4.2 → 1.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grantjs/schema",
-  "version": "1.4.2",
+  "version": "1.5.1",
   "description": "GraphQL schema and generated types for Grant",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -13,14 +13,14 @@
     "@graphql-typed-document-node/core": "^3.2.0"
   },
   "devDependencies": {
-    "@graphql-codegen/cli": "^7.1.2",
-    "@graphql-codegen/client-preset": "^6.0.1",
-    "@graphql-codegen/typescript": "^6.0.2",
-    "@graphql-codegen/typescript-resolvers": "^6.0.2",
-    "@parcel/watcher": "^2.5.4",
-    "@types/node": "^25.9.3",
-    "eslint": "^10.5.0",
-    "typescript": "^6"
+    "@graphql-codegen/cli": "^7.2.0",
+    "@graphql-codegen/client-preset": "^6.1.0",
+    "@graphql-codegen/typescript": "^6.1.0",
+    "@graphql-codegen/typescript-resolvers": "^6.1.0",
+    "@parcel/watcher": "^2.6.0",
+    "@types/node": "^26.1.1",
+    "eslint": "^10.7.0",
+    "typescript": "^6.0.3"
   },
   "scripts": {
     "build": "tsc",

package/src/events/event-catalog.ts

@@ -0,0 +1,214 @@
+/**
+ * Canonical domain-event catalog.
+ *
+ * Single source of truth for every event `type` the platform emits, its
+ * notification `category`, its `deliveryClass`, and the declarative
+ * `audienceRule` consumed by the notification audience resolver. Services
+ * reference these constants instead of string literals; a coverage test asserts
+ * each mutating action that should emit has an entry here.
+ */
+
+export const EVENT_CATEGORIES = ['security', 'iam', 'membership', 'integrations'] as const;
+export type EventCategory = (typeof EVENT_CATEGORIES)[number];
+
+export const EVENT_DELIVERY_CLASSES = ['transactional', 'notification'] as const;
+export type EventDeliveryClass = (typeof EVENT_DELIVERY_CLASSES)[number];
+
+/** Declarative audience primitives resolved by the notification audience resolver. */
+export const AUDIENCE_PRIMITIVES = [
+  'actor',
+  'subject',
+  'scopeMembers',
+  'roleHolders',
+  'owners',
+  'watchers',
+] as const;
+export type AudiencePrimitive = (typeof AUDIENCE_PRIMITIVES)[number];
+
+export interface AudienceRule {
+  /** Primitives whose resolved users are unioned to form the candidate set. */
+  primitives: readonly AudiencePrimitive[];
+  /** Exclude the acting user from the resolved audience (default true). */
+  excludeActor?: boolean;
+}
+
+export interface EventCatalogEntry {
+  category: EventCategory;
+  deliveryClass: EventDeliveryClass;
+  audienceRule: AudienceRule;
+}
+
+const IAM_OWNERS: EventCatalogEntry = {
+  category: 'iam',
+  deliveryClass: 'notification',
+  audienceRule: { primitives: ['owners'], excludeActor: true },
+};
+
+const IAM_SUBJECT_OWNERS: EventCatalogEntry = {
+  category: 'iam',
+  deliveryClass: 'notification',
+  audienceRule: { primitives: ['subject', 'owners'], excludeActor: true },
+};
+
+const IAM_ROLE_HOLDERS_OWNERS: EventCatalogEntry = {
+  category: 'iam',
+  deliveryClass: 'notification',
+  audienceRule: { primitives: ['roleHolders', 'owners'], excludeActor: true },
+};
+
+const MEMBERSHIP_SUBJECT_OWNERS: EventCatalogEntry = {
+  category: 'membership',
+  deliveryClass: 'notification',
+  audienceRule: { primitives: ['subject', 'owners'], excludeActor: true },
+};
+
+const SECURITY_OWNERS: EventCatalogEntry = {
+  category: 'security',
+  deliveryClass: 'notification',
+  audienceRule: { primitives: ['owners'], excludeActor: true },
+};
+
+const SECURITY_SUBJECT: EventCatalogEntry = {
+  category: 'security',
+  deliveryClass: 'notification',
+  audienceRule: { primitives: ['subject'], excludeActor: false },
+};
+
+const SECURITY_SUBJECT_EXCLUDE_ACTOR: EventCatalogEntry = {
+  category: 'security',
+  deliveryClass: 'notification',
+  audienceRule: { primitives: ['subject'], excludeActor: true },
+};
+
+const INTEGRATIONS_OWNERS: EventCatalogEntry = {
+  category: 'integrations',
+  deliveryClass: 'notification',
+  audienceRule: { primitives: ['owners'], excludeActor: true },
+};
+
+export const EVENT_TYPES = [
+  // IAM mutations (Phase 1 slice)
+  'role.created',
+  'role.updated',
+  'role.deleted',
+  'permission.created',
+  'permission.updated',
+  'permission.deleted',
+  'group.created',
+  'group.updated',
+  'group.deleted',
+  'resource.created',
+  'resource.updated',
+  'resource.deleted',
+  'role.permission_assigned',
+  'role.permission_revoked',
+  'user.permission_assigned',
+  'user.permission_revoked',
+  'group.permission_assigned',
+  'group.permission_revoked',
+  'role.group_assigned',
+  'role.group_revoked',
+  'user.group_assigned',
+  'user.group_revoked',
+  'api_key.created',
+  'api_key.rotated',
+  'api_key.revoked',
+  'user.role_assigned',
+  'user.role_revoked',
+  // Lifecycle / membership / security (Phase 3 seed)
+  'organization.invitation_sent',
+  'organization.invitation_accepted',
+  'organization.invitation_revoked',
+  'organization.member_added',
+  'organization.member_role_changed',
+  'organization.member_removed',
+  'project.user_added',
+  'project.user_removed',
+  'project.user_profile_updated',
+  'user.email_verification_requested',
+  'organization.mfa_enforcement_changed',
+  'signing_key.created',
+  'signing_key.rotated',
+  'user.mfa_enabled',
+  'user.mfa_disabled',
+  'user.mfa_recovery_codes_regenerated',
+  'user.session_revoked',
+  'user.sessions_revoked',
+  'user.password_changed',
+  // CDM / project sync job summaries (entity events suppressed during import)
+  'project_sync.completed',
+  'project_sync.failed',
+] as const;
+
+export type EventType = (typeof EVENT_TYPES)[number];
+
+export const EVENT_CATALOG: Readonly<Record<EventType, EventCatalogEntry>> = {
+  'role.created': IAM_ROLE_HOLDERS_OWNERS,
+  'role.updated': IAM_OWNERS,
+  'role.deleted': IAM_OWNERS,
+  'permission.created': IAM_OWNERS,
+  'permission.updated': IAM_ROLE_HOLDERS_OWNERS,
+  'permission.deleted': IAM_OWNERS,
+  'group.created': IAM_OWNERS,
+  'group.updated': IAM_OWNERS,
+  'group.deleted': IAM_OWNERS,
+  'resource.created': IAM_OWNERS,
+  'resource.updated': IAM_OWNERS,
+  'resource.deleted': IAM_OWNERS,
+  'role.permission_assigned': IAM_OWNERS,
+  'role.permission_revoked': IAM_OWNERS,
+  'user.permission_assigned': IAM_SUBJECT_OWNERS,
+  'user.permission_revoked': IAM_SUBJECT_OWNERS,
+  'group.permission_assigned': IAM_OWNERS,
+  'group.permission_revoked': IAM_OWNERS,
+  'role.group_assigned': IAM_OWNERS,
+  'role.group_revoked': IAM_OWNERS,
+  'user.group_assigned': IAM_SUBJECT_OWNERS,
+  'user.group_revoked': IAM_SUBJECT_OWNERS,
+  'api_key.created': SECURITY_OWNERS,
+  'api_key.rotated': SECURITY_OWNERS,
+  'api_key.revoked': SECURITY_OWNERS,
+  'user.role_assigned': IAM_SUBJECT_OWNERS,
+  'user.role_revoked': IAM_SUBJECT_OWNERS,
+  'organization.invitation_sent': {
+    category: 'membership',
+    deliveryClass: 'notification',
+    audienceRule: { primitives: ['subject'], excludeActor: true },
+  },
+  'organization.invitation_accepted': MEMBERSHIP_SUBJECT_OWNERS,
+  'organization.invitation_revoked': MEMBERSHIP_SUBJECT_OWNERS,
+  'organization.member_added': MEMBERSHIP_SUBJECT_OWNERS,
+  'organization.member_role_changed': MEMBERSHIP_SUBJECT_OWNERS,
+  'organization.member_removed': MEMBERSHIP_SUBJECT_OWNERS,
+  'project.user_added': MEMBERSHIP_SUBJECT_OWNERS,
+  'project.user_removed': MEMBERSHIP_SUBJECT_OWNERS,
+  'project.user_profile_updated': MEMBERSHIP_SUBJECT_OWNERS,
+  'user.email_verification_requested': {
+    category: 'security',
+    deliveryClass: 'transactional',
+    audienceRule: { primitives: ['subject'], excludeActor: false },
+  },
+  'organization.mfa_enforcement_changed': {
+    category: 'security',
+    deliveryClass: 'notification',
+    audienceRule: { primitives: ['scopeMembers'], excludeActor: false },
+  },
+  'signing_key.created': SECURITY_OWNERS,
+  'signing_key.rotated': SECURITY_OWNERS,
+  'user.mfa_enabled': SECURITY_SUBJECT,
+  'user.mfa_disabled': SECURITY_SUBJECT,
+  'user.mfa_recovery_codes_regenerated': SECURITY_SUBJECT,
+  'user.session_revoked': SECURITY_SUBJECT_EXCLUDE_ACTOR,
+  'user.sessions_revoked': SECURITY_SUBJECT,
+  'user.password_changed': SECURITY_SUBJECT,
+  'project_sync.completed': INTEGRATIONS_OWNERS,
+  'project_sync.failed': INTEGRATIONS_OWNERS,
+};
+
+export function getEventCatalogEntry(type: EventType): EventCatalogEntry {
+  return EVENT_CATALOG[type];
+}
+
+export function isKnownEventType(type: string): type is EventType {
+  return Object.prototype.hasOwnProperty.call(EVENT_CATALOG, type);
+}

package/src/events/event-envelope.ts

@@ -0,0 +1,73 @@
+import type { Scope } from '../generated/schema-types';
+import type { EventCategory, EventType } from './event-catalog';
+
+/**
+ * Payload carried inside an event. The internal model can be rich; the external
+ * webhook envelope projects `data` through a redaction allowlist.
+ */
+export interface EventData {
+  /** Snapshot of the entity after the change (redacted on external delivery). */
+  after?: Record<string, unknown> | null;
+  /** Snapshot before the change (optional). */
+  before?: Record<string, unknown> | null;
+  /** Changed-fields delta: field -> { from, to }. */
+  delta?: Record<string, { from: unknown; to: unknown }> | null;
+}
+
+/** Reference to the aggregate (entity) the event is about. */
+export interface EventAggregateRef {
+  kind: string;
+  id: string;
+}
+
+/**
+ * Input accepted by `IEventPublisher.publish`. The publisher fills in id,
+ * sequence, and persistence concerns.
+ */
+export interface DomainEventInput {
+  type: EventType;
+  /** Optional explicit scope; when omitted the publisher derives it from the request auth context. */
+  scope?: Scope;
+  actor?: { userId: string } | null;
+  subjectUserId?: string | null;
+  aggregate?: EventAggregateRef;
+  data: EventData;
+  occurredAt?: Date;
+}
+
+/**
+ * The internal event as persisted to `event_log` and read by in-process
+ * consumers (notification generator). Carries the full (unredacted) payload.
+ */
+export interface DomainEvent {
+  id: string;
+  sequence: number;
+  type: EventType;
+  category: EventCategory;
+  deliveryClass: 'transactional' | 'notification';
+  scope: Scope;
+  actorUserId: string | null;
+  subjectUserId: string | null;
+  aggregate?: EventAggregateRef;
+  data: EventData;
+  occurredAt: Date;
+}
+
+/**
+ * External event envelope delivered to webhook consumers. CloudEvents 1.0 core
+ * fields plus Grant extension attributes (prefixed `grant`). `data` is the
+ * redacted projection of the internal payload.
+ */
+export interface CloudEventEnvelope {
+  specversion: '1.0';
+  id: string;
+  source: string;
+  type: EventType;
+  time: string;
+  subject?: string;
+  grantsequence: string;
+  grantscope: { tenant: string; id: string };
+  grantactor?: { userId: string } | null;
+  grantcategory: EventCategory;
+  data: EventData;
+}

package/src/events/index.ts

@@ -0,0 +1,2 @@
+export * from './event-catalog';
+export * from './event-envelope';