studiograph 1.3.48-next.13 → 1.3.48-next.131

package/dist/services/auth-service.d.ts

@@ -5,20 +5,51 @@
  * Database lives at .studiograph/auth.db inside the workspace.
  *
  * Auth state is portable via .studiograph/auth-seed.json — a JSON export of
- * all users (with bcrypt hashes) and the JWT secret. The seed file is
- * committed to the config repo so it syncs between local and Railway:
+ * all users (with bcrypt hashes) and the JWT signing secret. The seed file
+ * is committed to the config repo so it syncs between local and Railway:
  *   local setup → commit → push → Railway redeploy → users restored from seed
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * SECURITY — config repo is a secret store
+ * ─────────────────────────────────────────────────────────────────────────
+ * `auth-seed.json` carries:
+ *   • the JWT signing secret (anyone holding this can mint sessions for any
+ *     user in the workspace, bypassing password auth entirely)
+ *   • bcrypt password hashes for every user (offline-crackable; bcrypt cost
+ *     12 buys time but not invulnerability against weak passwords)
+ *
+ * Treat the .studiograph/ config repo with the same operational care as any
+ * other secret store: private remote, restricted contributors, never made
+ * public. The audit (2026-05) flagged this surface specifically — `getSeedData`
+ * returns these fields by design (they're how the seed-restore flow works on
+ * Railway redeploys) but every caller needs to understand they are exporting
+ * raw secrets.
+ *
+ * To override the file-based JWT secret in production (e.g. Railway), set
+ * the STUDIOGRAPH_JWT_SECRET environment variable. The env var wins over the
+ * `auth-secret` file and the seed file: a leaked seed file alone won't let
+ * an attacker mint tokens for an environment with a different in-process
+ * secret. Rotation: change the env var and restart — all extant tokens
+ * invalidate together.
  */
-export type UserRole = 'owner' | 'admin' | 'member';
+export type UserRole = 'owner' | 'member';
+export type FolderRole = 'admin' | 'editor';
 export interface AuthUser {
     id: number;
     email: string;
+    /**
+     * Stable, human-readable identifier used for `created_by` / `updated_by`
+     * audit fields in entity frontmatter and as the git author identity on
+     * workspace commits. Email-free so the workspace git history doesn't carry
+     * PII. Generated at user creation, immutable thereafter.
+     */
+    handle: string;
     displayName: string;
     role: UserRole;
     createdAt: string;
 }
