piper-utils 1.1.65 → 1.1.67

package/src/audit/audit.test.js

@@ -0,0 +1,313 @@
+import {
+    attachAudit,
+    auditModels,
+    bindAuditRequest,
+    decrementWithAudit,
+    getAuditFilter,
+    getAuditModel,
+    incrementWithAudit,
+    modelOptions
+} from './audit.js';
+
+const buildEvent = ({ uid = '42', email = 'kevin@test.com', auditEnabled = true, businessIds = { '1': 'A' } } = {}) => ({
+    requestContext: {
+        authorizer: {
+            claims: {
+                'custom:UID': uid,
+                'email': email,
+                'custom:SET': JSON.stringify({ auditEnabled }),
+                'custom:AR': JSON.stringify({ businessIds })
+            }
+        }
+    }
+});
+
+const resetState = () => {
+    Object.keys(auditModels).forEach((k) => delete auditModels[k]);
+    Object.keys(modelOptions).forEach((k) => delete modelOptions[k]);
+};
+
+describe('audit', () => {
+    describe('bindAuditRequest', () => {
+        it('binds user from JWT claims and businessId from arg', () => {
+            resetState();
+            const Model = { name: 'Customer' };
+            const event = buildEvent({ uid: '7', email: 'kevin@test.com', auditEnabled: true });
+
+            bindAuditRequest(event, 'BIZ-1', [Model]);
+
+            expect(modelOptions['Customer'].user.username).toEqual('kevin@test.com');
+            expect(modelOptions['Customer'].user.id).toEqual(7);
+            expect(modelOptions['Customer'].businessId).toEqual('BIZ-1');
+            expect(modelOptions['Customer'].auditEnabled).toEqual(true);
+        });
+
+        it('reads auditEnabled=false from custom:SET claim', () => {
+            resetState();
+            const Model = { name: 'Customer' };
+            const event = buildEvent({ auditEnabled: false });
+
+            bindAuditRequest(event, 'BIZ-1', [Model]);
+
+            expect(modelOptions['Customer'].auditEnabled).toEqual(false);
+        });
+
+        it('binds multiple models in one call', () => {
+            resetState();
+            const A = { name: 'ModelA' };
+            const B = { name: 'ModelB' };
+
+            bindAuditRequest(buildEvent(), 'BIZ-1', [A, B]);
+
+            expect(modelOptions['ModelA']).toBeDefined();
+            expect(modelOptions['ModelB']).toBeDefined();
+        });
+    });
+
+    describe('attachAudit', () => {
+        it('defines a <Name>Audit model and wires four hooks', async () => {
+            resetState();
+            const auditModel = {
+                belongsTo: jasmine.createSpy('belongsTo'),
+                sync: jasmine.createSpy('sync').and.resolveTo()
+            };
+            const Model = {
+                name: 'Customer',
+                addHook: jasmine.createSpy('addHook'),
+                sequelize: {
+                    define: jasmine.createSpy('define').and.returnValue(auditModel),
+                    Sequelize: { STRING: 'STRING_TYPE' }
+                }
+            };
+
+            await attachAudit(Model);
+
+            expect(Model.sequelize.define).toHaveBeenCalled();
+            const [name, schema, opts] = Model.sequelize.define.calls.mostRecent().args;
+            expect(name).toEqual('CustomerAudit');
+            expect(schema.changedByUser.allowNull).toEqual(false);
+            expect(schema.businessId.allowNull).toEqual(false);
+            expect(opts).toEqual({ updatedAt: false, freezeTableName: true });
+
+            expect(auditModel.belongsTo).toHaveBeenCalledWith(Model, jasmine.objectContaining({ onDelete: 'SET NULL' }));
+            expect(Model.addHook).toHaveBeenCalledWith('afterCreate', jasmine.any(Function));
+            expect(Model.addHook).toHaveBeenCalledWith('afterUpsert', jasmine.any(Function));
+            expect(Model.addHook).toHaveBeenCalledWith('afterUpdate', jasmine.any(Function));
+            expect(Model.addHook).toHaveBeenCalledWith('afterDestroy', jasmine.any(Function));
+            expect(auditModel.sync).toHaveBeenCalled();
+        });
+
+        it('is idempotent — second call is a no-op', async () => {
+            resetState();
+            const Model = {
+                name: 'Customer',
+                addHook: jasmine.createSpy('addHook'),
+                sequelize: {
+                    define: jasmine.createSpy('define').and.returnValue({
+                        belongsTo: () => {},
+                        sync: () => Promise.resolve()
+                    }),
+                    Sequelize: { STRING: 'STRING_TYPE' }
+                }
+            };
+
+            await attachAudit(Model);
+            await attachAudit(Model);
+
+            expect(Model.sequelize.define).toHaveBeenCalledTimes(1);
+        });
+    });
+
+    describe('audit hook (auditMe via attachAudit)', () => {
+        const buildModel = (name) => {
+            const definedAudit = { belongsTo: () => {}, sync: () => Promise.resolve() };
+            return {
+                name,
+                addHook: jasmine.createSpy('addHook'),
+                sequelize: {
+                    define: jasmine.createSpy('define').and.returnValue(definedAudit),
+                    Sequelize: { STRING: 'STRING_TYPE' }
+                }
+            };
+        };
+        const captureHook = async (Model) => {
+            await attachAudit(Model);
+            const auditModel = auditModels[Model.name];
+            auditModel.create = jasmine.createSpy('create').and.resolveTo();
+            const hook = Model.addHook.calls.allArgs().find(([h]) => h === 'afterCreate')[1];
+            return { hook, auditModel };
+        };
+
+        it('writes changedByUser from bound user, no ChangedByUserId field', async () => {
+            resetState();
+            const Model = buildModel('Widget');
+            const { hook, auditModel } = await captureHook(Model);
+            modelOptions['Widget'] = {
+                user: { username: 'kevin@test.com', id: 7 },
+                businessId: 'BIZ-1',
+                auditEnabled: true
+            };
+
+            await hook(
+                { _changed: ['name'], _previousDataValues: { name: 'old' }, dataValues: { id: 99, name: 'new' } },
+                { type: 'INITIAL' }
+            );
+
+            const writtenRow = auditModel.create.calls.mostRecent().args[0];
+            expect(writtenRow.changedByUser).toEqual('kevin@test.com');
+            expect(writtenRow.businessId).toEqual('BIZ-1');
+            expect(writtenRow.WidgetId).toEqual(99);
+            expect(writtenRow.field).toEqual('name');
+            expect(writtenRow.valueOld).toEqual('old');
+            expect(writtenRow.valueNew).toEqual('new');
+            expect(writtenRow.ChangedByUserId).toBeUndefined();
+        });
+
+        it('skips audit when auditEnabled is false for that model', async () => {
+            resetState();
+            const Model = buildModel('Widget');
+            const { hook, auditModel } = await captureHook(Model);
+            modelOptions['Widget'] = {
+                user: { username: 'kevin@test.com', id: 7 },
+                businessId: 'BIZ-1',
+                auditEnabled: false
+            };
+
+            await hook(
+                { _changed: ['name'], _previousDataValues: { name: 'old' }, dataValues: { id: 99, name: 'new' } },
+                { type: 'INITIAL' }
+            );
+
+            expect(auditModel.create).not.toHaveBeenCalled();
+        });
+
+        it('skips audit when no per-request bind exists for the model', async () => {
+            resetState();
+            const Model = buildModel('Widget');
+            const { hook, auditModel } = await captureHook(Model);
+
+            await hook(
+                { _changed: ['name'], _previousDataValues: { name: 'old' }, dataValues: { id: 99, name: 'new' } },
+                { type: 'INITIAL' }
+            );
+
+            expect(auditModel.create).not.toHaveBeenCalled();
+        });
+
+        it('per-model isolation — binding model A does not enable audit for model B', async () => {
+            resetState();
+            const ModelA = buildModel('A');
+            const ModelB = buildModel('B');
+            const { hook: hookA, auditModel: auditA } = await captureHook(ModelA);
+            const { hook: hookB, auditModel: auditB } = await captureHook(ModelB);
+            modelOptions['A'] = { user: { username: 'k', id: 1 }, businessId: 'B1', auditEnabled: true };
+
+            await hookA({ _changed: ['x'], _previousDataValues: { x: '1' }, dataValues: { id: 1, x: '2' } }, {});
+            await hookB({ _changed: ['x'], _previousDataValues: { x: '1' }, dataValues: { id: 1, x: '2' } }, {});
+
+            expect(auditA.create).toHaveBeenCalled();
+            expect(auditB.create).not.toHaveBeenCalled();
+        });
+
+        it('masks sensitive fields inside array values', async () => {
+            resetState();
+            const Model = buildModel('Widget');
+            const { hook, auditModel } = await captureHook(Model);
+            modelOptions['Widget'] = { user: { username: 'k', id: 1 }, businessId: 'B1', auditEnabled: true };
+
+            await hook(
+                {
+                    _changed: ['tokens'],
+                    _previousDataValues: { tokens: [{ token: 'secret-old' }] },
+                    dataValues: { id: 1, tokens: [{ token: 'secret-new' }] }
+                },
+                {}
+            );
+
+            const row = auditModel.create.calls.mostRecent().args[0];
+            expect(row.valueOld).not.toContain('secret-old');
+            expect(row.valueNew).not.toContain('secret-new');
+            expect(row.valueOld).toContain('***************');
+            expect(row.valueNew).toContain('***************');
+        });
+
+        it('passes the transaction through to auditModel.create when present', async () => {
+            resetState();
+            const Model = buildModel('Widget');
+            const { hook, auditModel } = await captureHook(Model);
+            modelOptions['Widget'] = { user: { username: 'k', id: 1 }, businessId: 'B1', auditEnabled: true };
+
+            await hook(
+                { _changed: ['name'], _previousDataValues: { name: 'a' }, dataValues: { id: 1, name: 'b' } },
+                { transaction: 'TX-1' }
+            );
+
+            expect(auditModel.create.calls.mostRecent().args[1]).toEqual({ transaction: 'TX-1' });
+        });
+    });
+
+    describe('incrementWithAudit / decrementWithAudit', () => {
+        it('increments and writes an audit row using bound context', async () => {
+            resetState();
+            const auditModel = { create: jasmine.createSpy('create').and.resolveTo() };
+            auditModels['Inv'] = auditModel;
+            modelOptions['Inv'] = { user: { username: 'k', id: 1 }, businessId: 'B1', auditEnabled: true };
+
+            const incremented = {
+                _previousDataValues: { qty: 5 },
+                dataValues: { id: 10, qty: 6 }
+            };
+            const model = { increment: jasmine.createSpy('increment').and.resolveTo(incremented) };
+
+            const r = await incrementWithAudit('Inv', model, 'qty', { by: 1, transaction: 'TX' });
+
+            expect(model.increment).toHaveBeenCalledWith('qty', { by: 1, transaction: 'TX' });
+            expect(r._changed).toEqual(['qty']);
+            expect(auditModel.create).toHaveBeenCalled();
+            expect(auditModel.create.calls.mostRecent().args[1]).toEqual({ transaction: 'TX' });
+        });
+
+        it('decrements and writes an audit row', async () => {
+            resetState();
+            const auditModel = { create: jasmine.createSpy('create').and.resolveTo() };
+            auditModels['Rel'] = auditModel;
+            modelOptions['Rel'] = { user: { username: 'k', id: 1 }, businessId: 'B1', auditEnabled: true };
+
+            const decremented = {
+                _previousDataValues: { qty: 6 },
+                dataValues: { id: 11, qty: 5 }
+            };
+            const model = { decrement: jasmine.createSpy('decrement').and.resolveTo(decremented) };
+
+            const r = await decrementWithAudit('Rel', model, 'qty', { by: 1 });
+
+            expect(model.decrement).toHaveBeenCalledWith('qty', { by: 1 });
+            expect(r._changed).toEqual(['qty']);
+            expect(auditModel.create).toHaveBeenCalled();
+        });
+    });
+
+    describe('getAuditModel / getAuditFilter', () => {
+        it('returns the audit model registered for a parent', () => {
+            resetState();
+            const fakeAudit = { name: 'WidgetAudit' };
+            auditModels['Widget'] = fakeAudit;
+            expect(getAuditModel({ name: 'Widget' })).toBe(fakeAudit);
+        });
+
+        it('builds a where filter scoped to caller businessIds with parent FK', () => {
+            resetState();
+            const Widget = { name: 'Widget' };
+            const event = buildEvent({ businessIds: { 'B1': 'A', 'B2': 'R' } });
+
+            const filter = getAuditFilter(Widget, 42, { event, offset: 0, limit: 10 });
+
+            expect(filter.where.WidgetId).toEqual(42);
+            expect(filter.where.businessId).toBeDefined();
+            expect(filter.include[0].model).toBe(Widget);
+            expect(filter.order).toEqual([['createdAt', 'DESC']]);
+            expect(filter.offset).toEqual(0);
+            expect(filter.limit).toEqual(10);
+        });
+    });
+});

