@managemint-solutions/sdk 0.53.0 → 0.55.0

package/README.md

@@ -210,9 +210,10 @@ A task's `task_id` (its per-organization number) is assigned by the database on
 task carries its embedded `status`, `assigned_to`, `project` and `client`. The detail read also carries its `parent`,
 `subtasks` and `related` tasks, read from `task_links` in both directions.
 
-The client decodes `{ mms_id, organization_id }` from the JWT itself and scopes every query
-by `organization_id`. `supabase.supabase` is the raw `@supabase/supabase-js` client
-(`TypedSupabaseClient`) - the escape hatch for queries not yet covered by a resource.
+The client runs as the verified `{ mms_id, organization_id }` it is handed and scopes every
+query by `organization_id`. Staff have a client of their own (see Staff below).
+`supabase.supabase` is the raw `@supabase/supabase-js` client (`TypedSupabaseClient`) - the
+escape hatch for queries not yet covered by a resource.
 
 ## Audit
 
@@ -344,6 +345,77 @@ export class AuthController {
 }
 ```
 
+## Staff
+
+ManageMint Solutions employees sign in to the admin api with a token whose role is `staff`. Their
+client is a `SupabaseStaffClient`, which carries only what the admin api reads: `clients`, `leads`,
+`projects`, `tasks`, `users`, `organizations`, `staff`, `staffPermissions` and
+`userApiCredentials`. A resource not on it is not available to staff.
+
+- **Reads span every organization.** The shared resources drop their organization filter and the
+  `staff` role's policies decide what comes back. The `clients`, `leads`, `projects`, `tasks` and
+  `users` lists embed each row's `organization` (`{ mms_id, name }`) and take an `organization_id`
+  filter through the staff query DTOs (`StaffGetClientsDto`, ...); a tenant's request and response
+  are unchanged. `organizations.list` pages every organization (`search` over name, trading
+  name, email).
+- **Every write is refused** with a `403 Permission Error` before any statement runs, as is the
+  tenant-only `organizations.get()`.
+
+```ts
+import { StaffGetClientsDto, type SupabaseStaffClient as StaffClient } from '@managemint-solutions/sdk';
+import { attachSupabaseStaffRequestContext, SupabaseStaffClient } from '@managemint-solutions/sdk/nest';
+
+// In the admin api's guard: verifies the token (role `staff`, an active `staff` row) and
+// stores the context under its own key, `request.supabaseStaff`.
+const { staff, client } = await attachSupabaseStaffRequestContext(request);
+const flags = await client.staffPermissions.flagsFor(staff.mms_id, 'read_clients'); // is_admin + the flag
+
+// In a controller:
+list(@SupabaseStaffClient() supabase: StaffClient, @Query() query: StaffGetClientsDto) {
+  return supabase.clients.list(query); // every organization's, each row with its organization
+}
+```
+
+`verifyAccessToken` refuses any token whose role is not `authenticated`, so a staff token never
+reaches a tenant route.
+
+Staff and their flags are written on the service client only - staff hold SELECT alone:
+
+```ts
+await service.staff.preRegister({ email, name, created_by: staffId }); // mms_id null until linked
+try {
+  await service.createStaffAuthUser({ email, password }); // role staff: the trigger links the row
+} catch (error) {
+  await service.staff.removePending(email);
+  throw error;
+}
+await service.staff.setActive(staffId, false, byStaffId); // stamps deactivated_at/by
+await service.setAuthUserBanned(staffId, true);           // and ends their sign-ins
+await service.staffPermissions.updateForStaff(staffId, patch, byStaffId); // UpdateStaffPermissionsDto
+```
+
+### User api credentials and emulation
+
+A credential is a client id and secret staff issue for one tenant user. Exchanging it mints that
+user's own token, which the custom access token hook marks `emulated: true` and gives a one-hour
+`exp`; `verifyAccessToken` returns it as `emulated: true` (`false` for a user's own session).
+
+The mint itself lives in the admin api. The SDK calls it is made of:
+
+- `service.userApiCredentials.findByClientId(clientId)` - the credential with its `secret_hash`,
+  or null.
+- `service.emulationHandshakes.open(userId, credentialId)` - a 30-second handshake; returns its id.
+- `service.mintMagicLink(email)`, then `auth.exchangeMagicLinkToken({ token_hash })` - the sign-in
+  the hook spends the handshake on.
+- `service.emulationHandshakes.close(id)` - in a `finally`, whatever happened above.
+- `auth.signOut(accessToken)` afterwards, so only the access token outlives the mint.
+- `service.userApiCredentials.markUsed(credentialId)` - stamps `last_used_at`, unaudited.
+
+`service.userApiCredentials.create` and `revoke` (null when already revoked) are audited against
+the credential's organization as the system and show in the user's history; `secret_hash` is a
+redacted column. Staff list a user's credentials on their own client
+(`supabase.userApiCredentials.listForUser`), through a column grant that never includes the hash.
+
 ## Billing and invoices
 
 Billing is split by who may write. On the caller's client, `supabase.billing` and

package/dist/additional-details/index.d.ts

@@ -1,7 +1,7 @@
 import type { AdditionalDetailSummary, AdditionalDetailsEntity } from '@managemint-solutions/entities/additional-details';
 import type { AddAdditionalDetailsDto, UpdateAdditionalDetailsDto } from '@managemint-solutions/entities/additional-details/dto';
 import { AdditionalDetailsEntityTypes } from '@managemint-solutions/entities/additional-details/enum';
-import type { AuthContext } from '../auth';
+import type { ClientContext } from '../auth';
 import { type AuditResource } from '../audit';
 import type { TypedSupabaseClient } from '../client';
 export * from './dto';
@@ -10,7 +10,7 @@ export declare class AdditionalDetailsResource {
     private readonly supabase;
     private readonly auth;
     private readonly table;
-    constructor(supabase: TypedSupabaseClient, auth: AuthContext, audit: AuditResource);
+    constructor(supabase: TypedSupabaseClient, auth: ClientContext, audit: AuditResource);
     getById(additionalDetailsId: string): Promise<AdditionalDetailsEntity>;
     list(entity: AdditionalDetailsEntityTypes, entityId: string): Promise<AdditionalDetailSummary[]>;
     create(entity: AdditionalDetailsEntityTypes, entityId: string, input: AddAdditionalDetailsDto): Promise<AdditionalDetailsEntity>;

package/dist/additional-details/index.js

@@ -19,6 +19,7 @@ const enum_1 = require("@managemint-solutions/entities/additional-details/enum")
 const enum_2 = require("@managemint-solutions/entities/audit-trail/enum");
 const audit_1 = require("../audit");
 const errors_1 = require("../errors");
+const tenancy_1 = require("../tenancy");
 const won_1 = require("../leads/won");
 const values_1 = require("./values");
 __exportStar(require("./dto"), exports);
@@ -47,10 +48,7 @@ class AdditionalDetailsResource {
         });
     }
     async getById(additionalDetailsId) {
-        const { data, error } = await this.supabase
-            .from('additional_details')
-            .select(ADDITIONAL_DETAILS_SELECT)
-            .eq('organization_id', this.auth.organization_id)
+        const { data, error } = await (0, tenancy_1.scopeToOrganization)(this.supabase.from('additional_details').select(ADDITIONAL_DETAILS_SELECT), this.auth)
             .eq('mms_id', additionalDetailsId)
             .single();
         if (error)
@@ -58,10 +56,7 @@ class AdditionalDetailsResource {
         return withCastValue(data);
     }
     async list(entity, entityId) {
-        const { data, error } = await this.supabase
-            .from('additional_details')
-            .select(ADDITIONAL_DETAILS_SUMMARY_SELECT)
-            .eq('organization_id', this.auth.organization_id)
+        const { data, error } = await (0, tenancy_1.scopeToOrganization)(this.supabase.from('additional_details').select(ADDITIONAL_DETAILS_SUMMARY_SELECT), this.auth)
             .eq('entity_type', entity)
             .eq('entity_id', entityId)
             .order('key', { ascending: false });
@@ -70,11 +65,12 @@ class AdditionalDetailsResource {
         return data.map(withCastValue);
     }
     async create(entity, entityId, input) {
+        const organizationId = (0, tenancy_1.requireOrganization)(this.auth);
         if (entity === enum_1.AdditionalDetailsEntityTypes.LEAD) {
-            await (0, won_1.refuseWonLead)(this.supabase, this.auth.organization_id, entityId);
+            await (0, won_1.refuseWonLead)(this.supabase, organizationId, entityId);
         }
         const row = await this.table.insert({
-            organization_id: this.auth.organization_id,
+            organization_id: organizationId,
             entity_type: entity,
             entity_id: entityId,
             key: input.key,

package/dist/audit/index.d.ts

@@ -2,6 +2,7 @@ import type { SupabaseClient as SupabaseJsClient } from '@supabase/supabase-js';
 import type { AuditTrailEntity } from '@managemint-solutions/entities/audit-trail';
 import { AuditTrailAction, type AuditTrailEntityType } from '@managemint-solutions/entities/audit-trail/enum';
 import type { MmsList } from '@managemint-solutions/entities/common';
+import type { StaffContext } from '../auth';
 import type { GetAuditTrailDto } from './dto';
 export * from './dto';
 /**
@@ -12,6 +13,8 @@ export type AuditActor = {
     mms_id: string | null;
     organization_id: string;
 };
+/** Who a resource runs as: a write's actor, or staff, who read across organizations and write nothing. */
+export type ResourceActor = AuditActor | StaffContext;
 /** A flat database row - always `select('*')`, never an entity shape with embedded joins. */
 export type AuditRow = Record<string, unknown>;
 /**
@@ -45,8 +48,9 @@ export declare const AUDIT_EXCLUDED_COLUMNS: ReadonlySet<string>;
  * `read_logs`, so a value copied into `changes` is a value published to the whole organization -
  * and these are either provider credentials and identifiers (the `paystack_*` customer and
  * subscription codes, card metadata, tokens, an idempotency key that would let a replay be
- * forged) or content the base table deliberately withholds (`authenticated` has no grant on
- * `notifications.rendered_content`, so the rendered email must not arrive by the back door).
+ * forged, an api credential's secret hash) or content the base table deliberately withholds
+ * (`authenticated` has no grant on `notifications.rendered_content`, so the rendered email must
+ * not arrive by the back door).
  * The column still shows up in the trail - that it changed is the point - with both sides
  * replaced by `'[redacted]'`.
  */
@@ -83,7 +87,7 @@ export declare class AuditResource {
     private readonly supabase;
     private readonly actor;
     private readonly onError?;
-    constructor(supabase: SupabaseJsClient, actor: AuditActor, onError?: AuditErrorHandler | undefined);
+    constructor(supabase: SupabaseJsClient, actor: ResourceActor, onError?: AuditErrorHandler | undefined);
     /**
      * Records the entries: held by the current event's batch when there is one (`withAuditBatch`),
      * written straight away when there is not.
@@ -112,7 +116,7 @@ export declare class EntityAuditTrail {
     private readonly supabase;
     private readonly actor;
     private readonly entityType;
-    constructor(supabase: SupabaseJsClient, actor: AuditActor, entityType: AuditTrailEntityType);
+    constructor(supabase: SupabaseJsClient, actor: ResourceActor, entityType: AuditTrailEntityType);
     /**
      * A page of the history. `entity_type` keeps the entries about one kind of record (the record
      * itself, or its notes ...). `search` matches what a change recorded - the stored text, field
@@ -172,9 +176,11 @@ export type AuditedTable = {
     /** Hard delete. Returns the row as it was, so the caller can still act on it. */
     remove(id: string): Promise<AuditRow>;
 };
+/** How a service-client resource reaches an audited table once it knows a row's organization. */
+export type OrganizationTableFactory = (organizationId: string) => AuditedTable;
 /**
  * The audited write helper every resource writes through: it does the pre-read, the write, the
  * diff and the `audit_logs` insert itself, so no feature carries audit code. The write fails
  * loudly (`SupabaseClientError`); only the audit insert is swallowed.
  */
-export declare const auditedTable: (supabase: SupabaseJsClient, actor: AuditActor, audit: AuditResource, options: AuditedTableOptions) => AuditedTable;
+export declare const auditedTable: (supabase: SupabaseJsClient, actor: ResourceActor, audit: AuditResource, options: AuditedTableOptions) => AuditedTable;

package/dist/audit/index.js

@@ -18,6 +18,7 @@ exports.auditedTable = exports.EntityAuditTrail = exports.AuditResource = export
 const node_async_hooks_1 = require("node:async_hooks");
 const enum_1 = require("@managemint-solutions/entities/audit-trail/enum");
 const errors_1 = require("../errors");
+const tenancy_1 = require("../tenancy");
 const transforms_1 = require("../transforms");
 __exportStar(require("./dto"), exports);
 /**
@@ -60,8 +61,9 @@ exports.AUDIT_EXCLUDED_COLUMNS = new Set([
  * `read_logs`, so a value copied into `changes` is a value published to the whole organization -
  * and these are either provider credentials and identifiers (the `paystack_*` customer and
  * subscription codes, card metadata, tokens, an idempotency key that would let a replay be
- * forged) or content the base table deliberately withholds (`authenticated` has no grant on
- * `notifications.rendered_content`, so the rendered email must not arrive by the back door).
+ * forged, an api credential's secret hash) or content the base table deliberately withholds
+ * (`authenticated` has no grant on `notifications.rendered_content`, so the rendered email must
+ * not arrive by the back door).
  * The column still shows up in the trail - that it changed is the point - with both sides
  * replaced by `'[redacted]'`.
  */
@@ -76,6 +78,7 @@ exports.AUDIT_REDACTED_COLUMNS = new Set([
     'access_token',
     'refresh_token',
     'password',
+    'secret_hash',
 ]);
 /** True for a named redacted column, and for every provider-issued `paystack_*` identifier. */
 const isRedactedColumn = (name) => exports.AUDIT_REDACTED_COLUMNS.has(name) || name.startsWith('paystack_');
@@ -280,7 +283,7 @@ class AuditResource {
             // `eq`/`in` return `this`, so the org filter can be reassigned onto the builder.
             let query = this.supabase.from(source.from).select(source.select).in('mms_id', [...new Set(list)]);
             if (source.scoped)
-                query = query.eq('organization_id', this.actor.organization_id);
+                query = (0, tenancy_1.scopeToOrganization)(query, this.actor);
             const { data, error } = await query;
             if (error)
                 throw (0, errors_1.mapPostgrestError)(error);
@@ -329,7 +332,7 @@ class EntityAuditTrail {
                     .or((0, transforms_1.orIlike)(source.search, search))
                     .limit(SEARCH_NAME_LIMIT);
                 if (source.scoped)
-                    lookup = lookup.eq('organization_id', this.actor.organization_id);
+                    lookup = (0, tenancy_1.scopeToOrganization)(lookup, this.actor);
                 const { data: rows, error: lookupError } = await lookup;
                 if (lookupError)
                     throw (0, errors_1.mapPostgrestError)(lookupError);
@@ -344,12 +347,11 @@ class EntityAuditTrail {
             filter = `and(${filter},or(${matches.join(',')}))`;
         }
         // `eq` returns `this`, so the type filter can be reassigned onto the builder.
-        let historyQuery = this.supabase
+        let historyQuery = (0, tenancy_1.scopeToOrganization)(this.supabase
             .from('audit_logs')
             // Exact, not estimated: one record's history is small and index-backed, and the pager
             // must not offer a page that is not there.
-            .select(AUDIT_TRAIL_SELECT, { count: 'exact' })
-            .eq('organization_id', this.actor.organization_id)
+            .select(AUDIT_TRAIL_SELECT, { count: 'exact' }), this.actor)
             // One element, so the record and the search can nest as `and(or(...),or(...))`.
             .or(filter);
         if (query.entity_type)
@@ -381,6 +383,8 @@ const buildUpdate = (supabase, table, id, payload, organizationId) => {
  */
 const auditedTable = (supabase, actor, audit, options) => {
     const scoped = options.scopeByOrganization !== false;
+    // Null for staff too, who never get this far: every write below refuses them first.
+    const organizationFilter = scoped ? actor.organization_id : null;
     // The record a row belongs to: the declared foreign key, or the owner the polymorphic tables
     // (notes, additional details, supporting files) carry in `entity_type`/`entity_id`. A row with
     // a type and no id (statuses and labels name the kind of record they apply to) has no owner.
@@ -397,14 +401,13 @@ const auditedTable = (supabase, actor, audit, options) => {
     const read = async (id) => {
         // `eq` returns `this`, so the org filter can be reassigned onto the builder without a cast.
         let query = supabase.from(options.table).select('*').eq('mms_id', id);
-        if (scoped)
-            query = query.eq('organization_id', actor.organization_id);
+        if (organizationFilter !== null)
+            query = query.eq('organization_id', organizationFilter);
         const { data, error } = await query.single();
         if (error)
             throw (0, errors_1.mapPostgrestError)(error);
         return data;
     };
-    const organizationFilter = scoped ? actor.organization_id : null;
     const updateOf = (id, before, payload) => buildUpdate(supabase, options.table, id, typeof payload === 'function' ? payload(before) : payload, organizationFilter);
     // The changes with the table's untracked columns taken out.
     const tracked = (changes) => Object.fromEntries(Object.entries(changes).filter(([column]) => !options.untracked?.includes(column)));
@@ -422,6 +425,7 @@ const auditedTable = (supabase, actor, audit, options) => {
         });
     };
     const write = async (id, action, payload) => {
+        (0, tenancy_1.requireOrganization)(actor);
         const before = await read(id);
         const { data, error } = await updateOf(id, before, payload).select('*').single();
         if (error)
@@ -433,6 +437,7 @@ const auditedTable = (supabase, actor, audit, options) => {
         return (0, exports.withoutInternalId)(after);
     };
     const writeWhere = async (id, guard, payload) => {
+        (0, tenancy_1.requireOrganization)(actor);
         const before = await read(id);
         // `maybeSingle`, not `single`: matching nothing is the guard doing its job, not an error.
         const { data, error } = await guard(updateOf(id, before, payload))
@@ -449,6 +454,7 @@ const auditedTable = (supabase, actor, audit, options) => {
     };
     return {
         async insert(payload) {
+            (0, tenancy_1.requireOrganization)(actor);
             const { data, error } = await supabase
                 .from(options.table)
                 .insert(payload)
@@ -467,6 +473,7 @@ const auditedTable = (supabase, actor, audit, options) => {
             return (0, exports.withoutInternalId)(row);
         },
         async insertMany(payloads) {
+            (0, tenancy_1.requireOrganization)(actor);
             if (payloads.length === 0)
                 return [];
             const { data, error } = await supabase.from(options.table).insert(payloads).select('*');
@@ -492,10 +499,11 @@ const auditedTable = (supabase, actor, audit, options) => {
             return write(id, action, payload);
         },
         async remove(id) {
+            (0, tenancy_1.requireOrganization)(actor);
             const before = await read(id);
             let query = supabase.from(options.table).delete().eq('mms_id', id);
-            if (scoped)
-                query = query.eq('organization_id', actor.organization_id);
+            if (organizationFilter !== null)
+                query = query.eq('organization_id', organizationFilter);
             const { error } = await query;
             if (error)
                 throw (0, errors_1.mapPostgrestError)(error);

package/dist/auth-client/index.d.ts

@@ -31,6 +31,8 @@ export declare class SupabaseAuthClient {
     sendPasswordResetEmail(input: SendPasswordResetEmailDto, redirectTo: string): Promise<void>;
     exchangeRecoveryToken(input: ExchangeTokenHashDto): Promise<ExchangeTokenResponse>;
     exchangeConfirmToken(input: ExchangeTokenHashDto): Promise<ExchangeTokenResponse>;
+    /** Spends a `mintMagicLink` hash for tokens - how the admin api mints an emulated session. */
+    exchangeMagicLinkToken(input: ExchangeTokenHashDto): Promise<ExchangeTokenResponse>;
     resetPassword(input: ResetPasswordDto): Promise<void>;
     /**
      * Stamps `users.last_logged_in` as the user who just signed in - the users UPDATE policy

package/dist/auth-client/index.js

@@ -102,6 +102,18 @@ class SupabaseAuthClient {
             throw noSession('Token exchange failed: No session data returned');
         return toTokens(data.session);
     }
+    /** Spends a `mintMagicLink` hash for tokens - how the admin api mints an emulated session. */
+    async exchangeMagicLinkToken(input) {
+        const { data, error } = await this.supabase.auth.verifyOtp({
+            type: 'magiclink',
+            token_hash: input.token_hash,
+        });
+        if (error)
+            throw (0, errors_1.mapAuthError)(error);
+        if (!data.session)
+            throw noSession('Token exchange failed: No session data returned');
+        return toTokens(data.session);
+    }
     async resetPassword(input) {
         const { error: sessionError } = await this.supabase.auth.setSession({
             access_token: input.access_token,

package/dist/auth.d.ts

@@ -1,4 +1,5 @@
 import { type SupabaseClient as SupabaseJsClient } from '@supabase/supabase-js';
+import type { StaffEntity } from '@managemint-solutions/entities/staff';
 /**
  * A raw supabase-js client, built the one way the SDK ever needs one: server-side and stateless -
  * nothing is stored, refreshed or read out of a URL - carrying the caller's bearer token when
@@ -10,6 +11,18 @@ export type AuthContext = {
     mms_id: string;
     organization_id: string;
 };
+/**
+ * A ManageMint Solutions staff member: no tenant of their own, so reads span every organization
+ * (the `staff` role's policies decide what they see) and every write is refused.
+ */
+export type StaffContext = {
+    mms_id: string;
+    organization_id: null;
+};
+/** Who a resource the tenant and staff clients share runs as: a tenant user or staff. */
+export type ClientContext = AuthContext | StaffContext;
+/** What a verified staff token resolves to: the GoTrue subject plus their `staff` row. */
+export type VerifiedStaff = Pick<StaffEntity, 'mms_id' | 'email' | 'name'>;
 /**
  * The billing state of the caller's organization, read in the same query as their tenancy so the
  * api's payment and module gates cost no extra round trip. `billing_status` is a
@@ -27,6 +40,8 @@ export type VerifiedAuth = AuthContext & {
     name: string | null;
     surname: string | null;
     organization: VerifiedOrganization;
+    /** True when the token was minted through an emulation handshake; false for the user's own session. */
+    emulated: boolean;
 };
 export type VerifyAccessTokenConfig = {
     url: string;
@@ -50,3 +65,9 @@ export type VerifyAccessTokenConfig = {
  * The token itself is never logged: a failure says only that it was rejected.
  */
 export declare const verifyAccessToken: ({ url, key, accessToken, client, }: VerifyAccessTokenConfig) => Promise<VerifiedAuth>;
+/**
+ * `verifyAccessToken` for a staff session: the same signature check, then the `staff` role
+ * (`auth.users.role`, set by `createStaffAuthUser`), then the `staff` row, read under the staff
+ * member's own RLS.
+ */
+export declare const verifyStaffAccessToken: ({ url, key, accessToken, client, }: VerifyAccessTokenConfig) => Promise<VerifiedStaff>;

package/dist/auth.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.verifyAccessToken = exports.createRawClient = void 0;
+exports.verifyStaffAccessToken = exports.verifyAccessToken = exports.createRawClient = void 0;
 const supabase_js_1 = require("@supabase/supabase-js");
 const errors_1 = require("./errors");
 /**
@@ -32,8 +32,10 @@ const verifyAccessToken = async ({ url, key, accessToken, client = (0, exports.c
     // Verifies the signature locally against the project's JWKS for asymmetric keys, and against
     // the auth server for HS256 projects. Either way the token is checked, not merely decoded.
     const { data, error } = await client.auth.getClaims(accessToken);
-    const mms_id = data?.claims?.sub;
-    if (error || typeof mms_id !== 'string' || mms_id === '') {
+    const claims = data?.claims;
+    const mms_id = claims?.sub;
+    // A staff token is signed by the same project; its role keeps it off every tenant route.
+    if (error || typeof mms_id !== 'string' || mms_id === '' || claims?.role !== 'authenticated') {
         throw authError('Invalid or expired token');
     }
     const { data: profileData, error: profileError } = await client
@@ -70,6 +72,48 @@ const verifyAccessToken = async ({ url, key, accessToken, client = (0, exports.c
             access_expires_at: organization.access_expires_at ?? null,
             modules: organization.modules ?? [],
         },
+        // Stamped by the custom access token hook, inside the signature - a user cannot add it to
+        // their own session.
+        emulated: claims.emulated === true,
     };
 };
 exports.verifyAccessToken = verifyAccessToken;
+/**
+ * `verifyAccessToken` for a staff session: the same signature check, then the `staff` role
+ * (`auth.users.role`, set by `createStaffAuthUser`), then the `staff` row, read under the staff
+ * member's own RLS.
+ */
+const verifyStaffAccessToken = async ({ url, key, accessToken, client = (0, exports.createRawClient)(url, key, accessToken), }) => {
+    const { data, error } = await client.auth.getClaims(accessToken);
+    const claims = data?.claims;
+    const mms_id = claims?.sub;
+    if (error || typeof mms_id !== 'string' || mms_id === '') {
+        throw authError('Invalid or expired token');
+    }
+    if (claims?.role !== 'staff') {
+        throw new errors_1.SupabaseClientError({
+            status: 403,
+            error: 'Authentication Error',
+            message: 'Not a staff session',
+        });
+    }
+    const { data: staffData, error: staffError } = await client
+        .from('staff')
+        .select('email, name, active')
+        .eq('mms_id', mms_id)
+        .maybeSingle();
+    if (staffError)
+        throw (0, errors_1.mapPostgrestError)(staffError);
+    const staff = staffData;
+    if (!staff)
+        throw authError('No staff profile exists for this account');
+    if (staff.active === false) {
+        throw new errors_1.SupabaseClientError({
+            status: 403,
+            error: 'Authentication Error',
+            message: 'Your staff account has been deactivated',
+        });
+    }
+    return { mms_id: mms_id, email: staff.email, name: staff.name };
+};
+exports.verifyStaffAccessToken = verifyStaffAccessToken;

package/dist/clients/dto.d.ts

@@ -1,5 +1,5 @@
 import type { UUID } from 'crypto';
-import type { ClientIdDto as ClientIdDtoType, CreateClientDto as CreateClientDtoType, GetClientsDto as GetClientsDtoType, UpdateClientDto as UpdateClientDtoType } from '@managemint-solutions/entities/clients/dto';
+import type { ClientIdDto as ClientIdDtoType, CreateClientDto as CreateClientDtoType, GetClientsDto as GetClientsDtoType, StaffGetClientsDto as StaffGetClientsDtoType, UpdateClientDto as UpdateClientDtoType } from '@managemint-solutions/entities/clients/dto';
 export declare class GetClientsDto implements Omit<GetClientsDtoType, 'status_id_in'> {
     readonly search?: string | null;
     readonly page: number;
@@ -9,6 +9,10 @@ export declare class GetClientsDto implements Omit<GetClientsDtoType, 'status_id
     readonly status_id_in?: string[] | null;
     readonly archive: boolean;
 }
+/** A staff read across organizations, optionally narrowed to one of them. */
+export declare class StaffGetClientsDto extends GetClientsDto implements Omit<StaffGetClientsDtoType, 'status_id_in'> {
+    readonly organization_id?: string | null;
+}
 export declare class ClientIdDto implements ClientIdDtoType {
     readonly clientId: string;
 }

package/dist/clients/dto.js

@@ -9,7 +9,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UpdateClientDto = exports.CreateClientDto = exports.ClientIdDto = exports.GetClientsDto = void 0;
+exports.UpdateClientDto = exports.CreateClientDto = exports.ClientIdDto = exports.StaffGetClientsDto = exports.GetClientsDto = void 0;
 const class_validator_1 = require("class-validator");
 const class_transformer_1 = require("class-transformer");
 const validators_1 = require("../validators");
@@ -78,6 +78,17 @@ __decorate([
     (0, class_validator_1.IsBoolean)({ message: 'Include archived must be a boolean' }),
     __metadata("design:type", Boolean)
 ], GetClientsDto.prototype, "archive", void 0);
+/** A staff read across organizations, optionally narrowed to one of them. */
+class StaffGetClientsDto extends GetClientsDto {
+    organization_id;
+}
+exports.StaffGetClientsDto = StaffGetClientsDto;
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, validators_1.IsNullable)(),
+    (0, class_validator_1.IsUUID)('7', { message: 'Invalid organization ID format' }),
+    __metadata("design:type", Object)
+], StaffGetClientsDto.prototype, "organization_id", void 0);
 class ClientIdDto {
     clientId;
 }

package/dist/clients/index.d.ts

@@ -1,6 +1,6 @@
 import type { ClientEntity, ClientSummary } from '@managemint-solutions/entities/clients';
 import type { MmsList } from '@managemint-solutions/entities/common';
-import type { AuthContext } from '../auth';
+import type { ClientContext } from '../auth';
 import { EntityAuditTrail, type AuditResource } from '../audit';
 import type { TypedSupabaseClient } from '../client';
 import type { CreateClientDto, GetClientsDto, UpdateClientDto } from './dto';
@@ -11,8 +11,10 @@ export declare class ClientsResource {
     private readonly table;
     /** This record's history - its own rows and the rows that hang off it. */
     readonly audit: EntityAuditTrail;
-    constructor(supabase: TypedSupabaseClient, auth: AuthContext, audit: AuditResource);
-    list(query: GetClientsDto): Promise<MmsList<ClientSummary>>;
+    constructor(supabase: TypedSupabaseClient, auth: ClientContext, audit: AuditResource);
+    list(query: GetClientsDto & {
+        organization_id?: string | null;
+    }): Promise<MmsList<ClientSummary>>;
     getById(clientId: string): Promise<ClientEntity>;
     create(input: CreateClientDto): Promise<ClientEntity>;
     update(clientId: string, input: UpdateClientDto): Promise<ClientEntity>;

package/dist/clients/index.js

@@ -18,6 +18,7 @@ exports.ClientsResource = void 0;
 const enum_1 = require("@managemint-solutions/entities/audit-trail/enum");
 const audit_1 = require("../audit");
 const errors_1 = require("../errors");
+const tenancy_1 = require("../tenancy");
 const transforms_1 = require("../transforms");
 __exportStar(require("./dto"), exports);
 // The public contract is the shared ClientSummary / ClientEntity from
@@ -92,14 +93,16 @@ class ClientsResource {
         const trimmedSearch = query.search?.trim();
         // `order`/`range` return `this`, so the builder stays a filter builder and the conditional
         // filters below can be reassigned onto it without a cast.
-        let clientsQuery = this.supabase
+        let clientsQuery = (0, tenancy_1.scopeToOrganization)(this.supabase
             .from('clients')
-            .select(CLIENT_LIST_SELECT, { count: 'estimated' })
-            .eq('organization_id', this.auth.organization_id)
+            .select((0, tenancy_1.withOrganization)(CLIENT_LIST_SELECT, this.auth), { count: 'estimated' }), this.auth)
             .eq('archived', query.archive)
             .eq('deleted', false)
             .order('created_at', { ascending: false })
             .range(offset, offset + pageSize - 1);
+        if (query.organization_id) {
+            clientsQuery = clientsQuery.eq('organization_id', query.organization_id);
+        }
         if (trimmedSearch) {
             clientsQuery = clientsQuery.or((0, transforms_1.orIlike)(['name', 'email'], trimmedSearch));
         }
@@ -118,18 +121,17 @@ class ClientsResource {
         return (0, transforms_1.toMmsList)(data, page, pageSize, count);
     }
     async getById(clientId) {
-        const { data, error } = await this.supabase
-            .from('clients')
-            .select(CLIENT_DETAIL_SELECT)
-            .eq('organization_id', this.auth.organization_id)
+        const { data, error } = await (0, tenancy_1.scopeToOrganization)(this.supabase.from('clients').select((0, tenancy_1.withOrganization)(CLIENT_DETAIL_SELECT, this.auth)), this.auth)
             .eq('mms_id', clientId)
             .single();
         if (error)
             throw (0, errors_1.mapPostgrestError)(error);
+        // The select carries the staff embed, so its row type is not inferred from the string.
+        const row = data;
         // A soft-deleted client keeps its audit trail but gives up its details.
-        if (data.deleted) {
+        if (row.deleted) {
             return {
-                ...data,
+                ...row,
                 name: '',
                 email: '',
                 phone: '',
@@ -143,7 +145,7 @@ class ClientsResource {
     async create(input) {
         const row = await this.table.insert({
             ...input,
-            organization_id: this.auth.organization_id,
+            organization_id: (0, tenancy_1.requireOrganization)(this.auth),
             created_by: this.auth.mms_id,
             created_at: new Date().toISOString(),
         });

package/dist/emulation-handshakes/index.d.ts

@@ -0,0 +1,16 @@
+import type { TypedSupabaseClient } from '../client';
+/**
+ * `emulation_handshakes`, service client only: proof that a user's next sign-in is the admin
+ * api's own mint, which the custom access token hook spends to mark that token emulated.
+ */
+export declare class EmulationHandshakesResource {
+    private readonly supabase;
+    constructor(supabase: TypedSupabaseClient);
+    /**
+     * Opens a handshake for `userId`'s next sign-in, good for thirty seconds. Returns its id. The
+     * credential is the one a public mint presented; a staff member's own mint has none.
+     */
+    open(userId: string, credentialId: string | null): Promise<number>;
+    /** Deletes the handshake, spent or not, once the mint is over. */
+    close(id: number): Promise<void>;
+}