Humans and Permissions Implementation (V1)

Status: Draft Date: 2026-02-21 Owners: Server + UI + CLI + DB + Shared Companion plan: doc/plan/humans-and-permissions.md

1. Document role

This document is the engineering implementation contract for the humans-and-permissions plan. It translates product decisions into concrete schema, API, middleware, UI, CLI, and test work.

If this document conflicts with prior exploratory notes, this document wins for V1 execution.

2. Locked V1 decisions

1. Two deployment modes remain:

• local_trusted
• cloud_hosted

2. local_trusted:

• no login UX
• implicit local instance admin actor
• loopback-only server binding
• full admin/settings/invite/approval capabilities available locally

3. cloud_hosted:

• Better Auth for humans
• email/password only
• no email verification requirement in V1

4. Permissions:

• one shared authorization system for humans and agents
• normalized grants table (principal_permission_grants)
• no separate “agent permissions engine”

5. Invites:

• copy-link only (no outbound email sending in V1)
• unified company_join link that supports human or agent path
• acceptance creates pending_approval join request
• no access until admin approval

6. Join review metadata:

• source IP required
• no GeoIP/country lookup in V1

7. Agent API keys:

• indefinite by default
• hash at rest
• display once on claim
• revoke/regenerate supported

8. Local ingress:

• public/untrusted ingress is out of scope for V1
• no --dangerous-agent-ingress in V1

3. Current baseline and delta

Current baseline (repo as of this doc):

• server actor model defaults to board in server/src/middleware/auth.ts
• authorization is mostly assertBoard + company check in server/src/routes/authz.ts
• no human auth/session tables in local schema
• no principal membership or grants tables
• no invite or join-request lifecycle

Required delta:

• move from board-vs-agent authz to principal-based authz
• add Better Auth integration in cloud mode
• add membership/grants/invite/join-request persistence
• add approval inbox signals and actions
• preserve local no-login UX without weakening cloud security

4. Architecture

4.1 Deployment mode contract

Add explicit runtime mode:

• deployment.mode = local_trusted | cloud_hosted

Config behavior:

• mode stored in config file (packages/shared/src/config-schema.ts)
• loaded in server config (server/src/config.ts)
• surfaced in /api/health

Startup guardrails:

• local_trusted: fail startup if bind host is not loopback
• cloud_hosted: fail startup if Better Auth is not configured

4.2 Actor model

Replace implicit “board” semantics with explicit actors:

• user (session-authenticated human)
• agent (bearer API key)
• local_implicit_admin (local_trusted only)

Implementation note:

• keep req.actor shape backward-compatible during migration by introducing a normalizer helper
• remove hard-coded "board" checks route-by-route after new authz helpers are in place

4.3 Authorization model

Authorization input tuple:

• (company_id, principal_type, principal_id, permission_key, scope_payload)

Principal types:

• user
• agent

Role layers:

• instance_admin (instance-wide)
• company-scoped grants via principal_permission_grants

Evaluation order:

1. resolve principal from actor
2. resolve instance role (instance_admin short-circuit for admin-only actions)
3. resolve company membership (active required for company access)
4. resolve grant + scope for requested action

5. Data model

5.1 Better Auth tables

Managed by Better Auth adapter/migrations (expected minimum):

• user
• session
• account
• verification

Note:

• use Better Auth canonical table names/types to avoid custom forks

5.2 New Paperclip tables

1. instance_user_roles

• id uuid pk
• user_id text not null
• role text not null (instance_admin)
• created_at, updated_at
• unique index: (user_id, role)

2. company_memberships

• id uuid pk
• company_id uuid fk companies.id not null
• principal_type text not null (user | agent)
• principal_id text not null
• status text not null (pending | active | suspended)
• membership_role text null
• created_at, updated_at
• unique index: (company_id, principal_type, principal_id)
• index: (principal_type, principal_id, status)

3. principal_permission_grants

• id uuid pk
• company_id uuid fk companies.id not null
• principal_type text not null (user | agent)
• principal_id text not null
• permission_key text not null
• scope jsonb null
• granted_by_user_id text null
• created_at, updated_at
• unique index: (company_id, principal_type, principal_id, permission_key)
• index: (company_id, permission_key)

4. invites

• id uuid pk
• company_id uuid fk companies.id not null
• invite_type text not null (company_join | bootstrap_ceo)
• token_hash text not null
• allowed_join_types text not null (human | agent | both) for company_join
• defaults_payload jsonb null
• expires_at timestamptz not null
• invited_by_user_id text null
• revoked_at timestamptz null
• accepted_at timestamptz null
• created_at timestamptz not null default now()
• unique index: (token_hash)
• index: (company_id, invite_type, revoked_at, expires_at)

5. join_requests