package/src/database/dbUtils/partnerAccess/accessContext.js

@@ -0,0 +1,70 @@
+import { isSuperUser, isPartnerUser, getAccessRightsInfo } from '../queryStringUtils/accessRightsUtils.js';
+import { errorList } from '../../../requestResponse/errorCodes.js';
+
+/**
+ * Resolve the caller's access level from the Lambda event.
+ * Synchronous — reads JWT claims only, no Dynamo lookups.
+ *
+ * Returns an access object:
+ *   { level: 'global' }                              — super user or local/test env
+ *   { level: 'partner', partnerId, partnerBusinessId: null, businessIds: null }
+ *   { level: 'standard', businessIds: string[] }
+ *
+ * Partner fields (partnerBusinessId, businessIds) start null and are
+ * lazy-loaded by ensurePartnerScope on first use.
+ *
+ * @param {object} event - Lambda event with Cognito authorizer claims.
+ * @returns {object} Access object.
+ */
+export function resolveAccess(event) {
+    if (isSuperUser(event)) {
+        return { level: 'global' };
+    }
+
+    const env = process.env.BUILD_ENV;
+    if (env === 'local' || env === 'test') {
+        return { level: 'global' };
+    }
+
+    const partnerId = isPartnerUser(event);
+    if (partnerId) {
+        return { level: 'partner', partnerId, partnerBusinessId: null, businessIds: null };
+    }
+
+    const arBusinessIds = getAccessRightsInfo(event);
+    const businessIds = Object.keys(arBusinessIds);
+    if (businessIds.length > 0) {
+        return { level: 'standard', businessIds };
+    }
+
+    throw errorList.unauthorized;
+}
+
+/**
+ * Lazy-load partner scope from Dynamo. Populates partnerBusinessId and
+ * businessIds on the access object, then caches for the request lifetime.
+ *
+ * No-op for non-partner access objects or if already loaded.
+ *
+ * @param {object} access - Access object from resolveAccess.
+ * @param {{ getPartnerById: Function }} deps - Injected so piper-utils stays DB-agnostic.
+ * @returns {object} The same access object, now populated.
+ */
+export async function ensurePartnerScope(access, { getPartnerById }) {
+    if (!access || access.level !== 'partner') {
+        return access;
+    }
+    if (access.businessIds !== null && access.businessIds !== undefined) {
+        return access;
+    }
+    try {
+        const partner = await getPartnerById(access.partnerId);
+        access.businessIds = partner?.businessIds || [];
+        access.partnerBusinessId = partner?.partnerBusinessId || null;
+    } catch (err) {
+        console.error('partnerAccess: failed to load partner for scoping:', err);
+        access.businessIds = [];
+        access.partnerBusinessId = null;
+    }
+    return access;
+}

