Allocation Project SSH Access v1¶

Purpose: - Define how project members can gain SSH access to a live allocation without private key sharing. - Separate personal SSH-key management from project-scoped allocation access. - Establish the first product and authz model for team handoff on allocations.

Inputs: - doc/product/Allocation_Experience_Gaps_v1.md - doc/api/openapi.draft.yaml - packages/services/auth/ - cmd/api/routes.go

Related: - doc/product/Allocation_Restart_Model_v1.md - doc/product/Allocation_Storage_Model_v1.md

1. Executive Summary¶

The platform currently supports: - personal/public SSH-key registration - project-scoped SSH keys - allocation-level SSH-key attachment updates

That is not yet enough for the real collaboration need: - a different project member should be able to gain SSH access to a live allocation with their own public key, without the original owner sharing a private key

The first correct model is: - allocation access remains project-scoped - the granted user contributes their own public key material - authorized actors manage allocation access grants explicitly - every access-change is audited

This should be a distinct product surface, not an extension of personal-key defaults alone.

2. Problem Statement¶

Today, if user A owns an allocation and user B needs to use it later: - user A can swap their own attached public keys - but user B cannot independently attach their own access to that allocation through a clean project flow

That leads to bad workarounds: - sharing a private key - copying public keys through out-of-band shell access - asking an admin to intervene

None of those are acceptable as the normal collaboration path.

3. Product Boundary¶

3.1 Personal SSH keys¶

Personal SSH keys are: - user-scoped - registered by an individual - used for their own direct access defaults and allocation attachment choices

3.2 Project-scoped allocation access¶

Project-scoped allocation access is: - collaboration state for a live allocation - based on project membership and role - not equivalent to a user’s personal default-key choice

The platform should not blur these two concepts.

4. First-Version Product Decision¶

The first team-access model should work like this:

Every user still registers their own public keys.
An authorized actor grants project-member access to a live allocation.
The platform attaches the granted member’s chosen public key(s) to that allocation.
The node reconciles the allocation runtime user’s authorized_keys set.

This means: - no private key sharing - no impersonation - no platform need to store anyone’s private key

5. Authz Model¶

Recommended first rule: - allocation owner may grant/revoke project-member SSH access - project admins may grant/revoke project-member SSH access - platform admins retain override capability

Users who are merely project members but not allocation owner or project admin: - should not automatically control access grants for someone else’s live allocation in the first slice

This keeps the first model simple while still solving handoff.

6. Membership Requirements¶

To be granted access, the target user must: - have active tenant membership in the same tenant - have active project membership in the same project - have at least one registered public SSH key

The platform should reject access grants if: - the target user is outside the project - the target user has no registered public key - the target user’s relevant key is revoked

7. Data Model Direction¶

The first clean model likely needs an explicit access-grant record rather than overloading the allocation-owner SSH-key list forever.

Conceptually: - allocation_access_grant - allocation_id - grantee_user_id - granted_by_user_id - ssh_key_ids or resolved key references - created_at - revoked_at

The existing allocation SSH-key material can still be the runtime projection, but the collaboration source-of-truth should not just be “whatever keys happen to be attached.”

That distinction matters for: - auditability - revocation - explaining who has access and why

8. Runtime Reconcile Model¶

The runtime should derive the effective authorized_keys set for the allocation from: - owner-attached keys - active project-member access grants

Then it should reconcile the node runtime user state asynchronously, just as the platform already does for allocation key updates.

This keeps the runtime model additive and bounded.

9. UX Direction¶

Allocation detail should gain an explicit section such as: - SSH Access

That section should show: - owner-attached keys - granted project members - which public keys are active for each granted member - who granted access - revoke action where authorized

The first user flow should be: 1. open allocation detail 2. choose Grant project member access 3. select a project member 4. choose one or more of that member’s public keys 5. save

The UI should explain clearly: - the user will authenticate with their own private key corresponding to the granted public key - the platform never shares private keys between users

10. Audit Requirements¶

Every mutation must write audit logs including: - actor - grantee - allocation - granted/revoked key identifiers - result - correlation ID

Required auditable actions: - access grant create - access grant update - access grant revoke

This is important both for security and for team supportability.

11. Out of Scope for First Slice¶

Not in the first collaboration slice: - approval workflows - temporary time-boxed access grants - cross-project or cross-tenant access - group-based access grants - sharing whole login sessions - platform handling anyone’s private key material

Those can come later if needed.

12. Open Questions¶

Should the first version allow the owner to choose from the grantee’s existing personal keys only, or should project-scoped keys also be supported in the same flow?
Should a granted member be allowed to revoke only their own access, or only owner/admin can do that?
Should grants survive allocation restart automatically? The recommended answer is yes.
Should grants remain visible on a decommissioned allocation for audit/history, even though runtime access is gone? The recommended answer is yes.

13. Decision Summary¶

The correct collaboration model is: - personal keys stay personal - project membership gates who may be granted access - authorized actors grant or revoke allocation access explicitly - granted users authenticate with their own private keys - the platform only manages public-key attachment and runtime reconcile

That solves team handoff without crossing the private-key boundary.