feat: add access control helpers for cross-org delegation (Option 2a)

[ekremney]

Summary

Follow-on to #1448. Adds the spacecat-shared primitives required to implement the access-check
decision flow (Path A / Path B) and the delegated-site dropdown in the api-service.

AuthInfo.isDelegatedTenantsComplete() — spacecat-shared-http-utils

Returns true when the delegated_tenants_complete JWT claim is absent or true; false when
it is explicitly false.

hasAccess() in the api-service uses this to branch between two resolution paths:

Path	Condition	Behaviour
A	complete = true (≤ 20 grants, typical agency)	JWT gate: if target org not in delegated_tenants list, deny with zero DB calls. DB only hit when JWT confirms a match (revocation check).
B	complete = false (> 20 grants, e.g. internal sales)	Skip JWT gate. Read sourceOrganizationId from delegated_tenants[0] and go DB-direct every request.

Defaults to true when the claim is absent — backward-compat with tokens minted before the claim
was added (all such tokens had ≤ 20 grants).

BaseCollection.createInstanceFromRow(row) — spacecat-shared-data-access

Public wrapper around the existing private #toModelRecord + #createInstance pipeline.
Enables other collections to convert an embedded PostgREST sub-row (snake_case columns) into a
proper model instance, reusing the full field-mapping logic without duplication.

SiteImsOrgAccessCollection additions — spacecat-shared-data-access

findBySiteIdAndOrganizationIdAndProductCode(siteId, organizationId, productCode)
Thin public wrapper around findByIndexKeys. Used by hasAccess() for the DB revocation check
(Path A) and the DB-direct lookup (Path B).

allByOrganizationIdWithSites(organizationId)
Single-round-trip PostgREST embedding query (sites!site_ims_org_accesses_site_id_fkey(*)).
Returns { grant: SiteImsOrgAccess, site: Site | null } pairs — both fields are proper model
instances with getters. Used by the api-service getSitesForOrganization endpoint to merge
delegated sites into the org's site list with no N+1.

All embedding methods now return SiteImsOrgAccess model instances for grant
Previously grant was a plain camelCase object. Now allByOrganizationIdWithTargetOrganization,
allByOrganizationIdsWithTargetOrganization, and allByOrganizationIdWithSites all return a
proper SiteImsOrgAccess model instance as grant. Callers use entry.grant.getOrganizationId(),
entry.grant.getExpiresAt(), etc. — consistent getters everywhere.

The now-unnecessary static #toGrant(row) helper was removed.

How these will be used in the api-service (next PR)

hasAccess() in access-control-util.js:

// Path A (complete = true)
const delegatedTenant = authInfo.getDelegatedTenant(imsOrgId, productCode);
if (!delegatedTenant) return false; // zero DB calls
const grant = await this.SiteImsOrgAccess
  .findBySiteIdAndOrganizationIdAndProductCode(siteId, delegatedTenant.sourceOrganizationId, productCode);
if (grant && (!grant.getExpiresAt() || new Date(grant.getExpiresAt()) > new Date())) {
  hasOrgAccess = true; isDelegatedAccess = true;
}

// Path B (complete = false)
const sourceOrganizationId = authInfo.getDelegatedTenants()[0]?.sourceOrganizationId;
const grant = await this.SiteImsOrgAccess
  .findBySiteIdAndOrganizationIdAndProductCode(siteId, sourceOrganizationId, productCode);

getSitesForOrganization in organizations.js:

const delegatedEntries = await SiteImsOrgAccess.allByOrganizationIdWithSites(organizationId);
for (const entry of delegatedEntries) {
  if (entry.grant.getProductCode() !== productCode) continue;
  if (entry.grant.getExpiresAt() && new Date(entry.grant.getExpiresAt()) <= now) continue;
  if (entry.site && !ownSiteIds.has(entry.site.getId())) sites.push(entry.site);
}

Test plan

• AuthInfo.isDelegatedTenantsComplete() — 5 unit tests
• SiteImsOrgAccessCollection — 33 unit tests (all embedding methods use getter assertions)
• IT tests — 13 passing (all embedding methods verified against live PostgREST DB)

Related

• Design doc / amendment PR: adobe/spacecat-auth-service#503
• Initial entity models PR: feat: cross-org delegation entity models and AuthInfo extensions #1448

🤖 Generated with Claude Code

[github-actions]

This PR will trigger a minor release when merged.

[ekremney]

@solaris007 this contains a bunch of helpers for the feature I will implement in api-service side. Due to time constraints, I will need to merge this. Please review, but I will address the reviews retroactively in a separate PR.

[solaris007]

🎉 This PR is included in version @adobe/spacecat-shared-data-access-v3.26.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[solaris007]

🎉 This PR is included in version @adobe/spacecat-shared-http-utils-v1.24.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