-/** Check if a role has admin-level privileges (owner or admin). */
-export declare function isAdminOrOwner(role: string): boolean;
+/** Check if a user has workspace-owner privileges. */
+export declare function isWorkspaceOwner(role: string): boolean;
 export interface UserView {
     id: number;
     name: string;
@@ -32,26 +63,61 @@ export interface UserView {
 }
 export interface AuthSeed {
     jwtSecret: string;
+    /** @deprecated removed in favor of per-user tokens (api_tokens table). Retained so pre-existing seeds don't fail to parse. */
     apiKey?: string;
     users: Array<{
         email: string;
+        handle: string;
         password_hash: string;
         display_name: string;
         role: string;
         created_at: string;
     }>;
-    collection_access?: Array<{
+    folder_access?: Array<{
         user_email: string;
-        collection_name: string;
+        folder_name: string;
+        role?: FolderRole;
     }>;
 }
+/**
+ * Optional encryption hookup for per-user secrets stored in auth.db.
+ *
+ * When `masterKey` is provided, AuthService treats `oauth_tokens.data_ciphertext`
+ * and `user_preferences.settings_ciphertext` as the source of truth for
+ * encrypted user-secrets, falling back to legacy plaintext columns only on
+ * pre-migration databases. Without a master key (tests, flag-off boots),
+ * AuthService stays on the legacy plaintext path — but it refuses to run
+ * against a database that has already been migrated, since reading
+ * post-migration rows without the key would silently return empty data.
+ */
+export interface AuthServiceCryptoOptions {
+    masterKey: Uint8Array;
+    /** Defaults to 'mk_v1'. Bumped by master-key rotation. */
+    keyVersion?: string;
+}
 export declare class AuthService {
     private db;
     private jwtSecret;
-    private apiKey;
     private sgDir;
-    constructor(workspacePath: string);
+    private crypto?;
+    /**
+     * True once we've confirmed `data_ciphertext` exists on `oauth_tokens`
+     * (post-migration shape). The encrypted code path keys off this rather
+     * than re-running PRAGMA on every call.
+     */
+    private oauthTokensEncrypted;
+    /** True once `settings_ciphertext` is available on `user_preferences`. */
+    private userPrefsEncrypted;
+    constructor(workspacePath: string, cryptoOpts?: AuthServiceCryptoOptions);
     createUser(email: string, password: string, displayName: string, role?: UserRole): AuthUser;
+    /**
+     * Pick a unique handle by slugifying the display name (or email local-part
+     * fallback) and appending `-2`, `-3`, … on collision. Handles are immutable
+     * once assigned, so we don't have to worry about two parallel inserts
+     * racing — SQLite's UNIQUE constraint will reject the loser and the caller
+     * can retry.
+     */
+    private allocateHandle;
     authenticate(email: string, password: string): {
         user: AuthUser;
         token: string;
@@ -60,6 +126,18 @@ export declare class AuthService {
     findUserById(userId: number): AuthUser | null;
     listUsers(): AuthUser[];
     deleteUser(email: string): boolean;
+    /**
+     * Before deleting `targetUserId`, transfer folder-admin rights to
+     * `actorUserId` for every folder where the target is the sole admin.
+     * Inserts an admin folder_access row for the actor (or upgrades an
+     * existing editor row). Returns the list of folder names that were
+     * transferred so the caller can surface them in UX.
+     *
+     * This prevents folders from becoming orphaned (no admins) after the
+     * target user's folder_access rows cascade-delete. Folders with other
+     * admins are left alone — no redundant membership added.
+     */
+    transferFoldersOnDelete(targetUserId: number, actorUserId: number): string[];
     updateProfile(userId: number, fields: {
         displayName?: string;
         email?: string;
@@ -71,15 +149,35 @@ export declare class AuthService {
      */
     getOwner(): AuthUser | null;
     /**
-     * Transfer ownership to another user. The current owner becomes an admin.
+     * Transfer ownership to another user. The current owner becomes a regular member.
      * Both changes happen in a single transaction.
      */
     transferOwnership(currentOwnerId: number, newOwnerId: number): void;
-    grantCollectionAccess(userId: number, collectionName: string): void;
-    revokeCollectionAccess(userId: number, collectionName: string): void;
-    getUserCollections(userId: number): string[];
-    getCollectionUsers(collectionName: string): AuthUser[];
-    renameCollection(oldName: string, newName: string): void;
+    /** Grant folder membership. `role` defaults to 'editor'. Upserts the role if the row exists. */
+    grantFolderAccess(userId: number, folder: string, role?: FolderRole): void;
+    revokeFolderAccess(userId: number, folder: string): void;
+    /** Folder names the user is a member of. */
+    getUserFolders(userId: number): string[];
+    /** All users with any role on a folder. */
+    getFolderUsers(folder: string): AuthUser[];
+    /** (user, role) pairs for every member of a folder. */
+    getFolderMembers(folder: string): Array<{
+        user: AuthUser;
+        role: FolderRole;
+    }>;
+    /** Folder role for a specific user, or null if they aren't a member. */
+    getFolderRole(userId: number, folder: string): FolderRole | null;
+    /** True if the user is a folder admin on that folder. */
+    isFolderAdmin(userId: number, folder: string): boolean;
+    /** All users with folder-admin role on a folder. */
+    getFolderAdmins(folder: string): AuthUser[];
+    /**
+     * Transfer folder admin role from one user to another. Used during member
+     * removal to pass orphaned folders to the workspace owner.
+     */
+    transferFolderAdmin(folder: string, fromUserId: number, toUserId: number): void;
+    /** Rename the folder slug across all membership rows. */
+    renameFolder(oldName: string, newName: string): void;
     /** Get stored OAuth data (tokens, clientInfo, codeVerifier) for a user+connector. */
     getOAuthData(userId: number, connectorName: string): Record<string, any> | null;
     /** Save OAuth data (upsert). */
@@ -94,26 +192,61 @@ export declare class AuthService {
     hasOAuthTokens(userId: number, connectorName: string): boolean;
     hasUsers(): boolean;
     getUserCount(): number;
-    /** Get the workspace API key (for MCP and programmatic access). */
-    getApiKey(): string;
-    /** Check whether the given string matches the workspace API key. */
-    validateApiKey(key: string): boolean;
     /**
-     * Ensure the current API key is present in auth-seed.json and pushed to the
-     * config repo. Called on server startup so the key is always reachable by CLI.
-     * Non-fatal — never throws.
+     * Mint a new per-user API token. Returns the raw token once — only its
+     * sha256 hash is stored in the database. The raw value cannot be recovered
+     * later, matching how GitHub personal access tokens work.
+     */
+    createApiToken(userId: number, name: string): {
+        id: number;
+        token: string;
+        name: string;
+    };
+    /**
+     * Resolve a raw API token to its owning user, updating `last_used_at`
+     * on success. Returns null if the token is unknown or the owning user
+     * has been deleted.
      */
-    syncApiKeyToSeed(): void;
-    /** Regenerate the workspace API key. Returns the new key. */
-    regenerateApiKey(): string;
+    verifyApiToken(token: string): AuthUser | null;
+    /**
+     * Same as verifyApiToken but also returns the token's user-set name (e.g.
+     * "Cursor", "Claude Desktop"). Used by surfaces that need to attribute an
+     * action to a specific named integration — most importantly the
+     * agent-activity feature, which renders "<owner>'s <token name>" chips.
+     */
+    verifyApiTokenWithMeta(token: string): {
+        user: AuthUser;
+        tokenName: string;
+    } | null;
+    /** List a user's API tokens. Never returns the raw token — only metadata. */
+    listApiTokens(userId: number): Array<{
+        id: number;
+        name: string;
+        created_at: string;
+        last_used_at: string | null;
+    }>;
+    /** Revoke (delete) an API token owned by the given user. No-op if not found. */
+    revokeApiToken(tokenId: number, userId: number): boolean;
     /**
      * Ensure auth.db and auth-secret are in .studiograph/.gitignore.
      * Only the seed JSON file should be committed to the config repo.
      */
     private ensureGitignore;
     /**
-     * Build and return the current auth seed data (users + JWT secret + collection access).
+     * Build and return the current auth seed data (users + JWT secret + folder access).
      * Does not write to disk — use exportSeed() for that.
+     *
+     * SECURITY: the returned object embeds raw secrets:
+     *   • `jwtSecret` — signing key for ALL session tokens. Anyone holding this
+     *     can mint a valid session for any user. Rotate by setting
+     *     STUDIOGRAPH_JWT_SECRET in production and restarting.
+     *   • `users[].password_hash` — bcrypt hashes (cost 12). Offline-crackable
+     *     against weak passwords; treat as compromise of the listed accounts
+     *     if leaked.
+     *
+     * Only call this from paths that write to a trusted location (auth-seed.json
+     * inside the .studiograph/ config repo). Never expose over HTTP, never log,
+     * never include in error messages or telemetry.
      */
     getSeedData(): AuthSeed;
     /**
@@ -129,10 +262,20 @@ export declare class AuthService {
     private pushSeed;
     /**
      * Import users and JWT secret from .studiograph/auth-seed.json.
-     * Uses INSERT OR IGNORE so it's safe to call on non-empty databases
-     * (e.g. after `studiograph pull` brings a new seed file).
+     * Two modes:
+     *   • `merge` (default) — INSERT OR IGNORE on email. Existing local rows win
+     *     on conflict. Safe for boot-time recovery when the local DB may carry
+     *     legitimate state the seed shouldn't clobber.
+     *   • `overwrite` — UPSERT on email. Seed values win on conflict. Correct
+     *     for explicit "remote is authoritative" callers (`studiograph pull`,
+     *     `studiograph clone`, admin bundle import) where any local divergence
+     *     was almost certainly the post-clone setup-wizard stamping fresh
+     *     credentials over the real ones. `merge` mode silently shadowed
+     *     production credentials in that exact scenario — see 2026-05 incident.
      */
-    applySeed(): void;
+    applySeed(options?: {
+        mode?: 'merge' | 'overwrite';
+    }): void;
     getUserViews(userId: number): UserView[];
     createUserView(userId: number, name: string, viewType?: string, config?: Record<string, any>, createdByName?: string): UserView;
     setViewVisibility(viewId: number, userId: number, visibility: 'private' | 'workspace'): void;
@@ -160,15 +303,20 @@ export declare class AuthService {
     setAccentColor(userId: number, color: string | null): void;
     getOnboarded(userId: number): boolean;
     setOnboarded(userId: number, value: boolean): void;
+    /**
+     * Reset per-user state used by the agent: onboarding flag, cached briefing,
+     * home brief, and meeting-capture settings (Deepgram key, calendar, default
+     * folder). Preserves the user account, accent color, and minted API tokens.
+     * Used by `POST /api/reset` to put a tester back to a clean slate without
+     * a redeploy or DB surgery.
+     */
+    resetUserState(userId: number): void;
     getHomeBrief(userId: number): string;
     setHomeBrief(userId: number, brief: string): void;
-    getCachedInsights(userId: number): {
-        insights: any[];
-        generatedAt: string | null;
-    };
-    setCachedInsights(userId: number, insights: any[]): void;
-    /** Returns ms since insights were last generated, or null if never generated. */
-    getCachedInsightsAge(userId: number): number | null;
+    getUserSettings(userId: number): Record<string, any>;
+    setUserSettings(userId: number, settings: Record<string, any>): void;
+    getUserSetting(userId: number, key: string): any;
+    setUserSetting(userId: number, key: string, value: any): void;
     getCachedBriefing(userId: number): {
         briefingText: string | null;
         previousBriefingText: string | null;