package/src/database/dbUtils/partnerAccess/accessGates.js

@@ -0,0 +1,34 @@
+import { errorList } from '../../../requestResponse/errorCodes.js';
+
+/**
+ * Gate: CRM routes — rejects standard users. Super and partner pass.
+ * @param {object} access - Access object from resolveAccess.
+ */
+export function requireCrmAccess(access) {
+    if (!access) {
+        throw errorList.unauthorized;
+    }
+    if (access.level === 'standard') {
+        throw errorList.unauthorized;
+    }
+}
+
+/**
+ * Gate: Ticket routes — all three user types pass. Only rejects null access.
+ * @param {object} access - Access object from resolveAccess.
+ */
+export function requireTicketAccess(access) {
+    if (!access) {
+        throw errorList.unauthorized;
+    }
+}
+
+/**
+ * Gate: Super-only routes — throws unless global.
+ * @param {object} access - Access object from resolveAccess.
+ */
+export function requireSuper(access) {
+    if (!access || access.level !== 'global') {
+        throw errorList.unauthorized;
+    }
+}

package/src/database/dbUtils/partnerAccess/accessScope.js

@@ -0,0 +1,99 @@
+import _ from 'lodash';
+import { ensurePartnerScope } from './accessContext.js';
+import { errorList } from '../../../requestResponse/errorCodes.js';
+
+/**
+ * Scope a WHERE clause to the partner's own business (partnerBusinessId).
+ * Use for "mine" resources: deal, activity, application, template.
+ *
+ *   global   → deletes where.businessId (super sees everything)
+ *   partner  → sets where.businessId = partnerBusinessId
+ *              throws partnerNotConfigured if partnerBusinessId is missing
+ *   standard → no-op (createFilters already handled)
+ *
+ * @param {object} where  - Sequelize WHERE clause to mutate.
+ * @param {object} access - Access object from resolveAccess.
+ * @param {{ getPartnerById: Function }} deps
+ */
+export async function scopeToOwnBusiness(where, access, { getPartnerById } = {}) {
+    if (!access) {
+        throw errorList.unauthorized;
+    }
+    if (access.level === 'global') {
+        delete where.businessId;
+        return;
+    }
+    if (access.level === 'partner') {
+        await ensurePartnerScope(access, { getPartnerById });
+        if (!access.partnerBusinessId) {
+            throw errorList.partnerNotConfigured;
+        }
+        where.businessId = access.partnerBusinessId;
+        return;
+    }
+    // standard → no-op (createFilters already injected from JWT)
+}
+
+/**
+ * Scope a WHERE clause to the partner's portfolio (businessIds array).
+ * Use for "book" resources (future transaction lists, merchant inbox views).
+ *
+ *   global   → deletes where.businessId
+ *   partner  → sets where.businessId = businessIds[]
+ *   standard → no-op
+ *
+ * @param {object} where  - Sequelize WHERE clause to mutate.
+ * @param {object} access - Access object from resolveAccess.
+ * @param {{ getPartnerById: Function }} deps
+ */
+export async function scopeToPartnerBook(where, access, { getPartnerById } = {}) {
+    if (!access) {
+        throw errorList.unauthorized;
+    }
+    if (access.level === 'global') {
+        delete where.businessId;
+        return;
+    }
+    if (access.level === 'partner') {
+        await ensurePartnerScope(access, { getPartnerById });
+        where.businessId = access.businessIds || [];
+        return;
+    }
+    // standard → no-op
+}
+
+/**
+ * Scope to the union of partnerBusinessId + businessIds.
+ * Use for tickets — partner sees own tickets + portfolio merchants' tickets.
+ *
+ *   global   → deletes where.businessId
+ *   partner  → sets where.businessId = [partnerBusinessId, ...businessIds]
+ *   standard → sets where.businessId = access.businessIds
+ *              (explicitly handled here because ticket routes may not call
+ *               createFilters before scoping, e.g. delete/resolve handlers)
+ *
+ * @param {object} where  - Sequelize WHERE clause to mutate.
+ * @param {object} access - Access object from resolveAccess.
+ * @param {{ getPartnerById: Function }} deps
+ */
+export async function scopeToBookUnionOwn(where, access, { getPartnerById } = {}) {
+    if (!access) {
+        throw errorList.unauthorized;
+    }
+    if (access.level === 'global') {
+        delete where.businessId;
+        return;
+    }
+    if (access.level === 'partner') {
+        await ensurePartnerScope(access, { getPartnerById });
+        const ids = _.uniq(
+            [access.partnerBusinessId, ...(access.businessIds || [])].filter(Boolean)
+        );
+        where.businessId = ids;
+        return;
+    }
+    if (access.level === 'standard') {
+        where.businessId = access.businessIds;
+        return;
+    }
+}

