@harborclient/team-hub 0.4.3 → 0.4.4

package/dist/cli.js

@@ -366,7 +366,7 @@ function mergeGlobalOptions(command, options) {
 }
 
 // src/db/firestore/FirestoreDatabase.ts
-import { randomUUID as randomUUID2 } from "crypto";
+import { randomUUID as randomUUID3 } from "crypto";
 import { Firestore } from "@google-cloud/firestore";
 
 // src/db/attribution.ts
@@ -379,9 +379,26 @@ async function resolveActingUserName(findUserById, actingUserId) {
 import { randomUUID } from "crypto";
 var BOOTSTRAP_USER_NAME = "bootstrap";
 
+// src/db/invitationErrors.ts
+var InvitationUnavailableError = class extends Error {
+  /**
+   * Specific failure reason used to choose a safe HTTP status code.
+   */
+  reason;
+  /**
+   * @param reason - Why the invitation cannot be used.
+   */
+  constructor(reason) {
+    super("Invalid or expired invitation.");
+    this.name = "InvitationUnavailableError";
+    this.reason = reason;
+  }
+};
+
 // src/db/firestore/const.ts
 var USERS_COLLECTION = "users";
 var API_TOKENS_COLLECTION = "apiTokens";
+var INVITATIONS_COLLECTION = "invitations";
 var COLLECTIONS_COLLECTION = "collections";
 var ENVIRONMENTS_COLLECTION = "environments";
 var SNIPPETS_COLLECTION = "snippets";
@@ -427,11 +444,25 @@ var firestoreConfigSchema = z2.object({
 
 // src/db/firestore/utils.ts
 function parseAuditEntityType(value) {
-  if (value === "user" || value === "api_token" || value === "collection" || value === "environment" || value === "snippet" || value === "folder" || value === "request" || value === "run_result") {
+  if (value === "user" || value === "api_token" || value === "invitation" || value === "collection" || value === "environment" || value === "snippet" || value === "folder" || value === "request" || value === "run_result") {
     return value;
   }
   throw new Error(`Invalid audit entity type: ${value}`);
 }
+function mapFirestoreInvitation(id, data) {
+  return {
+    id,
+    userId: data.userId,
+    codeHash: data.codeHash,
+    codePrefix: data.codePrefix,
+    expiresAt: data.expiresAt,
+    redeemedAt: data.redeemedAt,
+    revokedAt: data.revokedAt,
+    createdAt: data.createdAt,
+    createdByUserId: data.createdByUserId ?? null,
+    updatedByUserId: data.updatedByUserId ?? null
+  };
+}
 function mapFirestoreApiToken(id, data) {
   if (!data.userId) {
     throw new Error(`API token ${id} is missing a userId`);
@@ -644,6 +675,39 @@ function parseRunResultPayload(payload) {
   };
 }
 
+// src/server/auth/apiTokens.ts
+import { createHash, randomBytes, randomUUID as randomUUID2 } from "crypto";
+var TOKEN_PREFIX = "hbk_";
+function hashToken(token) {
+  return createHash("sha256").update(token).digest("hex");
+}
+function generateApiToken(userId, name) {
+  const secretSuffix = randomBytes(32).toString("base64url");
+  const secret = `${TOKEN_PREFIX}${secretSuffix}`;
+  const tokenPrefix = `${TOKEN_PREFIX}${secretSuffix.slice(0, 8)}`;
+  const createdAt = /* @__PURE__ */ new Date();
+  const record = {
+    id: randomUUID2(),
+    userId,
+    name,
+    tokenHash: hashToken(secret),
+    tokenPrefix,
+    createdAt,
+    lastUsedAt: null,
+    revokedAt: null,
+    createdByUserId: null,
+    updatedByUserId: null
+  };
+  return { record, secret };
+}
+function extractBearer(headerValue) {
+  if (!headerValue) {
+    return null;
+  }
+  const match = /^Bearer\s+(\S+)$/i.exec(headerValue.trim());
+  return match?.[1] ?? null;
+}
+
 // src/db/trimRequiredName.ts
 function trimRequiredName(name, label) {
   const trimmed = name.trim();
@@ -842,7 +906,7 @@ var FirestoreDatabase = class _FirestoreDatabase {
   async createUser(input, actingUserId) {
     const trimmedName = trimRequiredName(input.name, "User name");
     assertUserNameNotReserved(trimmedName);
-    const id = randomUUID2();
+    const id = randomUUID3();
     const now = /* @__PURE__ */ new Date();
     const attributionUserId = trimmedName === SYSTEM_USER_NAME ? id : actingUserId;
     const data = {
@@ -1146,6 +1210,205 @@ var FirestoreDatabase = class _FirestoreDatabase {
   async touchApiTokenLastUsed(id, when) {
     await this.requireClient().collection(API_TOKENS_COLLECTION).doc(id).update({ lastUsedAt: when });
   }
+  /**
+   * Creates a user account and its initial onboarding invitation in one transaction.
+   *
+   * @param userId - Pre-generated stable identifier for the new user.
+   * @param input - User fields to persist.
+   * @param invitation - Invitation metadata including the stored code hash.
+   * @param actingUserId - User performing the create action.
+   */
+  async createInvitedUser(userId, input, invitation, actingUserId) {
+    const trimmedName = trimRequiredName(input.name, "User name");
+    assertUserNameNotReserved(trimmedName);
+    const now = /* @__PURE__ */ new Date();
+    const client = this.requireClient();
+    const userRef = client.collection(USERS_COLLECTION).doc(userId);
+    const invitationRef = client.collection(INVITATIONS_COLLECTION).doc(invitation.id);
+    const userData = {
+      name: trimmedName,
+      role: input.role,
+      collectionAccess: input.collectionAccess,
+      environmentAccess: input.environmentAccess,
+      snippetAccess: input.snippetAccess,
+      llmAccess: input.llmAccess ?? false,
+      llmModels: input.llmModels ?? [],
+      llmMonthlyTokenLimit: input.llmMonthlyTokenLimit ?? null,
+      createdAt: now,
+      updatedAt: now,
+      createdByUserId: actingUserId,
+      updatedByUserId: actingUserId
+    };
+    const invitationData = {
+      userId: invitation.userId,
+      codeHash: invitation.codeHash,
+      codePrefix: invitation.codePrefix,
+      expiresAt: invitation.expiresAt,
+      redeemedAt: invitation.redeemedAt,
+      revokedAt: invitation.revokedAt,
+      createdAt: invitation.createdAt,
+      createdByUserId: actingUserId,
+      updatedByUserId: actingUserId
+    };
+    await client.runTransaction(async (transaction) => {
+      transaction.set(userRef, userData);
+      transaction.set(invitationRef, invitationData);
+    });
+    await this.recordAuditEntry(actingUserId, "create", "user", userId);
+    await this.recordAuditEntry(actingUserId, "create", "invitation", invitation.id);
+    return {
+      user: mapFirestoreUser(userId, userData),
+      invitation
+    };
+  }
+  /**
+   * Persists a new onboarding invitation for an existing user account.
+   *
+   * @param invitation - Invitation metadata including the stored code hash.
+   * @param actingUserId - User performing the create action.
+   */
+  async createInvitation(invitation, actingUserId) {
+    const user = await this.findUserById(invitation.userId);
+    if (!user) {
+      throw new Error("User not found");
+    }
+    const data = {
+      userId: invitation.userId,
+      codeHash: invitation.codeHash,
+      codePrefix: invitation.codePrefix,
+      expiresAt: invitation.expiresAt,
+      redeemedAt: invitation.redeemedAt,
+      revokedAt: invitation.revokedAt,
+      createdAt: invitation.createdAt,
+      createdByUserId: actingUserId,
+      updatedByUserId: actingUserId
+    };
+    await this.requireClient().collection(INVITATIONS_COLLECTION).doc(invitation.id).set(data);
+    await this.recordAuditEntry(actingUserId, "create", "invitation", invitation.id);
+    return invitation;
+  }
+  /**
+   * Finds an invitation by stable identifier.
+   *
+   * @param id - Invitation identifier to look up.
+   */
+  async findInvitationById(id) {
+    const snapshot = await this.requireClient().collection(INVITATIONS_COLLECTION).doc(id).get();
+    if (!snapshot.exists) {
+      return null;
+    }
+    return mapFirestoreInvitation(snapshot.id, snapshot.data());
+  }
+  /**
+   * Finds an invitation by the sha256 hash of its secret.
+   *
+   * @param codeHash - sha256 hex digest of the invitation secret.
+   */
+  async findInvitationByCodeHash(codeHash) {
+    const snapshot = await this.requireClient().collection(INVITATIONS_COLLECTION).where("codeHash", "==", codeHash).limit(1).get();
+    const doc = snapshot.docs[0];
+    if (!doc) {
+      return null;
+    }
+    return mapFirestoreInvitation(doc.id, doc.data());
+  }
+  /**
+   * Lists all invitations ordered by creation time descending.
+   */
+  async listInvitations() {
+    const snapshot = await this.requireClient().collection(INVITATIONS_COLLECTION).orderBy("createdAt", "desc").get();
+    return snapshot.docs.map(
+      (doc) => mapFirestoreInvitation(doc.id, doc.data())
+    );
+  }
+  /**
+   * Revokes a pending invitation by id.
+   *
+   * @param id - Invitation identifier to revoke.
+   * @param actingUserId - User performing the revoke action.
+   */
+  async revokeInvitation(id, actingUserId) {
+    const docRef = this.requireClient().collection(INVITATIONS_COLLECTION).doc(id);
+    const snapshot = await docRef.get();
+    if (!snapshot.exists) {
+      return false;
+    }
+    const data = snapshot.data();
+    const now = /* @__PURE__ */ new Date();
+    if (data.redeemedAt !== null || data.revokedAt !== null || data.expiresAt.getTime() <= now.getTime()) {
+      return false;
+    }
+    await docRef.update({ revokedAt: now, updatedByUserId: actingUserId });
+    await this.recordAuditEntry(actingUserId, "update", "invitation", id);
+    return true;
+  }
+  /**
+   * Atomically consumes a pending invitation and issues a permanent API token.
+   *
+   * @param codeHash - sha256 hex digest of the invitation secret.
+   * @param tokenName - Label stored on the newly created API token.
+   * @param actingUserId - Internal user attributed with the redemption action.
+   */
+  async redeemInvitation(codeHash, tokenName, actingUserId) {
+    const now = /* @__PURE__ */ new Date();
+    const client = this.requireClient();
+    const invitationQuery = client.collection(INVITATIONS_COLLECTION).where("codeHash", "==", codeHash).limit(1);
+    let user;
+    let invitation;
+    let token;
+    let secret;
+    await client.runTransaction(async (transaction) => {
+      const invitationSnapshot = await transaction.get(invitationQuery);
+      const invitationDoc = invitationSnapshot.docs[0];
+      if (!invitationDoc) {
+        throw new InvitationUnavailableError("not_found");
+      }
+      const invitationData = invitationDoc.data();
+      if (invitationData.redeemedAt) {
+        throw new InvitationUnavailableError("redeemed");
+      }
+      if (invitationData.revokedAt) {
+        throw new InvitationUnavailableError("revoked");
+      }
+      if (invitationData.expiresAt.getTime() <= now.getTime()) {
+        throw new InvitationUnavailableError("expired");
+      }
+      transaction.update(invitationDoc.ref, {
+        redeemedAt: now,
+        updatedByUserId: actingUserId
+      });
+      const userRef = client.collection(USERS_COLLECTION).doc(invitationData.userId);
+      const userSnapshot = await transaction.get(userRef);
+      if (!userSnapshot.exists) {
+        throw new Error("User not found");
+      }
+      user = mapFirestoreUser(userSnapshot.id, userSnapshot.data());
+      invitation = mapFirestoreInvitation(invitationDoc.id, {
+        ...invitationData,
+        redeemedAt: now,
+        updatedByUserId: actingUserId
+      });
+      const generated = generateApiToken(user.id, tokenName);
+      token = generated.record;
+      secret = generated.secret;
+      const tokenRef = client.collection(API_TOKENS_COLLECTION).doc(token.id);
+      const tokenData = {
+        userId: token.userId,
+        name: token.name,
+        tokenHash: token.tokenHash,
+        tokenPrefix: token.tokenPrefix,
+        createdAt: token.createdAt,
+        lastUsedAt: token.lastUsedAt,
+        revokedAt: token.revokedAt,
+        createdByUserId: actingUserId,
+        updatedByUserId: actingUserId
+      };
+      transaction.set(tokenRef, tokenData);
+    });
+    await this.recordAuditEntry(actingUserId, "update", "invitation", invitation.id);
+    await this.recordAuditEntry(actingUserId, "create", "api_token", token.id);
+    return { user, token, secret };
+  }
   /**
    * Lists all collections ordered by name.
    */
@@ -1163,7 +1426,7 @@ var FirestoreDatabase = class _FirestoreDatabase {
    */
   async createCollection(name, actingUserId) {
     const trimmedName = trimRequiredName(name, "Collection name");
-    const id = randomUUID2();
+    const id = randomUUID3();
     const now = /* @__PURE__ */ new Date();
     const data = {
       name: trimmedName,
@@ -1295,7 +1558,7 @@ var FirestoreDatabase = class _FirestoreDatabase {
    */
   async createEnvironment(name, actingUserId) {
     const trimmedName = trimRequiredName(name, "Environment name");
-    const id = randomUUID2();
+    const id = randomUUID3();
     const now = /* @__PURE__ */ new Date();
     const data = {
       name: trimmedName,
@@ -1412,7 +1675,7 @@ var FirestoreDatabase = class _FirestoreDatabase {
    */
   async createSnippet(name, code, scope, actingUserId) {
     const trimmedName = trimRequiredName(name, "Snippet name");
-    const id = randomUUID2();
+    const id = randomUUID3();
     const now = /* @__PURE__ */ new Date();
     const existing = await this.listSnippets();
     const maxOrder = existing.reduce((max, snippet) => Math.max(max, snippet.sortOrder), -1);
@@ -1606,7 +1869,7 @@ var FirestoreDatabase = class _FirestoreDatabase {
     }
     const existingRequests = await this.listRequests(input.collectionId);
     const maxOrder = existingRequests.filter((request) => request.folderId === folderId).reduce((max, request) => Math.max(max, request.sortOrder), -1);
-    const id = randomUUID2();
+    const id = randomUUID3();
     const data = {
       collectionId: input.collectionId,
       folderId,
@@ -1676,7 +1939,7 @@ var FirestoreDatabase = class _FirestoreDatabase {
    */
   async createFolder(collectionId, name, actingUserId) {
     const trimmedName = trimRequiredName(name, "Folder name");
-    const id = randomUUID2();
+    const id = randomUUID3();
     const now = /* @__PURE__ */ new Date();
     const existingFolders = await this.listFolders(collectionId);
     const maxOrder = existingFolders.reduce((max, folder) => Math.max(max, folder.sortOrder), -1);
@@ -1938,7 +2201,7 @@ var FirestoreDatabase = class _FirestoreDatabase {
   async createRunResult(input, actingUserId) {
     const metadata = parseRunResultPayload(input.payload);
     const label = input.label?.trim() || buildDefaultRunResultLabel(metadata);
-    const id = randomUUID2();
+    const id = randomUUID3();
     const now = /* @__PURE__ */ new Date();
     const data = {
       kind: metadata.kind,
@@ -1987,7 +2250,7 @@ var FirestoreDatabase = class _FirestoreDatabase {
    * @param input - Usage details for one successful completion step.
    */
   async createLlmUsageLog(input) {
-    const id = randomUUID2();
+    const id = randomUUID3();
     const now = /* @__PURE__ */ new Date();
     const data = {
       userId: input.userId,
@@ -2043,7 +2306,7 @@ var FirestoreDatabase = class _FirestoreDatabase {
       return;
     }
     const input = createSystemUserInput();
-    const id = randomUUID2();
+    const id = randomUUID3();
     const now = /* @__PURE__ */ new Date();
     const trimmedName = trimRequiredName(input.name, "User name");
     const data = {
@@ -2077,7 +2340,7 @@ var FirestoreDatabase = class _FirestoreDatabase {
       (userId) => this.findUserById(userId),
       actingUserId
     );
-    const id = randomUUID2();
+    const id = randomUUID3();
     const now = /* @__PURE__ */ new Date();
     const data = {
       userId: actingUserId,
@@ -2105,7 +2368,7 @@ var FirestoreDatabase = class _FirestoreDatabase {
 };
 
 // src/db/mysql/MysqlDatabase.ts
-import { randomUUID as randomUUID3 } from "crypto";
+import { randomUUID as randomUUID4 } from "crypto";
 import mysql from "mysql2/promise";
 
 // src/db/apiTokenRows.ts
@@ -2127,6 +2390,49 @@ function mapApiTokenSqlRow(row) {
   };
 }
 
+// src/db/invitationRows.ts
+function mapInvitationSqlRow(row) {
+  return {
+    id: row.id,
+    userId: row.user_id,
+    codeHash: row.code_hash,
+    codePrefix: row.code_prefix,
+    expiresAt: row.expires_at,
+    redeemedAt: row.redeemed_at,
+    revokedAt: row.revoked_at,
+    createdAt: row.created_at,
+    createdByUserId: row.created_by_user_id ?? null,
+    updatedByUserId: row.updated_by_user_id ?? null
+  };
+}
+function getInvitationStatus(invitation, now = /* @__PURE__ */ new Date()) {
+  if (invitation.redeemedAt) {
+    return "redeemed";
+  }
+  if (invitation.revokedAt) {
+    return "revoked";
+  }
+  if (invitation.expiresAt.getTime() <= now.getTime()) {
+    return "expired";
+  }
+  return "pending";
+}
+
+// src/db/mysql/invitationSql.ts
+var INVITATION_SELECT_COLUMNS = `
+  id,
+  user_id,
+  code_hash,
+  code_prefix,
+  expires_at,
+  redeemed_at,
+  revoked_at,
+  created_at,
+  created_by_user_id,
+  updated_by_user_id
+`.trim();
+var INVITATION_SELECT = `SELECT ${INVITATION_SELECT_COLUMNS} FROM user_invitations`;
+
 // src/db/auditLogRows.ts
 function parseAuditAction(value) {
   if (value === "create" || value === "update" || value === "delete" || value === "reorder" || value === "move") {
@@ -2135,7 +2441,7 @@ function parseAuditAction(value) {
   throw new Error(`Invalid audit action: ${value}`);
 }
 function parseAuditEntityType2(value) {
-  if (value === "user" || value === "api_token" || value === "collection" || value === "environment" || value === "snippet" || value === "folder" || value === "request" || value === "run_result") {
+  if (value === "user" || value === "api_token" || value === "invitation" || value === "collection" || value === "environment" || value === "snippet" || value === "folder" || value === "request" || value === "run_result") {
     return value;
   }
   throw new Error(`Invalid audit entity type: ${value}`);
@@ -2541,6 +2847,25 @@ CREATE TABLE IF NOT EXISTS run_results (
   INDEX run_results_created_idx (created_at)
 )
 `.trim();
+var USER_INVITATIONS_MIGRATION_SQL = `
+CREATE TABLE IF NOT EXISTS user_invitations (
+  id VARCHAR(36) PRIMARY KEY,
+  user_id VARCHAR(36) NOT NULL,
+  code_hash CHAR(64) NOT NULL UNIQUE,
+  code_prefix VARCHAR(32) NOT NULL,
+  expires_at DATETIME NOT NULL,
+  redeemed_at DATETIME,
+  revoked_at DATETIME,
+  created_at DATETIME NOT NULL,
+  created_by_user_id VARCHAR(36),
+  updated_by_user_id VARCHAR(36),
+  INDEX user_invitations_user_id_idx (user_id),
+  INDEX user_invitations_expires_at_idx (expires_at),
+  CONSTRAINT user_invitations_user_id_fk FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
+  CONSTRAINT user_invitations_created_by_fk FOREIGN KEY (created_by_user_id) REFERENCES users(id) ON DELETE SET NULL,
+  CONSTRAINT user_invitations_updated_by_fk FOREIGN KEY (updated_by_user_id) REFERENCES users(id) ON DELETE SET NULL
+)
+`.trim();
 var MYSQL_MIGRATIONS = [
   USERS_MIGRATION_SQL,
   API_TOKENS_MIGRATION_SQL,
@@ -2567,7 +2892,8 @@ var MYSQL_MIGRATIONS = [
   ENVIRONMENTS_DELETION_LOCKED_MIGRATION_SQL,
   USERS_SNIPPET_ACCESS_MIGRATION_SQL,
   USERS_SNIPPET_ACCESS_BACKFILL_SQL,
-  RUN_RESULTS_MIGRATION_SQL
+  RUN_RESULTS_MIGRATION_SQL,
+  USER_INVITATIONS_MIGRATION_SQL
 ];
 
 // src/db/mysql/schemas.ts
@@ -2800,7 +3126,7 @@ var MysqlDatabase = class _MysqlDatabase {
   async createUser(input, actingUserId) {
     const trimmedName = trimRequiredName(input.name, "User name");
     assertUserNameNotReserved(trimmedName);
-    const id = randomUUID3();
+    const id = randomUUID4();
     const now = /* @__PURE__ */ new Date();
     const attributionUserId = trimmedName === SYSTEM_USER_NAME ? id : actingUserId;
     await this.executeStatement(
@@ -3128,65 +3454,355 @@ var MysqlDatabase = class _MysqlDatabase {
     await this.executeStatement(`UPDATE api_tokens SET last_used_at = ? WHERE id = ?`, [when, id]);
   }
   /**
-   * Lists all collections ordered by name.
+   * Creates a user account and its initial onboarding invitation in one transaction.
+   *
+   * @param userId - Pre-generated stable identifier for the new user.
+   * @param input - User fields to persist.
+   * @param invitation - Invitation metadata including the stored code hash.
+   * @param actingUserId - User performing the create action.
    */
-  async listCollections() {
-    const rows = await this.queryRows(
-      `${COLLECTION_SELECT} ORDER BY name ASC`
-    );
-    return rows.map(mapCollectionSqlRow);
+  async createInvitedUser(userId, input, invitation, actingUserId) {
+    const trimmedName = trimRequiredName(input.name, "User name");
+    assertUserNameNotReserved(trimmedName);
+    const now = /* @__PURE__ */ new Date();
+    const connection = await this.requirePool().getConnection();
+    try {
+      await connection.beginTransaction();
+      await connection.execute(
+        `INSERT INTO users (
+          id,
+          name,
+          role,
+          collection_access,
+          environment_access,
+          snippet_access,
+          llm_access,
+          llm_models,
+          llm_monthly_token_limit,
+          created_at,
+          updated_at,
+          created_by_user_id,
+          updated_by_user_id
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        [
+          userId,
+          trimmedName,
+          input.role,
+          serializeAccessList(input.collectionAccess),
+          serializeAccessList(input.environmentAccess),
+          serializeAccessList(input.snippetAccess),
+          input.llmAccess ? 1 : 0,
+          serializeAccessList(input.llmModels ?? []),
+          input.llmMonthlyTokenLimit ?? null,
+          now,
+          now,
+          actingUserId,
+          actingUserId
+        ]
+      );
+      const [userRows] = await connection.execute(
+        `${USER_SELECT} WHERE id = ? LIMIT 1`,
+        [userId]
+      );
+      const userRow = userRows[0];
+      if (!userRow) {
+        throw new Error("User not found after insert");
+      }
+      await connection.execute(
+        `INSERT INTO user_invitations (
+          id,
+          user_id,
+          code_hash,
+          code_prefix,
+          expires_at,
+          redeemed_at,
+          revoked_at,
+          created_at,
+          created_by_user_id,
+          updated_by_user_id
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        [
+          invitation.id,
+          invitation.userId,
+          invitation.codeHash,
+          invitation.codePrefix,
+          invitation.expiresAt,
+          invitation.redeemedAt,
+          invitation.revokedAt,
+          invitation.createdAt,
+          actingUserId,
+          actingUserId
+        ]
+      );
+      await connection.commit();
+      await this.recordAuditEntry(actingUserId, "create", "user", userId);
+      await this.recordAuditEntry(actingUserId, "create", "invitation", invitation.id);
+      return {
+        user: mapUserSqlRow(userRow),
+        invitation
+      };
+    } catch (error) {
+      await connection.rollback();
+      throw error;
+    } finally {
+      connection.release();
+    }
   }
   /**
-   * Creates a new collection with the given name.
+   * Persists a new onboarding invitation for an existing user account.
    *
-   * @param name - Display name for the collection.
+   * @param invitation - Invitation metadata including the stored code hash.
    * @param actingUserId - User performing the create action.
    */
-  async createCollection(name, actingUserId) {
-    const trimmedName = trimRequiredName(name, "Collection name");
-    const id = randomUUID3();
-    const now = /* @__PURE__ */ new Date();
+  async createInvitation(invitation, actingUserId) {
+    const user = await this.findUserById(invitation.userId);
+    if (!user) {
+      throw new Error("User not found");
+    }
     await this.executeStatement(
-      `INSERT INTO collections (
+      `INSERT INTO user_invitations (
         id,
-        name,
-        variables,
-        headers,
-        auth,
-        pre_request_script,
-        post_request_script,
+        user_id,
+        code_hash,
+        code_prefix,
+        expires_at,
+        redeemed_at,
+        revoked_at,
         created_at,
-        updated_at,
         created_by_user_id,
         updated_by_user_id
-      ) VALUES (?, ?, '[]', '[]', ?, '', '', ?, ?, ?, ?)`,
-      [id, trimmedName, MYSQL_DEFAULT_AUTH_JSON, now, now, actingUserId, actingUserId]
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        invitation.id,
+        invitation.userId,
+        invitation.codeHash,
+        invitation.codePrefix,
+        invitation.expiresAt,
+        invitation.redeemedAt,
+        invitation.revokedAt,
+        invitation.createdAt,
+        actingUserId,
+        actingUserId
+      ]
     );
-    await this.recordAuditEntry(actingUserId, "create", "collection", id);
+    await this.recordAuditEntry(actingUserId, "create", "invitation", invitation.id);
+    return invitation;
+  }
+  /**
+   * Finds an invitation by stable identifier.
+   *
+   * @param id - Invitation identifier to look up.
+   */
+  async findInvitationById(id) {
     const rows = await this.queryRows(
-      `${COLLECTION_SELECT} WHERE id = ?`,
+      `${INVITATION_SELECT} WHERE id = ? LIMIT 1`,
       [id]
     );
     const row = rows[0];
-    if (!row) {
-      throw new Error("Collection not found after insert");
-    }
-    return mapCollectionSqlRow(row);
+    return row ? mapInvitationSqlRow(row) : null;
   }
   /**
-   * Updates a collection's name, variables, headers, and scripts.
+   * Finds an invitation by the sha256 hash of its secret.
    *
-   * @param actingUserId - User performing the update action.
+   * @param codeHash - sha256 hex digest of the invitation secret.
    */
-  async updateCollection(id, name, variables, headers, preRequestScript, postRequestScript, auth, actingUserId) {
-    const trimmedName = trimRequiredName(name, "Collection name");
-    const updatedAt = /* @__PURE__ */ new Date();
-    const result = await this.executeStatement(
-      `UPDATE collections
-      SET name = ?,
-        variables = ?,
-        headers = ?,
-        auth = ?,
+  async findInvitationByCodeHash(codeHash) {
+    const rows = await this.queryRows(
+      `${INVITATION_SELECT} WHERE code_hash = ? LIMIT 1`,
+      [codeHash]
+    );
+    const row = rows[0];
+    return row ? mapInvitationSqlRow(row) : null;
+  }
+  /**
+   * Lists all invitations ordered by creation time descending.
+   */
+  async listInvitations() {
+    const rows = await this.queryRows(
+      `${INVITATION_SELECT} ORDER BY created_at DESC`
+    );
+    return rows.map(mapInvitationSqlRow);
+  }
+  /**
+   * Revokes a pending invitation by id.
+   *
+   * @param id - Invitation identifier to revoke.
+   * @param actingUserId - User performing the revoke action.
+   */
+  async revokeInvitation(id, actingUserId) {
+    const now = /* @__PURE__ */ new Date();
+    const result = await this.executeStatement(
+      `UPDATE user_invitations
+      SET revoked_at = ?,
+        updated_by_user_id = ?
+      WHERE id = ?
+        AND redeemed_at IS NULL
+        AND revoked_at IS NULL
+        AND expires_at > ?`,
+      [now, actingUserId, id, now]
+    );
+    const revoked = (result.affectedRows ?? 0) > 0;
+    if (revoked) {
+      await this.recordAuditEntry(actingUserId, "update", "invitation", id);
+    }
+    return revoked;
+  }
+  /**
+   * Atomically consumes a pending invitation and issues a permanent API token.
+   *
+   * @param codeHash - sha256 hex digest of the invitation secret.
+   * @param tokenName - Label stored on the newly created API token.
+   * @param actingUserId - Internal user attributed with the redemption action.
+   */
+  async redeemInvitation(codeHash, tokenName, actingUserId) {
+    const now = /* @__PURE__ */ new Date();
+    const connection = await this.requirePool().getConnection();
+    try {
+      await connection.beginTransaction();
+      const [updateResult] = await connection.execute(
+        `UPDATE user_invitations
+        SET redeemed_at = ?,
+          updated_by_user_id = ?
+        WHERE code_hash = ?
+          AND redeemed_at IS NULL
+          AND revoked_at IS NULL
+          AND expires_at > ?`,
+        [now, actingUserId, codeHash, now]
+      );
+      if ((updateResult.affectedRows ?? 0) === 0) {
+        const [existingRows] = await connection.execute(
+          `${INVITATION_SELECT} WHERE code_hash = ? LIMIT 1`,
+          [codeHash]
+        );
+        const existingRow = existingRows[0];
+        if (!existingRow) {
+          throw new InvitationUnavailableError("not_found");
+        }
+        const existing = mapInvitationSqlRow(existingRow);
+        if (existing.redeemedAt) {
+          throw new InvitationUnavailableError("redeemed");
+        }
+        if (existing.revokedAt) {
+          throw new InvitationUnavailableError("revoked");
+        }
+        throw new InvitationUnavailableError("expired");
+      }
+      const [rows] = await connection.execute(
+        `${INVITATION_SELECT} WHERE code_hash = ? LIMIT 1`,
+        [codeHash]
+      );
+      const invitationRow = rows[0];
+      if (!invitationRow) {
+        throw new Error("Invitation not found after claim");
+      }
+      const invitation = mapInvitationSqlRow(invitationRow);
+      const [userRows] = await connection.execute(
+        `${USER_SELECT} WHERE id = ? LIMIT 1`,
+        [invitation.userId]
+      );
+      const userRow = userRows[0];
+      if (!userRow) {
+        throw new Error("User not found");
+      }
+      const user = mapUserSqlRow(userRow);
+      const { record, secret } = generateApiToken(user.id, tokenName);
+      await connection.execute(
+        `INSERT INTO api_tokens (
+          id,
+          user_id,
+          name,
+          token_hash,
+          token_prefix,
+          created_at,
+          last_used_at,
+          revoked_at,
+          created_by_user_id,
+          updated_by_user_id
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        [
+          record.id,
+          record.userId,
+          record.name,
+          record.tokenHash,
+          record.tokenPrefix,
+          record.createdAt,
+          record.lastUsedAt,
+          record.revokedAt,
+          actingUserId,
+          actingUserId
+        ]
+      );
+      await connection.commit();
+      await this.recordAuditEntry(actingUserId, "update", "invitation", invitation.id);
+      await this.recordAuditEntry(actingUserId, "create", "api_token", record.id);
+      return { user, token: record, secret };
+    } catch (error) {
+      await connection.rollback();
+      throw error;
+    } finally {
+      connection.release();
+    }
+  }
+  /**
+   * Lists all collections ordered by name.
+   */
+  async listCollections() {
+    const rows = await this.queryRows(
+      `${COLLECTION_SELECT} ORDER BY name ASC`
+    );
+    return rows.map(mapCollectionSqlRow);
+  }
+  /**
+   * Creates a new collection with the given name.
+   *
+   * @param name - Display name for the collection.
+   * @param actingUserId - User performing the create action.
+   */
+  async createCollection(name, actingUserId) {
+    const trimmedName = trimRequiredName(name, "Collection name");
+    const id = randomUUID4();
+    const now = /* @__PURE__ */ new Date();
+    await this.executeStatement(
+      `INSERT INTO collections (
+        id,
+        name,
+        variables,
+        headers,
+        auth,
+        pre_request_script,
+        post_request_script,
+        created_at,
+        updated_at,
+        created_by_user_id,
+        updated_by_user_id
+      ) VALUES (?, ?, '[]', '[]', ?, '', '', ?, ?, ?, ?)`,
+      [id, trimmedName, MYSQL_DEFAULT_AUTH_JSON, now, now, actingUserId, actingUserId]
+    );
+    await this.recordAuditEntry(actingUserId, "create", "collection", id);
+    const rows = await this.queryRows(
+      `${COLLECTION_SELECT} WHERE id = ?`,
+      [id]
+    );
+    const row = rows[0];
+    if (!row) {
+      throw new Error("Collection not found after insert");
+    }
+    return mapCollectionSqlRow(row);
+  }
+  /**
+   * Updates a collection's name, variables, headers, and scripts.
+   *
+   * @param actingUserId - User performing the update action.
+   */
+  async updateCollection(id, name, variables, headers, preRequestScript, postRequestScript, auth, actingUserId) {
+    const trimmedName = trimRequiredName(name, "Collection name");
+    const updatedAt = /* @__PURE__ */ new Date();
+    const result = await this.executeStatement(
+      `UPDATE collections
+      SET name = ?,
+        variables = ?,
+        headers = ?,
+        auth = ?,
         pre_request_script = ?,
         post_request_script = ?,
         updated_at = ?,
@@ -3289,7 +3905,7 @@ var MysqlDatabase = class _MysqlDatabase {
    */
   async createEnvironment(name, actingUserId) {
     const trimmedName = trimRequiredName(name, "Environment name");
-    const id = randomUUID3();
+    const id = randomUUID4();
     const now = /* @__PURE__ */ new Date();
     await this.executeStatement(
       `INSERT INTO environments (
@@ -3418,7 +4034,7 @@ var MysqlDatabase = class _MysqlDatabase {
    */
   async createSnippet(name, code, scope, actingUserId) {
     const trimmedName = trimRequiredName(name, "Snippet name");
-    const id = randomUUID3();
+    const id = randomUUID4();
     const now = /* @__PURE__ */ new Date();
     const maxRows = await this.queryRows(
       "SELECT COALESCE(MAX(sort_order), -1) AS max_order FROM snippets"
@@ -3641,7 +4257,7 @@ var MysqlDatabase = class _MysqlDatabase {
       [input.collectionId, folderId, folderId]
     );
     const maxOrder = maxRows[0]?.max_order ?? -1;
-    const id = randomUUID3();
+    const id = randomUUID4();
     await this.executeStatement(
       `INSERT INTO requests (
         id,
@@ -3741,7 +4357,7 @@ var MysqlDatabase = class _MysqlDatabase {
    */
   async createFolder(collectionId, name, actingUserId) {
     const trimmedName = trimRequiredName(name, "Folder name");
-    const id = randomUUID3();
+    const id = randomUUID4();
     const now = /* @__PURE__ */ new Date();
     const maxRows = await this.queryRows(
       "SELECT COALESCE(MAX(sort_order), -1) AS max_order FROM folders WHERE collection_id = ?",
@@ -3995,7 +4611,7 @@ var MysqlDatabase = class _MysqlDatabase {
   async addLlmUsage(userId, period, promptTokens, completionTokens) {
     const totalDelta = promptTokens + completionTokens;
     const now = /* @__PURE__ */ new Date();
-    const id = randomUUID3();
+    const id = randomUUID4();
     await this.executeStatement(
       `INSERT INTO llm_usage (
         id,
@@ -4025,7 +4641,7 @@ var MysqlDatabase = class _MysqlDatabase {
    * @param input - Usage details for one successful completion step.
    */
   async createLlmUsageLog(input) {
-    const id = randomUUID3();
+    const id = randomUUID4();
     const now = /* @__PURE__ */ new Date();
     await this.executeStatement(
       `INSERT INTO llm_usage_log (
@@ -4103,7 +4719,7 @@ var MysqlDatabase = class _MysqlDatabase {
   async createRunResult(input, actingUserId) {
     const metadata = parseRunResultPayload(input.payload);
     const label = input.label?.trim() || buildDefaultRunResultLabel(metadata);
-    const id = randomUUID3();
+    const id = randomUUID4();
     const now = /* @__PURE__ */ new Date();
     await this.executeStatement(
       `INSERT INTO run_results (
@@ -4175,7 +4791,7 @@ var MysqlDatabase = class _MysqlDatabase {
       return;
     }
     const input = createSystemUserInput();
-    const id = randomUUID3();
+    const id = randomUUID4();
     const now = /* @__PURE__ */ new Date();
     const trimmedName = trimRequiredName(input.name, "User name");
     await this.executeStatement(
@@ -4223,7 +4839,7 @@ var MysqlDatabase = class _MysqlDatabase {
    */
   async recordAuditEntry(actingUserId, action, entityType, entityId, metadata) {
     const userName = await resolveActingUserName(this.findUserById.bind(this), actingUserId);
-    const id = randomUUID3();
+    const id = randomUUID4();
     const now = /* @__PURE__ */ new Date();
     await this.executeStatement(
       `INSERT INTO audit_log (
@@ -4285,9 +4901,24 @@ var MysqlDatabase = class _MysqlDatabase {
 };
 
 // src/db/postgres/PostgresDatabase.ts
-import { randomUUID as randomUUID4 } from "crypto";
+import { randomUUID as randomUUID5 } from "crypto";
 import pg from "pg";
 
+// src/db/postgres/invitationSql.ts
+var INVITATION_SELECT_COLUMNS2 = `
+  id,
+  user_id,
+  code_hash,
+  code_prefix,
+  expires_at,
+  redeemed_at,
+  revoked_at,
+  created_at,
+  created_by_user_id,
+  updated_by_user_id
+`.trim();
+var INVITATION_SELECT2 = `SELECT ${INVITATION_SELECT_COLUMNS2} FROM user_invitations`;
+
 // src/db/postgres/migrations.ts
 var API_TOKENS_MIGRATION_SQL2 = `
 CREATE TABLE IF NOT EXISTS api_tokens (
@@ -4527,6 +5158,22 @@ CREATE TABLE IF NOT EXISTS run_results (
 );
 CREATE INDEX IF NOT EXISTS run_results_created_idx ON run_results (created_at DESC);
 `.trim();
+var USER_INVITATIONS_MIGRATION_SQL2 = `
+CREATE TABLE IF NOT EXISTS user_invitations (
+  id TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  code_hash CHAR(64) NOT NULL UNIQUE,
+  code_prefix TEXT NOT NULL,
+  expires_at TIMESTAMPTZ NOT NULL,
+  redeemed_at TIMESTAMPTZ,
+  revoked_at TIMESTAMPTZ,
+  created_at TIMESTAMPTZ NOT NULL,
+  created_by_user_id TEXT REFERENCES users(id) ON DELETE SET NULL,
+  updated_by_user_id TEXT REFERENCES users(id) ON DELETE SET NULL
+);
+CREATE INDEX IF NOT EXISTS user_invitations_user_id_idx ON user_invitations (user_id);
+CREATE INDEX IF NOT EXISTS user_invitations_expires_at_idx ON user_invitations (expires_at);
+`.trim();
 var POSTGRES_MIGRATIONS = [
   USERS_MIGRATION_SQL2,
   API_TOKENS_MIGRATION_SQL2,
@@ -4553,7 +5200,8 @@ var POSTGRES_MIGRATIONS = [
   ENVIRONMENTS_DELETION_LOCKED_MIGRATION_SQL2,
   USERS_SNIPPET_ACCESS_MIGRATION_SQL2,
   USERS_SNIPPET_ACCESS_BACKFILL_SQL2,
-  RUN_RESULTS_MIGRATION_SQL2
+  RUN_RESULTS_MIGRATION_SQL2,
+  USER_INVITATIONS_MIGRATION_SQL2
 ];
 
 // src/db/postgres/schemas.ts
@@ -4711,7 +5359,7 @@ var PostgresDatabase = class _PostgresDatabase {
   async createUser(input, actingUserId) {
     const trimmedName = trimRequiredName(input.name, "User name");
     assertUserNameNotReserved(trimmedName);
-    const id = randomUUID4();
+    const id = randomUUID5();
     const now = /* @__PURE__ */ new Date();
     const result = await this.query(
       `INSERT INTO users (
@@ -5029,6 +5677,286 @@ var PostgresDatabase = class _PostgresDatabase {
   async touchApiTokenLastUsed(id, when) {
     await this.query(`UPDATE api_tokens SET last_used_at = $2 WHERE id = $1`, [id, when]);
   }
+  /**
+   * Creates a user account and its initial onboarding invitation in one transaction.
+   *
+   * @param userId - Pre-generated stable identifier for the new user.
+   * @param input - User fields to persist.
+   * @param invitation - Invitation metadata including the stored code hash.
+   * @param actingUserId - User performing the create action.
+   */
+  async createInvitedUser(userId, input, invitation, actingUserId) {
+    const trimmedName = trimRequiredName(input.name, "User name");
+    assertUserNameNotReserved(trimmedName);
+    const now = /* @__PURE__ */ new Date();
+    const client = await this.requirePool().connect();
+    try {
+      await client.query("BEGIN");
+      const userResult = await client.query(
+        `INSERT INTO users (
+          id,
+          name,
+          role,
+          collection_access,
+          environment_access,
+          snippet_access,
+          llm_access,
+          llm_models,
+          llm_monthly_token_limit,
+          created_at,
+          updated_at,
+          created_by_user_id,
+          updated_by_user_id
+        ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13)
+        RETURNING ${USER_SELECT_COLUMNS}`,
+        [
+          userId,
+          trimmedName,
+          input.role,
+          serializeAccessList(input.collectionAccess),
+          serializeAccessList(input.environmentAccess),
+          serializeAccessList(input.snippetAccess),
+          input.llmAccess ?? false,
+          serializeAccessList(input.llmModels ?? []),
+          input.llmMonthlyTokenLimit ?? null,
+          now,
+          now,
+          actingUserId,
+          actingUserId
+        ]
+      );
+      const userRow = userResult.rows[0];
+      if (!userRow) {
+        throw new Error("User not found after insert");
+      }
+      await client.query(
+        `INSERT INTO user_invitations (
+          id,
+          user_id,
+          code_hash,
+          code_prefix,
+          expires_at,
+          redeemed_at,
+          revoked_at,
+          created_at,
+          created_by_user_id,
+          updated_by_user_id
+        ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)`,
+        [
+          invitation.id,
+          invitation.userId,
+          invitation.codeHash,
+          invitation.codePrefix,
+          invitation.expiresAt,
+          invitation.redeemedAt,
+          invitation.revokedAt,
+          invitation.createdAt,
+          actingUserId,
+          actingUserId
+        ]
+      );
+      await client.query("COMMIT");
+      await this.recordAuditEntry(actingUserId, "create", "user", userId);
+      await this.recordAuditEntry(actingUserId, "create", "invitation", invitation.id);
+      return {
+        user: mapUserSqlRow(userRow),
+        invitation
+      };
+    } catch (error) {
+      await client.query("ROLLBACK");
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+  /**
+   * Persists a new onboarding invitation for an existing user account.
+   *
+   * @param invitation - Invitation metadata including the stored code hash.
+   * @param actingUserId - User performing the create action.
+   */
+  async createInvitation(invitation, actingUserId) {
+    const user = await this.findUserById(invitation.userId);
+    if (!user) {
+      throw new Error("User not found");
+    }
+    await this.query(
+      `INSERT INTO user_invitations (
+        id,
+        user_id,
+        code_hash,
+        code_prefix,
+        expires_at,
+        redeemed_at,
+        revoked_at,
+        created_at,
+        created_by_user_id,
+        updated_by_user_id
+      ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)`,
+      [
+        invitation.id,
+        invitation.userId,
+        invitation.codeHash,
+        invitation.codePrefix,
+        invitation.expiresAt,
+        invitation.redeemedAt,
+        invitation.revokedAt,
+        invitation.createdAt,
+        actingUserId,
+        actingUserId
+      ]
+    );
+    await this.recordAuditEntry(actingUserId, "create", "invitation", invitation.id);
+    return invitation;
+  }
+  /**
+   * Finds an invitation by stable identifier.
+   *
+   * @param id - Invitation identifier to look up.
+   */
+  async findInvitationById(id) {
+    const result = await this.query(
+      `${INVITATION_SELECT2} WHERE id = $1 LIMIT 1`,
+      [id]
+    );
+    const row = result.rows[0];
+    return row ? mapInvitationSqlRow(row) : null;
+  }
+  /**
+   * Finds an invitation by the sha256 hash of its secret.
+   *
+   * @param codeHash - sha256 hex digest of the invitation secret.
+   */
+  async findInvitationByCodeHash(codeHash) {
+    const result = await this.query(
+      `${INVITATION_SELECT2} WHERE code_hash = $1 LIMIT 1`,
+      [codeHash]
+    );
+    const row = result.rows[0];
+    return row ? mapInvitationSqlRow(row) : null;
+  }
+  /**
+   * Lists all invitations ordered by creation time descending.
+   */
+  async listInvitations() {
+    const result = await this.query(
+      `${INVITATION_SELECT2} ORDER BY created_at DESC`
+    );
+    return result.rows.map(mapInvitationSqlRow);
+  }
+  /**
+   * Revokes a pending invitation by id.
+   *
+   * @param id - Invitation identifier to revoke.
+   * @param actingUserId - User performing the revoke action.
+   */
+  async revokeInvitation(id, actingUserId) {
+    const now = /* @__PURE__ */ new Date();
+    const result = await this.query(
+      `UPDATE user_invitations
+      SET revoked_at = $1, updated_by_user_id = $2
+      WHERE id = $3
+        AND redeemed_at IS NULL
+        AND revoked_at IS NULL
+        AND expires_at > $1
+      RETURNING id`,
+      [now, actingUserId, id]
+    );
+    if (!result.rows[0]) {
+      return false;
+    }
+    await this.recordAuditEntry(actingUserId, "update", "invitation", id);
+    return true;
+  }
+  /**
+   * Atomically consumes a pending invitation and issues a permanent API token.
+   *
+   * @param codeHash - sha256 hex digest of the invitation secret.
+   * @param tokenName - Label stored on the newly created API token.
+   * @param actingUserId - Internal user attributed with the redemption action.
+   */
+  async redeemInvitation(codeHash, tokenName, actingUserId) {
+    const now = /* @__PURE__ */ new Date();
+    const client = await this.requirePool().connect();
+    try {
+      await client.query("BEGIN");
+      const claimResult = await client.query(
+        `UPDATE user_invitations
+        SET redeemed_at = $1, updated_by_user_id = $2
+        WHERE code_hash = $3
+          AND redeemed_at IS NULL
+          AND revoked_at IS NULL
+          AND expires_at > $1
+        RETURNING ${INVITATION_SELECT_COLUMNS2}`,
+        [now, actingUserId, codeHash]
+      );
+      const invitationRow = claimResult.rows[0];
+      if (!invitationRow) {
+        const existingResult = await client.query(
+          `${INVITATION_SELECT2} WHERE code_hash = $1 LIMIT 1`,
+          [codeHash]
+        );
+        const existingRow = existingResult.rows[0];
+        if (!existingRow) {
+          throw new InvitationUnavailableError("not_found");
+        }
+        const existing = mapInvitationSqlRow(existingRow);
+        if (existing.redeemedAt) {
+          throw new InvitationUnavailableError("redeemed");
+        }
+        if (existing.revokedAt) {
+          throw new InvitationUnavailableError("revoked");
+        }
+        throw new InvitationUnavailableError("expired");
+      }
+      const invitation = mapInvitationSqlRow(invitationRow);
+      const userResult = await client.query(`${USER_SELECT2} WHERE id = $1 LIMIT 1`, [
+        invitation.userId
+      ]);
+      const userRow = userResult.rows[0];
+      if (!userRow) {
+        throw new Error("User not found");
+      }
+      const user = mapUserSqlRow(userRow);
+      const effectiveTokenName = tokenName.trim().length > 0 ? tokenName.trim() : user.name;
+      const { record, secret } = generateApiToken(user.id, effectiveTokenName);
+      await client.query(
+        `INSERT INTO api_tokens (
+          id,
+          user_id,
+          name,
+          token_hash,
+          token_prefix,
+          created_at,
+          last_used_at,
+          revoked_at,
+          created_by_user_id,
+          updated_by_user_id
+        ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)`,
+        [
+          record.id,
+          record.userId,
+          record.name,
+          record.tokenHash,
+          record.tokenPrefix,
+          record.createdAt,
+          record.lastUsedAt,
+          record.revokedAt,
+          actingUserId,
+          actingUserId
+        ]
+      );
+      await client.query("COMMIT");
+      await this.recordAuditEntry(actingUserId, "update", "invitation", invitation.id);
+      await this.recordAuditEntry(actingUserId, "create", "api_token", record.id);
+      return { user, token: record, secret };
+    } catch (error) {
+      await client.query("ROLLBACK");
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
   /**
    * Lists all collections ordered by name.
    */
@@ -5044,7 +5972,7 @@ var PostgresDatabase = class _PostgresDatabase {
    */
   async createCollection(name, actingUserId) {
     const trimmedName = trimRequiredName(name, "Collection name");
-    const id = randomUUID4();
+    const id = randomUUID5();
     const now = /* @__PURE__ */ new Date();
     const result = await this.query(
       `INSERT INTO collections (
@@ -5179,7 +6107,7 @@ var PostgresDatabase = class _PostgresDatabase {
    */
   async createEnvironment(name, actingUserId) {
     const trimmedName = trimRequiredName(name, "Environment name");
-    const id = randomUUID4();
+    const id = randomUUID5();
     const now = /* @__PURE__ */ new Date();
     const result = await this.query(
       `INSERT INTO environments (
@@ -5302,7 +6230,7 @@ var PostgresDatabase = class _PostgresDatabase {
    */
   async createSnippet(name, code, scope, actingUserId) {
     const trimmedName = trimRequiredName(name, "Snippet name");
-    const id = randomUUID4();
+    const id = randomUUID5();
     const now = /* @__PURE__ */ new Date();
     const maxResult = await this.query(
       "SELECT COALESCE(MAX(sort_order), -1) AS max_order FROM snippets"
@@ -5508,7 +6436,7 @@ var PostgresDatabase = class _PostgresDatabase {
       [input.collectionId, folderId]
     );
     const maxOrder = maxResult.rows[0]?.max_order ?? -1;
-    const id = randomUUID4();
+    const id = randomUUID5();
     const result = await this.query(
       `INSERT INTO requests (
         id,
@@ -5602,7 +6530,7 @@ var PostgresDatabase = class _PostgresDatabase {
    */
   async createFolder(collectionId, name, actingUserId) {
     const trimmedName = trimRequiredName(name, "Folder name");
-    const id = randomUUID4();
+    const id = randomUUID5();
     const now = /* @__PURE__ */ new Date();
     const maxResult = await this.query(
       "SELECT COALESCE(MAX(sort_order), -1) AS max_order FROM folders WHERE collection_id = $1",
@@ -5849,7 +6777,7 @@ var PostgresDatabase = class _PostgresDatabase {
   async addLlmUsage(userId, period, promptTokens, completionTokens) {
     const totalDelta = promptTokens + completionTokens;
     const now = /* @__PURE__ */ new Date();
-    const id = randomUUID4();
+    const id = randomUUID5();
     const result = await this.query(
       `INSERT INTO llm_usage (
         id,
@@ -5880,7 +6808,7 @@ var PostgresDatabase = class _PostgresDatabase {
    * @param input - Usage details for one successful completion step.
    */
   async createLlmUsageLog(input) {
-    const id = randomUUID4();
+    const id = randomUUID5();
     const now = /* @__PURE__ */ new Date();
     const result = await this.query(
       `INSERT INTO llm_usage_log (
@@ -5955,7 +6883,7 @@ var PostgresDatabase = class _PostgresDatabase {
   async createRunResult(input, actingUserId) {
     const metadata = parseRunResultPayload(input.payload);
     const label = input.label?.trim() || buildDefaultRunResultLabel(metadata);
-    const id = randomUUID4();
+    const id = randomUUID5();
     const now = /* @__PURE__ */ new Date();
     const result = await this.query(
       `INSERT INTO run_results (
@@ -6035,7 +6963,7 @@ var PostgresDatabase = class _PostgresDatabase {
       this.systemUserId = existing.id;
       return;
     }
-    const id = randomUUID4();
+    const id = randomUUID5();
     const now = /* @__PURE__ */ new Date();
     const input = createSystemUserInput();
     await this.query(
@@ -6086,7 +7014,7 @@ var PostgresDatabase = class _PostgresDatabase {
       (userId) => this.findUserById(userId),
       actingUserId
     );
-    const id = randomUUID4();
+    const id = randomUUID5();
     const now = /* @__PURE__ */ new Date();
     await this.query(
       `INSERT INTO audit_log (
@@ -6290,39 +7218,41 @@ function registerMigrateCommand(program, handler = migrateCommand) {
 
 // src/cli/userCommand.ts
 import { InvalidArgumentError } from "commander";
+import { randomUUID as randomUUID7 } from "crypto";
 
-// src/server/auth/apiTokens.ts
-import { createHash, randomBytes, randomUUID as randomUUID5 } from "crypto";
-var TOKEN_PREFIX = "hbk_";
-function hashToken(token) {
-  return createHash("sha256").update(token).digest("hex");
-}
-function generateApiToken(userId, name) {
-  const secretSuffix = randomBytes(32).toString("base64url");
-  const secret = `${TOKEN_PREFIX}${secretSuffix}`;
-  const tokenPrefix = `${TOKEN_PREFIX}${secretSuffix.slice(0, 8)}`;
+// src/server/auth/invitations.ts
+import { createHash as createHash2, randomBytes as randomBytes2, randomUUID as randomUUID6 } from "crypto";
+var INVITATION_PREFIX = "hbi_";
+var DEFAULT_INVITATION_EXPIRES_IN_HOURS = 24;
+function hashInvitationSecret(secret) {
+  return createHash2("sha256").update(secret).digest("hex");
+}
+function isInvitationSecretFormat(secret) {
+  return secret.startsWith(INVITATION_PREFIX) && secret.length > INVITATION_PREFIX.length + 8;
+}
+function resolveInvitationExpiresAt(expiresInHours) {
+  const hours = expiresInHours !== void 0 && expiresInHours > 0 ? expiresInHours : DEFAULT_INVITATION_EXPIRES_IN_HOURS;
+  return new Date(Date.now() + hours * 60 * 60 * 1e3);
+}
+function generateInvitation(userId, actingUserId, expiresAt) {
+  const secretSuffix = randomBytes2(32).toString("base64url");
+  const secret = `${INVITATION_PREFIX}${secretSuffix}`;
+  const codePrefix = `${INVITATION_PREFIX}${secretSuffix.slice(0, 8)}`;
   const createdAt = /* @__PURE__ */ new Date();
   const record = {
-    id: randomUUID5(),
+    id: randomUUID6(),
     userId,
-    name,
-    tokenHash: hashToken(secret),
-    tokenPrefix,
-    createdAt,
-    lastUsedAt: null,
+    codeHash: hashInvitationSecret(secret),
+    codePrefix,
+    expiresAt,
+    redeemedAt: null,
     revokedAt: null,
-    createdByUserId: null,
-    updatedByUserId: null
+    createdAt,
+    createdByUserId: actingUserId,
+    updatedByUserId: actingUserId
   };
   return { record, secret };
 }
-function extractBearer(headerValue) {
-  if (!headerValue) {
-    return null;
-  }
-  const match = /^Bearer\s+(\S+)$/i.exec(headerValue.trim());
-  return match?.[1] ?? null;
-}
 
 // src/server/admin/userValidation.ts
 var ValidationError = class extends Error {
@@ -6578,6 +7508,13 @@ function parseMonthlyTokenLimit(value) {
   }
   return parsed;
 }
+function parsePositiveInt(value) {
+  const parsed = Number(value.trim());
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new InvalidArgumentError("Value must be a positive integer.");
+  }
+  return parsed;
+}
 function printUser(user, usage) {
   console.log(`- id: ${user.id}`);
   console.log(`  name: ${user.name}`);
@@ -6683,6 +7620,100 @@ async function userCreateCommand(options) {
   console.log("");
   printCreatedApiToken(user, record, secret);
 }
+function printCreatedInvitation(user, invitation, secret) {
+  console.log(`Created invitation (${invitation.id}) for user "${user.name}" (${user.id}).`);
+  console.log(`Invitation prefix: ${invitation.codePrefix}`);
+  console.log(`Expires: ${invitation.expiresAt.toISOString()}`);
+  console.log("");
+  console.log("Store this invitation secret now; it will not be shown again:");
+  console.log(secret);
+}
+async function userInviteCreateCommand(options) {
+  const config = loadServerConfig(options.config);
+  const db = createDatabase(config.db);
+  const access = mapValidationError(
+    () => normalizeAccessForRole(
+      options.role,
+      options.collectionAccess,
+      options.environmentAccess,
+      options.snippetAccess
+    )
+  );
+  await db.connect();
+  const actingUserId = await requireSystemUserId(db);
+  const catalogs = await loadAccessCatalogs(db, config.llm);
+  const llmModels = readLlmModelsOption(options);
+  const llm = mapValidationError(
+    () => normalizeLlmForRole(options.role, options.llmAccess ?? false, llmModels)
+  );
+  validateSubmittedAccessListsOrThrow(
+    {
+      role: options.role,
+      collectionAccess: access.collectionAccess,
+      environmentAccess: access.environmentAccess,
+      snippetAccess: access.snippetAccess,
+      llmModels
+    },
+    catalogs
+  );
+  const userId = randomUUID7();
+  const expiresAt = resolveInvitationExpiresAt(options.expiresInHours);
+  const { record: invitation, secret } = generateInvitation(userId, actingUserId, expiresAt);
+  const created = await db.createInvitedUser(
+    userId,
+    {
+      name: options.name,
+      role: options.role,
+      collectionAccess: access.collectionAccess ?? [],
+      environmentAccess: access.environmentAccess ?? [],
+      snippetAccess: access.snippetAccess ?? [],
+      llmAccess: llm.llmAccess,
+      llmModels: llm.llmModels,
+      llmMonthlyTokenLimit: options.llmMonthlyTokens ?? null
+    },
+    invitation,
+    actingUserId
+  );
+  await db.disconnect();
+  console.log(
+    `Created invited user "${created.user.name}" (${created.user.id}) with role ${created.user.role}.`
+  );
+  printUser(created.user);
+  console.log("");
+  printCreatedInvitation(created.user, created.invitation, secret);
+}
+async function userInviteListCommand(options) {
+  const config = loadServerConfig(options.config);
+  const db = createDatabase(config.db);
+  await db.connect();
+  const [invitations, users] = await Promise.all([db.listInvitations(), db.listUsers()]);
+  await db.disconnect();
+  if (invitations.length === 0) {
+    console.log("No invitations found.");
+    return;
+  }
+  const usersById = new Map(users.map((user) => [user.id, user.name]));
+  for (const invitation of invitations) {
+    const userName = usersById.get(invitation.userId) ?? invitation.userId;
+    console.log(
+      `${invitation.id}  ${userName}  ${invitation.codePrefix}  ${getInvitationStatus(invitation)}`
+    );
+    console.log(`  expires: ${invitation.expiresAt.toISOString()}`);
+  }
+}
+async function userInviteRevokeCommand(options) {
+  const config = loadServerConfig(options.config);
+  const db = createDatabase(config.db);
+  await db.connect();
+  const actingUserId = await requireSystemUserId(db);
+  const revoked = await db.revokeInvitation(options.id, actingUserId);
+  await db.disconnect();
+  if (revoked) {
+    console.log(`Revoked invitation ${options.id}.`);
+    return;
+  }
+  console.log(`No pending invitation found with id ${options.id}.`);
+}
 async function userListCommand(options) {
   const config = loadServerConfig(options.config);
   const db = createDatabase(config.db);
@@ -6855,6 +7886,48 @@ async function userTokenRevokeCommand(options) {
 }
 function registerUserCommand(program, handlers = {}) {
   const user = program.command("user").description("Manage user accounts and their API tokens");
+  const invite = user.command("invite").description("Manage onboarding invitations for user accounts");
+  invite.command("create").description("Create a user account with a single-use onboarding invitation").requiredOption("--name <name>", "Unique display name", parseRequiredName).requiredOption("--role <role>", "Account role (admin or user)", parseUserRole2).option(
+    "--collection-access <id>",
+    "Collection id or * (repeatable)",
+    parseAccessFlag,
+    []
+  ).option(
+    "--environment-access <id>",
+    "Environment id or * (repeatable)",
+    parseAccessFlag,
+    []
+  ).option(
+    "--snippet-access <id>",
+    "Snippet id or * (repeatable)",
+    parseAccessFlag,
+    []
+  ).option("--llm-access", "Enable hub-proxied LLM access for the user").option("--llm-model <id>", "LLM model id or * (repeatable)", parseAccessFlag, []).option("--llm-monthly-tokens <count>", "Monthly LLM token limit", parseMonthlyTokenLimit).option("--expires-in-hours <hours>", "Invitation lifetime in hours", parsePositiveInt).action(
+    /**
+     * Runs the user invite create subcommand after merging global CLI options.
+     */
+    async function userInviteCreateAction(options) {
+      await (handlers.inviteCreate ?? userInviteCreateCommand)(mergeGlobalOptions(this, options));
+    }
+  );
+  invite.command("list").description("List stored onboarding invitations").action(
+    /**
+     * Runs the user invite list subcommand after merging global CLI options.
+     */
+    async function userInviteListAction(options) {
+      await (handlers.inviteList ?? userInviteListCommand)(mergeGlobalOptions(this, options));
+    }
+  );
+  invite.command("revoke").description("Revoke a pending onboarding invitation by id").argument("<id>", "Invitation identifier to revoke").action(
+    /**
+     * Runs the user invite revoke subcommand after merging global CLI options.
+     */
+    async function userInviteRevokeAction(id, options) {
+      await (handlers.inviteRevoke ?? userInviteRevokeCommand)(
+        mergeGlobalOptions(this, { ...options, id })
+      );
+    }
+  );
   user.command("create").description("Create a new user account").requiredOption("--name <name>", "Unique display name", parseRequiredName).requiredOption("--role <role>", "Account role (admin or user)", parseUserRole2).option(
     "--collection-access <id>",
     "Collection id or * (repeatable)",
@@ -7026,6 +8099,9 @@ function readPackageVersion() {
   return pkg.version;
 }
 
+// src/server/routes/admin.ts
+import { randomUUID as randomUUID8 } from "crypto";
+
 // src/server/auth/accessControl.ts
 function isAdmin(user) {
   return user.role === "admin";
@@ -7679,34 +8755,101 @@ var reloadConfigSectionResultSchema = z9.object({
   status: z9.enum(["reloaded", "unchanged", "failed", "restart-required"]),
   error: z9.string().optional()
 });
-var reloadConfigResponseSchema = z9.object({
-  sections: z9.array(reloadConfigSectionResultSchema),
-  fatalError: z9.string().optional()
+var reloadConfigResponseSchema = z9.object({
+  sections: z9.array(reloadConfigSectionResultSchema),
+  fatalError: z9.string().optional()
+});
+function serializeHubUser(user) {
+  return {
+    id: user.id,
+    name: user.name,
+    role: user.role,
+    collectionAccess: user.collectionAccess,
+    environmentAccess: user.environmentAccess,
+    snippetAccess: user.snippetAccess,
+    llmAccess: user.llmAccess,
+    llmModels: user.llmModels,
+    llmMonthlyTokenLimit: user.llmMonthlyTokenLimit,
+    createdAt: user.createdAt.toISOString(),
+    updatedAt: user.updatedAt.toISOString()
+  };
+}
+function serializeApiToken(token) {
+  return {
+    id: token.id,
+    userId: token.userId,
+    name: token.name,
+    tokenPrefix: token.tokenPrefix,
+    createdAt: token.createdAt.toISOString(),
+    lastUsedAt: token.lastUsedAt ? token.lastUsedAt.toISOString() : null,
+    revokedAt: token.revokedAt ? token.revokedAt.toISOString() : null
+  };
+}
+
+// src/server/routes/schemas/invitations.ts
+import { z as z10 } from "zod/v4";
+var invitationStatusSchema = z10.enum(["pending", "redeemed", "revoked", "expired"]);
+var hubInvitationRecordSchema = z10.object({
+  id: z10.string(),
+  userId: z10.string(),
+  codePrefix: z10.string(),
+  expiresAt: timestampSchema,
+  redeemedAt: timestampSchema.nullable(),
+  revokedAt: timestampSchema.nullable(),
+  createdAt: timestampSchema,
+  status: invitationStatusSchema
+});
+var createAdminInvitedUserBodySchema = createAdminUserBodySchema.extend({
+  expiresInHours: z10.number().int().positive().optional()
+});
+var createAdminInvitationResponseSchema = z10.object({
+  user: hubUserRecordSchema,
+  invitation: hubInvitationRecordSchema,
+  secret: z10.string()
+});
+var listAdminInvitationsResponseSchema = z10.object({
+  invitations: z10.array(hubInvitationRecordSchema)
+});
+var invitationSecretBodySchema = z10.object({
+  secret: z10.string().trim().min(1)
+});
+var redeemInvitationBodySchema = invitationSecretBodySchema.extend({
+  tokenName: z10.string().trim().min(1).optional()
+});
+var hubInvitationPreviewUserSchema = z10.object({
+  name: z10.string(),
+  role: userRoleSchema,
+  collectionAccess: z10.array(z10.string()),
+  environmentAccess: z10.array(z10.string()),
+  snippetAccess: z10.array(z10.string()),
+  llmAccess: z10.boolean(),
+  llmModels: z10.array(z10.string())
+});
+var previewInvitationResponseSchema = z10.object({
+  user: hubInvitationPreviewUserSchema,
+  expiresAt: timestampSchema
 });
-function serializeHubUser(user) {
+function serializeHubInvitation(invitation) {
+  return {
+    id: invitation.id,
+    userId: invitation.userId,
+    codePrefix: invitation.codePrefix,
+    expiresAt: invitation.expiresAt.toISOString(),
+    redeemedAt: invitation.redeemedAt?.toISOString() ?? null,
+    revokedAt: invitation.revokedAt?.toISOString() ?? null,
+    createdAt: invitation.createdAt.toISOString(),
+    status: getInvitationStatus(invitation)
+  };
+}
+function serializeInvitationPreviewUser(user) {
   return {
-    id: user.id,
     name: user.name,
     role: user.role,
     collectionAccess: user.collectionAccess,
     environmentAccess: user.environmentAccess,
     snippetAccess: user.snippetAccess,
     llmAccess: user.llmAccess,
-    llmModels: user.llmModels,
-    llmMonthlyTokenLimit: user.llmMonthlyTokenLimit,
-    createdAt: user.createdAt.toISOString(),
-    updatedAt: user.updatedAt.toISOString()
-  };
-}
-function serializeApiToken(token) {
-  return {
-    id: token.id,
-    userId: token.userId,
-    name: token.name,
-    tokenPrefix: token.tokenPrefix,
-    createdAt: token.createdAt.toISOString(),
-    lastUsedAt: token.lastUsedAt ? token.lastUsedAt.toISOString() : null,
-    revokedAt: token.revokedAt ? token.revokedAt.toISOString() : null
+    llmModels: user.llmModels
   };
 }
 
@@ -7856,6 +8999,174 @@ async function registerAdminRoutes(app, options) {
       }
     }
   });
+  routes.route({
+    method: "POST",
+    url: "/admin/invited-users",
+    schema: {
+      body: createAdminInvitedUserBodySchema,
+      response: {
+        201: createAdminInvitationResponseSchema,
+        400: errorResponseSchema,
+        403: errorResponseSchema
+      }
+    },
+    /**
+     * Creates a user account and a single-use onboarding invitation without issuing an API token.
+     */
+    handler: async (request, reply) => {
+      try {
+        const user = requireAuthenticatedUser(request);
+        if (denyUnlessAllowed(reply, canUseManagementApi(user))) {
+          return;
+        }
+        const input = buildAdminUserCreateInput(request.body);
+        const llm = getLlm();
+        const [collections, environments, snippets] = await Promise.all([
+          db.listCollections(),
+          db.listEnvironments(),
+          db.listSnippets()
+        ]);
+        const catalogs = buildAccessCatalogIds(
+          collections,
+          environments,
+          snippets,
+          llm ? listHubOfferedModels(llm).map((model) => model.id) : null
+        );
+        validateSubmittedAccessLists(
+          {
+            role: request.body.role,
+            collectionAccess: request.body.collectionAccess,
+            environmentAccess: request.body.environmentAccess,
+            snippetAccess: request.body.snippetAccess,
+            llmModels: request.body.llmModels
+          },
+          catalogs
+        );
+        const userId = randomUUID8();
+        const expiresAt = resolveInvitationExpiresAt(request.body.expiresInHours);
+        const { record: invitation, secret } = generateInvitation(userId, user.id, expiresAt);
+        const created = await db.createInvitedUser(userId, input, invitation, user.id);
+        return reply.code(201).send({
+          user: serializeHubUser(created.user),
+          invitation: serializeHubInvitation(created.invitation),
+          secret
+        });
+      } catch (error) {
+        if (handleValidationError(reply, error) || handleDbError(reply, error)) {
+          return;
+        }
+        throw error;
+      }
+    }
+  });
+  routes.route({
+    method: "POST",
+    url: "/admin/users/:id/invitations",
+    schema: {
+      params: idParamSchema,
+      body: createAdminInvitedUserBodySchema.pick({ expiresInHours: true }),
+      response: {
+        201: createAdminInvitationResponseSchema,
+        400: errorResponseSchema,
+        403: errorResponseSchema,
+        404: errorResponseSchema
+      }
+    },
+    /**
+     * Issues a replacement onboarding invitation for an existing user account.
+     */
+    handler: async (request, reply) => {
+      try {
+        const admin = requireAuthenticatedUser(request);
+        if (denyUnlessAllowed(reply, canUseManagementApi(admin))) {
+          return;
+        }
+        const existing = await db.findUserById(request.params.id);
+        if (!existing) {
+          return reply.code(404).send({ error: "User not found" });
+        }
+        if (denySystemUserTarget(reply, existing, db.getSystemUserId())) {
+          return;
+        }
+        const expiresAt = resolveInvitationExpiresAt(request.body.expiresInHours);
+        const { record: invitation, secret } = generateInvitation(existing.id, admin.id, expiresAt);
+        await db.createInvitation(invitation, admin.id);
+        return reply.code(201).send({
+          user: serializeHubUser(existing),
+          invitation: serializeHubInvitation(invitation),
+          secret
+        });
+      } catch (error) {
+        if (handleDbError(reply, error)) {
+          return;
+        }
+        throw error;
+      }
+    }
+  });
+  routes.route({
+    method: "GET",
+    url: "/admin/invitations",
+    schema: {
+      response: {
+        200: listAdminInvitationsResponseSchema,
+        403: errorResponseSchema
+      }
+    },
+    /**
+     * Lists onboarding invitations for operator review and recovery.
+     */
+    handler: async (request, reply) => {
+      try {
+        const user = requireAuthenticatedUser(request);
+        if (denyUnlessAllowed(reply, canUseManagementApi(user))) {
+          return;
+        }
+        const invitations = await db.listInvitations();
+        return reply.send({
+          invitations: invitations.map((invitation) => serializeHubInvitation(invitation))
+        });
+      } catch (error) {
+        if (handleDbError(reply, error)) {
+          return;
+        }
+        throw error;
+      }
+    }
+  });
+  routes.route({
+    method: "DELETE",
+    url: "/admin/invitations/:id",
+    schema: {
+      params: idParamSchema,
+      response: {
+        204: emptyResponseSchema,
+        403: errorResponseSchema,
+        404: errorResponseSchema
+      }
+    },
+    /**
+     * Revokes a pending onboarding invitation so it can no longer be redeemed.
+     */
+    handler: async (request, reply) => {
+      try {
+        const user = requireAuthenticatedUser(request);
+        if (denyUnlessAllowed(reply, canUseManagementApi(user))) {
+          return;
+        }
+        const revoked = await db.revokeInvitation(request.params.id, user.id);
+        if (!revoked) {
+          return reply.code(404).send({ error: "Invitation not found or not revocable." });
+        }
+        return reply.code(204).send(null);
+      } catch (error) {
+        if (handleDbError(reply, error)) {
+          return;
+        }
+        throw error;
+      }
+    }
+  });
   routes.route({
     method: "GET",
     url: "/admin/collections",
@@ -8719,6 +10030,189 @@ async function registerAuthRoutes(app) {
   });
 }
 
+// src/db/invitationValidation.ts
+function assertInvitationPending(invitation, now = /* @__PURE__ */ new Date()) {
+  if (invitation.redeemedAt) {
+    throw new InvitationUnavailableError("redeemed");
+  }
+  if (invitation.revokedAt) {
+    throw new InvitationUnavailableError("revoked");
+  }
+  if (invitation.expiresAt.getTime() <= now.getTime()) {
+    throw new InvitationUnavailableError("expired");
+  }
+}
+
+// src/server/routes/invitationErrors.ts
+function handleInvitationError(reply, error) {
+  if (!(error instanceof InvitationUnavailableError)) {
+    return false;
+  }
+  const status = error.reason === "not_found" ? 404 : 410;
+  void reply.code(status).send(errorResponseSchema.parse({ error: error.message }));
+  return true;
+}
+
+// src/server/routes/invitations.ts
+function buildInvitationThrottleKey(request) {
+  return `${request.ip}:invitation`;
+}
+function createInvitationThrottleHook(throttleStore) {
+  return async function invitationThrottle(request, reply) {
+    const policy = throttleStore.getPolicy();
+    const throttleKey = buildInvitationThrottleKey(request);
+    try {
+      if (await throttleStore.isBlocked(throttleKey)) {
+        return reply.header("Retry-After", String(policy.blockSeconds)).code(429).send({ error: "Too Many Requests" });
+      }
+    } catch {
+      return reply.code(503).send({ error: "Service Unavailable" });
+    }
+  };
+}
+async function recordInvitationFailure(throttleStore, request, reply) {
+  const throttleKey = buildInvitationThrottleKey(request);
+  try {
+    await throttleStore.recordFailure(throttleKey);
+    return false;
+  } catch {
+    void reply.code(503).send({ error: "Service Unavailable" });
+    return true;
+  }
+}
+async function resetInvitationThrottle(throttleStore, request, reply) {
+  const throttleKey = buildInvitationThrottleKey(request);
+  try {
+    await throttleStore.reset(throttleKey);
+    return false;
+  } catch {
+    void reply.code(503).send({ error: "Service Unavailable" });
+    return true;
+  }
+}
+async function registerInvitationRoutes(app, options) {
+  const routes = app.withTypeProvider();
+  app.addHook("onRequest", createInvitationThrottleHook(options.throttleStore));
+  routes.route({
+    method: "POST",
+    url: "/auth/invitations/preview",
+    schema: {
+      body: invitationSecretBodySchema,
+      response: {
+        200: previewInvitationResponseSchema,
+        400: errorResponseSchema,
+        404: errorResponseSchema,
+        410: errorResponseSchema,
+        429: errorResponseSchema,
+        503: errorResponseSchema
+      }
+    },
+    /**
+     * Returns invited user details for confirmation without consuming the invitation.
+     */
+    handler: async (request, reply) => {
+      try {
+        const secret = request.body.secret;
+        if (!isInvitationSecretFormat(secret)) {
+          return reply.code(400).send({ error: "Invalid invitation secret format." });
+        }
+        const invitation = await options.db.findInvitationByCodeHash(hashInvitationSecret(secret));
+        if (!invitation) {
+          if (await recordInvitationFailure(options.throttleStore, request, reply)) {
+            return;
+          }
+          return reply.code(404).send({ error: "Invalid or expired invitation." });
+        }
+        try {
+          assertInvitationPending(invitation);
+        } catch (error) {
+          if (await recordInvitationFailure(options.throttleStore, request, reply)) {
+            return;
+          }
+          if (handleInvitationError(reply, error)) {
+            return;
+          }
+          throw error;
+        }
+        const user = await options.db.findUserById(invitation.userId);
+        if (!user) {
+          return reply.code(404).send({ error: "Invalid or expired invitation." });
+        }
+        if (await resetInvitationThrottle(options.throttleStore, request, reply)) {
+          return;
+        }
+        return reply.send({
+          user: serializeInvitationPreviewUser(user),
+          expiresAt: invitation.expiresAt.toISOString()
+        });
+      } catch (error) {
+        if (handleDbError(reply, error) || handleInvitationError(reply, error)) {
+          return;
+        }
+        throw error;
+      }
+    }
+  });
+  routes.route({
+    method: "POST",
+    url: "/auth/invitations/redeem",
+    schema: {
+      body: redeemInvitationBodySchema,
+      response: {
+        201: createdApiTokenResponseSchema,
+        400: errorResponseSchema,
+        404: errorResponseSchema,
+        410: errorResponseSchema,
+        429: errorResponseSchema,
+        503: errorResponseSchema
+      }
+    },
+    /**
+     * Consumes a pending invitation and returns a one-time permanent API token secret.
+     */
+    handler: async (request, reply) => {
+      try {
+        const secret = request.body.secret;
+        if (!isInvitationSecretFormat(secret)) {
+          return reply.code(400).send({ error: "Invalid invitation secret format." });
+        }
+        const systemUserId = options.db.getSystemUserId();
+        if (!systemUserId) {
+          throw new Error("System user is not provisioned");
+        }
+        const tokenName = request.body.tokenName?.trim();
+        const codeHash = hashInvitationSecret(secret);
+        let redeemed;
+        try {
+          redeemed = await options.db.redeemInvitation(codeHash, tokenName ?? "", systemUserId);
+        } catch (error) {
+          if (error instanceof InvitationUnavailableError) {
+            if (await recordInvitationFailure(options.throttleStore, request, reply)) {
+              return;
+            }
+          }
+          if (handleInvitationError(reply, error)) {
+            return;
+          }
+          throw error;
+        }
+        if (await resetInvitationThrottle(options.throttleStore, request, reply)) {
+          return;
+        }
+        return reply.code(201).send({
+          token: serializeApiToken(redeemed.token),
+          secret: redeemed.secret
+        });
+      } catch (error) {
+        if (handleDbError(reply, error) || handleInvitationError(reply, error)) {
+          return;
+        }
+        throw error;
+      }
+    }
+  });
+}
+
 // src/server/routes/collections.ts
 async function registerCollectionRoutes(app, db) {
   const routes = app.withTypeProvider();
@@ -9339,10 +10833,10 @@ async function registerFolderRoutes(app, db) {
 }
 
 // src/server/routes/health.ts
-import { z as z10 } from "zod/v4";
-var healthResponseSchema = z10.object({
-  status: z10.literal("ok"),
-  version: z10.string()
+import { z as z11 } from "zod/v4";
+var healthResponseSchema = z11.object({
+  status: z11.literal("ok"),
+  version: z11.string()
 });
 async function registerHealthRoute(app, version2) {
   app.withTypeProvider().route({
@@ -10462,10 +11956,10 @@ async function registerLlmRoutes(app, options) {
 }
 
 // src/server/routes/schemas/plugins.ts
-import { z as z11 } from "zod/v4";
-var pluginSourcesResponseSchema = z11.object({
-  catalogs: z11.array(z11.string()),
-  trusted: z11.array(z11.string())
+import { z as z12 } from "zod/v4";
+var pluginSourcesResponseSchema = z12.object({
+  catalogs: z12.array(z12.string()),
+  trusted: z12.array(z12.string())
 });
 
 // src/server/routes/plugins.ts
@@ -10559,6 +12053,10 @@ function createBearerAuthHook(db, throttleStore) {
 // src/server/routes/index.ts
 async function registerPublicRoutes(app, options) {
   await registerHealthRoute(app, options.version);
+  await registerInvitationRoutes(app, {
+    db: options.db,
+    throttleStore: options.throttleStore
+  });
 }
 async function registerProtectedRoutes(app, options) {
   registerBearerAuthDecorator(app);