@managemint-solutions/sdk 0.52.0 → 0.54.0

package/dist/audit/index.js

@@ -14,9 +14,11 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.auditedTable = exports.AuditResource = exports.snapshotChanges = exports.diffChanges = exports.isRedactedColumn = exports.AUDIT_REDACTED_COLUMNS = exports.AUDIT_EXCLUDED_COLUMNS = exports.withoutInternalId = void 0;
+exports.auditedTable = exports.EntityAuditTrail = exports.AuditResource = exports.withAuditBatch = exports.snapshotChanges = exports.diffChanges = exports.isRedactedColumn = exports.AUDIT_REDACTED_COLUMNS = exports.AUDIT_EXCLUDED_COLUMNS = exports.withoutInternalId = void 0;
+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);
 /**
@@ -59,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]'`.
  */
@@ -75,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_');
@@ -121,6 +125,34 @@ const snapshotChanges = (row, side) => {
     return changes;
 };
 exports.snapshotChanges = snapshotChanges;
+/**
+ * Where each table's readable name comes from (`select`, `name`) and which columns a history
+ * search matches it by (`search`). People are read through `user_profiles`, which exposes
+ * nothing beyond the name; the view carries no `organization_id`, but it runs as the invoker,
+ * so the users RLS keeps it to the caller's tenant.
+ */
+const NAME_SOURCES = {
+    users: {
+        from: 'user_profiles',
+        select: 'mms_id, name, surname',
+        search: ['name', 'surname'],
+        scoped: false,
+        name: (row) => [row.name, row.surname].filter(Boolean).join(' '),
+    },
+    statuses: { from: 'statuses', select: 'mms_id, label', search: ['label'], scoped: true, name: (row) => String(row.label) },
+    clients: { from: 'clients', select: 'mms_id, name', search: ['name'], scoped: true, name: (row) => String(row.name) },
+    projects: { from: 'projects', select: 'mms_id, name', search: ['name'], scoped: true, name: (row) => String(row.name) },
+    tasks: {
+        from: 'tasks',
+        select: 'mms_id, task_id, name',
+        search: ['name'],
+        scoped: true,
+        name: (row) => `TASK-${row.task_id} ${row.name}`,
+    },
+    leave_types: { from: 'leave_types', select: 'mms_id, name', search: ['name'], scoped: true, name: (row) => String(row.name) },
+};
+// How many matching names per table a history search widens itself by.
+const SEARCH_NAME_LIMIT = 20;
 const AUDIT_TRAIL_SELECT = `
         mms_id,
         created_at,
@@ -132,9 +164,62 @@ const AUDIT_TRAIL_SELECT = `
         related_entity_id,
         changes
       `;
+/** The batch the current event records into, when there is one - see `withAuditBatch`. */
+const auditBatch = new node_async_hooks_1.AsyncLocalStorage();
+/**
+ * Runs `work` as one event: every audit entry recorded inside it - by any client or service
+ * scope - is held, then written once it settles (or throws, since its writes still happened)
+ * as **one row per record**. The api wraps each request in it, so a save that writes a task and
+ * its labels, or a webhook that moves an organization twice, logs one row, whatever code wrote it.
+ */
+const withAuditBatch = async (work) => {
+    const pending = [];
+    try {
+        return await auditBatch.run(pending, work);
+    }
+    finally {
+        // Entries about the same record fold together: each field keeps its first `old` and its
+        // last `new`. A record created in the event stays created; otherwise a lifecycle move
+        // (archive, delete, restore ...) says more than an update. The first writer writes the row.
+        const merged = new Map();
+        for (const { entry, writer } of pending) {
+            const key = `${entry.entityType}:${entry.entityId}`;
+            const earlier = merged.get(key);
+            if (!earlier) {
+                merged.set(key, { entry: { ...entry, changes: { ...entry.changes } }, writer });
+                continue;
+            }
+            for (const [field, change] of Object.entries(entry.changes)) {
+                const first = earlier.entry.changes[field];
+                earlier.entry.changes[field] = { old: first ? first.old : change.old, new: change.new };
+            }
+            if (earlier.entry.action !== enum_1.AuditTrailAction.INSERT && entry.action !== enum_1.AuditTrailAction.UPDATE) {
+                earlier.entry.action = entry.action;
+            }
+            earlier.entry.relatedEntityType ??= entry.relatedEntityType;
+            earlier.entry.relatedEntityId ??= entry.relatedEntityId;
+        }
+        const byWriter = new Map();
+        for (const { entry, writer } of merged.values()) {
+            // A field that ended where it started is no change (a redacted one reads the same on both
+            // sides by design, so it stays).
+            for (const [field, change] of Object.entries(entry.changes)) {
+                if (change.old !== REDACTED && JSON.stringify(change.old) === JSON.stringify(change.new)) {
+                    delete entry.changes[field];
+                }
+            }
+            // Updates that cancelled out changed nothing: no row.
+            if (entry.action === enum_1.AuditTrailAction.UPDATE && Object.keys(entry.changes).length === 0)
+                continue;
+            byWriter.set(writer, [...(byWriter.get(writer) ?? []), entry]);
+        }
+        await Promise.all([...byWriter].map(([writer, entries]) => writer.write(entries)));
+    }
+};
+exports.withAuditBatch = withAuditBatch;
 /**
- * The `audit_logs` table. Reads are the audit trail endpoint; writes go through `record`, which
- * every audited write calls for itself - no feature ever writes an audit line by hand.
+ * The `audit_logs` writer. Every audited write calls `record` for itself - no feature ever
+ * writes an audit line by hand. Reads are per record, through `EntityAuditTrail`.
  */
 class AuditResource {
     supabase;
@@ -146,14 +231,27 @@ class AuditResource {
         this.onError = onError;
     }
     /**
-     * Writes the audit row(s) - one insert, however many entries. **Never throws**: a logging
-     * problem must not fail the business write, so a failure goes to `onAuditError`
-     * (default `console.error`) instead.
+     * Records the entries: held by the current event's batch when there is one (`withAuditBatch`),
+     * written straight away when there is not.
      */
     async record(entry) {
         const entries = Array.isArray(entry) ? entry : [entry];
         if (entries.length === 0)
             return;
+        const batch = auditBatch.getStore();
+        if (batch) {
+            batch.push(...entries.map((item) => ({ entry: item, writer: this })));
+            return;
+        }
+        await this.write(entries);
+    }
+    /**
+     * Inserts the audit row(s) - one insert, however many entries. **Never throws**: a logging
+     * problem must not fail the business write, so a failure goes to `onAuditError`
+     * (default `console.error`) instead. Called by `record`, and by `withAuditBatch` when it
+     * writes what it held.
+     */
+    async write(entries) {
         try {
             const { error } = await this.supabase.from('audit_logs').insert(entries.map((item) => ({
                 created_by: this.actor.mms_id,
@@ -173,43 +271,103 @@ class AuditResource {
             handle(error, entries);
         }
     }
-    async list(query) {
+    /**
+     * Readable names for the ids a page of history holds (`status_id`, `assigned_to_id`, ...),
+     * keyed by id: one query per table asked about. An id with no row - the record was hard
+     * deleted - is simply absent, and the caller says so.
+     */
+    async names(ids) {
+        const lookups = Object.entries(ids).filter(([, list]) => list.length > 0);
+        const pages = await Promise.all(lookups.map(async ([table, list]) => {
+            const source = NAME_SOURCES[table];
+            // `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 = (0, tenancy_1.scopeToOrganization)(query, this.actor);
+            const { data, error } = await query;
+            if (error)
+                throw (0, errors_1.mapPostgrestError)(error);
+            return (data ?? []).map((row) => [String(row.mms_id), source.name(row)]);
+        }));
+        return Object.fromEntries(pages.flat());
+    }
+}
+exports.AuditResource = AuditResource;
+/**
+ * One record's history: the rows about the record itself and every row that hangs off it (a
+ * note, a file, a timesheet entry, a user's permissions), newest first. Each resource with a
+ * record page exposes one as `audit`, so a client's history is `supabase.clients.audit.list(id)`.
+ */
+class EntityAuditTrail {
+    supabase;
+    actor;
+    entityType;
+    constructor(supabase, actor, entityType) {
+        this.supabase = supabase;
+        this.actor = actor;
+        this.entityType = entityType;
+    }
+    /**
+     * 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
+     * names included - and, because a foreign key is stored as an id, also any change holding the
+     * id of a person, status, client, project, task or leave type whose name matches, and any
+     * change made by a person whose name matches.
+     */
+    async list(entityId, query) {
         const page = query.page;
         const pageSize = query.page_size;
         const offset = (page - 1) * pageSize;
-        // `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 auditTrailQuery = this.supabase
+        // `entityId` is interpolated into the filter: callers pass a uuid their route DTO has
+        // already validated. The two halves are served by the by-entity and by-related indexes.
+        let filter = `or(and(entity_type.eq.${this.entityType},entity_id.eq.${entityId}),` +
+            `and(related_entity_type.eq.${this.entityType},related_entity_id.eq.${entityId}))`;
+        const search = query.search?.trim();
+        if (search) {
+            const named = await Promise.all(Object.entries(NAME_SOURCES).map(async ([table, source]) => {
+                // `or`/`eq` return `this`, so the org filter can be reassigned onto the builder.
+                let lookup = this.supabase
+                    .from(source.from)
+                    .select('mms_id')
+                    .or((0, transforms_1.orIlike)(source.search, search))
+                    .limit(SEARCH_NAME_LIMIT);
+                if (source.scoped)
+                    lookup = (0, tenancy_1.scopeToOrganization)(lookup, this.actor);
+                const { data: rows, error: lookupError } = await lookup;
+                if (lookupError)
+                    throw (0, errors_1.mapPostgrestError)(lookupError);
+                return { table, ids: (rows ?? []).map((row) => row.mms_id) };
+            }));
+            const people = named.find((match) => match.table === 'users')?.ids ?? [];
+            const matches = [
+                `search_text.ilike.${(0, transforms_1.ilikeContains)(search)}`,
+                ...named.flatMap((match) => match.ids.map((id) => `search_text.ilike.${(0, transforms_1.ilikeContains)(id)}`)),
+                ...(people.length > 0 ? [`created_by.in.(${people.join(',')})`] : []),
+            ];
+            filter = `and(${filter},or(${matches.join(',')}))`;
+        }
+        // `eq` returns `this`, so the type filter can be reassigned onto the builder.
+        let historyQuery = (0, tenancy_1.scopeToOrganization)(this.supabase
             .from('audit_logs')
-            .select(AUDIT_TRAIL_SELECT, { count: 'estimated' })
-            .eq('organization_id', this.actor.organization_id)
+            // 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' }), this.actor)
+            // One element, so the record and the search can nest as `and(or(...),or(...))`.
+            .or(filter);
+        if (query.entity_type)
+            historyQuery = historyQuery.eq('entity_type', query.entity_type);
+        const { data, error, count } = await historyQuery
             .order('created_at', { ascending: false })
+            // A multi-row insert stamps every row with the same `created_at`; the time-ordered v7
+            // `mms_id` keeps the pages stable.
+            .order('mms_id', { ascending: false })
             .range(offset, offset + pageSize - 1);
-        if (query.created_after) {
-            auditTrailQuery = auditTrailQuery.gte('created_at', query.created_after);
-        }
-        if (query.created_before) {
-            auditTrailQuery = auditTrailQuery.lte('created_at', query.created_before);
-        }
-        if (query.created_by) {
-            auditTrailQuery = auditTrailQuery.eq('created_by', query.created_by);
-        }
-        if (query.action) {
-            auditTrailQuery = auditTrailQuery.eq('action', query.action);
-        }
-        if (query.entity_type) {
-            auditTrailQuery = auditTrailQuery.eq('entity_type', query.entity_type);
-        }
-        if (query.entity_id) {
-            auditTrailQuery = auditTrailQuery.eq('entity_id', query.entity_id);
-        }
-        const { data, error, count } = await auditTrailQuery;
         if (error)
             throw (0, errors_1.mapPostgrestError)(error);
         return (0, transforms_1.toMmsList)(data, page, pageSize, count);
     }
 }
-exports.AuditResource = AuditResource;
+exports.EntityAuditTrail = EntityAuditTrail;
 /** The keyed update every audited write builds, before any caller-supplied guard. */
 const buildUpdate = (supabase, table, id, payload, organizationId) => {
     // `eq` returns `this`, so the org filter can be reassigned onto the builder without a cast.
@@ -225,32 +383,49 @@ const buildUpdate = (supabase, table, id, payload, organizationId) => {
  */
 const auditedTable = (supabase, actor, audit, options) => {
     const scoped = options.scopeByOrganization !== false;
-    // Tables that hang off another entity (notes, additional details, supporting files) carry the
-    // owner in `entity_type`/`entity_id`; the audit row records it as the related entity.
-    const relatedOf = (row) => ({
-        relatedEntityType: row.entity_type ?? null,
-        relatedEntityId: row.entity_id ?? null,
-    });
+    // 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.
+    const relatedOf = (row) => {
+        const { related } = options;
+        const relatedEntityId = row[related?.column ?? 'entity_id'] ?? null;
+        if (!relatedEntityId)
+            return { relatedEntityType: null, relatedEntityId: null };
+        return {
+            relatedEntityType: related?.entityType ?? row.entity_type,
+            relatedEntityId,
+        };
+    };
     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);
-    const recordWrite = (id, action, before, after) => audit.record({
-        action,
-        entityType: options.entityType,
-        entityId: id,
-        changes: (0, exports.diffChanges)(before, after),
-        ...relatedOf(before),
-    });
+    // The changes with the table's untracked columns taken out.
+    const tracked = (changes) => Object.fromEntries(Object.entries(changes).filter(([column]) => !options.untracked?.includes(column)));
+    // An update that changed nothing tracked is not an event: no row.
+    const recordWrite = async (id, action, before, after) => {
+        const changes = tracked((0, exports.diffChanges)(before, after));
+        if (action === enum_1.AuditTrailAction.UPDATE && Object.keys(changes).length === 0)
+            return;
+        await audit.record({
+            action,
+            entityType: options.entityType,
+            entityId: id,
+            changes,
+            ...relatedOf(before),
+        });
+    };
     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)
@@ -262,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))
@@ -278,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)
@@ -290,12 +467,13 @@ const auditedTable = (supabase, actor, audit, options) => {
                 action: enum_1.AuditTrailAction.INSERT,
                 entityType: options.entityType,
                 entityId: row.mms_id,
-                changes: (0, exports.snapshotChanges)(row, 'new'),
+                changes: tracked((0, exports.snapshotChanges)(row, 'new')),
                 ...relatedOf(row),
             });
             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('*');
