|
| 1 | +# Spacecat Shared - MacGiver Client |
| 2 | + |
| 3 | +A thin client over the MacGiver FACS `/api/facs/permissions/check` endpoint for |
| 4 | +evaluating a single user's permissions within an IMS organization. Consumed by |
| 5 | +`spacecat-auth-service` at login to mint the `facs_permissions` JWT claim. |
| 6 | + |
| 7 | +## Installation |
| 8 | + |
| 9 | +```bash |
| 10 | +npm install @adobe/spacecat-shared-mac-giver-client |
| 11 | +``` |
| 12 | + |
| 13 | +## Usage |
| 14 | + |
| 15 | +### Create from a Universal context |
| 16 | + |
| 17 | +The wrapper attaches the client to `context.macGiverClient` (place it after the |
| 18 | +IMS client wrapper, since it requires `context.imsClient`): |
| 19 | + |
| 20 | +```javascript |
| 21 | +import { macGiverClientWrapper } from '@adobe/spacecat-shared-mac-giver-client'; |
| 22 | + |
| 23 | +export const main = wrap(run) |
| 24 | + .with(macGiverClientWrapper); |
| 25 | +``` |
| 26 | + |
| 27 | +Or construct directly: |
| 28 | + |
| 29 | +```javascript |
| 30 | +import { MacGiverClient } from '@adobe/spacecat-shared-mac-giver-client'; |
| 31 | + |
| 32 | +const client = MacGiverClient.createFrom(context); |
| 33 | +``` |
| 34 | + |
| 35 | +### Check an explicit list of permissions |
| 36 | + |
| 37 | +Returns the subset of the requested permissions that are allowed: |
| 38 | + |
| 39 | +```javascript |
| 40 | +const allowed = await client.checkListOfPermission({ |
| 41 | + userId: '17837D23...@AdobeID', |
| 42 | + imsOrgId: 'AAAA...CCCC@AdobeOrg', |
| 43 | + permissions: ['llmo/can_view', 'llmo/can_manage_users'], |
| 44 | +}); |
| 45 | +// → ['llmo/can_view'] |
| 46 | +``` |
| 47 | + |
| 48 | +### Check all permissions in a namespace |
| 49 | + |
| 50 | +Evaluates every permission defined in the given namespaces and returns the |
| 51 | +allowed subset: |
| 52 | + |
| 53 | +```javascript |
| 54 | +const allowed = await client.checkAllPermission({ |
| 55 | + userId: '17837D23...@AdobeID', |
| 56 | + imsOrgId: 'AAAA...CCCC@AdobeOrg', |
| 57 | + namespaces: ['llmo'], |
| 58 | +}); |
| 59 | +// → ['llmo/can_view', 'llmo/can_manage_users'] |
| 60 | +``` |
| 61 | + |
| 62 | +## Behavior |
| 63 | + |
| 64 | +- **Evaluated, none granted** — a `2xx` `SUCCESS` response with no `allowed: true` |
| 65 | + entries (or a non-`SUCCESS` status) returns `[]`. |
| 66 | +- **Could not evaluate** — a non-`2xx` response or transport failure **throws** |
| 67 | + (with a `tag: 'macgiver'` warning), so callers can fail-safe (e.g. omit the |
| 68 | + `facs_permissions` claim) rather than confusing an outage with "no permissions". |
| 69 | +- The request is bounded by `AbortSignal.timeout` (default `5000` ms, tunable via |
| 70 | + the `MACGIVER_TIMEOUT_MS` env var) since MacGiver sits on the login critical path. |
| 71 | + |
| 72 | +## Configuration |
| 73 | + |
| 74 | +| Env var | Default | Description | |
| 75 | +|---|---|---| |
| 76 | +| `MACGIVER_BASE_URL` | `http://localhost:8080` | MacGiver service base URL. | |
| 77 | +| `MACGIVER_TIMEOUT_MS` | `5000` | Per-request timeout in milliseconds. | |
0 commit comments