studiograph 1.3.48-next.21 → 1.3.48-next.210

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

@@ -5,20 +5,53 @@
  * 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';
+import { type OAuthStateClaims } from '../mcp/state-signer.js';
+import { OAuthServerStore } from './oauth-server-store.js';
+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;
@@ -30,36 +63,163 @@ export interface UserView {
     createdAt: string;
     updatedAt: string;
 }
+/**
+ * A workspace-shared view, scoped to a folder / type / `recent` (the
+ * folder-views redesign). Unlike UserView these are NOT per-user — they belong
+ * to the workspace and everyone sees the same set. One per (scope, viewType).
+ */
+export interface WorkspaceView {
+    id: number;
+    scope: string;
+    viewType: string;
+    config: Record<string, any>;
+    position: number;
+    name: string | null;
+    createdBy: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
 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;
+    /**
+     * Listeners for OAuth-token mutations. Fires after `saveOAuthData` or
+     * `clearOAuthData` lands a row. Used by the agent orchestrator to evict
+     * the user's pooled agent so the next chat builds a fresh tool list
+     * that reflects the new per-user connector state (otherwise the agent
+     * keeps the toolset it had at first session creation, missing any
+     * connector the user just OAuthed). Mirrors the `onSecretMutation`
+     * pattern in `src/core/secrets/index.ts`.
+     *
+     * Listener errors are swallowed — never let a stray subscriber take
+     * down the OAuth write path.
+     */
+    private oauthMutationListeners;
+    /**
+     * OAuth state signer. Initialized lazily from the master key (HKDF-derived,
+     * domain-separated from the AEAD key). When `cryptoOpts` is missing — e.g.
+     * tests that don't exercise the OAuth init/callback paths — sign/verify
+     * throw on use rather than silently falling back to unsigned state.
+     */
+    private oauthStateSigner;
+    /** OAuth 2.0 authorization-server store. Initialized at the end of the constructor. */
+    private oauthServerStore;
+    constructor(workspacePath: string, cryptoOpts?: AuthServiceCryptoOptions);
+    /** The OAuth authorization-server store (clients/codes/refresh + minting). */
+    get oauthServer(): OAuthServerStore;
     createUser(email: string, password: string, displayName: string, role?: UserRole): AuthUser;
+    upsertCloudManagedUser(input: {
+        email: 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;
     } | null;
+    createSessionToken(user: AuthUser): string;
+    /** Expose the resolved JWT secret to sibling services that mint their own
+     *  signed tokens against the same key (e.g. `asset-upload-token` for the
+     *  MCP presign flow). Reusing one secret keeps "rotate the JWT" a single
+     *  operational lever instead of N parallel ones. The secret never leaves
+     *  the server process. */
+    getJwtSecret(): string;
+    /**
+     * Resolve a session JWT to its user. **Rejects OAuth access tokens**
+     * (`oauth:true`) — those are authorization-server-issued and confined to the
+     * MCP surface, so they must never satisfy a session check. This is the
+     * choke point: every hook-bypassing surface that authenticates a JWT
+     * (`requireUser` for `/api/auth/*`, Git Basic-auth, the WebSocket route, the
+     * cookie branch of the global hook) calls this, so rejecting OAuth tokens
+     * here closes all of them at once. The single place that intentionally
+     * accepts an OAuth token — the global hook's Bearer→`/mcp` branch — uses
+     * `verifyTokenWithClaims` directly and enforces audience scoping there.
+     */
     verifyToken(token: string): AuthUser | null;
+    /**
+     * Verify a session/OAuth JWT in a single decode and surface the OAuth-specific
+     * claims the auth hook needs: `oauth` marks an authorization-server-issued
+     * token (which the hook scopes to `/mcp` + `/oauth/*`), `cid` is the issuing
+     * client_id (used as the integration label), and `aud` is the bound resource.
+     * Returns null for any invalid/expired token or unknown user.
+     */
+    verifyTokenWithClaims(token: string): {
+        user: AuthUser;
+        oauth: boolean;
+        cid: string | null;
+        aud: string | null;
+    } | null;
     findUserById(userId: number): AuthUser | null;
+    /** Look up a user by their stable handle (e.g. `christian-marc-schmidt`). */
+    findUserByHandle(handle: string): AuthUser | null;
+    /** Look up a user by email (case-insensitive). */
+    findUserByEmail(email: string): 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,17 +231,64 @@ 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;
+    /**
+     * Sign an OAuth state parameter for outbound flows. Throws when the service
+     * was constructed without crypto options (the signing key is HKDF-derived
+     * from the master key). Callers in OAuth init paths must ensure the
+     * AuthService is constructed with crypto options — production always is;
+     * tests that exercise OAuth flows should provide a master key.
+     */
+    signOAuthState(claims: OAuthStateClaims): string;
+    /**
+     * Verify a signed OAuth state. Returns null on:
+     *   - missing/invalid signing key (defensive — should not happen in
+     *     production where serve.ts wires the master key)
+     *   - tampered / forged / unsigned state
+     *   - state older than 10 minutes (replay window)
+     *   - state with future-skewed `t` beyond a small tolerance
+     * Callers should treat null as "invalid/expired state" and surface a
+     * generic error to the browser without echoing details.
+     */
+    verifyOAuthState(state: string): OAuthStateClaims | null;
+    /**
+     * Subscribe to OAuth-token mutations. Returns an unsubscribe fn.
+     * Listeners fire AFTER the row write commits. Both connect and disconnect
+     * paths emit; subscribers that only care about one should filter
+     * themselves.
+     */
+    onOAuthMutation(fn: (userId: number, connectorName: string) => void): () => void;
+    private notifyOAuthMutation;
     /** Save OAuth data (upsert). */
     saveOAuthData(userId: number, connectorName: string, data: Record<string, any>): void;
     /** List all connected connectors for a user. */
@@ -94,26 +301,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.
+     */
+    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.
      */
-    syncApiKeyToSeed(): void;
-    /** Regenerate the workspace API key. Returns the new key. */
-    regenerateApiKey(): string;
+    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 +371,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;
@@ -143,6 +395,30 @@ export declare class AuthService {
         sortOrder?: number;
     }): void;
     deleteUserView(viewId: number, userId: number): void;
+    private toWorkspaceView;
+    /** All views for a scope, in tab order. */
+    getViewsForScope(scope: string): WorkspaceView[];
+    getWorkspaceView(viewId: number): WorkspaceView | null;
+    /**
+     * Add a view to a scope. One-of-each is enforced by UNIQUE(scope, view_type):
+     * a duplicate is a no-op that returns the existing row, so callers (and the
+     * "+" menu) never create dupes.
+     */
+    createWorkspaceView(scope: string, viewType: string, config?: Record<string, any>, createdBy?: string): WorkspaceView;
+    updateWorkspaceView(viewId: number, fields: {
+        config?: Record<string, any>;
+        position?: number;
+        name?: string | null;
+    }): void;
+    deleteWorkspaceView(viewId: number): void;
+    /**
+     * Idempotently seed a scope's default views (called on first GET for a scope).
+     * Every scope (folder, type, recent) seeds with just List — the user adds
+     * additional views via the manage popover. INSERT OR IGNORE + UNIQUE(scope,
+     * view_type) makes this safe to call on every access and race-safe across
+     * concurrent loads.
+     */
+    ensureViewsForScope(scope: string): WorkspaceView[];
     private _viewMigrationDone;
     /**
      * Create default workspace views based on which entity types have data.
@@ -160,26 +436,17 @@ export declare class AuthService {
     setAccentColor(userId: number, color: string | null): void;
     getOnboarded(userId: number): boolean;
     setOnboarded(userId: number, value: boolean): void;
-    getHomeBrief(userId: number): string;
-    setHomeBrief(userId: number, brief: string): void;
+    /**
+     * Reset per-user state used by the agent: onboarding flag 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;
     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;
-    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;
-    getCachedBriefing(userId: number): {
-        briefingText: string | null;
-        previousBriefingText: string | null;
-        generatedAt: string | null;
-    };
-    setCachedBriefing(userId: number, briefingText: string): void;
-    getCachedBriefingAge(userId: number): number | null;
     close(): void;
     private toAuthUser;
 }