@@ -306,7 +484,7 @@ const auditedTable = (supabase, actor, audit, options) => {
                 action: enum_1.AuditTrailAction.INSERT,
                 entityType: options.entityType,
                 entityId: row.mms_id,
-                changes: (0, exports.snapshotChanges)(row, 'new'),
+                changes: tracked((0, exports.snapshotChanges)(row, 'new')),
                 ...relatedOf(row),
             })));
             return rows.map(exports.withoutInternalId);
@@ -321,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);
@@ -332,7 +511,7 @@ const auditedTable = (supabase, actor, audit, options) => {
                 action: enum_1.AuditTrailAction.DELETE,
                 entityType: options.entityType,
                 entityId: id,
-                changes: (0, exports.snapshotChanges)(before, 'old'),
+                changes: tracked((0, exports.snapshotChanges)(before, 'old')),
                 ...relatedOf(before),
             });
             return (0, exports.withoutInternalId)(before);

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,7 +1,7 @@
 import type { ClientEntity, ClientSummary } from '@managemint-solutions/entities/clients';
 import type { MmsList } from '@managemint-solutions/entities/common';
-import type { AuthContext } from '../auth';
-import { type AuditResource } from '../audit';
+import type { ClientContext } from '../auth';
+import { EntityAuditTrail, type AuditResource } from '../audit';
 import type { TypedSupabaseClient } from '../client';
 import type { CreateClientDto, GetClientsDto, UpdateClientDto } from './dto';
 export * from './dto';
@@ -9,8 +9,12 @@ export declare class ClientsResource {
     private readonly supabase;
     private readonly auth;
     private readonly table;
-    constructor(supabase: TypedSupabaseClient, auth: AuthContext, audit: AuditResource);
-    list(query: GetClientsDto): Promise<MmsList<ClientSummary>>;
+    /** This record's history - its own rows and the rows that hang off it. */
+    readonly audit: EntityAuditTrail;
+    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>;