Skip to content

The open-source app everyone uses to manage agents at work

5.7 KB
Raw Blame

navigation: {"section":"Getting started and access","sectionOrder":10,"order":20}

Login, invitations, and access

People and agents enter the correct instance and company with the permissions granted to their identity. Login, membership, resource access, and CLI authorization have separate controls.

Feature ID: access.

Implementation: auth page, company members, invitation.

Agent access: companion.

Sub-features

  • login: access/login — sign in or claim the board in the configured deployment mode.
  • invitations: access/invitations — join through a valid invite and handle expired or already-used links.
  • membership: access/membership — review join requests and manage company/instance membership and permissions.
  • resources: access/resources — respect company and resource boundaries on deep links and mutations.
  • cli-auth: access/cli-auth — authorize a CLI session and revoke or replace credentials.

How to get to it (user POV)

login

Open /auth; first-owner bootstrap uses /board-claim/:token when configured.

invite-members

Open /invite/:token; operators manage members in company settings and join requests at /inbox/requests. Create/revoke human links at Members → Invites (/company/settings/members?tab=invites). Human invitees receive the chosen role after sign-in; agent invitations still use join-request approval.

cli-authorization

Start the CLI auth/connect flow and approve its /cli-auth/:id browser page; instance access is under Settings when visible.

Driving it with Playwright and the Paperclip CLI

Preconditions: follow the baseline. For login tests use authenticated mode and two test users; local-trusted mode does not prove session enforcement. Use two companies for isolation checks.

login

Automated: auth UI and session routes cover their respective layers.

Manual: Sign in, reload a company deep link, sign out, and revisit it. Confirm the browser requests authentication rather than showing cached company data. Test an invalid claim separately on disposable state.

invite-members

Automated: member UI and invite replay provide component and route evidence.

Manual: Accept an invite as the intended user, inspect the resulting company and permissions, then reuse and expire disposable invites. Change a member permission, reload as that member, and verify a denied operation on another company remains denied.

cli-authorization

Automated: board auth client and token commands cover the client contracts.

Manual: Authorize the intended CLI context, make a read-only company request, then revoke its token and retry. Verify failure is explicit and does not silently fall back to another identity.

Use auth login, auth whoami, and auth revoke-current with explicit context. Retry with the same bearer to prove revocation; deleting local credentials with logout alone does not establish that server revocation succeeded.

Gotchas

  • External assistants use their own browser/device consent and personal MCP grants. Human CLI tokens and agent bearer keys have separate authorization paths.
  • Settings visibility is not authorization; direct requests still need permission checks.
  • An agent bearer key must not gain another company’s access.
  • Never put invite tokens, session cookies, or API keys in verification evidence.

Storybook verification

login

Capability ID: access/login.

Scope: ui Storybook: Sign-in form, pending and invalid credentials, deployment-mode claim gate, expired claim. Production: Authenticate and reload company deep link; sign out and confirm session enforcement; reject invalid bootstrap claim. Sources: Source: Auth.tsx, BoardClaim.tsx, board-claim.ts. Tests: Auth.test.tsx, auth-session-route.test.ts, board-claim.test.ts

membership

Capability ID: access/membership.

Scope: ui Storybook: Member and join-request lists; editable versus read-only roles; pending change, rejected request, revoked invite. Production: Persist role/membership changes; enforce actual actor authority, invite replay/expiry and cross-company denial. Sources: Source: CompanyAccess.tsx, authz.ts. Tests: CompanyAccess.test.tsx, invite-accept-replay.test.ts, multi-user-authenticated.spec.ts

cli-auth

Capability ID: access/cli-auth.

Scope: ui Storybook: CLI authorization approval, pending, expired/denied and already-authorized states. Production: Authorize intended CLI identity/context, make scoped request, revoke current server token and retry same bearer; logout alone is insufficient. Sources: Source: CliAuth.tsx. Tests: cli-auth-routes.test.ts, board-auth.test.ts, token.test.ts