@adobe/spacecat-shared-data-access 3.24.0 → 3.26.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [@adobe/spacecat-shared-data-access-v3.26.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v3.25.0...@adobe/spacecat-shared-data-access-v3.26.0) (2026-03-19)
+
+### Features
+
+* add access control helpers for cross-org delegation (Option 2a) ([#1453](https://github.com/adobe/spacecat-shared/issues/1453)) ([960623e](https://github.com/adobe/spacecat-shared/commit/960623ea9e77e849be8b0a5bd7ee047309377cef)), closes [adobe/spacecat-auth-service#503](https://github.com/adobe/spacecat-auth-service/issues/503) [#1448](https://github.com/adobe/spacecat-shared/issues/1448)
+
+## [@adobe/spacecat-shared-data-access-v3.25.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v3.24.0...@adobe/spacecat-shared-data-access-v3.25.0) (2026-03-19)
+
+### Features
+
+* cross-org delegation entity models and AuthInfo extensions ([#1448](https://github.com/adobe/spacecat-shared/issues/1448)) ([b0cb091](https://github.com/adobe/spacecat-shared/commit/b0cb091432f15eb304e20263c0a18ec794d93bb9))
+
 ## [@adobe/spacecat-shared-data-access-v3.24.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v3.23.0...@adobe/spacecat-shared-data-access-v3.24.0) (2026-03-19)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-data-access",
-  "version": "3.24.0",
+  "version": "3.26.0",
   "description": "Shared modules of the Spacecat Services - Data Access",
   "type": "module",
   "engines": {

package/src/models/access-grant-log/access-grant-log.collection.js

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import BaseCollection from '../base/base.collection.js';
+
+/**
+ * AccessGrantLogCollection - Collection of immutable audit log entries.
+ * Supports creation and querying only (no update/delete at the app layer).
+ *
+ * @class AccessGrantLogCollection
+ * @extends BaseCollection
+ */
+class AccessGrantLogCollection extends BaseCollection {
+  static COLLECTION_NAME = 'AccessGrantLogCollection';
+}
+
+export default AccessGrantLogCollection;

package/src/models/access-grant-log/access-grant-log.model.js

@@ -0,0 +1,31 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import BaseModel from '../base/base.model.js';
+
+/**
+ * AccessGrantLog - Immutable audit log entry for cross-org delegation grant/revoke actions.
+ * site_id and organization_id are TEXT (not FK) — values survive entity deletion.
+ *
+ * @class AccessGrantLog
+ * @extends BaseModel
+ */
+class AccessGrantLog extends BaseModel {
+  static ENTITY_NAME = 'AccessGrantLog';
+
+  static GRANT_ACTIONS = {
+    GRANT: 'grant',
+    REVOKE: 'revoke',
+  };
+}
+
+export default AccessGrantLog;

package/src/models/access-grant-log/access-grant-log.schema.js

@@ -0,0 +1,62 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { isValidUUID } from '@adobe/spacecat-shared-utils';
+import { Entitlement } from '../entitlement/index.js';
+import SiteImsOrgAccess from '../site-ims-org-access/site-ims-org-access.model.js';
+import SchemaBuilder from '../base/schema.builder.js';
+import AccessGrantLog from './access-grant-log.model.js';
+import AccessGrantLogCollection from './access-grant-log.collection.js';
+
+const PERFORMED_BY_PATTERN = /^(ims:\S+|slack:\S+|system)$/;
+
+const schema = new SchemaBuilder(AccessGrantLog, AccessGrantLogCollection)
+  .allowUpdates(false)
+  .allowRemove(false)
+  // siteId, organizationId, and targetOrganizationId are plain addAttribute (not belongs_to)
+  // because the DB columns are TEXT, not FK. Audit logs must preserve UUIDs after entity deletion.
+  .addAttribute('siteId', {
+    type: 'string',
+    required: true,
+    validate: (v) => isValidUUID(v),
+  })
+  .addAttribute('organizationId', {
+    type: 'string',
+    required: true,
+    validate: (v) => isValidUUID(v),
+  })
+  .addAttribute('targetOrganizationId', {
+    type: 'string',
+    required: true,
+    validate: (v) => isValidUUID(v),
+  })
+  .addAttribute('productCode', {
+    type: Object.values(Entitlement.PRODUCT_CODES),
+    required: true,
+  })
+  .addAttribute('action', {
+    type: Object.values(AccessGrantLog.GRANT_ACTIONS),
+    required: true,
+  })
+  .addAttribute('role', {
+    type: Object.values(SiteImsOrgAccess.DELEGATION_ROLES),
+    required: true,
+  })
+  .addAttribute('performedBy', {
+    type: 'string',
+    required: true,
+    validate: (v) => PERFORMED_BY_PATTERN.test(v),
+  })
+  .addAllIndex(['organizationId'])
+  .addAllIndex(['siteId']);
+
+export default schema.build();

package/src/models/access-grant-log/index.d.ts

@@ -0,0 +1,37 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import type {
+  BaseCollection, BaseModel, EntitlementProductCode,
+} from '../index';
+
+export type AccessGrantAction = 'grant' | 'revoke';
+export type AccessGrantRole = 'collaborator' | 'agency' | 'viewer';
+
+export interface AccessGrantLog extends BaseModel {
+  getSiteId(): string;
+  getOrganizationId(): string;
+  getTargetOrganizationId(): string;
+  getProductCode(): EntitlementProductCode;
+  getAction(): AccessGrantAction;
+  getRole(): AccessGrantRole;
+  getPerformedBy(): string;
+}
+
+export interface AccessGrantLogCollection extends
+    BaseCollection<AccessGrantLog> {
+  allByOrganizationId(organizationId: string): Promise<AccessGrantLog[]>;
+  allBySiteId(siteId: string): Promise<AccessGrantLog[]>;
+
+  findByOrganizationId(organizationId: string): Promise<AccessGrantLog | null>;
+  findBySiteId(siteId: string): Promise<AccessGrantLog | null>;
+}

package/src/models/access-grant-log/index.js

@@ -0,0 +1,15 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+export { default as AccessGrantLog } from './access-grant-log.model.js';
+export { default as AccessGrantLogCollection } from './access-grant-log.collection.js';
+export { default as AccessGrantLogSchema } from './access-grant-log.schema.js';

package/src/models/base/base.collection.js

@@ -585,6 +585,20 @@ class BaseCollection {
     return this.#queryByIndexKeys(keys, { ...options, limit: 1 });
   }
 
+  /**
+   * Converts a raw PostgREST row (snake_case) to a model instance using the same field mapping
+   * pipeline as the internal create/find paths. Intended for use by collections that receive
+   * embedded sub-rows from PostgREST resource embedding (e.g. `sites!fkey(*)`), allowing them
+   * to return proper model instances rather than raw snake_case objects.
+   *
+   * @param {object} row - Raw PostgREST row with snake_case column names.
+   * @returns {object|null} A model instance, or null if the row is empty/invalid.
+   */
+  createInstanceFromRow(row) {
+    if (!isNonEmptyObject(row)) return null;
+    return this.#createInstance(this.#toModelRecord(row));
+  }
+
   async findById(id) {
     guardId(this.idName, id, this.entityName);
     if (this.entity) {

package/src/models/base/base.model.js

@@ -176,6 +176,20 @@ class BaseModel {
               }
 
               return null;
+            })
+            .catch((error) => {
+              // Gracefully skip dependents whose table/column is absent from the PostgREST
+              // schema cache (e.g. when the legacy test DB pre-dates this table). All other
+              // errors are re-thrown so they still surface as removal failures.
+              const msg = error?.cause?.message || error?.message || '';
+              if (
+                msg.includes('Could not find the')
+                && (msg.includes('table') || msg.includes('column'))
+                && msg.includes('schema cache')
+              ) {
+                return null;
+              }
+              throw error;
             }),
         );
       });

package/src/models/base/entity.registry.js

@@ -48,6 +48,8 @@ import PageCitabilityCollection from '../page-citability/page-citability.collect
 import PlgOnboardingCollection from '../plg-onboarding/plg-onboarding.collection.js';
 import SentimentGuidelineCollection from '../sentiment-guideline/sentiment-guideline.collection.js';
 import SentimentTopicCollection from '../sentiment-topic/sentiment-topic.collection.js';
+import AccessGrantLogCollection from '../access-grant-log/access-grant-log.collection.js';
+import SiteImsOrgAccessCollection from '../site-ims-org-access/site-ims-org-access.collection.js';
 
 import ApiKeySchema from '../api-key/api-key.schema.js';
 import AsyncJobSchema from '../async-job/async-job.schema.js';
@@ -83,6 +85,8 @@ import PageCitabilitySchema from '../page-citability/page-citability.schema.js';
 import PlgOnboardingSchema from '../plg-onboarding/plg-onboarding.schema.js';
 import SentimentGuidelineSchema from '../sentiment-guideline/sentiment-guideline.schema.js';
 import SentimentTopicSchema from '../sentiment-topic/sentiment-topic.schema.js';
+import AccessGrantLogSchema from '../access-grant-log/access-grant-log.schema.js';
+import SiteImsOrgAccessSchema from '../site-ims-org-access/site-ims-org-access.schema.js';
 
 /**
  * EntityRegistry - A registry class responsible for managing entities, their schema and collection.
@@ -213,6 +217,8 @@ EntityRegistry.registerEntity(PageCitabilitySchema, PageCitabilityCollection);
 EntityRegistry.registerEntity(PlgOnboardingSchema, PlgOnboardingCollection);
 EntityRegistry.registerEntity(SentimentGuidelineSchema, SentimentGuidelineCollection);
 EntityRegistry.registerEntity(SentimentTopicSchema, SentimentTopicCollection);
+EntityRegistry.registerEntity(AccessGrantLogSchema, AccessGrantLogCollection);
+EntityRegistry.registerEntity(SiteImsOrgAccessSchema, SiteImsOrgAccessCollection);
 EntityRegistry.defaultEntities = { ...EntityRegistry.entities };
 
 export default EntityRegistry;

package/src/models/index.d.ts

@@ -10,6 +10,7 @@
  * governing permissions and limitations under the License.
  */
 
+export type * from './access-grant-log';
 export type * from './api-key';
 export type * from './async-job';
 export type * from './audit';
@@ -39,6 +40,7 @@ export type * from './sentiment-topic';
 export type * from './site';
 export type * from './site-candidate';
 export type * from './site-enrollment';
+export type * from './site-ims-org-access';
 export type * from './site-top-form';
 export type * from './site-top-page';
 export type * from './suggestion';

package/src/models/index.js

@@ -10,6 +10,7 @@
  * governing permissions and limitations under the License.
  */
 
+export * from './access-grant-log/index.js';
 export * from './api-key/index.js';
 export * from './async-job/index.js';
 export * from './audit/index.js';
@@ -32,6 +33,7 @@ export * from './scrape-job/index.js';
 export * from './scrape-url/index.js';
 export * from './site-candidate/index.js';
 export * from './site-enrollment/index.js';
+export * from './site-ims-org-access/index.js';
 export * from './site-top-form/index.js';
 export * from './site-top-page/index.js';
 export * from './site/index.js';

package/src/models/sentiment-topic/index.d.ts

@@ -16,18 +16,10 @@ import type { BaseCollection, BaseModel, Site } from '../index';
  * SentimentTopic entity representing a topic for sentiment analysis.
  * Composite primary key: siteId (PK) + topicId (SK)
  */
-export interface SentimentTopicUrl {
-  url: string;
-  timesCited: number;
-  category?: string;
-  subPrompts?: string[];
-}
-
 export interface SentimentTopic extends BaseModel {
   getTopicId(): string;
   getName(): string;
   getDescription(): string | undefined;
-  getUrls(): SentimentTopicUrl[];
   getEnabled(): boolean;
   getCreatedAt(): string;
   getCreatedBy(): string;
@@ -38,7 +30,6 @@ export interface SentimentTopic extends BaseModel {
 
   setName(name: string): SentimentTopic;
   setDescription(description: string): SentimentTopic;
-  setUrls(urls: SentimentTopicUrl[]): SentimentTopic;
   setEnabled(enabled: boolean): SentimentTopic;
   setUpdatedBy(updatedBy: string): SentimentTopic;
 }

package/src/models/sentiment-topic/sentiment-topic.schema.js

@@ -55,25 +55,6 @@ const schema = new SchemaBuilder(SentimentTopic, SentimentTopicCollection)
     type: 'string',
     required: false,
   })
-  .addAttribute('urls', {
-    type: 'list',
-    required: false,
-    default: [],
-    items: {
-      type: 'map',
-      properties: {
-        url: { type: 'string', required: true },
-        timesCited: { type: 'number', required: true },
-        category: { type: 'string', required: false },
-        subPrompts: {
-          type: 'list',
-          items: { type: 'string' },
-          required: false,
-          default: [],
-        },
-      },
-    },
-  })
   .addAttribute('enabled', {
     type: 'boolean',
     required: true,

package/src/models/site/site.schema.js

@@ -43,6 +43,11 @@ const schema = new SchemaBuilder(Site, SiteCollection)
   .addReference('has_many', 'Opportunities')
   .addReference('has_many', 'SiteCandidates')
   .addReference('has_many', 'SiteEnrollments')
+  // TODO(Phase 2 audit gap): removeDependents silently removes all SiteImsOrgAccess records on
+  // site deletion without writing AccessGrantLog 'revoke' entries. Anyone auditing "why did
+  // agency X lose access to site Y" will find nothing in the log. Add a model-level pre-remove
+  // hook that writes revoke audit entries before this ships to production.
+  .addReference('has_many', 'SiteImsOrgAccesses', [], { removeDependents: true })
   .addReference('has_many', 'SiteTopForms')
   .addReference('has_many', 'SiteTopPages')
   .addReference('has_many', 'TrialUserActivities')

package/src/models/site-ims-org-access/index.d.ts

@@ -0,0 +1,64 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import type {
+  BaseCollection, BaseModel, EntitlementProductCode, Organization, Site,
+} from '../index';
+
+export type SiteImsOrgAccessRole = 'collaborator' | 'agency' | 'viewer';
+
+export interface SiteImsOrgAccess extends BaseModel {
+  getSite(): Promise<Site>;
+  getOrganization(): Promise<Organization>;
+  getSiteId(): string;
+  /** organizationId is the delegate org receiving access (read-only, part of grant identity). */
+  getOrganizationId(): string;
+  /** targetOrganizationId is the site-owning org (read-only, part of grant identity). */
+  getTargetOrganizationId(): string;
+  /** productCode is read-only; changing scope requires a new grant. */
+  getProductCode(): EntitlementProductCode;
+  getRole(): SiteImsOrgAccessRole;
+  getGrantedBy(): string | null;
+  getExpiresAt(): string | null;
+  setRole(role: SiteImsOrgAccessRole): SiteImsOrgAccess;
+  setGrantedBy(grantedBy: string): SiteImsOrgAccess;
+  setExpiresAt(expiresAt: string): SiteImsOrgAccess;
+}
+
+export interface SiteImsOrgAccessGrantWithTarget {
+  grant: SiteImsOrgAccess;
+  targetOrganization: {
+    id: string;
+    imsOrgId: string;
+  };
+}
+
+export interface SiteImsOrgAccessGrantWithSite {
+  grant: SiteImsOrgAccess;
+  /** Site model instance. Null only if the FK is broken (should not occur given ON DELETE CASCADE). */
+  site: Site | null;
+}
+
+export interface SiteImsOrgAccessCollection extends
+    BaseCollection<SiteImsOrgAccess> {
+  allBySiteId(siteId: string): Promise<SiteImsOrgAccess[]>;
+  allByOrganizationId(organizationId: string): Promise<SiteImsOrgAccess[]>;
+  allByTargetOrganizationId(targetOrganizationId: string): Promise<SiteImsOrgAccess[]>;
+  allByOrganizationIdWithTargetOrganization(organizationId: string): Promise<SiteImsOrgAccessGrantWithTarget[]>;
+  allByOrganizationIdsWithTargetOrganization(organizationIds: string[]): Promise<SiteImsOrgAccessGrantWithTarget[]>;
+  allByOrganizationIdWithSites(organizationId: string): Promise<SiteImsOrgAccessGrantWithSite[]>;
+
+  findBySiteId(siteId: string): Promise<SiteImsOrgAccess | null>;
+  findByOrganizationId(organizationId: string): Promise<SiteImsOrgAccess | null>;
+  findByTargetOrganizationId(targetOrganizationId: string): Promise<SiteImsOrgAccess | null>;
+  findBySiteIdAndOrganizationIdAndProductCode(siteId: string, organizationId: string, productCode: EntitlementProductCode): Promise<SiteImsOrgAccess | null>;
+}

package/src/models/site-ims-org-access/index.js

@@ -0,0 +1,15 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+export { default as SiteImsOrgAccess } from './site-ims-org-access.model.js';
+export { default as SiteImsOrgAccessCollection } from './site-ims-org-access.collection.js';
+export { default as SiteImsOrgAccessSchema } from './site-ims-org-access.schema.js';

package/src/models/site-ims-org-access/site-ims-org-access.collection.js

@@ -0,0 +1,264 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import BaseCollection from '../base/base.collection.js';
+import DataAccessError from '../../errors/data-access.error.js';
+import { DEFAULT_PAGE_SIZE } from '../../util/postgrest.utils.js';
+
+/**
+ * SiteImsOrgAccessCollection - Collection of cross-org delegation grants.
+ * Provides idempotent create and the 50-delegate-per-site limit.
+ *
+ * @class SiteImsOrgAccessCollection
+ * @extends BaseCollection
+ */
+class SiteImsOrgAccessCollection extends BaseCollection {
+  static COLLECTION_NAME = 'SiteImsOrgAccessCollection';
+
+  static MAX_DELEGATES_PER_SITE = 50;
+
+  /**
+   * Idempotent create: if a grant already exists for (siteId, organizationId, productCode),
+   * return the existing record. Otherwise, enforce the 50-delegate-per-site limit and create.
+   * Follows the SiteEnrollment pattern (site-enrollment.collection.js:25-32).
+   *
+   * Note: the findByIndexKeys + allBySiteId + super.create sequence is not atomic. Concurrent
+   * requests can both pass the idempotency check (creating duplicates) or both pass the limit
+   * check (exceeding it). A DB-level unique constraint on (siteId, organizationId, productCode)
+   * is the authoritative guard against duplicates.
+   */
+  async create(item, options = {}) {
+    if (item?.organizationId && item?.targetOrganizationId
+      && item.organizationId === item.targetOrganizationId) {
+      const message = 'Cannot create self-delegation: organizationId and targetOrganizationId must differ';
+      this.log.warn(`[SiteImsOrgAccess] Self-delegation rejected: org=${item.organizationId}`);
+      const err = new DataAccessError(message);
+      err.status = 409;
+      throw err;
+    }
+
+    if (item?.siteId && item?.organizationId && item?.productCode) {
+      const existing = await this.findByIndexKeys({
+        siteId: item.siteId,
+        organizationId: item.organizationId,
+        productCode: item.productCode,
+      });
+      if (existing) {
+        this.log.info(`[SiteImsOrgAccess] Idempotent create: returning existing grant for site=${item.siteId} org=${item.organizationId} product=${item.productCode}`);
+        return existing;
+      }
+    }
+
+    // Enforce 50-active-delegate-per-site limit; expired grants do not count.
+    if (item?.siteId) {
+      const allGrants = await this.allBySiteId(item.siteId);
+      const activeGrants = allGrants.filter(
+        (g) => !g.getExpiresAt() || new Date(g.getExpiresAt()) > new Date(),
+      );
+      if (activeGrants.length >= SiteImsOrgAccessCollection.MAX_DELEGATES_PER_SITE) {
+        const message = `Cannot add delegate: site already has ${activeGrants.length}/${SiteImsOrgAccessCollection.MAX_DELEGATES_PER_SITE} active delegates`;
+        this.log.warn(`[SiteImsOrgAccess] Delegate limit reached for site=${item.siteId}`);
+        const err = new DataAccessError(message);
+        err.status = 409;
+        throw err;
+      }
+    }
+
+    const created = await super.create(item, options);
+    this.log.info(`[SiteImsOrgAccess] New grant created: id=${created.getId()} site=${item.siteId} org=${item.organizationId} product=${item.productCode}`);
+    return created;
+  }
+
+  /**
+   * Shared pagination loop for PostgREST embedding queries. Fetches all pages and maps
+   * each row using the provided mapper function.
+   *
+   * @param {object} query - PostgREST query builder (result of .from(...).select(...))
+   * @param {Function} mapRow - Maps a raw row to the desired return shape
+   * @param {string} errorMessage - Used for logging and DataAccessError message
+   * @returns {Promise<Array>}
+   * @private
+   */
+  async #fetchPaginatedGrants(query, mapRow, errorMessage) {
+    const allResults = [];
+    let offset = 0;
+    let keepGoing = true;
+    const orderedQuery = query.order('id');
+
+    while (keepGoing) {
+      // eslint-disable-next-line no-await-in-loop
+      const { data, error } = await orderedQuery.range(offset, offset + DEFAULT_PAGE_SIZE - 1);
+
+      if (error) {
+        this.log.error(`[SiteImsOrgAccess] ${errorMessage} - ${error.message}`, error);
+        throw new DataAccessError(
+          errorMessage,
+          { entityName: 'SiteImsOrgAccess', tableName: 'site_ims_org_accesses' },
+          error,
+        );
+      }
+
+      if (!data || data.length === 0) {
+        keepGoing = false;
+      } else {
+        allResults.push(...data);
+        keepGoing = data.length >= DEFAULT_PAGE_SIZE;
+        offset += DEFAULT_PAGE_SIZE;
+      }
+    }
+
+    return allResults.map(mapRow);
+  }
+
+  /**
+   * @param {object} query - PostgREST query builder
+   * @returns {Promise<Array<{grant: SiteImsOrgAccess, targetOrganization: object}>>}
+   * @private
+   */
+  async #fetchGrantsWithTargetOrg(query) {
+    return this.#fetchPaginatedGrants(
+      query,
+      (row) => ({
+        grant: this.createInstanceFromRow(row),
+        targetOrganization: { id: row.organizations.id, imsOrgId: row.organizations.ims_org_id },
+      }),
+      'Failed to query grants with target organization',
+    );
+  }
+
+  /**
+   * Returns all grants for the given delegate organization with the target organization's
+   * id and imsOrgId embedded via PostgREST resource embedding (INNER JOIN). This avoids
+   * a separate batch query to resolve target org IMS identifiers.
+   *
+   * Returns plain objects, not model instances. Access properties directly
+   * (e.g., `entry.grant.productCode`, `entry.targetOrganization.imsOrgId`).
+   *
+   * @param {string} organizationId - UUID of the delegate organization.
+   * @returns {Promise<Array<{
+   *   grant: {id: string, siteId: string, organizationId: string,
+   *     targetOrganizationId: string, productCode: string, role: string,
+   *     grantedBy: string|null, expiresAt: string|null},
+   *   targetOrganization: {id: string, imsOrgId: string}
+   * }>>}
+   */
+  async allByOrganizationIdWithTargetOrganization(organizationId) {
+    if (!organizationId) {
+      throw new DataAccessError('organizationId is required', { entityName: 'SiteImsOrgAccess', tableName: 'site_ims_org_accesses' });
+    }
+    // eslint-disable-next-line max-len
+    const select = 'id, site_id, organization_id, target_organization_id, product_code, role, granted_by, expires_at, organizations!site_ims_org_accesses_target_organization_id_fkey(id, ims_org_id)';
+    return this.#fetchGrantsWithTargetOrg(
+      this.postgrestService.from('site_ims_org_accesses').select(select).eq('organization_id', organizationId),
+    );
+  }
+
+  /**
+   * Bulk variant of allByOrganizationIdWithTargetOrganization. Fetches grants for multiple
+   * delegate organizations in a single PostgREST IN query with target org embedding.
+   * Returns an empty array when organizationIds is empty.
+   *
+   * @param {string[]} organizationIds - UUIDs of the delegate organizations.
+   * @returns {Promise<Array<{
+   *   grant: {id: string, siteId: string, organizationId: string,
+   *     targetOrganizationId: string, productCode: string, role: string,
+   *     grantedBy: string|null, expiresAt: string|null},
+   *   targetOrganization: {id: string, imsOrgId: string}
+   * }>>}
+   */
+  async allByOrganizationIdsWithTargetOrganization(organizationIds) {
+    if (!organizationIds || organizationIds.length === 0) {
+      return [];
+    }
+    if (organizationIds.length > SiteImsOrgAccessCollection.MAX_DELEGATES_PER_SITE) {
+      throw new DataAccessError(
+        `allByOrganizationIdsWithTargetOrganization: organizationIds array exceeds maximum of ${SiteImsOrgAccessCollection.MAX_DELEGATES_PER_SITE}`,
+        { entityName: 'SiteImsOrgAccess', tableName: 'site_ims_org_accesses' },
+      );
+    }
+    // eslint-disable-next-line max-len
+    const select = 'id, site_id, organization_id, target_organization_id, product_code, role, granted_by, expires_at, organizations!site_ims_org_accesses_target_organization_id_fkey(id, ims_org_id)';
+    return this.#fetchGrantsWithTargetOrg(
+      this.postgrestService.from('site_ims_org_accesses').select(select).in('organization_id', organizationIds),
+    );
+  }
+
+  /**
+   * Finds a single grant by the compound key (siteId, organizationId, productCode).
+   * Used by hasAccess() in the api-service to verify a grant still exists (Path A revocation
+   * check) or to perform a direct DB lookup when the JWT list was truncated (Path B).
+   *
+   * Returns a model instance so callers can use getExpiresAt(), getRole(), etc.
+   * Returns null when no matching grant exists.
+   *
+   * @param {string} siteId - UUID of the site.
+   * @param {string} organizationId - UUID of the delegate organization.
+   * @param {string} productCode - Product code (e.g. 'LLMO', 'ASO').
+   * @returns {Promise<SiteImsOrgAccess|null>}
+   */
+  async findBySiteIdAndOrganizationIdAndProductCode(siteId, organizationId, productCode) {
+    if (!siteId || !organizationId || !productCode) {
+      throw new DataAccessError(
+        'siteId, organizationId and productCode are required',
+        { entityName: 'SiteImsOrgAccess', tableName: 'site_ims_org_accesses' },
+      );
+    }
+    return this.findByIndexKeys({ siteId, organizationId, productCode });
+  }
+
+  /**
+   * Returns all grants for the given delegate organization with the full site row embedded
+   * via PostgREST resource embedding (INNER JOIN on site_id FK). This is a single round-trip
+   * query — no N+1 — suitable for populating the site dropdown for delegated users.
+   *
+   * Returns plain objects, not model instances. The `site` field contains the raw PostgREST
+   * row for the joined site (snake_case column names). It is null only when the FK is broken,
+   * which should not occur given ON DELETE CASCADE on site_id.
+   *
+   * @param {string} organizationId - UUID of the delegate organization.
+   * @returns {Promise<Array<{
+   *   grant: {id: string, siteId: string, organizationId: string,
+   *     targetOrganizationId: string, productCode: string, role: string,
+   *     grantedBy: string|null, expiresAt: string|null},
+   *   site: object|null
+   * }>>}
+   */
+  async allByOrganizationIdWithSites(organizationId) {
+    if (!organizationId) {
+      throw new DataAccessError('organizationId is required', { entityName: 'SiteImsOrgAccess', tableName: 'site_ims_org_accesses' });
+    }
+    // eslint-disable-next-line max-len
+    const select = 'id, site_id, organization_id, target_organization_id, product_code, role, granted_by, expires_at, sites!site_ims_org_accesses_site_id_fkey(*)';
+    return this.#fetchGrantsWithSite(
+      this.postgrestService.from('site_ims_org_accesses').select(select).eq('organization_id', organizationId),
+    );
+  }
+
+  /**
+   * @param {object} query - PostgREST query builder
+   * @returns {Promise<Array<{grant: SiteImsOrgAccess, site: Site|null}>>}
+   * @private
+   */
+  async #fetchGrantsWithSite(query) {
+    const siteCollection = this.entityRegistry.getCollection('SiteCollection');
+    return this.#fetchPaginatedGrants(
+      query,
+      (row) => ({
+        grant: this.createInstanceFromRow(row),
+        site: row.sites ? siteCollection.createInstanceFromRow(row.sites) : null,
+      }),
+      'Failed to query grants with site',
+    );
+  }
+}
+
+export default SiteImsOrgAccessCollection;

