Invitation Access

Invitation Access is the collaborator onboarding flow used by Uhpenry when a project owner wants to grant a user read-only collaborator access on the owner's repository (e.g., GitHub). It is a sub-type of the Standard access model and is purpose-built to be fast, auditable, and owner-respecting.

Key characteristics:

• One-time, user-initiated: the user generates a request key after completing the Snapcharge.
• Isolated: the request key is stored independently from Snapcharges and Snapshots (separate DB collection) to keep entitlement history immutable while allowing operational control.
• Automated: Uhpenry automates the owner-invite + user-accept flow so users don't wait for manual invitations.
• Security-first: tokens and provider credentials are short-lived and never persisted beyond their operational need.

---

Goals & Rationale

1. User intent & accountability: We request that user explicitly generate the request key as to show the user's intent to join as a collaborator.
2. Automated, low-latency flow: We have automated the acceptance by avoiding manual action by both the owner (sending the invitation request) and user (accepting the invitation request) while preserving the provider's authorization model.
3. Auditability: We store lifecycle events, messages, and metrics in a request key document for support and dispute resolution.
4. Safety: We never grant more than read-only access, owner retains the ability to elevate permissions directly on the provider (Github).

---

Invitation Access: Process Types & States

Types (type)

These define how a user can become a collaborator on a project:

• self: The owner allows users to add themselves as collaborators immediately, without any approval.
• approve: Users request access, but the owner must manually approve before they become collaborators.
• payment: Access is triggered automatically after a successful payment. Not selectable by the owner, handled internally. Even if the invitation is self or approve, once a valid payment occurs, access is granted automatically.

---

Process States (process)

These track the current status of a collaboration request:

• pending: Request has been created but not yet accepted.
• accepted: Owner has approved the invite, but repository join may still be pending verification.
• rejected: Invite was rejected or expired.
• joined: User has successfully joined as a verified collaborator.
• removed: Access revoked or removed by the owner.

Important: All transitions are append-only. This ensures a complete historical record so the platform can rebuild every step, audit activity, and verify entitlement.

---

Security & Operational Guarantees

• Short-lived tokens only: provider tokens from the user's session are never persisted. Use them only to accept the specific invitation, then discard.
• Minimal scopes: owner tokens used to create invitations must be scoped to only the actions required (invite/collaborator management) and stored encrypted.
• Idempotency & deduplication: creating multiple request keys for the same (userId, projectId) isn't allowed both on Server-side and Client-side.
• Validation prior to invite: confirm Snapcharge completeness and Snapshot persistence before creating an invitation.

---

Cooldowns, Revocation & Policies

• Cooldown: default 24 hours (1440 minutes). If a request key is rejected or revoked, respect the cooldown before allowing another request generation.
• Revocation: owner or platform can set state.status = 'revoked'. This denies further action and appends history. If revoked after joined, platform will remove local references but cannot reverse the provider-level collaborator removal; owner must remove user on provider.
• Tombstoning: use deleted for housekeeping while preserving historical records for audits and disputes.

Invitation Access in Uhpenry provides a secure, auditable, and automated way for users to gain read-only collaborator access to a project repository. By combining Snapgate, Snapcharge, and Request Key flows, the platform ensures that access is intentional, verifiable, and governed by the owner's policies.

This model balances user autonomy (self-add) with owner control (approve/payment flows), while maintaining a complete, append-only history for auditability and dispute resolution. With short-lived tokens, minimal scopes, and enforced cooldowns, Invitation Access upholds the platform's security-first philosophy, enabling seamless collaboration without compromising integrity or operational safety.

In short, it guarantees that every collaborator access is tracked, validated, and revocable, aligning with Uhpenry's broader mission of trusted, gated distribution of project artifacts.

Note: This guide is living documentation. We welcome contributions and corrections via GitHub or support@uhpenry.com.