feat: add auth/access foundation - deps, DB schema, shared types, and config

Add Better Auth, drizzle-orm, @dnd-kit, and remark-gfm dependencies.
Introduce DB schema for auth tables (user, session, account, verification),
company memberships, instance user roles, permission grants, invites, and
join requests. Add assigneeUserId to issues. Extend shared config schema
with deployment mode/exposure/auth settings, add access types and validators,
and wire up new API path constants.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

packages/shared/src/api.ts

@@ -13,4 +13,8 @@ export const API = {
   activity: `${API_PREFIX}/activity`,
   dashboard: `${API_PREFIX}/dashboard`,
   sidebarBadges: `${API_PREFIX}/sidebar-badges`,
+  invites: `${API_PREFIX}/invites`,
+  joinRequests: `${API_PREFIX}/join-requests`,
+  members: `${API_PREFIX}/members`,
+  admin: `${API_PREFIX}/admin`,
 } as const;

packages/shared/src/config-schema.ts

@@ -1,5 +1,11 @@
 import { z } from "zod";
-import { SECRET_PROVIDERS, STORAGE_PROVIDERS } from "./constants.js";
+import {
+  AUTH_BASE_URL_MODES,
+  DEPLOYMENT_EXPOSURES,
+  DEPLOYMENT_MODES,
+  SECRET_PROVIDERS,
+  STORAGE_PROVIDERS,
+} from "./constants.js";
 
 export const configMetaSchema = z.object({
   version: z.literal(1),
@@ -25,10 +31,18 @@ export const loggingConfigSchema = z.object({
 });
 
 export const serverConfigSchema = z.object({
+  deploymentMode: z.enum(DEPLOYMENT_MODES).default("local_trusted"),
+  exposure: z.enum(DEPLOYMENT_EXPOSURES).default("private"),
+  host: z.string().default("127.0.0.1"),
   port: z.number().int().min(1).max(65535).default(3100),
   serveUi: z.boolean().default(true),
 });
 
+export const authConfigSchema = z.object({
+  baseUrlMode: z.enum(AUTH_BASE_URL_MODES).default("auto"),
+  publicBaseUrl: z.string().url().optional(),
+});
+
 export const storageLocalDiskConfigSchema = z.object({
   baseDir: z.string().default("~/.paperclip/instances/default/data/storage"),
 });
@@ -66,32 +80,72 @@ export const secretsConfigSchema = z.object({
   }),
 });
 
-export const paperclipConfigSchema = z.object({
-  $meta: configMetaSchema,
-  llm: llmConfigSchema.optional(),
-  database: databaseConfigSchema,
-  logging: loggingConfigSchema,
-  server: serverConfigSchema,
-  storage: storageConfigSchema.default({
-    provider: "local_disk",
-    localDisk: {
-      baseDir: "~/.paperclip/instances/default/data/storage",
-    },
-    s3: {
-      bucket: "paperclip",
-      region: "us-east-1",
-      prefix: "",
-      forcePathStyle: false,
-    },
-  }),
-  secrets: secretsConfigSchema.default({
-    provider: "local_encrypted",
-    strictMode: false,
-    localEncrypted: {
-      keyFilePath: "~/.paperclip/instances/default/secrets/master.key",
-    },
-  }),
-});
+export const paperclipConfigSchema = z
+  .object({
+    $meta: configMetaSchema,
+    llm: llmConfigSchema.optional(),
+    database: databaseConfigSchema,
+    logging: loggingConfigSchema,
+    server: serverConfigSchema,
+    auth: authConfigSchema.default({
+      baseUrlMode: "auto",
+    }),
+    storage: storageConfigSchema.default({
+      provider: "local_disk",
+      localDisk: {
+        baseDir: "~/.paperclip/instances/default/data/storage",
+      },
+      s3: {
+        bucket: "paperclip",
+        region: "us-east-1",
+        prefix: "",
+        forcePathStyle: false,
+      },
+    }),
+    secrets: secretsConfigSchema.default({
+      provider: "local_encrypted",
+      strictMode: false,
+      localEncrypted: {
+        keyFilePath: "~/.paperclip/instances/default/secrets/master.key",
+      },
+    }),
+  })
+  .superRefine((value, ctx) => {
+    if (value.server.deploymentMode === "local_trusted") {
+      if (value.server.exposure !== "private") {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "server.exposure must be private when deploymentMode is local_trusted",
+          path: ["server", "exposure"],
+        });
+      }
+      return;
+    }
+
+    if (value.auth.baseUrlMode === "explicit" && !value.auth.publicBaseUrl) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "auth.publicBaseUrl is required when auth.baseUrlMode is explicit",
+        path: ["auth", "publicBaseUrl"],
+      });
+    }
+
+    if (value.server.exposure === "public" && value.auth.baseUrlMode !== "explicit") {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "auth.baseUrlMode must be explicit when deploymentMode=authenticated and exposure=public",
+        path: ["auth", "baseUrlMode"],
+      });
+    }
+
+    if (value.server.exposure === "public" && !value.auth.publicBaseUrl) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "auth.publicBaseUrl is required when deploymentMode=authenticated and exposure=public",
+        path: ["auth", "publicBaseUrl"],
+      });
+    }
+  });
 
 export type PaperclipConfig = z.infer<typeof paperclipConfigSchema>;
 export type LlmConfig = z.infer<typeof llmConfigSchema>;
