Snapgate

A Snapgate is the secure entry point to a specific entity (project/application/solution) for a specific user. It is account‑bound, uniquely identifying the user ↔ entity access relationship, and it is the place where terms are accepted, access is granted, and enforcement (revoke/suspend) is executed.

Rule of thumb: Snapgate decides, Snapcharge records, Snapshot preserves.

Snapgate does not perform payment verification itself. Instead, it orchestrates access and policy while delegating transactional recording and cryptographic verification to Snapcharge. The resulting history is aggregated in a Snapshot.

Core Responsibilities

1. Access Orchestration Create a per-user, per-entity gate through which downloads or invitations are executed.

2. Terms & Policy Attestation Capture explicit acceptance of license terms and booth policies, with a timestamp.

3. Moderation & Enforcement Allow owners to revoke, suspend, or flag access on violations (e.g., redistribution, account sharing).

4. Telemetry for Trust Record environment signals (user agent, coarse location) to detect anomalous access patterns.

5. Transaction Context Maintain linkage to all Snapcharges created under this gate, including success/failure summaries.

When is a Snapgate created?

A Snapgate is created the first time a user attempts to access an entity and acknowledges the terms. Subsequent access to the same entity by the same user reuses the existing Snapgate (idempotent by userId + productId + type).

Snapgate Flow

1. Discover Project

   • A user browses Uhpenry and finds a project they want access to.

2. Generate Secure Snapgate

   • Before proceeding, the user is presented with the Snapgate terms.

   • After accepting, Uhpenry generates a secure Snapgate instance for that user/project context.

   • This Snapgate lives at a URL like:

     /Snapgates/{entity_type:projects}/{path}

3. Complete Snapcharge (Payment)

   • On the Snapgate, the user initiates and completes a Snapcharge transaction (payment, license, or verification step).
   • The Snapcharge is cryptographically bound to that Snapgate instance.

4. Access Granted

   • Once the Snapcharge is confirmed, Uhpenry records the completed transaction.
   • The Snapgate transitions into a state where the user is authorized.
   • The user gains access to the project content gated by that Snapgate.

Flow Diagram

Data Model (Developer Reference)

Field names reflect the current schema you provided; grouped for clarity.

// Snapgates
{
  // Ownership & linking
  userId: Id<'users'>,
  boothId: Id<'booths'>,
  productId: Id<'projects'>, 
  type: 'projects',

  // Operational
  SnapchargeIds: Id<'Snapcharges'>[],
  summary: {
    success: Id<'Snapcharges'>[],
    failed: Id<'Snapcharges'>[],
  },
  snapshotId?: Id<'Snapshots'>,

  // Attestations
  agreements: {
    understandTerms: boolean,
    readTerms: boolean,
    date: number, // timestamp when terms were accepted
  },

  // Moderation & policy
  violationCount?: number,
  violation?: Violation,          // latest violation object
  history?: Violation[],          // prior violations (append‑only)
  violationType?: 'revoke' | 'suspend' | 'violation',
  status: 'good_standing' | 'poor_standing' | 'bad_standing',
  active: 'enabled' | 'disabled',

  scheduleId?: Id<'_scheduled_functions'>,

  ...
}

Terms & Policy Attestation

Before a Snapgate is created, the user must explicitly accept the project license and booth terms. The result is captured in agreements with a timestamp.

Enforcement & Moderation

Owners (and, when necessary, the platform) can:

• Suspend temporarily disallow use of the Snapgate (active = 'disabled'), retaining history.
• Revoke permanently disable access and set status accordingly (e.g., 'bad_standing').
• Report as Violation Owners can report behavior or activity that breaks the rules. Reported users may temporarily lose access to booth projects, and repeat or serious cases can lead to platform-level restrictions after review.

Each enforcement action should be mirrored by a follow‑up Snapcharge that captures the effective state on the user side (e.g., access locked for downloads). This ensures the Snapshot's audit trail reflects what the user actually experienced.

Signals considered (examples):

• Location mismatch: purchases/downloads from disparate regions in short windows.
• Unusual UA churn: rapidly changing user agents suggesting shared credentials.
• Excessive downloads: rate limit triggers.

Enforcement actions must be proportionate and auditable store evidence references in the violation record.

Visibility & Privacy

Snapgate visibility controls who may view the gate's high‑level record and associated history:

• private only the user (and platform admins).
• member user + owner team members assigned to the booth/project.
• public anyone with the link (rare; used for public attestations or open resources under Snapshot).

Interactions with Snapcharge & Snapshot

• Snapcharge: Every successful (or terminal) access event under a Snapgate is recorded as a Snapcharge. The Snapgate's summary.success/failed enables quick status views without expanding the full history.
• Snapshot: The Snapshot aggregates serialized copies of the Snapgate and all Snapcharges to preserve point-in-time truth and enable verification.

Operational Invariants

• Uniqueness: One Snapgate per (userId, productId, productType) tuple. Treat creation as idempotent.
• Persistence: Snapgates are not deleted. Standing/activation change, history grows.
• Precondition: No Snapcharge should be created unless agreements.date is set.
• Mirroring: Any enforcement with user impact must be mirrored by a Snapcharge.

Where Snapgate Fits

The Snapgate serves as the secure, account-bound checkpoint for user access to projects, applications, or solutions within Uhpenry. By combining terms attestation, access orchestration, and enforcement capabilities, Snapgate ensures that every interaction is explicitly authorized, auditable, and enforceable.

While Snapgate decides access and enforces policy, it works in tandem with Snapcharge (which records transactional and state events) and Snapshot (which preserves the serialized history). This triad provides a tamper-evident, append-only record of all user interactions, enabling trust, accountability, and compliance, without requiring users to manage the complexity of payment verification or cryptographic proofs themselves.

In essence, Snapgate is the first line of trust, governing how, when, and under what conditions users can interact with content, while preserving a complete historical audit trail for security, disputes, and future verification.

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