Permissions, Tenancy & Rollout

Business view

DHS touches money, patient identity and a national health exchange. Three separate controls decide whether any given click is allowed:

1. Is the feature on for this clinic? A feature flag, off for everyone except the beta

cohort.

1. Does this user have the right permission? Nine new, deliberately granular

permissions, configured per permission group.

1. Does this record belong to this clinic? Tenant rules, enforced server-side even for

users who pass the first two.

The nine permissions

They appear as a new DHS Settings tab when editing a permission group (Settings → Permission Groups → group):

Two more live on the Settings tab, under a DHS Integration row:

For that row the View-Created, Add and Delete checkboxes are deliberately disabled — only View and Edit make sense for a singleton integration record.

Sensible defaults to recommend

Dentolize ships no DHS permissions enabled on any seeded group. A reasonable starting point:

The rollout flag

FEATURE_DHS_INTEGRATION is seeded active: true with the positive rule Rule('isBeta', 'EQUALS', true). In plain terms: the feature is live only for companies flagged as beta. Turning it on for a clinic is a matter of flipping that company's beta flag (or editing the rule), not a code deploy.

When the flag is off, every DHS GraphQL operation is refused, every DHS UI surface is hidden, the background job skips the company entirely, and — importantly — the invoicing guards do not block anything. A non-beta clinic behaves exactly as it did before this PR.

Technical view

Permission constants

packages/prisma/schema.prisma:6348-6356 and enums.graphql:622-630, identical sets:

VIEW_DHS_INTEGRATION      EDIT_DHS_INTEGRATION
VIEW_DHS_APPROVALS        CHECK_DHS_INSURANCE
CHECK_DHS_ELIGIBILITY     CREATE_DHS_APPROVAL
CANCEL_DHS_APPROVAL       CREATE_MANUAL_DHS_APPROVAL
GET_DHS_APPROVAL

Documented discrepancy. The PR description names MANAGE_DHS_INTEGRATION, MANAGE_DHS_APPROVALS and CHECK_INSURANCE. Those were added to the Postgres enum by migration 20260615152553_dhs_permissions and then superseded by the nine above in 20260616100525_add_dhs_permissions. Because Postgres cannot drop enum values, they still exist in the database type while being absent from schema.prisma and enums.graphql. A repo-wide grep for MANAGE_DHS returns zero hits. The PR description is out of date; the code is correct.

Front-end mapping: packages/clinic-mobile/src/shared/utils/getUserPermissions.js:459-468 (shared by web and mobile). Note getDhsApprovals is backed by the singular GET_DHS_APPROVAL constant.

Permission-group UI: settings/Groups/tableData.js:471-479 (the seven-row DhsDataSource, exported at :1133), rendered as its own tab at settings/Groups/Group.js:251. The DHS_INTEGRATION row lives in the Settings data source at tableData.js:126-129, with View-Created / Add / Delete disabled at :515, :529, :562.

Shield wiring

packages/server/src/permissions/permissions.js. Every DHS field uses the same shape:

and(
  chain(isAuthenticated, hasPermission(X)[, tenantRule]),
  hasFeatureFlag('FEATURE_DHS_INTEGRATION')
)

Queries (:2727-2734):

Mutations (:2770-2781):

The move out of the public patientApp namespace into the authenticated clinic namespace — called out in the PR's security-review section — is what these entries represent.

Tenant rules

packages/server/src/permissions/rules.js:

All three return true when the relevant id is absent — they are permissive on absence, not fail-closed. The resolvers compensate: dhsGetApproval.js:30-31 and dhsCancelApproval.js:29-37 both add an explicit !dhsApprovalId guard whose comment explains that Prisma drops undefined filters, which would otherwise degrade the lookup to "any approval in this company".

isSameCompanyAsDhsManualOperations checks the branch's company, not operation.companyId, and its .every does not verify that all requested ids were found — a nonexistent id silently drops out of the result set. The resolver's own count assertion (dhsManualUpdateOperations.js:46-51) is the real guard.

Note: the read side (getDHSApprovals, dhsApprovalDetails) has no shield-level tenant rule. Scoping is enforced inside the resolvers — getDHSApprovals.js:16-17 always includes AND: [{ companyId }], and dhsApprovalDetails.js:24-26 compares approval.companyId after an unscoped findUnique and throws 'Not Authorised'.

Defence in depth: layered gating

Even with the flag and permission satisfied, most patient-facing surfaces require a third condition — the selected branch has an NPHIES code:

This is why, on a freshly flagged clinic, none of the patient-side DHS controls appear until step 2 of the setup wizard has been completed. It was reproduced exactly on the branch sandbox: setting a branch NPHIES code made Check Eligibility, Check Insurance, the Approvals tab and GET Approval all appear at once.

Feature-flag enforcement — three independent places

The flag is genuinely enforced, not a decorative seed row:

1. GraphQL shield — all 18 DHS operations, via hasFeatureFlag

(rules.js:174-193), which loads the flag row and evaluates positive/negative rules against the caller's company. All rejection causes collapse to the same 'Feature not enabled' message, deliberately (comment :169-170).

1. The cron — a global active check at dhsApprovalsCron.js:68-75, then per-company

rule evaluation at :124-145.

1. Resolver-side guard — isDhsFeatureActiveForCompany inside

assertNoPendingDhsApproval (dhsGuards.js:6,12-28,51), so that flag-off never blocks invoicing.

All three share evaluateFeatureFlagRules and the same company field set { id, country, isBeta, isVIP, tier, createdAt }. rules.js:165-167 explains why the company is loaded directly rather than via companyCache — the cache omits those fields.

Seed: packages/server/src/generateServerData/seedFeatureFlags.js:39-45, upserted by key at :50-54.

The seed description says "off by default", but the row is seeded active: true with a beta-only positive rule. The gating is the isBeta rule, not the active bit — worth knowing before someone flips active expecting it to be the master switch.

Client-side, useFeatureFlag('FEATURE_DHS_INTEGRATION') appears in ~20 files across clinic-web and clinic-web-canary. That is presentation only; the server is the authority.

Environment prerequisites

All hardcoded staging-*.motalabatech.health URLs were replaced by these variables, as the PR describes. required() also strips one trailing slash (dhsConfig.js:4).