# AiMe Web Control Plane and RBAC Plan

Status: Draft plan; local protocol/runtime proofs in progress, no deployed control plane  
Last updated: 2026-08-14  
Scope: Managed multi-device and multi-user operation

## Purpose

This document defines the required web control plane for users who manage
multiple computers or allow other people to use selected AiMe profiles. It also
defines the separation between user, organization-admin, and platform-admin
authority.

The web control plane coordinates identity, membership, device presence,
profile sharing, connection authorization, revocation, and release policy. It
does **not** replace the local Windows policy boundary. The local AiMe app
remains authoritative for roots, capability ceilings, sensitive confirmation,
secrets, execution, process containment, and emergency stop.

## Prerequisite Go/No-Go gate

Phase 1 in [the delivery roadmap](ROADMAP.md) recorded a scoped `GO` after real
end-to-end evidence that ChatGPT Chat, not Work, discovered and called AiMe on
the Windows VM. This removes the investment hold, but does not waive the Phase
3 identity, tenant-isolation, deployment, or release gates. Login,
organizations, RBAC, sharing, admin pages, control-plane leases, and
multi-tenant infrastructure remain unimplemented.

## Operating modes

### Personal local mode

A user may run one independently configured computer/profile without creating
an AiMe web account where the selected ChatGPT transport permits it. Local mode
retains the same filesystem, process, audit, and revocation controls but has no
web sharing, organization management, or remote lost-device workflow.

### Managed mode

Managed mode requires an AiMe account and the web control plane. It supports:

- several computers under one account or organization;
- several profiles per computer;
- invitations and membership;
- time-bounded profile sharing and delegation;
- user, organization-admin, and platform-admin pages;
- remote device/profile/session revocation;
- release channels and minimum-version policy; and
- privacy-preserving security and operational metadata.

Managed mode does not grant the server access to local file, screen, clipboard,
prompt, or command-output content.

## Trust-boundary rule

```text
Web control plane: identity, requested policy, leases, routing, revoke
        |
        | signed/versioned policy and short-lived authorization
        v
Local AiMe app: final policy, confirmation, secrets, execution, kill
        |
        v
Approved Windows resource
```

The control plane can narrow or revoke local authority but cannot silently
widen it. A web-side permission is an upper-bound request; the effective
permission is the intersection of:

1. account and organization membership;
2. the profile share and its expiry;
3. the connection/session scope;
4. the local profile capability ceiling;
5. the current local confirmation policy; and
6. live local risk evaluation.

## Principal and resource model

| Entity | Purpose | Important boundary |
| --- | --- | --- |
| User | Human account used to sign in to the web app and authorize ChatGPT connections. | A user is not automatically authorized for any device. |
| Organization | Ownership and collaboration boundary for people, devices, profiles, policy, and billing/quota later. | Every tenant-owned row and token is bound to one organization ID. |
| Membership | User's organization role and lifecycle. | Role changes and removal revoke derived access. |
| Device | One independently identified AiMe installation. | Device key, lease, presence, and revoke are independent from other devices. |
| Profile | Local capability configuration on one device. | Server stores aliases and policy metadata, not native roots or secrets. |
| Profile share | Delegation from a profile owner to a user/group with a capability ceiling and expiry. | Never grants above the locally approved profile ceiling. |
| Connection | OAuth/transport binding between a ChatGPT identity/connection and an allowed profile or selection flow. | Must not assume caller identity unless cryptographically established. |
| Session lease | Short-lived authorization for one user, device, profile, and connection. | Cannot switch target or outlive membership/share/revoke. |
| Invitation | One-time, expiring request to join an organization or receive a profile share. | Acceptance alone does not bypass local share activation. |
| Release | Signed application version and rollout policy. | Signing private key is not held by the control plane or NAS. |
| Audit event | Allowlisted security/administrative metadata. | No local content, raw credential, or prompt is stored. |

## Authentication

### Human authentication

- Use a standards-based identity provider through OIDC/WebAuthn rather than
  designing custom password cryptography.
- Prefer passkeys and require MFA for organization owners, organization admins,
  and every platform-admin account.
- If email/password login is ever enabled, password storage and reset are
  delegated to the selected audited identity provider; AiMe does not store raw
  passwords.
- Web sessions use Secure, HttpOnly, appropriately scoped cookies, CSRF
  protection, rotation after authentication/role change, idle expiry, absolute
  expiry, and global session revoke.
- Login, MFA enrollment/reset, recovery, suspicious-session review, and account
  deletion have explicit user flows and audit events.