• id uuid pk
• invite_id uuid fk invites.id not null
• company_id uuid fk companies.id not null
• request_type text not null (human | agent)
• status text not null (pending_approval | approved | rejected)
• request_ip text not null
• requesting_user_id text null
• request_email_snapshot text null
• agent_name text null
• adapter_type text null
• capabilities text null
• agent_defaults_payload jsonb null
• created_agent_id uuid fk agents.id null
• approved_by_user_id text null
• approved_at timestamptz null
• rejected_by_user_id text null
• rejected_at timestamptz null
• created_at, updated_at
• index: (company_id, status, request_type, created_at desc)
• unique index: (invite_id) to enforce one request per consumed invite

5.3 Existing table changes

1. issues

• add assignee_user_id text null
• enforce single-assignee invariant:
  • at most one of assignee_agent_id and assignee_user_id is non-null

2. agents

• keep existing permissions JSON for transition only
• mark as deprecated in code path once principal grants are live

5.4 Migration strategy

Migration ordering:

1. add new tables/columns/indexes
2. backfill minimum memberships/grants for existing data:

• create local implicit admin membership context in local mode at runtime (not persisted as Better Auth user)
• for cloud, bootstrap creates first admin user role on acceptance

3. switch authz reads to new tables
4. remove legacy board-only checks

6. API contract (new/changed)

All under /api.

6.1 Health

GET /api/health response additions:

• deploymentMode
• authReady
• bootstrapStatus (ready | bootstrap_pending)

6.2 Invites

1. POST /api/companies/:companyId/invites

• create company_join invite
• copy-link value returned once

2. GET /api/invites/:token

• validate token
• return invite landing payload
• includes allowedJoinTypes

3. POST /api/invites/:token/accept

• body:
  • requestType: human | agent
  • human path: no extra payload beyond authenticated user
  • agent path: agentName, adapterType, capabilities, optional adapter defaults
• consumes invite token
• creates join_requests(status=pending_approval)

4. POST /api/invites/:inviteId/revoke

• revokes non-consumed invite

6.3 Join requests

1. GET /api/companies/:companyId/join-requests?status=pending_approval&requestType=...

2. POST /api/companies/:companyId/join-requests/:requestId/approve

• human:
  • create/activate company_memberships
  • apply default grants
• agent:
  • create agents row
  • create pending claim context for API key
  • create/activate agent membership
  • apply default grants

3. POST /api/companies/:companyId/join-requests/:requestId/reject

4. POST /api/join-requests/:requestId/claim-api-key

• approved agent request only
• returns plaintext key once
• stores hash in agent_api_keys

6.4 Membership and grants

1. GET /api/companies/:companyId/members

• returns both principal types

2. PATCH /api/companies/:companyId/members/:memberId/permissions

• upsert/remove grants

3. PUT /api/admin/users/:userId/company-access

• instance admin only

4. GET /api/admin/users/:userId/company-access

5. POST /api/admin/users/:userId/promote-instance-admin

6. POST /api/admin/users/:userId/demote-instance-admin

6.5 Inbox

GET /api/companies/:companyId/inbox additions:

• pending join request alert items when actor can joins:approve
• each item includes inline action metadata:
  • join request id
  • request type
  • source IP
  • human email snapshot when applicable

7. Server implementation details

7.1 Config and startup

Files:

• packages/shared/src/config-schema.ts
• server/src/config.ts
• server/src/index.ts
• server/src/startup-banner.ts

Changes:

• add deployment mode + bind host settings
• enforce loopback-only for local_trusted
• enforce Better Auth readiness in cloud_hosted
• banner shows mode and bootstrap status

7.2 Better Auth integration

Files:

