@burdenoff/microfe-movethewheels 2026.1012.2 → 2026.1013.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@burdenoff/microfe-movethewheels",
-  "version": "2026.1012.2",
+  "version": "2026.1013.1",
   "description": "Burdenoff MoveTheWheels Microfrontend - Logistics & Supply Chain Management Platform",
   "type": "module",
   "files": [
@@ -36,7 +36,7 @@
     "format": "prettier --write \"src/**/*.{ts,tsx}\"",
     "type:check": "bash scripts/build-limits.sh tsc --noEmit",
     "validate:schema-drift": "graphql-schema-drift",
-    "sanity": "bash scripts/build-limits.sh --gate bash -c 'bun run codegen && bun run validate:schema-drift && bun run lint:sanity && bun run format && bun run type:check && bun run verify:live-logistics-contract && bun run verify:empty-reuse-retry && bun run verify:empty-reuse-recovery && bun run verify:trip-utilization-input && bun run verify:trip-draft-context && bun run verify:stock-binding-input && bun run verify:stock-observation-input && bun run verify:pending-pick-input && bun run verify:freight-input && bun run verify:freight-recovery && bun run verify:procedure-input && bun run verify:consolidation && bun run verify:multimodal-single-attempt && bun run verify:workspace-predispatch && bun run verify:tracking-quality-outcomes && bun run verify:shipment-status-authority && bun run verify:braces-depth && bun run build && bun run build-storybook'",
+    "sanity": "bash scripts/build-limits.sh --gate bash -c 'bun run codegen && bun run validate:schema-drift && bun run lint:sanity && bun run format && bun run type:check && bun run verify:live-logistics-contract && bun run verify:empty-reuse-retry && bun run verify:empty-reuse-recovery && bun run verify:trip-utilization-input && bun run verify:trip-draft-context && bun run verify:stock-binding-input && bun run verify:stock-observation-input && bun run verify:pending-pick-input && bun run verify:freight-input && bun run verify:freight-recovery && bun run verify:procedure-input && bun run verify:consolidation && bun run verify:multimodal-single-attempt && bun run verify:workspace-predispatch && bun run verify:tracking-quality-outcomes && bun run verify:shipment-status-authority && bun run verify:free-time-permissions && bun run verify:braces-depth && bun run build && bun run build-storybook'",
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build",
     "test:storybook": "test-storybook",
@@ -64,7 +64,8 @@
     "verify:consolidation": "bun scripts/verify-consolidation-input.mjs && bun scripts/verify-consolidation-recovery-hook.mjs && bun scripts/verify-consolidation-mounted-hook.mjs",
     "verify:tracking-quality-outcomes": "bun test scripts/verify-tracking-quality-outcomes.test.ts",
     "verify:braces-depth": "bun test scripts/braces-depth-patch.test.ts",
-    "verify:shipment-status-authority": "bun scripts/verify-shipment-status-command.mjs"
+    "verify:shipment-status-authority": "bun scripts/verify-shipment-status-command.mjs",
+    "verify:free-time-permissions": "bun scripts/verify-free-time-permission-gates.mjs"
   },
   "dependencies": {
     "@apollo/client": "^4.0.11",

package/src/movethewheels/hooks/useContainerLifecycle.ts

@@ -64,7 +64,7 @@ function describeError(error: unknown): string {
 }
 
 /** Source-labelled physical equipment; cargo shipment completion does not close a cycle. */
-export function useContainerLifecycle() {
+export function useContainerLifecycle(readEnabled = true) {
   const { apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, currentUser } =
     useMoveTheWheels();
   const options = useMemo(
@@ -103,6 +103,10 @@ export function useContainerLifecycle() {
     setError(null);
     setContainers([]);
     setHasMore(false);
+    if (!readEnabled) {
+      setLoading(false);
+      return;
+    }
     void executeGraphQL<ContainerRegistryQuery>(options, print(ContainerRegistryDocument), {
       pagination: { limit: PAGE_SIZE, offset: page * PAGE_SIZE },
     })
@@ -121,7 +125,7 @@ export function useContainerLifecycle() {
     return () => {
       cancelled = true;
     };
-  }, [options, page, revision]);
+  }, [options, page, revision, readEnabled]);
 
   // Clear selections whenever the security/workspace context changes.
   useEffect(() => {
@@ -137,7 +141,7 @@ export function useContainerLifecycle() {
     setCycles([]);
     setHasMoreCycles(false);
     setCycleError(null);
-    if (!containerId) {
+    if (!readEnabled || !containerId) {
       setCyclesLoading(false);
       return;
     }
@@ -161,14 +165,14 @@ export function useContainerLifecycle() {
     return () => {
       cancelled = true;
     };
-  }, [options, containerId, cyclePage, revision]);
+  }, [options, containerId, cyclePage, revision, readEnabled]);
 
   useEffect(() => {
     let cancelled = false;
     setEvents([]);
     setHasMoreEvents(false);
     setEventError(null);
-    if (!cycleId) {
+    if (!readEnabled || !cycleId) {
       setEventsLoading(false);
       return;
     }
@@ -192,7 +196,7 @@ export function useContainerLifecycle() {
     return () => {
       cancelled = true;
     };
-  }, [options, cycleId, eventPage, revision]);
+  }, [options, cycleId, eventPage, revision, readEnabled]);
 
   const refresh = useCallback(() => setRevision((value) => value + 1), []);
   // Keep the same key after an uncertain response so a manual retry replays the

package/src/movethewheels/hooks/useShipmentPermissions.ts

@@ -0,0 +1,38 @@
+import { useCallback, useLayoutEffect, useRef } from 'react';
+import { usePermissions } from '@burdenoff/fe-libs/shared/providers/shell';
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+
+/** Match ordinary effective permissions to this page's current actor and workspace. */
+export function useShipmentPermissions() {
+  const permissions = usePermissions();
+  const { workspaceId, currentUser } = useMoveTheWheels();
+  const currentScope = Boolean(
+    workspaceId &&
+    currentUser?.id &&
+    permissions.scopeId === workspaceId &&
+    (permissions.isSuperAdmin ||
+      (permissions.permissions?.scopeId === workspaceId &&
+        permissions.permissions.actorId === currentUser.id))
+  );
+  const ready = currentScope && !permissions.isLoading && !permissions.error;
+  const canRead = ready && permissions.hasPermission('shipment:read');
+  const canCreate = canRead && permissions.hasPermission('shipment:create');
+  const canUpdate = canRead && permissions.hasPermission('shipment:update');
+  const current = useRef({ create: false, update: false });
+  useLayoutEffect(() => {
+    current.current = { create: canCreate, update: canUpdate };
+    return () => {
+      // Retained callbacks from a revoked or unmounted scope cannot submit a command.
+      current.current = { create: false, update: false };
+    };
+  }, [canCreate, canUpdate]);
+  const allows = useCallback((action: 'create' | 'update') => current.current[action], []);
+  return {
+    canRead,
+    canCreate,
+    canUpdate,
+    allows,
+    loading: permissions.isLoading,
+    failed: Boolean(permissions.error),
+  };
+}

package/src/movethewheels/pages/ContainersPage.tsx

@@ -1,5 +1,7 @@
 import { useState, type FormEvent } from 'react';
 import { Boxes, RefreshCw } from 'lucide-react';
+import { PermissionProvider } from '@burdenoff/fe-libs/shared/providers/shell';
+import { useShipmentPermissions } from '../hooks/useShipmentPermissions';
 import { PageLayout } from '../components/PageLayout';
 import { Button, Input, Label } from '../components/ui';
 import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
@@ -23,12 +25,25 @@ const sectionClass = 'rounded-xl border bg-bg-surface p-5 space-y-4';
 
 /** Remount on identity/workspace changes so previous workspace records never flash. */
 export default function ContainersPage() {
-  const { workspaceId, currentUser } = useMoveTheWheels();
-  return <ContainerWorkbench key={`${workspaceId ?? ''}:${currentUser?.id ?? ''}`} />;
+  const { workspaceId, tenantId, currentUser, apiGatewayUrl } = useMoveTheWheels();
+  return (
+    <PermissionProvider
+      key={`${workspaceId}:${tenantId}:${currentUser?.id}:${apiGatewayUrl}`}
+      scopeId={workspaceId ?? null}
+      gateway="workspace"
+    >
+      <ContainerAccess />
+    </PermissionProvider>
+  );
+}
+
+function ContainerAccess() {
+  const access = useShipmentPermissions();
+  return <ContainerWorkbench access={access} />;
 }
 
-function ContainerWorkbench() {
-  const data = useContainerLifecycle();
+function ContainerWorkbench({ access }: { access: ReturnType<typeof useShipmentPermissions> }) {
+  const data = useContainerLifecycle(access.canRead);
   const [number, setNumber] = useState('');
   const [equipmentType, setEquipmentType] = useState<EquipmentType>('DRY_20');
   const [ownerName, setOwnerName] = useState('');
@@ -63,6 +78,7 @@ function ContainerWorkbench() {
   };
   const register = (event: FormEvent) => {
     event.preventDefault();
+    if (!access.allows('create')) return;
     void act(async () => {
       await data.register({
         containerNumber: number.trim(),
@@ -75,7 +91,7 @@ function ContainerWorkbench() {
   };
   const record = (event: FormEvent) => {
     event.preventDefault();
-    if (!cycle) return;
+    if (!cycle || !access.allows('update')) return;
     void act(async () => {
       const timestamp = new Date(eventTime);
       if (!Number.isFinite(timestamp.getTime())) throw new Error('Enter a valid event time.');
@@ -94,6 +110,21 @@ function ContainerWorkbench() {
     }, 'Event recorded with its source and receipt time.');
   };
 
+  if (!access.canRead)
+    return (
+      <PageLayout
+        title="Containers"
+        subtitle="Physical equipment, usage cycles and sourced movement history"
+      >
+        <p role={access.failed ? 'alert' : 'status'}>
+          {access.loading
+            ? 'Checking shipment permissions…'
+            : access.failed
+              ? 'Shipment permissions are unavailable. Reload to retry.'
+              : 'Shipment read permission is required.'}
+        </p>
+      </PageLayout>
+    );
   return (
     <PageLayout
       title="Containers"
@@ -167,54 +198,56 @@ function ContainerWorkbench() {
               data.setPage(page);
             }}
           />
-          <form onSubmit={register} className="space-y-3 border-t pt-4">
-            <h3 className="font-semibold">Register container</h3>
-            <Label htmlFor="container-number">ISO container number</Label>
-            <Input
-              id="container-number"
-              value={number}
-              onChange={(event) => setNumber(event.target.value)}
-              required
-              maxLength={20}
-              placeholder="Four letters and seven digits"
-            />
-            <Label htmlFor="equipment-type">Physical equipment type</Label>
-            <select
-              id="equipment-type"
-              className={selectClass}
-              value={equipmentType}
-              onChange={(event) =>
-                setEquipmentType(
-                  EQUIPMENT_TYPES.find((value) => value === event.target.value) ?? 'OTHER'
-                )
-              }
-            >
-              {EQUIPMENT_TYPES.map((value) => (
-                <option key={value} value={value}>
-                  {readable(value)}
-                </option>
-              ))}
-            </select>
-            <Label htmlFor="container-owner">Owner (optional)</Label>
-            <Input
-              id="container-owner"
-              value={ownerName}
-              onChange={(event) => setOwnerName(event.target.value)}
-              maxLength={200}
-            />
-            <Label htmlFor="container-source">Information source</Label>
-            <Input
-              id="container-source"
-              value={source}
-              onChange={(event) => setSource(event.target.value)}
-              required
-              maxLength={120}
-              placeholder="Equipment release document or carrier portal"
-            />
-            <Button type="submit" disabled={busy || !number.trim() || !source.trim()}>
-              Register container
-            </Button>
-          </form>
+          {access.canCreate && (
+            <form onSubmit={register} className="space-y-3 border-t pt-4">
+              <h3 className="font-semibold">Register container</h3>
+              <Label htmlFor="container-number">ISO container number</Label>
+              <Input
+                id="container-number"
+                value={number}
+                onChange={(event) => setNumber(event.target.value)}
+                required
+                maxLength={20}
+                placeholder="Four letters and seven digits"
+              />
+              <Label htmlFor="equipment-type">Physical equipment type</Label>
+              <select
+                id="equipment-type"
+                className={selectClass}
+                value={equipmentType}
+                onChange={(event) =>
+                  setEquipmentType(
+                    EQUIPMENT_TYPES.find((value) => value === event.target.value) ?? 'OTHER'
+                  )
+                }
+              >
+                {EQUIPMENT_TYPES.map((value) => (
+                  <option key={value} value={value}>
+                    {readable(value)}
+                  </option>
+                ))}
+              </select>
+              <Label htmlFor="container-owner">Owner (optional)</Label>
+              <Input
+                id="container-owner"
+                value={ownerName}
+                onChange={(event) => setOwnerName(event.target.value)}
+                maxLength={200}
+              />
+              <Label htmlFor="container-source">Information source</Label>
+              <Input
+                id="container-source"
+                value={source}
+                onChange={(event) => setSource(event.target.value)}
+                required
+                maxLength={120}
+                placeholder="Equipment release document or carrier portal"
+              />
+              <Button type="submit" disabled={busy || !number.trim() || !source.trim()}>
+                Register container
+              </Button>
+            </form>
+          )}
         </section>
         <section className={sectionClass}>
           <h2 className="text-lg font-semibold">Usage cycles</h2>
@@ -266,11 +299,12 @@ function ContainerWorkbench() {
               }}
             />
           )}
-          {data.containerId && (
+          {data.containerId && access.canCreate && (
             <form
               className="space-y-3 border-t pt-4"
               onSubmit={(event) => {
                 event.preventDefault();
+                if (!access.allows('create')) return;
                 void act(async () => {
                   const timestamp = new Date(openingTime);
                   if (!Number.isFinite(timestamp.getTime())) {
@@ -345,111 +379,116 @@ function ContainerWorkbench() {
           )}
           {cycle?.status === 'OPEN' && (
             <>
-              <form onSubmit={record} className="space-y-3 border-t pt-4">
-                <h3 className="font-semibold">Record event</h3>
-                <Label htmlFor="container-event">Event</Label>
-                <select
-                  id="container-event"
-                  className={selectClass}
-                  value={eventType}
-                  onChange={(event) =>
-                    setEventType(
-                      CONTAINER_EVENT_TYPES.find((value) => value === event.target.value) ??
-                        'POSITION_UPDATE'
-                    )
-                  }
-                >
-                  {CONTAINER_EVENT_TYPES.map((value) => (
-                    <option key={value} value={value}>
-                      {readable(value)}
-                    </option>
-                  ))}
-                </select>
-                <Label htmlFor="event-kind">Event certainty</Label>
-                <select
-                  id="event-kind"
-                  className={selectClass}
-                  value={kind}
-                  onChange={(event) =>
-                    setKind(
-                      event.target.value === 'PLANNED'
-                        ? 'PLANNED'
-                        : event.target.value === 'ESTIMATED'
-                          ? 'ESTIMATED'
-                          : 'ACTUAL'
-                    )
-                  }
-                >
-                  <option value="ACTUAL">Actual</option>
-                  <option value="PLANNED">Planned</option>
-                  <option value="ESTIMATED">Estimated</option>
-                </select>
-                <Label htmlFor="event-time">Event time (your local timezone)</Label>
-                <Input
-                  id="event-time"
-                  type="datetime-local"
-                  step={1}
-                  value={eventTime}
-                  onChange={(event) => setEventTime(event.target.value)}
-                  required
-                />
-                <Label htmlFor="event-source">Event source</Label>
-                <Input
-                  id="event-source"
-                  value={eventSource}
-                  onChange={(event) => setEventSource(event.target.value)}
-                  required
-                  maxLength={120}
-                />
-                <Label htmlFor="source-reference">Source reference (optional)</Label>
-                <Input
-                  id="source-reference"
-                  value={sourceReference}
-                  onChange={(event) => setSourceReference(event.target.value)}
-                  maxLength={200}
-                />
-                <Label htmlFor="event-location">Location (optional)</Label>
-                <Input
-                  id="event-location"
-                  value={location}
-                  onChange={(event) => setLocation(event.target.value)}
-                  maxLength={200}
-                />
-                <Label htmlFor="event-evidence">
-                  Evidence note
-                  {eventType === 'RETURN_ACCEPTED' && kind === 'ACTUAL'
-                    ? ' (required for acceptance)'
-                    : ' (optional)'}
-                </Label>
-                <Input
-                  id="event-evidence"
-                  value={evidence}
-                  onChange={(event) => setEvidence(event.target.value)}
-                  maxLength={2000}
-                  required={eventType === 'RETURN_ACCEPTED' && kind === 'ACTUAL'}
-                />
-                <Button type="submit" disabled={busy || !eventSource.trim()}>
-                  Record event
-                </Button>
-              </form>
-              <div className="space-y-3 border-t pt-4">
-                <p className="text-sm text-text-secondary">
-                  Closure checks the complete recorded history for actual empty return and
-                  acceptance. A planned return or delivered shipment is insufficient.
-                </p>
-                <Button
-                  variant="outline"
-                  disabled={busy || data.cyclesLoading || data.eventsLoading}
-                  onClick={() =>
-                    void act(
-                      () => data.closeCycle(cycle),
-                      'Cycle closed after accepted empty return.'
-                    )
-                  }
-                >
-                  Close cycle
-                </Button>
-              </div>
+              {access.canUpdate && (
+                <form onSubmit={record} className="space-y-3 border-t pt-4">
+                  <h3 className="font-semibold">Record event</h3>
+                  <Label htmlFor="container-event">Event</Label>
+                  <select
+                    id="container-event"
+                    className={selectClass}
+                    value={eventType}
+                    onChange={(event) =>
+                      setEventType(
+                        CONTAINER_EVENT_TYPES.find((value) => value === event.target.value) ??
+                          'POSITION_UPDATE'
+                      )
+                    }
+                  >
+                    {CONTAINER_EVENT_TYPES.map((value) => (
+                      <option key={value} value={value}>
+                        {readable(value)}
+                      </option>
+                    ))}
+                  </select>
+                  <Label htmlFor="event-kind">Event certainty</Label>
+                  <select
+                    id="event-kind"
+                    className={selectClass}
+                    value={kind}
+                    onChange={(event) =>
+                      setKind(
+                        event.target.value === 'PLANNED'
+                          ? 'PLANNED'
+                          : event.target.value === 'ESTIMATED'
+                            ? 'ESTIMATED'
+                            : 'ACTUAL'
+                      )
+                    }
+                  >
+                    <option value="ACTUAL">Actual</option>
+                    <option value="PLANNED">Planned</option>
+                    <option value="ESTIMATED">Estimated</option>
+                  </select>
+                  <Label htmlFor="event-time">Event time (your local timezone)</Label>
+                  <Input
+                    id="event-time"
+                    type="datetime-local"
+                    step={1}
+                    value={eventTime}
+                    onChange={(event) => setEventTime(event.target.value)}
+                    required
+                  />
+                  <Label htmlFor="event-source">Event source</Label>
+                  <Input
+                    id="event-source"
+                    value={eventSource}
+                    onChange={(event) => setEventSource(event.target.value)}
+                    required
+                    maxLength={120}
+                  />
+                  <Label htmlFor="source-reference">Source reference (optional)</Label>
+                  <Input
+                    id="source-reference"
+                    value={sourceReference}
+                    onChange={(event) => setSourceReference(event.target.value)}
+                    maxLength={200}
+                  />
+                  <Label htmlFor="event-location">Location (optional)</Label>
+                  <Input
+                    id="event-location"
+                    value={location}
+                    onChange={(event) => setLocation(event.target.value)}
+                    maxLength={200}
+                  />
+                  <Label htmlFor="event-evidence">
+                    Evidence note
+                    {eventType === 'RETURN_ACCEPTED' && kind === 'ACTUAL'
+                      ? ' (required for acceptance)'
+                      : ' (optional)'}
+                  </Label>
+                  <Input
+                    id="event-evidence"
+                    value={evidence}
+                    onChange={(event) => setEvidence(event.target.value)}
+                    maxLength={2000}
+                    required={eventType === 'RETURN_ACCEPTED' && kind === 'ACTUAL'}
+                  />
+                  <Button type="submit" disabled={busy || !eventSource.trim()}>
+                    Record event
+                  </Button>
+                </form>
+              )}
+              {access.canUpdate && (
+                <div className="space-y-3 border-t pt-4">
+                  <p className="text-sm text-text-secondary">
+                    Closure checks the complete recorded history for actual empty return and
+                    acceptance. A planned return or delivered shipment is insufficient.
+                  </p>
+                  <Button
+                    variant="outline"
+                    disabled={busy || data.cyclesLoading || data.eventsLoading}
+                    onClick={() =>
+                      access.allows('update') &&
+                      void act(
+                        () => data.closeCycle(cycle),
+                        'Cycle closed after accepted empty return.'
+                      )
+                    }
+                  >
+                    Close cycle
+                  </Button>
+                </div>
+              )}
             </>
           )}
           {cycle?.status === 'CLOSED' && (