The identity provider is intentionally not selected in this document. Selection
requires a separate architecture decision covering exportability, self-hosting,
MFA/passkey support, tenant isolation, recovery, and operational burden.

### Device authentication and pairing

1. The local app generates a device key pair; private material stays protected
   on the device.
2. The web user creates a short-lived, single-use pairing request.
3. The local app displays and locally confirms the target account/organization
   and proposed device alias.
4. The device proves possession of its private key and receives a revocable,
   device-bound credential.
5. Re-pairing, ownership transfer, or organization transfer requires a new
   local confirmation and invalidates the former binding.

Pairing codes must be random, rate-limited, short-lived, bound to the intended
flow, and never auto-approved merely by opening a link while signed in.

Current implementation proves the protocol boundary with local authorities
behind one tested composition root. A separately signed local approval binds tenant, subject, device
public-key fingerprint, and one Read-profile revision. It is consumed once,
then an Ed25519 or ECDSA-P256 device challenge issues a revocable
algorithm-bound certificate; every reconnect requires a fresh proof. Tests
cover forged approvals, replay, expiry, capacity, revoke, algorithm mismatch,
and audit rollback. The composition root replays a bounded authenticated
append-only journal, hydrates the shared device-revocation fence, and binds
active credential IDs through leases and device sessions before admitting work.
Production still needs the approval signer bound to a real local confirmation
UI, protected persistent device keys, native or service-side durable storage,
multi-process coordination, and rollback-resistant operations.

The repository also has a separate local executable data-plane proof. A
five-minute signed Read lease binds tenant, subject, connection, device,
profile revision, and policy digest to one logical outbound device session.
It forwards bounded bidirectional JSON-RPC to a fresh instance of the existing
device-side MCP server and revalidates the lease per message. A bounded
Streamable HTTP relay now proves initialize, tool discovery/calls, Host/Origin
validation, pre-authentication admission/body caps, durable session-open audit,
session binding, and DELETE cleanup.
It also publishes protected-resource metadata, emits fixed OAuth-style
challenges, validates issuer/client/resource/scope/expiry, binds the verified
identity to the signed route lease, and rechecks leases in both message
directions. A standalone resource-server verifier now validates a strict,
short-lived RS256 access-token profile through a statically pinned bounded JWKS
fetch, including cache and key-rotation behavior. A matching local issuer
produces bounded five-minute RS256 access tokens and public-only JWKS output,
and a headless authorization-code authority enforces one-time codes, exact
client/resource binding, optional legacy redirect matching, and PKCE S256 before
returning an access grant.
The token-service seam then issues only the bound short-lived access token and
collapses code, replay, and binding failures into one sanitized response class.
The local public-application router now composes the authorization-server
metadata/JWKS, authorization, token, protected-resource, JWT-verification, and
MCP paths in one end-to-end Read test. Managed tool discovery advertises the
same global `aime.read` OAuth scheme in both required descriptor locations.
The MCP server rejects simultaneous managed tool security and Modify
configuration, so no managed Modify tool is exposed. Stdio independently
rejects Modify profiles. A separate
local device-wire stack now includes authenticated wire handoff,
authenticated session-to-hub binding, and bounded TCP/WSS carrier proofs over
real sockets. A narrow managed network host now places the public OAuth/MCP
router and authenticated device WebSocket gateway on one owned Node HTTP server
with bounded shutdown; it does not listen publicly, configure TLS, or own tenant
and authority state. A managed consumer gateway runtime now composes the host,
OAuth handlers, JWT verifier, MCP relay, signed lease issuance, and authority
runtime under one ordered lifecycle. Its route resolver may return only a
non-secret device/profile binding; verified access-token claims remain the sole
source of tenant, subject, and connection identity. There is still no durable
signing-key ring, production tenant resolver, login/consent UI, or deployed endpoint.
These local components do not establish durable tenant storage, public
HTTPS/WSS routing, or production authorization.

An unwired transactional PostgreSQL authorization-code adapter and migration now
implement atomic digest-only consume-on-attempt, independent approval replay
fences, fixed advisory-lock capacity serialization, bounded expiry/retention,
and strict row validation. Deterministic tests cover its transaction contract,
and an opt-in two-pool integration test covers one-winner redemption, replay,
and burn across reopen. That integration remains skipped until an explicit
disposable `AIME_TEST_POSTGRES_URL` is provided, so multi-process/restart proof
and production wiring are still required. Authorization-code state must not be
added to the device-local authority journal, whose serialization and tamper
evidence are only a single-process local proof.

