@shipfox/api-auth 9.3.0 → 10.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-auth",
   "license": "MIT",
-  "version": "9.3.0",
+  "version": "10.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -27,19 +27,19 @@
     "drizzle-orm": "^0.45.2",
     "zod": "^4.4.3",
     "@shipfox/api-common-dto": "9.2.0",
-    "@shipfox/api-auth-context": "9.3.0",
-    "@shipfox/api-auth-dto": "9.3.0",
-    "@shipfox/api-email-challenges": "1.1.5",
-    "@shipfox/api-workspaces-dto": "9.3.0",
+    "@shipfox/api-auth-context": "10.0.0",
+    "@shipfox/api-auth-dto": "10.0.0",
+    "@shipfox/api-email-challenges": "1.1.6",
+    "@shipfox/api-workspaces-dto": "10.0.0",
     "@shipfox/inter-module": "0.2.2",
     "@shipfox/config": "1.2.4",
     "@shipfox/node-drizzle": "0.3.4",
     "@shipfox/node-auth-root-key": "0.2.3",
-    "@shipfox/node-fastify": "0.3.4",
+    "@shipfox/node-fastify": "0.4.0",
     "@shipfox/node-jwt": "0.3.2",
     "@shipfox/node-email": "0.3.4",
     "@shipfox/node-mailer": "0.2.4",
-    "@shipfox/node-module": "1.0.3",
+    "@shipfox/node-module": "1.0.4",
     "@shipfox/node-opentelemetry": "0.6.3",
     "@shipfox/node-outbox": "0.2.6",
     "@shipfox/node-postgres": "0.4.4",

package/src/core/administration.ts

@@ -1,15 +1,21 @@
 import {createHash, timingSafeEqual} from 'node:crypto';
 import type {AdminRole} from '@shipfox/api-auth-dto';
 import {createAdministrationActionEvent} from '@shipfox/api-common-dto';
+import type {TimestampIdCursor} from '@shipfox/node-drizzle';
 import {config} from '#config.js';
 import {
   bootstrapFirstAdminOwner as bootstrapFirstAdminOwnerInDb,
   grantAdminRoleWithAudit,
-  listAdminGrants,
+  listAdminGrantSummaries,
   revokeAdminGrantWithAudit,
 } from '#db/admin-grants.js';
+import {findAdministratorUser as findAdministratorUserInDb} from '#db/admin-users.js';
 import {requireAdminRole} from './admin-role.js';
 import type {AdminGrant} from './entities/admin-grant.js';
+import type {
+  AdministratorGrantSummary,
+  AdministratorUserSummary,
+} from './entities/administrator-read-model.js';
 import {
   AdminBootstrapClosedError,
   AdminGrantAlreadyExistsError,
@@ -21,6 +27,7 @@ import {
 } from './errors.js';
 
 const ADMIN_OWNER_ROLE: AdminRole = 'admin-owner';
+const ADMIN_OBSERVER_ROLE: AdminRole = 'admin-observer';
 const BOOTSTRAP_COMMAND = 'auth.admin_grant.bootstrap';
 const GRANT_COMMAND = 'auth.admin_grant.grant';
 const REVOKE_COMMAND = 'auth.admin_grant.revoke';
@@ -98,9 +105,43 @@ export async function bootstrapFirstAdminOwner(
   });
 }
 