@@ -103,4 +157,5 @@ export type StorageLocalDiskConfig = z.infer<typeof storageLocalDiskConfigSchema
 export type StorageS3Config = z.infer<typeof storageS3ConfigSchema>;
 export type SecretsConfig = z.infer<typeof secretsConfigSchema>;
 export type SecretsLocalEncryptedConfig = z.infer<typeof secretsLocalEncryptedConfigSchema>;
+export type AuthConfig = z.infer<typeof authConfigSchema>;
 export type ConfigMeta = z.infer<typeof configMetaSchema>;

packages/shared/src/types/access.ts

@@ -0,0 +1,78 @@
+import type {
+  InstanceUserRole,
+  InviteJoinType,
+  InviteType,
+  JoinRequestStatus,
+  JoinRequestType,
+  MembershipStatus,
+  PermissionKey,
+  PrincipalType,
+} from "../constants.js";
+
+export interface CompanyMembership {
+  id: string;
+  companyId: string;
+  principalType: PrincipalType;
+  principalId: string;
+  status: MembershipStatus;
+  membershipRole: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface PrincipalPermissionGrant {
+  id: string;
+  companyId: string;
+  principalType: PrincipalType;
+  principalId: string;
+  permissionKey: PermissionKey;
+  scope: Record<string, unknown> | null;
+  grantedByUserId: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface Invite {
+  id: string;
+  companyId: string | null;
+  inviteType: InviteType;
+  tokenHash: string;
+  allowedJoinTypes: InviteJoinType;
+  defaultsPayload: Record<string, unknown> | null;
+  expiresAt: Date;
+  invitedByUserId: string | null;
+  revokedAt: Date | null;
+  acceptedAt: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface JoinRequest {
+  id: string;
+  inviteId: string;
+  companyId: string;
+  requestType: JoinRequestType;
+  status: JoinRequestStatus;
+  requestIp: string;
+  requestingUserId: string | null;
+  requestEmailSnapshot: string | null;
+  agentName: string | null;
+  adapterType: string | null;
+  capabilities: string | null;
+  agentDefaultsPayload: Record<string, unknown> | null;
+  createdAgentId: string | null;
+  approvedByUserId: string | null;
+  approvedAt: Date | null;
+  rejectedByUserId: string | null;
+  rejectedAt: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface InstanceUserRoleGrant {
+  id: string;
+  userId: string;
+  role: InstanceUserRole;
+  createdAt: Date;
+  updatedAt: Date;
+}

packages/shared/src/types/index.ts

@@ -43,3 +43,10 @@ export type { LiveEvent } from "./live.js";
 export type { DashboardSummary } from "./dashboard.js";
 export type { ActivityEvent } from "./activity.js";
 export type { SidebarBadges } from "./sidebar-badges.js";
+export type {
+  CompanyMembership,
+  PrincipalPermissionGrant,
+  Invite,
+  JoinRequest,
+  InstanceUserRoleGrant,
+} from "./access.js";

packages/shared/src/types/issue.ts

@@ -24,6 +24,7 @@ export interface IssueAncestor {
   status: string;
   priority: string;
   assigneeAgentId: string | null;
+  assigneeUserId: string | null;
   projectId: string | null;
   goalId: string | null;
   project: IssueAncestorProject | null;
@@ -42,6 +43,7 @@ export interface Issue {
   status: IssueStatus;
   priority: IssuePriority;
   assigneeAgentId: string | null;
+  assigneeUserId: string | null;
   checkoutRunId: string | null;
   executionRunId: string | null;
   executionAgentNameKey: string | null;

packages/shared/src/types/sidebar-badges.ts

@@ -2,4 +2,5 @@ export interface SidebarBadges {
   inbox: number;
   approvals: number;
   failedRuns: number;
+  joinRequests: number;
 }

packages/shared/src/validators/access.ts

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import {
+  INVITE_JOIN_TYPES,
+  JOIN_REQUEST_STATUSES,
+  JOIN_REQUEST_TYPES,
+  PERMISSION_KEYS,
+} from "../constants.js";
+
+export const createCompanyInviteSchema = z.object({
+  allowedJoinTypes: z.enum(INVITE_JOIN_TYPES).default("both"),
+  expiresInHours: z.number().int().min(1).max(24 * 30).optional().default(72),
+  defaultsPayload: z.record(z.string(), z.unknown()).optional().nullable(),
+});
+
+export type CreateCompanyInvite = z.infer<typeof createCompanyInviteSchema>;
+
+export const acceptInviteSchema = z.object({
+  requestType: z.enum(JOIN_REQUEST_TYPES),
+  agentName: z.string().min(1).max(120).optional(),
+  adapterType: z.string().min(1).max(120).optional(),
+  capabilities: z.string().max(4000).optional().nullable(),
+  agentDefaultsPayload: z.record(z.string(), z.unknown()).optional().nullable(),
+});
+
+export type AcceptInvite = z.infer<typeof acceptInviteSchema>;
+
+export const listJoinRequestsQuerySchema = z.object({
+  status: z.enum(JOIN_REQUEST_STATUSES).optional(),
+  requestType: z.enum(JOIN_REQUEST_TYPES).optional(),
+});
+
+export type ListJoinRequestsQuery = z.infer<typeof listJoinRequestsQuerySchema>;
+
+export const updateMemberPermissionsSchema = z.object({
+  grants: z.array(
+    z.object({
+      permissionKey: z.enum(PERMISSION_KEYS),
+      scope: z.record(z.string(), z.unknown()).optional().nullable(),
+    }),
+  ),
+});
+
+export type UpdateMemberPermissions = z.infer<typeof updateMemberPermissionsSchema>;
+
+export const updateUserCompanyAccessSchema = z.object({
+  companyIds: z.array(z.string().uuid()).default([]),
+});
+
+export type UpdateUserCompanyAccess = z.infer<typeof updateUserCompanyAccessSchema>;

packages/shared/src/validators/index.ts

@@ -91,3 +91,16 @@ export {
   createAssetImageMetadataSchema,
   type CreateAssetImageMetadata,
 } from "./asset.js";
+
+export {
+  createCompanyInviteSchema,
+  acceptInviteSchema,
+  listJoinRequestsQuerySchema,
+  updateMemberPermissionsSchema,
+  updateUserCompanyAccessSchema,
+  type CreateCompanyInvite,
+  type AcceptInvite,
+  type ListJoinRequestsQuery,
+  type UpdateMemberPermissions,
+  type UpdateUserCompanyAccess,
+} from "./access.js";

packages/shared/src/validators/issue.ts

@@ -10,6 +10,7 @@ export const createIssueSchema = z.object({
   status: z.enum(ISSUE_STATUSES).optional().default("backlog"),
   priority: z.enum(ISSUE_PRIORITIES).optional().default("medium"),
   assigneeAgentId: z.string().uuid().optional().nullable(),
+  assigneeUserId: z.string().optional().nullable(),
   requestDepth: z.number().int().nonnegative().optional().default(0),
   billingCode: z.string().optional().nullable(),
 });