### ChatGPT connection identity

AiMe must not assume that MCP stdio or a tunnel supplies verified ChatGPT user,
organization, or conversation identity. Multi-user sharing requires an
authenticated AiMe connection whose token is bound to the AiMe user,
organization, profile/selector, audience, scopes, expiry, and connection ID.

Managed consumer mode uses the separately threat-modeled AiMe OAuth/MCP relay
because private Secure MCP Tunnel onboarding would require each end user or
administrator to provision OpenAI Platform tunnel credentials manually. A
personal/developer deployment may still use a user-owned Secure MCP Tunnel.
Neither mode may fall back to a shared bearer token that makes recipients
indistinguishable.

The intended production data-plane seam keeps the gateway limited to verified
identity, lease, tenant, route, and resource controls. Tool schemas, root
capabilities, confirmations, filesystem/process enforcement, and final audit
remain authoritative on the selected device; the gateway must not reimplement
or widen them.

## Roles

### Organization roles

| Role | May do | May not do |
| --- | --- | --- |
| Owner | Manage organization lifecycle, admins, members, device ownership, shares, organization policy, and revoke. | Bypass local capability/confirmation or view local content. |
| Organization Admin | Manage members, invitations, managed devices, profile-share requests, policies, and organization audit metadata. | Delete/transfer the organization owner, become platform admin, or bypass local enforcement. |
| Member | Use profiles explicitly shared with them, view their own connections/sessions, and revoke their own access. | Manage other members/devices or grant onward access unless explicitly delegated. |
| Viewer | View explicitly allowed inventory/status and audit summaries. | Establish a tool session or use a profile. |

An organization may define custom groups later, but custom roles are deferred
until the fixed-role authorization matrix and tenant-isolation tests are proven.

### Profile-share permissions

A profile share is separate from an organization role. It includes:

- grantee user/group;
- device/profile IDs and display aliases;
- maximum capability level and explicit tool scopes;
- start and expiry times;
- session/concurrency limits;
- whether onward delegation is forbidden or explicitly bounded;
- local activation state and local policy version; and
- creator, reason, and revoke metadata.

The safe default is no onward delegation. Modify, Control, Full, and Admin are
not implied by organization ownership or administration.

### Platform roles

| Platform role | May do | Explicit prohibition |
| --- | --- | --- |
| Platform Support | View service health, redacted account/device aliases, entitlement status, and user-submitted diagnostics. | Impersonate users, retrieve tokens, or view local content. |
| Platform Security Admin | Suspend accounts/organizations, revoke connections/device credentials, inspect security-event metadata, and respond to incidents. | Send a command or widen a local capability. |
| Platform Operations Admin | Manage deployment, migrations, quotas, release rollout, and infrastructure health. | Read tenant local content or act as an organization member. |
| Platform Super Admin | Emergency management of platform-admin identities and critical configuration through break-glass procedure. | Routine support use or silent tenant impersonation. |

Platform roles are never inherited from organization roles. Platform-admin
accounts use separate authentication policy, mandatory MFA, short sessions,
strong audit, and no shared accounts.

## User-facing web areas

### User dashboard

- account security, active sessions, MFA/passkeys, recovery, and deletion;
- organizations and pending invitations;
- device/profile aliases, presence, version, connection state, and owner;
- profiles shared with the user and their capability ceilings/expiry;
- ChatGPT connection setup and revoke;
- the user's current and recent session metadata;
- device/profile/share revoke available to the authorized owner; and
- release channel and update status where policy allows user selection.

### Organization administration

- organization settings and ownership;
- members, roles, groups later, invitations, and removals;
- managed devices and profiles;
- pending and active profile shares/delegations;
- organization-wide maximum capability and sharing policy;
- version-compliance and revoke policy;
- tenant-scoped security/audit metadata; and
- export/deletion workflow.

### Platform administration

- users and organizations by stable identifier and redacted display metadata;
- account/organization status, suspension, and revoke;
- device/version/tunnel aggregate health;
- package/channel/rollout and minimum supported version;
- quotas/entitlements if introduced;
- security alerts and immutable admin-action audit;
- deployment/migration status; and
- support cases containing only user-submitted, redacted diagnostics.

Platform Admin does not provide a file browser, screen viewer, prompt viewer,
raw command console, token viewer, or generic device-control endpoint.

## Sharing flow

1. An authorized owner/admin selects an existing profile alias.
2. The web app displays the current local capability ceiling and asks for the
   grantee, explicit scopes, expiry, and limits.