• server/package.json (dependency)
• server/src/auth/* (new)
• server/src/app.ts (mount auth handler endpoints + session middleware)

Changes:

• add Better Auth server instance
• cookie/session handling for cloud mode
• no-op session auth in local mode

7.3 Actor middleware

Files:

• server/src/middleware/auth.ts
• server/src/routes/authz.ts
• server/src/middleware/board-mutation-guard.ts

Changes:

• stop defaulting every request to board in cloud mode
• map local requests to local_implicit_admin actor in local mode
• map Better Auth session to user actor in cloud mode
• preserve agent bearer path
• replace assertBoard with permission-oriented helpers:
  • requireInstanceAdmin(req)
  • requireCompanyAccess(req, companyId)
  • requireCompanyPermission(req, companyId, permissionKey, scope?)

7.4 Authorization services

Files:

• server/src/services (new modules)
  • memberships.ts
  • permissions.ts
  • invites.ts
  • join-requests.ts
  • instance-admin.ts

Changes:

• centralized permission evaluation
• centralized membership resolution
• one place for principal-type branching

7.5 Routes

Files:

• server/src/routes/index.ts and new route modules:
  • auth.ts (if needed)
  • invites.ts
  • join-requests.ts
  • members.ts
  • instance-admin.ts
  • inbox.ts (or extension of existing inbox source)

Changes:

• add new endpoints listed above
• apply company and permission checks consistently
• log all mutations through activity log service

7.6 Activity log and audit

Files:

• server/src/services/activity-log.ts
• call sites in invite/join/member/admin routes

Required actions:

• invite.created
• invite.revoked
• join.requested
• join.approved
• join.rejected
• membership.activated
• permission.granted
• permission.revoked
• instance_admin.promoted
• instance_admin.demoted
• agent_api_key.claimed
• agent_api_key.revoked

7.7 Real-time and inbox propagation

Files:

• server/src/services/live-events.ts
• server/src/realtime/live-events-ws.ts
• inbox data source endpoint(s)

Changes:

• emit join-request events
• ensure inbox refresh path includes join alerts

8. CLI implementation

Files:

• cli/src/index.ts
• cli/src/commands/onboard.ts
• cli/src/commands/configure.ts
• cli/src/prompts/server.ts

Commands:

1. paperclipai auth bootstrap-ceo

• create bootstrap invite
• print one-time URL

2. paperclipai onboard

• in cloud mode with bootstrap_pending, print bootstrap URL and next steps
• in local mode, skip bootstrap requirement

Config additions:

• deployment mode
• bind host (validated against mode)

9. UI implementation

Files:

• routing: ui/src/App.tsx
• API clients: ui/src/api/*
• pages/components (new):
  • AuthLogin / AuthSignup (cloud mode)
  • BootstrapPending page
  • InviteLanding page
  • InstanceSettings page
  • join approval components in Inbox
  • member/grant management in company settings

Required UX:

1. Cloud unauthenticated user:

• redirect to login/signup

2. Cloud bootstrap pending:

• block app with setup command guidance

3. Invite landing:

• choose human vs agent path (respect allowedJoinTypes)
• submit join request
• show pending approval confirmation

4. Inbox:

• show join approval cards with approve/reject actions
• include source IP and human email snapshot when applicable

5. Local mode:

• no login prompts
• full settings/invite/approval UI available

10. Security controls

1. Token handling

• invite tokens hashed at rest
• API keys hashed at rest
• one-time plaintext key reveal only

2. Local mode isolation

• loopback bind enforcement
• startup hard-fail on non-loopback host

3. Cloud auth

• no implicit board fallback
• session auth mandatory for human mutations

4. Join workflow hardening

• one request per invite token
• pending request has no data access
• approval required before membership activation

5. Abuse controls

• rate limit invite accept and key claim endpoints
• structured logging for join and claim failures

11. Migration and compatibility

11.1 Runtime compatibility

• keep existing board-dependent routes functional while migrating authz helper usage
• phase out assertBoard calls only after permission helpers cover all routes

11.2 Data compatibility

• do not delete agents.permissions in V1
• stop reading it once grants are wired
• remove in post-V1 cleanup migration

11.3 Better Auth user ID handling

• treat user.id as text end-to-end
• existing created_by_user_id and similar text fields remain valid

12. Testing strategy

12.1 Unit tests

• permission evaluator:
  • instance admin bypass
  • grant checks
  • scope checks
• join approval state machine
• invite token lifecycle

12.2 Integration tests

• cloud mode unauthenticated mutation -> 401
• local mode implicit admin mutation -> success
• invite accept -> pending join -> no access
• join approve (human) -> membership/grants active
• join approve (agent) -> key claim once
• cross-company access denied for user and agent principals
• local mode non-loopback bind -> startup failure

12.3 UI tests

• login gate in cloud mode
• bootstrap pending screen
• invite landing choose-path UX
• inbox join alert approve/reject flows

12.4 Regression tests

• existing agent API key flows still work
• task assignment and checkout invariants unchanged
• activity logging still emitted for all mutations

13. Delivery plan

Phase A: Foundations

• config mode/bind host support
• startup guardrails
• Better Auth integration skeleton
• actor type expansion

Phase B: Schema and authz core

• add membership/grants/invite/join tables
• add permission service and helpers
• wire company/member/instance admin checks

Phase C: Invite + join backend

• invite create/revoke
• invite accept -> pending request
• approve/reject + key claim
• activity log + live events

Phase D: UI + CLI

• cloud login/bootstrap screens
• invite landing
• inbox join approval actions
• instance settings and member permissions
• bootstrap CLI command and onboarding updates

Phase E: Hardening

• full integration/e2e coverage
• docs updates (SPEC-implementation, DEVELOPING, CLI)
• cleanup of legacy board-only codepaths

14. Verification gate

Before handoff:

pnpm -r typecheck
pnpm test:run
pnpm build

If any command is skipped, record exactly what was skipped and why.

15. Done criteria

1. Behavior matches locked V1 decisions in this doc and doc/plan/humans-and-permissions.md.
2. Cloud mode requires auth; local mode has no login UX.
3. Unified invite + pending approval flow works for both humans and agents.
4. Shared principal membership + permission system is live for users and agents.
5. Local mode remains loopback-only and fails otherwise.
6. Inbox shows actionable join approvals.
7. All new mutating paths are activity-logged.