package/src/database/dbUtils/partnerAccess/accessWrites.js

@@ -0,0 +1,128 @@
+import _ from 'lodash';
+import { ensurePartnerScope } from './accessContext.js';
+import { errorList } from '../../../requestResponse/errorCodes.js';
+
+/**
+ * Assert the caller can write to their own business.
+ * For partner: businessId must equal partnerBusinessId.
+ *
+ *   global   → allow
+ *   partner  → businessId must equal partnerBusinessId; throws if not
+ *   standard → throws (CRM routes gate standard users before reaching this)
+ *
+ * @param {object} access     - Access object from resolveAccess.
+ * @param {string} businessId - The businessId being written to.
+ * @param {{ getPartnerById: Function }} deps
+ */
+export async function assertCanWriteOwnBusiness(access, businessId, { getPartnerById } = {}) {
+    if (!access) {
+        throw errorList.unauthorized;
+    }
+    if (access.level === 'global') {
+        return;
+    }
+    if (access.level === 'partner') {
+        await ensurePartnerScope(access, { getPartnerById });
+        if (!access.partnerBusinessId) {
+            throw { ...errorList.partnerNotConfigured };
+        }
+        if (businessId !== access.partnerBusinessId) {
+            throw errorList.unauthorized;
+        }
+        return;
+    }
+    throw errorList.unauthorized;
+}
+
+/**
+ * Assert the caller can write to a business in their portfolio.
+ * For partner: businessId must be in the businessIds array.
+ *
+ *   global   → allow
+ *   standard → allow (handled elsewhere via checkWriteAccess)
+ *   partner  → businessId must be in portfolio; throws if not
+ *
+ * @param {object} access     - Access object from resolveAccess.
+ * @param {string} businessId - The businessId being written to.
+ * @param {{ getPartnerById: Function }} deps
+ */
+export async function assertCanWriteBookBusiness(access, businessId, { getPartnerById } = {}) {
+    if (!access) {
+        throw errorList.unauthorized;
+    }
+    if (access.level === 'global') {
+        return;
+    }
+    if (access.level === 'standard') {
+        return;
+    }
+    if (access.level === 'partner') {
+        if (!businessId) {
+            throw { ...errorList.invalidRequest, message: 'businessId is required' };
+        }
+        await ensurePartnerScope(access, { getPartnerById });
+        if (!(access.businessIds || []).includes(businessId)) {
+            throw errorList.unauthorized;
+        }
+        return;
+    }
+    throw errorList.unauthorized;
+}
+
+/**
+ * Assert the caller can write to a business in the union of own + portfolio.
+ * For partner: businessId must be partnerBusinessId OR in businessIds[].
+ * Used by ticket write paths.
+ *
+ *   global   → allow
+ *   standard → allow (handled elsewhere via checkWriteAccess)
+ *   partner  → businessId must be in [partnerBusinessId, ...businessIds]
+ *
+ * @param {object} access     - Access object from resolveAccess.
+ * @param {string} businessId - The businessId being written to.
+ * @param {{ getPartnerById: Function }} deps
+ */
+export async function assertCanWriteBookUnionOwn(access, businessId, { getPartnerById } = {}) {
+    if (!access) {
+        throw errorList.unauthorized;
+    }
+    if (access.level === 'global') {
+        return;
+    }
+    if (access.level === 'standard') {
+        return;
+    }
+    if (access.level === 'partner') {
+        if (!businessId) {
+            throw { ...errorList.invalidRequest, message: 'businessId is required' };
+        }
+        await ensurePartnerScope(access, { getPartnerById });
+        const allowed = _.uniq(
+            [access.partnerBusinessId, ...(access.businessIds || [])].filter(Boolean)
+        );
+        if (!allowed.includes(businessId)) {
+            throw errorList.unauthorized;
+        }
+        return;
+    }
+    throw errorList.unauthorized;
+}
+
+/**
+ * Auto-stamp body.businessId from the partner's own business if missing.
+ * No-op for non-partner users or if body.businessId is already set.
+ *
+ * @param {object} access - Access object from resolveAccess.
+ * @param {object} body   - Request body to mutate.
+ * @param {{ getPartnerById: Function }} deps
+ */
+export async function stampOwnBusinessId(access, body, { getPartnerById } = {}) {
+    if (!access || access.level !== 'partner') {
+        return;
+    }
+    if (body.businessId) {
+        return;
+    }
+    await ensurePartnerScope(access, { getPartnerById });
+    body.businessId = access.partnerBusinessId;
+}