-export async function listAdministratorGrants(params: {actorId: string}): Promise<AdminGrant[]> {
-  await requireAdminRole({userId: params.actorId, minimumRole: ADMIN_OWNER_ROLE});
-  return await listAdminGrants();
+export async function findAdministratorUserSummary(
+  params: {actorId: string} & ({id: string; email?: never} | {email: string; id?: never}),
+): Promise<AdministratorUserSummary | undefined> {
+  await requireAdminRole({userId: params.actorId, minimumRole: ADMIN_OBSERVER_ROLE});
+
+  const user = await findAdministratorUserInDb(
+    'id' in params ? {id: params.id} : {email: params.email},
+  );
+  if (!user) return undefined;
+
+  return user;
+}
+
+export async function listAdministratorGrantSummaries(params: {
+  actorId: string;
+  limit: number;
+  cursor?: TimestampIdCursor;
+}): Promise<{
+  grants: AdministratorGrantSummary[];
+  nextCursor: TimestampIdCursor | null;
+}> {
+  await requireAdminRole({userId: params.actorId, minimumRole: ADMIN_OBSERVER_ROLE});
+
+  const result = await listAdminGrantSummaries({
+    limit: params.limit,
+    ...(params.cursor ? {cursor: params.cursor} : {}),
+  });
+  return {
+    grants: result.rows.map((row) => ({
+      grantId: row.id,
+      role: row.role,
+      createdAt: row.createdAt,
+      revokedAt: row.revokedAt,
+      user: row.user,
+    })),
+    nextCursor: result.nextCursor,
+  };
 }
 
 export async function grantAdministratorRole(

package/src/core/entities/administrator-read-model.ts

@@ -0,0 +1,23 @@
+import type {AdminRole} from '@shipfox/api-auth-dto';
+import type {UserStatus} from './user.js';
+
+export interface AdministratorUserIdentity {
+  id: string;
+  email: string;
+  name: string | null;
+  status: UserStatus;
+}
+
+export interface AdministratorUserSummary extends AdministratorUserIdentity {
+  emailVerifiedAt: Date | null;
+  createdAt: Date;
+  adminRole: AdminRole | null;
+}
+
+export interface AdministratorGrantSummary {
+  grantId: string;
+  role: AdminRole;
+  createdAt: Date;
+  revokedAt: Date | null;
+  user: AdministratorUserIdentity;
+}

package/src/db/admin-grants.test.ts

@@ -1,12 +1,7 @@
 import {eq} from 'drizzle-orm';
 import {LastAdminOwnerError} from '#core/errors.js';
 import {userFactory} from '#test/index.js';
-import {
-  createAdminGrant,
-  findCurrentAdminRole,
-  listAdminGrants,
-  revokeAdminGrant,
-} from './admin-grants.js';
+import {createAdminGrant, findCurrentAdminRole, revokeAdminGrant} from './admin-grants.js';
 import {db} from './db.js';
 import {users} from './schema/users.js';
 
@@ -18,7 +13,6 @@ describe('admin grants db', () => {
 
     expect(observer.userId).toBe(user.id);
     expect(await findCurrentAdminRole({userId: user.id})).toBe('admin-operator');
-    expect((await listAdminGrants()).filter((grant) => grant.userId === user.id)).toHaveLength(2);
   });
 
   test('does not evaluate revoked grants or grants for suspended users', async () => {

package/src/db/admin-grants.ts

@@ -3,10 +3,16 @@ import type {
   AdministrationActionEvent,
   AdministrationActionEventMap,
 } from '@shipfox/api-common-dto';
+import {
+  paginateTimestampIdRows,
+  type TimestampIdCursor,
+  timestampIdCursorWhere,
+} from '@shipfox/node-drizzle';
 import {writeOutboxEvent} from '@shipfox/node-outbox';
-import {and, asc, eq, isNull, sql} from 'drizzle-orm';
+import {and, desc, eq, isNull, sql} from 'drizzle-orm';
 import {highestAdminRole} from '#core/admin-role-model.js';
 import type {AdminGrant} from '#core/entities/admin-grant.js';
+import type {AdministratorGrantSummary} from '#core/entities/administrator-read-model.js';
 import {
   AdminBootstrapClosedError,
   AdminGrantAlreadyExistsError,
@@ -42,9 +48,51 @@ export async function createAdminGrant(params: CreateAdminGrantParams): Promise<
   return toAdminGrant(row);
 }
 
-export async function listAdminGrants(): Promise<AdminGrant[]> {
-  const rows = await db().select().from(adminGrants).orderBy(asc(adminGrants.createdAt));
-  return rows.map(toAdminGrant);
+export interface AdministratorGrantSummaryRecord {
+  id: string;
+  role: AdminRole;
+  createdAt: Date;
+  revokedAt: Date | null;
+  user: AdministratorGrantSummary['user'];
+}
+
+export async function listAdminGrantSummaries(params: {
+  limit: number;
+  cursor?: TimestampIdCursor;
+}): Promise<{
+  rows: AdministratorGrantSummaryRecord[];
+  nextCursor: TimestampIdCursor | null;
+}> {
+  const cursorCondition = timestampIdCursorWhere({
+    timestampColumn: adminGrants.createdAt,
+    idColumn: adminGrants.id,
+    cursor: params.cursor,
+  });
+  const conditions = cursorCondition ? [cursorCondition] : [];
+  const rows = await db()
+    .select({
+      id: adminGrants.id,
+      role: adminGrants.role,
+      createdAt: adminGrants.createdAt,
+      revokedAt: adminGrants.revokedAt,
+      user: {
+        id: users.id,
+        email: users.email,
+        name: users.name,
+        status: users.status,
+      },
+    })
+    .from(adminGrants)
+    .innerJoin(users, eq(adminGrants.userId, users.id))
+    .where(and(...conditions))
+    .orderBy(desc(adminGrants.createdAt), desc(adminGrants.id))
+    .limit(params.limit + 1);
+
+  const page = paginateTimestampIdRows({rows, limit: params.limit, timestampKey: 'createdAt'});
+  return {
+    rows: page.pageRows,
+    nextCursor: page.nextCursor,
+  };
 }
 
 export async function findCurrentAdminRole(params: {userId: string}): Promise<AdminRole | null> {

package/src/db/admin-users.ts

@@ -0,0 +1,58 @@
+import type {AdminRole} from '@shipfox/api-auth-dto';
+import {and, eq, isNull} from 'drizzle-orm';
+import {highestAdminRole} from '#core/admin-role-model.js';
+import type {UserStatus} from '#core/entities/user.js';
+import {db} from './db.js';
+import {adminGrants} from './schema/admin-grants.js';
+import {users} from './schema/users.js';
+
+export interface AdministratorUserRecord {
+  id: string;
+  email: string;
+  name: string | null;
+  emailVerifiedAt: Date | null;
+  status: UserStatus;
+  createdAt: Date;
+  adminRole: AdminRole | null;
+}
+
+type AdministratorUserLookup = {id: string; email?: never} | {email: string; id?: never};
+
+export async function findAdministratorUser(
+  params: AdministratorUserLookup,
+): Promise<AdministratorUserRecord | undefined> {
+  const identifier = 'id' in params ? eq(users.id, params.id) : eq(users.email, params.email);
+  const rows = await db()
+    .select({
+      id: users.id,
+      email: users.email,
+      name: users.name,
+      emailVerifiedAt: users.emailVerifiedAt,
+      status: users.status,
+      createdAt: users.createdAt,
+      adminRole: adminGrants.role,
+    })
+    .from(users)
+    .leftJoin(
+      adminGrants,
+      and(
+        eq(adminGrants.userId, users.id),
+        isNull(adminGrants.revokedAt),
+        eq(users.status, 'active'),
+      ),
+    )
+    .where(identifier);
+
+  const first = rows[0];
+  if (!first) return undefined;
+
+  return {
+    id: first.id,
+    email: first.email,
+    name: first.name,
+    emailVerifiedAt: first.emailVerifiedAt,
+    status: first.status,
+    createdAt: first.createdAt,
+    adminRole: highestAdminRole(rows.flatMap(({adminRole}) => (adminRole ? [adminRole] : []))),
+  };
+}

package/src/index.test.ts

@@ -78,7 +78,7 @@ describe('authModule', () => {
         getWorkspaceOperatingState: vi.fn(),
       },
     });
-    expect(module.routes).toHaveLength(2);
+    expect(module.routes).toHaveLength(3);
     const signupPolicy = buildAuthRoutes.mock.calls[0]?.[2];
 
     expect(signupPolicy).toEqual(expect.objectContaining({isSignupAllowed: expect.any(Function)}));

package/src/index.ts

@@ -17,7 +17,10 @@ import {createLeaseTokenAuthMethod} from '#presentation/auth/lease-token-auth.js
 import {createRunnerSessionAuthMethod} from '#presentation/auth/runner-session-auth.js';
 import {createAuthE2eRoutes} from '#presentation/e2eRoutes/index.js';
 import {createAuthInterModulePresentation} from '#presentation/inter-module.js';
-import {administrationRoutes} from '#presentation/routes/administration.js';
+import {
+  administrationRoutes,
+  administrationUserRoutes,
+} from '#presentation/routes/administration.js';
 import {buildAuthRoutes} from '#presentation/routes/index.js';
 import {onPasswordResetSendRequested} from '#presentation/subscribers/index.js';
 import {passwordLoginMethods} from './login-methods.js';
@@ -36,7 +39,6 @@ export {
 export {
   bootstrapFirstAdminOwner,
   grantAdministratorRole,
-  listAdministratorGrants,
   revokeAdministratorGrant,
 } from '#core/administration.js';
 export type {
@@ -113,6 +115,7 @@ export function createAuthModule({
     routes: [
       buildAuthRoutes(config.AUTH_PASSWORD_ENABLED, workspaces, signupPolicy),
       administrationRoutes,
+      administrationUserRoutes,
     ],
     e2eRoutes: [createAuthE2eRoutes(workspaces)],
     publishers: [{name: 'auth', table: authOutbox, db, eventSchemas: authPublisherEventSchemas}],

package/src/metrics/instance.ts

@@ -3,7 +3,7 @@ import {instanceMetrics} from '@shipfox/node-opentelemetry';
 export type AuthTokenType = 'session' | 'job_lease' | 'runner_session';
 export type AuthTokenVerificationOutcome = 'ok' | 'rejected';
 export type AuthTokenRefreshOutcome = 'rotated' | 'grace' | 'rejected';
-export type AuthRateLimitAction = 'login' | 'email-send' | 'bootstrap';
+export type AuthRateLimitAction = 'login' | 'email-send' | 'bootstrap' | 'lookup';
 export type AuthRateLimitScope = 'ip' | 'email';
 export type AuthRateLimitOutcome = 'allowed' | 'blocked' | 'unavailable';