package/src/models/site-ims-org-access/site-ims-org-access.model.js

@@ -0,0 +1,32 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import BaseModel from '../base/base.model.js';
+
+/**
+ * SiteImsOrgAccess - Maps delegate orgs to sites they can access, per product.
+ * Part of the cross-org delegation feature (Option 2a Phase 1).
+ *
+ * @class SiteImsOrgAccess
+ * @extends BaseModel
+ */
+class SiteImsOrgAccess extends BaseModel {
+  static ENTITY_NAME = 'SiteImsOrgAccess';
+
+  static DELEGATION_ROLES = {
+    COLLABORATOR: 'collaborator',
+    AGENCY: 'agency',
+    VIEWER: 'viewer',
+  };
+}
+
+export default SiteImsOrgAccess;

package/src/models/site-ims-org-access/site-ims-org-access.schema.js

@@ -0,0 +1,63 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { isIsoDate, isValidUUID } from '@adobe/spacecat-shared-utils';
+import { Entitlement } from '../entitlement/index.js';
+import SchemaBuilder from '../base/schema.builder.js';
+import SiteImsOrgAccess from './site-ims-org-access.model.js';
+import SiteImsOrgAccessCollection from './site-ims-org-access.collection.js';
+
+const GRANTED_BY_PATTERN = /^(ims:\S+|slack:\S+|system)$/;
+
+const schema = new SchemaBuilder(SiteImsOrgAccess, SiteImsOrgAccessCollection)
+  .addReference('belongs_to', 'Site')
+  .addReference('belongs_to', 'Organization') // the agency/delegate org receiving access
+  // targetOrganizationId is addAttribute (not belongs_to) because SchemaBuilder's
+  // belongs_to uses the referenced model name as the FK column prefix (organization_id).
+  // We already have belongs_to Organization for the delegate org, so a second belongs_to
+  // would conflict. addAttribute with UUID validation achieves the same FK semantics
+  // without the naming collision. readOnly: true prevents the setter from being generated
+  // since the target org is part of the grant's identity — a different target means a
+  // different grant.
+  .addAttribute('targetOrganizationId', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+    validate: (v) => isValidUUID(v),
+  })
+  // organizationId (delegate org, from belongs_to) and siteId are also part of the grant's
+  // identity and are readOnly by virtue of their belongs_to FK nature.
+  .addAttribute('productCode', {
+    type: Object.values(Entitlement.PRODUCT_CODES),
+    required: true,
+    readOnly: true,
+  })
+  .addAttribute('role', {
+    type: Object.values(SiteImsOrgAccess.DELEGATION_ROLES),
+    required: true,
+    default: SiteImsOrgAccess.DELEGATION_ROLES.AGENCY,
+  })
+  .addAttribute('grantedBy', {
+    type: 'string',
+    required: false,
+    validate: (v) => !v || GRANTED_BY_PATTERN.test(v),
+  })
+  .addAttribute('expiresAt', {
+    type: 'string',
+    required: false,
+    validate: (v) => !v || isIsoDate(v),
+  })
+  .addAllIndex(['organizationId'])
+  // Index for "show all delegations granted to org Z across all sites" admin query
+  .addAllIndex(['targetOrganizationId']);
+
+export default schema.build();