package/src/database/dbUtils/partnerAccess/createAccessHelpers.js

@@ -0,0 +1,38 @@
+import { ensurePartnerScope } from './accessContext.js';
+import { scopeToOwnBusiness, scopeToPartnerBook, scopeToBookUnionOwn } from './accessScope.js';
+import {
+    assertCanWriteOwnBusiness,
+    assertCanWriteBookBusiness,
+    assertCanWriteBookUnionOwn,
+    stampOwnBusinessId
+} from './accessWrites.js';
+
+/**
+ * Factory that pre-binds getPartnerById into all scope/assert/stamp helpers.
+ * Bind once at module level, then call without repeating the injection:
+ *
+ *   import { createAccessHelpers } from 'piper-utils';
+ *   import { getPartnerById } from '../partner/partner.js';
+ *
+ *   const {
+ *       scopeToOwnBusiness,
+ *       stampOwnBusinessId,
+ *       assertCanWriteOwnBusiness
+ *   } = createAccessHelpers({ getPartnerById });
+ *
+ * @param {{ getPartnerById: Function }} deps
+ * @returns {object} Pre-bound helpers.
+ */
+export function createAccessHelpers({ getPartnerById }) {
+    const deps = { getPartnerById };
+    return {
+        ensurePartnerScope: (access) => ensurePartnerScope(access, deps),
+        scopeToOwnBusiness: (where, access) => scopeToOwnBusiness(where, access, deps),
+        scopeToPartnerBook: (where, access) => scopeToPartnerBook(where, access, deps),
+        scopeToBookUnionOwn: (where, access) => scopeToBookUnionOwn(where, access, deps),
+        assertCanWriteOwnBusiness: (access, businessId) => assertCanWriteOwnBusiness(access, businessId, deps),
+        assertCanWriteBookBusiness: (access, businessId) => assertCanWriteBookBusiness(access, businessId, deps),
+        assertCanWriteBookUnionOwn: (access, businessId) => assertCanWriteBookUnionOwn(access, businessId, deps),
+        stampOwnBusinessId: (access, body) => stampOwnBusinessId(access, body, deps)
+    };
+}