@shipfox/api-auth 17.0.0 → 19.0.0

package/drizzle/meta/_journal.json

@@ -22,6 +22,20 @@
       "when": 1785075183023,
       "tag": "0002_burly_whizzer",
       "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "7",
+      "when": 1788171920746,
+      "tag": "0003_brainy_luckman",
+      "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "7",
+      "when": 1788195662870,
+      "tag": "0004_yummy_runaways",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-auth",
   "license": "MIT",
-  "version": "17.0.0",
+  "version": "19.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -27,9 +27,9 @@
     "drizzle-orm": "^0.45.2",
     "zod": "^4.4.3",
     "@shipfox/api-common-dto": "15.0.0",
-    "@shipfox/api-auth-context": "17.0.0",
-    "@shipfox/api-auth-dto": "17.0.0",
-    "@shipfox/api-email-challenges": "1.1.11",
+    "@shipfox/api-auth-context": "19.0.0",
+    "@shipfox/api-auth-dto": "19.0.0",
+    "@shipfox/api-email-challenges": "1.1.12",
     "@shipfox/api-workspaces-dto": "15.0.0",
     "@shipfox/inter-module": "0.2.3",
     "@shipfox/config": "1.2.4",
@@ -39,12 +39,12 @@
     "@shipfox/node-jwt": "0.4.0",
     "@shipfox/node-email": "0.3.5",
     "@shipfox/node-mailer": "0.2.6",
-    "@shipfox/node-module": "1.0.7",
+    "@shipfox/node-module": "1.0.8",
     "@shipfox/node-opentelemetry": "0.6.5",
-    "@shipfox/node-outbox": "0.2.6",
+    "@shipfox/node-outbox": "0.2.7",
     "@shipfox/node-postgres": "0.5.1",
     "@shipfox/node-rate-limit": "0.4.0",
