tabletcommand-backend-models 7.4.99 → 7.4.100

package/sc-33945-plan.md

@@ -0,0 +1,189 @@
+# Plan — sc-33945: Update Endpoint to include "Can Approve Sharing Agreements" permission
+
+**Story:** [sc-33945](https://app.shortcut.com/tabletcommand/story/33945) (chore)
+**Parent:** [sc-33735](https://app.shortcut.com/tabletcommand/story/33735) — FE checkbox on Superuser User Details page
+**Epic:** [Data Sharing Agreement (33722)](https://app.shortcut.com/tabletcommand/epic/33722)
+**Iteration:** Sprint 2026/14 (2026-07-05 → 2026-07-19)
+**Owner:** Kevin Yoshiyama
+
+## Goal
+
+Extend the admin user-update API so a **superadmin** can grant/revoke a new boolean
+permission `canApproveSharingAgreements` on a user, subject to guardrails, with the
+change written to the searchable action log. This is the backend half; the parent
+story (33735) is the frontend checkbox.
+
+## Acceptance criteria (from the story)
+
+- [ ] API rejects `canApproveSharingAgreements: true` for non-admin target users with `400`.
+- [ ] Non-superadmin API callers receive `403` when attempting to set this field.
+- [ ] The user-detail `GET` response includes `canApproveSharingAgreements` for superadmin callers.
+- [ ] Grant/revoke is written to the audit log with the acting superadmin's ID + timestamp.
+- [ ] The action is searchable in the superadmin action log.
+- [ ] BE unit tests complete.
+
+---
+
+## Current state (what I found in the code)
+
+| Concern | Location |
+|---|---|
+| `GET /api/a1/admin/user/:userId` | [server-admin/src/routes/admin.ts:342](server-admin/src/routes/admin.ts) |
+| `POST /api/a1/admin/user/:userId/:departmentId?` (the "update" endpoint) | [server-admin/src/routes/admin.ts:374](server-admin/src/routes/admin.ts) |
+| Request-body decode / field allow-list | `decodeUpdateUser()` [server-admin/src/lib/domain.ts:4201](server-admin/src/lib/domain.ts) |
+| Auth resolution (`isSuper`, `isAdmin`, …) | `decodeAuth()` [server-admin/src/lib/domain.ts:389](server-admin/src/lib/domain.ts) |
+| Persist + restricted-field revert + action log | `updateUserForDepartment()` [server-admin/src/lib/store/index.ts:2010](server-admin/src/lib/store/index.ts) |
+| GET data fetch | `getUserForDepartment()` [server-admin/src/lib/store/index.ts:~1961](server-admin/src/lib/store/index.ts) |
+| Action-log write helper | `logAction()` / `models.ActionLog` [server-admin/src/lib/store/index.ts:418](server-admin/src/lib/store/index.ts) |
+| Action-log message formatter | [server-admin/src/lib/actionLogMessages.ts:287](server-admin/src/lib/actionLogMessages.ts) |
+| BE tests | [server-admin/src/test/routes/admin.ts](server-admin/src/test/routes/admin.ts) (`node:test` + `chai` + `node-mocks-http`) |
+| **User model / schema (EXTERNAL)** | `tabletcommand-backend-models` `~7.4.94` — `src/models/user.ts`, `src/types/user.ts`, collection `sys_user` |
+
+### Key facts that shape the plan
+
+1. **The User model is an external npm package**, not in this repo. The Mongoose schema is
+   **strict by default** (no `strict: false`), so a field absent from the schema is silently
+   dropped on save. `canApproveSharingAgreements` **must be added to
+   `tabletcommand-backend-models` first**, published, then the dependency bumped here. This is
+   a hard prerequisite — without it, saves will no-op.
+
+2. **The existing pattern for privileged flags is a silent revert, not a 403.** For `admin` and
+   `canBlockIncidents`, a non-superadmin's edits are reverted to the previous value
+   ([store/index.ts:2039-2044](server-admin/src/lib/store/index.ts)) — no error is returned.
+   The story asks for an explicit **`403`**. See Decision 1.
+
+3. **Auth failures in these routes currently return `401`, not `403`** (see admin.ts:353/383).
+   The story says `403`. See Decision 1.
+
+4. **The endpoint is `POST` (not `PUT`) at `/user/:userId/:departmentId?`** — the story's
+   `api/a1/admin/user/` shorthand omits this. No route change needed.
+
+5. **Action logging is already generic.** `updateUserForDepartment` builds a `propertiesChanged`
+   array and writes one `ActionLog` (`action: "adminModifyUser"`) with `email: user.email`
+   (the actor) and `createdAt` timestamp. Adding a `canApproveSharingAgreements` diff to that
+   array satisfies the "audit log + searchable" criteria for free. Note the actor is recorded by
+   **email**, not `_id` — see Decision 2.
+
+---
+
+## Decisions (confirmed)
+
+**Decision 1 — Return `403` for unauthorized writes. ✅ CONFIRMED.**
+Return `403` when a non-superadmin includes `canApproveSharingAgreements` in the body. Implemented
+as an early guard in the route so it doesn't disturb the existing revert behavior for other flags.
+(This intentionally diverges from the surrounding `401` convention for auth failures — accepted.)
+
+**Decision 2 — Log both email and `_id` in the audit log. ✅ CONFIRMED.**
+Existing `adminModifyUser` logs store the actor as `email`. Record **both** the acting user's
+`email` and `_id` on the action item.
+
+**Decision 3 — "target user is admin" check basis.**
+`canApproveSharingAgreements: true` is only allowed if the target is an admin. Because admin status
+can change in the same request, validate against the **effective** admin value:
+`userData.admin` if present in the body, else `previousUser.admin`. Also mirror the parent story's
+rule: **if admin is being set false, force `canApproveSharingAgreements = false`.**
+
+**Decision 4 — Include a descriptive `message` in error response bodies. ✅ CONFIRMED.**
+The `400` (non-admin target) and `403` (non-superadmin caller) responses should return a `message`
+field explaining the rejection, e.g. `{ ok: false, message: "..." }`, rather than bare
+`{ ok: false }`.
+
+---
+
+## Implementation steps
+
+### Step 0 — External model change (prerequisite, separate repo)
+In `tabletcommand-backend-models`:
+- Add to `src/models/user.ts` (next to `canBlockIncidents`, ~line 123):
+  ```ts
+  canApproveSharingAgreements: {
+    type: Boolean,
+    default: false,
+  },
+  ```
+- Add `canApproveSharingAgreements: boolean` to the `User` type in `src/types/user.ts` (~line 103).
+- Add it to the test mock (`src/test/mock.ts`) if permission flags are enumerated there.
+- Publish a new version; bump `server-admin/package.json` (`~7.4.94` → new) and `npm install`.
+
+> If publishing a new models version is out of scope for this sprint, coordinate with whoever
+> owns that package. Nothing below persists without it.
+
+### Step 1 — Route guard for superadmin-only write (`403`)
+In `POST /user/:userId/:departmentId?` ([routes/admin.ts:374](server-admin/src/routes/admin.ts)),
+after `decodeAuth`: if `req.body` contains the key `canApproveSharingAgreements` **and** `!isSuper`,
+return `403` with `{ ok: false, message: "..." }` (Decision 4). Do this before
+`decodeUpdateUser`/store call.
+
+### Step 2 — Preserve the field through decode
+`decodeUpdateUser()` ([domain.ts:4201](server-admin/src/lib/domain.ts)) uses an `ignoredFields`
+allow-list; `canApproveSharingAgreements` is **not** in it, so it passes through — no change needed.
+Add a brief comment noting it's intentionally allowed (superadmin-gated upstream). Do **not** add it
+to `ignoredFields`.
+
+### Step 3 — Validation + revert logic in the store
+In `updateUserForDepartment()` ([store/index.ts:2010](server-admin/src/lib/store/index.ts)), after
+`previousUser` is loaded (~line 2038):
+- **400 guard:** if `userData.canApproveSharingAgreements === true`, compute effective admin
+  (`userData.admin ?? previousUser.admin`); if not truthy, reject with `400` and a descriptive
+  `message` in the body (Decision 4), e.g.
+  `{ ok: false, message: "canApproveSharingAgreements requires the target user to be an admin" }`.
+  Implement via a typed error the route maps to `400`, or short-circuit in the route before the
+  store call — either way the message must reach the body (the existing `catch` returns a bare
+  `{ ok: false }`, so adjust it or return earlier).
+- **Cascade:** if effective admin is false, force `userData.canApproveSharingAgreements = false`
+  (mirrors parent-story rule and prevents orphaned permission).
+- **Non-superadmin safety net:** extend the existing block at
+  [store/index.ts:2039-2044](server-admin/src/lib/store/index.ts) to also revert
+  `canApproveSharingAgreements` to `previousUser.canApproveSharingAgreements` when
+  `user.superuser !== true` (defense in depth behind the Step 1 route guard).
+
+### Step 4 — Audit log entry
+In the `propertiesChanged` block (~[store/index.ts:2099](server-admin/src/lib/store/index.ts)),
+mirroring the `admin` diff:
+```ts
+if (foundUser.canApproveSharingAgreements !== userData.canApproveSharingAgreements) {
+  propertiesChanged.push({ canApproveSharingAgreements: userData.canApproveSharingAgreements });
+}
+```
+This flows into the existing `adminModifyUser` `ActionLog` (actor email + `createdAt`), making it
+searchable. Record both acting `user.email` (already present) and `user._id` per Decision 2.
+Confirm `formatAdminModifyUserMessage`
+([actionLogMessages.ts:287](server-admin/src/lib/actionLogMessages.ts)) renders the new key
+acceptably (its generic loop already handles arbitrary keys).
+
+### Step 5 — GET response
+`getUserForDepartment()` returns the full Mongoose doc, so once the schema field exists (Step 0)
+the value is included automatically. **Verify** no projection/`select` or serializer strips it, and
+that it's only meaningfully surfaced for superadmin callers (the field is superadmin-managed; the FE
+in 33735 only renders it for superadmins). No code change expected — confirm with a test.
+
+### Step 6 — Backend unit tests
+Add to [server-admin/src/test/routes/admin.ts](server-admin/src/test/routes/admin.ts), following
+the existing `superUserTest` / `requestUser2` fixtures and `httpMocks` patterns:
+1. Superadmin sets `canApproveSharingAgreements: true` on an admin target → `200`; DB value `true`;
+   `ActionLog` row written with the diff.
+2. Set `true` on a **non-admin** target → `400`.
+3. **Non-superadmin** (regular admin) sends the field → `403`.
+4. Setting `admin: false` cascades `canApproveSharingAgreements` → `false`.
+5. `GET /user/:userId` as superadmin includes the field.
+6. Revoke (`true` → `false`) writes an audit-log diff.
+
+Run: `gulp test` (or the `tsx --test` next-suite) in `server-admin`.
+
+---
+
+## Out of scope
+- Frontend checkbox / Data Sharing tab visibility — parent story [sc-33735](https://app.shortcut.com/tabletcommand/story/33735).
+- Bulk-edit endpoint (`/user-bulk-edit`) — **out of scope for this story** (confirmed).
+
+## Risks / open questions
+- **Models package release** (Step 0) is the critical path and lives in another repo.
+- Whether the 400 error message should appear in the response body (current pattern returns
+  `{ ok: false }` only).
+
+## Suggested commits / PR
+1. (models repo) add `canApproveSharingAgreements` to schema + type + mock; publish.
+2. `server-admin`: bump models dep; route `403` guard; store 400/cascade/revert; audit-log diff.
+3. `server-admin`: unit tests.
+
+Branch suggestion: `feature/sc-33945/can-approve-sharing-agreements`.

package/src/index.ts

@@ -35,6 +35,7 @@ async function wireModels(mongoose: MongooseModule) {
     CADIncident: await getModel(import("./models/cad-incident")),
     CADIncidentBlock: await getModel(import("./models/cad-incident-block")),
     CADIncidentStream: await getModel(import("./models/cad-incident-stream")),
+    CADInterfaceMetaData: await getModel(import("./models/cad-interface-meta-data")),
     CADSimulation: await getModel(import("./models/cad-simulation")),
     CADStatus: await getModel(import("./models/cad-status")),
     CADStatusMap: await getModel(import("./models/cad-status-map")),
@@ -100,6 +101,7 @@ export { BeaconLog, BeaconLogModel } from "./models/beacon-log";
 export { CADIncident, CADIncidentModel } from "./models/cad-incident";
 export { CADIncidentBlock, CADIncidentBlockModel } from "./models/cad-incident-block";
 export { CADIncidentStream, CADIncidentStreamModel } from "./models/cad-incident-stream";
+export { CADInterfaceMetaData, CADInterfaceMetaDataModel } from "./models/cad-interface-meta-data";
 export { CADSimulation, CADSimulationModel } from "./models/cad-simulation";
 export { CADStatus, CADStatusModel } from "./models/cad-status";
 export { CADStatusMap, CADStatusMapModel } from "./models/cad-status-map";
@@ -154,6 +156,7 @@ export { UserRegistration, UserRegistrationModel } from "./models/user-registrat
 export { ValidationReport, ValidationReportModel } from "./models/validation-report";
 
 export * from "./helpers";
+export { IntegrationTypes } from "./types/department";
 
 export * from "./checklist-item-event-message";
 
@@ -162,7 +165,11 @@ export type {
   ForwardingConnectionType,
   ForwardingConfigType,
   ForwardFieldsType,
+  IntegrationType,
 } from "./types/department";
+export type {
+  CADInterfaceMetaDataType,
+} from "./types/cad-interface-meta-data";
 
 // Export default vars
 export {

package/src/models/cad-interface-meta-data.ts

@@ -0,0 +1,27 @@
+import { Model, Schema } from "mongoose";
+import { MongooseModule } from "../helpers";
+import { CADInterfaceMetaDataType } from "../types/cad-interface-meta-data";
+
+export interface CADInterfaceMetaData extends CADInterfaceMetaDataType {}
+
+export default async function CADInterfaceMetaDataModule(mongoose: MongooseModule) {
+  const modelSchema = new Schema<CADInterfaceMetaDataType>({
+    systemType: { type: String, required: true, trim: true },
+  }, {
+    autoIndex: false,
+    timestamps: true, // manages createdAt / updatedAt automatically (per story)
+    toJSON: { virtuals: true, versionKey: false },
+  });
+
+  // Uniqueness so the same CAD system can't be catalogued twice.
+  modelSchema.index({ systemType: 1 }, { unique: true });
+
+  return mongoose.model<CADInterfaceMetaData>(
+    "CADInterfaceMetaData",
+    modelSchema,
+    "massive_cad_interface_meta_data",
+    { overwriteModels: true }
+  );
+}
+
+export interface CADInterfaceMetaDataModel extends Model<CADInterfaceMetaData> {}

package/src/models/department.ts

@@ -50,6 +50,7 @@ import {
   IntterraConnectionType,
   IntterraFieldsType,
   LicensingType,
+  IntegrationTypes,
   ManagedIncidentMode,
   ManagedIncidentModeItem,
   ManagedIncidentPriority,
@@ -1741,7 +1742,7 @@ export default async function DepartmentModule(mongoose: MongooseModule) {
   });
 
   // Main schema
-  const modelSchema = new Schema<DepartmentType>({
+  const modelSchema = new Schema<Department>({
     _id: {
       type: Schema.Types.ObjectId,
       auto: true,
@@ -2080,6 +2081,16 @@ export default async function DepartmentModule(mongoose: MongooseModule) {
       ref: "Agency",
       default: [],
     }],
+    cadInterfaceMetaDataId: {
+      type: mongoose.Schema.Types.ObjectId,
+      ref: "CADInterfaceMetaData",
+      default: null,
+    },
+    integrationType: {
+      type: String,
+      enum: [...IntegrationTypes, ""],
+      default: "",
+    },
 
     // Signup
     signupKey: {

package/src/test/cad-interface-meta-data.ts

@@ -0,0 +1,53 @@
+import { assert } from "chai";
+import { describe, it, beforeEach, afterEach } from "node:test";
+import * as m from "../index";
+import * as config from "./config";
+import mockModule from "./mock";
+
+describe("CADInterfaceMetaData", function() {
+  let models: m.BackendModels, mongoose: m.MongooseModule;
+  let testItem: Partial<m.CADInterfaceMetaData>;
+  beforeEach(async function() {
+    const c = await m.connect(config.url);
+    models = c.models;
+    mongoose = c.mongoose;
+
+    const mock = mockModule({
+      mongoose
+    });
+    testItem = {
+      systemType: "Tritech Inform"
+    };
+    await mock.beforeEach();
+  });
+  afterEach(async function() {
+    await mongoose.disconnect();
+  });
+
+  it("is saved", async function() {
+    const item = new models.CADInterfaceMetaData(testItem);
+    const sut = await item.save();
+
+    assert.isNotNull(sut._id);
+    assert.equal(sut.systemType, testItem.systemType);
+    assert.isNotNull(sut.createdAt);
+    assert.isNotNull(sut.updatedAt);
+  });
+
+  it("enforces unique systemType index", async function() {
+    const item1 = new models.CADInterfaceMetaData(testItem);
+    await item1.save();
+
+    const item2 = new models.CADInterfaceMetaData({
+      systemType: testItem.systemType
+    });
+    try {
+      await item2.save();
+      assert.fail("Should have failed unique index constraint");
+    } catch (err: any) {
+      assert.isNotNull(err);
+      // Mongo unique index error code is 11000
+      assert.equal(err.code, 11000);
+    }
+  });
+});

package/src/types/cad-interface-meta-data.ts

@@ -0,0 +1,9 @@
+import { Types } from "mongoose";
+
+export interface CADInterfaceMetaDataType {
+  _id: Types.ObjectId;
+  systemType: string;
+  // timestamps managed by mongoose:
+  createdAt?: Date;
+  updatedAt?: Date;
+}

package/src/types/department.ts

@@ -9,6 +9,9 @@ import {
 import { ReportNumberSchemaType } from "./common-incident";
 import { GeoPolygon } from "./geojson";
 
+export const IntegrationTypes = ["TC", "Vendor", "Hybrid"] as const;
+export type IntegrationType = typeof IntegrationTypes[number];
+
 export interface WSFeedConnectionOptionsType {
   enabled: boolean;
   url: string;
@@ -588,6 +591,8 @@ export interface DepartmentType {
   addUserInstructions: string,
   adsb: ADSBConfigType,
   agencyIds: Types.ObjectId[],
+  cadInterfaceMetaDataId?: Types.ObjectId | null,
+  integrationType?: IntegrationType | "",
   allowShareWith3rdParties: boolean,
   apikey: string,
   arcGISMapsEnabled: boolean,