3. The control plane creates a `pending_local_activation` share.
4. The local app fetches the signed/versioned policy proposal and displays the
   recipient, scopes, expiry, and effect.
5. The local owner approves or denies. A future locally configured delegation
   rule may auto-approve only a pre-authorized Read ceiling and bounded expiry.
6. The device acknowledges the accepted policy version.
7. The grantee establishes their own authenticated ChatGPT connection and
   receives short-lived session authority.
8. Web revoke, local revoke, membership removal, expiry, device revoke, or
   policy downgrade invalidates the next call and active leases.

The web UI must never claim that a share is active until the intended device has
acknowledged the policy version.

## Policy synchronization and failure behavior

- Policy objects are versioned, signed/authenticated, replay-resistant, and
  monotonic per device/profile.
- Devices poll over outbound HTTPS and never accept inbound control-plane
  connections.
- Authorization uses short-lived leases. Missing renewal, control-plane revoke,
  invalid signature, clock uncertainty beyond tolerance, policy-version
  conflict, or tenant mismatch fails closed.
- The strict initial policy stops remote tool execution when the managed control
  plane is unavailable beyond the documented lease window. Local emergency
  stop, revoke, uninstall, and local-only diagnostics remain available.
- A stale Online state is never represented as proof that the device is
  callable. Presence and successful data-plane readiness are distinct.
- Control-plane recovery never restores a removed share or older broader policy
  without a new valid authorization.

## Tenant isolation requirements

- Tenant ID is derived from authenticated server context, never trusted from a
  client-supplied request field alone.
- Every tenant-owned database row, cache key, object path, job, event, token,
  and audit query is tenant-bound.
- Object-level authorization is checked after route-level authentication.
- IDs are unguessable but are not treated as authorization.
- Invitations, pairing codes, OAuth requests/codes, refresh tokens, and revoke
  handles are single-use or rotated and have bounded lifetime.
- Cross-tenant exports, search, analytics, support access, background jobs, and
  error handling receive explicit negative tests.
- Database administrative access does not imply application-level permission;
  operational access is minimized and audited.

## Data minimization and retention

The control plane may store:

- account identity and security state;
- organization/membership/invitation records;
- device/profile aliases and minimal configuration metadata;
- capability ceilings, share policy, versions, and revocation state;
- connection/session identifiers and bounded operational status;
- release/update compliance; and
- allowlisted security and administrative audit metadata.

It does not store local absolute paths, file contents, screenshots, clipboard,
raw prompts, command output, browser content, reusable raw device private keys,
or unredacted bearer credentials. Retention and deletion periods must be defined
before public use, with shorter defaults for session and presence metadata.

## Required audit events

- login success/failure, MFA/recovery change, session create/revoke;
- organization/member/role/invitation lifecycle;
- device pairing, transfer, credential rotation, and revoke;
- profile publication, share request, local activation, use, expiry, and revoke;
- ChatGPT connection/OAuth lifecycle;
- platform-admin view/change/suspend/revoke/release actions;
- policy sync conflicts and tenant-isolation denials; and
- update-channel, rollout, and minimum-version changes.

Audit records contain stable IDs/aliases and reason codes, not local content or
credential values.

## Security acceptance gate

Managed multi-user operation may ship only when:

1. authentication, MFA, recovery, CSRF, session rotation, and global logout pass;
2. the complete organization/profile/platform authorization matrix passes;
3. automated cross-tenant tests return zero unauthorized rows, objects, jobs,
   events, tokens, exports, or audit data;
4. a pending web share cannot be used before local activation;
5. downgrade, expiry, removal, suspension, and revoke fail the next call closed;
6. a control-plane outage, stale policy, replay, or reordered event cannot widen
   authority;
7. Platform Admin cannot retrieve local content/credentials or send a command;
8. pairing and OAuth device/login-link CSRF and replay tests pass;
9. backup/restore preserves tenant boundaries and revoke state; and
10. no Critical or High finding remains for the managed control plane.

## Open architecture decisions

- Human identity provider and account-recovery model.
- Database, migration, and tenant-isolation enforcement pattern.
- Whether OpenAI Secure MCP Tunnel can satisfy per-user managed connections or
  a separately threat-modeled OAuth/MCP relay is required.
- Lease duration and the exact offline failure window.
- Whether low-risk Read sharing may use a locally pre-authorized delegation rule.
- Whether organization billing/quota is ever needed.

Deployment and update operations are defined in
[the deployment and update plan](DEPLOYMENT_AND_UPDATE_PLAN.md).