-    "@shipfox/node-tokens": "0.3.3"
+    "@shipfox/node-tokens": "1.1.0"
   },
   "imports": {
     "#*": "./dist/*"

package/src/core/admin-role.test.ts

@@ -1,7 +1,11 @@
 import {createAdminGrant} from '#db/admin-grants.js';
+import {db} from '#db/db.js';
+import {users} from '#db/schema/users.js';
 import {userFactory} from '#test/index.js';
 import {hasMinimumAdminRole, highestAdminRole, requireAdminRole} from './admin-role.js';
+import {listAdministratorUsers} from './administration.js';
 import type {AdminRoleRequiredError} from './errors.js';
+import {InvalidAdministratorUserDirectoryFilterError} from './errors.js';
 
 describe('admin role policy', () => {
   test.each([
@@ -23,6 +27,72 @@ describe('admin role policy', () => {
     expect(highestAdminRole([])).toBeNull();
   });
 
+  test('protects the administrator user directory with the observer role', async () => {
+    const user = await userFactory.create({emailVerifiedAt: new Date()});
+
+    await expect(listAdministratorUsers({actorId: user.id, limit: 10})).rejects.toEqual(
+      expect.objectContaining<Partial<AdminRoleRequiredError>>({
+        minimumRole: 'admin-observer',
+      }),
+    );
+  });
+
+  test('bounds administrator user directory search input', async () => {
+    const user = await userFactory.create({emailVerifiedAt: new Date()});
+    await createAdminGrant({userId: user.id, role: 'admin-observer'});
+
+    await expect(
+      listAdministratorUsers({
+        actorId: user.id,
+        limit: 10,
+        search: Array.from({length: 11}, () => 'term').join(' '),
+      }),
+    ).rejects.toThrow('at most 10 terms');
+    await expect(
+      listAdministratorUsers({actorId: user.id, limit: 10, search: 'x'.repeat(101)}),
+    ).rejects.toThrow('at most 100 characters');
+  });
+
+  test('rejects an active eligibility filter combined with a non-active status', async () => {
+    const user = await userFactory.create({emailVerifiedAt: new Date()});
+    await createAdminGrant({userId: user.id, role: 'admin-observer'});
+
+    await expect(
+      listAdministratorUsers({
+        actorId: user.id,
+        limit: 10,
+        eligible: true,
+        status: 'suspended',
+      }),
+    ).rejects.toBeInstanceOf(InvalidAdministratorUserDirectoryFilterError);
+  });
+
+  test('caps the directory page size in the core operation', async () => {
+    const user = await userFactory.create({emailVerifiedAt: new Date()});
+    await createAdminGrant({userId: user.id, role: 'admin-observer'});
+    const marker = `admin-directory-cap-${crypto.randomUUID()}`;
+    await db()
+      .insert(users)
+      .values(
+        Array.from({length: 101}, (_, index) => ({
+          email: `${marker}-${index}@example.com`,
+          name: `Directory User ${index}`,
+          hashedPassword: null,
+          emailVerifiedAt: new Date(),
+        })),
+      );
+
+    const result = await listAdministratorUsers({
+      actorId: user.id,
+      limit: 1_000,
+      search: marker,
+    });
+
+    expect(result.users).toHaveLength(100);
+    expect(result.rows).toEqual(result.users);
+    expect(result.nextCursor).not.toBeNull();
+  });
+
   test('evaluates the current role from Auth storage for every required minimum', async () => {
     const user = await userFactory.create({emailVerifiedAt: new Date()});
     await createAdminGrant({userId: user.id, role: 'admin-operator'});

package/src/core/administration.ts

@@ -18,7 +18,10 @@ import {
   suspendUserWithAudit,
   type UserModerationResult,
 } from '#db/admin-user-moderation.js';
-import {findAdministratorUser as findAdministratorUserInDb} from '#db/admin-users.js';
+import {
+  findAdministratorUser as findAdministratorUserInDb,
+  listAdministratorUsers as listAdministratorUsersInDb,
+} from '#db/admin-users.js';
 import {
   type ImpersonationResult,
   impersonateUserWithAudit,
@@ -45,6 +48,7 @@ import {
   ImpersonationExpiredError,
   ImpersonationTargetNotActiveError,
   InvalidAdminBootstrapTokenError,
+  InvalidAdministratorUserDirectoryFilterError,
   InvalidCredentialsError,
   LastAdminOwnerError,
   UserNotFoundError,
@@ -53,6 +57,10 @@ import {
 const ADMIN_OWNER_ROLE: AdminRole = 'admin-owner';
 const ADMIN_OBSERVER_ROLE: AdminRole = 'admin-observer';
 const ADMIN_OPERATOR_ROLE: AdminRole = 'admin-operator';
+const ADMINISTRATOR_DIRECTORY_MAX_PAGE_SIZE = 100;
+const ADMINISTRATOR_DIRECTORY_MAX_SEARCH_TERMS = 10;
+const ADMINISTRATOR_DIRECTORY_MAX_SEARCH_TERM_LENGTH = 100;
+const ADMINISTRATOR_DIRECTORY_SEARCH_TERM_SEPARATOR = /\s+/g;
 const BOOTSTRAP_COMMAND = 'auth.admin_grant.bootstrap';
 const GRANT_COMMAND = 'auth.admin_grant.grant';
 const REVOKE_COMMAND = 'auth.admin_grant.revoke';
@@ -192,6 +200,75 @@ export async function findAdministratorUserSummary(
   return user;
 }
 
+export interface ListAdministratorUsersParams {
+  actorId: string;
+  limit: number;
+  cursor?: TimestampIdCursor | undefined;
+  search?: string | undefined;
+  status?: AdministratorUserSummary['status'] | undefined;
+  eligible?: boolean | undefined;
+}
+
+export interface ListAdministratorUsersResult {
+  /** Retained for compatibility with the original database-shaped result. */
+  rows: AdministratorUserSummary[];
+  users: AdministratorUserSummary[];
+  nextCursor: TimestampIdCursor | null;
+}
+
+function normalizeAdministratorUserDirectorySearch(search: string | undefined): string | undefined {
+  const normalizedSearch = search
+    ?.trim()
+    .replace(ADMINISTRATOR_DIRECTORY_SEARCH_TERM_SEPARATOR, ' ');
+  if (!normalizedSearch) return;
+
+  const terms = normalizedSearch.split(' ');
+  if (terms.length > ADMINISTRATOR_DIRECTORY_MAX_SEARCH_TERMS) {
+    throw new InvalidAdministratorUserDirectoryFilterError(
+      `Administrator user directory search accepts at most ${ADMINISTRATOR_DIRECTORY_MAX_SEARCH_TERMS} terms`,
+    );
+  }
+
+  if (terms.some((term) => term.length > ADMINISTRATOR_DIRECTORY_MAX_SEARCH_TERM_LENGTH)) {
+    throw new InvalidAdministratorUserDirectoryFilterError(
+      `Administrator user directory search terms must be at most ${ADMINISTRATOR_DIRECTORY_MAX_SEARCH_TERM_LENGTH} characters`,
+    );
+  }
+
+  return normalizedSearch;
+}
+
+function validateAdministratorUserDirectoryFilters(
+  params: ListAdministratorUsersParams,
+): string | undefined {
+  const normalizedSearch = normalizeAdministratorUserDirectorySearch(params.search);
+  if (params.eligible === true && params.status && params.status !== 'active') {
+    throw new InvalidAdministratorUserDirectoryFilterError(
+      'eligible users must have active status',
+    );
+  }
+  return normalizedSearch;
+}
+
+export async function listAdministratorUsers(
+  params: ListAdministratorUsersParams,
+): Promise<ListAdministratorUsersResult> {
+  await requireAdminRole({userId: params.actorId, minimumRole: ADMIN_OBSERVER_ROLE});
+  const normalizedSearch = validateAdministratorUserDirectoryFilters(params);
+  const result = await listAdministratorUsersInDb({
+    ...params,
+    limit: Math.min(params.limit, ADMINISTRATOR_DIRECTORY_MAX_PAGE_SIZE),
+    search: normalizedSearch,
+  });
+  return {
+    rows: result.rows,
+    // Keep the original `rows` result while exposing the domain-named field
+    // used by the directory route.
+    users: result.rows,
+    nextCursor: result.nextCursor,
+  };
+}
+
 export async function listAdministratorGrantSummaries(params: {
   actorId: string;
   limit: number;

package/src/core/auth.ts

@@ -442,11 +442,9 @@ export type CreateSessionForUserError =
 export async function createSessionForUser(
   params: CreateSessionForUserParams,
 ): Promise<CreateSessionForUserResult> {
-  const user = params.userId
-    ? await findUserById({id: params.userId})
-    : params.email
-      ? await findUserByEmail({email: emailSchema.parse(params.email)})
-      : undefined;
+  let user: User | undefined;
+  if (params.userId) user = await findUserById({id: params.userId});
+  else if (params.email) user = await findUserByEmail({email: emailSchema.parse(params.email)});
 
   if (!user) {
     throw new UserNotFoundError(params.userId ?? params.email ?? 'unknown');

package/src/core/entities/agent-access.ts

@@ -0,0 +1,80 @@
+export type AgentClientKind = 'registered' | 'cimd';
+
+export interface AgentClient {
+  id: string;
+  clientId: string;
+  name: string;
+  redirectUris: string[];
+  kind: AgentClientKind;
+  lastSeenAt: Date | null;
+  unreferencedAt: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface AgentAuthorizationRequest {
+  id: string;
+  clientId: string;
+  redirectUri: string;
+  resource: string;
+  scopes: string[];
+  codeChallenge: string;
+  state: string | null;
+  expiresAt: Date;
+  consumedAt: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface AgentGrant {
+  id: string;
+  userId: string;
+  workspaceId: string;
+  clientId: string;
+  scopes: string[];
+  lastUsedAt: Date | null;
+  revokedAt: Date | null;
+  terminalAt: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface AgentAuthorizationCode {
+  id: string;
+  grantId: string;
+  hashedCode: string;
+  codeChallenge: string;
+  redirectUri: string;
+  resource: string;
+  expiresAt: Date;
+  consumedAt: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface AgentRefreshToken {
+  id: string;
+  grantId: string;
+  hashedToken: string;
+  expiresAt: Date;
+  rotatedAt: Date | null;
+  revokedAt: Date | null;
+  lastUsedAt: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface AgentPersonalAccessToken {
+  id: string;
+  userId: string;
+  workspaceId: string;
+  hashedToken: string;
+  prefix: string;
+  name: string;
+  scopes: string[];
+  expiresAt: Date;
+  lastUsedAt: Date | null;
+  revokedAt: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+}

package/src/core/errors.ts

@@ -95,6 +95,13 @@ export class AdminRoleRequiredError extends Error {
   }
 }
 
+export class InvalidAdministratorUserDirectoryFilterError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'InvalidAdministratorUserDirectoryFilterError';
+  }
+}
+
 export class LastAdminOwnerError extends Error {
   constructor() {
     super('Cannot remove the final active administrator owner');

package/src/core/runner-session-token.test.ts

@@ -14,6 +14,7 @@ function claims() {
     scope: 'workspace' as const,
     labels: ['linux', 'x64'],
     maxClaims: null,
+    lifecycleCapabilities: ['local_execution_fence_v1'],
   };
 }
 
@@ -30,6 +31,7 @@ describe('runner-session-token', () => {
     expect(verified?.scope).toBe(input.scope);
     expect(verified?.labels).toEqual(input.labels);
     expect(verified?.maxClaims).toBeNull();
+    expect(verified?.lifecycleCapabilities).toEqual(input.lifecycleCapabilities);
     expect(verified?.aud).toBe(RUNNER_SESSION_TOKEN_AUDIENCE);
     expect(verified?.iat).toBeTypeOf('number');
     expect(verified?.exp).toBeGreaterThan(verified?.iat ?? 0);

package/src/core/runner-session-token.ts

@@ -21,6 +21,7 @@ export async function issueRunnerSessionToken(
       scope: claims.scope,
       labels: claims.labels,
       maxClaims: claims.maxClaims,
+      lifecycleCapabilities: claims.lifecycleCapabilities,
     },
     secret: runnerSessionTokenKey(),
     expiresIn: config.AUTH_RUNNER_SESSION_TOKEN_EXPIRES_IN,

package/src/db/admin-user-moderation.ts

@@ -139,6 +139,58 @@ async function revokeActiveSessions(tx: Tx, userId: string): Promise<number> {
   return new Set(revoked.map(({sessionId}) => sessionId)).size;
 }
 
+async function suspendUser(tx: Tx, user: Awaited<ReturnType<typeof readTargetUserForUpdate>>) {
+  if (user.status !== 'active') return;
+  const activeOwners = await tx
+    .select({id: adminGrants.id})
+    .from(adminGrants)
+    .innerJoin(users, eq(adminGrants.userId, users.id))
+    .where(
+      and(
+        eq(adminGrants.role, 'admin-owner'),
+        isNull(adminGrants.revokedAt),
+        eq(users.status, 'active'),
+      ),
+    )
+    .limit(2);
+  const targetIsActiveOwner = await tx
+    .select({id: adminGrants.id})
+    .from(adminGrants)
+    .where(
+      and(
+        eq(adminGrants.userId, user.id),
+        eq(adminGrants.role, 'admin-owner'),
+        isNull(adminGrants.revokedAt),
+      ),
+    )
+    .limit(1);
+  if (targetIsActiveOwner.length > 0 && activeOwners.length <= 1) throw new LastAdminOwnerError();
+  await tx
+    .update(users)
+    .set({status: 'suspended', updatedAt: sql`now()`})
+    .where(eq(users.id, user.id));
+}
+
+async function applyModerationOperation(
+  tx: Tx,
+  user: Awaited<ReturnType<typeof readTargetUserForUpdate>>,
+  operation: 'suspend' | 'reactivate' | 'revoke-sessions',
+): Promise<number> {
+  if (operation === 'suspend') {
+    await suspendUser(tx, user);
+    return await revokeActiveSessions(tx, user.id);
+  }
+  if (operation === 'reactivate' && user.status === 'suspended') {
+    await tx
+      .update(users)
+      .set({status: 'active', updatedAt: sql`now()`})
+      .where(eq(users.id, user.id));
+    return 0;
+  }
+  if (operation === 'revoke-sessions') return await revokeActiveSessions(tx, user.id);
+  return 0;
+}
+
 async function executeUserModerationCommand(
   params: UserModerationCommandParams & {
     operation: 'suspend' | 'reactivate' | 'revoke-sessions';
@@ -157,51 +209,7 @@ async function executeUserModerationCommand(
     await lockUserSessionMutations(tx, params.userId);
     const user = await readTargetUserForUpdate(tx, params.userId);
     await requireActiveAdminOperator(tx, params.actorId);
-    let sessionsRevoked = 0;
-
-    if (params.operation === 'suspend') {
-      if (user.status === 'active') {
-        const activeOwners = await tx
-          .select({id: adminGrants.id})
-          .from(adminGrants)
-          .innerJoin(users, eq(adminGrants.userId, users.id))
-          .where(
-            and(
-              eq(adminGrants.role, 'admin-owner'),
-              isNull(adminGrants.revokedAt),
-              eq(users.status, 'active'),
-            ),
-          )
-          .limit(2);
-        const targetIsActiveOwner = await tx
-          .select({id: adminGrants.id})
-          .from(adminGrants)
-          .where(
-            and(
-              eq(adminGrants.userId, user.id),
-              eq(adminGrants.role, 'admin-owner'),
-              isNull(adminGrants.revokedAt),
-            ),
-          )
-          .limit(1);
-        if (targetIsActiveOwner.length > 0 && activeOwners.length <= 1) {
-          throw new LastAdminOwnerError();
-        }
-
-        await tx
-          .update(users)
-          .set({status: 'suspended', updatedAt: sql`now()`})
-          .where(eq(users.id, user.id));
-      }
-      sessionsRevoked = await revokeActiveSessions(tx, user.id);
-    } else if (params.operation === 'reactivate' && user.status === 'suspended') {
-      await tx
-        .update(users)
-        .set({status: 'active', updatedAt: sql`now()`})
-        .where(eq(users.id, user.id));
-    } else if (params.operation === 'revoke-sessions') {
-      sessionsRevoked = await revokeActiveSessions(tx, user.id);
-    }
+    const sessionsRevoked = await applyModerationOperation(tx, user, params.operation);
 
     const summary = await findUserSummary(tx, user.id);
     const result: StoredAdminUserModerationResult = {